@nanisoft/prism-ui 0.10.1 → 0.13.0

package/dist/components/ui/command-palette.js

@@ -0,0 +1,176 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
+import { Dialog, DialogContent, DialogTitle } from './dialog.js';
+import { locate, RANKS } from '../../lib/rank.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * A searchable list of commands, over the Dialog this system already has.
+ *
+ * **It ranks, and that is the difference between this and a filtered menu.** A
+ * palette that filters without ordering shows every command containing the query
+ * in whatever order the groups happened to be declared, so the command you meant
+ * sits below one that merely mentions your query. Ranking by where the match falls
+ * puts it first, and the whole premise of a palette is that typing three letters
+ * is faster than navigating to it.
+ *
+ * **It is composed on the Dialog rather than beside it.** Focus trapping, Escape,
+ * the portal, the scroll lock and the return of focus to the trigger are five
+ * behaviours that are correct in the Dialog and would be five chances to get one
+ * wrong here. A palette that rolled its own overlay would be a second answer to
+ * all five questions, and the second answer is the one that ships the bug.
+ *
+ * **The matched run is emphasised by weight, not by a background.** A Mark is the
+ * right treatment in a list of results, where the match is the reason the row is
+ * there and a full background is the point. In a palette the match is a hint while
+ * the row's label is what the reader is reading, and a saturated background on
+ * every matched character fights the text it is inside. So the palette uses the
+ * quieter of the two, and the two surfaces are not the same surface. See the Mark
+ * documentation for the other half of that decision.
+ *
+ * **The search field keeps focus for the whole interaction.** Arrows move a
+ * highlight through the list rather than moving focus into it, so a reader can keep
+ * typing while they choose, and the highlighted row carries the state. That is the
+ * combobox pattern and it is the reason the arrows do not steal the caret.
+ */
+function CommandPalette({ open, onOpenChange, label, inputLabel, placeholder, groups, suggest, empty, className, }) {
+    const [query, setQuery] = useState('');
+    const [active, setActive] = useState(0);
+    const listRef = useRef(null);
+    const titleId = useId();
+    const trimmed = query.trim();
+    /**
+     * The ranked result: groups in their declared order, items within a group by
+     * rank. A group whose every item filtered out disappears rather than rendering
+     * an empty heading, because a heading over nothing is a divider a reader has to
+     * read past.
+     */
+    const results = useMemo(() => {
+        if (trimmed === '') {
+            // With nothing typed there is nothing to rank, so every row is a row with no
+            // match to emphasise. Suggestions replace the groups rather than joining
+            // them, because a palette that opens showing both a suggestion list and the
+            // full command list is a palette with two answers to what it is for.
+            return suggest
+                ? [
+                    {
+                        id: '__suggest',
+                        label: suggest.label,
+                        hits: suggest.items.map((item) => ({ item, rank: RANKS.prefix })),
+                    },
+                ]
+                : groups.map((group) => ({
+                    id: group.id,
+                    label: group.label,
+                    hits: group.items.map((item) => ({ item, rank: RANKS.prefix })),
+                }));
+        }
+        const scored = [];
+        for (const group of groups) {
+            const hits = group.items
+                .map((item) => {
+                const inLabel = locate(item.label, trimmed);
+                if (inLabel.rank < RANKS.keyword)
+                    return { item, rank: inLabel.rank, range: inLabel.range };
+                // Keywords are searched only after the label misses, so a keyword can
+                // never outrank a label match. A reader who typed the name of a command
+                // wants that command, and a synonym is a fallback rather than a rival.
+                const keywordHit = (item.keywords ?? []).some((word) => word.toLowerCase().includes(trimmed.toLowerCase()));
+                return keywordHit ? { item, rank: RANKS.keyword } : null;
+            })
+                .filter((hit) => hit !== null)
+                .sort((a, b) => a.rank - b.rank);
+            if (hits.length > 0)
+                scored.push({ id: group.id, label: group.label, hits });
+        }
+        // The groups are ordered by their best hit, not by where they were declared.
+        // Ranking only *within* a group leaves the premise of the surface broken: a
+        // command in a later group that matches exactly sits below a command in an
+        // earlier group that matches badly, so a reader still scans. Ordering the
+        // groups by their strongest member puts the best answer at the top and keeps
+        // the headings, which is the whole of what a grouped list is for. The sort is
+        // stable, so groups whose best hits tie keep the order they were declared in.
+        return scored.sort((a, b) => Math.min(...a.hits.map((hit) => hit.rank)) - Math.min(...b.hits.map((hit) => hit.rank)));
+    }, [groups, suggest, trimmed]);
+    /** The flat order, which is the order the arrows walk. */
+    const flat = useMemo(() => results.flatMap((group) => group.hits.map((hit) => hit.item)), [results]);
+    // The highlight is clamped rather than reset on every keystroke. Resetting to
+    // zero is the obvious choice and it is wrong: a reader who arrows down three
+    // rows and then types one more character is choosing from a list that just
+    // changed under them, and yanking the highlight back to the top discards where
+    // they were. Clamping keeps the position when it still exists.
+    const activeIndex = Math.min(active, Math.max(flat.length - 1, 0));
+    useEffect(() => {
+        if (!open) {
+            // Reset on close rather than on open, so the palette does not reopen showing
+            // the last query typed into it. A surface that remembers its filter between
+            // visits is a surface whose state the reader has to reason about.
+            setQuery('');
+            setActive(0);
+        }
+    }, [open]);
+    const run = useCallback((item) => {
+        onOpenChange(false);
+        item.onSelect();
+    }, [onOpenChange]);
+    const onKeyDown = (event) => {
+        if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+            if (flat.length === 0)
+                return;
+            event.preventDefault();
+            // Wraps, and that is the one place a list is allowed to: a list that stops
+            // at the end makes a reader who overshot press Up to come back, and a
+            // palette is a transient surface where overshoot is common.
+            setActive((index) => {
+                const next = event.key === 'ArrowDown' ? index + 1 : index - 1;
+                return (next + flat.length) % flat.length;
+            });
+            return;
+        }
+        if (event.key === 'Enter') {
+            const item = flat[activeIndex];
+            // Enter with nothing highlighted does nothing rather than running the first
+            // item, because running a command a reader did not point at is the one
+            // outcome a palette must never produce.
+            if (item === undefined)
+                return;
+            event.preventDefault();
+            run(item);
+        }
+    };
+    /** Keeps the highlighted row in view when the arrows move it. */
+    useEffect(() => {
+        const list = listRef.current;
+        if (list === null)
+            return;
+        const row = list.querySelector('[data-active="true"]');
+        row?.scrollIntoView({ block: 'nearest' });
+    }, [activeIndex]);
+    return (_jsx(Dialog, { open: open, onOpenChange: onOpenChange, children: _jsxs(DialogContent
+        // The palette is a wide, top-anchored surface rather than a centred card,
+        // and it carries no visible heading: the search field is what a reader
+        // looks at, and a heading above it would be a label for the surface the
+        // reader is already in. The DialogTitle is still rendered and still names
+        // the dialog for assistive technology, which is the whole reason it
+        // exists separately from anything visible.
+        , { 
+            // The palette is a wide, top-anchored surface rather than a centred card,
+            // and it carries no visible heading: the search field is what a reader
+            // looks at, and a heading above it would be a label for the surface the
+            // reader is already in. The DialogTitle is still rendered and still names
+            // the dialog for assistive technology, which is the whole reason it
+            // exists separately from anything visible.
+            side: "top", showCloseButton: false, className: cn('max-w-xl gap-0 p-0', className), children: [_jsx(DialogTitle, { className: "sr-only", children: label }), _jsx("div", { className: "border-border flex items-center border-b px-3", children: _jsx("input", { "data-slot": "command-palette-input", type: "text", role: "combobox", "aria-expanded": flat.length > 0, "aria-controls": `${titleId}-list`, "aria-activedescendant": flat[activeIndex] === undefined ? undefined : `${titleId}-item-${flat[activeIndex]?.id}`, "aria-label": inputLabel, ...(placeholder === undefined ? null : { placeholder }), value: query, onChange: (event) => {
+                            setQuery(event.target.value);
+                            setActive(0);
+                        }, onKeyDown: onKeyDown, 
+                        // The field is focused when the palette opens, so a reader can type
+                        // immediately. Nothing else in the surface is focusable, which is what
+                        // makes this a combobox rather than a list of buttons.
+                        autoFocus: true, className: "placeholder:text-muted-foreground h-12 w-full bg-transparent text-sm outline-none" }) }), _jsx("div", { "data-slot": "command-palette-list", id: `${titleId}-list`, ref: listRef, role: "listbox", "aria-label": label, className: "max-h-80 overflow-y-auto p-1", children: results.length === 0 ? (_jsxs("p", { "data-slot": "command-palette-empty", className: "text-muted-foreground px-3 py-6 text-center text-sm", children: [empty.message(trimmed), empty.hint === undefined ? null : (_jsx("span", { className: "mt-1 block text-xs", children: empty.hint }))] })) : (results.map((group) => (_jsxs("div", { "data-slot": "command-palette-group", className: "mb-1 last:mb-0", children: [_jsx("div", { "data-slot": "command-palette-group-label", className: "text-muted-foreground bg-popover text-xs font-medium tracking-wide uppercase sticky top-0 px-3 py-1.5", children: group.label }), group.hits.map((hit) => {
+                                const index = flat.indexOf(hit.item);
+                                const isActive = index === activeIndex;
+                                return (_jsxs("div", { id: `${titleId}-item-${hit.item.id}`, "data-slot": "command-palette-item", "data-active": isActive, role: "option", "aria-selected": isActive, onMouseEnter: () => setActive(index), onClick: () => run(hit.item), className: cn('flex cursor-pointer items-baseline justify-between gap-3 rounded-sm px-3 py-2 text-sm', isActive && 'bg-accent text-accent-foreground', !isActive && 'text-muted-foreground hover:text-foreground'), children: [_jsx("span", { className: "min-w-0 truncate", children: hit.range === undefined ? (hit.item.label) : (_jsxs(_Fragment, { children: [hit.item.label.slice(0, hit.range[0]), _jsx("strong", { className: "text-foreground font-semibold", children: hit.item.label.slice(hit.range[0], hit.range[1]) }), hit.item.label.slice(hit.range[1])] })) }), hit.item.hint === undefined ? null : (_jsx("span", { className: "shrink-0 text-xs", children: hit.item.hint }))] }, hit.item.id));
+                            })] }, group.id)))) })] }) }));
+}
+export { CommandPalette };

