@cosmicdrift/kumiko-renderer-web 0.226.0 → 0.228.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer-web",
-  "version": "0.226.0",
+  "version": "0.228.0",
   "description": "Web-platform bindings for @cosmicdrift/kumiko-renderer. HTML default-primitives, browser history-based navigation, EventSource-backed live events, and a one-call createKumikoApp that mounts the whole stack via react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -16,9 +16,9 @@
     "./styles.css": "./src/styles.css"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.226.0",
-    "@cosmicdrift/kumiko-headless": "0.226.0",
-    "@cosmicdrift/kumiko-renderer": "0.226.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.228.0",
+    "@cosmicdrift/kumiko-headless": "0.228.0",
+    "@cosmicdrift/kumiko-renderer": "0.228.0",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-label": "^2.1.8",
@@ -64,7 +64,7 @@
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
     "tailwindcss": "^4.3.0",
-    "@cosmicdrift/kumiko-locale-de": "0.226.0"
+    "@cosmicdrift/kumiko-locale-de": "0.228.0"
   },
   "repository": {
     "type": "git",

package/src/__tests__/projection-detail-record-layout.test.tsx

@@ -6,7 +6,14 @@ import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
 import type { FeatureSchema, NavApi } from "@cosmicdrift/kumiko-renderer";
 import { DispatcherProvider, KumikoScreen, NavProvider } from "@cosmicdrift/kumiko-renderer";
 import userEvent from "@testing-library/user-event";
-import { createMockDispatcher, render, screen, waitFor } from "./test-utils";
+import { type ReactNode, useState } from "react";
+import {
+  createMockDispatcher,
+  render,
+  renderWithPrimitivesOverride,
+  screen,
+  waitFor,
+} from "./test-utils";
 
 const baseScreen: ProjectionDetailScreenDefinition = {
   id: "rent-detail",
@@ -124,6 +131,57 @@ describe("KumikoScreen / projectionDetail — record header + metrics band", ()
   });
 });
 
