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

package/bundled-realms/pretui/components/field-error.md

@@ -0,0 +1,60 @@
+## What it is
+
+One validation issue, rendered. It is the atom of the forms territory's messaging — **FormField** uses it for routed issues, **ErrorSummary** composes rows from the same data, and you can use it directly for an issue that belongs to no field. If you want the whole list, use **ErrorSummary**; if you want a page-level banner, use **Alert**.
+
+## The contract
+
+```
+@issue: FormIssue   (required)
+@announce?          — add role='alert'. Default false.
+@showRuleId?        — print issue.ruleId as a mono Token
+```
+
+`FormIssue` is `{ targetPath, severity, message, ruleId? }`.
+
+Two decisions carry the component.
+
+**The message is printed verbatim.** A rule author wrote it; rewriting rule copy in a component is how enterprise forms end up lying about what actually failed. There is no truncation, no sentence-casing, no "Please" prefix.
+
+**Severity normalisation fails closed.** `normalizeSeverity` returns `'warning'` or `'info'` only for exactly those two strings. Anything else — `undefined`, `''`, `'critical'`, `'ERROR'`, a typo — resolves to `'error'` and therefore **blocks the commit**. This mirrors the BXL guide contract, where a rule that cannot be evaluated counts as a failure. A misspelled severity making a form stricter is the safe direction to fail.
+
+`@showRuleId` renders `issue.ruleId` as a mono **Token** after the message — provenance for rule authors debugging why a form refused, and off by default because end users should never see it.
+
+## Prior art
+
+Ported from **React Spectrum's `<FieldError>`**, which is errors-only and unstyled by severity, and **SLDS's `.slds-form-element__help`**, which is one flat red line with no severity concept at all. Neither library has severity tiers on a field message.
+
+Pretui's improvements, each concrete:
+
+- **Three severities** on the kit's Law 2 hue treatment — one hue in, a complete treatment out — so error, warning and info are one recipe rather than three stylesheets.
+- **Fail-closed normalisation** (above). Neither reference normalises at all; an unknown severity in SLDS is simply an unstyled message.
+- **Optional rule provenance** as a Law 3 Token.
+- **A deliberate live-region policy**, which is the part everyone gets wrong.
+
+The glyph vocabulary (`✕` / `!` / `i`) is shared with **Alert**, so a field message and a banner about the same thing read as one system.
+
+## Accessibility
+
+No APG pattern. The governing criteria are WCAG **3.3.1 Error Identification** and **4.1.3 Status Messages**, and the interesting decision here is a live-region one.
+
+**Stated plainly: `role="alert"` interrupts.** A field message that re-renders on every keystroke must never be a live region, or a screen-reader user is talked over while typing. So `@announce` is opt-in, and **FormField only turns it on in `record` mode**, where an error appears as the result of one discrete commit. In `submit` mode the **ErrorSummary** announces by taking focus. In `live` mode nothing announces at all — and the message is still read whenever the field itself is focused, because FormField already put this element's id in the control's `aria-describedby`.
+
+That last clause is what makes the restraint safe. The message is always reachable; the question is only whether it interrupts.
+
+Gaps and cautions:
+
+- **Severity is not exposed to assistive tech.** The glyph is decorative and the hue is visual; a warning and an error are announced identically as message text. `role="alert"` versus `role="status"` would be the natural distinction (assertive for blocking, polite for advisory) and it is not made — `@announce` produces `role="alert"` regardless of severity. Worth fixing.
+- **Nothing prefixes the message with "Error:".** GOV.UK's pattern adds a visually-hidden prefix to the inline message so a screen-reader user hears the severity before the text. Here they hear only the text.
+- **`role="alert"` on a message that is already in `aria-describedby`** will be announced twice when the field receives focus after the alert fires. This is inherent to the pattern rather than a Pretui bug, but it is the reason `@announce` is scoped to `record` mode.
+- **The glyph is `aria-hidden`**, so "✕" is never part of the announced text; the message carries the meaning.
+- **Using `@announce` directly, outside FormField, is easy to get wrong.** The rule of thumb from the source is the one to follow: turn it on only where the message appears as the result of a discrete commit, never on a control that revalidates per keystroke.
+
+## Theming
+
+Severity hues: `--destructive` (error), `--warning`, `--pretui-info`, each feeding the Law 2 treatment that derives ink, glyph and any tint from the single hue. Type: `--text-ui-sm`. Provenance: **Token**'s `--font-mono`, `--inset`, `--muted-foreground`, `--pretui-shadow-hairline`.
+
+Because severity is carried by **glyph and hue together**, it survives WCAG 1.4.1 (Use of Color) even in a theme whose warning and error hues are close. Removing the glyphs would break that — they are not decoration.
+
+A theme must define `--warning` and `--pretui-info` legibly at 11.5px against `--card`; amber and pale blue at small sizes are the two most common contrast failures in this territory.
+
+The styles sit in `@layer PretComposite`, above Token's `PretComponent` layer, so what this component sets on Token wins by layer order. A caller's unlayered CSS overrides both without a more specific selector.

