@cosmicdrift/kumiko-renderer 0.389.0 → 0.390.0

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

@@ -0,0 +1,5 @@
+import type { EntityListScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import { type ReactNode } from "react";
+export declare function ListHeaderSlotMount({ screen, }: {
+    readonly screen: EntityListScreenDefinition;
+}): ReactNode;

package/dist/components/render-list-header-slot.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect } from "react";
+import { extensionSectionName, useExtensionSectionComponent } from "../app/extension-sections.js";
+import { rendererWarn } from "../dev-console.js";
+// Header slot in the list toolbar (toolbarEnd): `screen.slots.header` is
+// a PlatformComponent (`{ react: { __component: "X" } }`) resolved through
+// the same ExtensionSectionsProvider registry as entityEdit sections.
+// entityId is null in the list context because there is no row; the component
+// loads its own data (for example, a cap counter from a usage query). A
+// separate component is required by the Rules of Hooks because
+// useExtensionSectionComponent must not run conditionally in RenderList.
+export function ListHeaderSlotMount({ screen, }) {
+    const header = screen.slots?.header;
+    const name = header !== undefined ? extensionSectionName(header) : undefined;
+    const Component = useExtensionSectionComponent(name);
+    // A declared-but-unregistered header slot renders nothing; warn so the author
+    // finds the typo / missing clientFeatures.extensionSectionComponents entry,
+    // mirroring the diagnostic banner in render-edit's ExtensionSectionMount
+    // (the toolbar has no room for a banner, so a dev-warn it is).
+    useEffect(() => {
+        if (name !== undefined && Component === undefined) {
+            rendererWarn(`[kumiko] List header slot component "${name}" on screen "${screen.id}" is not registered in clientFeatures.extensionSectionComponents — the header slot renders nothing.`);
+        }
+    }, [name, Component, screen.id]);
+    if (Component === undefined)
+        return null;
+    // screenId lets a header control drive this list's URL-filter state
+    // (useListUrlState) — e.g. a tag filter narrowing the list to an id-set.
+    return _jsx(Component, { entityName: screen.entity, entityId: null, screenId: screen.id });
+}

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

@@ -0,0 +1,3 @@
+import type { ReactNode } from "react";
+import type { PublishedReferenceLookup, ReferenceColumnSpec } from "./render-list-reference-columns.ts";
+export declare function renderReferenceLookupBridges(referenceColumns: readonly ReferenceColumnSpec[], onMap: (field: string, lookup: PublishedReferenceLookup) => void): ReactNode;

package/dist/components/render-list-reference-bridge.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect } from "react";
+import { useReferenceLookup } from "../hooks/use-reference-lookup.js";
+// Bridge component for each reference column. It is mounted once per
+// column, calls useReferenceLookup unconditionally, and publishes the map
+// to the parent through onMap. React manages mounting and unmounting when
+// the schema changes through the key prop in the parent's map loop.
+function ReferenceLookupBridge({ field, refEntity, labelField, featureName, onMap, }) {
+    const lookup = useReferenceLookup(featureName, refEntity, labelField);
+    // Use an effect rather than calling directly so setState runs outside the
+    // render path; otherwise React warns about updating one component while
+    // rendering another.
+    // Do not publish while loading or after a failed lookup: a missing map means
+    // "not resolved", whereas an empty published map means "nothing found".
+    // Only the latter may display "Unknown".
+    const resolved = !lookup.loading && !lookup.failed;
+    useEffect(() => {
+        if (resolved)
+            onMap(field, { map: lookup.map, complete: lookup.complete });
+    }, [field, lookup.map, lookup.complete, resolved, onMap]);
+    return null;
+}
+export function renderReferenceLookupBridges(referenceColumns, onMap) {
+    return referenceColumns.map((rc) => (_jsx(ReferenceLookupBridge, { field: rc.field, refEntity: rc.refEntity, labelField: rc.labelField, featureName: rc.refFeature, onMap: onMap }, rc.field)));
+}

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

