@xenosystem/elements-react 0.0.1

package/dist/overlays/Menu.d.ts

@@ -0,0 +1,28 @@
+import type { ReactElement, ReactNode } from 'react';
+/**
+ * `<Menu>` — a {@link Popover} whose panel is a `role="menu"` list of {@link MenuItem} rows. It layers
+ * the ARIA menu keyboard model onto Popover's anchoring + dismissal: on open, focus moves to the first
+ * enabled item; Arrow Up/Down move focus between items (wrapping), Home/End jump to the ends, Tab and
+ * Escape close it, and activating an item (click / Enter / Space) closes the menu. Disabled items are
+ * skipped by the roving focus and never dismiss the menu.
+ *
+ * Controlled: `open` + `onOpenChange`. Wire the `trigger`'s `onClick` to toggle `open` (and set its
+ * `aria-haspopup="menu"` + `aria-expanded`); Popover restores focus to it when the menu closes.
+ */
+export interface MenuProps {
+    /** Whether the menu panel is open. */
+    readonly open: boolean;
+    /** Called with the next open state (on select, Tab, Escape, and outside click). */
+    readonly onOpenChange?: (open: boolean) => void;
+    /** The anchor button — wire its `onClick` to toggle `open`. */
+    readonly trigger: ReactNode;
+    /** The {@link MenuItem} rows. */
+    readonly children?: ReactNode;
+    /** Which trigger edge the panel aligns to. Default `start`. */
+    readonly align?: 'start' | 'end';
+    /** Accessible name for the menu list. */
+    readonly 'aria-label'?: string;
+    /** Extra class on the Popover wrapper. */
+    readonly className?: string;
+}
+export declare function Menu({ open, onOpenChange, trigger, children, align, 'aria-label': ariaLabel, className, }: MenuProps): ReactElement;

package/dist/overlays/Menu.js

@@ -0,0 +1,32 @@
+import { jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef } from 'react';
+import { useGooPill } from '../useGooPill.js';
+import { useMenu } from '../useMenu.js';
+import { Popover } from './Popover.js';
+export function Menu({ open, onOpenChange, trigger, children, align = 'start', 'aria-label': ariaLabel, className, }) {
+    const panelRef = useRef(null);
+    // The travelling highlight is a primitive (`useGooPill` + `goo.css`), not a menu feature: a menu is
+    // simply the first list that needed it, and the sidebar, a command palette or a product's own
+    // hand-rolled dropdown all want the same behaviour off the same two measurements.
+    const { hostProps: gooProps, pill } = useGooPill({ hostRef: panelRef });
+    /* Every key and every focus move now comes from `useMenu`. This component was where that behaviour
+       was written, and it stayed here long enough for a product to need it and not be able to reach it —
+       the same story `Modal` had before `useDialog`. The hook is handed the panel ref this component
+       already owns, so the keyboard, the highlight and Popover's placement all address one element. */
+    const { menuProps: keyboard } = useMenu({
+        open,
+        onClose: () => onOpenChange?.(false),
+        menuRef: panelRef,
+    });
+    // `ref` is Popover's to place (`panelRef`), so the hook's copy of it is dropped here rather than
+    // spread — the hook was handed that same ref, so both halves are looking at one element.
+    const { ref: _gooRef, className: gooClass, ...gooHandlers } = gooProps;
+    const { ref: _menuRef, ...keyboardProps } = keyboard;
+    const panelProps = {
+        className: `xeno-menu ${gooClass}`,
+        ...keyboardProps,
+        ...(ariaLabel !== undefined ? { 'aria-label': ariaLabel } : {}),
+        ...gooHandlers,
+    };
+    return (_jsxs(Popover, { open: open, ...(onOpenChange ? { onOpenChange } : {}), trigger: trigger, align: align, panelRef: panelRef, panelProps: panelProps, ...(className !== undefined ? { className } : {}), children: [pill, children] }));
+}

package/dist/overlays/MenuItem.d.ts

