@zeyos/zx 5.0.0 → 5.2.0

package/src/core/component.js

@@ -1,6 +1,6 @@
 // @ts-check
 import { h, resolveElement } from './dom.js';
-import { getLanguage, printf, translate } from './i18n.js';
+import { defaultMessage, getLanguage, hostMessage, legacyMessageKey, printf } from './i18n.js';
 import { deepMerge, isElement } from './util.js';
 
 /** @typedef {Record<string, any>} ComponentOptions */
@@ -9,6 +9,13 @@ import { deepMerge, isElement } from './util.js';
 /** @type {WeakMap<Element, Component>} */
 const registry = new WeakMap();
 
+/**
+ * Each instance's `msg` tables, kept apart so the host translator can sit between them: the
+ * option the instance was given, and the defaults its class chain declares.
+ * @type {WeakMap<object, {own: Record<string, any>|null, inherited: Record<string, any>|null}>}
+ */
+const messageTables = new WeakMap();
+
 /**
  * Base class for lifecycle-safe Zx components.
  *
@@ -62,6 +69,10 @@ export class Component extends EventTarget {
     this.refs = {};
 
     const merged = /** @type {TOptions} */ (mergeOptions(self, options));
+    messageTables.set(this, {
+      own: isMessageTable(options?.msg) ? Object.freeze(deepMerge({}, options.msg)) : null,
+      inherited: inheritedMessages(self)
+    });
     const eventOptions = [];
     for (const [key, value] of Object.entries(merged)) {
       if (/^on[a-z]/.test(key) && typeof value === 'function') {
@@ -204,19 +215,38 @@ export class Component extends EventTarget {
   }
 
   /**
-   * Resolves and interpolates a component-local or global translation.
+   * Resolves and interpolates one of the component's messages. The first answer wins:
+   *
+   * 1. the `msg` option this instance was given — a `{[lang]: {key: text}}` table for the active
+   *    language (the `lang` option, else `getLanguage()`), then a flat `{key: text}` entry;
+   * 2. the host translator installed with `setTranslator()`;
+   * 3. the `msg` defaults the component class declares;
+   * 4. the default English catalogue (`defaultMessages`);
+   * 5. the key itself.
+   *
+   * A renamed key (`calendar.today`, formerly `today`) is also looked up under its former name,
+   * right after the new one, in steps 1 and 2.
    * @param {string} key Message key.
-   * @param {...unknown} args Positional interpolation values.
+   * @param {...unknown} args Positional interpolation values (`%1`, `%2`, …).
    * @returns {string}
    */
   msg(key, ...args) {
-    const messages = this.options.msg;
-    const lang = this.options.lang ?? this.options.language ?? getLanguage();
-    const localized = messages?.[lang]?.[key];
-    if (localized != null) return printf(String(localized), args);
-    const direct = messages?.[key];
-    if (direct != null) return printf(String(direct), args);
-    return translate(key, args);
+    const lang = this.options?.lang ?? this.options?.language ?? getLanguage();
+    const legacy = legacyMessageKey(key);
+    // An object that borrows this method without running the constructor reads its options' `msg`.
+    const tables = messageTables.get(this) ?? {
+      own: isMessageTable(this.options?.msg) ? this.options.msg : null,
+      inherited: null
+    };
+    const own = tables.own;
+    const text = pickMessage(own, lang, key)
+      ?? (legacy ? pickMessage(own, lang, legacy) : null)
+      ?? hostMessage(key)
+      ?? (legacy ? hostMessage(legacy) : null)
+      ?? pickMessage(tables.inherited, lang, key)
+      ?? defaultMessage(key)
+      ?? key;
+    return printf(text, args);
   }
 
   /**
@@ -254,13 +284,7 @@ export class Component extends EventTarget {
 
 /** @param {typeof Component} constructor @param {ComponentOptions} options @returns {ComponentOptions} */
 function mergeOptions(constructor, options) {
-  const chain = [];
-  let current = constructor;
-  while (current && current !== Function.prototype) {
-    if (Object.prototype.hasOwnProperty.call(current, 'defaults')) chain.unshift(current.defaults);
-    current = Object.getPrototypeOf(current);
-  }
-
+  const chain = defaultsChain(constructor);
   const result = {};
   let messages = {};
   let hasMessages = false;
@@ -281,6 +305,53 @@ function mergeOptions(constructor, options) {
   return result;
 }
 
+/**
+ * The `defaults` objects a class and its ancestors declare, base class first.
+ * @param {typeof Component} constructor
+ * @returns {ComponentOptions[]}
+ */
+function defaultsChain(constructor) {
+  const chain = [];
+  let current = constructor;
+  while (current && current !== Function.prototype) {
+    if (Object.prototype.hasOwnProperty.call(current, 'defaults')) chain.unshift(current.defaults);
+    current = Object.getPrototypeOf(current);
+  }
+  return chain;
+}
+
+/** @param {unknown} value @returns {value is Record<string, any>} */
+function isMessageTable(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** @param {typeof Component} constructor @returns {Record<string, any>|null} */
+function inheritedMessages(constructor) {
+  let messages = null;
+  for (const defaults of defaultsChain(constructor)) {
+    if (defaults && typeof defaults === 'object' && isMessageTable(defaults.msg)) {
+      messages = deepMerge(messages ?? {}, defaults.msg);
+    }
+  }
+  return messages ? Object.freeze(messages) : null;
+}
+
+/**
+ * Reads one key from a `msg` table: the active language's sub-table first, then a flat entry.
+ * @param {Record<string, any>|null} table Message table.
+ * @param {string} lang Active language.
+ * @param {string} key Message key.
+ * @returns {string|null}
+ */
+function pickMessage(table, lang, key) {
+  if (!table) return null;
+  const localized = table[lang]?.[key];
+  if (localized != null && typeof localized !== 'object') return String(localized);
+  const direct = Object.prototype.hasOwnProperty.call(table, key) ? table[key] : null;
+  if (direct != null && typeof direct !== 'object') return String(direct);
+  return null;
+}
+
 /**
  * @param {string} type
  * @param {Record<string, unknown>} detail

package/src/core/fontawesome.js

@@ -55,7 +55,11 @@ export const faNames = Object.freeze({
   warning: 'triangle-exclamation',
   error: 'circle-exclamation',
   success: 'circle-check',
-  drag: 'grip-vertical'
+  drag: 'grip-vertical',
+  type: 'font',
+  hash: 'hashtag',
+  mail: 'envelope',
+  'link-2': 'link'
 });
 
 /** @type {Map<string, Promise<void>>} In-flight and settled kit loads, keyed by URL. */

package/src/core/i18n.js

@@ -1,4 +1,8 @@
 // @ts-check
+import { defaultMessages, legacyMessageKeys } from './messages.js';
+
+export { defaultMessages };
+
 /** @typedef {(key: string) => string|null|undefined} Translator */
 
 /** @type {Translator|null} */
@@ -6,7 +10,9 @@ let translator = null;
 let language = 'en';
 
 /**
- * Installs the host application's translation function, or clears it with null.
+ * Installs the host application's translation function, or clears it with null. The function
+ * answers one key at a time; returning null, undefined, or the key itself means "no translation",
+ * and resolution moves on to the default English catalogue (`defaultMessages`).
  * @param {Translator|null} fn Translator function.
  * @returns {void}
  */
@@ -35,14 +41,51 @@ export function getLanguage() {
 }
 
 /**
- * Translates a key through the injected host translator and interpolates arguments.
+ * Asks the host translator for one key, without interpolating. A translator that returns null,
+ * undefined, or the key itself has no answer.
+ * @param {string} key Message key.
+ * @returns {string|null} The translation, or null when there is none.
+ */
+export function hostMessage(key) {
+  if (!translator) return null;
+  const translated = translator(key);
+  if (translated == null) return null;
+  const text = String(translated);
+  return text === key ? null : text;
+}
+
+/**
+ * Looks one key up in the default English catalogue.
+ * @param {string} key Message key.
+ * @returns {string|null} The English text, or null when the catalogue has no entry.
+ */
+export function defaultMessage(key) {
+  return Object.prototype.hasOwnProperty.call(defaultMessages, key)
+    ? /** @type {Record<string, string>} */ (defaultMessages)[key] : null;
+}
+
+/**
+ * The key a renamed message key replaced, which is still honoured for one major version.
+ * @param {string} key Current message key.
+ * @returns {string|null} The former key, or null when the key was never renamed.
+ */
+export function legacyMessageKey(key) {
+  return Object.prototype.hasOwnProperty.call(legacyMessageKeys, key)
+    ? /** @type {Record<string, string>} */ (legacyMessageKeys)[key] : null;
+}
+
+/**
+ * Translates a key and interpolates arguments. The host translator answers first (then, for a
+ * renamed key, the translator again under its former name), then the default English catalogue;
+ * a key neither knows comes back unchanged.
  * @param {string} key Translation key.
  * @param {unknown[]|Record<string, unknown>|string|number} [args] Interpolation arguments.
  * @returns {string}
  */
 export function translate(key, args) {
-  const translated = translator ? translator(key) : key;
-  return printf(translated == null ? key : String(translated), args);
+  const legacy = legacyMessageKey(key);
+  const text = hostMessage(key) ?? (legacy ? hostMessage(legacy) : null) ?? defaultMessage(key) ?? key;
+  return printf(text, args);
 }
 
 /**

package/src/core/icons.js

@@ -160,7 +160,16 @@ export const icons = Object.freeze({
   copy: outline('M10 8h10a2 2 0 0 1 2 2v10a2 2 0 0 1-2 2h-10a2 2 0 0 1-2-2v-10a2 2 0 0 1 2-2zM4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2'),
   square: outline('M5 3h14a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2h-14a2 2 0 0 1-2-2v-14a2 2 0 0 1 2-2z'),
   code: outline('M18 16l4-4-4-4M6 8l-4 4 4 4M14.5 4l-5 16'), // code-xml
-  book: outline('M4 19.5v-15A2.5 2.5 0 0 1 6.5 2H19a1 1 0 0 1 1 1v18a1 1 0 0 1-1 1H6.5a1 1 0 0 1 0-5H20')
+  book: outline('M4 19.5v-15A2.5 2.5 0 0 1 6.5 2H19a1 1 0 0 1 1 1v18a1 1 0 0 1-1 1H6.5a1 1 0 0 1 0-5H20'),
+  'table-cells-large': outline('M4 3h5a1 1 0 0 1 1 1v5a1 1 0 0 1-1 1h-5a1 1 0 0 1-1-1v-5a1 1 0 0 1 1-1zM15 3h5a1 1 0 0 1 1 1v5a1 1 0 0 1-1 1h-5a1 1 0 0 1-1-1v-5a1 1 0 0 1 1-1zM15 14h5a1 1 0 0 1 1 1v5a1 1 0 0 1-1 1h-5a1 1 0 0 1-1-1v-5a1 1 0 0 1 1-1zM4 14h5a1 1 0 0 1 1 1v5a1 1 0 0 1-1 1h-5a1 1 0 0 1-1-1v-5a1 1 0 0 1 1-1z'), // layout-grid
+  table: outline('M12 3v18M5 3h14a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2h-14a2 2 0 0 1-2-2v-14a2 2 0 0 1 2-2zM3 9h18M3 15h18'),
+  image: outline('M5 3h14a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2h-14a2 2 0 0 1-2-2v-14a2 2 0 0 1 2-2zM7 9a2 2 0 1 0 4 0a2 2 0 1 0-4 0zM21 15l-3.086-3.086a2 2 0 0 0-2.828 0L6 21'),
+  columns: outline('M5 3h14a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2h-14a2 2 0 0 1-2-2v-14a2 2 0 0 1 2-2zM9 3v18M15 3v18'), // columns-3
+  type: outline('M12 4v16M4 7V5a1 1 0 0 1 1-1h14a1 1 0 0 1 1 1v2M9 20h6'),
+  hash: outline('M4 9h16M4 15h16M10 3L8 21M16 3l-2 18'),
+  mail: outline('M22 7l-8.991 5.727a2 2 0 0 1-2.009 0L2 7M4 4h16a2 2 0 0 1 2 2v12a2 2 0 0 1-2 2h-16a2 2 0 0 1-2-2v-12a2 2 0 0 1 2-2z'),
+  'link-2': outline('M9 17H7A5 5 0 0 1 7 7h2M15 7h2a5 5 0 1 1 0 10h-2M8 12h8'),
+  'circle-chevron-down': outline('M2 12a10 10 0 1 0 20 0a10 10 0 1 0-20 0zM16 10l-4 4-4-4')
   // </lucide-glyphs>
 });
 
@@ -171,7 +180,8 @@ const aliases = Object.freeze({
   checked: 'check',
   question: 'info',
   range: 'filter',
-  fields: 'list'
+  fields: 'list',
+  grid: 'table-cells-large'
 });
 
 /** @type {Record<string, IconGlyph>} Glyphs added at runtime by `registerIcons`. */

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)))