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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34dbcfca1f64a125bc86e2d946b7c2c62753f02e67c7444b4b25823f9ed3f3a3
-  data.tar.gz: fb0661197fe81c6559960f2b74d0dfffd5d126f3b285edda5123bf2fe37db6e3
+  metadata.gz: d5958af6bffb81de09834ec57bed72292dccba82e858e62c87b99a43f769cc94
+  data.tar.gz: 4a35a8a27e890e26652fa67bf44739e8a9e28993df7bfd7b912ca33b39fef11b
 SHA512:
-  metadata.gz: 6f1578a41271afa0633a19c627200e4abe957ce7b6fb7e2d9013db876d75fd84140af7e3b98a8c0e37ffa931c159f9c952b444105b099882cc61bbfde220085b
-  data.tar.gz: 2037a7c5dfb426bdc8f19bc6d14e689d488695eb545b59b58572bfbccd8db9d6dd6d9102d129a79d6baef3371ca1bd2301a0a6d353877584601689460c03e2e4
+  metadata.gz: b288d136c73d80180990c922f83999d9eabc8b03cf2e1c685ee0c9ebcbbb3f46aecb336888200570ff8caf481049a147f3bdeb70b53611be76a14ae4a7ab7e1f
+  data.tar.gz: 8155446be40a4afbff0d10608797da863cd5264efc03507c018478aa3d0121029083fd8f6d28ed3d704604e9d2f4eb02dfc23641aeaeb57bf04961c5d573c1b3

data/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

