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

package/bundled-realms/pretui/components/rating.gts

@@ -0,0 +1,266 @@
+// Pretui — Rating: score as a row of selectable symbols. Ported from
+// Web Awesome's wa-rating (MIT, (c) Fonticons), re-cut on Pretui bones.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { htmlSafe } from '@ember/template';
+import { cssStyle } from '../pretui-css';
+import { emit, firstDefined } from '../pretui-primitives';
+import type { ControlNotifyArgs } from '../pretui-primitives';
+
+
+// Rating — ported from Web Awesome's wa-rating (MIT, (c) Fonticons) as the
+// harmonization pilot: WA's semantic surface (precision, hover preview,
+// click-to-clear, slider keyboard model) re-cut on Pretui bones. WA's
+// --symbol-* knobs become --pretui-rating-*; the active color obeys Law 2
+// (one hue in). Wave-0 adaptations: LTR only, and no pointer-capture touch
+// scrubbing (lint forbids pointer-down bindings) — tap/hover/keyboard carry
+// the interaction; both noted for the polish pass.
+export interface RatingSignature {
+  Args: ControlNotifyArgs<number> & {
+    value?: number;
+    defaultValue?: number;
+    max?: number;
+    precision?: number;
+    readonly?: boolean;
+    disabled?: boolean;
+    label?: string;
+    hue?: string;
+    onHover?: (phase: 'start' | 'move' | 'end', value: number) => void;
+    /** aliases — React Aria / HTML boolean spellings */
+    isReadOnly?: boolean;
+    readOnly?: boolean;
+    isDisabled?: boolean;
+  };
+  Element: HTMLDivElement;
+}
+
+interface RatingSymbol {
+  frac: number;
+  hover: boolean;
+  clipStyle: ReturnType<typeof htmlSafe> | undefined;
+}
+
+export class Rating extends Component<RatingSignature> {
+  @tracked internal = this.args.defaultValue ?? 0;
+  @tracked hoverValue = 0;
+  @tracked isHovering = false;
+
+  get value() {
+    return this.args.value ?? this.internal;
+  }
+  get max() {
+    return this.args.max ?? 5;
+  }
+  get precision() {
+    return this.args.precision ?? 1;
+  }
+  get disabled() {
+    return firstDefined(this.args.disabled, this.args.isDisabled) ?? false;
+  }
+  get readonly() {
+    return (
+      firstDefined(
+        this.args.readonly,
+        this.args.isReadOnly,
+        this.args.readOnly,
+      ) ?? false
+    );
+  }
+  get interactive() {
+    return !this.disabled && !this.readonly;
+  }
+  get displayValue() {
+    return this.interactive && this.isHovering ? this.hoverValue : this.value;
+  }
+  get hueStyle() {
+    // `@hue` is a caller string reaching an inline style — validated against
+    // the kit allowlist so it cannot carry its own declarations.
+    return cssStyle('--pretui-rating-hue', this.args.hue);
+  }
+  get symbols(): RatingSymbol[] {
+    let d = this.displayValue;
+    return Array.from({ length: this.max }, (_v, i) => {
+      let frac = Math.min(Math.max(d - i, 0), 1);
+      return {
+        frac,
+        hover: this.isHovering && Math.ceil(d) === i + 1,
+        clipStyle:
+          frac > 0 && frac < 1
+            ? htmlSafe(`clip-path: inset(0 ${(100 - frac * 100).toFixed(1)}% 0 0)`)
+            : undefined,
+      };
+    });
+  }
+
+  private roundToPrecision(n: number) {
+    let m = 1 / this.precision;
+    return Math.ceil(n * m) / m;
+  }
+  private valueFromX(el: HTMLElement, clientX: number) {
+    let { left, width } = el.getBoundingClientRect();
+    let raw = this.roundToPrecision(((clientX - left) / width) * this.max);
+    return Math.min(Math.max(raw, 0), this.max);
+  }
+  private commit(v: number) {
+    // Clicking the current value clears the rating — the WA toggle semantic.
+    let next = v === this.value ? 0 : v;
+    if (this.args.value === undefined) {
+      this.internal = next;
+    }
+    this.isHovering = false;
+    emit([this.args.onValueChange, this.args.onChange], next);
+  }
+
+  handleClick = (e: Event) => {
+    if (!this.interactive) return;
+    let ev = e as MouseEvent;
+    this.commit(this.valueFromX(ev.currentTarget as HTMLElement, ev.clientX));
+  };
+  handleKeyDown = (e: Event) => {
+    if (!this.interactive) return;
+    let ev = e as KeyboardEvent;
+    let step = ev.shiftKey ? 1 : this.precision;
+    let next: number | undefined;
+    if (ev.key === 'ArrowDown' || ev.key === 'ArrowLeft') {
+      next = Math.max(0, this.value - step);
+    } else if (ev.key === 'ArrowUp' || ev.key === 'ArrowRight') {
+      next = Math.min(this.max, this.value + step);
+    } else if (ev.key === 'Home') {
+      next = 0;
+    } else if (ev.key === 'End') {
+      next = this.max;
+    }
+    if (next !== undefined) {
+      ev.preventDefault();
+      if (next !== this.value) {
+        if (this.args.value === undefined) {
+          this.internal = next;
+        }
+        emit([this.args.onValueChange, this.args.onChange], next);
+      }
+    }
+  };
+  handlePointerEnter = (e: Event) => {
+    if (!this.interactive) return;
+    let ev = e as PointerEvent;
+    this.isHovering = true;
+    this.hoverValue = this.valueFromX(ev.currentTarget as HTMLElement, ev.clientX);
+    this.args.onHover?.('start', this.hoverValue);
+  };
+  handlePointerMove = (e: Event) => {
+    if (!this.interactive) return;
+    let ev = e as PointerEvent;
+    let v = this.valueFromX(ev.currentTarget as HTMLElement, ev.clientX);
+    if (v !== this.hoverValue) {
+      this.hoverValue = v;
+      this.args.onHover?.('move', v);
+    }
+  };
+  handlePointerLeave = () => {
+    if (!this.interactive) return;
+    this.isHovering = false;
+    this.args.onHover?.('end', this.hoverValue);
+  };
+  <template>
+    <div
+      class='pretui-rating'
+      role='slider'
+      tabindex={{if this.interactive '0' '-1'}}
+      aria-label={{if @label @label 'Rating'}}
+      aria-valuemin='0'
+      aria-valuemax={{this.max}}
+      aria-valuenow={{this.value}}
+      aria-disabled={{if this.disabled 'true' 'false'}}
+      aria-readonly={{if this.readonly 'true' 'false'}}
+      data-disabled={{if this.disabled 'true'}}
+      data-readonly={{if this.readonly 'true'}}
+      data-test-pretui-rating
+      style={{this.hueStyle}}
+      {{on 'click' this.handleClick}}
+      {{on 'keydown' this.handleKeyDown}}
+      {{on 'pointerenter' this.handlePointerEnter}}
+      {{on 'pointermove' this.handlePointerMove}}
+      {{on 'pointerleave' this.handlePointerLeave}}
+      ...attributes
+    >
+      {{#each this.symbols as |s|}}
+        <span
+          class='pretui-rating-symbol'
+          data-hover={{if s.hover 'true'}}
+          aria-hidden='true'
+        >
+          <svg class='pretui-rating-base' viewBox='0 0 24 24' role='presentation'>
+            <path
+              role='presentation'
+              d='M12 17.75l-6.172 3.245 1.179-6.873-5-4.867 6.9-1 3.093-6.253 3.093 6.253 6.9 1-5 4.867 1.179 6.873z'
+            />
+          </svg>
+          {{#if s.frac}}
+            <svg
+              class='pretui-rating-fill'
+              viewBox='0 0 24 24'
+              role='presentation'
+              style={{s.clipStyle}}
+            >
+              <path
+                role='presentation'
+                d='M12 17.75l-6.172 3.245 1.179-6.873-5-4.867 6.9-1 3.093-6.253 3.093 6.253 6.9 1-5 4.867 1.179 6.873z'
+              />
+            </svg>
+          {{/if}}
+        </span>
+      {{/each}}
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-rating {
+          display: inline-flex;
+          gap: var(--pretui-rating-gap, 2px);
+          cursor: pointer;
+          outline-offset: 4px;
+          border-radius: 4px;
+        }
+        .pretui-rating[data-readonly],
+        .pretui-rating[data-disabled] {
+          cursor: default;
+        }
+        .pretui-rating[data-disabled] {
+          opacity: 0.45;
+        }
+        .pretui-rating-symbol {
+          position: relative;
+          display: inline-grid;
+          width: var(--pretui-rating-size, 18px);
+          height: var(--pretui-rating-size, 18px);
+          transition: transform 120ms ease;
+        }
+        .pretui-rating-symbol[data-hover='true'] {
+          transform: scale(1.12);
+        }
+        .pretui-rating-symbol svg {
+          grid-area: 1 / 1;
+          width: 100%;
+          height: 100%;
+        }
+        .pretui-rating-base {
+          fill: none;
+          stroke: var(--pretui-rating-track, var(--line-strong, var(--boxel-400)));
+          stroke-width: 1.5;
+          stroke-linejoin: round;
+        }
+        .pretui-rating-fill {
+          fill: var(--pretui-rating-hue, var(--warning, var(--boxel-warning)));
+          stroke: var(--pretui-rating-hue, var(--warning, var(--boxel-warning)));
+          stroke-width: 1.5;
+          stroke-linejoin: round;
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-rating-symbol {
+            transition: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,55 @@
+## What it is
+
+A star (or arbitrary symbol) rating, either as an interactive control or a read-only display. Reach for it when a bounded, small-integer score is a familiar shorthand — reviews, quality flags, priority. If the score is not conventionally a star scale, use **Meter** or **Delta**; if it is a display-only value in a table, plain text or a **Chip** reads faster and costs nothing. For a general bounded number picker use **Slider**.
+
+## The contract
+
+```
+@value?, @defaultValue?, @max? (5), @precision? (1), @label?
+@readonly?, @disabled?, @hue?
+@onValueChange?(value: number), @onHover?(phase: 'start'|'move'|'end', value: number)
+```
+
+Hybrid controlled/uncontrolled, the kit-wide idiom.
+
+**`@precision` produces fractional symbols by clip-path, not by extra elements.** A symbol whose fraction is between 0 and 1 gets `clip-path: inset(0 X% 0 0)` over a filled copy, so half stars are one CSS declaration rather than a second overlay layer per star.
+
+**Hover is a separate display channel.** The hovered value and the hovering flag are tracked internally, independently of `@value`, and `displayValue` prefers the hover value only while interactive and hovering — so the preview never mutates state. `@onHover` reports `start`/`move`/`end` with the previewed value, which is what lets a call site show "3 — Good" beside the stars without owning the pointer maths.
+
+**Clicking the current value clears the rating** (`v === value ? 0 : v`). That is Web Awesome's toggle semantic, adopted deliberately: without it a five-star scale has no way back to "unrated".
+
+Value comes from pointer X against the element's `getBoundingClientRect`, rounded up to the nearest `precision` step and clamped — so the whole control is one hit target rather than `max` separate buttons.
+
+## Prior art
+
+APG ships **two** reference examples and they disagree by design: `radio-rating` (a radio group, recommended for seven or fewer discrete values, with free form semantics) and `slider-rating` (recommended for granular scales, and the example that exists specifically to demonstrate `aria-valuetext` — "3 of 5 stars").
+
+**Web Awesome `wa-rating`** takes the slider route: `role = 'slider'` is a _reactive property_ so a caller can override it, the host carries `aria-valuenow`/`valuemin=0`/`valuemax`/`aria-disabled`/`aria-readonly`/`aria-label`, each symbol is `role="presentation"`, and it offers `precision` (fractional stars via clip-path layers), `max`, `readonly`, and a `getSymbol(value, isSelected) => string` HTML hook. **React Spectrum** ships no rating.
+
+Pretui follows Web Awesome closely — `role="slider"`, clip-path fractions, the click-to-clear toggle — which is the right call for `@precision < 1`, where a radio group cannot express half values.
+
+Where Pretui improves: `@onHover` with an explicit three-phase signal is a cleaner contract than reading pointer events at the call site, and the hue escape (`--pretui-rating-hue` set from `@hue`) lets a call site tint a rating per row — a status-coloured rating in a table — without a variant explosion.
+
+Where it is behind: no `getSymbol` equivalent, so the symbol is fixed; and `tabindex` is `-1` when read-only, which removes display ratings from the tab order but leaves them as `role="slider"` — a read-only display would be better as plain text or `role="img"` with a label.
+
+## Accessibility
+
+Governing pattern: APG **Slider** (the `slider-rating` variant). This is one of the better-implemented controls in the kit:
+
+- Present and correct: `role="slider"`, `aria-valuemin="0"`, `aria-valuemax`, `aria-valuenow`, `aria-disabled`, `aria-readonly`, `aria-label` (defaulting to `'Rating'`), `tabindex="0"` when interactive.
+- Keyboard: ArrowLeft/ArrowDown decrement, ArrowRight/ArrowUp increment, Home → 0, End → max, all with `preventDefault`. **Shift+Arrow steps by a whole unit** rather than by `@precision`, which is a nice inversion of the usual Shift-means-bigger convention and exactly right for half stars.
+
+Gaps:
+
+- **No `aria-valuetext`.** This is the specific thing the APG `slider-rating` example exists to demonstrate: the control announces "3" where it should announce "3 of 5 stars", and with `@precision` of 0.5 it announces "2.5". Given that Pretui otherwise follows the slider-rating pattern closely, this omission is conspicuous and is the single highest-value fix.
+- **No Page Up/Page Down.** Optional in APG, but Shift+Arrow covers the same need here.
+- **`@label` defaults to `'Rating'`** — two ratings in a list are both announced identically.
+- **A read-only rating is still `role="slider"` with `tabindex="-1"`.** It is announced as a slider that cannot be reached, which is worse than announcing it as text. Display ratings should drop the role.
+- **The whole control is one pointer target**, so there are no per-star targets to fail WCAG 2.5.8 — but equally there is no way to select a value by pointer other than aiming within a `(1/max)` fraction of the width. On a small rating that is a narrow target.
+- No `forced-colors` treatment for the clip-path fills.
+
+## Theming
+
+`--pretui-rating-hue` (set per instance from `@hue`), plus the kit's ink and control tokens for the empty symbol. Theme authors should define a default rating hue that reads at small sizes against both `--card` and `--canvas` — a mid-yellow that works on white commonly disappears on a light panel.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,96 @@
+// Pretui — Rating usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Rating } from './rating';
+import { Token } from './token';
+
+const PRECISIONS = ['1', '0.5'];
+
+export class RatingUsage extends GlimmerComponent {
+  @tracked value = 3.5;
+  @tracked precision = '0.5';
+  @tracked max = 5;
+  @tracked readonly = false;
+  @tracked disabled = false;
+  onChange = (v: number) => (this.value = v);
+  setPrecision = (v: string) => (this.precision = v);
+  setMax = (v: number | null) => (this.max = v ?? 5);
+  setReadonly = (v: boolean) => (this.readonly = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  get precisionVal() {
+    return Number(this.precision);
+  }
+  get valueText() {
+    return String(this.value);
+  }
+  get usage() {
+    return `<Rating @value={{${this.value}}} @precision={{${this.precision}}} @max={{${this.max}}} @onValueChange={{this.onChange}} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Rating'
+      @description='Score as a row of selectable symbols. Ported from Web Awesome (MIT): half-symbol precision via clip-path, hover preview, click-to-clear, slider keyboard model (arrows step by precision, Shift for whole steps, Home/End). The specimen is its own knob.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <Rating
+          @value={{this.value}}
+          @precision={{this.precisionVal}}
+          @max={{this.max}}
+          @readonly={{this.readonly}}
+          @disabled={{this.disabled}}
+          @label='Demo rating'
+          @onValueChange={{this.onChange}}
+        />
+        <Token @value={{this.valueText}} />
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='precision'
+          @value={{this.precision}}
+          @options={{PRECISIONS}}
+          @defaultValue='1'
+          @description='The increment the rating moves by — 0.5 allows half-star ratings (rendered via clip-path).'
+          @onInput={{this.setPrecision}}
+        />
+        <Args.Number
+          @name='max'
+          @value={{this.max}}
+          @min={{3}}
+          @max={{10}}
+          @defaultValue={{5}}
+          @description='The highest rating to show.'
+          @onInput={{this.setMax}}
+        />
+        <Args.Bool
+          @name='readonly'
+          @value={{this.readonly}}
+          @defaultValue={{false}}
+          @description='Displays the value without accepting interaction.'
+          @onInput={{this.setReadonly}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @value={{this.disabled}}
+          @defaultValue={{false}}
+          @description='Disables the rating.'
+          @onInput={{this.setDisabled}}
+        />
+        <Args.Action
+          @name='onValueChange'
+          @description='Called with the committed value; clicking the current value clears to 0 (the Web Awesome toggle semantic).'
+        />
+        <Args.Action
+          @name='onHover'
+          @description="Called with ('start'|'move'|'end', value) as the pointer previews a value."
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+
+export const DEMOS_RATING: Record<string, unknown> = {
+  Rating: RatingUsage,
+};