@xenosystem/elements-react 0.0.1

package/dist/index.js

@@ -0,0 +1,81 @@
+/**
+ * `@xenosystem/elements-react` — the XENO web renderer (React + SVG).
+ *
+ * - {@link XenoElement} renders any element DECLARATION (icons + stateful glyphs) from data.
+ * - Tier-1 CONTROLS (Button, IconButton, ToggleButton, Switch, TextInput, Textarea) are the first
+ *   non-icon elements — styled from the design tokens, CSS-first, behaviour hand-rolled (Base UI later).
+ * - Tier-2 ELEMENTS (containers, overlays, forms, content, nav, layout, status) compose the controls
+ *   and the renderer into the surfaces a chat/agent product needs.
+ *
+ * Import the styles once:
+ *   `@xenosystem/elements-react/xeno-elements.css`  (theme tokens + element + control + every element style)
+ * or à la carte:
+ *   `@xenosystem/elements-react/xeno-theme.css`  (tokens as CSS vars; scope with a `.xeno` element)
+ *   `@xenosystem/elements-react/controls.css`    (control styles)
+ *
+ * Glyphs are DATA: import each per-id from `@xenosystem/elements/elements/<id>`. No barrel.
+ *
+ * @module
+ */
+export { XenoElement } from './XenoElement.js';
+export { useDialog } from './useDialog.js';
+export { useTabs } from './useTabs.js';
+export { useMenu } from './useMenu.js';
+export { useGooPill, } from './useGooPill.js';
+// ── Tier-1 controls ─────────────────────────────────────────────────────────────────────────────
+export { Button } from './controls/Button.js';
+export { IconButton } from './controls/IconButton.js';
+export { ConfirmButton } from './controls/ConfirmButton.js';
+export { ToggleButton } from './controls/ToggleButton.js';
+export { Switch } from './controls/Switch.js';
+export { TextInput } from './controls/TextInput.js';
+export { Textarea } from './controls/Textarea.js';
+// ── Containers ──────────────────────────────────────────────────────────────────────────────────
+export { Card } from './containers/Card.js';
+export { Panel } from './containers/Panel.js';
+export { Chip } from './containers/Chip.js';
+export { Tile } from './containers/Tile.js';
+export { MessageBubble } from './containers/MessageBubble.js';
+export { Badge } from './containers/Badges.js';
+export { StatusPill } from './containers/Badges.js';
+export { CountBadge } from './containers/Badges.js';
+export { CitationBadge } from './containers/Badges.js';
+export { Avatar } from './containers/Avatar.js';
+export { AvatarStack } from './containers/Avatar.js';
+export { ListRow } from './containers/ListRow.js';
+export { Table, THead, TBody, Tr, Th, Td, } from './containers/Table.js';
+export { DataTable } from './containers/DataTable.js';
+// ── Overlays ────────────────────────────────────────────────────────────────────────────────────
+export { Popover } from './overlays/Popover.js';
+export { Menu } from './overlays/Menu.js';
+export { MenuItem } from './overlays/MenuItem.js';
+export { Modal, Sheet } from './overlays/Modal.js';
+export { Tabs } from './overlays/Tabs.js';
+export { SegmentedControl } from './overlays/SegmentedControl.js';
+export { PillFilter } from './overlays/PillFilter.js';
+export { Tooltip } from './overlays/Tooltip.js';
+export { PickerField } from './overlays/PickerField.js';
+export { Reveal } from './overlays/Reveal.js';
+export { DatePicker, TimePicker } from './overlays/DateTimePicker.js';
+// ── Forms ───────────────────────────────────────────────────────────────────────────────────────
+export { Checkbox } from './forms/Checkbox.js';
+export { RadioGroup, RadioRow } from './forms/RadioGroup.js';
+// ── Content ─────────────────────────────────────────────────────────────────────────────────────
+export { CodeBlock, } from './content/CodeBlock.js';
+export { SourceCard } from './content/SourceCard.js';
+export { SourcesDisclosure } from './content/SourcesDisclosure.js';
+export { ModelPicker } from './content/ModelPicker.js';
+export { InlineCode } from './content/InlineCode.js';
+export { Callout } from './content/Callout.js';
+export { Collapsible } from './content/Collapsible.js';
+export { Caret } from './content/Caret.js';
+// ── Nav ─────────────────────────────────────────────────────────────────────────────────────────
+export { Sidebar } from './nav/Sidebar.js';
+// ── Layout ──────────────────────────────────────────────────────────────────────────────────────
+export { ResizablePanel } from './layout/ResizablePanel.js';
+// ── Status ──────────────────────────────────────────────────────────────────────────────────────
+export { ThinkingCube } from './status/ThinkingCube.js';
+export { Spinner } from './status/Spinner.js';
+export { ProgressBar } from './status/ProgressBar.js';
+export { StepTimeline } from './status/StepTimeline.js';
+export { StatusIndicator } from './status/StatusIndicator.js';

package/dist/layout/ResizablePanel.d.ts

