@cosmicdrift/kumiko-renderer 0.388.0 → 0.389.0

package/dist/app/kumiko-screen.js

@@ -3,7 +3,7 @@ import { useEffect, useMemo, useRef } from "react";
 import { useUserRoles } from "../context/user-roles-context.js";
 import { useQuery } from "../hooks/use-query.js";
 import { useTranslation } from "../i18n.js";
-import { PageHeaderSlotAvailableProvider, usePageHeaderSlotAvailable, } from "../page-header-slot.js";
+import { PageHeaderSlotAvailableProvider } from "../page-header-slot.js";
 import { usePrimitives } from "../primitives.js";
 import { ActionFormBody } from "./action-form-body.js";
 import { ConfigEditBody } from "./config-edit-body.js";
@@ -11,6 +11,7 @@ import { useCustomScreenComponent } from "./custom-screens.js";
 import { useDashboardBody } from "./dashboard-body.js";
 import { EntityEditScreen } from "./entity-edit-screen.js";
 import { EntityListScreen } from "./entity-list-screen.js";
+import { LockedHeaderScope, StandInChainBoundary } from "./locked-screen-header.js";
 import { ProjectionDetailBody } from "./projection-detail-body.js";
 import { ProjectionListBody } from "./projection-list-body.js";
 import { lastSegment } from "./qn.js";
@@ -54,7 +55,7 @@ export function KumikoScreen({ schema, qn, translate, entityId, onRowClick, onCo
         onCopyLink,
     });
     // Gate every entry (incl. direct URL): the body element is only mounted once the condition holds.
