@cosmicdrift/kumiko-renderer 0.328.0 → 0.329.0

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

@@ -0,0 +1,117 @@
+import type { EntityDefinition, EntityListScreenDefinition, IconKey } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { ListRowViewModel, Translate } from "@cosmicdrift/kumiko-headless";
+import { type ReactNode } from "react";
+import type { ListSort } from "../hooks/use-list-url-state.js";
+import { type DataTableDateRangeFacet, type DataTableFacet, type DataTableRowAction, type DataTableRowActionMode } from "../primitives.js";
+export type RenderListProps = {
+    readonly screen: EntityListScreenDefinition;
+    readonly entity: EntityDefinition;
+    readonly rows: readonly Readonly<Record<string, unknown>>[];
+    readonly featureName: string;
+    readonly translate?: Translate;
+    readonly onRowClick?: (row: ListRowViewModel) => void;
+    /** Override der Default-Empty-Box. Wenn gesetzt, wird der Auto-CTA
+     *  via `onCreate` ignoriert — Caller-Inhalt gewinnt. */
+    readonly emptyState?: ReactNode;
+    /** Setzt einen "+ Neu" Button in die Toolbar UND dient als CTA in
+     *  der Default-Empty-Box. Caller liefert die Action selber (z. B.
+     *  navigate auf den Edit-Screen). */
+    readonly onCreate?: () => void;
+    /** Label für den + Neu Button. Default kommt aus dem i18n-Bundle
+     *  (`kumiko.actions.create`). Caller kann durch eigenen String
+     *  überschreiben. */
+    readonly createLabel?: string;
+    /** Aktiviert ein Search-Input in der Toolbar. Server-side Filter
+     *  via Caller's onSearchChange — RenderList filtert NICHT lokal. */
+    readonly searchable?: boolean;
+    /** Placeholder für das Search-Input. Default kommt aus dem i18n-
+     *  Bundle (`kumiko.list.search-placeholder`). */
+    readonly searchPlaceholder?: string;
+    /** Hint at the left of the toolbar when there is no search box (already translated). */
+    readonly description?: string;
+    /** Plural-forms key for the footer count noun; default is the entity's `:noun` convention key. */
+    readonly itemNounKey?: string;
+    /** Aktueller Search-Term (vom URL-State / Parent). RenderList puffert
+     *  Tipps lokal mit 300ms Debounce, bevor onSearchChange gefeuert
+     *  wird — sonst macht jeder Tastendruck einen Server-Roundtrip. */
+    readonly searchValue?: string;
+    /** Wird gerufen wenn der debounced Search-Term sich ändert. Caller
+     *  setzt damit URL-State (?<id>.q=…) und triggert ein refetch. */
+    readonly onSearchChange?: (next: string) => void;
+    /** Aktuelle Sortierung (oder null = Server-Default-Order). */
+    readonly sort?: ListSort | null;
+    /** Wird gerufen mit dem nächsten Sort-State nach einem Header-Klick. */
+    readonly onSortChange?: (next: ListSort | null) => void;
+    /** Pager-Props für pagination="pages". Wenn undefined, kein Pager-
+     *  UI — Default oder infinite-Mode. KumikoScreen liefert das je nach
+     *  screen.pagination. */
+    readonly pager?: {
+        readonly page: number;
+        readonly limit: number;
+        readonly total: number;
+        readonly onPageChange: (next: number) => void;
+    };
+    /** Infinite-Scroll-Wiring für pagination="infinite". KumikoScreen
+     *  hält accumulated rows + cursor, RenderList reicht die Callbacks
+     *  einfach durch an DataTable. */
+    readonly onReachEnd?: () => void;
+    readonly loadingMore?: boolean;
+    readonly hasMore?: boolean;
+    /** Pro-Row-Aktionen — Resolved-Form (KumikoScreen baut das aus
+     *  EntityListScreenDefinition.rowActions: handler-QN → dispatcher-Call,
+     *  i18n-Keys → translated Strings). */
+    readonly rowActions?: readonly DataTableRowAction[];
+    /** How the row-action column renders (see `DataTableProps.rowActionMode`).
+     *  KumikoScreen derives it from the actions themselves; without it the
+     *  DataTable falls back to its adaptive default. */
+    readonly rowActionMode?: DataTableRowActionMode;
+    /** Toolbar-Aktionen im List-Header — Resolved-Form (KumikoScreen baut
+     *  das aus EntityListScreenDefinition.toolbarActions: navigate-target
+     *  → useNav, handler-QN → dispatcher-Call). RenderList rendert die
+     *  Buttons rechts in der Toolbar, vor "+ Neu". */
+    readonly toolbarActions?: readonly ToolbarActionButton[];
+    /** Faceted-Filter-Dropdowns — KumikoScreen baut sie aus den filterable
+     *  select/boolean-Feldern; RenderList reicht sie an die DataTable durch. */
+    readonly filterFacets?: readonly DataTableFacet[];
+    /** Aktuell gewählte Facet-Werte je Feld (vom URL-State). */
+    readonly filterValues?: Readonly<Record<string, readonly string[]>>;
+    /** Toggle eines Facet-Werts (URL-State setzen + refetch). */
+    readonly onFilterChange?: (field: string, values: readonly string[]) => void;
+    /** Reset aller aktiven Facets. */
+    readonly onFilterReset?: () => void;
+    /** Time-range filters (fw#3104) — forwarded to the DataTable. */
+    readonly dateRangeFacets?: readonly DataTableDateRangeFacet[];
+    /** One bound changed (set URL state + refetch). */
+    readonly onDateRangeChange?: (field: string, bound: "from" | "to", value: string) => void;
+    /** Forwarded to `DataTableProps.chromeless` — drops the table's own card
+     *  frame for a host that already provides one (relatedList in a tabs-mode
+     *  section, fw#2722). Default false. */
+    readonly chromeless?: boolean;
+    /** Forwarded to `DataTableProps.scrollBody` — bounds the table height and
+     *  scrolls rows internally instead of growing the page (relatedList in a
+     *  tabs-mode section, fw#2722). Default false. */
+    readonly scrollBody?: boolean;
+    /** Forwarded to `DataTableProps.screenPadding` — `true`: the table carries
+     *  the shared screen padding because it is the screen body (entityList/
+     *  projectionList, fw#2640). Explicit `false`: no padding at all — the
+     *  host already pads its own children (relatedList in a tabs-mode Card,
+     *  fw#3234). Omitted: legacy `p-6` fallback for a standalone table with no
+     *  padded host. */
+    readonly screenPadding?: boolean;
+};
+export type ToolbarActionButton = {
+    readonly id: string;
+    readonly label: string;
+    readonly style?: "primary" | "secondary" | "danger";
+    readonly confirm?: string;
+    readonly confirmLabel?: string;
+    /** Overrides the default "danger implies a confirm dialog" rule. Schema-driven
+     *  navigate/drawer actions set it to false: the colour marks the action as
+     *  destructive, but the target form is the confirmation. */
+    readonly confirmRequired?: boolean;
+    readonly onTrigger: () => Promise<void> | void;
+    /** Id-derived default icon (ACTION_ICON_BY_ID in kumiko-screen.tsx) —
+     *  ToolbarAction has no author-declared icon field, unlike RowAction. */
+    readonly icon?: IconKey;
+};
+export declare function RenderList(props: RenderListProps): ReactNode;

