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

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

@@ -0,0 +1,315 @@
+// Pretui — Form: the host that owns issues, submit, and the context its parts register with.
+import Component from '@glimmer/component';
+import { modifier } from 'ember-modifier';
+import { on } from '@ember/modifier';
+import { hash } from '@ember/helper';
+import { CompoundField } from './compound-field';
+import { ErrorSummary } from './error-summary';
+import { FieldError } from './field-error';
+import { FormField } from './form-field';
+import { FormLayout } from './form-layout';
+import { FormSection } from './form-section';
+import { FormContext } from '../internal/forms-core';
+import type { FormFocusTarget, FormHost, FormIssue, FormMode } from '../internal/forms-core';
+
+// ── Form ─────────────────────────────────────────────────────────────────
+// The host. Three commit models, because a Boxel card autosaves and has no
+// submit — wiring a classic submit form into a card edit view is exactly
+// what sank the earlier attempt. SLDS had already solved this; the modes are
+// its three shapes made explicit:
+//
+//   @mode='submit'  commit on submit · validate on submit, focus first error
+//                   → React Spectrum classic. Errors are WITHHELD until the
+//                     user tries to commit.
+//   @mode='live'    commit per field, immediately · issues are ambient advice
+//                   and never a gate → the card-autosave shape. Submitting
+//                   does not refuse and does not move focus.
+//   @mode='record'  commit per field inline, saved as a batch · validate per
+//                   field plus a summary → the SLDS record-detail page. The
+//                   <:footer> block docks (sticky, not fixed) and its save
+//                   goes through the same gate as submit mode.
+//
+// @validationBehavior is React Spectrum's switch, same names: 'aria'
+// (default) puts `novalidate` on the form so the browser's own bubbles never
+// race ours; 'native' leaves native constraint validation switched on.
+//
+// The form NEVER validates. It is handed FormIssue[] and does three things
+// with them: routes them to fields by whole-string path equality, gates the
+// commit on the blocking ones, and moves focus when it refuses.
+
+/* eslint-disable @typescript-eslint/no-explicit-any -- the curried
+   contextual components in the yielded hash are any-typed exactly as in
+   freestyle.gts's Args hash; every other member is precisely typed. */
+export interface FormApi {
+  /** FormField, pre-bound to this form's context. */
+  Field: any;
+  /** FormLayout, pre-bound to this form's context. */
+  Layout: any;
+  /** FormSection, pre-bound to this form's context — a real fieldset. */
+  Section: any;
+  /** ErrorSummary, pre-bound to this form's context. */
+  Summary: any;
+  /** CompoundField, pre-bound to this form's context. */
+  Compound: any;
+  /** FieldError, for rendering an issue outside a field. */
+  Error: any;
+  context: FormContext;
+  mode: FormMode;
+  issues: FormIssue[];
+  blockingIssues: FormIssue[];
+  hasBlockingIssues: boolean;
+  unroutedIssues: FormIssue[];
+  dirty: boolean;
+  pristine: boolean;
+  submitted: boolean;
+  disabled: boolean;
+  busy: boolean;
+  submit: () => void;
+  reset: () => void;
+  markDirty: () => void;
+  markPristine: () => void;
+}
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+export interface FormSignature {
+  Args: {
+    /** 'submit' (default) | 'live' | 'record'. See the table above. */
+    mode?: FormMode;
+    /** Already-computed issues. The component never produces these. */
+    issues?: FormIssue[];
+    /** Disable every field at once (travels through the context). */
+    disabled?: boolean;
+    /** A commit is in flight: sets aria-busy and blocks re-submission. */
+    busy?: boolean;
+    /** Called on a commit that passed the gate. */
+    onSubmit?: (event: Event) => void;
+    /** Called when the native form resets. */
+    onReset?: (event: Event) => void;
+    /** Called with the blocking issues when a commit is refused — the hook
+     *  for a toast, a telemetry ping, or a scroll. */
+    onInvalidSubmit?: (issues: FormIssue[]) => void;
+    /** Where focus lands on a refused commit: 'field' (default, React
+     *  Spectrum's behavior), 'summary' (the GOV.UK behavior), or 'none'. */
+    focusOnInvalid?: FormFocusTarget;
+    /** 'aria' (default) adds novalidate; 'native' leaves the browser's own
+     *  constraint validation and its bubbles switched on. */
+    validationBehavior?: 'aria' | 'native';
+    /** Accessible name for the form landmark. */
+    label?: string;
+    /** id of an element naming the form, if a heading already does it. */
+    labelledBy?: string;
+  };
+  Blocks: {
+    /** The form body. Receives the whole API. */
+    default: [FormApi];
+    /** Action bar. Docks (sticky) in record mode. NOTE: using this block
+     *  means the body must be written as an explicit <:default> — mixing
+     *  loose content with named blocks fails the realm transpile. */
+    footer: [FormApi];
+  };
+  Element: HTMLFormElement;
+}
+
+export class Form extends Component<FormSignature> implements FormHost {
+  context = new FormContext(this);
+
+  get mode(): FormMode {
+    return this.args.mode ?? 'submit';
+  }
+  get issues(): FormIssue[] {
+    return this.args.issues ?? [];
+  }
+  get disabled(): boolean {
+    return Boolean(this.args.disabled);
+  }
+  get busy(): boolean {
+    return Boolean(this.args.busy);
+  }
+  get focusOnInvalid(): FormFocusTarget {
+    return this.args.focusOnInvalid ?? 'field';
+  }
+  /** 'aria' is React Spectrum's default and ours: we own the messaging, so
+   *  the browser must not also pop its own bubbles over our fields. */
+  get novalidateAttr(): string | undefined {
+    return (this.args.validationBehavior ?? 'aria') === 'aria'
+      ? 'novalidate'
+      : undefined;
+  }
+  /** live mode has no gate at all — issues there are advice, and refusing a
+   *  commit would contradict per-field autosave. */
+  get gates(): boolean {
+    return this.mode !== 'live';
+  }
+  get isDocked(): boolean {
+    return this.mode === 'record';
+  }
+
+  willDestroy(): void {
+    super.willDestroy();
+    this.context.teardown();
+  }
+
+  handleSubmit = (event: Event): void => {
+    event.preventDefault();
+    this.context.submitAttempted = true;
+    if (this.busy) {
+      return;
+    }
+    if (this.gates && this.context.hasBlockingIssues) {
+      this.args.onInvalidSubmit?.(this.context.blockingIssues);
+      this.context.focusInvalid();
+      return;
+    }
+    this.args.onSubmit?.(event);
+  };
+
+  handleReset = (event: Event): void => {
+    this.context.markPristine();
+    this.args.onReset?.(event);
+  };
+
+  // Dirty tracking rides the form's own bubbled input/change, so a caller
+  // does not have to remember to call markDirty from every control. The
+  // control context yields markDirty as well for controls that commit
+  // without emitting either (a custom picker, a drag handle).
+  handleEdit = (_event: Event): void => {
+    this.context.markDirty();
+  };
+
+  private formEl: HTMLFormElement | undefined;
+  captureForm = modifier((el: HTMLFormElement) => {
+    this.formEl = el;
+    return () => {
+      this.formEl = undefined;
+    };
+  });
+
+  // Through the element, so native validation and the caller's own listeners
+  // see the same submit and reset a button would produce.
+  requestSubmit = (): void => {
+    if (this.disabled) {
+      return;
+    }
+    if (this.formEl) {
+      this.formEl.requestSubmit();
+    } else {
+      this.handleSubmit(new Event('submit', { cancelable: true }));
+    }
+  };
+  requestReset = (): void => {
+    if (this.disabled) {
+      return;
+    }
+    if (this.formEl) {
+      this.formEl.reset();
+    } else {
+      this.handleReset(new Event('reset'));
+    }
+  };
+
+  <template>
+    <form
+      class='pretui-form'
+      novalidate={{this.novalidateAttr}}
+      aria-busy={{if this.busy 'true'}}
+      aria-label={{@label}}
+      aria-labelledby={{@labelledBy}}
+      data-mode={{this.mode}}
+      data-dirty={{if this.context.dirty 'true'}}
+      data-submitted={{if this.context.submitAttempted 'true'}}
+      data-busy={{if this.busy 'true'}}
+      data-test-pretui-form
+      {{on 'submit' this.handleSubmit}}
+      {{on 'reset' this.handleReset}}
+      {{this.captureForm}}
+      {{on 'input' this.handleEdit}}
+      {{on 'change' this.handleEdit}}
+      ...attributes
+    >
+      {{#let
+        (hash
+          Field=(component FormField form=this.context)
+          Layout=(component FormLayout form=this.context)
+          Section=(component FormSection form=this.context)
+          Compound=(component CompoundField form=this.context)
+          Summary=(component ErrorSummary form=this.context)
+          Error=FieldError
+          context=this.context
+          mode=this.mode
+          issues=this.issues
+          blockingIssues=this.context.blockingIssues
+          hasBlockingIssues=this.context.hasBlockingIssues
+          unroutedIssues=this.context.unroutedIssues
+          dirty=this.context.dirty
+          pristine=this.context.pristine
+          submitted=this.context.submitAttempted
+          disabled=this.disabled
+          busy=this.busy
+          submit=this.requestSubmit
+          reset=this.requestReset
+          markDirty=this.context.markDirty
+          markPristine=this.context.markPristine
+        )
+        as |api|
+      }}
+        <div class='pretui-form-body'>{{yield api}}</div>
+        {{#if (has-block 'footer')}}
+          <div
+            class='pretui-form-footer'
+            data-docked={{if this.isDocked 'true'}}
+          >{{yield api to='footer'}}</div>
+        {{/if}}
+      {{/let}}
+    </form>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-form {
+          display: grid;
+          gap: var(--pretui-form-gap, var(--space-5, 14px));
+          align-content: start;
+          min-width: 0;
+          font-size: var(--text-ui-md, 12.5px);
+          letter-spacing: var(--track-ui, 0.01em);
+          color: var(--foreground);
+        }
+        .pretui-form-body {
+          display: grid;
+          gap: var(--pretui-form-gap, var(--space-5, 14px));
+          align-content: start;
+          min-width: 0;
+        }
+        .pretui-form-footer {
+          display: flex;
+          align-items: center;
+          justify-content: flex-end;
+          gap: var(--space-3, 8px);
+          min-width: 0;
+        }
+        /* SLDS's docked-form-footer, minus the viewport-pinned positioning and
+           full-bleed width that put its bar over the host's own chrome when the
+           form lives in a card pane. Sticky keeps it at the bottom of the
+           form's own scroll box, where it belongs. */
+        .pretui-form-footer[data-docked='true'] {
+          position: sticky;
+          bottom: 0;
+          z-index: 2;
+          margin-top: calc(var(--space-3, 8px) * -1);
+          padding: var(--space-3, 8px) var(--space-4, 11px);
+          border-radius: var(--radius-surface, 10px);
+          background: var(--card);
+          box-shadow: var(
+            --pretui-shadow-raised,
+            0 0 0 1px var(--border), 0 -2px 10px rgb(0 0 0 / 0.08)
+          );
+        }
+        /* A busy form still shows its content — it just stops taking input.
+           No spinner overlay: the caller's footer owns the busy affordance
+           (Button already has @busy), and an overlay would hide the very
+           values the user is waiting on. */
+        .pretui-form[data-busy='true'] .pretui-form-body {
+          pointer-events: none;
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,82 @@
+## What it is
+
+The form host. It owns the commit gate, routes issues to fields, moves focus when it refuses, and yields a pre-bound API so nothing inside has to be threaded manually. Reach for it whenever more than two controls commit together, or whenever validation messages need to reach fields. For a single labelled control on a settings panel, **Field** is enough. For a read-only record view, **RecordDetail**.
+
+**The architectural rule of the territory: the form never validates.** It is handed an already-computed `FormIssue[]` — produced by BXL guide rules authored as data and evaluated elsewhere — and it does three things with them: routes them to fields, gates the commit on the blocking ones, and moves focus when it refuses. Nothing here compiles, evaluates, splits or regex-matches anything. If you are looking for where to put a validation rule, it is not in this component.
+
+## The contract
+
+```
+@mode? 'submit' | 'live' | 'record'   (default 'submit')
+@issues?, @disabled?, @busy?
+@onSubmit?, @onReset?, @onInvalidSubmit?(blockingIssues)
+@focusOnInvalid? 'field' | 'summary' | 'none'   (default 'field')
+@validationBehavior? 'aria' | 'native'          (default 'aria')
+@label?, @labelledBy?
+<:default as |form|>  <:footer as |form|>
+```
+
+**Three commit models, because a Boxel card autosaves and has no submit.** Wiring a classic submit form into a card edit view is precisely what sank the earlier attempt, so the modes are explicit:
+
+- `submit` — commit on submit, validate on submit, focus the first error. Errors are **withheld** until the user tries to commit. React Spectrum's classic shape.
+- `live` — commit per field immediately; issues are ambient advice and **never a gate**. Submitting does not refuse and does not move focus. The card-autosave shape.
+- `record` — commit per field inline, saved as a batch; validate per field plus a summary. The `<:footer>` docks and its save goes through the same gate as submit mode. The SLDS record-detail shape.
+
+**`@validationBehavior='aria'` puts `novalidate` on the `<form>`.** Same switch, same names as React Spectrum. Since the kit owns the messaging, the browser must not also pop its own bubbles over the fields.
+
+**The yielded API is pre-curried.** `form.Field`, `form.Layout`, `form.Section`, `form.Summary` and `form.Error` are contextual components already bound to this form's context, alongside `dirty`, `pristine`, `submitted`, `blockingIssues`, `unroutedIssues`, `submit`, `reset` and `markDirty`. Nothing inside a form has to be handed the form by hand — though every one of those components also accepts it directly, which is what makes them usable stand-alone.
+
+Dirty tracking rides the form's own bubbled `input`/`change`, so a caller never has to remember to call `markDirty` — and `markDirty` is yielded anyway for controls that commit without emitting either.
+
+One authoring trap, documented in the source: **using `<:footer>` means the body must be an explicit `<:default>`.** Mixing loose content with named blocks fails the realm transpile.
+
+## Prior art
+
+Two references, split by concern. **React Spectrum / React Aria** supplies the semantics: the `validationBehavior` switch, `FieldError`, focus-the-first-invalid-field on submit, `aria-describedby` ordering, required marking. **Salesforce Lightning Design System** supplies the layout and enterprise patterns: `form-element` with its `_stacked`/`_horizontal`/`_readonly`/`__static`/`__help` modifiers, `form-layout`, `docked-form-footer`, `record-detail`. **Radix `Form`** is the third comparison — `Field name` auto-association, `Message match` over native `ValidityState`, and focus-to-first-invalid on submit — and it is the closest in spirit, though it validates and Pretui deliberately does not.
+
+Where Pretui improves on both, concretely:
+
+- **SLDS's docked form footer is `position: fixed; width: 100%` against the viewport** — inside a card pane it escapes its pane and lands over the host chrome. Pretui's is `position: sticky` inside the form.
+- **SLDS breaks form-layout columns on `@media (min-width: 48em)`** — the viewport, not the pane — so a two-column form in a 320px side panel of a 1600px window stays two columns and shreds. Pretui uses container queries.
+- **Neither library ships an error summary that can prove nothing was dropped.** `ErrorSummary` lists every issue and explicitly marks the ones whose `targetPath` matched no rendered field.
+- **Neither has severity tiers on a field message.** SLDS has one flat error style; React Spectrum's `FieldError` is errors-only. Pretui's is severity-aware and **fails closed** — an unrecognised severity renders as an error and blocks.
+- **`live` mode has no analogue in either.** It exists because autosaving cards are the primary consumer.
+
+## Accessibility
+
+No APG pattern — a form is wiring. The governing criteria are WCAG **3.3.1 Error Identification**, **3.3.2 Labels or Instructions**, **3.3.3 Error Suggestion** and **3.3.4 Error Prevention**.
+
+What is right, and is the point of the component:
+
+- **Focus lands somewhere useful on a refused commit.** `focusInvalid()` prefers the first invalid field _in real document order_ — sorted by `compareDocumentPosition`, not by registration order, because conditionals and re-renders break that — then falls back to the summary, then to whatever the summary would have pointed at. `@focusOnInvalid='summary'` switches to the GOV.UK behavior.
+- **Focus can reach a control inside a collapsed section.** `reveal()` walks up through every `[data-pretui-form-section]` ancestor, calls its registered open callback _and_ clears the `hidden` attribute on the spot so focus lands in this tick rather than after the next render. A user is never asked to fix something they cannot see.
+- `aria-busy` while `@busy`; `aria-label`/`aria-labelledby` for the form's name.
+- The deferred claim publish is a **microtask**, not a timer — the realm's no-`setTimeout` law holds — which sidesteps Ember's backtracking-rerender assertion when fields register mid-render, and coalesces a batch into one flush.
+
+Gaps:
+
+- **`<form>` gets no `role="form"` landmark.** A `<form>` is only a landmark when it has an accessible name — so passing `@label` or `@labelledBy` is not optional if you want it findable by landmark navigation, and nothing warns when both are absent.
+- **`@busy` sets `aria-busy` but announces nothing.** A submit in flight is silent to a screen-reader user; pair it with a live region.
+- **A refused submit announces only via focus movement.** That is deliberate (see ErrorSummary's live-region note) and matches GOV.UK, but it means `@focusOnInvalid='none'` produces a submit that silently does nothing. Do not use it without another announcement channel.
+- `@disabled` travels through the context to every field, which is correct, but it does not disable the footer's own buttons — the caller owns those.
+
+## Theming
+
+The `<form>` element itself carries `data-mode`, `data-dirty`, `data-submitted` and `data-busy` for styling hooks, and consumes the shared layout tokens (`--space-*`). Nearly all visual tokens belong to the child components — **FormField**, **FormLayout**, **FormSection**, **ErrorSummary**, **FormFooter** — which is the intended shape: the host is behavior, the children are dress.
+
+Note the invalid and readonly dresses reach caller-supplied controls **through the inherited token channel** (`--field`, `--input`), not through `:deep()` or `:global()`. That is why they work on Input, Textarea, Select and anything else that reads the Pretui control tokens, and it is why a custom control that reads those tokens gets validation styling for free.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+| React                                  | Pretui                              |
+| -------------------------------------- | ----------------------------------- |
+| `<Form>` / react-hook-form / Aria Form | this tile                           |
+| FormField / Field / FormControl        | **FormField** / **Field**           |
+| FormMessage / errorMessage             | **FieldError**                      |
+| FormDescription                        | help slot                           |
+| Fieldset / FormSection                 | **FormSection** / **Fieldset** stub |
+| zod resolver / validation              | caller — Form routes issues         |
+
+- [ ] Accept `onSubmit` prevention defaults agents expect (`event.preventDefault`).