@adia-ai/web-components 0.7.16 → 0.7.18

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog — @adia-ai/web-components
 
+## [0.7.18] — 2026-06-09
+
+### Changed
+- **Clear caret OPEN state across the dropdown family.** Every dropdown-class primitive's caret now flips 180° while its popover/listbox is open (and returns on close), with a fast reduced-motion-respecting transition: `select-ui` (its trigger glyph also changed `caret-up-down` → `caret-down` to join the family convention), `combobox-ui`, `datetime-picker-ui`, `date-range-picker-ui`, and `menu-ui` (a consumer trigger carrying a `caret-down` icon — e.g. `<button-ui icon-trailing="caret-down">` — flips automatically). All rules are **name-guarded** (`icon-ui[name="caret-down"]`) so custom non-caret trigger/suffix glyphs never rotate. Disclosure-row components already had clear states (nav-group/tree/pane/agent-trace rotate 90°, agent-reasoning/agent-artifact swap glyphs, accordion rotates) and are unchanged; `table-toolbar`'s `caret-up-down` is a sort indicator and `calendar-picker`'s carets are month-nav arrows — deliberately excluded. Regression harness: `scripts/dev/caret-open-state-probe.mjs` (15 browser assertions: renders / flips 180° / returns, per component).
+
+### Fixed
+- **`datetime-picker-ui` / `date-range-picker-ui` — the default trigger's caret now actually renders.** Both default triggers declared `trailing-icon="caret-down"`, but `button-ui`'s attribute is `icon-trailing` — the made-up attribute was silently ignored (the silent-failure-on-unknown-attrs class), so the caret never appeared. Fixed to `icon-trailing="caret-down"`; combined with the change above, the picker triggers now show a caret that flips while open.
+- **`combobox-ui` — the menu can no longer cover its own input.** Two root causes fixed in `core/anchor.js`: (1) the native anchor path set an inline `max-height: calc(100vh - 3rem)` that CLOBBERED the component's stylesheet cap, so long option lists grew viewport-tall; (2) neither path reliably flipped — Chromium's `position-try-fallbacks: flip-block` demonstrably does NOT fire for a tall scrollable popover (verified via the new probe), and the JS fallback's viewport clamp slid an oversized menu UP OVER the trigger. Both paths now pick the vertical side **explicitly at open** (prefer the requested side; flip when it can't fit and the other side can; when neither fits, take the roomier side) and **clamp `max-height` to that side's available space** — the popover can never cross the anchor. Components can declare their own cap via `--popover-max-height` (the vertical twin of the existing `--popover-max-width` convention). Affects all `anchorPopover` consumers (combobox, select, menu, context-menu, tooltip, pickers) uniformly for the better. Regression harness: `scripts/dev/combobox-overflow-probe.mjs` (11 browser assertions incl. a short-viewport neither-side-fits case).
+- **`combobox-ui` — opening a flipped menu no longer yanks the page.** Active-option reveal now scrolls WITHIN the listbox (scroll arithmetic) instead of `scrollIntoView({block:'nearest'})`, which also scrolled document ancestors.
+- **`combobox-ui` — match-highlight spacing.** `[role="option"]` is `display:flex`, which dropped the whitespace between the `<mark>` and the rest of the label ("Ada Lovelace" rendered "AdaLovelace"); option labels now render inside a single `[data-option-label]` span. The `mark` rule also consumes the (previously dead) `--combobox-match-bg/fg` tokens with raw-token fallbacks.
+
+### Added
+- **`combobox-ui` `[max-visible-items]`** (default **10**) — caps how many option rows are visible before the menu scrolls; the listbox height hugs N rows (measured live, so it tracks `[size]`/density) instead of growing to the 18rem fallback. Distinct from `[max-options]` (the render cap). `0` disables. Demo: the new "long list — visible-item cap + flip" section (60 declarative options) in `combobox.examples.html`.
+- **`<theme-provider>` one-`<script>` CDN bundle** — `dist/theme-provider.min.js` (536 KB, self-contained: the element + its foundation-adoption machinery). A single `<script src=".../theme-provider.min.js">` registers `<theme-provider>`, which adopts the foundation from anywhere in the DOM (no `<head>` stylesheet link) — the CDN-first path for the 0.7.12 element. Added as a `bundle-js.mjs` entry, so `check:js-bundles-fresh` (blocking) gates its freshness alongside the other 6 bundles; served via the existing `./dist/*` export + the CDN. (First of the `<theme-provider>` follow-ups; build-time `<head>` hoist + an `adia-ui-kit` compose recipe + the embedded-app dogfood remain on the roadmap.)
+
+## [0.7.17] — 2026-06-08
+
+### Fixed
+- **`badge-ui` / `tag-ui` — icon-bearing chips no longer inflate row height.** Capped the inner `icon-ui` block-size to the text line-height (`components/badge/badge.css` `0.75em`, `components/tag/tag.css` `1em`) so a leading icon can't push the chip taller than a text-only one. Plus an `[icon]`-gated spacing tighten — reduced leading padding (`--a-space-1`) + a `~0.2em` icon↔label gap so the icon + label read as one tight unit; text-only chips unchanged. `dist/web-components.min.{css,js}` + `.sheet.js` regenerated to match.
+
 ## [0.7.16] — 2026-06-08
 
 ### Changed

