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

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

@@ -0,0 +1,156 @@
+// Pretui — Presence: enter and exit transitions for content that appears and disappears.
+import Component from '@glimmer/component';
+import { htmlSafe } from '@ember/template';
+import { cssNumber } from '../pretui-css';
+import { presetTransform, seconds } from '../internal/motion-core';
+import type { MotionPreset } from '../internal/motion-core';
+
+// ── Presence ─────────────────────────────────────────────────────────────
+// Enter AND exit transitions for content that appears and disappears.
+//
+// Ported from motion-primitives' <AnimatePresence> (itself framer-motion's).
+// Upstream needs a whole animation engine for one reason: React removes the
+// element the instant the flag flips, so something has to keep a ghost of it
+// alive long enough to animate out. That is ~40kB of runtime to defer one
+// unmount.
+//
+// Better than the inspiration: the modern CSS platform now does exit
+// transitions natively. `transition-behavior: allow-discrete` lets `display`
+// participate in a transition — the browser holds `display: block` for the
+// duration and flips to `none` at the end — and `@starting-style` supplies
+// the from-values for the enter side, since an element leaving
+// `display: none` counts as newly rendered. Zero JS, zero timers, zero
+// dependency, and it survives a blocked main thread.
+//
+// The one API consequence, stated plainly rather than hidden (Law 7): the
+// content must stay in the template. Presence owns visibility via @show; do
+// NOT wrap it in {{#if}}, or you are back to an instant unmount. Presence
+// still works under {{#if}} — you simply get the enter half only.
+//
+// Dropped upstream surface: `mode='wait' | 'popLayout'` (cross-fading two
+// children through a shared layout requires FLIP measurement and a JS
+// engine — out of scope for a CSS primitive; render two Presences and stagger
+// them with @delay), and variant/keyframe objects (a preset knob plus two
+// custom properties covers the honest cases).
+export interface PresenceSignature {
+  Args: {
+    /** visible when true (default). Presence owns display — do NOT also wrap it in {{#if}}, or the exit transition has nothing to animate. */
+    show?: boolean;
+    /** entrance preset: fade | rise | fall | scale | slide */
+    enter?: MotionPreset;
+    /** exit preset — separately settable, because leaving reads differently from arriving (Law 7). Defaults to @enter. */
+    exit?: MotionPreset;
+    /** entrance duration in seconds */
+    duration?: number;
+    /** exit duration in seconds — defaults to two-thirds of @duration, because leaving should not linger */
+    exitDuration?: number;
+    /** seconds to wait before entering — the timer-free way to stagger several Presences */
+    delay?: number;
+    /** travel distance in px for rise / fall / slide */
+    distance?: number;
+    /** start scale for the scale preset (0–1) */
+    scale?: number;
+  };
+  Blocks: { default: [] };
+  Element: HTMLDivElement;
+}
+
+export class Presence extends Component<PresenceSignature> {
+  get show(): boolean {
+    return this.args.show ?? true;
+  }
+  // Focus must not be reachable inside content that is on its way out.
+  // display:none already removes it once the transition ends; `inert` covers
+  // the window in between (upstream leaves that gap open).
+  get inert(): true | undefined {
+    return this.show ? undefined : true;
+  }
+  get style(): ReturnType<typeof htmlSafe> {
+    let enter = this.args.enter ?? 'fade';
+    let exit = this.args.exit ?? enter;
+    let duration = this.args.duration !== undefined && this.args.duration > 0
+      ? this.args.duration
+      : 0.22;
+    let bits = [
+      `--pretui-presence-enter: ${presetTransform(enter)}`,
+      `--pretui-presence-exit: ${presetTransform(exit)}`,
+      `--pretui-presence-enter-duration: ${duration.toFixed(3)}s`,
+      `--pretui-presence-exit-duration: ${seconds(
+        this.args.exitDuration,
+        duration * (2 / 3),
+      )}`,
+      `--pretui-presence-delay: ${(this.args.delay ?? 0).toFixed(3)}s`,
+    ];
+    {
+      let n = cssNumber(this.args.distance, -10000, 10000);
+      if (n !== undefined) {
+        bits.push(`--pretui-motion-distance: ${n}px`);
+      }
+    }
+    {
+      let n = cssNumber(this.args.scale, 0, 100);
+      if (n !== undefined) {
+        bits.push(`--pretui-motion-scale: ${n}`);
+      }
+    }
+    return htmlSafe(bits.join('; '));
+  }
+  <template>
+    <div
+      class='pretui-presence'
+      data-show={{if this.show 'true' 'false'}}
+      inert={{this.inert}}
+      style={{this.style}}
+      data-test-pretui-presence
+      ...attributes
+    >{{yield}}</div>
+    <style scoped>
+      @layer PretComponent {
+        /* Hidden IS the base rule, so its declarations are also the exit
+           destination — and because CSS transitions read the after-change
+           style, the exit timing lives here and the enter timing lives on the
+           shown rule. One mechanism, two independently tuned halves. */
+        .pretui-presence {
+          display: none;
+          opacity: 0;
+          transform: var(--pretui-presence-exit, none);
+          transition-property: opacity, transform, display;
+          transition-duration: var(--pretui-presence-exit-duration, 150ms);
+          transition-timing-function: var(
+            --pretui-ease-snap,
+            cubic-bezier(0.23, 1, 0.32, 1)
+          );
+          transition-behavior: allow-discrete;
+        }
+        .pretui-presence[data-show='true'] {
+          display: var(--pretui-presence-display, block);
+          opacity: 1;
+          transform: none;
+          transition-property: opacity, transform, display;
+          transition-duration: var(--pretui-presence-enter-duration, 220ms);
+          transition-delay: var(--pretui-presence-delay, 0s);
+          transition-timing-function: var(
+            --pretui-ease-snap,
+            cubic-bezier(0.23, 1, 0.32, 1)
+          );
+          transition-behavior: allow-discrete;
+        }
+        /* Leaving display:none counts as a first render, so this supplies the
+           enter from-state on every appearance, not just the first. */
+        @starting-style {
+          .pretui-presence[data-show='true'] {
+            opacity: 0;
+            transform: var(--pretui-presence-enter, none);
+          }
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-presence,
+          .pretui-presence[data-show='true'] {
+            transition-property: none;
+            transform: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,55 @@
+## What it is
+
+Mount and unmount transitions: content that fades, rises, falls, scales or slides both **in and out**. Use it wherever something appears or disappears and the disappearance should be visible — a panel, a row, a toast, an inline detail. If the entrance should be triggered by scroll position, **InView**. If the thing is an overlay, **Dialog**, **Drawer** and **Popover** already have their own `@starting-style` motion.
+
+## The contract
+
+```
+@show? (default true)
+@enter? / @exit?: 'fade' | 'rise' | 'fall' | 'scale' | 'slide'
+@duration? / @exitDuration? (seconds)
+@delay? (seconds), @distance? (px), @scale? (0–1)
+<:default>
+```
+
+**`Presence` owns `display` — do not also wrap it in `{{#if}}`.** That is the one thing to get right: an `{{#if}}` removes the element before the exit transition can run, so the content vanishes instead of leaving. This is the single most common misuse and the source calls it out in the arg's own doc comment.
+
+**`@exit` is separately settable and defaults to `@enter`; `@exitDuration` defaults to two-thirds of `@duration`.** Leaving reads differently from arriving, and leaving should not linger — that ratio is Law 7 expressed as a default rather than a rule you have to remember.
+
+**`@delay` is the timer-free way to stagger several Presences.** Seconds, unitless rate vocabulary, same as **StreamingText**'s rate arg.
+
+The preset table is **shared with InView**, so "rise" means the same travel in both, and every preset resolves through `--pretui-motion-distance` / `--pretui-motion-scale` — a caller can retune the travel without leaving the preset vocabulary.
+
+## Prior art
+
+**`AnimatePresence`** from framer-motion / motion-primitives is the direct upstream, and the comparison is the whole point of this file: `AnimatePresence` pays a **JS animation engine and a per-frame RAF loop** for behaviour the modern CSS platform now expresses declaratively.
+
+Pretui uses **`@starting-style` plus `transition-behavior: allow-discrete`**, which gives real enter _and_ exit transitions on a `display` change with no engine at all. The source is explicit that "dropping the engine is not a compromise here; it is the upgrade" — and the concrete payoff is that **it keeps working when the main thread is busy**, which the RAF originals do not. A page mid-hydration or mid-parse animates correctly here and janks in framer-motion.
+
+Dependency-free (Law 9) and timer-free (realm law): every effect is CSS.
+
+**Deliberately dropped** from the upstream surface: **layout animation** (morphing children through a shared layout needs FLIP measurement and a JS engine — render two Presences and stagger them with `@delay`), and **variant/keyframe objects** (a preset knob plus two custom properties covers the honest cases).
+
+## Accessibility
+
+No pattern governs it; the criteria are WCAG **2.3.3 Animation from Interactions** and **2.2.2**.
+
+The notable thing this does that the upstream does not:
+
+- **`inert` during the exit window.** `display: none` removes focusability once the transition ends, but there is a window in between where the content is still in the DOM, still focusable, and on its way out — a keyboard user can tab into content that is disappearing. Presence sets `inert` for exactly that window. **Upstream leaves that gap open.** This is a small, genuinely-better detail and worth knowing about.
+
+Gaps and cautions:
+
+- **There is no `prefers-reduced-motion` branch in this component.** Every other animated component in the kit has one; here the reduced-motion answer is presumably that the caller sets `@duration={{0}}`, or that a theme zeroes `--pretui-motion-distance`. Verify — an unguarded entrance and exit on every mounted element is exactly what **2.3.3** is about, and a component whose entire purpose is motion is the one that most needs the guard.
+- **Content appearing is not announced.** Presence is a visual transition, not a live region; if the content mattering is the point (an error, a result), pair it with a `role="status"` region that already exists in the DOM.
+- **Focus is not moved into entering content**, correctly — that is the caller's decision, and moving it automatically would be wrong for most uses.
+- **`@delay` staggering means later items appear after a measurable gap**; a screen-reader user encountering the DOM does not experience the stagger at all, which is fine, but do not use stagger to convey order.
+- Content that is `inert` on the way out is correctly unreachable; content on the way _in_ is reachable immediately, before the transition finishes.
+
+## Theming
+
+`--pretui-motion-distance` (default 8px, used by rise/fall/slide) and `--pretui-motion-scale` (default 0.96, used by scale) — two tokens that a theme sets once to give every Presence and **InView** in the product the same travel. Duration, exit duration and delay are args in seconds rather than tokens, so a theme cannot set a house pace; that is an inconsistency with the kit's `--pretui-dur-*` tokens elsewhere.
+
+Because the presets resolve _through_ those custom properties rather than baking in pixel values, a caller can override `--pretui-motion-distance` on an ancestor and every preset inside adapts — including a theme that wants near-zero travel for a calm feel, which is also the poor-man's reduced-motion switch.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,204 @@
+// Pretui — Presence usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { Button } from './button';
+import { Presence } from './presence';
+import type { MotionPreset } from '../internal/motion-core';
+import { PRESETS } from '../demo-motion-core';
+
+// ── Presence — fresh page (no upstream knob rig) ─────────────────────────
+class PresenceUsage extends Component {
+  @tracked show = true;
+  @tracked enter: MotionPreset = 'rise';
+  @tracked exit: MotionPreset = 'fade';
+  @tracked duration = 0.24;
+  @tracked exitDuration = 0.16;
+  @tracked delay = 0;
+  @tracked distance = 8;
+  @tracked scale = 0.96;
+  setShow = (v: boolean) => (this.show = v);
+  setEnter = (v: string) => (this.enter = v as MotionPreset);
+  setExit = (v: string) => (this.exit = v as MotionPreset);
+  setDuration = (v: number | null) => (this.duration = v ?? 0.24);
+  setExitDuration = (v: number | null) => (this.exitDuration = v ?? 0.16);
+  setDelay = (v: number | null) => (this.delay = v ?? 0);
+  setDistance = (v: number | null) => (this.distance = v ?? 8);
+  setScale = (v: number | null) => (this.scale = v ?? 0.96);
+  toggle = () => (this.show = !this.show);
+  get usage() {
+    let bits = [
+      `@show={{this.show}}`,
+      `@enter='${this.enter}'`,
+      `@exit='${this.exit}'`,
+      `@duration={{${this.duration}}}`,
+      `@exitDuration={{${this.exitDuration}}}`,
+    ];
+    if (this.delay) bits.push(`@delay={{${this.delay}}}`);
+    return `<Presence ${bits.join(' ')}>\n  <LotCard />\n</Presence>`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Presence'
+      @description='Enter and exit transitions for content that comes and goes — the CSS answer to AnimatePresence. @starting-style supplies the arriving state and transition-behavior: allow-discrete keeps display:block alive long enough to leave, so both halves run with no animation engine, no timers and no dependency. Presence owns visibility through @show: keep the content in the template rather than wrapping it in an if-block, or the exit half has nothing left to animate. Enter and exit are tuned separately, because arriving and leaving read differently.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='presence-stage'>
+          <Button
+            @size='xs'
+            @appearance='outlined'
+            {{on 'click' this.toggle}}
+          >{{if this.show 'Withdraw lot' 'Offer lot'}}</Button>
+          <Presence
+            @show={{this.show}}
+            @enter={{this.enter}}
+            @exit={{this.exit}}
+            @duration={{this.duration}}
+            @exitDuration={{this.exitDuration}}
+            @delay={{this.delay}}
+            @distance={{this.distance}}
+            @scale={{this.scale}}
+          >
+            <div class='presence-card'>
+              <p class='presence-title'>Da Hong Pao · lot B-1181</p>
+              <p class='presence-meta'>Wuyi Origins · Wuyishan · $102/kg</p>
+            </div>
+          </Presence>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Bool
+          @name='show'
+          @defaultValue={{true}}
+          @value={{this.show}}
+          @description='Visible when true. Presence owns display — while hidden the content is display:none (out of the accessibility tree) and inert during the exit window, so focus can never land inside something on its way out.'
+          @onInput={{this.setShow}}
+        />
+        <Args.String
+          @name='enter'
+          @defaultValue='fade'
+          @value={{this.enter}}
+          @options={{PRESETS}}
+          @description='Entrance preset. fade holds still; rise/fall travel on the block axis; slide travels on the inline axis; scale grows into place. All five resolve through --pretui-motion-distance / --pretui-motion-scale.'
+          @onInput={{this.setEnter}}
+        />
+        <Args.String
+          @name='exit'
+          @defaultValue='(matches @enter)'
+          @value={{this.exit}}
+          @options={{PRESETS}}
+          @description='Exit preset, settable independently of @enter (Law 7). A panel that rises in and simply fades out reads calmer than one that reverses its own entrance.'
+          @onInput={{this.setExit}}
+        />
+        <Args.Number
+          @name='duration'
+          @defaultValue={{0.22}}
+          @value={{this.duration}}
+          @min={{0.05}}
+          @max={{1.5}}
+          @step={{0.02}}
+          @description='Entrance duration in seconds.'
+          @onInput={{this.setDuration}}
+        />
+        <Args.Number
+          @name='exitDuration'
+          @defaultValue={{0.15}}
+          @value={{this.exitDuration}}
+          @min={{0.05}}
+          @max={{1.5}}
+          @step={{0.02}}
+          @description='Exit duration in seconds; defaults to two-thirds of @duration so leaving never lingers.'
+          @onInput={{this.setExitDuration}}
+        />
+        <Args.Number
+          @name='delay'
+          @defaultValue={{0}}
+          @value={{this.delay}}
+          @min={{0}}
+          @max={{1}}
+          @step={{0.05}}
+          @description='Seconds before entering — the timer-free way to stagger a group of Presences into one choreography. Applies to the enter half only.'
+          @onInput={{this.setDelay}}
+        />
+        <Args.Number
+          @name='distance'
+          @defaultValue={{8}}
+          @value={{this.distance}}
+          @min={{0}}
+          @max={{48}}
+          @step={{2}}
+          @description='Travel in px for rise / fall / slide.'
+          @onInput={{this.setDistance}}
+        />
+        <Args.Number
+          @name='scale'
+          @defaultValue={{0.96}}
+          @value={{this.scale}}
+          @min={{0.5}}
+          @max={{1}}
+          @step={{0.01}}
+          @description='Start scale for the scale preset.'
+          @onInput={{this.setScale}}
+        />
+        <Args.Yield
+          @name='default'
+          @description='The content whose arrival and departure is being staged. Rendered inside a wrapper div whose display comes from --pretui-presence-display (block by default; set it to flex or grid to keep a layout role).'
+        />
+        <Args.Base
+          @name='--pretui-presence-display'
+          @type='CSS'
+          @defaultValue='block'
+          @description='The display value the wrapper takes while shown.'
+        />
+        <Args.Base
+          @name='--pretui-motion-distance'
+          @type='CSS'
+          @defaultValue='8px'
+          @description='Travel for rise / fall / slide; @distance sets it.'
+        />
+        <Args.Base
+          @name='--pretui-motion-scale'
+          @type='CSS'
+          @defaultValue='0.96'
+          @description='Start scale for the scale preset; @scale sets it.'
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .presence-stage {
+        display: grid;
+        gap: var(--space-4, 11px);
+        justify-items: start;
+        min-height: 96px;
+      }
+      .presence-card {
+        padding: var(--space-4, 11px) var(--space-5, 15px);
+        border-radius: var(--radius-surface, 10px);
+        background: var(--card);
+        box-shadow: var(
+          --pretui-shadow-card,
+          0 0 0 1px var(--border),
+          0 1px 2px rgb(16 24 40 / 0.12)
+        );
+      }
+      .presence-title {
+        margin: 0;
+        font-size: var(--text-ui-lg, 15px);
+        font-weight: 600;
+        letter-spacing: var(--track-heading, -0.02em);
+        color: var(--foreground);
+      }
+      .presence-meta {
+        margin: 4px 0 0;
+        font-size: var(--text-ui, 12px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_PRESENCE: Record<string, unknown> = {
+  Presence: PresenceUsage,
+};

package/bundled-realms/pretui/components/progress-bar.gts

@@ -0,0 +1,177 @@
+// Pretui — ProgressBar: quantitative progress along a track.
+import Component from '@glimmer/component';
+import { htmlSafe } from '@ember/template';
+import { hueStyle } from '../internal/ink';
+
+export interface ProgressBarSignature {
+  Args: {
+    value: number;
+    max?: number;
+    label?: string;
+    count?: string;
+    valueText?: string;
+    hue?: string;
+    steps?: boolean;
+  };
+  Element: HTMLDivElement;
+}
+
+// Quantitative completion. Stepped mode for small discrete totals ("3 / 6").
+//
+// The root element is the `progressbar`, so `aria-label` and `aria-labelledby`
+// passed as attributes name it directly; `@label` names it otherwise, and a bar
+// with neither is named "Progress". The visible header sits inside the widget
+// and is hidden from assistive tech, which hears the name and value from the
+// ARIA attributes instead.
+export class ProgressBar extends Component<ProgressBarSignature> {
+  // A negative or non-finite `@max` reads as an empty range, so `aria-valuemax`
+  // never drops below `aria-valuemin` and the stepped track is always a finite
+  // row.
+  get max() {
+    let max = this.args.max ?? 100;
+    return Number.isFinite(max) ? Math.max(0, max) : 0;
+  }
+  // `@value` clamped into [0, max], with an unset or non-finite value read as
+  // 0, so `aria-valuenow` always sits between `aria-valuemin` and
+  // `aria-valuemax`. It is also what a sighted user sees: a continuous bar's
+  // fill paints the exact value, and a stepped bar lights a partly reached step
+  // whole, so with a whole-number `@max` the value there rounds up to the
+  // number of lit steps (2.5 of 6 lights and announces 3), as Meter does with a
+  // fractional level. Stepped mode is for small discrete totals, so a
+  // fractional `@max` isn't meant to be used there: it draws `Math.ceil(max)`
+  // steps against the raw max, and the outer `Math.min` (a no-op for a
+  // whole-number `@max`) keeps the value within `aria-valuemax` rather than
+  // matching the lit steps.
+  get valueNow() {
+    let value = Number.isFinite(this.args.value) ? this.args.value : 0;
+    let clamped = Math.max(0, Math.min(value, this.max));
+    return this.stepped ? Math.min(Math.ceil(clamped), this.max) : clamped;
+  }
+  // A zero `@max` has no fraction to show, so any value against it reads as an
+  // empty bar at 0%, with no division by zero.
+  get pct() {
+    return this.max > 0 ? (this.valueNow / this.max) * 100 : 0;
+  }
+  get stepped() {
+    return this.args.steps ?? (this.args.count !== undefined && this.max <= 12);
+  }
+  get countText() {
+    return this.args.count ?? `${Math.round(this.pct)}%`;
+  }
+  get fillStyle() {
+    return htmlSafe(`width: ${this.pct}%; min-width: ${this.pct > 0 ? '0.25rem' : 0}`);
+  }
+  get stepList(): { on: boolean }[] {
+    let out = [];
+    for (let i = 0; i < this.max; i++) {
+      out.push({ on: i < this.valueNow });
+    }
+    return out;
+  }
+  // A `progressbar` must have an accessible name, so an unnamed bar falls back
+  // to a generic one, as boxel-ui's ProgressBar does. A caller's `aria-label`
+  // replaces it (`...attributes` comes after it on the root), and a caller's
+  // `aria-labelledby` takes precedence over any `aria-label` in the
+  // accessible-name computation.
+  get accessibleLabel() {
+    return this.args.label || 'Progress';
+  }
+  get showHeader() {
+    return this.args.label || this.args.count !== undefined;
+  }
+  // A caller's words for the value win. In stepped mode the visible count is
+  // next, since it is already the human reading and carries the total
+  // ("3 / 6"). A continuous bar's count can omit the total ("300 files"), so
+  // there assistive tech keeps deriving a percentage from the value range.
+  get valueText() {
+    return this.args.valueText ?? (this.stepped ? this.args.count : undefined);
+  }
+  get style() {
+    return hueStyle('--pretui-progress-hue', this.args.hue);
+  }
+  <template>
+    <div
+      class='pretui-progresswrap'
+      role='progressbar'
+      aria-label={{this.accessibleLabel}}
+      aria-valuemin='0'
+      aria-valuenow={{this.valueNow}}
+      aria-valuemax={{this.max}}
+      aria-valuetext={{this.valueText}}
+      style={{this.style}}
+      data-test-pretui-progress
+      ...attributes
+    >
+      {{#if this.showHeader}}
+        <div class='pretui-progress-head' aria-hidden='true'>
+          <span>{{@label}}</span>
+          <span class='pretui-progress-count'>{{this.countText}}</span>
+        </div>
+      {{/if}}
+      {{#if this.stepped}}
+        <div class='pretui-progress-steps'>
+          {{#each this.stepList as |s|}}
+            <span class='pretui-progress-step' data-on={{if s.on 'true'}}></span>
+          {{/each}}
+        </div>
+      {{else}}
+        <div class='pretui-progress'>
+          <div class='pretui-progress-fill' style={{this.fillStyle}}></div>
+        </div>
+      {{/if}}
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-progresswrap {
+          display: grid;
+          gap: var(--boxel-sp-3xs);
+        }
+        .pretui-progress-head {
+          display: flex;
+          justify-content: space-between;
+          align-items: last baseline;
+          font-size: var(--boxel-font-size-xs);
+          color: var(--muted-foreground);
+        }
+        .pretui-progress-count {
+          font-family: var(--font-mono);
+          font-size: var(--boxel-font-size-2xs);
+          font-variant-numeric: tabular-nums;
+          color: var(--foreground);
+        }
+        .pretui-progress {
+          height: 0.25rem;
+          border-radius: var(--boxel-border-radius-2xs);
+          background-color: var(--inset);
+          overflow: hidden;
+        }
+        .pretui-progress-fill {
+          height: 100%;
+          border-radius: var(--boxel-border-radius-2xs);
+          background-color: var(--pretui-progress-hue, var(--primary));
+          transition: width var(--pretui-dur-morph, 300ms) var(--pretui-ease-morph, ease-out);
+        }
+        .pretui-progress-steps {
+          display: flex;
+          gap: var(--boxel-sp-5xs);
+        }
+        .pretui-progress-step {
+          flex: 1;
+          height: 0.25rem;
+          border-radius: var(--boxel-border-radius-2xs);
+          background-color: var(--inset);
+          transition: background-color var(--pretui-dur-morph, 300ms) var(--pretui-ease-morph, ease-out);
+        }
+        .pretui-progress-step[data-on] {
+          background-color: var(--pretui-progress-hue, var(--primary));
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-progress-fill,
+          .pretui-progress-step {
+            transition: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/progress-bar.md

@@ -0,0 +1,63 @@
+## What it is
+
+Quantitative completion: how much of a known task is done. Two renders from one component — a continuous bar for percentages, and a **stepped** row of segments for small discrete totals ("3 / 6"). Reach for it when there is a real numerator and denominator. If the number is a _measurement_ within a range rather than progress toward completion — disk used, score, capacity — use **Meter**, which is a different pattern and deliberately looks different. If the duration is unknown, use **Spinner** or **LoadingState**.
+
+## The contract
+
+```
+@value: number   (required)
+@max? (100), @label?, @count?, @valueText?, @hue?, @steps?
+...attributes → the progressbar element (aria-label, aria-labelledby, …)
+```
+
+**The stepped/continuous choice is inferred, not configured.** `@steps` forces it, but the default is `@count !== undefined && @max <= 12` — pass a count and a small max and you get discrete segments, because six segments read faster than a bar at 50%. Twelve is the cutoff where segments stop being countable at a glance.
+
+`@count` is a _display override_, not the value: pass `'3 / 6'` and the header shows that instead of `50%`. The header only renders when `@label` or `@count` is present, so a bare bar has no chrome.
+
+**The root element is the `progressbar`.** Attributes passed to the component land on the widget itself, so a bar with no visible header is named with `aria-label='Time left before the SLA breaches'`, or pointed at a heading with `aria-labelledby`. `@label` both shows the header text and names the bar; a caller's `aria-label` wins over it. A bar named by none of these is called "Progress", as boxel-ui's ProgressBar is, so it never renders as a nameless `progressbar`.
+
+`@valueText` is the announced reading of the value when the number alone would mislead (a run that ended early fills every segment, but "6 of 6" is not what happened). It changes what assistive tech hears, not what the header shows. In stepped mode it defaults to `@count`; a continuous bar announces a percentage unless `@valueText` is given, since its count ("300 files") need not carry the total.
+
+`@hue` paints the fill (and the lit segments) in any CSS color, typically a state hue: `@hue='var(--warning)'`. It is the same one-color arg as Meter's and Chip's `@hue`, and like theirs it writes a per-component custom property, `--pretui-progress-hue`, on the root, so the same knob can also be set on any ancestor, or in a caller's `style`. A caller's `style` attribute replaces the component's own, so a bar that takes a `style` carries the knob in it rather than in `@hue`.
+
+`min-width: 0.25rem` on a non-zero fill is the detail that stops 1% from rendering as nothing — a bar that shows no progress when progress exists is worse than no bar.
+
+## Prior art
+
+**Web Awesome `wa-progress-bar`** has `value`, `indeterminate` and `label`, hardcodes `aria-valuemin="0"`/`aria-valuemax="100"`, and — less correctly — sends `aria-valuenow="0"` when indeterminate. **React Aria `useProgressBar`** sets `aria-valuenow` and `aria-valuetext` to `undefined` when indeterminate, which is the right handling: an indeterminate progress bar has no value, and asserting zero is a lie. **Radix `Progress`** composes `Root`/`Indicator` with `value`, `max` and `getValueLabel`, and models `null` as indeterminate.
+
+Pretui's differentiator is the **stepped mode**, which none of the three ships. For "3 of 6 approvals" a segmented row communicates the denominator visually, and a percentage bar does not. Inferring it from the data rather than exposing another mode arg is the good version of that idea.
+
+Where it is behind: **there is no indeterminate state at all.** That is the single most-used progress variant in the field and it is absent — for an unknown-duration operation you must switch to **Spinner** or **LoadingState**, which is a different visual language mid-operation.
+
+## Accessibility
+
+Governing role: `progressbar` with `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, and `aria-valuetext` when the raw number is not human-meaningful.
+
+What it does:
+
+- **The root element carries `role="progressbar"`** with `aria-valuemin="0"`, `aria-valuenow` and `aria-valuemax`, so `...attributes` reach the widget: `aria-label` and `aria-labelledby` name it directly.
+- **`aria-valuenow` is `@value` clamped to `[0, @max]`**, the same clamp the fill, the lit steps and the visible percentage use, so `@value={{180}}` against a max of 100 is announced as 100, and what assistive tech hears matches the bar a sighted user sees. A stepped bar lights a partly reached step whole, so with a whole-number `@max` the value there rounds up to the number of lit steps: `@value={{2.5}} @max={{6}} @steps={{true}}` lights three steps and announces 3 (and a percentage header reads 50%). Stepped mode is for small discrete totals, so a fractional `@max` isn't meant to be used there: it draws whole steps up to the next integer while `aria-valuemax` and a percentage header keep the raw max, and the two don't agree. A continuous bar keeps the exact value, which is the width its fill paints. An unset or non-finite `@value` reads as 0, and a negative or non-finite `@max` as 0, so `aria-valuenow` never reads `NaN` and `aria-valuemax` never drops below `aria-valuemin`. A `@max` of 0 is an empty range: any value against it is announced as 0, and the continuous bar is empty at 0%. A stepped bar with a `@max` of 0 has no segments, so its track renders nothing and only the header (when there is one) shows.
+- **`@label` is the accessible name** as well as the visible header text. A caller's `aria-label` replaces it, and a caller's `aria-labelledby` takes precedence over both. A bar with none of these falls back to the name "Progress", so it passes the role's required-name rule, but a screen-reader user still hears "Progress, 60%" with no idea what is progressing — name it.
+- **`aria-valuetext`** is `@valueText` when given. In stepped mode it falls back to `@count`, so the bar announces "3 / 6" where "3" alone would be meaningless. A continuous bar does not fall back to its count, which can drop the total ("300 files"), so with no `@valueText` assistive tech derives a percentage from the value range.
+- **The visible header is inside the widget and `aria-hidden`.** The name and value already say what the label and count show, so they are not announced a second time as loose text.
+
+Gaps, and they are the kind that pass review by looking present:
+
+- **No announcement on change.** A progress bar that advances silently is correct for a fast operation and unhelpful for a slow one; there is no live region and no hook for one.
+- **The fill fails WCAG 1.4.11 Non-text Contrast (3:1) against its track in the boxel light default theme.** The fill (`--pretui-progress-hue`, default `--primary`) sits on `--inset` with no border, and stepped mode tells lit from unlit segments by that color alone. In the boxel light default, `--primary` (`--boxel-teal`, `#00ffba`) on `--inset` (`#f5f5f5`) is 1.2:1, against the 3:1 that 1.4.11 requires; a lighter track cannot fix it (teal on white is 1.31:1), so a light-theme `3 / 6` bar reads as empty. The dark default passes (10.2:1 on `#302d3b`). The fill has to darken in light mode.
+- The 0.25rem bar height is below any comfortable pointer target, but nothing here is interactive, so 2.5.8 does not apply.
+
+## Theming
+
+`--pretui-progress-hue` (the fill and lit segments; defaults to `--primary`, set by `@hue` or on any ancestor), `--inset` (track and unlit segments), `--muted-foreground` (label), `--foreground` (count), `--font-mono` + `--boxel-font-size-2xs` (the count's tabular-figure voice), `--boxel-font-size-xs` (the header), `--pretui-dur-morph` / `--pretui-ease-morph` (optional knobs for the fill transition; nothing in the boxel theme defines them, so the fallbacks `300ms` and `ease-out` apply unless a caller sets them). The fill and step transitions are turned off under `prefers-reduced-motion: reduce`.
+
+The 0.25rem height, `--boxel-border-radius-2xs` radius and `--boxel-sp-5xs` step gap are fixed. The theme (the boxel default and any card's Theme) must keep `--primary` (and a caller any `--pretui-progress-hue` it sets) and `--inset` at 3:1 or more in luminance, not just different in hue — that separation is the entire signal in stepped mode. The boxel light default does not meet it today (`--primary` on `--inset` is 1.2:1, see Accessibility); the dark default does.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+shadcn `Progress`. Ant `Progress`. Aria `ProgressBar`. Indeterminate
+is **Spinner**, not a bar with no value. Accept `value` / `max` /
+`isIndeterminate` (→ Spinner or a recipe).