veryfront 0.1.1237 → 0.1.1239

package/esm/src/react/components/ui/calendar.js

@@ -0,0 +1,170 @@
+/**
+ * Calendar: a dependency-free single-month date grid. Renders a header row
+ * (previous-month button, "Month YYYY" caption, and next-month button), a
+ * weekday header, and a `role="grid"` table of days. One day participates in
+ * the tab order. Arrow keys move by day or week, Home and End move to week
+ * boundaries, and Page Up and Page Down move by month. The selected day is
+ * controlled via `value`; selecting a day fires `onChange`. The displayed month
+ * is tracked internally (seeded from `defaultMonth ?? value ?? today`) and moved
+ * by the previous and next buttons. Self-contained: no `react-day-picker`, no
+ * floating engine; skinned with the veryfront theme tokens.
+ *
+ * @example
+ * ```tsx
+ * import { Calendar } from "veryfront/ui";
+ *
+ * function Example() {
+ *   const [day, setDay] = React.useState<Date>();
+ *   return <Calendar value={day} onChange={setDay} />;
+ * }
+ * ```
+ *
+ * @module react/components/ui/calendar
+ */
+import * as React from "react";
+import { cx as cn } from "./cva.js";
+const MONTHS = [
+    "January",
+    "February",
+    "March",
+    "April",
+    "May",
+    "June",
+    "July",
+    "August",
+    "September",
+    "October",
+    "November",
+    "December",
+];
+// Sunday-first weekday labels; rotated when weekStartsOn === 1.
+const WEEKDAYS = ["Su", "Mo", "Tu", "We", "Th", "Fr", "Sa"];
+/** First day of the month `d` falls in, at local midnight. */
+function startOfMonth(d) {
+    return new Date(d.getFullYear(), d.getMonth(), 1);
+}
+/** True when `a` and `b` are the same calendar day. */
+function isSameDay(a, b) {
+    return (a.getFullYear() === b.getFullYear() &&
+        a.getMonth() === b.getMonth() &&
+        a.getDate() === b.getDate());
+}
+/** True when `a` and `b` fall in the same calendar month. */
+function isSameMonth(a, b) {
+    return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth();
+}
+/** Return the local calendar day `offset` days from `date`. */
+function addDays(date, offset) {
+    return new Date(date.getFullYear(), date.getMonth(), date.getDate() + offset);
+}
+/** Move by whole months, clamping the day to the target month's final day. */
+function addMonths(date, offset) {
+    const target = new Date(date.getFullYear(), date.getMonth() + offset, 1);
+    const lastDay = new Date(target.getFullYear(), target.getMonth() + 1, 0).getDate();
+    return new Date(target.getFullYear(), target.getMonth(), Math.min(date.getDate(), lastDay));
+}
+/** Chunk the flat cell list into rows of seven. */
+function toWeeks(cells) {
+    const weeks = [];
+    for (let i = 0; i < cells.length; i += 7)
+        weeks.push(cells.slice(i, i + 7));
+    return weeks;
+}
+/** A dependency-free single-month date grid. */
+export function Calendar({ value, onChange, defaultMonth, weekStartsOn = 0, className, ref, ...props }) {
+    const [displayed, setDisplayed] = React.useState(() => startOfMonth(defaultMonth ?? value ?? new Date()));
+    const [activeDate, setActiveDate] = React.useState(() => {
+        const initialMonth = startOfMonth(defaultMonth ?? value ?? new Date());
+        const today = new Date();
+        if (value != null && isSameMonth(value, initialMonth))
+            return value;
+        if (isSameMonth(today, initialMonth))
+            return today;
+        return initialMonth;
+    });
+    const activeButtonRef = React.useRef(null);
+    const shouldFocusActiveRef = React.useRef(false);
+    React.useEffect(() => {
+        if (!shouldFocusActiveRef.current)
+            return;
+        shouldFocusActiveRef.current = false;
+        activeButtonRef.current?.focus();
+    }, [activeDate, displayed]);
+    const today = new Date();
+    const year = displayed.getFullYear();
+    const month = displayed.getMonth();
+    const caption = `${MONTHS[month]} ${year}`;
+    const weekdays = weekStartsOn === 1 ? [...WEEKDAYS.slice(1), WEEKDAYS[0]] : WEEKDAYS;
+    const daysInMonth = new Date(year, month + 1, 0).getDate();
+    const leading = (new Date(year, month, 1).getDay() - weekStartsOn + 7) % 7;
+    const cells = [];
+    for (let i = 0; i < leading; i++)
+        cells.push(null);
+    for (let d = 1; d <= daysInMonth; d++)
+        cells.push(d);
+    while (cells.length % 7 !== 0)
+        cells.push(null);
+    const weeks = toWeeks(cells);
+    const select = (day) => onChange?.(new Date(year, month, day));
+    const moveFocus = (date) => {
+        shouldFocusActiveRef.current = true;
+        if (!isSameMonth(date, displayed))
+            setDisplayed(startOfMonth(date));
+        setActiveDate(date);
+    };
+    const changeDisplayedMonth = (offset) => {
+        const date = addMonths(activeDate, offset);
+        setDisplayed(startOfMonth(date));
+        setActiveDate(date);
+    };
+    const goPrev = () => changeDisplayedMonth(-1);
+    const goNext = () => changeDisplayedMonth(1);
+    const handleDayKeyDown = (event, date) => {
+        const dayOfWeek = (date.getDay() - weekStartsOn + 7) % 7;
+        const nextDate = event.key === "ArrowLeft"
+            ? addDays(date, -1)
+            : event.key === "ArrowRight"
+                ? addDays(date, 1)
+                : event.key === "ArrowUp"
+                    ? addDays(date, -7)
+                    : event.key === "ArrowDown"
+                        ? addDays(date, 7)
+                        : event.key === "Home"
+                            ? addDays(date, -dayOfWeek)
+                            : event.key === "End"
+                                ? addDays(date, 6 - dayOfWeek)
+                                : event.key === "PageUp"
+                                    ? addMonths(date, -1)
+                                    : event.key === "PageDown"
+                                        ? addMonths(date, 1)
+                                        : null;
+        if (nextDate == null)
+            return;
+        event.preventDefault();
+        moveFocus(nextDate);
+    };
+    return (React.createElement("div", { ref: ref, "data-month": caption, className: cn("w-fit select-none rounded-lg border border-[var(--border)] bg-[var(--background)] p-3 text-[var(--foreground)]", className), ...props },
+        React.createElement("div", { className: "mb-2 flex items-center justify-between" },
+            React.createElement("button", { type: "button", "aria-label": "Previous month", onClick: goPrev, className: "inline-flex size-7 items-center justify-center rounded-md text-[var(--muted-foreground)] hover:bg-[var(--accent)] hover:text-[var(--accent-foreground)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring)]" }, "\u2039"),
+            React.createElement("div", { "aria-live": "polite", className: "text-sm font-medium text-[var(--foreground)]" }, caption),
+            React.createElement("button", { type: "button", "aria-label": "Next month", onClick: goNext, className: "inline-flex size-7 items-center justify-center rounded-md text-[var(--muted-foreground)] hover:bg-[var(--accent)] hover:text-[var(--accent-foreground)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring)]" }, "\u203A")),
+        React.createElement("table", { role: "grid", "aria-label": caption, className: "border-collapse" },
+            React.createElement("thead", null,
+                React.createElement("tr", { role: "row", className: "flex" }, weekdays.map((label, i) => (React.createElement("th", { key: i, scope: "col", className: "inline-flex size-9 items-center justify-center text-xs font-normal text-[var(--muted-foreground)]" }, label))))),
+            React.createElement("tbody", null, weeks.map((week, wi) => (React.createElement("tr", { key: wi, role: "row", className: "flex" }, week.map((day, di) => {
+                if (day == null) {
+                    return React.createElement("td", { key: di, role: "gridcell", className: "size-9" });
+                }
+                const date = new Date(year, month, day);
+                const selected = value != null && isSameDay(value, date);
+                const isToday = isSameDay(today, date);
+                const active = isSameDay(activeDate, date);
+                return (
+                // aria-selected belongs on the gridcell: ARIA defines it for
+                // gridcell/option/row/tab, not for role="button". The button
+                // carries aria-pressed for its own state instead.
+                React.createElement("td", { key: di, role: "gridcell", "aria-selected": selected, "data-selected": selected ? "true" : undefined, className: "p-0" },
+                    React.createElement("button", { ref: active ? activeButtonRef : undefined, type: "button", tabIndex: active ? 0 : -1, "aria-pressed": selected, "data-today": isToday ? "true" : undefined, onFocus: () => setActiveDate(date), onKeyDown: (event) => handleDayKeyDown(event, date), onClick: () => select(day), className: cn("inline-flex size-9 items-center justify-center rounded-md text-sm text-[var(--foreground)]", "hover:bg-[var(--accent)] hover:text-[var(--accent-foreground)]", "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring)]", isToday && "ring-1 ring-[var(--ring)]", selected &&
+                            "bg-[var(--primary)] text-[var(--primary-foreground)] hover:bg-[var(--primary)] hover:text-[var(--primary-foreground)]") }, day)));
+            }))))))));
+}