@@ -0,0 +1,71 @@
+import type { ButtonHTMLAttributes, ReactElement } from 'react';
+import type { ElementDeclaration, ElementState } from '@xenosystem/elements/schema';
+/**
+ * `<MenuItem>` — a single `role="menuitem"` row inside a {@link Menu}. Grammar-consistent with the
+ * controls: it honours the `availability` axis (`data-availability`, `disabled`) and — when it is a
+ * selectable (checkable) item — the `selection` axis (`data-selection` + `aria-checked`).
+ *
+ * A row reads left→right as: an optional leading glyph (or the selection check), the label
+ * (`children`), an optional right-aligned `value`, an optional right-aligned mono `shortcut`, and a
+ * trailing chevron when the row leads somewhere (`submenu` beside, `expanded` below). `variant`
+ * `danger` recolours the row to `--xeno-danger`. When `selected` is passed the item becomes a
+ * `menuitemcheckbox` and shows a check glyph; the leading slot is reserved so labels stay aligned with
+ * checked siblings.
+ */
+export type MenuItemVariant = 'default' | 'danger';
+export interface MenuItemProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onSelect'> {
+    /** Fired on click / Enter / Space (unless the click was defaultPrevented). */
+    readonly onSelect?: () => void;
+    /** A glyph before the label — imported per-id from `@xenosystem/elements`. */
+    readonly leadingIcon?: ElementDeclaration;
+    /** A right-aligned keyboard hint, rendered in muted mono (e.g. `⌘C`). */
+    readonly shortcut?: string;
+    /**
+     * The row's CURRENT VALUE, right-aligned and muted — for a row that opens a submenu of choices and
+     * wants to show which one is in force ("Type · All ›").
+     *
+     * Not `shortcut`, though the slot looks the same. `shortcut` is set in mono because it stands for
+     * a key the reader will press; a value is a word the reader picked, and mono makes a word read as
+     * a key. Products that only had `shortcut` used it for values anyway and got "All" in the same
+     * typeface as "⌘C" — this is the slot that was missing, not a second way to write the first.
+     */
+    readonly value?: string;
+    /** When defined the row is a checkable `menuitemcheckbox`; `true` shows the check glyph. */
+    readonly selected?: boolean;
+    /** Marks the row as opening a submenu — draws a trailing chevron and sets `aria-haspopup`. */
+    readonly submenu?: boolean;
+    /**
+     * Marks the row as a DISCLOSURE: it opens a region inside the menu rather than a menu beside it.
+     * Draws the same trailing chevron, quarter-turned when open, and reports `aria-expanded`.
+     *
+     * Not `submenu`, and the two must not be confused. `submenu` promises a second menu somewhere
+     * else on screen and says `aria-haspopup="menu"`; a disclosure grows the menu it is already in,
+     * and a screen reader told to expect a popup that never arrives is worse off than one told
+     * nothing. The chevron is shared because the gesture is: "there is more behind this row." Where
+     * it points is the difference — sideways for a menu beside, downwards for a panel below.
+     *
+     * Pass `aria-controls` alongside it; this component does not invent the region's id.
+     */
+    readonly expanded?: boolean;
+    /** `danger` recolours the row to `--xeno-danger`. */
+    readonly variant?: MenuItemVariant;
+    /**
+     * The leading glyph's own STATE, for a glyph that has one.
+     *
+     * `leadingIcon` is a declaration and this component draws it, which left a caller no way to say
+     * "that glyph, but on". Products fake it: a chat marking a pinned conversation put `fill-current`
+     * on an icon it rendered itself, because it could not reach the row's glyph from outside.
+     *
+     * It never needed faking. `bookmark` already declares a `selection` axis whose `on` variant is the
+     * same silhouette FILLED — the real thing, and one that MORPHS between the two rather than swapping,
+     * because both variants are a single path of equal length. This prop is the door to it.
+     *
+     * Distinct from `selected`, and the difference is what the row MEANS. `selected` says the row is a
+     * checkable option and this is the chosen one, so the component draws a check in the leading slot.
+     * `iconState` says nothing about choosing — it is the state of the thing the row acts on. A pinned
+     * chat is not a selected menu item, and a menu that conflated the two would draw a tick where the
+     * pin should be.
+     */
+    readonly iconState?: Partial<ElementState>;
+}
+export declare function MenuItem({ onSelect, leadingIcon, shortcut, value, selected, submenu, expanded, variant, iconState, disabled, className, children, onClick, type, ...rest }: MenuItemProps): ReactElement;

