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

package/bundled-realms/pretui/components/property-row.gts

@@ -0,0 +1,316 @@
+// Pretui — PropertyRow: the property-panel atom, a label and its control in one row.
+import Component from '@glimmer/component';
+import { on } from '@ember/modifier';
+import { htmlSafe } from '@ember/template';
+import { guidFor } from '@ember/object/internals';
+
+// ═══════════════════════════════════════════════════════════════════════
+// PropertyRow — the atom (fig-field)
+// ═══════════════════════════════════════════════════════════════════════
+
+export interface PropertyRowSignature {
+  Args: {
+    /** the property name, shown in the label column */
+    label?: string;
+    /** short explanation; rendered under the control, and referenced by
+     * `aria-describedby` on whatever the caller wires `controlId` to */
+    hint?: string;
+    /** 'row' (default) puts the label in a fixed left column — the dense
+     * inspector shape. 'stack' puts it above. 'split' gives label and
+     * control equal halves. */
+    layout?: 'row' | 'stack' | 'split';
+    /** width of the label column in `row` layout; any CSS length */
+    labelWidth?: string;
+    /** true when the selection holds more than one value for this property.
+     * Rendered as the WORD "Mixed" beside the label, never as colour or a
+     * bare dash: state is never colour alone. */
+    mixed?: boolean;
+    /** true when the value differs from its default: reveals the reset
+     * control. Without `@onReset` the dot is informational only. */
+    modified?: boolean;
+    /** invoked by the reset control */
+    onReset?: () => void;
+    /** dims the row (`data-disabled`), blocks the reset control, and is
+     * yielded so the control can follow it */
+    disabled?: boolean;
+  };
+  Blocks: {
+    /** the control(s). Yields the id to put on the control so the label
+     * points at it, the id of the hint for `aria-describedby`, and
+     * whether the row is disabled. */
+    default: [controlId: string, hintId: string, disabled: boolean];
+    /** replaces the plain text label — for a label that is itself a
+     * control (a scrub grip, a units toggle) */
+    label: [controlId: string];
+    /** trailing affordances: a link/unlink toggle, an overflow menu */
+    actions: [];
+  };
+  Element: HTMLDivElement;
+}
+
+/**
+ * The inspector row: a property name, its control, and the two states a
+ * property panel cannot work without — MIXED (multi-selection) and MODIFIED
+ * (differs from default, offering a reset).
+ *
+ * **Why this is not `Field`.** `controls.gts`'s `Field` is the FORM field:
+ * label above, control below, and a permanently reserved message line so a
+ * row of side-by-side inputs never shifts when validation appears. Those
+ * are exactly the wrong properties for an inspector, where rows are dense,
+ * the label lives in a fixed left column, and vertical space is the scarce
+ * resource. `PropertyRow` also carries mixed/modified/reset, which are
+ * inspector concepts with no meaning in a form. Use `Field` in forms and
+ * `PropertyRow` in panels; `PropertyRow @layout='stack'` is the closest the
+ * two come to each other.
+ */
+export class PropertyRow extends Component<PropertyRowSignature> {
+  private guid = guidFor(this);
+  get controlId(): string {
+    return this.guid + '-ctl';
+  }
+  get hintId(): string {
+    return this.guid + '-hint';
+  }
+  get labelStyle() {
+    // Caller strings never reach CSS unescaped: only a whitelist of length
+    // characters survives, so `@labelWidth` cannot inject a declaration.
+    let raw = this.args.labelWidth ?? '';
+    let safe = /^[0-9a-zA-Z.%() +-]{0,32}$/.test(raw) ? raw : '';
+    return safe ? htmlSafe('--pretui-property-label-w: ' + safe) : undefined;
+  }
+  get resetLabel(): string {
+    return this.args.label ? 'Reset ' + this.args.label : 'Reset to default';
+  }
+  get disabled(): boolean {
+    return this.args.disabled === true;
+  }
+  handleReset = () => {
+    if (this.disabled) {
+      return;
+    }
+    this.args.onReset?.();
+  };
+  <template>
+    <div
+      class='pretui-property'
+      data-layout={{if @layout @layout 'row'}}
+      data-mixed={{if @mixed 'true'}}
+      data-modified={{if @modified 'true'}}
+      data-disabled={{if @disabled 'true'}}
+      style={{this.labelStyle}}
+      data-test-pretui-property-row
+      ...attributes
+    >
+      <div class='pretui-property-name'>
+        {{#if (has-block 'label')}}
+          {{yield this.controlId to='label'}}
+        {{else if @label}}
+          <label for={{this.controlId}}>{{@label}}</label>
+        {{/if}}
+        {{#if @mixed}}
+          <span class='pretui-property-mixed' data-test-pretui-property-mixed>Mixed</span>
+        {{/if}}
+      </div>
+
+      <div class='pretui-property-control'>
+        {{yield this.controlId this.hintId this.disabled}}
+      </div>
+
+      <div class='pretui-property-tail'>
+        {{#if (has-block 'actions')}}{{yield to='actions'}}{{/if}}
+        {{#if @modified}}
+          {{#if @onReset}}
+            <button
+              type='button'
+              class='pretui-property-reset'
+              aria-label={{this.resetLabel}}
+              aria-disabled={{if @disabled 'true'}}
+              {{on 'click' this.handleReset}}
+              data-test-pretui-property-reset
+            >
+              <svg
+                width='11'
+                height='11'
+                viewBox='0 0 12 12'
+                aria-hidden='true'
+                focusable='false'
+              ><path
+                  d='M2.5 6a3.5 3.5 0 1 0 1.1-2.55M3 2v2h2'
+                  fill='none'
+                  stroke='currentColor'
+                  stroke-width='1.2'
+                  stroke-linecap='round'
+                  stroke-linejoin='round'
+                /></svg>
+            </button>
+          {{else}}
+            <span
+              class='pretui-property-dot'
+              title='Changed from default'
+              data-test-pretui-property-dot
+            ><span class='pretui-sr'>Changed from default</span></span>
+          {{/if}}
+        {{/if}}
+      </div>
+
+      {{#if @hint}}
+        <p class='pretui-property-hint' id={{this.hintId}}>{{@hint}}</p>
+      {{/if}}
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-property {
+          --pretui-property-label-w: 84px;
+          display: grid;
+          grid-template-columns: var(--pretui-property-label-w) minmax(0, 1fr) auto;
+          grid-template-areas: 'name control tail' '. hint hint';
+          align-items: center;
+          column-gap: var(--space-3, 8px);
+          row-gap: 2px;
+          min-height: var(--control-h, 28px);
+          padding-block: 1px;
+          font-size: var(--text-ui, 12px);
+          letter-spacing: var(--track-ui, 0.01em);
+          color: var(--foreground);
+        }
+        .pretui-property[data-layout='stack'] {
+          grid-template-columns: minmax(0, 1fr) auto;
+          grid-template-areas: 'name tail' 'control control' 'hint hint';
+          align-items: start;
+          row-gap: 4px;
+        }
+        .pretui-property[data-layout='split'] {
+          grid-template-columns: minmax(0, 1fr) minmax(0, 1fr) auto;
+        }
+        .pretui-property[data-disabled='true'] {
+          opacity: 0.45;
+        }
+        .pretui-property-name {
+          grid-area: name;
+          display: flex;
+          align-items: baseline;
+          gap: 5px;
+          min-width: 0;
+        }
+        .pretui-property-name > label {
+          display: block;
+          min-width: 0;
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+          font-weight: 500;
+          color: var(--muted-foreground);
+          cursor: default;
+        }
+        .pretui-property-control {
+          grid-area: control;
+          min-width: 0;
+          display: flex;
+          align-items: center;
+          gap: var(--space-2, 6px);
+        }
+        .pretui-property-control > * {
+          min-width: 0;
+        }
+        .pretui-property-tail {
+          grid-area: tail;
+          display: flex;
+          align-items: center;
+          gap: 2px;
+          /* The reset control is revealed by hover/focus but must never be
+             the ONLY way to reach it: it stays in the tab order and becomes
+             fully opaque on :focus-visible, and on a coarse pointer it is
+             always visible (see the pointer query below). */
+          opacity: 0;
+          transition: opacity var(--pretui-dur-snap, 160ms)
+            var(--pretui-ease-snap, ease);
+        }
+        .pretui-property:hover .pretui-property-tail,
+        .pretui-property:focus-within .pretui-property-tail,
+        .pretui-property[data-mixed='true'] .pretui-property-tail {
+          opacity: 1;
+        }
+        .pretui-property-hint {
+          grid-area: hint;
+          margin: 0;
+          font-size: var(--text-ui-sm, 11.5px);
+          color: var(--ink-3, var(--boxel-400));
+        }
+        .pretui-property-mixed {
+          flex: none;
+          font-family: var(--font-mono);
+          font-size: var(--text-ui-xs, 11px);
+          letter-spacing: var(--track-eyebrow, 0.04em);
+          color: var(--muted-foreground);
+          background: var(--field, var(--boxel-light));
+          border-radius: var(--radius-sm, 5px);
+          padding: 0 4px;
+        }
+        .pretui-property-reset {
+          display: inline-flex;
+          align-items: center;
+          justify-content: center;
+          width: 20px;
+          height: 20px;
+          padding: 0;
+          border: 0;
+          border-radius: var(--radius-sm, 5px);
+          background: transparent;
+          color: var(--muted-foreground);
+          cursor: pointer;
+        }
+        .pretui-property-reset:hover {
+          background: var(--hover, rgb(0 0 0 / 0.05));
+          color: var(--foreground);
+        }
+        .pretui-property-reset:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 1px;
+        }
+        .pretui-property-dot {
+          display: inline-block;
+          width: 6px;
+          height: 6px;
+          margin: 0 7px;
+          border-radius: 50%;
+          background: var(--primary);
+        }
+        .pretui-sr {
+          position: absolute;
+          width: 1px;
+          height: 1px;
+          overflow: hidden;
+          clip-path: inset(50%);
+          white-space: nowrap;
+        }
+        /* Touch: hover-reveal is meaningless, and 20px is under the 44px
+           floor, so the tail is always visible and the hit area grows. */
+        @media (pointer: coarse) {
+          .pretui-property-tail {
+            opacity: 1;
+          }
+          .pretui-property-reset {
+            width: 32px;
+            height: 32px;
+          }
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-property-tail {
+            transition: none;
+          }
+        }
+        /* Narrow panes fold the label above the control. Unnamed container
+           query only — a named one silently deletes every rule after it. */
+        @container (max-width: 240px) {
+          .pretui-property,
+          .pretui-property[data-layout='split'] {
+            grid-template-columns: minmax(0, 1fr) auto;
+            grid-template-areas: 'name tail' 'control control' 'hint hint';
+            align-items: start;
+            row-gap: 4px;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/property-row.md

@@ -0,0 +1,55 @@
+## What it is
+
+One labelled row of a property inspector: a label column, a control, a hint, a mixed-state marker and a reset affordance.
+
+**PropertySheet** builds a panel out of these. Use the row directly when the panel is hand-assembled.
+
+## The contract
+
+```
+@label?      — the property name, shown in the label column
+@hint?       — short explanation under the control, referenced by aria-describedby
+@layout?     — 'row' (default) puts the label in a fixed left column — the dense
+               inspector shape. 'stack' puts it above. 'split' gives equal halves
+@labelWidth? — width of the label column in 'row' layout; any CSS length
+@mixed?      — the selection holds more than one value for this property
+@modified?   — the value differs from its default: reveals the reset control
+@onReset?    — invoked by the reset control
+@disabled?   — dims the row, blocks reset, and is yielded to the control
+
+<:default> — the control(s). Yields [controlId, hintId, disabled]
+<:label>   — replaces the plain text label, for a label that is itself a control
+<:actions> — trailing affordances: a link/unlink toggle, an overflow menu
+```
+
+**`@mixed` renders the word "Mixed"**, never a colour or a bare dash. State is never colour alone, and a multi-selection whose values differ is exactly the state that gets shown as an empty field in hand-built inspectors — which reads as "no value" and is a lie.
+
+**The row yields both ids the caller needs**: the one to put on the control so the label points at it, and the hint's id for `aria-describedby`. That is what makes the label association correct without the caller minting ids.
+
+**Without `@onReset` the modified dot is informational only.** The affordance appears when there is something for it to do.
+
+**`@disabled` dims the row (`data-disabled`) and blocks the reset control, which stays focusable with `aria-disabled`.** The row cannot reach into a yielded block, so it yields the state as the third block param: pass it to the control's own `@disabled`.
+
+## Prior art
+
+figui3's property rows, and the inspector rows in every design tool.
+
+Where Pretui is better: the yielded ids, and "Mixed" as a word. Both are small; both are the things hand-built inspectors get wrong most reliably.
+
+Where it is thinner: no inline validation state, no per-row units switching (that is `<:label>`'s job), and no drag-to-reorder.
+
+## Accessibility
+
+- **The label points at the control through a yielded id**, so the association is real rather than positional — which is the whole point of the block yielding rather than wrapping.
+- **The hint is referenced by `aria-describedby`**, not left as adjacent text.
+- **"Mixed" is a word**, so a multi-value selection is perceivable without sight and without interpreting an empty field.
+- **`<:label>` exists for a label that is itself a control** — a scrub grip, a units toggle — which is the case where a plain `<label>` would be wrong.
+- **The disabled state belongs to the controls.** The row is a layout box, not a widget, so it carries `data-disabled` for styling only. The reset button gets `aria-disabled`, and the yielded `disabled` lets the control announce its own state.
+
+## Theming
+
+`@labelWidth` is a caller value rather than a token, because inspector density is a property of the panel rather than the theme; everything else takes the kit's shared control and text tokens.
+
+The three layouts exist so one component serves a dense left-column inspector, a stacked mobile form and an equal-halves settings row without any of them inventing their own row.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/property-row.usage.gts

@@ -0,0 +1,146 @@
+// Pretui — PropertyRow usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { PropertyRow } from './property-row';
+import { ScrubInput } from './scrub-input';
+
+// ── PropertyRow ──────────────────────────────────────────────────────────
+const LAYOUTS = ['row', 'stack', 'split'];
+
+class PropertyRowUsage extends Component {
+  layoutOptions = LAYOUTS;
+
+  @tracked layout = 'row';
+  @tracked labelText = 'Opacity';
+  @tracked hint = '';
+  @tracked mixed = false;
+  @tracked modified = true;
+  @tracked disabled = false;
+  @tracked value: number | null = 80;
+
+  setLayout = (v: string) => (this.layout = v);
+  setLabel = (v: string) => (this.labelText = v);
+  setHint = (v: string) => (this.hint = v);
+  setMixed = (v: boolean) => (this.mixed = v);
+  setModified = (v: boolean) => (this.modified = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  setValue = (v: number | null) => (this.value = v);
+  reset = () => {
+    this.value = 100;
+    this.modified = false;
+  };
+
+  get layoutVal() {
+    return this.layout as 'row' | 'stack' | 'split';
+  }
+  get usage() {
+    return (
+      "<PropertyRow @label='" +
+      this.labelText +
+      "' @modified={{this.modified}} @onReset={{this.reset}} as |controlId hintId|>\n" +
+      '  <ScrubInput @controlId={{controlId}} @describedBy={{hintId}} … />\n' +
+      '</PropertyRow>'
+    );
+  }
+  <template>
+    <FreestyleUsage
+      @name='PropertyRow'
+      @description='The inspector atom: a property name, its control, and the two states a property panel cannot work without — MIXED (multi-selection) and MODIFIED (differs from default, offering a reset). Ported from figui3 fig-field. Distinct from Field, which is the stacked FORM field with a reserved validation line; PropertyRow is dense, label-in-a-column, and carries reset/mixed.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='pretui-property-demo'>
+          <PropertyRow
+            @label={{this.labelText}}
+            @layout={{this.layoutVal}}
+            @hint={{this.hint}}
+            @mixed={{this.mixed}}
+            @modified={{this.modified}}
+            @disabled={{this.disabled}}
+            @onReset={{this.reset}}
+            as |controlId hintId|
+          >
+            <ScrubInput
+              @controlId={{controlId}}
+              @describedBy={{hintId}}
+              @label={{this.labelText}}
+              @value={{this.value}}
+              @min={{0}}
+              @max={{100}}
+              @unit='%'
+              @precision={{0}}
+              @mixed={{this.mixed}}
+              @disabled={{this.disabled}}
+              @onInput={{this.setValue}}
+            />
+          </PropertyRow>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='label'
+          @value={{this.labelText}}
+          @description='Property name, wired to the yielded controlId with a real <label for>.'
+          @onInput={{this.setLabel}}
+        />
+        <Args.String
+          @name='layout'
+          @defaultValue='row'
+          @value={{this.layout}}
+          @options={{this.layoutOptions}}
+          @description="'row' is the dense inspector shape (fixed label column); 'stack' puts the label above; 'split' gives both halves. A pane under 240px folds to stack automatically via an unnamed container query."
+          @onInput={{this.setLayout}}
+        />
+        <Args.String
+          @name='hint'
+          @value={{this.hint}}
+          @description='Short explanation under the control; its id is the second yielded value, for aria-describedby.'
+          @onInput={{this.setHint}}
+        />
+        <Args.Bool
+          @name='mixed'
+          @defaultValue={{false}}
+          @value={{this.mixed}}
+          @description='Multi-selection. Renders the word “Mixed” beside the label — a text channel, not a colour or a bare dash.'
+          @onInput={{this.setMixed}}
+        />
+        <Args.Bool
+          @name='modified'
+          @defaultValue={{false}}
+          @value={{this.modified}}
+          @description='Differs from default. Reveals the reset control (or an accessible dot when no @onReset is given).'
+          @onInput={{this.setModified}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @defaultValue={{false}}
+          @value={{this.disabled}}
+          @description='Dims the row and marks it aria-disabled; the control itself is the caller’s to disable.'
+          @onInput={{this.setDisabled}}
+        />
+        <Args.String
+          @name='labelWidth'
+          @description='Label column width in row layout. Validated against a length whitelist before it reaches CSS — a caller string can never become a declaration.'
+        />
+        <Args.Action
+          @name='onReset'
+          @description='Invoked by the reset control.'
+        />
+        <Args.Yield
+          @description='Default block yields (controlId, hintId). Named blocks: label (replaces the text label with a control) and actions (trailing affordances).'
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-property-demo {
+        max-width: 300px;
+        container-type: inline-size;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_PROPERTY_ROW: Record<string, unknown> = {
+  PropertyRow: PropertyRowUsage,
+};

package/bundled-realms/pretui/components/property-sheet.gts

@@ -0,0 +1,133 @@
+// Pretui — PropertySheet: a sheet of ValueInputs driven by a spec list.
+import Component from '@glimmer/component';
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { PropertyRow } from './property-row';
+import type { PropertyRowSignature } from './property-row';
+import { ValueInput } from './value-input';
+import type { ValueKind, ValueOf, ValueSpec } from './value-input';
+
+// ═══════════════════════════════════════════════════════════════════════
+// PropertySheet
+// ═══════════════════════════════════════════════════════════════════════
+
+export interface PropertySheetSignature {
+  Args: {
+    /** the rows, in order */
+    specs: ValueSpec[];
+    /** current values, keyed by `spec.key` */
+    values: Record<string, ValueOf>;
+    /** default row layout (each spec may override) */
+    layout?: PropertyRowSignature['Args']['layout'];
+    disabled?: boolean;
+    onChange?: (key: string, value: ValueOf) => void;
+    /** invoked by a row's reset control; the row only shows one when the
+     * spec is `modified` AND this is supplied */
+    onReset?: (key: string) => void;
+  };
+  Blocks: {
+    custom: [ValueKind, ValueOf, ValueSpec, boolean];
+  };
+  Element: HTMLDivElement;
+}
+
+/**
+ * A property panel rendered from data.
+ *
+ * The point is not brevity — it is that a panel defined as `ValueSpec[]` can
+ * come from a card schema, a plugin manifest or a diffing multi-selection,
+ * and still get every affordance the hand-written rows have: labels wired to
+ * controls, hints wired to `aria-describedby`, mixed state as text, reset
+ * where a value differs from its default, and the container-query fold.
+ */
+export const PropertySheet: TemplateOnlyComponent<PropertySheetSignature> = <template>
+    <div class='pretui-sheet' data-test-pretui-property-sheet ...attributes>
+      {{#each @specs key='key' as |spec|}}
+        <PropertySheetRow
+          @spec={{spec}}
+          @value={{get @values spec.key}}
+          @layout={{if spec.layout spec.layout @layout}}
+          @disabled={{@disabled}}
+          @onChange={{@onChange}}
+          @onReset={{@onReset}}
+        >
+          <:custom as |kind value disabled|>
+            {{yield kind value spec disabled to='custom'}}
+          </:custom>
+        </PropertySheetRow>
+      {{/each}}
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-sheet {
+          display: grid;
+          gap: 1px;
+          min-width: 0;
+        }
+      }
+    </style>
+</template>;
+
+/** Index into the values record without a helper import. */
+function get(record: Record<string, ValueOf> | undefined, key: string): ValueOf {
+  return record ? record[key] : undefined;
+}
+
+// ── One sheet row ────────────────────────────────────────────────────────
+// A child component so each row owns stable bound handlers. `(fn this.emit
+// spec.key)` inside the loop would allocate a fresh closure every render,
+// which is the modifier-retracking trap the workspace learnings document.
+
+interface PropertySheetRowSignature {
+  Args: {
+    spec: ValueSpec;
+    value: ValueOf;
+    layout?: PropertyRowSignature['Args']['layout'];
+    disabled?: boolean;
+    onChange?: (key: string, value: ValueOf) => void;
+    onReset?: (key: string) => void;
+  };
+  Blocks: { custom: [ValueKind, ValueOf, boolean] };
+  Element: HTMLDivElement;
+}
+
+class PropertySheetRow extends Component<PropertySheetRowSignature> {
+  get disabled(): boolean {
+    return this.args.disabled || this.args.spec.disabled || false;
+  }
+  get resettable(): (() => void) | undefined {
+    return this.args.onReset ? this.reset : undefined;
+  }
+  change = (value: ValueOf) => {
+    this.args.onChange?.(this.args.spec.key, value);
+  };
+  reset = () => {
+    this.args.onReset?.(this.args.spec.key);
+  };
+  <template>
+    <PropertyRow
+      @label={{@spec.label}}
+      @hint={{@spec.hint}}
+      @layout={{@layout}}
+      @mixed={{@spec.mixed}}
+      @modified={{@spec.modified}}
+      @disabled={{this.disabled}}
+      @onReset={{this.resettable}}
+      ...attributes
+      as |controlId hintId|
+    >
+      <ValueInput
+        @kind={{@spec.kind}}
+        @value={{@value}}
+        @spec={{@spec}}
+        @controlId={{controlId}}
+        @describedBy={{hintId}}
+        @disabled={{this.disabled}}
+        @onChange={{this.change}}
+      >
+        <:custom as |kind value disabled|>
+          {{yield kind value disabled to='custom'}}
+        </:custom>
+      </ValueInput>
+    </PropertyRow>
+  </template>
+}