stimeo-ui 0.1.0-alpha.1

package/dist/controllers/focus_controller.js

@@ -0,0 +1,216 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/focus_controller.ts
+
+// src/utils/focus_trap.ts
+var FOCUSABLE = 'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+var FocusTrap = class {
+  /** The element focused before activation, restored on deactivation. */
+  #previouslyFocused = null;
+  /** The body's inline `overflow` before locking, restored on deactivation. */
+  #previousBodyOverflow = "";
+  /** Whether scroll was locked this activation (so it is only restored if applied). */
+  #scrollLocked = false;
+  /** Background siblings made `inert` while active, restored on deactivation. */
+  #inertedSiblings = [];
+  /** Whether the modal side effects are currently applied. */
+  #activeState = false;
+  /** Returns the trapped element; called on every operation for the live target. */
+  #getContainer;
+  /** Closing/focus hooks; see {@link FocusTrapOptions}. */
+  #options;
+  /**
+   * @param getContainer - Returns the trapped element. Called on every operation
+   *   so the live target is always used.
+   * @param options - Closing/focus hooks; see {@link FocusTrapOptions}.
+   */
+  constructor(getContainer, options = {}) {
+    this.#getContainer = getContainer;
+    this.#options = options;
+  }
+  /** Whether the trap is currently active. */
+  get active() {
+    return this.#activeState;
+  }
+  /**
+   * Applies the trap: records the current focus, optionally locks background scroll
+   * and makes background siblings `inert`, listens for `Tab`/`Escape`, and (unless
+   * `autoFocus` is off) moves focus inside. No-ops if already active.
+   */
+  activate() {
+    if (this.#activeState) return;
+    this.#activeState = true;
+    const active = document.activeElement;
+    this.#previouslyFocused = active instanceof HTMLElement && active !== document.body ? active : null;
+    if (this.#flag(this.#options.lockScroll, true)) {
+      this.#previousBodyOverflow = document.body.style.overflow;
+      document.body.style.overflow = "hidden";
+      this.#scrollLocked = true;
+    }
+    if (this.#flag(this.#options.isolate, true)) this.#isolateBackground();
+    document.addEventListener("keydown", this.#onKeydown);
+    if (this.#flag(this.#options.autoFocus, true)) this.#focusInitial();
+  }
+  /**
+   * Reverts every side effect applied by {@link activate}. No-ops if inactive, so
+   * a controller can call it defensively from both `close()` and `disconnect()`.
+   *
+   * @param restoreFocus - Move focus back to the opener (default `true`). Pass
+   *   `false` on teardown (`disconnect`), where yanking focus is undesirable.
+   */
+  deactivate({ restoreFocus = true } = {}) {
+    if (!this.#activeState) return;
+    this.#activeState = false;
+    document.removeEventListener("keydown", this.#onKeydown);
+    if (this.#scrollLocked) {
+      document.body.style.overflow = this.#previousBodyOverflow;
+      this.#scrollLocked = false;
+    }
+    this.#releaseBackground();
+    if (restoreFocus) {
+      const target = this.#previouslyFocused ?? this.#options.fallbackFocus?.() ?? null;
+      target?.focus();
+    }
+  }
+  /** Resolves a boolean-or-getter option, defaulting when it was not provided. */
+  #flag(option, fallback) {
+    if (option === void 0) return fallback;
+    return typeof option === "function" ? option() : option;
+  }
+  /** Handles `Escape` (delegated) and `Tab` (focus trap) while active. */
+  #onKeydown = (event) => {
+    if (event.key === "Escape") {
+      if (this.#options.onEscape) {
+        event.preventDefault();
+        this.#options.onEscape();
+      }
+      return;
+    }
+    if (event.key === "Tab") this.#trapTab(event);
+  };
+  /** Keeps `Tab` focus cycling within the container's focusable elements. */
+  #trapTab(event) {
+    const focusable = this.#focusableElements();
+    if (focusable.length === 0) {
+      event.preventDefault();
+      return;
+    }
+    const first = focusable[0];
+    const last = focusable[focusable.length - 1];
+    const active = document.activeElement;
+    if (!(active instanceof Node) || !this.#getContainer().contains(active)) {
+      event.preventDefault();
+      first?.focus();
+      return;
+    }
+    if (event.shiftKey && active === first) {
+      event.preventDefault();
+      last?.focus();
+    } else if (!event.shiftKey && active === last) {
+      event.preventDefault();
+      first?.focus();
+    }
+  }
+  /**
+   * Marks every element outside the container's subtree as `inert` so background
+   * content cannot be focused or reached by assistive technology, honoring the
+   * `aria-modal="true"` contract. An element that was *already* `inert` is left
+   * untracked so `#releaseBackground` does not wrongly clear it.
+   */
+  #isolateBackground() {
+    const container = this.#getContainer();
+    this.#inertedSiblings = [];
+    for (const sibling of Array.from(document.body.children)) {
+      if (!(sibling instanceof HTMLElement)) continue;
+      if (sibling.contains(container) || sibling.inert) continue;
+      sibling.inert = true;
+      this.#inertedSiblings.push(sibling);
+    }
+  }
+  /** Reverts the `inert` flags applied by `#isolateBackground`. */
+  #releaseBackground() {
+    for (const sibling of this.#inertedSiblings) {
+      sibling.inert = false;
+    }
+    this.#inertedSiblings = [];
+  }
+  /** Moves focus to the initial target, the first focusable, or the container. */
+  #focusInitial() {
+    const preferred = this.#options.initialFocus?.();
+    if (preferred) {
+      preferred.focus();
+      return;
+    }
+    const focusable = this.#focusableElements();
+    if (focusable[0]) {
+      focusable[0].focus();
+      return;
+    }
+    const container = this.#getContainer();
+    container.tabIndex = -1;
+    container.focus();
+  }
+  /** Collects the container's currently focusable descendants in DOM order. */
+  #focusableElements() {
+    return Array.from(this.#getContainer().querySelectorAll(FOCUSABLE)).filter(
+      (el) => !el.hidden
+    );
+  }
+};
+
+// src/controllers/focus_controller.ts
+var FocusController = class extends Controller {
+  static targets = ["initial"];
+  static values = {
+    trap: { type: Boolean, default: false },
+    auto: { type: Boolean, default: true },
+    restore: { type: Boolean, default: true },
+    inert: { type: Boolean, default: false }
+  };
+  static actions = ["activate", "deactivate"];
+  static events = ["activate", "deactivate"];
+  #trap = new FocusTrap(() => this.element, {
+    // A focus scope is not a modal: never lock scroll, and only isolate the background
+    // when `inert` is requested. `auto` gates the initial focus move; Escape releases.
+    lockScroll: false,
+    isolate: () => this.inertValue,
+    autoFocus: () => this.autoValue,
+    initialFocus: () => this.hasInitialTarget ? this.initialTarget : null,
+    onEscape: () => this.deactivate()
+  });
+  /** Stimulus drives activation from the `trap` value (also fires on connect). */
+  trapValueChanged() {
+    if (this.trapValue) this.#activate();
+    else this.#deactivate();
+  }
+  disconnect() {
+    this.#trap.deactivate({ restoreFocus: false });
+    this.element.removeAttribute("data-focus-trapped");
+  }
+  /** Turns the trap on. Acts synchronously and keeps the `trap` value in sync. */
+  activate() {
+    this.trapValue = true;
+    this.#activate();
+  }
+  /** Turns the trap off (also wired to Escape). */
+  deactivate() {
+    this.trapValue = false;
+    this.#deactivate();
+  }
+  #activate() {
+    if (this.#trap.active) return;
+    this.#trap.activate();
+    this.element.setAttribute("data-focus-trapped", "true");
+    this.dispatch("activate", { detail: {} });
+  }
+  #deactivate() {
+    if (!this.#trap.active) return;
+    this.#trap.deactivate({ restoreFocus: this.restoreValue });
+    this.element.removeAttribute("data-focus-trapped");
+    this.dispatch("deactivate", { detail: {} });
+  }
+};
+
+export { FocusController };
+//# sourceMappingURL=focus_controller.js.map
+//# sourceMappingURL=focus_controller.js.map

