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

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

@@ -0,0 +1,222 @@
+// Pretui — ScrollProgress: a reading-progress ribbon bound to scroll position.
+import Component from '@glimmer/component';
+import { htmlSafe } from '@ember/template';
+import { modifier } from 'ember-modifier';
+import { cssNumber } from '../pretui-css';
+
+// ── scrollProgress (modifier) + ScrollProgress ───────────────────────────
+// Reading-progress ribbon bound to scroll position.
+//
+// Ported from motion-primitives' <ScrollProgress>, which subscribes to
+// framer-motion's useScroll — a scroll listener feeding a spring on every
+// frame — and renders a bare <div> with no role, no label, and no
+// reduced-motion consideration.
+//
+// Better than the inspiration: the default path is a pure CSS scroll-driven
+// animation (`animation-timeline: scroll()`), which runs off the main thread
+// entirely — no listener, no frame loop, no jank while the page is busy.
+// Where scroll timelines are unavailable, or where the caller opts into
+// announcing progress, the modifier installs a *passive scroll listener*
+// (an event listener, not a timer) and writes the ratio into the same custom
+// property the CSS path animates, so exactly one set of styles serves both.
+//
+// Accessibility, which upstream skips entirely: a reading ribbon is chrome —
+// the scroll container already reports position to assistive tech, and a
+// second, unlabelled progressbar is noise. So the default is
+// `aria-hidden='true'` by deliberate choice, documented here rather than by
+// omission. Callers who genuinely need it announced pass @label with
+// @announce, which switches on `role='progressbar'` with a live
+// `aria-valuenow` — and necessarily switches to the listener path, because a
+// CSS scroll timeline's position is not observable from script.
+//
+// Dropped upstream surface: `springOptions` (a spring lag between the
+// scrollbar and the ribbon makes the readout wrong; a progress indicator is
+// a direct readout, not an animation) and the container-ref prop (@source
+// resolves the scroller from the DOM instead).
+function nearestScroller(el: HTMLElement): HTMLElement {
+  let node = el.parentElement;
+  while (node) {
+    // Declared overflow, not current overflow: the modifier installs before
+    // the sibling content that will make the box scroll, so measuring
+    // scrollHeight here would walk straight past the intended scroller.
+    let overflow = getComputedStyle(node).overflowY;
+    if (overflow === 'auto' || overflow === 'scroll' || overflow === 'overlay') {
+      return node;
+    }
+    node = node.parentElement;
+  }
+  return (document.scrollingElement as HTMLElement) ?? document.documentElement;
+}
+
+/**
+ * Degradation + announcement path for `<ScrollProgress />`. No-ops (leaving
+ * the CSS scroll timeline in charge) when scroll-driven animations are
+ * supported and nothing needs announcing.
+ */
+export const scrollProgress = modifier(
+  (el: HTMLElement, [source, announce]: ['page' | 'nearest', boolean]) => {
+    let cssDriven =
+      !announce &&
+      typeof CSS !== 'undefined' &&
+      typeof CSS.supports === 'function' &&
+      CSS.supports('animation-timeline', 'scroll()');
+    if (cssDriven) return;
+    el.setAttribute('data-js', 'true');
+    let scroller =
+      source === 'nearest'
+        ? nearestScroller(el)
+        : ((document.scrollingElement as HTMLElement) ??
+          document.documentElement);
+    let target: EventTarget =
+      scroller === document.scrollingElement ||
+      scroller === document.documentElement
+        ? window
+        : scroller;
+    let update = () => {
+      let max = scroller.scrollHeight - scroller.clientHeight;
+      let ratio = max > 0 ? scroller.scrollTop / max : 0;
+      ratio = Math.min(Math.max(ratio, 0), 1);
+      el.style.setProperty('--pretui-scroll-progress', ratio.toFixed(4));
+      if (announce) {
+        el.setAttribute('aria-valuenow', String(Math.round(ratio * 100)));
+      }
+    };
+    update();
+    target.addEventListener('scroll', update, { passive: true });
+    window.addEventListener('resize', update);
+    return () => {
+      target.removeEventListener('scroll', update);
+      window.removeEventListener('resize', update);
+    };
+  },
+);
+
+export interface ScrollProgressSignature {
+  Args: {
+    /** 'page' (default) tracks the document; 'nearest' tracks the closest scrolling ancestor — the ribbon must live inside it */
+    source?: 'page' | 'nearest';
+    /** ribbon thickness in px */
+    thickness?: number;
+    /** show the unfilled remainder as a track (default true) — this is what makes the component legible in a still frame */
+    track?: boolean;
+    /** 'none' (default) leaves placement to the caller; 'top' / 'bottom' stick the ribbon to that edge of its scroll container */
+    affix?: 'none' | 'top' | 'bottom';
+    /** accessible name — required when @announce is true */
+    label?: string;
+    /** expose the ribbon as a live progressbar to assistive tech. Off by default: see the a11y note in the source. Forces the scroll-listener path. */
+    announce?: boolean;
+  };
+  Element: HTMLDivElement;
+}
+
+export class ScrollProgress extends Component<ScrollProgressSignature> {
+  get source(): 'page' | 'nearest' {
+    return this.args.source ?? 'page';
+  }
+  get announce(): boolean {
+    return this.args.announce ?? false;
+  }
+  get hidden(): 'true' | undefined {
+    return this.announce ? undefined : 'true';
+  }
+  get role(): string | undefined {
+    return this.announce ? 'progressbar' : undefined;
+  }
+  get affix(): string {
+    return this.args.affix ?? 'none';
+  }
+  get showTrack(): boolean {
+    return this.args.track ?? true;
+  }
+  get style(): ReturnType<typeof htmlSafe> {
+    let bits: string[] = [];
+    {
+      let n = cssNumber(this.args.thickness, 0, 1000);
+      if (n !== undefined) {
+        bits.push(`--pretui-scrollprogress-thickness: ${n}px`);
+      }
+    }
+    return htmlSafe(bits.join('; '));
+  }
+  <template>
+    <div
+      class='pretui-scrollprogress'
+      data-source={{this.source}}
+      data-affix={{this.affix}}
+      data-track={{if this.showTrack 'true' 'false'}}
+      style={{this.style}}
+      role={{this.role}}
+      aria-hidden={{this.hidden}}
+      aria-label={{if this.announce @label}}
+      aria-valuemin={{if this.announce '0'}}
+      aria-valuemax={{if this.announce '100'}}
+      data-test-pretui-scroll-progress
+      {{scrollProgress this.source this.announce}}
+      ...attributes
+    >
+      <span class='pretui-scrollprogress-fill'></span>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-scrollprogress {
+          position: relative;
+          overflow: hidden;
+          height: var(--pretui-scrollprogress-thickness, 3px);
+          border-radius: var(--pretui-scrollprogress-radius, 999px);
+        }
+        .pretui-scrollprogress[data-track='true'] {
+          background: var(
+            --pretui-scrollprogress-track,
+            color-mix(in oklch, var(--foreground) 10%, transparent)
+          );
+        }
+        .pretui-scrollprogress[data-affix='top'] {
+          position: sticky;
+          inset-block-start: 0;
+          z-index: 2;
+        }
+        .pretui-scrollprogress[data-affix='bottom'] {
+          position: sticky;
+          inset-block-end: 0;
+          z-index: 2;
+        }
+        .pretui-scrollprogress-fill {
+          position: absolute;
+          inset: 0;
+          transform-origin: left center;
+          transform: scaleX(var(--pretui-scroll-progress, 0));
+          border-radius: inherit;
+          background: var(--pretui-scrollprogress-fill, var(--primary));
+        }
+        @keyframes pretui-scrollprogress-grow {
+          from {
+            transform: scaleX(0);
+          }
+          to {
+            transform: scaleX(1);
+          }
+        }
+        /* The preferred path: the compositor drives this off the scroll
+           timeline, so it never touches the main thread. [data-js] is written
+           by the modifier only when it has taken over. Order matters — the
+           `animation` shorthand resets animation-timeline, so the timeline
+           longhand has to come after it. */
+        @supports (animation-timeline: scroll()) {
+          .pretui-scrollprogress[data-source='page']:not([data-js])
+            .pretui-scrollprogress-fill {
+            animation: pretui-scrollprogress-grow linear both;
+            animation-timeline: scroll(root block);
+          }
+          .pretui-scrollprogress[data-source='nearest']:not([data-js])
+            .pretui-scrollprogress-fill {
+            animation: pretui-scrollprogress-grow linear both;
+            animation-timeline: scroll(nearest block);
+          }
+        }
+        /* No reduced-motion branch by design: the ribbon is a 1:1 readout of
+           scroll position with no easing, no lag and no independent movement,
+           so there is nothing for prefers-reduced-motion to reduce. */
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,48 @@
+## What it is
+
+A reading-progress ribbon bound to scroll: a filled bar that tracks how far through a document, or a scrolling container, the reader has got.
+
+## The contract
+
+```
+@source?    — 'page' (default) tracks the document; 'nearest' tracks the closest
+              scrolling ancestor — the ribbon must live inside it
+@thickness? — ribbon thickness in px
+@track?     — show the unfilled remainder. Default true
+@affix?     — 'none' (default) leaves placement to the caller; 'top' / 'bottom'
+              stick the ribbon to that edge of its scroll container
+@label?     — accessible name; required when @announce is true
+@announce?  — expose the ribbon as a live progressbar to assistive tech. Off by default
+```
+
+**It prefers a scroll-driven CSS animation and falls back to a listener.** When the browser supports `animation-timeline: scroll()` and the ribbon is not announcing, the fill is computed by the compositor with no JavaScript on the scroll path at all. Otherwise a passive scroll listener writes a ratio into a custom property.
+
+**`@announce` forces the listener path**, because `aria-valuenow` has to be written by script — there is no declarative way to keep an ARIA value in sync with a CSS scroll timeline.
+
+**`@track` defaults to true, and it is what makes the component legible in a still frame.** A bare fill with no remainder reads as a coloured line rather than as progress.
+
+**`@source='nearest'` requires the ribbon to live inside the container it tracks.**
+
+## Prior art
+
+**motion-primitives' ScrollProgress**, with fancy's parallax family as a cousin.
+
+Where Pretui is better: **the CSS scroll-timeline path.** Upstream implementations attach a scroll listener unconditionally and update state on every scroll event; here that is the fallback, not the default, so on a modern browser the ribbon costs nothing on the scroll path. The track is also on by default rather than being an afterthought.
+
+Where it is thinner: no horizontal-scroll source, no segment or chapter markers along the ribbon, no circular variant, and no reading-time estimate. The fill is linear with no easing.
+
+## Accessibility
+
+- **The ribbon is `aria-hidden` by default, and that is deliberate.** A progress bar that updates continuously as someone scrolls is a live region that never stops talking — for most readers it is noise, and the scroll position is already perceivable through the content itself.
+- **`@announce` is the opt-in for the cases where it genuinely helps** — a long legal document, a form-like reading flow — and it requires `@label`, because an unnamed progressbar tells a listener nothing.
+- **With `@announce` on, the value is rounded to whole percent.** A `aria-valuenow` updating on a fractional ratio would be unbearable.
+- **The ribbon is never focusable and never interactive.** It reports; it does not seek.
+- **Colour alone carries the fill.** With `@track={{false}}` there is no boundary between filled and unfilled, so the progress is conveyed by extent against nothing — keep the track.
+
+## Theming
+
+`--pretui-scroll-progress` (the 0–1 ratio, written by either path), `--pretui-scrollprogress-fill`, `--pretui-scrollprogress-track`, `--pretui-scrollprogress-thickness` (from `@thickness`), `--pretui-scrollprogress-radius`.
+
+Splitting fill and track into two tokens is what lets a theme set the contrast between them; a theme that makes them too close produces a ribbon that is technically animating and practically invisible, which is the failure mode to check in a dark palette.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/scroll-progress.usage.gts

@@ -0,0 +1,162 @@
+// Pretui — ScrollProgress usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { array } from '@ember/helper';
+import { FreestyleUsage } from './freestyle-usage';
+import { TASKS } from '../examples';
+import { ScrollProgress } from './scroll-progress';
+
+// ── ScrollProgress — fresh page (no upstream knob rig) ───────────────────
+class ScrollProgressUsage extends Component {
+  @tracked thickness = 3;
+  @tracked track = true;
+  @tracked affix: 'none' | 'top' | 'bottom' = 'top';
+  @tracked announce = false;
+  @tracked label = 'Harvest ledger read progress';
+  setThickness = (v: number | null) => (this.thickness = v ?? 3);
+  setTrack = (v: boolean) => (this.track = v);
+  setAffix = (v: string) => (this.affix = v as 'none' | 'top' | 'bottom');
+  setAnnounce = (v: boolean) => (this.announce = v);
+  setLabel = (v: string) => (this.label = v);
+  get paragraphs(): string[] {
+    return TASKS.slice(0, 10) as string[];
+  }
+  get usage() {
+    let bits = [
+      `@source='nearest'`,
+      `@affix='${this.affix}'`,
+      `@thickness={{${this.thickness}}}`,
+    ];
+    if (!this.track) bits.push('@track={{false}}');
+    if (this.announce) bits.push(`@announce={{true}} @label='${this.label}'`);
+    return `<ScrollProgress ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='ScrollProgress'
+      @description="Reading-progress ribbon bound to scroll position. The default path is a pure CSS scroll-driven animation (animation-timeline: scroll()), which runs off the main thread — no scroll listener, no frame loop, nothing to jank. Where scroll timelines are unavailable, a passive scroll listener in a modifier writes the same custom property, so one set of styles serves both paths. It is aria-hidden by default on purpose: the scroll container already reports position to assistive tech, and a second unlabelled progressbar is noise — pass @announce with @label when the ribbon is genuinely the primary readout."
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='sp-scroller'>
+          <ScrollProgress
+            @source='nearest'
+            @affix={{this.affix}}
+            @thickness={{this.thickness}}
+            @track={{this.track}}
+            @announce={{this.announce}}
+            @label={{this.label}}
+          />
+          <h4 class='sp-title'>Harvest ledger — spring season</h4>
+          {{#each this.paragraphs as |task|}}
+            <p class='sp-para'>{{task}} before the Wuyishan curing room reopens.
+              The cupping panel wants the scorecards filed alongside the
+              humidity logs, and the customs paperwork trails the shipment by a
+              week.</p>
+          {{/each}}
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='source'
+          @defaultValue='page'
+          @options={{array 'page' 'nearest'}}
+          @description="'page' tracks the document (scroll(root block)); 'nearest' tracks the closest scrolling ancestor, in which case the ribbon must live inside that scroller. Fixed to 'nearest' in this example so the effect is visible inside the workbench."
+        />
+        <Args.String
+          @name='affix'
+          @defaultValue='none'
+          @value={{this.affix}}
+          @options={{array 'none' 'top' 'bottom'}}
+          @description="'none' leaves placement to the caller; 'top' / 'bottom' stick the ribbon to that edge of its scroll container."
+          @onInput={{this.setAffix}}
+        />
+        <Args.Number
+          @name='thickness'
+          @defaultValue={{3}}
+          @value={{this.thickness}}
+          @min={{1}}
+          @max={{16}}
+          @step={{1}}
+          @description='Ribbon thickness in px.'
+          @onInput={{this.setThickness}}
+        />
+        <Args.Bool
+          @name='track'
+          @defaultValue={{true}}
+          @value={{this.track}}
+          @description='Show the unfilled remainder. This is what gives the component a defensible resting appearance at scroll position zero (Law 8) — turn it off only where another surface supplies the groove.'
+          @onInput={{this.setTrack}}
+        />
+        <Args.Bool
+          @name='announce'
+          @defaultValue={{false}}
+          @value={{this.announce}}
+          @description='Expose the ribbon as role=progressbar with a live aria-valuenow. Off by default (see the description). Turning it on forces the scroll-listener path, because a CSS scroll timeline is not observable from script.'
+          @onInput={{this.setAnnounce}}
+        />
+        <Args.String
+          @name='label'
+          @defaultValue=''
+          @value={{this.label}}
+          @description='Accessible name. Required whenever @announce is true; ignored otherwise.'
+          @onInput={{this.setLabel}}
+        />
+        <Args.Base
+          @name='--pretui-scrollprogress-fill'
+          @type='CSS'
+          @defaultValue='var(--primary)'
+          @description='Colour of the filled portion.'
+        />
+        <Args.Base
+          @name='--pretui-scrollprogress-track'
+          @type='CSS'
+          @defaultValue='foreground at 10%'
+          @description='Colour of the unfilled groove.'
+        />
+        <Args.Base
+          @name='--pretui-scrollprogress-thickness'
+          @type='CSS'
+          @defaultValue='3px'
+          @description='Ribbon thickness; @thickness sets it.'
+        />
+        <Args.Base
+          @name='--pretui-scrollprogress-radius'
+          @type='CSS'
+          @defaultValue='999px'
+          @description='Ribbon corner radius — set 0 for a square-ended rule.'
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .sp-scroller {
+        height: 240px;
+        overflow-y: auto;
+        padding: 0 var(--space-4, 11px) var(--space-4, 11px);
+        border-radius: var(--radius-surface, 10px);
+        background: var(--card);
+        box-shadow: var(
+          --pretui-shadow-hairline,
+          0 0 0 1px var(--border)
+        );
+      }
+      .sp-title {
+        margin: var(--space-4, 11px) 0 var(--space-3, 8px);
+        font-size: var(--text-ui-lg, 15px);
+        font-weight: 600;
+        letter-spacing: var(--track-heading, -0.02em);
+        color: var(--foreground);
+      }
+      .sp-para {
+        margin: 0 0 var(--space-4, 11px);
+        font-size: var(--text-ui-md, 12.5px);
+        line-height: 1.6;
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_SCROLL_PROGRESS: Record<string, unknown> = {
+  ScrollProgress: ScrollProgressUsage,
+};