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

package/bundled-realms/pretui/components/signature-pad.md

@@ -0,0 +1,57 @@
+## What it is
+
+A signature capture surface with a typed-name alternative beside it.
+
+The alternative is not a convenience — it is the only path for anyone who cannot draw with a pointer, and it is the reason this component is usable at all.
+
+## The contract
+
+```
+@label?         — the visible label. Defaults to 'Signature'
+@description?   — helper text under the surface, wired via aria-describedby
+@signerName?    — who is signing; used in the image alt text and as the typed default
+@defaultStrokes?, @defaultTypedName? — rehydration from a previous @onChange payload
+@defaultMode?   — which method is offered first. 'draw' by default
+@hideTypedAlternative? — strongly discouraged; see below
+@penColor?      — opaque hex or rgb(); defaults to the resolved token ink
+@minWidth?      — thinnest stroke in px, clamped to [0.1, 10]
+@maxWidth?      — thickest stroke in px, clamped to [0.5, 30]
+@dotSize?       — radius of a single tap dot in px, clamped to [0, 20]
+@height?        — surface height in px, clamped to [80, 600]. Default 180
+@required?      — marks the control required and says so in the label
+@onChange?      — fires on every stroke, clear, typed keystroke and mode change
+
+<:default> — receives an api: clear, toSVG, toPNG, isEmpty, value
+```
+
+**`@hideTypedAlternative` is documented as discouraged in the signature itself.** It exists so a caller with a genuinely different fallback can say so out loud, rather than being unable to express that. Using it without one leaves a control that a large group of people simply cannot complete.
+
+**Every numeric arg is clamped**, so a caller cannot produce an unusable pen or a surface too small to sign on.
+
+**`@onChange` fires on everything** — strokes, clears, typed keystrokes, mode changes — so a form always holds the current state rather than needing to poll.
+
+**The block yields an imperative api** because export is inherently imperative: `toSVG` and `toPNG` are called when a form submits, not rendered.
+
+## Prior art
+
+The signature-pad libraries that wrap a canvas. The comparison worth making is not with their drawing quality but with their scope: a canvas with strokes on it is not a signature control, because it has exactly one input method.
+
+Where Pretui is better: the typed alternative is part of the component, with the mode change reported like any other change, rather than being something each product bolts on beside it.
+
+Where it is thinner: no pressure or tilt input, no stroke smoothing options beyond the width range, no timestamp or audit metadata in the payload, and no verification of any kind — this captures a mark, it does not attest to anything.
+
+## Accessibility
+
+- **The typed alternative is the accessibility story.** Drawing is a fine-motor pointer gesture with no keyboard equivalent that means anything; the typed name is the equal path, and it is why hiding it is called out in the contract.
+- **The rendered signature carries `role='img'` with alt text built from `@signerName`**, so an exported mark is described rather than being an unlabelled graphic.
+- **`@description` is wired through `aria-describedby`**, giving a place for "sign with your mouse or type your name" that is not a placeholder.
+- **`@required` says so in the label** rather than only setting an attribute — the asterisk is `aria-hidden` and the word is in the name.
+- **Mode changes are reported through `@onChange`**, so a form knows which method produced the value.
+
+## Theming
+
+`--pretui-sigpad-paper` (the surface), `--pretui-sigpad-ink` (the default pen), `--pretui-sigpad-radius`, `--pretui-sigpad-script` (the typeface the typed name renders in), over `--pretui-shadow-control`.
+
+`--pretui-sigpad-script` is the one that matters for the typed path: a typed signature set in the interface font reads as a text field, and set in a script face it reads as a signature. A theme that leaves it unset makes the alternative feel like a lesser option, which is exactly what it must not be.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/signature-pad.usage.gts

