@cosmicdrift/kumiko-renderer 0.388.0 → 0.389.0

package/dist/hooks/list-server-groups.d.ts

@@ -0,0 +1,39 @@
+import type { ListAggregateGroup } from "@cosmicdrift/kumiko-types/list-aggregate-types";
+import { type ListTableGrouping } from "@cosmicdrift/kumiko-types/screen";
+import type { DataTableMeasure, DataTableServerGroup } from "../data-table-aggregate-types.ts";
+import type { Translate } from "../headless/index.ts";
+import { type ListGroupPageRequest, type ListGroupPageResult, type ListGroupPaging } from "./list-group-pages.ts";
+export type GroupLoadState = {
+    readonly resetKey: string;
+    readonly toggled: ReadonlySet<string>;
+    readonly visible: ReadonlySet<string>;
+    readonly requestedPages: ReadonlyMap<string, number>;
+    readonly results: ReadonlyMap<string, ListGroupPageResult>;
+};
+export type MeasureSpec = {
+    readonly field: string;
+    readonly kind: DataTableMeasure["kind"];
+};
+type Row = Readonly<Record<string, unknown>>;
+export declare function freshLoadState(resetKey: string): GroupLoadState;
+export declare function measuresOf(totals: readonly MeasureSpec[], group: ListAggregateGroup | undefined): DataTableMeasure[];
+type ServerGroupsInput = {
+    readonly answer: readonly ListAggregateGroup[];
+    readonly groupField: string;
+    /** The declared grouping, only when the active field is the declared one. */
+    readonly declared: ListTableGrouping | undefined;
+    readonly state: GroupLoadState;
+    readonly base: Readonly<Record<string, unknown>>;
+    readonly pageSize: number;
+    readonly paging: ListGroupPaging;
+    readonly measures: readonly MeasureSpec[];
+    readonly translate: Translate;
+};
+export type ServerGroupsBuild = {
+    readonly groups: DataTableServerGroup[];
+    readonly rows: Row[];
+    readonly requests: ListGroupPageRequest[];
+};
+/** Header entries, loaded rows and the page requests of the open, visible groups. */
+export declare function buildServerGroups(input: ServerGroupsInput): ServerGroupsBuild;
+export {};

package/dist/hooks/list-server-groups.js