package/esm/src/react/components/ui/combobox.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Combobox - a text input that filters a dropdown `listbox` as you type, then
+ * commits a selection. The look is ours (theme tokens); the mechanics (query,
+ * filtering, `aria-activedescendant` keyboard nav, open/dismiss, portalling)
+ * come from the active adapter's `combobox` slot - the zero-dependency
+ * {@link builtinCombobox} by default, swappable to cmdk / Base UI / etc. via
+ * `UIAdapterProvider`.
+ *
+ * @example
+ * ```tsx
+ * import { Combobox, ComboboxInput, ComboboxContent, ComboboxItem } from "veryfront/ui";
+ *
+ * <Combobox onValueChange={setFramework}>
+ *   <ComboboxInput placeholder="Search framework…" />
+ *   <ComboboxContent>
+ *     <ComboboxItem value="next">Next.js</ComboboxItem>
+ *     <ComboboxItem value="remix">Remix</ComboboxItem>
+ *     <ComboboxItem value="astro">Astro</ComboboxItem>
+ *   </ComboboxContent>
+ * </Combobox>;
+ * ```
+ *
+ * @module react/components/ui/combobox
+ */
+import * as React from "react";
+/** Props accepted by `<Combobox>` (the root; owns query/open/value state). */
+export interface ComboboxProps {
+    /** `ComboboxInput` + `ComboboxContent` parts to compose. */
+    children: React.ReactNode;
+    /** Controlled selected value (pair with `onValueChange`). */
+    value?: string;
+    /** Initial selected value when uncontrolled. */
+    defaultValue?: string;
+    /** Fires with the newly-selected value. */
+    onValueChange?: (value: string) => void;
+    /** Controlled open state of the listbox (pair with `onOpenChange`). */
+    open?: boolean;
+    /** Initial open state when uncontrolled. */
+    defaultOpen?: boolean;
+    /** Fires when the listbox opens or closes. */
+    onOpenChange?: (open: boolean) => void;
+    /** Initial input text. */
+    defaultInputValue?: string;
+}
+/** Combobox root - renders no node of its own (state + context only). */
+export declare function Combobox(props: ComboboxProps): React.ReactElement;
+/** Props accepted by `<ComboboxInput>`. */
+export interface ComboboxInputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+    /** React 19: ref is a regular prop. */
+    ref?: React.Ref<HTMLInputElement>;
+}
+/** The `role="combobox"` text input that drives filtering. */
+export declare function ComboboxInput({ className, ...props }: ComboboxInputProps): React.ReactElement;
+/** Props accepted by `<ComboboxContent>`. */
+export interface ComboboxContentProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** React 19: ref is a regular prop. */
+    ref?: React.Ref<HTMLDivElement>;
+}
+/** The floating `role="listbox"` surface, shown while filtering. */
+export declare function ComboboxContent({ className, children, ...props }: ComboboxContentProps): React.ReactElement | null;
+/** Props accepted by `<ComboboxItem>`. */
+export interface ComboboxItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onSelect"> {
+    /** The value this option commits when chosen. */
+    value: string;
+    /** Text used for filtering and the input after selection. Defaults to plain child text, then value. */
+    textValue?: string;
+    /** Disable selection and dim the option. */
+    disabled?: boolean;
+    /** React 19: ref is a regular prop. */
+    ref?: React.Ref<HTMLDivElement>;
+}
+/** A selectable, filterable option. Hides itself when it doesn't match the query. */
+export declare function ComboboxItem({ value, textValue, disabled, className, children, onClick, ref, ...props }: ComboboxItemProps): React.ReactElement | null;
+//# sourceMappingURL=combobox.d.ts.map

