@deriv-com/dds-marketing 0.1.0 → 0.2.0

package/dist/components/core/select/Select.js

@@ -0,0 +1,524 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Children, cloneElement, isValidElement, useEffect, useId, useRef, useState } from 'react';
+import { ChevronDownRegularIcon, CircleCheckSolidIcon, CircleExclamationSolidIcon, CircleInfoRegularIcon, TriangleExclamationSolidIcon, } from '@deriv-com/quill-icons-web';
+import './Select.css';
+import './select-impl.css';
+import { Icon } from '../icon/Icon.js';
+import { SearchInput } from '../search-input/SearchInput.js';
+import { Spinner } from '../spinner/Spinner.js';
+import { TooltipAnchor } from '../tooltip/TooltipAnchor.js';
+import { given } from '../../given.js';
+import { selectDefaults, selectGlyphStep, selectParts } from './Select.types.js';
+/**
+ * What each reported status looks like.
+ *
+ * The same marks TextInput draws, and the same argument: circle for error, triangle for
+ * warning, because the two colours are close enough that a red-green deficiency can converge
+ * them and the shape is what separates the pair at a glance. A form mixing these two controls
+ * cannot have them disagree about which shape means what.
+ *
+ * An exclamation rather than a cross, which is not interchangeable here: the cross is what
+ * SearchInput draws on its clear button, and this control holds a SearchInput whenever it is
+ * searchable. The same mark meaning "this failed" underneath and "press to empty" inside is
+ * one glyph doing two jobs in one component.
+ */
+const statusGlyph = {
+    none: null,
+    pending: null,
+    error: _jsx(CircleExclamationSolidIcon, {}),
+    warning: _jsx(TriangleExclamationSolidIcon, {}),
+    success: _jsx(CircleCheckSolidIcon, {}),
+};
+/**
+ * The answers, as a list this control can index.
+ *
+ * Levelled out of `children` rather than assumed to be an array: a set built from data arrives
+ * through a `.map()`, one written by hand may arrive in a fragment, and a set with a condition
+ * in it arrives with a `false` among the rows. `Children.toArray` flattens all three and drops
+ * the falsy entries, which is the whole reason to go through it rather than reading `children`.
+ */
+function optionsOf(children) {
+    return Children.toArray(children).filter((child) => isValidElement(child));
+}
+/**
+ * How long a run of keystrokes stays one search rather than starting the next.
+ *
+ * Half a second, which is roughly what a native select allows and comfortably longer than the gap
+ * between two letters somebody is typing on purpose. Too short and "si" becomes a search for "s"
+ * followed by a search for "i", which lands on whatever begins with I; too long and a letter
+ * pressed a beat later joins a word the reader had finished with.
+ *
+ * Compared as timestamps rather than cleared by a timer. There is nothing to cancel on unmount
+ * and nothing to get out of step with a re-render — the buffer is only ever read at the moment a
+ * key arrives, so the question is how old it is, not whether something has expired.
+ */
+const TYPING_WINDOW = 500;
+/**
+ * An option's words, flattened enough to match a letter against.
+ *
+ * An option is given text, but `allowedChildren` says text and React says ReactNode, so a set
+ * built from data can arrive holding numbers or nested fragments. Anything that is not a string
+ * or a number contributes nothing rather than throwing: a row nobody can type their way to is a
+ * smaller failure than a list that cannot render.
+ */
+function words(node) {
+    if (typeof node === 'string')
+        return node;
+    if (typeof node === 'number')
+        return String(node);
+    if (Array.isArray(node))
+        return node.map(words).join('');
+    return '';
+}
+/**
+ * A control for choosing one answer from a set the reader scans.
+ *
+ * Built as marketing's TextInput is built — a box that draws the border and the fill, and one
+ * element inside it holding the value — because that is what makes a form of mixed controls line
+ * up. The difference is the element inside: a text field's is an `<input>`, which can hold
+ * nothing, so its ornaments sit beside it and part of its box is not the field. Here it is a
+ * `<button>`, which can hold what it needs, so the whole box presses.
+ *
+ * Announced as a combobox, which is the name for a control that owns a list of answers whether
+ * or not anything can be typed into it. That role replaces the button's own activation on the
+ * way in, so Enter and Space are written here rather than inherited.
+ *
+ * Focus never leaves the box. Nothing here takes the caret — not even the search field, which is
+ * reachable with a pointer and otherwise fed from the box: every letter typed at the control goes
+ * into the query, so a keyboard never needs to be in the field to narrow the list. The rows are
+ * not focusable either, and the box says through `aria-activedescendant` which one the arrow keys
+ * are resting on; moving focus into the list would cost a tab stop per answer, which on a
+ * marketing page is a tab stop between the visitor and the button that submits the form.
+ *
+ * So Tab is one stop whether the list is open or shut. Open, it shuts the list on the way past
+ * rather than walking into the surface — the field and its clear button are furniture, and a
+ * reader tabbing out of a control has said they are done with it.
+ */
+export function Select(props) {
+    const { size = selectDefaults.size, status = selectDefaults.status, fixed = selectDefaults.fixed, label, labelTooltip, placeholder, helperText, value, defaultValue, onChange, open, defaultOpen, onOpenChange, searchable = selectDefaults.searchable, emptyLabel, required = selectDefaults.required, requiredMark = selectDefaults.requiredMark, optional = selectDefaults.optional, statusMessage, children, id, ...rest } = props;
+    const fallbackId = useId();
+    const rootId = id ?? fallbackId;
+    const labelId = `${rootId}-label`;
+    const listId = `${rootId}-list`;
+    const rowId = (index) => `${rootId}-option-${index}`;
+    const box = useRef(null);
+    const trigger = useRef(null);
+    /**
+     * The answer, and whether the list is showing — each held here only while nobody else holds it.
+     *
+     * `in` rather than a check against undefined: a page clearing its own answer passes an empty
+     * string and a page that never held one passes nothing. Reading those as the same thing makes a
+     * controlled control uncontrollable the moment it is emptied.
+     */
+    const owned = 'value' in props;
+    const [held, setHeld] = useState(defaultValue ?? '');
+    const chosen = owned ? (value ?? '') : held;
+    const driven = 'open' in props;
+    const [showing, setShowing] = useState(defaultOpen ?? false);
+    /**
+     * And never open while the control is unavailable.
+     *
+     * A browser refuses a press and a keystroke on a disabled button, so no handler here needs to
+     * check — but `defaultOpen` reaches past all of them: `<Select disabled defaultOpen>` would
+     * render a list hanging off a control nobody can use, from props alone and without an event.
+     * Read off `rest` rather than destructured, because the attribute still has to reach the button.
+     */
+    const unavailable = rest.disabled === true;
+    const expanded = !unavailable && !fixed && (driven ? (open ?? false) : showing);
+    const options = optionsOf(children);
+    /**
+     * What has been typed at the search field, which is not an answer and never becomes one.
+     *
+     * Held here alone. A query is not a value the page has any use for — it is how the visitor got
+     * to the row they took — so there is no controlled twin of it and nothing to report. Emptied
+     * when the list shuts, for the same reason: it was a way through the answers, and the answers
+     * have gone.
+     */
+    const [query, setQuery] = useState('');
+    /**
+     * The answers a query leaves, or all of them.
+     *
+     * `includes` rather than the `startsWith` type-ahead uses, and the two are different jobs: a
+     * letter pressed at the control is a jump to a row, so it matches from the beginning, where a
+     * query typed into a field is a filter, and a visitor typing "land" means to see Ireland as
+     * well as Iceland.
+     *
+     * Everything below indexes into this rather than into the whole set — the rows the arrow keys
+     * walk, the row Enter takes, the ids the list carries. An index into a set that is not the one
+     * on screen takes the answer next to the one the visitor was looking at.
+     */
+    const narrowed = (text) => {
+        const needle = text.trim().toLowerCase();
+        if (needle === '')
+            return options;
+        return options.filter((option) => words(option.props.children).toLowerCase().includes(needle));
+    };
+    const visible = searchable ? narrowed(query) : options;
+    const indexOf = (v) => visible.findIndex((option) => option.props.value === v);
+    /**
+     * Where the arrow keys are resting, which is not what has been chosen.
+     *
+     * Two facts, and the visitor needs both: what they answered, and what they are about to answer.
+     * Arrowing past the chosen row does not unchoose it, and opening puts the keys on the answer
+     * rather than at the top — somebody who has to find their own answer again before changing it
+     * has been made to do the work twice.
+     *
+     * An index rather than a value, so a set that repeats a value cannot light two rows at once.
+     */
+    const [activeIndex, setActiveIndex] = useState(-1);
+    /**
+     * What has been typed at the list, and when.
+     *
+     * A ref rather than state: nothing renders from it, and a keystroke has to read what the last
+     * one left within the same event rather than after a re-render. Held together in one object so
+     * the letters and their age cannot get out of step.
+     */
+    const typed = useRef({ text: '', at: 0 });
+    const setOpen = (next) => {
+        // Forgotten on the way out, so a list reopened later does not show a marker for a position
+        // the visitor is no longer in, nor continue a search they finished.
+        if (!next) {
+            setActiveIndex(-1);
+            typed.current = { text: '', at: 0 };
+            // The query goes with it. A list reopened on the last visitor's search would be a list
+            // missing most of its answers for a reason nothing on screen explains.
+            setQuery('');
+        }
+        if (!driven)
+            setShowing(next);
+        onOpenChange?.(next);
+    };
+    const openAt = (index) => {
+        setActiveIndex(index);
+        setOpen(true);
+    };
+    const take = (index) => {
+        const option = visible[index];
+        if (option === undefined || option.props.disabled === true)
+            return;
+        const next = option.props.value ?? '';
+        if (!owned)
+            setHeld(next);
+        onChange?.(next);
+        // And the focus with it. From the box this is where it already was; from the field, or from
+        // a press on a row while the caret was in the field, the popup is about to be unmounted with
+        // the focus inside it — which drops the reader on <body>, at the top of the page, from a
+        // control halfway down it. Escape and Tab both already did this; taking an answer, which is
+        // the ordinary way out, did not.
+        shutAndReturn();
+    };
+    /**
+     * The next row the keys can rest on, stepping over the ones that cannot be taken.
+     *
+     * Stepped over rather than stopped at. A row the keys land on and refuse is a dead end the
+     * visitor has to press through, and pressing down twice to move once reads as a control that
+     * is broken rather than one that is being careful. The rows stay in the list and stay
+     * readable — a set that hid what it will not accept would leave somebody hunting for
+     * something that was there last week.
+     */
+    const step = (from, by) => {
+        for (let i = 1; i <= visible.length; i += 1) {
+            const at = (from + by * i + visible.length * i) % visible.length;
+            if (visible[at]?.props.disabled !== true)
+                return at;
+        }
+        // Nothing can be rested on — an empty narrowed set, or every answer refused. -1 is the state
+        // a list nobody has moved in is already in, so no row is marked and Enter has nothing to
+        // take. Returning `from` instead handed `lastOpen` the length of the list, and
+        // `aria-activedescendant` then named a row id that was never rendered: a screen reader is
+        // told where it is and finds nothing there, which is worse than not being told.
+        return -1;
+    };
+    /**
+     * The first answer whose words begin with what has been typed, searched circularly.
+     *
+     * From `after` rather than from the top, which is what makes a letter pressed twice walk
+     * through the answers beginning with it instead of returning to the first one each time — the
+     * behaviour a native select has, and the reason type-ahead is usable on a list of countries
+     * at all.
+     *
+     * Refusals are skipped, for the reason the arrow keys skip them: landing on an answer that
+     * cannot be taken reads as the control being broken rather than as it being careful.
+     */
+    const matching = (run, after) => {
+        for (let i = 1; i <= visible.length; i += 1) {
+            const at = (after + i + visible.length * i) % visible.length;
+            const option = visible[at];
+            if (option?.props.disabled === true)
+                continue;
+            if (words(option?.props.children).trim().toLowerCase().startsWith(run))
+                return at;
+        }
+        return -1;
+    };
+    /**
+     * A query, and the row the keys should be resting on once it lands.
+     *
+     * The ring moves to the first answer the new query leaves rather than staying where it was.
+     * An index means nothing across two different sets — row three of "land" is not row three of
+     * "l" — and a ring left behind pointed at whatever had taken that position, which is the answer
+     * Enter would then have given.
+     *
+     * Nothing matching leaves it at -1, which is the same state as a list nobody has moved in: no
+     * row is marked, and Enter has nothing to take.
+     */
+    const narrow = (next) => {
+        setQuery(next);
+        setActiveIndex(narrowed(next).findIndex((option) => option.props.disabled !== true));
+    };
+    /**
+     * A letter, and what it means given what came just before it.
+     *
+     * One character repeated is a request for the next answer beginning with it, which is why the
+     * buffer collapses to a single letter in that case rather than searching for "ss". Anything
+     * else refines the run: typing "s" then "i" searches for "si" from where "s" landed, so the
+     * match narrows rather than jumping to whatever begins with I.
+     */
+    const typeAhead = (key) => {
+        /**
+         * Where there is a field, the letter is the start of a query rather than a jump to a row.
+         *
+         * Kept rather than dropped: somebody who presses S at a shut control has begun typing, and a
+         * control that opens a field and swallows the first letter is one they have to notice and
+         * type twice.
+         *
+         * Appended once the list is open, and only replacing the query on the press that opened it.
+         */
+        if (searchable) {
+            if (expanded)
+                narrow(query + key);
+            else {
+                setOpen(true);
+                narrow(key);
+            }
+            return;
+        }
+        const now = Date.now();
+        const run = now - typed.current.at > TYPING_WINDOW ? key : typed.current.text + key;
+        typed.current = { text: run, at: now };
+        const repeated = run.length > 1 && [...run].every((each) => each === run[0]);
+        const sought = (repeated ? run[0] : run).toLowerCase();
+        // A repeated letter walks on from where it is; a growing run re-reads from one before, so the
+        // answer it just landed on is still the first candidate. Floored at -1, or a run typed at a
+        // list nothing is resting on yet would start from -2 and skip the first answer — which is
+        // every list opened by `defaultOpen`.
+        const found = matching(sought, repeated ? activeIndex : Math.max(activeIndex - 1, -1));
+        if (found === -1)
+            return;
+        if (!expanded)
+            openAt(found);
+        else
+            setActiveIndex(found);
+    };
+    /**
+     * Back to the box, which is where the visitor was before the field took the caret.
+     *
+     * Focus cannot be left on an element that is about to be removed — the popup goes when the
+     * list shuts, and focus with it lands on the body, which is a reader dropped at the top of the
+     * page from a control halfway down it.
+     */
+    const shutAndReturn = () => {
+        setOpen(false);
+        trigger.current?.focus();
+    };
+    const firstOpen = () => step(-1, 1);
+    const lastOpen = () => step(visible.length, -1);
+    const onTheAnswer = () => (chosen === '' ? firstOpen() : indexOf(chosen));
+    /**
+     * A key that is a letter somebody typed, rather than a command.
+     *
+     * Space is excluded, and it has to be: here it does what Enter does, so a space that started a
+     * search would be a space that stopped taking the answer. Which costs nothing worth having —
+     * type-ahead is for the first few letters of a name, and nobody reaches a space before they
+     * have found what they were after.
+     *
+     * A modifier means the keystroke belongs to the browser or the operating system.
+     */
+    const printable = (event) => event.key.length === 1 && event.key !== ' ' && !event.ctrlKey && !event.metaKey;
+    const onKeyDown = (event) => {
+        const key = event.key;
+        if (!expanded) {
+            // All four open it, which is the whole of what a shut combobox does. Enter and Space are
+            // here rather than inherited, the role having replaced the button's own activation.
+            if (key === 'Enter' || key === ' ' || key === 'ArrowDown') {
+                event.preventDefault();
+                openAt(onTheAnswer());
+                return;
+            }
+            if (key === 'ArrowUp') {
+                event.preventDefault();
+                openAt(chosen === '' ? lastOpen() : indexOf(chosen));
+                return;
+            }
+            if (printable(event)) {
+                // Typing at a shut control opens it rather than answering it. A native select changes the
+                // value outright, which is how brushing a key while tabbing past one silently replaces an
+                // answer somebody already gave — the list opening on the match says the same thing and
+                // asks before committing to it.
+                event.preventDefault();
+                typeAhead(key);
+            }
+            return;
+        }
+        if (key === 'ArrowDown') {
+            event.preventDefault();
+            setActiveIndex(step(activeIndex, 1));
+        }
+        else if (key === 'ArrowUp') {
+            event.preventDefault();
+            setActiveIndex(step(activeIndex, -1));
+        }
+        else if (key === 'Home') {
+            event.preventDefault();
+            setActiveIndex(firstOpen());
+        }
+        else if (key === 'End') {
+            event.preventDefault();
+            setActiveIndex(lastOpen());
+        }
+        else if (key === 'Enter' || key === ' ') {
+            event.preventDefault();
+            take(activeIndex);
+        }
+        else if (key === 'Escape') {
+            // The answer is left alone. Escape is a visitor saying they did not mean to open the list,
+            // not that they have changed their mind about what they already answered.
+            event.preventDefault();
+            setOpen(false);
+        }
+        else if (key === 'Tab') {
+            // Not prevented, so the press carries on to the next field — but the list goes first.
+            // Without this, Tab from an open searchable box walks into the popup and stops on the
+            // search field and its clear button, with the list still open behind it. The rows are not
+            // tab stops by design; neither should the furniture above them be.
+            setOpen(false);
+        }
+        else if (key === 'Backspace' && searchable) {
+            // The counterpart to the letters above. Somebody typing at the box can see the query in the
+            // field and cannot reach it with the caret, so without this the only way back from a typo
+            // is the mouse — and a control that has to be corrected with the mouse is one the keyboard
+            // cannot finish.
+            event.preventDefault();
+            narrow(query.slice(0, -1));
+        }
+        else if (printable(event)) {
+            event.preventDefault();
+            typeAhead(key);
+        }
+    };
+    /**
+     * The same keys, read from the field instead of the box.
+     *
+     * Not the box's handler with a branch in it, because three of its keys mean something else in
+     * a field: Space types a space, and Home and End move the caret to the ends of the query —
+     * taking those would make the field a worse field than the one it replaced. What is left is
+     * the movement and the two ways out.
+     */
+    const onSearchKeyDown = (event) => {
+        const key = event.key;
+        if (key === 'ArrowDown') {
+            event.preventDefault();
+            setActiveIndex(step(activeIndex, 1));
+        }
+        else if (key === 'ArrowUp') {
+            event.preventDefault();
+            setActiveIndex(step(activeIndex, -1));
+        }
+        else if (key === 'Enter') {
+            event.preventDefault();
+            take(activeIndex);
+        }
+        else if (key === 'Escape') {
+            // The answer is left alone, as it is from the box.
+            event.preventDefault();
+            shutAndReturn();
+        }
+        else if (key === 'Tab') {
+            // Not prevented. The list shuts and the box takes the focus back, and the press the visitor
+            // made carries on from there — so Tab out of an open control lands on the next field, which
+            // is where it would have landed had the control been shut.
+            shutAndReturn();
+        }
+    };
+    /**
+     * Shutting on a press elsewhere, which is the only way out that is not a keystroke.
+     *
+     * Bound while open and unbound the moment it shuts, rather than left listening: one document
+     * handler per Select on a form of six is six of them running on every click anywhere on the
+     * page. `pointerdown` rather than `click`, so the list is gone before whatever was underneath
+     * it has moved.
+     */
+    useEffect(() => {
+        if (!expanded)
+            return;
+        const onPointerDown = (event) => {
+            if (box.current?.contains(event.target) === true)
+                return;
+            setOpen(false);
+        };
+        document.addEventListener('pointerdown', onPointerDown);
+        return () => document.removeEventListener('pointerdown', onPointerDown);
+    });
+    const checking = status === 'pending';
+    const reporting = status !== 'none';
+    const showsMessage = reporting && given(statusMessage);
+    const showsHelper = given(helperText) && !reporting;
+    const messageId = showsMessage ? `${rootId}-status` : showsHelper ? `${rootId}-helper` : undefined;
+    // Read off the whole set rather than the narrowed one: the box shows the answer that was
+    // given, and a query that happens not to match it does not unanswer the control.
+    const taken = chosen === '' ? undefined : options.find((option) => option.props.value === chosen);
+    return (_jsxs("div", { className: selectParts.root, 
+        /* The consumer's own, when they gave one, and a generated one when they did not. It was
+           being read for the child ids below and then applied to nothing, so `<Select id="country">`
+           put "country" on no element at all and any anchor or `getElementById` naming it found
+           nothing. */
+        id: rootId, "data-size": size, "data-status": status, "data-fixed": String(fixed), children: [_jsxs("div", { className: selectParts['label-row'], children: [_jsxs("span", { className: selectParts.label, id: labelId, children: [label, required ? (_jsx("span", { className: selectParts['required-mark'], "aria-hidden": "true", children: requiredMark === 'asterisk' ? '*' : 'required' })) : null, optional ? _jsx("span", { className: selectParts['optional-mark'], children: "optional" }) : null] }), given(labelTooltip) ? (_jsx(TooltipAnchor, { content: labelTooltip, placement: "top", children: _jsx("button", { type: "button", className: selectParts['label-tooltip'], "aria-label": `About ${label}`, children: _jsx(Icon, { size: selectGlyphStep[size], children: _jsx(CircleInfoRegularIcon, {}) }) }) })) : null] }), _jsxs("div", { className: selectParts.control, ref: box, children: [_jsxs("button", { ref: trigger, type: "button", className: selectParts.field, role: "combobox", "aria-labelledby": labelId, "aria-controls": listId, "aria-expanded": expanded, "aria-haspopup": "listbox", "aria-activedescendant": expanded && activeIndex !== -1 ? rowId(activeIndex) : undefined, "aria-invalid": status === 'error' || undefined, "aria-required": required || undefined, "aria-busy": checking || undefined, "aria-disabled": fixed || undefined, "aria-describedby": messageId, onClick: fixed ? undefined : () => (expanded ? setOpen(false) : openAt(onTheAnswer())), onKeyDown: fixed ? undefined : onKeyDown, ...rest, children: [_jsxs("span", { className: selectParts.answer, children: [taken?.props.leadingIcon, _jsx("span", { className: selectParts.value, "data-placeholder": taken === undefined || undefined, children: taken?.props.children ?? placeholder })] }), _jsx("span", { className: selectParts['trailing-icon'], "aria-hidden": "true", children: _jsx(Icon, { size: selectGlyphStep[size], children: _jsx(ChevronDownRegularIcon, { style: expanded ? { rotate: '180deg' } : undefined }) }) })] }), expanded ? (_jsxs("div", { className: selectParts.popup, children: [searchable ? (
+                            /* The field the answers are narrowed with, above them rather than in the box — a
+                               <ul> may hold options and little else, so this could not live in the list, and the
+                               box below is a button, which nothing can be typed into. */
+                            _jsx("div", { className: selectParts.search, children: _jsx(SearchInput
+                                /* The smallest step at every size of control, where a row takes the control's
+                                   own. The difference is what each one is: a row is an answer and has to read at
+                                   the size the form is set in, and this is the way to an answer — so a
+                                   touch-first Select spends its room on the answers rather than on the field
+                                   that finds them. */
+                                , { 
+                                    /* The smallest step at every size of control, where a row takes the control's
+                                       own. The difference is what each one is: a row is an answer and has to read at
+                                       the size the form is set in, and this is the way to an answer — so a
+                                       touch-first Select spends its room on the answers rather than on the field
+                                       that finds them. */
+                                    size: "sm", 
+                                    /* Named after the control it narrows, the way the label's own explanation is. A
+                                       second field inside a control, announced as nothing, is a box a screen reader
+                                       arrives at without being told what it is for. Clipped rather than drawn, which
+                                       is SearchInput's own default — the placeholder below carries the words for an
+                                       eye. */
+                                    label: `Search ${label}`, placeholder: `Search ${label}`, clearLabel: "Clear search", value: query, onChange: narrow, "aria-controls": listId, "aria-activedescendant": activeIndex === -1 ? undefined : rowId(activeIndex), onKeyDown: onSearchKeyDown }) })) : null, _jsx("ul", { className: selectParts.listbox, id: listId, role: "listbox", "aria-labelledby": labelId, children: visible.map((option, index) => cloneElement(option, {
+                                    key: option.props.value ?? index,
+                                    id: rowId(index),
+                                    /* Marketing's Option is drawn at two steps where this control has three, so a
+                                       large Select holds rows at the step below it. Which is the honest mapping
+                                       rather than a gap: `lg` is a touch-first box, and its rows are already the
+                                       largest an Option is cut for. */
+                                    size: size === 'sm' ? 'sm' : 'md',
+                                    selected: option.props.value === chosen && chosen !== '',
+                                    active: index === activeIndex,
+                                    // The row reports the press and the control decides what it means, which is why
+                                    // a row that cannot be taken still gets a handler: `take` refuses it in one
+                                    // place rather than every caller remembering to.
+                                    onClick: () => take(index),
+                                    // The pointer moves the ring, so there is one marker rather than two competing.
+                                    onMouseEnter: () => setActiveIndex(index),
+                                    // A press on a row must not take focus off the box. Without this the button
+                                    // blurs, `aria-activedescendant` stops meaning anything, and the handler above
+                                    // reads the press as having landed outside.
+                                    onMouseDown: (event) => event.preventDefault(),
+                                })) }), searchable ? (
+                            /* Here whenever the list can be narrowed, and shown only once it has been narrowed
+                               to nothing. A list that empties reads as a control that broke; a sentence in its
+                               place reads as an answer, and the visitor needs to know which before they know
+                               whether to keep typing. */
+                            _jsx("span", { className: selectParts.empty, "data-shown": visible.length === 0 || undefined, children: emptyLabel })) : null] })) : null] }), showsHelper ? (_jsx("span", { className: selectParts.helper, id: messageId, children: helperText })) : null, showsMessage ? (_jsxs("span", { className: selectParts.message, id: messageId, children: [_jsx("span", { className: selectParts['message-icon'], "aria-hidden": "true", children: checking ? (_jsx(Spinner, { size: "sm", variant: "inherit" })) : (_jsx(Icon, { size: "xs", children: statusGlyph[status] })) }), statusMessage] })) : null] }));
+}

