@cosmicdrift/kumiko-renderer 0.220.1 → 0.221.0

package/src/components/render-edit.tsx

@@ -64,7 +64,7 @@ const FORM_DRAFT_KEY_MAX_LENGTH = 256;
 // (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;
+export const PATCH_DRAFT_SAVE_DEBOUNCE_MS = 500;
 
 type FormDraftBlob = {
   readonly values: Record<string, unknown>;
@@ -190,10 +190,6 @@ function ExtensionSectionMount({
   );
 }
 
-// One header action + its own busy/confirm state — same pattern as
-// render-list.tsx's ToolbarActionView (each RenderEditAction is
-// independently bound by the caller, there is no shared trigger pipeline
-// to hook into like the built-in onDelete/onSubmit paths have).
 export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   props: RenderEditProps<TValues, TCtx>,
 ): ReactNode {
@@ -301,9 +297,11 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   const fields = useMemo(() => deriveFormFields<TValues, TCtx>(screen), [screen]);
 
   // Must be computed before submitConfig/useForm bakes it in (the controller
-  // freezes it on first render) — safe because a section's field-name set is
-  // value-independent, so it matches filterEditSections(vm.sections, fieldsFilter).
-  // undefined = unscoped, since scoping would silently drop root-level .refine() issues.
+  // freezes it on first render). This is the unfiltered field-name set from
+  // `fieldsFilter` ∩ `fields` — not the value-dependent `filteredSections`
+  // (which also drops `section.visible === false`). Hidden fields still fall
+  // out via form-controller's `hiddenFields` path. undefined = unscoped, since
+  // 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
@@ -361,11 +359,6 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   // re-subscribes with a "new" onChange → refires.
   const onChangeRef = useRef(onChange);
   onChangeRef.current = onChange;
-  // `schema` is typically an inline caller prop (`schema={z.object({...})}`)
-  // with unstable identity across renders — as an effect dep it would refire
-  // on every parent render, not just on a snapshot change, risking a loop if
-  // the caller's onChange triggers a parent re-render. Held in a ref like
-  // onChangeRef so only a real snapshot mutation retriggers this effect.
   // Guards against redelivering to the SAME callback identity on every
   // render (an inline-arrow onControlsReady would otherwise refire the
   // effect below on every render since the callback itself is now a dep).
@@ -373,6 +366,11 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   // real handler after mount (e.g. `onControlsReady={ready ? cb : undefined}`)
   // gets delivered to for THIS mount instead of never (fw#1899).
   const deliveredControlsToRef = useRef<typeof onControlsReady>(undefined);
+  const onControlsReadyRef = useRef(onControlsReady);
+  onControlsReadyRef.current = onControlsReady;
+  const hasNavigatedRef = useRef(false);
+  const submittedRef = useRef(false);
+  const isSubmittingRef = useRef(false);
   const scopeFieldNamesRef = useRef(scopeFieldNames);
   scopeFieldNamesRef.current = scopeFieldNames;
   const scopedValidate = useCallback(
@@ -416,14 +414,15 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   const patchAndScheduleDraftSave = useCallback(
     (partial: Partial<TValues>) => {
       controller.setValues(partial);
-      if (!draftEnabled || dispatcher === undefined) return;
+      if (!draftEnabled || dispatcher === undefined || disabled || submittedRef.current) return;
       if (draftSaveTimerRef.current !== null) clearTimeout(draftSaveTimerRef.current);
       draftSaveTimerRef.current = setTimeout(() => {
         draftSaveTimerRef.current = null;
+        if (disabled || submittedRef.current) return;
         saveDraftRef.current(currentStepRef.current);
       }, PATCH_DRAFT_SAVE_DEBOUNCE_MS);
     },
-    [controller, draftEnabled, dispatcher],
+    [controller, draftEnabled, dispatcher, disabled],
   );
 
   // Runs before the onChange effect below (declaration order = React
@@ -434,23 +433,27 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   // 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.
+  const hasControlsReady = onControlsReady !== undefined;
   useEffect(() => {
-    if (onControlsReady === undefined) return;
-    if (deliveredControlsToRef.current === onControlsReady) return;
-    deliveredControlsToRef.current = onControlsReady;
-    onControlsReady({
+    if (!hasControlsReady) return;
+    const ready = onControlsReadyRef.current;
+    if (ready === undefined) return;
+    if (deliveredControlsToRef.current === ready) return;
+    deliveredControlsToRef.current = ready;
+    ready({
       patch: patchAndScheduleDraftSave,
       validate: scopedValidate,
       getValues: () => controller.getSnapshot().values,
       submit: () => handleSubmitRef.current(),
     });
-    // controller is mount-lifetime-stable (see useForm's comment on its own
-    // useMemo), same for patchAndScheduleDraftSave/scopedValidate (both
-    // useCallback over mount-stable deps) — onControlsReady is the only dep
-    // that can legitimately change post-mount, and the guard above stops an
-    // unstable inline-arrow identity from redelivering on every render.
-  }, [onControlsReady, controller, scopedValidate, patchAndScheduleDraftSave]);
+    // Dep on boolean presence only — inline-arrow identity must not redeliver.
+  }, [hasControlsReady, controller, scopedValidate, patchAndScheduleDraftSave]);
 
+  // `schema` is typically an inline caller prop (`schema={z.object({...})}`)
+  // with unstable identity across renders — as an effect dep it would refire
+  // on every parent render, not just on a snapshot change, risking a loop if
+  // the caller's onChange triggers a parent re-render. Held in a ref like
+  // onChangeRef so only a real snapshot mutation retriggers this effect.
   const schemaRef = useRef(schema);
   schemaRef.current = schema;
   // Controls are guaranteed ready by the time this fires (see the
@@ -489,23 +492,28 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     if (draftId !== null && draftId === mintedDraftIdRef.current) return;
     let cancelled = false;
     void (async () => {
-      const result = await dispatcher.query<{ readonly draft: FormDraftBlob | null }>(
-        FORM_DRAFT_GET,
-        { draftKey },
-      );
-      // skip: superseded by a newer mount, or the draft lookup failed — an
-      // unreachable draft store must not break the form itself.
-      if (cancelled || !result.isSuccess) return;
-      const draft = result.data?.draft ?? null;
-      // skip: nothing saved yet for this key.
-      if (draft === null) return;
-      // skip: the user already typed while the lookup was in flight — their
-      // input wins over the stored draft.
-      if (controller.getSnapshot().isDirty) return;
-      // @cast-boundary form-draft blob: `values` round-trips through an opaque
-      // jsonb column and comes back untyped.
-      controller.setValues(draft.values as Partial<TValues>);
-      setRawStep(Math.max(draft.stepIndex, 0));
+      try {
+        const result = await dispatcher.query<{ readonly draft: FormDraftBlob | null }>(
+          FORM_DRAFT_GET,
+          { draftKey },
+        );
+        // skip: superseded by a newer mount, or the draft lookup failed — an
+        // unreachable draft store must not break the form itself.
+        if (cancelled || !result.isSuccess) return;
+        const draft = result.data?.draft ?? null;
+        // skip: nothing saved yet for this key.
+        if (draft === null) return;
+        // skip: the user already typed or wizard-navigated while the lookup
+        // was in flight — their input wins over the stored draft.
+        if (controller.getSnapshot().isDirty || hasNavigatedRef.current) return;
+        // @cast-boundary form-draft blob: `values` round-trips through an opaque
+        // jsonb column and comes back untyped.
+        controller.setValues(draft.values as Partial<TValues>);
+        setRawStep(Math.max(draft.stepIndex, 0));
+      } catch (err: unknown) {
+        // biome-ignore lint/suspicious/noConsole: draft restore must not red-screen the form
+        console.warn("render-edit: draft restore query failed", err);
+      }
     })();
     return () => {
       cancelled = true;
@@ -533,24 +541,29 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
       dispatcher === undefined
     )
       return;
-    didListRef.current = true;
     let cancelled = false;
     void (async () => {
-      const result = await dispatcher.query<{ readonly drafts: readonly DraftCandidate[] }>(
-        FORM_DRAFT_LIST,
-        { screenId: screen.id },
-      );
-      // skip: superseded by a newer mount, or the lookup failed — an
-      // unreachable draft store must not break a fresh create.
-      if (cancelled || !result.isSuccess) return;
-      const prefix = newDraftPrefix(screen.id);
-      // list's LIKE-prefix scan also matches edit-mode drafts
-      // (`${screenId}:${entityId}`) — keep only create-mode ones.
-      const candidates = (result.data?.drafts ?? []).filter((d) => d.draftKey.startsWith(prefix));
-      // skip: no open drafts for this screen — stay null, saveDraft mints a
-      // fresh draftId on the first step change same as any other create.
-      if (candidates.length === 0) return;
-      setDraftCandidates(candidates);
+      try {
+        const result = await dispatcher.query<{ readonly drafts: readonly DraftCandidate[] }>(
+          FORM_DRAFT_LIST,
+          { screenId: screen.id },
+        );
+        // skip: superseded by a newer mount, or the lookup failed — an
+        // unreachable draft store must not break a fresh create.
+        if (cancelled || !result.isSuccess) return;
+        didListRef.current = true;
+        const prefix = newDraftPrefix(screen.id);
+        // list's LIKE-prefix scan also matches edit-mode drafts
+        // (`${screenId}:${entityId}`) — keep only create-mode ones.
+        const candidates = (result.data?.drafts ?? []).filter((d) => d.draftKey.startsWith(prefix));
+        // skip: no open drafts for this screen — stay null, saveDraft mints a
+        // fresh draftId on the first step change same as any other create.
+        if (candidates.length === 0) return;
+        setDraftCandidates(candidates);
+      } catch (err: unknown) {
+        // biome-ignore lint/suspicious/noConsole: draft lookup must not red-screen the form
+        console.warn("render-edit: draft list query failed", err);
+      }
     })();
     return () => {
       cancelled = true;
@@ -671,11 +684,16 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
       );
       return;
     }
-    void dispatcher.write(FORM_DRAFT_SAVE, {
-      draftKey: key,
-      values: controller.getSnapshot().values,
-      stepIndex,
-    });
+    void dispatcher
+      .write(FORM_DRAFT_SAVE, {
+        draftKey: key,
+        values: controller.getSnapshot().values,
+        stepIndex,
+      })
+      .catch((err: unknown) => {
+        // biome-ignore lint/suspicious/noConsole: fire-and-forget draft save must not red-screen
+        console.warn("render-edit: draft save failed", err);
+      });
   }
 
   // Next: scoped validate() on the current step's fields — errors stay
