@nanisoft/prism-ui 0.13.0 → 0.15.0

package/dist/components/ui/money-field.d.ts

@@ -0,0 +1,200 @@
+import { type FocusEventHandler } from 'react';
+/**
+ * The props the Money field accepts.
+ *
+ * A declared interface rather than a forwarded native one, and the reason is the
+ * gate on the surface rather than a preference: a forwarded `value` and
+ * `onChange` would be a second way to say what the field holds, and `value` here
+ * is a number while the DOM's is a string, so forwarding the native pair would
+ * make it possible to pass a string where a number belongs. The native attributes
+ * a money field genuinely needs are named individually below.
+ */
+export interface MoneyFieldProps {
+    /**
+     * The amount, as a number.
+     *
+     * Required and controlled, and a number rather than a string for the whole
+     * reason this Component exists: the value the caller holds and the value the
+     * reader sees are different kinds of thing, and only one of them is arithmetic.
+     * `null` means the field is empty, which is a different fact from zero and is
+     * reported as `null` rather than as a number the reader never typed.
+     */
+    value: number | null;
+    /**
+     * Called with the amount the reader's text currently parses to.
+     *
+     * Required, and called on every keystroke rather than on blur, because a form
+     * that learns the amount only when the reader leaves the field has already lost
+     * the reason to keep the text at all. It is called with `null` when the text
+     * holds no amount yet, which includes a partially typed one: `12.`, `-` and `.5`
+     * are all legitimate states of a field somebody is typing into, and reporting
+     * them as a number would report a number the reader did not mean.
+     */
+    onValueChange: (value: number | null) => void;
+    /**
+     * The locale the amount is written in.
+     *
+     * Required, because a locale is a claim about the caller's market and this
+     * Component may not guess one. It decides the grouping separator, the decimal
+     * separator, and how many fraction digits the currency has: `1.234,56` in
+     * `de-DE` and `1,234.56` in `en-US` are the same amount typed two ways, and a
+     * Component that hardcoded either one would be wrong for every reader in the
+     * other half of the world.
+     */
+    locale: Intl.LocalesArgument;
+    /**
+     * The currency, as an ISO 4217 code.
+     *
+     * Required, and a code rather than a symbol for three reasons: the symbol is
+     * read back out of the platform so no two products can disagree about it, a code
+     * is the one currency name every product already holds, and a symbol as an input
+     * would be an input that cannot be validated. `Intl` throws on a code it does not
+     * recognise, which is the right place for that error.
+     */
+    currency: string;
+    /**
+     * The field's own id, so a `Label` elsewhere can point at it.
+     *
+     * A native attribute forwarded untouched, because an id is a fact about the
+     * caller's form rather than about this Component.
+     */
+    id?: string;
+    /**
+     * The field's accessible name, when no visible label is used.
+     *
+     * Optional and not defaulted, because the visible label is the ordinary answer
+     * and a defaulted name here would be the English Prism guessed in place of the
+     * caller's own word.
+     */
+    'aria-label'?: string;
+    /**
+     * What the reader is expected to do with the amount.
+     *
+     * Forwarded rather than drawn, so a form can describe the field in one sentence
+     * a screen reader will reach. There is no `name`: a money field submits the text
+     * the reader typed, with this locale's punctuation in it, and a caller who needs
+     * a numeric submit owns a hidden input holding the number.
+     */
+    describedBy?: string;
+    /** Whether the reader may not change the amount. */
+    readOnly?: boolean;
+    /** Whether the field ignores interaction. */
+    disabled?: boolean;
+    /**
+     * Whether an amount must be entered.
+     *
+     * Announced on the field as `aria-required` rather than enforced by the browser's
+     * own `required`, for the same reason the JSDoc on `onBlur` matters: the browser
+     * refuses to submit with a message in English, and this Component may not choose
+     * a word for the reader. Enforce it in the caller's own submit handler, where it
+     * can be said in the caller's language.
+     */
+    required?: boolean;
+    /**
+     * The keyboard the field asks for. @defaultValue 'decimal'
+     *
+     * A `decimal` keyboard is the one with the separator a money field needs, and it
+     * is the default because a `numeric` keyboard on a phone has no decimal point at
+     * all. Override it for a market that types amounts some other way; the parser
+     * reads whatever the reader produced.
+     */
+    inputMode?: 'none' | 'text' | 'tel' | 'url' | 'email' | 'numeric' | 'decimal';
+    /**
+     * Called when the reader leaves the field, after the text has been re-formatted.
+     *
+     * Forwarded rather than drawn, and last in the Component's own handler on
+     * purpose: a caller's handler runs against a field that has already settled,
+     * so a validation that reads the field at that moment reads what the reader is
+     * looking at and not the keystrokes they are leaving behind.
+     */
+    onBlur?: FocusEventHandler<HTMLInputElement>;
+    /** Layout only. Changing a Prism-owned visual property from here is prohibited. */
+    className?: string;
+}
+/**
+ * A field that holds a currency amount as a number and shows it as the reader's
+ * market writes it.
+ *
+ * **The number the caller holds and the string the reader sees are different
+ * kinds of thing, and the round trip between them is the Component.** Everything
+ * else here follows from that. The caller passes a `number` and gets a `number`
+ * back; the field draws the platform's own rendering of that number in the
+ * caller's locale and the caller's currency; and every character the reader adds
+ * is parsed back into one. A field that handed the caller a string would push the
+ * parsing into every consumer, and a field that printed a hardcoded `$1,234.56`
+ * would be making three claims about every product that installed it.
+ *
+ * **The currency symbol is an input and not an output, and the difference is the
+ * whole of the composition.** It sits in the field's own frame, drawn by
+ * `InputGroupAddon`, read out of `Intl.NumberFormat` rather than written here, and
+ * it is hidden from the accessibility tree: a screen reader reads the digits, and
+ * the currency belongs in the field's accessible name, which is the caller's
+ * word. It is also not part of the value. The number a caller holds is `1234.56`
+ * whatever the reader sees on screen, and a symbol that leaked into the parse would
+ * make the same amount parse two ways depending on whether the reader typed it.
+ *
+ * **Nothing about a currency may be a literal in this file.** The symbol, the
+ * grouping and the decimal separators, and the number of fraction digits all come
+ * out of the platform for the locale and the code the caller passed. `de-DE` with
+ * `EUR` and `en-US` with `USD` differ in all four, and a Component that hardcoded
+ * any of them would be right for one market and silently wrong for the rest.
+ *
+ * **A partially typed amount is a legitimate state and the parser must not reject
+ * it.** `12.`, `-` and `.5` are all things a person is in the middle of typing,
+ * and `12,` and `,5` are the same three in a locale that separates with a comma.
+ * So the parser is not asked whether the text is a valid amount, only whether it
+ * currently means one: it reports `12` for `12.`, it reports nothing for a lone sign
+ * and for a lone separator, and it reports `0.5` for `.5`. And the text is never
+ * rewritten while the field has focus, because a field that re-formats under the
+ * reader moves the caret and eats the character being typed. That is what makes the
+ * states survivable at all.
+ *
+ * **The two values disagree for the whole of a mid-edit, and the Component
+ * resolves it in one direction.** The caller's number is always the parse of the
+ * text, and the text is never rewritten until the reader leaves. So a consumer
+ * that also renders the amount somewhere else on the page sees the parsed value and
+ * not the keystrokes, and that is deliberate: a second rendering of an amount
+ * mid-edit is a second thing to keep in step with a third. The cost is that a
+ * consumer whose own validation depends on the exact characters cannot get them
+ * from here; it gets the number, which is the thing worth validating.
+ *
+ * **On blur the text is re-formatted, and text that is not an amount is refused.**
+ * The reader leaves and the field holds what the platform writes for the number it
+ * parsed: grouped where this locale groups, padded to this currency's fraction
+ * digits, and with the grouping the reader did not type replaced by the grouping
+ * the reader's market uses. If the text held nothing that means an amount at all,
+ * the field restores the canonical rendering of the caller's own value and reports
+ * `null`. **That refusal has a real cost, and it is the cost of a snapped-back
+ * keystroke**: a reader who typed something this locale cannot write loses what
+ * they typed rather than being told it was wrong. The alternative is to keep the
+ * text and mark the field invalid, which needs an error this Component cannot
+ * render and a `required` rule this Component cannot judge. Refusing it here means
+ * an amount field never holds something that is not an amount, which is the
+ * strongest claim available; a caller who would rather explain the problem says so
+ * in their own `FieldError` beside a `value` of `null`.
+ *
+ * **A pasted amount from another market is read with this market's punctuation,
+ * and there is no better answer available.** `1,234.56` pasted into a `de-DE`
+ * field is `1.23456` here, because `,` is this locale's decimal separator. A
+ * Component that guessed the other way round would be guessing about money from a
+ * string with no locale in it, so it does not: pass the number in, and let the
+ * field format it. Grouping characters survive nothing either way, because
+ * dropping one leaves the same digits.
+ *
+ * **A `name` is deliberately absent, and the omission is the honest one.** What a
+ * form would submit from here is the reader's text, with this locale's separators
+ * in it, and a server that parses it has to guess the same things this Component
+ * guessed. A caller who needs a numeric submit writes a hidden input holding
+ * `value`. That is two lines, and it is better than a Component that submits a
+ * string and calls it a number.
+ *
+ * **It is a client Component**, because it holds the text while the reader is
+ * typing and because it takes the callback that carries the parse. What that
+ * costs is the price of every form control, and it is worth naming because the
+ * Component looks like a text input: a server render draws the canonical rendering
+ * of the caller's number, which is right, and cannot report a keystroke, which is
+ * also right.
+ */
+declare function MoneyField({ value, onValueChange, locale, currency, id, 'aria-label': ariaLabel, describedBy, readOnly, disabled, required, inputMode, onBlur: onBlurProp, className, }: MoneyFieldProps): import("react").JSX.Element;
+export { MoneyField };
+//# sourceMappingURL=money-field.d.ts.map

