stimeo-ui 0.8.0 → 0.9.0

data/dist/controllers/color_picker_controller.js

@@ -58,8 +58,62 @@ var MicrotaskCoalescer = class {
   }
 };
 
+// src/utils/owned_pointer_session.ts
+var OwnedPointerSession = class {
+  pointerId;
+  #owner;
+  #handlers;
+  #abort = new AbortController();
+  #active = true;
+  constructor(start, owner, handlers) {
+    this.pointerId = start.pointerId;
+    this.#owner = owner;
+    this.#handlers = handlers;
+    const { signal } = this.#abort;
+    owner.ownerDocument.addEventListener("pointermove", this.#onMove, { signal });
+    owner.ownerDocument.addEventListener("pointerup", this.#onEndEvent, { signal });
+    owner.ownerDocument.addEventListener("pointercancel", this.#onEndEvent, { signal });
+    owner.addEventListener("lostpointercapture", this.#onLostCapture, { signal });
+    try {
+      owner.setPointerCapture?.(this.pointerId);
+    } catch {
+    }
+  }
+  /** Whether this session still owns its pointer and listeners. */
+  get active() {
+    return this.#active;
+  }
+  /** Whether `event` belongs to the initiating pointer of the live session. */
+  owns(event) {
+    return this.#active && event.pointerId === this.pointerId;
+  }
+  /** Releases capture/listeners and invokes the end callback exactly once. */
+  end() {
+    if (!this.#active) return;
+    this.#active = false;
+    this.#abort.abort();
+    try {
+      this.#owner.releasePointerCapture?.(this.pointerId);
+    } catch {
+    }
+    this.#handlers.end?.();
+  }
+  #onMove = (event) => {
+    if (this.owns(event)) this.#handlers.move(event);
+  };
+  #onEndEvent = (event) => {
+    if (this.owns(event)) this.end();
+  };
+  #onLostCapture = (event) => {
+    const pointerId = event.pointerId;
+    if (typeof pointerId === "number" && pointerId !== this.pointerId) return;
+    this.end();
+  };
+};
+
 // src/controllers/color_picker_controller.ts
 var COLOR_PROPERTY = "--stimeo--color";
+var VALUE_TEXT_ATTRIBUTE = "data-value-text";
 var CHANNEL_RANGE = {
   hue: [0, 360],
   saturation: [0, 100],
@@ -79,10 +133,10 @@ var ColorPickerController = class extends Controller {
   get #mirrored() {
     return this.logicalTrackValue && isRtl(this.element);
   }
-  /** The current color in the editing model. */
+  /** The current color in the editing model; its alpha is 100 while `alpha` is off. */
   #color = { hue: 0, saturation: 0, lightness: 0, alpha: 100 };
-  /** Aborts in-progress pointer-drag listeners on drag end / teardown. */
-  #dragAbort = null;
+  /** The pointer that owns the live drag, with the slider whose geometry maps it. */
+  #drag = null;
   /** Color the last repaint settled on, so a configuration-driven move is reported once. */
   #committedHex = null;
   /**
@@ -93,25 +147,48 @@ var ColorPickerController = class extends Controller {
   /** Seeds the model from the initial hex value and renders every surface. */
   connect() {
     this.#repaint.activate();
-    const parsed = hexToHsla(this.valueValue);
-    if (parsed) this.#color = this.alphaValue ? parsed : { ...parsed, alpha: 100 };
+    this.#adoptValue();
     this.#render();
   }
   /** Cancels any active pointer drag so document listeners never leak. */
   disconnect() {
     this.#repaint.cancel();
-    this.#dragAbort?.abort();
-    this.#dragAbort = null;
+    this.#endDrag();
   }
   /** Repaints when application code (or a Turbo morph) changes `alpha` at runtime. */
   alphaValueChanged() {
     this.#repaint.schedule();
   }
+  /** Adopts a color application code (or a Turbo morph) put in `value` at runtime. */
+  valueValueChanged() {
+    if (this.valueValue === this.#committedHex) return;
+    this.#repaint.schedule();
+  }
+  /** Hydrates a channel slider inserted or replaced at runtime. */
+  sliderTargetConnected(slider) {
+    this.#renderSlider(slider);
+  }
+  /** Ends a gesture whose geometry target disappeared or ceased being a target. */
+  sliderTargetDisconnected(slider) {
+    if (this.#drag?.slider === slider) this.#endDrag();
+  }
+  /** Fills a hex input inserted or replaced at runtime with the current color. */
+  hexTargetConnected(hex) {
+    this.#mirrorColor(hex, this.#hexString());
+  }
+  /** Fills a form field inserted or replaced at runtime with the current color. */
+  fieldTargetConnected(field) {
+    this.#mirrorColor(field, this.#hexString());
+  }
+  /** Publishes the current color on a preview inserted or replaced at runtime. */
+  previewTargetConnected(preview) {
+    this.#publishColor(preview, this.#hexString());
+  }
   /** Keyboard stepping on the focused channel slider (APG Slider model). */
   onKeydown(event) {
     if (isReservedArrowChord(event)) return;
     const slider = event.currentTarget;
-    const channel = this.#channelOf(slider);
+    const channel = this.#editableChannel(slider);
     if (!channel) return;
     const [min, max] = this.#rangeOf(slider, channel);
     const value = this.#color[channel];
@@ -143,34 +220,36 @@ var ColorPickerController = class extends Controller {
     event.preventDefault();
     this.#setChannel(channel, next, min, max);
   }
-  /** Begins a pointer drag on a channel slider and tracks movement. */
+  /** Begins a primary-button drag on a channel slider, owned by its own pointer. */
   onPointerDown(event) {
+    if (event.button !== 0 || this.#drag) return;
     const slider = event.currentTarget;
-    const channel = this.#channelOf(slider);
+    const channel = this.#editableChannel(slider);
     if (!channel) return;
-    event.preventDefault();
-    slider.focus();
     const [min, max] = this.#rangeOf(slider, channel);
     const mirrored = this.#mirrored;
     const update = (clientX) => {
       const rect = slider.getBoundingClientRect();
-      if (rect.width === 0) return;
+      if (rect.width === 0) return false;
       const offset = Math.min(1, Math.max(0, (clientX - rect.left) / rect.width));
       const fraction = mirrored ? 1 - offset : offset;
       this.#setChannel(channel, min + fraction * (max - min), min, max);
+      return true;
     };
-    update(event.clientX);
-    this.#dragAbort?.abort();
-    const abort = new AbortController();
-    this.#dragAbort = abort;
-    const onMove = (move) => update(move.clientX);
-    const onUp = () => {
-      abort.abort();
-      this.#dragAbort = null;
-    };
-    document.addEventListener("pointermove", onMove, { signal: abort.signal });
-    document.addEventListener("pointerup", onUp, { signal: abort.signal });
-    document.addEventListener("pointercancel", onUp, { signal: abort.signal });
+    if (!update(event.clientX)) return;
+    event.preventDefault();
+    slider.focus();
+    const drag = { pointer: null, slider };
+    drag.pointer = new OwnedPointerSession(event, slider, {
+      move: (move) => {
+        if (slider.isConnected) update(move.clientX);
+        else this.#endDrag();
+      },
+      end: () => {
+        if (this.#drag === drag) this.#drag = null;
+      }
+    });
+    this.#drag = drag;
   }
   /** Parses the hex input on confirm and syncs every channel + surface. */
   onHexInput() {
@@ -180,9 +259,22 @@ var ColorPickerController = class extends Controller {
       this.hexTarget.value = this.#hexString();
       return;
     }
-    this.#color = this.alphaValue ? parsed : { ...parsed, alpha: 100 };
+    this.#color = this.#opaqueUnlessEnabled(parsed);
     this.#commitColor();
   }
+  /** Replaces the model with the color `value` names, leaving an unparsable one alone. */
+  #adoptValue() {
+    const parsed = hexToHsla(this.valueValue);
+    if (parsed) this.#color = this.#opaqueUnlessEnabled(parsed);
+  }
+  /**
+   * The model a parsed color implies: alpha only survives while its channel is
+   * enabled, because `hexString()` would otherwise emit `#RRGGBB` while `change`
+   * reported `rgba.a < 1`.
+   */
+  #opaqueUnlessEnabled(parsed) {
+    return this.alphaValue ? parsed : { ...parsed, alpha: 100 };
+  }
   /** 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)));
@@ -201,32 +293,57 @@ var ColorPickerController = class extends Controller {
     }
   }
   /**
-   * Reflects the model onto sliders, the hex input, preview, and form field.
+   * Reflects the model onto sliders, the hex input, preview, form field, and the
+   * `value` Value it serializes into.
    *
    * @stimeoRenderRoot
    */
   #render() {
-    for (const slider of this.sliderTargets) {
-      const channel = this.#channelOf(slider);
-      if (!channel) continue;
-      const value = this.#color[channel];
-      slider.setAttribute("aria-valuenow", String(value));
-      slider.setAttribute("aria-valuetext", valueText(channel, value));
-    }
+    for (const slider of this.sliderTargets) this.#renderSlider(slider);
     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);
+    if (this.valueValue !== hex) this.valueValue = hex;
+    if (this.hasHexTarget) this.#mirrorColor(this.hexTarget, hex);
+    for (const field of this.fieldTargets) this.#mirrorColor(field, hex);
+    for (const preview of this.previewTargets) this.#publishColor(preview, hex);
+    this.#publishColor(this.element, hex);
+  }
+  /** Writes one slider's announced range, value, and value text, skipping equal ones. */
+  #renderSlider(slider) {
+    const channel = this.#channelOf(slider);
+    if (!channel) return;
+    const [min, max] = this.#rangeOf(slider, channel);
+    const value = this.#color[channel];
+    const attributes = {
+      "aria-valuemin": String(min),
+      "aria-valuemax": String(max),
+      "aria-valuenow": String(value),
+      "aria-valuetext": this.#valueText(slider, channel, value)
+    };
+    for (const [name, next] of Object.entries(attributes)) {
+      if (slider.getAttribute(name) !== next) slider.setAttribute(name, next);
+    }
+  }
+  /** Mirrors the color into an input, leaving an already-equal value untouched. */
+  #mirrorColor(input, hex) {
+    if (input.value !== hex) input.value = hex;
+  }
+  /** Publishes the color as the consumer's CSS hook, skipping an equal value. */
+  #publishColor(element, hex) {
+    if (element.style.getPropertyValue(COLOR_PROPERTY) !== hex) {
+      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.
+   * Repaints after a declarative input changed at runtime and reports a color this
+   * controller settled on. Disabling alpha drops it from the model and an outside
+   * `value` names another color, so the committed color can move without a user
+   * edit; `change` stays reserved for the picker's own actions.
    */
   #reconcileColor() {
     const previous = this.#committedHex;
+    if (previous !== null && this.valueValue !== previous) this.#adoptValue();
+    if (!this.alphaValue) this.#color.alpha = 100;
     this.#render();
     if (previous !== null && this.#committedHex !== previous) {
       this.dispatch("reconcile", { detail: this.#settledDetail() });
@@ -247,7 +364,27 @@ var ColorPickerController = class extends Controller {
   /** Reads a slider's `data-channel`, if it is a known channel. */
   #channelOf(slider) {
     const channel = slider.getAttribute("data-channel");
-    return channel && channel in CHANNEL_RANGE ? channel : null;
+    return channel && Object.hasOwn(CHANNEL_RANGE, channel) ? channel : null;
+  }
+  /**
+   * The channel a slider edits, or null when this picker edits none through it. An
+   * alpha slider authored while `alpha` is off edits nothing: moving it would leave
+   * the model translucent behind an opaque `#RRGGBB`.
+   */
+  #editableChannel(slider) {
+    const channel = this.#channelOf(slider);
+    return channel === "alpha" && !this.alphaValue ? null : channel;
+  }
+  /** The channel's announced text: the slider's template, or the built-in English. */
+  #valueText(slider, channel, value) {
+    const template = slider.getAttribute(VALUE_TEXT_ATTRIBUTE);
+    return template ? template.replaceAll("{value}", String(value)) : defaultValueText(channel, value);
+  }
+  /** Ends the live drag so no further movement of that pointer reaches the model. */
+  #endDrag() {
+    const drag = this.#drag;
+    this.#drag = null;
+    drag?.pointer?.end();
   }
   /**
    * A slider's `[min, max]` from aria-valuemin/max, falling back per channel.
@@ -263,7 +400,7 @@ var ColorPickerController = class extends Controller {
     ];
   }
 };
-function valueText(channel, value) {
+function defaultValueText(channel, value) {
   const label = channel.charAt(0).toUpperCase() + channel.slice(1);
   const unit = channel === "hue" ? "degrees" : "percent";
   return `${label} ${value} ${unit}`;

data/dist/controllers/data_grid_controller.js

@@ -18,6 +18,56 @@ 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/interactive_host.ts
+var INTERACTIVE_HOST_SELECTOR = "button, input, select, textarea, label, a[href], area[href], summary, details, audio[controls], video[controls], iframe, object, embed";
+function isInteractiveHost(element) {
+  if (element.matches(INTERACTIVE_HOST_SELECTOR)) return true;
+  let current = element;
+  while (current) {
+    const raw = current.getAttribute("contenteditable");
+    if (raw !== null) {
+      const value = raw.trim().toLowerCase();
+      if (value === "false") return false;
+      if (value === "" || value === "true" || value === "plaintext-only") return true;
+    }
+    current = current.parentElement;
+  }
+  return false;
+}
+
+// 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/data_grid_controller.ts
 var SORT_CYCLE = ["none", "ascending", "descending"];
 function nextSortDirection(current) {
@@ -32,8 +82,15 @@ var DataGridController = class extends Controller {
   };
   static actions = ["onKeydown", "sort", "toggleSelect"];
   static events = ["selectionchange", "sort"];
-  /** Gates the row callback so it does not re-walk every row once per authored row on mount. */
-  #connected = false;
+  /**
+   * Collapses the per-element target callbacks of one DOM mutation into a single
+   * baseline pass, and refuses to run before `connect()` or after `disconnect()`.
+   *
+   * Stimulus reports every target one at a time, so an ungated pass would re-walk
+   * the whole grid once per authored cell on mount and once per streamed cell
+   * afterwards — quadratic in the cell count both times.
+   */
+  #reconcile = new MicrotaskCoalescer(() => this.#restoreBaseline());
   /**
    * Establishes a single tab stop across all navigable cells/headers and brings
    * the rows to their baseline.
@@ -44,15 +101,30 @@ var DataGridController = class extends Controller {
    * attribute, so the Value callback does not fire a second time.
    */
   connect() {
+    this.#restoreBaseline();
+    this.#reconcile.activate();
+  }
+  /** Closes the reconcile window so a queued pass cannot run against a detached tree. */
+  disconnect() {
+    this.#reconcile.cancel();
+  }
+  /**
+   * Rebuilds both DOM-owned baselines from the live grid: exactly one navigable
+   * cell is in the Tab sequence, and every selectable row carries an explicit
+   * `aria-selected`.
+   *
+   * The tab stop keeps whichever cell already holds it, so a rebuild triggered by
+   * an unrelated row arriving does not throw the user's position away; only when
+   * no cell holds it — the grid is fresh, or the holder was removed — does the
+   * first navigable cell take over. Without that fallback a grid whose active row
+   * is removed keeps every cell at `-1` and drops out of the Tab sequence
+   * entirely.
+   */
+  #restoreBaseline() {
     const cells = this.#navigableCells();
     const active = cells.find((cell) => cell.tabIndex === 0) ?? cells[0];
-    this.#setActiveCell(active, { focus: false });
+    if (active) this.#setActiveCell(active, { focus: false }, cells);
     this.#normalizeSelection();
-    this.#connected = true;
-  }
-  /** Reopens the row callback for the next mount. */
-  disconnect() {
-    this.#connected = false;
   }
   /**
    * Keeps `aria-multiselectable` in step with the `selection` Value. Fires on connect
@@ -63,16 +135,25 @@ var DataGridController = class extends Controller {
     this.#syncSelectable();
     this.#normalizeSelection();
   }
-  /**
-   * Re-establishes the row baseline for a row added after connect.
-   *
-   * Each pass walks every row, and Stimulus reports the authored rows one by one
-   * before `connect()`, so the mount is gated to keep it linear in the row count
-   * rather than quadratic; `connect()` runs the single baseline pass instead.
-   */
+  /** Re-establishes the baselines for a row added after connect. */
   rowTargetConnected() {
-    if (!this.#connected) return;
-    this.#normalizeSelection();
+    this.#reconcile.schedule();
+  }
+  /** Re-establishes the tab stop when a cell joins the grid after connect. */
+  cellTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /** Re-establishes the tab stop when a cell leaves the grid. */
+  cellTargetDisconnected() {
+    this.#reconcile.schedule();
+  }
+  /** Re-establishes the tab stop when a header joins the grid after connect. */
+  columnHeaderTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /** Re-establishes the tab stop when a header leaves the grid. */
+  columnHeaderTargetDisconnected() {
+    this.#reconcile.schedule();
   }
   /**
    * Brings the authored rows to the shape the APG requires, without changing
@@ -117,6 +198,9 @@ var DataGridController = class extends Controller {
   sort(event) {
     const header = event.currentTarget;
     if (!this.columnHeaderTargets.includes(header)) return;
+    if (event.defaultPrevented) return;
+    const control = this.#claimingControl(event, header);
+    if (control && !(control instanceof HTMLButtonElement)) return;
     const direction = nextSortDirection(header.getAttribute("aria-sort") ?? "none");
     for (const other of this.columnHeaderTargets) {
       other.setAttribute("aria-sort", other === header ? direction : "none");
@@ -127,14 +211,19 @@ var DataGridController = class extends Controller {
   /** Toggles selection of the row owning the event target. Bound optionally. */
   toggleSelect(event) {
     if (this.selectionValue === "none") return;
-    const row = event.currentTarget.closest("[role='row']");
+    if (event.defaultPrevented) return;
+    const host = event.currentTarget;
+    if (this.#claimedByDescendant(event, host)) return;
+    const row = host.closest("[role='row']");
     if (row && this.rowTargets.includes(row)) this.#toggleRow(row);
   }
   /** Grid navigation + sort/select activation. Bound to cells and headers. */
   onKeydown(event) {
     if (event.defaultPrevented) return;
     if (isReservedArrowChord(event)) return;
+    if (event.isComposing) return;
     const cell = event.currentTarget;
+    if (this.#claimedByDescendant(event, cell)) return;
     const matrix = this.#matrix();
     const position = this.#locate(matrix, cell);
     if (!position) return;
@@ -170,9 +259,35 @@ var DataGridController = class extends Controller {
     }
     if (target) {
       event.preventDefault();
-      this.#setActiveCell(target, { focus: true });
+      this.#setActiveCell(target, { focus: true }, matrix.flat());
     }
   }
+  /**
+   * Whether the event was addressed to a control inside `host` rather than to the
+   * grid.
+   *
+   * Cells and headers hold consumer markup, and APG's grid pattern expects that
+   * markup to include working controls — a row action button, an inline editor.
+   * Those own their own keystrokes and clicks, so the grid stands down entirely
+   * rather than acting in parallel. An editable host (its `contenteditable` state
+   * is inherited, so the walk is explicit) counts the same way.
+   */
+  #claimedByDescendant(event, host) {
+    return this.#claimingControl(event, host) !== null;
+  }
+  /**
+   * The nested control this event belongs to, or `null` when the host owns it.
+   *
+   * Naming the control, rather than answering yes or no, is what lets the click
+   * path treat a sortable header's `<button>` as the activation it is while every
+   * other control still takes the event away.
+   */
+  #claimingControl(event, host) {
+    const source = event.target;
+    const control = source.closest(INTERACTIVE_HOST_SELECTOR);
+    if (control && host.contains(control)) return control;
+    return isInteractiveHost(source) ? source : null;
+  }
   /** Performs a header's sort or a cell row's selection toggle on activation. */
   #activate(cell) {
     if (this.columnHeaderTargets.includes(cell)) {
@@ -203,11 +318,22 @@ var DataGridController = class extends Controller {
     const rows = this.rowTargets.filter((r) => r.getAttribute("aria-selected") === "true");
     this.dispatch("selectionchange", { detail: { rows } });
   }
-  /** Makes `cell` the single tabbable cell (roving) and optionally focuses it. */
-  #setActiveCell(cell, { focus }) {
-    if (!cell) return;
-    for (const candidate of this.#navigableCells()) {
-      candidate.tabIndex = candidate === cell ? 0 : -1;
+  /**
+   * Makes `cell` the single tabbable cell (roving) and optionally focuses it.
+   *
+   * `cells` lets a caller that already walked the grid hand its collection over,
+   * so one keystroke rebuilds the matrix once instead of twice. The write is
+   * skipped where the attribute already holds the wanted value — comparing the
+   * attribute rather than the IDL property, because a cell with no `tabindex` at
+   * all reports `-1` and would then never receive the attribute it needs to be
+   * focusable.
+   */
+  #setActiveCell(cell, { focus }, cells) {
+    for (const candidate of cells ?? this.#navigableCells()) {
+      const wanted = candidate === cell ? "0" : "-1";
+      if (candidate.getAttribute("tabindex") !== wanted) {
+        candidate.setAttribute("tabindex", wanted);
+      }
     }
     if (focus) cell.focus();
   }