@cosmicdrift/kumiko-renderer 0.374.0 → 0.377.0

package/dist/web/layout/theme-label.js

@@ -0,0 +1,35 @@
+import { useOptionalTranslation, useTokenController } from "../../index.js";
+// light -> dark -> auto -> light: a click describes and applies the NEXT step.
+export function nextThemePreference(current) {
+    if (current === "light")
+        return "dark";
+    if (current === "dark")
+        return "auto";
+    return "light";
+}
+export function useThemeToggleLabel({ titleInDark, titleInLight, titleForAuto, }) {
+    const { mode, preference = mode, setPreference, toggleMode } = useTokenController();
+    // Optional: the toggle also renders outside a LocaleProvider (samples, tests).
+    const translate = useOptionalTranslation();
+    // A TokensApi without setPreference is a plain light/dark implementation: no auto step.
+    const nextPreference = setPreference
+        ? nextThemePreference(preference)
+        : mode === "dark"
+            ? "light"
+            : "dark";
+    const titles = {
+        light: titleInDark ?? translate?.("kumiko.theme.light") ?? "Light theme",
+        dark: titleInLight ?? translate?.("kumiko.theme.dark") ?? "Dark theme",
+        auto: titleForAuto ?? translate?.("kumiko.theme.auto") ?? "Automatic theme",
+    };
+    return {
+        nextPreference,
+        title: titles[nextPreference],
+        cyclePreference: () => {
+            if (setPreference)
+                setPreference(nextPreference);
+            else
+                toggleMode();
+        },
+    };
+}

package/dist/web/layout/theme-menu-item.d.ts

@@ -0,0 +1,12 @@
+import type { ReactNode } from "react";
+export type ThemeMenuItemProps = {
+    readonly lightIcon?: ReactNode;
+    readonly darkIcon?: ReactNode;
+    readonly autoIcon?: ReactNode;
+    readonly titleInDark?: string;
+    readonly titleInLight?: string;
+    readonly titleForAuto?: string;
+    readonly testId?: string;
+};
+/** Theme toggle as a dropdown entry, for a user menu that carries the shell controls. */
+export declare function ThemeMenuItem({ lightIcon, darkIcon, autoIcon, titleInDark, titleInLight, titleForAuto, testId, }: ThemeMenuItemProps): ReactNode;

package/dist/web/layout/theme-menu-item.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { DropdownMenuItem } from "../primitives/dropdown-menu.js";
+import { useThemeToggleLabel } from "./theme-label.js";
+/** Theme toggle as a dropdown entry, for a user menu that carries the shell controls. */
+export function ThemeMenuItem({ lightIcon = "☀", darkIcon = "☾", autoIcon = "◐", titleInDark, titleInLight, titleForAuto, testId, }) {
+    const { nextPreference, title, cyclePreference } = useThemeToggleLabel({
+        titleInDark,
+        titleInLight,
+        titleForAuto,
+    });
+    const icons = { light: lightIcon, dark: darkIcon, auto: autoIcon };
+    return (_jsxs(DropdownMenuItem, { "data-testid": testId, onSelect: (event) => {
+            event.preventDefault();
+            cyclePreference();
+        }, children: [_jsx("span", { "aria-hidden": "true", children: icons[nextPreference] }), _jsx("span", { children: title })] }));
+}

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

@@ -0,0 +1,17 @@
+import { type ReactNode } from "react";
+export type ThemeToggleProps = {
+    /** Icon for the step to light mode. Default: ☀ */
+    readonly lightIcon?: ReactNode;
+    /** Icon for the step to dark mode. Default: ☾ */
+    readonly darkIcon?: ReactNode;
+    /** Icon for the step to auto mode. Default: ◐ */
+    readonly autoIcon?: ReactNode;
+    /** Title/aria-label for the step to light mode. Default: i18n `kumiko.theme.light` */
+    readonly titleInDark?: string;
+    /** Title/aria-label for the step to dark mode. Default: i18n `kumiko.theme.dark` */
+    readonly titleInLight?: string;
+    /** Title/aria-label for the step to auto mode. Default: i18n `kumiko.theme.auto` */
+    readonly titleForAuto?: string;
+    readonly testId?: string;
+};
+export declare function ThemeToggle({ lightIcon, darkIcon, autoIcon, titleInDark, titleInLight, titleForAuto, testId, }: ThemeToggleProps): ReactNode;