package/dist/components/ui/money-field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"money-field.d.ts","sourceRoot":"","sources":["../../../src/components/ui/money-field.tsx"],"names":[],"mappings":"AAEA,OAAO,EAKL,KAAK,iBAAiB,EAEvB,MAAM,OAAO,CAAA;AAKd;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;OAQG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;;;;;;;OASG;IACH,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IAC7C;;;;;;;;;OASG;IACH,MAAM,EAAE,IAAI,CAAC,eAAe,CAAA;IAC5B;;;;;;;;OAQG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,EAAE,CAAC,EAAE,MAAM,CAAA;IACX;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAA;IAC7E;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC,gBAAgB,CAAC,CAAA;IAC5C,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAqGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AACH,iBAAS,UAAU,CAAC,EAClB,KAAK,EACL,aAAa,EACb,MAAM,EACN,QAAQ,EACR,EAAE,EACF,YAAY,EAAE,SAAS,EACvB,WAAW,EACX,QAAgB,EAChB,QAAgB,EAChB,QAAgB,EAChB,SAAqB,EACrB,MAAM,EAAE,UAAU,EAClB,SAAS,GACV,EAAE,eAAe,+BAiEjB;AAED,OAAO,EAAE,UAAU,EAAE,CAAA"}

package/dist/components/ui/money-field.js

