stimeo-ui 0.4.0 → 0.6.0

package/dist/controllers/rating_controller.js

@@ -13,6 +13,72 @@ 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/attribute_lease.ts
+var AttributeLease = class {
+  #attribute;
+  #records = /* @__PURE__ */ new Map();
+  /** @param attribute - The attribute whose temporary values this lease owns. */
+  constructor(attribute) {
+    this.#attribute = attribute;
+  }
+  /** Writes or removes the leased attribute while preserving its authored value. */
+  write(element, value) {
+    const existing = this.#records.get(element);
+    if (existing) {
+      existing.written = value;
+    } else {
+      this.#records.set(element, {
+        original: element.getAttribute(this.#attribute),
+        written: value
+      });
+    }
+    if (value === null) element.removeAttribute(this.#attribute);
+    else element.setAttribute(this.#attribute, value);
+  }
+  /** Returns one lease without overwriting a value subsequently authored by a consumer. */
+  return(element) {
+    const record = this.#records.get(element);
+    if (!record) return;
+    this.#records.delete(element);
+    if (element.getAttribute(this.#attribute) !== record.written) return;
+    if (record.original === null) element.removeAttribute(this.#attribute);
+    else element.setAttribute(this.#attribute, record.original);
+  }
+  /** Returns every outstanding lease using the same ownership check as {@link return}. */
+  returnAll() {
+    for (const element of Array.from(this.#records.keys())) this.return(element);
+  }
+};
+
+// 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/microtask_coalescer.ts
 var MicrotaskCoalescer = class {
   #run;
@@ -68,10 +134,12 @@ var RovingTabindex = class {
    * "nothing is currently tabbable".
    *
    * @param index - Position of the item to make tabbable.
-   * @param options - Pass `{ focus: true }` to also move DOM focus to that item.
+   * @param options - Pass `{ focus: true }` to also move DOM focus to that item,
+   *   and `items` to reuse an event-scoped collection snapshot.
    */
-  setActive(index, { focus = false } = {}) {
-    const items = this.#getItems();
+  setActive(index, options = {}) {
+    const { focus = false } = options;
+    const items = options.items ?? this.#getItems();
     items.forEach((item, i) => {
       item.tabIndex = i === index ? 0 : -1;
     });
@@ -79,165 +147,282 @@ var RovingTabindex = class {
   }
 };
 
+// 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/rating_controller.ts
 var RatingController = class extends Controller {
   static targets = ["symbol", "field"];
   static values = {
     value: { type: Number, default: 0 },
-    max: { type: Number, default: 5 },
     clearable: { type: Boolean, default: true },
     readonly: { type: Boolean, default: false }
   };
   static actions = ["endPreview", "onKeydown", "preview", "select"];
-  static events = ["change"];
+  static events = ["change", "reconcile"];
   #roving = new RovingTabindex(() => this.symbolTargets);
-  /** Reflects the initial value, or switches to the non-interactive readonly view. */
-  /**
-   * Collapses a morph that swaps render inputs into one repaint, and refuses the
-   * pass Stimulus delivers before `connect()`.
-   */
-  #repaint = new MicrotaskCoalescer(() => {
-    if (this.readonlyValue) {
-      this.#applyReadonly();
-      return;
-    }
-    this.#apply(this.#clamp(this.valueValue), { focus: false });
-  });
+  #rootRole = new AttributeLease("role");
+  #symbolRole = new AttributeLease("role");
+  #symbolAriaHidden = new AttributeLease("aria-hidden");
+  #rootTabindex = new TabindexLoan();
+  #repaint = new MicrotaskCoalescer(() => this.#reconcileScale());
+  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
+  #connected = false;
+  #rescuedFocus = false;
+  /** Reflects declarative state without announcing an initial user change. */
   connect() {
     this.#repaint.activate();
-    if (this.readonlyValue) {
-      this.#applyReadonly();
-      return;
-    }
-    this.#apply(this.#clamp(this.valueValue), { focus: false });
+    this.#beforeCache.activate();
+    this.#apply(this.#normalize(this.valueValue), { focus: false });
+    this.#connected = true;
   }
-  /** Closes the window in which a queued repaint may still run. */
+  /** Drops a queued reconciliation and hands every borrowed attribute back. */
   disconnect() {
+    this.#connected = false;
     this.#repaint.cancel();
+    this.#beforeCache.deactivate();
+    this.#releaseReadonly();
+  }
+  /** Removes a runtime-added symbol's authored Tab stop before the batch repaint. */
+  symbolTargetConnected(symbol) {
+    if (this.#connected === false) return;
+    symbol.tabIndex = -1;
+    this.#repaint.schedule();
+  }
+  /** Releases readonly ownership and reconciles the remaining DOM-ordered scale. */
+  symbolTargetDisconnected(symbol) {
+    this.#symbolRole.return(symbol);
+    this.#symbolAriaHidden.return(symbol);
+    this.#repaint.schedule();
+  }
+  /** Reflects into a hidden field added or replaced after connection. */
+  fieldTargetConnected() {
+    this.#repaint.schedule();
   }
-  /** Repaints when application code (or a Turbo morph) changes `value` at runtime. */
+  /** Reconciles after a hidden field is removed or replaced. */
+  fieldTargetDisconnected() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code or a Turbo morph changes `value`. */
   valueValueChanged() {
     this.#repaint.schedule();
   }
-  /** Selects (or clears) the clicked symbol. Bound via `data-action` (click). */
+  /** Repaints when application code changes whether value 0 is permitted. */
+  clearableValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code enters or leaves the readonly snapshot. */
+  readonlyValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Selects or clears the clicked symbol. Bound via `data-action` (click). */
   select(event) {
     if (this.readonlyValue) return;
-    const value = this.#clamp(this.#symbolValue(event.currentTarget));
-    if (this.clearableValue && value === this.valueValue) {
-      this.#render(0, { focus: true });
-    } else {
-      this.#render(value, { focus: false });
-    }
+    const ordinal = this.#symbolOrdinal(event.currentTarget);
+    if (ordinal === null) return;
+    const current = this.#normalize(this.valueValue);
+    this.#commit(this.clearableValue && ordinal === current ? 0 : ordinal, {
+      focus: ordinal === current
+    });
   }
-  /** Previews a fill range on hover/focus. Bound via `data-action` (mouseenter/focus). */
+  /** Previews a fill range on hover or focus without committing it. */
   preview(event) {
     if (this.readonlyValue) return;
-    this.#setFillRange(this.#clamp(this.#symbolValue(event.currentTarget)));
+    const ordinal = this.#symbolOrdinal(event.currentTarget);
+    if (ordinal !== null) this.#setFillRange(ordinal);
   }
-  /** Restores the fill range to the selected value. Bound via `data-action` (mouseleave/blur). */
+  /** Restores the fill range after hover or focus leaves a symbol. */
   endPreview() {
     if (this.readonlyValue) return;
-    this.#setFillRange(this.valueValue);
+    this.#setFillRange(this.#normalize(this.valueValue));
   }
-  /** Arrow/Home/End/Space keyboard control, clamped (no wrap). */
+  /** Arrow/Home/End/Space/Delete keyboard control, clamped without wrapping. */
   onKeydown(event) {
-    if (event.defaultPrevented) return;
-    if (isReservedArrowChord(event)) return;
-    if (this.readonlyValue) return;
+    if (event.defaultPrevented || isReservedArrowChord(event) || this.readonlyValue) return;
+    const current = this.#normalize(this.valueValue);
     let next = null;
     const rtl = isRtl(this.element);
     switch (event.key) {
       case "ArrowRight":
       case "ArrowUp":
-        next = this.valueValue + (event.key === "ArrowRight" && rtl ? -1 : 1);
+        next = current + (event.key === "ArrowRight" && rtl ? -1 : 1);
         break;
       case "ArrowLeft":
       case "ArrowDown":
-        next = this.valueValue - (event.key === "ArrowLeft" && rtl ? -1 : 1);
+        next = current - (event.key === "ArrowLeft" && rtl ? -1 : 1);
         break;
       case "Home":
         next = this.#minValue;
         break;
       case "End":
-        next = this.maxValue;
+        next = this.symbolTargets.length;
         break;
       case " ":
       case "Enter":
-        next = this.#symbolValue(event.currentTarget);
+        next = this.#symbolOrdinal(event.currentTarget);
+        break;
+      case "Delete":
+      case "Backspace":
+        if (!this.clearableValue) return;
+        next = 0;
         break;
       default:
         return;
     }
+    if (next === null) return;
     event.preventDefault();
-    this.#render(this.#clamp(next), { focus: true });
+    this.#commit(next, { focus: true });
   }
   /**
-   * Applies `value` (already clamped) everywhere, then dispatches `change`.
-   * Use for user-driven changes; on connect call `#apply` directly so
-   * initialization mirrors state without emitting an event.
+   * Repaints one settled target/Value mutation batch and reports only a value
+   * this controller had to normalize.
+   *
+   * @stimeoRenderRoot
    */
-  #render(value, { focus }) {
+  #reconcileScale() {
+    const requested = this.valueValue;
+    const value = this.#normalize(requested);
+    this.#apply(value, { focus: false });
+    if (!Object.is(value, requested)) {
+      this.dispatch("reconcile", { detail: { value } });
+    }
+  }
+  /** Applies one user operation and emits only when its committed value changes. */
+  #commit(raw, { focus }) {
+    const previous = this.#normalize(this.valueValue);
+    const value = this.#normalize(raw);
     this.#apply(value, { focus });
-    this.dispatch("change", { detail: { value } });
+    if (value !== previous) this.dispatch("change", { detail: { value } });
   }
-  /**
-   * Stores `value`, syncs `aria-checked` and the roving Tab stop, the hidden
-   * field, and the fill range — without dispatching `change`. Idempotent and
-   * safe on connect (and across Turbo morphing).
-   */
+  /** Synchronizes value, ARIA, roving focus, form state, and the visual fill hook. */
   #apply(value, { focus }) {
-    this.valueValue = value;
-    this.symbolTargets.forEach((symbol) => {
-      symbol.setAttribute(
-        "aria-checked",
-        value > 0 && this.#symbolValue(symbol) === value ? "true" : "false"
-      );
+    if (!Object.is(this.valueValue, value)) this.valueValue = value;
+    this.symbolTargets.forEach((symbol, index) => {
+      symbol.setAttribute("aria-checked", value > 0 && index + 1 === value ? "true" : "false");
     });
-    this.#roving.setActive(value > 0 ? value - 1 : 0, { focus });
+    if (this.readonlyValue) {
+      this.#applyReadonly();
+    } else {
+      const returning = this.#releaseReadonly();
+      this.#roving.setActive(value > 0 ? value - 1 : 0, { focus: focus || returning });
+    }
     if (this.hasFieldTarget) this.fieldTarget.value = String(value);
     this.#setFillRange(value);
   }
-  /** Marks symbols up to `range` with `data-rating-hover` (the consumer's fill hook). */
+  /** Marks the first `range` symbols with the consumer-owned fill hook. */
   #setFillRange(range) {
-    for (const symbol of this.symbolTargets) {
-      if (this.#symbolValue(symbol) <= range && range > 0) {
-        symbol.setAttribute("data-rating-hover", "");
-      } else {
-        symbol.removeAttribute("data-rating-hover");
-      }
-    }
+    this.symbolTargets.forEach((symbol, index) => {
+      symbol.toggleAttribute("data-rating-hover", range > 0 && index < range);
+    });
   }
-  /** Turns the group into a non-interactive `role="img"` snapshot of the value. */
+  /**
+   * Temporarily turns the radiogroup into a non-interactive image snapshot.
+   *
+   * Each lease is returned before it is taken again, so a value the consumer
+   * wrote while readonly becomes the value the lease restores on release. The
+   * return is a no-op on an attribute still holding this controller's own
+   * write, which is the ordinary case.
+   */
   #applyReadonly() {
-    const value = this.#clamp(this.valueValue);
-    this.valueValue = value;
-    this.element.setAttribute("role", "img");
+    this.#rescueFocus();
+    this.#rootRole.return(this.element);
+    this.#rootRole.write(this.element, "img");
     for (const symbol of this.symbolTargets) {
-      symbol.removeAttribute("role");
-      symbol.setAttribute("aria-hidden", "true");
-      symbol.tabIndex = -1;
+      this.#symbolRole.return(symbol);
+      this.#symbolRole.write(symbol, null);
+      this.#symbolAriaHidden.return(symbol);
+      this.#symbolAriaHidden.write(symbol, "true");
     }
-    if (this.hasFieldTarget) this.fieldTarget.value = String(value);
-    this.#setFillRange(value);
+    this.#roving.setActive(-1);
   }
   /**
-   * Clamps `value` to `[min, max]` (min is 0 when clearable, else 1). The upper
-   * bound is also capped at the number of symbols so the roving Tab stop
-   * (`value - 1`) always maps to a real symbol — even if the consumer's `max`
-   * value and rendered symbol count disagree, the tabbable item is never lost.
+   * Hands every readonly borrowing back before Turbo clones the page.
+   *
+   * The snapshot is taken while the controller is still connected, so an
+   * element left as `role="img"` with hidden symbols is what a restored page
+   * connects against — and that markup would be read as the authored one,
+   * leaving no way back to the radiogroup. Rewinding first keeps the cached
+   * copy identical to what the consumer wrote.
    */
-  #clamp(value) {
-    const max = Math.min(this.maxValue, this.symbolTargets.length);
-    return Math.min(max, Math.max(this.#minValue, value));
+  #rewindForCache() {
+    this.#releaseReadonly();
+    const value = this.#normalize(this.valueValue);
+    this.#roving.setActive(value > 0 ? value - 1 : 0);
+  }
+  /**
+   * Lands focus on the root before the symbols leave the accessibility tree.
+   *
+   * A symbol holding focus when readonly begins would keep it while losing its
+   * role and gaining `aria-hidden`, stranding the user on a node no longer in
+   * the tree. The root is the one element that survives the transition named:
+   * it carries the consumer's accessible name under `role="img"`.
+   */
+  #rescueFocus() {
+    const active = document.activeElement;
+    if (!(active instanceof HTMLElement) || active === this.element) return;
+    if (!this.element.contains(active)) return;
+    this.#rootTabindex.lend(this.element);
+    this.element.focus();
+    this.#rescuedFocus = true;
+  }
+  /**
+   * Restores authored roles and visibility after leaving readonly mode.
+   *
+   * @returns whether focus is standing on the root because {@link #rescueFocus}
+   *   put it there, and therefore belongs back on the Tab stop.
+   */
+  #releaseReadonly() {
+    const returning = this.#rescuedFocus && document.activeElement === this.element;
+    this.#rescuedFocus = false;
+    this.#rootRole.return(this.element);
+    this.#symbolRole.returnAll();
+    this.#symbolAriaHidden.returnAll();
+    this.#rootTabindex.returnAll();
+    return returning;
+  }
+  /** Normalizes a raw value to an integer ordinal in the live DOM range. */
+  #normalize(raw) {
+    const maximum = this.symbolTargets.length;
+    const ordinal = Number.isFinite(raw) ? Math.round(raw) : this.#minValue;
+    return Math.min(maximum, Math.max(this.#minValue, ordinal));
   }
   /** Lowest selectable value: 0 when clearable, otherwise 1. */
   get #minValue() {
     return this.clearableValue ? 0 : 1;
   }
-  /** A symbol's ordinal value (`data-rating-value`, defaulting to its position). */
-  #symbolValue(symbol) {
-    const raw = Number(symbol.getAttribute("data-rating-value"));
-    return Number.isFinite(raw) && raw > 0 ? raw : this.symbolTargets.indexOf(symbol) + 1;
+  /** Returns a target's 1-based position, or null when the action host is invalid. */
+  #symbolOrdinal(target) {
+    const targets = this.symbolTargets;
+    const index = targets.indexOf(target);
+    return index < 0 ? null : index + 1;
   }
 };