@zeyos/zx 4.4.0 → 5.2.0

package/src/core/keyboard.js

@@ -5,10 +5,18 @@ const FOCUSABLE_SELECTOR = [
   '[contenteditable="true"]', '[tabindex]:not([tabindex="-1"])'
 ].join(',');
 
+/** Attributes that change whether a roving item is available; nothing else is observed. */
+const AVAILABILITY_ATTRIBUTES = ['hidden', 'disabled', 'aria-disabled', 'aria-hidden'];
+/** `<input>` types without a caret, which a roving group may move focus away from freely. */
+const CARETLESS_INPUT_TYPES = new Set(['button', 'checkbox', 'color', 'file', 'image', 'reset', 'submit']);
+
 /**
  * @typedef {Object} RovingOptions
  * @property {'vertical'|'horizontal'} [orientation='vertical'] Arrow-key axis.
  * @property {boolean} [wrap=true] Whether navigation wraps at either end.
+ * @property {'auto'|boolean} [rtl='auto'] Whether ArrowLeft and ArrowRight swap meaning in a
+ *   horizontal group. `'auto'` reads the container's computed `direction` on every key press, so
+ *   a group inside `dir="rtl"` moves to the visually next item; `true`/`false` force it.
  */
 /**
  * @typedef {Object} FocusTrapController
@@ -73,12 +81,23 @@ export function focusTrap(container) {
 
 /**
  * Applies the ARIA roving-tabindex keyboard pattern to matching descendants.
+ *
+ * Editable items keep the keys they need, as the APG toolbar pattern asks: Home and End always
+ * stay with a text field, select, or contenteditable region, and so do the arrow keys — except
+ * that a text field whose caret already sits at the edge the arrow points past hands focus on to
+ * the neighbouring item, so a reader is never trapped in it. Under `dir="rtl"` the horizontal
+ * arrows follow the visual order.
+ *
+ * The group re-reads its items when children are added or removed and when an availability
+ * attribute (`hidden`, `disabled`, `aria-disabled`, `aria-hidden`) changes on an item or on an
+ * element inside the container that holds items — a `<fieldset disabled>` toggled around them; its
+ * own `tabindex` writes and unrelated attribute churn are not observed.
  * @param {Element} container Event and query container.
  * @param {string} itemSelector Selector for roving items.
  * @param {RovingOptions} [options={}] Behavior options.
  * @returns {RovingController}
  */
