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

package/bundled-realms/pretui/components/toggle-matrix.md

@@ -0,0 +1,44 @@
+## What it is
+
+A grid of switches: rows against columns, with every intersection independently on or off. The permissions matrix — roles against capabilities, people against projects.
+
+## The contract
+
+```
+@rows, @columns (required)
+@label (required)  — the grid's accessible name
+@value?, @defaultValue? — every switched-on intersection
+@onValueChange?    — fires with the whole next value, always in rows × columns order
+@onToggle?         — fires once per cell that ACTUALLY changed, including inside a
+                     bulk or span operation
+@rowAxisLabel?     — name for the header of the row axis, e.g. 'Role'
+@bulk?             — show the row / column / whole-matrix select-all checkboxes. Default true
+```
+
+**Two callbacks, two consumers.** `@onValueChange` hands you the whole next state, in a stable order, for storing. `@onToggle` fires once per cell that actually changed — including inside a bulk operation — so an **audit log gets individual grants rather than a diff**. That distinction is the reason both exist.
+
+**`@label` is required**, for the same reason **ToggleGroup**'s is: a matrix of unnamed checkboxes is the worst case of the unnamed-group problem, because there are now two axes to be lost on.
+
+**Bulk operations are per row, per column and whole-matrix.** A permissions grid without them is unusable at any real size.
+
+## Prior art
+
+A kit addition. The comparison is against the hand-rolled permissions table every product grows, and the two things those get wrong: no bulk selection, and a change event that reports the new state rather than the individual grants — which makes an audit trail impossible to reconstruct.
+
+Where it is thinner: no tri-state or inherited-permission model, no row or column grouping, no virtualisation for a large matrix, and no per-cell disabled state — the grid is uniform.
+
+## Accessibility
+
+- **The grid is named, and both axes are labelled.** `@rowAxisLabel` names the row header column, which is the thing that is usually blank and leaves a reader unable to tell what the rows *are*.
+- **A cell's meaning is the intersection of two headers**, which is why the axis labels matter more here than in a normal table — announcing "on" tells a reader nothing without both.
+- **Bulk checkboxes are real controls**, so select-all-in-row is reachable rather than being a pointer-only convenience.
+- **`@onToggle` firing per changed cell inside a bulk operation** means a caller can announce "4 permissions granted" accurately, rather than guessing from a diff.
+- **The column rule aid is visual only.** A heavier rule every Nth column helps scanning and conveys nothing, which is correct.
+
+## Theming
+
+The matrix uses the kit's shared control and border tokens rather than a component-specific surface; the scanning rule is a border-weight change on the shared border token.
+
+That sharing is what keeps a permissions grid looking like a table in the same product rather than like a spreadsheet embedded in it.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/toggle-matrix.usage.gts