@@ -0,0 +1,25 @@
+import type { useReferenceLinkResolver } from "../app/reference-link.ts";
+import type { ListColumnViewModel, Translate } from "../headless/index.ts";
+import type { ReferenceLookupMap } from "../hooks/use-reference-lookup.ts";
+export type PublishedReferenceLookup = {
+    readonly map: ReferenceLookupMap;
+    readonly complete: boolean;
+};
+export type ReferenceColumnSpec = {
+    readonly field: string;
+    readonly refEntity: string;
+    readonly refFeature: string;
+    readonly labelField: string;
+};
+type ResolveReferenceLink = ReturnType<typeof useReferenceLinkResolver>;
+export declare function selectReferenceColumns(columns: readonly ListColumnViewModel[], featureName: string): ReferenceColumnSpec[];
+export type EnrichReferenceColumnsInput = {
+    readonly columns: readonly ListColumnViewModel[];
+    readonly referenceColumns: readonly ReferenceColumnSpec[];
+    readonly referenceLookups: Readonly<Record<string, PublishedReferenceLookup>>;
+    readonly resolveReferenceLink: ResolveReferenceLink;
+    readonly featureName: string;
+    readonly translate: Translate;
+};
+export declare function enrichReferenceColumns(input: EnrichReferenceColumnsInput): readonly ListColumnViewModel[];
+export {};

package/dist/components/render-list-reference-columns.js