@@ -0,0 +1,84 @@
+import { relatedListGroupHeaderLabel, relatedListGroupKey, } from "@cosmicdrift/kumiko-types/screen";
+import { groupPageKey, groupPagePayload, loadedGroupPages, } from "./list-group-pages.js";
+export function freshLoadState(resetKey) {
+    return {
+        resetKey,
+        toggled: new Set(),
+        visible: new Set(),
+        requestedPages: new Map(),
+        results: new Map(),
+    };
+}
+export function measuresOf(totals, group) {
+    return totals.map((total, index) => ({
+        field: total.field,
+        kind: total.kind,
+        value: group?.measures[index] ?? null,
+    }));
+}
+function startsCollapsed(declared, key) {
+    return (declared?.collapsedWhen !== undefined && key === relatedListGroupKey(declared.collapsedWhen));
+}
+function headerLabel(input, key, group) {
+    const serverLabel = group.label ?? undefined;
+    const labelKey = input.declared === undefined ? undefined : relatedListGroupHeaderLabel(input.declared, key);
+    if (labelKey === undefined)
+        return serverLabel;
+    return input.translate(labelKey, { count: group.count, value: serverLabel ?? key });
+}
+function pageRequests(input, group, key, pages, requestedPages) {
+    const requests = [];
+    for (let pageIndex = 0; pageIndex < requestedPages; pageIndex++) {
+        const cursor = pageIndex === 0 ? undefined : (pages[pageIndex - 1]?.nextCursor ?? undefined);
+        // skip: a cursor page waits for the page before it
+        if (input.paging === "cursor" && pageIndex > 0 && cursor === undefined)
+            break;
+        requests.push({
+            pageKey: groupPageKey(key, pageIndex),
+            payload: groupPagePayload({
+                base: input.base,
+                groupField: input.groupField,
+                groupValue: group.key,
+                pageSize: input.pageSize,
+                pageIndex,
+                paging: input.paging,
+                cursor,
+            }),
+        });
+    }
+    return requests;
+}
+function hasMoreRows(paging, loaded, count, lastPage) {
+    return loaded < count && (paging === "offset" || lastPage?.nextCursor !== null);
+}
+function buildGroup(input, group, into) {
+    const { state } = input;
+    const key = relatedListGroupKey(group.key);
+    const collapsed = startsCollapsed(input.declared, key) !== state.toggled.has(key);
+    const requestedPages = state.requestedPages.get(key) ?? 1;
+    const pages = collapsed ? [] : loadedGroupPages(state.results, key, requestedPages);
+    const loadsRows = !collapsed && state.visible.has(key);
+    if (loadsRows)
+        into.requests.push(...pageRequests(input, group, key, pages, requestedPages));
+    const groupRows = pages.flatMap((page) => page.rows);
+    into.rows.push(...groupRows);
+    const label = headerLabel(input, key, group);
+    into.groups.push({
+        key,
+        value: group.key,
+        ...(label !== undefined && { label }),
+        count: group.count,
+        measures: measuresOf(input.measures, group),
+        collapsed,
+        rowCount: groupRows.length,
+        hasMore: hasMoreRows(input.paging, groupRows.length, group.count, pages[pages.length - 1]),
+        loading: loadsRows && (pages.length < requestedPages || pages.some((page) => page.loading)),
+    });
+}
+/** Header entries, loaded rows and the page requests of the open, visible groups. */
+export function buildServerGroups(input) {
+    const build = { groups: [], rows: [], requests: [] };
+    for (const group of input.answer)
+        buildGroup(input, group, build);
+    return build;
+}

package/dist/hooks/list-state-schema.d.ts

@@ -0,0 +1,28 @@
+import { type ListColumnPin, type ListTableDensity } from "@cosmicdrift/kumiko-types/screen";
+export type StoredListColumn = {
+    readonly field: string;
+    readonly visible: boolean;
+};
+/** Remembered state of one list. `params` holds the list's URL parameters
+ *  without the screen-id prefix (`sort`, `dir`, `q`, `page`, `size`, `f.<field>`). */
+export type StoredListState = {
+    readonly params?: Readonly<Record<string, string>>;
+    readonly view?: {
+        readonly columns?: readonly StoredListColumn[];
+        readonly density?: ListTableDensity;
+        readonly pins?: Readonly<Record<string, ListColumnPin>>;
+        readonly widths?: Readonly<Record<string, number>>;
+        /** Chosen group field, "" = the user turned grouping off. */
+        readonly groupBy?: string;
+    };
+};
+/** Storage boundary: anything that is not a well-formed state reads as "nothing remembered". */
+export declare function parseStoredListState(raw: unknown): StoredListState | undefined;
+export declare function parseStoredListStateJson(text: string): StoredListState | undefined;
+export type KnownListFields = {
+    readonly columnFields: readonly string[];
+    readonly filterFields: readonly string[];
+};
+/** Drops what the screen no longer has (renamed field, removed column) so an old
+ *  session never feeds dead keys into the URL or the column picker. */
+export declare function sanitizeStoredListState(raw: unknown, known: KnownListFields): StoredListState | undefined;

package/dist/hooks/list-state-schema.js

