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

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

@@ -0,0 +1,323 @@
+// Pretui — Scroller: a scroll container with edge fades or shadows that show more content is there.
+import Component from '@glimmer/component';
+import { modifier } from 'ember-modifier';
+
+// ── Scroller ─────────────────────────────────────────────────────────────
+
+export type ScrollerOrientation = 'horizontal' | 'vertical' | 'both';
+export type ScrollerEdge = 'fade' | 'shadow' | 'none';
+
+/**
+ * Maintains the four edge facts as DATA ATTRIBUTES on the viewport, and
+ * makes the viewport keyboard-reachable exactly when it actually scrolls.
+ *
+ * Written as attributes rather than tracked state on purpose: a scroll
+ * listener that writes tracked state re-renders the component on every
+ * frame of a flick. These attributes are read only by CSS, so the whole
+ * affordance costs one `setAttribute` and no render at all.
+ *
+ * `tabindex` is managed here too. A scroll container that a mouse user can
+ * reach and a keyboard user cannot is a keyboard trap in reverse — the
+ * content is simply unreachable. Chromium and Firefox have started making
+ * scrollers focusable natively; this keeps the guarantee everywhere, and
+ * REMOVES the tab stop again when the content shrinks and no longer
+ * overflows, which is the part native focusable-scrollers gets right and
+ * hand-rolled `tabindex='0'` does not.
+ */
+const scrollEdges = modifier(
+  (element: HTMLElement, [orientation]: [ScrollerOrientation]) => {
+    let update = () => {
+      let horizontal = orientation !== 'vertical';
+      let vertical = orientation !== 'horizontal';
+      // 1px of slack: sub-pixel layout means scrollLeft rarely reaches
+      // exactly scrollWidth - clientWidth, and a permanently-visible "there
+      // is more" fade at a hard stop is a lie.
+      let overflowX = element.scrollWidth - element.clientWidth > 1;
+      let overflowY = element.scrollHeight - element.clientHeight > 1;
+      let left = Math.abs(element.scrollLeft);
+      element.dataset['startX'] =
+        horizontal && overflowX && left > 1 ? 'clipped' : 'flush';
+      element.dataset['endX'] =
+        horizontal && overflowX && left < element.scrollWidth - element.clientWidth - 1
+          ? 'clipped'
+          : 'flush';
+      element.dataset['startY'] =
+        vertical && overflowY && element.scrollTop > 1 ? 'clipped' : 'flush';
+      element.dataset['endY'] =
+        vertical &&
+        overflowY &&
+        element.scrollTop < element.scrollHeight - element.clientHeight - 1
+          ? 'clipped'
+          : 'flush';
+
+      let scrollable = (horizontal && overflowX) || (vertical && overflowY);
+      if (scrollable) {
+        if (element.getAttribute('tabindex') === null) {
+          element.setAttribute('tabindex', '0');
+        }
+      } else if (element.getAttribute('tabindex') === '0') {
+        element.removeAttribute('tabindex');
+      }
+    };
+
+    element.addEventListener('scroll', update, { passive: true });
+    // Content can change size without a scroll ever happening — a lazy image
+    // landing, a theme change altering the type scale. Observing the viewport
+    // AND its content covers both directions. Content inserted later can grow
+    // the scroll extent while every observed box keeps its size (a slide
+    // appended to a full-width flex track), so DOM changes re-measure too and
+    // hand new direct children to the resize observer.
+    // observer callbacks coalesce into one measurement per frame; the frame
+    // is owned here and cancelled on teardown
+    let frame: number | undefined;
+    let schedule = () => {
+      if (frame !== undefined) {
+        return;
+      }
+      frame = requestAnimationFrame(() => {
+        frame = undefined;
+        update();
+      });
+    };
+    let observer = new ResizeObserver(schedule);
+    let observeChildren = () => {
+      for (let child of Array.from(element.children)) {
+        observer.observe(child);
+      }
+    };
+    observer.observe(element);
+    observeChildren();
+    let mutations = new MutationObserver(() => {
+      observeChildren();
+      schedule();
+    });
+    mutations.observe(element, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+    });
+    update();
+
+    return () => {
+      element.removeEventListener('scroll', update);
+      observer.disconnect();
+      mutations.disconnect();
+      if (frame !== undefined) {
+        cancelAnimationFrame(frame);
+      }
+    };
+  },
+);
+
+export interface ScrollerSignature {
+  Args: {
+    /** Which axes may scroll. Default `horizontal`. */
+    orientation?: ScrollerOrientation;
+    /** Accessible name. Supplying one promotes the viewport to a landmark
+     * `region`, which is what makes it findable by rotor — without a name a
+     * region is noise, so the role is not applied unless it is named. */
+    label?: string;
+    /** Edge treatment: a `fade` (default), an inset `shadow`, or `none`. */
+    edge?: ScrollerEdge;
+    /** Hide the native scrollbar. The edge affordance stays — which is the
+     * whole reason hiding it is defensible at all. */
+    hideScrollbar?: boolean;
+  };
+  Blocks: { default: [] };
+  Element: HTMLDivElement;
+}
+
+/**
+ * A scroll container that says when it is clipped.
+ *
+ * ```hbs
+ * <Scroller @label='Recent lots' @orientation='horizontal'>
+ *   <div class='row'>…</div>
+ * </Scroller>
+ * ```
+ *
+ * Better than the inspiration (`wa-scroller`): upstream ships one shadow
+ * treatment, both axes always on, and no notion of whether the region is
+ * reachable by keyboard. Here the axis is explicit, the treatment is a knob,
+ * the tab stop appears and DISAPPEARS with the overflow, and the affordance
+ * is driven by data attributes rather than by re-rendering on every scroll
+ * frame.
+ */
+export class Scroller extends Component<ScrollerSignature> {
+  get orientation(): ScrollerOrientation {
+    return this.args.orientation ?? 'horizontal';
+  }
+  get edge(): ScrollerEdge {
+    return this.args.edge ?? 'fade';
+  }
+  get role(): string | undefined {
+    return this.args.label ? 'region' : undefined;
+  }
+
+  <template>
+    <div
+      class='pretui-scroller'
+      data-test-pretui-scroller
+      data-edge={{this.edge}}
+      ...attributes
+    >
+      <div
+        class='pretui-scroller-viewport'
+        data-orientation={{this.orientation}}
+        data-hide-scrollbar={{if @hideScrollbar 'true'}}
+        role={{this.role}}
+        aria-label={{@label}}
+        data-test-pretui-scroller-viewport
+        {{scrollEdges this.orientation}}
+      >
+        {{yield}}
+      </div>
+      {{! Four overlays rather than a mask on the viewport: a mask would fade
+          the scrollbar too. Sibling combinators off the viewport's data
+          attributes drive them, so no state round-trips through Glimmer. }}
+      <span class='pretui-scroller-edge' data-side='start-x' aria-hidden='true'></span>
+      <span class='pretui-scroller-edge' data-side='end-x' aria-hidden='true'></span>
+      <span class='pretui-scroller-edge' data-side='start-y' aria-hidden='true'></span>
+      <span class='pretui-scroller-edge' data-side='end-y' aria-hidden='true'></span>
+    </div>
+
+    <style scoped>
+      @layer PretComponent {
+        .pretui-scroller {
+          position: relative;
+          display: block;
+          min-width: 0;
+          container-type: inline-size;
+        }
+        .pretui-scroller-viewport {
+          min-width: 0;
+          overscroll-behavior: contain;
+          scrollbar-width: thin;
+          scrollbar-gutter: stable;
+        }
+        .pretui-scroller-viewport:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 2px;
+          border-radius: var(--radius-surface, 10px);
+        }
+        .pretui-scroller-viewport[data-orientation='horizontal'] {
+          overflow-x: auto;
+          overflow-y: hidden;
+        }
+        .pretui-scroller-viewport[data-orientation='vertical'] {
+          overflow-x: hidden;
+          overflow-y: auto;
+        }
+        .pretui-scroller-viewport[data-orientation='both'] {
+          overflow: auto;
+        }
+        .pretui-scroller-viewport[data-hide-scrollbar='true'] {
+          scrollbar-width: none;
+        }
+        .pretui-scroller-edge {
+          position: absolute;
+          opacity: 0;
+          pointer-events: none;
+          /* An opacity fade is not motion that encodes a state change so much
+             as a state change that would otherwise pop; it stays short and it
+             is cut entirely under reduced motion. */
+          transition: opacity 140ms linear;
+        }
+        .pretui-scroller-edge[data-side='start-x'],
+        .pretui-scroller-edge[data-side='end-x'] {
+          inset-block: 0;
+          inline-size: var(--pretui-scroller-fade, 28px);
+        }
+        .pretui-scroller-edge[data-side='start-x'] {
+          inset-inline-start: 0;
+        }
+        .pretui-scroller-edge[data-side='end-x'] {
+          inset-inline-end: 0;
+        }
+        .pretui-scroller-edge[data-side='start-y'],
+        .pretui-scroller-edge[data-side='end-y'] {
+          inset-inline: 0;
+          block-size: var(--pretui-scroller-fade, 28px);
+        }
+        .pretui-scroller-edge[data-side='start-y'] {
+          inset-block-start: 0;
+        }
+        .pretui-scroller-edge[data-side='end-y'] {
+          inset-block-end: 0;
+        }
+        /* Sibling combinators off the viewport's own attributes: the state
+           never round-trips through Glimmer, so a flick costs no renders. */
+        .pretui-scroller-viewport[data-start-x='clipped'] ~ .pretui-scroller-edge[data-side='start-x'],
+        .pretui-scroller-viewport[data-end-x='clipped'] ~ .pretui-scroller-edge[data-side='end-x'],
+        .pretui-scroller-viewport[data-start-y='clipped'] ~ .pretui-scroller-edge[data-side='start-y'],
+        .pretui-scroller-viewport[data-end-y='clipped'] ~ .pretui-scroller-edge[data-side='end-y'] {
+          opacity: 1;
+        }
+        .pretui-scroller[data-edge='none'] .pretui-scroller-edge {
+          display: none;
+        }
+        .pretui-scroller[data-edge='fade'] .pretui-scroller-edge[data-side='start-x'] {
+          background: linear-gradient(
+            to right,
+            var(--pretui-scroller-ground, var(--card)),
+            transparent
+          );
+        }
+        .pretui-scroller[data-edge='fade'] .pretui-scroller-edge[data-side='end-x'] {
+          background: linear-gradient(
+            to left,
+            var(--pretui-scroller-ground, var(--card)),
+            transparent
+          );
+        }
+        .pretui-scroller[data-edge='fade'] .pretui-scroller-edge[data-side='start-y'] {
+          background: linear-gradient(
+            to bottom,
+            var(--pretui-scroller-ground, var(--card)),
+            transparent
+          );
+        }
+        .pretui-scroller[data-edge='fade'] .pretui-scroller-edge[data-side='end-y'] {
+          background: linear-gradient(
+            to top,
+            var(--pretui-scroller-ground, var(--card)),
+            transparent
+          );
+        }
+        .pretui-scroller[data-edge='shadow'] .pretui-scroller-edge[data-side='start-x'] {
+          background: linear-gradient(
+            to right,
+            color-mix(in oklch, var(--foreground) 14%, transparent),
+            transparent
+          );
+        }
+        .pretui-scroller[data-edge='shadow'] .pretui-scroller-edge[data-side='end-x'] {
+          background: linear-gradient(
+            to left,
+            color-mix(in oklch, var(--foreground) 14%, transparent),
+            transparent
+          );
+        }
+        .pretui-scroller[data-edge='shadow'] .pretui-scroller-edge[data-side='start-y'] {
+          background: linear-gradient(
+            to bottom,
+            color-mix(in oklch, var(--foreground) 14%, transparent),
+            transparent
+          );
+        }
+        .pretui-scroller[data-edge='shadow'] .pretui-scroller-edge[data-side='end-y'] {
+          background: linear-gradient(
+            to top,
+            color-mix(in oklch, var(--foreground) 14%, transparent),
+            transparent
+          );
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-scroller-edge {
+            transition: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,44 @@
+## What it is
+
+A scroll container that tells you it is clipped: an edge fade or shadow appearing exactly when there is content past that edge.
+
+It is deliberately small and deliberately first. "Content continues past this edge" is a fact half the kit's collections need, and before this it was re-solved — or skipped — per component. **Carousel** consumes it rather than reimplementing edge detection.
+
+## The contract
+
+```
+@orientation?   — which axes may scroll. Default 'horizontal'
+@label?         — accessible name; supplying one promotes the viewport to a
+                  landmark region
+@edge?          — edge treatment: 'fade' (default) | 'shadow' | 'none'
+@hideScrollbar? — hide the native scrollbar; the edge affordance stays
+```
+
+**The region role is applied only when named.** An unnamed landmark is noise in a rotor, so `@label` is what promotes the viewport rather than the role being unconditional. That is the correct way round and the opposite of what most implementations do.
+
+**Hiding the scrollbar is defensible only because the edge affordance stays.** A scroll container with neither is content that appears to end where it does not — the single most common cause of people not finding the rest of a horizontal list.
+
+**Edge detection is one listener in a modifier** that removes itself in its destructor.
+
+## Prior art
+
+The scroll-shadow and fade patterns every design system reimplements per component.
+
+Where Pretui is better: it is a primitive rather than a treatment applied ad hoc, so every collection that scrolls gets the same affordance with the same behaviour — and the consumers do not each carry a resize observer.
+
+Where it is thinner: no scroll-to-item API, no snap behaviour (that is Carousel), and no programmatic edge query for a caller that wants to react to clipping itself.
+
+## Accessibility
+
+- **A named scroller is a landmark; an unnamed one is a plain box.** Both are correct for their case, and the arg is what distinguishes them.
+- **The edge affordance is `aria-hidden`.** It is a visual cue that content continues; a screen reader learns that from the content itself.
+- **Hiding the scrollbar removes a pointer affordance and a visual cue.** The edge treatment replaces the cue, not the affordance — keyboard scrolling still works, but a trackpad user loses the drag target.
+- **A scroll container needs a tab stop to be scrollable by keyboard.** Whatever is inside usually supplies one; a scroller of non-focusable content is reachable by pointer only, which is worth checking.
+
+## Theming
+
+`@edge` selects between a fade and an inset shadow, both drawn from the kit's surface tokens so the treatment matches whatever it sits on.
+
+That matching is the point: a fade that does not blend into its background reads as a grey band rather than as content continuing, which is why the treatment is token-derived rather than a fixed gradient.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,184 @@
+// Pretui — Scroller usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Scroller } from './scroller';
+import { LOTS } from '../demo-structure-scroll';
+
+// ── Scroller ─────────────────────────────────────────────────────────────
+export class ScrollerUsage extends Component {
+  @tracked orientation: 'horizontal' | 'vertical' | 'both' = 'horizontal';
+  @tracked edge: 'fade' | 'shadow' | 'none' = 'fade';
+  @tracked hideScrollbar = false;
+
+  orientationOptions = ['horizontal', 'vertical', 'both'];
+  edgeOptions = ['fade', 'shadow', 'none'];
+  lots = LOTS;
+
+  setOrientation = (v: string) => {
+    this.orientation = v as 'horizontal' | 'vertical' | 'both';
+  };
+  setEdge = (v: string) => {
+    this.edge = v as 'fade' | 'shadow' | 'none';
+  };
+  setHideScrollbar = (v: boolean) => {
+    this.hideScrollbar = v;
+  };
+
+  get isVertical(): boolean {
+    return this.orientation === 'vertical';
+  }
+
+  get usage(): string {
+    return [
+      '<Scroller',
+      "  @label='Recent lots'",
+      "  @orientation='" + this.orientation + "'",
+      "  @edge='" + this.edge + "'",
+      '>',
+      '  <div class="row">…</div>',
+      '</Scroller>',
+    ].join('\n');
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='Scroller'
+      @description='A scroll container that tells you it is clipped. The edge affordance appears on whichever side has content past it and disappears at a hard stop, and the region becomes a tab stop exactly when it actually scrolls — and stops being one when the content shrinks. Scroll the strip below and watch both edges: the state is carried on data attributes, so a flick costs zero renders.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='scroller-stage'>
+          <Scroller
+            @label='Recent lots'
+            @orientation={{this.orientation}}
+            @edge={{this.edge}}
+            @hideScrollbar={{this.hideScrollbar}}
+          >
+            <div class='scroller-strip' data-vertical={{if this.isVertical 'true'}}>
+              {{#each this.lots key='id' as |lot|}}
+                <article class='scroller-card'>
+                  <p class='scroller-id'>{{lot.id}}</p>
+                  <h4 class='scroller-tea'>{{lot.tea}}</h4>
+                  <p class='scroller-meta'>{{lot.place}}
+                    ·
+                    {{lot.chests}}
+                    chests</p>
+                </article>
+              {{/each}}
+            </div>
+          </Scroller>
+          <p class='scroller-note'>Tab into the strip and use the arrow keys —
+            the tab stop is added and removed with the overflow.</p>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='orientation'
+          @description='Which axes may scroll: horizontal (default), vertical, or both. Explicit rather than always-on, so a horizontal strip cannot be nudged vertically by a trackpad.'
+          @options={{this.orientationOptions}}
+          @value={{this.orientation}}
+          @onInput={{this.setOrientation}}
+          @defaultValue='horizontal'
+        />
+        <Args.String
+          @name='edge'
+          @description='Edge treatment. fade blends into the surface behind it; shadow reads as a physical lip; none keeps the behaviour and drops the affordance.'
+          @options={{this.edgeOptions}}
+          @value={{this.edge}}
+          @onInput={{this.setEdge}}
+          @defaultValue='fade'
+        />
+        <Args.String
+          @name='label'
+          @description='Accessible name. Supplying one promotes the viewport to a landmark region — the role is deliberately NOT applied without a name, because an unnamed region is noise in a rotor.'
+        />
+        <Args.Bool
+          @name='hideScrollbar'
+          @description='Hide the native scrollbar. Defensible only because the edge affordance stays: without it, a hidden scrollbar hides the fact that there is more.'
+          @defaultValue={{false}}
+          @value={{this.hideScrollbar}}
+          @onInput={{this.setHideScrollbar}}
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-scroller-fade'
+          @type='dimension'
+          @description='Width (or height) of the edge affordance.'
+          @defaultValue='28px'
+        />
+        <Css.Basic
+          @name='pretui-scroller-ground'
+          @type='color'
+          @description='The colour the fade blends into. Set it to whatever the Scroller actually sits on.'
+          @defaultValue='var(--card)'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+
+    <style scoped>
+      .scroller-stage {
+        display: grid;
+        gap: var(--space-3, 8px);
+        padding: var(--space-5, 14px);
+        border-radius: var(--radius-surface, 10px);
+        background: var(--card);
+        box-shadow: var(
+          --pretui-shadow-hairline,
+          0 0 0 1px var(--border)
+        );
+        /* Custom properties INHERIT, so the Scroller's fade blends into the
+           surface it actually sits on without a selector that has to reach
+           into another component's scope. */
+        --pretui-scroller-ground: var(--card);
+      }
+      .scroller-strip {
+        display: flex;
+        gap: var(--space-3, 8px);
+        padding-block-end: var(--space-2, 6px);
+      }
+      .scroller-strip[data-vertical='true'] {
+        flex-direction: column;
+        max-block-size: none;
+      }
+      .scroller-card {
+        flex: 0 0 auto;
+        inline-size: 178px;
+        padding: var(--space-4, 11px);
+        border-radius: var(--radius-surface, 10px);
+        background: var(--muted);
+        box-shadow: var(
+          --pretui-shadow-hairline,
+          0 0 0 1px var(--border)
+        );
+      }
+      .scroller-id {
+        margin: 0;
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        letter-spacing: var(--track-eyebrow, 0.08em);
+        color: var(--muted-foreground);
+      }
+      .scroller-tea {
+        margin: 2px 0 0;
+        font-size: var(--text-ui-lg, 14px);
+        font-weight: var(--weight-strong, 600);
+      }
+      .scroller-meta {
+        margin: 2px 0 0;
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+      .scroller-note {
+        margin: 0;
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_SCROLLER: Record<string, unknown> = {
+  Scroller: ScrollerUsage,
+};