@@ -0,0 +1,137 @@
+import { UNRESOLVED_REFERENCE_LABEL_KEYS } from "@cosmicdrift/kumiko-framework/ui-types";
+import { EMPTY_VALUE_PLACEHOLDER } from "../headless/index.js";
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// The server leaves a missing or unreadable target out of `_refs`, and a null
+// entry means the same: both read as unresolved.
+function eagerloadedRef(row, field) {
+    // skip: row carries no eager-loaded refs, so the lookup map decides
+    if (!isPlainRecord(row) || !isPlainRecord(row["_refs"]))
+        return undefined;
+    const ref = row["_refs"][field];
+    if (Array.isArray(ref))
+        return ref.filter(isPlainRecord);
+    return isPlainRecord(ref) ? ref : undefined;
+}
+export function selectReferenceColumns(columns, featureName) {
+    return columns
+        .filter((c) => c.type === "reference" && c.refEntity !== undefined)
+        .map((c) => ({
+        field: c.field,
+        refEntity: c.refEntity ?? "",
+        // refFeature comes from parseRefTarget in the ViewModel
+        // (default = the current featureName).
+        refFeature: c.refFeature ?? featureName,
+        labelField: c.refLabelField ?? "id",
+    }));
+}
+// No raw id for entities that opt in: a placeholder while the lookup
+// loads, the "unknown" label once the complete lookup found nothing. A
+// capped lookup page cannot prove absence, so it keeps the raw id.
+function unresolvedLabelFor(unknownKey, published, translate) {
+    return (id) => unknownKey === undefined
+        ? id
+        : published === undefined
+            ? EMPTY_VALUE_PLACEHOLDER
+            : published.complete
+                ? translate(unknownKey)
+                : id;
+}
+// Only a row the user can see is linkable: resolved by the server
+// eagerload or by the lookup query. A multi-reference links per entry via linkItemsFor.
+function buildLinkFor(lookup) {
+    const { col, map, refEntity, resolveReferenceLink } = lookup;
+    return (value, row) => {
+        // skip: empty and multi-valued cells have no single target to link
+        if (value === null || value === undefined || value === "" || Array.isArray(value)) {
+            return undefined;
+        }
+        const id = String(value);
+        const eagerloaded = eagerloadedRef(row, col.field);
+        // The server leaves a missing or unreadable target out; null is treated the same.
+        const resolved = (typeof eagerloaded === "object" && eagerloaded !== null && !Array.isArray(eagerloaded)) ||
+            map?.has(id);
+        return resolved === true ? resolveReferenceLink(refEntity, id) : undefined;
+    };
+}
+function buildLinkItemsFor(lookup) {
+    const { col, map, refEntity, labelField, resolveReferenceLink, unresolvedLabel } = lookup;
+    return (value, row) => {
+        // skip: only a non-empty array is a multi-reference value
+        if (!Array.isArray(value) || value.length === 0)
+            return undefined;
+        const eagerloaded = eagerloadedRef(row, col.field);
+        const eagerById = new Map(Array.isArray(eagerloaded) ? eagerloaded.map((r) => [String(r["id"]), r]) : []);
+        return value.map((v) => {
+            const id = String(v);
+            const target = eagerById.get(id);
+            const label = String(target?.[labelField] ?? map?.get(id) ?? unresolvedLabel(id));
+            // Only a row the user can see is linkable: server eagerload or lookup query.
+            const link = target !== undefined || map?.has(id) === true
+                ? resolveReferenceLink(refEntity, id)
+                : undefined;
+            return { id, label, ...(link !== undefined && { link }) };
+        });
+    };
+}
+function buildReferenceRenderer(lookup) {
+    const { col, map, labelField, unresolvedLabel } = lookup;
+    return (value, row) => {
+        // Server eager loading: when the server includes _refs, read the display
+        // value directly from the resolved row. This avoids a round trip
+        // through the bridge map and the limit:200 constraint. The
+        // EagerloadedRow type from @cosmicdrift/kumiko-framework/db defines
+        // the shape of _refs.
+        const resolved = eagerloadedRef(row, col.field);
+        if (Array.isArray(resolved) && resolved.length > 0) {
+            return resolved.map((r) => String(r[labelField] ?? r["id"] ?? "")).join(", ");
+        }
+        if (isPlainRecord(resolved)) {
+            return String(resolved[labelField] ?? resolved["id"] ?? "");
+        }
+        // Renderer-side fallback when server eager loading is not active.
+        if (Array.isArray(value)) {
+            if (value.length === 0)
+                return EMPTY_VALUE_PLACEHOLDER;
+            return value.map((v) => map?.get(String(v)) ?? unresolvedLabel(String(v))).join(", ");
+        }
+        if (value === null || value === undefined || value === "")
+            return EMPTY_VALUE_PLACEHOLDER;
+        const idStr = String(value);
+        return map?.get(idStr) ?? unresolvedLabel(idStr);
+    };
+}
+function enrichReferenceColumn(col, input) {
+    const { referenceLookups, resolveReferenceLink, featureName, translate } = input;
+    // skip: only reference columns are enriched
+    if (col.type !== "reference")
+        return col;
+    // skip: an author-declared renderer always takes precedence; the default
+    // is used only when none is set.
+    if (col.renderer !== undefined)
+        return col;
+    const published = referenceLookups[col.field];
+    const unknownKey = UNRESOLVED_REFERENCE_LABEL_KEYS[`${col.refFeature ?? featureName}:${col.refEntity ?? ""}`];
+    const lookup = {
+        col,
+        map: published?.map,
+        refEntity: col.refEntity ?? "",
+        labelField: col.refLabelField ?? "id",
+        resolveReferenceLink,
+        unresolvedLabel: unresolvedLabelFor(unknownKey, published, translate),
+    };
+    return {
+        ...col,
+        renderer: buildReferenceRenderer(lookup),
+        linkFor: buildLinkFor(lookup),
+        linkItemsFor: buildLinkItemsFor(lookup),
+    };
+}
+export function enrichReferenceColumns(input) {
+    const { columns, referenceColumns } = input;
+    // skip: without reference columns the view-model columns pass through untouched
+    if (referenceColumns.length === 0)
+        return columns;
+    return columns.map((col) => enrichReferenceColumn(col, input));
+}

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

