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

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

@@ -0,0 +1,174 @@
+// Pretui — Handle usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Handle } from './handle';
+import { dragsSurface } from '../internal/design-tools';
+import type { SurfaceFrame } from '../internal/design-tools';
+
+// ── Handle ───────────────────────────────────────────────────────────────
+const SHAPES = ['point', 'bar', 'square'];
+
+class HandleUsage extends Component {
+  shapeOptions = SHAPES;
+  @tracked shape = 'point';
+  @tracked x = 50;
+  @tracked y = 50;
+  @tracked hitArea = 8;
+  @tracked selected = false;
+  @tracked disabled = false;
+
+  setShape = (v: string) => (this.shape = v);
+  setHitArea = (v: number) => (this.hitArea = v);
+  setSelected = (v: boolean) => (this.selected = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+
+  get shapeVal() {
+    return this.shape as 'point' | 'bar' | 'square';
+  }
+  get valueText() {
+    return Math.round(this.x) + '%, ' + Math.round(this.y) + '%';
+  }
+  onDrag = (part: SurfaceFrame) => {
+    if (this.disabled) {
+      return;
+    }
+    this.x = part.nx * 100;
+    this.y = part.ny * 100;
+  };
+  nudge = (dx: number, dy: number) => {
+    if (dx === -Infinity) {
+      this.x = 0;
+      return;
+    }
+    if (dx === Infinity) {
+      this.x = 100;
+      return;
+    }
+    this.x = Math.min(100, Math.max(0, this.x + dx));
+    this.y = Math.min(100, Math.max(0, this.y + dy));
+  };
+  get usage() {
+    return (
+      '<div class="surface" {{dragsSurface this.onDrag}}>\n' +
+      '  <Handle @x={{this.x}} @y={{this.y}} @label="Origin" @valueText={{this.valueText}} @onNudge={{this.nudge}} />\n' +
+      '</div>'
+    );
+  }
+  <template>
+    <FreestyleUsage
+      @name='Handle'
+      @description='A draggable grip on a 2D surface — a real <button>, so it is focusable, named and activatable, with arrow-key movement carrying the same Shift/Alt multipliers as every other gesture in the territory. It does NOT own the drag: the surface does, via the dragsSurface modifier, which is what lets a surface with six stops keep one listener set and lets a handle dragged past the edge keep tracking. Ported from figui3 fig-handle; its hit-area idea is kept and simplified to one number.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='pretui-handle-demo'>
+          <div
+            class='pretui-handle-surface'
+            {{dragsSurface this.onDrag this.disabled}}
+          >
+            <Handle
+              @x={{this.x}}
+              @y={{this.y}}
+              @shape={{this.shapeVal}}
+              @hitArea={{this.hitArea}}
+              @selected={{this.selected}}
+              @disabled={{this.disabled}}
+              @label='Origin'
+              @valueText={{this.valueText}}
+              @onNudge={{this.nudge}}
+            />
+          </div>
+          <p class='pretui-demo-readout' data-test-handle-readout>
+            {{this.valueText}}
+          </p>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Number
+          @name='x'
+          @description='Horizontal position within the surface, 0–100 (percent). Clamped through Math before it reaches the inline style.'
+        />
+        <Args.Number
+          @name='y'
+          @description='Vertical position, 0–100.'
+        />
+        <Args.String
+          @name='shape'
+          @defaultValue='point'
+          @value={{this.shape}}
+          @options={{this.shapeOptions}}
+          @description="'point' is the round dot; 'bar' is the vertical stop marker a gradient bar uses; 'square' is a resize grip."
+          @onInput={{this.setShape}}
+        />
+        <Args.Number
+          @name='hitArea'
+          @defaultValue={{6}}
+          @value={{this.hitArea}}
+          @min={{0}}
+          @max={{24}}
+          @description='Invisible px added on every side. An 11px dot is an 11px target without it; a coarse pointer always gets 16px regardless.'
+          @onInput={{this.setHitArea}}
+        />
+        <Args.Bool
+          @name='selected'
+          @defaultValue={{false}}
+          @value={{this.selected}}
+          @description='Selected state, carried on aria-pressed as well as the fill.'
+          @onInput={{this.setSelected}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @defaultValue={{false}}
+          @value={{this.disabled}}
+          @onInput={{this.setDisabled}}
+        />
+        <Args.String
+          @name='label'
+          @description='REQUIRED accessible name — “Start point”, “Stop 2”, “Origin”.'
+        />
+        <Args.String
+          @name='valueText'
+          @description='Current position, folded into the accessible name (a button has no aria-valuetext).'
+        />
+        <Args.Number
+          @name='index'
+          @description='Identity a parent surface reads off SurfaceFrame.origin to know which handle a drag grabbed.'
+        />
+        <Args.Action
+          @name='onNudge'
+          @description='Arrow keys. Receives (dx, dy, modifiers) in percent, already multiplied; ±Infinity dx means Home/End.'
+        />
+        <Args.Action
+          @name='onActivate'
+          @description='Enter/Space, and a click that did not become a drag.'
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-handle-demo {
+        max-width: 220px;
+      }
+      .pretui-handle-surface {
+        position: relative;
+        width: 100%;
+        aspect-ratio: 1 / 1;
+        border-radius: var(--radius);
+        background: var(--field, var(--boxel-light));
+        box-shadow: inset 0 0 0 1px var(--border);
+        touch-action: none;
+      }
+      .pretui-demo-readout {
+        margin: 8px 0 0;
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--muted-foreground);
+        font-variant-numeric: tabular-nums;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_HANDLE: Record<string, unknown> = {
+  Handle: HandleUsage,
+};

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

@@ -0,0 +1,307 @@
+// Pretui — HeroSplit: a two-column hero: headline and actions beside media.
+import Component from '@glimmer/component';
+import { guidFor } from '@ember/object/internals';
+import { Chip } from './chip';
+import { MediaViewer } from './media-viewer';
+import type { MediaAssetSpec } from '../internal/media-viewer';
+import { cssStyle } from '../pretui-css';
+import { ariaLevelFor } from '../internal/blocks';
+import type { BlockHeadingLevel } from '../internal/blocks';
+
+// ═════════════════════════════════════════════════════════════════════════
+// B2 · HeroSplit
+// ═════════════════════════════════════════════════════════════════════════
+//
+// From catalog-app's storefront-hero. Split grid: eyebrow / headline /
+// lead / chip strip / dual CTA on one side, a media stage on the other.
+//
+// The three problems are all responsive, and this is what it does about
+// each:
+//
+//   1. SOURCE ORDER IS ALWAYS CONTENT FIRST. The content column is the
+//      first child of the grid in every configuration; `@mediaSide='start'`
+//      moves the media visually with `order`, and only at wide widths.
+//      A screen reader, a reading-mode extension and a keyboard tab pass
+//      always meet the headline before the picture, which is the one
+//      ordering that is never wrong.
+//   2. AT NARROW WIDTHS the grid collapses to a single column and the
+//      `order` override is cancelled at equal specificity, so the visual
+//      order rejoins the source order — media below content, never a
+//      picture ahead of the headline on a phone. The measurement is an
+//      UNNAMED container query against the block's own box: a hero inside a
+//      600px card pane must stack even when the viewport is 1600px wide.
+//   3. THE MEDIA STAGE IS RATIO-HONEST. With no `@ratio`, the stage takes
+//      the asset's intrinsic ratio and MediaViewer reserves the space
+//      before the bytes arrive (the Law-8 corollary). With `@ratio`, the
+//      stage holds exactly that box: a landscape asset letterboxes inside
+//      it and a portrait asset is centred and clipped symmetrically, so a
+//      row of heroes keeps its rhythm whatever the caller uploads. Nothing
+//      is stretched and nothing overflows the grid.
+//
+// BETTER THAN THE INSPIRATION:
+//   · Every chip and every line of copy was a literal in the template, so
+//     the source could not be reused without a fork → all copy is args,
+//     `@chips` is data, and the CTA is a named block so the caller supplies
+//     real Buttons rather than a fixed pair of href/label pairs.
+//   · `#11cf8a` twice as a hard literal (with a comment admitting it
+//     diverged from `--primary` on purpose), plus `#15151b0a`, `#fbfaf5`
+//     and `#ff5b9c` interpolated into `htmlSafe` styles → this block
+//     authors no colour at all. Chips take a hue token; everything else is
+//     inherited ink.
+//   · The rotation was hard-capped at three images with per-`nth-child`
+//     delays, had NO manual navigation, no `aria-live`, no
+//     `aria-roledescription`, and animated `pointer-events` inside
+//     keyframes → THE ROTATION IS GONE. A hero that cycles images is a
+//     carousel, a carousel has state, and state is not a block's to own.
+//     The kit already ships `Carousel` (structure-scroll.gts) with
+//     navigation, keyboard support and a reduced-motion contract; a caller
+//     who wants rotation puts one in the `<:media>` block and gets all of
+//     that instead of a bespoke 12-second loop nobody can pause.
+//   · The stage was welded to <img> → `@asset` goes through `MediaViewer`,
+//     so a hero can lead with a video or an audio piece and the right
+//     adapter is chosen without the caller knowing the kind.
+//
+// A fixed `@ratio` letterboxes a landscape asset and centre-clips a portrait
+// one evenly; it never stretches. A hero that wants a specific crop passes
+// its own image in the media block.
+
+export interface HeroChip {
+  label: string;
+  /** A tone token, e.g. `var(--success, var(--boxel-success))`. Validated by the kit's
+   * CSS allowlist before it reaches a style attribute. */
+  hue?: string;
+  /** Show the leading dot. Off by default here: a hero chip is a feature
+   * label, not a status. */
+  dot?: boolean;
+}
+
+export interface HeroSplitSignature {
+  Args: {
+    /** Small line above the headline. */
+    eyebrow?: string;
+    /** The headline. Required — it is the block's accessible name. */
+    headline: string;
+    /** One paragraph under the headline. */
+    lead?: string;
+    /** The chip strip. Data, never markup. */
+    chips?: readonly HeroChip[];
+    /** The media stage's asset — image, video or audio. Routed by
+     * MediaViewer, which reserves the space before it loads. */
+    asset?: MediaAssetSpec;
+    /** Which side the media sits on VISUALLY at wide widths. Source order
+     * is always content-first regardless. Default `end`. */
+    mediaSide?: 'start' | 'end';
+    /** Hold the media stage at a fixed CSS `aspect-ratio` (`16 / 9`,
+     * `4 / 3`). Omit it and the stage takes the asset's own ratio. */
+    ratio?: string;
+    /** Heading level for the headline in the host page. A hero is often
+     * the page's `<h1>`. */
+    headingLevel?: BlockHeadingLevel;
+  };
+  Blocks: {
+    /** Replaces the media stage entirely — a Carousel, a Chart, a Scene. */
+    media: [];
+    /** The call-to-action controls. Buttons come from the caller so their
+     * tone, appearance and behaviour are the caller's to choose. */
+    actions: [];
+    /** Anything under the actions — fine print, a trust strip. */
+    default: [];
+  };
+  Element: HTMLElement;
+}
+
+export class HeroSplit extends Component<HeroSplitSignature> {
+  private headlineId = guidFor(this) + '-headline';
+
+  get mediaSide(): 'start' | 'end' {
+    return this.args.mediaSide === 'start' ? 'start' : 'end';
+  }
+  get headingAriaLevel() {
+    return ariaLevelFor(this.args.headingLevel);
+  }
+  get style() {
+    return cssStyle('--pretui-hero-ratio', this.args.ratio);
+  }
+  get ratioMode(): string {
+    return this.args.ratio ? 'fixed' : 'intrinsic';
+  }
+  get chips(): HeroChip[] {
+    return (this.args.chips ?? []).map((chip) => ({
+      label: chip.label,
+      hue: chip.hue,
+      dot: chip.dot ?? false,
+    }));
+  }
+
+  <template>
+    <section
+      class='pretui-hero'
+      style={{this.style}}
+      data-media-side={{this.mediaSide}}
+      aria-labelledby={{this.headlineId}}
+      data-test-pretui-hero-split
+      ...attributes
+    >
+      <div class='pretui-hero-grid'>
+        {{! Content is ALWAYS the first child. `order` moves the picture,
+            never the prose. }}
+        <div class='pretui-hero-content'>
+          {{#if @eyebrow}}
+            <p class='pretui-hero-eyebrow'>{{@eyebrow}}</p>
+          {{/if}}
+          <h2
+            id={{this.headlineId}}
+            class='pretui-hero-headline'
+            aria-level={{this.headingAriaLevel}}
+          >{{@headline}}</h2>
+          {{#if @lead}}
+            <p class='pretui-hero-lead'>{{@lead}}</p>
+          {{/if}}
+          {{#if this.chips.length}}
+            <ul class='pretui-hero-chips' role='list'>
+              {{#each this.chips key='@index' as |chip|}}
+                <li>
+                  <Chip
+                    @label={{chip.label}}
+                    @hue={{chip.hue}}
+                    @dot={{chip.dot}}
+                  />
+                </li>
+              {{/each}}
+            </ul>
+          {{/if}}
+          {{#if (has-block 'actions')}}
+            <div
+              class='pretui-hero-actions'
+              data-test-pretui-hero-actions
+            >{{yield to='actions'}}</div>
+          {{/if}}
+          {{yield}}
+        </div>
+
+        {{#if (has-block 'media')}}
+          <div
+            class='pretui-hero-media'
+            data-ratio={{this.ratioMode}}
+            data-test-pretui-hero-media
+          >{{yield to='media'}}</div>
+        {{else}}
+          {{! Glint does not narrow an @arg through an else-if chain, so the
+              nested if-block is what makes @asset non-optional here.
+              Behaviour is identical. NB: a Glimmer comment ends at the first
+              closing brace pair, so it can never quote curly syntax. }}
+          {{#if @asset}}
+            <div
+              class='pretui-hero-media'
+              data-ratio={{this.ratioMode}}
+              data-test-pretui-hero-media
+            >
+              <MediaViewer @asset={{@asset}} />
+            </div>
+          {{/if}}
+        {{/if}}
+      </div>
+    </section>
+
+    <style scoped>
+      @layer PretComponent {
+        /* The block's own box is the query container. Unnamed — a NAMED
+           container query silently deletes every rule after it. */
+        .pretui-hero {
+          container-type: inline-size;
+          display: block;
+        }
+        .pretui-hero-grid {
+          display: grid;
+          grid-template-columns:
+            minmax(0, var(--pretui-hero-content-fr, 1fr))
+            minmax(0, var(--pretui-hero-media-fr, 1fr));
+          gap: var(--pretui-hero-gap, var(--space-8, 34px));
+          align-items: center;
+        }
+        .pretui-hero[data-media-side='start'] .pretui-hero-media {
+          order: -1;
+        }
+        .pretui-hero-content {
+          display: grid;
+          gap: var(--space-4, 11px);
+          justify-items: start;
+          min-width: 0;
+        }
+        .pretui-hero-eyebrow {
+          margin: 0;
+          font-family: var(--font-mono);
+          font-size: var(--text-ui-xs, 11px);
+          font-weight: 500;
+          letter-spacing: var(--track-eyebrow, 0.08em);
+          text-transform: uppercase;
+          color: var(--muted-foreground);
+        }
+        .pretui-hero-headline {
+          margin: 0;
+          font-family: var(--font-serif);
+          font-size: var(--pretui-hero-headline-size, var(--text-display, 33px));
+          font-weight: 400;
+          line-height: 1.12;
+          letter-spacing: var(--track-heading, -0.02em);
+          color: var(--foreground);
+          text-wrap: balance;
+        }
+        .pretui-hero-lead {
+          margin: 0;
+          font-size: var(--text-body, 15px);
+          line-height: 1.5;
+          color: var(--muted-foreground);
+          max-width: 58ch;
+        }
+        .pretui-hero-chips {
+          margin: 0;
+          padding: 0;
+          list-style: none;
+          display: flex;
+          flex-wrap: wrap;
+          gap: var(--space-2, 6px);
+        }
+        .pretui-hero-actions {
+          display: flex;
+          flex-wrap: wrap;
+          align-items: center;
+          gap: var(--space-3, 8px);
+        }
+        .pretui-hero-media {
+          min-width: 0;
+        }
+        /* A stated ratio holds the box: landscape letterboxes, portrait is
+           centred and clipped evenly. Both are honest; neither distorts. */
+        .pretui-hero-media[data-ratio='fixed'] {
+          aspect-ratio: var(--pretui-hero-ratio, 4 / 3);
+          overflow: hidden;
+          display: grid;
+          place-items: center;
+          border-radius: var(--radius-surface, 10px);
+        }
+
+        @container (max-width: 46rem) {
+          .pretui-hero-grid {
+            grid-template-columns: minmax(0, 1fr);
+            gap: var(--pretui-hero-gap-narrow, var(--space-6, 19px));
+          }
+          /* Same specificity as the wide rule, so the visual order rejoins
+             the source order instead of losing to it. */
+          .pretui-hero[data-media-side='start'] .pretui-hero-media {
+            order: 0;
+          }
+          .pretui-hero-headline {
+            font-size: var(
+              --pretui-hero-headline-size-narrow,
+              var(--text-heading, 19px)
+            );
+          }
+          .pretui-hero-actions {
+            width: 100%;
+          }
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,50 @@
+## What it is
+
+The split hero: an eyebrow, a headline, a lead paragraph and a chip strip on one side, a media stage on the other.
+
+## The contract
+
+```
+@eyebrow?  — small line above the headline
+@headline (required) — the block's accessible name
+@lead?     — one paragraph under the headline
+@chips?    — the chip strip. Data, never markup
+@asset?    — the media stage's asset; routed by MediaViewer, which reserves the
+             space before it loads
+@mediaSide? — which side the media sits on VISUALLY at wide widths. Default 'end'
+@ratio?    — hold the stage at a fixed CSS aspect-ratio; omit and the stage takes
+             the asset's own
+@headingLevel? — heading level for the headline in the host page
+```
+
+**`@headline` is required because it is the block's accessible name.** A hero with no headline is a picture with some chips next to it.
+
+**`@mediaSide` moves the media visually and never in source order.** Content comes first in the DOM regardless, so reading order is stable whichever side the picture is on — the same rule **StepsWithMedia** follows.
+
+**`@chips` is data, never markup.** A chip strip built from blocks is a chip strip that will eventually contain a link, a button and a nested component; keeping it typed keeps it a strip.
+
+**The stage reserves its space before the asset loads**, so a hero does not reflow under the reader — which matters most here, because a hero is the first thing on the page.
+
+## Prior art
+
+The split hero on every marketing page.
+
+Where Pretui is better: the source-order guarantee and the heading level as an argument. Both are the things that break when a hero is hand-built and then reused on a second page with a different outline.
+
+Where it is thinner: one media stage, no video background, no call-to-action model — actions are the caller's to place — and no alternating layout across stacked heroes.
+
+## Accessibility
+
+- **The headline is a real heading at `@headingLevel`**, so a hero participates in the document outline rather than being large text.
+- **Source order is content-first regardless of `@mediaSide`**, which means a screen reader gets the headline before the picture on both variants.
+- **`@eyebrow` is context, not a heading**, so it does not compete in the outline.
+- **The media carries its own alt text through MediaViewer**; a hero image with none is announced as an unnamed graphic.
+- **Chips are text**, announced after the lead, rather than being decorative shapes.
+
+## Theming
+
+The block composes **MediaViewer** and the kit's **Chip**, and takes the shared block spacing and heading tokens.
+
+A hero with its own type scale is how a marketing page ends up looking like two products — which is why the headline's size comes from the theme's scale at the given heading level rather than from a hero-specific token.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.