@cosmicdrift/kumiko-renderer 0.374.0 → 0.377.0

package/dist/web/layout/shell-breadcrumb.js

@@ -0,0 +1,34 @@
+import { resolveNavParentScreen } from "@cosmicdrift/kumiko-framework/ui-types";
+import { lastSegment } from "../../index.js";
+export function screenTitleKey(screenShortId) {
+    return `screen:${screenShortId}.title`;
+}
+// Delegates to resolveNavParentScreen, supplying the feature-qualified-id
+// normalization the client-side schema needs.
+function resolveParentScreen(screens, detail) {
+    return resolveNavParentScreen(screens, detail, (s) => lastSegment(s.id));
+}
+/** 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 function resolveParentScreenId(screens, screenId) {
+    const detail = screens.find((s) => lastSegment(s.id) === screenId);
+    if (detail === undefined)
+        return undefined;
+    const parent = resolveParentScreen(screens, detail);
+    return parent !== undefined ? lastSegment(parent.id) : undefined;
+}
+export function resolveDetailBreadcrumb(screens, detailScreenId, t) {
+    const detail = screens.find((s) => lastSegment(s.id) === detailScreenId);
+    if (detail === undefined)
+        return undefined;
+    const list = resolveParentScreen(screens, detail);
+    if (list === undefined) {
+        return [{ label: t(screenTitleKey(detailScreenId)) }];
+    }
+    const listId = lastSegment(list.id);
+    return [
+        { label: t(screenTitleKey(listId)), screenId: listId },
+        { label: t(screenTitleKey(detailScreenId)) },
+    ];
+}

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

@@ -0,0 +1,12 @@
+import { type ReactNode } from "react";
+import type { AppSchema, FeatureSchema } from "../../index.ts";
+type ShellHeaderUser = {
+    readonly id: string;
+    readonly roles: readonly string[];
+};
+export declare function ShellHeader({ schema, user, headerActions, }: {
+    readonly schema: AppSchema | FeatureSchema;
+    readonly user?: ShellHeaderUser;
+    readonly headerActions?: ReactNode;
+}): ReactNode;
+export {};

package/dist/web/layout/shell-header.js

@@ -0,0 +1,159 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// ShellHeader — inset header bar for sidebar-based shells: SidebarTrigger
+// (rail/mobile-sheet toggle), breadcrumb of the active screen, optional
+// right-aligned headerActions. Shared by DefaultAppShell and WorkspaceShell so
+// both carry the same header (h-14, also with a collapsed icon rail).
+//
+// The `data-kumiko-layout="shell-header"` marker drives `--shell-header-height`
+// in styles.css (:has() selector) — the single source for the header height
+// that Drawer's `belowHeader` prop also reads.
+import { MoreHorizontal } from "lucide-react";
+import { Fragment, useEffect, useId, useMemo, useRef, useState, } from "react";
+import { resolveNavigation } from "../../headless/index.js";
+import { toAppSchema, useNav, usePageHeaderCompact, useTranslation, } from "../../index.js";
+import { Icon, NAV_ICONS } from "../icons.js";
+import { cn } from "../lib/cn.js";
+import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator, } from "../ui/breadcrumb.js";
+import { SidebarTrigger } from "../ui/sidebar.js";
+import { HeaderOverflowMenuContext, headerOverflowMenuItemClass } from "./header-overflow-menu.js";
+import { buildNavRegistrySliceForApp, lastSegment } from "./nav-tree.js";
+import { usePageHeaderSlot } from "./page-header-slot.js";
+import { resolveDetailBreadcrumb, screenTitleKey, } from "./shell-breadcrumb.js";
+export function ShellHeader({ schema, user, headerActions, }) {
+    const nav = useNav();
+    const t = useTranslation();
+    const appSchema = toAppSchema(schema);
+    const tree = useMemo(() => {
+        const source = buildNavRegistrySliceForApp(appSchema);
+        return resolveNavigation({ source, ...(user !== undefined && { user }) });
+    }, [appSchema, user]);
+    const allScreens = useMemo(() => appSchema.features.flatMap((f) => f.screens), [appSchema.features]);
+    const slot = usePageHeaderSlot();
+    const standInScreenId = slot?.breadcrumbScreenId;
+    const screenId = standInScreenId ?? nav.route?.screenId;
+    const entityId = standInScreenId !== undefined ? undefined : nav.route?.entityId;
+    const crumbs = useMemo(() => {
+        if (screenId === undefined)
+            return undefined;
+        // A nav entry on an edit screen means "create"; an existing record (entityId in
+        // the route) is reached from the list, so the list crumb wins over the nav label.
+        if (entityId !== undefined) {
+            const detailCrumbs = resolveDetailBreadcrumb(allScreens, screenId, t);
+            if (detailCrumbs !== undefined && detailCrumbs.length > 1)
+                return detailCrumbs;
+        }
+        const navLabel = activeNavLabel(tree, screenId, (k) => t(k));
+        if (navLabel !== undefined)
+            return [{ label: navLabel }];
+        return resolveDetailBreadcrumb(allScreens, screenId, t);
+    }, [allScreens, screenId, entityId, t, tree]);
+    const setStatusElement = slot?.setStatusElement;
+    const setActionsElement = slot?.setActionsElement;
+    const titleOverride = slot?.title;
+    const recordTitle = slot?.recordTitle;
+    const compact = usePageHeaderCompact();
+    const overflowItems = slot?.overflowItems ?? [];
+    const hasOverflow = compact && (overflowItems.length > 0 || headerActions !== undefined);
+    // A stand-in without a translated title must not surface the raw i18n key.
+    const standInUntitled = standInScreenId !== undefined && crumbs?.at(-1)?.label === screenTitleKey(standInScreenId);
+    const shownCrumbs = (slot?.breadcrumbHidden === true && standInScreenId === undefined) || standInUntitled
+        ? undefined
+        : crumbs !== undefined && recordTitle !== undefined && crumbs.length > 0
+            ? [...crumbs.slice(0, -1), { label: recordTitle }, ...crumbs.slice(-1)]
+            : crumbs;
+    return (_jsxs("header", { "data-kumiko-layout": "shell-header", className: cn("flex h-14 shrink-0 items-center gap-3 border-b border-border pl-1.5 pr-3 md:pl-4 md:pr-6", compact && "relative"), children: [_jsxs("div", { className: cn("flex min-w-0 items-center gap-3", compact && "flex-1"), children: [_jsx(SidebarTrigger, { label: t("kumiko.sidebar.toggle") }), shownCrumbs !== undefined && shownCrumbs.length > 0 && (_jsx(Breadcrumb, { className: "min-w-0", "aria-label": t("kumiko.breadcrumb.label"), children: _jsx(BreadcrumbList, { className: "flex-nowrap gap-1.5 sm:gap-1.5", children: shownCrumbs.map((crumb, index) => {
+                                const screenId = crumb.screenId;
+                                const isLast = index === shownCrumbs.length - 1;
+                                return (_jsxs(Fragment, { children: [index > 0 && (_jsx(BreadcrumbSeparator, { className: "hidden text-muted-foreground sm:inline-flex [&>svg]:size-3.5" })), _jsx(BreadcrumbItem, { className: cn("min-w-0", !isLast && "hidden sm:inline-flex"), children: screenId !== undefined && !isLast ? (_jsx(BreadcrumbLink, { href: "#", className: "whitespace-nowrap text-foreground-secondary", onClick: (e) => {
+                                                    e.preventDefault();
+                                                    nav.navigate({ screenId });
+                                                }, children: crumb.label })) : isLast ? (_jsx("h1", { "aria-current": "page", className: "truncate text-lg font-semibold text-foreground", children: titleOverride ?? crumb.label })) : (_jsx(BreadcrumbPage, { className: "whitespace-nowrap text-foreground-secondary", children: crumb.label })) })] }, screenId ?? crumb.label));
+                            }) }) })), _jsx("div", { ref: setStatusElement, "data-kumiko-layout": "page-header-status", className: cn("flex items-center gap-2 empty:hidden", compact ? "min-w-0 overflow-hidden" : "shrink-0") })] }), _jsxs("div", { className: cn("ml-auto flex items-center gap-2", compact ? "min-w-0 max-w-[60%]" : "min-w-0 max-w-[50%] shrink-0 sm:max-w-none"), children: [_jsx("div", { ref: setActionsElement, "data-kumiko-layout": "page-header-actions", className: cn("flex min-w-0 items-center gap-2 empty:hidden [&_*]:min-w-0 [&_*]:max-w-full [&_button]:overflow-hidden [&_button]:whitespace-nowrap", compact && "overflow-hidden") }), !compact && headerActions !== undefined && (_jsx("div", { "data-kumiko-layout": "header-actions", className: "flex items-center gap-2", children: headerActions })), hasOverflow && _jsx(HeaderOverflow, { items: overflowItems, headerActions: headerActions })] })] }));
+}
+// A hand-rolled menu instead of Radix DropdownMenu: app headerActions are opaque
+// nodes with their own popovers, and the panel stays mounted while closed so their
+// effects (shortcut listeners) keep running.
+const MENU_ITEM_SELECTOR = '[role="menuitem"]:not(:disabled)';
+function HeaderOverflow({ items, headerActions, }) {
+    const t = useTranslation();
+    const [open, setOpen] = useState(false);
+    const panelId = useId();
+    const triggerRef = useRef(null);
+    const panelRef = useRef(null);
+    useEffect(() => {
+        if (!open)
+            return;
+        panelRef.current?.querySelector(MENU_ITEM_SELECTOR)?.focus();
+        const onKeyDown = (event) => {
+            if (event.key !== "Escape")
+                return;
+            setOpen(false);
+            triggerRef.current?.focus();
+        };
+        const onPointerDown = (event) => {
+            const target = event.target;
+            if (!(target instanceof Node))
+                return;
+            if (panelRef.current?.contains(target) || triggerRef.current?.contains(target))
+                return;
+            setOpen(false);
+        };
+        document.addEventListener("keydown", onKeyDown);
+        document.addEventListener("pointerdown", onPointerDown);
+        return () => {
+            document.removeEventListener("keydown", onKeyDown);
+            document.removeEventListener("pointerdown", onPointerDown);
+        };
+    }, [open]);
+    const onPanelKeyDown = (event) => {
+        // Opaque app headerActions (inputs, plain buttons) keep native Tab/arrow behaviour.
+        if (!(event.target instanceof HTMLElement) ||
+            event.target.getAttribute("role") !== "menuitem") {
+            return;
+        }
+        if (event.key === "Tab") {
+            event.preventDefault();
+            setOpen(false);
+            triggerRef.current?.focus();
+            return;
+        }
+        if (!["ArrowDown", "ArrowUp", "Home", "End"].includes(event.key))
+            return;
+        const menuItems = Array.from(panelRef.current?.querySelectorAll(MENU_ITEM_SELECTOR) ?? []);
+        if (menuItems.length === 0)
+            return;
+        const current = menuItems.indexOf(document.activeElement);
+        const last = menuItems.length - 1;
+        const next = event.key === "Home"
+            ? 0
+            : event.key === "End"
+                ? last
+                : event.key === "ArrowDown"
+                    ? current >= last
+                        ? 0
+                        : current + 1
+                    : current <= 0
+                        ? last
+                        : current - 1;
+        event.preventDefault();
+        menuItems[next]?.focus();
+    };
+    return (_jsxs(_Fragment, { children: [_jsx("button", { ref: triggerRef, type: "button", "aria-label": t("kumiko.page-header.actions"), "aria-haspopup": "menu", "aria-expanded": open, "aria-controls": panelId, "data-testid": "shell-header-overflow-trigger", onClick: () => setOpen((wasOpen) => !wasOpen), className: "inline-flex size-10 shrink-0 items-center justify-center rounded-md border border-input bg-background text-foreground shadow-xs hover:bg-accent focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring", children: _jsx(MoreHorizontal, { className: "size-4", "aria-hidden": "true" }) }), _jsxs("div", { ref: panelRef, id: panelId, role: "menu", "aria-label": t("kumiko.page-header.actions"), hidden: !open, onKeyDown: onPanelKeyDown, "data-testid": "shell-header-overflow", className: "absolute right-2 top-full z-30 mt-1 w-max min-w-[8rem] max-w-[calc(100vw-1rem)] rounded-md border bg-popover p-1 text-popover-foreground shadow-md", children: [items.length > 0 && (_jsx("div", { className: "flex flex-col", children: items.map((item) => (_jsxs("button", { type: "button", role: "menuitem", disabled: item.disabled === true, "data-testid": item.testId ?? `shell-header-overflow-item-${item.id}`, onClick: () => {
+                                setOpen(false);
+                                item.onSelect();
+                            }, className: cn(headerOverflowMenuItemClass, item.variant === "danger" && "text-destructive"), children: [item.icon !== undefined && Object.hasOwn(NAV_ICONS, item.icon) && (_jsx(Icon, { name: item.icon, className: "size-4 shrink-0" })), item.label] }, item.id))) })), items.length > 0 && headerActions !== undefined && (_jsx("hr", { className: "-mx-1 my-1 border-t border-border" })), headerActions !== undefined && (_jsx("div", { "data-kumiko-layout": "header-actions", 
+                        // Stacks direct children only; app wrappers opt in via HeaderActionGroup instead of
+                        // being restyled through a child selector that reaches into their markup.
+                        className: "flex flex-col items-stretch gap-1", onClick: () => setOpen(false), children: _jsx(HeaderOverflowMenuContext.Provider, { value: true, children: headerActions }) }))] })] }));
+}
+function activeNavLabel(nodes, screenId, t) {
+    for (const node of nodes) {
+        if (node.screen !== undefined && lastSegment(node.screen) === screenId) {
+            return node.label.includes(".") || node.label.includes(":") ? t(node.label) : node.label;
+        }
+        const child = activeNavLabel(node.children, screenId, t);
+        if (child !== undefined)
+            return child;
+    }
+    return undefined;
+}

package/dist/web/layout/sidebar-brand.d.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from "react";
+export type SidebarBrandProps = {
+    /** Workspace-/App-Name (fett, erste Zeile). */
+    readonly name: string;
+    /** Zweite Zeile — Plan, Tagline, Tenant (klein, gedimmt). */
+    readonly plan?: string;
+    /** Logo in der Kachel — typisch ein Lucide-Icon. Fehlt es, steht der
+     *  erste Buchstabe des Namens. */
+    readonly logo?: ReactNode;
+    /** Zeigt das ChevronsUpDown-Icon (Aufklapp-Affordance) nur wenn die App den
+     *  Brand tatsächlich in ein Dropdown wrappt. Default false: ohne Dropdown
+     *  ist das Chevron irreführend (suggeriert ein Menü, das nicht aufgeht). */
+    readonly collapsible?: boolean;
+};
+export declare function SidebarBrand({ name, plan, logo, collapsible, }: SidebarBrandProps): ReactNode;