package/dist/controllers/focus_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/focus_trap.ts","../../src/controllers/focus_controller.ts"],"names":[],"mappings":"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","file":"focus_controller.js","sourcesContent":["/**\n * Modal focus-trap primitive shared by the modal-overlay controllers\n * (dialog / alert-dialog / drawer).\n *\n * The WAI-ARIA APG modal pattern is more than \"cycle Tab inside a box\": a modal\n * also locks background scroll, makes the rest of the page `inert` (so assistive\n * technology and pointer/Tab cannot reach it, honoring `aria-modal=\"true\"`),\n * sends focus inside on open, and restores it to the opener on close — and every\n * one of those side effects must be reverted if the element is torn down while\n * open (a Turbo navigation mid-dialog). {@link FocusTrap} owns that whole modal\n * lifecycle so each controller only decides *when* to open/close and *what*\n * \"close\" means.\n *\n * It is intentionally **policy-free about closing**. Escape semantics differ per\n * widget (a plain dialog just closes; an alert-dialog closes *as a cancel* with a\n * reason; a drawer runs an exit transition), so the trap merely forwards Escape\n * to an {@link FocusTrapOptions.onEscape | onEscape} callback and never decides on\n * its own what closing entails.\n *\n * @remarks\n * The container is read through a getter so a controller can hand over a Stimulus\n * target without worrying about when the trap instance is constructed relative to\n * `connect()`.\n */\n\n/**\n * Selector matching the elements considered focusable. Shared by the trap's Tab\n * cycling and by form-validation's invalid-focus delegation.\n */\nexport const FOCUSABLE =\n  'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex=\"-1\"])';\n\n/** Behavior hooks a controller supplies when constructing a {@link FocusTrap}. */\nexport interface FocusTrapOptions {\n  /**\n   * Called when `Escape` is pressed while the trap is active. When omitted,\n   * `Escape` is left alone (the trap never closes itself). The trap calls\n   * `preventDefault()` before invoking it.\n   */\n  onEscape?: () => void;\n  /**\n   * Returns the element to focus when the trap activates. When it returns `null`\n   * (or is omitted), the first focusable descendant is used, falling back to the\n   * container itself (made programmatically focusable with `tabindex=-1`).\n   */\n  initialFocus?: () => HTMLElement | null;\n  /**\n   * Returns the element to focus on deactivation when nothing was focused before\n   * the trap opened (e.g. the trigger). The element focused *before* opening\n   * always takes precedence.\n   */\n  fallbackFocus?: () => HTMLElement | null;\n  /**\n   * Lock background scroll (`body` overflow) while active. Defaults to `true` for\n   * the modal overlays; a lighter focus scope passes `false`. Read on `activate`.\n   */\n  lockScroll?: boolean | (() => boolean);\n  /**\n   * Make background siblings `inert` while active (the `aria-modal` isolation).\n   * Defaults to `true` for the modal overlays; a soft focus scope can opt out so\n   * the background stays reachable while `Tab` still cycles inside. Read on `activate`.\n   */\n  isolate?: boolean | (() => boolean);\n  /**\n   * Move focus inside on `activate`. Defaults to `true`; a focus scope that only\n   * wants the `Tab` boundary (no focus move) passes `false`. Read on `activate`.\n   */\n  autoFocus?: boolean | (() => boolean);\n}\n\n/**\n * Owns the modal side effects (scroll lock, background `inert`, focus trap, focus\n * restore) for a single container, applied on {@link activate} and reverted on\n * {@link deactivate}.\n */\nexport class FocusTrap {\n  /** The element focused before activation, restored on deactivation. */\n  #previouslyFocused: HTMLElement | null = null;\n  /** The body's inline `overflow` before locking, restored on deactivation. */\n  #previousBodyOverflow = \"\";\n  /** Whether scroll was locked this activation (so it is only restored if applied). */\n  #scrollLocked = false;\n  /** Background siblings made `inert` while active, restored on deactivation. */\n  #inertedSiblings: HTMLElement[] = [];\n  /** Whether the modal side effects are currently applied. */\n  #activeState = false;\n\n  /** Returns the trapped element; called on every operation for the live target. */\n  readonly #getContainer: () => HTMLElement;\n  /** Closing/focus hooks; see {@link FocusTrapOptions}. */\n  readonly #options: FocusTrapOptions;\n\n  /**\n   * @param getContainer - Returns the trapped element. Called on every operation\n   *   so the live target is always used.\n   * @param options - Closing/focus hooks; see {@link FocusTrapOptions}.\n   */\n  constructor(getContainer: () => HTMLElement, options: FocusTrapOptions = {}) {\n    this.#getContainer = getContainer;\n    this.#options = options;\n  }\n\n  /** Whether the trap is currently active. */\n  get active(): boolean {\n    return this.#activeState;\n  }\n\n  /**\n   * Applies the trap: records the current focus, optionally locks background scroll\n   * and makes background siblings `inert`, listens for `Tab`/`Escape`, and (unless\n   * `autoFocus` is off) moves focus inside. No-ops if already active.\n   */\n  activate(): void {\n    if (this.#activeState) return;\n    this.#activeState = true;\n    // Record the opener so it can be refocused on close. `<body>` (the default\n    // active element when nothing is focused) is treated as \"nothing\", so the\n    // fallback target — typically the trigger — wins in that case.\n    const active = document.activeElement;\n    this.#previouslyFocused =\n      active instanceof HTMLElement && active !== document.body ? active : null;\n    if (this.#flag(this.#options.lockScroll, true)) {\n      this.#previousBodyOverflow = document.body.style.overflow;\n      document.body.style.overflow = \"hidden\";\n      this.#scrollLocked = true;\n    }\n    if (this.#flag(this.#options.isolate, true)) this.#isolateBackground();\n    document.addEventListener(\"keydown\", this.#onKeydown);\n    if (this.#flag(this.#options.autoFocus, true)) this.#focusInitial();\n  }\n\n  /**\n   * Reverts every side effect applied by {@link activate}. No-ops if inactive, so\n   * a controller can call it defensively from both `close()` and `disconnect()`.\n   *\n   * @param restoreFocus - Move focus back to the opener (default `true`). Pass\n   *   `false` on teardown (`disconnect`), where yanking focus is undesirable.\n   */\n  deactivate({ restoreFocus = true }: { restoreFocus?: boolean } = {}): void {\n    if (!this.#activeState) return;\n    this.#activeState = false;\n    document.removeEventListener(\"keydown\", this.#onKeydown);\n    if (this.#scrollLocked) {\n      document.body.style.overflow = this.#previousBodyOverflow;\n      this.#scrollLocked = false;\n    }\n    this.#releaseBackground();\n    if (restoreFocus) {\n      const target = this.#previouslyFocused ?? this.#options.fallbackFocus?.() ?? null;\n      target?.focus();\n    }\n  }\n\n  /** Resolves a boolean-or-getter option, defaulting when it was not provided. */\n  #flag(option: boolean | (() => boolean) | undefined, fallback: boolean): boolean {\n    if (option === undefined) return fallback;\n    return typeof option === \"function\" ? option() : option;\n  }\n\n  /** Handles `Escape` (delegated) and `Tab` (focus trap) while active. */\n  readonly #onKeydown = (event: KeyboardEvent): void => {\n    if (event.key === \"Escape\") {\n      if (this.#options.onEscape) {\n        event.preventDefault();\n        this.#options.onEscape();\n      }\n      return;\n    }\n    if (event.key === \"Tab\") this.#trapTab(event);\n  };\n\n  /** Keeps `Tab` focus cycling within the container's focusable elements. */\n  #trapTab(event: KeyboardEvent): void {\n    const focusable = this.#focusableElements();\n    if (focusable.length === 0) {\n      event.preventDefault();\n      return;\n    }\n    const first = focusable[0];\n    const last = focusable[focusable.length - 1];\n    const active = document.activeElement;\n\n    // If focus has somehow escaped the container, pull it back to the first item.\n    if (!(active instanceof Node) || !this.#getContainer().contains(active)) {\n      event.preventDefault();\n      first?.focus();\n      return;\n    }\n\n    if (event.shiftKey && active === first) {\n      event.preventDefault();\n      last?.focus();\n    } else if (!event.shiftKey && active === last) {\n      event.preventDefault();\n      first?.focus();\n    }\n  }\n\n  /**\n   * Marks every element outside the container's subtree as `inert` so background\n   * content cannot be focused or reached by assistive technology, honoring the\n   * `aria-modal=\"true\"` contract. An element that was *already* `inert` is left\n   * untracked so `#releaseBackground` does not wrongly clear it.\n   */\n  #isolateBackground(): void {\n    const container = this.#getContainer();\n    this.#inertedSiblings = [];\n    for (const sibling of Array.from(document.body.children)) {\n      if (!(sibling instanceof HTMLElement)) continue;\n      if (sibling.contains(container) || sibling.inert) continue;\n      sibling.inert = true;\n      this.#inertedSiblings.push(sibling);\n    }\n  }\n\n  /** Reverts the `inert` flags applied by `#isolateBackground`. */\n  #releaseBackground(): void {\n    for (const sibling of this.#inertedSiblings) {\n      sibling.inert = false;\n    }\n    this.#inertedSiblings = [];\n  }\n\n  /** Moves focus to the initial target, the first focusable, or the container. */\n  #focusInitial(): void {\n    const preferred = this.#options.initialFocus?.();\n    if (preferred) {\n      preferred.focus();\n      return;\n    }\n    const focusable = this.#focusableElements();\n    if (focusable[0]) {\n      focusable[0].focus();\n      return;\n    }\n    const container = this.#getContainer();\n    container.tabIndex = -1;\n    container.focus();\n  }\n\n  /** Collects the container's currently focusable descendants in DOM order. */\n  #focusableElements(): HTMLElement[] {\n    return Array.from(this.#getContainer().querySelectorAll<HTMLElement>(FOCUSABLE)).filter(\n      (el) => !el.hidden,\n    );\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { FocusTrap } from \"../utils/focus_trap\";\n\n/**\n * Headless **focus scope**: exposes the shared {@link FocusTrap} as a standalone,\n * declarative focus boundary — `Tab` cycling, initial focus, and restore-on-release —\n * for any region, without building a full modal (counterpart to Alpine `focus` /\n * Headless UI's trap). No dedicated APG pattern; it is the primitive the overlay\n * patterns use, surfaced for direct use.\n *\n * Markup contract (identifier: `stimeo--focus`):\n *   <div data-controller=\"stimeo--focus\" data-stimeo--focus-trap-value=\"true\">\n *     <input data-stimeo--focus-target=\"initial\" />\n *     …\n *   </div>\n *\n * While `trap` is on, `Tab` / `Shift+Tab` cycle within the element, focus moves to the\n * `initial` target (or the first focusable) when `auto`, `Escape` releases it, and on\n * release focus returns to the opener when `restore`. With `inert` the rest of the page\n * is made `inert` (a hard, modal-style isolation); left off it is a soft boundary —\n * `Tab` still cycles but the background stays reachable. The element carries\n * `data-focus-trapped` while active and emits `activate` / `deactivate`.\n *\n * @remarks\n * Behavior only — it does not open/close or render an overlay (pair with Dialog) and\n * does not move DOM (pair with Portal). It reuses `src/utils/focus_trap.ts`, so it never\n * scroll-locks the page (unlike the modal overlays) and tracks live focusable children\n * (dynamic additions are picked up on the next `Tab`). The opener is recorded on\n * activate and refocused on release if still present. Everything is torn down on\n * `disconnect()` (Turbo navigation included) without yanking focus.\n */\nexport class FocusController extends Controller<HTMLElement> {\n  static override targets = [\"initial\"];\n  static override values = {\n    trap: { type: Boolean, default: false },\n    auto: { type: Boolean, default: true },\n    restore: { type: Boolean, default: true },\n    inert: { type: Boolean, default: false },\n  };\n  static actions = [\"activate\", \"deactivate\"] as const;\n  static events = [\"activate\", \"deactivate\"] as const;\n\n  declare readonly initialTarget: HTMLElement;\n  declare readonly hasInitialTarget: boolean;\n\n  declare trapValue: boolean;\n  declare autoValue: boolean;\n  declare restoreValue: boolean;\n  declare inertValue: boolean;\n\n  readonly #trap = new FocusTrap(() => this.element, {\n    // A focus scope is not a modal: never lock scroll, and only isolate the background\n    // when `inert` is requested. `auto` gates the initial focus move; Escape releases.\n    lockScroll: false,\n    isolate: () => this.inertValue,\n    autoFocus: () => this.autoValue,\n    initialFocus: () => (this.hasInitialTarget ? this.initialTarget : null),\n    onEscape: () => this.deactivate(),\n  });\n\n  /** Stimulus drives activation from the `trap` value (also fires on connect). */\n  trapValueChanged(): void {\n    if (this.trapValue) this.#activate();\n    else this.#deactivate();\n  }\n\n  override disconnect(): void {\n    // Release without restoring focus — the element is leaving the DOM. This is a\n    // teardown, not a user-driven close, so it intentionally does NOT emit\n    // `deactivate` or reset `trapValue` (which would resurrect on a Turbo cache\n    // restore); only the public `deactivate()` action fires the event.\n    this.#trap.deactivate({ restoreFocus: false });\n    this.element.removeAttribute(\"data-focus-trapped\");\n  }\n\n  /** Turns the trap on. Acts synchronously and keeps the `trap` value in sync. */\n  activate(): void {\n    this.trapValue = true;\n    this.#activate();\n  }\n\n  /** Turns the trap off (also wired to Escape). */\n  deactivate(): void {\n    this.trapValue = false;\n    this.#deactivate();\n  }\n\n  #activate(): void {\n    if (this.#trap.active) return;\n    this.#trap.activate();\n    this.element.setAttribute(\"data-focus-trapped\", \"true\");\n    this.dispatch(\"activate\", { detail: {} });\n  }\n\n  #deactivate(): void {\n    if (!this.#trap.active) return;\n    this.#trap.deactivate({ restoreFocus: this.restoreValue });\n    this.element.removeAttribute(\"data-focus-trapped\");\n    this.dispatch(\"deactivate\", { detail: {} });\n  }\n}\n"]}

package/dist/controllers/form_field_controller.d.ts

@@ -0,0 +1,79 @@
+import { Controller } from '@hotwired/stimulus';
+
+/** Stimulus action params understood by {@link FormFieldController.setError}. */
+interface SetErrorParams {
+    /** The error message to display. */
+    message?: string;
+}
+/** An action event carrying Stimulus `data-*-param` values. */
+type ActionEvent = Event & {
+    params?: SetErrorParams;
+};
+/**
+ * Headless, accessible form-field association behavior.
+ *
+ * Markup contract (identifier: `stimeo--form-field`):
+ *   <div data-controller="stimeo--form-field">
+ *     <label for="email">Email</label>
+ *     <input id="email" type="email" aria-invalid="false"
+ *            data-stimeo--form-field-target="control" />
+ *     <p data-stimeo--form-field-target="description">We'll send a confirmation.</p>
+ *     <p role="alert" hidden data-stimeo--form-field-target="error"></p>
+ *   </div>
+ *
+ * Not an APG widget pattern — this is the wiring substrate behind form controls:
+ * it supports **Name, Role, Value** (WCAG 4.1.2) and **error identification**
+ * (3.3.1 / 4.1.3) by composing the control's `aria-describedby`, toggling
+ * `aria-invalid`, and pointing `aria-errormessage` at the live error region.
+ *
+ * @remarks
+ * Behavior only — it sets semantic attributes and the `hidden` state of the
+ * error region; it never validates input (the consumer / server decides) and
+ * never styles. The error target should carry `role="alert"` (or an
+ * `aria-live` region) so a newly shown message is announced without moving focus.
+ *
+ * Behavior provided:
+ * - On connect, assigns ids to description/error targets and composes the
+ *   control's `aria-describedby` from them (preserving any pre-existing tokens).
+ * - Reflects server-rendered errors: an error target that is already visible and
+ *   non-empty at connect puts the field into the invalid state (progressive
+ *   enhancement).
+ * - {@link setError} / {@link clearError} drive the invalid state at runtime and
+ *   dispatch `stimeo--form-field:validate`.
+ */
+declare class FormFieldController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        focusOnError: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+    };
+    static actions: readonly ["clearError", "setError"];
+    static events: readonly ["validate"];
+    readonly controlTarget: HTMLElement;
+    readonly hasControlTarget: boolean;
+    readonly descriptionTargets: HTMLElement[];
+    readonly errorTargets: HTMLElement[];
+    readonly hasErrorTarget: boolean;
+    focusOnErrorValue: boolean;
+    /** Wires ids, captures consumer tokens, and reflects any initial error state. */
+    connect(): void;
+    /**
+     * Marks the field invalid and shows the error message. Bound via `data-action`
+     * (`#setError`) or callable directly.
+     *
+     * @param arg - Either the message string, or the action event whose
+     *   `data-stimeo--form-field-message-param` supplies it. When no message is
+     *   resolvable, any already-populated error targets are simply (re)shown.
+     */
+    setError(arg?: string | ActionEvent): void;
+    /**
+     * Clears the error: empties and hides every error target and marks the field
+     * valid. Bound via `data-action` (`#clearError`) or callable directly.
+     */
+    clearError(): void;
+}
+
+export { FormFieldController };

