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

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

@@ -0,0 +1,61 @@
+## What it is
+
+**Pick one path through a hierarchy as one value**: Continent / Country / City, Category / Subcategory, Department / Team. The value is the path of keys, such as `['africa', 'ethiopia', 'guji']`, and the field shows it as "Africa / Ethiopia / Guji".
+
+Reach for a neighbour when the job is different:
+
+- **Tree** browses a hierarchy without holding a value.
+- **TreeSelect** collects a set of checked nodes.
+- **Select** is one flat list.
+
+## The contract
+
+```
+@options ({ value, label, children?, disabled? }[])
+@value?, @defaultValue?, @onChange? (path, labels)
+@changeOnSelect?, @label?, @placeholder?, @separator? (default ' / '), @disabled?
+Element: HTMLDivElement
+```
+
+**One column per level.** The trigger opens a popup with the top level in the first column. Choosing a branch opens its children in the next column, and so on down. Choosing a leaf commits the whole path, closes the popup and returns focus to the trigger.
+
+**`@changeOnSelect`** also commits a path that ends on a branch, such as "Africa / Ethiopia", and keeps the popup open for going deeper.
+
+**Opening lands on the value.** The committed path is expanded, with focus on its deepest option, so changing the city means one move rather than three.
+
+`@onChange` receives both the path of values and the matching labels. Disabled options are shown, marked and skipped.
+
+## Prior art
+
+**Ant `Cascader`** takes `options`, `value`, `onChange`, `changeOnSelect`, `expandTrigger` (`click | hover`), `showSearch`, `multiple` and `displayRender`. **Mantine** and **Element Plus** follow the same model.
+
+Where Pretui is better: **the keyboard follows the columns** and is fully specified (see Accessibility). Ant's keyboard support is partial and its columns have no listbox semantics. **Focus returns to the trigger** on commit and Escape.
+
+Where it is thinner: **no search** across the hierarchy, **no multiple mode** (use **TreeSelect**), **no hover expansion**, which is deliberate: it opens columns under a passing pointer. There is **no custom display render** beyond `@separator`, and **no lazy loading** of children.
+
+## Accessibility
+
+No single APG pattern. It is a trigger button plus a row of listboxes.
+
+- **The trigger** is a `<button>` with `aria-haspopup="listbox"`, `aria-expanded`, and `aria-controls` while open. It is named "{label}: {path}", so the committed value is heard. The tests assert all of these.
+- **Each column is `role="listbox"`**, and each option is a `role="option"` with `aria-selected` on the active one, `aria-disabled` on disabled ones. The first column is named by `@label`, and each deeper column by its parent option ("Asia"), so the columns are told apart. The tests assert the names.
+- **Keyboard.** ArrowUp and ArrowDown move within a column, wrapping and skipping disabled options. ArrowRight, Enter or Space on a branch goes into it, and commits nothing unless `@changeOnSelect`. ArrowLeft goes back out. Enter or Space on a leaf commits. Escape closes. Tab closes and moves on. The tests press each of these keys.
+- **Focus.** Options use a roving `tabindex`. Focus lands on the committed path when the popup opens, or on the part of it that still exists if the options changed, and returns to the trigger on commit or Escape. The tests assert all three.
+
+## Theming
+
+`--input-background`, `--input`, `--ring`, `--radius-control`, `--pretui-control-h`, `--foreground`, `--muted-foreground`, `--primary` (the active option), `--popover`, `--popover-foreground`, `--pretui-shadow-raised`, `--radius-surface`, `--border` (the rule between columns), `--hover`, `--pretui-z-dropdown`, `--font-sans`, `--text-ui-md`, `--space-2` and `--space-3`.
+
+Each column is at least 10rem wide and at most 16rem tall. The popup scrolls sideways when the path is deeper than the space available.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+| Agent types                             | Give them                              |
+| --------------------------------------- | -------------------------------------- |
+| Ant `<Cascader options value onChange>` | `<Cascader @options @value @onChange>` |
+| Ant `changeOnSelect`                    | `@changeOnSelect`                      |
+| Ant `displayRender`                     | `@separator`                           |
+| Ant `showSearch`                        | not supported                          |
+| Ant `multiple`                          | **TreeSelect**                         |

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

