@cosmicdrift/kumiko-renderer 0.389.0 → 0.390.0

package/dist/app/use-projection-detail-actions.js

@@ -0,0 +1,156 @@
+import { resolveActionIcon } from "@cosmicdrift/kumiko-types/action-icon";
+import { useCallback, useMemo } from "react";
+import { lastSegment } from "./qn.js";
+import { navigateToReturnOr, navigateWithReturnTo, } from "./return-to.js";
+import { buildRecordActions } from "./row-actions.js";
+import { findEditScreenFor } from "./screen-access.js";
+import { findEntityListScreen, navigateAfterRedirect } from "./screen-shared.js";
+export function useProjectionDetailActions(input) {
+    const { schema, screen, effectiveTranslate, effectiveEntityId, nav, host, dispatcher, clientActions, appFeatures, userRoles, returnTarget, openDrawer, detailQuery, reloadDetail, } = input;
+    const handleRecordLeft = useCallback((action, resultData, deletedShownRecord) => {
+        const record = detailQuery.data ?? {};
+        // Never return onto the just-deleted record.
+        const target = deletedShownRecord && returnTarget?.entityId === effectiveEntityId
+            ? undefined
+            : returnTarget;
+        if (action.redirect !== undefined) {
+            navigateAfterRedirect({
+                nav,
+                schema,
+                appFeatures,
+                returnTarget: target,
+                redirect: action.redirect,
+                resultData,
+                record,
+            });
+            // skip: the redirect already navigated
+            return;
+        }
+        navigateToReturnOr(nav, target, () => {
+            const listScreen = screen.listScreenId ??
+                (screen.detailFor !== undefined
+                    ? findEntityListScreen(schema, screen.detailFor)?.id
+                    : undefined);
+            if (listScreen !== undefined)
+                nav.navigate({ screenId: lastSegment(listScreen) });
+            else
+                void detailQuery.refetch();
+        });
+    }, [
+        detailQuery.data,
+        detailQuery.refetch,
+        nav,
+        schema,
+        appFeatures,
+        returnTarget,
+        effectiveEntityId,
+        screen.listScreenId,
+        screen.detailFor,
+    ]);
+    // Default edit action: resolved cross-feature over ALL mounted
+    // features, not just this feature's own schema — detailFor itself is
+    // resolved cross-feature by the boot-validator (detail-screens.ts), and
+    // the motivating case is a projectionDetail whose query belongs to one
+    // feature while the entity's entityEdit screen lives in another. Unlike
+    // useNavigateToCreateFor this must NOT filter on allowCreate/singleton —
+    // those gate create-targets, we're resolving an update-target by a
+    // known id.
+    const editScreen = useMemo(() => {
+        const detailFor = screen.detailFor;
+        // skip: no detailFor means there is no edit screen to resolve
+        if (detailFor === undefined)
+            return undefined;
+        return findEditScreenFor(detailFor, appFeatures, userRoles);
+    }, [appFeatures, screen.detailFor, userRoles]);
+    const defaultEditAction = useMemo(() => {
+        // skip: no edit screen for this entity, so no default edit action
+        if (editScreen === undefined)
+            return undefined;
+        // editScreen.id is registry-qualified ("feature:screen:contact-edit");
+        // nav.navigate expects the short form (see useNavigateToCreateFor).
+        const targetScreenId = lastSegment(editScreen.id);
+        return {
+            id: "edit",
+            label: effectiveTranslate("kumiko.actions.edit"),
+            icon: resolveActionIcon("edit"),
+            onPress: () => {
+                const target = {
+                    screenId: targetScreenId,
+                    ...(effectiveEntityId !== undefined && { entityId: effectiveEntityId }),
+                };
+                navigateWithReturnTo(nav, target, host);
+            },
+        };
+    }, [editScreen, effectiveTranslate, nav, effectiveEntityId, host]);
+    // a navigate-screen action targeting an entityEdit screen for the
+    // SAME entity this projectionDetail shows (screen.detailFor) defaults its
+    // entityId to the shown record's own id — without this fallback the target
+    // opens an empty create-form instead of the shown record, silently.
+    // Searched cross-feature, consistent with editScreen above.
+    const sameEntityScreenId = useCallback((targetScreen) => {
+        const record = detailQuery.data ?? {};
+        const targetIsEntityEditSameEntity = screen.detailFor !== undefined &&
+            appFeatures.some((feature) => feature.screens.some((s) => s.type === "entityEdit" &&
+                s.entity === screen.detailFor &&
+                lastSegment(s.id) === targetScreen));
+        return targetIsEntityEditSameEntity ? String(record["id"] ?? "") : undefined;
+    }, [detailQuery.data, screen.detailFor, appFeatures]);
+    const buildSectionActions = useCallback((actions) => buildRecordActions({
+        actions,
+        record: detailQuery.data ?? {},
+        translate: effectiveTranslate,
+        nav,
+        host,
+        dispatcher,
+        openDrawer,
+        onWriteSuccess: reloadDetail,
+        onRecordLeft: handleRecordLeft,
+        sameEntityScreenId,
+        clientActions,
+    }), [
+        detailQuery.data,
+        reloadDetail,
+        effectiveTranslate,
+        nav,
+        host,
+        dispatcher,
+        clientActions,
+        openDrawer,
+        handleRecordLeft,
+        sameEntityScreenId,
+    ]);
+    const headerActions = useMemo(() => {
+        const declaredHasEdit = screen.actions?.some((a) => a.id === "edit") === true;
+        const resolved = buildRecordActions({
+            actions: screen.actions ?? [],
+            record: detailQuery.data ?? {},
+            translate: effectiveTranslate,
+            nav,
+            host,
+            dispatcher,
+            openDrawer,
+            onWriteSuccess: reloadDetail,
+            onRecordLeft: handleRecordLeft,
+            sameEntityScreenId,
+            clientActions,
+        });
+        // skip: a declared or unavailable edit action leaves the resolved list untouched
+        if (defaultEditAction === undefined || declaredHasEdit)
+            return resolved;
+        return [defaultEditAction, ...(resolved ?? [])];
+    }, [
+        screen.actions,
+        defaultEditAction,
+        effectiveTranslate,
+        nav,
+        host,
+        dispatcher,
+        clientActions,
+        detailQuery.data,
+        reloadDetail,
+        openDrawer,
+        handleRecordLeft,
+        sameEntityScreenId,
+    ]);
+    return { buildSectionActions, headerActions };
+}