@@ -0,0 +1,52 @@
+import type { ReactNode } from "react";
+import type { RenderListProps } from "./render-list-types.ts";
+type Pick2<K extends keyof RenderListProps> = Pick<RenderListProps, K>;
+export declare function tableChromeProps(p: Pick2<"onRowClick" | "description"> & {
+    readonly composedEmptyState: ReactNode;
+    readonly toolbarStart: ReactNode;
+    readonly toolbarEnd: ReactNode;
+    readonly itemNoun: ((count: number) => string) | undefined;
+}): {
+    onRowClick?: ((row: import("../headless/index.ts").ListRowViewModel) => void) | undefined;
+    emptyState?: string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined;
+    toolbarStart?: string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined;
+    toolbarDescription?: string | undefined;
+    toolbarEnd?: string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined;
+    itemNoun?: ((count: number) => string) | undefined;
+};
+export declare function tableSortPagingProps(p: Pick2<"sort" | "onSortChange" | "pager" | "onReachEnd" | "loadingMore" | "hasMore">): {
+    sort?: import("../primitives.tsx").DataTableSort | null | undefined;
+    onSortChange?: ((next: import("../index.ts").ListSort | null) => void) | undefined;
+    pager?: {
+        readonly page: number;
+        readonly limit: number;
+        readonly total: number;
+        readonly onPageChange: (next: number) => void;
+    } | undefined;
+    onReachEnd?: (() => void) | undefined;
+    loadingMore?: boolean | undefined;
+    hasMore?: boolean | undefined;
+};
+export declare function tableRowProps(p: Pick2<"rowActions" | "rowActionMode" | "bulk" | "rowTone">): {
+    rowActions?: readonly import("../primitives.tsx").DataTableRowAction[] | undefined;
+    rowActionMode?: import("../primitives.tsx").DataTableRowActionMode | undefined;
+    bulk?: import("../data-table-bulk-types.ts").DataTableBulk | undefined;
+    rowTone?: ((row: import("../headless/index.ts").ListRowViewModel) => import("@cosmicdrift/kumiko-types/fields").SelectOptionTone | undefined) | undefined;
+};
+export declare function tableFilterProps(p: Pick2<"filterFacets" | "filterValues" | "onFilterChange" | "onFilterReset" | "dateRangeFacets" | "onDateRangeChange">): {
+    filterFacets?: readonly import("../data-table-facet-types.ts").DataTableFacet[] | undefined;
+    filterValues?: Readonly<Record<string, readonly string[]>> | undefined;
+    onFilterChange?: ((field: string, values: readonly string[]) => void) | undefined;
+    onFilterReset?: (() => void) | undefined;
+    dateRangeFacets?: readonly import("../data-table-facet-types.ts").DataTableDateRangeFacet[] | undefined;
+    onDateRangeChange?: ((field: string, bound: "from" | "to", value: string) => void) | undefined;
+};
+export declare function tableLayoutProps(p: Pick2<"chromeless" | "scrollBody" | "screenPadding" | "expandedRowIds" | "onToggleRowExpanded" | "renderExpandedRow">): {
+    chromeless?: boolean | undefined;
+    scrollBody?: boolean | undefined;
+    screenPadding?: boolean | undefined;
+    expandedRowIds?: ReadonlySet<string> | undefined;
+    onToggleRowExpanded?: ((rowId: string) => void) | undefined;
+    renderExpandedRow?: ((row: import("../headless/index.ts").ListRowViewModel) => ReactNode) | undefined;
+};
+export {};

package/dist/components/render-list-table-props.js

