@vamos-ui/react 0.0.0-stage → 0.2.0

package/dist/components/date-range-picker.js

@@ -0,0 +1,251 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { CalendarRange, X } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { useLocale } from "../lib/locale.js";
+import { useLabels } from "../lib/labels.js";
+import { useFieldControl, FieldContextReset } from "../lib/field-context.js";
+import { useControllableState } from "../lib/use-controllable-state.js";
+import { useMediaQuery } from "../lib/use-media-query.js";
+import { mergeIds } from "../lib/compose-refs.js";
+import { controlVariants, itemVariants } from "../lib/variants.js";
+import { addIsoDays, dateToIso, defaultRangePresets, isoToDate, rangeLength, todayIso, } from "../lib/date.js";
+import { CalendarGrid, toDayMatchers, useCalendarWeek } from "./calendar.js";
+import { useDateInputText } from "./date-picker.js";
+import { Popover, PopoverAnchor, PopoverContent, PopoverTrigger } from "./popover.js";
+import { Button } from "./button.js";
+const dateRangePickerLabels = {
+    placeholder: "Pick a date range",
+    openCalendar: "Open calendar",
+    clear: "Clear",
+    apply: "Apply",
+    cancel: "Cancel",
+    presets: "Quick ranges",
+    start: "Start date",
+    end: "End date",
+    dialog: "Choose dates",
+    days: "{count, plural, one {# day} other {# days}}",
+    summary: "From {from} to {to}, {days}",
+    pickEnd: "From {from}. Now pick the end date.",
+    minDays: "Pick at least {count} days",
+    maxDays: "Pick at most {count} days",
+    today: "Today",
+    yesterday: "Yesterday",
+    last7: "Last 7 days",
+    last30: "Last 30 days",
+    thisWeek: "This week",
+    thisMonth: "This month",
+    lastMonth: "Last month",
+    last90: "Last 90 days",
+    thisYear: "This year",
+};
+const sameRange = (a, b) => (a?.from ?? null) === (b?.from ?? null) && (a?.to ?? null) === (b?.to ?? null);
+/**
+ * A from–to range in one popover: presets column, one or two month grids, and a footer with the
+ * selected length. Hovering previews the band; `commit="apply"` holds changes until Apply.
+ * Values are `YYYY-MM-DD` strings.
+ *
+ * ```tsx
+ * <DateRangePicker presets value={range} onValueChange={setRange} />
+ * <DateRangePicker commit="apply" maxDays={31} min={todayIso()} />
+ * ```
+ */
+export const DateRangePicker = React.forwardRef(function DateRangePicker(rawProps, ref) {
+    const { value: valueProp, defaultValue, onValueChange, presets: presetsProp = false, numberOfMonths = 2, commit = "immediate", minDays, maxDays, min, max, disabledDays, excludeDisabled, trigger = "button", nameFrom, nameTo, placeholder, clearable, size = "md", invalid, align = "start", open: openProp, defaultOpen, onOpenChange, onInputError, calendarProps, className, labels, inputLabels, calendarLabels, ...rest } = rawProps;
+    const control = useFieldControl({ ...rest, "aria-invalid": invalid ? true : undefined });
+    const t = useLabels("dateRangePicker", dateRangePickerLabels, labels);
+    const { format, timeZone } = useLocale();
+    const week = useCalendarWeek();
+    const wide = useMediaQuery("(min-width: 640px)");
+    const months = numberOfMonths === 2 && wide !== false ? 2 : 1;
+    const today = todayIso(timeZone === "UTC" ? undefined : timeZone);
+    const inert = control.disabled || control.readOnly;
+    const [value, setValue] = useControllableState({ value: valueProp, defaultValue: defaultValue ?? null, onChange: onValueChange, name: "DateRangePicker" });
+    const [open, setOpenState] = useControllableState({ value: openProp, defaultValue: defaultOpen ?? false, onChange: onOpenChange, name: "DateRangePicker" });
+    const [draft, setDraft] = React.useState(value);
+    const [hover, setHover] = React.useState(null);
+    const [month, setMonth] = React.useState(() => isoToDate(value?.from ?? today));
+    const [lengthError, setLengthError] = React.useState(null);
+    const setOpen = (o) => {
+        if (o) {
+            setDraft(value);
+            setHover(null);
+            setLengthError(null);
+            const anchor = isoToDate(value?.from ?? today);
+            setMonth(new Date(anchor.getFullYear(), anchor.getMonth(), 1));
+        }
+        setOpenState(o);
+    };
+    const presets = React.useMemo(() => {
+        if (!presetsProp)
+            return [];
+        if (Array.isArray(presetsProp))
+            return presetsProp;
+        const keys = Object.keys(dateRangePickerLabels).filter((k) => ["today", "yesterday", "last7", "last30", "thisWeek", "thisMonth", "lastMonth", "last90", "thisYear"].includes(k));
+        return defaultRangePresets(Object.fromEntries(keys.map((k) => [k, t(k)])));
+    }, [presetsProp, t]);
+    const shown = commit === "apply" || open ? draft : value;
+    const activePreset = presets.find((p) => sameRange(p.range(today, week), shown))?.id ?? null;
+    const commitRange = (r, close) => {
+        setDraft(r);
+        if (commit === "immediate")
+            setValue(r);
+        if (close && commit === "immediate")
+            setOpenState(false);
+    };
+    const checkLength = (r) => {
+        if (!r.to)
+            return null;
+        const n = rangeLength(r);
+        if (minDays && n < minDays)
+            return t("minDays", { count: minDays });
+        if (maxDays && n > maxDays)
+            return t("maxDays", { count: maxDays });
+        return null;
+    };
+    const onSelect = (r) => {
+        setHover(null);
+        if (!r?.from) {
+            setLengthError(null);
+            return commitRange(null, false);
+        }
+        const next = { from: dateToIso(r.from), ...(r.to ? { to: dateToIso(r.to) } : {}) };
+        const problem = checkLength(next);
+        setLengthError(problem);
+        if (problem) {
+            setDraft({ from: next.from });
+            return;
+        }
+        commitRange(next, !!next.to);
+    };
+    // While the end is being picked, block days that would break min/max length.
+    const matchers = React.useMemo(() => {
+        const base = toDayMatchers({ min, max, disabledDays });
+        if (draft?.from && !draft.to) {
+            const from = isoToDate(draft.from);
+            if (maxDays) {
+                base.push({ after: isoToDate(addIsoDays(draft.from, maxDays - 1)) }, { before: isoToDate(addIsoDays(draft.from, -(maxDays - 1))) });
+            }
+            if (minDays && minDays > 1) {
+                const lo = isoToDate(addIsoDays(draft.from, -(minDays - 2)));
+                const hi = isoToDate(addIsoDays(draft.from, minDays - 2));
+                base.push((d) => d >= lo && d <= hi && d.getTime() !== from.getTime());
+            }
+        }
+        return base;
+    }, [min, max, disabledDays, draft, minDays, maxDays]);
+    const previewModifiers = React.useMemo(() => {
+        if (!draft?.from || draft.to || !hover || hover === draft.from)
+            return undefined;
+        const [lo, hi] = hover > draft.from ? [draft.from, hover] : [hover, draft.from];
+        const a = isoToDate(lo);
+        const b = isoToDate(hi);
+        return { preview: (d) => d >= a && d <= b };
+    }, [draft, hover]);
+    const fmtRange = (r, style = "medium") => {
+        if (!r?.from)
+            return "";
+        if (!r.to)
+            return `${format.date(r.from, style)} – …`;
+        return r.from === r.to ? format.date(r.from, style) : format.dateRange(r.from, r.to, style);
+    };
+    const announcement = draft?.from
+        ? draft.to
+            ? t("summary", { from: format.date(draft.from, "long"), to: format.date(draft.to, "long"), days: t("days", { count: rangeLength(draft) }) })
+            : t("pickEnd", { from: format.date(draft.from, "long") })
+        : "";
+    /* ---------------- presets listbox ---------------- */
+    const presetRef = React.useRef(null);
+    const pickPreset = (p) => {
+        const r = p.range(today, week);
+        setLengthError(null);
+        const anchor = isoToDate(r.from);
+        setMonth(new Date(anchor.getFullYear(), anchor.getMonth(), 1));
+        commitRange(r, true);
+    };
+    const onPresetKeyDown = (e) => {
+        const opts = Array.from(presetRef.current?.querySelectorAll('[role="option"]') ?? []);
+        const cur = opts.indexOf(document.activeElement);
+        let next = -1;
+        if (e.key === "ArrowDown")
+            next = (cur + 1) % opts.length;
+        else if (e.key === "ArrowUp")
+            next = (cur - 1 + opts.length) % opts.length;
+        else if (e.key === "Home")
+            next = 0;
+        else if (e.key === "End")
+            next = opts.length - 1;
+        else if (e.key === "Enter" || e.key === " ") {
+            e.preventDefault();
+            const p = presets[cur];
+            if (p)
+                pickPreset(p);
+            return;
+        }
+        else
+            return;
+        e.preventDefault();
+        opts[next]?.focus();
+    };
+    const focusablePreset = Math.max(0, presets.findIndex((p) => p.id === activePreset));
+    const footer = (_jsxs("div", { className: "-mx-1 flex flex-wrap items-center gap-x-3 gap-y-2 border-t border-line px-1 pt-2.5", children: [_jsx("p", { className: cn("me-auto min-w-0 text-xs tabular", lengthError ? "text-danger" : "text-fg-muted"), children: lengthError ?? (draft?.from ? (_jsxs(_Fragment, { children: [_jsx("span", { className: "text-fg", children: fmtRange(draft) }), draft.to ? _jsx("span", { className: "ms-2 text-fg-subtle", children: t("days", { count: rangeLength(draft) }) }) : null] })) : ((placeholder ?? t("placeholder")))) }), _jsxs("div", { className: "flex items-center gap-1.5", children: [clearable && draft?.from ? (_jsx(Button, { size: "xs", variant: "ghost", onClick: () => commitRange(null, false), children: t("clear") })) : null, commit === "apply" ? (_jsxs(_Fragment, { children: [_jsx(Button, { size: "xs", variant: "ghost", onClick: () => setOpenState(false), children: t("cancel") }), _jsx(Button, { size: "xs", variant: "primary", disabled: !!draft?.from && !draft.to, onClick: () => {
+                                    setValue(draft);
+                                    setOpenState(false);
+                                }, children: t("apply") })] })) : null] })] }));
+    const content = (_jsx(PopoverContent, { size: "auto", padded: false, align: align, "aria-label": t("dialog"), onOpenAutoFocus: (e) => e.preventDefault(), className: "max-w-[calc(100vw-1.5rem)]", children: _jsxs(FieldContextReset, { children: [_jsxs("div", { className: "flex flex-col sm:flex-row", children: [presets.length ? (_jsx("div", { ref: presetRef, role: "listbox", "aria-label": t("presets"), onKeyDown: onPresetKeyDown, className: "flex gap-1 overflow-x-auto border-b border-line p-2 scrollbar-none sm:w-40 sm:flex-col sm:overflow-visible sm:border-e sm:border-b-0", children: presets.map((p, i) => {
+                                const selected = p.id === activePreset;
+                                return (_jsx("div", { role: "option", "aria-selected": selected, tabIndex: i === focusablePreset ? 0 : -1, onClick: () => pickPreset(p), className: cn(itemVariants({ size: "sm" }), "shrink-0 whitespace-nowrap focus-ring sm:w-full", selected && "bg-accent-soft! font-medium text-accent-ink"), children: p.label }, p.id));
+                            }) })) : null, _jsx("div", { className: "p-(--popover-p) [--popover-p:calc(var(--gap)*0.85)]", children: _jsx(CalendarGrid, { autoFocus: !presets.length, ...calendarProps, labels: calendarLabels, mode: "range", resetOnSelect: true, excludeDisabled: excludeDisabled, selected: draft ? { from: isoToDate(draft.from) ?? undefined, to: isoToDate(draft.to) ?? undefined } : undefined, onSelect: onSelect, month: month, onMonthChange: setMonth, numberOfMonths: months, disabled: matchers, modifiers: previewModifiers, onDayMouseEnter: (d) => setHover(dateToIso(d)), onDayFocus: (d) => setHover(dateToIso(d)), onDayMouseLeave: () => setHover(null), startMonth: calendarProps?.startMonth ?? (isoToDate(min) ?? undefined), endMonth: calendarProps?.endMonth ?? (isoToDate(max) ?? undefined), footer: footer }) })] }), _jsx("p", { className: "sr-only", "aria-live": "polite", children: announcement })] }) }));
+    const hidden = (_jsxs(_Fragment, { children: [nameFrom ? _jsx("input", { type: "hidden", name: nameFrom, value: value?.from ?? "" }) : null, nameTo ? _jsx("input", { type: "hidden", name: nameTo, value: value?.to ?? "" }) : null] }));
+    if (trigger === "input") {
+        return (_jsx(RangeInputs, { value: value, setValue: setValue, open: open, setOpen: (o) => !inert && setOpen(o), control: control, size: size, className: className, labels: labels, inputLabels: inputLabels, clearable: clearable, min: min, max: max, disabledDays: disabledDays, onInputError: onInputError, content: content, hidden: hidden, buttonRef: ref }));
+    }
+    return (_jsxs(Popover, { open: open, onOpenChange: (o) => !inert && setOpen(o), children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs("button", { ref: ref, type: "button", id: control.id, disabled: control.disabled, "aria-labelledby": control["aria-labelledby"] ? `${control["aria-labelledby"]} ${control.id}` : undefined, "aria-describedby": control["aria-describedby"], "aria-invalid": control["aria-invalid"] || undefined, "data-slot": "date-range-picker", "data-readonly": control.readOnly ? "" : undefined, "data-placeholder": value?.from ? undefined : "", className: cn(controlVariants({ size }), "w-auto cursor-default justify-start text-start focus-ring", className), children: [_jsx(CalendarRange, { "aria-hidden": true, className: "text-fg-subtle" }), control["aria-label"] && !control["aria-labelledby"] ? _jsxs("span", { className: "sr-only", children: [control["aria-label"], ", "] }) : null, _jsx("span", { className: cn("truncate tabular", !value?.from && "text-fg-subtle"), children: value?.from ? fmtRange(value) : (placeholder ?? t("placeholder")) })] }) }), content, hidden] }));
+});
+/* Two typeable fields in one box (trigger="input"). */
+function RangeInputs({ value, setValue, open, setOpen, control, size, className, labels, inputLabels, clearable, min, max, disabledDays, onInputError, content, hidden, buttonRef, }) {
+    const t = useLabels("dateRangePicker", dateRangePickerLabels, labels);
+    const errorId = React.useId();
+    const from = useDateInputText({
+        value: value?.from ?? null,
+        onCommit: (f) => {
+            if (!f)
+                return setValue(null);
+            const to = value?.to && value.to >= f ? value.to : undefined;
+            setValue({ from: f, ...(to ? { to } : {}) });
+        },
+        min,
+        max,
+        disabledDays,
+        labels: inputLabels,
+        onError: onInputError,
+    });
+    const to = useDateInputText({
+        value: value?.to ?? null,
+        onCommit: (tv) => {
+            if (!tv)
+                return setValue(value?.from ? { from: value.from } : null);
+            if (!value?.from)
+                return setValue({ from: tv, to: tv });
+            setValue(tv < value.from ? { from: tv, to: value.from } : { from: value.from, to: tv });
+        },
+        min,
+        max,
+        disabledDays,
+        labels: inputLabels,
+        onError: onInputError,
+    });
+    const inert = control.disabled || control.readOnly;
+    const errorMessage = from.error ? from.errorMessage : to.error ? to.errorMessage : "";
+    const field = "h-full w-[calc(10ch+1rem)] min-w-0 flex-1 bg-transparent px-2 text-[length:inherit] text-fg tabular outline-none placeholder:text-fg-subtle disabled:cursor-not-allowed";
+    const shared = {
+        type: "text",
+        autoComplete: "off",
+        spellCheck: false,
+        disabled: control.disabled,
+        readOnly: control.readOnly,
+        "aria-describedby": mergeIds(control["aria-describedby"], errorMessage ? errorId : undefined),
+    };
+    return (_jsxs(Popover, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverAnchor, { asChild: true, children: _jsxs("div", { role: "group", "aria-labelledby": control["aria-labelledby"], "aria-label": control["aria-label"], "data-slot": "date-range-picker", "data-readonly": control.readOnly ? "" : undefined, className: cn(controlVariants({ size }), "w-auto cursor-text gap-0 px-0", className), children: [_jsx(CalendarRange, { "aria-hidden": true, className: "ms-3 shrink-0 text-fg-subtle" }), _jsx("input", { ...shared, id: control.id, "aria-label": t("start"), "aria-invalid": !!from.error || !!control["aria-invalid"] || undefined, placeholder: from.placeholder, value: from.text, onChange: (e) => from.setText(e.currentTarget.value), onBlur: () => from.commit(), onKeyDown: (e) => e.key === "Enter" && from.commit(), className: cn(field, "ps-2") }), _jsx("span", { "aria-hidden": true, className: "text-fg-subtle", children: "\u2013" }), _jsx("input", { ...shared, "aria-label": t("end"), "aria-invalid": !!to.error || !!control["aria-invalid"] || undefined, placeholder: to.placeholder, value: to.text, onChange: (e) => to.setText(e.currentTarget.value), onBlur: () => to.commit(), onKeyDown: (e) => e.key === "Enter" && to.commit(), className: field }), errorMessage ? (_jsx("span", { id: errorId, className: "sr-only", children: errorMessage })) : null, _jsxs("span", { className: "flex shrink-0 items-center gap-0.5 pe-1", children: [clearable && value?.from && !inert ? (_jsx("button", { type: "button", tabIndex: -1, "aria-label": t("clear"), onClick: () => setValue(null), className: "inline-flex size-[calc(var(--control-h)-0.75rem)] items-center justify-center rounded-ui-sm text-fg-muted hover:bg-hover hover:text-fg [&_svg]:size-3.5", children: _jsx(X, { "aria-hidden": true }) })) : null, _jsx(PopoverTrigger, { asChild: true, children: _jsx("button", { ref: buttonRef, type: "button", "aria-label": t("openCalendar"), disabled: inert, className: "inline-flex size-[calc(var(--control-h)-0.75rem)] items-center justify-center rounded-ui-sm text-fg-muted transition-colors hover:bg-hover hover:text-fg focus-ring disabled:opacity-40 [&_svg]:size-4", children: _jsx(CalendarRange, { "aria-hidden": true }) }) })] })] }) }), content, hidden] }));
+}

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

