@cosmicdrift/kumiko-renderer-web 0.68.0 → 0.70.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer-web",
-  "version": "0.68.0",
+  "version": "0.70.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.68.0",
-    "@cosmicdrift/kumiko-headless": "0.68.0",
-    "@cosmicdrift/kumiko-renderer": "0.68.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.70.0",
+    "@cosmicdrift/kumiko-headless": "0.70.0",
+    "@cosmicdrift/kumiko-renderer": "0.70.0",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-label": "^2.1.8",

package/src/__tests__/default-app-shell.test.tsx

@@ -57,3 +57,30 @@ describe("DefaultAppShell user-prop forwarding", () => {
     expect(screen.getByText("Sysadmin")).toBeTruthy();
   });
 });
+
+describe("DefaultAppShell headerActions-Slot (Topbar rechts)", () => {
+  test("headerActions rendern rechtsbündig im Topbar-Header", () => {
+    render(
+      <DefaultAppShell
+        brand={<span>Brand</span>}
+        schema={makeSchema()}
+        headerActions={<button type="button">Theme</button>}
+      >
+        <div>content</div>
+      </DefaultAppShell>,
+    );
+    const slot = document.querySelector("[data-kumiko-layout='header-actions']");
+    expect(slot).toBeTruthy();
+    expect(slot?.className).toContain("ml-auto");
+    expect(slot?.textContent).toBe("Theme");
+  });
+
+  test("ohne headerActions → kein Slot (keine leere Zelle)", () => {
+    render(
+      <DefaultAppShell brand={<span>Brand</span>} schema={makeSchema()}>
+        <div>content</div>
+      </DefaultAppShell>,
+    );
+    expect(document.querySelector("[data-kumiko-layout='header-actions']")).toBeNull();
+  });
+});

package/src/__tests__/form-action-bar.test.tsx

@@ -95,6 +95,54 @@ describe("Form = eine Card, Sections als innere Abschnitte", () => {
   });
 });
 
+describe("DefaultSection Card-Standard (subtitle + actions-Footer)", () => {
+  test("standalone: subtitle rendert muted, KEIN Divider unterm Titel", () => {
+    render(
+      <Section testId="sc" title="Ergebnis" subtitle="Kontext-Zeile">
+        <div>x</div>
+      </Section>,
+    );
+    expect(screen.getByTestId("sc-subtitle").textContent).toBe("Kontext-Zeile");
+    expect(screen.getByTestId("sc-subtitle").className).toContain("text-muted-foreground");
+    // border-b-Header (alt) ist weg — Titel fließt in den Body (shadcn-Muster).
+    expect(screen.getByTestId("sc").querySelector(".border-b")).toBeNull();
+  });
+
+  test("standalone: actions = abgehobene Footer-Row (border-t)", () => {
+    render(
+      <Section testId="sc" title="Ergebnis" actions={<Button>Übernehmen</Button>}>
+        <div>x</div>
+      </Section>,
+    );
+    const actions = screen.getByTestId("sc-actions");
+    expect(actions.className).toContain("border-t");
+    expect(actions.className).toContain("justify-end");
+    expect(actions.textContent).toContain("Übernehmen");
+  });
+
+  test("title-only standalone (Bestands-Consumer) hat keinen Divider mehr", () => {
+    render(
+      <Section testId="legacy" title="Stammdaten">
+        <div>x</div>
+      </Section>,
+    );
+    expect(screen.getByTestId("legacy").querySelector(".border-b")).toBeNull();
+  });
+
+  test("im Form: actions sind rechtsbündig OHNE border-t (das Form trägt den Footer)", () => {
+    render(
+      <Form onSubmit={() => {}} testId="f">
+        <Section testId="inner" actions={<Button>X</Button>}>
+          <div>x</div>
+        </Section>
+      </Form>,
+    );
+    const actions = screen.getByTestId("inner-actions");
+    expect(actions.className).toContain("justify-end");
+    expect(actions.className).not.toContain("border-t");
+  });
+});
+
 const orderEntity = {
   fields: { title: { type: "text", required: true } },
 } as unknown as EntityDefinition; // @cast-boundary test-fixture

package/src/__tests__/nav-tree.test.tsx