@@ -0,0 +1,222 @@
+// Pretui — SignaturePad usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { SignaturePad } from './signature-pad';
+import type { SignatureValue } from './signature-pad';
+import { Token } from './token';
+
+const MODES: string[] = ['draw', 'type'];
+
+// ── SignaturePad ─────────────────────────────────────────────────────────
+
+class SignaturePadUsage extends Component {
+  modes = MODES;
+
+  @tracked label = 'Contractor signature';
+  @tracked description =
+    'Sign with a pointer, or switch to Type and enter your full name.';
+  @tracked signerName = '';
+  @tracked defaultMode = 'draw';
+  @tracked hideTypedAlternative = false;
+  @tracked penColor = '';
+  @tracked minWidth = 0.7;
+  @tracked maxWidth = 2.4;
+  @tracked dotSize = 1.6;
+  @tracked height = 180;
+  @tracked required = false;
+  @tracked last: SignatureValue | undefined;
+
+  setLabel = (v: string) => (this.label = v);
+  setDescription = (v: string) => (this.description = v);
+  setSignerName = (v: string) => (this.signerName = v);
+  setDefaultMode = (v: string) => (this.defaultMode = v);
+  setHideTyped = (v: boolean) => (this.hideTypedAlternative = v);
+  setPenColor = (v: string) => (this.penColor = v);
+  setMinWidth = (v: number | null) => (this.minWidth = v ?? 0.7);
+  setMaxWidth = (v: number | null) => (this.maxWidth = v ?? 2.4);
+  setDotSize = (v: number | null) => (this.dotSize = v ?? 1.6);
+  setHeight = (v: number | null) => (this.height = v ?? 180);
+  setRequired = (v: boolean) => (this.required = v);
+  noteChange = (value: SignatureValue) => (this.last = value);
+
+  get defaultModeValue(): 'draw' | 'type' {
+    return this.defaultMode === 'type' ? 'type' : 'draw';
+  }
+  get penColorValue(): string | undefined {
+    return this.penColor.trim() === '' ? undefined : this.penColor;
+  }
+  get signerNameValue(): string | undefined {
+    return this.signerName.trim() === '' ? undefined : this.signerName;
+  }
+  get modeText(): string {
+    return this.last?.mode ?? '—';
+  }
+  get emptyText(): string {
+    return this.last ? String(this.last.isEmpty) : '—';
+  }
+  get strokeText(): string {
+    return this.last ? this.last.strokes.length + ' strokes' : '—';
+  }
+  get usage(): string {
+    return [
+      '<SignaturePad',
+      "  @label='" + this.label + "'",
+      "  @defaultMode='" + this.defaultMode + "'",
+      '  @height={{' + this.height + '}}',
+      '  @onChange={{this.persist}}',
+      '  as |sig|',
+      '>',
+      '  <button type="button" disabled={{sig.isEmpty}}>Save</button>',
+      '</SignaturePad>',
+    ].join('\n');
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='SignaturePad'
+      @description="Variable-width Bézier capture over pointer events, on a vendored signature_pad. Four things here are the reason most signature pads are bad. The backing store is scaled by devicePixelRatio, so strokes are not soft on a retina screen. A resize replays the stroke data instead of losing it — drag the height knob mid-signature and watch it survive the wipe that changing canvas.width always causes. The engine runs with throttle 0, which means it schedules no timer at all, so nothing here can outlive the element or hang a test run. And the typed-name alternative is a full peer of drawing, not a courtesy: same onChange payload, same isEmpty semantics, same SVG and PNG output, reachable by Tab alone — because a pointer-only input is not an input for everyone. @onChange emits the STROKE DATA, never a picture; the block yields toSVG() and toPNG() for when you actually want one, SVG first."
+      @source={{this.usage}}
+    >
+      <:example>
+        <SignaturePad
+          @label={{this.label}}
+          @description={{this.description}}
+          @signerName={{this.signerNameValue}}
+          @defaultMode={{this.defaultModeValue}}
+          @hideTypedAlternative={{this.hideTypedAlternative}}
+          @penColor={{this.penColorValue}}
+          @minWidth={{this.minWidth}}
+          @maxWidth={{this.maxWidth}}
+          @dotSize={{this.dotSize}}
+          @height={{this.height}}
+          @required={{this.required}}
+          @onChange={{this.noteChange}}
+        >
+          <p class='cap-readout'>
+            <span class='cap-readoutLabel'>@onChange</span>
+            <Token @value={{this.modeText}} />
+            <Token @value={{this.emptyText}} />
+            <Token @value={{this.strokeText}} />
+          </p>
+        </SignaturePad>
+      </:example>
+
+      <:api as |Args|>
+        <Args.String
+          @name='label'
+          @value={{this.label}}
+          @defaultValue='Signature'
+          @description='The visible label, and the stem of the canvas accessible name.'
+          @onInput={{this.setLabel}}
+        />
+        <Args.String
+          @name='description'
+          @value={{this.description}}
+          @description='Helper text under the surface, wired through aria-describedby to whichever input is active.'
+          @onInput={{this.setDescription}}
+        />
+        <Args.String
+          @name='signerName'
+          @value={{this.signerName}}
+          @description='Who is signing. Used in the exported image alt text, and as the initial typed name.'
+          @onInput={{this.setSignerName}}
+        />
+        <Args.String
+          @name='defaultMode'
+          @value={{this.defaultMode}}
+          @options={{this.modes}}
+          @defaultValue='draw'
+          @description='Which signing method is offered first.'
+          @onInput={{this.setDefaultMode}}
+        />
+        <Args.Bool
+          @name='hideTypedAlternative'
+          @value={{this.hideTypedAlternative}}
+          @defaultValue={{false}}
+          @description='Strongly discouraged — it removes the only path for anyone who cannot draw with a pointer. It exists so a caller with a genuinely different fallback has to say so out loud.'
+          @onInput={{this.setHideTyped}}
+        />
+        <Args.String
+          @name='penColor'
+          @value={{this.penColor}}
+          @description='Ink colour. Opaque hex or rgb() only; anything else falls back to the ink resolved from the theme token, which is also what happens when this is left empty.'
+          @onInput={{this.setPenColor}}
+        />
+        <Args.Number
+          @name='minWidth'
+          @value={{this.minWidth}}
+          @min={{0.1}}
+          @max={{10}}
+          @step={{0.1}}
+          @defaultValue={{0.7}}
+          @description='Thinnest stroke in px — the fast end of the velocity taper.'
+          @onInput={{this.setMinWidth}}
+        />
+        <Args.Number
+          @name='maxWidth'
+          @value={{this.maxWidth}}
+          @min={{0.5}}
+          @max={{30}}
+          @step={{0.1}}
+          @defaultValue={{2.4}}
+          @description='Thickest stroke in px — the slow end. Widen the gap for a more calligraphic line.'
+          @onInput={{this.setMaxWidth}}
+        />
+        <Args.Number
+          @name='dotSize'
+          @value={{this.dotSize}}
+          @min={{0}}
+          @max={{20}}
+          @step={{0.1}}
+          @defaultValue={{1.6}}
+          @description='Radius of a single tap dot, so a full stop is not invisible.'
+          @onInput={{this.setDotSize}}
+        />
+        <Args.Number
+          @name='height'
+          @value={{this.height}}
+          @min={{60}}
+          @max={{700}}
+          @defaultValue={{180}}
+          @description='Surface height in px, clamped to [80, 600]. Change it mid-signature: the strokes are replayed onto the new backing store rather than wiped.'
+          @onInput={{this.setHeight}}
+        />
+        <Args.Bool
+          @name='required'
+          @value={{this.required}}
+          @defaultValue={{false}}
+          @description='Marks the control required, with a visually-hidden "(required)" inside the label so it reaches AT.'
+          @onInput={{this.setRequired}}
+        />
+        <Args.Object
+          @name='onChange'
+          @value={{this.last}}
+          @description='Receives { mode, strokes, typedName, isEmpty } on every stroke, clear, typed keystroke and method change. Stroke data, not an image — the caller decides what to persist.'
+        />
+        <Args.Yield
+          @name='default'
+          @description='Receives the handle: mode, isEmpty, value, clear(), toSVG(), toPNG(), altText.'
+        />
+      </:api>
+    </FreestyleUsage>
+
+    <style scoped>
+      .cap-readout {
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        margin: 10px 0 0;
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+      .cap-readoutLabel {
+        font-family: var(--font-mono);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_SIGNATURE_PAD: Record<string, unknown> = {
+  SignaturePad: SignaturePadUsage,
+};

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

@@ -0,0 +1,46 @@
+// Pretui — Skeleton: a placeholder shape shown while content loads.
+import Component from '@glimmer/component';
+import { cssDeclaration, cssStyleFrom } from '../pretui-css';
+
+export interface SkeletonSignature {
+  Args: { width?: string; height?: string };
+  Element: HTMLSpanElement;
+}
+
+export class Skeleton extends Component<SkeletonSignature> {
+  get style() {
+    return cssStyleFrom([
+      cssDeclaration('--_w', this.args.width ?? '100%'),
+      cssDeclaration('--_h', this.args.height ?? '12px'),
+    ]);
+  }
+  <template>
+    <span class='pretui-skeleton' style={{this.style}} aria-hidden='true' data-test-pretui-skeleton ...attributes></span>
+    <style scoped>
+      @layer PretComponent {
+        @keyframes pretui-shimmer {
+          from {
+            background-position: 200% 0;
+          }
+          to {
+            background-position: -200% 0;
+          }
+        }
+        .pretui-skeleton {
+          display: block;
+          width: var(--_w, 100%);
+          height: var(--_h, 12px);
+          border-radius: 6px;
+          background: linear-gradient(90deg, var(--inset, var(--boxel-100)) 40%, var(--hover, var(--boxel-100)) 50%, var(--inset, var(--boxel-100)) 60%);
+          background-size: 200% 100%;
+          animation: pretui-shimmer 1.6s linear infinite;
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-skeleton {
+            animation: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,56 @@
+## What it is
+
+A shimmering grey rectangle standing in for content that has not arrived. Use it when you know the _shape_ of what is coming — a title line, three rows, an avatar — because a skeleton that matches the eventual layout prevents the reflow jolt that a spinner does not. If you do not know the shape, use **Spinner** or **LoadingState**. If the content will never arrive, **EmptyState**. If a specific reference is gone, **BrokenLink**.
+
+## The contract
+
+```
+@width? (default '100%'), @height? (default '12px')
+Element: HTMLSpanElement
+```
+
+Two args, both CSS length strings. Compose several to sketch a layout; there is no variant system, no `count`, no `circle` mode.
+
+**Both dimensions go through the kit's CSS guard.** `get style()` builds each declaration with `cssDeclaration`, so a value that fails the allowlist is dropped whole and the stylesheet's own `100%` / `12px` paints instead — the caller loses their override, never the component's rendering.
+
+That guard is the load-bearing part, and it is worth being precise about why the shape alone is not enough. Writing the value into a custom property the component chose (`--_w`, never a caller-supplied property name) stops the value becoming a _property_; it does not stop it becoming a second _declaration_. Unguarded, a `@width` of `0px; background: red` renders as `--_w: 0px; background: red; --_h: 12px` — a live declaration the caller chose. `components/skeleton.test.gts` pins the refusal: that input renders `--_h: 12px`, the width dropped whole and the stylesheet's own `var(--_w, 100%)` painting in its place. A chosen property name plus a validated value is the pattern to copy anywhere caller data reaches CSS; the property name on its own is half of it.
+
+The shimmer is a 200%-wide three-stop `linear-gradient` scrolled by `background-position` — one animation, no pseudo-element, no overlay.
+
+## Prior art
+
+**Web Awesome `wa-skeleton`** takes `effect` (`none | sheen | pulse`) and exposes `--color` and `--sheen-color`; you size it with CSS. **shadcn `Skeleton`** is a `<div>` with `animate-pulse` and a rounded background — you size it with Tailwind classes. **React Spectrum** has no skeleton; it uses `ProgressCircle` and content-shift avoidance instead.
+
+Pretui sits between the two: args rather than classes for size (so a call site does not need a styling system), and no effect axis. The improvement over shadcn is that **sizing is part of the API**, which means a skeleton is one self-describing element rather than an element plus a class soup. The improvement over Web Awesome is smaller — really just that the default 12px height matches the kit's body line box, so a bare `<Skeleton />` already looks like a line of text.
+
+Where it is behind: **no `pulse` alternative and no shape variants.** Web Awesome's `pulse` is the calmer effect and the one to prefer for large areas; a circular skeleton for avatars needs `border-radius` passed through `...attributes`, which works but is undiscoverable. The 6px radius is fixed.
+
+## Accessibility
+
+No APG pattern. Relevant criteria: WCAG **2.2.2 Pause, Stop, Hide**, **4.1.3 Status Messages**, **1.4.1**.
+
+What is right, and it is the important call:
+
+- **`aria-hidden="true"`.** Skeletons are pure decoration and are correctly removed from the accessibility tree. A page of twenty skeletons announces nothing, which is exactly right — the alternative (each one announced as an unlabelled region) is the common mistake.
+- **`prefers-reduced-motion: reduce` stops the animation entirely**, leaving a static grey block. That is the correct treatment for a decorative shimmer: unlike **Spinner**, where stopping the motion removes the meaning, a skeleton conveys everything it needs to by being there.
+
+Gaps — all of them at the composition level, which is where they belong:
+
+- **Nothing announces that content is loading, or that it has arrived.** Because the skeletons are `aria-hidden`, a screen-reader user gets _silence_ during the wait and then content appearing with no transition signal. The caller must supply a `role="status"` region — and it must exist in the DOM before the change, which is the usual live-region requirement. This is the single thing to get right when using Skeleton.
+- **`aria-busy="true"`** on the region being replaced is the other half, and nothing here sets or suggests it.
+- **The animation runs indefinitely.** WCAG 2.2.2 governs motion that starts automatically, lasts more than five seconds and runs in parallel with other content. A slow load with a screenful of skeletons qualifies, and there is no pause control — only the reduced-motion branch, which covers users who have set the preference and no one else.
+- **`role="presentation"` semantics via `aria-hidden` also hide any real content** placed inside a Skeleton. Do not nest content in one; it is meant to be empty.
+- The gray-on-gray gradient (`--inset` → `--hover` → `--inset`) is intentionally low contrast and carries no information, so **1.4.11** does not apply — but a theme that raises the contrast turns skeletons into visual noise.
+
+## Theming
+
+`--inset` (base) and `--hover` (the sheen's bright stop). That is the entire palette, and the two are adjacent by design — the shimmer should be barely perceptible.
+
+The 6px radius, 1.6s duration, `linear` easing and 200% gradient width are fixed. A theme cannot slow the shimmer or change its shape; retuning `--inset` and `--hover` closer together or further apart is the only available adjustment, and a theme that makes them very different will produce a distractingly strobing page. If you need circular skeletons for avatars, pass `style="border-radius: 50%"` through `...attributes` at the call site.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+Accept `width` / `height` / `radius` / `count`. Law 8: the skeleton
+must match the shape of the real content (AspectRatio for media).

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

@@ -0,0 +1,56 @@
+// Pretui — Skeleton usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Skeleton } from './skeleton';
+
+// ── Skeleton ← skeleton-placeholder/usage.gts ────────────────────────────
+// Dropped knobs: animation (wave/pulse/none — Pretui ships one shimmer;
+// reduced-motion turns it off in CSS).
+class SkeletonUsage extends GlimmerComponent {
+  @tracked width = '200px';
+  @tracked height = '20px';
+  setWidth = (v: string) => (this.width = v);
+  setHeight = (v: string) => (this.height = v);
+  <template>
+    <FreestyleUsage
+      @name='Skeleton'
+      @description='A skeleton placeholder component to show loading states'
+    >
+      <:example>
+        <div class='skeleton-stack'>
+          <Skeleton @width={{this.width}} @height={{this.height}} />
+          <Skeleton @width='140px' @height='12px' />
+          <Skeleton @width='80px' @height='12px' />
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='width'
+          @description='Width of the skeleton (px or %)'
+          @defaultValue='100%'
+          @value={{this.width}}
+          @onInput={{this.setWidth}}
+        />
+        <Args.String
+          @name='height'
+          @description='Height of the skeleton (px or %)'
+          @defaultValue='12px'
+          @value={{this.height}}
+          @onInput={{this.setHeight}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .skeleton-stack {
+        width: 240px;
+        display: grid;
+        gap: var(--space-3, 8px);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_SKELETON: Record<string, unknown> = {
+  Skeleton: SkeletonUsage,
+};

package/bundled-realms/pretui/components/skip-link.gts

@@ -0,0 +1,65 @@
+// Pretui — SkipLink: the first focusable control, a way past the chrome to the main content.
+import Component from '@glimmer/component';
+
+export interface SkipLinkSignature {
+  Args: {
+    /** The in-page target (default '#main'). Give that element the matching id. */
+    href?: string;
+    /** The link text (default 'Skip to content'). */
+    label?: string;
+  };
+  Element: HTMLAnchorElement;
+}
+
+/**
+ * WCAG 2.4.1 Bypass Blocks. Put it first in the pane, before the header and
+ * navigation. It is off screen until it receives focus, then appears at the
+ * top start corner of the nearest positioned ancestor so the keyboard user can see where they are. It is a plain
+ * in-page anchor, so it needs no router. The target should be focusable
+ * (`tabindex='-1'` on a `<main>`) so focus actually moves there, not only the
+ * scroll position.
+ */
+export class SkipLink extends Component<SkipLinkSignature> {
+  get href(): string {
+    return this.args.href ?? '#main';
+  }
+  get label(): string {
+    return this.args.label ?? 'Skip to content';
+  }
+  <template>
+    <a class='pretui-skip-link' href={{this.href}} data-test-pretui-skip-link ...attributes>{{this.label}}</a>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-skip-link {
+          position: absolute;
+          inset-block-start: var(--space-3, 0.5rem);
+          inset-inline-start: var(--space-3, 0.5rem);
+          z-index: var(--pretui-z-toast, 100);
+          padding: var(--space-2, 0.375rem) var(--space-4, 0.6875rem);
+          border-radius: var(--radius-control, 6px);
+          background: var(--primary);
+          color: var(--primary-foreground);
+          font-family: var(--font-sans);
+          font-size: var(--text-ui-md, 0.78rem);
+          font-weight: 600;
+          text-decoration: none;
+          box-shadow: var(--pretui-shadow-raised, 0 0 0 1px var(--border));
+        }
+        /* Off screen but in the tab order and the accessibility tree until it
+           has focus: the clip pattern, not display: none. */
+        .pretui-skip-link:not(:focus) {
+          inline-size: 1px;
+          block-size: 1px;
+          padding: 0;
+          overflow: hidden;
+          clip-path: inset(50%);
+          white-space: nowrap;
+        }
+        .pretui-skip-link:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 2px;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/skip-link.md

@@ -0,0 +1,49 @@
+## What it is
+
+**The first focusable control in a pane**: a link past the header and navigation to the main content. It satisfies WCAG 2.4.1 Bypass Blocks. It is off screen until it receives focus, then appears in the top start corner, so a keyboard user sees where the first Tab took them.
+
+Put exactly one SkipLink first in the pane, before any header or navigation. For other screen-reader-only text, use **VisuallyHidden**.
+
+## The contract
+
+```
+@href? (default '#main')
+@label? (default 'Skip to content')
+Element: HTMLAnchorElement
+```
+
+**A plain in-page anchor.** It needs no router and no script: following it moves the document to the element with the matching id. Give the target `tabindex='-1'`, for example `<main id='main' tabindex='-1'>`, so focus moves there too, not only the scroll position. Without it, the next Tab starts from the top again in some browsers.
+
+**Hidden with the clip pattern until focused.** Unfocused, it is 1px and clipped, but it stays in the tab order and the accessibility tree. Focused, it is a solid primary-toned pill, absolutely positioned in the top start corner of the nearest positioned ancestor.
+
+## Prior art
+
+**Chakra `SkipNavLink` / `SkipNavContent`** pairs the link with a target component that carries the id. **Gov.uk and USWDS** ship a skip link as a class on an anchor. Most other React kits (Radix, MUI, Ant, Mantine) have none, and agents hand-roll an `sr-only focus:not-sr-only` anchor.
+
+Where Pretui is better: the hidden state keeps the link reachable. Hand-rolled versions often use `display: none` until focus, which never receives focus at all. Where it is thinner: **no target component**. Chakra's `SkipNavContent` sets the id and `tabindex` for you; here you put them on your `<main>`.
+
+## Accessibility
+
+No APG pattern. WCAG 2.4.1 and the conventions around it.
+
+- **It is a real link.** `<a href>`, in the natural tab order with no `tabindex` and no `aria-hidden`. The tests assert the tag, the default `href` and label, and that it can take focus.
+- **It must come first.** A skip link after the navigation skips nothing. Render it before the header.
+- **The target must accept focus.** Put `tabindex='-1'` on it so focus moves with the scroll.
+- **The label says where it goes.** "Skip to content" is the convention. Use "Skip to results" or similar when the main region has a more specific job.
+- **The focus ring is always shown** on `:focus-visible`.
+
+## Theming
+
+`--primary` and `--primary-foreground` (the revealed pill), `--radius-control`, `--pretui-shadow-raised`, `--ring` (focus ring), `--font-sans`, `--text-ui-md`, `--space-2`, `--space-3` and `--space-4`, and `--pretui-z-toast`, so it sits above page chrome while it is visible.
+
+The corner position and the clip-until-focus behaviour are fixed.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+| Agent types                                 | Give them                                  |
+| ------------------------------------------- | ------------------------------------------ |
+| Chakra `<SkipNavLink>`                      | `<SkipLink />`                             |
+| Chakra `<SkipNavContent>`                   | `id='main' tabindex='-1'` on your `<main>` |
+| `<a className="sr-only focus:not-sr-only">` | `<SkipLink @href @label />`                |

package/bundled-realms/pretui/components/skip-link.usage.gts

@@ -0,0 +1,47 @@
+// Pretui — SkipLink usage page.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { FreestyleUsage } from './freestyle-usage';
+import { SkipLink } from './skip-link';
+
+const SOURCE = "<SkipLink @href='#main' />\n<header>…</header>\n<main id='main' tabindex='-1'>…</main>";
+
+const SkipLinkUsage: TemplateOnlyComponent = <template>
+  <FreestyleUsage
+    @name='SkipLink'
+    @description='The first focusable control in a pane: a way past the header and navigation to the main content (WCAG 2.4.1). It is off screen until it has focus. Tab into the demo frame to see it.'
+    @source={{SOURCE}}
+  >
+    <:example>
+      <div class='sk-demo'>
+        <SkipLink @href='#sk-demo-main' />
+        <nav class='sk-demo-nav'><a href='#sk-demo-main'>Lots</a> <a href='#sk-demo-main'>Roasts</a> <a href='#sk-demo-main'>Orders</a></nav>
+        <main id='sk-demo-main' class='sk-demo-main' tabindex='-1'>Main content</main>
+      </div>
+    </:example>
+    <:api as |Args|>
+      <Args.String @name='href' @defaultValue='#main' @description='The in-page target. Give it the matching id and tabindex=-1.' />
+      <Args.String @name='label' @defaultValue='Skip to content' />
+    </:api>
+  </FreestyleUsage>
+  <style scoped>
+    .sk-demo {
+      position: relative;
+      padding: var(--space-6, 1.25rem) var(--space-4, 0.6875rem) var(--space-4, 0.6875rem);
+      border-radius: var(--radius-surface, 10px);
+      box-shadow: 0 0 0 1px var(--border);
+    }
+    .sk-demo-nav {
+      display: flex;
+      gap: var(--space-4, 0.6875rem);
+      font-size: var(--text-ui-md, 0.78rem);
+    }
+    .sk-demo-main {
+      margin-block-start: var(--space-4, 0.6875rem);
+      color: var(--muted-foreground);
+    }
+  </style>
+</template>;
+
+export const DEMOS_SKIP_LINK: Record<string, unknown> = {
+  SkipLink: SkipLinkUsage,
+};

package/bundled-realms/pretui/components/slide-over.gts

@@ -0,0 +1,2 @@
+// Pretui — SlideOver: What shadcn calls Sheet: Drawer under a name that cannot collide.
+export { Drawer as SlideOver } from './drawer';

package/bundled-realms/pretui/components/slide-over.md

@@ -0,0 +1,41 @@
+## What it is
+
+**SlideOver** is **Drawer** under a name that cannot collide. shadcn calls this edge-anchored panel `Sheet`, but **Pretui `Sheet` is a spreadsheet**, so an agent that types Sheet for a slide-over gets the wrong component. SlideOver is the same export as Drawer, and the **Drawer** writeup carries the depth. A centred overlay is **Dialog**.
+
+## The contract
+
+```
+@open?, @onClose?, @onOpenChange?
+@label?          — the accessible name
+@placement? ('start' | 'end' | 'bottom'; default 'end'; the React spellings map)
+@dismissible? (default true)
+<:title> <:default> <:footer>
+Element: HTMLDialogElement
+```
+
+Identical to Drawer: a native `<dialog>` opened with `showModal()` and placed against one edge.
+
+## Prior art
+
+**shadcn `Sheet`** is Radix Dialog with a `side` of `top | right | bottom | left`. **MUI `Drawer`** takes `anchor`, `open`, `onClose` and `variant` (`temporary | persistent | permanent`). **Ant `Drawer`** takes `placement`, `open`, `onClose`, `size`, `extra` and `footer`. **Web Awesome `wa-drawer`** takes `placement` and `open`.
+
+Drawer's placements are logical, so `end` is on the left in RTL. It has no `top` placement and no persistent or permanent mode. A panel that stays in the layout is **SplitPanes** or a sidebar, not a modal drawer.
+
+## Accessibility
+
+Identical to Drawer: APG **Dialog (Modal)**. A drawer is a dialog with geometry. `showModal()` supplies the focus trap, Escape, `::backdrop`, inert background and stacking. `@label` is the only labelling route, so pass it as well as any `<:title>`.
+
+## Theming
+
+Identical to Drawer: `--pretui-drawer-size`, `--card`, `--foreground`, `--muted-foreground`, `--border`, `--radius-surface`, `--pretui-shadow-overlay`, `--pretui-overlay-scrim`, `--text-heading`, `--weight-heading`, `--track-heading`, `--text-body`, `--leading-body`, `--space-3`, `--space-4` and `--space-6`.
+
+## React ecosystem
+
+| shadcn / MUI / Ant            | Pretui                         |
+| ----------------------------- | ------------------------------ |
+| shadcn `<Sheet side="right">` | `<SlideOver @placement='end'>` |
+| MUI `anchor="left"`           | `@placement='start'`           |
+| Ant `placement="bottom"`      | `@placement='bottom'`          |
+| `open` / `onClose`            | `@open` / `@onClose`           |
+| `SheetTitle`                  | `<:title>` plus `@label`       |
+| MUI `variant="permanent"`     | **SplitPanes**, not a drawer   |