@cosmicdrift/kumiko-renderer 0.388.0 → 0.390.0

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

@@ -1,27 +1,25 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useMemo, useState } from "react";
-import { RenderList } from "../components/render-list.js";
+import { ListGroupPageBridges } from "../components/list-group-page-bridges.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 { screenFillsHeight } from "../screen-fills-height.js";
-import { DrawerHost, useDrawerAction } from "./action-form-body.js";
+import { useTranslation } from "../i18n.js";
+import { usePrimitives } from "../primitives.js";
+import { useDrawerAction } from "./action-form-body.js";
 import { useAppFeatures } from "./app-features-context.js";
 import { useClientActionRuntime } from "./client-actions.js";
-import { isListNarrowed, useListEmptyContent } from "./list-empty-content.js";
-import { buildDateRangePayload, buildFilterFacets, buildFilterPayload, clampDateRange, mergeReferenceFacetOptions, readDateRange, resolveDateRangeFacets, 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";
+import { renderProjectionDrawerHost } from "./projection-drawer-host.js";
+import { renderBadShapeBanner, renderProjectionList, renderQueryRetryBanner, } from "./projection-list-render.js";
+import { resolveWrappedRowClick } from "./projection-list-row-click.js";
+import { QueryLoadingBanner } from "./query-state-banners.js";
 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 { useProjectionListActions } from "./use-projection-list-actions.js";
+import { useProjectionListData } from "./use-projection-list-data.js";
+import { useProjectionListDefinitions } from "./use-projection-list-definitions.js";
+import { useProjectionListQuery } from "./use-projection-list-query.js";
+import { listPager } from "./use-screen-list-rows.js";
 // ---- projection-list ----
 // Like entityList, but the list query comes DIRECTLY from `screen.query`
 // (instead of being derived from an entity) — cross-feature capable.
@@ -41,205 +39,92 @@ export function ProjectionListBody({ schema, screen, translate, onRowClick, }) {
     const effectiveTranslate = translate ?? t;
     const userRoles = useUserRoles();
     const appFeatures = useAppFeatures();
-    const { drawerAction, drawerScreen, drawerInitialValues, openDrawer, closeDrawer } = useDrawerAction(schema);
-    const defaultEditScreen = useMemo(() => {
-        const detailFor = screen.detailFor;
-        if (detailFor === undefined)
-            return undefined;
-        return findEditScreenFor(detailFor, appFeatures, userRoles);
-    }, [appFeatures, screen.detailFor, userRoles]);
-    // searchable/sortable/paginated are derived at buildAppSchema time from the
-    // query handler's Zod schema — not authored on the screen.
-    const searchable = screen.searchable ?? false;
-    const sortable = screen.sortable ?? false;
-    const paginated = screen.paginated ?? false;
-    const entity = useMemo(() => synthesizeProjectionEntity(screen.columns, sortable), [screen.columns, sortable]);
-    const listScreen = useMemo(() => synthesizeProjectionScreen(screen), [screen]);
-    const urlState = useListUrlState(screen.id);
-    // Gated on the derived capability, not just on whether URL-state happens to
-    // carry a value — a stale/hand-crafted URL (?…q=x on a non-searchable
-    // screen) must not smuggle a param the query's Zod schema doesn't accept.
-    const activeSearch = searchable ? urlState.q : "";
-    // Same predicate that makes a header clickable: a stale link onto a
-    // sortable:false/unknown column must not reach the server (it answers 400).
-    const urlSort = urlState.sort;
-    const urlSortField = urlSort === null ? undefined : entity.fields[urlSort.field];
-    const urlSortAllowed = urlSortField !== undefined && "sortable" in urlSortField && urlSortField.sortable === true;
-    const activeSort = sortable
-        ? ((urlSortAllowed ? urlSort : null) ?? screen.defaultSort ?? null)
-        : null;
-    const limit = urlState.pageSize ?? screen.pageSize ?? 50;
-    // Pages-mode only (see header comment) — an author-set pagination:
-    // "infinite" on a paginated projectionList is silently a no-op today.
-    const usePager = paginated && (screen.pagination ?? "pages") === "pages";
-    // Facets — a projectionList has no entity, so screen.facets is
-    // the only field inventory; resolveProjectionFacetSpecs reshapes +
-    // translates its explicit labels into the same ResolvedFacetSpec the
-    // entityList adapter produces, so both feed the same
-    // buildFilterFacets/buildFilterPayload.
-    const facetSpecs = useMemo(() => resolveProjectionFacetSpecs(screen.facets, effectiveTranslate, schema.featureName), [screen.facets, effectiveTranslate, schema.featureName]);
-    const [projectionReferenceFacetOptions, setProjectionReferenceFacetOptions] = useState({});
-    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 queryPayload = useMemo(() => {
-        const payload = buildListQueryPayload({
-            limit,
-            search: activeSearch,
-            sort: activeSort,
-            usePager,
-            page: urlState.page,
-            useInfinite: false,
-            cursor: undefined,
-        });
-        // Gated on screen.filter/screen.facets being declared (not just on
-        // urlState/filterPayload happening to carry a value) — same rule as
-        // activeSearch/activeSort above: a stale URL must not smuggle a param
-        // the bound query's Zod schema doesn't accept.
-        if (screen.filter !== undefined) {
-            payload["filter"] = screen.filter;
-        }
-        if (screen.facets !== undefined && filterPayload.length > 0) {
-            payload["filters"] = filterPayload;
-        }
-        Object.assign(payload, dateRangePayload);
-        return payload;
-    }, [
-        limit,
-        activeSearch,
-        activeSort,
-        usePager,
-        urlState.page,
-        screen.filter,
-        screen.facets,
-        filterPayload,
-        dateRangePayload,
-    ]);
-    const rowsQuery = useQuery(screen.query, queryPayload, { live: true });
-    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
-    // with no guaranteed "id" field. The boot validator therefore enforces an
-    // explicit entityId for projectionList entity targets. Same helper
-    // relatedList's rowActions reuse (related-list-section.tsx) — a
-    // projectionDetail relatedList row has the identical "no guaranteed id"
-    // shape.
-    const runNavigate = useCallback((action, row) => runProjectionRowNavigate(nav, action, row, host), [nav, host]);
-    const defaultEditRowAction = useMemo(() => buildDefaultEditRowAction(defaultEditScreen), [defaultEditScreen]);
-    const rowActions = useMemo(() => buildProjectionRowActions({
-        rowActions: screen.rowActions,
-        translate: effectiveTranslate,
-        dispatcher,
-        nav,
-        refetch: rowsQuery.refetch,
-        openDrawer,
-        defaultEditRowAction,
-        host,
-        clientActions,
-    }), [
-        screen.rowActions,
+    const drawer = useDrawerAction(schema);
+    const { openDrawer } = drawer;
+    const definitions = useProjectionListDefinitions(screen, appFeatures, userRoles);
+    const { defaultEditScreen, searchable, sortable, paginated, entity } = definitions;
+    const query = useProjectionListQuery({
+        screen,
+        featureName: schema.featureName,
+        effectiveTranslate,
+        entity,
+        searchable,
+        sortable,
+        paginated,
+    });
+    const data = useProjectionListData({
+        screen,
+        featureName: schema.featureName,
+        queryPayload: query.queryPayload,
+        limit: query.limit,
+        usePager: query.usePager,
+        effectiveTranslate,
+        resolvedFacetSpecs: query.resolvedFacetSpecs,
+    });
+    const { listRows } = data;
+    const refreshRows = listRows.refreshAfterWrite;
+    const actions = useProjectionListActions({
+        screen,
         effectiveTranslate,
         dispatcher,
         clientActions,
         nav,
-        rowsQuery.refetch,
-        openDrawer,
-        defaultEditRowAction,
         host,
-    ]);
-    const toolbarActions = useMemo(() => buildProjectionToolbarActions({
-        toolbarActions: screen.toolbarActions,
-        translate: effectiveTranslate,
-        dispatcher,
-        nav,
-        refetch: rowsQuery.refetch,
-        openDrawer,
-        host,
-        access: { appFeatures, userRoles },
-    }), [
-        screen.toolbarActions,
-        effectiveTranslate,
-        nav,
-        host,
-        dispatcher,
-        rowsQuery.refetch,
+        refreshRows,
         openDrawer,
         appFeatures,
         userRoles,
-    ]);
-    const emptyContent = useListEmptyContent(screen.emptyState, effectiveTranslate, {
-        nav,
-        host,
-        dispatcher,
-        openDrawer,
-        onWriteSuccess: rowsQuery.refetch,
+        defaultEditScreen,
     });
-    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 renderQueryRetryBanner(listRows, listRows.error, effectiveTranslate);
     }
     // 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
+        ? renderQueryRetryBanner(listRows, listRows.error, effectiveTranslate)
+        : 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)) {
-        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 }" }), "."] }));
+    if (listRows.page !== null && !Array.isArray(listRows.page.rows)) {
+        return renderBadShapeBanner(screen, { Banner, Text });
     }
-    const rowClickAction = findRowClickAction(screen.rowActions);
-    const wrappedOnRowClick = rowClickAction
-        ? (row) => rowClickAction.kind === "drawer"
-            ? runDrawerRowAction(rowClickAction, openDrawer, row)
-            : runNavigate(rowClickAction, row)
-        : onRowClick !== undefined
-            ? (row) => onRowClick(row, listScreen.entity)
-            : undefined;
+    const wrappedOnRowClick = resolveWrappedRowClick({
+        screen,
+        onRowClick,
+        entityName: definitions.listScreen.entity,
+        openDrawer,
+        runNavigate: actions.runNavigate,
+    });
     // 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 && {
-                    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 && {
-                    filterFacets,
-                    onFilterChange: urlState.setFilter,
-                }), ...(dateRangeFacets.length > 0 && {
-                    dateRangeFacets,
-                    onDateRangeChange: handleDateRangeChange,
-                }), ...((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();
-                } })] }));
+    const pager = listPager({
+        usePager: query.usePager,
+        page: listRows.page,
+        limit: query.limit,
+        urlState: query.urlState,
+    });
+    return (_jsxs(_Fragment, { children: [refetchErrorBanner, _jsx(ListGroupPageBridges, { ...data.listTable.aggregates.groupPages }), _jsx(ReferenceFacetBridges, { specs: query.facetSpecs, onOptions: query.handleProjectionFacetOptions }), renderProjectionList({
+                schema,
+                screen,
+                translate,
+                effectiveTranslate,
+                isEmbeddedScreen,
+                definitions,
+                query,
+                data,
+                actions,
+                pager,
+                wrappedOnRowClick,
+            }), renderProjectionDrawerHost({
+                schema,
+                translate,
+                userRoles,
+                drawer,
+                refreshRows,
+            })] }));
 }

