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

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

@@ -0,0 +1,47 @@
+// Pretui — Disclosure usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Disclosure } from './disclosure';
+
+class DisclosureUsage extends Component {
+  @tracked open = false;
+  setOpen = (v: boolean) => (this.open = v);
+  <template>
+    <FreestyleUsage
+      @name='Disclosure'
+      @description='Collapsible under the React Aria name: one trigger, one disclosed region. Reach for this import when a port or an agent already speaks the Aria vocabulary; the component, its contract and its writeup are Collapsible’s.'
+      @source="<Disclosure @label='Grading notes' @open={{this.open}} @onOpenChange={{this.setOpen}}>…</Disclosure>"
+    >
+      <:example>
+        <Disclosure
+          @label='Grading notes'
+          @open={{this.open}}
+          @onOpenChange={{this.setOpen}}
+        >
+          <p class='pretui-demo-readout'>Leaf is even and tightly rolled, with a
+            bright liquor and no astringency at the finish.</p>
+        </Disclosure>
+      </:example>
+      <:api as |Args|>
+        <Args.Bool
+          @name='open'
+          @description='Controlled state; leave undefined for the uncontrolled half. Aria’s isExpanded.'
+          @value={{this.open}}
+          @onInput={{this.setOpen}}
+        />
+        <Args.Action
+          @name='onOpenChange'
+          @description='Fires with the next state on every toggle. Aria’s onExpandedChange.'
+        />
+        <Args.String @name='label' @value='Grading notes' />
+        <Args.Yield @name='trigger' @description='Replaces @label; yielded the open state.' />
+        <Args.Yield @name='default' @description='The disclosed region.' />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_DISCLOSURE: Record<string, unknown> = {
+  Disclosure: DisclosureUsage,
+};

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

@@ -0,0 +1,75 @@
+// Pretui — Divider: a semantic separator rule, optionally labelled.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+
+// Transcribed from wa-divider: a semantic role='separator' rule for
+// grouping adjacent content, horizontal or vertical, one hairline token
+// (--border). Adds the centered-label variant WA doesn't ship (the
+// 'OR' rule between form alternatives) — horizontal only; a vertical
+// divider ignores @label. WA's --color/--width/--spacing knobs collapse
+// to --pretui-divider-spacing; the hairline color IS the token.
+
+export interface DividerSignature {
+  Args: {
+    orientation?: 'horizontal' | 'vertical';
+    /** centered label — horizontal orientation only */
+    label?: string;
+  };
+  Element: HTMLDivElement;
+}
+
+function orientationOf(o: string | undefined): 'horizontal' | 'vertical' {
+  return o === 'vertical' ? 'vertical' : 'horizontal';
+}
+
+export const Divider: TemplateOnlyComponent<DividerSignature> = <template>
+  <div
+    class='pretui-divider'
+    role='separator'
+    aria-orientation={{orientationOf @orientation}}
+    aria-label={{@label}}
+    data-orientation={{orientationOf @orientation}}
+    data-test-pretui-divider
+    ...attributes
+  >
+    {{#if @label}}
+      <span class='pretui-divider-label'>{{@label}}</span>
+    {{/if}}
+  </div>
+  <style scoped>
+    @layer PretComponent {
+      .pretui-divider {
+        --pretui-divider-spacing: var(--space-4, 11px);
+      }
+      .pretui-divider[data-orientation='horizontal'] {
+        display: flex;
+        align-items: center;
+        margin: var(--pretui-divider-spacing) 0;
+      }
+      .pretui-divider[data-orientation='horizontal']::before,
+      .pretui-divider[data-orientation='horizontal']::after {
+        content: '';
+        flex: 1;
+        height: 1px;
+        background: var(--border);
+      }
+      .pretui-divider-label {
+        padding: 0 8px;
+        font-size: var(--text-ui-sm, 11.5px);
+        letter-spacing: var(--track-ui, 0.01em);
+        color: var(--muted-foreground);
+        white-space: nowrap;
+      }
+      .pretui-divider[data-orientation='vertical'] {
+        display: inline-block;
+        width: 1px;
+        align-self: stretch;
+        min-height: 1lh;
+        background: var(--border);
+        margin: 0 var(--pretui-divider-spacing);
+      }
+      .pretui-divider[data-orientation='vertical'] .pretui-divider-label {
+        display: none;
+      }
+    }
+  </style>
+</template>;

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

@@ -0,0 +1,49 @@
+## What it is
+
+A semantic separator between groups of adjacent content, horizontal or vertical, plus the centred-label variant — the "or" rule between two form alternatives — that every product page hand-rolls.
+
+It is the kit's smallest component, and it earns its slot by ending ad-hoc `<hr>` styling: one rule, one hairline token, one spacing token, restyled by a theme with no code. If you want a labeled boundary that also collapses its content, that is **PanelSection**; if you want spacing without a rule, that is layout, not this.
+
+## The contract
+
+```
+@orientation? — 'horizontal' (default) | 'vertical'
+@label?       — centred label; horizontal only
+```
+
+Two args, no state, no script.
+
+**It is always a `<div role='separator'>`, never an `<hr>`.** The role and `aria-orientation` are set explicitly rather than inherited from the element, which is what lets one component serve both orientations without swapping tags.
+
+**The horizontal rule is drawn by two flanking pseudo-elements, not by a border.** `::before` and `::after` each take `flex: 1`, so with no label they meet in the middle and read as a single line, and with a label they become the two hairlines either side of it. That is why the label needs no background to punch a hole in the rule — there is no rule under it to hide.
+
+**A vertical divider ignores `@label`.** The label span is hidden, and the rule is a 1px column with `min-height: 1lh` so it has a height even between two short inline items.
+
+**Spacing is one token, applied as a margin on the axis that matters** — block margins when horizontal, inline when vertical.
+
+## Prior art
+
+Transcribed from **Web Awesome's `wa-divider`**, with **React Spectrum's `Divider`** as the second reference; shadcn and Radix call the same thing `Separator` and take `orientation` and `decorative`.
+
+Where Pretui is better: **the centred-label variant is built in.** Neither upstream ships it, and it is the one divider anybody actually hand-writes. Web Awesome's three custom properties — `--color`, `--width`, `--spacing` — collapse to a single `--pretui-divider-spacing`, because the hairline colour _is_ the `--border` token and a divider that does not match every other hairline in the product is a bug rather than a feature.
+
+Where it is thinner, and these are real: **there is no `decorative` escape hatch.** Radix and Web Awesome both let a purely visual rule drop its separator semantics, and this one cannot — every divider is announced. **There is no width or size axis**: the hairline is 1px, full stop, where Spectrum offers a scale. **There are no inset or full-bleed presets** for list contexts, so a divider inside a padded list has to be positioned by its container. And **a vertical divider cannot be labelled**, which is correct for the layout but is a silent drop rather than a typed constraint.
+
+## Accessibility
+
+`role='separator'` with an explicit `aria-orientation` is the right shape, and the ARIA note that both upstreams follow. Three things are worth knowing:
+
+- **Every divider is announced, including purely decorative ones.** With no `decorative` arg, a rule used for visual rhythm rather than grouping still reaches the accessibility tree. A page that uses several as ornament will announce several separators, and the only remedy today is `aria-hidden='true'` passed through `...attributes` at the call site.
+- **`@label` becomes `aria-label` on the separator itself**, so a labelled rule announces as "or, separator" rather than as loose text — which is the intent.
+- **A vertical divider with a `@label` keeps that `aria-label` while hiding the text.** The name is announced but never visible, which is a mismatch between what a sighted and a non-sighted user perceive. Passing `@label` to a vertical divider is a call-site mistake the component does not report.
+- **A separator with a role is not focusable and takes no tab stop**, which is correct: `role='separator'` is only focusable when it is a splitter you can move, and this one never is.
+
+## Theming
+
+`--pretui-divider-spacing` (the margin on the divider's axis, defaulting to `--space-4`, 11px), `--border` (the hairline, in both orientations), `--muted-foreground` (the label ink), `--text-ui-sm` (11.5px), `--track-ui` (the label's letter-spacing).
+
+The 1px thickness, the 8px padding either side of the label and the vertical rule's `1lh` minimum height are fixed.
+
+A theme changes the density of every divider in the product through `--pretui-divider-spacing` alone, and its color through `--border` — which is shared, so dividers cannot drift away from the hairlines on cards, inputs and tables. That sharing is the deliberate trade: the kit gives up a per-divider color knob to guarantee that every hairline in a theme matches.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,98 @@
+// Pretui — Divider usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Divider } from './divider';
+import { ORIENTATIONS } from '../internal/composites-fixtures';
+
+// ── Divider ← wa-divider ─────────────────────────────────────────────────
+// Dropped knobs: --color/--width (the hairline IS the --border token; one
+// spacing knob survives as --pretui-divider-spacing). Added: the centered
+// @label variant WA doesn't ship — horizontal only; vertical ignores it.
+class DividerUsage extends Component {
+  orientationOptions = ORIENTATIONS;
+  @tracked orientation = 'horizontal';
+  @tracked labelText = 'or';
+  setOrientation = (v: string) => (this.orientation = v);
+  setLabel = (v: string) => (this.labelText = v);
+  get orientationVal() {
+    return this.orientation as 'horizontal' | 'vertical';
+  }
+  get isVertical() {
+    return this.orientation === 'vertical';
+  }
+  get usage() {
+    let bits: string[] = [];
+    if (this.orientation !== 'horizontal')
+      bits.push(`@orientation='${this.orientation}'`);
+    if (this.labelText && !this.isVertical)
+      bits.push(`@label='${this.labelText}'`);
+    return `<Divider${bits.length ? ' ' + bits.join(' ') : ''} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Divider'
+      @description="Semantic role='separator' rule for grouping adjacent content — one hairline riding the --border token, horizontal or vertical. The centered label variant (the 'or' between form alternatives) is a Pretui addition over wa-divider."
+      @source={{this.usage}}
+    >
+      <:example>
+        {{#if this.isVertical}}
+          <div class='pretui-divider-demo-row'>
+            <span>Continue with email</span>
+            <Divider @orientation='vertical' />
+            <span>Continue with SSO</span>
+          </div>
+        {{else}}
+          <div class='pretui-divider-demo-col'>
+            <span>Continue with email</span>
+            <Divider @label={{this.labelText}} />
+            <span>Continue with SSO</span>
+          </div>
+        {{/if}}
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='orientation'
+          @defaultValue='horizontal'
+          @value={{this.orientation}}
+          @options={{this.orientationOptions}}
+          @description='Line direction; aria-orientation follows.'
+          @onInput={{this.setOrientation}}
+        />
+        <Args.String
+          @name='label'
+          @value={{this.labelText}}
+          @description='Centered label — horizontal orientation only; a vertical divider ignores it.'
+          @onInput={{this.setLabel}}
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-divider-spacing'
+          @type='length'
+          @description="Margin along the divider's cross axis — WA's --spacing knob, defaulting to the --space-4 token."
+        />
+      </:cssVars>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-divider-demo-row {
+        display: flex;
+        align-items: stretch;
+        font-size: var(--text-ui-md, 12.5px);
+        color: var(--muted-foreground);
+      }
+      .pretui-divider-demo-row > span {
+        align-self: center;
+      }
+      .pretui-divider-demo-col {
+        display: block;
+        font-size: var(--text-ui-md, 12.5px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_DIVIDER: Record<string, unknown> = {
+  Divider: DividerUsage,
+};

package/bundled-realms/pretui/components/doc-report.gts

@@ -0,0 +1,306 @@
+// Pretui — DocReport: a rich agent deliverable, capped and expandable, with previewable card pills.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { fn } from '@ember/helper';
+import { guidFor } from '@ember/object/internals';
+import { Button } from './button';
+import { Prose } from './prose';
+import { Tooltip } from './tooltip';
+import { iconFor } from '../icon-registry';
+
+// ── DocReport ────────────────────────────────────────────────────────────
+// The deliverable at the end of a research run: a document, not a chat
+// message. Two things make it a component rather than a `<div>` of prose —
+// it is capped so a 4000-word report cannot swallow the transcript, and the
+// cards it cites are pills you can preview without leaving the report.
+//
+// The body is a slot, never a string: a report is markdown, tables, embedded
+// cards, whatever the run produced (Law 7). `Prose` supplies the reading
+// measure and the inline-code treatment; `Tooltip` supplies the pill preview
+// and, being CSS-only on hover AND focus-within, works from the keyboard —
+// which the design mirror's hover-only fit-preview did not.
+
+export interface DocCard {
+  /** stable id — the {{#each}} key */
+  id: string;
+  /** the pill face */
+  label: string;
+  /** one line shown in the preview */
+  summary?: string;
+  /** boxel-ui icon export name, resolved through icon-registry */
+  icon?: string;
+}
+
+export interface DocReportSignature {
+  Args: {
+    /** the report's title */
+    title: string;
+    /** small caps line above the title, e.g. 'Research · 12 sources' */
+    eyebrow?: string;
+    /** short facts rendered as a machine-value strip under the title */
+    meta?: string[];
+    /** the cards this report cites */
+    cards?: DocCard[];
+    /** fires when a card pill is activated */
+    onOpenCard?: (card: DocCard) => void;
+    /** controlled expansion */
+    expanded?: boolean;
+    /** starting expansion when uncontrolled */
+    defaultExpanded?: boolean;
+    /** fires with the requested expansion */
+    onExpandedChange?: (expanded: boolean) => void;
+    /** expand-button wording (default 'Full report') */
+    expandLabel?: string;
+    /** collapse-button wording (default 'Collapse') */
+    collapseLabel?: string;
+  };
+  Blocks: {
+    /** the report body */
+    default: [];
+    /** actions in the header, right of the title */
+    actions: [];
+  };
+  Element: HTMLElement;
+}
+
+export class DocReport extends Component<DocReportSignature> {
+  @tracked private innerExpanded?: boolean;
+
+  private bodyId = guidFor(this) + '-body';
+
+  get expanded(): boolean {
+    return (
+      this.args.expanded ?? this.innerExpanded ?? this.args.defaultExpanded ?? false
+    );
+  }
+  get toggleLabel(): string {
+    return this.expanded
+      ? (this.args.collapseLabel ?? 'Collapse')
+      : (this.args.expandLabel ?? 'Full report');
+  }
+  get cards(): DocCard[] {
+    return this.args.cards ?? [];
+  }
+  get meta(): string[] {
+    return this.args.meta ?? [];
+  }
+
+  toggle = () => {
+    let next = !this.expanded;
+    if (this.args.expanded === undefined) {
+      this.innerExpanded = next;
+    }
+    this.args.onExpandedChange?.(next);
+  };
+
+  openCard = (card: DocCard) => this.args.onOpenCard?.(card);
+
+  <template>
+    <article
+      class='pretui-doc'
+      data-expanded={{if this.expanded 'true'}}
+      data-test-pretui-doc-report
+      ...attributes
+    >
+      <header class='pretui-doc-head'>
+        <div class='pretui-doc-titles'>
+          {{#if @eyebrow}}
+            <span class='pretui-doc-eyebrow'>{{@eyebrow}}</span>
+          {{/if}}
+          <h3 class='pretui-doc-title'>{{@title}}</h3>
+        </div>
+        {{yield to='actions'}}
+      </header>
+
+      {{#if this.meta.length}}
+        <ul class='pretui-doc-meta' aria-label='Report facts'>
+          {{#each this.meta as |fact|}}
+            <li><code>{{fact}}</code></li>
+          {{/each}}
+        </ul>
+      {{/if}}
+
+      <div class='pretui-doc-clip' id={{this.bodyId}}>
+        <Prose>{{yield}}</Prose>
+      </div>
+
+      <div class='pretui-doc-foot'>
+        <Button
+          @tone='neutral'
+          @appearance='outlined'
+          @size='s'
+          aria-expanded={{if this.expanded 'true' 'false'}}
+          aria-controls={{this.bodyId}}
+          data-test-pretui-doc-report-toggle
+          {{on 'click' this.toggle}}
+        >{{this.toggleLabel}}</Button>
+
+        {{#if this.cards.length}}
+          <ul class='pretui-doc-pills' aria-label='Cards cited'>
+            {{#each this.cards key='id' as |card|}}
+              <li>
+                <Tooltip @content={{if card.summary card.summary card.label}}>
+                  <button
+                    type='button'
+                    class='pretui-doc-pill'
+                    data-test-pretui-doc-report-pill
+                    {{on 'click' (fn this.openCard card)}}
+                  >
+                    {{#let (iconFor card.icon) as |CardIcon|}}
+                      {{#if CardIcon}}
+                        <CardIcon
+                          class='pretui-doc-pill-icon'
+                          role='presentation'
+                        />
+                      {{/if}}
+                    {{/let}}
+                    <span>{{card.label}}</span>
+                  </button>
+                </Tooltip>
+              </li>
+            {{/each}}
+          </ul>
+        {{/if}}
+      </div>
+    </article>
+
+    <style scoped>
+      @layer PretComponent {
+        .pretui-doc {
+          display: flex;
+          flex-direction: column;
+          gap: var(--space-3, 9px);
+          padding: var(--space-4, 13px);
+          border-radius: var(--radius-surface, 14px);
+          background: var(--card);
+          box-shadow: var(
+            --pretui-shadow-card,
+            0 0 0 1px var(--border),
+            0 1px 2px rgb(0 0 0 / 0.08)
+          );
+        }
+        .pretui-doc-head {
+          display: flex;
+          align-items: flex-start;
+          gap: 10px;
+        }
+        .pretui-doc-titles {
+          flex: 1;
+          min-width: 0;
+        }
+        .pretui-doc-eyebrow {
+          display: block;
+          font-family: var(--font-mono);
+          font-size: 10px;
+          font-weight: 600;
+          letter-spacing: 0.06em;
+          text-transform: uppercase;
+          color: var(--ink-3, var(--boxel-400));
+        }
+        .pretui-doc-title {
+          margin: 2px 0 0;
+          font-size: 15px;
+          font-weight: 600;
+          letter-spacing: -0.02em;
+        }
+        .pretui-doc-meta {
+          display: flex;
+          flex-wrap: wrap;
+          gap: 6px;
+          margin: 0;
+          padding: 0;
+          list-style: none;
+        }
+        .pretui-doc-meta code {
+          font-family: var(--font-mono);
+          font-size: 11px;
+          padding: 1px 6px;
+          border-radius: 5px;
+          background: var(--inset, var(--boxel-100));
+          box-shadow: var(
+            --pretui-shadow-hairline,
+            0 0 0 1px var(--border)
+          );
+          color: var(--muted-foreground);
+          font-variant-numeric: tabular-nums;
+        }
+        /* the cap: content beyond it is clipped and faded out, so the reader
+           can see that there IS more rather than guessing */
+        .pretui-doc-clip {
+          font-size: var(--text-ui-md, 12.5px);
+          max-height: var(--pretui-doc-cap, 16rem);
+          overflow: hidden;
+          mask-image: linear-gradient(
+            to bottom,
+            #000 0,
+            #000 calc(100% - 3rem),
+            transparent 100%
+          );
+          transition: mask-image 200ms linear;
+        }
+        .pretui-doc[data-expanded] .pretui-doc-clip {
+          max-height: none;
+          overflow: visible;
+          mask-image: none;
+        }
+        .pretui-doc-foot {
+          display: flex;
+          align-items: center;
+          gap: 10px;
+          flex-wrap: wrap;
+        }
+        .pretui-doc-pills {
+          display: flex;
+          flex-wrap: wrap;
+          gap: 5px;
+          margin: 0;
+          padding: 0;
+          list-style: none;
+        }
+        .pretui-doc-pill {
+          display: inline-flex;
+          align-items: center;
+          gap: 5px;
+          min-height: 24px;
+          padding: 0 9px;
+          border: 0;
+          border-radius: 999px;
+          background: var(--inset, var(--boxel-100));
+          box-shadow: var(
+            --pretui-shadow-hairline,
+            0 0 0 1px var(--border)
+          );
+          font: inherit;
+          font-size: var(--text-ui-sm, 11.5px);
+          color: var(--muted-foreground);
+          cursor: pointer;
+        }
+        .pretui-doc-pill:hover {
+          background: var(--hover, var(--boxel-100));
+          color: var(--foreground);
+        }
+        .pretui-doc-pill:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 2px;
+        }
+        .pretui-doc-pill-icon {
+          width: 12px;
+          height: 12px;
+          flex: none;
+        }
+        @media (any-pointer: coarse) {
+          .pretui-doc-pill {
+            min-height: 44px;
+            padding: 0 14px;
+          }
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-doc-clip {
+            transition: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/doc-report.md

@@ -0,0 +1,45 @@
+## What it is
+
+The agent's written output as a document: a title, an eyebrow, a strip of machine facts, the cards it cited, and a full-report disclosure.
+
+## The contract
+
+```
+@title (required) — the report's title
+@eyebrow?    — small-caps line above the title, e.g. 'Research · 12 sources'
+@meta?       — short facts rendered as a machine-value strip under the title
+@cards?      — the cards this report cites
+@onOpenCard? — fires when a card pill is activated
+@expanded?, @defaultExpanded?, @onExpandedChange? — the disclosure
+@expandLabel?, @collapseLabel? — wording. Defaults 'Full report' / 'Collapse'
+```
+
+**The cited cards are pills, not links in prose.** A report that cites twelve things should let you reach any of them without reading for the reference, and `@onOpenCard` is how the host routes that.
+
+**`@meta` is a machine-value strip**, rendered in the **Token** treatment — counts, durations, model names — which keeps them scannable and distinct from the prose.
+
+**The disclosure is the whole report**, so a transcript holds a summary until someone wants the rest.
+
+## Prior art
+
+The research-report surfaces in agent products.
+
+Where Pretui is better: citations as first-class pills with an open callback, rather than as inline links the host cannot intercept. That is what lets a report's sources open in the right place in a workspace rather than navigating away.
+
+Where it is thinner: no inline citation markers tying a sentence to a source, no export, and no section navigation within a long report.
+
+## Accessibility
+
+- **The disclosure is the kit's**, so collapsed content is inert and the relationship is wired from self-minted ids.
+- **The title is a real heading**, so a report is findable in a transcript by heading navigation — which is the primary way a screen-reader user moves through a long session.
+- **Card pills are buttons with their own names**, so the citations are reachable and distinguishable rather than being a row of identical chips.
+- **`@meta` is text**, announced after the title, so the facts about the report are available without opening it.
+- **`@eyebrow` is context, not a heading** — it sits above the title without competing with it in the outline.
+
+## Theming
+
+The report takes the kit's block spacing, heading and **Token** treatments; the card pills are **RecordPill**-shaped.
+
+Nothing here is separately themeable, which is right for a component whose job is to look like a document inside an application that already has a type scale.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.