package/esm/src/react/components/ui/combobox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"combobox.d.ts","sourceRoot":"","sources":["../../../../../src/src/react/components/ui/combobox.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,uEAAuE;IACvE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,4CAA4C;IAC5C,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,8CAA8C;IAC9C,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IACvC,0BAA0B;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,yEAAyE;AACzE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,CAAC,YAAY,CAIjE;AA6CD,2CAA2C;AAC3C,MAAM,WAAW,kBAAmB,SAAQ,KAAK,CAAC,mBAAmB,CAAC,gBAAgB,CAAC;IACrF,uCAAuC;IACvC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;CACnC;AAED,8DAA8D;AAC9D,wBAAgB,aAAa,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,kBAAkB,GAAG,KAAK,CAAC,YAAY,CAc7F;AAED,6CAA6C;AAC7C,MAAM,WAAW,oBAAqB,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;IAChF,uCAAuC;IACvC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;CACjC;AAED,oEAAoE;AACpE,wBAAgB,eAAe,CAC7B,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,EAAE,oBAAoB,GACtD,KAAK,CAAC,YAAY,GAAG,IAAI,CAc3B;AAED,0CAA0C;AAC1C,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,UAAU,CAAC;IAC/F,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,uGAAuG;IACvG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,uCAAuC;IACvC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;CACjC;AAED,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,EAC3B,KAAK,EACL,SAAS,EACT,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,OAAO,EACP,GAAG,EACH,GAAG,KAAK,EACT,EAAE,iBAAiB,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CAwC/C"}

