stimeo-ui 0.5.0 → 0.7.0

package/dist/controllers/checkbox_controller.d.ts

@@ -21,28 +21,57 @@ import { Controller } from '@hotwired/stimulus';
  * `indeterminate` property (announced as `mixed`) derived from its children, and
  * the cascade from a parent toggle to its children.
  *
+ * `change` and `reconcile` dispatch
+ * `{ checked: boolean, indeterminate: boolean, state: "all" | "partial" | "none" }`.
+ *
  * @remarks
  * Behavior only — the check mark and any "mixed" affordance are the consumer's
- * CSS (keyed off `:checked` / `:indeterminate` / `data-state`). A lone tri-state
- * checkbox can use just `parent` and drive `indeterminate` externally.
+ * CSS (keyed off `:checked` / `:indeterminate` / `data-state`). The `parent`
+ * target is optional: a child-only group still exposes its aggregate on the root,
+ * while a lone tri-state checkbox can use just `parent` and drive
+ * `indeterminate` externally — with no `child` target the parent's own `checked`
+ * and `indeterminate` stay the consumer's, because only children are
+ * authoritative over them. At most one `parent` may be present.
  *
  * Behavior provided:
  * - Parent toggle checks/unchecks every child and clears its own `indeterminate`.
+ *   All child targets, including disabled ones, participate; omit the target to
+ *   exclude an input. The cascade does not synthesize native child `change`
+ *   events — one aggregate custom event describes the action.
  * - A child change recomputes the parent: all → checked, none → unchecked,
  *   some → `indeterminate`.
  * - The aggregate (`all` / `partial` / `none`) is mirrored to `data-state` on the