@@ -0,0 +1,53 @@
+export function tableChromeProps(p) {
+    const { onRowClick, composedEmptyState, toolbarStart, description, toolbarEnd, itemNoun } = p;
+    return {
+        ...(onRowClick !== undefined && { onRowClick }),
+        ...(composedEmptyState !== undefined && { emptyState: composedEmptyState }),
+        ...(toolbarStart !== undefined && { toolbarStart }),
+        ...(description !== undefined && { toolbarDescription: description }),
+        ...(toolbarEnd !== undefined && { toolbarEnd }),
+        ...(itemNoun !== undefined && { itemNoun }),
+    };
+}
+export function tableSortPagingProps(p) {
+    const { sort, onSortChange, pager, onReachEnd, loadingMore, hasMore } = p;
+    return {
+        ...(sort !== undefined && { sort }),
+        ...(onSortChange !== undefined && { onSortChange }),
+        ...(pager !== undefined && { pager }),
+        ...(onReachEnd !== undefined && { onReachEnd }),
+        ...(loadingMore !== undefined && { loadingMore }),
+        ...(hasMore !== undefined && { hasMore }),
+    };
+}
+export function tableRowProps(p) {
+    const { rowActions, rowActionMode, bulk, rowTone } = p;
+    return {
+        ...(rowActions !== undefined && { rowActions }),
+        ...(rowActionMode !== undefined && { rowActionMode }),
+        ...(bulk !== undefined && { bulk }),
+        ...(rowTone !== undefined && { rowTone }),
+    };
+}
+export function tableFilterProps(p) {
+    const { filterFacets, filterValues, onFilterChange, onFilterReset, dateRangeFacets, onDateRangeChange, } = p;
+    return {
+        ...(filterFacets !== undefined && { filterFacets }),
+        ...(filterValues !== undefined && { filterValues }),
+        ...(onFilterChange !== undefined && { onFilterChange }),
+        ...(onFilterReset !== undefined && { onFilterReset }),
+        ...(dateRangeFacets !== undefined && { dateRangeFacets }),
+        ...(onDateRangeChange !== undefined && { onDateRangeChange }),
+    };
+}
+export function tableLayoutProps(p) {
+    const { chromeless, scrollBody, screenPadding, expandedRowIds, onToggleRowExpanded, renderExpandedRow, } = p;
+    return {
+        ...(chromeless !== undefined && { chromeless }),
+        ...(scrollBody !== undefined && { scrollBody }),
+        ...(screenPadding !== undefined && { screenPadding }),
+        ...(expandedRowIds !== undefined && { expandedRowIds }),
+        ...(onToggleRowExpanded !== undefined && { onToggleRowExpanded }),
+        ...(renderExpandedRow !== undefined && { renderExpandedRow }),
+    };
+}

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

@@ -0,0 +1,42 @@
+import type { EntityListScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Translate } from "../headless/index.ts";
+import { type ActionMenuItemSpec } from "../primitives.tsx";
+import type { ToolbarActionButton } from "./render-list-toolbar-action.tsx";
+type ToolbarModelInput = {
+    readonly toolbarActions: readonly ToolbarActionButton[] | undefined;
+    readonly pageHeaderAvailable: boolean;
+    readonly pageHeaderSlotAvailable: boolean;
+    readonly pageHeaderCompact: boolean;
+    readonly createInPageHeader: boolean;
+};
+export type ToolbarActionSplit = {
+    readonly toolbarIconOnly: boolean;
+    readonly promotedToolbarActions: readonly ToolbarActionButton[];
+    readonly promotedInOverflowMenu: boolean;
+    readonly toolbarActionsInToolbar: readonly ToolbarActionButton[];
+    readonly hasToolbarActionsInToolbar: boolean;
+};
+export declare function splitToolbarActions(input: ToolbarModelInput): ToolbarActionSplit;
+type MenuItemInput = {
+    readonly promotedToolbarActions: readonly ToolbarActionButton[];
+    readonly promotedInOverflowMenu: boolean;
+    readonly menuActionBusyId: string | null;
+    readonly setMenuActionBusyId: (id: string | null) => void;
+    readonly setMenuActionError: (message: string | null) => void;
+};
+export declare function buildPromotedMenuItems(input: MenuItemInput): readonly ActionMenuItemSpec[];
+type ListLabelInput = {
+    readonly screen: EntityListScreenDefinition;
+    readonly translate: Translate;
+    readonly createLabel: string | undefined;
+    readonly searchPlaceholder: string | undefined;
+    readonly itemNounKey: string | undefined;
+    readonly featureName: string;
+};
+export declare function resolveToolbarLabels(input: ListLabelInput): {
+    effectiveCreateLabel: string;
+    effectiveSearchPlaceholder: string;
+};
+export declare function resolveItemNoun(input: ListLabelInput): ((count: number) => string) | undefined;
+export declare function resolveToolbarTitle(screen: EntityListScreenDefinition, translate: Translate): string;
+export {};

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

