@cosmicdrift/kumiko-renderer 0.374.0 → 0.377.0

package/dist/web/layout/nav-tree.js

@@ -0,0 +1,536 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ChevronDown, ChevronRight, Plus, Search } from "lucide-react";
+import { createContext, useCallback, useContext, useEffect, useMemo, useState, } from "react";
+import { resolveNavigation } from "../../headless/index.js";
+import { lastSegment, toAppSchema, useLiveEvents, useNav, useTranslation } from "../../index.js";
+import { KumikoLink } from "../app/nav.js";
+import { useNavEntities, useNavProviders } from "../app/nav-providers-context.js";
+import { NAV_ICONS } from "../icons.js";
+import { cn } from "../lib/cn.js";
+import { SidebarGroup, SidebarGroupContent, SidebarGroupLabel, SidebarInput, SidebarMenu, SidebarMenuAction, SidebarMenuButton, SidebarMenuItem, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, useSidebar, } from "../ui/sidebar.js";
+import { resolveParentScreenId } from "./shell-breadcrumb.js";
+import { useDispatchTarget } from "./target-resolver-stub.js";
+import { parseTargetFromSearchParams } from "./target-url.js";
+// Widened alias for the two lookup sites below, which index by the plain
+// `string` icon key of the resolved NavNode/TreeAction tree — not the
+// closed NavIconKey union NAV_ICONS itself is typed against.
+const NAV_ICON_LOOKUP = NAV_ICONS;
+const EMPTY_BADGES = new Map();
+const NavBadgesContext = createContext(EMPTY_BADGES);
+const NavFilterContext = createContext({ q: "", matches: () => true });
+const ActiveScreenMarkerContext = createContext(undefined);
+// Walks only the static `children` — provider-emitted nodes (treeNodeToNavNode
+// below) never set `screen`, so they can't hide a match this walk would miss.
+function treeContainsScreen(nodes, screenId) {
+    return nodes.some((n) => (n.screen !== undefined && lastSegment(n.screen) === screenId) ||
+        treeContainsScreen(n.children, screenId));
+}
+// Ein Knoten überlebt den Filter, wenn er selbst oder ein Nachfahre matcht.
+// Provider-Kinder sind zur Filterzeit schon materialisiert (Provider-Knoten
+// sind default-expanded → eager geladen), darum reicht die statische
+// children-Rekursion. ponytail: ein zur Filterzeit noch NICHT geladener
+// (user-zugeklappter) Provider wird über den force-expand in useNavNodeState
+// aufgeklappt, lädt und filtert dann mit.
+function subtreeMatches(node, matches) {
+    return matches(node.label) || node.children.some((c) => subtreeMatches(c, matches));
+}
+export function NavTree({ schema, user, testId, allowedNavQns, navBadges, }) {
+    const app = useMemo(() => toAppSchema(schema), [schema]);
+    const tree = useMemo(() => {
+        const source = buildNavRegistrySliceForApp(app, allowedNavQns);
+        return resolveNavigation({ source, ...(user !== undefined && { user }) });
+    }, [app, user, allowedNavQns]);
+    const nav = useNav();
+    const activeScreenId = nav.route?.screenId;
+    const activeEntityId = nav.route?.entityId;
+    // Same "no nav entry of its own" gap the breadcrumb closes (fw#2724):
+    // when the routed screen has no node in {tree}, fall back to its
+    // resolved parent so a detail/edit/form screen still orients the user.
+    const activeMarker = useMemo(() => {
+        if (activeScreenId === undefined)
+            return undefined;
+        const allScreens = app.features.flatMap((f) => f.screens);
+        const parentScreenId = resolveParentScreenId(allScreens, activeScreenId);
+        // A nav entry on an edit screen means "create"; an existing record (entityId
+        // in the route) belongs to its list, same rule as the breadcrumb.
+        if (activeEntityId !== undefined &&
+            parentScreenId !== undefined &&
+            treeContainsScreen(tree, parentScreenId)) {
+            return { screenId: parentScreenId, exact: false };
+        }
+        if (treeContainsScreen(tree, activeScreenId))
+            return { screenId: activeScreenId, exact: true };
+        return parentScreenId !== undefined ? { screenId: parentScreenId, exact: false } : undefined;
+    }, [tree, app.features, activeScreenId, activeEntityId]);
+    // Collapsed-Set: nur die explizit zugeklappten qualified-names. Default
+    // ist also "alles auf" — neue Features tauchen sofort offen auf, ohne
+    // dass der User erst klicken muss.
+    const [collapsed, setCollapsed] = useState(() => new Set());
+    const onToggle = useCallback((qn) => {
+        setCollapsed((prev) => {
+            const next = new Set(prev);
+            if (next.has(qn))
+                next.delete(qn);
+            else
+                next.add(qn);
+            return next;
+        });
+    }, []);
+    const t = useTranslation();
+    const { state: sidebarState } = useSidebar();
+    const [filter, setFilter] = useState("");
+    // The search box is only CSS-hidden (`group-data-[collapsible=icon]:hidden`)
+    // when the sidebar collapses to icon rail, not unmounted — without this,
+    // a stale filter re-applies invisibly on the next expand (fw#1816).
+    useEffect(() => {
+        if (sidebarState === "collapsed")
+            setFilter("");
+    }, [sidebarState]);
+    const q = filter.trim().toLowerCase();
+    const matches = useCallback((raw) => {
+        const label = raw.includes(".") ? t(raw) : raw;
+        return label.toLowerCase().includes(q);
+    }, [t, q]);
+    const navFilter = useMemo(() => ({ q, matches }), [q, matches]);
+    return (_jsx(ActiveScreenMarkerContext.Provider, { value: activeMarker, children: _jsx(NavFilterContext.Provider, { value: navFilter, children: _jsx(NavBadgesContext.Provider, { value: navBadges ?? EMPTY_BADGES, children: _jsxs("div", { "data-testid": testId, "data-kumiko-layout": "nav-tree", className: "flex w-full flex-col gap-3", children: [_jsxs("div", { className: "relative mb-0 group-data-[collapsible=icon]:hidden", children: [_jsx(Search, { "aria-hidden": "true", className: "pointer-events-none absolute left-2 top-1/2 size-4 -translate-y-1/2 text-sidebar-muted" }), _jsx(SidebarInput, { className: "pl-8", value: filter, onChange: (e) => setFilter(e.target.value), placeholder: t("kumiko.nav.search"), "aria-label": t("kumiko.nav.search") })] }), tree.map((node) => isPureSection(node) ? (_jsx(NavSection, { node: node, collapsed: collapsed, onToggle: onToggle }, node.qualifiedName)) : (_jsx(SidebarMenu, { children: _jsx(NavMenuNode, { node: node, collapsed: collapsed, onToggle: onToggle }) }, node.qualifiedName)))] }) }) }) }));
+}
+// 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.
+// Defense-in-depth (555/4): every current call site already guards on
+// node.screen/node.target !== undefined before rendering <NavBadge>, so this
+// early-return changes no current behavior — it's here so a future call
+// site added without that guard can't silently show a leaf's badge on an
+// unrelated container node that happens to share its last-segment.
+function NavBadge({ node }) {
+    const badges = useContext(NavBadgesContext);
+    if (node.screen === undefined && node.target === undefined)
+        return null;
+    const badge = badges.get(lastSegment(node.qualifiedName));
+    if (badge === undefined)
+        return null;
+    return _jsx("span", { className: "ml-auto shrink-0", children: badge });
+}
+// 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)
+// ist dagegen ein klickbarer Menu-Eintrag.
+function isPureSection(node) {
+    return (node.screen === undefined &&
+        node.target === undefined &&
+        node.provider !== true &&
+        node.createAction === undefined &&
+        node.children.length > 0);
+}
+// i18n-Key Konvention: enthält das label einen Punkt, durchs t() laufen
+// lassen (Bundle kennt den Key → übersetzt, sonst bleibt der Key sichtbar
+// = vergessene Übersetzung). Reine String-Labels bleiben unangetastet.
+function useLabel(node) {
+    const t = useTranslation();
+    return node.label.includes(".") ? t(node.label) : node.label;
+}
+// Without an icon only the collapsed rail shows the initial letter; expanded,
+// the label stands alone.
+function NavLeadingIcon({ node, active, expanded = false, label, }) {
+    const iconKey = expanded && node.icon === "folder" ? "folder-open" : node.icon;
+    const isKnownIcon = iconKey !== undefined && Object.hasOwn(NAV_ICONS, iconKey);
+    const NavIcon = iconKey !== undefined && isKnownIcon ? NAV_ICON_LOOKUP[iconKey] : undefined;
+    useEffect(() => {
+        if (iconKey !== undefined && !isKnownIcon) {
+            // biome-ignore lint/suspicious/noConsole: diagnostic for unregistered nav icon keys
+            console.warn(`[kumiko] Nav entry "${node.qualifiedName}" references icon "${iconKey}", which is not ` +
+                `registered in NAV_ICONS — falling back to the dot indicator. Check the icon key spelling.`);
+        }
+    }, [iconKey, isKnownIcon, node.qualifiedName]);
+    if (NavIcon !== undefined)
+        return _jsx(NavIcon, { "aria-hidden": "true", className: "shrink-0" });
+    const initial = label?.trim().charAt(0).toUpperCase();
+    if (initial === undefined || initial === "")
+        return null;
+    return (_jsx("span", { "aria-hidden": "true", className: cn("hidden size-4 shrink-0 items-center justify-center font-medium text-xs group-data-[collapsible=icon]:flex", active ? "text-sidebar-accent-foreground" : "text-sidebar-foreground/70"), children: initial }));
+}
+// Stable-reference empty-list — sonst destabilisiert ein neues `[]` pro
+// Render die useEffect-deps der SSE-Subscription.
+const EMPTY_ENTITY_LIST = [];
+// Active-Target-Vergleich: featureId + action exakt, args shallow-equal
+// (heute nur primitives). Gespiegelt aus dem alten TreeNodeRenderer.
+function targetsEqual(a, b) {
+    if (b === undefined)
+        return false;
+    if (a.featureId !== b.featureId || a.action !== b.action)
+        return false;
+    const aKeys = a.args ? Object.keys(a.args) : [];
+    const bKeys = b.args ? Object.keys(b.args) : [];
+    if (aKeys.length !== bKeys.length)
+        return false;
+    for (const k of aKeys) {
+        if (a.args?.[k] !== b.args?.[k])
+            return false;
+    }
+    return true;
+}
+// Adapter: provider-emittierte TreeNodes → renderbare NavNodes. Synthetische
+// QN aus parent-QN + idx-label (stabil über Emit-Order). Statische children
+// rekursiv. ponytail: eine TreeChildrenSubscribe-Function als children wird
+// als Leaf behandelt — nested-dynamic-Provider nutzt heute kein Consumer;
+// upgrade-path = synthetische QN registrieren wenn einer sie emittet.
+function treeNodeToNavNode(tn, parentQn, idx) {
+    const qualifiedName = `${parentQn}/${idx}-${tn.label}`;
+    const children = Array.isArray(tn.children)
+        ? tn.children.map((c, i) => treeNodeToNavNode(c, qualifiedName, i))
+        : [];
+    return {
+        qualifiedName,
+        label: tn.label,
+        order: idx,
+        children,
+        ...(tn.icon !== undefined && { icon: tn.icon }),
+        ...(tn.target !== undefined && { target: tn.target }),
+        ...(tn.actions !== undefined && { actions: tn.actions }),
+        ...(tn.createAction !== undefined && { createAction: tn.createAction }),
+    };
+}
+// Lazy provider-children + SSE-Live-Refresh für einen `provider: true`-Knoten.
+// Subscribe läuft erst wenn der Knoten ausgeklappt ist (enabled); die
+// treeEntities-Liste (per QN) re-fired den Provider bei Entity-Events → neu
+// erstellte Knoten erscheinen live. Logik gespiegelt aus VisualTree.ProviderBranch.
+function useNavProviderChildren(qn, enabled) {
+    const providers = useNavProviders();
+    const entitiesMap = useNavEntities();
+    const subscribeLive = useLiveEvents();
+    const provider = providers.get(qn);
+    const entities = entitiesMap.get(qn) ?? EMPTY_ENTITY_LIST;
+    const [raw, setRaw] = useState(null);
+    const [error, setError] = useState(null);
+    const [attempt, setAttempt] = useState(0);
+    useEffect(() => {
+        if (!enabled || entities.length === 0)
+            return;
+        const unsubs = entities.map((e) => subscribeLive(e, () => setAttempt((n) => n + 1)));
+        return () => {
+            for (const u of unsubs)
+                u();
+        };
+    }, [enabled, entities, subscribeLive]);
+    // `attempt` triggert SSE-Refresh + erneutes Subscribe — Biome sieht es
+    // nicht im body, semantisch ist es der re-fire-Trigger.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: attempt = re-fire trigger
+    useEffect(() => {
+        if (!enabled) {
+            setRaw(null);
+            setError(null);
+            return;
+        }
+        if (provider === undefined) {
+            setError("Kein nav-provider registriert.");
+            return;
+        }
+        setError(null);
+        setRaw(null);
+        try {
+            const subscribe = provider();
+            try {
+                return subscribe(setRaw, (e) => setError(e instanceof Error ? e.message : String(e)));
+            }
+            catch (e) {
+                setError(e instanceof Error ? e.message : "Subscribe fehlgeschlagen.");
+            }
+        }
+        catch (e) {
+            setError(e instanceof Error ? e.message : "Provider-Init fehlgeschlagen.");
+        }
+        return undefined;
+    }, [enabled, provider, attempt]);
+    const nodes = useMemo(() => (raw === null ? null : raw.map((tn, i) => treeNodeToNavNode(tn, qn, i))), [raw, qn]);
+    return { nodes, error };
+}
+// Geteilte Knoten-Logik für Top-Level- (NavMenuNode) und Sub-Knoten
+// (NavSubNode): Label, Expand/Collapse, active-State (screen ODER target),
+// und die lazy Provider-Children. Die zwei Renderer unterscheiden sich nur
+// in den shadcn-Primitives, nicht in dieser Logik.
+function useNavNodeState(node, collapsed) {
+    const nav = useNav();
+    const { q: filterQ, matches } = useContext(NavFilterContext);
+    const filterActive = filterQ !== "";
+    const displayLabel = useLabel(node);
+    const isCollapsed = collapsed.has(node.qualifiedName);
+    const expandable = node.children.length > 0 || node.provider === true;
+    // Aktiver Filter klappt jeden Container auf, damit Treffer unter zugeklappten
+    // Ordnern sichtbar werden (und Provider-Kinder nachladen).
+    const isExpanded = expandable && (!isCollapsed || filterActive);
+    const { nodes: providerChildren, error: providerError } = useNavProviderChildren(node.qualifiedName, node.provider === true && isExpanded);
+    const activeTarget = useMemo(() => parseTargetFromSearchParams(nav.searchParams), [nav.searchParams]);
+    const activeMarker = useContext(ActiveScreenMarkerContext);
+    const screenActive = node.screen !== undefined &&
+        activeMarker !== undefined &&
+        lastSegment(node.screen) === activeMarker.screenId;
+    const screenIsExactMatch = screenActive && activeMarker?.exact === true;
+    const targetActive = node.target !== undefined && targetsEqual(node.target, activeTarget);
+    const childNodes = node.provider === true ? (providerChildren ?? []) : node.children;
+    const visibleChildNodes = filterActive
+        ? childNodes.filter((c) => subtreeMatches(c, matches))
+        : childNodes;
+    return {
+        displayLabel,
+        isCollapsed,
+        expandable,
+        isExpanded,
+        active: screenActive || targetActive,
+        ariaCurrent: screenIsExactMatch || targetActive,
+        childNodes: visibleChildNodes,
+        // Ein gefilterter Knoten verschwindet nur, wenn weder er selbst noch ein
+        // sichtbar gebliebenes Kind matcht — sonst bliebe ein leerer Ordner-Header.
+        hidden: filterActive && !matches(node.label) && visibleChildNodes.length === 0,
+        providerLoading: node.provider === true && isExpanded && providerChildren === null,
+        providerError,
+        workspaceId: nav.route?.workspaceId,
+    };
+}
+// Action icon lookup: registered NAV_ICONS key → Lucide icon, otherwise the
+// raw string as text (provider convention, no boot-fail on an unknown key).
+function ActionGlyph({ icon }) {
+    const Icon = Object.hasOwn(NAV_ICONS, icon) ? NAV_ICON_LOOKUP[icon] : undefined;
+    if (Icon !== undefined)
+        return _jsx(Icon, { "aria-hidden": true, className: "size-3.5" });
+    return (_jsx("span", { "aria-hidden": true, className: "text-xs", children: icon }));
+}
+// Boot validates screen XOR target for NavDefinition actions, but a
+// provider-emitted TreeNode reaches here without going through boot — warn
+// once per label instead of rendering a dead button.
+const warnedTreeActionLabels = new Set();
+function warnTreeActionMisconfigured(label, problem) {
+    const key = `${label}:${problem}`;
+    // skip: already warned for this label and problem — suppresses the repeat, not the warning itself.
+    if (warnedTreeActionLabels.has(key))
+        return;
+    warnedTreeActionLabels.add(key);
+    // biome-ignore lint/suspicious/noConsole: dev-warning for a setup error
+    console.warn(`[kumiko] Nav action "${label}" ${problem}`);
+}
+// An action button carries screen XOR target (see TreeAction) — `screen`
+// renders a KumikoLink to the route, `target` a dispatch button. Same
+// classes/size either way, only the element changes.
+function TreeActionControl({ action, ariaLabel, className, dispatch, workspaceId, children, }) {
+    // Authored actions are typed screen-XOR-target, but schemas can arrive
+    // untyped over the wire — read both fields to stay defensive at runtime.
+    const loose = action;
+    if (loose.screen !== undefined && loose.target !== undefined) {
+        warnTreeActionMisconfigured(action.label, 'has both "screen" and "target" set — using "screen", "target" is ignored.');
+    }
+    if (loose.screen !== undefined) {
+        const screenId = lastSegment(loose.screen);
+        return (_jsx(KumikoLink, { to: { ...(workspaceId !== undefined && { workspaceId }), screenId }, "aria-label": ariaLabel, className: className, onClick: (e) => e.stopPropagation(), children: children }));
+    }
+    if (loose.target !== undefined) {
+        const target = loose.target;
+        return (_jsx("button", { type: "button", "aria-label": ariaLabel, className: className, onClick: (e) => {
+                e.stopPropagation();
+                dispatch(target);
+            }, children: children }));
+    }
+    warnTreeActionMisconfigured(action.label, 'has neither "screen" nor "target" set — it will not render.');
+    return null;
+}
+// Hover-actions + the "+" affordance, positioned absolute right.
+// createAction is persistent (a user-visible "+"), the other actions only
+// show on hover. stopPropagation so the row click (toggle/dispatch) doesn't
+// also fire. `expandable` comes from useNavNodeState (s.expandable) instead
+// of being re-derived here — a node without a chevron doesn't need the
+// right-7 gap, otherwise the "+" hangs 28px off the edge.
+function NodeActions({ node, expandable, workspaceId, }) {
+    const dispatch = useDispatchTarget();
+    const t = useTranslation();
+    const create = node.createAction;
+    const actions = node.actions ?? [];
+    if (create === undefined && actions.length === 0)
+        return null;
+    const label = (s) => (s.includes(".") ? t(s) : s);
+    const btn = "flex size-5 items-center justify-center rounded-md text-sidebar-muted hover:bg-sidebar-accent hover:text-sidebar-accent-foreground";
+    const hover = "opacity-0 group-hover/menu-item:opacity-100 group-hover/menu-sub-item:opacity-100 group-focus-within/menu-item:opacity-100";
+    return (_jsxs("div", { className: cn("absolute top-1 flex items-center gap-0.5", expandable ? "right-7" : "right-1"), children: [create !== undefined && (_jsx(TreeActionControl, { action: create, ariaLabel: label(create.label), className: btn, dispatch: dispatch, workspaceId: workspaceId, children: _jsx(Plus, { className: "size-3.5" }) })), actions.map((a) => (_jsx(TreeActionControl, { action: a, ariaLabel: label(a.label), className: cn(btn, hover), dispatch: dispatch, workspaceId: workspaceId, children: _jsx(ActionGlyph, { icon: a.icon }) }, a.label)))] }));
+}
+// Status-Zeilen innerhalb einer Provider-Sub-Liste (lazy-loading / error).
+function ProviderStatus({ loading, error, }) {
+    if (error !== null) {
+        return _jsx("li", { className: "px-2 py-1 text-xs text-destructive", children: error });
+    }
+    if (loading) {
+        return _jsx("li", { className: "px-2 py-1 text-xs text-sidebar-muted italic", children: "L\u00E4dt \u2026" });
+    }
+    return null;
+}
+// Top-Level-Section: SidebarGroup mit STATISCHEM Label (sidebar-07-Muster —
+// "Platform"/"Projects" sind feste Überschriften, keine Toggles). Collapse
+// gehört auf Items MIT children, nicht auf die Section selbst.
+function NavSection({ node, collapsed, onToggle }) {
+    const displayLabel = useLabel(node);
+    const { q, matches } = useContext(NavFilterContext);
+    // Provider-Kinder (statisch leer bis geladen) halten die Section offen — ihr
+    // Match lässt sich hier nicht statisch prüfen; der Knoten selbst self-hidet.
+    if (q !== "" &&
+        !matches(node.label) &&
+        !node.children.some((c) => c.provider === true || subtreeMatches(c, matches))) {
+        return null;
+    }
+    return (_jsxs(SidebarGroup, { children: [_jsx(SidebarGroupLabel, { children: displayLabel }), _jsx(SidebarGroupContent, { children: _jsx(SidebarMenu, { children: node.children.map((child) => (_jsx(NavMenuNode, { node: child, collapsed: collapsed, onToggle: onToggle }, child.qualifiedName))) }) })] }));
+}
+// Ein Menu-Eintrag (Top-Level-Item oder Section-Child). Drei Klick-Modi am
+// EINEN Knoten: `screen` → Route-Link (KumikoLink), `target` → EditorPanel-
+// Dispatch (useDispatchTarget), keins → Container/Provider-Knoten der nur
+// auf-/zuklappt. Provider-Knoten laden ihre Children lazy + SSE-live. Der
+// Collapse-Chevron sitzt als SidebarMenuAction daneben (separater Button,
+// sonst <button> im <a> = invalides HTML); createAction/actions als
+// absolute NodeActions links davon.
+function NavMenuNode({ node, collapsed, onToggle }) {
+    const t = useTranslation();
+    const dispatch = useDispatchTarget();
+    const s = useNavNodeState(node, collapsed);
+    if (s.hidden)
+        return null;
+    const sub = s.isExpanded ? (_jsxs(SidebarMenuSub, { children: [_jsx(ProviderStatus, { loading: s.providerLoading, error: s.providerError }), s.childNodes.map((child) => (_jsx(NavSubNode, { node: child, collapsed: collapsed, onToggle: onToggle }, child.qualifiedName)))] })) : null;
+    const chevron = s.expandable ? (_jsx(SidebarMenuAction, { "aria-label": t(s.isExpanded ? "kumiko.nav.collapse" : "kumiko.nav.expand"), "aria-expanded": s.isExpanded, onClick: () => onToggle(node.qualifiedName), children: s.isExpanded ? _jsx(ChevronDown, {}) : _jsx(ChevronRight, {}) })) : null;
+    if (node.screen !== undefined) {
+        const screenId = lastSegment(node.screen);
+        return (_jsxs(SidebarMenuItem, { children: [_jsx(SidebarMenuButton, { asChild: true, isActive: s.active, tooltip: s.displayLabel, children: _jsxs(KumikoLink, { to: { ...(s.workspaceId !== undefined && { workspaceId: s.workspaceId }), screenId }, ...(s.ariaCurrent && { "aria-current": "page" }), children: [_jsx(NavLeadingIcon, { node: node, active: s.active, label: s.displayLabel }), _jsx("span", { className: "min-w-0 truncate group-data-[collapsible=icon]:hidden", title: s.displayLabel, children: s.displayLabel }), _jsx(NavBadge, { node: node })] }) }), _jsx(NodeActions, { node: node, expandable: s.expandable, workspaceId: s.workspaceId }), chevron, sub] }));
+    }
+    if (node.target !== undefined) {
+        const target = node.target;
+        return (_jsxs(SidebarMenuItem, { children: [_jsxs(SidebarMenuButton, { isActive: s.active, tooltip: s.displayLabel, onClick: () => dispatch(target), children: [_jsx(NavLeadingIcon, { node: node, active: s.active, label: s.displayLabel }), _jsx("span", { className: "min-w-0 truncate group-data-[collapsible=icon]:hidden", title: s.displayLabel, children: s.displayLabel }), _jsx(NavBadge, { node: node })] }), _jsx(NodeActions, { node: node, expandable: s.expandable, workspaceId: s.workspaceId }), chevron, sub] }));
+    }
+    return (_jsxs(SidebarMenuItem, { children: [_jsxs(SidebarMenuButton, { onClick: () => {
+                    if (s.expandable)
+                        onToggle(node.qualifiedName);
+                }, ...(s.expandable && { "aria-expanded": s.isExpanded }), children: [_jsx(NavLeadingIcon, { node: node, active: false, expanded: s.isExpanded, label: s.displayLabel }), _jsx("span", { className: "truncate group-data-[collapsible=icon]:hidden", title: s.displayLabel, children: s.displayLabel }), s.expandable &&
+                        (s.isExpanded ? (_jsx(ChevronDown, { className: "ml-auto" })) : (_jsx(ChevronRight, { className: "ml-auto" })))] }), _jsx(NodeActions, { node: node, expandable: s.expandable, workspaceId: s.workspaceId }), sub] }));
+}
+// Verschachtelte Einträge (innerhalb SidebarMenuSub). Gleiche drei Klick-Modi
+// wie NavMenuNode, nur mit den Sub-Primitives. Folder-/Container-Knoten (kein
+// screen/target) klappen auf — Provider-Children + tiefere Statics rekursiv.
+// Non-Link-Klickziele brauchen asChild+<button> (SidebarMenuSubButton ist ein
+// <a>); der Chevron sitzt als eigener absoluter Button (kein Button-im-<a>).
+function NavSubNode({ node, collapsed, onToggle }) {
+    const t = useTranslation();
+    const dispatch = useDispatchTarget();
+    const s = useNavNodeState(node, collapsed);
+    if (s.hidden)
+        return null;
+    // Kinder in ein eigenes SidebarMenuSub (<ul>) — ein Sub-Item ist ein <li>,
+    // verschachtelte <li> ohne <ul> dazwischen sind invalides HTML (nested
+    // Content-Ordner: Marketing/ > Block). Der <ul> trägt zugleich die
+    // Einrück-/Border-Stufe pro Tiefe.
+    const deeper = s.isExpanded ? (_jsxs(SidebarMenuSub, { children: [_jsx(ProviderStatus, { loading: s.providerLoading, error: s.providerError }), s.childNodes.map((child) => (_jsx(NavSubNode, { node: child, collapsed: collapsed, onToggle: onToggle }, child.qualifiedName)))] })) : null;
+    const chevron = s.expandable ? (_jsx("button", { type: "button", "aria-label": t(s.isExpanded ? "kumiko.nav.collapse" : "kumiko.nav.expand"), "aria-expanded": s.isExpanded, onClick: (e) => {
+            e.stopPropagation();
+            onToggle(node.qualifiedName);
+        }, className: "absolute top-1 right-1 flex size-5 items-center justify-center rounded-md text-sidebar-muted hover:bg-sidebar-accent hover:text-sidebar-accent-foreground", children: s.isExpanded ? _jsx(ChevronDown, { className: "size-3.5" }) : _jsx(ChevronRight, { className: "size-3.5" }) })) : null;
+    if (node.screen !== undefined) {
+        const screenId = lastSegment(node.screen);
+        return (_jsxs(SidebarMenuSubItem, { children: [_jsx(SidebarMenuSubButton, { asChild: true, isActive: s.active, children: _jsxs(KumikoLink, { to: { ...(s.workspaceId !== undefined && { workspaceId: s.workspaceId }), screenId }, ...(s.ariaCurrent && { "aria-current": "page" }), children: [_jsx(NavLeadingIcon, { node: node, active: s.active, label: s.displayLabel }), _jsx("span", { className: "min-w-0 truncate group-data-[collapsible=icon]:hidden", title: s.displayLabel, children: s.displayLabel }), _jsx(NavBadge, { node: node })] }) }), _jsx(NodeActions, { node: node, expandable: s.expandable, workspaceId: s.workspaceId }), chevron, deeper] }));
+    }
+    if (node.target !== undefined) {
+        const target = node.target;
+        return (_jsxs(SidebarMenuSubItem, { children: [_jsx(SidebarMenuSubButton, { asChild: true, isActive: s.active, children: _jsxs("button", { type: "button", onClick: () => dispatch(target), children: [_jsx(NavLeadingIcon, { node: node, active: s.active, label: s.displayLabel }), _jsx("span", { className: "min-w-0 truncate group-data-[collapsible=icon]:hidden", title: s.displayLabel, children: s.displayLabel }), _jsx(NavBadge, { node: node })] }) }), _jsx(NodeActions, { node: node, expandable: s.expandable, workspaceId: s.workspaceId }), chevron, deeper] }));
+    }
+    return (_jsxs(SidebarMenuSubItem, { children: [_jsx(SidebarMenuSubButton, { asChild: true, children: _jsxs("button", { type: "button", onClick: () => {
+                        if (s.expandable)
+                            onToggle(node.qualifiedName);
+                    }, children: [_jsx(NavLeadingIcon, { node: node, active: false, expanded: s.isExpanded, label: s.displayLabel }), _jsx("span", { className: "truncate group-data-[collapsible=icon]:hidden", title: s.displayLabel, children: s.displayLabel })] }) }), _jsx(NodeActions, { node: node, expandable: s.expandable, workspaceId: s.workspaceId }), chevron, deeper] }));
+}
+// Backwards-kompatibler Single-Feature-Builder. Convenience-Wrapper um
+// buildNavRegistrySliceForApp — bestehende Tests die direkt mit
+// FeatureSchema rufen brauchen keine Änderung.
+export function buildNavRegistrySlice(schema, allowedNavQns) {
+    return buildNavRegistrySliceForApp(toAppSchema(schema), allowedNavQns);
+}
+// Multi-Feature-Variante. Iteriert alle Features, qualifiziert pro
+// Feature mit dem eigenen featureName. Reihenfolge: Features in der
+// AppSchema-Ordnung, navs in der vom Feature deklarierten Reihenfolge.
+//
+// Cross-Feature-Workspaces sind hier nativ unterstützt — `navMembers`
+// referenzieren QNs, der Filter trifft die jeweils richtigen Einträge
+// egal in welchem Feature sie deklariert sind.
+export function buildNavRegistrySliceForApp(app, allowedNavQns) {
+    const screenAccessByQn = buildScreenAccessMap(app);
+    const qualified = [];
+    for (const feature of app.features) {
+        for (const n of feature.navs ?? []) {
+            const screen = n.screen !== undefined ? qualifyScreenId(feature.featureName, n.screen) : undefined;
+            // Nav entries without their own `access` inherit the referenced
+            // screen's access rule — otherwise a broader workspace/parent access
+            // lets a role see a nav entry whose target screen 403s them (#1099).
+            // An explicit `n.access` always wins; inheritance only fills the gap.
+            const inheritedAccess = n.access ?? (screen !== undefined ? screenAccessByQn.get(screen) : undefined);
+            qualified.push({
+                ...n,
+                id: qualifyNavId(feature.featureName, n.id),
+                ...(n.parent !== undefined && { parent: qualifyNavId(feature.featureName, n.parent) }),
+                ...(screen !== undefined && { screen }),
+                ...(inheritedAccess !== undefined && { access: inheritedAccess }),
+            });
+        }
+    }
+    const existing = dropNavsWithNonexistentParent(qualified);
+    // Workspace filter: drop nav entries whose qualified id isn't in the
+    // allow-set. A child whose parent gets dropped surfaces as a top-level
+    // entry — the workspace owner should list parents explicitly if they
+    // want the grouping preserved.
+    const filtered = allowedNavQns !== undefined ? existing.filter((n) => allowedNavQns.has(n.id)) : existing;
+    const allowedQnSet = new Set(filtered.map((n) => n.id));
+    const topLevel = [];
+    const byParentMap = new Map();
+    for (const nav of filtered) {
+        // Treat the entry as top-level when its parent isn't visible — keeps
+        // children visible after filtering, even if the workspace omits the
+        // parent group from its members list.
+        const hasVisibleParent = nav.parent !== undefined && allowedQnSet.has(nav.parent);
+        if (hasVisibleParent && nav.parent !== undefined) {
+            const list = byParentMap.get(nav.parent) ?? [];
+            list.push(nav);
+            byParentMap.set(nav.parent, list);
+        }
+        else {
+            topLevel.push(nav);
+        }
+    }
+    return {
+        topLevel,
+        byParent: (parent) => byParentMap.get(parent) ?? [],
+    };
+}
+// A parent absent from the (role-projected) schema is not a workspace
+// filter result: the child must not leak to the top level. Transitive.
+// Parents removed by an allowlist (filterAppSchemaNavsByAllowlist) are not
+// absent here: that helper already lifted their children to the top level.
+function dropNavsWithNonexistentParent(navs) {
+    let current = [...navs];
+    for (;;) {
+        const ids = new Set(current.map((n) => n.id));
+        const kept = current.filter((n) => n.parent === undefined || ids.has(n.parent));
+        if (kept.length === current.length)
+            return current;
+        current = kept;
+    }
+}
+// Exported (not part of the package's public index.ts surface) so other
+// modules under layout/ — e.g. filter-app-schema-navs.ts — qualify nav ids
+// the same way instead of keeping a second copy in sync.
+export function qualifyNavId(feature, id) {
+    return id.includes(":nav:") ? id : `${feature}:nav:${id}`;
+}
+function qualifyScreenId(feature, id) {
+    return id.includes(":screen:") ? id : `${feature}:screen:${id}`;
+}
+function buildScreenAccessMap(app) {
+    const map = new Map();
+    for (const feature of app.features) {
+        for (const s of feature.screens) {
+            map.set(qualifyScreenId(feature.featureName, s.id), s.access);
+        }
+    }
+    return map;
+}
+// `lastSegment` lebt jetzt in @cosmicdrift/kumiko-renderer (./app/qn) — eine
+// Quelle, beide Pakete teilen sie.
+export { lastSegment };

