@cosmicdrift/kumiko-renderer 0.333.0 → 0.335.0

package/dist/app/nav.js

@@ -9,8 +9,21 @@ import { lastSegment } from "./qn.js";
 // Alles nach den ersten 2/3 Segmenten wird ignoriert — kumikos
 // Navigation-Grammatik nested nicht weiter. Nested-Routes wäre eine
 // Spec-Änderung, nicht ein URL-Shape-Unfall.
+function decodeSegments(segments) {
+    try {
+        return segments.map((segment) => decodeURIComponent(segment));
+    }
+    catch {
+        // Malformed percent-escape ("%zz") — treat the URL as no route.
+        return undefined;
+    }
+}
 export function parsePath(pathname, hasWorkspaces) {
-    const parts = pathname.split("/").filter((p) => p !== "");
+    const rawParts = pathname.split("/").filter((p) => p !== "");
+    // Only the segments the grammar uses are decoded; ignored trailing ones may be junk.
+    const parts = decodeSegments(rawParts.slice(0, hasWorkspaces === true ? 3 : 2));
+    if (parts === undefined)
+        return undefined;
     if (hasWorkspaces === true) {
         const [workspaceId, screenId, entityId] = parts;
         if (workspaceId === undefined || workspaceId === "")
@@ -41,17 +54,17 @@ export function formatPath(target) {
     segments.push(target.screenId);
     if (target.entityId !== undefined)
         segments.push(target.entityId);
-    return `/${segments.join("/")}`;
+    return `/${segments.map((segment) => encodeURIComponent(segment)).join("/")}`;
 }
 // Shared entity→detailFor-screen lookup — resolveTarget's ObjectTarget
 // branch and hasDetailScreen (create-app's row-click default, fw#2164) both
 // need "is there a detail screen for this entity", one to resolve it, the
 // other to just check before falling back to a different default.
-function findDetailForScreen(features, entity) {
+export function findDetailForScreen(features, entity) {
     for (const feature of features) {
         for (const screen of feature.screens) {
             if (screen.detailFor === entity)
-                return { featureName: feature.featureName, screenId: screen.id };
+                return { featureName: feature.featureName, screenId: screen.id, screen };
         }
     }
     return undefined;

package/dist/app/query-state-banners.d.ts

@@ -0,0 +1,8 @@
+import type { DispatcherError, Translate } from "@cosmicdrift/kumiko-headless";
+import type { ReactNode } from "react";
+export declare function QueryLoadingBanner(): ReactNode;
+export declare function QueryErrorBanner({ error, translate, onRetry, }: {
+    readonly error: DispatcherError;
+    readonly translate: Translate;
+    readonly onRetry: () => void | Promise<void>;
+}): ReactNode;

package/dist/app/query-state-banners.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useTranslation } from "../i18n.js";
+import { usePrimitives } from "../primitives.js";
+import { dispatcherErrorText } from "./write-failed-error.js";
+export function QueryLoadingBanner() {
+    const { Banner } = usePrimitives();
+    const t = useTranslation();
+    return (_jsx(Banner, { padded: true, variant: "loading", testId: "kumiko-screen-loading", children: t("kumiko.widget.loading") }));
+}
+export function QueryErrorBanner({ error, translate, onRetry, }) {
+    const { Banner, Button } = usePrimitives();
+    const t = useTranslation();
+    return (_jsx(Banner, { padded: true, variant: "error", testId: "kumiko-screen-error", actions: _jsx(Button, { variant: "secondary", size: "sm", onClick: onRetry, testId: "kumiko-screen-retry", children: t("kumiko.actions.retry") }), children: dispatcherErrorText(error, translate) }));
+}

package/dist/app/reference-facet-bridge.js

@@ -2,14 +2,21 @@ import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 // One bridge component per reference facet, mirroring ReferenceLookupBridge —
 // facet count varies per screen, so the hook can't be called in a loop.
 import { useEffect } from "react";
+import { REFERENCE_LIST_LOOKUP_LIMIT } from "../hooks/reference-limits.js";
 import { useReferenceLookup } from "../hooks/use-reference-lookup.js";
 function ReferenceFacetOptionsBridge({ field, refEntity, refFeature, labelField, onOptions, }) {
     const lookup = useReferenceLookup(refFeature, refEntity, labelField);
     useEffect(() => {
         if (lookup.loading)
             return;
+        // The lookup is one capped list fetch; a full page means the facet may be
+        // missing values the user wants to filter by.
+        if (lookup.map.size >= REFERENCE_LIST_LOOKUP_LIMIT) {
+            // biome-ignore lint/suspicious/noConsole: dev-warning, facet options are silently truncated
+            console.warn(`[kumiko] reference facet "${field}" shows only the first ${REFERENCE_LIST_LOOKUP_LIMIT} ${refEntity} rows; further values cannot be filtered by`);
+        }
         onOptions(field, [...lookup.map.entries()].map(([value, label]) => ({ value, label })));
-    }, [lookup.loading, lookup.map, field, onOptions]);
+    }, [lookup.loading, lookup.map, field, refEntity, onOptions]);
     return null;
 }
 // One invisible bridge per "reference" facet spec, each publishing its

package/dist/app/row-actions.d.ts

@@ -15,6 +15,7 @@ export declare function runProjectionRowNavigate(nav: NavApi, action: RowActionN
 type OpenDrawer = (action: RowActionDrawer, initialValues: Readonly<Record<string, unknown>> | undefined) => void;
 /** @internal test-only */
 export declare function resetDrawerActionWarningsForTests(): void;
+export declare function buildDrawerRowAction(action: RowActionDrawer, translate: Translate, openDrawer: OpenDrawer): DataTableRowAction;
 export declare function buildProjectionRowActions(options: {
     readonly rowActions: readonly RowAction[] | undefined;
     readonly translate: Translate;
@@ -52,6 +53,8 @@ export declare function buildProjectionToolbarActions(options: {
     readonly record?: Readonly<Record<string, unknown>>;
     readonly host: ReturnHost | undefined;
 }): readonly ToolbarActionButton[] | undefined;
+export declare function deletesShownRecord(action: RowActionWriteHandler, payload: Readonly<Record<string, unknown>>, shownRecordId: unknown): boolean;
+export type RecordLeftHandler = (action: RowActionWriteHandler, resultData: unknown, deletedShownRecord: boolean) => void;
 export declare function buildRecordActions(options: {
     readonly actions: readonly RowAction[];
     readonly record: Readonly<Record<string, unknown>>;
@@ -62,6 +65,11 @@ export declare function buildRecordActions(options: {
     readonly openDrawer: (action: RowActionDrawer, initialValues: Readonly<Record<string, unknown>> | undefined) => void;
     /** Called after a writeHandler action succeeds (refetch/reload). */
     readonly onWriteSuccess: () => void | Promise<void>;
+    /** Called INSTEAD of `onWriteSuccess` when a writeHandler action succeeds
+     *  and leaves the shown record (`redirect` set, or it deletes the record).
+     *  Callers whose actions run on the shown record pass it; callers whose
+     *  records are list rows omit it. */
+    readonly onRecordLeft?: RecordLeftHandler;
     /** Screen-target navigate default entityId when the action declares no
      *  explicit `entityId` field-source. A caller editing a fixed entity can
      *  pass its own `entityId` here directly (the record it already is). A
@@ -73,5 +81,9 @@ export declare function buildRecordActions(options: {
      *  belongs to (cross-feature lookup) — undefined otherwise. Omitted by
      *  callers with no such cross-screen lookup. */
     readonly sameEntityScreenId?: (targetScreen: string) => string | undefined;
+    /** Default `{ id }` for a writeHandler action declaring no `payload`. A
+     *  caller editing a fixed entity passes its route id so the payload does
+     *  not depend on the loaded record carrying an `id` field. */
+    readonly defaultWritePayloadId?: string;
 }): readonly RenderEditAction[] | undefined;
 export {};

package/dist/app/row-actions.js

@@ -119,7 +119,7 @@ function warnDrawerActionDropped(actionKind, actionId) {
     // biome-ignore lint/suspicious/noConsole: dev-warning for a setup error
     console.warn(`[kumiko] ${actionKind} "${actionId}" is kind:"drawer", but the host did not wire openDrawer (RelatedListSection: pass onOpenDrawer) — it will not render.`);
 }
-function buildDrawerRowAction(action, translate, openDrawer) {
+export function buildDrawerRowAction(action, translate, openDrawer) {
     const { visible, params } = action;
     const actionIcon = resolveActionIcon(action.id, action.icon);
     return {
@@ -269,9 +269,9 @@ export function buildProjectionToolbarActions(options) {
         return undefined;
     const out = [];
     for (const action of toolbarActions) {
+        // Fail closed: a conditional action without a record to evaluate against stays hidden.
         if (action.visible !== undefined &&
-            record !== undefined &&
-            !evalFieldCondition(action.visible, record)) {
+            (record === undefined || !evalFieldCondition(action.visible, record))) {
             continue;
         }
         if (action.kind === "navigate") {
@@ -356,8 +356,17 @@ function buildDrawerRecordAction(action, options) {
         },
     };
 }
+// Entity delete handler QN: `<feature>:write:<entity>:delete` (see
+// entityWriteCommand in kumiko-screen.tsx).
+const ENTITY_DELETE_HANDLER_PATTERN = /:write:[^:]+:delete$/;
+export function deletesShownRecord(action, payload, shownRecordId) {
+    return (ENTITY_DELETE_HANDLER_PATTERN.test(action.handler) &&
+        payload["id"] !== undefined &&
+        payload["id"] === shownRecordId);
+}
 function buildWriteHandlerRecordAction(action, options) {
-    const { record, translate, actionIcon, dispatcher, onWriteSuccess } = options;
+    const { record, translate, actionIcon, dispatcher, onWriteSuccess, defaultWritePayloadId, onRecordLeft, } = options;
+    const shownRecordId = defaultWritePayloadId ?? record["id"];
     return {
         id: action.id,
         label: translate(action.label),
@@ -371,12 +380,18 @@ function buildWriteHandlerRecordAction(action, options) {
         onPress: async () => {
             const payload = action.payload !== undefined
                 ? evalRowExtractor(action.payload, record)
-                : { id: record["id"] };
+                : { id: shownRecordId };
             const result = await dispatcher.write(action.handler, payload);
             if (!result.isSuccess) {
                 throw new WriteFailedError(result.error, dispatcherErrorText(result.error, translate));
             }
-            await onWriteSuccess();
+            const deletedShownRecord = deletesShownRecord(action, payload, shownRecordId);
+            if (onRecordLeft !== undefined && (action.redirect !== undefined || deletedShownRecord)) {
+                onRecordLeft(action, result.data, deletedShownRecord);
+            }
+            else {
+                await onWriteSuccess();
+            }
         },
     };
 }
@@ -387,7 +402,7 @@ function buildWriteHandlerRecordAction(action, options) {
 // resolved against the record currently being viewed/edited, independent of
 // any table row.
 export function buildRecordActions(options) {
-    const { actions, record, translate, nav, host, dispatcher, openDrawer, onWriteSuccess, defaultScreenTargetEntityId, sameEntityScreenId, } = options;
+    const { actions, record, translate, nav, host, dispatcher, openDrawer, onWriteSuccess, onRecordLeft, defaultScreenTargetEntityId, sameEntityScreenId, defaultWritePayloadId, } = options;
     const out = [];
     for (const action of actions) {
         if (action.visible !== undefined && !evalFieldCondition(action.visible, record))
@@ -420,6 +435,8 @@ export function buildRecordActions(options) {
             actionIcon,
             dispatcher,
             onWriteSuccess,
+            defaultWritePayloadId,
+            onRecordLeft,
         }));
     }
     return out.length > 0 ? out : undefined;

package/dist/app/screen-access.js

@@ -1,4 +1,5 @@
 import { isUiAccessGranted } from "@cosmicdrift/kumiko-framework/ui-types";
+import { findDetailForScreen } from "./nav.js";
 import { lastSegment } from "./qn.js";
 // Shared UI-visibility predicate for the screen-render path (#1203 — nav
 // filtering via filterByAccess in workspace-shell.tsx hid role-gated
@@ -20,15 +21,18 @@ export function navigateTargetAllows(navigate, appFeatures, userRoles) {
     // forbidden ones.
     if (appFeatures.length === 0)
         return true;
-    for (const feature of appFeatures) {
-        for (const candidate of feature.screens) {
-            const isTarget = entity !== undefined
-                ? candidate.detailFor === entity
-                : lastSegment(candidate.id) === screen;
-            // First match IS the destination: short ids are globally unique
-            // (validateScreenShortIdCollisions) and both the router and
-            // resolveTarget take the first hit.
-            if (isTarget)
+    // Entity targets share nav's lookup so the gate and resolveTarget can't
+    // pick different screens. Short ids are globally unique
+    // (validateScreenShortIdCollisions), so the first screen hit is the one.
+    if (entity !== undefined) {
+        const found = findDetailForScreen(appFeatures, entity);
+        if (found !== undefined)
+            return isUiAccessGranted(found.screen.access, userRoles);
+    }
+    else {
+        for (const feature of appFeatures) {
+            const candidate = feature.screens.find((s) => lastSegment(s.id) === screen);
+            if (candidate !== undefined)
                 return isUiAccessGranted(candidate.access, userRoles);
         }
     }

package/dist/app/secret-mint-body.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useMemo, useRef, useState } from "react";
 import { RenderEdit } from "../components/render-edit.js";
 import { useTranslation } from "../i18n.js";
@@ -44,7 +44,7 @@ function isBlank(value) {
 export function SecretMintBody({ schema, screen, translate }) {
     const nav = useNav();
     const returnTarget = useReturnTarget(screen.id);
-    const { Card, Heading, Banner, Button, Text, Grid, GridCell, SecretReveal } = usePrimitives();
+    const { Card, Heading, Banner, Button, Text, Grid, GridCell, Section, SecretReveal } = usePrimitives();
     const t = useTranslation();
     const effectiveTranslate = translate ?? t;
     const synthEntity = useMemo(() => synthesizeActionFormEntity(screen.fields), [screen.fields]);
@@ -63,6 +63,9 @@ export function SecretMintBody({ schema, screen, translate }) {
     }), [screen.fields, screen.urlPrefillFields, nav.searchParams, synthScreen, handoffValues]);
     const [revealed, setRevealed] = useState(null);
     const [done, setDone] = useState(false);
+    // The secret was minted server-side but none of the declared reveal fields
+    // came back; the mint form must not return (a re-mint would invalidate it).
+    const [revealMissing, setRevealMissing] = useState(false);
     // Never rendered, never merged into `revealed` or the confirm form's
     // initial values — read only from `buildPayload` at confirm-submit time.
     const carriedRef = useRef({});
@@ -82,16 +85,36 @@ export function SecretMintBody({ schema, screen, translate }) {
                 continue;
             values[revealField.field] = value;
         }
+        if (Object.values(values).every(isBlank)) {
+            // biome-ignore lint/suspicious/noConsole: the user-facing banner carries no detail; this names the screen and fields for the developer
+            console.error(`secretMint "${screen.id}": write result carried no value for reveal fields [${screen.reveal.fields
+                .map((revealField) => revealField.field)
+                .join(", ")}]`);
+            setRevealMissing(true);
+            return;
+        }
         setRevealed(values);
         carriedRef.current =
             confirm?.carry !== undefined ? extractCarriedValues(result.data, confirm.carry) : {};
-    }, [screen.reveal.fields, confirm?.carry]);
+    }, [screen.id, screen.reveal.fields, confirm?.carry]);
     const handleCancel = useMemo(() => {
         const target = screen.cancelTarget ?? screen.redirect;
         if (target === undefined || target === false)
             return undefined;
-        return () => navigateToReturnOr(nav, returnTarget, () => nav.navigate({ screenId: lastSegment(target) }));
+        return () => {
+            // A native stack keeps this screen mounted after navigate; drop the secret first.
+            setRevealed(null);
+            carriedRef.current = {};
+            navigateToReturnOr(nav, returnTarget, () => nav.navigate({ screenId: lastSegment(target) }));
+        };
     }, [nav, screen.redirect, screen.cancelTarget, returnTarget]);
+    // The confirm step must always offer a way out: a failed confirm (e.g. an
+    // expired setup token) otherwise leaves a form that can only keep failing.
+    // Restarting re-mints, which issues a fresh secret and invalidates this one.
+    const restartMint = useCallback(() => {
+        setRevealed(null);
+        carriedRef.current = {};
+    }, []);
     // Ends the reveal phase for both paths (the bare acknowledge button, and a
     // successful confirm submit): clears the secret and the carried values, then
     // either navigates (screen.redirect) or shows a done-state — never falls
@@ -113,7 +136,10 @@ export function SecretMintBody({ schema, screen, translate }) {
             finishMint();
     }, [finishMint]);
     if (done) {
-        return (_jsx(Card, { children: _jsx(Banner, { variant: "info", testId: "kumiko-screen-secret-mint-done", children: effectiveTranslate(confirm?.doneMessage ?? "kumiko.secretMint.done") }) }));
+        return (_jsx(Card, { options: { screenBody: true }, children: _jsx(Banner, { variant: "info", testId: "kumiko-screen-secret-mint-done", children: effectiveTranslate(confirm?.doneMessage ?? "kumiko.secretMint.done") }) }));
+    }
+    if (revealMissing) {
+        return (_jsx(Card, { options: { screenBody: true }, children: _jsx(Banner, { variant: "error", testId: "kumiko-screen-secret-mint-missing", children: effectiveTranslate("kumiko.form.error.generic") }) }));
     }
     if (revealed !== null) {
         const values = screen.reveal.fields.flatMap((revealField) => {
@@ -134,7 +160,15 @@ export function SecretMintBody({ schema, screen, translate }) {
                 },
             ];
         });
-        return (_jsxs(Card, { testId: "kumiko-screen-secret-mint-card", children: [_jsx(Heading, { variant: "page", children: effectiveTranslate(screen.reveal.title ?? "kumiko.secretMint.title") }), _jsx(Banner, { variant: "warning", testId: "kumiko-screen-secret-mint-warning", children: effectiveTranslate(screen.reveal.warning ?? "kumiko.secretMint.warning") }), SecretReveal !== undefined ? (_jsx(SecretReveal, { values: values, copyLabel: effectiveTranslate("kumiko.secretMint.copy"), copiedLabel: effectiveTranslate("kumiko.secretMint.copied"), testId: "kumiko-screen-secret-mint-reveal" })) : (_jsx(Grid, { columns: 1, testId: "kumiko-screen-secret-mint-reveal", children: values.map((v) => (_jsxs(GridCell, { children: [_jsx(Text, { children: v.label }), _jsx(Text, { variant: "code", children: v.value })] }, v.label))) })), confirm !== undefined && confirmEntity !== undefined && confirmScreen !== undefined ? (_jsx(RenderEdit, { screen: confirmScreen, entity: confirmEntity, featureName: schema.featureName, initial: confirmInitial ?? {}, writeCommand: confirm.handler, payloadMode: "values", buildPayload: (snapshot) => ({ ...snapshot.values, ...carriedRef.current }), onSubmit: handleConfirmSubmitted, ...(handleCancel !== undefined && { onCancel: handleCancel }), ...(translate !== undefined && { translate }), ...(confirm.submitLabel !== undefined && { submitLabel: confirm.submitLabel }) })) : (_jsx(Button, { type: "button", variant: "primary", onClick: finishMint, testId: "kumiko-screen-secret-mint-confirm", children: effectiveTranslate(screen.reveal.confirmLabel ?? "kumiko.secretMint.confirm") }))] }));
+        const revealContent = (_jsxs(_Fragment, { children: [_jsx(Heading, { variant: "page", children: effectiveTranslate(screen.reveal.title ?? "kumiko.secretMint.title") }), _jsx(Banner, { variant: "warning", testId: "kumiko-screen-secret-mint-warning", children: effectiveTranslate(screen.reveal.warning ?? "kumiko.secretMint.warning") }), SecretReveal !== undefined ? (_jsx(SecretReveal, { values: values, copyLabel: effectiveTranslate("kumiko.secretMint.copy"), copiedLabel: effectiveTranslate("kumiko.secretMint.copied"), testId: "kumiko-screen-secret-mint-reveal" })) : (_jsx(Grid, { columns: 1, testId: "kumiko-screen-secret-mint-reveal", children: values.map((v) => (_jsxs(GridCell, { children: [_jsx(Text, { children: v.label }), _jsx(Text, { variant: "code", children: v.value })] }, v.label))) }))] }));
+        // One screen form like the mint phase: the reveal leads the form column
+        // instead of the confirm form nesting a second card inside a card. The
+        // keys stop the mint and confirm forms sharing one instance (and its
+        // submit state) across phases.
+        if (confirm !== undefined && confirmEntity !== undefined && confirmScreen !== undefined) {
+            return (_jsx(RenderEdit, { screen: confirmScreen, i18nScreenId: screen.id, entity: confirmEntity, featureName: schema.featureName, initial: confirmInitial ?? {}, writeCommand: confirm.handler, payloadMode: "values", buildPayload: (snapshot) => ({ ...snapshot.values, ...carriedRef.current }), onSubmit: handleConfirmSubmitted, onCancel: handleCancel ?? restartMint, fillScreenHeight: true, leadContent: _jsx(Section, { testId: "kumiko-screen-secret-mint-card", children: revealContent }), ...(translate !== undefined && { translate }), ...(confirm.submitLabel !== undefined && { submitLabel: confirm.submitLabel }) }, "confirm"));
+        }
+        return (_jsxs(Card, { options: { screenBody: true }, testId: "kumiko-screen-secret-mint-card", children: [revealContent, _jsx(Button, { type: "button", variant: "primary", onClick: finishMint, testId: "kumiko-screen-secret-mint-confirm", children: effectiveTranslate(screen.reveal.confirmLabel ?? "kumiko.secretMint.confirm") })] }));
     }
-    return (_jsx(RenderEdit, { screen: synthScreen, entity: synthEntity, featureName: schema.featureName, initial: initial, extensionInitialValues: initial, writeCommand: screen.handler, payloadMode: "values", onSubmit: handleSubmitted, ...(handleCancel !== undefined && { onCancel: handleCancel }), ...(translate !== undefined && { translate }), ...(screen.submitLabel !== undefined && { submitLabel: screen.submitLabel }) }));
+    return (_jsx(RenderEdit, { screen: synthScreen, entity: synthEntity, featureName: schema.featureName, initial: initial, extensionInitialValues: initial, writeCommand: screen.handler, payloadMode: "values", onSubmit: handleSubmitted, fillScreenHeight: true, ...(handleCancel !== undefined && { onCancel: handleCancel }), ...(translate !== undefined && { translate }), ...(screen.submitLabel !== undefined && { submitLabel: screen.submitLabel }) }, "mint"));
 }

package/dist/app/secrets-edit-body.js

@@ -3,13 +3,23 @@ import { useCallback, useMemo, useState } from "react";
 import { useDispatcher } from "../context/dispatcher-context.js";
 import { useQuery } from "../hooks/use-query.js";
 import { useTranslation } from "../i18n.js";
-import { usePrimitives } from "../primitives.js";
+import { STICKY_PRIMARY_ACTION_PROP, usePrimitives } from "../primitives.js";
+import { QueryErrorBanner, QueryLoadingBanner } from "./query-state-banners.js";
 import { dispatcherErrorText } from "./write-failed-error.js";
+function groupSectionsByTitle(sections) {
+    const byTitle = new Map();
+    for (const section of sections) {
+        const title = section.title ?? "config.secrets.section";
+        // kumiko-lint-ignore section-fields-raw secretsEdit section fields are field-id strings, not EditFieldSpec
+        byTitle.set(title, [...(byTitle.get(title) ?? []), ...section.fields]);
+    }
+    return [...byTitle].map(([title, fields]) => ({ title, fields }));
+}
 // secrets:query:list never returns plaintext (only a redacted preview), so
 // unlike ConfigEditBody there is no server value to pre-fill a draft with —
 // every input starts at "" and stays that way unless the user types into it.
 export function SecretsEditBody({ screen, translate }) {
-    const { Banner, Form, Section, Field, Input, Button, Text } = usePrimitives();
+    const { Banner, Dialog, Form, Section, Field, Input, Button, Text, Grid } = usePrimitives();
     const t = useTranslation();
     const effectiveTranslate = translate ?? t;
     const dispatcher = useDispatcher();
@@ -17,6 +27,8 @@ export function SecretsEditBody({ screen, translate }) {
     const [drafts, setDrafts] = useState({});
     const [submitting, setSubmitting] = useState(false);
     const [submitError, setSubmitError] = useState(null);
+    const [pendingDeleteKey, setPendingDeleteKey] = useState(null);
+    const [deleting, setDeleting] = useState(false);
     const rowsByQualifiedKey = useMemo(() => {
         const out = new Map();
         for (const row of listQuery.data ?? [])
@@ -35,42 +47,86 @@ export function SecretsEditBody({ screen, translate }) {
             return;
         setSubmitting(true);
         setSubmitError(null);
-        const result = await dispatcher.batch(commands);
-        setSubmitting(false);
-        if (!result.isSuccess) {
-            setSubmitError(dispatcherErrorText(result.error, effectiveTranslate));
-            return;
+        try {
+            const result = await dispatcher.batch(commands);
+            if (!result.isSuccess) {
+                setSubmitError(dispatcherErrorText(result.error, effectiveTranslate));
+                return;
+            }
+            setDrafts({});
+            await listQuery.refetch();
+        }
+        catch {
+            // Transport failures reject instead of returning a result; drafts stay
+            // so the user can retry without retyping the secrets.
+            setSubmitError(effectiveTranslate("kumiko.form.error.generic"));
+        }
+        finally {
+            setSubmitting(false);
         }
-        setDrafts({});
-        await listQuery.refetch();
     }, [dispatcher, drafts, screen.secretKeys, listQuery.refetch, effectiveTranslate]);
     const handleDelete = useCallback(async (qualified) => {
-        const result = await dispatcher.write("secrets:write:delete", { key: qualified });
-        if (!result.isSuccess) {
-            setSubmitError(dispatcherErrorText(result.error, effectiveTranslate));
-            return;
+        setDeleting(true);
+        try {
+            const result = await dispatcher.write("secrets:write:delete", { key: qualified });
+            if (!result.isSuccess) {
+                setSubmitError(dispatcherErrorText(result.error, effectiveTranslate));
+                return;
+            }
+            setSubmitError(null);
+            await listQuery.refetch();
+        }
+        catch {
+            setSubmitError(effectiveTranslate("kumiko.form.error.generic"));
+        }
+        finally {
+            setDeleting(false);
         }
-        await listQuery.refetch();
     }, [dispatcher, listQuery.refetch, effectiveTranslate]);
-    if (listQuery.loading && listQuery.data === null) {
-        return (_jsx(Banner, { padded: true, variant: "loading", testId: "kumiko-screen-loading", children: "Loading\u2026" }));
-    }
+    if (listQuery.loading && listQuery.data === null)
+        return _jsx(QueryLoadingBanner, {});
     if (listQuery.error) {
-        return (_jsx(Banner, { padded: true, variant: "error", testId: "kumiko-screen-error", children: dispatcherErrorText(listQuery.error, effectiveTranslate) }));
+        return (_jsx(QueryErrorBanner, { error: listQuery.error, translate: effectiveTranslate, onRetry: listQuery.refetch }));
     }
-    return (_jsxs(Form, { onSubmit: () => {
-            void handleSubmit();
-        }, testId: "secrets-edit-form", ...(screen.description !== undefined && {
-            subtitle: effectiveTranslate(screen.description),
-        }), actions: _jsx(Button, { type: "submit", variant: "primary", loading: submitting, disabled: submitting, testId: "secrets-edit-submit", children: effectiveTranslate("kumiko.actions.save") }), children: [submitError !== null && (_jsx(Banner, { variant: "error", testId: "secrets-edit-error", children: submitError })), screen.sections.map((section, index) => (_jsx(Section, { ...(section.title !== undefined && { title: effectiveTranslate(section.title) }), children: section.fields.map((fieldId) => {
-                    const qualified = screen.secretKeys[fieldId];
-                    if (qualified === undefined)
-                        return null;
-                    const row = rowsByQualifiedKey.get(qualified);
-                    const hintKey = screen.fieldHints?.[fieldId];
-                    const isRequired = screen.requiredFields?.includes(fieldId) ?? false;
-                    return (_jsxs(Field, { id: fieldId, label: effectiveTranslate(screen.fieldLabels[fieldId] ?? fieldId), required: isRequired, testId: `field-${fieldId}`, fieldAppendix: _jsxs(_Fragment, { children: [hintKey !== undefined && (_jsx(Text, { variant: "small", children: effectiveTranslate(hintKey) })), row !== undefined ? (_jsxs(_Fragment, { children: [_jsx(Text, { variant: "small", testId: `secret-preview-${fieldId}`, children: row.redactedPreview ?? effectiveTranslate("config.secrets.set") }), _jsx(Button, { type: "button", variant: "danger-ghost", size: "sm", onClick: () => handleDelete(qualified), testId: `secret-delete-${fieldId}`, children: effectiveTranslate("config.secrets.delete") })] })) : (_jsxs(_Fragment, { children: [_jsx(Text, { variant: "small", testId: `secret-not-set-${fieldId}`, children: effectiveTranslate("config.secrets.notSet") }), isRequired && (_jsx(Text, { variant: "small", testId: `required-marker-${fieldId}`, children: effectiveTranslate("config.secrets.required") }))] }))] }), children: [_jsx(Text, { variant: "small", children: effectiveTranslate(row !== undefined
-                                    ? "config.secrets.replacePlaceholder"
-                                    : "config.secrets.placeholder") }), _jsx(Input, { kind: "password", id: fieldId, name: fieldId, value: drafts[fieldId] ?? "", onChange: (v) => setDraft(fieldId, v), autoComplete: "new-password", disabled: submitting, testId: `secret-input-${fieldId}` })] }, fieldId));
-                }) }, section.title ?? `section-${index}`)))] }));
+    // The generator emits one section per feature; features without a declared
+    // title all fall under the generic "Secrets" heading and share one band.
+    const sectionGroups = groupSectionsByTitle(screen.sections);
+    const unsavedCount = Object.values(drafts).filter((value) => value.trim() !== "").length;
+    return (_jsxs(_Fragment, { children: [_jsxs(Form, { onSubmit: () => {
+                    void handleSubmit();
+                }, testId: "secrets-edit-form", width: "full", fillHeight: true, stickyActions: true, screenForm: true, unsavedCount: unsavedCount, ...(screen.description !== undefined && {
+                    subtitle: effectiveTranslate(screen.description),
+                }), actions: _jsxs(_Fragment, { children: [unsavedCount > 0 && (_jsx(Button, { type: "button", variant: "ghost", disabled: submitting, onClick: () => setDrafts({}), testId: "secrets-edit-discard", [STICKY_PRIMARY_ACTION_PROP]: true, children: effectiveTranslate("kumiko.form.discard") })), _jsx(Button, { type: "submit", variant: "primary", loading: submitting, disabled: submitting || unsavedCount === 0, testId: "secrets-edit-submit", children: effectiveTranslate("kumiko.form.saveChanges") })] }), children: [submitError !== null && (_jsx(Banner, { variant: "error", testId: "secrets-edit-error", children: submitError })), sectionGroups.map((section) => (_jsx(Section, { layout: "settings-list", title: effectiveTranslate(section.title), subtitle: effectiveTranslate("config.secrets.description"), children: _jsx(Grid, { columns: 1, list: true, children: section.fields.map((fieldId) => {
+                                const qualified = screen.secretKeys[fieldId];
+                                if (qualified === undefined)
+                                    return null;
+                                const row = rowsByQualifiedKey.get(qualified);
+                                const hintKey = screen.fieldHints?.[fieldId];
+                                const isRequired = screen.requiredFields?.includes(fieldId) ?? false;
+                                return (_jsx(Field, { id: fieldId, layout: "row", label: effectiveTranslate(screen.fieldLabels[fieldId] ?? fieldId), required: isRequired, testId: `field-${fieldId}`, status: row !== undefined
+                                        ? {
+                                            tone: "ok",
+                                            label: effectiveTranslate("config.secrets.saved"),
+                                            testId: `secret-saved-${fieldId}`,
+                                        }
+                                        : {
+                                            tone: isRequired ? "bad" : "muted",
+                                            label: effectiveTranslate("config.secrets.notSet"),
+                                            testId: `secret-not-set-${fieldId}`,
+                                        }, ...(hintKey !== undefined && { description: effectiveTranslate(hintKey) }), ...(row !== undefined && {
+                                        fieldAppendix: (_jsxs(Grid, { columns: "auto", children: [_jsx(Text, { variant: "muted", testId: `secret-preview-${fieldId}`, children: row.redactedPreview !== null
+                                                        ? effectiveTranslate("config.secrets.stored", {
+                                                            preview: row.redactedPreview,
+                                                        })
+                                                        : effectiveTranslate("config.secrets.set") }), _jsx(Button, { type: "button", variant: "danger-ghost", size: "sm", disabled: submitting || deleting, onClick: () => setPendingDeleteKey(qualified), testId: `secret-delete-${fieldId}`, children: effectiveTranslate("config.secrets.delete") })] })),
+                                    }), children: _jsx(Input, { kind: "password", id: fieldId, name: fieldId, value: drafts[fieldId] ?? "", onChange: (v) => setDraft(fieldId, v), placeholder: effectiveTranslate(row !== undefined
+                                            ? "config.secrets.replacePlaceholder"
+                                            : "config.secrets.placeholder"), autoComplete: "new-password", disabled: submitting, testId: `secret-input-${fieldId}` }) }, fieldId));
+                            }) }) }, section.title)))] }), _jsx(Dialog, { open: pendingDeleteKey !== null, onOpenChange: (open) => {
+                    if (!open)
+                        setPendingDeleteKey(null);
+                }, title: effectiveTranslate("config.secrets.delete"), description: effectiveTranslate("config.secrets.deleteConfirm"), confirmLabel: effectiveTranslate("config.secrets.delete"), variant: "danger", initialFocus: "cancel", onConfirm: async () => {
+                    if (pendingDeleteKey !== null)
+                        await handleDelete(pendingDeleteKey);
+                }, testId: "secrets-delete-dialog" })] }));
 }

package/dist/components/embedded-list-field.js

@@ -3,7 +3,7 @@ import { computeDerivedCellValue, currencyDecimals, groupEmbeddedListIssues, rou
 import { useState } from "react";
 import { REFERENCE_COMBOBOX_LIMIT } from "../hooks/reference-limits.js";
 import { useQuery } from "../hooks/use-query.js";
-import { referenceLookupSource } from "../hooks/use-reference-lookup.js";
+import { referenceOptionSource } from "../hooks/use-reference-lookup.js";
 import { useTranslation } from "../i18n.js";
 import { usePrimitives } from "../primitives.js";
 function withRecomputedDerived(row, derived, cells) {
@@ -107,9 +107,7 @@ export function EmbeddedListField({ field, id, onChange, allIssues, featureName,
     const rows = Array.isArray(field.value) ? field.value : [];
     const derived = field.embeddedListDerived;
     const referenceCells = cells.filter((c) => c.type === "reference");
-    const referenceSources = referenceCells.map((cell) => cell.refOptionsQuery !== undefined
-        ? { queryQn: cell.refOptionsQuery, labelKey: "label" }
-        : referenceLookupSource(cell.refFeature ?? featureName, cell.refEntity ?? "", cell.refLabelField ?? "id"));
+    const referenceSources = referenceCells.map((cell) => referenceOptionSource(cell, cell.refFeature ?? featureName, cell.refEntity ?? ""));
     const referenceQueries = referenceSources.map((source) => 
     // biome-ignore lint/correctness/useHookAtTopLevel: referenceCells comes from the entity-schema definition — fixed for the screen's lifetime, not a real conditional-hook risk.
     useQuery(source.queryQn, {

package/dist/components/grid-cell-for-field.d.ts

@@ -1,6 +1,6 @@
 import type { EditFieldViewModel, FieldIssue } from "@cosmicdrift/kumiko-headless";
 import type { ReactNode } from "react";
-import type { FieldCellWidth, usePrimitives } from "../primitives.js";
+import type { FieldCellWidth, FieldProps, usePrimitives } from "../primitives.js";
 export type GridCellForFieldProps = {
     readonly field: EditFieldViewModel;
     readonly columns: number;
@@ -12,6 +12,9 @@ export type GridCellForFieldProps = {
     readonly featureName: string;
     readonly labelAppendix?: ReactNode;
     readonly fieldAppendix?: ReactNode;
+    readonly appendixPlacement?: FieldProps["appendixPlacement"];
+    readonly description?: ReactNode;
+    readonly status?: FieldProps["status"];
     /** Full issues-by-path map (FormSnapshot.errors) — passed through for
      *  embedded-list fields, which bucket row-/cell-level issues themselves. */
     readonly allIssues: Readonly<Record<string, readonly FieldIssue[]>>;
@@ -21,6 +24,8 @@ export type GridCellForFieldProps = {
     readonly row: Readonly<Record<string, unknown>>;
     readonly changed?: boolean;
     readonly flow?: boolean;
+    readonly layout?: FieldProps["layout"];
+    readonly accent?: boolean;
 };
 export declare function fieldCellWidth(field: EditFieldViewModel): FieldCellWidth;
-export declare function GridCellForField({ field, columns, issues, onChange, GridCell, featureName, labelAppendix, fieldAppendix, allIssues, valueDisplay, row, changed, flow, }: GridCellForFieldProps): ReactNode;
+export declare function GridCellForField({ field, columns, issues, onChange, GridCell, featureName, labelAppendix, fieldAppendix, appendixPlacement, description, status, allIssues, valueDisplay, row, changed, flow, layout, accent, }: GridCellForFieldProps): ReactNode;

package/dist/components/grid-cell-for-field.js

@@ -29,10 +29,10 @@ export function fieldCellWidth(field) {
         return "full";
     return FIELD_CELL_WIDTH_BY_TYPE[field.type] ?? "text";
 }
-export function GridCellForField({ field, columns, issues, onChange, GridCell, featureName, labelAppendix, fieldAppendix, allIssues, valueDisplay, row, changed, flow, }) {
+export function GridCellForField({ field, columns, issues, onChange, GridCell, featureName, labelAppendix, fieldAppendix, appendixPlacement, description, status, allIssues, valueDisplay, row, changed, flow, layout, accent, }) {
     // RenderField renders nothing for a hidden field, but the GridCell around it still claims the row.
     if (!field.visible)
         return null;
     const effectiveSpan = field.span !== undefined ? Math.min(field.span, columns) : 1;
-    return (_jsx(GridCell, { span: effectiveSpan, ...(flow === true && { width: fieldCellWidth(field) }), children: _jsx(RenderField, { field: field, ...(issues !== undefined && { issues }), onChange: onChange, featureName: featureName, ...(labelAppendix !== undefined && { labelAppendix }), ...(fieldAppendix !== undefined && { fieldAppendix }), allIssues: allIssues, valueDisplay: valueDisplay, row: row, ...(changed === true && { changed }) }) }));
+    return (_jsx(GridCell, { span: effectiveSpan, ...(flow === true && { width: fieldCellWidth(field) }), children: _jsx(RenderField, { field: field, ...(issues !== undefined && { issues }), onChange: onChange, featureName: featureName, ...(labelAppendix !== undefined && { labelAppendix }), ...(fieldAppendix !== undefined && { fieldAppendix }), ...(appendixPlacement !== undefined && { appendixPlacement }), ...(description !== undefined && { description }), ...(status !== undefined && { status }), allIssues: allIssues, valueDisplay: valueDisplay, row: row, ...(changed === true && { changed }), ...(layout !== undefined && { layout }), ...(accent === true && { accent }) }) }));
 }

package/dist/components/multi-select-checkboxes.js

@@ -32,5 +32,8 @@ export function MultiSelectCheckboxes({ field, id, options, value, onChange, })
     };
     return (_jsxs(_Fragment, { children: [_jsx(Button, { type: "button", variant: "secondary", size: "sm", disabled: disabled, onClick: toggleAll, testId: `${id}-select-all`, children: allSelected
                     ? t("kumiko.field.multiSelect.deselect-all")
-                    : t("kumiko.field.multiSelect.select-all") }), _jsx(Grid, { columns: field.columns ?? 2, testId: `${id}-checkboxes`, ...(field.maxRows !== undefined && { maxRows: field.maxRows }), children: options.map((opt) => (_jsx(GridCell, { children: _jsx(Field, { id: `${id}-${opt.value}`, label: opt.label, layout: "inline", children: _jsx(Input, { kind: "boolean", id: `${id}-${opt.value}`, name: `${id}-${opt.value}`, value: selected.has(opt.value), onChange: (checked) => toggleOption(opt.value, checked), disabled: disabled }) }) }, opt.value))) })] }));
+                    : t("kumiko.field.multiSelect.select-all") }), _jsx(Grid, { columns: field.columns ?? 2, testId: `${id}-checkboxes`, 
+                // Field's label targets `id`, which no checkbox carries here; point the
+                // group at Field's `${id}-label` element instead.
+                ariaLabelledBy: `${id}-label`, ...(field.maxRows !== undefined && { maxRows: field.maxRows }), children: options.map((opt) => (_jsx(GridCell, { children: _jsx(Field, { id: `${id}-${opt.value}`, label: opt.label, layout: "inline", children: _jsx(Input, { kind: "boolean", id: `${id}-${opt.value}`, name: `${id}-${opt.value}`, value: selected.has(opt.value), onChange: (checked) => toggleOption(opt.value, checked), disabled: disabled }) }) }, opt.value))) })] }));
 }

package/dist/components/query-options-select.d.ts

@@ -1,12 +1,21 @@
 import type { EditFieldViewModel } from "@cosmicdrift/kumiko-headless";
-import type { ReactNode } from "react";
+import { type OptionsQueryPayload } from "@cosmicdrift/kumiko-types/fields";
+import { type ReactNode } from "react";
+type ResolvedOptionsQueryPayload = Readonly<Record<string, string | number | boolean>>;
+export declare function resolveOptionsQueryPayload(payload: OptionsQueryPayload, row: Readonly<Record<string, unknown>>): ResolvedOptionsQueryPayload;
 type QueryOptionsSelectProps = {
     readonly field: EditFieldViewModel;
     readonly query: string;
-    readonly payload: Readonly<Record<string, string | number | boolean>>;
+    readonly payload: OptionsQueryPayload;
+    readonly row: Readonly<Record<string, unknown>>;
     readonly id: string;
     readonly hasError: boolean;
     readonly onChange: (value: unknown) => void;
 };
-export declare function QueryOptionsSelect({ field, query, payload, id, hasError, onChange, }: QueryOptionsSelectProps): ReactNode;
+export declare function QueryOptionsSelect({ field, query, payload, row, id, hasError, onChange, }: QueryOptionsSelectProps): ReactNode;
+export declare function QueryOptionLabel({ query, payload, value, }: {
+    readonly query: string;
+    readonly payload: ResolvedOptionsQueryPayload;
+    readonly value: string | number | boolean;
+}): ReactNode;
 export {};