package/dist/app/use-projection-detail-data.d.ts

@@ -0,0 +1,19 @@
+import type { ProjectionDetailScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { usePrimitives } from "../primitives.tsx";
+import type { NavApi } from "./nav.tsx";
+type DetailDataInput = {
+    readonly screen: ProjectionDetailScreenDefinition;
+    readonly Tabs: ReturnType<typeof usePrimitives>["Tabs"];
+    readonly nav: NavApi;
+    readonly effectiveEntityId: string | undefined;
+};
+export declare function useProjectionDetailData(input: DetailDataInput): {
+    activeSection: import("@cosmicdrift/kumiko-framework/ui-types").EditSectionSpec | undefined;
+    hasTabs: boolean;
+    entity: Pick<import("@cosmicdrift/kumiko-types/fields").EntityDefinition, "fields">;
+    detailScreen: import("@cosmicdrift/kumiko-framework/ui-types").EntityEditScreenDefinition;
+    detailQuery: import("../hooks/use-query.ts").UseQueryResult<Readonly<Record<string, unknown>>>;
+    reloadNonce: number;
+    reloadDetail: () => Promise<void>;
+};
+export {};

package/dist/app/use-projection-detail-data.js

@@ -0,0 +1,47 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { rendererWarn } from "../dev-console.js";
+import { useQuery } from "../hooks/use-query.js";
+import { synthesizeProjectionDetailEntity, synthesizeProjectionDetailScreen, } from "./projection-detail-shim.js";
+import { refetchAfterWrite } from "./row-actions.js";
+export function useProjectionDetailData(input) {
+    const { screen, Tabs, nav, effectiveEntityId } = input;
+    const idParam = screen.idParam ?? "id";
+    const isTabsMode = screen.layout.mode === "tabs";
+    const activeSection = useMemo(() => {
+        // skip: only tabs mode with a registered Tabs primitive has an active section
+        if (!isTabsMode || Tabs === undefined)
+            return undefined;
+        const tabParam = nav.searchParams["tab"];
+        return (screen.layout.sections.find((section) => section.id === tabParam) ?? screen.layout.sections[0]);
+    }, [isTabsMode, Tabs, screen.layout.sections, nav.searchParams]);
+    const hasTabs = isTabsMode && Tabs !== undefined && activeSection !== undefined;
+    // Tabs is an optional Core-Primitive: without it the screen falls back to
+    // the stacked all-sections layout instead of silently truncating to section 1.
+    useEffect(() => {
+        if (isTabsMode && Tabs === undefined) {
+            rendererWarn(`[kumiko] screen "${screen.id}" uses layout.mode: "tabs", but no <Tabs> primitive is registered — the tab strip will not render. createKumikoApp() from kumiko-renderer-web wires it automatically.`);
+        }
+    }, [isTabsMode, Tabs, screen.id]);
+    const entity = useMemo(() => synthesizeProjectionDetailEntity(screen.layout), [screen.layout]);
+    const detailScreen = useMemo(() => {
+        const source = activeSection !== undefined
+            ? { ...screen, layout: { ...screen.layout, sections: [activeSection] } }
+            : screen;
+        return synthesizeProjectionDetailScreen(source);
+    }, [screen, activeSection]);
+    const detailQuery = useQuery(screen.query, effectiveEntityId !== undefined ? { [idParam]: effectiveEntityId } : {});
+    // A writeForm section's handler creates a new record (see EditWriteFormSection's
+    // doc) — both the outer record (header/metrics/other sections) and a sibling
+    // relatedList section's own independently-fetched rows must reflect it. A
+    // query refetch alone only refreshes `record` below; bumping this as
+    // <RenderEdit>'s refreshToken makes RelatedListSection's own useQuery
+    // re-run too (it has no `live` subscription of its own). Refetch instead of
+    // remount (a `key`) so unsaved input in the other writeForm sections and
+    // the related lists' local state survive.
+    const [reloadNonce, setReloadNonce] = useState(0);
+    const reloadDetail = useCallback(async () => {
+        await refetchAfterWrite(detailQuery.refetch);
+        setReloadNonce((n) => n + 1);
+    }, [detailQuery.refetch]);
+    return { activeSection, hasTabs, entity, detailScreen, detailQuery, reloadNonce, reloadDetail };
+}

package/dist/app/use-projection-detail-layout.d.ts

@@ -0,0 +1,17 @@
+import type { ProjectionDetailScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { RenderEditAction } from "../components/render-edit.tsx";
+import type { useProjectionDetailData } from "./use-projection-detail-data.ts";
+type DetailLayoutInput = {
+    readonly screen: ProjectionDetailScreenDefinition;
+    readonly headerActions: readonly RenderEditAction[] | undefined;
+    readonly hasTabs: boolean;
+    readonly detailScreen: ReturnType<typeof useProjectionDetailData>["detailScreen"];
+};
+export declare function useProjectionDetailLayout(input: DetailLayoutInput): {
+    hasMetrics: boolean;
+    headerActionsList: readonly RenderEditAction[];
+    hasHeaderActions: boolean;
+    hasHeaderCard: boolean;
+    renderedDetailScreen: import("@cosmicdrift/kumiko-framework/ui-types").EntityEditScreenDefinition;
+};
+export {};

package/dist/app/use-projection-detail-layout.js

@@ -0,0 +1,23 @@
+import { useMemo } from "react";
+import { screenFillsHeight } from "../screen-fills-height.js";
+const HEADER_CARD_DEFAULT_WIDTH = "4xl";
+export function useProjectionDetailLayout(input) {
+    const { screen, headerActions, hasTabs, detailScreen } = input;
+    const hasHeader = screen.header !== undefined;
+    const hasMetrics = screen.metrics !== undefined && screen.metrics.length > 0;
+    // ?? [] rather than threading `headerActions !== undefined` through every
+    // use below — an empty array is a safe no-op for .map/.length.
+    const headerActionsList = headerActions ?? [];
+    const hasHeaderActions = headerActionsList.length > 0;
+    const hasHeaderCard = hasHeader || hasMetrics || hasHeaderActions;
+    // A header card (metric band, status, actions) needs more room than the
+    // 640px form column; screens with only a record title keep the narrow one.
+    const widensScreenFormColumn = hasHeaderCard &&
+        !hasTabs &&
+        screenFillsHeight(screen) &&
+        detailScreen.layout.width === undefined;
+    const renderedDetailScreen = useMemo(() => widensScreenFormColumn
+        ? { ...detailScreen, layout: { ...detailScreen.layout, width: HEADER_CARD_DEFAULT_WIDTH } }
+        : detailScreen, [detailScreen, widensScreenFormColumn]);
+    return { hasMetrics, headerActionsList, hasHeaderActions, hasHeaderCard, renderedDetailScreen };
+}

package/dist/app/use-projection-list-actions.d.ts

@@ -0,0 +1,31 @@
+import type { ProjectionListScreenDefinition, RowActionNavigate } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { useOptionalDispatcher } from "../context/dispatcher-context.tsx";
+import type { useUserRoles } from "../context/user-roles-context.tsx";
+import type { ListRowViewModel, Translate } from "../headless/index.ts";
+import type { useDrawerAction } from "./action-form-body.tsx";
+import type { useAppFeatures } from "./app-features-context.tsx";
+import type { useClientActionRuntime } from "./client-actions.tsx";
+import type { useNav } from "./nav.tsx";
+import type { useReturnHost } from "./return-to.tsx";
+import type { useProjectionListDefinitions } from "./use-projection-list-definitions.ts";
+type ProjectionListActionsInput = {
+    readonly screen: ProjectionListScreenDefinition;
+    readonly effectiveTranslate: Translate;
+    readonly dispatcher: ReturnType<typeof useOptionalDispatcher>;
+    readonly clientActions: ReturnType<typeof useClientActionRuntime>;
+    readonly nav: ReturnType<typeof useNav>;
+    readonly host: ReturnType<typeof useReturnHost>;
+    readonly refreshRows: () => Promise<void>;
+    readonly openDrawer: ReturnType<typeof useDrawerAction>["openDrawer"];
+    readonly appFeatures: ReturnType<typeof useAppFeatures>;
+    readonly userRoles: ReturnType<typeof useUserRoles>;
+    readonly defaultEditScreen: ReturnType<typeof useProjectionListDefinitions>["defaultEditScreen"];
+};
+export declare function useProjectionListActions(input: ProjectionListActionsInput): {
+    runNavigate: (action: RowActionNavigate, row: ListRowViewModel) => void;
+    rowActions: readonly import("../primitives.tsx").DataTableRowAction[] | undefined;
+    toolbarActions: readonly import("../components/render-list-toolbar-action.tsx").ToolbarActionButton[] | undefined;
+    bulk: import("../data-table-bulk-types.ts").DataTableBulk | undefined;
+    emptyContent: import("../components/list-empty-state.tsx").ListEmptyStateContent | undefined;
+};
+export {};

package/dist/app/use-projection-list-actions.js

@@ -0,0 +1,73 @@
+import { useCallback, useMemo } from "react";
+import { useListBulk } from "./list-bulk-actions.js";
+import { useListEmptyContent } from "./list-empty-content.js";
+import { buildDefaultEditRowAction, buildProjectionRowActions, buildProjectionToolbarActions, runProjectionRowNavigate, } from "./row-actions.js";
+export function useProjectionListActions(input) {
+    const { screen, effectiveTranslate, dispatcher, clientActions, nav, host, refreshRows, openDrawer, appFeatures, userRoles, defaultEditScreen, } = input;
+    // 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: refreshRows,
+        openDrawer,
+        defaultEditRowAction,
+        host,
+        clientActions,
+    }), [
+        screen.rowActions,
+        effectiveTranslate,
+        dispatcher,
+        clientActions,
+        nav,
+        refreshRows,
+        openDrawer,
+        defaultEditRowAction,
+        host,
+    ]);
+    const toolbarActions = useMemo(() => buildProjectionToolbarActions({
+        toolbarActions: screen.toolbarActions,
+        translate: effectiveTranslate,
+        dispatcher,
+        nav,
+        refetch: refreshRows,
+        openDrawer,
+        host,
+        access: { appFeatures, userRoles },
+    }), [
+        screen.toolbarActions,
+        effectiveTranslate,
+        nav,
+        host,
+        dispatcher,
+        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: refreshRows,
+    });
+    return { runNavigate, rowActions, toolbarActions, bulk, emptyContent };
+}

