stimeo-ui 0.1.0-alpha.1

package/dist/controllers/menu_controller.js

@@ -0,0 +1,134 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/menu_controller.ts
+var MenuController = class extends Controller {
+  static targets = ["trigger", "menu", "item"];
+  static actions = [
+    "activate",
+    "close",
+    "onItemKeydown",
+    "onTriggerKeydown",
+    "open",
+    "toggle"
+  ];
+  /** Starts closed and registers the outside-click listener. */
+  connect() {
+    this.close();
+    document.addEventListener("click", this.#onOutsideClick);
+  }
+  /** Removes the document-level listener registered in {@link connect}. */
+  disconnect() {
+    document.removeEventListener("click", this.#onOutsideClick);
+  }
+  /** Toggles the menu open/closed. Bound via `data-action` (click). */
+  toggle() {
+    if (this.#isOpen) {
+      this.close();
+    } else {
+      this.open();
+      this.#focusFirst();
+    }
+  }
+  /** Opens the menu and reflects the expanded state on the trigger. */
+  open() {
+    if (!this.hasMenuTarget) return;
+    this.menuTarget.hidden = false;
+    if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "true");
+  }
+  /** Closes the menu and reflects the collapsed state on the trigger. */
+  close() {
+    if (!this.hasMenuTarget) return;
+    this.menuTarget.hidden = true;
+    if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "false");
+  }
+  /**
+   * Opens the menu with the keyboard per the APG (Down → first, Up → last).
+   *
+   * Enter/Space are intentionally not handled here: on a native `<button>`
+   * trigger the browser turns them into a click, which already runs
+   * {@link toggle} (open + focus first item). Handling them again here would
+   * open and then immediately re-toggle the menu.
+   */
+  onTriggerKeydown(event) {
+    if (event.key === "ArrowDown") {
+      event.preventDefault();
+      this.open();
+      this.#focusFirst();
+    } else if (event.key === "ArrowUp") {
+      event.preventDefault();
+      this.open();
+      this.#focusLast();
+    }
+  }
+  /** Implements roving focus and closing keys inside the menu. */
+  onItemKeydown(event) {
+    const items = this.#navigableItems;
+    const currentIndex = items.indexOf(event.currentTarget);
+    switch (event.key) {
+      case "ArrowDown":
+        event.preventDefault();
+        if (items.length > 0) items[(currentIndex + 1) % items.length]?.focus();
+        break;
+      case "ArrowUp":
+        event.preventDefault();
+        if (items.length > 0) items[(currentIndex - 1 + items.length) % items.length]?.focus();
+        break;
+      case "Home":
+        event.preventDefault();
+        items[0]?.focus();
+        break;
+      case "End":
+        event.preventDefault();
+        items[items.length - 1]?.focus();
+        break;
+      case "Escape":
+        event.preventDefault();
+        this.close();
+        if (this.hasTriggerTarget) this.triggerTarget.focus();
+        break;
+      case "Tab":
+        this.close();
+        break;
+    }
+  }
+  /** Closes the menu after an item is activated. Bound via `data-action`. */
+  activate() {
+    this.close();
+    if (this.hasTriggerTarget) this.triggerTarget.focus();
+  }
+  /** Closes the menu when a click lands outside the controller's element. */
+  #onOutsideClick = (event) => {
+    if (this.#isOpen && !this.element.contains(event.target)) this.close();
+  };
+  /** Moves focus to the first navigable item (no-op if none). */
+  #focusFirst() {
+    this.#navigableItems[0]?.focus();
+  }
+  /** Moves focus to the last navigable item (no-op if none). */
+  #focusLast() {
+    const items = this.#navigableItems;
+    items[items.length - 1]?.focus();
+  }
+  /** Menu items eligible for roving focus (excludes disabled / hidden). */
+  get #navigableItems() {
+    return this.itemTargets.filter((item) => this.#isNavigable(item));
+  }
+  /**
+   * An item can take roving focus unless it is `hidden`, `aria-disabled="true"`,
+   * or a natively `disabled` form control. CSS-only visibility is not detectable
+   * here and is the consumer's responsibility.
+   */
+  #isNavigable(item) {
+    if (item.hasAttribute("hidden")) return false;
+    if (item.getAttribute("aria-disabled") === "true") return false;
+    return !item.disabled;
+  }
+  /** Whether the menu is currently visible. */
+  get #isOpen() {
+    return this.hasMenuTarget && !this.menuTarget.hidden;
+  }
+};
+
+export { MenuController };
+//# sourceMappingURL=menu_controller.js.map
+//# sourceMappingURL=menu_controller.js.map

