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

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

@@ -0,0 +1,233 @@
+// Pretui — Sparkline: an inline micro-chart for a Stat or a table cell — line, area or bars, in SVG.
+import Component from '@glimmer/component';
+import { cached } from '@glimmer/tracking';
+import { htmlSafe } from '@ember/template';
+import { PRETUI_TONES, resolveTone } from '../pretui-primitives';
+import type { PretuiToneArg } from '../pretui-primitives';
+import { TONE_HUES } from '../internal/corner-mark';
+
+export type SparklineKind = 'line' | 'area' | 'bar';
+
+
+export interface SparklineSignature {
+  Args: {
+    values: number[];
+    /** Required: what the series is ('Revenue, last 12 weeks'). The summary is appended. */
+    label: string;
+    /** 'line' (default), 'area' or 'bar'. */
+    kind?: SparklineKind;
+    /** Default 'primary'. Accepts the kit's tone spellings. */
+    tone?: PretuiToneArg;
+    /** Pixels (default 96 × 24). */
+    width?: number;
+    height?: number;
+    /** Mark the last point with a dot (line and area). */
+    showLast?: boolean;
+    /** Start the scale at zero rather than the series minimum. */
+    zeroBased?: boolean;
+  };
+  Element: SVGSVGElement;
+}
+
+const NUMBER = new Intl.NumberFormat(undefined, { maximumFractionDigits: 2 });
+
+function finite(values: number[] | undefined): number[] {
+  return (values ?? []).filter((v) => typeof v === 'number' && Number.isFinite(v));
+}
+
+function round(n: number): number {
+  return Math.round(n * 100) / 100;
+}
+
+/**
+ * The spark: a series drawn at the size of a word, next to the number it
+ * explains. Chart is the full plot with axes; BarList ranks named rows.
+ *
+ * It is plain SVG with no engine and no animation. It is `role="img"`, named
+ * by `@label` plus a spoken summary ("from 12 to 30, low 8, high 31"), so the
+ * shape's meaning reaches a screen reader as words. The stroke scales
+ * without distortion (`vector-effect: non-scaling-stroke`), and a series of
+ * one value draws a flat line rather than nothing.
+ */
+export class Sparkline extends Component<SparklineSignature> {
+  get kind(): SparklineKind {
+    let k = this.args.kind;
+    return k === 'area' || k === 'bar' ? k : 'line';
+  }
+  get width(): number {
+    return Math.max(8, this.args.width ?? 96);
+  }
+  get height(): number {
+    return Math.max(4, this.args.height ?? 24);
+  }
+  get values(): number[] {
+    return finite(this.args.values);
+  }
+  get empty(): boolean {
+    return this.values.length === 0;
+  }
+  /** Computed once per render. Bars always include zero: a bar's length
+   * encodes its distance from zero, so zero has to be on the scale. */
+  @cached
+  private get range(): { min: number; max: number } {
+    let min = Infinity;
+    let max = -Infinity;
+    for (let v of this.values) {
+      min = Math.min(min, v);
+      max = Math.max(max, v);
+    }
+    if (this.args.zeroBased || this.kind === 'bar') {
+      min = Math.min(0, min);
+      max = Math.max(0, max);
+    }
+    return { min, max };
+  }
+  /** y for a value, with 1px of headroom so the stroke is never clipped. */
+  private y(value: number): number {
+    let { min, max } = this.range;
+    let h = this.height - 2;
+    if (max === min) {
+      return round(1 + h / 2);
+    }
+    return round(1 + h - ((value - min) / (max - min)) * h);
+  }
+  get points(): { x: number; y: number }[] {
+    let values = this.values;
+    let w = this.width - 2;
+    let n = values.length;
+    return values.map((v, i) => ({ x: round(1 + (n === 1 ? w / 2 : (i / (n - 1)) * w)), y: this.y(v) }));
+  }
+  get linePath(): string {
+    let pts = this.points;
+    if (pts.length === 1) {
+      let p = (pts[0] as { x: number; y: number });
+      return `M1 ${p.y} L${this.width - 1} ${p.y}`;
+    }
+    return pts.map((p, i) => `${i === 0 ? 'M' : 'L'}${p.x} ${p.y}`).join(' ');
+  }
+  get areaPath(): string {
+    let pts = this.points;
+    let base = this.args.zeroBased ? this.y(0) : this.height - 1;
+    if (pts.length === 1) {
+      let p = (pts[0] as { x: number; y: number });
+      return `M1 ${p.y} L${this.width - 1} ${p.y} L${this.width - 1} ${base} L1 ${base} Z`;
+    }
+    let first = (pts[0] as { x: number; y: number });
+    let last = (pts[pts.length - 1] as { x: number; y: number });
+    return `${this.linePath} L${last.x} ${base} L${first.x} ${base} Z`;
+  }
+  get bars(): { x: number; y: number; width: number; height: number }[] {
+    let values = this.values;
+    let n = values.length;
+    let slot = (this.width - 2) / n;
+    let gap = Math.min(2, slot * 0.25);
+    // every bar stands on zero, up for positive values and down for negative
+    let base = this.y(0);
+    return values.map((v, i) => {
+      let top = this.y(v);
+      let y = Math.min(top, base);
+      return {
+        x: round(1 + i * slot + gap / 2),
+        y,
+        width: round(Math.max(1, slot - gap)),
+        height: round(Math.max(1, Math.abs(base - top))),
+      };
+    });
+  }
+  get last(): { x: number; y: number } | undefined {
+    return this.args.showLast && this.kind !== 'bar' ? this.points[this.points.length - 1] : undefined;
+  }
+  get summary(): string {
+    let values = this.values;
+    if (!values.length) {
+      return 'no data';
+    }
+    let first = values[0] as number;
+    let last = values[values.length - 1] as number;
+    let low = Infinity;
+    let high = -Infinity;
+    for (let v of values) {
+      low = Math.min(low, v);
+      high = Math.max(high, v);
+    }
+    let f = (n: number) => NUMBER.format(n);
+    return `from ${f(first)} to ${f(last)}, low ${f(low)}, high ${f(high)}`;
+  }
+  get name(): string {
+    return `${this.args.label}: ${this.summary}`;
+  }
+  get style() {
+    let tone = resolveTone(this.args.tone, PRETUI_TONES, 'primary');
+    return htmlSafe(`--pretui-sparkline-hue: ${TONE_HUES[tone]}`);
+  }
+  isKind = (kind: SparklineKind): boolean => this.kind === kind;
+
+  get viewBox(): string {
+    return `0 0 ${this.width} ${this.height}`;
+  }
+
+  <template>
+    <svg
+      class='pretui-sparkline'
+      role='img'
+      aria-label={{this.name}}
+      width={{this.width}}
+      height={{this.height}}
+      viewBox={{this.viewBox}}
+      preserveAspectRatio='none'
+      data-kind={{this.kind}}
+      style={{this.style}}
+      data-test-pretui-sparkline
+      ...attributes
+    >
+      {{#unless this.empty}}
+        {{#if (this.isKind 'bar')}}
+          {{#each this.bars as |bar|}}
+            <rect class='pretui-sparkline-bar' x={{bar.x}} y={{bar.y}} width={{bar.width}} height={{bar.height}} rx='1' />
+          {{/each}}
+        {{else}}
+          {{#if (this.isKind 'area')}}
+            <path class='pretui-sparkline-area' d={{this.areaPath}} />
+          {{/if}}
+          <path class='pretui-sparkline-line' d={{this.linePath}} />
+          {{#if this.last}}
+            <circle class='pretui-sparkline-dot' cx={{this.last.x}} cy={{this.last.y}} r='2' />
+          {{/if}}
+        {{/if}}
+      {{/unless}}
+    </svg>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-sparkline {
+          display: inline-block;
+          vertical-align: middle;
+          overflow: visible;
+          color: var(--pretui-sparkline-hue, var(--primary));
+        }
+        .pretui-sparkline-line {
+          fill: none;
+          stroke: currentColor;
+          stroke-width: var(--pretui-sparkline-stroke, 1.5);
+          stroke-linecap: round;
+          stroke-linejoin: round;
+          vector-effect: non-scaling-stroke;
+        }
+        .pretui-sparkline-area {
+          fill: currentColor;
+          opacity: var(--pretui-sparkline-fill, 0.16);
+          stroke: none;
+        }
+        .pretui-sparkline-bar {
+          fill: currentColor;
+        }
+        .pretui-sparkline-dot {
+          fill: currentColor;
+          stroke: var(--card);
+          stroke-width: 1;
+          vector-effect: non-scaling-stroke;
+        }
+      }
+    </style>
+  </template>
+
+}

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

@@ -0,0 +1,58 @@
+## What it is
+
+**An inline micro-chart**, a series drawn at the size of a word next to the number it explains: orders this week with the last twelve weeks beside it, or a table cell's trend. It comes as a line, an area or bars.
+
+Reach for a neighbour when you need more:
+
+- **Chart** is the full plot, with axes and a legend.
+- **BarList** ranks named rows.
+- **Stat** is the number the spark sits beside.
+
+## The contract
+
+```
+@values (number[]), @label (required)
+@kind? ('line' | 'area' | 'bar'; default 'line'), @tone? (default 'primary')
+@width? (96), @height? (24), @showLast?, @zeroBased?
+Element: SVGSVGElement
+```
+
+**Plain SVG, no engine.** Line and area are one path through the points, and bars are one rect per value. Line and area scale from the series minimum to its maximum, or include zero with `@zeroBased`. Bars always include zero and stand on it, up for positive values and down for negative ones, because a bar's length has to encode its distance from zero. The stroke keeps its width when the chart is stretched (`vector-effect: non-scaling-stroke`). There is 1px of headroom so the line is never clipped, and `@showLast` marks the final point.
+
+**Degenerate series behave.** One value draws a flat line, an empty series draws nothing, and non-numbers (`NaN`, `Infinity`) are dropped.
+
+**No animation.** A spark shows a shape, not a process.
+
+## Prior art
+
+**Mantine `Sparkline`** takes `data`, `curveType`, `color`, `fillOpacity`, `withGradient` and `trendColors`, and is built on Recharts. **Tremor `SparkAreaChart` / `SparkLineChart` / `SparkBarChart`** also use Recharts. **react-sparklines** is a small SVG library.
+
+Where Pretui is better: **it has a name.** The chart is `role="img"`, named by `@label` plus a spoken summary ("from 12 to 41, low 12, high 41"), with the numbers formatted to at most two decimals. Mantine and Tremor render an unnamed SVG that a screen reader skips or reads as "image". **No chart engine** is loaded for a 96px drawing.
+
+Where it is thinner: **no curve smoothing**, **no gradient fill**, **no trend-coloured tone** (pick `@tone` yourself), and **no tooltip or hover value**. Use **Chart** when the reader needs to read individual points.
+
+## Accessibility
+
+No APG pattern. It is an image.
+
+- **`role="img"`, named by `@label` and a summary** of the first, last, lowest and highest values. The tests assert the full name, and "no data" for an empty series.
+- **The label is required**, because a spark without one tells a screen reader nothing. Say what the series is and over what period, for example "Orders, last 12 weeks".
+- **The tone is not the meaning.** A red spark still needs its label, and usually the number next to it, to say whether falling is bad.
+
+## Theming
+
+`--pretui-sparkline-hue` (set from the tone: `--primary` by default, or `--pretui-info`, `--success`, `--warning`, `--destructive`, `--pretui-attention`, `--muted-foreground`), `--pretui-sparkline-stroke` (line width, default 1.5), `--pretui-sparkline-fill` (area opacity, default 0.16) and `--card` (the ring around the last-point dot).
+
+Size is an arg, because a spark is sized to its context rather than to the theme.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+| Agent types                                     | Give them                                  |
+| ----------------------------------------------- | ------------------------------------------ |
+| Mantine `<Sparkline data curveType="linear">`   | `<Sparkline @values @label>`               |
+| Mantine `fillOpacity`                           | `@kind='area'` + `--pretui-sparkline-fill` |
+| Tremor `<SparkBarChart>`                        | `@kind='bar'`                              |
+| react-sparklines `<Sparklines><SparklinesLine>` | `<Sparkline>`                              |
+| a hover tooltip per point                       | **Chart**                                  |

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

@@ -0,0 +1,74 @@
+// Pretui — Sparkline usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Sparkline } from './sparkline';
+import type { SparklineKind } from './sparkline';
+import type { PretuiToneArg } from '../pretui-primitives';
+
+const ORDERS = [12, 18, 14, 22, 19, 27, 31, 29, 34, 30, 38, 41];
+const KINDS = ['line', 'area', 'bar'];
+const TONES = ['primary', 'success', 'warning', 'danger', 'info', 'neutral'];
+
+export class SparklineUsage extends Component {
+  orders = ORDERS;
+  kinds = KINDS;
+  tones = TONES;
+  @tracked kind = 'area';
+  @tracked tone = 'primary';
+  @tracked showLast = true;
+  setKind = (v: string) => (this.kind = v);
+  setTone = (v: string) => (this.tone = v);
+  setShowLast = (v: boolean) => (this.showLast = v);
+  get toneArg(): PretuiToneArg {
+    return this.tone as PretuiToneArg;
+  }
+  get kindArg() {
+    return this.kind as SparklineKind;
+  }
+  get usage() {
+    return `<Sparkline @values={{this.orders}} @label='Orders, last 12 weeks' @kind='${this.kind}' @tone='${this.tone}'${this.showLast ? ' @showLast={{true}}' : ''} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Sparkline'
+      @description='An inline micro-chart at the size of a word, next to the number it explains: line, area or bars, in plain SVG with no engine and no animation. It is an image named by its label and a spoken summary, so the shape reaches a screen reader as words. Chart is the full plot.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <p class='sp-demo'>
+          <span class='sp-demo-num'>41</span> orders this week
+          <Sparkline @values={{this.orders}} @label='Orders, last 12 weeks' @kind={{this.kindArg}} @tone={{this.toneArg}} @showLast={{this.showLast}} />
+        </p>
+      </:example>
+      <:api as |Args|>
+        <Args.Object @name='values' @required={{true}} @description='number[]; non-numbers are dropped.' />
+        <Args.String @name='label' @required={{true}} @description='What the series is. The summary is appended.' />
+        <Args.String @name='kind' @value={{this.kind}} @options={{this.kinds}} @defaultValue='line' @onInput={{this.setKind}} />
+        <Args.String @name='tone' @value={{this.tone}} @options={{this.tones}} @defaultValue='primary' @onInput={{this.setTone}} />
+        <Args.Bool @name='showLast' @value={{this.showLast}} @defaultValue={{false}} @onInput={{this.setShowLast}} />
+        <Args.Bool @name='zeroBased' @defaultValue={{false}} @description='Start the scale at zero.' />
+        <Args.Number @name='width' @defaultValue={{96}} />
+        <Args.Number @name='height' @defaultValue={{24}} />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .sp-demo {
+        display: flex;
+        align-items: center;
+        gap: var(--space-3, 0.5rem);
+        margin: 0;
+        font-size: var(--text-ui-md, 0.78rem);
+      }
+      .sp-demo-num {
+        font-family: var(--font-serif);
+        font-size: var(--text-heading, 1.1875rem);
+        font-variant-numeric: tabular-nums;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_SPARKLINE: Record<string, unknown> = {
+  Sparkline: SparklineUsage,
+};

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

@@ -0,0 +1,57 @@
+// Pretui — Spinner: an indeterminate busy indicator, sized in pixels.
+import Component from '@glimmer/component';
+import { htmlSafe } from '@ember/template';
+import type { PretuiSize, PretuiSizeArg } from '../pretui-primitives';
+import { resolvePixelSize } from '../internal/feedback';
+
+const SPINNER_PX: Record<PretuiSize, number> = {
+  xs: 9,
+  s: 11,
+  m: 13,
+  l: 17,
+  xl: 22,
+};
+
+export interface SpinnerSignature {
+  Args: {
+    /** pixels, or any spelling of the `xs|s|m|l|xl` scale */
+    size?: number | PretuiSizeArg;
+  };
+  Element: HTMLSpanElement;
+}
+
+// `aria-label` deliberately stays a plain attribute above `...attributes`,
+// not an `@arg`: a caller who needs a different accessible name passes
+// `aria-label='…'` and splattributes wins. Promoting it to an arg is the
+// native-attribute-swallowing bug this whole alias pass exists to avoid.
+export class Spinner extends Component<SpinnerSignature> {
+  get style() {
+    let size = resolvePixelSize(this.args.size, SPINNER_PX);
+    return htmlSafe(`width: ${size}px; height: ${size}px`);
+  }
+  <template>
+    <span class='pretui-spinner' role='status' aria-label='Loading' style={{this.style}} data-test-pretui-spinner ...attributes></span>
+    <style scoped>
+      @layer PretComponent {
+        @keyframes pretui-spin {
+          to {
+            transform: rotate(360deg);
+          }
+        }
+        .pretui-spinner {
+          display: inline-block;
+          border-radius: 50%;
+          border: 1.5px solid color-mix(in oklch, currentColor 25%, transparent);
+          border-top-color: currentColor;
+          animation: pretui-spin 0.7s linear infinite;
+          flex: none;
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-spinner {
+            animation-duration: 2.8s;
+          }
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,49 @@
+## What it is
+
+The smallest possible "something is happening": a ring that spins, sized in pixels, inheriting the current text colour. Use it inline — inside a **Button**'s busy state, beside a label, in a table cell — where the duration is unknown and there is no room for anything larger. If the operation has a known extent, use **ProgressBar**. If the whole region is loading and you want a shape hint, use **Skeleton**. If you want a labelled loader with an elapsed clock, use **LoadingState**.
+
+## The contract
+
+```
+@size? (13)
+Element: HTMLSpanElement
+```
+
+One arg, and it sets `width` and `height` inline. Everything else is inherited.
+
+**The ring is `currentColor`.** The border is `color-mix(in srgb, currentColor 25%, transparent)` with `border-top-color: currentColor`, so a Spinner takes the colour of whatever text it sits in — white inside an accent Button, `--muted-foreground` in a table cell — with no tone arg and no variant. That is the reason the component has one argument.
+
+`flex: none` means it never shrinks in a flex row, which is the failure mode of hand-rolled spinners next to a long label.
+
+`display: inline-block` (not `inline-flex`) keeps it on the text baseline rather than centring it, which matters when it sits mid-sentence.
+
+## Prior art
+
+**Web Awesome `wa-spinner`** has **zero properties and zero slots** — an SVG with `role="progressbar"` and a localized `aria-label` of "loading", themed entirely through `--track-width`, `--track-color`, `--indicator-color` and `--speed`. That is the closest philosophical match, and its four custom properties are the thing Pretui lacks. **React Spectrum** has no separate spinner; `ProgressCircle isIndeterminate` covers it. **shadcn** has no spinner component at all — the convention is a Lucide `Loader2` icon with `animate-spin`.
+
+Pretui's `currentColor` inheritance is a real improvement on Web Awesome's `--indicator-color`: it needs no configuration at every call site to look right, and it _cannot_ be wrong inside a Button that changes tone.
+
+Where it is behind: **no speed, thickness or color tokens.** The 1.5px border and 0.7s duration are hard-coded, so a theme cannot make spinners slower or heavier. Web Awesome's `--speed` in particular is the knob a calm theme wants.
+
+Note that **Button embeds its own copy of this ring** rather than composing `Spinner` — the same CSS, duplicated. Worth consolidating.
+
+## Accessibility
+
+No APG pattern. The two legitimate treatments are `role="progressbar"` with no `aria-valuenow` (the indeterminate contract) or `role="status"` for an announced "Loading…".
+
+Pretui uses `role="status"` with `aria-label="Loading"`, and that combination has a specific problem:
+
+- **`role="status"` is a live region, and this one is created with its content already in place.** A live region must exist in the DOM _before_ its content changes to be announced. A spinner that mounts when a fetch begins will frequently announce nothing at all — the region and its accessible name arrive together, which is exactly the case screen readers skip. `role="progressbar"` with no `aria-valuenow` would be the more honest choice here: it describes the element rather than trying to announce it.
+- **Every spinner on a page announces the same literal "Loading"**, with no way to say what is loading. There is no `@label` arg; you can pass `aria-label` through `...attributes`, and you should.
+- **Nothing announces when loading _finishes_.** The spinner unmounts silently. This is the other half of the pattern and it belongs to the caller — write "Loaded 24 results" into a persistent live region.
+- **Inside a `<Button @busy>`, the button is `disabled`**, so focus is lost from it and the spinner is inside an element removed from the tab order. The busy state is silent to assistive tech in that path.
+- **Reduced motion slows the animation to 2.8s rather than stopping it.** This is a defensible reading — a spinner that does not spin conveys nothing — and is gentler than the common approach of hiding it entirely. It is not a full `prefers-reduced-motion` stop, so a user who cannot tolerate any looping motion is not fully served; a static ring plus text would be.
+- The element is empty, so nothing else is announced.
+
+## Theming
+
+`currentColor` for both the track (at 25% alpha) and the indicator. That is the entire palette — there are no spinner-specific tokens at all, which is either the cleanest thing about it or the most limiting, depending on what you need.
+
+The 1.5px border width, 0.7s duration (2.8s under reduced motion), and the 13px default size are hard-coded. A theme wanting a heavier or slower spinner must fork the component. Since it inherits ink, a theme only needs to ensure `--foreground`, `--muted-foreground` and each Button tone's on-color all read acceptably at 25% alpha — the track is the part that disappears first on low-contrast surfaces.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,65 @@
+// Pretui — Spinner usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Spinner } from './spinner';
+
+// ── Spinner ← loading-indicator/usage.gts + circle-spinner/usage.gts ─────
+// Dropped knobs: color (Spinner inherits currentColor — tint the wrapper,
+// shown in the specimen), variant (no theme-variant matrix; currentColor
+// covers it).
+class SpinnerUsage extends GlimmerComponent {
+  @tracked size = 20;
+  setSize = (v: number | null) => {
+    if (v !== null) {
+      this.size = v;
+    }
+  };
+  <template>
+    <FreestyleUsage
+      @name='Spinner'
+      @description='Default loading indicator for Boxel components.'
+    >
+      <:example>
+        <Spinner @size={{this.size}} />
+        <span class='tint-primary'><Spinner @size={{this.size}} /></span>
+        <span class='tint-danger'><Spinner @size={{this.size}} /></span>
+        <p class='note'>Stroke color follows currentColor — the tinted
+          specimens wrap the spinner in colored text.</p>
+      </:example>
+      <:api as |Args|>
+        <Args.Number
+          @name='size'
+          @description='Sets height and width for loading indicator icon.'
+          @defaultValue={{13}}
+          @value={{this.size}}
+          @min={{10}}
+          @max={{48}}
+          @step={{1}}
+          @onInput={{this.setSize}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .tint-primary {
+        color: var(--pretui-primary-ink, var(--boxel-highlight-hover));
+        display: inline-flex;
+      }
+      .tint-danger {
+        color: var(--pretui-destructive-ink, var(--boxel-danger));
+        display: inline-flex;
+      }
+      .note {
+        flex-basis: 100%;
+        text-align: center;
+        margin: 0;
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_SPINNER: Record<string, unknown> = {
+  Spinner: SpinnerUsage,
+};

package/bundled-realms/pretui/components/split-panes.gts

@@ -0,0 +1,69 @@
+// Pretui — SplitPanes: drag-resizable panes, a thin wrap of boxel-ui ResizablePanelGroup.
+import Component from '@glimmer/component';
+import { ResizablePanelGroup as BoxelResizablePanelGroup } from '@cardstack/boxel-ui/components';
+
+// ── SplitPanes — WRAPS boxel-ui ──────────────────────────────────────────
+// boxel-ui's ResizablePanelGroup drag-resize engine intact: per-panel
+// constraint solving (defaultSize/minSize/maxSize/collapsible, in
+// percent), pointer-captured drag, double-click collapse (reversible via
+// @reverseCollapse). The yielded Panel/Handle pair passes straight
+// through. Handle dress note: boxel's handle declares its own
+// --boxel-panel-resize-handle-* colors FROM --boxel-450 /
+// --boxel-highlight, so the wrapper re-skins one level up — remapping
+// those two channel tokens to the Pretui equivalents for this subtree.
+
+export interface SplitPanesSignature {
+  Args: {
+    /** 'horizontal' (default) lays panes left-to-right */
+    orientation?: 'horizontal' | 'vertical';
+    /** double-click collapse folds the LAST panel instead of the first */
+    reverseCollapse?: boolean;
+    onLayoutChange?: (layout: number[]) => void;
+  };
+  Blocks: {
+    /* eslint-disable @typescript-eslint/no-explicit-any -- the yielded
+       pair are boxel-ui's curried ResizablePanel / ResizeHandle */
+    default: [any, any];
+    /* eslint-enable @typescript-eslint/no-explicit-any */
+  };
+  Element: HTMLDivElement;
+}
+
+export class SplitPanes extends Component<SplitPanesSignature> {
+  get orientation(): 'horizontal' | 'vertical' {
+    return this.args.orientation ?? 'horizontal';
+  }
+  <template>
+    <div
+      class='pretui-splitpanes'
+      data-orientation={{this.orientation}}
+      data-test-pretui-split-panes
+      ...attributes
+    >
+      <BoxelResizablePanelGroup
+        @orientation={{this.orientation}}
+        @reverseCollapse={{@reverseCollapse}}
+        @onLayoutChange={{@onLayoutChange}}
+        as |Panel Handle|
+      >
+        {{yield Panel Handle}}
+      </BoxelResizablePanelGroup>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        /* The group fills its host — give the wrapping context a height.
+           Handle idle color rides the Pretui hairline voice; hover snaps to
+           primary (both via the remapped --boxel-* channel, see above). */
+        .pretui-splitpanes {
+          height: 100%;
+          min-height: 0;
+          font-size: var(--text-ui-md, 12.5px);
+          letter-spacing: var(--track-ui, 0.01em);
+          color: var(--foreground);
+          --boxel-450: var(--muted-foreground);
+          --boxel-highlight: var(--primary);
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/split-panes.md

@@ -0,0 +1,54 @@
+## What it is
+
+Two or more resizable panes with a draggable divider between them. Use it for a persistent side-by-side arrangement the user should be able to retune — a list beside a detail, an editor beside a preview, a tree beside a canvas. If the second region is transient, use **Drawer** or **Popover**. If the split is fixed, plain CSS grid is lighter. If you need a full canvas workspace, that is **NodeCanvas**.
+
+## The contract
+
+```
+@orientation? 'horizontal' | 'vertical'   (default 'horizontal')
+@reverseCollapse?
+@onLayoutChange?(layout: number[])
+<:default as |Panel, Handle|>
+```
+
+`Panel` takes `defaultSize` / `minSize` / `maxSize` / `collapsible`, all in **percent**. `Handle` is placed between panels.
+
+Two behaviours worth knowing. **Double-clicking a handle collapses a pane**, and `@reverseCollapse` switches which one — the last instead of the first. And `@onLayoutChange` reports the whole layout as an array of percentages, which is what you persist if you want the split to survive a reload; nothing here stores it for you.
+
+## Prior art
+
+This is a **thin runtime wrap of boxel-ui's `ResizablePanelGroup`**, per the territory's foundation rule: the machinery is boxel-ui's and only the cloth changes. The engine supplies per-panel constraint solving, pointer-captured drag (so the drag survives the pointer leaving the handle), and the double-click collapse.
+
+The dress note is the interesting implementation detail: **boxel-ui's handle declares its own `--boxel-panel-resize-handle-*` colors _from_ `--boxel-450` and `--boxel-highlight`**, so the wrapper cannot repoint the handle tokens directly — it has to remap those two upstream channel tokens for the subtree instead. That is the general shape of the retrofit pattern in this kit: when a token is derived rather than read, you re-skin one level up.
+
+Against the field: **`react-resizable-panels`** (which shadcn wraps as `ResizablePanel`) is the reference — `direction`, `defaultSize`/`minSize`/`maxSize`, `collapsible`/`collapsedSize`, `onLayout`, `autoSaveId` for localStorage persistence, and `ResizableHandle withHandle`. **Web Awesome `wa-split-panel`** takes `position`/`position-in-pixels`, `vertical`, `disabled`, `primary`, `snap` and `snap-threshold`. **React Spectrum** has no equivalent.
+
+Where Pretui/boxel-ui is comparable or better: percent-based constraints with real solving (Web Awesome's single `position` cannot express a three-pane minimum), and pointer capture done properly.
+
+Where it is behind: **no `autoSaveId`** (persistence is entirely yours via `@onLayoutChange`), **no snap points** (Web Awesome's `snap`/`snap-threshold` is the nicest thing in that component), and no visible grip affordance arg equivalent to shadcn's `withHandle`.
+
+## Accessibility
+
+Governing pattern: **ARIA `separator` with `aria-valuenow`** — a focusable separator is one of the few cases where `separator` is an interactive role. The contract is: `role="separator"` on the handle, `tabindex="0"`, `aria-valuenow`/`aria-valuemin`/`aria-valuemax` describing the position as a percentage, `aria-orientation`, an accessible name (`aria-label` such as "Resize panels"), and **arrow keys moving the divider** — Left/Right for a horizontal split, Up/Down for a vertical one, with Home/End going to the extremes and Enter or F6 toggling collapse.
+
+**All of that belongs to boxel-ui's engine, not to this wrapper.** What the engine does today:
+
+- **The handle is a native `<button>` named "Resize handle".** Tab reaches it, and double-click collapses the pane.
+- **There is no keyboard resizing and no `aria-valuenow`.** Arrow keys do nothing on the handle, and a screen-reader user is not told where the divider sits. That is a **WCAG 2.1.1 Keyboard** gap for arbitrary resizing, and **WCAG 2.5.7 Dragging Movements** has only the collapse as a single-pointer alternative. The fix belongs in boxel-ui's ResizeHandle.
+- **Name each handle.** The yielded `Handle` splats its attributes after its own label, so `aria-label='Resize the sidebar'` replaces the generic name. In a three-pane layout, "Resize handle" three times is not enough.
+- `@onLayoutChange` fires continuously during a drag; do not put an announcement on it.
+
+## Theming
+
+Consumed: `--text-ui-md`, `--track-ui`, and the layout tokens.
+
+Remapped for the subtree: `--boxel-450` and `--boxel-highlight` → the Pretui handle colors (rest and active). Because the handle's own custom properties are _derived_ from those two, this is the only place a theme can reach the handle — repointing `--boxel-panel-resize-handle-*` directly has no effect.
+
+`data-orientation` is reflected on the wrapper for styling hooks. Note the group fills its host, so **the wrapping context must have a height** — a SplitPanes in an auto-height container collapses to nothing, which is the first thing to check when it renders blank.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+shadcn `Resizable` (`react-resizable-panels`) is this tile (alias stub).
+Ant/Mantine `Splitter` too.