@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/components/app-shell.d.ts

@@ -0,0 +1,159 @@
+import * as React from "react";
+import { type VamosLinkComponent, type VamosProviderProps } from "../lib/provider.js";
+import type { MenuEntry } from "../lib/variants.js";
+import { type BadgeSpec, type NavIcon, type NavNode } from "../lib/nav.js";
+import { type CommandAction, type CommandSource } from "./command.js";
+import { type UserMenuProps } from "./top-bar.js";
+declare const appShellLabels: {
+    skip: string;
+    navigation: string;
+    appMenu: string;
+    workspace: string;
+    goTo: string;
+    apps: string;
+    switchTo: string;
+    newItem: string;
+    noApps: string;
+    noAppsDescription: string;
+    pageChanged: string;
+};
+export type AppShellLabels = typeof appShellLabels;
+export interface AppLink {
+    id: string;
+    label: string;
+    href: string;
+    icon?: NavIcon;
+    external?: boolean;
+}
+/** One app (CMS, CRM, HR, PRM…) on the shared shell. Define these in a client module (they hold components). */
+export interface AppDefinition {
+    /** `"site"` | `"crm"` | `"people"`… */
+    id: string;
+    name: string;
+    description?: string;
+    icon?: React.ComponentType<{
+        className?: string;
+        strokeWidth?: number;
+    }> | React.ReactNode;
+    /** App home. An absolute URL (separately deployed app) triggers a full navigation. */
+    href: string;
+    /** Path prefix that belongs to the app. Default: `href`. */
+    base?: string;
+    /** `data-accent` override for the whole shell while this app is active (e.g. CRM = `"ocean"`). */
+    accent?: string;
+    nav: NavNode[];
+    /** Commands for ⌘K while this app is active. */
+    commands?: CommandAction[];
+    /** Record search sources (stay registered when another app is active). */
+    sources?: CommandSource[];
+    /** Contents of the top bar's "New ▾" button. */
+    newMenu?: MenuEntry[];
+    /** Top-bar links that only make sense in this app ("View site" in the Site app). */
+    links?: AppLink[];
+    /** Hide the app entirely unless `can(permission)`. */
+    permission?: string;
+}
+export interface AppShellProviderProps extends Partial<Omit<VamosProviderProps, "children" | "Link">> {
+    apps: AppDefinition[];
+    /** Default: the app whose `base` / `href` is the longest prefix of `currentPath`, else the last one used. */
+    activeApp?: string;
+    /** A menu shared by every app (users, settings), shown at the bottom of the sidebar. */
+    sharedNav?: NavNode[];
+    /** Commands available in every app. */
+    commands?: CommandAction[];
+    /** Feature flags / module toggles for nav items with `feature`. */
+    features?: Record<string, boolean | undefined>;
+    /** Rail preference — read the `ui-sidebar` cookie on the server (`parseSidebarCookie`) to avoid a flash. `undefined` = no preference. */
+    defaultCollapsed?: boolean;
+    /** Default: writes the `ui-sidebar` cookie. */
+    onCollapsedChange?: (collapsed: boolean) => void;
+    workspaces?: {
+        id: string;
+        name: string;
+        logo?: string;
+    }[];
+    activeWorkspace?: string;
+    onWorkspaceChange?: (id: string) => void;
+    /** Global shortcuts: `mod+k` (palette) and `mod+\\` (rail). Default `true`; turn off for shells embedded in a page. */
+    shortcuts?: boolean;
+    /** Router link (Next `Link`). Also accepted as `Link`. Omit when a `VamosProvider` above already sets it. */
+    linkComponent?: VamosLinkComponent;
+    Link?: VamosLinkComponent;
+    children: React.ReactNode;
+}
+/**
+ * The app bridge for the shell: apps, shared nav, permissions, collapse preference, the ⌘K
+ * registry (with "Go to" commands derived from every accessible app's nav) and app switching.
+ * Router pieces come from the surrounding `VamosProvider`, or pass them here.
+ */
+export declare function AppShellProvider(props: AppShellProviderProps): React.JSX.Element;
+/**
+ * The shell state: active app, nav, rail, mobile nav, app switching. Throws outside `AppShellProvider`.
+ */
+export declare function useAppShell(): {
+    activeApp: AppDefinition | undefined;
+    apps: AppDefinition[];
+    nav: NavNode[];
+    sharedNav: NavNode[];
+    collapsed: boolean;
+    setCollapsed: (v: boolean) => void;
+    openMobileNav: () => void;
+    closeMobileNav: () => void;
+    mobileNavOpen: boolean;
+    trail: string[];
+    can: (permission: string) => boolean;
+    switchApp: (id: string) => void;
+};
+/** `true` inside an `AppShellProvider`. */
+export declare function useInAppShell(): boolean;
+/** Breadcrumb built from the shell's active trail (used by `PageHeader breadcrumb="auto"`). */
+export declare function AppShellBreadcrumb({ includeApp, className }: {
+    includeApp?: boolean;
+    className?: string;
+}): React.JSX.Element | null;
+export interface AppShellProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "dir"> {
+    /** Replace the default sidebar (AppSwitcher + SidebarNav + shared nav + collapse). `false` = none. */
+    sidebar?: React.ReactNode | false;
+    /** Replace the default top bar. `false` = none. */
+    topbar?: React.ReactNode | false;
+    /** Slot above the top bar (offline, trial, maintenance banner). */
+    banner?: React.ReactNode;
+    /** Notification center in the default top bar (`<NotificationCenter adapter={…} />`). */
+    notifications?: React.ReactNode;
+    /** Extra default top-bar actions (theme switch, help). */
+    actions?: React.ReactNode;
+    /** User menu in the default top bar. */
+    user?: UserMenuProps;
+    /** Live sidebar badges by nav item id. */
+    badges?: Record<string, BadgeSpec | undefined>;
+    /** Extra sidebar footer content (above the collapse button). */
+    sidebarFooter?: React.ReactNode;
+    /** Footer link in the app switcher ("Manage apps & modules…"). */
+    appSwitcherFooter?: React.ReactNode;
+    /** `sidebar` (default) or `topnav` (portal-style: top-level links in the top bar, no sidebar). */
+    layout?: "sidebar" | "topnav";
+    /** Permissions still loading: sidebar skeleton. */
+    loading?: boolean;
+    /** Move focus to `main` and announce the page title after route changes. Default `true`. */
+    announceRouteChanges?: boolean;
+    /** `screen` fills the viewport (default); `fill` fills the parent (embedded previews). */
+    height?: "screen" | "fill";
+    /** Mount the ⌘K palette, Toaster and confirm dialog. Default `true`. */
+    globals?: boolean;
+    labels?: Partial<AppShellLabels>;
+}
+/**
+ * The one shell every app runs in: sidebar, top bar, content, skip link, mobile sheet nav, ⌘K
+ * palette, toasts and confirm. Switching apps swaps the nav, commands, "New" menu, links and
+ * accent; everything else stays. Use inside `AppShellProvider`.
+ *
+ * ```tsx
+ * <AppShellProvider apps={[siteApp, crmApp]} sharedNav={shared} currentPath={pathname} linkComponent={Link} navigate={router.push}>
+ *   <AppShell user={{ name: "Ada Lovelace", email: "ada@northwind.io", items: account }} notifications={<NotificationCenter adapter={inbox} />}>
+ *     {children}
+ *   </AppShell>
+ * </AppShellProvider>
+ * ```
+ */
+export declare const AppShell: React.ForwardRefExoticComponent<AppShellProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/dist/components/app-shell.js

