@cosmicdrift/kumiko-renderer-web 0.48.1 → 0.51.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer-web",
-  "version": "0.48.1",
+  "version": "0.51.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.45.0",
-    "@cosmicdrift/kumiko-headless": "0.45.0",
-    "@cosmicdrift/kumiko-renderer": "0.45.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.50.0",
+    "@cosmicdrift/kumiko-headless": "0.50.0",
+    "@cosmicdrift/kumiko-renderer": "0.50.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__/app-layout.test.tsx

@@ -0,0 +1,43 @@
+// AppLayout: pinnt den fill-Vertrag — Default ist der klassische
+// min-h-screen-Seitenflow, fill schaltet auf h-screen + innen-scrollendes
+// main (min-h-0). Plus die className/mainClassName-Erweiterungspunkte.
+
+import { describe, expect, test } from "bun:test";
+import { AppLayout } from "../layout/app-layout";
+import { render } from "./test-utils";
+
+function root(container: HTMLElement): HTMLElement {
+  const el = container.querySelector('[data-kumiko-layout="app"]');
+  if (el === null) throw new Error("AppLayout root not found");
+  return el as HTMLElement;
+}
+
+describe("AppLayout fill", () => {
+  test("Default → min-h-screen (Seiten-Scroll), kein fill-Marker", () => {
+    const { container } = render(<AppLayout>x</AppLayout>);
+    const el = root(container);
+    expect(el.className).toContain("min-h-screen");
+    expect(el.getAttribute("data-kumiko-fill")).toBeNull();
+    expect((container.querySelector("main") as HTMLElement).className).not.toContain("min-h-0");
+  });
+
+  test("fill → h-screen + main min-h-0 (Innen-Scroll), fill-Marker gesetzt", () => {
+    const { container } = render(<AppLayout fill>x</AppLayout>);
+    const el = root(container);
+    expect(el.className).not.toContain("min-h-screen");
+    expect(el.className).toContain("h-screen");
+    expect(el.getAttribute("data-kumiko-fill")).toBe("true");
+    expect((container.querySelector("main") as HTMLElement).className).toContain("min-h-0");
+  });
+
+  test("className/mainClassName werden an die Defaults angehängt", () => {
+    const { container } = render(
+      <AppLayout className="bg-gradient-test" mainClassName="main-test">
+        x
+      </AppLayout>,
+    );
+    expect(root(container).className).toContain("bg-gradient-test");
+    expect(root(container).className).toContain("flex");
+    expect((container.querySelector("main") as HTMLElement).className).toContain("main-test");
+  });
+});

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

@@ -179,4 +179,34 @@ describe("NavTree", () => {
     // Items selbst bleibt sichtbar
     expect(screen.getByText("Items")).toBeTruthy();
   });
+
+  test("Nav-Eintrag mit bekanntem icon rendert ein Lucide-Icon, ohne icon den Dot", () => {
+    const schema = {
+      featureName: "showcase",
+      entities: {},
+      screens: [
+        { id: "dash", type: "entityList", entity: "x", columns: [] },
+        { id: "plain", type: "entityList", entity: "x", columns: [] },
+      ],
+      navs: [
+        { id: "dash", label: "Dash", screen: "dash", order: 10, icon: "dashboard" },
+        { id: "plain", label: "Plain", screen: "plain", order: 20 },
+      ],
+    } as FeatureSchema;
+    const { container } = render(<NavTree schema={schema} />);
+    // Flache Navigation ohne Sections → keine Chevrons. Genau EIN svg:
+    // das dashboard-Icon. Das icon-lose Item rendert den Dot (span, kein svg).
+    expect(container.querySelectorAll("svg").length).toBe(1);
+  });
+
+  test("unbekannter icon-Key fällt sauber auf den Dot zurück (kein svg)", () => {
+    const schema = {
+      featureName: "showcase",
+      entities: {},
+      screens: [{ id: "x", type: "entityList", entity: "x", columns: [] }],
+      navs: [{ id: "x", label: "X", screen: "x", order: 10, icon: "does-not-exist" }],
+    } as FeatureSchema;
+    const { container } = render(<NavTree schema={schema} />);
+    expect(container.querySelectorAll("svg").length).toBe(0);
+  });
 });

package/src/app/browser-locale.ts