data/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)](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
 ```
 
@@ -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.

data/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();

data/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

data/dist/controllers/hover_card_controller.js

@@ -55,26 +55,56 @@ var SafeTimeout = class extends TimerRegistry {
   }
 };
 
+// src/utils/scroll_dismiss.ts
+function observeScrollDismiss(element, onScroll) {
+  const targets = [...scrollParents(element), window];
+  const handler = () => onScroll();
+  for (const target of targets) {
+    target.addEventListener("scroll", handler, { passive: true });
+  }
+  return () => {
+    for (const target of targets) target.removeEventListener("scroll", handler);
+  };
+}
+function scrollParents(element) {
+  const parents = [];
+  let node = element.parentElement;
+  while (node) {
+    if (isScrollable(node)) parents.push(node);
+    node = node.parentElement;
+  }
+  return parents;
+}
+function isScrollable(element) {
+  const style = getComputedStyle(element);
+  return /auto|scroll|overlay/.test(style.overflow + style.overflowX + style.overflowY);
+}
+
 // src/controllers/hover_card_controller.ts
 var HoverCardController = class extends Controller {
   static targets = ["trigger", "card"];
   static values = {
     openDelay: { type: Number, default: 300 },
-    closeDelay: { type: Number, default: 200 }
+    closeDelay: { type: Number, default: 200 },
+    closeOnScroll: { type: Boolean, default: false }
   };
   static actions = ["close", "onKeydown", "open"];
   /** Pending open/close timers, torn down together on disconnect. */
   #timers = new SafeTimeout();
   #pendingOpen = null;
   #pendingClose = null;
+  /** Cleanup for the dismiss-on-scroll listeners while open, or `null`. */
+  #stopScrollDismiss = null;
   /** Starts closed. */
   connect() {
     this.#conceal();
   }
-  /** 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() {
     this.#timers.clearAll();
     document.removeEventListener("keydown", this.#onDocumentKeydown);
+    this.#stopScrollDismiss?.();
+    this.#stopScrollDismiss = null;
   }
   /** Opens the card, after `openDelay` ms (or immediately at 0). Cancels a pending close. */
   open() {
@@ -111,21 +141,26 @@ var HoverCardController = class extends Controller {
       this.#dismiss();
     }
   }
-  /** Reveals the card, reflects state, and starts watching for a dismissing `Escape`. */
+  /** Reveals the card, reflects state, and starts watching for a dismissing `Escape`/scroll. */
   #reveal() {
     if (!this.hasCardTarget) return;
     this.cardTarget.hidden = false;
     this.cardTarget.setAttribute("data-state", "open");
     if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "true");
     document.addEventListener("keydown", this.#onDocumentKeydown);
+    if (this.closeOnScrollValue && !this.#stopScrollDismiss) {
+      this.#stopScrollDismiss = observeScrollDismiss(this.element, () => this.#dismiss());
+    }
   }
-  /** Hides the card, reflects state, and stops watching for `Escape`. */
+  /** Hides the card, reflects state, and stops watching for `Escape`/scroll. */
   #conceal() {
+    document.removeEventListener("keydown", this.#onDocumentKeydown);
+    this.#stopScrollDismiss?.();
+    this.#stopScrollDismiss = null;
     if (!this.hasCardTarget) return;
     this.cardTarget.hidden = true;
     this.cardTarget.setAttribute("data-state", "closed");
     if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "false");
-    document.removeEventListener("keydown", this.#onDocumentKeydown);
   }
   /** Cancels pending timers and conceals immediately (shared Escape path). */
   #dismiss() {

data/dist/controllers/popover_controller.js

@@ -1,9 +1,41 @@
 import { Controller } from '@hotwired/stimulus';
 
+// src/controllers/popover_controller.ts
+
+// src/utils/scroll_dismiss.ts
+function observeScrollDismiss(element, onScroll) {
+  const targets = [...scrollParents(element), window];
+  const handler = () => onScroll();
+  for (const target of targets) {
+    target.addEventListener("scroll", handler, { passive: true });
+  }
+  return () => {
+    for (const target of targets) target.removeEventListener("scroll", handler);
+  };
+}
+function scrollParents(element) {
+  const parents = [];
+  let node = element.parentElement;
+  while (node) {
+    if (isScrollable(node)) parents.push(node);
+    node = node.parentElement;
+  }
+  return parents;
+}
+function isScrollable(element) {
+  const style = getComputedStyle(element);
+  return /auto|scroll|overlay/.test(style.overflow + style.overflowX + style.overflowY);
+}
+
 // src/controllers/popover_controller.ts
 var PopoverController = class _PopoverController extends Controller {
   static targets = ["trigger", "panel"];
+  static values = {
+    closeOnScroll: { type: Boolean, default: false }
+  };
   static actions = ["close", "open", "toggle"];
+  /** Cleanup for the dismiss-on-scroll listeners while open, or `null`. */
+  #stopScrollDismiss = null;
   /** Selector for natively focusable elements used to find the first one. */
   static #FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
   /** Starts closed and registers the document-level dismissal listeners. */
@@ -22,6 +54,8 @@ var PopoverController = class _PopoverController extends Controller {
     document.removeEventListener("click", this.#onOutsideClick);
     document.removeEventListener("keydown", this.#onKeydown);
     if (this.hasPanelTarget) this.panelTarget.removeEventListener("focusout", this.#onFocusOut);
+    this.#stopScrollDismiss?.();
+    this.#stopScrollDismiss = null;
   }
   /** Toggles the popover. Bound via `data-action` (click on the trigger). */
   toggle() {
@@ -37,12 +71,17 @@ var PopoverController = class _PopoverController extends Controller {
     this.panelTarget.hidden = false;
     if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "true");
     this.panelTarget.addEventListener("focusout", this.#onFocusOut);
+    if (this.closeOnScrollValue && !this.#stopScrollDismiss) {
+      this.#stopScrollDismiss = observeScrollDismiss(this.element, () => this.close());
+    }
     this.#focusFirst();
   }
   /** Closes the panel and reflects the collapsed state. Bound via `data-action`. */
   close() {
     if (!this.hasPanelTarget) return;
     this.panelTarget.removeEventListener("focusout", this.#onFocusOut);
+    this.#stopScrollDismiss?.();
+    this.#stopScrollDismiss = null;
     this.panelTarget.hidden = true;
     if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "false");
   }

data/dist/controllers/submit_once_controller.js

@@ -72,19 +72,28 @@ var SubmitOnceController = class extends Controller {
   #timeoutId = null;
   #busy = false;
   #submitter = null;
+  #onSubmitStart = (event) => {
+    this.start(event);
+  };
   #onSubmitEnd = (event) => {
     const success = event.detail?.success;
     this.#restore(success);
   };
   connect() {
+    this.element.addEventListener("turbo:submit-start", this.#onSubmitStart);
     this.element.addEventListener("turbo:submit-end", this.#onSubmitEnd);
     this.#clearStaleBusy();
   }
   disconnect() {
+    this.element.removeEventListener("turbo:submit-start", this.#onSubmitStart);
     this.element.removeEventListener("turbo:submit-end", this.#onSubmitEnd);
     this.#clearTimeout();
   }
-  /** Enters the busy state for the submission started by `event`. */
+  /**
+   * Enters the busy state for the submission started by `event`. Accepts both a
+   * native `SubmitEvent` (manual `submit->#start` on non-Turbo forms) and Turbo's
+   * `turbo:submit-start` CustomEvent (auto-subscribed in `connect`).
+   */
   start(event) {
     if (this.#busy) return;
     this.#busy = true;
@@ -158,12 +167,24 @@ var SubmitOnceController = class extends Controller {
   }
   /** The triggering button: the event's submitter when ours, else the first button. */
   #resolveSubmitter(event, buttons) {
-    const submitter = event.submitter;
+    const submitter = this.#eventSubmitter(event);
     if (submitter && this.#isSubmitButton(submitter) && buttons.includes(submitter)) {
       return submitter;
     }
     return buttons[0] ?? null;
   }
+  /**
+   * Reads the submitter from a native `SubmitEvent` (`event.submitter`) or from
+   * Turbo's `turbo:submit-start` detail (`detail.formSubmission.submitter`), so
+   * the busy label swaps onto the right button under either path.
+   */
+  #eventSubmitter(event) {
+    if (typeof SubmitEvent !== "undefined" && event instanceof SubmitEvent) {
+      return event.submitter;
+    }
+    const detail = event.detail;
+    return detail?.formSubmission?.submitter ?? null;
+  }
   /** The controlled buttons: `submit` targets, or the form's native submit controls. */
   get #buttons() {
     if (this.hasSubmitTarget) return this.submitTargets;

data/dist/controllers/tooltip_controller.js

@@ -55,12 +55,38 @@ var SafeTimeout = class extends TimerRegistry {
   }
 };
 
