@agent-ui-kit/components 0.0.3

package/dist/controls/combo-box/combo-box.css

@@ -0,0 +1,397 @@
+/* combo-box.css — ui-combo-box, the single-file component stylesheet (ADR-0003).
+ * Two clearly-SECTIONED blocks, mirroring popover.css / text-field.css:
+ *
+ *   [1] TOKEN BLOCK  — `:where(ui-combo-box)` (specificity 0,0,0) declares the `--ui-combo-box-*`
+ *       chain from the colour roles (`--md-sys-color-{family}-{role}`) and the dimensional ramp
+ *       (`--md-sys-height-md` / `--md-sys-shape-corner-base`). Raw `--md-sys-color-*` roles enter ONLY
+ *       here; `@scope` never reads them. This is the "Geometry-by-part" three-class pattern
+ *       from the decomp: the editor is Control-class, the panel is Container/surface, and the
+ *       option rows are the legacy item-pad (ROV-C5 / §4.6/5.1).
+ *   [2] STYLES BLOCK — `@scope (ui-combo-box)` CONSUMES only `--ui-combo-box-*` for its OWN
+ *       tokens plus the shared fleet constants (`--md-sys-color-focus-ring`, `--ui-motion-*`).
+ *       The host is `display: inline-grid` with a `min-inline-size` floor (ADR-0021: entry-
+ *       control frame law; the same trap that collapsed ui-text-field + ui-slider). The editor
+ *       part is Control-class: `block-size` off `--ui-combo-box-height`; inline text inset = h/2
+ *       (the fleet Control-class value-edge standard, matching text-field/select). The listbox
+ *       panel is Container/surface: `--ui-container-bg` equivalent, `--md-sys-shape-corner-base` rounding.
+ *       Options use the item-pad row model. `[data-active]` highlights the active-descendant
+ *       option without moving DOM focus.
+ *       (2026-07-06) The item-pad's numbers are DERIVED off the editor's own height/font
+ *       (`--ui-combo-box-height`/`-font`/`-padding-inline`) instead of fixed `--md-sys-space-*` px, so
+ *       option text aligns under the editor's text and the option row height matches the editor's
+ *       — the same size-carrying model as ui-select's listbox, applied to combo-box's single
+ *       (currently size-less) register; see the token-block comment for the exact derivation.
+ *       (2026-07-06, follow-up) `--ui-combo-box-padding-inline` itself is now h/2 (was the fixed
+ *       `--md-sys-space-sm`) — the editor was the lone entry-control outlier off the fleet h/2 value-
+ *       edge law; the item-pad derivation above already read this token, so options auto-followed
+ *       (h/4 + h/4 = h/2), now byte-identical in model to ui-select's trigger/listbox pairing.
+ *
+ * Standalone stylesheet — NOT injected from combo-box.ts (behaviour-only `.ts`, plan §2).
+ * Linked via the component-styles barrel (wave-4 integration slice). The panel's `[popover]`
+ * attribute gives it `display:none` until `showPopover()` opens it into the top layer.
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-combo-box) ════════════════ */
+
+:where(ui-combo-box) {
+  /* ── Editor (Control-class) ─────────────────────────────────────────── */
+  /* Geometry: control height off the md-scale ramp (the combo-box trigger is the editor). */
+  --ui-combo-box-height: var(--md-sys-height-md);
+  --ui-combo-box-font: var(--md-sys-font-md);
+  /* (2026-07-06) h/2 — the fleet Control-class value-edge standard (text-field.css:119,
+     select.css trigger padding-inline-start), replacing the earlier fixed --md-sys-space-sm.
+     The editor was the lone entry-control outlier still anchored to a space token instead
+     of the frame-law h/2 inset; this brings it into line. */
+  --ui-combo-box-padding-inline: calc(var(--ui-combo-box-height) / 2);
+
+  /* Frame — Kim's filled/container state law (TKT-0062), SUPERSEDING the earlier border-only
+     channel: THREE channels now repoint per state (background, border, text-ink), keyed off five
+     states — default (empty, idle) / filled (has a value, idle) / hover / focus / disabled.
+     user-invalid is UNCHANGED — its own border-only danger channel (below) layers on top of
+     whichever bg/ink this table already picked; it never touches bg.
+       state    | bg              | border           | ink
+       default  | container-low   | transparent       | neutral
+       filled   | container       | transparent       | on-surface-variant
+       hover    | container       | outline-variant   | on-surface-variant
+       focus    | container-low   | transparent (ring)| on-surface
+       disabled | container-low   | transparent       | neutral-low
+     "filled" reads `[data-part='editor']:not([data-empty])` DIRECTLY (no :has() indirection needed
+     — unlike text-field/textarea, whose editor is a SEPARATE part inside :scope, combo-box's
+     `[data-part='editor']` IS both the frame and the value surface); see @scope's selector below.
+     Declared here, consumed at the matching pseudo-/attribute selector in @scope (so @scope reads
+     only --ui-combo-box-*, never a role). */
+  --ui-combo-box-bg: var(--md-sys-color-neutral-container-low); /* default */
+  --ui-combo-box-bg-filled: var(--md-sys-color-neutral-container);
+  --ui-combo-box-bg-hover: var(--md-sys-color-neutral-container);
+  --ui-combo-box-bg-focus: var(--md-sys-color-neutral-container-low);
+  --ui-combo-box-border: transparent; /* default — the ring is the interactive indicator, not the border */
+  --ui-combo-box-border-hover: var(--md-sys-color-neutral-outline-variant); /* :hover — the ONE visible-border state */
+  --ui-combo-box-border-focus: transparent; /* sole focus indicator = shared outline ring */
+  /* user-invalid (ADR-0051) — the danger border, appearing only AFTER the first interaction (the
+     trackUserInvalid controller owns that timing; combo-box.ts toggles :state(user-invalid)).
+     UNCHANGED/orthogonal to the table above — never touches bg. */
+  --ui-combo-box-border-invalid: var(--md-sys-color-danger);
+  --ui-combo-box-border-invalid-hover: var(--md-sys-color-danger-high);
+  --ui-combo-box-ink: var(--md-sys-color-neutral); /* default — empty, idle */
+  --ui-combo-box-ink-filled: var(--md-sys-color-neutral-on-surface-variant);
+  --ui-combo-box-ink-hover: var(--md-sys-color-neutral-on-surface-variant);
+  --ui-combo-box-ink-focus: var(--md-sys-color-neutral-on-surface);
+  --ui-combo-box-placeholder: var(--ui-combo-box-ink); /* tracks the SAME default-state ink role dynamically (Kim's table has no separate placeholder row) — re-resolves live off whatever --ui-combo-box-ink cascades to, so the disabled repoint below reaches it for free */
+
+  /* Disabled state (TKT-0062's disabled row) — an indirection layer of -disabled-suffixed tokens
+     fed to the base bg/border/ink trio by the [disabled] block below (keeps the TKT-0047 shape). */
+  --ui-combo-box-border-disabled: transparent;
+  --ui-combo-box-bg-disabled: var(--md-sys-color-neutral-container-low);
+  --ui-combo-box-ink-disabled: var(--md-sys-color-neutral-low);
+
+  /* Frame shape */
+  --ui-combo-box-radius: var(--md-sys-shape-corner-base);
+
+  /* Min-inline-size floor (ADR-0021 entry-control lesson — must NOT be 0 or the editor
+     collapses to a zero-width typing target in a flex row, just like text-field #74). */
+  --ui-combo-box-min-inline-size: 20ch;
+
+  /* ── Listbox panel (Container/surface-class) ────────────────────────── */
+  --ui-combo-box-panel-bg: var(--md-sys-color-neutral-surface);
+  --ui-combo-box-panel-ink: var(--md-sys-color-neutral-on-surface);
+  --ui-combo-box-panel-outline: var(--md-sys-color-neutral-outline-variant);
+  --ui-combo-box-panel-radius: var(--md-sys-shape-corner-base);
+  --ui-combo-box-panel-min-inline-size: 12rem; /* prevent empty-panel collapse (ADR-0021) */
+  /* Panel-edge inset (feeds --ui-box-inset below, same mechanism as ui-select, 2026-07-06):
+     DERIVED off the editor's OWN inline text-pad (--ui-combo-box-padding-inline), which is now
+     itself the fleet h/2 standard (2026-07-06 follow-up — see the token comment above), so
+     panel-inset + option-inline (below) sum to h/2 exactly — the SAME alignment law as ui-select's
+     trigger (listbox-padding + option-inline == h/2): option text lines up under the editor's text
+     at the identical inline offset. Split evenly (h/4 + h/4), same as ui-select. NOTE: ui-combo-box
+     has no `[size]` attribute yet (a structural divergence from ui-select — flagged, not forced);
+     this is still worth deriving off the ramp now so a future `[size]` addition (its own ADR/decomp,
+     a new-attribute contract change) would make this repoint for free, same as ui-select. */
+  --ui-combo-box-listbox-padding: calc(var(--ui-combo-box-padding-inline) / 2);
+
+  /* Panel max-block-size (TKT-0027) — public dial, default min(50vh, 12 real option rows), same
+     shape as ui-select's listbox dial (the family precedent — combo-box's option row height IS
+     --ui-combo-box-height exactly, by the same row-height law: (height−font)/2 padding × 2 + font
+     == height). 12 rows = 12 option boxes + 13 inset margins (leading + 11 collapsed inter-row +
+     trailing — the panel is `[data-box]`, a BFC collapsing adjacent siblings' margins to ONE
+     inset); --ui-combo-box-listbox-padding is the value fed to --ui-box-inset below, read here
+     directly (not the DOM-positional --ui-box-inset itself). Density-invariant (height is a frame
+     quantity, geometry.md). + 2px — the panel's border-box: max-block-size caps the BORDER box
+     (box-sizing: border-box below), but the row math above computed the CONTENT box (12 rows + 13
+     insets, no border term) — without this the 12th row would overflow its own cap by exactly the
+     1px+1px border width (FIXED 2026-07-12, TKT-0027 browser-leg finding, same shape as ui-menu). */
+  --ui-combo-box-panel-max-block-size: min(50vh, calc(12 * var(--ui-combo-box-height) + 13 * var(--ui-combo-box-listbox-padding) + 2px));
+
+  /* ── Option rows (legacy item-pad — ROV-C5 / §4.6/5.1) — DERIVED (2026-07-06), same model as
+     ui-select: block-pad = (editor height − option font)/2 (the row's rendered height == the
+     editor's own height); inline-pad pairs with --ui-combo-box-listbox-padding above to total the
+     editor's own inline pad (the alignment law). Supersedes the earlier fixed --md-sys-space-xs/sm px. */
+  --ui-combo-box-option-padding-block: calc((var(--ui-combo-box-height) - var(--ui-combo-box-font)) / 2);
+  --ui-combo-box-option-padding-inline: calc(var(--ui-combo-box-padding-inline) / 2);
+  --ui-combo-box-option-font: var(--ui-combo-box-font); /* options were size-blind on FONT too (bug fix) */
+  --ui-combo-box-option-active-bg: var(--md-sys-color-neutral-tint-dim); /* active-descendant highlight — 5% neutral overlay (was the undefined -tint-5) */
+  --ui-combo-box-option-active-ink: var(--md-sys-color-neutral-on-surface);
+  --ui-combo-box-option-selected-bg: var(--md-sys-color-primary-container-low); /* selected-value row — matches ui-select's AA-safe pairing (was the undefined -tint-5) */
+  --ui-combo-box-option-selected-ink: var(--md-sys-color-primary-high);
+}
+
+/* ── disabled → muted neutral roles (TKT-0047, the select.css precedent) ──────────────────────── */
+/* TKT-0063: widened to `:is([disabled], :state(disabled))` — the own `[disabled]` attribute ALONE
+   missed the effective-disabled case (own || ancestor <fieldset disabled>/form-provider); combo-box.ts's
+   effectiveDisabled() effect now also sets :state(disabled), mirroring text-field.ts's own precedent. */
+:where(ui-combo-box:is([disabled], :state(disabled))) {
+  --ui-combo-box-border: var(--ui-combo-box-border-disabled);
+  --ui-combo-box-bg: var(--ui-combo-box-bg-disabled);
+  --ui-combo-box-ink: var(--ui-combo-box-ink-disabled);
+  --ui-combo-box-placeholder: var(--ui-combo-box-ink-disabled);
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-combo-box) ════════════════ */
+
+@scope (ui-combo-box) {
+  /* Host: inline-grid so width is the layout's job, but a min-inline-size floor prevents
+     collapse (the ADR-0021 entry-control law; same pattern as text-field + slider). */
+  :scope {
+    display: inline-grid;
+    min-inline-size: var(--ui-combo-box-min-inline-size);
+    grid-template-columns: 1fr;
+    position: relative; /* stacking context for any decorative caret pseudo */
+  }
+
+  /* ── Editor part (Control-class) ──────────────────────────────────────── */
+
+  :scope > [data-part='editor'] {
+    box-sizing: border-box;
+    /* Re-declare the placeholder alias AT THE EDITOR (TKT-0065 F13, second half of the fix): a custom
+       property resolves at computed-value time ON THE ELEMENT THAT DECLARES IT — the host-level
+       `--ui-combo-box-placeholder: var(--ui-combo-box-ink)` locks in the HOST's ink and inherits down
+       as a resolved value, so the state rules' editor-level ink repoints below never reached the
+       placeholder ::before (proven by the F13 regression test: hover/focus repainted the typed text but
+       the placeholder stayed frozen). Declaring the same alias here re-resolves it against the EDITOR's
+       own (state-repointed) ink. Own-chain read — @scope hygiene holds. Unlike text-field, whose state
+       rules live on the host itself, combo-box's frame IS the editor part, so the alias must live here. */
+    --ui-combo-box-placeholder: var(--ui-combo-box-ink);
+    /* Control-class height (block-size off the ramp, not a content-height).
+       line-height: 1 + padding-block: 0 = the text fills the box without double-spacing
+       (matches --md-sys-control-line-height, ADR-0036). */
+    min-block-size: var(--ui-combo-box-height);
+    line-height: 1;
+    padding-block: 0;
+    padding-inline: var(--ui-combo-box-padding-inline);
+
+    display: flex;
+    align-items: center;
+
+    /* FIXED (2026-07-06, found by the option-font trip-wire): `font: var(--ui-combo-box-font)` was
+       an INVALID `font` shorthand (a single value — the shorthand requires font-size AND
+       font-family at minimum), so the whole declaration was dropped and the editor silently fell
+       back to the UA default (16px) instead of the --md-sys-font-md ramp (14px). `font-size` is the
+       correct longhand — this is the same class of bug the option font-size fix below closes. */
+    font-size: var(--ui-combo-box-font);
+    background-color: var(--ui-combo-box-bg);
+    color: var(--ui-combo-box-ink);
+    border: 1px solid var(--ui-combo-box-border);
+    border-radius: var(--ui-combo-box-radius);
+    cursor: text;
+    outline: none; /* focus ring handled via :focus-visible outline on this element */
+
+    /* Prevent collapsing inline when empty — the 1fr grid column already handles host width,
+       but the editor cell can collapse its OWN inline-size if content is absent.
+       min-inline-size: 0 here (the floor is on the HOST, not the editor cell). */
+    min-inline-size: 0;
+
+    /* SINGLE-LINE (2026-07-07 fix — the initial-caret visual bug root cause): a `contenteditable`'s
+       OWN UA default is `white-space: pre-wrap` (it wraps by default — unlike a plain block/inline
+       element). Every other single-line Control-class entry field in the fleet overrides this
+       explicitly (text-field.css's editor sets the identical pair), but it was missing here. Without
+       it, the placeholder (`::before` `content: attr(data-placeholder)`) — or any typed text — wraps
+       onto a second line the moment it exceeds the field's width, growing the box past its fixed
+       `--ui-combo-box-height` (min-block-size is a floor, not a cap) and visually displacing the caret
+       relative to a now multi-line, oddly-centered placeholder block: the "caret sits oddly relative
+       to the placeholder" defect (browser-confirmed: an unconstrained-width editor with a long
+       placeholder/value silently grows taller and wraps instead of staying single-line). `overflow:
+       hidden` clips the (now guaranteed single-line) content that exceeds the box; the editor
+       self-scrolls horizontally to keep the caret in view on overflow, matching text-field. */
+    white-space: nowrap;
+    overflow: hidden;
+  }
+
+  /* Placeholder via ::before + attr(data-placeholder) (text-field pattern):
+     the [data-empty] attribute is toggled by TS when editor.textContent is empty. */
+  :scope > [data-part='editor'][data-empty]::before {
+    content: attr(data-placeholder);
+    color: var(--ui-combo-box-placeholder);
+    pointer-events: none;
+    user-select: none;
+  }
+
+  /* The filled/container state ladder (TKT-0062, Kim's ruling — supersedes the earlier border-only
+     channel) — repoints background/border-color/color together from the per-state tokens declared
+     in the :where() block (the geometry law is untouched). "filled" = the editor itself carries a
+     value (`:not([data-empty])`, the SAME emptiness signal the placeholder ::before above already
+     keys off) — read DIRECTLY on `[data-part='editor']` (no `:has()` indirection: combo-box's
+     editor IS both the frame and the value surface, unlike text-field/textarea's separate
+     editor-inside-host split).
+
+     Precedence is enforced by MUTUAL EXCLUSION (`:not()`), not source-order/specificity — the SAME
+     lesson text-field's law was fixed under (a `:not(:is(disabled))`-guarded `:hover` was measured
+     to OUTRANK an unguarded `:focus-within` by specificity, so clicking to focus — which also
+     leaves the pointer hovering — kept the hover border instead of stepping transparent, a live
+     regression that history was caught fixing). Making each rule EXPLICITLY exclude every state
+     that should outrank it removes the ambiguity regardless of computed specificity: filled
+     excludes hover/focus/disabled; hover excludes focus/disabled (fill state doesn't matter — hover
+     overrides regardless); focus is checked last (the `:not([aria-disabled='true'])` guard there is
+     defensive — `contenteditable="false"` already makes a disabled editor non-focusable,
+     combo-box.ts — so it should never actually engage). user-invalid's border-only override still
+     layers on top of whichever bg/ink row above resolved, untouched. */
+  /* NOTE (TKT-0065 lateral review, fixed — the text-field.css precedent): repointing the
+     --ui-combo-box-ink TOKEN itself, NOT a direct color: declaration — the placeholder ::before above
+     carries its own `color: var(--ui-combo-box-placeholder)`, which ALIASES the ink token; a property
+     repoint on the editor never reached it, so an EMPTY combo-box's placeholder stayed at the default
+     ink under hover/focus while text-field's repainted (proven frozen in a real Chromium+WebKit probe
+     before this fix — the exact TKT-0062 mechanic-[b] regression, one consumer over). */
+  :scope > [data-part='editor']:not(:hover):not(:focus):not([aria-disabled='true']):not([data-empty]) {
+    background-color: var(--ui-combo-box-bg-filled);
+    --ui-combo-box-ink: var(--ui-combo-box-ink-filled);
+  }
+  :scope > [data-part='editor']:not(:focus):not([aria-disabled='true']):hover {
+    background-color: var(--ui-combo-box-bg-hover);
+    border-color: var(--ui-combo-box-border-hover);
+    --ui-combo-box-ink: var(--ui-combo-box-ink-hover);
+  }
+
+  /* Focus: the shared outline ring is the SOLE indicator (matches text-field's transparent
+     border-focus approach — a coloured border-focus would double with the ring). Focus's bg/ink
+     (TKT-0062) override filled/hover unconditionally — a focused-and-filled editor still shows the
+     FOCUS row (container-low bg, on-surface ink), not filled's. */
+  :scope > [data-part='editor']:not([aria-disabled='true']):focus {
+    background-color: var(--ui-combo-box-bg-focus);
+    border-color: var(--ui-combo-box-border-focus);
+    --ui-combo-box-ink: var(--ui-combo-box-ink-focus);
+    outline: var(--md-sys-state-focus-ring-width) solid var(--md-sys-color-focus-ring);
+    outline-offset: var(--md-sys-state-focus-ring-offset);
+  }
+
+  /* user-invalid (ADR-0051) — the danger border, appearing only AFTER the first interaction. */
+  :scope:state(user-invalid) > [data-part='editor'] {
+    border-color: var(--ui-combo-box-border-invalid);
+  }
+  :scope:state(user-invalid) > [data-part='editor']:hover {
+    border-color: var(--ui-combo-box-border-invalid-hover);
+  }
+
+  /* Disabled — TKT-0047: converges on the fleet's dominant mechanism (token-repoint, not opacity).
+     The :where(ui-combo-box[disabled]) block above already repoints --ui-combo-box-border/-bg/-ink
+     (this rule's own base declarations already read those tokens) — no opacity needed. */
+  :scope > [data-part='editor'][aria-disabled='true'] {
+    cursor: default;
+    pointer-events: none;
+  }
+
+  /* ── Listbox panel (Container/surface in the top layer) ──────────────── */
+
+  :scope > [data-part='listbox'] {
+    box-sizing: border-box;
+    margin: 0; /* JS positioning controller sets position:fixed + top/left; no UA margin */
+    min-inline-size: var(--ui-combo-box-panel-min-inline-size);
+
+    background-color: var(--ui-combo-box-panel-bg);
+    color: var(--ui-combo-box-panel-ink);
+    border: 1px solid var(--ui-combo-box-panel-outline);
+    border-radius: var(--ui-combo-box-panel-radius);
+
+    /* No panel padding — options have their own padding-inline to align the ink edge */
+    padding: 0;
+    max-block-size: var(--ui-combo-box-panel-max-block-size); /* TKT-0027 — public dial, default min(50vh, 12 option rows) */
+    overflow-y: auto; /* still clips options to the panel radius (an `auto` axis clips like `hidden`, just scrollably) */
+    list-style: none;
+    /* Repoint the shared container-box.css inset LOCALLY to the size-derived value (the panel
+       carries [data-box], combo-box.ts — same mechanism as ui-select, 2026-07-06). */
+    --ui-box-inset: var(--ui-combo-box-listbox-padding);
+    font-size: var(--ui-combo-box-option-font); /* was unset (inherited ambient) — options now read the ramp */
+  }
+
+  /* ── Option rows (legacy item-pad) ───────────────────────────────────── */
+
+  :scope [role='option'] {
+    display: block;
+    margin: var(--ui-box-inset, 0.375rem); /* the box-model inset — repointed above to the size-derived value */
+    padding-block: var(--ui-combo-box-option-padding-block);
+    padding-inline: var(--ui-combo-box-option-padding-inline);
+    /* line-height: 1 makes the (height−font)/2 block-pad math exact (matches ui-select's row-height law) */
+    line-height: 1;
+    /* nested-radius (ADR-0018): the highlight corner inset from the panel by the box margin */
+    border-radius: calc(var(--ui-combo-box-panel-radius) - var(--ui-box-inset, 0.375rem));
+    cursor: pointer;
+  }
+
+  /* Active-descendant highlight: [data-active] is set by TS on the highlighted option.
+     This is the CSS face of the aria-activedescendant visual highlight — NOT :focus (focus
+     stays on the editor) but a dedicated attribute-driven style. */
+  :scope [role='option'][data-active] {
+    background-color: var(--ui-combo-box-option-active-bg);
+    color: var(--ui-combo-box-option-active-ink);
+  }
+
+  /* Selected option (aria-selected="true", set by the selection-commit pattern on prior commits) */
+  :scope [role='option'][aria-selected='true'] {
+    background-color: var(--ui-combo-box-option-selected-bg);
+    color: var(--ui-combo-box-option-selected-ink);
+  }
+
+  /* ── "No matches" row (2026-07-07 fix) ────────────────────────────────
+     Shares the option rows' EXACT geometry (margin/padding-block/line-height/radius) so the panel's
+     row-height law still holds when this is the panel's ONLY visible child — this is what gives the
+     empty panel a real, deliberate height instead of collapsing to its own border (the "stray line"
+     bug). Muted ink (the same token text-field/combo-box use for placeholder text — a neutral,
+     informational read, not an actionable row): non-interactive (`cursor: default`, no hover/active/
+     selected states — it never carries `[role=option]`, so the click/keyboard commit paths already
+     skip it structurally; `pointer-events: none` here is a defensive belt-and-suspenders). */
+  :scope [data-part='empty']:not([hidden]) {
+    display: block;
+    margin: var(--ui-box-inset, 0.375rem);
+    padding-block: var(--ui-combo-box-option-padding-block);
+    padding-inline: var(--ui-combo-box-option-padding-inline);
+    line-height: 1;
+    border-radius: calc(var(--ui-combo-box-panel-radius) - var(--ui-box-inset, 0.375rem));
+    color: var(--ui-combo-box-placeholder);
+    cursor: default;
+    pointer-events: none;
+  }
+
+  /* Hidden options (filtered out): the `hidden` HTML attribute already gives display:none
+     in the UA stylesheet — no extra rule needed. The `[hidden]` selector here is purely
+     defensive in case a UA omits the base `[hidden]` rule. */
+  :scope [role='option'][hidden] {
+    display: none;
+  }
+
+  /* ── Forced colors (WHCM) ─────────────────────────────────────────────── */
+  /* The editor frame, ink, and panel stay visible as system colours.
+     forced-color-adjust: none is NOT used — the system palette handles the field
+     correctly without it. The active-descendant highlight (Highlight/HighlightText)
+     and the focus ring (Highlight) must survive. */
+  @media (forced-colors: active) {
+    :scope > [data-part='editor'] {
+      background-color: Field;
+      color: FieldText;
+      border-color: FieldText;
+      forced-color-adjust: none;
+    }
+
+    :scope > [data-part='editor']:focus {
+      outline-color: Highlight;
+    }
+
+    :scope > [data-part='listbox'] {
+      background-color: Canvas;
+      color: CanvasText;
+      border-color: CanvasText;
+    }
+
+    :scope [role='option'][data-active] {
+      background-color: Highlight;
+      color: HighlightText;
+      forced-color-adjust: none;
+    }
+  }
+}

