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

package/bundled-realms/pretui/components/color-area.gts

@@ -0,0 +1,339 @@
+// Pretui — ColorArea: a two-channel colour plane painted from the colour engine.
+import Component from '@glimmer/component';
+import { modifier } from 'ember-modifier';
+import { on } from '@ember/modifier';
+import { cssDeclaration, cssStyleFrom } from '../pretui-css';
+import { dragsSurface } from '../internal/design-tools';
+import type { SurfaceFrame } from '../internal/design-tools';
+import { areaColorAt, paintArea, areaPosition, channelValueText, clamp, cssFor, inkOn, round, spaceSpec, stepFor, withAlpha } from '../color-engine';
+import type { ColorValue, GamutId } from '../color-engine';
+
+// ── Modifiers ────────────────────────────────────────────────────────────
+
+/**
+ * Paints the area canvas. The engine returns raw RGBA; this puts it on the
+ * canvas at native resolution and lets CSS scale it up smoothly.
+ *
+ * Owning the paint in a modifier is what makes it legal: it re-runs when its
+ * arguments change, never on a loop, and there is nothing to tear down
+ * because nothing outlives the call. Contrast upstream, which posts to a
+ * Worker built from an object URL — a lifetime that must be terminated and a
+ * URL that must be revoked, both of which the realm's no-unowned-timers law
+ * exists to prevent people from forgetting.
+ */
+export const paintsArea = modifier(
+  (
+    element: HTMLCanvasElement,
+    [base, gamut, size]: [ColorValue, GamutId, number],
+  ) => {
+    let context = element.getContext('2d');
+    if (!context) {
+      return;
+    }
+    let paint = paintArea(base, gamut, size);
+    if (element.width !== paint.size) {
+      element.width = paint.size;
+    }
+    if (element.height !== paint.size) {
+      element.height = paint.size;
+    }
+    // `createImageData` + `set` rather than `new ImageData(buffer, …)`: the
+    // constructor overload is typed against a specific ArrayBuffer variance
+    // that a plain Uint8ClampedArray does not satisfy under the realm's TS
+    // lib, and this path allocates the same amount.
+    let image = context.createImageData(paint.size, paint.size);
+    image.data.set(paint.data);
+    context.putImageData(image, 0, 0);
+  },
+);
+
+// ── ColorArea ────────────────────────────────────────────────────────────
+
+/**
+ * The 2D plane. Which two channels it shows depends on the space: saturation
+ * × value for the RGB-ish models, chroma × lightness for OKLCH/P3/Rec.2020,
+ * a × b for OKLab. The third channel is the slider beside it.
+ *
+ * **Accessibility model.** A 2D control cannot be one `role="slider"` — a
+ * single `aria-valuenow` cannot express two axes, which is the flaw in both
+ * sources (upstream sets none at all; figui3 sets `aria-valuenow` to the
+ * vertical axis only and papers over it with `aria-valuetext`). This renders
+ * TWO real range inputs, one per axis, each with its own label and spoken
+ * value. Both are transparent and cover the plane, so either tab stop drives
+ * both axes from the keyboard, and the focus ring is drawn on the thumb.
+ */
+export interface ColorAreaSignature {
+  Args: {
+    color: ColorValue;
+    gamut: GamutId;
+    /** Paint resolution. 96 is ~10ms; 128 is ~36ms and visibly crisper on
+     *  a large picker. */
+    resolution?: number;
+    disabled?: boolean;
+    onChange: (color: ColorValue) => void;
+    onCommit?: () => void;
+  };
+  Element: HTMLDivElement;
+}
+
+export class ColorArea extends Component<ColorAreaSignature> {
+  get spec() {
+    return spaceSpec(this.args.color.space);
+  }
+  get modelSpec() {
+    return spaceSpec(this.spec.area.model);
+  }
+  get xChannel() {
+    return this.modelSpec.channels[this.spec.area.x]!;
+  }
+  get yChannel() {
+    return this.modelSpec.channels[this.spec.area.y]!;
+  }
+  get position() {
+    return areaPosition(this.args.color);
+  }
+  get resolution() {
+    return clamp(this.args.resolution ?? 96, 16, 256);
+  }
+  get thumbStyle() {
+    let point = this.position;
+    return cssStyleFrom([
+      '--pretui-area-x: ' + round(clamp(point.x, 0, 1) * 100, 3) + '%',
+      '--pretui-area-y: ' + round(clamp(point.y, 0, 1) * 100, 3) + '%',
+      cssDeclaration(
+        '--pretui-area-thumb-color',
+        cssFor(withAlpha(this.args.color, 1)),
+      ),
+      // `inkOn` returns the literal 'black' | 'white' — a closed enum, not
+      // caller text — but it costs nothing to send it through the guard too.
+      cssDeclaration('--pretui-area-thumb-ink', inkOn(this.args.color)),
+    ]);
+  }
+  /** Display value on each axis, for the range inputs. */
+  get xValue() {
+    let min = this.xChannel.min;
+    return round(min + (this.xChannel.max - min) * this.position.x, 4);
+  }
+  get yValue() {
+    let min = this.yChannel.min;
+    return round(min + (this.yChannel.max - min) * (1 - this.position.y), 4);
+  }
+  get xValueText() {
+    return channelValueText(this.modelSpec, this.spec.area.x, this.xValue);
+  }
+  get yValueText() {
+    return channelValueText(this.modelSpec, this.spec.area.y, this.yValue);
+  }
+  get groupLabel() {
+    return `${this.xChannel.label} and ${this.yChannel.label}`;
+  }
+
+  private emit(fx: number, fy: number) {
+    this.args.onChange(areaColorAt(this.args.color, fx, fy));
+  }
+
+  /** Pointer handling is `dragsSurface` from the design-tools port — one
+   *  drag primitive for the kit, not a second one here. It gives pointer
+   *  capture (so a drag survives leaving the plane), touch, and the
+   *  press-origin element, all of which a hand-rolled area picker gets
+   *  wrong. */
+  handleDrag = (frame: SurfaceFrame) => {
+    if (this.args.disabled) {
+      return;
+    }
+    this.emit(frame.nx, frame.ny);
+    if (frame.phase === 'end') {
+      this.args.onCommit?.();
+    }
+  };
+
+  handleX = (event: Event) => {
+    let input = event.target as HTMLInputElement;
+    let span = this.xChannel.max - this.xChannel.min;
+    let fx = span === 0 ? 0 : (Number(input.value) - this.xChannel.min) / span;
+    this.emit(fx, this.position.y);
+  };
+
+  handleY = (event: Event) => {
+    let input = event.target as HTMLInputElement;
+    let span = this.yChannel.max - this.yChannel.min;
+    let fy =
+      span === 0 ? 0 : 1 - (Number(input.value) - this.yChannel.min) / span;
+    this.emit(this.position.x, fy);
+  };
+
+  /**
+   * Both inputs get the SAME handler, so whichever axis has focus can drive
+   * either one. Without this, tabbing to the vertical axis and pressing
+   * ArrowLeft would do nothing — a keyboard user would have to know which
+   * invisible input they were on, which is exactly the kind of thing that
+   * makes a "keyboard accessible" widget unusable in practice.
+   */
+  handleKey = (rawEvent: Event) => {
+    let event = rawEvent as KeyboardEvent;
+    let key = event.key;
+    let horizontal = key === 'ArrowLeft' || key === 'ArrowRight';
+    let vertical = key === 'ArrowUp' || key === 'ArrowDown';
+    let corner = key === 'Home' || key === 'End';
+    if (!horizontal && !vertical && !corner) {
+      return;
+    }
+    event.preventDefault();
+    let point = this.position;
+
+    if (corner) {
+      // Home/End move along the axis the focused input owns, which is what
+      // a screen-reader user is told they are on. Neither source implements
+      // Home/End on the area at all.
+      let isY = (event.target as HTMLElement).classList.contains(
+        'pretui-area-axis-y',
+      );
+      if (isY) {
+        this.emit(point.x, key === 'Home' ? 1 : 0);
+      } else {
+        this.emit(key === 'Home' ? 0 : 1, point.y);
+      }
+      this.args.onCommit?.();
+      return;
+    }
+
+    let channel = horizontal ? this.xChannel : this.yChannel;
+    let span = channel.max - channel.min;
+    let step = stepFor(channel, {
+      shiftKey: event.shiftKey,
+      altKey: event.altKey,
+    });
+    let fraction = span === 0 ? 0 : step / span;
+    let direction = key === 'ArrowRight' || key === 'ArrowUp' ? 1 : -1;
+
+    if (horizontal) {
+      this.emit(clamp(point.x + fraction * direction, 0, 1), point.y);
+    } else {
+      // y is inverted: screen-down is channel-down.
+      this.emit(point.x, clamp(point.y - fraction * direction, 0, 1));
+    }
+    this.args.onCommit?.();
+  };
+
+  <template>
+    <div
+      class='pretui-area'
+      role='group'
+      aria-label={{this.groupLabel}}
+      style={{this.thumbStyle}}
+      data-disabled={{if @disabled 'true'}}
+      data-test-pretui-color-area
+      {{dragsSurface this.handleDrag @disabled}}
+      ...attributes
+    >
+      <canvas
+        class='pretui-area-canvas'
+        aria-hidden='true'
+        {{paintsArea @color @gamut this.resolution}}
+      ></canvas>
+      <span class='pretui-area-thumb' aria-hidden='true'></span>
+      <input
+        type='range'
+        class='pretui-area-axis pretui-area-axis-x'
+        aria-label={{this.xChannel.label}}
+        aria-valuetext={{this.xValueText}}
+        min={{this.xChannel.min}}
+        max={{this.xChannel.max}}
+        step={{this.xChannel.step}}
+        value={{this.xValue}}
+        disabled={{@disabled}}
+        {{on 'input' this.handleX}}
+        {{on 'keydown' this.handleKey}}
+      />
+      <input
+        type='range'
+        class='pretui-area-axis pretui-area-axis-y'
+        aria-label={{this.yChannel.label}}
+        aria-valuetext={{this.yValueText}}
+        min={{this.yChannel.min}}
+        max={{this.yChannel.max}}
+        step={{this.yChannel.step}}
+        value={{this.yValue}}
+        disabled={{@disabled}}
+        {{on 'input' this.handleY}}
+        {{on 'keydown' this.handleKey}}
+      />
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-area {
+          position: relative;
+          display: block;
+          width: 100%;
+          aspect-ratio: var(--pretui-area-ratio, 4 / 3);
+          border-radius: calc(var(--radius) / 1.6);
+          overflow: hidden;
+          box-shadow: inset 0 0 0 1px
+            color-mix(in oklch, var(--foreground) 16%, transparent);
+          touch-action: none;
+          cursor: crosshair;
+          /* the faded out-of-gamut pixels are drawn OVER this, so the plate
+             colour is what "unreachable" reads against */
+          background: var(--card);
+        }
+        .pretui-area[data-disabled='true'] {
+          cursor: not-allowed;
+          opacity: 0.55;
+        }
+        .pretui-area-canvas {
+          display: block;
+          width: 100%;
+          height: 100%;
+          /* the canvas is painted at 96²–128² and scaled up; smooth is
+             correct here — the plane genuinely is continuous */
+          image-rendering: auto;
+        }
+        .pretui-area-thumb {
+          position: absolute;
+          left: var(--pretui-area-x, 50%);
+          top: var(--pretui-area-y, 50%);
+          width: var(--pretui-area-thumb-size, 16px);
+          height: var(--pretui-area-thumb-size, 16px);
+          margin-left: calc(var(--pretui-area-thumb-size, 16px) / -2);
+          margin-top: calc(var(--pretui-area-thumb-size, 16px) / -2);
+          border-radius: 50%;
+          background: var(--pretui-area-thumb-color, transparent);
+          box-shadow:
+            0 0 0 2px var(--pretui-area-thumb-ink, var(--boxel-light)),
+            0 0 0 3.5px rgb(0 0 0 / 0.35);
+          pointer-events: none;
+          /* `raised` is the tier for layering INSIDE one component's own box:
+             the thumb over its canvas. It must never compete with anything
+             outside the picker. */
+          z-index: var(--pretui-z-raised, 1);
+        }
+        /* focus lands on an invisible input; the ring belongs on the thumb.
+           The thumb is absolutely positioned, so the doubled transparent
+           outline cannot move anything; it exists only for forced-colors
+           mode, which paints no box-shadow and would otherwise leave the
+           plane with no focus indicator at all. */
+        .pretui-area:has(.pretui-area-axis:focus-visible) .pretui-area-thumb {
+          outline: 2px solid transparent;
+          outline-offset: 2px;
+          box-shadow:
+            0 0 0 2px var(--pretui-area-thumb-ink, var(--boxel-light)),
+            0 0 0 4px var(--ring);
+        }
+        .pretui-area-axis {
+          position: absolute;
+          inset: 0;
+          width: 100%;
+          height: 100%;
+          margin: 0;
+          opacity: 0;
+          appearance: none;
+          -webkit-appearance: none;
+          background: transparent;
+          /* the drag is owned by the surface modifier; the inputs exist for
+             the keyboard and the accessibility tree only */
+          pointer-events: none;
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,49 @@
+## What it is
+
+The two-channel picking plane of a colour tool: a gradient surface where one axis is one channel and the other is another, with a thumb you can move by pointer or by keyboard.
+
+It is a building block of **ColorPicker**. Reach for it when composing a colour tool.
+
+## The contract
+
+```
+@color (required)  — the current colour
+@gamut (required)  — the gamut the plane is painted and clamped against
+@resolution?       — paint resolution. 96 is ~10ms; 128 is ~36ms and visibly crisper
+                     on a large picker
+@disabled?
+@onChange (required) — fires as the colour moves
+@onCommit?           — fires once when a gesture ends
+```
+
+**`@resolution` is a real performance knob with a documented cost.** The plane is painted per render, and the two numbers in the contract are measurements rather than guesses — a large picker earns the crisper paint, a small one does not.
+
+**The gamut is an argument, not an assumption.** The plane is painted for the gamut it is told about, so a colour outside it is visibly outside rather than silently clamped into the surface.
+
+**`@onChange` and `@onCommit` split continuous movement from gesture end**, the same way **ChannelSlider** does.
+
+## Prior art
+
+**hdr-color-input's area picker.**
+
+Where Pretui is better: the accessibility model below, and the gamut being explicit rather than implicit.
+
+Where it is thinner: no zoom into a region of the plane, no alternate channel pairings beyond what the picker's space provides, and no touch-specific magnifier — a fingertip covers the thumb it is moving.
+
+## Accessibility
+
+**A 2D control cannot be one slider, and this is the component where that matters most.** A single `role='slider'` has one value; a plane has two, and announcing a colour as one number is meaningless.
+
+- **The plane is a `role='group'`** containing **two named sliders**, one per axis, each with its own label and its own value text. That is the only arrangement that lets a keyboard user move in both dimensions and be told where they are in each.
+- **Each axis announces a sentence**, not a coordinate.
+- **The painted surface itself is `aria-hidden`**, as is the thumb — they are the visual expression of two values that are already announced.
+- **Keyboard movement is per axis**, which is what the two-slider model buys: arrows move one channel at a time, deliberately, rather than dragging a point around a plane.
+- **A picking plane is the hardest part of any color tool to use without sight**, and this arrangement does not make it easy — it makes it _possible_, which no single-slider or canvas-only implementation does.
+
+## Theming
+
+`--pretui-area-x` and `--pretui-area-y` (the thumb's position), `--pretui-area-thumb-size`, `--pretui-area-thumb-color` and `--pretui-area-thumb-ink`, `--pretui-area-ratio` (the plane's shape).
+
+Splitting the thumb's fill from its ink is what keeps it visible over the whole plane: the thumb sits on every color the surface can show, so a theme sets a ring and a contrasting core rather than one color that will disappear somewhere on the gradient.
+
+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-area.usage.gts

@@ -0,0 +1,72 @@
+// Pretui — ColorArea usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { parseColor } from '../color-engine';
+import type { ColorValue, GamutId } from '../color-engine';
+import { ColorArea } from './color-area';
+import { FreestyleUsage } from './freestyle-usage';
+import { GAMUT_NAMES } from '../internal/color-fixtures';
+
+// ── ColorArea ────────────────────────────────────────────────────────────
+class ColorAreaUsage extends Component {
+  @tracked color: ColorValue = parseColor('oklch(0.66 0.19 25)')!;
+  @tracked gamut = 'srgb';
+  gamuts = GAMUT_NAMES;
+  setColor = (next: ColorValue) => (this.color = next);
+  setGamut = (v: string) => (this.gamut = v);
+  get gamutId(): GamutId {
+    return this.gamut as GamutId;
+  }
+  get usage() {
+    return '<ColorArea @color={{this.color}} @gamut="srgb" @onChange={{this.setColor}} />';
+  }
+  <template>
+    <FreestyleUsage
+      @name='ColorArea'
+      @description="The 2D plane — chroma × lightness here, because the colour is OKLCH. Regions OUTSIDE the selected gamut are painted faded, so the gamut boundary is something you can see and aim at rather than a flat band that lies about what is selectable. Switch the gamut knob to P3 and watch the reachable area grow."
+      @source={{this.usage}}
+    >
+      <:example>
+        <ColorArea
+          @color={{this.color}}
+          @gamut={{this.gamutId}}
+          @onChange={{this.setColor}}
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='gamut'
+          @defaultValue='srgb'
+          @options={{this.gamuts}}
+          @description='Which gamut counts as reachable. Unreachable pixels are drawn faded.'
+          @value={{this.gamut}}
+          @onInput={{this.setGamut}}
+        />
+        <Args.Number
+          @name='resolution'
+          @defaultValue={{96}}
+          @description='Paint resolution. 96² is ~10ms; 128² is ~36ms and crisper on a large picker. Painted synchronously inside a modifier — no worker, so no lifetime to leak.'
+          @value={{96}}
+        />
+        <Args.Action
+          @name='onChange'
+          @description='Receives a ColorValue on every pointer move and arrow press.'
+        />
+      </:api>
+      <:description>
+        <p>Two real
+          <code>&lt;input type="range"&gt;</code>
+          elements sit invisibly over the plane, one per axis, each with its own
+          label and spoken value — a single
+          <code>aria-valuenow</code>
+          cannot express two axes. Either tab stop drives both axes, so a
+          keyboard user never has to know which invisible input they are on.
+          Home/End move along the focused axis.</p>
+      </:description>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_COLOR_AREA: Record<string, unknown> = {
+  ColorArea: ColorAreaUsage,
+};

package/bundled-realms/pretui/components/color-field.gts

@@ -0,0 +1,179 @@
+// Pretui — ColorField: a colour value as a form field with a picker popover.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { Popover } from './popover';
+import { FormField } from './form-field';
+import { describeColor, parseColor, toHex } from '../color-engine';
+import type { ColorValue, GamutId, SpaceId } from '../color-engine';
+import { ColorPalette } from './color-palette';
+import { ColorPicker } from './color-picker';
+import type { ColorFormat } from './color-picker';
+import { SwatchChip } from './swatch-chip';
+
+// ── ColorField ───────────────────────────────────────────────────────────
+
+/**
+ * The small surface that OPENS the picker: a labelled form field whose
+ * control is a swatch trigger plus a hex text input, with the full picker in
+ * a popover.
+ *
+ * Composed rather than rebuilt: `FormField` (forms-core) owns the label,
+ * description, required marking, issue routing and describedby wiring;
+ * `Popover` (overlay) owns placement, dismissal, Escape and focus return;
+ * `Swatch` is the trigger face. Nothing here re-implements any of that —
+ * which is the point of having the foundations.
+ */
+export interface ColorFieldSignature {
+  Args: {
+    label?: string;
+    value?: string;
+    defaultValue?: string;
+    description?: string;
+    required?: boolean;
+    disabled?: boolean;
+    /** Path for form issue routing. */
+    path?: string;
+    space?: SpaceId;
+    gamut?: GamutId;
+    noAlpha?: boolean;
+    format?: ColorFormat;
+    /** Quick-pick swatches shown above the picker. */
+    presets?: string[];
+    onValueChange?: (value: string) => void;
+  };
+  Element: HTMLDivElement;
+}
+
+export class ColorField extends Component<ColorFieldSignature> {
+  @tracked private internal: string | null = null;
+
+  get value(): string {
+    return this.args.value ?? this.internal ?? this.args.defaultValue ?? '';
+  }
+  get parsed(): ColorValue | null {
+    return parseColor(this.value);
+  }
+  get display(): string {
+    let parsed = this.parsed;
+    return parsed ? toHex(parsed) : '';
+  }
+  get triggerLabel(): string {
+    let parsed = this.parsed;
+    return parsed
+      ? `Colour: ${describeColor(parsed, this.args.gamut ?? 'srgb')}`
+      : 'Choose a colour';
+  }
+  get swatchColor(): string {
+    return this.value || 'transparent';
+  }
+
+  handleChange = (next: string) => {
+    if (this.args.value === undefined) {
+      this.internal = next;
+    }
+    this.args.onValueChange?.(next);
+  };
+
+  <template>
+    <FormField
+      @label={{@label}}
+      @path={{@path}}
+      @description={{@description}}
+      @required={{@required}}
+      @disabled={{@disabled}}
+      data-test-pretui-color-field
+      ...attributes
+    >
+      <:control as |control|>
+        <div class='pretui-colorfield'>
+          <Popover @placement='bottom-start' @label='Colour picker'>
+            <:trigger as |open toggle|>
+              <button
+                type='button'
+                class='pretui-colorfield-trigger'
+                id={{control.id}}
+                aria-expanded={{if open 'true' 'false'}}
+                aria-haspopup='dialog'
+                aria-label={{this.triggerLabel}}
+                disabled={{@disabled}}
+                {{on 'click' toggle}}
+              >
+                <SwatchChip
+                  @color={{this.swatchColor}}
+                  @shape='square'
+                  @size={{18}}
+                  aria-hidden='true'
+                />
+                <span class='pretui-colorfield-value'>{{this.display}}</span>
+              </button>
+            </:trigger>
+            <:default>
+              <div class='pretui-colorfield-panel'>
+                {{#if @presets}}
+                  <ColorPalette
+                    @colors={{@presets}}
+                    @value={{this.value}}
+                    @label='Preset colours'
+                    @onValueChange={{this.handleChange}}
+                  />
+                {{/if}}
+                <ColorPicker
+                  @value={{this.value}}
+                  @space={{@space}}
+                  @gamut={{@gamut}}
+                  @noAlpha={{@noAlpha}}
+                  @format={{@format}}
+                  @onValueChange={{this.handleChange}}
+                />
+              </div>
+            </:default>
+          </Popover>
+        </div>
+      </:control>
+    </FormField>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-colorfield {
+          display: flex;
+        }
+        .pretui-colorfield-trigger {
+          display: inline-flex;
+          align-items: center;
+          gap: var(--space-2, 5px);
+          height: var(--control-h, 28px);
+          padding: 0 var(--space-3, 8px);
+          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-colorfield-trigger:disabled {
+          cursor: not-allowed;
+          opacity: 0.55;
+        }
+        .pretui-colorfield-trigger:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 1px;
+        }
+        .pretui-colorfield-value {
+          font-family: var(--font-mono);
+          font-variant-numeric: tabular-nums;
+          min-width: 8ch;
+          text-align: left;
+        }
+        .pretui-colorfield-panel {
+          display: flex;
+          flex-direction: column;
+          gap: var(--space-3, 8px);
+          padding: var(--space-3, 8px);
+          min-width: 264px;
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,47 @@
+## What it is
+
+A form field whose value is a colour: a trigger showing the current colour, a popover holding a **ColorPicker**, and optional quick-pick swatches.
+
+It is the form-facing wrapper. **ColorPicker** is the instrument; this is the field you put in a form.
+
+## The contract
+
+```
+@label?, @description?, @required?, @disabled?
+@value?, @defaultValue?
+@path?      — path for form issue routing
+@space?, @gamut?, @noAlpha?, @format? — forwarded to the picker
+@presets?   — quick-pick swatches shown above the picker
+@onValueChange?
+```
+
+**`@path` is what connects the field to a form's issue routing**, so a validation problem on this colour lands on this control rather than in a general error list.
+
+**The picker's space, gamut, alpha and format args are forwarded**, so a field can lock the whole product to sRGB hex without the call site reaching past the field into the picker.
+
+**`@presets` are a fast path, not a constraint.** They sit above the picker; the full picker remains.
+
+## Prior art
+
+**hdr-color-input.**
+
+Where Pretui is better: the split between field and instrument. A colour picker embedded directly into a form is a large surface competing with the rest of the fields; putting it behind a trigger with a popover makes a colour field the same size as a text field, which is what a form wants.
+
+Where it is thinner: no eyedropper on the trigger itself, no recent-colours memory across fields, and no contrast check against a paired colour — the obvious missing feature for a design-system colour field.
+
+## Accessibility
+
+- **The trigger carries `aria-haspopup='dialog'` and `aria-expanded`**, which is the correct pattern for a control that opens a picker rather than a listbox.
+- **The trigger is named**, so a row of colour fields does not announce as several identical buttons.
+- **The colour preview inside the trigger is `aria-hidden`** — the value is in the name, and a swatch has nothing to announce.
+- **The popover holds ColorPicker**, so everything that component does about gamut reporting and text entry applies here.
+- **`@description` is associated with the field**, giving a place for "hex or any CSS colour" that is not a placeholder.
+- **A colour chosen by swatch is the same value as one typed**, so the two paths never disagree.
+
+## Theming
+
+`--pretui-swatch-size` and `--pretui-swatch-color` for the trigger and presets, `--pretui-palette-columns` for the preset grid, `--pretui-checker` behind anything with alpha, `--pretui-destructive-ink` for the invalid state, `--pretui-z-raised` for the popover layer.
+
+`--pretui-palette-columns` as a token rather than an arg is deliberate: preset grids should have the same rhythm everywhere in a product, and a per-field column count is how a palette ends up looking different on two screens.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.