package/dist/overlays/MenuItem.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { XenoElement } from '../XenoElement.js';
+import { cx } from '../controls/util.js';
+import Check from '@xenosystem/elements/elements/check';
+import ChevronRight from '@xenosystem/elements/elements/chevron-right';
+export function MenuItem({ onSelect, leadingIcon, shortcut, value, selected, submenu = false, expanded, variant = 'default', iconState, disabled = false, className, children, onClick, type = 'button', ...rest }) {
+    const selectable = selected !== undefined;
+    const showLead = selectable || leadingIcon !== undefined;
+    const leadGlyph = selected ? Check : leadingIcon;
+    return (_jsxs("button", { type: type, role: selectable ? 'menuitemcheckbox' : 'menuitem', tabIndex: -1, className: cx('xeno-menu-item', className), "data-variant": variant, "data-availability": disabled ? 'disabled' : 'enabled', "data-selection": selectable ? (selected ? 'on' : 'off') : undefined, disabled: disabled, "aria-checked": selectable ? selected : undefined, "aria-haspopup": submenu ? 'menu' : undefined, "aria-expanded": expanded, onClick: (e) => {
+            onClick?.(e);
+            if (!e.defaultPrevented)
+                onSelect?.();
+        }, ...rest, children: [showLead && (_jsx("span", { className: "xeno-menu-item-lead", "aria-hidden": "true", children: leadGlyph ? _jsx(XenoElement, { decl: leadGlyph, size: 16, ...(iconState && !selected ? { state: iconState } : {}) }) : null })), _jsx("span", { className: "xeno-menu-item-label", children: children }), value !== undefined && _jsx("span", { className: "xeno-menu-item-value", children: value }), shortcut !== undefined && _jsx("span", { className: "xeno-menu-item-shortcut", children: shortcut }), (submenu || expanded !== undefined) && (_jsx("span", { className: "xeno-menu-item-chevron", "data-state": expanded === undefined ? undefined : expanded ? 'open' : 'closed', "aria-hidden": "true", children: _jsx(XenoElement, { decl: ChevronRight, size: 16 }) }))] }));
+}

package/dist/overlays/Modal.d.ts

@@ -0,0 +1,36 @@
+import type { HTMLAttributes, ReactElement, ReactNode } from 'react';
+/**
+ * `<Modal>` — the locked "floating window" (SPEC: dialog, not heavy chrome). One overlay pattern with
+ * two placements via the `variant` axis: a `center` dialog and a `sheet` that slides up from the bottom
+ * edge (rounding only its top corners). The card is `--xeno-elevated`, a 1px hairline border, a soft
+ * (uncoloured) shadow, and `--xeno-radius-md` throughout — a header (title + a close `IconButton` drawn
+ * from the `x` glyph), a scrollable body, and an optional right-aligned footer for actions.
+ *
+ * Controlled: `open` + `onClose`. It renders nothing when closed. While open it is `aria-modal` — Esc
+ * closes it, a click on the scrim (never on the card) closes it, focus moves into the dialog and is
+ * trapped on Tab, the page scroll is locked, and focus is restored to the opener on close.
+ */
+export type ModalVariant = 'center' | 'sheet';
+export interface ModalProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title' | 'children' | 'onClick'> {
+    /** Whether the dialog is mounted + visible. Nothing renders when false. */
+    readonly open: boolean;
+    /** Called on Esc, on a scrim click, and by the header close button. */
+    readonly onClose: () => void;
+    /** Header heading. When present it labels the dialog via `aria-labelledby`. */
+    readonly title?: ReactNode;
+    /** The scrollable body content. */
+    readonly children?: ReactNode;
+    /** Optional actions, laid out right-aligned in a bordered footer. */
+    readonly footer?: ReactNode;
+    /** `center` (default) floats mid-screen; `sheet` slides up from the bottom. */
+    readonly variant?: ModalVariant;
+    /** Accessible label for the close button. */
+    readonly closeLabel?: string;
+}
+export declare function Modal({ open, onClose, title, children, footer, variant, closeLabel, className, ...rest }: ModalProps): ReactElement | null;
+/**
+ * `<Sheet>` — the bottom-sheet placement of {@link Modal}, i.e. `Modal` pinned to `variant="sheet"`.
+ * Same controlled contract, same a11y; it slides up from the bottom and rounds only its top corners.
+ */
+export type SheetProps = Omit<ModalProps, 'variant'>;
+export declare function Sheet(props: SheetProps): ReactElement | null;

