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

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

@@ -0,0 +1,58 @@
+## What it is
+
+The system signature: a card surface with an optional header, a body, and a hairline-separated action bar (status left, actions right). It is the box everything else sits in. Use it for any bounded region with its own identity — a section of a dashboard, a form group's container, a list with a footer count. If the region needs a title row with actions but no surface, use **Toolbar**. If it collapses, use **Accordion** or **FormSection**. If it floats, **Popover** or **Dialog**.
+
+## The contract
+
+```
+@title?, @eyebrow?
+<:default>  <:status>  <:actions>
+Element: HTMLElement (a <section>)
+```
+
+Three decisions.
+
+**The footer renders when either `<:status>` or `<:actions>` is provided.** Status sits left, actions right; an actions-only panel gets a footer with the action cluster alone, and a status-only panel gets the line alone. (An earlier cut gated the footer on `status`, which silently dropped an actions-only panel's buttons; the unit test now holds the either/or.) If you want a title row with actions and no surface, use **Toolbar**.
+
+**`@eyebrow` is the mono uppercase voice**, shared with **Toolbar**, **DataGrid** headers and **FormField** labels. It is how the kit says "this is a category, not a title", and it is the same 11px mono with `--track-eyebrow` letterspacing everywhere.
+
+**The hairline is a `box-shadow`, not a `border`.** `box-shadow: 0 -1px 0 var(--border)` on the footer, and `box-shadow: 0 0 0 1px` for the panel's own edge. Shadows do not participate in layout, so the panel's box metrics are exactly its content plus padding — no `box-sizing` arithmetic, and nested panels do not accumulate border widths. This is a house convention: hairlines ride shadows throughout the kit.
+
+`overflow: hidden` plus `flex-direction: column` means a **DataGrid** or scrolling body clips to the panel's rounded corners without a second wrapper.
+
+## Prior art
+
+**Web Awesome `wa-card`** has `appearance` (accent/filled/outlined/plain), `with-header`/`with-image`/`with-footer` booleans for SSR slot detection, and four slots. **shadcn `Card`** is six components — `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter` — each a styled div. **React Spectrum** has `View` (a style primitive) and no card per se.
+
+Pretui takes the two-block route rather than shadcn's six-component route, and the trade is the usual one: fewer imports and no way to assemble a header out of order, versus less control. The specific improvement over shadcn is that **the footer's layout is prescribed** — status left, actions right, baseline aligned — so every panel footer in a product agrees. shadcn's `CardFooter` is a flex row and every team invents its own arrangement inside it.
+
+Against Web Awesome: no `appearance` axis. Every Panel is the same filled surface with a hairline. That is a real limitation — there is no quiet, borderless Panel — and the kit currently answers it by not using a Panel.
+
+## Accessibility
+
+No APG pattern. The relevant criteria are WCAG **1.3.1 Info and Relationships** and **2.4.6 Headings and Labels**.
+
+What is right: the root is a `<section>`, and the header is a `<header>` containing an `<h2>`, so the panel has real landmark and heading structure rather than nested `<div>`s.
+
+Gaps, and the heading one matters:
+
+- **The title is hard-coded as `<h2>`.** A card does not know its host's outline — the same panel may be embedded under an `<h1>` on one page and under an `<h3>` on another — so every Panel on a page emits an `h2` regardless of depth, producing skipped and repeated levels. **ErrorSummary** in the forms territory solved exactly this with an authorable `@headingLevel`; Panel should do the same, and this is the single clearest fix.
+- **A `<section>` is only a landmark when it has an accessible name**, and nothing wires `@title` to it. There is no `aria-labelledby` pointing at the `<h2>`. So a Panel is either an unnamed `section` (ignored by landmark navigation, which is fine) or, if a caller adds a role, an unlabeled one. Wiring the heading id would make panels navigable as regions — worth doing, but note that turning every panel into a landmark is its own kind of noise, so it should probably be opt-in.
+- **`@eyebrow` is inside the `<header>` but outside the `<h2>`**, so it is announced as loose text before the heading. Since eyebrows are usually category names ("REVENUE", "STEP 2"), that is arguably correct — but it means the heading alone is often not self-describing.
+- **A Panel with no `@title` has no header at all** and is a bare surface; that is correct and there is nothing to announce.
+- `overflow: hidden` on the panel can clip a focus ring on an element flush to its edge (WCAG **2.4.11/2.4.13**). Give focusable content a little inset.
+- The status/actions footer is a plain `<footer>` with two spans — no `role="toolbar"`, no grouping. For two or three buttons that is right; for more, use **Toolbar** or **ButtonGroup** inside it.
+
+## Theming
+
+`--card` (surface), `--radius-surface`, `--pretui-shadow-card` (the hairline edge), `--border` (the footer rule), `--foreground` (title), `--muted-foreground` (eyebrow and status ink), `--font-mono` + `--text-ui-xs` + `--track-eyebrow` (eyebrow voice), `--text-body`, `--text-ui`, `--track-heading`, `--space-3/4/5`.
+
+A theme retuning `--radius-surface` moves Panel, **Dialog** and **Drawer** together, which is intended — those three are the kit's surface vocabulary. `--pretui-shadow-card` is where a theme expresses whether panels are outlined or elevated; it defaults to a 1px ring and a theme can swap it for a real shadow without touching the component.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+Closest to Mantine `Paper` / a chromeless Card. Agents who want
+header/body/footer composition want the **Card** stub. Agents who want
+a Boxel identity tile want **FittedCard**.

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

@@ -0,0 +1,82 @@
+// Pretui — Panel usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Panel } from './panel';
+import { Button } from './button';
+
+// ── Panel ← container/usage.gts + card-container/usage.gts ───────────────
+
+// Dropped knobs: tag (Panel renders a fixed <section>); display (body layout
+// is left to content — no grid/flex switch); displayBoundaries (Panel always
+// draws its card surface and hairline).
+class PanelUsage extends GlimmerComponent {
+  @tracked title = 'Card';
+  @tracked eyebrow = 'container';
+  setTitle = (v: string) => (this.title = v);
+  setEyebrow = (v: string) => (this.eyebrow = v);
+  <template>
+    <FreestyleUsage
+      @name='Panel'
+      @description='A wrapper container for a card: the panel surface with standard padding, an optional title header, and the status/actions footer — the merged successor to Container and CardContainer.'
+    >
+      <:example>
+        <Panel @title={{this.title}} @eyebrow={{this.eyebrow}} class='panel-box'>
+          <:default>
+            <p class='panel-copy'>Card content here — the body block is
+              unstyled beyond standard padding, so one strategy is a root
+              element with <code>display: grid</code> to lay out your card.</p>
+          </:default>
+          <:status>Saved just now</:status>
+          <:actions>
+            <Button @tone='neutral' @appearance='outlined' @size='s'>Export</Button>
+            <Button @tone='primary' @size='s'>Publish</Button>
+          </:actions>
+        </Panel>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='title'
+          @description='Header title, shown at the top of the panel surface. Omit to render a headerless surface.'
+          @value={{this.title}}
+          @onInput={{this.setTitle}}
+        />
+        <Args.String
+          @name='eyebrow'
+          @description='Mono uppercase overline rendered above the title.'
+          @value={{this.eyebrow}}
+          @onInput={{this.setEyebrow}}
+        />
+        <Args.Yield
+          @description='Unstyled area for custom card content and fields'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @name='status'
+          @description='Status line at the start of the panel footer; the footer renders only when this block is present.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @name='actions'
+          @description='Action buttons aligned to the end of the panel footer.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .panel-box {
+        width: 100%;
+        max-width: 420px;
+      }
+      .panel-copy {
+        margin: 0;
+        font-size: var(--text-ui-md, 12.5px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_PANEL: Record<string, unknown> = {
+  Panel: PanelUsage,
+};

package/bundled-realms/pretui/components/password-input.gts

@@ -0,0 +1,329 @@
+// Pretui — PasswordInput: a password field with a reveal toggle.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { htmlSafe } from '@ember/template';
+import { BoxelInput } from '@cardstack/boxel-ui/components';
+import { emit, firstDefined } from '../pretui-primitives';
+import type { ControlAliasArgs } from '../pretui-primitives';
+import { PasswordStrength, estimateWhenIdle, loadPasswordEstimator } from './password-strength';
+import type { StrengthReading } from './password-strength';
+import { TYPED_FONT } from '../internal/extras';
+
+// BoxelInput @type='password' plus the reveal toggle boxel-ui doesn't
+// ship: an overlay eye button flips the native type to text while pressed
+// state holds (aria-pressed carries it). @autocomplete defaults to
+// 'current-password'; pass 'new-password' for signup forms, 'off' to opt
+// out. @revealable={{false}} removes the toggle.
+//
+// Strength estimation (added 2026-08-13) is OPT-IN via @strength={{true}} —
+// Law 9, weight is opt-in at the package boundary. Without it this component
+// is byte-for-byte what it was: the zxcvbn bundle (1.59 MiB / 839 KiB
+// gzipped) is not on the static import graph at all, and even with
+// @strength on it is fetched by the first estimate rather than by render, so
+// the field types and submits from first paint. See components/password-strength.gts.
+//
+// @userInputs is the single highest-value knob: hand it the user's own name,
+// email and handle and "chris1985" stops reading as strong, because zxcvbn
+// scores against them as a dictionary. Pass it on every signup form.
+//
+// Estimation is ADVICE. Nothing here disables the field, reports invalid, or
+// blocks submission on a score — current NIST 800-63B guidance is that
+// composition rules are counterproductive and that length and
+// not-being-breached are what matter. The password is never announced,
+// logged, put in the DOM as text, or sent anywhere; zxcvbn runs entirely
+// locally and there is no network call on this path.
+
+const PASSWORD_METRICS = htmlSafe(
+  'font: inherit; letter-spacing: inherit; line-height: 18px; padding-block: 4px; padding-right: 30px;',
+);
+
+/** Idle time after the last keystroke before an estimate runs. Long enough
+ * that a live region is not narrating mid-word, short enough to feel live. */
+const STRENGTH_DELAY = 400;
+
+export interface PasswordInputSignature {
+  Args: ControlAliasArgs & {
+    value?: string;
+    placeholder?: string;
+    disabled?: boolean;
+    required?: boolean;
+    controlId?: string;
+    /** autocomplete hint — 'current-password' by default */
+    autocomplete?: string;
+    /** show the reveal toggle — true by default */
+    revealable?: boolean;
+    onInput?: (value: string) => void;
+    /** render the strength indicator (opt-in; loads the estimator lazily) */
+    strength?: boolean;
+    /** what you already know about the user — name, email, handle, company.
+     * zxcvbn scores against these, so "chris1985" reads as weak instead of
+     * strong. The single most valuable thing you can pass. */
+    userInputs?: (string | number)[];
+    /** idle ms before an estimate runs — 400 by default */
+    strengthDelay?: number;
+    /** replace the five strength labels (localisation, or a house voice) */
+    strengthLabels?: readonly string[];
+    /** show the meter row before anything has been typed — false by default,
+     * so the field does not open with an empty accusation */
+    strengthAlwaysVisible?: boolean;
+    /** called with each settled estimate. Advice, not a gate — do not wire
+     * this to a submit button's disabled state. */
+    onStrength?: (reading: StrengthReading) => void;
+  };
+  Element: HTMLDivElement;
+}
+
+export class PasswordInput extends Component<PasswordInputSignature> {
+  @tracked revealed = false;
+  /** the value the estimator will see. Lives in memory only: it is never
+   * written to an attribute, a title, a test hook, or the console. */
+  @tracked pending = this.args.value ?? '';
+  @tracked reading: StrengthReading | undefined = undefined;
+  @tracked estimating = false;
+  /** discards the result of a superseded in-flight estimate */
+  private estimateRun = 0;
+
+  get revealable() {
+    return this.args.revealable ?? true;
+  }
+  get type() {
+    return this.revealed && this.revealable ? 'text' : 'password';
+  }
+  get autocomplete() {
+    return this.args.autocomplete ?? 'current-password';
+  }
+  get inputStyle() {
+    return this.revealable ? PASSWORD_METRICS : TYPED_FONT;
+  }
+  get strength() {
+    return this.args.strength ?? false;
+  }
+  get strengthDelay() {
+    return this.args.strengthDelay ?? STRENGTH_DELAY;
+  }
+  get strengthAlwaysVisible() {
+    return this.args.strengthAlwaysVisible ?? false;
+  }
+  get score() {
+    return this.reading?.score;
+  }
+  get warning() {
+    return this.reading?.warning;
+  }
+  get suggestions() {
+    return this.reading?.suggestions;
+  }
+  get crackTime() {
+    return this.reading?.crackTime;
+  }
+  get hideStrengthWhenEmpty() {
+    return !this.strengthAlwaysVisible;
+  }
+  /** A by-VALUE key for @userInputs, so learning the user's email re-scores
+   * the password — but an inline `{{array …}}` literal, which is a fresh
+   * object every render, does not re-arm the debounce. */
+  get userInputsKey() {
+    return (this.args.userInputs ?? []).join(', ');
+  }
+  get disabled() {
+    return firstDefined(this.args.disabled, this.args.isDisabled);
+  }
+  get required() {
+    return firstDefined(this.args.required, this.args.isRequired);
+  }
+  handleInput = (value: string) => {
+    this.pending = value;
+    emit(
+      [this.args.onInput, this.args.onChange, this.args.onValueChange],
+      value,
+    );
+  };
+  /** Fired by `estimateWhenIdle` once typing has settled. The estimator is
+   * fetched here — the first time anyone asks, and never again. */
+  runEstimate = (value: string) => {
+    if (!this.strength) {
+      return;
+    }
+    if (value === '') {
+      this.reading = undefined;
+      this.estimating = false;
+      return;
+    }
+    let run = ++this.estimateRun;
+    this.estimating = true;
+    loadPasswordEstimator()
+      .then((estimate) => {
+        if (this.isDestroying || run !== this.estimateRun) {
+          return;
+        }
+        let reading = estimate(value, this.args.userInputs ?? []);
+        this.reading = reading;
+        this.estimating = false;
+        this.args.onStrength?.(reading);
+      })
+      .catch(() => {
+        // A meter that fails to load is a missing meter, not a broken field.
+        if (this.isDestroying || run !== this.estimateRun) {
+          return;
+        }
+        this.reading = undefined;
+        this.estimating = false;
+      });
+  };
+  toggle = (_e: Event) => {
+    this.revealed = !this.revealed;
+  };
+  <template>
+    <div
+      class='pretui-boxelwrap'
+      data-revealed={{if this.revealed 'true'}}
+      data-test-pretui-password-input
+      ...attributes
+    >
+      <BoxelInput
+        @type={{this.type}}
+        @value={{@value}}
+        @placeholder={{@placeholder}}
+        @disabled={{this.disabled}}
+        @required={{this.required}}
+        @autocomplete={{this.autocomplete}}
+        @onInput={{this.handleInput}}
+        id={{@controlId}}
+        style={{this.inputStyle}}
+      />
+      {{#if this.revealable}}
+        <button
+          type='button'
+          class='pretui-reveal'
+          aria-label={{if this.revealed 'Hide password' 'Show password'}}
+          aria-pressed={{if this.revealed 'true' 'false'}}
+          disabled={{this.disabled}}
+          {{on 'click' this.toggle}}
+        >
+          {{#if this.revealed}}
+            <svg
+              width='14'
+              height='14'
+              viewBox='0 0 16 16'
+              aria-hidden='true'
+            ><path
+                d='M1.5 8s2.4-4.5 6.5-4.5S14.5 8 14.5 8 12.1 12.5 8 12.5 1.5 8 1.5 8Z'
+                fill='none'
+                stroke='currentColor'
+                stroke-width='1.3'
+                stroke-linejoin='round'
+              /><circle
+                cx='8'
+                cy='8'
+                r='2'
+                fill='none'
+                stroke='currentColor'
+                stroke-width='1.3'
+              /><path
+                d='M2.5 13.5 13.5 2.5'
+                fill='none'
+                stroke='currentColor'
+                stroke-width='1.3'
+                stroke-linecap='round'
+              /></svg>
+          {{else}}
+            <svg
+              width='14'
+              height='14'
+              viewBox='0 0 16 16'
+              aria-hidden='true'
+            ><path
+                d='M1.5 8s2.4-4.5 6.5-4.5S14.5 8 14.5 8 12.1 12.5 8 12.5 1.5 8 1.5 8Z'
+                fill='none'
+                stroke='currentColor'
+                stroke-width='1.3'
+                stroke-linejoin='round'
+              /><circle
+                cx='8'
+                cy='8'
+                r='2'
+                fill='none'
+                stroke='currentColor'
+                stroke-width='1.3'
+              /></svg>
+          {{/if}}
+        </button>
+      {{/if}}
+      {{#if this.strength}}
+        {{! The meter lives INSIDE the existing wrapper so the component keeps
+            exactly one root element and `...attributes` lands where it always
+            did. The modifier owns the debounce timer and cancels it in its
+            destructor — it is one-shot and cannot re-arm itself. }}
+        <div
+          class='pretui-password-strength'
+          {{estimateWhenIdle
+            this.pending
+            this.strengthDelay
+            this.runEstimate
+            this.userInputsKey
+          }}
+        >
+          <PasswordStrength
+            @score={{this.score}}
+            @warning={{this.warning}}
+            @suggestions={{this.suggestions}}
+            @crackTime={{this.crackTime}}
+            @labels={{@strengthLabels}}
+            @busy={{this.estimating}}
+            @hideWhenEmpty={{this.hideStrengthWhenEmpty}}
+          />
+        </div>
+      {{/if}}
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        /* Same re-skin channel as EmailInput — see that component's note. */
+        .pretui-boxelwrap {
+          position: relative;
+          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-input-height: var(--control-h, 28px);
+          --boxel-form-control-border-radius: var(--radius);
+          --boxel-sp-xs: 5px;
+          --boxel-sp-sm: 9px;
+        }
+        .pretui-reveal {
+          position: absolute;
+          top: calc((var(--control-h, 28px) - 20px) / 2);
+          right: 5px;
+          display: grid;
+          place-items: center;
+          width: 20px;
+          height: 20px;
+          border: 0;
+          padding: 0;
+          border-radius: 6px;
+          background: none;
+          color: var(--muted-foreground);
+          cursor: pointer;
+        }
+        .pretui-reveal:hover:not(:disabled) {
+          background: var(--hover, var(--boxel-100));
+          color: var(--foreground);
+        }
+        .pretui-reveal:disabled {
+          opacity: 0.45;
+          cursor: default;
+        }
+        /* The meter sits under the control inside the same wrapper. It is the
+           only thing that changes the wrapper's height, and only when
+           @strength is on. */
+        .pretui-password-strength {
+          margin-block-start: var(--space-2, 6px);
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/password-input.md

@@ -0,0 +1,58 @@
+## What it is
+
+A password field with a reveal toggle. Use it for any credential entry. The reveal is on by default, which is the right default — hiding a password the user is _typing_ protects against shoulder-surfing and costs them the ability to check their own typing, and letting them choose is strictly better than choosing for them.
+
+## The contract
+
+```
+@value?, @placeholder?, @disabled?, @required?, @controlId?
+@autocomplete? (default 'current-password')
+@revealable? (default true)
+@onInput?(value: string)
+```
+
+**`@autocomplete` defaults to `'current-password'`, and this is the arg you must think about.** A sign-in field is `current-password`; a registration or change-password field is `new-password` — and getting that wrong means password managers offer the saved password where they should generate a new one, or vice versa. It is also the only member of the typed-input family that exposes `autocomplete` as a first-class arg, which is a good decision that the rest of the family should copy.
+
+**`@revealable={{false}}` removes the toggle**, and the component swaps its inline metrics accordingly (`PASSWORD_METRICS` reserves room for the button; `TYPED_FONT` does not) so a non-revealable field has no dead space on its right.
+
+The reveal is implemented by swapping `type` between `'password'` and `'text'` — the standard approach, and worth knowing because it means the value is briefly a plain text input, visible to anything reading the DOM.
+
+## Prior art
+
+**Web Awesome** folds this into `wa-input`: `password-toggle`, `password-visible`, and `show-password-icon`/`hide-password-icon` slots, with the toggle at **`tabindex="-1"`** and a localized `aria-label`. **React Spectrum** has no password field at all. **shadcn** has none; the reveal is a docs recipe.
+
+So the comparison is really against `wa-input`, and Pretui matches it on the essentials while making it a distinct component rather than a mode of the text input. That is arguably the better factoring — a password field has a different `autocomplete` contract, a different validation story and a different security posture from a text field, and modelling it as `type="password"` on a general input invites people to forget all three.
+
+Where Pretui is ahead: **`@autocomplete` as an explicit arg with a considered default.** Web Awesome inherits `autocomplete` from the generic input and does not default it, so every call site must remember.
+
+Where it is behind:
+
+- **No strength meter and no requirements display.** A registration field needs both, and **Meter** is right there. Composing it is on you.
+- **No `caps lock` warning**, which is the single most common cause of a failed sign-in.
+- **No confirm-field pairing.**
+- **No masked-reveal timeout** — once revealed, it stays revealed until toggled back.
+
+## Accessibility
+
+No APG pattern; a native `<input type="password">` with a toggle button.
+
+Gaps, and the toggle is where most of them live:
+
+- **The toggle's tab-order treatment needs checking.** Web Awesome deliberately sets `tabindex="-1"` on its reveal button so Tab moves from the password field to the submit button rather than into a decorative control. If Pretui's toggle is a normal tab stop, every sign-in form costs an extra Tab. Verify.
+- **The toggle's accessible name must change with state** — "Show password" / "Hide password" — and the state change should be announced. Changing an `aria-label` does not announce on its own; a screen-reader user pressing the toggle may hear nothing and not know whether the password is now visible. This is the same gap **CopyButton** has, and it matters more here because the consequence is a visible credential.
+- **`aria-pressed` would be more honest than a changing label.** The toggle _is_ a two-state control, and APG's toggle-button guidance is explicit that the label should stay fixed while `aria-pressed` carries the state. A changing label also breaks voice control ("click show password" stops working once pressed).
+- **Revealing the password is a visual state with no non-visual signal.** A screen-reader user has no indication that their password is currently displayed on screen — which is a privacy consideration, not just a usability one.
+- **No accessible name of its own** for the field. Outside **Field**/**FormField** and without an explicit `aria-label`, it is unnamed.
+- **Never block paste**, and this does not — good, and worth stating because blocking paste is still common and actively harms password-manager users.
+- **Requirements must be available before submission** (**WCAG 3.3.2**). There is no `@hint`; use **FormField**'s `@description`, and reference it with `aria-describedby` so it is announced with the field rather than encountered after it.
+- **`@disabled` uses the native attribute**, removing the field from the tab order.
+
+## Theming
+
+Consumed: `--field`, `--input`, `--primary` (focus ring via `--ring`), `--ink-3` (placeholder), `--control-h`, `--radius`, `--text-ui-md`, `--text-ui-sm`, `--text-ui-xs`, `--track-ui`, plus **IconButton**'s tokens for the toggle.
+
+Forwarded into boxel-ui through the `--boxel-*` channel, matching **Input**'s metrics.
+
+`data-revealed` is reflected on the wrapper, so a stylesheet can dress the revealed state — a tinted hairline, a changed toggle color — beyond the icon swap. Given that the revealed state has real privacy consequences and is currently signaled only by the glyph, using that hook is worth doing. Note the inline metrics differ between revealable and non-revealable modes, so a theme cannot change the toggle's reserved width through a token.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.