@@ -0,0 +1,40 @@
+import type { HTMLAttributes, ReactElement, ReactNode } from 'react';
+/** Which edge the drag handle rides on (and therefore which direction grows the panel). */
+export type ResizablePanelSide = 'left' | 'right';
+export interface ResizablePanelProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'onChange'> {
+    /** Edge the handle sits on. `right` grows rightward; `left` grows leftward. Default `right`. */
+    readonly side?: ResizablePanelSide;
+    /** Starting width (px) when uncontrolled. Default `280`. */
+    readonly defaultSize?: number;
+    /** Smallest allowed width (px). Default `160`. */
+    readonly min?: number;
+    /** Largest allowed width (px). Default `480`. */
+    readonly max?: number;
+    /** Controlled width (px). When set, the component defers to `onSizeChange` for updates. */
+    readonly size?: number;
+    /** Fires with the next clamped width (px) on drag or keyboard resize. */
+    readonly onSizeChange?: (size: number) => void;
+    /** Keyboard resize increment (px) for the arrow keys. Default `16`. */
+    readonly step?: number;
+    /** When true the handle is inert (no drag, no keyboard, disabled cursor). */
+    readonly disabled?: boolean;
+    /** Accessible name for the resize handle. Default `Resize panel`. */
+    readonly handleLabel?: string;
+    /** Panel contents. */
+    readonly children?: ReactNode;
+}
+/**
+ * `<ResizablePanel>` — a fixed-width panel with a draggable divider on one edge.
+ *
+ * The root is a flex row of the panel body (its `width` the only sized property) and a 4px handle
+ * (`cursor: col-resize`) pinned to `side`. A pointer press on the handle registers `window`
+ * `pointermove`/`pointerup` listeners (removed on release) and translates horizontal travel into width,
+ * clamped to `[min, max]`. `side='right'` grows rightward, `side='left'` grows leftward.
+ *
+ * Width is CONTROLLED when `size` is supplied (updates flow through `onSizeChange`), otherwise
+ * uncontrolled from `defaultSize`. The handle is a `role="separator"` with `aria-orientation="vertical"`
+ * and live `aria-valuenow/min/max`; it is keyboard-operable — ←/→ nudge by `step` in the drag direction,
+ * Home/End jump to `min`/`max`. Dragging is reflected as `data-dragging` on the root (drives the grab
+ * cursor + a text-selection lock); `disabled` flows to `data-availability`.
+ */
+export declare function ResizablePanel({ side, defaultSize, min, max, size, onSizeChange, step, disabled, handleLabel, children, className, ...rest }: ResizablePanelProps): ReactElement;

package/dist/layout/ResizablePanel.js

