@cosmicdrift/kumiko-renderer 0.387.0 → 0.389.0

package/dist/components/list-group-page-bridges.js

@@ -0,0 +1,31 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+// One invisible bridge per requested group page: the number of open groups and
+// loaded pages varies, so useQuery can't be called in a loop. The pool caps
+// group page requests at four in flight.
+import { useEffect, useRef } from "react";
+import { useQuery } from "../hooks/use-query.js";
+const GROUP_PAGE_CONCURRENCY = 4;
+function GroupPageBridge({ pageKey, queryType, payload, onResult, refreshNonce, }) {
+    const result = useQuery(queryType, payload, {
+        live: true,
+        concurrency: GROUP_PAGE_CONCURRENCY,
+    });
+    const { data, loading, refetch } = result;
+    useEffect(() => {
+        if (data === null)
+            return;
+        onResult(pageKey, { rows: data.rows, nextCursor: data.nextCursor ?? null, loading });
+    }, [data, loading, pageKey, onResult]);
+    const seenNonce = useRef(refreshNonce);
+    useEffect(() => {
+        // skip: the mount fetch already covers the nonce the bridge started with
+        if (seenNonce.current === refreshNonce)
+            return;
+        seenNonce.current = refreshNonce;
+        void refetch();
+    }, [refreshNonce, refetch]);
+    return null;
+}
+export function ListGroupPageBridges({ queryType, requests, onResult, refreshNonce, }) {
+    return (_jsx(_Fragment, { children: requests.map((request) => (_jsx(GroupPageBridge, { pageKey: request.pageKey, queryType: queryType, payload: request.payload, onResult: onResult, refreshNonce: refreshNonce }, request.pageKey))) }));
+}

package/dist/components/list-state-store.d.ts

@@ -0,0 +1,16 @@
+import { type ReactNode } from "react";
+import type { StoredListState } from "../hooks/list-state-schema.ts";
+export type ListStateStore = {
+    read(key: string): StoredListState | undefined;
+    write(key: string, state: StoredListState): void;
+    remove(key: string): void;
+    clear(): void;
+};
+export declare function createMemoryListStateStore(): ListStateStore;
+export declare function ListStateStoreProvider({ store, children, }: {
+    readonly store: ListStateStore;
+    readonly children: ReactNode;
+}): ReactNode;
+export declare function useListStateStore(): ListStateStore;
+/** The shared in-memory default; the web boot clears it when the identity changes. */
+export declare function getDefaultMemoryListStateStore(): ListStateStore;

package/dist/components/list-state-store.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+export function createMemoryListStateStore() {
+    const entries = new Map();
+    return {
+        read: (key) => entries.get(key),
+        write: (key, state) => {
+            entries.set(key, state);
+        },
+        remove: (key) => {
+            entries.delete(key);
+        },
+        clear: () => {
+            entries.clear();
+        },
+    };
+}
+// Module-wide so remembered list state survives route changes in the SPA
+// without any provider mounted.
+const defaultMemoryStore = createMemoryListStateStore();
+const ListStateStoreContext = createContext(defaultMemoryStore);
+export function ListStateStoreProvider({ store, children, }) {
+    return _jsx(ListStateStoreContext.Provider, { value: store, children: children });
+}
+export function useListStateStore() {
+    return useContext(ListStateStoreContext);
+}
+/** The shared in-memory default; the web boot clears it when the identity changes. */
+export function getDefaultMemoryListStateStore() {
+    return defaultMemoryStore;
+}

package/dist/components/related-list-section.js

@@ -1,9 +1,10 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { evalFieldCondition, normalizeListColumn, parseRefTarget, relatedListGroupHeaderLabel, relatedListGroupKey, } from "@cosmicdrift/kumiko-framework/ui-types";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { evalFieldCondition, normalizeListColumn, parseRefTarget, } from "@cosmicdrift/kumiko-framework/ui-types";
+import { useCallback, useMemo, useState } from "react";
 import { useAppFeatures } from "../app/app-features-context.js";
 import { useClientActionRuntime } from "../app/client-actions.js";
 import { ErrorReference } from "../app/error-reference.js";
+import { useListBulk } from "../app/list-bulk-actions.js";
 import { buildFilterFacets, buildFilterPayload, mergeReferenceFacetOptions, resolveProjectionFacetSpecs, } from "../app/list-facets.js";
 import { useNav } from "../app/nav.js";
 import { SYNTHESIZED_FIELD_PII_REASON } from "../app/projection-list-shim.js";
@@ -15,15 +16,29 @@ import { dispatcherErrorText } from "../app/write-failed-error.js";
 import { useOptionalDispatcher } from "../context/dispatcher-context.js";
 import { useUserRoles } from "../context/user-roles-context.js";
 import { rendererWarn } from "../dev-console.js";
-import { useQuery } from "../hooks/use-query.js";
+import { useRelatedListRows } from "../hooks/use-related-list-rows.js";
+import { useRelatedListState } from "../hooks/use-related-list-state.js";
 import { useOptionalLocale, useTranslation } from "../i18n.js";
 import { PageHeaderSlotAvailableProvider } from "../page-header-slot.js";
