@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/components/editor-layout.js

@@ -0,0 +1,237 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { Collapsible } from "radix-ui";
+import { ArrowLeft, Check, ChevronDown, CloudOff, PanelRight, TriangleAlert } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { useLabels } from "../lib/labels.js";
+import { useLocale } from "../lib/locale.js";
+import { SmartLink } from "../lib/provider.js";
+import { useHotkeys } from "../lib/use-hotkeys.js";
+import { useContainerWidth } from "../lib/use-container-width.js";
+import { useControllableState } from "../lib/use-controllable-state.js";
+import { useComposedRefs } from "../lib/compose-refs.js";
+import { Button } from "./button.js";
+import { ActionMenu } from "./dropdown-menu.js";
+import { Skeleton, SkeletonText } from "./skeleton.js";
+import { Spinner } from "./spinner.js";
+import { Sheet, SheetBody, SheetContent, SheetHeader } from "./sheet.js";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "./tabs.js";
+import { SidePaneHandle } from "./record-detail-layout.js";
+/* ------------------------------------------------------------------ */
+/* Labels & context                                                    */
+/* ------------------------------------------------------------------ */
+const editorLabels = {
+    panel: "Settings",
+    togglePanel: "Settings panel",
+    resizePanel: "Resize settings panel",
+    focusMode: "Focus mode",
+    exitFocusMode: "Exit focus mode",
+    moreActions: "More actions",
+    dirty: "Unsaved changes",
+    saving: "Saving…",
+    saved: "Saved {time}",
+    savedJustNow: "Saved just now",
+    savedPlain: "Saved",
+    error: "Couldn't save",
+    retry: "Retry",
+    offline: "Offline · changes kept locally",
+    loading: "Loading editor",
+};
+/** Below this container width (44rem) the side panel becomes a sheet. Matches navigation.css. */
+const NARROW = 704;
+const EditorLayoutContext = React.createContext(null);
+function useEditorLayout() {
+    return React.useContext(EditorLayoutContext);
+}
+/**
+ * The "edit one thing" page: a sticky bar with back link, title, save status and publish
+ * actions; a wide content canvas; and a side panel of collapsible settings sections (status,
+ * SEO, taxonomy…). Below 44rem (704px) of its own width the panel opens as a non-modal sheet.
+ *
+ * ```tsx
+ * <EditorLayout>
+ *   <EditorBar back={{ href: "/posts", label: "Posts" }} title="Spring menu launch"
+ *     status={<SaveStatus state="saved" at={savedAt} />}
+ *     actions={<><Button>Preview</Button><Button variant="primary">Publish</Button></>} />
+ *   <EditorCanvas width="prose">{editor}</EditorCanvas>
+ *   <EditorPanel>
+ *     <EditorPanelSection id="status" title="Status" summary="Draft">…</EditorPanelSection>
+ *   </EditorPanel>
+ * </EditorLayout>
+ * ```
+ */
+export const EditorLayout = React.forwardRef(function EditorLayout({ panelOpen: panelOpenProp, defaultPanelOpen = true, onPanelOpenChange, panelWidth: panelWidthProp, defaultPanelWidth = 320, onPanelWidthChange, resizable = false, focusMode: focusModeProp, defaultFocusMode = false, onFocusModeChange, readOnly = false, scroll = "page", stickyTop, shortcuts = true, labels, className, style, children, ...props }, ref) {
+    const { ref: measureRef, width } = useContainerWidth();
+    const composed = useComposedRefs(ref, measureRef);
+    const narrow = width !== undefined && width < NARROW;
+    const autoId = React.useId();
+    const panelId = `editor-panel${autoId.replace(/:/g, "")}`;
+    const [wideOpen, setWideOpen] = useControllableState({ value: panelOpenProp, defaultValue: defaultPanelOpen, onChange: onPanelOpenChange, name: "EditorLayout" });
+    const [sheetOpen, setSheetOpen] = React.useState(false);
+    const panelOpen = narrow ? (panelOpenProp !== undefined ? panelOpenProp : sheetOpen) : wideOpen;
+    const setPanelOpen = React.useCallback((open) => {
+        if (narrow) {
+            setSheetOpen(open);
+            onPanelOpenChange?.(open);
+        }
+        else
+            setWideOpen(open);
+    }, [narrow, setWideOpen, onPanelOpenChange]);
+    // Leaving the narrow layout closes the sheet; the wide panel keeps its own state.
+    React.useEffect(() => {
+        if (!narrow)
+            setSheetOpen(false);
+    }, [narrow]);
+    const [focusMode, setFocusMode] = useControllableState({ value: focusModeProp, defaultValue: defaultFocusMode, onChange: onFocusModeChange, name: "EditorLayout" });
+    const [panelWidth, setPanelWidth] = useControllableState({ value: panelWidthProp, defaultValue: defaultPanelWidth, onChange: onPanelWidthChange, name: "EditorLayout" });
+    // Focus mode: the bar dims after 1.5s without pointer movement.
+    const [idle, setIdle] = React.useState(false);
+    React.useEffect(() => {
+        if (!focusMode) {
+            setIdle(false);
+            return;
+        }
+        let timer = window.setTimeout(() => setIdle(true), 1500);
+        const wake = () => {
+            setIdle(false);
+            window.clearTimeout(timer);
+            timer = window.setTimeout(() => setIdle(true), 1500);
+        };
+        window.addEventListener("pointermove", wake);
+        return () => {
+            window.clearTimeout(timer);
+            window.removeEventListener("pointermove", wake);
+        };
+    }, [focusMode]);
+    // `mod+shift+,` — `,` is `<` with Shift on many layouts, so listen for both.
+    useHotkeys(["mod+shift+comma", "mod+shift+<"], () => setPanelOpen(!panelOpen), { enabled: shortcuts && !focusMode });
+    useHotkeys("mod+shift+f", () => setFocusMode(!focusMode), { enabled: shortcuts });
+    useHotkeys("escape", () => setFocusMode(false), { enabled: focusMode, preventDefault: false });
+    const ctx = React.useMemo(() => ({ panelId, panelOpen: panelOpen && !focusMode, setPanelOpen, narrow, focusMode, setFocusMode, readOnly, idle, resizable, panelWidth, defaultPanelWidth, setPanelWidth, labels }), [panelId, panelOpen, setPanelOpen, narrow, focusMode, setFocusMode, readOnly, idle, resizable, panelWidth, defaultPanelWidth, setPanelWidth, labels]);
+    const top = stickyTop === undefined ? undefined : typeof stickyTop === "number" ? `${stickyTop}px` : stickyTop;
+    return (_jsx(EditorLayoutContext.Provider, { value: ctx, children: _jsx("div", { ref: composed, "data-slot": "editor-layout", "data-scroll": scroll, "data-focus-mode": focusMode ? "" : undefined, "data-read-only": readOnly ? "" : undefined, className: cn("@container/editor relative w-full min-w-0", scroll === "panes" && "h-full min-h-0", className), style: { "--editor-panel-w": `${panelWidth}px`, ...(top !== undefined ? { "--editor-sticky-top": top } : null), ...style }, ...props, children: _jsx("div", { className: "vui-editor-grid", "data-panel": ctx.panelOpen && !narrow ? "open" : "closed", "data-scroll": scroll, children: children }) }) }));
+});
+/** The sticky publish bar: back, title, save status, actions, panel toggle. */
+export const EditorBar = React.forwardRef(function EditorBar({ back, title, status, actions, secondaryActions, menu, panelToggle = true, focusToggle = false, labels, className, children, ...props }, ref) {
+    const ctx = useEditorLayout();
+    const t = useLabels("editor", editorLabels, labels ?? ctx?.labels);
+    const readOnly = ctx?.readOnly ?? false;
+    return (_jsxs("div", { ref: ref, "data-slot": "editor-bar", "data-idle": ctx?.idle ? "" : undefined, className: cn("vui-editor-bar surface-bar flex h-(--editor-bar-h,3.5rem) min-w-0 items-center gap-2 px-3 @2xl/editor:gap-3 @2xl/editor:px-4", className), ...props, children: [back ? (_jsxs(SmartLink, { href: back.href, "aria-label": back.label, className: "inline-flex h-8 shrink-0 items-center gap-1.5 rounded-ui-sm px-2 text-[13px] text-fg-muted transition-colors hover:bg-hover hover:text-fg focus-ring", children: [_jsx(ArrowLeft, { "aria-hidden": true, className: "size-4 rtl:-scale-x-100" }), _jsx("span", { "aria-hidden": true, className: "hidden @3xl/editor:inline", children: back.label })] })) : null, back && title ? _jsx("span", { "aria-hidden": true, className: "hidden h-5 w-px bg-line @3xl/editor:block" }) : null, _jsx("div", { "data-slot": "editor-bar-title", className: "min-w-0 flex-1 truncate text-[14px] font-medium text-fg", children: title }), status ? _jsx("div", { className: "hidden shrink-0 @md/editor:block", children: status }) : null, _jsxs("div", { className: "flex shrink-0 items-center gap-1.5", children: [secondaryActions && !readOnly ? _jsx("div", { className: "hidden items-center gap-1.5 @2xl/editor:flex", children: secondaryActions }) : null, actions && !readOnly ? actions : null, children, menu?.length ? _jsx(ActionMenu, { items: menu, triggerSize: "sm", triggerLabel: t("moreActions") }) : null, focusToggle && ctx ? (_jsx(Button, { variant: "ghost", size: "sm", "aria-pressed": ctx.focusMode, onClick: () => ctx.setFocusMode(!ctx.focusMode), "aria-keyshortcuts": "Control+Shift+F Meta+Shift+F", children: ctx.focusMode ? t("exitFocusMode") : t("focusMode") })) : null, panelToggle && ctx && !ctx.focusMode ? (_jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": t("togglePanel"), title: t("togglePanel"), "aria-expanded": ctx.panelOpen, "aria-controls": ctx.panelOpen || !ctx.narrow ? ctx.panelId : undefined, "aria-keyshortcuts": "Control+Shift+Comma Meta+Shift+Comma", "data-active": ctx.panelOpen ? "" : undefined, onClick: () => ctx.setPanelOpen(!ctx.panelOpen), className: "data-active:bg-selected", children: _jsx(PanelRight, { "aria-hidden": true, className: "rtl:-scale-x-100" }) })) : null] })] }));
+});
+const UNITS = [
+    ["day", 86400],
+    ["hour", 3600],
+    ["minute", 60],
+];
+/**
+ * Where the document's changes are: "Unsaved changes" · "Saving…" · "Saved 2 min ago" ·
+ * "Couldn't save · Retry" · "Offline · changes kept locally". A polite status; the error is an alert.
+ */
+export const SaveStatus = React.forwardRef(function SaveStatus({ state, at, onRetry, guard = true, now: nowProp, labels, className, ...props }, ref) {
+    const ctx = useEditorLayout();
+    const t = useLabels("editor", editorLabels, labels ?? ctx?.labels);
+    const { locale } = useLocale();
+    const [tick, setTick] = React.useState(0);
+    React.useEffect(() => {
+        if (state !== "saved" || at === undefined || nowProp !== undefined)
+            return;
+        const id = window.setInterval(() => setTick((n) => n + 1), 30_000);
+        return () => window.clearInterval(id);
+    }, [state, at, nowProp]);
+    React.useEffect(() => {
+        if (!guard || (state !== "dirty" && state !== "saving"))
+            return;
+        const onBeforeUnload = (e) => {
+            e.preventDefault();
+            e.returnValue = "";
+        };
+        window.addEventListener("beforeunload", onBeforeUnload);
+        return () => window.removeEventListener("beforeunload", onBeforeUnload);
+    }, [guard, state]);
+    const savedText = React.useMemo(() => {
+        if (at === undefined)
+            return t("savedPlain");
+        const now = nowProp !== undefined ? +nowProp : Date.now();
+        const secs = Math.round((now - +at) / 1000);
+        if (secs < 45)
+            return t("savedJustNow");
+        const rtf = new Intl.RelativeTimeFormat(locale, { numeric: "auto", style: "short" });
+        for (const [unit, size] of UNITS) {
+            if (secs >= size || unit === "minute")
+                return t("saved", { time: rtf.format(-Math.max(1, Math.round(secs / size)), unit) });
+        }
+        return t("savedPlain");
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [at, nowProp, locale, t, tick]);
+    const content = state === "dirty" ? (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": true, className: "size-1.5 rounded-full bg-warning" }), t("dirty")] })) : state === "saving" ? (_jsxs(_Fragment, { children: [_jsx(Spinner, { size: "xs" }), t("saving")] })) : state === "saved" ? (_jsxs(_Fragment, { children: [_jsx(Check, { "aria-hidden": true, className: "size-3.5 text-success" }), savedText] })) : state === "offline" ? (_jsxs(_Fragment, { children: [_jsx(CloudOff, { "aria-hidden": true, className: "size-3.5" }), t("offline")] })) : null;
+    return (_jsxs("span", { ref: ref, "data-slot": "save-status", "data-state": state, className: cn("inline-flex items-center gap-1.5 whitespace-nowrap text-[13px] text-fg-subtle", className), ...props, children: [_jsx("span", { role: "status", className: "inline-flex items-center gap-1.5", children: content }), state === "error" ? (_jsxs("span", { role: "alert", className: "inline-flex items-center gap-1.5 text-danger", children: [_jsx(TriangleAlert, { "aria-hidden": true, className: "size-3.5" }), t("error"), onRetry ? (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": true, children: "\u00B7" }), _jsx("button", { type: "button", onClick: onRetry, className: "rounded-ui-sm font-medium underline underline-offset-2 hover:no-underline focus-ring", children: t("retry") })] })) : null] })) : null] }));
+});
+/* ------------------------------------------------------------------ */
+/* EditorCanvas                                                        */
+/* ------------------------------------------------------------------ */
+const canvasWidth = { prose: "max-w-[720px]", wide: "max-w-[1080px]", full: "max-w-none" };
+/** The writing area: a centred column with generous margins. */
+export const EditorCanvas = React.forwardRef(function EditorCanvas({ width = "prose", tone = "surface", notice, loading, labels, className, children, ...props }, ref) {
+    const ctx = useEditorLayout();
+    const t = useLabels("editor", editorLabels, labels ?? ctx?.labels);
+    return (_jsx("div", { ref: ref, "data-slot": "editor-canvas", "data-tone": tone, "aria-busy": loading || undefined, className: cn("vui-editor-canvas min-w-0 px-[var(--gutter,1.5rem)] py-8 @3xl/editor:py-12", tone === "surface" ? "bg-surface" : "bg-transparent", className), ...props, children: _jsxs("div", { className: cn("mx-auto flex w-full flex-col gap-6", canvasWidth[width]), children: [notice, loading ? (_jsxs("div", { role: "status", "aria-label": t("loading"), className: "grid gap-6", children: [_jsx(Skeleton, { className: "h-10 w-3/4 rounded-ui-sm" }), _jsx(SkeletonText, { lines: 4 }), _jsx(SkeletonText, { lines: 5 })] })) : (children)] }) }));
+});
+/** The side panel: `<aside>` of collapsible settings sections; a non-modal sheet on narrow layouts. */
+export const EditorPanel = React.forwardRef(function EditorPanel({ tabs, value: valueProp, defaultValue, onValueChange, footer, labels, className, children, ...props }, ref) {
+    const ctx = useEditorLayout();
+    const t = useLabels("editor", editorLabels, labels ?? ctx?.labels);
+    const [value, setValue] = useControllableState({ value: valueProp, defaultValue: defaultValue ?? tabs?.[0]?.id ?? "", onChange: onValueChange, name: "EditorPanel" });
+    const label = props["aria-label"] ?? t("panel");
+    let inner = children;
+    if (tabs?.length) {
+        inner = (_jsxs(Tabs, { value: value, onValueChange: setValue, className: "gap-0", children: [_jsx("div", { className: "sticky top-0 z-[1] border-b border-line bg-surface px-3 py-2.5", children: _jsx(TabsList, { variant: "segmented", size: "sm", fill: true, "aria-label": label, children: tabs.map((tab) => (_jsx(TabsTrigger, { value: tab.id, children: tab.label }, tab.id))) }) }), children] }));
+    }
+    const body = (_jsxs("fieldset", { disabled: ctx?.readOnly || undefined, className: "m-0 flex min-h-0 min-w-0 flex-1 flex-col border-0 p-0", children: [_jsx("div", { className: "min-h-0 flex-1", children: inner }), footer ? _jsx("div", { className: "sticky bottom-0 border-t border-line bg-surface px-4 py-3", children: footer }) : null] }));
+    if (ctx?.narrow) {
+        return (_jsx(Sheet, { open: ctx.panelOpen, onOpenChange: ctx.setPanelOpen, modal: false, children: _jsxs(SheetContent, { side: "end", size: "sm", id: ctx.panelId, children: [_jsx(SheetHeader, { title: label }), _jsx(SheetBody, { className: "p-0", children: _jsx("section", { "aria-label": label, className: cn("flex min-h-full flex-col", className), children: body }) })] }) }));
+    }
+    return (_jsxs("aside", { ref: ref, id: ctx?.panelId, "aria-label": label, hidden: ctx ? !ctx.panelOpen : undefined, "data-slot": "editor-panel", className: cn("vui-editor-panel relative flex min-w-0 flex-col border-s border-line bg-surface", className), ...props, children: [ctx?.resizable ? (_jsx(SidePaneHandle, { "aria-label": t("resizePanel"), edge: "start", value: ctx.panelWidth, min: 280, max: 520, defaultValue: ctx.defaultPanelWidth, onValueChange: ctx.setPanelWidth, className: "-start-1" })) : null, body] }));
+});
+/** The sections of one panel tab (`value` matches a tab `id`). */
+export const EditorPanelContent = React.forwardRef(function EditorPanelContent({ className, ...props }, ref) {
+    return _jsx(TabsContent, { ref: ref, className: cn("mt-0", className), ...props });
+});
+const storageKey = (id) => `vui:editor-section:${id}`;
+function readStored(id) {
+    if (!id || typeof window === "undefined")
+        return undefined;
+    try {
+        const v = window.localStorage.getItem(storageKey(id));
+        return v === "1" ? true : v === "0" ? false : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A folding meta box in the panel: Status, Permalink, Categories, Featured image, SEO. */
+export const EditorPanelSection = React.forwardRef(function EditorPanelSection({ id, title, summary, defaultOpen = false, open: openProp, onOpenChange, actions, headingLevel = 2, className, children, ...props }, ref) {
+    const [open, setOpen] = useControllableState({ value: openProp, defaultValue: defaultOpen, onChange: onOpenChange, name: "EditorPanelSection" });
+    // Restore after mount (SSR renders the default).
+    React.useEffect(() => {
+        if (openProp !== undefined)
+            return;
+        const stored = readStored(id);
+        if (stored !== undefined)
+            setOpen(stored);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [id]);
+    const autoId = React.useId();
+    const titleId = `editor-section${autoId.replace(/:/g, "")}`;
+    const H = `h${headingLevel}`;
+    return (_jsx(Collapsible.Root, { open: open, onOpenChange: (v) => {
+            setOpen(v);
+            if (id)
+                try {
+                    window.localStorage.setItem(storageKey(id), v ? "1" : "0");
+                }
+                catch {
+                    /* storage blocked */
+                }
+        }, asChild: true, children: _jsxs("section", { ref: ref, "aria-labelledby": titleId, "data-slot": "editor-panel-section", "data-section": id, className: cn("group/section border-b border-line last:border-b-0", className), ...props, children: [_jsxs("div", { className: "flex items-center gap-1 pe-2", children: [_jsx(H, { id: titleId, className: "min-w-0 flex-1", children: _jsxs(Collapsible.Trigger, { className: "flex w-full min-w-0 items-center gap-2 py-3 ps-4 pe-2 text-start outline-none transition-colors hover:bg-hover focus-visible:bg-hover focus-ring focus-visible:outline-offset-[-2px]", children: [_jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: "block truncate text-[13px] font-semibold text-fg", children: title }), summary && !open ? _jsx("span", { className: "mt-0.5 block truncate text-[12px] font-normal text-fg-subtle", children: summary }) : null] }), _jsx(ChevronDown, { "aria-hidden": true, className: "size-4 shrink-0 text-fg-subtle transition-transform duration-200 group-data-[state=open]/section:rotate-180 motion-reduce:transition-none" })] }) }), actions ? _jsx("div", { className: "flex shrink-0 items-center gap-1", children: actions }) : null] }), _jsx(Collapsible.Content, { className: "ui-collapse", children: _jsx("div", { className: "grid gap-3 px-4 pb-4 pt-0.5 text-[13px]", children: children }) })] }) }));
+});

package/dist/components/empty-state.d.ts

@@ -0,0 +1,49 @@
+import * as React from "react";
+export type EmptyStateKind = "first-use" | "no-results" | "error" | "forbidden" | "done";
+export declare const emptyStateVariants: (props?: ({
+    size?: "sm" | "md" | "lg" | null | undefined;
+    framed?: boolean | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export interface EmptyStateProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+    /** Picks the default icon, its tint and the default title. Default `"first-use"`. */
+    kind?: EmptyStateKind;
+    /** `sm` inside a table/card, `md` a page section, `lg` a full page. Default `"md"`. */
+    size?: "sm" | "md" | "lg";
+    /** Replace the kind's icon, or `false` for none. */
+    icon?: React.ReactNode | false;
+    /** A larger picture in place of the icon well (SVG, image). */
+    illustration?: React.ReactNode;
+    /** Default copy comes from the dictionary (`empty.firstUse`, `empty.noResults`…). */
+    title?: React.ReactNode;
+    description?: React.ReactNode;
+    /** One primary next step, optionally a secondary one. */
+    actions?: React.ReactNode;
+    /** Dashed frame — a drop zone or an empty column. */
+    framed?: boolean;
+    /** Title element. Default `"h3"`. */
+    as?: "h2" | "h3" | "h4" | "p";
+}
+/**
+ * Points to a next step when a list is empty, a search finds nothing, access is denied or
+ * something failed. Server-compatible. A `no-results` state is announced (`role="status"`).
+ *
+ * ```tsx
+ * <EmptyState
+ *   title="No posts yet"
+ *   description="Write your first post, or import from WordPress."
+ *   actions={<Button variant="primary">Write a post</Button>}
+ * />
+ * <EmptyState kind="no-results" size="sm" actions={<Button size="sm" onClick={clear}>Clear filters</Button>} />
+ * ```
+ */
+export declare const EmptyState: React.ForwardRefExoticComponent<EmptyStateProps & React.RefAttributes<HTMLDivElement>>;
+/** The icon well (sits on two faint contour rings). */
+export declare function EmptyStateIcon({ className, children, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
+export declare function EmptyStateTitle({ as: Tag, size, className, ...props }: React.HTMLAttributes<HTMLHeadingElement> & {
+    as?: "h2" | "h3" | "h4" | "p";
+    size?: "sm" | "md" | "lg";
+}): React.JSX.Element;
+export declare function EmptyStateDescription({ size, className, ...props }: React.HTMLAttributes<HTMLParagraphElement> & {
+    size?: "sm" | "md" | "lg";
+}): React.JSX.Element;
+export declare function EmptyStateActions({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;

package/dist/components/empty-state.js

@@ -0,0 +1,68 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cva } from "class-variance-authority";
+import { CircleCheck, FilePlus2, LockKeyhole, SearchX, TriangleAlert } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { LocalizedText } from "../lib/islands.js";
+const emptyLabels = {
+    firstUse: "Nothing here yet",
+    noResults: "No results match your filters",
+    error: "Something went wrong",
+    forbidden: "You don't have access to this page",
+    done: "You're all caught up",
+    retry: "Try again",
+};
+const KIND = {
+    "first-use": { icon: FilePlus2, label: "firstUse", well: "bg-accent-soft text-accent-ink" },
+    "no-results": { icon: SearchX, label: "noResults", well: "surface-2 text-fg-muted" },
+    error: { icon: TriangleAlert, label: "error", well: "tone-danger tone-soft" },
+    forbidden: { icon: LockKeyhole, label: "forbidden", well: "surface-2 text-fg-muted" },
+    done: { icon: CircleCheck, label: "done", well: "tone-success tone-soft" },
+};
+export const emptyStateVariants = cva("vui-empty flex w-full flex-col items-center text-center", {
+    variants: {
+        size: {
+            /** Inside a table, card or popover. */
+            sm: "gap-2.5 px-4 py-8 [--empty-well:2.5rem] [--empty-icon:1.125rem]",
+            /** A page section. */
+            md: "gap-3 px-6 py-14 [--empty-well:3rem] [--empty-icon:1.375rem]",
+            /** A whole page. */
+            lg: "gap-4 px-6 py-24 [--empty-well:3.75rem] [--empty-icon:1.625rem]",
+        },
+        framed: {
+            true: "rounded-ui-lg border border-dashed border-field-border",
+        },
+    },
+    defaultVariants: { size: "md" },
+});
+/**
+ * Points to a next step when a list is empty, a search finds nothing, access is denied or
+ * something failed. Server-compatible. A `no-results` state is announced (`role="status"`).
+ *
+ * ```tsx
+ * <EmptyState
+ *   title="No posts yet"
+ *   description="Write your first post, or import from WordPress."
+ *   actions={<Button variant="primary">Write a post</Button>}
+ * />
+ * <EmptyState kind="no-results" size="sm" actions={<Button size="sm" onClick={clear}>Clear filters</Button>} />
+ * ```
+ */
+export const EmptyState = React.forwardRef(function EmptyState({ kind = "first-use", size = "md", icon, illustration, title, description, actions, framed, as = "h3", className, children, role, ...props }, ref) {
+    const k = KIND[kind];
+    const Icon = k.icon;
+    return (_jsxs("div", { ref: ref, "data-slot": "empty-state", "data-kind": kind, "data-size": size, role: role ?? (kind === "no-results" ? "status" : undefined), className: cn(emptyStateVariants({ size, framed }), className), ...props, children: [illustration ? (_jsx("div", { "data-slot": "empty-state-illustration", className: cn("mb-1 flex justify-center text-fg-subtle", size === "lg" ? "max-w-72" : "max-w-48"), children: illustration })) : icon === false ? null : (_jsx(EmptyStateIcon, { className: cn(k.well, size === "sm" ? "mb-1" : "mb-2"), children: icon ?? _jsx(Icon, { "aria-hidden": true }) })), _jsx(EmptyStateTitle, { as: as, size: size, children: title ?? _jsx(LocalizedText, { namespace: "empty", id: k.label, defaults: emptyLabels }) }), description ? _jsx(EmptyStateDescription, { size: size, children: description }) : null, children, actions ? _jsx(EmptyStateActions, { className: size === "sm" ? "mt-1" : "mt-2", children: actions }) : null] }));
+});
+/** The icon well (sits on two faint contour rings). */
+export function EmptyStateIcon({ className, children, ...props }) {
+    return (_jsx("div", { "aria-hidden": true, "data-slot": "empty-state-icon", className: cn("vui-empty-well flex size-(--empty-well,3rem) items-center justify-center rounded-ui [&_svg]:size-(--empty-icon,1.375rem) [&_svg]:stroke-[1.75]", className), ...props, children: children }));
+}
+export function EmptyStateTitle({ as: Tag = "h3", size = "md", className, ...props }) {
+    return (_jsx(Tag, { "data-slot": "empty-state-title", className: cn("max-w-[36ch] text-balance text-fg", size === "sm" && "text-sm font-semibold", size === "md" && "text-base font-semibold tracking-[-0.01em]", size === "lg" && "font-display text-[1.75rem] leading-tight", className), ...props }));
+}
+export function EmptyStateDescription({ size = "md", className, ...props }) {
+    return (_jsx("p", { "data-slot": "empty-state-description", className: cn("max-w-[44ch] text-pretty text-fg-muted", size === "sm" ? "-mt-1 text-[13px]" : size === "lg" ? "-mt-1 text-[15px] leading-relaxed" : "-mt-1 text-sm leading-relaxed", className), ...props }));
+}
+export function EmptyStateActions({ className, ...props }) {
+    return _jsx("div", { "data-slot": "empty-state-actions", className: cn("flex flex-wrap items-center justify-center gap-2", className), ...props });
+}

package/dist/components/entity-card.d.ts

@@ -0,0 +1,83 @@
+import * as React from "react";
+import { type ValueFormat } from "../lib/value-format.js";
+import { type DescriptionEntry } from "./description-list.js";
+export type EntityKind = "person" | "organization" | "product" | "generic";
+export type EntityTone = "neutral" | "accent" | "success" | "warning" | "danger" | "info";
+/** A compact fact in the card's stat row ("Open deals · 4", "Lifetime value · $182,400"). */
+export interface EntityStat {
+    label: string;
+    value: number | string;
+    format?: ValueFormat;
+}
+export declare const entityCardLabels: {
+    email: string;
+    call: string;
+    website: string;
+    archived: string;
+    selected: string;
+};
+export type EntityCardLabels = Partial<typeof entityCardLabels>;
+export interface EntityCardProps extends Omit<React.HTMLAttributes<HTMLElement>, "title"> {
+    /** Changes defaults only: avatar shape and fallback icon. Default `"person"`. */
+    kind?: EntityKind;
+    name: string;
+    /** Role · company, domain, SKU. */
+    subtitle?: React.ReactNode;
+    /** Photo, logo or product image. Missing → initials (person, organization) or an icon. */
+    media?: {
+        src?: string | null;
+        alt?: string;
+        fallback?: React.ReactNode;
+    };
+    /** Badges after the name (tags, plan, segment). */
+    badges?: React.ReactNode;
+    /** One status pill ("Active", "Out of stock"). */
+    status?: {
+        tone: EntityTone;
+        label: string;
+    };
+    /** Key facts — a mini Description list. */
+    fields?: DescriptionEntry[];
+    /** 2–3 numbers in a row. */
+    stats?: EntityStat[];
+    /** Quick actions. Each is a labelled button or link ("Email Jane Cooper"). */
+    actions?: React.ReactNode;
+    /** Built-in labelled quick actions: mailto / tel / website links. */
+    contact?: {
+        email?: string;
+        phone?: string;
+        website?: string;
+    };
+    /** Short free text (bio, product summary). */
+    description?: React.ReactNode;
+    /** The name becomes the card's one primary link (stretched over the card). */
+    href?: string;
+    /** `card` (grid tile), `compact` (row in a side panel), `header` (top of a record page), `chip` (inline name with a hover card). Default `"card"`. */
+    variant?: "card" | "compact" | "header" | "chip";
+    /** Heading level of the name. Default `h3` (`h1` for `header`). */
+    headingAs?: "h1" | "h2" | "h3" | "h4" | "p";
+    /** Muted with an "Archived" badge. */
+    archived?: boolean;
+    /** Picker state: accent outline + `aria-current`. */
+    selected?: boolean;
+    /** Skeleton in the variant's shape. */
+    loading?: boolean;
+    labels?: EntityCardLabels;
+}
+/**
+ * The identity of a record at a glance — a contact, a company, a product, an employee — with
+ * key facts and quick actions. An `<article>` with the name as its heading; with `href` the name
+ * is the one primary link (stretched over the card) and actions stay separate, labelled buttons.
+ *
+ * ```tsx
+ * <EntityCard
+ *   name="Jane Cooper"
+ *   subtitle="Head of Operations · Northwind Traders"
+ *   status={{ tone: "success", label: "Customer" }}
+ *   contact={{ email: "jane@northwind.com", phone: "+1 415 555 0136" }}
+ *   fields={[{ key: "owner", label: "Owner", value: "Ayşe Kaya" }]}
+ *   href="/contacts/jane-cooper"
+ * />
+ * ```
+ */
+export declare const EntityCard: React.ForwardRefExoticComponent<EntityCardProps & React.RefAttributes<HTMLElement>>;

package/dist/components/entity-card.js

@@ -0,0 +1,92 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { Building2, Globe, Mail, Package, Phone, Shapes, UserRound } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { useLabels } from "../lib/labels.js";
+import { useFormat } from "../lib/locale.js";
+import { formatValue } from "../lib/value-format.js";
+import { Avatar } from "./avatar.js";
+import { Badge } from "./badge.js";
+import { IconButton } from "./button.js";
+import { DescriptionList } from "./description-list.js";
+import { HoverCard, HoverCardContent, HoverCardTrigger } from "./hover-card.js";
+import { Skeleton } from "./skeleton.js";
+export const entityCardLabels = {
+    email: "Email {name}",
+    call: "Call {name}",
+    website: "Open {name}'s website",
+    archived: "Archived",
+    selected: "Selected",
+};
+const KIND_ICON = { person: UserRound, organization: Building2, product: Package, generic: Shapes };
+function EntityMedia({ kind, name, media, size, className }) {
+    const Icon = KIND_ICON[kind];
+    if (kind === "product" || size === "product" || size === "product-lg") {
+        const big = size === "product-lg";
+        return (_jsx("span", { "data-slot": "entity-media", className: cn("relative flex shrink-0 items-center justify-center overflow-hidden bg-surface-2 text-fg-subtle ring-1 ring-inset ring-line", big ? "aspect-[4/3] w-full rounded-[calc(var(--radius)-2px)]" : size === "xl" ? "size-16 rounded-ui" : size === "lg" ? "size-12 rounded-ui-sm" : "size-10 rounded-ui-sm", className), children: media?.src ? _jsx("img", { src: media.src, alt: media.alt ?? "", loading: "lazy", className: "size-full object-cover" }) : (media?.fallback ?? _jsx(Icon, { "aria-hidden": true, strokeWidth: 1.5, className: big ? "size-9" : "size-5" })) }));
+    }
+    const avatarSize = size;
+    return (_jsx(Avatar, { "data-slot": "entity-media", name: name, src: media?.src, size: avatarSize, shape: kind === "person" ? "circle" : "square", fallback: media?.fallback ?? (kind === "generic" ? _jsx(Icon, { "aria-hidden": true }) : undefined), className: cn("ring-2 ring-(--surface-solid)", className), "aria-hidden": true }));
+}
+function EntityStats({ stats, size = "md" }) {
+    const f = useFormat();
+    return (_jsx("dl", { "data-slot": "entity-stats", className: "flex flex-wrap gap-y-2", children: stats.map((s) => (_jsxs("div", { className: "grid min-w-0 flex-auto gap-0.5 border-s border-line px-3 first:border-s-0 first:ps-0 last:pe-0", children: [_jsx("dt", { className: "truncate text-[11.5px] text-fg-muted", children: s.label }), _jsx("dd", { className: cn("whitespace-nowrap font-heading font-semibold tracking-[-0.01em] text-fg tabular", size === "lg" ? "text-xl" : size === "sm" ? "text-sm" : "text-base"), children: typeof s.value === "number" ? formatValue(f, s.value, s.format ?? "number") : s.format && !Number.isNaN(Number(s.value)) ? formatValue(f, s.value, s.format) : s.value })] }, s.label))) }));
+}
+function ContactActions({ name, contact, t, size = "sm" }) {
+    return (_jsxs(_Fragment, { children: [contact.email ? (_jsx(IconButton, { asChild: true, label: t("email", { name }), size: size, variant: "secondary", tooltip: false, children: _jsx("a", { href: `mailto:${contact.email}`, children: _jsx(Mail, {}) }) })) : null, contact.phone ? (_jsx(IconButton, { asChild: true, label: t("call", { name }), size: size, variant: "secondary", tooltip: false, children: _jsx("a", { href: `tel:${contact.phone.replace(/[^\d+]/g, "")}`, children: _jsx(Phone, {}) }) })) : null, contact.website ? (_jsx(IconButton, { asChild: true, label: t("website", { name }), size: size, variant: "secondary", tooltip: false, children: _jsx("a", { href: contact.website, target: "_blank", rel: "noreferrer", children: _jsx(Globe, {}) }) })) : null] }));
+}
+/**
+ * The identity of a record at a glance — a contact, a company, a product, an employee — with
+ * key facts and quick actions. An `<article>` with the name as its heading; with `href` the name
+ * is the one primary link (stretched over the card) and actions stay separate, labelled buttons.
+ *
+ * ```tsx
+ * <EntityCard
+ *   name="Jane Cooper"
+ *   subtitle="Head of Operations · Northwind Traders"
+ *   status={{ tone: "success", label: "Customer" }}
+ *   contact={{ email: "jane@northwind.com", phone: "+1 415 555 0136" }}
+ *   fields={[{ key: "owner", label: "Owner", value: "Ayşe Kaya" }]}
+ *   href="/contacts/jane-cooper"
+ * />
+ * ```
+ */
+export const EntityCard = React.forwardRef(function EntityCard({ kind = "person", name, subtitle, media, badges, status, fields, stats, actions, contact, description, href, variant = "card", headingAs, archived, selected, loading, labels, className, ...props }, ref) {
+    const t = useLabels("entityCard", entityCardLabels, labels);
+    const H = headingAs ?? (variant === "header" ? "h1" : "h3");
+    const headingId = React.useId();
+    if (variant === "chip") {
+        const chip = (_jsxs("span", { className: "inline-flex max-w-full items-center gap-1.5 align-middle", children: [_jsx(EntityMedia, { kind: kind, name: name, media: media, size: "xs", className: "ring-0" }), _jsx("span", { className: "truncate font-medium", children: name })] }));
+        return (_jsxs(HoverCard, { children: [_jsx(HoverCardTrigger, { asChild: true, children: href ? (_jsx("a", { ref: ref, href: href, "data-slot": "entity-chip", className: cn("inline-flex max-w-full rounded-full py-0.5 pe-2 ps-0.5 text-[13px] text-fg hover:bg-hover focus-ring", className), ...props, children: chip })) : (_jsx("span", { ref: ref, tabIndex: 0, "data-slot": "entity-chip", className: cn("inline-flex max-w-full cursor-default rounded-full py-0.5 pe-2 ps-0.5 text-[13px] text-fg hover:bg-hover focus-ring", className), ...props, children: chip })) }), _jsx(HoverCardContent, { className: "w-80 p-0", children: _jsx(EntityCardPreview, { kind: kind, name: name, subtitle: subtitle, media: media, badges: badges, status: status, fields: fields, stats: stats, contact: contact, actions: actions, description: description, archived: archived, headingAs: "p", className: "border-0 bg-transparent shadow-none backdrop-blur-none", labels: labels }) })] }));
+    }
+    if (loading) {
+        return (_jsxs("article", { ref: ref, "aria-busy": "true", "data-slot": "entity-card", "data-variant": variant, className: cn(variant === "card" && "surface rounded-ui p-(--gap)", variant === "compact" && "flex items-center gap-3 py-2", variant === "header" && "flex items-center gap-5", className), ...props, children: [_jsxs("span", { className: cn("flex items-center gap-3", variant === "card" && "mb-4"), children: [_jsx(Skeleton, { shape: "circle", className: variant === "header" ? "size-16" : variant === "compact" ? "size-8" : "size-10" }), _jsxs("span", { className: "grid flex-1 gap-2", children: [_jsx(Skeleton, { className: cn("h-4 rounded-ui-sm", variant === "header" ? "w-56" : "w-32") }), _jsx(Skeleton, { className: "h-3 w-44 rounded-ui-sm" })] })] }), variant === "card" ? (_jsxs("span", { className: "grid gap-2", children: [_jsx(Skeleton, { className: "h-3 w-full rounded-ui-sm" }), _jsx(Skeleton, { className: "h-3 w-4/5 rounded-ui-sm" })] })) : null] }));
+    }
+    const title = (_jsx(H, { id: headingId, className: cn("min-w-0 text-fg", variant === "header" ? "font-heading text-2xl font-semibold tracking-[-0.02em] sm:text-[1.75rem]" : variant === "compact" ? "truncate text-[13.5px] font-semibold" : "truncate text-[15px] font-semibold tracking-[-0.005em]"), children: href ? (_jsx("a", { href: href, className: "rounded-ui-sm outline-none after:absolute after:inset-0 after:rounded-[inherit] after:content-[''] hover:underline underline-offset-[3px] focus-visible:after:outline-2 focus-visible:after:outline-offset-2 focus-visible:after:outline-(--ring)", children: name })) : (name) }));
+    const pills = status || badges || archived ? (_jsxs("span", { "data-slot": "entity-badges", className: "flex flex-wrap items-center gap-1", children: [status ? (_jsx(Badge, { tone: status.tone, dot: true, children: status.label })) : null, archived ? _jsx(Badge, { tone: "outline", children: t("archived") }) : null, badges] })) : null;
+    const quick = contact || actions ? (_jsxs("div", { "data-slot": "entity-actions", className: "relative z-1 flex shrink-0 flex-wrap items-center gap-1.5", children: [contact ? _jsx(ContactActions, { name: name, contact: contact, t: t, size: variant === "compact" ? "xs" : "sm" }) : null, actions] })) : null;
+    const shared = {
+        ref,
+        "data-slot": "entity-card",
+        "data-variant": variant,
+        "data-kind": kind,
+        "data-archived": archived ? "" : undefined,
+        "aria-labelledby": headingId,
+        "aria-current": selected ? true : undefined,
+        ...props,
+    };
+    if (variant === "compact") {
+        return (_jsxs("article", { ...shared, className: cn("group relative flex items-center gap-3 rounded-ui-sm px-2 py-2 transition-colors", href && "hover:bg-hover", selected && "bg-selected ring-1 ring-inset ring-[color-mix(in_srgb,var(--accent-ink)_45%,transparent)]", archived && "opacity-65", className), children: [_jsx(EntityMedia, { kind: kind, name: name, media: media, size: "md", className: "ring-0" }), _jsxs("div", { className: "grid min-w-0 flex-1 gap-0.5", children: [_jsxs("div", { className: "flex min-w-0 items-center gap-2", children: [title, status ? (_jsx(Badge, { tone: status.tone, dot: true, size: "sm", className: "shrink-0", children: status.label })) : null] }), subtitle ? _jsx("p", { className: "truncate text-xs text-fg-muted", children: subtitle }) : null] }), quick] }));
+    }
+    if (variant === "header") {
+        return (_jsxs("article", { ...shared, className: cn("relative grid gap-5", archived && "[&_[data-slot=entity-media]]:grayscale", className), children: [_jsxs("div", { className: "flex flex-wrap items-start gap-x-5 gap-y-4", children: [_jsx(EntityMedia, { kind: kind, name: name, media: media, size: "xl", className: kind === "product" ? undefined : "size-16 text-xl" }), _jsxs("div", { className: "grid min-w-0 flex-1 basis-64 gap-1.5", children: [pills, title, subtitle ? _jsx("p", { className: "text-sm text-fg-muted", children: subtitle }) : null, description ? _jsx("p", { className: "max-w-[62ch] text-[13.5px] leading-relaxed text-fg-muted", children: description }) : null] }), quick ? _jsx("div", { className: "self-start", children: quick }) : null] }), stats?.length ? (_jsx("div", { className: "border-y border-line py-3", children: _jsx(EntityStats, { stats: stats, size: "lg" }) })) : null, fields?.length ? (_jsx("div", { className: "@container", children: _jsx(DescriptionList, { items: fields, layout: "grid", size: "sm", className: "grid-cols-2 @2xl:grid-cols-3" }) })) : null] }));
+    }
+    // card
+    const productTile = kind === "product";
+    return (_jsxs("article", { ...shared, className: cn("surface group relative flex flex-col overflow-hidden rounded-ui transition-[border-color,box-shadow]", href && "hover:border-field-border-hover", selected && "border-[color-mix(in_srgb,var(--accent-ink)_55%,var(--line))] shadow-[0_0_0_1px_color-mix(in_srgb,var(--accent-ink)_55%,transparent)]", archived && "[&>*]:opacity-70", className), children: [productTile ? (_jsx("div", { className: "p-1.5 pb-0", children: _jsx(EntityMedia, { kind: kind, name: name, media: media, size: "product-lg" }) })) : null, _jsxs("div", { className: "flex flex-1 flex-col gap-3 p-(--gap)", children: [_jsxs("div", { className: "flex min-w-0 items-start gap-3", children: [!productTile ? _jsx(EntityMedia, { kind: kind, name: name, media: media, size: "lg" }) : null, _jsxs("div", { className: "grid min-w-0 flex-1 gap-0.5", children: [title, subtitle ? _jsx("p", { className: "truncate text-[12.5px] text-fg-muted", children: subtitle }) : null] })] }), pills, description ? _jsx("p", { className: "line-clamp-3 text-[13px] leading-relaxed text-fg-muted", children: description }) : null, stats?.length ? (_jsx("div", { className: "rounded-ui-sm bg-surface-2 px-3 py-2.5", children: _jsx(EntityStats, { stats: stats, size: "sm" }) })) : null, fields?.length ? _jsx(DescriptionList, { items: fields, layout: "grid", size: "sm", className: "relative z-1 grid-cols-2 gap-y-3" }) : null, quick ? _jsx("div", { className: "mt-auto flex items-center pt-1", children: quick }) : null] })] }));
+});
+/** The card shown inside the chip variant's hover card. */
+function EntityCardPreview(props) {
+    return _jsx(EntityCard, { ...props });
+}