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

package/bundled-realms/pretui/components/float-button.usage.gts

@@ -0,0 +1,134 @@
+// Pretui — FloatButton usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { FloatButton } from './float-button';
+import type { FloatButtonAction } from './float-button';
+
+const PLACEMENT_OPTIONS = ['bottom-end', 'bottom-start', 'top-end', 'top-start'];
+const INBOX = [
+  'Lot 7 roast profile approved',
+  'Invoice 1042 paid',
+  'Cupping notes from Tuesday',
+  'Green coffee arrival: Huila',
+  'Label proofs for the spring blend',
+  'Warehouse count reconciled',
+];
+
+export class FloatButtonUsage extends Component {
+  placementOptions = PLACEMENT_OPTIONS;
+  inbox = INBOX;
+  @tracked label = 'Compose';
+  @tracked extended = false;
+  @tracked placement = 'bottom-end';
+  @tracked dial = true;
+  @tracked last = '';
+  setLabel = (v: string) => (this.label = v);
+  setExtended = (v: boolean) => (this.extended = v);
+  setPlacement = (v: string) => (this.placement = v);
+  setDial = (v: boolean) => (this.dial = v);
+  onAction = () => (this.last = 'Compose');
+  actions: FloatButtonAction[] = [
+    { id: 'note', label: 'New note', onSelect: () => (this.last = 'New note') },
+    { id: 'task', label: 'New task', onSelect: () => (this.last = 'New task') },
+    { id: 'lot', label: 'New lot', onSelect: () => (this.last = 'New lot') },
+  ];
+  get actionsArg() {
+    return this.dial ? this.actions : undefined;
+  }
+  get usage() {
+    let bits = [`@label='${this.label}'`];
+    if (this.extended) bits.push('@extended={{true}}');
+    if (this.placement !== 'bottom-end') bits.push(`@placement='${this.placement}'`);
+    bits.push(this.dial ? '@actions={{this.actions}}' : '@onAction={{this.compose}}');
+    return `<div style='position: relative'>\n  …the pane…\n  <FloatButton ${bits.join(' ')} />\n</div>`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='FloatButton'
+      @description='The primary action of a long pane, pinned to a corner of the pane rather than the viewport. With @actions it becomes a speed dial: a disclosure that opens a list of labelled actions. Fab is the same component under the MUI name.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='fb-demo-pane'>
+          <ul class='fb-demo-list'>
+            {{#each this.inbox as |line|}}<li>{{line}}</li>{{/each}}
+          </ul>
+          <FloatButton
+            @label={{this.label}}
+            @extended={{this.extended}}
+            @placement={{this.placement}}
+            @actions={{this.actionsArg}}
+            @onAction={{this.onAction}}
+          />
+        </div>
+        {{#if this.last}}<p class='fb-demo-last'>Last chosen: {{this.last}}</p>{{/if}}
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='label'
+          @required={{true}}
+          @value={{this.label}}
+          @description='The accessible name, and the visible text when extended.'
+          @onInput={{this.setLabel}}
+        />
+        <Args.Bool
+          @name='extended'
+          @defaultValue={{false}}
+          @value={{this.extended}}
+          @description='Show the label beside the icon.'
+          @onInput={{this.setExtended}}
+        />
+        <Args.String
+          @name='placement'
+          @value={{this.placement}}
+          @options={{this.placementOptions}}
+          @defaultValue='bottom-end'
+          @description='The corner. Logical, so RTL flips it; bottom-right and friends map.'
+          @onInput={{this.setPlacement}}
+        />
+        <Args.String @name='position' @defaultValue='absolute' @description='absolute anchors to the nearest positioned ancestor; fixed to the viewport.' />
+        <Args.String @name='tone' @defaultValue='primary' @description='The button tone.' />
+        <Args.String @name='size' @defaultValue='m' @description='s, m or l.' />
+        <Args.Bool
+          @name='actions'
+          @value={{this.dial}}
+          @description='Toggle the speed dial in this demo. In code, an array of { id, label, onSelect }.'
+          @onInput={{this.setDial}}
+        />
+        <Args.Action @name='onAction' @description='Fired by the button when there are no actions.' />
+        <Args.Bool @name='open' @description='Controlled dial state; omit for uncontrolled.' />
+        <Args.Action @name='onOpenChange' @description='Reports every open or close request.' />
+        <Args.Yield @name='default' @description='The icon. Defaults to a plus.' />
+        <Args.Yield @name='actionIcon' @description='The icon for one dial action, yielded the action.' />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .fb-demo-pane {
+        position: relative;
+        block-size: 16rem;
+        overflow: auto;
+        border-radius: var(--radius-surface, 10px);
+        box-shadow: 0 0 0 1px var(--border);
+        background: var(--card);
+      }
+      .fb-demo-list {
+        margin: 0;
+        padding: var(--space-3, 0.5rem) var(--space-4, 0.6875rem);
+        list-style: none;
+        display: grid;
+        gap: var(--space-3, 0.5rem);
+        font-size: var(--text-ui-md, 0.78rem);
+      }
+      .fb-demo-last {
+        margin: var(--space-2, 0.375rem) 0 0;
+        font-size: var(--text-ui-sm, 0.72rem);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_FLOAT_BUTTON: Record<string, unknown> = {
+  FloatButton: FloatButtonUsage,
+};

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

@@ -0,0 +1,86 @@
+// Pretui — Fold: settled work folded to receipt counts; indentation encodes containment only.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+
+export interface FoldSignature {
+  Args: {
+    receipt: string;
+    defaultOpen?: boolean;
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+  };
+  Blocks: { default: [] };
+  Element: HTMLDivElement;
+}
+
+// THE FOLD — indentation encodes containment only, never importance.
+// One step = 14px under a hairline rail; settled work folds to counts.
+export class Fold extends Component<FoldSignature> {
+  @tracked internal = this.args.defaultOpen ?? false;
+  get open() {
+    return this.args.open ?? this.internal;
+  }
+  toggle = () => {
+    let next = !this.open;
+    if (this.args.open === undefined) {
+      this.internal = next;
+    }
+    this.args.onOpenChange?.(next);
+  };
+  <template>
+    <div class='pretui-fold' data-fold={{if this.open 'open' 'folded'}} data-test-pretui-fold ...attributes>
+      <button type='button' class='pretui-collapsed' aria-expanded={{if this.open 'true' 'false'}} {{on 'click' this.toggle}}>
+        <span class='pretui-fold-mark' data-open={{if this.open 'true'}}>{{if this.open '▾' '✓'}}</span>{{@receipt}}
+      </button>
+      {{#if this.open}}
+        <div class='pretui-fold-children'>{{yield}}</div>
+      {{/if}}
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-fold {
+          display: grid;
+          gap: 0;
+        }
+        .pretui-collapsed {
+          display: inline-flex;
+          align-items: center;
+          gap: 7px;
+          height: 24px;
+          padding: 0 calc(5px * var(--pretui-capsule-base, 1.35) + 12px * var(--pretui-radius-encroach, 0.35));
+          border-radius: 12px;
+          border: 0;
+          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;
+          font-variant-numeric: tabular-nums;
+          justify-self: start;
+        }
+        .pretui-collapsed:hover {
+          background: var(--hover, var(--boxel-100));
+        }
+        .pretui-fold-mark {
+          color: var(--success, var(--boxel-success));
+        }
+        .pretui-fold-mark[data-open] {
+          color: var(--muted-foreground);
+        }
+        .pretui-fold-children {
+          margin-left: 7px;
+          margin-top: 6px;
+          padding-left: 14px;
+          box-shadow: inset 1px 0 0 var(--border);
+          display: grid;
+          gap: 6px;
+        }
+        .pretui-fold-children :deep(.pretui-fold-children) {
+          box-shadow: inset 1px 0 0 var(--line-strong, var(--boxel-400));
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,54 @@
+## What it is
+
+The fold: a disclosure whose indentation encodes **containment only, never importance**. Use it to nest agent work — a run containing actions containing steps — and to collapse settled work down to its receipt. This is the territory's structural primitive; **WorkItem** is what goes inside it.
+
+## The contract
+
+```
+@receipt: string   (required)
+@defaultOpen? (default false), @open?, @onOpenChange?(open: boolean)
+<:default>
+```
+
+Hybrid controlled/uncontrolled, the kit-wide idiom.
+
+**`@receipt` is required, and it is the collapsed representation.** A Fold is not "a chevron and some hidden content" — it is a receipt line that can be expanded into the work behind it. That inversion is the point: a settled transcript is a column of receipts, and the receipts are readable on their own. A disclosure with no summary would make a folded transcript a column of chevrons.
+
+**Default closed.** Agent work accumulates; a transcript that expands everything by default is unusable after ten minutes.
+
+**One step of nesting is 14px under a hairline rail** (`box-shadow: inset 1px 0 0 --border`, `padding-left: 14px`, `margin-left: 7px`). Nested Folds switch the rail to `--line-strong`, so depth is legible without the indent growing large enough to squeeze the content. That restraint is the fold law in CSS: 14px says "contained by", and nothing says "more important than".
+
+## Prior art
+
+**APG's Disclosure** is the governing pattern and is deliberately minimal: a button with `aria-expanded`, Enter/Space to toggle, and _no_ arrow keys, no roving tabindex, no focus management — the whole keyboard contract is Tab and Enter/Space.
+
+**Radix `Collapsible`** is `Root`/`Trigger`/`Content` with `open`/`onOpenChange`/`disabled` and a `--radix-collapsible-content-height` for animation. **Web Awesome `wa-details`** wraps a real `<details>`/`<summary>` with `open`, `summary`, `name` grouping, `appearance` and `icon-placement`. **Pretui's own Accordion** wraps boxel-ui's grid-rows disclosure engine.
+
+So there are now **three disclosure mechanisms in this kit** — `Fold`, `Accordion`, and `FormSection` — and it is worth being clear about why, because it looks like duplication. `Accordion` is a group with a shared open policy; `FormSection` is a fieldset that knows about validation and can open itself; `Fold` is a single containment step with a required receipt and a rail. They are different components, but the _disclosure_ part is written three times, and consolidating that onto one primitive would be a real improvement.
+
+Where Fold is better than `<details>`: the receipt is a first-class arg rather than a `<summary>` you might forget, and the rail makes nesting legible. Where it is behind: `<details>` gives you the platform's semantics and Ctrl+F expansion for free.
+
+## Accessibility
+
+Governing pattern: APG **Disclosure**.
+
+What is right: the trigger is a real `<button>` carrying **`aria-expanded`**, which is the pattern's one required property, and Enter/Space toggle it natively. No arrow keys and no roving tabindex — correctly, since the pattern has neither.
+
+Gaps:
+
+- **No `aria-controls`** pointing at the content region. Optional in APG, but it is the only thing that tells assistive tech _what_ expands, and it is one attribute.
+- **The receipt is the button's content, so it is the accessible name** — which is good, and means the announcement is "3 files changed, collapsed button". Verify no glyph is concatenated into it.
+- **The nesting rail conveys containment visually and nothing conveys it programmatically.** A Fold inside a Fold is announced as a button followed by content followed by another button; the containment that 14px of indent makes obvious to a sighted user is invisible. Nested `role="group"`s with labels, or a real list structure, would carry it. For a territory whose central law is "indentation encodes containment", not expressing that containment in the accessibility tree is the notable gap.
+- **The expansion is not announced beyond `aria-expanded` being re-read.** Content appearing below a button is discoverable by continuing to read, which is adequate.
+- **Content is presumably removed from the DOM when closed** (a `{{#if}}`), so its controls are correctly unreachable — unlike **FormSection**, which keeps them registered on purpose. Know which you are using.
+- **Deep nesting compounds tab stops**: every Fold is a tab stop, so a run with thirty folded steps is thirty tab stops before the next thing.
+
+## Theming
+
+`--border` (the first-level rail), `--line-strong` (nested rails), plus the receipt's ink (`--muted-foreground` or `--foreground` depending on state) and the kit's type scale.
+
+The 14px indent, 7px offset and 1px rail are fixed — deliberately, since they _are_ the fold law rather than decoration. A theme should not increase the indent to make nesting more obvious; the two-tone rail is the intended mechanism, and the rails are the tokens to adjust.
+
+Check `--line-strong` against `--border` per theme: at two levels of nesting the rails are the only depth cue, and if the two tokens converge, a nested Fold looks identical to a sibling.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,19 @@
+// Pretui — Fold usage page.
+import Component from '@glimmer/component';
+import { FreestyleUsage } from './freestyle-usage';
+import { Fold } from './fold';
+import { ResultCard } from './result-card';
+
+class FoldUsage extends Component {
+  <template>
+    <FreestyleUsage @name='Fold' @description='Agent work that collapses to a receipt while preserving containment through one hairline indentation step.' @source='<Fold @receipt="Inspected 4 linked cards">…</Fold>'>
+      <:example><Fold @receipt='Inspected 4 linked cards' @defaultOpen={{true}}><ResultCard @eyebrow='Inspection' @title='No broken links' @lines={{this.lines}} /></Fold></:example>
+      <:api as |Args|><Args.String @name='receipt' @value='Inspected 4 linked cards' /><Args.Bool @name='defaultOpen' @value={{true}} /><Args.Bool @name='open' /><Args.Action @name='onOpenChange' /><Args.Yield @name='default' /></:api>
+    </FreestyleUsage>
+  </template>
+  lines = ['4 references resolved', '0 missing cards'];
+}
+
+export const DEMOS_FOLD: Record<string, unknown> = {
+  Fold: FoldUsage,
+};