@@ -0,0 +1,108 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useId, useRef, useState } from 'react';
+import { cx } from '../controls/util.js';
+/** Keep a value inside `[lo, hi]` (tolerant of an inverted range). */
+function clamp(n, lo, hi) {
+    return Math.min(Math.max(n, lo), hi);
+}
+/**
+ * `<ResizablePanel>` — a fixed-width panel with a draggable divider on one edge.
+ *
+ * The root is a flex row of the panel body (its `width` the only sized property) and a 4px handle
+ * (`cursor: col-resize`) pinned to `side`. A pointer press on the handle registers `window`
+ * `pointermove`/`pointerup` listeners (removed on release) and translates horizontal travel into width,
+ * clamped to `[min, max]`. `side='right'` grows rightward, `side='left'` grows leftward.
+ *
+ * Width is CONTROLLED when `size` is supplied (updates flow through `onSizeChange`), otherwise
+ * uncontrolled from `defaultSize`. The handle is a `role="separator"` with `aria-orientation="vertical"`
+ * and live `aria-valuenow/min/max`; it is keyboard-operable — ←/→ nudge by `step` in the drag direction,
+ * Home/End jump to `min`/`max`. Dragging is reflected as `data-dragging` on the root (drives the grab
+ * cursor + a text-selection lock); `disabled` flows to `data-availability`.
+ */
+export function ResizablePanel({ side = 'right', defaultSize = 280, min = 160, max = 480, size, onSizeChange, step = 16, disabled = false, handleLabel = 'Resize panel', children, className, ...rest }) {
+    const isControlled = size !== undefined;
+    const [internalSize, setInternalSize] = useState(defaultSize);
+    const current = clamp(size ?? internalSize, min, max);
+    // `right` handle: rightward pointer travel widens; `left` handle: leftward travel widens.
+    const dirSign = side === 'right' ? 1 : -1;
+    const [dragging, setDragging] = useState(false);
+    const dragStart = useRef(null);
+    const moveRef = useRef(null);
+    const upRef = useRef(null);
+    const panelId = useId();
+    // Commit a proposed width: clamp, update internal state when uncontrolled, always notify.
+    const commit = (next) => {
+        const clamped = clamp(next, min, max);
+        if (!isControlled)
+            setInternalSize(clamped);
+        onSizeChange?.(clamped);
+    };
+    // Latest-commit ref so the long-lived pointermove listener never fires a stale closure.
+    const commitRef = useRef(commit);
+    useEffect(() => {
+        commitRef.current = commit;
+    });
+    /**
+     * Tear down any live drag listeners — shared by pointerup, POINTERCANCEL and unmount.
+     *
+     * `pointercancel` is not optional. The browser fires it instead of `pointerup` whenever it takes the
+     * pointer stream away — a touch turning into a scroll, a system gesture, the handle unmounting
+     * mid-drag. Listening only for `pointerup` meant that in those cases the teardown never ran: the
+     * `pointermove` listener stayed on `window`, `dragging` stayed true, and the panel went on resizing
+     * itself under a pointer with no button held until some unrelated pointerup happened to land.
+     */
+    const endDrag = useCallback(() => {
+        if (moveRef.current)
+            window.removeEventListener('pointermove', moveRef.current);
+        if (upRef.current) {
+            window.removeEventListener('pointerup', upRef.current);
+            window.removeEventListener('pointercancel', upRef.current);
+        }
+        moveRef.current = null;
+        upRef.current = null;
+        dragStart.current = null;
+        setDragging(false);
+    }, []);
+    useEffect(() => endDrag, [endDrag]);
+    const onPointerDown = (e) => {
+        if (disabled || e.button !== 0)
+            return;
+        e.preventDefault();
+        dragStart.current = { x: e.clientX, size: current };
+        setDragging(true);
+        const onMove = (ev) => {
+            const start = dragStart.current;
+            if (!start)
+                return;
+            const delta = (ev.clientX - start.x) * dirSign;
+            commitRef.current(start.size + delta);
+        };
+        const onUp = () => endDrag();
+        moveRef.current = onMove;
+        upRef.current = onUp;
+        window.addEventListener('pointermove', onMove);
+        window.addEventListener('pointerup', onUp);
+        window.addEventListener('pointercancel', onUp);
+    };
+    const onKeyDown = (e) => {
+        if (disabled)
+            return;
+        let next = null;
+        if (e.key === 'ArrowRight')
+            next = current + dirSign * step;
+        else if (e.key === 'ArrowLeft')
+            next = current - dirSign * step;
+        else if (e.key === 'Home')
+            next = min;
+        else if (e.key === 'End')
+            next = max;
+        if (next === null)
+            return;
+        e.preventDefault();
+        commit(next);
+    };
+    const availability = disabled ? 'disabled' : 'enabled';
+    const handle = (_jsx("div", { className: "xeno-resizable-handle", role: "separator", "aria-orientation": "vertical", "aria-label": handleLabel, "aria-controls": panelId, "aria-valuenow": Math.round(current), "aria-valuemin": min, "aria-valuemax": max, "aria-disabled": disabled || undefined, tabIndex: disabled ? -1 : 0, "data-availability": availability, onPointerDown: onPointerDown, onKeyDown: onKeyDown }));
+    return (_jsxs("div", { className: cx('xeno-resizable', className), "data-side": side, "data-dragging": dragging ? 'true' : 'false', "data-availability": availability, ...rest, children: [side === 'left' && handle, _jsx("div", { id: panelId, className: "xeno-resizable-panel", style: { width: `${current}px` }, children: children }), side === 'right' && handle] }));
+}

package/dist/nav/Sidebar.d.ts

@@ -0,0 +1,60 @@
+import type { HTMLAttributes, ReactElement, ReactNode } from 'react';
+import type { ElementDeclaration } from '@xenosystem/elements/schema';
+/** One navigable row: a leading glyph (optional) + a label, keyed by a stable id. */
+export interface SidebarItem {
+    readonly id: string;
+    readonly label: string;
+    /** A glyph before the label — imported per-id from `@xenosystem/elements`. */
+    readonly icon?: ElementDeclaration;
+}
+/** A titled group of rows — e.g. `Pinned` / `Recents`. The heading is mono muted. */
+export interface SidebarSection {
+    /** Section heading (mono muted). Omit for an untitled group. */
+    readonly heading?: string;
+    readonly items: readonly SidebarItem[];
+}
+export interface SidebarProps extends Omit<HTMLAttributes<HTMLElement>, 'onSelect' | 'children'> {
+    /** Controlled open/closed. Closed slides the panel to `translateX(-100%)`. */
+    readonly open: boolean;
+    /** Requests a state change — from Esc, or a backdrop tap on small screens. */
+    readonly onOpenChange?: (open: boolean) => void;
+    /** The primary (untitled) nav section. */
+    readonly items: readonly SidebarItem[];
+    /** Optional titled groups rendered after `items` — Pinned / Recents / … */
+    readonly sections?: readonly SidebarSection[];
+    /** The id of the active row (→ `var(--xeno-control)`, `aria-current="page"`). */
+    readonly activeId?: string;
+    /** A row was activated (click / Enter / Space). */
+    readonly onSelect?: (id: string) => void;
+    /** Brand shown top-left of the header. Defaults to the wordmark `XENO`. */
+    readonly brand?: ReactNode;
+    /** Show the header search field. Default `true`. */
+    readonly searchable?: boolean;
+    /** Controlled search text. Leave unset for an uncontrolled field. */
+    readonly searchValue?: string;
+    readonly onSearchChange?: (value: string) => void;
+    readonly searchPlaceholder?: string;
+    /** Override the search field glyph. Defaults to `xeno.search`. */
+    readonly searchIcon?: ElementDeclaration;
+    /** Pinned to the bottom — account row, version, sign-out, … */
+    readonly footer?: ReactNode;
+    /** Render a scrim behind the panel on small screens. Default `true`. */
+    readonly backdrop?: boolean;
+    /** Accessible name for the inner nav landmark. Default `Primary`. */
+    readonly navLabel?: string;
+}
+/**
+ * `<Sidebar>` — the slide-in left navigation panel.
+ *
+ * Locked geometry: SQUARE corners, flush to the viewport edge (`position: fixed; left: 0`), a fixed
+ * ~260px column on `var(--xeno-surface)`. It is CONTROLLED (`open` / `onOpenChange`) and opens by
+ * transforming `translateX(-100% → 0)` — the only animated property, guarded by reduced-motion.
+ *
+ * Structure: a header (brand + a search `TextInput` carrying the search glyph), a scrollable nav of
+ * self-contained rows (leading glyph + label; the active row fills with `var(--xeno-control)`), any
+ * number of titled `sections` (Pinned / Recents), and an optional pinned `footer`.
+ *
+ * Behaviour is hand-rolled: Esc closes; ↑/↓/Home/End rove focus across rows; a backdrop tap closes on
+ * small screens. When closed the panel is `inert` + `aria-hidden`, so it leaves the tab order.
+ */
+export declare function Sidebar({ open, onOpenChange, items, sections, activeId, onSelect, brand, searchable, searchValue, onSearchChange, searchPlaceholder, searchIcon, footer, backdrop, navLabel, className, onKeyDown, ...rest }: SidebarProps): ReactElement;