package/dist/web/layout/sidebar-brand.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// SidebarBrand — logo tile, name and subtitle for DefaultAppShell's `brand`
+// slot. Look only, no team-switch dropdown: an app usually has one identity;
+// apps that need switching wrap their own dropdown around it and set
+// `collapsible`.
+import { ChevronsUpDown } from "lucide-react";
+export function SidebarBrand({ name, plan, logo, collapsible = false, }) {
+    return (_jsxs("div", { className: "flex items-center gap-2.5 px-2 pt-1 pb-3 group-data-[collapsible=icon]:justify-center group-data-[collapsible=icon]:px-0", children: [_jsx("div", { className: "flex size-7 shrink-0 items-center justify-center rounded-md bg-sidebar-primary text-sm font-semibold text-sidebar-primary-foreground", children: logo ?? _jsx("span", { children: name.charAt(0) }) }), _jsxs("div", { className: "grid min-w-0 flex-1 text-left leading-tight group-data-[collapsible=icon]:hidden", children: [_jsx("span", { className: "truncate text-sm font-semibold text-sidebar-foreground", children: name }), plan !== undefined && _jsx("span", { className: "truncate text-xs text-sidebar-muted", children: plan })] }), collapsible && (_jsx(ChevronsUpDown, { className: "ml-auto size-4 text-sidebar-muted group-data-[collapsible=icon]:hidden" }))] }));
+}

