@cosmicdrift/kumiko-renderer 0.389.0 → 0.390.0

package/dist/components/render-list.js

@@ -1,23 +1,14 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { UNRESOLVED_REFERENCE_LABEL_KEYS, } from "@cosmicdrift/kumiko-framework/ui-types";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { extensionSectionName, useExtensionSectionComponent } from "../app/extension-sections.js";
-import { useReferenceLinkResolver } from "../app/reference-link.js";
-import { rendererWarn } from "../dev-console.js";
-import { computeListViewModel, EMPTY_VALUE_PLACEHOLDER } from "../headless/index.js";
-import { useReferenceLookup } from "../hooks/use-reference-lookup.js";
+import { useState } from "react";
 import { useTranslation } from "../i18n.js";
 import { usePageHeaderCompact, usePageHeaderSlotAvailable } from "../page-header-slot.js";
-import { shouldRenderActionsIconOnly, usePrimitives, } from "../primitives.js";
-import { ListEmptyStateBody } from "./list-empty-state.js";
-import { needsActionConfirm } from "./render-edit-action-button.js";
-import { ToolbarActionView } from "./render-list-toolbar-action.js";
-const SEARCH_DEBOUNCE_MS = 300;
-// Icon-less actions are promoted too; on phones the call site falls back to a
-// "plus" icon, on desktop the label carries the action.
-function isHeaderPromotableToolbarAction(action) {
-    return action.style === "primary" && !needsActionConfirm(action);
-}
+import { usePrimitives } from "../primitives.js";
+import { renderReferenceLookupBridges } from "./render-list-reference-bridge.js";
+import { tableChromeProps, tableFilterProps, tableLayoutProps, tableRowProps, tableSortPagingProps, } from "./render-list-table-props.js";
+import { composeEmptyState, renderCreateButton, renderHeaderActions, renderMenuActionError, renderPageHeader, renderSearchInput, renderToolbarEnd, } from "./render-list-toolbar.js";
+import { buildPromotedMenuItems, resolveItemNoun, resolveToolbarLabels, resolveToolbarTitle, splitToolbarActions, } from "./render-list-toolbar-model.js";
+import { useRenderListColumns } from "./use-render-list-columns.js";
+import { useRenderListSearch } from "./use-render-list-search.js";
 export function RenderList(props) {
     const { screen, entity, rows, featureName, translate: translateProp, onRowClick, emptyState, onCreate, createLabel, searchable = false, searchPlaceholder, description, emptyContent, narrowed = false, defaultFilterActive: defaultFilterActiveProp = false, itemNounKey, searchValue, onSearchChange, sort, onSortChange, pager, onReachEnd, loadingMore, hasMore, rowActions, rowActionMode, bulk, rowTone, toolbarActions, filterFacets, filterValues, onFilterChange, onFilterReset, dateRangeFacets, onDateRangeChange, chromeless, scrollBody, screenPadding, expandedRowIds, onToggleRowExpanded, renderExpandedRow, ...tableBlockProps } = props;
     // As in RenderEdit, fall back to the i18next context for translation;
@@ -32,303 +23,96 @@ export function RenderList(props) {
     // their own, so their busy and error state lives here.
     const [menuActionBusyId, setMenuActionBusyId] = useState(null);
     const [menuActionError, setMenuActionError] = useState(null);
-    // Local search buffer + debounce. External changes (browser back,
-    // cross-component reset) are mirrored back; typing only fires
-    // onSearchChange after 300ms without further keystrokes.
-    const [localQ, setLocalQ] = useState(searchValue ?? "");
-    // Sync during render, not in a useEffect: the passive effect also fires on
-    // mount and can flush after a keystroke landing in the same commit,
-    // resetting localQ and swallowing the input.
-    const [syncedSearchValue, setSyncedSearchValue] = useState(searchValue);
-    // The parent may echo our own debounced emits back late (router/URL round
-    // trip), possibly after a newer emit already went out; adopting such a stale
-    // echo would erase keys typed in between. All unechoed emits are kept, and a
-    // matching echo drops itself and every older one. The render phase only reads
-    // the list (a discarded or repeated render must find the echo again); the
-    // matched entries are dropped in an effect.
-    const pendingEmitsRef = useRef([]);
-    if (searchValue !== syncedSearchValue) {
-        setSyncedSearchValue(searchValue);
-        if (!pendingEmitsRef.current.includes(searchValue ?? "")) {
-            setLocalQ(searchValue ?? "");
-            pendingEmitsRef.current = [];
-        }
-    }
-    useEffect(() => {
-        const echoIndex = pendingEmitsRef.current.indexOf(syncedSearchValue ?? "");
-        if (echoIndex >= 0)
-            pendingEmitsRef.current.splice(0, echoIndex + 1);
-    }, [syncedSearchValue]);
-    useEffect(() => {
-        if (onSearchChange === undefined)
-            return;
-        if (localQ === (searchValue ?? ""))
-            return;
-        // A late echo of an older emit changes searchValue but must not re-send
-        // the value that is already in flight.
-        if (pendingEmitsRef.current.at(-1) === localQ)
-            return;
-        const timer = setTimeout(() => {
-            pendingEmitsRef.current.push(localQ);
-            onSearchChange(localQ);
-        }, SEARCH_DEBOUNCE_MS);
-        return () => clearTimeout(timer);
-    }, [localQ, searchValue, onSearchChange]);
-    const vm = useMemo(() => computeListViewModel({ screen, entity, rows, translate, featureName }), [screen, entity, rows, translate, featureName]);
-    // Reference-field eager loading through bridge components.
-    // The Hooks rule requires useReferenceLookup for each reference column,
-    // but the number of columns varies with the schema. Each column therefore
-    // mounts a ReferenceLookupBridge that publishes its map to local state
-    // through onMap. Each bridge makes a constant number of hook calls (one),
-    // and React manages its lifecycle when the schema changes via key.
-    const referenceColumns = useMemo(() => vm.columns
-        .filter((c) => c.type === "reference" && c.refEntity !== undefined)
-        .map((c) => ({
-        field: c.field,
-        refEntity: c.refEntity ?? "",
-        // refFeature comes from parseRefTarget in the ViewModel
-        // (default = the current featureName).
-        refFeature: c.refFeature ?? featureName,
-        labelField: c.refLabelField ?? "id",
-    })), [vm.columns, featureName]);
-    const [referenceLookups, setReferenceLookups] = useState({});
-    const handleLookupMap = useCallback((field, lookup) => {
-        setReferenceLookups((prev) => {
-            // Skip the update when the lookup is identical. Otherwise the bridge
-            // would re-render and send the same map back until React entered
-            // an infinite loop.
-            const current = prev[field];
-            if (current?.map === lookup.map && current.complete === lookup.complete)
-                return prev;
-            return { ...prev, [field]: lookup };
-        });
-    }, []);
-    const resolveReferenceLink = useReferenceLinkResolver();
-    const enrichedColumns = useMemo(() => {
-        if (referenceColumns.length === 0)
-            return vm.columns;
-        return vm.columns.map((col) => {
-            if (col.type !== "reference")
-                return col;
-            // An author-declared renderer always takes precedence;
-            // the default is used only when none is set.
-            if (col.renderer !== undefined)
-                return col;
-            const published = referenceLookups[col.field];
-            const map = published?.map;
-            const unknownKey = UNRESOLVED_REFERENCE_LABEL_KEYS[`${col.refFeature ?? featureName}:${col.refEntity ?? ""}`];
-            // No raw id for entities that opt in: a placeholder while the lookup
-            // loads, the "unknown" label once the complete lookup found nothing. A
-            // capped lookup page cannot prove absence, so it keeps the raw id.
-            const unresolvedLabel = (id) => unknownKey === undefined
-                ? id
-                : published === undefined
-                    ? EMPTY_VALUE_PLACEHOLDER
-                    : published.complete
-                        ? translate(unknownKey)
-                        : id;
-            const labelField = col.refLabelField ?? "id";
-            const refEntity = col.refEntity ?? "";
-            // Only a row the user can see is linkable: resolved by the server
-            // eagerload or by the lookup query. A multi-reference links per entry via linkItemsFor.
-            const linkFor = (value, row) => {
-                if (value === null || value === undefined || value === "" || Array.isArray(value)) {
-                    return undefined;
-                }
-                const id = String(value);
-                const eagerloaded = eagerloadedRef(row, col.field);
-                // The server leaves a missing or unreadable target out; null is treated the same.
-                const resolved = (typeof eagerloaded === "object" &&
-                    eagerloaded !== null &&
-                    !Array.isArray(eagerloaded)) ||
-                    map?.has(id);
-                return resolved === true ? resolveReferenceLink(refEntity, id) : undefined;
-            };
-            const linkItemsFor = (value, row) => {
-                if (!Array.isArray(value) || value.length === 0)
-                    return undefined;
-                const eagerloaded = eagerloadedRef(row, col.field);
-                const eagerById = new Map(Array.isArray(eagerloaded) ? eagerloaded.map((r) => [String(r["id"]), r]) : []);
-                return value.map((v) => {
-                    const id = String(v);
-                    const target = eagerById.get(id);
-                    const label = String(target?.[labelField] ?? map?.get(id) ?? unresolvedLabel(id));
-                    // Only a row the user can see is linkable: server eagerload or lookup query.
-                    const link = target !== undefined || map?.has(id) === true
-                        ? resolveReferenceLink(refEntity, id)
-                        : undefined;
-                    return { id, label, ...(link !== undefined && { link }) };
-                });
-            };
-            const renderer = (value, row) => {
-                // Server eager loading: when the server includes _refs, read the display
-                // value directly from the resolved row. This avoids a round trip
-                // through the bridge map and the limit:200 constraint. The
-                // EagerloadedRow type from @cosmicdrift/kumiko-framework/db defines
-                // the shape of _refs.
-                const resolved = eagerloadedRef(row, col.field);
-                if (Array.isArray(resolved) && resolved.length > 0) {
-                    return resolved.map((r) => String(r[labelField] ?? r["id"] ?? "")).join(", ");
-                }
-                if (isPlainRecord(resolved)) {
-                    return String(resolved[labelField] ?? resolved["id"] ?? "");
-                }
-                // Renderer-side fallback when server eager loading is not active.
-                if (Array.isArray(value)) {
-                    if (value.length === 0)
-                        return EMPTY_VALUE_PLACEHOLDER;
-                    return value.map((v) => map?.get(String(v)) ?? unresolvedLabel(String(v))).join(", ");
-                }
-                if (value === null || value === undefined || value === "")
-                    return EMPTY_VALUE_PLACEHOLDER;
-                const idStr = String(value);
-                return map?.get(idStr) ?? unresolvedLabel(idStr);
-            };
-            return { ...col, renderer, linkFor, linkItemsFor };
-        });
-    }, [
-        vm.columns,
-        referenceColumns,
-        referenceLookups,
-        resolveReferenceLink,
+    const { localQ, setLocalQ } = useRenderListSearch(searchValue, onSearchChange);
+    const { referenceColumns, handleLookupMap, enrichedVm } = useRenderListColumns({
+        screen,
+        entity,
+        rows,
         featureName,
         translate,
-    ]);
-    const enrichedVm = useMemo(() => ({
-        ...vm,
-        columns: enrichedColumns,
-    }), [vm, enrichedColumns]);
-    // i18n defaults for toolbar and empty-state strings. The caller can
-    // override each one through a prop; otherwise the framework bundles provide
-    // them (kumiko.actions.create, kumiko.list.search-placeholder, …).
-    const effectiveCreateLabel = translate(createLabel ?? screen.createLabel ?? "kumiko.actions.create");
-    const effectiveSearchPlaceholder = translate(searchPlaceholder ?? screen.searchPlaceholder ?? "kumiko.list.search-placeholder");
-    const nounKey = itemNounKey ?? `${featureName}:entity:${screen.entity}:noun`;
-    const itemNoun = (itemNounKey !== undefined || !screen.entity.startsWith("__")) &&
-        translate(nounKey, { count: 2 }) !== nounKey
-        ? (count) => translate(nounKey, { count })
+    });
+    const labelInput = {
+        screen,
+        translate,
+        createLabel,
+        searchPlaceholder,
+        itemNounKey,
+        featureName,
+    };
+    const { effectiveCreateLabel, effectiveSearchPlaceholder } = resolveToolbarLabels(labelInput);
+    const itemNoun = resolveItemNoun(labelInput);
+    const toolbarStart = searchable
+        ? renderSearchInput(Input, localQ, setLocalQ, effectiveSearchPlaceholder)
         : undefined;
-    const toolbarStart = searchable ? (_jsx(Input, { kind: "text", id: "render-list-search", name: "search", value: localQ, onChange: setLocalQ, placeholder: effectiveSearchPlaceholder })) : undefined;
     // Toolbar-end slot: an optional header slot (for example, a cap counter,
     // at the left of the right-hand cluster), toolbar actions from the schema,
     // and an optional "+ New" button at the right edge. The header slot lives
     // inside the toolbar row, with the same card frame, rather than as loose
     // text above the screen title. Items retain array order, and "+ New" comes
     // last because it is the most common and prominent CTA.
-    const hasToolbarActions = toolbarActions !== undefined && toolbarActions.length > 0;
-    const hasHeaderSlot = screen.slots?.header !== undefined;
-    const toolbarIconOnly = hasToolbarActions && shouldRenderActionsIconOnly(toolbarActions);
-    const createButton = onCreate !== undefined && createInPageHeader && pageHeaderCompact ? (_jsx(Button, { variant: "primary", icon: "plus", size: "icon", ariaLabel: effectiveCreateLabel, title: effectiveCreateLabel, onClick: onCreate, testId: "render-list-create" })) : onCreate !== undefined ? (_jsx(Button, { variant: "primary", icon: "plus", onClick: onCreate, testId: "render-list-create", className: "px-3.5", children: effectiveCreateLabel })) : undefined;
-    // Every primary toolbar action takes the page-header slot, left of the create
-    // button (which stays the rightmost primary action): labelled on desktop, so
-    // projection lists look like entity lists. On phones an icon button, or, next to
-    // the create button, an entry in the header's overflow menu: the header has no
-    // room for a labelled action beside it.
-    const promotedToolbarActions = PageHeader !== undefined && pageHeaderSlotAvailable
-        ? (toolbarActions?.filter(isHeaderPromotableToolbarAction) ?? [])
-        : [];
-    const promotedInOverflowMenu = pageHeaderCompact && createInPageHeader && promotedToolbarActions.length > 0;
-    const promotedMenuItems = promotedInOverflowMenu
-        ? promotedToolbarActions.map((a) => ({
-            id: a.id,
-            label: a.label,
-            ...(a.icon !== undefined && { icon: a.icon }),
-            ...(menuActionBusyId !== null && { disabled: true }),
-            testId: `render-list-toolbar-action-${a.id}`,
-            onSelect: () => {
-                setMenuActionBusyId(a.id);
-                setMenuActionError(null);
-                void (async () => {
-                    try {
-                        await a.onTrigger();
-                    }
-                    catch (e) {
-                        setMenuActionError(e instanceof Error ? e.message : String(e));
-                    }
-                    finally {
-                        setMenuActionBusyId(null);
-                    }
-                })();
-            },
-        }))
-        : [];
-    const headerActions = promotedToolbarActions.length > 0 && !promotedInOverflowMenu ? (_jsxs(_Fragment, { children: [promotedToolbarActions.map((a) => (_jsx(ToolbarActionView, { action: pageHeaderCompact ? { ...a, icon: a.icon ?? "plus" } : a, iconOnly: pageHeaderCompact, Button: Button, Dialog: Dialog, Banner: Banner }, a.id))), createInPageHeader && createButton] })) : createInPageHeader ? (createButton) : undefined;
-    const toolbarActionsInToolbar = toolbarActions?.filter((a) => !promotedToolbarActions.includes(a)) ?? [];
-    const hasToolbarActionsInToolbar = toolbarActionsInToolbar.length > 0;
-    const toolbarEnd = hasHeaderSlot ||
-        hasToolbarActionsInToolbar ||
-        (onCreate !== undefined && !createInPageHeader) ? (_jsxs(_Fragment, { children: [hasHeaderSlot && _jsx(ListHeaderSlotMount, { screen: screen }), hasToolbarActionsInToolbar &&
-                toolbarActionsInToolbar.map((a) => (_jsx(ToolbarActionView, { action: a, iconOnly: toolbarIconOnly, Button: Button, Dialog: Dialog, Banner: Banner }, a.id))), !createInPageHeader && createButton] })) : undefined;
-    // Empty state: by default, show a heading, description, and optional CTA
-    // button. The caller can replace it completely through emptyState.
-    // Without onCreate or an override, DataTable uses its default
-    // (`kumiko.list.no-entries`).
-    const defaultFilterActive = defaultFilterActiveProp && onFilterReset !== undefined;
-    const composedEmptyState = emptyState ??
-        (onCreate !== undefined || emptyContent !== undefined || narrowed || defaultFilterActive ? (_jsx(ListEmptyStateBody, { content: emptyContent, narrowed: narrowed, defaultFilterActive: defaultFilterActive, ...(onFilterReset !== undefined && { onShowAll: onFilterReset }), translate: translate, createButton: onCreate !== undefined && !narrowed && !defaultFilterActive && !createInPageHeader ? (_jsx(Button, { variant: "primary", icon: "plus", onClick: onCreate, testId: "render-list-empty-create", children: effectiveCreateLabel })) : undefined })) : undefined);
-    // Title resolution uses the conventional i18n key `screen:<id>.title`.
-    // If the bundle knows the key, use its translated title; otherwise use
-    // screenId so the app developer can see that the translation is missing.
-    const titleKey = `screen:${screen.id}.title`;
-    const resolvedTitle = translate(titleKey);
-    const toolbarTitle = resolvedTitle === titleKey ? screen.id : resolvedTitle;
-    return (_jsxs(_Fragment, { children: [headerActions !== undefined && PageHeader !== undefined && (_jsx(PageHeader, { actions: headerActions, ...(promotedInOverflowMenu && { overflowItems: promotedMenuItems }) })), menuActionError !== null && (_jsx(Banner, { variant: "error", testId: "render-list-toolbar-action-error", children: menuActionError })), referenceColumns.map((rc) => (_jsx(ReferenceLookupBridge, { field: rc.field, refEntity: rc.refEntity, labelField: rc.labelField, featureName: rc.refFeature, onMap: handleLookupMap }, rc.field))), _jsx(DataTable, { columns: enrichedVm.columns, rows: enrichedVm.rows, toolbarTitle: toolbarTitle, ...(onRowClick !== undefined && { onRowClick }), ...(composedEmptyState !== undefined && { emptyState: composedEmptyState }), ...(toolbarStart !== undefined && { toolbarStart }), ...(description !== undefined && { toolbarDescription: description }), ...(toolbarEnd !== undefined && { toolbarEnd }), ...(sort !== undefined && { sort }), ...(onSortChange !== undefined && { onSortChange }), ...(pager !== undefined && { pager }), ...(onReachEnd !== undefined && { onReachEnd }), ...(loadingMore !== undefined && { loadingMore }), ...(hasMore !== undefined && { hasMore }), ...(itemNoun !== undefined && { itemNoun }), ...(rowActions !== undefined && { rowActions }), ...(rowActionMode !== undefined && { rowActionMode }), ...(bulk !== undefined && { bulk }), ...(rowTone !== undefined && { rowTone }), ...(filterFacets !== undefined && { filterFacets }), ...(filterValues !== undefined && { filterValues }), ...(onFilterChange !== undefined && { onFilterChange }), ...(onFilterReset !== undefined && { onFilterReset }), ...(dateRangeFacets !== undefined && { dateRangeFacets }), ...(onDateRangeChange !== undefined && { onDateRangeChange }), ...(chromeless !== undefined && { chromeless }), ...(scrollBody !== undefined && { scrollBody }), ...(screenPadding !== undefined && { screenPadding }), ...(expandedRowIds !== undefined && { expandedRowIds }), ...(onToggleRowExpanded !== undefined && { onToggleRowExpanded }), ...(renderExpandedRow !== undefined && { renderExpandedRow }), ...tableBlockProps, testId: "render-list-table" })] }));
-}
-// Header slot in the list toolbar (toolbarEnd): `screen.slots.header` is
-// a PlatformComponent (`{ react: { __component: "X" } }`) resolved through
-// the same ExtensionSectionsProvider registry as entityEdit sections.
-// entityId is null in the list context because there is no row; the component
-// loads its own data (for example, a cap counter from a usage query). A
-// separate component is required by the Rules of Hooks because
-// useExtensionSectionComponent must not run conditionally in RenderList.
-function ListHeaderSlotMount({ screen, }) {
-    const header = screen.slots?.header;
-    const name = header !== undefined ? extensionSectionName(header) : undefined;
-    const Component = useExtensionSectionComponent(name);
-    // A declared-but-unregistered header slot renders nothing; warn so the author
-    // finds the typo / missing clientFeatures.extensionSectionComponents entry,
-    // mirroring the diagnostic banner in render-edit's ExtensionSectionMount
-    // (the toolbar has no room for a banner, so a dev-warn it is).
-    useEffect(() => {
-        if (name !== undefined && Component === undefined) {
-            rendererWarn(`[kumiko] List header slot component "${name}" on screen "${screen.id}" is not registered in clientFeatures.extensionSectionComponents — the header slot renders nothing.`);
-        }
-    }, [name, Component, screen.id]);
-    if (Component === undefined)
-        return null;
-    // screenId lets a header control drive this list's URL-filter state
-    // (useListUrlState) — e.g. a tag filter narrowing the list to an id-set.
-    return _jsx(Component, { entityName: screen.entity, entityId: null, screenId: screen.id });
-}
-// Bridge component for each reference column. It is mounted once per
-// column, calls useReferenceLookup unconditionally, and publishes the map
-// to the parent through onMap. React manages mounting and unmounting when
-// the schema changes through the key prop in the parent's map loop.
-function ReferenceLookupBridge({ field, refEntity, labelField, featureName, onMap, }) {
-    const lookup = useReferenceLookup(featureName, refEntity, labelField);
-    // Use an effect rather than calling directly so setState runs outside the
-    // render path; otherwise React warns about updating one component while
-    // rendering another.
-    // Do not publish while loading or after a failed lookup: a missing map means
-    // "not resolved", whereas an empty published map means "nothing found".
-    // Only the latter may display "Unknown".
-    const resolved = !lookup.loading && !lookup.failed;
-    useEffect(() => {
-        if (resolved)
-            onMap(field, { map: lookup.map, complete: lookup.complete });
-    }, [field, lookup.map, lookup.complete, resolved, onMap]);
-    return null;
-}
-function isPlainRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-// The server leaves a missing or unreadable target out of `_refs`, and a null
-// entry means the same: both read as unresolved.
-function eagerloadedRef(row, field) {
-    if (!isPlainRecord(row) || !isPlainRecord(row["_refs"]))
-        return undefined;
-    const ref = row["_refs"][field];
-    if (Array.isArray(ref))
-        return ref.filter(isPlainRecord);
-    return isPlainRecord(ref) ? ref : undefined;
+    const split = splitToolbarActions({
+        toolbarActions,
+        pageHeaderAvailable: PageHeader !== undefined,
+        pageHeaderSlotAvailable,
+        pageHeaderCompact,
+        createInPageHeader,
+    });
+    const toolbarModel = {
+        screen,
+        Button,
+        Dialog,
+        Banner,
+        onCreate,
+        createInPageHeader,
+        pageHeaderCompact,
+        effectiveCreateLabel,
+        split,
+    };
+    const createButton = renderCreateButton(toolbarModel);
+    const promotedMenuItems = buildPromotedMenuItems({
+        promotedToolbarActions: split.promotedToolbarActions,
+        promotedInOverflowMenu: split.promotedInOverflowMenu,
+        menuActionBusyId,
+        setMenuActionBusyId,
+        setMenuActionError,
+    });
+    const headerActions = renderHeaderActions(toolbarModel, createButton);
+    const toolbarEnd = renderToolbarEnd(toolbarModel, createButton);
+    const composedEmptyState = composeEmptyState({
+        Button,
+        emptyState,
+        onCreate,
+        emptyContent,
+        narrowed,
+        defaultFilterActive: defaultFilterActiveProp && onFilterReset !== undefined,
+        onFilterReset,
+        translate,
+        createInPageHeader,
+        effectiveCreateLabel,
+    });
+    const toolbarTitle = resolveToolbarTitle(screen, translate);
+    return (_jsxs(_Fragment, { children: [headerActions !== undefined &&
+                PageHeader !== undefined &&
+                renderPageHeader(PageHeader, headerActions, split.promotedInOverflowMenu, promotedMenuItems), menuActionError !== null && renderMenuActionError(Banner, menuActionError), renderReferenceLookupBridges(referenceColumns, handleLookupMap), _jsx(DataTable, { columns: enrichedVm.columns, rows: enrichedVm.rows, toolbarTitle: toolbarTitle, ...tableChromeProps({
+                    onRowClick,
+                    composedEmptyState,
+                    toolbarStart,
+                    description,
+                    toolbarEnd,
+                    itemNoun,
+                }), ...tableSortPagingProps({ sort, onSortChange, pager, onReachEnd, loadingMore, hasMore }), ...tableRowProps({ rowActions, rowActionMode, bulk, rowTone }), ...tableFilterProps({
+                    filterFacets,
+                    filterValues,
+                    onFilterChange,
+                    onFilterReset,
+                    dateRangeFacets,
+                    onDateRangeChange,
+                }), ...tableLayoutProps({
+                    chromeless,
+                    scrollBody,
+                    screenPadding,
+                    expandedRowIds,
+                    onToggleRowExpanded,
+                    renderExpandedRow,
+                }), ...tableBlockProps, testId: "render-list-table" })] }));
 }

package/dist/components/use-reference-input-state.d.ts

@@ -0,0 +1,20 @@
+import type { EntityEditScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { EditFieldViewModel } from "../headless/index.ts";
+export declare function useReferenceInputState(field: EditFieldViewModel, featureName: string, onChange: (value: unknown) => void): {
+    refFeature: string;
+    isMultiple: boolean;
+    options: {
+        value: string;
+        label: string;
+    }[];
+    loading: boolean;
+    createTarget: {
+        screen: EntityEditScreenDefinition;
+        entity: import("@cosmicdrift/kumiko-types/fields").EntityDefinition;
+    } | undefined;
+    createOpen: boolean;
+    setCreateOpen: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    createdWithoutIdWarning: boolean;
+    handleCreated: (newId: string | undefined) => void;
+    handleSearchChange: (q: string) => void;
+};

package/dist/components/use-reference-input-state.js

@@ -0,0 +1,85 @@
+import { useCallback, useMemo, useState } from "react";
+import { useAppFeatures } from "../app/app-features-context.js";
+import { screenAccessAllows } from "../app/screen-access.js";
+import { useUserRoles } from "../context/user-roles-context.js";
+import { rendererError } from "../dev-console.js";
+import { REFERENCE_COMBOBOX_LIMIT } from "../hooks/reference-limits.js";
+import { useQuery } from "../hooks/use-query.js";
+import { referenceOptionSource } from "../hooks/use-reference-lookup.js";
+import { stringArrayOf } from "./render-field-values.js";
+export function useReferenceInputState(field, featureName, onChange) {
+    const refEntity = field.refEntity ?? "";
+    const refFeature = field.refFeature ?? featureName;
+    const isMultiple = field.refMultiple === true;
+    // refFeature may differ from featureName (for example,
+    // items.assignee → users:query:user:list). The default is the same feature,
+    // as provided by the ViewModel (parseRefTarget).
+    // refOptionsQuery replaces that source with an author-supplied handler whose
+    // rows already carry a composed `label`.
+    const { queryQn, labelKey } = referenceOptionSource(field, refFeature, refEntity);
+    // "+ Neu" in the combobox opens the referenced entity's create screen in a
+    // dialog instead of leaving the current form.
+    // refFeature may differ from the currently rendered feature; appFeatures
+    // (createKumikoApp) knows all feature schemas, not only the active screen.
+    // If the feature, screen, or entity is not registered, or allowCreate:false,
+    // onCreate remains undefined and the combobox renders without the footer.
+    const appFeatures = useAppFeatures();
+    const userRoles = useUserRoles();
+    const [createOpen, setCreateOpen] = useState(false);
+    const refTargetSchema = appFeatures.find((f) => f.featureName === refFeature);
+    const refCreateScreen = refTargetSchema?.screens.find((s) => s.type === "entityEdit" &&
+        s.entity === refEntity &&
+        s.allowCreate !== false &&
+        screenAccessAllows(s.access, userRoles));
+    const refEntityDef = refTargetSchema?.entities[refEntity];
+    // When the user types in the combobox, the server filters through the
+    // existing list-payload `search` parameter. The combobox debounces the
+    // keystroke itself (300ms) and calls onSearchChange.
+    // An empty initial state requests the first 50 items in default order.
+    const [searchTerm, setSearchTerm] = useState("");
+    const queryPayload = useMemo(() => searchTerm === ""
+        ? { limit: REFERENCE_COMBOBOX_LIMIT }
+        : { limit: REFERENCE_COMBOBOX_LIMIT, search: searchTerm }, [searchTerm]);
+    const queryResult = useQuery(queryQn, queryPayload);
+    const handleSearchChange = useCallback((q) => setSearchTerm(q), []);
+    const createTarget = !field.readOnly && refCreateScreen !== undefined && refEntityDef !== undefined
+        ? { screen: refCreateScreen, entity: refEntityDef }
+        : undefined;
+    const [createdWithoutIdWarning, setCreatedWithoutIdWarning] = useState(false);
+    const handleCreated = useCallback((newId) => {
+        setCreateOpen(false);
+        // Clear the search filter before refetching — the just-created record
+        // won't match whatever the user had typed pre-create, and would then
+        // be missing from `options` (shown as a raw id instead of a label).
+        setSearchTerm("");
+        queryResult.refetch().catch((err) => {
+            rendererError("render-field: refetch after create failed", err);
+        });
+        // Record was created server-side but the payload carried no id —
+        // can't auto-select it, surface that instead of failing silently.
+        setCreatedWithoutIdWarning(newId === undefined);
+        if (newId !== undefined) {
+            onChange(isMultiple ? [...stringArrayOf(field.value), newId] : newId);
+        }
+    }, [isMultiple, field.value, onChange, queryResult.refetch]);
+    const options = useMemo(() => {
+        const rows = queryResult.data?.rows ?? [];
+        return rows.map((row) => {
+            const idVal = String(row["id"] ?? "");
+            const label = String(row[labelKey] ?? idVal);
+            return { value: idVal, label };
+        });
+    }, [queryResult.data, labelKey]);
+    return {
+        refFeature,
+        isMultiple,
+        options,
+        loading: queryResult.loading,
+        createTarget,
+        createOpen,
+        setCreateOpen,
+        createdWithoutIdWarning,
+        handleCreated,
+        handleSearchChange,
+    };
+}

package/dist/components/use-render-edit-controlled-sync.d.ts

@@ -0,0 +1,3 @@
+import type { FormValues } from "../headless/index.ts";
+import type { RenderEditCore } from "./render-edit-render-model.ts";
+export declare function useRenderEditControlledSync<TValues extends FormValues, TCtx>({ props, state, form, draft, }: RenderEditCore<TValues, TCtx>): void;

package/dist/components/use-render-edit-controlled-sync.js

@@ -0,0 +1,26 @@
+import { useEffect, useRef } from "react";
+import { useUnsavedInputSource } from "../leave-guard.js";
+import { useWizardFormDraftRestore } from "./use-wizard-form-draft.js";
+export function useRenderEditControlledSync({ props, state, form, draft, }) {
+    const { controller, snapshot } = form;
+    const { extensionDirty } = state;
+    const onDirtyChangeRef = useRef(props.onDirtyChange);
+    onDirtyChangeRef.current = props.onDirtyChange;
+    const hasUnsavedInput = snapshot.isDirty || extensionDirty;
+    useEffect(() => {
+        onDirtyChangeRef.current?.(hasUnsavedInput);
+    }, [hasUnsavedInput]);
+    // Draft wizards keep their input server-side, so leaving loses nothing.
+    const persistsDraft = state.isWizard && props.screen.layout.draft === true;
+    useUnsavedInputSource(() => !persistsDraft && (controller.getSnapshot().isDirty || state.extensionDirtyRef.current));
+    useWizardFormDraftRestore({
+        screenId: props.screen.id,
+        isCreateMode: state.isCreateMode,
+        draftEnabled: state.draftEnabled,
+        dispatcher: state.dispatcher,
+        controller,
+        hasNavigatedRef: draft.refs.hasNavigatedRef,
+        setRawStep: state.setRawStep,
+        draftState: state.draftState,
+    });
+}

package/dist/components/use-render-edit-draft-save.d.ts

@@ -0,0 +1,29 @@
+import { type MutableRefObject } from "react";
+import type { FormValues } from "../headless/index.ts";
+import type { ResolvedRenderEditProps } from "./render-edit-render-model.ts";
+import type { RenderEditForm } from "./use-render-edit-form.ts";
+import type { RenderEditState } from "./use-render-edit-state.ts";
+export type RenderEditRefs<TValues extends FormValues> = {
+    readonly onChangeRef: MutableRefObject<ResolvedRenderEditProps<TValues>["onChange"]>;
+    readonly deliveredControlsToRef: MutableRefObject<ResolvedRenderEditProps<TValues>["onControlsReady"]>;
+    readonly onControlsReadyRef: MutableRefObject<ResolvedRenderEditProps<TValues>["onControlsReady"]>;
+    readonly hasNavigatedRef: MutableRefObject<boolean>;
+    readonly submittedRef: MutableRefObject<boolean>;
+    readonly isSubmittingRef: MutableRefObject<boolean>;
+    readonly scopeFieldNamesRef: MutableRefObject<readonly string[] | undefined>;
+    readonly saveDraftRef: MutableRefObject<(stepIndex: number) => void>;
+    readonly handleSubmitRef: MutableRefObject<(options?: {
+        readonly saveNow?: boolean;
+    }) => Promise<void>>;
+    readonly wizardNextRef: MutableRefObject<() => void>;
+    readonly wizardBackRef: MutableRefObject<() => void>;
+    readonly currentStepRef: MutableRefObject<number>;
+    readonly draftSaveTimerRef: MutableRefObject<ReturnType<typeof setTimeout> | null>;
+};
+export type RenderEditDraft<TValues extends FormValues> = {
+    readonly refs: RenderEditRefs<TValues>;
+    readonly scopedValidate: () => boolean;
+    readonly markSaved: (fields?: readonly string[]) => void;
+    readonly patchAndScheduleDraftSave: (partial: Partial<TValues>) => void;
+};
+export declare function useRenderEditDraftSave<TValues extends FormValues, TCtx>(props: ResolvedRenderEditProps<TValues, TCtx>, state: RenderEditState, form: RenderEditForm<TValues>): RenderEditDraft<TValues>;