@tapestry-ui/combobox 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brandon Minton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,113 @@
-# Temporary Holding Version
+# @tapestry-ui/combobox
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A combobox for Preact: **type to narrow, or open the whole list like a select.**
+WCAG 2.1 AA, headless behavior, skinned entirely through CSS.
+
+Part of [Tapestry UI](https://github.com/ryurage/brandonminton) — components
+forged inside a woven-tapestry game and a private war-room dashboard, then
+published so they have to survive strangers.
+
+```bash
+npm i @tapestry-ui/combobox
+```
+
+```tsx
+import { Combobox } from '@tapestry-ui/combobox';
+import '@tapestry-ui/combobox/styles.css'; // structural only — no colors
+
+<Combobox
+  label="Property"
+  options={properties.map((name) => ({ value: name }))}
+  value={chosen}
+  onChange={setChosen}
+  placeholder="all properties"
+/>
+```
+
+## Why not a `<select>`
+
+A native select cannot be styled past its edges and cannot be typed into. With
+eighteen options, "scroll until you see Fairview" is the wrong interaction —
+you already know the name. This is both halves at once: a text field that
+filters as you type, and a chevron that shows you everything.
+
+## The two contracts
+
+**Typing is a query, never a value.** A component that replaces a `<select>`
+must never end up holding something nobody chose. Abandon the field half-typed
+and the committed label comes back. Only Enter, Tab, a click, or — with
+`allowCustom` — blurring on free text commits anything.
+
+**The container contract, and its one exception.** Tapestry UI components never
+own scrolling. The popup is the exception, deliberately: it is an overlay over
+the page rather than part of your layout, so capping its height constrains
+nothing you laid out. The cap is still yours —
+`--tui-combobox-list-max-h: none` removes it.
+
+## Props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `options` | `ComboboxOption[]` | `{ value, label?, description?, disabled? }`; `label` defaults to `value` |
+| `label` | `string` | **required** — the accessible name, read before the value |
+| `showLabel` | `boolean` | render the label visibly too (default: screen readers only) |
+| `value` / `onChange` | `string` / `(value) => void` | controlled; the component reports intent and never drifts |
+| `defaultValue` | `string` | uncontrolled starting value |
+| `placeholder` | `string` | |
+| `allowCustom` | `boolean` | commit typed text that matches no option |
+| `openOnFocus` | `boolean` | show the whole list the moment the field is focused |
+| `filter` | `(query, option) => boolean` | the query arrives lowercased and de-accented |
+| `emptyLabel` | `string` | shown when nothing matches (default `"no match"`) |
+| `toggleLabel` | `string` | accessible name for the chevron |
+| `maxVisible` | `number` | rendered-row cap (default 100); the rest are counted, not drawn |
+| `disabled` / `required` | `boolean` | |
+| `name` | `string` | adds a hidden input so the field posts like a `<select>` |
+| `class` / `inputClass` / `listClass` / `optionClass` / `id` | `string` | skin hooks |
+
+`foldCase(text)` is exported — the same lowercase-and-strip-accents the default
+filter uses, in case you write your own.
+
+## Keyboard
+
+| Key | Does |
+|---|---|
+| <kbd>↓</kbd> / <kbd>↑</kbd> | open the list; move the highlight, wrapping at the ends |
+| <kbd>Home</kbd> / <kbd>End</kbd> | first / last option |
+| <kbd>Enter</kbd> | commit the highlighted option (and **not** submit the form) |
+| <kbd>Tab</kbd> | commit the highlighted option and move on |
+| <kbd>Esc</kbd> | close the list; again restores the committed label |
+| typing | filter, highlighting the matched run |
+
+Disabled options are never a destination. DOM focus stays in the input the
+whole time — the highlight is carried by `aria-activedescendant`, so a screen
+reader reads the option without losing the text field, and the option count is
+announced from a polite live region as the list narrows.
+
+## Styling
+
+Structural CSS ships in `styles.css`; it picks no colors. Skin it with custom
+properties, or ignore the file and style the `[data-part]` hooks yourself.
+**Never fork the package to restyle it.**
+
+| Property | Default |
+|---|---|
+| `--tui-combobox-pad` | `0.4em 2em 0.4em 0.6em` |
+| `--tui-combobox-focus` | `2px solid currentColor` |
+| `--tui-combobox-toggle-w` | `2em` |
+| `--tui-combobox-chevron-w` | `0.625em` |
+| `--tui-combobox-list-max-h` | `15em` (`none` to uncap) |
+| `--tui-combobox-option-pad` | `0.4em 0.6em` |
+| `--tui-combobox-z` | `20` |
+
+Parts: `root` (`data-state="open|closed"`, `data-placement="below|above"`),
+`label`, `field`, `input`, `toggle`, `list`, `option`
+(`data-state="active|idle"`), `option-label`, `option-desc`, `match`, `empty`,
+`more`, `status`, `value`.
+
+The popup opens upward on its own when there is no room below it — a phone
+keyboard eats the bottom half of the screen, and a popup under the fold is a
+popup that isn't there.
+
+## License
+
+MIT © Brandon Minton

package/dist/combobox.d.ts

@@ -0,0 +1,66 @@
+import { type JSX } from 'preact';
+/**
+ * Everything this component says that it ASSEMBLES rather than simply renders.
+ * Functions, not templates with holes in them, because a string cannot
+ * pluralise: "1 option" / "2 options" is an English rule, and Polish has three
+ * forms. The target language decides, not a format string.
+ */
+export interface ComboboxStrings {
+    /** The chevron's accessible name, given the field's own label. */
+    showAll: (label: string) => string;
+    /** The note under a capped list. */
+    more: (count: number) => string;
+    /** The live count, announced as the list narrows. */
+    optionCount: (count: number) => string;
+}
+export declare const EN_COMBOBOX: ComboboxStrings;
+export interface ComboboxOption {
+    /** the committed value — what onChange reports and a hidden input submits */
+    value: string;
+    /** what the human reads; defaults to `value` */
+    label?: string;
+    /** a quiet second line in the option row (a role, a count, an address) */
+    description?: string;
+    disabled?: boolean;
+}
+export interface ComboboxProps {
+    options: ComboboxOption[];
+    /** accessible name for the field — assistive tech reads this before the value */
+    label: string;
+    /** render the label as visible text above the field (default: it is only for AT) */
+    showLabel?: boolean;
+    /** controlled value — the component follows it and only reports intent */
+    value?: string;
+    /** uncontrolled initial value (default: nothing chosen) */
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+    placeholder?: string;
+    /** commit typed text that matches no option (default: typing is only a filter) */
+    allowCustom?: boolean;
+    /** open the whole list as soon as the field is focused */
+    openOnFocus?: boolean;
+    /** override the match test; the query arrives already lowercased and de-accented */
+    filter?: (query: string, option: ComboboxOption) => boolean;
+    /** shown in the popup when nothing matches */
+    emptyLabel?: string;
+    /** accessible name for the chevron */
+    toggleLabel?: string;
+    /** Replace any sentence this component builds. Defaults are English. */
+    strings?: Partial<ComboboxStrings>;
+    /** cap on rendered options (default 100); the rest are counted, not drawn */
+    maxVisible?: number;
+    disabled?: boolean;
+    required?: boolean;
+    /** render a hidden input under this name so the field posts like a <select> */
+    name?: string;
+    /** skin hooks — tapestry-ui components style through CSS, never props */
+    class?: string;
+    inputClass?: string;
+    listClass?: string;
+    optionClass?: string;
+    id?: string;
+}
+/** Lowercased and stripped of accents, so "Fairview" finds "fairview" and
+ *  "Muñoz" finds "munoz". Both sides of every comparison go through this. */
+export declare function foldCase(text: string): string;
+export declare function Combobox(props: ComboboxProps): JSX.Element;

package/dist/combobox.js

@@ -0,0 +1,251 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
+// @tapestry-ui/combobox — the picker (Tapestry UI citizen #5).
+//
+// WHY IT EXISTS: a native <select> cannot be styled past a certain point, and
+// it cannot be typed into. With eighteen properties in the list, "scroll until
+// you see Fairview" is the wrong interaction — you know the name, you should be
+// able to say it. This component is both halves at once: type to narrow, or hit
+// the chevron and read the whole list like a select.
+//
+// A11y shape: the WAI-ARIA combobox pattern, list-autocomplete variant. The
+// input carries role=combobox + aria-expanded + aria-controls, the popup is a
+// listbox of options, and the keyboard's position is announced through
+// aria-activedescendant — DOM focus never leaves the input, so a screen reader
+// reads the option without losing the text field.
+//
+// THE CONTAINER CONTRACT, and its one exception: tapestry-ui components never
+// own scrolling. The popup is the exception, and deliberately: it is an overlay
+// over the page, not part of the consumer's flow, so a cap on its height
+// constrains nothing the consumer laid out. The cap is a custom property
+// (--tui-combobox-list-max-h) so it is still yours to set or remove.
+//
+// THE SELECT CONTRACT: a thing that replaces a <select> must never hold a value
+// nobody chose. Typing is a QUERY, not a value — abandon the field half-typed
+// and the committed label comes back. Only Enter, Tab, a click, or (with
+// `allowCustom`) blur-on-free-text commits anything.
+import { Fragment } from 'preact';
+import { useEffect, useId, useLayoutEffect, useMemo, useRef, useState } from 'preact/hooks';
+/** Options rendered at once. Past this, typing is the way through — a popup
+ *  with four hundred rows is a scroll race, not a choice. */
+const DEFAULT_MAX_VISIBLE = 100;
+/** Space (px) the popup needs below the input before it gives up and opens upward. */
+const FLIP_THRESHOLD_PX = 220;
+export const EN_COMBOBOX = {
+    showAll: (label) => `Show all ${label} options`,
+    more: (count) => `${count} more — keep typing`,
+    optionCount: (count) => `${count} ${count === 1 ? 'option' : 'options'}`,
+};
+/** Lowercased and stripped of accents, so "Fairview" finds "fairview" and
+ *  "Muñoz" finds "munoz". Both sides of every comparison go through this. */
+export function foldCase(text) {
+    return text.normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase();
+}
+const labelOf = (option) => option.label ?? option.value;
+/** The default match: the query appears anywhere in the label or description. */
+const containsQuery = (query, option) => foldCase(labelOf(option)).includes(query) ||
+    (option.description !== undefined && foldCase(option.description).includes(query));
+/** The label with every occurrence of the query wrapped, so the eye lands on
+ *  the reason the row survived the filter. */
+function Highlight({ text, query }) {
+    if (query === '')
+        return _jsx(_Fragment, { children: text });
+    const folded = foldCase(text);
+    const pieces = [];
+    let cursor = 0;
+    let hit = folded.indexOf(query);
+    while (hit !== -1) {
+        if (hit > cursor)
+            pieces.push(_jsx(Fragment, { children: text.slice(cursor, hit) }, `t${cursor}`));
+        pieces.push(_jsx("mark", { "data-part": "match", children: text.slice(hit, hit + query.length) }, `m${hit}`));
+        cursor = hit + query.length;
+        hit = folded.indexOf(query, cursor);
+    }
+    pieces.push(_jsx(Fragment, { children: text.slice(cursor) }, "tail"));
+    return _jsx(_Fragment, { children: pieces });
+}
+export function Combobox(props) {
+    const autoId = useId();
+    const base = props.id ?? `tui-combobox-${autoId}`;
+    const listId = `${base}-list`;
+    const optionId = (index) => `${base}-opt-${index}`;
+    const words = { ...EN_COMBOBOX, ...props.strings };
+    const rootRef = useRef(null);
+    const inputRef = useRef(null);
+    const controlled = props.value !== undefined;
+    const [ownValue, setOwnValue] = useState(props.defaultValue ?? '');
+    const committed = controlled ? props.value : ownValue;
+    const [open, setOpen] = useState(false);
+    /** null means "not typing" — the field shows the committed label */
+    const [query, setQuery] = useState(null);
+    const [activeIndex, setActiveIndex] = useState(-1);
+    const [placement, setPlacement] = useState('below');
+    const chosen = props.options.find((option) => option.value === committed);
+    const committedText = chosen ? labelOf(chosen) : props.allowCustom ? committed : '';
+    const text = query ?? committedText;
+    // An empty query is the SAME as not typing: show everything. That is what
+    // makes the chevron and a cleared field behave identically.
+    const folded = query === null ? '' : foldCase(query.trim());
+    const match = props.filter ?? containsQuery;
+    const matching = useMemo(() => (folded === '' ? props.options : props.options.filter((option) => match(folded, option))), [folded, props.options, props.filter]);
+    const maxVisible = props.maxVisible ?? DEFAULT_MAX_VISIBLE;
+    const shown = matching.slice(0, maxVisible);
+    const hiddenCount = matching.length - shown.length;
+    /** Keep the keyboard's position inside the list as the list shrinks under it. */
+    useEffect(() => {
+        if (activeIndex >= shown.length)
+            setActiveIndex(shown.length === 0 ? -1 : shown.length - 1);
+    }, [shown.length, activeIndex]);
+    /** Follow the active option with the popup's own scroll. jsdom has no
+     *  scrollIntoView and an exception here would take the whole render with it. */
+    useEffect(() => {
+        if (!open || activeIndex < 0)
+            return;
+        document.getElementById(optionId(activeIndex))?.scrollIntoView?.({ block: 'nearest' });
+    }, [open, activeIndex]);
+    /** Open upward when there is no room below — a phone keyboard eats the bottom
+     *  half of the screen, and a popup under the fold is a popup that isn't there. */
+    useLayoutEffect(() => {
+        if (!open)
+            return;
+        const box = inputRef.current?.getBoundingClientRect?.();
+        if (!box)
+            return;
+        const roomBelow = window.innerHeight - box.bottom;
+        setPlacement(roomBelow < FLIP_THRESHOLD_PX && box.top > roomBelow ? 'above' : 'below');
+    }, [open, shown.length]);
+    const commit = (value) => {
+        if (!controlled)
+            setOwnValue(value);
+        setQuery(null);
+        setOpen(false);
+        setActiveIndex(-1);
+        if (value !== committed)
+            props.onChange?.(value);
+    };
+    /** Back to the committed value with nothing chosen: typing was only ever a query. */
+    const abandon = () => {
+        setQuery(null);
+        setOpen(false);
+        setActiveIndex(-1);
+    };
+    const openFullList = () => {
+        setQuery(null);
+        setOpen(true);
+        const atCommitted = props.options.findIndex((option) => option.value === committed);
+        setActiveIndex(atCommitted);
+    };
+    /** The next selectable row in `step` direction, wrapping; disabled is never a
+     *  destination. Returns -1 when every row is disabled. */
+    const nextEnabled = (from, step) => {
+        const count = shown.length;
+        if (count === 0)
+            return -1;
+        for (let hop = 1; hop <= count; hop++) {
+            const index = (((from + step * hop) % count) + count) % count;
+            if (!shown[index].disabled)
+                return index;
+        }
+        return -1;
+    };
+    const handleKey = (event) => {
+        if (props.disabled)
+            return;
+        switch (event.key) {
+            case 'ArrowDown':
+                event.preventDefault();
+                if (!open) {
+                    setOpen(true);
+                    setActiveIndex(nextEnabled(-1, 1));
+                }
+                else
+                    setActiveIndex(nextEnabled(activeIndex, 1));
+                return;
+            case 'ArrowUp':
+                event.preventDefault();
+                if (!open) {
+                    setOpen(true);
+                    setActiveIndex(nextEnabled(0, -1));
+                }
+                else
+                    setActiveIndex(nextEnabled(activeIndex, -1));
+                return;
+            case 'Home':
+                if (!open)
+                    return;
+                event.preventDefault();
+                setActiveIndex(nextEnabled(-1, 1));
+                return;
+            case 'End':
+                if (!open)
+                    return;
+                event.preventDefault();
+                setActiveIndex(nextEnabled(0, -1));
+                return;
+            case 'Enter': {
+                const active = open && activeIndex >= 0 ? shown[activeIndex] : undefined;
+                if (active && !active.disabled) {
+                    // the pick is the whole point of the keystroke — it must not also submit
+                    event.preventDefault();
+                    commit(active.value);
+                }
+                else if (props.allowCustom && query !== null) {
+                    event.preventDefault();
+                    commit(query.trim());
+                }
+                return;
+            }
+            case 'Escape':
+                // first Escape closes the popup, a second puts the committed label back
+                event.preventDefault();
+                if (open) {
+                    setOpen(false);
+                    setActiveIndex(-1);
+                }
+                else
+                    abandon();
+                return;
+            case 'Tab': {
+                // leaving the field is a decision: take the highlighted row with you
+                const active = open && activeIndex >= 0 ? shown[activeIndex] : undefined;
+                if (active && !active.disabled)
+                    commit(active.value);
+                return;
+            }
+            default:
+                return;
+        }
+    };
+    /** Focus leaving the whole widget — not merely hopping input -> chevron. */
+    const handleFocusOut = (event) => {
+        const movingTo = event.relatedTarget;
+        if (movingTo && rootRef.current?.contains(movingTo))
+            return;
+        const typed = query?.trim() ?? '';
+        if (props.allowCustom && query !== null && typed !== committed)
+            commit(typed);
+        else
+            abandon();
+    };
+    const activeOption = activeIndex >= 0 ? shown[activeIndex] : undefined;
+    return (_jsxs("div", { ref: rootRef, id: base, class: cx('tui-combobox', props.class), "data-part": "root", "data-state": open ? 'open' : 'closed', "data-placement": placement, onFocusOut: handleFocusOut, children: [_jsx("label", { class: cx('tui-combobox__label', !props.showLabel && 'tui-combobox__sr'), "data-part": "label", for: `${base}-input`, children: props.label }), _jsxs("div", { class: "tui-combobox__field", "data-part": "field", children: [_jsx("input", { ref: inputRef, id: `${base}-input`, class: cx('tui-combobox__input', props.inputClass), "data-part": "input", type: "text", role: "combobox", autocomplete: "off", spellcheck: false, "aria-expanded": open, "aria-controls": listId, "aria-autocomplete": "list", "aria-activedescendant": open && activeIndex >= 0 ? optionId(activeIndex) : undefined, "aria-required": props.required, placeholder: props.placeholder, disabled: props.disabled, value: text, onInput: (event) => {
+                            setQuery(event.currentTarget.value);
+                            setOpen(true);
+                            setActiveIndex(0);
+                        }, onFocus: () => { if (props.openOnFocus && !open)
+                            openFullList(); }, onKeyDown: handleKey }), _jsx("button", { type: "button", class: "tui-combobox__toggle", "data-part": "toggle", 
+                        // the chevron is not a tab stop: the input is the widget's one stop,
+                        // and ArrowDown already opens the list from there
+                        tabIndex: -1, "aria-label": props.toggleLabel ?? words.showAll(props.label), "aria-expanded": open, "aria-controls": listId, disabled: props.disabled, onMouseDown: (event) => event.preventDefault(), onClick: () => {
+                            if (open)
+                                abandon();
+                            else {
+                                openFullList();
+                                inputRef.current?.focus();
+                            }
+                        }, children: _jsx("svg", { viewBox: "0 0 10 6", "aria-hidden": "true", focusable: "false", children: _jsx("path", { d: "M1 1l4 4 4-4", fill: "none", stroke: "currentColor", "stroke-width": "1.5", "stroke-linecap": "round" }) }) })] }), open && (_jsxs("ul", { id: listId, class: cx('tui-combobox__list', props.listClass), "data-part": "list", role: "listbox", "aria-label": props.label, children: [shown.length === 0 && (_jsx("li", { class: "tui-combobox__empty", "data-part": "empty", role: "presentation", children: props.emptyLabel ?? 'no match' })), shown.map((option, index) => (_jsxs("li", { id: optionId(index), class: cx('tui-combobox__option', props.optionClass), "data-part": "option", "data-state": index === activeIndex ? 'active' : 'idle', role: "option", "aria-selected": option.value === committed, "aria-disabled": option.disabled, onMouseDown: (event) => event.preventDefault(), onMouseMove: () => { if (!option.disabled)
+                            setActiveIndex(index); }, onClick: () => { if (!option.disabled)
+                            commit(option.value); }, children: [_jsx("span", { class: "tui-combobox__option-label", "data-part": "option-label", children: _jsx(Highlight, { text: labelOf(option), query: folded }) }), option.description !== undefined && (_jsx("span", { class: "tui-combobox__option-desc", "data-part": "option-desc", children: _jsx(Highlight, { text: option.description, query: folded }) }))] }, option.value))), hiddenCount > 0 && (_jsx("li", { class: "tui-combobox__more", "data-part": "more", role: "presentation", children: words.more(hiddenCount) }))] })), _jsxs("span", { class: "tui-combobox__sr", "data-part": "status", role: "status", "aria-live": "polite", children: [open ? words.optionCount(matching.length) : '', activeOption ? `, ${labelOf(activeOption)}` : ''] }), props.name !== undefined && (_jsx("input", { type: "hidden", name: props.name, value: committed, "data-part": "value" }))] }));
+}
+function cx(...parts) {
+    return parts.filter(Boolean).join(' ');
+}

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@tapestry-ui/combobox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "A WCAG 2.1 AA combobox for Preact \u2014 type to filter or open the whole list, APG keyboard, match highlighting, headless behavior, skin via CSS. The polished replacement for a native select.",
+  "license": "MIT",
+  "author": "Brandon Minton",
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/combobox.d.ts",
+      "default": "./dist/combobox.js"
+    },
+    "./styles.css": "./styles.css"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "styles.css",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "peerDependencies": {
+    "preact": ">=10.24.0"
+  },
+  "devDependencies": {
+    "jsdom": "^25.0.1",
+    "preact": "^10.29.4",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ryurage/brandonminton.git",
+    "directory": "packages/tapestry-ui/combobox"
+  },
+  "keywords": [
+    "preact",
+    "combobox",
+    "autocomplete",
+    "typeahead",
+    "select",
+    "a11y",
+    "wcag",
+    "headless",
+    "tapestry-ui"
+  ]
+}