package/dist/web/layout/sidebar-panel.d.ts

@@ -0,0 +1,41 @@
+import { type ReactNode } from "react";
+type SlotElement = HTMLElement | null;
+type SidebarPanelSlot = {
+    readonly element: SlotElement;
+    /** Tells the shell state whether a screen is currently claiming the space. */
+    readonly setOccupied: (occupied: boolean) => void;
+};
+export declare const SidebarPanelProvider: import("react").Provider<SidebarPanelSlot | null>;
+/** Shells only — screens use `SidebarPanel`. */
+export declare function useSidebarPanelSlot(): SidebarPanelSlot | null;
+export type SidebarPanelProps = {
+    readonly children: ReactNode;
+    /** Initial width in px. After the first drag the stored width wins. */
+    readonly defaultWidth?: number;
+    readonly minWidth?: number;
+    readonly maxWidth?: number;
+    /** localStorage key for the dragged width. Without a key nothing is stored —
+     *  two screens with their own list should not overwrite each other's width. */
+    readonly storageKey?: string;
+    readonly className?: string;
+    /** "nav" (default) matches the shell's own sidebar chrome. "surface" reads
+     *  as page content instead of navigation — for a list that carries the
+     *  screen's own content colors (e.g. status-tinted rows). */
+    readonly tone?: "nav" | "surface";
+};
+/** Renders its children into the second sidebar column when the shell offers
+ *  one. When it does not (public surface, tests, an older shell) the children
+ *  land in place — the screen stays usable instead of losing its list.
+ *
+ *  The width drags like in any mail client: the handle sits on the divider and
+ *  the result survives a reload (with `storageKey`). */
+export declare function SidebarPanel({ children, defaultWidth, minWidth, maxWidth, storageKey, className, tone, }: SidebarPanelProps): ReactNode;
+/** Shell-side counterpart: holds the slot element and the occupied state. Its
+ *  own hook so both shells (WorkspaceShell, DefaultAppShell) share one wiring
+ *  instead of getting the same thing half right twice. */
+export declare function useSidebarPanelHost(): {
+    readonly occupied: boolean;
+    readonly value: SidebarPanelSlot;
+    readonly ref: (node: SlotElement) => void;
+};
+export {};