@@ -0,0 +1,215 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo, useState, } from 'react';
+import { InputGroup, InputGroupAddon, InputGroupInput } from './input-group.js';
+/**
+ * Everything one locale and one currency say about the shape of an amount.
+ *
+ * Memoised on the two props that decide it and not read per keystroke, because
+ * building three `Intl.NumberFormat` objects on every character typed is a cost
+ * with no reader attached, and the answer cannot change while the locale and the
+ * currency do not.
+ */
+function readCurrency(locale, currency) {
+    // The currency formatter is the only thing that knows how this currency is
+    // written: where the symbol sits, how many fraction digits it has, and which
+    // characters are its own.
+    const money = new Intl.NumberFormat(locale, { style: 'currency', currency });
+    const symbol = money
+        .formatToParts(0)
+        .find((part) => part.type === 'currency')
+        ?.value ?? currency;
+    const { minimumFractionDigits, maximumFractionDigits } = money.resolvedOptions();
+    // The digits come from a decimal formatter carrying the currency's own fraction
+    // digits, so the amount is grouped and padded the way this currency is padded
+    // and carries no symbol, because the symbol is already in the field's frame.
+    const digits = new Intl.NumberFormat(locale, { minimumFractionDigits, maximumFractionDigits });
+    // The decimal separator, taken from a value that has one. `undefined` is a real
+    // answer and not a gap: a locale whose numbers are written without a fractional
+    // part has no decimal separator to accept and none is offered to the reader.
+    const marks = new Intl.NumberFormat(locale).formatToParts(1.5);
+    const separator = marks.find((part) => part.type === 'decimal')?.value;
+    /*
+     * The characters this locale's own formatter could have produced.
+     *
+     * Grouping is deliberately absent. A group separator is cosmetic, and dropping
+     * one leaves the same digits, which is exactly the amount the reader meant. So a
+     * reader typing `1,234.56` into `en-US` and a reader typing `1.234,56` into
+     * `de-DE` both end up with a field holding the number they wanted, and neither
+     * has to be told which characters their market uses to write it.
+     */
+    const allowed = new Set('0123456789-');
+    for (const character of separator ?? '')
+        allowed.add(character);
+    for (const character of symbol)
+        allowed.add(character);
+    return { symbol, digits, separator, allowed };
+}
+/** What is left after the allowed set has had its turn, which is what can be typed. */
+function filterAmount(text, allowed) {
+    let out = '';
+    for (const character of text) {
+        if (allowed.has(character))
+            out += character;
+    }
+    return out;
+}
+const DIGITS_ONLY = /^[0-9]+$/;
+/**
+ * The number the reader's text means, or nothing.
+ *
+ * `null` is the honest answer in four distinct cases and the Component does not
+ * distinguish them for the caller, because none of them is an amount: the field is
+ * empty, the field holds only a sign, the field holds only the separator, and the
+ * field holds something that is not an amount at all. The text is never rewritten
+ * in response, so all four are visible to the reader as states of a field they are
+ * in the middle of typing into.
+ */
+function readAmount(text, separator, symbol) {
+    let body = '';
+    for (const character of text) {
+        // The currency symbol is dropped wherever it appears rather than only at the
+        // front, because a reader pasting a formatted amount gets whatever order their
+        // source wrote it in.
+        if (symbol !== '' && symbol.includes(character))
+            continue;
+        body += character;
+    }
+    const negative = body.startsWith('-');
+    if (negative)
+        body = body.slice(1);
+    if (body === '')
+        return null;
+    const halves = separator === undefined ? [body] : body.split(separator);
+    // More than one separator is not a partially typed amount, it is a different
+    // number, and guessing which separator was meant is a guess about money.
+    if (halves.length > 2)
+        return null;
+    let [whole, fraction = ''] = halves;
+    // A separator with no whole part is that many units. The reader who typed the
+    // separator first is at the beginning of an amount, not at the end of one.
+    if (whole === '' && fraction !== '')
+        whole = '0';
+    if (!DIGITS_ONLY.test(whole))
+        return null;
+    if (fraction !== '' && !DIGITS_ONLY.test(fraction))
+        return null;
+    const amount = Number(`${whole}.${fraction}`);
+    if (!Number.isFinite(amount))
+        return null;
+    return negative ? -amount : amount;
+}
+/**
+ * A field that holds a currency amount as a number and shows it as the reader's
+ * market writes it.
+ *
+ * **The number the caller holds and the string the reader sees are different
+ * kinds of thing, and the round trip between them is the Component.** Everything
+ * else here follows from that. The caller passes a `number` and gets a `number`
+ * back; the field draws the platform's own rendering of that number in the
+ * caller's locale and the caller's currency; and every character the reader adds
+ * is parsed back into one. A field that handed the caller a string would push the
+ * parsing into every consumer, and a field that printed a hardcoded `$1,234.56`
+ * would be making three claims about every product that installed it.
+ *
+ * **The currency symbol is an input and not an output, and the difference is the
+ * whole of the composition.** It sits in the field's own frame, drawn by
+ * `InputGroupAddon`, read out of `Intl.NumberFormat` rather than written here, and
+ * it is hidden from the accessibility tree: a screen reader reads the digits, and
+ * the currency belongs in the field's accessible name, which is the caller's
+ * word. It is also not part of the value. The number a caller holds is `1234.56`
+ * whatever the reader sees on screen, and a symbol that leaked into the parse would
+ * make the same amount parse two ways depending on whether the reader typed it.
+ *
+ * **Nothing about a currency may be a literal in this file.** The symbol, the
+ * grouping and the decimal separators, and the number of fraction digits all come
+ * out of the platform for the locale and the code the caller passed. `de-DE` with
+ * `EUR` and `en-US` with `USD` differ in all four, and a Component that hardcoded
+ * any of them would be right for one market and silently wrong for the rest.
+ *
+ * **A partially typed amount is a legitimate state and the parser must not reject
+ * it.** `12.`, `-` and `.5` are all things a person is in the middle of typing,
+ * and `12,` and `,5` are the same three in a locale that separates with a comma.
+ * So the parser is not asked whether the text is a valid amount, only whether it
+ * currently means one: it reports `12` for `12.`, it reports nothing for a lone sign
+ * and for a lone separator, and it reports `0.5` for `.5`. And the text is never
+ * rewritten while the field has focus, because a field that re-formats under the
+ * reader moves the caret and eats the character being typed. That is what makes the
+ * states survivable at all.
+ *
+ * **The two values disagree for the whole of a mid-edit, and the Component
+ * resolves it in one direction.** The caller's number is always the parse of the
+ * text, and the text is never rewritten until the reader leaves. So a consumer
+ * that also renders the amount somewhere else on the page sees the parsed value and
+ * not the keystrokes, and that is deliberate: a second rendering of an amount
+ * mid-edit is a second thing to keep in step with a third. The cost is that a
+ * consumer whose own validation depends on the exact characters cannot get them
+ * from here; it gets the number, which is the thing worth validating.
+ *
+ * **On blur the text is re-formatted, and text that is not an amount is refused.**
+ * The reader leaves and the field holds what the platform writes for the number it
+ * parsed: grouped where this locale groups, padded to this currency's fraction
+ * digits, and with the grouping the reader did not type replaced by the grouping
+ * the reader's market uses. If the text held nothing that means an amount at all,
+ * the field restores the canonical rendering of the caller's own value and reports
+ * `null`. **That refusal has a real cost, and it is the cost of a snapped-back
+ * keystroke**: a reader who typed something this locale cannot write loses what
+ * they typed rather than being told it was wrong. The alternative is to keep the
+ * text and mark the field invalid, which needs an error this Component cannot
+ * render and a `required` rule this Component cannot judge. Refusing it here means
+ * an amount field never holds something that is not an amount, which is the
+ * strongest claim available; a caller who would rather explain the problem says so
+ * in their own `FieldError` beside a `value` of `null`.
+ *
+ * **A pasted amount from another market is read with this market's punctuation,
+ * and there is no better answer available.** `1,234.56` pasted into a `de-DE`
+ * field is `1.23456` here, because `,` is this locale's decimal separator. A
+ * Component that guessed the other way round would be guessing about money from a
+ * string with no locale in it, so it does not: pass the number in, and let the
+ * field format it. Grouping characters survive nothing either way, because
+ * dropping one leaves the same digits.
+ *
+ * **A `name` is deliberately absent, and the omission is the honest one.** What a
+ * form would submit from here is the reader's text, with this locale's separators
+ * in it, and a server that parses it has to guess the same things this Component
+ * guessed. A caller who needs a numeric submit writes a hidden input holding
+ * `value`. That is two lines, and it is better than a Component that submits a
+ * string and calls it a number.
+ *
+ * **It is a client Component**, because it holds the text while the reader is
+ * typing and because it takes the callback that carries the parse. What that
+ * costs is the price of every form control, and it is worth naming because the
+ * Component looks like a text input: a server render draws the canonical rendering
+ * of the caller's number, which is right, and cannot report a keystroke, which is
+ * also right.
+ */
+function MoneyField({ value, onValueChange, locale, currency, id, 'aria-label': ariaLabel, describedBy, readOnly = false, disabled = false, required = false, inputMode = 'decimal', onBlur: onBlurProp, className, }) {
+    const { symbol, digits, separator, allowed } = useMemo(() => readCurrency(locale, currency), [locale, currency]);
+    // The text while it is being typed, and `null` when it is not. A separate value
+    // from the caller's is the whole mechanism: a field whose displayed text is
+    // derived from a number on every render cannot hold `12.` without rewriting it.
+    const [draft, setDraft] = useState(null);
+    const canonical = value === null || !Number.isFinite(value) ? '' : digits.format(value);
+    const text = draft === null ? canonical : draft;
+    const handleChange = (event) => {
+        const next = filterAmount(event.target.value, allowed);
+        setDraft(next);
+        onValueChange(readAmount(next, separator, symbol));
+    };
+    const handleBlur = (event) => {
+        // A field nobody edited is not a field that resolved. Without this a reader who
+        // tabbed through a field holding an amount would have that amount reported as
+        // `null` on the way out, because an untouched field has no draft to re-formatted.
+        if (draft !== null) {
+            // The one place the text is rewritten, and the one place the parse is reported
+            // a second time: whatever parsed is what the reader is left looking at.
+            onValueChange(readAmount(draft, separator, symbol));
+            setDraft(null);
+        }
+        // Forwarded last, so a caller's own handler runs against a field that has
+        // already settled rather than one caught mid-transition.
+        onBlurProp?.(event);
+    };
+    return (_jsxs(InputGroup, { className: className, disabled: disabled, children: [_jsx(InputGroupAddon, { position: "prefix", children: _jsx("span", { "data-slot": "money-field-symbol", "aria-hidden": "true", children: symbol }) }), _jsx(InputGroupInput, { "data-slot": "money-field-input", id: id, type: "text", inputMode: inputMode, autoComplete: "off", spellCheck: false, "aria-label": ariaLabel, "aria-describedby": describedBy, "aria-required": required || undefined, readOnly: readOnly, disabled: disabled, value: text, onChange: handleChange, onBlur: handleBlur })] }));
+}
+export { MoneyField };

