@cosmicdrift/kumiko-renderer 0.387.0 → 0.389.0

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 };
+}

package/dist/hooks/use-list-view-state.d.ts

@@ -0,0 +1,43 @@
+import type { ListColumnPin, ListColumnSpec, ListTableOptions } from "@cosmicdrift/kumiko-types/screen";
+import type { ListStateStore } from "../components/list-state-store.tsx";
+import type { DataTableColumnPins, DataTableColumnWidths, DataTableDensity, DataTableViewColumn } from "../data-table-view-types.ts";
+export type ListViewSchemaColumn = {
+    readonly field: string;
+    readonly hidden?: boolean;
+    readonly pinned?: ListColumnPin;
+    readonly width?: number;
+    readonly minWidth?: number;
+};
+export type ListViewState = {
+    /** Undefined unless `table.columnPicker` is on. */
+    readonly columns: readonly DataTableViewColumn[] | undefined;
+    readonly density: DataTableDensity;
+    readonly userChoosesDensity: boolean;
+    readonly setColumns: (next: readonly DataTableViewColumn[]) => void;
+    readonly setDensity: (next: DataTableDensity) => void;
+    /** Undefined unless `table.pinning` is on. */
+    readonly pins: DataTableColumnPins | undefined;
+    readonly setPins: (next: DataTableColumnPins) => void;
+    /** Undefined unless `table.resizing` is on. */
+    readonly widths: DataTableColumnWidths | undefined;
+    readonly minWidths: DataTableColumnWidths | undefined;
+    readonly setWidth: (field: string, width: number) => void;
+    /** Active group field, "" = not grouped. */
+    readonly groupBy: string;
+    /** Undefined unless `table.grouping.userChoice` is on. */
+    readonly groupByFields: readonly string[] | undefined;
+    readonly setGroupBy: (next: string) => void;
+    readonly resetView: () => void;
+    readonly viewIsDefault: boolean;
+};
+export declare function listViewSchemaColumns(columns: readonly ListColumnSpec[]): ListViewSchemaColumn[];
+type ViewStateArgs = {
+    readonly storeKey: string;
+    readonly store: ListStateStore;
+    readonly table: ListTableOptions;
+    readonly schemaColumns: readonly ListViewSchemaColumn[];
+};
+/** Column choice, order and density of one list. Lives in the list-state store
+ *  (never in the URL) and is independent of `rememberState`. */
+export declare function useListViewState(args: ViewStateArgs): ListViewState;
+export {};

package/dist/hooks/use-list-view-state.js

