stimeo-ui 0.1.0-alpha.1 → 0.1.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+While the version is `0.x`, the public API (the `stimeo--*` data attributes) may
+change between releases.
+
+## [0.1.0-beta.1] - 2026-06-30
+
+First beta. The 101 core components meet the accessibility quality bar, so the
+library graduates from the `alpha` channel to `beta`.
+
+### Added
+
+- multi-select: emits named hidden fields so the current selection submits with
+  the form, no application JavaScript required.
+- form-validation: declarative per-constraint messages and a `disallow=whitespace`
+  rule.
+- hover-card, tooltip, and popover: opt-in dismiss when the page scrolls.
+- submit-once: auto-subscribes to `turbo:submit-start` on connect.
+
+### Fixed
+
+- Ignore keydown events fired during IME composition in tags-input, multi-select,
+  and combobox, so selecting a candidate no longer triggers shortcuts.
+
+## [0.1.0-alpha.1] - 2026-06-20
+
+Initial public alpha: 101 behavior-only, accessible Stimulus controllers driven
+by `data-*` attributes, shipping no CSS. Published to npm (with provenance) and
+RubyGems.
+
+[0.1.0-beta.1]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.1.0-beta.1
+[0.1.0-alpha.1]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.1.0-alpha.1

package/README.md

