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

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

@@ -0,0 +1,105 @@
+## What it is
+
+A composition shape: a header (eyebrow, title, description, and an action parked at the end edge), an optional full-bleed media band, a body and a footer. This is what a React-trained agent means by `<Card>` — a pricing tile, a settings block, a media object composed by hand.
+
+It is easy to confuse with two neighbours. **CopyFit** is a container-query _identity_: one design that re-cuts itself across badge, strip, tile and card sizes, which is what a Boxel record looks like at whatever size the grid gives it. **Panel** is a _surface_: body, hairline, action bar, with no header/media/footer composition. Card reuses Panel's surface recipe (`--card`, `--radius-surface`, the `--pretui-shadow-*` ladder) rather than inventing a third one. Reach for **Item** for a single row-shaped record, **EmptyState** for a zero-data placeholder, **Result** for an outcome screen, and **Collapsible** when the body should disclose.
+
+## The contract
+
+```
+@title?, @description?, @eyebrow?
+@tone? (default neutral), @appearance? (default outlined), @size? (default m)
+@orientation? | @direction? (default vertical)
+@interactive?, @scroll?
+@selected?, @onSelect?, @selectLabel?
+<:header>       — replaces the whole generated header
+<:title>        — the title line, when it needs markup
+<:description>  — the description line, when it needs markup
+<:action>       — parked at the header's end edge
+<:media>        — full-bleed band before the header (start edge when horizontal)
+<:default>      — the body
+<:footer>       — the footer band, below a hairline
+Element: HTMLElement (the root <section>)
+```
+
+**The header is generated from `@title` or `<:title>`, and from nothing else.** A block wins over its arg: `<:title>` over `@title`, `<:description>` over `@description`. Without a title there is no header at all, so `@eyebrow`, `@description` and `<:action>` render nothing on a titleless card. `<:header>` replaces the generated header outright — the eyebrow, title, description and action are all dropped, and the caller owns the markup and the naming.
+
+**The action column is known, not probed.** The header is a grid that gains its second column only when `<:action>` was passed; the component reflects that as `data-has-action` from a block test, so nesting the action inside a wrapper cannot collapse the layout and no `:has()` is involved.
+
+**Regions render in a fixed order**: media, then header, body and footer in a column. In the `vertical` orientation the media band sits _above_ the header; in `horizontal` it takes the start edge (logical, so RTL mirrors) at `--pretui-card-media-size` wide, and the header, body and footer stack beside it.
+
+**`@interactive` does not make the card clickable.** It adds a hover elevation and a `:focus-within` ring so the card reacts as one surface around the control it contains. A card-sized `<button>` around arbitrary content is a nested-interactive trap; the caller's own link or button stays the target.
+
+**`@onSelect` makes the whole surface a select target, without wrapping anything.** Card renders one native `<button type='button'>` as the section's first child, as wide as the card and behind its content. That button carries the keyboard, the accessible name and `aria-pressed`, and its focus ring outlines the card. A pointer click lands on the content as usual, and the card's own click handler selects the card unless the click landed on something that keeps its own click. That covers every control the kit treats as owning a press (`a[href]`, `button`, `input`, `select`, `textarea`, `label`, `summary`, the `button` and `link` roles, `contenteditable`), anything with a `tabindex`, native media and embeds (`video`, `audio`, `iframe`, `object`, `embed`), and inline overlays (`dialog`, `[popover]`, and the `dialog`, `menu`, `listbox`, `tooltip` and `slider` roles). The walk runs over the composed path, so the controls inside an open shadow root, such as media-chrome's, count too. A click that ends a text selection inside the card doesn't select it either. Nothing in the content is disabled: scrolling, media controls, hover tooltips and text selection behave as they would outside the card. The content is positioned only so it paints after the button, with no z-index and no stacking context, so an inline Popup or Menu still rises above neighbouring cards. Use it for a card that filters a list or drives a detail pane; for a card whose one action is navigation, put a link in the title instead.
+
+**`@selected` is the state, `@onSelect` is the control.** `@selected` reflects as `data-selected` and draws a `--primary` rule on the inline start, the same signal as **List**. On `outlined`, `filled` and `filled-outlined` cards it also lays a `--pretui-selected` tint over the card's own fill, so a tone fill or a caller's `--pretui-card-bg` still shows through. `plain` has no fill to tint, and an `accent` fill under its on-tone ink would be unreadable, so both carry selection on the rule alone; on `accent` the rule is wider and drawn in that ink. With `@onSelect`, `@selected` is also `aria-pressed` on the select control. `@selected` alone draws the state for a card selected from elsewhere. `@onSelect` implies the hover elevation, and replaces `@interactive`'s `:focus-within` ring with the select button's own, so the two never stack.
+
+**`@scroll` scrolls the body, and pins the header and footer.** The caller supplies the height; the body gets `overflow-y: auto` with a stable scrollbar gutter.
+
+`@tone` and `@appearance` are the kit's two axes (`neutral | primary | info | success | warning | danger | attention` × `outlined | filled | filled-outlined | accent | plain`), so a `danger` `filled` card is the same recipe as a `danger` `filled` Button. `@size` takes the house scale and the `sm`/`md`/`lg`/`default` aliases, and sets only the host font-size; every internal dimension is em. `@direction` is an alias for `@orientation` and also accepts `row`/`column`.
+
+Once any named block is present, wrap the body in `<:default>`: loose content beside named blocks passes a local parse and fails the realm transpile.
+
+## Prior art
+
+**shadcn `Card`** is seven `<div>` parts — `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent`, `CardFooter` — with the action column switched on by `has-data-[slot=card-action]:grid-cols-[1fr_auto]`, a `:has()` probe that silently reverts to one column if the action is nested one level deeper. **Mantine `Card`** + `Card.Section` gets full-bleed sections by sniffing `child.type === CardSection` with a `displayName` fallback, so wrapping a section in a memo or HOC stops the trick, and its root is unconditionally `overflow: hidden`. **Chakra `Card`** spells emphasis as `variant` + `colorPalette` resolved in a theme file. **Ant `Card`** takes `title`, `extra`, `cover`, `actions` and `hoverable`; **MUI `Card`** composes `CardHeader`, `CardMedia`, `CardContent`, `CardActions` and `CardActionArea`; **Tremor `Card`** is a decorated surface with a coloured top/left rule.
+
+Where Pretui is better:
+
+- **The title is a heading and names the region.** Every shadcn part is a `<div>`, so a page of cards has no outline and no accessible names. Here the title is an `<h3>` with an id and the `<section>` is `aria-labelledby` it.
+- **The root does not clip.** Mantine's `overflow: hidden` clips every Popover, Menu, Tooltip and focus ring rendered inline — and this kit renders overlays in place. Only the media band clips, and it carries its own logical corner radii.
+- **A whole-card target that can still hold controls.** MUI's `CardActionArea` is a `<button>` around the content, so a link or button inside it is invalid nested-interactive markup, and Ant's `hoverable` + `onClick` is a click handler on a `<div>` that no keyboard reaches. `@onSelect` is a real button beside the content, with `aria-pressed`, and the controls inside stay valid.
+- **Keyboard focus shows.** Every kit's interactive card recipe is a hover shadow; `@interactive` adds the `:focus-within` state that actually exists when a keyboard user is inside.
+- **Named blocks cannot be wrapped away**, unlike Mantine's type-sniffed sections, and the action column is a block test rather than a selector probe.
+- **Tone is the kit's two-axis grid**, not a colour prop resolved somewhere the component cannot document.
+
+Where it is thinner:
+
+- **No heading-level arg.** The title is always `<h3>`; a card under an `<h3>` section heading needs `<:header>` to supply the right level, which also means supplying the id and naming by hand.
+- **No whole-card link.** `@onSelect` makes the surface a select target, not a navigation target; the stretched-link pattern (one link whose `::after` covers the card) is left to the caller.
+- **No `extra` / `actions` array.** Ant's footer action row and header `extra` are blocks here, with no divided action-bar layout.
+- **No loading state.** Ant's `loading` skeleton has no analogue; compose **Skeleton** into the body.
+- **No inset media.** The media band is full-bleed only; Mantine's `inheritPadding` section has no equivalent.
+
+## Accessibility
+
+No APG pattern — a card is a sectioning element, and the component leans on native semantics rather than roles.
+
+- **A titled card is a named region.** The root is a `<section>`; with `@title` or `<:title>` it carries `aria-labelledby` pointing at the generated `<h3>`'s id, which the tests assert. A `<section>` with an accessible name is a `region` landmark, so a grid of twenty titled cards puts twenty landmarks in the rotor. For a long repeated list, prefer **Item** or give the cards a `<:header>` without the naming.
+- **An untitled card adds nothing.** No title means no heading and no `aria-labelledby`, so the `<section>` has no name and exposes no landmark; the tests assert there is no dangling reference.
+- **`<:header>` hands naming back to the caller.** The generated heading and `aria-labelledby` are both dropped (asserted), so a caller header that should name the card must set `aria-labelledby` itself through `...attributes`.
+- **The heading level is fixed at `<h3>`.** Whether that fits the page outline is the caller's problem; nothing adapts it.
+- **The select control is a native button.** Enter and Space come from the platform, and it carries `aria-pressed` from `@selected`. Its name is `@selectLabel`, or the generated title through `aria-labelledby` (asserted). A selectable card with neither a title nor `@selectLabel` has an unnamed button, so give a `<:header>` card a `@selectLabel`. Its `:focus-visible` outline rings the whole card.
+- **Selection does not rely on colour.** The inline-start rule carries it in greyscale, and `aria-pressed` carries it to assistive tech.
+- **The select control comes first in Tab order**, before the card's own controls, and each control inside keeps its own name and focus style.
+- **`@interactive` is presentational.** The card gains no role and no tabindex. The `:focus-within` ring shows keyboard presence, but the control inside must still have its own focus style and accessible name.
+- **A scrolling body is not focusable.** `@scroll` sets `overflow-y: auto` without a tabindex, so a body of plain text cannot be scrolled from the keyboard unless the browser makes the scroller focusable itself. Put a focusable element inside, or add `tabindex="0"` and a label on the content.
+- **Contrast on `accent` is the caller's to check.** `accent` paints the fill with the tone and sets ink to `--pretui-tone-on`, but the description and eyebrow keep `--muted-foreground`, which is tuned for the `--card` ground, not a saturated fill.
+- Motion: the hover shadow transition is removed under `prefers-reduced-motion: reduce`.
+
+## Theming
+
+The per-component knobs: `--pretui-card-pad` (header, body and footer padding, default `1.1em`), `--pretui-card-gap` (header column gap, `0.9em`), `--pretui-card-radius` (defaults to `--radius-surface`; the media band inherits the corners it touches), `--pretui-card-media-size` (media width when horizontal, `34%`), `--pretui-card-bg` (overrides the fill of every appearance except `plain`), `--pretui-card-shadow` (the outlined / filled-outlined hairline) and `--pretui-card-shadow-hover` (the interactive and selectable hover). Selection reads `--pretui-selected` for the tint and `--primary` for the inline-start rule.
+
+The surface reads `--card`, `--card-foreground`, `--border`, `--muted-foreground`, `--ring`, `--pretui-shadow-card` and `--pretui-shadow-raised`. Tone resolves through the shared channel `--pretui-tone` / `--pretui-tone-on`, fed from `--primary`, `--pretui-info`, `--success`, `--warning`, `--destructive` and `--pretui-attention` (with their `--pretui-on-*` partners). Size reads `--pretui-size-*` with `--text-ui-*` fallbacks. Type reads `--track-ui`, `--track-heading`, `--track-eyebrow` and `--font-mono`; motion reads `--pretui-dur-snap` and `--pretui-ease-snap`.
+
+Fixed: the title at `1.12em` weight 600, the description at `0.94em`, the footer hairline (a `-1px` inset shadow in `--border`), the `12%` tone mix for `filled` and the `32%` hairline mix for `filled-outlined`.
+
+A theme changes every card by retuning `--card`, `--radius-surface` and the shadow ladder, which moves Panel in lockstep. Because the filled recipes mix the tone against `--card`, dark mode gets correctly tinted dark cards without a dark-mode branch.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+| Agent types                                | Give them                           |
+| ------------------------------------------ | ----------------------------------- |
+| `CardHeader` / `CardTitle` / Ant `title`   | `@title` or `<:title>`              |
+| `CardDescription` / MUI `subheader`        | `@description` or `<:description>`  |
+| `CardAction` / Ant `extra`                 | `<:action>`                         |
+| `CardContent`                              | `<:default>`                        |
+| `CardFooter` / Ant `actions`               | `<:footer>`                         |
+| `CardMedia` / Ant `cover` / `Card.Section` | `<:media>`                          |
+| Ant `hoverable`                            | `@interactive` (hover + focus ring) |
+| MUI `CardActionArea` / a selectable tile   | `@onSelect` + `@selected`           |
+| Mantine `Paper` / a bare surface           | **Panel**                           |
+| A record tile that resizes with its slot   | **CopyFit**                         |

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

