@cardstack/boxel-cli 0.10.0 → 0.10.1-unstable.0

package/bundled-realms/pretui/components/morphing-popover.usage.gts

@@ -0,0 +1,176 @@
+// Pretui — MorphingPopover usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { MorphingPopover } from './morphing-popover';
+import type { PopupPlacement } from '../internal/overlay';
+
+// ── MorphingPopover ──────────────────────────────────────────────────────
+export class MorphingPopoverUsage extends Component {
+  @tracked placement: PopupPlacement = 'bottom-start';
+
+  placementOptions = [
+    'top-start',
+    'top',
+    'top-end',
+    'bottom-start',
+    'bottom',
+    'bottom-end',
+    'left',
+    'right',
+  ];
+
+  setPlacement = (v: string) => {
+    this.placement = v as PopupPlacement;
+  };
+
+  get usage(): string {
+    return [
+      "<MorphingPopover @label='Filters'>",
+      '  <:trigger>Filters</:trigger>',
+      '  <:default as |close|>…</:default>',
+      '</MorphingPopover>',
+    ].join('\n');
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='MorphingPopover'
+      @description='A trigger that grows into its own anchored panel. It WRAPS Popup, so placement, flipping, shifting and re-placement on scroll are anchorTo’s. Added here: the morph out of the trigger’s rectangle, Escape in the capture phase so one keypress cannot mean two things, outside-pointer dismissal, focus into the panel on open, and focus back to the trigger on every dismissal path.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='mp-stage'>
+          <MorphingPopover @label='Filters' @placement={{this.placement}}>
+            <:trigger>Filters</:trigger>
+            <:default as |close|>
+              <div class='mp-panel'>
+                <p class='mp-title'>Filter lots</p>
+                <ul class='mp-list'>
+                  <li>Cleared and bonded</li>
+                  <li>Awaiting cupping</li>
+                  <li>Held at the dock</li>
+                </ul>
+                <button type='button' class='mp-done' {{on 'click' close}}>
+                  Done
+                </button>
+              </div>
+            </:default>
+          </MorphingPopover>
+          <p class='mp-note'>Tab to the trigger and press Enter: focus lands
+            inside the panel, Escape closes it, and focus returns to the
+            trigger. The
+            <code>close</code>
+            action is yielded, so a control inside the panel can dismiss it
+            without the caller tracking any state.</p>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='label'
+          @description='Accessible name for the panel, which carries role=dialog.'
+        />
+        <Args.String
+          @name='placement'
+          @description='Where the panel sits relative to the trigger. anchorTo flips and shifts it to stay on screen.'
+          @options={{this.placementOptions}}
+          @value={{this.placement}}
+          @onInput={{this.setPlacement}}
+          @defaultValue='bottom-start'
+        />
+        <Args.Number
+          @name='distance'
+          @description='Gap between trigger and panel in px.'
+          @defaultValue={{8}}
+        />
+        <Args.Bool
+          @name='matchWidth'
+          @description='Match the panel’s minimum width to the trigger’s.'
+          @defaultValue={{false}}
+        />
+        <Args.Bool
+          @name='open'
+          @description='Controlled open state. Omit for uncontrolled.'
+        />
+        <Args.Action
+          @name='onOpenChange'
+          @description='Fires with the next open state on every change, including Escape and an outside click.'
+        />
+        <Args.Yield
+          @name='default'
+          @description='The panel contents. Receives a close action.'
+          @hideControls={{true}}
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-morph-popover-width'
+          @type='dimension'
+          @description='Minimum panel width.'
+          @defaultValue='240px'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+
+    <style scoped>
+      .mp-stage {
+        display: grid;
+        gap: var(--space-4, 11px);
+        justify-items: start;
+        padding: var(--space-6, 19px);
+        border-radius: var(--radius-surface, 10px);
+        background: var(--card);
+        box-shadow: var(
+          --pretui-shadow-hairline,
+          0 0 0 1px var(--border)
+        );
+      }
+      .mp-panel {
+        display: grid;
+        gap: var(--space-3, 8px);
+      }
+      .mp-title {
+        margin: 0;
+        font-weight: var(--weight-strong, 600);
+      }
+      .mp-list {
+        margin: 0;
+        padding-inline-start: 1.1em;
+        display: grid;
+        gap: 3px;
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+      .mp-done {
+        justify-self: end;
+        padding: 5px 12px;
+        min-block-size: 28px;
+        border: 0;
+        border-radius: var(--radius-control, 7px);
+        background: var(--primary);
+        color: var(--primary-foreground);
+        font: inherit;
+        font-size: var(--text-ui-sm, 11.5px);
+        cursor: pointer;
+      }
+      .mp-done:focus-visible {
+        outline: 2px solid var(--ring);
+        outline-offset: 2px;
+      }
+      .mp-note {
+        margin: 0;
+        max-inline-size: 58ch;
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--muted-foreground);
+      }
+      .mp-note code {
+        font-family: var(--font-mono);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_MORPHING_POPOVER: Record<string, unknown> = {
+  MorphingPopover: MorphingPopoverUsage,
+};

package/bundled-realms/pretui/components/multi-select.gts

@@ -0,0 +1,392 @@
+// Pretui — MultiSelect.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { fn } from '@ember/helper';
+import { htmlSafe } from '@ember/template';
+import { guidFor } from '@ember/object/internals';
+import { OwnedTimers, TypeaheadBuffer, ownsTimers, typeaheadIndex } from '../focus';
+import { Popup } from './popup';
+import type { SelectOption } from './select';
+
+// ── MultiSelect ──────────────────────────────────────────────────────────
+// Fresh on the Popup primitive, mirroring Pretui Select's structure: same
+// trigger dress (pretui-input face, focus ring while open), same listbox
+// with the traveling highlight — plus removable chips in the trigger
+// (FilterChips capsule dress) and checkbox-marked options that keep the
+// list open across toggles. The trigger is a role='combobox' div rather
+// than a button so the chip-remove buttons can nest inside it legally.
+export interface MultiSelectSignature {
+  Args: {
+    options: SelectOption[];
+    value?: string[];
+    defaultValue?: string[];
+    placeholder?: string;
+    /** accessible name for the combobox; falls back to @placeholder */
+    label?: string;
+    disabled?: boolean;
+    onValueChange?: (values: string[]) => void;
+  };
+  Element: HTMLDivElement;
+}
+
+export class MultiSelect extends Component<MultiSelectSignature> {
+  get listboxId() {
+    return `${guidFor(this)}-listbox`;
+  }
+  optionId = (index: number) => `${guidFor(this)}-opt-${index}`;
+  get activeId(): string | undefined {
+    return this.open && this.args.options.length ? this.optionId(this.hi) : undefined;
+  }
+  get accessibleName(): string {
+    return this.args.label ?? this.args.placeholder ?? 'Select items';
+  }
+  get countText(): string {
+    return `${this.values.length} selected`;
+  }
+  private timers = new OwnedTimers();
+  private typeahead = new TypeaheadBuffer(this.timers);
+  @tracked internal: string[] = this.args.defaultValue ?? [];
+  @tracked open = false;
+  @tracked hi = 0;
+
+  get values(): string[] {
+    return this.args.value ?? this.internal;
+  }
+  get selectedOptions() {
+    return this.args.options.filter((o) => this.values.includes(o.value));
+  }
+  get highlightStyle() {
+    return htmlSafe(`transform: translateY(${4 + this.hi * 28}px); height: 28px; top: 0`);
+  }
+  isChecked = (option: SelectOption) => this.values.includes(option.value);
+  toggleOpen = () => {
+    if (this.args.disabled) {
+      return;
+    }
+    this.open = !this.open;
+    if (this.open) {
+      this.hi = Math.max(0, this.args.options.findIndex((o) => this.isChecked(o)));
+    }
+  };
+  close = () => {
+    this.open = false;
+  };
+  toggleValue = (option: SelectOption) => {
+    if (this.args.disabled) {
+      return;
+    }
+    let next = this.isChecked(option)
+      ? this.values.filter((v) => v !== option.value)
+      : [...this.values, option.value];
+    if (this.args.value === undefined) {
+      this.internal = next;
+    }
+    this.args.onValueChange?.(next);
+    // multi-select semantics: the listbox stays open across toggles
+  };
+  remove = (option: SelectOption, e: Event) => {
+    e.stopPropagation();
+    this.toggleValue(option);
+  };
+  hover = (index: number) => {
+    this.hi = index;
+  };
+  onKey = (e: Event) => {
+    let ev = e as KeyboardEvent;
+    let opts = this.args.options;
+    if (!this.open && (ev.key === 'Enter' || ev.key === ' ' || ev.key === 'ArrowDown')) {
+      ev.preventDefault();
+      this.toggleOpen();
+      return;
+    }
+    if (!this.open) {
+      return;
+    }
+    if (ev.key === 'ArrowDown') {
+      ev.preventDefault();
+      this.hi = Math.min(opts.length - 1, this.hi + 1);
+    } else if (ev.key === 'ArrowUp') {
+      ev.preventDefault();
+      this.hi = Math.max(0, this.hi - 1);
+    } else if (ev.key === 'Home') {
+      ev.preventDefault();
+      this.hi = 0;
+    } else if (ev.key === 'End') {
+      ev.preventDefault();
+      this.hi = Math.max(0, opts.length - 1);
+    } else if (ev.key === 'Enter' || ev.key === ' ') {
+      ev.preventDefault();
+      let o = opts[this.hi];
+      if (o) {
+        this.toggleValue(o);
+      }
+    } else if (ev.key === 'Escape') {
+      this.close();
+    } else if (ev.key.length === 1 && !ev.ctrlKey && !ev.metaKey && !ev.altKey) {
+      let prefix = this.typeahead.push(ev.key);
+      let next = typeaheadIndex(
+        opts.map((o) => o.label),
+        prefix,
+        this.hi,
+        this.typeahead.isCycling,
+      );
+      if (next >= 0) {
+        this.hi = next;
+      }
+    }
+  };
+
+  <template>
+    <div class='pretui-selectwrap' data-test-pretui-multi-select {{ownsTimers this.timers}} ...attributes>
+      <Popup @open={{this.open}} @matchWidth={{true}} @distance={{4}}>
+        <:anchor>
+          <div
+            role='combobox'
+            tabindex='0'
+            class='pretui-input pretui-mstrigger'
+            data-state={{if this.open 'open' 'closed'}}
+            data-disabled={{if @disabled 'true'}}
+            aria-haspopup='listbox'
+            aria-controls={{this.listboxId}}
+            aria-expanded={{if this.open 'true' 'false'}}
+            aria-disabled={{if @disabled 'true' 'false'}}
+            aria-label={{this.accessibleName}}
+            aria-activedescendant={{this.activeId}}
+            {{on 'keydown' this.onKey}}
+            {{on 'click' this.toggleOpen}}
+          >
+            {{#if this.selectedOptions.length}}
+              {{#each this.selectedOptions as |option|}}
+                <span class='pretui-mschip'>
+                  {{option.label}}
+                  <button
+                    type='button'
+                    class='pretui-mschip-x'
+                    aria-label='Remove {{option.label}}'
+                    tabindex='-1'
+                    {{on 'click' (fn this.remove option)}}
+                  >
+                    <svg width='8' height='8' viewBox='0 0 8 8' aria-hidden='true'><path d='M1.5 1.5 6.5 6.5 M6.5 1.5 1.5 6.5' fill='none' stroke='currentColor' stroke-width='1.4' stroke-linecap='round' /></svg>
+                  </button>
+                </span>
+              {{/each}}
+            {{else}}
+              <span class='pretui-placeholder'>{{if @placeholder @placeholder 'Select…'}}</span>
+            {{/if}}
+            <svg width='10' height='10' viewBox='0 0 10 10' class='pretui-caret' aria-hidden='true'><path d='M2 3.5 5 6.5 8 3.5' fill='none' stroke='currentColor' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round' /></svg>
+          </div>
+        </:anchor>
+        <:default>
+          <button type='button' class='pretui-select-backdrop' aria-label='Close' tabindex='-1' {{on 'click' this.close}}></button>
+          <div
+            class='pretui-listbox'
+            id={{this.listboxId}}
+            role='listbox'
+            aria-multiselectable='true'
+          >
+            <div class='pretui-listbox-hl' style={{this.highlightStyle}}></div>
+            {{#each @options as |option index|}}
+              <div
+                id={{this.optionId index}}
+                role='option'
+                aria-selected={{if (this.isChecked option) 'true' 'false'}}
+                class='pretui-option'
+                data-state={{if (this.isChecked option) 'checked'}}
+                {{on 'mouseenter' (fn this.hover index)}}
+                {{on 'click' (fn this.toggleValue option)}}
+              >
+                <span class='pretui-msbox' data-state={{if (this.isChecked option) 'checked'}}>
+                  {{#if (this.isChecked option)}}<span class='pretui-msbox-check'></span>{{/if}}
+                </span>
+                {{option.label}}
+              </div>
+            {{/each}}
+          </div>
+        </:default>
+      </Popup>
+      <span class='pretui-ms-count' role='status'>{{this.countText}}</span>
+    </div>
+    <style scoped>
+      /* above Popup's layer, so these win by layer order, not file order */
+      @layer PretComponent, PretComposite;
+      @layer PretComposite {
+        .pretui-selectwrap {
+          min-width: 0;
+        }
+        .pretui-ms-count {
+          position: absolute;
+          width: 1px;
+          height: 1px;
+          overflow: hidden;
+          clip-path: inset(50%);
+          white-space: nowrap;
+        }
+        .pretui-input {
+          display: flex;
+          align-items: center;
+          gap: 6px;
+          height: var(--control-h, 28px);
+          padding: 0 9px;
+          border: 0;
+          border-radius: var(--radius);
+          font: inherit;
+          font-size: var(--text-ui-md, 12.5px);
+          letter-spacing: var(--track-ui, 0.01em);
+          color: var(--foreground);
+          background: var(--field, var(--boxel-light));
+          box-shadow: 0 0 0 1px var(--input);
+          width: 100%;
+        }
+        /* trigger grows with wrapped chips; keeps the h28 rest state */
+        .pretui-mstrigger {
+          height: auto;
+          min-height: var(--control-h, 28px);
+          flex-wrap: wrap;
+          gap: 3px;
+          padding: 3px 9px 3px 4px;
+          cursor: pointer;
+        }
+        /* The ring is a box-shadow so it costs no layout — but a box-shadow is
+           not painted at all in forced-colors mode, which would leave this
+           trigger with no focus indicator in high contrast. The transparent
+           outline is the standard fix: it paints nothing in normal rendering
+           and it never participates in layout, while forced-colors forces
+           outline-color to a system colour and the ring reappears. boxel-ui
+           uses exactly this device on its own invalid-input focus state. */
+        .pretui-mstrigger:focus-visible {
+          outline: 2px solid transparent;
+          outline-offset: 1px;
+          box-shadow: 0 0 0 2px var(--primary), var(--pretui-shadow-inset, inset 0 1px 2px rgb(0 0 0 / 0.16));
+        }
+        .pretui-mstrigger[data-state='open'] {
+          box-shadow: 0 0 0 2px var(--primary), var(--pretui-shadow-inset, inset 0 1px 2px rgb(0 0 0 / 0.16));
+        }
+        .pretui-mstrigger[data-disabled] {
+          opacity: 0.45;
+          cursor: default;
+        }
+        .pretui-placeholder {
+          color: var(--ink-3, var(--boxel-400));
+          padding-left: 5px;
+        }
+        .pretui-caret {
+          flex: none;
+          margin-left: auto;
+          color: var(--ink-3, var(--boxel-400));
+        }
+        /* selected chips — FilterChips capsule dress, cut down to 20px */
+        .pretui-mschip {
+          display: inline-flex;
+          align-items: center;
+          gap: 3px;
+          height: 20px;
+          border-radius: 10px;
+          padding: 0 3px 0 calc(4px * var(--pretui-capsule-base, 1.35) + 10px * var(--pretui-radius-encroach, 0.35));
+          background: var(--card);
+          box-shadow: var(--pretui-shadow-control, 0 0 0 1px var(--border));
+          font-size: var(--text-ui-sm, 11.5px);
+          font-weight: 500;
+          color: var(--foreground);
+          flex: none;
+        }
+        .pretui-mschip-x {
+          border: 0;
+          background: none;
+          padding: 0;
+          width: 14px;
+          height: 14px;
+          border-radius: 50%;
+          display: inline-grid;
+          place-content: center;
+          color: var(--ink-3, var(--boxel-400));
+          cursor: pointer;
+          flex: none;
+        }
+        .pretui-mschip-x:hover {
+          background: var(--hover, var(--boxel-100));
+          color: var(--foreground);
+        }
+        .pretui-select-backdrop {
+          /* wave-0 backdrop-close: viewport-covering close target instead of a
+             document listener; fixed is intentional (lint warns, accepted) */
+          position: fixed;
+          inset: 0;
+          background: transparent;
+          border: 0;
+          /* kit stacking scale (pretui-css.gts). A scrim always sits one tier
+             BELOW the surface it dismisses — the bare 49 this replaced
+             outranked the listbox's auto z, so the scrim painted over the
+             options it was meant to sit behind. */
+          z-index: var(--pretui-z-scrim, 50);
+          cursor: default;
+        }
+        .pretui-listbox {
+          /* positioned by the Popup primitive (fixed, clip-proof, matchWidth) */
+          position: relative;
+          z-index: var(--pretui-z-dropdown, 60);
+          background: var(--popover);
+          border-radius: 10px;
+          box-shadow: var(--pretui-shadow-overlay, 0 0 0 1px var(--border), 0 8px 28px rgb(0 0 0 / 0.16));
+          padding: 4px;
+          min-width: 100%;
+        }
+        .pretui-listbox-hl {
+          position: absolute;
+          left: 4px;
+          right: 4px;
+          border-radius: 6px;
+          background: var(--hover, var(--boxel-100));
+          transition: transform var(--pretui-dur-snap, 180ms) var(--pretui-ease-snap, ease);
+          pointer-events: none;
+        }
+        .pretui-option {
+          position: relative;
+          display: flex;
+          align-items: center;
+          gap: 7px;
+          height: 28px;
+          padding: 0 8px;
+          border-radius: 6px;
+          font-size: var(--text-ui-md, 12.5px);
+          cursor: pointer;
+          color: var(--foreground);
+        }
+        /* checkbox marker — the pretui-checkbox recipe at option scale */
+        .pretui-msbox {
+          width: 15px;
+          height: 15px;
+          border-radius: 5px;
+          background: var(--pretui-control-rest, var(--field, var(--boxel-light)));
+          box-shadow: 0 0 0 1px var(--pretui-control-border, var(--input));
+          display: inline-grid;
+          place-content: center;
+          flex: none;
+          transition: background var(--pretui-dur-snap, 180ms) var(--pretui-ease-snap, ease);
+        }
+        .pretui-msbox[data-state='checked'] {
+          background: var(--primary);
+          box-shadow: 0 0 0 1px color-mix(in oklch, var(--primary) 70%, var(--border)),
+            var(--pretui-edge-highlight, inset 0 1px 0 rgb(255 255 255 / 0.14));
+        }
+        .pretui-msbox-check {
+          width: 9px;
+          height: 9px;
+          background: var(--primary-foreground);
+          clip-path: polygon(14% 47%, 38% 70%, 86% 18%, 96% 30%, 39% 89%, 4% 58%);
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-listbox-hl,
+          .pretui-msbox {
+            transition: none;
+          }
+        }
+        .pretui-selectwrap :deep(.pretui-popup-anchor) {
+          display: block;
+          width: 100%;
+        }
+      }
+    </style>
+  </template>
+}
+

package/bundled-realms/pretui/components/multi-select.md

@@ -0,0 +1,57 @@
+## What it is
+
+Pick several values from a known list, with the chosen ones shown as removable chips in the trigger. Use it for tags, assignees, filter facets — anywhere the selection is a set and the user needs to see it without opening the list. For one value, **Select**. For a value that may not be in the list, **Combobox**. For a searchable set of records, **Lookup**. For a two-column available/chosen arrangement over a long list, **DuelingPicklist**. For a multi-select with a select-all row and a search box, **Picker**.
+
+## The contract
+
+```
+@options: { value, label }[]   (required)
+@value?, @defaultValue?, @placeholder?, @disabled?
+@label?        — accessible name; falls back to @placeholder, then 'Select items'
+@onValueChange?(values: string[])
+```
+
+Hybrid controlled/uncontrolled, the kit-wide idiom.
+
+**The trigger is a `role="combobox"` `<div>`, not a `<button>`, and that is a deliberate legality fix.** The chips inside the trigger carry their own remove buttons, and a `<button>` cannot legally contain another `<button>`. Making the trigger a div with an explicit role keeps the markup valid while preserving the combobox semantics.
+
+**Toggling an option keeps the list open.** That is the difference from **Select**, and it is what a multi-select is for — closing after each pick would make selecting five things five round trips.
+
+## Prior art
+
+**boxel-ui's `BoxelMultiSelect` rides the ember-power-select wormhole**, which is on this kit's wart list — the portal escapes the theme island, so theme tokens cannot reach the dropdown. So this is a **fresh build on the kit's own `Popup` primitive** rather than a wrap, mirroring **Select**'s structure exactly: the same trigger dress, the same focus ring while open, the same listbox with the traveling highlight, the same viewport-covering backdrop button instead of a `document` click listener.
+
+Against the field: **Web Awesome `wa-select multiple`** shows chips with `max-options-visible` (default 3) and a `getTag(option, index)` render hook. **React Spectrum** has no multi-select picker. **Radix** has none; the ecosystem uses Popover + Command, which is what shadcn's multi-select recipes are.
+
+Where Pretui is ahead of the shadcn assembly: it is one component with real listbox semantics rather than three composed libraries. Where it is behind Web Awesome: **no overflow cap.** There is no `@maxSelectedDisplay`, so selecting twenty options grows the trigger unboundedly — **Picker**, which wraps boxel-ui, does have that arg. That is the clearest gap and it is the first thing a real list will hit.
+
+Also missing versus both: no search/filter inside the dropdown (Select auto-enables one past seven options; this does not), no grouping, and no select-all.
+
+## Accessibility
+
+Governing pattern: APG **Combobox with listbox popup**, multi-select form.
+
+Present and correct, and this is one of the more complete ARIA implementations in the kit: `role="combobox"` on the trigger with `aria-haspopup="listbox"`, `aria-controls` pointing at the listbox id, `aria-expanded`, `aria-disabled` and `aria-label`; `role="listbox"` with **`aria-multiselectable="true"`** on the panel; `role="option"` with `aria-selected` explicitly `'true'`/`'false'` on every row; `aria-label="Remove {label}"` on each chip's remove button; an `aria-label="Close"` backdrop at `tabindex="-1"`.
+
+Keyboard: Enter, Space and ArrowDown open; ArrowUp/ArrowDown move the highlight, Home/End jump to the ends, and typing jumps to the next matching label; Enter/Space toggle; Escape closes. Focus stays on the trigger, and `aria-activedescendant` names the highlighted option, so a screen reader follows the highlight. A polite status announces the selection count.
+
+Gaps:
+
+- **No `@controlId`.** The trigger is a `role="combobox"` `<div>`, which a `<label for>` cannot name, so **Field**/**FormField** wiring needs `@label` instead.
+- **The chip remove buttons are pointer-only** (`tabindex="-1"`), so they add no tab stops. Keyboard removal goes through the list, where Enter or Space toggles the option off.
+- **`aria-disabled` rather than the native attribute** keeps a disabled control focusable — arguably better than **Input**'s native `disabled`, and inconsistent with it.
+- The dropdown escapes clipping via `Popup`'s `position: fixed`, so unlike **Select** it is not clipped by `overflow: hidden` ancestors.
+
+## Theming
+
+Trigger: `--field`, `--input`, `--primary` (the open/focus ring), `--ink-3` (placeholder), `--control-h`, `--radius`, `--text-ui-md`, `--track-ui`. Chips: **FilterChips**' capsule dress. Listbox: `--popover`, `--hover`, `--foreground`, `--pretui-shadow-overlay`, and the 28px row height the index-positioned highlight depends on.
+
+**That 28px is load-bearing**: the traveling highlight is positioned by index × row height rather than measured, so a theme that changes option row height without changing the highlight's step will desynchronize them. It is the one metric here that cannot safely be retuned in CSS alone.
+
+The styles sit in `@layer PretComposite`, above Popup's `PretComponent` layer, so what this component sets on Popup wins by layer order. A caller's unlayered CSS overrides both without a more specific selector.
+
+## React ecosystem
+
+Value is a **known set** (records or enums). Free-string chips are
+**TagsInput**. Record references with search are **Lookup**. Ant
+`mode=multiple` is this; `mode=tags` is TagsInput.