stimeo-ui 0.6.0 → 0.7.0

package/dist/controllers/conditional_fields_controller.d.ts

@@ -1,10 +1,10 @@
 import { Controller } from '@hotwired/stimulus';
 
-/** Trigger controls whose state drives region visibility. */
+/** Trigger controls whose live state drives region visibility. */
 type Trigger = HTMLInputElement | HTMLSelectElement;
 /**
  * Headless dependent-fields behavior: shows/hides (and enables/disables) regions
- * based on trigger control values, keeping `hidden` / `aria-hidden` / `disabled` in
+ * from trigger control values while keeping submission and accessibility state in
  * sync (no dedicated APG pattern).
  *
  * Markup contract (identifier: `stimeo--conditional-fields`):
@@ -15,17 +15,32 @@ type Trigger = HTMLInputElement | HTMLSelectElement;
  *     </fieldset>
  *   </form>
  *
- * Each region declares its condition with a data attribute: `data-when-checked`,
- * `data-when-unchecked`, or `data-when-value="x"`. When the condition (combined
- * across triggers per `match`) holds the region is shown and its inputs enabled;
- * otherwise it is hidden, `aria-hidden`, and — with `disableHidden` — its inputs are
- * disabled so they drop out of the submission. Hiding a region that holds focus
- * first retreats focus to a trigger.
+ * A region declares one condition: `data-when-checked`, `data-when-unchecked`,
+ * or `data-when-value="x"`. The condition is combined across all triggers using
+ * `match` (`"any"` by default, or `"all"`). A region with no condition preserves
+ * its authored `hidden` state; a declared condition with no triggers is false.
+ *
+ * Hidden regions receive `hidden` and `aria-hidden="true"`; visible regions expose
+ * `data-visible="true"`. With `disableHidden`, descendant controls are disabled and
+ * marked with `data-conditional-disabled="true"`, and only marked controls are
+ * re-enabled. Before a focused region is hidden, focus moves to the first trigger
+ * that can actually receive it. If every trigger is unsafe — including one inside
+ * another region being hidden in the same pass — the controller root temporarily
+ * receives `tabindex="-1"` and focus.
+ *
+ * `change` and `reconcile` dispatch `{ region, visible }`.
  *
  * @remarks
- * Behavior only. Visibility/enabled state lives entirely on the elements' `hidden` /
- * `disabled` / `aria-hidden`, re-derived from triggers on `connect()` (Morph-safe).
- * The change/input listener is removed on `disconnect()` (Turbo navigation included).
+ * Behavior only. Trigger `input` / `change`, dynamic targets and descendants,
+ * condition attributes, Values, native form reset, and Turbo retained-element
+ * morphs all reconcile against the live DOM. Direct writes to an input's live
+ * `checked` / `value` property remain observable only when the caller also emits
+ * the corresponding native event. DOM repair is silent. User input or the public
+ * action dispatches `stimeo--conditional-fields:change`; a lifecycle, Value,
+ * reset, mutation, or morph reconciliation dispatches
+ * `stimeo--conditional-fields:reconcile` instead. Initial connection is silent.
+ * Every listener, observer, queued pass, and borrowed root `tabindex` is released
+ * on `disconnect()`.
  */
 declare class ConditionalFieldsController extends Controller<HTMLElement> {
     #private;
@@ -41,15 +56,28 @@ declare class ConditionalFieldsController extends Controller<HTMLElement> {
         };
     };
     static actions: readonly ["evaluate"];
-    static events: readonly ["change"];
+    static events: readonly ["change", "reconcile"];
     readonly triggerTargets: Trigger[];
     readonly regionTargets: HTMLElement[];
-    readonly hasTriggerTarget: boolean;
     disableHiddenValue: boolean;
     matchValue: string;
+    /** Reflects initial live state and opens every retained-DOM reconciliation path. */
     connect(): void;
+    /** Releases all external resources and returns the temporary focus landmark loan. */
     disconnect(): void;
-    /** Re-evaluates every region against the current trigger state. */
+    /** Reconciles after a trigger target is inserted or restored. */
+    triggerTargetConnected(): void;
+    /** Reconciles after a trigger target is removed or replaced. */
+    triggerTargetDisconnected(): void;
+    /** Initializes a region target inserted or restored at runtime. */
+    regionTargetConnected(): void;
+    /** Reconciles the remaining region set after a target leaves. */
+    regionTargetDisconnected(): void;
+    /** Reconciles when application code or a morph changes the match policy. */
+    matchValueChanged(): void;
+    /** Reconciles control ownership when hidden controls become enabled or excluded. */
+    disableHiddenValueChanged(): void;
+    /** Re-evaluates every region and repairs all reflected DOM state. */
     evaluate(): void;
 }
 