package/dist/overlays/Modal.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, useRef } from 'react';
+import { useDialog } from '../useDialog.js';
+import { IconButton } from '../controls/IconButton.js';
+import { cx } from '../controls/util.js';
+import X from '@xenosystem/elements/elements/x';
+export function Modal({ open, onClose, title, children, footer, variant = 'center', closeLabel = 'Close', className, ...rest }) {
+    const titleId = useId();
+    const scrimArmed = useRef(false);
+    const { panelProps } = useDialog({ open, onClose });
+    if (!open)
+        return null;
+    // Close only when both the press and the release land on the scrim itself — a drag that begins on the
+    // card and releases outside must not dismiss.
+    const onScrimMouseDown = (e) => {
+        scrimArmed.current = e.target === e.currentTarget;
+    };
+    const onScrimClick = (e) => {
+        if (e.target === e.currentTarget && scrimArmed.current)
+            onClose();
+        scrimArmed.current = false;
+    };
+    return (_jsx("div", { className: "xeno-modal-overlay", "data-variant": variant, onMouseDown: onScrimMouseDown, onClick: onScrimClick, children: _jsxs("div", { ...rest, ...panelProps, role: "dialog", "aria-modal": "true", ...(title !== undefined ? { 'aria-labelledby': titleId } : {}), className: cx('xeno-modal', className), "data-variant": variant, children: [_jsxs("div", { className: "xeno-modal-header", children: [title !== undefined ? (_jsx("h2", { id: titleId, className: "xeno-modal-title", children: title })) : null, _jsx(IconButton, { icon: X, "aria-label": closeLabel, className: "xeno-modal-close", onClick: onClose })] }), _jsx("div", { className: "xeno-modal-body", children: children }), footer !== undefined ? _jsx("div", { className: "xeno-modal-footer", children: footer }) : null] }) }));
+}
+export function Sheet(props) {
+    return _jsx(Modal, { ...props, variant: "sheet" });
+}

package/dist/overlays/PickerField.d.ts

@@ -0,0 +1,32 @@
+import type { HTMLAttributes, ReactElement, ReactNode } from 'react';
+import type { ElementDeclaration } from '@xenosystem/elements/schema';
+/**
+ * `<PickerField>` — a form field that REVEALS a panel (a {@link DatePicker}, {@link TimePicker}, or any
+ * content) with the chat's "Scheduled" open/close animation, via {@link Reveal}: the panel unfolds
+ * in-flow (pushing content down, never floating over it), full-width, its content fading up a beat
+ * later. The trigger shows a `label`, the current `value` (or `placeholder`), and a chevron that turns
+ * as it opens. Controlled (`open` + `onOpenChange`) or uncontrolled (`defaultOpen`); Esc and an outside
+ * click dismiss it.
+ *
+ * For several fields that should share ONE reveal (so switching between them never dips the layout),
+ * compose your own triggers with a single {@link Reveal} instead — see the preview's date/time pair.
+ */
+export interface PickerFieldProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'onChange'> {
+    /** The value shown in the field (e.g. a formatted date). Falls back to `placeholder` when empty. */
+    readonly value?: ReactNode;
+    /** Shown, muted, when `value` is empty. */
+    readonly placeholder?: string;
+    /** A small caption before the value (e.g. "Date"). */
+    readonly label?: string;
+    /** A leading glyph, drawn by the shared renderer. */
+    readonly icon?: ElementDeclaration;
+    /** Controlled open state. Omit to use `defaultOpen`. */
+    readonly open?: boolean;
+    readonly defaultOpen?: boolean;
+    readonly onOpenChange?: (open: boolean) => void;
+    /** Which field edge the panel aligns to. Default `start`. */
+    readonly align?: 'start' | 'end';
+    /** The revealed content — a picker, a menu, anything. */
+    readonly children?: ReactNode;
+}
+export declare function PickerField({ value, placeholder, label, icon, open: openProp, defaultOpen, onOpenChange, align, className, children, ...rest }: PickerFieldProps): ReactElement;

package/dist/overlays/PickerField.js