package/dist/components/ui/multi-combobox.d.ts

@@ -0,0 +1,181 @@
+import type { ComboboxItem } from './combobox.js';
+/** The props the Multi combobox accepts. */
+export interface MultiComboboxProps {
+    /**
+     * The accessible name of the field.
+     *
+     * Required, and required as a name rather than as a placeholder, for the reason
+     * `Combobox` requires it: a placeholder disappears the moment the reader types,
+     * which leaves a field holding a row of chips with no name at exactly the moment
+     * the reader most needs to know what they are filtering.
+     */
+    label: string;
+    /**
+     * The options.
+     *
+     * `ComboboxItem` rather than a second option type, because the shape is one fact
+     * about an option and not one fact about the number of options it appears in. A
+     * copy would drift the first time a field grew a `keywords` member.
+     */
+    items: readonly ComboboxItem[];
+    /** The chosen values, when the field is controlled. */
+    value?: readonly string[];
+    /** The values chosen initially, for an uncontrolled field. */
+    defaultValue?: readonly string[];
+    /**
+     * Called with every chosen value, in the order they were chosen.
+     *
+     * The whole set rather than the one value that changed, because there is no one
+     * value: a toggle is an edit of a set and the caller is the only party that can
+     * decide whether the form submits an array or a joined string.
+     */
+    onValueChange?: (value: readonly string[]) => void;
+    /**
+     * The accessible name of one chip's remove control, given that chip's label.
+     *
+     * Required rather than optional, which is the one place this Component is less
+     * forgiving than `TagGroup`. A multi combobox that cannot deselect is not a
+     * multi combobox, so the remove control is always drawn, so its name is always
+     * needed, and an optional prop would be a prop whose absence is always a mistake.
+     */
+    removeLabel: (label: string) => string;
+    /** What a reader is told when the query matches nothing. */
+    empty: {
+        message: (query: string) => string;
+        hint?: string;
+    };
+    /**
+     * The most values that may be chosen at once.
+     *
+     * Omit it and the set is unbounded. Given one, an option that is not yet chosen
+     * becomes `aria-disabled` and the arrows step over it once the cap is reached,
+     * and the select-all control announces itself as unavailable rather than
+     * quietly choosing fewer than it says it will.
+     */
+    max?: number;
+    /**
+     * Draws a control that chooses every option the query currently matches, and
+     * returns its accessible name given how many match.
+     *
+     * A function of a count rather than a string because the count is the whole
+     * content of the name, and it is a count of the caller's options rather than one
+     * this Component holds.
+     */
+    selectAll?: (matching: number) => string;
+    /**
+     * Draws a control that drops every chosen value, and returns its accessible name
+     * given how many are chosen.
+     */
+    clearAll?: (chosen: number) => string;
+    /**
+     * Whether the trigger shows how many values are chosen.
+     *
+     * A number and not a sentence, and it is hidden from assistive technology. The
+     * chosen values are already announced, one chip at a time, through the field's
+     * description, so a bare number adds a figure with no noun to read out loud.
+     */
+    showCount?: boolean;
+    /** The placeholder in the search field. The caller's word. */
+    placeholder?: string;
+    /** Whether the list is open, when the field is controlled. */
+    open?: boolean;
+    /** Whether the list starts open, for an uncontrolled field. */
+    defaultOpen?: boolean;
+    /** Called when the list opens or closes. */
+    onOpenChange?: (open: boolean) => void;
+    /** Whether the field ignores interaction. */
+    disabled?: boolean;
+    /** Whether at least one value must be chosen before the form submits. */
+    required?: boolean;
+    /**
+     * The form field name each chosen value is submitted under.
+     *
+     * One hidden input per value, all carrying this name, because a form has no way
+     * to submit an array and a joined string is a decision the caller makes.
+     */
+    name?: string;
+    /** Identifies the form that owns the hidden inputs. */
+    form?: string;
+    /** The field's own id, so a label elsewhere can point at it. */
+    id?: string;
+    /** Identifies the element that describes the field. */
+    'aria-describedby'?: string;
+    /** Layout only. */
+    className?: string;
+}
+/**
+ * A field that searches one list and toggles as many of its options as the reader
+ * wants, with the chosen ones visible as chips in the trigger.
+ *
+ * **The value is an array, and that is not a prop combination.** Every sibling in
+ * this family commits one value: `Combobox` closes on a choice, `Select` closes on
+ * a choice, `NativeSelect` submits one value. Turning one of those into this one
+ * is not a boolean. A single-value control closes on commit because the answer is
+ * finished; here the answer is a set that keeps growing after every commit, so
+ * closing on commit makes the second choice a re-open, and a reader choosing six
+ * regions opens the field six times and retypes the query five of them. The state
+ * machine is different, not configured differently, which is the test
+ * `DESIGN.md` states: a member of a family that differs from its siblings only by a
+ * prop every one of them already takes is a call site.
+ *
+ * **Space and Enter toggle, and the list stays open.** This inverts the commit
+ * contract the single-select siblings are built on, and the inversion is the whole
+ * reason the two surfaces feel nothing alike. In a combobox, Enter ends the
+ * interaction; here it is one more toggle, and closing the list on it would make
+ * choosing a second value a two-keystroke act for no reason a reader can see. So
+ * the keys that close a single-select field are the keys that add to the set, and
+ * Escape, a blur and Tab are the ways out. The honest cost is on the typeahead:
+ * **a query cannot contain a space typed with the Space key**, because Space is
+ * spoken for. An option is found by the words in its label and in its keywords, so
+ * the space in a query buys nothing a reader would miss, and the alternative is a
+ * control where the primary key for selecting cannot also type.
+ *
+ * **Backspace in the trigger removes the last chip, and only then edits text.**
+ * Backspace with a caret in the search field is a text edit like any other. Backspace
+ * in an empty one is a gesture at the set, and it takes the last chip chosen, which
+ * is the one nearest where the caret was. This is the second gesture every token
+ * field has and the one a hand-rolled multi select gets wrong by having no second
+ * path out of the chips at all.
+ *
+ * **The chips are `TagGroup` and the frame is `InputGroup`, not a reimplementation
+ * of either.** A chip is a thing the reader chose and can un-pick, which is the
+ * definition `TagGroup` already states and the reason its remove control exists.
+ * Drawing a second chip here would be a second answer to what a chip is, and it
+ * would be the one that quietly diverges on the coarse-pointer target size. The
+ * frame is borrowed for the same reason: a bordered group with one border and one
+ * focus colour is the thing a row of chips inside a search field has to be, and
+ * `InputGroup` already turns its border to the ring token when anything inside it
+ * has focus.
+ *
+ * **The listbox is `aria-multiselectable`, because a reader who cannot see that
+ * many of its rows may be chosen does not know what Space will do.** The attribute
+ * is the whole announcement difference between this list and a single-select one,
+ * and omitting it leaves a reader guessing whether the next Space replaces or adds.
+ *
+ * **A cap is visible rather than silent.** With `max`, an unchosen option past the
+ * cap is drawn and announced as unavailable and the arrows step over it, so the
+ * limit is discoverable before the reader hits it. The select-all control is the
+ * case where silence would be worst: it says it will choose everything and then
+ * chooses fewer, so it announces itself as unavailable instead, at the cost of a
+ * reader who wanted all of it having to add the rest one at a time.
+ *
+ * **Ordering is the reader's.** Values are appended in the order they were chosen
+ * and a removal closes the gap rather than re-sorting, because a chip row that
+ * reorders under the pointer is a chip row a reader cannot aim at. The list itself
+ * is ranked by the scorer imported from `lib/rank`, so a query that floats one
+ * option to the top floats it in the command palette too.
+ *
+ * **The chosen values are announced through the field's description, not through
+ * the query.** The search field holds a query and nothing else, so a screen reader
+ * focused on it hears the query and the chosen values are silent. Pointing
+ * `aria-describedby` at the chip row costs one generated id and makes every chosen
+ * label read out after the value. `showCount` is deliberately outside that: a bare
+ * figure has no noun, so it is drawn and not announced.
+ *
+ * The list is anchored to the field rather than portalled, for the trade
+ * `Combobox` states: put the field near the top of any scroll container it lives
+ * in.
+ */
+declare function MultiCombobox({ label, items, value, defaultValue, onValueChange, removeLabel, empty, max, selectAll, clearAll, showCount, placeholder, open, defaultOpen, onOpenChange, disabled, required, name, form, id, 'aria-describedby': describedBy, className, }: MultiComboboxProps): import("react").JSX.Element;
+export { MultiCombobox };
+//# sourceMappingURL=multi-combobox.d.ts.map

