@cosmicdrift/kumiko-renderer 0.387.0 → 0.389.0

package/dist/app/projection-list-body.js

@@ -1,19 +1,20 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useMemo, useState } from "react";
+import { ListGroupPageBridges } from "../components/list-group-page-bridges.js";
 import { RenderList } from "../components/render-list.js";
 import { useOptionalDispatcher } from "../context/dispatcher-context.js";
 import { useIsEmbeddedScreen } from "../context/embedded-screen-context.js";
 import { useUserRoles } from "../context/user-roles-context.js";
 import { useListUrlState } from "../hooks/use-list-url-state.js";
-import { useQuery } from "../hooks/use-query.js";
-import { useOptionalTimeZone, useTranslation } from "../i18n.js";
-import { usePrimitives, } from "../primitives.js";
+import { useTranslation } from "../i18n.js";
+import { usePrimitives } from "../primitives.js";
 import { screenFillsHeight } from "../screen-fills-height.js";
 import { DrawerHost, useDrawerAction } from "./action-form-body.js";
 import { useAppFeatures } from "./app-features-context.js";
 import { useClientActionRuntime } from "./client-actions.js";
+import { useListBulk } from "./list-bulk-actions.js";
 import { isListNarrowed, useListEmptyContent } from "./list-empty-content.js";
-import { buildDateRangePayload, buildFilterFacets, buildFilterPayload, clampDateRange, mergeReferenceFacetOptions, readDateRange, resolveDateRangeFacets, resolveProjectionFacetSpecs, } from "./list-facets.js";
+import { buildFilterFacets, buildFilterPayload, mergeReferenceFacetOptions, resolveProjectionFacetSpecs, } from "./list-facets.js";
 import { useNav } from "./nav.js";
 import { synthesizeProjectionEntity, synthesizeProjectionScreen } from "./projection-list-shim.js";
 import { QueryErrorBanner, QueryLoadingBanner } from "./query-state-banners.js";
@@ -21,7 +22,10 @@ import { ReferenceFacetBridges } from "./reference-facet-bridge.js";
 import { useReturnHost } from "./return-to.js";
 import { buildDefaultEditRowAction, buildProjectionRowActions, buildProjectionToolbarActions, findRowClickAction, runDrawerRowAction, runProjectionRowNavigate, } from "./row-actions.js";
 import { findEditScreenFor } from "./screen-access.js";
-import { buildListQueryPayload, pageSizeOptionsFor } from "./screen-shared.js";
+import { buildListQueryPayload } from "./screen-shared.js";
+import { useProjectionDateRange } from "./use-projection-date-range.js";
+import { listPager, useScreenListRows } from "./use-screen-list-rows.js";
+import { useScreenListTable } from "./use-screen-list-table.js";
 // ---- projection-list ----
 // Like entityList, but the list query comes DIRECTLY from `screen.query`
 // (instead of being derived from an entity) — cross-feature capable.
