@cosmicdrift/kumiko-renderer 0.328.0 → 0.328.1

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

@@ -0,0 +1,273 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { normalizeListColumn } from "@cosmicdrift/kumiko-framework/ui-types";
+import { useCallback, useMemo, useState } from "react";
+import { useAppFeatures } from "../app/app-features-context.js";
+import { buildFilterFacets, buildFilterPayload, mergeReferenceFacetOptions, resolveProjectionFacetSpecs, } from "../app/list-facets.js";
+import { useNav } from "../app/nav.js";
+import { ReferenceFacetBridges } from "../app/reference-facet-bridge.js";
+import { navigateWithReturnTo, useReturnHost } from "../app/return-to.js";
+import { buildDefaultEditRowAction, buildProjectionRowActions, buildProjectionToolbarActions, buildRecordActions, runProjectionRowNavigate, } from "../app/row-actions.js";
+import { findEditScreenFor } from "../app/screen-access.js";
+import { dispatcherErrorText } from "../app/write-failed-error.js";
+import { useOptionalDispatcher } from "../context/dispatcher-context.js";
+import { useUserRoles } from "../context/user-roles-context.js";
+import { useQuery } from "../hooks/use-query.js";
+import { useTranslation } from "../i18n.js";
+import { PageHeaderSlotAvailableProvider } from "../page-header-slot.js";
+import { usePrimitives } from "../primitives.js";
+import { sortByAccessor } from "../sort-by-accessor.js";
+import { RenderEditActionButton } from "./render-edit-action-button.js";
+import { RenderList } from "./render-list.js";
+const RELATED_LIST_PSEUDO_ENTITY = "__related-list__";
+// Minimal EntityDefinition from the section's own columns — same shape as
+// projection-list-shim's synthesizeProjectionEntity, but sortable is read
+// per-column (ListColumnSpec.sortable) instead of screen-wide, since a
+// relatedList section has no single Zod schema to derive it from.
+function synthesizeRelatedListEntity(columns) {
+    const fields = {};
+    for (const col of columns) {
+        const normalized = normalizeListColumn(col);
+        fields[normalized.field] = {
+            type: normalized.valueType ?? "text",
+            sortable: normalized.sortable === true,
+        };
+    }
+    return { fields };
+}
+// Mirrors row-actions.ts's own warnDrawerActionDropped (module-private
+// there, so not reusable directly) — a drawer-kind emptyState.action with no
+// onOpenDrawer wired is dropped (not rendered) with a dev warning, same as a
+// drawer-kind rowAction/toolbarAction without one.
+function warnRelatedListEmptyStateDrawerDropped(actionId) {
+    // biome-ignore lint/suspicious/noConsole: dev-time warning, same pattern as row-actions.ts
+    console.warn(`[kumiko] relatedList emptyState.action "${actionId}" is kind: "drawer" but no onOpenDrawer was supplied — dropped.`);
+}
+export function RelatedListSection({ section, parentId, record, featureName, translate, hideTitle, grow, onOpenDrawer, actions, }) {
+    const { Banner, Section, FillContainer, Text, Button, Dialog } = usePrimitives();
+    const [emptyStateActionError, setEmptyStateActionError] = useState(null);
+    const t = useTranslation();
+    const effectiveTranslate = translate ?? t;
+    const nav = useNav();
+    const host = useReturnHost();
+    const dispatcher = useOptionalDispatcher();
+    const appFeatures = useAppFeatures();
+    const userRoles = useUserRoles();
+    const defaultEditScreen = useMemo(() => {
+        const targetEntity = section.rowClick?.entity;
+        if (targetEntity === undefined)
+            return undefined;
+        return findEditScreenFor(targetEntity, appFeatures, userRoles);
+    }, [appFeatures, section.rowClick, userRoles]);
+    const defaultEditRowAction = useMemo(() => buildDefaultEditRowAction(defaultEditScreen, section.rowClick?.idColumn ?? "id"), [defaultEditScreen, section.rowClick]);
+    const entity = useMemo(() => synthesizeRelatedListEntity(section.columns), [section.columns]);
+    const listScreen = useMemo(() => ({
+        // Empty id → RenderList's own toolbarTitle resolves to "" (its
+        // `screen:${id}.title` lookup misses and falls back to `id`) — this
+        // component renders the visible heading itself via `Section` below,
+        // so RenderList's toolbar carries none.
+        id: "",
+        type: "entityList",
+        entity: RELATED_LIST_PSEUDO_ENTITY,
+        columns: section.columns,
+    }), [section.columns]);
+    // 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 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 }), []);
+    const resolvedFacetSpecs = useMemo(() => mergeReferenceFacetOptions(facetSpecs, referenceFacetOptions), [facetSpecs, referenceFacetOptions]);
+    const filterPayload = useMemo(() => buildFilterPayload(filters, (field) => resolvedFacetSpecs.find((spec) => spec.field === field)?.type), [filters, resolvedFacetSpecs]);
+    const filterFacets = useMemo(() => buildFilterFacets(resolvedFacetSpecs), [resolvedFacetSpecs]);
+    const payload = useMemo(() => ({
+        // `parentFilter` sends the parent id as a server-side `filter` clause
+        // instead of a bespoke top-level key — the generic `<entity>:list`
+        // query understands `filter`, not an arbitrary `parentParam` key. Kept
+        // separate from `filterPayload` (user facets) below so a facet
+        // selection can never clear or overwrite it.
+        ...(section.parentFilter !== undefined
+            ? { filter: { field: section.parentFilter.field, op: "eq", value: parentId } }
+            : { [section.parentParam ?? "id"]: parentId }),
+        ...(section.pageSize !== undefined && { limit: section.pageSize }),
+        // Gated on the declared capability, not just on state carrying a value —
+        // same rule as ProjectionListBody: a param the bound query's Zod schema
+        // doesn't accept would 422 the whole section.
+        ...(section.searchable === true && search !== "" && { search }),
+        ...(section.facets !== undefined && filterPayload.length > 0 && { filters: filterPayload }),
+    }), [
+        section.parentFilter,
+        section.parentParam,
+        section.pageSize,
+        section.searchable,
+        section.facets,
+        parentId,
+        search,
+        filterPayload,
+    ]);
+    const rowsQuery = useQuery(section.query, payload);
+    const onFilterChange = useCallback((field, values) => setFilters((prev) => ({ ...prev, [field]: values })), []);
+    const onFilterReset = useCallback(() => setFilters({}), []);
+    // Sorted client-side over the already-loaded rows — this section has no
+    // pager (see `payload` above: a one-shot fetch, no cursor/offset), so the
+    // loaded set already IS the full display set and there is no "other page"
+    // a client-side sort could misleadingly hide (fw#2722).
+    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];
+                return typeof value === "number" ? value : String(value ?? "");
+            };
+        }
+        return accessors;
+    }, [section.columns]);
+    const sortedRows = useMemo(() => sortByAccessor(rowsQuery.data?.rows ?? [], sort, sortAccessors), [rowsQuery.data, sort, sortAccessors]);
+    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
+    // both being set, so this order is just a fallback, not a precedence rule.
+    const rowClickAction = section.rowActions?.find((a) => a.kind === "navigate" && a.rowClick === true);
+    const onRowClick = rowClick !== undefined
+        ? (row) => {
+            const id = String(row.values[rowClick.idColumn ?? "id"] ?? "");
+            if (id === "")
+                return;
+            navigateWithReturnTo(nav, { entity: rowClick.entity, id }, host);
+        }
+        : rowClickAction !== undefined
+            ? (row) => runProjectionRowNavigate(nav, rowClickAction, row, host)
+            : undefined;
+    // Same execution path as projectionList's rowActions (kumiko-screen.tsx) —
+    // a relatedList row has the identical "no guaranteed id field" shape a
+    // query-projection row has, so navigate/writeHandler dispatch is shared
+    // rather than a second implementation (fw editable-detail-screens).
+    const rowActions = useMemo(() => buildProjectionRowActions({
+        rowActions: section.rowActions,
+        translate: effectiveTranslate,
+        dispatcher,
+        nav,
+        refetch: rowsQuery.refetch,
+        openDrawer: onOpenDrawer,
+        defaultEditRowAction,
+        host,
+    }), [
+        section.rowActions,
+        effectiveTranslate,
+        dispatcher,
+        nav,
+        rowsQuery.refetch,
+        onOpenDrawer,
+        defaultEditRowAction,
+        host,
+    ]);
+    // Toolbar actions (e.g. "+ Create" above the tab table) — same schema
+    // and dispatch semantics as entityList/projectionList.
+    const toolbarActionButtons = useMemo(() => buildProjectionToolbarActions({
+        toolbarActions: section.toolbarActions,
+        translate: effectiveTranslate,
+        dispatcher,
+        nav,
+        refetch: rowsQuery.refetch,
+        navigatePrefill: section.parentFilter !== undefined
+            ? { [section.parentFilter.field]: parentId }
+            : { [section.parentParam ?? "id"]: parentId },
+        record,
+        host,
+        ...(onOpenDrawer !== undefined && {
+            openDrawer: (action) => onOpenDrawer(action, undefined),
+        }),
+    }), [
+        section.toolbarActions,
+        section.parentParam,
+        section.parentFilter,
+        parentId,
+        record,
+        effectiveTranslate,
+        dispatcher,
+        nav,
+        host,
+        rowsQuery.refetch,
+        onOpenDrawer,
+    ]);
+    // emptyState.action is a RowAction — the same record-bound action shape
+    // (and evalRowExtractor payload/params evaluation) screen-level and
+    // section-level actions already use via buildRecordActions, NOT the
+    // toolbar-action builder (whose `payload` is a literal Record, not a
+    // RowFieldExtractor — casting a RowAction into it would silently skip the
+    // declared `pick`/`map` evaluation). "Row" here is the parent record: a
+    // relatedList's emptyState has no row of its own.
+    const emptyStateActionButton = useMemo(() => {
+        const action = section.emptyState?.action;
+        if (action === undefined)
+            return undefined;
+        if (action.kind === "drawer" && onOpenDrawer === undefined) {
+            warnRelatedListEmptyStateDrawerDropped(action.id);
+            return undefined;
+        }
+        return buildRecordActions({
+            actions: [action],
+            record,
+            translate: effectiveTranslate,
+            nav,
+            host,
+            dispatcher,
+            openDrawer: onOpenDrawer ?? (() => { }),
+            onWriteSuccess: rowsQuery.refetch,
+        })?.[0];
+    }, [
+        section.emptyState,
+        record,
+        effectiveTranslate,
+        nav,
+        host,
+        dispatcher,
+        onOpenDrawer,
+        rowsQuery.refetch,
+    ]);
+    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" (fw#2722 review).
+    // `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: "Loading\u2026" })) : 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 && (_jsx(Banner, { variant: "error", testId: "related-list-empty-state-action-error", children: emptyStateActionError })), _jsx(PageHeaderSlotAvailableProvider, { value: false, children: _jsx(RenderList, { screen: listScreen, entity: entity, rows: sortedRows, featureName: 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,
+                    }), ...(filterFacets.length > 0 && {
+                        filterFacets,
+                        filterValues: filters,
+                        onFilterChange,
+                        onFilterReset,
+                    }), ...(onRowClick !== undefined && { onRowClick }), ...(rowActions !== undefined && { rowActions }), ...(toolbarActionButtons !== undefined && { toolbarActions: toolbarActionButtons }), ...(emptyStateContent !== undefined && { emptyState: emptyStateContent }), ...(hideTitle === true && {
+                        scrollBody: true,
+                        screenPadding: false,
+                        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
+    // table to the panel height; `FillContainer` is this section's link in the
+    // fillHeight flex chain that Card's `options.fillHeight` continues (see
+    // render-edit.tsx). A platform primitive (not a raw `<div>`) because
+    // `renderer` stays DOM-free. Stacked (non-tabs) sections keep their own
+    // Section card and document-flow height since they render a visible title
+    // and aren't confined to a tab panel.
+    const bridges = _jsx(ReferenceFacetBridges, { specs: facetSpecs, onOptions: handleFacetOptions });
+    if (hideTitle) {
+        return (_jsxs(_Fragment, { children: [bridges, FillContainer !== undefined ? (_jsx(FillContainer, { ...(grow === true && { grow: true }), children: content })) : (content)] }));
+    }
+    return (_jsxs(_Fragment, { children: [bridges, _jsx(Section, { title: section.title, ...(actions !== undefined && { actions }), testId: `related-list-${section.title}`, children: content })] }));
+}

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

@@ -0,0 +1,22 @@
+import type { ReactNode } from "react";
+import type { usePrimitives } from "../primitives.js";
+import type { RenderEditAction } from "./render-edit-types.js";
+export declare function needsActionConfirm(action: RenderEditAction): boolean;
+export declare function RenderEditActionConfirmDialog({ action, open, onOpenChange, onConfirm, Dialog, }: {
+    readonly action: RenderEditAction;
+    readonly open: boolean;
+    readonly onOpenChange: (open: boolean) => void;
+    readonly onConfirm: () => void | Promise<void>;
+    readonly Dialog: ReturnType<typeof usePrimitives>["Dialog"];
+}): ReactNode;
+export declare function RenderEditActionButton({ action, iconOnly, hideIcon, Button, Dialog, onError, }: {
+    readonly action: RenderEditAction;
+    /** Group-level collapse (see `shouldRenderActionsIconOnly`) — only takes
+     *  effect when this action actually resolved an icon. */
+    readonly iconOnly?: boolean;
+    /** Record-header actions are text-only; the icon still shows when collapsed to icon-only. */
+    readonly hideIcon?: boolean;
+    readonly Button: ReturnType<typeof usePrimitives>["Button"];
+    readonly Dialog: ReturnType<typeof usePrimitives>["Dialog"];
+    readonly onError: (text: string | null) => void;
+}): ReactNode;

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

@@ -0,0 +1,43 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+// Same rule as RowActionWriteHandler: "danger" forces a confirm even
+// without an explicit confirm key — unless `confirmRequired` overrides it
+// (schema-driven navigate/drawer actions, where the target form is itself
+// the confirmation).
+export function needsActionConfirm(action) {
+    return action.confirm !== undefined || (action.confirmRequired ?? action.style === "danger");
+}
+export function RenderEditActionConfirmDialog({ action, open, onOpenChange, onConfirm, Dialog, }) {
+    return (_jsx(Dialog, { open: open, onOpenChange: onOpenChange, title: action.label, ...(action.confirm !== undefined && { description: action.confirm }), confirmLabel: action.confirmLabel ?? action.label, ...(action.style === "danger" && { variant: "danger" }), onConfirm: onConfirm, testId: `render-edit-action-${action.id}-dialog` }));
+}
+// One header action + its own busy/confirm state — same pattern as
+// render-list.tsx's ToolbarActionView (each RenderEditAction is
+// independently bound by the caller, there is no shared trigger pipeline
+// to hook into like the built-in onDelete/onSubmit paths have).
+export function RenderEditActionButton({ action, iconOnly = false, hideIcon = false, Button, Dialog, onError, }) {
+    const [busy, setBusy] = useState(false);
+    const [confirmOpen, setConfirmOpen] = useState(false);
+    const trigger = async () => {
+        setBusy(true);
+        onError(null);
+        try {
+            await action.onPress();
+        }
+        catch (e) {
+            onError(e instanceof Error ? e.message : String(e));
+        }
+        finally {
+            setBusy(false);
+        }
+    };
+    const variant = action.style ?? "secondary";
+    const showIconOnly = iconOnly && action.icon !== undefined;
+    return (_jsxs(_Fragment, { children: [_jsx(Button, { type: "button", variant: variant, loading: busy, ...(action.icon !== undefined && (!hideIcon || showIconOnly) && { icon: action.icon }), ...(showIconOnly && { size: "icon", ariaLabel: action.label }), onClick: () => {
+                    if (needsActionConfirm(action)) {
+                        setConfirmOpen(true);
+                    }
+                    else {
+                        void trigger();
+                    }
+                }, testId: `render-edit-action-${action.id}`, children: showIconOnly ? null : action.label }), _jsx(RenderEditActionConfirmDialog, { action: action, open: confirmOpen, onOpenChange: setConfirmOpen, onConfirm: trigger, Dialog: Dialog })] }));
+}

package/dist/components/render-edit-logic.d.ts

@@ -0,0 +1,6 @@
+import type { EditSectionViewModel, SubmitResult } from "@cosmicdrift/kumiko-headless";
+export declare function hasEditableSection(sections: readonly EditSectionViewModel[]): boolean;
+export declare function resolveExtensionEntityId(entityIdProp: string | null | undefined, vmId: string | null): string | null;
+export declare function shouldNotifyCaller(result: SubmitResult<unknown>, extensionsPersisted: boolean): boolean;
+export declare function hasIssueWithoutRenderedField(issuePaths: readonly string[], sections: readonly EditSectionViewModel[]): boolean;
+export declare function filterEditSections(sections: readonly EditSectionViewModel[], fieldsFilter: readonly string[] | undefined): readonly EditSectionViewModel[];

package/dist/components/render-edit-logic.js

@@ -0,0 +1,63 @@
+// Hides the Save button when no field is editable and no extension section
+// contributes to the composed form submit. Extensions that persist via their
+// own dispatcher writes must not opt in (fw#2359).
+// Explicit-positive per kind (653/1), not `s.kind !== "fields"` — a future
+// third EditSectionViewModel member would otherwise default to "editable"
+// without anyone deciding that on purpose.
+export function hasEditableSection(sections) {
+    return sections.some((s) => (s.kind === "extension" && s.contributesToFormSubmit) ||
+        (s.kind === "fields" && s.visible && s.fields.some((f) => !f.readOnly && f.visible)));
+}
+// Single source of truth for the extension-section entity-id. The section mount
+// and persistExtensions MUST resolve the same id — otherwise a section mounts
+// editable against one id (vm.id) while the persist step writes to (or skips)
+// another (null), silently dropping the user's input. An explicit `null` prop
+// forces "no entity" (no extension persistence); an omitted prop (undefined)
+// falls back to vm.id (= values["id"]), which the update form carries for the
+// existing row, so editing custom fields on that row actually persists.
+export function resolveExtensionEntityId(entityIdProp, vmId) {
+    return entityIdProp !== undefined ? entityIdProp : vmId;
+}
+// After a submit, decide whether to invoke the caller's onSubmit. The success
+// callback typically navigates away, which unmounts the extension-error banner.
+// Suppress the callback ONLY when the entity write succeeded but an extension-
+// section persist failed: the user must stay on the form to see the banner and
+// retry. Every other case still notifies the caller — entity failures and
+// validation blocks carry information the caller needs.
+export function shouldNotifyCaller(result, extensionsPersisted) {
+    return !(result.isSuccess && !extensionsPersisted);
+}
+// Matched on the first path segment (embedded-list rows are dotted, e.g. `tasks.2.title`).
+// No issues at all counts as unmatched, so the caller keeps the banner.
+export function hasIssueWithoutRenderedField(issuePaths, sections) {
+    if (issuePaths.length === 0)
+        return true;
+    const renderedFields = new Set(sections
+        .filter((s) => s.kind === "fields" && (s.visible || s.fields.length === 0))
+        .flatMap((s) => (s.kind === "fields" ? s.fields.filter((f) => f.visible) : []))
+        .map((f) => f.field));
+    return issuePaths.some((path) => !renderedFields.has(path.split(".")[0] ?? path));
+}
+// Extension, relatedList and writeForm sections skip the `fields` filter
+// (writeForm's fields belong to its own independent form, not the host's);
+// a `fields` section left with zero fields after filtering is dropped, not
+// rendered empty.
+export function filterEditSections(sections, fieldsFilter) {
+    if (fieldsFilter === undefined)
+        return sections;
+    const filterSet = new Set(fieldsFilter);
+    const result = [];
+    for (const section of sections) {
+        if (section.kind === "extension" ||
+            section.kind === "relatedList" ||
+            section.kind === "writeForm") {
+            result.push(section);
+            continue;
+        }
+        const fields = section.fields.filter((f) => filterSet.has(f.field));
+        if (fields.length === 0)
+            continue;
+        result.push({ ...section, fields });
+    }
+    return result;
+}

package/dist/components/render-edit-types.d.ts

@@ -0,0 +1,209 @@
+import type { EntityDefinition, EntityEditScreenDefinition, IconKey, RowAction, RowActionDrawer } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { FormSnapshot, FormValues, SubmitResult, Translate } from "@cosmicdrift/kumiko-headless";
+import type { ReactNode } from "react";
+import type * as z from "zod";
+export type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
+    readonly screen: EntityEditScreenDefinition;
+    readonly entity: EntityDefinition;
+    readonly featureName: string;
+    readonly initial: TValues;
+    /** Real entity id for extension-section mounts (set-value UI). Mount AND
+     *  persistExtensions resolve it via `resolveExtensionEntityId(entityIdProp,
+     *  vm.id)` — the same value, so the section doesn't mount editable against
+     *  one id while persist writes against another (or none at all).
+     *  Omitting (undefined) = fallback to `vm.id` (= values["id"]), which the
+     *  update form carries for the existing row. Explicit `null` = "no entity"
+     *  (create mode / no extension persistence). */
+    readonly entityId?: string | null;
+    /** Already-persisted extension values (e.g. `record.customFields`) for
+     *  extension-section mounts. Lets the section display its current stock
+     *  during edit. Only the update body provides this. */
+    readonly extensionInitialValues?: Readonly<Record<string, unknown>>;
+    /** Standard single-write submit path. Ignored when `customSubmit` is set
+     *  (configEdit screens dispatch multiple writes per submit, where a single
+     *  writeCommand makes no sense). */
+    readonly writeCommand?: string;
+    /** Override for the submit pipeline. When set, runs controller.validate()
+     *  and then customSubmit(snapshot) instead of controller.submit(). On
+     *  success the form state rebases so that isUnchanged/isDirty become false
+     *  again — without that, save button and banner stay stale. */
+    readonly customSubmit?: (snapshot: FormSnapshot<TValues>) => Promise<SubmitResult<unknown>>;
+    readonly translate?: Translate;
+    readonly ctx?: TCtx;
+    readonly schema?: z.ZodType;
+    readonly onSubmit?: (result: SubmitResult<unknown>) => void;
+    readonly payloadMode?: "values" | "changes";
+    readonly buildPayload?: (snapshot: FormSnapshot<TValues>) => unknown;
+    /** Prefix to strip from server validation issue paths before mapping them
+     *  onto form fields — see SubmitConfig.serverFieldPathPrefix. Only needed
+     *  when buildPayload nests the form values under a key. */
+    readonly serverFieldPathPrefix?: string;
+    readonly onDelete?: () => Promise<void> | void;
+    readonly onCancel?: () => void;
+    readonly onReload?: () => void;
+    /** Fires when the form gains or loses unsaved input (field changes or a
+     *  dirty extension section). Lets a host such as a drawer guard closing. */
+    readonly onDirtyChange?: (dirty: boolean) => void;
+    /** Copy-link action (issue #912) — only set in update mode (create mode
+     *  has no entity id yet, hence no permalink). The callback is already fully
+     *  bound (URL building + clipboard happen outside, in
+     *  `@cosmicdrift/kumiko-renderer-web`'s RoutedScreen — this platform-neutral
+     *  package must not touch `navigator`/`window`, see
+     *  guard-renderer-boundaries). undefined = no button. */
+    readonly onCopyLink?: () => Promise<void> | void;
+    /** Header action buttons, rendered before the built-in copy-link/
+     *  delete/cancel/save controls. Each callback is already fully
+     *  bound (screen-type/nav/dispatcher resolution happens in the caller,
+     *  same split as `onCopyLink`) — RenderEdit only wires the button, its
+     *  busy state and its confirm dialog. */
+    readonly actions?: readonly RenderEditAction[];
+    /** Opens a relatedList section row's drawer-kind action (fw#2710).
+     *  RenderEdit has no `schema` to resolve the target actionForm itself —
+     *  the caller (ProjectionDetailBody, which does have schema) supplies the
+     *  opener and owns the actual Drawer state/rendering. Only projectionDetail
+     *  passes this — the boot validator rejects relatedList sections on every
+     *  other screen type that shares this layout. */
+    readonly onRelatedListDrawerAction?: (action: RowActionDrawer, initialValues: Readonly<Record<string, unknown>> | undefined) => void;
+    /** i18n key for the submit button. Default: "kumiko.actions.save".
+     *  Action forms (tier 2.7d) pass their screen.submitLabel here so that
+     *  "Save" can be replaced by domain-specific strings ("Approve" /
+     *  "Dispatch" / etc.). */
+    readonly submitLabel?: string;
+    /** Visual style of the submit button (actionForm `submitStyle`). Default "primary". */
+    readonly submitVariant?: "primary" | "danger";
+    /** Context box above the drawer form (title + optional subtitle, already resolved). */
+    readonly summary?: {
+        readonly title: string;
+        readonly subtitle?: string;
+    };
+    /** Per-field extra content inline after the label (e.g.
+     *  ConfigSourceBadge). Called with the field name, returns a ReactNode or
+     *  undefined. */
+    readonly labelAppendix?: (fieldName: string) => ReactNode | undefined;
+    /** Per-field extra content below the input (e.g. ConfigCascadeView).
+     *  Called with the field name, returns a ReactNode or undefined. */
+    readonly fieldAppendix?: (fieldName: string) => ReactNode | undefined;
+    /** Controlled mode (issue #1887): fires on every values-snapshot change
+     *  (typing, `patch(...)` from outside) with the current values. `changes`
+     *  is the delta against the initial values — same semantics as
+     *  `payloadMode: "changes"` — so a caller never overwrites unseen fields.
+     *  `valid` is a pure dry-run parse against `schema` (not a
+     *  `controller.validate()` call), so it does not paint field errors into
+     *  the UI and can diverge from the currently rendered `snapshot.errors` —
+     *  always `true` without `schema`. A caller that patches a fresh object
+     *  reference on every call must not do so unconditionally: `setValues` is
+     *  a no-op when the merged value is reference-equal to the current one,
+     *  so only a converging patch settles instead of looping. Without this
+     *  prop, existing behavior is unchanged. `onControlsReady` is guaranteed
+     *  to have already fired by the time the mount-time `onChange` call
+     *  happens, so a caller patching dependent fields from inside `onChange`
+     *  never has to guard against `controls` being undefined. */
+    readonly onChange?: (state: RenderEditChangeState<TValues>) => void;
+    /** Controlled mode (issue #1887): called once after mount, hands the
+     *  caller `patch`/`validate`/`getValues` bound to this RenderEdit
+     *  instance — addressable from outside without a remount. `patch` merges
+     *  only the given keys (existing `controller.setValues` semantics),
+     *  values on unmentioned fields stay untouched. `validate` runs without a
+     *  write and reports field issues via `snapshot.errors` on the field
+     *  itself rather than as a summary banner. Without this prop, existing
+     *  behavior is unchanged. */
+    readonly onControlsReady?: (controls: RenderEditControls<TValues>) => void;
+    /** Renders only these fields (by `field` name from the layout) — section
+     *  order, title, and visibility still come from the layout, so the caller
+     *  doesn't duplicate its shape. A section with no fields left after
+     *  filtering is dropped entirely (not rendered empty). Submit validation
+     *  is scoped to the actually-rendered fields the same way — a required
+     *  field outside this list doesn't block submit. Omitting this prop keeps
+     *  unchanged behavior. Read once at mount for `controller.submit()`'s
+     *  validation scope (the underlying `useForm` controller is mount-lived);
+     *  rendering and `controls.validate()` do stay reactive to later changes. */
+    readonly fields?: readonly string[];
+    /** Locked state (issue #1896): every rendered field and the submit button
+     *  go visibly inactive, no write possible. For cases where input becomes
+     *  moot — e.g. Solon's editor pointing at an existing record instead of
+     *  creating a new one. Extension sections are out of scope: RenderEdit has
+     *  no way to force-disable an arbitrary registered component. Omitting
+     *  this prop keeps unchanged behavior.
+     *
+     *  ponytail: direct-consumer only — kumiko-screen.tsx's RenderEdit call
+     *  sites pass explicit prop lists without a spread and never forward
+     *  `disabled`, so a screen-driven app can't set the locked state today.
+     *  Upgrade path if that's needed: thread a screen-spec flag through to
+     *  `EntityEditCreateBody`/`EntityEditEditBody`. */
+    readonly disabled?: boolean;
+    /** Renders the fields without RenderEdit's own action bar (save, cancel,
+     *  delete, copy-link). For hosts that put those controls into their own
+     *  chrome — a drawer footer, a wizard shell — and drive the write through
+     *  `onControlsReady`'s `submit`. Omitting this prop keeps unchanged
+     *  behavior. */
+    readonly hideActions?: boolean;
+    /** "form" (default) — every field renders as its Input widget, disabled
+     *  when `field.readOnly`, unchanged behavior. "text" renders a
+     *  `field.readOnly` field as plain text instead of a disabled Input
+     *  (ProjectionDetailBody's read view, fw#2245) — editable fields are
+     *  unaffected either way, so this only changes forms that already have
+     *  readOnly fields. */
+    readonly valueDisplay?: "form" | "text";
+    /** Suppresses every section's own title (fields-section header, relatedList
+     *  Section title) AND the form's own top-level title/subtitle — for a host
+     *  that already renders that label itself elsewhere (e.g. a tab strip
+     *  whose label duplicates it, or a page-level header above RenderEdit).
+     *  Without this, the form's title (`screen:<id>.title` / `screen.id`)
+     *  renders unconditionally regardless of section-level suppression — a
+     *  host relying on this prop to fully own the heading otherwise sees a
+     *  redundant title above its content. Omitting this prop keeps unchanged
+     *  behavior. */
+    readonly hideSectionTitles?: boolean;
+    /** Screen body fills the shell height: the form gets `fillHeight` and
+     *  `stickyActions` (sections scroll, footer pinned). Set by KumikoScreen for
+     *  screens with `fillHeight !== false`; dialogs and other embedded hosts
+     *  omit it and keep document-flow height. */
+    readonly fillScreenHeight?: boolean;
+    /** Extra content rendered above the card, sharing its left padding and
+     *  width — for a host with its own header region (title/metrics/tabs)
+     *  that would otherwise render as unpadded siblings before RenderEdit.
+     *  Omitting this prop keeps unchanged behavior. */
+    readonly headerRegion?: ReactNode | ((headerSlot: ReactNode | undefined) => ReactNode);
+    /** resolves an `EditFieldsSection`/`EditExtensionSection`/
+     *  `EditRelatedListSection`/`EditWriteFormSection`'s own `actions` into
+     *  already-bound buttons, rendered in that section's title row — same
+     *  split as `onCopyLink`/header `actions`: RenderEdit has no dispatcher/nav
+     *  context of its own, so the caller (which does) resolves each RowAction
+     *  against the record being edited. Returns `undefined`/`[]` to render no
+     *  actions for that section. */
+    readonly buildSectionActions?: (actions: readonly RowAction[]) => readonly RenderEditAction[] | undefined;
+};
+export type RenderEditAction = {
+    readonly id: string;
+    readonly label: string;
+    readonly onPress: () => void | Promise<void>;
+    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;
+    /** Resolved icon (author `RowAction.icon` or the id-derived default) —
+     *  drives both the icon-left-of-text render and the icon-only collapse
+     *  rule (see `shouldRenderActionsIconOnly`). */
+    readonly icon?: IconKey;
+};
+export type RenderEditChangeState<TValues extends FormValues> = {
+    readonly values: TValues;
+    readonly changes: Partial<TValues>;
+    readonly dirty: boolean;
+    readonly valid: boolean;
+    readonly submitting: boolean;
+};
+export type RenderEditControls<TValues extends FormValues> = {
+    readonly patch: (partial: Partial<TValues>) => void;
+    readonly validate: () => boolean;
+    readonly getValues: () => TValues;
+    /** Runs the same pipeline the built-in save button runs: validation,
+     *  `customSubmit`/`writeCommand`, extension-section persistence, draft
+     *  discard, state rebase. Unlike the button it carries no unchanged-form
+     *  guard — a host showing a pre-filled proposal must be able to accept it
+     *  untouched. */
+    readonly submit: () => Promise<void>;
+};

package/dist/components/render-edit-types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,6 @@
+import type { FormValues } from "@cosmicdrift/kumiko-headless";
+import type { RenderEditProps } from "./render-edit-types.js";
+export type { RenderEditAction, RenderEditChangeState, RenderEditControls, RenderEditProps, } from "./render-edit-types.js";
+import { type ReactNode } from "react";
+export declare const PATCH_DRAFT_SAVE_DEBOUNCE_MS = 500;
+export declare function RenderEdit<TValues extends FormValues, TCtx = unknown>(props: RenderEditProps<TValues, TCtx>): ReactNode;