package/dist/controllers/conditional_fields_controller.js

@@ -1,7 +1,134 @@
 import { Controller } from '@hotwired/stimulus';
 
+// src/controllers/conditional_fields_controller.ts
+
+// src/utils/focus_candidate.ts
+function inheritsFieldsetDisabled(control) {
+  let fieldset = control.closest("fieldset[disabled]");
+  while (fieldset) {
+    const legend = Array.from(fieldset.children).find((child) => child.tagName === "LEGEND");
+    if (!legend?.contains(control)) return true;
+    fieldset = fieldset.parentElement?.closest("fieldset[disabled]") ?? null;
+  }
+  return false;
+}
+function canTakeFocus(element) {
+  if (element.closest("[hidden], [inert]")) return false;
+  if (element instanceof HTMLInputElement && element.type === "hidden") return false;
+  if (!("disabled" in element)) return true;
+  if (element.disabled) return false;
+  return !inheritsFieldsetDisabled(element);
+}
+
+// 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/before_cache_reset.ts
+var BeforeCacheReset = class _BeforeCacheReset {
+  /** Every subscribed instance, iterated by the one shared document listener. */
+  static #subscribers = /* @__PURE__ */ new Set();
+  /** The shared listener; installed while at least one instance is subscribed. */
+  static #onBeforeCache = () => {
+    for (const subscriber of _BeforeCacheReset.#subscribers) subscriber.#rewind();
+  };
+  #rewind;
+  /** @param rewind - the pass that returns this controller's state to its initial form. */
+  constructor(rewind) {
+    this.#rewind = rewind;
+  }
+  /** Subscribes to `turbo:before-cache`; call from `connect()`. Idempotent. */
+  activate() {
+    const first = _BeforeCacheReset.#subscribers.size === 0;
+    _BeforeCacheReset.#subscribers.add(this);
+    if (first) {
+      document.addEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+    }
+  }
+  /** Unsubscribes; call from `disconnect()`. Safe when never subscribed. */
+  deactivate() {
+    _BeforeCacheReset.#subscribers.delete(this);
+    if (_BeforeCacheReset.#subscribers.size > 0) return;
+    document.removeEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+  }
+};
+
+// src/utils/tabindex_loan.ts
+var TabindexLoan = class {
+  #value;
+  #lent = /* @__PURE__ */ new Set();
+  /** Returns live loans before Turbo can copy them into its page snapshot. */
+  #beforeCache = new BeforeCacheReset(() => this.returnAll());
+  /**
+   * @param value - the `tabindex` to lend. `"-1"` (the default) is
+   *   programmatically focusable but not a Tab stop; `"0"` is a real Tab stop,
+   *   which a scroll region with no focusable content of its own needs.
+   */
+  constructor(value = "-1") {
+    this.#value = value;
+  }
+  /** Lends `element` the value; no-ops when it already carries a `tabindex`. */
+  lend(element) {
+    if (element.hasAttribute("tabindex")) return;
+    element.setAttribute("tabindex", this.#value);
+    this.#lent.add(element);
+    this.#beforeCache.activate();
+  }
+  /** Takes back every loan whose value is still the one that was lent. */
+  returnAll() {
+    for (const element of this.#lent) {
+      if (element.getAttribute("tabindex") === this.#value) element.removeAttribute("tabindex");
+    }
+    this.#lent.clear();
+    this.#beforeCache.deactivate();
+  }
+};
+
 // src/controllers/conditional_fields_controller.ts
 var DISABLED_MARKER = "data-conditional-disabled";
+var OBSERVED_ATTRIBUTES = [
+  "hidden",
+  "aria-hidden",
+  "data-visible",
+  DISABLED_MARKER,
+  "disabled",
+  "data-when-checked",
+  "data-when-unchecked",
+  "data-when-value",
+  "checked",
+  "selected",
+  "value",
+  "type"
+];
 var ConditionalFieldsController = class extends Controller {
   static targets = ["trigger", "region"];
   static values = {
@@ -9,56 +136,171 @@ var ConditionalFieldsController = class extends Controller {
     match: { type: String, default: "any" }
   };
   static actions = ["evaluate"];
-  static events = ["change"];
+  static events = ["change", "reconcile"];
+  /** Logical state last committed for each current region; rebuilt on every connect. */
   #lastVisible = /* @__PURE__ */ new WeakMap();
-  #onChange = () => {
-    this.evaluate();
+  /** Controller writes awaiting an observer callback, separated from authored morphs. */
+  #internalWrites = /* @__PURE__ */ new WeakMap();
+  #observing = false;
+  /** Coalesces one target/morph/mutation batch into one full DOM reconciliation. */
+  #reconcile = new MicrotaskCoalescer(() => this.#reconcileDom());
+  /** Provides the last-resort focus landmark without claiming an authored tabindex. */
+  #rootTabindex = new TabindexLoan();
+  /** Watches retained targets and controls whose declarative or reflected state changed. */
+  #observer = new MutationObserver((records) => this.#onMutations(records));
+  /** Evaluates only events whose source is one of this instance's live trigger targets. */
+  #onTriggerInput = (event) => {
+    const target = event.target;
+    const triggers = this.triggerTargets;
+    if (target instanceof Element && triggers.some((trigger) => trigger === target)) {
+      this.#commitChange(triggers);
+    }
+  };
+  /** Reconciles property-only retained-element changes after Turbo morphs. */
+  #onMorph = () => {
+    this.#reconcile.schedule();
+  };
+  /** Reconciles the settled defaults after a non-cancelled owning form reset. */
+  #onReset = (event) => {
+    const form = event.target;
+    if (form instanceof HTMLFormElement && this.#hasTriggerOwnedBy(form)) {
+      queueMicrotask(() => {
+        if (!event.defaultPrevented) this.#reconcile.schedule();
+      });
+    }
   };
+  /** Reflects initial live state and opens every retained-DOM reconciliation path. */
   connect() {
-    this.evaluate();
-    this.element.addEventListener("change", this.#onChange);
-    this.element.addEventListener("input", this.#onChange);
+    this.#lastVisible = /* @__PURE__ */ new WeakMap();
+    this.#internalWrites = /* @__PURE__ */ new WeakMap();
+    this.#reconcile.activate();
+    this.#settle();
+    this.#observer.observe(this.element, {
+      attributes: true,
+      attributeFilter: OBSERVED_ATTRIBUTES,
+      childList: true,
+      subtree: true
+    });
+    this.#observing = true;
+    this.element.addEventListener("change", this.#onTriggerInput);
+    this.element.addEventListener("input", this.#onTriggerInput);
+    this.element.addEventListener("turbo:morph-element", this.#onMorph);
+    document.addEventListener("reset", this.#onReset, true);
   }
+  /** Releases all external resources and returns the temporary focus landmark loan. */
   disconnect() {
-    this.element.removeEventListener("change", this.#onChange);
-    this.element.removeEventListener("input", this.#onChange);
+    this.#reconcile.cancel();
+    this.#observing = false;
+    this.#observer.disconnect();
+    this.element.removeEventListener("change", this.#onTriggerInput);
+    this.element.removeEventListener("input", this.#onTriggerInput);
+    this.element.removeEventListener("turbo:morph-element", this.#onMorph);
+    document.removeEventListener("reset", this.#onReset, true);
+    this.#rootTabindex.returnAll();
+  }
+  /** Reconciles after a trigger target is inserted or restored. */
+  triggerTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /** Reconciles after a trigger target is removed or replaced. */
+  triggerTargetDisconnected() {
+    this.#reconcile.schedule();
+  }
+  /** Initializes a region target inserted or restored at runtime. */
+  regionTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /** Reconciles the remaining region set after a target leaves. */
+  regionTargetDisconnected() {
+    this.#reconcile.schedule();
   }
-  /** Re-evaluates every region against the current trigger state. */
+  /** Reconciles when application code or a morph changes the match policy. */
+  matchValueChanged() {
+    this.#reconcile.schedule();
+  }
+  /** Reconciles control ownership when hidden controls become enabled or excluded. */
+  disableHiddenValueChanged() {
+    this.#reconcile.schedule();
+  }
+  /** Re-evaluates every region and repairs all reflected DOM state. */
   evaluate() {
-    const triggers = this.triggerTargets;
-    for (const region of this.regionTargets) {
-      this.#applyRegion(region, this.#isVisible(region, triggers));
+    this.#commitChange();
+  }
+  /**
+   * Computes one settled plan, shows destinations before hiding sources, and then
+   * returns logical transitions in DOM order after every region is internally coherent.
+   */
+  #settle(triggers = this.triggerTargets) {
+    const regions = this.regionTargets;
+    const plan = /* @__PURE__ */ new Map();
+    for (const region of regions) plan.set(region, this.#isVisible(region, triggers));
+    const changed = /* @__PURE__ */ new Set();
+    const applicationOrder = [
+      ...regions.filter((region) => plan.get(region) === true),
+      ...regions.filter((region) => plan.get(region) === false)
+    ];
+    for (const region of applicationOrder) {
+      const visible = plan.get(region);
+      if (visible !== void 0 && this.#applyRegion(region, visible, plan)) {
+        changed.add(region);
+      }
+    }
+    return regions.filter((region) => changed.has(region)).map((region) => ({ region, visible: plan.get(region) === true }));
+  }
+  /** Reports logical transitions caused by user input or the public action. */
+  #commitChange(triggers = this.triggerTargets) {
+    for (const detail of this.#settle(triggers)) {
+      this.dispatch("change", { detail });
+    }
+  }
+  /** Reports logical transitions derived from DOM, lifecycle, reset, or Value state. */
+  #reconcileDom() {
+    for (const detail of this.#settle()) {
+      this.dispatch("reconcile", { detail });
     }
   }
-  /** Applies a region's visibility, syncing hidden/aria/disabled and emitting change. */
-  #applyRegion(region, visible) {
+  /** Applies one planned state while keeping event history separate from DOM repair. */
+  #applyRegion(region, visible, plan) {
     const previous = this.#lastVisible.get(region) ?? !region.hidden;
-    if (visible === previous && this.#lastVisible.has(region)) return;
+    const changed = visible !== previous;
     this.#lastVisible.set(region, visible);
-    if (visible) {
-      region.hidden = false;
-      region.removeAttribute("aria-hidden");
-      region.setAttribute("data-visible", "true");
-      this.#setRegionDisabled(region, false);
-    } else {
-      this.#retreatFocus(region);
-      region.hidden = true;
-      region.setAttribute("aria-hidden", "true");
-      region.removeAttribute("data-visible");
-      this.#setRegionDisabled(region, true);
-    }
-    if (visible !== previous) {
-      this.dispatch("change", { detail: { region, visible } });
+    if (!visible) this.#retreatFocus(region, plan);
+    this.#syncRegionState(region, visible);
+    this.#syncRegionControls(region, visible);
+    return changed;
+  }
+  /** Reflects visibility idempotently, recording writes so the observer ignores its own work. */
+  #syncRegionState(region, visible) {
+    this.#writeAttribute(region, "hidden", visible ? null : "");
+    this.#writeAttribute(region, "aria-hidden", visible ? null : "true");
+    this.#writeAttribute(region, "data-visible", visible ? "true" : null);
+  }
+  /** Enables/disables descendant controls, touching only state carrying our marker. */
+  #syncRegionControls(region, visible) {
+    const shouldDisable = !visible && this.disableHiddenValue;
+    const controls = region.querySelectorAll("input, textarea, select, button");
+    for (const control of controls) {
+      const marked = control.hasAttribute(DISABLED_MARKER);
+      if (shouldDisable) {
+        if (!control.disabled) {
+          this.#writeAttribute(control, "disabled", "");
+          this.#writeAttribute(control, DISABLED_MARKER, "true");
+        } else if (marked && control.getAttribute(DISABLED_MARKER) !== "true") {
+          this.#writeAttribute(control, DISABLED_MARKER, "true");
+        }
+      } else if (marked) {
+        this.#writeAttribute(control, "disabled", null);
+        this.#writeAttribute(control, DISABLED_MARKER, null);
+      }
     }
   }
   /** Whether a region's declared condition holds across `triggers` per `match`. */
   #isVisible(region, triggers) {
     const predicate = this.#predicateFor(region);
     if (predicate === null) return !region.hidden;
-    if (triggers.length === 0) return false;
-    return this.matchValue === "all" ? triggers.every(predicate) : triggers.some(predicate);
+    return triggers.length > 0 && (this.matchValue === "all" ? triggers.every(predicate) : triggers.some(predicate));
   }
-  /** Builds the per-trigger predicate from the region's `data-when-*` attribute. */
+  /** Builds the deterministic per-trigger predicate from the region's condition. */
   #predicateFor(region) {
     if (region.hasAttribute("data-when-checked")) {
       return (trigger) => this.#isChecked(trigger);
@@ -75,35 +317,87 @@ var ConditionalFieldsController = class extends Controller {
   #isChecked(trigger) {
     return trigger instanceof HTMLInputElement && trigger.checked;
   }
-  /** A trigger "has" a value: selected radio/checkbox value, or the control value. */
+  /** A trigger has a value when a radio/checkbox is selected, or its control value matches. */
   #matchesValue(trigger, wanted) {
     if (trigger instanceof HTMLInputElement && (trigger.type === "checkbox" || trigger.type === "radio")) {
       return trigger.checked && trigger.value === wanted;
     }
     return trigger.value === wanted;
   }
-  /** Enables/disables a region's inputs, tracking only the ones we disabled. */
-  #setRegionDisabled(region, disabled) {
-    if (!this.disableHiddenValue) return;
-    const controls = region.querySelectorAll("input, textarea, select, button");
-    for (const control of Array.from(controls)) {
-      if (disabled) {
-        if (!control.disabled) {
-          control.disabled = true;
-          control.setAttribute(DISABLED_MARKER, "true");
+  /** Moves focus to the first safe trigger, or to the controller landmark as a fallback. */
+  #retreatFocus(region, plan) {
+    const active = document.activeElement;
+    if (active && region.contains(active)) this.#moveFocus(plan);
+  }
+  /** Moves focus after the caller establishes that the active node is being hidden. */
+  #moveFocus(plan) {
+    const destination = this.triggerTargets.find(
+      (trigger) => canTakeFocus(trigger) && this.#survivesPlan(trigger, plan)
+    );
+    if (destination) {
+      this.#rootTabindex.returnAll();
+      destination.focus();
+      return;
+    }
+    this.#rootTabindex.lend(this.element);
+    this.element.focus();
+  }
+  /** Whether a focus candidate sits outside every region this pass will hide. */
+  #survivesPlan(candidate, plan) {
+    return [...plan].every(([region, visible]) => visible || !region.contains(candidate));
+  }
+  /** Records one idempotent attribute write before MutationObserver sees it. */
+  #writeAttribute(element, name, value) {
+    if (element.getAttribute(name) !== value) {
+      if (this.#observing) {
+        let writes = this.#internalWrites.get(element);
+        if (!writes) {
+          writes = /* @__PURE__ */ new Map();
+          this.#internalWrites.set(element, writes);
         }
-      } else if (control.hasAttribute(DISABLED_MARKER)) {
-        control.disabled = false;
-        control.removeAttribute(DISABLED_MARKER);
+        writes.set(name, value);
       }
+      if (value === null) element.removeAttribute(name);
+      else element.setAttribute(name, value);
     }
   }
-  /** Moves focus out of a region about to be hidden, to a trigger when possible. */
-  #retreatFocus(region) {
-    const active = document.activeElement;
-    if (!(active instanceof HTMLElement) || !region.contains(active)) return;
-    active.blur();
-    if (this.hasTriggerTarget) this.triggerTargets[0]?.focus();
+  /** Separates authored records from controller writes and queues one relevant repair. */
+  #onMutations(records) {
+    const triggers = this.triggerTargets;
+    const regions = this.regionTargets;
+    const touchedWrites = /* @__PURE__ */ new Map();
+    let needsReconcile = false;
+    for (const record of records) {
+      if (record.type === "attributes" && record.target instanceof Element) {
+        const name = record.attributeName;
+        const writes = this.#internalWrites.get(record.target);
+        if (name && writes?.has(name)) {
+          let names = touchedWrites.get(record.target);
+          if (!names) {
+            names = /* @__PURE__ */ new Set();
+            touchedWrites.set(record.target, names);
+          }
+          names.add(name);
+          if (record.target.getAttribute(name) === writes.get(name)) continue;
+        }
+      }
+      if (record.target instanceof Element && this.#elementAffectsState(record.target, triggers, regions)) {
+        needsReconcile = true;
+      }
+    }
+    for (const [element, names] of touchedWrites) {
+      const writes = this.#internalWrites.get(element);
+      for (const name of names) writes?.delete(name);
+    }
+    if (needsReconcile) this.#reconcile.schedule();
+  }
+  /** Whether an authored mutation target belongs to a trigger, region, or managed control. */
+  #elementAffectsState(target, triggers, regions) {
+    return triggers.some((trigger) => trigger === target || trigger.contains(target)) || regions.some((region) => region === target || region.contains(target));
+  }
+  /** Whether a form owns at least one current trigger, including `form=` associations. */
+  #hasTriggerOwnedBy(form) {
+    return this.triggerTargets.some((trigger) => trigger.form === form);
   }
 };