@cosmicdrift/kumiko-renderer 0.195.0 → 0.196.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.195.0",
+  "version": "0.196.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.195.0",
-    "@cosmicdrift/kumiko-headless": "0.195.0",
+    "@cosmicdrift/kumiko-framework": "0.196.0",
+    "@cosmicdrift/kumiko-headless": "0.196.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"

package/src/app/__tests__/entity-list-row-action-refetch.test.tsx

@@ -0,0 +1,215 @@
+// Bug found while archiving a cost-type in solon (kumiko-framework#113-adjacent):
+// a `writeHandler` row-action on an entityList screen writes successfully
+// (HTTP 200, projection updated) but the list keeps showing the old state,
+// because nothing ever refetches the rows query after the write resolves.
+// Actions with a `redirect`/navigate target hide this — the screen remount
+// reloads everything. This test renders the real list path (KumikoScreen →
+// EntityListScreen → EntityListBody → RenderList) under a stub dispatcher
+// that counts `query()` calls, and proves the rows query refetches after a
+// successful row-action write, but NOT after a failed one (no double-fetch,
+// no silent refetch loop).
+
+import { describe, expect, test } from "bun:test";
+import type {
+  EntityDefinition,
+  EntityListScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
+import { act, render, waitFor } from "@testing-library/react";
+import type { ComponentType, ReactNode } from "react";
+import { DispatcherProvider } from "../../context/dispatcher-context";
+import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
+import { kumikoDefaultTranslations } from "../../i18n-defaults";
+import {
+  type CorePrimitives,
+  type DataTableProps,
+  type DataTableRowAction,
+  PrimitivesProvider,
+} from "../../primitives";
+import type { FeatureSchema } from "../feature-schema";
+import { KumikoScreen } from "../kumiko-screen";
+import { NavProvider } from "../nav";
+
+let capturedRowActions: readonly DataTableRowAction[] | undefined;
+const captureDataTable: ComponentType<DataTableProps> = (props) => {
+  capturedRowActions = props.rowActions;
+  return null;
+};
+const noop = (): ReactNode => null;
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+
+const testPrimitives: CorePrimitives = {
+  Button: noop,
+  Banner: passChildren,
+  Field: passChildren,
+  Input: noop,
+  DataTable: captureDataTable,
+  Form: passChildren,
+  Section: passChildren,
+  Card: passChildren,
+  Grid: passChildren,
+  GridCell: passChildren,
+  Text: passChildren,
+  Heading: noop,
+  Dialog: noop,
+  Modal: noop,
+  Lightbox: noop,
+  ConfigSourceBadge: noop,
+  ConfigCascadeView: noop,
+  Link: noop,
+};
+
+let queryCallCount = 0;
+let writeIsSuccess = true;
+
+function stubDispatcher(): Dispatcher {
+  return {
+    write: (async () => {
+      if (!writeIsSuccess) {
+        return {
+          isSuccess: false,
+          error: {
+            code: "unknown",
+            httpStatus: 500,
+            i18nKey: "kumiko:error:unknown",
+            message: "boom",
+          },
+        };
+      }
+      return { isSuccess: true, data: {} };
+    }) as unknown as Dispatcher["write"],
+    query: (async () => {
+      queryCallCount += 1;
+      return {
+        isSuccess: true,
+        data: { rows: [{ id: "unit-1", status: "active" }], nextCursor: null, total: 1 },
+      };
+    }) as unknown as Dispatcher["query"],
+    batch: (async () => ({ isSuccess: true, results: [] })) as unknown as Dispatcher["batch"],
+    statusStore: {
+      getState: () => "online",
+      subscribe: () => () => {},
+    } as unknown as Dispatcher["statusStore"],
+    async *stream() {},
+    pendingWrites: () => [],
+    pendingFiles: () => [],
+  };
+}
+
+function buildSchema(): FeatureSchema {
+  const entity: EntityDefinition = {
+    fields: {
+      status: {
+        type: "text",
+        maxLength: 50,
+        required: false,
+        searchable: false,
+        sortable: false,
+      },
+    },
+  };
+  const listScreen: EntityListScreenDefinition = {
+    id: "unit-list",
+    type: "entityList",
+    entity: "unit",
+    columns: ["status"],
+    rowActions: [
+      {
+        id: "archive",
+        label: "Archive",
+        handler: "units:write:unit:archive",
+      },
+    ],
+  };
+  return {
+    featureName: "units",
+    entities: { unit: entity },
+    screens: [listScreen],
+  } as FeatureSchema;
+}
+
+function renderListScreen(): void {
+  render(
+    <LocaleProvider
+      resolver={createStaticLocaleResolver({ locale: "de-DE" })}
+      fallbackBundles={[kumikoDefaultTranslations]}
+    >
+      <DispatcherProvider dispatcher={stubDispatcher()}>
+        <NavProvider
+          value={{
+            route: { screenId: "units:unit-list" },
+            navigate: () => {},
+            replace: () => {},
+            hrefFor: () => "",
+            searchParams: {},
+            setSearchParams: () => {},
+          }}
+        >
+          <PrimitivesProvider value={testPrimitives}>
+            <KumikoScreen schema={buildSchema()} qn="units:screen:unit-list" />
+          </PrimitivesProvider>
+        </NavProvider>
+      </DispatcherProvider>
+    </LocaleProvider>,
+  );
+}
+
+function requireArchiveAction(): DataTableRowAction {
+  const action = capturedRowActions?.find((a) => a.id === "archive");
+  if (!action) throw new Error("expected the 'archive' row action to be captured");
+  return action;
+}
+
+describe("entityList row-action writeHandler refetches the rows query", () => {
+  test("a successful row-action write triggers exactly one refetch", async () => {
+    capturedRowActions = undefined;
+    queryCallCount = 0;
+    writeIsSuccess = true;
+
+    renderListScreen();
+
+    await waitFor(() => {
+      expect(capturedRowActions).toBeDefined();
+    });
+
+    const countAfterMount = queryCallCount;
+    expect(countAfterMount).toBeGreaterThan(0);
+
+    await act(async () => {
+      await requireArchiveAction().onTrigger({ id: "unit-1", values: { id: "unit-1" } });
+    });
+
+    await waitFor(() => {
+      expect(queryCallCount).toBe(countAfterMount + 1);
+    });
+
+    // Give any accidental extra refetch a chance to land before asserting
+    // there wasn't one (no double-fetch, no refetch loop).
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(queryCallCount).toBe(countAfterMount + 1);
+  });
+
+  test("a failed row-action write does not refetch the rows query", async () => {
+    capturedRowActions = undefined;
+    queryCallCount = 0;
+    writeIsSuccess = false;
+
+    renderListScreen();
+
+    await waitFor(() => {
+      expect(capturedRowActions).toBeDefined();
+    });
+
+    const countAfterMount = queryCallCount;
+    expect(countAfterMount).toBeGreaterThan(0);
+
+    await act(async () => {
+      await expect(
+        requireArchiveAction().onTrigger({ id: "unit-1", values: { id: "unit-1" } }),
+      ).rejects.toThrow();
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(queryCallCount).toBe(countAfterMount);
+  });
+});

package/src/app/form-schema.ts

@@ -3,7 +3,7 @@ import type {
   EntityEditScreenDefinition,
   FieldDefinition,
 } from "@cosmicdrift/kumiko-framework/ui-types";
-import { evalFieldCondition } from "@cosmicdrift/kumiko-framework/ui-types";
+import { evalFieldCondition, NO_WIDGET_FIELD_TYPES } from "@cosmicdrift/kumiko-framework/ui-types";
 import { I18N_KEY_PARAM } from "@cosmicdrift/kumiko-headless";
 import { z } from "zod";
 import { layoutEditFields } from "./layout-fields";
@@ -16,23 +16,13 @@ function isPresent(value: unknown): boolean {
   return true;
 }
 
-// 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.
-// #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: ReadonlySet<FieldDefinition["type"]> = new Set([
-  "jsonb",
-  "embedded",
-  "files",
-  "images",
-]);
+// A statically-`required: true` field with no bound widget is caught
+// loudly at boot — validateNoWidgetRequiredField in
+// packages/framework/src/engine/boot-validator/screens.ts, sharing
+// NO_WIDGET_FIELD_TYPES with the presence check below.
+function isEmbeddedListField(field: FieldDefinition): boolean {
+  return field.type === "embedded" && field.multiple === true;
+}
 
 // Renders raw to the user without a de+en default in i18n-defaults.ts.
 export const REQUIRED_FIELD_I18N_KEY = "kumiko.validation.required";
@@ -86,7 +76,10 @@ export function buildFormSchema(
         const isRequired =
           spec.required === undefined ? entityRequired : evalFieldCondition(spec.required, record);
         if (!isRequired) continue;
-        if (FIELD_TYPES_WITHOUT_WIDGET.has(field.type)) continue;
+        // Embedded LIST fields get their own EmbeddedListField grid widget
+        // (#1838) — they're fillable, so NO_WIDGET_FIELD_TYPES's "embedded"
+        // entry must not exempt them from the presence check below.
+        if (NO_WIDGET_FIELD_TYPES.includes(field.type) && !isEmbeddedListField(field)) continue;
         if (isPresent(record[spec.field])) continue;
         ctx.addIssue({
           code: "custom",

package/src/app/kumiko-screen.tsx

@@ -1136,6 +1136,9 @@ function EntityListBody({
                 dispatcherErrorText(result.error, effectiveTranslate),
               );
             }
+            // Refetch — without a redirect nothing else remounts the screen,
+            // so the list would otherwise keep showing stale rows.
+            await rowsQuery.refetch();
           },
           isVisible:
             writeActionVisible !== undefined
@@ -1144,7 +1147,7 @@ function EntityListBody({
         };
       })
       .filter((a: DataTableRowAction | null): a is DataTableRowAction => a !== null);
-  }, [screen.rowActions, effectiveTranslate, dispatcher, runNavigate]);
+  }, [screen.rowActions, effectiveTranslate, dispatcher, runNavigate, rowsQuery.refetch]);
 
   // ToolbarActions: Schema → Resolved-Form (analog rowActions).
   // navigate-kind → useNav().navigate({ screenId }), writeHandler-kind