@@ -63,7 +63,7 @@ export function createBrowserLocaleResolver(
 
   return {
     translate: (key) => key,
-    locale: () => store.getSnapshot(),
+    locale: () => store.getSnapshot(), // @wrapper-known semantic-alias
     timeZone: () => timeZone,
     subscribe: store.subscribe,
     setLocale: (next) => {

package/src/layout/__tests__/settings-hub-visibility.test.ts

@@ -0,0 +1,170 @@
+// End-to-end Settings-Hub visibility on the REAL boot path:
+//   createRegistry → buildAppSchema → buildNavRegistrySliceForApp → resolveNavigation.
+// These are the actual functions the shell runs at boot; no stubs. Proves a
+// config key declared with `mask` surfaces as a role-filtered nav tree that
+// only shows inside its own synthetic "settings" workspace.
+
+import { describe, expect, test } from "bun:test";
+import {
+  access,
+  buildAppSchema,
+  createRegistry,
+  createSystemConfig,
+  createTenantConfig,
+  createUserConfig,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { resolveNavigation } from "@cosmicdrift/kumiko-headless";
+import { qualifyScreenId } from "@cosmicdrift/kumiko-renderer";
+import { buildNavRegistrySliceForApp } from "../nav-tree";
+
+const billing = defineFeature("billing", (r) => {
+  r.config({
+    keys: {
+      stripeKey: createTenantConfig("text", { mask: { title: "billing.stripe-key" } }),
+      // system-scope default write = ["system"] (internal actor) → human-hidden
+      platformFee: createSystemConfig("number", { mask: { title: "billing.platform-fee" } }),
+    },
+  });
+});
+const notify = defineFeature("notify", (r) => {
+  r.config({
+    keys: { digest: createUserConfig("boolean", { mask: { title: "notify.digest" } }) },
+  });
+});
+// A system-scope key that explicitly opts a HUMAN role into write → its
+// settings entry becomes visible to that admin (the opt-in path).
+const ops = defineFeature("ops", (r) => {
+  r.config({
+    keys: {
+      maintenanceMode: createSystemConfig("boolean", {
+        write: access.systemAdmin,
+        mask: { title: "ops.maintenance" },
+      }),
+    },
+  });
+});
+// A real work-workspace, so the app is in workspace (filter) mode.
+const shell = defineFeature("shell", (r) => {
+  r.entity("thing", { fields: { label: { type: "text" } } });
+  r.screen({ id: "home", type: "entityList", entity: "thing", columns: ["label"] });
+  r.nav({ id: "home", label: "Home", screen: "home" });
+  r.workspace({ id: "main", label: "Main", nav: ["shell:nav:home"] });
+});
+
+const app = buildAppSchema(createRegistry([shell, billing, notify, ops]));
+
+function navMembersOf(workspaceId: string): ReadonlySet<string> {
+  const ws = app.workspaces?.find((w) => w.definition.id === workspaceId);
+  if (ws === undefined) throw new Error(`no workspace "${workspaceId}"`);
+  return new Set(ws.navMembers);
+}
+
+function qualifiedNames(tree: ReturnType<typeof resolveNavigation>): string[] {
+  const out: string[] = [];
+  const walk = (nodes: ReturnType<typeof resolveNavigation>): void => {
+    for (const n of nodes) {
+      out.push(n.qualifiedName);
+      walk(n.children);
+    }
+  };
+  walk(tree);
+  return out;
+}
+
+// Mirrors the exact screen lookup KumikoScreen runs (kumiko-screen.tsx:102) —
+// the REAL qualifyScreenId against the FeatureSchema's short screen ids. Proves
+// a nav's screen-QN resolves to a renderable definition, not just that the ref
+// string matches a convention.
+function resolveScreenDef(qn: string) {
+  for (const f of app.features) {
+    const hit = f.screens.find((s) => qualifyScreenId(f.featureName, s.id) === qn);
+    if (hit !== undefined) return hit;
+  }
+  return undefined;
+}
+
+function screenRefsIn(tree: ReturnType<typeof resolveNavigation>): string[] {
+  const out: string[] = [];
+  const walk = (nodes: ReturnType<typeof resolveNavigation>): void => {
+    for (const n of nodes) {
+      if (n.screen !== undefined) out.push(n.screen);
+      walk(n.children);
+    }
+  };
+  walk(tree);
+  return out;
+}
+
+describe("Settings-Hub visibility — full boot pipeline", () => {
+  test("privileged user sees the human-relevant hub; system-internal keys stay hidden", () => {
+    const slice = buildNavRegistrySliceForApp(app, navMembersOf("settings"));
+    const tree = resolveNavigation({
+      source: slice,
+      user: { id: "u-1", roles: ["TenantAdmin", "SystemAdmin"] },
+    });
+    const names = qualifiedNames(tree);
+
+    expect(names).toContain("config:nav:audience-tenant");
+    expect(names).toContain("config:nav:audience-user");
+    // system audience surfaces ONLY because `ops` opted a human (SystemAdmin)
+    // into write; its child ops-system shows, billing's system-internal key
+    // (write ["system"]) stays hidden from the same admin.
+    expect(names).toContain("config:nav:audience-system");
+    expect(names).toContain("config:nav:ops-system");
+    expect(names).not.toContain("config:nav:billing-system");
+
+    // schema-level completeness: the hidden key IS generated (a system actor
+    // could resolve it) — it's gated at resolve-time, not omitted at build-time.
+    expect(navMembersOf("settings").has("config:nav:billing-system")).toBe(true);
+
+    // hierarchy: the billing-tenant screen hangs under the tenant audience
+    const tenantAudience = tree.find((n) => n.qualifiedName === "config:nav:audience-tenant");
+    expect(tenantAudience?.children.map((c) => c.qualifiedName)).toContain(
+      "config:nav:billing-tenant",
+    );
+    expect(tenantAudience?.children[0]?.screen).toBe("config:screen:billing-tenant");
+  });
+
+  test("anonymous user sees only the openToAll (user-scope) audience", () => {
+    const slice = buildNavRegistrySliceForApp(app, navMembersOf("settings"));
+    const tree = resolveNavigation({ source: slice }); // no user
+    const names = qualifiedNames(tree);
+
+    // digest is createUserConfig → write `all` → openToAll → visible to anyone
+    expect(names).toContain("config:nav:audience-user");
+    // admin/system audiences are role-gated → hidden from anonymous
+    expect(names).not.toContain("config:nav:audience-tenant");
+    expect(names).not.toContain("config:nav:audience-system");
+  });
+
+  test("every visible leaf nav resolves to a real configEdit screen (nav → screen → definition)", () => {
+    const slice = buildNavRegistrySliceForApp(app, navMembersOf("settings"));
+    const tree = resolveNavigation({
+      source: slice,
+      user: { id: "u-1", roles: ["TenantAdmin", "SystemAdmin"] },
+    });
+    const refs = screenRefsIn(tree);
+    expect(refs.length).toBeGreaterThan(0); // audiences have no screen; children do
+
+    // the short screen ids in the config FeatureSchema must qualify back to the
+    // exact QN the nav carries — qualifyScreenId is NOT idempotent, so a mismatch
+    // would render "Screen not found" on every settings click.
+    for (const qn of refs) {
+      expect(resolveScreenDef(qn)?.type).toBe("configEdit");
+    }
+    expect(resolveScreenDef("config:screen:billing-tenant")?.type).toBe("configEdit");
+  });
+
+  test("the work workspace does NOT leak the settings hub", () => {
+    const slice = buildNavRegistrySliceForApp(app, navMembersOf("main"));
+    const tree = resolveNavigation({
+      source: slice,
+      user: { id: "u-1", roles: ["TenantAdmin", "SystemAdmin"] },
+    });
+    const names = qualifiedNames(tree);
+
+    expect(names).toContain("shell:nav:home");
+    expect(names.some((n) => n.startsWith("config:nav:"))).toBe(false);
+  });
+});

package/src/layout/app-layout.tsx

@@ -1,4 +1,5 @@
 import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
 
 // Linear-Pattern: Sidebar ist Geschwister von <Topbar+Main>-Spalte,
 // nimmt die volle Höhe. Wenn ein Topbar gesetzt ist, lebt er NUR über
@@ -12,23 +13,50 @@ export type AppLayoutProps = {
   readonly sidebar?: ReactNode;
   readonly children: ReactNode;
   readonly testId?: string;
+  /** Viewport-fit Shell. true → Wurzel = `h-screen` (fixe Viewport-Höhe),
+   *  Sidebar/Topbar bleiben stehen, der Main-Bereich scrollt INNEN
+   *  (`min-h-0` + `overflow-auto`). false (Default) → klassischer
+   *  `min-h-screen`-Flow, die ganze Seite scrollt. Dashboard-artige Apps
+   *  wollen `true`; eine öffentliche, lange Content-Seite eher `false`.
+   *  Clippt nie — der Content scrollt in `main` statt im Body. */
+  readonly fill?: boolean;
+  /** Optionaler Klassen-Append an die Wurzel (eigener Hintergrund etc.).
+   *  Erweitert die Defaults, ersetzt sie nicht (cn-merge). */
+  readonly className?: string;
+  /** Optionaler Klassen-Append an `<main>`. */
+  readonly mainClassName?: string;
 };
 
-export function AppLayout({ topbar, sidebar, children, testId }: AppLayoutProps): ReactNode {
+export function AppLayout({
+  topbar,
+  sidebar,
+  children,
+  testId,
+  fill,
+  className,
+  mainClassName,
+}: AppLayoutProps): ReactNode {
   return (
     <div
       data-testid={testId}
       data-kumiko-layout="app"
-      className="flex min-h-screen flex-row bg-background text-foreground"
+      {...(fill === true && { "data-kumiko-fill": "true" })}
+      className={cn(
+        "flex flex-row bg-background text-foreground",
+        fill === true ? "h-screen" : "min-h-screen",
+        className,
+      )}
     >
       {sidebar}
-      <div className="flex flex-1 min-w-0 flex-col">
+      <div className={cn("flex flex-1 min-w-0 flex-col", fill === true && "min-h-0")}>
         {topbar}
         {/* main hat KEIN Padding — Screens (Form, Liste, Demo-Pages)
              managen ihr Padding selber, damit Action-Bars edge-to-edge
              spannen können ohne Negative-Margin-Tricks die mit
              `position: sticky` kollidieren. */}
-        <main className="flex-1 overflow-auto">{children}</main>
+        <main className={cn("flex-1 overflow-auto", fill === true && "min-h-0", mainClassName)}>
+          {children}
+        </main>
       </div>
     </div>
   );

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

@@ -44,6 +44,10 @@ export type DefaultAppShellProps = {
   /** Footer-Slot unten in der Sidebar — Profile-Row, Help-Link,
    *  Plan-Banner. Klebt am unteren Rand via `mt-auto`. */
   readonly sidebarFooter?: ReactNode;
+  /** Viewport-fit Shell — durchgereicht an AppLayout. true → fixe
+   *  Viewport-Höhe, Content scrollt innen statt der ganzen Seite.
+   *  Default false (klassischer Seiten-Scroll). Siehe AppLayout.fill. */
+  readonly fill?: boolean;
   /** Screen-Content der in `main` gerendert wird. */
   readonly children: ReactNode;
 };
@@ -54,10 +58,12 @@ export function DefaultAppShell({
   user,
   sidebarActions,
   sidebarFooter,
+  fill,
   children,
 }: DefaultAppShellProps): ReactNode {
   return (
     <AppLayout
+      {...(fill !== undefined && { fill })}
       sidebar={
         <Sidebar
           header={brand}

package/src/layout/nav-tree.tsx

@@ -16,11 +16,72 @@ import type { NavNode, NavRegistrySlice } from "@cosmicdrift/kumiko-headless";
 import { resolveNavigation } from "@cosmicdrift/kumiko-headless";
 import type { AppSchema, FeatureSchema } from "@cosmicdrift/kumiko-renderer";
 import { lastSegment, toAppSchema, useNav, useTranslation } from "@cosmicdrift/kumiko-renderer";
-import { ChevronDown, ChevronRight } from "lucide-react";
+import {
+  BarChart3,
+  Bell,
+  Calculator,
+  CalendarDays,
+  ChevronDown,
+  ChevronRight,
+  Coins,
+  CreditCard,
+  FileText,
+  Folder,
+  Gauge,
+  Home,
+  LayoutDashboard,
+  LineChart,
+  List,
+  PiggyBank,
+  Receipt,
+  Search,
+  Settings,
+  Shield,
+  Sparkles,
+  Table,
+  TrendingUp,
+  User,
+  Users,
+  Wallet,
+  Wand2,
+} from "lucide-react";
 import { type ReactNode, useCallback, useMemo, useState } from "react";
 import { KumikoLink } from "../app/nav";
 import { cn } from "../lib/cn";
 
+// Nav-Icon-Registry: ein Nav-Eintrag setzt `icon: "<key>"` (im r.nav-Decl),
+// der Renderer mappt den symbolischen Key auf ein lucide-Component. Unknown
+// Keys → kein Icon (sauberer Fallback auf den Dot, kein Boot-Fail). Spiegelt
+// das NODE_ICONS-Muster vom Visual-Tree. App-Authors referenzieren nur diese
+// Keys; Erweiterung = neuer Eintrag hier (eine Quelle, alle Apps).
+const NAV_ICONS: Readonly<Record<string, typeof Folder>> = {
+  dashboard: LayoutDashboard,
+  gauge: Gauge,
+  list: List,
+  table: Table,
+  calculator: Calculator,
+  wallet: Wallet,
+  coins: Coins,
+  "credit-card": CreditCard,
+  "piggy-bank": PiggyBank,
+  receipt: Receipt,
+  chart: LineChart,
+  "bar-chart": BarChart3,
+  trending: TrendingUp,
+  sparkles: Sparkles,
+  wand: Wand2,
+  calendar: CalendarDays,
+  file: FileText,
+  folder: Folder,
+  home: Home,
+  bell: Bell,
+  shield: Shield,
+  settings: Settings,
+  users: Users,
+  user: User,
+  search: Search,
+};
+
 export type NavTreeProps = {
   // Akzeptiert beide Shapes — AppSchema (multi-feature) oder
   // FeatureSchema (legacy single-feature). toAppSchema normalisiert
@@ -82,6 +143,7 @@ function NavNodeItem({ node, depth, collapsed, onToggle }: NavNodeItemProps): Re
   const t = useTranslation();
   const active = node.screen !== undefined && nav.route?.screenId === lastSegment(node.screen);
 
+  const NavIcon = node.icon !== undefined ? NAV_ICONS[node.icon] : undefined;
   const hasChildren = node.children.length > 0;
   const isCollapsed = collapsed.has(node.qualifiedName);
   const indent = { paddingLeft: `${0.5 + depth * 1}rem` };
@@ -156,13 +218,23 @@ function NavNodeItem({ node, depth, collapsed, onToggle }: NavNodeItemProps): Re
             )}
             {...(active && { "aria-current": "page" })}
           >
-            <span
-              aria-hidden="true"
-              className={cn(
-                "inline-block size-1.5 rounded-full",
-                active ? "bg-accent-foreground" : "bg-muted-foreground/40",
-              )}
-            />
+            {NavIcon !== undefined ? (
+              <NavIcon
+                aria-hidden="true"
+                className={cn(
+                  "size-4 shrink-0",
+                  active ? "text-foreground" : "text-muted-foreground",
+                )}
+              />
+            ) : (
+              <span
+                aria-hidden="true"
+                className={cn(
+                  "inline-block size-1.5 rounded-full",
+                  active ? "bg-accent-foreground" : "bg-muted-foreground/40",
+                )}
+              />
+            )}
             <span className="truncate">{displayLabel}</span>
           </KumikoLink>
           {chevron !== null && <div className="pr-2">{chevron}</div>}

package/src/styles.css

@@ -19,12 +19,17 @@
    Defaults bleiben rdp's eigenes Stylesheet. */
 @import "react-day-picker/style.css";
 
-/* Tailwind v4 scannt per default vom Import-Ort aus; da das CSS
-   aus einem temp-dir kompiliert wird, findet es sonst keine
-   Source-Dateien. Explizite @source-Direktiven decken alle
-   Workspace-Sources ab — der CLI scannt dann unsere Primitives,
-   Layout-Components UND die Sample-App. */
-@source "../../renderer-web/src/**/*.{ts,tsx}";
+/* Tailwind v4 scannt per default vom Import-Ort aus; da das CSS aus
+   einem temp-dir kompiliert wird, findet es sonst keine Source-Dateien.
+   Die erste Zeile ist self-relativ (`./` = dieses src/) und MUSS es
+   bleiben: das Paket shippt `src`, also löst sie in jedem Install-Layout
+   auf — Workspace UND Standalone-Consumer (node_modules). Ein monorepo-
+   relativer Pfad fand im Standalone-Build die eigenen Shell-Klassen
+   nicht → unstyled prod, 15KB statt 48KB (#359). Die restlichen Zeilen
+   sind Monorepo-Build-Quellen (renderer hat keine eigenen Klassen,
+   samples nur für den In-Monorepo-Sample-Build) — im Consumer matchen
+   sie nichts und sind dort ein harmloser No-op. */
+@source "./**/*.{ts,tsx}";
 @source "../../renderer/src/**/*.{ts,tsx}";
 @source "../../../samples/**/src/**/*.{ts,tsx}";
 

package/src/tokens.ts

@@ -35,10 +35,12 @@ function readCurrentMode(): ThemeMode {
   return document.documentElement.classList.contains("dark") ? "dark" : "light";
 }
 
+// @wrapper-known semantic-alias
 function notifyThemeChange(): void {
   themeTick.setState((t) => t + 1);
 }
 
+// @wrapper-known semantic-alias
 function persistMode(mode: ThemeMode): void {
   try {
     window.localStorage.setItem(THEME_STORAGE_KEY, mode);