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

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

@@ -0,0 +1,218 @@
+// Pretui — Item: one row atom: media, title, description and actions.
+import Component from '@glimmer/component';
+import type { PretuiSize } from '../pretui-primitives';
+import type { ListingSizeArg } from '../internal/reading-listing';
+import { resolveSize } from '../pretui-primitives';
+
+// ═════════════════════════════════════════════════════════════════════════
+// Item — one row of a listing
+// ═════════════════════════════════════════════════════════════════════════
+//
+// The media object every kit ships: leading slot, title, description, a
+// trailing meta column and an actions column. It renders a `<div>`, never an
+// `<li>`, so `<List>` can own the `<li>` and `<Item>` can also stand alone
+// inside a card, a `<Panel>`, or a `<DataTable>`'s `<:expanded>` block.
+//
+// Better than Ant's `List.Item.Meta` and MUI's `ListItemText`:
+//   • Ant hard-codes `<h4>` for the row title, so every list injects h4s into
+//     the page outline regardless of where it sits. This emits a `<span>` and
+//     documents `<:title>` as the place to put a real heading if the row IS
+//     one. MUI wraps titles in `<Typography>` with no heading semantics at
+//     all, which has the opposite failure: a list of section headings that
+//     announces as body text.
+//   • Both leave the flex-overflow bug open: a long title in a flex row
+//     pushes the trailing meta off the end. The fix is applied in full here — `min-width: 0` AND the three
+//     truncation declarations, never one without the others.
+//   • Ant's `actions` are an `<ul>` of `<li>`s with `<em>` separators, which
+//     is list markup used for spacing. Here the actions slot is a plain flex
+//     row and the separator is a border.
+
+export interface ItemSignature {
+  Args: {
+    /** the row's name. `<:title>` wins over it. */
+    title?: string;
+    /** the supporting line. `<:description>` wins over it. */
+    description?: string;
+    /** makes the title a link. A row with a single obvious destination
+     * should have a real `<a>` — not a click handler on the row. */
+    href?: string;
+    /** density — `xs|s|m|l|xl`, `sm`/`md`/`lg` accepted */
+    size?: ListingSizeArg;
+    /** align the leading slot to the first line instead of the block centre
+     * — right for a multi-line row, wrong for a single-line one */
+    alignStart?: boolean;
+    /* NOTE: the wrap at narrow widths is an unnamed container query, which
+     * resolves against the nearest ANCESTOR container. Inside `<List>` that
+     * is the row, which is already one. Standalone, give the box that holds
+     * the Item `container-type: inline-size` or the wrap never fires. */
+  };
+  Blocks: {
+    /** free body content under the title/description */
+    default: [];
+    /** avatar, icon, thumbnail, checkbox */
+    leading: [];
+    /** the row's name, when a string is not enough — put a heading here if
+     * this row is genuinely a heading in your document */
+    title: [];
+    /** the supporting line, when a string is not enough */
+    description: [];
+    /** meta on the inline end: a timestamp, a StatusChip, a count */
+    trailing: [];
+    /** buttons or a Menu, separated from the meta */
+    actions: [];
+  };
+  Element: HTMLDivElement;
+}
+
+export class Item extends Component<ItemSignature> {
+  get size(): PretuiSize {
+    return resolveSize(this.args.size);
+  }
+  get align(): string {
+    return this.args.alignStart ? 'start' : 'center';
+  }
+
+  <template>
+    <div
+      class='pretui-item'
+      data-test-pretui-item
+      data-size={{this.size}}
+      data-align={{this.align}}
+      ...attributes
+    >
+      {{#if (has-block 'leading')}}
+        <div class='pretui-item-lead'>{{yield to='leading'}}</div>
+      {{/if}}
+
+      <div class='pretui-item-body'>
+        {{#if (has-block 'title')}}
+          <span class='pretui-item-title'>{{yield to='title'}}</span>
+        {{else if @title}}
+          {{#if @href}}
+            <a class='pretui-item-title pretui-item-link' href={{@href}}>{{@title}}</a>
+          {{else}}
+            <span class='pretui-item-title'>{{@title}}</span>
+          {{/if}}
+        {{/if}}
+
+        {{#if (has-block 'description')}}
+          <span class='pretui-item-desc'>{{yield to='description'}}</span>
+        {{else if @description}}
+          <span class='pretui-item-desc'>{{@description}}</span>
+        {{/if}}
+
+        {{#if (has-block)}}
+          <div class='pretui-item-content'>{{yield}}</div>
+        {{/if}}
+      </div>
+
+      {{#if (has-block 'trailing')}}
+        <div class='pretui-item-trail'>{{yield to='trailing'}}</div>
+      {{/if}}
+      {{#if (has-block 'actions')}}
+        <div class='pretui-item-actions'>{{yield to='actions'}}</div>
+      {{/if}}
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-item {
+          display: flex;
+          align-items: center;
+          gap: var(--pretui-item-gap, var(--space-4, 11px));
+          min-width: 0;
+          font-size: var(--text-ui-md, 12.5px);
+          letter-spacing: var(--track-ui, 0.01em);
+          color: var(--foreground);
+        }
+        .pretui-item[data-align='start'] {
+          align-items: flex-start;
+        }
+        .pretui-item[data-size='xs'] {
+          font-size: 10.5px;
+        }
+        .pretui-item[data-size='s'] {
+          font-size: var(--text-ui-sm, 11.5px);
+        }
+        .pretui-item[data-size='l'] {
+          font-size: 14px;
+        }
+        .pretui-item[data-size='xl'] {
+          font-size: 16px;
+        }
+        .pretui-item-lead {
+          flex: none;
+          display: flex;
+          align-items: center;
+        }
+        /* min-width:0 is half the fix; without the three truncation
+           declarations on the text it hard-clips instead of ellipsising
+           */
+        .pretui-item-body {
+          flex: 1 1 auto;
+          min-width: 0;
+          display: grid;
+          gap: 2px;
+        }
+        .pretui-item-title {
+          display: block;
+          min-width: 0;
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+          font-weight: 500;
+        }
+        .pretui-item-link {
+          color: inherit;
+          text-decoration: none;
+        }
+        .pretui-item-link:hover {
+          text-decoration: underline;
+        }
+        .pretui-item-link:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 2px;
+          border-radius: 3px;
+        }
+        .pretui-item-desc {
+          display: block;
+          min-width: 0;
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+          color: var(--muted-foreground);
+          font-size: 0.94em;
+        }
+        .pretui-item-content {
+          min-width: 0;
+          margin-block-start: 2px;
+        }
+        .pretui-item-trail {
+          flex: none;
+          display: flex;
+          align-items: center;
+          gap: var(--space-3, 8px);
+          color: var(--muted-foreground);
+          font-size: 0.94em;
+          font-variant-numeric: tabular-nums;
+        }
+        .pretui-item-actions {
+          flex: none;
+          display: flex;
+          align-items: center;
+          gap: var(--space-2, 6px);
+        }
+        /* Unnamed container query on the nearest ancestor container (List's
+           row, or whatever the caller made a container). At this width the
+           trailing meta wraps under the body rather than crushing the title. */
+        @container (max-width: 22rem) {
+          .pretui-item {
+            flex-wrap: wrap;
+          }
+          .pretui-item-trail {
+            margin-inline-start: auto;
+          }
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,66 @@
+## What it is
+
+One row of a listing: a leading slot, a title, a description, a trailing meta column and an actions column. It is the media object every kit ships, and it renders a `<div>`, never an `<li>`, so **List** owns the `<li>` and Item can also stand alone inside a card, a **Panel**, or a **DataTable**'s `<:expanded>` block.
+
+If the row represents a record with an avatar and a name, **EntityDisplay** is the display-only pair. If it is a card in a fitted grid, **FittedCard**. If it is a pill naming a record, **RecordPill**. If it is a step in a sequence, **StepList**. Item is the general row: whatever goes at the start, a name, a line under it, something at the end.
+
+## The contract
+
+```
+@title?, @description?      — strings; the <:title> and <:description> blocks win over them
+@href?                      — makes the title a real <a>
+@size?                      — xs|s|m|l|xl; sm/md/lg accepted
+@alignStart?                — leading slot to the first line instead of the block centre
+<:leading> <:title> <:description> <:trailing> <:actions>
+<:default>                  — free body content under the title and description
+```
+
+**The title is a `<span>`, never a heading.** If this row is genuinely a heading in your document, put a real `<h3>` in `<:title>`; the component will not guess a level for you.
+
+**`@href` makes the title a link, not the row.** A row with one obvious destination should have an anchor; a click handler on the row is not a link and does not announce as one.
+
+**Title and description truncate to one line** with all four declarations (`min-width: 0`, `overflow`, `text-overflow`, `white-space`), because `min-width: 0` on its own hard-clips instead of ellipsising. The default block does not truncate.
+
+**The narrow-width wrap is a container query on the nearest ancestor container.** Inside **List** that is the row, which is already one. Standalone, give the box that holds the Item `container-type: inline-size` or the trailing slot never wraps under the body.
+
+## Prior art
+
+**shadcn `Item`** is the newest name for this and the one an agent will type: `ItemMedia`, `ItemTitle`, `ItemDescription`, `ItemActions`, `asChild` for a link. **MUI `ListItem`** composes `ListItemAvatar`, `ListItemText` (primary/secondary) and `ListItemSecondaryAction`. **Ant `List.Item`** takes `actions` and `extra`, with `List.Item.Meta` for avatar, title and description. **React Aria `GridListItem`** is the selectable row inside a grid list.
+
+Where this is better: **no heading hazard.** Ant's `List.Item.Meta` hard-codes an `<h4>` for every row title, so a list injects h4s into whatever outline it lands in; MUI wraps titles in `<Typography>` with no heading semantics at all, which is the opposite failure for a list of section headings. The title here is a `<span>` and the `<:title>` block is where a real heading goes. **The flex-overflow bug is closed.** Both Ant and MUI let a long title push the trailing meta off the end of the row; here the body is `min-width: 0` and the text truncates. **Actions are a flex row**, not Ant's `<ul>` of `<li>`s with `<em>` separators.
+
+Where it is thinner: **no selection or press state of its own** — that is **List**'s job, through the row API it yields; **no `asChild`** and so no way to make the whole row the link (the title is the link); **no `extra`** distinct from `<:trailing>`; **no dense-vs-comfortable padding axis** beyond `@size`, and no divider of its own (the hairline is **List**'s `@divided`).
+
+## Accessibility
+
+No APG pattern: an Item is a `<div>` of text and slots and carries no role. Its accessibility is composition.
+
+What the component does, from its rendered markup and its tests:
+
+- **No heading is emitted** for `@title`, and no `<li>` — the row is a `<div>`.
+- **`@href` renders a real `<a href>`** around the title text, with a visible focus ring.
+
+The caller's failures to avoid, and they are most of the story: a row whose only action is a handler on the outer `<div>` is not keyboard-reachable — put a link in the title or a button in `<:actions>`; a `<:leading>` avatar with no name or `alt` announces nothing, which is fine only when the title already names the thing; controls in `<:actions>` sit inside the row and, inside **List**, after the row's own selection control in Tab order; and truncation is visual only, so a title that matters in full needs a `title` attribute or a detail view. The trailing column is `--muted-foreground` at 0.94em with tabular numerals; a value that carries meaning must not rely on that colour.
+
+## Theming
+
+Consumed directly: `--foreground`, `--muted-foreground`, `--ring`, `--text-ui-md`, `--text-ui-sm`, `--track-ui`, `--space-2`, `--space-3`, `--space-4`.
+
+Its own knob: `--pretui-item-gap` (default `--space-4`) is the gap between the slots. Density is `@size` on the root `font-size`; everything inside is `em`. The title is weight 500; the description and trailing meta are 0.94em in `--muted-foreground`; the trailing column has `font-variant-numeric: tabular-nums` so a column of prices in a **List** lines up.
+
+Fixed: the 2px gap between title and description, the one-line truncation, the 22rem wrap breakpoint.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+| React | Pretui |
+| --- | --- |
+| `ItemMedia` / `ListItemAvatar` / `Meta.avatar` | `<:leading>` |
+| `ItemTitle` / `ListItemText.primary` / `Meta.title` | `@title` or `<:title>` |
+| `ItemDescription` / `ListItemText.secondary` / `Meta.description` | `@description` or `<:description>` |
+| `ItemActions` / `ListItemSecondaryAction` / Ant `actions` | `<:actions>` |
+| Ant `extra` | `<:trailing>` |
+| `asChild` + `href` | `@href` (the title is the link) |
+| `dense` | `@size='s'` |
+| `alignItems='flex-start'` | `@alignStart` |

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

@@ -0,0 +1,121 @@
+// Pretui — Item usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Button } from './button';
+import { Chip } from './chip';
+import { Item } from './item';
+import type { ListingSizeArg } from '../internal/reading-listing';
+import { LOTS, SIZES } from '../examples-listing';
+import type { Lot } from '../examples-listing';
+
+class ItemUsage extends Component {
+  sizes = SIZES;
+  lot = LOTS[0] as Lot;
+
+  @tracked size: ListingSizeArg = 'm';
+  @tracked alignStart = false;
+  @tracked showActions = true;
+
+  setSize = (v: string) => (this.size = v as ListingSizeArg);
+  setAlignStart = (v: boolean) => (this.alignStart = v);
+  setShowActions = (v: boolean) => (this.showActions = v);
+
+  <template>
+    <FreestyleUsage
+      @name='Item'
+      @slug='item'
+      @description='One row of a listing: leading slot, title, description, a trailing meta column and an actions column. It renders a div, never an li, so List owns the li and Item can also stand alone in a card or inside a DataTable detail row.'
+    >
+      <:example>
+        <div class='it-demo'>
+          {{#if this.showActions}}
+            <Item
+              @title={{this.lot.tea}}
+              @description={{this.lot.supplier}}
+              @size={{this.size}}
+              @alignStart={{this.alignStart}}
+            >
+              <:leading><Chip @label={{this.lot.id}} /></:leading>
+              <:trailing>{{this.lot.price}}</:trailing>
+              <:actions>
+                <Button @appearance='outlined' @size='s'>Open</Button>
+              </:actions>
+            </Item>
+          {{else}}
+            <Item
+              @title={{this.lot.tea}}
+              @description={{this.lot.note}}
+              @size={{this.size}}
+              @alignStart={{this.alignStart}}
+            >
+              <:leading><Chip @label={{this.lot.id}} /></:leading>
+              <:trailing>{{this.lot.price}}</:trailing>
+            </Item>
+          {{/if}}
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='title'
+          @value={{this.lot.tea}}
+          @description='The row’s name. Rendered as a span, never a heading: Ant’s List.Item.Meta hard-codes an h4 and drops it into whatever outline the list lands in. If this row IS a heading in your document, put a real one in the title block.'
+          @hideControls={{true}}
+        />
+        <Args.String
+          @name='description'
+          @value={{this.lot.supplier}}
+          @description='The supporting line. Both title and description truncate with all four declarations — min-width 0 plus overflow, text-overflow and white-space — because min-width 0 on its own hard-clips instead of ellipsising and looks fixed.'
+          @hideControls={{true}}
+        />
+        <Args.String
+          @name='href'
+          @description='Makes the title a real anchor. A row with one obvious destination should have a link, not a click handler.'
+          @hideControls={{true}}
+        />
+        <Args.String
+          @name='size'
+          @value={{this.size}}
+          @options={{this.sizes}}
+          @defaultValue='m'
+          @description='Density on the house scale.'
+          @onInput={{this.setSize}}
+        />
+        <Args.Bool
+          @name='alignStart'
+          @value={{this.alignStart}}
+          @defaultValue={{false}}
+          @description='Align the leading slot to the first line instead of the block centre — right for a multi-line row, wrong for a single-line one.'
+          @onInput={{this.setAlignStart}}
+        />
+        <Args.Bool
+          @name='actions block (demo knob)'
+          @value={{this.showActions}}
+          @defaultValue={{true}}
+          @description='Toggles the actions slot and swaps the description for a long one, so you can watch the truncation and the container-query wrap.'
+          @onInput={{this.setShowActions}}
+        />
+        <Args.Yield
+          @description='Named blocks: leading, title, description, trailing, actions, and a default block for free body content under the title.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .it-demo {
+        container-type: inline-size;
+        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)
+        );
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_ITEM: Record<string, unknown> = {
+  Item: ItemUsage,
+};