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

package/bundled-realms/pretui/components/json-tree.usage.gts

@@ -0,0 +1,217 @@
+// Pretui — JsonTree usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { JsonTree } from './json-tree';
+import { SAMPLE } from '../demo-json';
+
+/** 300 items, so the page shows truncation rather than describing it. */
+function longArrayDocument(): string {
+  const items: string[] = [];
+  for (let i = 1; i <= 300; i++) {
+    items.push('{ "n": ' + String(i) + ', "sku": "SKU-' + String(1000 + i) + '" }');
+  }
+  return '{\n  "catalogue": [\n    ' + items.join(',\n    ') + '\n  ]\n}';
+}
+
+const LONG = longArrayDocument();
+
+const BROKEN = '{\n  "a": 1,\n  "b": [2, 3,]\n}';
+
+const PARTIAL = '{\n  "a": ';
+
+const DUPLICATED = '{ "a": 1, "b": 2, "a": 3 }';
+
+class JsonTreeUsage extends Component {
+  @tracked source = 'sample';
+  @tracked query = '';
+  @tracked label = 'Order SO-4471';
+  @tracked expandAll = true;
+  @tracked hideToolbar = false;
+  @tracked pageSize = 25;
+  @tracked picked = 'nothing selected yet';
+
+  setSource = (v: string) => (this.source = v);
+  setQuery = (v: string) => (this.query = v);
+  setLabel = (v: string) => (this.label = v);
+  setExpandAll = (v: boolean) => (this.expandAll = v);
+  setHideToolbar = (v: boolean) => (this.hideToolbar = v);
+  setPageSize = (v: number) => (this.pageSize = v);
+
+  sourceOptions = ['sample', 'long array', 'malformed', 'half-typed', 'duplicate keys'];
+
+  get json(): string {
+    if (this.source === 'long array') {
+      return LONG;
+    }
+    if (this.source === 'malformed') {
+      return BROKEN;
+    }
+    if (this.source === 'half-typed') {
+      return PARTIAL;
+    }
+    if (this.source === 'duplicate keys') {
+      return DUPLICATED;
+    }
+    return SAMPLE;
+  }
+
+  onSelect = (_node: unknown, path: ReadonlyArray<string | number>) => {
+    this.picked = path.length === 0 ? '$ (the root)' : path.join(' › ');
+  };
+
+  get usage(): string {
+    const bits = ['@json={{this.json}}', `@label='${this.label}'`];
+    if (this.expandAll) {
+      bits.push('@expandAll={{true}}');
+    }
+    if (this.query !== '') {
+      bits.push(`@query='${this.query}'`);
+    }
+    if (this.pageSize !== 100) {
+      bits.push(`@pageSize={{${this.pageSize}}}`);
+    }
+    if (this.hideToolbar) {
+      bits.push('@hideToolbar={{true}}');
+    }
+    bits.push('@onSelect={{this.onSelect}}');
+    return `<JsonTree\n  ${bits.join('\n  ')}\n/>`;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='JsonTree'
+      @description='A read-only JSON document as a WAI-ARIA treeview. Every
+      value carries a type badge, containers carry a child count, and long
+      containers truncate with an explicit "Showing N of M" row you can press
+      Enter on to see more — a viewer that renders 50,000 rows is not a
+      viewer. Keyboard: Up/Down move, Right expands then descends, Left
+      collapses then climbs, Home/End jump, * expands every sibling at the
+      level, single-character type-ahead cycles through property names, and
+      Ctrl/Cmd+C copies the focused value while Ctrl/Cmd+Shift+C copies its
+      path. Numbers keep their SOURCE TEXT, so an id beyond 2^53 is displayed
+      and copied exactly rather than silently rounded, and the document warns
+      you when that happens. Duplicate property names are kept and reported
+      rather than dropped the way JSON.parse drops them. Honest limits: the
+      row actions are pointer affordances rather than buttons (a button inside
+      a treeitem is nested-interactive ARIA), which is why the copy keyboard
+      shortcuts exist; long containers truncate rather than virtualize,
+      because virtualization needs measurement timers this realm forbids and
+      an honest count beats a scrollbar that lies; and there is no inline
+      syntax highlighting of raw text — this is a structural view.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='jd-stack'>
+          <JsonTree
+            @json={{this.json}}
+            @label={{this.label}}
+            @expandAll={{this.expandAll}}
+            @query={{this.query}}
+            @pageSize={{this.pageSize}}
+            @hideToolbar={{this.hideToolbar}}
+            @onSelect={{this.onSelect}}
+          />
+          <p class='jd-readout'>Selected: {{this.picked}}</p>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='json'
+          @value={{this.source}}
+          @options={{this.sourceOptions}}
+          @defaultValue='sample'
+          @description='The document as text. Switch between a well-formed
+          order, a 300-item catalogue that truncates, a malformed document, a
+          half-typed one, and one with duplicate keys.'
+          @onInput={{this.setSource}}
+        />
+        <Args.Object
+          @name='value'
+          @description='The document as a plain JavaScript value, when you
+          have data rather than text. @json wins when both are set.'
+          @hideControls={{true}}
+        />
+        <Args.String
+          @name='label'
+          @value={{this.label}}
+          @defaultValue='JSON document'
+          @description='Accessible name for the tree, and the toolbar caption.'
+          @onInput={{this.setLabel}}
+        />
+        <Args.String
+          @name='query'
+          @value={{this.query}}
+          @description='Case-insensitive filter over property names and scalar
+          values. Matches pull their ancestors open without disturbing your own
+          expansion state — clearing the query restores exactly what you had.'
+          @onInput={{this.setQuery}}
+        />
+        <Args.Bool
+          @name='expandAll'
+          @value={{this.expandAll}}
+          @defaultValue={{false}}
+          @description='Open every container on first render.'
+          @onInput={{this.setExpandAll}}
+        />
+        <Args.Number
+          @name='pageSize'
+          @value={{this.pageSize}}
+          @min={{5}}
+          @max={{200}}
+          @step={{5}}
+          @defaultValue={{100}}
+          @description='Children rendered per container before truncating.'
+          @onInput={{this.setPageSize}}
+        />
+        <Args.Bool
+          @name='hideToolbar'
+          @value={{this.hideToolbar}}
+          @defaultValue={{false}}
+          @description='Hide the name, match count and expand/collapse buttons.'
+          @onInput={{this.setHideToolbar}}
+        />
+        <Args.Array
+          @name='defaultExpanded'
+          @description='Container paths open on first render.'
+          @hideControls={{true}}
+        />
+        <Args.Action
+          @name='onSelect'
+          @description='Fires with the node and its path on Enter, Space or click.'
+          @hideControls={{true}}
+        />
+        <Args.Action
+          @name='onParseError'
+          @description='Fires with every diagnostic when @json will not parse.
+          Called from a modifier rather than a getter, so a caller may safely
+          write tracked state in it.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @name=':empty'
+          @description='Replaces the default EmptyState.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+
+    <style scoped>
+      .jd-stack {
+        display: flex;
+        flex-direction: column;
+        gap: var(--space-3, 8px);
+      }
+      .jd-readout {
+        margin: 0;
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_JSON_TREE: Record<string, unknown> = {
+  JsonTree: JsonTreeUsage,
+};

package/bundled-realms/pretui/components/jump-chip.gts

@@ -0,0 +1,230 @@
+// Pretui — JumpChip: scroll orientation for a growing stream, plus the scrollEdge measurement modifier it pairs with.
+import Component from '@glimmer/component';
+import { on } from '@ember/modifier';
+import { modifier } from 'ember-modifier';
+
+// ── scrollEdge ───────────────────────────────────────────────────────────
+// The measurement JumpChip needs, and the reason the chip is not merely
+// decorative: a passive `scroll` listener on the transcript that reports
+// **only when the answer changes**. Reporting every frame is what makes a
+// naive version of this re-render a list on every wheel tick; the boolean
+// latch means a full scroll to the bottom produces exactly one state write.
+//
+// It is an `ember-modifier`, so the listener is removed in the destructor.
+// No timer is involved at any point — a re-arming debounce here would block
+// `await settled()` and hang the whole test suite.
+export const scrollEdge = modifier(
+  (
+    el: HTMLElement,
+    [onChange]: [(atEnd: boolean, element: HTMLElement) => void],
+    named: { threshold?: number },
+  ) => {
+    let threshold = named.threshold ?? 24;
+    let last: boolean | undefined;
+    let report = () => {
+      let distance = el.scrollHeight - el.clientHeight - el.scrollTop;
+      let atEnd = distance <= threshold;
+      if (atEnd !== last) {
+        last = atEnd;
+        onChange(atEnd, el);
+      }
+    };
+    el.addEventListener('scroll', report, { passive: true });
+    report();
+    return () => el.removeEventListener('scroll', report);
+  },
+);
+
+// ── JumpChip ─────────────────────────────────────────────────────────────
+// Scroll orientation for a stream that grows while you are reading it. Two
+// jobs in one control, distinguished by whether anything arrived: "3 new
+// messages" when it did, "Back to bottom" when it did not.
+//
+// Presentational by contract — the caller owns the scroller and decides when
+// the chip is warranted (`scrollEdge` above is the measurement, offered
+// separately so a caller with their own virtualiser can ignore it). The chip
+// positions itself against the nearest positioned ancestor, which is stated
+// here because it is the one thing a caller must do for it to land right.
+
+export interface JumpChipSignature {
+  Args: {
+    /** whether the chip is offered at all */
+    visible?: boolean;
+    /**
+     * items that arrived while the reader was away. Non-zero switches the
+     * chip to its "new message" voice and shows the count.
+     */
+    count?: number;
+    /** override the derived label entirely */
+    label?: string;
+    /** which way the jump goes (default 'down') */
+    direction?: 'down' | 'up';
+    /** fires when the reader takes the jump */
+    onJump?: () => void;
+  };
+  Element: HTMLDivElement;
+}
+
+export class JumpChip extends Component<JumpChipSignature> {
+  get count(): number {
+    return this.args.count ?? 0;
+  }
+  get direction(): 'down' | 'up' {
+    return this.args.direction ?? 'down';
+  }
+  get visible(): boolean {
+    return this.args.visible ?? true;
+  }
+  get isNews(): boolean {
+    return this.count > 0;
+  }
+  get label(): string {
+    if (this.args.label) {
+      return this.args.label;
+    }
+    if (this.isNews) {
+      return this.count === 1 ? '1 new message' : this.count + ' new messages';
+    }
+    return this.direction === 'up' ? 'Back to top' : 'Back to bottom';
+  }
+
+  jump = () => this.args.onJump?.();
+
+  <template>
+    <div
+      class='pretui-jump'
+      data-visible={{if this.visible 'true'}}
+      data-direction={{this.direction}}
+      data-news={{if this.isNews 'true'}}
+      inert={{unless this.visible true}}
+      data-test-pretui-jump-chip
+      ...attributes
+    >
+      <button
+        type='button'
+        class='pretui-jump-btn'
+        data-test-pretui-jump-chip-button
+        {{on 'click' this.jump}}
+      >
+        <svg viewBox='0 0 24 24' aria-hidden='true' focusable='false'>
+          <path
+            d='M12 5v14M6 13l6 6 6-6'
+            fill='none'
+            stroke='currentColor'
+            stroke-width='2.2'
+            stroke-linecap='round'
+            stroke-linejoin='round'
+          />
+        </svg>
+        <span>{{this.label}}</span>
+      </button>
+    </div>
+
+    <style scoped>
+      @layer PretComponent {
+        /* absolute against the caller's positioned scroll frame — stated in the
+           docs because it is the one thing the caller must provide */
+        .pretui-jump {
+          position: absolute;
+          inset-inline: 0;
+          bottom: var(--pretui-jump-offset, 12px);
+          display: flex;
+          justify-content: center;
+          pointer-events: none;
+          z-index: var(--pretui-z-sticky, 10);
+        }
+        .pretui-jump[data-direction='up'] {
+          bottom: auto;
+          top: var(--pretui-jump-offset, 12px);
+        }
+        .pretui-jump-btn {
+          display: inline-flex;
+          align-items: center;
+          gap: 7px;
+          min-height: 30px;
+          padding: 0 13px;
+          border: 0;
+          border-radius: 999px;
+          background: var(--card);
+          box-shadow: var(
+            --pretui-shadow-overlay,
+            0 0 0 1px var(--border),
+            0 8px 28px rgb(0 0 0 / 0.18)
+          );
+          font: inherit;
+          font-size: var(--text-ui-sm, 11.5px);
+          font-weight: 500;
+          color: var(--foreground);
+          cursor: pointer;
+          pointer-events: auto;
+          opacity: 0;
+          transform: translateY(8px) scale(0.96);
+          transition:
+            opacity 180ms ease-out,
+            transform 220ms
+              var(--pretui-ease-enter, cubic-bezier(0.22, 0.61, 0.25, 1));
+        }
+        .pretui-jump[data-visible] .pretui-jump-btn {
+          opacity: 1;
+          transform: none;
+        }
+        /* hidden means hidden: no pointer events, no tab stop, no hit area */
+        .pretui-jump:not([data-visible]) .pretui-jump-btn {
+          pointer-events: none;
+          visibility: hidden;
+          transition:
+            opacity 180ms ease-out,
+            transform 220ms ease-out,
+            visibility 0s linear 220ms;
+        }
+        .pretui-jump-btn:hover {
+          background: var(--hover, var(--boxel-100));
+        }
+        .pretui-jump-btn:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 2px;
+        }
+        .pretui-jump-btn > svg {
+          width: 13px;
+          height: 13px;
+          flex: none;
+          color: var(--ink-3, var(--boxel-400));
+        }
+        .pretui-jump[data-direction='up'] .pretui-jump-btn > svg {
+          transform: rotate(180deg);
+        }
+        /* news is never colour alone — the count is in the label */
+        .pretui-jump[data-news] .pretui-jump-btn {
+          background: color-mix(
+            in oklch,
+            var(--primary) 12%,
+            var(--card)
+          );
+          box-shadow:
+            0 0 0 1px
+              color-mix(in oklch, var(--primary) 45%, var(--border)),
+            0 8px 28px rgb(0 0 0 / 0.18);
+        }
+        .pretui-jump[data-news] .pretui-jump-btn > svg {
+          color: color-mix(
+            in oklch,
+            var(--foreground) 18%,
+            var(--primary)
+          );
+        }
+        @media (any-pointer: coarse) {
+          .pretui-jump-btn {
+            min-height: 44px;
+            padding: 0 18px;
+          }
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-jump-btn {
+            transition: none;
+            transform: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/jump-chip.md

@@ -0,0 +1,44 @@
+## What it is
+
+The "jump to latest" chip: a floating control that appears when the reader has scrolled away from the live end of a transcript, and counts what arrived while they were gone.
+
+## The contract
+
+```
+@visible?   — whether the chip is offered at all
+@count?     — items that arrived while the reader was away. Non-zero switches the
+              chip to its "new message" voice and shows the count
+@label?     — override the derived label entirely
+@direction? — which way the jump goes. Default 'down'
+@onJump?    — fires when the reader takes the jump
+```
+
+**`@count` changes the chip's voice, not just its text.** Zero means "you have scrolled up"; non-zero means "things happened" — two different reasons to jump, and conflating them makes the chip either alarming or invisible.
+
+**The chip does not decide when to show itself.** `@visible` is the caller's, because whether the reader is "away" depends on a scroll position the transcript owns.
+
+**`@direction` exists because a transcript is not always bottom-anchored.**
+
+## Prior art
+
+The jump-to-latest affordance in every chat product.
+
+Where Pretui is better: not much — this is a small component and the value is in it being one component rather than a bespoke floating div per surface. The count-versus-no-count voice split is the one design decision worth keeping.
+
+Where it is thinner: no auto-hide on reaching the end (the caller flips `@visible`), no unread marker in the transcript itself, and no per-kind counting — "3 new" rather than "2 messages, 1 tool call".
+
+## Accessibility
+
+- **It is a real button**, reachable by keyboard, which matters more than it sounds: a floating pointer-only affordance leaves a keyboard user with no way back to the live end except scrolling.
+- **The label carries the count** when there is one, so the reason to jump is in the accessible name rather than in a badge.
+- **The glyph is `aria-hidden` with `focusable='false'`.**
+- **Appearing is not announced.** The chip arriving is not news worth interrupting a reader for — it is an affordance they will find when they want it.
+- **`@label` overrides the derived text entirely**, which is the escape hatch for a surface where "jump to latest" is the wrong phrase.
+
+## Theming
+
+The chip takes the kit's shared control and elevation tokens, floating at the raised layer.
+
+There is no jump-chip-specific surface, which keeps it reading as a control belonging to the transcript rather than as an overlay on top of it.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/jump-chip.usage.gts

@@ -0,0 +1,151 @@
+// Pretui — JumpChip usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { Button } from './button';
+import { JumpChip, scrollEdge } from './jump-chip';
+
+// ── JumpChip ─────────────────────────────────────────────────────────────
+const STREAM = [
+  'Pulled the Kandy auction catalogue — 18 lots.',
+  'Lot 104 scores 84.1; below the 2025 mean once freight is netted out.',
+  'Lot 118 scores 88.6 and is still unsold.',
+  'Checked the 2024 comparables: 118 cleared at 12% over the mean.',
+  'Freight from Colombo is quoted flat this quarter, so the netting holds.',
+  'Rewrote the pricing rule to filter on unsold status.',
+  'Re-ran the valuation: 118 clears at 9.4% over.',
+  'Drafted the buying note.',
+  'Attached the contract for signature.',
+  'Waiting on your approval before the bid goes in.',
+];
+
+class JumpChipUsage extends GlimmerComponent {
+  @tracked atEnd = true;
+  @tracked news = 3;
+  private scroller?: HTMLElement;
+
+  setNews = (n: number) => (this.news = n);
+
+  get visible(): boolean {
+    return !this.atEnd || this.news > 0;
+  }
+
+  // One boolean latch, reported only when the answer changes — a scroll
+  // handler that wrote on every event would re-render the list on every
+  // wheel tick.
+  edgeChanged = (atEnd: boolean, element: HTMLElement) => {
+    this.atEnd = atEnd;
+    this.scroller = element;
+    if (atEnd) {
+      this.news = 0;
+    }
+  };
+
+  jump = () => {
+    let element = this.scroller;
+    if (!element) {
+      return;
+    }
+    element.scrollTop = element.scrollHeight;
+    this.news = 0;
+  };
+
+  addNews = () => (this.news = this.news + 1);
+
+  <template>
+    <FreestyleUsage
+      @name='JumpChip'
+      @description='Scroll orientation for a stream that grows while you are reading it, doing two jobs in one control: "3 new messages" when something arrived, "Back to bottom" when nothing did. It is presentational by contract — the caller owns the scroller — but the measurement ships beside it as `scrollEdge`, an ember-modifier that attaches ONE passive scroll listener and reports only when the at-the-bottom answer changes. That boolean latch is the whole design: a handler that wrote state on every scroll event would re-render the transcript on every wheel tick, and a debounce would be a re-arming timer, which a realm forbids. The chip positions itself against the nearest positioned ancestor; give the scroll frame `position: relative` and it lands.'
+    >
+      <:example>
+        <div class='demo-frame'>
+          <div
+            class='demo-scroll'
+            {{scrollEdge this.edgeChanged threshold=16}}
+          >
+            {{#each STREAM as |line|}}
+              <p class='demo-line'>{{line}}</p>
+            {{/each}}
+          </div>
+          <JumpChip
+            @visible={{this.visible}}
+            @count={{this.news}}
+            @onJump={{this.jump}}
+          />
+        </div>
+        <p class='demo-hint'>Scroll up in the frame and the chip appears;
+          scroll back down and it leaves. “New message” adds to the count and
+          switches the chip to its news voice — reaching the bottom clears it.</p>
+        <Button
+          @tone='neutral'
+          @appearance='outlined'
+          @size='s'
+          {{on 'click' this.addNews}}
+        >New message</Button>
+      </:example>
+      <:api as |Args|>
+        <Args.Bool
+          @name='visible'
+          @description='Whether the chip is offered. Hidden means hidden: no pointer events, no tab stop, no hit area — the whole chip goes inert.'
+          @value={{this.visible}}
+          @hideControls={{true}}
+        />
+        <Args.Number
+          @name='count'
+          @description='Items that arrived while the reader was away. Non-zero switches the chip to its news voice and puts the number in the label — never in colour alone.'
+          @value={{this.news}}
+          @onInput={{this.setNews}}
+          @defaultValue={{0}}
+          @min={{0}}
+          @max={{9}}
+        />
+        <Args.Base
+          @name='label / direction / onJump'
+          @description='The @label arg overrides the derived wording entirely. @direction flips the chip to the top edge and rotates its arrow, for a stream that grows upward.'
+          @hideControls={{true}}
+        />
+        <Args.Base
+          @name='scrollEdge (modifier)'
+          @description='Applied as a modifier on the scroll container, with an onChange handler and an optional threshold (default 24px). onChange receives (atEnd, element) — the element comes with it so the caller can scroll it later without a second ref mechanism. The listener is passive and is removed in the modifier’s destructor.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .demo-frame {
+        position: relative;
+        border-radius: 12px;
+        overflow: hidden;
+        box-shadow: var(
+          --pretui-shadow-hairline,
+          0 0 0 1px var(--border)
+        );
+      }
+      .demo-scroll {
+        height: 11rem;
+        overflow-y: auto;
+        padding: 12px 14px;
+        background: var(--card);
+      }
+      .demo-line {
+        margin: 0 0 10px;
+        max-width: 62ch;
+        font-size: var(--text-ui-md, 12.5px);
+        line-height: 1.6;
+        color: var(--muted-foreground);
+      }
+      .demo-hint {
+        margin: var(--space-4, 11px) 0 var(--space-3, 7px);
+        max-width: 62ch;
+        font-size: var(--text-ui-sm, 11.5px);
+        line-height: 1.6;
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_JUMP_CHIP: Record<string, unknown> = {
+  JumpChip: JumpChipUsage,
+};