@@ -0,0 +1,161 @@
+import { normalizeListColumn } from "@cosmicdrift/kumiko-framework/ui-types";
+import { useCallback, useMemo, useState } from "react";
+import { clampWidth, DEFAULT_MIN_COLUMN_WIDTH_PX, defaultPins, defaultWidths, mergeSavedWidths, minWidthsOf, sameRecord, } from "./list-column-layout.js";
+import { sanitizeStoredListState } from "./list-state-schema.js";
+export function listViewSchemaColumns(columns) {
+    return columns.map((column) => {
+        const { field, hidden, pinned, width, minWidth } = normalizeListColumn(column);
+        return {
+            field,
+            ...(hidden === true && { hidden }),
+            ...(pinned !== undefined && { pinned }),
+            ...(width !== undefined && { width }),
+            ...(minWidth !== undefined && { minWidth }),
+        };
+    });
+}
+function schemaDefaultColumns(schema) {
+    return schema.map((column) => ({ field: column.field, visible: column.hidden !== true }));
+}
+/** Saved order wins; a column the saved view has never seen takes its schema
+ *  position (after its schema predecessor) with its schema default. */
+function mergeSavedColumns(schema, saved) {
+    const merged = [...saved];
+    const present = new Set(saved.map((column) => column.field));
+    schema.forEach((column, index) => {
+        // skip: column already saved
+        if (present.has(column.field))
+            return;
+        const predecessor = schema[index - 1];
+        const predecessorAt = predecessor === undefined ? -1 : merged.findIndex((m) => m.field === predecessor.field);
+        merged.splice(predecessorAt + 1, 0, {
+            field: column.field,
+            visible: column.hidden !== true,
+        });
+        present.add(column.field);
+    });
+    return merged;
+}
+function sameColumns(a, b) {
+    return (a.length === b.length &&
+        a.every((c, i) => c.field === b[i]?.field && c.visible === b[i]?.visible));
+}
+function hasVisibleColumn(columns) {
+    return columns.some((column) => column.visible);
+}
+function groupByChoices(grouping) {
+    if (grouping?.userChoice !== true)
+        return undefined;
+    const offered = [
+        ...(grouping.field !== undefined ? [grouping.field] : []),
+        ...(grouping.fields ?? []),
+    ];
+    return [...new Set(offered)];
+}
+function isOfferedGroupBy(grouping, saved) {
+    if (saved === undefined)
+        return false;
+    const choices = groupByChoices(grouping);
+    return choices !== undefined && (saved === "" || choices.includes(saved));
+}
+function readInitialView(args, defaults) {
+    const saved = sanitizeStoredListState(args.store.read(args.storeKey), {
+        columnFields: args.schemaColumns.map((column) => column.field),
+        filterFields: [],
+    })?.view;
+    const savedGroupBy = saved?.groupBy;
+    const merged = args.table.columnPicker === true && saved?.columns !== undefined
+        ? mergeSavedColumns(args.schemaColumns, saved.columns)
+        : defaults.columns;
+    return {
+        columns: hasVisibleColumn(merged) ? merged : defaults.columns,
+        density: args.table.density?.userChoice === true && saved?.density ? saved.density : defaults.density,
+        // Saved pins replace the schema pins entirely, so the user can release a schema pin.
+        pins: args.table.pinning === true && saved?.pins !== undefined ? saved.pins : defaults.pins,
+        widths: args.table.resizing === true && saved?.widths !== undefined
+            ? mergeSavedWidths(defaults.widths, saved.widths, minWidthsOf(args.schemaColumns))
+            : defaults.widths,
+        groupBy: isOfferedGroupBy(args.table.grouping, savedGroupBy) ? savedGroupBy : defaults.groupBy,
+    };
+}
+/** Column choice, order and density of one list. Lives in the list-state store
+ *  (never in the URL) and is independent of `rememberState`. */
+export function useListViewState(args) {
+    const { storeKey, store, table, schemaColumns } = args;
+    const columnPicker = table.columnPicker === true;
+    const userChoosesDensity = table.density?.userChoice === true;
+    const pinning = table.pinning === true;
+    const resizing = table.resizing === true;
+    const groupByFields = useMemo(() => groupByChoices(table.grouping), [table.grouping]);
+    const userChoosesGroupBy = groupByFields !== undefined;
+    const minWidths = useMemo(() => minWidthsOf(schemaColumns), [schemaColumns]);
+    const defaults = useMemo(() => ({
+        columns: schemaDefaultColumns(schemaColumns),
+        density: table.density?.default ?? "comfortable",
+        pins: pinning ? defaultPins(schemaColumns) : {},
+        widths: resizing ? defaultWidths(schemaColumns, minWidths) : {},
+        groupBy: table.grouping?.field ?? "",
+    }), [schemaColumns, table.density?.default, pinning, resizing, minWidths, table.grouping?.field]);
+    const [seeded, setSeeded] = useState(() => ({
+        storeKey,
+        view: readInitialView(args, defaults),
+    }));
+    const view = seeded.storeKey === storeKey ? seeded.view : readInitialView(args, defaults);
+    if (seeded.storeKey !== storeKey)
+        setSeeded({ storeKey, view });
+    const commit = useCallback((next) => {
+        setSeeded({ storeKey, view: next });
+        store.write(storeKey, {
+            ...store.read(storeKey),
+            view: {
+                ...(columnPicker && { columns: next.columns }),
+                ...(userChoosesDensity && { density: next.density }),
+                ...(pinning && { pins: next.pins }),
+                ...(resizing && { widths: next.widths }),
+                ...(userChoosesGroupBy && { groupBy: next.groupBy }),
+            },
+        });
+    }, [store, storeKey, columnPicker, userChoosesDensity, pinning, resizing, userChoosesGroupBy]);
+    const setColumns = useCallback((next) => {
+        // skip: a view must keep at least one visible column
+        if (!hasVisibleColumn(next))
+            return;
+        commit({ ...view, columns: next });
+    }, [commit, view]);
+    const setDensity = useCallback((next) => commit({ ...view, density: next }), [commit, view]);
+    const setPins = useCallback((next) => commit({ ...view, pins: next }), [commit, view]);
+    const setWidth = useCallback((field, width) => commit({
+        ...view,
+        widths: {
+            ...view.widths,
+            [field]: clampWidth(width, minWidths[field] ?? DEFAULT_MIN_COLUMN_WIDTH_PX),
+        },
+    }), [commit, view, minWidths]);
+    const setGroupBy = useCallback((next) => commit({ ...view, groupBy: next }), [commit, view]);
+    const resetView = useCallback(() => {
+        setSeeded({ storeKey, view: defaults });
+        const { view: _dropped, ...rest } = store.read(storeKey) ?? {};
+        store.write(storeKey, rest);
+    }, [store, storeKey, defaults]);
+    return {
+        columns: columnPicker ? view.columns : undefined,
+        density: view.density,
+        userChoosesDensity,
+        setColumns,
+        setDensity,
+        pins: pinning ? view.pins : undefined,
+        setPins,
+        widths: resizing ? view.widths : undefined,
+        minWidths: resizing ? minWidths : undefined,
+        setWidth,
+        groupBy: view.groupBy,
+        groupByFields,
+        setGroupBy,
+        resetView,
+        viewIsDefault: view.density === defaults.density &&
+            (!columnPicker || sameColumns(view.columns, defaults.columns)) &&
+            (!pinning || sameRecord(view.pins, defaults.pins)) &&
+            (!resizing || sameRecord(view.widths, defaults.widths)) &&
+            view.groupBy === defaults.groupBy,
+    };
+}

