@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/components/settings-layout.d.ts

@@ -0,0 +1,134 @@
+import * as React from "react";
+declare const settingsLabels: {
+    nav: string;
+    saveBar: string;
+    unsaved: string;
+    save: string;
+    saving: string;
+    reset: string;
+    error: string;
+    loading: string;
+};
+export type SettingsLayoutLabels = Partial<typeof settingsLabels>;
+export interface SettingsLayoutProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** `SettingsNav` — a column at the inline start; a scrolling strip on top below 42rem (672px). */
+    nav?: React.ReactNode;
+    /** `md` 64rem (default) · `lg` 80rem overall. */
+    width?: "md" | "lg";
+    /** Disables every control in the sections (pair with an Alert in `notice`). */
+    readOnly?: boolean;
+    /** Banner above the first section (read-only notice, plan limits). */
+    notice?: React.ReactNode;
+    /** Where the nav sticks. Default `"var(--topbar-h)"`. Use `0` in your own scroll box. */
+    stickyTop?: number | string;
+    labels?: SettingsLayoutLabels;
+}
+/**
+ * A shared skeleton for settings pages: section nav, titled sections of label | control rows,
+ * a sticky save bar that rises when there are unsaved changes, and a danger zone. Not bound to
+ * a form library — pass `dirty` from react-hook-form's `formState.isDirty` or your own state.
+ *
+ * ```tsx
+ * <SettingsLayout nav={<SettingsNav items={[{ id: "general", label: "General" }, { id: "danger", label: "Danger zone" }]} />}>
+ *   <SettingsSection id="general" title="General" description="Basic information about the site.">
+ *     <SettingsRow label="Site name" description="Shown in the title bar."><Input defaultValue="Northwind Journal" /></SettingsRow>
+ *     <SettingsRow label="Maintenance mode" layout="inline"><Switch /></SettingsRow>
+ *   </SettingsSection>
+ *   <SettingsSaveBar dirty={dirty} saving={saving} onSave={save} onReset={reset} />
+ * </SettingsLayout>
+ * ```
+ */
+export declare const SettingsLayout: React.ForwardRefExoticComponent<SettingsLayoutProps & React.RefAttributes<HTMLDivElement>>;
+export interface SettingsNavItem {
+    /** Section id (`#general`) — or a key when `href` is set. */
+    id: string;
+    label: string;
+    /** Route link (a separate settings page). Without it the item jumps to `#id` with scroll-spy. */
+    href?: string;
+    icon?: React.ReactNode;
+    badge?: React.ReactNode;
+    /** Hidden when `can(permission)` from `VamosProvider` is false. */
+    permission?: string;
+    /** Danger tone (the "Danger zone" item). */
+    tone?: "default" | "danger";
+}
+export interface SettingsNavProps extends Omit<React.HTMLAttributes<HTMLElement>, "defaultValue"> {
+    items: SettingsNavItem[];
+    /** Active item id (controlled). Default: derived from scroll position (anchors) or `currentPath` (links). */
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (id: string) => void;
+    /** Track the section in view. Default `true` for anchor items. */
+    scrollSpy?: boolean;
+    "aria-label"?: string;
+    labels?: SettingsLayoutLabels;
+}
+/**
+ * Section navigation: a `nav` with `aria-current`. Anchor items scroll to their section, move focus
+ * to its heading, and follow the scroll (scroll-spy). Link items use the app's router.
+ */
+export declare const SettingsNav: React.ForwardRefExoticComponent<SettingsNavProps & React.RefAttributes<HTMLElement>>;
+export interface SettingsSectionProps extends Omit<React.HTMLAttributes<HTMLElement>, "title"> {
+    /** Anchor for `SettingsNav` (`#general`). */
+    id?: string;
+    title: React.ReactNode;
+    description?: React.ReactNode;
+    /** `stacked` (default): title above the card. `split`: title in a start column, card beside it (stacks when narrow). */
+    layout?: "stacked" | "split";
+    /** `danger` for irreversible actions: red hairline and title. */
+    tone?: "default" | "danger";
+    /** Card footer: a section-level button, a hint ("Changes apply to new invoices only"). */
+    footer?: React.ReactNode;
+    /** Skeleton rows instead of the content. */
+    loading?: boolean | number;
+    /** Heading level. Default 2. */
+    headingLevel?: 2 | 3;
+    labels?: SettingsLayoutLabels;
+}
+/** A titled group of setting rows. `<section aria-labelledby>`. */
+export declare const SettingsSection: React.ForwardRefExoticComponent<SettingsSectionProps & React.RefAttributes<HTMLElement>>;
+export interface SettingsRowProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+    label: React.ReactNode;
+    description?: React.ReactNode;
+    /** Id of the control. Default: generated and passed to kit controls through the field context. */
+    htmlFor?: string;
+    /**
+     * `split` (default): label | control side by side, stacked when narrow. `inline`: control at the
+     * end on every width (switches). `stacked`: label, description, full-width control.
+     */
+    layout?: "stacked" | "inline" | "split";
+    /** "Beta", "Pro" — next to the label. */
+    badge?: React.ReactNode;
+    /** Error text under the control (marks kit controls invalid). */
+    error?: React.ReactNode;
+    disabled?: boolean;
+}
+/**
+ * One setting: label + description | control. Acts like a `Field` for kit controls (Input,
+ * Switch, Select…): the id, `aria-describedby` and disabled/invalid state are wired for you.
+ */
+export declare const SettingsRow: React.ForwardRefExoticComponent<SettingsRowProps & React.RefAttributes<HTMLDivElement>>;
+export interface SettingsSaveBarProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onReset"> {
+    /** The form differs from what's saved. The bar shows while `dirty`, `saving` or `error`. */
+    dirty: boolean;
+    saving?: boolean;
+    onSave: () => void;
+    onReset: () => void;
+    /** Replace "You have unsaved changes" ("3 changes to notification rules"). */
+    message?: React.ReactNode;
+    /** Save failed: danger tone and this text (or the default). `true` for the default text. */
+    error?: React.ReactNode;
+    /** Warn before leaving the page while dirty (`beforeunload`). Default `true`. */
+    blockNavigation?: boolean;
+    /** `mod+s` saves while dirty. Default `true`. */
+    shortcuts?: boolean;
+    /** Label of the save button. Default "Save changes". */
+    saveLabel?: string;
+    labels?: SettingsLayoutLabels;
+}
+/**
+ * The sticky "Unsaved changes · Discard · Save" bar. It rises from the bottom of the content when
+ * the form is dirty, announces itself politely, and `mod+s` saves.
+ */
+export declare const SettingsSaveBar: React.ForwardRefExoticComponent<SettingsSaveBarProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/dist/components/settings-layout.js

