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

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

@@ -0,0 +1,301 @@
+// Pretui — PanelSection: a collapsible group of property rows.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { guidFor } from '@ember/object/internals';
+
+// ═══════════════════════════════════════════════════════════════════════
+// PanelSection — the collapsible group (fig-group)
+// ═══════════════════════════════════════════════════════════════════════
+
+export interface PanelSectionSignature {
+  Args: {
+    /** section heading */
+    title?: string;
+    /** heading level for the title, 2–6. Defaults to 3 — a panel section
+     * sits under the panel's own h2. */
+    level?: 2 | 3 | 4 | 5 | 6;
+    /** false makes the section a plain titled group with no disclosure */
+    collapsible?: boolean;
+    /** CONTROLLED open state. Omit to let the section own it. */
+    open?: boolean;
+    /** initial open state when uncontrolled (default true) */
+    defaultOpen?: boolean;
+    /** small count/summary shown after the title (e.g. "3 effects") */
+    summary?: string;
+    /** 0 (default) is a top-level group. 1–3 mark a group nested INSIDE
+     * another group — a Person inside a Subject — which drops the peer
+     * hairline, de-shouts the heading out of small-caps, and hangs the body
+     * off a vertical rule so the nesting is legible in a still frame rather
+     * than only while collapsing. Indentation itself compounds from the
+     * parent's own body padding; this arg supplies the treatment, not the
+     * offset. */
+    depth?: number;
+    onToggle?: (open: boolean) => void;
+  };
+  Blocks: {
+    default: [];
+    /** controls that ride in the header — an add button, an eye toggle.
+     * Rendered OUTSIDE the disclosure button so they stay independently
+     * clickable, which figui3's whole-header click target breaks. */
+    actions: [];
+  };
+  Element: HTMLElement;
+}
+
+/**
+ * A titled, collapsible group of property rows — the workhorse of an
+ * inspector.
+ *
+ * Fixes carried over figui3's `fig-group`:
+ *
+ *  - Upstream puts `role='button'` + `tabindex=0` on the whole `fig-header`,
+ *    so any action button inside it is swallowed by the toggle. Here the
+ *    disclosure is a real `<button>` and `<:actions>` sits beside it.
+ *  - Upstream's chevron lives inside the `<h3>`, making the heading text
+ *    read as "▸ Layout" to a screen reader. Here the chevron is
+ *    `aria-hidden` and the heading wraps the button (the APG disclosure
+ *    shape), so the accessible name is just the title.
+ *  - The collapse is a `grid-template-rows: 0fr → 1fr` transition rather
+ *    than `display: none`, so it animates without measuring a height, and
+ *    lands on the END state under `prefers-reduced-motion`.
+ */
+export class PanelSection extends Component<PanelSectionSignature> {
+  @tracked internalOpen = this.args.defaultOpen ?? true;
+  private guid = guidFor(this);
+
+  get regionId(): string {
+    return this.guid + '-region';
+  }
+  get summaryId(): string {
+    return this.guid + '-summary';
+  }
+  get open(): boolean {
+    return this.args.open ?? this.internalOpen;
+  }
+  get collapsible(): boolean {
+    return this.args.collapsible ?? true;
+  }
+  get expanded(): boolean {
+    return this.collapsible ? this.open : true;
+  }
+  get level(): number {
+    let raw = this.args.level ?? 3;
+    return raw >= 2 && raw <= 6 ? raw : 3;
+  }
+  get depth(): number {
+    let raw = Math.trunc(Number(this.args.depth ?? 0));
+    if (!Number.isFinite(raw) || raw <= 0) {
+      return 0;
+    }
+    return Math.min(3, raw);
+  }
+  toggle = () => {
+    let next = !this.open;
+    if (this.args.open === undefined) {
+      this.internalOpen = next;
+    }
+    this.args.onToggle?.(next);
+  };
+  <template>
+    <section
+      class='pretui-section'
+      data-open={{if this.expanded 'true' 'false'}}
+      data-depth={{this.depth}}
+      data-test-pretui-panel-section
+      ...attributes
+    >
+      {{#if @title}}
+        <div class='pretui-section-head'>
+          <div class='pretui-section-heading' role='heading' aria-level={{this.level}}>
+            {{#if this.collapsible}}
+              <button
+                type='button'
+                class='pretui-section-toggle'
+                aria-expanded={{if this.expanded 'true' 'false'}}
+                aria-controls={{this.regionId}}
+                aria-describedby={{if @summary this.summaryId}}
+                {{on 'click' this.toggle}}
+                data-test-pretui-section-toggle
+              >
+                <span class='pretui-section-chevron' aria-hidden='true'></span>
+                <span class='pretui-section-title'>{{@title}}</span>
+              </button>
+            {{else}}
+              <span class='pretui-section-static'>
+                <span class='pretui-section-title'>{{@title}}</span>
+              </span>
+            {{/if}}
+          </div>
+          {{#if @summary}}
+            <span class='pretui-section-summary' id={{this.summaryId}}>{{@summary}}</span>
+          {{/if}}
+          {{#if (has-block 'actions')}}
+            <span class='pretui-section-actions'>{{yield to='actions'}}</span>
+          {{/if}}
+        </div>
+      {{/if}}
+      <div
+        class='pretui-section-region'
+        id={{this.regionId}}
+        role='group'
+        aria-hidden={{unless this.expanded 'true'}}
+        inert={{unless this.expanded true}}
+      >
+        <div class='pretui-section-body'>{{yield}}</div>
+      </div>
+    </section>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-section {
+          display: block;
+          container-type: inline-size;
+          border-top: 1px solid var(--border);
+        }
+        .pretui-section:first-of-type {
+          border-top: 0;
+        }
+        .pretui-section-head {
+          display: flex;
+          align-items: center;
+          gap: var(--space-2, 6px);
+          min-height: 32px;
+          padding-inline: var(--space-4, 11px);
+        }
+        .pretui-section-heading {
+          flex: 1 1 auto;
+          min-width: 0;
+        }
+        .pretui-section-toggle,
+        .pretui-section-static {
+          display: flex;
+          align-items: center;
+          gap: 5px;
+          width: 100%;
+          min-height: 32px;
+          padding: 0;
+          border: 0;
+          background: transparent;
+          color: inherit;
+          text-align: start;
+          cursor: pointer;
+          font: inherit;
+        }
+        .pretui-section-static {
+          cursor: default;
+        }
+        .pretui-section-toggle:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: -1px;
+          border-radius: var(--radius-sm, 5px);
+        }
+        .pretui-section-title {
+          font-size: var(--text-ui-xs, 11px);
+          font-weight: 600;
+          letter-spacing: var(--track-eyebrow, 0.06em);
+          text-transform: uppercase;
+          color: var(--muted-foreground);
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+        }
+        .pretui-section-toggle:hover .pretui-section-title {
+          color: var(--foreground);
+        }
+        /* The chevron is a CSS triangle, not an icon component: it must sit
+           inside a role-bearing button, where remote lint's
+           require-presentational-children rejects any svg or component. */
+        .pretui-section-chevron {
+          flex: none;
+          width: 0;
+          height: 0;
+          margin-inline: 2px 1px;
+          border-inline-start: 4px solid currentColor;
+          border-block: 3.5px solid transparent;
+          color: var(--muted-foreground);
+          transform-origin: 25% 50%;
+          transition: transform var(--pretui-dur-snap, 160ms)
+            var(--pretui-ease-snap, ease);
+        }
+        .pretui-section[data-open='true'] .pretui-section-chevron {
+          transform: rotate(90deg);
+        }
+        .pretui-section-summary {
+          flex: none;
+          font-family: var(--font-mono);
+          font-size: var(--text-ui-xs, 11px);
+          color: var(--ink-3, var(--boxel-400));
+          font-variant-numeric: tabular-nums;
+        }
+        .pretui-section-actions {
+          flex: none;
+          display: flex;
+          align-items: center;
+          gap: 2px;
+        }
+        .pretui-section-region {
+          display: grid;
+          grid-template-rows: 1fr;
+          transition: grid-template-rows var(--pretui-dur-snap, 160ms)
+            var(--pretui-ease-snap, ease);
+        }
+        .pretui-section[data-open='false'] .pretui-section-region {
+          grid-template-rows: 0fr;
+        }
+        .pretui-section-region > .pretui-section-body {
+          overflow: hidden;
+          min-height: 0;
+        }
+        .pretui-section[data-open='true'] > .pretui-section-region
+          > .pretui-section-body {
+          /* Once open, stop clipping so a dropdown inside a row can escape. */
+          overflow: visible;
+          padding: 2px var(--space-4, 11px) var(--space-3, 8px);
+        }
+        .pretui-section[data-open='false'] .pretui-section-body {
+          padding-inline: var(--space-4, 11px);
+        }
+        /* ── Nested groups ────────────────────────────────────────────────
+           A group inside a group must not read as its peer. Upstream has no
+           representation for depth at all, and the source panel this was
+           checked against expressed it purely as left padding — which reads
+           as "slightly misaligned" rather than "contained". The hairline
+           goes (it is the peer separator), the heading stops shouting in
+           small-caps, and the body hangs off a vertical rule that makes the
+           containment visible in a still frame. */
+        .pretui-section:not([data-depth='0']) {
+          border-top: 0;
+          margin-block-start: 2px;
+        }
+        .pretui-section:not([data-depth='0']) .pretui-section-head {
+          min-height: 26px;
+          padding-inline: 0;
+        }
+        .pretui-section:not([data-depth='0']) .pretui-section-title {
+          font-size: var(--text-ui, 12px);
+          font-weight: 600;
+          letter-spacing: var(--track-ui, 0.01em);
+          text-transform: none;
+          color: var(--foreground);
+        }
+        .pretui-section:not([data-depth='0'])[data-open='true']
+          > .pretui-section-region
+          > .pretui-section-body {
+          padding: 1px 0 var(--space-2, 6px) var(--space-3, 8px);
+          margin-inline-start: 5px;
+          border-inline-start: 1px solid var(--border);
+        }
+        .pretui-section:not([data-depth='0'])[data-open='false']
+          .pretui-section-body {
+          padding-inline: 0;
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-section-region,
+          .pretui-section-chevron {
+            transition: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,48 @@
+## What it is
+
+A titled group inside a panel, optionally collapsible, with a nesting depth that reads in a still frame.
+
+## The contract
+
+```
+@title?       — section heading
+@level?       — heading level for the title, 2–6. Default 3 — a panel section sits
+                under the panel's own h2
+@collapsible? — false makes the section a plain titled group with no disclosure
+@open?, @defaultOpen? — controlled / uncontrolled. Default open
+@summary?     — small count shown after the title, e.g. "3 effects"
+@depth?       — 0 (default) is top-level; 1–3 mark a group nested INSIDE another
+<:default>    — the section body
+<:actions>    — header affordances beside the title (an add button, a menu)
+```
+
+**`@depth` is the arg worth understanding.** A nested group drops the peer hairline, de-shouts its heading out of small-caps, and hangs its body off a vertical rule — so the nesting is legible **in a still frame** rather than only while collapsing. Indentation alone compounds and stops meaning anything by the third level.
+
+**`@level` defaults to 3** because a panel section sits under the panel's own `h2`. It is separate from `@depth`: visual nesting and outline level are different questions, and a section can be visually nested without being a deeper heading.
+
+**`@collapsible={{false}}` makes it a plain titled group** — no button, no disclosure, just a heading and content.
+
+## Prior art
+
+The inspector section in design tools and the accordion section in kits.
+
+Where Pretui is better: separating depth from heading level, and making depth legible at rest. Most implementations convey nesting by indentation only, which is invisible in a screenshot and meaningless past two levels.
+
+Where it is thinner: no drag-to-reorder, and depth capped at 3.
+
+## Accessibility
+
+- **The heading is a real heading at `@level`**, so a panel of sections has a navigable outline.
+- **`@depth` and `@level` being separate is the accessibility point**: a section can be visually nested without lying about the document structure, and vice versa.
+- **When collapsible, it is a full disclosure** — real button, `aria-expanded`, `aria-controls` — and when not, there is no control at all rather than a disabled one.
+- **`@summary` describes the toggle** through `aria-describedby`, so "Effects, 3 effects" arrives together. It sits outside the heading, so the outline lists the title alone.
+- **A closed section is `inert`** as well as `aria-hidden`, so Tab never lands on a control nobody can see.
+- **Default open is the right default** for a panel: content that starts hidden is content many readers never find.
+
+## Theming
+
+The section takes the kit's border, heading and surface tokens; depth changes which of them apply rather than introducing new ones.
+
+That is what keeps a nested section recognisably the same component as a top-level one — it is quieter, not different.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,137 @@
+// Pretui — PanelSection usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { PanelSection } from './panel-section';
+import { PropertyRow } from './property-row';
+import { ScrubInput } from './scrub-input';
+
+// ── PanelSection ─────────────────────────────────────────────────────────
+class PanelSectionUsage extends Component {
+  @tracked title = 'Layout';
+  @tracked summary = '3 rules';
+  @tracked collapsible = true;
+  @tracked open = true;
+
+  setTitle = (v: string) => (this.title = v);
+  setSummary = (v: string) => (this.summary = v);
+  setCollapsible = (v: boolean) => (this.collapsible = v);
+  toggled = (v: boolean) => (this.open = v);
+
+  @tracked width: number | null = 320;
+  @tracked height: number | null = 180;
+  setWidth = (v: number | null) => (this.width = v);
+  setHeight = (v: number | null) => (this.height = v);
+
+  get usage() {
+    return (
+      "<PanelSection @title='" +
+      this.title +
+      "' @summary='" +
+      this.summary +
+      "'>\n  <PropertyRow … />\n</PanelSection>"
+    );
+  }
+  <template>
+    <FreestyleUsage
+      @name='PanelSection'
+      @description='A titled, collapsible group of property rows — the workhorse of an inspector. Ported from figui3 fig-group, with three fixes: the disclosure is a real button (so header actions stay clickable, which upstream’s whole-header click target swallows), the chevron is aria-hidden outside the heading text, and the collapse is a 0fr→1fr grid transition that needs no height measurement and lands on the end state under prefers-reduced-motion.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='pretui-section-demo'>
+          <PanelSection
+            @title={{this.title}}
+            @summary={{this.summary}}
+            @collapsible={{this.collapsible}}
+            @open={{this.open}}
+            @onToggle={{this.toggled}}
+          >
+            <PropertyRow @label='Width' as |controlId|>
+              <ScrubInput
+                @controlId={{controlId}}
+                @label='Width'
+                @value={{this.width}}
+                @unit='px'
+                @precision={{0}}
+                @steppers={{true}}
+                @onInput={{this.setWidth}}
+              />
+            </PropertyRow>
+            <PropertyRow @label='Height' as |controlId|>
+              <ScrubInput
+                @controlId={{controlId}}
+                @label='Height'
+                @value={{this.height}}
+                @unit='px'
+                @precision={{0}}
+                @steppers={{true}}
+                @onInput={{this.setHeight}}
+              />
+            </PropertyRow>
+          </PanelSection>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='title'
+          @value={{this.title}}
+          @description='Section heading. Rendered as the accessible name of the disclosure button.'
+          @onInput={{this.setTitle}}
+        />
+        <Args.String
+          @name='summary'
+          @value={{this.summary}}
+          @description='Mono count/summary after the title — “3 effects”, “2 selected”.'
+          @onInput={{this.setSummary}}
+        />
+        <Args.Bool
+          @name='collapsible'
+          @defaultValue={{true}}
+          @value={{this.collapsible}}
+          @description='false makes it a plain titled group with no disclosure.'
+          @onInput={{this.setCollapsible}}
+        />
+        <Args.Bool
+          @name='open'
+          @description='CONTROLLED open state. Omit to let the section own it (see @defaultOpen).'
+        />
+        <Args.Bool
+          @name='defaultOpen'
+          @defaultValue={{true}}
+          @description='Initial state when uncontrolled.'
+        />
+        <Args.Number
+          @name='level'
+          @defaultValue={{3}}
+          @description='Heading level 2–6 for the title; a panel section sits under the panel’s own h2.'
+        />
+        <Args.Number
+          @name='depth'
+          @defaultValue={{0}}
+          @description='0 is a top-level group; 1–3 mark a group nested INSIDE another (a Person inside a Subject). It drops the peer hairline, takes the heading out of small-caps, and hangs the body off a vertical rule, so the containment is legible in a still frame. Indentation compounds from the parent’s own body padding — this supplies the treatment, not the offset. See the composed inspector.'
+        />
+        <Args.Action
+          @name='onToggle'
+          @description='Receives the next open state.'
+        />
+        <Args.Yield
+          @description='Default block is the section body. The actions block rides in the header, outside the disclosure button.'
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-section-demo {
+        max-width: 300px;
+        border-radius: var(--radius-surface, 10px);
+        background: var(--card);
+        box-shadow: var(--pretui-shadow-card, 0 0 0 1px var(--border));
+        overflow: hidden;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_PANEL_SECTION: Record<string, unknown> = {
+  PanelSection: PanelSectionUsage,
+};

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

@@ -0,0 +1,158 @@
+// Pretui — Panel: the titled surface that frames a region, with optional eyebrow, meta and action.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+
+export interface PanelSignature {
+  Args: {
+    title?: string;
+    eyebrow?: string;
+    /**
+     * 'card' (default) is the reading surface: padded body, header floating
+     * on the same ground. 'inspector' is the design-tool shell ported from
+     * figui3's `fig-header` / `fig-content` / `fig-footer` trio — flush
+     * body so `PanelSection` hairlines run edge to edge, a header and
+     * footer separated by hairlines, and a container context so the
+     * `PropertyRow` fold resolves against the panel rather than the page.
+     */
+    variant?: 'card' | 'inspector';
+    /**
+     * Scroll the body instead of growing. The caller supplies the height
+     * (`style='height: 100%'`, a grid row, a fixed rail); this only makes
+     * the body the part that scrolls, with header and footer pinned.
+     */
+    scroll?: boolean;
+  };
+  Blocks: {
+    default: [];
+    /** replaces the generated title header entirely — for a header that
+     * carries controls (a target picker, a close button) */
+    header: [];
+    status: [];
+    actions: [];
+  };
+  Element: HTMLElement;
+}
+
+// The system signature: body + hairline + action bar (status left, actions right).
+export const Panel: TemplateOnlyComponent<PanelSignature> = <template>
+  <section
+    class='pretui-panel'
+    data-variant={{if @variant @variant 'card'}}
+    data-scroll={{if @scroll 'true'}}
+    data-test-pretui-panel
+    ...attributes
+  >
+    {{#if (has-block 'header')}}
+      <header class='pretui-panel-header'>{{yield to='header'}}</header>
+    {{else if @title}}
+      <header class='pretui-panel-header'>
+        {{#if @eyebrow}}<span class='pretui-eyebrow'>{{@eyebrow}}</span>{{/if}}
+        <h2>{{@title}}</h2>
+      </header>
+    {{/if}}
+    <div class='pretui-panel-body'>{{yield}}</div>
+    {{! Defect fixed 2026-08-13: the footer was gated on the `status` block
+        alone, so a Panel supplying only <:actions> rendered no footer and
+        silently dropped its buttons. }}
+    {{#if (has-block 'status')}}
+      <footer class='pretui-panel-footer'>
+        <span class='pretui-panel-status'>{{yield to='status'}}</span>
+        <span class='pretui-panel-actions'>{{yield to='actions'}}</span>
+      </footer>
+    {{else if (has-block 'actions')}}
+      <footer class='pretui-panel-footer'>
+        <span class='pretui-panel-status'></span>
+        <span class='pretui-panel-actions'>{{yield to='actions'}}</span>
+      </footer>
+    {{/if}}
+  </section>
+  <style scoped>
+    @layer PretComponent {
+      .pretui-panel {
+        background: var(--card);
+        border-radius: var(--radius-surface, 10px);
+        box-shadow: var(--pretui-shadow-card, 0 0 0 1px var(--border));
+        display: flex;
+        flex-direction: column;
+        overflow: hidden;
+      }
+      .pretui-panel-header {
+        padding: var(--space-4, 11px) var(--space-5, 14px) 0;
+        display: grid;
+        gap: 2px;
+      }
+      .pretui-panel-header h2 {
+        margin: 0;
+        font-size: var(--text-body, 15px);
+        font-weight: 600;
+        letter-spacing: var(--track-heading, -0.02em);
+      }
+      .pretui-eyebrow {
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        font-weight: 500;
+        letter-spacing: var(--track-eyebrow, 0.08em);
+        text-transform: uppercase;
+        color: var(--muted-foreground);
+      }
+      .pretui-panel-body {
+        padding: var(--space-5, 14px);
+      }
+      .pretui-panel-footer {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: var(--space-3, 8px);
+        padding: var(--space-3, 8px) var(--space-5, 14px);
+        box-shadow: 0 -1px 0 var(--border);
+      }
+      .pretui-panel-status {
+        font-size: var(--text-ui, 12px);
+        color: var(--muted-foreground);
+        display: flex;
+        align-items: center;
+        gap: 6px;
+      }
+      .pretui-panel-actions {
+        display: flex;
+        align-items: center;
+        gap: var(--space-3, 8px);
+      }
+      /* ── inspector variant (design-tools shell) ───────────────────────── */
+      .pretui-panel[data-variant='inspector'] {
+        /* An inspector's rows fold against the PANEL width, never the
+           viewport. Unnamed container only — a named one silently deletes
+           every rule after it in the transpiled sheet. */
+        container-type: inline-size;
+      }
+      .pretui-panel[data-variant='inspector'] .pretui-panel-header {
+        padding: var(--space-3, 8px) var(--space-4, 11px);
+        box-shadow: 0 1px 0 var(--border);
+      }
+      .pretui-panel[data-variant='inspector'] .pretui-panel-header h2 {
+        font-size: var(--text-ui-md, 12.5px);
+      }
+      /* Flush, so PanelSection hairlines run edge to edge. */
+      .pretui-panel[data-variant='inspector'] .pretui-panel-body {
+        padding: 0;
+      }
+      .pretui-panel[data-variant='inspector'] .pretui-panel-footer {
+        padding: var(--space-2, 6px) var(--space-4, 11px);
+      }
+      /* ── scrolling body ───────────────────────────────────────────────── */
+      .pretui-panel[data-scroll='true'] {
+        min-height: 0;
+      }
+      .pretui-panel[data-scroll='true'] .pretui-panel-header,
+      .pretui-panel[data-scroll='true'] .pretui-panel-footer {
+        flex: none;
+      }
+      .pretui-panel[data-scroll='true'] .pretui-panel-body {
+        flex: 1 1 auto;
+        min-height: 0;
+        overflow-y: auto;
+        overscroll-behavior: contain;
+        scrollbar-gutter: stable;
+      }
+    }
+  </style>
+</template>;