+// src/utils/scroll_dismiss.ts
+function observeScrollDismiss(element, onScroll) {
+  const targets = [...scrollParents(element), window];
+  const handler = () => onScroll();
+  for (const target of targets) {
+    target.addEventListener("scroll", handler, { passive: true });
+  }
+  return () => {
+    for (const target of targets) target.removeEventListener("scroll", handler);
+  };
+}
+function scrollParents(element) {
+  const parents = [];
+  let node = element.parentElement;
+  while (node) {
+    if (isScrollable(node)) parents.push(node);
+    node = node.parentElement;
+  }
+  return parents;
+}
+function isScrollable(element) {
+  const style = getComputedStyle(element);
+  return /auto|scroll|overlay/.test(style.overflow + style.overflowX + style.overflowY);
+}
+
 // src/controllers/tooltip_controller.ts
 var TooltipController = class extends Controller {
   static targets = ["trigger", "content"];
   static values = {
     showDelay: { type: Number, default: 0 },
-    hideDelay: { type: Number, default: 0 }
+    hideDelay: { type: Number, default: 0 },
+    closeOnScroll: { type: Boolean, default: false }
   };
   static actions = ["hide", "onKeydown", "show"];
   /** Pending show/hide timers, torn down together on disconnect. */
@@ -68,14 +94,18 @@ var TooltipController = class extends Controller {
   /** The id of the currently pending show or hide timer, if any. */
   #pendingShow = null;
   #pendingHide = null;
+  /** Cleanup for the dismiss-on-scroll listeners while shown, or `null`. */
+  #stopScrollDismiss = null;
   /** Starts hidden. */
   connect() {
     this.#conceal();
   }
-  /** 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() {
     this.#timers.clearAll();
     document.removeEventListener("keydown", this.#onDocumentKeydown);
+    this.#stopScrollDismiss?.();
+    this.#stopScrollDismiss = null;
   }
   /** Shows the tooltip, after `showDelay` ms (or immediately at 0). Cancels a pending hide. */
   show() {
@@ -117,19 +147,28 @@ var TooltipController = class extends Controller {
       this.#conceal();
     }
   }
-  /** Reveals the content and starts watching for a dismissing `Escape`. */
+  /** Reveals the content and starts watching for a dismissing `Escape`/scroll. */
   #reveal() {
     if (!this.hasContentTarget) return;
     this.contentTarget.hidden = false;
     this.contentTarget.setAttribute("data-state", "open");
     document.addEventListener("keydown", this.#onDocumentKeydown);
+    if (this.closeOnScrollValue && !this.#stopScrollDismiss) {
+      this.#stopScrollDismiss = observeScrollDismiss(this.element, () => {
+        this.#cancelShow();
+        this.#cancelHide();
+        this.#conceal();
+      });
+    }
   }