package/dist/components/core/select/Select.types.d.ts

@@ -0,0 +1,96 @@
+import type { ButtonHTMLAttributes, ReactNode } from 'react';
+export interface SelectOwnProps {
+    /**
+     * `sm` — A filter row above an index, or a narrowing that sits in a bar rather than in a form. Desktop only: below what a finger reliably hits, which is why a filter row that has to work on a phone takes md
+     * `md` — The default, and what a marketing form wants. It matches TextInput at the same step, so a contact form's country field and its email field are the same height
+     * `lg` — A hero, a conversion band, or a form that is the whole point of the page. The step that pairs with a large Button, so the field and the thing that submits it agree
+     */
+    size?: 'sm' | 'md' | 'lg';
+    /** The answer is settled and still worth reading — a region a page was entered through, a plan a link arrived with. The box keeps its ink and its border and stops opening, so a reader can see what was answered without being invited to change it.
+  
+  Named for what it is rather than borrowed from the family. A text field says this with the platform's `readonly`, which the browser owns and enforces; there is no such attribute for a button, so this is the component's own. */
+    fixed?: boolean;
+    /** Always — a control with no label is unusable by a screen reader, and on a marketing page it is also the only thing telling a visitor what is being asked before they commit to opening it. A noun phrase naming the answer, in sentence case: "Country", not "Please choose your country" */
+    label: string;
+    /** A short explanation the label has no room for — why the answer is asked for, what it changes further down the form. Revealed on hover and on focus, so it costs no height */
+    labelTooltip?: string;
+    /** Always. What the box says with nothing chosen — an instruction rather than an example, there being nothing to spell: "Select a country". Required where a text field's is optional, and the difference is what an empty one looks like: an empty text field looks empty, while an empty box with a chevron looks like it might already hold something */
+    placeholder: string;
+    /** What the visitor needs to know before they choose — what the answer affects, or where to look if none of the options seem right. On a marketing form this is often the line that decides whether the field gets answered at all: "This only changes which prices we show you" removes a reason to abandon the page */
+    helperText?: string;
+    /** The chosen answer, when the consumer owns it — the controlled form. The value and not the words, so a page holds "sg" while the box shows "Singapore" and the words can be reworded or translated without changing what any form submits. Which matters more here than in an app: these pages are translated, and a value that travelled as its label would change meaning with the locale */
+    value?: string;
+    /** The answer the control starts on — a region guessed from where the visitor arrived, or a sort an index defaults to. Leave it out and the placeholder shows, which is what a set with no safe default wants */
+    defaultValue?: string;
+    /** Always, and it is required for that reason. It hands back the value of the answer taken, each time one is taken — the value rather than an event, there being no keystroke here to read one off. It is also the only way the answer reaches the page: this draws a button rather than a <select>, so there is no form control for a browser to submit on its own */
+    onChange: (value: string) => void;
+    /** Whether the list is showing, when the consumer owns that too. Left out, the control opens and shuts itself, which is what almost every page wants */
+    open?: boolean;
+    /** Open on first render. For a documentation page or a specimen that has to show the list without anybody pressing anything — not for a page a visitor lands on, where a list that opens by itself covers whatever is under it */
+    defaultOpen?: boolean;
+    /** Told when the list opens and shuts, for a page that has to react — closing something else, or holding a scroll position */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * `text` — Short forms, public ones, and anywhere the label row has room. The safer default and the right one for nearly every marketing form: it needs nothing looked up and still means something read out of context
+     * `asterisk` — Long or dense forms where the word repeats down the page and one legend can say it once instead. Only where that legend is visible from the fields it governs
+     */
+    requiredMark?: 'text' | 'asterisk';
+    /** Allowed: Option */
+    children: ReactNode;
+}
+export type SelectProps = SelectOwnProps & Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'className' | 'size' | 'status' | 'fixed' | 'label' | 'labelTooltip' | 'placeholder' | 'helperText' | 'value' | 'defaultValue' | 'onChange' | 'open' | 'defaultOpen' | 'onOpenChange' | 'searchable' | 'emptyLabel' | 'required' | 'requiredMark' | 'optional' | 'statusMessage'> & ({
+    required?: boolean;
+    optional?: false;
+} | {
+    required?: false;
+    optional?: boolean;
+}) & ({
+    status?: 'none' | 'pending' | 'error' | 'warning' | 'success';
+    statusMessage: string;
+} | {
+    status?: Exclude<'none' | 'pending' | 'error' | 'warning' | 'success', 'error' | 'warning' | 'pending'>;
+    statusMessage?: string;
+}) & ({
+    searchable?: boolean;
+    emptyLabel: string;
+} | {
+    searchable?: false;
+    emptyLabel?: string;
+});
+/** The class each part carries. Apply these — do not retype them. */
+export declare const selectParts: {
+    readonly root: "dds-select";
+    readonly 'label-row': "dds-select__label-row";
+    readonly label: "dds-select__label";
+    readonly 'label-tooltip': "dds-select__label-tooltip";
+    readonly 'required-mark': "dds-select__required-mark";
+    readonly 'optional-mark': "dds-select__optional-mark";
+    readonly control: "dds-select__control";
+    readonly field: "dds-select__field";
+    readonly answer: "dds-select__answer";
+    readonly value: "dds-select__value";
+    readonly 'trailing-icon': "dds-select__trailing-icon";
+    readonly popup: "dds-select__popup";
+    readonly search: "dds-select__search";
+    readonly listbox: "dds-select__listbox";
+    readonly empty: "dds-select__empty";
+    readonly helper: "dds-select__helper";
+    readonly message: "dds-select__message";
+    readonly 'message-icon': "dds-select__message-icon";
+};
+/** Generated so defaults cannot drift from the contract. */
+export declare const selectDefaults: {
+    readonly size: "md";
+    readonly status: "none";
+    readonly fixed: false;
+    readonly searchable: false;
+    readonly required: false;
+    readonly requiredMark: "text";
+    readonly optional: false;
+};
+/** The step this component draws a glyph slot at. Generated — do not retype. */
+export declare const selectGlyphStep: {
+    readonly sm: "xs";
+    readonly md: "sm";
+    readonly lg: "sm";
+};

