@agent-ui-kit/components 0.0.3

package/dist/controls/select/select.css

@@ -0,0 +1,467 @@
+/* select.css — ui-select, the single-file component stylesheet (ADR-0003).
+ * Two clearly-SECTIONED blocks, mirroring button.css / text-field.css / popover.css:
+ *
+ *   [1] TOKEN BLOCK  — `:where(ui-select)` (specificity 0,0,0) DECLARES the `--ui-select-*`
+ *       chain from the colour roles (`--md-sys-color-{family}-{role}`; family = neutral for the trigger frame)
+ *       and the dimensional ramp (`--md-sys-height-{size}` / `--md-sys-font-{size}` / `--md-sys-icon-{size}`).
+ *       The trigger is a Control-class surface carrying Kim's filled/container state law (TKT-0062,
+ *       superseding the ADR-0014 cl.2c border-only channel) — background/border/text-ink ALL repoint
+ *       per state (default/filled/hover/focus/disabled; "filled" = a real selection, via a NEW
+ *       `[data-empty]` toggle select.ts's label effect now maintains); a caret = font inline
+ *       affordance, §4.1. The listbox
+ *       panel is a Container/surface (bg + outline + radius + padding — NOT a control height). The
+ *       option rows use the legacy item-pad model (§5.1 / ROV-C5: padding-based row height, NOT
+ *       the --md-sys-compact widget box — option rows are text items, not stand-alone widgets) — but
+ *       (2026-07-06) the item-pad's own NUMBERS are now DERIVED off the trigger ramp
+ *       (`--ui-select-height`/`--ui-select-font`), superseding the earlier fixed-px item-pad
+ *       (6px/12px): panel inset + option padding now scale with `[size]` the same as the trigger,
+ *       and option text aligns under the trigger label (listbox-padding + option-inline == h/2).
+ *       `[size]` repoints the geometry (trigger AND, transitively via the shared height/font
+ *       tokens, the panel/options — no separate [size] block needed for the panel).
+ *   [2] STYLES BLOCK — `@scope (ui-select)` CONSUMES only `--ui-select-*` for its OWN tokens.
+ *       The host is `display: inline-block` with a min-inline-size floor (the ADR-0021 lesson:
+ *       a control that can be empty needs a floor; the trigger inherits full width from the host).
+ *       The trigger is `display: inline-grid; grid-template-columns: 1fr auto` — always a
+ *       [label | caret] anatomy (the trailing caret slot is always present, so the grid is fixed
+ *       at two columns). The caret span is an icon-sized cell (the CELL stays icon-sized for both
+ *       icon and caret roles; only the GLYPH inside differs — padding: (icon−glyph)/2 centers the
+ *       font-sized glyph in the icon cell, the §4.1 caret centering law). The listbox panel uses
+ *       the overlay controller's position:fixed + inset (we do NOT fix position here). Option rows
+ *       get hover/selected/focus states; focus ring on :focus-visible (real DOM focus via rovingFocus).
+ *       Forced-colors keeps the trigger frame, label, and panel surface visible as system colours.
+ *
+ * Standalone stylesheet — NOT injected from select.ts (behaviour-only `.ts`, no runtime injection
+ * per plan §2). Linked via the component-styles barrel (s12); the barrel @imports foundation roles
+ * FIRST. The listbox's `popover` attribute (set by the overlay controller) gives it `display: none`
+ * in the UA stylesheet until `showPopover()` places it in the top layer.
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-select) declares --ui-select-* ════════════════ */
+
+:where(ui-select) {
+  /* ── Trigger frame — Kim's filled/container state law (TKT-0062), SUPERSEDING the ADR-0014
+     cl.2c border-only channel: bg/border/ink ALL repoint per state now (default/filled/hover/
+     focus/disabled — same table as text-field/textarea/combo-box). "filled" = the trigger shows a
+     real selection, not the placeholder (`[data-empty]`, a NEW toggle this ticket added to
+     select.ts's own label effect — select previously had no emptiness hook at all, unlike its
+     siblings). Focus = transparent: the shared outline ring is the SOLE focus indicator (ADR-0014
+     dev#1; a border-focus step doubles with the ring). */
+  --ui-select-bg: var(--md-sys-color-neutral-container-low); /* default */
+  --ui-select-bg-filled: var(--md-sys-color-neutral-container);
+  --ui-select-bg-hover: var(--md-sys-color-neutral-container);
+  --ui-select-bg-focus: var(--md-sys-color-neutral-container-low);
+  --ui-select-border: transparent; /* default */
+  --ui-select-border-hover: var(--md-sys-color-neutral-outline-variant); /* the ONE visible-border state */
+  --ui-select-border-focus: transparent;    /* transparent holds the geometry — no layout shift */
+  /* user-invalid (ADR-0051) — the danger border, appearing only AFTER the first interaction (the
+     trackUserInvalid controller owns that timing; select.ts toggles :state(user-invalid)). The
+     text-field precedent, on the trigger's border channel — UNCHANGED, orthogonal to the table above. */
+  --ui-select-border-invalid: var(--md-sys-color-danger);
+  --ui-select-border-invalid-hover: var(--md-sys-color-danger-high);
+  --ui-select-ink: var(--md-sys-color-neutral); /* default — showing the placeholder */
+  --ui-select-ink-filled: var(--md-sys-color-neutral-on-surface-variant);
+  --ui-select-ink-hover: var(--md-sys-color-neutral-on-surface-variant);
+  --ui-select-ink-focus: var(--md-sys-color-neutral-on-surface);
+  --ui-select-radius: var(--md-sys-shape-corner-base); /* fixed rounded-rect radius, like text-field */
+
+  /* ── Trigger geometry (Control class, default size = md) — off the §1-row ramp (ADR-0038).
+     height/font/icon from the explicit per-[scale] table; gap = font/2 × density (on `*`).
+     The caret (inline affordance) follows the §4.1 law: glyph size = font (RHYTHM family,
+     not frame) → glyph is font-sized, centred in the icon cell by padding=(icon−glyph)/2. */
+  --ui-select-height: var(--md-sys-height-md);
+  --ui-select-font: var(--md-sys-font-md);
+  --ui-select-gap: var(--md-sys-gap-md);          /* the density-bearing column-gap */
+  --ui-select-icon: var(--md-sys-icon-md);        /* the icon-cell size (caret CELL is icon-wide) */
+  --ui-select-glyph: var(--ui-select-font);   /* caret GLYPH = font (§4.1 caret law) */
+
+  /* ── Sizing floor (ADR-0021 lesson) — a select with no selection or an empty placeholder
+     needs a floor so it is hittable and the overlay positions against a real anchor rect. */
+  --ui-select-min-inline-size: 10ch;
+
+  /* ── Disabled state — TKT-0062's disabled row (bg=container-low, border=transparent, ink=neutral-low) */
+  --ui-select-border-disabled: transparent;
+  --ui-select-bg-disabled: var(--md-sys-color-neutral-container-low);
+  --ui-select-ink-disabled: var(--md-sys-color-neutral-low);
+
+  /* ── Listbox panel — Container/surface geometry (NOT a control height; like modal/card/popover) */
+  --ui-select-listbox-bg: var(--md-sys-color-neutral-surface);
+  --ui-select-listbox-ink: var(--md-sys-color-neutral-on-surface);
+  --ui-select-listbox-outline: var(--md-sys-color-neutral-outline-variant);
+  --ui-select-listbox-radius: var(--md-sys-shape-corner-base);
+  /* ── The size-carrying derivation (supersedes the fixed "legacy item-pad" px, 2026-07-06) ──────
+     ROV-C5/ADR-0043 cl.5 keep options OUT of the h/2 "comfortable control" model and the
+     `--md-sys-compact` widget box — that boundary is unchanged. What changes: the item-pad's OWN
+     numbers are now DERIVED off the trigger's `--ui-select-height`/`--ui-select-font` (the same
+     ramp the trigger already repoints at `[size=sm|lg]`) instead of hand-picked fixed px, so the
+     panel inset + option row scale WITH the trigger — no new sm/lg blocks needed; the calc()s
+     below repoint for free.
+       • Alignment law: listbox-padding + option-inline == h/2, so option text starts at the same
+         inline offset from the panel's outer edge as the trigger label does from the trigger's
+         edge (h/2) — text lines up under text. Split evenly (h/4 + h/4).
+       • Row-height law: option-block == (h − font)/2 — the SAME (height−glyph)/2 centering law
+         (geometry.md), applied on the block axis to the option's own text (glyph = font here) —
+         so the option row's rendered content-box height == the trigger height exactly, and both
+         grow together under [size]. */
+  --ui-select-listbox-padding: calc(var(--ui-select-height) / 4); /* panel-edge inset + inter-row gap (feeds --ui-box-inset below) */
+  --ui-select-listbox-min-inline-size: 12ch;       /* floor: at least as wide as a short option */
+
+  /* Panel max-block-size (TKT-0027) — public dial, default min(50vh, 12 real option rows): the
+     smaller of half the viewport or a scannable dozen rows, replacing the old flat 40vh magic
+     number. An option row's rendered height IS --ui-select-height exactly (the row-height law
+     above: (h−font)/2 padding × 2 + font == h, line-height:1 makes it exact) — no separate item-
+     block token needed, unlike ui-menu (which has no analogous control height to reuse). 12 rows
+     = 12 option boxes + 13 inset margins (leading + 11 collapsed inter-row + trailing — the
+     listbox is `[data-box]`, a BFC that collapses adjacent siblings' margins to ONE inset, never
+     doubled); --ui-select-listbox-padding IS the value fed to --ui-box-inset below, so this reads
+     the same source, not the DOM-positional --ui-box-inset itself. Rides [size]/[scale] naturally
+     (both terms derive from --ui-select-height); density-invariant, like the trigger height itself
+     (geometry.md: height is a frame quantity, not rhythm). + 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-select-listbox-max-block-size: min(50vh, calc(12 * var(--ui-select-height) + 13 * var(--ui-select-listbox-padding) + 2px));
+
+  /* ── Option rows — legacy item-pad (§5.1 / ROV-C5): padding-based row height, NOT a fixed
+     --md-sys-compact widget box. Options are text list items, not stand-alone widgets. The row
+     radius is inset from the listbox shell radius (nested-radius: shell − padding, ADR-0018). */
+  --ui-select-option-block: calc((var(--ui-select-height) - var(--ui-select-font)) / 2); /* (h−font)/2 — row height == trigger height */
+  --ui-select-option-inline: calc(var(--ui-select-height) / 4);            /* h/4 — pairs with listbox-padding to total h/2 */
+  --ui-select-option-font: var(--ui-select-font);   /* options were size-blind on FONT too (bug fix) — now the ramp */
+  --ui-select-option-radius: calc(var(--ui-select-listbox-radius) - var(--ui-select-listbox-padding)); /* nested-radius off the REAL inset (was a hardcoded 4px, ADR-0018) */
+  --ui-select-option-bg-hover: var(--md-sys-color-neutral-surface-high);
+  --ui-select-option-bg-selected: var(--md-sys-color-primary-container-low);
+  --ui-select-option-ink-selected: var(--md-sys-color-primary-high);
+  --ui-select-option-bg-focus: var(--md-sys-color-primary-container-low);
+  --ui-select-option-ink-focus: var(--md-sys-color-primary-high);
+
+  /* ── Group header (optgroup parity) — a non-interactive label above a [role=group]'s options.
+     Muted, small, slightly emphasised; the option rows below it keep the standard item-pad. */
+  --ui-select-group-label-ink: var(--md-sys-color-neutral-on-surface-variant);
+}
+
+/* ── size → dimensional ramp repoint ────────────────────────────────────────────────────────── */
+
+:where(ui-select[size='sm']) {
+  --ui-select-height: var(--md-sys-height-sm);
+  --ui-select-font: var(--md-sys-font-sm);
+  --ui-select-gap: var(--md-sys-gap-sm);
+  --ui-select-icon: var(--md-sys-icon-sm);
+}
+
+:where(ui-select[size='lg']) {
+  --ui-select-height: var(--md-sys-height-lg);
+  --ui-select-font: var(--md-sys-font-lg);
+  --ui-select-gap: var(--md-sys-gap-lg);
+  --ui-select-icon: var(--md-sys-icon-lg);
+}
+
+/* ── disabled → muted neutral roles ────────────────────────────────────────────────────────── */
+/* TKT-0063: widened to `:is([disabled], :state(disabled))` — the own `[disabled]` attribute ALONE
+   missed the effective-disabled case (own || ancestor <fieldset disabled>/form-provider); select.ts's
+   effectiveDisabled() effect now also sets :state(disabled), mirroring text-field.ts's own precedent. */
+:where(ui-select:is([disabled], :state(disabled))) {
+  --ui-select-border: var(--ui-select-border-disabled);
+  --ui-select-bg: var(--ui-select-bg-disabled);
+  --ui-select-ink: var(--ui-select-ink-disabled);
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-select) consumes ONLY --ui-select-* ════════════════ */
+
+@scope (ui-select) {
+  /* The host: an inline-block with a min-inline-size floor. The trigger child fills the host
+     width (width: 100%) so the select is as wide as its container or at least 10ch. */
+  :scope {
+    display: inline-block;
+    min-inline-size: var(--ui-select-min-inline-size);
+    vertical-align: middle; /* align with adjacent form controls (like a native <select>) */
+  }
+
+  /* The trigger button (Control class): a [label | caret] inline-grid. The trigger ALWAYS
+     has the caret trailing — unlike button.css which is presence-driven. So the grid is fixed
+     at two columns: 1fr (the label grows to fill) + auto (the caret icon cell). The label side
+     gets the h/2 start pad; the caret side gets the ½(h−icon) end pad (same as a trailing slot
+     in button.css — the icon-cell-edge law). block-size is the Control-class ramp height.
+     line-height: 1 (ADR-0036 single-line control standard — the glyph is centred by the frame). */
+  :scope > [data-part='trigger'] {
+    display: inline-grid;
+    grid-template-columns: 1fr auto;
+    column-gap: var(--ui-select-gap);
+    align-items: center;
+    box-sizing: border-box;
+    width: 100%; /* fill the host's inline-size */
+
+    block-size: var(--ui-select-height);
+    padding-block: 0; /* NEVER block padding — geometry law */
+    padding-inline-start: calc(var(--ui-select-height) / 2);   /* h/2 label edge */
+    padding-inline-end: calc((var(--ui-select-height) - var(--ui-select-icon)) / 2); /* ½(h−icon) caret edge */
+    min-inline-size: 0; /* allow the trigger to shrink within a narrow host (the host sets the floor) */
+
+    font-size: var(--ui-select-font);
+    line-height: var(--md-sys-control-line-height); /* single-line control standard (ADR-0036) */
+    background: var(--ui-select-bg);
+    color: var(--ui-select-ink);
+    border: 1px solid var(--ui-select-border);
+    border-radius: var(--ui-select-radius);
+    cursor: pointer;
+    text-align: start;
+    -webkit-user-select: none;
+    user-select: none;
+  }
+
+  /* The label span: fills the 1fr column; clipped for overflow. */
+  :scope > [data-part='trigger'] > [data-part='label'] {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  /* The aria-label span (ADR-0085): visually-hidden, always present (idempotent-parts precedent) —
+     referenced by the trigger's aria-labelledby only when `label` is set and the control is unfielded.
+     The standard CLIP technique, not `hidden`/`display:none` — some AT/engine combinations do not
+     reliably fold a display:none-referenced node's text into the accessible-name computation for an
+     aria-labelledby reference, while the clip approach is the robust cross-engine convention. */
+  :scope > [data-part='aria-label'] {
+    position: absolute;
+    inline-size: 1px;
+    block-size: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+
+  /* The caret span: an icon-sized CELL (box-sizing border-box). The glyph inside is font-sized
+     and centred by padding = ½(icon − glyph), the §4.1 caret law (same as button.css [data-role='caret']).
+     aria-hidden is set in select.ts; the glyph is decorative. */
+  :scope > [data-part='trigger'] > [data-part='caret'] {
+    inline-size: var(--ui-select-icon);
+    block-size: var(--ui-select-icon);
+    box-sizing: border-box;
+    padding: calc((var(--ui-select-icon) - var(--ui-select-glyph)) / 2);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: var(--ui-select-glyph); /* the caret glyph = font (§4.1) */
+    line-height: 1;
+  }
+
+  /* The injected Phosphor caret-down (setIcon, @agent-ui-kit/icons): sized explicitly to the glyph
+     rhythm — not the icon cell — so the §4.1 law holds independent of the padding math above
+     (the padding already insets to the same value; this is belt-and-suspenders, not reliance on
+     it). Overrides the svg's own width/height="100%" presentational attributes (resolve.ts). */
+  :scope > [data-part='trigger'] > [data-part='caret'] svg {
+    display: block;
+    inline-size: var(--ui-select-glyph);
+    block-size: var(--ui-select-glyph);
+  }
+
+  /* Trigger filled/container state law (TKT-0062, Kim's ruling — supersedes the ADR-0014 cl.2c
+     border-only channel) — repoints background/border-color/color together. "filled" = the trigger
+     shows a real selection (`[data-part='trigger']:not([data-empty])` — the NEW toggle select.ts's
+     label effect now maintains). Precedence is enforced by MUTUAL EXCLUSION (`:not()`), never
+     source-order/specificity (the lesson from text-field.css's own build: a disabled-guarded `:hover`
+     measured HIGHER specificity than an unguarded focus selector, so a mouse-click focus — which also
+     leaves the pointer hovering — kept the wrong state painted). `[disabled]` is checked directly on
+     the TRIGGER (select.ts already collapses own-disabled OR form-disabled onto the trigger's own
+     attribute — `trigger.setAttribute('disabled', ...)` in the effectiveDisabled() effect — so no
+     separate `:state(disabled)` check is needed here, unlike text-field/textarea/combo-box). */
+  :scope > [data-part='trigger']:not(:hover):not(:focus-visible):not([disabled]):not([data-empty]) {
+    background: var(--ui-select-bg-filled);
+    color: var(--ui-select-ink-filled);
+  }
+  :scope > [data-part='trigger']:not(:focus-visible):not([disabled]):hover {
+    background: var(--ui-select-bg-hover);
+    border-color: var(--ui-select-border-hover);
+    color: var(--ui-select-ink-hover);
+  }
+
+  :scope > [data-part='trigger']:focus-within,
+  :scope > [data-part='trigger']:focus-visible {
+    outline: none; /* the outline ring below replaces the UA default */
+  }
+
+  /* Focus (keyboard-only :focus-visible, the button precedent — a trigger is an action control, not a
+     text-entry surface) wins over filled/hover unconditionally; a disabled trigger cannot be focused,
+     so no guard is needed here (matching the old law). */
+  :scope > [data-part='trigger']:focus-visible {
+    background: var(--ui-select-bg-focus);
+    border-color: var(--ui-select-border-focus);
+    color: var(--ui-select-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='trigger'] {
+    border-color: var(--ui-select-border-invalid);
+  }
+  :scope:state(user-invalid) > [data-part='trigger']:hover {
+    border-color: var(--ui-select-border-invalid-hover);
+  }
+
+  /* Disabled trigger: pointer-inert; :hover/:active become inert. The trigger is a REAL native
+     <button> whose own `disabled` attribute select.ts already sets from effectiveDisabled() (own ||
+     form-disabled) — a native disabled button is platform-inert regardless of this rule, so
+     `pointer-events: none` here is defensive-only; `:state(disabled)` (TKT-0063) widens the match so
+     `cursor: default` also applies under the form-disabled-only case, not just the host's own
+     `[disabled]` attribute. */
+  :scope:is([disabled], :state(disabled)) > [data-part='trigger'] {
+    pointer-events: none;
+    cursor: default;
+  }
+
+  /* ── The listbox panel (Container/surface in the Popover API top layer) ───────────────────────
+     The UA `[popover]` rule hides this with display:none until showPopover(). The overlay
+     controller sets position:fixed + inset on open — we do NOT set position here. `margin: 0`
+     prevents UA-default centering from conflicting with the controller's explicit placement. */
+  :scope > [data-part='listbox'] {
+    box-sizing: border-box;
+    margin: 0;
+    min-inline-size: var(--ui-select-listbox-min-inline-size);
+    /* Matching the trigger width is done in JS (see select.ts model→overlay effect): in the
+       Popover API top layer `100%` resolves to 100vw (the viewport), NOT the trigger width.
+       select.ts stamps `listbox.style.minInlineSize = triggerWidth + 'px'` before showPopover(). */
+    max-block-size: var(--ui-select-listbox-max-block-size); /* TKT-0027 — public dial, default min(50vh, 12 option rows) */
+    overflow-y: auto;
+
+    background-color: var(--ui-select-listbox-bg);
+    color: var(--ui-select-listbox-ink);
+    border: 1px solid var(--ui-select-listbox-outline);
+    border-radius: var(--ui-select-listbox-radius);
+    padding: 0; /* the box-model child margins provide the inset (container-box.css); no shell padding */
+    /* Repoint the shared container-box.css inset LOCALLY to the size-derived value (the panel
+       carries [data-box], see select.ts — that rule declares --ui-box-inset: 0.375rem at
+       specificity 0; this higher-specificity declaration on the same element overrides it so
+       the size-carrying model owns the value fed to the rows' margin + the nested-radius calc
+       below, instead of the shared fleet-wide 6px fallback every [data-box] otherwise gets). */
+    --ui-box-inset: var(--ui-select-listbox-padding);
+    font-size: var(--ui-select-option-font); /* was unset (inherited ambient) — options + the group label now read the ramp */
+  }
+
+  /* ── Option rows (legacy item-pad — §5.1 / ROV-C5) ──────────────────────────────────────────
+     Options are text list items with padding-based row height (not a fixed widget-box height).
+     rovingFocus manages tabindex (0 = roving current, -1 = others). The focus ring on :focus-visible
+     is the fleet ring (the direct --md-sys-color-focus-ring read, the one permitted exception — same as button). */
+  :scope > [data-part='listbox'] [role='option'] {
+    box-sizing: border-box;
+    display: block;
+    margin: var(--ui-box-inset, 0.375rem); /* the box-model inset — repointed above to the size-derived value */
+    padding-block: var(--ui-select-option-block);
+    padding-inline: var(--ui-select-option-inline);
+    /* line-height: 1 makes the (h−font)/2 block-pad math exact — font + 2×pad == the trigger
+       height, so the row's rendered content-box is literally the SAME height as the control that
+       opened it (the row-height law above), not the DoD's Control-class line-height rule (that
+       one is scoped to Control-class elements; this is a local derivation choice for item rows). */
+    line-height: 1;
+    border-radius: var(--ui-select-option-radius);
+    cursor: pointer;
+    -webkit-user-select: none;
+    user-select: none;
+    outline: none; /* suppress the default UA outline — :focus-visible provides the ring below */
+  }
+
+  /* Groups are STRUCTURAL, not visible boxes — full-bleed (no inset margin); their options + sticky header
+     carry the box rhythm. (Overrides the shared `[data-box] > *` margin for the group wrapper.) */
+  :scope > [data-part='listbox'] > [role='group'] {
+    margin: 0;
+    display: block;
+  }
+
+  /* Group header (optgroup parity) — a non-interactive label; NOT a [role=option], so rovingFocus +
+     selectionCommit skip it. STICKY: pins to the panel's scroll top and takes the panel surface so scrolled
+     options never show through (the container box-model region pattern). Full-bleed edge-to-edge. */
+  :scope > [data-part='listbox'] [data-part='group-label'] {
+    box-sizing: border-box;
+    display: block;
+    position: sticky;
+    inset-block-start: 0;
+    z-index: 1;
+    margin: 0; /* full-bleed — spans the panel width so the sticky surface fully occludes scrolled rows */
+    padding-block: var(--ui-select-option-block);
+    padding-inline: var(--ui-select-option-inline);
+    background-color: var(--ui-select-listbox-bg); /* the panel surface — occludes scrolled content */
+    color: var(--ui-select-group-label-ink);
+    font-size: 0.85em;
+    font-weight: 600;
+    letter-spacing: 0.02em;
+    cursor: default;
+    -webkit-user-select: none;
+    user-select: none;
+  }
+
+  /* A group after the first gets a hairline divider above it (visual grouping between sticky sections). */
+  :scope > [data-part='listbox'] > [role='group'] + [role='group'] {
+    border-block-start: 1px solid var(--ui-select-listbox-outline);
+  }
+
+  :scope > [data-part='listbox'] [role='option']:hover {
+    background-color: var(--ui-select-option-bg-hover);
+  }
+
+  :scope > [data-part='listbox'] [role='option'][aria-selected='true'] {
+    background-color: var(--ui-select-option-bg-selected);
+    color: var(--ui-select-option-ink-selected);
+  }
+
+  :scope > [data-part='listbox'] [role='option']:focus-visible {
+    background-color: var(--ui-select-option-bg-focus);
+    color: var(--ui-select-option-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);
+  }
+
+  /* Disabled option — not interactive; rovingFocus skips disabled items. */
+  :scope > [data-part='listbox'] [role='option'][aria-disabled='true'],
+  :scope > [data-part='listbox'] [role='option'][disabled] {
+    color: var(--ui-select-ink-disabled);
+    cursor: default;
+    pointer-events: none;
+  }
+
+  /* ── Motion (state-PAINT only; geometry snaps — ADR-0008) ─────────────────────────────────── */
+
+  :scope > [data-part='trigger']:state(ready) {
+    transition:
+      background-color var(--md-sys-motion-duration-fast) var(--md-sys-motion-easing-standard),
+      border-color var(--md-sys-motion-duration-fast) var(--md-sys-motion-easing-standard),
+      color var(--md-sys-motion-duration-fast) var(--md-sys-motion-easing-standard);
+  }
+  @media (prefers-reduced-motion: reduce) {
+    :scope > [data-part='trigger']:state(ready) {
+      transition: none;
+    }
+  }
+
+  /* ── forced-colors (WHCM) ─────────────────────────────────────────────────────────────────── */
+
+  @media (forced-colors: active) {
+    /* Trigger: keep ink and border as system ButtonText/ButtonBorder; background stays as
+       ButtonFace. The focus ring survives via --md-sys-color-focus-ring → Highlight. */
+    :scope > [data-part='trigger'] {
+      color: ButtonText;
+      border-color: ButtonBorder;
+      background: ButtonFace;
+      forced-color-adjust: none; /* preserve our explicit border/bg/color from the OS wash */
+    }
+
+    /* Panel: Canvas/CanvasText for the surface; CanvasText for the border. */
+    :scope > [data-part='listbox'] {
+      background-color: Canvas;
+      color: CanvasText;
+      border-color: CanvasText;
+      forced-color-adjust: none;
+    }
+
+    /* Option selected/hover: Highlight/HighlightText (system selection colours). */
+    :scope > [data-part='listbox'] [role='option']:hover,
+    :scope > [data-part='listbox'] [role='option'][aria-selected='true'],
+    :scope > [data-part='listbox'] [role='option']:focus-visible {
+      background-color: Highlight;
+      color: HighlightText;
+      forced-color-adjust: none;
+    }
+  }
+}

package/dist/controls/select/select.d.ts

@@ -0,0 +1,147 @@
+import { type ReactiveProps } from '../../dom/index.js';
+import { UIFormElement } from '../../dom/index.js';
+import type { FormValue, ValidityResult, FieldLabelling } from '../../dom/index.js';
+import { type OverlayHandle } from '../../traits/overlay.js';
+declare const props: {
+    value: {
+        reflect: true;
+        type: import("../../index.js").PropType<string>;
+        default: string;
+        attribute?: string | false;
+    };
+    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;
+    };
+    placeholder: {
+        type: import("../../index.js").PropType<string>;
+        default: string;
+        attribute?: string | false;
+        reflect?: boolean;
+    };
+    size: {
+        reflect: true;
+        type: import("../../index.js").PropType<"sm" | "md" | "lg">;
+        default: "sm" | "md" | "lg";
+        attribute?: string | false;
+    };
+    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 UISelectElement extends ReactiveProps<typeof props> {
+}
+export declare class UISelectElement extends UIFormElement {
+    #private;
+    static props: {
+        value: {
+            reflect: true;
+            type: import("../../index.js").PropType<string>;
+            default: string;
+            attribute?: string | false;
+        };
+        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;
+        };
+        placeholder: {
+            type: import("../../index.js").PropType<string>;
+            default: string;
+            attribute?: string | false;
+            reflect?: boolean;
+        };
+        size: {
+            reflect: true;
+            type: import("../../index.js").PropType<"sm" | "md" | "lg">;
+            default: "sm" | "md" | "lg";
+            attribute?: string | false;
+        };
+        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 — accessible to test probes (C10 idempotent-cleanup DoD).
+     * Replaced on each reconnect (connected() re-runs); the old handle's cleanup fires via the
+     * scope effect disposer at disconnect before this is re-assigned.
+     */
+    protected _overlayHandle: OverlayHandle | null;
+    protected formValue(): FormValue;
+    protected formValidity(): ValidityResult;
+    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;
+    /**
+     * The part-role override (ADR-0085 cl.4) — the trigger carries no `internals.role` (a logical select
+     * wrapper), so the base's guarded internals-reflection default (dom/form.ts) never fires; wire the
+     * trigger's `aria-labelledby`/`aria-describedby` content attributes directly instead (the text-field
+     * `applyFieldLabelling` precedent, ADR-0051 cl.2/LLD-C2).
+     *
+     * `aria-labelledby` is the BARE-mode effect's (connected(), below) exclusive concern whenever
+     * `fieldLabelling === null` — this override never touches it on dissociation (`refs === null`), so the
+     * two effects can never race to write the SAME attribute in the same flush wave (the F3 dual-writer
+     * discipline text-field's own override documents). While fielded (`refs !== null`), THIS method is the
+     * exclusive writer: MERGE, never clobber — `<refs.label.id> <value-span-id>` (field label + value),
+     * the same two-id shape as the bare path, only the name source swaps.
+     *
+     * `aria-describedby` has NO other owner for this control (the trigger carries no internal
+     * validity-message node, unlike text-field's editor) — so unlike text-field's override, THIS one is the
+     * describedby's exclusive owner in BOTH directions: written from `[refs.description, refs.error]` when
+     * fielded, cleared on dissociation.
+     *
+     * Guards a not-yet-created trigger (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;
+    protected connected(): void;
+}
+export {};