stimeo-ui 0.1.0-alpha.1

package/dist/controllers/radio_group_controller.js

@@ -0,0 +1,128 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/radio_group_controller.ts
+
+// src/utils/roving_tabindex.ts
+var RovingTabindex = class {
+  /** Returns the current ordered item elements; called on every operation. */
+  #getItems;
+  /**
+   * @param getItems - Returns the current ordered item elements. Called on every
+   *   operation so the live target list is always used.
+   */
+  constructor(getItems) {
+    this.#getItems = getItems;
+  }
+  /** Index of the currently tabbable item (`tabindex="0"`), or `-1` if none. */
+  get activeIndex() {
+    return this.#getItems().findIndex((item) => item.tabIndex === 0);
+  }
+  /**
+   * Makes exactly the item at `index` tabbable (`tabindex="0"`) and removes every
+   * other item from the Tab sequence (`tabindex="-1"`). An out-of-range `index`
+   * (e.g. `-1`) leaves all items at `-1`, which a controller can use to express
+   * "nothing is currently tabbable".
+   *
+   * @param index - Position of the item to make tabbable.
+   * @param options - Pass `{ focus: true }` to also move DOM focus to that item.
+   */
+  setActive(index, { focus = false } = {}) {
+    const items = this.#getItems();
+    items.forEach((item, i) => {
+      item.tabIndex = i === index ? 0 : -1;
+    });
+    if (focus) items[index]?.focus();
+  }
+};
+function rovingMove(current, length, delta, wrap) {
+  if (length === 0) return -1;
+  const next = current + delta;
+  return (next + length) % length;
+}
+
+// src/controllers/radio_group_controller.ts
+var RadioGroupController = class extends Controller {
+  static targets = ["radio", "field"];
+  static actions = ["onKeydown", "select"];
+  static events = ["change"];
+  #roving = new RovingTabindex(() => this.radioTargets);
+  /** Establishes the roving entry point and reflects the initial selection. */
+  connect() {
+    const selected = this.#selectedIndex();
+    this.#roving.setActive(selected === -1 ? 0 : selected);
+    if (selected !== -1) this.#reflectField(this.radioTargets[selected], { silent: true });
+  }
+  /** Selects the clicked radio. Bound via `data-action` (click). */
+  select(event) {
+    const index = this.radioTargets.indexOf(event.currentTarget);
+    if (index !== -1) this.#selectIndex(index, { focus: false });
+  }
+  /** Arrow/Home/End/Space navigation with selection-follows-focus. */
+  onKeydown(event) {
+    const current = this.radioTargets.indexOf(event.currentTarget);
+    if (current === -1) return;
+    let next = null;
+    switch (event.key) {
+      case "ArrowDown":
+      case "ArrowRight":
+        next = rovingMove(current, this.radioTargets.length, 1);
+        break;
+      case "ArrowUp":
+      case "ArrowLeft":
+        next = rovingMove(current, this.radioTargets.length, -1);
+        break;
+      case "Home":
+        next = 0;
+        break;
+      case "End":
+        next = this.radioTargets.length - 1;
+        break;
+      case " ":
+        next = current;
+        break;
+      default:
+        return;
+    }
+    event.preventDefault();
+    this.#selectIndex(next, { focus: true });
+  }
+  /**
+   * Checks the radio at `index`, clears the rest, updates the roving Tab stop and
+   * the hidden field, and dispatches `change`.
+   */
+  #selectIndex(index, { focus }) {
+    const radio = this.radioTargets[index];
+    if (!radio) return;
+    this.radioTargets.forEach((item, i) => {
+      item.setAttribute("aria-checked", i === index ? "true" : "false");
+    });
+    this.#roving.setActive(index, { focus });
+    this.#reflectField(radio);
+    this.dispatch("change", { detail: { value: this.#radioValue(radio), radio } });
+  }
+  /** Index of the currently checked radio, or `-1` if none. */
+  #selectedIndex() {
+    return this.radioTargets.findIndex((radio) => radio.getAttribute("aria-checked") === "true");
+  }
+  /**
+   * Mirrors a radio's `data-value` onto the hidden field, when present. Fires a
+   * native bubbling `change` on a real value change (matching `listbox`, so
+   * `auto-submit` and other native-`change` consumers react) — unless `silent`
+   * (the initial connect reflection, which is not a user edit).
+   */
+  #reflectField(radio, { silent = false } = {}) {
+    if (!this.hasFieldTarget || !radio) return;
+    const value = this.#radioValue(radio);
+    if (this.fieldTarget.value === value) return;
+    this.fieldTarget.value = value;
+    if (!silent) this.fieldTarget.dispatchEvent(new Event("change", { bubbles: true }));
+  }
+  /** A radio's submitted value (`data-value`, defaulting to empty). */
+  #radioValue(radio) {
+    return radio.getAttribute("data-value") ?? "";
+  }
+};
+
+export { RadioGroupController };
+//# sourceMappingURL=radio_group_controller.js.map
+//# sourceMappingURL=radio_group_controller.js.map

