@cosmicdrift/kumiko-renderer 0.388.0 → 0.390.0

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

@@ -0,0 +1,83 @@
+import { useCallback, useMemo, useState } from "react";
+import { useListUrlState } from "../hooks/use-list-url-state.js";
+import { buildFilterPayload, mergeReferenceFacetOptions, resolveProjectionFacetSpecs, } from "./list-facets.js";
+import { buildListQueryPayload } from "./screen-shared.js";
+import { useProjectionDateRange } from "./use-projection-date-range.js";
+// Same predicate that makes a header clickable: a stale link onto a
+// sortable:false/unknown column must not reach the server (it answers 400).
+function resolveActiveSort(urlSort, input) {
+    const { screen, entity, sortable } = input;
+    const urlSortField = urlSort === null ? undefined : entity.fields[urlSort.field];
+    const urlSortAllowed = urlSortField !== undefined && "sortable" in urlSortField && urlSortField.sortable === true;
+    return sortable ? ((urlSortAllowed ? urlSort : null) ?? screen.defaultSort ?? null) : null;
+}
+export function useProjectionListQuery(input) {
+    const { screen, featureName, effectiveTranslate, searchable, paginated } = input;
+    const urlState = useListUrlState(screen.id);
+    // Gated on the derived capability, not just on whether URL-state happens to
+    // carry a value — a stale/hand-crafted URL (?…q=x on a non-searchable
+    // screen) must not smuggle a param the query's Zod schema doesn't accept.
+    const activeSearch = searchable ? urlState.q : "";
+    const activeSort = resolveActiveSort(urlState.sort, input);
+    const limit = urlState.pageSize ?? screen.pageSize ?? 50;
+    // Pages-mode only (see header comment) — an author-set pagination:
+    // "infinite" on a paginated projectionList is silently a no-op today.
+    const usePager = paginated && (screen.pagination ?? "pages") === "pages";
+    // Facets — a projectionList has no entity, so screen.facets is
+    // the only field inventory; resolveProjectionFacetSpecs reshapes +
+    // translates its explicit labels into the same ResolvedFacetSpec the
+    // entityList adapter produces, so both feed the same
+    // buildFilterFacets/buildFilterPayload.
+    const facetSpecs = useMemo(() => resolveProjectionFacetSpecs(screen.facets, effectiveTranslate, featureName), [screen.facets, effectiveTranslate, featureName]);
+    const [projectionReferenceFacetOptions, setProjectionReferenceFacetOptions] = useState({});
+    const handleProjectionFacetOptions = useCallback((field, options) => setProjectionReferenceFacetOptions((prev) => prev[field] === options ? prev : { ...prev, [field]: options }), []);
+    const resolvedFacetSpecs = useMemo(() => mergeReferenceFacetOptions(facetSpecs, projectionReferenceFacetOptions), [facetSpecs, projectionReferenceFacetOptions]);
+    const filterPayload = useMemo(() => buildFilterPayload(urlState.filters, (field) => facetSpecs.find((spec) => spec.field === field)?.type), [urlState.filters, facetSpecs]);
+    const { dateRangePayload, dateRangeFacets, handleDateRangeChange } = useProjectionDateRange(screen.facets, effectiveTranslate, urlState);
+    const queryPayload = useMemo(() => {
+        const payload = buildListQueryPayload({
+            limit,
+            search: activeSearch,
+            sort: activeSort,
+            usePager,
+            page: urlState.page,
+            useInfinite: false,
+            cursor: undefined,
+        });
+        // Gated on screen.filter/screen.facets being declared (not just on
+        // urlState/filterPayload happening to carry a value) — same rule as
+        // activeSearch/activeSort above: a stale URL must not smuggle a param
+        // the bound query's Zod schema doesn't accept.
+        if (screen.filter !== undefined) {
+            payload["filter"] = screen.filter;
+        }
+        if (screen.facets !== undefined && filterPayload.length > 0) {
+            payload["filters"] = filterPayload;
+        }
+        Object.assign(payload, dateRangePayload);
+        return payload;
+    }, [
+        limit,
+        activeSearch,
+        activeSort,
+        usePager,
+        urlState.page,
+        screen.filter,
+        screen.facets,
+        filterPayload,
+        dateRangePayload,
+    ]);
+    return {
+        urlState,
+        activeSearch,
+        activeSort,
+        limit,
+        usePager,
+        facetSpecs,
+        handleProjectionFacetOptions,
+        resolvedFacetSpecs,
+        dateRangeFacets,
+        handleDateRangeChange,
+        queryPayload,
+    };
+}

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

@@ -0,0 +1,37 @@
+import type { DispatcherError } from "../headless/index.ts";
+import type { ListAggregates } from "../hooks/use-list-aggregates.ts";
+import type { ListUrlStateApi } from "../hooks/use-list-url-state.ts";
+import type { DataTableProps } from "../primitives.tsx";
+import { type PagedRows } from "./screen-shared.tsx";
+type Row = Readonly<Record<string, unknown>>;
+export type ScreenListRows = {
+    readonly rows: readonly Row[];
+    /** The ungrouped page answer; null while grouped or before the first answer. */
+    readonly page: PagedRows | null;
+    readonly firstLoad: boolean;
+    readonly error: DispatcherError | null;
+    readonly hasData: boolean;
+    readonly retry: () => Promise<void>;
+    readonly infinite?: {
+        readonly onReachEnd: () => void;
+        readonly loadingMore: boolean;
+        readonly hasMore: boolean;
+    };
+    readonly refreshAfterWrite: () => Promise<void>;
+};
+/** 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 declare function useScreenListRows({ queryType, payload, infinite, aggregates, }: {
+    readonly queryType: string;
+    readonly payload: Readonly<Record<string, unknown>>;
+    readonly infinite: boolean;
+    readonly aggregates: ListAggregates;
+}): ScreenListRows;
+/** Pager props for `pagination: "pages"`; none until the server total arrives. */
+export declare function listPager(args: {
+    readonly usePager: boolean;
+    readonly page: PagedRows | null;
+    readonly limit: number;
+    readonly urlState: Pick<ListUrlStateApi, "page" | "setPage" | "setPageSize">;
+}): DataTableProps["pager"];
+export {};

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-edit-banners.d.ts

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