package/dist/controllers/menu_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/menu_controller.ts"],"names":[],"mappings":"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","file":"menu_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/**\n * Headless, accessible menu button behavior.\n *\n * Markup contract (identifier: `stimeo--menu`):\n *   <div data-controller=\"stimeo--menu\">\n *     <button data-stimeo--menu-target=\"trigger\"\n *             data-action=\"click->stimeo--menu#toggle\n *                          keydown->stimeo--menu#onTriggerKeydown\"\n *             aria-haspopup=\"menu\" aria-expanded=\"false\" aria-controls=\"menu\">\n *       Actions\n *     </button>\n *     <ul id=\"menu\" role=\"menu\" data-stimeo--menu-target=\"menu\" hidden>\n *       <li role=\"none\">\n *         <button role=\"menuitem\" tabindex=\"-1\"\n *                 data-stimeo--menu-target=\"item\"\n *                 data-action=\"click->stimeo--menu#activate\n *                              keydown->stimeo--menu#onItemKeydown\">…</button>\n *       </li>\n *     </ul>\n *   </div>\n *\n * Implements the WAI-ARIA APG **Menu Button** pattern (a button that opens a menu\n * of commands). Unlike `stimeo--dropdown` (a disclosure for arbitrary content),\n * this is a true `role=\"menu\"` widget with roving focus across `role=\"menuitem\"`\n * children.\n *\n * @remarks\n * Behavior only — static placement is the consumer's responsibility (CSS), and\n * viewport-edge collision handling is intentionally out of scope (a future shared\n * positioning module will own it). State is exposed via `aria-expanded` and the\n * menu's `hidden` attribute.\n *\n * Behavior provided:\n * - Click the trigger to toggle; `ArrowDown`/`ArrowUp` open and focus the\n *   first/last item.\n * - Within the menu, `ArrowDown`/`ArrowUp` move focus (wrapping), `Home`/`End`\n *   jump to the first/last item, `Escape`/`Tab` close and return focus to the\n *   trigger, and activating an item closes the menu.\n * - A click outside the controller closes the menu.\n *\n * Roving focus skips items that are not navigable — `hidden`, natively\n * `disabled`, or `aria-disabled=\"true\"` — so the keyboard never lands focus on an\n * inert command (matching `stimeo--command-palette` / `stimeo--toolbar`).\n */\nexport class MenuController extends Controller<HTMLElement> {\n  static override targets = [\"trigger\", \"menu\", \"item\"];\n  static actions = [\n    \"activate\",\n    \"close\",\n    \"onItemKeydown\",\n    \"onTriggerKeydown\",\n    \"open\",\n    \"toggle\",\n  ] as const;\n\n  declare readonly triggerTarget: HTMLButtonElement;\n  declare readonly menuTarget: HTMLElement;\n  declare readonly itemTargets: HTMLButtonElement[];\n  declare readonly hasTriggerTarget: boolean;\n  declare readonly hasMenuTarget: boolean;\n\n  /** Starts closed and registers the outside-click listener. */\n  override connect(): void {\n    this.close();\n    document.addEventListener(\"click\", this.#onOutsideClick);\n  }\n\n  /** Removes the document-level listener registered in {@link connect}. */\n  override disconnect(): void {\n    document.removeEventListener(\"click\", this.#onOutsideClick);\n  }\n\n  /** Toggles the menu open/closed. Bound via `data-action` (click). */\n  toggle(): void {\n    if (this.#isOpen) {\n      this.close();\n    } else {\n      this.open();\n      this.#focusFirst();\n    }\n  }\n\n  /** Opens the menu and reflects the expanded state on the trigger. */\n  open(): void {\n    if (!this.hasMenuTarget) return;\n    this.menuTarget.hidden = false;\n    if (this.hasTriggerTarget) this.triggerTarget.setAttribute(\"aria-expanded\", \"true\");\n  }\n\n  /** Closes the menu and reflects the collapsed state on the trigger. */\n  close(): void {\n    if (!this.hasMenuTarget) return;\n    this.menuTarget.hidden = true;\n    if (this.hasTriggerTarget) this.triggerTarget.setAttribute(\"aria-expanded\", \"false\");\n  }\n\n  /**\n   * Opens the menu with the keyboard per the APG (Down → first, Up → last).\n   *\n   * Enter/Space are intentionally not handled here: on a native `<button>`\n   * trigger the browser turns them into a click, which already runs\n   * {@link toggle} (open + focus first item). Handling them again here would\n   * open and then immediately re-toggle the menu.\n   */\n  onTriggerKeydown(event: KeyboardEvent): void {\n    if (event.key === \"ArrowDown\") {\n      event.preventDefault();\n      this.open();\n      this.#focusFirst();\n    } else if (event.key === \"ArrowUp\") {\n      event.preventDefault();\n      this.open();\n      this.#focusLast();\n    }\n  }\n\n  /** Implements roving focus and closing keys inside the menu. */\n  onItemKeydown(event: KeyboardEvent): void {\n    const items = this.#navigableItems;\n    const currentIndex = items.indexOf(event.currentTarget as HTMLButtonElement);\n\n    switch (event.key) {\n      case \"ArrowDown\":\n        event.preventDefault();\n        if (items.length > 0) items[(currentIndex + 1) % items.length]?.focus();\n        break;\n      case \"ArrowUp\":\n        event.preventDefault();\n        if (items.length > 0) items[(currentIndex - 1 + items.length) % items.length]?.focus();\n        break;\n      case \"Home\":\n        event.preventDefault();\n        items[0]?.focus();\n        break;\n      case \"End\":\n        event.preventDefault();\n        items[items.length - 1]?.focus();\n        break;\n      case \"Escape\":\n        event.preventDefault();\n        this.close();\n        if (this.hasTriggerTarget) this.triggerTarget.focus();\n        break;\n      case \"Tab\":\n        // Per APG, Tab closes the menu but focus moves on naturally (it is not\n        // returned to the trigger — that is Escape's job).\n        this.close();\n        break;\n      default:\n        break;\n    }\n  }\n\n  /** Closes the menu after an item is activated. Bound via `data-action`. */\n  activate(): void {\n    this.close();\n    if (this.hasTriggerTarget) this.triggerTarget.focus();\n  }\n\n  /** Closes the menu when a click lands outside the controller's element. */\n  readonly #onOutsideClick = (event: MouseEvent): void => {\n    if (this.#isOpen && !this.element.contains(event.target as Node)) this.close();\n  };\n\n  /** Moves focus to the first navigable item (no-op if none). */\n  #focusFirst(): void {\n    this.#navigableItems[0]?.focus();\n  }\n\n  /** Moves focus to the last navigable item (no-op if none). */\n  #focusLast(): void {\n    const items = this.#navigableItems;\n    items[items.length - 1]?.focus();\n  }\n\n  /** Menu items eligible for roving focus (excludes disabled / hidden). */\n  get #navigableItems(): HTMLButtonElement[] {\n    return this.itemTargets.filter((item) => this.#isNavigable(item));\n  }\n\n  /**\n   * An item can take roving focus unless it is `hidden`, `aria-disabled=\"true\"`,\n   * or a natively `disabled` form control. CSS-only visibility is not detectable\n   * here and is the consumer's responsibility.\n   */\n  #isNavigable(item: HTMLButtonElement): boolean {\n    if (item.hasAttribute(\"hidden\")) return false;\n    if (item.getAttribute(\"aria-disabled\") === \"true\") return false;\n    return !item.disabled;\n  }\n\n  /** Whether the menu is currently visible. */\n  get #isOpen(): boolean {\n    return this.hasMenuTarget && !this.menuTarget.hidden;\n  }\n}\n"]}