@@ -0,0 +1,92 @@
+import * as React from "react";
+import type { descriptionListLabels } from "../lib/data-islands.js";
+import type { ValueFormat } from "../lib/value-format.js";
+export { DescriptionEditable, type DescriptionEditableProps } from "../lib/data-islands.js";
+export type DescriptionListLabels = Partial<typeof descriptionListLabels>;
+/** One row of `DescriptionList items`. */
+export interface DescriptionEntry {
+    /** Stable key (also passed to `onEdit`). */
+    key: string;
+    label: React.ReactNode;
+    /** The value. Numbers/dates are formatted with `format`; `null`/`undefined`/`""` show the empty value. */
+    value?: React.ReactNode;
+    /** Small help text under the value. */
+    hint?: React.ReactNode;
+    /** Format a number or date value. */
+    format?: ValueFormat;
+    /** Copy button: `true` copies the value text, a string copies that string. */
+    copyable?: boolean | string;
+    /** Grid layout only: columns to span. */
+    span?: 1 | 2 | "full";
+    /** Click-to-edit (needs `onEdit` on the list). The edited text starts from `editValue` or the value. */
+    editable?: boolean;
+    editValue?: string;
+    inputType?: "text" | "email" | "tel" | "url" | "number";
+}
+export interface DescriptionListProps extends Omit<React.HTMLAttributes<HTMLDListElement>, "children"> {
+    /** Rows as data. Or compose `<DescriptionItem>` children. */
+    items?: DescriptionEntry[];
+    /**
+     * `"horizontal"` (default): label start, value end — switches to stacked under ~28rem of container width.
+     * `"vertical"`: label above value. `"grid"`: stacked pairs in `columns`.
+     */
+    layout?: "horizontal" | "vertical" | "grid";
+    /** Grid layout columns (fewer on narrow containers). Default 2. */
+    columns?: 1 | 2 | 3;
+    /** Width of the label column in horizontal layout. Default `"11rem"`. */
+    labelWidth?: string;
+    /** Hairlines between rows. Default `true` for horizontal, `false` otherwise. */
+    divided?: boolean;
+    /** Default `"md"`. */
+    size?: "sm" | "md";
+    /** Shown for empty values. Default "—". */
+    emptyValue?: React.ReactNode;
+    /** Saves an inline edit (rows with `editable`). Reject to show the error state. */
+    onEdit?: (key: string, value: string) => void | Promise<void>;
+    /** Label + value skeletons for this many rows. */
+    loading?: boolean | number;
+    labels?: DescriptionListLabels;
+    children?: React.ReactNode;
+}
+/**
+ * Label/value pairs for record details and summaries — a native `<dl>`. Values can be copied
+ * or edited in place. Server-component compatible (copy and edit are small client islands).
+ *
+ * ```tsx
+ * <DescriptionList items={[
+ *   { key: "owner", label: "Owner", value: "Ayşe Kaya" },
+ *   { key: "amount", label: "Amount", value: 48500, format: "currency" },
+ *   { key: "iban", label: "IBAN", value: "TR33 0006 1005 1978 6457 8413 26", copyable: true },
+ * ]} />
+ * ```
+ */
+export declare const DescriptionList: React.ForwardRefExoticComponent<DescriptionListProps & React.RefAttributes<HTMLDListElement>>;
+export interface DescriptionItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+    label: React.ReactNode;
+    /** The value. */
+    children?: React.ReactNode;
+    hint?: React.ReactNode;
+    /** Copy button: `true` copies the text value, a string copies that string. */
+    copyable?: boolean | string;
+    /** Grid layout: columns to span. */
+    span?: 1 | 2 | "full";
+    /** Shown when the value is empty. Default "—". */
+    emptyValue?: React.ReactNode;
+    /** Inline edit slot (e.g. `<DescriptionEditable … />`) — replaces the value. */
+    edit?: React.ReactNode;
+    /** Trailing slot after the value (a link, a status badge). */
+    action?: React.ReactNode;
+    labels?: DescriptionListLabels;
+}
+/** One label/value pair (`<div><dt/><dd/></div>`). */
+export declare const DescriptionItem: React.ForwardRefExoticComponent<DescriptionItemProps & React.RefAttributes<HTMLDivElement>>;
+export interface DescriptionGroupProps extends Omit<React.HTMLAttributes<HTMLElement>, "title"> {
+    title: React.ReactNode;
+    description?: React.ReactNode;
+    /** Heading level. Default `"h4"`. */
+    titleAs?: "h2" | "h3" | "h4" | "h5";
+    /** Slot at the end of the heading row ("Edit" link). */
+    action?: React.ReactNode;
+}
+/** A titled section of a details view; put a DescriptionList inside. */
+export declare function DescriptionGroup({ title, description, titleAs: H, action, className, children, ...props }: DescriptionGroupProps): React.JSX.Element;