@@ -82,12 +86,7 @@ export function ProjectionListBody({ schema, screen, translate, onRowClick, }) {
     const handleProjectionFacetOptions = useCallback((field, options) => setProjectionReferenceFacetOptions((prev) => prev[field] === options ? prev : { ...prev, [field]: options }), []);
     const resolvedFacetSpecs = useMemo(() => mergeReferenceFacetOptions(facetSpecs, projectionReferenceFacetOptions), [facetSpecs, projectionReferenceFacetOptions]);
     const filterPayload = useMemo(() => buildFilterPayload(urlState.filters, (field) => facetSpecs.find((spec) => spec.field === field)?.type), [urlState.filters, facetSpecs]);
-    // dateRange facets bypass `filters` entirely — their two bounds
-    // become the top-level query params the facet declares, resolved from a
-    // calendar date to an instant in the viewer's zone.
-    const timeZone = useOptionalTimeZone();
-    const dateRangeSpecs = useMemo(() => resolveDateRangeFacets(screen.facets, effectiveTranslate), [screen.facets, effectiveTranslate]);
-    const dateRangePayload = useMemo(() => buildDateRangePayload(dateRangeSpecs, urlState.filters, timeZone), [dateRangeSpecs, urlState.filters, timeZone]);
+    const { dateRangePayload, dateRangeFacets, handleDateRangeChange } = useProjectionDateRange(screen.facets, effectiveTranslate, urlState);
     const queryPayload = useMemo(() => {
         const payload = buildListQueryPayload({
             limit,
@@ -121,16 +120,25 @@ export function ProjectionListBody({ schema, screen, translate, onRowClick, }) {
         filterPayload,
         dateRangePayload,
     ]);
-    const rowsQuery = useQuery(screen.query, queryPayload, { live: true });
+    const facetFilterFields = useMemo(() => (screen.facets ?? []).map((facet) => facet.field), [screen.facets]);
+    const listTable = useScreenListTable({
+        screen,
+        featureName: schema.featureName,
+        payload: queryPayload,
+        filterFields: facetFilterFields,
+        queryType: screen.query,
+        pageSize: limit,
+        paging: usePager ? "offset" : "cursor",
+        translate: effectiveTranslate,
+    });
+    const listRows = useScreenListRows({
+        queryType: screen.query,
+        payload: queryPayload,
+        infinite: false,
+        aggregates: listTable.aggregates,
+    });
+    const refreshRows = listRows.refreshAfterWrite;
     const filterFacets = useMemo(() => buildFilterFacets(resolvedFacetSpecs), [resolvedFacetSpecs]);
-    const dateRangeFacets = useMemo(() => dateRangeSpecs.map((spec) => ({
-        field: spec.field,
-        label: spec.label,
-        ...readDateRange(urlState.filters, spec.field),
-    })), [dateRangeSpecs, urlState.filters]);
-    const handleDateRangeChange = useCallback((field, bound, value) => {
-        urlState.setDateRange(field, clampDateRange(readDateRange(urlState.filters, field), bound, value));
-    }, [urlState.setDateRange, urlState.filters]);
     // Entity targets: see EntityListBody.runNavigate for why the resolution happens
     // in the NavApi impl. Unlike there: NO row["id"]
     // fallback — projectionList rows come from an arbitrary query projection
@@ -146,7 +154,7 @@ export function ProjectionListBody({ schema, screen, translate, onRowClick, }) {
         translate: effectiveTranslate,
         dispatcher,
         nav,
-        refetch: rowsQuery.refetch,
+        refetch: refreshRows,
         openDrawer,
         defaultEditRowAction,
         host,
@@ -157,7 +165,7 @@ export function ProjectionListBody({ schema, screen, translate, onRowClick, }) {
         dispatcher,
         clientActions,
         nav,
-        rowsQuery.refetch,
+        refreshRows,
         openDrawer,
         defaultEditRowAction,
         host,
@@ -167,7 +175,7 @@ export function ProjectionListBody({ schema, screen, translate, onRowClick, }) {
         translate: effectiveTranslate,
         dispatcher,
         nav,
-        refetch: rowsQuery.refetch,
+        refetch: refreshRows,
         openDrawer,
         host,
         access: { appFeatures, userRoles },
@@ -177,30 +185,37 @@ export function ProjectionListBody({ schema, screen, translate, onRowClick, }) {
         nav,
         host,
         dispatcher,
-        rowsQuery.refetch,
+        refreshRows,
         openDrawer,
         appFeatures,
         userRoles,
     ]);
+    const bulk = useListBulk({
+        bulkActions: screen.bulkActions,
+        rowActions: screen.rowActions,
+        translate: effectiveTranslate,
+        dispatcher,
+        reload: refreshRows,
+    });
     const emptyContent = useListEmptyContent(screen.emptyState, effectiveTranslate, {
         nav,
         host,
         dispatcher,
         openDrawer,
-        onWriteSuccess: rowsQuery.refetch,
+        onWriteSuccess: refreshRows,
     });
-    if (rowsQuery.loading && rowsQuery.data === null) {
+    if (listRows.firstLoad) {
         return _jsx(QueryLoadingBanner, {});
     }
-    if (rowsQuery.error && rowsQuery.data === null) {
-        return (_jsx(QueryErrorBanner, { error: rowsQuery.error, translate: effectiveTranslate, onRetry: rowsQuery.refetch }));
+    if (listRows.error && !listRows.hasData) {
+        return (_jsx(QueryErrorBanner, { error: listRows.error, translate: effectiveTranslate, onRetry: listRows.retry }));
     }
     // A failed refetch keeps the last good data on screen.
-    const refetchErrorBanner = rowsQuery.error ? (_jsx(QueryErrorBanner, { error: rowsQuery.error, translate: effectiveTranslate, onRetry: rowsQuery.refetch })) : null;
-    // rowsQuery.data is typed as PagedRows but the query handler is free to
+    const refetchErrorBanner = listRows.error ? (_jsx(QueryErrorBanner, { error: listRows.error, translate: effectiveTranslate, onRetry: listRows.retry })) : null;
+    // listRows.page is typed as PagedRows but the query handler is free to
     // return anything at runtime (a bare array silently rendered an empty
     // table instead of surfacing the mismatch), so the shape is checked.
-    if (rowsQuery.data !== null && !Array.isArray(rowsQuery.data.rows)) {
+    if (listRows.page !== null && !Array.isArray(listRows.page.rows)) {
         return (_jsxs(Banner, { padded: true, variant: "error", testId: "kumiko-screen-projection-list-bad-shape", children: ["Screen ", _jsx(Text, { variant: "code", children: screen.id }), " query", " ", _jsx(Text, { variant: "code", children: screen.query }), " did not return a PagedRows envelope; a projectionList query must return ", _jsx(Text, { variant: "code", children: "{ rows, nextCursor }" }), "."] }));
     }
     const rowClickAction = findRowClickAction(screen.rowActions);
@@ -214,32 +229,22 @@ export function ProjectionListBody({ schema, screen, translate, onRowClick, }) {
     // Same pager-construction as EntityListBody: no Pager UI until the
     // server-provided `total` arrives (guards pagination="pages" without
     // totalCount support).
-    const total = rowsQuery.data?.total;
-    const pager = usePager && total !== undefined
-        ? {
-            page: urlState.page,
-            limit,
-            total,
-            onPageChange: urlState.setPage,
-            pageSizeOptions: pageSizeOptionsFor(limit),
-            onPageSizeChange: urlState.setPageSize,
-        }
-        : undefined;
-    return (_jsxs(_Fragment, { children: [refetchErrorBanner, _jsx(ReferenceFacetBridges, { specs: facetSpecs, onOptions: handleProjectionFacetOptions }), _jsx(RenderList, { screen: listScreen, entity: entity, rows: rowsQuery.data?.rows ?? [], featureName: schema.featureName, searchable: searchable, narrowed: isListNarrowed(activeSearch, urlState.filters), ...(screen.description !== undefined && {
+    const pager = listPager({ usePager, page: listRows.page, limit, urlState });
+    return (_jsxs(_Fragment, { children: [refetchErrorBanner, _jsx(ListGroupPageBridges, { ...listTable.aggregates.groupPages }), _jsx(ReferenceFacetBridges, { specs: facetSpecs, onOptions: handleProjectionFacetOptions }), _jsx(RenderList, { screen: listScreen, entity: entity, rows: listRows.rows, featureName: schema.featureName, searchable: searchable, narrowed: isListNarrowed(activeSearch, urlState.filters), ...(screen.description !== undefined && {
                     description: effectiveTranslate(screen.description),
                 }), ...(emptyContent !== undefined && { emptyContent }), searchValue: urlState.q, onSearchChange: urlState.setQ, sort: activeSort, onSortChange: urlState.setSort, ...(isEmbeddedScreen
                     ? { screenPadding: false, chromeless: true }
-                    : { screenPadding: true }), ...(screenFillsHeight(listScreen) && { scrollBody: true }), ...(pager !== undefined && { pager }), ...(rowActions !== undefined && { rowActions }), ...(screen.rowActionMode !== undefined && { rowActionMode: screen.rowActionMode }), ...(toolbarActions !== undefined && { toolbarActions }), ...(translate !== undefined && { translate }), ...(wrappedOnRowClick !== undefined && { onRowClick: wrappedOnRowClick }), ...(filterFacets.length > 0 && {
+                    : { screenPadding: true }), ...(screenFillsHeight(listScreen) && { scrollBody: true }), ...(pager !== undefined && { pager }), ...(rowActions !== undefined && { rowActions }), ...(screen.rowActionMode !== undefined && { rowActionMode: screen.rowActionMode }), ...(bulk !== undefined && { bulk }), ...(toolbarActions !== undefined && { toolbarActions }), ...(translate !== undefined && { translate }), ...(wrappedOnRowClick !== undefined && { onRowClick: wrappedOnRowClick }), ...(filterFacets.length > 0 && {
                     filterFacets,
                     onFilterChange: urlState.setFilter,
                 }), ...(dateRangeFacets.length > 0 && {
                     dateRangeFacets,
                     onDateRangeChange: handleDateRangeChange,
-                }), ...((filterFacets.length > 0 || dateRangeFacets.length > 0) && {
+                }), ...listTable.props, ...((filterFacets.length > 0 || dateRangeFacets.length > 0) && {
                     filterValues: urlState.filters,
                     onFilterReset: urlState.clearFilters,
                 }) }), _jsx(DrawerHost, { schema: schema, drawerAction: drawerAction, drawerScreen: drawerScreen, ...(drawerInitialValues !== undefined && { drawerInitialValues }), userRoles: userRoles, ...(translate !== undefined && { translate }), onClose: closeDrawer, onSuccess: () => {
                     closeDrawer();
-                    void rowsQuery.refetch();
+                    void refreshRows();
                 } })] }));
 }

package/dist/app/row-actions.d.ts

@@ -21,6 +21,9 @@ export declare function runDrawerRowAction(action: RowActionDrawer, openDrawer:
  *  validator allows at most one per list. */
 export declare function findRowClickAction(rowActions: readonly RowAction[] | undefined): RowActionNavigate | RowActionDrawer | undefined;
 export declare function buildDrawerRowAction(action: RowActionDrawer, translate: Translate, openDrawer: OpenDrawer): DataTableRowAction;
+/** The one server write of a writeHandler row action for one row. */
+export declare function writeRowAction(action: RowActionWriteHandler, row: ListRowViewModel, dispatcher: Dispatcher): ReturnType<Dispatcher["write"]>;
+export declare function buildWriteHandlerRowAction(action: RowActionWriteHandler, translate: Translate, refetch: () => Promise<unknown>, dispatcher: Dispatcher): DataTableRowAction;
 export declare function buildClientActionRowAction(action: RowActionClientAction, translate: Translate, runtime: ClientActionRuntime | undefined, refetch: () => Promise<unknown>): DataTableRowAction;
 export declare function buildProjectionRowActions(options: {
     readonly rowActions: readonly RowAction[] | undefined;

package/dist/app/row-actions.js

@@ -153,7 +153,14 @@ function mergeDefaultEditAction(rowActions, defaultEditRowAction) {
         ? [defaultEditRowAction, ...(rowActions ?? [])]
         : (rowActions ?? []);
 }
-function buildWriteHandlerRowAction(action, translate, refetch, dispatcher) {
+/** The one server write of a writeHandler row action for one row. */
+export function writeRowAction(action, row, dispatcher) {
+    const payload = action.payload !== undefined
+        ? evalRowExtractor(action.payload, row.values)
+        : { id: row.values["id"] };
+    return dispatcher.write(action.handler, payload);
+}
+export function buildWriteHandlerRowAction(action, translate, refetch, dispatcher) {
     const writeVisible = action.visible;
     return {
         id: action.id,
@@ -166,10 +173,8 @@ function buildWriteHandlerRowAction(action, translate, refetch, dispatcher) {
             confirmLabel: translate(action.confirmLabel),
         }),
         onTrigger: async (row) => {
-            const payload = action.payload !== undefined
-                ? evalRowExtractor(action.payload, row.values)
-                : { id: row.values["id"] };
-            const result = await dispatcher.write(action.handler, payload);
+            const result = await writeRowAction(action, row, dispatcher);
+            // write() does not throw: an unthrown failure would close the confirm dialog silently.
             if (!result.isSuccess) {
                 throw new WriteFailedError(result.error, dispatcherErrorText(result.error, translate));
             }

package/dist/app/screen-shared.js

@@ -130,7 +130,7 @@ export function formatSummaryParams(prefill, locale) {
 }
 // Placeholders of `successMessage`: formatted submitted values, with a
 // reference field resolved to the chosen record's label. A lookup that fails or
-// misses the row (the lookup list is capped) falls back to the raw id.
+// misses the row falls back to the raw id.
 export async function resolveSuccessMessageParams(screen, featureName, values, dispatcher, locale) {
     const params = formatSummaryParams(values, locale);
     await Promise.all(Object.entries(screen.fields).map(async ([name, def]) => {
@@ -139,7 +139,14 @@ export async function resolveSuccessMessageParams(screen, featureName, values, d
             return;
         const target = parseRefTarget(def.entity, featureName);
         const { queryQn, labelKey } = referenceLookupSource(target.featureName, target.entityName, def.labelField ?? "id");
-        const lookup = await dispatcher.query(queryQn, { limit: REFERENCE_LIST_LOOKUP_LIMIT });
+        // Ask for exactly the chosen record so it cannot fall beyond the lookup cap: `ids` is the
+        // by-id input of directory sources, `filters` that of entity list handlers. A source that
+        // knows neither returns its capped list and the scan below still finds the row if present.
+        const lookup = await dispatcher.query(queryQn, {
+            limit: REFERENCE_LIST_LOOKUP_LIMIT,
+            ids: [raw],
+            filters: [{ field: "id", op: "in", value: [raw] }],
+        });
         if (!lookup.isSuccess)
             return;
         const row = lookup.data.rows.find((candidate) => candidate["id"] === raw);

package/dist/app/use-entity-range-facets.d.ts

@@ -0,0 +1,24 @@
+import type { EntityListScreenDefinition } from "@cosmicdrift/kumiko-types/screen";
+import type { DataTableRangeBound, DataTableRangeFacet } from "../data-table-aggregate-types.ts";
+import { type Translate } from "../headless/index.ts";
+import type { ListUrlStateApi } from "../hooks/use-list-url-state.ts";
+export type RangeFilter = {
+    readonly field: string;
+    readonly op: "gte" | "lte";
+    readonly value: number;
+};
+export type EntityRangeFacets = {
+    readonly rangeFacets: readonly DataTableRangeFacet[];
+    readonly rangeFilters: readonly RangeFilter[];
+    /** Facet keys the remembered list state may keep (`<field>`, bounds hang off it). */
+    readonly rangeFields: readonly string[];
+    readonly onRangeChange: (field: string, bound: DataTableRangeBound, value: string) => void;
+};
+/** `display: "range"` facets of an entityList: from/to inputs sent as `gte`/`lte`. */
+export declare function useEntityRangeFacets({ fields, screen, featureName, translate, urlState, }: {
+    readonly fields: Readonly<Record<string, unknown>>;
+    readonly screen: EntityListScreenDefinition;
+    readonly featureName: string;
+    readonly translate: Translate;
+    readonly urlState: Pick<ListUrlStateApi, "filters" | "setFilter">;
+}): EntityRangeFacets;

package/dist/app/use-entity-range-facets.js

@@ -0,0 +1,64 @@
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { useCallback, useMemo } from "react";
+import { fieldLabelKey } from "../headless/index.js";
+const RANGE_FIELD_TYPES = new Set(["number", "decimal", "money", "bigInt"]);
+// Money is stored and filtered in minor units; the user types the major amount.
+const MONEY_MINOR_UNITS = 100;
+// The bounds live in the facet URL namespace (`<screenId>.f.<field>.min`), so
+// page reset and clearFilters cover them; buildFilterPayload skips the dotted key.
+function rangeUrlField(field, bound) {
+    return `${field}.${bound}`;
+}
+function literalCurrencyOf(def) {
+    const currency = propertyOf(def, "currency");
+    const code = propertyOf(currency, "code");
+    return propertyOf(currency, "kind") === "literal" && typeof code === "string" ? code : undefined;
+}
+function resolveRangeSpecs(fields, facets, featureName, entityName, translate) {
+    return Object.entries(facets ?? {}).flatMap(([field, config]) => {
+        if (config === false || config.display !== "range")
+            return [];
+        const def = fields[field];
+        const type = propertyOf(def, "type");
+        if (typeof type !== "string" || !RANGE_FIELD_TYPES.has(type))
+            return [];
+        const unit = type === "money" ? literalCurrencyOf(def) : undefined;
+        return [
+            {
+                field,
+                label: translate(fieldLabelKey(featureName, entityName, field)),
+                money: type === "money",
+                ...(unit !== undefined && { unit }),
+            },
+        ];
+    });
+}
+function boundOf(urlFilters, field, bound) {
+    return urlFilters[rangeUrlField(field, bound)]?.[0] ?? "";
+}
+function rangeFiltersOf(specs, urlFilters) {
+    return specs.flatMap((spec) => ["min", "max"].flatMap((bound) => {
+        const typed = boundOf(urlFilters, spec.field, bound);
+        const amount = Number(typed);
+        if (typed === "" || !Number.isFinite(amount))
+            return [];
+        const value = spec.money ? Math.round(amount * MONEY_MINOR_UNITS) : amount;
+        return [{ field: spec.field, op: bound === "min" ? "gte" : "lte", value }];
+    }));
+}
+/** `display: "range"` facets of an entityList: from/to inputs sent as `gte`/`lte`. */
+export function useEntityRangeFacets({ fields, screen, featureName, translate, urlState, }) {
+    const { filters: urlFilters, setFilter } = urlState;
+    const specs = useMemo(() => resolveRangeSpecs(fields, screen.facets, featureName, screen.entity, translate), [fields, screen.facets, featureName, screen.entity, translate]);
+    const rangeFacets = useMemo(() => specs.map((spec) => ({
+        field: spec.field,
+        label: spec.label,
+        min: boundOf(urlFilters, spec.field, "min"),
+        max: boundOf(urlFilters, spec.field, "max"),
+        ...(spec.unit !== undefined && { unit: spec.unit }),
+    })), [specs, urlFilters]);
+    const rangeFilters = useMemo(() => rangeFiltersOf(specs, urlFilters), [specs, urlFilters]);
+    const rangeFields = useMemo(() => specs.map((spec) => spec.field), [specs]);
+    const onRangeChange = useCallback((field, bound, value) => setFilter(rangeUrlField(field, bound), value === "" ? [] : [value]), [setFilter]);
+    return { rangeFacets, rangeFilters, rangeFields, onRangeChange };
+}

package/dist/app/use-projection-date-range.d.ts

@@ -0,0 +1,12 @@
+import type { ProjectionListScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Translate } from "../headless/index.ts";
+import type { ListUrlStateApi } from "../hooks/use-list-url-state.ts";
+import type { DataTableDateRangeFacet } from "../primitives.tsx";
+/** dateRange facets bypass `filters` entirely: their two bounds become the
+ *  top-level query params the facet declares, resolved from a calendar date
+ *  to an instant in the viewer's zone. */
+export declare function useProjectionDateRange(facets: ProjectionListScreenDefinition["facets"], translate: Translate, urlState: ListUrlStateApi): {
+    dateRangePayload: Record<string, string>;
+    dateRangeFacets: DataTableDateRangeFacet[];
+    handleDateRangeChange: (field: string, bound: "from" | "to", value: string) => void;
+};

package/dist/app/use-projection-date-range.js

@@ -0,0 +1,21 @@
+import { useCallback, useMemo } from "react";
+import { useOptionalTimeZone } from "../i18n.js";
+import { buildDateRangePayload, clampDateRange, readDateRange, resolveDateRangeFacets, } from "./list-facets.js";
+/** dateRange facets bypass `filters` entirely: their two bounds become the
+ *  top-level query params the facet declares, resolved from a calendar date
+ *  to an instant in the viewer's zone. */
+export function useProjectionDateRange(facets, translate, urlState) {
+    const timeZone = useOptionalTimeZone();
+    const dateRangeSpecs = useMemo(() => resolveDateRangeFacets(facets, translate), [facets, translate]);
+    const dateRangePayload = useMemo(() => buildDateRangePayload(dateRangeSpecs, urlState.filters, timeZone), [dateRangeSpecs, urlState.filters, timeZone]);
+    const dateRangeFacets = useMemo(() => dateRangeSpecs.map((spec) => ({
+        field: spec.field,
+        label: spec.label,
+        ...readDateRange(urlState.filters, spec.field),
+    })), [dateRangeSpecs, urlState.filters]);
+    const { setDateRange, filters } = urlState;
+    const handleDateRangeChange = useCallback((field, bound, value) => {
+        setDateRange(field, clampDateRange(readDateRange(filters, field), bound, value));
+    }, [setDateRange, filters]);
+    return { dateRangePayload, dateRangeFacets, handleDateRangeChange };
+}

package/dist/app/use-screen-list-rows.d.ts

@@ -0,0 +1,37 @@
+import type { DispatcherError } from "../headless/index.ts";
+import type { ListAggregates } from "../hooks/use-list-aggregates.ts";
+import type { ListUrlStateApi } from "../hooks/use-list-url-state.ts";
+import type { DataTableProps } from "../primitives.tsx";
+import { type PagedRows } from "./screen-shared.tsx";
+type Row = Readonly<Record<string, unknown>>;
+export type ScreenListRows = {
+    readonly rows: readonly Row[];
+    /** The ungrouped page answer; null while grouped or before the first answer. */
+    readonly page: PagedRows | null;
+    readonly firstLoad: boolean;
+    readonly error: DispatcherError | null;
+    readonly hasData: boolean;
+    readonly retry: () => Promise<void>;
+    readonly infinite?: {
+        readonly onReachEnd: () => void;
+        readonly loadingMore: boolean;
+        readonly hasMore: boolean;
+    };
+    readonly refreshAfterWrite: () => Promise<void>;
+};
+/** Rows of a URL-backed list screen: one page, accumulated infinite pages, or the
+ *  loaded rows of the open server groups. `payload` carries no cursor. */
+export declare function useScreenListRows({ queryType, payload, infinite, aggregates, }: {
+    readonly queryType: string;
+    readonly payload: Readonly<Record<string, unknown>>;
+    readonly infinite: boolean;
+    readonly aggregates: ListAggregates;
+}): ScreenListRows;
+/** Pager props for `pagination: "pages"`; none until the server total arrives. */
+export declare function listPager(args: {
+    readonly usePager: boolean;
+    readonly page: PagedRows | null;
+    readonly limit: number;
+    readonly urlState: Pick<ListUrlStateApi, "page" | "setPage" | "setPageSize">;
+}): DataTableProps["pager"];
+export {};

package/dist/app/use-screen-list-rows.js

@@ -0,0 +1,104 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useQuery } from "../hooks/use-query.js";
+import { refetchAfterWrite } from "./row-actions.js";
+import { pageSizeOptionsFor } from "./screen-shared.js";
+function freshInfiniteState(resetKey) {
+    return { resetKey, rows: [], cursor: undefined, hasMore: true };
+}
+// Live updates can bring an entry onto the next page that was already appended.
+function appendUnseen(previous, next) {
+    const seen = new Set(previous.map((row) => row["id"]));
+    return [...previous, ...next.filter((row) => !seen.has(row["id"]))];
+}
+/** Rows of a URL-backed list screen: one page, accumulated infinite pages, or the
+ *  loaded rows of the open server groups. `payload` carries no cursor. */
+export function useScreenListRows({ queryType, payload, infinite, aggregates, }) {
+    const { grouped, refresh: refreshAggregates } = aggregates;
+    const resetKey = JSON.stringify(payload);
+    const [infiniteState, setInfiniteState] = useState(() => freshInfiniteState(resetKey));
+    const state = infiniteState.resetKey === resetKey ? infiniteState : freshInfiniteState(resetKey);
+    if (infiniteState.resetKey !== resetKey)
+        setInfiniteState(state);
+    const cursor = infinite ? state.cursor : undefined;
+    const rowsPayload = useMemo(() => (cursor === undefined ? payload : { ...payload, cursor }), [payload, cursor]);
+    const rowsQuery = useQuery(queryType, rowsPayload, { live: true, enabled: !grouped });
+    const { data, loading, refetch } = rowsQuery;
+    const lastDataRef = useRef(null);
+    useEffect(() => {
+        // skip: only a new answer of an infinite list is appended
+        if (!infinite || data === null || data === lastDataRef.current)
+            return;
+        lastDataRef.current = data;
+        setInfiniteState((current) => current.resetKey !== resetKey
+            ? current
+            : {
+                ...current,
+                rows: current.cursor === undefined ? data.rows : appendUnseen(current.rows, data.rows),
+                hasMore: data.nextCursor !== null,
+            });
+    }, [data, infinite, resetKey]);
+    const onReachEnd = useCallback(() => {
+        // skip: the next page waits for the current answer
+        if (loading)
+            return;
+        const nextCursor = data?.nextCursor;
+        // skip: no cursor means the last page is loaded
+        if (nextCursor === undefined || nextCursor === null)
+            return;
+        setInfiniteState((current) => current.resetKey === resetKey ? { ...current, cursor: nextCursor } : current);
+    }, [loading, data, resetKey]);
+    const refreshAfterWrite = useCallback(async () => {
+        refreshAggregates();
+        // skip: grouped rows reload through the aggregates refresh
+        if (grouped)
+            return;
+        if (infinite && cursor !== undefined) {
+            setInfiniteState(freshInfiniteState(resetKey));
+            // skip: starting over refetches the first page
+            return;
+        }
+        await refetchAfterWrite(refetch);
+    }, [refreshAggregates, grouped, infinite, cursor, resetKey, refetch]);
+    const retry = useCallback(async () => {
+        if (grouped)
+            refreshAggregates();
+        else
+            await refetch();
+    }, [grouped, refreshAggregates, refetch]);
+    if (grouped) {
+        return {
+            rows: aggregates.rows,
+            page: null,
+            firstLoad: aggregates.loading,
+            error: aggregates.error,
+            hasData: aggregates.serverGroups !== undefined,
+            retry,
+            refreshAfterWrite,
+        };
+    }
+    return {
+        rows: infinite ? state.rows : (data?.rows ?? []),
+        page: data,
+        firstLoad: loading && data === null,
+        error: rowsQuery.error,
+        hasData: data !== null,
+        retry,
+        ...(infinite && { infinite: { onReachEnd, loadingMore: loading, hasMore: state.hasMore } }),
+        refreshAfterWrite,
+    };
+}
+/** Pager props for `pagination: "pages"`; none until the server total arrives. */
+export function listPager(args) {
+    const { usePager, page, limit, urlState } = args;
+    const total = page?.total;
+    if (!usePager || total === undefined)
+        return undefined;
+    return {
+        page: urlState.page,
+        limit,
+        total,
+        onPageChange: urlState.setPage,
+        pageSizeOptions: pageSizeOptionsFor(limit),
+        onPageSizeChange: urlState.setPageSize,
+    };
+}

package/dist/app/use-screen-list-table.d.ts

@@ -0,0 +1,24 @@
+import type { EntityListScreenDefinition, ProjectionListScreenDefinition } from "@cosmicdrift/kumiko-types/screen";
+import type { Translate } from "../headless/index.ts";
+import type { ListGroupPaging } from "../hooks/list-group-pages.ts";
+import { type ListAggregates } from "../hooks/use-list-aggregates.ts";
+import { type ListTableProps } from "../hooks/use-list-table.ts";
+import type { DataTableTableBlockProps } from "../primitives.tsx";
+type ScreenListTableArgs = {
+    readonly screen: EntityListScreenDefinition | ProjectionListScreenDefinition;
+    readonly featureName: string;
+    /** The list query payload as sent; paging keys are stripped for the export. */
+    readonly payload: Readonly<Record<string, unknown>>;
+    readonly filterFields: readonly string[];
+    readonly queryType: string;
+    readonly pageSize: number;
+    readonly paging: ListGroupPaging;
+    readonly translate: Translate;
+};
+export type ScreenListTable = {
+    readonly props: ListTableProps & Pick<DataTableTableBlockProps, "serverGroups" | "totals" | "notice">;
+    readonly aggregates: ListAggregates;
+};
+/** Table-block wiring of a URL-backed list screen (entityList, projectionList). */
+export declare function useScreenListTable({ screen, featureName, payload, filterFields, queryType, pageSize, paging, translate, }: ScreenListTableArgs): ScreenListTable;
+export {};

package/dist/app/use-screen-list-table.js

@@ -0,0 +1,46 @@
+import { useMemo } from "react";
+import { useListStateStore } from "../components/list-state-store.js";
+import { useListAggregates } from "../hooks/use-list-aggregates.js";
+import { useListTable } from "../hooks/use-list-table.js";
+import { listViewSchemaColumns } from "../hooks/use-list-view-state.js";
+import { useRememberedListParams } from "../hooks/use-remembered-list-params.js";
+/** Table-block wiring of a URL-backed list screen (entityList, projectionList). */
+export function useScreenListTable({ screen, featureName, payload, filterFields, queryType, pageSize, paging, translate, }) {
+    const { id: screenId, table, columns } = screen;
+    const store = useListStateStore();
+    const schemaColumns = useMemo(() => listViewSchemaColumns(columns), [columns]);
+    const known = useMemo(() => ({ columnFields: schemaColumns.map((column) => column.field), filterFields }), [schemaColumns, filterFields]);
+    useRememberedListParams({
+        screenId,
+        enabled: table?.rememberState === true,
+        store,
+        known,
+    });
+    const exportSource = useMemo(() => ({ screen: `${featureName}:screen:${screenId}`, screenShortId: screenId, payload }), [featureName, screenId, payload]);
+    const { props, groupField } = useListTable({
+        storeKey: screenId,
+        table,
+        schemaColumns,
+        url: { screenId },
+        exportSource,
+    });
+    const aggregates = useListAggregates({
+        queryType,
+        payload,
+        table,
+        groupField,
+        pageSize,
+        paging,
+        translate,
+    });
+    const { serverGroups, totals, notice } = aggregates;
+    return {
+        props: {
+            ...props,
+            ...(serverGroups !== undefined && { serverGroups }),
+            ...(totals !== undefined && { totals }),
+            ...(notice !== undefined && { notice }),
+        },
+        aggregates,
+    };
+}

package/dist/components/edit-mounts.d.ts

@@ -10,7 +10,7 @@ export declare function ExtensionSectionMount({ section, entityName: hostEntityN
     readonly values?: Readonly<Record<string, unknown>>;
     readonly patch?: (partial: Readonly<Record<string, unknown>>) => void;
     readonly validate?: () => boolean;
-    readonly markSaved?: () => void;
+    readonly markSaved?: (fields?: readonly string[]) => void;
     readonly hideTitle?: boolean;
     /** section.actions, already resolved into buttons by the caller. */
     readonly actions?: ReactNode;
@@ -24,7 +24,7 @@ export declare function EditSlotMount({ slot, slotName, screenId, entityName, en
     readonly entityName: string;
     readonly entityId: string | null;
     readonly values: Readonly<Record<string, unknown>>;
-    readonly markSaved?: () => void;
+    readonly markSaved?: (fields?: readonly string[]) => void;
     readonly hasUnsavedChanges?: boolean;
     readonly wizardStep?: {
         readonly index: number;

package/dist/components/embedded-list-field.js

@@ -169,7 +169,7 @@ function EmbeddedListFieldInner({ field, id, onChange, allIssues, featureName, }
             };
         }
         return {
-            field: entry.from.join("+"),
+            field: `${entry.from.join("+")}:${entry.label}`,
             label: t(entry.label),
             value: entry.from.reduce((sum, name) => sum + sumEmbeddedListColumn(rows, name), 0),
             money: entry.from.every((name) => cells.find((c) => c.field === name)?.type === "money"),

package/dist/components/list-group-page-bridges.d.ts

@@ -0,0 +1,3 @@
+import { type ReactNode } from "react";
+import type { ListGroupPagesProps } from "../hooks/use-list-aggregates.ts";
+export declare function ListGroupPageBridges({ queryType, requests, onResult, refreshNonce, }: ListGroupPagesProps): ReactNode;