stimeo-ui 0.16.0 → 0.17.0

data/dist/controllers/step_indicator_controller.js

@@ -1,28 +1,32 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/step_indicator_controller.ts
+var ListenerSet = class {
+  #abort = new AbortController();
+  add(target, type, handler, options) {
+    target.addEventListener(type, handler, { ...options, signal: this.#abort.signal });
+  }
+  dispose() {
+    this.#abort.abort();
+    this.#abort = new AbortController();
+  }
+};
 
-// src/utils/microtask_coalescer.ts
 var MicrotaskCoalescer = class {
   #run;
   #queued = false;
   #active = false;
   #generation = 0;
-  /** @param run - the single reconciliation pass, invoked at most once per batch. */
   constructor(run) {
     this.#run = run;
   }
-  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
   activate() {
     this.#active = true;
   }
-  /** Closes the window and drops any pending pass; call from `disconnect()`. */
   cancel() {
     this.#active = false;
     this.#queued = false;
     this.#generation += 1;
   }
-  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
   schedule() {
     if (!this.#active || this.#queued) return;
     this.#queued = true;
@@ -35,52 +39,108 @@ var MicrotaskCoalescer = class {
   }
 };
 
-// src/controllers/step_indicator_controller.ts
-var StepIndicatorController = class extends Controller {
+var MorphRenderWatcher = class {
+  #listeners = new ListenerSet();
+  #pass;
+  #element = null;
+  #onMorph = () => this.#pass.schedule();
+  constructor(run) {
+    this.#pass = new MicrotaskCoalescer(run);
+  }
+  observe(element) {
+    if (this.#element === element) return;
+    this.disconnect();
+    this.#element = element;
+    this.#pass.activate();
+    this.#listeners.add(element, "turbo:morph-element", this.#onMorph);
+  }
+  schedule() {
+    this.#pass.schedule();
+  }
+  disconnect() {
+    this.#listeners.dispose();
+    this.#pass.cancel();
+    this.#element = null;
+  }
+};
+
+var NUMBER_BOUNDS = {
+  finite: { finite: true }};
+function matchesNumberBounds(value, bounds) {
+  if (!Number.isFinite(value)) {
+    const direction = value === Infinity ? "positive" : value === -Infinity ? "negative" : null;
+    if (direction === null) return false;
+    if (bounds.allowInfinity !== "both" && bounds.allowInfinity !== direction) return false;
+  }
+  if (bounds.min !== void 0 && value < bounds.min) return false;
+  if (bounds.max !== void 0 && value > bounds.max) return false;
+  if (bounds.exclusiveMin !== void 0 && value <= bounds.exclusiveMin) return false;
+  if (bounds.integer && !Number.isInteger(value)) return false;
+  if (bounds.allowedValues !== void 0 && !bounds.allowedValues.includes(value)) return false;
+  return true;
+}
+
+function readNumber(raw, fallback, bounds) {
+  return matchesNumberBounds(raw, bounds) ? raw : fallback;
+}
+
+var NumberValueReader = class {
+  #lastRejected = /* @__PURE__ */ new Map();
+  read(owner, name, raw, fallback, bounds) {
+    const resolved = readNumber(raw, fallback, bounds);
+    if (matchesNumberBounds(raw, bounds)) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    const attribute = `data-${owner.identifier}-${name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}-value`;
+    const literal = owner.element.getAttribute(attribute);
+    if (literal === null) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    if (this.#lastRejected.get(name) !== literal) {
+      this.#lastRejected.set(name, literal);
+      console.warn(
+        `Stimeo UI: "${owner.identifier}" has an invalid number Value "${name}" declaration ${JSON.stringify(literal)}; using ${fallback}.`
+      );
+    }
+    return resolved;
+  }
+};
+
+var StepIndicatorController = class _StepIndicatorController extends Controller {
+  #numbers = new NumberValueReader();
   static targets = ["step"];
   static values = {
     index: { type: Number, default: 0 }
   };
+  static valueConstraints = {
+    index: NUMBER_BOUNDS.finite
+  };
   static actions = ["setIndex"];
   static events = ["change"];
-  /**
-   * Collapses a batch of step callbacks — and a morph that swaps `index` with
-   * them — into one repaint. Replacing a list of N steps delivers N callbacks, and
-   * each one would otherwise rewrite every step's state.
-   */
-  #repaint = new MicrotaskCoalescer(() => this.#render());
-  /** Renders the initial state from the `index` value. */
+  #repaint = new MorphRenderWatcher(() => this.#render());
   connect() {
-    this.#repaint.activate();
+    this.#repaint.observe(this.element);
     this.#render();
   }
-  /** Closes the window in which a queued repaint may still run. */
   disconnect() {
-    this.#repaint.cancel();
+    this.#repaint.disconnect();
   }
-  /** Syncs a step appended or replaced at runtime (the consumer owns the list). */
   stepTargetConnected() {
     this.#repaint.schedule();
   }
-  /** Re-derives the remaining steps when one is removed at runtime. */
   stepTargetDisconnected() {
     this.#repaint.schedule();
   }
-  /** Repaints when application code (or a Turbo morph) changes `index` at runtime. */
   indexValueChanged() {
     this.#repaint.schedule();
   }
-  /**
-   * Moves the indicator from an external event (`detail.index`, 0-based) and
-   * dispatches `change`. Out-of-range positions are clamped to the step set,
-   * and both sides of the no-op test are clamped, so moving onto the step an
-   * out-of-range `index` already renders is not reported as a change.
-   */
   setIndex(event) {
     const next = event.detail?.index;
     if (typeof next !== "number" || !Number.isFinite(next)) return;
     const clamped = this.#clamp(next);
-    const previous = this.#clamp(this.indexValue);
+    const previous = this.#clamp(this.#safeIndex);
     const moved = clamped !== previous;
     this.indexValue = clamped;
     if (!moved) return;
@@ -89,18 +149,9 @@ var StepIndicatorController = class extends Controller {
       detail: { index: clamped, previous, total: this.stepTargets.length }
     });
   }
-  /**
-   * Applies `data-state`, `aria-current`, and the progress ratio custom property.
-   *
-   * A pure function of the step set and `index`, so running it again writes the
-   * same values — which is what lets the action path paint synchronously (the event
-   * goes out after the DOM is updated) while a coalesced pass may still follow.
-   *
-   * @stimeoRenderRoot
-   */
   #render() {
     const total = this.stepTargets.length;
-    const current = this.#clamp(this.indexValue);
+    const current = this.#clamp(this.#safeIndex);
     this.stepTargets.forEach((step, index) => {
       step.dataset.state = index < current ? "complete" : index === current ? "current" : "upcoming";
       if (index === current) {
@@ -112,19 +163,21 @@ var StepIndicatorController = class extends Controller {
     const ratio = total > 1 ? current / (total - 1) : 0;
     this.element.style.setProperty("--stimeo--step-indicator-ratio", String(ratio));
   }
-  /**
-   * Constrains an index to `[0, total-1]` (or `0` when there are no steps). A
-   * non-finite index falls back to the first step: `index` is read from markup,
-   * so an unparsable attribute arrives as `NaN` and would otherwise propagate
-   * into every state hook.
-   */
   #clamp(index) {
     const last = this.stepTargets.length - 1;
-    if (last < 0 || !Number.isFinite(index)) return 0;
+    if (last < 0) return 0;
     return Math.min(last, Math.max(0, Math.trunc(index)));
   }
+  get #safeIndex() {
+    return this.#numbers.read(
+      this,
+      "index",
+      this.indexValue,
+      _StepIndicatorController.values.index.default,
+      _StepIndicatorController.valueConstraints.index
+    );
+  }
 };
 
 export { StepIndicatorController };
-//# sourceMappingURL=step_indicator_controller.js.map
 //# sourceMappingURL=step_indicator_controller.js.map

data/dist/controllers/stepper_controller.js

@@ -1,28 +1,58 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/stepper_controller.ts
+var NUMBER_BOUNDS = {
+  finite: { finite: true }};
+function matchesNumberBounds(value, bounds) {
+  if (!Number.isFinite(value)) {
+    const direction = value === Infinity ? "positive" : value === -Infinity ? "negative" : null;
+    if (direction === null) return false;
+    if (bounds.allowInfinity !== "both" && bounds.allowInfinity !== direction) return false;
+  }
+  if (bounds.min !== void 0 && value < bounds.min) return false;
+  if (bounds.max !== void 0 && value > bounds.max) return false;
+  if (bounds.exclusiveMin !== void 0 && value <= bounds.exclusiveMin) return false;
+  if (bounds.integer && !Number.isInteger(value)) return false;
+  if (bounds.allowedValues !== void 0 && !bounds.allowedValues.includes(value)) return false;
+  return true;
+}
+
+function toFiniteNumber(raw) {
+  if (typeof raw !== "number" && typeof raw !== "string") return null;
+  if (typeof raw === "string" && raw.trim().length === 0) return null;
+  const value = Number(raw);
+  return Number.isFinite(value) ? value : null;
+}
+function readNumber(raw, fallback, bounds) {
+  return matchesNumberBounds(raw, bounds) ? raw : fallback;
+}
+
+var ListenerSet = class {
+  #abort = new AbortController();
+  add(target, type, handler, options) {
+    target.addEventListener(type, handler, { ...options, signal: this.#abort.signal });
+  }
+  dispose() {
+    this.#abort.abort();
+    this.#abort = new AbortController();
+  }
+};
 
-// src/utils/microtask_coalescer.ts
 var MicrotaskCoalescer = class {
   #run;
   #queued = false;
   #active = false;
   #generation = 0;
-  /** @param run - the single reconciliation pass, invoked at most once per batch. */
   constructor(run) {
     this.#run = run;
   }
-  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
   activate() {
     this.#active = true;
   }
-  /** Closes the window and drops any pending pass; call from `disconnect()`. */
   cancel() {
     this.#active = false;
     this.#queued = false;
     this.#generation += 1;
   }
-  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
   schedule() {
     if (!this.#active || this.#queued) return;
     this.#queued = true;
@@ -35,95 +65,113 @@ var MicrotaskCoalescer = class {
   }
 };
 
-// src/controllers/stepper_controller.ts
-var StepperController = class extends Controller {
+var MorphRenderWatcher = class {
+  #listeners = new ListenerSet();
+  #pass;
+  #element = null;
+  #onMorph = () => this.#pass.schedule();
+  constructor(run) {
+    this.#pass = new MicrotaskCoalescer(run);
+  }
+  observe(element) {
+    if (this.#element === element) return;
+    this.disconnect();
+    this.#element = element;
+    this.#pass.activate();
+    this.#listeners.add(element, "turbo:morph-element", this.#onMorph);
+  }
+  schedule() {
+    this.#pass.schedule();
+  }
+  disconnect() {
+    this.#listeners.dispose();
+    this.#pass.cancel();
+    this.#element = null;
+  }
+};
+
+var NumberValueReader = class {
+  #lastRejected = /* @__PURE__ */ new Map();
+  read(owner, name, raw, fallback, bounds) {
+    const resolved = readNumber(raw, fallback, bounds);
+    if (matchesNumberBounds(raw, bounds)) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    const attribute = `data-${owner.identifier}-${name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}-value`;
+    const literal = owner.element.getAttribute(attribute);
+    if (literal === null) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    if (this.#lastRejected.get(name) !== literal) {
+      this.#lastRejected.set(name, literal);
+      console.warn(
+        `Stimeo UI: "${owner.identifier}" has an invalid number Value "${name}" declaration ${JSON.stringify(literal)}; using ${fallback}.`
+      );
+    }
+    return resolved;
+  }
+};
+
+var StepperController = class _StepperController extends Controller {
+  #numbers = new NumberValueReader();
   static targets = ["step"];
   static values = {
     index: { type: Number, default: 0 },
     linear: { type: Boolean, default: false }
   };
+  static valueConstraints = {
+    index: NUMBER_BOUNDS.finite
+  };
   static actions = ["goto", "next", "prev"];
   static events = ["change", "reconcile"];
-  /**
-   * Collapses the Value and target callbacks of one mutation into one pass, and
-   * refuses the ones Stimulus delivers before `connect()`, which renders itself.
-   */
-  #repaint = new MicrotaskCoalescer(() => this.#reconcileStep());
-  /**
-   * The position shown current last, which the next move is measured from, or
-   * `null` before any step has been shown. While no step is present it keeps the
-   * last one.
-   */
+  #repaint = new MorphRenderWatcher(() => this.#reconcileStep());
   #shown = null;
-  /** Renders the initial state from `index`, clamped into the step range. */
   connect() {
-    this.#repaint.activate();
+    this.#repaint.observe(this.element);
     this.#shown = this.#currentStep;
     this.#render();
   }
-  /** Drops a pending pass, so nothing renders or reports for a stepper that left. */
   disconnect() {
-    this.#repaint.cancel();
+    this.#repaint.disconnect();
   }
-  /** Re-renders when Turbo Morph or application code changes `index` at runtime. */
   indexValueChanged() {
     this.#repaint.schedule();
   }
-  /** Re-derives every step's state for a step added at runtime. */
   stepTargetConnected() {
     this.#repaint.schedule();
   }
-  /** Re-derives every step's state for a step removed at runtime. */
   stepTargetDisconnected() {
     this.#repaint.schedule();
   }
-  /** Advances to the next step (ignored at the last step). */
   next() {
-    this.#moveTo(this.#clampIndex(this.indexValue) + 1);
+    this.#moveTo(this.#clampIndex(this.#safeIndex) + 1);
   }
-  /** Returns to the previous step (ignored at the first step). */
   prev() {
-    this.#moveTo(this.#clampIndex(this.indexValue) - 1);
+    this.#moveTo(this.#clampIndex(this.#safeIndex) - 1);
   }
-  /**
-   * Jumps to the step carried in the action's `index` param. A param that is empty,
-   * or that Stimulus parses into anything but a number or a string, is no index,
-   * so it jumps nowhere.
-   */
   goto(event) {
     const { index } = event.params;
-    if (index === "") return;
-    if (typeof index !== "number" && typeof index !== "string") return;
-    const target = Number(index);
-    if (!Number.isFinite(target) || !Number.isInteger(target)) return;
+    const target = toFiniteNumber(index);
+    if (target === null || !Number.isInteger(target)) return;
     this.#moveTo(target);
   }
-  /**
-   * Moves the current step to `target` when allowed: in range, not a no-op, and
-   * — under `linear` — not skipping more than one step ahead. Re-renders and
-   * dispatches `change`.
-   */
   #moveTo(target) {
     const total = this.stepTargets.length;
-    if (!Number.isFinite(target) || !Number.isInteger(target)) return;
     if (target < 0 || target >= total) return;
-    const current = this.#clampIndex(this.indexValue);
-    if (target === current) return;
+    const current = this.#clampIndex(this.#safeIndex);
+    if (target === current && target === this.#shown) return;
     if (this.linearValue && target > current + 1) return;
-    const previous = current;
+    const previous = this.#shown ?? current;
     this.indexValue = target;
     this.#shown = target;
     this.#render();
+    if (target === previous) return;
     this.dispatch("change", {
       detail: { index: target, previous, total, step: this.stepTargets[target] }
     });
   }
-  /**
-   * Re-derives one settled batch of Value and target changes, and reports a
-   * current position that moved from the one shown before as `reconcile`. With no
-   * step present there is nothing to report, and the position shown last stays the
-   * one the next move is measured from.
-   */
   #reconcileStep() {
     const previous = this.#shown;
     const index = this.#currentStep;
@@ -135,25 +183,11 @@ var StepperController = class extends Controller {
       detail: { index, previous, total: steps.length, step: steps[index] }
     });
   }
-  /** The current position, clamped into the step range, or `null` when there is no step. */
   get #currentStep() {
-    return this.stepTargets.length > 0 ? this.#clampIndex(this.indexValue) : null;
-  }
-  /**
-   * Derives each step's `data-state` and the current button's `aria-current` from
-   * `index`, clamped into the step range, without dispatching an action event.
-   *
-   * The clamp decides only what is shown. This body never writes `index`, so an
-   * out-of-range declaration stays in the attribute as the page wrote it.
-   *
-   * `aria-current="step"` is placed on the step's **first** `<button>`; the markup
-   * contract assumes one operable button per step. If a step needs multiple
-   * buttons, mark the navigational one first (or this would target the wrong one).
-   *
-   * @stimeoRenderRoot
-   */
+    return this.stepTargets.length > 0 ? this.#clampIndex(this.#safeIndex) : null;
+  }
   #render() {
-    const current = this.#clampIndex(this.indexValue);
+    const current = this.#clampIndex(this.#safeIndex);
     this.stepTargets.forEach((step, index) => {
       step.dataset.state = index < current ? "complete" : index === current ? "current" : "upcoming";
       const button = step.querySelector("button");
@@ -165,14 +199,21 @@ var StepperController = class extends Controller {
       }
     });
   }
-  /** Constrains an index to `[0, total-1]` (or `0` when there are no steps). */
   #clampIndex(index) {
     const last = this.stepTargets.length - 1;
-    if (last < 0 || !Number.isFinite(index)) return 0;
+    if (last < 0) return 0;
     return Math.min(last, Math.max(0, Math.trunc(index)));
   }
+  get #safeIndex() {
+    return this.#numbers.read(
+      this,
+      "index",
+      this.indexValue,
+      _StepperController.values.index.default,
+      _StepperController.valueConstraints.index
+    );
+  }
 };
 
 export { StepperController };
-//# sourceMappingURL=stepper_controller.js.map
 //# sourceMappingURL=stepper_controller.js.map