package/bundled-realms/pretui/components/field-error.usage.gts

@@ -0,0 +1,146 @@
+// Pretui — FieldError usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { FieldError } from './field-error';
+import type { FormIssue } from '../internal/forms-core';
+
+// ── FieldError ───────────────────────────────────────────────────────────
+const SEVERITIES = ['error', 'warning', 'info', 'critical'];
+
+// Ported from React Spectrum's <FieldError> (errors only, no severity) and
+// SLDS's .slds-form-element__help (one flat style). Dropped: React
+// Spectrum's render-prop signature — the message is authored by a rule and
+// printed verbatim, so there is nothing for a render prop to reshape.
+class FieldErrorUsage extends Component {
+  severityOptions = SEVERITIES;
+
+  @tracked severity = 'error';
+  @tracked message =
+    'Da Hong Pao lot DHP-04 is booked at 96 kg against an 84 kg allocation.';
+  @tracked ruleId = 'lot-allocation-ceiling';
+  @tracked announce = false;
+  @tracked showRuleId = true;
+
+  setSeverity = (v: string) => (this.severity = v);
+  setMessage = (v: string) => (this.message = v);
+  setRuleId = (v: string) => (this.ruleId = v);
+  setAnnounce = (v: boolean) => (this.announce = v);
+  setShowRuleId = (v: boolean) => (this.showRuleId = v);
+
+  get issue(): FormIssue {
+    return {
+      ruleId: this.ruleId,
+      targetPath: '"Line Item"[SKU = "DHP-04"].Quantity',
+      severity: this.severity,
+      message: this.message,
+    };
+  }
+  get resolvedNote() {
+    return this.severity === 'error' ||
+      this.severity === 'warning' ||
+      this.severity === 'info'
+      ? `severity '${this.severity}' is known`
+      : `severity '${this.severity}' is unknown → renders as error (fail closed)`;
+  }
+  get usage() {
+    let bits = ['@issue={{this.issue}}'];
+    if (this.announce) bits.push('@announce={{true}}');
+    if (this.showRuleId) bits.push('@showRuleId={{true}}');
+    return `<FieldError ${bits.join(' ')} />`;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='FieldError'
+      @description="One issue, rendered. Three severities on the Law 2 hue treatment, sharing Alert's glyph vocabulary so a field message and a banner about the same thing read as one system. Unknown severities FAIL CLOSED — anything that is not exactly 'warning' or 'info' renders and blocks as an error, matching the guide contract where an unevaluable rule counts as a failure. The live-region policy is deliberate: role='alert' interrupts, so @announce is opt-in and FormField only turns it on in record mode, where the message follows one discrete commit. In submit mode the ErrorSummary announces by taking focus; in live mode nothing announces and the message is still read when the field is focused, because it is in the control's aria-describedby."
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='demo-forms-errorstage'>
+          <FieldError
+            @issue={{this.issue}}
+            @announce={{this.announce}}
+            @showRuleId={{this.showRuleId}}
+          />
+          <p class='demo-forms-readout'>{{this.resolvedNote}}</p>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='severity'
+          @defaultValue='error'
+          @value={{this.severity}}
+          @options={{this.severityOptions}}
+          @description="Demo knob writing issue.severity. 'critical' is in the list on purpose: it is not a known severity, so it must render as an error."
+          @onInput={{this.setSeverity}}
+        />
+        <Args.String
+          @name='message'
+          @value={{this.message}}
+          @description='Demo knob writing issue.message. Rendered verbatim — a rule author wrote it, and rewriting rule copy in a component is how enterprise forms end up lying about what failed.'
+          @onInput={{this.setMessage}}
+        />
+        <Args.String
+          @name='ruleId'
+          @value={{this.ruleId}}
+          @description='Demo knob writing issue.ruleId — optional provenance back to the rule.'
+          @onInput={{this.setRuleId}}
+        />
+        <Args.Bool
+          @name='announce'
+          @defaultValue={{false}}
+          @value={{this.announce}}
+          @description="Add role='alert'. Only where the message appears as the result of a discrete commit — never on a control that revalidates per keystroke."
+          @onInput={{this.setAnnounce}}
+        />
+        <Args.Bool
+          @name='showRuleId'
+          @defaultValue={{false}}
+          @value={{this.showRuleId}}
+          @description='Print issue.ruleId as a mono accent-tinted Token (Law 3 — machine values look like machine values).'
+          @onInput={{this.setShowRuleId}}
+        />
+        <Args.Object
+          @name='issue'
+          @required={{true}}
+          @description='The FormIssue: { targetPath, severity, message, ruleId? }.'
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='--pretui-issue-error'
+          @value='var(--destructive)'
+          @description='Hue for the error severity; the whole treatment derives from it.'
+        />
+        <Css.Basic
+          @name='--pretui-issue-warning'
+          @value='var(--warning)'
+          @description='Hue for the warning severity.'
+        />
+        <Css.Basic
+          @name='--pretui-issue-info'
+          @value='var(--pretui-info)'
+          @description='Hue for the info severity.'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+    <style scoped>
+      .demo-forms-errorstage {
+        display: grid;
+        gap: 6px;
+        max-width: 28rem;
+      }
+      .demo-forms-readout {
+        margin: 0;
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_FIELD_ERROR: Record<string, unknown> = {
+  FieldError: FieldErrorUsage,
+};

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

@@ -0,0 +1,185 @@
+// Pretui — Field: label[for] + reserved message line so side-by-side fields
+// never shift when an error appears (alignment law).
+import Component from '@glimmer/component';
+import { guidFor } from '@ember/object/internals';
+import { firstDefined, resolveTone } from '../pretui-primitives';
+import type { PretuiToneArg } from '../pretui-primitives';
+import { Cue, CUE_TONES } from './cue';
+import type { CueKind, CueTone } from './cue';
+
+export interface FieldSignature {
+  Args: {
+    label?: string;
+    hint?: string;
+    error?: string;
+    /** aliases for @hint — shadcn/Aria/Chakra `description`, MUI
+     * `helperText`. Slots still win when the caption needs markup. */
+    description?: string;
+    helperText?: string;
+    /** alias for @error — the React Aria / shadcn Field spelling */
+    errorMessage?: string;
+    /**
+     * A polite, transient status for the field — "Checking availability…",
+     * "Saved". Ranks between error and hint, rides the reserved message line
+     * so nothing moves, and announces itself when it changes.
+     */
+    status?: string;
+    /** tone for that status line (default 'info') */
+    statusTone?: CueTone | PretuiToneArg;
+  };
+  Blocks: {
+    /** the control. Second param is the id of the message line, for
+     * `aria-describedby` on a control that does not take it automatically. */
+    default: [controlId: string, describedBy: string];
+    /** cue accessory at the reading start of the control row */
+    inlineStart: [];
+    /** cue accessory at the reading end of the control row */
+    inlineEnd: [];
+  };
+  Element: HTMLDivElement;
+}
+
+// THE wrapper every input needs: label[for] + reserved message line so
+// side-by-side fields never shift when an error appears (alignment law).
+//
+// The message line is a `Cue`, so its tone carries a glyph as well as a
+// color and a status announces itself. `<:inlineStart>` / `<:inlineEnd>` hold
+// accessories at the LOGICAL edges of the control row (a currency prefix, a
+// unit suffix, a verified tick). The message line's id is the block's second
+// param, so a control can point `aria-describedby` at it.
+export class Field extends Component<FieldSignature> {
+  get controlId() {
+    return `${guidFor(this)}-ctl`;
+  }
+  get messageId() {
+    return `${guidFor(this)}-msg`;
+  }
+  get error() {
+    return firstDefined(this.args.error, this.args.errorMessage);
+  }
+  get hint() {
+    return firstDefined(
+      this.args.hint,
+      this.args.description,
+      this.args.helperText,
+    );
+  }
+  get messageKind(): CueKind {
+    if (this.error) return 'error';
+    if (this.args.status) return 'status';
+    return 'description';
+  }
+  get messageTone(): CueTone {
+    if (this.error) return 'danger';
+    if (this.args.status) return resolveTone(this.args.statusTone, CUE_TONES, 'info');
+    return 'neutral';
+  }
+  get messageText() {
+    return this.error ?? this.args.status ?? this.hint;
+  }
+  <template>
+    <div class='pretui-fieldw' data-invalid={{if this.error 'true'}} data-test-pretui-field ...attributes>
+      {{#if @label}}<label for={{this.controlId}}>{{@label}}</label>{{/if}}
+      {{! The row wrapper appears ONLY when an accessory does. A Field with no
+          accessories keeps the exact DOM it has always had — the control
+          stays a direct grid child, so a caller yielding two elements still
+          gets two grid rows, and every existing selector still matches. }}
+      {{#if (has-block 'inlineStart')}}
+        <div class='pretui-fieldrow'>
+          <span class='pretui-fieldcue'>{{yield to='inlineStart'}}</span>
+          <div class='pretui-fieldctl'>{{yield this.controlId this.messageId}}</div>
+          {{#if (has-block 'inlineEnd')}}
+            <span class='pretui-fieldcue'>{{yield to='inlineEnd'}}</span>
+          {{/if}}
+        </div>
+      {{else if (has-block 'inlineEnd')}}
+        <div class='pretui-fieldrow'>
+          <div class='pretui-fieldctl'>{{yield this.controlId this.messageId}}</div>
+          <span class='pretui-fieldcue'>{{yield to='inlineEnd'}}</span>
+        </div>
+      {{else}}
+        {{yield this.controlId this.messageId}}
+      {{/if}}
+      <div class='pretui-fieldmsg'>
+        {{#if this.messageText}}
+          <Cue
+            @kind={{this.messageKind}}
+            @tone={{this.messageTone}}
+            @text={{this.messageText}}
+            @id={{this.messageId}}
+          />
+        {{/if}}
+      </div>
+    </div>
+    <style scoped>
+      /* above Input's layer, so these win by layer order, not file order */
+      @layer PretComponent, PretComposite;
+      @layer PretComposite {
+        .pretui-fieldw {
+          display: grid;
+          gap: var(--boxel-sp-3xs);
+          grid-template-rows: auto auto auto;
+          align-content: start;
+          justify-items: start;
+        }
+        .pretui-fieldw > label {
+          font-size: var(--boxel-ui-label-font-size);
+          font-weight: var(--boxel-ui-label-font-weight);
+          line-height: var(--boxel-ui-label-line-height);
+          color: var(--foreground);
+        }
+        /* the control row: accessories sit at the LOGICAL edges, so an RTL
+           reading order moves them without a second rule */
+        .pretui-fieldrow {
+          display: flex;
+          align-items: center;
+          justify-self: stretch;
+          min-width: 0;
+        }
+        .pretui-fieldctl {
+          flex: 1;
+          min-width: 0;
+        }
+        .pretui-fieldcue {
+          flex: none;
+        }
+        .pretui-fieldctl > :deep(.pretui-input),
+        .pretui-fieldctl > :deep(.pretui-inputwrap),
+        .pretui-fieldctl > :deep(.pretui-boxelwrap),
+        .pretui-fieldctl > :deep(.pretui-selectwrap) {
+          width: 100%;
+        }
+        .pretui-fieldw > :deep(.pretui-input),
+        .pretui-fieldw > :deep(.pretui-inputwrap),
+        .pretui-fieldw > :deep(.pretui-boxelwrap),
+        .pretui-fieldw > :deep(.pretui-selectwrap) {
+          justify-self: stretch;
+        }
+        .pretui-fieldmsg {
+          min-height: 1rem;
+          line-height: 1rem;
+        }
+        /* the hint / error spans are gone: the message line is a <Cue>, which
+           brings its own type scale, its own tone and its own glyph */
+        .pretui-fieldw[data-invalid] :deep(.pretui-input) {
+          box-shadow: 0 0 0 1px var(--destructive);
+          background-color: color-mix(in oklch, var(--destructive) 4%, var(--field));
+        }
+        /* boxel-ui-wrapped controls: the invalid dress travels through the
+           token channel — repoint the wrapper's --border/--background and the
+           inner BoxelInput re-dresses itself; no CSS reaches boxel markup.
+           A control sets --pretui-invalid-border/-background on its wrapper
+           to choose its own dress. */
+        .pretui-fieldw[data-invalid] :deep(.pretui-inputwrap),
+        .pretui-fieldw[data-invalid] :deep(.pretui-boxelwrap) {
+          --border: var(--pretui-invalid-border, var(--destructive));
+          --background: var(
+            --pretui-invalid-background,
+            color-mix(in oklch, var(--destructive) 4%, var(--field))
+          );
+        }
+      }
+    </style>
+  </template>
+}
+

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

@@ -0,0 +1,60 @@
+## What it is
+
+The wrapper every control needs: a label bound to the control by id, and a **reserved message line** below it. Reach for it whenever you put an **Input**, **Textarea**, **Select** or **Switch** on a surface outside a **Form**. Inside a Form, use **FormField** instead — it does everything Field does _and_ subscribes to the form's issue store, so validation state arrives without being threaded through. Field is the standalone, uncontrolled-validation version; FormField is the form-aware one.
+
+## The contract
+
+```
+@label?, @hint?, @error?
+<:default as |controlId|>
+Element: HTMLDivElement
+```
+
+Two decisions carry the component.
+
+**It mints the id and yields it.** `guidFor(this) + '-ctl'` goes on `<label for>` and is handed to the block, which passes it to the control's own id arg. Ownership of the association sits in exactly one place, and no control has to generate an id it might collide on. The cost is real and worth stating: **a control that takes no id arg cannot be labeled through this API at all** — which currently rules out `RadioGroup`, `Slider`, `Checkbox` and `Rating`.
+
+**The message line is always there.** `.pretui-fieldmsg` has `min-height: 1rem` whether or not there is anything to say. This is the kit's alignment law: two fields side by side never shift when an error appears on one of them. Every design system eventually learns this; most learn it after shipping the jump.
+
+`@error` takes precedence over `@hint` — one line, error wins — rather than stacking both. That keeps the reserved height at exactly one line and forces the hint to be genuinely optional guidance rather than something the user needs while fixing an error.
+
+## Prior art
+
+**React Aria `useField`** is the reference: it generates label, description and error ids with `useSlotId` so they are `undefined` when the slot is empty (no dangling idrefs) and returns four prop bags. **Radix `Form`** goes further with `Field name` auto-associating label ↔ control ↔ message and `Message match` accepting native `ValidityState` matchers. **Web Awesome** has no field wrapper at all — each control owns `label` and `hint` as both props and slots, with `with-label`/`with-hint` booleans for SSR slot detection.
+
+Pretui's yielded-id shape is closest to Radix's implicit association but explicit about it, which makes it obvious at the call site which control the label belongs to — useful when a "field" contains two controls.
+
+Where Pretui is genuinely better than all three: **the invalid dress travels through the token channel.** `Field` sets `data-invalid` on itself, and its own stylesheet repoints `--border` and `--background` on any `.pretui-inputwrap` or `.pretui-boxelwrap` descendant. A control picks its own invalid dress by setting `--pretui-invalid-border` and `--pretui-invalid-background` on its wrapper; Input uses a `--destructive-ink` edge and no tint, and the rest default to a `--destructive` edge with a 4% tint. The inner boxel-ui control re-dresses itself; **no Pretui CSS reaches into boxel markup**, so a boxel-ui upgrade cannot break the error styling, and a theme can redefine what "invalid" looks like by changing one token. Compare the usual approach of threading an `isError` prop down through three components.
+
+Where it is behind: no `aria-describedby` wiring (below), no required/optional marker of its own, and no support for grouped controls.
+
+## Accessibility
+
+No APG pattern — this is wiring, governed by WCAG **3.3.1 Error Identification**, **3.3.2 Labels or Instructions** and **4.1.2 Name, Role, Value**.
+
+What works: `<label for={{controlId}}>` gives a real programmatic label, and clicking the label focuses the control.
+
+Gaps, and they matter:
+
+- **The hint and error are not wired to the control.** There is no `aria-describedby`, and neither message element carries an id. A screen-reader user hears the label and the control's value; the hint and the error text are floating content they may or may not encounter. React Aria's `useField` exists precisely to solve this, and it is the standard.
+- **`@error` sets no `aria-invalid` on the control.** `data-invalid` drives the red dress and nothing else. Visually the field is clearly wrong; to assistive tech it is unremarkable. This is a direct 3.3.1 failure when Field is used standalone.
+- Worth noting what the ecosystem has settled on: `aria-errormessage` is still poorly supported, and React Aria carries an explicit code comment that it uses `aria-describedby` for error text "because `aria-errormessage` is unsupported using VoiceOver or NVDA". If Field adds wiring, `aria-describedby` carrying both description and error ids is the shape to copy, with `aria-errormessage` added only additively.
+- **Controls without a `@controlId` arg cannot be associated.** Wrapping a `RadioGroup` or `Slider` in a `Field` produces a visible label pointing at nothing — `for` references an id that no element has. That is worse than no label, because it looks correct in review.
+- No `aria-required` and no required marker.
+
+Use **FormField** for anything validated. Field is right for a labeled control on a settings panel, not for a form that reports errors.
+
+## Theming
+
+`--foreground` (label ink), `--muted-foreground` (hint ink, through Cue), `--destructive` (error ink, through Cue, and the other controls' invalid hairline/tint), `--destructive-ink` (an invalid Input's edge), `--field` (the tinted invalid background base), the label role (`--boxel-ui-label-*`), `--text-ui-sm` (messages, through Cue).
+
+Repointed into descendants when invalid: on an **Input**, `--border` → `--destructive-ink`, matching Select and Autocomplete; on Textarea and the other boxel-ui-wrapped controls, `--border` → `--destructive` and `--background` → a 4% `--destructive` mix over `--field`.
+
+The `--boxel-sp-3xs` row gap and 1rem reserved message line are fixed. A theme must keep `--muted-foreground` and `--destructive` distinguishable at 11.5px — hint and error occupy the same slot, so weight (500 on the error) plus hue is the only differentiator, and hue alone fails WCAG 1.4.1.
+
+The styles sit in `@layer PretComposite`, above Input's `PretComponent` layer, so what this component sets on Input wins by layer order. A caller's unlayered CSS overrides both without a more specific selector.
+
+## React ecosystem
+
+shadcn `Field` / Aria Field. **FormField** is the form-kit wrapper.
+Accept `errorMessage` / `description` string sugar.

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

@@ -0,0 +1,73 @@
+// Pretui — Field usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Field } from './field';
+import { Input } from './input';
+
+// ── Field ← field-container/usage.gts ────────────────────────────────────
+// Dropped knobs: @tag (Field renders a fixed div wrapper), @fieldId (a
+// controlId is generated and yielded instead), @icon (no icon slot),
+// @vertical (Field is vertical-only by design), @inline (no compact
+// horizontal layout), @horizontalLabelSize / @labelFontSize (no horizontal
+// label column), @centeredDisplay (no centered display mode).
+export class FieldUsage extends Component {
+  @tracked label = 'Full Name of the Issuer';
+  @tracked hint = 'As printed on the certificate';
+  @tracked error = '';
+  @tracked value = 'Gary Walker';
+  setLabel = (v: string) => (this.label = v);
+  setHint = (v: string) => (this.hint = v);
+  setError = (v: string) => (this.error = v);
+  setValue = (v: string) => (this.value = v);
+  get usage() {
+    let bits = [`@label='${this.label}'`];
+    if (this.hint) bits.push(`@hint='${this.hint}'`);
+    if (this.error) bits.push(`@error='${this.error}'`);
+    return `<Field ${bits.join(' ')} as |controlId|>…</Field>`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Field'
+      @description='Form-field wrapper that pairs a label with its input control, plus helper text and validation messages — the standard layout primitive for form rows.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <Field @label={{this.label}} @hint={{this.hint}} @error={{this.error}} as |controlId|>
+          <Input
+            @controlId={{controlId}}
+            @value={{this.value}}
+            @onInput={{this.setValue}}
+          />
+        </Field>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='label'
+          @value={{this.label}}
+          @description='field label'
+          @onInput={{this.setLabel}}
+        />
+        <Args.String
+          @name='hint'
+          @value={{this.hint}}
+          @description='Helper text on the reserved message line — no layout shift when it appears.'
+          @onInput={{this.setHint}}
+        />
+        <Args.String
+          @name='error'
+          @value={{this.error}}
+          @description='Error message — replaces hint on the reserved message line and paints the inner input invalid.'
+          @onInput={{this.setError}}
+        />
+        <Args.Yield
+          @description="Yield value or form field; yields the generated controlId — wire it to the control's @controlId for label association."
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_FIELD: Record<string, unknown> = {
+  Field: FieldUsage,
+};

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

@@ -0,0 +1,124 @@
+// Pretui — Fieldset: a real <fieldset> with a <legend>. Disabling it
+// disables every control inside through the platform, and the legend is the
+// group's accessible name. FormSection is the form-aware region with issue
+// counts and a disclosure; this is the thin primitive it stands on.
+import Component from '@glimmer/component';
+import { guidFor } from '@ember/object/internals';
+import { firstDefined } from '../pretui-primitives';
+
+export type FieldsetOrientation = 'vertical' | 'horizontal';
+
+export interface FieldsetSignature {
+  Args: {
+    /** the group's name; sugar for <:legend> */
+    legend?: string;
+    /** prose under the legend, wired to the group with aria-describedby */
+    description?: string;
+    /** native fieldset disabling — every control inside goes inert */
+    disabled?: boolean;
+    /** alias — React Aria / Base UI spelling of @disabled */
+    isDisabled?: boolean;
+    /** keep the legend for assistive tech but do not paint it */
+    hideLegend?: boolean;
+    /** `vertical` (default) stacks the controls; `horizontal` flows them in a row */
+    orientation?: FieldsetOrientation;
+  };
+  Blocks: {
+    /** the legend, when it needs markup; wins over @legend */
+    legend: [];
+    /** the controls */
+    default: [];
+  };
+  Element: HTMLFieldSetElement;
+}
+
+export class Fieldset extends Component<FieldsetSignature> {
+  descId = `${guidFor(this)}-desc`;
+  get disabled() {
+    return firstDefined(this.args.disabled, this.args.isDisabled) ?? false;
+  }
+  get orientation(): FieldsetOrientation {
+    return this.args.orientation ?? 'vertical';
+  }
+  <template>
+    <fieldset
+      class='pretui-fieldset'
+      data-orientation={{this.orientation}}
+      disabled={{this.disabled}}
+      aria-describedby={{if @description this.descId}}
+      data-test-pretui-fieldset
+      ...attributes
+    >
+      {{#if (has-block 'legend')}}
+        <legend class='pretui-fieldset-legend' data-hidden={{if @hideLegend 'true' 'false'}}>
+          {{yield to='legend'}}
+        </legend>
+      {{else if @legend}}
+        <legend class='pretui-fieldset-legend' data-hidden={{if @hideLegend 'true' 'false'}}>
+          {{@legend}}
+        </legend>
+      {{/if}}
+      {{#if @description}}
+        <p class='pretui-fieldset-desc' id={{this.descId}}>{{@description}}</p>
+      {{/if}}
+      <div class='pretui-fieldset-body'>{{yield}}</div>
+    </fieldset>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-fieldset {
+          --fs-gap: var(--space-3, 0.5rem);
+          --fs-text: var(--text-ui-md, 0.78rem);
+          --fs-small: var(--text-ui-sm, 0.72rem);
+          --fs-strong: var(--weight-strong, 600);
+          margin: 0;
+          padding: 0;
+          border: 0;
+          min-inline-size: 0;
+          display: flex;
+          flex-direction: column;
+          gap: var(--fs-gap);
+          font-size: var(--fs-text);
+        }
+        .pretui-fieldset-legend {
+          margin: 0;
+          padding: 0;
+          font-weight: var(--fs-strong);
+          color: var(--foreground);
+        }
+        /* a <legend> is laid out outside the flex flow, so its spacing is its own */
+        .pretui-fieldset-legend + .pretui-fieldset-desc,
+        .pretui-fieldset-legend + .pretui-fieldset-body {
+          margin-block-start: calc(var(--fs-gap) * 0.75);
+        }
+        .pretui-fieldset-legend[data-hidden='true'] {
+          position: absolute;
+          inline-size: 1px;
+          block-size: 1px;
+          overflow: hidden;
+          clip-path: inset(50%);
+          white-space: nowrap;
+        }
+        .pretui-fieldset-desc {
+          margin: 0;
+          font-size: var(--fs-small);
+          color: var(--muted-foreground);
+        }
+        .pretui-fieldset-body {
+          display: flex;
+          flex-direction: column;
+          gap: var(--fs-gap);
+          min-inline-size: 0;
+        }
+        .pretui-fieldset[data-orientation='horizontal'] .pretui-fieldset-body {
+          flex-direction: row;
+          flex-wrap: wrap;
+          align-items: center;
+          column-gap: calc(var(--fs-gap) * 2);
+        }
+        .pretui-fieldset:disabled .pretui-fieldset-legend {
+          color: var(--muted-foreground);
+        }
+      }
+    </style>
+  </template>
+}