@y14e/roving-tabindex 1.0.1 → 1.1.0

package/README.md

@@ -43,10 +43,15 @@ const cleanup = createRovingTabIndex(container, options);
 interface RovingTabIndexOptions {
   direction?: 'horizontal' | 'vertical'; // default: both (undefined)
   selector?: string;
+  typeahead?: boolean;                   // default: false
   wrap?: boolean;                        // default: false
 }
 ```
 
+### `typeahead`
+
+If `true`, enables character-based focus navigation. Typing a character moves focus to the next matching element.
+
 ### `wrap`
 
 If `true`, wraps around to the first or last element when reaching the end.

package/dist/index.cjs

@@ -1,5 +1,36 @@
 'use strict';
 
+// node_modules/@y14e/attributes-utils/dist/index.js
+var snapshots = /* @__PURE__ */ new WeakMap();
+function restoreAttributes(elements) {
+  elements.forEach((element) => {
+    const snapshot = snapshots.get(element);
+    if (!snapshot) {
+      return;
+    }
+    for (const [attribute, value] of snapshot.entries()) {
+      if (value === null) {
+        element.removeAttribute(attribute);
+      } else {
+        element.setAttribute(attribute, value);
+      }
+    }
+    snapshots.delete(element);
+  });
+}
+function saveAttributes(elements, attributes) {
+  elements.forEach((element) => {
+    let snapshot = snapshots.get(element);
+    if (!snapshot) {
+      snapshot = /* @__PURE__ */ new Map();
+      snapshots.set(element, snapshot);
+    }
+    attributes.forEach((attribute) => {
+      snapshot.set(attribute, element.getAttribute(attribute));
+    });
+  });
+}
+
 // node_modules/power-focusable/dist/index.js
 var FOCUSABLE_SELECTOR = `:is(a[href], area[href], button, embed, iframe, input:not([type="hidden" i]), object, select, details > summary:first-of-type, textarea, [contenteditable]:not([contenteditable="false" i]), [controls], [tabindex]):not(:disabled, [hidden], [inert], [tabindex="-1"])`;
 function getFocusables(container = document.body, options = {}) {
@@ -207,7 +238,7 @@ function createRovingTabIndex(container, options = {}) {
   if (!(container instanceof Element)) {
     throw new Error("Invalid container element");
   }
-  const { direction, selector, wrap = false } = options;
+  const { direction, selector, typeahead = false, wrap = false } = options;
   if (direction && !["horizontal", "vertical"].includes(direction)) {
     console.warn("Invalid direction. Fallback: both (undefined).");
     Object.assign(options, { direction: void 0 });
@@ -216,6 +247,10 @@ function createRovingTabIndex(container, options = {}) {
     console.warn("Invalid selector. Fallback: all focusable elements.");
     Object.assign(options, { selector: void 0 });
   }
+  if (typeof typeahead !== "boolean") {
+    console.warn("Invalid typeahead. Fallback: false.");
+    Object.assign(options, { typeahead: false });
+  }
   if (typeof wrap !== "boolean") {
     console.warn("Invalid wrap. Fallback: false.");
     Object.assign(options, { wrap: false });
@@ -227,7 +262,7 @@ var RovingTabIndex = class {
   #container;
   #options;
   #focusables = /* @__PURE__ */ new Set();
-  #tabIndexes = /* @__PURE__ */ new Map();
+  #focusablesByFirstChar = /* @__PURE__ */ new Map();
   #selectorFilter;
   #controller = null;
   #isDestroyed = false;
@@ -244,16 +279,9 @@ var RovingTabIndex = class {
     this.#isDestroyed = true;
     this.#controller?.abort();
     this.#controller = null;
-    this.#focusables.forEach((focusable) => {
-      const index = this.#tabIndexes.get(focusable);
-      if (index == null) {
-        focusable.removeAttribute("tabindex");
-      } else {
-        focusable.setAttribute("tabindex", index);
-      }
-    });
+    restoreAttributes([...this.#focusables]);
     this.#focusables.clear();
-    this.#tabIndexes.clear();
+    this.#focusablesByFirstChar.clear();
     this.#container.removeAttribute("data-roving-tabindex-initialized");
   }
   #initialize() {
@@ -273,7 +301,7 @@ var RovingTabIndex = class {
     if (altKey || ctrlKey || metaKey) {
       return;
     }
-    const { direction } = this.#options;
+    const { direction, typeahead, wrap } = this.#options;
     const isBoth = !direction;
     const isHorizontal = direction === "horizontal";
     if (![
@@ -282,7 +310,9 @@ var RovingTabIndex = class {
       ...isBoth ? ["ArrowLeft", "ArrowUp"] : [`Arrow${isHorizontal ? "Left" : "Up"}`],
       ...isBoth ? ["ArrowRight", "ArrowDown"] : [`Arrow${isHorizontal ? "Right" : "Down"}`]
     ].includes(key)) {
-      return;
+      if (!typeahead || !/^\S$/i.test(key) || !this.#focusablesByFirstChar.has(key.toLowerCase())) {
+        return;
+      }
     }
     const active = getActiveElement();
     if (!(active instanceof HTMLElement)) {
@@ -295,9 +325,9 @@ var RovingTabIndex = class {
     event.preventDefault();
     event.stopPropagation();
     const currentIndex = focusables.indexOf(active);
-    let rawIndex;
+    let rawIndex = currentIndex;
     let newIndex = currentIndex;
-    const { wrap = false } = this.#options;
+    let target = focusables;
     switch (key) {
       case "End":
         newIndex = -1;
@@ -315,8 +345,18 @@ var RovingTabIndex = class {
         rawIndex = currentIndex + 1;
         newIndex = wrap ? rawIndex % focusables.length : Math.min(rawIndex, focusables.length - 1);
         break;
+      default: {
+        if (!typeahead) {
+          break;
+        }
+        target = this.#focusablesByFirstChar.get(key.toLowerCase()) ?? [];
+        const foundIndex = target.findIndex(
+          (focusable2) => focusables.indexOf(focusable2) > currentIndex
+        );
+        newIndex = foundIndex !== -1 ? foundIndex : 0;
+      }
     }
-    const focusable = focusables.at(newIndex);
+    const focusable = target.at(newIndex);
     if (!focusable) {
       return;
     }
@@ -336,23 +376,36 @@ var RovingTabIndex = class {
         return;
       }
       if (focusable.isConnected) {
-        const index = this.#tabIndexes.get(focusable);
-        if (index == null) {
-          focusable.removeAttribute("tabindex");
-        } else {
-          focusable.setAttribute("tabindex", index);
-        }
+        restoreAttributes([focusable]);
       }
       this.#focusables.delete(focusable);
-      this.#tabIndexes.delete(focusable);
+      this.#focusablesByFirstChar.forEach((focusables) => {
+        const index = focusables.indexOf(focusable);
+        if (index !== -1) {
+          focusables.splice(index, 1);
+        }
+      });
     });
     current.forEach((c) => {
       if (this.#focusables.has(c)) {
         return;
       }
       this.#focusables.add(c);
-      this.#tabIndexes.set(c, c.getAttribute("tabindex"));
+      saveAttributes([c], ["tabindex"]);
       c.setAttribute("tabindex", "-1");
+      if (!this.#options.typeahead) {
+        return;
+      }
+      const shortcuts = c.ariaKeyShortcuts;
+      const keys = (shortcuts?.split(/\s+/) ?? [c.textContent?.trim()[0] ?? ""]).filter((key) => /^\S$/i.test(key)).map((key) => key.toLowerCase());
+      keys.forEach((key) => {
+        const focusables = this.#focusablesByFirstChar.get(key) ?? [];
+        focusables.push(c);
+        this.#focusablesByFirstChar.set(key, focusables);
+      });
+      const first = keys[0];
+      saveAttributes([c], ["aria-keyshortcuts"]);
+      !shortcuts && first && c.setAttribute("aria-keyshortcuts", first);
     });
     if (active && this.#focusables.has(active)) {
       this.#focusables.forEach((focusable) => {
@@ -391,7 +444,7 @@ function getActiveElement() {
  * Lightweight roving tabindex utility with fully focus management.
  * Designed for accessible menus, tabs, toolbars, and composite widgets.
  *
- * @version 1.0.1
+ * @version 1.1.0
  * @author Yusuke Kamiyamane
  * @license MIT
  * @copyright Copyright (c) Yusuke Kamiyamane
@@ -399,6 +452,17 @@ function getActiveElement() {
  */
 /*! Bundled license information:
 
+@y14e/attributes-utils/dist/index.js:
+  (**
+   * Attributes Utils
+   *
+   * @version 1.0.0
+   * @author Yusuke Kamiyamane
+   * @license MIT
+   * @copyright Copyright (c) Yusuke Kamiyamane
+   * @see {@link https://github.com/y14e/attributes-utils}
+   *)
+
 power-focusable/dist/index.js:
   (**
    * Power Focusable

package/dist/index.d.cts

@@ -3,7 +3,7 @@
  * Lightweight roving tabindex utility with fully focus management.
  * Designed for accessible menus, tabs, toolbars, and composite widgets.
  *
- * @version 1.0.1
+ * @version 1.1.0
  * @author Yusuke Kamiyamane
  * @license MIT
  * @copyright Copyright (c) Yusuke Kamiyamane
@@ -12,6 +12,7 @@
 interface RovingTabIndexOptions {
     readonly direction?: 'horizontal' | 'vertical';
     readonly selector?: string;
+    readonly typeahead?: boolean;
     readonly wrap?: boolean;
 }
 declare function createRovingTabIndex(container: Element, options?: RovingTabIndexOptions): () => void;

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  * Lightweight roving tabindex utility with fully focus management.
  * Designed for accessible menus, tabs, toolbars, and composite widgets.
  *
- * @version 1.0.1
+ * @version 1.1.0
  * @author Yusuke Kamiyamane
  * @license MIT
  * @copyright Copyright (c) Yusuke Kamiyamane
@@ -12,6 +12,7 @@
 interface RovingTabIndexOptions {
     readonly direction?: 'horizontal' | 'vertical';
     readonly selector?: string;
+    readonly typeahead?: boolean;
     readonly wrap?: boolean;
 }
 declare function createRovingTabIndex(container: Element, options?: RovingTabIndexOptions): () => void;

package/dist/index.js

@@ -1,3 +1,34 @@
+// node_modules/@y14e/attributes-utils/dist/index.js
+var snapshots = /* @__PURE__ */ new WeakMap();
+function restoreAttributes(elements) {
+  elements.forEach((element) => {
+    const snapshot = snapshots.get(element);
+    if (!snapshot) {
+      return;
+    }
+    for (const [attribute, value] of snapshot.entries()) {
+      if (value === null) {
+        element.removeAttribute(attribute);
+      } else {
+        element.setAttribute(attribute, value);
+      }
+    }
+    snapshots.delete(element);
+  });
+}
+function saveAttributes(elements, attributes) {
+  elements.forEach((element) => {
+    let snapshot = snapshots.get(element);
+    if (!snapshot) {
+      snapshot = /* @__PURE__ */ new Map();
+      snapshots.set(element, snapshot);
+    }
+    attributes.forEach((attribute) => {
+      snapshot.set(attribute, element.getAttribute(attribute));
+    });
+  });
+}
+
 // node_modules/power-focusable/dist/index.js
 var FOCUSABLE_SELECTOR = `:is(a[href], area[href], button, embed, iframe, input:not([type="hidden" i]), object, select, details > summary:first-of-type, textarea, [contenteditable]:not([contenteditable="false" i]), [controls], [tabindex]):not(:disabled, [hidden], [inert], [tabindex="-1"])`;
 function getFocusables(container = document.body, options = {}) {
@@ -205,7 +236,7 @@ function createRovingTabIndex(container, options = {}) {
   if (!(container instanceof Element)) {
     throw new Error("Invalid container element");
   }
-  const { direction, selector, wrap = false } = options;
+  const { direction, selector, typeahead = false, wrap = false } = options;
   if (direction && !["horizontal", "vertical"].includes(direction)) {
     console.warn("Invalid direction. Fallback: both (undefined).");
     Object.assign(options, { direction: void 0 });
@@ -214,6 +245,10 @@ function createRovingTabIndex(container, options = {}) {
     console.warn("Invalid selector. Fallback: all focusable elements.");
     Object.assign(options, { selector: void 0 });
   }
+  if (typeof typeahead !== "boolean") {
+    console.warn("Invalid typeahead. Fallback: false.");
+    Object.assign(options, { typeahead: false });
+  }
   if (typeof wrap !== "boolean") {
     console.warn("Invalid wrap. Fallback: false.");
     Object.assign(options, { wrap: false });
@@ -225,7 +260,7 @@ var RovingTabIndex = class {
   #container;
   #options;
   #focusables = /* @__PURE__ */ new Set();
-  #tabIndexes = /* @__PURE__ */ new Map();
+  #focusablesByFirstChar = /* @__PURE__ */ new Map();
   #selectorFilter;
   #controller = null;
   #isDestroyed = false;
@@ -242,16 +277,9 @@ var RovingTabIndex = class {
     this.#isDestroyed = true;
     this.#controller?.abort();
     this.#controller = null;
-    this.#focusables.forEach((focusable) => {
-      const index = this.#tabIndexes.get(focusable);
-      if (index == null) {
-        focusable.removeAttribute("tabindex");
-      } else {
-        focusable.setAttribute("tabindex", index);
-      }
-    });
+    restoreAttributes([...this.#focusables]);
     this.#focusables.clear();
-    this.#tabIndexes.clear();
+    this.#focusablesByFirstChar.clear();
     this.#container.removeAttribute("data-roving-tabindex-initialized");
   }
   #initialize() {
@@ -271,7 +299,7 @@ var RovingTabIndex = class {
     if (altKey || ctrlKey || metaKey) {
       return;
     }
-    const { direction } = this.#options;
+    const { direction, typeahead, wrap } = this.#options;
     const isBoth = !direction;
     const isHorizontal = direction === "horizontal";
     if (![
@@ -280,7 +308,9 @@ var RovingTabIndex = class {
       ...isBoth ? ["ArrowLeft", "ArrowUp"] : [`Arrow${isHorizontal ? "Left" : "Up"}`],
       ...isBoth ? ["ArrowRight", "ArrowDown"] : [`Arrow${isHorizontal ? "Right" : "Down"}`]
     ].includes(key)) {
-      return;
+      if (!typeahead || !/^\S$/i.test(key) || !this.#focusablesByFirstChar.has(key.toLowerCase())) {
+        return;
+      }
     }
     const active = getActiveElement();
     if (!(active instanceof HTMLElement)) {
@@ -293,9 +323,9 @@ var RovingTabIndex = class {
     event.preventDefault();
     event.stopPropagation();
     const currentIndex = focusables.indexOf(active);
-    let rawIndex;
+    let rawIndex = currentIndex;
     let newIndex = currentIndex;
-    const { wrap = false } = this.#options;
+    let target = focusables;
     switch (key) {
       case "End":
         newIndex = -1;
@@ -313,8 +343,18 @@ var RovingTabIndex = class {
         rawIndex = currentIndex + 1;
         newIndex = wrap ? rawIndex % focusables.length : Math.min(rawIndex, focusables.length - 1);
         break;
+      default: {
+        if (!typeahead) {
+          break;
+        }
+        target = this.#focusablesByFirstChar.get(key.toLowerCase()) ?? [];
+        const foundIndex = target.findIndex(
+          (focusable2) => focusables.indexOf(focusable2) > currentIndex
+        );
+        newIndex = foundIndex !== -1 ? foundIndex : 0;
+      }
     }
-    const focusable = focusables.at(newIndex);
+    const focusable = target.at(newIndex);
     if (!focusable) {
       return;
     }
@@ -334,23 +374,36 @@ var RovingTabIndex = class {
         return;
       }
       if (focusable.isConnected) {
-        const index = this.#tabIndexes.get(focusable);
-        if (index == null) {
-          focusable.removeAttribute("tabindex");
-        } else {
-          focusable.setAttribute("tabindex", index);
-        }
+        restoreAttributes([focusable]);
       }
       this.#focusables.delete(focusable);
-      this.#tabIndexes.delete(focusable);
+      this.#focusablesByFirstChar.forEach((focusables) => {
+        const index = focusables.indexOf(focusable);
+        if (index !== -1) {
+          focusables.splice(index, 1);
+        }
+      });
     });
     current.forEach((c) => {
       if (this.#focusables.has(c)) {
         return;
       }
       this.#focusables.add(c);
-      this.#tabIndexes.set(c, c.getAttribute("tabindex"));
+      saveAttributes([c], ["tabindex"]);
       c.setAttribute("tabindex", "-1");
+      if (!this.#options.typeahead) {
+        return;
+      }
+      const shortcuts = c.ariaKeyShortcuts;
+      const keys = (shortcuts?.split(/\s+/) ?? [c.textContent?.trim()[0] ?? ""]).filter((key) => /^\S$/i.test(key)).map((key) => key.toLowerCase());
+      keys.forEach((key) => {
+        const focusables = this.#focusablesByFirstChar.get(key) ?? [];
+        focusables.push(c);
+        this.#focusablesByFirstChar.set(key, focusables);
+      });
+      const first = keys[0];
+      saveAttributes([c], ["aria-keyshortcuts"]);
+      !shortcuts && first && c.setAttribute("aria-keyshortcuts", first);
     });
     if (active && this.#focusables.has(active)) {
       this.#focusables.forEach((focusable) => {
@@ -389,7 +442,7 @@ function getActiveElement() {
  * Lightweight roving tabindex utility with fully focus management.
  * Designed for accessible menus, tabs, toolbars, and composite widgets.
  *
- * @version 1.0.1
+ * @version 1.1.0
  * @author Yusuke Kamiyamane
  * @license MIT
  * @copyright Copyright (c) Yusuke Kamiyamane
@@ -397,6 +450,17 @@ function getActiveElement() {
  */
 /*! Bundled license information:
 
+@y14e/attributes-utils/dist/index.js:
+  (**
+   * Attributes Utils
+   *
+   * @version 1.0.0
+   * @author Yusuke Kamiyamane
+   * @license MIT
+   * @copyright Copyright (c) Yusuke Kamiyamane
+   * @see {@link https://github.com/y14e/attributes-utils}
+   *)
+
 power-focusable/dist/index.js:
   (**
    * Power Focusable

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@y14e/roving-tabindex",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Lightweight roving tabindex utility with fully focus management",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -48,6 +48,7 @@
   },
   "homepage": "https://github.com/y14e/roving-tabindex#readme",
   "devDependencies": {
+    "@y14e/attributes-utils": "^1.0.0",
     "bun-types": "latest",
     "power-focusable": "^4.1.5",
     "tsup": "^8.0.0",