@@ -0,0 +1,82 @@
+import { shouldRenderActionsIconOnly } from "../primitives.js";
+import { needsActionConfirm } from "./render-edit-action-button.js";
+// Icon-less actions are promoted too; on phones the call site falls back to a
+// "plus" icon, on desktop the label carries the action.
+function isHeaderPromotableToolbarAction(action) {
+    return action.style === "primary" && !needsActionConfirm(action);
+}
+export function splitToolbarActions(input) {
+    const { toolbarActions, pageHeaderAvailable, pageHeaderSlotAvailable, pageHeaderCompact, createInPageHeader, } = input;
+    const hasToolbarActions = toolbarActions !== undefined && toolbarActions.length > 0;
+    const toolbarIconOnly = hasToolbarActions && shouldRenderActionsIconOnly(toolbarActions);
+    // Every primary toolbar action takes the page-header slot, left of the create
+    // button (which stays the rightmost primary action): labelled on desktop, so
+    // projection lists look like entity lists. On phones an icon button, or, next to
+    // the create button, an entry in the header's overflow menu: the header has no
+    // room for a labelled action beside it.
+    const promotedToolbarActions = pageHeaderAvailable && pageHeaderSlotAvailable
+        ? (toolbarActions?.filter(isHeaderPromotableToolbarAction) ?? [])
+        : [];
+    const promotedInOverflowMenu = pageHeaderCompact && createInPageHeader && promotedToolbarActions.length > 0;
+    const toolbarActionsInToolbar = toolbarActions?.filter((a) => !promotedToolbarActions.includes(a)) ?? [];
+    const hasToolbarActionsInToolbar = toolbarActionsInToolbar.length > 0;
+    return {
+        toolbarIconOnly,
+        promotedToolbarActions,
+        promotedInOverflowMenu,
+        toolbarActionsInToolbar,
+        hasToolbarActionsInToolbar,
+    };
+}
+export function buildPromotedMenuItems(input) {
+    const { promotedToolbarActions, promotedInOverflowMenu, menuActionBusyId, setMenuActionBusyId, setMenuActionError, } = input;
+    return promotedInOverflowMenu
+        ? promotedToolbarActions.map((a) => ({
+            id: a.id,
+            label: a.label,
+            ...(a.icon !== undefined && { icon: a.icon }),
+            ...(menuActionBusyId !== null && { disabled: true }),
+            testId: `render-list-toolbar-action-${a.id}`,
+            onSelect: () => {
+                setMenuActionBusyId(a.id);
+                setMenuActionError(null);
+                void (async () => {
+                    try {
+                        await a.onTrigger();
+                    }
+                    catch (e) {
+                        setMenuActionError(e instanceof Error ? e.message : String(e));
+                    }
+                    finally {
+                        setMenuActionBusyId(null);
+                    }
+                })();
+            },
+        }))
+        : [];
+}
+export function resolveToolbarLabels(input) {
+    const { screen, translate, createLabel, searchPlaceholder } = input;
+    // i18n defaults for toolbar and empty-state strings. The caller can
+    // override each one through a prop; otherwise the framework bundles provide
+    // them (kumiko.actions.create, kumiko.list.search-placeholder, …).
+    const effectiveCreateLabel = translate(createLabel ?? screen.createLabel ?? "kumiko.actions.create");
+    const effectiveSearchPlaceholder = translate(searchPlaceholder ?? screen.searchPlaceholder ?? "kumiko.list.search-placeholder");
+    return { effectiveCreateLabel, effectiveSearchPlaceholder };
+}
+export function resolveItemNoun(input) {
+    const { screen, translate, itemNounKey, featureName } = input;
+    const nounKey = itemNounKey ?? `${featureName}:entity:${screen.entity}:noun`;
+    return (itemNounKey !== undefined || !screen.entity.startsWith("__")) &&
+        translate(nounKey, { count: 2 }) !== nounKey
+        ? (count) => translate(nounKey, { count })
+        : undefined;
+}
+// Title resolution uses the conventional i18n key `screen:<id>.title`.
+// If the bundle knows the key, use its translated title; otherwise use
+// screenId so the app developer can see that the translation is missing.
+export function resolveToolbarTitle(screen, translate) {
+    const titleKey = `screen:${screen.id}.title`;
+    const resolvedTitle = translate(titleKey);
+    return resolvedTitle === titleKey ? screen.id : resolvedTitle;
+}

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