package/dist/web/layout/theme-toggle.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// ThemeToggle — Button der die Theme-Wahl weiterschaltet (hell → dunkel → auto).
+// Icon-Slots als Props, damit renderer/web keine Icon-Lib als Hard-
+// Dependency zieht. Default: Unicode-Glyphs (☀ / ☾) — funktionieren in
+// jedem Browser, jede App kann lucide/heroicons/eigene SVG via Props
+// reinreichen.
+import { useContext } from "react";
+import { HeaderOverflowMenuContext, headerOverflowMenuItemClass } from "./header-overflow-menu.js";
+import { useThemeToggleLabel } from "./theme-label.js";
+export function ThemeToggle({ lightIcon = "☀", darkIcon = "☾", autoIcon = "◐", titleInDark, titleInLight, titleForAuto, testId, }) {
+    const inOverflowMenu = useContext(HeaderOverflowMenuContext);
+    const { nextPreference, title, cyclePreference } = useThemeToggleLabel({
+        titleInDark,
+        titleInLight,
+        titleForAuto,
+    });
+    const icon = { light: lightIcon, dark: darkIcon, auto: autoIcon }[nextPreference];
+    if (inOverflowMenu) {
+        return (_jsxs("button", { type: "button", role: "menuitem", onClick: cyclePreference, className: headerOverflowMenuItemClass, "data-testid": testId, children: [_jsx("span", { "aria-hidden": "true", children: icon }), _jsx("span", { children: title })] }));
+    }
+    return (_jsx("button", { type: "button", onClick: cyclePreference, className: "inline-flex h-8 w-8 items-center justify-center rounded-md border bg-background text-muted-foreground hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring", title: title, "aria-label": title, "data-testid": testId, children: icon }));
+}

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

@@ -0,0 +1,8 @@
+import type { ReactNode } from "react";
+export type TopbarProps = {
+    readonly start?: ReactNode;
+    readonly center?: ReactNode;
+    readonly end?: ReactNode;
+    readonly testId?: string;
+};
+export declare function Topbar({ start, center, end, testId }: TopbarProps): ReactNode;

package/dist/web/layout/topbar.js

@@ -0,0 +1,4 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function Topbar({ start, center, end, testId }) {
+    return (_jsxs("header", { "data-testid": testId, "data-kumiko-layout": "topbar", className: "flex h-12 items-center gap-4 border-b bg-background px-4 text-sm", children: [start !== undefined && _jsx("div", { className: "flex items-center gap-3", children: start }), center !== undefined && _jsx("nav", { className: "flex flex-1 items-center gap-6", children: center }), end !== undefined && _jsx("div", { className: "ml-auto flex items-center gap-2", children: end })] }));
+}

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