@@ -0,0 +1,289 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { ArrowUpRight, ChevronDown, Plus } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { useLabels } from "../lib/labels.js";
+import { SmartLink, useCan, useLink, useNavigation, VamosProvider } from "../lib/provider.js";
+import { ThemeScope } from "../lib/theme-scope.js";
+import { useContainerWidth } from "../lib/use-container-width.js";
+import { filterNav, flattenNav, isAbsoluteHref, matchPath, navItems, navTrailItems, resolveActive, SIDEBAR_COOKIE, } from "../lib/nav.js";
+import { Button } from "./button.js";
+import { Breadcrumb } from "./breadcrumb.js";
+import { DialogTitle } from "./dialog.js";
+import { Sheet, SheetContent } from "./sheet.js";
+import { TooltipProvider } from "./tooltip.js";
+import { Toaster } from "./toast.js";
+import { ConfirmProvider } from "./alert-dialog.js";
+import { EmptyState } from "./empty-state.js";
+import { DropdownMenu, DropdownMenuContent, DropdownMenuEntries, DropdownMenuTrigger } from "./dropdown-menu.js";
+import { CommandPalette, CommandProvider, createCommandRegistry, useRegisterCommands } from "./command.js";
+import { AppSwitcher, Sidebar, SidebarCollapseButton, SidebarContent, SidebarFooter, SidebarHeader, SidebarNav, SidebarSkeleton, } from "./sidebar.js";
+import { TopBar, TopBarActions, TopBarMenuButton, TopBarSearch, TopBarSeparator, TopBarShellContext, TopBarSpacer, TopBarStart, UserMenu } from "./top-bar.js";
+const appShellLabels = {
+    skip: "Skip to content",
+    navigation: "Navigation",
+    appMenu: "{app} menu",
+    workspace: "Workspace",
+    goTo: "Go to",
+    apps: "Apps",
+    switchTo: "Switch to {app}",
+    newItem: "New",
+    noApps: "No apps available",
+    noAppsDescription: "Your account doesn't have access to any app yet. Ask an administrator to invite you.",
+    pageChanged: "{title}",
+};
+const AppShellContext = React.createContext(null);
+/** Rail state as resolved by the layout (preference or width). */
+const CollapsedContext = React.createContext(false);
+function writeCookie(v) {
+    try {
+        document.cookie = `${SIDEBAR_COOKIE}=${v ? "1" : "0"}; path=/; max-age=31536000; samesite=lax`;
+    }
+    catch {
+        /* no document */
+    }
+}
+function appFor(apps, path) {
+    if (!path)
+        return undefined;
+    let best;
+    for (const a of apps) {
+        const base = a.base ?? a.href;
+        const score = matchPath(base, path);
+        if (score >= 0 && (!best || score > best.score))
+            best = { app: a, score };
+    }
+    return best?.app;
+}
+/**
+ * The app bridge for the shell: apps, shared nav, permissions, collapse preference, the ⌘K
+ * registry (with "Go to" commands derived from every accessible app's nav) and app switching.
+ * Router pieces come from the surrounding `VamosProvider`, or pass them here.
+ */
+export function AppShellProvider(props) {
+    const { linkComponent, Link, currentPath, navigate, can, locale, messages, dir, timeZone, currency, Image, media, ...rest } = props;
+    const bridge = linkComponent ?? Link ?? currentPath ?? navigate ?? can ?? locale ?? messages ?? dir ?? timeZone ?? currency ?? Image ?? media;
+    const inner = _jsx(AppShellState, { ...rest });
+    if (bridge === undefined)
+        return inner;
+    return (_jsx(VamosProvider, { Link: linkComponent ?? Link, currentPath: currentPath, navigate: navigate, can: can, locale: locale, messages: messages, dir: dir, timeZone: timeZone, currency: currency, Image: Image, media: media, children: inner }));
+}
+function AppShellState({ apps: allApps, activeApp: activeAppId, sharedNav = [], commands, features, defaultCollapsed, onCollapsedChange, workspaces, activeWorkspace, onWorkspaceChange, shortcuts = true, children, }) {
+    const can = useCan();
+    const { currentPath, navigate } = useNavigation();
+    const apps = React.useMemo(() => allApps.filter((a) => !a.permission || can(a.permission)), [allApps, can]);
+    const routeApp = activeAppId ? apps.find((a) => a.id === activeAppId) : appFor(apps, currentPath);
+    const [lastApp, setLastApp] = React.useState(routeApp?.id);
+    React.useEffect(() => {
+        if (routeApp)
+            setLastApp(routeApp.id);
+    }, [routeApp]);
+    const activeApp = routeApp ?? apps.find((a) => a.id === lastApp) ?? apps[0];
+    const [preference, setPreference] = React.useState(defaultCollapsed);
+    const setCollapsed = React.useCallback((v) => {
+        setPreference(v);
+        if (onCollapsedChange)
+            onCollapsedChange(v);
+        else
+            writeCookie(v);
+    }, [onCollapsedChange]);
+    const [mobileNavOpen, setMobileNavOpen] = React.useState(false);
+    React.useEffect(() => setMobileNavOpen(false), [currentPath]);
+    const nav = React.useMemo(() => filterNav(activeApp?.nav ?? [], { can, features }), [activeApp, can, features]);
+    const visibleSharedNav = React.useMemo(() => filterNav(sharedNav, { can, features }), [sharedNav, can, features]);
+    const trail = React.useMemo(() => resolveActive([...nav, ...visibleSharedNav], currentPath).trail, [nav, visibleSharedNav, currentPath]);
+    const switchApp = React.useCallback((id) => {
+        const a = apps.find((x) => x.id === id);
+        if (!a)
+            return;
+        setLastApp(id);
+        if (isAbsoluteHref(a.href) && typeof window !== "undefined")
+            window.location.assign(a.href);
+        else
+            navigate(a.href);
+    }, [apps, navigate]);
+    const [registry] = React.useState(() => createCommandRegistry());
+    // Static record sources of every app stay registered.
+    React.useEffect(() => {
+        const off = apps.flatMap((a) => a.sources ?? []).map((s) => registry.registerSource(s));
+        return () => off.forEach((f) => f());
+    }, [apps, registry]);
+    const value = React.useMemo(() => ({
+        apps,
+        activeApp,
+        sharedNav,
+        nav,
+        visibleSharedNav,
+        features,
+        trail,
+        preference,
+        setCollapsed,
+        mobileNavOpen,
+        setMobileNavOpen,
+        switchApp,
+        can,
+        workspaces,
+        activeWorkspace,
+        onWorkspaceChange,
+        registry,
+        commands,
+        currentPath,
+        shortcuts,
+    }), [apps, activeApp, sharedNav, nav, visibleSharedNav, features, trail, preference, setCollapsed, mobileNavOpen, switchApp, can, workspaces, activeWorkspace, onWorkspaceChange, registry, commands, currentPath, shortcuts]);
+    return (_jsx(AppShellContext.Provider, { value: value, children: _jsxs(CommandProvider, { registry: registry, shortcut: shortcuts ? "mod+k" : false, children: [_jsx(ShellCommands, {}), children] }) }));
+}
+/** Registers app commands, "Go to" commands from every accessible app's nav, and app switching. */
+function ShellCommands() {
+    const ctx = React.useContext(AppShellContext);
+    const t = useLabels("appShell", appShellLabels);
+    const { apps, activeApp, sharedNav, can, features, switchApp, commands } = ctx;
+    const multi = apps.length > 1;
+    const goTo = React.useMemo(() => {
+        const out = [];
+        for (const a of apps) {
+            for (const it of flattenNav(filterNav(a.nav, { can, features }))) {
+                out.push({
+                    id: `nav.${a.id}.${it.id}`,
+                    title: it.trail.join(" › "),
+                    group: t("goTo"),
+                    href: it.href,
+                    icon: it.icon,
+                    keywords: [...(it.keywords ?? []), ...(it.group ? [it.group] : []), a.name],
+                    app: multi ? a.name : undefined,
+                    priority: a.id === activeApp?.id ? 1 : 0,
+                });
+            }
+        }
+        for (const it of flattenNav(filterNav(sharedNav, { can, features }))) {
+            out.push({ id: `nav.shared.${it.id}`, title: it.trail.join(" › "), group: t("goTo"), href: it.href, icon: it.icon, keywords: it.keywords, priority: 0.5 });
+        }
+        if (multi) {
+            for (const a of apps) {
+                if (a.id === activeApp?.id)
+                    continue;
+                out.push({ id: `app.switch.${a.id}`, title: t("switchTo", { app: a.name }), subtitle: a.description, group: t("apps"), icon: a.icon, perform: () => switchApp(a.id) });
+            }
+        }
+        return out;
+    }, [apps, activeApp, sharedNav, can, features, multi, switchApp, t]);
+    useRegisterCommands(goTo, [goTo]);
+    useRegisterCommands(React.useMemo(() => (activeApp?.commands ?? []).map((c) => ({ ...c, app: c.app ?? (multi ? activeApp?.name : undefined) })), [activeApp, multi]), [activeApp]);
+    useRegisterCommands(commands ?? [], [commands]);
+    return null;
+}
+/**
+ * The shell state: active app, nav, rail, mobile nav, app switching. Throws outside `AppShellProvider`.
+ */
+export function useAppShell() {
+    const ctx = React.useContext(AppShellContext);
+    const collapsed = React.useContext(CollapsedContext);
+    if (!ctx)
+        throw new Error("useAppShell must be used inside <AppShellProvider>.");
+    return {
+        activeApp: ctx.activeApp,
+        apps: ctx.apps,
+        nav: ctx.nav,
+        sharedNav: ctx.visibleSharedNav,
+        collapsed,
+        setCollapsed: ctx.setCollapsed,
+        openMobileNav: () => ctx.setMobileNavOpen(true),
+        closeMobileNav: () => ctx.setMobileNavOpen(false),
+        mobileNavOpen: ctx.mobileNavOpen,
+        trail: ctx.trail,
+        can: ctx.can,
+        switchApp: ctx.switchApp,
+    };
+}
+/** `true` inside an `AppShellProvider`. */
+export function useInAppShell() {
+    return React.useContext(AppShellContext) !== null;
+}
+/** Breadcrumb built from the shell's active trail (used by `PageHeader breadcrumb="auto"`). */
+export function AppShellBreadcrumb({ includeApp = true, className }) {
+    const ctx = React.useContext(AppShellContext);
+    if (!ctx || !ctx.trail.length)
+        return null;
+    const crumbs = navTrailItems([...ctx.nav, ...ctx.visibleSharedNav], ctx.trail);
+    // An "All posts" index child duplicates its parent: keep one.
+    const items = crumbs.filter((c, i) => !(i > 0 && c.href && c.href === crumbs[i - 1].href));
+    const all = [...(includeApp && ctx.apps.length > 1 && ctx.activeApp ? [{ label: ctx.activeApp.name, href: ctx.activeApp.href }] : []), ...items.map((c) => ({ label: c.label, href: c.href }))];
+    // A one-item trail only repeats the page title.
+    if (all.length < 2)
+        return null;
+    return _jsx(Breadcrumb, { size: "sm", items: all, className: className });
+}
+/**
+ * The one shell every app runs in: sidebar, top bar, content, skip link, mobile sheet nav, ⌘K
+ * palette, toasts and confirm. Switching apps swaps the nav, commands, "New" menu, links and
+ * accent; everything else stays. Use inside `AppShellProvider`.
+ *
+ * ```tsx
+ * <AppShellProvider apps={[siteApp, crmApp]} sharedNav={shared} currentPath={pathname} linkComponent={Link} navigate={router.push}>
+ *   <AppShell user={{ name: "Ada Lovelace", email: "ada@northwind.io", items: account }} notifications={<NotificationCenter adapter={inbox} />}>
+ *     {children}
+ *   </AppShell>
+ * </AppShellProvider>
+ * ```
+ */
+export const AppShell = React.forwardRef(function AppShell({ sidebar, topbar, banner, notifications, actions, user, badges, sidebarFooter, appSwitcherFooter, layout = "sidebar", loading, announceRouteChanges = true, height = "screen", globals = true, labels, className, children, ...props }, ref) {
+    const ctx = React.useContext(AppShellContext);
+    if (!ctx)
+        throw new Error("AppShell must be used inside <AppShellProvider>.");
+    const t = useLabels("appShell", appShellLabels, labels);
+    const { ref: measureRef, width } = useContainerWidth();
+    const mainRef = React.useRef(null);
+    const columnRef = React.useRef(null);
+    const [announcement, setAnnouncement] = React.useState("");
+    const { activeApp, currentPath } = ctx;
+    // 768–1279px: rail unless the user chose otherwise.
+    const collapsed = ctx.preference ?? (width !== undefined && width >= 768 && width < 1280);
+    const first = React.useRef(true);
+    React.useEffect(() => {
+        if (first.current) {
+            first.current = false;
+            return;
+        }
+        if (!announceRouteChanges)
+            return;
+        columnRef.current?.scrollTo?.({ top: 0 });
+        mainRef.current?.focus({ preventScroll: true });
+        const id = setTimeout(() => setAnnouncement(typeof document !== "undefined" ? document.title : ""), 60);
+        return () => clearTimeout(id);
+    }, [currentPath, announceRouteChanges]);
+    const shellBridge = React.useMemo(() => ({ openMobileNav: () => ctx.setMobileNavOpen(true), mobileNavOpen: ctx.mobileNavOpen }), [ctx]);
+    if (!ctx.apps.length || !activeApp) {
+        return (_jsx("div", { ref: ref, className: cn("grid place-items-center bg-scene p-6", height === "screen" ? "min-h-dvh" : "h-full", className), ...props, children: _jsx(EmptyState, { kind: "forbidden", size: "lg", as: "h2", title: t("noApps"), description: t("noAppsDescription") }) }));
+    }
+    const sidebarBody = (mode) => (_jsxs(_Fragment, { children: [_jsx(SidebarHeader, { children: _jsx(AppSwitcher, { apps: ctx.apps.map((a) => ({ id: a.id, name: a.name, description: a.description, icon: a.icon, href: a.href })), activeApp: activeApp.id, onSelect: ctx.switchApp, workspaces: ctx.workspaces, activeWorkspace: ctx.activeWorkspace, onWorkspaceChange: ctx.onWorkspaceChange, footer: appSwitcherFooter }) }), _jsx(SidebarContent, { "aria-label": t("appMenu", { app: activeApp.name }), children: loading ? _jsx(SidebarSkeleton, {}) : _jsx(SidebarNav, { items: ctx.nav, badges: badges, trail: ctx.trail }) }), sidebarFooter ? _jsx(SidebarFooter, { children: sidebarFooter }) : null, ctx.visibleSharedNav.length && !loading ? (_jsx(SidebarFooter, { children: _jsx(SidebarNav, { "aria-label": t("workspace"), items: ctx.visibleSharedNav, badges: badges, trail: ctx.trail }) })) : null, mode === "desktop" ? (_jsx(SidebarFooter, { children: _jsx(SidebarCollapseButton, {}) })) : null] }));
+    const defaultSidebar = (_jsx(Sidebar, { collapsed: collapsed, onCollapsedChange: ctx.setCollapsed, shortcut: ctx.shortcuts ? "mod+\\" : false, className: "h-full", children: sidebarBody("desktop") }));
+    const links = activeApp.links ?? [];
+    const defaultTopbar = (_jsxs(TopBar, { scrollTarget: columnRef, children: [_jsxs(TopBarStart, { children: [_jsx(TopBarMenuButton, {}), layout === "topnav" ? _jsx("span", { className: "shrink-0 font-display text-[length:calc(19px*var(--display-scale))] leading-none text-fg", children: activeApp.name }) : null, layout === "topnav" ? _jsx(TopNavLinks, { nav: ctx.nav, trail: ctx.trail, label: t("appMenu", { app: activeApp.name }) }) : null] }), _jsx(TopBarSearch, {}), _jsx(TopBarSpacer, {}), _jsxs(TopBarActions, { children: [actions, actions && (links.length || notifications || activeApp.newMenu || user) ? _jsx(TopBarSeparator, {}) : null, links.map((l) => {
+                        const Icon = l.icon;
+                        const ext = l.external ?? isAbsoluteHref(l.href);
+                        return (_jsx(Button, { asChild: true, variant: "ghost", size: "sm", className: "@max-[640px]/topbar:hidden", children: _jsxs(SmartLink, { href: l.href, external: ext, children: [Icon ? _jsx(Icon, { "aria-hidden": true }) : ext ? _jsx(ArrowUpRight, { "aria-hidden": true }) : null, l.label] }) }, l.id));
+                    }), notifications, activeApp.newMenu?.length ? (_jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsxs(Button, { variant: "primary", size: "sm", children: [_jsx(Plus, { "aria-hidden": true }), _jsx("span", { className: "@max-[480px]/topbar:sr-only", children: t("newItem") }), _jsx(ChevronDown, { "aria-hidden": true, className: "-me-0.5 opacity-70" })] }) }), _jsx(DropdownMenuContent, { align: "end", children: _jsx(DropdownMenuEntries, { items: activeApp.newMenu }) })] })) : null, user ? _jsx(UserMenu, { ...user }) : null] })] }));
+    const showSidebar = layout === "sidebar" && sidebar !== false;
+    const shell = (_jsx(ThemeScope, { accent: activeApp.accent, className: cn("relative w-full overflow-hidden bg-transparent", height === "screen" ? "h-dvh" : "h-full"), children: _jsx(TopBarShellContext.Provider, { value: shellBridge, children: _jsxs(CollapsedContext.Provider, { value: collapsed, children: [_jsxs("div", { ref: (node) => {
+                            measureRef(node);
+                            if (typeof ref === "function")
+                                ref(node);
+                            else if (ref)
+                                ref.current = node;
+                        }, "data-slot": "app-shell", "data-app": activeApp.id, "data-layout": layout, "data-collapsed": collapsed ? "" : undefined, className: cn("vui-app-shell flex h-full w-full min-w-0", className), ...props, children: [_jsx("a", { href: "#vui-main", className: "vui-skip-link rounded-ui-sm bg-fg px-3 py-2 text-[13px] font-medium text-scene focus-ring", onClick: (e) => {
+                                    e.preventDefault();
+                                    mainRef.current?.focus();
+                                }, children: t("skip") }), showSidebar ? _jsx("div", { className: "relative z-(--z-nav) h-full shrink-0 @max-[767px]/shell:hidden", children: sidebar ?? defaultSidebar }) : null, _jsxs("div", { ref: columnRef, "data-slot": "app-shell-column", className: "flex h-full min-w-0 flex-1 flex-col overflow-y-auto overscroll-contain", children: [banner, topbar === false ? null : (topbar ?? defaultTopbar), _jsx("main", { ref: mainRef, id: "vui-main", tabIndex: -1, "data-slot": "app-shell-main", className: "min-w-0 flex-1 px-4 py-6 outline-none [--page-px:1rem] @min-[640px]/shell:px-6 @min-[640px]/shell:py-7 @min-[640px]/shell:[--page-px:1.5rem] @min-[1024px]/shell:px-8 @min-[1024px]/shell:[--page-px:2rem]", children: children })] })] }), (showSidebar || layout === "topnav") && sidebar !== false ? (_jsx(Sheet, { open: ctx.mobileNavOpen, onOpenChange: ctx.setMobileNavOpen, children: _jsxs(SheetContent, { side: "start", size: "sm", hideClose: true, className: "max-w-[86vw] border-0 p-0", children: [_jsx(DialogTitle, { className: "sr-only", children: t("navigation") }), _jsx(Sidebar, { mode: "mobile", onNavigate: () => ctx.setMobileNavOpen(false), className: "h-full", children: sidebarBody("mobile") })] }) })) : null, _jsx("div", { "aria-live": "polite", "aria-atomic": "true", className: "sr-only", children: announcement ? t("pageChanged", { title: announcement }) : "" })] }) }) }));
+    if (!globals)
+        return shell;
+    return (_jsx(TooltipProvider, { children: _jsxs(ConfirmProvider, { children: [shell, _jsx(CommandPalette, {}), _jsx(Toaster, {})] }) }));
+});
+function TopNavLinks({ nav, trail, label }) {
+    const Link = useLink();
+    return (_jsx("nav", { "aria-label": label, className: "ms-1 flex min-w-0 items-center gap-0.5 overflow-x-auto scrollbar-none @max-[767px]/shell:hidden", children: navItems(nav)
+            .filter((it) => it.href)
+            .map((it) => {
+            const active = trail[0] === it.id;
+            return (_jsx(Link, { href: it.href, "aria-current": active ? "page" : undefined, className: cn("shrink-0 rounded-ui-sm px-2.5 py-1.5 text-[13.5px] transition-colors focus-ring", active ? "bg-selected font-medium text-fg" : "text-fg-muted hover:bg-hover hover:text-fg"), children: it.label }, it.id));
+        }) }));
+}