@@ -0,0 +1,76 @@
+import { LIST_COLUMN_PINS, LIST_TABLE_DENSITIES, } from "@cosmicdrift/kumiko-types/screen";
+import * as z from "zod";
+const storedListStateSchema = z.object({
+    params: z.record(z.string(), z.string()).optional(),
+    view: z
+        .object({
+        columns: z.array(z.object({ field: z.string(), visible: z.boolean() })).optional(),
+        density: z.enum(LIST_TABLE_DENSITIES).optional(),
+        pins: z.record(z.string(), z.enum(LIST_COLUMN_PINS)).optional(),
+        widths: z.record(z.string(), z.number().finite().positive()).optional(),
+        groupBy: z.string().optional(),
+    })
+        .optional(),
+});
+/** Storage boundary: anything that is not a well-formed state reads as "nothing remembered". */
+export function parseStoredListState(raw) {
+    const parsed = storedListStateSchema.safeParse(raw);
+    return parsed.success ? parsed.data : undefined;
+}
+export function parseStoredListStateJson(text) {
+    try {
+        return parseStoredListState(JSON.parse(text));
+    }
+    catch {
+        return undefined;
+    }
+}
+const PLAIN_PARAM_SUFFIXES = new Set(["sort", "dir", "q", "page", "size"]);
+const FILTER_PREFIX = "f.";
+const RANGE_BOUND_SUFFIXES = [".from", ".to", ".min", ".max"];
+function isKnownParamSuffix(suffix, filterFields) {
+    if (PLAIN_PARAM_SUFFIXES.has(suffix))
+        return true;
+    if (!suffix.startsWith(FILTER_PREFIX))
+        return false;
+    const filterKey = suffix.slice(FILTER_PREFIX.length);
+    if (filterFields.has(filterKey))
+        return true;
+    return RANGE_BOUND_SUFFIXES.some((bound) => filterKey.endsWith(bound) && filterFields.has(filterKey.slice(0, -bound.length)));
+}
+function onKnownFields(record, known) {
+    if (record === undefined)
+        return undefined;
+    return Object.fromEntries(Object.entries(record).filter(([field]) => known.has(field)));
+}
+/** Drops what the screen no longer has (renamed field, removed column) so an old
+ *  session never feeds dead keys into the URL or the column picker. */
+export function sanitizeStoredListState(raw, known) {
+    const state = parseStoredListState(raw);
+    if (state === undefined)
+        return undefined;
+    const filterFields = new Set(known.filterFields);
+    const columnFields = new Set(known.columnFields);
+    const params = state.params === undefined
+        ? undefined
+        : Object.fromEntries(Object.entries(state.params).filter(([suffix]) => isKnownParamSuffix(suffix, filterFields)));
+    const columns = state.view?.columns?.filter((column) => columnFields.has(column.field));
+    const density = state.view?.density;
+    const pins = onKnownFields(state.view?.pins, columnFields);
+    const widths = onKnownFields(state.view?.widths, columnFields);
+    const savedGroupBy = state.view?.groupBy;
+    const groupBy = savedGroupBy === "" || (savedGroupBy !== undefined && columnFields.has(savedGroupBy))
+        ? savedGroupBy
+        : undefined;
+    const view = {
+        ...(columns !== undefined && { columns }),
+        ...(density !== undefined && { density }),
+        ...(pins !== undefined && { pins }),
+        ...(widths !== undefined && { widths }),
+        ...(groupBy !== undefined && { groupBy }),
+    };
+    return {
+        ...(params !== undefined && { params }),
+        ...(state.view !== undefined && { view }),
+    };
+}

package/dist/hooks/use-bulk-run.d.ts