package/dist/controllers/meter_controller.d.ts

@@ -0,0 +1,93 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Event shape `setValue` accepts: an action param `amount` or a `detail.value`.
+ * Both are typed `number | string` because, while Stimulus coerces numeric action
+ * params to numbers, a `meter:set` CustomEvent (or a non-numeric-looking param)
+ * may carry a string; {@link MeterController.setValue} normalizes either form.
+ */
+type SetValueEvent = Event & {
+    params?: {
+        amount?: number | string;
+    };
+    detail?: {
+        value?: number | string;
+    };
+};
+/**
+ * Headless meter behavior backed by the WAI-ARIA `meter` role.
+ *
+ * Markup contract (identifier: `stimeo--meter`):
+ *   <div data-controller="stimeo--meter" role="meter" aria-label="Disk usage"
+ *        aria-valuemin="0" aria-valuemax="100" aria-valuenow="72"
+ *        data-stimeo--meter-value-value="72"
+ *        data-stimeo--meter-low-value="50" data-stimeo--meter-high-value="80">
+ *     <div data-stimeo--meter-target="bar"></div>
+ *   </div>
+ *
+ * A `meter` is a *point-in-time* scalar within a known range (disk usage,
+ * battery, score) — distinct from {@link ProgressController}'s task progress.
+ * The controller syncs the ARIA value attributes and, when `low`/`high`
+ * thresholds are present, classifies the value into a `low`/`medium`/`high`
+ * segment on `data-state` so the consumer can color the bar.
+ *
+ * @remarks
+ * Behavior only. Because state must not be conveyed by color alone (WCAG 1.4.1),
+ * a consumer-provided `valueText` template feeds `aria-valuetext` so the segment
+ * is also available as text. Threshold presence is read from the *attributes*
+ * (an absent attribute means "no threshold"), not from a sentinel value.
+ */
+declare class MeterController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        value: {
+            type: NumberConstructor;
+            default: number;
+        };
+        min: {
+            type: NumberConstructor;
+            default: number;
+        };
+        max: {
+            type: NumberConstructor;
+            default: number;
+        };
+        low: {
+            type: NumberConstructor;
+            default: number;
+        };
+        high: {
+            type: NumberConstructor;
+            default: number;
+        };
+        optimum: {
+            type: NumberConstructor;
+            default: number;
+        };
+        valueText: {
+            type: StringConstructor;
+            default: string;
+        };
+    };
+    static actions: readonly ["setValue"];
+    static events: readonly ["change"];
+    readonly barTarget: HTMLElement;
+    readonly hasBarTarget: boolean;
+    valueValue: number;
+    minValue: number;
+    maxValue: number;
+    lowValue: number;
+    highValue: number;
+    optimumValue: number;
+    valueTextValue: string;
+    connect(): void;
+    /**
+     * Updates the measured value from an action param (`amount`) or a
+     * `detail.value` CustomEvent, syncs ARIA and `data-state`, and dispatches
+     * `change` with the value, ratio, and computed segment.
+     */
+    setValue(event: SetValueEvent): void;
+}
+
+export { MeterController };

package/dist/controllers/meter_controller.js