package/dist/hooks/use-reference-lookup.d.ts

@@ -13,10 +13,18 @@ export declare function referenceOptionSource(field: {
     readonly queryQn: string;
     readonly labelKey: string;
 };
-/** Empty while the query loads (or fails), so callers fall back to the raw id.
+export declare function isCompleteRowPage(data: {
+    readonly nextCursor?: string | null;
+} | null): boolean;
+/** `map` holds the resolved labels; while the query loads or has failed an id is
+ *  simply not in it. Callers decide the fallback: the raw id, or the "Unknown"
+ *  label for entities listed in `UNRESOLVED_REFERENCE_LABEL_KEYS` once the
+ *  lookup is complete.
  *  `featureName` is the reference's target feature, not the screen's. */
 export declare function useReferenceLookup(featureName: string, refEntity: string, labelField: string): {
     readonly map: ReferenceLookupMap;
     readonly loading: boolean;
     readonly failed: boolean;
+    /** False when the lookup page was capped: absent ids may still exist. */
+    readonly complete: boolean;
 };

package/dist/hooks/use-reference-lookup.js

@@ -9,7 +9,8 @@
 //     of N+1) but would have to extend the executor API with lookupTables.
 //     The renderer-side path wins for the MVP.
 //   - limit:200 is a hard UX limit: with more entries in the referenced
-//     entity, the last rows show only UUIDs. A searchable combobox plus a
+//     entity, the last rows fall back to the raw id (or "Unknown" for
+//     opt-in entities once the lookup is complete). A searchable combobox plus a
 //     server-side eager load with an ID whitelist will lift that later.
 //
 // The hook is call-stable: useQuery's internal cache shares the lookup map
@@ -44,7 +45,15 @@ export function referenceOptionSource(field, refFeature, refEntity) {
     }
     return referenceLookupSource(refFeature, refEntity, field.refLabelField ?? "id");
 }