@@ -0,0 +1,180 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { TriangleAlert } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { useLabels } from "../lib/labels.js";
+import { useCan, useNavigation, SmartLink } from "../lib/provider.js";
+import { useHotkeys } from "../lib/use-hotkeys.js";
+import { useReducedMotion } from "../lib/use-reduced-motion.js";
+import { useControllableState } from "../lib/use-controllable-state.js";
+import { useEdgeFade } from "../lib/use-edge-fade.js";
+import { FieldContext } from "../lib/field-context.js";
+import { Button } from "./button.js";
+import { SkeletonText } from "./skeleton.js";
+/* ------------------------------------------------------------------ */
+/* Labels & context                                                    */
+/* ------------------------------------------------------------------ */
+const settingsLabels = {
+    nav: "Settings sections",
+    saveBar: "Unsaved changes",
+    unsaved: "You have unsaved changes",
+    save: "Save changes",
+    saving: "Saving…",
+    reset: "Discard",
+    error: "Couldn't save your changes",
+    loading: "Loading settings",
+};
+const SettingsLayoutContext = React.createContext({ readOnly: false });
+/**
+ * A shared skeleton for settings pages: section nav, titled sections of label | control rows,
+ * a sticky save bar that rises when there are unsaved changes, and a danger zone. Not bound to
+ * a form library — pass `dirty` from react-hook-form's `formState.isDirty` or your own state.
+ *
+ * ```tsx
+ * <SettingsLayout nav={<SettingsNav items={[{ id: "general", label: "General" }, { id: "danger", label: "Danger zone" }]} />}>
+ *   <SettingsSection id="general" title="General" description="Basic information about the site.">
+ *     <SettingsRow label="Site name" description="Shown in the title bar."><Input defaultValue="Northwind Journal" /></SettingsRow>
+ *     <SettingsRow label="Maintenance mode" layout="inline"><Switch /></SettingsRow>
+ *   </SettingsSection>
+ *   <SettingsSaveBar dirty={dirty} saving={saving} onSave={save} onReset={reset} />
+ * </SettingsLayout>
+ * ```
+ */
+export const SettingsLayout = React.forwardRef(function SettingsLayout({ nav, width = "md", readOnly = false, notice, stickyTop, labels, className, style, children, ...props }, ref) {
+    const ctx = React.useMemo(() => ({ readOnly, labels }), [readOnly, labels]);
+    const top = stickyTop === undefined ? undefined : typeof stickyTop === "number" ? `${stickyTop}px` : stickyTop;
+    return (_jsx(SettingsLayoutContext.Provider, { value: ctx, children: _jsx("div", { ref: ref, "data-slot": "settings-layout", "data-read-only": readOnly ? "" : undefined, className: cn("@container/settings mx-auto w-full min-w-0", width === "md" ? "max-w-[64rem]" : "max-w-[80rem]", className), style: top !== undefined ? { "--settings-sticky-top": top, ...style } : style, ...props, children: _jsxs("div", { className: cn("grid min-w-0 gap-x-10 gap-y-5", nav && "@2xl/settings:grid-cols-[11.5rem_minmax(0,1fr)]"), children: [nav ? (_jsx("div", { "data-slot": "settings-layout-nav", className: "min-w-0 @2xl/settings:sticky @2xl/settings:top-[calc(var(--settings-sticky-top,var(--topbar-h))+1.5rem)] @2xl/settings:self-start", children: nav })) : null, _jsxs("div", { "data-slot": "settings-layout-content", className: "flex min-w-0 flex-col gap-[calc(var(--gap)*1.6)]", children: [notice, children] })] }) }) }));
+});
+/**
+ * Section navigation: a `nav` with `aria-current`. Anchor items scroll to their section, move focus
+ * to its heading, and follow the scroll (scroll-spy). Link items use the app's router.
+ */
+export const SettingsNav = React.forwardRef(function SettingsNav({ items: itemsProp, value: valueProp, defaultValue, onValueChange, scrollSpy = true, labels, className, ...props }, ref) {
+    const ctx = React.useContext(SettingsLayoutContext);
+    const t = useLabels("settings", settingsLabels, labels ?? ctx.labels);
+    const can = useCan();
+    const { isActive } = useNavigation();
+    const reduced = useReducedMotion();
+    const items = React.useMemo(() => itemsProp.filter((i) => !i.permission || can(i.permission)), [itemsProp, can]);
+    const [value, setValue] = useControllableState({ value: valueProp, defaultValue: defaultValue ?? items[0]?.id ?? "", onChange: onValueChange, name: "SettingsNav" });
+    const listRef = React.useRef(null);
+    useEdgeFade(listRef, "x", true);
+    const lockUntil = React.useRef(0);
+    // Scroll-spy over anchor items.
+    const anchorIds = items.filter((i) => !i.href).map((i) => i.id).join("|");
+    React.useEffect(() => {
+        if (!scrollSpy || !anchorIds || typeof IntersectionObserver === "undefined")
+            return;
+        const ids = anchorIds.split("|");
+        const visible = new Set();
+        const io = new IntersectionObserver((entries) => {
+            for (const e of entries) {
+                if (e.isIntersecting)
+                    visible.add(e.target.id);
+                else
+                    visible.delete(e.target.id);
+            }
+            if (Date.now() < lockUntil.current)
+                return; // a click-scroll is in flight
+            const first = ids.find((id) => visible.has(id));
+            if (first)
+                setValue(first);
+        }, { rootMargin: "-10% 0px -55% 0px" });
+        for (const id of ids) {
+            const el = document.getElementById(id);
+            if (el)
+                io.observe(el);
+        }
+        return () => io.disconnect();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [scrollSpy, anchorIds]);
+    // Keep the active item visible in the horizontal strip.
+    React.useEffect(() => {
+        const el = listRef.current?.querySelector("[aria-current]");
+        el?.scrollIntoView?.({ block: "nearest", inline: "nearest" });
+    }, [value]);
+    const jump = (id) => {
+        const target = document.getElementById(id);
+        setValue(id);
+        if (!target)
+            return;
+        lockUntil.current = Date.now() + 800;
+        target.scrollIntoView?.({ behavior: reduced ? "auto" : "smooth", block: "start" });
+        const heading = target.querySelector("[data-settings-heading]") ?? target;
+        if (!heading.hasAttribute("tabindex"))
+            heading.setAttribute("tabindex", "-1");
+        heading.focus({ preventScroll: true });
+    };
+    const itemClass = (active, danger) => cn("group/settings-nav relative flex h-9 shrink-0 items-center gap-2.5 whitespace-nowrap rounded-ui-sm px-3 text-[13.5px] transition-colors focus-ring", "@2xl/settings:h-8.5 @2xl/settings:w-full", active ? "bg-selected font-medium text-fg" : "text-fg-muted hover:bg-hover hover:text-fg", danger && !active && "text-danger hover:text-danger", 
+    // accent tick on the start edge of the active item (wide layout)
+    "before:absolute before:inset-y-2 before:-start-px before:w-0.5 before:rounded-full before:bg-accent-ink before:opacity-0 before:transition-opacity @2xl/settings:before:opacity-0", active && "@2xl/settings:before:opacity-100", "[&_svg]:size-4 [&_svg]:shrink-0");
+    return (_jsx("nav", { ref: ref, "aria-label": props["aria-label"] ?? t("nav"), "data-slot": "settings-nav", className: cn("min-w-0", className), ...props, children: _jsx("ul", { ref: listRef, "data-edge-fade": "x", className: "-mx-1 flex min-w-0 gap-0.5 overflow-x-auto scrollbar-none px-1 pb-1 @2xl/settings:mx-0 @2xl/settings:flex-col @2xl/settings:overflow-visible @2xl/settings:px-0 @2xl/settings:pb-0 @2xl/settings:[mask-image:none]", children: items.map((item) => {
+                const active = item.href ? (valueProp !== undefined ? valueProp === item.id : isActive(item.href)) : value === item.id;
+                const inner = (_jsxs(_Fragment, { children: [item.icon ? _jsx("span", { "aria-hidden": true, className: cn("inline-flex", active ? "text-fg" : "text-fg-subtle"), children: item.icon }) : null, _jsx("span", { className: "truncate", children: item.label }), item.badge ? _jsx("span", { className: "ms-auto", children: item.badge }) : null] }));
+                return (_jsx("li", { className: "shrink-0", children: item.href ? (_jsx(SmartLink, { href: item.href, "aria-current": active ? "page" : undefined, className: itemClass(active, item.tone === "danger"), onClick: () => setValue(item.id), children: inner })) : (_jsx("a", { href: `#${item.id}`, "aria-current": active ? "true" : undefined, className: itemClass(active, item.tone === "danger"), onClick: (e) => {
+                            if (e.metaKey || e.ctrlKey || e.shiftKey || e.button !== 0)
+                                return;
+                            e.preventDefault();
+                            jump(item.id);
+                        }, children: inner })) }, item.id));
+            }) }) }));
+});
+/** A titled group of setting rows. `<section aria-labelledby>`. */
+export const SettingsSection = React.forwardRef(function SettingsSection({ id, title, description, layout = "stacked", tone = "default", footer, loading, headingLevel = 2, labels, className, children, ...props }, ref) {
+    const ctx = React.useContext(SettingsLayoutContext);
+    const t = useLabels("settings", settingsLabels, labels ?? ctx.labels);
+    const autoId = React.useId();
+    const titleId = `${id ?? `settings${autoId.replace(/:/g, "")}`}-title`;
+    const H = `h${headingLevel}`;
+    const danger = tone === "danger";
+    const rows = loading ? Math.max(1, typeof loading === "number" ? loading : 3) : 0;
+    return (_jsxs("section", { ref: ref, id: id, "aria-labelledby": titleId, "data-slot": "settings-section", "data-layout": layout, "data-tone": tone, className: cn("scroll-mt-[calc(var(--settings-sticky-top,var(--topbar-h))+1.5rem)] min-w-0", layout === "split" && "grid gap-x-8 gap-y-3 @4xl/settings:grid-cols-[minmax(0,15rem)_minmax(0,1fr)]", className), ...props, children: [_jsxs("div", { className: cn("min-w-0", layout === "stacked" ? "mb-3 px-0.5" : "px-0.5 @4xl/settings:pt-3"), children: [_jsxs(H, { id: titleId, "data-settings-heading": true, className: cn("rounded-ui-sm text-[15px] font-semibold tracking-[-0.005em] outline-none focus-visible:outline-2 focus-visible:outline-ring", danger ? "text-danger" : "text-fg"), children: [danger ? _jsx(TriangleAlert, { "aria-hidden": true, className: "-mt-0.5 me-1.5 inline size-4" }) : null, title] }), description ? _jsx("p", { className: "mt-1 max-w-[60ch] text-[13.5px] leading-relaxed text-fg-muted", children: description }) : null] }), _jsxs("div", { "data-slot": "settings-section-card", "aria-busy": loading ? true : undefined, className: cn("@container/setting-rows surface min-w-0 overflow-hidden rounded-ui-lg", danger && "border-[color-mix(in_srgb,var(--danger)_40%,transparent)]!"), children: [loading ? (_jsx("div", { role: "status", "aria-label": t("loading"), className: "divide-y divide-line", children: Array.from({ length: rows }, (_, i) => (_jsxs("div", { className: "grid gap-4 px-(--gap) py-4 @lg/setting-rows:grid-cols-2", children: [_jsx(SkeletonText, { lines: 2, lastLineWidth: "70%" }), _jsx(SkeletonText, { lines: 1, lineClassName: "h-(--control-h)" })] }, i))) })) : (_jsx("div", { className: "divide-y divide-line", children: children })), footer ? _jsx("div", { className: "flex flex-wrap items-center justify-end gap-2 border-t border-line bg-surface-2 px-(--gap) py-3 text-[13px] text-fg-muted", children: footer }) : null] })] }));
+});
+/**
+ * One setting: label + description | control. Acts like a `Field` for kit controls (Input,
+ * Switch, Select…): the id, `aria-describedby` and disabled/invalid state are wired for you.
+ */
+export const SettingsRow = React.forwardRef(function SettingsRow({ label, description, htmlFor, layout = "split", badge, error, disabled, className, children, ...props }, ref) {
+    const { readOnly } = React.useContext(SettingsLayoutContext);
+    const autoId = React.useId().replace(/:/g, "");
+    const controlId = htmlFor ?? `setting-${autoId}`;
+    const labelId = `${controlId}-label`;
+    const descId = description ? `${controlId}-desc` : undefined;
+    const errorId = error ? `${controlId}-error` : undefined;
+    const field = React.useMemo(() => ({
+        id: controlId,
+        labelId,
+        describedBy: [descId, errorId].filter(Boolean).join(" ") || undefined,
+        errorId,
+        invalid: Boolean(error),
+        required: false,
+        disabled: Boolean(disabled || readOnly),
+        readOnly: false,
+    }), [controlId, labelId, descId, errorId, error, disabled, readOnly]);
+    const text = (_jsxs("div", { className: "min-w-0", children: [_jsxs("label", { id: labelId, htmlFor: controlId, className: cn("inline-flex items-center gap-2 text-[14px] font-medium text-fg", (disabled || readOnly) && "text-fg-muted"), children: [label, badge] }), description ? (_jsx("p", { id: descId, className: "mt-0.5 max-w-[56ch] text-[13px] leading-relaxed text-fg-muted", children: description })) : null] }));
+    const control = (_jsxs("div", { "data-slot": "settings-row-control", className: cn("min-w-0", layout === "inline" && "shrink-0"), children: [_jsx(FieldContext.Provider, { value: field, children: children }), error ? (_jsx("p", { id: errorId, className: "mt-1.5 text-[12.5px] text-danger", children: error })) : null] }));
+    return (_jsxs("div", { ref: ref, "data-slot": "settings-row", "data-layout": layout, className: cn("px-(--gap) py-[calc(var(--gap)*0.8)]", layout === "split" && "grid items-start gap-x-8 gap-y-2.5 @lg/setting-rows:grid-cols-[minmax(0,1fr)_minmax(0,1.15fr)]", layout === "inline" && "flex items-center justify-between gap-6", layout === "stacked" && "grid gap-2.5", className), ...props, children: [text, control] }));
+});
+/**
+ * The sticky "Unsaved changes · Discard · Save" bar. It rises from the bottom of the content when
+ * the form is dirty, announces itself politely, and `mod+s` saves.
+ */
+export const SettingsSaveBar = React.forwardRef(function SettingsSaveBar({ dirty, saving = false, onSave, onReset, message, error, blockNavigation = true, shortcuts = true, saveLabel, labels, className, ...props }, ref) {
+    const ctx = React.useContext(SettingsLayoutContext);
+    const t = useLabels("settings", settingsLabels, labels ?? ctx.labels);
+    const visible = dirty || saving || Boolean(error);
+    useHotkeys("mod+s", () => onSave(), { enabled: shortcuts && dirty && !saving && !ctx.readOnly });
+    React.useEffect(() => {
+        if (!blockNavigation || !(dirty || saving))
+            return;
+        const handler = (e) => {
+            e.preventDefault();
+            e.returnValue = "";
+        };
+        window.addEventListener("beforeunload", handler);
+        return () => window.removeEventListener("beforeunload", handler);
+    }, [blockNavigation, dirty, saving]);
+    const errorText = error === true ? t("error") : error;
+    return (_jsxs(_Fragment, { children: [_jsx("div", { "aria-live": "polite", className: "sr-only", children: visible && !error ? t("unsaved") : "" }), visible ? (_jsxs("div", { ref: ref, role: "region", "aria-label": t("saveBar"), "data-slot": "settings-save-bar", "data-state": error ? "error" : saving ? "saving" : "dirty", className: cn("ui-rise surface-popover sticky bottom-4 z-(--z-sticky) flex flex-wrap items-center gap-x-4 gap-y-2 rounded-ui-lg py-2 ps-4 pe-2", error && "border-[color-mix(in_srgb,var(--danger)_45%,transparent)]!", className), ...props, children: [error ? (_jsxs("p", { role: "alert", className: "flex min-w-0 flex-1 items-center gap-2 text-[13.5px] font-medium text-danger", children: [_jsx(TriangleAlert, { "aria-hidden": true, className: "size-4 shrink-0" }), errorText] })) : (_jsxs("p", { className: "flex min-w-0 flex-1 items-center gap-2.5 text-[13.5px] text-fg", children: [_jsx("span", { "aria-hidden": true, className: "size-1.5 shrink-0 rounded-full bg-warning" }), _jsx("span", { className: "truncate", children: message ?? t("unsaved") })] })), _jsxs("div", { className: "ms-auto flex items-center gap-1.5", children: [_jsx(Button, { variant: "ghost", size: "sm", onClick: onReset, disabled: saving, children: t("reset") }), _jsx(Button, { variant: "primary", size: "sm", onClick: onSave, loading: saving, loadingText: t("saving"), disabled: ctx.readOnly, "aria-keyshortcuts": "Control+S Meta+S", children: saveLabel ?? t("save") })] })] })) : null] }));
+});

package/dist/components/sheet.d.ts

@@ -0,0 +1,103 @@
+import * as React from "react";
+import { DialogClose, DialogTrigger, type DialogProps, type LayerBodyProps, type LayerContentShellProps } from "./dialog.js";
+export interface SheetProps extends DialogProps {
+}
+/**
+ * An edge panel that keeps the page behind it in view: quick edit, record preview, mobile
+ * filters, mobile navigation. A positioned Dialog — same focus, Esc and close-guard behaviour.
+ *
+ * ```tsx
+ * <Sheet>
+ *   <SheetTrigger asChild><Button>Quick edit</Button></SheetTrigger>
+ *   <SheetContent side="end" size="md">
+ *     <SheetHeader title="Edit contact" />
+ *     <SheetBody>…</SheetBody>
+ *     <SheetFooter>…</SheetFooter>
+ *   </SheetContent>
+ * </Sheet>
+ * ```
+ *
+ * `modal={false}` keeps the page interactive (no overlay, no focus trap; Esc still closes).
+ */
+export declare function Sheet(props: SheetProps): React.JSX.Element;
+export declare const SheetTrigger: typeof DialogTrigger;
+export declare const SheetClose: typeof DialogClose;
+/** `LayerHeader` for sheets. */
+export declare const SheetHeader: React.ForwardRefExoticComponent<import("./dialog.js").LayerHeaderProps & React.RefAttributes<HTMLDivElement>>;
+/** `LayerBody` for sheets — the only part that scrolls. */
+export declare const SheetBody: React.ForwardRefExoticComponent<LayerBodyProps & React.RefAttributes<HTMLDivElement>>;
+/** `LayerFooter` for sheets. */
+export declare const SheetFooter: React.ForwardRefExoticComponent<import("./dialog.js").LayerFooterProps & React.RefAttributes<HTMLDivElement>>;
+export type SheetSide = "start" | "end" | "top" | "bottom";
+export interface SheetContentProps extends LayerContentShellProps {
+    /** Logical edge — `start`/`end` flip in RTL. `left`/`right` are accepted as aliases of `start`/`end`. Default `"end"`. */
+    side?: SheetSide | "left" | "right";
+    /**
+     * Width for `start`/`end`: 360 / 440 / 560 / 720 px or full. For `top`/`bottom` it caps the
+     * height (40 / 60 / 75 / 85 % of the viewport, or full); the panel otherwise fits its content.
+     * Default `"md"`.
+     */
+    size?: "sm" | "md" | "lg" | "xl" | "full";
+    /** 8px gutter and full radius — a floating panel. */
+    inset?: boolean;
+}
+export declare const SheetContent: React.ForwardRefExoticComponent<SheetContentProps & React.RefAttributes<HTMLDivElement>>;
+export interface UseDragDismissOptions {
+    /** Called when the drag passes the threshold or is flicked. */
+    onDismiss: () => void;
+    enabled?: boolean;
+    /** Fraction of the panel height to drag before it dismisses. Default 0.3. */
+    threshold?: number;
+    /** Flick speed in px/ms that dismisses regardless of distance. Default 0.5. */
+    velocity?: number;
+}
+/**
+ * Pointer-driven vertical drag for a bottom panel. Moves the element through the CSS
+ * `translate` property (so the close keyframes compose with it), sets `data-dragging` (which also
+ * turns blur off) and springs back below the threshold. Drags never start on interactive
+ * elements or inside a scrolled body.
+ */
+export declare function useDragDismiss<T extends HTMLElement>({ onDismiss, enabled, threshold, velocity }: UseDragDismissOptions): {
+    ref: React.RefObject<T | null>;
+    handlers: {
+        onPointerDown: (e: React.PointerEvent<T>) => void;
+        onPointerMove: (e: React.PointerEvent<T>) => void;
+        onPointerUp: (e: React.PointerEvent<T>) => void;
+        onPointerCancel: (e: React.PointerEvent<T>) => void;
+    };
+};
+export interface DrawerProps extends SheetProps {
+}
+/**
+ * A bottom sheet that closes by dragging down — mobile actions, filters, pickers. Dragging is an
+ * extra way to close: Esc and the close button always work.
+ *
+ * ```tsx
+ * <Drawer>
+ *   <DrawerTrigger asChild><Button>Filters</Button></DrawerTrigger>
+ *   <DrawerContent>
+ *     <DrawerHeader title="Filter orders" />
+ *     <DrawerBody>…</DrawerBody>
+ *     <DrawerFooter>…</DrawerFooter>
+ *   </DrawerContent>
+ * </Drawer>
+ * ```
+ */
+export declare function Drawer(props: DrawerProps): React.JSX.Element;
+export declare const DrawerTrigger: typeof DialogTrigger;
+export declare const DrawerClose: typeof DialogClose;
+export declare const DrawerHeader: React.ForwardRefExoticComponent<import("./dialog.js").LayerHeaderProps & React.RefAttributes<HTMLDivElement>>;
+export declare const DrawerFooter: React.ForwardRefExoticComponent<import("./dialog.js").LayerFooterProps & React.RefAttributes<HTMLDivElement>>;
+/** The scrolling body of a drawer; dragging starts from it only while it is scrolled to the top. */
+export declare const DrawerBody: React.ForwardRefExoticComponent<LayerBodyProps & React.RefAttributes<HTMLDivElement>>;
+/** The grab line at the top of a drawer. Decorative (`aria-hidden`). */
+export declare function DrawerHandle({ className }: {
+    className?: string;
+}): React.JSX.Element;
+export interface DrawerContentProps extends Omit<SheetContentProps, "side"> {
+    /** Close by dragging down. Default `true`. */
+    dragToDismiss?: boolean;
+    /** Show the grab handle. Default `true`. */
+    handle?: boolean;
+}
+export declare const DrawerContent: React.ForwardRefExoticComponent<DrawerContentProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/sheet.js

@@ -0,0 +1,165 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { useComposedRefs } from "../lib/compose-refs.js";
+import { useLatest } from "../lib/use-controllable-state.js";
+import { Dialog, DialogClose, DialogTrigger, LayerBody, LayerContentShell, LayerFooter, LayerHeader, useDialogRoot, } from "./dialog.js";
+/**
+ * An edge panel that keeps the page behind it in view: quick edit, record preview, mobile
+ * filters, mobile navigation. A positioned Dialog — same focus, Esc and close-guard behaviour.
+ *
+ * ```tsx
+ * <Sheet>
+ *   <SheetTrigger asChild><Button>Quick edit</Button></SheetTrigger>
+ *   <SheetContent side="end" size="md">
+ *     <SheetHeader title="Edit contact" />
+ *     <SheetBody>…</SheetBody>
+ *     <SheetFooter>…</SheetFooter>
+ *   </SheetContent>
+ * </Sheet>
+ * ```
+ *
+ * `modal={false}` keeps the page interactive (no overlay, no focus trap; Esc still closes).
+ */
+export function Sheet(props) {
+    return _jsx(Dialog, { ...props });
+}
+export const SheetTrigger = DialogTrigger;
+export const SheetClose = DialogClose;
+/** `LayerHeader` for sheets. */
+export const SheetHeader = LayerHeader;
+/** `LayerBody` for sheets — the only part that scrolls. */
+export const SheetBody = LayerBody;
+/** `LayerFooter` for sheets. */
+export const SheetFooter = LayerFooter;
+const sideAlias = { left: "start", right: "end" };
+export const SheetContent = React.forwardRef(function SheetContent({ side: sideProp = "end", size = "md", inset, className, ...props }, ref) {
+    const side = sideProp === "left" || sideProp === "right" ? sideAlias[sideProp] : sideProp;
+    return (_jsx(LayerContentShell, { ref: ref, "data-slot": "sheet-content", "data-side": side, "data-size": size, "data-inset": inset ? "" : undefined, className: cn("vui-sheet", `ui-sheet-${side}`, className), ...props }));
+});
+const INTERACTIVE = "button, a[href], input, select, textarea, label, [role=button], [role=slider], [contenteditable=true], [data-no-drag]";
+/**
+ * Pointer-driven vertical drag for a bottom panel. Moves the element through the CSS
+ * `translate` property (so the close keyframes compose with it), sets `data-dragging` (which also
+ * turns blur off) and springs back below the threshold. Drags never start on interactive
+ * elements or inside a scrolled body.
+ */
+export function useDragDismiss({ onDismiss, enabled = true, threshold = 0.3, velocity = 0.5 }) {
+    const ref = React.useRef(null);
+    const drag = React.useRef(null);
+    const dismiss = useLatest(onDismiss);
+    const settle = React.useCallback(() => {
+        const el = ref.current;
+        if (!el)
+            return;
+        el.setAttribute("data-settling", "");
+        el.style.translate = "";
+        const done = () => el.removeAttribute("data-settling");
+        el.addEventListener("transitionend", done, { once: true });
+        window.setTimeout(done, 260);
+    }, []);
+    const onPointerDown = React.useCallback((e) => {
+        const el = ref.current;
+        if (!enabled || !el || (e.pointerType === "mouse" && e.button !== 0))
+            return;
+        const target = e.target;
+        if (target.closest(INTERACTIVE))
+            return;
+        const body = target.closest(".vui-layer-body");
+        if (body && body.scrollTop > 0)
+            return;
+        drag.current = { y: e.clientY, t: performance.now(), id: e.pointerId, dy: 0 };
+    }, [enabled]);
+    const onPointerMove = React.useCallback((e) => {
+        const d = drag.current;
+        const el = ref.current;
+        if (!d || !el || e.pointerId !== d.id)
+            return;
+        const raw = e.clientY - d.y;
+        if (!el.hasAttribute("data-dragging")) {
+            if (Math.abs(raw) < 4)
+                return;
+            el.setAttribute("data-dragging", "");
+            el.setPointerCapture?.(e.pointerId);
+        }
+        // Upward drags resist (rubber band); downward follows the finger.
+        d.dy = raw < 0 ? -Math.sqrt(-raw) * 2 : raw;
+        el.style.translate = `0 ${d.dy}px`;
+    }, []);
+    const end = React.useCallback((e, cancelled) => {
+        const d = drag.current;
+        const el = ref.current;
+        drag.current = null;
+        if (!d || !el || !el.hasAttribute("data-dragging"))
+            return;
+        el.removeAttribute("data-dragging");
+        el.releasePointerCapture?.(e.pointerId);
+        const speed = d.dy / Math.max(1, performance.now() - d.t);
+        const height = el.getBoundingClientRect().height || 1;
+        if (!cancelled && d.dy > 0 && (d.dy > height * threshold || (speed > velocity && d.dy > 24))) {
+            dismiss.current();
+            // If a close guard keeps the panel open, spring back.
+            window.setTimeout(() => el.isConnected && el.getAttribute("data-state") === "open" && settle(), 320);
+        }
+        else
+            settle();
+    }, [threshold, velocity, dismiss, settle]);
+    return {
+        ref,
+        handlers: {
+            onPointerDown,
+            onPointerMove,
+            onPointerUp: (e) => end(e, false),
+            onPointerCancel: (e) => end(e, true),
+        },
+    };
+}
+/**
+ * A bottom sheet that closes by dragging down — mobile actions, filters, pickers. Dragging is an
+ * extra way to close: Esc and the close button always work.
+ *
+ * ```tsx
+ * <Drawer>
+ *   <DrawerTrigger asChild><Button>Filters</Button></DrawerTrigger>
+ *   <DrawerContent>
+ *     <DrawerHeader title="Filter orders" />
+ *     <DrawerBody>…</DrawerBody>
+ *     <DrawerFooter>…</DrawerFooter>
+ *   </DrawerContent>
+ * </Drawer>
+ * ```
+ */
+export function Drawer(props) {
+    return _jsx(Dialog, { ...props });
+}
+export const DrawerTrigger = DialogTrigger;
+export const DrawerClose = DialogClose;
+export const DrawerHeader = LayerHeader;
+export const DrawerFooter = LayerFooter;
+/** The scrolling body of a drawer; dragging starts from it only while it is scrolled to the top. */
+export const DrawerBody = React.forwardRef(function DrawerBody(props, ref) {
+    return _jsx(LayerBody, { ref: ref, "data-slot": "drawer-body", ...props });
+});
+/** The grab line at the top of a drawer. Decorative (`aria-hidden`). */
+export function DrawerHandle({ className }) {
+    return _jsx("div", { "aria-hidden": true, "data-slot": "drawer-handle", className: cn("vui-drawer-handle", className) });
+}
+export const DrawerContent = React.forwardRef(function DrawerContent({ dragToDismiss = true, handle = true, size = "lg", className, children, onPointerDown, onPointerMove, onPointerUp, onPointerCancel, ...props }, ref) {
+    const root = useDialogRoot();
+    const { ref: dragRef, handlers } = useDragDismiss({ onDismiss: () => root.requestOpenChange(false), enabled: dragToDismiss });
+    const composed = useComposedRefs(ref, dragRef);
+    return (_jsxs(SheetContent, { ref: composed, side: "bottom", size: size, "data-slot": "drawer-content", className: cn("vui-drawer", className), onPointerDown: (e) => {
+            onPointerDown?.(e);
+            handlers.onPointerDown(e);
+        }, onPointerMove: (e) => {
+            onPointerMove?.(e);
+            handlers.onPointerMove(e);
+        }, onPointerUp: (e) => {
+            onPointerUp?.(e);
+            handlers.onPointerUp(e);
+        }, onPointerCancel: (e) => {
+            onPointerCancel?.(e);
+            handlers.onPointerCancel(e);
+        }, ...props, children: [handle ? _jsx(DrawerHandle, {}) : null, children] }));
+});