@@ -1186,11 +1189,13 @@ function EntityListBody({
                 dispatcherErrorText(result.error, effectiveTranslate),
               );
             }
+            // Same refetch as rowActions above.
+            await rowsQuery.refetch();
           },
         };
       })
       .filter((a: ToolbarActionButton | null): a is ToolbarActionButton => a !== null);
-  }, [screen.toolbarActions, effectiveTranslate, nav, dispatcher]);
+  }, [screen.toolbarActions, effectiveTranslate, nav, dispatcher, rowsQuery.refetch]);
 
   if (rowsQuery.loading && rowsQuery.data === null) {
     return (
@@ -1375,6 +1380,8 @@ function ProjectionListBody({
               dispatcherErrorText(result.error, effectiveTranslate),
             );
           }
+          // Same refetch as EntityListBody's rowActions above.
+          await rowsQuery.refetch();
         },
         ...(writeVisible !== undefined && {
           isVisible: (row: ListRowViewModel) => evalFieldCondition(writeVisible, row.values),
@@ -1382,7 +1389,7 @@ function ProjectionListBody({
       });
     }
     return out.length > 0 ? out : undefined;
-  }, [screen.rowActions, effectiveTranslate, runNavigate, dispatcher]);
+  }, [screen.rowActions, effectiveTranslate, runNavigate, dispatcher, rowsQuery.refetch]);
 
   const toolbarActions = useMemo((): readonly ToolbarActionButton[] | undefined => {
     if (screen.toolbarActions === undefined) return undefined;
@@ -1419,11 +1426,13 @@ function ProjectionListBody({
               dispatcherErrorText(result.error, effectiveTranslate),
             );
           }
+          // Same refetch as rowActions above.
+          await rowsQuery.refetch();
         },
       });
     }
     return out.length > 0 ? out : undefined;
