@cosmicdrift/kumiko-renderer 0.387.0 → 0.389.0

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

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/live-refetch-scheduler.js

@@ -12,6 +12,10 @@ export function createLiveRefetchScheduler(run, windowMs = LIVE_REFETCH_COALESCE
         try {
             await run();
         }
+        catch {
+            // The caller surfaces its own load errors in state; a failed run must
+            // neither become an unhandled rejection nor drop the queued follow-up.
+        }
         finally {
             inFlight = false;
         }

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