package/dist/app/projection-list-render-props.d.ts

@@ -0,0 +1,56 @@
+import type { ProjectionListScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { ListRowViewModel, Translate } from "../headless/index.ts";
+import type { ListUrlStateApi } from "../hooks/use-list-url-state.ts";
+import type { useProjectionListActions } from "./use-projection-list-actions.ts";
+import type { useProjectionListData } from "./use-projection-list-data.ts";
+import type { useProjectionListDefinitions } from "./use-projection-list-definitions.ts";
+import type { useProjectionListQuery } from "./use-projection-list-query.ts";
+import type { listPager } from "./use-screen-list-rows.ts";
+export declare function projectionLeadProps(screen: ProjectionListScreenDefinition, effectiveTranslate: Translate, emptyContent: ReturnType<typeof useProjectionListActions>["emptyContent"]): {
+    description?: string | undefined;
+    emptyContent?: import("../components/list-empty-state.tsx").ListEmptyStateContent | undefined;
+};
+export declare function projectionLayoutProps(isEmbeddedScreen: boolean, screen: ProjectionListScreenDefinition, listScreen: ReturnType<typeof useProjectionListDefinitions>["listScreen"], pager: ReturnType<typeof listPager>, rowActions: ReturnType<typeof useProjectionListActions>["rowActions"]): {
+    screenPadding: boolean;
+    chromeless: boolean;
+    scrollBody?: boolean | undefined;
+    pager?: {
+        readonly page: number;
+        readonly limit: number;
+        readonly total: number;
+        readonly onPageChange: (next: number) => void;
+        readonly pageSizeOptions?: readonly number[];
+        readonly onPageSizeChange?: (next: number) => void;
+    } | undefined;
+    rowActions?: readonly import("../primitives.tsx").DataTableRowAction[] | undefined;
+    rowActionMode?: import("@cosmicdrift/kumiko-framework/ui-types").RowActionMode | undefined;
+} | {
+    screenPadding: boolean;
+    scrollBody?: boolean | undefined;
+    pager?: {
+        readonly page: number;
+        readonly limit: number;
+        readonly total: number;
+        readonly onPageChange: (next: number) => void;
+        readonly pageSizeOptions?: readonly number[];
+        readonly onPageSizeChange?: (next: number) => void;
+    } | undefined;
+    rowActions?: readonly import("../primitives.tsx").DataTableRowAction[] | undefined;
+    rowActionMode?: import("@cosmicdrift/kumiko-framework/ui-types").RowActionMode | undefined;
+};
+export declare function projectionActionProps(actions: ReturnType<typeof useProjectionListActions>, translate: Translate | undefined, wrappedOnRowClick: ((row: ListRowViewModel) => void) | undefined): {
+    bulk?: import("../data-table-bulk-types.ts").DataTableBulk | undefined;
+    toolbarActions?: readonly import("../components/render-list-toolbar-action.tsx").ToolbarActionButton[] | undefined;
+    translate?: Translate | undefined;
+    onRowClick?: ((row: ListRowViewModel) => void) | undefined;
+};
+export declare function projectionFacetProps(filterFacets: ReturnType<typeof useProjectionListData>["filterFacets"], dateRangeFacets: ReturnType<typeof useProjectionListQuery>["dateRangeFacets"], onDateRangeChange: ReturnType<typeof useProjectionListQuery>["handleDateRangeChange"], urlState: ListUrlStateApi): {
+    filterFacets?: import("../data-table-facet-types.ts").DataTableFacet[] | undefined;
+    onFilterChange?: ((field: string, values: readonly string[]) => void) | undefined;
+    dateRangeFacets?: import("../data-table-facet-types.ts").DataTableDateRangeFacet[] | undefined;
+    onDateRangeChange?: ((field: string, bound: "from" | "to", value: string) => void) | undefined;
+};
+export declare function projectionFilterStateProps(filterFacets: ReturnType<typeof useProjectionListData>["filterFacets"], dateRangeFacets: ReturnType<typeof useProjectionListQuery>["dateRangeFacets"], urlState: ListUrlStateApi): {
+    filterValues?: Readonly<Record<string, readonly string[]>> | undefined;
+    onFilterReset?: (() => void) | undefined;
+};

package/dist/app/projection-list-render-props.js

@@ -0,0 +1,47 @@
+import { screenFillsHeight } from "../screen-fills-height.js";
+export function projectionLeadProps(screen, effectiveTranslate, emptyContent) {
+    return {
+        ...(screen.description !== undefined && {
+            description: effectiveTranslate(screen.description),
+        }),
+        ...(emptyContent !== undefined && { emptyContent }),
+    };
+}
+export function projectionLayoutProps(isEmbeddedScreen, screen, listScreen, pager, rowActions) {
+    return {
+        ...(isEmbeddedScreen ? { screenPadding: false, chromeless: true } : { screenPadding: true }),
+        ...(screenFillsHeight(listScreen) && { scrollBody: true }),
+        ...(pager !== undefined && { pager }),
+        ...(rowActions !== undefined && { rowActions }),
+        ...(screen.rowActionMode !== undefined && { rowActionMode: screen.rowActionMode }),
+    };
+}
+export function projectionActionProps(actions, translate, wrappedOnRowClick) {
+    const { bulk, toolbarActions } = actions;
+    return {
+        ...(bulk !== undefined && { bulk }),
+        ...(toolbarActions !== undefined && { toolbarActions }),
+        ...(translate !== undefined && { translate }),
+        ...(wrappedOnRowClick !== undefined && { onRowClick: wrappedOnRowClick }),
+    };
+}
+export function projectionFacetProps(filterFacets, dateRangeFacets, onDateRangeChange, urlState) {
+    return {
+        ...(filterFacets.length > 0 && {
+            filterFacets,
+            onFilterChange: urlState.setFilter,
+        }),
+        ...(dateRangeFacets.length > 0 && {
+            dateRangeFacets,
+            onDateRangeChange,
+        }),
+    };
+}
+export function projectionFilterStateProps(filterFacets, dateRangeFacets, urlState) {
+    return {
+        ...((filterFacets.length > 0 || dateRangeFacets.length > 0) && {
+            filterValues: urlState.filters,
+            onFilterReset: urlState.clearFilters,
+        }),
+    };
+}

package/dist/app/projection-list-render.d.ts

@@ -0,0 +1,26 @@
+import type { ProjectionListScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { ReactNode } from "react";
+import type { ListRowViewModel, Translate } from "../headless/index.ts";
+import type { usePrimitives } from "../primitives.tsx";
+import type { FeatureSchema } from "./feature-schema.ts";
+import type { useProjectionListActions } from "./use-projection-list-actions.ts";
+import type { useProjectionListData } from "./use-projection-list-data.ts";
+import type { useProjectionListDefinitions } from "./use-projection-list-definitions.ts";
+import type { useProjectionListQuery } from "./use-projection-list-query.ts";
+import type { listPager, ScreenListRows } from "./use-screen-list-rows.ts";
+export type ProjectionListRenderModel = {
+    readonly schema: FeatureSchema;
+    readonly screen: ProjectionListScreenDefinition;
+    readonly translate: Translate | undefined;
+    readonly effectiveTranslate: Translate;
+    readonly isEmbeddedScreen: boolean;
+    readonly definitions: ReturnType<typeof useProjectionListDefinitions>;
+    readonly query: ReturnType<typeof useProjectionListQuery>;
+    readonly data: ReturnType<typeof useProjectionListData>;
+    readonly actions: ReturnType<typeof useProjectionListActions>;
+    readonly pager: ReturnType<typeof listPager>;
+    readonly wrappedOnRowClick: ((row: ListRowViewModel) => void) | undefined;
+};
+export declare function renderQueryRetryBanner(listRows: ScreenListRows, error: NonNullable<ScreenListRows["error"]>, effectiveTranslate: Translate): ReactNode;
+export declare function renderBadShapeBanner(screen: ProjectionListScreenDefinition, primitives: Pick<ReturnType<typeof usePrimitives>, "Banner" | "Text">): ReactNode;
+export declare function renderProjectionList(model: ProjectionListRenderModel): ReactNode;

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

@@ -0,0 +1,20 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { RenderList } from "../components/render-list.js";
+import { isListNarrowed } from "./list-empty-content.js";
+import { projectionActionProps, projectionFacetProps, projectionFilterStateProps, projectionLayoutProps, projectionLeadProps, } from "./projection-list-render-props.js";
+import { QueryErrorBanner } from "./query-state-banners.js";
+export function renderQueryRetryBanner(listRows, error, effectiveTranslate) {
+    return _jsx(QueryErrorBanner, { error: error, translate: effectiveTranslate, onRetry: listRows.retry });
+}
+export function renderBadShapeBanner(screen, primitives) {
+    const { Banner, Text } = primitives;
+    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 }" }), "."] }));
+}
+export function renderProjectionList(model) {
+    const { schema, screen, translate, effectiveTranslate, isEmbeddedScreen } = model;
+    const { definitions, query, data, actions, pager, wrappedOnRowClick } = model;
+    const { urlState } = query;
+    const { filterFacets, listRows, listTable } = data;
+    const { dateRangeFacets } = query;
+    return (_jsx(RenderList, { screen: definitions.listScreen, entity: definitions.entity, rows: listRows.rows, featureName: schema.featureName, searchable: definitions.searchable, narrowed: isListNarrowed(query.activeSearch, urlState.filters), ...projectionLeadProps(screen, effectiveTranslate, actions.emptyContent), searchValue: urlState.q, onSearchChange: urlState.setQ, sort: query.activeSort, onSortChange: urlState.setSort, ...projectionLayoutProps(isEmbeddedScreen, screen, definitions.listScreen, pager, actions.rowActions), ...projectionActionProps(actions, translate, wrappedOnRowClick), ...projectionFacetProps(filterFacets, dateRangeFacets, query.handleDateRangeChange, urlState), ...listTable.props, ...projectionFilterStateProps(filterFacets, dateRangeFacets, urlState) }));
+}

package/dist/app/projection-list-row-click.d.ts

@@ -0,0 +1,12 @@
+import type { ProjectionListScreenDefinition, RowActionNavigate } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { ListRowViewModel } from "../headless/index.ts";
+import type { useDrawerAction } from "./action-form-body.tsx";
+type RowClickInput = {
+    readonly screen: ProjectionListScreenDefinition;
+    readonly onRowClick: ((row: ListRowViewModel, entityName: string) => void) | undefined;
+    readonly entityName: string;
+    readonly openDrawer: ReturnType<typeof useDrawerAction>["openDrawer"];
+    readonly runNavigate: (action: RowActionNavigate, row: ListRowViewModel) => unknown;
+};
+export declare function resolveWrappedRowClick(input: RowClickInput): ((row: ListRowViewModel) => void) | undefined;
+export {};

package/dist/app/projection-list-row-click.js

@@ -0,0 +1,14 @@
+import { findRowClickAction, runDrawerRowAction } from "./row-actions.js";
+export function resolveWrappedRowClick(input) {
+    const { screen, onRowClick, entityName, openDrawer, runNavigate } = input;
+    const rowClickAction = findRowClickAction(screen.rowActions);
+    if (rowClickAction) {
+        return (row) => rowClickAction.kind === "drawer"
+            ? runDrawerRowAction(rowClickAction, openDrawer, row)
+            : runNavigate(rowClickAction, row);
+    }
+    // skip: no row-click wiring when neither the screen nor the host supplies a handler
+    if (onRowClick === undefined)
+        return undefined;
+    return (row) => onRowClick(row, entityName);
+}

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;