@@ -0,0 +1,41 @@
+import type { DataTableBulkAction } from "../data-table-bulk-types.ts";
+import type { ListRowViewModel } from "../headless/index.ts";
+/** Parallel row writes of one run; more would crowd out the list's own requests. */
+export declare const BULK_WRITE_CONCURRENCY = 4;
+export type BulkRunResult = {
+    readonly succeededIds: readonly string[];
+    readonly failedIds: readonly string[];
+    readonly skippedIds: readonly string[];
+    /** Rows a cancel kept from starting. */
+    readonly notStartedIds: readonly string[];
+    readonly firstFailureMessage?: string;
+};
+type BulkRunAction = Pick<DataTableBulkAction, "appliesTo" | "writeRow">;
+/** One write per row, at most `concurrency` at a time. Cancel stops new writes; running ones finish. */
+export declare function runBulkWrites({ rows, action, isCancelled, onRowSettled, concurrency, }: {
+    readonly rows: readonly ListRowViewModel[];
+    readonly action: BulkRunAction;
+    readonly isCancelled: () => boolean;
+    readonly onRowSettled?: () => void;
+    readonly concurrency?: number;
+}): Promise<BulkRunResult>;
+export type BulkRunState = {
+    readonly phase: "idle";
+} | {
+    readonly phase: "running";
+    readonly total: number;
+    readonly settled: number;
+    readonly cancelRequested: boolean;
+} | {
+    readonly phase: "finished";
+    readonly result: BulkRunResult;
+};
+export type BulkRun = {
+    readonly state: BulkRunState;
+    readonly start: (action: BulkRunAction, rows: readonly ListRowViewModel[]) => Promise<BulkRunResult>;
+    readonly cancel: () => void;
+    readonly dismissResult: () => void;
+};
+/** Execution model of a bulk run: progress counter, cancel and the final tally. */
+export declare function useBulkRun(): BulkRun;
+export {};

package/dist/hooks/use-bulk-run.js

@@ -0,0 +1,65 @@
+import { useCallback, useRef, useState } from "react";
+/** Parallel row writes of one run; more would crowd out the list's own requests. */
+export const BULK_WRITE_CONCURRENCY = 4;
+function failureOf(error) {
+    return { kind: "failed", message: error instanceof Error ? error.message : String(error) };
+}
+/** One write per row, at most `concurrency` at a time. Cancel stops new writes; running ones finish. */
+export async function runBulkWrites({ rows, action, isCancelled, onRowSettled, concurrency = BULK_WRITE_CONCURRENCY, }) {
+    const applicable = rows.filter((row) => action.appliesTo(row));
+    const skippedIds = rows.filter((row) => !action.appliesTo(row)).map((row) => row.id);
+    const succeededIds = [];
+    const failedIds = [];
+    let firstFailureMessage;
+    let nextIndex = 0;
+    async function drainQueue() {
+        while (nextIndex < applicable.length && !isCancelled()) {
+            const row = applicable[nextIndex];
+            nextIndex += 1;
+            if (row === undefined)
+                continue;
+            const outcome = await action.writeRow(row).catch(failureOf);
+            if (outcome.kind === "succeeded") {
+                succeededIds.push(row.id);
+            }
+            else {
+                failedIds.push(row.id);
+                firstFailureMessage ??= outcome.message;
+            }
+            onRowSettled?.();
+        }
+    }
+    const workerCount = Math.min(concurrency, applicable.length);
+    await Promise.all(Array.from({ length: workerCount }, drainQueue));
+    return {
+        succeededIds,
+        failedIds,
+        skippedIds,
+        notStartedIds: applicable.slice(nextIndex).map((row) => row.id),
+        ...(firstFailureMessage !== undefined && { firstFailureMessage }),
+    };
+}
+/** Execution model of a bulk run: progress counter, cancel and the final tally. */
+export function useBulkRun() {
+    const [state, setState] = useState({ phase: "idle" });
+    const cancelledRef = useRef(false);
+    const start = useCallback(async (action, rows) => {
+        cancelledRef.current = false;
+        const total = rows.filter((row) => action.appliesTo(row)).length;
+        setState({ phase: "running", total, settled: 0, cancelRequested: false });
+        const result = await runBulkWrites({
+            rows,
+            action,
+            isCancelled: () => cancelledRef.current,
+            onRowSettled: () => setState((prev) => prev.phase === "running" ? { ...prev, settled: prev.settled + 1 } : prev),
+        });
+        setState({ phase: "finished", result });
+        return result;
+    }, []);
+    const cancel = useCallback(() => {
+        cancelledRef.current = true;
+        setState((prev) => (prev.phase === "running" ? { ...prev, cancelRequested: true } : prev));
+    }, []);
+    const dismissResult = useCallback(() => setState({ phase: "idle" }), []);
+    return { state, start, cancel, dismissResult };
+}