package/dist/web/layout/page-header-slot.d.ts

@@ -0,0 +1,25 @@
+import { type ReactNode } from "react";
+import { type ActionMenuItemSpec } from "../../index.ts";
+type SlotElement = HTMLElement | null;
+export type PageHeaderSlot = {
+    readonly statusElement: SlotElement;
+    readonly actionsElement: SlotElement;
+    readonly setStatusElement: (node: SlotElement) => void;
+    readonly setActionsElement: (node: SlotElement) => void;
+    readonly title: string | undefined;
+    readonly setTitle: (title: string | undefined) => void;
+    readonly recordTitle: string | undefined;
+    readonly setRecordTitle: (recordTitle: string | undefined) => void;
+    readonly breadcrumbHidden: boolean;
+    readonly setBreadcrumbHidden: (hidden: boolean) => void;
+    readonly breadcrumbScreenId: string | undefined;
+    readonly setBreadcrumbScreenId: (screenId: string | undefined) => void;
+    readonly overflowItems: readonly ActionMenuItemSpec[] | undefined;
+    readonly setOverflowItems: (items: readonly ActionMenuItemSpec[] | undefined) => void;
+};
+export declare function usePageHeaderSlot(): PageHeaderSlot | null;
+/** Shells wrap ShellHeader and the content area in it. */
+export declare function PageHeaderSlotProvider({ children }: {
+    readonly children: ReactNode;
+}): ReactNode;
+export {};

