stimeo-ui 0.1.0.pre.alpha.1

data/dist/controllers/local_time_controller.js

@@ -0,0 +1,81 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/local_time_controller.ts
+var STYLES = /* @__PURE__ */ new Set(["full", "long", "medium", "short"]);
+function toStyle(value) {
+  return STYLES.has(value) ? value : void 0;
+}
+var LocalTimeController = class extends Controller {
+  static values = {
+    locale: { type: String, default: "" },
+    timeZone: { type: String, default: "" },
+    dateStyle: { type: String, default: "medium" },
+    timeStyle: { type: String, default: "short" },
+    titleFormat: { type: String, default: "" }
+  };
+  static events = ["format"];
+  connect() {
+    const date = this.#parse();
+    if (date === null) return;
+    const formatted = this.#applyFormat(date, this.dateStyleValue, this.timeStyleValue);
+    if (formatted === null) return;
+    this.element.textContent = formatted;
+    const title = this.#title(date);
+    if (title !== null) this.element.setAttribute("title", title);
+    this.dispatch("format", { detail: { formatted } });
+  }
+  /** Parses the UTC `datetime` attribute into a {@link Date}, or `null`. */
+  #parse() {
+    const raw = this.element.getAttribute("datetime");
+    if (!raw) return null;
+    const ms = Date.parse(this.#asUtc(raw.trim()));
+    return Number.isNaN(ms) ? null : new Date(ms);
+  }
+  /**
+   * Reads a timezone-less date-time as UTC — the documented input contract —
+   * since `Date.parse` would otherwise interpret e.g. `"2026-06-08T12:30:00"` in
+   * the *runtime's* local zone, contradicting "the server emits UTC". Values that
+   * already carry `Z` or a `±hh:mm` offset (and bare `YYYY-MM-DD` dates, already
+   * parsed as UTC) are returned unchanged.
+   */
+  #asUtc(value) {
+    const hasTime = /T\d{2}:\d{2}/.test(value);
+    const hasZone = /(Z|[+-]\d{2}:?\d{2})$/.test(value);
+    return hasTime && !hasZone ? `${value}Z` : value;
+  }
+  /**
+   * Builds the optional detailed `title`. `titleFormat` is an `Intl` style
+   * keyword applied to *both* date and time; empty (the default) adds no title.
+   */
+  #title(date) {
+    if (this.titleFormatValue.length === 0) return null;
+    return this.#applyFormat(date, this.titleFormatValue, this.titleFormatValue);
+  }
+  /**
+   * Formats `date` with `Intl.DateTimeFormat`, including each style only when it
+   * is a valid keyword (so a consumer can show date-only or time-only by clearing
+   * the other). Returns `null` when neither style is usable or `Intl` throws, so
+   * the caller can leave the authored text untouched.
+   */
+  #applyFormat(date, dateStyle, timeStyle) {
+    const options = {
+      dateStyle: toStyle(dateStyle),
+      timeStyle: toStyle(timeStyle)
+    };
+    if (options.dateStyle === void 0 && options.timeStyle === void 0) return null;
+    if (this.timeZoneValue.length > 0) options.timeZone = this.timeZoneValue;
+    try {
+      return new Intl.DateTimeFormat(this.#locale, options).format(date);
+    } catch {
+      return null;
+    }
+  }
+  /** 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 { LocalTimeController };
+//# sourceMappingURL=local_time_controller.js.map
+//# sourceMappingURL=local_time_controller.js.map

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

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

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

data/dist/controllers/network_status_controller.js

@@ -0,0 +1,126 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/network_status_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/network_status_controller.ts
+var NetworkStatusController = class extends Controller {
+  static targets = ["offline", "online"];
+  static values = {
+    onlineAutoHide: { type: Number, default: 0 }
+  };
+  static events = ["change"];
+  #timers = new SafeTimeout();
+  /** Last known connectivity; guards against duplicate-state re-announcements. */
+  #online = true;
+  /** Banner text captured from the markup so transitions can re-write it. */
+  #offlineMessage = "";
+  #onlineMessage = "";
+  #handleOnline = () => this.#update(true);
+  #handleOffline = () => this.#update(false);
+  connect() {
+    this.#offlineMessage = this.hasOfflineTarget ? (this.offlineTarget.textContent ?? "").trim() : "";
+    this.#onlineMessage = this.hasOnlineTarget ? (this.onlineTarget.textContent ?? "").trim() : "";
+    if (this.hasOfflineTarget) this.offlineTarget.hidden = true;
+    if (this.hasOnlineTarget) this.onlineTarget.hidden = true;
+    this.#online = navigator.onLine;
+    this.element.setAttribute("data-state", this.#online ? "online" : "offline");
+    if (!this.#online) this.#showOffline();
+    window.addEventListener("online", this.#handleOnline);
+    window.addEventListener("offline", this.#handleOffline);
+  }
+  disconnect() {
+    window.removeEventListener("online", this.#handleOnline);
+    window.removeEventListener("offline", this.#handleOffline);
+    this.#timers.clearAll();
+  }
+  /** Applies a connectivity transition, guarded against duplicate states. */
+  #update(online) {
+    if (online === this.#online) return;
+    this.#online = online;
+    this.element.setAttribute("data-state", online ? "online" : "offline");
+    if (online) {
+      this.#showOnline();
+    } else {
+      this.#showOffline();
+    }
+    this.dispatch("change", { detail: { online } });
+  }
+  /** Shows the offline banner and hides the recovery banner. */
+  #showOffline() {
+    this.#timers.clearAll();
+    if (this.hasOnlineTarget) this.onlineTarget.hidden = true;
+    if (this.hasOfflineTarget) {
+      this.offlineTarget.textContent = this.#offlineMessage;
+      this.offlineTarget.hidden = false;
+    }
+  }
+  /** Shows the recovery banner, optionally auto-hiding it after `onlineAutoHide`. */
+  #showOnline() {
+    if (this.hasOfflineTarget) this.offlineTarget.hidden = true;
+    if (!this.hasOnlineTarget) return;
+    this.onlineTarget.textContent = this.#onlineMessage;
+    this.onlineTarget.hidden = false;
+    if (this.onlineAutoHideValue > 0) {
+      this.#timers.set(() => {
+        this.onlineTarget.hidden = true;
+      }, this.onlineAutoHideValue);
+    }
+  }
+};
+
+export { NetworkStatusController };
+//# sourceMappingURL=network_status_controller.js.map
+//# sourceMappingURL=network_status_controller.js.map