stimeo-ui 0.4.0 → 0.6.0

data/dist/controllers/carousel_controller.js

@@ -20,6 +20,39 @@ function isReservedArrowChord(event, allow = []) {
   return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
 }
 
+// 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;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
+  }
+};
+
 // src/utils/roving_tabindex.ts
 var RovingTabindex = class {
   /** Returns the current ordered item elements; called on every operation. */
@@ -42,10 +75,12 @@ var RovingTabindex = class {
    * "nothing is currently tabbable".
    *
    * @param index - Position of the item to make tabbable.
-   * @param options - Pass `{ focus: true }` to also move DOM focus to that item.
+   * @param options - Pass `{ focus: true }` to also move DOM focus to that item,
+   *   and `items` to reuse an event-scoped collection snapshot.
    */
-  setActive(index, { focus = false } = {}) {
-    const items = this.#getItems();
+  setActive(index, options = {}) {
+    const { focus = false } = options;
+    const items = options.items ?? this.#getItems();
     items.forEach((item, i) => {
       item.tabIndex = i === index ? 0 : -1;
     });
@@ -120,9 +155,14 @@ var CarouselController = class extends Controller {
     "resume",
     "togglePlay"
   ];
-  static events = ["change", "pause", "play"];
+  static events = ["change", "pause", "play", "reconcile"];
   #roving = new RovingTabindex(() => this.pickerTargets);
-  /** Gates the target callback so it does not repaint once per authored picker on mount. */
+  #reconcileTargets = new MicrotaskCoalescer(() => this.#reconcileTargetSet());
+  /**
+   * Whether `connect()` has run. Scheduling is already inert outside that window
+   * ({@link MicrotaskCoalescer}), so this only gates the Tab stop a picker
+   * present at mount authored for itself.
+   */
   #connected = false;
   #intervals = new SafeInterval();
   /** Index of the visible slide. */
@@ -148,6 +188,7 @@ var CarouselController = class extends Controller {
     this.#render({ focus: false });
     this.#syncTimer();
     this.#connected = true;
+    this.#reconcileTargets.activate();
   }
   /**
    * Re-establishes the single selected picker when one is added after connect.
@@ -158,9 +199,22 @@ var CarouselController = class extends Controller {
    * repaint re-derives every picker from `#index`, so a late arrival never steals
    * the selection.
    */
-  pickerTargetConnected() {
+  pickerTargetConnected(picker) {
     if (!this.#connected) return;
-    this.#render({ focus: false });
+    picker.tabIndex = -1;
+    this.#reconcileTargets.schedule();
+  }
+  /** Repairs selection and roving after a picker leaves a retained carousel. */
+  pickerTargetDisconnected() {
+    this.#reconcileTargets.schedule();
+  }
+  /** Reconciles a slide added in the same DOM batch as its picker. */
+  slideTargetConnected() {
+    this.#reconcileTargets.schedule();
+  }
+  /** Re-clamps the active index after a slide is removed. */
+  slideTargetDisconnected() {
+    this.#reconcileTargets.schedule();
   }
   /**
    * Resolves the starting autoplay intent. The play toggle's `aria-pressed` is the
@@ -178,6 +232,7 @@ var CarouselController = class extends Controller {
   /** Clears the autoplay interval so it never fires after teardown. */
   disconnect() {
     this.#connected = false;
+    this.#reconcileTargets.cancel();
     this.#intervals.clearAll();
     this.#timerId = null;
   }
@@ -271,17 +326,42 @@ var CarouselController = class extends Controller {
     this.#syncTimer();
     if (changed) this.dispatch("change", { detail: { index, total: this.slideTargets.length } });
   }
-  /** Reflects `this.#index` onto slides and pickers (state hooks + roving). */
+  /**
+   * Reflects `this.#index` onto slides and pickers (state hooks + roving).
+   *
+   * @stimeoRenderRoot
+   */
   #render({ focus }) {
     this.slideTargets.forEach((slide, i) => {
       const active = i === this.#index;
       slide.setAttribute("data-state", active ? "active" : "inactive");
       slide.hidden = !active;
     });
+    const pickerIndex = Math.min(this.#index, this.pickerTargets.length - 1);
     this.pickerTargets.forEach((picker, i) => {
-      picker.setAttribute("aria-selected", i === this.#index ? "true" : "false");
+      picker.setAttribute("aria-selected", i === pickerIndex ? "true" : "false");
     });
-    this.#roving.setActive(this.#index, { focus });
+    this.#roving.setActive(pickerIndex, { focus });
+  }
+  /** Keeps the live active slide when possible and otherwise selects the nearest survivor. */
+  #reconcileTargetSet() {
+    const activeSlide = this.slideTargets.findIndex(
+      (slide) => slide.getAttribute("data-state") === "active"
+    );
+    const selectedPicker = this.pickerTargets.findIndex(
+      (picker) => picker.getAttribute("aria-selected") === "true"
+    );
+    const lastSlide = this.slideTargets.length - 1;
+    const candidate = activeSlide !== -1 ? activeSlide : selectedPicker !== -1 ? selectedPicker : this.#index;
+    const previous = this.#index;
+    this.#index = lastSlide < 0 ? 0 : Math.min(lastSlide, Math.max(0, candidate));
+    this.#render({ focus: false });
+    this.#syncTimer();
+    if (this.#index !== previous) {
+      this.dispatch("reconcile", {
+        detail: { index: this.#index, total: this.slideTargets.length }
+      });
+    }
   }
   /**
    * Drives the autoplay interval toward the desired state. Autoplay should run

data/dist/controllers/checkbox_controller.js

@@ -1,17 +1,89 @@
 import { Controller } from '@hotwired/stimulus';
 
+// src/controllers/checkbox_controller.ts
+
+// 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;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
+  }
+};
+
 // src/controllers/checkbox_controller.ts
 var CheckboxController = class extends Controller {
   static targets = ["parent", "child"];
   static actions = ["onChildChange", "onParentChange"];
-  static events = ["change"];
-  /** Reflects the initial aggregate (e.g. from server-rendered child states). */
-  connect() {
-    if (this.childTargets.length > 0) {
-      this.#syncFromChildren(false);
-    } else {
-      this.element.setAttribute("data-state", this.#aggregate());
+  static events = ["change", "reconcile"];
+  /** Collapses every lifecycle signal from one DOM update into one derived pass. */
+  #reconcile = new MicrotaskCoalescer(() => this.#reconcileFromChildren());
+  /** Aggregate this root last settled on, so a derived repair is reported once. */
+  #committedState = null;
+  /** Watches authored checked-attribute changes on retained target elements. */
+  #checkedObserver = new MutationObserver((records) => {
+    if (records.some((record) => this.#isManagedCheckbox(record.target))) {
+      this.#reconcile.schedule();
     }
+  });
+  /** Reflects the initial aggregate and starts retained-DOM reconciliation. */
+  connect() {
+    this.#reconcile.activate();
+    this.#syncFromChildren();
+    this.#checkedObserver.observe(this.element, {
+      attributes: true,
+      attributeFilter: ["checked"],
+      subtree: true
+    });
+    this.element.addEventListener("turbo:morph-element", this.#onMorph);
+    document.addEventListener("reset", this.#onReset, true);
+  }
+  /** Releases the observer, global reset listener, and every pending reconciliation. */
+  disconnect() {
+    this.#reconcile.cancel();
+    this.#checkedObserver.disconnect();
+    this.element.removeEventListener("turbo:morph-element", this.#onMorph);
+    document.removeEventListener("reset", this.#onReset, true);
+  }
+  /** Reconciles the aggregate for a parent added or replaced at runtime. */
+  parentTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /** Reconciles the aggregate after a parent target leaves the group. */
+  parentTargetDisconnected() {
+    this.#reconcile.schedule();
+  }
+  /** Reconciles the aggregate for a child added at runtime. */
+  childTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /** Reconciles the aggregate after a child leaves the group. */
+  childTargetDisconnected() {
+    this.#reconcile.schedule();
   }
   /** Cascades the parent's state to every child. Bound via `data-action` (change). */
   onParentChange() {
@@ -20,35 +92,74 @@ var CheckboxController = class extends Controller {
     for (const child of this.childTargets) {
       child.checked = checked;
     }
-    this.parentTarget.indeterminate = false;
-    const state = checked ? "all" : "none";
-    this.element.setAttribute("data-state", state);
-    this.dispatch("change", { detail: { checked, indeterminate: false, state } });
+    this.#reflect(checked ? "all" : "none", true);
+    const detail = this.#settledDetail();
+    if (detail) this.dispatch("change", { detail });
   }
   /** Recomputes the parent from its children. Bound via `data-action` (change). */
   onChildChange() {
-    this.#syncFromChildren(true);
+    this.#syncFromChildren();
+    const detail = this.#settledDetail();
+    if (detail) this.dispatch("change", { detail });
+  }
+  /**
+   * Announces an aggregate this pass derived rather than the user. `change` stays
+   * reserved for the two public actions, so automation never reads a repair as an edit.
+   */
+  #reconcileFromChildren() {
+    const previous = this.#committedState;
+    this.#syncFromChildren();
+    if (this.#committedState === previous) return;
+    const detail = this.#settledDetail();
+    if (detail) this.dispatch("reconcile", { detail });
   }
   /**
    * Derives the parent's `checked`/`indeterminate` and the root `data-state` from
-   * the children, optionally dispatching `change`.
+   * the children. Writing state and reporting it are separate so the caller — not
+   * a flag threaded through the write — decides which event describes the cause.
    */
-  #syncFromChildren(dispatch) {
-    const state = this.#aggregate();
-    if (this.hasParentTarget) {
+  #syncFromChildren() {
+    this.#reflect(this.#aggregate(), this.childTargets.length > 0);
+  }
+  /**
+   * Reflects one aggregate state.
+   *
+   * @param writeParent - whether the state is authoritative over the `parent`
+   * target's own `checked` / `indeterminate`.
+   */
+  #reflect(state, writeParent) {
+    if (writeParent && this.hasParentTarget) {
       this.parentTarget.checked = state === "all";
       this.parentTarget.indeterminate = state === "partial";
     }
     this.element.setAttribute("data-state", state);
-    if (dispatch) {
-      this.dispatch("change", {
-        detail: {
-          checked: this.hasParentTarget ? this.parentTarget.checked : state === "all",
-          indeterminate: this.hasParentTarget ? this.parentTarget.indeterminate : false,
-          state
-        }
-      });
-    }
+    this.#committedState = state;
+  }
+  /** The settled aggregate as event detail, or `null` before anything has settled. */
+  #settledDetail() {
+    const state = this.#committedState;
+    if (state === null) return null;
+    return { checked: state === "all", indeterminate: state === "partial", state };
+  }
+  /** Reconciles retained targets after Turbo has finished morphing their live state. */
+  #onMorph = () => {
+    this.#reconcile.schedule();
+  };
+  /** Reconciles after a non-cancelled reset restores any managed checkbox. */
+  #onReset = (event) => {
+    const form = event.target;
+    if (!(form instanceof HTMLFormElement) || !this.#hasCheckboxOwnedBy(form)) return;
+    queueMicrotask(() => {
+      if (!event.defaultPrevented) this.#reconcile.schedule();
+    });
+  };
+  /** Whether a form owns at least one current parent or child target. */
+  #hasCheckboxOwnedBy(form) {
+    return [...this.parentTargets, ...this.childTargets].some((checkbox) => checkbox.form === form);
+  }
+  /** Whether an observed attribute mutation belongs to this controller's target set. */
+  #isManagedCheckbox(node) {
+    return this.parentTargets.some((checkbox) => checkbox === node) || this.childTargets.some((checkbox) => checkbox === node);
   }
   /**
    * Computes the aggregate state. With children it counts them; with none it

data/dist/controllers/clipboard_controller.js

@@ -2,6 +2,13 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/clipboard_controller.ts
 
+// src/utils/default_attribute.ts
+function setDefaultAttribute(element, name, value) {
+  if (element.hasAttribute(name)) return false;
+  element.setAttribute(name, value);
+  return true;
+}
+
 // src/utils/safe_timeout.ts
 var TimerRegistry = class {
   /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
@@ -75,9 +82,7 @@ var ClipboardController = class extends Controller {
    */
   #resetTimerId = null;
   connect() {
-    if (!this.element.hasAttribute("data-state")) {
-      this.element.setAttribute("data-state", "idle");
-    }
+    setDefaultAttribute(this.element, "data-state", "idle");
   }
   disconnect() {
     this.#timers.clearAll();

data/dist/controllers/collapsible_controller.js

@@ -297,7 +297,10 @@ var CollapsibleController = class extends Controller {
   #applyContent(content, open, waitForCloseTransition) {
     if (open) {
       content.hidden = false;
-      content.style.setProperty("--stimeo-collapsible-content-height", `${content.scrollHeight}px`);
+      content.style.setProperty(
+        "--stimeo--collapsible-content-height",
+        `${content.scrollHeight}px`
+      );
       content.setAttribute("data-state", "open");
       return;
     }

data/dist/controllers/color_picker_controller.js

@@ -59,7 +59,7 @@ var MicrotaskCoalescer = class {
 };
 
 // src/controllers/color_picker_controller.ts
-var COLOR_PROPERTY = "--stimeo-color";
+var COLOR_PROPERTY = "--stimeo--color";
 var CHANNEL_RANGE = {
   hue: [0, 360],
   saturation: [0, 100],
@@ -74,7 +74,7 @@ var ColorPickerController = class extends Controller {
     logicalTrack: { type: Boolean, default: false }
   };
   static actions = ["onHexInput", "onKeydown", "onPointerDown"];
-  static events = ["change"];
+  static events = ["change", "reconcile"];
   /** Whether the consumer declared a mirroring track and the direction mirrors it. */
   get #mirrored() {
     return this.logicalTrackValue && isRtl(this.element);
@@ -83,14 +83,14 @@ var ColorPickerController = class extends Controller {
   #color = { hue: 0, saturation: 0, lightness: 0, alpha: 100 };
   /** Aborts in-progress pointer-drag listeners on drag end / teardown. */
   #dragAbort = null;
-  /** Seeds the model from the initial hex value and renders every surface. */
+  /** Color the last repaint settled on, so a configuration-driven move is reported once. */
+  #committedHex = null;
   /**
    * Collapses a morph that swaps render inputs into one repaint, and refuses the
    * pass Stimulus delivers before `connect()`.
    */
-  #repaint = new MicrotaskCoalescer(() => {
-    this.#render();
-  });
+  #repaint = new MicrotaskCoalescer(() => this.#reconcileColor());
+  /** Seeds the model from the initial hex value and renders every surface. */
   connect() {
     this.#repaint.activate();
     const parsed = hexToHsla(this.valueValue);
@@ -181,14 +181,30 @@ var ColorPickerController = class extends Controller {
       return;
     }
     this.#color = this.alphaValue ? parsed : { ...parsed, alpha: 100 };
-    this.#render();
+    this.#commitColor();
   }
   /** Clamps and snaps one channel to an integer, then re-renders + emits change. */
   #setChannel(channel, raw, min, max) {
     this.#color[channel] = Math.round(Math.min(max, Math.max(min, raw)));
+    this.#commitColor();
+  }
+  /**
+   * Renders the model and reports a color the user actually moved. A key pressed
+   * at a bound, a pointer that lands on the step already showing, and a re-confirmed
+   * hex all leave the committed color where it was, so no `change` describes them.
+   */
+  #commitColor() {
+    const previous = this.#committedHex;
     this.#render();
+    if (this.#committedHex !== previous) {
+      this.dispatch("change", { detail: this.#settledDetail() });
+    }
   }
-  /** Reflects the model onto sliders, the hex input, preview, and form field. */
+  /**
+   * Reflects the model onto sliders, the hex input, preview, and form field.
+   *
+   * @stimeoRenderRoot
+   */
   #render() {
     for (const slider of this.sliderTargets) {
       const channel = this.#channelOf(slider);
@@ -198,14 +214,28 @@ var ColorPickerController = class extends Controller {
       slider.setAttribute("aria-valuetext", valueText(channel, value));
     }
     const hex = this.#hexString();
+    this.#committedHex = hex;
     if (this.hasHexTarget) this.hexTarget.value = hex;
     for (const field of this.fieldTargets) field.value = hex;
     for (const preview of this.previewTargets) preview.style.setProperty(COLOR_PROPERTY, hex);
     this.element.style.setProperty(COLOR_PROPERTY, hex);
+  }
+  /**
+   * Repaints after `alpha` changed at runtime and reports a color this controller
+   * settled on. Disabling alpha drops it from the model, so the committed color can
+   * move without a user edit; `change` stays reserved for the picker's own actions.
+   */
+  #reconcileColor() {
+    const previous = this.#committedHex;
+    this.#render();
+    if (previous !== null && this.#committedHex !== previous) {
+      this.dispatch("reconcile", { detail: this.#settledDetail() });
+    }
+  }
+  /** The settled color as event detail, shared by both report paths. */
+  #settledDetail() {
     const rgb = hslToRgb(this.#color.hue, this.#color.saturation, this.#color.lightness);
-    this.dispatch("change", {
-      detail: { value: hex, rgba: { ...rgb, a: this.#color.alpha / 100 } }
-    });
+    return { value: this.#hexString(), rgba: { ...rgb, a: this.#color.alpha / 100 } };
   }
   /** The current color as `#RRGGBB`, or `#RRGGBBAA` when alpha is enabled. */
   #hexString() {

data/dist/controllers/context_menu_controller.js

@@ -237,8 +237,8 @@ var ContextMenuController = class extends Controller {
       onDismiss: () => this.#closeAndRestore(),
       claims: claimsWhileFocusWithin(this.element)
     });
-    this.menuTarget.style.setProperty("--stimeo-context-menu-x", `${x}px`);
-    this.menuTarget.style.setProperty("--stimeo-context-menu-y", `${y}px`);
+    this.menuTarget.style.setProperty("--stimeo--context-menu-x", `${x}px`);
+    this.menuTarget.style.setProperty("--stimeo--context-menu-y", `${y}px`);
     this.menuTarget.hidden = false;
     if (this.hasRegionTarget) this.regionTarget.setAttribute("data-state", "open");
     this.#navigableItems[0]?.focus();

data/dist/controllers/countdown_controller.js

@@ -268,7 +268,11 @@ var CountdownController = class extends Controller {
     const raw = this.#isDown ? this.#reference - now : now - this.#reference;
     return Math.max(0, raw);
   }
-  /** Writes the amount into the day/hour/minute/second slots. */
+  /**
+   * Writes the amount into the day/hour/minute/second slots.
+   *
+   * @stimeoRenderRoot
+   */
   #render(amount) {
     const totalSeconds = Math.floor(amount / SECOND_MS);
     this.#renderedAmount = totalSeconds * SECOND_MS;