- *   root, and `stimeo--checkbox:change` is dispatched on every change.
+ *   root. Dynamic targets, checked-attribute changes, Turbo morphs, and native
+ *   form resets are reconciled from the children. Callers that assign the live
+ *   `checked` property directly must dispatch `change`, because property writes
+ *   are not observable by a `MutationObserver`.
+ * - `stimeo--checkbox:change` is dispatched for the two public change actions;
+ *   `stimeo--checkbox:reconcile` is dispatched instead when a reconciliation —
+ *   not the user — moves the aggregate. Both carry `{ checked: boolean,
+ *   indeterminate: boolean, state: "all" | "partial" | "none" }` and describe
+ *   the aggregate even without a parent. Neither fires on connect.
  */
 declare class CheckboxController extends Controller<HTMLElement> {
     #private;
     static targets: string[];
     static actions: readonly ["onChildChange", "onParentChange"];
-    static events: readonly ["change"];
+    static events: readonly ["change", "reconcile"];
     readonly parentTarget: HTMLInputElement;
+    readonly parentTargets: HTMLInputElement[];
     readonly hasParentTarget: boolean;
     readonly childTargets: HTMLInputElement[];
-    /** Reflects the initial aggregate (e.g. from server-rendered child states). */
+    /** Reflects the initial aggregate and starts retained-DOM reconciliation. */
     connect(): void;
+    /** Releases the observer, global reset listener, and every pending reconciliation. */
+    disconnect(): void;
+    /** Reconciles the aggregate for a parent added or replaced at runtime. */
+    parentTargetConnected(): void;
+    /** Reconciles the aggregate after a parent target leaves the group. */
+    parentTargetDisconnected(): void;
+    /** Reconciles the aggregate for a child added at runtime. */
+    childTargetConnected(): void;
+    /** Reconciles the aggregate after a child leaves the group. */
+    childTargetDisconnected(): void;
     /** Cascades the parent's state to every child. Bound via `data-action` (change). */
     onParentChange(): void;
     /** Recomputes the parent from its children. Bound via `data-action` (change). */

package/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

package/dist/controllers/checkbox_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/controllers/checkbox_controller.ts"],"names":[],"mappings":"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","file":"checkbox_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/** Aggregate selection state of a parent/child checkbox group. */\ntype CheckboxState = \"all\" | \"partial\" | \"none\";\n\n/**\n * Headless, accessible checkbox behavior (including the tri-state / parent-child\n * \"select all\" pattern).\n *\n * Markup contract (identifier: `stimeo--checkbox`):\n *   <fieldset data-controller=\"stimeo--checkbox\" role=\"group\" aria-labelledby=\"all-label\">\n *     <label id=\"all-label\">\n *       <input type=\"checkbox\" data-stimeo--checkbox-target=\"parent\"\n *              data-action=\"change->stimeo--checkbox#onParentChange\" /> Select all\n *     </label>\n *     <label><input type=\"checkbox\" data-stimeo--checkbox-target=\"child\"\n *              data-action=\"change->stimeo--checkbox#onChildChange\" /> Item A</label>\n *     <!-- more children -->\n *   </fieldset>\n *\n * Implements the WAI-ARIA APG **Checkbox** pattern. Native `<input type=\"checkbox\">`\n * is used throughout (so Space toggle, focus order, and `mixed` exposure are the\n * browser's); the controller adds what HTML cannot express: the parent's\n * `indeterminate` property (announced as `mixed`) derived from its children, and\n * the cascade from a parent toggle to its children.\n *\n * @remarks\n * Behavior only — the check mark and any \"mixed\" affordance are the consumer's\n * CSS (keyed off `:checked` / `:indeterminate` / `data-state`). A lone tri-state\n * checkbox can use just `parent` and drive `indeterminate` externally.\n *\n * Behavior provided:\n * - Parent toggle checks/unchecks every child and clears its own `indeterminate`.\n * - A child change recomputes the parent: all → checked, none → unchecked,\n *   some → `indeterminate`.\n * - The aggregate (`all` / `partial` / `none`) is mirrored to `data-state` on the\n *   root, and `stimeo--checkbox:change` is dispatched on every change.\n */\nexport class CheckboxController extends Controller<HTMLElement> {\n  static override targets = [\"parent\", \"child\"];\n  static actions = [\"onChildChange\", \"onParentChange\"] as const;\n  static events = [\"change\"] as const;\n\n  declare readonly parentTarget: HTMLInputElement;\n  declare readonly hasParentTarget: boolean;\n  declare readonly childTargets: HTMLInputElement[];\n\n  /** Reflects the initial aggregate (e.g. from server-rendered child states). */\n  override connect(): void {\n    if (this.childTargets.length > 0) {\n      this.#syncFromChildren(false);\n    } else {\n      this.element.setAttribute(\"data-state\", this.#aggregate());\n    }\n  }\n\n  /** Cascades the parent's state to every child. Bound via `data-action` (change). */\n  onParentChange(): void {\n    if (!this.hasParentTarget) return;\n    const checked = this.parentTarget.checked;\n    for (const child of this.childTargets) {\n      child.checked = checked;\n    }\n    this.parentTarget.indeterminate = false;\n    const state: CheckboxState = checked ? \"all\" : \"none\";\n    this.element.setAttribute(\"data-state\", state);\n    this.dispatch(\"change\", { detail: { checked, indeterminate: false, state } });\n  }\n\n  /** Recomputes the parent from its children. Bound via `data-action` (change). */\n  onChildChange(): void {\n    this.#syncFromChildren(true);\n  }\n\n  /**\n   * Derives the parent's `checked`/`indeterminate` and the root `data-state` from\n   * the children, optionally dispatching `change`.\n   */\n  #syncFromChildren(dispatch: boolean): void {\n    const state = this.#aggregate();\n    if (this.hasParentTarget) {\n      this.parentTarget.checked = state === \"all\";\n      this.parentTarget.indeterminate = state === \"partial\";\n    }\n    this.element.setAttribute(\"data-state\", state);\n    if (dispatch) {\n      this.dispatch(\"change\", {\n        detail: {\n          checked: this.hasParentTarget ? this.parentTarget.checked : state === \"all\",\n          indeterminate: this.hasParentTarget ? this.parentTarget.indeterminate : false,\n          state,\n        },\n      });\n    }\n  }\n\n  /**\n   * Computes the aggregate state. With children it counts them; with none it\n   * reads the parent so a lone tri-state checkbox still reports a state without\n   * its externally-set `indeterminate` being clobbered.\n   */\n  #aggregate(): CheckboxState {\n    const children = this.childTargets;\n    if (children.length === 0) {\n      if (this.hasParentTarget && this.parentTarget.indeterminate) return \"partial\";\n      return this.hasParentTarget && this.parentTarget.checked ? \"all\" : \"none\";\n    }\n    const checked = children.filter((child) => child.checked).length;\n    if (checked === 0) return \"none\";\n    if (checked === children.length) return \"all\";\n    return \"partial\";\n  }\n}\n"]}
+{"version":3,"sources":["../../src/utils/microtask_coalescer.ts","../../src/controllers/checkbox_controller.ts"],"names":[],"mappings":"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","file":"checkbox_controller.js","sourcesContent":["/**\n * Collapses many Stimulus lifecycle callbacks from one DOM mutation into a\n * single pass.\n *\n * Stimulus fires `<name>TargetConnected` / `Disconnected` once per element and\n * `<name>ValueChanged` once per changed attribute. Replacing a list of N options\n * or morphing several render Values therefore delivers N callbacks — but the\n * useful unit of work is \"reconcile against the resulting declarative input\",\n * once, after the batch has settled. Every controller with reconcilable targets\n * or render Values needs the same shape: a `queued` flag plus `queueMicrotask`.\n *\n * **A microtask is the right horizon, and the reason is specific.** Stimulus\n * drives these callbacks from a `MutationObserver`, whose own callback already\n * runs as a microtask with the whole batch in hand; scheduling one more lands\n * after the last sibling callback of that batch and still before paint or any\n * event handler. A timer would be later than it needs to be, and reconciling\n * synchronously would run once per element against a half-applied DOM.\n *\n * **The two guards are not the same guard.** Scheduling is refused before the\n * controller connects, and running is refused after it disconnects:\n *\n * - **Before `connect()`** — Stimulus delivers initial target and Value callbacks\n *   ahead of `connect()`. Reconciling there would compute output against a\n *   controller whose own state has not been initialised, and `connect()` is\n *   about to do a full pass anyway.\n * - **After `disconnect()`** — Stimulus fires a callback for **every** target\n *   during teardown, and a microtask queued just before it would otherwise run\n *   against a detached tree. {@link MicrotaskCoalescer.cancel} exists for the\n *   teardown path to drop the pending pass outright.\n *\n * Both guards are part of one contract here rather than something each consumer\n * has to remember separately.\n *\n * Scope is the scheduling only. *What* to reconcile — keep the surviving active\n * option, fall back to the next / previous / first visible one, rebuild derived\n * chips or hidden fields — stays in the controller, because no two consumers\n * answer it the same way.\n *\n * This file's own doc block is dropped from `dist`, but every member comment is\n * inlined into each consumer entry (`tsup` builds with `splitting: false`), so\n * rationale belongs here and only the contract belongs on the members.\n *\n * @example\n * ```ts\n * readonly #reconcile = new MicrotaskCoalescer(() => this.#reconcileOptions());\n *\n * connect()    { this.#reconcile.activate(); }\n * disconnect() { this.#reconcile.cancel(); }\n *\n * optionTargetConnected()    { this.#reconcile.schedule(); }\n * optionTargetDisconnected() { this.#reconcile.schedule(); }\n * ```\n */\nexport class MicrotaskCoalescer {\n  readonly #run: () => void;\n  #queued = false;\n  #active = false;\n  #generation = 0;\n\n  /** @param run - the single reconciliation pass, invoked at most once per batch. */\n  constructor(run: () => void) {\n    this.#run = run;\n  }\n\n  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */\n  activate(): void {\n    this.#active = true;\n  }\n\n  /** Closes the window and drops any pending pass; call from `disconnect()`. */\n  cancel(): void {\n    this.#active = false;\n    this.#queued = false;\n    this.#generation += 1;\n  }\n\n  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */\n  schedule(): void {\n    if (!this.#active || this.#queued) return;\n    this.#queued = true;\n    const generation = this.#generation;\n    queueMicrotask(() => {\n      // A cancelled callback must not consume a pass queued after reconnect.\n      if (generation !== this.#generation || !this.#queued || !this.#active) return;\n      this.#queued = false;\n      this.#run();\n    });\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { MicrotaskCoalescer } from \"../utils/microtask_coalescer\";\n\n/** Aggregate selection state of a parent/child checkbox group. */\ntype CheckboxState = \"all\" | \"partial\" | \"none\";\n\n/**\n * Headless, accessible checkbox behavior (including the tri-state / parent-child\n * \"select all\" pattern).\n *\n * Markup contract (identifier: `stimeo--checkbox`):\n *   <fieldset data-controller=\"stimeo--checkbox\" role=\"group\" aria-labelledby=\"all-label\">\n *     <label id=\"all-label\">\n *       <input type=\"checkbox\" data-stimeo--checkbox-target=\"parent\"\n *              data-action=\"change->stimeo--checkbox#onParentChange\" /> Select all\n *     </label>\n *     <label><input type=\"checkbox\" data-stimeo--checkbox-target=\"child\"\n *              data-action=\"change->stimeo--checkbox#onChildChange\" /> Item A</label>\n *     <!-- more children -->\n *   </fieldset>\n *\n * Implements the WAI-ARIA APG **Checkbox** pattern. Native `<input type=\"checkbox\">`\n * is used throughout (so Space toggle, focus order, and `mixed` exposure are the\n * browser's); the controller adds what HTML cannot express: the parent's\n * `indeterminate` property (announced as `mixed`) derived from its children, and\n * the cascade from a parent toggle to its children.\n *\n * `change` and `reconcile` dispatch\n * `{ checked: boolean, indeterminate: boolean, state: \"all\" | \"partial\" | \"none\" }`.\n *\n * @remarks\n * Behavior only — the check mark and any \"mixed\" affordance are the consumer's\n * CSS (keyed off `:checked` / `:indeterminate` / `data-state`). The `parent`\n * target is optional: a child-only group still exposes its aggregate on the root,\n * while a lone tri-state checkbox can use just `parent` and drive\n * `indeterminate` externally — with no `child` target the parent's own `checked`\n * and `indeterminate` stay the consumer's, because only children are\n * authoritative over them. At most one `parent` may be present.\n *\n * Behavior provided:\n * - Parent toggle checks/unchecks every child and clears its own `indeterminate`.\n *   All child targets, including disabled ones, participate; omit the target to\n *   exclude an input. The cascade does not synthesize native child `change`\n *   events — one aggregate custom event describes the action.\n * - A child change recomputes the parent: all → checked, none → unchecked,\n *   some → `indeterminate`.\n * - The aggregate (`all` / `partial` / `none`) is mirrored to `data-state` on the\n *   root. Dynamic targets, checked-attribute changes, Turbo morphs, and native\n *   form resets are reconciled from the children. Callers that assign the live\n *   `checked` property directly must dispatch `change`, because property writes\n *   are not observable by a `MutationObserver`.\n * - `stimeo--checkbox:change` is dispatched for the two public change actions;\n *   `stimeo--checkbox:reconcile` is dispatched instead when a reconciliation —\n *   not the user — moves the aggregate. Both carry `{ checked: boolean,\n *   indeterminate: boolean, state: \"all\" | \"partial\" | \"none\" }` and describe\n *   the aggregate even without a parent. Neither fires on connect.\n */\nexport class CheckboxController extends Controller<HTMLElement> {\n  static override targets = [\"parent\", \"child\"];\n  static actions = [\"onChildChange\", \"onParentChange\"] as const;\n  static events = [\"change\", \"reconcile\"] as const;\n\n  declare readonly parentTarget: HTMLInputElement;\n  declare readonly parentTargets: HTMLInputElement[];\n  declare readonly hasParentTarget: boolean;\n  declare readonly childTargets: HTMLInputElement[];\n\n  /** Collapses every lifecycle signal from one DOM update into one derived pass. */\n  readonly #reconcile = new MicrotaskCoalescer(() => this.#reconcileFromChildren());\n  /** Aggregate this root last settled on, so a derived repair is reported once. */\n  #committedState: CheckboxState | null = null;\n  /** Watches authored checked-attribute changes on retained target elements. */\n  readonly #checkedObserver = new MutationObserver((records) => {\n    if (records.some((record) => this.#isManagedCheckbox(record.target))) {\n      this.#reconcile.schedule();\n    }\n  });\n\n  /** Reflects the initial aggregate and starts retained-DOM reconciliation. */\n  override connect(): void {\n    this.#reconcile.activate();\n    this.#syncFromChildren();\n    this.#checkedObserver.observe(this.element, {\n      attributes: true,\n      attributeFilter: [\"checked\"],\n      subtree: true,\n    });\n    this.element.addEventListener(\"turbo:morph-element\", this.#onMorph);\n    document.addEventListener(\"reset\", this.#onReset, true);\n  }\n\n  /** Releases the observer, global reset listener, and every pending reconciliation. */\n  override disconnect(): void {\n    this.#reconcile.cancel();\n    this.#checkedObserver.disconnect();\n    this.element.removeEventListener(\"turbo:morph-element\", this.#onMorph);\n    document.removeEventListener(\"reset\", this.#onReset, true);\n  }\n\n  /** Reconciles the aggregate for a parent added or replaced at runtime. */\n  parentTargetConnected(): void {\n    this.#reconcile.schedule();\n  }\n\n  /** Reconciles the aggregate after a parent target leaves the group. */\n  parentTargetDisconnected(): void {\n    this.#reconcile.schedule();\n  }\n\n  /** Reconciles the aggregate for a child added at runtime. */\n  childTargetConnected(): void {\n    this.#reconcile.schedule();\n  }\n\n  /** Reconciles the aggregate after a child leaves the group. */\n  childTargetDisconnected(): void {\n    this.#reconcile.schedule();\n  }\n\n  /** Cascades the parent's state to every child. Bound via `data-action` (change). */\n  onParentChange(): void {\n    if (!this.hasParentTarget) return;\n    const checked = this.parentTarget.checked;\n    for (const child of this.childTargets) {\n      child.checked = checked;\n    }\n    this.#reflect(checked ? \"all\" : \"none\", true);\n    const detail = this.#settledDetail();\n    if (detail) this.dispatch(\"change\", { detail });\n  }\n\n  /** Recomputes the parent from its children. Bound via `data-action` (change). */\n  onChildChange(): void {\n    this.#syncFromChildren();\n    const detail = this.#settledDetail();\n    if (detail) this.dispatch(\"change\", { detail });\n  }\n\n  /**\n   * Announces an aggregate this pass derived rather than the user. `change` stays\n   * reserved for the two public actions, so automation never reads a repair as an edit.\n   */\n  #reconcileFromChildren(): void {\n    const previous = this.#committedState;\n    this.#syncFromChildren();\n    if (this.#committedState === previous) return;\n    const detail = this.#settledDetail();\n    if (detail) this.dispatch(\"reconcile\", { detail });\n  }\n\n  /**\n   * Derives the parent's `checked`/`indeterminate` and the root `data-state` from\n   * the children. Writing state and reporting it are separate so the caller — not\n   * a flag threaded through the write — decides which event describes the cause.\n   */\n  #syncFromChildren(): void {\n    // A childless root reads its aggregate off the parent itself, so writing the\n    // derived value back would clear a `checked` the consumer drives alongside\n    // `indeterminate`. Only the children are authoritative over the parent.\n    this.#reflect(this.#aggregate(), this.childTargets.length > 0);\n  }\n\n  /**\n   * Reflects one aggregate state.\n   *\n   * @param writeParent - whether the state is authoritative over the `parent`\n   * target's own `checked` / `indeterminate`.\n   */\n  #reflect(state: CheckboxState, writeParent: boolean): void {\n    if (writeParent && this.hasParentTarget) {\n      this.parentTarget.checked = state === \"all\";\n      this.parentTarget.indeterminate = state === \"partial\";\n    }\n    this.element.setAttribute(\"data-state\", state);\n    this.#committedState = state;\n  }\n\n  /** The settled aggregate as event detail, or `null` before anything has settled. */\n  #settledDetail(): { checked: boolean; indeterminate: boolean; state: CheckboxState } | null {\n    const state = this.#committedState;\n    if (state === null) return null;\n    return { checked: state === \"all\", indeterminate: state === \"partial\", state };\n  }\n\n  /** Reconciles retained targets after Turbo has finished morphing their live state. */\n  readonly #onMorph = (): void => {\n    this.#reconcile.schedule();\n  };\n\n  /** Reconciles after a non-cancelled reset restores any managed checkbox. */\n  readonly #onReset = (event: Event): void => {\n    const form = event.target;\n    if (!(form instanceof HTMLFormElement) || !this.#hasCheckboxOwnedBy(form)) return;\n    queueMicrotask(() => {\n      if (!event.defaultPrevented) this.#reconcile.schedule();\n    });\n  };\n\n  /** Whether a form owns at least one current parent or child target. */\n  #hasCheckboxOwnedBy(form: HTMLFormElement): boolean {\n    return [...this.parentTargets, ...this.childTargets].some((checkbox) => checkbox.form === form);\n  }\n\n  /** Whether an observed attribute mutation belongs to this controller's target set. */\n  #isManagedCheckbox(node: Node): boolean {\n    return (\n      this.parentTargets.some((checkbox) => checkbox === node) ||\n      this.childTargets.some((checkbox) => checkbox === node)\n    );\n  }\n\n  /**\n   * Computes the aggregate state. With children it counts them; with none it\n   * reads the parent so a lone tri-state checkbox still reports a state without\n   * its externally-set `indeterminate` being clobbered.\n   */\n  #aggregate(): CheckboxState {\n    const children = this.childTargets;\n    if (children.length === 0) {\n      if (this.hasParentTarget && this.parentTarget.indeterminate) return \"partial\";\n      return this.hasParentTarget && this.parentTarget.checked ? \"all\" : \"none\";\n    }\n    const checked = children.filter((child) => child.checked).length;\n    if (checked === 0) return \"none\";\n    if (checked === children.length) return \"all\";\n    return \"partial\";\n  }\n}\n"]}

