@augment-vir/web 31.17.0 → 31.18.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 (4) hide show
  1. package/dist/augments/elements/element-children.d.ts +30 -3
  2. package/dist/augments/elements/element-children.js +36 -3
  3. package/dist/augments/elements/event-target.d.ts +2 -2
  4. package/package.json +5 -5
package/dist/augments/elements/element-children.d.ts CHANGED
@@ -1,17 +1,44 @@
1
1
  /**
2
- * Gets all deeply nested elements contained within the given element. Shadow DOMs are traversed.
2
+ * Gets all deeply nested elements contained within the given element, flattened into a single
3
+ * array. Shadow DOMs are traversed.
3
4
  *
4
5
  * Note that `<slot>` elements are included, as well as their nested elements (even if a slot filler
5
6
  * is provided by the parent) and the slot filler itself (if provided).
6
7
  *
7
- * Optionally define a second "depth" input to control how far nestings should be pursued. Leave
8
- * depth out or set it to undefined or any value <= 0 to allow full depth search.
8
+ * Optionally define a second "depth" input to control how far nestings should be pursued. Omit
9
+ * depth or set it to `undefined` or `0` to allow full depth search.
9
10
  *
10
11
  * @category Web : Elements
11
12
  * @category Package : @augment-vir/web
12
13
  * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
13
14
  */
14
15
  export declare function getNestedChildren(startingElement: Readonly<Element>, depth?: number | undefined): Element[];
16
+ /**
17
+ * A tree of child elements.
18
+ *
19
+ * @category Web : Elements
20
+ * @category Package : @augment-vir/web
21
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
22
+ */
23
+ export type ElementTree = {
24
+ element: Element;
25
+ children: ElementTree[];
26
+ };
27
+ /**
28
+ * Gets all deeply nested elements contained within the given element in a tree. Shadow DOMs are
29
+ * traversed.
30
+ *
31
+ * Note that `<slot>` elements are included, as well as their nested elements (even if a slot filler
32
+ * is provided by the parent) and the slot filler itself (if provided).
33
+ *
34
+ * Optionally define a second "depth" input to control how far nestings should be pursued. Omit
35
+ * depth or set it to `undefined` or `0` to allow full depth search.
36
+ *
37
+ * @category Web : Elements
38
+ * @category Package : @augment-vir/web
39
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
40
+ */
41
+ export declare function getNestedChildrenTree(startingElement: Readonly<Element>, depth?: number | undefined): ElementTree;
15
42
  /**
16
43
  * Gets an element's direct children. Includes slotted elements, direct `<slot>` children
17
44
  * themselves, and all direct children of a shadow DOM. Default `<slot>` children are not included
package/dist/augments/elements/element-children.js CHANGED
@@ -1,11 +1,12 @@
1
1
  /**
2
- * Gets all deeply nested elements contained within the given element. Shadow DOMs are traversed.
2
+ * Gets all deeply nested elements contained within the given element, flattened into a single
3
+ * array. Shadow DOMs are traversed.
3
4
  *
4
5
  * Note that `<slot>` elements are included, as well as their nested elements (even if a slot filler
5
6
  * is provided by the parent) and the slot filler itself (if provided).
6
7
  *
7
- * Optionally define a second "depth" input to control how far nestings should be pursued. Leave
8
- * depth out or set it to undefined or any value <= 0 to allow full depth search.
8
+ * Optionally define a second "depth" input to control how far nestings should be pursued. Omit
9
+ * depth or set it to `undefined` or `0` to allow full depth search.
9
10
  *
10
11
  * @category Web : Elements
11
12
  * @category Package : @augment-vir/web
@@ -27,6 +28,38 @@ function recursivelyGetNestedChildren(startingElement, maxDepth, currentDepth) {
27
28
  ].flat();
28
29
  });
29
30
  }
31
+ /**
32
+ * Gets all deeply nested elements contained within the given element in a tree. Shadow DOMs are
33
+ * traversed.
34
+ *
35
+ * Note that `<slot>` elements are included, as well as their nested elements (even if a slot filler
36
+ * is provided by the parent) and the slot filler itself (if provided).
37
+ *
38
+ * Optionally define a second "depth" input to control how far nestings should be pursued. Omit
39
+ * depth or set it to `undefined` or `0` to allow full depth search.
40
+ *
41
+ * @category Web : Elements
42
+ * @category Package : @augment-vir/web
43
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
44
+ */
45
+ export function getNestedChildrenTree(startingElement, depth) {
46
+ return {
47
+ element: startingElement,
48
+ children: recursivelyGetNestedChildrenTree(startingElement, depth ?? 0, 0),
49
+ };
50
+ }
51
+ function recursivelyGetNestedChildrenTree(startingElement, maxDepth, currentDepth) {
52
+ return getDirectChildren(startingElement).map((child) => {
53
+ const nextDepth = currentDepth + 1;
54
+ const nested = maxDepth && nextDepth >= Math.abs(maxDepth)
55
+ ? []
56
+ : recursivelyGetNestedChildrenTree(child, maxDepth, nextDepth);
57
+ return {
58
+ element: child,
59
+ children: nested,
60
+ };
61
+ });
62
+ }
30
63
  /**
31
64
  * Gets an element's direct children. Includes slotted elements, direct `<slot>` children
32
65
  * themselves, and all direct children of a shadow DOM. Default `<slot>` children are not included
package/dist/augments/elements/event-target.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { type PartialWithUndefined } from '@augment-vir/common';
2
- import { type Constructor } from 'type-fest';
2
+ import { type AbstractConstructor, type Constructor } from 'type-fest';
3
3
  /**
4
4
  * Extract the event target element from an Event.
5
5
  *
@@ -15,7 +15,7 @@ import { type Constructor } from 'type-fest';
15
15
  *
16
16
  * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
17
17
  */
18
- export declare function extractEventTarget<ExpectedTargetClassConstructor extends Constructor<Element>>(event: Event, expectedTargetClass: ExpectedTargetClassConstructor, options?: PartialWithUndefined<{
18
+ export declare function extractEventTarget<ExpectedTargetClassConstructor extends AbstractConstructor<Element> | Constructor<Element>>(event: Event, expectedTargetClass: ExpectedTargetClassConstructor, options?: PartialWithUndefined<{
19
19
  /**
20
20
  * By default `extractEventTarget` uses the `Event.currentTarget` field to extract the event
21
21
  * target so that it extract the target to which the event handler was attached to. However,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@augment-vir/web",
3
- "version": "31.17.0",
3
+ "version": "31.18.0",
4
4
  "description": "A collection of augments, helpers types, functions, and classes only for web (frontend) JavaScript environments.",
5
5
  "keywords": [
6
6
  "augment",
@@ -36,14 +36,14 @@
36
36
  "test:update": "npm test"
37
37
  },
38
38
  "dependencies": {
39
- "@augment-vir/assert": "^31.17.0",
40
- "@augment-vir/common": "^31.17.0",
39
+ "@augment-vir/assert": "^31.18.0",
40
+ "@augment-vir/common": "^31.18.0",
41
41
  "@date-vir/duration": "^7.3.1",
42
42
  "html-spec-tags": "^2.2.2",
43
- "type-fest": "^4.40.1"
43
+ "type-fest": "^4.41.0"
44
44
  },
45
45
  "devDependencies": {
46
- "@augment-vir/test": "^31.17.0",
46
+ "@augment-vir/test": "^31.18.0",
47
47
  "bowser": "^2.11.0",
48
48
  "typescript": "^5.8.3"
49
49
  },