@genspectrum/dashboard-components 1.16.0 → 1.17.0

package/src/preact/mutationsOverTime/mutations-over-time.tsx

@@ -1,33 +1,33 @@
 import { type FunctionComponent } from 'preact';
-import { type Dispatch, type StateUpdater, useMemo, useState, useEffect, useLayoutEffect, useRef } from 'preact/hooks';
+import { type Dispatch, type StateUpdater, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'preact/hooks';
 import z from 'zod';
 
-import { type BaseMutationOverTimeDataMap, type MutationOverTimeDataMap } from './MutationOverTimeData';
-import {
-    displayMutationsSchema,
-    getFilteredMutationOverTimeData,
-    type MutationFilter,
-} from './getFilteredMutationsOverTimeData';
+import { displayMutationsSchema, getFilteredMutationCodes, type MutationFilter } from './getFilteredMutationCodes';
 import { MutationsOverTimeGridTooltip } from './mutations-over-time-grid-tooltip';
-import { type ProportionValue, getProportion, queryMutationsOverTimeData } from '../../query/queryMutationsOverTime';
 import {
-    lapisFilterSchema,
-    sequenceTypeSchema,
-    type SubstitutionOrDeletionEntry,
-    temporalGranularitySchema,
-    views,
-} from '../../types';
+    getProportion,
+    type MutationsOverTimeMetadata,
+    type ProportionValue,
+    queryMutationsOverTimeMetadata,
+    queryMutationsOverTimePage,
+} from '../../query/queryMutationsOverTime';
+import { lapisFilterSchema, sequenceTypeSchema, temporalGranularitySchema, views } from '../../types';
 import { type Deletion, type Substitution } from '../../utils/mutations';
 import { type Temporal, toTemporalClass } from '../../utils/temporalClass';
 import { useDispatchFinishedLoadingEvent } from '../../utils/useDispatchFinishedLoadingEvent';
 import { useLapisUrl } from '../LapisUrlContext';
 import { useMutationAnnotationsProvider } from '../MutationAnnotationsContext';
+import { type MutationOverTimeDataMap } from './MutationOverTimeData';
 import { AnnotatedMutation } from '../components/annotated-mutation';
 import { type ColorScale } from '../components/color-scale-selector';
 import { ColorScaleSelectorDropdown } from '../components/color-scale-selector-dropdown';
 import { CsvDownloadButton } from '../components/csv-download-button';
 import { ErrorBoundary } from '../components/error-boundary';
-import FeaturesOverTimeGrid, { type FeatureRenderer, customColumnSchema } from '../components/features-over-time-grid';
+import {
+    customColumnSchema,
+    type FeatureRenderer,
+    FeaturesOverTimeGridServerPaginated,
+} from '../components/features-over-time-grid';
 import { Fullscreen } from '../components/fullscreen';
 import Info, { InfoComponentCode, InfoHeadline1, InfoParagraph } from '../components/info';
 import { LoadingDisplay } from '../components/loading-display';
@@ -40,8 +40,9 @@ import { ResizeContainer } from '../components/resize-container';
 import { type DisplayedSegment, SegmentSelector, useDisplayedSegments } from '../components/segment-selector';
 import Tabs from '../components/tabs';
 import { pageSizesSchema } from '../shared/tanstackTable/pagination';
-import { PageSizeContextProvider } from '../shared/tanstackTable/pagination-context';
+import { PageSizeContextProvider, usePageSizeContext } from '../shared/tanstackTable/pagination-context';
 import { useQuery } from '../useQuery';
+import { handleHideGaps, useMutationsOverTimePageData } from './useMutationsOverTimePageData';
 
 const mutationsOverTimeViewSchema = z.literal(views.grid);
 export type MutationsOverTimeView = z.infer<typeof mutationsOverTimeViewSchema>;
