@cosmicdrift/kumiko-renderer 0.188.0 → 0.189.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.188.0",
+  "version": "0.189.0",
   "description": "Platform-agnostic React renderer for Kumiko screens. Contains the shared logic — primitives-contract, hooks, KumikoScreen, navigation & SSE abstractions — that any platform-specific renderer (web, native) composes. No DOM, no EventSource, no react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -15,8 +15,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.188.0",
-    "@cosmicdrift/kumiko-headless": "0.188.0",
+    "@cosmicdrift/kumiko-framework": "0.189.0",
+    "@cosmicdrift/kumiko-headless": "0.189.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"

package/src/app/__tests__/form-schema.test.ts

@@ -4,6 +4,7 @@ import type {
   EntityDefinition,
   EntityEditScreenDefinition,
 } from "@cosmicdrift/kumiko-framework/ui-types";
+import { createFormController } from "@cosmicdrift/kumiko-headless";
 import { buildFormSchema } from "../form-schema";
 
 function screenWith(fields: readonly EditFieldSpec[]): EntityEditScreenDefinition {
@@ -40,6 +41,41 @@ describe("buildFormSchema", () => {
     }
   });
 
+  // kumiko-framework#1927: a bare presence issue used to render as
+  // "Invalid value." — pin the params.i18nKey override so the resolved
+  // FieldIssue points at "kumiko.validation.required" ("Pflichtfeld.")
+  // instead of the generic errors.validation.custom fallback.
+  test("required field missing → issue carries the required-field i18nKey override", () => {
+    const entity = entityWith({ name: { type: "text", required: true } });
+    const screen = screenWith(["name"]);
+
+    const result = buildFormSchema(entity, screen).safeParse({ name: "" });
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    const issue = result.error.issues[0];
+    if (issue?.code !== "custom") throw new Error("expected a custom issue");
+    expect(issue.params).toMatchObject({ i18nKey: "kumiko.validation.required" });
+  });
+
+  // kumiko-framework#1927: the seam the bug actually lived in — a schema
+  // built here only round-trips through createFormController's validate(),
+  // which is what feeds FormSnapshot.errors that render-edit.tsx passes to
+  // RenderField. A unit test on buildFormSchema() alone can't catch a break
+  // in that hand-off (e.g. zodErrorToFieldIssues not honoring the override).
+  test("end-to-end via createFormController: required field left empty → snapshot error carries kumiko.validation.required", () => {
+    const entity = entityWith({ name: { type: "text", required: true } });
+    const screen = screenWith(["name"]);
+
+    const form = createFormController({
+      initial: { name: "" },
+      schema: buildFormSchema(entity, screen),
+    });
+
+    expect(form.validate()).toBe(false);
+    const fieldErrors = form.getSnapshot().errors["name"];
+    expect(fieldErrors?.[0]?.i18nKey).toBe("kumiko.validation.required");
+  });
+
   describe("required field present → no issue", () => {
     const entity = entityWith({ name: { type: "number", required: true } });
     const screen = screenWith(["name"]);
@@ -72,12 +108,24 @@ describe("buildFormSchema", () => {
     expect(result.success).toBe(true);
   });
 
-  test("required multiSelect → no issue (no editable widget on the auto-wired path)", () => {
+  test("required multiSelect, empty array → issue on that field (#1925: has a combobox widget now)", () => {
     const entity = entityWith({
       tags: { type: "multiSelect", required: true, options: ["a", "b"] },
     });
     const screen = screenWith(["tags"]);
-    expect(buildFormSchema(entity, screen).safeParse({ tags: undefined }).success).toBe(true);
+    const result = buildFormSchema(entity, screen).safeParse({ tags: [] });
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    expect(result.error.issues).toHaveLength(1);
+    expect(result.error.issues[0]?.path).toEqual(["tags"]);
+  });
+
+  test("required multiSelect, non-empty array → no issue", () => {
+    const entity = entityWith({
+      tags: { type: "multiSelect", required: true, options: ["a", "b"] },
+    });
+    const screen = screenWith(["tags"]);
+    expect(buildFormSchema(entity, screen).safeParse({ tags: ["a"] }).success).toBe(true);
   });
 
   test("jsonb field → no issue (no editable widget on the auto-wired path)", () => {
@@ -94,6 +142,20 @@ describe("buildFormSchema", () => {
     expect(buildFormSchema(entity, screen).safeParse({ lines: undefined }).success).toBe(true);
   });
 
+  test("required files field → no issue (#1925: no multi-upload widget yet, deliberately deferred)", () => {
+    const entity = entityWith({ attachments: { type: "files" } });
+    const screen = screenWith([{ field: "attachments", required: true }]);
+    expect(buildFormSchema(entity, screen).safeParse({ attachments: undefined }).success).toBe(
+      true,
+    );
+  });
+
+  test("required images field → no issue (#1925: no multi-upload widget yet, deliberately deferred)", () => {
+    const entity = entityWith({ gallery: { type: "images" } });
+    const screen = screenWith([{ field: "gallery", required: true }]);
+    expect(buildFormSchema(entity, screen).safeParse({ gallery: undefined }).success).toBe(true);
+  });
+
   test("required money — bare number (create-form representation) → no issue", () => {
     const entity = entityWith({ price: { type: "money", required: true } });
     const screen = screenWith(["price"]);

package/src/app/form-schema.ts

@@ -17,9 +17,15 @@ function isPresent(value: unknown): boolean {
 // Field types without a bound, editable widget on the auto-wired
 // entityEdit path (render-field.tsx renders a read-only banner instead) —
 // a presence error on one of them would be unresolvable by the user.
-// Tracked in #1925 (field types without an operable widget). `money` has an
-// operable widget (MoneyInput) and stays out of this set.
-const FIELD_TYPES_WITHOUT_WIDGET = new Set(["multiSelect", "jsonb", "embedded"]);
+// #1925 gave multiSelect/decimal/bigInt/tz/longText real widgets, so they
+// dropped out of this set; files/images stay out of scope (deferred, no
+// multi-upload widget yet) alongside jsonb/embedded (structural types with
+// no editor at all). A statically-`required: true` field of one of these
+// types is caught loudly at boot — validateNoWidgetRequiredField in
+// packages/framework/src/engine/boot-validator/screens.ts, which mirrors
+// this set (framework can't import renderer, so it can't import this
+// constant directly — keep both in sync).
+const FIELD_TYPES_WITHOUT_WIDGET = new Set(["jsonb", "embedded", "files", "images"]);
 
 // Client-side presence validation for the auto-wired entityEdit path —
 // checks that every rendered required field HAS a value, not that the
@@ -76,6 +82,8 @@ export function buildFormSchema(
           code: "custom",
           path: [spec.field],
           message: `"${spec.field}" is required.`,
+          // `params.i18nKey` override, see packages/headless/src/form/zod-bridge.ts.
+          params: { i18nKey: "kumiko.validation.required" },
         });
       }
     });

package/src/app/kumiko-screen.tsx

@@ -406,19 +406,19 @@ function EntityEditScreen({
       />
     );
   }
-  if (screen.allowCreate === false) {
-    // Update-only Screen ohne entityId (Direkt-URL / verirrte Navigation):
-    // ein Create-Form würde gegen den nicht registrierten
-    // `<entity>:create`-Handler submitten — Fehler statt Falle.
+  if (screen.singleton === true) {
     return (
-      <Banner padded variant="error" testId="kumiko-screen-create-disabled">
-        Screen <Text variant="code">{screen.id}</Text> is update-only (allowCreate: false) — open it
-        from a row action with an entity id.
-      </Banner>
+      <EntityEditSingletonBody
+        schema={schema}
+        screen={screen}
+        entity={entity}
+        {...(translate !== undefined && { translate })}
+        {...(onCopyLink !== undefined && { onCopyLink })}
+      />
     );
   }
   return (
-    <EntityEditCreateBody
+    <EntityEditCreateOrDisabled
       schema={schema}
       screen={screen}
       entity={entity}
@@ -454,9 +454,14 @@ function EntityEditCreateBody({
   const navigateToList = useNavigateToListAfter(schema, screen.entity);
   const handleSubmitted = useCallback(
     (result: SubmitResult<unknown>) => {
-      if (result.isSuccess) navigateToList();
+      if (!result.isSuccess) return;
+      if (screen.redirect !== undefined) {
+        nav.navigate({ screenId: lastSegment(screen.redirect) });
+        return;
+      }
+      navigateToList();
     },
-    [navigateToList],
+    [nav, screen.redirect, navigateToList],
   );
   return (
     <RenderEdit
@@ -602,13 +607,19 @@ function EntityEditUpdateForm({
     [entityId, recordVersion],
   );
 
+  const nav = useNav();
   const dispatcher = useDispatcher();
   const navigateToList = useNavigateToListAfter(schema, screen.entity);
   const handleSubmitted = useCallback(
     (result: SubmitResult<unknown>) => {
-      if (result.isSuccess) navigateToList();
+      if (!result.isSuccess) return;
+      if (screen.redirect !== undefined) {
+        nav.navigate({ screenId: lastSegment(screen.redirect) });
+        return;
+      }
+      navigateToList();
     },
-    [navigateToList],
+    [nav, screen.redirect, navigateToList],
   );
   const handleDelete = useCallback(async () => {
     const res = await dispatcher.write(deleteCommand, { id: entityId });
@@ -646,6 +657,100 @@ function EntityEditUpdateForm({
   );
 }
 
+// Singleton entities (`singleton: true`, exactly one record per tenant):
+// EntityEditScreen reaches here only without an entityId. Resolve the
+// existing record via list(limit:1) before deciding create vs update —
+// otherwise every visit without an id would create another record.
+function EntityEditSingletonBody({
+  schema,
+  screen,
+  entity,
+  translate,
+  onCopyLink,
+}: {
+  readonly schema: FeatureSchema;
+  readonly screen: EntityEditScreenDefinition;
+  readonly entity: EntityDefinition;
+  readonly translate?: Translate;
+  readonly onCopyLink?: () => Promise<void> | void;
+}): ReactNode {
+  const { Banner } = usePrimitives();
+  const t = useTranslation();
+  const effectiveTranslate = translate ?? t;
+  const listQn = entityQueryCommand(schema.featureName, screen.entity, "list");
+  const listQuery = useQuery<PagedRows>(listQn, { limit: 1 });
+
+  if (listQuery.loading && listQuery.data === null) {
+    return (
+      <Banner padded variant="loading" testId="kumiko-screen-loading">
+        Loading…
+      </Banner>
+    );
+  }
+  if (listQuery.error) {
+    return (
+      <Banner padded variant="error" testId="kumiko-screen-error">
+        {dispatcherErrorText(listQuery.error, effectiveTranslate)}
+      </Banner>
+    );
+  }
+  const existingId = listQuery.data?.rows[0]?.["id"] as string | undefined;
+  if (existingId !== undefined) {
+    return (
+      <EntityEditUpdateBody
+        schema={schema}
+        screen={screen}
+        entity={entity}
+        entityId={existingId}
+        {...(translate !== undefined && { translate })}
+        {...(onCopyLink !== undefined && { onCopyLink })}
+      />
+    );
+  }
+  return (
+    <EntityEditCreateOrDisabled
+      schema={schema}
+      screen={screen}
+      entity={entity}
+      {...(translate !== undefined && { translate })}
+    />
+  );
+}
+
+// Shared no-entityId tail for both the plain create path and the
+// singleton path's empty-table fallback: `allowCreate: false` blocks
+// both the same way, since a create submit there would hit an
+// unregistered `<entity>:create` handler.
+function EntityEditCreateOrDisabled({
+  schema,
+  screen,
+  entity,
+  translate,
+}: {
+  readonly schema: FeatureSchema;
+  readonly screen: EntityEditScreenDefinition;
+  readonly entity: EntityDefinition;
+  readonly translate?: Translate;
+}): ReactNode {
+  const { Banner, Text } = usePrimitives();
+  if (screen.allowCreate === false) {
+    return (
+      <Banner padded variant="error" testId="kumiko-screen-create-disabled">
+        Screen <Text variant="code">{screen.id}</Text> is update-only (allowCreate: false) — open it
+        from a row action with an entity id.
+      </Banner>
+    );
+  }
+  return (
+    <EntityEditCreateBody
+      schema={schema}
+      screen={screen}
+      entity={entity}
+      {...(translate !== undefined && { translate })}
+    />
+  );
+}
+
 // ---- entity-list ----
 
 function entityQueryCommand(featureName: string, entity: string, verb: "list"): string {
@@ -1466,7 +1571,7 @@ function ActionFormBody({
       // Author entscheidet bewusst ob "stay on form" (default) oder
       // "back to list" (typisch bei Create-style Aktionen).
       if (result.isSuccess && screen.redirect !== undefined) {
-        nav.navigate({ screenId: screen.redirect });
+        nav.navigate({ screenId: lastSegment(screen.redirect) });
       }
     },
     [nav, screen.redirect],
@@ -1478,7 +1583,7 @@ function ActionFormBody({
   const handleCancel = useMemo<(() => void) | undefined>(() => {
     const target = screen.cancelTarget ?? screen.redirect;
     if (target === undefined || target === false) return undefined;
-    return () => nav.navigate({ screenId: target });
+    return () => nav.navigate({ screenId: lastSegment(target) });
   }, [nav, screen.redirect, screen.cancelTarget]);
   return (
     <RenderEdit

package/src/components/__tests__/render-field-unsupported-types.test.tsx

@@ -1,8 +1,12 @@
 // Regression #1834: field types without a dedicated widget (embedded
-// without embeddedListCells, jsonb, multiSelect) must render read-only
+// without embeddedListCells, jsonb, files, images) must render read-only
 // instead of falling back to a text input. The old default-branch
 // fallback ran the value through stringValue() — an object/array turned
 // into "[object Object]"/"a,b", and saving that overwrote the real data.
+// #1925 gave multiSelect a real combobox widget (so it dropped out of this
+// list) and moved files/images in (no multi-upload widget yet, deliberately
+// deferred — they used to hit the same text-input corruption via the
+// default branch).
 //
 // Capture-Input/Banner instead of real primitives, same pattern as
 // render-field-app-locale.test.tsx.
@@ -86,7 +90,8 @@ function renderField(field: EditFieldViewModel): void {
 describe.each([
   ["embedded (kein embeddedListCells)", baseField({ type: "embedded", value: { note: "x" } })],
   ["jsonb", baseField({ type: "jsonb", value: { a: 1 } })],
-  ["multiSelect", baseField({ type: "multiSelect", value: ["a", "b"] })],
+  ["files", baseField({ type: "files", value: ["11111111-1111-1111-1111-111111111111"] })],
+  ["images", baseField({ type: "images", value: ["11111111-1111-1111-1111-111111111111"] })],
 ])("RenderField — %s ohne Widget", (_name, field) => {
   test("rendert einen schreibgeschützten Banner statt eines editierbaren Text-Inputs", () => {
     renderField(field);
@@ -108,3 +113,62 @@ describe("RenderField — text bleibt weiterhin editierbar", () => {
     expect(capturedInput?.kind).toBe("text");
   });
 });
+
+// #1925: field types that gained a real widget on the auto-wired
+// entityEdit path (previously either no widget at all or a type-mismatched
+// text-input fallback).
+describe("RenderField — #1925 neue Widgets", () => {
+  test("multiSelect rendert eine Multi-Combobox statt eines Banners", () => {
+    renderField(
+      baseField({
+        type: "multiSelect",
+        value: ["a"],
+        options: ["a", "b"],
+      }),
+    );
+    expect(capturedBanner).toBeUndefined();
+    expect(capturedInput).toBeDefined();
+    expect(capturedInput?.kind).toBe("combobox");
+    if (capturedInput?.kind !== "combobox") return;
+    expect(capturedInput.multiple).toBe(true);
+    expect(capturedInput.value).toEqual(["a"]);
+    expect(capturedInput.options).toEqual([
+      { value: "a", label: "a" },
+      { value: "b", label: "b" },
+    ]);
+  });
+
+  test("decimal rendert ein number-Input statt Text (kein String-Fallback mehr)", () => {
+    renderField(baseField({ type: "decimal", value: 12.5 }));
+    expect(capturedBanner).toBeUndefined();
+    expect(capturedInput).toBeDefined();
+    expect(capturedInput?.kind).toBe("number");
+    if (capturedInput?.kind !== "number") return;
+    expect(capturedInput.value).toBe(12.5);
+  });
+
+  test("bigInt rendert ein number-Input statt Text (kein String-Fallback mehr)", () => {
+    renderField(baseField({ type: "bigInt", value: 42 }));
+    expect(capturedBanner).toBeUndefined();
+    expect(capturedInput).toBeDefined();
+    expect(capturedInput?.kind).toBe("number");
+    if (capturedInput?.kind !== "number") return;
+    expect(capturedInput.value).toBe(42);
+  });
+
+  test("tz rendert ein dediziertes tz-Input statt Text", () => {
+    renderField(baseField({ type: "tz", value: "Europe/Berlin" }));
+    expect(capturedBanner).toBeUndefined();
+    expect(capturedInput).toBeDefined();
+    expect(capturedInput?.kind).toBe("tz");
+    if (capturedInput?.kind !== "tz") return;
+    expect(capturedInput.value).toBe("Europe/Berlin");
+  });
+
+  test("longText rendert immer ein textarea, auch ohne explizites multiline-Flag", () => {
+    renderField(baseField({ type: "longText", value: "lange Notiz" }));
+    expect(capturedBanner).toBeUndefined();
+    expect(capturedInput).toBeDefined();
+    expect(capturedInput?.kind).toBe("textarea");
+  });
+});

package/src/components/render-edit.tsx

@@ -48,6 +48,14 @@ const FORM_DRAFT_SAVE = "form-draft:write:save";
 const FORM_DRAFT_DISCARD = "form-draft:write:discard";
 const FORM_DRAFT_LIST = "form-draft:query:list";
 
+// Trailing-edge debounce for patch()-triggered draft saves (#1914). A single
+// patch() call (VIN-decode, an extension section) should not save immediately
+// per call, but patch() can also fire from inside onChange on every keystroke
+// (the #1888 derived-field shape) — 500ms collapses a typing burst into one
+// save instead of one per keystroke, while still saving well before a user
+// abandons the tab.
+const PATCH_DRAFT_SAVE_DEBOUNCE_MS = 500;
+
 type FormDraftBlob = {
   readonly values: Record<string, unknown>;
   readonly stepIndex: number;
@@ -345,6 +353,11 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   // 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.
+  //
+  // 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.
   const [extensionDirty, setExtensionDirty] = useState(false);
   const [extensionErrorKey, setExtensionErrorKey] = useState<string | null>(null);
   const { registry: extensionFormRegistry, runAll: runExtensionSubmits } =
@@ -439,17 +452,54 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     () => controller.validate(scopeFieldNamesRef.current),
     [controller],
   );
+
+  // `saveDraft` (defined below) is a fresh closure every render, over that
+  // render's `draftKey`/`draftId` — the ref lets the debounce timer below
+  // always call the CURRENT one even though the timer was scheduled by an
+  // earlier render's patch() call. `currentStepRef` gives it the current
+  // wizard step without depending on `currentStep` (computed further down,
+  // from `filteredSections`) at the point patchAndScheduleDraftSave itself
+  // is defined — kept fresh where `currentStep` is computed below.
+  const saveDraftRef = useRef(saveDraft);
+  saveDraftRef.current = saveDraft;
+  const currentStepRef = useRef(0);
+  const draftSaveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(() => {
+    return () => {
+      if (draftSaveTimerRef.current !== null) clearTimeout(draftSaveTimerRef.current);
+    };
+  }, []);
+
+  // patch() (controlled mode, extension sections) applies immediately —
+  // only the resulting draft save is debounced (#1914), 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.
+  const patchAndScheduleDraftSave = useCallback(
+    (partial: Partial<TValues>) => {
+      controller.setValues(partial);
+      if (!draftEnabled) return;
+      if (draftSaveTimerRef.current !== null) clearTimeout(draftSaveTimerRef.current);
+      draftSaveTimerRef.current = setTimeout(() => {
+        draftSaveTimerRef.current = null;
+        saveDraftRef.current(currentStepRef.current);
+      }, PATCH_DRAFT_SAVE_DEBOUNCE_MS);
+    },
+    [controller, draftEnabled],
+  );
+
   useEffect(() => {
     const cb = onControlsReadyRef.current;
     if (cb === undefined) return;
     cb({
-      patch: controller.setValues,
+      patch: patchAndScheduleDraftSave,
       validate: scopedValidate,
       getValues: () => controller.getSnapshot().values,
     });
-    // controller is mount-lifetime-stable (see useForm's comment on its
-    // own useMemo) — this fires exactly once per RenderEdit mount.
-  }, [controller, scopedValidate]);
+    // controller is mount-lifetime-stable (see useForm's comment on its own
+    // useMemo), same for patchAndScheduleDraftSave/scopedValidate (both
+    // useCallback over mount-stable deps) — this fires exactly once per
+    // RenderEdit mount in practice.
+  }, [controller, scopedValidate, patchAndScheduleDraftSave]);
 
   useEffect(() => {
     // skip: this screen does not persist a draft.
@@ -579,6 +629,10 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   // stored stepIndex can point past what is currently rendered — that lands on
   // the last step instead of an empty one.
   const currentStep = Math.min(rawStep, lastStepIndex);
+  // Kept fresh for patchAndScheduleDraftSave's debounce timer above, which
+  // is defined before `currentStep` exists (it depends on `filteredSections`,
+  // computed further up from `vm`) and so cannot close over it directly.
+  currentStepRef.current = currentStep;
   const isLastWizardStep = currentStep >= lastStepIndex;
 
   // Step transitions only — never per keystroke. Deliberately not awaited: a
@@ -638,6 +692,12 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   async function discardDraft(): Promise<void> {
     // skip: this screen does not persist a draft.
     if (!draftEnabled) return;
+    // A pending debounced patch-save must not fire after discard — it would
+    // resurrect the draft it just deleted.
+    if (draftSaveTimerRef.current !== null) {
+      clearTimeout(draftSaveTimerRef.current);
+      draftSaveTimerRef.current = null;
+    }
     // skip: create-mode, no step change happened yet — no draftId was ever
     // minted, so no row exists to discard.
     if (draftKey === undefined) return;
@@ -836,6 +896,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
         {...(formSubtitle !== undefined && { subtitle: formSubtitle })}
         actions={formActions}
         testId="render-edit-form"
+        stickyActions={isWizard}
         {...(screen.layout.width !== undefined && { width: screen.layout.width })}
       >
         {draftCandidates !== null && (
@@ -887,7 +948,9 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
                   // @cast-boundary form-values: ExtensionSectionProps is not generic
                   // over TValues; controller is mount-lifetime-stable, see onControlsReady above.
                   patch={
-                    controller.setValues as (partial: Readonly<Record<string, unknown>>) => void
+                    patchAndScheduleDraftSave as (
+                      partial: Readonly<Record<string, unknown>>,
+                    ) => void
                   }
                   validate={scopedValidate}
                 />

package/src/components/render-field.tsx

@@ -323,7 +323,13 @@ function renderInput({
   } as const;
 
   switch (field.type) {
+    // 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).
     case "number":
+    case "decimal":
+    case "bigInt":
       return (
         <Input
           kind="number"
@@ -333,6 +339,34 @@ function renderInput({
           {...(field.icon !== undefined && { icon: field.icon })}
         />
       );
+    case "tz":
+      return (
+        <Input
+          kind="tz"
+          {...common}
+          value={stringValue(field.value)}
+          onChange={(v) => onChange(v)}
+        />
+      );
+    case "multiSelect": {
+      const rawOptions = field.options ?? [];
+      const labels = field.optionLabels;
+      const multiSelectOptions =
+        labels !== undefined
+          ? rawOptions.map((value: string) => ({ value, label: labels[value] ?? value }))
+          : rawOptions.map((value: string) => ({ value, label: value }));
+      const arrayValue = Array.isArray(field.value) ? (field.value as readonly string[]) : [];
+      return (
+        <Input
+          kind="combobox"
+          {...common}
+          multiple
+          value={arrayValue}
+          onChange={(v) => onChange(v)}
+          options={multiSelectOptions}
+        />
+      );
+    }
     case "money": {
       const currency = field.currency ?? "EUR";
       return (
@@ -432,14 +466,19 @@ function renderInput({
       );
     }
     // embedded (without embeddedListCells — that's embeddedList, which has
-    // had its own EmbeddedListField widget since #1838), jsonb and
-    // multiSelect carry objects/arrays. Without a dedicated widget these
-    // must NOT fall through to a text input: stringValue() turns them into
-    // "[object Object]" / "a,b", and saving that overwrites the real data
-    // with the mangled string (#1834).
+    // had its own EmbeddedListField widget since #1838) and jsonb carry
+    // arbitrary objects; files/images carry a FileRef-UUID array and have
+    // no multi-upload widget yet (deliberately deferred, #1925). Without a
+    // dedicated widget these must NOT fall through to a text input:
+    // stringValue() turns them into "[object Object]" / a comma-joined
+    // string, and saving that overwrites the real data with the mangled
+    // string (#1834). A `required: true` on any of these is caught loudly
+    // at boot (validateNoWidgetRequiredField in the framework package)
+    // instead of silently failing here.
     case "embedded":
     case "jsonb":
-    case "multiSelect":
+    case "files":
+    case "images":
       return (
         <Banner id={id} variant="info">
           {t("kumiko.field.unsupported")}
@@ -447,8 +486,11 @@ function renderInput({
       );
     default: {
       // text + unknown scalar type → text input. If TextFieldDef.multiline
-      // is set (the view-model carries it), the renderer switches to textarea.
-      if (field.type === "text" && field.multiline) {
+      // 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).
+      if (field.type === "longText" || (field.type === "text" && field.multiline)) {
         const rows = typeof field.multiline === "object" ? field.multiline.rows : undefined;
         return (
           <Input

package/src/primitives.tsx

@@ -408,6 +408,17 @@ export type InputProps =
       readonly required?: boolean;
       readonly hasError?: boolean;
     }
+  | {
+      readonly kind: "tz";
+      readonly id: string;
+      readonly name: string;
+      /** IANA zone name, e.g. "Europe/Berlin". Empty-state = "". */
+      readonly value: string;
+      readonly onChange: (v: string | undefined) => void;
+      readonly disabled?: boolean;
+      readonly required?: boolean;
+      readonly hasError?: boolean;
+    }
   | {
       readonly kind: "textarea";
       readonly id: string;
@@ -656,18 +667,14 @@ export type EmbeddedListInputProps = {
 
 export type { FormWidth };
 
-/** Submit-Wrapper. Web: `<form onSubmit>`, Native: View das einen
- *  onSubmit-Callback via Button-Press triggert. `onSubmit` bekommt
- *  eine abstrakte Signatur (keine FormEvent) damit Native-Impls das
- *  sinnvoll füllen können.
+/** Submit wrapper. Web: `<form onSubmit>`, native: a View that triggers an
+ *  onSubmit callback via button press. `onSubmit` gets an abstract
+ *  signature (no FormEvent) so native impls can fill it meaningfully.
  *
- *  `title`: linker Slot der sticky-top Bar — typisch der Screen-Titel
- *  ("Neuer Eintrag", "Bestellung bearbeiten"). Wenn gesetzt, rendert
- *  die Bar mit `justify-between` (Title links, Actions rechts).
- *  `actions`: optionaler Slot für die primären Form-Aktionen (Save,
- *  Cancel). Web rendert die Bar sticky-top, damit der Save-Button
- *  bei langen Forms beim Scrollen erreichbar bleibt. Native-Impls
- *  dürfen denselben Slot z. B. als Bottom-Bar rendern. */
+ *  `title`: slot in the card header. `actions`: optional slot for the
+ *  primary form actions (Save, Cancel) — renders as a footer row at the
+ *  end of the card (normal document flow). Native impls may render the
+ *  same slot as a bottom bar instead. */
 export type FormProps = {
   readonly onSubmit: (e?: FormEvent) => void;
   readonly children: ReactNode;
@@ -681,6 +688,12 @@ export type FormProps = {
    *  (`packages/types/src/screen.ts`, EditLayout.width, #1676). Native
    *  impls may ignore this prop (no width constraint there). */
   readonly width?: FormWidth;
+  /** Pins `actions` to the viewport bottom on narrow screens (`<640px`)
+   *  instead of normal document flow, so it stays reachable when a virtual
+   *  keyboard shrinks the visible viewport (fw#1918). Desktop/tablet
+   *  unaffected. Native impls may ignore this prop (already bottom-bar by
+   *  convention there). */
+  readonly stickyActions?: boolean;
 };
 
 /** Titled Gruppe von Feldern. Web: `<fieldset>` + `<legend>`, Native: