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

package/bundled-realms/pretui/components/form-footer.usage.gts

@@ -0,0 +1,217 @@
+// Pretui — FormFooter usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { FormFooter } from './form-footer';
+import type { FormIssue } from '../internal/forms-core';
+
+// ── FormFooter ───────────────────────────────────────────────────────────
+const FOOTER_ISSUES: FormIssue[] = [
+  {
+    ruleId: 'opp-close-date',
+    targetPath: 'Close Date',
+    severity: 'error',
+    message: 'Close date must fall inside the open fiscal quarter.',
+  },
+  {
+    ruleId: 'opp-amount-approval',
+    targetPath: 'Amount',
+    severity: 'error',
+    message: 'Deals above $250,000 need a second approver on the record.',
+  },
+];
+
+class FormFooterUsage extends Component {
+  @tracked count = 3;
+  @tracked saving = false;
+  @tracked disabled = false;
+  @tracked dock = 'sticky';
+  @tracked hasErrors = false;
+  @tracked saveLabel = 'Save';
+  @tracked cancelLabel = 'Cancel';
+  @tracked log = '';
+
+  setCount = (v: number) => (this.count = v);
+  setSaving = (v: boolean) => (this.saving = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  setDock = (v: string) => (this.dock = v);
+  setHasErrors = (v: boolean) => (this.hasErrors = v);
+  setSaveLabel = (v: string) => (this.saveLabel = v);
+  setCancelLabel = (v: string) => (this.cancelLabel = v);
+
+  get dockMode(): 'sticky' | 'static' {
+    return this.dock === 'static' ? 'static' : 'sticky';
+  }
+  get issues(): FormIssue[] {
+    return this.hasErrors ? FOOTER_ISSUES : [];
+  }
+  get dockOptions() {
+    return ['sticky', 'static'];
+  }
+  onSave = () => (this.log = `Saved ${this.count}.`);
+  onCancel = () => (this.log = 'Discarded.');
+
+  get usage() {
+    return [
+      `<FormFooter`,
+      `  @count={{${this.count}}}`,
+      `  @dock='${this.dockMode}'`,
+      `  @issues={{this.issues}}`,
+      `  @saving={{${this.saving}}}`,
+      `  @onSave={{this.onSave}}`,
+      `  @onCancel={{this.onCancel}} />`,
+    ].join('\n');
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='FormFooter'
+      @description="The docked save/cancel bar for a batched form — SLDS's docked-form-footer, cut to stay inside a card. Reach for it whenever edits accumulate before a single commit: RecordDetail renders one automatically, and you can dock your own anywhere else from its yielded state. It states the count of unsaved changes in an aria-live region (SLDS shows no count at all), disables Save while any blocking issue stands, and points Save's aria-describedby at the reason. The upstream is position: fixed, which escapes a card's bounding box and is lint-flagged in this codebase — this one is position: sticky, so it docks to the bottom of the form's own scroll container instead. Scroll the frame below to watch it hold. Limit: sticky needs a scrolling ancestor; with none, @dock='static' is the honest choice."
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='ff-frame'>
+          <div class='ff-scroll'>
+            <div class='ff-filler'>
+              <p>Opportunity — spring first-flush allocation. Scroll to see the
+                bar stay docked to the bottom of THIS frame rather than the
+                browser window.</p>
+              <p>Stage: Negotiation. Amount: $312,400. Close date: 2026-05-07.</p>
+              <p>Line items: Silver Needle, Da Hong Pao, Gyokuro, Milk Oolong,
+                White Peony, Jasmine Dragon Pearls.</p>
+              <p>Every batched edit above would be counted by the bar below.</p>
+              <p>Keep scrolling.</p>
+              <p>And a little more.</p>
+            </div>
+            <FormFooter
+              @count={{this.count}}
+              @issues={{this.issues}}
+              @saving={{this.saving}}
+              @disabled={{this.disabled}}
+              @dock={{this.dockMode}}
+              @saveLabel={{this.saveLabel}}
+              @cancelLabel={{this.cancelLabel}}
+              @onSave={{this.onSave}}
+              @onCancel={{this.onCancel}}
+            />
+          </div>
+        </div>
+        {{#if this.log}}
+          <p class='ff-log'>{{this.log}}</p>
+        {{/if}}
+      </:example>
+
+      <:api as |Args|>
+        <Args.Number
+          @name='count'
+          @value={{this.count}}
+          @min={{0}}
+          @max={{12}}
+          @step={{1}}
+          @defaultValue={{0}}
+          @description='Fields carrying a committed-but-unsaved edit. Drives the live status sentence and enables Save; at zero the bar still renders, reading “No unsaved changes”, so nothing jumps when the first edit lands.'
+          @onInput={{this.setCount}}
+        />
+        <Args.Bool
+          @name='issues'
+          @value={{this.hasErrors}}
+          @defaultValue={{false}}
+          @description='Injects two blocking issues. Blocking severity — “error”, or anything unrecognised — disables Save and is counted in the status line. The footer never evaluates anything.'
+          @onInput={{this.setHasErrors}}
+        />
+        <Args.Bool
+          @name='saving'
+          @value={{this.saving}}
+          @defaultValue={{false}}
+          @description='Save is in flight: the button goes busy and both actions lock.'
+          @onInput={{this.setSaving}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @value={{this.disabled}}
+          @defaultValue={{false}}
+          @description='Hard-disables Save regardless of count — a permission gate, say.'
+          @onInput={{this.setDisabled}}
+        />
+        <Args.String
+          @name='dock'
+          @value={{this.dock}}
+          @options={{this.dockOptions}}
+          @defaultValue='sticky'
+          @description="'sticky' docks to the bottom of the nearest scroll container; 'static' leaves the bar in normal flow. Never fixed — a card must not paint outside its own box."
+          @onInput={{this.setDock}}
+        />
+        <Args.String
+          @name='saveLabel'
+          @value={{this.saveLabel}}
+          @defaultValue='Save'
+          @description='Label for the commit action.'
+          @onInput={{this.setSaveLabel}}
+        />
+        <Args.String
+          @name='cancelLabel'
+          @value={{this.cancelLabel}}
+          @defaultValue='Cancel'
+          @description='Label for the discard action.'
+          @onInput={{this.setCancelLabel}}
+        />
+        <Args.Action
+          @name='onSave'
+          @description='Invoked when the user commits the batch.'
+          @hideControls={{true}}
+        />
+        <Args.Action
+          @name='onCancel'
+          @description='Invoked when the user discards the batch.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @name='<:status>'
+          @description='Replaces the generated status sentence entirely — for a domain where “3 unsaved changes” is the wrong thing to say, or where the errors should be a click-to-jump list.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @name='<:actions>'
+          @description='Extra actions rendered before Cancel/Save — a “Save & New”, say.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+
+    <style scoped>
+      .ff-frame {
+        border-radius: var(--radius-surface, 10px);
+        box-shadow: var(--pretui-shadow-card, 0 0 0 1px var(--border));
+        background: var(--card);
+        overflow: hidden;
+      }
+      .ff-scroll {
+        height: 240px;
+        overflow: auto;
+        display: flex;
+        flex-direction: column;
+      }
+      .ff-filler {
+        flex: 1 0 auto;
+        padding: var(--space-5, 14px);
+        display: grid;
+        gap: var(--space-4, 11px);
+        font-size: var(--text-ui-md, 12.5px);
+        color: var(--muted-foreground);
+      }
+      .ff-filler p {
+        margin: 0;
+      }
+      .ff-log {
+        margin: var(--space-3, 8px) 0 0;
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_FORM_FOOTER: Record<string, unknown> = {
+  FormFooter: FormFooterUsage,
+};

package/bundled-realms/pretui/components/form-layout.gts

@@ -0,0 +1,130 @@
+// Pretui — FormLayout: the grid a Form lays its fields and sections into.
+import Component from '@glimmer/component';
+import { hash } from '@ember/helper';
+import { FormField } from './form-field';
+import type { FormSectionRegistry } from './form-field';
+import { FormSection } from './form-section';
+import { FormContext } from '../internal/forms-core';
+
+// ── FormLayout ───────────────────────────────────────────────────────────
+// SLDS's `.slds-form` (`_stacked` / `_horizontal`) plus `slds-form__row` /
+// `slds-form__item`, as one grid.
+//
+// Better than the inspiration: SLDS breaks its columns on
+// `@media (min-width: 48em)` — the VIEWPORT — so a two-column form in a
+// 320px side panel of a 1600px window stays two columns and shreds. Ours
+// measures the pane with an unnamed container query. (Named container
+// queries are forbidden in realm code: the scoped-CSS transpiler silently
+// drops every rule after one, so a single `@container name (...)` would
+// delete the rest of this stylesheet with no error anywhere.)
+//
+// Note the container-query subtlety this markup exists to satisfy: an
+// unnamed query resolves against the nearest ANCESTOR container, so a rule
+// inside one can never match the container element itself. Hence the outer
+// `.pretui-formlayout` (the container) wrapping the inner
+// `.pretui-formlayout-grid` (what the queries actually restyle).
+
+/* eslint-disable @typescript-eslint/no-explicit-any -- curried contextual
+   components, any-typed exactly as in freestyle.gts's Args hash */
+export interface FormLayoutApi {
+  /** FormField, pre-curried with the form context and this direction. */
+  Field: any;
+  /** FormSection, pre-curried with the form context. A section is a grid
+   *  item and spans every column by default. */
+  Section: any;
+  direction: 'stacked' | 'horizontal';
+  columns: number;
+}
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+export interface FormLayoutSignature {
+  Args: {
+    /** 'stacked' puts labels above controls; 'horizontal' puts them beside,
+     *  and curries that into the yielded Field. */
+    direction?: 'stacked' | 'horizontal';
+    /** 1 or 2 (3 is allowed and collapses in two steps). Columns collapse to
+     *  one below the container breakpoint. */
+    columns?: number;
+    /** Label column width in the horizontal direction. Default 9rem. */
+    labelWidth?: string;
+    /** Gap between fields. Default var(--space-5, 14px). */
+    gap?: string;
+    /** The owning form's context — passed straight through to the yielded
+     *  Field. Supplied automatically by `form.Layout`. */
+    form?: FormContext;
+    /** The enclosing FormSection, passed through so fields laid out inside a
+     *  section still count toward that section's issue badge. Supplied
+     *  automatically by `section.Layout`. */
+    section?: FormSectionRegistry;
+  };
+  Blocks: { default: [FormLayoutApi] };
+  Element: HTMLDivElement;
+}
+
+export class FormLayout extends Component<FormLayoutSignature> {
+  get direction(): 'stacked' | 'horizontal' {
+    return this.args.direction ?? 'stacked';
+  }
+  get columns(): number {
+    return this.args.columns ?? 1;
+  }
+  get columnsAttr(): string {
+    return String(this.columns);
+  }
+  <template>
+    <div
+      class='pretui-formlayout'
+      data-direction={{this.direction}}
+      data-columns={{this.columnsAttr}}
+      data-test-pretui-form-layout
+      ...attributes
+    >
+      <div class='pretui-formlayout-grid' data-columns={{this.columnsAttr}}>
+        {{yield
+          (hash
+            Field=(component
+              FormField form=@form section=@section layout=this.direction
+            )
+            Section=(component FormSection form=@form)
+            direction=this.direction
+            columns=this.columns
+          )
+        }}
+      </div>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-formlayout {
+          /* UNNAMED container only — see the module note. */
+          container-type: inline-size;
+          min-width: 0;
+          --pretui-field-label-width: var(--pretui-formlayout-label-width, 9rem);
+        }
+        .pretui-formlayout-grid {
+          display: grid;
+          gap: var(--pretui-formlayout-gap, var(--space-5, 14px));
+          align-content: start;
+          min-width: 0;
+        }
+        .pretui-formlayout-grid[data-columns='2'] {
+          grid-template-columns: repeat(2, minmax(0, 1fr));
+        }
+        .pretui-formlayout-grid[data-columns='3'] {
+          grid-template-columns: repeat(3, minmax(0, 1fr));
+        }
+        /* Two collapse steps, measured against the PANE. */
+        @container (max-width: 52rem) {
+          .pretui-formlayout-grid[data-columns='3'] {
+            grid-template-columns: repeat(2, minmax(0, 1fr));
+          }
+        }
+        @container (max-width: 34rem) {
+          .pretui-formlayout-grid[data-columns='2'],
+          .pretui-formlayout-grid[data-columns='3'] {
+            grid-template-columns: minmax(0, 1fr);
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/form-layout.md

@@ -0,0 +1,52 @@
+## What it is
+
+The grid a form's fields sit in: one or two (or three) columns, labels above or beside, collapsing to one column when the _pane_ gets narrow. Use it inside a **Form** via `form.Layout`, or stand-alone around a set of **FormField**s. For grouping fields under a heading with its own issue count, use **FormSection** — a section is a grid item and spans every column by default.
+
+## The contract
+
+```
+@direction? 'stacked' | 'horizontal'   (default 'stacked')
+@columns?   1 | 2 (3 allowed, collapses in two steps)
+@labelWidth? (default 9rem)  @gap? (default var(--space-5, 14px))
+@form?, @section?
+<:default as |layout|>   — { Field, Section, direction, columns }
+```
+
+**`@direction` is curried into the yielded `Field`.** You set label placement once on the layout and every field inside inherits it; a field can still override with its own layout arg. Same for the form and section args — a field laid out inside a section still counts toward that section's issue badge, because the layout passes the section registry through.
+
+**FormField**'s own span arg is SLDS's `_2-col`: a field can claim more than one grid column.
+
+## Prior art
+
+This is **SLDS's `.slds-form`** (`_stacked` / `_horizontal`) plus `slds-form__row` / `slds-form__item`, collapsed into one grid. **React Spectrum's `Form`** takes a similar `labelPosition` (`top`/`side`) and `labelAlign`, and Spectrum's grid is `maxWidth`-driven. **Web Awesome** has no form layout at all — each control owns its own label placement.
+
+The improvement is specific and, in a card kit, decisive: **SLDS breaks its columns on `@media (min-width: 48em)` — the viewport.** A two-column form in a 320px side panel of a 1600px window stays two columns and shreds. Pretui measures the **pane** with a container query, so the same form collapses correctly wherever it is embedded. In a system where a card can be rendered at any size in any host, viewport media queries are simply the wrong instrument, and this is the clearest example of why.
+
+Two implementation details worth knowing, because they look like accidents and are not:
+
+- **The queries are unnamed.** Named container queries are forbidden in realm code: the scoped-CSS transpiler silently drops every rule after one, so a single `@container name (...)` would delete the rest of the stylesheet with no error anywhere. This is a platform trap, not a style preference.
+- **There are two nested elements** — `.pretui-formlayout` (the container) wrapping `.pretui-formlayout-grid` (what the queries restyle) — because an unnamed container query resolves against the nearest _ancestor_ container, so a rule inside one can never match the container element itself. The extra div is load-bearing.
+
+## Accessibility
+
+No APG pattern; this is layout. Roles, labelling and messaging all belong to **FormField** and **FormSection**.
+
+What matters here, and what does not:
+
+- **Visual order and DOM order must agree.** The grid uses `grid-template-columns` and normal flow, with `@span` widening items rather than reordering them — so the tab sequence follows the reading order, and WCAG **1.3.2 Meaningful Sequence** and **2.4.3 Focus Order** are satisfied by construction. Any layout that achieved two columns by `grid-column` placement or `order` would break both; this one cannot.
+- **Column collapse is a reflow win.** Because the breakpoint is the container, a form inside a narrow pane genuinely reflows to one column — WCAG **1.4.10 Reflow** is met at the pane level, not just at 320px viewport width, which is a stronger guarantee than the media-query version gives you.
+- `@direction='horizontal'` puts the label beside the control at a fixed `@labelWidth`. At large text sizes (WCAG **1.4.4**, 200% zoom) a 9rem label column can clip long labels; nothing here enforces wrapping, so prefer `stacked` for long labels.
+
+Gaps:
+
+- **The layout is not a group.** There is no `role="group"`, no `aria-label`, and no `<fieldset>` — deliberately, because that is **FormSection**'s job. But it means a bare `FormLayout` outside a section gives assistive tech no grouping at all, and a two-column form is announced as one flat run of fields.
+- **`@columns={{3}}` is allowed and collapses in two steps**, but three columns of form fields is very hard to scan and there is no warning. Prefer two.
+- Nothing associates the columns with anything; a screen-reader user has no signal that fields are laid out side by side, which is correct (it is presentational) but worth stating.
+
+## Theming
+
+`--space-5` (the default gap, overridable via `@gap`), the label column width (`@labelWidth`, default `9rem`), and whatever **FormField** consumes. The layout itself paints nothing — no background, no border, no shadow.
+
+`data-direction` and `data-columns` are reflected on the container, so a stylesheet can hook either without reaching into the grid. Because the breakpoints are container queries, a theme cannot retune them through tokens; changing where columns collapse means editing the component.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/form-layout.usage.gts

@@ -0,0 +1,200 @@
+// Pretui — FormLayout usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Input } from './input';
+import { Textarea } from './textarea';
+import { Form } from './form';
+import type { FormIssue } from '../internal/forms-core';
+import { LAYOUTS } from '../demo-forms-core';
+
+// ── FormLayout ───────────────────────────────────────────────────────────
+const OPPORTUNITY_ISSUES: FormIssue[] = [
+  {
+    ruleId: 'opp-close-date-quarter',
+    targetPath: '"Close Date"',
+    severity: 'warning',
+    message:
+      'Close date falls after the spring booking window closes on 2026-04-30.',
+  },
+];
+
+// SLDS's .slds-form (_stacked / _horizontal) plus slds-form__row /
+// slds-form__item, as one grid. Dropped: the __row / __item wrappers
+// themselves — a grid does not need a row element, and role='list' /
+// role='listitem' on a form's fields (which SLDS's record-detail applies) is
+// a semantic that helps nobody read a form.
+class FormLayoutUsage extends Component {
+  directionOptions = LAYOUTS;
+
+  @tracked direction = 'horizontal';
+  @tracked columns = 2;
+  @tracked labelWidth = '9rem';
+
+  @tracked contactName = 'Priya Raghunathan';
+  @tracked title = 'Head of Sourcing';
+  @tracked email = 'priya@nilgirileaf.coop';
+  @tracked phone = '+91 423 555 0148';
+  @tracked notes = 'Prefers the Nilgiri second flush shipped ahead of the monsoon.';
+
+  setDirection = (v: string) => (this.direction = v);
+  setColumns = (v: number | null) => (this.columns = v ?? 1);
+  setLabelWidth = (v: string) => (this.labelWidth = v);
+  setContactName = (v: string) => (this.contactName = v);
+  setTitle = (v: string) => (this.title = v);
+  setEmail = (v: string) => (this.email = v);
+  setPhone = (v: string) => (this.phone = v);
+  setNotes = (v: string) => (this.notes = v);
+
+  issues = OPPORTUNITY_ISSUES;
+
+  get directionVal() {
+    return this.direction as 'stacked' | 'horizontal';
+  }
+  get usage() {
+    let bits = [`@direction='${this.direction}'`, `@columns={{${this.columns}}}`];
+    return `<FormLayout ${bits.join(' ')} as |grid|>\n  <grid.Field @label='Name' @path='Name'>…</grid.Field>\n  <grid.Field @label='Notes' @path='Notes' @span={{2}}>…</grid.Field>\n</FormLayout>`;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='FormLayout'
+      @description="Stacked or horizontal, one to three columns, and it measures the PANE rather than the window — SLDS breaks its columns on @media (min-width: 48em), so a two-column form in a 320px side panel of a 1600px window stays two columns and shreds. This one uses unnamed container queries (the named form would silently delete every rule after it), collapsing three columns to two at 52rem and everything to one at 34rem, where horizontal labels also drop back above their controls. It yields a Field already curried with the direction and the form context. Drag the artboard narrow to watch it fold. Honest limit: a field can only span whole columns (@span), there is no row-and-cell addressing."
+      @source={{this.usage}}
+      @viewportMode='fill'
+    >
+      <:example>
+        <Form @mode='live' @issues={{this.issues}} @label='Contact' as |form|>
+          <form.Layout
+            @direction={{this.directionVal}}
+            @columns={{this.columns}}
+            as |grid|
+          >
+            <grid.Field @label='Contact Name' @path='Name' @required={{true}}>
+              <:control as |c|>
+                <Input
+                  @controlId={{c.id}}
+                  @value={{this.contactName}}
+                  @onInput={{this.setContactName}}
+                  aria-describedby={{c.describedBy}}
+                />
+              </:control>
+            </grid.Field>
+            <grid.Field @label='Title' @path='Title'>
+              <:control as |c|>
+                <Input
+                  @controlId={{c.id}}
+                  @value={{this.title}}
+                  @onInput={{this.setTitle}}
+                  aria-describedby={{c.describedBy}}
+                />
+              </:control>
+            </grid.Field>
+            <grid.Field @label='Email' @path='Email'>
+              <:control as |c|>
+                <Input
+                  @controlId={{c.id}}
+                  @type='email'
+                  @value={{this.email}}
+                  @onInput={{this.setEmail}}
+                  aria-describedby={{c.describedBy}}
+                />
+              </:control>
+            </grid.Field>
+            <grid.Field @label='Phone' @path='Phone'>
+              <:control as |c|>
+                <Input
+                  @controlId={{c.id}}
+                  @type='tel'
+                  @value={{this.phone}}
+                  @onInput={{this.setPhone}}
+                  aria-describedby={{c.describedBy}}
+                />
+              </:control>
+            </grid.Field>
+            <grid.Field
+              @label='Close Date'
+              @path='"Close Date"'
+              @static={{true}}
+              @value='2026-05-07'
+              @description='Rolled up from the spring booking window.'
+            />
+            <grid.Field @label='Account' @path='Account' @readonly={{true}}>
+              <:control as |c|>
+                <Input
+                  @controlId={{c.id}}
+                  @value='Nilgiri Leaf Cooperative'
+                  aria-describedby={{c.describedBy}}
+                  readonly={{true}}
+                />
+              </:control>
+            </grid.Field>
+            <grid.Field @label='Sourcing Notes' @path='Description' @span={{2}}>
+              <:control as |c|>
+                <Textarea
+                  @controlId={{c.id}}
+                  @value={{this.notes}}
+                  @onInput={{this.setNotes}}
+                  aria-describedby={{c.describedBy}}
+                />
+              </:control>
+            </grid.Field>
+          </form.Layout>
+        </Form>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='direction'
+          @defaultValue='stacked'
+          @value={{this.direction}}
+          @options={{this.directionOptions}}
+          @description='Curried into every yielded Field: labels above (stacked) or beside (horizontal).'
+          @onInput={{this.setDirection}}
+        />
+        <Args.Number
+          @name='columns'
+          @defaultValue={{1}}
+          @value={{this.columns}}
+          @min={{1}}
+          @max={{3}}
+          @description='1–3 grid columns, collapsing 3→2 at 52rem and →1 at 34rem of CONTAINER width.'
+          @onInput={{this.setColumns}}
+        />
+        <Args.String
+          @name='labelWidth'
+          @defaultValue='9rem'
+          @value={{this.labelWidth}}
+          @description='Label column width in the horizontal direction — documented as the --pretui-formlayout-label-width knob below.'
+          @onInput={{this.setLabelWidth}}
+        />
+        <Args.String
+          @name='gap'
+          @description='Gap between fields; also settable as --pretui-formlayout-gap.'
+        />
+        <Args.Object
+          @name='form'
+          @description='The owning FormContext, passed straight through to the yielded Field. Supplied automatically by form.Layout.'
+        />
+        <Args.Yield
+          @description='Receives { Field, direction, columns }. Field is FormField pre-curried with the form context and the direction.'
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='--pretui-formlayout-gap'
+          @value='var(--space-5, 14px)'
+          @description='Gap between fields in both axes.'
+        />
+        <Css.Basic
+          @name='--pretui-formlayout-label-width'
+          @value='9rem'
+          @description='Label column width handed down to every horizontal field in the grid.'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_FORM_LAYOUT: Record<string, unknown> = {
+  FormLayout: FormLayoutUsage,
+};