@cosmicdrift/kumiko-renderer 0.388.0 → 0.390.0

package/dist/components/use-render-list-columns.d.ts

@@ -0,0 +1,18 @@
+import type { EntityDefinition, EntityListScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { ListColumnViewModel, ListViewModel, Translate } from "../headless/index.ts";
+import { type PublishedReferenceLookup } from "./render-list-reference-columns.ts";
+type RenderListColumnsInput = {
+    readonly screen: EntityListScreenDefinition;
+    readonly entity: Pick<EntityDefinition, "fields" | "derivedFields">;
+    readonly rows: readonly Readonly<Record<string, unknown>>[];
+    readonly featureName: string;
+    readonly translate: Translate;
+};
+export declare function useRenderListColumns(input: RenderListColumnsInput): {
+    referenceColumns: import("./render-list-reference-columns.ts").ReferenceColumnSpec[];
+    handleLookupMap: (field: string, lookup: PublishedReferenceLookup) => void;
+    enrichedVm: Omit<ListViewModel, "columns"> & {
+        columns: readonly ListColumnViewModel[];
+    };
+};
+export {};

package/dist/components/use-render-list-columns.js

@@ -0,0 +1,41 @@
+import { useCallback, useMemo, useState } from "react";
+import { useReferenceLinkResolver } from "../app/reference-link.js";
+import { computeListViewModel } from "../headless/index.js";
+import { enrichReferenceColumns, selectReferenceColumns, } from "./render-list-reference-columns.js";
+export function useRenderListColumns(input) {
+    const { screen, entity, rows, featureName, translate } = input;
+    const vm = useMemo(() => computeListViewModel({ screen, entity, rows, translate, featureName }), [screen, entity, rows, translate, featureName]);
+    // Reference-field eager loading through bridge components.
+    // The Hooks rule requires useReferenceLookup for each reference column,
+    // but the number of columns varies with the schema. Each column therefore
+    // mounts a ReferenceLookupBridge that publishes its map to local state
+    // through onMap. Each bridge makes a constant number of hook calls (one),
+    // and React manages its lifecycle when the schema changes via key.
+    const referenceColumns = useMemo(() => selectReferenceColumns(vm.columns, featureName), [vm.columns, featureName]);
+    const [referenceLookups, setReferenceLookups] = useState({});
+    const handleLookupMap = useCallback((field, lookup) => {
+        setReferenceLookups((prev) => {
+            // Skip the update when the lookup is identical. Otherwise the bridge
+            // would re-render and send the same map back until React entered
+            // an infinite loop.
+            const current = prev[field];
+            if (current?.map === lookup.map && current.complete === lookup.complete)
+                return prev;
+            return { ...prev, [field]: lookup };
+        });
+    }, []);
+    const resolveReferenceLink = useReferenceLinkResolver();
+    const enrichedColumns = useMemo(() => enrichReferenceColumns({
+        columns: vm.columns,
+        referenceColumns,
+        referenceLookups,
+        resolveReferenceLink,
+        featureName,
+        translate,
+    }), [vm.columns, referenceColumns, referenceLookups, resolveReferenceLink, featureName, translate]);
+    const enrichedVm = useMemo(() => ({
+        ...vm,
+        columns: enrichedColumns,
+    }), [vm, enrichedColumns]);
+    return { referenceColumns, handleLookupMap, enrichedVm };
+}

package/dist/components/use-render-list-search.d.ts

@@ -0,0 +1,4 @@
+export declare function useRenderListSearch(searchValue: string | undefined, onSearchChange: ((next: string) => void) | undefined): {
+    readonly localQ: string;
+    readonly setLocalQ: (next: string) => void;
+};

package/dist/components/use-render-list-search.js

@@ -0,0 +1,50 @@
+import { useEffect, useRef, useState } from "react";
+const SEARCH_DEBOUNCE_MS = 300;
+// Local search buffer + debounce. External changes (browser back,
+// cross-component reset) are mirrored back; typing only fires
+// onSearchChange after 300ms without further keystrokes.
+export function useRenderListSearch(searchValue, onSearchChange) {
+    const [localQ, setLocalQ] = useState(searchValue ?? "");
+    // Sync during render, not in a useEffect: the passive effect also fires on
+    // mount and can flush after a keystroke landing in the same commit,
+    // resetting localQ and swallowing the input.
+    const [syncedSearchValue, setSyncedSearchValue] = useState(searchValue);
+    // The parent may echo our own debounced emits back late (router/URL round
+    // trip), possibly after a newer emit already went out; adopting such a stale
+    // echo would erase keys typed in between. All unechoed emits are kept, and a
+    // matching echo drops itself and every older one. The render phase only reads
+    // the list (a discarded or repeated render must find the echo again); the
+    // matched entries are dropped in an effect.
+    const pendingEmitsRef = useRef([]);
+    if (searchValue !== syncedSearchValue) {
+        setSyncedSearchValue(searchValue);
+        if (!pendingEmitsRef.current.includes(searchValue ?? "")) {
+            setLocalQ(searchValue ?? "");
+            pendingEmitsRef.current = [];
+        }
+    }
+    useEffect(() => {
+        const echoIndex = pendingEmitsRef.current.indexOf(syncedSearchValue ?? "");
+        if (echoIndex >= 0)
+            pendingEmitsRef.current.splice(0, echoIndex + 1);
+    }, [syncedSearchValue]);
+    useEffect(() => {
+        // skip: no search handler wired, so typing never emits
+        if (onSearchChange === undefined)
+            return;
+        // skip: buffer already matches the parent value
+        if (localQ === (searchValue ?? ""))
+            return;
+        // A late echo of an older emit changes searchValue but must not re-send
+        // the value that is already in flight.
+        // skip: that value is already in flight
+        if (pendingEmitsRef.current.at(-1) === localQ)
+            return;
+        const timer = setTimeout(() => {
+            pendingEmitsRef.current.push(localQ);
+            onSearchChange(localQ);
+        }, SEARCH_DEBOUNCE_MS);
+        return () => clearTimeout(timer);
+    }, [localQ, searchValue, onSearchChange]);
+    return { localQ, setLocalQ };
+}

package/dist/current-user.d.ts

@@ -7,6 +7,8 @@ export type CurrentUser = {
     readonly displayName: string;
     /** Effective IANA zone of the user (override, else tenant). */
     readonly timeZone?: string;
+    /** Active tenant; scopes per-user browser state such as remembered list views. */
+    readonly tenantId?: string;
 };
 export declare function CurrentUserProvider({ user, children, }: {
     readonly user: CurrentUser | undefined;

package/dist/data-table-aggregate-types.d.ts

@@ -0,0 +1,47 @@
+import type { AggregateKey } from "@cosmicdrift/kumiko-types/aggregate-types";
+import type { ListAggregateMeasureKind, ListAggregateValue } from "@cosmicdrift/kumiko-types/list-aggregate-types";
+/** One server-computed measure; a money measure holds one minor-unit value per currency. */
+export type DataTableMeasure = {
+    readonly field: string;
+    readonly kind: ListAggregateMeasureKind;
+    readonly value: ListAggregateValue;
+};
+export type DataTableServerGroup = {
+    /** `relatedListGroupKey` of the group value; stable across reloads. */
+    readonly key: string;
+    /** Raw group value, rendered through the group column when `label` is absent. */
+    readonly value: AggregateKey;
+    readonly label?: string;
+    /** Rows of the whole group on the server, not the loaded ones. */
+    readonly count: number;
+    readonly measures: readonly DataTableMeasure[];
+    readonly collapsed: boolean;
+    /** How many of the table's `rows` belong to this group; rows arrive in group order. */
+    readonly rowCount: number;
+    readonly hasMore: boolean;
+    readonly loading: boolean;
+};
+/** Server-side grouping: groups are the load unit, each loads its own rows. */
+export type DataTableServerGroups = {
+    readonly field: string;
+    readonly groups: readonly DataTableServerGroup[];
+    readonly totalCount: number;
+    readonly onToggle: (key: string) => void;
+    readonly onLoadMore: (key: string) => void;
+    readonly onHeaderVisible: (key: string) => void;
+};
+export type DataTableTotals = {
+    readonly measures: readonly DataTableMeasure[];
+};
+/** `truncated`: more groups than the server answers. `searchTruncated`: the search hit its cap. */
+export type DataTableListNotice = "truncated" | "searchTruncated";
+export type DataTableRangeBound = "min" | "max";
+/** "From/to" inputs on a number field. Values are the typed strings, "" = open bound. */
+export type DataTableRangeFacet = {
+    readonly field: string;
+    readonly label: string;
+    readonly min: string;
+    readonly max: string;
+    /** Shown after the inputs, e.g. the money field's currency. */
+    readonly unit?: string;
+};

package/dist/data-table-aggregate-types.js

@@ -0,0 +1 @@
+export {};

package/dist/data-table-bulk-types.d.ts

@@ -0,0 +1,27 @@
+import type { IconKey } from "@cosmicdrift/kumiko-types/nav-icon";
+import type { ListRowViewModel } from "./headless/index.ts";
+export type BulkRowOutcome = {
+    readonly kind: "succeeded";
+} | {
+    readonly kind: "failed";
+    readonly message: string;
+};
+export type DataTableBulkAction = {
+    readonly id: string;
+    /** Translated label of the underlying row action. */
+    readonly label: string;
+    readonly style?: "primary" | "secondary" | "danger";
+    readonly icon?: IconKey;
+    /** Present: one confirm dialog for the whole selection, with this text for `count` rows. */
+    readonly confirmText?: (count: number) => string;
+    readonly confirmLabel?: string;
+    /** False: the row action's `visible` hides it for this row; the run skips the row. */
+    readonly appliesTo: (row: ListRowViewModel) => boolean;
+    /** Exactly one server write for one row. Never throws for a rejected write. */
+    readonly writeRow: (row: ListRowViewModel) => Promise<BulkRowOutcome>;
+};
+export type DataTableBulk = {
+    readonly actions: readonly DataTableBulkAction[];
+    /** Reloads the list once after a run. */
+    readonly reload: () => Promise<void>;
+};

package/dist/data-table-bulk-types.js

@@ -0,0 +1 @@
+export {};

package/dist/data-table-facet-types.d.ts

@@ -0,0 +1,36 @@
+export type DataTableFacet = {
+    /** Entity-Feldname (= URL-State-Key + payload.filters[].field). */
+    readonly field: string;
+    /** Translated Button-Label ("Status", "Active"). */
+    readonly label: string;
+    /** Selectable values with display labels. `value` is the raw filter value
+     *  (a select option or `"true"`/`"false"`), transported as a string. */
+    readonly options: readonly {
+        readonly value: string;
+        readonly label: string;
+    }[];
+    /** Present: render the facet as a row of single-choice toggle chips instead
+     *  of a dropdown. A chip is pressed while the selection equals its values. */
+    readonly chips?: readonly DataTableFacetChip[];
+    /** Chips only: show each chip's `count` next to its label. */
+    readonly showCounts?: boolean;
+    /** Chips only: hide chips whose `count` is 0 (unless pressed). */
+    readonly hideEmpty?: boolean;
+};
+export type DataTableFacetChip = {
+    readonly id: string;
+    /** Translated chip label. */
+    readonly label: string;
+    /** Selection a click sets; `[]` clears the facet. */
+    readonly values: readonly string[];
+    /** Matching row count, undefined while unknown. */
+    readonly count?: number;
+};
+export type DataTableDateRangeFacet = {
+    /** The facet's namespace (its date field) — a key, not a filter value. */
+    readonly field: string;
+    /** Translated label ("When"). */
+    readonly label: string;
+    readonly from: string;
+    readonly to: string;
+};

package/dist/data-table-facet-types.js

@@ -0,0 +1 @@
+export {};

package/dist/data-table-view-types.d.ts

@@ -0,0 +1,73 @@
+import type { ListColumnPin, ListTableDensity } from "@cosmicdrift/kumiko-types/screen";
+import type { DataTableListNotice, DataTableRangeBound, DataTableRangeFacet, DataTableServerGroups, DataTableTotals } from "./data-table-aggregate-types.ts";
+export type DataTableDensity = ListTableDensity;
+export type DataTableColumnPin = ListColumnPin;
+export type DataTableColumnPins = Readonly<Record<string, DataTableColumnPin>>;
+export type DataTableColumnWidths = Readonly<Record<string, number>>;
+/** One column in the view menu. The label comes from the DataTable's own
+ *  column of the same `field`. */
+export type DataTableViewColumn = {
+    readonly field: string;
+    readonly visible: boolean;
+};
+export type DataTableViewOptions = {
+    /** Present: the view menu has a column section (visibility + order). The
+     *  order lists every column; hidden ones stay in the list. */
+    readonly columns?: readonly DataTableViewColumn[];
+    readonly onColumnsChange?: (next: readonly DataTableViewColumn[]) => void;
+    readonly density: DataTableDensity;
+    /** Present: the view menu has a density section. */
+    readonly onDensityChange?: (next: DataTableDensity) => void;
+    /** Present: pinning is on and the view menu has a pin section. Unpinned columns have no entry. */
+    readonly pins?: DataTableColumnPins;
+    readonly onPinsChange?: (next: DataTableColumnPins) => void;
+    /** Present: resizing is on; the table switches to table-layout fixed. Every column has an entry (px). */
+    readonly widths?: DataTableColumnWidths;
+    /** Present together with `widths`; every column has an entry (px). */
+    readonly minWidths?: DataTableColumnWidths;
+    readonly onWidthChange?: (field: string, width: number) => void;
+    readonly keyboardNavigation?: boolean;
+    /** Present: the view menu has a "group by" section. */
+    readonly groupBy?: DataTableGroupByChoice;
+    /** False once columns, order or density differ from the screen default. */
+    readonly viewIsDefault: boolean;
+    readonly onViewReset: () => void;
+};
+export type DataTableGroupByChoice = {
+    /** Active group field, "" = not grouped. */
+    readonly value: string;
+    readonly fields: readonly string[];
+    readonly onChange: (next: string) => void;
+};
+export type DataTableResetAll = {
+    /** True while something deviates from the screen default. */
+    readonly active: boolean;
+    readonly onReset: () => void;
+};
+/** What the export button sends to POST /api/export/xlsx (xlsx is the only format). */
+export type DataTableExport = {
+    /** Screen QN `<feature>:screen:<id>`. */
+    readonly screen: string;
+    readonly screenShortId: string;
+    /** The list payload without paging keys; the server reads the whole filtered list. */
+    readonly payload: Readonly<Record<string, unknown>>;
+    /** Visible column ids in display order. */
+    readonly columns: readonly string[];
+};
+/** The DataTable props a screen's `table` block feeds. */
+export type DataTableTableBlock = {
+    /** View menu (column picker, density); absent = no menu. */
+    readonly view?: DataTableViewOptions;
+    /** Replaces the facet reset with one that also covers sort, search and page size. */
+    readonly resetAll?: DataTableResetAll;
+    /** Present: the toolbar has an export button (web only). */
+    readonly exportList?: DataTableExport;
+    /** Present: the rows are grouped on the server; replaces pager and infinite scroll. */
+    readonly serverGroups?: DataTableServerGroups;
+    /** Present: a footer row with the server-computed totals of the filtered list. */
+    readonly totals?: DataTableTotals;
+    /** Present: the toolbar says the answer is incomplete and asks to narrow the list. */
+    readonly notice?: DataTableListNotice;
+    readonly rangeFacets?: readonly DataTableRangeFacet[];
+    readonly onRangeChange?: (field: string, bound: DataTableRangeBound, value: string) => void;
+};

package/dist/data-table-view-types.js

@@ -0,0 +1 @@
+export {};

package/dist/headless/view-model/edit.js

@@ -56,6 +56,7 @@ function wasEmptiedByWriteExclusion(declaredFieldSpecs, remainingFields) {
 export function computeRelatedListSectionViewModel(sectionSpec, translate) {
     return {
         kind: "relatedList",
+        ...(sectionSpec.id !== undefined && { id: sectionSpec.id }),
         title: translate(sectionSpec.title),
         query: sectionSpec.query,
         ...(sectionSpec.parentParam !== undefined && { parentParam: sectionSpec.parentParam }),
@@ -67,13 +68,14 @@ export function computeRelatedListSectionViewModel(sectionSpec, translate) {
         }),
         ...(sectionSpec.itemNoun !== undefined && { itemNoun: sectionSpec.itemNoun }),
         ...(sectionSpec.pageSize !== undefined && { pageSize: sectionSpec.pageSize }),
+        ...(sectionSpec.table !== undefined && { table: sectionSpec.table }),
         ...(sectionSpec.defaultSort !== undefined && { defaultSort: sectionSpec.defaultSort }),
         ...(sectionSpec.searchable !== undefined && { searchable: sectionSpec.searchable }),
         ...(sectionSpec.facets !== undefined && { facets: sectionSpec.facets }),
         ...(sectionSpec.rowClick !== undefined && { rowClick: sectionSpec.rowClick }),
         ...(sectionSpec.rowActions !== undefined && { rowActions: sectionSpec.rowActions }),
         ...(sectionSpec.rowActionMode !== undefined && { rowActionMode: sectionSpec.rowActionMode }),
-        ...(sectionSpec.groupBy !== undefined && { groupBy: sectionSpec.groupBy }),
+        ...(sectionSpec.bulkActions !== undefined && { bulkActions: sectionSpec.bulkActions }),
         ...(sectionSpec.rowTone !== undefined && { rowTone: sectionSpec.rowTone }),
         ...(sectionSpec.toolbarActions !== undefined && { toolbarActions: sectionSpec.toolbarActions }),
         ...(sectionSpec.actions !== undefined && { actions: sectionSpec.actions }),

package/dist/headless/view-model/types.d.ts

@@ -1,4 +1,4 @@
-import type { EditFieldSpec, EditSectionSpec, FieldAffix, FieldFillAction, FieldIconKey, FieldRenderer, IconKey, ListColumnSpec, ListFacetSpec, ListSortSpec, OptionsQueryPayload, PlatformComponent, RelatedListGroupBy, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionMode, ScreenSlots, SelectOptionTone } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { EditFieldSpec, EditSectionSpec, FieldAffix, FieldFillAction, FieldIconKey, FieldRenderer, IconKey, ListBulkAction, ListColumnSpec, ListFacetSpec, ListSortSpec, ListTableOptions, OptionsQueryPayload, PlatformComponent, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionMode, ScreenSlots, SelectOptionTone } from "@cosmicdrift/kumiko-framework/ui-types";
 export type RuntimeRenderer = (value: unknown, row?: Readonly<Record<string, unknown>>) => string;
 /** Where a cell's text links to. `href` comes from NavApi.hrefFor (new-tab and
  *  copy-link work); `onPress` is the in-app navigation for a plain click. */
@@ -333,6 +333,7 @@ export type EditExtensionSectionViewModel = {
 };
 export type EditRelatedListSectionViewModel = {
     readonly kind: "relatedList";
+    readonly id?: string;
     readonly title: string;
     readonly query: string;
     readonly parentParam?: string;
@@ -345,6 +346,7 @@ export type EditRelatedListSectionViewModel = {
     /** Untranslated plural-forms key, resolved with the row count by the list footer. */
     readonly itemNoun?: string;
     readonly pageSize?: number;
+    readonly table?: ListTableOptions;
     readonly defaultSort?: ListSortSpec;
     readonly searchable?: boolean;
     readonly facets?: readonly ListFacetSpec[];
@@ -354,7 +356,7 @@ export type EditRelatedListSectionViewModel = {
     };
     readonly rowActions?: readonly RowAction[];
     readonly rowActionMode?: RowActionMode;
-    readonly groupBy?: RelatedListGroupBy;
+    readonly bulkActions?: readonly ListBulkAction[];
     readonly rowTone?: RelatedListRowTone;
     readonly toolbarActions?: readonly RelatedListToolbarAction[];
     /** From `EditRelatedListSection.actions` — rendered in the

package/dist/hooks/list-column-layout.d.ts

@@ -0,0 +1,19 @@
+import type { DataTableColumnPin, DataTableColumnPins, DataTableColumnWidths } from "../data-table-view-types.ts";
+export declare const DEFAULT_COLUMN_WIDTH_PX = 160;
+export declare const DEFAULT_MIN_COLUMN_WIDTH_PX = 64;
+/** Upper bound so a tampered stored width cannot blow the table up. */
+export declare const MAX_COLUMN_WIDTH_PX = 2000;
+type LayoutSchemaColumn = {
+    readonly field: string;
+    readonly pinned?: DataTableColumnPin;
+    readonly width?: number;
+    readonly minWidth?: number;
+};
+export declare function defaultPins(schema: readonly LayoutSchemaColumn[]): DataTableColumnPins;
+export declare function minWidthsOf(schema: readonly LayoutSchemaColumn[]): DataTableColumnWidths;
+export declare function clampWidth(width: number, min: number): number;
+export declare function defaultWidths(schema: readonly LayoutSchemaColumn[], minWidths: DataTableColumnWidths): DataTableColumnWidths;
+/** A saved width wins per field; a column the saved view has never seen keeps its default. */
+export declare function mergeSavedWidths(defaults: DataTableColumnWidths, saved: Readonly<Record<string, number>>, minWidths: DataTableColumnWidths): DataTableColumnWidths;
+export declare function sameRecord<T>(a: Readonly<Record<string, T>>, b: Readonly<Record<string, T>>): boolean;
+export {};

package/dist/hooks/list-column-layout.js

@@ -0,0 +1,36 @@
+export const DEFAULT_COLUMN_WIDTH_PX = 160;
+export const DEFAULT_MIN_COLUMN_WIDTH_PX = 64;
+/** Upper bound so a tampered stored width cannot blow the table up. */
+export const MAX_COLUMN_WIDTH_PX = 2000;
+export function defaultPins(schema) {
+    const pins = {};
+    for (const column of schema) {
+        if (column.pinned !== undefined)
+            pins[column.field] = column.pinned;
+    }
+    return pins;
+}
+export function minWidthsOf(schema) {
+    return Object.fromEntries(schema.map((column) => [column.field, column.minWidth ?? DEFAULT_MIN_COLUMN_WIDTH_PX]));
+}
+export function clampWidth(width, min) {
+    return Math.min(MAX_COLUMN_WIDTH_PX, Math.max(min, Math.round(width)));
+}
+export function defaultWidths(schema, minWidths) {
+    return Object.fromEntries(schema.map((column) => [
+        column.field,
+        clampWidth(column.width ?? DEFAULT_COLUMN_WIDTH_PX, minWidths[column.field] ?? DEFAULT_MIN_COLUMN_WIDTH_PX),
+    ]));
+}
+/** A saved width wins per field; a column the saved view has never seen keeps its default. */
+export function mergeSavedWidths(defaults, saved, minWidths) {
+    return Object.fromEntries(Object.entries(defaults).map(([field, fallback]) => {
+        const savedWidth = saved[field];
+        const min = minWidths[field] ?? DEFAULT_MIN_COLUMN_WIDTH_PX;
+        return [field, savedWidth === undefined ? fallback : clampWidth(savedWidth, min)];
+    }));
+}
+export function sameRecord(a, b) {
+    const keys = Object.keys(a);
+    return keys.length === Object.keys(b).length && keys.every((key) => a[key] === b[key]);
+}

package/dist/hooks/list-group-pages.d.ts

@@ -0,0 +1,26 @@
+import type { AggregateKey } from "@cosmicdrift/kumiko-types/aggregate-types";
+/** How a group pages through its rows: offset for `pagination: "pages"`, cursor for `"infinite"`. */
+export type ListGroupPaging = "offset" | "cursor";
+export type ListGroupPageResult = {
+    readonly rows: readonly Readonly<Record<string, unknown>>[];
+    readonly nextCursor: string | null;
+    readonly loading: boolean;
+};
+export type ListGroupPageRequest = {
+    readonly pageKey: string;
+    readonly payload: Readonly<Record<string, unknown>>;
+};
+/** The list payload as the aggregate sees it: filters, search and screen filter, no paging. */
+export declare function withoutListPaging(payload: Readonly<Record<string, unknown>>): Record<string, unknown>;
+export declare function groupPageKey(groupKey: string, pageIndex: number): string;
+export declare function groupPagePayload(args: {
+    readonly base: Readonly<Record<string, unknown>>;
+    readonly groupField: string;
+    readonly groupValue: AggregateKey;
+    readonly pageSize: number;
+    readonly pageIndex: number;
+    readonly paging: ListGroupPaging;
+    readonly cursor: string | undefined;
+}): Record<string, unknown>;
+/** Loaded pages of one group in order, up to the first page that has not answered yet. */
+export declare function loadedGroupPages(results: ReadonlyMap<string, ListGroupPageResult>, groupKey: string, requestedPages: number): ListGroupPageResult[];

package/dist/hooks/list-group-pages.js

@@ -0,0 +1,37 @@
+const PAGING_KEYS = ["limit", "offset", "cursor", "totalCount"];
+/** The list payload as the aggregate sees it: filters, search and screen filter, no paging. */
+export function withoutListPaging(payload) {
+    const kept = { ...payload };
+    for (const key of PAGING_KEYS)
+        delete kept[key];
+    return kept;
+}
+export function groupPageKey(groupKey, pageIndex) {
+    return `${groupKey}#${pageIndex}`;
+}
+function existingFilters(base) {
+    const filters = base["filters"];
+    return Array.isArray(filters) ? filters : [];
+}
+export function groupPagePayload(args) {
+    const { base, groupField, groupValue, pageSize, pageIndex, paging, cursor } = args;
+    const offset = pageIndex * pageSize;
+    return {
+        ...base,
+        filters: [...existingFilters(base), { field: groupField, op: "eq", value: groupValue }],
+        limit: pageSize,
+        ...(paging === "offset" && offset > 0 && { offset }),
+        ...(paging === "cursor" && cursor !== undefined && { cursor }),
+    };
+}
+/** Loaded pages of one group in order, up to the first page that has not answered yet. */
+export function loadedGroupPages(results, groupKey, requestedPages) {
+    const pages = [];
+    for (let pageIndex = 0; pageIndex < requestedPages; pageIndex++) {
+        const page = results.get(groupPageKey(groupKey, pageIndex));
+        if (page === undefined)
+            break;
+        pages.push(page);
+    }
+    return pages;
+}

package/dist/hooks/list-reset.d.ts

@@ -0,0 +1,8 @@
+type UrlParams = Readonly<Record<string, string | undefined>>;
+/** Exact `${screenId}.` prefix: `orders` must not match `orders-archive.q`. */
+export declare function listParamKeys(params: UrlParams, screenId: string): string[];
+/** The page alone is navigation, not a deviation from the default view. */
+export declare function isListStateAtDefault(params: UrlParams, screenId: string): boolean;
+/** Nulling every list key lets defaultSort/defaultFilters apply again, and drops the `~` "no filter" markers. */
+export declare function listResetUpdates(params: UrlParams, screenId: string): Record<string, null>;
+export {};

package/dist/hooks/list-reset.js

@@ -0,0 +1,15 @@
+const PAGE_SUFFIX = "page";
+/** Exact `${screenId}.` prefix: `orders` must not match `orders-archive.q`. */
+export function listParamKeys(params, screenId) {
+    const prefix = `${screenId}.`;
+    return Object.keys(params).filter((key) => key.startsWith(prefix));
+}
+/** The page alone is navigation, not a deviation from the default view. */
+export function isListStateAtDefault(params, screenId) {
+    const pageKey = `${screenId}.${PAGE_SUFFIX}`;
+    return listParamKeys(params, screenId).every((key) => key === pageKey);
+}
+/** Nulling every list key lets defaultSort/defaultFilters apply again, and drops the `~` "no filter" markers. */
+export function listResetUpdates(params, screenId) {
+    return Object.fromEntries(listParamKeys(params, screenId).map((key) => [key, null]));
+}

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