package/dist/app/use-projection-list-data.d.ts

@@ -0,0 +1,20 @@
+import type { ProjectionListScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Translate } from "../headless/index.ts";
+import type { DataTableFacet } from "../primitives.tsx";
+import { type ResolvedFacetSpec } from "./list-facets.ts";
+import { useScreenListRows } from "./use-screen-list-rows.ts";
+type ProjectionListDataInput = {
+    readonly screen: ProjectionListScreenDefinition;
+    readonly featureName: string;
+    readonly queryPayload: Parameters<typeof useScreenListRows>[0]["payload"];
+    readonly limit: number;
+    readonly usePager: boolean;
+    readonly effectiveTranslate: Translate;
+    readonly resolvedFacetSpecs: readonly ResolvedFacetSpec[];
+};
+export declare function useProjectionListData(input: ProjectionListDataInput): {
+    listTable: import("./use-screen-list-table.ts").ScreenListTable;
+    listRows: import("./use-screen-list-rows.ts").ScreenListRows;
+    filterFacets: DataTableFacet[];
+};
+export {};

package/dist/app/use-projection-list-data.js

@@ -0,0 +1,26 @@
+import { useMemo } from "react";
+import { buildFilterFacets } from "./list-facets.js";
+import { useScreenListRows } from "./use-screen-list-rows.js";
+import { useScreenListTable } from "./use-screen-list-table.js";
+export function useProjectionListData(input) {
+    const { screen, featureName, queryPayload, limit, usePager, effectiveTranslate, resolvedFacetSpecs, } = input;
+    const facetFilterFields = useMemo(() => (screen.facets ?? []).map((facet) => facet.field), [screen.facets]);
+    const listTable = useScreenListTable({
+        screen,
+        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 filterFacets = useMemo(() => buildFilterFacets(resolvedFacetSpecs), [resolvedFacetSpecs]);
+    return { listTable, listRows, filterFacets };
+}

package/dist/app/use-projection-list-definitions.d.ts

@@ -0,0 +1,11 @@
+import type { ProjectionListScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { useUserRoles } from "../context/user-roles-context.tsx";
+import type { useAppFeatures } from "./app-features-context.tsx";
+export declare function useProjectionListDefinitions(screen: ProjectionListScreenDefinition, appFeatures: ReturnType<typeof useAppFeatures>, userRoles: ReturnType<typeof useUserRoles>): {
+    defaultEditScreen: import("@cosmicdrift/kumiko-framework/ui-types").EntityEditScreenDefinition | undefined;
+    searchable: boolean;
+    sortable: boolean;
+    paginated: boolean;
+    entity: Pick<import("@cosmicdrift/kumiko-types/fields").EntityDefinition, "fields">;
+    listScreen: import("@cosmicdrift/kumiko-framework/ui-types").EntityListScreenDefinition;
+};

package/dist/app/use-projection-list-definitions.js

@@ -0,0 +1,20 @@
+import { useMemo } from "react";
+import { synthesizeProjectionEntity, synthesizeProjectionScreen } from "./projection-list-shim.js";
+import { findEditScreenFor } from "./screen-access.js";
+export function useProjectionListDefinitions(screen, appFeatures, userRoles) {
+    const defaultEditScreen = useMemo(() => {
+        const detailFor = screen.detailFor;
+        // skip: no detail screen declared, so rows get no default edit action
+        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]);
+    return { defaultEditScreen, searchable, sortable, paginated, entity, listScreen };
+}

package/dist/app/use-projection-list-query.d.ts

@@ -0,0 +1,28 @@
+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 { synthesizeProjectionEntity } from "./projection-list-shim.ts";
+import type { ReferenceFacetOption } from "./reference-facet-bridge.tsx";
+type ProjectionListQueryInput = {
+    readonly screen: ProjectionListScreenDefinition;
+    readonly featureName: string;
+    readonly effectiveTranslate: Translate;
+    readonly entity: ReturnType<typeof synthesizeProjectionEntity>;
+    readonly searchable: boolean;
+    readonly sortable: boolean;
+    readonly paginated: boolean;
+};
+export declare function useProjectionListQuery(input: ProjectionListQueryInput): {
+    urlState: ListUrlStateApi;
+    activeSearch: string;
+    activeSort: import("../primitives.tsx").DataTableSort | null;
+    limit: number;
+    usePager: boolean;
+    facetSpecs: import("./list-facets.ts").ResolvedFacetSpec[];
+    handleProjectionFacetOptions: (field: string, options: readonly ReferenceFacetOption[]) => void;
+    resolvedFacetSpecs: import("./list-facets.ts").ResolvedFacetSpec[];
+    dateRangeFacets: import("../data-table-facet-types.ts").DataTableDateRangeFacet[];
+    handleDateRangeChange: (field: string, bound: "from" | "to", value: string) => void;
+    queryPayload: Record<string, unknown>;
+};
+export {};

package/dist/app/use-projection-list-query.js

@@ -0,0 +1,83 @@
+import { useCallback, useMemo, useState } from "react";
+import { useListUrlState } from "../hooks/use-list-url-state.js";
+import { buildFilterPayload, mergeReferenceFacetOptions, resolveProjectionFacetSpecs, } from "./list-facets.js";
+import { buildListQueryPayload } from "./screen-shared.js";
+import { useProjectionDateRange } from "./use-projection-date-range.js";
+// Same predicate that makes a header clickable: a stale link onto a
+// sortable:false/unknown column must not reach the server (it answers 400).
+function resolveActiveSort(urlSort, input) {
+    const { screen, entity, sortable } = input;
+    const urlSortField = urlSort === null ? undefined : entity.fields[urlSort.field];
+    const urlSortAllowed = urlSortField !== undefined && "sortable" in urlSortField && urlSortField.sortable === true;
+    return sortable ? ((urlSortAllowed ? urlSort : null) ?? screen.defaultSort ?? null) : null;
+}
+export function useProjectionListQuery(input) {
+    const { screen, featureName, effectiveTranslate, searchable, paginated } = input;
+    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 : "";
+    const activeSort = resolveActiveSort(urlState.sort, input);
+    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, featureName), [screen.facets, effectiveTranslate, 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]);
+    const { dateRangePayload, dateRangeFacets, handleDateRangeChange } = useProjectionDateRange(screen.facets, effectiveTranslate, urlState);
+    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,
+    ]);
+    return {
+        urlState,
+        activeSearch,
+        activeSort,
+        limit,
+        usePager,
+        facetSpecs,
+        handleProjectionFacetOptions,
+        resolvedFacetSpecs,
+        dateRangeFacets,
+        handleDateRangeChange,
+        queryPayload,
+    };
+}

