feat(WorkList): New Study List (WorkList based on ui-next); old study list renamed to LegacyWorklist (#6005)

---------

Co-authored-by: Dan Rukas <dan.rukas@gmail.com>
Co-authored-by: Bill Wallace <wayfarer3130@gmail.com>
This commit is contained in:
authored and GitHub committed 2026-05-28 12:26:30 -04:00
1 parent 9e7a3586ce
commit daae4c144e
121 files changed
+8071 -1468

No files matched your search

+12 -1
View File
@@ -1,4 +1,15 @@
import useDebounce from './useDebounce';
import useSearchParams from './useSearchParams';
import { useStudyListStateSync } from './useStudyListStateSync';
import { useSeriesFetch } from './useSeriesFetch';
import { useWorkListToolbarActions } from './useWorkListToolbarActions';
import { useStudyListQuery } from './useStudyListQuery';
export { useDebounce, useSearchParams };
export {
useDebounce,
useSearchParams,
useStudyListStateSync,
useSeriesFetch,
useWorkListToolbarActions,
useStudyListQuery,
};
+12 -1
View File
@@ -1,4 +1,15 @@
import useDebounce from './useDebounce';
import useSearchParams from './useSearchParams';
import { useStudyListStateSync } from './useStudyListStateSync';
import { useSeriesFetch } from './useSeriesFetch';
import { useWorkListToolbarActions } from './useWorkListToolbarActions';
import { useStudyListQuery } from './useStudyListQuery';
export { useDebounce, useSearchParams };
export {
useDebounce,
useSearchParams,
useStudyListStateSync,
useSeriesFetch,
useWorkListToolbarActions,
useStudyListQuery,
};
+204
View File
@@ -0,0 +1,204 @@
import { useCallback, useEffect, useRef, useState } from 'react';
import { useAppConfig } from '@state';
import { utils } from '@ohif/core';
import { thumbnailNoImageModalities } from '@ohif/core/src/utils/thumbnailNoImageModalities';
import {
PreviewThumbnailStatusState,
type PreviewThumbnailStatus,
type StudyRow,
} from '@ohif/ui-next';
// A series row carries arbitrary DICOM fields plus the thumbnail status this
// panel tracks. Only the latter is typed; the rest stays open.
type PreviewSeries = Record<string, any> & { thumbnailStatus: PreviewThumbnailStatus };
// Series rows may carry the UID under either casing depending on the data
// source; read it through one place so callers can't forget a variant.
function getSeriesUID(row: Record<string, any>): string | undefined {
return row.seriesInstanceUid || row.SeriesInstanceUID;
}
/**
* Runs `worker` over `items` with at most `maxParallel` in flight at once,
* stopping early if `signal` aborts. A shared cursor hands each worker the
* next item, so a slow fetch doesn't hold up the rest.
*/
async function runThumbnailPool<T>(
items: T[],
maxParallel: number,
signal: AbortSignal,
worker: (item: T) => Promise<void>
): Promise<void> {
let nextIndex = 0;
const runWorker = async () => {
while (!signal.aborted) {
const idx = nextIndex++;
if (idx >= items.length) {
return;
}
await worker(items[idx]);
}
};
await Promise.all(Array.from({ length: Math.min(maxParallel, items.length) }, runWorker));
}
/**
* Fetches the series for the selected study and, where applicable, their
* thumbnails, exposing the resulting list and an image-error handler.
*
* Owns the blob-URL lifecycle for thumbnails produced by the `fetch` strategy:
* every created `blob:` URL is tracked and revoked on study change / unmount,
* and `onThumbnailImageError` revokes a single failed thumbnail's URL.
*/
export function useSeriesFetch({
dataSource,
selected,
}: {
dataSource: any;
selected: StudyRow | null;
}): {
series: PreviewSeries[];
onThumbnailImageError: (seriesUID: string) => void;
} {
const [series, setSeries] = useState<PreviewSeries[]>([]);
// Blob URLs created by this panel (via the `fetch` thumbnail strategy).
// Tracked so we can URL.revokeObjectURL them on study change / unmount —
// otherwise every fetched series leaks one blob worth of memory.
const ownedBlobUrlsRef = useRef<string[]>([]);
const [appConfig] = useAppConfig();
const { sortBySeriesDate } = utils as any;
useEffect(() => {
// Drives cancellation when the selection changes or the panel unmounts: stops the
// worker pool from scheduling new fetches and aborts in-flight requests that honor
// AbortSignal (the `fetch` thumbnail strategy; the bulkDataURI XHR path cannot abort).
const abortController = new AbortController();
const { signal } = abortController;
const run = async () => {
const studyInstanceUID = (selected as any)?.studyInstanceUid;
if (!studyInstanceUID) {
setSeries([]);
return;
}
try {
const seriesList = await dataSource.query.series.search(studyInstanceUID);
if (signal.aborted) {
return;
}
const sortedSeriesList = sortBySeriesDate?.(seriesList) ?? [];
const normalizedSeriesList = sortedSeriesList.map(row => {
const modality = String(row.modality || row.Modality || '').toUpperCase();
const thumbnailStatus: PreviewThumbnailStatus = thumbnailNoImageModalities.includes(
modality
)
? { status: PreviewThumbnailStatusState.NotApplicable }
: { status: PreviewThumbnailStatusState.Loading };
return {
...row,
thumbnailStatus,
};
});
setSeries(normalizedSeriesList);
const fetchTargets = normalizedSeriesList.filter((row: PreviewSeries) => {
if (!getSeriesUID(row)) {
return false;
}
return row.thumbnailStatus?.status !== PreviewThumbnailStatusState.NotApplicable;
});
// Bound parallel thumbnail fetches so studies with many series don't
// saturate the connection and stall later viewer navigation. Mirrors
// CS3D's imageLoadPoolManager.maxNumRequests.thumbnail.
const maxParallelRequests = Math.max(1, appConfig?.maxNumRequests?.thumbnail ?? 5);
const fetchThumbnail = async (row: (typeof fetchTargets)[number]) => {
const seriesUID = getSeriesUID(row);
let src: string | null = null;
try {
const getThumbnailSrc = dataSource?.retrieve?.getGetThumbnailSrc?.(
{ StudyInstanceUID: studyInstanceUID, SeriesInstanceUID: seriesUID },
undefined
);
src = (await getThumbnailSrc?.({ signal })) ?? null;
} catch {
src = null;
}
// Track ownership of blob URLs before the abort check so URLs that
// arrive just after abort are still revoked on cleanup.
if (src?.startsWith('blob:')) {
ownedBlobUrlsRef.current.push(src);
}
if (signal.aborted) {
return;
}
setSeries(prev =>
prev.map(seriesItem => {
if (getSeriesUID(seriesItem) !== seriesUID) {
return seriesItem;
}
return {
...seriesItem,
thumbnailStatus: src
? { status: PreviewThumbnailStatusState.Ready, src }
: { status: PreviewThumbnailStatusState.NotAvailable },
};
})
);
};
await runThumbnailPool(fetchTargets, maxParallelRequests, signal, fetchThumbnail);
} catch (e) {
if (!signal.aborted) {
console.warn('Failed to load preview series/thumbnails for selected study.', e);
setSeries([]);
}
}
};
void run();
return () => {
abortController.abort();
// Revoke blob URLs this run created. Safe even though the old series
// may still be in the DOM briefly: revokeObjectURL only invalidates
// future loads, the already-rendered <img> keeps its pixels.
const urls = ownedBlobUrlsRef.current;
ownedBlobUrlsRef.current = [];
urls.forEach(url => {
try {
URL.revokeObjectURL(url);
} catch {}
});
};
}, [dataSource, selected, appConfig?.maxNumRequests?.thumbnail]);
const onThumbnailImageError = useCallback((seriesUID: string) => {
setSeries(prevSeriesList =>
prevSeriesList.map(seriesItem => {
if (getSeriesUID(seriesItem) !== seriesUID) {
return seriesItem;
}
const thumbnailStatus = seriesItem.thumbnailStatus as PreviewThumbnailStatus | undefined;
if (
thumbnailStatus?.status === PreviewThumbnailStatusState.Ready &&
thumbnailStatus.src?.startsWith('blob:')
) {
try {
URL.revokeObjectURL(thumbnailStatus.src);
} catch {}
}
return {
...seriesItem,
thumbnailStatus: { status: PreviewThumbnailStatusState.NotAvailable },
};
})
);
}, []);
return { series, onThumbnailImageError };
}
@@ -0,0 +1,182 @@
import React, { useCallback, useEffect, useState } from 'react';
import { useLocation, useParams } from 'react-router';
import { Enums, log } from '@ohif/core';
import { Button } from '@ohif/ui-next';
import { shallowEqualIgnoringArrayOrder } from '../utils/shallowEqualIgnoringArrayOrder';
import { URL_KEYS, getUrlParam } from '../utils/studyListFilterContract';
const DEFAULT_DATA = {
studies: [],
queryFilterValues: null,
};
/**
* Queries the data source for the study list and manages the result lifecycle:
* refetch-on-filter-change, loading / first-fetch flags, and surfacing
* connection errors (a modal with a Retry action). Pagination changes do not
* trigger refetches — the study list paginates client-side.
*
* `refresh` invalidates the cached result and re-arms the first-fetch gate,
* causing the next render to re-query. It also clears the loading flag, so the
* caller can use it as the single reset when the active data source changes.
*/
export function useStudyListQuery({
dataSource,
isDataSourceInitialized,
servicesManager,
}: {
dataSource: any;
isDataSourceInitialized: boolean;
servicesManager: AppTypes.ServicesManager;
}): {
studies: any[];
isLoading: boolean;
hasFetchedOnce: boolean;
refresh: () => void;
} {
const location = useLocation();
const params = useParams();
const [data, setData] = useState(DEFAULT_DATA);
const [isLoading, setIsLoading] = useState(false);
const [hasFetchedOnce, setHasFetchedOnce] = useState(false);
const refresh = useCallback(() => {
setIsLoading(false);
setHasFetchedOnce(false);
setData(DEFAULT_DATA);
}, []);
useEffect(() => {
if (!isDataSourceInitialized) {
return;
}
// Per-data-source result cap, passed to servers that honor the `limit`
// query parameter. Defaults to 101 when the data source doesn't set it.
const studiesLimit = dataSource.getConfig?.()?.queryLimit ?? 101;
const queryFilterValues = _getQueryFilterValues(location.search, studiesLimit);
// 204: no content
async function getData() {
setIsLoading(true);
log.time(Enums.TimingEnum.SEARCH_TO_LIST);
try {
const studies = await dataSource.query.studies.search(queryFilterValues);
setData({
studies: studies || [],
queryFilterValues,
});
log.timeEnd(Enums.TimingEnum.SCRIPT_TO_VIEW);
log.timeEnd(Enums.TimingEnum.SEARCH_TO_LIST);
} catch (e) {
console.error(e);
// Record that we attempted these filter values even though the fetch
// failed. Without this, the effect's `filtersChanged` check would
// remain true on the next render and immediately retry the same
// failing query in a tight loop.
setData(prev => ({ ...prev, queryFilterValues }));
// If there is a data source configuration API, the Worklist will pop
// up its own dialog to attempt to configure it. Otherwise surface the
// failure via a modal with a Retry action.
const { configurationAPI, friendlyName } = dataSource.getConfig();
if (!configurationAPI) {
const { uiModalService } = servicesManager.services;
uiModalService.show({
title: 'Data Source Connection Error',
content: () => (
<div className="text-foreground">
<p className="text-red-600">Error: {(e as Error).message}</p>
<p>
Please ensure the following data source is configured correctly or is running:
</p>
<div className="mt-2 font-bold">{friendlyName}</div>
<div className="mt-4 flex justify-end">
<Button
onClick={() => {
uiModalService.hide();
refresh();
}}
>
Retry
</Button>
</div>
</div>
),
});
}
} finally {
setIsLoading(false);
setHasFetchedOnce(true);
}
}
// Refetch when the filter set has actually changed. Filters can include
// array-valued fields like `modalitiesInStudy` whose element order
// doesn't matter, so we compare with an unordered-array shallow equal
// rather than reference equality — otherwise a re-render that
// re-creates the array with the same contents would force a refetch.
// Pagination changes alone don't invalidate the data (we paginate
// client-side).
const filtersChanged = !shallowEqualIgnoringArrayOrder(
data.queryFilterValues,
queryFilterValues
);
const isDataInvalid = !isLoading && filtersChanged;
if (isDataInvalid) {
getData();
}
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [data, location, params, isLoading, dataSource, isDataSourceInitialized]);
return {
studies: data.studies,
isLoading,
hasFetchedOnce,
refresh,
};
}
/**
* Translates the URL query string into the filter shape expected by the
* data source (`patientId`, `patientName`, `modalitiesInStudy`, …).
*
* URL keys come from the centralized contract in `studyListFilterContract.ts`,
* which is also what WorkList's URL serializer writes — so the read/write
* sides can't drift.
*
* @param {*} query - URL search string or `URLSearchParams`
*/
function _getQueryFilterValues(query, queryLimit) {
const params = new URLSearchParams(query);
const modalities = getUrlParam(params, URL_KEYS.modalities);
const queryFilterValues = {
// DCM
patientId: getUrlParam(params, URL_KEYS.mrn),
patientName: getUrlParam(params, URL_KEYS.patientName),
studyDescription: getUrlParam(params, URL_KEYS.description),
modalitiesInStudy: modalities ? modalities.split(',') : null,
accessionNumber: getUrlParam(params, URL_KEYS.accession),
//
startDate: getUrlParam(params, URL_KEYS.startDate),
endDate: getUrlParam(params, URL_KEYS.endDate),
// Rarely supported server-side
sortBy: getUrlParam(params, URL_KEYS.sortBy),
sortDirection: getUrlParam(params, URL_KEYS.sortDirection),
// So many different servers out there that we can't rely on them to support offset/limit.
// So we just query for everything up to the queryLimit for those that support it.
// For those that don't we will just assume we get everything back.
offset: 0,
limit: queryLimit,
};
// Delete null/undefined keys
Object.keys(queryFilterValues).forEach(
key => queryFilterValues[key] == null && delete queryFilterValues[key]
);
return queryFilterValues;
}
@@ -0,0 +1,219 @@
import * as React from 'react';
import { useMemo, useState } from 'react';
import { useNavigate, useLocation } from 'react-router-dom';
import type { SortingState, PaginationState, ColumnFiltersState } from '@tanstack/react-table';
import qs from 'query-string';
import useSearchParams from './useSearchParams';
import useDebounce from './useDebounce';
import {
useSessionStorage,
COLUMN_IDS,
TEXT_FILTER_COLUMN_IDS,
type StudyDateRangeFilter,
} from '@ohif/ui-next';
import { preserveQueryStrings } from '../utils/preserveQueryParameters';
import {
URL_KEYS,
getUrlParam,
urlKeyForTextFilter,
} from '../utils/studyListFilterContract';
export type StudyListState = {
sorting: SortingState;
pagination: PaginationState;
filters: ColumnFiltersState;
dataSources?: string;
};
/**
* Hook that syncs study list table state (sorting, pagination, filters) between:
* - URL query parameters (source of truth, takes precedence)
* - Session storage (fallback/persistence)
* - Component state (for reactivity)
*/
export function useStudyListStateSync() {
const navigate = useNavigate();
const location = useLocation();
const searchParams = useSearchParams({ lowerCaseKeys: true });
const [sessionState, updateSessionState] = useSessionStorage({
key: 'studyList.tableState',
defaultValue: {},
clearOnUnload: true,
});
const [pagination, setPagination] = useState<PaginationState>(
sessionState.pagination || parsePaginationFromURL(searchParams)
);
const [filters, setFilters] = useState<ColumnFiltersState>(
sessionState.filters || parseFiltersFromURL(searchParams)
);
const [sorting, setSorting] = useState<SortingState>(
sessionState.sorting || parseSortingFromURL(searchParams)
);
const dataSources = sessionState.dataSources || getUrlParam(searchParams, URL_KEYS.dataSources);
const state = useMemo(
() => ({ sorting, pagination, filters, dataSources }),
[sorting, pagination, filters, dataSources]
);
// Debounce state for URL updates
const debouncedState = useDebounce(state, 200);
// Sync to sessionStorage on state change
React.useEffect(() => {
updateSessionState(state);
}, [state, updateSessionState]);
// Sync to URL on debounced state change
React.useEffect(() => {
const query = buildQueryFromState(debouncedState);
const newSearch = query ? `?${query}` : '';
// Only navigate if the search string actually changed
if (newSearch !== location.search) {
navigate(
{
pathname: location.pathname,
search: newSearch,
},
{ replace: true }
);
}
}, [debouncedState, navigate, location.pathname, location.search]);
return {
sorting,
pagination,
filters,
setSorting,
setPagination,
setFilters,
};
}
/**
* Parse sorting state from URL query parameters
*/
function parseSortingFromURL(params: URLSearchParams): SortingState {
const sortBy = getUrlParam(params, URL_KEYS.sortBy);
const sortDirection = getUrlParam(params, URL_KEYS.sortDirection);
if (!sortBy) {
return [];
}
return [
{
id: sortBy,
desc: sortDirection === 'desc' || sortDirection === 'descending',
},
];
}
/**
* Parse pagination state from URL query parameters
*/
function parsePaginationFromURL(params: URLSearchParams): PaginationState {
const page = getUrlParam(params, URL_KEYS.pageNumber);
const perPage = getUrlParam(params, URL_KEYS.resultsPerPage);
return {
pageIndex: page ? parseInt(page, 10) - 1 : 0,
pageSize: perPage ? parseInt(perPage, 10) : 50,
};
}
/**
* Parse filters from URL query parameters
* Note: This is a simplified version. You may need to extend this based on your filter structure.
*/
function parseFiltersFromURL(params: URLSearchParams): ColumnFiltersState {
const filters: ColumnFiltersState = [];
const modalities = getUrlParam(params, URL_KEYS.modalities);
if (modalities) {
const modalityList = modalities.split(',').filter(Boolean);
if (modalityList.length > 0) {
filters.push({
id: COLUMN_IDS.MODALITIES,
value: modalityList,
});
}
}
const startDate = getUrlParam(params, URL_KEYS.startDate);
const endDate = getUrlParam(params, URL_KEYS.endDate);
if (startDate || endDate) {
filters.push({
id: COLUMN_IDS.STUDY_DATE_TIME,
value: {
...(startDate ? { startDate } : {}),
...(endDate ? { endDate } : {}),
},
});
}
// Text filters (patient name, MRN, accession, description). URL keys come
// from the centralized contract — see studyListFilterContract.ts.
TEXT_FILTER_COLUMN_IDS.forEach(id => {
const value = getUrlParam(params, urlKeyForTextFilter(id));
if (value) {
filters.push({
id,
value,
});
}
});
return filters;
}
/**
* Build URL query string from study list state preserving key query parameters.
*/
function buildQueryFromState(state: StudyListState): string {
const query: Record<string, string> = {};
// Sorting
if (state.sorting.length > 0) {
const sort = state.sorting[0];
query[URL_KEYS.sortBy] = sort.id;
query[URL_KEYS.sortDirection] = sort.desc ? 'desc' : 'asc';
}
// Pagination
if (state.pagination.pageIndex > 0) {
query[URL_KEYS.pageNumber] = String(state.pagination.pageIndex + 1);
}
if (state.pagination.pageSize !== 50) {
query[URL_KEYS.resultsPerPage] = String(state.pagination.pageSize);
}
// Filters
state.filters.forEach(filter => {
if (filter.id === COLUMN_IDS.MODALITIES && Array.isArray(filter.value)) {
query[URL_KEYS.modalities] = filter.value.join(',');
} else if (filter.id === COLUMN_IDS.STUDY_DATE_TIME) {
const dateRange = filter.value as StudyDateRangeFilter | undefined;
if (dateRange?.startDate) {
query[URL_KEYS.startDate] = dateRange.startDate;
}
if (dateRange?.endDate) {
query[URL_KEYS.endDate] = dateRange.endDate;
}
} else if (typeof filter.value === 'string' && filter.value) {
query[urlKeyForTextFilter(filter.id)] = filter.value;
}
});
if (state.dataSources) {
query[URL_KEYS.dataSources] = state.dataSources;
}
preserveQueryStrings(query);
return qs.stringify(query, { skipNull: true, skipEmptyString: true });
}
@@ -0,0 +1,66 @@
import React from 'react';
import { useTranslation } from 'react-i18next';
import { Button, Icons, useModal } from '@ohif/ui-next';
import { ServicesManager } from '@ohif/core';
export function useWorkListToolbarActions(
servicesManager: ServicesManager,
dataSource: any,
onRefresh: () => void
): React.ReactNode {
const { t } = useTranslation();
const { show, hide } = useModal();
const { customizationService } = servicesManager.services;
const DicomUploadComponent = customizationService.getCustomization('dicomUploadComponent') as any;
const dataSourceConfigurationComponent = customizationService.getCustomization(
'ohif.dataSourceConfigurationComponent'
) as any;
const uploadEnabled = DicomUploadComponent && dataSource.getConfig()?.dicomUploadEnabled;
const dataSourceConfigElement = dataSourceConfigurationComponent?.();
if (!uploadEnabled && !dataSourceConfigElement) {
return undefined;
}
const uploadProps = uploadEnabled
? {
title: 'Upload files',
containerClassName: DicomUploadComponent?.containerClassName,
closeButton: true,
shouldCloseOnEsc: false,
shouldCloseOnOverlayClick: false,
content: () => (
<DicomUploadComponent
dataSource={dataSource}
onComplete={() => {
hide();
onRefresh();
}}
onStarted={() => {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
show({ ...uploadProps, closeButton: false } as any);
}}
/>
),
}
: undefined;
return (
<div className="flex items-center gap-1">
{uploadProps && (
<Button
variant="ghost"
size="sm"
className="gap-1"
onClick={() => show(uploadProps as any)}
>
<Icons.Upload className="h-4 w-4" />
{t('Upload')}
</Button>
)}
{dataSourceConfigElement}
</div>
);
}