@@ -684,6 +702,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   // controls.validate() API), so no call, no clearing of unrelated errors.
   function handleWizardNext(): void {
     const next = Math.min(currentStep + 1, lastStepIndex);
+    hasNavigatedRef.current = true;
     // Locked state (#1896): `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
@@ -703,6 +722,11 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
 
   function handleWizardBack(): void {
     const previous = Math.max(currentStep - 1, 0);
+    hasNavigatedRef.current = true;
+    if (disabled) {
+      setRawStep(previous);
+      return;
+    }
     setRawStep(previous);
     saveDraft(previous);
   }
@@ -770,6 +794,10 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     // 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) return;
+    // Sync guard — React state `isSubmitting` is too late for double-clicks
+    // in the same tick (customSubmit has no submitInFlight of its own).
+    if (isSubmittingRef.current) return;
+    isSubmittingRef.current = true;
     setIsSubmitting(true);
     setExtensionErrorKey(null);
     try {
@@ -779,7 +807,10 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
       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.
-        if (await persistExtensions()) await discardDraft();
+        if (await persistExtensions()) {
+          submittedRef.current = true;
+          await discardDraft();
+        }
         return;
       }
       let result: SubmitResult<unknown>;
@@ -829,7 +860,10 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
         // `onSubmit` typically navigates away and unmounts this form, which
         // would abort an in-flight discard and leave the draft behind after
         // a successful submit.
-        if (result.isNoOp !== true) await discardDraft();
+        if (result.isNoOp !== true) {
+          submittedRef.current = true;
+          await discardDraft();
+        }
         extensionsPersisted = await persistExtensions();
       } else if (result.validationBlocked) {
         // Root-level `.refine()`/cross-field issues from controller.validate()
@@ -867,6 +901,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
       // and would unmount it before the user sees the failure).
       if (shouldNotifyCaller(result, extensionsPersisted)) onSubmit?.(result);
     } finally {
+      isSubmittingRef.current = false;
       setIsSubmitting(false);
     }
   }