@@ -0,0 +1,243 @@
+// Pretui — ToggleMatrix usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import type { PretuiSize, PretuiTone } from '../pretui-primitives';
+import { FreestyleUsage } from './freestyle-usage';
+import { ToggleMatrix } from './toggle-matrix';
+import type { ToggleCell, ToggleMatrixColumn, ToggleMatrixRow } from './toggle-matrix';
+import { SIZES, TONES } from '../internal/toggle-controls-fixtures';
+
+// ── ToggleMatrix ← beat-maker step grid ──────────────────────────────────
+const ROLES: ToggleMatrixRow[] = [
+  { id: 'owner', label: 'Owner', hint: 'Billing and deletion' },
+  { id: 'admin', label: 'Admin', hint: 'Manages the workspace' },
+  { id: 'editor', label: 'Editor', hint: 'Writes and publishes' },
+  { id: 'author', label: 'Author', hint: 'Writes drafts only' },
+  { id: 'viewer', label: 'Viewer', hint: 'Read-only' },
+  { id: 'guest', label: 'Guest', hint: 'Invited to one item', disabled: true },
+];
+
+const PERMISSIONS: ToggleMatrixColumn[] = [
+  { id: 'view', label: 'View' },
+  { id: 'comment', label: 'Comment' },
+  { id: 'edit', label: 'Edit' },
+  { id: 'publish', label: 'Publish' },
+  { id: 'share', label: 'Share' },
+  { id: 'invite', label: 'Invite' },
+  { id: 'billing', label: 'Billing' },
+  { id: 'delete', label: 'Delete' },
+];
+
+const GRANTS: ToggleCell[] = [
+  { row: 'owner', column: 'view' },
+  { row: 'owner', column: 'comment' },
+  { row: 'owner', column: 'edit' },
+  { row: 'owner', column: 'publish' },
+  { row: 'owner', column: 'share' },
+  { row: 'owner', column: 'invite' },
+  { row: 'owner', column: 'billing' },
+  { row: 'owner', column: 'delete' },
+  { row: 'admin', column: 'view' },
+  { row: 'admin', column: 'comment' },
+  { row: 'admin', column: 'edit' },
+  { row: 'admin', column: 'publish' },
+  { row: 'admin', column: 'share' },
+  { row: 'admin', column: 'invite' },
+  { row: 'editor', column: 'view' },
+  { row: 'editor', column: 'comment' },
+  { row: 'editor', column: 'edit' },
+  { row: 'editor', column: 'publish' },
+  { row: 'author', column: 'view' },
+  { row: 'author', column: 'comment' },
+  { row: 'author', column: 'edit' },
+  { row: 'viewer', column: 'view' },
+];
+
+class ToggleMatrixUsage extends Component {
+  tones = TONES;
+  sizes = SIZES;
+  rows = ROLES;
+  columns = PERMISSIONS;
+
+  @tracked grants: ToggleCell[] = GRANTS;
+  @tracked bulk = true;
+  @tracked groupEvery = 4;
+  @tracked activeColumn = 'publish';
+  @tracked rowAxisLabel = 'Role';
+  @tracked tone = 'primary';
+  @tracked sizeName = 'm';
+  @tracked lastChange = 'nothing yet';
+
+  setGrants = (v: ToggleCell[]) => (this.grants = v);
+  setBulk = (v: boolean) => (this.bulk = v);
+  setGroupEvery = (v: number | null) => (this.groupEvery = v ?? 0);
+  setActiveColumn = (v: string) => (this.activeColumn = v);
+  setRowAxisLabel = (v: string) => (this.rowAxisLabel = v);
+  setTone = (v: string) => (this.tone = v);
+  setSize = (v: string) => (this.sizeName = v);
+  noteChange = (row: string, column: string, live: boolean) => {
+    this.lastChange = `${row} · ${column} → ${live ? 'granted' : 'revoked'}`;
+  };
+
+  get columnIds() {
+    return ['', ...this.columns.map((column) => column.id)];
+  }
+  get toneVal() {
+    return this.tone as PretuiTone;
+  }
+  get sizeVal() {
+    return this.sizeName as PretuiSize;
+  }
+  get grantCount() {
+    return this.grants.length;
+  }
+  get usage() {
+    let bits = [
+      "@label='Role permissions'",
+      '@rows={{this.roles}}',
+      '@columns={{this.permissions}}',
+      '@value={{this.grants}}',
+      '@onValueChange={{this.setGrants}}',
+    ];
+    if (this.groupEvery) bits.push(`@groupEvery={{${this.groupEvery}}}`);
+    return `<ToggleMatrix ${bits.join(' ')} />`;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='ToggleMatrix'
+      @description="A two-dimensional grid of toggles with real header semantics: a table with role='grid', scoped row and column headers, select-all boxes carrying a true indeterminate state, and two-axis keyboard navigation over one tab stop — arrows in both directions, Home and End along the row, Ctrl+Home and Ctrl+End to the corners. Shift-activate paints the rectangle from the anchor, and Shift+Arrow does exactly the same thing from the keyboard, which is why drag-to-paint was not built. The mechanism comes from the beat-maker step grid with the music thrown away; the unnamed colour-only pads did not survive the trip."
+      @source={{this.usage}}
+    >
+      <:example>
+        <ToggleMatrix
+          @rows={{this.rows}}
+          @columns={{this.columns}}
+          @label='Role permissions'
+          @value={{this.grants}}
+          @onValueChange={{this.setGrants}}
+          @onToggle={{this.noteChange}}
+          @rowAxisLabel={{this.rowAxisLabel}}
+          @bulk={{this.bulk}}
+          @groupEvery={{this.groupEvery}}
+          @activeColumn={{this.activeColumn}}
+          @tone={{this.toneVal}}
+          @size={{this.sizeVal}}
+        />
+        <p class='pretui-demo-readout' data-test-tm-readout>
+          {{this.grantCount}} grants · last change:
+          {{this.lastChange}}
+        </p>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='rows'
+          @description='Row descriptors: id, label, an optional hint line and an optional disabled flag. Data-driven, unlike the source, whose rows were a literal array of drum names.'
+          @value={{this.rows}}
+        />
+        <Args.Object
+          @name='columns'
+          @description='Column descriptors: id, label, an optional abbr drawn when the full label will not fit (assistive tech still hears the full one), and an optional disabled flag.'
+          @value={{this.columns}}
+        />
+        <Args.String
+          @name='label'
+          @required={{true}}
+          @defaultValue='Role permissions'
+          @description='The grid name. Required for the same reason as ToggleGroup label.'
+        />
+        <Args.Object
+          @name='value'
+          @description='Controlled value: every switched-on intersection, as row and column ids. An array of pairs rather than interpolated string keys, which cannot survive an id containing the separator.'
+          @value={{this.grants}}
+        />
+        <Args.Action
+          @name='onValueChange'
+          @description='Receives the whole next value, always rebuilt in rows-by-columns order — so two identical selections serialize identically no matter how they were reached.'
+        />
+        <Args.Action
+          @name='onToggle'
+          @description='Fires once per cell that actually changed, including inside a bulk or span operation, so an audit log records individual grants rather than a diff.'
+        />
+        <Args.Bool
+          @name='bulk'
+          @defaultValue={{true}}
+          @value={{this.bulk}}
+          @description='Show the row, column and whole-matrix select-all boxes. They live in row and column minus-one of the same navigation space, so they are reachable by arrowing rather than by Tab, and they are aria-disabled rather than disabled so a tab stop can never land somewhere unfocusable.'
+          @onInput={{this.setBulk}}
+        />
+        <Args.Number
+          @name='groupEvery'
+          @defaultValue={{0}}
+          @value={{this.groupEvery}}
+          @min={{0}}
+          @max={{8}}
+          @description='Draw a heavier rule before every Nth column — the scanning aid the source hardcoded as three separate equality comparisons.'
+          @onInput={{this.setGroupEvery}}
+        />
+        <Args.String
+          @name='activeColumn'
+          @value={{this.activeColumn}}
+          @options={{this.columnIds}}
+          @description='Marks one column as current — a playhead, today, the live shift. Carried by aria-current and a drawn caret, never by colour alone.'
+          @onInput={{this.setActiveColumn}}
+        />
+        <Args.String
+          @name='rowAxisLabel'
+          @value={{this.rowAxisLabel}}
+          @description='Names the row axis in the corner cell, e.g. Role or Shift.'
+          @onInput={{this.setRowAxisLabel}}
+        />
+        <Args.String
+          @name='tone'
+          @defaultValue='primary'
+          @value={{this.tone}}
+          @options={{this.tones}}
+          @description='Semantic hue for switched-on cells and the current-column caret.'
+          @onInput={{this.setTone}}
+        />
+        <Args.String
+          @name='size'
+          @defaultValue='m'
+          @value={{this.sizeName}}
+          @options={{this.sizes}}
+          @description='Scale for the whole grid. Cells are em, so one declaration moves everything.'
+          @onInput={{this.setSize}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @defaultValue={{false}}
+          @description='Dims and inerts the whole grid.'
+        />
+        <Args.Yield
+          @name='empty'
+          @description='Replaces the built-in line shown when there are no rows or no columns.'
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-togglematrix-cell'
+          @type='length'
+          @description='Cell size, in em so it rides the size scale. Grows to a 44px-class target on coarse pointers.'
+        />
+        <Css.Basic
+          @name='pretui-togglematrix-radius'
+          @type='length'
+          @description='Corner radius of one cell.'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-demo-readout {
+        margin: 12px 0 0;
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_TOGGLE_MATRIX: Record<string, unknown> = {
+  ToggleMatrix: ToggleMatrixUsage,
+};

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

@@ -0,0 +1,235 @@
+// Pretui — Toggle: one button whose meaning is state.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { hash } from '@ember/helper';
+import { on } from '@ember/modifier';
+import { Button } from './button';
+import { PRETUI_TONES, emit, firstDefined, resolveSize, resolveTone } from '../pretui-primitives';
+import type {
+  PretuiAppearance,
+  PretuiSize,
+  PretuiSizeArg,
+  PretuiToneArg,
+  PretuiTone,
+} from '../pretui-primitives';
+
+// ═════════════════════════════════════════════════════════════════════════
+// Toggle
+// ═════════════════════════════════════════════════════════════════════════
+
+/** Which ARIA attribute carries the pressed state.
+ *
+ * `pressed` is a standalone toggle button and a multi-select toolbar member.
+ * `checked` is what a single-select group needs, where the member also wears
+ * `role='radio'` — the same swap Radix's ToggleGroup performs by deleting
+ * `aria-pressed` from the item's props. `none` hands the state to a parent
+ * that owns the ARIA itself. */
+export type ToggleAriaState = 'pressed' | 'checked' | 'none';
+
+export interface ToggleSignature {
+  Args: {
+    /** CONTROLLED pressed state. Omit to let the component own it. */
+    pressed?: boolean;
+    /** uncontrolled seed; ignored once `@pressed` is supplied */
+    defaultPressed?: boolean;
+    /** fires with the NEXT state on every activation */
+    onPressedChange?: (pressed: boolean) => void;
+    /** which ARIA attribute carries the state. `pressed` (default) is a
+     * standalone toggle or a toolbar member; `checked` is what a single-select
+     * `ToggleGroup` member needs beside its `role='radio'`; `none` hands the
+     * state to a parent that writes the ARIA itself. */
+    ariaState?: ToggleAriaState;
+    /** alias — the Radix/shadcn spelling is already the house name here, so
+     * this is the HTML-shaped notify for an agent that reaches for it */
+    onChange?: (pressed: boolean) => void;
+    /** accessible name. Required in `@iconOnly` mode, where there is no text
+     * for a reader to fall back on. */
+    label?: string;
+    /** draw the glyph only; `@label` becomes the sr-only name and the title */
+    iconOnly?: boolean;
+    /** Hue, default `neutral`. Accepts `destructive`/`brand`/… */
+    tone?: PretuiToneArg;
+    /** recipe worn at rest, default `outlined` */
+    appearance?: PretuiAppearance;
+    /** recipe worn while pressed, default `accent`. The pressed state is an
+     * APPEARANCE SWAP rather than a tint, so it survives greyscale (Law 6). */
+    pressedAppearance?: PretuiAppearance;
+    /** Scale, default `m`. Accepts `sm`/`md`/`lg`/`default`. */
+    size?: PretuiSizeArg;
+    /** dims and inerts, but stays focusable and announced (`aria-disabled`) */
+    disabled?: boolean;
+    /** alias — React Aria / Base UI spelling of `@disabled` */
+    isDisabled?: boolean;
+    /** pending: `aria-busy`, a spinner, clicks ignored, FOCUS RETAINED */
+    busy?: boolean;
+    /** aliases — the spellings the React corpus emits for `@busy` */
+    loading?: boolean;
+    isPending?: boolean;
+  };
+  Blocks: {
+    /** yields the resolved state, so a caller can swap the glyph in place
+     * rather than render two of them and hide one */
+    default: [{ pressed: boolean }];
+  };
+  Element: HTMLButtonElement;
+}
+
+/**
+ * A single button whose meaning is a state rather than an action.
+ *
+ * **From:** Radix `Toggle` (`packages/react/toggle/src/toggle.tsx`), whose
+ * whole body is `aria-pressed`, `data-state`, and a controllable boolean.
+ *
+ * **Better than the inspiration.** Radix's Toggle passes `disabled` straight
+ * to the button element, which removes it from the tab order — fine for one
+ * button on a page, wrong the moment a toolbar with roving tabindex holds it,
+ * because the group changes shape between visits and can never be learned.
+ * This one is always `aria-disabled`, which is the kit's law and the reason
+ * `ToggleGroup` could adopt it unchanged. Radix also has no visual opinion at
+ * all, so every consumer re-derives "what does pressed look like" and almost
+ * every one of them reaches for a tint — colour-only signalling. Here pressed
+ * is an appearance recipe swap over the tone channel, so it reads
+ * in grayscale AND re-tints with a theme it has never seen. Radix has no
+ * pending state; `@busy` here is React Aria's *pending* semantics (`aria-busy`
+ * + retained focus) rather than a disable. And Radix's `data-state` is the
+ * only thing it exposes to CSS; this reflects the whole resolved treatment as
+ * `data-tone` / `data-appearance` / `data-size` / `data-state` so a consumer
+ * styles states in CSS instead of through args.
+ */
+export class Toggle extends Component<ToggleSignature> {
+  @tracked private internal: boolean = this.args.defaultPressed ?? false;
+
+  get pressed(): boolean {
+    return this.args.pressed ?? this.internal;
+  }
+  get inert(): boolean {
+    return firstDefined(this.args.disabled, this.args.isDisabled) ?? false;
+  }
+  get busy(): boolean {
+    return (
+      firstDefined(this.args.busy, this.args.loading, this.args.isPending) ??
+      false
+    );
+  }
+  get tone(): PretuiTone {
+    return resolveTone(this.args.tone, PRETUI_TONES, 'neutral');
+  }
+  get size(): PretuiSize {
+    return resolveSize(this.args.size);
+  }
+  /** The recipe actually worn right now — the whole visual contract of the
+   * component is this one line. */
+  get appearance(): PretuiAppearance {
+    return this.pressed
+      ? (this.args.pressedAppearance ?? 'accent')
+      : (this.args.appearance ?? 'outlined');
+  }
+  get ariaState(): ToggleAriaState {
+    return this.args.ariaState ?? 'pressed';
+  }
+  get pressedAttr(): string | undefined {
+    return this.ariaState === 'pressed' ? String(this.pressed) : undefined;
+  }
+  get checkedAttr(): string | undefined {
+    return this.ariaState === 'checked' ? String(this.pressed) : undefined;
+  }
+  /** Busy wins the state slot so `Button`'s own busy rules still apply; the
+   * pressed state is still legible because it lives in the appearance. */
+  get stateAttr(): string {
+    if (this.busy) {
+      return 'busy';
+    }
+    return this.pressed ? 'on' : 'off';
+  }
+
+  activate = () => {
+    if (this.inert || this.busy) {
+      return;
+    }
+    let next = !this.pressed;
+    if (this.args.pressed === undefined) {
+      this.internal = next;
+    }
+    emit([this.args.onPressedChange, this.args.onChange], next);
+  };
+
+  <template>
+    <Button
+      class='pretui-toggle'
+      @tone={{this.tone}}
+      @appearance={{this.appearance}}
+      @size={{this.size}}
+      aria-pressed={{this.pressedAttr}}
+      aria-checked={{this.checkedAttr}}
+      aria-disabled={{if this.inert 'true'}}
+      aria-busy={{if this.busy 'true'}}
+      aria-label={{if @iconOnly @label}}
+      title={{if @iconOnly @label}}
+      data-state={{this.stateAttr}}
+      data-pressed={{if this.pressed 'true' 'false'}}
+      data-test-pretui-toggle
+      ...attributes
+      {{on 'click' this.activate}}
+    >
+      {{#if this.busy}}
+        <span class='pretui-toggle-spin' aria-hidden='true'></span>
+      {{/if}}
+      <span class='pretui-toggle-face'>
+        {{yield (hash pressed=this.pressed)}}
+      </span>
+    </Button>
+    <style scoped>
+      /* above Button's layer, so these win by layer order, not file order */
+      @layer PretComponent, PretComposite;
+      @layer PretComposite {
+        /* Everything visual arrives through Button's own token channel and its
+           appearance recipes, so this file paints nothing a theme cannot
+           retune. What is left is the press feedback and the pending ring. */
+        .pretui-toggle {
+          flex: none;
+        }
+        .pretui-toggle:active:not([aria-disabled='true']) {
+          transform: scale(0.96);
+        }
+        .pretui-toggle[aria-disabled='true'] {
+          opacity: 0.45;
+          cursor: default;
+        }
+        .pretui-toggle[aria-busy='true'] {
+          cursor: progress;
+        }
+        .pretui-toggle-face {
+          display: inline-flex;
+          align-items: center;
+          gap: 0.4em;
+          min-width: 0;
+        }
+        @keyframes pretui-toggle-spin {
+          to {
+            transform: rotate(360deg);
+          }
+        }
+        .pretui-toggle-spin {
+          flex: none;
+          width: 1.04em;
+          height: 1.04em;
+          border-radius: 50%;
+          border: 1.5px solid color-mix(in oklch, currentColor 25%, transparent);
+          border-top-color: currentColor;
+          animation: pretui-toggle-spin 0.7s linear infinite;
+        }
+        /* The end state has to still READ as pending, so the ring stops at an
+           angle that is obviously not a closed circle rather than at rest. */
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-toggle-spin {
+            animation: none;
+            transform: rotate(135deg);
+          }
+          .pretui-toggle:active:not([aria-disabled='true']) {
+            transform: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,59 @@
+## What it is
+
+One button whose meaning is a **state**, not an action: pressed or unpressed.
+
+It is deliberately neither of its neighbours. It is not a **Switch** — a setting that takes effect the moment it moves — and not a **Button**, which does a thing and returns to rest. Bold in a formatting bar is a Toggle. "Dark mode" is a Switch. "Save" is a Button.
+
+## The contract
+
+```
+@pressed?, @defaultPressed?, @onPressedChange? — controlled / uncontrolled state
+@onChange?         — alias; the HTML-shaped notify an agent reaches for
+@ariaState?        — which ARIA attribute carries the state:
+                     'pressed' (default) | 'checked' | 'none'
+@label?            — accessible name; REQUIRED in @iconOnly mode
+@iconOnly?         — draw the glyph only; @label becomes the sr-only name and the title
+@tone?             — hue, default 'neutral'
+@appearance?       — recipe worn at rest, default 'outlined'
+@pressedAppearance? — recipe worn while pressed, default 'accent'
+@size?             — scale, default 'm'
+@disabled?, @isDisabled? — dims and inerts, but stays focusable and announced
+@busy?, @loading?, @isPending? — pending: aria-busy, a spinner, clicks ignored, FOCUS RETAINED
+
+<:default> — yields { pressed }, so a caller can swap the glyph in place
+```
+
+**The pressed state is an appearance swap, not a tint.** It changes recipe — outlined to accent — rather than shifting a colour, which is what makes it survive greyscale, a colour-blind reader, and a printout. This is the single most-copied mistake in toggle implementations.
+
+**`@ariaState` exists because the same button means different things in different parents.** Standalone or in a toolbar it is `aria-pressed`; as a single-select **ToggleGroup** member beside `role='radio'` it must be `aria-checked`; `'none'` hands the ARIA to a parent that writes it.
+
+**`@disabled` is `aria-disabled`, not the `disabled` attribute** — so the button stays focusable and announced, which is what a roving-tabindex toolbar requires. A natively disabled button vanishes from the tab order and a reader cannot discover it exists.
+
+**`@busy` keeps focus.** A pending toggle is not a disabled toggle; disabling it on activation throws focus to the document.
+
+**The block yields the resolved state** so a caller swaps the glyph in place rather than rendering two and hiding one.
+
+## Prior art
+
+**Radix/shadcn Toggle**, **React Aria's ToggleButton**, **MUI's ToggleButton**, **Tremor's Toggle**.
+
+Where Pretui is better — three fixes over the Radix port: `aria-disabled` instead of `disabled` so it survives a toolbar; the pressed state as an appearance recipe rather than a tint so it reads in greyscale; and `@busy` as a real pending state that keeps focus rather than being modelled as a disable.
+
+Where it is thinner: no indeterminate state, no long-press or hold behaviour, and no built-in tooltip for the icon-only mode — `@label` becomes the `title`, which is the browser's tooltip rather than the kit's.
+
+## Accessibility
+
+- **`aria-pressed` is the default and the right one** for a standalone toggle: it says "this control has a state" rather than "this control does a thing".
+- **`@iconOnly` requires `@label`.** There is no text for a reader to fall back on, and an unnamed icon button is the most common accessibility defect in a formatting bar.
+- **Disabled stays discoverable.** `aria-disabled` keeps the control in the tab order and in the accessibility tree, announced as unavailable rather than absent.
+- **Busy is announced as busy** through `aria-busy`, and the spinner is `aria-hidden` so it is not read as content.
+- **The state survives without colour.** The appearance swap changes border, fill and ink together, so pressed is perceivable in greyscale.
+- **`@ariaState='none'` is a promise the parent has to keep.** Using it without a parent that writes the ARIA leaves a button with no state at all.
+
+## Theming
+
+The tone, appearance and size args resolve through the kit's shared recipe system rather than through component-local tokens, which is why a Toggle sits at exactly the same weight as a **Button** of the same size and tone beside it.
+
+That shared resolution is the reason `@pressedAppearance` is an appearance name rather than a color: a theme defines what `accent` looks like once, and every pressed toggle in the product follows it — including in a theme that expresses accent through border weight rather than fill.
+
+The styles sit in `@layer PretComposite`, above Button's `PretComponent` layer, so what this component sets on Button wins by layer order. A caller's unlayered CSS overrides both without a more specific selector.