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

package/bundled-realms/pretui/components/color-picker.md

@@ -0,0 +1,59 @@
+## What it is
+
+A colour picker built around a real colour engine: a gradient area, per-channel sliders, a text readout, and a gamut check that can tell you a colour is **not showable** and what the nearest one is.
+
+That last part is what separates it from every picker that just gives you a swatch. Use it wherever a colour is being chosen rather than merely displayed — for display alone, **Swatch** or **SwatchChip**.
+
+## The contract
+
+```
+@value?, @defaultValue?  — controlled / uncontrolled; any CSS colour string
+@space?, @defaultSpace?  — the channel model shown: srgb | p3 | rec2020 |
+                           oklch | oklab | hsl | hsv
+@gamut?                  — the gamut colours are checked and clamped against. Default sRGB
+@format?                 — emitted string shape: 'auto' (hex for RGB-ish models,
+                           the space's own CSS function otherwise) | 'hex' | 'css'
+@noAlpha?                — hide the alpha slider and drop alpha from the value
+@lockSpace?              — hide the space switcher, locking the model to @space
+@lockGamut?              — hide the gamut switcher; the gamut READOUT always stays
+@resolution?             — area paint resolution
+@disabled?
+@onValueChange?, @onSpaceChange?
+```
+
+**Space and gamut are different things, and keeping them apart is the design.** OKLCH is a _space_; sRGB is also a _gamut_. Conflating the two is why most pickers cannot tell you that a colour is unshowable — they only ever work in coordinates the display can render, so the question never arises.
+
+**`@lockGamut` hides the switcher but never the readout.** You can stop someone changing the target gamut; you cannot stop them being told their colour falls outside it.
+
+**Out-of-gamut is reported in full**: which gamut it is outside, the nearest showable colour as hex, and the ΔE distance to it — plus a control to take that nearest colour.
+
+**`@format='auto'` emits hex for the RGB-ish models and the space's own CSS function otherwise**, so an OKLCH selection round-trips as `oklch(...)` rather than being flattened to hex on the way out.
+
+## Prior art
+
+**`wa-color-picker`**, and boxel-ui's own ColorPicker.
+
+Where Pretui is better: **the gamut model.** Neither upstream has one. A colour picked in OKLCH can be outside sRGB — perfectly valid, and invisible on most displays — and a picker that silently clamps it has lied about what was chosen. This one names the condition, quantifies it with ΔE, and offers the correction rather than applying it.
+
+Seven spaces including two perceptual ones is also well beyond either upstream's RGB/HSL pair.
+
+Where it is thinner: no palette or recent-colours memory, no eyedropper on browsers without the API, no contrast checking against a second colour — which is the obvious next thing for a design-system picker — and no named-colour input beyond what the engine parses.
+
+**The catalog row and spec disagree with this file.** Both describe the component as _"Wrapped boxel-ui ColorPicker: native input + hex · runtime reuse"_, with `buildsOn: boxel-ui ColorPicker`. Nothing here wraps boxel-ui's picker: the colour engine, the gamut model and the seven channel models are this component's own, so the row and the spec want correcting.
+
+## Accessibility
+
+- **The text readout is a labelled input** with `aria-invalid` reflecting whether the typed value parses, and a visible "Not a colour" message beside it — so a bad paste is reported rather than silently ignored.
+- **The tools are named buttons** — "Pick a colour from the screen", "Copy colour value" — rather than icon-only controls with no accessible name.
+- **The preview chip and the gamut swatch are `aria-hidden`.** Both restate a value that is already text beside them.
+- **Out-of-gamut is text, not a colour cue.** The warning names the gamut, the nearest hex and the ΔE, so the condition is perceivable without seeing the difference — which is the point, since by definition the display cannot show it.
+- **The area is a two-dimensional control**, and it is the part to check most carefully in any picker: a gradient surface that is pointer-only excludes keyboard users from the primary interaction.
+- **Colour cannot be the only channel here**, by the nature of the component — which is why the readout carries the value as text at all times.
+
+## Theming
+
+`--pretui-picker-width`, `--pretui-picker-preview` (the readout's current colour), `--pretui-picker-clamped` (the nearest-showable colour in the gamut warning), plus the control tokens it reaches through its parts: `--pretui-slider-track`, `--pretui-slider-thumb`, `--pretui-slider-h` for the channel sliders (defined in `channel-slider.gts`), `--pretui-area-x` / `--pretui-area-y` / `--pretui-area-thumb-size` / `--pretui-area-thumb-color` / `--pretui-area-thumb-ink` / `--pretui-area-ratio` for the gradient area (defined in `color-area.gts`), `--pretui-swatch-color` and `--pretui-checker` for the previews, and `--pretui-destructive-ink` for the invalid state.
+
+Sharing the slider and area tokens with **ChannelSlider**, **ColorArea** and **GradientEditor** is what keeps the color tools reading as one family: a theme that retunes a thumb retunes every color control at once, rather than leaving the picker and the gradient editor visibly different.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/color-picker.usage.gts

@@ -0,0 +1,122 @@
+// Pretui — ColorPicker usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import type { GamutId, SpaceId } from '../color-engine';
+import { ColorPicker } from './color-picker';
+import type { ColorFormat } from './color-picker';
+import { FreestyleUsage } from './freestyle-usage';
+import { GAMUT_NAMES } from '../internal/color-fixtures';
+
+const SPACE_NAMES = ['srgb', 'hsl', 'hsv', 'oklch', 'oklab', 'p3', 'rec2020'];
+const FORMAT_NAMES = ['auto', 'hex', 'css'];
+
+// ── ColorPicker ──────────────────────────────────────────────────────────
+class ColorPickerUsage extends Component {
+  @tracked value = 'oklch(0.72 0.31 25)';
+  @tracked space = 'oklch';
+  @tracked gamut = 'srgb';
+  @tracked format = 'auto';
+  @tracked noAlpha = false;
+  @tracked lockSpace = false;
+  spaces = SPACE_NAMES;
+  gamuts = GAMUT_NAMES;
+  formats = FORMAT_NAMES;
+  setValue = (v: string) => (this.value = v);
+  setSpace = (v: string) => (this.space = v);
+  setGamut = (v: string) => (this.gamut = v);
+  setFormat = (v: string) => (this.format = v);
+  setNoAlpha = (v: boolean) => (this.noAlpha = v);
+  setLockSpace = (v: boolean) => (this.lockSpace = v);
+  get spaceId(): SpaceId {
+    return this.space as SpaceId;
+  }
+  get gamutId(): GamutId {
+    return this.gamut as GamutId;
+  }
+  get formatValue(): ColorFormat {
+    return this.format as ColorFormat;
+  }
+  get usage() {
+    return '<ColorPicker @value={{this.value}} @space="oklch" @gamut="srgb" @onValueChange={{this.setValue}} />';
+  }
+  <template>
+    <FreestyleUsage
+      @name='ColorPicker'
+      @description="The full picker: area, hue and opacity sliders, per-channel numbers, hex/CSS entry, eyedropper where the browser has one, copy, and space + gamut switching across sRGB / HSL / HSV / OKLCH / OKLab / Display P3 / Rec. 2020. The starting value is deliberately outside sRGB so the gamut report is visible on load — most pickers would clamp it silently and never mention it."
+      @source={{this.usage}}
+    >
+      <:example>
+        <ColorPicker
+          @value={{this.value}}
+          @space={{this.spaceId}}
+          @gamut={{this.gamutId}}
+          @format={{this.formatValue}}
+          @noAlpha={{this.noAlpha}}
+          @lockSpace={{this.lockSpace}}
+          @onValueChange={{this.setValue}}
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='value'
+          @description='Any CSS colour string. Unparseable input is refused on commit rather than silently discarded.'
+          @value={{this.value}}
+          @onInput={{this.setValue}}
+        />
+        <Args.String
+          @name='space'
+          @defaultValue='oklch'
+          @options={{this.spaces}}
+          @description='The channel model. Switching it re-expresses the SAME colour — it never changes what is selected, only the coordinates.'
+          @value={{this.space}}
+          @onInput={{this.setSpace}}
+        />
+        <Args.String
+          @name='gamut'
+          @defaultValue='srgb'
+          @options={{this.gamuts}}
+          @description='What "showable" means. Distinct from the space: OKLCH is a space, sRGB is also a gamut, and conflating them is why most pickers cannot tell you a colour is unshowable.'
+          @value={{this.gamut}}
+          @onInput={{this.setGamut}}
+        />
+        <Args.String
+          @name='format'
+          @defaultValue='auto'
+          @options={{this.formats}}
+          @description='Emitted shape. auto gives hex for the sRGB-bounded models and the space CSS function otherwise.'
+          @value={{this.format}}
+          @onInput={{this.setFormat}}
+        />
+        <Args.Bool
+          @name='noAlpha'
+          @defaultValue={{false}}
+          @description='Hide the opacity slider and drop alpha from the emitted value.'
+          @value={{this.noAlpha}}
+          @onInput={{this.setNoAlpha}}
+        />
+        <Args.Bool
+          @name='lockSpace'
+          @defaultValue={{false}}
+          @description='Hide the space switcher. The gamut READOUT always stays — clamping is never silent.'
+          @value={{this.lockSpace}}
+          @onInput={{this.setLockSpace}}
+        />
+        <Args.Action
+          @name='onValueChange'
+          @description='Receives the formatted colour string.'
+        />
+      </:api>
+      <:description>
+        <p>Every colour string is parsed and re-serialized before it reaches an
+          inline style, so a
+          <code>@value</code>
+          carrying extra declarations becomes
+          <code>transparent</code>, not an injection.</p>
+      </:description>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_COLOR_PICKER: Record<string, unknown> = {
+  ColorPicker: ColorPickerUsage,
+};

package/bundled-realms/pretui/components/color-stop-editor.gts

@@ -0,0 +1,184 @@
+// Pretui — ColorStopEditor: the editor for one gradient stop.
+import Component from '@glimmer/component';
+import { on } from '@ember/modifier';
+import { Button } from './button';
+import { ScrubInput } from './scrub-input';
+import { Popover } from './popover';
+import { describeColor, parseColor, round, toHex } from '../color-engine';
+import type { ColorValue, GradientStop } from '../color-engine';
+import { ColorPicker } from './color-picker';
+import { SwatchChip } from './swatch-chip';
+
+// ── ColorStopEditor ──────────────────────────────────────────────────────
+
+/**
+ * One row of the stop list: the swatch that opens a picker, the position,
+ * and remove.
+ *
+ * This is the component the design-tools port's `GradientInput` should reuse
+ * when it needs "let the user change this stop's colour" — it is the whole
+ * of the colour half of a stop, and it holds no geometry beyond the position
+ * number it is handed.
+ */
+export interface ColorStopEditorSignature {
+  Args: {
+    stop: GradientStop;
+    selected?: boolean;
+    disabled?: boolean;
+    removable?: boolean;
+    onSelect?: (id: string) => void;
+    onColorChange: (id: string, color: string) => void;
+    onPositionChange: (id: string, position: number | null) => void;
+    onRemove?: (id: string) => void;
+  };
+  Element: HTMLDivElement;
+}
+
+export class ColorStopEditor extends Component<ColorStopEditorSignature> {
+  get parsed(): ColorValue | null {
+    return parseColor(this.args.stop.color);
+  }
+  get hex(): string {
+    let parsed = this.parsed;
+    return parsed ? toHex(parsed) : '';
+  }
+  get triggerLabel(): string {
+    let parsed = this.parsed;
+    return `Stop colour: ${parsed ? describeColor(parsed) : 'none'}`;
+  }
+  get removeLabel(): string {
+    return `Remove stop at ${round(this.args.stop.position, 0)} percent`;
+  }
+  handleColor = (color: string) => {
+    this.args.onColorChange(this.args.stop.id, color);
+  };
+  handlePosition = (value: number | null) => {
+    this.args.onPositionChange(this.args.stop.id, value);
+  };
+  handleSelect = () => {
+    this.args.onSelect?.(this.args.stop.id);
+  };
+  handleRemove = () => {
+    this.args.onRemove?.(this.args.stop.id);
+  };
+  get removeDisabled(): boolean {
+    return Boolean(this.args.disabled) || !this.args.removable;
+  }
+  get removeTitle(): string {
+    return this.args.removable
+      ? this.removeLabel
+      : 'A gradient needs at least two stops';
+  }
+  <template>
+    <div
+      class='pretui-stoprow'
+      data-state={{if @selected 'selected'}}
+      data-test-pretui-color-stop={{@stop.id}}
+      ...attributes
+    >
+      <Popover @placement='right-start' @label='Stop colour'>
+        <:trigger as |open toggle|>
+          <button
+            type='button'
+            class='pretui-stoprow-trigger'
+            aria-expanded={{if open 'true' 'false'}}
+            aria-haspopup='dialog'
+            aria-label={{this.triggerLabel}}
+            disabled={{@disabled}}
+            {{on 'click' toggle}}
+            {{on 'focus' this.handleSelect}}
+          >
+            <SwatchChip
+              @color={{@stop.color}}
+              @shape='square'
+              @size={{16}}
+              aria-hidden='true'
+            />
+            <span class='pretui-stoprow-hex'>{{this.hex}}</span>
+          </button>
+        </:trigger>
+        <:default>
+          <div class='pretui-stoprow-panel'>
+            <ColorPicker
+              @value={{@stop.color}}
+              @format='hex'
+              @onValueChange={{this.handleColor}}
+            />
+          </div>
+        </:default>
+      </Popover>
+
+      <div class='pretui-stoprow-pos'>
+        <ScrubInput
+          @value={{@stop.position}}
+          @min={{0}}
+          @max={{100}}
+          @step={{1}}
+          @precision={{1}}
+          @disabled={{@disabled}}
+          @onInput={{this.handlePosition}}
+        />
+      </div>
+
+      <Button
+        @appearance='plain'
+        @size='xs'
+        @disabled={{this.removeDisabled}}
+        aria-label={{this.removeLabel}}
+        title={{this.removeTitle}}
+        {{on 'click' this.handleRemove}}
+      >✕</Button>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-stoprow {
+          display: flex;
+          align-items: center;
+          gap: var(--space-2, 5px);
+          padding: 2px;
+          border-radius: calc(var(--radius) / 1.6);
+        }
+        .pretui-stoprow[data-state='selected'] {
+          background: color-mix(
+            in oklch,
+            var(--primary) 10%,
+            transparent
+          );
+        }
+        .pretui-stoprow-trigger {
+          display: inline-flex;
+          align-items: center;
+          gap: var(--space-2, 5px);
+          flex: 1 1 auto;
+          min-width: 0;
+          height: var(--control-h, 28px);
+          padding: 0 var(--space-2, 5px);
+          border: 0;
+          border-radius: var(--radius);
+          background: var(--field, var(--boxel-light));
+          box-shadow: 0 0 0 1px var(--input);
+          font: inherit;
+          font-size: var(--text-ui-md, 12.5px);
+          color: var(--foreground);
+          cursor: pointer;
+        }
+        .pretui-stoprow-trigger:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 1px;
+        }
+        .pretui-stoprow-hex {
+          font-family: var(--font-mono);
+          font-variant-numeric: tabular-nums;
+        }
+        .pretui-stoprow-pos {
+          flex: none;
+          width: 72px;
+        }
+        .pretui-stoprow-panel {
+          padding: var(--space-3, 8px);
+          min-width: 264px;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/color-stop-editor.md

@@ -0,0 +1,46 @@
+## What it is
+
+The colour half of one gradient stop: a swatch trigger that opens a picker, a position, and a remove control.
+
+It is **GradientEditor**'s unit. On its own it is the answer to "let someone edit one stop of something".
+
+## The contract
+
+```
+@stop (required)   — the stop being edited
+@selected?         — whether this is the stop currently in focus in its bar
+@disabled?
+@removable?        — whether to offer removal
+@onSelect?         — fires with the stop's id
+@onColorChange (required)    — fires with the id and the new colour
+@onPositionChange (required) — fires with the id and the new position, or null
+@onRemove?         — fires with the id
+```
+
+**Every callback carries the stop's id.** The editor never mutates the stop it was given; a parent holding a list of stops gets told which one changed and applies it. That is what makes the bar's state single-owned.
+
+**`@onPositionChange` can report `null`**, which is how a stop says "no explicit position" rather than defaulting to zero — a distinction CSS itself makes.
+
+**`@removable` gates the remove control.** A gradient needs two stops, so the last two should not offer removal, and that decision belongs to the parent that can count them.
+
+## Prior art
+
+A kit addition — the piece that lets a gradient bar be built from named controls rather than from a canvas of draggable dots.
+
+Where it is thinner: no alpha handle separate from the colour, no per-stop easing hint, and no drag-to-reorder within this component — position changes come through the callback, and ordering is the parent's.
+
+## Accessibility
+
+- **The swatch trigger carries `aria-haspopup='dialog'` and `aria-expanded'`**, with a computed name, so a bar of stops announces as several distinguishable controls rather than as identical swatches.
+- **The remove control is separately named**, including which stop it removes.
+- **The swatch preview inside the trigger is `aria-hidden`** — the colour is in the name.
+- **`@removable` being false removes the control rather than disabling it**, so a reader is not offered an affordance that will refuse.
+- **Selection is reported, not assumed.** `@onSelect` lets a parent move a roving tab stop across a bar of stops, which is the arrangement that keeps a many-stop gradient to one tab stop.
+
+## Theming
+
+`--pretui-stop-color` (the stop's swatch) and `--pretui-stop-x` (its position along the bar), over `--pretui-swatch-size`, `--pretui-checker` and `--pretui-z-raised` for the popover.
+
+Position being a custom property rather than an inline left offset is what lets the bar animate a stop's movement with a transition — the value changes, the paint follows, and no layout code runs.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/color-stop-editor.usage.gts

@@ -0,0 +1,75 @@
+// Pretui — ColorStopEditor usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import type { GradientStop } from '../color-engine';
+import { ColorStopEditor } from './color-stop-editor';
+import { FreestyleUsage } from './freestyle-usage';
+
+// ── ColorStopEditor ──────────────────────────────────────────────────────
+class ColorStopEditorUsage extends Component {
+  @tracked stop: GradientStop = {
+    id: 'demo-stop',
+    position: 40,
+    color: '#7c3aed',
+  };
+  @tracked removable = true;
+  setRemovable = (v: boolean) => (this.removable = v);
+  setColor = (_id: string, color: string) =>
+    (this.stop = { ...this.stop, color });
+  setPosition = (_id: string, position: number | null) => {
+    if (position !== null) {
+      this.stop = { ...this.stop, position };
+    }
+  };
+  noop = () => {
+    // the demo keeps its single stop
+  };
+  get usage() {
+    return '<ColorStopEditor @stop={{this.stop}} @onColorChange={{this.setColor}} @onPositionChange={{this.setPosition}} />';
+  }
+  <template>
+    <FreestyleUsage
+      @name='ColorStopEditor'
+      @description='One row of a gradient stop list — the swatch that opens a picker, the position, and remove. This is the whole of the COLOUR half of a stop, and the component the design-tools GradientInput should reuse when it needs "let the user change this stop’s colour".'
+      @source={{this.usage}}
+    >
+      <:example>
+        <ColorStopEditor
+          @stop={{this.stop}}
+          @selected={{true}}
+          @removable={{this.removable}}
+          @onColorChange={{this.setColor}}
+          @onPositionChange={{this.setPosition}}
+          @onRemove={{this.noop}}
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='stop'
+          @required={{true}}
+          @description='{ id, position, color }. The id is a monotonic counter, never Math.random() — indexing determinism.'
+          @value={{this.stop}}
+        />
+        <Args.Bool
+          @name='removable'
+          @defaultValue={{false}}
+          @description='False disables remove and explains why in the title — a gradient needs two stops.'
+          @value={{this.removable}}
+          @onInput={{this.setRemovable}}
+        />
+        <Args.Action
+          @name='onColorChange'
+          @description='Receives (id, color).'
+        />
+        <Args.Action
+          @name='onPositionChange'
+          @description='Receives (id, position).'
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_COLOR_STOP_EDITOR: Record<string, unknown> = {
+  ColorStopEditor: ColorStopEditorUsage,
+};