package/dist/components/ui/command.d.ts

@@ -0,0 +1,82 @@
+import type { ComponentProps } from 'react';
+/**
+ * The props the Command row accepts.
+ *
+ * The row holds no words of its own. `label` is the command, `hint` is whatever
+ * the caller puts at the far end of it, and `keywords` are the extra words that
+ * should find it. Every one of the three is a prop because the reader's language
+ * is the caller's, and a row that ships an English label ships a claim about a
+ * command in a product that is not this system's.
+ */
+export interface CommandProps extends Omit<ComponentProps<'div'>, 'onSelect'> {
+    /** The words on the row. */
+    label: string;
+    /**
+     * A short run at the far end of the row, usually the keyboard shortcut.
+     *
+     * It is set apart from the label rather than shown on a second line, because a
+     * two-line row doubles the height of every row in the list and a palette is a
+     * surface a reader scans rather than reads.
+     */
+    hint?: string;
+    /**
+     * Words that should also find this command.
+     *
+     * The row does not render them, and that is the point of accepting them: a
+     * caller keeps one object per command and spreads it onto the row, so the same
+     * object can be read by whatever ranks the list. Accepting the field here is
+     * what lets that spread be total rather than a hand-picked three fields.
+     */
+    keywords?: readonly string[];
+    /**
+     * The characters of `label` that matched the query, as a start and an end.
+     *
+     * The row does not decide where the match is; whoever ranked the list does, and
+     * passes the range down. That keeps one ranking in the system rather than one
+     * here and a different one in the palette.
+     */
+    matchRange?: readonly [number, number];
+    /**
+     * Whether this is the highlighted row.
+     *
+     * The highlight is drawn on the row rather than moved as focus, so a reader can
+     * keep typing in the field while they choose. A list that moves DOM focus into
+     * itself takes the caret away mid-word, which is why the palette and the
+     * combobox both drive this from the arrow keys instead.
+     */
+    active?: boolean;
+    /** Called when the reader chooses the command. */
+    onSelect?: () => void;
+    /** Called when the pointer moves onto the row, so the highlight can follow it. */
+    onHover?: () => void;
+}
+/**
+ * One command, as a row in a list of commands.
+ *
+ * **This is the leaf; `CommandPalette` is the composite.** The palette is the
+ * dialog, the overlay behaviour, the scroll lock and the return of focus. This
+ * is one line of what it draws, for a caller who wants the row without the
+ * dialog: a settings page whose whole search list is fourteen commands, a
+ * command menu on a button, a launcher inside a panel that is already a
+ * floating surface and does not want a second overlay stacked on it.
+ *
+ * **It ranks nothing.** The row takes `matchRange` as a prop because deciding
+ * where a query matches is one decision and this system makes it once, in the
+ * shared scorer the palette and the combobox both call. A row that scored its own
+ * label would be a second scorer that starts agreeing with the first and stops.
+ *
+ * **The match is emphasised by weight, not by a colour.** A `<strong>` inherits
+ * whatever ink the row already has, so it is correct on the quiet row and on the
+ * highlighted one. A colour would be a second ink to keep in step with the two row
+ * states, and a saturated background on every matched character fights the label
+ * it sits inside.
+ *
+ * **The row takes `role="option"` and belongs in a listbox.** The parent owns the
+ * `role="listbox"`, the `aria-activedescendant` wiring and the roving `tabIndex`;
+ * the row is one option inside it. The row is not focusable by Tab, because the
+ * field above it keeps the caret for the whole interaction. It can still take
+ * programmatic focus, and it draws a full-strength ring when it does.
+ */
+declare function Command({ className, label, hint, keywords, matchRange, active, onSelect, onHover, ...props }: CommandProps): import("react").JSX.Element;
+export { Command };
+//# sourceMappingURL=command.d.ts.map