+describe("KumikoScreen / projectionDetail — metric tiles render through the Metric primitive", () => {
+  const metricsScreen: ProjectionDetailScreenDefinition = {
+    ...baseScreen,
+    metrics: ["balance"],
+  };
+
+  test("goes through the Metric primitive, not naked Text, when one is registered", async () => {
+    const dispatcher = dispatcherReturning(rowData);
+
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen
+          schema={schemaFor(metricsScreen)}
+          qn="rentals:screen:rent-detail"
+          entityId="rent-1"
+        />
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() => screen.getByTestId("render-edit-form"));
+    // Only the Metric primitive assigns a testid to the tile itself — the
+    // naked-Text fallback below only labels the -label/-value nodes. This
+    // is red against the pre-fix code (naked Text, no tile testid).
+    expect(screen.getByTestId("kumiko-screen-projection-detail-metric-balance")).toBeTruthy();
+    expect(
+      screen.getByTestId("kumiko-screen-projection-detail-metric-balance-value").textContent,
+    ).toBe("120");
+  });
+
+  test("falls back to plain label/value Text when no Metric primitive is registered", async () => {
+    const dispatcher = dispatcherReturning(rowData);
+
+    renderWithPrimitivesOverride(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen
+          schema={schemaFor(metricsScreen)}
+          qn="rentals:screen:rent-detail"
+          entityId="rent-1"
+        />
+      </DispatcherProvider>,
+      { Metric: undefined },
+    );
+
+    await waitFor(() => screen.getByTestId("render-edit-form"));
+    expect(
+      screen.getByTestId("kumiko-screen-projection-detail-metric-balance-value").textContent,
+    ).toBe("120");
+    expect(screen.queryByTestId("kumiko-screen-projection-detail-metric-balance")).toBeNull();
+  });
+});
+
 describe("KumikoScreen / projectionDetail — layout.mode: 'tabs'", () => {
   const tabsScreen: ProjectionDetailScreenDefinition = {
     ...baseScreen,
@@ -167,6 +225,92 @@ describe("KumikoScreen / projectionDetail — layout.mode: 'tabs'", () => {
     };
   }
 
+  // Reactive nav stub — navWithTab's searchParams is fixed at mount, so it
+  // can't exercise a real "click a tab, watch the active section change"
+  // flow. Only used by the tab-switch test below.
+  function StatefulTabNav({ children }: { readonly children: ReactNode }): ReactNode {
+    const [tab, setTab] = useState<string | undefined>(undefined);
+    const navApi: NavApi = {
+      route: undefined,
+      navigate: () => {},
+      replace: () => {},
+      hrefFor: () => "",
+      searchParams: tab !== undefined ? { tab } : {},
+      setSearchParams: (updates) => {
+        const next = updates["tab"];
+        setTab(next === null || next === undefined ? undefined : next);
+      },
+    };
+    return <NavProvider value={navApi}>{children}</NavProvider>;
+  }
+
+  test("switching tabs does not remount the body or refire the detail query", async () => {
+    const dispatcher = dispatcherReturning(rowData);
+    const user = userEvent.setup();
+
+    render(
+      <StatefulTabNav>
+        <DispatcherProvider dispatcher={dispatcher}>
+          <KumikoScreen
+            schema={schemaFor(tabsScreen)}
+            qn="rentals:screen:rent-detail"
+            entityId="rent-1"
+          />
+        </DispatcherProvider>
+      </StatefulTabNav>,
+    );
+
+    await waitFor(() => screen.getByTestId("render-edit-form"));
+    const detailCallsBefore = dispatcher.calls.filter(
+      (c) => c.type === "rentals:query:rent:detail",
+    ).length;
+    expect(detailCallsBefore).toBe(1);
+
+    const trigger = await waitFor(() =>
+      screen.getByTestId("kumiko-screen-projection-detail-tabs-payments"),
+    );
+    await user.click(trigger);
+    await waitFor(() =>
+      expect(dispatcher.calls.some((c) => c.type === "rentals:query:rent:payments")).toBe(true),
+    );
+
+    // A `key` on the record identifier alone (fw#2518 fix) must not also
+    // depend on the active tab — folding tab into the key would remount the
+    // body on every tab click and refire this query. The pre-fix "fires
+    // exactly one query" test above only checks first render and would not
+    // have caught that regression.
+    const detailCallsAfter = dispatcher.calls.filter(
+      (c) => c.type === "rentals:query:rent:detail",
+    ).length;
+    expect(detailCallsAfter).toBe(detailCallsBefore);
+  });
+
+  test("tabs mode suppresses the form's own redundant title, not just section titles", async () => {
+    const dispatcher = dispatcherReturning(rowData);
+    const { navApi } = navWithTab(undefined);
+
+    render(
+      <NavProvider value={navApi}>
+        <DispatcherProvider dispatcher={dispatcher}>
+          <KumikoScreen
+            schema={schemaFor(tabsScreen)}
+            qn="rentals:screen:rent-detail"
+            entityId="rent-1"
+          />
+        </DispatcherProvider>
+      </NavProvider>,
+    );
+
+    await waitFor(() => screen.getByTestId("render-edit-form"));
+    // hideSectionTitles used to only blank out each Section's own title —
+    // RenderEdit's own Form-level title (screen id/i18n fallback) rendered
+    // unconditionally regardless, duplicating the active tab's label
+    // whenever the two happened to read the same ("Mietvertrag" above the
+    // table, matching the already-visible tab). This asserts the Form-level
+    // title is gone too, not just the section ones.
+    expect(screen.queryByTestId("render-edit-form-title")).toBeNull();
+  });
+
   test("fires exactly one query on first render — the inactive tabs' relatedList queries never fire", async () => {
     const dispatcher = dispatcherReturning(rowData);
     const { navApi } = navWithTab(undefined);
@@ -301,5 +445,55 @@ describe("KumikoScreen / projectionDetail — unchanged for a solon-shaped scree
       expect(dispatcher.calls.some((c) => c.type === "rentals:query:rent:invoices")).toBe(true),
     );
     expect(screen.queryByTestId("kumiko-screen-projection-detail-tabs")).toBeNull();
+    // Contrast for the tabs-mode "form title suppressed" test above — outside
+    // tabs mode (hideSectionTitles unset) the form's own title still renders.
+    expect(screen.getByTestId("render-edit-form-title")).toBeTruthy();
+  });
+});
+
+describe("KumikoScreen / projectionDetail — switching records remounts the body (fw#2518)", () => {
+  test("record A's fields are gone from the DOM after switching to record B", async () => {
+    const dataById: Record<string, Readonly<Record<string, unknown>>> = {
+      "rent-1": { description: "Loft 4B" },
+      "rent-2": { description: "Warehouse 9" },
+    };
+    const query = (async (type: string, payload: unknown) => {
+      if (type === "rentals:query:rent:detail") {
+        const id = (payload as { id?: string }).id ?? "";
+        return { isSuccess: true, data: dataById[id] ?? {} };
+      }
+      return { isSuccess: true, data: { rows: [], nextCursor: null } };
+    }) as unknown as Dispatcher["query"];
+    const dispatcher = createMockDispatcher({ query });
+
+    const { rerender } = render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen
+          schema={schemaFor(baseScreen)}
+          qn="rentals:screen:rent-detail"
+          entityId="rent-1"
+        />
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() => screen.getByText("Loft 4B"));
+
+    rerender(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen
+          schema={schemaFor(baseScreen)}
+          qn="rentals:screen:rent-detail"
+          entityId="rent-2"
+        />
+      </DispatcherProvider>,
+    );
+
+    // Without the key fix, React keeps the old ProjectionDetailBody instance
+    // mounted and briefly renders record A's fields until the new query
+    // resolves. Asserting only the ABSENCE of "Loft 4B" would pass on flaky
+    // timing even without the fix, so this also waits for record B's own
+    // value to confirm the remount actually completed.
+    await waitFor(() => screen.getByText("Warehouse 9"));
+    expect(screen.queryByText("Loft 4B")).toBeNull();
   });
 });