-import { usePrimitives, } from "../primitives.js";
-import { sortByAccessor } from "../sort-by-accessor.js";
+import { usePrimitives } from "../primitives.js";
+import { ListGroupPageBridges } from "./list-group-page-bridges.js";
 import { RenderEditActionButton } from "./render-edit-action-button.js";
 import { RenderList } from "./render-list.js";
+// Keyed on the type, not on key presence: most factories omit `sortable`
+// from the definition, so `"sortable" in field` would drop the column flag.
+const NON_SORTABLE_FIELD_TYPES = new Set([
+    "longText",
+    "multiSelect",
+    "embedded",
+    "jsonb",
+    "tz",
+    "file",
+    "image",
+    "files",
+    "images",
+]);
 function isSortableCapable(field) {
-    return "sortable" in field;
+    return !NON_SORTABLE_FIELD_TYPES.has(field.type);
 }
 const RELATED_LIST_PSEUDO_ENTITY = "__related-list__";
 // Minimal EntityDefinition from the section's own columns — same shape as
@@ -72,36 +87,6 @@ function valueTypeField(valueType, sortable) {
 function warnRelatedListEmptyStateDrawerDropped(actionId) {
     rendererWarn(`[kumiko] relatedList emptyState.action "${actionId}" is kind: "drawer" but no onOpenDrawer was supplied — dropped.`);
 }
-function buildRowGrouping(groupBy, translate, locale) {
-    return {
-        keyOf: (row) => relatedListGroupKey(row.values[groupBy.field]),
-        startsCollapsed: (key) => groupBy.collapsedWhen !== undefined && key === relatedListGroupKey(groupBy.collapsedWhen),
-        headerLabel: (key, rows) => {
-            const labelKey = relatedListGroupHeaderLabel(groupBy, key);
-            if (labelKey === undefined)
-                return undefined;
-            const dates = groupBy.dateField === undefined
-                ? []
-                : rows
-                    .map((row) => String(row.values[groupBy.dateField ?? ""] ?? ""))
-                    .filter((value) => value !== "")
-                    .sort();
-            const latest = dates[dates.length - 1];
-            return translate(labelKey, {
-                count: rows.length,
-                value: key,
-                lastDate: latest === undefined
-                    ? ""
-                    : new Date(latest).toLocaleDateString(locale, {
-                        year: "numeric",
-                        month: "2-digit",
-                        day: "2-digit",
-                        timeZone: "UTC",
-                    }),
-            });
-        },
-    };
-}
 function buildRowTone(rule) {
     if (rule === undefined)
         return undefined;
@@ -113,9 +98,6 @@ export function RelatedListSection({ section, parentId, record, featureName, tra
     const t = useTranslation();
     const effectiveTranslate = translate ?? t;
     const locale = useOptionalLocale();
-    const rowGrouping = useMemo(() => section.groupBy === undefined
-        ? undefined
-        : buildRowGrouping(section.groupBy, effectiveTranslate, locale ?? "en"), [section.groupBy, effectiveTranslate, locale]);
     const rowTone = useMemo(() => buildRowTone(section.rowTone), [section.rowTone]);
     const nav = useNav();
     const host = useReturnHost();
@@ -152,8 +134,7 @@ export function RelatedListSection({ section, parentId, record, featureName, tra
     // Local state, not URL state: a section `id` is optional, so there is no
     // stable URL key to namespace against — the section's sort is local for the
     // same reason. Consequence: search/filters reset on reload.
-    const [search, setSearch] = useState("");
-    const [filters, setFilters] = useState({});
+    const { search, filters, sort, setSearch, setFilters, setSort, listTable, groupField } = useRelatedListState(section, nav.route?.screenId);
     const facetSpecs = useMemo(() => resolveProjectionFacetSpecs(section.facets, effectiveTranslate, featureName), [section.facets, effectiveTranslate, featureName]);
     const [referenceFacetOptions, setReferenceFacetOptions] = useState({});
     const handleFacetOptions = useCallback((field, options) => setReferenceFacetOptions((prev) => prev[field] === options ? prev : { ...prev, [field]: options }), []);
@@ -185,39 +166,19 @@ export function RelatedListSection({ section, parentId, record, featureName, tra
         search,
         filterPayload,
     ]);
-    const rowsQuery = useQuery(section.query, payload);
-    const ownRefetch = rowsQuery.refetch;
-    const lastRefreshTokenRef = useRef(refreshToken);
-    useEffect(() => {
-        if (lastRefreshTokenRef.current === refreshToken)
-            return;
-        lastRefreshTokenRef.current = refreshToken;
-        void ownRefetch();
-    }, [refreshToken, ownRefetch]);
-    const refetchSelfAndHost = useCallback(async () => {
-        await ownRefetch();
-        await onAfterWrite?.();
-    }, [ownRefetch, onAfterWrite]);
-    const onFilterChange = useCallback((field, values) => setFilters((prev) => ({ ...prev, [field]: values })), []);
-    const onFilterReset = useCallback(() => setFilters({}), []);
-    // Sorted client-side over the already-loaded rows only. The section has no
-    // pager (one-shot fetch); when that fetch is truncated (`nextCursor` set) the
-    // truncation banner below tells the user the sorted set is partial.
-    const [sort, setSort] = useState(section.defaultSort ?? null);
-    const sortAccessors = useMemo(() => {
-        const accessors = {};
-        for (const col of section.columns) {
-            const field = normalizeListColumn(col).field;
-            accessors[field] = (row) => {
-                const value = row[field];
-                if (value === null || value === undefined)
-                    return null;
-                return typeof value === "number" ? value : String(value);
-            };
-        }
-        return accessors;
-    }, [section.columns]);
-    const sortedRows = useMemo(() => sortByAccessor(rowsQuery.data?.rows ?? [], sort, sortAccessors, locale), [rowsQuery.data, sort, sortAccessors, locale]);
+    const listRows = useRelatedListRows({
+        section,
+        payload,
+        groupField,
+        sort,
+        locale,
+        refreshToken,
+        onAfterWrite,
+        translate: effectiveTranslate,
+    });
+    const { refetchSelfAndHost, aggregates } = listRows;
+    const onFilterChange = useCallback((field, values) => setFilters((prev) => ({ ...prev, [field]: values })), [setFilters]);
+    const onFilterReset = useCallback(() => setFilters({}), [setFilters]);
     const rowClick = section.rowClick;
     // A row-body click target comes from EITHER the legacy `rowClick` field OR
     // a `rowActions` entry marked rowClick:true — the boot-validator rejects
@@ -265,6 +226,13 @@ export function RelatedListSection({ section, parentId, record, featureName, tra
         defaultEditRowAction,
         host,
     ]);
+    const bulk = useListBulk({
+        bulkActions: section.bulkActions,
+        rowActions: section.rowActions,
+        translate: effectiveTranslate,
+        dispatcher,
+        reload: refetchSelfAndHost,
+    });
     // Toolbar actions (e.g. "+ Create" above the tab table) — same schema
     // and dispatch semantics as entityList/projectionList.
     const toolbarActionButtons = useMemo(() => buildProjectionToolbarActions({
@@ -335,20 +303,11 @@ export function RelatedListSection({ section, parentId, record, featureName, tra
         refetchSelfAndHost,
     ]);
     const emptyStateContent = section.emptyState !== undefined ? (_jsxs(_Fragment, { children: [_jsx(Text, { children: section.emptyState.title }), section.emptyState.description !== undefined && (_jsx(Text, { variant: "small", children: section.emptyState.description })), emptyStateActionButton !== undefined && (_jsx(RenderEditActionButton, { action: emptyStateActionButton, Button: Button, Dialog: Dialog, onError: setEmptyStateActionError }))] })) : undefined;
-    // A truncated fetch means `sortedRows` is a sort of a partial set, not of
-    // the full related-row set — the client-side sort above (or even plain
-    // unsorted display) would silently claim "these are the top N" when they
-    // are really just "the first N in the server's own order".
-    // `nextCursor` is exactly how the paged envelope marks that: non-null means
-    // more rows exist server-side beyond what was fetched.
-    // A handler that omits `nextCursor` (or reports a `total` the fetched rows
-    // already cover) has no further rows — only a real cursor marks truncation.
-    const truncated = rowsQuery.data !== null &&
-        typeof rowsQuery.data.nextCursor === "string" &&
-        (rowsQuery.data.total === undefined || rowsQuery.data.total > rowsQuery.data.rows.length);
-    const content = rowsQuery.loading && rowsQuery.data === null ? (_jsx(Banner, { padded: true, variant: "loading", testId: "related-list-loading", children: t("kumiko.widget.loading") })) : rowsQuery.error ? (_jsx(Banner, { padded: true, variant: "error", testId: "related-list-error", children: dispatcherErrorText(rowsQuery.error, effectiveTranslate) })) : (_jsxs(_Fragment, { children: [truncated && (_jsx(Banner, { variant: "info", testId: "related-list-truncated", children: effectiveTranslate("kumiko.list.related-list-truncated", {
-                    count: sortedRows.length,
-                }) })), emptyStateActionError !== null && (_jsxs(Banner, { variant: "error", testId: "related-list-empty-state-action-error", children: [emptyStateActionError.message, _jsx(ErrorReference, { requestId: emptyStateActionError.requestId })] })), _jsx(PageHeaderSlotAvailableProvider, { value: false, children: _jsx(RenderList, { screen: listScreen, entity: entity, rows: sortedRows, featureName: listFeatureName ?? featureName, translate: effectiveTranslate, ...(section.description !== undefined && { description: section.description }), ...(section.itemNoun !== undefined && { itemNounKey: section.itemNoun }), sort: sort, onSortChange: setSort, ...(section.searchable === true && {
+    // Without a cursor-driven pager the client-side sort covers only the fetched
+    // rows; the banner keeps it from claiming "these are the top N".
+    const content = listRows.firstLoad ? (_jsx(Banner, { padded: true, variant: "loading", testId: "related-list-loading", children: t("kumiko.widget.loading") })) : listRows.error ? (_jsx(Banner, { padded: true, variant: "error", testId: "related-list-error", children: dispatcherErrorText(listRows.error, effectiveTranslate) })) : (_jsxs(_Fragment, { children: [listRows.truncated && (_jsx(Banner, { variant: "info", testId: "related-list-truncated", children: effectiveTranslate("kumiko.list.related-list-truncated", {
+                    count: listRows.rows.length,
+                }) })), emptyStateActionError !== null && (_jsxs(Banner, { variant: "error", testId: "related-list-empty-state-action-error", children: [emptyStateActionError.message, _jsx(ErrorReference, { requestId: emptyStateActionError.requestId })] })), _jsx(ListGroupPageBridges, { ...aggregates.groupPages }), _jsx(PageHeaderSlotAvailableProvider, { value: false, children: _jsx(RenderList, { screen: listScreen, entity: entity, rows: listRows.rows, featureName: listFeatureName ?? featureName, translate: effectiveTranslate, ...(section.description !== undefined && { description: section.description }), ...(section.itemNoun !== undefined && { itemNounKey: section.itemNoun }), sort: sort, onSortChange: setSort, ...(section.searchable === true && {
                         searchable: true,
                         searchValue: search,
                         onSearchChange: setSearch,
@@ -357,7 +316,7 @@ export function RelatedListSection({ section, parentId, record, featureName, tra
                         filterValues: filters,
                         onFilterChange,
                         onFilterReset,
-                    }), ...(onRowClick !== undefined && { onRowClick }), ...(rowActions !== undefined && { rowActions }), ...(section.rowActionMode !== undefined && { rowActionMode: section.rowActionMode }), ...(rowGrouping !== undefined && { rowGrouping }), ...(rowTone !== undefined && { rowTone }), ...(toolbarActionButtons !== undefined && { toolbarActions: toolbarActionButtons }), ...(emptyStateContent !== undefined && { emptyState: emptyStateContent }), screenPadding: false, ...(hideTitle === true && { scrollBody: true, chromeless: true }), ...(embedded === true && { chromeless: true }) }) })] }));
+                    }), ...(onRowClick !== undefined && { onRowClick }), ...(rowActions !== undefined && { rowActions }), ...(section.rowActionMode !== undefined && { rowActionMode: section.rowActionMode }), ...(bulk !== undefined && { bulk }), ...(rowTone !== undefined && { rowTone }), ...(toolbarActionButtons !== undefined && { toolbarActions: toolbarActionButtons }), ...(emptyStateContent !== undefined && { emptyState: emptyStateContent }), ...listTable, ...(aggregates.serverGroups !== undefined && { serverGroups: aggregates.serverGroups }), ...(aggregates.totals !== undefined && { totals: aggregates.totals }), ...(aggregates.notice !== undefined && { notice: aggregates.notice }), screenPadding: false, ...(hideTitle === true && { scrollBody: true, chromeless: true }), ...(embedded === true && { chromeless: true }) }) })] }));
     // hideTitle (tabs mode) → the caller (render-edit.tsx) already wraps this
     // component's own return value in the same Card frame every other tab
     // kind gets — no card here, or the two would nest. `scrollBody` caps the
@@ -369,7 +328,9 @@ export function RelatedListSection({ section, parentId, record, featureName, tra
     // and aren't confined to a tab panel.
     const bridges = _jsx(ReferenceFacetBridges, { specs: facetSpecs, onOptions: handleFacetOptions });
     if (embedded === true) {
-        const countSuffix = rowsQuery.data !== null ? ` · ${sortedRows.length}` : "";
+        const countSuffix = listRows.hasData
+            ? ` · ${aggregates.serverGroups?.totalCount ?? listRows.rows.length}`
+            : "";
         return (_jsxs(_Fragment, { children: [bridges, _jsx(Card, { options: { framed: false, padded: false }, 
                     // Trim the default header inset: the host row already pads the area.
                     className: "[&>div:first-child]:px-0 [&>div:first-child]:pt-1 [&>div:first-child]:pb-2", slots: {

package/dist/components/render-edit-action-button.d.ts

@@ -10,15 +10,13 @@ export declare function RenderEditActionConfirmDialog({ action, open, onOpenChan
     readonly onConfirm: () => void | Promise<void>;
     readonly Dialog: ReturnType<typeof usePrimitives>["Dialog"];
 }): ReactNode;
-export declare function RenderEditActionButton({ action, iconOnly, hideIcon, compactLabel, Button, Dialog, onError, }: {
+export declare function RenderEditActionButton({ action, iconOnly, hideIcon, Button, Dialog, onError, }: {
     readonly action: RenderEditAction;
     /** Group-level collapse (see `shouldRenderActionsIconOnly`) — only takes
      *  effect when this action actually resolved an icon. */
     readonly iconOnly?: boolean;
     /** Record-header actions are text-only; the icon still shows when collapsed to icon-only. */
     readonly hideIcon?: boolean;
-    /** Short labelled button for a phone header, where a bare icon would hide what the action does. */
-    readonly compactLabel?: boolean;
     readonly Button: ReturnType<typeof usePrimitives>["Button"];
     readonly Dialog: ReturnType<typeof usePrimitives>["Dialog"];
     readonly onError: (notice: ErrorNotice | null) => void;

package/dist/components/render-edit-action-button.js

@@ -15,7 +15,7 @@ export function RenderEditActionConfirmDialog({ action, open, onOpenChange, onCo
 // render-list.tsx's ToolbarActionView (each RenderEditAction is
 // independently bound by the caller, there is no shared trigger pipeline
 // to hook into like the built-in onDelete/onSubmit paths have).
-export function RenderEditActionButton({ action, iconOnly = false, hideIcon = false, compactLabel = false, Button, Dialog, onError, }) {
+export function RenderEditActionButton({ action, iconOnly = false, hideIcon = false, Button, Dialog, onError, }) {
     const [busy, setBusy] = useState(false);
     const [confirmOpen, setConfirmOpen] = useState(false);
     const trigger = async () => {
@@ -33,7 +33,7 @@ export function RenderEditActionButton({ action, iconOnly = false, hideIcon = fa
     };
     const variant = action.style ?? "secondary";
     const showIconOnly = iconOnly && action.icon !== undefined;
-    return (_jsxs(_Fragment, { children: [_jsx(Button, { type: "button", variant: variant, loading: busy, ...(action.icon !== undefined && (!hideIcon || showIconOnly) && { icon: action.icon }), ...(compactLabel && !showIconOnly && { size: "sm" }), ...(showIconOnly && {
+    return (_jsxs(_Fragment, { children: [_jsx(Button, { type: "button", variant: variant, loading: busy, ...(action.icon !== undefined && (!hideIcon || showIconOnly) && { icon: action.icon }), ...(showIconOnly && {
                     size: "icon",
                     ariaLabel: action.label,
                     title: action.label,

package/dist/components/render-edit.js

@@ -215,10 +215,13 @@ export function RenderEdit(props) {
     const scopeFieldNamesRef = useRef(scopeFieldNames);
     scopeFieldNamesRef.current = scopeFieldNames;
     const scopedValidate = useCallback(() => controller.validate(scopeFieldNamesRef.current), [controller]);
-    const markSaved = useCallback(() => {
-        controller.rebase();
-        extensionDirtyRef.current = false;
-        setExtensionDirty(false);
+    // The extension dirty flag aggregates every section; each section clears its
+    // own part, so a host-side markSaved must not reset it.
+    const markSaved = useCallback((fields) => {
+        if (fields === undefined)
+            controller.rebase();
+        else
+            controller.rebaseFields(fields);
     }, [controller]);
     // `saveDraft` (defined below) is a fresh closure every render, over that
     // render's `draftKey`/`draftId` — the ref lets the debounce timer below
@@ -1048,7 +1051,7 @@ export function RenderEdit(props) {
                             // Title-less sections would otherwise collide on key/testId, so use the index
                             // as a fallback.
                             const sectionKey = section.title ?? `section-${sectionIndex}`;
-                            const renderFieldGrid = (fields, columns, gridKey) => (_jsx(Grid, { columns: columns, ...(isSettingsList ? { list: true } : usesFieldFlow && { flow: true }), children: fields.map((field) => (_jsx(GridCellForField, { field: disabled ? { ...field, readOnly: true } : field, columns: columns, ...(!isSettingsList && usesFieldFlow && { flow: true }), ...(isSettingsList && {
+                            const renderFieldGrid = (fields, columns, gridKey, columnsDeclared) => (_jsx(Grid, { columns: usesFieldFlow && columnsDeclared !== true ? 1 : columns, ...(isSettingsList ? { list: true } : usesFieldFlow && { flow: true }), children: fields.map((field) => (_jsx(GridCellForField, { field: disabled ? { ...field, readOnly: true } : field, columns: columns, ...(!isSettingsList && usesFieldFlow && { flow: true }), ...(isSettingsList && {
                                         layout: "row",
                                         accent: fieldAccent?.(field.field) === true,
                                     }), issues: snapshot.errors[field.field], onChange: (v) => {
@@ -1075,7 +1078,7 @@ export function RenderEdit(props) {
                             // cannot stand in for the tabs-mode card here.
                             if (hideSectionTitles === true) {
                                 if (section.groups !== undefined) {
-                                    const groupsGrid = (_jsx(Grid, { columns: 1, children: section.groups.map((group, groupIndex) => (_jsx(Card, { slots: { title: group.title }, testId: `section-${sectionKey}-group-${groupIndex}`, children: renderFieldGrid(group.fields, group.columns, `${sectionKey}-group-${groupIndex}-grid`) }, group.title))) }, `${sectionKey}-groups`));
+                                    const groupsGrid = (_jsx(Grid, { columns: 1, children: section.groups.map((group, groupIndex) => (_jsx(Card, { slots: { title: group.title }, testId: `section-${sectionKey}-group-${groupIndex}`, children: renderFieldGrid(group.fields, group.columns, `${sectionKey}-group-${groupIndex}-grid`, group.columnsDeclared) }, group.title))) }, `${sectionKey}-groups`));
                                     // `actions` on a `groups` section has no group of its own to
                                     // sit in and would need an extra title-less Card around the
                                     // group cards (Card-in-Card) — the boot-validator rejects that
@@ -1092,7 +1095,7 @@ export function RenderEdit(props) {
                                             ...(section.description !== undefined && { subtitle: section.description }),
                                             ...(sectionActionsEl !== undefined && { headerActions: sectionActionsEl }),
                                         },
-                                    }), testId: `section-${sectionKey}`, children: renderFieldGrid(section.fields, section.columns, `${sectionKey}-grid`) }, sectionKey));
+                                    }), testId: `section-${sectionKey}`, children: renderFieldGrid(section.fields, section.columns, `${sectionKey}-grid`, section.columnsDeclared) }, sectionKey));
                                 return wrapWizardStep(sectionKey, cardEl);
                             }
                             // Suppress the section header when it would just repeat the form
@@ -1109,7 +1112,7 @@ export function RenderEdit(props) {
                             const sectionSubtitle = section.description ?? (headerFallback ? formSubtitle : undefined);
                             const sectionEl = (_jsxs(Section, { ...(sectionNavItems.some((item) => item.id === formSectionDomId(sectionIndex)) && {
                                     id: formSectionDomId(sectionIndex),
-                                }), ...(sectionTitle !== undefined && { title: sectionTitle }), ...(sectionSubtitle !== undefined && { subtitle: sectionSubtitle }), ...(section.icon !== undefined && { icon: section.icon }), ...(sectionActionsEl !== undefined && { actions: sectionActionsEl }), ...(isSettingsList && { layout: "settings-list" }), testId: `section-${sectionKey}`, children: [showsAllRequiredHint && insideDrawer && sectionIndex === 0 && allRequiredHint, renderFieldGrid(section.fields, section.columns, `${sectionKey}-grid`)] }, sectionKey));
+                                }), ...(sectionTitle !== undefined && { title: sectionTitle }), ...(sectionSubtitle !== undefined && { subtitle: sectionSubtitle }), ...(section.icon !== undefined && { icon: section.icon }), ...(sectionActionsEl !== undefined && { actions: sectionActionsEl }), ...(isSettingsList && { layout: "settings-list" }), testId: `section-${sectionKey}`, children: [showsAllRequiredHint && insideDrawer && sectionIndex === 0 && allRequiredHint, renderFieldGrid(section.fields, section.columns, `${sectionKey}-grid`, section.columnsDeclared)] }, sectionKey));
                             return wrapWizardStep(sectionKey, sectionEl);
                         }), formError !== null && (_jsxs(Banner, { variant: "error", testId: "render-edit-form-error", actions: formError.code === "version_conflict" && onReload !== undefined ? (_jsx(Button, { variant: "secondary", onClick: () => {
                                     onReload();

package/dist/components/render-field.js

@@ -16,7 +16,7 @@ import { fileIdsOf } from "../file-ids-of.js";
 import { applyFormatSpec, currencyDecimals, EMPTY_VALUE_PLACEHOLDER, } from "../headless/index.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 { isCompleteRowPage, referenceOptionSource } from "../hooks/use-reference-lookup.js";
 import { useLocale, useTranslation } from "../i18n.js";
 import { usePrimitives } from "../primitives.js";
 import { AvailabilityOptionsMultiSelect, AvailabilityOptionsSelect, staticSelectOptions, } from "./availability-options-select.js";
@@ -285,6 +285,7 @@ function inputId(field) {
 function FieldRendererOutput({ field, renderer, row, appLocale, }) {
     const { Text, JsonView, FileValueList } = usePrimitives();
     const t = useTranslation();
+    const valueTestId = `field-value-${field.field}`;
     const componentName = !isFormatSpec(renderer) && typeof renderer === "object" && renderer !== null
         ? extensionSectionName(renderer)
         : undefined;
@@ -294,20 +295,20 @@ function FieldRendererOutput({ field, renderer, row, appLocale, }) {
         // itself) — applyFormatSpec's already-indented string is only the
         // fallback for primitives-providers without JsonView.
         if (renderer.format === "json" && JsonView !== undefined) {
-            return (_jsx(JsonView, { value: field.value, indent: renderer.indent, testId: `field-value-${field.field}` }));
+            return _jsx(JsonView, { value: field.value, indent: renderer.indent, testId: valueTestId });
         }
         if (renderer.format === "file" && FileValueList !== undefined) {
             const fileIds = fileIdsOf(field.value);
             if (fileIds.length === 0)
-                return _jsx(Text, { testId: `field-value-${field.field}`, children: EMPTY_VALUE_PLACEHOLDER });
-            return _jsx(FileValueList, { fileIds: fileIds, testId: `field-value-${field.field}` });
+                return _jsx(Text, { testId: valueTestId, children: EMPTY_VALUE_PLACEHOLDER });
+            return (_jsx(FileValueList, { fileIds: fileIds, previewOpenByDefault: renderer.previewOpenByDefault === true, testId: valueTestId }));
         }
         // App locale as default when the FormatSpec declares none of its own —
         // otherwise locale-sensitive formats (timestamp/date/number/decimal/
         // bigInt/unit) fell back to Intl's runtime default instead of the app
         // language chosen via LocaleProvider. Prefer renderer.locale
         // when set; coalesce undefined (spread override) back to appLocale.
-        return (_jsx(Text, { testId: `field-value-${field.field}`, children: applyFormatSpec({
+        return (_jsx(Text, { testId: valueTestId, children: applyFormatSpec({
                 ...renderer,
                 locale: stringPropertyOf(renderer, "locale") ?? appLocale,
             }, field.value, t) }));
@@ -318,7 +319,7 @@ function FieldRendererOutput({ field, renderer, row, appLocale, }) {
         }
         rendererWarn(`[kumiko] fieldRenderer "${componentName}" not registered`);
     }
-    return _jsx(Text, { testId: `field-value-${field.field}`, children: stringValue(field.value) });
+    return _jsx(Text, { testId: valueTestId, children: stringValue(field.value) });
 }
 // Read-only text for `type: "reference"` — resolves the referenced row's
 // label via the same lookup query as ReferenceInput's combobox, but shows
@@ -354,7 +355,10 @@ function ReadOnlyReferenceValue({ field, featureName, }) {
         const row = rows.find((r) => String(r["id"] ?? "") === id);
         if (row === undefined) {
             const unknownKey = UNRESOLVED_REFERENCE_LABEL_KEYS[`${refFeature}:${refEntity}`];
-            const label = unknownKey !== undefined && !queryResult.loading && queryResult.error === null
+            const label = unknownKey !== undefined &&
+                !queryResult.loading &&
+                queryResult.error === null &&
+                isCompleteRowPage(queryResult.data)
                 ? t(unknownKey)
                 : id;
             return { id, label, link: undefined };

package/dist/components/render-list-toolbar-action.d.ts

@@ -0,0 +1,27 @@
+import type { IconKey } from "@cosmicdrift/kumiko-framework/ui-types";
+import { type ReactNode } from "react";
+import type { usePrimitives } from "../primitives.tsx";
+export type ToolbarActionButton = {
+    readonly id: string;
+    readonly label: string;
+    readonly style?: "primary" | "secondary" | "danger";
+    readonly confirm?: string;
+    readonly confirmLabel?: string;
+    /** Overrides the default "danger implies a confirm dialog" rule. Schema-driven
+     *  navigate/drawer actions set it to false: the colour marks the action as
+     *  destructive, but the target form is the confirmation. */
+    readonly confirmRequired?: boolean;
+    readonly onTrigger: () => Promise<void> | void;
+    /** Id-derived default icon (ACTION_ICON_BY_ID in kumiko-screen.tsx) —
+     *  ToolbarAction has no author-declared icon field, unlike RowAction. */
+    readonly icon?: IconKey;
+};
+export declare function ToolbarActionView({ action, iconOnly, Button, Dialog, Banner, }: {
+    readonly action: ToolbarActionButton;
+    /** Group-level collapse (see `shouldRenderActionsIconOnly`) — only takes
+     *  effect when this action actually resolved an icon. */
+    readonly iconOnly?: boolean;
+    readonly Button: ReturnType<typeof usePrimitives>["Button"];
+    readonly Dialog: ReturnType<typeof usePrimitives>["Dialog"];
+    readonly Banner: ReturnType<typeof usePrimitives>["Banner"];
+}): ReactNode;

package/dist/components/render-list-toolbar-action.js

@@ -0,0 +1,40 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { needsActionConfirm } from "./render-edit-action-button.js";
+// ToolbarActionView renders one button per toolbar action, with a confirm
+// dialog when required. It follows the inline RowAction pattern but has no
+// row context. The busy state covers async onTrigger; the dialog opens before
+// the trigger when confirmation is required for confirm/danger actions.
+export function ToolbarActionView({ action, iconOnly = false, Button, Dialog, Banner, }) {
+    const [busy, setBusy] = useState(false);
+    const [confirmOpen, setConfirmOpen] = useState(false);
+    // Toolbar actions do not have access to the toast primitive, unlike
+    // rowActions routed through the DataTable primitive, so an inline error
+    // banner is used to surface failures. Without it, a swallowed failure result
+    // would look to the user as though nothing happened.
+    const [errorText, setErrorText] = useState(null);
+    const trigger = async () => {
+        setBusy(true);
+        setErrorText(null);
+        try {
+            await action.onTrigger();
+        }
+        catch (e) {
+            setErrorText(e instanceof Error ? e.message : String(e));
+        }
+        finally {
+            setBusy(false);
+        }
+    };
+    const variant = action.style ?? "secondary";
+    const needsConfirm = needsActionConfirm(action);
+    const showIconOnly = iconOnly && action.icon !== undefined;
+    return (_jsxs(_Fragment, { children: [_jsx(Button, { variant: variant, loading: busy, ...(action.icon !== undefined && { icon: action.icon }), size: showIconOnly ? "icon" : "md", ...(showIconOnly && { ariaLabel: action.label, title: action.label }), onClick: () => {
+                    if (needsConfirm) {
+                        setConfirmOpen(true);
+                    }
+                    else {
+                        void trigger();
+                    }
+                }, testId: `render-list-toolbar-action-${action.id}`, children: showIconOnly ? null : action.label }), _jsx(Dialog, { open: confirmOpen, onOpenChange: setConfirmOpen, title: action.label, ...(action.confirm !== undefined && { description: action.confirm }), confirmLabel: action.confirmLabel ?? action.label, ...(action.style === "danger" && { variant: "danger" }), onConfirm: trigger, testId: `render-list-toolbar-action-${action.id}-dialog` }), errorText !== null && (_jsx(Banner, { variant: "error", testId: `render-list-toolbar-action-${action.id}-error`, children: errorText }))] }));
+}

package/dist/components/render-list.d.ts

@@ -1,9 +1,11 @@
-import { type EntityDefinition, type EntityListScreenDefinition, type IconKey } from "@cosmicdrift/kumiko-framework/ui-types";
+import { type EntityDefinition, type EntityListScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
 import { type ReactNode } from "react";
 import type { ListRowViewModel, Translate } from "../headless/index.ts";
 import type { ListSort } from "../hooks/use-list-url-state.ts";
-import { type DataTableDateRangeFacet, type DataTableFacet, type DataTableProps, type DataTableRowAction, type DataTableRowActionMode, type DataTableRowGrouping } from "../primitives.tsx";
+import { type DataTableDateRangeFacet, type DataTableFacet, type DataTableProps, type DataTableRowAction, type DataTableRowActionMode, type DataTableTableBlockProps } from "../primitives.tsx";
 import { type ListEmptyStateContent } from "./list-empty-state.tsx";
+import { type ToolbarActionButton } from "./render-list-toolbar-action.tsx";
+export type { ToolbarActionButton };
 export type RenderListProps = {
     readonly screen: EntityListScreenDefinition;
     readonly entity: Pick<EntityDefinition, "fields" | "derivedFields">;
@@ -67,12 +69,11 @@ export type RenderListProps = {
      *  EntityListScreenDefinition.rowActions: handler-QN becomes a dispatcher
      *  call, and i18n keys become translated strings. */
     readonly rowActions?: readonly DataTableRowAction[];
-    /** How the row-action column renders (see `DataTableProps.rowActionMode`).
-     *  KumikoScreen derives it from the actions themselves; without it the
-     *  DataTable falls back to its adaptive default. */
+    /** How the row-action column renders (see `DataTableProps.rowActionMode`). KumikoScreen
+     *  derives it from the actions; without it the DataTable uses its adaptive default. */
     readonly rowActionMode?: DataTableRowActionMode;
-    /** Forwarded to `DataTableProps.rowGrouping` / `rowTone`. */
-    readonly rowGrouping?: DataTableRowGrouping;
+    /** Forwarded to `DataTableProps.bulk` / `rowTone`. */
+    readonly bulk?: DataTableProps["bulk"];
     readonly rowTone?: DataTableProps["rowTone"];
     /** Toolbar actions in the list header in resolved form. KumikoScreen
      *  builds them from EntityListScreenDefinition.toolbarActions:
@@ -93,13 +94,11 @@ export type RenderListProps = {
     readonly dateRangeFacets?: readonly DataTableDateRangeFacet[];
     /** One bound changed (set URL state + refetch). */
     readonly onDateRangeChange?: (field: string, bound: "from" | "to", value: string) => void;
-    /** Forwarded to `DataTableProps.chromeless` — drops the table's own card
-     *  frame for a host that already provides one (relatedList in a tabs-mode
-     *  section). Default false. */
+    /** Forwarded to `DataTableProps.chromeless` — drops the table's own card frame for a
+     *  host that already provides one (relatedList in a tabs-mode section). Default false. */
     readonly chromeless?: boolean;
-    /** Forwarded to `DataTableProps.scrollBody` — bounds the table height and
-     *  scrolls rows internally instead of growing the page (relatedList in a
-     *  tabs-mode section). Default false. */
+    /** Forwarded to `DataTableProps.scrollBody` — bounds the table height and scrolls rows
+     *  internally instead of growing the page (relatedList in a tabs-mode section). Default false. */
     readonly scrollBody?: boolean;
     /** Forwarded to `DataTableProps.screenPadding` — `true`: the table carries
      *  the shared screen padding because it is the screen body (entityList/
@@ -112,20 +111,5 @@ export type RenderListProps = {
     readonly expandedRowIds?: ReadonlySet<string>;
     readonly onToggleRowExpanded?: (rowId: string) => void;
     readonly renderExpandedRow?: (row: ListRowViewModel) => ReactNode;
-};
-export type ToolbarActionButton = {
-    readonly id: string;
-    readonly label: string;
-    readonly style?: "primary" | "secondary" | "danger";
-    readonly confirm?: string;
-    readonly confirmLabel?: string;
-    /** Overrides the default "danger implies a confirm dialog" rule. Schema-driven
-     *  navigate/drawer actions set it to false: the colour marks the action as
-     *  destructive, but the target form is the confirmation. */
-    readonly confirmRequired?: boolean;
-    readonly onTrigger: () => Promise<void> | void;
-    /** Id-derived default icon (ACTION_ICON_BY_ID in kumiko-screen.tsx) —
-     *  ToolbarAction has no author-declared icon field, unlike RowAction. */
-    readonly icon?: IconKey;
-};
+} & DataTableTableBlockProps;
 export declare function RenderList(props: RenderListProps): ReactNode;