power-focusable 3.0.1 → 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 +18 -8
  3. package/dist/index.d.cts +2 -1
  4. package/dist/index.d.ts +2 -1
  5. package/dist/index.js +18 -8
  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;
@@ -201,7 +202,7 @@ function isDisabledDeep(element) {
201
202
  if (current === element && isFormControl(current) && isDisabled(current)) {
202
203
  return true;
203
204
  }
204
- if (current.hasAttribute("inert")) {
205
+ if (isInert(current)) {
205
206
  return true;
206
207
  }
207
208
  if (isFormControl(element) && current.tagName === "FIELDSET" && isDisabled(current)) {
@@ -308,9 +309,18 @@ function getComposedParent(node) {
308
309
  }
309
310
  function getComposedSiblings(node) {
310
311
  if (node.assignedSlot) {
311
- return [...node.assignedSlot.children].filter(
312
- (child) => child instanceof Element && child !== node
313
- );
312
+ const siblings = node.assignedSlot.children;
313
+ const filtered = [];
314
+ for (let i = 0, l = siblings.length; i < l; i++) {
315
+ const sibling = siblings[i];
316
+ if (sibling !== node) {
317
+ if (!(sibling instanceof Element)) {
318
+ continue;
319
+ }
320
+ filtered[filtered.length] = sibling;
321
+ }
322
+ }
323
+ return filtered;
314
324
  }
315
325
  const parent = getComposedParent(node);
316
326
  if (!parent) {
@@ -403,7 +413,7 @@ function setInert(element, boolean) {
403
413
  * Handles complex focus rules including tabindex ordering, radio groups, inert,
404
414
  * and shadow DOM.
405
415
  *
406
- * @version 3.0.1
416
+ * @version 3.1.0
407
417
  * @author Yusuke Kamiyamane
408
418
  * @license MIT
409
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.1
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.1
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;
@@ -199,7 +200,7 @@ function isDisabledDeep(element) {
199
200
  if (current === element && isFormControl(current) && isDisabled(current)) {
200
201
  return true;
201
202
  }
202
- if (current.hasAttribute("inert")) {
203
+ if (isInert(current)) {
203
204
  return true;
204
205
  }
205
206
  if (isFormControl(element) && current.tagName === "FIELDSET" && isDisabled(current)) {
@@ -306,9 +307,18 @@ function getComposedParent(node) {
306
307
  }
307
308
  function getComposedSiblings(node) {
308
309
  if (node.assignedSlot) {
309
- return [...node.assignedSlot.children].filter(
310
- (child) => child instanceof Element && child !== node
311
- );
310
+ const siblings = node.assignedSlot.children;
311
+ const filtered = [];
312
+ for (let i = 0, l = siblings.length; i < l; i++) {
313
+ const sibling = siblings[i];
314
+ if (sibling !== node) {
315
+ if (!(sibling instanceof Element)) {
316
+ continue;
317
+ }
318
+ filtered[filtered.length] = sibling;
319
+ }
320
+ }
321
+ return filtered;
312
322
  }
313
323
  const parent = getComposedParent(node);
314
324
  if (!parent) {
@@ -401,7 +411,7 @@ function setInert(element, boolean) {
401
411
  * Handles complex focus rules including tabindex ordering, radio groups, inert,
402
412
  * and shadow DOM.
403
413
  *
404
- * @version 3.0.1
414
+ * @version 3.1.0
405
415
  * @author Yusuke Kamiyamane
406
416
  * @license MIT
407
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.1",
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",