package/dist/controllers/color_picker_controller.d.ts

@@ -27,6 +27,9 @@ import { Controller } from '@hotwired/stimulus';
  * preview and root as the `--stimeo--color` custom property and mirrored into a
  * hidden form field.
  *
+ * `change` and `reconcile` dispatch
+ * `{ value: string, rgba: { r: number, g: number, b: number, a: number } }`.
+ *
  * @remarks
  * Behavior only — the swatch/gradient visuals are the consumer's CSS/canvas, fed
  * by `--stimeo--color`. Only the consumer knows whether a channel track mirrors
@@ -44,6 +47,11 @@ import { Controller } from '@hotwired/stimulus';
  * exactly bijective: a typed hex can normalize to a near (not identical) value
  * once the HSL sliders are touched. This keeps the model small and zero-dep; use a
  * dedicated color library on the consumer side if exact hex preservation matters.
+ *
+ * A color the user set through a slider or the hex input is reported as
+ * `stimeo--color-picker:change`. Toggling `alpha` at runtime can move the
+ * committed color without a user edit, and that arrives as
+ * `stimeo--color-picker:reconcile` with the same detail. Neither fires on connect.
  */
 declare class ColorPickerController extends Controller<HTMLElement> {
     #private;
@@ -63,7 +71,7 @@ declare class ColorPickerController extends Controller<HTMLElement> {
         };
     };
     static actions: readonly ["onHexInput", "onKeydown", "onPointerDown"];
-    static events: readonly ["change"];
+    static events: readonly ["change", "reconcile"];
     readonly sliderTargets: HTMLElement[];
     readonly hexTarget: HTMLInputElement;
     readonly hasHexTarget: boolean;
@@ -72,6 +80,7 @@ declare class ColorPickerController extends Controller<HTMLElement> {
     valueValue: string;
     alphaValue: boolean;
     logicalTrackValue: boolean;
+    /** Seeds the model from the initial hex value and renders every surface. */
     connect(): void;
     /** Cancels any active pointer drag so document listeners never leak. */
     disconnect(): void;

package/dist/controllers/color_picker_controller.js

@@ -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,12 +181,24 @@ 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.
@@ -202,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() {