@@ -236,6 +236,51 @@ describe("NavTree", () => {
   });
 });
 
+describe("NavTree navBadges (Runtime-Badge-Slot)", () => {
+  // Tier-Badge & Co: die App liefert per bare nav-id einen ReactNode (Wert
+  // UND Farbe). Gekeyt auf lastSegment(qualifiedName) → die App schreibt
+  // "tarif", nicht "showcase:nav:tarif".
+  function flatSchema(): FeatureSchema {
+    return {
+      featureName: "showcase",
+      entities: {},
+      screens: [
+        { id: "tarif", type: "entityList", entity: "x", columns: [] },
+        { id: "plain", type: "entityList", entity: "x", columns: [] },
+      ],
+      navs: [
+        { id: "tarif", label: "Tarif & Limits", screen: "tarif", order: 10 },
+        { id: "plain", label: "Plain", screen: "plain", order: 20 },
+      ],
+    } as FeatureSchema;
+  }
+
+  test("Badge gekeyt auf bare nav-id sitzt im passenden Item, nicht in anderen", () => {
+    render(<NavTree schema={flatSchema()} navBadges={new Map([["tarif", <span>Pro</span>]])} />);
+    const badge = screen.getByText("Pro");
+    expect(screen.getByText("Tarif & Limits").closest("li")?.textContent).toContain("Pro");
+    expect(screen.getByText("Plain").closest("li")?.textContent).not.toContain("Pro");
+    // Slot-Wrapper schiebt rechts (ml-auto), Badge selbst shrinkt nicht weg.
+    expect(badge.parentElement?.className).toContain("ml-auto");
+  });
+
+  test("ohne navBadges → kein Badge-Slot", () => {
+    render(<NavTree schema={flatSchema()} />);
+    expect(screen.queryByText("Pro")).toBeNull();
+  });
+
+  test("Key ohne passendes Item → nichts (silent), übrige Items rendern normal", () => {
+    render(
+      <NavTree
+        schema={flatSchema()}
+        navBadges={new Map([["does-not-exist", <span>Ghost</span>]])}
+      />,
+    );
+    expect(screen.queryByText("Ghost")).toBeNull();
+    expect(screen.getByText("Tarif & Limits")).toBeTruthy();
+  });
+});
+
 // ── Visual-Tree-Merge: dynamische Knoten in der EINEN Nav ──────────────
 //
 // Beweist die vier Caps die NavTree aus dem alten VisualTree übernimmt:

package/src/layout/default-app-shell.tsx

@@ -8,6 +8,8 @@
 //   2. sidebarActions — Icon-Row (Search/Theme/Tenant-Switch)
 //   3. NavTree        — automatisch aus dem Schema
 //   4. sidebarFooter  — Bottom-Slot für Profile/Help/Plan-Banner
+// Topbar-Slot:
+//   headerActions     — rechtsbündig neben dem Breadcrumb (ThemeToggle etc.)
 //
 // Apps die feingranulare Kontrolle wollen, gehen direkt auf die ui/-Teile.
 // Wer ein Topbar mit Workspace-Switcher braucht, nutzt <WorkspaceShell>.