package/styles.css

@@ -0,0 +1,80 @@
+/* @tapestry-ui/combobox — STRUCTURAL styles only. The skin is yours:
+   override the custom properties, or ignore this file entirely and style the
+   [data-part] hooks from scratch. Nothing here picks a color. */
+.tui-combobox { position: relative; }
+
+.tui-combobox__field { position: relative; display: flex; align-items: stretch; }
+.tui-combobox__input {
+  font: inherit;
+  color: inherit;
+  background: none;
+  flex: 1;
+  min-width: 0; /* a flex child with a text input in it will not shrink without this */
+  padding: var(--tui-combobox-pad, 0.4em 2em 0.4em 0.6em);
+}
+.tui-combobox__input:focus-visible {
+  outline: var(--tui-combobox-focus, 2px solid currentColor);
+  outline-offset: 2px;
+}
+
+/* the chevron sits INSIDE the field's right edge, over the input's padding */
+.tui-combobox__toggle {
+  position: absolute;
+  inset: 0 0 0 auto;
+  width: var(--tui-combobox-toggle-w, 2em);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: none;
+  border: none;
+  color: inherit;
+  cursor: pointer;
+  padding: 0;
+}
+.tui-combobox__toggle svg { width: var(--tui-combobox-chevron-w, 0.625em); display: block; }
+.tui-combobox__toggle:disabled { cursor: default; opacity: 0.5; }
+.tui-combobox[data-state="open"] .tui-combobox__toggle svg { transform: rotate(180deg); }
+
+/* THE ONE PLACE THIS LIBRARY SCROLLS. The popup is an overlay, not part of the
+   consumer's flow, so a height cap here constrains nothing they laid out — and
+   it is still a custom property, so `none` gives you the uncapped list. */
+.tui-combobox__list {
+  position: absolute;
+  z-index: var(--tui-combobox-z, 20);
+  left: 0;
+  right: 0;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  max-height: var(--tui-combobox-list-max-h, 15em);
+  overflow-y: auto;
+  overscroll-behavior: contain; /* scrolling the list must not scroll the page behind it */
+}
+.tui-combobox[data-placement="below"] .tui-combobox__list { top: 100%; }
+.tui-combobox[data-placement="above"] .tui-combobox__list { bottom: 100%; }
+
+.tui-combobox__option {
+  display: block;
+  cursor: pointer;
+  padding: var(--tui-combobox-option-pad, 0.4em 0.6em);
+}
+.tui-combobox__option[aria-disabled="true"] { cursor: default; opacity: 0.5; }
+.tui-combobox__option-label { display: block; }
+.tui-combobox__option-desc { display: block; }
+.tui-combobox__option mark { background: none; color: inherit; font-weight: 700; }
+
+.tui-combobox__empty,
+.tui-combobox__more { padding: var(--tui-combobox-option-pad, 0.4em 0.6em); }
+
+/* visually hidden, still read aloud — the label and the live count live here */
+.tui-combobox__sr {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}