stimeo-ui 0.1.0.pre.alpha.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 34dbcfca1f64a125bc86e2d946b7c2c62753f02e67c7444b4b25823f9ed3f3a3
+  data.tar.gz: fb0661197fe81c6559960f2b74d0dfffd5d126f3b285edda5123bf2fe37db6e3
+SHA512:
+  metadata.gz: 6f1578a41271afa0633a19c627200e4abe957ce7b6fb7e2d9013db876d75fd84140af7e3b98a8c0e37ffa931c159f9c952b444105b099882cc61bbfde220085b
+  data.tar.gz: 2037a7c5dfb426bdc8f19bc6d14e689d488695eb545b59b58572bfbccd8db9d6dd6d9102d129a79d6baef3371ca1bd2301a0a6d353877584601689460c03e2e4

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stimeo Labs (taiyaky)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,72 @@
+# Stimeo UI
+
+**Headless Stimulus UI framework for Ruby on Rails.** Stimeo UI ships *behavior*
+— ARIA state, keyboard interaction, focus management, Turbo resilience — as
+`data-*`-driven Stimulus controllers. It does **not** ship CSS: the consuming app
+owns the look entirely.
+
+- Lean by design: the **core** needs only `@hotwired/stimulus` at runtime (kept
+  external in the build). The opt-in `stimeo-ui/positioning` module is the one
+  exception — it uses `@floating-ui/dom` (an optional **peer dependency**; see the
+  Peer dependencies note below).
+- Accessibility first: every controller follows the relevant WAI-ARIA APG pattern
+  and the related WCAG 2.2 AA criteria.
+- Public controller identifiers use the `stimeo--` namespace (e.g.
+  `stimeo--dropdown`).
+
+> Status: **alpha** (`0.x`). The `stimeo--*` attribute API may still change before
+> 1.0 — pin your version.
+
+## Install
+
+### Rails with importmap (recommended)
+
+```bash
+bundle add stimeo-ui
+bin/rails generate stimeo:install
+```
+
+The generator vendors the prebuilt JS into `vendor/javascript/stimeo/`, pins
+`stimeo-ui` in `config/importmap.rb`, and registers all controllers with your
+Stimulus application. Then drive components from HTML alone:
+
+```erb
+<div data-controller="stimeo--dropdown">
+  <button data-stimeo--dropdown-target="trigger"
+          data-action="click->stimeo--dropdown#toggle">Menu</button>
+  <div data-stimeo--dropdown-target="menu" hidden>…</div>
+</div>
+```
+
+### npm (jsbundling or any bundler)
+
+```bash
+npm install stimeo-ui @hotwired/stimulus
+```
+
+```js
+import { Application } from "@hotwired/stimulus";
+import { registerStimeo } from "stimeo-ui";
+
+const application = Application.start();
+registerStimeo(application); // registers every stimeo--* controller
+```
+
+Need only a few controllers? Import them individually from
+`stimeo-ui/controllers/*` and register them under your own identifiers.
+
+- **Peer dependencies:** `@hotwired/stimulus` (always), `@floating-ui/dom` (only
+  if you use the opt-in `stimeo-ui/positioning` module — tooltips, popovers, etc.
+  work without it via the default flow layout).
+- **No CSS is shipped.** Style the components yourself; controllers only toggle
+  ARIA state and `data-*` hooks.
+
+## Contributing
+
+Bug reports and feature requests are very welcome — please open a GitHub issue.
+For code changes, open an issue first to discuss direction; see
+[`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## License
+
+Released under the [MIT License](LICENSE) © Stimeo Labs.

data/dist/controllers/accordion_controller.js

@@ -0,0 +1,76 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/accordion_controller.ts
+var AccordionController = class extends Controller {
+  static targets = ["trigger", "panel"];
+  static actions = ["collapseAll", "expandAll", "onKeydown", "toggle"];
+  /** Toggles the panel controlled by the activated header. */
+  toggle(event) {
+    const trigger = event.currentTarget;
+    const panel = this.#panelFor(trigger);
+    if (!panel) return;
+    this.#setExpanded(trigger, panel, trigger.getAttribute("aria-expanded") !== "true");
+  }
+  /** Opens every panel. Bound via `data-action` on an "expand all" control. */
+  expandAll() {
+    this.#setAll(true);
+  }
+  /** Closes every panel. Bound via `data-action` on a "collapse all" control. */
+  collapseAll() {
+    this.#setAll(false);
+  }
+  /** Drives every header/panel pair to the same expanded state. */
+  #setAll(open) {
+    for (const trigger of this.triggerTargets) {
+      const panel = this.#panelFor(trigger);
+      if (panel) this.#setExpanded(trigger, panel, open);
+    }
+  }
+  /** Reflects one header/panel pair's state through `aria-expanded` + `hidden`. */
+  #setExpanded(trigger, panel, open) {
+    trigger.setAttribute("aria-expanded", open ? "true" : "false");
+    panel.hidden = !open;
+  }
+  /**
+   * Moves focus between headers per the APG keyboard model, skipping any header
+   * that is hidden or nested in a hidden subtree. A consumer may hide whole
+   * sections (e.g. an `stimeo--filter` that collapses empty groups), and an
+   * unperceivable header must never become an arrow-key target — otherwise
+   * `.focus()` lands on nothing and navigation appears to stall.
+   */
+  onKeydown(event) {
+    const current = event.currentTarget;
+    if (this.triggerTargets.indexOf(current) === -1) return;
+    const navigable = this.triggerTargets.filter((trigger) => trigger.closest("[hidden]") === null);
+    const here = navigable.indexOf(current);
+    if (here === -1) return;
+    let next;
+    switch (event.key) {
+      case "ArrowDown":
+        next = navigable[(here + 1) % navigable.length];
+        break;
+      case "ArrowUp":
+        next = navigable[(here - 1 + navigable.length) % navigable.length];
+        break;
+      case "Home":
+        next = navigable[0];
+        break;
+      case "End":
+        next = navigable[navigable.length - 1];
+        break;
+      default:
+        return;
+    }
+    event.preventDefault();
+    next?.focus();
+  }
+  /** Resolves the panel a header controls via its `aria-controls` reference. */
+  #panelFor(trigger) {
+    const id = trigger.getAttribute("aria-controls");
+    return id ? this.panelTargets.find((panel) => panel.id === id) ?? null : null;
+  }
+};
+
+export { AccordionController };
+//# sourceMappingURL=accordion_controller.js.map
+//# sourceMappingURL=accordion_controller.js.map

data/dist/controllers/announcer_controller.js

@@ -0,0 +1,184 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/announcer_controller.ts
+
+// src/utils/safe_timeout.ts
+var TimerRegistry = class {
+  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
+  ids = /* @__PURE__ */ new Set();
+  /**
+   * Cancels a single tracked timer.
+   *
+   * No-ops if the id is unknown (already cleared, fired, or never owned by this
+   * registry), so callers can clear defensively without guarding.
+   */
+  clear(id) {
+    if (this.ids.delete(id)) {
+      this.cancel(id);
+    }
+  }
+  /**
+   * Cancels every tracked timer. Call this from a controller's `disconnect()`
+   * to guarantee no timer outlives the element.
+   */
+  clearAll() {
+    for (const id of this.ids) {
+      this.cancel(id);
+    }
+    this.ids.clear();
+  }
+  /** Number of timers currently tracked (pending). */
+  get size() {
+    return this.ids.size;
+  }
+};
+var SafeTimeout = class extends TimerRegistry {
+  /**
+   * Schedules `callback` after `delay` ms and returns the timer id.
+   *
+   * The id is removed from the registry automatically when the timeout fires,
+   * so {@link TimerRegistry.size | size} reflects only still-pending timers.
+   */
+  set(callback, delay) {
+    const id = this.schedule(() => {
+      this.ids.delete(id);
+      callback();
+    }, delay);
+    this.ids.add(id);
+    return id;
+  }
+  schedule(callback, delay) {
+    return window.setTimeout(callback, delay);
+  }
+  cancel(id) {
+    window.clearTimeout(id);
+  }
+};
+
+// src/controllers/announcer_controller.ts
+var AnnouncerController = class extends Controller {
+  static targets = ["polite", "assertive"];
+  static values = {
+    clearAfter: { type: Number, default: 1e3 },
+    dedupeReannounce: { type: Boolean, default: true }
+  };
+  static actions = ["announce"];
+  /** Clear/re-announce timers; one `clearAll()` in disconnect tears them all down. */
+  #timers = new SafeTimeout();
+  /** Live regions generated to stand in for absent targets, for teardown. */
+  #generated = /* @__PURE__ */ new Map();
+  /**
+   * Guards against handling the same CustomEvent twice. An event dispatched on
+   * the controller element with `bubbles: true` reaches both the element and the
+   * `window` listener; this WeakSet ensures it announces only once.
+   */
+  #handled = /* @__PURE__ */ new WeakSet();
+  /** Receives programmatic announcements at the element or bubbled to `window`. */
+  #onAnnounceEvent = (event) => {
+    if (this.#handled.has(event)) return;
+    this.#handled.add(event);
+    const detail = event.detail;
+    const message = this.#messageFromDetail(detail);
+    if (!message) return;
+    this.#announce(message, this.#assertiveFromDetail(detail));
+  };
+  connect() {
+    this.element.addEventListener("stimeo--announcer:announce", this.#onAnnounceEvent);
+    window.addEventListener("stimeo--announcer:announce", this.#onAnnounceEvent);
+  }
+  disconnect() {
+    this.element.removeEventListener("stimeo--announcer:announce", this.#onAnnounceEvent);
+    window.removeEventListener("stimeo--announcer:announce", this.#onAnnounceEvent);
+    this.#timers.clearAll();
+    for (const region of this.#generated.values()) {
+      region.remove();
+    }
+    this.#generated.clear();
+  }
+  /**
+   * Announces a message. Reads the text from a Stimulus action param
+   * (`message`, plus optional `assertive`) for attribute-only triggers, falling
+   * back to a CustomEvent `detail` when the same handler is wired to an event.
+   * An empty/non-string message is ignored so untrusted payloads cannot blank
+   * the region.
+   */
+  announce(event) {
+    const params = event.params;
+    const fromParam = params?.message;
+    const message = typeof fromParam === "string" && fromParam.length > 0 ? fromParam : this.#messageFromDetail(event.detail);
+    if (!message) return;
+    const assertive = params?.assertive === true || this.#assertiveFromDetail(event.detail);
+    this.#announce(message, assertive);
+  }
+  /**
+   * Writes `message` into the matching live region and schedules its clear.
+   *
+   * When the region already holds the same text, an aria-atomic region is not
+   * re-read by assistive tech (the node did not change). If `dedupeReannounce`
+   * is on, the text is cleared and re-set on a later task so the mutation is
+   * observed and announced again.
+   */
+  #announce(message, assertive) {
+    const region = this.#regionFor(assertive ? "assertive" : "polite");
+    if (this.dedupeReannounceValue && region.textContent === message) {
+      region.textContent = "";
+      this.#timers.set(() => {
+        region.textContent = message;
+        this.#scheduleClear(region, message);
+      }, 0);
+      return;
+    }
+    region.textContent = message;
+    this.#scheduleClear(region, message);
+  }
+  /** Clears the region after `clearAfter` ms, unless a newer message replaced it. */
+  #scheduleClear(region, message) {
+    if (this.clearAfterValue <= 0) return;
+    this.#timers.set(() => {
+      if (region.textContent === message) region.textContent = "";
+    }, this.clearAfterValue);
+  }
+  /** Resolves the live region for a politeness level, generating it if absent. */
+  #regionFor(level) {
+    if (level === "assertive" && this.hasAssertiveTarget) return this.assertiveTarget;
+    if (level === "polite" && this.hasPoliteTarget) return this.politeTarget;
+    const existing = this.#generated.get(level);
+    if (existing) return existing;
+    const region = document.createElement("div");
+    region.setAttribute("aria-live", level);
+    region.setAttribute("aria-atomic", "true");
+    visuallyHide(region);
+    this.element.appendChild(region);
+    this.#generated.set(level, region);
+    return region;
+  }
+  /** Extracts a non-empty string `message` from a CustomEvent detail, else null. */
+  #messageFromDetail(detail) {
+    if (detail && typeof detail === "object" && "message" in detail) {
+      const value = detail.message;
+      if (typeof value === "string" && value.length > 0) return value;
+    }
+    return null;
+  }
+  /** Reads an `assertive === true` flag from a CustomEvent detail (default polite). */
+  #assertiveFromDetail(detail) {
+    return !!detail && typeof detail === "object" && detail.assertive === true;
+  }
+};
+function visuallyHide(node) {
+  const { style } = node;
+  style.position = "absolute";
+  style.width = "1px";
+  style.height = "1px";
+  style.margin = "-1px";
+  style.padding = "0";
+  style.border = "0";
+  style.overflow = "hidden";
+  style.clip = "rect(0 0 0 0)";
+  style.clipPath = "inset(50%)";
+  style.whiteSpace = "nowrap";
+}
+
+export { AnnouncerController, visuallyHide };
+//# sourceMappingURL=announcer_controller.js.map
+//# sourceMappingURL=announcer_controller.js.map

data/dist/controllers/aspect_ratio_controller.js

@@ -0,0 +1,36 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/aspect_ratio_controller.ts
+var AspectRatioController = class extends Controller {
+  static targets = ["content"];
+  static values = {
+    ratio: { type: String, default: "1/1" }
+  };
+  /** Applies the ratio on connect and whenever the value changes. */
+  ratioValueChanged() {
+    this.element.style.setProperty("--stimeo-aspect-ratio", this.#normalizeRatio(this.ratioValue));
+  }
+  /**
+   * Normalizes a ratio string to a valid CSS `<ratio>`:
+   * - `"16/9"` / `"16 / 9"` → `"16 / 9"` (both parts must be positive numbers)
+   * - `"1.5"` → `"1.5"` (a bare positive number)
+   * - anything else → `"1 / 1"` (the default), so the custom property is always valid.
+   */
+  #normalizeRatio(raw) {
+    const value = raw.trim();
+    if (value.includes("/")) {
+      const [w, h] = value.split("/").map((part) => Number.parseFloat(part.trim()));
+      if (this.#isPositive(w) && this.#isPositive(h)) return `${w} / ${h}`;
+      return "1 / 1";
+    }
+    const single = Number.parseFloat(value);
+    return this.#isPositive(single) ? String(single) : "1 / 1";
+  }
+  #isPositive(value) {
+    return value !== void 0 && Number.isFinite(value) && value > 0;
+  }
+};
+
+export { AspectRatioController };
+//# sourceMappingURL=aspect_ratio_controller.js.map
+//# sourceMappingURL=aspect_ratio_controller.js.map

data/dist/controllers/auto_submit_controller.js

@@ -0,0 +1,147 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/auto_submit_controller.ts
+
+// src/utils/safe_timeout.ts
+var TimerRegistry = class {
+  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
+  ids = /* @__PURE__ */ new Set();
+  /**
+   * Cancels a single tracked timer.
+   *
+   * No-ops if the id is unknown (already cleared, fired, or never owned by this
+   * registry), so callers can clear defensively without guarding.
+   */
+  clear(id) {
+    if (this.ids.delete(id)) {
+      this.cancel(id);
+    }
+  }
+  /**
+   * Cancels every tracked timer. Call this from a controller's `disconnect()`
+   * to guarantee no timer outlives the element.
+   */
+  clearAll() {
+    for (const id of this.ids) {
+      this.cancel(id);
+    }
+    this.ids.clear();
+  }
+  /** Number of timers currently tracked (pending). */
+  get size() {
+    return this.ids.size;
+  }
+};
+var SafeTimeout = class extends TimerRegistry {
+  /**
+   * Schedules `callback` after `delay` ms and returns the timer id.
+   *
+   * The id is removed from the registry automatically when the timeout fires,
+   * so {@link TimerRegistry.size | size} reflects only still-pending timers.
+   */
+  set(callback, delay) {
+    const id = this.schedule(() => {
+      this.ids.delete(id);
+      callback();
+    }, delay);
+    this.ids.add(id);
+    return id;
+  }
+  schedule(callback, delay) {
+    return window.setTimeout(callback, delay);
+  }
+  cancel(id) {
+    window.clearTimeout(id);
+  }
+};
+
+// src/controllers/auto_submit_controller.ts
+var AutoSubmitController = class extends Controller {
+  static targets = ["form"];
+  static values = {
+    debounce: { type: Number, default: 300 },
+    on: { type: String, default: "input change" },
+    announce: { type: Boolean, default: false },
+    message: { type: String, default: "" }
+  };
+  static actions = ["submit"];
+  static events = ["submit", "done"];
+  /** Debounce timer registry; one `clearAll()` in disconnect tears it down. */
+  #timers = new SafeTimeout();
+  /** Id of the pending debounce timer, so a new keystroke can reset it. */
+  #pendingId = 0;
+  /** Clears `aria-busy` and emits completion once Turbo finishes the submit. */
+  #onSubmitEnd = () => {
+    this.#form.removeAttribute("aria-busy");
+    const message = this.messageValue;
+    this.dispatch("done", { detail: { message: message || void 0 } });
+    if (this.announceValue && message) {
+      window.dispatchEvent(new CustomEvent("stimeo--announcer:announce", { detail: { message } }));
+    }
+  };
+  /** True while an IME composition is in progress on one of the form's fields. */
+  #composing = false;
+  /** Marks composition active so `input` events mid-conversion don't submit. */
+  #onCompositionStart = () => {
+    this.#composing = true;
+  };
+  /**
+   * Composition finished (the IME conversion is confirmed): clear the flag and
+   * schedule a submit as if `input` fired, so the settled text triggers a submit
+   * even on browsers whose post-composition `input` still reads `isComposing`.
+   */
+  #onCompositionEnd = (event) => {
+    this.#composing = false;
+    if (this.#triggers("input")) this.#schedule(event.target ?? null);
+  };
+  connect() {
+    this.#form.addEventListener("turbo:submit-end", this.#onSubmitEnd);
+    this.#form.addEventListener("compositionstart", this.#onCompositionStart);
+    this.#form.addEventListener("compositionend", this.#onCompositionEnd);
+  }
+  disconnect() {
+    this.#timers.clearAll();
+    this.#pendingId = 0;
+    this.#composing = false;
+    this.#form.removeAttribute("data-auto-submit-pending");
+    this.#form.removeEventListener("turbo:submit-end", this.#onSubmitEnd);
+    this.#form.removeEventListener("compositionstart", this.#onCompositionStart);
+    this.#form.removeEventListener("compositionend", this.#onCompositionEnd);
+  }
+  /**
+   * Schedules a debounced submit. Wired to `input`/`change`; the `on` value is an
+   * allowlist so a configured subset (e.g. only `change`) is honored even when both
+   * are bound in markup. Coalesces rapid events into a single `requestSubmit`.
+   */
+  submit(event) {
+    if (!this.#triggers(event.type)) return;
+    if (event.type === "input" && (this.#composing || event.isComposing)) return;
+    this.#schedule(event.target ?? null);
+  }
+  /** Schedules (and coalesces) the debounced submit for the given trigger. */
+  #schedule(trigger) {
+    this.#form.setAttribute("data-auto-submit-pending", "true");
+    if (this.#pendingId) this.#timers.clear(this.#pendingId);
+    this.#pendingId = this.#timers.set(() => {
+      this.#pendingId = 0;
+      this.#form.removeAttribute("data-auto-submit-pending");
+      this.dispatch("submit", { detail: { trigger } });
+      if (this.#form.checkValidity()) {
+        this.#form.setAttribute("aria-busy", "true");
+      }
+      this.#form.requestSubmit();
+    }, this.debounceValue);
+  }
+  /** Resolves the form element (explicit `form` target, else the controller root). */
+  get #form() {
+    return this.hasFormTarget ? this.formTarget : this.element;
+  }
+  /** Whether `type` is one of the whitespace-separated event types in `on`. */
+  #triggers(type) {
+    return this.onValue.split(/\s+/).filter(Boolean).includes(type);
+  }
+};
+
+export { AutoSubmitController };
+//# sourceMappingURL=auto_submit_controller.js.map
+//# sourceMappingURL=auto_submit_controller.js.map

data/dist/controllers/avatar_controller.js

@@ -0,0 +1,66 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/avatar_controller.ts
+var AvatarController = class extends Controller {
+  static targets = ["image", "fallback"];
+  static values = {
+    src: { type: String, default: "" }
+  };
+  static actions = ["onError", "onLoad"];
+  static events = ["error"];
+  connect() {
+    if (!this.hasImageTarget) {
+      this.#showFallback();
+      return;
+    }
+    if (this.srcValue) {
+      this.imageTarget.src = this.srcValue;
+    }
+    const src = this.imageTarget.getAttribute("src");
+    if (!src) {
+      this.#showFallback();
+      return;
+    }
+    if (this.imageTarget.complete && this.imageTarget.naturalWidth > 0) {
+      this.#showImage();
+      return;
+    }
+    if (this.imageTarget.complete && this.imageTarget.naturalWidth === 0 && src) {
+      this.onError();
+      return;
+    }
+    this.#enterLoading();
+  }
+  /** Reveals the image once it has loaded successfully. */
+  onLoad() {
+    this.#showImage();
+  }
+  /** Swaps to the fallback when the image fails and emits `error`. */
+  onError() {
+    const src = this.hasImageTarget ? this.imageTarget.getAttribute("src") ?? "" : "";
+    this.#showFallback();
+    this.dispatch("error", { detail: { src } });
+  }
+  /** Loading phase: keep the image visible (per markup) while it fetches. */
+  #enterLoading() {
+    if (this.hasImageTarget) this.imageTarget.hidden = false;
+    if (this.hasFallbackTarget) this.fallbackTarget.hidden = true;
+    this.element.setAttribute("data-state", "loading");
+  }
+  /** Loaded phase: image visible, fallback hidden. */
+  #showImage() {
+    if (this.hasImageTarget) this.imageTarget.hidden = false;
+    if (this.hasFallbackTarget) this.fallbackTarget.hidden = true;
+    this.element.setAttribute("data-state", "loaded");
+  }
+  /** Error / no-src phase: fallback visible, image hidden. */
+  #showFallback() {
+    if (this.hasImageTarget) this.imageTarget.hidden = true;
+    if (this.hasFallbackTarget) this.fallbackTarget.hidden = false;
+    this.element.setAttribute("data-state", "error");
+  }
+};
+
+export { AvatarController };
+//# sourceMappingURL=avatar_controller.js.map
+//# sourceMappingURL=avatar_controller.js.map