power-focusable 3.0.2 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +24 -3
  2. package/dist/index.cjs +5 -4
  3. package/dist/index.d.cts +2 -1
  4. package/dist/index.d.ts +2 -1
  5. package/dist/index.js +5 -4
  6. package/package.json +1 -1
package/README.md CHANGED
@@ -35,9 +35,10 @@ import { ... } 'https://unpkg.com/power-focusable/dist/index.js';
35
35
 
36
36
  ```ts
37
37
  interface PowerFocusableOptions {
38
- active?: Element | null; // default: document.activeElement
39
- composed?: boolean; // default: false
40
- wrap?: boolean; // default: false
38
+ active?: Element | null; // default: document.activeElement
39
+ composed?: boolean; // default: false
40
+ filter?: (element: Element) => boolean; // default: () => true
41
+ wrap?: boolean; // default: false
41
42
  }
42
43
  ```
43
44
 
@@ -53,6 +54,14 @@ If `true`, traverses the composed tree (including shadow DOM; slower)
53
54
 
54
55
  Used by `getFocusables`, `getNextFocusable`, `getPreviousFocusable`, and `hasFocusable`.
55
56
 
57
+ ### `filter`
58
+
59
+ Custom filter function for excluding elements from focus traversal. Useful for advanced focus management such as portals, virtual focus regions, temporary exclusions, or custom focus scopes.
60
+
61
+ The function should return `true` to include the element, or `false` to exclude it.
62
+
63
+ Used by `getFocusables`, `getNextFocusable`, `getPreviousFocusable`, and `hasFocusable`.
64
+
56
65
  ### `wrap`
57
66
 
58
67
  If `true`, wraps around to the first or last element when reaching the end.
@@ -84,6 +93,9 @@ getFocusables(container);
84
93
 
85
94
  // Traverses the composed tree (including shadow DOM; slower)
86
95
  getFocusables(container, { composed: true });
96
+
97
+ // Uses custom filter function
98
+ getFocusables(container, { filter: (element) => !element.matches('[data-skip-focus]') });
87
99
  ```
88
100
 
89
101
  ### `getNextFocusable`
@@ -102,6 +114,9 @@ getNextFocusable(container, { active: document.querySelector('.button') });
102
114
  // Traverses the composed tree (including shadow DOM; slower)
103
115
  getNextFocusable(container, { composed: true });
104
116
 
117
+ // Uses custom filter function
118
+ getNextFocusable(container, { filter: (element) => !element.matches('[data-skip-focus]') });
119
+
105
120
  // Wraps around to the first element when reaching the end
106
121
  getNextFocusable(container, { wrap: true });
107
122
  ```
@@ -122,6 +137,9 @@ getPreviousFocusable(container, { active: document.querySelector('.button') });
122
137
  // Traverses the composed tree (including shadow DOM; slower)
123
138
  getPreviousFocusable(container, { composed: true });
124
139
 
140
+ // Uses custom filter function
141
+ getPreviousFocusable(container, { filter: (element) => !element.matches('[data-skip-focus]') });
142
+
125
143
  //Wraps around to the last element when reaching the end
126
144
  getPreviousFocusable(container, { wrap: true });
127
145
 
@@ -139,6 +157,9 @@ hasFocusable(container);
139
157
 
140
158
  // Traverses the composed tree (including shadow DOM; slower)
141
159
  hasFocusable(container, { composed: true });