package/dist/hooks/use-group-load-state.d.ts

@@ -0,0 +1,11 @@
+import type { ListGroupPageResult } from "./list-group-pages.ts";
+import { type GroupLoadState } from "./list-server-groups.ts";
+export type GroupLoadControls = {
+    readonly state: GroupLoadState;
+    readonly onToggle: (key: string) => void;
+    readonly onHeaderVisible: (key: string) => void;
+    readonly onLoadMore: (key: string) => void;
+    readonly onResult: (pageKey: string, result: ListGroupPageResult) => void;
+};
+/** Open/visible/paged state of the server groups; starts over when `resetKey` changes. */
+export declare function useGroupLoadState(resetKey: string): GroupLoadControls;

package/dist/hooks/use-group-load-state.js

@@ -0,0 +1,31 @@
+import { useCallback, useState } from "react";
+import { freshLoadState } from "./list-server-groups.js";
+function withToggled(set, key) {
+    const next = new Set(set);
+    if (!next.delete(key))
+        next.add(key);
+    return next;
+}
+/** Open/visible/paged state of the server groups; starts over when `resetKey` changes. */
+export function useGroupLoadState(resetKey) {
+    const [loadState, setLoadState] = useState(() => freshLoadState(resetKey));
+    const state = loadState.resetKey === resetKey ? loadState : freshLoadState(resetKey);
+    if (loadState.resetKey !== resetKey)
+        setLoadState(state);
+    const update = useCallback((change) => setLoadState((current) => (current.resetKey === resetKey ? change(current) : current)), [resetKey]);
+    const onToggle = useCallback((key) => update((current) => ({ ...current, toggled: withToggled(current.toggled, key) })), [update]);
+    const onHeaderVisible = useCallback((key) => update((current) => current.visible.has(key)
+        ? current
+        : { ...current, visible: new Set([...current.visible, key]) }), [update]);
+    const onLoadMore = useCallback((key) => update((current) => {
+        const requestedPages = new Map(current.requestedPages);
+        requestedPages.set(key, (current.requestedPages.get(key) ?? 1) + 1);
+        return { ...current, requestedPages };
+    }), [update]);
+    const onResult = useCallback((pageKey, result) => update((current) => {
+        const results = new Map(current.results);
+        results.set(pageKey, result);
+        return { ...current, results };
+    }), [update]);
+    return { state, onToggle, onHeaderVisible, onLoadMore, onResult };
+}

package/dist/hooks/use-list-aggregates.d.ts

@@ -0,0 +1,38 @@
+import type { ListTableOptions } from "@cosmicdrift/kumiko-types/screen";
+import type { DataTableListNotice, DataTableServerGroups, DataTableTotals } from "../data-table-aggregate-types.ts";
+import type { DispatcherError, Translate } from "../headless/index.ts";
+import { type ListGroupPageRequest, type ListGroupPageResult, type ListGroupPaging } from "./list-group-pages.ts";
+type ListAggregatesArgs = {
+    readonly queryType: string;
+    /** The list payload as the ungrouped list would send it; paging keys are dropped. */
+    readonly payload: Readonly<Record<string, unknown>>;
+    readonly table: ListTableOptions | undefined;
+    readonly groupField: string | undefined;
+    readonly pageSize: number;
+    readonly paging: ListGroupPaging;
+    readonly translate: Translate;
+};
+export type ListGroupPagesProps = {
+    readonly queryType: string;
+    readonly requests: readonly ListGroupPageRequest[];
+    readonly onResult: (pageKey: string, result: ListGroupPageResult) => void;
+    readonly refreshNonce: number;
+};
+export type ListAggregates = {
+    readonly grouped: boolean;
+    /** Loaded rows of the open groups, in group order. */
+    readonly rows: readonly Readonly<Record<string, unknown>>[];
+    readonly serverGroups?: DataTableServerGroups;
+    readonly totals?: DataTableTotals;
+    readonly notice?: DataTableListNotice;
+    readonly groupPages: ListGroupPagesProps;
+    /** Reloads groups, totals and the loaded group pages (after a write). */
+    readonly refresh: () => void;
+    /** True until the first group answer is in. */
+    readonly loading: boolean;
+    readonly error: DispatcherError | null;
+};
+/** Server-side grouping and totals of a list: groups are the load unit, each open
+ *  and visible group pages through its own rows; nothing is summed on the client. */
+export declare function useListAggregates({ queryType, payload, table, groupField, pageSize, paging, translate, }: ListAggregatesArgs): ListAggregates;
+export {};

