@mistriwork/ui 0.0.0-stage → 1.0.0-rc.10

package/dist/DateField.js

@@ -0,0 +1,255 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The themed calendar field: editable ISO text beside a calendar popover,
+ * for a date, or with `withTime` for a date and a wall-clock time. The text
+ * is the value — typed drafts survive, the calendar only ever writes the
+ * date part — and nothing here converts a value through an instant. The
+ * arithmetic and the bounds are datePickerModel.ts's. Its words and the
+ * calendar button's icon are props: the kit lends its catalog's and its icon.
+ */
+import { useCallback, useEffect, useId, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, } from 'react';
+import { Popover } from '@base-ui/react/popover';
+import { layoutViewport, zoomAnchor } from './internal/anchor.js';
+import { addDateDays, addDateMonths, clampDate, dateBounds, dateFormat, dateParts, dateTimeWithinBounds, dateWithinBounds, isPickerDate, isPickerDateTime, monthGrid, monthLabel, splitDateTime, todayInZone, weekdayLabels, withDate, } from './internal/datePickerModel.js';
+import { popupContainer } from './internal/popups.js';
+/** How a locale writes a numeric date: the order of its parts and its separator ("MM/DD/YYYY" in en-US). */
+function dateMask(locale) {
+    let parts;
+    try {
+        parts = dateFormat(locale, { year: 'numeric', month: '2-digit', day: '2-digit', timeZone: 'UTC', calendar: 'gregory' }).formatToParts(Date.UTC(2006, 10, 22));
+    }
+    catch {
+        parts = [];
+    }
+    const order = parts.filter((part) => ['year', 'month', 'day'].includes(part.type)).map((part) => part.type);
+    if (order.length !== 3)
+        return { order: ['year', 'month', 'day'], sep: '-', hint: 'YYYY-MM-DD' };
+    const sep = parts.find((part) => part.type === 'literal')?.value.trim() || '/';
+    const word = { year: 'YYYY', month: 'MM', day: 'DD' };
+    return { order, sep, hint: order.map((type) => word[type]).join(sep) };
+}
+/** An ISO date as the locale writes it in a box. */
+function localeText(iso, mask) {
+    const { year, month, day } = dateParts(iso);
+    const of = {
+        year: String(year).padStart(4, '0'),
+        month: String(month).padStart(2, '0'),
+        day: String(day).padStart(2, '0'),
+    };
+    return mask.order.map((type) => of[type]).join(mask.sep);
+}
+const isoDate = (text) => isPickerDate(text);
+/** What was typed, read as a whole date in the locale's order (or ISO), else undefined: a draft stays text. */
+function readDate(text, mask) {
+    if (isoDate(text))
+        return text;
+    const numbers = text.trim().match(/^(\d{1,4})\D(\d{1,2})\D(\d{1,4})$/);
+    if (!numbers)
+        return undefined;
+    const at = {};
+    mask.order.forEach((type, index) => (at[type] = numbers[index + 1]));
+    if (at.year.length !== 4)
+        return undefined;
+    const iso = `${at.year}-${at.month.padStart(2, '0')}-${at.day.padStart(2, '0')}`;
+    return isPickerDate(iso) ? iso : undefined;
+}
+/** A date field, or a date and a wall-clock time. No input is parsed as an instant or shifted by a timezone. */
+export function DateField({ id, words, calendarIcon, value, onChange, onBlur, onKeyDown, disabled, required, min, max, locale, timezone, firstDay = 1, className = '', name, inputRef, placeholder, withTime = false, popupRef, onOpenChange, 'aria-label': label, 'aria-invalid': invalid, 'aria-describedby': describedBy, }) {
+    // The calendar only ever sees the date; a wall time's clock stays in the box.
+    const datePart = withTime ? (splitDateTime(value)?.date ?? value.slice(0, 10)) : value;
+    // A range facet may temporarily supply an incomplete or reversed bound.
+    // Keep text editable but disable calendar selection until both ends agree.
+    const configuredBounds = useMemo(() => {
+        try {
+            return dateBounds(withTime ? min?.slice(0, 10) : min, withTime ? max?.slice(0, 10) : max);
+        }
+        catch {
+            return null;
+        }
+    }, [min, max, withTime]);
+    const bounds = configuredBounds ?? dateBounds();
+    const today = todayInZone(new Date(), timezone);
+    const seed = () => clampDate(isPickerDate(datePart) ? datePart : today, bounds);
+    const [active, setActive] = useState(seed);
+    const [open, setOpenState] = useState(false);
+    const openCallback = useRef(onOpenChange);
+    useLayoutEffect(() => {
+        openCallback.current = onOpenChange;
+    });
+    const setOpen = (next) => {
+        setOpenState(next);
+        openCallback.current?.(next);
+    };
+    const [container, setContainer] = useState(null);
+    const group = useRef(null);
+    const trigger = useRef(null);
+    const input = useRef(null);
+    useImperativeHandle(inputRef, () => input.current, []);
+    const popup = useRef(null);
+    const setPopup = useCallback((node) => {
+        popup.current = node;
+        popupRef?.(node);
+    }, [popupRef]);
+    const ownedFocus = useRef(false);
+    const moveFocus = useRef(false);
+    const blurTimer = useRef(undefined);
+    const restoreFocus = useRef(false);
+    const blurCallback = useRef(onBlur);
+    useLayoutEffect(() => {
+        blurCallback.current = onBlur;
+    });
+    const caption = useId();
+    const hint = useId();
+    /* A date alone is shown as the locale writes it and kept as ISO; what is being typed stays as typed until the
+       field is left, so a half-typed date is never rewritten under the caret. A date with a time stays ISO text. */
+    const mask = useMemo(() => dateMask(locale), [locale]);
+    const [draft, setDraft] = useState(null);
+    const shown = withTime ? value : (draft ?? (isPickerDate(value) ? localeText(value, mask) : value));
+    const formatHint = withTime ? words.dateTimePattern : mask.hint;
+    useEffect(() => {
+        if (draft !== null && value !== (readDate(draft, mask) ?? draft))
+            setDraft(null);
+    }, [value]); // eslint-disable-line react-hooks/exhaustive-deps
+    const days = monthGrid(active, firstDay, bounds);
+    const weekdays = weekdayLabels(locale, firstDay);
+    useEffect(() => {
+        setContainer(trigger.current?.closest('dialog, [role="dialog"]'));
+        return () => {
+            clearTimeout(blurTimer.current);
+        };
+    }, []);
+    const bad = !configuredBounds ||
+        (value !== '' &&
+            (withTime
+                ? !isPickerDateTime(value) || !dateWithinBounds(datePart, bounds) || !dateTimeWithinBounds(value, min, max)
+                : !dateWithinBounds(value, bounds)));
+    useEffect(() => {
+        input.current?.setCustomValidity(!bad ? '' : withTime ? words.enterDateAndTime : words.enterDate(mask.hint));
+    }, [bad, withTime, mask]); // eslint-disable-line react-hooks/exhaustive-deps
+    useLayoutEffect(() => {
+        if (!open)
+            return;
+        if (!configuredBounds || disabled) {
+            setOpen(false);
+            return;
+        }
+        const next = clampDate(isPickerDate(datePart) ? datePart : active, configuredBounds);
+        if (next !== active) {
+            moveFocus.current = Boolean(popup.current?.querySelector('[data-date]:focus'));
+            setActive(next);
+        }
+        // Synchronize external changes, not arrow-key movement within the calendar.
+    }, [value, min, max, disabled]);
+    useLayoutEffect(() => {
+        if (!open || !moveFocus.current)
+            return;
+        popup.current?.querySelector(`[data-date="${active}"]`)?.focus();
+        moveFocus.current = false;
+    }, [active, open]);
+    const within = (node) => Boolean(node && (group.current?.contains(node) || popup.current?.contains(node)));
+    const commitBlur = () => {
+        if (ownedFocus.current) {
+            ownedFocus.current = false;
+            setDraft(null);
+            blurCallback.current?.();
+        }
+    };
+    const checkBlur = () => {
+        clearTimeout(blurTimer.current);
+        // Let the portal's focus restoration finish before deciding the field was left.
+        blurTimer.current = setTimeout(() => {
+            if (!within(document.activeElement))
+                commitBlur();
+        }, 0);
+    };
+    const leave = (event) => {
+        if (!event.relatedTarget) {
+            checkBlur();
+            return;
+        }
+        clearTimeout(blurTimer.current);
+        // Pointer focus leaves before the destination's click/submit. Publish the
+        // draft now so a surrounding filter's Apply button reads the new value.
+        if (!within(event.relatedTarget))
+            commitBlur();
+    };
+    const changeOpen = (next) => {
+        if (next) {
+            restoreFocus.current = false;
+            setActive(seed());
+        }
+        setOpen(next);
+        if (!next)
+            checkBlur();
+    };
+    const returnToTrigger = () => {
+        const target = trigger.current;
+        if (target?.isConnected && (!container || (container.isConnected && !container.hasAttribute('data-closed')))) {
+            target.focus({ preventScroll: true });
+        }
+    };
+    const choose = (date) => {
+        restoreFocus.current = true;
+        setDraft(null);
+        // Move focus before removing the focused day. Otherwise an enclosing
+        // modal sees focus fall to body and starts its own recovery to the dialog.
+        returnToTrigger();
+        onChange(withTime && date ? withDate(value, date) : date);
+        changeOpen(false);
+    };
+    const move = (date) => {
+        moveFocus.current = true;
+        setActive(clampDate(date, bounds));
+    };
+    const onDayKey = (event) => {
+        const index = days.findIndex((day) => day.date === active) % 7;
+        const steps = { ArrowLeft: -1, ArrowRight: 1, ArrowUp: -7, ArrowDown: 7, Home: -index, End: 6 - index };
+        if (Object.hasOwn(steps, event.key)) {
+            event.preventDefault();
+            event.stopPropagation();
+            move(addDateDays(active, steps[event.key]));
+        }
+        else if (event.key === 'PageUp' || event.key === 'PageDown') {
+            event.preventDefault();
+            event.stopPropagation();
+            move(addDateMonths(active, (event.key === 'PageUp' ? -1 : 1) * (event.shiftKey ? 12 : 1)));
+        }
+    };
+    const dayName = (date) => {
+        const p = dateParts(date), ruler = new Date(0);
+        ruler.setUTCFullYear(p.year, p.month - 1, p.day);
+        return dateFormat(locale, { calendar: 'gregory', timeZone: 'UTC', dateStyle: 'full' }).format(ruler);
+    };
+    const previous = addDateMonths(active, -1), next = addDateMonths(active, 1);
+    return (_jsx(Popover.Root, { open: open && !disabled && Boolean(configuredBounds), onOpenChange: (next, details) => {
+            restoreFocus.current = !next && details.reason === 'escape-key';
+            if (restoreFocus.current)
+                returnToTrigger();
+            changeOpen(next);
+        }, children: _jsxs("span", { ref: group, className: withTime ? 'date-field with-time' : 'date-field', onFocus: () => {
+                ownedFocus.current = true;
+            }, onBlur: leave, children: [_jsx("input", { ref: input, id: id, name: name, type: "text", value: shown, className: `date-field-input ${className}`, placeholder: placeholder ?? (withTime ? words.dateTimePattern : mask.hint), autoComplete: "off", spellCheck: false, disabled: disabled, required: required, "aria-required": required, "aria-label": label, "aria-invalid": invalid || bad || undefined, "aria-describedby": [describedBy, hint].filter(Boolean).join(' '), onChange: (event) => {
+                        const text = event.target.value;
+                        if (withTime)
+                            return onChange(text);
+                        setDraft(text);
+                        onChange(readDate(text, mask) ?? text);
+                    }, onKeyDown: (event) => {
+                        if (event.altKey && event.key === 'ArrowDown') {
+                            event.preventDefault();
+                            event.stopPropagation();
+                            if (configuredBounds)
+                                changeOpen(true);
+                        }
+                        else
+                            onKeyDown?.(event);
+                    } }), _jsxs("span", { id: hint, className: "date-field-hint", children: [withTime ? words.dateAndTimeFormat : words.dateFormat(formatHint), " ", words.openWithKeys] }), _jsx(Popover.Trigger, { render: _jsx("button", { ref: trigger, type: "button", className: "date-field-trigger", disabled: disabled || !configuredBounds, "aria-label": words.chooseDate(label || undefined) }), children: calendarIcon }), _jsx(Popover.Portal, { container: container ?? popupContainer(), children: _jsx(Popover.Positioner, { anchor: () => (trigger.current ? zoomAnchor(trigger.current) : null), positionMethod: "fixed", side: "bottom", align: "end", sideOffset: 6, collisionBoundary: layoutViewport(), collisionPadding: 8, style: { zIndex: 45 }, children: _jsxs(Popover.Popup, { ref: setPopup, finalFocus: () => {
+                                const target = trigger.current, focused = document.activeElement;
+                                return restoreFocus.current &&
+                                    target?.isConnected &&
+                                    (!container || (container.isConnected && !container.hasAttribute('data-closed'))) &&
+                                    (focused === target || focused === document.body || focused === container)
+                                    ? target
+                                    : false;
+                            }, className: "date-field-popup", "aria-label": words.calendar(label || undefined), initialFocus: () => popup.current?.querySelector(`[data-date="${active}"]`) ?? true, children: [_jsxs("div", { className: "date-field-head", children: [_jsx("button", { type: "button", "aria-label": words.previousMonth, disabled: previous.slice(0, 7) === active.slice(0, 7) || previous.slice(0, 7) < bounds.min.slice(0, 7), onClick: () => setActive(clampDate(previous, bounds)), children: "\u2190" }), _jsx("span", { id: caption, "aria-live": "polite", "aria-atomic": "true", children: monthLabel(active, locale) }), _jsx("button", { type: "button", "aria-label": words.nextMonth, disabled: next.slice(0, 7) === active.slice(0, 7) || next.slice(0, 7) > bounds.max.slice(0, 7), onClick: () => setActive(clampDate(next, bounds)), children: "\u2192" })] }), _jsxs("table", { className: "date-field-calendar", role: "grid", "aria-labelledby": caption, children: [_jsx("thead", { children: _jsx("tr", { children: weekdays.map((day) => (_jsx("th", { scope: "col", "aria-label": day.long, children: day.short }, day.long))) }) }), _jsx("tbody", { children: Array.from({ length: 6 }, (_, week) => (_jsx("tr", { children: days.slice(week * 7, week * 7 + 7).map((day, index) => (_jsx("td", { "aria-selected": day.date === datePart, children: day.date && (_jsx("button", { type: "button", "data-date": day.date, "data-outside": !day.inMonth || undefined, "data-selected": day.date === datePart || undefined, "aria-current": day.date === today ? 'date' : undefined, disabled: day.disabled, tabIndex: day.date === active ? 0 : -1, "aria-label": dayName(day.date), onKeyDown: onDayKey, onClick: () => choose(day.date), children: Number(day.date.slice(8)) })) }, day.date ?? index))) }, week))) })] }), _jsxs("div", { className: "date-field-foot", children: [_jsx("button", { type: "button", onClick: () => choose(''), children: words.clear }), _jsx("button", { type: "button", disabled: !dateWithinBounds(today, bounds), onClick: () => choose(today), children: words.today })] })] }) }) })] }) }));
+}

