@cosmicdrift/kumiko-renderer 0.386.0 → 0.387.0

package/dist/components/render-edit.js

@@ -32,11 +32,11 @@ export function RenderEdit(props) {
     const disabled = disabledProp || viewMode;
     const i18nScreenId = props.i18nScreenId ?? screen.id;
     const { customSubmit } = props;
-    // Translate-Fallback: wenn der Caller keine Translate-Fn übergibt,
-    // konsumieren wir den i18next-Context direkt. Sonst wären Field-
-    // Labels ohne Caller-Wiring raw-Keys (`feature:entity:foo:field:title`).
-    // useTranslation throwt ohne LocaleProvider — das ist ok, weil RenderEdit
-    // ohnehin nur in einem mounted Kumiko-App-Tree läuft.
+    // Translate fallback: when the caller does not provide a translate function,
+    // consume the i18next context directly. Otherwise field labels would remain raw
+    // keys (`feature:entity:foo:field:title`) without caller wiring.
+    // useTranslation throws without a LocaleProvider, which is acceptable because
+    // RenderEdit only runs inside a mounted Kumiko app tree.
     const t = useTranslation();
     const translate = translateProp ?? t;
     const dispatcher = useOptionalDispatcher();
@@ -44,7 +44,7 @@ export function RenderEdit(props) {
     // Tabs reuse the wizard's step machinery: one section visible at a time,
     // all of them mounted, `currentStep` as the active index. What they do NOT
     // share is navigation — a tab form submits from any tab, so every
-    // step-transition path below stays wizard-only (fw#3134).
+    // step-transition path below stays wizard-only.
     const isTabs = screen.layout.mode === "tabs";
     const draftEnabled = isWizard && screen.layout.draft === true && dispatcher !== undefined;
     const isCreateMode = entityIdProp === undefined || entityIdProp === null || entityIdProp === "";
@@ -63,8 +63,8 @@ export function RenderEdit(props) {
     // One state for all header actions (actions?), not per-button — only one
     // action can be in flight at a time, and this keeps the error surfaced in
     // the shared formError-adjacent banner region instead of inside the
-    // button row (fw#2166 review: a full-width Banner there breaks the
-    // flex justify-end action bar).
+    // button row: a full-width Banner there breaks the
+    // flex justify-end action bar.
     const [actionError, setActionError] = useState(null);
     const [rawStep, setRawStep] = useState(0);
     const [passedStepKeys, setPassedStepKeys] = useState(() => new Set());
@@ -82,15 +82,15 @@ export function RenderEdit(props) {
         draftStorage,
     });
     const { draftCandidates, setDraftCandidates } = draftState;
-    // Composed-Save: Extension-Sections melden hier ihren dirty-State (damit der
-    // Save-Button aktiv wird wenn NUR eine Section geändert wurde) + ihren
-    // Submit-Handler (läuft nach dem Entity-Write). extensionErrorKey hält den
-    // i18n-Key einer fehlgeschlagenen Section-Persistierung.
+    // Composed save: extension sections report their dirty state so the Save button
+    // activates when only a section changed, and provide a submit handler that runs
+    // after the entity write. extensionErrorKey stores the i18n key for a failed
+    // section persistence.
     //
-    // Not a second write path for saveDraft()'s data (#1914): deriveFormFields
-    // (above) skips extension sections entirely, so extension-owned field state
-    // never enters `fields`/`controller.getSnapshot().values` — there is no
-    // draft-blob-covered state left for persistExtensions() to compete over.
+    // This is not a second write path for saveDraft()'s data: deriveFormFields
+    // skips extension sections entirely, so extension-owned field state never enters
+    // `fields` or `controller.getSnapshot().values`; there is no draft-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);
@@ -109,7 +109,7 @@ export function RenderEdit(props) {
     // Both stepped layouts show one section at a time and keep the rest mounted
     // but inert. A tabs layout on a host without the Tabs primitive has no strip
     // to switch with, so it falls back to rendering every section stacked rather
-    // than stranding the user on section 0 (fw#3134). Same fallback when the
+    // than stranding the user on section 0. Same fallback when the
     // WizardStepGroup wrapper is missing.
     const isStepped = isWizard || (isTabs && Tabs !== undefined && WizardStepGroup !== undefined);
     const fields = useMemo(() => deriveFormFields(screen), [screen]);
@@ -121,7 +121,7 @@ export function RenderEdit(props) {
     // scoping would silently drop root-level .refine() issues.
     // A `fieldsFilter` that matches nothing in `fields` (typo, renamed field)
     // must fall back to unscoped too — an empty scope array would filter out
-    // ALL validation issues (kumiko-framework#1907), letting submit() through
+    // ALL validation issues, letting submit() through
     // unvalidated on a form that also renders no sections.
     const scopeFieldNames = useMemo(() => {
         if (fieldsFilter === undefined)
@@ -129,9 +129,9 @@ export function RenderEdit(props) {
         const matched = fieldsFilter.filter((f) => Object.hasOwn(fields, f));
         return matched.length === 0 ? undefined : matched;
     }, [fieldsFilter, fields]);
-    // Submit-Config nur wenn der Caller einen writeCommand mitgibt; bei
-    // customSubmit-Pfad kommt der Form-Controller ohne Submit-Wiring,
-    // weil wir controller.submit() eh nicht rufen.
+    // Configure submission only when the caller provides a writeCommand; with
+    // customSubmit, the form controller has no submit wiring because
+    // controller.submit() is not called.
     const writeVerb = isCreateMode ? "create" : "update";
     // A write-excluded field must never reach the payload: the handler schema is
     // z.never() for it, so even an unchanged read-only value would be rejected.
@@ -191,12 +191,12 @@ export function RenderEdit(props) {
         controller.setValues(initial);
         controller.rebase();
     }, [refreshToken, controller, initial]);
-    // Controlled mode (Issue #1887). Both callbacks live in refs so a
+    // Controlled mode. Both callbacks live in refs so a
     // re-rendering caller (identity-unstable `onChange`/`onControlsReady`
     // closures, e.g. inline arrows) doesn't retrigger these effects — only a
     // real snapshot mutation (typing, patch()) does. Without this, a caller
     // whose onChange calls patch() to fill other fields (the VIN-decode use
-    // case from #1888) would loop: patch → new snapshot → effect
+    // case) would loop: patch → new snapshot → effect
     // re-subscribes with a "new" onChange → refires.
     const onChangeRef = useRef(onChange);
     onChangeRef.current = onChange;
@@ -205,7 +205,7 @@ export function RenderEdit(props) {
     // effect below on every render since the callback itself is now a dep).
     // Tracks the actual prop, not a ref snapshot, so a caller that swaps in a
     // real handler after mount (e.g. `onControlsReady={ready ? cb : undefined}`)
-    // gets delivered to for THIS mount instead of never (fw#1899).
+    // gets delivered to for THIS mount instead of never.
     const deliveredControlsToRef = useRef(undefined);
     const onControlsReadyRef = useRef(onControlsReady);
     onControlsReadyRef.current = onControlsReady;
@@ -250,9 +250,9 @@ export function RenderEdit(props) {
         };
     }, []);
     // patch() (controlled mode, extension sections) applies immediately —
-    // only the resulting draft save is debounced (#1914), so a patch() burst
+    // only the resulting draft save is debounced, so a patch() burst
     // (VIN-decode filling several fields, or onChange fanning a keystroke out
-    // through patch(), see the #1888 test above) collapses into one save.
+    // through patch(), see the VIN-decode test above) collapses into one save.
     const patchAndScheduleDraftSave = useCallback((partial) => {
         controller.setValues(partial);
         if (!draftEnabled || dispatcher === undefined || disabled || submittedRef.current)
@@ -270,7 +270,7 @@ export function RenderEdit(props) {
     // execution order) so that an onChange fired on mount always sees
     // `controls !== undefined` — both effects depend only on mount-stable
     // values (controller/scopedValidate/patchAndScheduleDraftSave), so the
-    // swap is otherwise a no-op. See the #1888 VIN-decode test: an initial
+    // swap is otherwise a no-op. See the VIN-decode test: an initial
     // value that should derive dependent fields on mount needs controls.patch
     // available on the very first onChange call, not just from the second
     // keystroke onward.
@@ -377,7 +377,7 @@ export function RenderEdit(props) {
     // run their own query / own submit), so they always pass through. A
     // section with no fields at all (e.g. a review-only step) has
     // `visible: fields.some(...)` = false vacuously; that's "no fields to
-    // hide", not "hidden", so it stays too (fw#1901). Unless the create
+    // hide", not "hidden", so it stays too. Unless the create
     // exclusion emptied it: that would leave an empty wizard step / tab.
     () => filterEditSections(vm.sections, fieldsFilter).filter((section) => section.kind === "extension" ||
         section.kind === "relatedList" ||
@@ -391,9 +391,9 @@ export function RenderEdit(props) {
         return fillable.length > 0 && fillable.every((field) => field.required);
     }, [filteredSections]);
     const showsAllRequiredHint = allFieldsRequired && hideSectionTitles !== true && !isWizard;
-    // true when editable fields exist or an extension opted into composed submit (fw#2359).
+    // true when editable fields exist or an extension opted into composed submit.
     const isFormEditable = hasEditableSection(filteredSections);
-    // A fieldless form (input-less secretMint mint, fw#2838 — the secret is
+    // A fieldless form (input-less secretMint mint — the secret is
     // server-generated, the mint step is only its submit button) has no
     // section to gate on: it IS the action, so it always shows the submit
     // button, and it can never go dirty either.
@@ -404,8 +404,8 @@ export function RenderEdit(props) {
     // reaches this line and `filteredSections[0]` stays the active section)
     // needs its own tab panel capped at the available height so its table
     // scrolls inside the panel instead of the whole page stretching to the
-    // row count (fw#2722) — a short table still sizes to its content instead
-    // of stretching the panel to the bottom (fw#2778). Any other layout —
+    // row count — a short table still sizes to its content instead
+    // of stretching the panel to the bottom. Any other layout —
     // multiple sections, a non-relatedList tab, stacked (non-tabs) forms —
     // keeps normal document-flow height untouched.
     const fillHeight = fillScreenHeight === true ||
@@ -415,9 +415,9 @@ export function RenderEdit(props) {
     // 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.
+    // Persist all composed extension sections using the resolved entityId.
+    // false means a section failed and its i18n key is shown in the banner. Without
+    // entity context (create mode without a route id), there is nothing to write.
     async function persistExtensions() {
         const entityId = resolveExtensionEntityId(entityIdProp, vm.id);
         if (entityId === null)
@@ -495,7 +495,7 @@ export function RenderEdit(props) {
     function handleWizardNext() {
         const next = Math.min(currentStep + 1, lastStepIndex);
         hasNavigatedRef.current = true;
-        // Locked state (#1896): `disabled` means "no input/no write", not "no
+        // Locked state: `disabled` means "no input/no write", not "no
         // navigation" — a disabled wizard must still be steppable so Back/Next
         // reach every step. But neither validate() (would block on an empty
         // required field nobody can fill in) nor saveDraft() (would mint a
@@ -569,7 +569,7 @@ export function RenderEdit(props) {
             handleWizardNext();
             return;
         }
-        // Locked state (#1896): the submit button is visibly disabled, but a
+        // Locked state: the submit button is visibly disabled, but a
         // native form submit (Enter key) reaches this handler regardless of the
         // button's disabled attribute — block it here too, not just in the UI.
         if (disabled || submitBlocked)
@@ -582,9 +582,9 @@ export function RenderEdit(props) {
         setIsSubmitting(true);
         setExtensionErrorKey(null);
         try {
-            // Extension-only: only a section is dirty, the main form is unchanged.
-            // No entity write (would send an empty changes payload) — only
-            // die Section-Handler laufen lassen.
+            // Extension-only: only a section is dirty and the main form is unchanged.
+            // Skip the entity write (it would send an empty changes payload) and only
+            // run the section handlers.
             if (snapshot.isUnchanged && extensionDirty) {
                 // Same discard as the main path: an extension-only save is still a
                 // successful submit, so the draft must not survive it.
@@ -597,22 +597,19 @@ export function RenderEdit(props) {
             }
             let result;
             if (customSubmit !== undefined) {
-                // customSubmit path (e.g. configEdit, which fires a separate write
-                // per field). Client-side validation first, then
-                // an den Caller; on-success rebased der Form-State explizit
-                // because controller.submit() normally does this itself and
-                // without customSubmit's help the controller knows nothing about
-                // erfolgreichen Submit (isUnchanged blieb sonst false).
+                // customSubmit path (e.g. configEdit, which performs a separate write per
+                // field). Validate on the client first, then call the caller; on success,
+                // explicitly rebase the form state because controller.submit() normally
+                // does this itself, and the controller otherwise knows nothing about a
+                // successful custom submission (isUnchanged would remain false).
                 //
-                // WICHTIG: snapshot direkt vom Controller holen statt aus
-                // React state. On rapid fill→click, React batching may not have
-                // committed input state updates yet when the submit click fires.
-                // handleSubmit's closure would then run with
-                // stale snapshot.changes={} laufen, customSubmit fired keine
-                // Writes, returnt success, Form rebase → User glaubt "saved"
-                // aber gar nichts ist passiert. controller.getSnapshot() ist
-                // immer aktuell — der Controller ist die Source-of-Truth, die
-                // React state is only a mirror for rendering.
+                // Read the snapshot directly from the controller rather than React state.
+                // With rapid fill-then-click input, React batching may not have committed
+                // state updates when the submit click fires. handleSubmit's closure could otherwise
+                // see stale snapshot.changes={} and perform no writes, then return success
+                // and rebase the form, making it appear that the data was saved.
+                // controller.getSnapshot() is always current: the controller is the
+                // source of truth, while React state is only a rendering mirror.
                 const valid = controller.validate(scopeFieldNames);
                 if (!valid) {
                     // Field order matters: validationBlocked:true is its own
@@ -642,7 +639,7 @@ export function RenderEdit(props) {
                 // `isNoOp: true` (payloadMode "changes", pre-filled form submitted
                 // untouched) means controller.submit() never called dispatcher.write
                 // — nothing to discard, and discarding here would delete a draft the
-                // form never persisted (fw#1978). Awaited, not fire-and-forget:
+                // form never persisted. Awaited, not fire-and-forget:
                 // `onSubmit` typically navigates away and unmounts this form, which
                 // would abort an in-flight discard and leave the draft behind after
                 // a successful submit.
@@ -679,7 +676,7 @@ export function RenderEdit(props) {
                 // otherwise invisible — jump to the first step that contains one of
                 // the errored fields. For tabs this is what keeps the submit from
                 // blocking in silence, the failure mode the boot-validator used to
-                // prevent by rejecting the layout outright (fw#3134). An issue no
+                // prevent by rejecting the layout outright. An issue no
                 // rendered field can show (`version`, `id`, a root-level refine, a
                 // hidden field) keeps the banner, jump or not.
                 if (isStepped) {
@@ -850,14 +847,14 @@ export function RenderEdit(props) {
                         : hasDirtyFooter
                             ? "kumiko.form.saveChanges"
                             : "kumiko.actions.save")) })), writeFormFooterAction] }));
-    // Title + Subtitle, create/edit-bewusst. i18n-Keys (mode = "create"|"edit"):
+    // Title + Subtitle, create/edit-aware. i18n-Keys (mode = "create"|"edit"):
     //   screen:<id>.<mode>.title / .<mode>.subtitle  (mode = "create"|"edit"|"view")
-    // Fallback-Kette: mode-spezifisch → generisch (screen:<id>.title/.subtitle).
+    // Fallback chain: mode-specific → generic (screen:<id>.title/.subtitle).
     // title falls back to screenId; subtitle falls back to screen.description,
     // itself run through translate() so an i18n key (the established
     // convention for description, e.g. bundled-features) resolves instead of
     // showing the raw key — translate() returns the input unchanged for plain
-    // prose, same as it does for an unknown key (fw#2723 review). Same slot
+    // prose, same as it does for an unknown key. Same slot
     // section.description already fills for a section. Falls back to
     // undefined (no subtitle) when neither is set.
     const formMode = isCreate ? "create" : viewMode ? "view" : "edit";
@@ -984,7 +981,7 @@ export function RenderEdit(props) {
                             // survives navigating past its step — otherwise Finish only ran the
                             // last mounted step's handler and silently dropped earlier steps'
                             // writes. For tabs this is also what makes ONE submit cover every
-                            // tab, including tabs the user never opened (fw#3134).
+                            // tab, including tabs the user never opened.
                             const stepHidden = isStepped && sectionIndex !== currentStep;
                             const wrapWizardStep = (key, el) => {
                                 if (!isStepped)
@@ -1025,13 +1022,13 @@ export function RenderEdit(props) {
                             }
                             if (section.kind === "relatedList") {
                                 // parentId is the displayed record's id — without it there's no
-                                // parent row whose related rows could be queried (fw#2166).
+                                // parent row whose related rows could be queried.
                                 // Rejected at boot in wizard layouts, so no WizardStepGroup here.
                                 const parentId = resolveExtensionEntityId(entityIdProp, vm.id);
                                 if (parentId === null)
                                     return null;
                                 const mount = (_jsx(RelatedListSection, { section: section, parentId: parentId, 
-                                    // @cast-boundary form-values: TValues ist strukturell ein Record.
+                                    // @cast-boundary form-values: TValues is structurally a Record.
                                     record: snapshot.values, featureName: featureName, translate: translate, hideTitle: hideSectionTitles, ...(refreshToken !== undefined && { refreshToken }), ...(fillScreenHeight === true && { grow: true }), ...(hideSectionTitles !== true &&
                                         sectionActionsEl !== undefined && { actions: sectionActionsEl }), ...(onRelatedListDrawerAction !== undefined && {
                                         onOpenDrawer: onRelatedListDrawerAction,
@@ -1048,7 +1045,8 @@ export function RenderEdit(props) {
                             }
                             if (!section.visible)
                                 return null;
-                            // Titellose Sections kollidieren sonst auf key/testId — Index-Fallback.
+                            // Title-less sections would otherwise collide on key/testId, so use the index
+                            // as a fallback.
                             const sectionKey = section.title ?? `section-${sectionIndex}`;
                             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",
@@ -1085,7 +1083,7 @@ export function RenderEdit(props) {
                                     // undefined here at runtime.
                                     return wrapWizardStep(sectionKey, _jsx(Card, { options: { framed: false }, children: groupsGrid }, sectionKey));
                                 }
-                                // No section title here (fw#3218) — the Tab strip right above
+                                // No section title here — the Tab strip right above
                                 // already names this panel, so a repeated Card title would just
                                 // duplicate it. The header row only exists to carry the section
                                 // description and actions, never the title text.

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

@@ -5,14 +5,14 @@ export type RenderFieldProps = {
     readonly field: EditFieldViewModel;
     readonly issues?: readonly FieldIssue[];
     readonly onChange: (val: unknown) => void;
-    /** Nur bei type:"reference" relevant — Feature-Name für die Lookup-
-     *  Query-QN (`<feature>:query:<refEntity>:list`). Andere Field-Types
-     *  ignorieren das Prop. */
+    /** Relevant only for type:"reference": the feature name for the lookup
+     *  query QN (`<feature>:query:<refEntity>:list`). Other field types
+     *  ignore this prop. */
     readonly featureName?: string;
-    /** Optionaler Zusatz-Inhalt der nach dem Label gerendert wird (z.B.
+    /** Optional content rendered after the label (for example,
      *  ConfigSourceBadge). */
     readonly labelAppendix?: ReactNode;
-    /** Optionaler Zusatz-Inhalt der nach dem Input gerendert wird (z.B.
+    /** Optional content rendered after the input (for example,
      *  ConfigCascade). */
     readonly fieldAppendix?: ReactNode;
     readonly appendixPlacement?: FieldProps["appendixPlacement"];
@@ -26,12 +26,12 @@ export type RenderFieldProps = {
     /** "form" (default) renders every field as its editable Input, disabled
      *  when `field.readOnly` — unchanged behavior. "text" renders a
      *  `field.readOnly` field as plain text instead (projectionDetail's read
-     *  view, fw#2245); editable fields are untouched by this prop either way. */
+     *  view); editable fields are untouched by this prop either way. */
     readonly valueDisplay?: "form" | "text";
     /** Current form values, keyed by field name. Consulted when
      *  `field.renderer` resolves to a `{ react: { __component } }` registry
      *  component (passed through as `ColumnRendererProps.row`, same contract
-     *  as list-column renderers, fw#2245), and to resolve a `type: "number"`
+     *  as list-column renderers), and to resolve a `type: "number"`
      *  field's sibling-field `unit`. Omitted → falls back to a single-key
      *  `{ [field.field]: field.value }` row. */
     readonly row?: Readonly<Record<string, unknown>>;

package/dist/components/render-field.js

@@ -29,11 +29,10 @@ 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, 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
-    // App-Sprache. BEWUSSTE API-Verschärfung (seit 0.38): RenderField ist
-    // public exportiert und verlangt jetzt einen LocaleProvider —
-    // Standalone-Consumer/Tests müssen wrappen (createKumikoApp tut es).
+    // The app locale is required for money/date inputs; otherwise they fall back
+    // to navigator.language instead of the selected app language. RenderField is
+    // publicly exported and therefore requires a LocaleProvider; standalone
+    // consumers and tests must wrap it (createKumikoApp does this).
     const appLocale = useLocale().locale();
     const t = useTranslation();
     const allFieldsRequired = useContext(AllFieldsRequiredContext);
@@ -45,13 +44,13 @@ export function RenderField({ field, issues, onChange, featureName, labelAppendi
     // the list-column path (render-list.tsx). Only takes effect once the field
     // is actually readOnly — a FormatSpec/PlatformComponent renderer has no
     // editable widget of its own, so applying it to an editable field would
-    // silently make that field un-editable (fw#2245).
+    // silently make that field un-editable.
     const readOnlyText = valueDisplay === "text" && field.readOnly && field.renderer === undefined;
-    // 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.
+    // The reference field renders its own component because it uses useQuery()
+    // for the live lookup and must therefore be mounted as a React component,
+    // not called as a pure render function.
+    // The list input prints its own list-level issues (including the empty state),
+    // so the Field wrapper must not print them a second time.
     const listPrintsOwnIssues = field.type === "embedded" &&
         field.embeddedListCells !== undefined &&
         !(field.readOnly && field.renderer !== undefined);
@@ -168,38 +167,35 @@ function WriteOnlyTextInput({ field, id, hasError, onChange, changed, }) {
             },
         }) }));
 }
-// Tier 2.7e-3 + 2.1c: Reference-Input rendert eine Searchable Combobox
-// gefüllt aus einer Live-Query auf die referenced Entity. Default-
-// Limit: 200 — bei größeren Datasets fehlt der Tail im Dropdown
-// (Tier 2.7e-Remote: server-side Search-Query mit debounce kommt später).
-//   - Display = row[refLabelField], Default labelField "id".
-//   - Loading-State: leeres Dropdown bis die rows da sind. Field
-//     ist disabled während useQuery läuft.
-//   - Multi-Mode (Tier 2.7e-Multi via field.refMultiple): value ist
-//     ein UUID-Array, Combobox rendert Selected-Tags.
+// ReferenceInput renders a searchable combobox populated by a live query for
+// the referenced entity. With the default limit of 200, larger datasets miss
+// the tail in the dropdown; a server-side debounced search query comes later.
+//   - Display = row[refLabelField], default labelField "id".
+//   - During loading, the dropdown is empty and the field is disabled.
+//   - In multiple mode (field.refMultiple), value is a UUID array and the
+//     combobox renders tags.
 //
-// Storage: UI-Wert ist UUID (row.id) oder UUID-Array bei multiple.
-// Server-Schema: z.uuid() bzw. z.array(z.uuid()).
-// REFERENCE_COMBOBOX_LIMIT lebt zentral in hooks/reference-limits.ts
-// (siehe dort für Begründung der Default-Werte).
+// Storage: the UI value is a UUID (row.id), or a UUID array in multiple mode.
+// Server schema: z.uuid() or z.array(z.uuid()).
+// REFERENCE_COMBOBOX_LIMIT is centralized in hooks/reference-limits.ts
+// (see there for the rationale behind the default values).
 function ReferenceInput({ field, id, hasError, onChange, Input, featureName, }) {
     const { Banner } = usePrimitives();
     const refEntity = field.refEntity ?? "";
     const refFeature = field.refFeature ?? featureName;
     const isMultiple = field.refMultiple === true;
-    // Tier 2.7e Cross-Feature: refFeature kann ≠ featureName sein
-    // (z.B. items.assignee → users:query:user:list). Default ist
-    // same-feature, kommt aus dem ViewModel (parseRefTarget).
-    // fw#2780: refOptionsQuery replaces that source with an author-supplied
-    // handler whose rows already carry a composed `label`.
+    // refFeature may differ from featureName (for example,
+    // items.assignee → users:query:user:list). The default is the same feature,
+    // as provided by the ViewModel (parseRefTarget).
+    // refOptionsQuery replaces that source with an author-supplied handler whose
+    // rows already carry a composed `label`.
     const { queryQn, labelKey } = referenceOptionSource(field, refFeature, refEntity);
-    // Issue #1681: "+ Neu" in der Combobox öffnet den Create-Screen der
-    // referenced entity als Dialog, statt die aktuelle Form zu verlassen.
-    // refFeature kann ein anderes Feature als das aktuell gerenderte sein
-    // — appFeatures (createKumikoApp) kennt alle Feature-Schemas, nicht
-    // nur das der aktiven Screen. Kein Match (Feature/Screen/Entity nicht
-    // registriert, oder allowCreate:false) → onCreate bleibt undefined,
-    // Combobox rendert dann ohne den Footer.
+    // "+ Neu" in the combobox opens the referenced entity's create screen in a
+    // dialog instead of leaving the current form.
+    // refFeature may differ from the currently rendered feature; appFeatures
+    // (createKumikoApp) knows all feature schemas, not only the active screen.
+    // If the feature, screen, or entity is not registered, or allowCreate:false,
+    // onCreate remains undefined and the combobox renders without the footer.
     const appFeatures = useAppFeatures();
     const userRoles = useUserRoles();
     const t = useTranslation();
@@ -210,10 +206,10 @@ function ReferenceInput({ field, id, hasError, onChange, Input, featureName, })
         s.allowCreate !== false &&
         screenAccessAllows(s.access, userRoles));
     const refEntityDef = refTargetSchema?.entities[refEntity];
-    // Tier 2.7e Remote-Search: User tippt im Combobox → Server filtert
-    // via existing list-payload `search`-Param (Tier 2.6c). Combobox
-    // debounced den keystroke selbst (300ms) und ruft onSearchChange.
-    // Initial-State leer → erste 50 Items vom Server (default-sortiert).
+    // When the user types in the combobox, the server filters through the
+    // existing list-payload `search` parameter. The combobox debounces the
+    // keystroke itself (300ms) and calls onSearchChange.
+    // An empty initial state requests the first 50 items in default order.
     const [searchTerm, setSearchTerm] = useState("");
     const queryPayload = useMemo(() => searchTerm === ""
         ? { limit: REFERENCE_COMBOBOX_LIMIT }
@@ -254,13 +250,14 @@ function ReferenceInput({ field, id, hasError, onChange, Input, featureName, })
             return { value: idVal, label };
         });
     }, [queryResult.data, labelKey]);
-    // Single: value ist String/null; Multi: Array. Coerce auf das was
-    // der Combobox-Mode erwartet, damit Storage-Drift (Server liefert
-    // alten String wo jetzt Array erwartet wird) keine Crash auslöst.
+    // Single mode uses a String/null value; multiple mode uses an array. Coerce
+    // to the shape expected by the combobox so storage drift (for example, an
+    // old String from the server where an array is now expected) cannot crash it.
     const baseInputProps = {
         id,
         name: field.field,
-        // Initial-Load disabled — danach loading-Indicator im Popover.
+        // Disable the input during the initial load; subsequent loads show a
+        // loading indicator in the popover.
         disabled: field.readOnly || (queryResult.loading && options.length === 0),
         required: field.required,
         hasError,
@@ -295,7 +292,7 @@ function FieldRendererOutput({ field, renderer, row, appLocale, }) {
     if (isFormatSpec(renderer)) {
         // format:"json" wants the raw value (JsonView stringifies + highlights
         // itself) — applyFormatSpec's already-indented string is only the
-        // fallback for primitives-providers without JsonView (fw#2312).
+        // fallback for primitives-providers without JsonView.
         if (renderer.format === "json" && JsonView !== undefined) {
             return (_jsx(JsonView, { value: field.value, indent: renderer.indent, testId: `field-value-${field.field}` }));
         }
@@ -308,8 +305,8 @@ function FieldRendererOutput({ field, renderer, row, appLocale, }) {
         // App locale as default when the FormatSpec declares none of its own —
         // otherwise locale-sensitive formats (timestamp/date/number/decimal/
         // bigInt/unit) fell back to Intl's runtime default instead of the app
-        // language chosen via LocaleProvider (fw#2187). Prefer renderer.locale
-        // when set; coalesce undefined (spread override) back to appLocale (#2332).
+        // language chosen via LocaleProvider. Prefer renderer.locale
+        // when set; coalesce undefined (spread override) back to appLocale.
         return (_jsx(Text, { testId: `field-value-${field.field}`, children: applyFormatSpec({
                 ...renderer,
                 locale: stringPropertyOf(renderer, "locale") ?? appLocale,
@@ -417,7 +414,7 @@ function resolveFieldIcon(field) {
 // from the EditFieldViewModel (computeEditViewModel pulls them from
 // SelectFieldDef.options). Structural types without a widget (embedded,
 // jsonb, multiSelect) render read-only instead of a data-destroying text
-// fallback (#1834); truly unknown scalar types still fall back to text.
+// fallback; truly unknown scalar types still fall back to text.
 function renderInput({ field, id, hasError, onChange, Input, appLocale, Banner, Text, JsonView, t, row, fill, }) {
     const common = {
         id,
@@ -438,7 +435,7 @@ function renderInput({ field, id, hasError, onChange, Input, appLocale, Banner,
         // decimal/bigInt are both plain numbers on the wire (fieldToZod:
         // z.number() / z.number().int().safe()) — the number input's onChange
         // already emits `number | undefined`, so no extra coercion is needed
-        // beyond what "number" already does (#1925).
+        // beyond what "number" already does.
         case "number":
         case "bigInt": {
             const icon = resolveFieldIcon(field);
@@ -472,11 +469,11 @@ function renderInput({ field, id, hasError, onChange, Input, appLocale, Banner,
         case "locatedTimestamp":
             return (_jsx(Input, { kind: "locatedTimestamp", ...common, value: locatedValue(field.value), onChange: (v) => onChange(v), locale: field.dateLocale ?? appLocale, ...(field.min !== undefined && { min: field.min }), ...(field.max !== undefined && { max: field.max }) }));
         case "select": {
-            // Translated Option-Labels kommen aus dem ViewModel-Builder
-            // (computeEditViewModel, Convention-Key
+            // Translated option labels come from the ViewModel builder
+            // (computeEditViewModel, convention key
             // `<feature>:entity:<entity>:field:<field>:option:<value>`).
-            // Wenn keine Translations registriert sind, fallback auf raw
-            // value als Label — der ComboboxInput zeigt dann unverändert.
+            // If no translations are registered, fall back to the raw value as the
+            // label, which ComboboxInput then shows unchanged.
             const selectOptions = field.optionLabels !== undefined ? staticSelectOptions(field) : (field.options ?? []);
             // `display` is shared with multiSelect's "checkboxes", which is not a
             // select presentation — narrow to the two a select field can request.
@@ -495,11 +492,11 @@ function renderInput({ field, id, hasError, onChange, Input, appLocale, Banner,
         case "images":
             return (_jsx(FileListField, { field: field, id: id, kind: field.type === "images" ? "image" : "file", hasError: hasError, onChange: (ids) => onChange(ids) }));
         // embedded (without embeddedListCells — that's embeddedList, which has
-        // had its own EmbeddedListField widget since #1838) and jsonb carry
+        // had its own EmbeddedListField widget) and jsonb carry
         // arbitrary objects. Without a dedicated widget these must NOT fall
         // through to a text input: stringValue() turns them into
         // "[object Object]" and saving that overwrites the real data with the
-        // mangled string (#1834). A `required: true` on either is caught loudly
+        // mangled string. A `required: true` on either is caught loudly
         // at boot (validateNoWidgetRequiredField in the framework package)
         // instead of silently failing here.
         case "embedded":
@@ -519,7 +516,7 @@ function renderInput({ field, id, hasError, onChange, Input, appLocale, Banner,
             // is set (the view-model carries it), the renderer switches to
             // textarea. longText always renders a textarea — that's the point of
             // the type — regardless of whether `multiline` is set; `multiline`
-            // only supplies an optional `{ rows }` override for it (#1925).
+            // only supplies an optional `{ rows }` override for it.
             if (field.type === "longText" || (field.type === "text" && field.multiline)) {
                 const rows = typeof field.multiline === "object" ? field.multiline.rows : undefined;
                 return (_jsx(Input, { kind: "textarea", ...common, value: stringValue(field.value), onChange: (v) => onChange(v), ...(rows !== undefined && { rows }), ...placeholderProp }));
@@ -628,8 +625,9 @@ function moneyPayload(minorUnits, currency) {
         return undefined;
     return { amount: minorUnits / 10 ** currencyDecimals(currency), currency };
 }
-// locatedTimestamp-Feldwert: das Read-Wrapper liefert `{ at, tz, utc }`; leer
-// (noch nicht gesetzt) → "" als Empty-Sentinel, analog money/timestamp.
+// A locatedTimestamp field value is supplied by the read wrapper as
+// `{ at, tz, utc }`; an unset value becomes "" as the empty sentinel,
+// consistent with money and timestamp fields.
 function locatedValue(v) {
     if (v !== null && typeof v === "object" && "at" in v && "tz" in v) {
         const utc = propertyOf(v, "utc");
@@ -644,7 +642,7 @@ function locatedValue(v) {
 // Read-only text for a `field.readOnly` field without its own `renderer` —
 // per-type formatting that reuses the same value-shaping helpers as the
 // editable widgets above, so a text value and its would-be Input widget stay
-// derived from the identical parse (fw#2245). `type: "reference"` isn't
+// derived from the identical parse. `type: "reference"` isn't
 // 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.