@cosmicdrift/kumiko-renderer-web 0.251.0 → 0.252.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer-web",
-  "version": "0.251.0",
+  "version": "0.252.1",
   "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.251.0",
-    "@cosmicdrift/kumiko-headless": "0.251.0",
-    "@cosmicdrift/kumiko-renderer": "0.251.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.252.1",
+    "@cosmicdrift/kumiko-headless": "0.252.1",
+    "@cosmicdrift/kumiko-renderer": "0.252.1",
     "@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.251.0"
+    "@cosmicdrift/kumiko-locale-de": "0.252.1"
   },
   "repository": {
     "type": "git",

package/src/__tests__/dashboard-screen.test.tsx

@@ -90,6 +90,76 @@ describe("KumikoScreen dashboard", () => {
   });
 });
 
+// screen.description exists on DashboardScreenDefinition (types/src/
+// screen.ts:713) but WebDashboardBody never read it — the panels grid
+// rendered with no room for it at all.
+describe("KumikoScreen dashboard — screen.description", () => {
+  test("a plain-text description renders above the panels", async () => {
+    const screenWithDescription: DashboardScreenDefinition = {
+      ...dashboardScreen,
+      description: "Live health signals across every monitored service.",
+    };
+    const schemaWithDescription: FeatureSchema = {
+      featureName: "status",
+      entities: {},
+      screens: [screenWithDescription],
+    };
+    render(
+      <DispatcherProvider dispatcher={makeDispatcher()}>
+        <DashboardBodyProvider value={WebDashboardBody}>
+          <KumikoScreen schema={schemaWithDescription} qn="status:screen:overview" />
+        </DashboardBodyProvider>
+      </DispatcherProvider>,
+    );
+
+    expect(screen.getByTestId("dashboard-overview-description").textContent).toBe(
+      "Live health signals across every monitored service.",
+    );
+  });
+
+  test("a description that is a known i18n key renders translated, not as the raw key", async () => {
+    const screenWithDescription: DashboardScreenDefinition = {
+      ...dashboardScreen,
+      description: "status:dashboard:explainer",
+    };
+    const schemaWithDescription: FeatureSchema = {
+      featureName: "status",
+      entities: {},
+      screens: [screenWithDescription],
+    };
+    render(
+      <DispatcherProvider dispatcher={makeDispatcher()}>
+        <DashboardBodyProvider value={WebDashboardBody}>
+          <KumikoScreen
+            schema={schemaWithDescription}
+            qn="status:screen:overview"
+            translate={(key) =>
+              key === "status:dashboard:explainer" ? "Refreshes every 60 seconds." : key
+            }
+          />
+        </DashboardBodyProvider>
+      </DispatcherProvider>,
+    );
+
+    const description = screen.getByTestId("dashboard-overview-description");
+    expect(description.textContent).toBe("Refreshes every 60 seconds.");
+    expect(description.textContent).not.toBe("status:dashboard:explainer");
+  });
+
+  test("a screen without description renders no description block", async () => {
+    render(
+      <DispatcherProvider dispatcher={makeDispatcher()}>
+        <DashboardBodyProvider value={WebDashboardBody}>
+          <KumikoScreen schema={schema} qn="status:screen:overview" />
+        </DashboardBodyProvider>
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() => expect(screen.getByTestId("dashboard-overview")).toBeTruthy());
+    expect(screen.queryByTestId("dashboard-overview-description")).toBeNull();
+  });
+});
+
 const richScreen: DashboardScreenDefinition = {
   id: "rich",
   type: "dashboard",

package/src/__tests__/render-edit.test.tsx

@@ -202,6 +202,45 @@ describe("RenderEdit", () => {
     expect(fieldEl.querySelector("input")?.className).toContain("pl-8");
   });
 
+  // Fall 2: tabs layout sets hideSectionTitles (kumiko-screen.tsx's
+  // ProjectionDetailBody, the only real caller) to blank out each section's
+  // OWN title — the active tab already names it. That gate used to also
+  // swallow the screen-level subtitle (screen.description), which has
+  // nothing to do with section titles and must survive tabs mode.
+  test("tabs layout (hideSectionTitles) keeps the section title hidden but still shows the screen's own subtitle", () => {
+    const entity = {
+      fields: { email: { type: "text", required: true } },
+    } as unknown as EntityDefinition;
+    const screenDef: EntityEditScreenDefinition = {
+      id: "orders:screen:order-detail",
+      type: "entityEdit",
+      entity: "order",
+      description: "Everything about this order in one place.",
+      layout: {
+        mode: "tabs",
+        sections: [{ id: "contact", title: "Contact", fields: [{ field: "email" }] }],
+      },
+    };
+    render(
+      <DispatcherProvider dispatcher={makeDispatcher()}>
+        <RenderEdit
+          screen={screenDef}
+          entity={entity}
+          featureName="orders"
+          initial={{ email: "" } as never}
+          writeCommand="order:create"
+          hideSectionTitles
+        />
+      </DispatcherProvider>,
+    );
+
+    expect(screen.queryByTestId("render-edit-form-title")).toBeNull();
+    expect(screen.queryByTestId("section-Contact-title")).toBeNull();
+    expect(screen.getByTestId("render-edit-form-subtitle").textContent).toBe(
+      "Everything about this order in one place.",
+    );
+  });
+
   // End-to-end-Routing: ein `type:"locatedTimestamp"`-Entity-Feld muss durch
   // computeEditViewModel → render-field → DefaultInput auf den Located-Picker
   // laufen (Datum + Uhrzeit + Zone), NICHT auf den Klartext-Fallthrough. Vor

package/src/__tests__/secrets-edit-body.test.tsx

@@ -0,0 +1,84 @@
+// SecretsEditScreenDefinition.description exists (types/src/screen.ts:1205)
+// to explain what the secrets on this screen are for, same doc-promise as
+// every other description slot — but SecretsEditBody built its own <Form>
+// without ever reading screen.description. Fixed by wiring it into the
+// Form's established subtitle slot (same slot render-edit.tsx and
+// write-form-section.tsx use), rendered through DefaultForm — real
+// renderer-web primitives, not a stub, so this proves the actual DOM output.
+
+import { describe, expect, test } from "bun:test";
+import type { SecretsEditScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
+import { DispatcherProvider } from "@cosmicdrift/kumiko-renderer";
+import { SecretsEditBody } from "../../../renderer/src/app/secrets-edit-body";
+import { createMockDispatcher, render, screen, waitFor } from "./test-utils";
+
+function makeDispatcher(): Dispatcher {
+  return createMockDispatcher({
+    query: (async () => ({ isSuccess: true, data: [] })) as Dispatcher["query"],
+  });
+}
+
+function baseScreen(): SecretsEditScreenDefinition {
+  return {
+    id: "integrations:screen:secrets",
+    type: "secretsEdit",
+    secretKeys: { apiKey: "integrations:secret:api-key" },
+    fieldLabels: { apiKey: "API key" },
+    sections: [{ fields: ["apiKey"] }],
+  };
+}
+
+describe("SecretsEditBody — screen.description as form subtitle", () => {
+  test("a plain-text description renders as the form's subtitle", async () => {
+    const screenDef: SecretsEditScreenDefinition = {
+      ...baseScreen(),
+      description: "These credentials are shared across every integration on this workspace.",
+    };
+    render(
+      <DispatcherProvider dispatcher={makeDispatcher()}>
+        <SecretsEditBody screen={screenDef} />
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() =>
+      expect(screen.getByTestId("secrets-edit-form-subtitle").textContent).toBe(
+        "These credentials are shared across every integration on this workspace.",
+      ),
+    );
+  });
+
+  test("a description that is a known i18n key renders translated, not as the raw key", async () => {
+    const screenDef: SecretsEditScreenDefinition = {
+      ...baseScreen(),
+      description: "integrations:secrets.explainer",
+    };
+    render(
+      <DispatcherProvider dispatcher={makeDispatcher()}>
+        <SecretsEditBody
+          screen={screenDef}
+          translate={(key) =>
+            key === "integrations:secrets.explainer" ? "Rotate these keys every 90 days." : key
+          }
+        />
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() => {
+      const subtitle = screen.getByTestId("secrets-edit-form-subtitle");
+      expect(subtitle.textContent).toBe("Rotate these keys every 90 days.");
+      expect(subtitle.textContent).not.toBe("integrations:secrets.explainer");
+    });
+  });
+
+  test("a screen without description renders no subtitle at all", async () => {
+    render(
+      <DispatcherProvider dispatcher={makeDispatcher()}>
+        <SecretsEditBody screen={baseScreen()} />
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() => expect(screen.getByTestId("secrets-edit-form")).toBeTruthy());
+    expect(screen.queryByTestId("secrets-edit-form-subtitle")).toBeNull();
+  });
+});

package/src/app/dashboard-body.tsx

@@ -437,9 +437,15 @@ function PanelBody({
 export function WebDashboardBody({ screen, translate }: DashboardBodyProps): ReactNode {
   const t = useTranslation();
   const effectiveTranslate = translate ?? t;
+  const { Text } = usePrimitives();
   const { params: filterParams, picker } = useFilterParams(screen);
   return (
     <PageSection className="flex flex-col gap-4" testId={`dashboard-${screen.id}`}>
+      {screen.description !== undefined && (
+        <Text variant="muted" testId={`dashboard-${screen.id}-description`}>
+          {effectiveTranslate(screen.description)}
+        </Text>
+      )}
       {picker}
       <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-4">
         {screen.panels.map((panel) => {