stimeo-ui 0.6.0 → 0.7.0

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

data/dist/controllers/command_palette_controller.js

@@ -180,8 +180,81 @@ var EscapeLayer = class _EscapeLayer {
   }
 };
 
+// src/utils/focus_candidate.ts
+function inheritsFieldsetDisabled(control) {
+  let fieldset = control.closest("fieldset[disabled]");
+  while (fieldset) {
+    const legend = Array.from(fieldset.children).find((child) => child.tagName === "LEGEND");
+    if (!legend?.contains(control)) return true;
+    fieldset = fieldset.parentElement?.closest("fieldset[disabled]") ?? null;
+  }
+  return false;
+}
+function canTakeFocus(element) {
+  if (element.closest("[hidden], [inert]")) return false;
+  if (element instanceof HTMLInputElement && element.type === "hidden") return false;
+  if (!("disabled" in element)) return true;
+  if (element.disabled) return false;
+  return !inheritsFieldsetDisabled(element);
+}
+var TAB_STOP_CANDIDATE_SELECTOR = [
+  "a[href]",
+  "area[href]",
+  "button",
+  "input",
+  "select",
+  "textarea",
+  "summary",
+  "iframe",
+  "audio[controls]",
+  "video[controls]",
+  "[tabindex]",
+  "[contenteditable]"
+].join(",");
+function isRenderedForFocus(element) {
+  const check = element.checkVisibility;
+  return typeof check === "function" ? check.call(element, { visibilityProperty: true }) : true;
+}
+function authoredTabindex(element) {
+  const value = element.getAttribute("tabindex");
+  if (value === null || !/^[+-]?\d+$/.test(value.trim())) return null;
+  return Number(value);
+}
+function hasNativeTabStop(element) {
+  if (element instanceof HTMLAnchorElement || element instanceof HTMLAreaElement) {
+    return element.hasAttribute("href");
+  }
+  if (element instanceof HTMLButtonElement || element instanceof HTMLSelectElement || element instanceof HTMLTextAreaElement) {
+    return true;
+  }
+  if (element instanceof HTMLInputElement) return element.type !== "hidden";
+  if (element instanceof HTMLIFrameElement) return true;
+  if (element.tagName === "AUDIO" || element.tagName === "VIDEO") {
+    return element.hasAttribute("controls");
+  }
+  if (element instanceof HTMLElement && element.tagName === "SUMMARY") {
+    const details = element.parentElement;
+    return details instanceof HTMLDetailsElement && Array.from(details.children).find((child) => child.tagName === "SUMMARY") === element;
+  }
+  return false;
+}
+function hasEditableTabStop(element) {
+  const value = element.getAttribute("contenteditable")?.toLowerCase();
+  return value === "" || value === "true" || value === "plaintext-only";
+}
+function isTabStop(element) {
+  if (!canTakeFocus(element) || !isRenderedForFocus(element)) return false;
+  const tabindex = authoredTabindex(element);
+  if (tabindex !== null) return tabindex >= 0;
+  return hasNativeTabStop(element) || hasEditableTabStop(element);
+}
+function tabStopsWithin(root) {
+  return Array.from(root.querySelectorAll(TAB_STOP_CANDIDATE_SELECTOR)).filter(
+    isTabStop
+  );
+}
+
 // src/utils/focus_trap.ts
-var FOCUSABLE = 'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
 var FocusTrap = class {
   /** The element focused before activation, restored on deactivation. */
   #previouslyFocused = null;
@@ -343,9 +416,7 @@ var FocusTrap = class {
   }
   /** Collects the container's currently focusable descendants in DOM order. */
   #focusableElements() {
-    return Array.from(this.#getContainer().querySelectorAll(FOCUSABLE)).filter(
-      (el) => !el.hidden
-    );
+    return tabStopsWithin(this.#getContainer());
   }
 };