package/dist/web/layout/page-header-slot.js

@@ -0,0 +1,50 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// Two portal targets (status, actions) plus a title override and a record title inside the
+// ShellHeader, filled by the PageHeader primitive of whatever screen renders
+// below it.
+//
+// Why a slot: the header sits above the content and is owned by the shell; a
+// screen can only reach it through a portal. Same inversion as SidebarPanel.
+import { createContext, useContext, useMemo, useState } from "react";
+import { PageHeaderCompactProvider, PageHeaderSlotAvailableProvider, } from "../../index.js";
+import { useIsNarrowViewport } from "../primitives/use-narrow-viewport.js";
+const PageHeaderSlotContext = createContext(null);
+export function usePageHeaderSlot() {
+    return useContext(PageHeaderSlotContext);
+}
+/** Shells wrap ShellHeader and the content area in it. */
+export function PageHeaderSlotProvider({ children }) {
+    const [statusElement, setStatusElement] = useState(null);
+    const [actionsElement, setActionsElement] = useState(null);
+    const [title, setTitle] = useState(undefined);
+    const [recordTitle, setRecordTitle] = useState(undefined);
+    const [breadcrumbHidden, setBreadcrumbHidden] = useState(false);
+    const [breadcrumbScreenId, setBreadcrumbScreenId] = useState(undefined);
+    const [overflowItems, setOverflowItems] = useState(undefined);
+    const compact = useIsNarrowViewport();
+    const value = useMemo(() => ({
+        statusElement,
+        actionsElement,
+        setStatusElement,
+        setActionsElement,
+        title,
+        setTitle,
+        recordTitle,
+        setRecordTitle,
+        breadcrumbHidden,
+        setBreadcrumbHidden,
+        breadcrumbScreenId,
+        setBreadcrumbScreenId,
+        overflowItems,
+        setOverflowItems,
+    }), [
+        statusElement,
+        actionsElement,
+        title,
+        recordTitle,
+        breadcrumbHidden,
+        breadcrumbScreenId,
+        overflowItems,
+    ]);
+    return (_jsx(PageHeaderSlotContext.Provider, { value: value, children: _jsx(PageHeaderSlotAvailableProvider, { value: true, children: _jsx(PageHeaderCompactProvider, { value: compact, children: children }) }) }));
+}

