@cosmicdrift/kumiko-renderer 0.333.0 → 0.334.0

package/dist/components/render-edit.js

@@ -162,7 +162,7 @@ function resolveTitleTemplate(template, values, translate, fallback) {
     return translate(template, values);
 }
 export function RenderEdit(props) {
-    const { screen, entity, featureName, initial, writeCommand, translate: translateProp, ctx, schema, onSubmit, payloadMode = "values", buildPayload, serverFieldPathPrefix, onDelete, onCancel, onReload, onDirtyChange, onCopyLink, actions, onRelatedListDrawerAction, submitLabel, submitVariant, footerActions, summary, labelAppendix, fieldAppendix, entityId: entityIdProp, extensionInitialValues, onChange, onControlsReady, fields: fieldsFilter, disabled = false, hideActions, valueDisplay = "form", hideSectionTitles, fillScreenHeight, headerRegion, buildSectionActions, } = props;
+    const { screen, entity, featureName, initial, writeCommand, translate: translateProp, ctx, schema, onSubmit, payloadMode = "values", buildPayload, serverFieldPathPrefix, onDelete, onCancel, onReload, onDirtyChange, onCopyLink, actions, onRelatedListDrawerAction, submitLabel, submitVariant, footerActions, summary, labelAppendix, fieldAppendix, fieldAppendixPlacement, fieldDescription, fieldAccent, markChangedFields = false, entityId: entityIdProp, extensionInitialValues, onChange, onControlsReady, fields: fieldsFilter, disabled = false, hideActions, valueDisplay = "form", hideSectionTitles, fillScreenHeight, dirtyFooter, validateOnChange, headerRegion, buildSectionActions, } = props;
     const { customSubmit } = props;
     // Translate-Fallback: wenn der Caller keine Translate-Fn übergibt,
     // konsumieren wir den i18next-Context direkt. Sonst wären Field-
@@ -569,6 +569,11 @@ export function RenderEdit(props) {
     // keeps normal document-flow height untouched.
     const fillHeight = fillScreenHeight === true ||
         (hideSectionTitles === true && filteredSections[0]?.kind === "relatedList");
+    // A lone writeForm tab is the whole page, so its submit joins this form's
+    // footer (pinned to the window edge like every other screen's save)
+    // instead of sitting in the section's title row.
+    const isLoneWriteFormTab = hideSectionTitles === true && filteredSections[0]?.kind === "writeForm";
+    const [writeFormFooterAction, setWriteFormFooterAction] = useState(undefined);
     // Persistiert alle composed Extension-Sections mit der aufgelösten entityId.
     // false = eine Section schlug fehl (ihr i18n-Key landet im Banner). Ohne
     // Entity-Kontext (create-mode ohne route-id) gibt es nichts zu schreiben.
@@ -872,10 +877,7 @@ export function RenderEdit(props) {
     handleSubmitRef.current = handleSubmit;
     // Screen forms (entityEdit/actionForm filling the shell height) drop the card;
     // the title then lives in the shell header when the shell offers a slot.
-    const isScreenForm = fillScreenHeight === true &&
-        hideSectionTitles !== true &&
-        headerRegion === undefined &&
-        !insideDrawer;
+    const isScreenForm = fillScreenHeight === true && hideSectionTitles !== true && !insideDrawer;
     const titleInShell = PageHeader !== undefined &&
         pageHeaderSlotAvailable &&
         hideSectionTitles !== true &&
@@ -960,8 +962,26 @@ export function RenderEdit(props) {
     const hasFormActions = (isWizard && currentStep > 0) ||
         (isWizard && !isLastWizardStep) ||
         (showsSubmit && (!isWizard || isLastWizardStep)) ||
-        footerSlot !== undefined;
+        footerSlot !== undefined ||
+        writeFormFooterAction !== undefined;
     const nextStepTitle = isWizard ? filteredSections[currentStep + 1]?.title : undefined;
+    const isCreate = (() => {
+        const id = resolveExtensionEntityId(entityIdProp, vm.id);
+        return id == null || id === "";
+    })();
+    const changedFieldCount = Object.keys(snapshot.changes).length;
+    // Edit-mode screen forms always carry the dirty status (0 = quiet "No unsaved
+    // changes"); wizards keep the status-only-when-dirty behaviour.
+    const hasDirtyFooter = !isWizard &&
+        (dirtyFooter === true || (isScreenForm && !isCreate && headerRegion === undefined));
+    const unsavedCount = !hasDirtyFooter
+        ? undefined
+        : changedFieldCount > 0
+            ? changedFieldCount
+            : extensionDirty
+                ? 1
+                : 0;
+    const isSettingsList = screen.layout.variant === "settings-list" && hideSectionTitles !== true;
     const formActions = (_jsxs(_Fragment, { children: [isWizard && currentStep > 0 && (_jsx(Button, { type: "button", variant: "secondary", icon: "chevron-left", onClick: handleWizardBack, testId: "render-edit-wizard-back", children: translate("kumiko.actions.back") })), footerSlot !== undefined && (_jsx(EditSlotMount, { slot: footerSlot, slotName: "footer", screenId: screen.id, entityName: vm.entityName, entityId: resolveExtensionEntityId(entityIdProp, vm.id), values: snapshot.values, hasUnsavedChanges: snapshot.isDirty || extensionDirty, wizardStep: isWizard ? { index: currentStep, isLast: isLastWizardStep } : undefined, ...(screen.slots?.footerPrimary === true && { [STICKY_PRIMARY_ACTION_PROP]: true }) })), isWizard && !isLastWizardStep && showsSubmit && !isCreateMode && (_jsx(Button, { type: "button", variant: "ghost", disabled: isSubmitting || disabled, onClick: () => void handleSubmit({ saveNow: true }), testId: "render-edit-wizard-save-close", [STICKY_PRIMARY_ACTION_PROP]: true, children: translate("kumiko.wizard.save-and-close") })), isWizard && !isLastWizardStep && (_jsx(Button, { type: "submit", variant: "primary", iconEnd: "chevron-right", testId: "render-edit-wizard-next", children: nextStepTitle !== undefined
                     ? translate("kumiko.wizard.next-with-title", { title: nextStepTitle })
                     : translate("kumiko.actions.next") })), showsSubmit &&
@@ -969,9 +989,14 @@ export function RenderEdit(props) {
                 footerActions?.map((action) => (_jsx(Button, { type: "button", variant: action.variant ?? "secondary", ...(action.icon !== undefined && { icon: action.icon }), disabled: isSubmitting || disabled, onClick: () => {
                         controller.setValues(action.patch); // @cast-boundary form-values
                         void handleSubmit();
-                    }, testId: `render-edit-footer-action-${action.id}`, children: translate(action.label) }, action.id))), showsSubmit && (!isWizard || isLastWizardStep) && (_jsx(Button, { type: "submit", disabled: (snapshot.isUnchanged && !extensionDirty && !isFieldless && !insideDrawer) ||
+                    }, testId: `render-edit-footer-action-${action.id}`, children: translate(action.label) }, action.id))), hasDirtyFooter && showsSubmit && unsavedCount !== undefined && unsavedCount > 0 && (_jsx(Button, { type: "button", variant: "ghost", disabled: isSubmitting || disabled, onClick: () => controller.reset(), testId: "render-edit-discard", [STICKY_PRIMARY_ACTION_PROP]: true, children: translate("kumiko.form.discard") })), showsSubmit && (!isWizard || isLastWizardStep) && (_jsx(Button, { type: "submit", disabled: (snapshot.isUnchanged && !extensionDirty && !isFieldless && !insideDrawer) ||
                     isSubmitting ||
-                    disabled, loading: isSubmitting, variant: submitVariant ?? "primary", testId: "render-edit-submit", children: translate(submitLabel ?? (isWizard ? "kumiko.actions.finish" : "kumiko.actions.save")) }))] }));
+                    disabled, loading: isSubmitting, variant: submitVariant ?? "primary", testId: "render-edit-submit", children: translate(submitLabel ??
+                    (isWizard
+                        ? "kumiko.actions.finish"
+                        : hasDirtyFooter
+                            ? "kumiko.form.saveChanges"
+                            : "kumiko.actions.save")) })), writeFormFooterAction] }));
     // Title + Subtitle, create/edit-bewusst. i18n-Keys (mode = "create"|"edit"):
     //   screen:<id>.<mode>.title / .<mode>.subtitle
     // Fallback-Kette: mode-spezifisch → generisch (screen:<id>.title/.subtitle).