@@ -0,0 +1,63 @@
+import { type ReactNode } from "react";
+import type { AppSchema, FeatureSchema, WorkspaceSchema } from "../../index.ts";
+export type WorkspaceShellUser = {
+    readonly id: string;
+    readonly roles: readonly string[];
+};
+export type WorkspaceShellProps = {
+    /** Branding / logo on the left side of the topbar. */
+    readonly brand: ReactNode;
+    /** Schema mit `workspaces` populated — die engine baut das aus
+     *  registry.getAllWorkspaces() + getWorkspaceNavs(). Akzeptiert
+     *  AppSchema (multi-feature) oder die legacy FeatureSchema (single-
+     *  feature, workspaces inline). Ohne Workspaces fällt der Shell auf
+     *  plain NavTree ohne Switcher zurück. */
+    readonly schema: AppSchema | FeatureSchema;
+    /** Optional topbar end-slot — TenantSwitcher / ThemeToggle / UserMenu. */
+    readonly topbarActions?: ReactNode;
+    /** Current user. Drives which workspaces appear in the switcher. */
+    readonly user?: WorkspaceShellUser;
+    /** Initial active workspace short id ("admin"). When omitted: default
+     *  workspace from schema, otherwise first accessible. Useful for SSR
+     *  and tests to pre-seed without hitting the URL. */
+    readonly initialWorkspaceId?: string;
+    /** Footer-Slot unten in der Sidebar — Profile-Row, Help-Link, Build-
+     *  Info. Klebt am unteren Rand via `mt-auto` (siehe Sidebar.footer).
+     *  Symmetrisch zu DefaultAppShell.sidebarFooter. */
+    readonly sidebarFooter?: ReactNode;
+    /** Runtime badge slot per nav leaf (bare nav id), same as DefaultAppShell. */
+    readonly navBadges?: ReadonlyMap<string, ReactNode>;
+    /** Viewport-fit shell. true → fixed viewport height (`h-svh`), content
+     *  scrolls INSIDE instead of the whole page. Default true — set
+     *  `fill={false}` to opt back into page scroll. */
+    readonly fill?: boolean;
+    /** Screen content. */
+    readonly children: ReactNode;
+};
+export declare function WorkspaceShell({ brand, schema, topbarActions, user, initialWorkspaceId, sidebarFooter, navBadges, fill, children, }: WorkspaceShellProps): ReactNode;
+export declare function filterByAccess(workspaces: readonly WorkspaceSchema[], userRoles: readonly string[] | undefined): readonly WorkspaceSchema[];
+/** Returns the short screen-id of the first nav-member that points at
+ *  a screen. Walks the workspace's nav-list in order and skips section-
+ *  headers (NavDefinitions ohne `screen`) so ein workspace dessen erstes
+ *  Member ein Header ist trotzdem auf einen renderbaren Screen auflöst.
+ *
+ *  Returns "" when:
+ *    - navMembers is undefined or empty
+ *    - all members are section-headers (no `screen` property)
+ *    - all members are unknown to the schema (drift zwischen
+ *      r.workspace.nav und den registrierten navs — boot-validator fängt
+ *      das server-side, hier nur graceful fallback)
+ *
+ *  The caller MUST loop-guard on "": rendering with screenId="" macht
+ *  KumikoScreen den not-found-banner zeigen — und ein nav.replace mit
+ *  leerem screenId würde den useLayoutEffect in WorkspaceShell bei
+ *  jedem Re-Render erneut feuern (siehe matching guard dort).
+ *
+ *  Earlier code used `lastSegment(navQn)` which only worked when the
+ *  feature followed the convention nav.id === screen.id (samples/apps/
+ *  workspaces does this). Apps with distinct ids (publicstatus: nav
+ *  "components" → screen "component-list") got "Screen not found".
+ *
+ *  Exported für Edge-Case-Tests. */
+export declare function firstNavScreenId(app: AppSchema, navMembers: readonly string[] | undefined): string;
+export declare function resolveDefaultId(visible: readonly WorkspaceSchema[], preferredShortId: string | undefined): string | undefined;

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