package/dist/hooks/use-list-aggregates.js

@@ -0,0 +1,107 @@
+import { isListAggregateResult, } from "@cosmicdrift/kumiko-types/list-aggregate-types";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { withoutListPaging, } from "./list-group-pages.js";
+import { buildServerGroups, measuresOf } from "./list-server-groups.js";
+import { useGroupLoadState } from "./use-group-load-state.js";
+import { useQuery } from "./use-query.js";
+const EMPTY_BUILD = { groups: [], rows: [], requests: [] };
+function aggregateOf(data) {
+    return isListAggregateResult(data) ? data : undefined;
+}
+function noticeOf(groups, totals) {
+    if (groups?.truncated === true)
+        return "truncated";
+    if (groups?.searchTruncated === true || totals?.searchTruncated === true) {
+        return "searchTruncated";
+    }
+    return undefined;
+}
+/** The groups and totals aggregate queries plus a refresh that reloads both. */
+function useAggregateQueries(args) {
+    const { queryType, base, groupField, measures } = args;
+    const grouped = groupField !== undefined;
+    const withTotals = measures.length > 0;
+    const groupsPayload = useMemo(() => ({ ...base, aggregate: { groupBy: groupField, measures } }), [base, groupField, measures]);
+    const totalsPayload = useMemo(() => ({ ...base, aggregate: { measures } }), [base, measures]);
+    const groupsQuery = useQuery(queryType, groupsPayload, { live: true, enabled: grouped });
+    const totalsQuery = useQuery(queryType, totalsPayload, {
+        live: true,
+        enabled: withTotals,
+    });
+    const [refreshNonce, setRefreshNonce] = useState(0);
+    const refetchGroups = groupsQuery.refetch;
+    const refetchTotals = totalsQuery.refetch;
+    const refresh = useCallback(() => setRefreshNonce((n) => n + 1), []);
+    useEffect(() => {
+        // skip: the mount fetch already covers the first nonce
+        if (refreshNonce === 0)
+            return;
+        if (grouped)
+            void refetchGroups();
+        if (withTotals)
+            void refetchTotals();
+    }, [refreshNonce, grouped, withTotals, refetchGroups, refetchTotals]);
+    return {
+        groupsAnswer: grouped ? aggregateOf(groupsQuery.data) : undefined,
+        totalsAnswer: withTotals ? aggregateOf(totalsQuery.data) : undefined,
+        groupsError: grouped ? groupsQuery.error : null,
+        refresh,
+        refreshNonce,
+    };
+}
+/** Server-side grouping and totals of a list: groups are the load unit, each open
+ *  and visible group pages through its own rows; nothing is summed on the client. */
+export function useListAggregates({ queryType, payload, table, groupField, pageSize, paging, translate, }) {
+    const grouping = table?.grouping;
+    const totalSpecs = useMemo(() => table?.totals ?? [], [table?.totals]);
+    const base = useMemo(() => withoutListPaging(payload), [payload]);
+    const baseKey = JSON.stringify(base);
+    const measures = useMemo(() => totalSpecs.map((total) => ({ field: total.field, kind: total.kind })), [totalSpecs]);
+    const grouped = groupField !== undefined;
+    const { groupsAnswer, totalsAnswer, groupsError, refresh, refreshNonce } = useAggregateQueries({
+        queryType,
+        base,
+        groupField,
+        measures,
+    });
+    const { state, onToggle, onHeaderVisible, onLoadMore, onResult } = useGroupLoadState(`${groupField ?? ""}|${baseKey}`);
+    const active = groupField !== undefined && groupsAnswer !== undefined;
+    const { groups, rows, requests } = active
+        ? buildServerGroups({
+            answer: groupsAnswer.groups,
+            groupField,
+            declared: grouping?.field === groupField ? grouping : undefined,
+            state,
+            base,
+            pageSize,
+            paging,
+            measures: totalSpecs,
+            translate,
+        })
+        : EMPTY_BUILD;
+    const serverGroups = active
+        ? {
+            field: groupField,
+            groups,
+            totalCount: groups.reduce((sum, group) => sum + group.count, 0),
+            onToggle,
+            onLoadMore,
+            onHeaderVisible,
+        }
+        : undefined;
+    const totals = totalsAnswer !== undefined
+        ? { measures: measuresOf(totalSpecs, totalsAnswer.groups[0]) }
+        : undefined;
+    const notice = noticeOf(groupsAnswer, totalsAnswer);
+    return {
+        grouped,
+        rows,
+        ...(serverGroups !== undefined && { serverGroups }),
+        ...(totals !== undefined && { totals }),
+        ...(notice !== undefined && { notice }),
+        groupPages: { queryType, requests, onResult, refreshNonce },
+        refresh,
+        loading: grouped && groupsAnswer === undefined && groupsError === null,
+        error: groupsError,
+    };
+}

