@cosmicdrift/kumiko-renderer-web 0.1.0

package/src/layout/workspace-shell.tsx

@@ -0,0 +1,282 @@
+// WorkspaceShell — App-shell for multi-persona apps. Renders the
+// switcher in the topbar center slot, picks the active workspace from
+// URL state (?w=<id>) or default, and feeds the active workspace's
+// nav-membership down to NavTree as an allow-set.
+//
+// Apps that don't need workspaces stick with DefaultAppShell. Both
+// shells live side-by-side; createKumikoApp's `shell` prop picks one.
+//
+// Active-workspace resolution priority:
+//   1. URL workspace segment `/<workspace>/...`  (user-driven, shareable)
+//   2. `initialWorkspaceId` prop                  (caller-pinned, SSR/test)
+//   3. WorkspaceDefinition with default:true      (engine-validated unique)
+//   4. First workspace the user has access to
+//
+// State lives in the URL as the single source of truth via the standard
+// nav route (`useNav().route.workspaceId`). No local React state —
+// tenant-switches and role refreshes heal automatically: `visible`
+// recomputes, the URL id no longer matches a visible workspace, the
+// resolution chain falls through to the default. Reloads / bookmarks /
+// shared links keep the active workspace because it's part of the URL.
+//
+// The switcher's onSelect calls nav.navigate({ workspaceId, screenId })
+// where screenId is the first nav-member of the target workspace, so a
+// click lands on a real screen instead of an unresolved root URL.
+//
+// Roles gating:
+//   * access.openToAll → always shown
+//   * access.roles     → shown only when user.roles ∩ access.roles ≠ ∅
+//   * access undefined → shown to everyone (engine convention — same
+//                        rule that NavDefinition.access follows)
+
+import type { AccessRule } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { AppSchema, FeatureSchema, WorkspaceSchema } from "@cosmicdrift/kumiko-renderer";
+import { qualifyNavId, toAppSchema, useNav } from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useCallback, useLayoutEffect, useMemo } from "react";
+import { AppLayout } from "./app-layout";
+import { lastSegment, NavTree } from "./nav-tree";
+import { Sidebar } from "./sidebar";
+import { Topbar } from "./topbar";
+import { WorkspaceSwitcher } from "./workspace-switcher";
+
+export type WorkspaceShellUser = {
+  readonly id: string;
+  readonly roles: readonly string[];
+};
+
+export type WorkspaceShellProps = {
+  /** Branding / logo on the left side of the topbar. */
+  readonly brand: ReactNode;
+  /** Schema mit `workspaces` populated — die engine baut das aus
+   *  registry.getAllWorkspaces() + getWorkspaceNavs(). Akzeptiert
+   *  AppSchema (multi-feature) oder die legacy FeatureSchema (single-
+   *  feature, workspaces inline). Ohne Workspaces fällt der Shell auf
+   *  plain NavTree ohne Switcher zurück. */
+  readonly schema: AppSchema | FeatureSchema;
+  /** Optional topbar end-slot — TenantSwitcher / ThemeToggle / UserMenu. */
+  readonly topbarActions?: ReactNode;
+  /** Current user. Drives which workspaces appear in the switcher. */
+  readonly user?: WorkspaceShellUser;
+  /** Initial active workspace short id ("admin"). When omitted: default
+   *  workspace from schema, otherwise first accessible. Useful for SSR
+   *  and tests to pre-seed without hitting the URL. */
+  readonly initialWorkspaceId?: string;
+  /** Footer-Slot unten in der Sidebar — Profile-Row, Help-Link, Build-
+   *  Info. Klebt am unteren Rand via `mt-auto` (siehe Sidebar.footer).
+   *  Symmetrisch zu DefaultAppShell.sidebarFooter. */
+  readonly sidebarFooter?: ReactNode;
+  /** Screen content. */
+  readonly children: ReactNode;
+};
+
+export function WorkspaceShell({
+  brand,
+  schema,
+  topbarActions,
+  user,
+  initialWorkspaceId,
+  sidebarFooter,
+  children,
+}: WorkspaceShellProps): ReactNode {
+  const app = useMemo(() => toAppSchema(schema), [schema]);
+  const visible = useMemo<readonly WorkspaceSchema[]>(
+    () => filterByAccess(app.workspaces ?? [], user?.roles),
+    [app.workspaces, user?.roles],
+  );
+
+  const nav = useNav();
+  const routeWorkspaceId = nav.route?.workspaceId;
+
+  // Single source of truth: URL > initial > engine-default > first visible.
+  // Recomputed on every dependency change — no local state, no stale-id
+  // healing useEffect. If the URL points at a workspace the user can no
+  // longer access (e.g. after a tenant-switch), the chain falls through
+  // to the resolveDefaultId fallback.
+  const activeId = useMemo(() => {
+    if (
+      routeWorkspaceId !== undefined &&
+      visible.some((ws) => ws.definition.id === routeWorkspaceId)
+    ) {
+      return routeWorkspaceId;
+    }
+    return resolveDefaultId(visible, initialWorkspaceId);
+  }, [routeWorkspaceId, visible, initialWorkspaceId]);
+
+  const handleSelect = useCallback(
+    (id: string) => {
+      // Pick the first nav-member that actually points at a screen so
+      // the URL lands on something renderable instead of `/<workspace>`.
+      // Section-headers (nav-Einträge ohne `screen`) werden übersprungen.
+      const target = visible.find((ws) => ws.definition.id === id);
+      const screenId = firstNavScreenId(app, target?.navMembers);
+      nav.navigate({ workspaceId: id, screenId });
+    },
+    [nav, app, visible],
+  );
+
+  // Initial sync: covers two URL states that need a default-fill so
+  // NavTree links and RoutedScreen have something to chew on.
+  //
+  //   1. No workspace in URL ("/" or wrong workspace id) → fill the
+  //      active workspace AND its first nav-member's screen.
+  //   2. Workspace present but screen missing ("/admin") → fill in the
+  //      first nav-member's screen, keep the workspace.
+  //
+  // replace, NOT navigate: these are default-fills, not user actions.
+  // Using pushState would create a history entry the user never asked
+  // for — Browser-Back from /admin/x → / → effect re-pushes →
+  // Back-loop. replaceState swaps in place: Back leaves the app cleanly.
+  //
+  // useLayoutEffect, NOT useEffect: the children below this shell render
+  // RoutedScreen with the URL's current screenId. If that's "" (URL was
+  // "/" or "/admin"), KumikoScreen renders a "Screen not found" banner
+  // for the empty qn. useEffect would let that banner paint to the
+  // screen for one frame before the URL got fixed. useLayoutEffect runs
+  // synchronously between commit and paint, so the user only ever sees
+  // the resolved screen. (No SSR here, otherwise we'd need a guard.)
+  useLayoutEffect(() => {
+    if (activeId === undefined) return;
+    const routeScreenEmpty = nav.route?.screenId === undefined || nav.route.screenId === "";
+    const workspaceMatches = routeWorkspaceId === activeId;
+    if (workspaceMatches && !routeScreenEmpty) return; // URL is fine
+    const target = visible.find((ws) => ws.definition.id === activeId);
+    const navMembers = target?.navMembers;
+    if ((navMembers === undefined || navMembers.length === 0) && !routeScreenEmpty) {
+      // Workspace exists but no nav members — keep whatever screen the
+      // user typed, just lock the workspace prefix.
+      nav.replace({ workspaceId: activeId, screenId: nav.route?.screenId ?? "" });
+      return;
+    }
+    const screenId = firstNavScreenId(app, navMembers);
+    // Loop-guard: wenn keiner der nav-members eine screen-property hat
+    // (alle section-headers oder unbekannte QNs), würde nav.replace mit
+    // screenId="" den Effect bei jedem Re-Render erneut feuern und den
+    // User auf "/<workspace>/" pinnen. Lieber gar nicht replacen — der
+    // Workspace-Selector kann den User dann manuell auf einen leaf-nav
+    // schicken.
+    if (screenId === "") return;
+    nav.replace({ workspaceId: activeId, screenId });
+  }, [activeId, routeWorkspaceId, visible, nav, app]);
+
+  const activeWorkspace = useMemo(
+    () => visible.find((ws) => ws.definition.id === activeId),
+    [visible, activeId],
+  );
+
+  // Filter resolution has THREE branches and getting them right matters:
+  //   * Schema declares workspaces + active resolved → filter to its members
+  //   * Schema declares workspaces + NO active visible → empty allow-set
+  //     (NOT undefined). This catches the "user has no accessible workspace"
+  //     case — falling back to "no filter" would leak nav items the user
+  //     shouldn't see, e.g. admin entries to a driver after a role change.
+  //   * Schema doesn't declare workspaces at all → undefined (no filter).
+  //     Apps that haven't opted into workspaces yet get every nav as before.
+  const allowedNavQns = useMemo(() => {
+    const hasWorkspaceMode = app.workspaces !== undefined && app.workspaces.length > 0;
+    if (!hasWorkspaceMode) return undefined;
+    if (activeWorkspace === undefined) return new Set<string>();
+    return new Set(activeWorkspace.navMembers);
+  }, [app.workspaces, activeWorkspace]);
+
+  const switcher = activeId !== undefined && (
+    <WorkspaceSwitcher workspaces={visible} activeId={activeId} onSelect={handleSelect} />
+  );
+
+  return (
+    <AppLayout
+      topbar={<Topbar start={brand} center={switcher || undefined} end={topbarActions} />}
+      sidebar={
+        <Sidebar {...(sidebarFooter !== undefined && { footer: sidebarFooter })}>
+          <NavTree
+            schema={app}
+            {...(user !== undefined && { user })}
+            {...(allowedNavQns !== undefined && { allowedNavQns })}
+          />
+        </Sidebar>
+      }
+    >
+      {children}
+    </AppLayout>
+  );
+}
+
+// --- helpers (exported for tests) ---
+
+export function filterByAccess(
+  workspaces: readonly WorkspaceSchema[],
+  userRoles: readonly string[] | undefined,
+): readonly WorkspaceSchema[] {
+  const roles = userRoles ?? [];
+  return [...workspaces]
+    .filter((ws) => userMatchesAccess(ws.definition.access, roles))
+    .sort(byOrderThenInsertion);
+}
+
+function userMatchesAccess(access: AccessRule | undefined, userRoles: readonly string[]): boolean {
+  if (access === undefined) return true;
+  if ("openToAll" in access) return access.openToAll;
+  return access.roles.some((r) => userRoles.includes(r));
+}
+
+function byOrderThenInsertion(a: WorkspaceSchema, b: WorkspaceSchema): number {
+  // Missing `order` sorts last; ties keep insertion order via stable sort.
+  const ao = a.definition.order ?? Number.POSITIVE_INFINITY;
+  const bo = b.definition.order ?? Number.POSITIVE_INFINITY;
+  return ao - bo;
+}
+
+/** Returns the short screen-id of the first nav-member that points at
+ *  a screen. Walks the workspace's nav-list in order and skips section-
+ *  headers (NavDefinitions ohne `screen`) so ein workspace dessen erstes
+ *  Member ein Header ist trotzdem auf einen renderbaren Screen auflöst.
+ *
+ *  Returns "" when:
+ *    - navMembers is undefined or empty
+ *    - all members are section-headers (no `screen` property)
+ *    - all members are unknown to the schema (drift zwischen
+ *      r.workspace.nav und den registrierten navs — boot-validator fängt
+ *      das server-side, hier nur graceful fallback)
+ *
+ *  The caller MUST loop-guard on "": rendering with screenId="" macht
+ *  KumikoScreen den not-found-banner zeigen — und ein nav.replace mit
+ *  leerem screenId würde den useLayoutEffect in WorkspaceShell bei
+ *  jedem Re-Render erneut feuern (siehe matching guard dort).
+ *
+ *  Earlier code used `lastSegment(navQn)` which only worked when the
+ *  feature followed the convention nav.id === screen.id (samples/apps/
+ *  workspaces does this). Apps with distinct ids (publicstatus: nav
+ *  "components" → screen "component-list") got "Screen not found".
+ *
+ *  Exported für Edge-Case-Tests. */
+export function firstNavScreenId(
+  app: AppSchema,
+  navMembers: readonly string[] | undefined,
+): string {
+  if (navMembers === undefined || navMembers.length === 0) return "";
+  for (const navQn of navMembers) {
+    for (const feature of app.features) {
+      for (const nav of feature.navs ?? []) {
+        if (qualifyNavId(feature.featureName, nav.id) !== navQn) continue;
+        if (nav.screen === undefined) break; // section-header → nächstes member
+        return lastSegment(nav.screen);
+      }
+    }
+  }
+  return "";
+}
+
+export function resolveDefaultId(
+  visible: readonly WorkspaceSchema[],
+  preferredShortId: string | undefined,
+): string | undefined {
+  // 1. Caller-pinned preference (URL or test prop) wins if it's accessible.
+  if (preferredShortId !== undefined) {
+    const match = visible.find((ws) => ws.definition.id === preferredShortId);
+    if (match !== undefined) return match.definition.id;
+  }
+  // 2. Engine-declared default if accessible.
+  const defaulted = visible.find((ws) => ws.definition.default === true);
+  if (defaulted !== undefined) return defaulted.definition.id;
+  // 3. First workspace the user can see.
+  return visible[0]?.definition.id;
+}