package/dist/controls/combo-box/combo-box.d.ts

@@ -0,0 +1,133 @@
+import { type ReactiveProps } from '../../dom/index.js';
+import { UIFormElement, type FormValue, type ValidityResult, type FieldLabelling } from '../../dom/form.js';
+import { type OverlayHandle } from '../../traits/overlay.js';
+declare const props: {
+    value: import("../../index.js").PropConfig<string>;
+    label: {
+        reflect: true;
+        type: import("../../index.js").PropType<string>;
+        default: string;
+        attribute?: string | false;
+    };
+    open: {
+        reflect: true;
+        type: import("../../index.js").PropType<boolean>;
+        default: boolean;
+        attribute?: string | false;
+    };
+    strict: {
+        reflect: true;
+        type: import("../../index.js").PropType<boolean>;
+        default: boolean;
+        attribute?: string | false;
+    };
+    placeholder: import("../../index.js").PropConfig<string>;
+    name: {
+        reflect: true;
+        type: import("../../index.js").PropType<string>;
+        default: string;
+        attribute?: string | false;
+    };
+    disabled: {
+        reflect: true;
+        type: import("../../index.js").PropType<boolean>;
+        default: boolean;
+        attribute?: string | false;
+    };
+    required: {
+        reflect: true;
+        type: import("../../index.js").PropType<boolean>;
+        default: boolean;
+        attribute?: string | false;
+    };
+};
+export interface UIComboBoxElement extends ReactiveProps<typeof props> {
+}
+export declare class UIComboBoxElement extends UIFormElement {
+    #private;
+    static props: {
+        value: import("../../index.js").PropConfig<string>;
+        label: {
+            reflect: true;
+            type: import("../../index.js").PropType<string>;
+            default: string;
+            attribute?: string | false;
+        };
+        open: {
+            reflect: true;
+            type: import("../../index.js").PropType<boolean>;
+            default: boolean;
+            attribute?: string | false;
+        };
+        strict: {
+            reflect: true;
+            type: import("../../index.js").PropType<boolean>;
+            default: boolean;
+            attribute?: string | false;
+        };
+        placeholder: import("../../index.js").PropConfig<string>;
+        name: {
+            reflect: true;
+            type: import("../../index.js").PropType<string>;
+            default: string;
+            attribute?: string | false;
+        };
+        disabled: {
+            reflect: true;
+            type: import("../../index.js").PropType<boolean>;
+            default: boolean;
+            attribute?: string | false;
+        };
+        required: {
+            reflect: true;
+            type: import("../../index.js").PropType<boolean>;
+            default: boolean;
+            attribute?: string | false;
+        };
+    };
+    /** Protected overlay handle — used for the C10 cleanup probe. */
+    protected _overlayHandle: OverlayHandle | null;
+    focus(options?: FocusOptions): void;
+    protected connected(): void;
+    /**
+     * The value this combo-box contributes to its form.
+     * '' (nothing committed) → null (no form entry submitted, matching the native <select> convention).
+     */
+    protected formValue(): FormValue;
+    /**
+     * The validity verdict:
+     * - disabled → always valid (native parity: disabled controls bypass constraint validation).
+     * - required && value==='' → valueMissing.
+     * - strict && value!=='' && no matching option → typeMismatch (the typed value is not in the set).
+     */
+    protected formValidity(): ValidityResult;
+    /** Form reset → restore value ← defaultValue, clear the editor, reset filter + active. */
+    protected formReset(): void;
+    protected disconnected(): void;
+    /** Feeds `FormConnectDetail.userInvalid` (ADR-0050) — the `trackUserInvalid` tracker IS the one
+     *  timing source; this override just exposes its gate. */
+    protected formUserInvalid(): boolean;
+    /** Restore value after navigation / autofill. */
+    protected formStateRestore(state: File | string | FormData | null): void;
+    /**
+     * The part-role override (ADR-0085 cl.3 · text-field.ts:662 precedent) — the combobox role rides the
+     * light-DOM editor PART, not `internals.role`, so the base's guarded internals-reflection default
+     * (dom/form.ts) never fires; id-reference the editor directly instead.
+     *
+     * `aria-labelledby` is this method's own, exclusive concern in both directions: set from `refs.label`
+     * when present, removed when `null` (matching text-field exactly).
+     *
+     * `aria-describedby` is ALSO this method's exclusive concern in both directions here — UNLIKE
+     * text-field, this control has no internal validity-MESSAGE node/effect competing for the
+     * attribute (the ADR-0051 user-invalid leg below writes only `:state(user-invalid)` +
+     * `aria-invalid`, never `aria-describedby`), so there is no dual-writer race to avoid by leaving
+     * it untouched on dissociation; it is written from `[refs.description, refs.error]` when fielded
+     * and cleared when not, in both branches below.
+     *
+     * Guards a not-yet-created editor (the LLD-C2 override contract) — cannot happen in practice
+     * (`#ensureParts()` runs synchronously at the top of `connected()`, before the base's forwarding effect
+     * installs), but the guard costs nothing and documents the contract.
+     */
+    protected applyFieldLabelling(refs: FieldLabelling | null): void;
+}
+export {};