package/dist/hooks/use-list-table.d.ts

@@ -0,0 +1,38 @@
+import type { ListTableOptions } from "@cosmicdrift/kumiko-types/screen";
+import type { DataTableExport, DataTableResetAll, DataTableViewOptions } from "../data-table-view-types.ts";
+import { type ListViewSchemaColumn } from "./use-list-view-state.ts";
+type ListTableArgs = {
+    readonly storeKey: string;
+    /** Undefined: the list has no `table` block and nothing below is active. */
+    readonly table: ListTableOptions | undefined;
+    /** Must be referentially stable across renders. */
+    readonly schemaColumns: readonly ListViewSchemaColumn[];
+    /** URL-backed list (entityList, projectionList): reset clears the `<screenId>.*` keys. */
+    readonly url?: {
+        readonly screenId: string;
+    };
+    /** List with component-local state (relatedList): the owner resets it. */
+    readonly local?: {
+        readonly atDefault: boolean;
+        readonly reset: () => void;
+    };
+    /** Screen identity and current list payload; used only when `table.export.xlsx` is on. */
+    readonly exportSource?: {
+        readonly screen: string;
+        readonly screenShortId: string;
+        readonly payload: Readonly<Record<string, unknown>>;
+    };
+};
+export type ListTableProps = {
+    readonly view?: DataTableViewOptions;
+    readonly resetAll?: DataTableResetAll;
+    readonly exportList?: DataTableExport;
+};
+export type ListTableState = {
+    readonly props: ListTableProps;
+    /** Field the list is grouped by right now; undefined = ungrouped. */
+    readonly groupField: string | undefined;
+};
+/** Props for the DataTable's `view` / `resetAll` from a screen's `table` block. */
+export declare function useListTable({ storeKey, table, schemaColumns, url, local, exportSource, }: ListTableArgs): ListTableState;
+export {};

package/dist/hooks/use-list-table.js