package/dist/components/description-list.js

@@ -0,0 +1,42 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { CopyValueButton, DataLabel, DescriptionEditable, ValueText } from "../lib/data-islands.js";
+import { Skeleton } from "./skeleton.js";
+export { DescriptionEditable } from "../lib/data-islands.js";
+const gridCols = { 1: "", 2: "@lg/dl:grid-cols-2", 3: "@lg/dl:grid-cols-2 @3xl/dl:grid-cols-3" };
+/**
+ * Label/value pairs for record details and summaries — a native `<dl>`. Values can be copied
+ * or edited in place. Server-component compatible (copy and edit are small client islands).
+ *
+ * ```tsx
+ * <DescriptionList items={[
+ *   { key: "owner", label: "Owner", value: "Ayşe Kaya" },
+ *   { key: "amount", label: "Amount", value: 48500, format: "currency" },
+ *   { key: "iban", label: "IBAN", value: "TR33 0006 1005 1978 6457 8413 26", copyable: true },
+ * ]} />
+ * ```
+ */
+export const DescriptionList = React.forwardRef(function DescriptionList({ items, layout = "horizontal", columns = 2, labelWidth, divided, size = "md", emptyValue, onEdit, loading, labels, className, style, children, ...props }, ref) {
+    const isDivided = divided ?? layout === "horizontal";
+    const rows = loading ? (Array.from({ length: typeof loading === "number" ? loading : 4 }, (_, i) => (_jsxs("div", { "data-slot": "description-item", "aria-hidden": true, className: "ui-dl-row", children: [_jsx("dt", { children: _jsx(Skeleton, { shape: "text", className: "h-3 w-20" }) }), _jsx("dd", { children: _jsx(Skeleton, { shape: "text", className: "h-3", style: { width: `${70 - ((i * 13) % 35)}%` } }) })] }, i)))) : items ? (items.map((it) => (_jsx(DescriptionItem, { label: it.label, hint: it.hint, span: it.span, copyable: it.copyable, emptyValue: emptyValue, labels: labels, edit: it.editable && onEdit ? (_jsx(DescriptionEditable, { value: it.editValue ?? (typeof it.value === "string" || typeof it.value === "number" ? String(it.value) : ""), display: renderValue(it.value, it.format), label: typeof it.label === "string" ? it.label : it.key, inputType: it.inputType, labels: labels, onSave: (v) => onEdit(it.key, v) })) : undefined, children: renderValue(it.value, it.format) }, it.key)))) : (children);
+    return (_jsx("dl", { ref: ref, "data-slot": "description-list", "data-layout": layout, "data-divided": isDivided ? "" : undefined, "data-size": size, "aria-busy": loading ? true : undefined, className: cn("ui-dl @container/dl m-0 grid min-w-0", size === "sm" ? "text-[12.5px]" : "text-[13px]", layout === "grid" ? cn("grid-cols-1 gap-x-6 gap-y-4", gridCols[columns]) : null, className), style: labelWidth ? { ["--dl-label-w"]: labelWidth, ...style } : style, ...props, children: rows }));
+});
+function renderValue(value, format) {
+    if (format && (typeof value === "number" || typeof value === "string"))
+        return _jsx(ValueText, { value: value, format: format });
+    return value;
+}
+const isEmpty = (v) => v === null || v === undefined || v === "" || v === false;
+/** One label/value pair (`<div><dt/><dd/></div>`). */
+export const DescriptionItem = React.forwardRef(function DescriptionItem({ label, children, hint, copyable, span, emptyValue, edit, action, labels, className, ...props }, ref) {
+    const empty = isEmpty(children);
+    const copyText = typeof copyable === "string" ? copyable : copyable && (typeof children === "string" || typeof children === "number") ? String(children) : undefined;
+    const labelText = typeof label === "string" ? label : "value";
+    return (_jsxs("div", { ref: ref, "data-slot": "description-item", className: cn("ui-dl-row", span === 2 && "@lg/dl:col-span-2", span === "full" && "col-span-full", className), ...props, children: [_jsx("dt", { "data-slot": "description-label", children: label }), _jsxs("dd", { "data-slot": "description-value", children: [_jsxs("span", { className: "flex min-w-0 items-center gap-1.5", children: [edit ?? (_jsx("span", { className: cn("min-w-0 break-words", empty && "text-fg-subtle"), children: empty ? (emptyValue ?? _jsx("span", { "aria-hidden": true, children: "\u2014" })) : children })), copyText && !empty ? _jsx(CopyValueButton, { text: copyText, label: labelText, labels: labels, className: "-my-1" }) : null, action ? _jsx("span", { className: "ms-auto flex shrink-0 items-center gap-1.5", children: action }) : null] }), empty && !edit && emptyValue === undefined ? (_jsx("span", { className: "sr-only", children: _jsx(DataLabel, { ns: "descriptionList", id: "empty", override: labels }) })) : null, hint ? _jsx("span", { className: "mt-0.5 block text-xs text-fg-subtle", children: hint }) : null] })] }));
+});
+/** A titled section of a details view; put a DescriptionList inside. */
+export function DescriptionGroup({ title, description, titleAs: H = "h4", action, className, children, ...props }) {
+    const id = React.useId();
+    return (_jsxs("section", { "data-slot": "description-group", "aria-labelledby": id, className: cn("grid content-start gap-2", className), ...props, children: [_jsxs("div", { className: "flex items-end justify-between gap-3", children: [_jsxs("div", { className: "min-w-0", children: [_jsx(H, { id: id, className: "font-mono text-[11px] font-medium tracking-[0.06em] text-fg-subtle", children: title }), description ? _jsx("p", { className: "mt-0.5 text-xs text-fg-muted", children: description }) : null] }), action] }), children] }));
+}