package/dist/components/core/select/Select.types.js

@@ -0,0 +1,26 @@
+// GENERATED from select.contract.json. Do not edit.
+/** The class each part carries. Apply these — do not retype them. */
+export const selectParts = {
+    root: 'dds-select',
+    'label-row': 'dds-select__label-row',
+    label: 'dds-select__label',
+    'label-tooltip': 'dds-select__label-tooltip',
+    'required-mark': 'dds-select__required-mark',
+    'optional-mark': 'dds-select__optional-mark',
+    control: 'dds-select__control',
+    field: 'dds-select__field',
+    answer: 'dds-select__answer',
+    value: 'dds-select__value',
+    'trailing-icon': 'dds-select__trailing-icon',
+    popup: 'dds-select__popup',
+    search: 'dds-select__search',
+    listbox: 'dds-select__listbox',
+    empty: 'dds-select__empty',
+    helper: 'dds-select__helper',
+    message: 'dds-select__message',
+    'message-icon': 'dds-select__message-icon',
+};
+/** Generated so defaults cannot drift from the contract. */
+export const selectDefaults = { size: 'md', status: 'none', fixed: false, searchable: false, required: false, requiredMark: 'text', optional: false };
+/** The step this component draws a glyph slot at. Generated — do not retype. */
+export const selectGlyphStep = { sm: 'xs', md: 'sm', lg: 'sm' };