package/dist/components/ui/multi-combobox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-combobox.d.ts","sourceRoot":"","sources":["../../../src/components/ui/multi-combobox.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAM9C,4CAA4C;AAC5C,MAAM,WAAW,kBAAkB;IACjC;;;;;;;OAOG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;OAMG;IACH,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;IAC9B,uDAAuD;IACvD,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACzB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAA;IAClD;;;;;;;OAOG;IACH,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACtC,4DAA4D;IAC5D,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC5D;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAA;IACxC;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAA;IACrC;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,+DAA+D;IAC/D,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,4CAA4C;IAC5C,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACtC,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,gEAAgE;IAChE,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,uDAAuD;IACvD,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAiBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,iBAAS,aAAa,CAAC,EACrB,KAAK,EACL,KAAK,EACL,KAAK,EACL,YAAiB,EACjB,aAAa,EACb,WAAW,EACX,KAAK,EACL,GAAG,EACH,SAAS,EACT,QAAQ,EACR,SAAiB,EACjB,WAAW,EACX,IAAI,EACJ,WAAmB,EACnB,YAAY,EACZ,QAAgB,EAChB,QAAgB,EAChB,IAAI,EACJ,IAAI,EACJ,EAAE,EACF,kBAAkB,EAAE,WAAW,EAC/B,SAAS,GACV,EAAE,kBAAkB,+BA6ZpB;AAED,OAAO,EAAE,aAAa,EAAE,CAAA"}