@@ -0,0 +1,91 @@
+import { useCallback, useMemo } from "react";
+import { useNav } from "../app/nav.js";
+import { useListStateStore } from "../components/list-state-store.js";
+import { isListStateAtDefault, listResetUpdates } from "./list-reset.js";
+import { useListViewState } from "./use-list-view-state.js";
+const NO_TABLE_OPTIONS = {};
+const PAGING_PAYLOAD_KEYS = ["limit", "offset", "cursor", "totalCount", "filter"];
+function withoutPaging(payload) {
+    const kept = { ...payload };
+    for (const key of PAGING_PAYLOAD_KEYS)
+        delete kept[key];
+    return kept;
+}
+/** Props for the DataTable's `view` / `resetAll` from a screen's `table` block. */
+export function useListTable({ storeKey, table, schemaColumns, url, local, exportSource, }) {
+    const nav = useNav();
+    const store = useListStateStore();
+    const options = table ?? NO_TABLE_OPTIONS;
+    const viewState = useListViewState({ storeKey, store, table: options, schemaColumns });
+    const urlParams = nav.searchParams;
+    const urlScreenId = url?.screenId;
+    const localAtDefault = local?.atDefault;
+    const localReset = local?.reset;
+    const atDefault = urlScreenId !== undefined
+        ? isListStateAtDefault(urlParams, urlScreenId)
+        : (localAtDefault ?? true);
+    // The remembered view (columns, density) survives: "reset view" is its own action.
+    const onReset = useCallback(() => {
+        if (urlScreenId !== undefined)
+            nav.setSearchParams(listResetUpdates(urlParams, urlScreenId));
+        localReset?.();
+        const { params: _forgotten, ...kept } = store.read(storeKey) ?? {};
+        if (kept.view === undefined)
+            store.remove(storeKey);
+        else
+            store.write(storeKey, kept);
+    }, [nav, urlParams, urlScreenId, localReset, store, storeKey]);
+    const resetAll = useMemo(() => (options.resetAll === true ? { active: !atDefault, onReset } : undefined), [options.resetAll, atDefault, onReset]);
+    const hasView = options.columnPicker === true ||
+        options.density !== undefined ||
+        options.pinning === true ||
+        options.resizing === true ||
+        options.keyboardNavigation === true ||
+        viewState.groupByFields !== undefined;
+    const view = useMemo(() => hasView
+        ? {
+            ...(viewState.columns !== undefined && {
+                columns: viewState.columns,
+                onColumnsChange: viewState.setColumns,
+            }),
+            density: viewState.density,
+            ...(viewState.userChoosesDensity && { onDensityChange: viewState.setDensity }),
+            ...(viewState.pins !== undefined && {
+                pins: viewState.pins,
+                onPinsChange: viewState.setPins,
+            }),
+            ...(viewState.widths !== undefined &&
+                viewState.minWidths !== undefined && {
+                widths: viewState.widths,
+                minWidths: viewState.minWidths,
+                onWidthChange: viewState.setWidth,
+            }),
+            ...(options.keyboardNavigation === true && { keyboardNavigation: true }),
+            ...(viewState.groupByFields !== undefined && {
+                groupBy: {
+                    value: viewState.groupBy,
+                    fields: viewState.groupByFields,
+                    onChange: viewState.setGroupBy,
+                },
+            }),
+            viewIsDefault: viewState.viewIsDefault,
+            onViewReset: viewState.resetView,
+        }
+        : undefined, [hasView, viewState, options.keyboardNavigation]);
+    const exportEnabled = options.export?.xlsx === true;
+    const viewColumns = viewState.columns;
+    const exportList = useMemo(() => {
+        if (!exportEnabled || exportSource === undefined)
+            return undefined;
+        const ordered = viewColumns?.filter((column) => column.visible).map((column) => column.field) ??
+            schemaColumns.map((column) => column.field);
+        return { ...exportSource, payload: withoutPaging(exportSource.payload), columns: ordered };
+    }, [exportEnabled, exportSource, viewColumns, schemaColumns]);
+    const props = useMemo(() => ({
+        ...(view !== undefined && { view }),
+        ...(resetAll !== undefined && { resetAll }),
+        ...(exportList !== undefined && { exportList }),
+    }), [view, resetAll, exportList]);
+    const groupField = options.grouping !== undefined && viewState.groupBy !== "" ? viewState.groupBy : undefined;
+    return { props, groupField };
+}