-  /** Hides the content and stops watching for `Escape`. */
+  /** Hides the content and stops watching for `Escape`/scroll. */
   #conceal() {
+    document.removeEventListener("keydown", this.#onDocumentKeydown);
+    this.#stopScrollDismiss?.();
+    this.#stopScrollDismiss = null;
     if (!this.hasContentTarget) return;
     this.contentTarget.hidden = true;
     this.contentTarget.setAttribute("data-state", "closed");
-    document.removeEventListener("keydown", this.#onDocumentKeydown);
   }
   /** Document-level `Escape` watcher (active only while shown). */
   #onDocumentKeydown = (event) => {

data/dist/index.js

@@ -2065,6 +2065,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();
@@ -4833,6 +4834,21 @@ var FormFieldController = class _FormFieldController extends Controller {
     return existing.split(/\s+/).filter((token) => token.length > 0 && !owned.has(token));
   }
 };
+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 = {
@@ -4847,6 +4863,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();
@@ -4958,16 +4980,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
@@ -5183,25 +5245,57 @@ var HighlightController = class extends Controller {
     return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
   }
 };
+
+// src/utils/scroll_dismiss.ts
+function observeScrollDismiss(element, onScroll) {
+  const targets = [...scrollParents(element), window];
+  const handler = () => onScroll();
+  for (const target of targets) {
+    target.addEventListener("scroll", handler, { passive: true });
+  }
+  return () => {
+    for (const target of targets) target.removeEventListener("scroll", handler);
+  };
+}
+function scrollParents(element) {
+  const parents = [];
+  let node = element.parentElement;
+  while (node) {
+    if (isScrollable(node)) parents.push(node);
+    node = node.parentElement;
+  }
+  return parents;
+}
+function isScrollable(element) {
+  const style = getComputedStyle(element);
+  return /auto|scroll|overlay/.test(style.overflow + style.overflowX + style.overflowY);
+}
+
+// src/controllers/hover_card_controller.ts
 var HoverCardController = class extends Controller {
   static targets = ["trigger", "card"];
   static values = {
     openDelay: { type: Number, default: 300 },
-    closeDelay: { type: Number, default: 200 }
+    closeDelay: { type: Number, default: 200 },
+    closeOnScroll: { type: Boolean, default: false }
   };
   static actions = ["close", "onKeydown", "open"];
   /** Pending open/close timers, torn down together on disconnect. */
   #timers = new SafeTimeout();
   #pendingOpen = null;
   #pendingClose = null;
+  /** Cleanup for the dismiss-on-scroll listeners while open, or `null`. */
+  #stopScrollDismiss = null;
   /** Starts closed. */
   connect() {
     this.#conceal();
   }
-  /** 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() {
     this.#timers.clearAll();
     document.removeEventListener("keydown", this.#onDocumentKeydown);
+    this.#stopScrollDismiss?.();
+    this.#stopScrollDismiss = null;
   }
   /** Opens the card, after `openDelay` ms (or immediately at 0). Cancels a pending close. */
   open() {
@@ -5238,21 +5332,26 @@ var HoverCardController = class extends Controller {
       this.#dismiss();
     }
   }
-  /** Reveals the card, reflects state, and starts watching for a dismissing `Escape`. */
+  /** Reveals the card, reflects state, and starts watching for a dismissing `Escape`/scroll. */
   #reveal() {
     if (!this.hasCardTarget) return;
     this.cardTarget.hidden = false;
     this.cardTarget.setAttribute("data-state", "open");
     if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "true");
     document.addEventListener("keydown", this.#onDocumentKeydown);
+    if (this.closeOnScrollValue && !this.#stopScrollDismiss) {
+      this.#stopScrollDismiss = observeScrollDismiss(this.element, () => this.#dismiss());
+    }
   }
