@cosmicdrift/kumiko-renderer 0.388.0 → 0.390.0

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-projection-detail-actions.d.ts

@@ -0,0 +1,35 @@
+import type { ProjectionDetailScreenDefinition, RowAction } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { RenderEditAction } from "../components/render-edit.tsx";
+import type { useOptionalDispatcher } from "../context/dispatcher-context.tsx";
+import type { useUserRoles } from "../context/user-roles-context.tsx";
+import type { 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 { FeatureSchema } from "./feature-schema.ts";
+import type { NavApi } from "./nav.tsx";
+import { type useReturnHost, type useReturnTarget } from "./return-to.tsx";
+import type { useProjectionDetailData } from "./use-projection-detail-data.ts";
+type DetailActionsInput = {
+    readonly schema: FeatureSchema;
+    readonly screen: ProjectionDetailScreenDefinition & {
+        readonly detailFor?: string;
+    };
+    readonly effectiveTranslate: Translate;
+    readonly effectiveEntityId: string | undefined;
+    readonly nav: NavApi;
+    readonly host: ReturnType<typeof useReturnHost>;
+    readonly dispatcher: ReturnType<typeof useOptionalDispatcher>;
+    readonly clientActions: ReturnType<typeof useClientActionRuntime>;
+    readonly appFeatures: ReturnType<typeof useAppFeatures>;
+    readonly userRoles: ReturnType<typeof useUserRoles>;
+    readonly returnTarget: ReturnType<typeof useReturnTarget> | undefined;
+    readonly openDrawer: ReturnType<typeof useDrawerAction>["openDrawer"];
+    readonly detailQuery: ReturnType<typeof useProjectionDetailData>["detailQuery"];
+    readonly reloadDetail: ReturnType<typeof useProjectionDetailData>["reloadDetail"];
+};
+export declare function useProjectionDetailActions(input: DetailActionsInput): {
+    buildSectionActions: (actions: readonly RowAction[]) => readonly RenderEditAction[] | undefined;
+    headerActions: readonly RenderEditAction[] | undefined;
+};
+export {};

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