@@ -0,0 +1,79 @@
+// Pretui — Cascader usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Cascader } from './cascader';
+import type { CascaderOption } from './cascader';
+
+const ORIGINS: CascaderOption[] = [
+  {
+    value: 'americas',
+    label: 'Americas',
+    children: [
+      { value: 'colombia', label: 'Colombia', children: [{ value: 'huila', label: 'Huila' }, { value: 'narino', label: 'Nariño' }] },
+      { value: 'guatemala', label: 'Guatemala', children: [{ value: 'antigua', label: 'Antigua' }] },
+    ],
+  },
+  {
+    value: 'africa',
+    label: 'Africa',
+    children: [
+      { value: 'ethiopia', label: 'Ethiopia', children: [{ value: 'yirgacheffe', label: 'Yirgacheffe' }, { value: 'guji', label: 'Guji' }] },
+      { value: 'kenya', label: 'Kenya', children: [{ value: 'nyeri', label: 'Nyeri' }] },
+    ],
+  },
+  { value: 'asia', label: 'Asia', children: [{ value: 'yunnan', label: 'Yunnan' }] },
+];
+
+export class CascaderUsage extends Component {
+  origins = ORIGINS;
+  @tracked path: string[] = ['africa', 'ethiopia', 'guji'];
+  @tracked changeOnSelect = false;
+  setPath = (v: string[]) => (this.path = v);
+  setChangeOnSelect = (v: boolean) => (this.changeOnSelect = v);
+  get usage() {
+    let bits = ['@options={{this.origins}}', '@value={{this.path}}', '@onChange={{this.setPath}}', "@label='Origin'"];
+    if (this.changeOnSelect) bits.push('@changeOnSelect={{true}}');
+    return `<Cascader ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Cascader'
+      @description='Pick one path through a hierarchy as one value, shown as Africa / Ethiopia / Guji. The popup is a column per level; arrows walk within a column, Right or Enter goes into a branch, Left comes back, Enter on a leaf commits. Tree browses without a value; TreeSelect collects a checked set.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='cs-demo'>
+          <Cascader @options={{this.origins}} @value={{this.path}} @onChange={{this.setPath}} @changeOnSelect={{this.changeOnSelect}} @label='Origin' @placeholder='Choose an origin' />
+          <p class='cs-demo-value'>Value: <code>{{#each this.path as |v|}}{{v}} {{/each}}</code></p>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Object @name='options' @required={{true}} @description='{ value, label, children?, disabled? }[]' />
+        <Args.Object @name='value' @description='The path of values, root first. defaultValue seeds the uncontrolled form.' />
+        <Args.Action @name='onChange' @description='The committed path and its labels.' />
+        <Args.Bool @name='changeOnSelect' @value={{this.changeOnSelect}} @defaultValue={{false}} @onInput={{this.setChangeOnSelect}} @description='Commit a path that ends on a branch too.' />
+        <Args.String @name='label' />
+        <Args.String @name='placeholder' />
+        <Args.String @name='separator' @defaultValue=' / ' />
+        <Args.Bool @name='disabled' @defaultValue={{false}} />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .cs-demo {
+        display: grid;
+        gap: var(--space-2, 0.375rem);
+        padding-block-end: 16rem;
+      }
+      .cs-demo-value {
+        margin: 0;
+        font-size: var(--text-ui-sm, 0.72rem);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_CASCADER: Record<string, unknown> = {
+  Cascader: CascaderUsage,
+};

package/bundled-realms/pretui/components/channel-slider.gts

@@ -0,0 +1,251 @@
+// Pretui — ChannelSlider: a slider for one colour channel, with a sentence for its value.
+import Component from '@glimmer/component';
+import { on } from '@ember/modifier';
+import { cssStyleFrom, cssValue } from '../pretui-css';
+import { alphaTrackCss, channelTrackCss, clamp, stepFor } from '../color-engine';
+import type { ColorValue, GamutId } from '../color-engine';
+
+// ── ChannelSlider ────────────────────────────────────────────────────────
+
+/**
+ * One channel on a track that shows what the channel does.
+ *
+ * Built on a real `<input type="range">` rather than a div with a thumb,
+ * which is the decision that buys the whole accessibility floor from the
+ * platform: `role="slider"`, `aria-valuenow`/`min`/`max`, Home/End,
+ * PageUp/PageDown, touch, high-contrast mode, and RTL. What is layered on
+ * top is only what the platform lacks:
+ *
+ *  * **Shift = ×10, Alt = ÷10** on the arrow keys (upstream has these on its
+ *    number fields but not its sliders; figui3 has Shift only).
+ *  * **Hue channels WRAP.** Arrowing up from 359° lands on 0°, not on a dead
+ *    stop — a hue slider that clamps is a hue slider with a seam in it.
+ *    (Upstream's own hue range maxes at 359 and clamps; only its number field
+ *    wraps.)
+ *  * A track gradient built from REAL conversions of the current colour, so
+ *    an OKLCH chroma track shows where the colour leaves the gamut instead of
+ *    a plausible-looking fake.
+ */
+export interface ChannelSliderSignature {
+  Args: {
+    label: string;
+    /** Spoken text — a sentence, not a number. */
+    valueText: string;
+    value: number;
+    min: number;
+    max: number;
+    step: number;
+    /** Whether the value wraps at the ends. */
+    wrap?: boolean;
+    /** How to paint the track. See `ChannelTrack` — a typed spec, not a CSS
+     *  string. */
+    track: ChannelTrack;
+    /** Show the alpha checkerboard behind the track. */
+    checker?: boolean;
+    disabled?: boolean;
+    onInput: (value: number) => void;
+    /** Called once when a gesture ends — where announcements belong. */
+    onCommit?: () => void;
+  };
+  Element: HTMLDivElement;
+}
+
+/**
+ * How a slider paints its track.
+ *
+ * It is not a raw CSS string: that would make `@track` a caller-supplied
+ * value interpolated straight into an inline style — the sharpest hazard in
+ * the whole colour surface, since a slider track is a `background` and a
+ * `background` is where `url(…)` wants to live.
+ *
+ * A guard on the string would have been the obvious fix and is the weaker
+ * one. **The value is typed instead, so on the two paths every real caller
+ * uses there is no caller text at all** — the component hands numbers to the
+ * engine and the engine constructs the gradient. That is the same
+ * parse-and-reserialize principle the colour values follow, applied to a
+ * whole declaration: emit a canonical string we built, never the caller's.
+ *
+ * `custom` remains for a caller who genuinely needs their own ramp, and it
+ * is the only branch that touches caller text — so it is the only one that
+ * needs `cssValue`, and a value that fails validation is DROPPED whole (the
+ * stylesheet's own fallback paints instead), never stripped and used.
+ */
+export type ChannelTrack =
+  /** One channel of `color` swept across its range, gamut-clamped. */
+  | {
+      kind: 'channel';
+      color: ColorValue;
+      index: number;
+      gamut: GamutId;
+      /** Sample count. More is smoother and longer. */
+      steps?: number;
+    }
+  /** `color` fading from transparent to opaque, over the checkerboard. */
+  | { kind: 'alpha'; color: ColorValue; gamut: GamutId }
+  /** A caller's own CSS. Validated by the shared allowlist; dropped if it
+   *  fails. NOTE: the allowlist does not currently admit the gradient
+   *  functions, so a custom gradient is rejected today — see the report. */
+  | { kind: 'custom'; css: string };
+
+export class ChannelSlider extends Component<ChannelSliderSignature> {
+  /** The track's CSS. Engine-constructed on the `channel` and `alpha`
+   *  branches; guarded by the shared allowlist on `custom`. */
+  get trackCss(): string | undefined {
+    let track = this.args.track;
+    if (track.kind === 'channel') {
+      return channelTrackCss(
+        track.color,
+        track.index,
+        track.gamut,
+        track.steps,
+      );
+    }
+    if (track.kind === 'alpha') {
+      return alphaTrackCss(track.color, track.gamut);
+    }
+    return cssValue(track.css);
+  }
+
+  get trackStyle() {
+    // `channel` and `alpha` are engine output — numbers and closed-enum
+    // keywords concatenated by `color-engine.ts`, with every embedded colour
+    // already through `cssFor`. `custom` has been through `cssValue` above.
+    return cssStyleFrom(['--pretui-slider-track: ' + (this.trackCss ?? 'none')]);
+  }
+
+  handleInput = (event: Event) => {
+    let input = event.target as HTMLInputElement;
+    this.args.onInput(Number(input.value));
+  };
+
+  handleChange = () => {
+    this.args.onCommit?.();
+  };
+
+  handleKey = (rawEvent: Event) => {
+    let event = rawEvent as KeyboardEvent;
+    let direction =
+      event.key === 'ArrowRight' || event.key === 'ArrowUp'
+        ? 1
+        : event.key === 'ArrowLeft' || event.key === 'ArrowDown'
+          ? -1
+          : 0;
+    if (direction === 0) {
+      return;
+    }
+    let modified = event.shiftKey || event.altKey;
+    // Plain arrows on a non-wrapping channel are already correct natively —
+    // intercepting them would only risk diverging from the platform.
+    if (!modified && !this.args.wrap) {
+      return;
+    }
+    event.preventDefault();
+    let step = stepFor(
+      { step: this.args.step } as never,
+      { shiftKey: event.shiftKey, altKey: event.altKey },
+    );
+    let next = this.args.value + direction * step;
+    let span = this.args.max - this.args.min;
+    if (this.args.wrap && span > 0) {
+      let offset = (next - this.args.min) % span;
+      next = this.args.min + (offset < 0 ? offset + span : offset);
+    } else {
+      next = clamp(next, this.args.min, this.args.max);
+    }
+    this.args.onInput(next);
+    this.args.onCommit?.();
+  };
+
+  <template>
+    <div
+      class='pretui-chslider'
+      data-checker={{if @checker 'true'}}
+      style={{this.trackStyle}}
+      data-test-pretui-channel-slider={{@label}}
+      ...attributes
+    >
+      <input
+        type='range'
+        class='pretui-chslider-input'
+        aria-label={{@label}}
+        aria-valuetext={{@valueText}}
+        min={{@min}}
+        max={{@max}}
+        step={{@step}}
+        value={{@value}}
+        disabled={{@disabled}}
+        {{on 'input' this.handleInput}}
+        {{on 'change' this.handleChange}}
+        {{on 'keydown' this.handleKey}}
+      />
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-chslider {
+          position: relative;
+          height: var(--pretui-slider-h, 16px);
+          border-radius: 999px;
+          background-image: var(--pretui-slider-track, none);
+          box-shadow: inset 0 0 0 1px
+            color-mix(in oklch, var(--foreground) 16%, transparent);
+          /* keep the drag from scrolling the page under it */
+          touch-action: none;
+        }
+        .pretui-chslider[data-checker='true'] {
+          background-image: var(--pretui-slider-track, none),
+            var(
+              --pretui-checker,
+              repeating-conic-gradient(
+                color-mix(in oklch, var(--foreground) 11%, transparent) 0 25%,
+                transparent 0 50%
+              )
+            );
+          background-size: auto, 8px 8px;
+        }
+        .pretui-chslider-input {
+          appearance: none;
+          -webkit-appearance: none;
+          width: 100%;
+          height: 100%;
+          margin: 0;
+          background: transparent;
+          cursor: pointer;
+          display: block;
+          touch-action: none;
+        }
+        .pretui-chslider-input:disabled {
+          cursor: not-allowed;
+        }
+        .pretui-chslider-input::-webkit-slider-thumb {
+          appearance: none;
+          -webkit-appearance: none;
+          width: var(--pretui-slider-thumb, 14px);
+          height: var(--pretui-slider-thumb, 14px);
+          border-radius: 50%;
+          background: transparent;
+          box-shadow:
+            0 0 0 2px #fff,
+            0 0 0 3.5px rgb(0 0 0 / 0.45);
+        }
+        .pretui-chslider-input::-moz-range-thumb {
+          width: var(--pretui-slider-thumb, 14px);
+          height: var(--pretui-slider-thumb, 14px);
+          border: 0;
+          border-radius: 50%;
+          background: transparent;
+          box-shadow:
+            0 0 0 2px #fff,
+            0 0 0 3.5px rgb(0 0 0 / 0.45);
+        }
+        .pretui-chslider-input:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 2px;
+          border-radius: 999px;
+        }
+        .pretui-chslider:has(.pretui-chslider-input:disabled) {
+          opacity: 0.5;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/channel-slider.md

@@ -0,0 +1,51 @@
+## What it is
+
+One colour channel as a slider, with a live gradient track showing what moving it will do.
+
+It is a building block of **ColorPicker** rather than a standalone control — reach for it when composing a colour tool, not when asking for a colour.
+
+## The contract
+
+```
+@label (required)     — the channel's name
+@valueText (required) — spoken text: a SENTENCE, not a number
+@value, @min, @max, @step (all required)
+@wrap?     — whether the value wraps at the ends
+@track (required) — how to paint the track; a typed ChannelTrack spec, not a CSS string
+@checker?  — show the alpha checkerboard behind the track
+@disabled?
+@onInput (required) — fires as the value moves
+@onCommit? — called once when a gesture ends — where announcements belong
+```
+
+**`@track` is a typed spec rather than a CSS gradient string.** The caller describes the channel; the component builds the paint. A CSS string here would be caller text reaching a style attribute, and it would also put the gradient maths in every call site.
+
+**`@valueText` is required and must be a sentence.** A hue slider announcing "212" is technically correct and useless; "hue 212 degrees, cyan" is what a listener can act on.
+
+**`@wrap` exists because hue is circular** and the other channels are not — a hue slider that stops at 360 instead of rolling to 0 is wrong in a way a generic slider cannot know.
+
+**`@onInput` and `@onCommit` are separate for a reason**: input fires continuously through a drag, commit fires once at the end, and an announcement belongs on the commit or it fires hundreds of times.
+
+## Prior art
+
+**hdr-color-input.**
+
+Where Pretui is better: the typed track spec, and the separation of continuous input from gesture commit. Most channel sliders take a gradient string and fire one event, which leaves the caller either announcing on every pixel or not announcing at all.
+
+Where it is thinner: no two-thumb range, no logarithmic channels, and no per-channel gamut warning — that lives on **ColorPicker**, which owns the whole colour.
+
+## Accessibility
+
+- **A real slider with a name and a value text.** The name is the channel; the value text is the sentence.
+- **`@onCommit` is where announcements belong**, and calling it out in the contract is the component telling the caller where to put them.
+- **The checkerboard is presentation** — it makes alpha legible for sighted readers, and the value text carries alpha for everyone else.
+- **`@wrap` changes keyboard behaviour at the ends**, so arrowing past the end of a hue channel continues rather than stopping, which is what the underlying value actually does.
+- **`@disabled` inerts the control** while leaving it announced.
+
+## Theming
+
+`--pretui-slider-track`, `--pretui-slider-thumb` and `--pretui-slider-h` — shared with every other slider-shaped control in the colour module — plus `--pretui-checker` for the alpha ground.
+
+Sharing the three slider tokens across **ChannelSlider**, the sliders inside **ColorPicker** and **GradientEditor**'s stop controls is what keeps a colour tool reading as one instrument rather than as three widgets that happen to be adjacent.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/channel-slider.usage.gts

@@ -0,0 +1,104 @@
+// Pretui — ChannelSlider usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { parseColor } from '../color-engine';
+import type { ColorValue } from '../color-engine';
+import { ChannelSlider } from './channel-slider';
+import type { ChannelTrack } from './channel-slider';
+import { FreestyleUsage } from './freestyle-usage';
+
+// ── ChannelSlider ────────────────────────────────────────────────────────
+class ChannelSliderUsage extends Component {
+  @tracked color: ColorValue = parseColor('oklch(0.7 0.16 210)')!;
+  @tracked hue = 210;
+  setHue = (v: number) => {
+    this.hue = v;
+    this.color = { ...this.color, coords: [0.7, 0.16, v] };
+  };
+  get track(): ChannelTrack {
+    // A typed spec, not a CSS string — the engine builds the gradient, so
+    // there is no caller text on this path at all.
+    return { kind: 'channel', color: this.color, index: 2, gamut: 'srgb', steps: 32 };
+  }
+  get valueText() {
+    return `Hue ${Math.round(this.hue)} degrees`;
+  }
+  get trackKind() {
+    return this.track.kind;
+  }
+  get usage() {
+    return "<ChannelSlider @label='Hue' @valueText={{this.text}} @value={{this.hue}} @min={{0}} @max={{360}} @step={{1}} @wrap={{true}} @track={{this.track}} @onInput={{this.setHue}} />";
+  }
+  <template>
+    <FreestyleUsage
+      @name='ChannelSlider'
+      @description="One channel on a track built from real conversions of the current colour. It is a native <input type='range'>, so Home/End, PageUp/PageDown, touch and RTL arrive from the platform; Shift (×10), Alt (÷10) and hue WRAPPING are layered on. Focus it and hold Shift while arrowing."
+      @source={{this.usage}}
+    >
+      <:example>
+        <ChannelSlider
+          @label='Hue'
+          @valueText={{this.valueText}}
+          @value={{this.hue}}
+          @min={{0}}
+          @max={{360}}
+          @step={{1}}
+          @wrap={{true}}
+          @track={{this.track}}
+          @onInput={{this.setHue}}
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='label'
+          @required={{true}}
+          @description='Accessible name for the slider.'
+          @value='Hue'
+        />
+        <Args.String
+          @name='valueText'
+          @required={{true}}
+          @description="Spoken value — a sentence ('Lightness 62%'), never a bare number."
+          @value={{this.valueText}}
+        />
+        <Args.Number
+          @name='value'
+          @required={{true}}
+          @value={{this.hue}}
+          @description='Current value in display units.'
+          @onInput={{this.setHue}}
+        />
+        <Args.Bool
+          @name='wrap'
+          @defaultValue={{false}}
+          @description='Hue channels wrap at the ends instead of dead-ending at 0/360.'
+          @value={{true}}
+        />
+        <Args.Bool
+          @name='checker'
+          @defaultValue={{false}}
+          @description='Show the alpha checkerboard behind the track.'
+          @value={{false}}
+        />
+        <Args.String
+          @name='track'
+          @required={{true}}
+          @description="A TYPED spec — { kind: 'channel' | 'alpha' | 'custom' }. The two real paths carry no caller text at all; only 'custom' does, and it goes through the shared allowlist."
+          @value={{this.trackKind}}
+        />
+        <Args.Action
+          @name='onInput'
+          @description='Receives the new value on every change.'
+        />
+        <Args.Action
+          @name='onCommit'
+          @description='Fires once when a gesture ends. Announcements belong here, not on onInput — a live region that fires per drag frame is unusable.'
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_CHANNEL_SLIDER: Record<string, unknown> = {
+  ChannelSlider: ChannelSliderUsage,
+};