package/dist/controllers/radio_group_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/roving_tabindex.ts","../../src/controllers/radio_group_controller.ts"],"names":[],"mappings":"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","file":"radio_group_controller.js","sourcesContent":["/**\n * Low-level roving-tabindex primitive shared by composite-widget controllers.\n *\n * The APG roving-tabindex pattern keeps a composite widget a single Tab stop:\n * exactly one item is in the Tab sequence (`tabindex=\"0\"`) while the rest are\n * removed from it (`tabindex=\"-1\"`), and the arrow keys move both DOM focus and\n * that single tabbable position together. {@link RovingTabindex} owns *only* that\n * mechanical bookkeeping — \"which one item is tabbable, and move focus there\".\n *\n * It is intentionally **policy-free**. Orientation, wrapping vs. clamping,\n * selection-follows-focus, typeahead, and `Home`/`End` semantics differ per APG\n * pattern (Radio Group, Toolbar, Rating, …); folding them into one helper would\n * flatten those widgets to a lowest common denominator and lose each pattern's\n * correctness. Those decisions therefore stay in each controller, which calls\n * {@link RovingTabindex.setActive} with an index it computed itself (optionally\n * via the pure {@link rovingMove} helper).\n *\n * @remarks\n * Items are read lazily through a getter so a controller can add or remove\n * targets (Stimulus re-scans the DOM) without re-wiring this helper.\n */\nexport class RovingTabindex {\n  /** Returns the current ordered item elements; called on every operation. */\n  readonly #getItems: () => HTMLElement[];\n\n  /**\n   * @param getItems - Returns the current ordered item elements. Called on every\n   *   operation so the live target list is always used.\n   */\n  constructor(getItems: () => HTMLElement[]) {\n    this.#getItems = getItems;\n  }\n\n  /** Index of the currently tabbable item (`tabindex=\"0\"`), or `-1` if none. */\n  get activeIndex(): number {\n    return this.#getItems().findIndex((item) => item.tabIndex === 0);\n  }\n\n  /**\n   * Makes exactly the item at `index` tabbable (`tabindex=\"0\"`) and removes every\n   * other item from the Tab sequence (`tabindex=\"-1\"`). An out-of-range `index`\n   * (e.g. `-1`) leaves all items at `-1`, which a controller can use to express\n   * \"nothing is currently tabbable\".\n   *\n   * @param index - Position of the item to make tabbable.\n   * @param options - Pass `{ focus: true }` to also move DOM focus to that item.\n   */\n  setActive(index: number, { focus = false }: { focus?: boolean } = {}): void {\n    const items = this.#getItems();\n    items.forEach((item, i) => {\n      item.tabIndex = i === index ? 0 : -1;\n    });\n    if (focus) items[index]?.focus();\n  }\n}\n\n/** Edge behavior for {@link rovingMove}: cycle past the ends, or stop at them. */\nexport type RovingWrap = \"wrap\" | \"clamp\";\n\n/**\n * Pure helper that resolves the target index for a one-step directional move.\n *\n * Keyboard/orientation mapping stays in the caller: it decides that a key means\n * `delta` `+1` (next) or `-1` (previous) and whether the widget should `\"wrap\"`\n * (Radio Group, Toolbar) or `\"clamp\"` at the ends.\n *\n * @param current - The index focus is moving from.\n * @param length - Number of items in the set.\n * @param delta - `+1` to move to the next item, `-1` for the previous.\n * @param wrap - `\"wrap\"` cycles around the ends; `\"clamp\"` stops at them.\n * @returns The resolved index, or `-1` when there are no items.\n */\nexport function rovingMove(\n  current: number,\n  length: number,\n  delta: number,\n  wrap: RovingWrap,\n): number {\n  if (length === 0) return -1;\n  const next = current + delta;\n  if (wrap === \"wrap\") return (next + length) % length;\n  return Math.min(length - 1, Math.max(0, next));\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { RovingTabindex, rovingMove } from \"../utils/roving_tabindex\";\n\n/**\n * Headless, accessible radio-group behavior for **custom** (non-native) radios.\n *\n * Markup contract (identifier: `stimeo--radio-group`):\n *   <div data-controller=\"stimeo--radio-group\" role=\"radiogroup\" aria-label=\"Plan\">\n *     <div role=\"radio\" aria-checked=\"true\" tabindex=\"0\" data-value=\"basic\"\n *          data-stimeo--radio-group-target=\"radio\"\n *          data-action=\"click->stimeo--radio-group#select\n *                       keydown->stimeo--radio-group#onKeydown\">Basic</div>\n *     <!-- more radios; exactly one tabindex=0 -->\n *     <input type=\"hidden\" data-stimeo--radio-group-target=\"field\" />\n *   </div>\n *\n * Implements the WAI-ARIA APG **Radio Group** pattern. Use this only for custom\n * radios (e.g. button-styled cards); native `<input type=\"radio\">` already does\n * this and should be preferred when its look suffices.\n *\n * @remarks\n * Behavior only — selection is exposed through `aria-checked`, the single Tab\n * stop through roving `tabindex` ({@link RovingTabindex}); the consumer styles\n * off `[role=\"radio\"][aria-checked=\"true\"]`. Per APG, **selection follows\n * focus**: arrow keys move focus and select in one step.\n *\n * Behavior provided:\n * - Click selects a radio.\n * - `ArrowDown`/`ArrowRight` select the next, `ArrowUp`/`ArrowLeft` the previous\n *   (wrapping); `Home`/`End` the first/last; `Space` selects the focused radio.\n * - The selected radio's `data-value` is mirrored to the optional hidden `field`,\n *   and `stimeo--radio-group:change` is dispatched on every change.\n */\nexport class RadioGroupController extends Controller<HTMLElement> {\n  static override targets = [\"radio\", \"field\"];\n  static actions = [\"onKeydown\", \"select\"] as const;\n  static events = [\"change\"] as const;\n\n  declare readonly radioTargets: HTMLElement[];\n  declare readonly fieldTarget: HTMLInputElement;\n  declare readonly hasFieldTarget: boolean;\n\n  readonly #roving = new RovingTabindex(() => this.radioTargets);\n\n  /** Establishes the roving entry point and reflects the initial selection. */\n  override connect(): void {\n    const selected = this.#selectedIndex();\n    // With no selection, the first radio is the (unchecked) Tab entry point.\n    this.#roving.setActive(selected === -1 ? 0 : selected);\n    // Reflect the server-rendered selection without firing a native `change`:\n    // connect is not a user edit, and the field already carries this value.\n    if (selected !== -1) this.#reflectField(this.radioTargets[selected], { silent: true });\n  }\n\n  /** Selects the clicked radio. Bound via `data-action` (click). */\n  select(event: Event): void {\n    const index = this.radioTargets.indexOf(event.currentTarget as HTMLElement);\n    if (index !== -1) this.#selectIndex(index, { focus: false });\n  }\n\n  /** Arrow/Home/End/Space navigation with selection-follows-focus. */\n  onKeydown(event: KeyboardEvent): void {\n    const current = this.radioTargets.indexOf(event.currentTarget as HTMLElement);\n    if (current === -1) return;\n\n    let next: number | null = null;\n    switch (event.key) {\n      case \"ArrowDown\":\n      case \"ArrowRight\":\n        next = rovingMove(current, this.radioTargets.length, 1, \"wrap\");\n        break;\n      case \"ArrowUp\":\n      case \"ArrowLeft\":\n        next = rovingMove(current, this.radioTargets.length, -1, \"wrap\");\n        break;\n      case \"Home\":\n        next = 0;\n        break;\n      case \"End\":\n        next = this.radioTargets.length - 1;\n        break;\n      case \" \":\n        next = current;\n        break;\n      default:\n        return;\n    }\n\n    event.preventDefault();\n    this.#selectIndex(next, { focus: true });\n  }\n\n  /**\n   * Checks the radio at `index`, clears the rest, updates the roving Tab stop and\n   * the hidden field, and dispatches `change`.\n   */\n  #selectIndex(index: number, { focus }: { focus: boolean }): void {\n    const radio = this.radioTargets[index];\n    if (!radio) return;\n    this.radioTargets.forEach((item, i) => {\n      item.setAttribute(\"aria-checked\", i === index ? \"true\" : \"false\");\n    });\n    this.#roving.setActive(index, { focus });\n    this.#reflectField(radio);\n    this.dispatch(\"change\", { detail: { value: this.#radioValue(radio), radio } });\n  }\n\n  /** Index of the currently checked radio, or `-1` if none. */\n  #selectedIndex(): number {\n    return this.radioTargets.findIndex((radio) => radio.getAttribute(\"aria-checked\") === \"true\");\n  }\n\n  /**\n   * Mirrors a radio's `data-value` onto the hidden field, when present. Fires a\n   * native bubbling `change` on a real value change (matching `listbox`, so\n   * `auto-submit` and other native-`change` consumers react) — unless `silent`\n   * (the initial connect reflection, which is not a user edit).\n   */\n  #reflectField(\n    radio: HTMLElement | undefined,\n    { silent = false }: { silent?: boolean } = {},\n  ): void {\n    if (!this.hasFieldTarget || !radio) return;\n    const value = this.#radioValue(radio);\n    if (this.fieldTarget.value === value) return;\n    this.fieldTarget.value = value;\n    if (!silent) this.fieldTarget.dispatchEvent(new Event(\"change\", { bubbles: true }));\n  }\n\n  /** A radio's submitted value (`data-value`, defaulting to empty). */\n  #radioValue(radio: HTMLElement): string {\n    return radio.getAttribute(\"data-value\") ?? \"\";\n  }\n}\n"]}

package/dist/controllers/rating_controller.d.ts

@@ -0,0 +1,82 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless, accessible rating (star) behavior.
+ *
+ * Markup contract (identifier: `stimeo--rating`):
+ *   <div data-controller="stimeo--rating" role="radiogroup" aria-label="Rating"
+ *        data-stimeo--rating-value-value="3" data-stimeo--rating-max-value="5">
+ *     <span role="radio" aria-checked="false" aria-label="1 star" tabindex="-1"
+ *           data-rating-value="1" data-stimeo--rating-target="symbol"
+ *           data-action="click->stimeo--rating#select
+ *                        mouseenter->stimeo--rating#preview
+ *                        mouseleave->stimeo--rating#endPreview
+ *                        focus->stimeo--rating#preview
+ *                        blur->stimeo--rating#endPreview
+ *                        keydown->stimeo--rating#onKeydown">★</span>
+ *     <!-- symbols 2..max; the selected one (or the first when unrated) tabindex=0 -->
+ *     <input type="hidden" data-stimeo--rating-target="field" />
+ *   </div>
+ *
+ * Implements the WAI-ARIA APG **Radio Group** pattern (an ordinal scale): exactly
+ * one symbol is `aria-checked`. Unlike a generic radio group it deliberately does
+ * **not** wrap — being ordinal, arrows clamp at the bounds.
+ *
+ * @remarks
+ * Behavior only — symbols are styled by the consumer off `[aria-checked]` and the
+ * `data-rating-hover` fill hook. In `readonly` mode the group becomes
+ * `role="img"`: because Stimeo never emits human-readable prose, the accessible
+ * name (e.g. "Rated 3 of 5") is the consumer's `aria-label`/`aria-labelledby`.
+ *
+ * Behavior provided:
+ * - Click selects a symbol; clicking the selected symbol clears to 0 when
+ *   `clearable`.
+ * - `ArrowRight`/`ArrowUp` raise and `ArrowLeft`/`ArrowDown` lower the value
+ *   (clamped, down to 0 when `clearable`); `Home`/`End` jump to min/max;
+ *   `Space`/`Enter` select the focused symbol.
+ * - Hover/focus previews a fill range via `data-rating-hover`; leaving restores
+ *   the selected range. `stimeo--rating:change` is dispatched on every change.
+ */
+declare class RatingController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        value: {
+            type: NumberConstructor;
+            default: number;
+        };
+        max: {
+            type: NumberConstructor;
+            default: number;
+        };
+        clearable: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        readonly: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+    };
+    static actions: readonly ["endPreview", "onKeydown", "preview", "select"];
+    static events: readonly ["change"];
+    readonly symbolTargets: HTMLElement[];
+    readonly fieldTarget: HTMLInputElement;
+    readonly hasFieldTarget: boolean;
+    valueValue: number;
+    maxValue: number;
+    clearableValue: boolean;
+    readonlyValue: boolean;
+    /** Reflects the initial value, or switches to the non-interactive readonly view. */
+    connect(): void;
+    /** Selects (or clears) the clicked symbol. Bound via `data-action` (click). */
+    select(event: Event): void;
+    /** Previews a fill range on hover/focus. Bound via `data-action` (mouseenter/focus). */
+    preview(event: Event): void;
+    /** Restores the fill range to the selected value. Bound via `data-action` (mouseleave/blur). */
+    endPreview(): void;
+    /** Arrow/Home/End/Space keyboard control, clamped (no wrap). */
+    onKeydown(event: KeyboardEvent): void;
+}
+
+export { RatingController };