package/dist/controllers/form_field_controller.js

@@ -0,0 +1,154 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/form_field_controller.ts
+
+// src/utils/aria_ids.ts
+var counter = 0;
+function uniqueId(prefix = "stimeo") {
+  let candidate;
+  do {
+    counter += 1;
+    candidate = `${prefix}-${counter}`;
+  } while (typeof document !== "undefined" && document.getElementById(candidate) !== null);
+  return candidate;
+}
+function ensureId(element, prefix = "stimeo") {
+  if (element.id) return element.id;
+  const id = uniqueId(prefix);
+  element.id = id;
+  return id;
+}
+
+// src/controllers/form_field_controller.ts
+var FormFieldController = class _FormFieldController extends Controller {
+  static targets = ["control", "description", "error"];
+  static values = {
+    focusOnError: { type: Boolean, default: false }
+  };
+  static actions = ["clearError", "setError"];
+  static events = ["validate"];
+  /** Root attribute (CSS hook) reflecting the invalid state. */
+  static #INVALID_ATTR = "data-stimeo--form-field-invalid";
+  /**
+   * `aria-describedby` tokens the consumer set on the control that the
+   * controller does not own. Captured once so composition never clobbers them.
+   */
+  #baseDescribedBy = [];
+  /** Wires ids, captures consumer tokens, and reflects any initial error state. */
+  connect() {
+    for (const description of this.descriptionTargets) {
+      ensureId(description, "stimeo--form-field-desc");
+    }
+    for (const error of this.errorTargets) {
+      ensureId(error, "stimeo--form-field-error");
+    }
+    this.#baseDescribedBy = this.#externalDescribedByTokens();
+    this.#reflect();
+  }
+  /**
+   * Marks the field invalid and shows the error message. Bound via `data-action`
+   * (`#setError`) or callable directly.
+   *
+   * @param arg - Either the message string, or the action event whose
+   *   `data-stimeo--form-field-message-param` supplies it. When no message is
+   *   resolvable, any already-populated error targets are simply (re)shown.
+   */
+  setError(arg) {
+    const message = this.#resolveMessage(arg);
+    if (message !== null && this.hasErrorTarget) {
+      this.errorTargets[0]?.replaceChildren(document.createTextNode(message));
+    }
+    for (const error of this.errorTargets) {
+      error.hidden = (error.textContent ?? "").trim() === "";
+    }
+    this.#reflect(true);
+    this.dispatch("validate", { detail: { valid: false, message: this.#shownMessage() } });
+    if (this.focusOnErrorValue && this.hasControlTarget) {
+      this.controlTarget.focus();
+    }
+  }
+  /**
+   * Clears the error: empties and hides every error target and marks the field
+   * valid. Bound via `data-action` (`#clearError`) or callable directly.
+   */
+  clearError() {
+    for (const error of this.errorTargets) {
+      error.replaceChildren();
+      error.hidden = true;
+    }
+    this.#reflect();
+    this.dispatch("validate", { detail: { valid: true, message: "" } });
+  }
+  /**
+   * Synchronizes the control's ARIA wiring and the root CSS hook from the current
+   * error targets. Idempotent, so it is safe to call on connect and after any
+   * change (and survives Turbo morphing).
+   *
+   * @param force - When `true`, the field is marked invalid regardless of whether
+   *   a (visible, non-empty) error region exists. {@link setError} passes this so
+   *   the invalid state holds even with no error target; derivation from the DOM
+   *   (connect / {@link clearError}) leaves it `false`.
+   */
+  #reflect(force = false) {
+    const shown = this.#shownErrors();
+    const invalid = force || shown.length > 0;
+    if (invalid) {
+      this.element.setAttribute(_FormFieldController.#INVALID_ATTR, "");
+    } else {
+      this.element.removeAttribute(_FormFieldController.#INVALID_ATTR);
+    }
+    if (!this.hasControlTarget) return;
+    const control = this.controlTarget;
+    control.setAttribute("aria-invalid", invalid ? "true" : "false");
+    const errorIds = shown.map((error) => error.id);
+    const primaryErrorId = errorIds[0];
+    if (primaryErrorId) {
+      control.setAttribute("aria-errormessage", primaryErrorId);
+    } else {
+      control.removeAttribute("aria-errormessage");
+    }
+    const describedBy = [
+      ...this.#baseDescribedBy,
+      ...this.descriptionTargets.map((description) => description.id),
+      ...errorIds
+    ];
+    if (describedBy.length > 0) {
+      control.setAttribute("aria-describedby", describedBy.join(" "));
+    } else {
+      control.removeAttribute("aria-describedby");
+    }
+  }
+  /** Error targets currently visible and non-empty. */
+  #shownErrors() {
+    return this.errorTargets.filter(
+      (error) => !error.hidden && (error.textContent ?? "").trim() !== ""
+    );
+  }
+  /** Text of the first shown error, for the `validate` event detail. */
+  #shownMessage() {
+    return (this.#shownErrors()[0]?.textContent ?? "").trim();
+  }
+  /** Resolves a message from a string argument or an action event's params. */
+  #resolveMessage(arg) {
+    if (typeof arg === "string") return arg;
+    const message = arg?.params?.message;
+    return typeof message === "string" ? message : null;
+  }
+  /**
+   * Tokens already in the control's `aria-describedby` that are not ids of this
+   * controller's own description/error targets.
+   */
+  #externalDescribedByTokens() {
+    if (!this.hasControlTarget) return [];
+    const owned = /* @__PURE__ */ new Set([
+      ...this.descriptionTargets.map((description) => description.id),
+      ...this.errorTargets.map((error) => error.id)
+    ]);
+    const existing = this.controlTarget.getAttribute("aria-describedby") ?? "";
+    return existing.split(/\s+/).filter((token) => token.length > 0 && !owned.has(token));
+  }
+};
+
+export { FormFieldController };
+//# sourceMappingURL=form_field_controller.js.map
+//# sourceMappingURL=form_field_controller.js.map

package/dist/controllers/form_field_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/aria_ids.ts","../../src/controllers/form_field_controller.ts"],"names":[],"mappings":";;;;;AAkBA,IAAI,OAAA,GAAU,CAAA;AAeP,SAAS,QAAA,CAAS,SAAS,QAAA,EAAkB;AAClD,EAAA,IAAI,SAAA;AACJ,EAAA,GAAG;AACD,IAAA,OAAA,IAAW,CAAA;AACX,IAAA,SAAA,GAAY,CAAA,EAAG,MAAM,CAAA,CAAA,EAAI,OAAO,CAAA,CAAA;AAAA,EAClC,SAAS,OAAO,QAAA,KAAa,eAAe,QAAA,CAAS,cAAA,CAAe,SAAS,CAAA,KAAM,IAAA;AACnF,EAAA,OAAO,SAAA;AACT;AAYO,SAAS,QAAA,CAAS,OAAA,EAAkB,MAAA,GAAS,QAAA,EAAkB;AACpE,EAAA,IAAI,OAAA,CAAQ,EAAA,EAAI,OAAO,OAAA,CAAQ,EAAA;AAC/B,EAAA,MAAM,EAAA,GAAK,SAAS,MAAM,CAAA;AAC1B,EAAA,OAAA,CAAQ,EAAA,GAAK,EAAA;AACb,EAAA,OAAO,EAAA;AACT;;;ACbO,IAAM,mBAAA,GAAN,MAAM,oBAAA,SAA4B,UAAA,CAAwB;AAAA,EAC/D,OAAgB,OAAA,GAAU,CAAC,SAAA,EAAW,eAAe,OAAO,CAAA;AAAA,EAC5D,OAAgB,MAAA,GAAS;AAAA,IACvB,YAAA,EAAc,EAAE,IAAA,EAAM,OAAA,EAAS,SAAS,KAAA;AAAM,GAChD;AAAA,EACA,OAAO,OAAA,GAAU,CAAC,YAAA,EAAc,UAAU,CAAA;AAAA,EAC1C,OAAO,MAAA,GAAS,CAAC,UAAU,CAAA;AAAA;AAAA,EAU3B,OAAgB,aAAA,GAAgB,iCAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMhC,mBAA6B,EAAC;AAAA;AAAA,EAGrB,OAAA,GAAgB;AACvB,IAAA,KAAA,MAAW,WAAA,IAAe,KAAK,kBAAA,EAAoB;AACjD,MAAA,QAAA,CAAS,aAAa,yBAAyB,CAAA;AAAA,IACjD;AACA,IAAA,KAAA,MAAW,KAAA,IAAS,KAAK,YAAA,EAAc;AACrC,MAAA,QAAA,CAAS,OAAO,0BAA0B,CAAA;AAAA,IAC5C;AACA,IAAA,IAAA,CAAK,gBAAA,GAAmB,KAAK,0BAAA,EAA2B;AACxD,IAAA,IAAA,CAAK,QAAA,EAAS;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,SAAS,GAAA,EAAkC;AACzC,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,eAAA,CAAgB,GAAG,CAAA;AACxC,IAAA,IAAI,OAAA,KAAY,IAAA,IAAQ,IAAA,CAAK,cAAA,EAAgB;AAC3C,MAAA,IAAA,CAAK,aAAa,CAAC,CAAA,EAAG,gBAAgB,QAAA,CAAS,cAAA,CAAe,OAAO,CAAC,CAAA;AAAA,IACxE;AACA,IAAA,KAAA,MAAW,KAAA,IAAS,KAAK,YAAA,EAAc;AACrC,MAAA,KAAA,CAAM,MAAA,GAAA,CAAU,KAAA,CAAM,WAAA,IAAe,EAAA,EAAI,MAAK,KAAM,EAAA;AAAA,IACtD;AAIA,IAAA,IAAA,CAAK,SAAS,IAAI,CAAA;AAClB,IAAA,IAAA,CAAK,QAAA,CAAS,UAAA,EAAY,EAAE,MAAA,EAAQ,EAAE,KAAA,EAAO,KAAA,EAAO,OAAA,EAAS,IAAA,CAAK,aAAA,EAAc,EAAE,EAAG,CAAA;AACrF,IAAA,IAAI,IAAA,CAAK,iBAAA,IAAqB,IAAA,CAAK,gBAAA,EAAkB;AACnD,MAAA,IAAA,CAAK,cAAc,KAAA,EAAM;AAAA,IAC3B;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,UAAA,GAAmB;AACjB,IAAA,KAAA,MAAW,KAAA,IAAS,KAAK,YAAA,EAAc;AACrC,MAAA,KAAA,CAAM,eAAA,EAAgB;AACtB,MAAA,KAAA,CAAM,MAAA,GAAS,IAAA;AAAA,IACjB;AACA,IAAA,IAAA,CAAK,QAAA,EAAS;AACd,IAAA,IAAA,CAAK,QAAA,CAAS,UAAA,EAAY,EAAE,MAAA,EAAQ,EAAE,OAAO,IAAA,EAAM,OAAA,EAAS,EAAA,EAAG,EAAG,CAAA;AAAA,EACpE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,QAAA,CAAS,QAAQ,KAAA,EAAa;AAC5B,IAAA,MAAM,KAAA,GAAQ,KAAK,YAAA,EAAa;AAChC,IAAA,MAAM,OAAA,GAAU,KAAA,IAAS,KAAA,CAAM,MAAA,GAAS,CAAA;AAExC,IAAA,IAAI,OAAA,EAAS;AACX,MAAA,IAAA,CAAK,OAAA,CAAQ,YAAA,CAAa,oBAAA,CAAoB,aAAA,EAAe,EAAE,CAAA;AAAA,IACjE,CAAA,MAAO;AACL,MAAA,IAAA,CAAK,OAAA,CAAQ,eAAA,CAAgB,oBAAA,CAAoB,aAAa,CAAA;AAAA,IAChE;AAEA,IAAA,IAAI,CAAC,KAAK,gBAAA,EAAkB;AAC5B,IAAA,MAAM,UAAU,IAAA,CAAK,aAAA;AACrB,IAAA,OAAA,CAAQ,YAAA,CAAa,cAAA,EAAgB,OAAA,GAAU,MAAA,GAAS,OAAO,CAAA;AAE/D,IAAA,MAAM,WAAW,KAAA,CAAM,GAAA,CAAI,CAAC,KAAA,KAAU,MAAM,EAAE,CAAA;AAG9C,IAAA,MAAM,cAAA,GAAiB,SAAS,CAAC,CAAA;AACjC,IAAA,IAAI,cAAA,EAAgB;AAClB,MAAA,OAAA,CAAQ,YAAA,CAAa,qBAAqB,cAAc,CAAA;AAAA,IAC1D,CAAA,MAAO;AACL,MAAA,OAAA,CAAQ,gBAAgB,mBAAmB,CAAA;AAAA,IAC7C;AAIA,IAAA,MAAM,WAAA,GAAc;AAAA,MAClB,GAAG,IAAA,CAAK,gBAAA;AAAA,MACR,GAAG,IAAA,CAAK,kBAAA,CAAmB,IAAI,CAAC,WAAA,KAAgB,YAAY,EAAE,CAAA;AAAA,MAC9D,GAAG;AAAA,KACL;AACA,IAAA,IAAI,WAAA,CAAY,SAAS,CAAA,EAAG;AAC1B,MAAA,OAAA,CAAQ,YAAA,CAAa,kBAAA,EAAoB,WAAA,CAAY,IAAA,CAAK,GAAG,CAAC,CAAA;AAAA,IAChE,CAAA,MAAO;AACL,MAAA,OAAA,CAAQ,gBAAgB,kBAAkB,CAAA;AAAA,IAC5C;AAAA,EACF;AAAA;AAAA,EAGA,YAAA,GAA8B;AAC5B,IAAA,OAAO,KAAK,YAAA,CAAa,MAAA;AAAA,MACvB,CAAC,UAAU,CAAC,KAAA,CAAM,WAAW,KAAA,CAAM,WAAA,IAAe,EAAA,EAAI,IAAA,EAAK,KAAM;AAAA,KACnE;AAAA,EACF;AAAA;AAAA,EAGA,aAAA,GAAwB;AACtB,IAAA,OAAA,CAAQ,KAAK,YAAA,EAAa,CAAE,CAAC,CAAA,EAAG,WAAA,IAAe,IAAI,IAAA,EAAK;AAAA,EAC1D;AAAA;AAAA,EAGA,gBAAgB,GAAA,EAA2C;AACzD,IAAA,IAAI,OAAO,GAAA,KAAQ,QAAA,EAAU,OAAO,GAAA;AACpC,IAAA,MAAM,OAAA,GAAU,KAAK,MAAA,EAAQ,OAAA;AAC7B,IAAA,OAAO,OAAO,OAAA,KAAY,QAAA,GAAW,OAAA,GAAU,IAAA;AAAA,EACjD;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,0BAAA,GAAuC;AACrC,IAAA,IAAI,CAAC,IAAA,CAAK,gBAAA,EAAkB,OAAO,EAAC;AACpC,IAAA,MAAM,KAAA,uBAAY,GAAA,CAAI;AAAA,MACpB,GAAG,IAAA,CAAK,kBAAA,CAAmB,IAAI,CAAC,WAAA,KAAgB,YAAY,EAAE,CAAA;AAAA,MAC9D,GAAG,IAAA,CAAK,YAAA,CAAa,IAAI,CAAC,KAAA,KAAU,MAAM,EAAE;AAAA,KAC7C,CAAA;AACD,IAAA,MAAM,QAAA,GAAW,IAAA,CAAK,aAAA,CAAc,YAAA,CAAa,kBAAkB,CAAA,IAAK,EAAA;AACxE,IAAA,OAAO,QAAA,CAAS,KAAA,CAAM,KAAK,CAAA,CAAE,OAAO,CAAC,KAAA,KAAU,KAAA,CAAM,MAAA,GAAS,CAAA,IAAK,CAAC,KAAA,CAAM,GAAA,CAAI,KAAK,CAAC,CAAA;AAAA,EACtF;AACF","file":"form_field_controller.js","sourcesContent":["/**\n * Minimal id primitives for wiring ARIA relationships.\n *\n * Accessible relationships such as `aria-describedby`, `aria-errormessage`,\n * `aria-labelledby`, and `aria-activedescendant` reference their targets by DOM\n * `id`. When a controller must establish such a relationship but the consumer's\n * markup left the target without an `id`, it needs to mint one that is stable for\n * the page's lifetime and guaranteed not to collide with another generated id.\n *\n * These helpers own *only* id generation/assignment. The linking policy (which\n * attribute, what order, when to add or remove it) stays in each controller —\n * this deliberately avoids a premature generic \"ARIA linker\" abstraction.\n */\n\n/**\n * Monotonic counter backing {@link uniqueId}. Module-scoped so every generated\n * id is unique across all controller instances sharing this module in a document.\n */\nlet counter = 0;\n\n/**\n * Returns a unique, DOM-id-safe string of the form `` `${prefix}-${n}` `` where\n * `n` increases on each call.\n *\n * The counter alone guarantees uniqueness against other *generated* ids, but a\n * consumer-authored element could already own `` `${prefix}-${n}` ``. When a\n * `document` is available the candidate is therefore advanced until no element\n * with that id exists, so a generated id never collides with author markup\n * either — the minimal \"id registry\" guarantee these helpers exist to provide.\n *\n * @param prefix - Leading segment of the id (e.g. a controller's identifier).\n *   Defaults to `\"stimeo\"`.\n */\nexport function uniqueId(prefix = \"stimeo\"): string {\n  let candidate: string;\n  do {\n    counter += 1;\n    candidate = `${prefix}-${counter}`;\n  } while (typeof document !== \"undefined\" && document.getElementById(candidate) !== null);\n  return candidate;\n}\n\n/**\n * Returns `element`'s existing `id`, or assigns it a freshly generated\n * {@link uniqueId} (with the given `prefix`) and returns that. Idempotent: an\n * element that already has an id keeps it, so consumer-authored ids are never\n * overwritten.\n *\n * @param element - The element to read or stamp an `id` onto.\n * @param prefix - Prefix forwarded to {@link uniqueId} when one must be generated.\n * @returns The element's id (existing or newly assigned).\n */\nexport function ensureId(element: Element, prefix = \"stimeo\"): string {\n  if (element.id) return element.id;\n  const id = uniqueId(prefix);\n  element.id = id;\n  return id;\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { ensureId } from \"../utils/aria_ids\";\n\n/** Stimulus action params understood by {@link FormFieldController.setError}. */\ninterface SetErrorParams {\n  /** The error message to display. */\n  message?: string;\n}\n\n/** An action event carrying Stimulus `data-*-param` values. */\ntype ActionEvent = Event & { params?: SetErrorParams };\n\n/**\n * Headless, accessible form-field association behavior.\n *\n * Markup contract (identifier: `stimeo--form-field`):\n *   <div data-controller=\"stimeo--form-field\">\n *     <label for=\"email\">Email</label>\n *     <input id=\"email\" type=\"email\" aria-invalid=\"false\"\n *            data-stimeo--form-field-target=\"control\" />\n *     <p data-stimeo--form-field-target=\"description\">We'll send a confirmation.</p>\n *     <p role=\"alert\" hidden data-stimeo--form-field-target=\"error\"></p>\n *   </div>\n *\n * Not an APG widget pattern — this is the wiring substrate behind form controls:\n * it supports **Name, Role, Value** (WCAG 4.1.2) and **error identification**\n * (3.3.1 / 4.1.3) by composing the control's `aria-describedby`, toggling\n * `aria-invalid`, and pointing `aria-errormessage` at the live error region.\n *\n * @remarks\n * Behavior only — it sets semantic attributes and the `hidden` state of the\n * error region; it never validates input (the consumer / server decides) and\n * never styles. The error target should carry `role=\"alert\"` (or an\n * `aria-live` region) so a newly shown message is announced without moving focus.\n *\n * Behavior provided:\n * - On connect, assigns ids to description/error targets and composes the\n *   control's `aria-describedby` from them (preserving any pre-existing tokens).\n * - Reflects server-rendered errors: an error target that is already visible and\n *   non-empty at connect puts the field into the invalid state (progressive\n *   enhancement).\n * - {@link setError} / {@link clearError} drive the invalid state at runtime and\n *   dispatch `stimeo--form-field:validate`.\n */\nexport class FormFieldController extends Controller<HTMLElement> {\n  static override targets = [\"control\", \"description\", \"error\"];\n  static override values = {\n    focusOnError: { type: Boolean, default: false },\n  };\n  static actions = [\"clearError\", \"setError\"] as const;\n  static events = [\"validate\"] as const;\n\n  declare readonly controlTarget: HTMLElement;\n  declare readonly hasControlTarget: boolean;\n  declare readonly descriptionTargets: HTMLElement[];\n  declare readonly errorTargets: HTMLElement[];\n  declare readonly hasErrorTarget: boolean;\n  declare focusOnErrorValue: boolean;\n\n  /** Root attribute (CSS hook) reflecting the invalid state. */\n  static readonly #INVALID_ATTR = \"data-stimeo--form-field-invalid\";\n\n  /**\n   * `aria-describedby` tokens the consumer set on the control that the\n   * controller does not own. Captured once so composition never clobbers them.\n   */\n  #baseDescribedBy: string[] = [];\n\n  /** Wires ids, captures consumer tokens, and reflects any initial error state. */\n  override connect(): void {\n    for (const description of this.descriptionTargets) {\n      ensureId(description, \"stimeo--form-field-desc\");\n    }\n    for (const error of this.errorTargets) {\n      ensureId(error, \"stimeo--form-field-error\");\n    }\n    this.#baseDescribedBy = this.#externalDescribedByTokens();\n    this.#reflect();\n  }\n\n  /**\n   * Marks the field invalid and shows the error message. Bound via `data-action`\n   * (`#setError`) or callable directly.\n   *\n   * @param arg - Either the message string, or the action event whose\n   *   `data-stimeo--form-field-message-param` supplies it. When no message is\n   *   resolvable, any already-populated error targets are simply (re)shown.\n   */\n  setError(arg?: string | ActionEvent): void {\n    const message = this.#resolveMessage(arg);\n    if (message !== null && this.hasErrorTarget) {\n      this.errorTargets[0]?.replaceChildren(document.createTextNode(message));\n    }\n    for (const error of this.errorTargets) {\n      error.hidden = (error.textContent ?? \"\").trim() === \"\";\n    }\n    // setError is an explicit invalid request: mark invalid even when the field\n    // has no error region (structure rules require only `control`), so the DOM\n    // invalid state never disagrees with the dispatched `valid: false`.\n    this.#reflect(true);\n    this.dispatch(\"validate\", { detail: { valid: false, message: this.#shownMessage() } });\n    if (this.focusOnErrorValue && this.hasControlTarget) {\n      this.controlTarget.focus();\n    }\n  }\n\n  /**\n   * Clears the error: empties and hides every error target and marks the field\n   * valid. Bound via `data-action` (`#clearError`) or callable directly.\n   */\n  clearError(): void {\n    for (const error of this.errorTargets) {\n      error.replaceChildren();\n      error.hidden = true;\n    }\n    this.#reflect();\n    this.dispatch(\"validate\", { detail: { valid: true, message: \"\" } });\n  }\n\n  /**\n   * Synchronizes the control's ARIA wiring and the root CSS hook from the current\n   * error targets. Idempotent, so it is safe to call on connect and after any\n   * change (and survives Turbo morphing).\n   *\n   * @param force - When `true`, the field is marked invalid regardless of whether\n   *   a (visible, non-empty) error region exists. {@link setError} passes this so\n   *   the invalid state holds even with no error target; derivation from the DOM\n   *   (connect / {@link clearError}) leaves it `false`.\n   */\n  #reflect(force = false): void {\n    const shown = this.#shownErrors();\n    const invalid = force || shown.length > 0;\n\n    if (invalid) {\n      this.element.setAttribute(FormFieldController.#INVALID_ATTR, \"\");\n    } else {\n      this.element.removeAttribute(FormFieldController.#INVALID_ATTR);\n    }\n\n    if (!this.hasControlTarget) return;\n    const control = this.controlTarget;\n    control.setAttribute(\"aria-invalid\", invalid ? \"true\" : \"false\");\n\n    const errorIds = shown.map((error) => error.id);\n    // aria-errormessage references a single error element (the widely-supported\n    // IDREF form); any additional errors stay in aria-describedby below.\n    const primaryErrorId = errorIds[0];\n    if (primaryErrorId) {\n      control.setAttribute(\"aria-errormessage\", primaryErrorId);\n    } else {\n      control.removeAttribute(\"aria-errormessage\");\n    }\n\n    // Compose describedby: consumer tokens, then descriptions, then shown errors\n    // (so legacy AT that ignore aria-errormessage still read the error).\n    const describedBy = [\n      ...this.#baseDescribedBy,\n      ...this.descriptionTargets.map((description) => description.id),\n      ...errorIds,\n    ];\n    if (describedBy.length > 0) {\n      control.setAttribute(\"aria-describedby\", describedBy.join(\" \"));\n    } else {\n      control.removeAttribute(\"aria-describedby\");\n    }\n  }\n\n  /** Error targets currently visible and non-empty. */\n  #shownErrors(): HTMLElement[] {\n    return this.errorTargets.filter(\n      (error) => !error.hidden && (error.textContent ?? \"\").trim() !== \"\",\n    );\n  }\n\n  /** Text of the first shown error, for the `validate` event detail. */\n  #shownMessage(): string {\n    return (this.#shownErrors()[0]?.textContent ?? \"\").trim();\n  }\n\n  /** Resolves a message from a string argument or an action event's params. */\n  #resolveMessage(arg?: string | ActionEvent): string | null {\n    if (typeof arg === \"string\") return arg;\n    const message = arg?.params?.message;\n    return typeof message === \"string\" ? message : null;\n  }\n\n  /**\n   * Tokens already in the control's `aria-describedby` that are not ids of this\n   * controller's own description/error targets.\n   */\n  #externalDescribedByTokens(): string[] {\n    if (!this.hasControlTarget) return [];\n    const owned = new Set([\n      ...this.descriptionTargets.map((description) => description.id),\n      ...this.errorTargets.map((error) => error.id),\n    ]);\n    const existing = this.controlTarget.getAttribute(\"aria-describedby\") ?? \"\";\n    return existing.split(/\\s+/).filter((token) => token.length > 0 && !owned.has(token));\n  }\n}\n"]}

