@cosmicdrift/kumiko-renderer 0.333.0 → 0.334.0

package/dist/app/config-edit-shim.d.ts

@@ -1,4 +1,5 @@
 import type { ConfigEditScreenDefinition, EntityDefinition, EntityEditScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import * as z from "zod";
 /** Baut eine minimale EntityDefinition aus den Inline-Fields des
  *  ConfigEdit-Screens. RenderEdit + computeEditViewModel iterieren
  *  über entity.fields zur Render-Zeit; alle weiteren EntityDefinition-
@@ -9,3 +10,9 @@ export declare function synthesizeConfigEditEntity(fields: ConfigEditScreenDefin
  *  damit der Type-Constraint hält; entity wird auf den Pseudo-Namen
  *  gepinnt — RenderEdit liest das Feld nicht. */
 export declare function synthesizeConfigEditScreen(screen: ConfigEditScreenDefinition): EntityEditScreenDefinition;
+/** Client-side range check for number keys with declared bounds, so an
+ *  out-of-range value surfaces on its field instead of as the server's
+ *  form-level "Validation failed." banner. Only bounds: required/format stay
+ *  server-authoritative like in buildFormSchema. `.passthrough()` keeps every
+ *  form key visible to the superRefine. */
+export declare function buildConfigEditSchema(fields: ConfigEditScreenDefinition["fields"]): z.ZodType;

package/dist/app/config-edit-shim.js

@@ -12,6 +12,8 @@
 // zukünftiger Boot-Validator die schema.entities-Map cross-referenziert,
 // brechen die Type-Lies hier silent. Dann ist Zeit für eine echte
 // RenderConfigEdit-Komponente die direkt fields nimmt.
+import { I18N_KEY_PARAM } from "@cosmicdrift/kumiko-headless";
+import * as z from "zod";
 const CONFIG_EDIT_PSEUDO_ENTITY = "__config-edit__";
 /** Baut eine minimale EntityDefinition aus den Inline-Fields des
  *  ConfigEdit-Screens. RenderEdit + computeEditViewModel iterieren
@@ -35,3 +37,40 @@ export function synthesizeConfigEditScreen(screen) {
         ...(screen.access !== undefined && { access: screen.access }),
     };
 }
+/** Client-side range check for number keys with declared bounds, so an
+ *  out-of-range value surfaces on its field instead of as the server's
+ *  form-level "Validation failed." banner. Only bounds: required/format stay
+ *  server-authoritative like in buildFormSchema. `.passthrough()` keeps every
+ *  form key visible to the superRefine. */
+export function buildConfigEditSchema(fields) {
+    return z
+        .object({})
+        .passthrough()
+        .superRefine((values, ctx) => {
+        // @cast-boundary form-values
+        const record = values;
+        for (const [name, field] of Object.entries(fields)) {
+            if (field.type !== "number")
+                continue;
+            const value = record[name];
+            if (typeof value !== "number" || !Number.isFinite(value))
+                continue;
+            if (field.min !== undefined && value < field.min) {
+                ctx.addIssue({
+                    code: "custom",
+                    minimum: field.min,
+                    params: { [I18N_KEY_PARAM]: "kumiko.validation.number.min" },
+                    path: [name],
+                });
+            }
+            if (field.max !== undefined && value > field.max) {
+                ctx.addIssue({
+                    code: "custom",
+                    maximum: field.max,
+                    params: { [I18N_KEY_PARAM]: "kumiko.validation.number.max" },
+                    path: [name],
+                });
+            }
+        }
+    });
+}

package/dist/app/kumiko-screen.js

@@ -1,14 +1,16 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { evalFieldCondition, isWriteFormEditSection, metricField, parseRefTarget, } from "@cosmicdrift/kumiko-framework/ui-types";
-import { computeRelatedListSectionViewModel, fieldLabelKey, fieldOptionLabelKey, isSafeHref, } from "@cosmicdrift/kumiko-headless";
+import { buildOptionLabels, computeRelatedListSectionViewModel, fieldLabelKey, fieldOptionLabelKey, isSafeHref, } from "@cosmicdrift/kumiko-headless";
 import { resolveActionIcon } from "@cosmicdrift/kumiko-types/action-icon";
 import { TENANT_CURRENCY_CONFIG_KEY } from "@cosmicdrift/kumiko-types/fields";
 import { Fragment, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { QueryOptionLabel, resolveOptionsQueryPayload, } from "../components/query-options-select.js";
 import { extractCreatedId, extractIdField } from "../components/reference-create-dialog.js";
 import { RenderEdit, resolveRecordTitle, } from "../components/render-edit.js";
 import { needsActionConfirm, RenderEditActionButton, RenderEditActionConfirmDialog, } from "../components/render-edit-action-button.js";
 import { RenderList } from "../components/render-list.js";
 import { useDispatcher, useOptionalDispatcher } from "../context/dispatcher-context.js";
+import { useIsEmbeddedScreen } from "../context/embedded-screen-context.js";
 import { useUserRoles } from "../context/user-roles-context.js";
 import { PAGE_SIZE_OPTIONS, useListUrlState } from "../hooks/use-list-url-state.js";
 import { useQuery } from "../hooks/use-query.js";
@@ -19,7 +21,7 @@ import { statusToneForOptionTone, statusToneForValue, usePrimitives, } from "../
 import { screenFillsHeight } from "../screen-fills-height.js";
 import { synthesizeActionFormEntity, synthesizeActionFormScreen } from "./action-form-shim.js";
 import { useAppFeatures } from "./app-features-context.js";
-import { synthesizeConfigEditEntity, synthesizeConfigEditScreen } from "./config-edit-shim.js";
+import { buildConfigEditSchema, synthesizeConfigEditEntity, synthesizeConfigEditScreen, } from "./config-edit-shim.js";
 import { useCustomScreenComponent } from "./custom-screens.js";
 import { useDashboardBody } from "./dashboard-body.js";
 import { EntityListExpandedRow } from "./entity-list-expanded-row.js";
@@ -32,6 +34,7 @@ import { synthesizeProjectionDetailEntity, synthesizeProjectionDetailScreen, } f
 import { synthesizeProjectionEntity, synthesizeProjectionScreen } from "./projection-list-shim.js";
 import { lastSegment, toKebab } from "./qn.js";
 import { featureNameFromQualifiedScreenId, qualifyScreenId } from "./qualify-screen-id.js";
+import { QueryErrorBanner, QueryLoadingBanner } from "./query-state-banners.js";
 import { ReferenceFacetBridges } from "./reference-facet-bridge.js";
 import { navigateToReturn, navigateToReturnOr, navigateWithReturnTo, ReturnHostProvider, useReturnHost, useReturnTarget, } from "./return-to.js";
 import { buildDefaultEditRowAction, buildProjectionRowActions, buildProjectionToolbarActions, buildRecordActions, evalRowExtractor, isWriteHandlerRowAction, navigateActionSearchParams, refetchAfterWrite, runProjectionRowNavigate, } from "./row-actions.js";
@@ -967,6 +970,7 @@ function EntityListScreen({ schema, screen, translate, onRowClick, }) {
     return (_jsx(EntityListBody, { schema: schema, screen: screen, entity: entity, ...(translate !== undefined && { translate }), ...(onRowClick !== undefined && { onRowClick }) }));
 }
 function EntityListBody({ schema, screen, entity, translate, onRowClick, }) {
+    const isEmbeddedScreen = useIsEmbeddedScreen();
     const featureName = schema.featureName;
     const onCreate = useNavigateToCreateFor(schema, screen.entity, screen.createScreen);
     const { Banner } = usePrimitives();
@@ -1392,7 +1396,9 @@ function EntityListBody({ schema, screen, entity, translate, onRowClick, }) {
     // Bei Infinite-Mode: rows kommen aus accumulated (über mehrere
     // useQuery-Calls gesammelt), bei pages/false aus dem aktuellen Result.
     const renderRows = useInfinite ? accumulated : (rowsQuery.data?.rows ?? []);
-    return (_jsxs(_Fragment, { children: [_jsx(ReferenceFacetBridges, { specs: entityFacetSpecs, onOptions: handleEntityFacetOptions }), _jsx(FacetCountBridges, { queryType: queryType, queries: facetCountQueries, onCount: handleFacetCount }), _jsx(RenderList, { screen: screen, entity: entity, rows: renderRows, featureName: featureName, searchable: searchable, searchValue: urlState.q, onSearchChange: urlState.setQ, sort: effectiveSort, onSortChange: urlState.setSort, screenPadding: true, ...(screenFillsHeight(screen) && { scrollBody: true }), ...(pager !== undefined && { pager }), ...(rowActions !== undefined && { rowActions }), ...(screen.rowActionMode !== undefined && { rowActionMode: screen.rowActionMode }), ...(toolbarActions !== undefined && toolbarActions.length > 0 && { toolbarActions }), ...(useInfinite && {
+    return (_jsxs(_Fragment, { children: [_jsx(ReferenceFacetBridges, { specs: entityFacetSpecs, onOptions: handleEntityFacetOptions }), _jsx(FacetCountBridges, { queryType: queryType, queries: facetCountQueries, onCount: handleFacetCount }), _jsx(RenderList, { screen: screen, entity: entity, rows: renderRows, featureName: featureName, searchable: searchable, searchValue: urlState.q, onSearchChange: urlState.setQ, sort: effectiveSort, onSortChange: urlState.setSort, ...(isEmbeddedScreen
+                    ? { screenPadding: false, chromeless: true }
+                    : { screenPadding: true }), ...(screenFillsHeight(screen) && { scrollBody: true }), ...(pager !== undefined && { pager }), ...(rowActions !== undefined && { rowActions }), ...(screen.rowActionMode !== undefined && { rowActionMode: screen.rowActionMode }), ...(toolbarActions !== undefined && toolbarActions.length > 0 && { toolbarActions }), ...(useInfinite && {
                     onReachEnd: loadMore,
                     loadingMore: rowsQuery.loading,
                     hasMore,
@@ -1420,6 +1426,7 @@ function EntityListBody({ schema, screen, entity, translate, onRowClick, }) {
 // declared here. Pages-mode pagination only — infinite-scroll accumulation
 // isn't wired for projectionList.
 function ProjectionListBody({ schema, screen, translate, onRowClick, }) {
+    const isEmbeddedScreen = useIsEmbeddedScreen();
     const { Banner, Text } = usePrimitives();
     const t = useTranslation();
     const nav = useNav();
@@ -1591,7 +1598,9 @@ function ProjectionListBody({ schema, screen, translate, onRowClick, }) {
             onPageSizeChange: urlState.setPageSize,
         }
         : undefined;
-    return (_jsxs(_Fragment, { children: [_jsx(ReferenceFacetBridges, { specs: facetSpecs, onOptions: handleProjectionFacetOptions }), _jsx(RenderList, { screen: listScreen, entity: entity, rows: rowsQuery.data?.rows ?? [], featureName: schema.featureName, searchable: searchable, searchValue: urlState.q, onSearchChange: urlState.setQ, sort: activeSort, onSortChange: urlState.setSort, screenPadding: true, ...(screenFillsHeight(listScreen) && { scrollBody: true }), ...(pager !== undefined && { pager }), ...(rowActions !== undefined && { rowActions }), ...(screen.rowActionMode !== undefined && { rowActionMode: screen.rowActionMode }), ...(toolbarActions !== undefined && { toolbarActions }), ...(translate !== undefined && { translate }), ...(wrappedOnRowClick !== undefined && { onRowClick: wrappedOnRowClick }), ...(filterFacets.length > 0 && {
+    return (_jsxs(_Fragment, { children: [_jsx(ReferenceFacetBridges, { specs: facetSpecs, onOptions: handleProjectionFacetOptions }), _jsx(RenderList, { screen: listScreen, entity: entity, rows: rowsQuery.data?.rows ?? [], featureName: schema.featureName, searchable: searchable, searchValue: urlState.q, onSearchChange: urlState.setQ, sort: activeSort, onSortChange: urlState.setSort, ...(isEmbeddedScreen
+                    ? { screenPadding: false, chromeless: true }
+                    : { screenPadding: true }), ...(screenFillsHeight(listScreen) && { scrollBody: true }), ...(pager !== undefined && { pager }), ...(rowActions !== undefined && { rowActions }), ...(screen.rowActionMode !== undefined && { rowActionMode: screen.rowActionMode }), ...(toolbarActions !== undefined && { toolbarActions }), ...(translate !== undefined && { translate }), ...(wrappedOnRowClick !== undefined && { onRowClick: wrappedOnRowClick }), ...(filterFacets.length > 0 && {
                     filterFacets,
                     onFilterChange: urlState.setFilter,
                 }), ...(dateRangeFacets.length > 0 && {
@@ -2189,8 +2198,13 @@ function unwrapMoneyValue(value) {
     }
     return value;
 }
+const CONFIG_SCOPE_SOURCE = {
+    user: "user-row",
+    tenant: "tenant-row",
+    system: "system-row",
+};
 function ConfigEditBody({ schema, screen, translate, }) {
-    const { Banner, ConfigCascadeView } = usePrimitives();
+    const { ConfigCascadeView } = usePrimitives();
     const t = useTranslation();
     const effectiveTranslate = translate ?? t;
     const dispatcher = useDispatcher();
@@ -2201,6 +2215,7 @@ function ConfigEditBody({ schema, screen, translate, }) {
     const cascadeQuery = useQuery("config:query:cascade", {});
     const synthEntity = useMemo(() => synthesizeConfigEditEntity(screen.fields), [screen.fields]);
     const synthScreen = useMemo(() => synthesizeConfigEditScreen(screen), [screen]);
+    const boundsSchema = useMemo(() => buildConfigEditSchema(screen.fields), [screen.fields]);
     // Initial-Values: pro Field-Name den Wert aus `values[qualifiedKey]`
     // abholen. Fehlt der Key auf dem Server (= noch nie gesetzt), nutzen
     // wir den Field-Default (createTextField/createNumberField/...).
@@ -2271,7 +2286,20 @@ function ConfigEditBody({ schema, screen, translate, }) {
             const qualified = screen.configKeys[shortName];
             if (qualified === undefined)
                 continue;
-            const ftype = screen.fields[shortName]?.type;
+            const fieldDef = screen.fields[shortName];
+            const ftype = fieldDef?.type;
+            // A query-backed select is cleared to "" when its dependent value became
+            // invalid. config:write:set would store that as an empty override (the
+            // badge shows "Mandant" with no value); reset falls back to the inherited
+            // value. set can't do it: deleting the row is irreversible, reset is
+            // the high-risk handler.
+            if (ftype === "select" && fieldDef?.optionsQuery !== undefined && value === "") {
+                commands.push({
+                    type: "config:write:reset",
+                    payload: { key: qualified, scope: screen.scope },
+                });
+                continue;
+            }
             commands.push({
                 type: "config:write:set",
                 payload: {
@@ -2302,41 +2330,40 @@ function ConfigEditBody({ schema, screen, translate, }) {
         valuesQuery.refetch,
         cascadeQuery.refetch,
     ]);
-    // Cascade-Disclosure (#429): Trigger sitzt in der Label-Row, das Panel
-    // unter dem Input — zwei getrennte Render-Slots teilen sich den
-    // expanded-State, der daher hier (pro Feld) statt in der Komponente lebt.
-    const [expandedFields, setExpandedFields] = useState(new Set());
-    const toggleExpanded = useCallback((fieldName) => {
-        setExpandedFields((prev) => {
-            const next = new Set(prev);
-            if (next.has(fieldName))
-                next.delete(fieldName);
-            else
-                next.add(fieldName);
-            return next;
-        });
-    }, []);
-    if (valuesQuery.loading && valuesQuery.data === null) {
-        return (_jsx(Banner, { padded: true, variant: "loading", testId: "kumiko-screen-loading", children: "Loading\u2026" }));
-    }
+    if (valuesQuery.loading && valuesQuery.data === null)
+        return _jsx(QueryLoadingBanner, {});
     if (valuesQuery.error) {
-        return (_jsx(Banner, { padded: true, variant: "error", testId: "kumiko-screen-error", children: dispatcherErrorText(valuesQuery.error, effectiveTranslate) }));
+        return (_jsx(QueryErrorBanner, { error: valuesQuery.error, translate: effectiveTranslate, onRetry: valuesQuery.refetch }));
     }
-    if (initial === null) {
-        return (_jsx(Banner, { padded: true, variant: "loading", testId: "kumiko-screen-loading", children: "Loading\u2026" }));
-    }
-    return (_jsx(RenderEdit, { screen: synthScreen, entity: synthEntity, featureName: schema.featureName, initial: initial, customSubmit: customSubmit, ...(screenFillsHeight(screen) && { fillScreenHeight: true }), ...(screen.submitLabel !== undefined && { submitLabel: screen.submitLabel }), ...(translate !== undefined && { translate }), labelAppendix: (fieldName) => {
+    if (initial === null)
+        return _jsx(QueryLoadingBanner, {});
+    // Cascade values of a select show the option label the select itself shows,
+    // not the stored value (a UUID for optionsQuery selects).
+    const cascadeValueRenderer = (fieldName) => {
+        const fieldDef = screen.fields[fieldName];
+        if (fieldDef?.type !== "select")
+            return undefined;
+        if (fieldDef.optionsQuery !== undefined) {
+            const query = fieldDef.optionsQuery;
+            const payload = resolveOptionsQueryPayload(fieldDef.optionsQueryPayload ?? {}, initial);
+            return (value) => _jsx(QueryOptionLabel, { query: query, payload: payload, value: value });
+        }
+        if (fieldDef.options.length === 0)
+            return undefined;
+        return (value) => buildOptionLabels(effectiveTranslate, (option) => fieldOptionLabelKey(schema.featureName, synthScreen.entity, fieldName, option), [String(value)])[String(value)];
+    };
+    return (_jsx(RenderEdit, { screen: synthScreen, entity: synthEntity, featureName: schema.featureName, initial: initial, schema: boundsSchema, customSubmit: customSubmit, dirtyFooter: true, validateOnChange: true, ...(screenFillsHeight(screen) && { fillScreenHeight: true }), ...(screen.submitLabel !== undefined && { submitLabel: screen.submitLabel }), ...(translate !== undefined && { translate }), fieldAppendixPlacement: "below-control", fieldAccent: (fieldName) => cascades[fieldName]?.levels.find((level) => level.isActive)?.source ===
+            CONFIG_SCOPE_SOURCE[screen.scope], markChangedFields: true, ...(screen.fieldDescriptions !== undefined && {
+            fieldDescription: (fieldName) => {
+                const key = screen.fieldDescriptions?.[fieldName];
+                return key === undefined ? undefined : effectiveTranslate(key);
+            },
+        }), fieldAppendix: (fieldName) => {
             const cascade = cascades[fieldName];
             if (cascade === undefined)
                 return undefined;
-            return (_jsx(ConfigCascadeView, { slot: "trigger", cascade: cascade, screenScope: screen.scope, expanded: expandedFields.has(fieldName), onToggle: () => toggleExpanded(fieldName) }));
-        }, fieldAppendix: (fieldName) => {
-            const cascade = cascades[fieldName];
-            // Panel nur rendern wenn aufgeklappt — sonst kein leerer Abstand
-            // unter dem Input.
-            if (cascade === undefined || !expandedFields.has(fieldName))
-                return undefined;
-            return (_jsx(ConfigCascadeView, { slot: "panel", cascade: cascade, screenScope: screen.scope, expanded: true, qualifiedKey: screen.configKeys[fieldName], onReset: async (key, scope) => {
+            const renderValue = cascadeValueRenderer(fieldName);
+            return (_jsx(ConfigCascadeView, { cascade: cascade, screenScope: screen.scope, qualifiedKey: screen.configKeys[fieldName], required: screen.requiredFields?.includes(fieldName) ?? false, ...(renderValue !== undefined && { renderValue }), onReset: async (key, scope) => {
                     await dispatcher.write("config:write:reset", { key, scope });
                     await Promise.allSettled([valuesQuery.refetch?.(), cascadeQuery.refetch?.()]);
                 } }));

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/secret-mint-body.js

@@ -113,7 +113,7 @@ 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 (revealed !== null) {
         const values = screen.reveal.fields.flatMap((revealField) => {
@@ -134,7 +134,7 @@ 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") }))] }));
+        return (_jsxs(Card, { options: { screenBody: true }, 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") }))] }));
     }
-    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 }) }));
 }

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, Form, Section, Field, Input, Button, Text, Grid } = usePrimitives();
     const t = useTranslation();
     const effectiveTranslate = translate ?? t;
     const dispatcher = useDispatcher();
@@ -52,25 +62,44 @@ export function SecretsEditBody({ screen, translate }) {
         }
         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 }));
     }
+    // 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(Form, { onSubmit: () => {
             void handleSubmit();
-        }, testId: "secrets-edit-form", ...(screen.description !== undefined && {
+        }, testId: "secrets-edit-form", width: "full", fillHeight: true, stickyActions: true, screenForm: true, unsavedCount: unsavedCount, ...(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
+        }), 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", onClick: () => handleDelete(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") }), _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}`)))] }));
+                                    : "config.secrets.placeholder"), autoComplete: "new-password", disabled: submitting, testId: `secret-input-${fieldId}` }) }, fieldId));
+                    }) }) }, section.title)))] }));
 }

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/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 {};

package/dist/components/query-options-select.js

@@ -1,14 +1,50 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { isOptionsQueryFieldRef } from "@cosmicdrift/kumiko-types/fields";
+import { useEffect, useRef } from "react";
 import { useQuery } from "../hooks/use-query.js";
 import { usePrimitives } from "../primitives.js";
+function isPayloadScalar(value) {
+    return ((typeof value === "string" && value !== "") ||
+        typeof value === "number" ||
+        typeof value === "boolean");
+}
+// An empty sibling value drops its key, so "nothing chosen yet" reaches the query
+// handler as an absent property, not as "" / null.
+export function resolveOptionsQueryPayload(payload, row) {
+    const resolved = {};
+    for (const [name, entry] of Object.entries(payload)) {
+        const value = isOptionsQueryFieldRef(entry) ? row[entry.field] : entry;
+        if (isPayloadScalar(value))
+            resolved[name] = value;
+    }
+    return resolved;
+}
 // Select whose options come from a query (SelectFieldDef.optionsQuery), so it
 // has to be a mounted component for useQuery. useQuery re-fetches on the
 // serialized payload, hence no payload memoization here.
-export function QueryOptionsSelect({ field, query, payload, id, hasError, onChange, }) {
+export function QueryOptionsSelect({ field, query, payload, row, id, hasError, onChange, }) {
     const { Input } = usePrimitives();
-    const { data, loading } = useQuery(query, payload);
+    const resolvedPayload = resolveOptionsQueryPayload(payload, row);
+    const payloadKey = JSON.stringify(resolvedPayload);
+    const { data, loading } = useQuery(query, resolvedPayload);
     const current = typeof field.value === "string" ? field.value : "";
     const rows = data?.rows ?? [];
+    // useQuery keeps the previous data while a changed payload reloads, and a
+    // superseded response is aborted — so a fresh `data` object always belongs to
+    // the payload of the render it arrives in. The first load never clears (a stored
+    // value missing there stays visible); only a load after a payload change does.
+    const settledPayloadKey = useRef(null);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: runs once per loaded result, not on every keystroke
+    useEffect(() => {
+        if (data === null)
+            return;
+        const previousKey = settledPayloadKey.current;
+        settledPayloadKey.current = payloadKey;
+        const payloadChanged = previousKey !== null && previousKey !== payloadKey;
+        if (payloadChanged && current !== "" && !data.rows.some((row) => row.value === current)) {
+            onChange("");
+        }
+    }, [data]);
     // A stored value missing from the result (still loading, or dropped from the
     // catalog) must stay visible instead of silently turning into "nothing selected".
     const options = current !== "" && !rows.some((row) => row.value === current)
@@ -19,3 +55,10 @@ export function QueryOptionsSelect({ field, query, payload, id, hasError, onChan
     const display = field.display === "radio" || field.display === "dropdown" ? field.display : "dropdown";
     return (_jsx(Input, { kind: "select", id: id, name: field.field, disabled: field.readOnly || loading, required: field.required, hasError: hasError, value: current, onChange: (v) => onChange(v), options: options, display: display }));
 }
+// Badge text for a stored value of an optionsQuery select: the row's label once
+// loaded, the raw value while loading or when the value is not in the result.
+export function QueryOptionLabel({ query, payload, value, }) {
+    const { data } = useQuery(query, payload);
+    const label = data?.rows.find((row) => row.value === value)?.label;
+    return label ?? String(value);
+}

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

@@ -306,11 +306,7 @@ export function RelatedListSection({ section, parentId, record, featureName, tra
                         filterValues: filters,
                         onFilterChange,
                         onFilterReset,
-                    }), ...(onRowClick !== undefined && { onRowClick }), ...(rowActions !== undefined && { rowActions }), ...(section.rowActionMode !== undefined && { rowActionMode: section.rowActionMode }), ...(rowGrouping !== undefined && { rowGrouping }), ...(rowTone !== undefined && { rowTone }), ...(toolbarActionButtons !== undefined && { toolbarActions: toolbarActionButtons }), ...(emptyStateContent !== undefined && { emptyState: emptyStateContent }), ...(hideTitle === true && {
-                        scrollBody: true,
-                        screenPadding: false,
-                        chromeless: true,
-                    }), ...(embedded === true && { screenPadding: false, chromeless: true }) }) })] }));
+                    }), ...(onRowClick !== undefined && { onRowClick }), ...(rowActions !== undefined && { rowActions }), ...(section.rowActionMode !== undefined && { rowActionMode: section.rowActionMode }), ...(rowGrouping !== undefined && { rowGrouping }), ...(rowTone !== undefined && { rowTone }), ...(toolbarActionButtons !== undefined && { toolbarActions: toolbarActionButtons }), ...(emptyStateContent !== undefined && { emptyState: emptyStateContent }), screenPadding: false, ...(hideTitle === true && { scrollBody: true, chromeless: true }), ...(embedded === true && { chromeless: true }) }) })] }));
     // 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

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

@@ -88,6 +88,17 @@ export type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
     /** 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;
+    /** Placement of every `fieldAppendix` relative to its control. Default
+     *  above-control; below-control keeps the inputs of neighbouring fields
+     *  on one line when an appendix expands. */
+    readonly fieldAppendixPlacement?: "above-control" | "below-control";
+    /** Per-field help text rendered under the label (translated by the caller). */
+    readonly fieldDescription?: (fieldName: string) => ReactNode | undefined;
+    /** Marks fields whose value is set at this level; drawn by `settings-list` rows. */
+    readonly fieldAccent?: (fieldName: string) => boolean;
+    /** Edit-mode "changed" markers also for screens without an entity id
+     *  (configEdit loads its values from a query, not a record). */
+    readonly markChangedFields?: boolean;
     /** 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
@@ -164,6 +175,15 @@ export type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
      *  screens with `fillHeight !== false`; dialogs and other embedded hosts
      *  omit it and keep document-flow height. */
     readonly fillScreenHeight?: boolean;
+    /** Show the unsaved-changes footer (count, Discard, "Save changes") even
+     *  without an entity id or a screen-height form — for hosts that edit an
+     *  existing server-side record through `customSubmit` (configEdit, also when
+     *  embedded as a dashboard panel). */
+    readonly dirtyFooter?: boolean;
+    /** Validate the edited field right after each change instead of only on
+     *  submit, so a bounds violation shows at the field while the Save button
+     *  looks enabled. Set where Save never blocks on a pre-check (configEdit). */
+    readonly validateOnChange?: 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.