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

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

@@ -0,0 +1,298 @@
+// Pretui — Onboarding: a first-run checklist that tracks what is done.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { guidFor } from '@ember/object/internals';
+import { Button } from './button';
+import { StepList } from './step-list';
+import type { StepItem } from './step-list';
+import { EmptyState } from './empty-state';
+
+// ── Onboarding ───────────────────────────────────────────────────────────
+// The first-run walkthrough. Four decisions carry it:
+//
+//   · The rail is `StepList`, the same component SessionPrep uses, so the
+//     kit has one visual grammar for "where am I in a sequence".
+//   · The media is a slot, not a prop. An onboarding step shows a video, a
+//     screenshot, a live component or nothing, and no prop shape covers all
+//     four (Law 7).
+//   · Position is announced. "Step 2 of 4 — Attach a card" goes to a polite
+//     live region, because a walkthrough whose progress is only visible is a
+//     walkthrough a screen-reader user has to count.
+//   · Skip is a named button, never a corner glyph, whenever `@onSkip` is
+//     given. A walkthrough you cannot leave is a modal, and this is not one.
+
+export interface OnboardingStep {
+  /** stable id */
+  id: string;
+  /** the step's heading, also its rail caption */
+  title: string;
+  /** the step's copy */
+  body?: string;
+  /** shorter caption for the rail, when the title is too long for it */
+  caption?: string;
+}
+
+export interface OnboardingSignature {
+  Args: {
+    /** the walkthrough, in order */
+    steps: OnboardingStep[];
+    /** controlled step index */
+    current?: number;
+    /** starting index when uncontrolled (default 0) */
+    defaultCurrent?: number;
+    /** fires with the requested index */
+    onStepChange?: (index: number) => void;
+    /** fires when the reader finishes the last step */
+    onDone?: () => void;
+    /** fires when the reader leaves early; omit to hide the skip */
+    onSkip?: () => void;
+    /** accessible name for the whole scene (default 'Getting started') */
+    label?: string;
+    /** final-step button wording (default 'Get started') */
+    doneLabel?: string;
+    /** skip wording (default 'Skip') */
+    skipLabel?: string;
+    /** rail presentation, passed to StepList (default 'track') */
+    variant?: 'steps' | 'track';
+  };
+  Blocks: {
+    /** the step's illustration — receives the step and its index */
+    media: [step: OnboardingStep, index: number];
+  };
+  Element: HTMLElement;
+}
+
+export class Onboarding extends Component<OnboardingSignature> {
+  @tracked private innerCurrent?: number;
+
+  private sceneId = guidFor(this) + '-scene';
+
+  get steps(): OnboardingStep[] {
+    return this.args.steps ?? [];
+  }
+  get count(): number {
+    return this.steps.length;
+  }
+  get current(): number {
+    let requested =
+      this.args.current ?? this.innerCurrent ?? this.args.defaultCurrent ?? 0;
+    if (this.count === 0) {
+      return 0;
+    }
+    return Math.min(Math.max(Math.round(requested), 0), this.count - 1);
+  }
+  get step(): OnboardingStep | undefined {
+    return this.steps[this.current];
+  }
+  get railSteps(): StepItem[] {
+    return this.steps.map((step) => ({
+      label: step.caption ?? step.title,
+    }));
+  }
+  get isFirst(): boolean {
+    return this.current === 0;
+  }
+  get isLast(): boolean {
+    return this.count === 0 || this.current === this.count - 1;
+  }
+  get label(): string {
+    return this.args.label ?? 'Getting started';
+  }
+  get nextLabel(): string {
+    return this.isLast ? (this.args.doneLabel ?? 'Get started') : 'Next';
+  }
+  get position(): string {
+    if (!this.step) {
+      return '';
+    }
+    return (
+      'Step ' +
+      (this.current + 1) +
+      ' of ' +
+      this.count +
+      ' — ' +
+      this.step.title
+    );
+  }
+
+  private go = (index: number) => {
+    if (this.args.current === undefined) {
+      this.innerCurrent = index;
+    }
+    this.args.onStepChange?.(index);
+  };
+
+  back = (event: Event) => {
+    if (this.isFirst) {
+      return;
+    }
+    this.go(this.current - 1);
+    // Back is about to go disabled on step one; hand focus to Next first so
+    // it doesn't drop to the body
+    let button = event.currentTarget as HTMLElement;
+    if (this.isFirst && document.activeElement === button) {
+      (button.parentElement?.querySelector('.pretui-onb-next') as HTMLElement | null)?.focus();
+    }
+  };
+
+  next = () => {
+    if (this.isLast) {
+      this.args.onDone?.();
+      return;
+    }
+    this.go(this.current + 1);
+  };
+
+  skip = () => this.args.onSkip?.();
+
+  <template>
+    <section
+      class='pretui-onb'
+      aria-label={{this.label}}
+      data-test-pretui-onboarding
+      ...attributes
+    >
+      {{#if this.railSteps.length}}
+        <StepList
+          @steps={{this.railSteps}}
+          @current={{this.current}}
+          @variant={{if @variant @variant 'track'}}
+          @label='Walkthrough progress'
+        />
+      {{/if}}
+
+      <span class='pretui-sr' role='status'>{{this.position}}</span>
+
+      {{#if this.step}}
+        <div class='pretui-onb-scene' id={{this.sceneId}}>
+          {{#if (has-block 'media')}}
+            <div class='pretui-onb-media'>
+              {{yield this.step this.current to='media'}}
+            </div>
+          {{/if}}
+          <div class='pretui-onb-copy'>
+            <h3 class='pretui-onb-title'>{{this.step.title}}</h3>
+            {{#if this.step.body}}
+              <p class='pretui-onb-body'>{{this.step.body}}</p>
+            {{/if}}
+          </div>
+        </div>
+      {{else}}
+        <EmptyState
+          @title='Nothing to walk through'
+          @message='This walkthrough has no steps yet.'
+        />
+      {{/if}}
+
+      <div class='pretui-onb-nav'>
+        {{#if @onSkip}}
+          <Button
+            @tone='neutral'
+            @appearance='plain'
+            @size='s'
+            data-test-pretui-onboarding-skip
+            {{on 'click' this.skip}}
+          >{{if @skipLabel @skipLabel 'Skip'}}</Button>
+        {{/if}}
+        <span class='pretui-onb-nav-end'>
+          <Button
+            @tone='neutral'
+            @appearance='outlined'
+            @size='s'
+            @disabled={{if this.isFirst true}}
+            data-test-pretui-onboarding-back
+            {{on 'click' this.back}}
+          >Back</Button>
+          <Button
+            class='pretui-onb-next'
+            @size='s'
+            @disabled={{unless this.step true}}
+            aria-controls={{this.sceneId}}
+            data-test-pretui-onboarding-next
+            {{on 'click' this.next}}
+          >{{this.nextLabel}}</Button>
+        </span>
+      </div>
+    </section>
+
+    <style scoped>
+      @layer PretComponent {
+        .pretui-onb {
+          display: flex;
+          flex-direction: column;
+          gap: var(--space-4, 13px);
+          padding: var(--space-4, 15px);
+          border-radius: var(--radius-surface, 14px);
+          background: var(--card);
+          box-shadow: var(
+            --pretui-shadow-card,
+            0 0 0 1px var(--border),
+            0 1px 2px rgb(0 0 0 / 0.08)
+          );
+          font-size: var(--text-ui-md, 12.5px);
+          container-type: inline-size;
+        }
+        .pretui-onb-scene {
+          display: grid;
+          grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+          gap: var(--space-4, 15px);
+          align-items: center;
+          min-height: 9rem;
+        }
+        .pretui-onb-scene:not(:has(.pretui-onb-media)) {
+          grid-template-columns: minmax(0, 1fr);
+        }
+        /* unnamed container query — resolves against .pretui-onb */
+        @container (max-width: 34rem) {
+          .pretui-onb-scene {
+            grid-template-columns: minmax(0, 1fr);
+          }
+        }
+        .pretui-onb-media {
+          border-radius: 10px;
+          overflow: hidden;
+          background: var(--inset, var(--boxel-100));
+          box-shadow: var(
+            --pretui-shadow-hairline,
+            0 0 0 1px var(--border)
+          );
+        }
+        .pretui-onb-copy {
+          min-width: 0;
+        }
+        .pretui-onb-title {
+          margin: 0;
+          font-size: 16px;
+          font-weight: 600;
+          letter-spacing: -0.02em;
+        }
+        .pretui-onb-body {
+          margin: 6px 0 0;
+          max-width: 52ch;
+          line-height: 1.65;
+          color: var(--muted-foreground);
+        }
+        .pretui-onb-nav {
+          display: flex;
+          align-items: center;
+          gap: 8px;
+        }
+        .pretui-onb-nav-end {
+          display: inline-flex;
+          align-items: center;
+          gap: 8px;
+          margin-left: auto;
+        }
+        .pretui-sr {
+          position: absolute;
+          width: 1px;
+          height: 1px;
+          overflow: hidden;
+          clip-path: inset(50%);
+          white-space: nowrap;
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,48 @@
+## What it is
+
+A walkthrough: an ordered set of steps with an illustration, a rail showing progress, and a skip.
+
+## The contract
+
+```
+@steps (required) — the walkthrough, in order
+@current?, @defaultCurrent?, @onStepChange? — the position
+@onDone?    — fires when the reader finishes the last step
+@onSkip?    — fires when the reader leaves early; OMIT TO HIDE THE SKIP
+@label?     — accessible name for the whole scene. Default 'Getting started'
+@doneLabel? — final-step button wording. Default 'Get started'
+@skipLabel? — default 'Skip'
+@variant?   — rail presentation, passed to StepList. Default 'track'
+
+<:media> — the step's illustration; receives the step and its index
+```
+
+**Omitting `@onSkip` hides the skip**, which is the kit's conditional-affordance rule applied to the one control readers look for first.
+
+**The rail is a StepList in `track` mode**, so progress is conveyed as text rather than by a row of dots.
+
+**`@doneLabel` defaults to "Get started"** rather than "Done", because the last step of an onboarding is a beginning.
+
+## Prior art
+
+The product-tour and walkthrough components.
+
+Where Pretui is better: not much structurally — it is a stepped scene. The value is that the rail is a real StepList rather than dots, so progress is announced, and that skip is a first-class arg rather than a footnote.
+
+Where it is thinner: no anchored tooltips pointing at real UI — this is a scene, not a coach-mark tour — no branching, and no persistence of where someone stopped.
+
+## Accessibility
+
+- **The scene is named**, defaulting to "Getting started".
+- **Progress comes from StepList**, so "step 2 of 5" is available as text rather than by counting filled dots.
+- **Skip is a real, named control**, and hiding it is a deliberate act with a visible cost: an onboarding with no exit is a modal trap.
+- **`<:media>` illustrations are decoration unless the caller says otherwise** — an illustration carrying meaning needs its own alt text.
+- **Moving backwards is allowed** through `@onStepChange`, which matters for anyone who moved past something too quickly.
+
+## Theming
+
+Everything comes from **StepList** and the kit's block and button tokens.
+
+An onboarding that themed independently would be the first thing a new reader sees and the one screen that does not look like the product — which is the exact opposite of what it is for.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,155 @@
+// Pretui — Onboarding usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { Button } from './button';
+import { Onboarding } from './onboarding';
+import type { OnboardingStep } from './onboarding';
+
+// ── Onboarding ───────────────────────────────────────────────────────────
+const STEPS: OnboardingStep[] = [
+  {
+    id: 'o1',
+    title: 'Attach what the agent should see',
+    caption: 'Attach',
+    body: 'Anything you are viewing is offered as context automatically. Pin it to keep it attached for the whole session, or drop it and the agent never sees it.',
+  },
+  {
+    id: 'o2',
+    title: 'Ask before you Act',
+    caption: 'Modes',
+    body: 'Ask reads only. Act may propose changes, and every change it proposes arrives as a receipt you keep or revert — nothing is written behind your back.',
+  },
+  {
+    id: 'o3',
+    title: 'Read the trace',
+    caption: 'Trace',
+    body: 'Every answer carries the reasoning that produced it, folded away by default. Open it when the answer surprises you.',
+  },
+  {
+    id: 'o4',
+    title: 'Keep what works',
+    caption: 'Keep',
+    body: 'Standing instructions and saved prompts persist across sessions, so the second run starts where the first one ended.',
+  },
+];
+
+class OnboardingUsage extends GlimmerComponent {
+  @tracked current = 0;
+  @tracked outcome = '';
+
+  setCurrent = (index: number) => (this.current = index);
+  done = () => (this.outcome = 'finished the walkthrough');
+  skip = () => (this.outcome = 'skipped the walkthrough');
+  restart = () => {
+    this.current = 0;
+    this.outcome = '';
+  };
+
+  <template>
+    <FreestyleUsage
+      @name='Onboarding'
+      @description='The first-run walkthrough. Four decisions carry it. The rail is StepList — the same rail SessionPrep uses — so the kit has one visual grammar for "where am I in a sequence". The media is a slot, not a prop: an onboarding step shows a video, a screenshot, a live component or nothing, and no prop shape covers all four. Position is announced ("Step 2 of 4 — Ask before you Act"), because a walkthrough whose progress is only visible is a walkthrough a screen-reader user has to count. And Skip is always available and never hidden behind a corner glyph — a walkthrough you cannot leave is a modal, and this is not one.'
+    >
+      <:example>
+        {{#if this.outcome}}
+          <p class='demo-log'>You
+            {{this.outcome}}.</p>
+        {{else}}
+          <Onboarding
+            @steps={{STEPS}}
+            @current={{this.current}}
+            @onStepChange={{this.setCurrent}}
+            @onDone={{this.done}}
+            @onSkip={{this.skip}}
+          >
+            <:media as |step index|>
+              <div class='demo-media'>
+                <span class='demo-media-num'>{{index}}</span>
+                <span class='demo-media-cap'>{{step.caption}}</span>
+              </div>
+            </:media>
+          </Onboarding>
+        {{/if}}
+        <Button
+          @tone='neutral'
+          @appearance='outlined'
+          @size='s'
+          {{on 'click' this.restart}}
+        >Start over</Button>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='steps'
+          @description='{ id, title, body?, caption? }. `caption` is the rail label when the title is too long for a marker — the rail should read at a glance and the scene should read in full.'
+          @value={{STEPS}}
+        />
+        <Args.Number
+          @name='current'
+          @description='Controlled index, clamped to the step range so an out-of-bounds value can never blank the scene. Uncontrolled it starts at @defaultCurrent.'
+          @value={{this.current}}
+          @onInput={{this.setCurrent}}
+          @defaultValue={{0}}
+          @min={{0}}
+          @max={{3}}
+        />
+        <Args.Yield
+          @name='media'
+          @description='The step’s illustration, receiving (step, index). Drop a HoverVideoPlayer in here and the walkthrough previews the feature it is describing; supply nothing and the scene collapses to a single column.'
+          @hideControls={{true}}
+        />
+        <Args.Base
+          @name='onStepChange / onDone / onSkip'
+          @description='Next on the last step fires @onDone instead of advancing. @onSkip is optional and gates the skip button, because an escape hatch that does nothing is worse than none.'
+          @hideControls={{true}}
+        />
+        <Args.Base
+          @name='label / doneLabel / skipLabel / variant'
+          @description='The scene’s accessible name, the final-step button face (default "Get started"), the skip wording, and the rail presentation passed to StepList (default "track").'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .demo-log {
+        margin: 0 0 var(--space-4, 11px);
+        font-size: var(--text-ui-md, 12.5px);
+        color: var(--muted-foreground);
+      }
+      .demo-media {
+        display: grid;
+        place-items: center;
+        gap: 4px;
+        aspect-ratio: 16 / 10;
+        background: linear-gradient(
+          140deg,
+          color-mix(in oklch, var(--primary) 16%, var(--card)),
+          var(--inset, var(--boxel-100))
+        );
+      }
+      .demo-media-num {
+        font-family: var(--font-mono);
+        font-size: 34px;
+        font-weight: 700;
+        line-height: 1;
+        color: color-mix(
+          in oklch,
+          var(--foreground) 24%,
+          var(--primary)
+        );
+        font-variant-numeric: tabular-nums;
+      }
+      .demo-media-cap {
+        font-size: var(--text-ui-sm, 11.5px);
+        letter-spacing: 0.08em;
+        text-transform: uppercase;
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_ONBOARDING: Record<string, unknown> = {
+  Onboarding: OnboardingUsage,
+};