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

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

@@ -0,0 +1,283 @@
+// Pretui — Collapsible: a single disclosure panel with an animated reveal.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { guidFor } from '@ember/object/internals';
+import type { PretuiSize } from '../pretui-primitives';
+import { pretuiSize } from '../internal/structure-layout';
+import type { SizeAlias } from '../internal/structure-layout';
+
+// ── Collapsible ──────────────────────────────────────────────────────────
+//
+// Sources read: radix-primitives/packages/react/collapsible, shadcn
+// collapsible.tsx, chakra collapsible.
+//
+// The single disclosure. `Accordion` (structure-extras.gts) is the multi-panel
+// set and `Fold` (agentic.gts) is the receipt-shaped one; this is the plain
+// "one trigger, one region" primitive, which is what an agent typing
+// `<Collapsible>` means.
+//
+// What is fixed relative to Radix:
+//
+//   1. **No measurement.** Radix publishes
+//      `--radix-collapsible-content-height` by *mutating the element's own*
+//      `style.transitionDuration` and `style.animationName` to `0s`/`none`,
+//      reading `getBoundingClientRect()`, and restoring the originals from a
+//      ref that is captured once and never refreshed
+//      (`originalStylesRef.current = originalStylesRef.current || {…}`). The
+//      published value is a pixel count, so it is stale the moment the
+//      content reflows. This uses the kit's expand grammar
+//      (`grid-template-rows: 0fr → 1fr`): the browser animates
+//      the real height with no JS at all, and content that grows
+//      mid-transition just works. Never `max-height`, never `scrollHeight`.
+//   2. **Neither of Radix's two content modes is right.** The default path
+//      renders `{isOpen && children}`, so every open REMOUNTS the content —
+//      uncontrolled inputs reset, scroll position is lost, a playing video
+//      restarts. The `forceMount` path, which is the one you need for any
+//      animation at all, then leaves focusable content reachable behind a
+//      clipped box. Here the content stays mounted and `visibility: hidden`
+//      takes it out of both the tab order and the accessibility tree,
+//      transitioned with a `0s linear <duration>` step so it only flips at
+//      the end of the collapse. State survives; focus does not leak.
+//   3. **`disabled` is the native attribute upstream.** A disabled trigger
+//      that leaves the tab order is a control that vanishes; `aria-disabled`
+//      keeps it focusable and announced, and the handler is the gate.
+//   4. **There is no indicator slot.** The near-universal rotating chevron
+//      has to be hand-built off `data-state` in every Radix and shadcn
+//      consumer. It is built in here and `@hideCaret` turns it off.
+//   5. **State attributes disagree with themselves upstream** —
+//      `data-state="open"|"closed"` is a string but `data-disabled=""` is a
+//      bare presence attribute, so consumers write two selector idioms for
+//      one component. Everything here reflects `'true'`/`'false'`.
+//   6. **Reduced motion lands on the END state**, not a frozen midpoint.
+//      Not one of Radix, shadcn or the shadcn registry ships a
+//      `prefers-reduced-motion` guard for this component.
+
+export interface CollapsibleSignature {
+  Args: {
+    /** Controlled open state. Leave undefined for the uncontrolled half. */
+    open?: boolean;
+    /** Uncontrolled initial state. Default `false`. */
+    defaultOpen?: boolean;
+    /** Fires on every toggle, controlled or not. */
+    onOpenChange?: (open: boolean) => void;
+    /** Trigger label. Sugar for `<:trigger>`; the block wins. */
+    label?: string;
+    /** Announced and styled as disabled; stays focusable (`aria-disabled`). */
+    disabled?: boolean;
+    /** Size. */
+    size?: SizeAlias;
+    /** Hide the rotating caret — for a trigger that is its own affordance. */
+    hideCaret?: boolean;
+  };
+  Blocks: {
+    /** The trigger's contents. Yielded the current open state. */
+    trigger: [boolean];
+    /** The disclosed region. */
+    default: [];
+  };
+  Element: HTMLDivElement;
+}
+
+/**
+ * One trigger, one disclosed region.
+ *
+ * ```hbs
+ * <Collapsible @label='Advanced' @defaultOpen={{false}}>
+ *   <FormRow …/>
+ * </Collapsible>
+ * ```
+ */
+export class Collapsible extends Component<CollapsibleSignature> {
+  @tracked private internal = this.args.defaultOpen ?? false;
+  private contentId = `${guidFor(this)}-content`;
+  private triggerId = `${guidFor(this)}-trigger`;
+
+  get open(): boolean {
+    return this.args.open ?? this.internal;
+  }
+  get size(): PretuiSize {
+    return pretuiSize(this.args.size);
+  }
+  get state(): string {
+    return this.open ? 'open' : 'closed';
+  }
+  toggle = () => {
+    if (this.args.disabled) {
+      return;
+    }
+    let next = !this.open;
+    // Internal state moves only while UNcontrolled; the callback always fires.
+    if (this.args.open === undefined) {
+      this.internal = next;
+    }
+    this.args.onOpenChange?.(next);
+  };
+
+  <template>
+    <div
+      class='pretui-collapsible'
+      data-state={{this.state}}
+      data-size={{this.size}}
+      data-disabled={{if @disabled 'true' 'false'}}
+      data-test-pretui-collapsible
+      ...attributes
+    >
+      <button
+        type='button'
+        id={{this.triggerId}}
+        class='pretui-collapsible-trigger'
+        aria-expanded={{if this.open 'true' 'false'}}
+        {{! Radix only emits aria-controls while OPEN, because its content
+            carries the `hidden` attribute when closed and pointing
+            aria-controls at a hidden id is an axe violation. This content is
+            never `hidden` — it is a visibility-collapsed region that always
+            exists — so the reference is always valid and always present,
+            which is what lets a reader jump to the region before opening it. }}
+        aria-controls={{this.contentId}}
+        aria-disabled={{if @disabled 'true'}}
+        data-state={{this.state}}
+        data-test-pretui-collapsible-trigger
+        {{on 'click' this.toggle}}
+      >
+        {{#unless @hideCaret}}
+          <span class='pretui-collapsible-caret' aria-hidden='true'></span>
+        {{/unless}}
+        <span class='pretui-collapsible-label'>
+          {{#if (has-block 'trigger')}}
+            {{yield this.open to='trigger'}}
+          {{else}}
+            {{@label}}
+          {{/if}}
+        </span>
+      </button>
+
+      {{! The kit's expand grammar: 0fr → 1fr animates the real height with no
+          measurement and no max-height guess. `visibility` rides along on a
+          delayed 0s step so a closed region is out of the tab order and out of
+          the accessibility tree, not merely clipped. }}
+      <div
+        id={{this.contentId}}
+        class='pretui-collapsible-fold'
+        role='region'
+        aria-labelledby={{this.triggerId}}
+        data-state={{this.state}}
+        data-test-pretui-collapsible-content
+      >
+        <div class='pretui-collapsible-inner'>{{yield}}</div>
+      </div>
+    </div>
+
+    <style scoped>
+      @layer PretComponent {
+        .pretui-collapsible {
+          display: grid;
+          min-inline-size: 0;
+          font-size: var(--pretui-size-m, var(--text-ui-md, 0.78rem));
+          letter-spacing: var(--track-ui, 0.01em);
+          color: var(--foreground);
+        }
+        .pretui-collapsible[data-size='xs'] {
+          font-size: var(--pretui-size-xs, var(--text-ui-xs, 0.66rem));
+        }
+        .pretui-collapsible[data-size='s'] {
+          font-size: var(--pretui-size-s, var(--text-ui-sm, 0.72rem));
+        }
+        .pretui-collapsible[data-size='l'] {
+          font-size: var(--pretui-size-l, var(--text-ui-lg, 0.875rem));
+        }
+        .pretui-collapsible[data-size='xl'] {
+          font-size: var(--pretui-size-xl, var(--text-ui-xl, 1rem));
+        }
+        .pretui-collapsible-trigger {
+          display: inline-flex;
+          align-items: center;
+          gap: 0.5em;
+          justify-self: start;
+          min-block-size: var(--pretui-collapsible-h, 2.24em);
+          padding: 0 var(--pretui-collapsible-px, 0.5em);
+          margin-inline-start: calc(var(--pretui-collapsible-px, 0.5em) * -1);
+          border: 0;
+          border-radius: var(--radius-chip, 6px);
+          background: none;
+          color: inherit;
+          font: inherit;
+          letter-spacing: inherit;
+          font-weight: 600;
+          text-align: start;
+          cursor: pointer;
+          min-inline-size: 0;
+        }
+        .pretui-collapsible-trigger:hover {
+          background: var(--hover, var(--boxel-100));
+        }
+        .pretui-collapsible-trigger:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 1px;
+        }
+        .pretui-collapsible-trigger:active {
+          transform: scale(0.985);
+        }
+        .pretui-collapsible[data-disabled='true'] .pretui-collapsible-trigger {
+          opacity: 0.45;
+          cursor: default;
+        }
+        .pretui-collapsible[data-disabled='true'] .pretui-collapsible-trigger:hover {
+          background: none;
+        }
+        .pretui-collapsible-label {
+          min-inline-size: 0;
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+        }
+        .pretui-collapsible-caret {
+          flex: none;
+          inline-size: 0.45em;
+          block-size: 0.45em;
+          border-inline-end: 1.5px solid currentColor;
+          border-block-end: 1.5px solid currentColor;
+          transform: rotate(-45deg) translate(-0.1em, -0.1em);
+          color: var(--muted-foreground);
+          transition: transform var(--pretui-dur-snap, 180ms)
+            var(--pretui-ease-snap, ease);
+        }
+        .pretui-collapsible-trigger[data-state='open'] .pretui-collapsible-caret {
+          transform: rotate(45deg) translate(-0.05em, -0.15em);
+        }
+        .pretui-collapsible-fold {
+          display: grid;
+          grid-template-rows: 0fr;
+          visibility: hidden;
+          transition: grid-template-rows var(--pretui-dur-morph, 300ms)
+              var(--pretui-ease-morph, cubic-bezier(0.3, 0.7, 0.2, 1.02)),
+            visibility 0s linear var(--pretui-dur-morph, 300ms);
+        }
+        .pretui-collapsible-fold[data-state='open'] {
+          grid-template-rows: 1fr;
+          visibility: visible;
+          transition: grid-template-rows var(--pretui-dur-morph, 300ms)
+              var(--pretui-ease-morph, cubic-bezier(0.3, 0.7, 0.2, 1.02)),
+            visibility 0s;
+        }
+        .pretui-collapsible-inner {
+          min-block-size: 0;
+          min-inline-size: 0;
+          overflow: hidden;
+        }
+        /* Reduced motion lands on the END state — open is open, closed is
+           closed, never a frozen midpoint of the row track. */
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-collapsible-fold,
+          .pretui-collapsible-fold[data-state='open'],
+          .pretui-collapsible-caret {
+            transition: none;
+          }
+          .pretui-collapsible-trigger:active {
+            transform: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,69 @@
+## What it is
+
+One trigger, one disclosed region. Use it for the single "show more" a page needs — advanced options under a form, grading notes under a lot, a long caption folded away. If several sections belong together and open independently, use **Accordion**, which is a stack of these with the boxel-ui engine underneath. If the region is a receipt of agent work with a rail down the side, that is **Fold**. If the collapsible group lives inside an inspector and needs a titled header row, use **PanelSection**. If nothing needs to animate and no state needs to survive, a native `<details>` is enough.
+
+## The contract
+
+```
+@open?           — controlled state; leave undefined for the uncontrolled half
+@defaultOpen?    — uncontrolled initial state (default false)
+@onOpenChange?   — fires on every toggle with the next state, controlled or not
+@label?          — trigger text; sugar for <:trigger>
+@disabled?       — announced and styled as disabled, still focusable
+@size?           — the kit size scale (xs · s · m · l · xl, default m)
+@hideCaret?      — drop the rotating chevron
+<:trigger as |open|>   — wins over @label; yielded the current state
+<:default>             — the disclosed region
+```
+
+**Hybrid state, one callback.** With `@open` undefined the component keeps its own state and `@defaultOpen` seeds it. With `@open` set the component never moves itself — it reports the requested state through `@onOpenChange` and waits for the parent to change the arg. The callback fires in both modes, so a consumer that only wants to count toggles need not choose.
+
+**The region is never unmounted.** Closed content stays in the DOM; the fold's `visibility` takes it out of the tab order and the accessibility tree, on a delayed step so it only flips once the collapse has finished. An input inside keeps its value across a toggle, and the animation is the height itself — a grid row track going from `0fr` to `1fr` — so nothing is measured and nothing goes stale when the content reflows mid-transition.
+
+**Disabled is `aria-disabled`, not the attribute.** The trigger stays focusable and announced; the click handler is the gate, and the callback does not fire.
+
+**State attributes are strings both ways.** `data-state='open' | 'closed'` on the root and the trigger, `data-disabled='true' | 'false'` on the root, so a consumer writes one selector idiom.
+
+## Prior art
+
+**Radix `Collapsible`** (and **shadcn**, which re-exports it) is the reference agents type from memory: `open` / `defaultOpen` / `onOpenChange` / `disabled`, a `Trigger` and a `Content`. Radix animates by publishing `--radix-collapsible-content-height`, which it obtains by temporarily zeroing the element's own transition and reading `getBoundingClientRect()` — a pixel value that is stale the moment the content reflows. Its default content mode renders `{open && children}`, so every open remounts the region and uncontrolled inputs reset; the `forceMount` mode you need for any animation leaves focusable content reachable behind a clipped box. Its `data-state` is a string while `data-disabled` is a bare presence attribute. **Chakra `Collapsible`** has the same shape plus `unmountOnExit`. **React Aria `Disclosure`** spells the state `isExpanded` / `onExpandedChange` and provides the button and panel roles. **Mantine `Collapse`** and **MUI `Collapse`** are animation wrappers only — no trigger, no ARIA.
+
+Where this is better: the height animation is the kit's expand grammar with no measurement and no JS; content stays mounted and is genuinely removed from the tab order when closed; the trigger stays focusable when disabled; the rotating caret every Radix consumer hand-builds off `data-state` is built in and switchable; and reduced motion lands on the end state rather than a frozen midpoint, which none of Radix, shadcn or the shadcn registry guard.
+
+Where it is thinner: there is no `unmountOnExit` — the region is always mounted, by design, and a consumer that needs teardown wraps the content in its own `{{#if}}`. There is no `isExpanded` / `onExpandedChange` spelling. The trigger is always a button with the label inside it; a consumer who wants a heading around it has to supply the heading and put the whole component in it.
+
+## Accessibility
+
+Governing pattern: APG **Disclosure**. The pattern requires a button with `aria-expanded`, optionally `aria-controls` pointing at the region, Enter and Space to toggle. All three are here and asserted.
+
+- **The trigger is a native `<button type='button'>`** carrying `aria-expanded='true' | 'false'` and `aria-controls` pointing at the region's id. `aria-controls` is present while closed as well as open — Radix omits it when closed because its closed content carries `hidden`, and the region here is never `hidden`, so the reference is always valid and a reader can jump to the region before opening it.
+- **The region is `role='region'` with `aria-labelledby` back to the trigger**, so it is named by its own trigger text. This is the right call for a single disclosure; a page with many of them will accumulate landmarks, which is where **Accordion**'s engine — region optional — is the better fit.
+- **Closed content is out of the tab order and the accessibility tree** through `visibility: hidden`, not clipping. A test asserts the content exists in the DOM while closed and that a field inside keeps its value across a toggle.
+- **`@disabled` keeps the trigger focusable** with `aria-disabled='true'` and no native `disabled`, so a keyboard user still finds it and hears that it is disabled. The click is refused and the callback does not fire.
+- **Enter and Space come from the native button**, so there is no key handling to get wrong, and nothing here manages focus — correct for the pattern.
+- **The caret is `aria-hidden`.** The label span is the trigger's only accessible text; a `<:trigger>` block is announced as whatever you put in it, so put text in it.
+- What is the caller's: the trigger has no heading semantics. If the disclosure is a section of a document, wrap it in the heading you mean.
+
+## Theming
+
+Consumed directly: `--foreground`, `--muted-foreground` (the caret), `--hover` (trigger hover fill), `--ring` (focus outline), `--radius-chip` (trigger corners), `--track-ui`, and the size scale `--pretui-size-xs` … `--pretui-size-xl` with `--text-ui-xs` … `--text-ui-xl` as the fallbacks.
+
+The component's own knobs: `--pretui-collapsible-h` (minimum trigger height, 2.24em) and `--pretui-collapsible-px` (trigger inline padding, 0.5em — also the negative margin that keeps the label flush with the content edge).
+
+Motion is the kit's: `--pretui-dur-morph` / `--pretui-ease-morph` for the fold, `--pretui-dur-snap` / `--pretui-ease-snap` for the caret. A theme retunes every Collapsible's expand by retuning the morph pair; the reduced-motion branch removes both transitions and the trigger's press scale. The 600 trigger weight, the 0.45em caret and the 0.985 press scale are fixed.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+| React                                    | Pretui                                        |
+| ---------------------------------------- | --------------------------------------------- |
+| `open` / `onOpenChange` / `defaultOpen`  | the same names                                |
+| `disabled`                               | `@disabled` (aria-disabled, stays focusable)  |
+| `isExpanded` / `onExpandedChange` (Aria) | `@open` / `@onOpenChange`                     |
+| `<Collapsible.Trigger>`                  | `@label` or `<:trigger>`                      |
+| `<Collapsible.Content>`                  | `<:default>`                                  |
+| `unmountOnExit` / `forceMount`           | not offered; the region is always mounted     |
+| `data-state`, `data-disabled`            | both present, both `'true'`/`'false'` strings |
+
+**Accordion** is N of these behind boxel-ui's engine; **Disclosure** is the React Aria name for this component.

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

@@ -0,0 +1,173 @@
+// Pretui — Collapsible usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+
+import { FreestyleUsage } from './freestyle-usage';
+import { Collapsible } from './collapsible';
+import type { SizeAlias } from '../internal/structure-layout';
+
+class CollapsibleUsage extends Component {
+  @tracked open = false;
+  @tracked disabled = false;
+  @tracked hideCaret = false;
+  @tracked size = 'm';
+  @tracked events = 0;
+
+  sizeOptions = ['xs', 's', 'm', 'l', 'xl'];
+
+  setOpen = (v: boolean) => {
+    this.open = v;
+    this.events = this.events + 1;
+  };
+  setDisabled = (v: boolean) => {
+    this.disabled = v;
+  };
+  setHideCaret = (v: boolean) => {
+    this.hideCaret = v;
+  };
+  setSize = (v: string) => {
+    this.size = v;
+  };
+
+  get sizeValue(): SizeAlias {
+    return this.size as SizeAlias;
+  }
+
+  get usage(): string {
+    return [
+      '<Collapsible',
+      "  @label='Advanced'",
+      '  @open={{this.open}}',
+      '  @onOpenChange={{this.setOpen}}',
+      '>',
+      '  <FormRow …/>',
+      '</Collapsible>',
+    ].join('\n');
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='Collapsible'
+      @description='One trigger, one disclosed region. The height animates with the kit expand grammar — a grid row track going from 0fr to 1fr — so there is no measurement, no max-height guess and no stale pixel value when the content reflows mid-transition. Content stays mounted and visibility takes it out of the tab order, so an input inside keeps its value across a toggle.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='fold-stage'>
+          <Collapsible
+            @label='Grading notes'
+            @open={{this.open}}
+            @onOpenChange={{this.setOpen}}
+            @disabled={{this.disabled}}
+            @hideCaret={{this.hideCaret}}
+            @size={{this.sizeValue}}
+          >
+            <div class='fold-body'>
+              <p class='fold-p'>Leaf is even and tightly rolled, with a bright
+                liquor and no astringency at the finish. Cupped twice, both
+                against the reference lot.</p>
+              <p class='fold-p'>Toggle this twice and note that the region is
+                never remounted — Radix rebuilds its children on every open
+                unless you opt into a mode that then leaks focus into the
+                closed box.</p>
+            </div>
+          </Collapsible>
+          <p class='fold-count'>onOpenChange fired
+            <b>{{this.events}}</b>
+            times</p>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Bool
+          @name='open'
+          @description='Controlled state. Leave it undefined for the uncontrolled half; the callback fires either way.'
+          @defaultValue={{false}}
+          @value={{this.open}}
+          @onInput={{this.setOpen}}
+        />
+        <Args.Bool
+          @name='defaultOpen'
+          @description='The uncontrolled initial state.'
+          @defaultValue={{false}}
+        />
+        <Args.Action
+          @name='onOpenChange'
+          @description='Fires on every toggle with the next state, controlled or not.'
+        />
+        <Args.String
+          @name='label'
+          @description='Trigger text. Sugar for the trigger block, which wins when both are present and is yielded the open state.'
+        />
+        <Args.Bool
+          @name='disabled'
+          @description='Announced and styled as disabled, and still focusable — aria-disabled, never the native attribute, because a control that leaves the tab order is a control that vanished.'
+          @defaultValue={{false}}
+          @value={{this.disabled}}
+          @onInput={{this.setDisabled}}
+        />
+        <Args.Bool
+          @name='hideCaret'
+          @description='Drop the rotating chevron, for a trigger that is its own affordance. Radix and shadcn have no indicator slot at all, so this gets hand-built in every consumer.'
+          @defaultValue={{false}}
+          @value={{this.hideCaret}}
+          @onInput={{this.setHideCaret}}
+        />
+        <Args.String
+          @name='size'
+          @description='The kit size scale.'
+          @options={{this.sizeOptions}}
+          @value={{this.size}}
+          @onInput={{this.setSize}}
+          @defaultValue='m'
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-collapsible-h'
+          @type='dimension'
+          @description='Minimum trigger height, in em.'
+          @defaultValue='2.24em'
+        />
+        <Css.Basic
+          @name='pretui-dur-morph'
+          @type='time'
+          @description='The expand duration. A theme retunes it for the whole kit.'
+          @defaultValue='300ms'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+
+    <style scoped>
+      .fold-stage {
+        max-inline-size: 460px;
+        padding: var(--space-5, 14px);
+        border-radius: var(--radius-surface, 10px);
+        background: var(--card);
+        box-shadow: var(
+          --pretui-shadow-hairline,
+          0 0 0 1px var(--border)
+        );
+      }
+      .fold-body {
+        padding-block-start: var(--space-3, 8px);
+        display: grid;
+        gap: var(--space-3, 8px);
+      }
+      .fold-p {
+        margin: 0;
+        font-size: var(--text-ui-sm, 11.5px);
+        line-height: 1.55;
+        color: var(--muted-foreground);
+      }
+      .fold-count {
+        margin: var(--space-4, 11px) 0 0;
+        font-size: var(--text-ui-xs, 11px);
+        font-variant-numeric: tabular-nums;
+        color: var(--ink-3, var(--boxel-400));
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_COLLAPSIBLE: Record<string, unknown> = {
+  Collapsible: CollapsibleUsage,
+};