package/components/badge/badge.css

@@ -45,13 +45,27 @@
 
   /* Leading icon stamped by JS (when [icon] is set). Inherits the badge's
      foreground color so legend chips read as a single color-coded unit
-     (e.g. accent variant → accent-colored dot + accent-colored label). */
+     (e.g. accent variant → accent-colored dot + accent-colored label).
+     ICON-HEIGHT FIX: cap the icon block-size so it cannot exceed the text
+     line-height. `line-height:1` on the badge drives the block size via
+     the text glyph; an icon taller than 1em would inflate the row. */
   :scope > icon-ui {
     --a-icon-size: 0.75em;
+    block-size: 0.75em;
     color: currentColor;
     flex-shrink: 0;
   }
 
+  /* ── Icon-badge spacing rebalance (B0) ──
+     Symmetric --badge-px looks loose / left-heavy when a leading icon is present:
+     the icon's own visual mass eats into the left breathing room. Tighten the
+     leading pad to --a-space-1 (4px) and narrow the gap to ~0.2em so the icon+label
+     read as ONE tight unit. Gated on [icon] so text-only badges are unaffected. */
+  :scope[icon] {
+    padding-inline-start: var(--badge-px-icon, var(--a-space-1));
+    gap: var(--badge-gap-icon, 0.2em);
+  }
+
   /* ── Variants ──
      Badge fg pairs with the muted (tinted) bg — use --a-{family}-text, which
      flips with scheme (shade in light, tint in dark) for proper contrast.

package/components/combobox/combobox.a2ui.json

@@ -81,6 +81,11 @@
       "type": "number",
       "default": 100
     },
+    "max-visible-items": {
+      "description": "How many option rows are visible before the listbox scrolls — the menu height hugs N rows instead of growing to the 18rem fallback. Distinct from max-options (the render cap). 0 disables.",
+      "type": "number",
+      "default": 10
+    },
     "name": {
       "description": "Form control name for form data submission",
       "type": "string",

package/components/combobox/combobox.class.js

@@ -75,6 +75,10 @@ export class UICombobox extends UIFormElement {
     filterMode:      { type: String,  default: 'substring', reflect: true, attribute: 'filter-mode' },
     loading:         { type: Boolean, default: false,       reflect: true },
     maxOptions:      { type: Number,  default: 100,         reflect: true, attribute: 'max-options' },
+    // Height cap: how many option rows are VISIBLE before the listbox scrolls
+    // (distinct from max-options, which caps how many are RENDERED at all).
+    // 0 disables the cap (falls back to the stylesheet's 18rem max).
+    maxVisibleItems: { type: Number,  default: 10,          reflect: true, attribute: 'max-visible-items' },
     highlightMatch:  { type: Boolean, default: true,        reflect: true, attribute: 'highlight-match' },
   };
 
@@ -392,7 +396,10 @@ export class UICombobox extends UIFormElement {
       el.dataset.value = opt.value ?? '';
       if (opt.disabled) el.setAttribute('aria-disabled', 'true');
       if (opt.value === this.value) el.setAttribute('aria-selected', 'true');
-      el.innerHTML = this.#renderOptionLabel(opt.label ?? opt.value);
+      // Single wrapping span: [role="option"] is display:flex, and a bare
+      // <mark> + text-run pair become SEPARATE flex items — flex drops the
+      // whitespace between them ("Ada Lovelace" rendered "AdaLovelace").
+      el.innerHTML = `<span data-option-label>${this.#renderOptionLabel(opt.label ?? opt.value)}</span>`;
       el.addEventListener('click', this.#onOptionClick);
       el.addEventListener('mouseenter', this.#onOptionMouseEnter);
       return el;
@@ -427,11 +434,40 @@ export class UICombobox extends UIFormElement {
       this.#emptyEl.style.display = visible || this.loading ? 'none' : '';
     }
 
+    // Re-apply the visible-item height cap — typing re-filters the row count.
+    if (this.open) this.#applyVisibleCap();
+
     // Clear any stale active-descendant pointer.
     this.#activeIndex = -1;
     this.#inputEl?.removeAttribute('aria-activedescendant');
   }
 
+  // ── Visible-item height cap ──
+
+  /**
+   * Cap the listbox to `max-visible-items` rows; rows past the cap scroll.
+   * Measured from the first rendered row so the cap tracks [size] / density /
+   * register automatically. Distinct from `max-options` (render cap). Only
+   * measurable while the popover is open (display:none otherwise) — callers
+   * gate on that.
+   */
+  #applyVisibleCap() {
+    if (!this.#listbox) return;
+    const cap = Number(this.maxVisibleItems);
+    const rows = this.#listbox.querySelectorAll('[role="option"]');
+    if (!Number.isFinite(cap) || cap <= 0 || rows.length <= cap) {
+      this.#listbox.style.removeProperty('--combobox-list-max-block');
+      return;
+    }
+    const rowH = rows[0].getBoundingClientRect().height;
+    if (!rowH) return; // not measurable yet — leave the standing cap untouched
+    const cs = getComputedStyle(this.#listbox);
+    const chrome =
+      (parseFloat(cs.paddingBlockStart) || 0) + (parseFloat(cs.paddingBlockEnd) || 0) +
+      (parseFloat(cs.borderBlockStartWidth) || 0) + (parseFloat(cs.borderBlockEndWidth) || 0);
+    this.#listbox.style.setProperty('--combobox-list-max-block', `${Math.ceil(rowH * cap + chrome)}px`);
+  }
+
   #renderOptionLabel(label) {
     const text = String(label ?? '');
     if (!this.highlightMatch || !this.#query) return escapeHTML(text);
@@ -615,7 +651,16 @@ export class UICombobox extends UIFormElement {
     const el = opts[clamped];
     if (!el) return;
     el.setAttribute('data-active', '');
-    el.scrollIntoView({ block: 'nearest' });
+    // Scroll WITHIN the listbox only — scrollIntoView({block:'nearest'}) also
+    // scrolls document ancestors, which yanked the whole page when a flipped
+    // (above-the-field) menu poked past the viewport top.
+    const lb = this.#listbox;
+    if (lb) {
+      const oTop = el.offsetTop;
+      const oBot = oTop + el.offsetHeight;
+      if (oTop < lb.scrollTop) lb.scrollTop = oTop;
+      else if (oBot > lb.scrollTop + lb.clientHeight) lb.scrollTop = oBot - lb.clientHeight;
+    }
     this.#activeIndex = clamped;
     this.#inputEl?.setAttribute('aria-activedescendant', el.id);
   }
@@ -804,6 +849,8 @@ export class UICombobox extends UIFormElement {
   #openPopover() {
     if (!this.#listbox) return;
     this.#listbox.showPopover?.();
+    // Cap the height BEFORE anchoring so flip/collision math sees the capped box.
+    this.#applyVisibleCap();
     const trigger = this.querySelector(':scope > [data-field]') || this;
     this.#listbox.style.minWidth = `${trigger.getBoundingClientRect().width}px`;
     this.#anchorCleanup?.();

package/components/combobox/combobox.css

@@ -120,6 +120,14 @@
   [data-suffix] {
     cursor: pointer;
   }
+  [data-suffix] icon-ui[name="caret-down"] {
+    transition: rotate var(--a-duration-fast) var(--a-easing);
+  }
+  /* Clear OPEN state: the default caret flips while the listbox is open.
+     Name-guarded — a consumer-slotted suffix glyph never rotates. */
+  :scope[open] [data-suffix] icon-ui[name="caret-down"] {
+    rotate: 180deg;
+  }
 
   [data-input] {
     flex: 1;
@@ -180,12 +188,21 @@ combobox-ui [data-field] [data-input] {
 
 combobox-ui [data-listbox] {
   margin: 0;
+  /* border-box so the JS visible-item cap (rows + padding + border) maps 1:1
+     onto max-height. */
+  box-sizing: border-box;
   padding: var(--a-space-1);
   border: 1px solid var(--a-ui-border);
   border-radius: var(--a-radius);
   background: var(--a-canvas-bright);
   box-shadow: var(--a-shadow-lg);
-  max-height: 18rem;
+  /* --combobox-list-max-block is set inline by #applyVisibleCap() when the
+     rendered options exceed [max-visible-items] (default 10) — the menu hugs
+     N rows and scrolls past the cap. 18rem is the uncapped fallback. */
+  max-height: var(--combobox-list-max-block, 18rem);
+  /* Feed the same cap to core/anchor.js's native-path viewport clamp (which
+     sets an INLINE max-height and would otherwise out-cascade this rule). */
+  --popover-max-height: var(--combobox-list-max-block, 18rem);
   overflow-y: auto;
   font-family: inherit;
   font-size: var(--a-ui-size);
@@ -239,8 +256,11 @@ combobox-ui [data-listbox] [role="option"][aria-disabled="true"] {
 }
 
 combobox-ui [data-listbox] [role="option"] mark {
-  background: var(--a-accent-muted);
-  color: var(--a-accent-strong);
+  /* Consume the :where(:scope) match tokens (custom props inherit through the
+     DOM even though the popover paints in the top layer); raw-token fallbacks
+     keep the highlight alive if the host tokens are unavailable. */
+  background: var(--combobox-match-bg, var(--a-accent-muted));
+  color: var(--combobox-match-fg, var(--a-accent-strong));
   padding: 0 0.1em;
   border-radius: var(--a-radius-sm);
 }

package/components/combobox/combobox.test.js

@@ -195,4 +195,62 @@ describe('combobox-ui', () => {
     const navigable = el.querySelectorAll('[role="option"]:not([aria-disabled="true"])');
     expect(navigable.length).toBe(2);
   });
+
+  it('max-visible-items defaults to 10 and wires the kebab attribute', async () => {
+    const el = mount(`
+      <combobox-ui>
+        <option value="a">Alpha</option>
+      </combobox-ui>
+    `);
+    await tick();
+    expect(el.maxVisibleItems).toBe(10);
+    const el2 = mount(`<combobox-ui max-visible-items="5"></combobox-ui>`);
+    await tick();
+    expect(el2.maxVisibleItems).toBe(5);
+    // Geometry is unmeasurable in this env (rect heights are 0), so the cap
+    // var must NOT be stamped — the browser-level cap is covered by the
+    // Playwright visual harness; here we assert the bail path stays clean.
+    expect(el2.querySelector('[data-listbox]').style.getPropertyValue('--combobox-list-max-block')).toBe('');
+  });
+
+  it('typing wraps the matched substring of each filtered option in <mark>', async () => {
+    const el = mount(`
+      <combobox-ui>
+        <option value="a">Alpha</option>
+        <option value="b">Altitude</option>
+        <option value="c">Gamma</option>
+      </combobox-ui>
+    `);
+    await tick();
+    const input = el.querySelector('[data-input]');
+    input.textContent = 'al';
+    input.dispatchEvent(new Event('input', { bubbles: true }));
+    await tick();
+    const opts = el.querySelectorAll('[data-listbox] [role="option"]');
+    expect(opts.length).toBe(2); // Alpha + Altitude match; Gamma filtered out
+    const marks = el.querySelectorAll('[data-listbox] [role="option"] mark');
+    expect(marks.length).toBe(2);
+    expect(marks[0].textContent.toLowerCase()).toBe('al');
+  });
+
+  it('highlightMatch = false (programmatic) renders filtered options without <mark>', async () => {
+    // NOTE: declarative `highlight-match="false"` does NOT disable (Boolean
+    // attr present → true; the prop's default:true violates the
+    // Boolean-defaults-false contract rule — a pre-existing wart). The
+    // supported disable path is the programmatic setter.
+    const el = mount(`
+      <combobox-ui>
+        <option value="a">Alpha</option>
+        <option value="c">Gamma</option>
+      </combobox-ui>
+    `);
+    await tick();
+    el.highlightMatch = false;
+    const input = el.querySelector('[data-input]');
+    input.textContent = 'al';
+    input.dispatchEvent(new Event('input', { bubbles: true }));
+    await tick();
+    expect(el.querySelectorAll('[data-listbox] [role="option"]').length).toBe(1);
+    expect(el.querySelectorAll('[data-listbox] mark').length).toBe(0);
+  });
 });

package/components/combobox/combobox.yaml

@@ -128,6 +128,11 @@ props:
     type: number
     default: 100
     reflect: true
+  max-visible-items:
+    description: How many option rows are visible before the listbox scrolls — the menu height hugs N rows instead of growing to the 18rem fallback. Distinct from max-options (the render cap). 0 disables.
+    type: number
+    default: 10
+    reflect: true
   highlight-match:
     description: Wraps the matched substring in `<mark>` inside option labels
     type: boolean

package/components/date-range-picker/date-range-picker.class.js

@@ -155,7 +155,7 @@ export class UIDateRangePicker extends UIFormElement {
   // / hidePopover() programmatically. Two calendar instances + a preset
   // rail + a calendar area sit inside.
   static parts = {
-    trigger: '<button-ui slot="trigger" variant="outline" type="button" icon="calendar" trailing-icon="caret-down" aria-label="Open date range picker"></button-ui>',
+    trigger: '<button-ui slot="trigger" variant="outline" type="button" icon="calendar" icon-trailing="caret-down" aria-label="Open date range picker"></button-ui>',
     popover: '<div slot="popover" popover="manual" role="dialog" aria-label="Date range picker"></div>',
     presets: '<div data-preset-rail role="group" aria-label="Date range presets"></div>',
     calArea: '<div data-calendar-area></div>',

package/components/date-range-picker/date-range-picker.css

@@ -89,6 +89,15 @@
      stamped by date-range-picker.class.js — these rules override button-ui's defaults at
      equal specificity so the picker trigger reads as part of the
      input/picker family rather than a generic button. */
+  :scope [slot="trigger"] icon-ui[name="caret-down"] {
+    transition: rotate var(--a-duration-fast) var(--a-easing);
+  }
+  /* Clear OPEN state: the default trigger's trailing caret flips while the
+     picker popover is open (name-guarded; custom trigger glyphs untouched). */
+  :scope[open] [slot="trigger"] icon-ui[name="caret-down"] {
+    rotate: 180deg;
+  }
+
   :scope [slot="trigger"] {
     min-width: var(--date-range-picker-trigger-min-width);
     min-height: var(--date-range-picker-trigger-height);

package/components/datetime-picker/datetime-picker.class.js

@@ -146,7 +146,7 @@ export class UIDatetimePicker extends UIFormElement {
   // showPopover() / hidePopover() programmatically. Mirrors
   // date-range-picker's shape (the closest sibling).
   static parts = {
-    trigger:  '<button-ui slot="trigger" variant="outline" type="button" icon="calendar" trailing-icon="caret-down" aria-label="Open date and time picker"></button-ui>',
+    trigger:  '<button-ui slot="trigger" variant="outline" type="button" icon="calendar" icon-trailing="caret-down" aria-label="Open date and time picker"></button-ui>',
     popover:  '<div slot="popover" popover="manual" role="dialog" aria-label="Date and time picker"></div>',
     // §FB-Wave1-QA — substrate primitive (extracted from calendar-picker-ui).
     calPane:  '<calendar-grid-ui data-cal-pane aria-label="Date"></calendar-grid-ui>',

package/components/datetime-picker/datetime-picker.css

@@ -61,6 +61,15 @@
      picker-family field shape (mirrors date-range-picker): value text
      left-aligned with the caret pushed to the trailing edge, not centered
      like a default button. */
+  :scope [slot="trigger"] icon-ui[name="caret-down"] {
+    transition: rotate var(--a-duration-fast) var(--a-easing);
+  }
+  /* Clear OPEN state: the default trigger's trailing caret flips while the
+     picker popover is open (name-guarded; custom trigger glyphs untouched). */
+  :scope[open] [slot="trigger"] icon-ui[name="caret-down"] {
+    rotate: 180deg;
+  }
+
   :scope [slot="trigger"] {
     min-width: var(--datetime-picker-trigger-min-width);
     justify-content: space-between;

package/components/menu/menu.css

@@ -71,6 +71,17 @@ menu-ui [data-menu-popover]:popover-open {
   }
 }
 
+/* Clear OPEN state for caret-bearing triggers: a consumer trigger that carries
+   a caret-down icon (e.g. <button-ui icon-trailing="caret-down">) flips it
+   while the menu is open. Name-guarded — non-caret trigger glyphs (dots,
+   gear, …) never rotate. */
+menu-ui [slot="trigger"] icon-ui[name="caret-down"] {
+  transition: rotate var(--a-duration-fast) var(--a-easing);
+}
+menu-ui[open] [slot="trigger"] icon-ui[name="caret-down"] {
+  rotate: 180deg;
+}
+
 @media (prefers-reduced-motion: reduce) {
   menu-ui [data-menu-popover] { transition: none; }
 }

package/components/select/select.class.js

@@ -27,7 +27,7 @@ export class UISelect extends UIFormElement {
   // (slot 11). Per FEEDBACK-06 §4 + FEEDBACK-07 §4.
   // SPEC-040: [multiple] mode stamps <tag-ui> chips (own `x`), checkbox
   // indicator (`check`), and search-input prefix (`magnifying-glass`).
-  static requiredIcons = ['caret-up-down', 'check', 'x', 'magnifying-glass'];
+  static requiredIcons = ['caret-down', 'check', 'x', 'magnifying-glass'];
 
   // §225 (v0.5.9, FEEDBACK-10 §3): once-per-element console.warn dedup when
   // consumer authors children that aren't native <option>/<optgroup>. The
@@ -445,7 +445,7 @@ export class UISelect extends UIFormElement {
           <button type="button" data-clear-all aria-label="Clear all" hidden>
             <icon-ui name="x"></icon-ui>
           </button>
-          <icon-ui name="caret-up-down" slot="caret"></icon-ui>
+          <icon-ui name="caret-down" slot="caret"></icon-ui>
         </span>
         ${hintMarkup}
       `;

package/components/select/select.css

@@ -167,6 +167,14 @@
   :scope [slot="trigger"] [slot="caret"] {
     color: var(--select-caret-fg);
     flex-shrink: 0;
+    transition: rotate var(--a-duration-fast) var(--a-easing);
+  }
+
+  /* Clear OPEN state on the caret: the default caret-down flips to point up
+     while the listbox is open. Name-guarded so a consumer-slotted non-caret
+     glyph in the caret slot never rotates. */
+  :scope[open] [slot="trigger"] icon-ui[slot="caret"][name="caret-down"] {
+    rotate: 180deg;
   }
 
   /* Size handled by universal [size] attribute system. */

package/components/select/select.yaml

@@ -236,7 +236,7 @@ states:
 traits: []
 tokens: {}
 requiredIcons:
-  - caret-up-down
+  - caret-down
   - check               # checkbox indicator on each option in [multiple] mode
   - x                   # chip dismiss + clear-all affordance ([multiple] + [clearable])
   - magnifying-glass    # search-input prefix ([searchable])

package/components/tag/tag.css

@@ -189,10 +189,25 @@ tag-ui[removable]:not([disabled]):hover {
   /* ── Slotted icons (leading) ──
      Icons placed inside the tag (e.g. `<icon-ui name="check">`) inherit
      the host's text color so legend / status chips read as a single
-     color-coded unit. Mirrors `<badge-ui>`'s convention. */
+     color-coded unit. Mirrors `<badge-ui>`'s convention.
+     ICON-HEIGHT FIX: cap the icon at 1em so it never exceeds the text
+     line-height and inflates the row. The icon is visual decoration on
+     a text chip — it must not drive the block size. `flex-none` prevents
+     it from growing or shrinking; `flex-shrink:0` is already here. */
   :scope > icon-ui {
     color: currentColor;
     flex-shrink: 0;
+    --a-icon-size: 1em;
+    block-size: 1em;
+  }
+
+  /* ── Icon-tag spacing rebalance (B0) ──
+     Mirrors badge-ui's [icon] rebalance: tighten leading pad + narrow gap when
+     a leading icon is present, so the icon+label read as one tight unit.
+     Gated on :has(> icon-ui) to leave text-only tags unaffected. */
+  :scope:has(> icon-ui) {
+    padding-inline-start: var(--tag-px-icon, var(--a-space-1));
+    gap: var(--tag-gap-icon, 0.2em);
   }
 
   /* ── Dismiss button ── */

package/core/anchor.js

@@ -54,12 +54,42 @@ function anchorNative(anchor, popover, { placement, gap, matchWidth }) {
 
   anchor.style.anchorName = name;
 
+  // Resolve the vertical side OURSELVES at apply time (same logic as the JS
+  // fallback) instead of trusting `position-try-fallbacks: flip-block` — in
+  // practice (verified against Chromium via the combobox overflow probe) the
+  // try fallback does NOT fire for a tall scrollable popover, so a long list
+  // anchored low simply overflowed the viewport. We pick the side that fits
+  // (preferring the requested one), and clamp max-height to that side's
+  // available space so the popover can never cross the anchor.
+  let resolved = placement;
+  if (placement.startsWith('bottom') || placement.startsWith('top')) {
+    const a = anchor.getBoundingClientRect();
+    const vh = window.innerHeight;
+    const spaceBelow = vh - a.bottom - gap * 2;
+    const spaceAbove = a.top - gap * 2;
+    // The popover's own cap (e.g. combobox's visible-item cap) participates in
+    // the fit decision; fall back to content height when no cap is declared.
+    const capPx = resolveLengthPx(getComputedStyle(popover).getPropertyValue('--popover-max-height'));
+    const want = Number.isFinite(capPx) ? capPx : (popover.scrollHeight || 0);
+    const wantBelow = placement.startsWith('bottom');
+    const fitsBelow = want <= spaceBelow;
+    const fitsAbove = want <= spaceAbove;
+    let useBelow = wantBelow;
+    if (wantBelow && !fitsBelow) useBelow = fitsAbove ? false : spaceBelow >= spaceAbove;
+    else if (!wantBelow && !fitsAbove) useBelow = fitsBelow ? true : spaceBelow > spaceAbove;
+    resolved = placement.replace(/^(bottom|top)/, useBelow ? 'bottom' : 'top');
+    // 40px floor so a degenerate viewport never collapses the popover entirely.
+    const avail = Math.max(40, Math.floor(useBelow ? spaceBelow : spaceAbove));
+    popover.style.maxHeight = `${Number.isFinite(capPx) ? Math.min(capPx, avail) : avail}px`;
+  }
+
   popover.style.position = 'fixed';
   popover.style.positionAnchor = name;
-  popover.style.positionArea = placementToPositionArea(placement);
+  popover.style.positionArea = placementToPositionArea(resolved);
   // Gap only on the main (anchor-adjacent) axis so start/end alignment stays tight.
-  popover.style.margin = placementToGapMargin(placement, gap);
-  // Let the browser flip across the opposite side + both perpendicular edges.
+  popover.style.margin = placementToGapMargin(resolved, gap);
+  // Best-effort extras for post-open scroll/resize (the side is already chosen
+  // above; these only help at the margins).
   popover.style.positionTryFallbacks = 'flip-block, flip-inline, flip-block flip-inline';
 
   // Sizing concerns that follow from anchor positioning — kept here (not in
@@ -80,7 +110,11 @@ function anchorNative(anchor, popover, { placement, gap, matchWidth }) {
   // setting --popover-max-width on the popover element. Viewport safety
   // (100vw - 1rem) still wins so nothing escapes the screen.
   popover.style.maxWidth = 'min(calc(100vw - 1rem), var(--popover-max-width, 32rem))';
-  popover.style.maxHeight = 'calc(100vh - 3rem)';
+  // Vertical placements got a side-aware literal clamp above (which also folds
+  // in --popover-max-height); horizontal placements keep the viewport-safety cap.
+  if (!resolved.startsWith('bottom') && !resolved.startsWith('top')) {
+    popover.style.maxHeight = 'calc(100vh - 3rem)';
+  }
   popover.style.overflowY = 'auto';
 
   // top/left are controlled by position-area; make sure no stale values fight it.
@@ -93,6 +127,21 @@ function anchorNative(anchor, popover, { placement, gap, matchWidth }) {
   };
 }
 
+// Resolve a --popover-max-height declaration to px. The convention's consumers
+// declare px (JS-measured caps) or rem (stylesheet defaults); anything else
+// (calc, var chains, empty) returns NaN and the caller falls back to content
+// height. Kept deliberately narrow — this feeds a fit DECISION, not layout.
+function resolveLengthPx(raw) {
+  const v = String(raw || '').trim();
+  if (!v) return NaN;
+  const m = /^(-?\d+(?:\.\d+)?)(px|rem)$/.exec(v);
+  if (!m) return NaN;
+  const n = parseFloat(m[1]);
+  if (m[2] === 'px') return n;
+  const rootPx = parseFloat(getComputedStyle(document.documentElement).fontSize) || 16;
+  return n * rootPx;
+}
+
 // Axis-specific margin so gap only separates on the main axis (TRBL).
 function placementToGapMargin(placement, gap) {
   if (placement.startsWith('bottom')) return `${gap}px 0 0 0`;
@@ -124,21 +173,49 @@ function placementToPositionArea(placement) {
 // ── JS fallback ──
 
 function anchorJS(anchor, popover, { placement, gap, matchWidth }) {
+  // Inline height-clamp state we may apply per-update — captured so each update
+  // re-measures from the stylesheet's own cap (and cleanup can restore).
+  const prevMaxHeight = popover.style.maxHeight;
+  const prevOverflowY = popover.style.overflowY;
+
   function update() {
     if (!anchor || !popover) return;
 
+    // Reset any clamp WE applied on a prior update before measuring, so the
+    // popover's natural (stylesheet-capped) height drives this pass — the
+    // anchor may have scrolled somewhere roomier.
+    popover.style.maxHeight = prevMaxHeight;
+    popover.style.overflowY = prevOverflowY;
+
     const a = anchor.getBoundingClientRect();
-    const p = popover.getBoundingClientRect();
+    let p = popover.getBoundingClientRect();
     const vw = window.innerWidth;
     const vh = window.innerHeight;
 
     let resolved = placement;
 
-    // Vertical flip
-    if (resolved.startsWith('bottom') && a.bottom + gap + p.height > vh && a.top - gap - p.height > 0) {
-      resolved = resolved.replace('bottom', 'top');
-    } else if (resolved.startsWith('top') && a.top - gap - p.height < 0 && a.bottom + gap + p.height < vh) {
-      resolved = resolved.replace('top', 'bottom');
+    // Vertical placements: flip + collision-clamp so the popover NEVER crosses
+    // the anchor. The old logic only flipped when the other side fully fit and
+    // then viewport-clamped `top` — which slid an oversized popover UP OVER the
+    // anchor (the combobox long-list bug: the menu covered its own input).
+    if (resolved.startsWith('bottom') || resolved.startsWith('top')) {
+      const spaceBelow = vh - a.bottom - gap * 2;
+      const spaceAbove = a.top - gap * 2;
+      const wantBelow = resolved.startsWith('bottom');
+      const fitsBelow = p.height <= spaceBelow;
+      const fitsAbove = p.height <= spaceAbove;
+      let useBelow = wantBelow;
+      if (wantBelow && !fitsBelow) useBelow = fitsAbove ? false : spaceBelow >= spaceAbove;
+      else if (!wantBelow && !fitsAbove) useBelow = fitsBelow ? true : spaceBelow > spaceAbove;
+      resolved = resolved.replace(/^(bottom|top)/, useBelow ? 'bottom' : 'top');
+
+      // Clamp to the chosen side's available space; scroll the overflow.
+      const avail = Math.max(0, Math.floor(useBelow ? spaceBelow : spaceAbove));
+      if (p.height > avail) {
+        popover.style.maxHeight = `${avail}px`;
+        popover.style.overflowY = 'auto';
+        p = popover.getBoundingClientRect();
+      }
     }
 
     let top, left;
@@ -168,7 +245,13 @@ function anchorJS(anchor, popover, { placement, gap, matchWidth }) {
     if (left + p.width > vw - gap) left = a.right - p.width;
     if (left < gap) left = a.left;
 
-    top = Math.max(gap, Math.min(top, vh - p.height - gap));
+    // Horizontal placements still viewport-clamp vertically (they center on the
+    // anchor, so the clamp can't cross it). Vertical placements are in-bounds
+    // by construction after the collision clamp above — clamping them here is
+    // exactly what used to drag the popover over the anchor.
+    if (resolved.startsWith('left') || resolved.startsWith('right')) {
+      top = Math.max(gap, Math.min(top, vh - p.height - gap));
+    }
     left = Math.max(gap, Math.min(left, vw - p.width - gap));
 
     popover.style.position = 'fixed';
@@ -190,6 +273,8 @@ function anchorJS(anchor, popover, { placement, gap, matchWidth }) {
   return () => {
     for (const sp of scrollParents) sp.removeEventListener('scroll', update);
     window.removeEventListener('resize', update);
+    popover.style.maxHeight = prevMaxHeight;
+    popover.style.overflowY = prevOverflowY;
   };
 }