package/dist/Drawer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A drawer: a sheet that slides in from an edge, over Base UI's Drawer,
+ * which gives it the scrim, focus held inside, Escape and a click on the
+ * scrim to dismiss, focus handed back on close, and the swipe to dismiss
+ * on a phone. Controlled with `open`/`onOpenChange`; a closed drawer is
+ * dismissed (its exit animation aside, the sheet stays in the tree only
+ * while that runs), so nothing inside it is read while it is shut.
+ * `side` is the edge it comes from, right by default,
+ * and the panel is at most 420px wide (a left drawer the same), full
+ * width on a phone. The sheet is named by its `title` or, where it draws
+ * none, by `ariaLabel`; one of the two is required.
+ */
+import type { ReactNode } from 'react';
+export type DrawerSide = 'left' | 'right';
+interface DrawerBase {
+    open: boolean;
+    onOpenChange?: (open: boolean) => void;
+    side?: DrawerSide;
+    children: ReactNode;
+    className?: string;
+    /** A non-cancellable operation is awaiting acknowledgement. */
+    closeDisabled?: boolean;
+}
+/** A sheet is named by a title it draws or by an `ariaLabel` it does not; one of the two is required, so none is announced unnamed. */
+export type DrawerProps = DrawerBase & ({
+    title: ReactNode;
+    ariaLabel?: string;
+} | {
+    title?: undefined;
+    ariaLabel: string;
+});
+export declare function Drawer({ open, onOpenChange, side, title, ariaLabel, children, className, closeDisabled }: DrawerProps): import("react").JSX.Element;
+export {};

