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

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

@@ -0,0 +1,68 @@
+// Pretui — Grid: a fitted-format card grid, a thin wrap of boxel-ui GridContainer.
+import Component from '@glimmer/component';
+import { GridContainer as BoxelGridContainer } from '@cardstack/boxel-ui/components';
+import type { FittedFormatId } from '@cardstack/boxel-ui/helpers';
+
+// ── Grid — WRAPS boxel-ui ────────────────────────────────────────────────
+// boxel-ui's GridContainer layout engine: an auto-fill CSS grid whose
+// column width and row height come from the fitted-format spec table
+// (@size), with a one-column list mode (@viewFormat='list'). Yields each
+// item with a curried GridItemContainer that clamps the tile to the
+// format's dimensions (@fullWidthItem stretches width, keeps height).
+// Wave-0 adaptations: @items is required (boxel's itemless free-content
+// mode is dropped — use plain CSS grid for that) and @tag is dropped
+// (the container renders boxel's default div).
+
+export interface GridSignature<T = unknown> {
+  Args: {
+    /** the tiles to lay out — yielded back in the caller's own row type */
+    items: T[];
+    /** fitted format id — sets column width and row height */
+    size?: FittedFormatId;
+    /** 'grid' (default) auto-fills columns; 'list' stacks one column */
+    viewFormat?: 'list' | 'grid';
+    /** stretch each item to full row width (height still from @size) */
+    fullWidthItem?: boolean;
+  };
+  Blocks: {
+    /* eslint-disable @typescript-eslint/no-explicit-any -- the SECOND param
+       is boxel-ui's curried GridItemContainer, whose signature is not
+       exported from the components barrel; the first is the caller's row */
+    default: [item: T, gridItemContainer: any];
+    /* eslint-enable @typescript-eslint/no-explicit-any */
+  };
+  Element: HTMLDivElement;
+}
+
+// A class rather than a TemplateOnlyComponent for one reason: a
+// `const … : TemplateOnlyComponent<S>` cannot carry a type parameter, and
+// `T` flowing into the yielded block is worth the extra three lines. The
+// rendered DOM is byte-identical.
+export class Grid<T = unknown> extends Component<GridSignature<T>> {
+  <template>
+    <div class='pretui-grid' data-test-pretui-grid ...attributes>
+      <BoxelGridContainer
+        @items={{@items}}
+        @size={{@size}}
+        @viewFormat={{@viewFormat}}
+        @fullWidthItem={{@fullWidthItem}}
+        as |item ItemContainer|
+      >
+        {{yield item ItemContainer}}
+      </BoxelGridContainer>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        /* The engine's cell gap reads --boxel-sp — remapped to the Pretui
+           spacing scale so grid rhythm follows the theme. */
+        .pretui-grid {
+          width: 100%;
+          font-size: var(--text-ui-md, 12.5px);
+          letter-spacing: var(--track-ui, 0.01em);
+          color: var(--foreground);
+          --boxel-sp: var(--space-4, 11px);
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,54 @@
+## What it is
+
+An auto-filling grid of uniformly sized tiles, where the tile dimensions come from Boxel's **fitted-format** spec table rather than from CSS you write. Use it to lay out a collection of cards at a known format — a search result page, a catalogue, a picker's browse view. If the tiles have varying heights and you want them to pack, use **Masonry**. If the collection is a stream with new items arriving, **Feed**. If it is tabular, **DataGrid**.
+
+## The contract
+
+```
+@items: T[]   (required)
+@size?: FittedFormatId
+@viewFormat? 'grid' | 'list'   (default 'grid')
+@fullWidthItem?
+<:default as |item, GridItemContainer|>
+```
+
+**`@size` is a fitted-format id, not a pixel width.** That is the point of the component: it binds the grid's column width and row height to the same format table the rest of Boxel uses to size a card's fitted render, so a `regular-tile` in a Grid is exactly the size a `regular-tile` is anywhere else. Writing `grid-template-columns: repeat(auto-fill, minmax(200px, 1fr))` by hand gets you a grid; using this gets you a grid that _agrees with the platform_.
+
+The second yielded value, `GridItemContainer`, clamps each tile to the format's dimensions. `@fullWidthItem` stretches width while keeping the format's height — the "one wide row per item" arrangement, distinct from `@viewFormat='list'`, which switches the grid to a single column.
+
+**`@items` is required.** boxel-ui's itemless free-content mode is deliberately dropped in this wave — if you want an arbitrary CSS grid, use plain CSS.
+
+The component is a class rather than a `TemplateOnlyComponent` for exactly one reason, documented in the source: a `const … : TemplateOnlyComponent<S>` cannot carry a type parameter, and `T` flowing into the yielded block is worth three extra lines. The rendered DOM is byte-identical.
+
+## Prior art
+
+A **thin runtime wrap of boxel-ui's `GridContainer`**, per the territory rule — the layout engine is boxel-ui's, and the wrapper only remaps the cell gap (`--boxel-sp` ← `--space-4`) so grid rhythm follows the theme.
+
+The comparison set is thin because the fitted-format binding has no analogue outside Boxel. **React Spectrum's `CardView`** is the nearest — a virtualised grid with `layout` (`grid`/`waterfall`), selection and drag-and-drop. **shadcn** has no grid component. **Web Awesome** has none.
+
+Where this is better than a hand-rolled `auto-fill` grid: format agreement (above), and the fact that `@viewFormat` switches between grid and list without the call site restructuring its markup.
+
+Where it is behind Spectrum's `CardView`, and the gap is significant at scale: **no virtualisation, no selection, and no drag-and-drop.** Every item renders. For a few dozen tiles that is fine; for a few thousand it is not, and there is no windowing option — you page the data yourself with **Pagination**.
+
+## Accessibility
+
+**No roles, no keyboard handling, and that is the right answer.** A grid of tiles is a _layout_, not a widget. The APG **Grid** pattern (roving tabindex, arrow-key cell navigation, `role="grid"`) exists for tabular data with interactive cells, and applying it to a card grid makes it _harder_ to use — arrow keys stop scrolling the page, and every tile becomes unreachable by Tab.
+
+So the accessibility of a Grid is entirely the accessibility of what you yield into it, and that is where to look:
+
+- **Each tile needs its own accessible name.** If tiles are clickable, the clickable element is what carries it — an `<a>` or `<button>` wrapping the tile content, not a `<div>` with a click handler.
+- **Do not stack a click handler on the tile and interactive content inside it.** A tile that is itself a link containing a link is invalid and produces unreachable controls. This is the single most common failure in card grids.
+- **Reading order follows DOM order**, which follows `@items` order, so WCAG **1.3.2 Meaningful Sequence** and **2.4.3 Focus Order** hold by construction — `auto-fill` reflows visually without reordering the DOM.
+- **The container has no accessible name or list semantics.** A screen-reader user is not told "24 items"; they encounter a run of tiles. Wrapping in a `<ul>`/`<li>` or `role="list"` at the call site is worth doing for anything countable.
+- **Reflow (WCAG 1.4.10)**: `auto-fill` handles narrow viewports correctly, but the _tile_ width comes from the fitted-format table and is fixed — so at 320px a wide format will overflow rather than shrink. Choose the format for the narrowest context.
+- **No virtualisation** means no `aria-setsize`/`aria-posinset` bookkeeping is needed, which is one genuine upside of rendering everything.
+
+## Theming
+
+Consumed: `--foreground`, `--text-ui-md`, `--track-ui`.
+
+Remapped into the boxel-ui channel: `--boxel-sp` ← `--space-4` (the cell gap).
+
+That is the entire surface — the Grid paints no background, no border and no shadow, and inherits whatever it sits on. All visual weight belongs to the tiles you yield. Column width and row height come from the fitted-format table and are **not** tokenized, so a theme cannot retune tile dimensions; changing them means changing `@size`.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,144 @@
+// Pretui — Grid usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Grid } from './grid';
+import type { FittedFormatId } from '@cardstack/boxel-ui/helpers';
+
+// ── Grid ← grid-container/usage.gts ──────────────────────────────────────
+// Dropped knobs: @tag (wrapper renders boxel's default div — same
+// narrowing as Pretui Panel's fixed section) and the itemless
+// free-content mode (@items is required in the wrap; use plain CSS grid
+// for custom content). The upstream size list is the full fitted-format
+// table; a representative subset keeps the knob readable.
+const GRID_ITEMS = ['Alpha', 'Bravo', 'Charlie', 'Delta', 'Echo', 'Foxtrot'];
+
+const GRID_SIZES = [
+  'small-tile',
+  'regular-tile',
+  'large-tile',
+  'compact-card',
+  'single-strip',
+  'double-strip',
+];
+
+const GRID_VIEW_FORMATS = ['grid', 'list'];
+
+class GridUsage extends Component {
+  items = GRID_ITEMS;
+  sizeOptions = GRID_SIZES;
+  viewFormatOptions = GRID_VIEW_FORMATS;
+  @tracked size = 'regular-tile';
+  @tracked viewFormat = 'grid';
+  @tracked fullWidthItem = false;
+  setSize = (v: string) => (this.size = v);
+  setViewFormat = (v: string) => (this.viewFormat = v);
+  setFullWidthItem = (v: boolean) => (this.fullWidthItem = v);
+  get sizeVal() {
+    return this.size as FittedFormatId;
+  }
+  get viewFormatVal() {
+    return this.viewFormat as 'grid' | 'list';
+  }
+  get usage() {
+    let bits = [
+      '@items={{this.items}}',
+      `@size='${this.size}'`,
+    ];
+    if (this.viewFormat !== 'grid') bits.push(`@viewFormat='${this.viewFormat}'`);
+    if (this.fullWidthItem) bits.push('@fullWidthItem={{true}}');
+    return `<Grid ${bits.join(' ')} as |item Cell|>\n  <Cell>…</Cell>\n</Grid>`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Grid'
+      @description="Collection layout over the fitted-format spec table: an auto-fill CSS grid whose column width and row height come from @size, with a one-column list mode. Wraps boxel-ui's GridContainer; each item arrives with a curried cell container that clamps the tile to the format's dimensions."
+      @source={{this.usage}}
+    >
+      <:example>
+        <Grid
+          @items={{this.items}}
+          @size={{this.sizeVal}}
+          @viewFormat={{this.viewFormatVal}}
+          @fullWidthItem={{this.fullWidthItem}}
+          as |item Cell|
+        >
+          <Cell>
+            <div class='grid-demo-card'>
+              <span class='grid-demo-eyebrow'>tile</span>
+              <h4 class='grid-demo-title'>{{item}}</h4>
+            </div>
+          </Cell>
+        </Grid>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='items'
+          @required={{true}}
+          @value={{this.items}}
+          @description='Array iterated by the grid — each entry is yielded to the block with its cell container.'
+        />
+        <Args.String
+          @name='size'
+          @value={{this.size}}
+          @options={{this.sizeOptions}}
+          @description='Fitted format id — sets grid column width and row height from the spec table.'
+          @onInput={{this.setSize}}
+        />
+        <Args.String
+          @name='viewFormat'
+          @defaultValue='grid'
+          @value={{this.viewFormat}}
+          @options={{this.viewFormatOptions}}
+          @description="'grid' auto-fills columns at the format width; 'list' stacks items in one full-width column."
+          @onInput={{this.setViewFormat}}
+        />
+        <Args.Bool
+          @name='fullWidthItem'
+          @defaultValue={{false}}
+          @value={{this.fullWidthItem}}
+          @description='Stretches each cell to full row width — height still comes from @size.'
+          @onInput={{this.setFullWidthItem}}
+        />
+        <Args.Yield
+          @description='Yields (item, Cell) per entry — render tile content inside the curried Cell container.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .grid-demo-card {
+        height: 100%;
+        display: grid;
+        align-content: start;
+        gap: 2px;
+        padding: var(--space-4, 11px);
+        background: var(--card);
+        border-radius: var(--radius-surface, 10px);
+        box-shadow: var(
+          --pretui-shadow-card,
+          0 0 0 1px var(--border)
+        );
+        overflow: hidden;
+      }
+      .grid-demo-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);
+      }
+      .grid-demo-title {
+        margin: 0;
+        font-size: var(--text-ui-md, 12.5px);
+        font-weight: 600;
+        color: var(--foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_GRID: Record<string, unknown> = {
+  Grid: GridUsage,
+};

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

@@ -0,0 +1,192 @@
+// Pretui — Handle: a drag grip with a real hit area.
+import Component from '@glimmer/component';
+import { on } from '@ember/modifier';
+import { htmlSafe } from '@ember/template';
+import { keyboardNudge } from '../internal/design-tools';
+import type { DragModifiers } from '../internal/design-tools';
+
+// ═══════════════════════════════════════════════════════════════════════
+// Handle — the drag grip with a real hit area (fig-handle)
+// ═══════════════════════════════════════════════════════════════════════
+
+export interface HandleSignature {
+  Args: {
+    /** position within the parent surface, 0–100 (percentages) */
+    x?: number;
+    y?: number;
+    /** 'point' (default) is the round dot; 'bar' is the vertical stop
+     * marker a gradient bar uses; 'square' is a resize grip */
+    shape?: 'point' | 'bar' | 'square';
+    /** index a parent uses to identify which handle a drag grabbed —
+     * surfaces read it off `SurfaceFrame.origin` */
+    index?: number;
+    /** percent moved by one arrow press before modifiers (default 1) */
+    step?: number;
+    selected?: boolean;
+    disabled?: boolean;
+    /** REQUIRED accessible name — "Start point", "Stop 2", "Origin" */
+    label?: string;
+    /** extra invisible hit area in px on every side (default 6). This is
+     * figui3's `hit-area`, simplified to one number. */
+    hitArea?: number;
+    /** current value announced to a screen reader ("32%, 60%") */
+    valueText?: string;
+    /** arrow-key movement. dx/dy are in PERCENT of the surface, already
+     * multiplied by the modifier keys held. */
+    onNudge?: (dx: number, dy: number, keys: DragModifiers) => void;
+    /** Enter/Space, and a plain click that did not become a drag */
+    onActivate?: () => void;
+  };
+  Blocks: { default: [] };
+  Element: HTMLButtonElement;
+}
+
+/**
+ * A draggable handle on a 2D surface.
+ *
+ * It is a real `<button>` — focusable, named, and activatable — because
+ * that is the only element whose keyboard and accessibility behaviour is
+ * already right for a grip. It does NOT own the drag: the surface does
+ * (see `dragsSurface`), which is what lets a surface with six stops keep
+ * one listener set and lets a handle dragged past the edge keep tracking.
+ *
+ * ARIA has no two-dimensional slider, so the keyboard contract is arrows
+ * (with the same Shift/Alt multipliers as everything else in this module)
+ * plus an announced `aria-valuetext`, and every 2D control in this
+ * territory ALSO exposes paired `ScrubInput` spinbuttons for the exact
+ * numbers. A pointer-only handle would be incomplete; a handle that
+ * pretends to be a slider would be a lie.
+ *
+ * `hitArea` is the fix for the thing that makes most web handles miserable:
+ * a 10px dot is a 10px target. The visible dot stays 10px; an invisible
+ * inset-negative pseudo-element gives it a ~22px target, and 44px on a
+ * coarse pointer.
+ */
+export class Handle extends Component<HandleSignature> {
+  get index(): number {
+    return this.args.index ?? 0;
+  }
+  /** ARIA has no `aria-valuetext` for a button, so the current position is
+   * folded into the accessible name: "Stop 2, 40%". */
+  get accessibleName(): string {
+    let name = this.args.label ?? 'Handle';
+    return this.args.valueText ? name + ', ' + this.args.valueText : name;
+  }
+  get style() {
+    // Every number is clamped through Math before it reaches CSS: a caller
+    // string can never become a declaration here.
+    let x = Math.max(-1000, Math.min(1000, Number(this.args.x ?? 50) || 0));
+    let y = Math.max(-1000, Math.min(1000, Number(this.args.y ?? 50) || 0));
+    let hit = Math.max(0, Math.min(64, Number(this.args.hitArea ?? 6) || 0));
+    return htmlSafe(
+      'left:' +
+        x +
+        '%;top:' +
+        y +
+        '%;--pretui-handle-hit:' +
+        hit +
+        'px',
+    );
+  }
+  handleKeyDown = (event: Event) => {
+    if (this.args.disabled) {
+      return;
+    }
+    let key = event as KeyboardEvent;
+    let keys: DragModifiers = {
+      shift: key.shiftKey,
+      alt: key.altKey,
+      meta: key.metaKey,
+    };
+    let intent = keyboardNudge(key.key, keys, this.args.step ?? 1);
+    if (!intent.handled) {
+      return;
+    }
+    event.preventDefault();
+    event.stopPropagation();
+    // Home/End travel to the ends of the horizontal range; ±Infinity is the
+    // agreed sentinel so a surface can clamp with its own bounds.
+    let dx = intent.toMin ? -Infinity : intent.toMax ? Infinity : intent.dx;
+    this.args.onNudge?.(dx, intent.dy, keys);
+  };
+  handleClick = (event: Event) => {
+    // A click that followed a drag has already moved the handle; only a
+    // stationary press is an activation.
+    void event;
+    if (!this.args.disabled) {
+      this.args.onActivate?.();
+    }
+  };
+  <template>
+    <button
+      type='button'
+      class='pretui-handle'
+      data-shape={{if @shape @shape 'point'}}
+      data-handle={{this.index}}
+      data-selected={{if @selected 'true'}}
+      aria-pressed={{if @selected 'true'}}
+      aria-label={{this.accessibleName}}
+      aria-disabled={{if @disabled 'true'}}
+      style={{this.style}}
+      {{on 'keydown' this.handleKeyDown}}
+      {{on 'click' this.handleClick}}
+      data-test-pretui-handle
+      ...attributes
+    >{{yield}}</button>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-handle {
+          position: absolute;
+          translate: -50% -50%;
+          display: block;
+          width: 11px;
+          height: 11px;
+          padding: 0;
+          border: 0;
+          border-radius: 50%;
+          background: var(--card);
+          box-shadow: 0 0 0 1.5px var(--primary),
+            0 1px 3px var(--shadow-ink-mid, rgb(0 0 0 / 0.22));
+          cursor: grab;
+          touch-action: none;
+          z-index: 2;
+        }
+        /* The hit area: invisible, centred, and never smaller than the dot. */
+        .pretui-handle::before {
+          content: '';
+          position: absolute;
+          inset: calc(-1 * var(--pretui-handle-hit, 6px));
+          border-radius: inherit;
+        }
+        .pretui-handle[data-shape='bar'] {
+          width: 10px;
+          height: 18px;
+          border-radius: var(--radius-sm, 4px);
+        }
+        .pretui-handle[data-shape='square'] {
+          border-radius: 2px;
+        }
+        .pretui-handle[data-selected='true'] {
+          background: var(--primary);
+          box-shadow: 0 0 0 1.5px var(--card),
+            0 0 0 3px var(--primary);
+          z-index: 3;
+        }
+        .pretui-handle[aria-disabled='true'] {
+          cursor: default;
+          opacity: 0.5;
+        }
+        .pretui-handle:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 2px;
+          z-index: 4;
+        }
+        @media (pointer: coarse) {
+          .pretui-handle::before {
+            inset: -16px;
+          }
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,55 @@
+## What it is
+
+A draggable grip on a two-dimensional surface: the dot on a gradient bar, the point on a picking plane, the corner of a crop box.
+
+It is the primitive the spatial controls in this territory are built from, and it is a `<button>` — which is where its keyboard path comes from.
+
+## The contract
+
+```
+@x?, @y?     — position within the parent surface, 0–100 (percentages)
+@shape?      — 'point' (default) the round dot | 'bar' the vertical stop marker
+               a gradient bar uses | 'square' a resize grip
+@index?      — index a parent uses to identify which handle a drag grabbed
+@step?       — percent moved by one arrow press before modifiers. Default 1
+@selected?, @disabled?
+@label?      — REQUIRED accessible name: "Start point", "Stop 2", "Origin"
+@hitArea?    — extra invisible hit area in px on every side. Default 6
+@valueText?  — current value announced to a screen reader ("32%, 60%")
+@onNudge?    — arrow-key movement; dx/dy in PERCENT of the surface, already
+               multiplied by the modifier keys held
+@onActivate? — Enter/Space, and a plain click that did not become a drag
+```
+
+**`@onNudge` receives deltas already multiplied by the modifiers held**, so a parent implements one move function rather than re-deriving what Shift means. The modifiers are passed along too, for a parent that wants to distinguish them.
+
+**`@hitArea` is invisible padding on every side**, defaulting to 6px — figui3's hit-area, simplified to one number. A 10px dot with no hit area is a control most people miss.
+
+**`@onActivate` fires on Enter, Space, and a click that did not become a drag** — so selecting a handle and dragging it are different outcomes of the same gesture.
+
+**`@label` and `@valueText` are both required in practice.** A surface of five identical handles with no names is unusable; a handle whose position is never announced is unusable in a different way.
+
+## Prior art
+
+figui3's handles.
+
+Where Pretui is better: it is a `<button>`, so focus, activation and the tab order are the platform's rather than re-implemented on a div. That is the difference between a handle a keyboard user can reach and one they cannot.
+
+Where it is thinner: no rotation or scale handles, no snapping — a parent implements that in its nudge handler — and no multi-handle selection.
+
+## Accessibility
+
+- **It is a real `<button>`**, which is the whole design. Every spatial control in this territory is keyboard-operable because its handles are buttons.
+- **`@label` is what distinguishes handles from each other.** "Stop 2" and "Stop 3" are navigable; two unnamed dots are not.
+- **`@valueText` is how position is announced.** A handle without it tells a reader it moved but never where to.
+- **Arrow keys nudge in percent of the surface**, so movement is proportional rather than absolute — the same key travels the same visual distance on a small pad and a large one.
+- **`@hitArea` is a motor-accessibility affordance**, not a convenience: a larger target is easier for everyone and materially easier for anyone with a tremor.
+- **`@selected` is a state a parent sets**, and it needs to be perceivable beyond colour in whatever surface hosts it.
+
+## Theming
+
+The handle takes the kit's control and ring tokens, with `@shape` switching geometry rather than palette.
+
+Keeping all three shapes on one token set is what makes a gradient stop, a picking-plane thumb and a crop grip read as the same family of object — they are different shapes of the same affordance.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.