@cosmicdrift/kumiko-renderer 0.294.1 → 0.296.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.294.1",
+  "version": "0.296.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,9 +15,9 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.294.1",
-    "@cosmicdrift/kumiko-headless": "0.294.1",
-    "@cosmicdrift/kumiko-types": "0.294.1",
+    "@cosmicdrift/kumiko-framework": "0.296.0",
+    "@cosmicdrift/kumiko-headless": "0.296.0",
+    "@cosmicdrift/kumiko-types": "0.296.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
@@ -28,7 +28,7 @@
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
     "react-dom": "^19.2.6",
-    "@cosmicdrift/kumiko-locale-de": "0.294.1"
+    "@cosmicdrift/kumiko-locale-de": "0.296.0"
   },
   "repository": {
     "type": "git",

package/src/app/__tests__/projection-detail-reference-field.test.tsx

@@ -60,10 +60,12 @@ function stubDispatcher(): Dispatcher {
           data: { id: "sess-1", userId: "u-1", actedBy: SYSTEM_USER_ID, ip: "10.0.0.1" },
         };
       }
-      if (type === "user:query:user:list") {
+      // user:user resolves through the tenant-scoped member directory, not the
+      // SystemAdmin-only user:query:user:list a TenantAdmin can't call (fw#3107).
+      if (type === "tenant:query:member-directory") {
         return {
           isSuccess: true,
-          data: { rows: [{ id: "u-1", displayName: "Jane Doe" }], nextCursor: null },
+          data: { rows: [{ id: "u-1", label: "Jane Doe" }], nextCursor: null },
         };
       }
       return { isSuccess: true, data: { rows: [], nextCursor: null } };

package/src/app/__tests__/projection-list-reference-column.test.tsx

@@ -75,16 +75,21 @@ function stubDispatcher(): Dispatcher {
           },
         };
       }