-/** Empty while the query loads (or fails), so callers fall back to the raw id.
+// A page with a continuation cursor is only a prefix of the referenced rows,
+// so a missing id in it proves nothing about the row's existence.
+export function isCompleteRowPage(data) {
+    return data !== null && (data.nextCursor ?? null) === null;
+}
+/** `map` holds the resolved labels; while the query loads or has failed an id is
+ *  simply not in it. Callers decide the fallback: the raw id, or the "Unknown"
+ *  label for entities listed in `UNRESOLVED_REFERENCE_LABEL_KEYS` once the
+ *  lookup is complete.
  *  `featureName` is the reference's target feature, not the screen's. */
 export function useReferenceLookup(featureName, refEntity, labelField) {
     const { queryQn, labelKey } = referenceLookupSource(featureName, refEntity, labelField);
@@ -72,5 +81,10 @@ export function useReferenceLookup(featureName, refEntity, labelField) {
         }
         return out;
     }, [result.data, labelKey, systemLabel, translate]);
-    return { map, loading: result.loading, failed: result.error !== null };
+    return {
+        map,
+        loading: result.loading,
+        failed: result.error !== null,
+        complete: isCompleteRowPage(result.data),
+    };
 }

package/dist/hooks/use-related-list-rows.d.ts

@@ -0,0 +1,27 @@
+import type { EditRelatedListSectionViewModel, Translate } from "../headless/index.ts";
+import type { DataTableSort } from "../primitives.tsx";
+import { type ListAggregates } from "./use-list-aggregates.ts";
+type Row = Readonly<Record<string, unknown>>;
+export type RelatedListRows = {
+    readonly rows: readonly Row[];
+    readonly firstLoad: boolean;
+    readonly error: ListAggregates["error"];
+    readonly hasData: boolean;
+    /** The one-shot fetch stopped early, so the client-side sort covers part of the set. */
+    readonly truncated: boolean;
+    readonly aggregates: ListAggregates;
+    readonly refetchSelfAndHost: () => Promise<void>;
+};
+/** Rows of a relatedList section: one fetch sorted on the client, or the loaded
+ *  rows of its server groups in server order when `table.grouping` is active. */
+export declare function useRelatedListRows(args: {
+    readonly section: EditRelatedListSectionViewModel;
+    readonly payload: Readonly<Record<string, unknown>>;
+    readonly groupField: string | undefined;
+    readonly sort: DataTableSort | null;
+    readonly locale: string | undefined;
+    readonly refreshToken: unknown;
+    readonly onAfterWrite: (() => Promise<void> | void) | undefined;
+    readonly translate: Translate;
+}): RelatedListRows;
+export {};

package/dist/hooks/use-related-list-rows.js

@@ -0,0 +1,81 @@
+import { normalizeListColumn } from "@cosmicdrift/kumiko-framework/ui-types";
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import { sortByAccessor } from "../sort-by-accessor.js";
+import { useListAggregates } from "./use-list-aggregates.js";
+import { useQuery } from "./use-query.js";
+const DEFAULT_GROUP_PAGE_SIZE = 50;
+// A handler that omits `nextCursor` (or reports a `total` the fetched rows
+// already cover) has no further rows; only a real cursor marks truncation.
+function isTruncatedFetch(data) {
+    return (data !== null &&
+        typeof data.nextCursor === "string" &&
+        (data.total === undefined || data.total > data.rows.length));
+}
+/** Rows of a relatedList section: one fetch sorted on the client, or the loaded
+ *  rows of its server groups in server order when `table.grouping` is active. */
+export function useRelatedListRows(args) {
+    const { section, payload, groupField, sort, locale, refreshToken, onAfterWrite } = args;
+    const aggregates = useListAggregates({
+        queryType: section.query,
+        payload,
+        table: section.table,
+        groupField,
+        pageSize: section.pageSize ?? DEFAULT_GROUP_PAGE_SIZE,
+        paging: "cursor",
+        translate: args.translate,
+    });
+    const { grouped, refresh: refreshAggregates } = aggregates;
+    const rowsQuery = useQuery(section.query, payload, { enabled: !grouped });
+    const ownRefetch = rowsQuery.refetch;
+    const refetchOwn = useCallback(async () => {
+        refreshAggregates();
+        if (!grouped)
+            await ownRefetch();
+    }, [refreshAggregates, grouped, ownRefetch]);
+    const lastRefreshTokenRef = useRef(refreshToken);
+    useEffect(() => {
+        // skip: the token has not changed since the last refetch
+        if (lastRefreshTokenRef.current === refreshToken)
+            return;
+        lastRefreshTokenRef.current = refreshToken;
+        void refetchOwn();
+    }, [refreshToken, refetchOwn]);
+    const refetchSelfAndHost = useCallback(async () => {
+        await refetchOwn();
+        await onAfterWrite?.();
+    }, [refetchOwn, onAfterWrite]);
+    const sortAccessors = useMemo(() => {
+        const accessors = {};
+        for (const col of section.columns) {
+            const field = normalizeListColumn(col).field;
+            accessors[field] = (row) => {
+                const value = row[field];
+                if (value === null || value === undefined)
+                    return null;
+                return typeof value === "number" ? value : String(value);
+            };
+        }
+        return accessors;
+    }, [section.columns]);
+    const sortedRows = useMemo(() => sortByAccessor(rowsQuery.data?.rows ?? [], sort, sortAccessors, locale), [rowsQuery.data, sort, sortAccessors, locale]);
+    if (grouped) {
+        return {
+            rows: aggregates.rows,
+            firstLoad: aggregates.loading,
+            error: aggregates.error,
+            hasData: aggregates.serverGroups !== undefined,
+            truncated: false,
+            aggregates,
+            refetchSelfAndHost,
+        };
+    }
+    return {
+        rows: sortedRows,
+        firstLoad: rowsQuery.loading && rowsQuery.data === null,
+        error: rowsQuery.error,
+        hasData: rowsQuery.data !== null,
+        truncated: isTruncatedFetch(rowsQuery.data),
+        aggregates,
+        refetchSelfAndHost,
+    };
+}