@@ -0,0 +1,40 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useRef, useState } from 'react';
+import { XenoElement } from '../XenoElement.js';
+import { cx } from '../controls/util.js';
+import ChevronRight from '@xenosystem/elements/elements/chevron-right';
+import { Reveal } from './Reveal.js';
+export function PickerField({ value, placeholder, label, icon, open: openProp, defaultOpen = false, onOpenChange, align = 'start', className, children, ...rest }) {
+    const controlled = openProp !== undefined;
+    const [openState, setOpenState] = useState(defaultOpen);
+    const open = controlled ? openProp : openState;
+    const rootRef = useRef(null);
+    const panelId = useId();
+    const setOpen = (next) => {
+        onOpenChange?.(next);
+        if (!controlled)
+            setOpenState(next);
+    };
+    // Dismiss on Escape / outside click, only while open.
+    useEffect(() => {
+        if (!open)
+            return;
+        const onKey = (e) => {
+            if (e.key === 'Escape')
+                setOpen(false);
+        };
+        const onPointer = (e) => {
+            if (rootRef.current && !rootRef.current.contains(e.target))
+                setOpen(false);
+        };
+        document.addEventListener('keydown', onKey);
+        document.addEventListener('mousedown', onPointer);
+        return () => {
+            document.removeEventListener('keydown', onKey);
+            document.removeEventListener('mousedown', onPointer);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [open]);
+    const empty = value === undefined || value === null || value === '';
+    return (_jsxs("div", { ref: rootRef, className: cx('xeno-field', className), "data-align": align, ...rest, children: [_jsxs("button", { type: "button", className: "xeno-field-trigger", "data-open": open ? 'true' : 'false', "aria-haspopup": "dialog", "aria-expanded": open, "aria-controls": open ? panelId : undefined, onClick: () => setOpen(!open), children: [icon && (_jsx("span", { className: "xeno-field-icon", "aria-hidden": "true", children: _jsx(XenoElement, { decl: icon, size: 16 }) })), label && _jsx("span", { className: "xeno-field-label", children: label }), _jsx("span", { className: "xeno-field-value", "data-placeholder": empty ? 'true' : 'false', children: empty ? placeholder : value }), _jsx("span", { className: "xeno-field-chevron", "aria-hidden": "true", children: _jsx(XenoElement, { decl: ChevronRight, size: 14 }) })] }), _jsx(Reveal, { open: open, align: align, panelProps: { id: panelId, role: 'dialog', 'aria-modal': false }, children: children })] }));
+}

package/dist/overlays/PillFilter.d.ts

@@ -0,0 +1,25 @@
+import { type HTMLAttributes, type ReactElement } from 'react';
+import { type ControlSizeToken } from '../controls/util.js';
+/**
+ * `<PillFilter>` — a wrapping row of small toggle pills (rounded squares, `radius-md`) for
+ * multi-select. Each pill is its own on/off toggle on the selection axis (`aria-pressed` +
+ * `data-selection`); the whole row is a `role="group"`. A selected pill fills to
+ * `var(--xeno-control)` with a `var(--xeno-muted)` hairline; an optional `count` renders as a small
+ * inset badge.
+ *
+ * Controlled: `value` is the array of selected option values and `onValueChange` receives the next
+ * array on every toggle. A disabled option rides the availability axis and cannot be toggled.
+ */
+export interface PillOption {
+    readonly value: string;
+    readonly label: string;
+    readonly count?: number;
+    readonly disabled?: boolean;
+}
+export interface PillFilterProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'children'> {
+    readonly value: readonly string[];
+    readonly onValueChange?: (value: string[]) => void;
+    readonly options: readonly PillOption[];
+    readonly size?: ControlSizeToken;
+}
+export declare function PillFilter({ value, onValueChange, options, size, className, ...rest }: PillFilterProps): ReactElement;

package/dist/overlays/PillFilter.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { sizeAttr, cx } from '../controls/util.js';
+export function PillFilter({ value, onValueChange, options, size = 'sm', className, ...rest }) {
+    const toggle = (v) => {
+        const next = value.includes(v) ? value.filter((x) => x !== v) : [...value, v];
+        onValueChange?.(next);
+    };
+    /**
+     * The fill pours in on a keyframe, so a row rendered with pills already selected would pour every one
+     * of them on page load. Arming has to be PER PILL, not per row: arming the whole row on the first
+     * click would make every already-selected pill flood at that moment too, which is the same bug one
+     * interaction later. A pill joins the set the first time its own selection actually flips, and stays.
+     *
+     * The comparison is on a sorted key, not on the array's identity — a parent that rebuilds `value` on
+     * every render would otherwise look like a change every time, and setting state during render on
+     * every render does not terminate.
+     */
+    const key = [...value].sort().join('\u0000');
+    const [seen, setSeen] = useState({ key, list: value });
+    const [armed, setArmed] = useState(() => new Set());
+    if (seen.key !== key) {
+        const before = new Set(seen.list);
+        const after = new Set(value);
+        const flipped = [...new Set([...seen.list, ...value])].filter((v) => before.has(v) !== after.has(v));
+        if (flipped.length > 0) {
+            setArmed((prev) => {
+                const next = new Set(prev);
+                for (const v of flipped)
+                    next.add(v);
+                return next;
+            });
+        }
+        setSeen({ key, list: value });
+    }
+    return (_jsx("div", { role: "group", className: cx('xeno-pillfilter', className), ...sizeAttr(size), ...rest, children: options.map((o) => {
+            const selected = value.includes(o.value);
+            const disabled = o.disabled ?? false;
+            return (_jsxs("button", { type: "button", className: "xeno-pill", "data-selection": selected ? 'on' : 'off', "data-availability": disabled ? 'disabled' : 'enabled', ...(armed.has(o.value) ? { 'data-motion': 'ready' } : {}), "aria-pressed": selected, disabled: disabled, onClick: () => toggle(o.value), children: [_jsx("span", { className: "xeno-pill-label", children: o.label }), o.count !== undefined && (_jsx("span", { className: "xeno-pill-count", "aria-hidden": "true", children: o.count }))] }, o.value));
+        }) }));
+}

package/dist/overlays/Popover.d.ts

@@ -0,0 +1,32 @@
+import type { HTMLAttributes, ReactElement, ReactNode, Ref } from 'react';
+/**
+ * `<Popover>` — a hand-rolled anchored overlay (no portal lib, SPEC §13). A `position:relative` wrapper
+ * holds the `trigger`; while `open`, an absolutely-positioned panel (`--xeno-elevated`, a hairline
+ * border, one soft uncoloured shadow, `--xeno-radius-md`) is placed below the trigger, aligned to its
+ * `start` (default) or `end` edge. Nothing renders inside the panel until it is open.
+ *
+ * Controlled: `open` + `onOpenChange`. While open it wires two document listeners — a `mousedown`
+ * outside the wrapper closes it, and `Escape` closes it — both cleaned up on close/unmount. Focus is
+ * captured on open and restored to the opener on close.
+ *
+ * It is the composition seam for {@link Menu}: pass `panelProps` (spread onto the panel — `role`,
+ * `aria-*`, `onKeyDown`, `onClick`, …) and `panelRef` (attached to the panel node) to layer a menu, a
+ * listbox, or any anchored surface on top of the same anchoring + dismissal behaviour.
+ */
+export interface PopoverProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /** Whether the panel is mounted + visible. Nothing renders in the panel when false. */
+    readonly open: boolean;
+    /** Called with `false` on an outside click and on Escape. */
+    readonly onOpenChange?: (open: boolean) => void;
+    /** The anchor — wire its `onClick` to toggle `open` (this is a controlled overlay). */
+    readonly trigger: ReactNode;
+    /** The panel content. */
+    readonly children?: ReactNode;
+    /** Which trigger edge the panel aligns to. Default `start`. */
+    readonly align?: 'start' | 'end';
+    /** Attached to the panel node (composition seam — e.g. {@link Menu} queries its items). */
+    readonly panelRef?: Ref<HTMLDivElement>;
+    /** Spread onto the panel node — `role`, `aria-*`, `onKeyDown`, `onClick`, … (composition seam). */
+    readonly panelProps?: HTMLAttributes<HTMLDivElement>;
+}
+export declare function Popover({ open, onOpenChange, trigger, children, align, panelRef, panelProps, className, ...rest }: PopoverProps): ReactElement;

package/dist/overlays/Popover.js

@@ -0,0 +1,38 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef } from 'react';
+import { cx } from '../controls/util.js';
+export function Popover({ open, onOpenChange, trigger, children, align = 'start', panelRef, panelProps, className, ...rest }) {
+    const rootRef = useRef(null);
+    const restoreFocus = useRef(null);
+    // Dismissal — bound on the document only while open, so nothing is listening when closed.
+    useEffect(() => {
+        if (!open)
+            return;
+        const onPointer = (e) => {
+            if (rootRef.current && !rootRef.current.contains(e.target))
+                onOpenChange?.(false);
+        };
+        const onKey = (e) => {
+            if (e.key === 'Escape')
+                onOpenChange?.(false);
+        };
+        document.addEventListener('mousedown', onPointer);
+        document.addEventListener('keydown', onKey);
+        return () => {
+            document.removeEventListener('mousedown', onPointer);
+            document.removeEventListener('keydown', onKey);
+        };
+    }, [open, onOpenChange]);
+    // Capture the opener on open; restore focus to it on close.
+    useEffect(() => {
+        if (open) {
+            restoreFocus.current = document.activeElement;
+        }
+        else if (restoreFocus.current) {
+            restoreFocus.current.focus?.();
+            restoreFocus.current = null;
+        }
+    }, [open]);
+    const { className: panelClassName, ...restPanel } = panelProps ?? {};
+    return (_jsxs("div", { ref: rootRef, className: cx('xeno-popover', className), ...rest, children: [trigger, open && (_jsx("div", { ref: panelRef, className: cx('xeno-popover-panel', panelClassName), "data-align": align, ...restPanel, children: children }))] }));
+}