package/dist/components/dialog.d.ts

@@ -0,0 +1,139 @@
+import * as React from "react";
+import { Dialog as DialogPrimitive } from "radix-ui";
+type SlotComponent = React.ComponentType<React.HTMLAttributes<HTMLElement> & {
+    asChild?: boolean;
+    children?: React.ReactNode;
+}>;
+interface LayerParts {
+    /** Element that names the layer (Radix Title → `aria-labelledby`). */
+    Title: SlotComponent;
+    /** Element that describes the layer (Radix Description → `aria-describedby`). */
+    Description: SlotComponent;
+    /** Called while a description is mounted, so the content can drop a dangling `aria-describedby`. */
+    registerDescription?: () => () => void;
+}
+/** Lets a layer (Dialog, Alert Dialog, Sheet…) plug its accessible Title/Description into the shared header. */
+export declare function LayerPartsProvider({ value, children }: {
+    value: LayerParts;
+    children: React.ReactNode;
+}): React.JSX.Element;
+export interface LayerHeaderProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+    /** Required: names the layer for assistive tech. Use `srOnly` to hide it visually. */
+    title: React.ReactNode;
+    description?: React.ReactNode;
+    /** Leading icon or icon well. */
+    icon?: React.ReactNode;
+    /** Trailing control next to the title (a status badge, a menu). */
+    action?: React.ReactNode;
+    /** Keeps title and description for screen readers only. */
+    srOnly?: boolean;
+}
+/**
+ * The fixed top of a layer: title, optional description, icon and action. Shared by Dialog,
+ * Alert Dialog, Sheet and Drawer (exported under each name: `DialogHeader`, `SheetHeader`…).
+ */
+export declare const LayerHeader: React.ForwardRefExoticComponent<LayerHeaderProps & React.RefAttributes<HTMLDivElement>>;
+export interface LayerBodyProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Remove the default padding (full-bleed lists, media). */
+    flush?: boolean;
+}
+/** The scrolling middle of a layer. Header and footer stay fixed; only the body scrolls. */
+export declare const LayerBody: React.ForwardRefExoticComponent<LayerBodyProps & React.RefAttributes<HTMLDivElement>>;
+export interface LayerFooterProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** `"end"` (default) groups the buttons at the end; `"between"` pushes the first child to the start. */
+    align?: "end" | "between" | "stretch";
+}
+/** The fixed bottom of a layer: actions, primary last. Stacks (primary on top) inside a mobile sheet. */
+export declare const LayerFooter: React.ForwardRefExoticComponent<LayerFooterProps & React.RefAttributes<HTMLDivElement>>;
+type Guard = () => boolean | Promise<boolean>;
+interface DialogRootContextValue {
+    open: boolean;
+    /** Request a state change; closing runs the content's `onBeforeClose` guard first. */
+    requestOpenChange: (open: boolean) => void;
+    setGuard: (guard: Guard | undefined) => void;
+    modal: boolean;
+}
+/** Read the nearest Dialog/Sheet/Drawer root — e.g. to close it from custom code (`requestOpenChange(false)`). */
+export declare function useDialogRoot(): DialogRootContextValue;
+export interface DialogProps {
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** `false` keeps the page behind interactive (no overlay, no focus trap). Default `true`. */
+    modal?: boolean;
+    children?: React.ReactNode;
+}
+/**
+ * A focused task that keeps the user in context (modal by default).
+ *
+ * ```tsx
+ * <Dialog>
+ *   <DialogTrigger asChild><Button>New contact</Button></DialogTrigger>
+ *   <DialogContent size="md">
+ *     <DialogHeader title="New contact" description="Add a contact manually." />
+ *     <DialogBody>…</DialogBody>
+ *     <DialogFooter>
+ *       <DialogClose asChild><Button>Cancel</Button></DialogClose>
+ *       <Button variant="primary">Save</Button>
+ *     </DialogFooter>
+ *   </DialogContent>
+ * </Dialog>
+ * ```
+ */
+export declare function Dialog({ open: openProp, defaultOpen, onOpenChange, modal, children }: DialogProps): React.JSX.Element;
+export declare const DialogTrigger: React.ForwardRefExoticComponent<DialogPrimitive.DialogTriggerProps & React.RefAttributes<HTMLButtonElement>>;
+export declare const DialogClose: React.ForwardRefExoticComponent<DialogPrimitive.DialogCloseProps & React.RefAttributes<HTMLButtonElement>>;
+export declare const DialogPortal: React.FC<DialogPrimitive.DialogPortalProps>;
+export declare const DialogTitle: React.ForwardRefExoticComponent<DialogPrimitive.DialogTitleProps & React.RefAttributes<HTMLHeadingElement>>;
+export declare const DialogDescription: React.ForwardRefExoticComponent<DialogPrimitive.DialogDescriptionProps & React.RefAttributes<HTMLParagraphElement>>;
+/** The dimmed backdrop. `DialogContent` renders its own; export for custom layers. */
+export declare const DialogOverlay: React.ForwardRefExoticComponent<Omit<DialogPrimitive.DialogOverlayProps & React.RefAttributes<HTMLDivElement>, "ref"> & {
+    blurred?: boolean;
+} & React.RefAttributes<HTMLDivElement>>;
+declare const dialogLabels: {
+    close: string;
+};
+/** Shared plumbing for every Radix Dialog-based panel (Dialog, Sheet, Drawer). */
+export interface LayerContentBaseProps {
+    /** `false` → overlay click and Esc do not close (an unsaved form, a running import). Close buttons still work. */
+    dismissible?: boolean;
+    /** Runs on every close attempt (Esc, overlay, close button, `DialogClose`). Return/resolve `false` to stay open. */
+    onBeforeClose?: () => boolean | Promise<boolean>;
+    /** Hide the built-in × button. */
+    hideClose?: boolean;
+    /** Portal target. Defaults to the nearest `PortalContainer` / `ThemeScope`, else `document.body`. */
+    container?: HTMLElement | null;
+    /** Override the built-in strings (`close`). */
+    labels?: Partial<typeof dialogLabels>;
+}
+export interface LayerContentShellProps extends React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>, LayerContentBaseProps {
+    /** Class of the overlay element. */
+    overlayClassName?: string;
+}
+/**
+ * Internal: portal + overlay + layer depth + close guard + × button around a Radix Dialog.Content.
+ * Exported so other layers (Sheet, Drawer, Notification panel) share one implementation.
+ */
+export declare const LayerContentShell: React.ForwardRefExoticComponent<LayerContentShellProps & React.RefAttributes<HTMLDivElement>>;
+export type DialogSize = "sm" | "md" | "lg" | "xl" | "full";
+export interface DialogContentProps extends LayerContentShellProps {
+    /** 400 / 520 / 680 / 880 px, or the viewport minus a 12px gutter. Default `"md"`. */
+    size?: DialogSize;
+    /**
+     * Behaviour below 640px (CSS only, no component swap): `"sheet"` (default) anchors to the bottom
+     * and stacks the footer; `"center"` stays a centred card; `"fullscreen"` fills the screen (long forms).
+     */
+    mobile?: "sheet" | "center" | "fullscreen";
+}
+/**
+ * The dialog panel. Renders its own portal and overlay, traps focus, closes on Esc, returns
+ * focus to the trigger. Initial focus goes to `[data-autofocus]` if present, else the first field.
+ */
+export declare const DialogContent: React.ForwardRefExoticComponent<DialogContentProps & React.RefAttributes<HTMLDivElement>>;
+/** `LayerHeader` for dialogs. */
+export declare const DialogHeader: React.ForwardRefExoticComponent<LayerHeaderProps & React.RefAttributes<HTMLDivElement>>;
+/** `LayerBody` for dialogs. */
+export declare const DialogBody: React.ForwardRefExoticComponent<LayerBodyProps & React.RefAttributes<HTMLDivElement>>;
+/** `LayerFooter` for dialogs. */
+export declare const DialogFooter: React.ForwardRefExoticComponent<LayerFooterProps & React.RefAttributes<HTMLDivElement>>;
+export {};