package/src/__tests__/projection-detail.test.tsx

@@ -9,7 +9,12 @@ import { describe, expect, test } from "bun:test";
 import type { ProjectionDetailScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
 import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
 import type { FeatureSchema, NavApi, NavTarget } from "@cosmicdrift/kumiko-renderer";
-import { DispatcherProvider, KumikoScreen, NavProvider } from "@cosmicdrift/kumiko-renderer";
+import {
+  DispatcherProvider,
+  ExtensionSectionsProvider,
+  KumikoScreen,
+  NavProvider,
+} from "@cosmicdrift/kumiko-renderer";
 import { act, createMockDispatcher, fireEvent, render, screen, waitFor } from "./test-utils";
 
 const detailScreen: ProjectionDetailScreenDefinition = {
@@ -470,3 +475,141 @@ describe("KumikoScreen / projectionDetail relatedList section (fw#2166)", () =>
     expect(navigated).toBeUndefined();
   });
 });
+
+// solon#264: a hand-written NotesSection block had no declarative equivalent
+// on projectionDetail. Extension sections without contributesToFormSubmit
+// (self-persisting, e.g. via their own dispatcher writes) are now allowed.
+describe("KumikoScreen / projectionDetail extension section (solon#264)", () => {
+  const SessionNotes = ({
+    entityName,
+    entityId,
+  }: {
+    entityName: string;
+    entityId: string | null;
+  }) => (
+    <div data-testid="session-notes">
+      {entityName}:{entityId ?? "(none)"}
+    </div>
+  );
+
+  test("mounts and receives the route entityId and the section's declared entityName, no submit button", async () => {
+    const extensionScreen: ProjectionDetailScreenDefinition = {
+      ...detailScreen,
+      layout: {
+        sections: [
+          ...detailScreen.layout.sections,
+          {
+            kind: "extension",
+            title: "Notes",
+            component: { react: { __component: "SessionNotes" } },
+            entityName: "user-session",
+          },
+        ],
+      },
+    };
+    const extensionSchema: FeatureSchema = {
+      featureName: "sessions",
+      entities: {},
+      screens: [extensionScreen],
+    };
+    const dispatcher: Dispatcher = createMockDispatcher({
+      query: (async () => ({
+        isSuccess: true,
+        data: { userId: "user-42", createdAt: "2026-07-01T00:00:00Z" },
+      })) as unknown as Dispatcher["query"],
+    });
+
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <ExtensionSectionsProvider value={{ SessionNotes }}>
+          <KumikoScreen
+            schema={extensionSchema}
+            qn="sessions:screen:session-detail"
+            entityId="sess-1"
+          />
+        </ExtensionSectionsProvider>
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() => screen.getByTestId("render-edit-form"));
+    // Declared entityName ("user-session") must win over the shim's internal
+    // placeholder entity name — otherwise a self-persisting section like
+    // NotesSection would filter/write against the wrong domain entity.
+    expect(screen.getByTestId("session-notes").textContent).toBe("user-session:sess-1");
+    expect(screen.queryByTestId("render-edit-submit")).toBeNull();
+  });
+
+  test("layout.mode: 'tabs' — mounts only when its tab is active, not on first render of another tab", async () => {
+    const tabsExtensionScreen: ProjectionDetailScreenDefinition = {
+      ...detailScreen,
+      layout: {
+        mode: "tabs",
+        sections: [
+          { id: "overview", title: "Session", fields: ["userId"] },
+          {
+            id: "notes",
+            kind: "extension",
+            title: "Notes",
+            component: { react: { __component: "SessionNotes" } },
+            entityName: "user-session",
+          },
+        ],
+      },
+    };
+    const tabsExtensionSchema: FeatureSchema = {
+      featureName: "sessions",
+      entities: {},
+      screens: [tabsExtensionScreen],
+    };
+    const dispatcher: Dispatcher = createMockDispatcher({
+      query: (async () => ({
+        isSuccess: true,
+        data: { userId: "user-42", createdAt: "2026-07-01T00:00:00Z" },
+      })) as unknown as Dispatcher["query"],
+    });
+    function navWithTab(tab: string | undefined): NavApi {
+      return {
+        route: undefined,
+        navigate: () => {},
+        replace: () => {},
+        hrefFor: () => "",
+        searchParams: tab !== undefined ? { tab } : {},
+        setSearchParams: () => {},
+      };
+    }
+
+    const { unmount } = render(
+      <NavProvider value={navWithTab(undefined)}>
+        <DispatcherProvider dispatcher={dispatcher}>
+          <ExtensionSectionsProvider value={{ SessionNotes }}>
+            <KumikoScreen
+              schema={tabsExtensionSchema}
+              qn="sessions:screen:session-detail"
+              entityId="sess-1"
+            />
+          </ExtensionSectionsProvider>
+        </DispatcherProvider>
+      </NavProvider>,
+    );
+    await waitFor(() => screen.getByTestId("render-edit-form"));
+    expect(screen.queryByTestId("session-notes")).toBeNull();
+    unmount();
+
+    render(
+      <NavProvider value={navWithTab("notes")}>
+        <DispatcherProvider dispatcher={dispatcher}>
+          <ExtensionSectionsProvider value={{ SessionNotes }}>
+            <KumikoScreen
+              schema={tabsExtensionSchema}
+              qn="sessions:screen:session-detail"
+              entityId="sess-1"
+            />
+          </ExtensionSectionsProvider>
+        </DispatcherProvider>
+      </NavProvider>,
+    );
+    await waitFor(() => screen.getByTestId("session-notes"));
+    expect(screen.getByTestId("session-notes").textContent).toBe("user-session:sess-1");
+    expect(screen.queryByTestId("field-userId")).toBeNull();
+  });
+});