package/dist/hooks/use-related-list-state.d.ts

@@ -0,0 +1,15 @@
+import type { EditRelatedListSectionViewModel } from "../headless/index.ts";
+/** Search, filters and sort of a relatedList section (component-local: it has
+ *  no URL namespace) plus the DataTable props of its `table` block. */
+export declare function useRelatedListState(section: EditRelatedListSectionViewModel, parentScreenId: string | undefined): {
+    search: string;
+    filters: Readonly<Record<string, readonly string[]>>;
+    sort: import("./use-list-url-state.ts").ListSort | null;
+    setSearch: (search: string) => void;
+    setFilters: import("react").Dispatch<import("react").SetStateAction<Readonly<Record<string, readonly string[]>>>>;
+    setSort: (sort: import("./use-list-url-state.ts").ListSort | null) => void;
+    reset: () => void;
+    atDefault: boolean;
+    listTable: import("./use-list-table.ts").ListTableProps;
+    groupField: string | undefined;
+};

package/dist/hooks/use-related-list-state.js

@@ -0,0 +1,31 @@
+import { useMemo } from "react";
+import { useListStateStore } from "../components/list-state-store.js";
+import { useListTable } from "./use-list-table.js";
+import { listViewSchemaColumns } from "./use-list-view-state.js";
+import { useRememberedLocalListState } from "./use-remembered-local-list-state.js";
+/** Search, filters and sort of a relatedList section (component-local: it has
+ *  no URL namespace) plus the DataTable props of its `table` block. */
+export function useRelatedListState(section, parentScreenId) {
+    const store = useListStateStore();
+    const storeKey = `${parentScreenId ?? ""}#${section.id ?? section.query}`;
+    const defaultSort = useMemo(() => section.defaultSort ?? null, [section.defaultSort]);
+    const schemaColumns = useMemo(() => listViewSchemaColumns(section.columns), [section.columns]);
+    const known = useMemo(() => ({
+        columnFields: schemaColumns.map((column) => column.field),
+        filterFields: (section.facets ?? []).map((facet) => facet.field),
+    }), [schemaColumns, section.facets]);
+    const local = useRememberedLocalListState({
+        storeKey,
+        store,
+        remember: section.table?.rememberState === true,
+        defaultSort,
+        known,
+    });
+    const { props: listTable, groupField } = useListTable({
+        storeKey,
+        table: section.table,
+        schemaColumns,
+        local: { atDefault: local.atDefault, reset: local.reset },
+    });
+    return { ...local, listTable, groupField };
+}