package/dist/components/attachment-list.d.ts

@@ -0,0 +1,96 @@
+import * as React from "react";
+/** One file attached to a record. */
+export interface AttachmentData {
+    id: string;
+    /** File name with extension ("Master services agreement.pdf"). */
+    name: string;
+    /** Size in bytes. */
+    size: number;
+    /** MIME type. Used with the extension to pick the icon. */
+    mime: string;
+    /** Download / open URL. Without `onPreview` the name links here. */
+    url?: string;
+    /** Image thumbnail (grid layout and image files). */
+    thumbUrl?: string;
+    uploadedBy?: string;
+    /** ISO instant or `YYYY-MM-DD`. */
+    uploadedAt?: string;
+    /** Default `"ready"`. */
+    status?: "uploading" | "processing" | "ready" | "error";
+    /** 0–100 while uploading. */
+    progress?: number;
+    /** Error message for `status: "error"`. */
+    error?: string;
+}
+export type AttachmentKind = "image" | "pdf" | "document" | "spreadsheet" | "presentation" | "archive" | "audio" | "video" | "code" | "text" | "other";
+/** Splits "contract.final.pdf" into `["contract.final", ".pdf"]` (no extension → `[name, ""]`). */
+export declare function splitFileName(name: string): [base: string, ext: string];
+/** Picks the file family from MIME type and extension — drives the icon and its tint. */
+export declare function attachmentKind(mime: string | undefined, name?: string): AttachmentKind;
+export declare const attachmentLabels: {
+    list: string;
+    empty: string;
+    preview: string;
+    download: string;
+    remove: string;
+    retry: string;
+    uploading: string;
+    progress: string;
+    processing: string;
+    failed: string;
+    add: string;
+    removing: string;
+};
+export type AttachmentListLabels = Partial<typeof attachmentLabels>;
+export interface AttachmentIconProps extends React.HTMLAttributes<HTMLSpanElement> {
+    mime?: string;
+    name?: string;
+    /** Tile size. Default `"md"` (36px). `"lg"` is the grid tile. */
+    size?: "sm" | "md" | "lg";
+}
+/** Mime-family tile: tinted icon, plus the extension in mono on larger tiles. Decorative. */
+export declare function AttachmentIcon({ mime, name, size, className, style, ...props }: AttachmentIconProps): React.JSX.Element;
+/** File name that truncates its base but always keeps the extension visible ("Quarterly board rep….pdf"). */
+export declare function AttachmentName({ name, className, ...props }: React.HTMLAttributes<HTMLSpanElement> & {
+    name: string;
+}): React.JSX.Element;
+export interface AttachmentListProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+    items: AttachmentData[];
+    /** `list` (rows with meta), `grid` (thumbnail tiles) or `chips` (inline, inside comments and forms). Default `"list"`. */
+    layout?: "list" | "grid" | "chips";
+    /** Row height and text size. Default `"md"`. */
+    size?: "sm" | "md";
+    /** Makes the file name a button (open a Lightbox / preview sheet). */
+    onPreview?: (file: AttachmentData) => void;
+    /** Download button. Without it, a ready file with `url` gets a native download link. */
+    onDownload?: (file: AttachmentData) => void;
+    /** Remove button. The row fades while the promise runs; a rejection restores it. Offer Undo in a toast. */
+    onRemove?: (file: AttachmentData) => void | Promise<void>;
+    /** Retry button on failed uploads. */
+    onRetry?: (file: AttachmentData) => void;
+    /** Built-in "Add files" button that opens the file chooser. */
+    onAddFiles?: (files: File[]) => void;
+    /** `accept` for the built-in chooser ("image/*,.pdf"). */
+    accept?: string;
+    /** Your own upload control (a File upload drop zone), rendered after the files. */
+    uploadSlot?: React.ReactNode;
+    /** Hides remove / retry / add. */
+    readOnly?: boolean;
+    /** Shown when there are no files (and nothing to add). Default "No files attached". */
+    empty?: React.ReactNode;
+    /** Accessible name of the list. Default "Attachments". */
+    "aria-label"?: string;
+    labels?: AttachmentListLabels;
+}
+/**
+ * Files on a record — contracts on a deal, an employee's documents, a post's downloads. Mime
+ * icons tinted per family, sizes in the current locale ("1.2 MB" / "1,2 MB"), upload progress,
+ * processing and error states, preview, download and remove.
+ *
+ * ```tsx
+ * <AttachmentList items={files} onPreview={openLightbox} onRemove={removeWithUndo} onAddFiles={upload} />
+ * <AttachmentList layout="grid" items={photos} />
+ * <AttachmentList layout="chips" items={commentFiles} readOnly />
+ * ```
+ */
+export declare const AttachmentList: React.ForwardRefExoticComponent<AttachmentListProps & React.RefAttributes<HTMLDivElement>>;