package/dist/overlays/Reveal.d.ts

@@ -0,0 +1,20 @@
+import type { HTMLAttributes, ReactElement, ReactNode } from 'react';
+/**
+ * `<Reveal>` — an IN-FLOW animated disclosure (the XENO chat's "Scheduled" reveal, generalised). When
+ * `open`, an in-flow region animates its height (measured from the content) so surrounding content is
+ * pushed DOWN — never floated over — while the content itself is clipped panel-WIDTH so a wide child
+ * (e.g. a calendar) shows full width and only unfolds VERTICALLY, its content fading up a beat later.
+ *
+ * Because the region's height tracks the CONTENT, one shared `<Reveal>` swapped between two same-height
+ * panels keeps a constant height — so switching panels never dips the layout. Hand-rolled, no portal
+ * lib (SPEC §13). Returns nothing while closed + fully exited.
+ */
+export interface RevealProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    readonly open: boolean;
+    /** Which edge the clipped panel aligns to. Default `start`. */
+    readonly align?: 'start' | 'end';
+    readonly children?: ReactNode;
+    /** Spread onto the panel node — `id`, `role`, `aria-*` (composition seam for {@link PickerField}). */
+    readonly panelProps?: HTMLAttributes<HTMLDivElement>;
+}
+export declare function Reveal({ open, align, children, panelProps, className, ...rest }: RevealProps): ReactElement | null;