@@ -1,4 +1,13 @@
-# Stimeo UI
+<h1 align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/taiyaky/stimeo-ui/main/assets/logo-wordmark-dark.png">
+    <img alt="Stimeo UI" src="https://raw.githubusercontent.com/taiyaky/stimeo-ui/main/assets/logo-wordmark.png" width="240">
+  </picture>
+</h1>
+
+<p align="center"><a href="https://stimeo-labs.com"><strong>Live demo (beta) →</strong></a></p>
+
+[![CI](https://github.com/taiyaky/stimeo-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/taiyaky/stimeo-ui/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/stimeo-ui/beta)](https://www.npmjs.com/package/stimeo-ui) [![gem](https://img.shields.io/gem/v/stimeo-ui)](https://rubygems.org/gems/stimeo-ui) [![License: MIT](https://img.shields.io/github/license/taiyaky/stimeo-ui)](LICENSE)
 
 **Headless Stimulus UI framework for Ruby on Rails.** Stimeo UI ships *behavior*
 — ARIA state, keyboard interaction, focus management, Turbo resilience — as
@@ -14,7 +23,7 @@ owns the look entirely.
 - Public controller identifiers use the `stimeo--` namespace (e.g.
   `stimeo--dropdown`).
 
-> Status: **alpha** (`0.x`). The `stimeo--*` attribute API may still change before
+> Status: **beta** (`0.x`). The `stimeo--*` attribute API may still change before
 > 1.0 — pin your version.
 
 ## Install
@@ -22,7 +31,7 @@ owns the look entirely.
 ### Rails with importmap (recommended)
 
 ```bash
-bundle add stimeo-ui
+bundle add stimeo-ui --version "0.1.0.pre.beta.1"
 bin/rails generate stimeo:install
 ```
 
@@ -41,7 +50,7 @@ Stimulus application. Then drive components from HTML alone:
 ### npm (jsbundling or any bundler)
 
 ```bash
-npm install stimeo-ui @hotwired/stimulus
+npm install stimeo-ui@beta @hotwired/stimulus
 ```
 
 ```js
@@ -61,6 +70,50 @@ Need only a few controllers? Import them individually from
 - **No CSS is shipped.** Style the components yourself; controllers only toggle
   ARIA state and `data-*` hooks.
 
+## Linting
+
+Stimeo UI is headless, so **you** author the WAI-ARIA roles, states, and
+properties — and some controllers use explicit roles as selector contracts (the
+data-grid finds its rows via `[role="row"]`). Your markup therefore contains
+valid custom-widget ARIA such as `<ul role="menu">`, `<div role="radio">`, and
+`<table role="grid">…<td role="gridcell">`.
+
+Strict static a11y linters — Biome's `recommended` preset (≥ 2.5) and
+`eslint-plugin-jsx-a11y` — report these valid
+[APG](https://www.w3.org/WAI/ARIA/apg/) patterns as errors, because their
+heuristics assume native semantic elements (there is no native equivalent for a
+custom, fully-stylable radio). Relax the conflicting rules **only for the paths
+where you author Stimeo UI markup** — set `includes` to your own component
+directories (the value below is a placeholder; adjust it to your layout) and
+keep the rules on everywhere else. For Biome:
+
+```json
+{
+  "overrides": [
+    {
+      "includes": ["app/components/**"],
+      "linter": {
+        "rules": {
+          "a11y": {
+            "noNoninteractiveElementToInteractiveRole": "off",
+            "noRedundantRoles": "off",
+            "useSemanticElements": "off",
+            "useFocusableInteractive": "off",
+            "noNoninteractiveTabindex": "off"
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+The `eslint-plugin-jsx-a11y` equivalents are
+`no-noninteractive-element-to-interactive-role`, `no-redundant-roles`,
+`prefer-tag-over-role`, `interactive-supports-focus`, and
+`no-noninteractive-tabindex`. These components' real accessibility is exercised
+with axe-core and real screen readers in this project's own test suite.
+
 ## Contributing
 
 Bug reports and feature requests are very welcome — please open a GitHub issue.

package/dist/controllers/combobox_controller.js

@@ -60,6 +60,7 @@ var ComboboxController = class extends Controller {
   }
   /** Routes keyboard interaction per the APG combobox model. */
   onKeydown(event) {
+    if (event.isComposing || event.keyCode === 229) return;
     switch (event.key) {
       case "ArrowDown": {
         event.preventDefault();

package/dist/controllers/combobox_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/controllers/combobox_controller.ts"],"names":[],"mappings":";;;AA6CO,IAAM,kBAAA,GAAN,cAAiC,UAAA,CAAwB;AAAA,EAC9D,OAAgB,OAAA,GAAU,CAAC,OAAA,EAAS,QAAQ,QAAQ,CAAA;AAAA,EACpD,OAAO,OAAA,GAAU,CAAC,SAAS,QAAA,EAAU,WAAA,EAAa,QAAQ,eAAe,CAAA;AAAA,EACzE,OAAO,MAAA,GAAS,CAAC,UAAU,CAAA;AAAA;AAAA,EAS3B,YAAA,GAAe,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMf,aAAA,GAAgB,KAAA;AAAA;AAAA,EAGP,OAAA,GAAgB;AACvB,IAAA,IAAA,CAAK,KAAA,EAAM;AACX,IAAA,QAAA,CAAS,gBAAA,CAAiB,OAAA,EAAS,IAAA,CAAK,eAAe,CAAA;AAAA,EACzD;AAAA;AAAA,EAGS,UAAA,GAAmB;AAC1B,IAAA,QAAA,CAAS,mBAAA,CAAoB,OAAA,EAAS,IAAA,CAAK,eAAe,CAAA;AAAA,EAC5D;AAAA;AAAA,EAGA,MAAA,GAAe;AACb,IAAA,IAAA,CAAK,IAAA,EAAK;AAAA,EACZ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,IAAA,GAAa;AACX,IAAA,IAAI,CAAC,IAAA,CAAK,aAAA,IAAiB,IAAA,CAAK,aAAA,EAAe;AAC/C,IAAA,IAAA,CAAK,YAAA,EAAa;AAClB,IAAA,IAAA,CAAK,WAAW,MAAA,GAAS,KAAA;AACzB,IAAA,IAAA,CAAK,WAAA,CAAY,YAAA,CAAa,eAAA,EAAiB,MAAM,CAAA;AACrD,IAAA,IAAA,CAAK,WAAW,EAAE,CAAA;AAClB,IAAA,IAAA,CAAK,kBAAA,EAAmB;AAAA,EAC1B;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,YAAA,GAAqB;AACnB,IAAA,MAAM,QAAQ,IAAA,CAAK,WAAA,CAAY,KAAA,CAAM,IAAA,GAAO,WAAA,EAAY;AACxD,IAAA,KAAA,MAAW,MAAA,IAAU,KAAK,aAAA,EAAe;AACvC,MAAA,MAAM,QAAQ,MAAA,CAAO,WAAA,IAAe,EAAA,EAAI,IAAA,GAAO,WAAA,EAAY;AAC3D,MAAA,MAAA,CAAO,SAAS,KAAA,CAAM,MAAA,GAAS,KAAK,CAAC,IAAA,CAAK,SAAS,KAAK,CAAA;AAAA,IAC1D;AAAA,EACF;AAAA;AAAA,EAGA,KAAA,GAAc;AACZ,IAAA,IAAI,CAAC,KAAK,aAAA,EAAe;AACzB,IAAA,IAAA,CAAK,WAAW,MAAA,GAAS,IAAA;AACzB,IAAA,IAAA,CAAK,WAAA,CAAY,YAAA,CAAa,eAAA,EAAiB,OAAO,CAAA;AACtD,IAAA,IAAA,CAAK,WAAW,EAAE,CAAA;AAClB,IAAA,IAAA,CAAK,OAAA,CAAQ,gBAAgB,6BAA6B,CAAA;AAAA,EAC5D;AAAA;AAAA,EAGA,UAAU,KAAA,EAA4B;AACpC,IAAA,QAAQ,MAAM,GAAA;AAAK,MACjB,KAAK,WAAA,EAAa;AAChB,QAAA,KAAA,CAAM,cAAA,EAAe;AAErB,QAAA,IAAI,IAAA,CAAK,SAAA,EAAW,IAAA,CAAK,IAAA,EAAK;AAC9B,QAAA,MAAM,OAAA,GAAU,KAAK,eAAA,EAAgB;AACrC,QAAA,IAAI,OAAA,CAAQ,SAAS,CAAA,EAAG;AACtB,UAAA,MAAM,IAAA,GAAO,KAAK,YAAA,KAAiB,EAAA,GAAK,KAAK,IAAA,CAAK,YAAA,GAAe,KAAK,OAAA,CAAQ,MAAA;AAC9E,UAAA,IAAA,CAAK,WAAW,IAAI,CAAA;AAAA,QACtB;AACA,QAAA;AAAA,MACF;AAAA,MACA,KAAK,SAAA,EAAW;AACd,QAAA,KAAA,CAAM,cAAA,EAAe;AACrB,QAAA,IAAI,IAAA,CAAK,SAAA,EAAW,IAAA,CAAK,IAAA,EAAK;AAC9B,QAAA,MAAM,OAAA,GAAU,KAAK,eAAA,EAAgB;AACrC,QAAA,IAAI,OAAA,CAAQ,SAAS,CAAA,EAAG;AAGtB,UAAA,MAAM,IAAA,GACJ,IAAA,CAAK,YAAA,KAAiB,EAAA,GAClB,OAAA,CAAQ,MAAA,GAAS,CAAA,GAAA,CAChB,IAAA,CAAK,YAAA,GAAe,CAAA,GAAI,OAAA,CAAQ,MAAA,IAAU,OAAA,CAAQ,MAAA;AACzD,UAAA,IAAA,CAAK,WAAW,IAAI,CAAA;AAAA,QACtB;AACA,QAAA;AAAA,MACF;AAAA,MACA,KAAK,MAAA;AACH,QAAA,IAAI,CAAC,IAAA,CAAK,SAAA,IAAa,KAAK,eAAA,EAAgB,CAAE,SAAS,CAAA,EAAG;AACxD,UAAA,KAAA,CAAM,cAAA,EAAe;AACrB,UAAA,IAAA,CAAK,WAAW,CAAC,CAAA;AAAA,QACnB;AACA,QAAA;AAAA,MACF,KAAK,KAAA,EAAO;AACV,QAAA,MAAM,OAAA,GAAU,KAAK,eAAA,EAAgB;AACrC,QAAA,IAAI,CAAC,IAAA,CAAK,SAAA,IAAa,OAAA,CAAQ,SAAS,CAAA,EAAG;AACzC,UAAA,KAAA,CAAM,cAAA,EAAe;AACrB,UAAA,IAAA,CAAK,UAAA,CAAW,OAAA,CAAQ,MAAA,GAAS,CAAC,CAAA;AAAA,QACpC;AACA,QAAA;AAAA,MACF;AAAA,MACA,KAAK,OAAA,EAAS;AACZ,QAAA,MAAM,OAAA,GAAU,KAAK,eAAA,EAAgB;AACrC,QAAA,MAAM,SAAS,IAAA,CAAK,YAAA,KAAiB,KAAK,MAAA,GAAY,OAAA,CAAQ,KAAK,YAAY,CAAA;AAC/E,QAAA,IAAI,MAAA,EAAQ;AACV,UAAA,KAAA,CAAM,cAAA,EAAe;AACrB,UAAA,IAAA,CAAK,QAAQ,MAAM,CAAA;AAAA,QACrB;AACA,QAAA;AAAA,MACF;AAAA,MACA,KAAK,QAAA;AACH,QAAA,KAAA,CAAM,cAAA,EAAe;AACrB,QAAA,IAAA,CAAK,KAAA,EAAM;AACX,QAAA;AAAA,MACF,KAAK,KAAA;AAEH,QAAA,IAAA,CAAK,KAAA,EAAM;AACX,QAAA;AAEA;AACJ,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOS,eAAA,GAAkB,CAAC,KAAA,KAA4B;AACtD,IAAA,IAAI,CAAC,IAAA,CAAK,SAAA,IAAa,CAAC,IAAA,CAAK,OAAA,CAAQ,QAAA,CAAS,KAAA,CAAM,MAAc,CAAA,EAAG,IAAA,CAAK,KAAA,EAAM;AAAA,EAClF,CAAA;AAAA;AAAA,EAGA,cAAc,KAAA,EAAoB;AAChC,IAAA,MAAM,MAAA,GAAU,KAAA,CAAM,aAAA,CAA8B,OAAA,CAAqB,iBAAiB,CAAA;AAC1F,IAAA,IAAI,MAAA,EAAQ,IAAA,CAAK,OAAA,CAAQ,MAAM,CAAA;AAAA,EACjC;AAAA;AAAA,EAGA,QAAQ,MAAA,EAA2B;AACjC,IAAA,MAAM,QAAQ,MAAA,CAAO,OAAA,CAAQ,UAAU,MAAA,CAAO,WAAA,IAAe,IAAI,IAAA,EAAK;AACtE,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,WAAA,CAAY,KAAA,KAAU,KAAA;AAC3C,IAAA,IAAA,CAAK,YAAY,KAAA,GAAQ,KAAA;AACzB,IAAA,IAAA,CAAK,KAAA,EAAM;AAGX,IAAA,IAAA,CAAK,aAAA,GAAgB,IAAA;AACrB,IAAA,IAAA,CAAK,YAAY,KAAA,EAAM;AACvB,IAAA,IAAA,CAAK,aAAA,GAAgB,KAAA;AACrB,IAAA,IAAI,OAAA,EAAS;AAMX,MAAA,IAAA,CAAK,WAAA,CAAY,cAAc,IAAI,KAAA,CAAM,UAAU,EAAE,OAAA,EAAS,IAAA,EAAM,CAAC,CAAA;AAAA,IACvE;AACA,IAAA,IAAA,CAAK,SAAS,UAAA,EAAY,EAAE,QAAQ,EAAE,KAAA,IAAS,CAAA;AAAA,EACjD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,kBAAA,GAA2B;AACzB,IAAA,MAAM,QAAQ,CAAC,IAAA,CAAK,aAAa,IAAA,CAAK,eAAA,GAAkB,MAAA,KAAW,CAAA;AACnE,IAAA,IAAI,KAAA,EAAO;AACT,MAAA,IAAA,CAAK,OAAA,CAAQ,YAAA,CAAa,6BAAA,EAA+B,EAAE,CAAA;AAAA,IAC7D,CAAA,MAAO;AACL,MAAA,IAAA,CAAK,OAAA,CAAQ,gBAAgB,6BAA6B,CAAA;AAAA,IAC5D;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,WAAW,KAAA,EAAqB;AAC9B,IAAA,IAAA,CAAK,YAAA,GAAe,KAAA;AACpB,IAAA,MAAM,OAAA,GAAU,KAAK,eAAA,EAAgB;AACrC,IAAA,MAAM,MAAA,GAAS,KAAA,KAAU,EAAA,GAAK,IAAA,GAAO,QAAQ,KAAK,CAAA;AAIlD,IAAA,KAAA,MAAW,MAAA,IAAU,KAAK,aAAA,EAAe;AACvC,MAAA,MAAA,CAAO,YAAA,CAAa,eAAA,EAAiB,MAAA,KAAW,MAAA,GAAS,SAAS,OAAO,CAAA;AAAA,IAC3E;AACA,IAAA,IAAI,QAAQ,EAAA,EAAI;AACd,MAAA,IAAA,CAAK,WAAA,CAAY,YAAA,CAAa,uBAAA,EAAyB,MAAA,CAAO,EAAE,CAAA;AAAA,IAClE,CAAA,MAAO;AACL,MAAA,IAAA,CAAK,WAAA,CAAY,gBAAgB,uBAAuB,CAAA;AAAA,IAC1D;AAAA,EACF;AAAA;AAAA,EAGA,eAAA,GAAiC;AAC/B,IAAA,OAAO,KAAK,aAAA,CAAc,MAAA,CAAO,CAAC,MAAA,KAAW,CAAC,OAAO,MAAM,CAAA;AAAA,EAC7D;AAAA;AAAA,EAGA,IAAI,SAAA,GAAqB;AACvB,IAAA,OAAO,CAAC,IAAA,CAAK,aAAA,IAAiB,IAAA,CAAK,WAAW,MAAA,KAAW,KAAA;AAAA,EAC3D;AACF","file":"combobox_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/**\n * Headless, accessible combobox behavior (list autocomplete).\n *\n * Markup contract (identifier: `stimeo--combobox`):\n *   <div data-controller=\"stimeo--combobox\">\n *     <input type=\"text\" role=\"combobox\" aria-expanded=\"false\"\n *            aria-autocomplete=\"list\" aria-controls=\"listbox\"\n *            data-stimeo--combobox-target=\"input\"\n *            data-action=\"input->stimeo--combobox#filter\n *                         keydown->stimeo--combobox#onKeydown\n *                         focus->stimeo--combobox#open\n *                         click->stimeo--combobox#open\" />\n *     <ul id=\"listbox\" role=\"listbox\" data-stimeo--combobox-target=\"list\" hidden>\n *       <li role=\"option\" id=\"opt-apple\" data-value=\"apple\"\n *           data-stimeo--combobox-target=\"option\"\n *           data-action=\"click->stimeo--combobox#selectByClick\">Apple</li>\n *       <!-- more options -->\n *     </ul>\n *   </div>\n *\n * Implements the WAI-ARIA APG **Combobox** pattern with a listbox popup and\n * list-autocomplete. Focus stays in the input; the active option is tracked with\n * `aria-activedescendant` rather than by moving DOM focus.\n *\n * @remarks\n * Behavior only. Options are authored in the DOM; the controller filters them by\n * toggling each option's `hidden` attribute (case-insensitive substring match on\n * its text). The consumer owns styling, typically keyed off `[aria-selected]`.\n * When an open listbox has no matching options, the root element gets\n * `data-stimeo--combobox-empty` so the consumer can style the empty state (hide\n * the list, show a \"no results\" node, …) — the library imposes no visuals.\n *\n * Behavior provided:\n * - Typing filters the options and opens the listbox.\n * - Focusing or clicking the input opens the listbox, re-filtered against the\n *   current value (so re-opening with a non-matching value keeps the empty state).\n * - `ArrowDown`/`ArrowUp` move the active option (wrapping); `Enter` selects it;\n *   `Escape` closes the listbox; `Home`/`End` jump to the first/last visible\n *   option.\n * - Selecting an option fills the input (with the option's `data-value` if set,\n *   otherwise its text) and closes the listbox.\n * - A click outside the combobox closes the listbox.\n */\nexport class ComboboxController extends Controller<HTMLElement> {\n  static override targets = [\"input\", \"list\", \"option\"];\n  static actions = [\"close\", \"filter\", \"onKeydown\", \"open\", \"selectByClick\"] as const;\n  static events = [\"selected\"] as const;\n\n  declare readonly inputTarget: HTMLInputElement;\n  declare readonly listTarget: HTMLElement;\n  declare readonly optionTargets: HTMLElement[];\n  declare readonly hasInputTarget: boolean;\n  declare readonly hasListTarget: boolean;\n\n  /** Index into the *visible* options of the active option, or -1 if none. */\n  #activeIndex = -1;\n  /**\n   * Suppresses {@link open} for the duration of the programmatic re-focus in\n   * `#select`, so committing a value (which returns focus to the input)\n   * does not immediately re-open the listbox via a `focus`-bound action.\n   */\n  #suppressOpen = false;\n\n  /** Starts closed with no active option and registers the outside-click listener. */\n  override connect(): void {\n    this.close();\n    document.addEventListener(\"click\", this.#onOutsideClick);\n  }\n\n  /** Removes the document-level listener registered in {@link connect}. */\n  override disconnect(): void {\n    document.removeEventListener(\"click\", this.#onOutsideClick);\n  }\n\n  /** Filters options by the current input value and opens the listbox. */\n  filter(): void {\n    this.open();\n  }\n\n  /**\n   * Opens the listbox, re-filtering the options against the current input value\n   * so the visible options and empty state always match what is typed (e.g.\n   * re-opening with a stale non-matching value still surfaces the empty state).\n   */\n  open(): void {\n    if (!this.hasListTarget || this.#suppressOpen) return;\n    this.#applyFilter();\n    this.listTarget.hidden = false;\n    this.inputTarget.setAttribute(\"aria-expanded\", \"true\");\n    this.#setActive(-1);\n    this.#reflectEmptyState();\n  }\n\n  /**\n   * Hides options that don't match the current input value (case-insensitive\n   * substring). An empty query shows every option. Does not change open state.\n   */\n  #applyFilter(): void {\n    const query = this.inputTarget.value.trim().toLowerCase();\n    for (const option of this.optionTargets) {\n      const text = (option.textContent ?? \"\").trim().toLowerCase();\n      option.hidden = query.length > 0 && !text.includes(query);\n    }\n  }\n\n  /** Closes the listbox, clears the active option, and updates ARIA state. */\n  close(): void {\n    if (!this.hasListTarget) return;\n    this.listTarget.hidden = true;\n    this.inputTarget.setAttribute(\"aria-expanded\", \"false\");\n    this.#setActive(-1);\n    this.element.removeAttribute(\"data-stimeo--combobox-empty\");\n  }\n\n  /** Routes keyboard interaction per the APG combobox model. */\n  onKeydown(event: KeyboardEvent): void {\n    switch (event.key) {\n      case \"ArrowDown\": {\n        event.preventDefault();\n        // open() re-filters, so read the visible set afterwards.\n        if (this.#isClosed) this.open();\n        const visible = this.#visibleOptions();\n        if (visible.length > 0) {\n          const next = this.#activeIndex === -1 ? 0 : (this.#activeIndex + 1) % visible.length;\n          this.#setActive(next);\n        }\n        break;\n      }\n      case \"ArrowUp\": {\n        event.preventDefault();\n        if (this.#isClosed) this.open();\n        const visible = this.#visibleOptions();\n        if (visible.length > 0) {\n          // From the input (no active option) ArrowUp jumps to the last option,\n          // per the APG; otherwise it wraps backwards.\n          const next =\n            this.#activeIndex === -1\n              ? visible.length - 1\n              : (this.#activeIndex - 1 + visible.length) % visible.length;\n          this.#setActive(next);\n        }\n        break;\n      }\n      case \"Home\":\n        if (!this.#isClosed && this.#visibleOptions().length > 0) {\n          event.preventDefault();\n          this.#setActive(0);\n        }\n        break;\n      case \"End\": {\n        const visible = this.#visibleOptions();\n        if (!this.#isClosed && visible.length > 0) {\n          event.preventDefault();\n          this.#setActive(visible.length - 1);\n        }\n        break;\n      }\n      case \"Enter\": {\n        const visible = this.#visibleOptions();\n        const active = this.#activeIndex === -1 ? undefined : visible[this.#activeIndex];\n        if (active) {\n          event.preventDefault();\n          this.#select(active);\n        }\n        break;\n      }\n      case \"Escape\":\n        event.preventDefault();\n        this.close();\n        break;\n      case \"Tab\":\n        // Let focus leave naturally, but don't keep a stale popup open.\n        this.close();\n        break;\n      default:\n        break;\n    }\n  }\n\n  /**\n   * Closes the listbox when a click lands outside the combobox. Mirrors the menu\n   * button's outside-click behavior; clicks on an option are inside the element,\n   * so `#select` (not this handler) closes the popup after committing.\n   */\n  readonly #onOutsideClick = (event: MouseEvent): void => {\n    if (!this.#isClosed && !this.element.contains(event.target as Node)) this.close();\n  };\n\n  /** Selects the clicked option. Bound via `data-action` (click). */\n  selectByClick(event: Event): void {\n    const option = (event.currentTarget as HTMLElement).closest<HTMLElement>('[role=\"option\"]');\n    if (option) this.#select(option);\n  }\n\n  /** Commits an option: fills the input, closes the listbox, notifies listeners. */\n  #select(option: HTMLElement): void {\n    const value = option.dataset.value ?? (option.textContent ?? \"\").trim();\n    const changed = this.inputTarget.value !== value;\n    this.inputTarget.value = value;\n    this.close();\n    // Returning focus to the input would re-trigger a `focus`-bound open(); guard\n    // it so the listbox stays closed after a selection.\n    this.#suppressOpen = true;\n    this.inputTarget.focus();\n    this.#suppressOpen = false;\n    if (changed) {\n      // A native bubbling `change` (matching <select>/listbox semantics: only on\n      // an actual value change) so form-level behaviors — validation re-checks,\n      // auto-submit — hear the commit without knowing this widget. Deliberately\n      // NOT `input`: that is this combobox's own filter trigger and would reopen\n      // the popup on every selection.\n      this.inputTarget.dispatchEvent(new Event(\"change\", { bubbles: true }));\n    }\n    this.dispatch(\"selected\", { detail: { value } });\n  }\n\n  /**\n   * Reflects whether the open listbox currently has zero matching options by\n   * toggling `data-stimeo--combobox-empty` on the root element. Behavior only:\n   * consumers decide how to present the empty state (hide the list, show a\n   * \"no results\" node, etc.) via CSS keyed off this attribute.\n   */\n  #reflectEmptyState(): void {\n    const empty = !this.#isClosed && this.#visibleOptions().length === 0;\n    if (empty) {\n      this.element.setAttribute(\"data-stimeo--combobox-empty\", \"\");\n    } else {\n      this.element.removeAttribute(\"data-stimeo--combobox-empty\");\n    }\n  }\n\n  /**\n   * Marks the visible option at `index` active via `aria-selected` and the\n   * input's `aria-activedescendant`. Pass `-1` to clear the active option.\n   */\n  #setActive(index: number): void {\n    this.#activeIndex = index;\n    const visible = this.#visibleOptions();\n    const active = index === -1 ? null : visible[index];\n    // Clear aria-selected on every option (not just the visible ones) so a\n    // previously-active option that became hidden by filtering doesn't keep a\n    // stale selected state.\n    for (const option of this.optionTargets) {\n      option.setAttribute(\"aria-selected\", option === active ? \"true\" : \"false\");\n    }\n    if (active?.id) {\n      this.inputTarget.setAttribute(\"aria-activedescendant\", active.id);\n    } else {\n      this.inputTarget.removeAttribute(\"aria-activedescendant\");\n    }\n  }\n\n  /** The options currently shown (not filtered out). */\n  #visibleOptions(): HTMLElement[] {\n    return this.optionTargets.filter((option) => !option.hidden);\n  }\n\n  /** Whether the listbox is currently hidden. */\n  get #isClosed(): boolean {\n    return !this.hasListTarget || this.listTarget.hidden !== false;\n  }\n}\n"]}
+{"version":3,"sources":["../../src/controllers/combobox_controller.ts"],"names":[],"mappings":"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","file":"combobox_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/**\n * Headless, accessible combobox behavior (list autocomplete).\n *\n * Markup contract (identifier: `stimeo--combobox`):\n *   <div data-controller=\"stimeo--combobox\">\n *     <input type=\"text\" role=\"combobox\" aria-expanded=\"false\"\n *            aria-autocomplete=\"list\" aria-controls=\"listbox\"\n *            data-stimeo--combobox-target=\"input\"\n *            data-action=\"input->stimeo--combobox#filter\n *                         keydown->stimeo--combobox#onKeydown\n *                         focus->stimeo--combobox#open\n *                         click->stimeo--combobox#open\" />\n *     <ul id=\"listbox\" role=\"listbox\" data-stimeo--combobox-target=\"list\" hidden>\n *       <li role=\"option\" id=\"opt-apple\" data-value=\"apple\"\n *           data-stimeo--combobox-target=\"option\"\n *           data-action=\"click->stimeo--combobox#selectByClick\">Apple</li>\n *       <!-- more options -->\n *     </ul>\n *   </div>\n *\n * Implements the WAI-ARIA APG **Combobox** pattern with a listbox popup and\n * list-autocomplete. Focus stays in the input; the active option is tracked with\n * `aria-activedescendant` rather than by moving DOM focus.\n *\n * @remarks\n * Behavior only. Options are authored in the DOM; the controller filters them by\n * toggling each option's `hidden` attribute (case-insensitive substring match on\n * its text). The consumer owns styling, typically keyed off `[aria-selected]`.\n * When an open listbox has no matching options, the root element gets\n * `data-stimeo--combobox-empty` so the consumer can style the empty state (hide\n * the list, show a \"no results\" node, …) — the library imposes no visuals.\n *\n * Behavior provided:\n * - Typing filters the options and opens the listbox.\n * - Focusing or clicking the input opens the listbox, re-filtered against the\n *   current value (so re-opening with a non-matching value keeps the empty state).\n * - `ArrowDown`/`ArrowUp` move the active option (wrapping); `Enter` selects it;\n *   `Escape` closes the listbox; `Home`/`End` jump to the first/last visible\n *   option.\n * - Selecting an option fills the input (with the option's `data-value` if set,\n *   otherwise its text) and closes the listbox.\n * - A click outside the combobox closes the listbox.\n */\nexport class ComboboxController extends Controller<HTMLElement> {\n  static override targets = [\"input\", \"list\", \"option\"];\n  static actions = [\"close\", \"filter\", \"onKeydown\", \"open\", \"selectByClick\"] as const;\n  static events = [\"selected\"] as const;\n\n  declare readonly inputTarget: HTMLInputElement;\n  declare readonly listTarget: HTMLElement;\n  declare readonly optionTargets: HTMLElement[];\n  declare readonly hasInputTarget: boolean;\n  declare readonly hasListTarget: boolean;\n\n  /** Index into the *visible* options of the active option, or -1 if none. */\n  #activeIndex = -1;\n  /**\n   * Suppresses {@link open} for the duration of the programmatic re-focus in\n   * `#select`, so committing a value (which returns focus to the input)\n   * does not immediately re-open the listbox via a `focus`-bound action.\n   */\n  #suppressOpen = false;\n\n  /** Starts closed with no active option and registers the outside-click listener. */\n  override connect(): void {\n    this.close();\n    document.addEventListener(\"click\", this.#onOutsideClick);\n  }\n\n  /** Removes the document-level listener registered in {@link connect}. */\n  override disconnect(): void {\n    document.removeEventListener(\"click\", this.#onOutsideClick);\n  }\n\n  /** Filters options by the current input value and opens the listbox. */\n  filter(): void {\n    this.open();\n  }\n\n  /**\n   * Opens the listbox, re-filtering the options against the current input value\n   * so the visible options and empty state always match what is typed (e.g.\n   * re-opening with a stale non-matching value still surfaces the empty state).\n   */\n  open(): void {\n    if (!this.hasListTarget || this.#suppressOpen) return;\n    this.#applyFilter();\n    this.listTarget.hidden = false;\n    this.inputTarget.setAttribute(\"aria-expanded\", \"true\");\n    this.#setActive(-1);\n    this.#reflectEmptyState();\n  }\n\n  /**\n   * Hides options that don't match the current input value (case-insensitive\n   * substring). An empty query shows every option. Does not change open state.\n   */\n  #applyFilter(): void {\n    const query = this.inputTarget.value.trim().toLowerCase();\n    for (const option of this.optionTargets) {\n      const text = (option.textContent ?? \"\").trim().toLowerCase();\n      option.hidden = query.length > 0 && !text.includes(query);\n    }\n  }\n\n  /** Closes the listbox, clears the active option, and updates ARIA state. */\n  close(): void {\n    if (!this.hasListTarget) return;\n    this.listTarget.hidden = true;\n    this.inputTarget.setAttribute(\"aria-expanded\", \"false\");\n    this.#setActive(-1);\n    this.element.removeAttribute(\"data-stimeo--combobox-empty\");\n  }\n\n  /** Routes keyboard interaction per the APG combobox model. */\n  onKeydown(event: KeyboardEvent): void {\n    // Ignore keys fired during IME composition: the `Enter` that confirms a\n    // candidate (and arrows that move within it) must not select an option or\n    // close the popup. `keyCode === 229` covers browsers that omit `isComposing`\n    // on the confirming keydown. Aligns with the library's IME composition-guard\n    // policy (the keydown-level equivalent of the input-path guards in\n    // character-counter / auto-submit).\n    if (event.isComposing || event.keyCode === 229) return;\n    switch (event.key) {\n      case \"ArrowDown\": {\n        event.preventDefault();\n        // open() re-filters, so read the visible set afterwards.\n        if (this.#isClosed) this.open();\n        const visible = this.#visibleOptions();\n        if (visible.length > 0) {\n          const next = this.#activeIndex === -1 ? 0 : (this.#activeIndex + 1) % visible.length;\n          this.#setActive(next);\n        }\n        break;\n      }\n      case \"ArrowUp\": {\n        event.preventDefault();\n        if (this.#isClosed) this.open();\n        const visible = this.#visibleOptions();\n        if (visible.length > 0) {\n          // From the input (no active option) ArrowUp jumps to the last option,\n          // per the APG; otherwise it wraps backwards.\n          const next =\n            this.#activeIndex === -1\n              ? visible.length - 1\n              : (this.#activeIndex - 1 + visible.length) % visible.length;\n          this.#setActive(next);\n        }\n        break;\n      }\n      case \"Home\":\n        if (!this.#isClosed && this.#visibleOptions().length > 0) {\n          event.preventDefault();\n          this.#setActive(0);\n        }\n        break;\n      case \"End\": {\n        const visible = this.#visibleOptions();\n        if (!this.#isClosed && visible.length > 0) {\n          event.preventDefault();\n          this.#setActive(visible.length - 1);\n        }\n        break;\n      }\n      case \"Enter\": {\n        const visible = this.#visibleOptions();\n        const active = this.#activeIndex === -1 ? undefined : visible[this.#activeIndex];\n        if (active) {\n          event.preventDefault();\n          this.#select(active);\n        }\n        break;\n      }\n      case \"Escape\":\n        event.preventDefault();\n        this.close();\n        break;\n      case \"Tab\":\n        // Let focus leave naturally, but don't keep a stale popup open.\n        this.close();\n        break;\n      default:\n        break;\n    }\n  }\n\n  /**\n   * Closes the listbox when a click lands outside the combobox. Mirrors the menu\n   * button's outside-click behavior; clicks on an option are inside the element,\n   * so `#select` (not this handler) closes the popup after committing.\n   */\n  readonly #onOutsideClick = (event: MouseEvent): void => {\n    if (!this.#isClosed && !this.element.contains(event.target as Node)) this.close();\n  };\n\n  /** Selects the clicked option. Bound via `data-action` (click). */\n  selectByClick(event: Event): void {\n    const option = (event.currentTarget as HTMLElement).closest<HTMLElement>('[role=\"option\"]');\n    if (option) this.#select(option);\n  }\n\n  /** Commits an option: fills the input, closes the listbox, notifies listeners. */\n  #select(option: HTMLElement): void {\n    const value = option.dataset.value ?? (option.textContent ?? \"\").trim();\n    const changed = this.inputTarget.value !== value;\n    this.inputTarget.value = value;\n    this.close();\n    // Returning focus to the input would re-trigger a `focus`-bound open(); guard\n    // it so the listbox stays closed after a selection.\n    this.#suppressOpen = true;\n    this.inputTarget.focus();\n    this.#suppressOpen = false;\n    if (changed) {\n      // A native bubbling `change` (matching <select>/listbox semantics: only on\n      // an actual value change) so form-level behaviors — validation re-checks,\n      // auto-submit — hear the commit without knowing this widget. Deliberately\n      // NOT `input`: that is this combobox's own filter trigger and would reopen\n      // the popup on every selection.\n      this.inputTarget.dispatchEvent(new Event(\"change\", { bubbles: true }));\n    }\n    this.dispatch(\"selected\", { detail: { value } });\n  }\n\n  /**\n   * Reflects whether the open listbox currently has zero matching options by\n   * toggling `data-stimeo--combobox-empty` on the root element. Behavior only:\n   * consumers decide how to present the empty state (hide the list, show a\n   * \"no results\" node, etc.) via CSS keyed off this attribute.\n   */\n  #reflectEmptyState(): void {\n    const empty = !this.#isClosed && this.#visibleOptions().length === 0;\n    if (empty) {\n      this.element.setAttribute(\"data-stimeo--combobox-empty\", \"\");\n    } else {\n      this.element.removeAttribute(\"data-stimeo--combobox-empty\");\n    }\n  }\n\n  /**\n   * Marks the visible option at `index` active via `aria-selected` and the\n   * input's `aria-activedescendant`. Pass `-1` to clear the active option.\n   */\n  #setActive(index: number): void {\n    this.#activeIndex = index;\n    const visible = this.#visibleOptions();\n    const active = index === -1 ? null : visible[index];\n    // Clear aria-selected on every option (not just the visible ones) so a\n    // previously-active option that became hidden by filtering doesn't keep a\n    // stale selected state.\n    for (const option of this.optionTargets) {\n      option.setAttribute(\"aria-selected\", option === active ? \"true\" : \"false\");\n    }\n    if (active?.id) {\n      this.inputTarget.setAttribute(\"aria-activedescendant\", active.id);\n    } else {\n      this.inputTarget.removeAttribute(\"aria-activedescendant\");\n    }\n  }\n\n  /** The options currently shown (not filtered out). */\n  #visibleOptions(): HTMLElement[] {\n    return this.optionTargets.filter((option) => !option.hidden);\n  }\n\n  /** Whether the listbox is currently hidden. */\n  get #isClosed(): boolean {\n    return !this.hasListTarget || this.listTarget.hidden !== false;\n  }\n}\n"]}

package/dist/controllers/form_validation_controller.d.ts

@@ -28,10 +28,22 @@ import { FormFieldController } from './form_field_controller.js';
  * 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.
+ * 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.
+ *
+ * Two declarative escape hatches let a field **exceed** native validation with no
+ * consumer JS (author them on the control):
+ * - **Per-constraint messages** — `data-stimeo--form-field-message-<constraint>`
+ *   (`value-missing`, `too-short`, `too-long`, `pattern-mismatch`, `type-mismatch`,
+ *   `range-overflow`, `range-underflow`, `step-mismatch`, `bad-input`), or a generic
+ *   `data-stimeo--form-field-message` fallback, override the shown text per failing
+ *   `ValidityState` flag — controlled, localizable wording that also fixes headless
+ *   browsers returning an empty native `validationMessage`. Falls back to native.
+ * - **`data-stimeo--form-field-disallow="whitespace"`** — a built-in custom rule
+ *   rejecting a value that is blank after trimming (which slips past `required` /
+ *   `minlength`), wired through `setCustomValidity` so it blocks submit like any
+ *   native constraint.
  *
  * Behavior provided:
  * - On connect, suppresses native bubbles (`novalidate`, restored on disconnect)

package/dist/controllers/form_validation_controller.js

@@ -6,6 +6,21 @@ import { Controller } from '@hotwired/stimulus';
 var FOCUSABLE = 'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
 
 // src/controllers/form_validation_controller.ts
+var CONSTRAINT_MESSAGE_KEYS = [
+  ["valueMissing", "value-missing"],
+  ["typeMismatch", "type-mismatch"],
+  ["patternMismatch", "pattern-mismatch"],
+  ["tooShort", "too-short"],
+  ["tooLong", "too-long"],
+  ["rangeUnderflow", "range-underflow"],
+  ["rangeOverflow", "range-overflow"],
+  ["stepMismatch", "step-mismatch"],
+  ["badInput", "bad-input"]
+];
+var MESSAGE_ATTR_PREFIX = "data-stimeo--form-field-message-";
+var MESSAGE_ATTR_GENERIC = "data-stimeo--form-field-message";
+var DISALLOW_ATTR = "data-stimeo--form-field-disallow";
+var DISALLOW_WHITESPACE_DEFAULT = "Please enter a value that is not only whitespace.";
 var FormValidationController = class _FormValidationController extends Controller {
   static outlets = ["stimeo--form-field"];
   static values = {
@@ -20,6 +35,12 @@ var FormValidationController = class _FormValidationController extends Controlle
   static #NOVALIDATE_MARKER = "data-stimeo--form-validation-novalidate";
   /** Controls already interacted with — the gate for blur / input (re)validation. */
   #touched = /* @__PURE__ */ new WeakSet();
+  /**
+   * Controls whose `customError` *we* set via the `disallow` rule. Tracked so we
+   * only ever clear our own custom validity — a consumer's `setCustomValidity` on
+   * the same control survives once our rule passes (don't-clobber-authored-state).
+   */
+  #ownedCustomError = /* @__PURE__ */ new WeakSet();
   #onSubmit = (event) => {
     if (event.target !== this.element) return;
     const invalid = this.#validateAll();
@@ -131,16 +152,56 @@ var FormValidationController = class _FormValidationController extends Controlle
    * Routing goes through the outlet, so the ARIA wiring is never duplicated here.
    */
   #applyGroup(group) {
+    for (const control of group.controls) this.#syncCustomValidity(control);
     const firstInvalid = group.controls.find((control) => !control.checkValidity()) ?? null;
     if (group.field) {
       if (firstInvalid) {
-        group.field.setError(firstInvalid.validationMessage);
+        group.field.setError(this.#messageFor(firstInvalid));
       } else {
         group.field.clearError();
       }
     }
     return firstInvalid;
   }
+  /**
+   * Resolves the message to show for an invalid control: a per-constraint
+   * override (`data-stimeo--form-field-message-<constraint>`) for the first failing
+   * `ValidityState` flag, then a generic `data-stimeo--form-field-message`
+   * override, then the browser's native `validationMessage`. Authoring an override
+   * gives controlled, localizable, theme-able wording with **no consumer JS** —
+   * and sidesteps headless browsers that return an empty native message.
+   */
+  #messageFor(control) {
+    for (const [flag, key] of CONSTRAINT_MESSAGE_KEYS) {
+      if (control.validity[flag]) {
+        return control.getAttribute(`${MESSAGE_ATTR_PREFIX}${key}`) ?? control.getAttribute(MESSAGE_ATTR_GENERIC) ?? control.validationMessage;
+      }
+    }
+    return control.validationMessage || control.getAttribute(MESSAGE_ATTR_GENERIC) || "";
+  }
+  /**
+   * Applies (or clears) a declarative custom constraint via `setCustomValidity`,
+   * for controls that opt in with `data-stimeo--form-field-disallow`. The one
+   * supported rule today is `"whitespace"` — a value that is non-empty but blank
+   * after trimming (which slips past `required` / `minlength`); its message follows
+   * the per-constraint (`value-missing`) → generic → default chain.
+   *
+   * Don't-clobber-authored-state: an unknown/absent rule is never touched, and a
+   * custom error is only cleared when *we* set it (tracked in {@link #ownedCustomError}),
+   * so a consumer's own `setCustomValidity` on the same control survives.
+   */
+  #syncCustomValidity(control) {
+    const violates = control.getAttribute(DISALLOW_ATTR) === "whitespace" && control.value.length > 0 && control.value.trim() === "";
+    if (violates) {
+      control.setCustomValidity(
+        control.getAttribute(`${MESSAGE_ATTR_PREFIX}value-missing`) ?? control.getAttribute(MESSAGE_ATTR_GENERIC) ?? DISALLOW_WHITESPACE_DEFAULT
+      );
+      this.#ownedCustomError.add(control);
+    } else if (this.#ownedCustomError.has(control)) {
+      this.#ownedCustomError.delete(control);
+      control.setCustomValidity("");
+    }
+  }
   /**
    * A grouping key that collects controls belonging to the same field: the owning
    * `stimeo--form-field` when present, else a radio group's shared `name`, else

package/dist/controllers/form_validation_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/focus_trap.ts","../../src/controllers/form_validation_controller.ts"],"names":[],"mappings":"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","file":"form_validation_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 { FOCUSABLE } from \"../utils/focus_trap\";\nimport type { FormFieldController } from \"./form_field_controller\";\n\n/** Native form controls that participate in constraint validation. */\ntype ValidatableControl = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;\n\n/** A field's validatable controls, grouped so the whole field validates together. */\ninterface FieldGroup {\n  readonly field: FormFieldController | undefined;\n  readonly controls: ValidatableControl[];\n}\n\n/**\n * Headless, accessible **form-validation orchestration**.\n *\n * Markup contract (identifier: `stimeo--form-validation`):\n *   <form data-controller=\"stimeo--form-validation\"\n *         data-stimeo--form-validation-stimeo--form-field-outlet=\"[data-controller~='stimeo--form-field']\">\n *     <div data-controller=\"stimeo--form-field\">\n *       <label for=\"email\">Email</label>\n *       <input id=\"email\" type=\"email\" required\n *              data-stimeo--form-field-target=\"control\" />\n *       <p role=\"alert\" hidden data-stimeo--form-field-target=\"error\"></p>\n *     </div>\n *     <button type=\"submit\">Save</button>\n *   </form>\n *\n * Not an APG widget pattern — this is the *timing* layer for **error\n * identification** (WCAG 3.3.1) and **error suggestion** (3.3.3): it decides\n * *when* each control is checked and routes the browser's native\n * `validationMessage` into the field's {@link FormFieldController} error region.\n * The per-field ARIA wiring (`aria-invalid` / `aria-errormessage` /\n * `aria-describedby`) therefore lives in exactly one place — `stimeo--form-field`,\n * reached through a Stimulus **outlet** — and is never re-implemented here.\n *\n * @remarks\n * Behavior only — validation **rules** stay in the markup (native HTML\n * constraints: `required`, `type`, `pattern`, `min`/`max`, …) or in the consumer's\n * own `setCustomValidity()` calls, which `checkValidity()` surfaces transparently.\n * This controller never invents rules or messages and never styles. It sets the\n * form's `novalidate` so it can replace the browser's default error bubbles with\n * the accessible, in-page `role=\"alert\"` regions, and restores the attribute on\n * disconnect.\n *\n * Behavior provided:\n * - On connect, suppresses native bubbles (`novalidate`, restored on disconnect)\n *   and intercepts the form's `submit` in the **capture phase** so an invalid form\n *   is cancelled before any other submit handler (e.g. `stimeo--submit-once`)\n *   reacts to a submission that will never happen.\n * - On submit, validates every control; if any is invalid it blocks submission,\n *   moves focus to the first invalid control (unless `focusInvalid` is `false`),\n *   and dispatches `stimeo--form-validation:invalid`. An all-valid form dispatches\n *   `:valid` and submits normally.\n * - Validates a field on blur once it has been interacted with (`validateOnBlur`),\n *   and re-validates it on input while it is already touched\n *   (`revalidateOnInput`) so a shown message clears the moment the value becomes\n *   valid — but a pristine field is never eagerly flagged mid-typing.\n *\n * A control with no owning `stimeo--form-field` outlet is still validated (it can\n * block submit and receive focus) but renders no message.\n *\n * Radio groups work unchanged: point the field's `control` target at the\n * `role=\"radiogroup\"` container so the invalid state lands on the group, and the\n * group is reported as a single invalid entry (not one per radio).\n *\n * Rich widgets (listbox, time-picker, …) that keep their committed value in a\n * hidden holder participate by making that holder a **validatable mirror**:\n * `<input type=\"text\" hidden required>` — the `hidden` *attribute*, not\n * `type=\"hidden\"`, which is barred from constraint validation. Native\n * constraints then govern the widget's value with no extra JavaScript. The\n * widget dispatches a bubbling `change` on the mirror when a value is committed\n * (a completed interaction, so it validates immediately), and focus for an\n * invalid mirror is delegated to the field's visible `control` target — the\n * target itself when focusable, else its first focusable descendant.\n *\n * No-JS caveat: a `required` mirror also gates the browser's own pre-Stimulus\n * validation, which cannot surface UI on an invisible control. When the no-JS\n * fallback matters, author `novalidate` on the form (this controller preserves\n * an author-set attribute) so the submission reaches the server's validation.\n */\nexport class FormValidationController extends Controller<HTMLFormElement> {\n  static override outlets = [\"stimeo--form-field\"];\n  static override values = {\n    validateOnBlur: { type: Boolean, default: true },\n    validateOnChange: { type: Boolean, default: true },\n    revalidateOnInput: { type: Boolean, default: true },\n    focusInvalid: { type: Boolean, default: true },\n  };\n  static actions = [\"validate\"] as const;\n  static events = [\"valid\", \"invalid\"] as const;\n\n  declare readonly stimeoFormFieldOutlets: FormFieldController[];\n  declare readonly stimeoFormFieldOutletElements: HTMLElement[];\n\n  declare validateOnBlurValue: boolean;\n  declare validateOnChangeValue: boolean;\n  declare revalidateOnInputValue: boolean;\n  declare focusInvalidValue: boolean;\n\n  /** Marker recording that we added `novalidate`, so we only remove our own. */\n  static readonly #NOVALIDATE_MARKER = \"data-stimeo--form-validation-novalidate\";\n\n  /** Controls already interacted with — the gate for blur / input (re)validation. */\n  readonly #touched = new WeakSet<ValidatableControl>();\n\n  readonly #onSubmit = (event: SubmitEvent): void => {\n    if (event.target !== this.element) return;\n    const invalid = this.#validateAll();\n    if (invalid.length === 0) {\n      this.dispatch(\"valid\", { detail: {} });\n      return;\n    }\n    // Cancel the whole submit: preventDefault stops native/Turbo navigation;\n    // stopImmediatePropagation keeps later submit handlers (e.g. submit-once's\n    // busy state) from acting on a submission that will never happen.\n    event.preventDefault();\n    event.stopImmediatePropagation();\n    const first = invalid[0];\n    if (this.focusInvalidValue && first) this.#focusTargetFor(first)?.focus();\n    this.dispatch(\"invalid\", { detail: { invalid } });\n  };\n\n  readonly #onFocusOut = (event: FocusEvent): void => {\n    if (!this.validateOnBlurValue) return;\n    const control = this.#controlFrom(event.target);\n    if (!control) return;\n    // Focus moving *within* the same field (e.g. between members of a radio\n    // group) is not leaving it — defer validation until focus actually exits.\n    const field = this.#fieldFor(control);\n    const related = event.relatedTarget;\n    if (field && related instanceof Node && field.element.contains(related)) return;\n    this.#touched.add(control);\n    this.#validateControl(control);\n  };\n\n  readonly #onInput = (event: Event): void => {\n    if (!this.revalidateOnInputValue) return;\n    const control = this.#controlFrom(event.target);\n    // Only re-validate a field the user has already left once, so the first\n    // keystroke never eagerly flags a control they are still filling in.\n    if (!control || !this.#touched.has(control)) return;\n    this.#validateControl(control);\n  };\n\n  readonly #onChange = (event: Event): void => {\n    if (!this.validateOnChangeValue) return;\n    const control = this.#controlFrom(event.target);\n    if (!control) return;\n    // change marks a *committed* interaction (a picked option, a toggled box, a\n    // widget writing its mirror), so unlike input it both touches and validates.\n    this.#touched.add(control);\n    this.#validateControl(control);\n  };\n\n  /** Suppresses native bubbles and binds the submit / blur / input listeners. */\n  override connect(): void {\n    if (!this.element.hasAttribute(\"novalidate\")) {\n      this.element.setAttribute(\"novalidate\", \"\");\n      this.element.setAttribute(FormValidationController.#NOVALIDATE_MARKER, \"\");\n    }\n    // Capture phase on the document so we run before any submit listener bound to\n    // the form itself (Stimulus actions, submit-once), whose relative order in the\n    // target phase would otherwise be unpredictable.\n    document.addEventListener(\"submit\", this.#onSubmit, true);\n    this.element.addEventListener(\"focusout\", this.#onFocusOut);\n    this.element.addEventListener(\"input\", this.#onInput);\n    this.element.addEventListener(\"change\", this.#onChange);\n  }\n\n  /** Tears down listeners and restores `novalidate` if we added it. */\n  override disconnect(): void {\n    document.removeEventListener(\"submit\", this.#onSubmit, true);\n    this.element.removeEventListener(\"focusout\", this.#onFocusOut);\n    this.element.removeEventListener(\"input\", this.#onInput);\n    this.element.removeEventListener(\"change\", this.#onChange);\n    if (this.element.hasAttribute(FormValidationController.#NOVALIDATE_MARKER)) {\n      this.element.removeAttribute(\"novalidate\");\n      this.element.removeAttribute(FormValidationController.#NOVALIDATE_MARKER);\n    }\n  }\n\n  /**\n   * Validates every control now, rendering or clearing each field's message, and\n   * returns whether the whole form is valid. Marks every control touched so a\n   * later input re-validates it. Bound via `data-action`\n   * (`#validate`) or callable directly (e.g. before a programmatic submit).\n   */\n  validate(): boolean {\n    return this.#validateAll().length === 0;\n  }\n\n  /**\n   * Validates every control and returns one invalid control per field. Controls\n   * are grouped by field first (see {@link #keyFor}) so a field with several\n   * controls — a radio group, or a mirror plus its visible control — reflects\n   * *all* of them: a valid sibling must never clear an invalid one's message.\n   * Each group's first invalid control supplies the message and the focus target.\n   */\n  #validateAll(): ValidatableControl[] {\n    const groups = new Map<unknown, FieldGroup>();\n    for (const control of this.#controls) {\n      this.#touched.add(control);\n      const field = this.#fieldFor(control);\n      const key = this.#keyFor(control, field);\n      const group = groups.get(key);\n      if (group) {\n        group.controls.push(control);\n      } else {\n        groups.set(key, { field, controls: [control] });\n      }\n    }\n\n    const invalid: ValidatableControl[] = [];\n    for (const group of groups.values()) {\n      const firstInvalid = this.#applyGroup(group);\n      if (firstInvalid) invalid.push(firstInvalid);\n    }\n    return invalid;\n  }\n\n  /** Re-validates the whole field a single control belongs to (or that control). */\n  #validateControl(control: ValidatableControl): void {\n    const field = this.#fieldFor(control);\n    const key = this.#keyFor(control, field);\n    const controls = this.#controls.filter(\n      (other) => this.#keyFor(other, this.#fieldFor(other)) === key,\n    );\n    this.#applyGroup({ field, controls });\n  }\n\n  /**\n   * Runs native constraint validation across a field's controls and routes the\n   * result to its `stimeo--form-field` outlet: the first invalid control's\n   * `validationMessage` is shown, an all-valid field is cleared. Returns the\n   * first invalid control (for the invalid list / focus), or `null` when valid.\n   * Routing goes through the outlet, so the ARIA wiring is never duplicated here.\n   */\n  #applyGroup(group: FieldGroup): ValidatableControl | null {\n    const firstInvalid = group.controls.find((control) => !control.checkValidity()) ?? null;\n    if (group.field) {\n      if (firstInvalid) {\n        group.field.setError(firstInvalid.validationMessage);\n      } else {\n        group.field.clearError();\n      }\n    }\n    return firstInvalid;\n  }\n\n  /**\n   * A grouping key that collects controls belonging to the same field: the owning\n   * `stimeo--form-field` when present, else a radio group's shared `name`, else\n   * the control itself (always distinct).\n   */\n  #keyFor(control: ValidatableControl, field: FormFieldController | undefined): unknown {\n    if (field) return field;\n    if (control instanceof HTMLInputElement && control.type === \"radio\" && control.name) {\n      return `radio:${control.name}`;\n    }\n    return control;\n  }\n\n  /**\n   * Where focus should land for an invalid control. A visible control is focused\n   * directly (status quo for native fields and radios). A validatable mirror\n   * (the `hidden` attribute) cannot receive focus, so focus is delegated to the\n   * visible widget: the owning field's `control` target when it is itself\n   * focusable, else its first focusable descendant (e.g. a roving-tabindex\n   * member). Resolved structurally — never by probing `focus()` — so behavior\n   * is deterministic and CSS-independent.\n   */\n  #focusTargetFor(control: ValidatableControl): HTMLElement | null {\n    if (!control.hidden) return control;\n    const field = this.#fieldFor(control);\n    if (!field?.hasControlTarget) return null;\n    const root = field.controlTarget;\n    if (root.matches(FOCUSABLE)) return root;\n    return root.querySelector<HTMLElement>(FOCUSABLE);\n  }\n\n  /** The `stimeo--form-field` outlet whose element contains `control`, if any. */\n  #fieldFor(control: ValidatableControl): FormFieldController | undefined {\n    const elements = this.stimeoFormFieldOutletElements;\n    for (let index = 0; index < elements.length; index++) {\n      if (elements[index]?.contains(control)) return this.stimeoFormFieldOutlets[index];\n    }\n    return undefined;\n  }\n\n  /** This form's native controls that participate in constraint validation. */\n  get #controls(): ValidatableControl[] {\n    const controls: ValidatableControl[] = [];\n    for (const element of Array.from(this.element.elements)) {\n      if (this.#isValidatable(element)) controls.push(element);\n    }\n    return controls;\n  }\n\n  /** Narrows an event target to a validatable control. */\n  #controlFrom(target: EventTarget | null): ValidatableControl | null {\n    return target instanceof Element && this.#isValidatable(target) ? target : null;\n  }\n\n  #isValidatable(element: Element): element is ValidatableControl {\n    return (\n      (element instanceof HTMLInputElement ||\n        element instanceof HTMLSelectElement ||\n        element instanceof HTMLTextAreaElement) &&\n      // `willValidate` already excludes disabled, read-only, hidden, and button\n      // controls — the exact set barred from constraint validation.\n      element.willValidate\n    );\n  }\n}\n"]}
+{"version":3,"sources":["../../src/utils/focus_trap.ts","../../src/controllers/form_validation_controller.ts"],"names":[],"mappings":"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","file":"form_validation_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 { FOCUSABLE } from \"../utils/focus_trap\";\nimport type { FormFieldController } from \"./form_field_controller\";\n\n/** Native form controls that participate in constraint validation. */\ntype ValidatableControl = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;\n\n/**\n * Maps each `ValidityState` flag (in priority order) to the kebab-case suffix of\n * its per-constraint message-override attribute. The first flag that is `true`\n * wins, so e.g. `valueMissing` is reported before a stale `patternMismatch`.\n */\nconst CONSTRAINT_MESSAGE_KEYS: ReadonlyArray<readonly [keyof ValidityState, string]> = [\n  [\"valueMissing\", \"value-missing\"],\n  [\"typeMismatch\", \"type-mismatch\"],\n  [\"patternMismatch\", \"pattern-mismatch\"],\n  [\"tooShort\", \"too-short\"],\n  [\"tooLong\", \"too-long\"],\n  [\"rangeUnderflow\", \"range-underflow\"],\n  [\"rangeOverflow\", \"range-overflow\"],\n  [\"stepMismatch\", \"step-mismatch\"],\n  [\"badInput\", \"bad-input\"],\n];\n\n/** Attribute prefix for a per-constraint message override, authored on the control. */\nconst MESSAGE_ATTR_PREFIX = \"data-stimeo--form-field-message-\";\n/** Attribute for a generic message override applied to any failing constraint. */\nconst MESSAGE_ATTR_GENERIC = \"data-stimeo--form-field-message\";\n/** Attribute opting a control into a declarative custom rule (`\"whitespace\"`). */\nconst DISALLOW_ATTR = \"data-stimeo--form-field-disallow\";\n/** Default message when `disallow=\"whitespace\"` fails and no override is given. */\nconst DISALLOW_WHITESPACE_DEFAULT = \"Please enter a value that is not only whitespace.\";\n\n/** A field's validatable controls, grouped so the whole field validates together. */\ninterface FieldGroup {\n  readonly field: FormFieldController | undefined;\n  readonly controls: ValidatableControl[];\n}\n\n/**\n * Headless, accessible **form-validation orchestration**.\n *\n * Markup contract (identifier: `stimeo--form-validation`):\n *   <form data-controller=\"stimeo--form-validation\"\n *         data-stimeo--form-validation-stimeo--form-field-outlet=\"[data-controller~='stimeo--form-field']\">\n *     <div data-controller=\"stimeo--form-field\">\n *       <label for=\"email\">Email</label>\n *       <input id=\"email\" type=\"email\" required\n *              data-stimeo--form-field-target=\"control\" />\n *       <p role=\"alert\" hidden data-stimeo--form-field-target=\"error\"></p>\n *     </div>\n *     <button type=\"submit\">Save</button>\n *   </form>\n *\n * Not an APG widget pattern — this is the *timing* layer for **error\n * identification** (WCAG 3.3.1) and **error suggestion** (3.3.3): it decides\n * *when* each control is checked and routes the browser's native\n * `validationMessage` into the field's {@link FormFieldController} error region.\n * The per-field ARIA wiring (`aria-invalid` / `aria-errormessage` /\n * `aria-describedby`) therefore lives in exactly one place — `stimeo--form-field`,\n * reached through a Stimulus **outlet** — and is never re-implemented here.\n *\n * @remarks\n * Behavior only — validation **rules** stay in the markup (native HTML\n * constraints: `required`, `type`, `pattern`, `min`/`max`, …) or in the consumer's\n * own `setCustomValidity()` calls, which `checkValidity()` surfaces transparently.\n * It sets the form's `novalidate` so it can replace the browser's default error\n * bubbles with the accessible, in-page `role=\"alert\"` regions, and restores the\n * attribute on disconnect.\n *\n * Two declarative escape hatches let a field **exceed** native validation with no\n * consumer JS (author them on the control):\n * - **Per-constraint messages** — `data-stimeo--form-field-message-<constraint>`\n *   (`value-missing`, `too-short`, `too-long`, `pattern-mismatch`, `type-mismatch`,\n *   `range-overflow`, `range-underflow`, `step-mismatch`, `bad-input`), or a generic\n *   `data-stimeo--form-field-message` fallback, override the shown text per failing\n *   `ValidityState` flag — controlled, localizable wording that also fixes headless\n *   browsers returning an empty native `validationMessage`. Falls back to native.\n * - **`data-stimeo--form-field-disallow=\"whitespace\"`** — a built-in custom rule\n *   rejecting a value that is blank after trimming (which slips past `required` /\n *   `minlength`), wired through `setCustomValidity` so it blocks submit like any\n *   native constraint.\n *\n * Behavior provided:\n * - On connect, suppresses native bubbles (`novalidate`, restored on disconnect)\n *   and intercepts the form's `submit` in the **capture phase** so an invalid form\n *   is cancelled before any other submit handler (e.g. `stimeo--submit-once`)\n *   reacts to a submission that will never happen.\n * - On submit, validates every control; if any is invalid it blocks submission,\n *   moves focus to the first invalid control (unless `focusInvalid` is `false`),\n *   and dispatches `stimeo--form-validation:invalid`. An all-valid form dispatches\n *   `:valid` and submits normally.\n * - Validates a field on blur once it has been interacted with (`validateOnBlur`),\n *   and re-validates it on input while it is already touched\n *   (`revalidateOnInput`) so a shown message clears the moment the value becomes\n *   valid — but a pristine field is never eagerly flagged mid-typing.\n *\n * A control with no owning `stimeo--form-field` outlet is still validated (it can\n * block submit and receive focus) but renders no message.\n *\n * Radio groups work unchanged: point the field's `control` target at the\n * `role=\"radiogroup\"` container so the invalid state lands on the group, and the\n * group is reported as a single invalid entry (not one per radio).\n *\n * Rich widgets (listbox, time-picker, …) that keep their committed value in a\n * hidden holder participate by making that holder a **validatable mirror**:\n * `<input type=\"text\" hidden required>` — the `hidden` *attribute*, not\n * `type=\"hidden\"`, which is barred from constraint validation. Native\n * constraints then govern the widget's value with no extra JavaScript. The\n * widget dispatches a bubbling `change` on the mirror when a value is committed\n * (a completed interaction, so it validates immediately), and focus for an\n * invalid mirror is delegated to the field's visible `control` target — the\n * target itself when focusable, else its first focusable descendant.\n *\n * No-JS caveat: a `required` mirror also gates the browser's own pre-Stimulus\n * validation, which cannot surface UI on an invisible control. When the no-JS\n * fallback matters, author `novalidate` on the form (this controller preserves\n * an author-set attribute) so the submission reaches the server's validation.\n */\nexport class FormValidationController extends Controller<HTMLFormElement> {\n  static override outlets = [\"stimeo--form-field\"];\n  static override values = {\n    validateOnBlur: { type: Boolean, default: true },\n    validateOnChange: { type: Boolean, default: true },\n    revalidateOnInput: { type: Boolean, default: true },\n    focusInvalid: { type: Boolean, default: true },\n  };\n  static actions = [\"validate\"] as const;\n  static events = [\"valid\", \"invalid\"] as const;\n\n  declare readonly stimeoFormFieldOutlets: FormFieldController[];\n  declare readonly stimeoFormFieldOutletElements: HTMLElement[];\n\n  declare validateOnBlurValue: boolean;\n  declare validateOnChangeValue: boolean;\n  declare revalidateOnInputValue: boolean;\n  declare focusInvalidValue: boolean;\n\n  /** Marker recording that we added `novalidate`, so we only remove our own. */\n  static readonly #NOVALIDATE_MARKER = \"data-stimeo--form-validation-novalidate\";\n\n  /** Controls already interacted with — the gate for blur / input (re)validation. */\n  readonly #touched = new WeakSet<ValidatableControl>();\n\n  /**\n   * Controls whose `customError` *we* set via the `disallow` rule. Tracked so we\n   * only ever clear our own custom validity — a consumer's `setCustomValidity` on\n   * the same control survives once our rule passes (don't-clobber-authored-state).\n   */\n  readonly #ownedCustomError = new WeakSet<ValidatableControl>();\n\n  readonly #onSubmit = (event: SubmitEvent): void => {\n    if (event.target !== this.element) return;\n    const invalid = this.#validateAll();\n    if (invalid.length === 0) {\n      this.dispatch(\"valid\", { detail: {} });\n      return;\n    }\n    // Cancel the whole submit: preventDefault stops native/Turbo navigation;\n    // stopImmediatePropagation keeps later submit handlers (e.g. submit-once's\n    // busy state) from acting on a submission that will never happen.\n    event.preventDefault();\n    event.stopImmediatePropagation();\n    const first = invalid[0];\n    if (this.focusInvalidValue && first) this.#focusTargetFor(first)?.focus();\n    this.dispatch(\"invalid\", { detail: { invalid } });\n  };\n\n  readonly #onFocusOut = (event: FocusEvent): void => {\n    if (!this.validateOnBlurValue) return;\n    const control = this.#controlFrom(event.target);\n    if (!control) return;\n    // Focus moving *within* the same field (e.g. between members of a radio\n    // group) is not leaving it — defer validation until focus actually exits.\n    const field = this.#fieldFor(control);\n    const related = event.relatedTarget;\n    if (field && related instanceof Node && field.element.contains(related)) return;\n    this.#touched.add(control);\n    this.#validateControl(control);\n  };\n\n  readonly #onInput = (event: Event): void => {\n    if (!this.revalidateOnInputValue) return;\n    const control = this.#controlFrom(event.target);\n    // Only re-validate a field the user has already left once, so the first\n    // keystroke never eagerly flags a control they are still filling in.\n    if (!control || !this.#touched.has(control)) return;\n    this.#validateControl(control);\n  };\n\n  readonly #onChange = (event: Event): void => {\n    if (!this.validateOnChangeValue) return;\n    const control = this.#controlFrom(event.target);\n    if (!control) return;\n    // change marks a *committed* interaction (a picked option, a toggled box, a\n    // widget writing its mirror), so unlike input it both touches and validates.\n    this.#touched.add(control);\n    this.#validateControl(control);\n  };\n\n  /** Suppresses native bubbles and binds the submit / blur / input listeners. */\n  override connect(): void {\n    if (!this.element.hasAttribute(\"novalidate\")) {\n      this.element.setAttribute(\"novalidate\", \"\");\n      this.element.setAttribute(FormValidationController.#NOVALIDATE_MARKER, \"\");\n    }\n    // Capture phase on the document so we run before any submit listener bound to\n    // the form itself (Stimulus actions, submit-once), whose relative order in the\n    // target phase would otherwise be unpredictable.\n    document.addEventListener(\"submit\", this.#onSubmit, true);\n    this.element.addEventListener(\"focusout\", this.#onFocusOut);\n    this.element.addEventListener(\"input\", this.#onInput);\n    this.element.addEventListener(\"change\", this.#onChange);\n  }\n\n  /** Tears down listeners and restores `novalidate` if we added it. */\n  override disconnect(): void {\n    document.removeEventListener(\"submit\", this.#onSubmit, true);\n    this.element.removeEventListener(\"focusout\", this.#onFocusOut);\n    this.element.removeEventListener(\"input\", this.#onInput);\n    this.element.removeEventListener(\"change\", this.#onChange);\n    if (this.element.hasAttribute(FormValidationController.#NOVALIDATE_MARKER)) {\n      this.element.removeAttribute(\"novalidate\");\n      this.element.removeAttribute(FormValidationController.#NOVALIDATE_MARKER);\n    }\n  }\n\n  /**\n   * Validates every control now, rendering or clearing each field's message, and\n   * returns whether the whole form is valid. Marks every control touched so a\n   * later input re-validates it. Bound via `data-action`\n   * (`#validate`) or callable directly (e.g. before a programmatic submit).\n   */\n  validate(): boolean {\n    return this.#validateAll().length === 0;\n  }\n\n  /**\n   * Validates every control and returns one invalid control per field. Controls\n   * are grouped by field first (see {@link #keyFor}) so a field with several\n   * controls — a radio group, or a mirror plus its visible control — reflects\n   * *all* of them: a valid sibling must never clear an invalid one's message.\n   * Each group's first invalid control supplies the message and the focus target.\n   */\n  #validateAll(): ValidatableControl[] {\n    const groups = new Map<unknown, FieldGroup>();\n    for (const control of this.#controls) {\n      this.#touched.add(control);\n      const field = this.#fieldFor(control);\n      const key = this.#keyFor(control, field);\n      const group = groups.get(key);\n      if (group) {\n        group.controls.push(control);\n      } else {\n        groups.set(key, { field, controls: [control] });\n      }\n    }\n\n    const invalid: ValidatableControl[] = [];\n    for (const group of groups.values()) {\n      const firstInvalid = this.#applyGroup(group);\n      if (firstInvalid) invalid.push(firstInvalid);\n    }\n    return invalid;\n  }\n\n  /** Re-validates the whole field a single control belongs to (or that control). */\n  #validateControl(control: ValidatableControl): void {\n    const field = this.#fieldFor(control);\n    const key = this.#keyFor(control, field);\n    const controls = this.#controls.filter(\n      (other) => this.#keyFor(other, this.#fieldFor(other)) === key,\n    );\n    this.#applyGroup({ field, controls });\n  }\n\n  /**\n   * Runs native constraint validation across a field's controls and routes the\n   * result to its `stimeo--form-field` outlet: the first invalid control's\n   * `validationMessage` is shown, an all-valid field is cleared. Returns the\n   * first invalid control (for the invalid list / focus), or `null` when valid.\n   * Routing goes through the outlet, so the ARIA wiring is never duplicated here.\n   */\n  #applyGroup(group: FieldGroup): ValidatableControl | null {\n    // Apply declarative custom rules (e.g. disallow=\"whitespace\") before reading\n    // validity so they participate in checkValidity() like a native constraint.\n    for (const control of group.controls) this.#syncCustomValidity(control);\n    const firstInvalid = group.controls.find((control) => !control.checkValidity()) ?? null;\n    if (group.field) {\n      if (firstInvalid) {\n        group.field.setError(this.#messageFor(firstInvalid));\n      } else {\n        group.field.clearError();\n      }\n    }\n    return firstInvalid;\n  }\n\n  /**\n   * Resolves the message to show for an invalid control: a per-constraint\n   * override (`data-stimeo--form-field-message-<constraint>`) for the first failing\n   * `ValidityState` flag, then a generic `data-stimeo--form-field-message`\n   * override, then the browser's native `validationMessage`. Authoring an override\n   * gives controlled, localizable, theme-able wording with **no consumer JS** —\n   * and sidesteps headless browsers that return an empty native message.\n   */\n  #messageFor(control: ValidatableControl): string {\n    for (const [flag, key] of CONSTRAINT_MESSAGE_KEYS) {\n      if (control.validity[flag]) {\n        return (\n          control.getAttribute(`${MESSAGE_ATTR_PREFIX}${key}`) ??\n          control.getAttribute(MESSAGE_ATTR_GENERIC) ??\n          control.validationMessage\n        );\n      }\n    }\n    // customError (our `disallow` rule, or a consumer's setCustomValidity): for our\n    // rule the message was already resolved with per-constraint > generic > default\n    // precedence when set, and a consumer error carries its own text — so return the\n    // live validationMessage as-is, falling back to the generic override then \"\".\n    return control.validationMessage || control.getAttribute(MESSAGE_ATTR_GENERIC) || \"\";\n  }\n\n  /**\n   * Applies (or clears) a declarative custom constraint via `setCustomValidity`,\n   * for controls that opt in with `data-stimeo--form-field-disallow`. The one\n   * supported rule today is `\"whitespace\"` — a value that is non-empty but blank\n   * after trimming (which slips past `required` / `minlength`); its message follows\n   * the per-constraint (`value-missing`) → generic → default chain.\n   *\n   * Don't-clobber-authored-state: an unknown/absent rule is never touched, and a\n   * custom error is only cleared when *we* set it (tracked in {@link #ownedCustomError}),\n   * so a consumer's own `setCustomValidity` on the same control survives.\n   */\n  #syncCustomValidity(control: ValidatableControl): void {\n    const violates =\n      control.getAttribute(DISALLOW_ATTR) === \"whitespace\" &&\n      control.value.length > 0 &&\n      control.value.trim() === \"\";\n    if (violates) {\n      control.setCustomValidity(\n        control.getAttribute(`${MESSAGE_ATTR_PREFIX}value-missing`) ??\n          control.getAttribute(MESSAGE_ATTR_GENERIC) ??\n          DISALLOW_WHITESPACE_DEFAULT,\n      );\n      this.#ownedCustomError.add(control);\n    } else if (this.#ownedCustomError.has(control)) {\n      // Only clear the custom error we previously set; leave a consumer's intact.\n      this.#ownedCustomError.delete(control);\n      control.setCustomValidity(\"\");\n    }\n  }\n\n  /**\n   * A grouping key that collects controls belonging to the same field: the owning\n   * `stimeo--form-field` when present, else a radio group's shared `name`, else\n   * the control itself (always distinct).\n   */\n  #keyFor(control: ValidatableControl, field: FormFieldController | undefined): unknown {\n    if (field) return field;\n    if (control instanceof HTMLInputElement && control.type === \"radio\" && control.name) {\n      return `radio:${control.name}`;\n    }\n    return control;\n  }\n\n  /**\n   * Where focus should land for an invalid control. A visible control is focused\n   * directly (status quo for native fields and radios). A validatable mirror\n   * (the `hidden` attribute) cannot receive focus, so focus is delegated to the\n   * visible widget: the owning field's `control` target when it is itself\n   * focusable, else its first focusable descendant (e.g. a roving-tabindex\n   * member). Resolved structurally — never by probing `focus()` — so behavior\n   * is deterministic and CSS-independent.\n   */\n  #focusTargetFor(control: ValidatableControl): HTMLElement | null {\n    if (!control.hidden) return control;\n    const field = this.#fieldFor(control);\n    if (!field?.hasControlTarget) return null;\n    const root = field.controlTarget;\n    if (root.matches(FOCUSABLE)) return root;\n    return root.querySelector<HTMLElement>(FOCUSABLE);\n  }\n\n  /** The `stimeo--form-field` outlet whose element contains `control`, if any. */\n  #fieldFor(control: ValidatableControl): FormFieldController | undefined {\n    const elements = this.stimeoFormFieldOutletElements;\n    for (let index = 0; index < elements.length; index++) {\n      if (elements[index]?.contains(control)) return this.stimeoFormFieldOutlets[index];\n    }\n    return undefined;\n  }\n\n  /** This form's native controls that participate in constraint validation. */\n  get #controls(): ValidatableControl[] {\n    const controls: ValidatableControl[] = [];\n    for (const element of Array.from(this.element.elements)) {\n      if (this.#isValidatable(element)) controls.push(element);\n    }\n    return controls;\n  }\n\n  /** Narrows an event target to a validatable control. */\n  #controlFrom(target: EventTarget | null): ValidatableControl | null {\n    return target instanceof Element && this.#isValidatable(target) ? target : null;\n  }\n\n  #isValidatable(element: Element): element is ValidatableControl {\n    return (\n      (element instanceof HTMLInputElement ||\n        element instanceof HTMLSelectElement ||\n        element instanceof HTMLTextAreaElement) &&\n      // `willValidate` already excludes disabled, read-only, hidden, and button\n      // controls — the exact set barred from constraint validation.\n      element.willValidate\n    );\n  }\n}\n"]}

package/dist/controllers/hover_card_controller.d.ts

@@ -38,6 +38,10 @@ import { Controller } from '@hotwired/stimulus';
  *   closes regardless of where focus sits (card, trigger, or elsewhere).
  * - Open/closed flips the trigger's `aria-expanded`, the card's `hidden`, and a
  *   `data-state` (`open`/`closed`). Focus is never stolen on open.
+ * - Opt-in **dismiss on scroll** (`closeOnScroll`): while open, scrolling a tracked
+ *   scroll-parent ancestor (or the window) closes the card — the Radix / floating-ui
+ *   convention. Covers keyboard/programmatic scroll and scrollbar-drag, which the
+ *   pointer-leave close cannot. Off by default.
  */
 declare class HoverCardController extends Controller<HTMLElement> {
     #private;
@@ -51,6 +55,10 @@ declare class HoverCardController extends Controller<HTMLElement> {
             type: NumberConstructor;
             default: number;
         };
+        closeOnScroll: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
     };
     static actions: readonly ["close", "onKeydown", "open"];
     readonly triggerTarget: HTMLElement;
@@ -59,9 +67,10 @@ declare class HoverCardController extends Controller<HTMLElement> {
     readonly hasCardTarget: boolean;
     readonly openDelayValue: number;
     readonly closeDelayValue: number;
+    readonly closeOnScrollValue: boolean;
     /** Starts closed. */
     connect(): void;
-    /** Clears timers and the document `Escape` listener so nothing outlives the element. */
+    /** Clears timers and the document `Escape` / scroll listeners so nothing outlives the element. */
     disconnect(): void;
     /** Opens the card, after `openDelay` ms (or immediately at 0). Cancels a pending close. */
     open(): void;