@@ -0,0 +1,96 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/meter_controller.ts
+
+// src/utils/coerce.ts
+function toFiniteNumber(raw) {
+  if (raw === null || raw === void 0 || raw === "") return null;
+  const value = typeof raw === "number" ? raw : Number(raw);
+  return Number.isFinite(value) ? value : null;
+}
+
+// src/controllers/meter_controller.ts
+var MeterController = class extends Controller {
+  static targets = ["bar"];
+  static values = {
+    value: { type: Number, default: 0 },
+    min: { type: Number, default: 0 },
+    max: { type: Number, default: 100 },
+    low: { type: Number, default: 0 },
+    high: { type: Number, default: 0 },
+    optimum: { type: Number, default: 0 },
+    valueText: { type: String, default: "" }
+  };
+  static actions = ["setValue"];
+  static events = ["change"];
+  connect() {
+    this.#render();
+  }
+  /**
+   * Updates the measured value from an action param (`amount`) or a
+   * `detail.value` CustomEvent, syncs ARIA and `data-state`, and dispatches
+   * `change` with the value, ratio, and computed segment.
+   */
+  setValue(event) {
+    const next = toFiniteNumber(event.params?.amount ?? event.detail?.value);
+    if (next === null) return;
+    this.valueValue = this.#clamp(next);
+    this.#render();
+    this.dispatch("change", {
+      detail: { value: this.valueValue, ratio: this.#ratio, state: this.#state }
+    });
+  }
+  /** Clamps `raw` into the configured `[min, max]` range. */
+  #clamp(raw) {
+    return Math.min(this.maxValue, Math.max(this.minValue, raw));
+  }
+  /** Current fraction of the range in `[0, 1]`; `0` when the range is empty. */
+  get #ratio() {
+    const span = this.maxValue - this.minValue;
+    if (span <= 0) return 0;
+    return (this.#clamp(this.valueValue) - this.minValue) / span;
+  }
+  /** Whether a threshold attribute is present (absent = no threshold). */
+  #hasThreshold(name) {
+    return this.element.hasAttribute(`data-stimeo--meter-${name}-value`);
+  }
+  /**
+   * Classifies the value into a `low`/`medium`/`high` segment. Values at or
+   * below `low` are `low`; at or above `high` are `high`; otherwise `medium`.
+   * With neither threshold present, everything is `medium`.
+   */
+  get #state() {
+    const value = this.#clamp(this.valueValue);
+    if (this.#hasThreshold("low") && value <= this.lowValue) return "low";
+    if (this.#hasThreshold("high") && value >= this.highValue) return "high";
+    return "medium";
+  }
+  /** Reflects value/range onto ARIA, the segment onto `data-state`, and the ratio. */
+  #render() {
+    const value = this.#clamp(this.valueValue);
+    this.element.setAttribute("aria-valuemin", String(this.minValue));
+    this.element.setAttribute("aria-valuemax", String(this.maxValue));
+    this.element.setAttribute("aria-valuenow", String(value));
+    this.element.style.setProperty("--stimeo-meter-ratio", String(this.#ratio));
+    this.element.setAttribute("data-state", this.#state);
+    this.#applyValueText(value);
+  }
+  /**
+   * Sets `aria-valuetext` from the consumer-provided template, substituting
+   * `{value}`, `{percent}`, and `{state}`. Kept i18n-neutral in the library;
+   * cleared when no template is given.
+   */
+  #applyValueText(value) {
+    if (this.valueTextValue.length === 0) {
+      this.element.removeAttribute("aria-valuetext");
+      return;
+    }
+    const percent = Math.round(this.#ratio * 100);
+    const text = this.valueTextValue.replaceAll("{value}", String(value)).replaceAll("{percent}", String(percent)).replaceAll("{state}", this.#state);
+    this.element.setAttribute("aria-valuetext", text);
+  }
+};
+
+export { MeterController };
+//# sourceMappingURL=meter_controller.js.map
+//# sourceMappingURL=meter_controller.js.map

package/dist/controllers/meter_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/coerce.ts","../../src/controllers/meter_controller.ts"],"names":[],"mappings":"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","file":"meter_controller.js","sourcesContent":["/**\n * Numeric coercion shared by the value-bearing status controllers (progress,\n * meter).\n *\n * Stimulus already coerces numeric action params to numbers, but a value can also\n * arrive as a string — via a `*:set` CustomEvent `detail`, or an action param\n * whose attribute does not look numeric. Centralizing the parse keeps `setValue`\n * tolerant of either form while rejecting anything that is not a finite number.\n */\n\n/**\n * Coerces `raw` to a finite number, or returns `null` when it is absent, empty,\n * or not parseable. Empty strings are treated as \"no value\" rather than `0`, so a\n * stray blank param cannot silently reset the value.\n */\nexport function toFiniteNumber(raw: number | string | null | undefined): number | null {\n  if (raw === null || raw === undefined || raw === \"\") return null;\n  const value = typeof raw === \"number\" ? raw : Number(raw);\n  return Number.isFinite(value) ? value : null;\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { toFiniteNumber } from \"../utils/coerce\";\n\n/**\n * Event shape `setValue` accepts: an action param `amount` or a `detail.value`.\n * Both are typed `number | string` because, while Stimulus coerces numeric action\n * params to numbers, a `meter:set` CustomEvent (or a non-numeric-looking param)\n * may carry a string; {@link MeterController.setValue} normalizes either form.\n */\ntype SetValueEvent = Event & {\n  params?: { amount?: number | string };\n  detail?: { value?: number | string };\n};\n\n/** Threshold segment a value falls into, reflected on `data-state`. */\ntype MeterState = \"low\" | \"medium\" | \"high\";\n\n/**\n * Headless meter behavior backed by the WAI-ARIA `meter` role.\n *\n * Markup contract (identifier: `stimeo--meter`):\n *   <div data-controller=\"stimeo--meter\" role=\"meter\" aria-label=\"Disk usage\"\n *        aria-valuemin=\"0\" aria-valuemax=\"100\" aria-valuenow=\"72\"\n *        data-stimeo--meter-value-value=\"72\"\n *        data-stimeo--meter-low-value=\"50\" data-stimeo--meter-high-value=\"80\">\n *     <div data-stimeo--meter-target=\"bar\"></div>\n *   </div>\n *\n * A `meter` is a *point-in-time* scalar within a known range (disk usage,\n * battery, score) — distinct from {@link ProgressController}'s task progress.\n * The controller syncs the ARIA value attributes and, when `low`/`high`\n * thresholds are present, classifies the value into a `low`/`medium`/`high`\n * segment on `data-state` so the consumer can color the bar.\n *\n * @remarks\n * Behavior only. Because state must not be conveyed by color alone (WCAG 1.4.1),\n * a consumer-provided `valueText` template feeds `aria-valuetext` so the segment\n * is also available as text. Threshold presence is read from the *attributes*\n * (an absent attribute means \"no threshold\"), not from a sentinel value.\n */\nexport class MeterController extends Controller<HTMLElement> {\n  static override targets = [\"bar\"];\n  static override values = {\n    value: { type: Number, default: 0 },\n    min: { type: Number, default: 0 },\n    max: { type: Number, default: 100 },\n    low: { type: Number, default: 0 },\n    high: { type: Number, default: 0 },\n    optimum: { type: Number, default: 0 },\n    valueText: { type: String, default: \"\" },\n  };\n  static actions = [\"setValue\"] as const;\n  static events = [\"change\"] as const;\n\n  declare readonly barTarget: HTMLElement;\n  declare readonly hasBarTarget: boolean;\n\n  declare valueValue: number;\n  declare minValue: number;\n  declare maxValue: number;\n  declare lowValue: number;\n  declare highValue: number;\n  declare optimumValue: number;\n  declare valueTextValue: string;\n\n  override connect(): void {\n    this.#render();\n  }\n\n  /**\n   * Updates the measured value from an action param (`amount`) or a\n   * `detail.value` CustomEvent, syncs ARIA and `data-state`, and dispatches\n   * `change` with the value, ratio, and computed segment.\n   */\n  setValue(event: SetValueEvent): void {\n    const next = toFiniteNumber(event.params?.amount ?? event.detail?.value);\n    if (next === null) return;\n    this.valueValue = this.#clamp(next);\n    this.#render();\n    this.dispatch(\"change\", {\n      detail: { value: this.valueValue, ratio: this.#ratio, state: this.#state },\n    });\n  }\n\n  /** Clamps `raw` into the configured `[min, max]` range. */\n  #clamp(raw: number): number {\n    return Math.min(this.maxValue, Math.max(this.minValue, raw));\n  }\n\n  /** Current fraction of the range in `[0, 1]`; `0` when the range is empty. */\n  get #ratio(): number {\n    const span = this.maxValue - this.minValue;\n    if (span <= 0) return 0;\n    return (this.#clamp(this.valueValue) - this.minValue) / span;\n  }\n\n  /** Whether a threshold attribute is present (absent = no threshold). */\n  #hasThreshold(name: \"low\" | \"high\"): boolean {\n    return this.element.hasAttribute(`data-stimeo--meter-${name}-value`);\n  }\n\n  /**\n   * Classifies the value into a `low`/`medium`/`high` segment. Values at or\n   * below `low` are `low`; at or above `high` are `high`; otherwise `medium`.\n   * With neither threshold present, everything is `medium`.\n   */\n  get #state(): MeterState {\n    const value = this.#clamp(this.valueValue);\n    if (this.#hasThreshold(\"low\") && value <= this.lowValue) return \"low\";\n    if (this.#hasThreshold(\"high\") && value >= this.highValue) return \"high\";\n    return \"medium\";\n  }\n\n  /** Reflects value/range onto ARIA, the segment onto `data-state`, and the ratio. */\n  #render(): void {\n    const value = this.#clamp(this.valueValue);\n    this.element.setAttribute(\"aria-valuemin\", String(this.minValue));\n    this.element.setAttribute(\"aria-valuemax\", String(this.maxValue));\n    this.element.setAttribute(\"aria-valuenow\", String(value));\n    this.element.style.setProperty(\"--stimeo-meter-ratio\", String(this.#ratio));\n    this.element.setAttribute(\"data-state\", this.#state);\n    this.#applyValueText(value);\n  }\n\n  /**\n   * Sets `aria-valuetext` from the consumer-provided template, substituting\n   * `{value}`, `{percent}`, and `{state}`. Kept i18n-neutral in the library;\n   * cleared when no template is given.\n   */\n  #applyValueText(value: number): void {\n    if (this.valueTextValue.length === 0) {\n      this.element.removeAttribute(\"aria-valuetext\");\n      return;\n    }\n    const percent = Math.round(this.#ratio * 100);\n    const text = this.valueTextValue\n      .replaceAll(\"{value}\", String(value))\n      .replaceAll(\"{percent}\", String(percent))\n      .replaceAll(\"{state}\", this.#state);\n    this.element.setAttribute(\"aria-valuetext\", text);\n  }\n}\n"]}

package/dist/controllers/nested_form_controller.d.ts

@@ -0,0 +1,85 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless **nested / dynamic fields** for Rails `fields_for` +
+ * `accepts_nested_attributes_for` (no dedicated APG pattern — form editing). The
+ * Headless successor to the cocoon / nested_form gems: clone a `<template>` row,
+ * renumber its index, and remove rows by flagging `_destroy` (persisted) or
+ * dropping them from the DOM (unsaved).
+ *
+ * Markup contract (identifier: `stimeo--nested-form`):
+ *   <div data-controller="stimeo--nested-form" data-stimeo--nested-form-min-value="1">
+ *     <div data-stimeo--nested-form-target="list">
+ *       <!-- existing rows; a persisted row carries a _destroy flag + remove button -->
+ *     </div>
+ *     <template data-stimeo--nested-form-target="template">
+ *       <fieldset>
+ *         <input name="order[items_attributes][__INDEX__][name]">
+ *         <button type="button" data-stimeo--nested-form-target="remove">Remove</button>
+ *       </fieldset>
+ *     </template>
+ *     <button type="button" data-stimeo--nested-form-target="add"
+ *             data-action="click->stimeo--nested-form#add">Add</button>
+ *   </div>
+ *
+ * @remarks
+ * Behavior only — server-side `accepts_nested_attributes_for`, per-field
+ * validation, and reordering are out of scope. Row state lives **only** in the DOM
+ * (inserted nodes + each `_destroy` hidden input); there is no module-scope index
+ * counter, so the controller stays idempotent across Turbo swaps. Remove buttons
+ * are handled by **delegation** on the container, so dynamically-added rows work
+ * without per-row `data-action` (see `stimulus-lifecycle-turbo`). Adding a row moves
+ * focus to its first control and removing returns focus to a neighbor (WCAG 2.2
+ * 2.4.3); count changes are announced through the shared `stimeo--announcer`
+ * (WCAG 2.2 4.1.3) when `announce` + `countMessage` are set. The delegated listener
+ * is removed on `disconnect()`.
+ */
+declare class NestedFormController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        min: {
+            type: NumberConstructor;
+            default: number;
+        };
+        max: {
+            type: NumberConstructor;
+            default: number;
+        };
+        indexPlaceholder: {
+            type: StringConstructor;
+            default: string;
+        };
+        announce: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        countMessage: {
+            type: StringConstructor;
+            default: string;
+        };
+    };
+    static actions: readonly ["add"];
+    static events: readonly ["add", "remove"];
+    readonly listTarget: HTMLElement;
+    readonly templateTarget: HTMLTemplateElement;
+    readonly addTarget: HTMLButtonElement;
+    readonly hasListTarget: boolean;
+    readonly hasTemplateTarget: boolean;
+    readonly hasAddTarget: boolean;
+    minValue: number;
+    maxValue: number;
+    indexPlaceholderValue: string;
+    announceValue: boolean;
+    countMessageValue: string;
+    connect(): void;
+    disconnect(): void;
+    /**
+     * Clones the template row, replaces the index placeholder with a unique value,
+     * appends it, focuses its first control, and announces the new count. No-ops at
+     * `max`.
+     */
+    add(): void;
+}
+
+export { NestedFormController };

package/dist/controllers/nested_form_controller.js

@@ -0,0 +1,131 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/nested_form_controller.ts
+var NestedFormController = class extends Controller {
+  static targets = ["list", "template", "add", "remove", "destroyFlag"];
+  static values = {
+    min: { type: Number, default: 0 },
+    max: { type: Number, default: 0 },
+    indexPlaceholder: { type: String, default: "__INDEX__" },
+    announce: { type: Boolean, default: true },
+    countMessage: { type: String, default: "" }
+  };
+  static actions = ["add"];
+  static events = ["add", "remove"];
+  /** Monotonic source for unique row indices; never a row-state counter. */
+  #lastIndex = 0;
+  /** Delegated click handler for the per-row remove buttons (dynamic-safe). */
+  #onClick = (event) => {
+    const target = event.target;
+    const button = target?.closest('[data-stimeo--nested-form-target="remove"]');
+    if (!button || !this.element.contains(button)) return;
+    const row = this.#rowContaining(button);
+    if (row) this.#removeRow(row);
+  };
+  connect() {
+    this.element.addEventListener("click", this.#onClick);
+    this.#refresh();
+  }
+  disconnect() {
+    this.element.removeEventListener("click", this.#onClick);
+  }
+  /**
+   * Clones the template row, replaces the index placeholder with a unique value,
+   * appends it, focuses its first control, and announces the new count. No-ops at
+   * `max`.
+   */
+  add() {
+    if (!this.hasTemplateTarget || !this.hasListTarget || this.#atMax) return;
+    const index = this.#nextIndex();
+    const markup = this.templateTarget.innerHTML.replaceAll(
+      this.indexPlaceholderValue,
+      String(index)
+    );
+    this.listTarget.insertAdjacentHTML("beforeend", markup);
+    const row = this.listTarget.lastElementChild;
+    if (!row) return;
+    this.#refresh();
+    this.#firstControl(row)?.focus();
+    this.dispatch("add", { detail: { index, element: row } });
+    this.#announce();
+  }
+  /**
+   * Removes a row: a persisted row (one carrying a `destroyFlag`) has its flag set
+   * to `1` and is hidden so Rails destroys it on submit; an unsaved row is dropped
+   * from the DOM. Returns focus to a neighboring row. No-ops at `min`.
+   */
+  #removeRow(row) {
+    if (this.#effectiveRows.length <= this.minValue) return;
+    const neighbors = this.#effectiveRows;
+    const position = neighbors.indexOf(row);
+    const neighbor = neighbors[position + 1] ?? neighbors[position - 1] ?? null;
+    const flag = row.querySelector(
+      '[data-stimeo--nested-form-target="destroyFlag"]'
+    );
+    const persisted = flag !== null;
+    if (persisted) {
+      flag.value = "1";
+      row.hidden = true;
+    } else {
+      row.remove();
+    }
+    this.#refresh();
+    const focusTarget = neighbor ? this.#firstControl(neighbor) : this.hasAddTarget ? this.addTarget : null;
+    focusTarget?.focus();
+    this.dispatch("remove", { detail: { element: row, persisted } });
+    this.#announce();
+  }
+  /** Recomputes the live count and the min/max state hooks from the DOM. */
+  #refresh() {
+    const count = this.#effectiveRows.length;
+    this.element.setAttribute("data-nested-count", String(count));
+    this.#reflect("data-nested-at-max", this.maxValue > 0 && count >= this.maxValue);
+    this.#reflect("data-nested-at-min", count <= this.minValue);
+    if (this.hasAddTarget) this.addTarget.disabled = this.#atMax;
+  }
+  /** Bridges the count change to the shared announcer when configured. */
+  #announce() {
+    if (!this.announceValue || !this.countMessageValue) return;
+    const message = this.countMessageValue.replaceAll(
+      "{count}",
+      String(this.#effectiveRows.length)
+    );
+    window.dispatchEvent(new CustomEvent("stimeo--announcer:announce", { detail: { message } }));
+  }
+  /** Sets `attribute` to `"true"` when `on`, else removes it. */
+  #reflect(attribute, on) {
+    if (on) this.element.setAttribute(attribute, "true");
+    else this.element.removeAttribute(attribute);
+  }
+  /** A strictly-increasing unique index (collision-free even on rapid adds). */
+  #nextIndex() {
+    const index = Math.max(Date.now(), this.#lastIndex + 1);
+    this.#lastIndex = index;
+    return index;
+  }
+  get #atMax() {
+    return this.maxValue > 0 && this.#effectiveRows.length >= this.maxValue;
+  }
+  /** Direct child rows of the list that are not flagged for destruction. */
+  get #effectiveRows() {
+    return Array.from(this.listTarget.children).filter((row) => !row.hidden);
+  }
+  /** The nearest ancestor of `el` that is a direct child of the list, else null. */
+  #rowContaining(el) {
+    let node = el;
+    while (node && node.parentElement !== this.listTarget) {
+      node = node.parentElement;
+    }
+    return node;
+  }
+  /** First visible focusable control inside `row` (skips hidden inputs). */
+  #firstControl(row) {
+    return row.querySelector(
+      'input:not([type="hidden"]), select, textarea, button, [tabindex]'
+    );
+  }
+};
+
+export { NestedFormController };
+//# sourceMappingURL=nested_form_controller.js.map
+//# sourceMappingURL=nested_form_controller.js.map