package/dist/overlays/Reveal.js

@@ -0,0 +1,45 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { cx } from '../controls/util.js';
+/** Match the CSS reveal/exit duration so the region is unmounted only after it has animated out. */
+const EXIT_MS = 240;
+// useLayoutEffect measures before paint on the client; fall back to useEffect on the server so SSR does
+// not warn. `typeof window` is constant per environment, so the hook choice is stable.
+const useIsoLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
+export function Reveal({ open, align = 'start', children, panelProps, className, ...rest }) {
+    const [mounted, setMounted] = useState(open);
+    const [shown, setShown] = useState(open);
+    const [clipped, setClipped] = useState(true);
+    const [height, setHeight] = useState(0);
+    const panelRef = useRef(null);
+    // The panel's natural height is what the region animates to. Re-measured when the content changes, so
+    // a swapped-in panel of a different height re-targets smoothly.
+    useIsoLayoutEffect(() => {
+        if (mounted && panelRef.current)
+            setHeight(panelRef.current.offsetHeight);
+    }, [mounted, children]);
+    useEffect(() => {
+        if (open) {
+            setMounted(true);
+            setClipped(true);
+            let raf2 = 0;
+            const raf1 = requestAnimationFrame(() => {
+                raf2 = requestAnimationFrame(() => setShown(true));
+            });
+            const unclip = setTimeout(() => setClipped(false), EXIT_MS + 30);
+            return () => {
+                cancelAnimationFrame(raf1);
+                cancelAnimationFrame(raf2);
+                clearTimeout(unclip);
+            };
+        }
+        setShown(false);
+        setClipped(true);
+        const t = setTimeout(() => setMounted(false), EXIT_MS);
+        return () => clearTimeout(t);
+    }, [open]);
+    if (!mounted)
+        return null;
+    const { className: panelClassName, ...restPanel } = panelProps ?? {};
+    return (_jsx("div", { className: cx('xeno-reveal', className), "data-open": shown ? 'true' : 'false', style: { height: shown ? height : 0 }, ...rest, children: _jsx("div", { className: "xeno-reveal-clip", "data-clip": clipped ? 'true' : 'false', "data-align": align, children: _jsx("div", { className: cx('xeno-reveal-panel', panelClassName), ref: panelRef, ...restPanel, children: _jsx("div", { className: "xeno-reveal-content", children: children }) }) }) }));
+}

package/dist/overlays/SegmentedControl.d.ts

@@ -0,0 +1,23 @@
+import { type HTMLAttributes, type ReactElement } from 'react';
+import { type ControlSizeToken } from '../controls/util.js';
+/**
+ * `<SegmentedControl>` — a single-select of connected options inside one bordered track (a rounded
+ * square, `radius-md`). The chosen option floats on an inset `var(--xeno-control)` fill; the rest are
+ * transparent `var(--xeno-muted)` labels. Semantics are a `role="group"` of `aria-pressed` buttons
+ * (the selection axis), so exactly one option reads as pressed.
+ *
+ * Controlled: the caller owns `value`/`onValueChange`. Clicking the already-selected option is a no-op
+ * (a segmented control always keeps one option chosen). A disabled option rides the availability axis.
+ */
+export interface SegmentedOption {
+    readonly value: string;
+    readonly label: string;
+    readonly disabled?: boolean;
+}
+export interface SegmentedControlProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
+    readonly value: string;
+    readonly onValueChange?: (value: string) => void;
+    readonly options: readonly SegmentedOption[];
+    readonly size?: ControlSizeToken;
+}
+export declare function SegmentedControl({ value, onValueChange, options, size, className, ...rest }: SegmentedControlProps): ReactElement;

package/dist/overlays/SegmentedControl.js