package/dist/nav/Sidebar.js

@@ -0,0 +1,84 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { version as reactVersion } from 'react';
+import { XenoElement } from '../XenoElement.js';
+import { TextInput } from '../controls/TextInput.js';
+import { cx } from '../controls/util.js';
+import Search from '@xenosystem/elements/elements/search';
+/** Glyph px for a nav row — sits a hair under the 20px switch knob so labels lead. */
+const ITEM_ICON = 18;
+/**
+ * `inert`, spelled so it survives BOTH React versions in the peer range.
+ *
+ * The two versions genuinely disagree, and each one DROPS the other's spelling:
+ *
+ *   React 18  does not know `inert`, so `true` is refused as a non-boolean attribute value and the
+ *             attribute never reaches the DOM. `''` renders as the custom attribute `inert=""`.
+ *   React 19  knows it as a boolean: `true` renders `inert=""`, while `''` is read as FALSE (it warns
+ *             "Received an empty string for a boolean attribute") and the attribute is dropped.
+ *
+ * There is no single value that works on both, so the value is chosen from the version actually
+ * loaded. Getting it wrong is silent and costly: a CLOSED panel keeps every nav button and the search
+ * field in the tab order, which is precisely what this is here to prevent.
+ *
+ * The cast exists only to satisfy React 19's typings, which narrow the prop to `boolean`.
+ */
+const INERT_VALUE = Number.parseInt(reactVersion, 10) >= 19 ? true : '';
+const inertWhen = (on) => on ? { inert: INERT_VALUE } : {};
+/**
+ * `<Sidebar>` — the slide-in left navigation panel.
+ *
+ * Locked geometry: SQUARE corners, flush to the viewport edge (`position: fixed; left: 0`), a fixed
+ * ~260px column on `var(--xeno-surface)`. It is CONTROLLED (`open` / `onOpenChange`) and opens by
+ * transforming `translateX(-100% → 0)` — the only animated property, guarded by reduced-motion.
+ *
+ * Structure: a header (brand + a search `TextInput` carrying the search glyph), a scrollable nav of
+ * self-contained rows (leading glyph + label; the active row fills with `var(--xeno-control)`), any
+ * number of titled `sections` (Pinned / Recents), and an optional pinned `footer`.
+ *
+ * Behaviour is hand-rolled: Esc closes; ↑/↓/Home/End rove focus across rows; a backdrop tap closes on
+ * small screens. When closed the panel is `inert` + `aria-hidden`, so it leaves the tab order.
+ */
+export function Sidebar({ open, onOpenChange, items, sections, activeId, onSelect, brand = 'XENO', searchable = true, searchValue, onSearchChange, searchPlaceholder = 'Search', searchIcon, footer, backdrop = true, navLabel = 'Primary', className, onKeyDown, ...rest }) {
+    const searchGlyph = searchIcon ?? Search;
+    const onRootKeyDown = (e) => {
+        onKeyDown?.(e);
+        if (!e.defaultPrevented && e.key === 'Escape') {
+            onOpenChange?.(false);
+        }
+    };
+    // Roving focus across the rows — arrows never leave the nav, Home/End jump to the ends.
+    const onNavKeyDown = (e) => {
+        if (e.key !== 'ArrowDown' && e.key !== 'ArrowUp' && e.key !== 'Home' && e.key !== 'End')
+            return;
+        const rows = Array.from(e.currentTarget.querySelectorAll('[data-sidebar-item]:not([disabled])'));
+        if (rows.length === 0)
+            return;
+        e.preventDefault();
+        const active = typeof document !== 'undefined' ? document.activeElement : null;
+        const idx = active instanceof HTMLButtonElement ? rows.indexOf(active) : -1;
+        let next = idx;
+        if (e.key === 'ArrowDown')
+            next = idx < 0 ? 0 : (idx + 1) % rows.length;
+        else if (e.key === 'ArrowUp')
+            next = idx <= 0 ? rows.length - 1 : idx - 1;
+        else if (e.key === 'Home')
+            next = 0;
+        else if (e.key === 'End')
+            next = rows.length - 1;
+        rows[next]?.focus();
+    };
+    const renderItem = (item) => {
+        const isActive = item.id === activeId;
+        return (_jsxs("button", { type: "button", className: "xeno-sidebar-item", "data-sidebar-item": "", "data-selection": isActive ? 'on' : 'off', "data-availability": "enabled", "aria-current": isActive ? 'page' : undefined, onClick: () => onSelect?.(item.id), children: [item.icon && (_jsx("span", { className: "xeno-sidebar-item-icon", "aria-hidden": "true", children: _jsx(XenoElement, { decl: item.icon, size: ITEM_ICON, ...(item.icon.contract.axes.includes('selection')
+                            ? { state: { selection: isActive ? 'on' : 'off' } }
+                            : {}) }) })), _jsx("span", { className: "xeno-sidebar-item-label", children: item.label })] }, item.id));
+    };
+    /**
+     * A group of rows plus the travelling pill that backs them. The pill is a real element and it is
+     * rendered LAST so the rows keep their natural `:nth-child` numbering — the stylesheet drives it
+     * purely with `.xeno-sidebar-item:nth-child(n):hover ~ .xeno-sidebar-goo`, no JS and no measuring.
+     */
+    const renderRows = (list) => (_jsxs("div", { className: "xeno-sidebar-items", children: [list.map(renderItem), _jsx("span", { className: "xeno-sidebar-goo", "aria-hidden": "true" })] }));
+    const state = open ? 'open' : 'closed';
+    return (_jsxs(_Fragment, { children: [backdrop && (_jsx("div", { className: "xeno-sidebar-backdrop", "data-state": state, "aria-hidden": "true", onClick: () => onOpenChange?.(false) })), _jsxs("aside", { className: cx('xeno-sidebar', className), "data-state": state, "aria-hidden": !open || undefined, ...inertWhen(!open), onKeyDown: onRootKeyDown, ...rest, children: [_jsxs("header", { className: "xeno-sidebar-header", children: [_jsx("div", { className: "xeno-sidebar-brand", children: brand }), searchable && (_jsx(TextInput, { className: "xeno-sidebar-search", leadingIcon: searchGlyph, placeholder: searchPlaceholder, "aria-label": searchPlaceholder, onChange: (e) => onSearchChange?.(e.currentTarget.value), ...(searchValue !== undefined ? { value: searchValue } : {}) }))] }), _jsxs("nav", { className: "xeno-sidebar-nav", "aria-label": navLabel, onKeyDown: onNavKeyDown, children: [_jsx("div", { className: "xeno-sidebar-section", children: renderRows(items) }), sections?.map((section, i) => (_jsxs("div", { className: "xeno-sidebar-section", children: [section.heading && (_jsx("div", { className: "xeno-sidebar-heading", "aria-hidden": "true", children: section.heading })), renderRows(section.items)] }, `section-${i}`)))] }), footer && _jsx("footer", { className: "xeno-sidebar-footer", children: footer })] })] }));
+}