160
+
161
+ // Uses custom filter function
162
+ hasFocusable(container, { filter: (element) => !element.matches('[data-skip-focus]') });
142
163
  ```
143
164
 
144
165
  ### `inertOutside`
package/dist/index.cjs CHANGED
@@ -46,7 +46,7 @@ function getFocusables(container = document.body, options = {}) {
46
46
  console.warn("Invalid container element. Fallback: <body> element.");
47
47
  container = document.body;
48
48
  }
49
- const { composed = false } = options;
49
+ const { composed = false, filter = () => true } = options;
50
50
  const elements = [];
51
51
  if (composed) {
52
52
  let traverse2 = function(node) {
@@ -77,7 +77,7 @@ function getFocusables(container = document.body, options = {}) {
77
77
  }
78
78
  }
79
79
  }
80
- return normalizeRadioGroup(sortByTabIndex(elements));
80
+ return normalizeRadioGroup(sortByTabIndex(elements)).filter(filter);
81
81
  }
82
82
  function getNextFocusable(container = document.body, options = {}) {
83
83
  if (!(container instanceof Element)) {
@@ -161,9 +161,10 @@ function getRelativeFocusable(container, offset, options) {
161
161
  const {
162
162
  active = getActiveElement(),
163
163
  composed = false,
164
+ filter = () => true,
164
165
  wrap = false
165
166
  } = options;
166
- const focusables = getFocusables(container, { composed });
167
+ const focusables = getFocusables(container, { composed, filter });
167
168
  const { length } = focusables;
168
169
  if (!length) {
169
170
  return null;
@@ -412,7 +413,7 @@ function setInert(element, boolean) {
412
413
  * Handles complex focus rules including tabindex ordering, radio groups, inert,
413
414
  * and shadow DOM.
414
415
  *
415
- * @version 3.0.2
416
+ * @version 3.1.0
416
417
  * @author Yusuke Kamiyamane
417
418
  * @license MIT
418
419
  * @copyright Copyright (c) Yusuke Kamiyamane
package/dist/index.d.cts CHANGED
@@ -4,7 +4,7 @@
4
4
  * Handles complex focus rules including tabindex ordering, radio groups, inert,
5
5
  * and shadow DOM.
6
6
  *
7
- * @version 3.0.2
7
+ * @version 3.1.0
8
8
  * @author Yusuke Kamiyamane
9
9
  * @license MIT
10
10
  * @copyright Copyright (c) Yusuke Kamiyamane
@@ -13,6 +13,7 @@
13
13
  interface PowerFocusableOptions {
14
14
  readonly active?: Element | null;
15
15
  readonly composed?: boolean;
16
+ readonly filter?: (element: Element) => boolean;
16
17
  readonly wrap?: boolean;
17
18
  }
18
19
  declare function createFocusTrap(container: Element): () => void;
package/dist/index.d.ts CHANGED
@@ -4,7 +4,7 @@
4
4
  * Handles complex focus rules including tabindex ordering, radio groups, inert,
5
5
  * and shadow DOM.
6
6
  *
7
- * @version 3.0.2
7
+ * @version 3.1.0
8
8
  * @author Yusuke Kamiyamane
9
9
  * @license MIT
10
10
  * @copyright Copyright (c) Yusuke Kamiyamane
@@ -13,6 +13,7 @@
13
13
  interface PowerFocusableOptions {
14
14
  readonly active?: Element | null;
15
15
  readonly composed?: boolean;
16
+ readonly filter?: (element: Element) => boolean;
16
17
  readonly wrap?: boolean;
17
18
  }
18
19
  declare function createFocusTrap(container: Element): () => void;
package/dist/index.js CHANGED
@@ -44,7 +44,7 @@ function getFocusables(container = document.body, options = {}) {
44
44
  console.warn("Invalid container element. Fallback: <body> element.");
45
45
  container = document.body;
46
46
  }
47
- const { composed = false } = options;
47
+ const { composed = false, filter = () => true } = options;
48
48
  const elements = [];
49
49
  if (composed) {
50
50
  let traverse2 = function(node) {
@@ -75,7 +75,7 @@ function getFocusables(container = document.body, options = {}) {
75
75
  }
76
76
  }
77
77
  }
78
- return normalizeRadioGroup(sortByTabIndex(elements));
78
+ return normalizeRadioGroup(sortByTabIndex(elements)).filter(filter);
79
79
  }
80
80
  function getNextFocusable(container = document.body, options = {}) {
81
81
  if (!(container instanceof Element)) {
@@ -159,9 +159,10 @@ function getRelativeFocusable(container, offset, options) {
159
159
  const {
160
160
  active = getActiveElement(),
161
161
  composed = false,
162
+ filter = () => true,
162
163
  wrap = false
163
164
  } = options;
164
- const focusables = getFocusables(container, { composed });
165
+ const focusables = getFocusables(container, { composed, filter });
165
166
  const { length } = focusables;
166
167
  if (!length) {
167
168
  return null;
@@ -410,7 +411,7 @@ function setInert(element, boolean) {
410
411
  * Handles complex focus rules including tabindex ordering, radio groups, inert,
411
412
  * and shadow DOM.
412
413
  *
413
- * @version 3.0.2
414
+ * @version 3.1.0
414
415
  * @author Yusuke Kamiyamane
415
416
  * @license MIT
416
417
  * @copyright Copyright (c) Yusuke Kamiyamane
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "power-focusable",
3
- "version": "3.0.2",
3
+ "version": "3.1.0",
4
4
  "description": "High-precision focus management utility with full composed tree support",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",