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

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

@@ -0,0 +1,62 @@
+## What it is
+
+An immediate on/off. The distinction from **Checkbox** is not shape, it is _when the change lands_: a Switch takes effect the moment it is flipped, a Checkbox is a value collected and submitted. If your Switch sits above a Save button, it should have been a Checkbox. For one-of-many use **RadioGroup**; for a pressed/unpressed _action_ use a **Button** with `aria-pressed`.
+
+## The contract
+
+```
+@checked?, @defaultChecked?, @disabled?, @controlId?
+@onCheckedChange?(checked: boolean)
+Element: HTMLButtonElement
+```
+
+Hybrid controlled/uncontrolled — `@checked ?? @internal`, with `@internal` written only when `@checked === undefined` — the same idiom as Checkbox, RadioGroup, Select, Tabs and Slider.
+
+`@controlId` lands on the element so **Field**/**FormField** can wire `<label for>`. There is no label arg; the label is the wrapper's job, which keeps one owner for the association but means a bare Switch has no name (see below).
+
+The implementation is a `<button role="switch">` rather than `<input type="checkbox" role="switch">`. That is the one decision worth questioning: the checkbox route keeps native `checked` state, form participation and the platform's own toggle semantics, and it is what React Aria and Web Awesome both do. The button route is simpler to style and is what Radix does. Neither is wrong; the button route just means form submission is entirely on the caller.
+
+The `disabled` guard is doubled — the native `disabled` attribute _and_ an early return in `toggle` — which is belt-and-braces rather than redundant, since `...attributes` could in principle re-enable the element.
+
+## Prior art
+
+**APG Switch** is the pattern, and all three respected implementations follow it. **React Aria `useSwitch`** builds on `useToggle` and puts `role="switch"` on a real checkbox input. **Web Awesome `wa-switch`** likewise uses `<input type="checkbox" role="switch">`, and adds ArrowLeft/ArrowRight (RTL-aware) as toggle keys plus a `hint` prop and slot, with `setValue` → `null` when unchecked so unchecked switches submit nothing. **Radix `Switch`** is `Root` + `Thumb` with `checked`/`defaultChecked`/`onCheckedChange`, rendering a visually hidden native input for form participation.
+
+Pretui is deliberately the smallest of the four. Where it is better: the thumb travel is a single `transform: translateX(12px)` transition on a `data-state` attribute with a `prefers-reduced-motion` opt-out, so the animation is CSS state rather than a JS-driven value, and the whole component has no runtime beyond the toggle handler.
+
+Where it is behind:
+
+- **No arrow-key toggling.** Web Awesome adds Left/Right, which is a small, real usability gain on a settings page.
+- **No form participation.** Radix and Web Awesome both submit a value; Pretui submits nothing. `name`/`value` cannot be threaded because there is no input.
+- **No hint/label slot**, no size axis, no invalid state.
+
+## Accessibility
+
+Governing pattern: APG **Switch**. `role="switch"` and `aria-checked` `'true'`/`'false'` are both present and correct — and notably `aria-checked` is never `'mixed'`, which the Switch pattern forbids (unlike Checkbox, where `mixed` is legal).
+
+Keyboard: it is a native `<button>`, so **Space and Enter both activate**. APG requires Space and permits Enter, so this passes.
+
+Gaps:
+
+- **No accessible name of its own.** There is no `@label`, and the only content is an empty thumb `<span>`. A Switch outside `Field`/`FormField` and without an explicit `aria-label` is announced as "switch, off" with no indication of what it controls. This is the most likely real-world failure, because a Switch is visually self-evident and developers do not notice the omission.
+- **`@disabled` uses the native attribute**, so a disabled switch leaves the tab order entirely and cannot be discovered by a keyboard user scanning a settings panel. `aria-disabled` would keep it readable.
+- **`opacity: 0.45`** for disabled will fail contrast in most themes.
+- **No focus-visible ring is defined.** The track uses `background` and the thumb uses `box-shadow`; nothing paints `:focus-visible`, so the control relies on the UA outline around a 30×18 pill. Likely WCAG 2.4.7 failure.
+- **Target size is 30×18 CSS px**, below the 24×24 minimum of WCAG 2.5.8 on the short axis. Wrapping it in a larger label row (which `Field` does) resolves it in practice, but a bare Switch in a table row does not.
+- The label, if a wrapper supplies one, must not change with state — "Notifications", not "Notifications on". That is an APG requirement and a caller obligation.
+
+## Theming
+
+Track: `--pretui-control-border` (falling back to `--line-strong`) when off, `--primary` when on. Thumb: `--card` with `--shadow-ink-mid`. Pressed: `--pretui-shadow-inset`. Motion: `--pretui-dur-snap`, `--pretui-ease-snap`.
+
+The 30×18 track, 14px thumb and 12px travel are fixed — there is no size axis, so a theme cannot scale it alongside Button's `xs`–`xl`. That inconsistency is visible when a Switch sits next to an `xs` Button.
+
+A theme that sets `--primary` close in luminance to `--line-strong` makes on and off indistinguishable for anyone not perceiving hue; the thumb position is the only other cue, and it is subtle at this size.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+Immediate on/off setting. **Toggle** is a pressed _button_ (toolbar).
+**Checkbox** is a form value. Accept `isSelected` / `onSelectedChange`
+as aliases of `@checked` / `@onChange`.

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

@@ -0,0 +1,59 @@
+// Pretui — Switch usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Switch } from './switch';
+
+// ── Switch ← switch/usage.gts ────────────────────────────────────────────
+// Dropped knobs: @label (no label arg on the bare control — pair with Field
+// or your own <label>; boxel-ui rendered it inline).
+export class SwitchUsage extends Component {
+  @tracked checkedVal = false;
+  @tracked disabled = false;
+  setChecked = (v: boolean) => (this.checkedVal = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  get usage() {
+    let bits = [`@checked={{${this.checkedVal}}}`];
+    if (this.disabled) bits.push('@disabled={{true}}');
+    bits.push('@onCheckedChange={{this.setChecked}}');
+    return `<Switch ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Switch'
+      @description='A switch is a component that allows the user to switch a setting on or off.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <Switch
+          @checked={{this.checkedVal}}
+          @disabled={{this.disabled}}
+          @onCheckedChange={{this.setChecked}}
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.Bool
+          @name='checked'
+          @defaultValue={{false}}
+          @value={{this.checkedVal}}
+          @description="Controlled on/off state — boxel-ui's @isEnabled."
+          @onInput={{this.setChecked}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @defaultValue={{false}}
+          @value={{this.disabled}}
+          @onInput={{this.setDisabled}}
+        />
+        <Args.Action
+          @name='onCheckedChange'
+          @description="Receives the next checked state as a boolean — boxel-ui's @onChange."
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_SWITCH: Record<string, unknown> = {
+  Switch: SwitchUsage,
+};

package/bundled-realms/pretui/components/table-of-contents.gts

@@ -0,0 +1,384 @@
+// Pretui — TableOfContents: a scroll-spy table of contents with one IntersectionObserver and a travelling marker.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { fn } from '@ember/helper';
+import { on } from '@ember/modifier';
+import { htmlSafe } from '@ember/template';
+import { modifier } from 'ember-modifier';
+
+// The row's link or button: the caller's attributes land once, on whichever
+// element renders, so the two modes cannot drift apart.
+const TocLink: TemplateOnlyComponent<{
+  Args: { asLink: boolean; href?: string };
+  Blocks: { default: [] };
+  Element: HTMLAnchorElement | HTMLButtonElement;
+}> = <template>
+  {{#if @asLink}}
+    <a href={{@href}} ...attributes>{{yield}}</a>
+  {{else}}
+    <button type='button' ...attributes>{{yield}}</button>
+  {{/if}}
+</template>;
+
+// ── TableOfContents ──────────────────────────────────────────────────────
+// Document navigation with a marker that TRAVELS between sections.
+//
+// Two mechanisms, both cheap: (1) section tracking is ONE IntersectionObserver
+// over the heading elements, created inside a modifier and disconnected on
+// cleanup — no scroll handler, no rAF, no re-measure per frame. The observer
+// auto-roots on the nearest scrollable ancestor of the first heading, so a TOC
+// beside a scrolling panel works without the caller wiring a root. (2) The
+// active marker is one absolutely-positioned bar whose top/height follow the
+// active link (Law 5's sliding highlight, measured in a modifier with a
+// ResizeObserver for reflow). A SlidingHighlight primitive is landing in
+// motion-core.gts in parallel; this local copy should be replaced by it once
+// both are on the realm — the behaviour is identical, only vertical.
+//
+// Dropped from the docs-site originals: nested collapsible sub-lists (an
+// accordion in a TOC hides the thing the reader came for; levels indent
+// instead), and scroll-into-view on activation (that is the caller's
+// scroll-behavior, not ours to seize).
+//
+// Two row modes, chosen the way the rest of the kit chooses: a row with an
+// href is a link, a row without one is a button. Links (the default) are
+// `<a href="#id">`, so the browser's fragment navigation scrolls the page.
+// `@links={{false}}` drops the href and renders every row as a
+// `<button type="button">`, so a caller whose sections live in its own
+// scrolling panel (an edit form, a split view) does the scrolling itself from
+// the @onSelect event's `currentTarget`. @onSelect only reports the click, in
+// either mode; it never changes what renders.
+
+export interface TocItem {
+  /** the target element's DOM id — becomes the link's href fragment and
+   * what the spy observes; with `@links={{false}}` it is whatever key the
+   * caller needs */
+  id: string;
+  /** link text; override the rendering with the <:item> block */
+  label: string;
+  /** 1-based heading depth; 1 is flush, each level indents (default 1) */
+  level?: number;
+}
+
+interface TocRow {
+  item: TocItem;
+  level: number;
+  style: ReturnType<typeof htmlSafe>;
+}
+
+export interface TableOfContentsSignature {
+  Args: {
+    /** the document's sections, in document order */
+    items: TocItem[];
+    /** accessible name for the nav landmark (default 'On this page') */
+    label?: string;
+    /** controlled active id; omit for uncontrolled */
+    activeId?: string;
+    /** initial active id when uncontrolled (defaults to the first item) */
+    defaultActiveId?: string;
+    /** fires with the id whenever the active section changes — from a click
+     * or from the observer */
+    onActiveChange?: (id: string) => void;
+    /** fires with the id and the click event when a row is clicked, in
+     * either mode; it reports, and never changes what renders */
+    onSelect?: (id: string, event: Event) => void;
+    /** rows are `<a href="#id">` fragment links (default true). False renders
+     * them as `<button type="button">` with no href: the component never
+     * scrolls, and the caller does from the @onSelect event's
+     * `currentTarget`. */
+    links?: boolean;
+    /** watch the document and follow the reader's scroll. Defaults to
+     * @links: on for fragment links, off for buttons, whose ids need not be
+     * DOM ids and would otherwise match unrelated elements in the document */
+    spy?: boolean;
+    /** how far down the viewport a heading must reach before it becomes
+     * active, as a percentage (default 38 — the top ~38% is the read band) */
+    band?: number;
+  };
+  Blocks: {
+    /** replaces the row text; receives the item, whether it is active, and
+     * its 0-based position in @items */
+    item?: [item: TocItem, active: boolean, index: number];
+  };
+  Element: HTMLElement;
+}
+
+// Nearest scrollable ancestor — the IntersectionObserver root that makes the
+// read band mean what it says inside a scrolling panel.
+function scrollParent(el: HTMLElement): HTMLElement | null {
+  let node: HTMLElement | null = el.parentElement;
+  while (node) {
+    let overflow = getComputedStyle(node).overflowY;
+    if (overflow === 'auto' || overflow === 'scroll' || overflow === 'overlay') {
+      return node;
+    }
+    node = node.parentElement;
+  }
+  return null;
+}
+
+export class TableOfContents extends Component<TableOfContentsSignature> {
+  @tracked private internalActive: string | undefined =
+    this.args.defaultActiveId;
+
+  get label(): string {
+    return this.args.label ?? 'On this page';
+  }
+  get rows(): TocRow[] {
+    return (this.args.items ?? []).map((item) => {
+      let level = Math.max(1, Math.floor(item.level ?? 1));
+      return { item, level, style: htmlSafe(`--_level: ${level}`) };
+    });
+  }
+  get ids(): string[] {
+    return (this.args.items ?? []).map((i) => i.id);
+  }
+  get activeId(): string | undefined {
+    return (
+      this.args.activeId ?? this.internalActive ?? this.args.items?.[0]?.id
+    );
+  }
+  get links(): boolean {
+    return this.args.links ?? true;
+  }
+  get spy(): boolean {
+    return this.args.spy ?? this.links;
+  }
+  get band(): number {
+    return Math.min(90, Math.max(5, this.args.band ?? 38));
+  }
+  isActive = (row: TocRow): boolean => row.item.id === this.activeId;
+  hrefFor = (row: TocRow): string => `#${row.item.id}`;
+
+  private setActive(id: string) {
+    if (this.args.activeId === undefined) {
+      this.internalActive = id;
+    }
+    this.args.onActiveChange?.(id);
+  }
+  activate = (id: string, event: Event) => {
+    this.setActive(id);
+    this.args.onSelect?.(id, event);
+  };
+  private handleSpy = (id: string) => {
+    this.setActive(id);
+  };
+
+  /** One observer for the whole document. Entries flow into a live set; the
+   * active section is the FIRST item (document order) currently inside the
+   * read band, which is what a reader would call "where I am". */
+  sectionSpy = modifier(
+    (
+      el: HTMLElement,
+      [ids, enabled, band, onActive]: [
+        string[],
+        boolean,
+        number,
+        (id: string) => void,
+      ],
+    ) => {
+      if (!enabled || !ids.length) {
+        return undefined;
+      }
+      let doc = el.ownerDocument;
+      let targets = ids
+        .map((id) => doc.getElementById(id))
+        .filter((t): t is HTMLElement => !!t);
+      if (!targets.length) {
+        return undefined;
+      }
+      let inBand = new Set<string>();
+      let observer = new IntersectionObserver(
+        (entries) => {
+          for (let entry of entries) {
+            if (entry.isIntersecting) {
+              inBand.add(entry.target.id);
+            } else {
+              inBand.delete(entry.target.id);
+            }
+          }
+          let first = ids.find((id) => inBand.has(id));
+          if (first) {
+            onActive(first);
+          }
+        },
+        {
+          root: scrollParent(targets[0]),
+          rootMargin: `0px 0px -${100 - band}% 0px`,
+          threshold: 0,
+        },
+      );
+      for (let target of targets) {
+        observer.observe(target);
+      }
+      return () => observer.disconnect();
+    },
+  );
+
+  /** Measures the active link and parks the travelling marker on it. No
+   * timers: it runs on arg change and on reflow (ResizeObserver, disconnected
+   * on cleanup). */
+  marker = modifier((list: HTMLElement, [activeId]: [string | undefined]) => {
+    let apply = () => {
+      let active: HTMLElement | undefined;
+      let links = list.querySelectorAll('[data-toc-id]');
+      for (let i = 0; i < links.length; i++) {
+        let candidate = links[i] as HTMLElement;
+        if (candidate.dataset.tocId === activeId) {
+          active = candidate;
+          break;
+        }
+      }
+      if (!active) {
+        list.style.setProperty('--pretui-toc-marker-opacity', '0');
+        return;
+      }
+      list.style.setProperty('--pretui-toc-marker-opacity', '1');
+      list.style.setProperty('--pretui-toc-marker-top', `${active.offsetTop}px`);
+      list.style.setProperty(
+        '--pretui-toc-marker-height',
+        `${active.offsetHeight}px`,
+      );
+    };
+    apply();
+    let observer = new ResizeObserver(apply);
+    observer.observe(list);
+    return () => observer.disconnect();
+  });
+
+  <template>
+    <nav
+      class='pretui-toc'
+      aria-label={{this.label}}
+      data-test-pretui-toc
+      {{this.sectionSpy this.ids this.spy this.band this.handleSpy}}
+      ...attributes
+    >
+      <div class='pretui-toc-track' {{this.marker this.activeId}}>
+        {{! the marker is chrome: a sibling of the list, never a list item }}
+        <span class='pretui-toc-marker' aria-hidden='true'></span>
+        {{! role='list' is not redundant: list-style:none strips list
+            semantics in Safari/VoiceOver, and the lint rule allows ol+list }}
+        <ol class='pretui-toc-list' role='list'>
+          {{#each this.rows key='item.id' as |row index|}}
+            <li class='pretui-toc-row' style={{row.style}}>
+              <TocLink
+                @asLink={{this.links}}
+                @href={{if this.links (this.hrefFor row)}}
+                class='pretui-toc-link'
+                data-toc-id={{row.item.id}}
+                data-active={{if (this.isActive row) 'true'}}
+                aria-current={{if (this.isActive row) 'location'}}
+                {{on 'click' (fn this.activate row.item.id)}}
+              >
+                {{#if (has-block 'item')}}
+                  {{yield row.item (this.isActive row) index to='item'}}
+                {{else}}
+                  {{row.item.label}}
+                {{/if}}
+              </TocLink>
+            </li>
+          {{/each}}
+        </ol>
+      </div>
+    </nav>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-toc {
+          min-width: 0;
+          font-size: var(--boxel-font-size-xs);
+        }
+        .pretui-toc-track {
+          position: relative;
+          padding-inline-start: var(--pretui-toc-rail-gap, var(--boxel-sp-sm));
+        }
+        /* the rail the marker travels down */
+        .pretui-toc-track::before {
+          content: '';
+          position: absolute;
+          inset-inline-start: 0;
+          top: 0;
+          bottom: 0;
+          width: 1px;
+          background-color: var(--border);
+        }
+        .pretui-toc-list {
+          list-style: none;
+          margin: 0;
+          padding: 0;
+          display: grid;
+          gap: var(--boxel-sp-6xs);
+        }
+        .pretui-toc-marker {
+          position: absolute;
+          inset-inline-start: 0;
+          width: 2px;
+          border-radius: 1px;
+          background-color: var(--primary-ink);
+          top: var(--pretui-toc-marker-top, 0);
+          height: var(--pretui-toc-marker-height, 0);
+          opacity: var(--pretui-toc-marker-opacity, 0);
+          transition:
+            top 220ms var(--pretui-ease-snap, cubic-bezier(0.2, 0.8, 0.2, 1)),
+            height 220ms var(--pretui-ease-snap, cubic-bezier(0.2, 0.8, 0.2, 1));
+        }
+        .pretui-toc-row {
+          padding-inline-start: calc(
+            var(--pretui-toc-indent, var(--boxel-sp-sm)) * (var(--_level, 1) - 1)
+          );
+          min-width: 0;
+        }
+        .pretui-toc-link {
+          display: block;
+          padding: var(--boxel-sp-3xs) var(--boxel-sp-2xs);
+          border-radius: var(--boxel-border-radius-sm);
+          color: var(--muted-foreground);
+          text-decoration: none;
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+          transition-property: color, background-color;
+          transition-duration: 140ms;
+          transition-timing-function: var(--pretui-ease-snap, ease);
+        }
+        /* button mode: the same row, without the button's own chrome */
+        button.pretui-toc-link {
+          width: 100%;
+          border: 0;
+          background-color: transparent;
+          font-family: inherit;
+          font-size: inherit;
+          font-weight: inherit;
+          font-style: inherit;
+          line-height: inherit;
+          letter-spacing: inherit;
+          text-align: start;
+        }
+        /* gated on a hovering pointer, so a tapped row on a touch screen does
+           not keep the fill */
+        @media (hover: hover) {
+          .pretui-toc-link:hover {
+            color: var(--foreground);
+            background-color: var(--hover);
+          }
+        }
+        .pretui-toc-link[data-active='true'] {
+          color: var(--foreground);
+          font-weight: 500;
+        }
+        .pretui-toc-link:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 1px;
+        }
+        /* reduced motion keeps the END state (the marker is already parked on
+           the active row), it just stops travelling */
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-toc-marker,
+          .pretui-toc-link {
+            transition: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/table-of-contents.md

@@ -0,0 +1,75 @@
+## What it is
+
+The "On this page" sidebar: a list of a document's sections that follows the reader's scroll and marks where they are. Use it beside long-form content — a **Prose** article, a spec, a card with many sections. If the sections are collapsible panels rather than headings, **Accordion** already shows the structure. If the reader is stepping through a process, **StepList**.
+
+## The contract
+
+```
+@items: { id, label, level? }[]   (required, in document order)
+@label? ('On this page')
+@activeId? / @defaultActiveId? / @onActiveChange?(id)
+@onSelect?(id, event)
+@links? (default true)
+@spy? (default @links)
+@band? (default 38)
+<:item as |item, active, index|>
+Element: HTMLElement (a <nav>)
+```
+
+**`@band` is the read band, as a percentage of the viewport.** A heading becomes active once it reaches the top 38% of the scroll container. That is the parameter every scroll-spy has and almost none exposes: too small and headings activate only when they touch the very top, too large and the active item runs ahead of what you are reading. Clamped to 5–90.
+
+**`@items[].id` is a real DOM id** and becomes the link's `href` fragment — so the links work with JavaScript off, and the browser's native fragment navigation does the scrolling.
+
+**`@onSelect` reports a click.** It fires with `(id, event)` when a row is clicked, and it never changes what renders: a link-mode caller can use it to close a mobile drawer and the fragment link still navigates. This is unlike **Swatch**, where `@onSelect` is what turns a static `<span>` chip into a `<button>`: a contents row is clickable in both modes, so the element follows the `href` (`@links`), not the handler.
+
+**`@links={{false}}` is button mode.** The kit renders a row with an `href` as a link and a row without one as a button (**Button**, **BottomNav**, **SidebarItem**), and here the `href` is the generated `#id`, so turning it off is the switch. Every row is then a `<button type="button">` with no `href`, and the component does no scrolling, so the caller owns it through `@onSelect`. Use it when the sections live in the caller's own scroll container and fragment navigation would scroll the wrong thing, such as an edit form inside a panel: the caller finds its root from `event.currentTarget` and calls `scrollIntoView` on the section. The ids then only have to mean something to the caller. `@onActiveChange`, `@activeId`, the marker and `aria-current` work the same in both modes.
+
+**`@spy` defaults to `@links`.** The spy looks up each id with `getElementById` across the whole document, which is right for fragment links and wrong for buttons, whose ids may be generic keys (`details`, `pricing`) that match an unrelated element elsewhere on the page. So it is on for links and off for buttons. A button-mode caller whose keys are real DOM ids in its own scroller can pass `@spy={{true}}`.
+
+**`<:item>` gets the row's 0-based position** as its third argument, for a numbered rail ("01", "02") without the caller indexing `@items` itself.
+
+Two things deliberately dropped from the docs-site originals: **nested collapsible sub-lists** (an accordion in a table of contents hides the thing the reader came for; levels indent instead), and **scroll-into-view on activation** (that is the caller's `scroll-behavior`, not the component's to seize).
+
+## Prior art
+
+**Nextra**, **Docusaurus** and **react-bits**' scroll-spy all take the same approach: bind a `scroll` listener, re-measure every heading's `getBoundingClientRect` on every frame, then cross-fade an active class.
+
+Pretui differs on both halves, and both are improvements:
+
+- **One `IntersectionObserver` instead of a scroll listener.** No per-frame measurement, no layout thrash, and the work happens off the main thread's critical path. The observer is **auto-rooted on the real scroll container** — `scrollParent()` walks up looking for `overflow-y: auto | scroll | overlay` — so a TOC beside a scrolling panel works without the caller wiring a root. In a card system where the scroll container is almost never the viewport, that is the difference between working and not.
+- **The active marker travels.** One absolutely-positioned bar whose `top` and `height` follow the active link, measured in a modifier with a `ResizeObserver` for reflow — Law 5's sliding-highlight mechanism, the same idea as **Tabs** and **SegmentedControl**, here vertical. The docs-site originals cross-fade a class, which reads as two separate marks blinking rather than one mark moving.
+
+The source notes this local marker implementation should be replaced by **SlidingHighlight** (`components/sliding-highlight.gts`) once both are on the realm — identical behaviour, only vertical. Worth knowing there are currently two copies of the mechanism.
+
+Where it is behind: **no nested collapse** (deliberate), no "back to top", and no automatic heading extraction — you pass `@items` explicitly, which means a markdown render has to produce them.
+
+## Accessibility
+
+No APG pattern; the governing conventions are the navigation landmark plus `aria-current`, and WCAG **2.4.8 Location** (AAA) is the criterion a TOC exists to satisfy.
+
+What is right, and two details are better than most implementations:
+
+- **`<nav aria-label="On this page">`** — a labelled landmark, so it is distinguishable from the page's other navs.
+- **`aria-current="location"`** on the active link. Note the value: `location`, not `page`. That is the correct one — `page` means "this link points at the current page", `location` means "this is where you are within it". Almost every TOC in the wild uses `page` and is subtly wrong.
+- **`role="list"` is set explicitly on the `<ol>`, and it is not redundant** — `list-style: none` strips list semantics in Safari/VoiceOver, so an unstyled list silently stops being announced as a list. The source calls this out. This is a real bug that most kits ship.
+- **The marker is `aria-hidden`** — it is chrome, and the `aria-current` carries the meaning.
+- Links are ordinary tab stops with no roving tabindex, which is correct: a TOC is navigation, not a composite widget.
+- **Button mode uses real buttons.** Rows are `<button type="button">`, so Enter and Space activate them and a TOC inside a `<form>` never submits it. They keep the same `<nav>`, list and `aria-current="location"`. A button is the honest element there: with no `href` the row does not navigate, it runs the caller's code.
+
+Gaps:
+
+- **The active change is not announced.** As the reader scrolls, `aria-current` moves silently. That is arguably right (announcing on every scroll would be intolerable), but it means a screen-reader user reading the body has no signal from the TOC at all — they would have to navigate back to it.
+- **`@level` indents but carries no semantics.** A level-3 item is visually nested under a level-2 one and is announced as a sibling. `aria-level` on the list items, or real nesting, would convey the document's structure.
+- **The link targets must actually exist.** `href="#id"` pointing at a missing element silently does nothing, and nothing validates it.
+- **Fragment navigation moves focus** to the target element only if it is focusable or has `tabindex="-1"` — a plain `<h2>` receives _scroll_ but not _focus_ in several browsers, so a keyboard user clicking a TOC link may find focus still in the TOC. Adding `tabindex="-1"` to headings at the call site is the fix. In button mode focus always stays on the button; a caller that wants it to follow should focus the section after scrolling.
+- **Target size**: rows are small text; block padding of `--boxel-sp-3xs` plus the inherited line-height should land near WCAG **2.5.8**'s 24px minimum, but this is derived from the CSS, not measured, and a tighter inherited line-height would fall below it.
+
+## Theming
+
+`--muted-foreground` (resting links), `--foreground` (active link), `--hover` (row hover fill), `--primary-ink` (the marker bar), `--border` (the rail), `--ring` (focus outline), `--boxel-font-size-xs`, `--boxel-sp-*` and `--boxel-border-radius-sm` (row type, padding, gap and radius), and `--_level` (the per-item indent step, set inline from `@level`). The rail, marker and indent sit on the inline-start side, so they move to the right under a right-to-left writing direction. The hover fill applies only on a device with a hovering pointer, so a tapped row on a touch screen does not keep it.
+
+Because the marker is absolutely positioned and measured, a theme that changes link line-height or padding gets a correctly-resized marker for free — the `ResizeObserver` handles reflow. A theme that hides the marker entirely, however, leaves `aria-current` as the only active signal and ink weight as the only visual one; keep at least one strong visual channel.
+
+The rail gap and the per-level indent are caller knobs, `--pretui-toc-rail-gap` and `--pretui-toc-indent`, defaulting to `--boxel-sp-sm`. Rows take `--boxel-sp-3xs` block padding, which keeps a row near the WCAG 2.5.8 24px target at the inherited line-height (computed from the CSS, not measured).
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.