package/dist/controllers/rating_controller.js

@@ -0,0 +1,179 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/rating_controller.ts
+
+// src/utils/roving_tabindex.ts
+var RovingTabindex = class {
+  /** Returns the current ordered item elements; called on every operation. */
+  #getItems;
+  /**
+   * @param getItems - Returns the current ordered item elements. Called on every
+   *   operation so the live target list is always used.
+   */
+  constructor(getItems) {
+    this.#getItems = getItems;
+  }
+  /** Index of the currently tabbable item (`tabindex="0"`), or `-1` if none. */
+  get activeIndex() {
+    return this.#getItems().findIndex((item) => item.tabIndex === 0);
+  }
+  /**
+   * Makes exactly the item at `index` tabbable (`tabindex="0"`) and removes every
+   * other item from the Tab sequence (`tabindex="-1"`). An out-of-range `index`
+   * (e.g. `-1`) leaves all items at `-1`, which a controller can use to express
+   * "nothing is currently tabbable".
+   *
+   * @param index - Position of the item to make tabbable.
+   * @param options - Pass `{ focus: true }` to also move DOM focus to that item.
+   */
+  setActive(index, { focus = false } = {}) {
+    const items = this.#getItems();
+    items.forEach((item, i) => {
+      item.tabIndex = i === index ? 0 : -1;
+    });
+    if (focus) items[index]?.focus();
+  }
+};
+
+// src/controllers/rating_controller.ts
+var RatingController = class extends Controller {
+  static targets = ["symbol", "field"];
+  static values = {
+    value: { type: Number, default: 0 },
+    max: { type: Number, default: 5 },
+    clearable: { type: Boolean, default: true },
+    readonly: { type: Boolean, default: false }
+  };
+  static actions = ["endPreview", "onKeydown", "preview", "select"];
+  static events = ["change"];
+  #roving = new RovingTabindex(() => this.symbolTargets);
+  /** Reflects the initial value, or switches to the non-interactive readonly view. */
+  connect() {
+    if (this.readonlyValue) {
+      this.#applyReadonly();
+      return;
+    }
+    this.#apply(this.#clamp(this.valueValue), { focus: false });
+  }
+  /** Selects (or clears) the clicked symbol. Bound via `data-action` (click). */
+  select(event) {
+    if (this.readonlyValue) return;
+    const value = this.#clamp(this.#symbolValue(event.currentTarget));
+    if (this.clearableValue && value === this.valueValue) {
+      this.#render(0, { focus: true });
+    } else {
+      this.#render(value, { focus: false });
+    }
+  }
+  /** Previews a fill range on hover/focus. Bound via `data-action` (mouseenter/focus). */
+  preview(event) {
+    if (this.readonlyValue) return;
+    this.#setFillRange(this.#clamp(this.#symbolValue(event.currentTarget)));
+  }
+  /** Restores the fill range to the selected value. Bound via `data-action` (mouseleave/blur). */
+  endPreview() {
+    if (this.readonlyValue) return;
+    this.#setFillRange(this.valueValue);
+  }
+  /** Arrow/Home/End/Space keyboard control, clamped (no wrap). */
+  onKeydown(event) {
+    if (this.readonlyValue) return;
+    let next = null;
+    switch (event.key) {
+      case "ArrowRight":
+      case "ArrowUp":
+        next = this.valueValue + 1;
+        break;
+      case "ArrowLeft":
+      case "ArrowDown":
+        next = this.valueValue - 1;
+        break;
+      case "Home":
+        next = this.#minValue;
+        break;
+      case "End":
+        next = this.maxValue;
+        break;
+      case " ":
+      case "Enter":
+        next = this.#symbolValue(event.currentTarget);
+        break;
+      default:
+        return;
+    }
+    event.preventDefault();
+    this.#render(this.#clamp(next), { focus: true });
+  }
+  /**
+   * Applies `value` (already clamped) everywhere, then dispatches `change`.
+   * Use for user-driven changes; on connect call `#apply` directly so
+   * initialization mirrors state without emitting an event.
+   */
+  #render(value, { focus }) {
+    this.#apply(value, { focus });
+    this.dispatch("change", { detail: { value } });
+  }
+  /**
+   * Stores `value`, syncs `aria-checked` and the roving Tab stop, the hidden
+   * field, and the fill range — without dispatching `change`. Idempotent and
+   * safe on connect (and across Turbo morphing).
+   */
+  #apply(value, { focus }) {
+    this.valueValue = value;
+    this.symbolTargets.forEach((symbol) => {
+      symbol.setAttribute(
+        "aria-checked",
+        value > 0 && this.#symbolValue(symbol) === value ? "true" : "false"
+      );
+    });
+    this.#roving.setActive(value > 0 ? value - 1 : 0, { focus });
+    if (this.hasFieldTarget) this.fieldTarget.value = String(value);
+    this.#setFillRange(value);
+  }
+  /** Marks symbols up to `range` with `data-rating-hover` (the consumer's fill hook). */
+  #setFillRange(range) {
+    for (const symbol of this.symbolTargets) {
+      if (this.#symbolValue(symbol) <= range && range > 0) {
+        symbol.setAttribute("data-rating-hover", "");
+      } else {
+        symbol.removeAttribute("data-rating-hover");
+      }
+    }
+  }
+  /** Turns the group into a non-interactive `role="img"` snapshot of the value. */
+  #applyReadonly() {
+    const value = this.#clamp(this.valueValue);
+    this.valueValue = value;
+    this.element.setAttribute("role", "img");
+    for (const symbol of this.symbolTargets) {
+      symbol.removeAttribute("role");
+      symbol.setAttribute("aria-hidden", "true");
+      symbol.tabIndex = -1;
+    }
+    if (this.hasFieldTarget) this.fieldTarget.value = String(value);
+    this.#setFillRange(value);
+  }
+  /**
+   * Clamps `value` to `[min, max]` (min is 0 when clearable, else 1). The upper
+   * bound is also capped at the number of symbols so the roving Tab stop
+   * (`value - 1`) always maps to a real symbol — even if the consumer's `max`
+   * value and rendered symbol count disagree, the tabbable item is never lost.
+   */
+  #clamp(value) {
+    const max = Math.min(this.maxValue, this.symbolTargets.length);
+    return Math.min(max, Math.max(this.#minValue, value));
+  }
+  /** Lowest selectable value: 0 when clearable, otherwise 1. */
+  get #minValue() {
+    return this.clearableValue ? 0 : 1;
+  }
+  /** A symbol's ordinal value (`data-rating-value`, defaulting to its position). */
+  #symbolValue(symbol) {
+    const raw = Number(symbol.getAttribute("data-rating-value"));
+    return Number.isFinite(raw) && raw > 0 ? raw : this.symbolTargets.indexOf(symbol) + 1;
+  }
+};
+
+export { RatingController };
+//# sourceMappingURL=rating_controller.js.map
+//# sourceMappingURL=rating_controller.js.map