@@ -0,0 +1,220 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// WorkspaceShell — App-shell for multi-persona apps. Renders the
+// switcher in the topbar center slot, picks the active workspace from
+// URL state (?w=<id>) or default, and feeds the active workspace's
+// nav-membership down to NavTree as an allow-set.
+//
+// Apps that don't need workspaces stick with DefaultAppShell. Both
+// shells live side-by-side; createKumikoApp's `shell` prop picks one.
+//
+// Active-workspace resolution priority:
+//   1. URL workspace segment `/<workspace>/...`  (user-driven, shareable)
+//   2. `initialWorkspaceId` prop                  (caller-pinned, SSR/test)
+//   3. WorkspaceDefinition with default:true      (engine-validated unique)
+//   4. First workspace the user has access to
+//
+// State lives in the URL as the single source of truth via the standard
+// nav route (`useNav().route.workspaceId`). No local React state —
+// tenant-switches and role refreshes heal automatically: `visible`
+// recomputes, the URL id no longer matches a visible workspace, the
+// resolution chain falls through to the default. Reloads / bookmarks /
+// shared links keep the active workspace because it's part of the URL.
+//
+// The switcher's onSelect calls nav.navigate({ workspaceId, screenId })
+// where screenId is the first nav-member of the target workspace, so a
+// click lands on a real screen instead of an unresolved root URL.
+//
+// Roles gating:
+//   * access.openToAll → always shown
+//   * access.roles     → shown only when user.roles ∩ access.roles ≠ ∅
+//   * access undefined → shown to everyone (engine convention — same
+//                        rule that NavDefinition.access follows)
+import { isUiAccessGranted } from "@cosmicdrift/kumiko-framework/ui-types";
+import { useCallback, useLayoutEffect, useMemo } from "react";
+import { qualifyNavId, toAppSchema, UserRolesProvider, useNav, useTranslation, } from "../../index.js";
+import { useResolvers } from "../app/resolvers-context.js";
+import { Sidebar, SidebarContent, SidebarFooter, SidebarHeader, SidebarInset, SidebarProvider, SidebarRail, } from "../ui/sidebar.js";
+import { EditorPanel } from "./editor-panel.js";
+import { fillClasses } from "./fill-classes.js";
+import { lastSegment, NavTree } from "./nav-tree.js";
+import { PageHeaderSlotProvider } from "./page-header-slot.js";
+import { ShellHeader } from "./shell-header.js";
+import { SidebarPanelProvider, useSidebarPanelHost } from "./sidebar-panel.js";
+import { parseTargetFromSearchParams } from "./target-url.js";
+import { WorkspaceSwitcher } from "./workspace-switcher.js";
+export function WorkspaceShell({ brand, schema, topbarActions, user, initialWorkspaceId, sidebarFooter, navBadges, fill = true, children, }) {
+    const app = useMemo(() => toAppSchema(schema), [schema]);
+    const visible = useMemo(() => filterByAccess(app.workspaces ?? [], user?.roles), [app.workspaces, user?.roles]);
+    const nav = useNav();
+    const t = useTranslation();
+    const routeWorkspaceId = nav.route?.workspaceId;
+    // Single source of truth: URL > initial > engine-default > first visible.
+    // Recomputed on every dependency change — no local state, no stale-id
+    // healing useEffect. If the URL points at a workspace the user can no
+    // longer access (e.g. after a tenant-switch), the chain falls through
+    // to the resolveDefaultId fallback.
+    const activeId = useMemo(() => {
+        if (routeWorkspaceId !== undefined &&
+            visible.some((ws) => ws.definition.id === routeWorkspaceId)) {
+            return routeWorkspaceId;
+        }
+        return resolveDefaultId(visible, initialWorkspaceId);
+    }, [routeWorkspaceId, visible, initialWorkspaceId]);
+    const handleSelect = useCallback((id) => {
+        // Pick the first nav-member that actually points at a screen so
+        // the URL lands on something renderable instead of `/<workspace>`.
+        // Section-headers (nav-Einträge ohne `screen`) werden übersprungen.
+        const target = visible.find((ws) => ws.definition.id === id);
+        const screenId = firstNavScreenId(app, target?.navMembers);
+        nav.navigate({ workspaceId: id, screenId });
+    }, [nav, app, visible]);
+    // Initial sync: covers two URL states that need a default-fill so
+    // NavTree links and RoutedScreen have something to chew on.
+    //
+    //   1. No workspace in URL ("/" or wrong workspace id) → fill the
+    //      active workspace AND its first nav-member's screen.
+    //   2. Workspace present but screen missing ("/admin") → fill in the
+    //      first nav-member's screen, keep the workspace.
+    //
+    // replace, NOT navigate: these are default-fills, not user actions.
+    // Using pushState would create a history entry the user never asked
+    // for — Browser-Back from /admin/x → / → effect re-pushes →
+    // Back-loop. replaceState swaps in place: Back leaves the app cleanly.
+    //
+    // useLayoutEffect, NOT useEffect: the children below this shell render
+    // RoutedScreen with the URL's current screenId. If that's "" (URL was
+    // "/" or "/admin"), KumikoScreen renders a "Screen not found" banner
+    // for the empty qn. useEffect would let that banner paint to the
+    // screen for one frame before the URL got fixed. useLayoutEffect runs
+    // synchronously between commit and paint, so the user only ever sees
+    // the resolved screen. (No SSR here, otherwise we'd need a guard.)
+    useLayoutEffect(() => {
+        if (activeId === undefined)
+            return;
+        const routeScreenEmpty = nav.route?.screenId === undefined || nav.route.screenId === "";
+        const workspaceMatches = routeWorkspaceId === activeId;
+        if (workspaceMatches && !routeScreenEmpty)
+            return; // URL is fine
+        const target = visible.find((ws) => ws.definition.id === activeId);
+        const navMembers = target?.navMembers;
+        if ((navMembers === undefined || navMembers.length === 0) && !routeScreenEmpty) {
+            // Workspace exists but no nav members — keep whatever screen the
+            // user typed, just lock the workspace prefix.
+            nav.replace({ workspaceId: activeId, screenId: nav.route?.screenId ?? "" });
+            return;
+        }
+        const screenId = firstNavScreenId(app, navMembers);
+        // Loop-guard: wenn keiner der nav-members eine screen-property hat
+        // (alle section-headers oder unbekannte QNs), würde nav.replace mit
+        // screenId="" den Effect bei jedem Re-Render erneut feuern und den
+        // User auf "/<workspace>/" pinnen. Lieber gar nicht replacen — der
+        // Workspace-Selector kann den User dann manuell auf einen leaf-nav
+        // schicken.
+        if (screenId === "")
+            return;
+        nav.replace({ workspaceId: activeId, screenId });
+    }, [activeId, routeWorkspaceId, visible, nav, app]);
+    const activeWorkspace = useMemo(() => visible.find((ws) => ws.definition.id === activeId), [visible, activeId]);
+    // Filter resolution has THREE branches and getting them right matters:
+    //   * Schema declares workspaces + active resolved → filter to its members
+    //   * Schema declares workspaces + NO active visible → empty allow-set
+    //     (NOT undefined). This catches the "user has no accessible workspace"
+    //     case — falling back to "no filter" would leak nav items the user
+    //     shouldn't see, e.g. admin entries to a driver after a role change.
+    //   * Schema doesn't declare workspaces at all → undefined (no filter).
+    //     Apps that haven't opted into workspaces yet get every nav as before.
+    const allowedNavQns = useMemo(() => {
+        const hasWorkspaceMode = app.workspaces !== undefined && app.workspaces.length > 0;
+        if (!hasWorkspaceMode)
+            return undefined;
+        if (activeWorkspace === undefined)
+            return new Set();
+        return new Set(activeWorkspace.navMembers);
+    }, [app.workspaces, activeWorkspace]);
+    const switcher = activeId !== undefined && (_jsx(WorkspaceSwitcher, { workspaces: visible, activeId: activeId, onSelect: handleSelect }));
+    // EINE Nav: immer NavTree. Dynamische Knoten (r.nav({ provider: true }))
+    // ziehen ihre Children client-seitig aus den registrierten navProviders —
+    // der frühere navigation:"tree"/VisualTree-Zweig ist hier eingefaltet.
+    // Content-Bereich: ein aktives target (aus den nav.searchParams, gesetzt
+    // beim Klick auf einen target-Knoten) rendert den EditorPanel statt des
+    // RoutedScreen — sonst die normalen screen-children.
+    // (WorkspaceDefinition.navigation ist seitdem ein No-op; deferred removal.)
+    const resolvers = useResolvers();
+    const activeTarget = parseTargetFromSearchParams(nav.searchParams);
+    const sidebarContent = (_jsx(NavTree, { schema: app, ...(user !== undefined && { user }), ...(allowedNavQns !== undefined && { allowedNavQns }), ...(navBadges !== undefined && { navBadges }) }));
+    // Modern shell (like DefaultAppShell): collapsible icon-rail sidebar
+    // carries brand + workspace switcher + nav + footer; the SidebarInset
+    // renders the shared ShellHeader (panel toggle + breadcrumb + actions)
+    // above the content. topbarActions render right inside the header row
+    // instead of a separate topbar — one header line, not two.
+    const fillCls = fillClasses(fill);
+    // Zweite Spalte nur wenn ein Screen sie fuellt (sidebar-09-Muster) — sonst
+    // stuende auf jedem anderen Screen ein leerer Streifen neben der Navigation.
+    const panel = useSidebarPanelHost();
+    return (_jsx(SidebarProvider, { ...fillCls.provider, children: _jsxs(SidebarPanelProvider, { value: panel.value, children: [_jsxs(Sidebar, { collapsible: "icon", mobileTitle: t("kumiko.sidebar.title"), mobileDescription: t("kumiko.sidebar.description"), children: [_jsxs(SidebarHeader, { "data-kumiko-layout": "sidebar-header", children: [brand, switcher] }), _jsx(SidebarContent, { "data-kumiko-layout": "sidebar-nav", children: sidebarContent }), sidebarFooter !== undefined && (_jsx(SidebarFooter, { "data-kumiko-layout": "sidebar-footer", className: "border-t border-sidebar-border", children: sidebarFooter })), _jsx(SidebarRail, { "aria-label": t("kumiko.sidebar.toggle"), title: t("kumiko.sidebar.toggle") })] }), _jsx("div", { ref: panel.ref, "data-kumiko-layout": "sidebar-panel", className: panel.occupied ? "flex h-svh shrink-0 flex-col" : "hidden" }), _jsx(SidebarInset, { className: fillCls.inset, children: _jsxs(PageHeaderSlotProvider, { children: [_jsx(ShellHeader, { schema: app, ...(user !== undefined && { user }), ...(topbarActions !== undefined && { headerActions: topbarActions }) }), _jsx("main", { className: fillCls.main, children: activeTarget !== undefined ? (_jsx(EditorPanel, { resolvers: resolvers })) : (_jsx(UserRolesProvider, { roles: user?.roles, children: children })) })] }) })] }) }));
+}
+// --- helpers (exported for tests) ---
+export function filterByAccess(workspaces, userRoles) {
+    return [...workspaces]
+        .filter((ws) => isUiAccessGranted(ws.definition.access, userRoles))
+        .sort(byOrderThenInsertion);
+}
+function byOrderThenInsertion(a, b) {
+    // Missing `order` sorts last; ties keep insertion order via stable sort.
+    const ao = a.definition.order ?? Number.POSITIVE_INFINITY;
+    const bo = b.definition.order ?? Number.POSITIVE_INFINITY;
+    return ao - bo;
+}
+/** Returns the short screen-id of the first nav-member that points at
+ *  a screen. Walks the workspace's nav-list in order and skips section-
+ *  headers (NavDefinitions ohne `screen`) so ein workspace dessen erstes
+ *  Member ein Header ist trotzdem auf einen renderbaren Screen auflöst.
+ *
+ *  Returns "" when:
+ *    - navMembers is undefined or empty
+ *    - all members are section-headers (no `screen` property)
+ *    - all members are unknown to the schema (drift zwischen
+ *      r.workspace.nav und den registrierten navs — boot-validator fängt
+ *      das server-side, hier nur graceful fallback)
+ *
+ *  The caller MUST loop-guard on "": rendering with screenId="" macht
+ *  KumikoScreen den not-found-banner zeigen — und ein nav.replace mit
+ *  leerem screenId würde den useLayoutEffect in WorkspaceShell bei
+ *  jedem Re-Render erneut feuern (siehe matching guard dort).
+ *
+ *  Earlier code used `lastSegment(navQn)` which only worked when the
+ *  feature followed the convention nav.id === screen.id (samples/apps/
+ *  workspaces does this). Apps with distinct ids (publicstatus: nav
+ *  "components" → screen "component-list") got "Screen not found".
+ *
+ *  Exported für Edge-Case-Tests. */
+export function firstNavScreenId(app, navMembers) {
+    if (navMembers === undefined || navMembers.length === 0)
+        return "";
+    for (const navQn of navMembers) {
+        for (const feature of app.features) {
+            for (const nav of feature.navs ?? []) {
+                if (qualifyNavId(feature.featureName, nav.id) !== navQn)
+                    continue;
+                if (nav.screen === undefined)
+                    break; // section-header → nächstes member
+                return lastSegment(nav.screen);
+            }
+        }
+    }
+    return "";
+}
+export function resolveDefaultId(visible, preferredShortId) {
+    // 1. Caller-pinned preference (URL or test prop) wins if it's accessible.
+    if (preferredShortId !== undefined) {
+        const match = visible.find((ws) => ws.definition.id === preferredShortId);
+        if (match !== undefined)
+            return match.definition.id;
+    }
+    // 2. Engine-declared default if accessible.
+    const defaulted = visible.find((ws) => ws.definition.default === true);
+    if (defaulted !== undefined)
+        return defaulted.definition.id;
+    // 3. First workspace the user can see.
+    return visible[0]?.definition.id;
+}

