stimeo-ui 0.2.1 → 0.4.0

data/dist/controllers/pagination_controller.js

@@ -1,7 +1,53 @@
 import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/pagination_controller.ts
-var PaginationController = class extends Controller {
+
+// 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]")) return false;
+  if (!("disabled" in element)) return true;
+  if (element.disabled) return false;
+  return !inheritsFieldsetDisabled(element);
+}
+
+// src/utils/tabindex_loan.ts
+var TabindexLoan = class {
+  #value;
+  #lent = /* @__PURE__ */ new Set();
+  /**
+   * @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);
+  }
+  /** 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();
+  }
+};
+
+// src/controllers/pagination_controller.ts
+var PaginationController = class _PaginationController extends Controller {
   static targets = ["page", "prev", "next"];
   static values = {
     page: { type: Number, default: 1 },
@@ -9,79 +55,164 @@ var PaginationController = class extends Controller {
   };
   static actions = ["next", "prev", "select"];
   static events = ["change"];
+  /** Marks a `disabled` this controller applied at a boundary (ownership flag). */
+  static #BOUNDARY_ATTR = "data-stimeo--pagination-boundary-disabled";
+  #isConnected = false;
+  /** The `tabindex` this instance lends the root for the focus fallback. */
+  #tabindex = new TabindexLoan();
   /** Normalizes out-of-range initial values and renders the initial state. */
   connect() {
-    this.totalValue = Math.max(1, Math.trunc(this.totalValue));
-    this.pageValue = Math.min(this.totalValue, Math.max(1, Math.trunc(this.pageValue)));
+    this.#isConnected = true;
+    this.#normalizeAndRender();
+  }
+  /** Reverts the one attribute the controller adds outside its state hooks. */
+  disconnect() {
+    this.#isConnected = false;
+    this.#tabindex.returnAll();
+  }
+  /** Re-renders when application code (or a Turbo morph) changes `page` at runtime. */
+  pageValueChanged() {
+    if (!this.#isConnected) return;
+    this.#normalizeAndRender();
+  }
+  /** Re-renders when application code (or a Turbo morph) changes `total` at runtime. */
+  totalValueChanged() {
+    if (!this.#isConnected) return;
+    this.#normalizeAndRender();
+  }
+  /** Syncs a page button appended/replaced at runtime (the consumer owns the list). */
+  pageTargetConnected() {
+    if (!this.#isConnected) return;
+    this.#render();
+  }
+  /** Syncs a `prev` button appended/replaced at runtime. */
+  prevTargetConnected() {
+    if (!this.#isConnected) return;
+    this.#render();
+  }
+  /** Syncs a `next` button appended/replaced at runtime. */
+  nextTargetConnected() {
+    if (!this.#isConnected) return;
     this.#render();
   }
   /** Makes the clicked page button (its `data-page`) current. */
   select(event) {
     const button = event.currentTarget;
-    const page = Number(button.dataset.page);
-    if (!Number.isFinite(page)) return;
+    const raw = button.dataset.page;
+    if (raw === void 0 || raw.trim() === "") return;
+    const page = Number(raw);
+    if (!Number.isInteger(page)) return;
     this.#goto(page);
   }
   /** Steps to the previous page. */
   prev() {
-    this.#goto(this.pageValue - 1);
+    this.#goto(this.#page - 1);
   }
   /** Steps to the next page. */
   next() {
-    this.#goto(this.pageValue + 1);
+    this.#goto(this.#page + 1);
   }
   /** Moves to `page` (clamped to `[1, total]`), re-renders, and dispatches `change`. */
   #goto(page) {
-    const total = Math.max(1, Math.trunc(this.totalValue));
-    const target = Math.min(total, Math.max(1, Math.trunc(page)));
-    if (target === this.pageValue) return;
-    const previous = this.pageValue;
+    if (!Number.isFinite(page)) return;
+    const previous = this.#page;
+    const target = this.#clamp(page);
+    if (target === previous) return;
     this.pageValue = target;
     this.#render();
     this.dispatch("change", {
-      detail: { page: target, total: this.totalValue, previous }
+      detail: { page: target, total: this.#total, previous }
     });
   }
+  /** Writes the normalized Values back (only when they differ) and renders. */
+  #normalizeAndRender() {
+    const total = this.#total;
+    if (!Object.is(total, this.totalValue)) this.totalValue = total;
+    const page = this.#page;
+    if (!Object.is(page, this.pageValue)) this.pageValue = page;
+    this.#render();
+  }
   /** Syncs `aria-current` on the page buttons and the prev/next `disabled` state. */
   #render() {
+    const page = this.#page;
     for (const button of this.pageTargets) {
-      if (Number(button.dataset.page) === this.pageValue) {
+      if (Number(button.dataset.page) === page) {
         button.setAttribute("aria-current", "page");
       } else {
         button.removeAttribute("aria-current");
       }
     }
-    this.#setDisabled(this.hasPrevTarget ? this.prevTarget : null, this.pageValue <= 1);
-    this.#setDisabled(
-      this.hasNextTarget ? this.nextTarget : null,
-      this.pageValue >= this.totalValue
-    );
+    const prev = this.hasPrevTarget ? this.prevTarget : null;
+    const next = this.hasNextTarget ? this.nextTarget : null;
+    const atStart = page <= 1;
+    const atEnd = page >= this.#total;
+    const prevStaysDisabled = this.#disabledAfter(prev, atStart);
+    const nextStaysDisabled = this.#disabledAfter(next, atEnd);
+    this.#release(prev, atStart);
+    this.#release(next, atEnd);
+    this.#disable(prev, atStart, nextStaysDisabled ? null : next);
+    this.#disable(next, atEnd, prevStaysDisabled ? null : prev);
+  }
+  /** Whether a boundary button will still be `disabled` once this render applies. */
+  #disabledAfter(button, atBoundary) {
+    if (!button) return true;
+    if (atBoundary) return true;
+    return button.disabled && !this.#owns(button);
+  }
+  /** Releases the boundary `disabled` this controller owns, once away from it. */
+  #release(button, atBoundary) {
+    if (!button || atBoundary || !this.#owns(button)) return;
+    button.disabled = false;
+    button.removeAttribute(_PaginationController.#BOUNDARY_ATTR);
   }
   /**
-   * Sets `disabled` on a boundary button, first moving focus off it if it is the
-   * active element so disabling never strands focus.
+   * Disables a boundary button, first moving focus off it when it is the active
+   * element so disabling never strands focus.
    */
-  #setDisabled(button, disabled) {
-    if (!button) return;
-    if (disabled && button === document.activeElement) {
-      this.#moveFocusAwayFrom(button);
-    }
-    button.disabled = disabled;
+  #disable(button, atBoundary, opposite) {
+    if (!button || !atBoundary) return;
+    if (button.disabled && !this.#owns(button)) return;
+    if (button === document.activeElement) this.#moveFocusAwayFrom(opposite);
+    button.disabled = true;
+    button.setAttribute(_PaginationController.#BOUNDARY_ATTR, "");
   }
-  /** Moves focus to the opposite enabled control, falling back to the current page. */
-  #moveFocusAwayFrom(button) {
-    const opposite = button === (this.hasPrevTarget ? this.prevTarget : null) ? this.hasNextTarget ? this.nextTarget : null : this.hasPrevTarget ? this.prevTarget : null;
+  /**
+   * Moves focus to `opposite` (already resolved to `null` when it will stay
+   * disabled), else to the current page button, else to the landmark itself.
+   */
+  #moveFocusAwayFrom(opposite) {
+    const page = this.#page;
     const currentPage = this.pageTargets.find(
-      (candidate) => Number(candidate.dataset.page) === this.pageValue
+      (candidate) => Number(candidate.dataset.page) === page
+    );
+    const destination = [opposite, currentPage].find(
+      (candidate) => candidate != null && canTakeFocus(candidate)
     );
-    const destination = opposite && !opposite.disabled ? opposite : currentPage;
     if (destination) {
       destination.focus();
       return;
     }
-    if (!this.element.hasAttribute("tabindex")) this.element.setAttribute("tabindex", "-1");
+    this.#tabindex.lend(this.element);
     this.element.focus();
   }
+  /** Total pages, normalized to a finite integer >= 1. */
+  get #total() {
+    const total = this.totalValue;
+    return Number.isFinite(total) ? Math.max(1, Math.trunc(total)) : 1;
+  }
+  /** The current page, normalized into `[1, total]`. */
+  get #page() {
+    return this.#clamp(this.pageValue);
+  }
+  /** Constrains `page` to `[1, total]`; a non-finite page falls back to page 1. */
+  #clamp(page) {
+    if (!Number.isFinite(page)) return 1;
+    return Math.min(this.#total, Math.max(1, Math.trunc(page)));
+  }
+  /** Whether the button's current `disabled` was applied by boundary control. */
+  #owns(button) {
+    return button.hasAttribute(_PaginationController.#BOUNDARY_ATTR);
+  }
 };
 
 export { PaginationController };

data/dist/controllers/persist_controller.js

@@ -182,12 +182,12 @@ var PersistController = class extends Controller {
   }
   /**
    * Persistable fields paired with a stable storage key. Uniquely-named fields key
-   * by their name (unchanged, backward-compatible). Repeated same-name fields
-   * (e.g. a `tags[]` checkbox group or array text inputs) are disambiguated by
-   * DOM-order occurrence — the first keeps its plain `name` (backward-
-   * compatible), later ones get a NUL-separated index suffix — so each is stored and
-   * restored individually instead of the last one clobbering the rest. Radios are
-   * the exception: a group intentionally shares one key (one value per name).
+   * by their name. Repeated same-name fields (e.g. a `tags[]` checkbox group or
+   * array text inputs) are disambiguated by DOM-order occurrence — the first keeps
+   * its plain `name`, later ones get a NUL-separated index suffix — so each is
+   * stored and restored individually instead of the last one clobbering the rest.
+   * Radios are the exception: a group intentionally shares one key (one value per
+   * name).
    */
   #fieldEntries() {
     const entries = [];

data/dist/controllers/pointer_drag_controller.js

@@ -2,6 +2,12 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/pointer_drag_controller.ts
 
+// src/utils/arrow_step.ts
+function isReservedArrowChord(event, allow = []) {
+  if (!event.key.startsWith("Arrow")) return false;
+  return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
+}
+
 // src/utils/detach_gate.ts
 var DetachGate = class _DetachGate {
   /** Set while a probe is queued, waiting for a reconnect to cancel it. */
@@ -186,8 +192,10 @@ var PointerDragController = class _PointerDragController extends Controller {
     if (this.disabledValue) return;
     const handle = this.#handleFor(event.target);
     if (!handle) return;
+    if (event.defaultPrevented) return;
+    if (isReservedArrowChord(event)) return;
     if (event.key === "Escape") {
-      if (event.defaultPrevented || event.isComposing) return;
+      if (event.isComposing) return;
       if (this.#pointer?.started) {
         const { pointerType } = this.#pointer;
         this.#teardownSessions();

data/dist/controllers/popover_controller.js

@@ -133,7 +133,7 @@ var PopoverController = class _PopoverController extends Controller {
   /** Starts closed and registers the standing dismissal listeners. */
   connect() {
     this.close();
-    document.addEventListener("click", this.#onOutsideClick);
+    document.addEventListener("click", this.#onOutsideClick, true);
     this.element.addEventListener("focusout", this.#onFocusOut);
   }
   /**
@@ -144,7 +144,7 @@ var PopoverController = class _PopoverController extends Controller {
    */
   disconnect() {
     this.#escapeLayer.deactivate();
-    document.removeEventListener("click", this.#onOutsideClick);
+    document.removeEventListener("click", this.#onOutsideClick, true);
     this.element.removeEventListener("focusout", this.#onFocusOut);
     this.#stopScrollDismiss?.();
     this.#stopScrollDismiss = null;

data/dist/controllers/progress_controller.js

@@ -2,6 +2,23 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/progress_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/coerce.ts
 function toFiniteNumber(raw) {
   if (raw === null || raw === void 0 || raw === "") return null;
@@ -9,7 +26,57 @@ function toFiniteNumber(raw) {
   return Number.isFinite(value) ? value : null;
 }
 
+// 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/range.ts
+function rangeFraction(value, min, max) {
+  const span = max - min;
+  if (!(span > 0)) return 0;
+  const clamped = Math.min(max, Math.max(min, value));
+  let fraction;
+  if (Number.isFinite(span)) {
+    fraction = (clamped - min) / span;
+  } else {
+    const scale = Math.max(Math.abs(min), Math.abs(max));
+    fraction = (clamped / scale - min / scale) / (max / scale - min / scale);
+  }
+  if (!Number.isFinite(fraction)) return 0;
+  return Math.min(1, Math.max(0, fraction));
+}
+
 // src/controllers/progress_controller.ts
+var OWNED_VALUE_TEXT = "data-stimeo--progress-owns-valuetext";
 var ProgressController = class extends Controller {
   static targets = ["bar"];
   static values = {
@@ -17,13 +84,27 @@ var ProgressController = class extends Controller {
     min: { type: Number, default: 0 },
     max: { type: Number, default: 100 },
     indeterminate: { type: Boolean, default: false },
-    valueText: { type: String, default: "" }
+    valueText: { type: String, default: "" },
+    announceText: { type: String, default: "" }
   };
   static actions = ["setValue"];
   static events = ["change", "complete"];
+  /**
+   * Collapses a morph that swaps several render inputs at once into one repaint.
+   * A single update usually rewrites the whole set, and each Value would otherwise
+   * repaint on its own.
+   */
+  #repaint = new MicrotaskCoalescer(() => {
+    this.#render();
+  });
   connect() {
+    this.#repaint.activate();
     this.#render();
   }
+  /** Closes the window in which a queued repaint may still run. */
+  disconnect() {
+    this.#repaint.cancel();
+  }
   /**
    * Updates the progress value from an action param (`amount`) or a
    * `detail.value` CustomEvent, normalizes it into range, syncs ARIA, and
@@ -39,11 +120,30 @@ var ProgressController = class extends Controller {
     this.dispatch("change", { detail: { value, ratio: this.#ratio } });
     if (value >= this.maxValue) {
       this.dispatch("complete", { detail: { value } });
+      announce(
+        fillTemplate(this.announceTextValue, { value, percent: Math.round(this.#ratio * 100) })
+      );
     }
   }
-  /** Re-render when the indeterminate flag is toggled via its data attribute. */
+  /** Repaints when application code (or a Turbo morph) changes `indeterminate` at runtime. */
   indeterminateValueChanged() {
-    this.#render();
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `value` at runtime. */
+  valueValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `min` at runtime. */
+  minValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `max` at runtime. */
+  maxValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `valueText` at runtime. */
+  valueTextValueChanged() {
+    this.#repaint.schedule();
   }
   /** Clamps `raw` into the configured `[min, max]` range. */
   #clamp(raw) {
@@ -51,9 +151,7 @@ var ProgressController = class extends Controller {
   }
   /** Current fraction of the range in `[0, 1]`; `0` when the range is empty. */
   get #ratio() {
-    const span = this.maxValue - this.minValue;
-    if (span <= 0) return 0;
-    return (this.#clamp(this.valueValue) - this.minValue) / span;
+    return rangeFraction(this.valueValue, this.minValue, this.maxValue);
   }
   /** Reflects value/range/indeterminate onto ARIA, `data-state`, and the ratio. */
   #render() {
@@ -61,7 +159,7 @@ var ProgressController = class extends Controller {
     this.element.setAttribute("aria-valuemax", String(this.maxValue));
     if (this.indeterminateValue) {
       this.element.removeAttribute("aria-valuenow");
-      this.element.removeAttribute("aria-valuetext");
+      this.#clearOwnValueText();
       this.element.style.removeProperty("--stimeo-progress-ratio");
       this.element.setAttribute("data-state", "indeterminate");
       return;
@@ -75,16 +173,25 @@ var ProgressController = class extends Controller {
   /**
    * Sets `aria-valuetext` from the consumer-provided template, substituting
    * `{value}` and `{percent}`. Left to the consumer so the human-readable text
-   * stays i18n-neutral in the library; cleared when no template is given.
+   * stays i18n-neutral in the library. With no template the attribute belongs to
+   * the consumer, so only a text this controller wrote is taken back
+   * ({@link OWNED_VALUE_TEXT}).
    */
   #applyValueText(value) {
     if (this.valueTextValue.length === 0) {
-      this.element.removeAttribute("aria-valuetext");
+      this.#clearOwnValueText();
       return;
     }
     const percent = Math.round(this.#ratio * 100);
     const text = this.valueTextValue.replaceAll("{value}", String(value)).replaceAll("{percent}", String(percent));
     this.element.setAttribute("aria-valuetext", text);
+    this.element.setAttribute(OWNED_VALUE_TEXT, "");
+  }
+  /** Removes `aria-valuetext` only when this controller is the one that wrote it. */
+  #clearOwnValueText() {
+    if (!this.element.hasAttribute(OWNED_VALUE_TEXT)) return;
+    this.element.removeAttribute("aria-valuetext");
+    this.element.removeAttribute(OWNED_VALUE_TEXT);
   }
 };
 

data/dist/controllers/radio_group_controller.js

@@ -2,6 +2,24 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/radio_group_controller.ts
 
+// src/utils/logical_scroll.ts
+function isRtl(element) {
+  return window.getComputedStyle(element).direction === "rtl";
+}
+
+// src/utils/arrow_step.ts
+function logicalArrowStep(key, element) {
+  if (key === "ArrowDown") return 1;
+  if (key === "ArrowUp") return -1;
+  if (key !== "ArrowRight" && key !== "ArrowLeft") return 0;
+  const forward = isRtl(element) ? "ArrowLeft" : "ArrowRight";
+  return key === forward ? 1 : -1;
+}
+function isReservedArrowChord(event, allow = []) {
+  if (!event.key.startsWith("Arrow")) return false;
+  return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
+}
+
 // src/utils/roving_tabindex.ts
 var RovingTabindex = class {
   /** Returns the current ordered item elements; called on every operation. */
@@ -59,17 +77,18 @@ var RadioGroupController = class extends Controller {
   }
   /** Arrow/Home/End/Space navigation with selection-follows-focus. */
   onKeydown(event) {
+    if (event.defaultPrevented) return;
+    if (isReservedArrowChord(event)) return;
     const current = this.radioTargets.indexOf(event.currentTarget);
     if (current === -1) return;
     let next = null;
+    const step = logicalArrowStep(event.key, this.element);
     switch (event.key) {
       case "ArrowDown":
       case "ArrowRight":
-        next = rovingMove(current, this.radioTargets.length, 1);
-        break;
       case "ArrowUp":
       case "ArrowLeft":
-        next = rovingMove(current, this.radioTargets.length, -1);
+        next = rovingMove(current, this.radioTargets.length, step);
         break;
       case "Home":
         next = 0;