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

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

@@ -0,0 +1,97 @@
+// Pretui — MultiSelect usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { MultiSelect } from './multi-select';
+
+const COUNTRY_NAMES = [
+  'United States',
+  'Spain',
+  'Portugal',
+  'Russia',
+  'Latvia',
+  'Brazil',
+  'United Kingdom',
+];
+const COUNTRY_OPTIONS = COUNTRY_NAMES.map((c) => ({ value: c, label: c }));
+
+
+// ── MultiSelect ← multi-select/usage.gts ─────────────────────────────────
+// Dropped knobs: @renderInPlace / @matchTriggerWidth (Popup always renders
+// in place and matches the trigger), @searchEnabled / @searchField (no
+// search box in wave-0), @closeOnSelect (the listbox always stays open
+// across toggles — that's the multi-select semantic), @selectedItemComponent
+// and the custom AssigneePill / CheckboxIndicator dropdown components
+// (options are {value, label} data, rendered by the component),
+// @registerAPI / publicAPI (no power-select escape hatch), the
+// boxel-selected-pill-* css vars (chips wear the FilterChips capsule dress
+// from theme tokens).
+export class MultiSelectUsage extends Component {
+  countryOptions = COUNTRY_OPTIONS;
+  @tracked values: string[] = ['Spain', 'Portugal'];
+  @tracked placeholder = 'Select Items';
+  @tracked disabled = false;
+  setValues = (v: string[]) => (this.values = v);
+  setPlaceholder = (v: string) => (this.placeholder = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  get usage() {
+    let bits = ['@options={{this.countries}}', '@value={{this.values}}'];
+    if (this.placeholder) bits.push(`@placeholder='${this.placeholder}'`);
+    if (this.disabled) bits.push('@disabled={{true}}');
+    bits.push('@onValueChange={{this.setValues}}');
+    return `<MultiSelect ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='MultiSelect'
+      @description='Dropdown control that lets the user pick multiple values from a list — shows the selected items as removable chips and emits the full selection on every toggle. Built fresh on the Popup primitive; keyboard: arrows move, Enter toggles, Escape closes.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <MultiSelect
+          @options={{this.countryOptions}}
+          @value={{this.values}}
+          @placeholder={{this.placeholder}}
+          @disabled={{this.disabled}}
+          @onValueChange={{this.setValues}}
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='options'
+          @required={{true}}
+          @description='An array of items to be listed on the dropdown — {value, label} pairs.'
+          @value={{this.countryOptions}}
+        />
+        <Args.Array
+          @name='value'
+          @description="Array of selected values — boxel-ui's @selected array of objects, now string values (comma-separate to edit)."
+          @value={{this.values}}
+          @onInput={{this.setValues}}
+        />
+        <Args.String
+          @name='placeholder'
+          @description='Placeholder for trigger component'
+          @value={{this.placeholder}}
+          @onInput={{this.setPlaceholder}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @defaultValue={{false}}
+          @description='When truthy the component cannot be interacted'
+          @value={{this.disabled}}
+          @onInput={{this.setDisabled}}
+        />
+        <Args.Action
+          @name='onValueChange'
+          @description="Receives the full selection as string[] on every toggle — boxel-ui's @onChange, which received the selected objects."
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+
+export const DEMOS_MULTI_SELECT: Record<string, unknown> = {
+  MultiSelect: MultiSelectUsage,
+};

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

@@ -0,0 +1,212 @@
+// Pretui — NativeSelect: a styled closed face over a real <select>. The
+// platform draws the open list, so a phone gets its own picker and the
+// control works in a form without a script. Select is the popup one.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { emit, firstDefined, resolveSize } from '../pretui-primitives';
+import type { ControlAliasArgs, PretuiSizeArg } from '../pretui-primitives';
+
+export interface NativeSelectOption {
+  value: string;
+  label: string;
+  disabled?: boolean;
+}
+
+export interface NativeSelectSignature {
+  Args: ControlAliasArgs & {
+    options?: NativeSelectOption[];
+    /** alias — the canonical flat-collection noun */
+    items?: NativeSelectOption[];
+    value?: string;
+    defaultValue?: string;
+    /** a disabled, unselectable first option, shown while nothing is chosen */
+    placeholder?: string;
+    disabled?: boolean;
+    required?: boolean;
+    invalid?: boolean;
+    /** alias — React Aria / Base UI spelling of @invalid */
+    isInvalid?: boolean;
+    /** the id a <label for> points at */
+    controlId?: string;
+    /** accessible name when no label element points here */
+    label?: string;
+    size?: PretuiSizeArg;
+  };
+  Blocks: {
+    /** hand-written <option> / <optgroup>; replaces @options */
+    default: [];
+  };
+  Element: HTMLSelectElement;
+}
+
+export class NativeSelect extends Component<NativeSelectSignature> {
+  @tracked internal = this.args.defaultValue;
+  get options(): NativeSelectOption[] {
+    return firstDefined(this.args.options, this.args.items) ?? [];
+  }
+  /** With no placeholder the platform selects the first enabled option, so
+   *  that option is the value until something else is chosen. */
+  get value() {
+    let chosen = this.args.value ?? this.internal;
+    if (chosen !== undefined) {
+      return chosen;
+    }
+    if (this.args.placeholder) {
+      return '';
+    }
+    return this.options.find((o) => !o.disabled)?.value ?? '';
+  }
+  /** the placeholder is showing; without one the select always shows a choice */
+  get empty() {
+    return Boolean(this.args.placeholder) && this.value === '';
+  }
+  get disabled() {
+    return firstDefined(this.args.disabled, this.args.isDisabled) ?? false;
+  }
+  get required() {
+    return firstDefined(this.args.required, this.args.isRequired) ?? false;
+  }
+  get invalid() {
+    return firstDefined(this.args.invalid, this.args.isInvalid) ?? false;
+  }
+  get size() {
+    return resolveSize(this.args.size);
+  }
+  handleChange = (ev: Event) => {
+    let select = ev.target as HTMLSelectElement;
+    let next = select.value;
+    if (this.args.value === undefined) {
+      this.internal = next;
+    }
+    emit([this.args.onChange, this.args.onValueChange], next);
+    if (this.args.value !== undefined) {
+      // controlled: show the owner's value until the owner moves it
+      select.value = this.value;
+    }
+  };
+  isOn = (option: NativeSelectOption) => option.value === this.value;
+  <template>
+    <span
+      class='pretui-nativeselect'
+      data-size={{this.size}}
+      data-empty={{if this.empty 'true' 'false'}}
+      data-invalid={{if this.invalid 'true' 'false'}}
+      data-test-pretui-native-select
+    >
+      <select
+        class='pretui-nativeselect-control'
+        id={{@controlId}}
+        aria-label={{@label}}
+        aria-invalid={{if this.invalid 'true'}}
+        disabled={{this.disabled}}
+        required={{this.required}}
+        {{on 'change' this.handleChange}}
+        ...attributes
+      >
+        {{#if @placeholder}}
+          <option value='' disabled selected={{this.empty}}>{{@placeholder}}</option>
+        {{/if}}
+        {{#if (has-block)}}
+          {{yield}}
+        {{else}}
+          {{! the param is not named `option`: a lowercase tag that matches an in-scope binding invokes it }}
+          {{#each this.options as |opt|}}
+            <option
+              value={{opt.value}}
+              selected={{this.isOn opt}}
+              disabled={{opt.disabled}}
+            >{{opt.label}}</option>
+          {{/each}}
+        {{/if}}
+      </select>
+      <svg class='pretui-nativeselect-caret' viewBox='0 0 12 12' aria-hidden='true'>
+        <path d='M3 4.5l3 3 3-3' />
+      </svg>
+    </span>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-nativeselect {
+          --ns-h-base: var(--control-h, 1.75rem);
+          --ns-h: var(--ns-h-base);
+          --ns-text: var(--text-ui-md, 0.78rem);
+          --ns-text-sm: var(--text-ui-sm, 0.72rem);
+          --ns-text-lg: var(--text-ui-lg, 0.875rem);
+          --ns-pad: var(--space-3, 0.5rem);
+          --ns-snap: var(--pretui-dur-snap, 180ms) var(--pretui-ease-snap, ease);
+          position: relative;
+          display: inline-grid;
+          align-items: center;
+          inline-size: 100%;
+          min-inline-size: 0;
+          font-size: var(--ns-text);
+          letter-spacing: var(--track-ui, 0.01em);
+        }
+        .pretui-nativeselect-control {
+          appearance: none;
+          inline-size: 100%;
+          min-block-size: var(--ns-h);
+          margin: 0;
+          padding-block: 0;
+          padding-inline: var(--ns-pad) calc(var(--ns-pad) * 2 + 0.75rem);
+          font: inherit;
+          letter-spacing: inherit;
+          color: var(--foreground);
+          background-color: var(--field);
+          border: 0;
+          border-radius: var(--radius);
+          box-shadow: 0 0 0 1px var(--input);
+          cursor: pointer;
+          transition:
+            box-shadow var(--ns-snap),
+            background-color var(--ns-snap);
+        }
+        .pretui-nativeselect[data-empty='true'] .pretui-nativeselect-control {
+          color: var(--muted-foreground);
+        }
+        .pretui-nativeselect-control:hover:not(:disabled) {
+          background-color: var(--hover);
+        }
+        .pretui-nativeselect-control:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 2px;
+        }
+        .pretui-nativeselect[data-invalid='true'] .pretui-nativeselect-control {
+          box-shadow: 0 0 0 1px var(--destructive);
+        }
+        .pretui-nativeselect-control:disabled {
+          opacity: 0.45;
+          cursor: default;
+        }
+        .pretui-nativeselect-caret {
+          position: absolute;
+          inset-inline-end: var(--ns-pad);
+          inline-size: 0.75rem;
+          block-size: 0.75rem;
+          fill: none;
+          stroke: currentColor;
+          stroke-width: 1.5;
+          stroke-linecap: round;
+          stroke-linejoin: round;
+          color: var(--muted-foreground);
+          pointer-events: none;
+        }
+        .pretui-nativeselect[data-size='xs'] {
+          --ns-h: calc(var(--ns-h-base) - 0.375rem);
+          --ns-text: var(--ns-text-sm);
+        }
+        .pretui-nativeselect[data-size='s'] {
+          --ns-h: calc(var(--ns-h-base) - 0.1875rem);
+        }
+        .pretui-nativeselect[data-size='l'] {
+          --ns-h: calc(var(--ns-h-base) + 0.25rem);
+          --ns-text: var(--ns-text-lg);
+        }
+        .pretui-nativeselect[data-size='xl'] {
+          --ns-h: calc(var(--ns-h-base) + 0.5rem);
+          --ns-text: var(--ns-text-lg);
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,77 @@
+## What it is
+
+A styled closed face over a real `<select>`. The platform draws the open list — a phone gets its own picker, a screen reader gets the native listbox, and the control posts a value in a `<form>` without a script. Use it for a short flat list where the choice is the whole job: a country, a unit, a grade. Use **Select** when the list needs typeahead, sections or rich items; it draws its own popup and pays for that with a script and its own keyboard model. Use **Combobox** when the user may type a value that is not in the list. Use **RadioGroup** when there are five options or fewer and they should all be visible.
+
+## The contract
+
+```
+@options? / @items?       — { value, label, disabled? }[]; @items is the alias
+@value?                   — controlled; leave undefined for the uncontrolled half
+@defaultValue?            — uncontrolled seed
+@onChange? / @onValueChange? — the chosen value, as a string
+@placeholder?             — a disabled first option, selected while nothing is chosen
+@disabled? @required? @invalid?
+@isDisabled? @isRequired? @isInvalid? @isReadOnly? @readOnly? — React Aria spellings
+@controlId?               — the id a <label for> points at
+@label?                   — aria-label, when no label element points here
+@size?                    — xs · s · m · l · xl (default m)
+<:default>                — hand-written <option> / <optgroup>; replaces @options
+Element: HTMLSelectElement
+```
+
+**`...attributes` reach the `<select>`, not the wrapper.** The visible box is a `<span>` that positions the caret; `name`, `form`, `autocomplete` and any `data-*` land on the control itself, so the component behaves as a `<select>` inside a form.
+
+**Without a placeholder the first enabled option is the value.** That is what the platform selects, so the component agrees: `data-empty` is `'false'` and the face reads as a choice. `data-empty='true'` only ever means the placeholder is showing.
+
+**The placeholder is a real option.** It renders as `<option value='' disabled>` and is the selected option while the value is `''`, which is what makes the closed face read the prompt. It cannot be re-chosen once a value is set; give the list an explicit "None" entry if clearing is a feature.
+
+**Hybrid state, one string out.** With `@value` undefined the component keeps its own selection and `@defaultValue` seeds it. With `@value` set the component reports the change, puts the select back to the owner's value, and renders whatever the owner decides next. Both callbacks fire on every change, with the value string — never the option object.
+
+**A default block replaces `@options` entirely.** Write `<optgroup>` and `<option>` by hand when the list has sections; keeping the chosen option's `selected` state is then the caller's job, since the component only marks options it generated.
+
+## Prior art
+
+**shadcn `NativeSelect`** is the same idea: a `<select>` with `appearance: none`, a chevron drawn beside it, `size` (`sm | default`) and `NativeSelectOption` / `NativeSelectOptGroup` children. **Mantine `NativeSelect`** takes `data` (strings or `{ value, label, disabled }`), `size`, `radius`, `leftSection` / `rightSection`, `error` and the full `Input.Wrapper` props (`label`, `description`, `withAsterisk`). **MUI `NativeSelect`** is the `Select` component with `native` on, children as `<option>`, `variant` and `IconComponent`. **Tremor `SelectNative`** is `<select>` with Tremor's field cloth and `hasError`.
+
+Where this one is better: **the alias layer.** `@items`, `@isDisabled`, `@isRequired`, `@isInvalid` and `@onValueChange` mean markup written from React Aria or Mantine memory works without a rename. **Both state halves** are supported; Mantine's `NativeSelect` is controlled-or-`defaultValue` too, but shadcn's leaves state entirely to the caller.
+
+Where it is thinner: **no label, description or error line of its own.** Mantine's wraps the control in `Input.Wrapper`; here the caption belongs to **Field**, which supplies `controlId` and the described-by id. **No leading section** — no icon or flag beside the value — and **no `radius` axis**; the corner comes from `--radius`. **The caret is fixed**; MUI's `IconComponent` has no equivalent. And the size scale moves height and type together with no independent padding knob.
+
+## Accessibility
+
+Governing pattern: none of APG's — this is the native `<select>`, and its listbox, keyboard model and announcements are the browser's. What the component does is keep from breaking that.
+
+- **The control is the `<select>`.** `appearance: none` removes the platform's closed-face painting; it does not touch the open list, the focus model or the role. Arrow keys, type-to-jump, Space/Enter to open and Escape to close are all still the platform's.
+- **The caret is `aria-hidden`** and `pointer-events: none`, so it is neither announced nor a hit target that misses the control.
+- **Naming is the caller's.** `@controlId` gives a `<label for>` something to point at, which is the preferred route; `@label` sets `aria-label` for the case where no visible label exists. Without either, the select is unnamed — the component does not invent a name from the placeholder.
+- **`@invalid` sets `aria-invalid='true'`** on the select and paints the destructive hairline; both are asserted. It does not render the message — pair it with **Field**'s error line.
+- **`@required` is the native attribute**, so a form's own validity check refuses submission while the placeholder is selected. The placeholder option being `disabled` is what makes that check meaningful.
+- **Disabled keeps the value visible** at 0.45 opacity rather than emptying the control.
+- **The focus ring is drawn** with `outline: 2px solid var(--ring)` on `:focus-visible`, because `appearance: none` discards the platform's.
+
+## Theming
+
+From the host theme, bare: `--field` (the face), `--input` (the hairline), `--hover`, `--foreground`, `--muted-foreground` (placeholder ink and the caret), `--destructive` (the invalid hairline), `--ring`, `--radius`.
+
+Kit tokens, each named once on the root and read through an internal variable: `--control-h` (the `m` height; `xs`, `s`, `l`, `xl` are offsets from it), `--text-ui-md`, `--text-ui-sm`, `--text-ui-lg`, `--space-3` (the inline padding), `--track-ui`, `--pretui-dur-snap`, `--pretui-ease-snap`.
+
+Fixed: the caret's 0.75rem box and its 1.5 stroke, the 1px hairline, the 2px focus outline, the 0.45 disabled opacity.
+
+A theme retunes the field face through `--field` and `--input` alongside **Input**, so the two read as one family; the size scale follows `--control-h`.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+| React                                           | Pretui                                          |
+| ----------------------------------------------- | ----------------------------------------------- |
+| value / onChange                                | `@value` / `@onChange` (a string, not an event) |
+| defaultValue                                    | `@defaultValue`                                 |
+| placeholder                                     | `@placeholder` — a disabled empty option        |
+| size (shadcn `sm`, Mantine `xs`–`xl`)           | `@size`                                         |
+| disabled / isDisabled                           | `@disabled` / `@isDisabled`                     |
+| required / isRequired                           | `@required` / `@isRequired`                     |
+| error (Mantine) / hasError (Tremor) / isInvalid | `@invalid` / `@isInvalid`                       |
+| data (Mantine)                                  | `@options` / `@items`                           |
+| children `<option>`                             | the default block                               |
+| label / description (Mantine)                   | **Field**                                       |

package/bundled-realms/pretui/components/native-select.usage.gts

@@ -0,0 +1,109 @@
+// Pretui — NativeSelect usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { NativeSelect } from './native-select';
+import type { PretuiSizeArg } from '../pretui-primitives';
+
+const GRADE_NAMES = ['FTGFOP1', 'TGFOP', 'GFOP', 'FOP', 'Pekoe', 'Fannings'];
+const GRADE_OPTIONS = GRADE_NAMES.map((g) => ({ value: g, label: g }));
+const SIZES = ['xs', 's', 'm', 'l', 'xl'];
+
+export class NativeSelectUsage extends Component {
+  gradeNames = GRADE_NAMES;
+  gradeOptions = GRADE_OPTIONS;
+  sizes = SIZES;
+  @tracked value = '';
+  @tracked placeholder = 'Choose a leaf grade';
+  @tracked size = 'm';
+  @tracked disabled = false;
+  @tracked required = false;
+  @tracked invalid = false;
+  setValue = (v: string) => (this.value = v);
+  setPlaceholder = (v: string) => (this.placeholder = v);
+  setSize = (v: string) => (this.size = v);
+  get sizeArg() {
+    return this.size as PretuiSizeArg;
+  }
+  setDisabled = (v: boolean) => (this.disabled = v);
+  setRequired = (v: boolean) => (this.required = v);
+  setInvalid = (v: boolean) => (this.invalid = v);
+  get usage() {
+    let bits = ['@options={{this.grades}}'];
+    if (this.value) bits.push(`@value='${this.value}'`);
+    if (this.placeholder) bits.push(`@placeholder='${this.placeholder}'`);
+    if (this.size !== 'm') bits.push(`@size='${this.size}'`);
+    if (this.disabled) bits.push('@disabled={{true}}');
+    if (this.required) bits.push('@required={{true}}');
+    if (this.invalid) bits.push('@invalid={{true}}');
+    bits.push('@onChange={{this.setValue}}');
+    return `<NativeSelect ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='NativeSelect'
+      @description='A styled closed face over a real <select>: the platform draws the open list, so a phone gets its own picker and the control posts in a form without a script. Reach for Select when the list needs typeahead, sections or rich items.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <NativeSelect
+          @label='Leaf grade'
+          @options={{this.gradeOptions}}
+          @value={{this.value}}
+          @placeholder={{this.placeholder}}
+          @size={{this.sizeArg}}
+          @disabled={{this.disabled}}
+          @required={{this.required}}
+          @invalid={{this.invalid}}
+          @onChange={{this.setValue}}
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='options'
+          @description='{value, label} pairs. @items is accepted as an alias; a default block of hand-written <option> / <optgroup> replaces both.'
+          @value={{this.gradeOptions}}
+        />
+        <Args.String
+          @name='value'
+          @value={{this.value}}
+          @options={{this.gradeNames}}
+          @description='Controlled value. Omit it and seed with @defaultValue for the uncontrolled half.'
+          @onInput={{this.setValue}}
+        />
+        <Args.Action
+          @name='onChange'
+          @description="Receives the chosen option's value as a string. @onValueChange is the same callback under the React Aria name."
+        />
+        <Args.String
+          @name='placeholder'
+          @value={{this.placeholder}}
+          @description='Rendered as a disabled first option, selected while nothing is chosen.'
+          @onInput={{this.setPlaceholder}}
+        />
+        <Args.String
+          @name='size'
+          @value={{this.size}}
+          @options={{this.sizes}}
+          @defaultValue='m'
+          @onInput={{this.setSize}}
+        />
+        <Args.Bool @name='disabled' @defaultValue={{false}} @value={{this.disabled}} @onInput={{this.setDisabled}} />
+        <Args.Bool @name='required' @defaultValue={{false}} @value={{this.required}} @onInput={{this.setRequired}} />
+        <Args.Bool
+          @name='invalid'
+          @defaultValue={{false}}
+          @value={{this.invalid}}
+          @description='Paints the destructive hairline and sets aria-invalid on the select.'
+          @onInput={{this.setInvalid}}
+        />
+        <Args.String @name='label' @value='Leaf grade' @description='Accessible name when no <label for> points at the select.' />
+        <Args.String @name='controlId' @description='The id a <label for> points at.' />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_NATIVE_SELECT: Record<string, unknown> = {
+  NativeSelect: NativeSelectUsage,
+};