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

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

@@ -0,0 +1,238 @@
+// Pretui — Masonry usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Masonry } from './masonry';
+import { StatusChip } from './status-chip';
+import { Token } from './token';
+
+// ── Masonry ← react-masonry-css and the JS masonry engines ───────────────
+// Cupping notes of deliberately uneven length — the only content shape that
+// makes a masonry worth having. The page's whole job is to be honest about
+// reading order, so the description says it and the example proves it: the
+// cards are numbered in DOM order, and you can watch 1-2-3 run DOWN the
+// first column rather than across the top.
+interface TastingNote {
+  id: string;
+  n: number;
+  tea: string;
+  place: string;
+  score: string;
+  body: string;
+}
+
+const NOTES: TastingNote[] = [
+  {
+    id: 'n1',
+    n: 1,
+    tea: 'Da Hong Pao',
+    place: 'Wuyishan',
+    score: '93',
+    body: 'Charcoal and stone fruit, a long mineral finish that outlasts the cup. Third infusion is the one to sell on.',
+  },
+  {
+    id: 'n2',
+    n: 2,
+    tea: 'Gyokuro',
+    place: 'Uji',
+    score: '95',
+    body: 'Sweet, thick, almost broth-like at 50°C. Pushed past 60°C it turns green and bitter within a single steep, which is worth writing on the tin because half the returns last season were people brewing it like sencha.',
+  },
+  {
+    id: 'n3',
+    n: 3,
+    tea: 'Silver Needle',
+    place: 'Fuding',
+    score: '88',
+    body: 'Quiet. Melon and hay.',
+  },
+  {
+    id: 'n4',
+    n: 4,
+    tea: 'Aged Shou Pu-erh',
+    place: 'Yiwu',
+    score: '91',
+    body: 'Damp cellar on the nose, then dates and wet wood. Stored in the separate room since March; the humidity log shows one excursion in June that did not reach the leaf.',
+  },
+  {
+    id: 'n5',
+    n: 5,
+    tea: 'Keemun Hao Ya',
+    place: 'Anxi',
+    score: '84',
+    body: 'Cocoa and a little smoke. House-blend band, not ceremonial.',
+  },
+  {
+    id: 'n6',
+    n: 6,
+    tea: 'Jasmine Dragon Pearls',
+    place: 'Hangzhou',
+    score: '89',
+    body: 'Seven scentings, and it shows — the jasmine sits on top of the tea instead of in it. Best cold-brewed, which nobody expects from a scented green.',
+  },
+  {
+    id: 'n7',
+    n: 7,
+    tea: 'Milk Oolong',
+    place: 'Alishan',
+    score: '86',
+    body: 'Buttery, short. Reliable rather than interesting.',
+  },
+  {
+    id: 'n8',
+    n: 8,
+    tea: 'Lapsang Souchong',
+    place: 'Wuyishan',
+    score: '90',
+    body: 'Pine smoke over a sweet base, and the base survives it. The only lot this season that people either love or return.',
+  },
+];
+
+class MasonryUsage extends Component {
+  notes = NOTES;
+
+  @tracked columns: number | null = 3;
+  @tracked min = '14rem';
+  @tracked gap: number | null = 14;
+
+  setColumns = (v: number | null) => (this.columns = v);
+  setMin = (v: string) => (this.min = v);
+  setGap = (v: number | null) => (this.gap = v);
+
+  get columnsVal() {
+    return this.columns ?? undefined;
+  }
+  get gapVal() {
+    return this.gap ?? undefined;
+  }
+  get usage() {
+    let bits = ['@items={{this.notes}}'];
+    if (this.columns !== null && this.columns !== 3) {
+      bits.push(`@columns={{${this.columns}}}`);
+    }
+    if (this.min !== '16rem') bits.push(`@min='${this.min}'`);
+    if (this.gap !== null && this.gap !== 14) bits.push(`@gap={{${this.gap}}}`);
+    return `<Masonry ${bits.join(' ')}>\n  <:item as |item|>…</:item>\n</Masonry>`;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='Masonry'
+      @description="A staggered wall of unequal-height cards — moodboards, galleries, cupping notes — with no measuring engine at all. It is native CSS multi-column, so it costs zero JavaScript, zero per-child measurement and zero re-layout on resize. READING ORDER IS THE TRAP, so read this before reaching for it: DOM order, keyboard order and screen-reader order are always the order you pass @items, and never move. The VISUAL order is COLUMN-MAJOR — card 1 is top-left, card 2 is BELOW it, and a column fills to the bottom before the next column starts. The example numbers each card so you can watch 1-2-3 run down the first column. That makes Masonry right for a wall of peers, where no card outranks another, and WRONG for ranked content where 'first' must read top-left then rightwards — use <Grid> for that, which is row-major. A JS masonry engine buys row-major fill at the price of measuring every child on every resize AND a DOM whose order no longer matches what anyone sees; this component refuses that trade and says so. Under a narrow container it collapses to one column, where the two orders coincide. Dropped from the JS originals: measured per-item placement, animated re-flow, and infinite-scroll integration (that is <Feed>'s job)."
+      @source={{this.usage}}
+    >
+      <:example>
+        <Masonry
+          @items={{this.notes}}
+          @columns={{this.columnsVal}}
+          @min={{this.min}}
+          @gap={{this.gapVal}}
+        >
+          <:item as |note|>
+            <article class='note'>
+              <div class='note-head'>
+                <span class='note-n'>{{note.n}}</span>
+                <h4 class='note-tea'>{{note.tea}}</h4>
+              </div>
+              <div class='note-meta'>
+                <Token @value={{note.place}} />
+                <StatusChip @value={{note.score}} />
+              </div>
+              <p class='note-body'>{{note.body}}</p>
+            </article>
+          </:item>
+        </Masonry>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='items'
+          @required={{true}}
+          @value={{this.notes}}
+          @description='The items to lay out. <Masonry> is generic over the row type, so they arrive in the <:item> block as whatever you passed in — this page hands it TastingNote[] and reads note.tea directly, with no cast. The component itself never reads inside an item.'
+        />
+        <Args.Number
+          @name='columns'
+          @value={{this.columns}}
+          @min={{1}}
+          @max={{6}}
+          @step={{1}}
+          @defaultValue={{3}}
+          @description='Maximum number of columns. The browser uses fewer whenever @min would not fit, so this is a ceiling, not a count.'
+          @onInput={{this.setColumns}}
+        />
+        <Args.String
+          @name='min'
+          @value={{this.min}}
+          @defaultValue='16rem'
+          @description='Minimum column width as a CSS length. Together with @columns it is the whole responsive story — there is no breakpoint list to maintain. Values that are not simple CSS lengths are ignored rather than injected.'
+          @onInput={{this.setMin}}
+        />
+        <Args.Number
+          @name='gap'
+          @value={{this.gap}}
+          @min={{0}}
+          @max={{40}}
+          @step={{1}}
+          @defaultValue={{14}}
+          @description='Gutter in px, applied to both the column gap and each cell’s bottom margin (multi-column has no row-gap). Also settable as --pretui-masonry-gap.'
+          @onInput={{this.setGap}}
+        />
+        <Args.Yield
+          @name=':item'
+          @description='Required. One cell — receives (item, index). The cell wrapper sets break-inside:avoid, so a card is never split across a column boundary.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .note {
+        display: grid;
+        gap: 6px;
+        padding: var(--space-4, 11px) 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)
+        );
+        min-width: 0;
+      }
+      .note-head {
+        display: flex;
+        align-items: baseline;
+        gap: 7px;
+        min-width: 0;
+      }
+      .note-n {
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        font-weight: 600;
+        color: var(--muted-foreground);
+        font-variant-numeric: tabular-nums;
+      }
+      .note-tea {
+        margin: 0;
+        font-size: var(--text-ui-md, 12.5px);
+        font-weight: 600;
+        color: var(--foreground);
+        min-width: 0;
+      }
+      .note-meta {
+        display: flex;
+        align-items: center;
+        flex-wrap: wrap;
+        gap: 5px;
+      }
+      .note-body {
+        margin: 0;
+        font-size: var(--text-ui-sm, 11.5px);
+        line-height: 1.5;
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_MASONRY: Record<string, unknown> = {
+  Masonry: MasonryUsage,
+};

package/bundled-realms/pretui/components/media-inspector.gts

@@ -0,0 +1,145 @@
+// Pretui — MediaInspector: the metadata panel for one asset, composed from KeyValue.
+import Component from '@glimmer/component';
+import { formatBytes, resolveAsset } from '../internal/media-viewer';
+import type { MediaAssetSpec, ResolvedMediaAsset } from '../internal/media-viewer';
+import { formatClock } from '../internal/reading-format';
+import { KeyValue } from './key-value';
+import type { KeyValueItem } from './key-value';
+import { Token } from './token';
+import { KIND_WORD } from '../internal/media-assets';
+
+// ── MediaInspector ───────────────────────────────────────────────────────
+//
+// The metadata panel. It composes KeyValue rather than growing its own definition list. The only
+// thing it adds is the derived row set: kind, dimensions, duration and size
+// are computed from the asset the same way the grid computes them, so the
+// panel and the tile can never disagree.
+
+export interface MediaInspectorSignature {
+  Args: {
+    /** The asset to describe. */
+    asset: MediaAssetSpec;
+    /** Heading above the rows. @default 'Details' */
+    title?: string;
+    /** Hide the derived rows and show only `asset.meta`. @default false */
+    metaOnly?: boolean;
+  };
+  Blocks: {
+    /** Extra rows or controls under the table. */
+    footer: [];
+  };
+  Element: HTMLElement;
+}
+
+export class MediaInspector extends Component<MediaInspectorSignature> {
+  get asset(): ResolvedMediaAsset {
+    return resolveAsset(this.args.asset);
+  }
+  get title(): string {
+    return this.args.title ?? 'Details';
+  }
+  get items(): KeyValueItem[] {
+    const asset = this.asset;
+    const rows: KeyValueItem[] = [];
+    if (!(this.args.metaOnly ?? false)) {
+      rows.push({ key: 'Kind', value: KIND_WORD[asset.kind] });
+      if (asset.width && asset.height) {
+        rows.push({
+          key: 'Dimensions',
+          value: `${asset.width} × ${asset.height}`,
+        });
+      }
+      if (asset.duration) {
+        rows.push({ key: 'Duration', value: formatClock(asset.duration) });
+      }
+      const size = formatBytes(asset.bytes);
+      if (size) {
+        rows.push({ key: 'Size', value: size });
+      }
+      if (asset.tracks && asset.tracks.length > 0) {
+        rows.push({
+          key: 'Captions',
+          value: asset.tracks.map((part) => part.label).join(', '),
+        });
+      }
+    }
+    const extra = asset.meta;
+    if (extra) {
+      for (const key of Object.keys(extra)) {
+        rows.push({ key, value: extra[key] });
+      }
+    }
+    return rows;
+  }
+
+  <template>
+    <section
+      class='pretui-minspector'
+      aria-label={{this.title}}
+      data-test-pretui-media-inspector
+      ...attributes
+    >
+      <header class='pretui-minspector-head'>
+        <h3 class='pretui-minspector-title'>{{this.title}}</h3>
+        <span class='pretui-minspector-name'>{{this.asset.label}}</span>
+      </header>
+      <KeyValue @items={{this.items}}>
+        <:value as |item|>
+          {{#if (isMachineRow item.key)}}
+            <Token @value={{item.value}} />
+          {{else}}
+            {{item.value}}
+          {{/if}}
+        </:value>
+      </KeyValue>
+      <div class='pretui-minspector-footer'>{{yield to='footer'}}</div>
+    </section>
+
+    <style scoped>
+      @layer PretComponent {
+        .pretui-minspector {
+          display: flex;
+          flex-direction: column;
+          gap: 10px;
+          min-width: 0;
+          padding: 12px 14px;
+          border-radius: var(--radius);
+          background: var(--card);
+          box-shadow: var(--pretui-shadow-hairline, 0 0 0 1px var(--border));
+        }
+        .pretui-minspector-head {
+          display: flex;
+          flex-direction: column;
+          gap: 2px;
+          min-width: 0;
+        }
+        .pretui-minspector-title {
+          margin: 0;
+          font-size: var(--text-ui-sm, 11.5px);
+          font-weight: 600;
+          letter-spacing: 0.06em;
+          text-transform: uppercase;
+          color: var(--muted-foreground);
+        }
+        .pretui-minspector-name {
+          font-size: var(--text-body, 14px);
+          font-weight: 600;
+          letter-spacing: -0.01em;
+          color: var(--foreground);
+          overflow: hidden;
+          text-overflow: ellipsis;
+        }
+        .pretui-minspector-footer:empty {
+          display: none;
+        }
+      }
+    </style>
+  </template>
+}
+
+// Machine values get the Law-3 treatment; prose does not. One predicate,
+// used from the KeyValue value slot.
+const MACHINE_ROWS = new Set(['Dimensions', 'Size', 'Duration', 'Format']);
+function isMachineRow(key: string): boolean {
+  return MACHINE_ROWS.has(key);
+}

package/bundled-realms/pretui/components/media-inspector.md

@@ -0,0 +1,46 @@
+## What it is
+
+The metadata panel for an asset: kind, dimensions, duration, size, captions, then whatever the caller attached — rendered as a **KeyValue** table under a heading.
+
+It is the companion to **MediaViewer** rather than part of it. A viewer shows the asset; this describes it. **AssetWell** and **Gallery** pair the two.
+
+## The contract
+
+```
+@asset (required) — a MediaAssetSpec; resolved here, so the same spec the viewer takes
+@title?           — heading above the rows. Default 'Details'
+@metaOnly?        — hide the derived rows and show only asset.meta. Default false
+<:footer>         — extra rows or controls under the table
+```
+
+**Rows are derived, and a row it cannot fill does not appear.** Kind is always present, translated to a word — "3D model" rather than `model`, "File" for an unknown kind. Dimensions appear only when both are known, duration only when there is one, size only when the byte count formats to something, captions only when the asset has tracks. There is no "—" and no empty row.
+
+**Caller metadata is appended, never merged.** Everything in `asset.meta` lands after the derived rows in its own key order, so a caller cannot accidentally shadow a derived row — and `@metaOnly` drops the derived ones entirely when the host already shows them elsewhere.
+
+**Machine values are rendered as Tokens.** Dimensions, Size, Duration and Format take the mono treatment through the **KeyValue** value slot; everything else is prose. That distinction is the panel's one styling opinion, and it is what makes `1920 × 1080` scannable next to a sentence.
+
+**Bytes are formatted in binary units** — KB meaning 1024 — because that is what a file manager shows, and an asset panel that disagrees with Finder is noise.
+
+## Prior art
+
+A kit addition. The comparison is against the metadata sidebar every digital-asset manager ships, and the two things those usually get wrong: rows that render as empty when the value is missing, so the panel is mostly dashes; and every value in the same voice, so a filename, a resolution and a description are visually identical.
+
+Where Pretui is better: absent rows are absent, and machine values are typographically distinct from prose without the caller tagging them.
+
+Where it is thinner: the row set is fixed — there is no way to reorder, relabel or hide a single derived row short of `@metaOnly`, which drops all of them. Values are strings only, so a caller cannot supply a link, a chip or a nested component as a value; `<:footer>` is the escape hatch, and it lands under the table rather than in it. There is no copy affordance on any value, which is the most obvious omission for a panel whose contents people paste elsewhere.
+
+## Accessibility
+
+- **The panel is a `<section>` with an `aria-label` taken from `@title`**, so it is a named region a screen-reader user can find and skip. A caller who passes a `@title` is naming a landmark, which is worth knowing when several inspectors sit on one page — several regions all called "Details" is the failure mode.
+- **The heading is a real `<h3>`**, and the asset's label sits beside it as text rather than as a second heading, so the document outline gets one entry per panel rather than two.
+- **The table is KeyValue's**, so the key/value association is whatever that component provides — this panel does not re-implement it.
+- **Nothing is conveyed by colour or position alone.** Machine values differ from prose by typeface, and each still carries its key.
+- **Nothing is focusable** unless the `<:footer>` block puts something focusable there.
+
+## Theming
+
+`--pretui-shadow-hairline` for the panel's edge, `--pretui-on-neutral` for the header ink, and the **KeyValue** and **Token** treatments for everything inside.
+
+There is almost no surface of its own, which is the intent: an inspector is a table with a heading, and a theme that retunes KeyValue and Token retunes every metadata panel in the product with it. `--pretui-assets-tile` and `--pretui-assets-aspect` are shared with the other components in this module, so an inspector sitting beside an **AssetGrid** inherits the same geometry.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/media-inspector.usage.gts

@@ -0,0 +1,83 @@
+// Pretui — MediaInspector usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import type { MediaAssetSpec } from '../internal/media-viewer';
+import { MediaInspector } from './media-inspector';
+import { SAMPLE_ASSETS } from '../media-examples';
+
+// ── MediaInspector ───────────────────────────────────────────────────────
+class MediaInspectorUsage extends Component {
+  names: string[] = SAMPLE_ASSETS.map((asset) => asset.name ?? asset.src);
+
+  @tracked choice = SAMPLE_ASSETS[0].name ?? '';
+  @tracked metaOnly = false;
+  @tracked title = 'Details';
+
+  setChoice = (v: string) => (this.choice = v);
+  setMetaOnly = (v: boolean) => (this.metaOnly = v);
+  setTitle = (v: string) => (this.title = v);
+
+  get asset(): MediaAssetSpec {
+    return (
+      SAMPLE_ASSETS.find((candidate) => candidate.name === this.choice) ??
+      SAMPLE_ASSETS[0]
+    );
+  }
+  get usage(): string {
+    return `<MediaInspector @asset={{this.asset}} @title='${this.title}' />`;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='MediaInspector'
+      @description="The metadata panel. It composes KeyValue rather than growing a second definition list — the only thing it adds is the derived row set, computed from the asset exactly the way AssetGrid computes the same numbers, so the panel and the tile can never disagree. Machine values (dimensions, size, duration, format) get the Law-3 mono token; prose does not."
+      @source={{this.usage}}
+    >
+      <:example>
+        <MediaInspector
+          @asset={{this.asset}}
+          @title={{this.title}}
+          @metaOnly={{this.metaOnly}}
+        />
+      </:example>
+
+      <:api as |Args|>
+        <Args.String
+          @name='asset (demo knob)'
+          @value={{this.choice}}
+          @options={{this.names}}
+          @description='Which asset to describe.'
+          @onInput={{this.setChoice}}
+        />
+        <Args.Object
+          @name='asset'
+          @value={{this.asset}}
+          @description='The same MediaAssetSpec the viewer and the grid take.'
+        />
+        <Args.String
+          @name='title'
+          @value={{this.title}}
+          @defaultValue='Details'
+          @description='Heading above the rows, and the accessible name of the section.'
+          @onInput={{this.setTitle}}
+        />
+        <Args.Bool
+          @name='metaOnly'
+          @value={{this.metaOnly}}
+          @defaultValue={{false}}
+          @description='Drop the derived rows (kind, dimensions, duration, size, captions) and show only asset.meta.'
+          @onInput={{this.setMetaOnly}}
+        />
+        <Args.Yield
+          @name='footer'
+          @description='Extra rows or controls under the table.'
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_MEDIA_INSPECTOR: Record<string, unknown> = {
+  MediaInspector: MediaInspectorUsage,
+};