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

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

@@ -0,0 +1,284 @@
+// Pretui — Stack: one-axis layout with a gap on the kit scale, items and an optional rule between them.
+import Component from '@glimmer/component';
+import { cssDeclaration, cssStyleFrom } from '../pretui-css';
+import type { PretuiSize } from '../pretui-primitives';
+import { pretuiOrientation, pretuiSize } from '../internal/structure-layout';
+import type { Orientation, OrientationAlias, SizeAlias } from '../internal/structure-layout';
+
+// ── Stack ────────────────────────────────────────────────────────────────
+//
+// Sources read: mantine/packages/@mantine/core/src/components/Stack,
+// .../Group, .../Flex; chakra-ui/packages/react/src/components/stack.
+//
+// What every one of them gets wrong, and what is fixed here:
+//
+//   1. **The divider prop is a `Children` walk, and it changes the box model.**
+//      Chakra interleaves a cloned separator through
+//      `Children.toArray(children).filter(isValidElement)` — which silently
+//      DISCARDS raw string and number children — and then drops `gap` from the
+//      flex container entirely, re-creating the spacing as margins on the
+//      separator. So `gap` and `separator` interact in a way nothing in the
+//      API hints at. MUI is worse: `useFlexGap` defaults to FALSE, so the
+//      default Stack spaces its children with `& > :not(style) ~ :not(style) {
+//      margin-top }`, which breaks under wrapping, under `row-reverse`, and
+//      whenever a child is a fragment. Glimmer has no children array at all,
+//      so the honest port is: hand me the ITEMS and I will lay them out.
+//      `@items` + `<:item>` cannot miscount, keeps `gap` as the one spacing
+//      mechanism in both modes, and is typed.
+//   2. **`min-width: 0` is missing everywhere.** A flex row child defaults to
+//      `min-width: auto`, so one long unbroken label blows the row out of its
+//      container. The fix is four declarations, not one: the cell gets `min-inline-size: 0` here and `.pretui-truncate` is
+//      the caller's half.
+//   3. **Physical `direction: 'row-reverse'` and `left`/`right` alignment.**
+//      Everything here is logical (`flex-direction: row`, `inset-inline`,
+//      `align-self`), so RTL is free rather than a second stylesheet.
+//   4. **`spacing` is a free-form CSS length in Mantine.** Here `@gap` rides
+// the kit's size scale so a theme change re-rhythms every
+//      Stack in the kit at once; a raw length is still accepted through
+//      `@gapLength`, validated by the kit guard.
+
+export type StackGap = 'none' | PretuiSize;
+export type StackAlign = 'start' | 'center' | 'end' | 'stretch' | 'baseline';
+export type StackJustify =
+  | 'start'
+  | 'center'
+  | 'end'
+  | 'between'
+  | 'around'
+  | 'evenly';
+
+export interface StackSignature<T = unknown> {
+  Args: {
+    /** `vertical` (default) or `horizontal`. */
+    orientation?: Orientation;
+    /** Alias for `@orientation`; also accepts `row` / `column`. */
+    direction?: OrientationAlias;
+    /** Gap on the kit's size scale. `sm`/`md`/`lg`/`default` resolve too. */
+    gap?: StackGap | SizeAlias;
+    /**
+     * A raw CSS length for the gap, when the scale is genuinely wrong (a
+     * pixel-matched port, a `calc()` tied to a sibling). Validated by the
+     * kit's caller-value guard; a rejected value falls back to `@gap`.
+     */
+    gapLength?: string;
+    /** Cross-axis alignment. Default `stretch` vertical, `center` horizontal. */
+    align?: StackAlign;
+    /** Main-axis distribution. Default `start`. */
+    justify?: StackJustify;
+    /** Allow items to wrap onto more lines. */
+    wrap?: boolean;
+    /** Render as `inline-flex` rather than `flex`. */
+    inline?: boolean;
+    /**
+     * Draw a hairline between items. **Only effective in the `@items` form**
+     * — the rule is an element this component authors, and a component
+     * cannot author anything between two yielded children.
+     */
+    dividers?: boolean;
+    /**
+     * The items to lay out. Supplying this switches Stack to the `<:item>`
+     * form, which is what unlocks `@dividers` and the per-cell overflow fix.
+     */
+    items?: T[];
+  };
+  Blocks: {
+    /** Free-form children. No dividers, no per-child overflow fix. */
+    default: [];
+    /** One item, with its index. Enables `@dividers`. */
+    item: [T, number];
+  };
+  Element: HTMLDivElement;
+}
+
+/**
+ * The default layout atom: one axis, one gap, logical alignment.
+ *
+ * ```hbs
+ * <Stack @orientation='horizontal' @gap='s' @align='center'>
+ *   <Button>Save</Button>
+ *   <Button @appearance='plain'>Cancel</Button>
+ * </Stack>
+ *
+ * <Stack @items={{this.rows}} @gap='m' @dividers={{true}}>
+ *   <:item as |row|><RowFace @row={{row}} /></:item>
+ * </Stack>
+ * ```
+ *
+ * A class rather than a `TemplateOnlyComponent` for one reason: a
+ * `const … : TemplateOnlyComponent<S>` cannot carry a type parameter, and `T`
+ * flowing into `<:item>` is worth the extra lines. Same call Grid makes.
+ */
+export class Stack<T = unknown> extends Component<StackSignature<T>> {
+  get orientation(): Orientation {
+    return pretuiOrientation(
+      this.args.orientation,
+      this.args.direction,
+      'vertical',
+    );
+  }
+  get gap(): StackGap {
+    let raw = this.args.gap;
+    if (raw === undefined) {
+      return 'm';
+    }
+    if (raw === 'none') {
+      return 'none';
+    }
+    return pretuiSize(raw);
+  }
+  get align(): StackAlign {
+    return (
+      this.args.align ??
+      (this.orientation === 'horizontal' ? 'center' : 'stretch')
+    );
+  }
+  get justify(): StackJustify {
+    return this.args.justify ?? 'start';
+  }
+  /** A caller length reaches CSS only through the kit guard — never
+   * interpolated, never `htmlSafe`d raw. */
+  get style() {
+    return cssStyleFrom([
+      cssDeclaration('--pretui-stack-gap', this.args.gapLength),
+    ]);
+  }
+  /** The `<:item>` form is chosen by BOTH a block and items being present, so
+   * a caller who passes items but writes free-form children still renders. */
+  get usesItems(): boolean {
+    return this.args.items !== undefined;
+  }
+  isFirst = (index: number) => index === 0;
+
+  <template>
+    <div
+      class='pretui-stack'
+      style={{this.style}}
+      data-orientation={{this.orientation}}
+      data-gap={{this.gap}}
+      data-align={{this.align}}
+      data-justify={{this.justify}}
+      data-wrap={{if @wrap 'true' 'false'}}
+      data-inline={{if @inline 'true' 'false'}}
+      data-dividers={{if @dividers 'true' 'false'}}
+      data-test-pretui-stack
+      ...attributes
+    >
+      {{#if this.usesItems}}
+        {{#each @items key='@identity' as |item index|}}
+          {{#unless (this.isFirst index)}}
+            {{#if @dividers}}
+              {{! Decorative by construction: a Stack rule separates LAYOUT,
+                  not sections. `role='separator'` would put a landmark in
+                  the accessibility tree for a hairline that carries no
+                  meaning; Radix's Separator defaults to decorative for the
+                  same reason. A caller who needs the semantic one composes
+                  Divider into the item. }}
+              <span class='pretui-stack-rule' aria-hidden='true'></span>
+            {{/if}}
+          {{/unless}}
+          <div class='pretui-stack-cell'>{{yield item index to='item'}}</div>
+        {{/each}}
+      {{else}}
+        {{yield}}
+      {{/if}}
+    </div>
+
+    <style scoped>
+      @layer PretComponent {
+        .pretui-stack {
+          display: flex;
+          min-inline-size: 0;
+          font-size: inherit;
+        }
+        .pretui-stack[data-inline='true'] {
+          display: inline-flex;
+        }
+        .pretui-stack[data-orientation='vertical'] {
+          flex-direction: column;
+        }
+        .pretui-stack[data-orientation='horizontal'] {
+          flex-direction: row;
+        }
+        .pretui-stack[data-wrap='true'] {
+          flex-wrap: wrap;
+        }
+        /* Gap rides the kit's size scale, so a theme change re-rhythms every
+           Stack at once. `--pretui-stack-gap` (from @gapLength or any ancestor)
+           wins where a caller genuinely needs a length. */
+        .pretui-stack[data-gap='none'] {
+          gap: var(--pretui-stack-gap, 0);
+        }
+        .pretui-stack[data-gap='xs'] {
+          gap: var(--pretui-stack-gap, var(--space-1, 4px));
+        }
+        .pretui-stack[data-gap='s'] {
+          gap: var(--pretui-stack-gap, var(--space-2, 6px));
+        }
+        .pretui-stack[data-gap='m'] {
+          gap: var(--pretui-stack-gap, var(--space-4, 11px));
+        }
+        .pretui-stack[data-gap='l'] {
+          gap: var(--pretui-stack-gap, var(--space-6, 19px));
+        }
+        .pretui-stack[data-gap='xl'] {
+          gap: var(--pretui-stack-gap, var(--space-8, 34px));
+        }
+        /* Logical alignment throughout — RTL costs nothing. */
+        .pretui-stack[data-align='start'] {
+          align-items: flex-start;
+        }
+        .pretui-stack[data-align='center'] {
+          align-items: center;
+        }
+        .pretui-stack[data-align='end'] {
+          align-items: flex-end;
+        }
+        .pretui-stack[data-align='stretch'] {
+          align-items: stretch;
+        }
+        .pretui-stack[data-align='baseline'] {
+          align-items: baseline;
+        }
+        .pretui-stack[data-justify='start'] {
+          justify-content: flex-start;
+        }
+        .pretui-stack[data-justify='center'] {
+          justify-content: center;
+        }
+        .pretui-stack[data-justify='end'] {
+          justify-content: flex-end;
+        }
+        .pretui-stack[data-justify='between'] {
+          justify-content: space-between;
+        }
+        .pretui-stack[data-justify='around'] {
+          justify-content: space-around;
+        }
+        .pretui-stack[data-justify='evenly'] {
+          justify-content: space-evenly;
+        }
+        /* The cell exists to carry the overflow fix: a flex child defaults to min-size auto, so one long token blows the row
+           out. The caller's half is `.pretui-truncate` on their own text. */
+        .pretui-stack-cell {
+          min-inline-size: 0;
+          min-block-size: 0;
+        }
+        .pretui-stack[data-orientation='horizontal'] .pretui-stack-cell {
+          display: flex;
+          align-items: inherit;
+        }
+        .pretui-stack-rule {
+          flex: none;
+          align-self: stretch;
+          background: var(--pretui-stack-rule-color, var(--border));
+        }
+        .pretui-stack[data-orientation='horizontal'] .pretui-stack-rule {
+          inline-size: 1px;
+        }
+        .pretui-stack[data-orientation='vertical'] .pretui-stack-rule {
+          block-size: 1px;
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,81 @@
+## What it is
+
+The one-axis layout atom: a flex row or column with a gap on the kit scale and logical alignment. It is the component a React-trained agent reaches for first — Mantine `Stack` / `Group` / `Flex`, Chakra `VStack` / `HStack`, MUI `Stack`, Ant `Space` — shipped as one component with an orientation rather than three names. A `Group` is a horizontal Stack.
+
+Use **Grid** when items align on two axes, **FormLayout** for label/field columns, **ButtonGroup** when buttons should read as one joined control, and **Toolbar** for a keyboard-navigable action row. **StackDivider** (in `stack-divider.gts`) is the hairline to drop between free-form children; **Divider** stays the canonical reading-territory rule.
+
+## The contract
+
+```
+@orientation? | @direction? (default vertical)
+@gap? (default m), @gapLength?
+@align? (default stretch vertical, center horizontal), @justify? (default start)
+@wrap?, @inline?
+@items?, @dividers?
+<:default>          — free-form children
+<:item as |item i|> — one per item, when @items is passed
+Element: HTMLDivElement
+```
+
+**Two forms, chosen by `@items` alone.** Without `@items`, Stack yields its default block and lays out whatever the caller wrote. With `@items`, it renders one authored cell per item and yields `<:item>` with the item and its index; the default block is not rendered in that form, so passing `@items` with only free-form children renders an empty stack. `T` flows from `@items` into `<:item>`, so the block param is typed.
+
+**`@dividers` and the overflow fix only exist in the items form.** A component can only style elements it authored — scoped CSS stamps the component's own hash on the last compound of every selector, so a rule like `.pretui-stack > * + *` never matches a caller's children. In the items form the cell is authored here: it carries `min-inline-size: 0` (the flex-child overflow fix) and the rule between cells is an element this component renders, exactly n−1 of them. In the free-form form `@dividers` is inert, and a caller who wants a rule drops **StackDivider** between their children.
+
+**The gap is a scale, not a length.** `@gap` takes `none | xs | s | m | l | xl` and the `sm`/`md`/`lg`/`default` aliases. `@gapLength` accepts a raw CSS length for the case where the scale is genuinely wrong; it is validated by the kit's caller-value guard and written to `--pretui-stack-gap` in the root's `style`. A rejected value is dropped whole and the scale gap applies.
+
+**Alignment defaults follow the axis.** A vertical stack stretches its children across the column; a horizontal one centres them on the row. `@justify` takes `start | center | end | between | around | evenly`. `@direction` is an alias for `@orientation` and also accepts `row` / `column`.
+
+`@wrap` sets `flex-wrap: wrap`; `@inline` renders `inline-flex`. `...attributes` reaches the root, and a caller `class` composes with `pretui-stack` rather than replacing it.
+
+## Prior art
+
+**Chakra `Stack`** interleaves its `separator` by walking `Children.toArray(children).filter(isValidElement)` — which silently discards string and number children — and then drops `gap` from the container, re-creating spacing as margins on the separator, so `gap` and `separator` interact in a way the API never states. **MUI `Stack`** defaults `useFlexGap` to false, spacing children with `& > :not(style) ~ :not(style) { margin-top }`, which breaks under wrapping, under `row-reverse` and whenever a child is a fragment. **Mantine** splits the idea across `Stack`, `Group` and `Flex`, with `gap` as a free CSS length or theme key. **Ant `Space`** has `size`, `direction`, `align`, `wrap` and `split` (a divider between items). Tailwind is `flex flex-col gap-2`.
+
+Where Pretui is better:
+
+- **One spacing mechanism in both forms.** `gap` is the only spacing, with or without dividers; the rule is a flex item with its own size, not a margin trick.
+- **The divider cannot miscount.** Glimmer has no children array to walk, so the honest port is to take the items: `@items` + `<:item>` renders n cells and n−1 rules, typed, with no dropped text children.
+- **The overflow fix is built in.** Every source leaves a flex child at `min-width: auto`, so one long unbroken label blows the row out of its container. Items-form cells carry `min-inline-size: 0`.
+- **Logical throughout.** No `row-reverse`, no `left` / `right`; RTL costs nothing.
+- **The gap re-rhythms with the theme.** A scale value maps to `--space-*`, so retuning the spacing tokens moves every Stack at once, where Mantine's raw lengths do not.
+
+Where it is thinner:
+
+- **No reverse direction.** MUI and Chakra accept `row-reverse` / `column-reverse`; here there is none.
+- **No responsive props.** MUI's `direction={{ xs: 'column', sm: 'row' }}` and Chakra's responsive arrays have no analogue; the orientation does not flip at a container width.
+- **No grow / shrink.** Mantine `Group`'s `grow` and per-child `flex` are absent; a child that should fill needs its own style.
+- **No divider in the free-form form.** Chakra and Ant draw one between any children; here that needs the items form or a hand-placed **StackDivider**.
+- **No separate row and column gaps.** Mantine `Flex` takes `rowGap` / `columnGap`; a wrapping Stack uses one gap for both.
+- **The items form wraps every item in a cell**, so a child that expects to be a direct flex item of the stack (for `flex: 1`, say) gets a wrapper in between.
+
+## Accessibility
+
+No APG pattern — Stack is layout and renders a plain `<div>` with no role.
+
+- **Items-form rules are decorative.** Each rule is a `<span aria-hidden="true">` with no role; the tests assert both. A stack rule separates layout, not sections, and a `separator` role for every hairline would clutter the tree.
+- **StackDivider is decorative by default and semantic on request.** It renders `aria-hidden="true"` and no role; with `@semantic={{true}}` it drops `aria-hidden` and renders `role="separator"` with `aria-orientation` (asserted). Its `@orientation` names the _stack's_ axis, not the line's: `horizontal` draws a vertical 1px line for a row. `aria-orientation` echoes that value, which is the opposite of the line as drawn, so a semantic divider in a row announces `horizontal` for a vertical rule. `aria-orientation` reads only `@orientation`; a divider oriented through its `direction` alias falls back to `vertical`.
+- **Visual order is source order.** Nothing reorders, so reading order and tab order match what is drawn — the reason there is no reverse direction.
+- **Grouping is the caller's.** A Stack of related controls is not a group to assistive tech; add `role="group"` and a label through `...attributes`, or use **ButtonGroup** / **Toolbar** where the semantics are the point.
+- **Truncation is the caller's half of the overflow fix.** The cell lets text shrink; ellipsis on the text itself is still the caller's job, and truncated text needs its full value reachable some other way.
+
+## Theming
+
+`--pretui-stack-gap` overrides the scale gap for every value of `@gap`, and is what `@gapLength` writes. Because a custom property inherits, setting it on an ancestor — or passing `@gapLength` to an outer Stack — also overrides every nested Stack's gap unless the inner one passes its own `@gapLength`. `--pretui-stack-rule-color` colours both the items-form rule and **StackDivider** (default `--border`).
+
+The scale maps to `--space-1` (xs), `--space-2` (s), `--space-4` (m), `--space-6` (l) and `--space-8` (xl); `none` is `0`. A theme re-rhythms every Stack by retuning those spacing tokens.
+
+Fixed: the rule's 1px thickness, and the root's `min-inline-size: 0`. Stack sets no colour, font or surface of its own — it inherits font-size and is invisible except for its rules.
+
+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                                   |
+| ------------------------------------------------ | ------------------------------------------- |
+| `Stack` / `VStack` / `Flex direction="column"`   | `<Stack>`                                   |
+| `Group` / `HStack` / `Flex` / Ant `Space`        | `<Stack @orientation='horizontal'>`         |
+| `gap` / `spacing` / Ant `size`                   | `@gap` (scale), `@gapLength` (raw length)   |
+| `align` / `justify` / `wrap`                     | the same names                              |
+| Chakra `separator` / MUI `divider` / Ant `split` | `@items` + `@dividers`, or **StackDivider** |
+| `Separator` / `Divider` between children         | **StackDivider**                            |
+| A two-axis layout                                | **Grid**                                    |

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

@@ -0,0 +1,228 @@
+// Pretui — Stack usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import type { SizeAlias } from '../internal/structure-layout';
+import { Button } from './button';
+import { FreestyleUsage } from './freestyle-usage';
+import { Stack } from './stack';
+import type { StackAlign, StackGap, StackJustify } from './stack';
+import { StackDivider } from './stack-divider';
+import { LOTS } from '../internal/structure-layout-fixtures';
+
+// ── Stack ────────────────────────────────────────────────────────────────
+
+export class StackUsage extends Component {
+  @tracked orientation: 'horizontal' | 'vertical' = 'vertical';
+  @tracked gap: string = 'm';
+  @tracked align: string = 'stretch';
+  @tracked justify: string = 'start';
+  @tracked wrap = false;
+  @tracked dividers = true;
+
+  orientationOptions = ['vertical', 'horizontal'];
+  gapOptions = ['none', 'xs', 's', 'm', 'l', 'xl'];
+  alignOptions = ['start', 'center', 'end', 'stretch', 'baseline'];
+  justifyOptions = ['start', 'center', 'end', 'between', 'around', 'evenly'];
+  lots = LOTS;
+
+  setOrientation = (v: string) => {
+    this.orientation = v as 'horizontal' | 'vertical';
+  };
+  setGap = (v: string) => {
+    this.gap = v;
+  };
+  setAlign = (v: string) => {
+    this.align = v;
+  };
+  setJustify = (v: string) => {
+    this.justify = v;
+  };
+  setWrap = (v: boolean) => {
+    this.wrap = v;
+  };
+  setDividers = (v: boolean) => {
+    this.dividers = v;
+  };
+
+  // The knob rows carry plain strings; the component takes exhaustive unions.
+  // Narrowing in one getter per knob keeps the cast at the boundary instead of
+  // spreading `as` through the template.
+  get gapValue(): StackGap | SizeAlias {
+    return this.gap as StackGap | SizeAlias;
+  }
+  get alignValue(): StackAlign {
+    return this.align as StackAlign;
+  }
+  get justifyValue(): StackJustify {
+    return this.justify as StackJustify;
+  }
+
+  get usage(): string {
+    return [
+      '<Stack',
+      "  @orientation='" + this.orientation + "'",
+      "  @gap='" + this.gap + "'",
+      '  @items={{this.lots}}',
+      '  @dividers={{' + String(this.dividers) + '}}',
+      '>',
+      '  <:item as |lot|>…</:item>',
+      '</Stack>',
+    ].join('\n');
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='Stack'
+      @description='One axis, one gap, logical alignment. Two shapes: free-form children for the ordinary case, and an items form that unlocks dividers and the per-cell overflow fix. The second shape exists because a component can only style elements it authored — a rule between two yielded children is not something CSS can reach.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='layout-stage'>
+          <Stack
+            @orientation={{this.orientation}}
+            @gap={{this.gapValue}}
+            @align={{this.alignValue}}
+            @justify={{this.justifyValue}}
+            @wrap={{this.wrap}}
+            @dividers={{this.dividers}}
+            @items={{this.lots}}
+          >
+            <:item as |lot|>
+              <div class='layout-cell'>
+                <p class='layout-id'>{{lot.id}}</p>
+                <p class='layout-tea'>{{lot.tea}}</p>
+                <p class='layout-meta'>{{lot.place}} · {{lot.chests}} chests</p>
+              </div>
+            </:item>
+          </Stack>
+        </div>
+
+        <p class='layout-note'>Free-form children, no dividers — the shape you
+          reach for nine times out of ten:</p>
+        <div class='layout-stage'>
+          <Stack @orientation='horizontal' @gap='s' @align='center'>
+            <Button @size='s'>Save</Button>
+            <Button @size='s' @appearance='outlined' @tone='neutral'>Cancel</Button>
+            <StackDivider @orientation='horizontal' />
+            <Button @size='s' @appearance='plain' @tone='danger'>Discard</Button>
+          </Stack>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='orientation'
+          @description='vertical (default) or horizontal. The alias direction is accepted too, and so are row and column, because that is what an agent copying flexbox will type.'
+          @options={{this.orientationOptions}}
+          @value={{this.orientation}}
+          @onInput={{this.setOrientation}}
+          @defaultValue='vertical'
+        />
+        <Args.String
+          @name='gap'
+          @description='Gap on the kit size scale, so a theme change re-rhythms every Stack at once. sm, md, lg and default resolve to s, m, l and m.'
+          @options={{this.gapOptions}}
+          @value={{this.gap}}
+          @onInput={{this.setGap}}
+          @defaultValue='m'
+        />
+        <Args.String
+          @name='gapLength'
+          @description='A raw CSS length, for the case where the scale is genuinely wrong. Validated by the kit caller-value guard; a rejected value falls back to the scale.'
+        />
+        <Args.String
+          @name='align'
+          @description='Cross-axis alignment. Defaults to stretch when vertical and center when horizontal, which is what each axis actually wants.'
+          @options={{this.alignOptions}}
+          @value={{this.align}}
+          @onInput={{this.setAlign}}
+          @defaultValue='stretch'
+        />
+        <Args.String
+          @name='justify'
+          @description='Main-axis distribution.'
+          @options={{this.justifyOptions}}
+          @value={{this.justify}}
+          @onInput={{this.setJustify}}
+          @defaultValue='start'
+        />
+        <Args.Bool
+          @name='wrap'
+          @description='Allow items onto more lines.'
+          @defaultValue={{false}}
+          @value={{this.wrap}}
+          @onInput={{this.setWrap}}
+        />
+        <Args.Bool
+          @name='dividers'
+          @description='Draw a hairline between items. Only effective in the items form — a rule is an element this component authors, and nothing can be authored between two yielded children.'
+          @defaultValue={{false}}
+          @value={{this.dividers}}
+          @onInput={{this.setDividers}}
+        />
+        <Args.Array
+          @name='items'
+          @description='Supplying items switches Stack to the item block form, where each cell carries min-inline-size 0 — the flex overflow bug fixed by construction rather than by remembering.'
+        />
+        <Args.Yield
+          @name='item'
+          @description='One item and its index. The typed replacement for React Children.map, which miscounts across fragments and conditional branches.'
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-stack-gap'
+          @type='dimension'
+          @description='Overrides the gap scale from any ancestor.'
+          @defaultValue='var(--space-4)'
+        />
+        <Css.Basic
+          @name='pretui-stack-rule-color'
+          @type='color'
+          @description='The hairline colour used by dividers.'
+          @defaultValue='var(--border)'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+
+    <style scoped>
+      .layout-stage {
+        padding: 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)
+        );
+      }
+      .layout-note {
+        margin: var(--space-5, 14px) 0 var(--space-3, 8px);
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+      .layout-cell {
+        padding: var(--space-3, 8px);
+      }
+      .layout-id {
+        margin: 0;
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        letter-spacing: var(--track-eyebrow, 0.08em);
+        color: var(--muted-foreground);
+      }
+      .layout-tea {
+        margin: 2px 0 0;
+        font-size: var(--text-ui-md, 12.5px);
+        font-weight: 600;
+      }
+      .layout-meta {
+        margin: 1px 0 0;
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_STACK: Record<string, unknown> = {
+  Stack: StackUsage,
+};