@@ -982,10 +1007,6 @@ export function RenderEdit(props) {
     // prose, same as it does for an unknown key (fw#2723 review). Same slot
     // section.description already fills for a section. Falls back to
     // undefined (no subtitle) when neither is set.
-    const isCreate = (() => {
-        const id = resolveExtensionEntityId(entityIdProp, vm.id);
-        return id == null || id === "";
-    })();
     const formMode = isCreate ? "create" : "edit";
     const recordTitle = !isCreate && screen.recordTitleField !== undefined
         ? resolveRecordTitle(initial[screen.recordTitleField])
@@ -1009,18 +1030,14 @@ export function RenderEdit(props) {
         ? (resolveScreenText("subtitle") ??
             (screen.description !== undefined ? translate(screen.description) : undefined))
         : undefined;
+    // Embedded settings-list forms (dashboard panels) have no shell header: the
+    // form title/subtitle move into the first section's header column instead of
+    // floating as a heading above the band.
+    const titleInSettingsHeader = isSettingsList && !titleInShell;
     const usesFieldFlow = isScreenForm || insideDrawer;
     const allRequiredHint = (_jsx(Text, { variant: "muted", testId: "render-edit-all-required-hint", children: translate("kumiko.form.all-required") }));
     const stepRail = isWizard && isScreenForm && StepBar !== undefined;
     const upNextSection = screen.layout.wizard?.aside?.upNext === true ? filteredSections[currentStep + 1] : undefined;
-    const changedFieldCount = isCreate ? 0 : Object.keys(snapshot.changes).length;
-    const unsavedCount = isCreate || !isScreenForm
-        ? 0
-        : changedFieldCount > 0
-            ? changedFieldCount
-            : extensionDirty
-                ? 1
-                : 0;
     const sectionNavItems = isScreenForm && !isStepped
         ? filteredSections.flatMap((section, index) => section.kind !== "extension" &&
             section.kind !== "relatedList" &&
@@ -1046,7 +1063,12 @@ export function RenderEdit(props) {
                     !pageHeaderCompact &&
                     ActionOverflowMenu !== undefined && {
                     actions: (_jsx(ActionOverflowMenu, { label: translate("kumiko.list.row-actions.more"), items: headerMenuItems, testId: "render-edit-header-menu" })),
-                }) })), _jsx(Form, { onSubmit: () => void handleSubmit(), ...(hideSectionTitles !== true && !titleInShell && { title: formTitle }), ...(formSubtitle !== undefined && !stepRail && { subtitle: formSubtitle }), ...(isScreenForm && { screenForm: true }), ...(unsavedCount > 0 && { unsavedCount }), ...(sectionNavItems.length > 0 && { sectionNav: sectionNavItems }), ...(stepRail && {
+                }) })), _jsx(Form, { onSubmit: () => void handleSubmit(), ...(hideSectionTitles !== true &&
+                    !titleInShell &&
+                    !titleInSettingsHeader && { title: formTitle }), ...(formSubtitle !== undefined &&
+                    !stepRail &&
+                    !titleInSettingsHeader && { subtitle: formSubtitle }), ...(isScreenForm && { screenForm: true }), ...(unsavedCount !== undefined &&
+                    (unsavedCount > 0 || hasDirtyFooter) && { unsavedCount }), ...(sectionNavItems.length > 0 && { sectionNav: sectionNavItems }), ...(stepRail && {
                     sideRail: (_jsx(StepBar, { steps: filteredSections.map((section) => section.title ?? ""), currentIndex: currentStep, compactLabel: compactStepLabel, onStepSelect: handleWizardJumpBack, orientation: "vertical", heading: translate("kumiko.wizard.step", {
                             current: currentStep + 1,
                             total: lastStepIndex + 1,
@@ -1153,19 +1175,29 @@ export function RenderEdit(props) {
                                 // Own submit button + dispatcher call, entirely independent of
                                 // this screen's (nonexistent, on projectionDetail) form submit —
                                 // rejected at boot in wizard layouts, so no WizardStepGroup here.
-                                return (_jsx(WriteFormSection, { section: section, featureName: featureName, translate: translate, hideTitle: hideSectionTitles, onSubmitted: () => onReload?.(), ...(sectionActionsEl !== undefined && { actions: sectionActionsEl }) }, section.title ?? `write-form-${sectionIndex}`));
+                                return (_jsx(WriteFormSection, { section: section, featureName: featureName, translate: translate, hideTitle: hideSectionTitles, onSubmitted: () => onReload?.(), ...(isLoneWriteFormTab && { onFooterAction: setWriteFormFooterAction }), ...(sectionActionsEl !== undefined && { actions: sectionActionsEl }) }, section.title ?? `write-form-${sectionIndex}`));
                             }
                             if (!section.visible)
                                 return null;
                             // Titellose Sections kollidieren sonst auf key/testId — Index-Fallback.
                             const sectionKey = section.title ?? `section-${sectionIndex}`;
-                            const renderFieldGrid = (fields, columns, gridKey) => (_jsx(Grid, { columns: columns, ...(usesFieldFlow && { flow: true }), children: fields.map((field) => (_jsx(GridCellForField, { field: disabled ? { ...field, readOnly: true } : field, columns: columns, ...(usesFieldFlow && { flow: true }), issues: snapshot.errors[field.field], onChange: (v) => {
+                            const renderFieldGrid = (fields, columns, gridKey) => (_jsx(Grid, { columns: columns, ...(isSettingsList ? { list: true } : usesFieldFlow && { flow: true }), children: fields.map((field) => (_jsx(GridCellForField, { field: disabled ? { ...field, readOnly: true } : field, columns: columns, ...(!isSettingsList && usesFieldFlow && { flow: true }), ...(isSettingsList && {
+                                        layout: "row",
+                                        accent: fieldAccent?.(field.field) === true,
+                                    }), issues: snapshot.errors[field.field], onChange: (v) => {
                                         controller.setField(field.field, v);
+                                        if (validateOnChange === true)
+                                            controller.validate([field.field]);
                                     }, GridCell: GridCell, featureName: featureName, ...(labelAppendix !== undefined && {
                                         labelAppendix: labelAppendix(field.field),
                                     }), ...(fieldAppendix !== undefined && {
                                         fieldAppendix: fieldAppendix(field.field),
-                                    }), allIssues: snapshot.errors, valueDisplay: valueDisplay, row: snapshot.values, ...(!isCreate && field.field in snapshot.changes && { changed: true }) }, field.field))) }, gridKey));
+                                    }), ...(fieldAppendixPlacement !== undefined && {
+                                        appendixPlacement: fieldAppendixPlacement,
+                                    }), ...(fieldDescription !== undefined && {
+                                        description: fieldDescription(field.field),
+                                    }), allIssues: snapshot.errors, valueDisplay: valueDisplay, row: snapshot.values, ...((!isCreate || markChangedFields) &&
+                                        field.field in snapshot.changes && { changed: true }) }, field.field))) }, gridKey));
                             // Tabs mode: the tab panel is the surface, so field sections render
                             // as unframed padded panels; group cards inside stay framed.
                             // Stays `Card`, not `Section` — Section always flattens to a
@@ -1196,10 +1228,16 @@ export function RenderEdit(props) {
                             // tab label right above it. Without a Tabs primitive the sections
                             // render stacked, and then the titles are what tells them apart.
                             const repeatsTabLabel = isTabs && isStepped;
-                            const sectionTitle = section.title === formTitle || repeatsTabLabel ? undefined : section.title;
+                            const headerFallback = titleInSettingsHeader && sectionIndex === 0;
+                            const sectionTitle = headerFallback
+                                ? (section.title ?? formTitle)
+                                : section.title === formTitle || repeatsTabLabel
+                                    ? undefined
+                                    : section.title;
+                            const sectionSubtitle = section.description ?? (headerFallback ? formSubtitle : undefined);
                             const sectionEl = (_jsxs(Section, { ...(sectionNavItems.some((item) => item.id === formSectionDomId(sectionIndex)) && {
                                     id: formSectionDomId(sectionIndex),
-                                }), ...(sectionTitle !== undefined && { title: sectionTitle }), ...(section.description !== undefined && { subtitle: section.description }), ...(section.icon !== undefined && { icon: section.icon }), ...(sectionActionsEl !== undefined && { actions: sectionActionsEl }), testId: `section-${sectionKey}`, children: [showsAllRequiredHint && insideDrawer && sectionIndex === 0 && allRequiredHint, renderFieldGrid(section.fields, section.columns, `${sectionKey}-grid`)] }, sectionKey));
+                                }), ...(sectionTitle !== undefined && { title: sectionTitle }), ...(sectionSubtitle !== undefined && { subtitle: sectionSubtitle }), ...(section.icon !== undefined && { icon: section.icon }), ...(sectionActionsEl !== undefined && { actions: sectionActionsEl }), ...(isSettingsList && { layout: "settings-list" }), testId: `section-${sectionKey}`, children: [showsAllRequiredHint && insideDrawer && sectionIndex === 0 && allRequiredHint, renderFieldGrid(section.fields, section.columns, `${sectionKey}-grid`)] }, sectionKey));
                             return wrapWizardStep(sectionKey, sectionEl);
                         }), formError !== null && (_jsx(Banner, { variant: "error", testId: "render-edit-form-error", actions: formError.code === "version_conflict" && onReload !== undefined ? (_jsx(Button, { variant: "secondary", onClick: () => {
                                     onReload();

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

@@ -1,5 +1,6 @@
 import { type EditFieldViewModel, type FieldIssue } from "@cosmicdrift/kumiko-headless";
 import { type ReactNode } from "react";
+import { type FieldProps } from "../primitives.js";
 export type RenderFieldProps = {
     readonly field: EditFieldViewModel;
     readonly issues?: readonly FieldIssue[];
@@ -14,6 +15,9 @@ export type RenderFieldProps = {
     /** Optionaler Zusatz-Inhalt der nach dem Input gerendert wird (z.B.
      *  ConfigCascade). */
     readonly fieldAppendix?: ReactNode;
+    readonly appendixPlacement?: FieldProps["appendixPlacement"];
+    readonly description?: ReactNode;
+    readonly status?: FieldProps["status"];
     /** Flat issues-by-path map (FormSnapshot.errors) — only relevant for
      *  type:"embedded" with embeddedListCells, to bucket row-/cell-issues
      *  (`${field}.${rowIndex}` / `${field}.${rowIndex}.${cellField}`).
@@ -33,6 +37,8 @@ export type RenderFieldProps = {
     readonly row?: Readonly<Record<string, unknown>>;
     /** Marks the field as modified against the loaded record (edit mode only). */
     readonly changed?: boolean;
+    readonly layout?: FieldProps["layout"];
+    readonly accent?: boolean;
 };
 export declare const AllFieldsRequiredProvider: import("react").Provider<boolean>;
-export declare function RenderField({ field, issues, onChange, featureName, labelAppendix, fieldAppendix, allIssues, valueDisplay, row, changed, }: RenderFieldProps): ReactNode;
+export declare function RenderField({ field, issues, onChange, featureName, labelAppendix, fieldAppendix, appendixPlacement, description, status, allIssues, valueDisplay, row, changed, layout, accent, }: RenderFieldProps): ReactNode;

package/dist/components/render-field.js

@@ -19,7 +19,7 @@ import { QueryOptionsSelect } from "./query-options-select.js";
 import { ReferenceCreateDialog } from "./reference-create-dialog.js";
 const AllFieldsRequiredContext = createContext(false);
 export const AllFieldsRequiredProvider = AllFieldsRequiredContext.Provider;
-export function RenderField({ field, issues, onChange, featureName, labelAppendix, fieldAppendix, allIssues, valueDisplay = "form", row, changed, }) {
+export function RenderField({ field, issues, onChange, featureName, labelAppendix, fieldAppendix, appendixPlacement, description, status, allIssues, valueDisplay = "form", row, changed, layout, accent, }) {
     const { Field, Input, Banner, Text, JsonView } = usePrimitives();
     // App-Locale (i18n) für money/date-Inputs — sonst fielen sie auf
     // navigator.language (Browser-Sprache) zurück statt der gewählten
@@ -42,7 +42,7 @@ export function RenderField({ field, issues, onChange, featureName, labelAppendi
     // Reference-Field rendert eine eigene Component — sie nutzt
     // useQuery() für den Live-Lookup, also muss sie als React-
     // Komponente gemountet werden (nicht als pure render-Call).
-    const control = field.readOnly && field.renderer !== undefined ? (_jsx(FieldRendererOutput, { field: field, renderer: field.renderer, appLocale: appLocale, ...(row !== undefined && { row }) })) : field.type === "embedded" && field.embeddedListCells !== undefined ? (_jsx(EmbeddedListField, { field: field, id: id, onChange: onChange, allIssues: allIssues ?? {}, featureName: featureName ?? "" })) : field.type === "reference" ? (readOnlyText ? (_jsx(ReadOnlyReferenceValue, { field: field, featureName: featureName ?? "" })) : (_jsx(ReferenceInput, { field: field, id: id, hasError: hasError, onChange: onChange, Input: Input, featureName: featureName ?? "" }))) : field.type === "select" && field.selectOptionsQuery !== undefined && !readOnlyText ? (_jsx(QueryOptionsSelect, { field: field, query: field.selectOptionsQuery.query, payload: field.selectOptionsQuery.payload, id: id, hasError: hasError, onChange: onChange })) : readOnlyText && !isComplexFieldType(field.type) ? (_jsx(Text, { testId: `field-value-${field.field}`, children: readOnlyDisplayText(field, appLocale) })) : (renderInput({
+    const control = field.readOnly && field.renderer !== undefined ? (_jsx(FieldRendererOutput, { field: field, renderer: field.renderer, appLocale: appLocale, ...(row !== undefined && { row }) })) : field.type === "embedded" && field.embeddedListCells !== undefined ? (_jsx(EmbeddedListField, { field: field, id: id, onChange: onChange, allIssues: allIssues ?? {}, featureName: featureName ?? "" })) : field.type === "reference" ? (readOnlyText ? (_jsx(ReadOnlyReferenceValue, { field: field, featureName: featureName ?? "" })) : (_jsx(ReferenceInput, { field: field, id: id, hasError: hasError, onChange: onChange, Input: Input, featureName: featureName ?? "" }))) : field.type === "select" && field.selectOptionsQuery !== undefined && !readOnlyText ? (_jsx(QueryOptionsSelect, { field: field, query: field.selectOptionsQuery.query, payload: field.selectOptionsQuery.payload, row: row ?? { [field.field]: field.value }, id: id, hasError: hasError, onChange: onChange })) : readOnlyText && !isComplexFieldType(field.type) ? (_jsx(Text, { testId: `field-value-${field.field}`, children: readOnlyDisplayText(field, appLocale, t) })) : field.type === "text" && field.writeOnly === true && !readOnlyText ? (_jsx(WriteOnlyTextInput, { field: field, id: id, hasError: hasError, onChange: onChange, changed: changed === true })) : (renderInput({
         field,
         id,
         hasError,
@@ -55,7 +55,33 @@ export function RenderField({ field, issues, onChange, featureName, labelAppendi
         t,
         row,
     }));
-    return (_jsx(Field, { id: id, label: field.label, required: field.required && field.type !== "boolean" && !allFieldsRequired, ...(issues !== undefined && { issues }), ...(labelAppendix !== undefined && { labelAppendix }), ...(fieldAppendix !== undefined && { fieldAppendix }), ...(changed === true && { changed }), testId: `field-${field.field}`, children: control }));
+    return (_jsx(Field, { id: id, label: field.label, required: field.required && field.type !== "boolean" && !allFieldsRequired, ...(issues !== undefined && { issues }), ...(labelAppendix !== undefined && { labelAppendix }), ...(fieldAppendix !== undefined && { fieldAppendix }), ...(appendixPlacement !== undefined && { appendixPlacement }), ...(description !== undefined && { description }), ...(status !== undefined && { status }), ...(changed === true && { changed }), ...(layout !== undefined && { layout }), ...(accent === true && { accent }), testId: `field-${field.field}`, children: control }));
+}
+// Wire value of a writeOnly field is `true` (set) / `null` (empty), never the
+// secret. Typing sets a new value; an untouched or emptied input submits
+// nothing / "" which the server reads as "keep". `null` after a loaded `true`
+// (changed) means "remove on save".
+function WriteOnlyTextInput({ field, id, hasError, onChange, changed, }) {
+    const { Input } = usePrimitives();
+    const t = useTranslation();
+    const isSet = field.value === true;
+    const isMarkedForRemoval = field.value === null && changed;
+    if (isMarkedForRemoval) {
+        return (_jsx(Input, { kind: "password", id: id, name: field.field, disabled: true, hasError: hasError, value: "", onChange: () => { }, autoComplete: "new-password", placeholder: t("kumiko.field.writeOnly.willRemove"), testId: `field-write-only-removal-${field.field}`, trailingAction: {
+                icon: "undo",
+                label: t("kumiko.field.writeOnly.undo"),
+                onPress: () => onChange(true),
+            } }));
+    }
+    return (_jsx(Input, { kind: "password", id: id, name: field.field, disabled: field.readOnly, required: field.required && !isSet, hasError: hasError, value: typeof field.value === "string" ? field.value : "", onChange: (v) => onChange(v), autoComplete: "new-password", ...(isSet && { placeholder: t("kumiko.field.writeOnly.setPlaceholder") }), ...(isSet &&
+            !field.required &&
+            !field.readOnly && {
+            trailingAction: {
+                icon: "clear",
+                label: t("kumiko.field.writeOnly.remove"),
+                onPress: () => onChange(null),
+            },
+        }) }));
 }
 // Where a reference field's option rows come from, and which of their keys
 // holds the display text — the entity's own list handler plus `refLabelField`
@@ -488,10 +514,12 @@ function locatedValue(v) {
 // covered here — it needs a live label lookup, see ReadOnlyReferenceValue.
 // `isComplexFieldType` types aren't covered either — callers keep those on
 // `renderInput`'s existing Banner fallback.
-function readOnlyDisplayText(field, appLocale) {
+function readOnlyDisplayText(field, appLocale, t) {
     const { type, value } = field;
     if (value === undefined || value === null || value === "")
         return "—";
+    if (type === "text" && field.writeOnly === true)
+        return t("kumiko.field.writeOnly.set");
     if (type === "text" && field.format === "password")
         return "••••••••";
     switch (type) {

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

@@ -13,5 +13,9 @@ export type WriteFormSectionProps = {
      *  rendered alongside (before) the section's own submit button in the
      *  title-row actions slot. */
     readonly actions?: ReactNode;
+    /** Set when this section is a whole tab: the submit button is handed to
+     *  the host form's footer (pinned like every other screen's save) instead
+     *  of the section's title row. Called with undefined on unmount. */
+    readonly onFooterAction?: (action: ReactNode | undefined) => void;
 };
-export declare function WriteFormSection({ section, featureName, translate, hideTitle, onSubmitted, actions, }: WriteFormSectionProps): ReactNode;
+export declare function WriteFormSection({ section, featureName, translate, hideTitle, onSubmitted, actions, onFooterAction, }: WriteFormSectionProps): ReactNode;

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

@@ -1,12 +1,12 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { I18N_KEY_PARAM } from "@cosmicdrift/kumiko-headless";
-import { useMemo, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import * as z from "zod";
 import { REQUIRED_FIELD_I18N_KEY } from "../app/form-schema.js";
 import { dispatcherErrorText } from "../app/write-failed-error.js";
 import { useForm } from "../hooks/use-form.js";
 import { useTranslation } from "../i18n.js";
-import { usePrimitives } from "../primitives.js";
+import { STICKY_PRIMARY_ACTION_PROP, usePrimitives } from "../primitives.js";
 import { GridCellForField } from "./grid-cell-for-field.js";
 // Same "has a value" rule as buildFormSchema's isPresent (app/form-schema.ts)
 // — duplicated because that helper walks raw EditFieldSpec + EntityDefinition,
@@ -45,7 +45,7 @@ function buildWriteFormSchema(fields) {
 // would render a second, invalid nested <form> inside the host's own form
 // element — so this mounts its own independent useForm() controller and
 // submits via a plain button click instead of native form submission.
-export function WriteFormSection({ section, featureName, translate, hideTitle, onSubmitted, actions, }) {
+export function WriteFormSection({ section, featureName, translate, hideTitle, onSubmitted, actions, onFooterAction, }) {
     const { Section, Card, Grid, GridCell, Button, Banner } = usePrimitives();
     const t = useTranslation();
     const effectiveTranslate = translate ?? t;
@@ -85,8 +85,20 @@ export function WriteFormSection({ section, featureName, translate, hideTitle, o
     // type="button" (not "submit") is load-bearing: this section is deliberately
     // NOT a nested <form> (see the component doc above), so a "submit" type
     // would instead trigger the host RenderEdit's own form submit.
-    const submitButton = (_jsx(Button, { type: "button", variant: "primary", disabled: isSubmitting, loading: isSubmitting, onClick: () => void handleSubmit(), testId: "write-form-section-submit", children: section.submitLabel ?? effectiveTranslate("kumiko.actions.save") }));
-    const titleRowActions = actions !== undefined ? (_jsxs(_Fragment, { children: [actions, submitButton] })) : (submitButton);
+    // The footer copy of the button outlives this render, so it calls the
+    // latest handleSubmit through a ref instead of capturing a stale closure.
+    const handleSubmitRef = useRef(handleSubmit);
+    handleSubmitRef.current = handleSubmit;
+    const submitLabel = section.submitLabel ?? effectiveTranslate("kumiko.actions.save");
+    const submitButton = (_jsx(Button, { type: "button", variant: "primary", disabled: isSubmitting, loading: isSubmitting, onClick: () => void handleSubmitRef.current(), testId: "write-form-section-submit", [STICKY_PRIMARY_ACTION_PROP]: true, children: submitLabel }));
+    // biome-ignore lint/correctness/useExhaustiveDependencies: submitButton is rebuilt every render; isSubmitting and submitLabel are everything it shows.
+    useEffect(() => {
+        if (onFooterAction === undefined)
+            return;
+        onFooterAction(submitButton);
+        return () => onFooterAction(undefined);
+    }, [onFooterAction, isSubmitting, submitLabel]);
+    const titleRowActions = onFooterAction !== undefined ? (actions) : actions !== undefined ? (_jsxs(_Fragment, { children: [actions, submitButton] })) : (submitButton);
     // Section always flattens to a borderless divider when rendered inside
     // RenderEdit's own <Form> in tabs mode (hideTitle) — an unframed Card panel
     // stands in, like render-edit.tsx's tabs-mode fields/extension branches.

package/dist/context/embedded-screen-context.d.ts

@@ -0,0 +1,5 @@
+import { type ReactNode } from "react";
+export declare function EmbeddedScreenProvider({ children }: {
+    readonly children: ReactNode;
+}): ReactNode;
+export declare function useIsEmbeddedScreen(): boolean;

package/dist/context/embedded-screen-context.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+// A host that already frames and pads the embedded screen (dashboard panel
+// with `chromeless`) marks the subtree, so list screens drop their own
+// screen padding and card frame instead of stacking it on the host's.
+const EmbeddedScreenContext = createContext(false);
+export function EmbeddedScreenProvider({ children }) {
+    return _jsx(EmbeddedScreenContext, { value: true, children: children });
+}
+export function useIsEmbeddedScreen() {
+    return useContext(EmbeddedScreenContext);
+}

package/dist/i18n-defaults.js

@@ -14,6 +14,7 @@ export const kumikoDefaultTranslations = {
         "kumiko.actions.delete": "Delete",
         "kumiko.actions.delete-confirm": "Confirm delete?",
         "kumiko.actions.reload": "Reload",
+        "kumiko.actions.retry": "Try again",
         "kumiko.actions.create": "New",
         "kumiko.actions.edit": "Edit",
         "kumiko.actions.view": "View",
@@ -36,6 +37,11 @@ export const kumikoDefaultTranslations = {
         "kumiko.field.locatedTzHint": "Time local to the given location",
         "kumiko.field.reference-created-no-id": "Record was created but could not be selected automatically. Please select it manually.",
         "kumiko.field.unsupported": "This field type can't be edited here yet.",
+        "kumiko.field.writeOnly.remove": "Remove stored value",
+        "kumiko.field.writeOnly.set": "Set",
+        "kumiko.field.writeOnly.setPlaceholder": "Set — leave empty to keep it",
+        "kumiko.field.writeOnly.undo": "Undo",
+        "kumiko.field.writeOnly.willRemove": "Removed on save",
         "kumiko.field.embedded-list.add-row": "Add row",
         "kumiko.field.embedded-list.remove-row": "Remove row",
         "kumiko.field.embedded-list.duplicate-row": "Duplicate row",
@@ -77,6 +83,9 @@ export const kumikoDefaultTranslations = {
         "kumiko.list.sort.by": "Sorted by {column}",
         "kumiko.form.changed": "changed",
         "kumiko.form.on-this-page": "On this page",
+        "kumiko.form.noUnsavedChanges": "No unsaved changes",
+        "kumiko.form.discard": "Discard",
+        "kumiko.form.saveChanges": "Save changes",
         "kumiko.form.unsaved.one": "1 unsaved change",
         "kumiko.form.unsaved.other": "{count} unsaved changes",
         "kumiko.wizard.next-with-title": "Next: {title}",
@@ -153,16 +162,30 @@ export const kumikoDefaultTranslations = {
         "kumiko.contentEditor.heading2": "Heading 2",
         "kumiko.contentEditor.bulletList": "Bullet list",
         "kumiko.contentEditor.orderedList": "Numbered list",
-        "kumiko.config.source.user": "My value",
+        "kumiko.config.source.user": "Your value",
         "kumiko.config.source.tenant": "Tenant",
-        "kumiko.config.source.system": "System",
+        "kumiko.config.source.system": "Platform",
         "kumiko.config.source.appOverride": "App override",
         "kumiko.config.source.computed": "Computed",
         "kumiko.config.source.default": "Default",
         "kumiko.config.source.missing": "Missing",
-        "kumiko.config.cascade.noValue": "No value set",
-        "kumiko.config.cascade.activeMarker": "active",
-        "kumiko.config.cascade.resetTo": "Reset override ({scope})",
+        "kumiko.config.cascade.noValue": "Not set",
+        "kumiko.config.cascade.noDefault": "not set",
+        "kumiko.config.cascade.notSetRequired": "Not set. Required.",
+        "kumiko.config.cascade.activeMarker": "in use",
+        "kumiko.config.cascade.resetTo": "Reset to default",
+        "kumiko.config.cascade.resetToApp": "Reset to app value",
+        "kumiko.config.cascade.showLevels": "Show all levels",
+        "kumiko.config.cascade.hideLevels": "Hide levels",
+        "kumiko.config.cascade.on": "On",
+        "kumiko.config.cascade.off": "Off",
+        "kumiko.config.cascade.origin.tenant": "Set for this tenant. Default is {value}.",
+        "kumiko.config.cascade.origin.user": "Set by you. Default is {value}.",
+        "kumiko.config.cascade.originNoDefault.tenant": "Set for this tenant.",
+        "kumiko.config.cascade.originNoDefault.user": "Set by you.",
+        "kumiko.config.cascade.originNoDefault.system": "Set for the platform.",
+        "kumiko.config.cascade.origin.system": "Set for the platform. App default is {value}.",
+        "kumiko.config.cascade.origin.default": "Uses the default",
         "kumiko.form.error.generic": "Something went wrong.",
         "kumiko.form.error.version-conflict": "Record was modified in the meantime. Reload and try again.",
         "kumiko.form.extension.save-failed": "A custom field could not be saved.",
@@ -183,6 +206,8 @@ export const kumikoDefaultTranslations = {
         "errors.validation.invalid_type": "Invalid value.",
         "errors.validation.too_small": "Too small or too short (minimum: {minimum}).",
         "errors.validation.too_big": "Too big or too long (maximum: {maximum}).",
+        "kumiko.validation.number.min": "Must be at least {minimum}.",
+        "kumiko.validation.number.max": "Must be {maximum} or less.",
         "errors.validation.invalid_format": "Invalid format.",
         "errors.validation.not_multiple_of": "Must be a multiple of {divisor}.",
         "errors.validation.unrecognized_keys": "Unknown fields.",

package/dist/index.d.ts

@@ -43,6 +43,7 @@ export type { DispatcherProviderProps } from "./context/dispatcher-context.js";
 export { DispatcherProvider, useDispatcher, useDispatcherStatus, useOptionalDispatcher, } from "./context/dispatcher-context.js";
 export type { DraftStorage, DraftStorageProviderProps } from "./context/draft-storage-context.js";
 export { DraftStorageProvider, useDraftStorage } from "./context/draft-storage-context.js";
+export { EmbeddedScreenProvider, useIsEmbeddedScreen } from "./context/embedded-screen-context.js";
 export type { UserRolesProviderProps } from "./context/user-roles-context.js";
 export { UserRolesProvider, useUserRoles } from "./context/user-roles-context.js";
 export { formatWhen } from "./format-when.js";
@@ -67,7 +68,7 @@ export { createStaticLocaleResolver, FormalityProvider, LocaleProvider, mergeTra
 export { kumikoDefaultTranslations } from "./i18n-defaults.js";
 export { InsideDrawerProvider, useInsideDrawer } from "./inside-drawer.js";
 export { PageHeaderCompactProvider, PageHeaderSlotAvailableProvider, usePageHeaderCompact, usePageHeaderSlotAvailable, } from "./page-header-slot.js";
-export type { ActionMenuItemSpec, ActionOverflowMenuProps, AppPrimitives, BannerProps, ButtonProps, CardOptions, CardProps, CardSlots, CopyButtonProps, CorePrimitives, DataTableDateRangeFacet, DataTableFacet, DataTableFacetChip, DataTableProps, DataTableRowAction, DataTableRowActionMode, DataTableRowGrouping, DataTableSort, DataTableSortDir, DialogProps, DrawerProps, EmbeddedListCellType, EmbeddedListColumn, EmbeddedListInputProps, EmbeddedListTotal, FieldCellWidth, FieldProps, FillContainerProps, FormProps, FormSectionNavItem, FormWidth, GridCellProps, GridProps, HeadingProps, InputProps, JsonViewProps, LightboxProps, LinkProps, MetricBandProps, MetricProps, ModalProps, PageHeaderProps, PrimitivesProviderProps, PrimitivesRegistry, ProgressProps, ProgressTone, PromoPanelAction, PromoPanelProps, RuntimeRenderer, SecretRevealProps, SecretRevealValue, SectionProps, ShareButtonProps, StatusBadgeProps, StatusTone, StepBarProps, StickyActionBarProps, StickyPrimaryActionMarker, TabsProps, TextProps, WizardStepGroupProps, } from "./primitives.js";
+export type { ActionMenuItemSpec, ActionOverflowMenuProps, AppPrimitives, BannerProps, ButtonProps, CardOptions, CardProps, CardSlots, CopyButtonProps, CorePrimitives, DataTableDateRangeFacet, DataTableFacet, DataTableFacetChip, DataTableProps, DataTableRowAction, DataTableRowActionMode, DataTableRowGrouping, DataTableSort, DataTableSortDir, DialogProps, DrawerProps, EmbeddedListCellType, EmbeddedListColumn, EmbeddedListInputProps, EmbeddedListTotal, FieldCellWidth, FieldProps, FillContainerProps, FormProps, FormSectionNavItem, FormWidth, GridCellProps, GridProps, HeadingProps, InputProps, JsonViewProps, LightboxProps, LinkProps, MetricBandProps, MetricProps, ModalProps, PageHeaderProps, PrimitivesProviderProps, PrimitivesRegistry, ProgressProps, ProgressTone, PromoPanelAction, PromoPanelProps, RuntimeRenderer, SecretRevealProps, SecretRevealValue, SectionProps, ShareButtonProps, StatusBadgeProps, StatusTone, StepBarProps, StickyActionBarProps, StickyPrimaryActionMarker, TabsProps, TextProps, TrailingInputAction, WizardStepGroupProps, } from "./primitives.js";
 export { PrimitivesProvider, STICKY_PRIMARY_ACTION_PROP, shouldRenderActionsIconOnly, statusToneForOptionTone, statusToneForValue, usePrimitives, } from "./primitives.js";
 export { buildWhatsAppShareUrl } from "./share-links.js";
 export { sortByAccessor } from "./sort-by-accessor.js";

package/dist/index.js

@@ -33,6 +33,7 @@ export { RenderField } from "./components/render-field.js";
 export { RenderList } from "./components/render-list.js";
 export { DispatcherProvider, useDispatcher, useDispatcherStatus, useOptionalDispatcher, } from "./context/dispatcher-context.js";
 export { DraftStorageProvider, useDraftStorage } from "./context/draft-storage-context.js";
+export { EmbeddedScreenProvider, useIsEmbeddedScreen } from "./context/embedded-screen-context.js";
 export { UserRolesProvider, useUserRoles } from "./context/user-roles-context.js";
 export { formatWhen } from "./format-when.js";
 export { REFERENCE_COMBOBOX_LIMIT, REFERENCE_LIST_LOOKUP_LIMIT, REFERENCE_SEARCH_DEBOUNCE_MS, } from "./hooks/reference-limits.js";

package/dist/primitives.d.ts

@@ -123,11 +123,28 @@ export type FieldProps = {
     readonly issues?: readonly FieldIssue[];
     readonly labelAppendix?: ReactNode;
     readonly fieldAppendix?: ReactNode;
+    /** Where `fieldAppendix` sits relative to the control. Default
+     *  `above-control` (a disclosure panel belongs under its label-row
+     *  trigger); `below-control` keeps sibling inputs on one line when the
+     *  appendix is a status line or an expanded detail. */
+    readonly appendixPlacement?: "above-control" | "below-control";
+    /** Help text directly under the label, above the control. */
+    readonly description?: ReactNode;
+    /** Status pill at the right end of the label row (e.g. "Saved", "Not set"). */
+    readonly status?: {
+        readonly tone: StatusTone;
+        readonly label: string;
+        readonly testId?: string;
+    };
     readonly children: ReactNode;
     /** Label-Layout. `stacked` (Default): Label über dem Control. `inline`:
      *  Control + Label nebeneinander (Box links, Label rechts) — für
      *  Checkbox/Switch-Felder (boolean), wie das shadcn-Muster. */
-    readonly layout?: "stacked" | "inline";
+    readonly layout?: "stacked" | "inline" | "row";
+    /** Marks a field whose value is set at this level (differs from the
+     *  inherited one). Only `layout="row"` draws it: a 2px primary line on the
+     *  row's left edge. Ignored by the other layouts. */
+    readonly accent?: boolean;
     /** Collapses the visible label to `sr-only` — stays associated via
      *  `htmlFor` (no separate `aria-label` needed). For tables/grids whose
      *  column header already carries the label for each row. */
@@ -141,6 +158,12 @@ export type FieldProps = {
 /** Discriminated union — jede Input-Sorte hat ihre eigene value/onChange
  *  Signatur. Custom-Impls dispatchen intern, rendern anders (Toggle
  *  statt Checkbox), oder nur einzelne kinds unterschiedlich. */
+export type TrailingInputAction = {
+    readonly icon: "clear" | "undo";
+    readonly label: string;
+    readonly onPress: () => void;
+    readonly testId?: string;
+};
 export type InputProps = {
     readonly kind: "text";
     readonly id: string;
@@ -198,6 +221,9 @@ export type InputProps = {
      *  Browser-Password-Manager nutzen das für die Speicherentscheidung.
      *  Native: textContentType="password" / "newPassword". */
     readonly autoComplete?: "current-password" | "new-password";
+    /** Icon button inside the field's trailing edge (clear a stored value,
+     *  undo a pending removal). `label` is its accessible name + tooltip. */
+    readonly trailingAction?: TrailingInputAction;
     readonly testId?: string;
 } | {
     readonly kind: "number";
@@ -299,8 +325,13 @@ export type InputProps = {
     readonly options: readonly string[] | readonly {
         readonly value: string;
         readonly label: string;
-        /** Second line under the label; shown by `radioVariant="card"`. */
+        /** Muted second line under the label (radio list and dropdown items;
+         *  the dropdown search matches it too). */
         readonly description?: string;
+        /** Group heading. Groups form in order of first occurrence; options
+         *  without a group stay ungrouped and come before all groups. Options
+         *  with description or group never render as a segmented control. */
+        readonly group?: string;
     }[];
     readonly disabled?: boolean;
     readonly required?: boolean;
@@ -837,8 +868,8 @@ export type FormProps = {
      *  detail screens (which also fill the height) do not set it. Native impls
      *  may ignore this prop. */
     readonly screenForm?: boolean;
-    /** Number of unsaved changes, shown in the pinned footer. Omitted in create
-     *  mode and when nothing changed — the footer then shows no status. */
+    /** Number of unsaved changes, shown in the pinned footer; 0 shows the quiet
+     *  "No unsaved changes" status. Omitted (create mode) — no status at all. */
     readonly unsavedCount?: number;
     /** Drawer-hosted forms: context box above the fields. */
     readonly summary?: {
@@ -870,6 +901,9 @@ export type SectionProps = {
      *  title-less/subtitle-less Section still draws the row when `actions`
      *  is set, so a hideTitle tabs-Section with actions isn't stranded. */
     readonly actions?: ReactNode;
+    /** "settings-list": title + subtitle form a left header column and the
+     *  children (field rows) the right one on `md:` and up. Default "stacked". */
+    readonly layout?: "stacked" | "settings-list";
     /** "destructive" marks the Section as a warning/danger area (e.g. account
      *  deletion, restrict processing) — border color only, no content change.
      *  Default "default" (normal card border). */
@@ -920,6 +954,9 @@ export type GridProps = {
     /** Fields flow left to right in wrapping rows sized by `GridCell.width`
      *  instead of equal-width tracks (screen forms and drawers). */
     readonly flow?: boolean;
+    /** One full-width row per child, separated by hairlines — the field rows of
+     *  a `settings-list` section. Wins over `columns`/`flow`. */
+    readonly list?: boolean;
 };
 /** Width class of a field cell inside a `flow` grid: sized by what the field holds. */
 export type FieldCellWidth = "text" | "number" | "money" | "date" | "timestamp" | "select" | "full" | "toggle";
@@ -1036,19 +1073,19 @@ export type ConfigSourceBadgeProps = {
      *  rule as ConfigCascadeView's toDisplayLevels. */
     readonly screenScope?: ConfigScope;
 };
-/** Collapsible cascade-view for a config-edit field. Split into two slots
- *  (#429): "trigger" is the collapsed ▶ + source + value line for the label
- *  row; "panel" is the expanded cascade + reset shown below the input. In
- *  split mode the screen owns the `expanded` state (both slots share it);
- *  without `slot` the component renders both with its own state. */
+/** Cascade view for a config-edit field: one origin line ("Set for this
+ *  tenant", "Uses the default", …), a reset action for an own value, and a
+ *  disclosure listing every level. Owns its disclosure state. */
 export type ConfigCascadeViewProps = {
     readonly cascade: ConfigCascade;
     readonly screenScope: ConfigScope;
     readonly onReset?: (key: string, scope: ConfigScope) => void;
     readonly qualifiedKey?: string;
-    readonly slot?: "trigger" | "panel";
-    readonly expanded?: boolean;
-    readonly onToggle?: () => void;
+    /** The key declares `required: true` — a missing value reads "Not set. Required.". */
+    readonly required?: boolean;
+    /** Display form of a level value (e.g. a select's label instead of its raw
+     *  value). Absent = the raw value; a missing value keeps the no-value text. */
+    readonly renderValue?: (value: string | number | boolean) => ReactNode;
 };
 /** Card-Slots — benannte Inhalts-Regionen, alle optional. Neue Slots später =
  *  rein additiv → Consumer müssen NIE migriert werden. `header` ist der Escape-
@@ -1082,6 +1119,11 @@ export type CardOptions = {
     /** false drops border, background, shadow and radius but keeps padding and
      *  header slots — a panel inside a host surface such as a tab panel. Default true. */
     readonly framed?: boolean;
+    /** The card is the whole screen body (secretMint reveal and done phase):
+     *  no frame, the shared screen insets and width of form screens, children
+     *  stacked with a gap. Without it such a screen sits raw against the
+     *  shell edge. Default false. */
+    readonly screenBody?: boolean;
 };
 /** Generische Card-Chrome (border/bg/radius/shadow + Header/Body/Footer) als
  *  Primitive — eine Quelle für alle Card-Flächen, statt pro App nachgebaut.