-      if (type === "tenant:query:tenant:list") {
+      // tenant:tenant resolves through the tenant directory, not the
+      // SystemAdmin-only tenant:query:tenant:list a TenantAdmin can't call
+      // (fw#3142).
+      if (type === "tenant:query:tenant-directory") {
         return {
           isSuccess: true,
-          data: { rows: [{ id: REAL_TENANT_ID, name: "Acme Inc" }], nextCursor: null },
+          data: { rows: [{ id: REAL_TENANT_ID, label: "Acme Inc" }], nextCursor: null },
         };
       }
-      if (type === "user:query:user:list") {
+      // user:user resolves through the tenant-scoped member directory, not the
+      // SystemAdmin-only user:query:user:list a TenantAdmin can't call (fw#3107).
+      if (type === "tenant:query:member-directory") {
         return {
           isSuccess: true,
-          data: { rows: [{ id: REAL_USER_ID, displayName: "Ada Lovelace" }], nextCursor: null },
+          data: { rows: [{ id: REAL_USER_ID, label: "Ada Lovelace" }], nextCursor: null },
         };
       }
       return { isSuccess: true, data: { rows: [], nextCursor: null } };

package/src/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.296.0",
+    "type": "improvement",
+    "title": "entityEdit accepts layout.mode \"tabs\" (fw#3134)",
+    "detail": "A long edit form no longer has to choose between one endless page\n(`mode: \"single\"`) and a forced walk through every step (`mode: \"wizard\"`).\nTabs were rejected at boot because a required field on a hidden tab would block\nsubmit with nothing on screen to explain it.\nWhat resolves that is not scoping validation to the active tab — that would\nskip the field instead of showing it — but the opposite: every tab stays\nmounted, one submit validates across all of them, and a field error activates\nthe tab holding it. Values from a tab the user never opened travel with that\nsubmit. The tab strip needs the same per-tab `id` and title projectionDetail\nalready requires, now checked by a shared validator for both.\n`actionForm`, `configEdit` and `secretMint` still reject tabs: none of them has\na jump-to-erroring-tab path, so the silent-block failure would remain.\nThe tab is activated, not focused — focus would need a platform-specific call\nthis layer does not have. The error renders inline on the now-visible field.\nTwo side effects worth knowing before declaring a tabs layout: a section that\nomits `columns` defaults to 2 under tabs (the existing projectionDetail rule now\nalso reaches entityEdit), and the section title is dropped from the panel\nbecause the tab label already carries it.",
+    "migration": "Nothing to change: `single` and `wizard` behave as before. A screen that\nswitches to `mode: \"tabs\"` needs at least two sections, each with a title and\na kebab-case `id` — the same shape projectionDetail already requires. Two\ndefaults differ from `single` inside a tabs layout: a section that omits\n`columns` renders in 2 columns, and its title is dropped from the panel\nbecause the tab label carries it."
+  },
   {
     "version": "0.292.0",
     "type": "fix",

package/src/components/embedded-list-field.tsx

@@ -11,9 +11,9 @@ import {
   sumEmbeddedListColumn,
 } from "@cosmicdrift/kumiko-headless";
 import { type ReactNode, useState } from "react";
-import { toKebab } from "../app/qn";
 import { REFERENCE_COMBOBOX_LIMIT } from "../hooks/reference-limits";
 import { useQuery } from "../hooks/use-query";
+import { referenceLookupSource } from "../hooks/use-reference-lookup";
 import { useTranslation } from "../i18n";
 import type { EmbeddedListColumn, EmbeddedListTotal } from "../primitives";
 import { usePrimitives } from "../primitives";
@@ -148,15 +148,21 @@ export function EmbeddedListField({
   const derived = field.embeddedListDerived;
 
   const referenceCells = cells.filter((c) => c.type === "reference");
-  const referenceQueries = referenceCells.map((cell) => {
-    const refFeature = cell.refFeature ?? featureName;
-    const refEntity = cell.refEntity ?? "";
-    const qn = cell.refOptionsQuery ?? `${toKebab(refFeature)}:query:${toKebab(refEntity)}:list`;
+  const referenceSources = referenceCells.map((cell) =>
+    cell.refOptionsQuery !== undefined
+      ? { queryQn: cell.refOptionsQuery, labelKey: "label" }
+      : referenceLookupSource(
+          cell.refFeature ?? featureName,
+          cell.refEntity ?? "",
+          cell.refLabelField ?? "id",
+        ),
+  );
+  const referenceQueries = referenceSources.map((source) =>
     // biome-ignore lint/correctness/useHookAtTopLevel: referenceCells comes from the entity-schema definition — fixed for the screen's lifetime, not a real conditional-hook risk.
-    return useQuery<{ rows: ReadonlyArray<Record<string, unknown>> }>(qn, {
+    useQuery<{ rows: ReadonlyArray<Record<string, unknown>> }>(source.queryQn, {
       limit: REFERENCE_COMBOBOX_LIMIT,
-    });
-  });
+    }),
+  );
 
   if (EmbeddedListInput === undefined) return null;
 
@@ -165,7 +171,7 @@ export function EmbeddedListField({
     if (cell.type === "reference") {
       const idx = referenceCells.indexOf(cell);
       const query = referenceQueries[idx];
-      const labelKey = cell.refOptionsQuery !== undefined ? "label" : (cell.refLabelField ?? "id");
+      const labelKey = referenceSources[idx]?.labelKey ?? "id";
       const referenceOptions = (query?.data?.rows ?? []).map((row) => ({
         value: String(row["id"] ?? ""),
         label: String(row[labelKey] ?? row["id"] ?? ""),

package/src/components/render-edit.tsx

@@ -109,6 +109,16 @@ function toConditionValue<TValues extends FormValues, TCtx>(
   return (values: TValues) => evalFieldCondition(cond, values as Record<string, unknown>);
 }
 
+// Tab-strip key. The boot-validator makes `id` mandatory on a tabs layout and
+// entityEdit only ever has "fields"/"extension" sections (relatedList and
+// writeForm are rejected outright), so the positional fallback is unreachable
+// for a tabs screen — it only keeps this total for other layouts.
+function tabIdAt(section: EditSectionViewModel | undefined, index: number): string {
+  const declared =
+    section?.kind === "fields" || section?.kind === "extension" ? section.id : undefined;
+  return declared ?? `section-${index}`;
+}
+
 function deriveFormFields<TValues extends FormValues, TCtx>(
   screen: EntityEditScreenDefinition,
 ): Record<string, FieldConditions<TValues, TCtx>> {
@@ -285,6 +295,11 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   const dispatcher = useOptionalDispatcher();
 
   const isWizard = screen.layout.mode === "wizard";
+  // 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).
+  const isTabs = screen.layout.mode === "tabs";
   const draftEnabled = isWizard && screen.layout.draft === true && dispatcher !== undefined;
   const isCreateMode = entityIdProp === undefined || entityIdProp === null || entityIdProp === "";
   const draftStorage = useDraftStorage();
@@ -350,8 +365,14 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     Progress,
     StepBar,
     WizardStepGroup,
+    Tabs,
   } = usePrimitives();
 
+  // 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).
+  const isStepped = isWizard || (isTabs && Tabs !== undefined);
   const fields = useMemo(() => deriveFormFields<TValues, TCtx>(screen), [screen]);
 
   // Must be computed before submitConfig/useForm bakes it in (the controller
@@ -683,8 +704,10 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   // button, and it can never go dirty either.
   const isFieldless = Object.keys(entity.fields).length === 0;
 
-  // A lone relatedList tab (hideSectionTitles is only ever set by the tabs
-  // layout, which also narrows filteredSections to that one active section)
+  // A lone relatedList tab (`hideSectionTitles` is only ever set by
+  // ProjectionDetailBody, which hands this component ONE section — its
+  // synthesized screen drops layout.mode, so an entityEdit tabs layout never
+  // 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
@@ -850,14 +873,16 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     }
   }
 
-  // Wizard mode: locates the first step whose "fields" section contains one
-  // of the given field paths — matched on the path's first segment, since
-  // `FieldIssue.path`/`snapshot.errors` keys can be dotted (embedded-list
-  // rows, e.g. `tasks.2.title`) while a section's field name is always the
-  // plain top-level name. Returns undefined for a root-level issue (path
-  // `"(root)"`, see zod-bridge.ts) or one that matches no rendered field —
-  // callers must NOT suppress the error banner in that case, there is
-  // nowhere to jump the user to.
+  // Stepped modes (wizard, tabs): locates the first step whose "fields"
+  // section contains one of the given field paths — matched on the path's
+  // first segment, since `FieldIssue.path`/`snapshot.errors` keys can be
+  // dotted (embedded-list rows, e.g. `tasks.2.title`) while a section's field
+  // name is always the plain top-level name. Returns undefined for a
+  // root-level issue (path `"(root)"`, see zod-bridge.ts) or one that matches
+  // no rendered field — callers must NOT suppress the error banner in that
+  // case, there is nowhere to jump the user to. Extension sections are not
+  // jump targets by design: they validate through the controlled-mode
+  // controls.validate() API and own no field specs to match against.
   function findFirstErroringStep(fieldPaths: readonly string[]): number | undefined {
     const erroredFields = new Set(fieldPaths.map((p) => p.split(".")[0]));
     const idx = filteredSections.findIndex(
@@ -956,18 +981,21 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
         // Root-level `.refine()`/cross-field issues from controller.validate()
         // — same "jump to the erroring step" treatment as a server field
         // error below, sourced from the freshly-validated snapshot.
-        if (isWizard) {
+        if (isStepped) {
           const step = findFirstErroringStep(Object.keys(controller.getSnapshot().errors));
           if (step !== undefined) setRawStep(step);
         }
       } else {
         const fieldIssues = result.error.details?.fields ?? [];
-        // A server field error on a step the wizard isn't currently showing
-        // is otherwise invisible — jump to the first step that contains one
-        // of the errored fields. Non-wizard forms render every field at
-        // once, so the original suppress-when-field-issues-exist rule still
-        // applies there (the field itself already shows the error inline).
-        if (isWizard) {
+        // A server field error on a step the form isn't currently showing is
+        // 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). Single-section
+        // forms render every field at once, so the original
+        // suppress-when-field-issues-exist rule still applies there (the
+        // field itself already shows the error inline).
+        if (isStepped) {
           const step = findFirstErroringStep(fieldIssues.map((i) => i.path));
           if (step !== undefined) {
             setRawStep(step);
@@ -1293,18 +1321,44 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
             })()}
           </>
         )}
+        {isTabs &&
+          (() => {
+            // No Tabs primitive registered → every section renders stacked
+            // (stepHidden below is gated on the same condition), which is the
+            // single-layout behaviour. Degrading to one long form beats
+            // hiding sections behind a strip that never drew.
+            if (Tabs === undefined) return null;
+            return (
+              <Tabs
+                testId="render-edit-tabs"
+                items={filteredSections.map((section, index) => ({
+                  id: tabIdAt(section, index),
+                  label: section.title ?? "",
+                }))}
+                activeId={tabIdAt(filteredSections[currentStep], currentStep)}
+                onSelect={(id) => {
+                  const index = filteredSections.findIndex((s, i) => tabIdAt(s, i) === id);
+                  // skip: the strip reported an id no section owns.
+                  if (index === -1) return;
+                  setRawStep(index);
+                }}
+              />
+            );
+          })()}
         {filteredSections.map((section: EditSectionViewModel, sectionIndex: number) => {
-          // Wizard steps stay mounted while off-screen (native `hidden`, not
-          // unmounted) so an extension section's submit-registry entry
-          // (useExtensionFormSubmit → registry.remove on unmount) survives
-          // navigating past its step — otherwise Finish only ran the last
-          // mounted step's handler and silently dropped earlier steps' writes.
-          const stepHidden = isWizard && sectionIndex !== currentStep;
+          // Wizard steps and tabs stay mounted while off-screen (native
+          // `hidden`, not unmounted) so an extension section's submit-registry
+          // entry (useExtensionFormSubmit → registry.remove on unmount)
+          // 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).
+          const stepHidden = isStepped && sectionIndex !== currentStep;
           const wrapWizardStep = (key: string, el: ReactNode): ReactNode => {
-            if (!isWizard) return el;
+            if (!isStepped) return el;
             if (WizardStepGroup === undefined) {
               throw new Error(
-                "RenderEdit: wizard layout requires primitives.WizardStepGroup, but none is registered.",
+                `RenderEdit: ${screen.layout.mode} layout requires primitives.WizardStepGroup, but none is registered.`,
               );
             }
             return (
@@ -1446,8 +1500,12 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
             return wrapWizardStep(sectionKey, cardEl);
           }
           // Suppress the section header when it would just repeat the form
-          // title verbatim (typical for single-section actionForms).
-          const sectionTitle = section.title === formTitle ? undefined : section.title;
+          // title verbatim (typical for single-section actionForms), or the
+          // tab label right above it. Without a Tabs primitive the sections
+          // render stacked, and then the titles are what tells them apart.
+          const repeatsTabLabel = isTabs && isStepped;
+          const sectionTitle =
+            section.title === formTitle || repeatsTabLabel ? undefined : section.title;
           const sectionEl = (
             <Section
               key={sectionKey}

package/src/components/render-field.tsx

@@ -20,6 +20,7 @@ import { screenAccessAllows } from "../app/screen-access";
 import { useUserRoles } from "../context/user-roles-context";
 import { REFERENCE_COMBOBOX_LIMIT } from "../hooks/reference-limits";
 import { useQuery } from "../hooks/use-query";
+import { referenceLookupSource } from "../hooks/use-reference-lookup";
 import { useLocale, useTranslation } from "../i18n";
 import { usePrimitives } from "../primitives";
 import { EmbeddedListField } from "./embedded-list-field";
@@ -179,10 +180,7 @@ function referenceOptionSource(
   if (field.refOptionsQuery !== undefined) {
     return { queryQn: field.refOptionsQuery, labelKey: "label" };
   }
-  return {
-    queryQn: `${toKebab(refFeature)}:query:${toKebab(refEntity)}:list`,
-    labelKey: field.refLabelField ?? "id",
-  };
+  return referenceLookupSource(refFeature, refEntity, field.refLabelField ?? "id");
 }
 
 // Tier 2.7e-3 + 2.1c: Reference-Input rendert eine Searchable Combobox

package/src/hooks/use-reference-lookup.ts

@@ -17,7 +17,10 @@
 // internen Cache shared zwischen List + Edit-Form für die gleiche
 // Entity, Live-Updates kommen via SSE (use-query-live).
 
-import { SYSTEM_REFERENCE_LABELS } from "@cosmicdrift/kumiko-framework/ui-types";
+import {
+  REFERENCE_LOOKUP_SOURCES,
+  SYSTEM_REFERENCE_LABELS,
+} from "@cosmicdrift/kumiko-framework/ui-types";
 import { useMemo } from "react";
 import { toKebab } from "../app/qn";
 import { useTranslation } from "../i18n";
@@ -26,19 +29,30 @@ import { useQuery } from "./use-query";
 
 export type ReferenceLookupMap = ReadonlyMap<string, string>;
 
-/** Bulk-Lookup für eine einzelne Reference-Spalte. Liefert eine Map
- *  von UUID → Display-Value (aus labelField). Während die Query lädt,
- *  ist die Map leer; der Caller fällt dann auf den UUID-Fallback.
- *
- *  `featureName` ist hier das **target**-Feature (refFeature aus
- *  ViewModel), nicht das current Feature — Cross-Feature-Refs lookup
- *  laufen damit gegen `<refFeature>:query:<refEntity>:list`. */
+/** Where a reference target's label rows come from: the central override for
+ *  that `feature:entity` if one exists, else the entity-convention list
+ *  handler plus the caller's own label field. */
+export function referenceLookupSource(
+  refFeature: string,
+  refEntity: string,
+  labelField: string,
+): { readonly queryQn: string; readonly labelKey: string } {
+  const override = REFERENCE_LOOKUP_SOURCES[`${refFeature}:${refEntity}`];
+  if (override !== undefined) return override;
+  return {
+    queryQn: `${toKebab(refFeature)}:query:${toKebab(refEntity)}:list`,
+    labelKey: labelField,
+  };
+}
+
+/** Empty while the query loads (or fails), so callers fall back to the raw id.
+ *  `featureName` is the reference's target feature, not the screen's. */
 export function useReferenceLookup(
   featureName: string,
   refEntity: string,
   labelField: string,
 ): { readonly map: ReferenceLookupMap; readonly loading: boolean } {
-  const queryQn = `${toKebab(featureName)}:query:${toKebab(refEntity)}:list`;
+  const { queryQn, labelKey } = referenceLookupSource(featureName, refEntity, labelField);
   const result = useQuery<{ rows: ReadonlyArray<Record<string, unknown>> }>(queryQn, {
     limit: REFERENCE_LIST_LOOKUP_LIMIT,
   });
@@ -50,13 +64,13 @@ export function useReferenceLookup(
       const id = row["id"];
       if (id === undefined || id === null) continue;
       const idStr = String(id);
-      const label = row[labelField] ?? id;
+      const label = row[labelKey] ?? id;
       out.set(idStr, String(label));
     }
     // System-scope ids (e.g. SYSTEM_TENANT_ID) never have a backing row, so
     // the bulk lookup above never covers them — inject the label directly.
     if (systemLabel !== undefined) out.set(systemLabel.id, translate(systemLabel.labelKey));
     return out;
-  }, [result.data, labelField, systemLabel, translate]);
+  }, [result.data, labelKey, systemLabel, translate]);
   return { map, loading: result.loading };
 }