package/dist/components/render-list.js

@@ -0,0 +1,232 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { computeListViewModel } from "@cosmicdrift/kumiko-headless";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { extensionSectionName, useExtensionSectionComponent } from "../app/extension-sections.js";
+import { useReferenceLookup } from "../hooks/use-reference-lookup.js";
+import { useTranslation } from "../i18n.js";
+import { usePageHeaderSlotAvailable } from "../page-header-slot.js";
+import { shouldRenderActionsIconOnly, usePrimitives, } from "../primitives.js";
+const SEARCH_DEBOUNCE_MS = 300;
+export function RenderList(props) {
+    const { screen, entity, rows, featureName, translate: translateProp, onRowClick, emptyState, onCreate, createLabel, searchable = false, searchPlaceholder, description, itemNounKey, searchValue, onSearchChange, sort, onSortChange, pager, onReachEnd, loadingMore, hasMore, rowActions, rowActionMode, toolbarActions, filterFacets, filterValues, onFilterChange, onFilterReset, dateRangeFacets, onDateRangeChange, chromeless, scrollBody, screenPadding, } = props;
+    // Wie RenderEdit: Translate-Fallback aus dem i18next-Context, sonst
+    // wären Column-Header raw i18n-Keys.
+    const t = useTranslation();
+    const translate = translateProp ?? t;
+    const { DataTable, Button, Dialog, Input, Text, Banner, PageHeader } = usePrimitives();
+    const pageHeaderSlotAvailable = usePageHeaderSlotAvailable();
+    const createInPageHeader = onCreate !== undefined && PageHeader !== undefined && pageHeaderSlotAvailable;
+    // Local search buffer + debounce. External changes (browser back,
+    // cross-component reset) are mirrored back; typing only fires
+    // onSearchChange after 300ms without further keystrokes.
+    const [localQ, setLocalQ] = useState(searchValue ?? "");
+    // Sync during render, not in a useEffect: the passive effect also fires on
+    // mount and can flush after a keystroke landing in the same commit,
+    // resetting localQ and swallowing the input.
+    const [syncedSearchValue, setSyncedSearchValue] = useState(searchValue);
+    if (searchValue !== syncedSearchValue) {
+        setSyncedSearchValue(searchValue);
+        setLocalQ(searchValue ?? "");
+    }
+    useEffect(() => {
+        if (onSearchChange === undefined)
+            return;
+        if (localQ === (searchValue ?? ""))
+            return;
+        const timer = setTimeout(() => onSearchChange(localQ), SEARCH_DEBOUNCE_MS);
+        return () => clearTimeout(timer);
+    }, [localQ, searchValue, onSearchChange]);
+    const vm = useMemo(() => computeListViewModel({ screen, entity, rows, translate, featureName }), [screen, entity, rows, translate, featureName]);
+    // Tier 2.7e-4: Reference-Field-Eagerload via Bridge-Component-Pattern.
+    // Hooks-Rule-Konflikt: pro reference-Spalte muss useReferenceLookup
+    // gerufen werden, aber die Anzahl varriiert per Schema. Lösung —
+    // ReferenceLookupBridge-Komponenten pro Spalte gemountet, die ihre
+    // Map über onMap-Callback in einen lokalen State veröffentlichen.
+    // Anzahl der Hook-Calls pro Bridge-Component ist konstant (1), und
+    // React verwaltet die mounted/unmounted Lifecycles beim Schema-
+    // Wechsel über die key-Property automatisch.
+    const referenceColumns = useMemo(() => vm.columns
+        .filter((c) => c.type === "reference" && c.refEntity !== undefined)
+        .map((c) => ({
+        field: c.field,
+        refEntity: c.refEntity ?? "",
+        // Tier 2.7e Cross-Feature: refFeature kommt aus parseRefTarget
+        // im ViewModel (default = current featureName).
+        refFeature: c.refFeature ?? featureName,
+        labelField: c.refLabelField ?? "id",
+    })), [vm.columns, featureName]);
+    const [referenceLookups, setReferenceLookups] = useState({});
+    const handleLookupMap = useCallback((field, map) => {
+        setReferenceLookups((prev) => {
+            // skip-update wenn die Map identisch ist (Render-Loop-Schutz —
+            // Bridge-Component re-rendert sonst und schickt die gleiche Map
+            // wieder rein bis React in eine Endlosschleife geht).
+            if (prev[field] === map)
+                return prev;
+            return { ...prev, [field]: map };
+        });
+    }, []);
+    const enrichedColumns = useMemo(() => {
+        if (referenceColumns.length === 0)
+            return vm.columns;
+        return vm.columns.map((col) => {
+            if (col.type !== "reference")
+                return col;
+            // Author-deklarierter Renderer übersteuert immer — Default greift
+            // nur wenn keiner gesetzt ist.
+            if (col.renderer !== undefined)
+                return col;
+            const map = referenceLookups[col.field];
+            const labelField = col.refLabelField ?? "id";
+            const renderer = (value, row) => {
+                // Tier 2.7e Server-Eagerload: wenn der Server _refs mit-
+                // schickt, lesen wir den Display-Wert direkt aus der
+                // resolved Row — kein Roundtrip durch die Bridge-Map nötig
+                // und keine limit:200-Constraint. EagerloadedRow-Type aus
+                // @cosmicdrift/kumiko-framework/db pinnt die Form von _refs.
+                const eagerloadedRow = row;
+                const resolved = eagerloadedRow?._refs?.[col.field];
+                if (Array.isArray(resolved) && resolved.length > 0) {
+                    return resolved.map((r) => String(r[labelField] ?? r["id"] ?? "")).join(", ");
+                }
+                if (resolved !== undefined && !Array.isArray(resolved)) {
+                    const single = resolved; // @cast-boundary render-helper
+                    return String(single[labelField] ?? single["id"] ?? "");
+                }
+                // Renderer-Side-Fallback (kein Server-Eagerload aktiv).
+                if (Array.isArray(value)) {
+                    if (value.length === 0)
+                        return "—";
+                    return value.map((v) => map?.get(String(v)) ?? String(v)).join(", ");
+                }
+                if (value === null || value === undefined || value === "")
+                    return "—";
+                const idStr = String(value);
+                return map?.get(idStr) ?? idStr;
+            };
+            return { ...col, renderer };
+        });
+    }, [vm.columns, referenceColumns, referenceLookups]);
+    const enrichedVm = useMemo(() => ({
+        ...vm,
+        columns: enrichedColumns,
+    }), [vm, enrichedColumns]);
+    // i18n-Defaults für Toolbar/Empty-State Strings — Caller kann jeden
+    // einzeln per Prop überschreiben, sonst kommen die Framework-Bundles
+    // (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");
+    const nounKey = itemNounKey ?? `${featureName}:entity:${screen.entity}:noun`;
+    const itemNoun = (itemNounKey !== undefined || !screen.entity.startsWith("__")) &&
+        translate(nounKey, { count: 2 }) !== nounKey
+        ? (count) => translate(nounKey, { count })
+        : undefined;
+    const toolbarStart = searchable ? (_jsx(Input, { kind: "text", id: "render-list-search", name: "search", value: localQ, onChange: setLocalQ, placeholder: effectiveSearchPlaceholder })) : undefined;
+    // Toolbar-End-Slot: optionaler Header-Slot (z.B. Cap-Counter, links im
+    // rechten Cluster) + Toolbar-Actions (List-Header-Buttons aus dem Schema)
+    // + optional "+ Neu" am rechten Edge. Der Header-Slot lebt IN der Toolbar-
+    // Zeile (gleicher Card-Rahmen), nicht als loser Text über dem Screen-Titel
+    // (Bug-Bash 3 #12). Reihenfolge = Array-Reihenfolge (Schema-deklariert),
+    // "+ Neu" zuletzt weil das die häufigste/auffälligste CTA ist.
+    const hasToolbarActions = toolbarActions !== undefined && toolbarActions.length > 0;
+    const hasHeaderSlot = screen.slots?.header !== undefined;
+    const toolbarIconOnly = hasToolbarActions && shouldRenderActionsIconOnly(toolbarActions);
+    const createButton = onCreate !== undefined ? (_jsx(Button, { variant: "primary", icon: "plus", onClick: onCreate, testId: "render-list-create", className: "px-3.5", children: effectiveCreateLabel })) : undefined;
+    const toolbarEnd = hasHeaderSlot || hasToolbarActions || (onCreate !== undefined && !createInPageHeader) ? (_jsxs(_Fragment, { children: [hasHeaderSlot && _jsx(ListHeaderSlotMount, { screen: screen }), hasToolbarActions &&
+                toolbarActions.map((a) => (_jsx(ToolbarActionView, { action: a, iconOnly: toolbarIconOnly, Button: Button, Dialog: Dialog, Banner: Banner }, a.id))), !createInPageHeader && createButton] })) : undefined;
+    // Empty-State: Default zeigt Heading + Description + optional CTA-
+    // Button. Caller kann via emptyState-Prop komplett überschreiben.
+    // Wenn weder onCreate noch ein Override gegeben ist, fällt die
+    // DataTable auf den DataTable-Default zurück (`kumiko.list.no-entries`).
+    const composedEmptyState = emptyState ??
+        (onCreate !== undefined ? (_jsxs(_Fragment, { children: [_jsx(Text, { children: translate("kumiko.list.empty.title") }), _jsx(Text, { variant: "small", children: translate("kumiko.list.empty.hint") }), _jsx(Button, { variant: "primary", icon: "plus", onClick: onCreate, testId: "render-list-empty-create", children: effectiveCreateLabel })] })) : undefined);
+    // Title-Resolution: ein konventioneller i18n-Key `screen:<id>.title`.
+    // Wenn das Bundle den Key kennt, schöner Titel; sonst kommt der
+    // screenId selber raus (kein "Untitled"-Fallback — der App-Dev sieht
+    // dann dass die Übersetzung fehlt).
+    const titleKey = `screen:${screen.id}.title`;
+    const resolvedTitle = translate(titleKey);
+    const toolbarTitle = resolvedTitle === titleKey ? screen.id : resolvedTitle;
+    // ListSort = DataTableSort (use-list-url-state aliased) — kein Cast nötig.
+    return (_jsxs(_Fragment, { children: [createInPageHeader && PageHeader !== undefined && _jsx(PageHeader, { actions: createButton }), referenceColumns.map((rc) => (_jsx(ReferenceLookupBridge, { field: rc.field, refEntity: rc.refEntity, labelField: rc.labelField, featureName: rc.refFeature, onMap: handleLookupMap }, rc.field))), _jsx(DataTable, { columns: enrichedVm.columns, rows: enrichedVm.rows, toolbarTitle: toolbarTitle, ...(onRowClick !== undefined && { onRowClick }), ...(composedEmptyState !== undefined && { emptyState: composedEmptyState }), ...(toolbarStart !== undefined && { toolbarStart }), ...(description !== undefined && !searchable && { toolbarDescription: description }), ...(toolbarEnd !== undefined && { toolbarEnd }), ...(sort !== undefined && { sort }), ...(onSortChange !== undefined && { onSortChange }), ...(pager !== undefined && { pager }), ...(onReachEnd !== undefined && { onReachEnd }), ...(loadingMore !== undefined && { loadingMore }), ...(hasMore !== undefined && { hasMore }), ...(itemNoun !== undefined && { itemNoun }), ...(rowActions !== undefined && { rowActions }), ...(rowActionMode !== undefined && { rowActionMode }), ...(filterFacets !== undefined && { filterFacets }), ...(filterValues !== undefined && { filterValues }), ...(onFilterChange !== undefined && { onFilterChange }), ...(onFilterReset !== undefined && { onFilterReset }), ...(dateRangeFacets !== undefined && { dateRangeFacets }), ...(onDateRangeChange !== undefined && { onDateRangeChange }), ...(chromeless !== undefined && { chromeless }), ...(scrollBody !== undefined && { scrollBody }), ...(screenPadding !== undefined && { screenPadding }), testId: "render-list-table" })] }));
+}
+// Header-Slot in der Listen-Toolbar (toolbarEnd): `screen.slots.header` ist
+// eine PlatformComponent (`{ react: { __component: "X" } }`), aufgelöst über
+// dieselbe ExtensionSectionsProvider-Registry wie entityEdit-Sections.
+// entityId ist null (Listen-Kontext, keine Row); die Component lädt ihre
+// Daten selbst (z.B. ein Cap-Counter aus einer usage-Query). Eigene
+// Component wegen Rules-of-Hooks — useExtensionSectionComponent darf nicht
+// konditional im RenderList-Body laufen.
+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) {
+            // biome-ignore lint/suspicious/noConsole: dev-warning für Setup-Fehler
+            console.warn(`[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 });
+}
+// Tier 2.7e-4: Bridge-Component pro reference-Spalte. Mounted für jede
+// Spalte einmal, ruft useReferenceLookup unconditional (Hook-Rules
+// happy), und published die Map über onMap an den Parent. React
+// verwaltet das Mounting/Unmounting beim Schema-Wechsel über die
+// key-Prop im map-Loop des Parents.
+function ReferenceLookupBridge({ field, refEntity, labelField, featureName, onMap, }) {
+    const lookup = useReferenceLookup(featureName, refEntity, labelField);
+    // useEffect statt direktem call damit setState außerhalb des Render-
+    // Pfads passiert (sonst React-Warning "Cannot update a component
+    // while rendering a different component").
+    useEffect(() => {
+        onMap(field, lookup.map);
+    }, [field, lookup.map, onMap]);
+    return null;
+}
+// ToolbarActionView — pro Toolbar-Action ein Button (+ Confirm-Dialog
+// wenn confirm gesetzt). Same Pattern wie RowAction (Inline-Variante)
+// aber ohne row-Context. busy-State während async onTrigger; Dialog
+// öffnet sich vor dem Trigger wenn confirm/danger gesetzt.
+function ToolbarActionView({ action, iconOnly = false, Button, Dialog, Banner, }) {
+    const [busy, setBusy] = useState(false);
+    const [confirmOpen, setConfirmOpen] = useState(false);
+    // Toolbar-Actions haben (anders als rowActions, die über die DataTable-
+    // Primitive laufen) keine Toast-Primitive zur Verfügung — ein inline
+    // Error-Banner ist der surfacing-Pfad hier. Gleicher Grund wie bei
+    // rowActions (Prod-Bug 2026-06-07): ein verschlucktes Failure-Result
+    // sieht für den User wie "nichts passiert" aus.
+    const [errorText, setErrorText] = useState(null);
+    const trigger = async () => {
+        setBusy(true);
+        setErrorText(null);
+        try {
+            await action.onTrigger();
+        }
+        catch (e) {
+            setErrorText(e instanceof Error ? e.message : String(e));
+        }
+        finally {
+            setBusy(false);
+        }
+    };
+    const variant = action.style ?? "secondary";
+    const needsConfirm = action.confirm !== undefined || (action.confirmRequired ?? action.style === "danger");
+    const showIconOnly = iconOnly && action.icon !== undefined;
+    return (_jsxs(_Fragment, { children: [_jsx(Button, { variant: variant, loading: busy, ...(action.icon !== undefined && { icon: action.icon }), size: showIconOnly ? "icon" : "sm", ...(showIconOnly && { ariaLabel: action.label }), onClick: () => {
+                    if (needsConfirm) {
+                        setConfirmOpen(true);
+                    }
+                    else {
+                        void trigger();
+                    }
+                }, testId: `render-list-toolbar-action-${action.id}`, children: showIconOnly ? null : action.label }), _jsx(Dialog, { open: confirmOpen, onOpenChange: setConfirmOpen, title: action.label, ...(action.confirm !== undefined && { description: action.confirm }), confirmLabel: action.confirmLabel ?? action.label, ...(action.style === "danger" && { variant: "danger" }), onConfirm: trigger, testId: `render-list-toolbar-action-${action.id}-dialog` }), errorText !== null && (_jsx(Banner, { variant: "error", testId: `render-list-toolbar-action-${action.id}-error`, children: errorText }))] }));
+}

package/dist/components/write-form-section.d.ts

@@ -0,0 +1,17 @@
+import type { EditWriteFormSectionViewModel, Translate } from "@cosmicdrift/kumiko-headless";
+import { type ReactNode } from "react";
+export type WriteFormSectionProps = {
+    readonly section: EditWriteFormSectionViewModel;
+    readonly featureName: string;
+    readonly translate?: Translate;
+    readonly hideTitle?: boolean;
+    /** Fired after a successful submit — projectionDetail reloads its own
+     *  record (a new one now exists) via a full RenderEdit remount, see
+     *  ProjectionDetailBody's reloadNonce/key in kumiko-screen.tsx. */
+    readonly onSubmitted: () => void;
+    /** section.actions, already resolved into buttons by the caller —
+     *  rendered alongside (before) the section's own submit button in the
+     *  title-row actions slot. */
+    readonly actions?: ReactNode;
+};
+export declare function WriteFormSection({ section, featureName, translate, hideTitle, onSubmitted, actions, }: WriteFormSectionProps): ReactNode;

package/dist/components/write-form-section.js

@@ -0,0 +1,104 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { I18N_KEY_PARAM } from "@cosmicdrift/kumiko-headless";
+import { useMemo, useState } from "react";
+import * as z from "zod";
+import { REQUIRED_FIELD_I18N_KEY } from "../app/form-schema.js";
+import { dispatcherErrorText } from "../app/write-failed-error.js";
+import { useForm } from "../hooks/use-form.js";
+import { useTranslation } from "../i18n.js";
+import { usePrimitives } from "../primitives.js";
+import { GridCellForField } from "./grid-cell-for-field.js";
+// Same "has a value" rule as buildFormSchema's isPresent (app/form-schema.ts)
+// — duplicated because that helper walks raw EditFieldSpec + EntityDefinition,
+// unavailable here: this section only ever sees computeEditViewModel's
+// already-resolved EditFieldViewModel[] (required/readOnly/visible are plain
+// booleans by the time render-edit.tsx hands the section to this component).
+function isPresent(value) {
+    if (value === undefined || value === null || value === "")
+        return false;
+    if (Array.isArray(value) && value.length === 0)
+        return false;
+    return true;
+}
+function buildWriteFormSchema(fields) {
+    return z
+        .object({})
+        .passthrough()
+        .superRefine((values, ctx) => {
+        const record = values;
+        for (const field of fields) {
+            if (field.readOnly || !field.visible || !field.required)
+                continue;
+            if (isPresent(record[field.field]))
+                continue;
+            ctx.addIssue({
+                code: "custom",
+                path: [field.field],
+                message: `"${field.field}" is required.`,
+                params: { [I18N_KEY_PARAM]: REQUIRED_FIELD_I18N_KEY },
+            });
+        }
+    });
+}
+// A self-persisting form section for projectionDetail (see
+// EditWriteFormSection's doc). Deliberately NOT a nested <RenderEdit> — that
+// would render a second, invalid nested <form> inside the host's own form
+// element — so this mounts its own independent useForm() controller and
+// submits via a plain button click instead of native form submission.
+export function WriteFormSection({ section, featureName, translate, hideTitle, onSubmitted, actions, }) {
+    const { Section, Card, Grid, GridCell, Button, Banner } = usePrimitives();
+    const t = useTranslation();
+    const effectiveTranslate = translate ?? t;
+    const initial = useMemo(() => Object.fromEntries(section.fields.map((f) => [f.field, f.value])), [section.fields]);
+    const schema = useMemo(() => buildWriteFormSchema(section.fields), [section.fields]);
+    const { controller, snapshot } = useForm({
+        initial,
+        submit: { type: section.handler, payloadMode: "values" },
+        schema,
+    });
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const [error, setError] = useState(null);
+    async function handleSubmit() {
+        if (isSubmitting)
+            return;
+        setIsSubmitting(true);
+        try {
+            const result = await controller.submit();
+            if (result.isSuccess) {
+                setError(null);
+                onSubmitted();
+                return;
+            }
+            if (result.validationBlocked)
+                return;
+            // Field-level issues already surface inline via snapshot.errors (same
+            // GridCellForField/RenderField path RenderEdit uses) — the banner is
+            // only for form-level errors nothing else would show (fw#1901 pattern).
+            const fieldIssues = result.error.details?.fields ?? [];
+            setError(fieldIssues.length === 0 ? dispatcherErrorText(result.error, effectiveTranslate) : null);
+        }
+        finally {
+            setIsSubmitting(false);
+        }
+    }
+    const content = (_jsxs(_Fragment, { children: [_jsx(Grid, { columns: section.columns, children: section.fields.map((field) => (_jsx(GridCellForField, { field: field, columns: section.columns, issues: snapshot.errors[field.field], onChange: (v) => controller.setField(field.field, v), GridCell: GridCell, featureName: featureName, allIssues: snapshot.errors, valueDisplay: "form", row: snapshot.values }, field.field))) }), error !== null && (_jsx(Banner, { variant: "error", testId: "write-form-section-error", children: error }))] }));
+    // type="button" (not "submit") is load-bearing: this section is deliberately
+    // NOT a nested <form> (see the component doc above), so a "submit" type
+    // would instead trigger the host RenderEdit's own form submit.
+    const submitButton = (_jsx(Button, { type: "button", variant: "primary", disabled: isSubmitting, loading: isSubmitting, onClick: () => void handleSubmit(), testId: "write-form-section-submit", children: section.submitLabel ?? effectiveTranslate("kumiko.actions.save") }));
+    const titleRowActions = actions !== undefined ? (_jsxs(_Fragment, { children: [actions, submitButton] })) : (submitButton);
+    // Section always flattens to a borderless divider when rendered inside
+    // RenderEdit's own <Form> in tabs mode (hideTitle) — Card frames it there
+    // instead, same reason render-edit.tsx's tabs-mode fields/extension
+    // branches stay on Card.
+    if (hideTitle) {
+        return (_jsx(Card, { slots: {
+                ...(section.description !== undefined && { subtitle: section.description }),
+                headerActions: titleRowActions,
+            }, testId: `write-form-${section.title ?? "section"}`, children: content }));
+    }
+    // Routed through Section's `actions` slot (same mechanism render-edit.tsx
+    // uses via Form's `actions`) so the button gets the established right-
+    // aligned footer treatment instead of stretching full-width inline.
+    return (_jsx(Section, { ...(section.title !== undefined && { title: section.title }), ...(section.description !== undefined && { subtitle: section.description }), ...(section.icon !== undefined && { icon: section.icon }), actions: titleRowActions, testId: `write-form-${section.title ?? "section"}`, children: content }));
+}

package/dist/context/dispatcher-context.d.ts

@@ -0,0 +1,10 @@
+import type { Dispatcher, DispatcherStatus } from "@cosmicdrift/kumiko-headless";
+import { type ReactNode } from "react";
+export type DispatcherProviderProps = {
+    readonly dispatcher: Dispatcher;
+    readonly children: ReactNode;
+};
+export declare function DispatcherProvider({ dispatcher, children }: DispatcherProviderProps): ReactNode;
+export declare function useDispatcher(): Dispatcher;
+export declare function useOptionalDispatcher(): Dispatcher | undefined;
+export declare function useDispatcherStatus(): DispatcherStatus;

package/{src/context/dispatcher-context.tsx → dist/context/dispatcher-context.js}

@@ -1,7 +1,6 @@
-import type { Dispatcher, DispatcherStatus } from "@cosmicdrift/kumiko-headless";
-import { createContext, type ReactNode, useContext } from "react";
-import { useStore } from "../hooks/use-store";
-
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+import { useStore } from "../hooks/use-store.js";
 // React Context threading the Dispatcher through the tree. An app
 // wraps its root in <DispatcherProvider dispatcher={createLiveDispatcher()}>
 // and every hook below reaches into that context instead of taking the
@@ -11,41 +10,29 @@ import { useStore } from "../hooks/use-store";
 // The context holds the Dispatcher INSTANCE, not a factory — a single
 // dispatcher per app (rebuilding would wipe its in-flight tracking and
 // status listeners). Tests wire a fake dispatcher in directly.
-
-const DispatcherContext = createContext<Dispatcher | null>(null);
-
-export type DispatcherProviderProps = {
-  readonly dispatcher: Dispatcher;
-  readonly children: ReactNode;
-};
-
-export function DispatcherProvider({ dispatcher, children }: DispatcherProviderProps): ReactNode {
-  return <DispatcherContext value={dispatcher}>{children}</DispatcherContext>;
+const DispatcherContext = createContext(null);
+export function DispatcherProvider({ dispatcher, children }) {
+    return _jsx(DispatcherContext, { value: dispatcher, children: children });
 }
-
 // Reads the ambient Dispatcher. Throws instead of returning null when
 // no provider is mounted — a dispatcher-less hook is always a
 // developer error (the app forgot to wrap its root) and surfacing it
 // early beats debugging "why did my write silently do nothing" later.
-export function useDispatcher(): Dispatcher {
-  const dispatcher = useContext(DispatcherContext);
-  if (!dispatcher) {
-    throw new Error(
-      "useDispatcher: no <DispatcherProvider> mounted above this component. Wrap your app root with <DispatcherProvider dispatcher={createLiveDispatcher()}>.",
-    );
-  }
-  return dispatcher;
+export function useDispatcher() {
+    const dispatcher = useContext(DispatcherContext);
+    if (!dispatcher) {
+        throw new Error("useDispatcher: no <DispatcherProvider> mounted above this component. Wrap your app root with <DispatcherProvider dispatcher={createLiveDispatcher()}>.");
+    }
+    return dispatcher;
 }
-
 // Soft-Variante: null wenn kein Provider mounted statt throw. Für
 // Components die einen Dispatcher OPTIONAL brauchen (z.B. KumikoScreen
 // rendert mit/ohne rowActions; die Test-Suite mountet kein Dispatcher
 // wenn der Screen keine Mutation triggert). Caller ist zuständig dass
 // er bei null einen sinnvollen Fallback hat (typisch: kein Action-Wiring).
-export function useOptionalDispatcher(): Dispatcher | undefined {
-  return useContext(DispatcherContext) ?? undefined;
+export function useOptionalDispatcher() {
+    return useContext(DispatcherContext) ?? undefined;
 }
-
 // Subscribes to online/offline/syncing transitions. The dispatcher
 // exposes `statusStore: Store<DispatcherStatus>` directly; useStore is
 // the canonical React-binding for that contract.
@@ -54,6 +41,6 @@ export function useOptionalDispatcher(): Dispatcher | undefined {
 // returns the same snapshot the client sees on hydration — for the
 // live-dispatcher that's "online" (the optimistic boot default), so
 // no flash on hydration.
-export function useDispatcherStatus(): DispatcherStatus {
-  return useStore(useDispatcher().statusStore);
+export function useDispatcherStatus() {
+    return useStore(useDispatcher().statusStore);
 }

package/dist/context/draft-storage-context.d.ts

@@ -0,0 +1,12 @@
+import { type ReactNode } from "react";
+export type DraftStorage = {
+    readonly getDraftId: (screenId: string) => string | null;
+    readonly setDraftId: (screenId: string, draftId: string) => void;
+    readonly clearDraftId: (screenId: string) => void;
+};
+export type DraftStorageProviderProps = {
+    readonly value: DraftStorage;
+    readonly children: ReactNode;
+};
+export declare function DraftStorageProvider({ value, children }: DraftStorageProviderProps): ReactNode;
+export declare function useDraftStorage(): DraftStorage;

package/dist/context/draft-storage-context.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+// No-op default: without a mounted provider (unwired platform, or a test
+// that doesn't care about drafts) same-tab reload just loses draftId
+// persistence — RenderEdit falls back to its `form-draft:query:list`
+// resume path, the same one a cleared sessionStorage takes on the web.
+const noopDraftStorage = {
+    getDraftId: () => null,
+    setDraftId: () => { },
+    clearDraftId: () => { },
+};
+const DraftStorageContext = createContext(noopDraftStorage);
+export function DraftStorageProvider({ value, children }) {
+    return _jsx(DraftStorageContext, { value: value, children: children });
+}
+export function useDraftStorage() {
+    return useContext(DraftStorageContext);
+}

package/dist/context/user-roles-context.d.ts

@@ -0,0 +1,7 @@
+import { type ReactNode } from "react";
+export type UserRolesProviderProps = {
+    readonly roles: readonly string[] | undefined;
+    readonly children: ReactNode;
+};
+export declare function UserRolesProvider({ roles, children }: UserRolesProviderProps): ReactNode;
+export declare function useUserRoles(): readonly string[] | undefined;

package/{src/context/user-roles-context.tsx → dist/context/user-roles-context.js}

@@ -1,5 +1,5 @@
-import { createContext, type ReactNode, useContext } from "react";
-
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
 // Threads the current user's roles through the tree so KumikoScreen can
 // gate role-restricted screens at render time (see #1203 — nav filtering
 // alone doesn't stop a direct-URL/screenQn hit on a role-gated screen).
@@ -10,18 +10,10 @@ import { createContext, type ReactNode, useContext } from "react";
 // unknown" — deliberately distinct from `[]` ("authenticated, no
 // roles"). Both deny role-gated screens; only `undefined` also lets an
 // app without any role-gated screens skip wiring this entirely.
-
-const UserRolesContext = createContext<readonly string[] | undefined>(undefined);
-
-export type UserRolesProviderProps = {
-  readonly roles: readonly string[] | undefined;
-  readonly children: ReactNode;
-};
-
-export function UserRolesProvider({ roles, children }: UserRolesProviderProps): ReactNode {
-  return <UserRolesContext value={roles}>{children}</UserRolesContext>;
+const UserRolesContext = createContext(undefined);
+export function UserRolesProvider({ roles, children }) {
+    return _jsx(UserRolesContext, { value: roles, children: children });
 }
-
-export function useUserRoles(): readonly string[] | undefined {
-  return useContext(UserRolesContext);
+export function useUserRoles() {
+    return useContext(UserRolesContext);
 }

package/dist/format-when.d.ts

@@ -0,0 +1 @@
+export declare function formatWhen(value: string): string;