package/dist/components/ui/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../src/components/ui/command.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAa,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC3E,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACtC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,iBAAS,OAAO,CAAC,EACf,SAAS,EACT,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,UAAU,EACV,MAAc,EACd,QAAQ,EACR,OAAO,EACP,GAAG,KAAK,EACT,EAAE,YAAY,+BAqCd;AAED,OAAO,EAAE,OAAO,EAAE,CAAA"}

package/dist/components/ui/command.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from '../../lib/utils.js';
+/**
+ * One command, as a row in a list of commands.
+ *
+ * **This is the leaf; `CommandPalette` is the composite.** The palette is the
+ * dialog, the overlay behaviour, the scroll lock and the return of focus. This
+ * is one line of what it draws, for a caller who wants the row without the
+ * dialog: a settings page whose whole search list is fourteen commands, a
+ * command menu on a button, a launcher inside a panel that is already a
+ * floating surface and does not want a second overlay stacked on it.
+ *
+ * **It ranks nothing.** The row takes `matchRange` as a prop because deciding
+ * where a query matches is one decision and this system makes it once, in the
+ * shared scorer the palette and the combobox both call. A row that scored its own
+ * label would be a second scorer that starts agreeing with the first and stops.
+ *
+ * **The match is emphasised by weight, not by a colour.** A `<strong>` inherits
+ * whatever ink the row already has, so it is correct on the quiet row and on the
+ * highlighted one. A colour would be a second ink to keep in step with the two row
+ * states, and a saturated background on every matched character fights the label
+ * it sits inside.
+ *
+ * **The row takes `role="option"` and belongs in a listbox.** The parent owns the
+ * `role="listbox"`, the `aria-activedescendant` wiring and the roving `tabIndex`;
+ * the row is one option inside it. The row is not focusable by Tab, because the
+ * field above it keeps the caret for the whole interaction. It can still take
+ * programmatic focus, and it draws a full-strength ring when it does.
+ */
+function Command({ className, label, hint, keywords, matchRange, active = false, onSelect, onHover, ...props }) {
+    return (_jsxs("div", { "data-slot": "command", "data-active": active, "data-keywords": keywords?.join(), role: "option", "aria-selected": active, onClick: onSelect, onMouseEnter: onHover, 
+        // The row suppresses the browser outline and draws a ring of its own at full
+        // strength, because the class that suppressed it is the only indicator a reader
+        // who moved focus onto a row programmatically would otherwise have.
+        className: cn('text-muted-foreground hover:text-foreground flex cursor-pointer items-baseline justify-between gap-3 rounded-sm px-3 py-2 text-sm outline-none', 'focus-visible:ring-ring focus-visible:ring-[3px]', active && 'bg-accent text-accent-foreground', className), ...props, children: [_jsx("span", { className: "min-w-0 truncate", children: matchRange === undefined ? (label) : (_jsxs(_Fragment, { children: [label.slice(0, matchRange[0]), _jsx("strong", { className: "font-semibold", children: label.slice(matchRange[0], matchRange[1]) }), label.slice(matchRange[1])] })) }), hint === undefined ? null : _jsx("span", { className: "shrink-0 text-xs", children: hint })] }));
+}
+export { Command };