package/dist/overlays/DateTimePicker.d.ts

@@ -0,0 +1,71 @@
+import type { HTMLAttributes, ReactElement } from 'react';
+/**
+ * DateTimePicker — a faithful port of the XENO chat's project "Scheduled" date/time popover
+ * (ChatWithLLM.tsx): monochrome, `rounded-md` (6px) throughout, a soft `--xeno-control` fill for the
+ * selection (never bright inverted ink), a fixed 6-week calendar (greyed overflow days keep the height
+ * stable), and a three-column time picker whose Hour/Min are quiet scroll lists and AM/PM two flat
+ * buttons. Both pieces render PURE from props so SSR is byte-deterministic (no `new Date()`).
+ *
+ * Exports {@link DatePicker} + {@link TimePicker}.
+ */
+/** A calendar date. `month` is 0-based (0 = January) to match `Date`'s month index. */
+export interface DateParts {
+    readonly year: number;
+    readonly month: number;
+    readonly day: number;
+}
+/** A visible month. `month` is 0-based (0 = January). */
+export interface MonthParts {
+    readonly year: number;
+    readonly month: number;
+}
+export interface DatePickerProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect' | 'children'> {
+    /** The month currently on screen (0-based month). */
+    readonly month: MonthParts;
+    /** The selected date — its cell gets the soft `--xeno-control` fill. */
+    readonly selected?: DateParts;
+    /** "Today" — gets `aria-current` and drives the Today button. */
+    readonly today?: DateParts;
+    /** The visible month should change (prev/next chevrons, PageUp/PageDown, Today). */
+    readonly onMonthChange?: (month: MonthParts) => void;
+    /** A day cell was activated (may be a day from the adjacent month). */
+    readonly onSelect?: (date: DateParts) => void;
+    /** The Clear button was pressed. When omitted the Clear button is hidden. */
+    readonly onClear?: () => void;
+    /** First column of the week: 0 = Sunday, 1 = Monday (default). */
+    readonly weekStartsOn?: 0 | 1;
+    /** Override the 12 month names (index 0 = January). */
+    readonly monthNames?: readonly string[];
+    /** Override the 7 short weekday names (index 0 = Sunday). */
+    readonly weekdayNames?: readonly string[];
+}
+/**
+ * `<DatePicker>` — a single-month calendar. A header (prev/next chevron {@link IconButton}s around a
+ * `Month Year` label), a weekday header (Mo…Su by default), a FIXED 6-week grid of square day cells
+ * (adjacent-month days shown greyed so the height never jumps), and a footer of Clear / Today ghost
+ * buttons. Controlled. Keyboard: arrows rove day-to-day (↑/↓ = week, ←/→ = day), Home/End jump to the
+ * ends of the grid, PageUp/PageDown change month, Enter/Space select (native).
+ */
+export declare function DatePicker({ month, selected, today, onMonthChange, onSelect, onClear, weekStartsOn, monthNames, weekdayNames, className, ...rest }: DatePickerProps): ReactElement;
+export type Meridiem = 'AM' | 'PM';
+/** A 12-hour clock time. `hour` is 1–12, `minute` is 0–59. */
+export interface TimeValue {
+    readonly hour: number;
+    readonly minute: number;
+    readonly meridiem: Meridiem;
+}
+export interface TimePickerProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'children'> {
+    /** The selected time. */
+    readonly value: TimeValue;
+    readonly onChange?: (value: TimeValue) => void;
+    /** Minute granularity for the middle column. Default 5. */
+    readonly minuteStep?: number;
+}
+/**
+ * `<TimePicker>` — three columns (Hour 1–12, Minute 00–59 by `minuteStep`, AM/PM). Hour + Min are quiet
+ * scroll lists inside their own hairline box; AM/PM is two flat buttons, not a scroller. The selected
+ * option in each column sits on `--xeno-control`. Controlled via `value` / `onChange`; each list is a
+ * `listbox` whose options rove with ↑/↓, Home/End jump, Enter/Space select. On change the selected
+ * scroll option is centred within its own column (never scrolling the page).
+ */
+export declare function TimePicker({ value, onChange, minuteStep, className, ...rest }: TimePickerProps): ReactElement;

