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

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

@@ -0,0 +1,135 @@
+// Pretui — CopyButton usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { CopyButton } from './copy-button';
+import {
+  PRETUI_APPEARANCES,
+  PRETUI_SIZES,
+  PRETUI_TONES,
+} from '../pretui-primitives';
+import type {
+  PretuiAppearance,
+  PretuiSize,
+  PretuiTone,
+} from '../pretui-primitives';
+
+const TONES = [...PRETUI_TONES];
+const APPEARANCES = [...PRETUI_APPEARANCES];
+const SIZES = [...PRETUI_SIZES];
+
+// ── CopyButton ← copy-button/usage.gts ───────────────────────────────────
+// Dropped knobs: @tooltipText / @placement / @offset (boxel-ui wraps the
+// button in an ember-velcro Tooltip — wart list forbids; the result is the
+// glyph swap plus a status announcement), @width / @height (the glyph
+// follows the button's font size, which @size sets). @textToCopy and
+// @ariaLabel are accepted as aliases of @text and @label. The result holds
+// for 2 s on every input.
+class CopyButtonUsage extends Component {
+  @tracked textToCopy = 'Text to copy';
+  @tracked labelText = 'Copy to clipboard';
+  @tracked tone = 'neutral';
+  @tracked appearance = 'outlined';
+  @tracked size = 'm';
+  @tracked disabled = false;
+  setText = (v: string) => (this.textToCopy = v);
+  setLabel = (v: string) => (this.labelText = v);
+  setTone = (v: string) => (this.tone = v);
+  setAppearance = (v: string) => (this.appearance = v);
+  setSize = (v: string) => (this.size = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  get sizeVal() {
+    return this.size as PretuiSize;
+  }
+  get toneVal() {
+    return this.tone as PretuiTone;
+  }
+  get appearanceVal() {
+    return this.appearance as PretuiAppearance;
+  }
+  get usage() {
+    let bits = [`@text='${this.textToCopy}'`];
+    if (this.tone !== 'neutral') bits.push(`@tone='${this.tone}'`);
+    if (this.appearance !== 'outlined') {
+      bits.push(`@appearance='${this.appearance}'`);
+    }
+    if (this.size !== 'm') bits.push(`@size='${this.size}'`);
+    if (this.disabled) bits.push('@disabled={{true}}');
+    return `<CopyButton ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='CopyButton'
+      @description='Button that copies a string to the clipboard on click and surfaces a brief confirmation — common in code blocks, share-link rows, and developer tools. The glyph swaps to a check, or a cross on failure, until the pointer leaves.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <CopyButton
+          @text={{this.textToCopy}}
+          @label={{this.labelText}}
+          @tone={{this.toneVal}}
+          @appearance={{this.appearanceVal}}
+          @size={{this.sizeVal}}
+          @disabled={{this.disabled}}
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='text'
+          @required={{true}}
+          @value={{this.textToCopy}}
+          @description='The string written to navigator.clipboard; @value and @textToCopy are aliases.'
+          @onInput={{this.setText}}
+        />
+        <Args.String
+          @name='label'
+          @defaultValue='Copy to clipboard'
+          @value={{this.labelText}}
+          @description='Accessible name, fixed through the result; @ariaLabel is an alias.'
+          @onInput={{this.setLabel}}
+        />
+        <Args.String
+          @name='tone'
+          @value={{this.tone}}
+          @options={{TONES}}
+          @defaultValue='neutral'
+          @description='Semantic color, as on Button.'
+          @onInput={{this.setTone}}
+        />
+        <Args.String
+          @name='appearance'
+          @value={{this.appearance}}
+          @options={{APPEARANCES}}
+          @defaultValue='outlined'
+          @description='Visual weight, as on Button.'
+          @onInput={{this.setAppearance}}
+        />
+        <Args.String
+          @name='size'
+          @value={{this.size}}
+          @options={{SIZES}}
+          @defaultValue='m'
+          @description='Button size; the square and the glyph scale with it.'
+          @onInput={{this.setSize}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @value={{this.disabled}}
+          @defaultValue={{false}}
+          @description='Disables the button.'
+          @onInput={{this.setDisabled}}
+        />
+        <Args.Base
+          @name='variant'
+          @typeLabel='String'
+          @description='Deprecated sugar over @tone + @appearance, as on Button.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_COPY_BUTTON: Record<string, unknown> = {
+  CopyButton: CopyButtonUsage,
+};

package/bundled-realms/pretui/components/copy-fit.gts

@@ -0,0 +1,396 @@
+// Pretui — CopyFit: one adaptive design across badge / strip / tile / card
+// sub-formats, container-query driven. Media-forward when media exists;
+// otherwise the monogram placeholder (wordmark letter on foreground).
+// Translated from pretui-design-system (components/fitted + css/structure.css).
+//
+// Naming (docs/catalog-taxonomy.md): `fitted` is a Boxel rendering format; CopyFit
+// is the layout MECHANISM that makes copy and optional media adapt across the
+// fitted format's quantums.
+import Component from '@glimmer/component';
+import { cssDeclaration, cssStyleFrom } from '../pretui-css';
+import { statusHue } from '../internal/ink';
+
+const or = (...values: unknown[]) => values.some(Boolean);
+
+export interface CopyFitSignature {
+  Args: {
+    title: string;
+    eyebrow?: string;
+    meta?: string;
+    media?: string; // image URL
+    mediaBg?: string;
+    monogram?: string;
+    footerLeft?: string;
+    footerRight?: string;
+    /**
+     * Hue for the monogram cover. Defaults to `statusHue` over the monogram
+     * source, so the same title is the same colour on every card by every
+     * author (Law 2's corollary) — a caller override is the exception.
+     */
+    coverHue?: string;
+    /**
+     * Render the placeholder instead of the content.
+     *
+     * This is the same element tree and the same container-query ladder, with
+     * shimmer bones where the text goes — so the placeholder degrades through
+     * badge / strip / tile / card *identically* to the real card, and the
+     * layout does not move when the data arrives. That is the whole point:
+     * the surveyed source achieved it by hand-duplicating the size ladder in
+     * a second file (and the thresholds were already drifting across three
+     * copies). Here there is one ladder, because there is one component.
+     */
+    loading?: boolean;
+    /** what the placeholder announces (default 'Loading') */
+    loadingLabel?: string;
+  };
+  Blocks: { media: []; footerLeft: []; footerRight: [] };
+  Element: HTMLDivElement;
+}
+
+/**
+ * One adaptive design across badge / strip / tile / card, container-query
+ * driven.
+ *
+ * Cover pass 2026-08-13 (boxel-catalog E7), two ideas:
+ *
+ * **The monogram is a cover, not a grey box.** With no image, the media band
+ * is a Law-2 treatment derived from one hue — a 135° tint gradient with the
+ * letter in ink mixed from the same hue — and that hue comes from `statusHue`
+ * over the monogram source, so it is stable and never picked by hand. (The
+ * surveyed source keyed its cover off a hardcoded type→colour table with a
+ * `#ff5b9c` fallback, and interpolated the whole thing into an `htmlSafe`
+ * style string, bypassing both the cascade and CSP. The hash is the better
+ * answer and Pretui already owned it.)
+ *
+ * **The tile tells the grid what it is.** The root publishes
+ * `data-no-image='true' | 'false'`, so a parent can pick the cell's aspect
+ * ratio from the tile's own content — an inversion of control that lets a
+ * masonry pack monogram tiles at 16:9 and photo tiles at 4:3:
+ *
+ * ```css
+ * .grid > * { aspect-ratio: 4 / 3; }
+ * .grid > *:has([data-no-image='true']) { aspect-ratio: 16 / 9; }
+ * ```
+ */
+export class CopyFit extends Component<CopyFitSignature> {
+  get mediaStyle() {
+    // `@mediaBg` and `@coverHue` are caller strings reaching an inline style
+    // — both go through the kit allowlist so neither can carry its own
+    // declarations.
+    // The caller's hue is validated BEFORE it wins: `??` on the raw value would
+    // let a rejected string swallow the derived hue and leave the tile with
+    // neither, which is the one case the Law-2 guarantee is about.
+    return cssStyleFrom([
+      cssDeclaration('--pretui-fitted-mediabg', this.args.mediaBg),
+      cssDeclaration('--pretui-fitted-cover-hue', this.args.coverHue) ??
+        cssDeclaration('--pretui-fitted-cover-hue', this.coverHue),
+    ]);
+  }
+  get monogram() {
+    return (this.args.monogram ?? this.args.title ?? '?').slice(0, 1);
+  }
+  /** Stable hash → one of the chart hues. Keyed on the whole monogram source
+   * rather than the single letter, so "Ledger" and "Lantern" do not collide. */
+  get coverHue() {
+    return statusHue(this.args.monogram ?? this.args.title ?? '');
+  }
+  get hasFooter() {
+    return this.args.footerLeft || this.args.footerRight;
+  }
+  get loadingLabel() {
+    return this.args.loadingLabel ?? 'Loading';
+  }
+  <template>
+    <div
+      class='pretui-fitted'
+      data-no-image={{if (has-block 'media') 'false' (if @media 'false' 'true')}}
+      data-loading={{if @loading 'true'}}
+      role={{if @loading 'status'}}
+      aria-busy={{if @loading 'true'}}
+      data-test-pretui-fitted
+      ...attributes
+    >
+      <div class='pretui-fitted-root'>
+        <div
+          class='pretui-fitted-media'
+          data-cover={{if
+            @loading
+            'loading'
+            (if (has-block 'media') 'slot' (if @media 'image' 'mono'))
+          }}
+          style={{this.mediaStyle}}
+        >
+          {{#if @loading}}
+            {{! the band itself is the shimmer }}
+          {{else if (has-block 'media')}}
+            {{yield to='media'}}
+          {{else if @media}}
+            <img src={{@media}} alt='' />
+          {{else}}
+            <span class='pretui-fitted-mono'>{{this.monogram}}</span>
+          {{/if}}
+        </div>
+        <div class='pretui-fitted-content'>
+          {{#if @loading}}
+            <span class='pretui-vh'>{{this.loadingLabel}}</span>
+            <span
+              class='pretui-eyebrow pretui-fitted-eyebrow pretui-fitted-bone'
+              aria-hidden='true'
+            ></span>
+            <span
+              class='pretui-fitted-title pretui-fitted-bone'
+              aria-hidden='true'
+            ></span>
+            <span
+              class='pretui-fitted-meta pretui-fitted-bone'
+              aria-hidden='true'
+            ></span>
+            <span class='pretui-fitted-footer' aria-hidden='true'><span
+                class='pretui-fitted-bone pretui-fitted-bone-foot'
+              ></span><span
+                class='pretui-fitted-bone pretui-fitted-bone-foot'
+              ></span></span>
+          {{else}}
+            {{#if @eyebrow}}<span class='pretui-eyebrow pretui-fitted-eyebrow'>{{@eyebrow}}</span>{{/if}}
+            <span class='pretui-fitted-title'>{{@title}}</span>
+            {{#if @meta}}<span class='pretui-fitted-meta'>{{@meta}}</span>{{/if}}
+            {{#if (or this.hasFooter (has-block 'footerLeft') (has-block 'footerRight'))}}
+              <span class='pretui-fitted-footer'><span>{{#if (has-block 'footerLeft')}}{{yield to='footerLeft'}}{{else}}{{@footerLeft}}{{/if}}</span><span>{{#if (has-block 'footerRight')}}{{yield to='footerRight'}}{{else}}{{@footerRight}}{{/if}}</span></span>
+            {{/if}}
+          {{/if}}
+        </div>
+      </div>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-fitted {
+          container-type: size;
+          width: 100%;
+          height: 100%;
+        }
+        .pretui-fitted-root {
+          position: relative;
+          display: flex;
+          width: 100%;
+          height: 100%;
+          background: var(--card);
+          border-radius: var(--radius-surface, 10px);
+          box-shadow: var(--pretui-shadow-card, 0 0 0 1px var(--border));
+          overflow: hidden;
+          flex-direction: column;
+        }
+        .pretui-fitted-media {
+          position: relative;
+          background: var(--pretui-fitted-mediabg, var(--foreground));
+          color: var(--pretui-on-neutral, var(--boxel-light));
+          display: grid;
+          place-items: center;
+          flex: none;
+          overflow: hidden;
+        }
+        .pretui-fitted-media img {
+          position: absolute;
+          inset: 0;
+          width: 100%;
+          height: 100%;
+          object-fit: cover;
+        }
+        /* The monogram COVER (Law 2: one hue in, a complete treatment out).
+           `--pretui-fitted-mediabg` still wins when a caller sets it, so this
+           is a better default rather than a new rule to fight. */
+        .pretui-fitted-media[data-cover='mono'] {
+          --_ch: var(--pretui-fitted-cover-hue, var(--chart-1));
+          background: var(
+            --pretui-fitted-mediabg,
+            linear-gradient(
+              135deg,
+              color-mix(in oklch, var(--_ch) 26%, var(--card)),
+              color-mix(in oklch, var(--_ch) 8%, var(--card))
+            )
+          );
+          color: color-mix(in oklch, var(--foreground) 16%, var(--_ch));
+        }
+        .pretui-fitted-mono {
+          font-family: var(--font-serif);
+          font-style: italic;
+          font-size: 20px;
+          font-weight: 600;
+        }
+        /* ── the placeholder ──────────────────────────────────────────────
+           Bones wear the SAME classes as the text they stand in for, so every
+           `display: none` / `font-size` rule in the ladder below applies to
+           them unchanged: the eyebrow disappears at badge size for the bone
+           exactly as it does for the eyebrow. Nothing here re-states a
+           threshold. */
+        @keyframes pretui-fitted-shimmer {
+          from {
+            background-position: 200% 0;
+          }
+          to {
+            background-position: -200% 0;
+          }
+        }
+        .pretui-fitted-media[data-cover='loading'],
+        .pretui-fitted-bone {
+          background: linear-gradient(
+            90deg,
+            var(--inset, var(--boxel-100)) 40%,
+            var(--hover, var(--boxel-100)) 50%,
+            var(--inset, var(--boxel-100)) 60%
+          );
+          background-size: 200% 100%;
+          animation: pretui-fitted-shimmer 1.6s linear infinite;
+        }
+        .pretui-fitted-bone {
+          min-height: 1em;
+          border-radius: 4px;
+          color: transparent;
+        }
+        .pretui-fitted-bone.pretui-fitted-eyebrow {
+          width: 38%;
+        }
+        .pretui-fitted-bone.pretui-fitted-title {
+          width: 74%;
+        }
+        .pretui-fitted-bone.pretui-fitted-meta {
+          width: 52%;
+        }
+        .pretui-fitted-bone-foot {
+          width: 22%;
+          min-height: 0.85em;
+        }
+        /* Reduced motion lands on the END state — a flat, honest resting
+           placeholder, never a frozen midpoint of the sweep. */
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-fitted-media[data-cover='loading'],
+          .pretui-fitted-bone {
+            animation: none;
+            background: var(--inset, var(--boxel-100));
+          }
+        }
+        .pretui-vh {
+          position: absolute;
+          width: 1px;
+          height: 1px;
+          overflow: hidden;
+          clip-path: inset(50%);
+          white-space: nowrap;
+        }
+        .pretui-fitted-content {
+          display: flex;
+          flex-direction: column;
+          gap: 2px;
+          padding: 10px 12px;
+          min-width: 0;
+          flex: 1;
+          justify-content: center;
+        }
+        .pretui-fitted-title {
+          font-weight: 600;
+          font-size: var(--text-ui-md, 12.5px);
+          letter-spacing: var(--track-heading, -0.02em);
+          white-space: nowrap;
+          overflow: hidden;
+          text-overflow: ellipsis;
+        }
+        .pretui-fitted-meta {
+          font-size: var(--text-ui-sm, 11.5px);
+          color: var(--muted-foreground);
+          white-space: nowrap;
+          overflow: hidden;
+          text-overflow: ellipsis;
+        }
+        .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-fitted-eyebrow {
+          display: none;
+        }
+        .pretui-fitted-footer {
+          display: none;
+          align-items: center;
+          justify-content: space-between;
+          margin-top: auto;
+          padding-top: 8px;
+          font-size: var(--text-ui-sm, 11.5px);
+          color: var(--muted-foreground);
+        }
+        /* badge — tiny: square mark + a word */
+        @container ((max-width: 139px) or (max-height: 47px)) {
+          .pretui-fitted-root {
+            flex-direction: row;
+            align-items: stretch;
+            border-radius: 8px;
+          }
+          .pretui-fitted-media {
+            width: 100cqh;
+            height: 100%;
+            flex: none;
+          }
+          .pretui-fitted-mono {
+            font-size: 13px;
+          }
+          .pretui-fitted-content {
+            padding: 0 9px;
+            gap: 0;
+            min-width: 0;
+          }
+          .pretui-fitted-meta {
+            display: none;
+          }
+          .pretui-fitted-title {
+            font-size: var(--text-ui-xs, 11px);
+          }
+        }
+        /* strip — short & wide: square media left */
+        @container (min-width: 140px) and (min-height: 48px) and (max-height: 89px) {
+          .pretui-fitted-root {
+            flex-direction: row;
+            align-items: stretch;
+          }
+          .pretui-fitted-media {
+            width: 100cqh;
+            height: 100%;
+            flex: none;
+          }
+          .pretui-fitted-content {
+            padding: 0 12px;
+            min-width: 0;
+          }
+        }
+        /* tile — roughly square: media on top */
+        @container (min-width: 140px) and (min-height: 90px) and (max-height: 189px) {
+          .pretui-fitted-media {
+            height: 54%;
+          }
+          .pretui-fitted-eyebrow {
+            display: block;
+          }
+        }
+        /* card — tall, media-forward */
+        @container (min-width: 140px) and (min-height: 190px) {
+          .pretui-fitted-media {
+            height: 52%;
+          }
+          .pretui-fitted-mono {
+            font-size: 28px;
+          }
+          .pretui-fitted-eyebrow {
+            display: block;
+          }
+          .pretui-fitted-footer {
+            display: flex;
+          }
+          .pretui-fitted-content {
+            padding: 12px 14px;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/copy-fit.md

@@ -0,0 +1,60 @@
+## What it is
+
+**One adaptive design across four sub-formats** — badge, strip, tile and card — driven entirely by container queries. Use it as the fitted render of a card: the thing that appears in a **Grid**, a search result, a picker row, or a linked-card slot, at whatever size the host gives it. You do not choose the sub-format; the container does. If you need a full identity row with a tag, **EntityDisplay**. If the reference is broken, **BrokenLink**.
+
+## The contract
+
+```
+@title: string   (required)
+@eyebrow?, @meta?, @media? (image URL), @mediaBg?, @monogram?
+@footerLeft?, @footerRight?
+<:media>  <:footerLeft>  <:footerRight>
+```
+
+**The sub-format is a container query, not an arg.** That is the whole design and it is what "fitted" means in Boxel: the same component renders as a 40px badge in a dense list and as a 300px card in a grid, because the host decides the box and the component decides what fits in it. A format arg would put that decision in the wrong place — the call site rarely knows how big its slot will be.
+
+**Media-forward when media exists; otherwise a monogram.** `@monogram` falls back to the first character of `@title`, then to `'?'` — so a fitted card is never blank, which is the failure mode of every image-first tile when the image is missing.
+
+**`@mediaBg` is a caller string reaching an inline style, and it is validated against the kit allowlist** so it cannot carry its own declarations. That guard is the kit's convention wherever caller data reaches CSS (**Skeleton** does the same with its width/height custom properties), and it is what makes a data-driven background safe.
+
+The footer renders only when `@footerLeft`, `@footerRight`, `<:footerLeft>` or `<:footerRight>` is present. A block replaces the string arg on its side.
+
+## Prior art
+
+The Boxel fitted-format system is the direct context: **Grid** sizes its cells from the same fitted-format spec table, so a `regular-tile` here and a `regular-tile` there are the same box.
+
+Against the wider field: **React Spectrum's `Card`** has `size` and `orientation` props — the caller chooses. **shadcn's `Card`** is six sub-components and no adaptivity at all. **Web Awesome `wa-card`** has `appearance` and slot booleans, again caller-chosen.
+
+So the differentiator is real: **every other kit makes the format a prop, and this makes it a measurement.** The payoff is that one component covers four presentations with no call-site branching, and a card dropped into an unfamiliar slot renders sensibly. The cost is that a caller who _wants_ the tile treatment in a wide box cannot ask for it — the container decides, and overriding means constraining the container.
+
+Container queries here are **unnamed**, as they must be in realm code: the scoped-CSS transpiler silently drops every rule after a named `@container`, so a single named query would delete the rest of the stylesheet with no error anywhere. Same constraint as **FormLayout** and **Timeline**.
+
+Where it is thin: no interactive state (selected, hovered-as-target), no drag affordance, no badge/count overlay, and no explicit aspect-ratio control for the media region.
+
+## Accessibility
+
+No pattern governs it; it is content layout, and the criteria are WCAG **1.3.1**, **1.1.1 Non-text Content** and **2.4.4 Link Purpose**.
+
+Gaps, and the first two are the ones that bite in practice:
+
+- **`@media` is decorative.** The image renders with `alt=""` and the title is the card's text, so a grid of cards neither repeats the title nor contributes unlabelled images. There is no `alt` arg; an image that carries meaning belongs in the card's own content, not in `@media`.
+- **The card is not a link and has no click target.** Interactivity is entirely the host's, which is correct for a presentational component — but it means the usual card-grid failure is available: a click handler on the wrapping `<div>` gives a target that is not focusable, not keyboard-operable and not announced. Wrap it in a real `<a>` or `<button>`, and make sure nothing interactive is inside.
+- **The title is not a heading**, so a grid of fitted cards has no structure to navigate by — the same gap **Panel**, **Toolbar**, **EmptyState**, **Stat** and **ResultCard** all share. An authorable heading level is the kit-wide fix.
+- **The monogram is a decorative letter** carrying no meaning; it should be `aria-hidden` when the title is present, or it announces as a stray character before the name.
+- **Eyebrow, title, meta and footer are four sibling elements with no grouping**, so a screen-reader user hears them as one run.
+- **The sub-format changes with the container**, so the visible content changes with size. Content a format drops is removed with `display: none`, never clipped, so a screen reader never announces text no one can see.
+
+## Theming
+
+`--pretui-fitted-mediabg` (the validated media background), `--card` (surface), `--border` and `--pretui-shadow-card` (edge), `--foreground` (title), `--muted-foreground` (eyebrow and meta), `--font-mono` + `--text-ui-xs` + `--track-eyebrow` (the eyebrow voice shared with **Panel**, **Toolbar** and **DataGrid**), plus the type scale per sub-format.
+
+The container-query breakpoints are not tokenized, so a theme cannot retune where a strip becomes a tile. The monogram's typography is the one thing worth checking per theme — it is a single large letter on a solid ground, and it is the fallback that appears most often in a realm where media is optional.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+Unique to Boxel (container-query badge/strip/tile/card). Not shadcn
+`Card`. When an agent asks for a Card they can compose, send them to
+the **Card** stub. When they ask for a search-result / linked-card
+tile, this is the one.