@cosmicdrift/kumiko-renderer-web 0.2.3 → 0.3.0

package/src/layout/tree-node-renderer.tsx

@@ -0,0 +1,292 @@
+// TreeNodeRenderer — recursive Pro-Knoten-Component für den Visual-Tree.
+//
+// **Pflichten** (visual-tree.md V.1.1-C):
+//   1. Render `[icon] [label] [actions]` row mit State-abhängigen Klassen
+//   2. Click-Dispatch: onClick mit gesetztem `node.target` → dispatchTarget
+//   3. Hover-Actions rechts (CSS-only, hover-visible)
+//   4. Children rekursiv: static-Array direkt, TreeChildrenSubscribe lazy
+//      mit subscribe/unsubscribe an expand/collapse
+//   5. Skeleton-Affordance: state="empty" + createAction → automatic
+//      "+"-Icon, dispatcht createAction.target
+//
+// **Expand-State** lebt nicht hier sondern im VisualTree (Top-Level)
+// damit localStorage-Persistenz pro Workspace eine Stelle hat. Renderer
+// kriegt `expanded: Set<path>` + `onToggle(path)` als Props.
+//
+// **Path** = Workspace-eindeutiger String (parent-path + child-index oder
+// node.label-segment). Stable über Re-Renders, eindeutig pro Knoten.
+//
+// Siehe visual-tree.md V.1.1-C + A4 (TreeNode-Type-Definition).
+
+import type {
+  TreeAction,
+  TreeChildrenSubscribe,
+  TreeContext,
+  TreeNode,
+  TreeNodeState,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { ChevronDown, ChevronRight, Plus } from "lucide-react";
+import { type ReactNode, useEffect, useState } from "react";
+import { cn } from "../lib/cn";
+import { dispatchTarget } from "./target-resolver-stub";
+
+// State → Tailwind-Klassen-Mapping. „filled" ist no-op (default-text).
+// Restliche Werte signalisieren visuell: stub = leise, empty = stark
+// gedimmt + italic, loading = pulse-animation, error = destruktiv-Farbe.
+const STATE_CLASSES: Readonly<Record<TreeNodeState, string>> = {
+  filled: "",
+  stub: "opacity-55",
+  empty: "opacity-50 italic",
+  loading: "animate-pulse",
+  error: "text-destructive",
+};
+
+// TypeGuard für TreeChildrenSubscribe-Form. Nach `Array.isArray()`-check
+// kann TS den Function-Branch nicht automatisch narrowen, daher dieser
+// explizite Guard statt `as`-Cast (siehe Memory `[Type Assertions]` und
+// build-target.ts:isArgsObject als Vorbild).
+function isSubscribeFn(c: readonly TreeNode[] | TreeChildrenSubscribe): c is TreeChildrenSubscribe {
+  return typeof c === "function";
+}
+
+export type TreeNodeRendererProps = {
+  readonly node: TreeNode;
+  readonly ctx: TreeContext;
+  readonly path: string;
+  readonly expanded: ReadonlySet<string>;
+  readonly onToggle: (path: string) => void;
+  readonly depth?: number;
+};
+
+export function TreeNodeRenderer({
+  node,
+  ctx,
+  path,
+  expanded,
+  onToggle,
+  depth = 0,
+}: TreeNodeRendererProps): ReactNode {
+  const isExpanded = expanded.has(path);
+  const hasChildren = node.children !== undefined;
+
+  // Dynamic-Children-Subscribe: nur wenn ausgeklappt UND Function-Form.
+  // null = noch nicht emitted (zeige loading), Array = letzter Emit.
+  //
+  // **Identity-Assumption** (TODO V.1.2 verifizieren mit echtem Provider):
+  // node.children muss als Function-Reference stabil über Re-Renders sein,
+  // sonst trigger der useEffect ständig unsubscribe+resubscribe ("re-
+  // subscribe-Storm"). Recommended-Pattern für Provider-Authors: Function
+  // als top-level-const oder useMemo'd, NICHT inline-Closure pro Emit.
+  // Bei first violation in V.1.2 entweder useMemo hier oder path-Cache
+  // im VisualTree-Top-Level — Entscheidung wenn realer Trigger sichtbar.
+  const [dynamicChildren, setDynamicChildren] = useState<readonly TreeNode[] | null>(null);
+  useEffect(() => {
+    if (!isExpanded) return;
+    if (node.children === undefined) return;
+    if (!isSubscribeFn(node.children)) return; // static-Array-Pfad in ChildrenView
+    const subscribe = node.children(ctx);
+    const unsubscribe = subscribe(setDynamicChildren);
+    return unsubscribe;
+  }, [isExpanded, node.children, ctx]);
+
+  const stateClass = STATE_CLASSES[node.state ?? "filled"];
+  const indentStyle = { paddingLeft: `${depth * 12 + 8}px` };
+
+  const handleRowClick = (): void => {
+    if (hasChildren) {
+      onToggle(path);
+      return;
+    }
+    if (node.target !== undefined) {
+      dispatchTarget(node.target);
+    }
+  };
+
+  return (
+    <div data-kumiko-tree-node={path}>
+      {/* Outer Row als <div role="button"> statt <button>: native <button>
+          darf laut HTML-Spec keine geschachtelten <button>-Children
+          enthalten — die HoverActions würden sonst ungültiges HTML
+          erzeugen. role+tabIndex+keyDown gibt äquivalente a11y. TODO V.1.2:
+          Arrow-key-navigation zwischen Tree-Siblings (ARIA-tree-Pattern). */}
+      {/* biome-ignore lint/a11y/useSemanticElements: nested <button> wäre invalid HTML — siehe HoverActions */}
+      <div
+        className={cn(
+          "group flex w-full items-center gap-1.5 py-1 pr-2 cursor-pointer hover:bg-accent/30 rounded-sm",
+          stateClass,
+        )}
+        style={indentStyle}
+        onClick={handleRowClick}
+        onKeyDown={(e) => {
+          if (e.key === "Enter" || e.key === " ") {
+            e.preventDefault();
+            handleRowClick();
+          }
+        }}
+        role="button"
+        tabIndex={0}
+        aria-expanded={hasChildren ? isExpanded : undefined}
+      >
+        <ChevronGlyph hasChildren={hasChildren} expanded={isExpanded} />
+        {node.icon !== undefined && (
+          <span aria-hidden className="size-3.5">
+            {node.icon}
+          </span>
+        )}
+        <span className="flex-1 truncate text-sm">{node.label}</span>
+        <HoverActions
+          actions={node.actions}
+          createAction={node.state === "empty" ? node.createAction : undefined}
+        />
+      </div>
+      {isExpanded && (
+        <ChildrenView
+          node={node}
+          ctx={ctx}
+          path={path}
+          expanded={expanded}
+          onToggle={onToggle}
+          depth={depth}
+          dynamicChildren={dynamicChildren}
+        />
+      )}
+    </div>
+  );
+}
+
+function ChevronGlyph({
+  hasChildren,
+  expanded,
+}: {
+  readonly hasChildren: boolean;
+  readonly expanded: boolean;
+}): ReactNode {
+  if (!hasChildren) return <span aria-hidden className="size-3.5" />;
+  return expanded ? (
+    <ChevronDown aria-hidden className="size-3.5 shrink-0" />
+  ) : (
+    <ChevronRight aria-hidden className="size-3.5 shrink-0" />
+  );
+}
+
+function HoverActions({
+  actions,
+  createAction,
+}: {
+  readonly actions?: readonly TreeAction[];
+  readonly createAction?: TreeAction;
+}): ReactNode {
+  const has = (actions !== undefined && actions.length > 0) || createAction !== undefined;
+  if (!has) return null;
+  return (
+    <span className="invisible group-hover:visible flex items-center gap-1 shrink-0">
+      {createAction !== undefined && (
+        <ActionButton action={createAction} icon={<Plus className="size-3.5" />} />
+      )}
+      {actions?.map((a) => (
+        <ActionButton key={a.label} action={a} icon={<span aria-hidden>{a.icon}</span>} />
+      ))}
+    </span>
+  );
+}
+
+function ActionButton({
+  action,
+  icon,
+}: {
+  readonly action: TreeAction;
+  readonly icon: ReactNode;
+}): ReactNode {
+  return (
+    <button
+      type="button"
+      aria-label={action.label}
+      className="p-0.5 hover:bg-accent rounded"
+      onClick={(e) => {
+        // Stop the event so the parent-row's onClick (which would
+        // toggle / dispatch the row's own target) doesn't fire.
+        e.stopPropagation();
+        dispatchTarget(action.target);
+      }}
+    >
+      {icon}
+    </button>
+  );
+}
+
+function ChildrenView({
+  node,
+  ctx,
+  path,
+  expanded,
+  onToggle,
+  depth,
+  dynamicChildren,
+}: {
+  readonly node: TreeNode;
+  readonly ctx: TreeContext;
+  readonly path: string;
+  readonly expanded: ReadonlySet<string>;
+  readonly onToggle: (path: string) => void;
+  readonly depth: number;
+  readonly dynamicChildren: readonly TreeNode[] | null;
+}): ReactNode {
+  // Array.isArray narrow't TS automatisch auf readonly TreeNode[] — kein
+  // as-Cast nötig (Memory `[Type Assertions]`).
+  if (Array.isArray(node.children)) {
+    const children = node.children;
+    return (
+      <>
+        {children.map((child, idx) => {
+          // Path: idx als stabiler Disambiguator falls Provider doppelte
+          // Labels liefert (Provider-Bug, aber React-Keys müssen unique
+          // sein sonst silent state-corruption). Provider-Liefer-Order
+          // ist stabil — idx ist hier kein „array-shift"-Risk wie bei
+          // user-rearrangeable Lists.
+          const childPath = `${path}/${idx}-${child.label}`;
+          return (
+            <TreeNodeRenderer
+              key={childPath}
+              node={child}
+              ctx={ctx}
+              path={childPath}
+              expanded={expanded}
+              onToggle={onToggle}
+              depth={depth + 1}
+            />
+          );
+        })}
+      </>
+    );
+  }
+  // Dynamic-children-Pfad: noch nicht emitted → Lade-Zeile, dann Liste.
+  if (dynamicChildren === null) {
+    return (
+      <div
+        className="text-xs text-muted-foreground italic py-1"
+        style={{ paddingLeft: `${(depth + 1) * 12 + 8}px` }}
+      >
+        Lädt …
+      </div>
+    );
+  }
+  return (
+    <>
+      {dynamicChildren.map((child, idx) => {
+        // Selbe idx-Disambiguator-Logik wie ChildrenView static-Branch.
+        const childPath = `${path}/${idx}-${child.label}`;
+        return (
+          <TreeNodeRenderer
+            key={childPath}
+            node={child}
+            ctx={ctx}
+            path={childPath}
+            expanded={expanded}
+            onToggle={onToggle}
+            depth={depth + 1}
+          />
+        );
+      })}
+    </>
+  );
+}

package/src/layout/visual-tree.tsx

@@ -0,0 +1,238 @@
+// @runtime client
+// VisualTree — Top-Level-Component für `r.workspace({ navigation: "tree" })`-
+// Workspaces. Ersetzt VisualTreeStub aus Phase 0 Schicht 3.
+//
+// **Pflichten** (visual-tree.md V.1.1-A):
+//   1. Provider-Iteration via `useTreeProviders()`-Hook
+//   2. Subscribe-Wiring pro Provider mit unsubscribe-Cleanup beim Unmount
+//   3. Top-Level-Reihenfolge alphabetisch nach featureName
+//   4. Children-Lazy-Load (TreeNodeRenderer subscribed wenn Knoten ausgeklappt)
+//   5. localStorage-Persistenz für expanded-Set pro Workspace
+//
+// **Empty-State**: keine Provider registriert → Hint statt leerem
+// `<aside>` (Memory `[Sicherheit > Convenience]`: explicit empty statt
+// silent fallback). Apps die navigation:"tree" deklarieren aber keinen
+// clientFeatures.treeProvider liefern, kriegen eine sichtbare Diagnose.
+//
+// **Tenant-Source V.1.1**: TreeContext.tenantId ist auf SYSTEM_TENANT_ID
+// gepinnt. Provider die echten Tenant brauchen kommen V.1.2 (text-content)
+// — dann wird der Tenant-Source via Auth-Layer / TenantContext / Prop
+// verdrahtet. V.1.1 zeigt das Wiring durch, kein konkreter Tenant-Bedarf.
+//
+// Siehe visual-tree.md V.1.1-A.
+
+import type {
+  TenantId,
+  TreeChildrenSubscribe,
+  TreeContext,
+  TreeNode,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { type ReactNode, useEffect, useMemo, useState } from "react";
+import { useTreeProviders } from "../app/tree-providers-context";
+import { TreeNodeRenderer } from "./tree-node-renderer";
+
+const EXPANDED_STORAGE_PREFIX = "kumiko:visual-tree:expanded:";
+
+// V.1.1-Pin: TenantId für die Default-Tree-Context. Lokal als Branded-
+// Type-Construction (Memory `[Type Assertions]`) statt Value-Import aus
+// /engine — der engine-Barrel ist `runtime`-klassifiziert und ein client-
+// Modul darf ihn nicht als Wert konsumieren. **Sync-Pflicht**: muss mit
+// SYSTEM_TENANT_ID aus engine/types/identifiers.ts identisch bleiben;
+// ein Mismatch zeigt sich als „falscher Tenant" in Provider-Requests.
+// V.1.2 ersetzt den Pin durch echten Tenant-Source (TenantContext oder
+// Auth-Layer) sobald der erste Provider tenant-spezifische Daten braucht.
+const SYSTEM_TENANT_ID_PIN = "00000000-0000-4000-8000-000000000000" as TenantId;
+
+const DEFAULT_TREE_CTX: TreeContext = Object.freeze({ tenantId: SYSTEM_TENANT_ID_PIN });
+
+export type VisualTreeProps = {
+  /** Workspace-ID des aktiven `navigation:"tree"`-Workspaces. Wird als
+   *  Schlüssel für localStorage-Persistenz verwendet (separates
+   *  Expand-State pro Workspace, weil ein User mehrere Visual-Workspaces
+   *  haben kann). */
+  readonly workspaceId: string;
+};
+
+export function VisualTree({ workspaceId }: VisualTreeProps): ReactNode {
+  const providers = useTreeProviders();
+  const sortedProviders = useMemo(
+    () => [...providers.entries()].sort(([a], [b]) => a.localeCompare(b)),
+    [providers],
+  );
+
+  const [expanded, setExpanded] = useState<ReadonlySet<string>>(() => loadExpanded(workspaceId));
+
+  // localStorage-Persistenz: jeder Toggle persistiert sofort. Workspace-
+  // Switch lädt anderen Set neu (siehe 2nd useEffect).
+  useEffect(() => {
+    saveExpanded(workspaceId, expanded);
+  }, [workspaceId, expanded]);
+
+  // Workspace-Switch: expanded-Set neu laden (User hat anderen Tree-
+  // Workspace ausgewählt, dort gilt anderer Set).
+  useEffect(() => {
+    setExpanded(loadExpanded(workspaceId));
+  }, [workspaceId]);
+
+  const handleToggle = (path: string): void => {
+    setExpanded((prev) => {
+      const next = new Set(prev);
+      if (next.has(path)) {
+        next.delete(path);
+      } else {
+        next.add(path);
+      }
+      return next;
+    });
+  };
+
+  if (sortedProviders.length === 0) {
+    return <EmptyState />;
+  }
+
+  return (
+    <aside
+      aria-label="Visual Tree"
+      data-kumiko-layout="visual-tree"
+      className="flex flex-col text-sm overflow-y-auto"
+    >
+      {sortedProviders.map(([featureName, provider]) => (
+        <ProviderBranch
+          key={featureName}
+          featureName={featureName}
+          provider={provider}
+          ctx={DEFAULT_TREE_CTX}
+          expanded={expanded}
+          onToggle={handleToggle}
+        />
+      ))}
+    </aside>
+  );
+}
+
+// ProviderBranch — eine Sub-Section pro registrertem TreeProvider.
+// Jeder Provider liefert eine readonly TreeNode[] über Subscribe; jeder
+// Top-Level-Knoten wird via TreeNodeRenderer gerendert.
+function ProviderBranch({
+  featureName,
+  provider,
+  ctx,
+  expanded,
+  onToggle,
+}: {
+  readonly featureName: string;
+  readonly provider: TreeChildrenSubscribe;
+  readonly ctx: TreeContext;
+  readonly expanded: ReadonlySet<string>;
+  readonly onToggle: (path: string) => void;
+}): ReactNode {
+  // null = noch nicht emitted (initial-Loading). Ein Provider der
+  // niemals emittet bleibt damit sichtbar als „lädt …" und nicht
+  // unsichtbar — Memory `[Sicherheit > Convenience]`.
+  const [nodes, setNodes] = useState<readonly TreeNode[] | null>(null);
+
+  useEffect(() => {
+    // TODO V.1.2: Subscribe-Error-Handling. Drei Error-Surfaces sind heute
+    // nicht abgedeckt: (1) provider(ctx) wirft synchron, (2) subscribe(emit)
+    // wirft synchron, (3) Provider-internes SSE/fetch wirft → emit nie
+    // gefeuert, „lädt …" bleibt unendlich. Fix-Shape hängt vom
+    // V.1.2-Consumer (text-content) ab — transient-network-blip vs.
+    // tenant-misconfig haben unterschiedliche Recovery-Pfade. Reload-
+    // Action im Knoten (state="error" + retry-Button) als minimaler
+    // Plan, aber ohne konkreten Failure-Mode-Anker keine richtige Spec.
+    const subscribe = provider(ctx);
+    const unsubscribe = subscribe(setNodes);
+    return unsubscribe;
+  }, [provider, ctx]);
+
+  if (nodes === null) {
+    return (
+      <div
+        data-kumiko-tree-branch={featureName}
+        data-kumiko-tree-state="loading"
+        className="text-xs text-muted-foreground italic px-2 py-1"
+      >
+        {featureName}: lädt …
+      </div>
+    );
+  }
+
+  return (
+    <div data-kumiko-tree-branch={featureName}>
+      {nodes.map((node, idx) => {
+        // Selbe idx-Disambiguator-Logik wie TreeNodeRenderer.ChildrenView.
+        const nodePath = `${featureName}/${idx}-${node.label}`;
+        return (
+          <TreeNodeRenderer
+            key={nodePath}
+            node={node}
+            ctx={ctx}
+            path={nodePath}
+            expanded={expanded}
+            onToggle={onToggle}
+            depth={0}
+          />
+        );
+      })}
+    </div>
+  );
+}
+
+function EmptyState(): ReactNode {
+  // <section> + aria-label + tabIndex=0 macht den Empty-State per Tab
+  // erreichbar — sonst wäre die Diagnose-Message für Keyboard-Nutzer
+  // unsichtbar/nicht-fokussierbar. <section> ist semantisch korrekt für
+  // „informational region", Biome akzeptiert tabIndex hier (im Gegensatz
+  // zu <aside> oder bare <div role="region">).
+  // TODO V.1.2: Volle Arrow-Key-Navigation zwischen Tree-Siblings (siehe
+  // ARIA-tree-Pattern). Heute nur Tab-Reach + native button-Tastatur.
+  return (
+    <section
+      aria-label="Visual Tree (no providers)"
+      data-kumiko-layout="visual-tree-empty"
+      className="p-4 text-sm text-muted-foreground"
+      // biome-ignore lint/a11y/noNoninteractiveTabindex: Empty-State ist eine Diagnose-Region die Keyboard-Nutzer per Tab erreichen können müssen
+      tabIndex={0}
+    >
+      <p className="m-0 font-semibold">Keine Tree-Provider aktiv</p>
+      <p className="mt-2">
+        Dieser Workspace deklariert <code>navigation: "tree"</code>, aber kein registriertes
+        Client-Feature liefert einen <code>treeProvider</code>. Siehe{" "}
+        <code>
+          createKumikoApp({"{"}clientFeatures: [...]{"}"})
+        </code>
+        .
+      </p>
+    </section>
+  );
+}
+
+// localStorage-Helpers. Stille Failure bei Storage-Errors (Quota,
+// Privacy-Mode) — Tree funktioniert dann ohne Persistenz, was ok ist.
+
+function storageKey(workspaceId: string): string {
+  return `${EXPANDED_STORAGE_PREFIX}${workspaceId}`;
+}
+
+function loadExpanded(workspaceId: string): ReadonlySet<string> {
+  if (typeof window === "undefined") return new Set();
+  try {
+    const raw = window.localStorage.getItem(storageKey(workspaceId));
+    if (raw === null) return new Set();
+    const parsed = JSON.parse(raw) as unknown;
+    if (!Array.isArray(parsed)) return new Set();
+    return new Set(parsed.filter((p): p is string => typeof p === "string"));
+  } catch {
+    return new Set();
+  }
+}
+
+function saveExpanded(workspaceId: string, expanded: ReadonlySet<string>): void {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(storageKey(workspaceId), JSON.stringify([...expanded]));
+  } catch {
+    // Privacy-Mode / Quota-Errors → ignorieren, Tree läuft ohne
+    // Persistenz weiter.
+  }
+}

package/src/layout/workspace-shell.tsx

@@ -33,10 +33,13 @@ 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 { useResolvers } from "../app/resolvers-context";
 import { AppLayout } from "./app-layout";
+import { EditorPanel } from "./editor-panel";
 import { lastSegment, NavTree } from "./nav-tree";
 import { Sidebar } from "./sidebar";
 import { Topbar } from "./topbar";
+import { VisualTree } from "./visual-tree";
 import { WorkspaceSwitcher } from "./workspace-switcher";
 
 export type WorkspaceShellUser = {
@@ -182,19 +185,42 @@ export function WorkspaceShell({
     <WorkspaceSwitcher workspaces={visible} activeId={activeId} onSelect={handleSelect} />
   );
 
+  // Sidebar-Content-Switch: workspace mit `navigation: "tree"` (opt-in)
+  // mountet die VisualTree-Component statt NavTree. Default (kein
+  // navigation gesetzt oder navigation="nav") behält das existing
+  // NavTree-Verhalten — kein Breaking-Change für Apps die Visual-Tree
+  // nicht aktivieren.
+  //
+  // VisualTree konsumiert TreeProviders via Context (siehe
+  // app/tree-providers-context.tsx) — App-Author registriert seine
+  // clientFeatures.treeProvider via createKumikoApp, kein zusätzlicher
+  // Prop hier nötig. Workspace-ID wird durchgereicht für die
+  // localStorage-Persistenz des expanded-Set.
+  // Siehe docs/plans/architecture/visual-tree.md A1 + V.1.1-A.
+  const resolvers = useResolvers();
+  const isTreeMode = activeWorkspace?.definition.navigation === "tree";
+
+  const sidebarContent =
+    activeWorkspace?.definition.navigation === "tree" ? (
+      <VisualTree workspaceId={activeWorkspace.definition.id} />
+    ) : (
+      <NavTree
+        schema={app}
+        {...(user !== undefined && { user })}
+        {...(allowedNavQns !== undefined && { allowedNavQns })}
+      />
+    );
+
   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 })}
-          />
+          {sidebarContent}
         </Sidebar>
       }
     >
+      {isTreeMode && <EditorPanel resolvers={resolvers} />}
       {children}
     </AppLayout>
   );