package/dist/components/ui/context-menu.d.ts

@@ -0,0 +1,151 @@
+import type { ComponentProps } from 'react';
+/**
+ * The props the ContextMenu root forwards to Base UI.
+ *
+ * Declared here rather than re-exported from Base UI so no upstream type
+ * crosses the package seam (ticket 07 section 6).
+ */
+export interface ContextMenuProps {
+    /** The controlled open state. */
+    open?: boolean;
+    /** The initially open state, for an uncontrolled context menu. */
+    defaultOpen?: boolean;
+    /** Called when the open state changes. */
+    onOpenChange?: (open: boolean) => void;
+    /** The area the menu belongs to, and the menu itself. */
+    children?: React.ReactNode;
+}
+/**
+ * The props ContextMenuTrigger forwards to Base UI.
+ *
+ * The trigger is an area, not a control. It renders a `<div>` and carries no
+ * role of its own, because there is no gesture a keyboard reader can be taught
+ * to perform here that is not already a shortcut, and an element that pretends
+ * to be a button and is not one is a lie the Tab order then repeats.
+ */
+export interface ContextMenuTriggerProps extends ComponentProps<'div'> {
+}
+/**
+ * The props ContextMenuContent forwards to Base UI.
+ *
+ * Declared here rather than re-exported from Base UI so no upstream type
+ * crosses the package seam (ticket 07 section 6).
+ */
+export interface ContextMenuContentProps extends ComponentProps<'div'> {
+    /**
+     * The accessible name of this menu, read before its rows.
+     *
+     * Required rather than defaulted, because a context menu is opened by a
+     * gesture on a region rather than by a control the reader chose, so nothing
+     * on the page has already named it. Three menus in one table, each announced
+     * as "menu", is a page where a screen reader user cannot tell which surface
+     * they are in. The name says what the menu acts on, and it is the caller's
+     * word because only the caller knows what the region is.
+     */
+    label: string;
+    /** The distance in pixels between the pointer and the menu. @defaultValue 0 */
+    sideOffset?: number;
+    /** The distance in pixels along the alignment axis. @defaultValue 0 */
+    alignOffset?: number;
+}
+/** The props ContextMenuItem forwards to Base UI. */
+export interface ContextMenuItemProps extends ComponentProps<'div'> {
+    /** Whether the item reads as a destructive action. @defaultValue default */
+    variant?: 'default' | 'destructive';
+    /** Whether the item ignores user interaction. */
+    disabled?: boolean;
+}
+/** The props ContextMenuLinkItem forwards to Base UI. */
+export interface ContextMenuLinkItemProps extends ComponentProps<'a'> {
+    /** Whether the link reads as a destructive action. @defaultValue default */
+    variant?: 'default' | 'destructive';
+}
+/** The props ContextMenuLabel forwards to Base UI. */
+export interface ContextMenuLabelProps extends ComponentProps<'div'> {
+}
+/** The props ContextMenuSeparator forwards to Base UI. */
+export interface ContextMenuSeparatorProps extends ComponentProps<'div'> {
+}
+/** The props ContextMenuGroup forwards to Base UI. */
+export interface ContextMenuGroupProps extends ComponentProps<'div'> {
+}
+/** The props ContextMenuSub forwards to Base UI. */
+export interface ContextMenuSubProps {
+    /** The controlled open state of the submenu. */
+    open?: boolean;
+    /** The initially open state of the submenu. */
+    defaultOpen?: boolean;
+    /** Called when the submenu opens or closes. */
+    onOpenChange?: (open: boolean) => void;
+    /** The submenu trigger and its content. */
+    children?: React.ReactNode;
+}
+/** The props ContextMenuSubTrigger forwards to Base UI. */
+export interface ContextMenuSubTriggerProps extends ComponentProps<'div'> {
+}
+/** The props ContextMenuSubContent forwards to Base UI. */
+export interface ContextMenuSubContentProps extends ComponentProps<'div'> {
+    /** The distance in pixels between the submenu and the trigger. @defaultValue 0 */
+    sideOffset?: number;
+    /** The offset in pixels along the alignment axis. @defaultValue 0 */
+    alignOffset?: number;
+}
+/**
+ * A menu of commands opened by the secondary pointer gesture over a region.
+ *
+ * **It knows whether each row is a command or a destination, and so should the
+ * caller.** `ContextMenuItem` is a command: a `<div>` with `role="menuitem"`,
+ * operated by click or Enter, doing something. `ContextMenuLinkItem` is a
+ * destination: a real `<a href>`, so it can be opened in a new tab, copied by
+ * address, and crawled. A context menu holding "Copy link" beside "Open in new
+ * tab" is the case that gets a consumer's product wrong, because the second is
+ * the one a reader expects to middle-click. Splitting the two into two parts is
+ * what makes that decision visible at the call site rather than at the review.
+ *
+ * **Nothing here is the only route to a command.** The gesture is secondary: it
+ * is unreachable by a keyboard and undiscoverable by a touch reader, so every
+ * row here must be reachable somewhere else on the page. The trigger is a plain
+ * `<div>` with no role for the same reason: an element that looks like a button
+ * and is not one teaches a reader a gesture that then does nothing.
+ *
+ * The menu is navigable with the arrow keys and with typeahead, and Escape or an
+ * outside press closes it. A menu is a list of commands, so a command belonging
+ * on the surface belongs on the surface, not behind a right-click.
+ */
+declare function ContextMenu({ ...props }: ContextMenuProps): import("react").JSX.Element;
+/**
+ * The region the menu belongs to. A secondary press inside it opens the menu.
+ *
+ * It renders a `<div>` and nothing more, because it is a region rather than a
+ * control. Base UI also treats a long press as the open gesture, which is what
+ * makes the menu reachable at all on a touch screen, and it is the reason a
+ * context menu is an addition to a surface rather than a substitute for one.
+ */
+declare function ContextMenuTrigger({ className, ...props }: ContextMenuTriggerProps): import("react").JSX.Element;
+/** The floating menu surface, opened at the pointer. */
+declare function ContextMenuContent({ className, label, sideOffset, alignOffset, ...props }: ContextMenuContentProps): import("react").JSX.Element;
+/** One command in the menu. It does something rather than going somewhere. */
+declare function ContextMenuItem({ className, variant, ...props }: ContextMenuItemProps): import("react").JSX.Element;
+/**
+ * One destination in the menu, rendered as a native anchor.
+ *
+ * A link is a `<a href>` and nothing else, so the browser's own affordances
+ * apply: middle-click opens it in a new tab, and "copy link address" copies a
+ * real address. A command styled as a link has neither, and a reader who
+ * middle-clicks a `div` gets nothing at all.
+ */
+declare function ContextMenuLinkItem({ className, variant, ...props }: ContextMenuLinkItemProps): import("react").JSX.Element;
+/** A non-interactive heading inside a group of rows. */
+declare function ContextMenuLabel({ className, ...props }: ContextMenuLabelProps): import("react").JSX.Element;
+/** A rule between groups of rows. */
+declare function ContextMenuSeparator({ className, ...props }: ContextMenuSeparatorProps): import("react").JSX.Element;
+/** A labelled set of related rows. */
+declare function ContextMenuGroup({ className, ...props }: ContextMenuGroupProps): import("react").JSX.Element;
+/** A group of rows that opens into a second menu. */
+declare function ContextMenuSub({ ...props }: ContextMenuSubProps): import("react").JSX.Element;
+/** The row that opens a submenu. */
+declare function ContextMenuSubTrigger({ className, children, ...props }: ContextMenuSubTriggerProps): import("react").JSX.Element;
+/** The nested menu surface. */
+declare function ContextMenuSubContent({ className, sideOffset, alignOffset, ...props }: ContextMenuSubContentProps): import("react").JSX.Element;
+export { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem, ContextMenuLinkItem, ContextMenuLabel, ContextMenuSeparator, ContextMenuGroup, ContextMenuSub, ContextMenuSubTrigger, ContextMenuSubContent, };
+//# sourceMappingURL=context-menu.d.ts.map