package/dist/controllers/form_validation_controller.d.ts

@@ -0,0 +1,114 @@
+import { Controller } from '@hotwired/stimulus';
+import { FormFieldController } from './form_field_controller.js';
+
+/**
+ * Headless, accessible **form-validation orchestration**.
+ *
+ * Markup contract (identifier: `stimeo--form-validation`):
+ *   <form data-controller="stimeo--form-validation"
+ *         data-stimeo--form-validation-stimeo--form-field-outlet="[data-controller~='stimeo--form-field']">
+ *     <div data-controller="stimeo--form-field">
+ *       <label for="email">Email</label>
+ *       <input id="email" type="email" required
+ *              data-stimeo--form-field-target="control" />
+ *       <p role="alert" hidden data-stimeo--form-field-target="error"></p>
+ *     </div>
+ *     <button type="submit">Save</button>
+ *   </form>
+ *
+ * Not an APG widget pattern — this is the *timing* layer for **error
+ * identification** (WCAG 3.3.1) and **error suggestion** (3.3.3): it decides
+ * *when* each control is checked and routes the browser's native
+ * `validationMessage` into the field's {@link FormFieldController} error region.
+ * The per-field ARIA wiring (`aria-invalid` / `aria-errormessage` /
+ * `aria-describedby`) therefore lives in exactly one place — `stimeo--form-field`,
+ * reached through a Stimulus **outlet** — and is never re-implemented here.
+ *
+ * @remarks
+ * Behavior only — validation **rules** stay in the markup (native HTML
+ * constraints: `required`, `type`, `pattern`, `min`/`max`, …) or in the consumer's
+ * own `setCustomValidity()` calls, which `checkValidity()` surfaces transparently.
+ * This controller never invents rules or messages and never styles. It sets the
+ * form's `novalidate` so it can replace the browser's default error bubbles with
+ * the accessible, in-page `role="alert"` regions, and restores the attribute on
+ * disconnect.
+ *
+ * Behavior provided:
+ * - On connect, suppresses native bubbles (`novalidate`, restored on disconnect)
+ *   and intercepts the form's `submit` in the **capture phase** so an invalid form
+ *   is cancelled before any other submit handler (e.g. `stimeo--submit-once`)
+ *   reacts to a submission that will never happen.
+ * - On submit, validates every control; if any is invalid it blocks submission,
+ *   moves focus to the first invalid control (unless `focusInvalid` is `false`),
+ *   and dispatches `stimeo--form-validation:invalid`. An all-valid form dispatches
+ *   `:valid` and submits normally.
+ * - Validates a field on blur once it has been interacted with (`validateOnBlur`),
+ *   and re-validates it on input while it is already touched
+ *   (`revalidateOnInput`) so a shown message clears the moment the value becomes
+ *   valid — but a pristine field is never eagerly flagged mid-typing.
+ *
+ * A control with no owning `stimeo--form-field` outlet is still validated (it can
+ * block submit and receive focus) but renders no message.
+ *
+ * Radio groups work unchanged: point the field's `control` target at the
+ * `role="radiogroup"` container so the invalid state lands on the group, and the
+ * group is reported as a single invalid entry (not one per radio).
+ *
+ * Rich widgets (listbox, time-picker, …) that keep their committed value in a
+ * hidden holder participate by making that holder a **validatable mirror**:
+ * `<input type="text" hidden required>` — the `hidden` *attribute*, not
+ * `type="hidden"`, which is barred from constraint validation. Native
+ * constraints then govern the widget's value with no extra JavaScript. The
+ * widget dispatches a bubbling `change` on the mirror when a value is committed
+ * (a completed interaction, so it validates immediately), and focus for an
+ * invalid mirror is delegated to the field's visible `control` target — the
+ * target itself when focusable, else its first focusable descendant.
+ *
+ * No-JS caveat: a `required` mirror also gates the browser's own pre-Stimulus
+ * validation, which cannot surface UI on an invisible control. When the no-JS
+ * fallback matters, author `novalidate` on the form (this controller preserves
+ * an author-set attribute) so the submission reaches the server's validation.
+ */
+declare class FormValidationController extends Controller<HTMLFormElement> {
+    #private;
+    static outlets: string[];
+    static values: {
+        validateOnBlur: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        validateOnChange: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        revalidateOnInput: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        focusInvalid: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+    };
+    static actions: readonly ["validate"];
+    static events: readonly ["valid", "invalid"];
+    readonly stimeoFormFieldOutlets: FormFieldController[];
+    readonly stimeoFormFieldOutletElements: HTMLElement[];
+    validateOnBlurValue: boolean;
+    validateOnChangeValue: boolean;
+    revalidateOnInputValue: boolean;
+    focusInvalidValue: boolean;
+    /** Suppresses native bubbles and binds the submit / blur / input listeners. */
+    connect(): void;
+    /** Tears down listeners and restores `novalidate` if we added it. */
+    disconnect(): void;
+    /**
+     * Validates every control now, rendering or clearing each field's message, and
+     * returns whether the whole form is valid. Marks every control touched so a
+     * later input re-validates it. Bound via `data-action`
+     * (`#validate`) or callable directly (e.g. before a programmatic submit).
+     */
+    validate(): boolean;
+}
+
+export { FormValidationController };