package/dist/controllers/nested_form_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/nested_form_controller.ts"],"names":[],"mappings":"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","file":"nested_form_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/**\n * Headless **nested / dynamic fields** for Rails `fields_for` +\n * `accepts_nested_attributes_for` (no dedicated APG pattern — form editing). The\n * Headless successor to the cocoon / nested_form gems: clone a `<template>` row,\n * renumber its index, and remove rows by flagging `_destroy` (persisted) or\n * dropping them from the DOM (unsaved).\n *\n * Markup contract (identifier: `stimeo--nested-form`):\n *   <div data-controller=\"stimeo--nested-form\" data-stimeo--nested-form-min-value=\"1\">\n *     <div data-stimeo--nested-form-target=\"list\">\n *       <!-- existing rows; a persisted row carries a _destroy flag + remove button -->\n *     </div>\n *     <template data-stimeo--nested-form-target=\"template\">\n *       <fieldset>\n *         <input name=\"order[items_attributes][__INDEX__][name]\">\n *         <button type=\"button\" data-stimeo--nested-form-target=\"remove\">Remove</button>\n *       </fieldset>\n *     </template>\n *     <button type=\"button\" data-stimeo--nested-form-target=\"add\"\n *             data-action=\"click->stimeo--nested-form#add\">Add</button>\n *   </div>\n *\n * @remarks\n * Behavior only — server-side `accepts_nested_attributes_for`, per-field\n * validation, and reordering are out of scope. Row state lives **only** in the DOM\n * (inserted nodes + each `_destroy` hidden input); there is no module-scope index\n * counter, so the controller stays idempotent across Turbo swaps. Remove buttons\n * are handled by **delegation** on the container, so dynamically-added rows work\n * without per-row `data-action` (see `stimulus-lifecycle-turbo`). Adding a row moves\n * focus to its first control and removing returns focus to a neighbor (WCAG 2.2\n * 2.4.3); count changes are announced through the shared `stimeo--announcer`\n * (WCAG 2.2 4.1.3) when `announce` + `countMessage` are set. The delegated listener\n * is removed on `disconnect()`.\n */\nexport class NestedFormController extends Controller<HTMLElement> {\n  static override targets = [\"list\", \"template\", \"add\", \"remove\", \"destroyFlag\"];\n  static override values = {\n    min: { type: Number, default: 0 },\n    max: { type: Number, default: 0 },\n    indexPlaceholder: { type: String, default: \"__INDEX__\" },\n    announce: { type: Boolean, default: true },\n    countMessage: { type: String, default: \"\" },\n  };\n  static actions = [\"add\"] as const;\n  static events = [\"add\", \"remove\"] as const;\n\n  declare readonly listTarget: HTMLElement;\n  declare readonly templateTarget: HTMLTemplateElement;\n  declare readonly addTarget: HTMLButtonElement;\n  declare readonly hasListTarget: boolean;\n  declare readonly hasTemplateTarget: boolean;\n  declare readonly hasAddTarget: boolean;\n\n  declare minValue: number;\n  declare maxValue: number;\n  declare indexPlaceholderValue: string;\n  declare announceValue: boolean;\n  declare countMessageValue: string;\n\n  /** Monotonic source for unique row indices; never a row-state counter. */\n  #lastIndex = 0;\n\n  /** Delegated click handler for the per-row remove buttons (dynamic-safe). */\n  readonly #onClick = (event: Event): void => {\n    const target = event.target as HTMLElement | null;\n    const button = target?.closest('[data-stimeo--nested-form-target=\"remove\"]');\n    if (!button || !this.element.contains(button)) return;\n    const row = this.#rowContaining(button);\n    if (row) this.#removeRow(row);\n  };\n\n  override connect(): void {\n    this.element.addEventListener(\"click\", this.#onClick);\n    this.#refresh();\n  }\n\n  override disconnect(): void {\n    this.element.removeEventListener(\"click\", this.#onClick);\n  }\n\n  /**\n   * Clones the template row, replaces the index placeholder with a unique value,\n   * appends it, focuses its first control, and announces the new count. No-ops at\n   * `max`.\n   */\n  add(): void {\n    if (!this.hasTemplateTarget || !this.hasListTarget || this.#atMax) return;\n\n    const index = this.#nextIndex();\n    const markup = this.templateTarget.innerHTML.replaceAll(\n      this.indexPlaceholderValue,\n      String(index),\n    );\n    this.listTarget.insertAdjacentHTML(\"beforeend\", markup);\n    const row = this.listTarget.lastElementChild as HTMLElement | null;\n    if (!row) return;\n\n    this.#refresh();\n    this.#firstControl(row)?.focus();\n    this.dispatch(\"add\", { detail: { index, element: row } });\n    this.#announce();\n  }\n\n  /**\n   * Removes a row: a persisted row (one carrying a `destroyFlag`) has its flag set\n   * to `1` and is hidden so Rails destroys it on submit; an unsaved row is dropped\n   * from the DOM. Returns focus to a neighboring row. No-ops at `min`.\n   */\n  #removeRow(row: HTMLElement): void {\n    if (this.#effectiveRows.length <= this.minValue) return;\n\n    const neighbors = this.#effectiveRows;\n    const position = neighbors.indexOf(row);\n    const neighbor = neighbors[position + 1] ?? neighbors[position - 1] ?? null;\n\n    const flag = row.querySelector<HTMLInputElement>(\n      '[data-stimeo--nested-form-target=\"destroyFlag\"]',\n    );\n    const persisted = flag !== null;\n    if (persisted) {\n      flag.value = \"1\";\n      row.hidden = true;\n    } else {\n      row.remove();\n    }\n\n    this.#refresh();\n    const focusTarget = neighbor\n      ? this.#firstControl(neighbor)\n      : this.hasAddTarget\n        ? this.addTarget\n        : null;\n    focusTarget?.focus();\n    this.dispatch(\"remove\", { detail: { element: row, persisted } });\n    this.#announce();\n  }\n\n  /** Recomputes the live count and the min/max state hooks from the DOM. */\n  #refresh(): void {\n    const count = this.#effectiveRows.length;\n    this.element.setAttribute(\"data-nested-count\", String(count));\n    this.#reflect(\"data-nested-at-max\", this.maxValue > 0 && count >= this.maxValue);\n    this.#reflect(\"data-nested-at-min\", count <= this.minValue);\n    if (this.hasAddTarget) this.addTarget.disabled = this.#atMax;\n  }\n\n  /** Bridges the count change to the shared announcer when configured. */\n  #announce(): void {\n    if (!this.announceValue || !this.countMessageValue) return;\n    const message = this.countMessageValue.replaceAll(\n      \"{count}\",\n      String(this.#effectiveRows.length),\n    );\n    window.dispatchEvent(new CustomEvent(\"stimeo--announcer:announce\", { detail: { message } }));\n  }\n\n  /** Sets `attribute` to `\"true\"` when `on`, else removes it. */\n  #reflect(attribute: string, on: boolean): void {\n    if (on) this.element.setAttribute(attribute, \"true\");\n    else this.element.removeAttribute(attribute);\n  }\n\n  /** A strictly-increasing unique index (collision-free even on rapid adds). */\n  #nextIndex(): number {\n    const index = Math.max(Date.now(), this.#lastIndex + 1);\n    this.#lastIndex = index;\n    return index;\n  }\n\n  get #atMax(): boolean {\n    return this.maxValue > 0 && this.#effectiveRows.length >= this.maxValue;\n  }\n\n  /** Direct child rows of the list that are not flagged for destruction. */\n  get #effectiveRows(): HTMLElement[] {\n    return (Array.from(this.listTarget.children) as HTMLElement[]).filter((row) => !row.hidden);\n  }\n\n  /** The nearest ancestor of `el` that is a direct child of the list, else null. */\n  #rowContaining(el: Element): HTMLElement | null {\n    let node: Element | null = el;\n    while (node && node.parentElement !== this.listTarget) {\n      node = node.parentElement;\n    }\n    return node as HTMLElement | null;\n  }\n\n  /** First visible focusable control inside `row` (skips hidden inputs). */\n  #firstControl(row: HTMLElement): HTMLElement | null {\n    return row.querySelector<HTMLElement>(\n      'input:not([type=\"hidden\"]), select, textarea, button, [tabindex]',\n    );\n  }\n}\n"]}