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

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

@@ -0,0 +1,112 @@
+// Pretui — Textarea: BoxelInput @type='textarea' in Pretui control dress.
+import Component from '@glimmer/component';
+import { htmlSafe } from '@ember/template';
+import { BoxelInput } from '@cardstack/boxel-ui/components';
+import { emit, firstDefined } from '../pretui-primitives';
+import type { ControlAliasArgs } from '../pretui-primitives';
+
+export interface TextareaSignature {
+  Args: ControlAliasArgs & {
+    value?: string;
+    placeholder?: string;
+    invalid?: boolean;
+    controlId?: string;
+    onInput?: (value: string) => void;
+    /** additive — see Input */
+    disabled?: boolean;
+    helperText?: string;
+    errorMessage?: string;
+    required?: boolean;
+    optional?: boolean;
+    readonly?: boolean;
+    /** aliases — see Input */
+    isInvalid?: boolean;
+    description?: string;
+  };
+  Element: HTMLTextAreaElement;
+}
+
+// Same retrofit as Input, on BoxelInput @type='textarea'. The inline style
+// carries the Pretui textarea metrics (64px min-height, 7/9 padding,
+// vertical-only resize) — boxel defines its 10rem --boxel-input-height ON
+// the textarea element itself, so the wrapper channel cannot override it;
+// the inline declaration can.
+const TEXTAREA_METRICS = htmlSafe(
+  'font: inherit; letter-spacing: inherit; --boxel-input-height: 64px; padding: 7px 9px; resize: vertical;',
+);
+
+export class Textarea extends Component<TextareaSignature> {
+  get invalid() {
+    return firstDefined(this.args.invalid, this.args.isInvalid) ?? false;
+  }
+  get disabled() {
+    return firstDefined(this.args.disabled, this.args.isDisabled);
+  }
+  get required() {
+    return firstDefined(this.args.required, this.args.isRequired);
+  }
+  get readonly() {
+    return firstDefined(
+      this.args.readonly,
+      this.args.isReadOnly,
+      this.args.readOnly,
+    );
+  }
+  get helperText() {
+    return firstDefined(this.args.helperText, this.args.description);
+  }
+  get state() {
+    return this.invalid ? 'invalid' : 'none';
+  }
+  handleInput = (value: string) => {
+    emit(
+      [this.args.onInput, this.args.onChange, this.args.onValueChange],
+      value,
+    );
+  };
+  <template>
+    <div
+      class='pretui-inputwrap pretui-textareawrap'
+      data-invalid={{if this.invalid 'true'}}
+      data-test-pretui-textarea
+    >
+      <BoxelInput
+        @id={{@controlId}}
+        @type='textarea'
+        @value={{@value}}
+        @placeholder={{@placeholder}}
+        @disabled={{this.disabled}}
+        @readonly={{this.readonly}}
+        @state={{this.state}}
+        @errorMessage={{@errorMessage}}
+        @helperText={{this.helperText}}
+        @required={{this.required}}
+        @optional={{@optional}}
+        @onInput={{this.handleInput}}
+        style={{TEXTAREA_METRICS}}
+        ...attributes
+      />
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        /* Same re-skin channel as Input — see that component's note. */
+        .pretui-inputwrap {
+          width: 100%;
+          font-size: var(--text-ui-md, 12.5px);
+          letter-spacing: var(--track-ui, 0.01em);
+          --background: var(--field, var(--boxel-light));
+          --border: var(--input);
+          --ring: var(--primary);
+          --muted-foreground: var(--ink-3, var(--boxel-400));
+          --boxel-form-control-height: var(--control-h, 28px);
+          --boxel-form-control-border-radius: var(--radius);
+          --boxel-font-size-sm: var(--text-ui-sm, 11.5px);
+          --boxel-font-size-xs: var(--text-ui-xs, 11px);
+          --boxel-sp-xs: 5px;
+          --boxel-sp-sm: 9px;
+        }
+      }
+    </style>
+  </template>
+}
+

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