package/esm/src/react/components/ui/combobox.js

@@ -0,0 +1,100 @@
+/**
+ * Combobox - a text input that filters a dropdown `listbox` as you type, then
+ * commits a selection. The look is ours (theme tokens); the mechanics (query,
+ * filtering, `aria-activedescendant` keyboard nav, open/dismiss, portalling)
+ * come from the active adapter's `combobox` slot - the zero-dependency
+ * {@link builtinCombobox} by default, swappable to cmdk / Base UI / etc. via
+ * `UIAdapterProvider`.
+ *
+ * @example
+ * ```tsx
+ * import { Combobox, ComboboxInput, ComboboxContent, ComboboxItem } from "veryfront/ui";
+ *
+ * <Combobox onValueChange={setFramework}>
+ *   <ComboboxInput placeholder="Search framework…" />
+ *   <ComboboxContent>
+ *     <ComboboxItem value="next">Next.js</ComboboxItem>
+ *     <ComboboxItem value="remix">Remix</ComboboxItem>
+ *     <ComboboxItem value="astro">Astro</ComboboxItem>
+ *   </ComboboxContent>
+ * </Combobox>;
+ * ```
+ *
+ * @module react/components/ui/combobox
+ */
+import * as React from "react";
+import { cx as cn } from "./cva.js";
+import { useAdapter } from "./adapter/context.js";
+/** Combobox root - renders no node of its own (state + context only). */
+export function Combobox(props) {
+    const { combobox } = useAdapter();
+    const optionLabels = React.useMemo(() => collectOptionLabels(props.children), [props.children]);
+    return React.createElement(combobox.Root, { ...props, optionLabels: optionLabels });
+}
+function collectOptionLabels(children, labels = []) {
+    React.Children.forEach(children, (child) => {
+        if (!React.isValidElement(child))
+            return;
+        if (child.type === ComboboxItem) {
+            const { value, textValue, children: itemChildren } = child.props;
+            labels.push({ value, text: resolveOptionText(value, textValue, itemChildren) });
+            return;
+        }
+        const nestedChildren = child.props.children;
+        if (nestedChildren !== undefined)
+            collectOptionLabels(nestedChildren, labels);
+    });
+    return labels;
+}
+function resolveOptionText(value, textValue, children) {
+    return textValue ?? collectPlainText(children) ?? value;
+}
+function collectPlainText(children) {
+    let text = "";
+    let hasText = false;
+    React.Children.forEach(children, (child) => {
+        if (typeof child === "string" || typeof child === "number") {
+            text += String(child);
+            hasText = true;
+            return;
+        }
+        if (!React.isValidElement(child))
+            return;
+        const nested = collectPlainText(child.props.children);
+        if (nested === undefined)
+            return;
+        text += nested;
+        hasText = true;
+    });
+    return hasText ? text : undefined;
+}
+/** The `role="combobox"` text input that drives filtering. */
+export function ComboboxInput({ className, ...props }) {
+    const { combobox } = useAdapter();
+    return (React.createElement(combobox.Input, { className: cn("h-[38px] w-full rounded-md px-3 text-base", "bg-[var(--input-bg)] text-[var(--foreground)] border border-[var(--outline-border)]", "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-[var(--edge-medium)]", "disabled:cursor-not-allowed disabled:opacity-50", className), ...props }));
+}
+/** The floating `role="listbox"` surface, shown while filtering. */
+export function ComboboxContent({ className, children, ...props }) {
+    const { combobox } = useAdapter();
+    return (React.createElement(combobox.Content, { className: cn("z-50 max-h-64 min-w-[220px] overflow-auto rounded-lg", "bg-[var(--popover)] text-[var(--foreground)] shadow-sm outline-none", className), ...props }, children));
+}
+/** A selectable, filterable option. Hides itself when it doesn't match the query. */
+export function ComboboxItem({ value, textValue, disabled, className, children, onClick, ref, ...props }) {
+    const { combobox } = useAdapter();
+    const ctx = combobox.useCombobox();
+    const id = React.useId();
+    const text = resolveOptionText(value, textValue, children);
+    React.useEffect(() => {
+        ctx.registerOption(id, value, text, disabled);
+        return () => ctx.unregisterOption(id);
+    }, [ctx, disabled, id, value, text]);
+    if (!ctx.matches(text))
+        return null;
+    const active = ctx.activeId === id;
+    const selected = ctx.value === value;
+    return (React.createElement("div", { ref: ref, id: id, role: "option", "aria-selected": selected, "aria-disabled": disabled || undefined, "data-active": active ? "" : undefined, "data-disabled": disabled ? "" : undefined, onClick: (event) => {
+            onClick?.(event);
+            if (!event.defaultPrevented && !disabled)
+                ctx.select(value, text);
+        }, className: cn("flex cursor-pointer items-center rounded-md px-2.5 py-1.5 text-base", "data-[active]:bg-[var(--accent)] aria-selected:font-medium", "data-[disabled]:pointer-events-none data-[disabled]:opacity-50", className), ...props }, children ?? text));
+}