-export function rovingTabindex(container, itemSelector, { orientation = 'vertical', wrap = true } = {}) {
+export function rovingTabindex(container, itemSelector, { orientation = 'vertical', wrap = true, rtl = 'auto' } = {}) {
   const controller = new AbortController();
   const originals = new Map();
   let destroyed = false;
@@ -117,14 +136,13 @@ export function rovingTabindex(container, itemSelector, { orientation = 'vertica
     const index = available.indexOf(current);
     if (index < 0) return;
 
-    const previousKey = orientation === 'horizontal' ? 'ArrowLeft' : 'ArrowUp';
-    const nextKey = orientation === 'horizontal' ? 'ArrowRight' : 'ArrowDown';
-    let nextIndex = null;
-    if (event.key === 'Home') nextIndex = 0;
-    else if (event.key === 'End') nextIndex = available.length - 1;
-    else if (event.key === previousKey) nextIndex = index - 1;
-    else if (event.key === nextKey) nextIndex = index + 1;
-    if (nextIndex === null || available.length === 0) return;
+    const reversed = orientation === 'horizontal' && isRightToLeft(container, rtl);
+    const step = rovingStep(event.key, orientation, reversed);
+    if (step === null) return;
+    if (!editableAllowsRoving(/** @type {Element|null} */ (event.target), step)) return;
+    let nextIndex = step === 'first' ? 0 : step === 'last' ? available.length - 1
+      : step === 'previous' ? index - 1 : index + 1;
+    if (available.length === 0) return;
 
     if (wrap) nextIndex = (nextIndex + available.length) % available.length;
     else nextIndex = Math.max(0, Math.min(available.length - 1, nextIndex));
@@ -143,10 +161,38 @@ export function rovingTabindex(container, itemSelector, { orientation = 'vertica
 
   container.addEventListener('keydown', onKeydown, { signal: controller.signal });
   container.addEventListener('focusin', onFocus, { signal: controller.signal });
-  const observer = typeof MutationObserver === 'function' ? new MutationObserver(() => update()) : null;
-  observer?.observe(container, { childList: true, subtree: true, attributes: true });
+  const observer = typeof MutationObserver === 'function'
+    ? new MutationObserver((records) => { if (records.some(concernsItems)) update(); })
+    : null;
+  observer?.observe(container, {
+    childList: true, subtree: true, attributes: true, attributeFilter: AVAILABILITY_ATTRIBUTES
+  });
   update();
 
+  /**
+   * Whether a mutation can change the item set: an item's availability attribute, or an added or
+   * removed subtree that is, holds, or held an item. Content churn inside an item is ignored.
+   * @param {MutationRecord} record Observed mutation.
+   * @returns {boolean}
+   */
+  function concernsItems(record) {
+    if (record.type === 'attributes') {
+      // An item's own attribute, or one on an element that holds items: a `<fieldset disabled>`
+      // disables every control inside it without touching their attributes.
+      return record.target instanceof Element
+        && (record.target.matches(itemSelector) || record.target.querySelector(itemSelector) !== null);
+    }
+    for (const node of record.addedNodes) {
+      if (node instanceof Element && (node.matches(itemSelector) || node.querySelector(itemSelector))) return true;
+    }
+    for (const node of record.removedNodes) {
+      if (!(node instanceof Element)) continue;
+      if (originals.has(/** @type {HTMLElement} */ (node))) return true;
+      for (const item of originals.keys()) if (node.contains(item)) return true;
+    }
+    return false;
+  }
+
   return {
     /** Focuses the first available item. @returns {void} */
     focusFirst() {
@@ -182,6 +228,77 @@ export function rovingTabindex(container, itemSelector, { orientation = 'vertica
   };
 }
 
+/**
+ * Where focus sat inside one keyed item of a collection, recorded before the collection re-renders.
+ * @typedef {Object} ItemFocusMemo
+ * @property {unknown} key The item's key.
+ * @property {boolean} self Whether the item element itself held focus.
+ * @property {number} index Position of the focused control among the item's focusable controls.
+ * @property {string} signature Tag, data attributes, and name of the focused control, which
+ *   identify its replacement after a rebuild.
+ */
+
+/**
+ * Records which control of which keyed item holds focus, so a collection that rebuilds an item
+ * can put focus back on the equivalent control afterwards. Returns null when focus is elsewhere.
+ * @param {Element} root Collection root.
+ * @param {(element: Element) => ({key: unknown, element: Element}|null)} locate Finds the keyed
+ *   item an element belongs to.
+ * @returns {ItemFocusMemo|null}
+ */
+export function captureItemFocus(root, locate) {
+  const active = root?.ownerDocument?.activeElement ?? null;
+  if (!active || active === root || !root.contains(active)) return null;
+  const item = locate(active);
+  if (!item) return null;
+  const controls = itemControls(item.element);
+  return {
+    key: item.key,
+    self: active === item.element,
+    index: controls.indexOf(/** @type {HTMLElement} */ (active)),
+    signature: controlSignature(active)
+  };
+}
+
+/**
+ * Puts focus back on the control a {@link captureItemFocus} memo describes, unless focus is still
+ * on a live element inside the collection (nothing was lost). The replacement is the control with
+ * the same signature, else the one at the same position, else the item's last control, else the
+ * item itself when it is focusable. Scrolling is suppressed: the reader did not move.
+ * @param {Element} root Collection root.
+ * @param {ItemFocusMemo|null} memo Recorded focus.
+ * @param {(key: unknown) => Element|null} resolve Finds the item element for a key after the update.
+ * @returns {boolean} Whether focus was moved.
+ */
+export function restoreItemFocus(root, memo, resolve) {
+  if (!memo || !root) return false;
+  const active = root.ownerDocument?.activeElement ?? null;
+  if (active && active !== root.ownerDocument?.body && active.isConnected && root.contains(active)) return false;
+  const element = resolve(memo.key);
+  if (!element) return false;
+  const controls = itemControls(element);
+  const target = memo.self ? /** @type {HTMLElement} */ (element)
+    : controls.find((control) => controlSignature(control) === memo.signature)
+      ?? controls[memo.index] ?? controls.at(-1) ?? null;
+  if (!target || typeof target.focus !== 'function') return false;
+  target.focus({ preventScroll: true });
+  return root.ownerDocument?.activeElement === target;
+}
+
+/** @param {Element} element @returns {HTMLElement[]} Focusable, enabled controls inside an item. */
+function itemControls(element) {
+  return /** @type {HTMLElement[]} */ (Array.from(element.querySelectorAll(`${FOCUSABLE_SELECTOR},[tabindex="-1"]`)))
+    .filter((control) => isAvailable(control));
+}
+
+/** @param {Element} element @returns {string} A rebuild-stable description of a control. */
+function controlSignature(element) {
+  const data = Object.entries(/** @type {HTMLElement} */ (element).dataset ?? {})
+    .map(([name, value]) => `${name}=${value}`).sort().join('&');
+  const name = element.getAttribute('aria-label') ?? element.textContent?.trim() ?? '';
+  return `${element.tagName}|${data}|${name}`;
+}
+
 /**
  * Creates a 500 ms buffered, case-insensitive first-letter typeahead handler.
  * @template T
@@ -212,6 +329,84 @@ export function typeahead(getItems, onMatch) {
   };
 }
 
+/**
+ * Maps a key to a roving step, or null for a key the group does not handle.
+ * @param {string} key `KeyboardEvent.key`.
+ * @param {'vertical'|'horizontal'} orientation Arrow-key axis.
+ * @param {boolean} reversed Whether the horizontal arrows are swapped (right-to-left).
+ * @returns {'first'|'last'|'previous'|'next'|null}
+ */
+export function rovingStep(key, orientation, reversed = false) {
+  if (key === 'Home') return 'first';
+  if (key === 'End') return 'last';
+  if (orientation === 'horizontal') {
+    if (key === 'ArrowLeft') return reversed ? 'next' : 'previous';
+    if (key === 'ArrowRight') return reversed ? 'previous' : 'next';
+    return null;
+  }
+  if (key === 'ArrowUp') return 'previous';
+  if (key === 'ArrowDown') return 'next';
+  return null;
+}
+
+/**
+ * Whether an element takes keyboard text input, so that arrow keys and Home/End move its caret
+ * or its value: a text-like `<input>`, `<textarea>`, `<select>`, or a contenteditable region.
+ * @param {Element|null} element Candidate, normally a key event's target.
+ * @returns {boolean}
+ */
+export function isEditableTarget(element) {
+  if (!element || typeof element !== 'object') return false;
+  const tag = String(element.tagName ?? '').toUpperCase();
+  if (tag === 'TEXTAREA' || tag === 'SELECT') return true;
+  if (tag === 'INPUT') {
+    return !CARETLESS_INPUT_TYPES.has(String(/** @type {HTMLInputElement} */ (element).type ?? 'text').toLowerCase());
+  }
+  return Boolean(/** @type {HTMLElement} */ (element).isContentEditable);
+}
+
+/**
+ * Whether a roving step may leave the event target. Non-editable targets always may. An editable
+ * one keeps Home/End, and keeps the arrows unless it is a single-line text field whose collapsed
+ * caret already sits at the edge the step points past: position 0 for `previous`, the end of the
+ * value for `next`. The steps are logical, so under right-to-left the caret check still matches
+ * the direction the caret would have moved.
+ * @param {Element|null} target Key event target.
+ * @param {'first'|'last'|'previous'|'next'} step Roving step.
+ * @returns {boolean}
+ */
+export function editableAllowsRoving(target, step) {
+  if (!isEditableTarget(target)) return true;
+  if (step === 'first' || step === 'last') return false;
+  if (String(target?.tagName ?? '').toUpperCase() !== 'INPUT') return false;
+  const input = /** @type {HTMLInputElement} */ (target);
+  let start;
+  let end;
+  try {
+    start = input.selectionStart;
+    end = input.selectionEnd;
+  } catch {
+    return false;
+  }
+  // Types without a selection API (number, date, range …) own their arrows outright.
+  if (typeof start !== 'number' || typeof end !== 'number' || start !== end) return false;
+  return step === 'previous' ? start === 0 : end === String(input.value ?? '').length;
+}
+
+/**
+ * @param {Element} container Group container.
+ * @param {'auto'|boolean} rtl Configured direction handling.
+ * @returns {boolean}
+ */
+function isRightToLeft(container, rtl) {
+  if (rtl === true || rtl === false) return rtl;
+  try {
+    return globalThis.getComputedStyle?.(container)?.direction === 'rtl';
+  } catch {
+    return false;
+  }
+}
+
 /** @param {Element} container @returns {HTMLElement[]} */
 function focusableItems(container) {
   return /** @type {HTMLElement[]} */ (Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR)))