@@ -0,0 +1,279 @@
+// Pretui — Card usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import type { SizeAlias } from '../internal/structure-layout';
+import type { PretuiTone } from '../pretui-primitives';
+import { AspectRatio } from './aspect-ratio';
+import { Button } from './button';
+import { Card } from './card';
+import type { CardAppearance } from './card';
+import { FreestyleUsage } from './freestyle-usage';
+import { LOTS, Lot, SWATCH } from '../internal/structure-layout-fixtures';
+
+// ── Card ─────────────────────────────────────────────────────────────────
+
+export class CardUsage extends Component {
+  @tracked tone = 'neutral';
+  @tracked appearance = 'outlined';
+  @tracked size = 'm';
+  @tracked orientation: 'horizontal' | 'vertical' = 'vertical';
+  @tracked interactive = true;
+  @tracked selectable = false;
+  @tracked selected = false;
+
+  toneOptions = [
+    'neutral',
+    'primary',
+    'info',
+    'success',
+    'warning',
+    'danger',
+    'attention',
+  ];
+  appearanceOptions = [
+    'outlined',
+    'filled',
+    'filled-outlined',
+    'accent',
+    'plain',
+  ];
+  sizeOptions = ['xs', 's', 'm', 'l', 'xl'];
+  orientationOptions = ['vertical', 'horizontal'];
+  swatch = SWATCH;
+  lot = LOTS[0] as Lot;
+
+  setTone = (v: string) => {
+    this.tone = v;
+  };
+  setAppearance = (v: string) => {
+    this.appearance = v;
+  };
+  setSize = (v: string) => {
+    this.size = v;
+  };
+  setOrientation = (v: string) => {
+    this.orientation = v as 'horizontal' | 'vertical';
+  };
+  setInteractive = (v: boolean) => {
+    this.interactive = v;
+  };
+  setSelectable = (v: boolean) => {
+    this.selectable = v;
+  };
+  setSelected = (v: boolean) => {
+    this.selected = v;
+  };
+  toggleSelected = () => {
+    this.selected = !this.selected;
+  };
+  get onSelect(): (() => void) | undefined {
+    return this.selectable ? this.toggleSelected : undefined;
+  }
+
+  get toneValue(): PretuiTone {
+    return this.tone as PretuiTone;
+  }
+  get appearanceValue(): CardAppearance {
+    return this.appearance as CardAppearance;
+  }
+  get sizeValue(): SizeAlias {
+    return this.size as SizeAlias;
+  }
+
+  get usage(): string {
+    return [
+      '<Card',
+      "  @title='Lot " + this.lot.id + "'",
+      "  @description='" + this.lot.tea + "'",
+      "  @tone='" + this.tone + "'",
+      "  @appearance='" + this.appearance + "'",
+      ...(this.selectable
+        ? [
+            '  @selected={{this.selected}}',
+            '  @onSelect={{this.toggleSelected}}',
+          ]
+        : []),
+      '>',
+      '  <:action>…</:action>',
+      '  <:media>…</:media>',
+      '  <:default>…</:default>',
+      '  <:footer>…</:footer>',
+      '</Card>',
+    ].join('\n');
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='Card'
+      @description='The name collision worth getting right: CopyFit is a container-query identity, Panel is a surface, and this is neither — it is the composition shape React means by Card. Header with a title, a description and an action parked at the end edge; then media, body and footer.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='card-stage'>
+          <Card
+            @title={{this.lot.tea}}
+            @eyebrow={{this.lot.id}}
+            @description='First flush, hand-rolled, single estate.'
+            @tone={{this.toneValue}}
+            @appearance={{this.appearanceValue}}
+            @size={{this.sizeValue}}
+            @orientation={{this.orientation}}
+            @interactive={{this.interactive}}
+            @selected={{this.selected}}
+            @onSelect={{this.onSelect}}
+          >
+            <:action>
+              <Button
+                @size='xs'
+                @appearance='plain'
+                @tone='neutral'
+              >Edit</Button>
+            </:action>
+            <:media>
+              <AspectRatio
+                @ratio='16 / 9'
+                @src={{this.swatch}}
+                @alt='Estate at dawn'
+              />
+            </:media>
+            <:default>
+              <p class='card-body'>{{this.lot.place}}
+                ·
+                {{this.lot.chests}}
+                chests. The header grid gains its second column only when an
+                action block is present — and it knows that from a block test,
+                not from a selector probe that a nested action would defeat.</p>
+            </:default>
+            <:footer>
+              <Button @size='s'>Open lot</Button>
+              <Button
+                @size='s'
+                @appearance='plain'
+                @tone='neutral'
+              >Archive</Button>
+            </:footer>
+          </Card>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='title'
+          @description='Header title. Sugar for the title block; the block wins when both exist. Rendered as a real h3 with an id, and the section is labelled by it — so a card with a title is a named region, and a card without one adds nothing to the rotor.'
+        />
+        <Args.String
+          @name='description'
+          @description='The supporting line under the title.'
+        />
+        <Args.String
+          @name='eyebrow'
+          @description='A small uppercase line above the title.'
+        />
+        <Args.String
+          @name='tone'
+          @description='The kit tone axis: which hue and why.'
+          @options={{this.toneOptions}}
+          @value={{this.tone}}
+          @onInput={{this.setTone}}
+          @defaultValue='neutral'
+        />
+        <Args.String
+          @name='appearance'
+          @description='The kit appearance axis: how loud. outlined is the hairline surface, plain removes it entirely.'
+          @options={{this.appearanceOptions}}
+          @value={{this.appearance}}
+          @onInput={{this.setAppearance}}
+          @defaultValue='outlined'
+        />
+        <Args.String
+          @name='size'
+          @description='Sets the host font size only; every internal dimension is em, so one declaration scales the whole card.'
+          @options={{this.sizeOptions}}
+          @value={{this.size}}
+          @onInput={{this.setSize}}
+          @defaultValue='m'
+        />
+        <Args.String
+          @name='orientation'
+          @description='vertical stacks media above the body; horizontal puts media on the start edge, which mirrors in RTL for free.'
+          @options={{this.orientationOptions}}
+          @value={{this.orientation}}
+          @onInput={{this.setOrientation}}
+          @defaultValue='vertical'
+        />
+        <Args.Bool
+          @name='interactive'
+          @description='Hover elevation plus a focus-within ring. It does not make the card itself clickable — a card-sized button around arbitrary content is a nested-interactive trap. The focus-within half is the part every source library omits.'
+          @defaultValue={{false}}
+          @value={{this.interactive}}
+          @onInput={{this.setInteractive}}
+        />
+        <Args.Bool
+          @name='onSelect'
+          @description='Set it and the whole card becomes a select target: one full-size button behind the content, with aria-pressed from selected. The Edit, Open lot and Archive buttons keep their own clicks. Toggle it here to try both.'
+          @defaultValue={{false}}
+          @value={{this.selectable}}
+          @onInput={{this.setSelectable}}
+        />
+        <Args.Bool
+          @name='selected'
+          @description='A tint plus a rule on the inline start, so selection reads without colour. Reflected as aria-pressed on the select control.'
+          @defaultValue={{false}}
+          @value={{this.selected}}
+          @onInput={{this.setSelected}}
+        />
+        <Args.String
+          @name='selectLabel'
+          @description='The select control name. Defaults to the title, through aria-labelledby.'
+        />
+        <Args.Bool
+          @name='scroll'
+          @description='The body scrolls and the header and footer pin. The caller supplies the height.'
+          @defaultValue={{false}}
+        />
+        <Args.Yield
+          @name='header / title / description / action / media / footer'
+          @description='The Glimmer equivalent of the React compound children. Once any named block is present, wrap the body in a default block — loose content beside named blocks passes local parse and fails the realm transpile.'
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-card-pad'
+          @type='dimension'
+          @description='Padding for the header, body and footer, in em so it rides the size scale.'
+          @defaultValue='1.1em'
+        />
+        <Css.Basic
+          @name='pretui-card-radius'
+          @type='dimension'
+          @description='Corner radius; the media band inherits the two corners it touches.'
+          @defaultValue='var(--radius-surface)'
+        />
+        <Css.Basic
+          @name='pretui-card-media-size'
+          @type='dimension'
+          @description='Media width in the horizontal orientation.'
+          @defaultValue='34%'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+
+    <style scoped>
+      .card-stage {
+        max-inline-size: 420px;
+        padding: var(--space-5, 14px);
+        border-radius: var(--radius-surface, 10px);
+        background: var(--canvas, var(--boxel-100));
+      }
+      .card-body {
+        margin: 0;
+        font-size: var(--text-ui-sm, 11.5px);
+        line-height: 1.55;
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_CARD: Record<string, unknown> = {
+  Card: CardUsage,
+};