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

package/bundled-realms/pretui/components/combobox.gts

@@ -0,0 +1,333 @@
+// Pretui — Combobox: a text input with a filtered option list.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { guidFor } from '@ember/object/internals';
+import { PoweredValuePicker, SelectedValue } from '../internal/forms-picker';
+import type { PickerSelectApi } from '../internal/forms-picker';
+
+// ── Combobox ─────────────────────────────────────────────────────────────
+// A free-text input over a filtering listbox, on power-select's engine, for closed sets that are too long to scroll and
+// too short to need a server. Where `Select` puts the search
+// box INSIDE the dropdown — power-select resolves `searchFieldPosition` to
+// 'before-options' for single selects — a combobox must have the text field
+// BE the control, which is what the multiple trigger gives. So Combobox
+// rides the same multiple engine and caps the selection at one.
+//
+// ARIA pattern: editable combobox + listbox + aria-activedescendant,
+// supplied by power-select. Documented delta: `aria-multiselectable='true'`
+// rides along on the listbox.
+//
+// Not supported, deliberately: accepting a value that is NOT in @options
+// ("create on the fly"). That is power-select-with-create, a separate addon
+// the realm cannot import.
+export interface ComboboxOption {
+  /** Stable value emitted through @onValueChange. */
+  value: string;
+  /** Visible text, and what the local filter matches. */
+  label: string;
+  /** Optional secondary line in the dropdown row. */
+  meta?: string;
+}
+
+export interface ComboboxSignature {
+  Args: {
+    /** The full candidate list. Filtering is local — no fetching here. */
+    options: ComboboxOption[];
+    /** Controlled value. Omit to let the component hold it. */
+    value?: string;
+    /** Uncontrolled initial value; ignored once @value is supplied. */
+    defaultValue?: string;
+    /** Input placeholder. */
+    placeholder?: string;
+    /** Accessible name for the combobox input. */
+    label?: string;
+    /** Blocks every interaction. */
+    disabled?: boolean;
+    /** Error dress plus aria-invalid. */
+    invalid?: boolean;
+    /** Emitted on every keystroke with the current search text. */
+    onSearch?: (query: string) => void;
+    /** Emitted with the chosen value, or '' when the value is cleared. */
+    onValueChange?: (value: string) => void;
+    /** Emitted when the dropdown opens or closes. */
+    onOpenChange?: (open: boolean) => void;
+  };
+  Blocks: {
+    /** Replace the default row. Yields the option and the current term. */
+    option: [option: ComboboxOption, state: { term: string }];
+  };
+  Element: HTMLDivElement;
+}
+
+export class Combobox extends Component<ComboboxSignature> {
+  uid = guidFor(this);
+  @tracked internal = this.args.defaultValue ?? '';
+  @tracked term = '';
+
+  get value() {
+    return this.args.value ?? this.internal;
+  }
+  get options() {
+    return this.args.options ?? [];
+  }
+  get selectedOptions(): ComboboxOption[] {
+    let hit = this.options.find((o) => o.value === this.value);
+    return hit ? [hit] : [];
+  }
+  get label() {
+    return this.args.label ?? 'Choose an option';
+  }
+  get placeholder() {
+    return this.args.placeholder ?? 'Type to filter…';
+  }
+  optionState = () => ({ term: this.term });
+  registerApi = (select: PickerSelectApi) => {
+    let next = select?.searchText ?? '';
+    if (next !== this.term) {
+      this.term = next;
+      this.args.onSearch?.(next);
+    }
+  };
+  handleChange = (selection: ComboboxOption[]) => {
+    let last = selection[selection.length - 1];
+    let next = last ? last.value : '';
+    if (this.args.value === undefined) {
+      this.internal = next;
+    }
+    this.args.onValueChange?.(next);
+  };
+  handleOpen = () => {
+    this.args.onOpenChange?.(true);
+  };
+  handleClose = () => {
+    this.args.onOpenChange?.(false);
+  };
+
+  <template>
+    <div
+      class='pretui-combobox'
+      data-disabled={{if @disabled 'true'}}
+      data-invalid={{if @invalid 'true'}}
+      data-test-pretui-combobox
+      ...attributes
+    >
+      <PoweredValuePicker
+        class='pretui-pickertrigger'
+        aria-invalid={{if @invalid 'true'}}
+        @options={{this.options}}
+        @selected={{this.selectedOptions}}
+        @onChange={{this.handleChange}}
+        @placeholder={{this.placeholder}}
+        @disabled={{@disabled}}
+        @searchEnabled={{true}}
+        @searchField='label'
+        @closeOnSelect={{true}}
+        @matchTriggerWidth={{true}}
+        @renderInPlace={{true}}
+        @dropdownClass='pretui-picker-dropdown'
+        @ariaLabel={{this.label}}
+        @registerAPI={{this.registerApi}}
+        @onOpen={{this.handleOpen}}
+        @onClose={{this.handleClose}}
+        @selectedItemComponent={{SelectedValue}}
+        as |option|
+      >
+        {{#if (has-block 'option')}}
+          {{yield option (this.optionState)}}
+        {{else}}
+          <span class='pretui-cbx-row'>
+            <span class='pretui-cbx-label'>{{option.label}}</span>
+            {{#if option.meta}}
+              <span class='pretui-cbx-meta'>{{option.meta}}</span>
+            {{/if}}
+          </span>
+        {{/if}}
+      </PoweredValuePicker>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-combobox {
+          position: relative;
+          display: block;
+          min-width: 0;
+          --boxel-form-control-border-radius: var(--radius);
+          --boxel-border-radius-sm: var(--radius);
+          --boxel-select-trigger-padding: 0;
+          --boxel-dropdown-background-color: var(--popover);
+          --boxel-dropdown-text-color: var(--foreground);
+          --boxel-dropdown-hover-color: var(--hover, var(--boxel-100));
+          --boxel-dropdown-highlight-color: var(--hover, var(--boxel-100));
+        }
+        .pretui-cbx-row {
+          display: flex;
+          align-items: baseline;
+          gap: var(--space-3, 8px);
+          min-width: 0;
+        }
+        .pretui-cbx-label {
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+        }
+        .pretui-cbx-meta {
+          margin-left: auto;
+          font-size: var(--text-ui-xs, 11px);
+          color: var(--muted-foreground);
+          white-space: nowrap;
+        }
+      }
+      /* Unlayered: BoxelMultiSelect's power-select rules are unlayered, and
+         unlayered CSS beats any layer, so these overrides only win from outside one. */
+      .pretui-combobox :deep(.pretui-pickertrigger.ember-power-select-trigger) {
+        display: flex;
+        align-items: center;
+        min-height: var(--control-h, 28px);
+        padding: 2px 8px 2px 4px;
+        border: 0;
+        border-radius: var(--radius);
+        background: var(--field, var(--boxel-light));
+        box-shadow: 0 0 0 1px var(--input);
+        color: var(--foreground);
+        width: 100%;
+      }
+      /* Transparent outline doubles the ring for forced-colors, where a
+         box-shadow is not painted. */
+      .pretui-combobox
+        :deep(.pretui-pickertrigger.ember-power-select-trigger[aria-expanded='true']),
+      .pretui-combobox
+        :deep(.pretui-pickertrigger.ember-power-select-trigger:focus-within) {
+        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-combobox[data-invalid]
+        :deep(.pretui-pickertrigger.ember-power-select-trigger) {
+        box-shadow: 0 0 0 1px var(--destructive);
+      }
+      .pretui-combobox[data-disabled]
+        :deep(.pretui-pickertrigger.ember-power-select-trigger) {
+        opacity: 0.45;
+        cursor: default;
+      }
+      .pretui-combobox :deep(ul.ember-power-select-multiple-options) {
+        display: flex;
+        flex-wrap: nowrap;
+        align-items: center;
+        gap: 4px;
+        list-style: none;
+        margin: 0;
+        padding: 0;
+        width: 100%;
+        min-width: 0;
+      }
+      /* single value: the chosen label reads as text, not a capsule */
+      .pretui-combobox :deep(li.ember-power-select-multiple-option) {
+        display: inline-flex;
+        align-items: center;
+        gap: 4px;
+        margin: 0;
+        padding: 0 0 0 5px;
+        border: 0;
+        background: none;
+        color: var(--foreground);
+        max-width: 60%;
+        overflow: hidden;
+      }
+      .pretui-combobox :deep(.ember-power-select-multiple-remove-btn) {
+        order: 2;
+        display: inline-grid;
+        place-content: center;
+        width: 14px;
+        height: 14px;
+        border-radius: 50%;
+        color: var(--ink-3, var(--boxel-400));
+        cursor: pointer;
+        opacity: 1;
+        font-size: 12px;
+        line-height: 1;
+      }
+      .pretui-combobox :deep(.ember-power-select-multiple-remove-btn:hover) {
+        background: var(--hover, var(--boxel-100));
+        color: var(--foreground);
+      }
+      .pretui-combobox
+        :deep(li.ember-power-select-trigger-multiple-input-container) {
+        flex: 1 1 6ch;
+        min-width: 4ch;
+        margin: 0;
+      }
+      .pretui-combobox :deep(input.ember-power-select-trigger-multiple-input) {
+        width: 100%;
+        height: 24px;
+        margin: 0;
+        padding: 0 5px;
+        border: 0;
+        background: transparent;
+        font: inherit;
+        font-size: var(--text-ui-md, 12.5px);
+        letter-spacing: var(--track-ui, 0.01em);
+        color: var(--foreground);
+      }
+      .pretui-combobox
+        :deep(input.ember-power-select-trigger-multiple-input:focus) {
+        outline: none;
+      }
+      .pretui-combobox
+        :deep(input.ember-power-select-trigger-multiple-input::placeholder) {
+        color: var(--ink-3, var(--boxel-400));
+      }
+      .pretui-combobox
+        :deep(.pretui-picker-dropdown.ember-power-select-dropdown) {
+        background: var(--popover);
+        border: 0;
+        border-radius: 10px;
+        box-shadow: var(
+          --pretui-shadow-overlay,
+          0 0 0 1px var(--border),
+          0 8px 28px rgb(0 0 0 / 0.16)
+        );
+        overflow: hidden;
+      }
+      .pretui-combobox :deep(.pretui-picker-dropdown ul) {
+        padding: 4px;
+        gap: 1px;
+        max-height: var(--pretui-combobox-max-height, 15rem);
+      }
+      .pretui-combobox
+        :deep(.pretui-picker-dropdown li.ember-power-select-option) {
+        min-height: 28px;
+        margin: 0;
+        padding: 3px 8px;
+        align-items: center;
+        border-radius: var(--radius-chip, 6px);
+        background: transparent;
+        color: var(--foreground);
+        font-size: var(--text-ui-md, 12.5px);
+        transition: none;
+      }
+      .pretui-combobox
+        :deep(.pretui-picker-dropdown li.ember-power-select-option--highlighted),
+      .pretui-combobox
+        :deep(.pretui-picker-dropdown li.ember-power-select-option:hover) {
+        background: var(--hover, var(--boxel-100));
+      }
+      .pretui-combobox
+        :deep(.pretui-picker-dropdown li.ember-power-select-option[aria-selected='true']) {
+        font-weight: 600;
+        color: var(--pretui-primary-ink, var(--primary));
+      }
+      .pretui-combobox
+        :deep(.pretui-picker-dropdown .ember-power-select-option--no-matches-message) {
+        min-height: 28px;
+        display: flex;
+        align-items: center;
+        padding: 0 8px;
+        color: var(--ink-3, var(--boxel-400));
+        font-style: normal;
+        font-size: var(--text-ui-md, 12.5px);
+        text-align: left;
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/combobox.md

@@ -0,0 +1,49 @@
+## What it is
+
+A free-text input over a filtering listbox: type to narrow a known list, then choose from it.
+
+The difference from **Autocomplete** is what counts as a value. A combobox's value is constrained to its list; an autocomplete's value is whatever the reader typed, with the list as help. If free text is a legal answer, you want the other one.
+
+## The contract
+
+```
+@options (required) — the full candidate list; filtering is local
+@value?, @defaultValue? — controlled / uncontrolled
+@placeholder?
+@label?          — accessible name for the combobox input
+@disabled?       — blocks every interaction
+@invalid?        — error dress plus aria-invalid
+@onSearch?       — emitted on every keystroke with the current search text
+@onValueChange?  — emitted with the chosen value, or '' when cleared
+@onOpenChange?   — emitted when the dropdown opens or closes
+
+<:option> — replaces the default row; yields the option and { term }
+```
+
+**Filtering is local and there is no fetching here.** `@options` is the full candidate list and the component narrows it; `@onSearch` exists so a caller can react to the query, not so the component can wait for one.
+
+**Clearing reports `''`, not null.** One empty representation, matching the kit's convention that a control's value is a string.
+
+**The option block receives the live term**, so a custom row can highlight the match without re-deriving it.
+
+## Prior art
+
+**React Spectrum's Combobox.**
+
+Where Pretui is better: the explicit split from Autocomplete. Most kits ship one component with a `freeSolo` or `allowsCustomValue` flag, which means the value's _type_ changes with a boolean — a caller has to handle both shapes everywhere. Two components with two contracts is the clearer answer.
+
+Where it is thinner: no async loading, no grouped or sectioned options, no multi-select, and no virtualisation — a very long option list renders in full. There is also no "create this" affordance, which is what a `freeSolo` flag usually buys.
+
+## Accessibility
+
+- **The input is the combobox** and carries `aria-invalid` when `@invalid`, so the error state is announced rather than only dressed.
+- **`@label` names the input.** Without a wrapper supplying a label, an unnamed combobox is announced as an unlabelled text field with a popup.
+- **`<:option>` is rendered into a row whose accessible name is computed**, so custom markup in the block cannot corrupt what the option announces.
+- **Open and close are reported through `@onOpenChange`**, which a caller needs if it is coordinating with anything else on screen — two popovers open at once is a focus problem.
+- **Local filtering means the list is complete and stable**, so a reader arrowing through options is not racing a fetch.
+
+## Theming
+
+`--pretui-combobox-max-height` bounds the dropdown, over the kit's shared overlay tokens — `--pretui-shadow-overlay` for the layer, `--pretui-shadow-control` and `--pretui-shadow-inset` for the field, `--pretui-destructive-ink` for the invalid state, and `--pretui-dur-snap` / `--pretui-ease-snap` for the open transition.
+
+The rules for the combobox's own elements sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector. The `:deep()` rules that restyle BoxelMultiSelect's power-select markup stay unlayered, because its own rules are unlayered and would beat them from inside a layer.

package/bundled-realms/pretui/components/combobox.usage.gts

@@ -0,0 +1,143 @@
+// Pretui — Combobox usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { PLACES, TEAS, pick, seedFrom } from '../examples';
+import { Combobox } from './combobox';
+import { FreestyleUsage } from './freestyle-usage';
+
+// ── Combobox ← the Lookup engine over plain {value,label} options ────────
+// Same ember-power-select engine as Lookup, single-valued. Where Pretui's
+// Select puts the search box inside the dropdown (power-select resolves
+// searchFieldPosition to 'before-options' for single selects), a combobox
+// needs the text field to BE the control — so this rides the multiple
+// trigger and caps the selection at one.
+class ComboboxUsage extends Component {
+  origins = PLACES.slice(0, 10).map((name, i) => ({
+    value: name.toLowerCase().replace(/[^a-z0-9]+/g, '-'),
+    label: name,
+    meta: pick(seedFrom(name), i, TEAS),
+  }));
+  @tracked value = '';
+  @tracked term = '';
+  @tracked placeholder = 'Type to filter origins…';
+  @tracked disabled = false;
+  @tracked invalid = false;
+
+  get optionValues() {
+    return this.origins.map((o) => o.value);
+  }
+  setValue = (v: string) => (this.value = v);
+  setTerm = (v: string) => (this.term = v);
+  setPlaceholder = (v: string) => (this.placeholder = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  setInvalid = (v: boolean) => (this.invalid = v);
+
+  get usage() {
+    let bits = ['@options={{this.origins}}', `@value='${this.value}'`];
+    if (this.placeholder) {
+      bits.push(`@placeholder='${this.placeholder}'`);
+    }
+    if (this.disabled) {
+      bits.push('@disabled={{true}}');
+    }
+    if (this.invalid) {
+      bits.push('@invalid={{true}}');
+    }
+    bits.push('@onValueChange={{this.setValue}}');
+    return `<Combobox ${bits.join('\n  ')}\n/>`;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='Combobox'
+      @description='A free-text input over a filtering listbox — the control for a closed set that is too long to scroll comfortably and too short to need a server. Type and the list narrows; Enter or click commits; the chosen label stays in the field as editable-looking text with a clear control. Reach for Combobox over Select whenever the option count passes roughly a dozen, and over Lookup whenever the values are plain data rather than records. It rides the same ember-power-select engine as Lookup (BoxelMultiSelect, rendered in place), so dismissal, Escape, focus return, arrow keys, the aria-activedescendant wiring and the result-count live region are the engine’s. Honest limits: it will NOT accept a value outside @options — creating on the fly is power-select-with-create, an addon the realm cannot import; filtering is local over @options, matched on label; and the listbox reports aria-multiselectable even though only one value can be held, because the single-value trigger is the multiple trigger with a cap of one.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <Combobox
+          @options={{this.origins}}
+          @value={{this.value}}
+          @placeholder={{this.placeholder}}
+          @disabled={{this.disabled}}
+          @invalid={{this.invalid}}
+          @label='Growing origin'
+          @onSearch={{this.setTerm}}
+          @onValueChange={{this.setValue}}
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='options'
+          @required={{true}}
+          @description='The full candidate list: {value, label, meta?}. Filtering is local, so hand over everything the user may pick.'
+          @value={{this.origins}}
+        />
+        <Args.String
+          @name='value'
+          @value={{this.value}}
+          @options={{this.optionValues}}
+          @description='Controlled value. Omit it and the component holds its own (@defaultValue seeds that). Clearing emits an empty string.'
+          @onInput={{this.setValue}}
+        />
+        <Args.Base
+          @name='defaultValue'
+          @type='String'
+          @description='Uncontrolled initial value. Ignored once @value is supplied.'
+        />
+        <Args.String
+          @name='placeholder'
+          @value={{this.placeholder}}
+          @defaultValue='Type to filter…'
+          @description='Input placeholder.'
+          @onInput={{this.setPlaceholder}}
+        />
+        <Args.Base
+          @name='label'
+          @type='String'
+          @defaultValue='Choose an option'
+          @description='Accessible name for the combobox input (passed to the engine as @ariaLabel).'
+        />
+        <Args.Bool
+          @name='disabled'
+          @defaultValue={{false}}
+          @description='Blocks every interaction.'
+          @value={{this.disabled}}
+          @onInput={{this.setDisabled}}
+        />
+        <Args.Bool
+          @name='invalid'
+          @defaultValue={{false}}
+          @description='Error dress plus aria-invalid. It marks; it never validates.'
+          @value={{this.invalid}}
+          @onInput={{this.setInvalid}}
+        />
+        <Args.String
+          @name='(search text)'
+          @value={{this.term}}
+          @description='READ-ONLY, and not an arg — the engine owns the search text. This row mirrors what @onSearch last reported.'
+          @onInput={{this.setTerm}}
+        />
+        <Args.Action
+          @name='onSearch'
+          @description='Fires on every keystroke with the current search text. Useful for analytics or a "no match — create one?" affordance beside the field.'
+        />
+        <Args.Action
+          @name='onValueChange'
+          @description="Fires with the chosen value, or '' when the value is cleared."
+        />
+        <Args.Action
+          @name='onOpenChange'
+          @description='Fires with true/false when the dropdown opens or closes.'
+        />
+        <Args.Yield
+          @name=':option'
+          @description='Replaces the default row. Yields (option, {term}). The default row is the label with an optional right-aligned meta.'
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_COMBOBOX: Record<string, unknown> = {
+  Combobox: ComboboxUsage,
+};