package/src/hooks/__tests__/use-form.test.tsx

@@ -33,14 +33,18 @@ describe("useForm — mounted without a DispatcherProvider", () => {
     expect(result.current.snapshot.values.title).toBe("");
   });
 
-  test("submit() without an explicit dispatcher rejects instead of crashing the hook", async () => {
+  test("submit() without an explicit dispatcher returns isSuccess:false instead of crashing the hook", async () => {
     const { result } = renderHook(() =>
       useForm({ initial: { title: "hello" }, submit: { type: "app:write:task:create" } }),
     );
 
-    await expect(result.current.controller.submit()).rejects.toThrow(
-      /submit\(\) called without a dispatcher/,
-    );
+    const submitResult = await result.current.controller.submit();
+    expect(submitResult.validationBlocked).toBe(false);
+    expect(submitResult.isSuccess).toBe(false);
+    if (submitResult.isSuccess || submitResult.validationBlocked) {
+      throw new Error("expected write failure");
+    }
+    expect(submitResult.error.message).toMatch(/submit\(\) called without a dispatcher/);
   });
 
   test("submit() with an explicit dispatcher still works without a provider", async () => {

package/src/i18n.tsx

@@ -193,6 +193,48 @@ function interpolate(template: string, params?: Readonly<Record<string, unknown>
   });
 }
 
+/** Non-throwing LocaleContext read — undefined outside LocaleProvider.
+ *  Used by DataTable FormatCell so plain tables without a provider do not crash. */
+export function useOptionalLocale(): string | undefined {
+  const ctx = useContext(LocaleContext);
+  useSyncExternalStore(
+    (onStoreChange) => (ctx ? ctx.resolver.subscribe(onStoreChange) : () => {}),
+    () => (ctx ? ctx.resolver.locale() : "en"),
+    () => "en",
+  );
+  return ctx === undefined ? undefined : ctx.resolver.locale();
+}
+
+/** Non-throwing translate — undefined outside LocaleProvider. */
+export function useOptionalTranslation():
+  | ((key: string, params?: Readonly<Record<string, unknown>>) => string)
+  | undefined {
+  const ctx = useContext(LocaleContext);
+  const locale = useSyncExternalStore(
+    (onStoreChange) => (ctx ? ctx.resolver.subscribe(onStoreChange) : () => {}),
+    () => (ctx ? ctx.resolver.locale() : "en"),
+    () => "en",
+  );
+  const t = useCallback(
+    (key: string, params?: Readonly<Record<string, unknown>>): string => {
+      if (ctx === undefined) return key;
+      const resolved = ctx.resolver.translate(key, params);
+      if (resolved !== key) return resolved;
+      const languageRoot = locale.split("-")[0] ?? locale;
+      const localesToTry = [locale, languageRoot, ctx.fallbackLocale];
+      for (const bundle of ctx.fallbackBundles) {
+        for (const localeToTry of localesToTry) {
+          const value = bundle[localeToTry]?.[key];
+          if (value !== undefined) return interpolate(value, params);
+        }
+      }
+      return key;
+    },
+    [ctx, locale],
+  );
+  return ctx === undefined ? undefined : t;
+}
+
 /** Default-Resolver für Apps ohne eigene i18n-Schicht. Gibt jeden Key
  *  unverändert zurück — die Plugin-Fallback-Bundles erledigen dann die
  *  echte Übersetzung. Nützlich auch als Basis für Tests. */

package/src/index.ts

@@ -158,6 +158,8 @@ export {
   mergeTranslations,
   translationsByLocaleFromKeys,
   useLocale,
+  useOptionalLocale,
+  useOptionalTranslation,
   useTranslation,
 } from "./i18n";
 export { kumikoDefaultTranslations } from "./i18n-defaults";

package/src/primitives.tsx

@@ -35,7 +35,7 @@ import type {
   ConfigScope,
   ConfigValueSource,
 } from "@cosmicdrift/kumiko-framework/engine";
-import type { FormWidth } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { FieldIconKey, FormWidth } from "@cosmicdrift/kumiko-framework/ui-types";
 import type {
   FieldIssue,
   ListColumnViewModel,
@@ -179,9 +179,8 @@ export type InputProps =
       /** Read-only Input (z.B. gewürfelter Free-Tier-Slug). Nicht `disabled`
        *  — bleibt fokussier-/kopierbar. */
       readonly readOnly?: boolean;
-      /** Symbolic icon key (FIELD_ICONS registry, renderer-web) — renders
-       *  as a prefix on the input. Unknown key → no icon (no boot-fail). */
-      readonly icon?: string;
+      /** Closed FieldIconKey vocabulary (FIELD_ICONS registry, renderer-web). */
+      readonly icon?: FieldIconKey;
     }
   | {
       readonly kind: "email";
@@ -223,9 +222,8 @@ export type InputProps =
       readonly required?: boolean;
       readonly hasError?: boolean;
       readonly testId?: string;
-      /** Symbolic icon key (FIELD_ICONS registry, renderer-web) — renders
-       *  as a prefix on the input. Unknown key → no icon (no boot-fail). */
-      readonly icon?: string;
+      /** Closed FieldIconKey vocabulary (FIELD_ICONS registry, renderer-web). */
+      readonly icon?: FieldIconKey;
       /** `<input step>`. "any" disables the native stepMismatch constraint
        *  (needed for decimal fields — integer fields leave this unset). */
       readonly step?: number | "any";