package/dist/Drawer.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Drawer as BaseDrawer } from '@base-ui/react/drawer';
+export function Drawer({ open, onOpenChange, side = 'right', title, ariaLabel, children, className, closeDisabled = false }) {
+    return (_jsx(BaseDrawer.Root, { open: open, disablePointerDismissal: closeDisabled, onOpenChange: (next) => {
+            /* A non-cancellable operation: a dismissal request (Escape, a
+               click outside) is refused here, as Modal's beforeClose refuses
+               one, and the controlled drawer stays open. */
+            if (!next && closeDisabled)
+                return;
+            onOpenChange?.(next);
+        }, children: _jsxs(BaseDrawer.Portal, { children: [_jsx(BaseDrawer.Backdrop, { className: "ui-drawer-backdrop" }), _jsx(BaseDrawer.Viewport, { className: ['ui-drawer-viewport', `ui-drawer-${side}`, className].filter(Boolean).join(' '), children: _jsxs(BaseDrawer.Popup, { className: "ui-drawer", "aria-label": ariaLabel ?? (typeof title === 'string' ? title : undefined), children: [title !== undefined ? _jsx(BaseDrawer.Title, { className: "ui-drawer-title", children: title }) : null, children] }) })] }) }));
+}

package/dist/DropMenu.d.ts

