@cosmicdrift/kumiko-renderer 0.388.0 → 0.389.0

package/dist/app/use-screen-list-rows.js

@@ -0,0 +1,104 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useQuery } from "../hooks/use-query.js";
+import { refetchAfterWrite } from "./row-actions.js";
+import { pageSizeOptionsFor } from "./screen-shared.js";
+function freshInfiniteState(resetKey) {
+    return { resetKey, rows: [], cursor: undefined, hasMore: true };
+}
+// Live updates can bring an entry onto the next page that was already appended.
+function appendUnseen(previous, next) {
+    const seen = new Set(previous.map((row) => row["id"]));
+    return [...previous, ...next.filter((row) => !seen.has(row["id"]))];
+}
+/** Rows of a URL-backed list screen: one page, accumulated infinite pages, or the
+ *  loaded rows of the open server groups. `payload` carries no cursor. */
+export function useScreenListRows({ queryType, payload, infinite, aggregates, }) {
+    const { grouped, refresh: refreshAggregates } = aggregates;
+    const resetKey = JSON.stringify(payload);
+    const [infiniteState, setInfiniteState] = useState(() => freshInfiniteState(resetKey));
+    const state = infiniteState.resetKey === resetKey ? infiniteState : freshInfiniteState(resetKey);
+    if (infiniteState.resetKey !== resetKey)
+        setInfiniteState(state);
+    const cursor = infinite ? state.cursor : undefined;
+    const rowsPayload = useMemo(() => (cursor === undefined ? payload : { ...payload, cursor }), [payload, cursor]);
+    const rowsQuery = useQuery(queryType, rowsPayload, { live: true, enabled: !grouped });
+    const { data, loading, refetch } = rowsQuery;
+    const lastDataRef = useRef(null);
+    useEffect(() => {
+        // skip: only a new answer of an infinite list is appended
+        if (!infinite || data === null || data === lastDataRef.current)
+            return;
+        lastDataRef.current = data;
+        setInfiniteState((current) => current.resetKey !== resetKey
+            ? current
+            : {
+                ...current,
+                rows: current.cursor === undefined ? data.rows : appendUnseen(current.rows, data.rows),
+                hasMore: data.nextCursor !== null,
+            });
+    }, [data, infinite, resetKey]);
+    const onReachEnd = useCallback(() => {
+        // skip: the next page waits for the current answer
+        if (loading)
+            return;
+        const nextCursor = data?.nextCursor;
+        // skip: no cursor means the last page is loaded
+        if (nextCursor === undefined || nextCursor === null)
+            return;
+        setInfiniteState((current) => current.resetKey === resetKey ? { ...current, cursor: nextCursor } : current);
+    }, [loading, data, resetKey]);
+    const refreshAfterWrite = useCallback(async () => {
+        refreshAggregates();
+        // skip: grouped rows reload through the aggregates refresh
+        if (grouped)
+            return;
+        if (infinite && cursor !== undefined) {
+            setInfiniteState(freshInfiniteState(resetKey));
+            // skip: starting over refetches the first page
+            return;
+        }
+        await refetchAfterWrite(refetch);
+    }, [refreshAggregates, grouped, infinite, cursor, resetKey, refetch]);
+    const retry = useCallback(async () => {
+        if (grouped)
+            refreshAggregates();
+        else
+            await refetch();
+    }, [grouped, refreshAggregates, refetch]);
+    if (grouped) {
+        return {
+            rows: aggregates.rows,
+            page: null,
+            firstLoad: aggregates.loading,
+            error: aggregates.error,
+            hasData: aggregates.serverGroups !== undefined,
+            retry,
+            refreshAfterWrite,
+        };
+    }
+    return {
+        rows: infinite ? state.rows : (data?.rows ?? []),
+        page: data,
+        firstLoad: loading && data === null,
+        error: rowsQuery.error,
+        hasData: data !== null,
+        retry,
+        ...(infinite && { infinite: { onReachEnd, loadingMore: loading, hasMore: state.hasMore } }),
+        refreshAfterWrite,
+    };
+}
+/** Pager props for `pagination: "pages"`; none until the server total arrives. */
+export function listPager(args) {
+    const { usePager, page, limit, urlState } = args;
+    const total = page?.total;
+    if (!usePager || total === undefined)
+        return undefined;
+    return {
+        page: urlState.page,
+        limit,
+        total,
+        onPageChange: urlState.setPage,
+        pageSizeOptions: pageSizeOptionsFor(limit),
+        onPageSizeChange: urlState.setPageSize,
+    };
+}