package/dist/overlays/DateTimePicker.js

@@ -0,0 +1,191 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useRef } from 'react';
+import { IconButton } from '../controls/IconButton.js';
+import { Button } from '../controls/Button.js';
+import { cx } from '../controls/util.js';
+import ChevronRight from '@xenosystem/elements/elements/chevron-right';
+// ── Pure calendar math (no `Date`, so identical on server + client, any timezone) ─────────────────
+const DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+const SAKAMOTO = [0, 3, 2, 5, 0, 3, 5, 1, 4, 6, 2, 4];
+const isLeapYear = (y) => (y % 4 === 0 && y % 100 !== 0) || y % 400 === 0;
+const daysInMonth = (year, month0) => month0 === 1 && isLeapYear(year) ? 29 : (DAYS_IN_MONTH[month0] ?? 30);
+/** Day of week for a date, 0 = Sunday … 6 = Saturday. Sakamoto's algorithm — `month0` is 0-based. */
+const dayOfWeek = (year, month0, day) => {
+    const y = month0 < 2 ? year - 1 : year;
+    const t = SAKAMOTO[month0] ?? 0;
+    return (((y + Math.floor(y / 4) - Math.floor(y / 100) + Math.floor(y / 400) + t + day) % 7) + 7) % 7;
+};
+/** Shift a month by ±n, carrying the year. */
+const shiftMonth = (m, delta) => {
+    const total = m.year * 12 + m.month + delta;
+    return { year: Math.floor(total / 12), month: ((total % 12) + 12) % 12 };
+};
+const DEFAULT_MONTH_NAMES = [
+    'January',
+    'February',
+    'March',
+    'April',
+    'May',
+    'June',
+    'July',
+    'August',
+    'September',
+    'October',
+    'November',
+    'December',
+];
+/** Short weekday names indexed by JS day: 0 = Sunday … 6 = Saturday. */
+const DEFAULT_WEEKDAY_NAMES = ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'];
+const sameDay = (a, c) => a !== undefined && a.year === c.year && a.month === c.month && a.day === c.day;
+/**
+ * `<DatePicker>` — a single-month calendar. A header (prev/next chevron {@link IconButton}s around a
+ * `Month Year` label), a weekday header (Mo…Su by default), a FIXED 6-week grid of square day cells
+ * (adjacent-month days shown greyed so the height never jumps), and a footer of Clear / Today ghost
+ * buttons. Controlled. Keyboard: arrows rove day-to-day (↑/↓ = week, ←/→ = day), Home/End jump to the
+ * ends of the grid, PageUp/PageDown change month, Enter/Space select (native).
+ */
+export function DatePicker({ month, selected, today, onMonthChange, onSelect, onClear, weekStartsOn = 1, monthNames = DEFAULT_MONTH_NAMES, weekdayNames = DEFAULT_WEEKDAY_NAMES, className, ...rest }) {
+    const gridRef = useRef(null);
+    const labelId = useId();
+    const { year, month: m0 } = month;
+    const monthName = monthNames[m0] ?? '';
+    const total = daysInMonth(year, m0);
+    const firstDow = dayOfWeek(year, m0, 1);
+    const lead = (firstDow - weekStartsOn + 7) % 7;
+    // A FIXED 6-week (42-cell) grid, filled with real days from the previous and next months so the
+    // calendar height is constant and every cell is a real, clickable date.
+    const prev = shiftMonth(month, -1);
+    const next = shiftMonth(month, 1);
+    const prevTotal = daysInMonth(prev.year, prev.month);
+    const cells = [];
+    for (let i = 0; i < lead; i += 1) {
+        cells.push({ year: prev.year, month: prev.month, day: prevTotal - lead + 1 + i, inMonth: false });
+    }
+    for (let d = 1; d <= total; d += 1)
+        cells.push({ year, month: m0, day: d, inMonth: true });
+    for (let d = 1; cells.length < 42; d += 1) {
+        cells.push({ year: next.year, month: next.month, day: d, inMonth: false });
+    }
+    const weeks = [];
+    for (let i = 0; i < cells.length; i += 7)
+        weeks.push(cells.slice(i, i + 7));
+    // The single roving-tabbable cell: the selection (if this month), else today (if this month), else
+    // the 1st — always an in-month day.
+    const focusIdx = (() => {
+        const bySel = cells.findIndex((c) => c.inMonth && sameDay(selected, c));
+        if (bySel >= 0)
+            return bySel;
+        const byToday = cells.findIndex((c) => c.inMonth && sameDay(today, c));
+        if (byToday >= 0)
+            return byToday;
+        return cells.findIndex((c) => c.inMonth);
+    })();
+    const weekdayHeader = Array.from({ length: 7 }, (_, i) => {
+        const idx = (weekStartsOn + i) % 7;
+        return weekdayNames[idx] ?? '';
+    });
+    const goToMonth = (delta) => onMonthChange?.(shiftMonth(month, delta));
+    const goToday = () => {
+        if (!today)
+            return;
+        onMonthChange?.({ year: today.year, month: today.month });
+        onSelect?.(today);
+    };
+    // Arrow-key roving across the 42 day buttons by their grid index.
+    const onGridKeyDown = (e) => {
+        const nav = ['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End', 'PageUp', 'PageDown'];
+        if (!nav.includes(e.key))
+            return;
+        e.preventDefault();
+        if (e.key === 'PageUp')
+            return goToMonth(-1);
+        if (e.key === 'PageDown')
+            return goToMonth(1);
+        const grid = gridRef.current;
+        if (!grid)
+            return;
+        const buttons = Array.from(grid.querySelectorAll('[data-idx]'));
+        if (buttons.length === 0)
+            return;
+        const activeEl = typeof document !== 'undefined' ? document.activeElement : null;
+        const cur = activeEl instanceof HTMLButtonElement ? buttons.indexOf(activeEl) : -1;
+        const base = cur < 0 ? Math.max(0, focusIdx) : cur;
+        let nextIdx = base;
+        if (e.key === 'ArrowLeft')
+            nextIdx = base - 1;
+        else if (e.key === 'ArrowRight')
+            nextIdx = base + 1;
+        else if (e.key === 'ArrowUp')
+            nextIdx = base - 7;
+        else if (e.key === 'ArrowDown')
+            nextIdx = base + 7;
+        else if (e.key === 'Home')
+            nextIdx = 0;
+        else if (e.key === 'End')
+            nextIdx = buttons.length - 1;
+        nextIdx = Math.max(0, Math.min(buttons.length - 1, nextIdx));
+        buttons[nextIdx]?.focus();
+    };
+    let idx = -1;
+    return (_jsxs("div", { className: cx('xeno-datepicker', className), role: "group", "aria-labelledby": labelId, ...rest, children: [_jsxs("div", { className: "xeno-datepicker-header", children: [_jsx(IconButton, { className: "xeno-datepicker-nav xeno-datepicker-prev", icon: ChevronRight, "aria-label": "Previous month", size: "xs", onClick: () => goToMonth(-1) }), _jsxs("div", { className: "xeno-datepicker-title", id: labelId, "aria-live": "polite", children: [monthName, " ", year] }), _jsx(IconButton, { className: "xeno-datepicker-nav xeno-datepicker-next", icon: ChevronRight, "aria-label": "Next month", size: "xs", onClick: () => goToMonth(1) })] }), _jsx("div", { className: "xeno-datepicker-weekdays", "aria-hidden": "true", children: weekdayHeader.map((wd, i) => (_jsx("div", { className: "xeno-datepicker-weekday", children: wd }, `${wd}-${i}`))) }), _jsx("div", { className: "xeno-datepicker-grid", role: "grid", ref: gridRef, onKeyDown: onGridKeyDown, children: weeks.map((week, wi) => (_jsx("div", { className: "xeno-datepicker-week", role: "row", children: week.map((cell, di) => {
+                        idx += 1;
+                        const isSel = sameDay(selected, cell);
+                        const isToday = sameDay(today, cell);
+                        const cellIdx = idx;
+                        return (_jsx("button", { type: "button", className: "xeno-datepicker-cell xeno-datepicker-day", role: "gridcell", "data-idx": String(cellIdx), "data-outside": cell.inMonth ? undefined : '', "data-selection": isSel ? 'on' : 'off', "data-availability": "enabled", "aria-selected": isSel, "aria-current": isToday ? 'date' : undefined, tabIndex: cellIdx === focusIdx ? 0 : -1, onClick: () => onSelect?.({ year: cell.year, month: cell.month, day: cell.day }), children: cell.day }, di));
+                    }) }, wi))) }), _jsxs("div", { className: "xeno-datepicker-footer", children: [onClear !== undefined && (_jsx(Button, { className: "xeno-datepicker-clear", variant: "ghost", size: "xs", onClick: () => onClear(), children: "Clear" })), _jsx(Button, { className: "xeno-datepicker-today", variant: "ghost", size: "xs", disabled: today === undefined, onClick: goToday, children: "Today" })] })] }));
+}
+const HOURS = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
+const MERIDIEMS = ['AM', 'PM'];
+const pad2 = (n) => (n < 10 ? `0${n}` : `${n}`);
+/**
+ * `<TimePicker>` — three columns (Hour 1–12, Minute 00–59 by `minuteStep`, AM/PM). Hour + Min are quiet
+ * scroll lists inside their own hairline box; AM/PM is two flat buttons, not a scroller. The selected
+ * option in each column sits on `--xeno-control`. Controlled via `value` / `onChange`; each list is a
+ * `listbox` whose options rove with ↑/↓, Home/End jump, Enter/Space select. On change the selected
+ * scroll option is centred within its own column (never scrolling the page).
+ */
+export function TimePicker({ value, onChange, minuteStep = 5, className, ...rest }) {
+    const rootRef = useRef(null);
+    const step = minuteStep > 0 ? minuteStep : 5;
+    const minutes = [];
+    for (let mnt = 0; mnt < 60; mnt += step)
+        minutes.push(mnt);
+    // Centre the selected option within each SCROLL column's own box (no page scroll).
+    useEffect(() => {
+        const root = rootRef.current;
+        if (!root)
+            return;
+        root.querySelectorAll('[data-timecol]').forEach((col) => {
+            const sel = col.querySelector('[data-selection="on"]');
+            if (sel)
+                col.scrollTop = sel.offsetTop - col.clientHeight / 2 + sel.offsetHeight / 2;
+        });
+    }, [value.hour, value.minute, value.meridiem, step]);
+    // Roving focus within one column's options.
+    const onColumnKeyDown = (e) => {
+        if (!['ArrowUp', 'ArrowDown', 'Home', 'End'].includes(e.key))
+            return;
+        e.preventDefault();
+        const options = Array.from(e.currentTarget.querySelectorAll('[data-option]'));
+        if (options.length === 0)
+            return;
+        const activeEl = typeof document !== 'undefined' ? document.activeElement : null;
+        const cur = activeEl instanceof HTMLButtonElement ? options.indexOf(activeEl) : -1;
+        let next = cur < 0 ? 0 : cur;
+        if (e.key === 'ArrowUp')
+            next = cur <= 0 ? options.length - 1 : cur - 1;
+        else if (e.key === 'ArrowDown')
+            next = cur < 0 ? 0 : (cur + 1) % options.length;
+        else if (e.key === 'Home')
+            next = 0;
+        else if (e.key === 'End')
+            next = options.length - 1;
+        options[next]?.focus();
+    };
+    const column = (label, items, isSelected, format, onPick, scroll) => (_jsxs("div", { className: "xeno-timepicker-col", children: [_jsx("div", { className: "xeno-timepicker-col-head", "aria-hidden": "true", children: label }), _jsx("div", { className: "xeno-timepicker-list", role: "listbox", "aria-label": label, "data-scroll": scroll ? '' : undefined, "data-timecol": scroll ? '' : undefined, onKeyDown: onColumnKeyDown, children: items.map((item) => {
+                    const on = isSelected(item);
+                    return (_jsx("button", { type: "button", className: "xeno-timepicker-option", role: "option", "data-option": "", "data-selection": on ? 'on' : 'off', "data-availability": "enabled", "aria-selected": on, tabIndex: on ? 0 : -1, onClick: () => onPick(item), children: format(item) }, String(item)));
+                }) })] }));
+    return (_jsxs("div", { className: cx('xeno-timepicker', className), role: "group", "aria-label": "Time", ref: rootRef, ...rest, children: [column('Hour', HOURS, (h) => h === value.hour, (h) => String(h), (h) => onChange?.({ ...value, hour: h }), true), column('Min', minutes, (mnt) => mnt === value.minute, (mnt) => pad2(mnt), (mnt) => onChange?.({ ...value, minute: mnt }), true), column('AM/PM', MERIDIEMS, (mer) => mer === value.meridiem, (mer) => String(mer), (mer) => onChange?.({ ...value, meridiem: mer }), false)] }));
+}