stimeo-ui 0.5.0 → 0.7.0

data/dist/controllers/carousel_controller.js

@@ -20,6 +20,39 @@ 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/microtask_coalescer.ts
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  /** @param run - the single reconciliation pass, invoked at most once per batch. */
+  constructor(run) {
+    this.#run = run;
+  }
+  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
+  activate() {
+    this.#active = true;
+  }
+  /** Closes the window and drops any pending pass; call from `disconnect()`. */
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  schedule() {
+    if (!this.#active || this.#queued) return;
+    this.#queued = true;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
+  }
+};
+
 // src/utils/roving_tabindex.ts
 var RovingTabindex = class {
   /** Returns the current ordered item elements; called on every operation. */
@@ -42,10 +75,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;
     });
@@ -120,9 +155,14 @@ var CarouselController = class extends Controller {
     "resume",
     "togglePlay"
   ];
-  static events = ["change", "pause", "play"];
+  static events = ["change", "pause", "play", "reconcile"];
   #roving = new RovingTabindex(() => this.pickerTargets);
-  /** Gates the target callback so it does not repaint once per authored picker on mount. */
+  #reconcileTargets = new MicrotaskCoalescer(() => this.#reconcileTargetSet());
+  /**
+   * Whether `connect()` has run. Scheduling is already inert outside that window
+   * ({@link MicrotaskCoalescer}), so this only gates the Tab stop a picker
+   * present at mount authored for itself.
+   */
   #connected = false;
   #intervals = new SafeInterval();
   /** Index of the visible slide. */
@@ -148,6 +188,7 @@ var CarouselController = class extends Controller {
     this.#render({ focus: false });
     this.#syncTimer();
     this.#connected = true;
+    this.#reconcileTargets.activate();
   }
   /**
    * Re-establishes the single selected picker when one is added after connect.
@@ -158,9 +199,22 @@ var CarouselController = class extends Controller {
    * repaint re-derives every picker from `#index`, so a late arrival never steals
    * the selection.
    */
