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

package/bundled-realms/pretui/components/value-input.gts

@@ -0,0 +1,265 @@
+// Pretui — ValueInput: one editor for any typed value, picking the right control for its kind.
+import Component from '@glimmer/component';
+import { Checkbox } from './checkbox';
+import { Input } from './input';
+import { Select } from './select';
+import type { SelectOption } from './select';
+import { ScrubInput } from './scrub-input';
+import type { PropertyRowSignature } from './property-row';
+import { AngleDial } from './angle-dial';
+import { Joystick } from './joystick';
+import { OriginGrid } from './origin-grid';
+import type { Point2 } from './joystick';
+import { EasingCurve } from './easing-curve';
+import type { CubicBezier } from './easing-curve';
+
+/** The value vocabulary this territory can edit. Extend through the
+ * `<:custom>` block rather than by widening this union in a fork. */
+export type ValueKind =
+  | 'number'
+  | 'text'
+  | 'toggle'
+  | 'select'
+  | 'angle'
+  | 'point'
+  | 'origin'
+  | 'curve'
+  | 'custom';
+
+export type ValueOf =
+  | number
+  | string
+  | boolean
+  | Point2
+  | CubicBezier
+  | null
+  | undefined;
+
+/** One row of a property sheet: what to edit, how, and in what state. */
+export interface ValueSpec {
+  /** stable key — the sheet uses it to address the value */
+  key: string;
+  kind: ValueKind;
+  label?: string;
+  hint?: string;
+  /** numeric kinds */
+  min?: number;
+  max?: number;
+  step?: number;
+  precision?: number;
+  unit?: string;
+  /** select kind */
+  options?: SelectOption[];
+  /** text kind */
+  placeholder?: string;
+  /** multi-selection with differing values */
+  mixed?: boolean;
+  /** differs from default — reveals the row's reset control */
+  modified?: boolean;
+  disabled?: boolean;
+  /** row layout override; the sheet's own default otherwise */
+  layout?: PropertyRowSignature['Args']['layout'];
+}
+
+const ORIGIN_DEFAULT: Point2 = { x: 50, y: 50 };
+const CURVE_DEFAULT: CubicBezier = { x1: 0.42, y1: 0, x2: 0.58, y2: 1 };
+
+function isPoint(value: ValueOf): value is Point2 {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as Point2).x === 'number' &&
+    typeof (value as Point2).y === 'number'
+  );
+}
+
+function isCurve(value: ValueOf): value is CubicBezier {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as CubicBezier).x1 === 'number' &&
+    typeof (value as CubicBezier).y2 === 'number'
+  );
+}
+
+export interface ValueInputSignature {
+  Args: {
+    /** which control to render */
+    kind: ValueKind;
+    /** the value, in whatever shape the kind implies */
+    value?: ValueOf;
+    /** knobs for the chosen kind; unrelated fields are simply unread */
+    spec?: Partial<ValueSpec>;
+    /** id to put on the control, so a PropertyRow label points at it */
+    controlId?: string;
+    describedBy?: string;
+    disabled?: boolean;
+    onChange?: (value: ValueOf) => void;
+  };
+  Blocks: {
+    /** kinds this component does not own — colour above all. Receives the
+     * kind, the raw value and whether the control is disabled. */
+    custom: [ValueKind, ValueOf, boolean];
+  };
+  Element: HTMLDivElement;
+}
+
+export class ValueInput extends Component<ValueInputSignature> {
+  get spec(): Partial<ValueSpec> {
+    return this.args.spec ?? {};
+  }
+  get label(): string {
+    return this.spec.label ?? 'Value';
+  }
+  get disabled(): boolean {
+    return this.args.disabled ?? this.spec.disabled ?? false;
+  }
+  get options(): SelectOption[] {
+    return this.spec.options ?? [];
+  }
+
+  // ── narrowing, done here so no template ever narrows ────────────────
+  get asNumber(): number | null {
+    return typeof this.args.value === 'number' ? this.args.value : null;
+  }
+  /** AngleDial's model is a plain number (an angle is never "empty"), so
+   * an absent value reads as 0 rather than null. */
+  get asAngle(): number {
+    return typeof this.args.value === 'number' ? this.args.value : 0;
+  }
+  get asText(): string {
+    return typeof this.args.value === 'string' ? this.args.value : '';
+  }
+  get asBoolean(): boolean {
+    return this.args.value === true;
+  }
+  get asPoint(): Point2 {
+    return isPoint(this.args.value) ? this.args.value : ORIGIN_DEFAULT;
+  }
+  get asCurve(): CubicBezier {
+    return isCurve(this.args.value) ? this.args.value : CURVE_DEFAULT;
+  }
+
+  // ── adapters, one per kind ──────────────────────────────────────────
+  emitNumber = (value: number | null) => {
+    this.args.onChange?.(value);
+  };
+  emitText = (value: string) => {
+    this.args.onChange?.(value);
+  };
+  emitBoolean = (value: boolean) => {
+    this.args.onChange?.(value);
+  };
+  emitSelect = (value: string) => {
+    this.args.onChange?.(value);
+  };
+  emitAngle = (value: number) => {
+    this.args.onChange?.(value);
+  };
+  emitPoint = (value: Point2) => {
+    this.args.onChange?.(value);
+  };
+  emitCurve = (value: CubicBezier) => {
+    this.args.onChange?.(value);
+  };
+  <template>
+    <div class='pretui-value' data-kind={{@kind}} data-test-pretui-value-input ...attributes>
+      {{#if (eq @kind 'number')}}
+        <ScrubInput
+          @controlId={{@controlId}}
+          @describedBy={{@describedBy}}
+          @label={{this.label}}
+          @value={{this.asNumber}}
+          @min={{this.spec.min}}
+          @max={{this.spec.max}}
+          @step={{this.spec.step}}
+          @precision={{this.spec.precision}}
+          @unit={{this.spec.unit}}
+          @mixed={{this.spec.mixed}}
+          @disabled={{this.disabled}}
+          @steppers={{true}}
+          @onChange={{this.emitNumber}}
+        />
+      {{else if (eq @kind 'text')}}
+        <Input
+          @value={{this.asText}}
+          @placeholder={{this.spec.placeholder}}
+          @disabled={{this.disabled}}
+          @controlId={{@controlId}}
+          @onInput={{this.emitText}}
+        />
+      {{else if (eq @kind 'toggle')}}
+        <Checkbox
+          @checked={{this.asBoolean}}
+          @label={{this.label}}
+          @disabled={{this.disabled}}
+          @onCheckedChange={{this.emitBoolean}}
+        />
+      {{else if (eq @kind 'select')}}
+        <Select
+          @options={{this.options}}
+          @value={{this.asText}}
+          @placeholder={{this.spec.placeholder}}
+          @disabled={{this.disabled}}
+          @controlId={{@controlId}}
+          @onValueChange={{this.emitSelect}}
+        />
+      {{else if (eq @kind 'angle')}}
+        <AngleDial
+          @label={{this.label}}
+          @value={{this.asAngle}}
+          @min={{this.spec.min}}
+          @max={{this.spec.max}}
+          @step={{this.spec.step}}
+          @precision={{this.spec.precision}}
+          @rotations={{true}}
+          @disabled={{this.disabled}}
+          @onChange={{this.emitAngle}}
+        />
+      {{else if (eq @kind 'point')}}
+        <Joystick
+          @label={{this.label}}
+          @value={{this.asPoint}}
+          @step={{this.spec.step}}
+          @precision={{this.spec.precision}}
+          @disabled={{this.disabled}}
+          @onChange={{this.emitPoint}}
+        />
+      {{else if (eq @kind 'origin')}}
+        <OriginGrid
+          @label={{this.label}}
+          @value={{this.asPoint}}
+          @precision={{this.spec.precision}}
+          @disabled={{this.disabled}}
+          @onChange={{this.emitPoint}}
+        />
+      {{else if (eq @kind 'curve')}}
+        <EasingCurve
+          @label={{this.label}}
+          @value={{this.asCurve}}
+          @precision={{this.spec.precision}}
+          @disabled={{this.disabled}}
+          @onChange={{this.emitCurve}}
+        />
+      {{else}}
+        {{yield @kind @value this.disabled to='custom'}}
+      {{/if}}
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-value {
+          display: block;
+          min-width: 0;
+          width: 100%;
+        }
+      }
+    </style>
+  </template>
+}
+
+/** Strict-mode templates have no built-in equality helper, and the kit does
+ * not ship one; a five-line local keeps `ValueInput` a single component
+ * rather than nine wrapper classes. */
+function eq(a: unknown, b: unknown): boolean {
+  return a === b;
+}

package/bundled-realms/pretui/components/value-input.md

@@ -0,0 +1,49 @@
+## What it is
+
+One control chosen by kind: hand it a `kind` and a value and it renders the right editor.
+
+It is the switch **PropertySheet** uses to turn a typed spec into a control, and the reason a property panel is a list of data rather than a tree of conditionals.
+
+## The contract
+
+```
+@kind (required) — which control to render
+@value?      — the value, in whatever shape the kind implies
+@spec?       — knobs for the chosen kind; unrelated fields are simply unread
+@controlId?  — id to put on the control, so a PropertyRow label points at it
+@describedBy?
+@disabled?
+@onChange?
+
+<:custom as |kind value disabled|> — kinds this component does not own — colour above all.
+            Receives the kind and the raw value
+```
+
+**`@spec` is a partial bag and unrelated fields are unread.** That is what lets one spec type describe every kind: a numeric row's `min`/`max` and a select row's `options` can live in the same object, and each kind takes what it needs.
+
+**`@controlId` and `@describedBy` are passed through to the control**, which is how the row's label association survives the indirection.
+
+**`<:custom>` is where the boundary is drawn**, and colour is the named case: a colour editor is a component in its own right, and inlining one here would make this switch own a picker.
+
+## Prior art
+
+The value-editor switch inside every property panel implementation.
+
+Where Pretui is better: it is a component with a contract rather than a conditional inside a sheet, which means a caller assembling rows by hand gets the same behaviour the sheet gets. The custom block makes the boundary explicit instead of the switch quietly growing.
+
+Where it is thinner: the kind list is fixed — extending it means `<:custom>` — there is no validation, and no kind inference from the value's shape.
+
+## Accessibility
+
+- **The ids pass through.** A control rendered here is labelled and described by whatever row contains it, exactly as a hand-written control would be.
+- **`<:custom>` receives no ids of its own beyond what the caller wires**, so a custom control that ignores `@controlId` breaks its label association — the one way to get this wrong.
+- **Each kind renders a real control of its type** rather than a styled div, so the platform's semantics come along.
+- **`@disabled` is passed to the control**, not applied as a visual state on a wrapper.
+
+## Theming
+
+Nothing of its own — every kind renders a kit control and inherits that control's tokens.
+
+A switch that themed would be a switch that made a text field in a property panel look different from a text field in a form, which is exactly the drift this component exists to prevent.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/value-input.usage.gts

@@ -0,0 +1,176 @@
+// Pretui — ValueInput usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { ValueInput } from './value-input';
+import type { ValueKind, ValueOf, ValueSpec } from './value-input';
+import { BLEND_OPTIONS } from '../demo-design-value';
+
+const KINDS = [
+  'number',
+  'text',
+  'toggle',
+  'select',
+  'angle',
+  'point',
+  'origin',
+  'curve',
+  'custom',
+];
+
+class ValueInputUsage extends Component {
+  kindOptions = KINDS;
+  blendOptions = BLEND_OPTIONS;
+
+  @tracked kind = 'number';
+  @tracked value: ValueOf = 24;
+  @tracked mixed = false;
+  @tracked disabled = false;
+
+  setKind = (v: string) => {
+    this.kind = v;
+    this.value = this.seedFor(v);
+  };
+  setMixed = (v: boolean) => (this.mixed = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  change = (v: ValueOf) => (this.value = v);
+
+  private seedFor(kind: string): ValueOf {
+    if (kind === 'number') {
+      return 24;
+    }
+    if (kind === 'text') {
+      return 'Layer 1';
+    }
+    if (kind === 'toggle') {
+      return true;
+    }
+    if (kind === 'select') {
+      return 'multiply';
+    }
+    if (kind === 'angle') {
+      return 45;
+    }
+    if (kind === 'point' || kind === 'origin') {
+      return { x: 50, y: 50 };
+    }
+    if (kind === 'curve') {
+      return { x1: 0.42, y1: 0, x2: 0.58, y2: 1 };
+    }
+    return null;
+  }
+
+  get kindVal() {
+    return this.kind as ValueKind;
+  }
+  get spec(): Partial<ValueSpec> {
+    return {
+      label: 'Value',
+      min: this.kind === 'number' ? 0 : undefined,
+      max: this.kind === 'number' ? 200 : undefined,
+      unit: this.kind === 'number' ? 'px' : undefined,
+      precision: 0,
+      options: BLEND_OPTIONS,
+      placeholder: 'Type a name',
+      mixed: this.mixed,
+    };
+  }
+  get readout() {
+    return JSON.stringify(this.value);
+  }
+  get usage() {
+    return (
+      "<ValueInput @kind='" +
+      this.kind +
+      "' @value={{this.value}} @spec={{this.spec}} @onChange={{this.change}} />"
+    );
+  }
+  <template>
+    <FreestyleUsage
+      @name='ValueInput'
+      @description='One control chosen by a kind discriminator, behind a single value/onChange contract — the natural consumer of every control this territory ships. The COMPONENT does the narrowing (asNumber, asPoint, asCurve, each with a sane fallback), never the caller, so a template never narrows a union. Unknown kinds fall through to a <:custom> block rather than crashing; kind="color" routes there deliberately, because colour belongs to the colour territory.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='pretui-value-demo'>
+          <ValueInput
+            @kind={{this.kindVal}}
+            @value={{this.value}}
+            @spec={{this.spec}}
+            @disabled={{this.disabled}}
+            @onChange={{this.change}}
+          >
+            <:custom as |kind|>
+              <p class='pretui-value-slot'>
+                No built-in editor for “{{kind}}” — this is the
+                <code>&lt;:custom&gt;</code>
+                slot a consumer fills (colour routes here).
+              </p>
+            </:custom>
+          </ValueInput>
+          <p class='pretui-demo-readout' data-test-value-readout>{{this.readout}}</p>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='kind'
+          @defaultValue='number'
+          @value={{this.kind}}
+          @options={{this.kindOptions}}
+          @description='Which control to render. Anything outside the union — or the literal “custom” — falls through to the <:custom> block.'
+          @onInput={{this.setKind}}
+        />
+        <Args.Object
+          @name='value'
+          @description='The value in whatever shape the kind implies: number, string, boolean, { x, y }, or { x1, y1, x2, y2 }.'
+        />
+        <Args.Object
+          @name='spec'
+          @description='Knobs for the chosen kind (min/max/step/precision/unit/options/placeholder/mixed). Fields the kind does not use are simply unread.'
+        />
+        <Args.Bool
+          @name='mixed'
+          @defaultValue={{false}}
+          @value={{this.mixed}}
+          @description='Demo knob for spec.mixed — multi-selection with differing values.'
+          @onInput={{this.setMixed}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @defaultValue={{false}}
+          @value={{this.disabled}}
+          @onInput={{this.setDisabled}}
+        />
+        <Args.String @name='controlId' @description='id for the control, so a PropertyRow label points at it.' />
+        <Args.Action @name='onChange' @description='Receives the value in the kind’s own shape.' />
+        <Args.Yield @description='The custom block receives (kind, value).' />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-value-demo {
+        max-width: 240px;
+        container-type: inline-size;
+      }
+      .pretui-value-slot {
+        margin: 0;
+        padding: 8px;
+        border-radius: var(--radius);
+        background: var(--field, var(--boxel-light));
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+      .pretui-demo-readout {
+        margin: 8px 0 0;
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--muted-foreground);
+        overflow-x: auto;
+        white-space: nowrap;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_VALUE_INPUT: Record<string, unknown> = {
+  ValueInput: ValueInputUsage,
+};

package/bundled-realms/pretui/components/video-player.gts

@@ -0,0 +1,80 @@
+// Pretui — VideoPlayer: MediaPlayer skinned for video, with a reserved aspect ratio and a caption.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { MediaPlayer } from './media-player';
+import type { MediaPlayerSignature } from './media-player';
+
+// ── VideoPlayer ──────────────────────────────────────────────────────────
+//
+// The other skin. It curries `@kind='video'` and defaults the two things a
+// video needs and an audio track does not: a reserved aspect ratio and a
+// poster. Everything else is MediaPlayer's, forwarded.
+
+export interface VideoPlayerSignature {
+  Args: Omit<MediaPlayerSignature['Args'], 'kind'> & {
+    /** Caption under the picture. A `<figcaption>`, so the picture and its
+     * caption are one figure to assistive technology. */
+    caption?: string;
+  };
+  Blocks: {
+    /** Forwarded to MediaPlayer's picture overlay. */
+    overlay: [];
+    /** Forwarded to MediaPlayer's control-bar slot. */
+    controls: [];
+    /** Forwarded to MediaPlayer's footer. */
+    footer: [];
+  };
+  Element: HTMLElement;
+}
+
+export const VideoPlayer: TemplateOnlyComponent<VideoPlayerSignature> =
+  <template>
+    <figure class='pretui-video' data-test-pretui-video-player ...attributes>
+      <MediaPlayer
+        @kind='video'
+        @src={{@src}}
+        @label={{@label}}
+        @poster={{@poster}}
+        @placeholder={{@placeholder}}
+        @aspectRatio={{@aspectRatio}}
+        @tracks={{@tracks}}
+        @thumbnails={{@thumbnails}}
+        @transcript={{@transcript}}
+        @transcriptOpen={{@transcriptOpen}}
+        @captionsDefault={{@captionsDefault}}
+        @chrome={{@chrome}}
+        @seekOffset={{@seekOffset}}
+        @autoHide={{@autoHide}}
+        @loop={{@loop}}
+        @muted={{@muted}}
+        @preload={{@preload}}
+        @crossOrigin={{@crossOrigin}}
+        @quietStatus={{@quietStatus}}
+        @onSnapshot={{@onSnapshot}}
+      >
+        <:overlay>{{yield to='overlay'}}</:overlay>
+        <:controls>{{yield to='controls'}}</:controls>
+        <:footer>{{yield to='footer'}}</:footer>
+      </MediaPlayer>
+      {{#if @caption}}
+        <figcaption class='pretui-video-caption'>{{@caption}}</figcaption>
+      {{/if}}
+    </figure>
+
+    <style scoped>
+      @layer PretComponent {
+        .pretui-video {
+          display: flex;
+          flex-direction: column;
+          gap: 8px;
+          margin: 0;
+          min-width: 0;
+        }
+        .pretui-video-caption {
+          font-size: var(--text-ui-sm, 11.5px);
+          line-height: 1.55;
+          color: var(--muted-foreground);
+          text-wrap: pretty;
+        }
+      }
+    </style>
+  </template>;

package/bundled-realms/pretui/components/video-player.md

@@ -0,0 +1,46 @@
+## What it is
+
+The video skin over **MediaPlayer**: the same transport, wrapped in a `<figure>` so the picture and its caption are one thing to assistive technology.
+
+It is a skin, not a rewrite. Every arg except `@kind` is forwarded straight through, and all three blocks are re-yielded. Reach for it whenever the media is video; reach for **MediaPlayer** directly only if you do not want the figure wrapper, and for **MediaViewer** when the kind is decided by the asset rather than by you.
+
+## The contract
+
+```
+every MediaPlayer arg except kind — @src, @label, @poster, @placeholder,
+  @aspectRatio, @tracks, @thumbnails, @transcript, @transcriptOpen,
+  @captionsDefault, @chrome, @seekOffset, @autoHide, @loop, @muted,
+  @preload, @crossOrigin, @quietStatus, @onSnapshot
+@caption? — caption under the picture, rendered as a <figcaption>
+
+<:overlay>, <:controls>, <:footer> — forwarded to MediaPlayer
+```
+
+**The kind is fixed to `'video'` and cannot be passed**, which is the whole difference between this and its base: the type omits that arg rather than accepting and ignoring it.
+
+**The wrapper is a real `<figure>` with a real `<figcaption>`**, not a div with a styled line under it. That association is the reason to use this rather than laying out a caption yourself.
+
+**The aspect ratio is reserved before the poster resolves.** Switching the source changes the box without a flash of collapsed layout — the defect the catalog sweep found three separate times in hand-rolled players, and the reason `@aspectRatio` has a default rather than being optional in practice.
+
+## Prior art
+
+**Vidstack** (MIT, web-components build) is the reference for this layer, over **Media Chrome** underneath. Both ship a video player; neither ships the figure/figcaption pairing, which is left to the caller and therefore usually skipped.
+
+Where Pretui is better: the figure semantics come for free, and the reserved ratio is enforced rather than documented.
+
+Where it is thinner: everything **MediaPlayer** lacks is lacking here too — no playlist, no quality selector, no chapters menu — and this layer adds no video-specific affordances of its own. There is no thumbnail-scrubbing UI beyond what `@thumbnails` gives Media Chrome, and no poster-to-first-frame transition.
+
+## Accessibility
+
+- **The `<figure>`/`<figcaption>` pairing is the point.** A caption laid out as a sibling paragraph is loose text; inside a figure it is the picture's caption, and assistive technology can say so.
+- **`@caption` does not name the player.** The accessible name still comes from `@label`, forwarded to MediaPlayer. A video with a caption but no label is still an unnamed region — the caption is _about_ the media, not the name _of_ it.
+- **Everything else is MediaPlayer's**: the polite live region that speaks only on failure, the seekable transcript as an APG disclosure, the `aria-current` cue, the status line whose glyph is hidden and whose text carries the meaning.
+- **Captions need `@tracks`, and cross-origin track files need `@crossOrigin='anonymous'`** or the browser drops them with no error and no captions button.
+
+## Theming
+
+The figure adds `--text-ui-sm` for the caption and an 8px gap between picture and caption; everything else is **MediaPlayer**'s — `--pretui-media-aspect`, `--pretui-media-radius`, `--pretui-media-ink`, `--pretui-media-scrim`, `--pretui-destructive-ink`, `--pretui-shadow-card`, `--pretui-shadow-hairline`.
+
+There is deliberately no video-specific token surface: a theme that retunes the player retunes this with it, and a video that looked different from an audio player in the same theme would be a bug.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.