@@ -83,47 +84,68 @@ export const MutationsOverTime: FunctionComponent<MutationsOverTimeProps> = (com
 
 export const MutationsOverTimeInner: FunctionComponent<MutationsOverTimeProps> = ({ ...componentProps }) => {
     const lapis = useLapisUrl();
-    const { lapisFilter, sequenceType, granularity, lapisDateField, displayMutations } = componentProps;
-
-    const { data, error, isLoading } = useQuery(
-        () =>
-            queryMutationsOverTimeData(lapisFilter, sequenceType, lapis, lapisDateField, granularity, displayMutations),
-        [granularity, lapis, lapisDateField, lapisFilter, sequenceType, displayMutations],
-    );
+    const { lapisFilter, sequenceType, granularity, lapisDateField, displayMutations, pageSizes } = componentProps;
+
+    const [pageIndex, setPageIndex] = useState(0);
+
+    const {
+        data: metadata,
+        error: metadataError,
+        isLoading: metadataLoading,
+    } = useQuery(() => {
+        setPageIndex(0);
+        return queryMutationsOverTimeMetadata(
+            lapisFilter,
+            sequenceType,
+            lapis,
+            lapisDateField,
+            granularity,
+            displayMutations,
+        );
+    }, [granularity, lapis, lapisDateField, lapisFilter, sequenceType, displayMutations]);
 
-    if (isLoading) {
+    if (metadataLoading) {
         return <LoadingDisplay />;
     }
 
-    if (error !== null) {
-        throw error;
+    if (metadataError) {
+        throw metadataError;
     }
 
-    if (data.overallMutationData.length === 0) {
+    if (metadata.overallMutationData.length === 0) {
         return <NoDataDisplay />;
     }
 
-    const { overallMutationData, mutationOverTimeData } = data;
     return (
-        <MutationsOverTimeTabs
-            overallMutationData={overallMutationData}
-            mutationOverTimeData={mutationOverTimeData}
-            originalComponentProps={componentProps}
-        />
+        <PageSizeContextProvider pageSizes={pageSizes}>
+            <MutationsOverTimeTabs
+                metadata={metadata}
+                originalComponentProps={componentProps}
+                pageIndex={pageIndex}
+                setPageIndex={setPageIndex}
+            />
+        </PageSizeContextProvider>
     );
 };
 
 type MutationOverTimeTabsProps = {
-    mutationOverTimeData: BaseMutationOverTimeDataMap;
+    metadata: MutationsOverTimeMetadata;
     originalComponentProps: MutationsOverTimeProps;
-    overallMutationData: SubstitutionOrDeletionEntry<Substitution, Deletion>[];
+    pageIndex: number;
+    setPageIndex: Dispatch<StateUpdater<number>>;
 };
 
 const MutationsOverTimeTabs: FunctionComponent<MutationOverTimeTabsProps> = ({
-    mutationOverTimeData,
+    metadata,
     originalComponentProps,
-    overallMutationData,
+    pageIndex,
+    setPageIndex,
 }) => {
+    const lapis = useLapisUrl();
+    const { lapisFilter, sequenceType, lapisDateField } = originalComponentProps;
+    const { overallMutationData, requestedDateRanges } = metadata;
+    const { pageSize } = usePageSizeContext();
+
     const tabsRef = useDispatchFinishedLoadingEvent();
     const tooltipPortalTargetRef = useRef<HTMLDivElement>(null);
     const [tooltipPortalTarget, setTooltipPortalTarget] = useState<HTMLDivElement | null>(null);
@@ -148,44 +170,65 @@ const MutationsOverTimeTabs: FunctionComponent<MutationOverTimeTabsProps> = ({
     ]);
 
     const [hideGaps, setHideGaps] = useState<boolean>(originalComponentProps.hideGaps ?? false);
-
     useEffect(() => setHideGaps(originalComponentProps.hideGaps ?? false), [originalComponentProps.hideGaps]);
 
-    const filteredData = useMemo(() => {
-        return getFilteredMutationOverTimeData({
-            data: mutationOverTimeData,
+    const filteredMutationCodes = useMemo(
+        () =>
+            getFilteredMutationCodes({
+                overallMutationData,
+                displayedSegments,
+                displayedMutationTypes,
+                proportionInterval,
+                mutationFilterValue,
+                sequenceType: originalComponentProps.sequenceType,
+                annotationProvider,
+            }),
+        [
             overallMutationData,
             displayedSegments,
             displayedMutationTypes,
             proportionInterval,
-            hideGaps,
+            originalComponentProps.sequenceType,
             mutationFilterValue,
-            sequenceType: originalComponentProps.sequenceType,
             annotationProvider,
-        });
-    }, [
-        mutationOverTimeData,
-        overallMutationData,
-        displayedSegments,
-        displayedMutationTypes,
-        proportionInterval,
+        ],
+    );
+
+    useEffect(() => {
+        setPageIndex(0);
+    }, [filteredMutationCodes, setPageIndex]);
+
+    const totalFilteredRows = filteredMutationCodes.length;
+    const {
+        isLoading: isPageLoading,
+        data: pageData,
+        pageMutationCodes,
+    } = useMutationsOverTimePageData(
+        filteredMutationCodes,
+        pageIndex,
+        pageSize,
+        lapisFilter,
+        lapis,
+        lapisDateField,
+        sequenceType,
+        requestedDateRanges,
         hideGaps,
-        originalComponentProps.sequenceType,
-        mutationFilterValue,
-        annotationProvider,
-    ]);
+    );
 
-    const mutationRenderer: FeatureRenderer<Substitution | Deletion> = {
-        asString: (value: Substitution | Deletion) => value.code,
-        renderRowLabel: (value: Substitution | Deletion) => (
-            <div className={'text-center'}>
-                <AnnotatedMutation mutation={value} sequenceType={originalComponentProps.sequenceType} />
-            </div>
-        ),
-        renderTooltip: (value: Substitution | Deletion, temporal: Temporal, proportionValue: ProportionValue) => (
-            <MutationsOverTimeGridTooltip mutation={value} date={temporal} value={proportionValue} />
-        ),
-    };
+    const mutationRenderer: FeatureRenderer<Substitution | Deletion> = useMemo(
+        () => ({
+            asString: (value: Substitution | Deletion) => value.code,
+            renderRowLabel: (value: Substitution | Deletion) => (
+                <div className={'text-center'}>
+                    <AnnotatedMutation mutation={value} sequenceType={originalComponentProps.sequenceType} />
+                </div>
+            ),
+            renderTooltip: (value: Substitution | Deletion, temporal: Temporal, proportionValue: ProportionValue) => (
+                <MutationsOverTimeGridTooltip mutation={value} date={temporal} value={proportionValue} />
+            ),
+        }),
+        [originalComponentProps.sequenceType],
+    );
 
     const getTab = (view: MutationsOverTimeView) => {
         switch (view) {
@@ -194,11 +237,17 @@ const MutationsOverTimeTabs: FunctionComponent<MutationOverTimeTabsProps> = ({
                 return {
                     title: 'Grid',
                     content: (
-                        <FeaturesOverTimeGrid
+                        <FeaturesOverTimeGridServerPaginated
                             rowLabelHeader='Mutation'
-                            data={filteredData}
+                            data={pageData}
+                            isLoading={isPageLoading}
+                            loadingRowLabels={pageMutationCodes}
+                            requestedDateRanges={requestedDateRanges}
                             colorScale={colorScale}
                             pageSizes={originalComponentProps.pageSizes}
+                            pageIndex={pageIndex}
+                            totalRows={totalFilteredRows}
+                            onPageChange={setPageIndex}
                             customColumns={originalComponentProps.customColumns}
                             featureRenderer={mutationRenderer}
                             tooltipPortalTarget={tooltipPortalTarget}
@@ -221,20 +270,19 @@ const MutationsOverTimeTabs: FunctionComponent<MutationOverTimeTabsProps> = ({
             setProportionInterval={setProportionInterval}
             hideGaps={hideGaps}
             setHideGaps={setHideGaps}
-            filteredData={filteredData}
             colorScale={colorScale}
             setColorScale={setColorScale}
             originalComponentProps={originalComponentProps}
             setFilterValue={setMutationFilterValue}
             mutationFilterValue={mutationFilterValue}
+            filteredMutationCodes={filteredMutationCodes}
+            metadata={metadata}
         />
     );
 
     return (
         <div ref={tooltipPortalTargetRef}>
-            <PageSizeContextProvider pageSizes={originalComponentProps.pageSizes}>
-                <Tabs ref={tabsRef} tabs={tabs} toolbar={toolbar} />
-            </PageSizeContextProvider>
+            <Tabs ref={tabsRef} tabs={tabs} toolbar={toolbar} />
         </div>
     );
 };
@@ -249,12 +297,13 @@ type ToolbarProps = {
     setProportionInterval: Dispatch<StateUpdater<ProportionInterval>>;
     hideGaps: boolean;
     setHideGaps: Dispatch<StateUpdater<boolean>>;
-    filteredData: MutationOverTimeDataMap;
     colorScale: ColorScale;
     setColorScale: Dispatch<StateUpdater<ColorScale>>;
     originalComponentProps: MutationsOverTimeProps;
     mutationFilterValue: MutationFilter;
     setFilterValue: Dispatch<StateUpdater<MutationFilter>>;
+    filteredMutationCodes: string[];
+    metadata: MutationsOverTimeMetadata;
 };
 
 const Toolbar: FunctionComponent<ToolbarProps> = ({
@@ -267,13 +316,29 @@ const Toolbar: FunctionComponent<ToolbarProps> = ({
     setProportionInterval,
     hideGaps,
     setHideGaps,
-    filteredData,
     colorScale,
     setColorScale,
     originalComponentProps,
     setFilterValue,
     mutationFilterValue,
+    filteredMutationCodes,
+    metadata,
 }) => {
+    const lapis = useLapisUrl();
+    const { lapisFilter, sequenceType, lapisDateField } = originalComponentProps;
+
+    const getDownloadDataAsync = async (): Promise<Record<string, string | number>[]> => {
+        const pageData = await queryMutationsOverTimePage(
+            lapisFilter,
+            lapis,
+            lapisDateField,
+            sequenceType,
+            metadata.requestedDateRanges,
+            filteredMutationCodes,
+        );
+        return getDownloadData(handleHideGaps(pageData, hideGaps));
+    };
+
     return (
         <>
             <MutationsOverTimeMutationsFilter setFilterValue={setFilterValue} value={mutationFilterValue} />
@@ -308,7 +373,7 @@ const Toolbar: FunctionComponent<ToolbarProps> = ({
             )}
             <CsvDownloadButton
                 className='btn btn-xs'
-                getData={() => getDownloadData(filteredData)}
+                getData={getDownloadDataAsync}
                 filename='mutations_over_time.csv'
             />
             <MutationsOverTimeInfo originalComponentProps={originalComponentProps} />

package/src/preact/mutationsOverTime/useMutationsOverTimePageData.ts

@@ -0,0 +1,111 @@
+import { useEffect, useMemo, useRef } from 'preact/hooks';
+
+import { type MutationOverTimeDataMap } from './MutationOverTimeData';
+import { type MutationsOverTimeMetadata, queryMutationsOverTimePage } from '../../query/queryMutationsOverTime';
+import { type LapisFilter } from '../../types';
+import { Map2dView } from '../../utils/map2d';
+import { useQuery } from '../useQuery';
+
+type MutationsOverTimePageQuery =
+    | { isLoading: true; data: null; pageMutationCodes: string[] }
+    | { isLoading: false; data: MutationOverTimeDataMap; pageMutationCodes: string[] };
+
+/**
+ * Fetches the data for a single page of the mutations-over-time grid.
+ *
+ * Rather than loading all mutation data at once, this hook fetches only the rows (mutation codes)
+ * that are visible on the current page. The set of visible mutations is determined by
+ * `filteredMutationCodes` (all mutations that pass the current client-side filters), sliced to
+ * the current page according to `pageIndex` and `pageSize`.
+ *
+ * Results are cached in a `useRef`-backed Map keyed by the full query context (filter, date
+ * ranges, sequence type, and the specific mutation codes on the page), so revisiting a page does
+ * not trigger a new network request. The cache is cleared automatically whenever the underlying
+ * query inputs change (i.e. `lapisFilter`, `lapis`, `lapisDateField`, `sequenceType`, or
+ * `requestedDateRanges`), ensuring stale data is never served after the dataset changes.
+ *
+ * When `hideGaps` is true, date-range columns that contain no data are removed from the returned
+ * view before it is passed to the grid.
+ */
+export function useMutationsOverTimePageData(
+    filteredMutationCodes: string[],
+    pageIndex: number,
+    pageSize: number,
+    lapisFilter: LapisFilter,
+    lapis: string,
+    lapisDateField: string,
+    sequenceType: 'nucleotide' | 'amino acid',
+    requestedDateRanges: MutationsOverTimeMetadata['requestedDateRanges'],
+    hideGaps: boolean,
+): MutationsOverTimePageQuery {
+    const pageMutationCodes = useMemo(
+        () => filteredMutationCodes.slice(pageIndex * pageSize, (pageIndex + 1) * pageSize),
+        [filteredMutationCodes, pageIndex, pageSize],
+    );
+
+    const cache = useRef<Map<string, MutationOverTimeDataMap>>(new Map());
+    useEffect(() => {
+        cache.current = new Map(); // make sure the cache doesn't grow indefinitely
+    }, [lapisFilter, lapis, lapisDateField, sequenceType, requestedDateRanges]);
+
+    const {
+        data: pageData,
+        error,
+        isLoading,
+    } = useQuery(async () => {
+        const cacheKey = JSON.stringify({
+            lapisFilter,
+            lapis,
+            lapisDateField,
+            sequenceType,
+            requestedDateRanges,
+            pageMutationCodes,
+        });
+        const cachedData = cache.current.get(cacheKey);
+        if (cachedData !== undefined) {
+            return cachedData;
+        }
+
+        const newData = await queryMutationsOverTimePage(
+            lapisFilter,
+            lapis,
+            lapisDateField,
+            sequenceType,
+            requestedDateRanges,
+            pageMutationCodes,
+        );
+        cache.current.set(cacheKey, newData);
+        return newData;
+    }, [lapisFilter, lapis, lapisDateField, sequenceType, requestedDateRanges, pageMutationCodes]);
+
+    if (error) {
+        throw error;
+    }
+
+    return useMemo(() => {
+        if (isLoading) {
+            return { isLoading: true, data: null, pageMutationCodes };
+        }
+
+        return { isLoading: false, data: handleHideGaps(pageData, hideGaps), pageMutationCodes };
+    }, [pageData, hideGaps, isLoading, pageMutationCodes]);
+}
+
+/**
+ * Returns a new view on `data` where columns (date ranges) that do not contain any data are
+ * filtered out. When `hideGaps` is false the original data is returned unchanged.
+ */
+export function handleHideGaps(data: MutationOverTimeDataMap, hideGaps: boolean) {
+    if (!hideGaps) {
+        return data;
+    }
+
+    const view = new Map2dView(data);
+    view.getSecondAxisKeys()
+        .filter((dateRange) => {
+            const vals = view.getColumn(dateRange);
+            return !vals.some((v) => (v?.type === 'value' || v?.type === 'valueWithCoverage') && v.totalCount > 0);
+        })
+        .forEach((dateRange) => view.deleteColumn(dateRange));
+    return view;
+}

package/src/preact/shared/tanstackTable/pagination-context.tsx

@@ -1,7 +1,8 @@
 import { createContext, type FunctionComponent } from 'preact';
-import { type Dispatch, type StateUpdater, useContext, useState } from 'preact/hooks';
+import { type Dispatch, type StateUpdater, useContext } from 'preact/hooks';
 
 import type { PageSizes } from './pagination';
+import { useControlledState } from '../../../utils/useControlledState';
 
 type PageSizeContext = {
     pageSize: number;
@@ -24,7 +25,9 @@ export type PageSizeContextProviderProps = {
 };
 
 export const PageSizeContextProvider: FunctionComponent<PageSizeContextProviderProps> = ({ children, pageSizes }) => {
-    const [pageSize, setPageSize] = useState(typeof pageSizes === 'number' ? pageSizes : (pageSizes.at(0) ?? 10));
+    const [pageSize, setPageSize] = useControlledState(
+        typeof pageSizes === 'number' ? pageSizes : (pageSizes.at(0) ?? 10),
+    );
 
     return <pageSizeContext.Provider value={{ pageSize, setPageSize }}>{children}</pageSizeContext.Provider>;
 };

package/src/preact/shared/tanstackTable/pagination.tsx

@@ -13,16 +13,19 @@ export type PageSizes = z.infer<typeof pageSizesSchema>;
 export function Pagination({
     table,
     pageSizes,
+    totalRows,
 }: PaginationProps & {
     pageSizes: PageSizes;
+    /** Override the total row count (for server-driven pagination). */
+    totalRows: number;
 }) {
     return (
         <div className='@container'>
             <div className='flex items-center gap-x-6 gap-y-2 flex-wrap @xl:justify-end justify-center'>
                 <PageSizeSelector table={table} pageSizes={pageSizes} />
-                <PageIndicator table={table} />
+                <PageIndicator table={table} totalRows={totalRows} />
                 <div className='@xl:block hidden'>
-                    <GotoPageSelector table={table} />
+                    <GotoPageSelector table={table} totalRows={totalRows} />
                 </div>
                 <SelectPageButtons table={table} />
             </div>
@@ -30,18 +33,17 @@ export function Pagination({
     );
 }
 
-function PageIndicator({ table }: PaginationProps) {
-    if (table.getRowModel().rows.length <= 1) {
+function PageIndicator({ table, totalRows }: PaginationProps & { totalRows: number }) {
+    if (table.getPaginationRowModel().rows.length <= 1 && totalRows <= 1) {
         return null;
     }
 
     const minRow = table.getState().pagination.pageIndex * table.getState().pagination.pageSize + 1;
-    const maxRow = minRow + table.getRowModel().rows.length - 1;
-    const numRows = table.getCoreRowModel().rows.length;
+    const maxRow = minRow + table.getPaginationRowModel().rows.length - 1;
 
     return (
         <span className='text-sm'>
-            {minRow} - {maxRow} of {numRows}
+            {minRow} - {maxRow} of {totalRows}
         </span>
     );
 }
@@ -88,8 +90,8 @@ function PageSizeSelector({
     );
 }
 
-function GotoPageSelector({ table }: PaginationProps) {
-    if (table.getRowModel().rows.length === 0) {
+function GotoPageSelector({ table, totalRows }: PaginationProps & { totalRows: number }) {
+    if (table.getRowModel().rows.length === 0 && totalRows === 0) {
         return null;
     }
 

package/src/preact/shared/tanstackTable/tanstackTable.tsx

@@ -4,8 +4,6 @@ import { useEffect, useState } from 'preact/hooks';
 
 import { usePageSizeContext } from './pagination-context';
 
-export * from '@tanstack/table-core';
-
 export type Renderable<TProps> = VNode<TProps> | ComponentType<TProps> | undefined | null | string | number | boolean;
 
 /*
@@ -45,12 +43,17 @@ export function usePreactTable<TData extends RowData>(options: TableOptions<TDat
         },
     }));
 
+    // When pagination is controlled externally (manualPagination: true with a state override),
+    // the caller manages pageSize themselves — skip the context sync to avoid conflicts.
+    const isControlled = options.manualPagination === true && options.state?.pagination !== undefined;
     const { pageSize } = usePageSizeContext();
     useEffect(
         () => {
-            tableRef.current.setPageSize(pageSize);
+            if (!isControlled) {
+                tableRef.current.setPageSize(pageSize);
+            }
         },
-        [pageSize], // eslint-disable-line react-hooks/exhaustive-deps -- only run this when the pageSize changes
+        [pageSize, isControlled], // eslint-disable-line react-hooks/exhaustive-deps -- only run this when the pageSize changes
     );
 
     return tableRef.current;

package/src/preact/wastewater/mutationsOverTime/wastewater-mutations-over-time.tsx

@@ -28,7 +28,7 @@ import { type MutationOverTimeDataMap } from '../../mutationsOverTime/MutationOv
 import {
     type MutationFilter,
     mutationOrAnnotationDoNotMatchFilter,
-} from '../../mutationsOverTime/getFilteredMutationsOverTimeData';
+} from '../../mutationsOverTime/getFilteredMutationCodes';
 import { MutationsOverTimeGridTooltip } from '../../mutationsOverTime/mutations-over-time-grid-tooltip';
 import { pageSizesSchema } from '../../shared/tanstackTable/pagination';
 import { PageSizeContextProvider } from '../../shared/tanstackTable/pagination-context';