-  pickerTargetConnected() {
+  pickerTargetConnected(picker) {
     if (!this.#connected) return;
-    this.#render({ focus: false });
+    picker.tabIndex = -1;
+    this.#reconcileTargets.schedule();
+  }
+  /** Repairs selection and roving after a picker leaves a retained carousel. */
+  pickerTargetDisconnected() {
+    this.#reconcileTargets.schedule();
+  }
+  /** Reconciles a slide added in the same DOM batch as its picker. */
+  slideTargetConnected() {
+    this.#reconcileTargets.schedule();
+  }
+  /** Re-clamps the active index after a slide is removed. */
+  slideTargetDisconnected() {
+    this.#reconcileTargets.schedule();
   }
   /**
    * Resolves the starting autoplay intent. The play toggle's `aria-pressed` is the
@@ -178,6 +232,7 @@ var CarouselController = class extends Controller {
   /** Clears the autoplay interval so it never fires after teardown. */
   disconnect() {
     this.#connected = false;
+    this.#reconcileTargets.cancel();
     this.#intervals.clearAll();
     this.#timerId = null;
   }
@@ -282,10 +337,31 @@ var CarouselController = class extends Controller {
       slide.setAttribute("data-state", active ? "active" : "inactive");
       slide.hidden = !active;
     });
+    const pickerIndex = Math.min(this.#index, this.pickerTargets.length - 1);
     this.pickerTargets.forEach((picker, i) => {
-      picker.setAttribute("aria-selected", i === this.#index ? "true" : "false");
+      picker.setAttribute("aria-selected", i === pickerIndex ? "true" : "false");
     });
-    this.#roving.setActive(this.#index, { focus });
+    this.#roving.setActive(pickerIndex, { focus });
+  }
+  /** Keeps the live active slide when possible and otherwise selects the nearest survivor. */
+  #reconcileTargetSet() {
+    const activeSlide = this.slideTargets.findIndex(
+      (slide) => slide.getAttribute("data-state") === "active"
+    );
+    const selectedPicker = this.pickerTargets.findIndex(
+      (picker) => picker.getAttribute("aria-selected") === "true"
+    );
+    const lastSlide = this.slideTargets.length - 1;
+    const candidate = activeSlide !== -1 ? activeSlide : selectedPicker !== -1 ? selectedPicker : this.#index;
+    const previous = this.#index;
+    this.#index = lastSlide < 0 ? 0 : Math.min(lastSlide, Math.max(0, candidate));
+    this.#render({ focus: false });
+    this.#syncTimer();
+    if (this.#index !== previous) {
+      this.dispatch("reconcile", {
+        detail: { index: this.#index, total: this.slideTargets.length }
+      });
+    }
   }
   /**
    * Drives the autoplay interval toward the desired state. Autoplay should run

data/dist/controllers/character_counter_controller.js

@@ -2,6 +2,93 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/character_counter_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 }
+    })
+  );
+}
+function fillTemplate(template, values) {
+  return template.replace(/\{([a-zA-Z][a-zA-Z0-9]*)\}/g, (match, name) => {
+    const replacement = values[name];
+    return replacement === void 0 ? match : String(replacement);
+  });
+}
+
+// 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
+      });
+    }
+    this.#reflect(element, 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);
+    const stillOwned = element.getAttribute(this.#attribute) === record.written;
+    if (stillOwned) this.#reflect(element, record.original);
+  }
+  /** Reflects only a real value transition, avoiding self-triggered mutation work. */
+  #reflect(element, value) {
+    if (element.getAttribute(this.#attribute) === value) return;
+    if (value === null) element.removeAttribute(this.#attribute);
+    else element.setAttribute(this.#attribute, value);
+  }
+  /** 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/composition_tracker.ts
 var CompositionTracker = class {
   #observedTargets = /* @__PURE__ */ new Set();
@@ -49,6 +136,39 @@ var CompositionTracker = class {
   };
 };
 
+// src/utils/microtask_coalescer.ts
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  /** @param run - the single reconciliation pass, invoked at most once per batch. */
+  constructor(run) {
+    this.#run = run;
+  }
+  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
+  activate() {
+    this.#active = true;
+  }
+  /** Closes the window and drops any pending pass; call from `disconnect()`. */
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  schedule() {
+    if (!this.#active || this.#queued) return;
+    this.#queued = true;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
+  }
+};
+
 // src/utils/safe_timeout.ts
 var TimerRegistry = class {
   /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
@@ -103,110 +223,265 @@ var SafeTimeout = class extends TimerRegistry {
 };
 
 // src/controllers/character_counter_controller.ts
-var ORIGINAL_INVALID = "data-character-counter-original-invalid";
 var CharacterCounterController = class _CharacterCounterController extends Controller {
   static targets = ["input", "output"];
   static values = {
     max: { type: Number, default: 0 },
     warnAt: { type: Number, default: 0 },
-    mode: { type: String, default: "remaining" }
+    mode: { type: String, default: "remaining" },
+    announceText: { type: String, default: "" }
   };
-  static events = ["change"];
-  /** Delay (ms) before the live-region count is written, to throttle SR flooding. */
+  static events = ["change", "reconcile"];
+  /** Delay (ms) before one settled count is sent to the shared announcer. */
   static #announceDelay = 200;
   #timeouts = new SafeTimeout();
+  #ariaInvalid = new AttributeLease("aria-invalid");
+  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
+  #repaint = new MicrotaskCoalescer(() => this.#reconcile(true));
+  #composition = new CompositionTracker({
+    onEnd: (event) => this.#commitFrom(event.currentTarget)
+  });
   #announceId = null;
-  /** Owns IME lifecycle state and applies the confirmed count once. */
-  #composition = new CompositionTracker({ onEnd: () => this.#update() });
+  #boundField = null;
+  #lastLength = null;
+  #lastDetail = null;
+  #reflectedOver = null;
   #onInput = (event) => {
+    const field = this.#boundField;
+    if (!field || event.currentTarget !== field || this.#field !== field) return;
     if (this.#composition.isComposing(event)) return;
-    this.#update();
+    this.#commit(field);
   };
+  /** Reflects the current DOM state and opens the mutation-reconciliation window. */
   connect() {
-    const field = this.#field;
-    if (!field) return;
-    field.addEventListener("input", this.#onInput);
-    this.#composition.observe(field);
-    this.#update({ announce: false });
+    this.#repaint.activate();
+    this.#beforeCache.activate();
+    this.#reconcile(false);
   }
+  /** Releases listeners, timers, borrowed ARIA, and controller-owned state hooks. */
   disconnect() {
-    const field = this.#field;
-    field?.removeEventListener("input", this.#onInput);
+    this.#repaint.cancel();
+    this.#beforeCache.deactivate();
+    this.#cancelAnnouncement();
+    this.#bindField(null);
     this.#composition.disconnect();
-    this.#timeouts.clearAll();
-    this.#announceId = null;
+    this.#clearStateHooks();
+    this.#lastLength = null;
+    this.#lastDetail = null;
+  }
+  /** Rebinds and repaints after an input target is added or replaced at runtime. */
+  inputTargetConnected() {
+    this.#repaint.schedule();
+  }
+  /** Releases and repaints after an input target is removed or replaced at runtime. */
+  inputTargetDisconnected() {
+    this.#repaint.schedule();
+  }
+  /** Initializes a display target inserted after the controller connected. */
+  outputTargetConnected() {
+    this.#repaint.schedule();
+  }
+  /** Reconciles the optional display target set after a removal or replacement. */
+  outputTargetDisconnected() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code or a Turbo morph changes `max`. */
+  maxValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code or a Turbo morph changes `warnAt`. */
+  warnAtValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code or a Turbo morph changes `mode`. */
+  modeValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Cancels a pending old message when its consumer-authored template changes. */
+  announceTextValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Rebinds one mutation batch and reports a changed controller-derived state. */
+  #reconcile(report) {
+    const previous = this.#lastDetail;
+    const owedField = this.#announceId === null ? null : this.#boundField;
+    this.#cancelAnnouncement();
+    this.#bindField(this.#field);
+    if (this.#composition.isComposing()) return;
+    const field = this.#boundField;
+    if (!field) {
+      this.#renderEmpty();
+      this.#lastLength = null;
+      this.#lastDetail = null;
+      return;
+    }
+    const reading = this.#render(field);
+    const detail = this.#detail(reading);
+    this.#lastLength = reading.length;
+    this.#lastDetail = detail;
+    if (owedField === field) this.#scheduleAnnouncement(reading);
+    if (report && previous && this.#detailsDiffer(previous, detail)) {
+      this.dispatch("reconcile", { detail });
+    }
+  }
+  /** Commits a composition only when it came from the field still owned here. */
+  #commitFrom(target) {
+    const field = this.#boundField;
+    if (!field || target !== field || this.#field !== field) return;
+    this.#commit(field);
+  }
+  /** Reflects one confirmed user input and reports only a real length transition. */
+  #commit(field) {
+    const reading = this.#render(field);
+    const previousLength = this.#lastLength;
+    const previousDetail = this.#lastDetail;
+    const detail = this.#detail(reading);
+    this.#lastLength = reading.length;
+    this.#lastDetail = detail;
+    if (previousLength === reading.length) {
+      if (previousDetail && this.#detailsDiffer(previousDetail, detail)) {
+        this.dispatch("reconcile", { detail });
+      }
+      return;
+    }
+    this.dispatch("change", { detail });
+    this.#scheduleAnnouncement(reading);
+  }
+  /** Selects the public event state from the richer internal reading. */
+  #detail(reading) {
+    return {
+      length: reading.length,
+      remaining: reading.remaining,
+      over: reading.over
+    };
+  }
+  /** Compares exactly the state carried by `change` and `reconcile`. */
+  #detailsDiffer(left, right) {
+    return left.length !== right.length || left.remaining !== right.remaining || left.over !== right.over;
   }
   /**
-   * Recomputes length-derived state. Non-text state (data hooks, `aria-invalid`)
-   * and the `change` event apply immediately; the live-region count text is
-   * debounced unless `announce` is `false` (initial render).
+   * Synchronizes visible count, state hooks, and temporary validation ARIA.
+   *
+   * @stimeoRenderRoot
    */
-  #update(options = {}) {
-    const field = this.#field;
-    if (!field) return;
+  #render(field) {
     const length = field.value.length;
-    const hasLimit = this.maxValue > 0;
-    const remaining = hasLimit ? this.maxValue - length : null;
-    const over = hasLimit && length > this.maxValue;
-    const near = hasLimit && this.warnAtValue > 0 && !over && remaining !== null && remaining <= this.warnAtValue;
+    const max = this.#normalizeCount(this.maxValue);
+    const warnAt = this.#normalizeCount(this.warnAtValue);
+    const remaining = max > 0 ? max - length : null;
+    const over = remaining !== null && remaining < 0;
+    const near = remaining !== null && warnAt > 0 && !over && remaining <= warnAt;
     this.#toggle("data-over-limit", over);
     this.#toggle("data-near-limit", near);
-    if (hasLimit && over) {
-      if (!field.hasAttribute(ORIGINAL_INVALID)) {
-        field.setAttribute(ORIGINAL_INVALID, field.getAttribute("aria-invalid") ?? "");
-      }
-      field.setAttribute("aria-invalid", "true");
-    } else if (field.hasAttribute(ORIGINAL_INVALID)) {
-      const original = field.getAttribute(ORIGINAL_INVALID);
-      if (original) {
-        field.setAttribute("aria-invalid", original);
-      } else {
-        field.removeAttribute("aria-invalid");
-      }
-      field.removeAttribute(ORIGINAL_INVALID);
-    }
-    const text = this.#format(length, remaining);
-    if (options.announce === false) {
-      this.#writeOutput(text);
-      return;
+    this.#reflectInvalid(field, over);
+    const text = this.#format(length, remaining, max);
+    this.#writeOutput(text);
+    return { length, remaining, over, max, text };
+  }
+  /** Clears derived output when the declarative input set has no usable field. */
+  #renderEmpty() {
+    this.#ariaInvalid.returnAll();
+    this.#reflectedOver = null;
+    this.#clearStateHooks();
+    this.#writeOutput("");
+  }
+  /** Replaces the observed field symmetrically, returning state from the old one. */
+  #bindField(field) {
+    if (field === this.#boundField) return;
+    const previous = this.#boundField;
+    if (previous) {
+      previous.removeEventListener("input", this.#onInput);
+      this.#composition.unobserve(previous);
+      this.#ariaInvalid.return(previous);
     }
-    this.dispatch("change", { detail: { length, remaining, over } });
-    if (this.#announceId !== null) this.#timeouts.clear(this.#announceId);
-    this.#announceId = this.#timeouts.set(() => {
-      this.#writeOutput(text);
-      this.#announceId = null;
-    }, _CharacterCounterController.#announceDelay);
+    this.#boundField = field;
+    this.#lastLength = null;
+    this.#reflectedOver = null;
+    if (!field) return;
+    field.addEventListener("input", this.#onInput);
+    this.#composition.observe(field);
+  }
+  /** Leases `aria-invalid` only on the edge into over-limit, then returns it. */
+  #reflectInvalid(field, over) {
+    if (this.#reflectedOver === over) return;
+    this.#reflectedOver = over;
+    if (over) this.#ariaInvalid.write(field, "true");
+    else this.#ariaInvalid.return(field);
   }
-  /** Builds the count text for the active `mode`. */
-  #format(length, remaining) {
+  /** Builds the visible count for the normalized display mode. */
+  #format(length, remaining, max) {
     if (remaining === null) return String(length);
-    switch (this.modeValue) {
+    switch (this.#mode) {
       case "used":
         return String(length);
       case "both":
-        return `${length}/${this.maxValue}`;
+        return `${length}/${max}`;
       default:
         return String(remaining);
     }
   }
+  /** Debounces one i18n-neutral message into the shared polite announcer. */
+  #scheduleAnnouncement(reading) {
+    this.#cancelAnnouncement();
+    const message = fillTemplate(this.announceTextValue, {
+      count: reading.text,
+      length: reading.length,
+      remaining: reading.remaining ?? "",
+      max: reading.max,
+      over: String(reading.over)
+    });
+    if (message.trim().length === 0) return;
+    this.#announceId = this.#timeouts.set(() => {
+      announce(message);
+      this.#announceId = null;
+    }, _CharacterCounterController.#announceDelay);
+  }
+  /** Cancels the one outstanding announcement without touching visible output. */
+  #cancelAnnouncement() {
+    if (this.#announceId !== null) this.#timeouts.clear(this.#announceId);
+    this.#announceId = null;
+  }
+  /** Writes the optional display only when its text actually changed. */
   #writeOutput(text) {
-    if (this.hasOutputTarget) this.outputTarget.textContent = text;
+    if (!this.hasOutputTarget || this.outputTarget.textContent === text) return;
+    this.outputTarget.textContent = text;
   }
-  /** Sets a presence-style boolean data hook (attribute present when `on`). */
+  /** Reflects a presence-style state hook without redundant attribute writes. */
   #toggle(name, on) {
     if (on) {
-      this.element.setAttribute(name, "true");
-    } else {
+      if (this.element.getAttribute(name) !== "true") this.element.setAttribute(name, "true");
+    } else if (this.element.hasAttribute(name)) {
       this.element.removeAttribute(name);
     }
   }
-  /** The watched field: the `input` target, or the element itself when it is one. */
+  /** Removes both state hooks owned by this controller. */
+  #clearStateHooks() {
+    this.#toggle("data-over-limit", false);
+    this.#toggle("data-near-limit", false);
+  }
+  /** Returns borrowed ARIA and transient hooks before Turbo snapshots the page. */
+  #rewindForCache() {
+    this.#cancelAnnouncement();
+    this.#ariaInvalid.returnAll();
+    this.#reflectedOver = null;
+    this.#clearStateHooks();
+  }
+  /** Converts a public count Value into a finite non-negative integer. */
+  #normalizeCount(raw) {
+    if (!Number.isFinite(raw)) return 0;
+    return Math.max(0, Math.trunc(raw));
+  }
+  /** Falls back to `remaining` when an authored display mode is unknown. */
+  get #mode() {
+    if (this.modeValue === "used" || this.modeValue === "both") return this.modeValue;
+    return "remaining";
+  }
+  /** The watched field: the first target, or a directly controlled form field. */
   get #field() {
     if (this.hasInputTarget) return this.inputTarget;
-    const el = this.element;
-    if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
-      return el;
-    }
+    const element = this.element;
+    if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement)
+      return element;
     return null;
   }
 };