@@ -53,6 +55,14 @@ export type DefaultAppShellProps = {
   /** Icon-Row zwischen Brand und NavTree — typisch Search-Trigger,
    *  ThemeToggle, TenantSwitcher. */
   readonly sidebarActions?: ReactNode;
+  /** Runtime-Badges pro Nav-Item (bare nav-id → ReactNode), an NavTree
+   *  durchgereicht. Für Tier-/Status-Badges, die die App pro User liefert
+   *  (Wert + Farbe), statt sie ins statische Schema zu backen. */
+  readonly navBadges?: ReadonlyMap<string, ReactNode>;
+  /** Rechtsbündiger Slot in der Topbar (neben dem Breadcrumb) — für
+   *  ThemeToggle, globale Actions o.ä. Spart die eigene sidebarActions-
+   *  Zeile in der Sidebar. */
+  readonly headerActions?: ReactNode;
   /** Footer-Slot unten in der Sidebar — Profile-Row, Help-Link,
    *  Plan-Banner. */
   readonly sidebarFooter?: ReactNode;
@@ -68,6 +78,8 @@ export function DefaultAppShell({
   schema,
   user,
   sidebarActions,
+  headerActions,
+  navBadges,
   sidebarFooter,
   fill,
   children,
@@ -87,7 +99,11 @@ export function DefaultAppShell({
           </SidebarGroup>
         )}
         <SidebarContent data-kumiko-layout="sidebar-nav">
-          <NavTree schema={schema} {...(user !== undefined && { user })} />
+          <NavTree
+            schema={schema}
+            {...(user !== undefined && { user })}
+            {...(navBadges !== undefined && { navBadges })}
+          />
         </SidebarContent>
         {sidebarFooter !== undefined && (
           <SidebarFooter data-kumiko-layout="sidebar-footer">{sidebarFooter}</SidebarFooter>
@@ -95,7 +111,11 @@ export function DefaultAppShell({
         <SidebarRail />
       </Sidebar>
       <SidebarInset className={fill === true ? "min-h-0" : undefined}>
-        <ShellHeader schema={schema} {...(user !== undefined && { user })} />
+        <ShellHeader
+          schema={schema}
+          {...(user !== undefined && { user })}
+          {...(headerActions !== undefined && { headerActions })}
+        />
         <main className={fill === true ? "min-h-0 flex-1 overflow-auto" : "flex-1 overflow-auto"}>
           {children}
         </main>
@@ -110,9 +130,11 @@ export function DefaultAppShell({
 function ShellHeader({
   schema,
   user,
+  headerActions,
 }: {
   readonly schema: AppSchema | FeatureSchema;
   readonly user?: DefaultAppShellUser;
+  readonly headerActions?: ReactNode;
 }): ReactNode {
   const nav = useNav();
   const t = useTranslation();
@@ -139,6 +161,11 @@ function ShellHeader({
           </Breadcrumb>
         )}
       </div>
+      {headerActions !== undefined && (
+        <div data-kumiko-layout="header-actions" className="ml-auto flex items-center gap-2 px-4">
+          {headerActions}
+        </div>
+      )}
     </header>
   );
 }

package/src/layout/nav-tree.tsx

@@ -55,7 +55,15 @@ import {
   Wallet,
   Wand2,
 } from "lucide-react";
-import { type ReactNode, useCallback, useEffect, useMemo, useState } from "react";
+import {
+  createContext,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
 import { KumikoLink } from "../app/nav";
 import { useNavEntities, useNavProviders } from "../app/nav-providers-context";
 import { cn } from "../lib/cn";
@@ -121,9 +129,23 @@ export type NavTreeProps = {
   // workspace's `navMembers` list. Undefined = no filter (legacy / non-
   // workspace apps render every nav).
   readonly allowedNavQns?: ReadonlySet<string>;
+  // Runtime-Badges pro Nav-Item, gekeyt auf die BARE nav-id (lastSegment der
+  // qualifiedName, also `"tarif"` nicht `"app:nav:tarif"`). Wert ist frei —
+  // die App liefert Text UND Farbe (`<Badge className="bg-amber-…">Pro</Badge>`).
+  // Für dynamische Zustände (Tier-Badge), die nicht ins statische Schema gehören.
+  readonly navBadges?: ReadonlyMap<string, ReactNode>;
 };
 
-export function NavTree({ schema, user, testId, allowedNavQns }: NavTreeProps): ReactNode {
+const EMPTY_BADGES: ReadonlyMap<string, ReactNode> = new Map();
+const NavBadgesContext = createContext<ReadonlyMap<string, ReactNode>>(EMPTY_BADGES);
+
+export function NavTree({
+  schema,
+  user,
+  testId,
+  allowedNavQns,
+  navBadges,
+}: NavTreeProps): ReactNode {
   const app = useMemo(() => toAppSchema(schema), [schema]);
   const tree = useMemo(() => {
     const source = buildNavRegistrySliceForApp(app, allowedNavQns);
@@ -144,25 +166,39 @@ export function NavTree({ schema, user, testId, allowedNavQns }: NavTreeProps):
   }, []);
 
   return (
-    <div data-testid={testId} data-kumiko-layout="nav-tree" className="flex w-full flex-col">
-      {tree.map((node) =>
-        isPureSection(node) ? (
-          <NavSection
-            key={node.qualifiedName}
-            node={node}
-            collapsed={collapsed}
-            onToggle={onToggle}
-          />
-        ) : (
-          <SidebarMenu key={node.qualifiedName} className="px-2 py-1">
-            <NavMenuNode node={node} collapsed={collapsed} onToggle={onToggle} />
-          </SidebarMenu>
-        ),
-      )}
-    </div>
+    <NavBadgesContext.Provider value={navBadges ?? EMPTY_BADGES}>
+      <div data-testid={testId} data-kumiko-layout="nav-tree" className="flex w-full flex-col">
+        {tree.map((node) =>
+          isPureSection(node) ? (
+            <NavSection
+              key={node.qualifiedName}
+              node={node}
+              collapsed={collapsed}
+              onToggle={onToggle}
+            />
+          ) : (
+            <SidebarMenu key={node.qualifiedName} className="px-2 py-1">
+              <NavMenuNode node={node} collapsed={collapsed} onToggle={onToggle} />
+            </SidebarMenu>
+          ),
+        )}
+      </div>
+    </NavBadgesContext.Provider>
   );
 }
 
+// Runtime-Badge-Slot rechts am Label, gekeyt auf die bare nav-id. Kein
+// Eintrag → nichts (silent, kein Layout-Shift). shrink-0 + die ml-auto
+// schiebt ihn ans rechte Ende; das truncate-Label gibt nach.
+// ponytail: nur an screen/target-Leaves verdrahtet, nicht an Container-
+// Knoten (die tragen den ml-auto-Chevron) — Tier-Badge ist ein Leaf.
+function NavBadge({ node }: { readonly node: NavNode }): ReactNode {
+  const badges = useContext(NavBadgesContext);
+  const badge = badges.get(lastSegment(node.qualifiedName));
+  if (badge === undefined) return null;
+  return <span className="ml-auto shrink-0">{badge}</span>;
+}
+
 // Pure section = ein Gruppen-Header ohne eigenen Screen, der nur seine
 // children gruppiert. Auf Top-Level wird daraus eine SidebarGroup mit
 // togglebarem GroupLabel; ein Node mit Screen (auch wenn er children hat)
@@ -502,7 +538,8 @@ function NavMenuNode({ node, collapsed, onToggle }: NavSubProps): ReactNode {
             {...(s.active && { "aria-current": "page" })}
           >
             <NavLeadingIcon node={node} active={s.active} />
-            <span className="truncate">{s.displayLabel}</span>
+            <span className="min-w-0 truncate">{s.displayLabel}</span>
+            <NavBadge node={node} />
           </KumikoLink>
         </SidebarMenuButton>
         <NodeActions node={node} />
@@ -522,7 +559,8 @@ function NavMenuNode({ node, collapsed, onToggle }: NavSubProps): ReactNode {
           onClick={() => dispatch(target)}
         >
           <NavLeadingIcon node={node} active={s.active} />
-          <span className="truncate">{s.displayLabel}</span>
+          <span className="min-w-0 truncate">{s.displayLabel}</span>
+          <NavBadge node={node} />
         </SidebarMenuButton>
         <NodeActions node={node} />
         {chevron}
@@ -603,7 +641,8 @@ function NavSubNode({ node, collapsed, onToggle }: NavSubProps): ReactNode {
             {...(s.active && { "aria-current": "page" })}
           >
             <NavLeadingIcon node={node} active={s.active} />
-            <span className="truncate">{s.displayLabel}</span>
+            <span className="min-w-0 truncate">{s.displayLabel}</span>
+            <NavBadge node={node} />
           </KumikoLink>
         </SidebarMenuSubButton>
         <NodeActions node={node} />
@@ -620,7 +659,8 @@ function NavSubNode({ node, collapsed, onToggle }: NavSubProps): ReactNode {
         <SidebarMenuSubButton asChild isActive={s.active}>
           <button type="button" onClick={() => dispatch(target)}>
             <NavLeadingIcon node={node} active={s.active} />
-            <span className="truncate">{s.displayLabel}</span>
+            <span className="min-w-0 truncate">{s.displayLabel}</span>
+            <NavBadge node={node} />
           </button>
         </SidebarMenuSubButton>
         <NodeActions node={node} />

package/src/primitives/index.tsx

@@ -57,7 +57,7 @@ import {
 import { cn } from "../lib/cn";
 import { Badge } from "../ui/badge";
 import { Button as UiButton } from "../ui/button";
-import { Card, CardContent, CardHeader } from "../ui/card";
+import { Card, CardContent } from "../ui/card";
 import { Checkbox } from "../ui/checkbox";
 import { Input as UiInput } from "../ui/input";
 import { Label as UiLabel } from "../ui/label";
@@ -1393,34 +1393,70 @@ function DefaultForm({
   );
 }
 
-function DefaultSection({ title, children, testId }: SectionProps): ReactNode {
+function DefaultSection({ title, subtitle, children, actions, testId }: SectionProps): ReactNode {
   const insideForm = useContext(InsideFormContext);
 
+  // h3 statt CardTitle (= div): erhält die Heading-Semantik für
+  // Screenreader-Navigation. Subtitle fließt darunter (kein Divider —
+  // shadcn CardTitle+CardDescription-Muster).
+  const header =
+    title !== undefined || subtitle !== undefined ? (
+      <div className="flex flex-col gap-1">
+        {title !== undefined && (
+          <h3
+            data-testid={testId !== undefined ? `${testId}-title` : undefined}
+            className="text-base font-semibold leading-none tracking-tight"
+          >
+            {title}
+          </h3>
+        )}
+        {subtitle !== undefined && (
+          <p
+            data-testid={testId !== undefined ? `${testId}-subtitle` : undefined}
+            className="text-sm text-muted-foreground"
+          >
+            {subtitle}
+          </p>
+        )}
+      </div>
+    ) : null;
+
   // Innerhalb eines Forms: divider-loser Abschnitt OHNE eigene Card-Fläche.
-  // Die Trennlinien ZWISCHEN Sections macht der divide-y-Wrapper im Form —
-  // keine Linie unter dem Titel, keine vor dem Footer.
+  // Die Trennlinien ZWISCHEN Sections macht der divide-y-Wrapper im Form.
+  // actions hier = rechtsbündige Reihe (das Form trägt den eigenen Footer).
   if (insideForm) {
     return (
       <section data-testid={testId} className="flex flex-col gap-4 px-6 py-6">
-        {title !== undefined && (
-          <h3 className="text-base font-semibold leading-none tracking-tight">{title}</h3>
-        )}
+        {header}
         {children}
+        {actions !== undefined && (
+          <div
+            data-testid={testId !== undefined ? `${testId}-actions` : undefined}
+            className="flex items-center justify-end gap-2"
+          >
+            {actions}
+          </div>
+        )}
       </section>
     );
   }
 
-  // Standalone: eigene Card (abgesetzter border-b-Header + gap-4-Body).
+  // Standalone: eigene Card, Header fließt in den Body (kein Divider).
+  // actions = abgehobene Footer-Row (border-t bg-muted/30, wie DefaultForm).
   return (
-    <Card data-testid={testId} className="gap-0 rounded-lg py-0">
-      {title !== undefined && (
-        <CardHeader className="border-b px-6 py-4">
-          {/* h3 statt CardTitle (= div): erhält die Heading-Semantik für
-              Screenreader-Navigation. Klassen = CardTitle-Default. */}
-          <h3 className="text-base font-semibold leading-none tracking-tight">{title}</h3>
-        </CardHeader>
+    <Card data-testid={testId} className="gap-0 overflow-hidden rounded-lg py-0">
+      <CardContent className="flex flex-col gap-4 px-6 py-6">
+        {header}
+        {children}
+      </CardContent>
+      {actions !== undefined && (
+        <div
+          data-testid={testId !== undefined ? `${testId}-actions` : undefined}
+          className="flex items-center justify-end gap-2 border-t bg-muted/30 px-6 py-4"
+        >
+          {actions}
+        </div>
       )}
-      <CardContent className="flex flex-col gap-4 px-6 py-6">{children}</CardContent>
     </Card>
   );
 }