package/src/primitives/index.tsx

@@ -105,6 +105,7 @@ import { EmbeddedListInput } from "./embedded-list-input";
 import { FileUploadInput } from "./file-upload";
 import { DefaultLightbox } from "./lightbox";
 import { LocatedTimestampInput } from "./located-timestamp-input";
+import { DefaultMetric } from "./metric";
 import { DefaultModal } from "./modal";
 import { currencyDecimals, formatMoney, MoneyInput } from "./money-input";
 import { DefaultStatusBadge } from "./status-badge";
@@ -1625,6 +1626,7 @@ function DefaultForm({
   testId,
   width,
   stickyActions,
+  headerRegion,
 }: FormProps): ReactNode {
   // Eingebettet (AuthCard etc.): nacktes <form>, gestapelte Felder mit gap —
   // der Container trägt Card/Titel selbst, sonst Card-in-Card.
@@ -1664,6 +1666,9 @@ function DefaultForm({
       className="flex flex-col w-full"
     >
       <FormScreenShell {...(width !== undefined && { maxWidth: width })}>
+        {headerRegion !== undefined && (
+          <div className="flex flex-col gap-6 mb-8">{headerRegion}</div>
+        )}
         <div className={cn(cardSurface(), "overflow-hidden")}>
           {(title !== undefined || subtitle !== undefined) && (
             <div className="px-6 pb-2 pt-5">
@@ -1856,6 +1861,16 @@ function DefaultSection({
 }
 
 function DefaultGrid({ columns, children, testId, maxRows }: GridProps): ReactNode {
+  // "auto": content-sized items in a wrapping row (e.g. a metrics band of
+  // self-sized tiles) instead of N equal-width, container-stretched tracks.
+  // maxRows/scrolling don't apply — the row just wraps.
+  if (columns === "auto") {
+    return (
+      <div data-testid={testId} className="flex flex-wrap gap-4">
+        {children}
+      </div>
+    );
+  }
   // Responsive: Mobile (< sm = 640px) bleibt 1-spaltig, ab sm: greift
   // die Author-deklarierte Spaltenzahl. Inline-style schreibt
   // CSS-Variable; Tailwind-Klasse liest die Variable mit
@@ -2098,4 +2113,5 @@ export const defaultPrimitives: CorePrimitives = {
   WizardStepGroup: DefaultWizardStepGroup,
   Tabs: DefaultTabs,
   StatusBadge: DefaultStatusBadge,
+  Metric: DefaultMetric,
 };

package/src/primitives/metric.tsx

@@ -0,0 +1,17 @@
+import type { MetricProps } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import { MiniStat } from "../widgets/stat";
+
+export function DefaultMetric({ label, value, testId }: MetricProps): ReactNode {
+  return (
+    <MiniStat
+      label={label}
+      value={value}
+      testId={testId}
+      {...(testId !== undefined && {
+        labelTestId: `${testId}-label`,
+        valueTestId: `${testId}-value`,
+      })}
+    />
+  );
+}

package/src/widgets/stat.tsx

@@ -157,12 +157,16 @@ export function MiniStat({
   tone = "default",
   emphasize = false,
   testId,
+  labelTestId,
+  valueTestId,
 }: {
   readonly label: string;
   readonly value: string;
   readonly tone?: StatTone;
   readonly emphasize?: boolean;
   readonly testId?: string;
+  readonly labelTestId?: string;
+  readonly valueTestId?: string;
 }): ReactNode {
   const { Card } = usePrimitives();
   return (
@@ -171,13 +175,16 @@ export function MiniStat({
       className={cn("p-3", emphasize && "ring-1 ring-primary/30")}
       testId={testId}
     >
-      <div className="text-xs text-muted-foreground">{label}</div>
+      <div className="text-xs text-muted-foreground" data-testid={labelTestId}>
+        {label}
+      </div>
       <div
         className={cn(
           "mt-0.5 font-semibold tabular-nums",
           TONE_VALUE[tone],
           emphasize ? "text-lg" : "text-sm",
         )}
+        data-testid={valueTestId}
       >
         {value}
       </div>