package/dist/app/use-screen-list-table.d.ts

@@ -0,0 +1,24 @@
+import type { EntityListScreenDefinition, ProjectionListScreenDefinition } from "@cosmicdrift/kumiko-types/screen";
+import type { Translate } from "../headless/index.ts";
+import type { ListGroupPaging } from "../hooks/list-group-pages.ts";
+import { type ListAggregates } from "../hooks/use-list-aggregates.ts";
+import { type ListTableProps } from "../hooks/use-list-table.ts";
+import type { DataTableTableBlockProps } from "../primitives.tsx";
+type ScreenListTableArgs = {
+    readonly screen: EntityListScreenDefinition | ProjectionListScreenDefinition;
+    readonly featureName: string;
+    /** The list query payload as sent; paging keys are stripped for the export. */
+    readonly payload: Readonly<Record<string, unknown>>;
+    readonly filterFields: readonly string[];
+    readonly queryType: string;
+    readonly pageSize: number;
+    readonly paging: ListGroupPaging;
+    readonly translate: Translate;
+};
+export type ScreenListTable = {
+    readonly props: ListTableProps & Pick<DataTableTableBlockProps, "serverGroups" | "totals" | "notice">;
+    readonly aggregates: ListAggregates;
+};
+/** Table-block wiring of a URL-backed list screen (entityList, projectionList). */
+export declare function useScreenListTable({ screen, featureName, payload, filterFields, queryType, pageSize, paging, translate, }: ScreenListTableArgs): ScreenListTable;
+export {};

package/dist/app/use-screen-list-table.js

@@ -0,0 +1,46 @@
+import { useMemo } from "react";
+import { useListStateStore } from "../components/list-state-store.js";
+import { useListAggregates } from "../hooks/use-list-aggregates.js";
+import { useListTable } from "../hooks/use-list-table.js";
+import { listViewSchemaColumns } from "../hooks/use-list-view-state.js";
+import { useRememberedListParams } from "../hooks/use-remembered-list-params.js";
+/** Table-block wiring of a URL-backed list screen (entityList, projectionList). */
+export function useScreenListTable({ screen, featureName, payload, filterFields, queryType, pageSize, paging, translate, }) {
+    const { id: screenId, table, columns } = screen;
+    const store = useListStateStore();
+    const schemaColumns = useMemo(() => listViewSchemaColumns(columns), [columns]);
+    const known = useMemo(() => ({ columnFields: schemaColumns.map((column) => column.field), filterFields }), [schemaColumns, filterFields]);
+    useRememberedListParams({
+        screenId,
+        enabled: table?.rememberState === true,
+        store,
+        known,
+    });
+    const exportSource = useMemo(() => ({ screen: `${featureName}:screen:${screenId}`, screenShortId: screenId, payload }), [featureName, screenId, payload]);
+    const { props, groupField } = useListTable({
+        storeKey: screenId,
+        table,
+        schemaColumns,
+        url: { screenId },
+        exportSource,
+    });
+    const aggregates = useListAggregates({
+        queryType,
+        payload,
+        table,
+        groupField,
+        pageSize,
+        paging,
+        translate,
+    });
+    const { serverGroups, totals, notice } = aggregates;
+    return {
+        props: {
+            ...props,
+            ...(serverGroups !== undefined && { serverGroups }),
+            ...(totals !== undefined && { totals }),
+            ...(notice !== undefined && { notice }),
+        },
+        aggregates,
+    };
+}

package/dist/components/list-group-page-bridges.d.ts

@@ -0,0 +1,3 @@
+import { type ReactNode } from "react";
+import type { ListGroupPagesProps } from "../hooks/use-list-aggregates.ts";
+export declare function ListGroupPageBridges({ queryType, requests, onResult, refreshNonce, }: ListGroupPagesProps): ReactNode;

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,11 +16,12 @@ 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`
@@ -85,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;
@@ -126,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();
@@ -165,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 }), []);
@@ -198,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
@@ -278,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({
@@ -348,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,
@@ -370,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
@@ -382,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-field.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

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 }))] }));
+}