package/dist/web/layout/sidebar-panel.js

@@ -0,0 +1,107 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// A second sidebar column for screens that need a list next to the navigation
+// rather than inside the content — the shadcn `sidebar-09` pattern (mail
+// client) against the `sidebar-07` the shell otherwise runs.
+//
+// Why a slot and not a screen layout: the area sits outside the `SidebarInset`
+// and therefore above the ShellHeader. A screen renders by definition *into*
+// the content, below the header, and cannot reach that spot from there. The
+// slot inverts the direction: the shell holds the space, the screen fills it
+// through a portal and stays an ordinary screen otherwise.
+//
+// With no screen filling it the shell does not render the space at all — no
+// empty strip on every other screen.
+import { createContext, useCallback, useContext, useEffect, useRef, useState, } from "react";
+import { createPortal } from "react-dom";
+import { clamp } from "../lib/clamp.js";
+import { cn } from "../lib/cn.js";
+const SidebarPanelContext = createContext(null);
+export const SidebarPanelProvider = SidebarPanelContext.Provider;
+/** Shells only — screens use `SidebarPanel`. */
+export function useSidebarPanelSlot() {
+    return useContext(SidebarPanelContext);
+}
+const DEFAULT_WIDTH = 340;
+const DEFAULT_MIN = 260;
+const DEFAULT_MAX = 640;
+function readStoredWidth(key) {
+    if (key === undefined || typeof window === "undefined")
+        return null;
+    const raw = window.localStorage.getItem(key);
+    if (raw === null)
+        return null;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+/** Renders its children into the second sidebar column when the shell offers
+ *  one. When it does not (public surface, tests, an older shell) the children
+ *  land in place — the screen stays usable instead of losing its list.
+ *
+ *  The width drags like in any mail client: the handle sits on the divider and
+ *  the result survives a reload (with `storageKey`). */
+export function SidebarPanel({ children, defaultWidth = DEFAULT_WIDTH, minWidth = DEFAULT_MIN, maxWidth = DEFAULT_MAX, storageKey, className, tone = "nav", }) {
+    const slot = useSidebarPanelSlot();
+    const setOccupied = slot?.setOccupied;
+    const [width, setWidth] = useState(() => clamp(readStoredWidth(storageKey) ?? defaultWidth, minWidth, maxWidth));
+    const dragging = useRef(false);
+    useEffect(() => {
+        if (setOccupied === undefined)
+            return;
+        setOccupied(true);
+        return () => setOccupied(false);
+    }, [setOccupied]);
+    // Listeners on window, not on the handle: a fast drag leaves the 4px strip
+    // between two frames, and a handler on the element would lose the drag there.
+    useEffect(() => {
+        const onMove = (event) => {
+            if (!dragging.current)
+                return;
+            event.preventDefault();
+            setWidth(clamp(event.clientX, minWidth, maxWidth));
+        };
+        const onUp = () => {
+            if (!dragging.current)
+                return;
+            dragging.current = false;
+            document.body.style.removeProperty("cursor");
+            document.body.style.removeProperty("user-select");
+        };
+        window.addEventListener("pointermove", onMove);
+        window.addEventListener("pointerup", onUp);
+        return () => {
+            window.removeEventListener("pointermove", onMove);
+            window.removeEventListener("pointerup", onUp);
+        };
+    }, [minWidth, maxWidth]);
+    useEffect(() => {
+        if (storageKey === undefined || typeof window === "undefined")
+            return;
+        window.localStorage.setItem(storageKey, String(width));
+    }, [storageKey, width]);
+    const startDrag = useCallback((event) => {
+        event.preventDefault();
+        dragging.current = true;
+        // Set globally while dragging: otherwise the cursor flickers as soon as the
+        // pointer sits over the list instead of the handle, and a drag selects the
+        // row text on the way.
+        document.body.style.setProperty("cursor", "col-resize");
+        document.body.style.setProperty("user-select", "none");
+    }, []);
+    const content = (_jsxs("div", { "data-kumiko-layout": "sidebar-panel-body", className: cn("relative flex h-full shrink-0 flex-col border-r", tone === "surface" ? "border-border bg-muted" : "border-sidebar-border bg-sidebar", className), style: { width: `${width}px` }, children: [children, _jsx("div", { "data-kumiko-layout": "sidebar-panel-handle", onPointerDown: startDrag, className: cn("absolute inset-y-0 right-0 w-1 cursor-col-resize bg-transparent transition-colors", tone === "surface" ? "hover:bg-border" : "hover:bg-sidebar-border") })] }));
+    if (slot?.element == null) {
+        return content;
+    }
+    return createPortal(content, slot.element);
+}
+/** Shell-side counterpart: holds the slot element and the occupied state. Its
+ *  own hook so both shells (WorkspaceShell, DefaultAppShell) share one wiring
+ *  instead of getting the same thing half right twice. */
+export function useSidebarPanelHost() {
+    const [element, setElement] = useState(null);
+    const [occupied, setOccupied] = useState(false);
+    return {
+        occupied,
+        value: { element, setOccupied },
+        ref: setElement,
+    };
+}

package/dist/web/layout/sidebar-user.d.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from "react";
+export type SidebarUserProps = {
+    readonly name: string;
+    readonly email?: string;
+    /** Avatar-URL. Fehlt sie, stehen die Initialen aus dem Namen. */
+    readonly avatar?: string;
+};
+export declare function SidebarUser({ name, email, avatar }: SidebarUserProps): ReactNode;

package/dist/web/layout/sidebar-user.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// SidebarUser — der NavUser-Footer aus shadcns sidebar-07: Avatar + Name +
+// Email + ChevronsUpDown. App-Author reicht ihn als `sidebarFooter` an
+// DefaultAppShell. Reiner Look (kein Account-Dropdown) — wer ein User-Menü
+// will, wrappt ihn in einen DropdownMenu.
+import { ChevronsUpDown } from "lucide-react";
+import { Avatar, AvatarFallback, AvatarImage } from "../ui/avatar.js";
+import { SidebarMenu, SidebarMenuButton, SidebarMenuItem } from "../ui/sidebar.js";
+function initials(name) {
+    const parts = name.trim().split(/\s+/);
+    const first = parts[0]?.charAt(0) ?? "";
+    const last = parts.length > 1 ? (parts[parts.length - 1]?.charAt(0) ?? "") : "";
+    return (first + last).toUpperCase() || name.slice(0, 2).toUpperCase();
+}
+export function SidebarUser({ name, email, avatar }) {
+    return (_jsx(SidebarMenu, { children: _jsx(SidebarMenuItem, { children: _jsxs(SidebarMenuButton, { size: "lg", className: "data-[state=open]:bg-sidebar-accent data-[state=open]:text-sidebar-accent-foreground", children: [_jsxs(Avatar, { className: "size-7 bg-sidebar-accent", children: [avatar !== undefined && _jsx(AvatarImage, { src: avatar, alt: name }), _jsx(AvatarFallback, { className: "bg-sidebar-accent text-xs font-medium text-sidebar-accent-foreground", children: initials(name) })] }), _jsxs("div", { className: "grid flex-1 text-left leading-tight", children: [_jsx("span", { className: "truncate font-medium text-sidebar-foreground", children: name }), email !== undefined && (_jsx("span", { className: "truncate text-xs text-sidebar-muted", children: email }))] }), _jsx(ChevronsUpDown, { className: "ml-auto size-4 text-sidebar-muted" })] }) }) }));
+}

package/dist/web/layout/sidebar.d.ts

@@ -0,0 +1,17 @@
+import type { ReactNode } from "react";
+export type SidebarProps = {
+    /** Header-Bereich oben — typisch Workspace-Avatar + Name + Badge.
+     *  Lebt VOR dem scroll-area, bleibt sichtbar wenn das nav scrollt. */
+    readonly header?: ReactNode;
+    /** Action-Cluster zwischen Header und Nav — typisch "+ Neu" Button
+     *  und Search-Icon. Linear-Pattern: prominent, nicht im scroll-area. */
+    readonly actions?: ReactNode;
+    /** NavTree + freie Sections (z.B. "Your teams" Header + Sub-Items).
+     *  Scrollt eigenständig wenn der Inhalt zu lang wird. */
+    readonly children: ReactNode;
+    /** Footer-Bereich unten — typisch Invite-Link, Help, Plan-Banner.
+     *  Klebt am unteren Rand via mt-auto. */
+    readonly footer?: ReactNode;
+    readonly testId?: string;
+};
+export declare function Sidebar({ header, actions, children, footer, testId }: SidebarProps): ReactNode;

package/dist/web/layout/sidebar.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function Sidebar({ header, actions, children, footer, testId }) {
+    // Linear-Pattern: 4 vertikale Bereiche
+    //   1. Header (Workspace-Identity)
+    //   2. Actions (Quick-Buttons, nicht-scrollend)
+    //   3. Nav-Scroll-Area (NavTree, scrollt wenn nötig)
+    //   4. Footer (klebt unten via mt-auto)
+    // bg-muted/40 + border-r für visuelle Distinction zur Main-Area;
+    // tighter padding (p-3) und kompakte gap-0.5 zwischen Items.
+    return (_jsxs("aside", { "data-testid": testId, "data-kumiko-layout": "sidebar", className: "hidden md:flex w-60 flex-shrink-0 bg-transparent flex-col text-sm", children: [header !== undefined && (_jsx("div", { "data-kumiko-layout": "sidebar-header", className: "h-12 flex items-center px-3 border-b border-border/50", children: header })), actions !== undefined && (_jsx("div", { "data-kumiko-layout": "sidebar-actions", className: "px-3 py-2 border-b border-border/50 flex flex-row items-center gap-1", children: actions })), _jsx("div", { "data-kumiko-layout": "sidebar-nav", className: "px-3 py-2 flex flex-col gap-0.5 overflow-auto flex-1", children: children }), footer !== undefined && (_jsx("div", { "data-kumiko-layout": "sidebar-footer", className: "px-3 py-2 border-t mt-auto flex flex-col gap-1 text-xs text-muted-foreground", children: footer }))] }));
+}

package/dist/web/layout/target-resolver-stub.d.ts

@@ -0,0 +1,13 @@
+import type { TargetRef } from "@cosmicdrift/kumiko-framework/engine";
+type DispatchListener = (target: TargetRef) => void;
+export declare function dispatchTarget(target: TargetRef): void;
+/** Test-Hook: Exklusiver Spy. Returnt cleanup. */
+export declare function setDispatchListener(fn: DispatchListener): () => void;
+/** Production-Subscriber registrieren. Returnt unsubscribe. Läuft nur
+ *  wenn kein Test-Listener aktiv (Test-Isolation). */
+export declare function subscribeTargetDispatches(fn: DispatchListener): () => void;
+/** V.1.4b: empfohlener Production-Dispatch. Schreibt target in
+ *  nav.searchParams (URL-State, F5-fähig) UND ruft dispatchTarget für
+ *  Test-Listener + legacy-Subscribers. */
+export declare function useDispatchTarget(): (target: TargetRef) => void;
+export {};

package/dist/web/layout/target-resolver-stub.js

@@ -0,0 +1,61 @@
+// TargetResolver — V.1.2: Multi-Listener-TargetDispatch mit Test-Hook.
+// V.1.4b: URL-State-Bridge via useDispatchTarget-Hook. Production schreibt
+// target in nav.searchParams (F5-recovery); Subscribe-Stream bleibt für
+// Test-Hooks (setDispatchListener) und Apps die kein NavProvider haben.
+//
+// Dispatch-Priority (V.1.2):
+//   1. Test-Listener (setDispatchListener) — exklusiv, kein Production-
+//      Subscriber läuft während Tests (Test-Isolation).
+//   2. Production-Subscriber (subscribeTargetDispatches) — alle
+//      registrierten Production-Subscriber.
+//   3. Kein Test-Listener + keine Subscriber → console.debug fallback
+//      (damit unhandled Klicks sichtbar bleiben).
+//
+// **useDispatchTarget (V.1.4b)** ist der empfohlene Production-Pfad.
+// NavTree ruft den Hook im Click-Handler eines target-Knotens — er schreibt
+// die URL via nav.setSearchParams UND ruft den globalen dispatchTarget für
+// Test-Listener-Kompatibilität.
+import { useCallback } from "react";
+import { useNav } from "../../index.js";
+import { serializeTarget } from "./target-url.js";
+let testListener;
+const subscribers = new Set();
+export function dispatchTarget(target) {
+    if (testListener !== undefined) {
+        testListener(target);
+        return;
+    }
+    if (subscribers.size > 0) {
+        for (const fn of subscribers) {
+            fn(target);
+        }
+        return;
+    }
+    // biome-ignore lint/suspicious/noConsole: fallback wenn kein Subscriber registered
+    console.debug("[NavTree] target dispatched (unhandled)", target);
+}
+/** Test-Hook: Exklusiver Spy. Returnt cleanup. */
+export function setDispatchListener(fn) {
+    testListener = fn;
+    return () => {
+        testListener = undefined;
+    };
+}
+/** Production-Subscriber registrieren. Returnt unsubscribe. Läuft nur
+ *  wenn kein Test-Listener aktiv (Test-Isolation). */
+export function subscribeTargetDispatches(fn) {
+    subscribers.add(fn);
+    return () => {
+        subscribers.delete(fn);
+    };
+}
+/** V.1.4b: empfohlener Production-Dispatch. Schreibt target in
+ *  nav.searchParams (URL-State, F5-fähig) UND ruft dispatchTarget für
+ *  Test-Listener + legacy-Subscribers. */
+export function useDispatchTarget() {
+    const nav = useNav();
+    return useCallback((target) => {
+        nav.setSearchParams(serializeTarget(target, nav.searchParams));
+        dispatchTarget(target);
+    }, [nav]);
+}

package/dist/web/layout/target-url.d.ts

@@ -0,0 +1,12 @@
+import type { TargetRef } from "@cosmicdrift/kumiko-framework/engine";
+/** Build a search-params update for `setSearchParams`. Clears all
+ *  existing `a_*` keys plus `t` (so wechsel target nicht alte args
+ *  liegen lässt). Returns null-value entries to clear, plus the new
+ *  target entries. */
+export declare function serializeTarget(target: TargetRef, currentParams: Readonly<Record<string, string>>): Readonly<Record<string, string | null>>;
+/** Inverse — parse the current search-params back into a TargetRef.
+ *  Returns undefined wenn der `t`-Key fehlt (kein active target). */
+export declare function parseTargetFromSearchParams(params: Readonly<Record<string, string>>): TargetRef | undefined;
+/** Returns null-valued updates that clear target + all args. Used vom
+ *  Close-Button + onUnmount. */
+export declare function clearTargetSearchParams(currentParams: Readonly<Record<string, string>>): Readonly<Record<string, string | null>>;

package/dist/web/layout/target-url.js

@@ -0,0 +1,77 @@
+// @runtime client
+// URL-Bridge für Visual-Tree-Targets. Serialisiert TargetRef in
+// Search-Params + parsed zurück.
+//
+// **URL-Shape**:
+//   ?t=<featureId>:<action>&a_<argKey1>=<value1>&a_<argKey2>=<value2>...
+//
+// Beispiel: text-content edit "imprint/de"
+//   ?t=text-content:edit&a_slug=imprint&a_lang=de
+//
+// **Warum prefix `a_`**: vermeidet Naming-Konflikt mit anderen Query-
+// Params (Pagination, Sort, Filter). Plus klare Trennung target-meta
+// (`t`) vs. action-args (`a_*`).
+//
+// **Warum nicht JSON-encoded**: URL bleibt lesbar + bookmark-fähig.
+// JSON-base64 wäre robust für arbitrary Shapes aber unleserlich. arg-
+// values sind heute nur primitive strings (text-content: slug, lang) —
+// V.1.5 kann auf JSON wechseln wenn nested-args echten Bedarf zeigen.
+const TARGET_PARAM = "t";
+const ARG_PREFIX = "a_";
+/** Build a search-params update for `setSearchParams`. Clears all
+ *  existing `a_*` keys plus `t` (so wechsel target nicht alte args
+ *  liegen lässt). Returns null-value entries to clear, plus the new
+ *  target entries. */
+export function serializeTarget(target, currentParams) {
+    const updates = {};
+    // Clear all previous arg-keys (vermeidet stale args bei target-switch).
+    for (const key of Object.keys(currentParams)) {
+        if (key.startsWith(ARG_PREFIX))
+            updates[key] = null;
+    }
+    updates[TARGET_PARAM] = `${target.featureId}:${target.action}`;
+    if (target.args !== undefined) {
+        for (const [k, v] of Object.entries(target.args)) {
+            // V.1.4b: nur string-args. Numbers/booleans werden via String()
+            // koerziert; nested objects/arrays werden NICHT supported (würde
+            // JSON-encoded URL brauchen, siehe Header-Comment).
+            if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+                updates[`${ARG_PREFIX}${k}`] = String(v);
+            }
+        }
+    }
+    return updates;
+}
+/** Inverse — parse the current search-params back into a TargetRef.
+ *  Returns undefined wenn der `t`-Key fehlt (kein active target). */
+export function parseTargetFromSearchParams(params) {
+    const t = params[TARGET_PARAM];
+    if (t === undefined || t === "")
+        return undefined;
+    const sepIdx = t.indexOf(":");
+    if (sepIdx < 0)
+        return undefined;
+    const featureId = t.slice(0, sepIdx);
+    const action = t.slice(sepIdx + 1);
+    if (featureId === "" || action === "")
+        return undefined;
+    const args = {};
+    let hasArgs = false;
+    for (const [key, value] of Object.entries(params)) {
+        if (key.startsWith(ARG_PREFIX)) {
+            args[key.slice(ARG_PREFIX.length)] = value;
+            hasArgs = true;
+        }
+    }
+    return hasArgs ? { featureId, action, args } : { featureId, action };
+}
+/** Returns null-valued updates that clear target + all args. Used vom
+ *  Close-Button + onUnmount. */
+export function clearTargetSearchParams(currentParams) {
+    const updates = { [TARGET_PARAM]: null };
+    for (const key of Object.keys(currentParams)) {
+        if (key.startsWith(ARG_PREFIX))
+            updates[key] = null;
+    }
+    return updates;
+}

package/dist/web/layout/theme-label.d.ts

@@ -0,0 +1,15 @@
+import { type ThemePreference } from "../../index.ts";
+export type ThemeToggleLabelOptions = {
+    /** Title while the next step is the light theme. */
+    readonly titleInDark?: string | undefined;
+    /** Title while the next step is the dark theme. */
+    readonly titleInLight?: string | undefined;
+    /** Title while the next step is the automatic theme. */
+    readonly titleForAuto?: string | undefined;
+};
+export declare function nextThemePreference(current: ThemePreference): ThemePreference;
+export declare function useThemeToggleLabel({ titleInDark, titleInLight, titleForAuto, }: ThemeToggleLabelOptions): {
+    readonly nextPreference: ThemePreference;
+    readonly title: string;
+    readonly cyclePreference: () => void;
+};