@cosmicdrift/kumiko-renderer 0.378.0 → 0.379.0

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

@@ -254,10 +254,13 @@ export function RelatedListSection({ section, parentId, record, featureName, tra
             : { [section.parentParam ?? "id"]: parentId },
         record,
         host,
+        access: { appFeatures, userRoles },
         ...(onOpenDrawer !== undefined && {
             openDrawer: (action) => onOpenDrawer(action, undefined),
         }),
     }), [
+        appFeatures,
+        userRoles,
         section.toolbarActions,
         section.parentParam,
         section.parentFilter,
@@ -319,7 +322,7 @@ export function RelatedListSection({ section, parentId, record, featureName, tra
     const truncated = rowsQuery.data !== null &&
         typeof rowsQuery.data.nextCursor === "string" &&
         (rowsQuery.data.total === undefined || rowsQuery.data.total > rowsQuery.data.rows.length);
-    const content = rowsQuery.loading && rowsQuery.data === null ? (_jsx(Banner, { padded: true, variant: "loading", testId: "related-list-loading", children: "Loading\u2026" })) : rowsQuery.error ? (_jsx(Banner, { padded: true, variant: "error", testId: "related-list-error", children: dispatcherErrorText(rowsQuery.error, effectiveTranslate) })) : (_jsxs(_Fragment, { children: [truncated && (_jsx(Banner, { variant: "info", testId: "related-list-truncated", children: effectiveTranslate("kumiko.list.related-list-truncated", {
+    const content = rowsQuery.loading && rowsQuery.data === null ? (_jsx(Banner, { padded: true, variant: "loading", testId: "related-list-loading", children: t("kumiko.widget.loading") })) : rowsQuery.error ? (_jsx(Banner, { padded: true, variant: "error", testId: "related-list-error", children: dispatcherErrorText(rowsQuery.error, effectiveTranslate) })) : (_jsxs(_Fragment, { children: [truncated && (_jsx(Banner, { variant: "info", testId: "related-list-truncated", children: effectiveTranslate("kumiko.list.related-list-truncated", {
                     count: sortedRows.length,
                 }) })), emptyStateActionError !== null && (_jsx(Banner, { variant: "error", testId: "related-list-empty-state-action-error", children: emptyStateActionError })), _jsx(PageHeaderSlotAvailableProvider, { value: false, children: _jsx(RenderList, { screen: listScreen, entity: entity, rows: sortedRows, featureName: listFeatureName ?? featureName, translate: effectiveTranslate, ...(section.description !== undefined && { description: section.description }), ...(section.itemNoun !== undefined && { itemNounKey: section.itemNoun }), sort: sort, onSortChange: setSort, ...(section.searchable === true && {
                         searchable: true,

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

@@ -3,7 +3,7 @@ export declare function hasEditableSection(sections: readonly EditSectionViewMod
 export declare function resolveExtensionEntityId(entityIdProp: string | null | undefined, vmId: string | null): string | null;
 export declare function shouldNotifyCaller(result: SubmitResult<unknown>, extensionsPersisted: boolean): boolean;
 export declare function issueRootField(path: string): string;
-export declare function hasIssueWithoutRenderedField(issuePaths: readonly string[], sections: readonly EditSectionViewModel[]): boolean;
+export declare function hasIssueWithoutRenderedField(issuePaths: readonly string[], sections: readonly EditSectionViewModel[], derivedTargets?: ReadonlySet<string>): boolean;
 export declare function hasIssueWithoutVisibleField(issuePaths: readonly string[], fields: readonly EditFieldViewModel[]): boolean;
 export declare function findFirstErroringSectionIndex(sections: readonly EditSectionViewModel[], issuePaths: readonly string[]): number | undefined;
 export declare function filterEditSections(sections: readonly EditSectionViewModel[], fieldsFilter: readonly string[] | undefined): readonly EditSectionViewModel[];

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

@@ -32,9 +32,15 @@ export function issueRootField(path) {
     return path.split(".")[0] ?? path;
 }
 // No issues at all counts as unmatched, so the caller keeps the banner.
-export function hasIssueWithoutRenderedField(issuePaths, sections) {
+// `derivedTargets` are head fields the form computes (actionForm `derive`): an
+// issue on one is a knock-on of another issue (an empty list leaves the total
+// without a value), nobody can fix it there. It is ignored while another issue
+// exists, so the banner does not bury the real one; alone it keeps the banner.
+export function hasIssueWithoutRenderedField(issuePaths, sections, derivedTargets = new Set()) {
+    const fixablePaths = issuePaths.filter((path) => !derivedTargets.has(issueRootField(path)));
+    const paths = fixablePaths.length > 0 ? fixablePaths : issuePaths;
     const renderedFields = sections.flatMap((s) => s.kind === "fields" && s.visible ? s.fields : []);
-    return hasIssueWithoutVisibleField(issuePaths, renderedFields);
+    return hasIssueWithoutVisibleField(paths, renderedFields);
 }
 export function hasIssueWithoutVisibleField(issuePaths, fields) {
     if (issuePaths.length === 0)

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

@@ -207,6 +207,9 @@ export type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
     /** actionForm `derive`: derived fields are recomputed into the form state on every
      *  change and render read-only. */
     readonly formDerivation?: FormDerivationScreen;
+    /** QN of the actionForm screen this form renders; its file fields upload as pending for that
+     *  screen. Unset for entityEdit and for secretMint/confirm forms, which take no uploads. */
+    readonly actionFormScreenQn?: string;
     /** 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

package/dist/components/render-edit.js

@@ -16,6 +16,7 @@ import { formatWhen } from "../format-when.js";
 import { useForm } from "../hooks/use-form.js";
 import { useTranslation } from "../i18n.js";
 import { useInsideDrawer } from "../inside-drawer.js";
+import { useUnsavedInputSource } from "../leave-guard.js";
 import { usePageHeaderCompact, usePageHeaderSlotAvailable } from "../page-header-slot.js";
 import { FOOTER_ACTION_ROLE_PROP, NARROW_LABEL_PROP, STICKY_PRIMARY_ACTION_PROP, shouldRenderActionsIconOnly, usePrimitives, } from "../primitives.js";
 import { GridCellForField } from "./grid-cell-for-field.js";
@@ -30,7 +31,7 @@ const FORM_DRAFT_GET = "form-draft:query:get";
 const FORM_DRAFT_SAVE = "form-draft:write:save";
 const FORM_DRAFT_DISCARD = "form-draft:write:discard";
 const FORM_DRAFT_LIST = "form-draft:query:list";
-// Mirrors bundled-features/src/form-draft/constants.ts's FORM_DRAFT_KEY_MAX_LENGTH
+// Mirrors bundled-features/src/form-draft/web/constants.ts's FORM_DRAFT_KEY_MAX_LENGTH
 // — same hardcoding rationale as the QNs above (no dependency on that package).
 const FORM_DRAFT_KEY_MAX_LENGTH = 256;
 // Trailing-edge debounce for patch()-triggered draft saves (#1914). A single
@@ -49,7 +50,7 @@ function newDraftPrefix(screenId) {
     return `${screenId}:new:`;
 }
 // `crypto.randomUUID` is missing in non-secure contexts and React Native/Hermes
-// without a polyfill — guard like dispatcher-live.ts's generateRequestId.
+// without a polyfill — guard like generateRequestId in headless/dispatcher/request-id.ts.
 function mintDraftId() {
     const webCrypto = propertyOf(globalThis, "crypto");
     const randomUUID = propertyOf(webCrypto, "randomUUID");
@@ -230,7 +231,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, refreshToken, onDirtyChange, onCopyLink, actions, menuActions, onRelatedListDrawerAction, submitLabel, submitVariant, submitWithoutChanges, footerActions, summary, labelAppendix, fieldAppendix, fieldAppendixPlacement, fieldDescription, fieldAccent, markChangedFields = false, entityId: entityIdProp, extensionInitialValues, onChange, onControlsReady, fields: fieldsFilter, disabled: disabledProp = false, viewMode = false, hideActions, valueDisplay = "form", hideSectionTitles, fillScreenHeight, dirtyFooter, validateOnChange, headerRegion, buildSectionActions, leadContent, submitBlocked = false, formDerivation, } = props;
+    const { screen, entity, featureName, initial, writeCommand, translate: translateProp, ctx, schema, onSubmit, payloadMode = "values", buildPayload, serverFieldPathPrefix, onDelete, onCancel, onReload, refreshToken, onDirtyChange, onCopyLink, actions, menuActions, onRelatedListDrawerAction, submitLabel, submitVariant, submitWithoutChanges, footerActions, summary, labelAppendix, fieldAppendix, fieldAppendixPlacement, fieldDescription, fieldAccent, markChangedFields = false, entityId: entityIdProp, extensionInitialValues, onChange, onControlsReady, fields: fieldsFilter, disabled: disabledProp = false, viewMode = false, hideActions, valueDisplay = "form", hideSectionTitles, fillScreenHeight, dirtyFooter, validateOnChange, headerRegion, buildSectionActions, leadContent, submitBlocked = false, formDerivation, actionFormScreenQn, } = props;
     // View mode is a locked form, so everything keyed on `disabled` follows.
     const disabled = disabledProp || viewMode;
     const i18nScreenId = props.i18nScreenId ?? screen.id;
@@ -255,6 +256,7 @@ export function RenderEdit(props) {
     const [confirmDeleteOpen, setConfirmDeleteOpen] = useState(false);
     const [linkCopied, setLinkCopied] = useState(false);
     const [isSubmitting, setIsSubmitting] = useState(false);
+    const [focusFirstErrorKey, setFocusFirstErrorKey] = useState(0);
     const [formError, setFormError] = useState(null);
     // Only a submit's validation/server error is cleared by editing; a delete
     // rejection and a version conflict (reload is the way out) stay put.
@@ -305,9 +307,12 @@ export function RenderEdit(props) {
     // never enters `fields`/`controller.getSnapshot().values` — there is no
     // draft-blob-covered state left for persistExtensions() to compete over.
     const [extensionDirty, setExtensionDirty] = useState(false);
+    // Mirror for the leave guard: it must see "saved" before React re-renders.
+    const extensionDirtyRef = useRef(false);
     const [hasExtensionRegistrations, setHasExtensionRegistrations] = useState(false);
     const [extensionErrorKey, setExtensionErrorKey] = useState(null);
     const { registry: extensionFormRegistry, runAll: runExtensionSubmits } = useExtensionFormHost(({ anyDirty, hasRegistrations }) => {
+        extensionDirtyRef.current = anyDirty;
         setExtensionDirty(anyDirty);
         setHasExtensionRegistrations(hasRegistrations);
     });
@@ -552,6 +557,9 @@ export function RenderEdit(props) {
     useEffect(() => {
         onDirtyChangeRef.current?.(hasUnsavedInput);
     }, [hasUnsavedInput]);
+    // Draft wizards keep their input server-side, so leaving loses nothing.
+    const persistsDraft = isWizard && screen.layout.draft === true;
+    useUnsavedInputSource(() => !persistsDraft && (controller.getSnapshot().isDirty || extensionDirtyRef.current));
     useEffect(() => {
         // skip: this screen does not persist a draft.
         if (!draftEnabled || dispatcher === undefined)
@@ -666,8 +674,10 @@ export function RenderEdit(props) {
         mode: writeVerb,
         ...(!isCreateMode && entityIdProp != null && { entityId: entityIdProp }),
         ...(formDerivation !== undefined && { derivation: formDerivation }),
+        ...(actionFormScreenQn !== undefined && { actionFormScreenQn }),
     }), [
         formDerivation,
+        actionFormScreenQn,
         screen,
         entity,
         snapshot.values,
@@ -975,6 +985,7 @@ export function RenderEdit(props) {
                 // Same discard as the main path: an extension-only save is still a
                 // successful submit, so the draft must not survive it.
                 if (await persistExtensions()) {
+                    extensionDirtyRef.current = false;
                     submittedRef.current = true;
                     await discardDraft();
                 }
@@ -1036,8 +1047,11 @@ export function RenderEdit(props) {
                     await discardDraft();
                 }
                 extensionsPersisted = await persistExtensions();
+                if (extensionsPersisted)
+                    extensionDirtyRef.current = false;
             }
             else if (result.validationBlocked) {
+                setFocusFirstErrorKey((key) => key + 1);
                 // Root-level `.refine()`/cross-field issues from controller.validate()
                 // — same "jump to the erroring step" treatment as a server field
                 // error below, sourced from the freshly-validated snapshot.
@@ -1050,6 +1064,8 @@ export function RenderEdit(props) {
             else {
                 const fieldIssues = result.error.details?.fields ?? [];
                 const issuePaths = fieldIssues.map((i) => i.path);
+                if (fieldIssues.length > 0)
+                    setFocusFirstErrorKey((key) => key + 1);
                 // controller.submit() writes server issues into the controller itself;
                 // customSubmit bypasses it, so push them here to reach the fields.
                 if (customSubmit !== undefined && fieldIssues.length > 0) {
@@ -1069,7 +1085,9 @@ export function RenderEdit(props) {
                 }
                 setExtraDeleteIssues([]);
                 setFormErrorSource("submit");
-                setFormError(hasIssueWithoutRenderedField(issuePaths, filteredSections) ? result.error : null);
+                setFormError(hasIssueWithoutRenderedField(issuePaths, filteredSections, new Set(Object.keys(formDerivation?.derive ?? {})))
+                    ? result.error
+                    : null);
             }
             // skip: on entity-success-but-extension-failure the extension-error
             // banner is showing — don't notify (the caller navigates away on success
@@ -1304,7 +1322,7 @@ 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 &&
+                }) })), _jsx(Form, { onSubmit: () => void handleSubmit(), ...(focusFirstErrorKey > 0 && { focusFirstErrorKey }), ...(hideSectionTitles !== true &&
                     !titleInShell &&
                     !titleInSettingsHeader &&
                     !recordTitleInHeaderRegion && { title: formTitle }), ...(formSubtitle !== undefined &&
@@ -1444,7 +1462,8 @@ export function RenderEdit(props) {
                                         appendixPlacement: fieldAppendixPlacement,
                                     }), ...(fieldDescription !== undefined && {
                                         description: fieldDescription(field.field),
-                                    }), allIssues: snapshot.errors, valueDisplay: valueDisplay, row: snapshot.values, ...(disabled && { fillDisabled: true }), ...((!isCreate || markChangedFields) &&
+                                    }), allIssues: snapshot.errors, valueDisplay: valueDisplay, row: snapshot.values, ...(disabled && { fillDisabled: true }), ...(hideSectionTitles !== true &&
+                                        section.title !== undefined && { sectionTitle: section.title }), ...((!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.

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

@@ -42,6 +42,8 @@ export type RenderFieldProps = {
     /** The surrounding form is locked as a whole: the fill button stays visible
      *  but inert, unlike a single readOnly field whose fill button keeps working. */
     readonly fillDisabled?: boolean;
+    /** Label stays for screen readers only (sr-only). */
+    readonly hideLabel?: boolean;
 };
 export declare const AllFieldsRequiredProvider: import("react").Provider<boolean>;
-export declare function RenderField({ field, issues, onChange, featureName, labelAppendix, fieldAppendix, appendixPlacement, description, status, allIssues, valueDisplay, row, changed, layout, accent, fillDisabled, }: RenderFieldProps): ReactNode;
+export declare function RenderField({ field, issues, onChange, featureName, labelAppendix, fieldAppendix, appendixPlacement, description, status, allIssues, valueDisplay, row, changed, layout, accent, fillDisabled, hideLabel, }: RenderFieldProps): ReactNode;

package/dist/components/render-field.js

@@ -1,5 +1,5 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { isFormatSpec, SYSTEM_REFERENCE_LABELS, } from "@cosmicdrift/kumiko-framework/ui-types";
+import { isFormatSpec, SYSTEM_REFERENCE_LABELS, UNRESOLVED_REFERENCE_LABEL_KEYS, } from "@cosmicdrift/kumiko-framework/ui-types";
 import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { createContext, Fragment, useCallback, useContext, useEffect, useMemo, useRef, useState, } from "react";
 import { useAppFeatures } from "../app/app-features-context.js";
@@ -26,7 +26,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, appendixPlacement, description, status, allIssues, valueDisplay = "form", row, changed, layout, accent, fillDisabled, }) {
+export function RenderField({ field, issues, onChange, featureName, labelAppendix, fieldAppendix, appendixPlacement, description, status, allIssues, valueDisplay = "form", row, changed, layout, accent, fillDisabled, hideLabel, }) {
     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
@@ -49,6 +49,11 @@ 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).
+    // The list input prints its own list-level issues (empty state included), so
+    // the Field wrapper must not print them a second time.
+    const listPrintsOwnIssues = field.type === "embedded" &&
+        field.embeddedListCells !== undefined &&
+        !(field.readOnly && field.renderer !== undefined);
     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 })) : field.type === "select" &&
         field.selectOptionsAvailabilityQuery !== undefined &&
         !readOnlyText ? (_jsx(AvailabilityOptionsSelect, { field: field, query: field.selectOptionsAvailabilityQuery.query, payload: field.selectOptionsAvailabilityQuery.payload, row: row ?? { [field.field]: field.value }, id: id, hasError: hasError, onChange: onChange })) : readOnlyText && !isComplexFieldType(field.type) && !isFileFieldType(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 })) : field.fillAction !== undefined ? (_jsx(FillActionControl, { field: field, fillAction: field.fillAction, row: row ?? { [field.field]: field.value }, onChange: onChange, disabled: fillDisabled === true, Banner: Banner, renderControl: (fill) => renderInput({
@@ -77,7 +82,7 @@ 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 }), ...(appendixPlacement !== undefined && { appendixPlacement }), ...(description !== undefined && { description }), ...(status !== undefined && { status }), ...(changed === true && { changed }), ...(layout !== undefined && { layout }), ...(accent === true && { accent }), testId: `field-${field.field}`, children: control }));
+    return (_jsx(Field, { id: id, label: field.label, required: field.required && field.type !== "boolean" && !allFieldsRequired, ...(issues !== undefined && !listPrintsOwnIssues && { 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 }), ...(hideLabel === true && { hideLabel }), testId: `field-${field.field}`, children: control }));
 }
 const NUMERIC_FIELD_TYPES = new Set(["number", "bigInt", "decimal"]);
 // A text field takes a number as its string form; a numeric field takes only a
@@ -347,12 +352,17 @@ function ReadOnlyReferenceValue({ field, featureName, }) {
     // instead of the raw id.
     const systemLabel = SYSTEM_REFERENCE_LABELS[`${refFeature}:${refEntity}`];
     const parts = ids.map((id) => {
-        if (systemLabel !== undefined && id === systemLabel.id) {
+        if (systemLabel !== undefined && (id === systemLabel.id || systemLabel.aliases?.includes(id))) {
             return { id, label: t(systemLabel.labelKey), link: undefined };
         }
         const row = rows.find((r) => String(r["id"] ?? "") === id);
-        if (row === undefined)
-            return { id, label: id, link: undefined };
+        if (row === undefined) {
+            const unknownKey = UNRESOLVED_REFERENCE_LABEL_KEYS[`${refFeature}:${refEntity}`];
+            const label = unknownKey !== undefined && !queryResult.loading && queryResult.error === null
+                ? t(unknownKey)
+                : id;
+            return { id, label, link: undefined };
+        }
         return { id, label: String(row[labelKey] ?? id), link: resolveReferenceLink(refEntity, id) };
     });
     return (_jsx(Text, { testId: `field-value-${field.field}`, children: parts.map(({ id, label, link }, index) => (_jsxs(Fragment, { children: [index > 0 && ", ", link === undefined ? (label) : (_jsx(Link, { href: link.href, onPress: link.onPress, testId: `field-link-${field.field}-${id}`, children: label }))] }, id))) }));
@@ -478,7 +488,9 @@ function renderInput({ field, id, hasError, onChange, Input, appLocale, Banner,
         case "image": {
             const kind = field.type === "image" ? "image" : "file";
             const fileId = typeof field.value === "string" && field.value !== "" ? field.value : null;
-            return (_jsx(Input, { kind: kind, ...common, value: fileId, onChange: (v) => onChange(v), ...(field.accept !== undefined && { accept: field.accept }), ...(field.maxSize !== undefined && { maxSize: field.maxSize }), ...(field.entityType !== undefined && { entityType: field.entityType }), ...(field.entityId !== undefined && { entityId: field.entityId }), ...(field.fieldName !== undefined && { fieldName: field.fieldName }), ...(field.imageVariant !== undefined && { imageVariant: field.imageVariant }), ...(field.capture !== undefined && { capture: field.capture }) }));
+            return (_jsx(Input, { kind: kind, ...common, value: fileId, onChange: (v) => onChange(v), ...(field.accept !== undefined && { accept: field.accept }), ...(field.maxSize !== undefined && { maxSize: field.maxSize }), ...(field.entityType !== undefined && { entityType: field.entityType }), ...(field.uploadActionForm !== undefined && {
+                    uploadActionForm: field.uploadActionForm,
+                }), ...(field.entityId !== undefined && { entityId: field.entityId }), ...(field.fieldName !== undefined && { fieldName: field.fieldName }), ...(field.imageVariant !== undefined && { imageVariant: field.imageVariant }), ...(field.capture !== undefined && { capture: field.capture }) }));
         }
         case "files":
         case "images":

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

@@ -1,4 +1,4 @@
-import type { EntityDefinition, EntityListScreenDefinition, IconKey } from "@cosmicdrift/kumiko-framework/ui-types";
+import { type EntityDefinition, type EntityListScreenDefinition, type IconKey } from "@cosmicdrift/kumiko-framework/ui-types";
 import { type ReactNode } from "react";
 import type { ListRowViewModel, Translate } from "../headless/index.ts";
 import type { ListSort } from "../hooks/use-list-url-state.ts";
@@ -34,6 +34,8 @@ export type RenderListProps = {
     readonly emptyContent?: ListEmptyStateContent;
     /** Search or filters changed the result; the empty box then says "no matches". */
     readonly narrowed?: boolean;
+    /** Nothing was narrowed by the user, but a default filter is still on; the empty box then offers "show all" instead of "create the first one". */
+    readonly defaultFilterActive?: boolean;
     /** Plural-forms key for the footer count noun; default is the entity's `:noun` convention key. */
     readonly itemNounKey?: string;
     /** Aktueller Search-Term (vom URL-State / Parent). RenderList puffert

package/dist/components/render-list.js

@@ -1,4 +1,5 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { UNRESOLVED_REFERENCE_LABEL_KEYS, } from "@cosmicdrift/kumiko-framework/ui-types";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { extensionSectionName, useExtensionSectionComponent } from "../app/extension-sections.js";
 import { useReferenceLinkResolver } from "../app/reference-link.js";
@@ -15,7 +16,7 @@ function isHeaderPromotableToolbarAction(action) {
     return action.style === "primary" && !needsActionConfirm(action);
 }
 export function RenderList(props) {
-    const { screen, entity, rows, featureName, translate: translateProp, onRowClick, emptyState, onCreate, createLabel, searchable = false, searchPlaceholder, description, emptyContent, narrowed = false, itemNounKey, searchValue, onSearchChange, sort, onSortChange, pager, onReachEnd, loadingMore, hasMore, rowActions, rowActionMode, rowGrouping, rowTone, toolbarActions, filterFacets, filterValues, onFilterChange, onFilterReset, dateRangeFacets, onDateRangeChange, chromeless, scrollBody, screenPadding, expandedRowIds, onToggleRowExpanded, renderExpandedRow, } = props;
+    const { screen, entity, rows, featureName, translate: translateProp, onRowClick, emptyState, onCreate, createLabel, searchable = false, searchPlaceholder, description, emptyContent, narrowed = false, defaultFilterActive: defaultFilterActiveProp = false, itemNounKey, searchValue, onSearchChange, sort, onSortChange, pager, onReachEnd, loadingMore, hasMore, rowActions, rowActionMode, rowGrouping, rowTone, toolbarActions, filterFacets, filterValues, onFilterChange, onFilterReset, dateRangeFacets, onDateRangeChange, chromeless, scrollBody, screenPadding, expandedRowIds, onToggleRowExpanded, renderExpandedRow, } = props;
     // Wie RenderEdit: Translate-Fallback aus dem i18next-Context, sonst
     // wären Column-Header raw i18n-Keys.
     const t = useTranslation();
@@ -101,6 +102,14 @@ export function RenderList(props) {
             if (col.renderer !== undefined)
                 return col;
             const map = referenceLookups[col.field];
+            const unknownKey = UNRESOLVED_REFERENCE_LABEL_KEYS[`${col.refFeature ?? featureName}:${col.refEntity ?? ""}`];
+            // No raw id for entities that opt in: a placeholder while the lookup
+            // loads, the "unknown" label once it found nothing.
+            const unresolvedLabel = (id) => unknownKey === undefined
+                ? id
+                : map === undefined
+                    ? EMPTY_VALUE_PLACEHOLDER
+                    : translate(unknownKey);
             const labelField = col.refLabelField ?? "id";
             const refEntity = col.refEntity ?? "";
             // Only a row the user can see is linkable: resolved by the server
@@ -126,7 +135,7 @@ export function RenderList(props) {
                 return value.map((v) => {
                     const id = String(v);
                     const target = eagerById.get(id);
-                    const label = String(target?.[labelField] ?? map?.get(id) ?? id);
+                    const label = String(target?.[labelField] ?? map?.get(id) ?? unresolvedLabel(id));
                     // Only a row the user can see is linkable: server eagerload or lookup query.
                     const link = target !== undefined || map?.has(id) === true
                         ? resolveReferenceLink(refEntity, id)
@@ -151,16 +160,23 @@ export function RenderList(props) {
                 if (Array.isArray(value)) {
                     if (value.length === 0)
                         return EMPTY_VALUE_PLACEHOLDER;
-                    return value.map((v) => map?.get(String(v)) ?? String(v)).join(", ");
+                    return value.map((v) => map?.get(String(v)) ?? unresolvedLabel(String(v))).join(", ");
                 }
                 if (value === null || value === undefined || value === "")
                     return EMPTY_VALUE_PLACEHOLDER;
                 const idStr = String(value);
-                return map?.get(idStr) ?? idStr;
+                return map?.get(idStr) ?? unresolvedLabel(idStr);
             };
             return { ...col, renderer, linkFor, linkItemsFor };
         });
-    }, [vm.columns, referenceColumns, referenceLookups, resolveReferenceLink]);
+    }, [
+        vm.columns,
+        referenceColumns,
+        referenceLookups,
+        resolveReferenceLink,
+        featureName,
+        translate,
+    ]);
     const enrichedVm = useMemo(() => ({
         ...vm,
         columns: enrichedColumns,
@@ -205,8 +221,9 @@ export function RenderList(props) {
     // Button. Caller kann via emptyState-Prop komplett überschreiben.
     // Wenn weder onCreate noch ein Override gegeben ist, fällt die
     // DataTable auf den DataTable-Default zurück (`kumiko.list.no-entries`).
+    const defaultFilterActive = defaultFilterActiveProp && onFilterReset !== undefined;
     const composedEmptyState = emptyState ??
-        (onCreate !== undefined || emptyContent !== undefined || narrowed ? (_jsx(ListEmptyStateBody, { content: emptyContent, narrowed: narrowed, translate: translate, createButton: onCreate !== undefined && !narrowed && !createInPageHeader ? (_jsx(Button, { variant: "primary", icon: "plus", onClick: onCreate, testId: "render-list-empty-create", children: effectiveCreateLabel })) : undefined })) : undefined);
+        (onCreate !== undefined || emptyContent !== undefined || narrowed || defaultFilterActive ? (_jsx(ListEmptyStateBody, { content: emptyContent, narrowed: narrowed, defaultFilterActive: defaultFilterActive, ...(onFilterReset !== undefined && { onShowAll: onFilterReset }), translate: translate, createButton: onCreate !== undefined && !narrowed && !defaultFilterActive && !createInPageHeader ? (_jsx(Button, { variant: "primary", icon: "plus", onClick: onCreate, testId: "render-list-empty-create", children: effectiveCreateLabel })) : undefined })) : undefined);
     // Title-Resolution: ein konventioneller i18n-Key `screen:<id>.title`.
     // Wenn das Bundle den Key kennt, schöner Titel; sonst kommt der
     // screenId selber raus (kein "Untitled"-Fallback — der App-Dev sieht
@@ -254,9 +271,13 @@ function ReferenceLookupBridge({ field, refEntity, labelField, featureName, onMa
     // useEffect statt direktem call damit setState außerhalb des Render-
     // Pfads passiert (sonst React-Warning "Cannot update a component
     // while rendering a different component").
+    // Unpublished while loading or after a failed lookup: the renderer treats a missing map as
+    // "not resolved", an empty published map as "nothing found". Only the latter may say "Unknown".
+    const resolved = !lookup.loading && !lookup.failed;
     useEffect(() => {
-        onMap(field, lookup.map);
-    }, [field, lookup.map, onMap]);
+        if (resolved)
+            onMap(field, lookup.map);
+    }, [field, lookup.map, resolved, onMap]);
     return null;
 }
 // ToolbarActionView — pro Toolbar-Action ein Button (+ Confirm-Dialog

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

@@ -6,6 +6,7 @@ import { dispatcherErrorText } from "../app/write-failed-error.js";
 import { I18N_KEY_PARAM } from "../headless/index.js";
 import { useForm } from "../hooks/use-form.js";
 import { useTranslation } from "../i18n.js";
+import { useUnsavedInputSource } from "../leave-guard.js";
 import { STICKY_PRIMARY_ACTION_PROP, usePrimitives } from "../primitives.js";
 import { GridCellForField } from "./grid-cell-for-field.js";
 import { hasIssueWithoutVisibleField, issuesAfterEdit } from "./render-edit-logic.js";
@@ -44,6 +45,7 @@ export function WriteFormSection({ section, featureName, translate, hideTitle, o
         submit: { type: section.handler, payloadMode: "values" },
         schema,
     });
+    useUnsavedInputSource(() => controller.getSnapshot().isDirty);
     const [isSubmitting, setIsSubmitting] = useState(false);
     const [error, setError] = useState(null);
     async function handleSubmit() {
@@ -100,7 +102,8 @@ export function WriteFormSection({ section, featureName, translate, hideTitle, o
                         if (remaining !== errors)
                             controller.setErrors(remaining);
                         setError(null);
-                    }, GridCell: GridCell, featureName: featureName, allIssues: snapshot.errors, valueDisplay: "form", row: snapshot.values }, field.field))) }), error !== null && (_jsx(Banner, { variant: "error", testId: "write-form-section-error", children: error })), onFooterAction === undefined && (_jsx(Card, { options: { framed: false, footerBordered: false, footerInset: false }, slots: { footer: submitButton }, testId: "write-form-section-submit-row" }))] }));
+                    }, GridCell: GridCell, featureName: featureName, allIssues: snapshot.errors, valueDisplay: "form", row: snapshot.values, ...(hideTitle !== true &&
+                        section.title !== undefined && { sectionTitle: section.title }) }, field.field))) }), error !== null && (_jsx(Banner, { variant: "error", testId: "write-form-section-error", children: error })), onFooterAction === undefined && (_jsx(Card, { options: { framed: false, footerBordered: false, footerInset: false }, slots: { footer: submitButton }, testId: "write-form-section-submit-row" }))] }));
     // 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/field-issue-text.d.ts

@@ -0,0 +1,4 @@
+import type { FieldIssue } from "./headless/index.ts";
+type TranslateFn = (key: string, params?: Readonly<Record<string, unknown>>) => string;
+export declare function fieldIssueText(t: TranslateFn, issue: FieldIssue): string;
+export {};

package/dist/field-issue-text.js

@@ -0,0 +1,14 @@
+const INVALID_FORMAT_KEY = "errors.validation.invalid_format";
+// Zod reports every string-format failure under one code; the per-format key
+// (…invalid_format.email) carries a worked example, the generic key stays the
+// fallback for formats without one.
+export function fieldIssueText(t, issue) {
+    const format = issue.params?.["format"];
+    if (issue.i18nKey === INVALID_FORMAT_KEY && typeof format === "string") {
+        const formatKey = `${INVALID_FORMAT_KEY}.${format}`;
+        const text = t(formatKey, issue.params);
+        if (text !== formatKey)
+            return text;
+    }
+    return t(issue.i18nKey, issue.params);
+}

package/dist/headless/dispatcher/index.d.ts

@@ -1,2 +1,3 @@
+export { generateRequestId } from "./request-id.ts";
 export type { BatchResult, Command, Dispatcher, DispatcherError, DispatcherStatus, FieldIssue, PendingFile, PendingWrite, QueryOpts, QueryResult, StreamOpts, WriteOpts, WriteResult, } from "./types.ts";
 export { StreamFrame, type StreamFrameEvent } from "./types.ts";

package/dist/headless/dispatcher/index.js

@@ -1 +1,2 @@
+export { generateRequestId } from "./request-id.js";
 export { StreamFrame } from "./types.js";

package/dist/headless/dispatcher/request-id.d.ts

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

package/dist/headless/dispatcher/request-id.js

@@ -0,0 +1,15 @@
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+// crypto.randomUUID where available (browser, Bun, Node); Math.random
+// fallback for React-Native runtimes without the WebCrypto polyfill.
+// Uniqueness only needs to hold per user within the server's dedup window —
+// this is an idempotency key, not a security token.
+export function generateRequestId() {
+    const webCrypto = propertyOf(globalThis, "crypto");
+    const randomUUID = propertyOf(webCrypto, "randomUUID");
+    if (typeof randomUUID === "function") {
+        const id = Reflect.apply(randomUUID, webCrypto, []);
+        if (typeof id === "string")
+            return id;
+    }
+    return `req-${Math.random().toString(36).slice(2)}${Math.random().toString(36).slice(2)}`;
+}

package/dist/headless/form/form-controller.js

@@ -1,3 +1,4 @@
+import { generateRequestId } from "../dispatcher/index.js";
 import { createStore } from "../store/index.js";
 import { groupIssuesByPath, relevantFieldIssues, zodErrorToFieldIssues } from "./zod-bridge.js";
 // Paths without the prefix (hook-level errors, "(root)") pass through unchanged.
@@ -91,6 +92,11 @@ function omitPayloadFields(payload, omitFields) {
         return payload;
     return Object.fromEntries(Object.entries(payload).filter(([key]) => !omitFields.includes(key)));
 }
+function isTransportFailure(result) {
+    return (!result.isSuccess &&
+        result.error.httpStatus === 0 &&
+        (result.error.code === "network_error" || result.error.code === "aborted"));
+}
 export function createFormController(options) {
     // Shallow copy so mutating the input after creation doesn't bleed into
     // the controller's internal state. `initial` stays fixed across the
@@ -115,6 +121,10 @@ export function createFormController(options) {
     // coherent (rebasing twice in quick succession would mis-align the
     // baseline with what the server actually saw).
     let submitInFlight = null;
+    // Idempotency key of the last attempt that got no server answer. The server
+    // caches every answer (errors too) under the requestId, so the key may only
+    // be reused for an identical retry after a transport failure.
+    let unansweredAttempt = null;
     function buildSnapshot() {
         const changes = valuesDiff(values, initial);
         const isDirty = Object.keys(changes).length > 0;
@@ -365,7 +375,12 @@ export function createFormController(options) {
                 };
             }
             const runWrite = async () => {
-                const result = await dispatcher.write(submitCfg.type, payload);
+                const fingerprint = JSON.stringify([submitCfg.type, payload]);
+                const requestId = unansweredAttempt?.fingerprint === fingerprint
+                    ? unansweredAttempt.requestId
+                    : generateRequestId();
+                const result = await dispatcher.write(submitCfg.type, payload, { requestId });
+                unansweredAttempt = isTransportFailure(result) ? { requestId, fingerprint } : null;
                 if (result.isSuccess) {
                     // Remember intentional empty clears so post-rebase submits keep them (#1858).
                     if (payload && typeof payload === "object" && !Array.isArray(payload)) {

package/dist/headless/form/zod-bridge.js

@@ -84,6 +84,13 @@ function extractIssueParams(issue) {
         if (bag[key] !== undefined)
             out[key] = bag[key];
     }
+    // A custom issue that overrides its i18n key also carries the values the text interpolates.
+    if (issue.code === "custom" && typeof issue.params?.[I18N_KEY_PARAM] === "string") {
+        for (const [key, value] of Object.entries(issue.params)) {
+            if (key !== I18N_KEY_PARAM && value !== undefined)
+                out[key] = value;
+        }
+    }
     return Object.keys(out).length > 0 ? out : undefined;
 }
 // Groups a flat FieldIssue list into the `errors` map carried by a

package/dist/headless/index.d.ts

@@ -2,12 +2,13 @@ export type { ParsedRefTarget } from "@cosmicdrift/kumiko-framework/ui-types";
 export { parseRefTarget } from "@cosmicdrift/kumiko-framework/ui-types";
 export type { AssetResolution, AssetResolveContext, AssetResolver, BadgeProps, ButtonProps, CardProps, DatePickerProps, IconProps, LocaleResolver, ModalProps, NumberInputProps, PrimitiveCommonProps, PrimitivesContract, SelectOption, SelectProps, TextInputProps, ToastIntent, ToastProps, ToggleProps, } from "./contracts/index.ts";
 export type { BatchResult, Command, Dispatcher, DispatcherError, DispatcherStatus, FieldIssue, PendingFile, PendingWrite, QueryOpts, QueryResult, StreamOpts, WriteOpts, WriteResult, } from "./dispatcher/index.ts";
-export { StreamFrame, type StreamFrameEvent } from "./dispatcher/index.ts";
+export { generateRequestId, StreamFrame, type StreamFrameEvent } from "./dispatcher/index.ts";
 export type { FieldConditionPredicate, FieldConditions, FieldConditionValue, FieldState, FormController, FormControllerOptions, FormSnapshot, FormValues, SubmitConfig, SubmitPayloadMode, SubmitResult, } from "./form/index.ts";
 export { createFormController, groupIssuesByPath, I18N_KEY_PARAM, relevantFieldIssues, zodErrorToFieldIssues, } from "./form/index.ts";
 export { applyFormatSpec, currencyDecimals, DOCUMENT_FALLBACK_CURRENCY, EMPTY_VALUE_PLACEHOLDER, escapeHtml, escapeHtmlAttr, escapeXml, formatDocumentDate, formatDocumentMoney, formatDocumentPercent, formatMoney, type HtmlValue, html, isSafeHref, RawHtml, raw, resolveSafeMoneyLocale, stripControlChars, toInstant, } from "./format/index.ts";
 export type { NavDefinition, NavNode, NavRegistrySlice, NavTree, ResolveNavigationOptions, } from "./nav/index.ts";
 export { resolveNavigation } from "./nav/index.ts";
+export { pluralKey } from "./plural-key.ts";
 export type { Store, WritableStore } from "./store/index.ts";
 export { createStore, shallowEqual } from "./store/index.ts";
 export type { CellLink, CellLinkItem, ComputeEditViewModelInput, ComputeListViewModelInput, DerivedCellRoundingTarget, EditExtensionSectionViewModel, EditFieldSpec, EditFieldsSectionViewModel, EditFieldViewModel, EditFormMode, EditRelatedListSectionViewModel, EditSectionSpec, EditSectionViewModel, EditViewModel, EditWriteFormSectionViewModel, EmbeddedDerivedOp, EmbeddedListCellViewModel, EmbeddedListIssueGroups, FieldConditionCtx, FieldRenderer, ListColumnFileDisplay, ListColumnSpec, ListColumnViewModel, ListRowViewModel, ListViewModel, RuntimeCellLink, RuntimeCellLinkItems, RuntimeRenderer, ScreenSlots, Translate, } from "./view-model/index.ts";

package/dist/headless/index.js

@@ -1,9 +1,10 @@
 // Re-Export aus framework/ui-types damit Renderer-Code denselben
 // Parser nutzt wie der Server-Boot-Validator (Cross-Feature-Refs).
 export { parseRefTarget } from "@cosmicdrift/kumiko-framework/ui-types";
-export { StreamFrame } from "./dispatcher/index.js";
+export { generateRequestId, StreamFrame } from "./dispatcher/index.js";
 export { createFormController, groupIssuesByPath, I18N_KEY_PARAM, relevantFieldIssues, zodErrorToFieldIssues, } from "./form/index.js";
 export { applyFormatSpec, currencyDecimals, DOCUMENT_FALLBACK_CURRENCY, EMPTY_VALUE_PLACEHOLDER, escapeHtml, escapeHtmlAttr, escapeXml, formatDocumentDate, formatDocumentMoney, formatDocumentPercent, formatMoney, html, isSafeHref, RawHtml, raw, resolveSafeMoneyLocale, stripControlChars, toInstant, } from "./format/index.js";
 export { resolveNavigation } from "./nav/index.js";
+export { pluralKey } from "./plural-key.js";
 export { createStore, shallowEqual } from "./store/index.js";
 export { buildOptionLabels, computeDerivedCellValue, computeEditViewModel, computeListViewModel, computeRelatedListSectionViewModel, embeddedCellLabelKey, embeddedCellOptionLabelKey, fieldLabelKey, fieldOptionLabelKey, fieldOptionLabelKeyPrefix, groupEmbeddedListIssues, roundDerivedCellValue, sumEmbeddedListColumn, } from "./view-model/index.js";

package/dist/headless/plural-key.d.ts

@@ -0,0 +1 @@
+export declare function pluralKey(baseKey: string, count: number): string;

package/dist/headless/plural-key.js

@@ -0,0 +1,5 @@
+// Manual plural convention for locale bundles that hold plain strings: `<base>.one` for a
+// count of exactly 1, `<base>.other` for everything else (0 included).
+export function pluralKey(baseKey, count) {
+    return `${baseKey}.${count === 1 ? "one" : "other"}`;
+}

package/dist/headless/view-model/edit.d.ts

@@ -15,6 +15,10 @@ export type ComputeEditViewModelInput<TValues extends Readonly<Record<string, un
     /** actionForm `derive`: computed fields render read-only (and never block submit
      *  as required) unless their derivation currently leaves them to the user. */
     readonly derivation?: FormDerivationScreen;
+    /** Qualified name of the actionForm screen this form belongs to. File fields then upload
+     *  as pending for that screen (`uploadActionForm`) instead of for an entity. Set explicitly:
+     *  secretMint and confirm forms share the pseudo-entity but cannot take uploads. */
+    readonly actionFormScreenQn?: string;
 };
 export type EditFormMode = "create" | "update";
 export declare function computeRelatedListSectionViewModel(sectionSpec: EditRelatedListSection, translate: Translate): EditRelatedListSectionViewModel;