@@ -0,0 +1,43 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { sizeAttr, cx } from '../controls/util.js';
+export function SegmentedControl({ value, onValueChange, options, size = 'md', className, ...rest }) {
+    /**
+     * The two numbers the stylesheet cannot work out for itself — how many segments there are, and which
+     * one is chosen. They are DATA, not animation: CSS derives the thumb's width and offset from them and
+     * owns every frame. An index of -1 (a `value` matching no option) parks the thumb and hides it.
+     */
+    const index = options.findIndex((o) => o.value === value);
+    /* The squash is a keyframe, and a keyframe plays the moment its rule matches — so a control that
+       mounts with a selection would squash on page load. Arm on the first genuine change of `value`. */
+    const [armed, setArmed] = useState(false);
+    const [seen, setSeen] = useState(value);
+    /**
+     * How far the thumb is about to travel, in segments. The goo stretches in proportion to it, so a jump
+     * from one end to the other reaches further than a step to the neighbour. Capped at 2: past that the
+     * stretch stops adding anything and starts looking like a smear.
+     */
+    const [distance, setDistance] = useState(1);
+    if (seen !== value) {
+        const from = options.findIndex((o) => o.value === seen);
+        if (from >= 0 && index >= 0)
+            setDistance(Math.min(2, Math.abs(index - from)));
+        setSeen(value);
+        if (!armed)
+            setArmed(true);
+    }
+    // Only the per-instance numbers stay inline; the size metrics moved to `data-xeno-size`.
+    const trackVars = {
+        '--xeno-seg-count': options.length,
+        '--xeno-seg-index': Math.max(0, index),
+        '--xeno-seg-dist': distance,
+    };
+    return (_jsxs("div", { role: "group", className: cx('xeno-segmented', className), "data-selection": index >= 0 ? 'on' : 'off', "data-index": index >= 0 ? index : undefined, ...(armed ? { 'data-motion': 'ready' } : {}), ...sizeAttr(size), style: trackVars, ...rest, children: [_jsx("span", { className: "xeno-segmented-thumb", "aria-hidden": "true" }), options.map((o) => {
+                const selected = o.value === value;
+                const disabled = o.disabled ?? false;
+                return (_jsx("button", { type: "button", className: "xeno-segmented-option", "data-selection": selected ? 'on' : 'off', "data-availability": disabled ? 'disabled' : 'enabled', "aria-pressed": selected, disabled: disabled, onClick: () => {
+                        if (!selected)
+                            onValueChange?.(o.value);
+                    }, children: o.label }, o.value));
+            })] }));
+}

package/dist/overlays/Tabs.d.ts

@@ -0,0 +1,32 @@
+import type { HTMLAttributes, ReactElement, ReactNode } from 'react';
+import type { ElementDeclaration } from '@xenosystem/elements/schema';
+import { type ControlSizeToken } from '../controls/util.js';
+/**
+ * `<Tabs>` — a horizontal tablist that follows the WAI-ARIA tabs pattern: `role="tablist"` wrapping
+ * `role="tab"` buttons with a roving tabIndex (only the selected tab is in the tab order) and
+ * Arrow/Home/End keys that move focus *and* selection (automatic activation). The selected tab reads
+ * as `var(--xeno-text)` with a hairline underline; the rest sit at `var(--xeno-muted)`.
+ *
+ * Controlled: the caller owns `value`/`onValueChange`. An optional panel is drawn either from a
+ * `renderPanel(value)` callback or from `children`; when present it is a `role="tabpanel"` labelled by
+ * the selected tab. A disabled item rides the availability axis (`aria-disabled` + `data-availability`)
+ * and is skipped by keyboard traversal — never made unfocusable-then-orphaned.
+ */
+export interface TabItem {
+    readonly value: string;
+    readonly label: string;
+    /** A glyph before the label — imported per-id from `@xenosystem/elements`. */
+    readonly icon?: ElementDeclaration;
+    readonly disabled?: boolean;
+}
+export interface TabsProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'children'> {
+    readonly value: string;
+    readonly onValueChange?: (value: string) => void;
+    readonly items: readonly TabItem[];
+    readonly size?: ControlSizeToken;
+    /** Draw the panel for the active tab. Wins over `children` when both are given. */
+    readonly renderPanel?: (value: string) => ReactNode;
+    /** Panel content for the active tab (used when `renderPanel` is absent). */
+    readonly children?: ReactNode;
+}
+export declare function Tabs({ value, onValueChange, items, size, renderPanel, children, className, 'aria-label': ariaLabel, ...rest }: TabsProps): ReactElement;