package/dist/components/render-edit-banners.d.ts

@@ -0,0 +1,12 @@
+import type { ReactNode } from "react";
+import type { FormValues } from "../headless/index.ts";
+import type { RenderEditModel } from "./render-edit-render-model.ts";
+export declare function renderAllRequiredHint<TValues extends FormValues, TCtx>({ engine: { state }, }: RenderEditModel<TValues, TCtx>): ReactNode;
+export declare function renderDraftPicker<TValues extends FormValues, TCtx>({ engine: { state, draftActions }, }: RenderEditModel<TValues, TCtx>): ReactNode;
+export declare function renderWizardProgress<TValues extends FormValues, TCtx>({ engine: { state, steps, sections, nav }, titles, }: RenderEditModel<TValues, TCtx>): ReactNode;
+export declare function renderTabStrip<TValues extends FormValues, TCtx>({ engine: { state, steps, sections, nav }, }: RenderEditModel<TValues, TCtx>): ReactNode;
+export declare function renderFormErrorBanner<TValues extends FormValues, TCtx>({ engine: { props, state }, layout, }: RenderEditModel<TValues, TCtx>): ReactNode;
+export declare function renderRootIssueBanners<TValues extends FormValues, TCtx>({ engine: { state }, layout, }: RenderEditModel<TValues, TCtx>): ReactNode;
+export declare function renderExtensionErrorBanner<TValues extends FormValues, TCtx>({ engine: { state }, }: RenderEditModel<TValues, TCtx>): ReactNode;
+export declare function renderActionErrorBanner<TValues extends FormValues, TCtx>({ engine: { state }, }: RenderEditModel<TValues, TCtx>): ReactNode;
+export declare function renderDeleteDialog<TValues extends FormValues, TCtx>({ engine: { props, state }, }: RenderEditModel<TValues, TCtx>): ReactNode;