package/esm/src/react/components/ui/context-menu.d.ts

@@ -0,0 +1,116 @@
+/**
+ * ContextMenu - a menu opened by right-click (the native `contextmenu` event) at
+ * the pointer position, rather than by clicking a trigger button. It shares the
+ * exact item / surface look of {@link ./dropdown-menu.tsx DropdownMenu} (classes
+ * ported 1:1 from Studio, token names remapped to veryfront's `[var(--token)]`
+ * vocabulary) and reuses the shared {@link ./floating.tsx Floating} portal +
+ * fixed-positioning helper for dismissal (outside-click / `Escape`), scroll
+ * following, viewport clamping, and portalling into the `[data-vf-ui]` token
+ * scope. The only behavioural difference from DropdownMenu is the trigger: it
+ * captures `onContextMenu`, calls `preventDefault()`, and opens the surface at
+ * the pointer's `clientX` / `clientY` via a zero-size virtual anchor.
+ *
+ * A11y work (roving focus, typeahead, focus trap) is tracked in
+ * anchored-surface.tsx and shared with the other menu surfaces.
+ *
+ * @example
+ * ```tsx
+ * <ContextMenu>
+ *   <ContextMenuTrigger className="rounded-md border border-[var(--edge-medium)] p-8">
+ *     Right-click here
+ *   </ContextMenuTrigger>
+ *   <ContextMenuContent>
+ *     <ContextMenuLabel>Actions</ContextMenuLabel>
+ *     <ContextMenuGroup>
+ *       <ContextMenuItem onSelect={() => console.log("cut")}>Cut</ContextMenuItem>
+ *       <ContextMenuItem onSelect={() => console.log("copy")}>Copy</ContextMenuItem>
+ *     </ContextMenuGroup>
+ *     <ContextMenuSeparator />
+ *     <ContextMenuItem onSelect={() => console.log("delete")}>Delete</ContextMenuItem>
+ *   </ContextMenuContent>
+ * </ContextMenu>
+ * ```
+ *
+ * @module react/components/ui/context-menu
+ */
+import * as React from "react";
+import { type PolymorphicButtonAttributes } from "./slot.js";
+import { type DisclosureOptions } from "./disclosure.js";
+/** Props accepted by `<ContextMenu>`. */
+export interface ContextMenuProps extends DisclosureOptions {
+    /** The trigger and content parts to compose. */
+    children: React.ReactNode;
+}
+/**
+ * ContextMenu root - owns open state and the pointer position. Renders a
+ * zero-size, `position: fixed` virtual anchor (kept inside the token scope so
+ * the portalled surface resolves `var(--…)`), which `Floating` measures to place
+ * the surface at the last right-click.
+ */
+export declare function ContextMenu({ children, open, defaultOpen, onOpenChange }: ContextMenuProps): React.ReactElement;
+/** Props accepted by `<ContextMenuTrigger>`. */
+export interface ContextMenuTriggerProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Merge the trigger behaviour onto your own element instead of a wrapper `div`. */
+    asChild?: boolean;
+    /** React 19: ref is a regular prop, forwarded to the trigger node. */
+    ref?: React.Ref<HTMLDivElement>;
+}
+/** Literal slotted trigger contract with an element-specific ref and events. */
+export type ContextMenuSlottedTriggerProps<T extends HTMLElement = HTMLElement> = Omit<React.HTMLAttributes<T>, "children" | "ref"> & {
+    asChild: true;
+    children: React.ReactElement;
+    ref?: React.Ref<T>;
+};
+/**
+ * Trigger - the region a right-click opens the menu over. Captures
+ * `onContextMenu`, calls `preventDefault()` (suppressing the browser's native
+ * menu), and opens the surface at the pointer coordinates. `asChild` merges onto
+ * the child element, which must forward `ref` to its DOM node.
+ */
+export declare function ContextMenuTrigger<T extends HTMLElement = HTMLElement>(props: ContextMenuSlottedTriggerProps<T>): React.ReactElement;
+export declare function ContextMenuTrigger(props: ContextMenuTriggerProps): React.ReactElement;
+/** Props accepted by `<ContextMenuContent>`. */
+export interface ContextMenuContentProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Horizontal edge of the surface aligned to the pointer. @default "start" */
+    align?: "start" | "end";
+    /** Consumer ref for the surface node (forwarded through `Floating`). */
+    ref?: React.Ref<HTMLDivElement>;
+}
+/** Menu surface - portalled to the pointer position while open. No border (Studio). */
+export declare function ContextMenuContent({ children, className, align, onKeyDown, ref, ...props }: ContextMenuContentProps): React.ReactElement | null;
+/** Groups related items with a tight inner gap (Studio: `gap-px p-0.5`). */
+export declare function ContextMenuGroup({ children, className }: {
+    children: React.ReactNode;
+    className?: string;
+}): React.ReactElement;
+/** Props accepted by `<ContextMenuItem>`. */
+export interface ContextMenuItemProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Called when the item is chosen (also closes the menu). */
+    onSelect?: () => void;
+    /** `asChild` merges item styling onto your own element. */
+    asChild?: boolean;
+    /** Consumer ref for the item node. */
+    ref?: React.Ref<HTMLButtonElement>;
+}
+/** Literal slotted item contract with element-specific refs and events. */
+export type ContextMenuSlottedItemProps<T extends HTMLElement = HTMLElement> = Omit<PolymorphicButtonAttributes<T>, "children" | "ref" | "onSelect"> & {
+    /** Called when the item is chosen (also closes the menu). */
+    onSelect?: () => void;
+    asChild: true;
+    children: React.ReactElement;
+    disabled?: boolean;
+    ref?: React.Ref<T>;
+};
+/** A selectable menu item. Icons render at `size-3.5` (14px). Closes on select. */
+export declare function ContextMenuItem<T extends HTMLElement = HTMLElement>(props: ContextMenuSlottedItemProps<T>): React.ReactElement;
+export declare function ContextMenuItem(props: ContextMenuItemProps): React.ReactElement;
+/** Full-width divider between groups (Studio: `-mx-2.5 my-2`). */
+export declare function ContextMenuSeparator({ className }: {
+    className?: string;
+}): React.ReactElement;
+/** Non-interactive section label - full-strength foreground (Studio). */
+export declare function ContextMenuLabel({ children, className, }: {
+    children: React.ReactNode;
+    className?: string;
+}): React.ReactElement;
+//# sourceMappingURL=context-menu.d.ts.map