package/dist/components/ui/context-menu.d.ts.map

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

package/dist/components/ui/context-menu.js

@@ -0,0 +1,97 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ContextMenu as ContextMenuPrimitive } from '@base-ui/react/context-menu';
+import { ChevronRightIcon } from 'lucide-react';
+import { cn } from '../../lib/utils.js';
+/**
+ * The menu surface's own class string, shared by the top level and a submenu.
+ *
+ * The panel takes focus when the menu opens, so it is a focusable element and it
+ * draws the focus ring at full strength rather than suppressing the outline and
+ * inheriting nothing. A menu item carries `role="menuitem"` and Base UI moves a
+ * highlighted state through the list instead of a DOM focus ring, so the ring
+ * belongs here and nowhere else in the surface.
+ */
+const POPUP = 'bg-popover text-popover-foreground z-50 max-h-(--available-height) min-w-40 overflow-x-hidden overflow-y-auto rounded-md border p-1 shadow-md outline-none transition-[opacity,transform] duration-fast ease-out focus-visible:ring-ring focus-visible:ring-[3px] data-[starting-style]:scale-95 data-[starting-style]:opacity-0 data-[ending-style]:scale-95 data-[ending-style]:opacity-0';
+/** One row in a context menu, whether it is a command or a link. */
+const ROW = 'focus:bg-accent focus:text-accent-foreground data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground relative flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*="size-"])]:size-4';
+/**
+ * A menu of commands opened by the secondary pointer gesture over a region.
+ *
+ * **It knows whether each row is a command or a destination, and so should the
+ * caller.** `ContextMenuItem` is a command: a `<div>` with `role="menuitem"`,
+ * operated by click or Enter, doing something. `ContextMenuLinkItem` is a
+ * destination: a real `<a href>`, so it can be opened in a new tab, copied by
+ * address, and crawled. A context menu holding "Copy link" beside "Open in new
+ * tab" is the case that gets a consumer's product wrong, because the second is
+ * the one a reader expects to middle-click. Splitting the two into two parts is
+ * what makes that decision visible at the call site rather than at the review.
+ *
+ * **Nothing here is the only route to a command.** The gesture is secondary: it
+ * is unreachable by a keyboard and undiscoverable by a touch reader, so every
+ * row here must be reachable somewhere else on the page. The trigger is a plain
+ * `<div>` with no role for the same reason: an element that looks like a button
+ * and is not one teaches a reader a gesture that then does nothing.
+ *
+ * The menu is navigable with the arrow keys and with typeahead, and Escape or an
+ * outside press closes it. A menu is a list of commands, so a command belonging
+ * on the surface belongs on the surface, not behind a right-click.
+ */
+function ContextMenu({ ...props }) {
+    return _jsx(ContextMenuPrimitive.Root, { ...props });
+}
+/**
+ * The region the menu belongs to. A secondary press inside it opens the menu.
+ *
+ * It renders a `<div>` and nothing more, because it is a region rather than a
+ * control. Base UI also treats a long press as the open gesture, which is what
+ * makes the menu reachable at all on a touch screen, and it is the reason a
+ * context menu is an addition to a surface rather than a substitute for one.
+ */
+function ContextMenuTrigger({ className, ...props }) {
+    return (_jsx(ContextMenuPrimitive.Trigger, { "data-slot": "context-menu-trigger", className: cn(className), ...props }));
+}
+/** The floating menu surface, opened at the pointer. */
+function ContextMenuContent({ className, label, sideOffset = 0, alignOffset = 0, ...props }) {
+    return (_jsx(ContextMenuPrimitive.Portal, { children: _jsx(ContextMenuPrimitive.Positioner, { sideOffset: sideOffset, alignOffset: alignOffset, children: _jsx(ContextMenuPrimitive.Popup, { "data-slot": "context-menu-content", "aria-label": label, className: cn(POPUP, className), ...props }) }) }));
+}
+/** One command in the menu. It does something rather than going somewhere. */
+function ContextMenuItem({ className, variant = 'default', ...props }) {
+    return (_jsx(ContextMenuPrimitive.Item, { "data-slot": "context-menu-item", "data-variant": variant, className: cn(ROW, 'data-[variant=destructive]:text-destructive data-[variant=destructive]:data-[highlighted]:bg-destructive/10', className), ...props }));
+}
+/**
+ * One destination in the menu, rendered as a native anchor.
+ *
+ * A link is a `<a href>` and nothing else, so the browser's own affordances
+ * apply: middle-click opens it in a new tab, and "copy link address" copies a
+ * real address. A command styled as a link has neither, and a reader who
+ * middle-clicks a `div` gets nothing at all.
+ */
+function ContextMenuLinkItem({ className, variant = 'default', ...props }) {
+    return (_jsx(ContextMenuPrimitive.LinkItem, { "data-slot": "context-menu-link-item", "data-variant": variant, className: cn(ROW, 'data-[variant=destructive]:text-destructive data-[variant=destructive]:data-[highlighted]:bg-destructive/10', className), ...props }));
+}
+/** A non-interactive heading inside a group of rows. */
+function ContextMenuLabel({ className, ...props }) {
+    return (_jsx(ContextMenuPrimitive.GroupLabel, { "data-slot": "context-menu-label", className: cn('px-2 py-1.5 text-xs font-medium', className), ...props }));
+}
+/** A rule between groups of rows. */
+function ContextMenuSeparator({ className, ...props }) {
+    return (_jsx(ContextMenuPrimitive.Separator, { "data-slot": "context-menu-separator", className: cn('bg-border -mx-1 my-1 h-px', className), ...props }));
+}
+/** A labelled set of related rows. */
+function ContextMenuGroup({ className, ...props }) {
+    return (_jsx(ContextMenuPrimitive.Group, { "data-slot": "context-menu-group", className: cn(className), ...props }));
+}
+/** A group of rows that opens into a second menu. */
+function ContextMenuSub({ ...props }) {
+    return _jsx(ContextMenuPrimitive.SubmenuRoot, { ...props });
+}
+/** The row that opens a submenu. */
+function ContextMenuSubTrigger({ className, children, ...props }) {
+    return (_jsxs(ContextMenuPrimitive.SubmenuTrigger, { "data-slot": "context-menu-sub-trigger", className: cn(ROW, className), ...props, children: [children, _jsx(ChevronRightIcon, { className: "ml-auto size-4" })] }));
+}
+/** The nested menu surface. */
+function ContextMenuSubContent({ className, sideOffset = 0, alignOffset = 0, ...props }) {
+    return (_jsx(ContextMenuPrimitive.Portal, { children: _jsx(ContextMenuPrimitive.Positioner, { sideOffset: sideOffset, alignOffset: alignOffset, children: _jsx(ContextMenuPrimitive.Popup, { "data-slot": "context-menu-sub-content", className: cn(POPUP, className), ...props }) }) }));
+}
+export { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem, ContextMenuLinkItem, ContextMenuLabel, ContextMenuSeparator, ContextMenuGroup, ContextMenuSub, ContextMenuSubTrigger, ContextMenuSubContent, };

package/dist/components/ui/cta-link.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cva } from 'class-variance-authority';
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/utils.js';
 /*
  * Why this is a second Component rather than an `as` or `href` prop on `Button`.
  * The design system has already answered this twice, in the two places a trail