package/dist/web/layout/workspace-switcher.d.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from "react";
+import type { WorkspaceSchema } from "../../index.ts";
+export type WorkspaceSwitcherProps = {
+    readonly workspaces: readonly WorkspaceSchema[];
+    readonly activeId: string;
+    readonly onSelect: (workspaceQn: string) => void;
+    readonly testId?: string;
+};
+/**
+ * Requires an ancestor `SidebarProvider` (see `../ui/sidebar`) — this
+ * component renders `SidebarMenuButton`, which calls `useSidebar()`
+ * internally and throws ("useSidebar must be used within a
+ * SidebarProvider.") when rendered outside one.
+ */
+export declare function WorkspaceSwitcher({ workspaces, activeId, onSelect, testId, }: WorkspaceSwitcherProps): ReactNode;

package/dist/web/layout/workspace-switcher.js

@@ -0,0 +1,36 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// WorkspaceSwitcher — dumb component for picking the active workspace.
+// Receives the role-filtered + order-sorted workspace list, the active
+// id, and a callback. Stays presentational so WorkspaceShell can own the
+// state (URL ?w=, defaults, role filtering) and tests can hand any list
+// in directly.
+//
+// Dropdown instead of a tab row: a row of fixed buttons overflowed the
+// sidebar width with 3+ workspaces (or even 2 longer names) —
+// truncate+scroll then hid the last entry entirely, unclickable. A
+// dropdown has constant trigger width regardless of count/length.
+//
+// Hidden entirely when collapsed instead of an icon/initial: a label at
+// icon width isn't readable anyway, and the user switches workspaces via
+// the full sidebar — no attempt to keep this operable in the icon rail
+// too (same as the search box in nav-tree.tsx).
+import { ChevronsUpDown } from "lucide-react";
+import { useTranslation } from "../../index.js";
+import { DropdownMenu, DropdownMenuContent, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuTrigger, } from "../primitives/dropdown-menu.js";
+import { SidebarMenu, SidebarMenuButton, SidebarMenuItem } from "../ui/sidebar.js";
+/**
+ * Requires an ancestor `SidebarProvider` (see `../ui/sidebar`) — this
+ * component renders `SidebarMenuButton`, which calls `useSidebar()`
+ * internally and throws ("useSidebar must be used within a
+ * SidebarProvider.") when rendered outside one.
+ */
+export function WorkspaceSwitcher({ workspaces, activeId, onSelect, testId, }) {
+    const t = useTranslation();
+    // Single workspace doesn't need a switcher — the user has no choice
+    // anyway. Render nothing instead of a useless one-button row.
+    if (workspaces.length <= 1)
+        return null;
+    const labelOf = (ws) => ws.definition.label.includes(".") ? t(ws.definition.label) : ws.definition.label;
+    const active = workspaces.find((ws) => ws.definition.id === activeId);
+    return (_jsx(SidebarMenu, { "data-testid": testId, "data-kumiko-layout": "workspace-switcher", className: "group-data-[collapsible=icon]:hidden", children: _jsx(SidebarMenuItem, { children: _jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsxs(SidebarMenuButton, { "data-testid": "workspace-switcher-trigger", "aria-label": t("kumiko.workspace.switch"), children: [_jsx("span", { className: "truncate", children: active !== undefined ? labelOf(active) : t("kumiko.workspace.select") }), _jsx(ChevronsUpDown, { className: "ml-auto" })] }) }), _jsx(DropdownMenuContent, { align: "start", className: "min-w-[10rem]", children: _jsx(DropdownMenuRadioGroup, { value: activeId, onValueChange: onSelect, children: workspaces.map((ws) => (_jsx(DropdownMenuRadioItem, { value: ws.definition.id, "data-testid": `workspace-tab-${ws.definition.id}`, children: _jsx("span", { className: "truncate", children: labelOf(ws) }) }, ws.definition.id))) }) })] }) }) }));
+}