-    const body = screen.visibleWhen !== undefined ? (_jsx(ScreenVisibilityGate, { featureName: schema.featureName, visibleWhen: screen.visibleWhen, fallback: screen.fallback, translate: translate, children: screenBody })) : (screenBody);
+    const body = screen.visibleWhen !== undefined ? (_jsx(ScreenVisibilityGate, { featureName: schema.featureName, visibleWhen: screen.visibleWhen, fallback: screen.fallback, translate: translate, children: _jsx(StandInChainBoundary, { children: screenBody }) })) : (_jsx(StandInChainBoundary, { children: screenBody }));
     // An embedded screen (e.g. a dashboard panel) keeps its parent's host and
     // must not portal its page header into the shell that hosts the outer screen.
     if (outerHost !== undefined) {
@@ -78,16 +79,7 @@ function ScreenVisibilityGate({ featureName, visibleWhen, fallback, translate, c
     if (fallback !== undefined) {
         return _jsx(FallbackScreen, { featureName: featureName, fallback: fallback, translate: translate });
     }
-    return (_jsxs(_Fragment, { children: [_jsx(LockedScreenHeader, {}), _jsx(ScreenUnavailableBanner, {})] }));
-}
-// The route still names the locked screen; its breadcrumb must not label what stands in for it.
-// With a stand-in the header is labelled with that screen instead, none if it has no title.
-function LockedScreenHeader({ standInScreenId }) {
-    const { PageHeader } = usePrimitives();
-    const pageHeaderSlotAvailable = usePageHeaderSlotAvailable();
-    if (PageHeader === undefined || !pageHeaderSlotAvailable)
-        return null;
-    return standInScreenId !== undefined ? (_jsx(PageHeader, { hideBreadcrumb: true, breadcrumbScreenId: standInScreenId })) : (_jsx(PageHeader, { hideBreadcrumb: true }));
+    return (_jsxs(_Fragment, { children: [_jsx(LockedHeaderScope, {}), _jsx(ScreenUnavailableBanner, {})] }));
 }
 function ScreenUnavailableBanner() {
     const { Banner } = usePrimitives();
@@ -99,9 +91,9 @@ function FallbackScreen({ featureName, fallback, translate, }) {
     // Also undefined when the user lacks access to the fallback screen, which is
     // not a framework error.
     if (target === undefined) {
-        return (_jsxs(_Fragment, { children: [_jsx(LockedScreenHeader, {}), _jsx(ScreenUnavailableBanner, {})] }));
+        return (_jsxs(_Fragment, { children: [_jsx(LockedHeaderScope, {}), _jsx(ScreenUnavailableBanner, {})] }));
     }
-    return (_jsxs(_Fragment, { children: [_jsx(LockedScreenHeader, { standInScreenId: lastSegment(target.qn) }), _jsx(KumikoScreen, { schema: target.schema, qn: target.qn, translate: translate })] }));
+    return (_jsx(LockedHeaderScope, { standInScreenId: lastSegment(target.qn), children: _jsx(KumikoScreen, { schema: target.schema, qn: target.qn, translate: translate }) }));
 }
 function renderScreenBody({ schema, screen, translate, entityId, onRowClick, onCopyLink, }) {
     switch (screen.type) {

package/dist/app/list-bulk-actions.d.ts

@@ -0,0 +1,18 @@
+import type { ListBulkAction, RowAction } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { DataTableBulk, DataTableBulkAction } from "../data-table-bulk-types.ts";
+import type { Dispatcher, Translate } from "../headless/index.ts";
+/** Resolves each bulk action against its writeHandler row action; one that resolves to nothing is dropped. */
+export declare function buildListBulkActions(options: {
+    readonly bulkActions: readonly ListBulkAction[];
+    readonly rowActions: readonly RowAction[] | undefined;
+    readonly translate: Translate;
+    readonly dispatcher: Dispatcher;
+}): readonly DataTableBulkAction[];
+/** DataTable `bulk` prop of a list screen; undefined without bulk actions or dispatcher. */
+export declare function useListBulk(options: {
+    readonly bulkActions: readonly ListBulkAction[] | undefined;
+    readonly rowActions: readonly RowAction[] | undefined;
+    readonly translate: Translate;
+    readonly dispatcher: Dispatcher | undefined;
+    readonly reload: () => Promise<unknown>;
+}): DataTableBulk | undefined;

package/dist/app/list-bulk-actions.js

@@ -0,0 +1,54 @@
+import { evalFieldCondition } from "@cosmicdrift/kumiko-framework/ui-types";
+import { resolveActionIcon } from "@cosmicdrift/kumiko-types/action-icon";
+import { useMemo } from "react";
+import { isWriteHandlerRowAction, refetchAfterWrite, writeRowAction } from "./row-actions.js";
+import { dispatcherErrorText } from "./write-failed-error.js";
+function asksForConfirm(bulk, rowAction) {
+    return (bulk.confirm !== undefined || rowAction.confirm !== undefined || rowAction.style === "danger");
+}
+function buildBulkAction(bulk, rowAction, translate, dispatcher) {
+    const label = translate(rowAction.label);
+    const visible = rowAction.visible;
+    const confirmKey = bulk.confirm ?? "kumiko.list.bulk.confirm";
+    return {
+        id: bulk.id,
+        label,
+        ...(rowAction.style !== undefined && { style: rowAction.style }),
+        icon: resolveActionIcon(rowAction.id, rowAction.icon),
+        ...(asksForConfirm(bulk, rowAction) && {
+            confirmText: (count) => translate(confirmKey, { count, action: label }),
+        }),
+        ...(rowAction.confirmLabel !== undefined && {
+            confirmLabel: translate(rowAction.confirmLabel),
+        }),
+        appliesTo: (row) => visible === undefined || evalFieldCondition(visible, row.values),
+        writeRow: async (row) => {
+            const result = await writeRowAction(rowAction, row, dispatcher);
+            return result.isSuccess
+                ? { kind: "succeeded" }
+                : { kind: "failed", message: dispatcherErrorText(result.error, translate) };
+        },
+    };
+}
+/** Resolves each bulk action against its writeHandler row action; one that resolves to nothing is dropped. */
+export function buildListBulkActions(options) {
+    const { bulkActions, rowActions, translate, dispatcher } = options;
+    return bulkActions.flatMap((bulk) => {
+        const rowAction = rowActions?.find((action) => action.id === bulk.rowAction);
+        if (rowAction === undefined || !isWriteHandlerRowAction(rowAction))
+            return [];
+        return [buildBulkAction(bulk, rowAction, translate, dispatcher)];
+    });
+}
+/** DataTable `bulk` prop of a list screen; undefined without bulk actions or dispatcher. */
+export function useListBulk(options) {
+    const { bulkActions, rowActions, translate, dispatcher, reload } = options;
+    return useMemo(() => {
+        if (bulkActions === undefined || dispatcher === undefined)
+            return undefined;
+        const actions = buildListBulkActions({ bulkActions, rowActions, translate, dispatcher });
+        if (actions.length === 0)
+            return undefined;
+        return { actions, reload: () => refetchAfterWrite(reload) };
+    }, [bulkActions, rowActions, translate, dispatcher, reload]);
+}

package/dist/app/locked-screen-header.d.ts

@@ -0,0 +1,9 @@
+import { type ReactNode } from "react";
+/** Screen bodies (and anything embedded in them) are not part of a fallback chain. */
+export declare function StandInChainBoundary({ children }: {
+    readonly children: ReactNode;
+}): ReactNode;
+export declare function LockedHeaderScope({ standInScreenId, children, }: {
+    readonly standInScreenId?: string;
+    readonly children?: ReactNode;
+}): ReactNode;

package/dist/app/locked-screen-header.js

@@ -0,0 +1,33 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useState } from "react";
+import { usePageHeaderSlotAvailable } from "../page-header-slot.js";
+import { usePrimitives } from "../primitives.js";
+// The route still names the locked screen; its breadcrumb must not label what stands in for it.
+// With a stand-in the header is labelled with that screen instead, none if it has no title.
+function LockedScreenHeader({ standInScreenId }) {
+    const { PageHeader } = usePrimitives();
+    const pageHeaderSlotAvailable = usePageHeaderSlotAvailable();
+    if (PageHeader === undefined || !pageHeaderSlotAvailable)
+        return null;
+    return standInScreenId !== undefined ? (_jsx(PageHeader, { hideBreadcrumb: true, breadcrumbScreenId: standInScreenId })) : (_jsx(PageHeader, { hideBreadcrumb: true }));
+}
+// A stand-in can itself be locked and fall back again. The header slot is a single value that
+// every mounted PageHeader overwrites and clears on unmount, so only the outermost scope mounts
+// a header; nested scopes report the screen that finally renders up to it.
+const ReportStandInContext = createContext(undefined);
+/** Screen bodies (and anything embedded in them) are not part of a fallback chain. */
+export function StandInChainBoundary({ children }) {
+    return (_jsx(ReportStandInContext.Provider, { value: undefined, children: children }));
+}
+export function LockedHeaderScope({ standInScreenId, children, }) {
+    const reportToOuter = useContext(ReportStandInContext);
+    const [inner, setInner] = useState(undefined);
+    const effectiveScreenId = inner !== undefined ? inner.screenId : standInScreenId;
+    useEffect(() => {
+        if (reportToOuter === undefined)
+            return;
+        reportToOuter({ screenId: effectiveScreenId });
+        return () => reportToOuter(undefined);
+    }, [reportToOuter, effectiveScreenId]);
+    return (_jsxs(_Fragment, { children: [reportToOuter === undefined && (_jsx(LockedScreenHeader, { ...(effectiveScreenId !== undefined && { standInScreenId: effectiveScreenId }) })), _jsx(ReportStandInContext.Provider, { value: setInner, children: children })] }));
+}

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