package/esm/src/react/components/ui/context-menu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-menu.d.ts","sourceRoot":"","sources":["../../../../../src/src/react/components/ui/context-menu.tsx"],"names":[],"mappings":"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"}

package/esm/src/react/components/ui/context-menu.js

@@ -0,0 +1,168 @@
+/**
+ * ContextMenu - a menu opened by right-click (the native `contextmenu` event) at
+ * the pointer position, rather than by clicking a trigger button. It shares the
+ * exact item / surface look of {@link ./dropdown-menu.tsx DropdownMenu} (classes
+ * ported 1:1 from Studio, token names remapped to veryfront's `[var(--token)]`
+ * vocabulary) and reuses the shared {@link ./floating.tsx Floating} portal +
+ * fixed-positioning helper for dismissal (outside-click / `Escape`), scroll
+ * following, viewport clamping, and portalling into the `[data-vf-ui]` token
+ * scope. The only behavioural difference from DropdownMenu is the trigger: it
+ * captures `onContextMenu`, calls `preventDefault()`, and opens the surface at
+ * the pointer's `clientX` / `clientY` via a zero-size virtual anchor.
+ *
+ * A11y work (roving focus, typeahead, focus trap) is tracked in
+ * anchored-surface.tsx and shared with the other menu surfaces.
+ *
+ * @example
+ * ```tsx
+ * <ContextMenu>
+ *   <ContextMenuTrigger className="rounded-md border border-[var(--edge-medium)] p-8">
+ *     Right-click here
+ *   </ContextMenuTrigger>
+ *   <ContextMenuContent>
+ *     <ContextMenuLabel>Actions</ContextMenuLabel>
+ *     <ContextMenuGroup>
+ *       <ContextMenuItem onSelect={() => console.log("cut")}>Cut</ContextMenuItem>
+ *       <ContextMenuItem onSelect={() => console.log("copy")}>Copy</ContextMenuItem>
+ *     </ContextMenuGroup>
+ *     <ContextMenuSeparator />
+ *     <ContextMenuItem onSelect={() => console.log("delete")}>Delete</ContextMenuItem>
+ *   </ContextMenuContent>
+ * </ContextMenu>
+ * ```
+ *
+ * @module react/components/ui/context-menu
+ */
+import * as React from "react";
+import { cx as cn } from "./cva.js";
+import { composeRefs, Slot } from "./slot.js";
+import { Floating } from "./floating.js";
+import { focusWithoutScroll } from "./focus-management.js";
+import { useMenuContentKeyboard } from "./menu-keyboard.js";
+import { useDisclosure } from "./disclosure.js";
+const ContextMenuContext = React.createContext(null);
+/**
+ * ContextMenu root - owns open state and the pointer position. Renders a
+ * zero-size, `position: fixed` virtual anchor (kept inside the token scope so
+ * the portalled surface resolves `var(--…)`), which `Floating` measures to place
+ * the surface at the last right-click.
+ */
+export function ContextMenu({ children, open, defaultOpen, onOpenChange }) {
+    const { open: isOpen, setOpen } = useDisclosure({ open, defaultOpen, onOpenChange });
+    const anchorRef = React.useRef(null);
+    const triggerRef = React.useRef(null);
+    const [pos, setPos] = React.useState({ x: 0, y: 0 });
+    const openAt = React.useCallback((x, y) => {
+        setPos({ x, y });
+        setOpen(true);
+    }, [setOpen]);
+    const ctx = React.useMemo(() => ({ open: isOpen, setOpen, anchorRef, triggerRef, openAt }), [isOpen, setOpen, openAt]);
+    return (React.createElement(ContextMenuContext.Provider, { value: ctx },
+        React.createElement("span", { ref: anchorRef, "aria-hidden": "true", style: {
+                position: "fixed",
+                left: pos.x,
+                top: pos.y,
+                width: 0,
+                height: 0,
+                pointerEvents: "none",
+            } }),
+        children));
+}
+export function ContextMenuTrigger({ asChild, onContextMenu, onKeyDown, children, ref, role, tabIndex, "aria-haspopup": ariaHasPopup, ...props }) {
+    const ctx = React.useContext(ContextMenuContext);
+    const triggerProps = asChild
+        ? { role, tabIndex, "aria-haspopup": ariaHasPopup }
+        : { role: role ?? "button", tabIndex: tabIndex ?? 0, "aria-haspopup": ariaHasPopup ?? "menu" };
+    const setTriggerRef = React.useCallback((element) => {
+        if (ctx)
+            ctx.triggerRef.current = element;
+    }, [ctx]);
+    const composedRef = React.useMemo(() => composeRefs(setTriggerRef, ref), [ref, setTriggerRef]);
+    const stateProps = {
+        "data-state": ctx?.open ? "open" : "closed",
+        onContextMenu: (event) => {
+            onContextMenu?.(event);
+            if (event.defaultPrevented)
+                return;
+            event.preventDefault();
+            ctx?.openAt(event.clientX, event.clientY);
+        },
+        onKeyDown: (event) => {
+            onKeyDown?.(event);
+            if (event.defaultPrevented || !ctx)
+                return;
+            if (event.key !== "ContextMenu" && !(event.key === "F10" && event.shiftKey))
+                return;
+            event.preventDefault();
+            const rect = event.currentTarget.getBoundingClientRect();
+            ctx.openAt(rect.left, rect.bottom);
+        },
+    };
+    if (asChild) {
+        return (React.createElement(Slot, { ref: composedRef, ...triggerProps, ...stateProps, ...props }, children));
+    }
+    return (React.createElement("div", { ref: composedRef, ...triggerProps, ...stateProps, ...props }, children));
+}
+/** Menu surface - portalled to the pointer position while open. No border (Studio). */
+export function ContextMenuContent({ children, className, align = "start", onKeyDown, ref, ...props }) {
+    const ctx = React.useContext(ContextMenuContext);
+    if (!ctx)
+        return null;
+    const handleKeyDown = useMenuContentKeyboard({
+        onKeyDown,
+        setOpen: ctx.setOpen,
+        triggerRef: ctx.triggerRef,
+    });
+    return (React.createElement(Floating, { anchorRef: ctx.anchorRef, open: ctx.open, align: align, onDismiss: () => ctx.setOpen(false), initialFocus: "[role='menuitem']:not([aria-disabled='true'])", returnFocusRef: ctx.triggerRef, contentRef: ref, role: "menu", "aria-orientation": "vertical", onKeyDown: handleKeyDown, className: cn("z-50 min-w-[260px] overflow-hidden rounded-lg bg-[var(--popover)] p-2.5 text-[var(--foreground)] shadow-sm outline-none", className), ...props }, children));
+}
+/** Groups related items with a tight inner gap (Studio: `gap-px p-0.5`). */
+export function ContextMenuGroup({ children, className }) {
+    return (React.createElement("div", { role: "group", className: cn("flex flex-col gap-px p-0.5", className) }, children));
+}
+export function ContextMenuItem({ children, className, onSelect, onClick, onKeyDown, disabled, asChild, ref, ...props }) {
+    const ctx = React.useContext(ContextMenuContext);
+    const closeAndRestoreFocus = React.useCallback(() => {
+        ctx?.setOpen(false);
+        const trigger = ctx?.triggerRef.current;
+        queueMicrotask(() => {
+            if (trigger?.isConnected)
+                focusWithoutScroll(trigger);
+        });
+    }, [ctx]);
+    const itemProps = {
+        role: "menuitem",
+        "aria-disabled": disabled || undefined,
+        disabled,
+        className: cn("relative flex w-full cursor-pointer select-none items-center gap-2.5 rounded-md px-3 h-[36px] text-base font-normal text-left text-[var(--foreground)] outline-none transition-colors", "hover:bg-[var(--tertiary)] focus:bg-[var(--tertiary)] dark:hover:bg-[var(--accent)] dark:focus:bg-[var(--accent)]", "disabled:pointer-events-none disabled:opacity-50 [&_svg]:size-3.5 [&_svg]:shrink-0", className),
+        onClick: (event) => {
+            if (disabled)
+                return;
+            onClick?.(event);
+            if (event.defaultPrevented)
+                return;
+            onSelect?.();
+            closeAndRestoreFocus();
+        },
+        onKeyDown: (event) => {
+            onKeyDown?.(event);
+            if (event.defaultPrevented)
+                return;
+            if (disabled || (event.key !== "Enter" && event.key !== " "))
+                return;
+            event.preventDefault();
+            event.currentTarget.click();
+        },
+    };
+    if (asChild) {
+        return (React.createElement(Slot, { ref: ref, ...itemProps, ...props }, children));
+    }
+    return (React.createElement("button", { type: "button", ref: ref, ...itemProps, ...props }, children));
+}
+/** Full-width divider between groups (Studio: `-mx-2.5 my-2`). */
+export function ContextMenuSeparator({ className }) {
+    return React.createElement("div", { className: cn("-mx-2.5 my-2 h-px bg-[var(--separator)]", className) });
+}
+/** Non-interactive section label - full-strength foreground (Studio). */
+export function ContextMenuLabel({ children, className, }) {
+    return (React.createElement("div", { className: cn("px-3 py-1.5 mb-0.5 text-sm font-medium text-[var(--foreground)]", className) }, children));
+}