package/dist/web/lib/accept-attr.d.ts

@@ -0,0 +1 @@
+export declare function toAcceptAttr(accept?: readonly string[]): string | undefined;

package/dist/web/lib/accept-attr.js

@@ -0,0 +1,6 @@
+// "jpg" → ".jpg", "image/png" stays as-is. Empty list → no accept attribute.
+export function toAcceptAttr(accept) {
+    if (accept === undefined || accept.length === 0)
+        return undefined;
+    return accept.map((a) => (a.startsWith(".") || a.includes("/") ? a : `.${a}`)).join(",");
+}

package/dist/web/lib/clamp.d.ts

@@ -0,0 +1 @@
+export declare function clamp(value: number, min: number, max: number): number;

package/dist/web/lib/clamp.js

@@ -0,0 +1,3 @@
+export function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}

package/dist/web/lib/cn.d.ts

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

package/dist/web/lib/cn.js

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

package/dist/web/lib/download.d.ts

@@ -0,0 +1,2 @@
+import type { Dispatcher, DispatcherError } from "../../headless/index.ts";
+export declare function postWithDownload(dispatcher: Dispatcher, type: string, payload: unknown): Promise<DispatcherError | null>;

package/dist/web/lib/download.js

@@ -0,0 +1,24 @@
+// Dispatch a query/handler whose result carries `{ url }` (a signed,
+// short-lived storage URL with `content-disposition: attachment`), then
+// navigate the browser to it so the file downloads. The query rides the
+// live dispatcher, so it carries the `X-CSRF-Token` header automatically —
+// unlike a plain `<a href>` navigation, which sends only cookies and trips
+// the CSRF double-submit check on any server-side re-dispatch.
+//
+// Web-only (uses `window`). Returns the dispatcher error on failure (so the
+// caller can surface its i18nKey), or null on success.
+export async function postWithDownload(dispatcher, type, payload) {
+    const res = await dispatcher.query(type, payload);
+    if (!res.isSuccess)
+        return res.error;
+    if (!res.data?.url) {
+        return {
+            code: "download_url_missing",
+            httpStatus: 502,
+            i18nKey: "errors.download.urlMissing",
+            message: "download query returned no url",
+        };
+    }
+    window.location.assign(res.data.url);
+    return null;
+}