package/src/layout/workspace-switcher.tsx

@@ -0,0 +1,62 @@
+// WorkspaceSwitcher — dumb component for picking the active workspace.
+// Receives the role-filtered + order-sorted workspace list, the active
+// id, and a callback. Stays presentational so WorkspaceShell can own the
+// state (URL ?w=, defaults, role filtering) and tests can hand any list
+// in directly.
+
+import type { WorkspaceSchema } from "@cosmicdrift/kumiko-renderer";
+import { useTranslation } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+export type WorkspaceSwitcherProps = {
+  readonly workspaces: readonly WorkspaceSchema[];
+  readonly activeId: string;
+  readonly onSelect: (workspaceQn: string) => void;
+  readonly testId?: string;
+};
+
+export function WorkspaceSwitcher({
+  workspaces,
+  activeId,
+  onSelect,
+  testId,
+}: WorkspaceSwitcherProps): ReactNode {
+  const t = useTranslation();
+  // Single workspace doesn't need a switcher — the user has no choice
+  // anyway. Render nothing instead of a useless one-button row.
+  if (workspaces.length <= 1) return null;
+  return (
+    <div
+      data-testid={testId}
+      data-kumiko-layout="workspace-switcher"
+      role="tablist"
+      className="flex items-center gap-1"
+    >
+      {workspaces.map((ws) => {
+        const active = ws.definition.id === activeId;
+        const label = ws.definition.label.includes(".")
+          ? t(ws.definition.label)
+          : ws.definition.label;
+        return (
+          <button
+            type="button"
+            key={ws.definition.id}
+            role="tab"
+            aria-selected={active}
+            data-testid={`workspace-tab-${ws.definition.id}`}
+            onClick={() => onSelect(ws.definition.id)}
+            className={cn(
+              "rounded-md px-3 py-1.5 text-sm font-medium transition-colors",
+              active
+                ? "bg-accent text-accent-foreground"
+                : "text-muted-foreground hover:bg-accent/40",
+            )}
+          >
+            {label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}

package/src/lib/cn.ts

@@ -0,0 +1,10 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+/** shadcn-Standard-Helper: clsx für konditionales Zusammenstecken,
+ *  tailwind-merge für Konfliktauflösung (z.B. `px-2 px-4` → `px-4`).
+ *  Jedes Primitive nutzt das um Consumer-Klassen mit Default-Klassen
+ *  zu mergen ohne Duplikate. */
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}

package/src/primitives/action-menu.tsx

@@ -0,0 +1,111 @@
+// Generic Action-Menu — Trigger + Items, auf @radix-ui/react-dropdown-
+// menu basiert. Wird benutzt für ProfileMenu (Topbar-Avatar), Edit-
+// Header-Menu (Three-Dots), List-Row-Kebab — die Mechanik ist überall
+// dieselbe, nur der Trigger unterscheidet sich.
+//
+// Nicht zu verwechseln mit RowActionsCell (siehe primitives/index.tsx),
+// die hat die rowActions-Schema-API + per-row Visibility-Logik. Hier
+// ist der Layer drunter: stable, schema-frei, callable von App-Code
+// und vom Schema-Renderer (KumikoApp).
+//
+// Items sind Discriminated Union (item / separator / label), Item kann
+// optional einen Keyboard-Shortcut-Hint rechts tragen (Linear-Pattern
+// "O then M") + Icon links + variant für danger-styling.
+
+import { type ReactNode, useState } from "react";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "./dropdown-menu";
+
+export type MenuItemDef =
+  | {
+      readonly kind: "item";
+      readonly id: string;
+      readonly label: string;
+      /** Optional Icon links vor dem Label (16px). */
+      readonly icon?: ReactNode;
+      /** Pure-display Shortcut-Hint rechts (monospace, gedimmt).
+       *  Caller registriert den Shortcut separat — Linear-Style
+       *  Strings wie "O then M", "Alt + Q", "⌘K". */
+      readonly shortcut?: string;
+      readonly onSelect: () => void;
+      readonly disabled?: boolean;
+      /** "danger" rendert Label rot — typisch Sign-out, Delete. */
+      readonly variant?: "default" | "danger";
+    }
+  | { readonly kind: "separator" }
+  | { readonly kind: "label"; readonly label: string };
+
+export type ActionMenuProps = {
+  /** Free-form Trigger-Component — Avatar, IconButton, Pill, Custom. */
+  readonly trigger: ReactNode;
+  /** aria-label für den Trigger-Wrapper. */
+  readonly triggerLabel?: string;
+  readonly items: readonly MenuItemDef[];
+  /** Wo das Popup relativ zum Trigger anchorn soll. Default: end. */
+  readonly align?: "start" | "center" | "end";
+  /** Min-width für den Content. Default: 14rem. */
+  readonly minWidth?: string;
+  readonly testId?: string;
+};
+
+export function ActionMenu({
+  trigger,
+  triggerLabel,
+  items,
+  align = "end",
+  minWidth = "14rem",
+  testId,
+}: ActionMenuProps): ReactNode {
+  const [open, setOpen] = useState(false);
+  return (
+    <DropdownMenu open={open} onOpenChange={setOpen}>
+      <DropdownMenuTrigger asChild>
+        <button
+          type="button"
+          data-testid={testId ?? "action-menu-trigger"}
+          {...(triggerLabel !== undefined && { "aria-label": triggerLabel })}
+          className="rounded outline-none focus-visible:ring-1 focus-visible:ring-ring"
+        >
+          {trigger}
+        </button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align={align} style={{ minWidth }}>
+        {items.map((item, idx) => {
+          if (item.kind === "separator") {
+            // biome-ignore lint/suspicious/noArrayIndexKey: Separators haben keine ID — Reihenfolge ist Identität
+            return <DropdownMenuSeparator key={`sep-${idx}`} />;
+          }
+          if (item.kind === "label") {
+            // biome-ignore lint/suspicious/noArrayIndexKey: gleicher Grund wie separator
+            return <DropdownMenuLabel key={`label-${idx}`}>{item.label}</DropdownMenuLabel>;
+          }
+          return (
+            <DropdownMenuItem
+              key={item.id}
+              onSelect={item.onSelect}
+              disabled={item.disabled === true}
+              data-testid={`action-menu-item-${item.id}`}
+              className={
+                item.variant === "danger" ? "text-destructive focus:text-destructive" : undefined
+              }
+            >
+              {item.icon !== undefined && <span className="size-4 shrink-0">{item.icon}</span>}
+              <span className="flex-1">{item.label}</span>
+              {item.shortcut !== undefined && (
+                <span className="ml-auto text-xs text-muted-foreground tracking-wider font-mono">
+                  {item.shortcut}
+                </span>
+              )}
+            </DropdownMenuItem>
+          );
+        })}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}