@vamos-ui/react 0.0.0-stage → 0.2.0

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>>;

package/dist/components/attachment-list.js

@@ -0,0 +1,196 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { AlertCircle, Download, Eye, File as FileGeneric, FileArchive, FileAudio, FileCode, FileImage, FileSpreadsheet, FileText, FileVideo, Paperclip, Plus, Presentation, RotateCcw, X, } from "lucide-react";
+import { cva } from "class-variance-authority";
+import { cn } from "../lib/cn.js";
+import { useLabels } from "../lib/labels.js";
+import { useFormat } from "../lib/locale.js";
+import { IconButton } from "./button.js";
+const EXT = {
+    pdf: "pdf",
+    doc: "document", docx: "document", odt: "document", rtf: "document", pages: "document",
+    xls: "spreadsheet", xlsx: "spreadsheet", ods: "spreadsheet", csv: "spreadsheet", numbers: "spreadsheet",
+    ppt: "presentation", pptx: "presentation", odp: "presentation", key: "presentation",
+    zip: "archive", rar: "archive", "7z": "archive", gz: "archive", tar: "archive",
+    png: "image", jpg: "image", jpeg: "image", gif: "image", webp: "image", avif: "image", svg: "image", heic: "image",
+    mp3: "audio", wav: "audio", m4a: "audio", ogg: "audio",
+    mp4: "video", mov: "video", webm: "video", mkv: "video",
+    js: "code", ts: "code", tsx: "code", json: "code", html: "code", css: "code", xml: "code", sql: "code",
+    txt: "text", md: "text", log: "text",
+};
+/** Splits "contract.final.pdf" into `["contract.final", ".pdf"]` (no extension → `[name, ""]`). */
+export function splitFileName(name) {
+    const i = name.lastIndexOf(".");
+    if (i <= 0 || i === name.length - 1 || name.length - i > 8)
+        return [name, ""];
+    return [name.slice(0, i), name.slice(i)];
+}
+/** Picks the file family from MIME type and extension — drives the icon and its tint. */
+export function attachmentKind(mime, name = "") {
+    const ext = splitFileName(name)[1].slice(1).toLowerCase();
+    const m = (mime ?? "").toLowerCase();
+    if (m === "application/pdf")
+        return "pdf";
+    if (m.startsWith("image/"))
+        return "image";
+    if (m.startsWith("video/"))
+        return "video";
+    if (m.startsWith("audio/"))
+        return "audio";
+    if (EXT[ext])
+        return EXT[ext];
+    if (/spreadsheet|excel|csv/.test(m))
+        return "spreadsheet";
+    if (/presentation|powerpoint/.test(m))
+        return "presentation";
+    if (/word|opendocument\.text|rtf/.test(m))
+        return "document";
+    if (/zip|compressed|tar|rar/.test(m))
+        return "archive";
+    if (/json|javascript|xml|html/.test(m))
+        return "code";
+    if (m.startsWith("text/"))
+        return "text";
+    return "other";
+}
+const KIND_ICON = {
+    image: FileImage,
+    pdf: FileText,
+    document: FileText,
+    spreadsheet: FileSpreadsheet,
+    presentation: Presentation,
+    archive: FileArchive,
+    audio: FileAudio,
+    video: FileVideo,
+    code: FileCode,
+    text: FileText,
+    other: FileGeneric,
+};
+/** Token-based tint per family (distinct, never raw colours). */
+const KIND_TONE = {
+    image: "var(--chart-4)",
+    pdf: "var(--danger)",
+    document: "var(--info)",
+    spreadsheet: "var(--success)",
+    presentation: "var(--warning)",
+    archive: "var(--chart-5)",
+    audio: "var(--chart-6)",
+    video: "var(--chart-3)",
+    code: "var(--chart-2)",
+    text: "var(--fg-muted)",
+    other: "var(--fg-muted)",
+};
+export const attachmentLabels = {
+    list: "Attachments",
+    empty: "No files attached",
+    preview: "Preview {name}",
+    download: "Download {name}",
+    remove: "Remove {name}",
+    retry: "Retry {name}",
+    uploading: "Uploading… {percent}",
+    progress: "{percent}, {name}",
+    processing: "Processing…",
+    failed: "Upload failed",
+    add: "Add files",
+    removing: "Removing…",
+};
+/** Mime-family tile: tinted icon, plus the extension in mono on larger tiles. Decorative. */
+export function AttachmentIcon({ mime, name = "", size = "md", className, style, ...props }) {
+    const kind = attachmentKind(mime, name);
+    const Icon = KIND_ICON[kind];
+    const ext = splitFileName(name)[1].slice(1).toUpperCase();
+    return (_jsxs("span", { "aria-hidden": true, "data-slot": "attachment-icon", "data-kind": kind, className: cn("relative inline-flex shrink-0 items-center justify-center rounded-ui-sm text-(--kind)", "bg-[color-mix(in_oklch,var(--kind)_11%,var(--surface-solid))] ring-1 ring-inset ring-[color-mix(in_oklch,var(--kind)_22%,transparent)]", size === "sm" && "size-6 [&_svg]:size-3.5", size === "md" && "size-9 [&_svg]:size-[18px]", size === "lg" && "size-full flex-col gap-1.5 rounded-none ring-0 [&_svg]:size-7", className), style: { ...style, ["--kind"]: KIND_TONE[kind] }, ...props, children: [_jsx(Icon, { strokeWidth: 1.6 }), size === "lg" && ext ? _jsx("span", { className: "font-mono text-[10px] font-medium tracking-[0.08em]", children: ext }) : null] }));
+}
+/** File name that truncates its base but always keeps the extension visible ("Quarterly board rep….pdf"). */
+export function AttachmentName({ name, className, ...props }) {
+    const [base, ext] = splitFileName(name);
+    return (_jsxs("span", { "data-slot": "attachment-name", dir: "auto", title: name, className: cn("flex min-w-0 items-baseline", className), ...props, children: [_jsx("span", { className: "truncate", children: base }), ext ? _jsx("span", { className: "shrink-0", children: ext }) : null] }));
+}
+/* ------------------------------------------------------------------ */
+/* AttachmentList                                                       */
+/* ------------------------------------------------------------------ */
+const listVariants = cva("", {
+    variants: {
+        layout: {
+            list: "flex flex-col divide-y divide-line overflow-hidden rounded-ui border border-line",
+            grid: "grid grid-cols-[repeat(auto-fill,minmax(9.5rem,1fr))] gap-3",
+            chips: "flex flex-wrap gap-1.5",
+        },
+    },
+    defaultVariants: { layout: "list" },
+});
+/**
+ * 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 const AttachmentList = React.forwardRef(function AttachmentList({ items, layout = "list", size = "md", onPreview, onDownload, onRemove, onRetry, onAddFiles, accept, uploadSlot, readOnly, empty, labels, className, "aria-label": ariaLabel, ...props }, ref) {
+    const t = useLabels("attachments", attachmentLabels, labels);
+    const [removing, setRemoving] = React.useState(() => new Set());
+    const inputRef = React.useRef(null);
+    const remove = React.useCallback(async (file) => {
+        if (!onRemove)
+            return;
+        setRemoving((s) => new Set(s).add(file.id));
+        try {
+            await onRemove(file);
+        }
+        finally {
+            setRemoving((s) => {
+                const n = new Set(s);
+                n.delete(file.id);
+                return n;
+            });
+        }
+    }, [onRemove]);
+    const canAdd = !readOnly && Boolean(onAddFiles);
+    const hasTail = canAdd || (!readOnly && uploadSlot);
+    if (items.length === 0 && !hasTail) {
+        return (_jsxs("div", { ref: ref, "data-slot": "attachment-list", className: cn("flex items-center gap-2 rounded-ui border border-dashed border-line px-3 py-3 text-sm text-fg-subtle", className), ...props, children: [_jsx(Paperclip, { className: "size-4", "aria-hidden": true }), empty ?? t("empty")] }));
+    }
+    const addButton = canAdd ? (_jsxs(_Fragment, { children: [_jsx("input", { ref: inputRef, type: "file", multiple: true, accept: accept, hidden: true, tabIndex: -1, "aria-hidden": true, onChange: (e) => {
+                    const files = Array.from(e.currentTarget.files ?? []);
+                    if (files.length)
+                        onAddFiles(files);
+                    e.currentTarget.value = "";
+                } }), _jsxs("button", { type: "button", "data-slot": "attachment-add", onClick: () => inputRef.current?.click(), className: cn("inline-flex cursor-pointer items-center justify-center gap-1.5 text-fg-muted transition-colors hover:text-fg focus-ring [&_svg]:size-4", layout === "list" && "h-10 w-full px-3 text-[13px] hover:bg-hover", layout === "grid" && "aspect-[4/3] w-full flex-col rounded-ui border border-dashed border-field-border text-[13px] hover:border-field-border-hover hover:bg-hover", layout === "chips" && "h-7 rounded-full border border-dashed border-field-border px-2.5 text-xs hover:bg-hover"), children: [_jsx(Plus, { "aria-hidden": true }), t("add")] })] })) : null;
+    return (_jsxs("div", { ref: ref, role: "list", "aria-label": ariaLabel ?? t("list"), "data-slot": "attachment-list", "data-layout": layout, className: cn(listVariants({ layout }), className), ...props, children: [items.map((file) => (_jsx(AttachmentItem, { file: file, layout: layout, size: size, removing: removing.has(file.id), onPreview: onPreview, onDownload: onDownload, onRemove: readOnly || !onRemove ? undefined : remove, onRetry: readOnly ? undefined : onRetry, t: t }, file.id))), hasTail ? (_jsxs("div", { role: "listitem", "data-slot": "attachment-tail", className: cn(layout === "chips" && "contents"), children: [!readOnly ? uploadSlot : null, addButton] })) : null] }));
+});
+function AttachmentItem({ file, layout, size, removing, onPreview, onDownload, onRemove, onRetry, t }) {
+    const f = useFormat();
+    const status = file.status ?? "ready";
+    const ready = status === "ready";
+    const percent = f.percent(Math.max(0, Math.min(100, file.progress ?? 0)) / 100, { maximumFractionDigits: 0 });
+    const isImage = attachmentKind(file.mime, file.name) === "image";
+    const nameEl = ready && onPreview ? (_jsx("button", { type: "button", onClick: () => onPreview(file), className: "min-w-0 cursor-pointer text-start font-medium text-fg after:absolute after:inset-0 hover:underline focus-ring focus-visible:after:rounded-[inherit] underline-offset-2", children: _jsx(AttachmentName, { name: file.name }) })) : ready && file.url ? (_jsx("a", { href: file.url, target: "_blank", rel: "noreferrer", className: "min-w-0 font-medium text-fg after:absolute after:inset-0 hover:underline focus-ring underline-offset-2", children: _jsx(AttachmentName, { name: file.name }) })) : (_jsx(AttachmentName, { name: file.name, className: cn("font-medium", ready ? "text-fg" : "text-fg-muted") }));
+    const meta = [f.bytes(file.size)];
+    if (file.uploadedBy)
+        meta.push(file.uploadedBy);
+    if (file.uploadedAt)
+        meta.push(f.date(file.uploadedAt, "medium"));
+    const statusLine = status === "uploading" ? (_jsx("span", { className: "tabular", children: t("uploading", { percent }) })) : status === "processing" ? (_jsx("span", { children: t("processing") })) : status === "error" ? (_jsxs("span", { className: "inline-flex items-center gap-1 text-danger", children: [_jsx(AlertCircle, { className: "size-3.5", "aria-hidden": true }), file.error ?? t("failed")] })) : (_jsx("span", { className: "tabular", children: meta.join(" · ") }));
+    const progressBar = status === "uploading" || status === "processing" ? (_jsx("span", { role: "progressbar", "aria-label": file.name, "aria-valuemin": 0, "aria-valuemax": 100, "aria-valuenow": status === "uploading" ? (file.progress ?? 0) : undefined, "aria-valuetext": status === "uploading" ? t("progress", { percent, name: file.name }) : t("processing"), "data-indeterminate": status === "processing" ? "" : undefined, className: "ui-attachment-progress relative block h-1 w-full overflow-hidden rounded-full bg-track", children: _jsx("span", { className: "absolute inset-y-0 start-0 rounded-full bg-accent transition-[width] duration-300", style: status === "uploading" ? { width: `${file.progress ?? 0}%` } : undefined }) })) : null;
+    const download = ready && (onDownload || file.url) ? (onDownload ? (_jsx(IconButton, { label: t("download", { name: file.name }), size: "xs", tooltip: false, onClick: () => onDownload(file), children: _jsx(Download, {}) })) : (_jsx(IconButton, { asChild: true, label: t("download", { name: file.name }), size: "xs", tooltip: false, children: _jsx("a", { href: file.url, download: file.name, children: _jsx(Download, {}) }) }))) : null;
+    const actions = (_jsxs("span", { "data-slot": "attachment-actions", className: "relative z-1 flex shrink-0 items-center gap-0.5", children: [status === "error" && onRetry ? (_jsx(IconButton, { label: t("retry", { name: file.name }), size: "xs", tooltip: false, onClick: () => onRetry(file), children: _jsx(RotateCcw, {}) })) : null, layout !== "chips" && ready && onPreview ? (_jsx(IconButton, { label: t("preview", { name: file.name }), size: "xs", tooltip: false, onClick: () => onPreview(file), className: "max-sm:hidden", children: _jsx(Eye, {}) })) : null, layout !== "chips" ? download : null, onRemove ? (_jsx(IconButton, { label: t("remove", { name: file.name }), size: "xs", tooltip: false, variant: "ghost", disabled: removing, onClick: () => onRemove(file), className: "hover:text-danger", children: _jsx(X, {}) })) : null] }));
+    const common = {
+        role: "listitem",
+        "data-slot": "attachment",
+        "data-status": status,
+        "data-removing": removing ? "" : undefined,
+        "aria-busy": removing || status === "uploading" || status === "processing" || undefined,
+    };
+    if (layout === "chips") {
+        return (_jsxs("div", { ...common, className: cn("relative inline-flex h-7 max-w-64 items-center gap-1.5 rounded-full border border-line bg-surface-2 ps-1 pe-0.5 text-xs transition-opacity", status === "error" && "border-[color-mix(in_srgb,var(--danger)_40%,transparent)]", removing && "opacity-40", !onRemove && "pe-2.5"), children: [_jsx(AttachmentIcon, { mime: file.mime, name: file.name, size: "sm", className: "size-5 rounded-full [&_svg]:size-3" }), nameEl, _jsx("span", { className: "shrink-0 text-fg-subtle tabular", children: status === "uploading" ? percent : f.bytes(file.size) }), (onRemove || (status === "error" && onRetry)) ? actions : null] }));
+    }
+    if (layout === "grid") {
+        return (_jsxs("div", { ...common, className: cn("group relative flex min-w-0 flex-col overflow-hidden rounded-ui border border-line bg-surface-2 transition-[opacity,border-color] hover:border-field-border-hover", removing && "opacity-40"), children: [_jsxs("div", { className: "relative aspect-[4/3] overflow-hidden border-b border-line bg-[color-mix(in_oklch,var(--surface-2),var(--fg)_3%)]", children: [file.thumbUrl || (isImage && file.url && ready) ? (_jsx("img", { src: file.thumbUrl ?? file.url, alt: "", loading: "lazy", className: cn("size-full object-cover transition-transform duration-500 motion-safe:group-hover:scale-[1.03]", !ready && "opacity-50 grayscale") })) : (_jsx(AttachmentIcon, { mime: file.mime, name: file.name, size: "lg" })), progressBar ? _jsx("span", { className: "absolute inset-x-2 bottom-2", children: progressBar }) : null, _jsx("span", { className: "absolute end-1.5 top-1.5 z-1 flex rounded-ui-sm border border-popover-border bg-popover-nested p-0.5 shadow-sm transition-opacity sm:opacity-0 sm:group-hover:opacity-100 sm:group-focus-within:opacity-100 [@media(hover:none)]:opacity-100", children: actions })] }), _jsxs("div", { className: "grid min-w-0 gap-0.5 px-2.5 py-2 text-[13px]", children: [nameEl, _jsx("span", { className: "truncate text-[11.5px] text-fg-muted", children: statusLine })] })] }));
+    }
+    return (_jsxs("div", { ...common, className: cn("group relative flex items-center gap-3 bg-transparent transition-[opacity,background-color] hover:bg-hover", size === "sm" ? "min-h-11 px-2.5 py-1.5 text-[13px]" : "min-h-14 px-3 py-2 text-sm", removing && "opacity-40", status === "error" && "bg-[color-mix(in_srgb,var(--danger)_5%,transparent)]"), children: [isImage && (file.thumbUrl || file.url) && ready ? (_jsx("img", { src: file.thumbUrl ?? file.url, alt: "", loading: "lazy", className: cn("shrink-0 rounded-ui-sm object-cover ring-1 ring-line", size === "sm" ? "size-7" : "size-9") })) : (_jsx(AttachmentIcon, { mime: file.mime, name: file.name, size: size === "sm" ? "sm" : "md", className: size === "sm" ? "size-7" : undefined })), _jsxs("div", { className: "grid min-w-0 flex-1 gap-1", children: [nameEl, progressBar ? _jsxs("span", { className: "flex items-center gap-2 text-xs text-fg-muted", children: [progressBar, _jsx("span", { className: "shrink-0", children: statusLine })] }) : _jsx("span", { className: "truncate text-xs text-fg-muted", children: statusLine })] }), actions] }));
+}