stimeo-ui 0.1.0.pre.alpha.1

data/dist/controllers/persist_controller.js

@@ -0,0 +1,259 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/persist_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/persist_controller.ts
+var NON_VALUE_TYPES = /* @__PURE__ */ new Set(["file", "submit", "reset", "button", "image"]);
+var STORAGE_PREFIX = "stimeo--persist:";
+var OCCURRENCE_SEP = "\0";
+var PersistController = class extends Controller {
+  static targets = ["field"];
+  static values = {
+    key: { type: String, default: "" },
+    debounce: { type: Number, default: 400 },
+    exclude: { type: Array, default: ["password"] },
+    clearOn: { type: String, default: "" }
+  };
+  static actions = ["clear"];
+  static events = ["restore", "save", "clear"];
+  #timeouts = new SafeTimeout();
+  #saveId = null;
+  #onInput = () => {
+    this.#scheduleSave();
+  };
+  #onClearEvent = () => {
+    this.clear();
+  };
+  connect() {
+    if (this.#storageKey === null) return;
+    this.#restore();
+    this.element.addEventListener("input", this.#onInput);
+    this.element.addEventListener("change", this.#onInput);
+    if (this.clearOnValue.length > 0) {
+      this.element.addEventListener(this.clearOnValue, this.#onClearEvent);
+    }
+  }
+  disconnect() {
+    this.element.removeEventListener("input", this.#onInput);
+    this.element.removeEventListener("change", this.#onInput);
+    if (this.clearOnValue.length > 0) {
+      this.element.removeEventListener(this.clearOnValue, this.#onClearEvent);
+    }
+    if (this.#saveId !== null) {
+      this.#timeouts.clear(this.#saveId);
+      this.#saveId = null;
+      this.#write();
+    }
+    this.#timeouts.clearAll();
+  }
+  /** Drops the saved draft and clears the restored marker. */
+  clear() {
+    const key = this.#storageKey;
+    if (key === null) return;
+    if (this.#saveId !== null) {
+      this.#timeouts.clear(this.#saveId);
+      this.#saveId = null;
+    }
+    this.#removeItem(key);
+    this.element.removeAttribute("data-persist-restored");
+    this.dispatch("clear", { detail: { key: this.#logicalKey } });
+  }
+  /** Schedules a debounced save. */
+  #scheduleSave() {
+    if (this.#saveId !== null) this.#timeouts.clear(this.#saveId);
+    this.#saveId = this.#timeouts.set(() => {
+      this.#saveId = null;
+      this.#save();
+    }, this.debounceValue);
+  }
+  /** Writes the current values and emits `save`. */
+  #save() {
+    this.#write();
+    this.dispatch("save", { detail: { key: this.#logicalKey } });
+  }
+  /** Serializes persistable fields and stores them under the storage key. */
+  #write() {
+    const key = this.#storageKey;
+    if (key === null) return;
+    const data = {};
+    for (const { field, key: fieldKey } of this.#fieldEntries()) {
+      if (field instanceof HTMLInputElement && field.type === "checkbox") {
+        data[fieldKey] = field.checked;
+      } else if (field instanceof HTMLInputElement && field.type === "radio") {
+        if (field.checked) data[fieldKey] = field.value;
+      } else if (field instanceof HTMLSelectElement && field.multiple) {
+        data[fieldKey] = Array.from(field.selectedOptions).map((o) => o.value);
+      } else {
+        data[fieldKey] = field.value;
+      }
+    }
+    this.#setItem(key, JSON.stringify(data));
+  }
+  /** Applies any saved values to the fields, without moving focus. */
+  #restore() {
+    const key = this.#storageKey;
+    if (key === null) return;
+    const raw = this.#getItem(key);
+    if (raw === null) return;
+    let data;
+    try {
+      data = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    let restoredAny = false;
+    for (const { field, key: fieldKey } of this.#fieldEntries()) {
+      if (!Object.hasOwn(data, fieldKey)) continue;
+      this.#applyValue(field, data[fieldKey]);
+      restoredAny = true;
+    }
+    if (restoredAny) {
+      this.element.setAttribute("data-persist-restored", "true");
+      this.dispatch("restore", { detail: { key: this.#logicalKey } });
+    }
+  }
+  /** Sets a single field's value from a stored entry. */
+  #applyValue(field, value) {
+    if (field instanceof HTMLInputElement && field.type === "checkbox") {
+      field.checked = Boolean(value);
+    } else if (field instanceof HTMLInputElement && field.type === "radio") {
+      field.checked = field.value === value;
+    } else if (field instanceof HTMLSelectElement && field.multiple) {
+      const selected = new Set(Array.isArray(value) ? value.map(String) : []);
+      for (const option of Array.from(field.options)) {
+        option.selected = selected.has(option.value);
+      }
+    } else {
+      field.value = String(value);
+    }
+  }
+  /**
+   * Persistable fields paired with a stable storage key. Uniquely-named fields key
+   * by their name (unchanged, backward-compatible). Repeated same-name fields
+   * (e.g. a `tags[]` checkbox group or array text inputs) are disambiguated by
+   * DOM-order occurrence — the first keeps its plain `name` (backward-
+   * compatible), later ones get a NUL-separated index suffix — so each is stored and
+   * restored individually instead of the last one clobbering the rest. Radios are
+   * the exception: a group intentionally shares one key (one value per name).
+   */
+  #fieldEntries() {
+    const entries = [];
+    const occurrence = /* @__PURE__ */ new Map();
+    for (const field of this.#fields()) {
+      const name = this.#keyOf(field);
+      if (name === null) continue;
+      if (field instanceof HTMLInputElement && field.type === "radio") {
+        entries.push({ field, key: name });
+        continue;
+      }
+      const seen = occurrence.get(name) ?? 0;
+      occurrence.set(name, seen + 1);
+      entries.push({ field, key: seen === 0 ? name : `${name}${OCCURRENCE_SEP}${seen}` });
+    }
+    return entries;
+  }
+  /** The fields to persist: `field` targets, or the element's named controls. */
+  #fields() {
+    const candidates = this.hasFieldTarget ? this.fieldTargets : Array.from(this.element.querySelectorAll("input, textarea, select"));
+    return candidates.filter((field) => this.#persistable(field));
+  }
+  /** Whether a field carries a restorable, non-excluded value. */
+  #persistable(field) {
+    if (this.#keyOf(field) === null) return false;
+    const type = field instanceof HTMLInputElement ? field.type : "";
+    if (NON_VALUE_TYPES.has(type)) return false;
+    if (this.excludeValue.includes(type)) return false;
+    if (field.name.length > 0 && this.excludeValue.includes(field.name)) return false;
+    return true;
+  }
+  /** A stable storage sub-key for a field (its name, else id). */
+  #keyOf(field) {
+    return field.name || field.id || null;
+  }
+  /** The logical key (key Value or element id), or null when neither is set. */
+  get #logicalKey() {
+    const key = this.keyValue || this.element.id;
+    return key.length > 0 ? key : null;
+  }
+  /** The prefixed localStorage key, or null when persistence is disabled. */
+  get #storageKey() {
+    const logical = this.#logicalKey;
+    return logical === null ? null : `${STORAGE_PREFIX}${logical}`;
+  }
+  #getItem(key) {
+    try {
+      return window.localStorage.getItem(key);
+    } catch {
+      return null;
+    }
+  }
+  #setItem(key, value) {
+    try {
+      window.localStorage.setItem(key, value);
+    } catch {
+    }
+  }
+  #removeItem(key) {
+    try {
+      window.localStorage.removeItem(key);
+    } catch {
+    }
+  }
+};
+
+export { PersistController };
+//# sourceMappingURL=persist_controller.js.map
+//# sourceMappingURL=persist_controller.js.map

data/dist/controllers/popover_controller.js

@@ -0,0 +1,94 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/popover_controller.ts
+var PopoverController = class _PopoverController extends Controller {
+  static targets = ["trigger", "panel"];
+  static actions = ["close", "open", "toggle"];
+  /** Selector for natively focusable elements used to find the first one. */
+  static #FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+  /** Starts closed and registers the document-level dismissal listeners. */
+  connect() {
+    this.close();
+    document.addEventListener("click", this.#onOutsideClick);
+    document.addEventListener("keydown", this.#onKeydown);
+  }
+  /**
+   * Removes the document-level listeners registered in {@link connect}, plus the
+   * panel's `focusout` listener if the popover is torn down while open (e.g. a
+   * Turbo navigation). `removeEventListener` is a no-op when it was never added,
+   * so this is safe in the closed state too — no listener outlives the element.
+   */
+  disconnect() {
+    document.removeEventListener("click", this.#onOutsideClick);
+    document.removeEventListener("keydown", this.#onKeydown);
+    if (this.hasPanelTarget) this.panelTarget.removeEventListener("focusout", this.#onFocusOut);
+  }
+  /** Toggles the popover. Bound via `data-action` (click on the trigger). */
+  toggle() {
+    if (this.#isOpen) {
+      this.close();
+    } else {
+      this.open();
+    }
+  }
+  /** Opens the panel, reflects state, and moves focus inside it. */
+  open() {
+    if (!this.hasPanelTarget || this.#isOpen) return;
+    this.panelTarget.hidden = false;
+    if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "true");
+    this.panelTarget.addEventListener("focusout", this.#onFocusOut);
+    this.#focusFirst();
+  }
+  /** Closes the panel and reflects the collapsed state. Bound via `data-action`. */
+  close() {
+    if (!this.hasPanelTarget) return;
+    this.panelTarget.removeEventListener("focusout", this.#onFocusOut);
+    this.panelTarget.hidden = true;
+    if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "false");
+  }
+  /** Moves focus to the first focusable element in the panel, or the panel itself. */
+  #focusFirst() {
+    const first = this.panelTarget.querySelector(_PopoverController.#FOCUSABLE);
+    if (first) {
+      first.focus();
+      return;
+    }
+    if (!this.panelTarget.hasAttribute("tabindex")) this.panelTarget.tabIndex = -1;
+    this.panelTarget.focus();
+  }
+  /** Closes and restores focus to the trigger (shared by Escape / outside click). */
+  #closeAndRestore() {
+    this.close();
+    if (this.hasTriggerTarget) this.triggerTarget.focus();
+  }
+  /** Closes (restoring focus) when a click lands outside the controller element. */
+  #onOutsideClick = (event) => {
+    if (this.#isOpen && !this.element.contains(event.target)) this.#closeAndRestore();
+  };
+  /** Closes (restoring focus) on `Escape` while open. */
+  #onKeydown = (event) => {
+    if (event.key === "Escape" && this.#isOpen) {
+      event.preventDefault();
+      this.#closeAndRestore();
+    }
+  };
+  /**
+   * Closes when focus leaves the panel for an element outside the controller
+   * (e.g. `Tab` past the last field). Focus is *not* restored — the natural
+   * destination is kept, which is the modeless contract. Moves within the
+   * controller (panel → trigger) keep it open.
+   */
+  #onFocusOut = (event) => {
+    const next = event.relatedTarget;
+    if (next && this.element.contains(next)) return;
+    this.close();
+  };
+  /** Whether the panel is currently visible. */
+  get #isOpen() {
+    return this.hasPanelTarget && !this.panelTarget.hidden;
+  }
+};
+
+export { PopoverController };
+//# sourceMappingURL=popover_controller.js.map
+//# sourceMappingURL=popover_controller.js.map

data/dist/controllers/portal_controller.js

@@ -0,0 +1,63 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/portal_controller.ts
+var portalState = /* @__PURE__ */ new WeakMap();
+var PortalController = class extends Controller {
+  static targets = ["content"];
+  static values = {
+    to: { type: String, default: "body" },
+    position: { type: String, default: "append" },
+    restore: { type: Boolean, default: true }
+  };
+  static events = ["mount", "unmount"];
+  connect() {
+    if (portalState.has(this.element)) return;
+    const node = this.hasContentTarget ? this.contentTarget : this.element;
+    const destination = this.#destination();
+    if (!destination || destination === node || node.contains(destination)) return;
+    const placeholder = document.createComment("stimeo--portal");
+    node.parentNode?.insertBefore(placeholder, node);
+    portalState.set(this.element, { node, placeholder });
+    if (this.positionValue === "prepend") {
+      destination.prepend(node);
+    } else {
+      destination.appendChild(node);
+    }
+    node.setAttribute("data-portaled", "true");
+    this.dispatch("mount", { detail: { target: destination } });
+  }
+  disconnect() {
+    if (this.element.isConnected && this.#stillControlled()) return;
+    const state = portalState.get(this.element);
+    if (!state) return;
+    portalState.delete(this.element);
+    const { node, placeholder } = state;
+    node.removeAttribute("data-portaled");
+    if (this.restoreValue && placeholder.parentNode) {
+      placeholder.parentNode.insertBefore(node, placeholder);
+    } else {
+      node.remove();
+    }
+    placeholder.remove();
+    this.dispatch("unmount", { detail: {} });
+  }
+  /** True while `data-controller` still lists this identifier (spurious-churn signal). */
+  #stillControlled() {
+    const tokens = (this.element.getAttribute("data-controller") ?? "").split(/\s+/);
+    return tokens.includes(this.identifier);
+  }
+  /** Resolves the destination for `to`, tolerating an invalid selector. */
+  #destination() {
+    const selector = this.toValue.trim();
+    if (!selector) return null;
+    try {
+      return document.querySelector(selector);
+    } catch {
+      return null;
+    }
+  }
+};
+
+export { PortalController };
+//# sourceMappingURL=portal_controller.js.map
+//# sourceMappingURL=portal_controller.js.map

data/dist/controllers/preview_guard_controller.js

@@ -0,0 +1,69 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/preview_guard_controller.ts
+var PreviewGuardController = class extends Controller {
+  static values = {
+    placeholder: { type: String, default: "" },
+    mode: { type: String, default: "hide" }
+  };
+  static events = ["hide", "show"];
+  #observer = null;
+  #hidden = false;
+  /** Saved inline visibility (hide mode), restored on show. */
+  #savedVisibility = "";
+  /** Saved text (placeholder mode); non-null marks that text — not visibility — was swapped. */
+  #savedText = null;
+  connect() {
+    if (typeof MutationObserver !== "undefined") {
+      this.#observer = new MutationObserver(() => this.#sync());
+      this.#observer.observe(document.documentElement, {
+        attributes: true,
+        attributeFilter: ["data-turbo-preview"]
+      });
+    }
+    this.#sync();
+  }
+  disconnect() {
+    this.#observer?.disconnect();
+    this.#observer = null;
+    this.#restore();
+  }
+  /** Reflects the current `data-turbo-preview` state onto the element. */
+  #sync() {
+    const previewing = document.documentElement.hasAttribute("data-turbo-preview");
+    if (previewing && !this.#hidden) this.#hide();
+    else if (!previewing && this.#hidden) this.#show();
+  }
+  #hide() {
+    this.#hidden = true;
+    if (this.modeValue === "placeholder") {
+      this.#savedText = this.element.textContent;
+      this.element.textContent = this.placeholderValue;
+    } else {
+      this.#savedVisibility = this.element.style.visibility;
+      this.element.style.visibility = "hidden";
+    }
+    this.element.setAttribute("data-preview-hidden", "true");
+    this.dispatch("hide", { detail: {} });
+  }
+  #show() {
+    this.#restore();
+    this.dispatch("show", { detail: {} });
+  }
+  /** Reverts the guard. Safe to call when not hidden (no-op) — used by show and teardown. */
+  #restore() {
+    if (!this.#hidden) return;
+    this.#hidden = false;
+    if (this.#savedText !== null) {
+      this.element.textContent = this.#savedText;
+      this.#savedText = null;
+    } else {
+      this.element.style.visibility = this.#savedVisibility;
+    }
+    this.element.removeAttribute("data-preview-hidden");
+  }
+};
+
+export { PreviewGuardController };
+//# sourceMappingURL=preview_guard_controller.js.map
+//# sourceMappingURL=preview_guard_controller.js.map

data/dist/controllers/progress_controller.js

@@ -0,0 +1,93 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/progress_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/progress_controller.ts
+var ProgressController = class extends Controller {
+  static targets = ["bar"];
+  static values = {
+    value: { type: Number, default: 0 },
+    min: { type: Number, default: 0 },
+    max: { type: Number, default: 100 },
+    indeterminate: { type: Boolean, default: false },
+    valueText: { type: String, default: "" }
+  };
+  static actions = ["setValue"];
+  static events = ["change", "complete"];
+  connect() {
+    this.#render();
+  }
+  /**
+   * Updates the progress value from an action param (`amount`) or a
+   * `detail.value` CustomEvent, normalizes it into range, syncs ARIA, and
+   * dispatches `change` (always) plus `complete` when `max` is reached.
+   */
+  setValue(event) {
+    const next = toFiniteNumber(event.params?.amount ?? event.detail?.value);
+    if (next === null) return;
+    const value = this.#clamp(next);
+    this.valueValue = value;
+    this.indeterminateValue = false;
+    this.#render();
+    this.dispatch("change", { detail: { value, ratio: this.#ratio } });
+    if (value >= this.maxValue) {
+      this.dispatch("complete", { detail: { value } });
+    }
+  }
+  /** Re-render when the indeterminate flag is toggled via its data attribute. */
+  indeterminateValueChanged() {
+    this.#render();
+  }
+  /** 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;
+  }
+  /** Reflects value/range/indeterminate onto ARIA, `data-state`, and the ratio. */
+  #render() {
+    this.element.setAttribute("aria-valuemin", String(this.minValue));
+    this.element.setAttribute("aria-valuemax", String(this.maxValue));
+    if (this.indeterminateValue) {
+      this.element.removeAttribute("aria-valuenow");
+      this.element.removeAttribute("aria-valuetext");
+      this.element.style.removeProperty("--stimeo-progress-ratio");
+      this.element.setAttribute("data-state", "indeterminate");
+      return;
+    }
+    const value = this.#clamp(this.valueValue);
+    this.element.setAttribute("aria-valuenow", String(value));
+    this.element.style.setProperty("--stimeo-progress-ratio", String(this.#ratio));
+    this.element.setAttribute("data-state", "determinate");
+    this.#applyValueText(value);
+  }
+  /**
+   * Sets `aria-valuetext` from the consumer-provided template, substituting
+   * `{value}` and `{percent}`. Left to the consumer so the human-readable text
+   * stays 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));
+    this.element.setAttribute("aria-valuetext", text);
+  }
+};
+
+export { ProgressController };
+//# sourceMappingURL=progress_controller.js.map
+//# sourceMappingURL=progress_controller.js.map