stimeo-ui 0.7.0 → 0.9.0

data/dist/controllers/clipboard_controller.js

@@ -2,6 +2,46 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/clipboard_controller.ts
 
+// src/utils/announce.ts
+function announce(message, options = {}) {
+  const text = message.trim();
+  if (text.length === 0) return;
+  window.dispatchEvent(
+    new CustomEvent("stimeo--announcer:announce", {
+      detail: { message: text, assertive: options.assertive === true }
+    })
+  );
+}
+
+// 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/default_attribute.ts
 function setDefaultAttribute(element, name, value) {
   if (element.hasAttribute(name)) return false;
@@ -63,45 +103,59 @@ var SafeTimeout = class extends TimerRegistry {
 };
 
 // src/controllers/clipboard_controller.ts
+var TRANSIENT_STATES = /* @__PURE__ */ new Set(["copied", "error"]);
 var ClipboardController = class extends Controller {
   static targets = ["source", "button", "feedback"];
   static values = {
     text: { type: String, default: "" },
     feedbackDuration: { type: Number, default: 2e3 },
     copiedLabel: { type: String, default: "Copied" },
-    errorLabel: { type: String, default: "Copy failed" }
+    errorLabel: { type: String, default: "Copy failed" },
+    announceCopiedText: { type: String, default: "" },
+    announceErrorText: { type: String, default: "" }
   };
   static actions = ["copy"];
   static events = ["copy"];
-  /** Auto-clear timer for the completion notice; torn down on disconnect. */
+  /**
+   * The pending return to idle — the only timer this controller schedules, so
+   * `clearAll()` is exactly "drop the auto-clear" and needs no id of its own.
+   */
   #timers = new SafeTimeout();
+  /** Returns the completion state to idle for the snapshot Turbo takes. */
+  #beforeCache = new BeforeCacheReset(() => this.#rewind());
   /**
-   * The pending auto-clear timer id, or `null` when none is scheduled. Tracked so
-   * a rapid second copy cancels the first window instead of letting a stale timer
-   * reset the freshly-shown notice early.
+   * Whether this connection is still live. `copy()` suspends on the Clipboard API,
+   * and a teardown that lands while it is suspended must win: the continuation
+   * would otherwise write to an element nobody owns and arm a timer past the
+   * `clearAll()` that was supposed to be the last word.
    */
-  #resetTimerId = null;
+  #connected = false;
   connect() {
-    setDefaultAttribute(this.element, "data-state", "idle");
+    this.#connected = true;
+    this.#adopt();
+    this.#beforeCache.activate();
   }
   disconnect() {
+    this.#connected = false;
+    this.#beforeCache.deactivate();
     this.#timers.clearAll();
   }
   /**
    * Copies the resolved text and reports the outcome. Bound via `data-action`
-   * (click). Always dispatches `stimeo--clipboard:copy` with `{ success, text }`
-   * — including on failure — so consumers can react either way.
+   * (click). Dispatches `stimeo--clipboard:copy` with `{ success, text }` once per
+   * completed attempt — including on failure — so consumers can react either way.
+   * An attempt whose connection ended while it was in flight reports nothing.
    */
   async copy() {
     const text = this.#resolveText();
     let success = false;
     try {
-      if (!navigator.clipboard?.writeText) throw new Error("Clipboard API unavailable");
       await navigator.clipboard.writeText(text);
       success = true;
     } catch {
       success = false;
     }
+    if (!this.#connected) return;
     this.#reportResult(success);
     this.dispatch("copy", { detail: { success, text } });
   }
@@ -118,24 +172,52 @@ var ClipboardController = class extends Controller {
     }
     return source.textContent ?? "";
   }
-  /** Reflects the result on `data-state`, announces it, and schedules a reset. */
+  /**
+   * Reads the current state back from the DOM.
+   *
+   * A `copied` or `error` found at connect time is this controller's own output
+   * from a connection that is gone, and so is the timer that would have cleared it
+   * — nothing else would ever return the element to `idle`. Any other authored
+   * value belongs to the consumer and only a missing attribute takes the default.
+   */
+  #adopt() {
+    if (this.#inTransientState()) {
+      this.#reset();
+      return;
+    }
+    setDefaultAttribute(this.element, "data-state", "idle");
+  }
+  /** Whether `data-state` currently holds one of the values this controller writes. */
+  #inTransientState() {
+    const state = this.element.getAttribute("data-state");
+    return state !== null && TRANSIENT_STATES.has(state);
+  }
+  /**
+   * Returns the completion state to idle for the snapshot Turbo is about to take,
+   * so a page reached with the Back button does not report a copy that happened
+   * before the navigation. Only a state this controller wrote is rewound — an
+   * authored one is the consumer's and has to survive into the snapshot, exactly as
+   * `connect()` leaves it alone. State only — no `copy` is dispatched, which would
+   * claim a fresh copy ran.
+   */
+  #rewind() {
+    if (!this.#inTransientState()) return;
+    this.#timers.clearAll();
+    this.#reset();
+  }
+  /** Reflects the result, announces it, and schedules the return to idle. */
   #reportResult(success) {
     this.element.setAttribute("data-state", success ? "copied" : "error");
     if (this.hasFeedbackTarget) {
       this.feedbackTarget.textContent = success ? this.copiedLabelValue : this.errorLabelValue;
     }
-    if (this.#resetTimerId !== null) {
-      this.#timers.clear(this.#resetTimerId);
-      this.#resetTimerId = null;
-    }
+    announce(success ? this.announceCopiedTextValue : this.announceErrorTextValue);
+    this.#timers.clearAll();
     if (this.feedbackDurationValue > 0) {
-      this.#resetTimerId = this.#timers.set(() => {
-        this.#resetTimerId = null;
-        this.#reset();
-      }, this.feedbackDurationValue);
+      this.#timers.set(() => this.#reset(), this.feedbackDurationValue);
     }
   }
-  /** Returns to the idle state and clears the completion notice. */
+  /** Returns to the idle state and empties the completion slot. */
   #reset() {
     this.element.setAttribute("data-state", "idle");
     if (this.hasFeedbackTarget) {

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}`;