@@ -0,0 +1,51 @@
+## What it is
+
+Multi-line free text. Reach for it when the value is prose — a note, a description, a comment body. If the value is one line, use **Input**; if it is markdown or rich content the user should see rendered, use **Prose** for display and a Textarea for editing; if it is structured (a query, a rule), use **ExpressionBuilder** rather than asking someone to type syntax into a box.
+
+## The contract
+
+```
+@value?, @placeholder?, @invalid?, @disabled?, @controlId?
+@onInput?(value: string)
+@helperText?, @errorMessage?, @required?, @optional?
+```
+
+Identical to **Input** minus its type arg, and that symmetry is deliberate: the two are interchangeable at a call site, so a **FormField** can swap one for the other without the surrounding code changing. `@onInput` receives the string, not the event; `@controlId` comes down from the labelling wrapper.
+
+Like Input, it is a **retrofit on boxel-ui's `BoxelInput`** in its textarea mode, re-dressed through the token channel — the wrapper `<div>` redefines `--background`, `--border`, `--ring`, `--muted-foreground` and a set of `--boxel-*` knobs and the inner control restyles itself. No Pretui CSS reaches boxel markup.
+
+The one thing worth knowing that Input does not have: **boxel-ui defines its `10rem` `--boxel-input-height` on the textarea element itself**, so the wrapper's custom-property channel cannot override it — an element-local definition beats an inherited one. The fix is a single inline `style` carrying the Pretui metrics: `--boxel-input-height: 64px`, `padding: 7px 9px`, `resize: vertical`. This is the concrete case that proves the channel's limit, and it is the reason the escape hatch exists at all.
+
+`resize: vertical` is a decision, not a default. Horizontal resize breaks every grid layout it sits in; vertical does not.
+
+## Prior art
+
+**Web Awesome `wa-textarea`** carries `rows` (default 4), `resize` (`none|vertical|horizontal|both|auto`, where `auto` uses a width-only ResizeObserver), `with-count`, plus label/hint props _and_ slots. **React Spectrum `TextArea`** is `TextField` with a different element and inherits the whole `description`/`errorMessage`/`isInvalid` surface. **shadcn** is a styled `<textarea>`.
+
+Pretui is smaller than Web Awesome on purpose — no `rows`, no auto-grow, no character counter — and the gap is honest rather than clever. Height is a fixed 64px minimum plus user resize.
+
+The one detail worth stealing back: **`wa-textarea`'s character counter is `aria-hidden` and paired with a separate visually-hidden `aria-live="polite"` region debounced by a full second**, so the count is available to screen readers without narrating every keystroke. If Pretui adds `with-count`, that is the shape to copy.
+
+Where Pretui is better than shadcn and comparable to Spectrum: the invalid dress travels through the token channel (`Field` sets `data-invalid`, which repoints `--border` and `--background` on the wrapper), so there is no `.error` class threaded through layers and a theme can redefine what invalid looks like in one place.
+
+## Accessibility
+
+Native `<textarea>`; no APG pattern. `aria-invalid`, `aria-errormessage` and `aria-describedby` wiring comes from BoxelInput, as with Input.
+
+Gaps, plainly:
+
+- **`@invalid` and `@errorMessage` are independent args.** `@invalid` alone gives a red control that announces nothing; `@errorMessage` alone renders nothing, because the error row is gated on validation state. Pass both, or use **FormField**.
+- **No accessible name of its own.** Outside `Field`/`FormField`, and without an explicit `aria-label`, the control is unnamed. A placeholder is not a label (and in a textarea it disappears the instant a character is typed, so it is worse here than on Input).
+- No `rows` arg means the initial height cannot express expected length — a one-sentence field and a five-paragraph field look identical, which is a WCAG 3.3.2 _instructions_ smell even though it is not a failure.
+- `@disabled` is the native attribute: out of the tab order, value not submitted. Use `readonly` via `...attributes` if you need focusable-but-fixed.
+- `resize: vertical` is good for 1.4.4/1.4.10 reflow; verify the focus ring (`--ring`, default `--primary`) against 2.4.11 in dark mode.
+
+## Theming
+
+`--field` (control face), `--input` (hairline), `--primary` (focus ring via `--ring`), `--ink-3` (placeholder ink, injected as a locally narrowed `--muted-foreground`), `--control-h`, `--radius`, `--text-ui-md`, `--text-ui-sm`, `--text-ui-xs`, `--track-ui`.
+
+Forwarded into boxel-ui: `--boxel-form-control-height`, `--boxel-form-control-border-radius`, `--boxel-font-size-sm`, `--boxel-font-size-xs`, `--boxel-sp-xs`, `--boxel-sp-sm`, and — inline only — `--boxel-input-height`.
+
+Note the asymmetry with Input: because the metrics ride an inline `style`, a theme **cannot** retune textarea height or padding through tokens. That is the accepted cost of the boxel-ui retrofit and the one place a theme will find itself blocked.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,100 @@
+// Pretui — Textarea usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Textarea } from './textarea';
+import { Field } from './field';
+
+// ── Textarea ← input/usage.gts (textarea type) ───────────────────────────
+// Same BoxelInput retrofit as Input, pinned to @type='textarea' with the
+// Pretui textarea metrics (64px min-height, vertical-only resize).
+export class TextareaUsage extends Component {
+  @tracked value = '';
+  @tracked placeholder = 'Tell us more…';
+  @tracked invalid = false;
+  @tracked disabled = false;
+  @tracked helperText = '';
+  @tracked errorMessage = 'This value is invalid.';
+  setValue = (v: string) => (this.value = v);
+  setPlaceholder = (v: string) => (this.placeholder = v);
+  setInvalid = (v: boolean) => (this.invalid = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  setHelperText = (v: string) => (this.helperText = v);
+  setErrorMessage = (v: string) => (this.errorMessage = v);
+  get usage() {
+    let bits = [`@value='${this.value}'`];
+    if (this.placeholder) bits.push(`@placeholder='${this.placeholder}'`);
+    if (this.invalid) bits.push('@invalid={{true}}');
+    bits.push('@onInput={{this.setValue}}');
+    return `<Textarea ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Textarea'
+      @description='Multi-line text entry riding boxel-ui BoxelInput (@type=textarea) — validation states and error/helper rows in the Pretui control dress; vertical-only resize.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <Field @label='Notes' as |controlId|>
+          <Textarea
+            @controlId={{controlId}}
+            @value={{this.value}}
+            @placeholder={{this.placeholder}}
+            @invalid={{this.invalid}}
+            @disabled={{this.disabled}}
+            @helperText={{this.helperText}}
+            @errorMessage={{this.errorMessage}}
+            @onInput={{this.setValue}}
+          />
+        </Field>
+      </:example>
+      <:api as |Args|>
+        <Args.Base
+          @name='controlId'
+          @description="The textarea's id for label wiring — supplied by the wrapping Field's yielded controlId."
+        />
+        <Args.String
+          @name='value'
+          @value={{this.value}}
+          @onInput={{this.setValue}}
+        />
+        <Args.String
+          @name='placeholder'
+          @value={{this.placeholder}}
+          @onInput={{this.setPlaceholder}}
+        />
+        <Args.Bool
+          @name='invalid'
+          @value={{this.invalid}}
+          @description='Paints the destructive ring and enables the errorMessage row.'
+          @onInput={{this.setInvalid}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @value={{this.disabled}}
+          @onInput={{this.setDisabled}}
+        />
+        <Args.String
+          @name='errorMessage'
+          @value={{this.errorMessage}}
+          @description='Error row under the control; renders only while @invalid.'
+          @onInput={{this.setErrorMessage}}
+        />
+        <Args.String
+          @name='helperText'
+          @value={{this.helperText}}
+          @description='Helper row under the control.'
+          @onInput={{this.setHelperText}}
+        />
+        <Args.Action
+          @name='onInput'
+          @description='Receives the changed value as a string'
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_TEXTAREA: Record<string, unknown> = {
+  Textarea: TextareaUsage,
+};

package/bundled-realms/pretui/components/theme-frame.gts

@@ -0,0 +1,272 @@
+// Pretui — ThemeFrame: per-page theme controls (upper-left).
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { guidFor } from '@ember/object/internals';
+import { Switch } from '@cardstack/boxel-ui/components';
+import { themeScope, themeScopedCss } from '@cardstack/boxel-ui/helpers';
+import Moon from '@cardstack/boxel-icons/moon';
+import Sun from '@cardstack/boxel-icons/sun';
+import { realmURL } from '@cardstack/base/card-api';
+import { Select } from './select';
+
+// Wraps a page in a theme island with a dark mode switch, built the
+// way the monorepo's own theme cards preview themselves (see
+// base/default-templates/theme-dashboard.gts). No custom theming code: the
+// outer div stamps data-theme, which theme.css translates into the
+// inherited --boxel-color-scheme signal; inside it, boxel-ui's `themeScope`
+// and `themeScopedCss` helpers re-declare the theme's variables under a
+// content-hashed scope, and their `.dark` block follows the signal through
+// the style container query those helpers emit.
+//
+// The re-scoping must sit INSIDE the data-theme wrapper. Boxel already
+// applied this card's theme at the card boundary above, but that scope
+// resolves against the app chrome's scheme, not this toggle — so the island
+// needs its own copy to flip. That is the same reasoning the ThemeDashboard
+// comment gives.
+//
+// It deliberately does NOT wrap in a nested CardContainer: that re-applies
+// a whole card box (background, radius, overflow, the --boxel-* derivation
+// and the element reset) which the frame then has to undo. The scoping
+// helpers are the part that was actually wanted.
+//
+// Components never branch on dark — the flip is entirely token
+// re-resolution.
+
+interface ThemeLike {
+  id?: string;
+  [realmURL]?: URL;
+  cssVariables?: string | null;
+  // `cardTitle`, not `title` — CardDef exposes no `title`, so reading `.title`
+  // silently yields undefined and every theme labels itself "Untitled theme".
+  cardTitle?: string;
+}
+
+export interface ThemeFrameSignature {
+  Args: {
+    // the Theme card linked from the page card's cardInfo (model.cardTheme)
+    theme?: ThemeLike | null;
+    // pass @context to enable the theme selector: the frame queries the
+    // realm for every Theme instance so each one can be previewed
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    context?: any;
+    // false hides the frame's own bar — for pages that place the yielded
+    // controls in their own header instead
+    bar?: boolean;
+  };
+  // yields the controls (dark mode switch, and the theme select when the
+  // realm has more than one theme) for pages that seat them in a header
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  Blocks: { default: [any] };
+  Element: HTMLDivElement;
+}
+
+// The same switch the base ThemeDashboard's ModeToggle renders, so a theme
+// previews light and dark the way it does everywhere else in Boxel.
+interface ThemeControlsSignature {
+  Args: { frame: ThemeFrame };
+  Element: HTMLSpanElement;
+}
+
+const ThemeControls: TemplateOnlyComponent<ThemeControlsSignature> = <template>
+  <span
+    class='pretui-theme-controls'
+    role='group'
+    aria-label='Theme preview'
+    data-test-pretui-theme-bar
+    ...attributes
+  >
+    <Switch
+      @isEnabled={{@frame.isDarkMode}}
+      @onChange={{@frame.toggleDarkMode}}
+      @size='touch'
+      @checkedIcon={{Moon}}
+      @uncheckedIcon={{Sun}}
+      @label='Dark mode'
+      data-test-pretui-theme-mode
+    />
+    {{#if @frame.showThemeSelect}}
+      <span class='pretui-theme-pick' data-test-pretui-theme-pick>
+        <Select
+          @options={{@frame.themeOptions}}
+          @value={{@frame.activeThemeId}}
+          @onValueChange={{@frame.pickTheme}}
+          @label='Theme'
+        />
+      </span>
+    {{else if @frame.activeTheme}}
+      <span
+        class='pretui-theme-name'
+        data-test-pretui-theme-name
+      >{{@frame.themeName}}</span>
+    {{/if}}
+  </span>
+  <style scoped>
+    @layer PretComponent {
+      .pretui-theme-controls {
+        --pretui-theme-pick-min-w: 11.25rem;
+
+        display: inline-flex;
+        align-items: center;
+        gap: var(--boxel-sp-xs);
+      }
+      .pretui-theme-pick {
+        min-width: var(--pretui-theme-pick-min-w);
+      }
+      .pretui-theme-name {
+        font-size: var(--boxel-font-size-xs);
+        color: var(--muted-foreground);
+        white-space: nowrap;
+      }
+    }
+  </style>
+</template>;
+
+export class ThemeFrame extends Component<ThemeFrameSignature> {
+  // Starts light, like ThemeDashboard: the Boxel chrome around the island
+  // has fixed colors, so the switch previews dark rather than following the OS.
+  @tracked isDarkMode = false;
+  @tracked selectedThemeId: string | undefined;
+  // a toggle, not a setter: the Switch in the CLI test harness passes its
+  // click event to @onChange, not a boolean
+  toggleDarkMode = () => (this.isDarkMode = !this.isDarkMode);
+  pickTheme = (v: string) => (this.selectedThemeId = v);
+
+  // All Theme instances in the linked theme's realm. Absent context
+  // (prerender, tests) degrades to the linked theme only.
+  themesResource = this.args.context?.getCards?.(
+    this,
+    () => ({
+      filter: {
+        // Themes must be queried on the ref they actually adopt from. The realm
+        // search API does not resolve re-export aliases, so `base/theme`/`default`
+        // (which re-exports this very class) matches zero cards rather than
+        // erroring — the selector then silently falls back to one theme forever.
+        type: { module: '@cardstack/base/card-api', name: 'Theme' },
+      },
+    }),
+    () => {
+      // the theme id may be prefix-form, which is not a URL base, so the
+      // realm comes from the theme card itself
+      let realm = this.args.theme?.[realmURL];
+      return realm ? [realm.href] : undefined;
+    },
+  );
+
+  get availableThemes(): ThemeLike[] {
+    let found = (this.themesResource?.instances ?? []) as ThemeLike[];
+    if (found.length > 0) {
+      return found;
+    }
+    return this.args.theme ? [this.args.theme] : [];
+  }
+  get activeTheme(): ThemeLike | undefined {
+    if (this.selectedThemeId) {
+      let picked = this.availableThemes.find(
+        (t) => t.id === this.selectedThemeId,
+      );
+      if (picked) {
+        return picked;
+      }
+    }
+    return this.args.theme ?? undefined;
+  }
+  get themeOptions() {
+    return this.availableThemes.map((t) => ({
+      value: t.id ?? '',
+      label: t.cardTitle ?? 'Untitled theme',
+    }));
+  }
+  get showThemeSelect() {
+    return this.themeOptions.length > 1;
+  }
+  get activeThemeId() {
+    return this.activeTheme?.id;
+  }
+
+  get dataTheme() {
+    return this.isDarkMode ? 'dark' : 'light';
+  }
+  get themeCss() {
+    return this.activeTheme?.cssVariables ?? undefined;
+  }
+  // boxel-ui's own scope helper: theme id plus a content hash of the CSS.
+  // The hash matters because the emitted rules are page-global — two cached
+  // renders sharing a scope but carrying different theme CSS would restyle
+  // each other. A hand-rolled `${id}-frame` string could not tell two
+  // versions of one theme apart.
+  get themeScopeId() {
+    return themeScope(this.activeThemeId, this.themeCss) ?? guidFor(this);
+  }
+  get themeName() {
+    return this.activeTheme?.cardTitle ?? 'Untitled theme';
+  }
+  get showBar() {
+    return this.args.bar ?? true;
+  }
+  <template>
+    <div
+      class='pretui-theme-frame'
+      data-theme={{this.dataTheme}}
+      data-test-pretui-theme-frame
+      ...attributes
+    >
+      {{! The theme's variables are re-scoped INSIDE the data-theme wrapper,
+          not above it: the card-level scope boxel already applied sits
+          higher up and resolves against the app chrome's scheme, not this
+          toggle. Same structure as the monorepo's ThemeDashboard. }}
+      <div
+        class='pretui-theme-surface'
+        data-boxel-theme-scope={{if this.themeCss this.themeScopeId}}
+      >
+        {{#if this.themeCss}}
+          {{! template-lint-disable require-scoped-style }}
+          <style data-boxel-theme-style>
+            {{themeScopedCss this.themeScopeId this.themeCss}}
+          </style>
+          {{! template-lint-enable require-scoped-style }}
+        {{/if}}
+        {{#if this.showBar}}
+          <div class='pretui-theme-bar'>
+            <ThemeControls @frame={{this}} />
+          </div>
+        {{/if}}
+        {{yield (component ThemeControls frame=this)}}
+      </div>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        /* a column, so the surface grows to fill the frame: a percentage
+           min-height can't, since the frame's own height isn't definite */
+        .pretui-theme-frame {
+          display: flex;
+          flex-direction: column;
+          min-height: 100%;
+        }
+        /* the scoped theme channel only carries custom properties, so the
+           frame owns the native color-scheme switch for form controls */
+        .pretui-theme-frame[data-theme='dark'] {
+          color-scheme: dark;
+        }
+        .pretui-theme-frame[data-theme='light'] {
+          color-scheme: light;
+        }
+        /* the island's tokens flip below the card's own surface, so the island
+           applies its own background, foreground and font, or the card's show
+           through */
+        .pretui-theme-surface {
+          flex: 1 0 auto;
+          background-color: var(--background);
+          color: var(--foreground);
+          font-family: var(--font-sans);
+        }
+        /* in-flow, not sticky: pages may carry their own sticky top bar */
+        .pretui-theme-bar {
+          width: fit-content;
+          margin-block-start: var(--boxel-sp-xs);
+          margin-inline-start: var(--boxel-sp-xs);
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/theme-frame.md

@@ -0,0 +1,48 @@
+## What it is
+
+The theme previewer for a documentation or catalog surface: it applies a theme to everything inside it, light or dark, and yields the controls for changing them.
+
+It is a tool, not a product control — a real application's theme setting belongs in its own settings surface. This exists so a reader can see any component under any theme in the realm, in both modes.
+
+## The contract
+
+```
+@theme?   — the Theme card linked from the page card's cardInfo
+@context? — pass it to enable the theme selector: the frame queries the realm
+            for every Theme instance, so each one can be previewed
+@bar?     — false hides the frame's own bar, for pages that place the yielded
+            controls in their own header instead
+
+<:default> — yields the controls: the dark mode switch, and the theme select
+             when the realm has more than one theme
+```
+
+**The mode switch is the one Boxel's ThemeDashboard uses**: a boxel-ui **Switch** labeled "Dark mode", with sun and moon icons. Off stamps `data-theme='light'` on the frame and on stamps `data-theme='dark'`, so the theme's light or dark variables apply through the same `--boxel-color-scheme` signal the host uses.
+
+**The frame owns the switching state**: the mode and the selected theme id live here, starting light like ThemeDashboard. The Boxel chrome around the frame has fixed colors, so the switch previews dark mode rather than following the reader's system setting. What it does not own is _persistence_ — nothing is written to storage, so a host that wants the choice to survive a reload stores it itself.
+
+**`@context` is the switch between one theme and all of them.** Without it the frame dresses its content in `@theme` and offers only the mode switch and the theme's name; with it, the frame queries the realm for every Theme instance, and when it finds more than one, a **Select** replaces the name.
+
+**`@bar={{false}}`** stops the frame drawing its own bar when the page seats the yielded controls in its own header.
+
+## Prior art
+
+The theme switcher in every component-documentation site, and Boxel's own ThemeDashboard, whose mode switch this reuses.
+
+Where it is thinner: no persistence, no per-component theme override, and no way to preview two themes side by side — the frame dresses one subtree at a time.
+
+## Accessibility
+
+- **The mode switch is a native checkbox with `role='switch'`**, named "Dark mode", so it is reachable, announced with its on/off state, and toggled with Space or Enter.
+- **The theme select is named "Theme".**
+- **Changing theme changes contrast across the whole subtree.** That is the component's purpose, and it means a catalog can be put into a theme whose tokens fail contrast — the frame applies what it is given and does not check it.
+
+## Theming
+
+The frame applies a theme rather than being themed by one — it establishes the token scope its subtree renders in, using boxel-ui's own theme helpers rather than hand-rolling the scoping.
+
+Its own controls take the active theme's tokens, so the switch and select restyle with the theme they switch to.
+
+The island paints its own surface, `--background` with `--foreground` in `--font-sans`, because its tokens flip below the card's own surface and the card's would otherwise show through. It grows to fill the frame. The controls are a group named "Theme preview"; the theme's name, when shown, is `--muted-foreground`.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.