@@ -0,0 +1,38 @@
+import type { EntityListScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { ReactNode } from "react";
+import type { Translate } from "../headless/index.ts";
+import type { ActionMenuItemSpec, usePrimitives } from "../primitives.tsx";
+import { type ListEmptyStateContent } from "./list-empty-state.tsx";
+import type { ToolbarActionSplit } from "./render-list-toolbar-model.ts";
+type Primitives = ReturnType<typeof usePrimitives>;
+export type ListToolbarModel = {
+    readonly screen: EntityListScreenDefinition;
+    readonly Button: Primitives["Button"];
+    readonly Dialog: Primitives["Dialog"];
+    readonly Banner: Primitives["Banner"];
+    readonly onCreate: (() => void) | undefined;
+    readonly createInPageHeader: boolean;
+    readonly pageHeaderCompact: boolean;
+    readonly effectiveCreateLabel: string;
+    readonly split: ToolbarActionSplit;
+};
+export declare function renderCreateButton(model: ListToolbarModel): ReactNode;
+export declare function renderHeaderActions(model: ListToolbarModel, createButton: ReactNode): ReactNode;
+export declare function renderToolbarEnd(model: ListToolbarModel, createButton: ReactNode): ReactNode;
+export declare function renderSearchInput(Input: Primitives["Input"], localQ: string, setLocalQ: (next: string) => void, placeholder: string): ReactNode;
+type EmptyStateModel = {
+    readonly Button: Primitives["Button"];
+    readonly emptyState: ReactNode;
+    readonly onCreate: (() => void) | undefined;
+    readonly emptyContent: ListEmptyStateContent | undefined;
+    readonly narrowed: boolean;
+    readonly defaultFilterActive: boolean;
+    readonly onFilterReset: (() => void) | undefined;
+    readonly translate: Translate;
+    readonly createInPageHeader: boolean;
+    readonly effectiveCreateLabel: string;
+};
+export declare function composeEmptyState(model: EmptyStateModel): ReactNode;
+export declare function renderPageHeader(PageHeader: NonNullable<Primitives["PageHeader"]>, headerActions: ReactNode, promotedInOverflowMenu: boolean, promotedMenuItems: readonly ActionMenuItemSpec[]): ReactNode;
+export declare function renderMenuActionError(Banner: Primitives["Banner"], menuActionError: string): ReactNode;
+export {};

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

@@ -0,0 +1,40 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ListEmptyStateBody } from "./list-empty-state.js";
+import { ListHeaderSlotMount } from "./render-list-header-slot.js";
+import { ToolbarActionView } from "./render-list-toolbar-action.js";
+export function renderCreateButton(model) {
+    const { Button, onCreate, createInPageHeader, pageHeaderCompact, effectiveCreateLabel } = model;
+    return onCreate !== undefined && createInPageHeader && pageHeaderCompact ? (_jsx(Button, { variant: "primary", icon: "plus", size: "icon", ariaLabel: effectiveCreateLabel, title: effectiveCreateLabel, onClick: onCreate, testId: "render-list-create" })) : onCreate !== undefined ? (_jsx(Button, { variant: "primary", icon: "plus", onClick: onCreate, testId: "render-list-create", className: "px-3.5", children: effectiveCreateLabel })) : undefined;
+}
+export function renderHeaderActions(model, createButton) {
+    const { Button, Dialog, Banner, createInPageHeader, pageHeaderCompact, split } = model;
+    const { promotedToolbarActions, promotedInOverflowMenu } = split;
+    return promotedToolbarActions.length > 0 && !promotedInOverflowMenu ? (_jsxs(_Fragment, { children: [promotedToolbarActions.map((a) => (_jsx(ToolbarActionView, { action: pageHeaderCompact ? { ...a, icon: a.icon ?? "plus" } : a, iconOnly: pageHeaderCompact, Button: Button, Dialog: Dialog, Banner: Banner }, a.id))), createInPageHeader && createButton] })) : createInPageHeader ? (createButton) : undefined;
+}
+export function renderToolbarEnd(model, createButton) {
+    const { screen, Button, Dialog, Banner, onCreate, createInPageHeader, split } = model;
+    const { toolbarActionsInToolbar, hasToolbarActionsInToolbar, toolbarIconOnly } = split;
+    const hasHeaderSlot = screen.slots?.header !== undefined;
+    return hasHeaderSlot ||
+        hasToolbarActionsInToolbar ||
+        (onCreate !== undefined && !createInPageHeader) ? (_jsxs(_Fragment, { children: [hasHeaderSlot && _jsx(ListHeaderSlotMount, { screen: screen }), hasToolbarActionsInToolbar &&
+                toolbarActionsInToolbar.map((a) => (_jsx(ToolbarActionView, { action: a, iconOnly: toolbarIconOnly, Button: Button, Dialog: Dialog, Banner: Banner }, a.id))), !createInPageHeader && createButton] })) : undefined;
+}
+export function renderSearchInput(Input, localQ, setLocalQ, placeholder) {
+    return (_jsx(Input, { kind: "text", id: "render-list-search", name: "search", value: localQ, onChange: setLocalQ, placeholder: placeholder }));
+}
+// Empty state: by default, show a heading, description, and optional CTA
+// button. The caller can replace it completely through emptyState.
+// Without onCreate or an override, DataTable uses its default
+// (`kumiko.list.no-entries`).
+export function composeEmptyState(model) {
+    const { Button, emptyState, onCreate, emptyContent, narrowed, defaultFilterActive, onFilterReset, translate, createInPageHeader, effectiveCreateLabel, } = model;
+    return (emptyState ??
+        (onCreate !== undefined || emptyContent !== undefined || narrowed || defaultFilterActive ? (_jsx(ListEmptyStateBody, { content: emptyContent, narrowed: narrowed, defaultFilterActive: defaultFilterActive, ...(onFilterReset !== undefined && { onShowAll: onFilterReset }), translate: translate, createButton: onCreate !== undefined && !narrowed && !defaultFilterActive && !createInPageHeader ? (_jsx(Button, { variant: "primary", icon: "plus", onClick: onCreate, testId: "render-list-empty-create", children: effectiveCreateLabel })) : undefined })) : undefined));
+}
+export function renderPageHeader(PageHeader, headerActions, promotedInOverflowMenu, promotedMenuItems) {
+    return (_jsx(PageHeader, { actions: headerActions, ...(promotedInOverflowMenu && { overflowItems: promotedMenuItems }) }));
+}
+export function renderMenuActionError(Banner, menuActionError) {
+    return (_jsx(Banner, { variant: "error", testId: "render-list-toolbar-action-error", children: menuActionError }));
+}