package/dist/controllers/rating_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/roving_tabindex.ts","../../src/controllers/rating_controller.ts"],"names":[],"mappings":"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","file":"rating_controller.js","sourcesContent":["/**\n * Low-level roving-tabindex primitive shared by composite-widget controllers.\n *\n * The APG roving-tabindex pattern keeps a composite widget a single Tab stop:\n * exactly one item is in the Tab sequence (`tabindex=\"0\"`) while the rest are\n * removed from it (`tabindex=\"-1\"`), and the arrow keys move both DOM focus and\n * that single tabbable position together. {@link RovingTabindex} owns *only* that\n * mechanical bookkeeping — \"which one item is tabbable, and move focus there\".\n *\n * It is intentionally **policy-free**. Orientation, wrapping vs. clamping,\n * selection-follows-focus, typeahead, and `Home`/`End` semantics differ per APG\n * pattern (Radio Group, Toolbar, Rating, …); folding them into one helper would\n * flatten those widgets to a lowest common denominator and lose each pattern's\n * correctness. Those decisions therefore stay in each controller, which calls\n * {@link RovingTabindex.setActive} with an index it computed itself (optionally\n * via the pure {@link rovingMove} helper).\n *\n * @remarks\n * Items are read lazily through a getter so a controller can add or remove\n * targets (Stimulus re-scans the DOM) without re-wiring this helper.\n */\nexport class RovingTabindex {\n  /** Returns the current ordered item elements; called on every operation. */\n  readonly #getItems: () => HTMLElement[];\n\n  /**\n   * @param getItems - Returns the current ordered item elements. Called on every\n   *   operation so the live target list is always used.\n   */\n  constructor(getItems: () => HTMLElement[]) {\n    this.#getItems = getItems;\n  }\n\n  /** Index of the currently tabbable item (`tabindex=\"0\"`), or `-1` if none. */\n  get activeIndex(): number {\n    return this.#getItems().findIndex((item) => item.tabIndex === 0);\n  }\n\n  /**\n   * Makes exactly the item at `index` tabbable (`tabindex=\"0\"`) and removes every\n   * other item from the Tab sequence (`tabindex=\"-1\"`). An out-of-range `index`\n   * (e.g. `-1`) leaves all items at `-1`, which a controller can use to express\n   * \"nothing is currently tabbable\".\n   *\n   * @param index - Position of the item to make tabbable.\n   * @param options - Pass `{ focus: true }` to also move DOM focus to that item.\n   */\n  setActive(index: number, { focus = false }: { focus?: boolean } = {}): void {\n    const items = this.#getItems();\n    items.forEach((item, i) => {\n      item.tabIndex = i === index ? 0 : -1;\n    });\n    if (focus) items[index]?.focus();\n  }\n}\n\n/** Edge behavior for {@link rovingMove}: cycle past the ends, or stop at them. */\nexport type RovingWrap = \"wrap\" | \"clamp\";\n\n/**\n * Pure helper that resolves the target index for a one-step directional move.\n *\n * Keyboard/orientation mapping stays in the caller: it decides that a key means\n * `delta` `+1` (next) or `-1` (previous) and whether the widget should `\"wrap\"`\n * (Radio Group, Toolbar) or `\"clamp\"` at the ends.\n *\n * @param current - The index focus is moving from.\n * @param length - Number of items in the set.\n * @param delta - `+1` to move to the next item, `-1` for the previous.\n * @param wrap - `\"wrap\"` cycles around the ends; `\"clamp\"` stops at them.\n * @returns The resolved index, or `-1` when there are no items.\n */\nexport function rovingMove(\n  current: number,\n  length: number,\n  delta: number,\n  wrap: RovingWrap,\n): number {\n  if (length === 0) return -1;\n  const next = current + delta;\n  if (wrap === \"wrap\") return (next + length) % length;\n  return Math.min(length - 1, Math.max(0, next));\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { RovingTabindex } from \"../utils/roving_tabindex\";\n\n/**\n * Headless, accessible rating (star) behavior.\n *\n * Markup contract (identifier: `stimeo--rating`):\n *   <div data-controller=\"stimeo--rating\" role=\"radiogroup\" aria-label=\"Rating\"\n *        data-stimeo--rating-value-value=\"3\" data-stimeo--rating-max-value=\"5\">\n *     <span role=\"radio\" aria-checked=\"false\" aria-label=\"1 star\" tabindex=\"-1\"\n *           data-rating-value=\"1\" data-stimeo--rating-target=\"symbol\"\n *           data-action=\"click->stimeo--rating#select\n *                        mouseenter->stimeo--rating#preview\n *                        mouseleave->stimeo--rating#endPreview\n *                        focus->stimeo--rating#preview\n *                        blur->stimeo--rating#endPreview\n *                        keydown->stimeo--rating#onKeydown\">★</span>\n *     <!-- symbols 2..max; the selected one (or the first when unrated) tabindex=0 -->\n *     <input type=\"hidden\" data-stimeo--rating-target=\"field\" />\n *   </div>\n *\n * Implements the WAI-ARIA APG **Radio Group** pattern (an ordinal scale): exactly\n * one symbol is `aria-checked`. Unlike a generic radio group it deliberately does\n * **not** wrap — being ordinal, arrows clamp at the bounds.\n *\n * @remarks\n * Behavior only — symbols are styled by the consumer off `[aria-checked]` and the\n * `data-rating-hover` fill hook. In `readonly` mode the group becomes\n * `role=\"img\"`: because Stimeo never emits human-readable prose, the accessible\n * name (e.g. \"Rated 3 of 5\") is the consumer's `aria-label`/`aria-labelledby`.\n *\n * Behavior provided:\n * - Click selects a symbol; clicking the selected symbol clears to 0 when\n *   `clearable`.\n * - `ArrowRight`/`ArrowUp` raise and `ArrowLeft`/`ArrowDown` lower the value\n *   (clamped, down to 0 when `clearable`); `Home`/`End` jump to min/max;\n *   `Space`/`Enter` select the focused symbol.\n * - Hover/focus previews a fill range via `data-rating-hover`; leaving restores\n *   the selected range. `stimeo--rating:change` is dispatched on every change.\n */\nexport class RatingController extends Controller<HTMLElement> {\n  static override targets = [\"symbol\", \"field\"];\n  static override values = {\n    value: { type: Number, default: 0 },\n    max: { type: Number, default: 5 },\n    clearable: { type: Boolean, default: true },\n    readonly: { type: Boolean, default: false },\n  };\n  static actions = [\"endPreview\", \"onKeydown\", \"preview\", \"select\"] as const;\n  static events = [\"change\"] as const;\n\n  declare readonly symbolTargets: HTMLElement[];\n  declare readonly fieldTarget: HTMLInputElement;\n  declare readonly hasFieldTarget: boolean;\n  declare valueValue: number;\n  declare maxValue: number;\n  declare clearableValue: boolean;\n  declare readonlyValue: boolean;\n\n  readonly #roving = new RovingTabindex(() => this.symbolTargets);\n\n  /** Reflects the initial value, or switches to the non-interactive readonly view. */\n  override connect(): void {\n    if (this.readonlyValue) {\n      this.#applyReadonly();\n      return;\n    }\n    this.#apply(this.#clamp(this.valueValue), { focus: false });\n  }\n\n  /** Selects (or clears) the clicked symbol. Bound via `data-action` (click). */\n  select(event: Event): void {\n    if (this.readonlyValue) return;\n    // Clamp the clicked value so a malformed data-rating-value can never push the\n    // roving Tab stop out of range.\n    const value = this.#clamp(this.#symbolValue(event.currentTarget as HTMLElement));\n    if (this.clearableValue && value === this.valueValue) {\n      // Clicking the selected symbol clears the rating; focus returns to the first.\n      this.#render(0, { focus: true });\n    } else {\n      this.#render(value, { focus: false });\n    }\n  }\n\n  /** Previews a fill range on hover/focus. Bound via `data-action` (mouseenter/focus). */\n  preview(event: Event): void {\n    if (this.readonlyValue) return;\n    this.#setFillRange(this.#clamp(this.#symbolValue(event.currentTarget as HTMLElement)));\n  }\n\n  /** Restores the fill range to the selected value. Bound via `data-action` (mouseleave/blur). */\n  endPreview(): void {\n    if (this.readonlyValue) return;\n    this.#setFillRange(this.valueValue);\n  }\n\n  /** Arrow/Home/End/Space keyboard control, clamped (no wrap). */\n  onKeydown(event: KeyboardEvent): void {\n    if (this.readonlyValue) return;\n    let next: number | null = null;\n    switch (event.key) {\n      case \"ArrowRight\":\n      case \"ArrowUp\":\n        next = this.valueValue + 1;\n        break;\n      case \"ArrowLeft\":\n      case \"ArrowDown\":\n        next = this.valueValue - 1;\n        break;\n      case \"Home\":\n        next = this.#minValue;\n        break;\n      case \"End\":\n        next = this.maxValue;\n        break;\n      case \" \":\n      case \"Enter\":\n        next = this.#symbolValue(event.currentTarget as HTMLElement);\n        break;\n      default:\n        return;\n    }\n    event.preventDefault();\n    this.#render(this.#clamp(next), { focus: true });\n  }\n\n  /**\n   * Applies `value` (already clamped) everywhere, then dispatches `change`.\n   * Use for user-driven changes; on connect call `#apply` directly so\n   * initialization mirrors state without emitting an event.\n   */\n  #render(value: number, { focus }: { focus: boolean }): void {\n    this.#apply(value, { focus });\n    this.dispatch(\"change\", { detail: { value } });\n  }\n\n  /**\n   * Stores `value`, syncs `aria-checked` and the roving Tab stop, the hidden\n   * field, and the fill range — without dispatching `change`. Idempotent and\n   * safe on connect (and across Turbo morphing).\n   */\n  #apply(value: number, { focus }: { focus: boolean }): void {\n    this.valueValue = value;\n    this.symbolTargets.forEach((symbol) => {\n      symbol.setAttribute(\n        \"aria-checked\",\n        value > 0 && this.#symbolValue(symbol) === value ? \"true\" : \"false\",\n      );\n    });\n    // The selected symbol is the Tab stop; when unrated, the first symbol is.\n    this.#roving.setActive(value > 0 ? value - 1 : 0, { focus });\n    if (this.hasFieldTarget) this.fieldTarget.value = String(value);\n    this.#setFillRange(value);\n  }\n\n  /** Marks symbols up to `range` with `data-rating-hover` (the consumer's fill hook). */\n  #setFillRange(range: number): void {\n    for (const symbol of this.symbolTargets) {\n      if (this.#symbolValue(symbol) <= range && range > 0) {\n        symbol.setAttribute(\"data-rating-hover\", \"\");\n      } else {\n        symbol.removeAttribute(\"data-rating-hover\");\n      }\n    }\n  }\n\n  /** Turns the group into a non-interactive `role=\"img\"` snapshot of the value. */\n  #applyReadonly(): void {\n    const value = this.#clamp(this.valueValue);\n    this.valueValue = value;\n    this.element.setAttribute(\"role\", \"img\");\n    for (const symbol of this.symbolTargets) {\n      // Drop the interactive radio role so the img has no nested interactive\n      // descendants; aria-hidden removes them from the tree entirely.\n      symbol.removeAttribute(\"role\");\n      symbol.setAttribute(\"aria-hidden\", \"true\");\n      symbol.tabIndex = -1;\n    }\n    if (this.hasFieldTarget) this.fieldTarget.value = String(value);\n    this.#setFillRange(value);\n  }\n\n  /**\n   * Clamps `value` to `[min, max]` (min is 0 when clearable, else 1). The upper\n   * bound is also capped at the number of symbols so the roving Tab stop\n   * (`value - 1`) always maps to a real symbol — even if the consumer's `max`\n   * value and rendered symbol count disagree, the tabbable item is never lost.\n   */\n  #clamp(value: number): number {\n    const max = Math.min(this.maxValue, this.symbolTargets.length);\n    return Math.min(max, Math.max(this.#minValue, value));\n  }\n\n  /** Lowest selectable value: 0 when clearable, otherwise 1. */\n  get #minValue(): number {\n    return this.clearableValue ? 0 : 1;\n  }\n\n  /** A symbol's ordinal value (`data-rating-value`, defaulting to its position). */\n  #symbolValue(symbol: HTMLElement): number {\n    const raw = Number(symbol.getAttribute(\"data-rating-value\"));\n    return Number.isFinite(raw) && raw > 0 ? raw : this.symbolTargets.indexOf(symbol) + 1;\n  }\n}\n"]}

package/dist/controllers/relative_time_controller.d.ts

@@ -0,0 +1,48 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless relative-time behavior: renders an absolute timestamp as "3 minutes
+ * ago" / "in 2 days" and keeps it fresh. No dedicated APG pattern; it follows
+ * the HTML `<time>` semantics.
+ *
+ * Markup contract (identifier: `stimeo--relative-time`):
+ *   <time data-controller="stimeo--relative-time"
+ *         datetime="2026-05-30T12:00:00+09:00" title="2026-05-30 12:00"
+ *         data-stimeo--relative-time-locale-value="ja">2026-05-30 12:00</time>
+ *
+ * Computes the difference from `datetime` to now and formats it with
+ * `Intl.RelativeTimeFormat` (a browser standard — no added dependency). The
+ * polling interval widens as the timestamp ages (seconds → minutes → hours →
+ * days). Past a `threshold`, it falls back to the authored absolute text.
+ *
+ * @remarks
+ * Behavior only. The machine-readable `datetime` attribute is left untouched
+ * while only the visible text updates, and the element is intentionally **not**
+ * a live region (silent updates, no announcement interruptions). The polling
+ * timer is owned by {@link SafeTimeout} and torn down on `disconnect()` (Turbo
+ * navigation included).
+ */
+declare class RelativeTimeController extends Controller<HTMLElement> {
+    #private;
+    static values: {
+        locale: {
+            type: StringConstructor;
+            default: string;
+        };
+        threshold: {
+            type: NumberConstructor;
+            default: number;
+        };
+        tickInterval: {
+            type: NumberConstructor;
+            default: number;
+        };
+    };
+    localeValue: string;
+    thresholdValue: number;
+    tickIntervalValue: number;
+    connect(): void;
+    disconnect(): void;
+}
+
+export { RelativeTimeController };

package/dist/controllers/relative_time_controller.js

@@ -0,0 +1,129 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/relative_time_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/relative_time_controller.ts
+var YEAR_SCALE = { limit: Number.POSITIVE_INFINITY, unit: "year", ms: 315576e5 };
+var UNITS = [
+  { limit: 60, unit: "second", ms: 1e3 },
+  { limit: 3600, unit: "minute", ms: 6e4 },
+  { limit: 86400, unit: "hour", ms: 36e5 },
+  { limit: 604800, unit: "day", ms: 864e5 },
+  { limit: 2629800, unit: "week", ms: 6048e5 },
+  { limit: 31557600, unit: "month", ms: 26298e5 },
+  YEAR_SCALE
+];
+var RelativeTimeController = class extends Controller {
+  static values = {
+    locale: { type: String, default: "" },
+    threshold: { type: Number, default: 0 },
+    tickInterval: { type: Number, default: 6e4 }
+  };
+  #timers = new SafeTimeout();
+  /** Epoch ms parsed from `datetime`; `NaN` when absent or invalid. */
+  #targetMs = Number.NaN;
+  /** The authored absolute text, restored when the threshold fallback kicks in. */
+  #absoluteText = "";
+  connect() {
+    if (this.element.getAttribute("data-state") !== "relative") {
+      this.#absoluteText = (this.element.textContent ?? "").trim();
+    }
+    this.#targetMs = Date.parse(this.element.getAttribute("datetime") ?? "");
+    if (Number.isNaN(this.#targetMs)) return;
+    this.#schedule();
+  }
+  disconnect() {
+    this.#timers.clearAll();
+  }
+  /** Renders the current representation and reschedules unless it is now absolute. */
+  #schedule() {
+    const nextDelay = this.#applyAndComputeDelay();
+    if (nextDelay !== null) {
+      this.#timers.set(() => this.#schedule(), nextDelay);
+    }
+  }
+  /**
+   * Updates the visible text and returns the next poll delay (ms), or `null`
+   * once the absolute fallback is shown (which never changes, so stop polling).
+   */
+  #applyAndComputeDelay() {
+    const deltaMs = this.#targetMs - Date.now();
+    const absSeconds = Math.abs(deltaMs) / 1e3;
+    if (this.thresholdValue > 0 && absSeconds >= this.thresholdValue && this.#absoluteText) {
+      this.element.textContent = this.#absoluteText;
+      this.element.setAttribute("data-state", "absolute");
+      return null;
+    }
+    const scale = UNITS.find((u) => absSeconds < u.limit) ?? YEAR_SCALE;
+    const value = Math.round(deltaMs / scale.ms);
+    this.element.textContent = this.#formatter.format(value, scale.unit);
+    this.element.setAttribute("data-state", "relative");
+    const unitFloor = scale.unit === "second" || scale.unit === "minute" ? 6e4 : scale.ms;
+    return Math.max(this.tickIntervalValue, Math.min(unitFloor, 864e5));
+  }
+  /** A `RelativeTimeFormat` for the resolved locale (`numeric: "auto"`). */
+  get #formatter() {
+    return new Intl.RelativeTimeFormat(this.#locale, { numeric: "auto" });
+  }
+  /** Locale precedence: the value, then the element's `lang`, then the document's. */
+  get #locale() {
+    return this.localeValue || this.element.lang || document.documentElement.lang || void 0;
+  }
+};
+
+export { RelativeTimeController };
+//# sourceMappingURL=relative_time_controller.js.map
+//# sourceMappingURL=relative_time_controller.js.map