package/dist/web/layout/profile-menu.d.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from "react";
+import { type MenuItemDef } from "../primitives/action-menu.tsx";
+export type ProfileMenuItem = MenuItemDef;
+export type ProfileMenuProps = {
+    readonly user: {
+        readonly id: string;
+        /** Display-Name oder Email — Quelle für Initials. */
+        readonly label: string;
+    };
+    readonly items: readonly ProfileMenuItem[];
+    readonly testId?: string;
+};
+export declare function ProfileMenu({ user, items, testId }: ProfileMenuProps): ReactNode;

package/dist/web/layout/profile-menu.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { ActionMenu } from "../primitives/action-menu.js";
+import { Avatar } from "./avatar.js";
+export function ProfileMenu({ user, items, testId }) {
+    return (_jsx(ActionMenu, { trigger: _jsx(Avatar, { id: user.id, label: user.label, size: "md" }), triggerLabel: `Open ${user.label} menu`, items: items, align: "end", testId: testId ?? "profile-menu-trigger" }));
+}

package/dist/web/layout/shell-breadcrumb.d.ts

@@ -0,0 +1,11 @@
+import type { ScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+export type BreadcrumbCrumb = {
+    readonly label: string;
+    readonly screenId?: string;
+};
+export declare function screenTitleKey(screenShortId: string): string;
+/** The short id of {screenId}'s parent list screen, resolved via the same
+ *  logic as `resolveDetailBreadcrumb` — `undefined` when nothing resolves
+ *  (unknown screen, or no explicit/heuristic parent). */
+export declare function resolveParentScreenId(screens: readonly ScreenDefinition[], screenId: string): string | undefined;
+export declare function resolveDetailBreadcrumb(screens: readonly ScreenDefinition[], detailScreenId: string, t: (key: string) => string): readonly BreadcrumbCrumb[] | undefined;