package/dist/web/lib/file-ref-download.d.ts

@@ -0,0 +1,15 @@
+export declare class FileDownloadFailedError extends Error {
+    readonly status: number;
+    constructor(status: number);
+}
+export declare function fileNameFromContentDisposition(header: string | null): string | undefined;
+export declare function fetchFileRefBlob(fileRefId: string): Promise<{
+    blob: Blob;
+    fileName: string | undefined;
+}>;
+export declare function saveBlobAsFile(fileName: string, blob: Blob, options?: {
+    bom?: boolean;
+}): void;
+export declare function downloadFileRef(fileRefId: string, options?: {
+    fileName?: string;
+}): Promise<void>;

package/dist/web/lib/file-ref-download.js

@@ -0,0 +1,62 @@
+import { CSRF_HEADER_NAME, readCsrfToken } from "../../live/index.js";
+const UTF8_BOM = String.fromCharCode(0xfeff);
+export class FileDownloadFailedError extends Error {
+    status;
+    constructor(status) {
+        super(`download failed (${status})`);
+        this.status = status;
+    }
+}
+const EXTENDED_FILENAME = /filename\*\s*=\s*(?:[^']*)'[^']*'([^;]+)/i;
+const PLAIN_FILENAME = /(?:^|;)\s*filename\s*=\s*(?:"((?:[^"\\]|\\.)*)"|([^;]+))/i;
+export function fileNameFromContentDisposition(header) {
+    if (header === null)
+        return undefined;
+    const extended = EXTENDED_FILENAME.exec(header)?.[1];
+    if (extended !== undefined) {
+        try {
+            return decodeURIComponent(extended.trim());
+        }
+        catch {
+            // malformed percent-encoding: fall back to the plain filename
+        }
+    }
+    const plain = PLAIN_FILENAME.exec(header);
+    const value = plain?.[1]?.replace(/\\(.)/g, "$1") ?? plain?.[2]?.trim();
+    return value === undefined || value === "" ? undefined : value;
+}
+export async function fetchFileRefBlob(fileRefId) {
+    const csrf = readCsrfToken();
+    const res = await fetch(`/api/files/${encodeURIComponent(fileRefId)}`, {
+        ...(csrf !== undefined && { headers: { [CSRF_HEADER_NAME]: csrf } }),
+    });
+    if (!res.ok)
+        throw new FileDownloadFailedError(res.status);
+    return {
+        blob: await res.blob(),
+        fileName: fileNameFromContentDisposition(res.headers.get("content-disposition")),
+    };
+}
+export function saveBlobAsFile(fileName, blob, options) {
+    const payload = options?.bom === true ? new Blob([UTF8_BOM, blob], { type: blob.type }) : blob;
+    const url = URL.createObjectURL(payload);
+    try {
+        const anchor = document.createElement("a");
+        anchor.href = url;
+        anchor.download = fileName;
+        document.body.appendChild(anchor);
+        try {
+            anchor.click();
+        }
+        finally {
+            anchor.remove();
+        }
+    }
+    finally {
+        URL.revokeObjectURL(url);
+    }
+}
+export async function downloadFileRef(fileRefId, options) {
+    const { blob, fileName } = await fetchFileRefBlob(fileRefId);
+    saveBlobAsFile(fileName ?? options?.fileName ?? fileRefId, blob);
+}

package/dist/web/lib/file-upload-form-data.d.ts

@@ -0,0 +1,7 @@
+export type FileUploadFormDataInput = {
+    readonly file: Blob;
+    readonly entityType?: string | undefined;
+    readonly entityId?: string | undefined;
+    readonly fieldName?: string | undefined;
+};
+export declare function buildFileUploadFormData(input: FileUploadFormDataInput): FormData;

package/dist/web/lib/file-upload-form-data.js

@@ -0,0 +1,11 @@
+export function buildFileUploadFormData(input) {
+    const formData = new FormData();
+    formData.append("file", input.file);
+    if (input.entityType !== undefined)
+        formData.append("entityType", input.entityType);
+    if (input.entityId !== undefined)
+        formData.append("entityId", input.entityId);
+    if (input.fieldName !== undefined)
+        formData.append("fieldName", input.fieldName);
+    return formData;
+}

package/dist/web/lib/resize-image.d.ts

@@ -0,0 +1 @@
+export declare function resizeImageBeforeUpload(file: File, maxEdge?: number): Promise<File>;