-  }, [screen.toolbarActions, effectiveTranslate, nav, dispatcher]);
+  }, [screen.toolbarActions, effectiveTranslate, nav, dispatcher, rowsQuery.refetch]);
 
   if (rowsQuery.loading && rowsQuery.data === null) {
     return (

package/src/components/render-edit.tsx

@@ -473,8 +473,13 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   // 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 onControlsReadyRef = useRef(onControlsReady);
-  onControlsReadyRef.current = onControlsReady;
+  // 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).
+  // 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).
+  const deliveredControlsToRef = useRef<typeof onControlsReady>(undefined);
   const scopeFieldNamesRef = useRef(scopeFieldNames);
   scopeFieldNamesRef.current = scopeFieldNames;
   const scopedValidate = useCallback(
@@ -499,7 +504,15 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   const draftSaveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   useEffect(() => {
     return () => {
-      if (draftSaveTimerRef.current !== null) clearTimeout(draftSaveTimerRef.current);
+      if (draftSaveTimerRef.current !== null) {
+        clearTimeout(draftSaveTimerRef.current);
+        // Flush the pending debounced save instead of dropping it — a
+        // navigation/unmount inside the debounce window would otherwise
+        // silently discard the last patch() (discardDraft nulls this ref
+        // first on the post-submit path, so this can't resurrect a
+        // just-submitted draft).
+        saveDraftRef.current(currentStepRef.current);
+      }
     };
   }, []);
 
@@ -529,9 +542,10 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   // available on the very first onChange call, not just from the second
   // keystroke onward.
   useEffect(() => {
-    const cb = onControlsReadyRef.current;
-    if (cb === undefined) return;
-    cb({
+    if (onControlsReady === undefined) return;
+    if (deliveredControlsToRef.current === onControlsReady) return;
+    deliveredControlsToRef.current = onControlsReady;
+    onControlsReady({
       patch: patchAndScheduleDraftSave,
       validate: scopedValidate,
       getValues: () => controller.getSnapshot().values,
@@ -539,9 +553,10 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     });
     // 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]);
+    // 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]);
 
   const schemaRef = useRef(schema);
   schemaRef.current = schema;
@@ -647,6 +662,10 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   // (see draftCandidates below) — adopt it the same way a single
   // auto-adopted candidate would be.
   function adoptDraft(candidate: DraftCandidate): void {
+    // Locked state (#1896/fw#1909): `disabled` means "no write possible" —
+    // repointing draftKey and patching in the candidate's values is exactly
+    // that, so a locked form must not adopt a draft.
+    if (disabled) return;
     const adoptedId = candidate.draftKey.slice(newDraftPrefix(screen.id).length);
     draftStorage.setDraftId(screen.id, adoptedId);
     setDraftId(adoptedId);
@@ -666,7 +685,17 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   );
 
   const filteredSections = useMemo(
-    () => filterEditSections(vm.sections, fieldsFilter),
+    // A fully-hidden "fields" section (every field in it currently
+    // condition-hidden) must not occupy a wizard step; it would render
+    // empty and block Back/Next on nothing. Extension sections carry no
+    // `visible` (they own their own dirty/save lifecycle), 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).
+    () =>
+      filterEditSections(vm.sections, fieldsFilter).filter(
+        (section) => section.kind === "extension" || section.fields.length === 0 || section.visible,
+      ),
     [vm.sections, fieldsFilter],
   );
 
@@ -889,10 +918,14 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
       let extensionsPersisted = true;
       if (result.isSuccess) {
         setFormError(null);
-        // 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.
-        await discardDraft();
+        // `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:
+        // `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();
         extensionsPersisted = await persistExtensions();
       } else if (result.validationBlocked) {
         // Root-level `.refine()`/cross-field issues from controller.validate()
@@ -959,6 +992,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
           type="button"
           variant="danger"
           testId="render-edit-delete"
+          disabled={disabled}
           onClick={() => setConfirmDeleteOpen(true)}
         >
           {translate("kumiko.actions.delete")}

package/src/i18n-defaults.ts

@@ -89,6 +89,11 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     // Widgets — StepBar screen-reader text for completed steps whose number is visually replaced by a checkmark.
     "kumiko.widget.step-bar.done": "Erledigt",
 
+    // Widgets — Drawer resize handle + maximize toggle aria-labels.
+    "kumiko.widget.drawer.restore": "Drawer-Breite zurücksetzen",
+    "kumiko.widget.drawer.maximize": "Drawer maximieren",
+    "kumiko.widget.drawer.resize": "Drawer-Größe ändern",
+
     // Nav — Sidebar Tree (Toggle-aria-Labels).
     "kumiko.nav.expand": "Aufklappen",
     "kumiko.nav.collapse": "Zuklappen",
@@ -269,6 +274,10 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
 
     "kumiko.widget.step-bar.done": "Done",
 
+    "kumiko.widget.drawer.restore": "Restore drawer width",
+    "kumiko.widget.drawer.maximize": "Maximize drawer width",
+    "kumiko.widget.drawer.resize": "Resize drawer",
+
     "kumiko.nav.expand": "Expand",
     "kumiko.nav.collapse": "Collapse",
     "kumiko.nav.search": "Search navigation…",