-  /** Hides the card, reflects state, and stops watching for `Escape`. */
+  /** Hides the card, reflects state, and stops watching for `Escape`/scroll. */
   #conceal() {
+    document.removeEventListener("keydown", this.#onDocumentKeydown);
+    this.#stopScrollDismiss?.();
+    this.#stopScrollDismiss = null;
     if (!this.hasCardTarget) return;
     this.cardTarget.hidden = true;
     this.cardTarget.setAttribute("data-state", "closed");
     if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "false");
-    document.removeEventListener("keydown", this.#onDocumentKeydown);
   }
   /** Cancels pending timers and conceals immediately (shared Escape path). */
   #dismiss() {
@@ -6381,9 +6480,20 @@ var MeterController = class extends Controller {
   }
 };
 var MultiSelectController = class extends Controller {
-  static targets = ["input", "list", "option", "tags", "tag", "tagTemplate", "status"];
+  static targets = [
+    "input",
+    "list",
+    "option",
+    "tags",
+    "tag",
+    "tagTemplate",
+    "status",
+    "fields"
+  ];
   static values = {
-    max: { type: Number, default: 0 }
+    max: { type: Number, default: 0 },
+    name: { type: String, default: "options[]" },
+    form: { type: String, default: "" }
   };
   static actions = ["close", "filter", "onKeydown", "open", "toggleOption"];
   static events = ["change", "filter"];
@@ -6400,6 +6510,7 @@ var MultiSelectController = class extends Controller {
       for (const option of this.#selectedOptions) this.#appendTag(option);
       if (this.#removeButtons.length > 0) this.#roving.setActive(0);
     }
+    this.#syncFields();
     document.addEventListener("click", this.#onOutsideClick);
   }
   /** Tears down document and chip listeners on disconnect (Turbo included). */
@@ -6439,6 +6550,7 @@ var MultiSelectController = class extends Controller {
   }
   /** Routes input keyboard interaction per the multi-select combobox model. */
   onKeydown(event) {
+    if (event.isComposing || event.keyCode === 229) return;
     switch (event.key) {
       case "ArrowDown":
         event.preventDefault();
@@ -6533,6 +6645,7 @@ var MultiSelectController = class extends Controller {
     }
     this.#announce(this.#optionLabel(option));
     this.#refreshRoving();
+    this.#syncFields();
     this.dispatch("change", { detail: { values: this.#values } });
   }
   /** Builds one chip from the template for `option`. */
@@ -6566,6 +6679,7 @@ var MultiSelectController = class extends Controller {
     tag.remove();
     this.#announce(option ? this.#optionLabel(option) : value);
     this.#refreshRoving();
+    this.#syncFields();
     this.dispatch("change", { detail: { values: this.#values } });
     const remaining = this.#removeButtons;
     if (remaining.length === 0) {
@@ -6615,6 +6729,26 @@ var MultiSelectController = class extends Controller {
       this.inputTarget.removeAttribute("aria-activedescendant");
     }
   }
+  /**
+   * Mirrors the selected values into named hidden inputs under the `fields`
+   * target so the selection submits with a normal form (parity with tags-input).
+   * No-ops without a `fields` target, keeping the control back-compat. When the
+   * `form` value is set, each input gets a matching `form` attribute so the picker
+   * can submit with a `<form>` it lives outside of.
+   */
+  #syncFields() {
+    if (!this.hasFieldsTarget) return;
+    this.fieldsTarget.replaceChildren(
+      ...this.#values.map((value) => {
+        const input = document.createElement("input");
+        input.type = "hidden";
+        input.name = this.nameValue;
+        input.value = value;
+        if (this.hasFormValue && this.formValue !== "") input.setAttribute("form", this.formValue);
+        return input;
+      })
+    );
+  }
   /** Keeps exactly one chip remove button tabbable after the set changes. */
   #refreshRoving() {
     if (this.#removeButtons.length > 0 && this.#roving.activeIndex === -1)
@@ -8124,7 +8258,12 @@ var PersistController = class extends Controller {
 };
 var PopoverController = class _PopoverController extends Controller {
   static targets = ["trigger", "panel"];
+  static values = {
+    closeOnScroll: { type: Boolean, default: false }
+  };
   static actions = ["close", "open", "toggle"];
+  /** Cleanup for the dismiss-on-scroll listeners while open, or `null`. */
+  #stopScrollDismiss = null;
   /** Selector for natively focusable elements used to find the first one. */
   static #FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
   /** Starts closed and registers the document-level dismissal listeners. */
@@ -8143,6 +8282,8 @@ var PopoverController = class _PopoverController extends Controller {
     document.removeEventListener("click", this.#onOutsideClick);
     document.removeEventListener("keydown", this.#onKeydown);
     if (this.hasPanelTarget) this.panelTarget.removeEventListener("focusout", this.#onFocusOut);
+    this.#stopScrollDismiss?.();
+    this.#stopScrollDismiss = null;
   }
   /** Toggles the popover. Bound via `data-action` (click on the trigger). */
   toggle() {
@@ -8158,12 +8299,17 @@ var PopoverController = class _PopoverController extends Controller {
     this.panelTarget.hidden = false;
     if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "true");
     this.panelTarget.addEventListener("focusout", this.#onFocusOut);
+    if (this.closeOnScrollValue && !this.#stopScrollDismiss) {
+      this.#stopScrollDismiss = observeScrollDismiss(this.element, () => this.close());
+    }
     this.#focusFirst();
   }
   /** Closes the panel and reflects the collapsed state. Bound via `data-action`. */
   close() {
     if (!this.hasPanelTarget) return;
     this.panelTarget.removeEventListener("focusout", this.#onFocusOut);
+    this.#stopScrollDismiss?.();
+    this.#stopScrollDismiss = null;
     this.panelTarget.hidden = true;
     if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "false");
   }
@@ -10489,19 +10635,28 @@ var SubmitOnceController = class extends Controller {
   #timeoutId = null;
   #busy = false;
   #submitter = null;
+  #onSubmitStart = (event) => {
+    this.start(event);
+  };
   #onSubmitEnd = (event) => {
     const success = event.detail?.success;
     this.#restore(success);
   };
   connect() {
+    this.element.addEventListener("turbo:submit-start", this.#onSubmitStart);
     this.element.addEventListener("turbo:submit-end", this.#onSubmitEnd);
     this.#clearStaleBusy();
   }
   disconnect() {
+    this.element.removeEventListener("turbo:submit-start", this.#onSubmitStart);
     this.element.removeEventListener("turbo:submit-end", this.#onSubmitEnd);
     this.#clearTimeout();
   }
-  /** Enters the busy state for the submission started by `event`. */
+  /**
+   * Enters the busy state for the submission started by `event`. Accepts both a
+   * native `SubmitEvent` (manual `submit->#start` on non-Turbo forms) and Turbo's
+   * `turbo:submit-start` CustomEvent (auto-subscribed in `connect`).
+   */
   start(event) {
     if (this.#busy) return;
     this.#busy = true;
@@ -10575,12 +10730,24 @@ var SubmitOnceController = class extends Controller {
   }
   /** The triggering button: the event's submitter when ours, else the first button. */
   #resolveSubmitter(event, buttons) {
-    const submitter = event.submitter;
+    const submitter = this.#eventSubmitter(event);
     if (submitter && this.#isSubmitButton(submitter) && buttons.includes(submitter)) {
       return submitter;
     }
     return buttons[0] ?? null;
   }
+  /**
+   * Reads the submitter from a native `SubmitEvent` (`event.submitter`) or from
+   * Turbo's `turbo:submit-start` detail (`detail.formSubmission.submitter`), so
+   * the busy label swaps onto the right button under either path.
+   */
+  #eventSubmitter(event) {
+    if (typeof SubmitEvent !== "undefined" && event instanceof SubmitEvent) {
+      return event.submitter;
+    }
+    const detail = event.detail;
+    return detail?.formSubmission?.submitter ?? null;
+  }
   /** The controlled buttons: `submit` targets, or the form's native submit controls. */
   get #buttons() {
     if (this.hasSubmitTarget) return this.submitTargets;
@@ -10740,6 +10907,7 @@ var TagsInputController = class extends Controller {
   }
   /** Commits on `Enter`/delimiter and deletes the last tag on empty `Backspace`. */
   onKeydown(event) {
+    if (event.isComposing || event.keyCode === 229) return;
     if (event.key === "Enter" || event.key === this.delimiterValue) {
       event.preventDefault();
       this.#commitInput();
@@ -11706,7 +11874,8 @@ var TooltipController = class extends Controller {
   static targets = ["trigger", "content"];
   static values = {
     showDelay: { type: Number, default: 0 },
-    hideDelay: { type: Number, default: 0 }
+    hideDelay: { type: Number, default: 0 },
+    closeOnScroll: { type: Boolean, default: false }
   };
   static actions = ["hide", "onKeydown", "show"];
   /** Pending show/hide timers, torn down together on disconnect. */
@@ -11714,14 +11883,18 @@ var TooltipController = class extends Controller {
   /** The id of the currently pending show or hide timer, if any. */
   #pendingShow = null;
   #pendingHide = null;
+  /** Cleanup for the dismiss-on-scroll listeners while shown, or `null`. */
+  #stopScrollDismiss = null;
   /** Starts hidden. */
   connect() {
     this.#conceal();
   }
-  /** 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() {
     this.#timers.clearAll();
     document.removeEventListener("keydown", this.#onDocumentKeydown);
+    this.#stopScrollDismiss?.();
+    this.#stopScrollDismiss = null;
   }
   /** Shows the tooltip, after `showDelay` ms (or immediately at 0). Cancels a pending hide. */
   show() {
@@ -11763,19 +11936,28 @@ var TooltipController = class extends Controller {
       this.#conceal();
     }
   }
-  /** Reveals the content and starts watching for a dismissing `Escape`. */
+  /** Reveals the content and starts watching for a dismissing `Escape`/scroll. */
   #reveal() {
     if (!this.hasContentTarget) return;
     this.contentTarget.hidden = false;
     this.contentTarget.setAttribute("data-state", "open");
     document.addEventListener("keydown", this.#onDocumentKeydown);
+    if (this.closeOnScrollValue && !this.#stopScrollDismiss) {
+      this.#stopScrollDismiss = observeScrollDismiss(this.element, () => {
+        this.#cancelShow();
+        this.#cancelHide();
+        this.#conceal();
+      });
+    }
   }
-  /** Hides the content and stops watching for `Escape`. */
+  /** Hides the content and stops watching for `Escape`/scroll. */
   #conceal() {
+    document.removeEventListener("keydown", this.#onDocumentKeydown);
+    this.#stopScrollDismiss?.();
+    this.#stopScrollDismiss = null;
     if (!this.hasContentTarget) return;
     this.contentTarget.hidden = true;
     this.contentTarget.setAttribute("data-state", "closed");
-    document.removeEventListener("keydown", this.#onDocumentKeydown);
   }
   /** Document-level `Escape` watcher (active only while shown). */
   #onDocumentKeydown = (event) => {

data/lib/stimeo/ui/version.rb

@@ -2,9 +2,9 @@
 
 module Stimeo
   module UI
-    # Kept in lockstep with package.json: npm `0.1.0-alpha.1` ⇔ gem
-    # `0.1.0.pre.alpha.1` (RubyGems forbids dashes). Bump both together —
+    # Kept in lockstep with package.json: npm `0.1.0-beta.1` ⇔ gem
+    # `0.1.0.pre.beta.1` (RubyGems forbids dashes). Bump both together —
     # see RELEASING.md for the synchronized release procedure.
-    VERSION = "0.1.0.pre.alpha.1"
+    VERSION = "0.1.0.pre.beta.1"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stimeo-ui
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.alpha.1
+  version: 0.1.0.pre.beta.1
 platform: ruby
 authors:
 - Stimeo Labs
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-20 00:00:00.000000000 Z
+date: 2026-06-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -39,6 +39,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - dist/controllers/accordion_controller.js
@@ -122,13 +123,14 @@ files:
 - lib/stimeo-ui.rb
 - lib/stimeo/ui.rb
 - lib/stimeo/ui/version.rb
-homepage: https://github.com/taiyaky/stimeo-ui
+homepage: https://stimeo-labs.com
 licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/taiyaky/stimeo-ui
   bug_tracker_uri: https://github.com/taiyaky/stimeo-ui/issues
   changelog_uri: https://github.com/taiyaky/stimeo-ui/releases
+  documentation_uri: https://stimeo-labs.com/components
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []