stimeo-ui 0.15.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,71 +39,119 @@ 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 = {
-    current: { type: Number, default: 0 }
+    index: { type: Number, default: 0 }
   };
-  static actions = ["setCurrent"];
+  static valueConstraints = {
+    index: NUMBER_BOUNDS.finite
+  };
+  static actions = ["setIndex"];
   static events = ["change"];
-  /**
-   * Collapses a batch of step callbacks — and a morph that swaps `current` 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 `current` 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 `current` at runtime. */
-  currentValueChanged() {
+  indexValueChanged() {
     this.#repaint.schedule();
   }
-  /**
-   * Updates the current step from an external event (`detail.current`, 0-based)
-   * and dispatches `change`. Out-of-range indices 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 `current` already renders is not reported as a change.
-   */
-  setCurrent(event) {
-    const next = event.detail?.current;
+  setIndex(event) {
+    const next = event.detail?.index;
     if (typeof next !== "number" || !Number.isFinite(next)) return;
     const clamped = this.#clamp(next);
-    const moved = clamped !== this.#clamp(this.currentValue);
-    this.currentValue = clamped;
+    const previous = this.#clamp(this.#safeIndex);
+    const moved = clamped !== previous;
+    this.indexValue = clamped;
     if (!moved) return;
     this.#render();
     this.dispatch("change", {
-      detail: { current: clamped, total: this.stepTargets.length }
+      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 `current`, 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.currentValue);
+    const current = this.#clamp(this.#safeIndex);
     this.stepTargets.forEach((step, index) => {
       step.dataset.state = index < current ? "complete" : index === current ? "current" : "upcoming";
       if (index === current) {
@@ -111,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: `current` 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,77 +1,193 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/stepper_controller.ts
-var StepperController = class extends Controller {
+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();
+  }
+};
+
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  constructor(run) {
+    this.#run = run;
+  }
+  activate() {
+    this.#active = true;
+  }
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  schedule() {
+    if (!this.#active || this.#queued) return;
+    this.#queued = true;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
+  }
+};
+
+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"];
-  #isConnected = false;
-  /** Normalizes an out-of-range initial `index` and renders the initial state. */
+  static events = ["change", "reconcile"];
+  #repaint = new MorphRenderWatcher(() => this.#reconcileStep());
+  #shown = null;
   connect() {
-    this.#isConnected = true;
-    this.#normalizeAndRender();
+    this.#repaint.observe(this.element);
+    this.#shown = this.#currentStep;
+    this.#render();
   }
   disconnect() {
-    this.#isConnected = false;
+    this.#repaint.disconnect();
   }
-  /** Re-renders when Turbo Morph or application code changes `index` at runtime. */
   indexValueChanged() {
-    if (!this.#isConnected) return;
-    this.#normalizeAndRender();
+    this.#repaint.schedule();
+  }
+  stepTargetConnected() {
+    this.#repaint.schedule();
+  }
+  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. */
   goto(event) {
-    const target = Number(event.params.index);
-    if (!Number.isFinite(target) || !Number.isInteger(target)) return;
+    const { index } = event.params;
+    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.#render(target);
+    this.#shown = target;
+    this.#render();
+    if (target === previous) return;
     this.dispatch("change", {
-      detail: { index: target, previous, step: this.stepTargets[target] }
+      detail: { index: target, previous, total, step: this.stepTargets[target] }
     });
   }
-  /** Normalizes the public Value and reflects it without dispatching an action event. */
-  #normalizeAndRender() {
-    const normalized = this.#clampIndex(this.indexValue);
-    if (!Object.is(normalized, this.indexValue)) this.indexValue = normalized;
-    this.#render(normalized);
-  }
-  /**
-   * Derives each step's `data-state` and the current button's `aria-current`.
-   *
-   * `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
-   */
-  #render(current) {
+  #reconcileStep() {
+    const previous = this.#shown;
+    const index = this.#currentStep;
+    if (index !== null) this.#shown = index;
+    this.#render();
+    if (index === null || previous === null || index === previous) return;
+    const steps = this.stepTargets;
+    this.dispatch("reconcile", {
+      detail: { index, previous, total: steps.length, step: steps[index] }
+    });
+  }
+  get #currentStep() {
+    return this.stepTargets.length > 0 ? this.#clampIndex(this.#safeIndex) : null;
+  }
+  #render() {
+    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");
@@ -83,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