@blakesteve/roster 4.8.2 → 4.9.0

package/README.md

@@ -186,7 +186,8 @@ they wrap your content and that text is not Roster's to restyle. `Eyebrow`,
 
 `solid` is the one variant where a component picks both the background and the
 text on it, so it can fail contrast on its own with no help from your app. Every
-solid fill in `Badge`, `Pill` and `Button` is measured against WCAG AA (4.5:1)
+solid fill in `Badge`, `Pill`, `Chip`, `Toast` and `Button` is measured against WCAG AA
+(4.5:1)
 by `src/contrast.test.ts`, at rest **and** on hover, in both themes.
 
 `Checkbox` is measured too, at 3:1 rather than 4.5:1 — its tick is a graphical
@@ -550,6 +551,340 @@ shared size, so they cannot drift apart. `Button` also has `xs` and `icon`,
 which neither field has an equivalent for. `Textarea` is not on this scale — it
 is multi-line, so the answer there is a min-height rather than a height.
 
+### Toasts
+
+Mount `Toaster` once near the root, then call `toast` from anywhere:
+
+```tsx
+import { Toaster, toast } from "@blakesteve/roster";
+
+<Toaster position="bottom-right" />;
+
+toast.success("Saved");
+toast.error("That name is taken");
+toast.info("Week 4 matchups are up");
+toast.warning("Picks close in ten minutes");
+```
+
+It wraps [`react-hot-toast`](https://react-hot-toast.com), which is a **peer
+dependency** — install it alongside Roster. It has to be external rather than
+bundled: its queue lives in module scope, so a bundled copy would give you two
+stores, and toasts fired from your own `import { toast } from "react-hot-toast"`
+would silently never appear.
+
+An app already using it keeps its call sites and only changes the import. What changes is
+the styling: the toast body is a real `Toast` component reading `--roster-*`
+rather than the inline hex each app was pinning.
+
+Two of those four helpers are Roster's own. `react-hot-toast` ships `success`,
+`error`, `loading` and `blank` — there is no `info` and no `warning`, so an app
+that wants one improvises, and at least one improvised by calling `toast.error`
+for `info`.
+
+**Errors are announced assertively, everything else politely.** That is also
+Roster's decision rather than the library's: `react-hot-toast` marks every
+toast `status` / `polite`, and a polite live region is read when the reader
+next pauses — which for a message that disappears in four seconds can mean
+never.
+
+`variant` on `Toaster` sets the fill for the whole queue:
+
+- **`soft`** (default) — the tinted fill `Alert` uses. Quiet enough that a stack
+  does not shout, which is the common case.
+- **`solid`** — the `-500` fill and ink token, step for step with `Pill` and
+  `Chip`. The one to reach for when toasts land over photography, video, or any
+  surface the app does not own: `bg-success-50` is a whisper on a white page
+  and illegible over an image.
+- **`glass`** — a neutral translucent surface at 60% with a backdrop blur,
+  matching `Dialog`'s variant of the same name. The tone lives on the **border
+  only**; the surface and the text are neutral for every scheme.
+
+Glass is neutral for a reason, and the border-only tone is the cost. Anything
+whose contrast depends on the backdrop is a guess: a colored fill measured
+2.60:1, and colored text on a neutral fill measured 2.81:1 — worse. Only the
+neutral ink is safe in both directions, at 17.49 over white, 6.14 over black
+and 9.22 over a brand color — 60% is as far as that allows, with 4.69 the worst
+case in dark. If the tone needs to be unmistakable, use `solid`.
+
+`src/contrast.test.ts` measures the `solid` fills and deliberately does not
+measure `glass` — a number there would be a number for one background.
+
+### Anchored popups share their internals
+
+`Select`, `Combobox` and `MultiSelect` open the same panel, and deliberately
+so: a combobox that opened a different-looking menu than a select on the same
+form is the bug worth preventing. The panel classes, the option rows and the dark-mode carry
+live in `src/internal/`, which is **not exported** — its contract is
+with those components, not with you. The escape hatch you reach for is
+`optionsClassName` on the component itself.
+
+Two things in there are worth knowing about even from outside, because both
+look like oversights until you know why:
+
+- **The panel sets no `max-height` and no `overflow`.** Headless UI's `size`
+  middleware writes both inline whenever `anchor` is set, so a utility would
+  lose to it anyway. To cap a menu shorter than the viewport allows, set the
+  variable that inline rule reads:
+  `optionsClassName="rst:[--anchor-max-height:20rem]"`.
+- **The panel is portaled to `<body>`**, so a `.dark` scoped to part of your
+  page does not reach it. All three components copy the nearest `.dark` onto
+  the panel to fix that. Custom properties are not carried the same way — set
+  `--roster-popover-*` at `:root`.
+- **`variant="slate"` opens on the dark palette**, in light mode too. That
+  variant paints a dark trigger, and its panel was rendering white: a dark
+  control opening a white sheet, which is the mismatch `--roster-popover-*`
+  exists to prevent. The token family only ever covered the variant that reads
+  tokens, and the ones that name a surface were left behind. It reuses the dark
+  palette rather than introducing a slate one, because every option state there
+  already exists and has already been measured.
+
+### Two ways to select more than one thing
+
+`MultiSelect` and `CheckboxGroup` both hold a set. They are not a fallback for
+each other:
+
+- **`MultiSelect`** when the field is one row of a form and the options do not
+  need to be read at a glance. It costs a click to see the list, which is what
+  makes it the right control for a dialog. Note that the default trigger still
+  grows as chips wrap — `maxChips` or `display="count"` is what actually pins
+  it to one row.
+- **`CheckboxGroup`** when scanning every option matters more than saving the
+  space, or when the options arrive in labeled categories. Nothing is hidden
+  and nothing needs a click to be read.
+
+Density is the axis, not correctness. The same eight sports are a good
+`MultiSelect` in a cramped creation dialog and a good `CheckboxGroup` on a
+settings page.
+
+Swapping one for the other is not free, though, and it is worth saying which
+parts move. `label`, `helperText` and `errorMessage` are the same three names
+in both. The value types are not: `CheckboxGroup` is `string[]`, `MultiSelect`
+is `(string | number)[]`, so state typed for one does not assign to the other.
+Neither do the options — `CheckboxGroupOption` carries a `description` that
+`SelectOption` has no field for, and `CheckboxGroup` additionally accepts
+`{ category, options }` groups that `MultiSelect` cannot take at all. Headless
+UI's `Listbox` has no grouping primitive, so option groups in the dropdown
+would be Roster's to build.
+
+#### MultiSelect
+
+The same Headless UI `Listbox` as `Select`, with `multiple` set, opening the
+same panel from `src/internal/popup.ts`. The panel stays open across picks;
+clicking a selected option again removes it.
+
+```tsx
+<MultiSelect
+  label="Sports"
+  options={SPORTS}
+  value={sports}
+  onChange={setSports}
+  maxChips={3}
+  clearable
+/>
+```
+
+Selections render as chips in the trigger, and each chip is individually
+dismissible without opening the menu.
+
+Getting that required a specific structure, and it is the interesting part of
+the component. A dismiss control is a `<button>` and `ListboxButton` is a
+button, so the chips cannot be its children — that pair is invalid HTML, and
+browsers do not rescue it either: React builds the DOM through the DOM API
+rather than the parser, which leaves it nested, so it would ship as a focusable
+control whose every click also opens the listbox. So the trigger is a **shell**
+with the `ListboxButton` stretched `inset-0` across it, and the chips are the
+button's siblings drawn on top.
+
+That keeps the button the full-width element, which matters more than it
+sounds: Headless UI anchors the panel to the button and sizes it from
+`--button-width`, and a trigger that stops being full width is how `Combobox`
+once shipped a 20px unreadable menu. Measured after the change, the panel still
+matches the field exactly.
+
+Everything decorative in the shell is `pointer-events-none`, so a click on a
+chip's label falls through and opens the menu like the rest of the field. Only
+the dismiss controls take their events back. Each is named after its own chip —
+a row of buttons all called "Remove" is a row a screen reader user cannot tell
+apart — and `removeLabel` takes a function if "Remove NFL" is not the phrasing
+you want. The chips are hidden from the trigger's accessible name, which
+carries a punctuated summary instead: they are `inline-flex` spans, and name
+computation joins them with no whitespace, so "NCAA Football" followed by "NBA"
+announced as "FootballNBA".
+
+The chips default to `outline` rather than a soft fill. The default trigger
+paints `--roster-control-bg`, which is `transparent`, so a chip sits on
+whatever the page is: a `soft neutral` chip is `gray-100`, which on this
+library's own `gray-50` page is a 1.04:1 rectangle. It rendered, it measured
+correct, and it could not be seen.
+
+`outline`'s identity is a border rather than a fill, but that alone was not
+enough either. Chip holds its border to 3:1 against a *page*, and this
+component can be told to paint its own surface — `variant="slate"` paints
+`gray-700`, byte-identical to the neutral chip's own `gray-700` label, which
+rendered chip-shaped holes at 1.00:1. So the chips take `text-inherit` and
+`border-current`, in both schemes, and cannot disagree with the surface they
+were placed on. The dismiss and clear controls inherit the same way, because
+the shell is what carries the trigger's color and they all sit inside it.
+Measured across all five variants in both schemes: chip label 9.42 to 18.11,
+chip border 4.33 to 8.99, glyphs 5.59 to 8.99.
+
+Each dismiss control's hit area is grown to 31x28 with an invisible `::after`.
+The glyph's own box is 15x12, and WCAG 2.5.8 asks 24x24 — the spacing exception
+does not rescue it, because the trigger is another target sitting directly
+underneath. That fix landed in `Chip` rather than here, so every dismissible
+chip gets it.
+
+`maxChips` collapses the tail into a `+N` chip and `display="count"` replaces
+the chips with `N selected`, so a field with eight selections does not become
+four rows tall. A selected value with no matching option renders as its own id
+rather than vanishing from a field that still reports it.
+
+#### CheckboxGroup
+
+Three things it adds over the version mega-squad's squad form hand-rolled:
+
+- **Each option is a Headless UI `Field`**, so its label is wired to its own
+  checkbox and clicking the text toggles it. The pointer cursor sits on the
+  label rather than on the row, because the label *is* the hit area: at two
+  columns, a short option like `NFL` fills about a quarter of its grid cell,
+  and a row-wide affordance would advertise the other three quarters as
+  clickable.
+- **Each category is a nested fieldset**, so `Football` is the accessible name
+  of the group under it rather than a styled `div` a screen reader walks past.
+  The heading is still a `<span>`, not a heading element, so it does not appear
+  in a screen reader's heading list — the name is reachable by entering the
+  group, which is what the nesting buys.
+- **`errorMessage` reaches the fieldset** as `aria-describedby`, wired by hand
+  rather than through Headless UI's `Description`. `Fieldset` collects
+  descendant labels but never calls `useDescriptions` and provides no
+  description context, so a `Description` dropped inside one throws rather than
+  degrading quietly. Per-option `description` text does go through `Field`,
+  which wires it properly — the distinction is real: a group description is
+  announced on entering the group, an option's on focusing that checkbox.
+
+  Both `aria-describedby` and `aria-invalid` are set **after** `...props` is
+  spread, and the describedby is merged with any the caller passes. Set before,
+  a caller's own `aria-describedby` would replace the error association with no
+  type error and no warning: a group rendering red text and reporting itself
+  valid.
+
+`variant="panel"` draws the enclosing box for the long-list case. It
+deliberately does not read `--roster-popover-*`: that family is for surfaces
+that float over the page, and this one is in the flow, so it takes `Card`'s
+`soft` fill. Its border is two ramp steps heavier than that card's, and that
+part is not shared: a card's hairline separates content from the page, while
+this one has to read as the wall a scroll region ends at.
+
+`maxHeight` is applied inline rather than as a class, because the useful values
+are arbitrary and a Tailwind class built from a prop is a class that does not
+exist at build time. A capped panel takes a tab stop of its own — Chrome and
+Firefox focus scrollers by themselves now, Safari does not, and a `disabled`
+group has no focusable option to tab to at all, so the region would be
+unscrollable from the keyboard.
+
+`errorMessage` repaints less here than it does on `Input` or `Select`, on
+purpose. `panel` gets an error border; `plain` has no boundary to repaint, so
+the message is the whole error state. A checkbox is not the thing that is
+invalid — the selection is — so nothing rings the individual controls.
+
+```tsx
+<CheckboxGroup
+  label="Select supported sports"
+  helperText="You can always add more later."
+  variant="panel"
+  columns={2}
+  maxHeight={240}
+  options={[
+    { category: "Football", options: [{ value: "nfl", label: "NFL" }] },
+    { category: "Hockey", options: [{ value: "nhl", label: "NHL" }] },
+  ]}
+  value={sports}
+  onChange={setSports}
+/>
+```
+
+`onChange` appends and filters rather than rebuilding the array from `options`.
+A rebuild sorts the result into declaration order, which reads tidier and
+silently drops any selected value whose option has not loaded yet.
+
+### Multi-selection is a checklist, not a menu
+
+`CheckboxGroup` exists instead of a multi-select `Select`, and the reason is
+that neither multi-selection UI in the portfolio was ever a dropdown.
+mega-squad's squad form picks sports from a grouped, scrollable checklist with
+category headings; bb-memorial's share form picks tags from a flat row of
+toggles. Collapsing either into a menu would have hidden the options behind a
+click to save vertical space neither screen was short of, so the component
+follows the shape that already worked. A multi-select dropdown is still the
+right answer for a list too long to show — when something in the portfolio has
+one, that is when to build it.
+
+Three things it adds over the hand-rolled version it replaces:
+
+- **Each option is a Headless UI `Field`**, so its label is wired to its own
+  checkbox and clicking the text toggles it. The pointer cursor sits on the
+  label rather than on the row, because the label *is* the hit area: at two
+  columns, a short option like `NFL` fills about a quarter of its grid cell,
+  and a row-wide affordance would advertise the other three quarters as
+  clickable.
+- **Each category is a nested fieldset**, so `Football` is the accessible name
+  of the group under it rather than a styled `div` a screen reader walks past.
+  The heading is still a `<span>`, not a heading element, so it does not appear
+  in a screen reader's heading list — the name is reachable by entering the
+  group, which is what the nesting buys.
+- **`errorMessage` reaches the fieldset** as `aria-describedby`, wired by hand
+  rather than through Headless UI's `Description`. `Fieldset` collects
+  descendant labels but never calls `useDescriptions` and provides no
+  description context, so a `Description` dropped inside one throws rather than
+  degrading quietly. Per-option `description` text does go through `Field`,
+  which wires it properly — the distinction is real: a group description is
+  announced on entering the group, an option's on focusing that checkbox.
+
+  Both `aria-describedby` and `aria-invalid` are set **after** `...props` is
+  spread, and the describedby is merged with any the caller passes. Set before,
+  a caller's own `aria-describedby` would replace the error association with no
+  type error and no warning: a group rendering red text and reporting itself
+  valid.
+
+`variant="panel"` draws the enclosing box for the long-list case. It
+deliberately does not read `--roster-popover-*`: that family is for surfaces
+that float over the page, and this one is in the flow, so it takes `Card`'s
+`soft` fill. Its border is two ramp steps heavier than that card's, and that
+part is not shared: a card's hairline separates content from the page, while
+this one has to read as the wall a scroll region ends at.
+
+`maxHeight` is applied inline rather than as a class, because the useful values
+are arbitrary and a Tailwind class built from a prop is a class that does not
+exist at build time. A capped panel takes a tab stop of its own — Chrome and
+Firefox focus scrollers by themselves now, Safari does not, and a `disabled`
+group has no focusable option to tab to at all, so the region would be
+unscrollable from the keyboard.
+
+`errorMessage` repaints less here than it does on `Input` or `Select`, on
+purpose. `panel` gets an error border; `plain` has no boundary to repaint, so
+the message is the whole error state. A checkbox is not the thing that is
+invalid — the selection is — so nothing rings the individual controls.
+
+```tsx
+<CheckboxGroup
+  label="Select supported sports"
+  helperText="You can always add more later."
+  variant="panel"
+  columns={2}
+  maxHeight={240}
+  options={[
+    { category: "Football", options: [{ value: "nfl", label: "NFL" }] },
+    { category: "Hockey", options: [{ value: "nhl", label: "NHL" }] },
+  ]}
+  value={sports}
+  onChange={setSports}
+/>
+```
+
+`onChange` appends and filters rather than rebuilding the array from `options`.
+A rebuild sorts the result into declaration order, which reads tidier and
+silently drops any selected value whose option has not loaded yet.
+
 ### Components that render links
 
 `Breadcrumbs` renders a plain `<a>` by default, which is right for a static
@@ -606,12 +941,15 @@ function App() {
 | `Button`             | Primary interactive element: solid, soft, outline, ghost, link variants                                      |
 | `Card`               | Bordered surface container                                                                                   |
 | `Checkbox`           | Accessible checkbox with label support                                                                       |
+| `Combobox`           | A `Select` you can type into: filters as you type, same panel and size scale                                 |
+| `Chip`               | The interactive one of Badge / Pill / Chip: removable, selectable, or both                                   |
 | `Disclosure`         | Show/hide toggle using HeadlessUI                                                                            |
 | `Eyebrow`            | Small tracked-out uppercase label above a heading or beside a rule; polymorphic via `as`                     |
 | `InlineCode`         | Inline `<code>` for identifiers in running prose                                                             |
 | `Input`              | Text input with label, error state, icon slots, and a size scale matching `Button`                           |
 | `LabeledDivider`     | Horizontal rule carrying a label, with an optional trailing count                                            |
 | `Link`               | Styled anchor with variant support                                                                           |
+| `MultiSelect`        | A `Select` that holds more than one value: dismissible chips, same panel                                     |
 | `PasswordInput`      | Password field with a show/hide reveal toggle                                                                |
 | `Pill`               | Inline phrase chrome: social proof, live state, applied filters                                              |
 | `AvatarStrip`        | Stacked avatar row with overflow chip, dismiss button, trailing slot, and label area                         |
@@ -633,12 +971,14 @@ function App() {
 | `Accordion`       | Collapsible content sections (single or multi-expand)                       |
 | `Alert`           | Inline notice strip with optional title and dismiss                         |
 | `Breadcrumbs`     | Navigation trail; pass `linkComponent` to keep navigation client-side       |
+| `CheckboxGroup`   | Checkbox set reporting one `string[]`; groups, columns, scroll, error       |
 | `CallToAction`    | Prominent hero-style CTA block                                              |
 | `DescriptionList` | Label and value pairs as a real `<dl>`: inline, stacked, or split           |
 | `EmptyState`      | Zero-data placeholder with icon and action slot                             |
 | `ErrorState`      | Error display with retry action                                             |
 | `MatchupCard`     | Head-to-head comparison card                                                |
 | `Pullquote`       | A line lifted out of prose, as `<figure>` + `<blockquote>` + `<figcaption>` |
+| `Toast`           | Transient floating notice; `Toaster` + the imperative `toast` handle        |
 
 ### Organisms
 

package/dist/{Table--O-sD53L.js → Table-C1JbdA7q.js}

@@ -4880,8 +4880,8 @@ export {
   ss as $,
   cs as A,
   Rs as B,
-  ds as C,
-  Df as D,
+  Df as C,
+  ds as D,
   ks as E,
   xf as F,
   He as G,
@@ -4896,22 +4896,22 @@ export {
   Hf as P,
   su as Q,
   Uf as R,
-  Yf as S,
+  Jf as S,
   Pf as T,
-  Qf as U,
+  Yf as U,
   Ns as V,
-  fu as W,
-  ru as X,
+  Qf as W,
+  fu as X,
   Ps as Y,
-  Zf as Z,
+  ru as Z,
   Bf as _,
   Tf as a,
-  Jf as a0,
-  qf as a1,
-  tu as a2,
-  Kf as a3,
-  iu as a4,
-  _s as a5,
+  Zf as a0,
+  _s as a1,
+  qf as a2,
+  tu as a3,
+  Kf as a4,
+  iu as a5,
   _f as a6,
   If as a7,
   js as a8,

package/dist/components/atoms/Chip/Chip.d.ts

@@ -0,0 +1,57 @@
+import { VariantProps } from 'class-variance-authority';
+import { chipVariants } from './chip-variants';
+import * as React from "react";
+export interface ChipProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "onSelect">, Omit<VariantProps<typeof chipVariants>, "disabled"> {
+    children: React.ReactNode;
+    /** Leading icon or avatar. */
+    leadingIcon?: React.ReactNode;
+    /**
+     * Presence makes the chip removable, adding a dismiss control.
+     *
+     * This is what Multi-select consumes for its selected values, and the reason
+     * Chip exists as a component rather than a prop on Badge.
+     */
+    onRemove?: () => void;
+    /**
+     * Accessible name for the dismiss control.
+     *
+     * Defaults to `Remove {children}` when `children` is a string, because eight
+     * chips in a row all named "Remove" is a list a screen reader user cannot
+     * navigate. Pass this explicitly whenever the label is not plain text.
+     */
+    removeLabel?: string;
+    /** Presence makes the body of the chip a toggle. */
+    onSelectedChange?: (selected: boolean) => void;
+    /**
+     * Pressed state for a selectable chip.
+     *
+     * Requires `onSelectedChange`. On its own it does nothing at all — the chip
+     * stays a plain span with no `aria-pressed` — because a chip that reports a
+     * pressed state and cannot be pressed is worse than one that reports
+     * nothing. Chip never styles this itself either; color is the consumer's
+     * call, as in the `Selectable` story.
+     */
+    selected?: boolean;
+    disabled?: boolean;
+}
+/**
+ * A chip: a label that does something. Removable, selectable, or both.
+ *
+ * The element it renders depends on what it can do, because that is what
+ * decides how it is announced and whether it can be reached:
+ *
+ * - neither  -> `<span>`, and you probably wanted `Pill`
+ * - select   -> the whole chip is a `<button aria-pressed>`
+ * - remove   -> a `<span>` wrapping the label and a dismiss `<button>`
+ * - both     -> a `<span>` wrapping TWO sibling buttons
+ *
+ * The last case is why the body is not simply made clickable when a dismiss
+ * button is present: a button inside a button is invalid HTML. Browsers do not
+ * rescue it either — measured, the HTML parser splits the pair into siblings,
+ * while the DOM API that React uses leaves it nested, so what actually ships is
+ * a focusable control whose every click also fires the button around it. Two
+ * siblings in a styled wrapper is the only structure that gives both actions a
+ * name, a focus ring and a tab stop.
+ */
+declare const Chip: React.ForwardRefExoticComponent<ChipProps & React.RefAttributes<HTMLElement>>;
+export { Chip };

package/dist/components/atoms/Chip/chip-variants.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Chip vs Pill vs Badge.
+ *
+ * Badge is a compact label attached to something else: a count on an avatar, a
+ * status on a table row. Pill is standalone inline chrome carrying a short
+ * phrase: social proof, live state, a filter that reads as a sentence fragment.
+ * Neither does anything when you click it.
+ *
+ * Chip is the interactive one. It is removable, selectable, or both, and it is
+ * the only one of the three that is a control rather than decoration. That is
+ * also why it is a component and not a `interactive` prop on Badge: it renders
+ * real buttons with real names and real focus rings, and bolting that onto a
+ * `<span>` would either lie to assistive tech or turn Badge into two
+ * components wearing one name.
+ *
+ * The visual language deliberately matches Pill — fully rounded, roomy
+ * horizontal padding — because a selected filter and a filter that merely
+ * reads as one should not look like different species. The difference the
+ * viewer should notice is that this one responds.
+ */
+export declare const chipVariants: (props?: ({
+    colorScheme?: "primary" | "amber" | "success" | "error" | "neutral" | "info" | null | undefined;
+    variant?: "soft" | "solid" | "outline" | null | undefined;
+    size?: "sm" | "md" | null | undefined;
+    disabled?: boolean | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;

package/dist/components/atoms/Combobox/Combobox.d.ts

@@ -0,0 +1,52 @@
+import { VariantProps } from 'class-variance-authority';
+import { inputVariants } from '../Input/input-variants';
+import { SelectOption } from '../Select/Select';
+import * as React from "react";
+export interface ComboboxProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange">, VariantProps<typeof inputVariants> {
+    options: SelectOption[];
+    value: string | number | null;
+    /**
+     * Receives `null` when the field is cleared.
+     *
+     * Headless UI reports a cleared input as `null`, and swallowing that made
+     * the selection unclearable: emptying the input fired nothing and Escape
+     * silently restored the old label.
+     */
+    onChange: (value: string | number | null) => void;
+    placeholder?: string;
+    disabled?: boolean;
+    label?: string;
+    helperText?: string;
+    errorMessage?: string;
+    /** Classes for the text input itself. `className` lands on the wrapper. */
+    inputClassName?: string;
+    /** Classes for the popup panel. */
+    optionsClassName?: string;
+    /** Shown in the panel when the query matches nothing. */
+    emptyMessage?: string;
+    /**
+     * Replaces the match rule.
+     *
+     * The default is a case-insensitive substring on `label`, which is what
+     * every hand-rolled version in the portfolio did. Pass this for fuzzy
+     * matching, matching on `value`, or filtering server-side by ignoring the
+     * query here entirely.
+     */
+    filter?: (options: SelectOption[], query: string) => SelectOption[];
+}
+/**
+ * A `Select` you can type into.
+ *
+ * Built on Headless UI's `Combobox` rather than on a Roster primitive, for the
+ * same reason `Select` is built on its `Listbox`: that IS the primitive, and
+ * it already handles the parts worth not rewriting — active-option tracking,
+ * the keyboard model, and the input's `aria-activedescendant` wiring.
+ *
+ * What Roster adds is the presentation, and it is deliberately the SAME
+ * presentation `Select` uses: the panel, its surface tokens, the `.dark` carry
+ * across the portal, and the option rows all come from shared internals. A
+ * combobox that opened a different-looking menu than a select on the same form
+ * would be the bug this component is meant to prevent.
+ */
+declare const Combobox: ({ options, value, onChange, placeholder, disabled, variant, size, error, label, helperText, errorMessage, className, inputClassName, optionsClassName, emptyMessage, filter, ...props }: ComboboxProps) => import("react/jsx-runtime").JSX.Element;
+export { Combobox };

package/dist/components/atoms/MultiSelect/MultiSelect.d.ts

@@ -0,0 +1,75 @@
+import { default as React } from 'react';
+import { VariantProps } from 'class-variance-authority';
+import { selectTriggerVariants } from '../Select/select-variants';
+import { SelectOption } from '../Select/Select';
+import { Chip } from '../Chip/Chip';
+export type MultiSelectValue = string | number;
+export interface MultiSelectProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue">, VariantProps<typeof selectTriggerVariants> {
+    /** Same option shape as `Select`. */
+    options: SelectOption[];
+    value: MultiSelectValue[];
+    onChange: (value: MultiSelectValue[]) => void;
+    placeholder?: string;
+    disabled?: boolean;
+    className?: string;
+    label?: string;
+    /** Classes for the trigger button itself. Mirrors `Select`. */
+    triggerClassName?: string;
+    /** Classes for the popup panel. Mirrors `Select`. */
+    optionsClassName?: string;
+    /** Supporting text under the trigger. */
+    helperText?: string;
+    /**
+     * The message for an invalid selection. Implies `error`, so a caller cannot
+     * set the red ring and forget to say why. Mirrors `Select`.
+     */
+    errorMessage?: string;
+    /**
+     * How the selection reads in the closed trigger.
+     *
+     * `chips` names every selection, which is the point of the component when
+     * the list is short. `count` is the escape hatch for a field that would
+     * otherwise grow to five rows on a narrow screen — `maxChips` handles the
+     * middle ground.
+     */
+    display?: "chips" | "count";
+    /**
+     * Chips to show before the rest collapse into a `+N` chip. `undefined` shows
+     * all of them.
+     */
+    maxChips?: number;
+    /** Adds a control that clears the whole selection. */
+    clearable?: boolean;
+    /** Color scheme for the selection chips. */
+    chipColorScheme?: React.ComponentProps<typeof Chip>["colorScheme"];
+    /**
+     * Fill for the selection chips. `outline` by default, and deliberately.
+     *
+     * The trigger's own default variant paints `--roster-control-bg`, which is
+     * `transparent` — so a chip sits on whatever the page is, not on a surface
+     * this component controls. A `soft neutral` chip is `gray-100`, which on the
+     * library's own `gray-50` page is a 1.04:1 rectangle: the chips rendered,
+     * measured correct, and could not be seen. `outline` is the one fill whose
+     * identity is a border rather than a background.
+     *
+     * Chip's own outline palette is not enough on its own, though, and that is
+     * why the chips below take `text-inherit` and `border-current`. Chip holds
+     * its border to 3:1 against a PAGE; this component can be told to paint its
+     * own surface, and `variant="slate"` paints `gray-700` — byte-identical to
+     * the neutral chip's own `gray-700` label. That rendered chip-shaped holes
+     * with no readable text at 1.00:1. Inheriting means the chip cannot disagree
+     * with the surface it was just placed on.
+     */
+    chipVariant?: React.ComponentProps<typeof Chip>["variant"];
+    /** Accessible name for the clear control. */
+    clearLabel?: string;
+    /**
+     * Builds the accessible name for a chip's dismiss control.
+     *
+     * A row of buttons all named "Remove" is a row a screen reader user cannot
+     * tell apart, so this takes the label rather than being a constant.
+     */
+    removeLabel?: (label: string) => string;
+}
+declare const MultiSelect: ({ options, value, onChange, placeholder, disabled, variant, size, error, className, triggerClassName, optionsClassName, helperText, errorMessage, label, display, maxChips, clearable, chipColorScheme, chipVariant, clearLabel, removeLabel, ...props }: MultiSelectProps) => import("react/jsx-runtime").JSX.Element;
+export { MultiSelect };