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

package/bundled-realms/pretui/components/password-strength.usage.gts

@@ -0,0 +1,34 @@
+// Pretui — PasswordStrength usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { PasswordStrength } from './password-strength';
+
+class PasswordStrengthUsage extends Component {
+  @tracked score = 2;
+  suggestions = ['Use four or more unrelated words.', 'Avoid supplier names and lot numbers.'];
+  setScore = (score: number | null) => (this.score = score ?? 0);
+  <template>
+    <FreestyleUsage
+      @name='PasswordStrength'
+      @description='An advisory meter over an external estimator result. It reports settled strength in text and never gates submission.'
+      @source='<PasswordStrength @score="2" @warning="Predictable phrase" … />'
+    >
+      <:example>
+        <PasswordStrength @score={{this.score}} @warning='Predictable phrase' @suggestions={{this.suggestions}} @crackTime='3 hours' @hideWhenEmpty={{false}} />
+      </:example>
+      <:api as |Args|>
+        <Args.Number @name='score' @value={{this.score}} @min={{0}} @max={{4}} @step={{1}} @onInput={{this.setScore}} />
+        <Args.String @name='warning' @value='Predictable phrase' />
+        <Args.Object @name='suggestions' @value={{this.suggestions}} />
+        <Args.String @name='crackTime' @value='3 hours' />
+        <Args.Bool @name='busy' @defaultValue={{false}} />
+        <Args.Bool @name='hideWhenEmpty' @defaultValue={{true}} />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_PASSWORD_STRENGTH: Record<string, unknown> = {
+  PasswordStrength: PasswordStrengthUsage,
+};

package/bundled-realms/pretui/components/path-text.gts

@@ -0,0 +1,288 @@
+// Pretui — PathText: text set along an SVG path — a circle, an arc, a wave.
+import Component from '@glimmer/component';
+import { htmlSafe } from '@ember/template';
+import { guidFor } from '@ember/object/internals';
+import { cssStyleFrom, cssValue } from '../pretui-css';
+
+// ═══════════════════════════════════════════════════════════════════════
+// PathText
+// ═══════════════════════════════════════════════════════════════════════
+
+/** The built-in paths. `custom` uses `@path`. */
+export type PathTextShape = 'circle' | 'arc' | 'wave' | 'custom';
+
+/** Path data may only contain command letters, numbers and separators.
+ * An allowlist, not a sanitiser: a `d` that contains anything else is
+ * dropped whole and the preset shape is drawn instead, so a rejected value
+ * costs the caller their override and never the component's rendering.
+ * (Same discipline as `cssValue` in pretui-css.gts, applied to the one
+ * caller string in this module that reaches an SVG attribute.) */
+const PATH_DATA = /^[MmLlHhVvCcSsQqTtAaZz0-9eE ,.+-]{1,2048}$/;
+
+/** Validate caller-supplied path data. */
+export function safePathData(raw: unknown): string | undefined {
+  if (typeof raw !== 'string') {
+    return undefined;
+  }
+  let value = raw.trim();
+  if (value.length === 0 || !PATH_DATA.test(value)) {
+    return undefined;
+  }
+  return value;
+}
+
+/** A circle path drawn as two arcs, starting at the top and running
+ * clockwise — the orientation that puts the first character at 12 o'clock,
+ * which is where a reader looks first. */
+export function circlePath(size: number, radius: number): string {
+  let centre = size / 2;
+  let top = centre - radius;
+  return (
+    'M ' + centre + ' ' + top +
+    ' a ' + radius + ' ' + radius + ' 0 1 1 -0.01 0' +
+    ' a ' + radius + ' ' + radius + ' 0 1 1 0.01 0'
+  );
+}
+
+/** A shallow upward arc across the box — the "banner" shape. */
+export function arcPath(size: number, radius: number): string {
+  let inset = size * 0.08;
+  let baseline = size * 0.72;
+  let sweep = Math.max(radius, size * 0.4);
+  return (
+    'M ' + inset + ' ' + baseline +
+    ' A ' + sweep + ' ' + sweep + ' 0 0 1 ' + (size - inset) + ' ' + baseline
+  );
+}
+
+/** One period of a sine-ish wave, drawn with two cubic segments. */
+export function wavePath(size: number, amplitude: number): string {
+  let middle = size / 2;
+  let quarter = size / 4;
+  return (
+    'M 0 ' + middle +
+    ' C ' + quarter + ' ' + (middle - amplitude) + ', ' + quarter + ' ' + (middle - amplitude) + ', ' + middle + ' ' + middle +
+    ' S ' + (size - quarter) + ' ' + (middle + amplitude) + ', ' + size + ' ' + middle
+  );
+}
+
+export interface PathTextSignature {
+  Args: {
+    /** the string to set along the path. It is the SVG's accessible name;
+     * the glyphs themselves are presentation, so a repeated ring is not read
+     * out three times. */
+    text: string;
+    /** which path (default 'circle') */
+    shape?: PathTextShape;
+    /** SVG path data for `@shape='custom'`. Validated against an allowlist;
+     * anything unrecognised falls back to the circle. */
+    path?: string;
+    /** the square viewBox edge (default 240). The SVG scales to its box —
+     * this only sets the coordinate space the geometry is expressed in. */
+    size?: number;
+    /** circle / arc radius (default 40% of size) */
+    radius?: number;
+    /** wave height (default 12% of size) */
+    amplitude?: number;
+    /** where along the path the text starts, in percent (default 0) */
+    offset?: number;
+    /** repeat the string around the path this many times (default 1) */
+    repeat?: number;
+    /** what separates the repeats (default a spaced middot) */
+    separator?: string;
+    /** glyph size in viewBox units (default 6% of size) */
+    fontSize?: number;
+    /** extra tracking in viewBox units */
+    tracking?: number;
+    /** fill colour. A caller string, so it goes through the kit's `cssValue`
+     * allowlist before it is written. */
+    fill?: string;
+    /** rotate the whole ring. See the Law 5 note at the top of this module:
+     * OFF by default, only meaningful for the closed shapes, and only
+     * legitimate when something ongoing is being reported — pair it with a
+     * text affordance saying what. */
+    travel?: boolean;
+    /** seconds for one full turn (default 14) */
+    revolution?: number;
+    /** which way it turns (default 'cw') */
+    direction?: 'cw' | 'ccw';
+  };
+  Element: HTMLSpanElement;
+}
+
+export class PathText extends Component<PathTextSignature> {
+  private guid = guidFor(this);
+
+  get size(): number {
+    let raw = this.args.size;
+    return raw !== undefined && Number.isFinite(raw) && raw > 0 ? raw : 240;
+  }
+  get shape(): PathTextShape {
+    return this.args.shape ?? 'circle';
+  }
+  get radius(): number {
+    let raw = this.args.radius;
+    if (raw !== undefined && Number.isFinite(raw) && raw > 0) {
+      return raw;
+    }
+    return this.size * 0.4;
+  }
+  get amplitude(): number {
+    let raw = this.args.amplitude;
+    if (raw !== undefined && Number.isFinite(raw) && raw > 0) {
+      return raw;
+    }
+    return this.size * 0.12;
+  }
+  get pathData(): string {
+    if (this.shape === 'custom') {
+      let supplied = safePathData(this.args.path);
+      if (supplied) {
+        return supplied;
+      }
+    }
+    if (this.shape === 'arc') {
+      return arcPath(this.size, this.radius);
+    }
+    if (this.shape === 'wave') {
+      return wavePath(this.size, this.amplitude);
+    }
+    return circlePath(this.size, this.radius);
+  }
+  get pathId(): string {
+    return this.guid + '-path';
+  }
+  get pathHref(): string {
+    return '#' + this.pathId;
+  }
+  get viewBox(): string {
+    return '0 0 ' + this.size + ' ' + this.size;
+  }
+  get startOffset(): string {
+    let raw = this.args.offset;
+    let value = raw !== undefined && Number.isFinite(raw) ? raw : 0;
+    return value.toFixed(2) + '%';
+  }
+  /** The string as it is actually drawn: the caller's text repeated, joined
+   * by the separator. A single repeat is the common case and adds nothing. */
+  get drawn(): string {
+    let text = this.args.text ?? '';
+    let raw = this.args.repeat;
+    let times =
+      raw !== undefined && Number.isFinite(raw) && raw >= 1
+        ? Math.min(24, Math.trunc(raw))
+        : 1;
+    if (times <= 1) {
+      return text;
+    }
+    let separator = this.args.separator ?? ' · ';
+    let pieces: string[] = [];
+    for (let i = 0; i < times; i++) {
+      pieces.push(text);
+    }
+    return pieces.join(separator) + separator;
+  }
+  /** Travel is honoured only where a rotation is truthful: rotating the
+   * group of an arc or a wave rotates the SHAPE too, which is a different
+   * (and wrong) picture. Named, not silently ignored. */
+  get travelling(): boolean {
+    if (!this.args.travel) {
+      return false;
+    }
+    return this.shape === 'circle' || this.shape === 'custom';
+  }
+  get textStyle() {
+    let size = this.args.fontSize;
+    let resolved =
+      size !== undefined && Number.isFinite(size) && size > 0
+        ? size
+        : this.size * 0.06;
+    let tracking = this.args.tracking;
+    let track =
+      tracking !== undefined && Number.isFinite(tracking) ? tracking : 0;
+    return cssStyleFrom([
+      'font-size: ' + resolved.toFixed(2) + 'px',
+      'letter-spacing: ' + track.toFixed(2) + 'px',
+      // The one caller STRING that reaches CSS in this module. Guarded.
+      this.args.fill === undefined
+        ? undefined
+        : cssValue(this.args.fill) === undefined
+          ? undefined
+          : 'fill: ' + cssValue(this.args.fill),
+    ]);
+  }
+  get spinStyle() {
+    let raw = this.args.revolution;
+    let seconds =
+      raw !== undefined && Number.isFinite(raw) && raw > 0 ? raw : 14;
+    return htmlSafe('--pretui-pathtext-revolution: ' + seconds.toFixed(2) + 's');
+  }
+  <template>
+    <span class='pretui-pathtext' data-test-pretui-path-text ...attributes>
+      <svg
+        class='pretui-pathtext-svg'
+        viewBox={{this.viewBox}}
+        role='img'
+        aria-label={{@text}}
+        data-travel={{if this.travelling 'true'}}
+        data-direction={{if @direction @direction 'cw'}}
+        style={{this.spinStyle}}
+      >
+        <defs>
+          <path id={{this.pathId}} d={{this.pathData}} fill='none' />
+        </defs>
+        <g class='pretui-pathtext-spin'>
+          <text class='pretui-pathtext-text' style={{this.textStyle}}>
+            <textPath href={{this.pathHref}} startOffset={{this.startOffset}}>
+              {{this.drawn}}
+            </textPath>
+          </text>
+        </g>
+      </svg>
+    </span>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-pathtext {
+          display: inline-block;
+          line-height: 0;
+        }
+        .pretui-pathtext-svg {
+          display: block;
+          width: 100%;
+          height: auto;
+          overflow: visible;
+        }
+        .pretui-pathtext-text {
+          fill: var(--pretui-pathtext-fill, var(--foreground));
+          font-family: var(--font-sans);
+          font-weight: var(--weight-medium, 500);
+        }
+        /* The resting state is the finished picture: the ring is fully drawn,
+           fully legible, and passes the screenshot test with the animation
+           removed. Rotation only says "this is ongoing". */
+        .pretui-pathtext-spin {
+          transform-box: view-box;
+          transform-origin: 50% 50%;
+        }
+        @keyframes pretui-pathtext-turn {
+          to {
+            rotate: 360deg;
+          }
+        }
+        .pretui-pathtext-svg[data-travel='true'] .pretui-pathtext-spin {
+          animation: pretui-pathtext-turn
+            var(--pretui-pathtext-revolution, 14s) linear infinite;
+        }
+        .pretui-pathtext-svg[data-travel='true'][data-direction='ccw']
+          .pretui-pathtext-spin {
+          animation-direction: reverse;
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-pathtext-spin {
+            animation: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/path-text.md

@@ -0,0 +1,58 @@
+## What it is
+
+Text set along an SVG path — a circle, an arc, a wave, or a path you supply — optionally travelling around it.
+
+At rest this is a **layout** capability rather than motion. It lives in the motion territory because that is where the catalog files it.
+
+## The contract
+
+```
+@text (required) — the string to set along the path; it is the SVG's accessible name
+@shape?          — which path. Default 'circle'
+@path?           — SVG path data for @shape='custom'; validated against an allowlist,
+                   and anything unrecognised falls back to the circle
+@size?           — the square viewBox edge. Default 240
+@radius?         — circle / arc radius. Default 40% of size
+@amplitude?      — wave height. Default 12% of size
+@offset?         — where along the path the text starts, in percent. Default 0
+@repeat?         — repeat the string around the path. Default 1
+@separator?      — what separates the repeats. Default a spaced middot
+@fontSize?       — glyph size in viewBox units. Default 6% of size
+@tracking?       — extra tracking in viewBox units
+@fill?           — fill colour; goes through the kit's cssValue allowlist
+@travel?         — rotate the whole ring. OFF by default
+@revolution?     — seconds for one full turn. Default 14
+@direction?      — 'cw' (default) | 'ccw'
+```
+
+**It uses `textPath`, so the glyphs keep real shaping** — kerning, ligatures, the actual typeface — rather than being individually positioned characters.
+
+**`@size` sets the coordinate space, not the rendered size.** The SVG scales to its box; `@size` only decides what units the geometry is expressed in.
+
+**A custom `@path` is validated against an allowlist** and falls back to the circle rather than being written through.
+
+**`@travel` defaults to off, and that is a rule rather than a preference.** Rotation reads as "something is ongoing". It is honored only for the closed shapes, and when it is on it must be paired with a text affordance saying _what_ is ongoing — it is never the only carrier of that fact.
+
+## Prior art
+
+**react-bits' CircularText** and **CurvedLoop**, **fancy's TextAlongPath**, and **motion-primitives' SpinningText**.
+
+Where Pretui is better: **the ring has an accessible name and the glyphs are presentation**, so a string repeated three times around a circle is read once rather than three times — which is exactly what the upstream components get wrong, because repeating the text is how they fill the path. The custom path is also validated rather than interpolated, and `@travel` is off by default where every upstream spins by default.
+
+Where it is thinner: four shapes plus an allowlisted custom path, no per-glyph effects, no text that reflows to fit the path automatically — if the string is longer than the path it overruns — and no vertical or 3D variants.
+
+## Accessibility
+
+- **The SVG is `role='img'` with `aria-label` from `@text`.** The glyphs themselves are presentation, which is what stops a repeated ring being announced several times.
+- **`@travel` is the borderline case and it is legislated rather than left to taste.** Off by default; on only where rotating is truthful; and never the sole indication that something is ongoing, because a screen-reader user cannot perceive rotation at all.
+- **Reduced motion lands on the end state** — a still ring — rather than a frozen midpoint of a revolution.
+- **Curved text is harder to read for everyone**, and substantially harder with dyslexia or low vision. Keep it short and never put anything a reader must act on in it.
+- **`@repeat` repeats the visual only.** The accessible name stays the single string.
+
+## Theming
+
+`--pretui-pathtext-fill` (from `@fill`, through the CSS guard) and `--pretui-pathtext-revolution` (from `@revolution`).
+
+Everything else is geometry expressed in viewBox units and passed as args, because a ring's proportions belong to the composition rather than to the theme. The fill defaults to `currentColor`'s context, so a ring inherits the ink of whatever it sits in and a theme needs to do nothing.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/path-text.usage.gts

@@ -0,0 +1,239 @@
+// Pretui — PathText usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { PathText } from './path-text';
+
+// ── PathText ────────────────────────────────────────────────────────────
+class PathTextUsage extends Component {
+  @tracked text = 'Wuyishan · lot B-1181 · spring pick';
+  @tracked shape = 'circle';
+  @tracked size = 240;
+  @tracked radius = 92;
+  @tracked amplitude = 28;
+  @tracked offset = 0;
+  @tracked repeat = 1;
+  @tracked fontSize = 15;
+  @tracked tracking = 0.6;
+  @tracked travel = false;
+  @tracked revolution = 18;
+  @tracked direction = 'cw';
+
+  setText = (v: string) => (this.text = v);
+  setShape = (v: string) => (this.shape = v);
+  setSize = (v: number | null) => (this.size = v ?? 240);
+  setRadius = (v: number | null) => (this.radius = v ?? 92);
+  setAmplitude = (v: number | null) => (this.amplitude = v ?? 28);
+  setOffset = (v: number | null) => (this.offset = v ?? 0);
+  setRepeat = (v: number | null) => (this.repeat = v ?? 1);
+  setFontSize = (v: number | null) => (this.fontSize = v ?? 15);
+  setTracking = (v: number | null) => (this.tracking = v ?? 0.6);
+  setTravel = (v: boolean) => (this.travel = v);
+  setRevolution = (v: number | null) => (this.revolution = v ?? 18);
+  setDirection = (v: string) => (this.direction = v);
+
+  get shapeOptions(): string[] {
+    return ['circle', 'arc', 'wave'];
+  }
+  get directionOptions(): string[] {
+    return ['cw', 'ccw'];
+  }
+  get shapeArg(): 'circle' | 'arc' | 'wave' | 'custom' {
+    return this.shape as 'circle' | 'arc' | 'wave' | 'custom';
+  }
+  get directionArg(): 'cw' | 'ccw' {
+    return this.direction as 'cw' | 'ccw';
+  }
+  /** Law 6 in practice: travel says something is ongoing, and it may never be
+   * the only thing saying it. This is the text affordance beside it. */
+  get travelNote(): string {
+    if (!this.travel) {
+      return 'At rest. The ring is a layout capability, not motion.';
+    }
+    if (this.shape !== 'circle') {
+      return 'Travel is ignored on this shape — rotating an arc or a wave rotates the SHAPE, which is a different and wrong picture.';
+    }
+    return 'Turning: cupping in progress.';
+  }
+
+  get usage(): string {
+    return (
+      '<PathText @text=' + "'" + this.text + "'" +
+      " @shape='" + this.shape + "'" +
+      ' @radius={{' + this.radius + '}} @repeat={{' + this.repeat + '}}' +
+      (this.travel ? ' @travel={{true}}' : '') +
+      ' />'
+    );
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='PathText'
+      @description='Text set along an SVG path, using textPath so the glyphs keep real shaping and the SVG carries the string as its accessible name. At rest this is a LAYOUT capability rather than motion — it lives in the motion territory because that is where the catalog files it. Travel is the borderline case Law 6 legislates for: it reads as something is ongoing, so it defaults off, is honoured only where rotating the group is truthful, and must be paired with a text affordance saying what is ongoing.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='pretui-pt-demo'>
+          <PathText
+            class='pretui-pt-demo-art'
+            @text={{this.text}}
+            @shape={{this.shapeArg}}
+            @size={{this.size}}
+            @radius={{this.radius}}
+            @amplitude={{this.amplitude}}
+            @offset={{this.offset}}
+            @repeat={{this.repeat}}
+            @fontSize={{this.fontSize}}
+            @tracking={{this.tracking}}
+            @travel={{this.travel}}
+            @revolution={{this.revolution}}
+            @direction={{this.directionArg}}
+          />
+          <p class='pretui-pt-demo-note'>{{this.travelNote}}</p>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='text'
+          @required={{true}}
+          @value={{this.text}}
+          @description='The string to set along the path. It becomes the accessible name of the SVG; the glyphs are presentation, so a repeated ring is not read out three times.'
+          @onInput={{this.setText}}
+        />
+        <Args.String
+          @name='shape'
+          @value={{this.shape}}
+          @defaultValue='circle'
+          @options={{this.shapeOptions}}
+          @description='Which built-in path. custom takes SVG path data through the path argument, validated against an allowlist — an unrecognised d falls back to the circle rather than being written out.'
+          @onInput={{this.setShape}}
+        />
+        <Args.Number
+          @name='size'
+          @value={{this.size}}
+          @defaultValue={{240}}
+          @min={{120}}
+          @max={{400}}
+          @step={{20}}
+          @description='The square viewBox edge. The SVG scales to its box; this only sets the coordinate space.'
+          @onInput={{this.setSize}}
+        />
+        <Args.Number
+          @name='radius'
+          @value={{this.radius}}
+          @min={{30}}
+          @max={{180}}
+          @step={{2}}
+          @description='Circle and arc radius. Defaults to 40 percent of size.'
+          @onInput={{this.setRadius}}
+        />
+        <Args.Number
+          @name='amplitude'
+          @value={{this.amplitude}}
+          @min={{0}}
+          @max={{80}}
+          @step={{2}}
+          @description='Wave height. Defaults to 12 percent of size.'
+          @onInput={{this.setAmplitude}}
+        />
+        <Args.Number
+          @name='offset'
+          @value={{this.offset}}
+          @defaultValue={{0}}
+          @min={{0}}
+          @max={{100}}
+          @step={{1}}
+          @description='Where along the path the text starts, in percent.'
+          @onInput={{this.setOffset}}
+        />
+        <Args.Number
+          @name='repeat'
+          @value={{this.repeat}}
+          @defaultValue={{1}}
+          @min={{1}}
+          @max={{6}}
+          @step={{1}}
+          @description='Repeat the string around the path this many times, joined by the separator.'
+          @onInput={{this.setRepeat}}
+        />
+        <Args.Number
+          @name='fontSize'
+          @value={{this.fontSize}}
+          @min={{6}}
+          @max={{40}}
+          @step={{1}}
+          @description='Glyph size in viewBox units. Defaults to 6 percent of size.'
+          @onInput={{this.setFontSize}}
+        />
+        <Args.Number
+          @name='tracking'
+          @value={{this.tracking}}
+          @min={{-2}}
+          @max={{8}}
+          @step={{0.2}}
+          @description='Extra letter-spacing in viewBox units.'
+          @onInput={{this.setTracking}}
+        />
+        <Args.Bool
+          @name='travel'
+          @value={{this.travel}}
+          @defaultValue={{false}}
+          @description='Rotate the ring. Off by default, honoured only on closed shapes, and never the only carrier of the fact it reports.'
+          @onInput={{this.setTravel}}
+        />
+        <Args.Number
+          @name='revolution'
+          @value={{this.revolution}}
+          @defaultValue={{14}}
+          @min={{3}}
+          @max={{60}}
+          @step={{1}}
+          @description='Seconds for one full turn.'
+          @onInput={{this.setRevolution}}
+        />
+        <Args.String
+          @name='direction'
+          @value={{this.direction}}
+          @defaultValue='cw'
+          @options={{this.directionOptions}}
+          @description='Which way it turns.'
+          @onInput={{this.setDirection}}
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-pathtext-fill'
+          @type='color'
+          @description='The glyph colour, when the fill argument is not used.'
+        />
+        <Css.Basic
+          @name='pretui-pathtext-revolution'
+          @type='duration'
+          @description='Seconds per turn, if you would rather set it in CSS than pass a number.'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-pt-demo {
+        display: grid;
+        gap: var(--space-3, 8px);
+        justify-items: center;
+      }
+      .pretui-pt-demo-art {
+        width: 260px;
+        max-width: 100%;
+      }
+      .pretui-pt-demo-note {
+        margin: 0;
+        max-width: 44ch;
+        text-align: center;
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_PATH_TEXT: Record<string, unknown> = {
+  PathText: PathTextUsage,
+};