@@ -0,0 +1,59 @@
+/**
+ * A button that opens a menu, over Base UI's Menu — what the `<details>`
+ * menus here did with a summary and a hook (react to a click, close on
+ * Escape or a click outside, hand focus back), plus what they never did:
+ * arrows between the items, Home and End, typeahead, and the roles a
+ * screen reader expects of a menu.
+ *
+ * The wrapper keeps the caller's class (`export`, `pb-picker`) because the
+ * stylesheet places the control by it; the trigger and the popup wear the
+ * classes the summary and the panel wore. The popup is anchored on the
+ * zoom-aware ruler (anchor.ts) and fixed to the viewport, so a scrolling
+ * panel cannot clip it. The open state can be the caller's, for a menu
+ * that has to stay up while a click inside it fetches.
+ */
+import { type ReactNode, type Ref } from 'react';
+import { Menu } from '@base-ui/react/menu';
+interface DropMenuProps {
+    /** The wrapper's class — where the stylesheet places the control. */
+    className?: string;
+    /** The trigger's classes; a secondary button's by default. */
+    triggerClassName?: string;
+    triggerTitle?: string;
+    /** The trigger's accessible name, when its visible label is shared with another menu on the page. */
+    triggerLabel?: string;
+    label: ReactNode;
+    /** The popup's classes; the house listbox surface (`dd-list`) by default. */
+    popupClassName?: string;
+    side?: 'top' | 'bottom';
+    align?: 'start' | 'end';
+    sideOffset?: number;
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Where the focus goes when the menu closes; absent, back to the trigger. */
+    finalFocus?: Menu.Popup.Props['finalFocus'];
+    children: ReactNode;
+}
+export declare function DropMenu({ className, triggerClassName, triggerTitle, triggerLabel, label, popupClassName, side, align, sideOffset, open, onOpenChange, finalFocus, children, }: DropMenuProps): import("react").JSX.Element;
+/** A labelled run of items: a menu that changes several things says which each item changes. */
+export declare function DropGroup({ className, labelClassName, label, children, }: {
+    className?: string;
+    labelClassName?: string;
+    label: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** A rule between two runs of items, a separator to a screen reader. */
+export declare function DropSeparator({ className }: {
+    className?: string;
+}): import("react").JSX.Element;
+/** An item drawn as a button, so `disabled` and the button styles hold. Closes the menu unless told not to. */
+export declare function DropItem({ className, disabled, closeOnClick, onClick, title, children, ref, }: {
+    className?: string;
+    disabled?: boolean;
+    closeOnClick?: boolean;
+    onClick: () => void;
+    title?: string;
+    children: ReactNode;
+    ref?: Ref<HTMLButtonElement>;
+}): import("react").JSX.Element;
+export {};

package/dist/DropMenu.js

@@ -0,0 +1,52 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A button that opens a menu, over Base UI's Menu — what the `<details>`
+ * menus here did with a summary and a hook (react to a click, close on
+ * Escape or a click outside, hand focus back), plus what they never did:
+ * arrows between the items, Home and End, typeahead, and the roles a
+ * screen reader expects of a menu.
+ *
+ * The wrapper keeps the caller's class (`export`, `pb-picker`) because the
+ * stylesheet places the control by it; the trigger and the popup wear the
+ * classes the summary and the panel wore. The popup is anchored on the
+ * zoom-aware ruler (anchor.ts) and fixed to the viewport, so a scrolling
+ * panel cannot clip it. The open state can be the caller's, for a menu
+ * that has to stay up while a click inside it fetches.
+ */
+import { useEffect, useRef, useState } from 'react';
+import { Menu } from '@base-ui/react/menu';
+import { layoutViewport, zoomAnchor } from './internal/anchor.js';
+import { popupContainer } from './internal/popups.js';
+import { buttonClass } from './Button.js';
+export function DropMenu({ className, triggerClassName = buttonClass(), triggerTitle, triggerLabel, label, popupClassName = 'dd-list', side = 'bottom', align = 'end', sideOffset = 4, open, onOpenChange, finalFocus, children, }) {
+    const trigger = useRef(null);
+    /* Inside a dialog the popup is drawn into that dialog, so it shares its
+       stacking context rather than landing behind it; elsewhere it goes to
+       the body the way every floating surface here does. */
+    const [container, setContainer] = useState(null);
+    useEffect(() => {
+        setContainer(trigger.current?.closest('dialog, [role="dialog"]'));
+    }, []);
+    const [own, setOwn] = useState(false);
+    const isOpen = open ?? own;
+    const change = (next, details) => {
+        // Return focus before unmount so a containing dialog does not reclaim it — unless the caller says where it goes.
+        if (!next && details.reason === 'escape-key' && finalFocus === undefined)
+            trigger.current?.focus({ preventScroll: true });
+        setOwn(next);
+        onOpenChange?.(next);
+    };
+    return (_jsx("div", { className: className || undefined, children: _jsxs(Menu.Root, { open: isOpen, onOpenChange: change, children: [_jsx(Menu.Trigger, { render: _jsx("button", { type: "button", className: triggerClassName, title: triggerTitle, "aria-label": triggerLabel, ref: trigger }), children: label }), _jsx(Menu.Portal, { container: container ?? popupContainer(), children: _jsx(Menu.Positioner, { anchor: () => (trigger.current ? zoomAnchor(trigger.current) : null), positionMethod: "fixed", side: side, align: align, sideOffset: sideOffset, collisionBoundary: layoutViewport(), collisionPadding: 8, style: { zIndex: 90 }, children: _jsx(Menu.Popup, { className: popupClassName, finalFocus: finalFocus, children: children }) }) })] }) }));
+}
+/** A labelled run of items: a menu that changes several things says which each item changes. */
+export function DropGroup({ className, labelClassName, label, children, }) {
+    return (_jsxs(Menu.Group, { className: className, children: [_jsx(Menu.GroupLabel, { className: labelClassName, children: label }), children] }));
+}
+/** A rule between two runs of items, a separator to a screen reader. */
+export function DropSeparator({ className = 'dd-divider' }) {
+    return _jsx(Menu.Separator, { className: className });
+}
+/** An item drawn as a button, so `disabled` and the button styles hold. Closes the menu unless told not to. */
+export function DropItem({ className = 'dd-option', disabled, closeOnClick, onClick, title, children, ref, }) {
+    return (_jsx(Menu.Item, { render: _jsx("button", { type: "button", className: className, title: title, ref: ref }), nativeButton: true, disabled: disabled, closeOnClick: closeOnClick, onClick: onClick, children: children }));
+}

package/dist/Dropdown.d.ts

@@ -0,0 +1,73 @@
+/**
+ * A themed listbox, over Base UI's Select.
+ *
+ * A native `<select>` cannot be styled where it matters: the open menu is
+ * drawn by the operating system, in the system font, with the system
+ * highlight colour, ignoring the page entirely. Base UI gives back what
+ * the native one gave for free — arrows move, Home and End jump, Enter and
+ * Space choose, Escape closes and returns focus, Tab closes, typing jumps
+ * to a matching option, the roles and `aria-expanded` — and this draws it
+ * in the tool's own classes, so the stylesheet and the browser suite see
+ * the control they always saw.
+ *
+ * Actions ride under a divider and are walked with the same arrows, but
+ * run rather than become the value: the value stays what the caller says
+ * it is, so choosing "re-read the schema" cannot select it.
+ */
+import { type Ref } from 'react';
+export interface DropdownItem {
+    value: string;
+    label: string;
+    detail?: string;
+    badge?: string;
+    disabled?: boolean;
+    /** Colours the option's word; the five tones of a display rule. */
+    tone?: 'good' | 'warn' | 'bad' | 'info' | 'neutral';
+    swatches?: string[];
+}
+interface DropdownBase {
+    items: DropdownItem[];
+    /** What a reader hears the list called; the kit's Dropdown supplies its catalog's word where a caller names none. */
+    ariaLabel?: string;
+    ariaInvalid?: boolean;
+    ariaDescribedBy?: string;
+    /** The caption that names the button, where it is drawn beside it (a field's label, "(required)" and all); `ariaLabel` gives way to it. */
+    ariaLabelledBy?: string;
+    /** The button's id, so a field's `<label for>` names it (components/Field.tsx). */
+    id?: string;
+    /** The button, for a form that needs to put focus on this control. */
+    buttonRef?: Ref<HTMLButtonElement>;
+    popupRef?: Ref<HTMLDivElement>;
+    onOpenChange?: (open: boolean) => void;
+    disabled?: boolean;
+    readOnly?: boolean;
+    /** A class on the shown value — a page title that is also a picker. */
+    valueClassName?: string;
+    /** Things to do rather than pick, listed under a divider — "re-read the schema" beneath the databases. */
+    actions?: DropdownAction[];
+    /** Classes on the button beside `dd-button`: a form's field wears `field-control` through it. */
+    buttonClassName?: string;
+    /** Classes on the list beside `dd-list`. */
+    listClassName?: string;
+    /** The id of the shown value, so a form can name the button by its label and its value both. */
+    valueId?: string;
+    /** What the button says while nothing is chosen (a form's "Choose"); without it an empty list says a dash. */
+    placeholder?: string;
+}
+export type DropdownProps = DropdownBase & {
+    value: string;
+    onChange: (value: string) => void;
+};
+/** `MultiDropdown`'s: the list of values taken and given, kept in the items' order. */
+export type MultiDropdownProps = DropdownBase & {
+    value: string[];
+    onChange: (value: string[]) => void;
+};
+export interface DropdownAction {
+    label: string;
+    onSelect: () => void;
+}
+export declare function Dropdown(props: DropdownProps): import("react").JSX.Element;
+/** The same listbox choosing several: it stays open while it is chosen from, and the button says the choices. */
+export declare function MultiDropdown(props: MultiDropdownProps): import("react").JSX.Element;
+export {};

package/dist/Dropdown.js

@@ -0,0 +1,85 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A themed listbox, over Base UI's Select.
+ *
+ * A native `<select>` cannot be styled where it matters: the open menu is
+ * drawn by the operating system, in the system font, with the system
+ * highlight colour, ignoring the page entirely. Base UI gives back what
+ * the native one gave for free — arrows move, Home and End jump, Enter and
+ * Space choose, Escape closes and returns focus, Tab closes, typing jumps
+ * to a matching option, the roles and `aria-expanded` — and this draws it
+ * in the tool's own classes, so the stylesheet and the browser suite see
+ * the control they always saw.
+ *
+ * Actions ride under a divider and are walked with the same arrows, but
+ * run rather than become the value: the value stays what the caller says
+ * it is, so choosing "re-read the schema" cannot select it.
+ */
+import { useEffect, useRef, useState } from 'react';
+import { Select } from '@base-ui/react/select';
+import { layoutViewport, zoomAnchor } from './internal/anchor.js';
+import { popupContainer } from './internal/popups.js';
+/* A value no option could carry, so an action's row is told apart from an option's. */
+const ACTION = '~~action:';
+export function Dropdown(props) {
+    return _jsx(DropdownList, { ...props });
+}
+/** The same listbox choosing several: it stays open while it is chosen from, and the button says the choices. */
+export function MultiDropdown(props) {
+    return _jsx(DropdownList, { ...props, multiple: true });
+}
+function DropdownList(props) {
+    const { items, ariaLabel, ariaInvalid, ariaDescribedBy, ariaLabelledBy, id, buttonRef, popupRef, onOpenChange, disabled, readOnly, valueClassName, actions = [], buttonClassName, listClassName, valueId, placeholder, } = props;
+    const many = props.multiple === true;
+    const chosen = props.multiple === true ? props.value : [props.value];
+    const selected = items.find((i) => i.value === chosen[0]);
+    /* Nothing chosen: a value no item carries (a form's empty answer) reads as no selection, not as a stray one. */
+    const said = many
+        ? items
+            .filter((i) => chosen.includes(i.value))
+            .map((i) => i.label)
+            .join(', ')
+        : (selected?.label ?? '');
+    /* Where the list is drawn. A list portalled to the end of the body sits
+       behind a modal <dialog>'s top layer, and half the pickers here live in
+       one — so inside a dialog the list is drawn into that dialog, and keeps
+       its stacking context; elsewhere it goes to the body the way every
+       floating surface here does. */
+    const root = useRef(null);
+    const [container, setContainer] = useState(null);
+    useEffect(() => {
+        setContainer(root.current?.closest('dialog, [role="dialog"]'));
+    }, []);
+    /* The trigger, for the anchor measured with the zoom-aware ruler (anchor.ts). */
+    const trigger = useRef(null);
+    const setTrigger = (node) => {
+        trigger.current = node;
+        if (typeof buttonRef === 'function')
+            buttonRef(node);
+        else if (buttonRef)
+            buttonRef.current = node;
+    };
+    return (_jsx("div", { className: "dd", ref: root, children: _jsxs(Select.Root, { multiple: many || undefined, value: (many ? chosen : selected ? selected.value : null), disabled: disabled, readOnly: readOnly, onOpenChange: onOpenChange, 
+            /* The labels, handed over: without them Base UI mounts the list
+               once, hidden, to read the selected label off an item. */
+            items: items.map((i) => ({ value: i.value, label: i.label })), onValueChange: (next) => {
+                if (props.multiple === true) {
+                    if (!Array.isArray(next))
+                        return;
+                    const ran = next.find((v) => typeof v === 'string' && v.startsWith(ACTION));
+                    if (ran)
+                        actions[Number(ran.slice(ACTION.length))]?.onSelect();
+                    else
+                        props.onChange(items.map((i) => i.value).filter((v) => next.includes(v)));
+                    return;
+                }
+                if (typeof next !== 'string')
+                    return;
+                if (next.startsWith(ACTION)) {
+                    actions[Number(next.slice(ACTION.length))]?.onSelect();
+                    return;
+                }
+                if (next !== props.value)
+                    props.onChange(next);
+            }, children: [_jsxs(Select.Trigger, { render: _jsx("button", { type: "button", role: "button", id: id, className: buttonClassName ? `dd-button ${buttonClassName}` : 'dd-button', ref: setTrigger, "aria-label": ariaLabelledBy ? undefined : ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-invalid": ariaInvalid || undefined, "aria-describedby": ariaDescribedBy, title: selected?.detail ?? '' }), children: [selected?.swatches && (_jsx("span", { className: "dd-swatches", "aria-hidden": "true", children: selected.swatches.map((color, index) => (_jsx("span", { style: { background: color } }, index))) })), _jsx("span", { id: valueId, className: `dd-value${valueClassName ? ` ${valueClassName}` : ''}${said ? '' : ' is-empty'}`, children: said || placeholder || '—' }), _jsx("span", { className: "dd-caret", "aria-hidden": "true", children: "\u25BE" })] }), _jsx(Select.Portal, { container: container ?? popupContainer(), children: _jsx(Select.Positioner, { anchor: () => (trigger.current ? zoomAnchor(trigger.current) : null), alignItemWithTrigger: false, positionMethod: "fixed", side: "bottom", align: "start", sideOffset: 4, collisionBoundary: layoutViewport(), collisionPadding: 8, style: { zIndex: 40 }, children: _jsx(Select.Popup, { ref: popupRef, className: "dd-popup", children: _jsxs(Select.List, { className: ['dd-list', many ? 'dd-list-multi' : '', listClassName].filter(Boolean).join(' '), "aria-label": ariaLabel, "aria-labelledby": ariaLabel ? undefined : ariaLabelledBy?.split(' ')[0], children: [items.map((item) => (_jsxs(Select.Item, { value: item.value, label: item.label, disabled: item.disabled, className: (s) => `dd-option${s.selected ? ' selected' : ''}${item.disabled ? ' disabled' : ''}${item.tone ? ` dd-tone-${item.tone}` : ''}${s.highlighted ? ' active' : ''}`, children: [many ? (_jsx("span", { className: "dd-box", "aria-hidden": "true" })) : (_jsx("span", { className: "dd-check", "aria-hidden": "true", children: item.value === props.value ? '✓' : '' })), item.swatches && (_jsx("span", { className: "dd-swatches", "aria-hidden": "true", children: item.swatches.map((color, index) => (_jsx("span", { style: { background: color } }, index))) })), _jsxs("span", { className: "dd-text", children: [_jsx("span", { className: "dd-label", children: item.label }), item.detail && _jsx("span", { className: "dd-detail", children: item.detail })] }), item.badge && _jsx("span", { className: "dd-badge", children: item.badge })] }, item.value))), actions.length ? _jsx("div", { className: "dd-divider", role: "presentation" }) : null, actions.map((action, i) => (_jsxs(Select.Item, { value: `${ACTION}${i}`, label: action.label, className: (s) => `dd-option dd-action${s.highlighted ? ' active' : ''}`, children: [_jsx("span", { className: "dd-check", "aria-hidden": "true" }), _jsx("span", { className: "dd-text", children: _jsx("span", { className: "dd-label", children: action.label }) })] }, action.label)))] }) }) }) })] }) }));
+}

package/dist/Field.d.ts

@@ -0,0 +1,53 @@
+/**
+ * One field: its label over the control, a hint under it, and the problem
+ * it holds under that — in the control's own column, so saying a problem
+ * never narrows or moves the control (docs/design.md, Access).
+ *
+ * The wiring is the point. The control is handed its id, what describes it
+ * (the hint, the problem), `aria-invalid` while it holds a problem and
+ * `aria-required` beside the star, so no form has to remember to join them.
+ * A control that is one element takes them as props (`children` an element);
+ * one that is several — a listbox's button, a date and its calendar, a
+ * picker — takes them through `children` as a function and puts them where
+ * its focusable is.
+ */
+import { type ReactElement, type ReactNode } from 'react';
+export interface FieldControlProps {
+    id: string;
+    'aria-describedby'?: string;
+    'aria-invalid'?: true;
+    'aria-required'?: true;
+    /** A group's label is not a `<label>`: its control names itself by this. */
+    'aria-labelledby'?: string;
+}
+interface FieldProps {
+    label: ReactNode;
+    /** A sentence that helps before anything goes wrong. */
+    hint?: ReactNode;
+    /** What is wrong with the value now, in the reader's words. Empty or absent: nothing. */
+    problem?: ReactNode;
+    required?: boolean;
+    /** The control's id; one is made when not given. */
+    id?: string;
+    /** A control that is not one labelable element (radios, a listbox's button): the label is a caption the control points at. */
+    group?: boolean;
+    /** A checkbox: the control first and its label beside it, on one line, the label checking it. */
+    check?: boolean;
+    /** The word that says a field may be left empty ("(optional)"), in the caller's language. Given on every field that is
+        not required, it is drawn only where the worn theme asks for it (`recipes.required: 'optional-word'`, the
+        stylesheet's to decide) and replaces the star. It stands beside the label, not in it, so the label's name is the
+        same either way; `aria-required` is untouched. */
+    optional?: ReactNode;
+    /** The label is read, not drawn: a group whose question is the heading above it. */
+    labelHidden?: boolean;
+    /** Something beside the label on its row: a help tip. */
+    labelAside?: ReactNode;
+    /** Keep the problem's line in the flow while it is empty, so a problem that arrives moves nothing below it. */
+    reserve?: boolean;
+    /** Compact: a filter's or a dense row's size. */
+    size?: 'compact' | 'default';
+    className?: string;
+    children: ReactElement<Record<string, unknown>> | ((control: FieldControlProps) => ReactNode);
+}
+export declare function Field({ label, hint, problem, required, id, group, check, size, optional, labelAside, labelHidden, reserve, className, children, }: FieldProps): import("react").JSX.Element;
+export {};