react-children-hooks 0.3.0 → 0.4.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.
package/dist/index.d.cts CHANGED
@@ -14,16 +14,47 @@ type ChildrenCountBounds = {
14
14
  */
15
15
  maximum: number;
16
16
  };
17
+ /**
18
+ * Optional traversal bounds used by the element-based query and validation hooks.
19
+ */
20
+ type TraversalOptions = {
21
+ /**
22
+ * The minimum inclusive child depth to include in results, where `0` represents direct children.
23
+ */
24
+ depth?: number;
25
+ /**
26
+ * The maximum inclusive child depth to include in results, where `0` represents direct children.
27
+ */
28
+ maximumDepth?: number;
29
+ };
30
+ /**
31
+ * Optional traversal metadata used by the element-based query hooks.
32
+ */
33
+ type QueryOptions = TraversalOptions;
17
34
  /**
18
35
  * Represents a React element whose props and element type are narrowed to the provided React element type.
19
36
  *
20
37
  * @typeParam T The React element type used to narrow the element's props and type.
21
38
  */
22
39
  type ElementOfType<T extends React.ElementType> = React.ReactElement<React.ComponentProps<T>, T>;
40
+ /**
41
+ * A callback child, also known as a render-prop child.
42
+ *
43
+ * @typeParam TArguments The positional argument tuple accepted by the callback.
44
+ * @typeParam TResult The value returned by the callback.
45
+ */
46
+ type CallbackChild<TArguments extends unknown[] = [], TResult = React.ReactNode> = (...args: TArguments) => TResult;
47
+ /**
48
+ * A direct-children value that may include callback children alongside regular React children.
49
+ *
50
+ * @typeParam TArguments The positional argument tuple accepted by callback children.
51
+ * @typeParam TResult The value returned by callback children.
52
+ */
53
+ type CallbackChildren<TArguments extends unknown[] = [], TResult = React.ReactNode> = React.ReactNode | CallbackChild<TArguments, TResult> | readonly CallbackChildren<TArguments, TResult>[];
23
54
  /**
24
55
  * Optional reporting metadata used by the validation hooks to derive thrown validation messages.
25
56
  */
26
- type ValidationOptions = {
57
+ type ValidationMessageOptions = {
27
58
  /**
28
59
  * An optional consumer-defined trace code that is prefixed to the thrown validation message.
29
60
  */
@@ -33,25 +64,39 @@ type ValidationOptions = {
33
64
  */
34
65
  childName?: string;
35
66
  };
67
+ /**
68
+ * Optional reporting and traversal metadata used by the validation hooks.
69
+ */
70
+ type ValidationOptions = ValidationMessageOptions & TraversalOptions;
36
71
 
37
72
  /**
38
73
  * Returns the first direct child element whose React element type exactly matches the provided type.
39
74
  *
40
75
  * @param children The React children value to inspect.
41
76
  * @param type The element or component type to match against each direct child element.
77
+ * @param options Optional query metadata used to configure how child elements are inspected.
42
78
  * @returns The first direct child element whose type matches the provided element type, or `null` when no match is found.
43
79
  */
44
- declare function useChildByType<T extends ElementType>(children: ReactNode, type: T): ElementOfType<T> | null;
80
+ declare function useChildByType<T extends ElementType>(children: ReactNode, type: T, options?: QueryOptions): ElementOfType<T> | null;
81
+
82
+ /**
83
+ * Returns the first direct callback child from the provided children value.
84
+ *
85
+ * @param children The direct children value to inspect.
86
+ * @returns The first direct callback child, or `null` when no callback child is found.
87
+ */
88
+ declare function useCallbackChild<TArguments extends unknown[] = [], TResult = ReactNode>(children: CallbackChildren<TArguments, TResult>): CallbackChild<TArguments, TResult> | null;
45
89
 
46
90
  /**
47
91
  * Returns the first direct child element that satisfies the provided predicate.
48
92
  *
49
93
  * @param children The React children value to inspect.
50
94
  * @param predicate A predicate that is called with each direct child element to determine whether it matches.
95
+ * @param options Optional query metadata used to configure how child elements are inspected.
51
96
  * @returns The first direct child element that satisfies the provided predicate, or `null` when no match is found.
52
97
  */
53
- declare function useChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): T | null;
54
- declare function useChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean): ReactElement | null;
98
+ declare function useChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: QueryOptions): T | null;
99
+ declare function useChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: QueryOptions): ReactElement | null;
55
100
 
56
101
  /**
57
102
  * Returns the direct child elements whose React element type exactly matches the provided type, or throws when the count falls outside the inclusive bounds.
@@ -81,19 +126,21 @@ declare function useBoundedChildrenMatching(children: ReactNode, predicate: (ele
81
126
  *
82
127
  * @param children The React children value to inspect.
83
128
  * @param type The element or component type to match against each direct child element.
129
+ * @param options Optional query metadata used to configure how child elements are inspected.
84
130
  * @returns An array of direct child elements whose type matches the provided element type.
85
131
  */
86
- declare function useChildrenByType<T extends ElementType>(children: ReactNode, type: T): ElementOfType<T>[];
132
+ declare function useChildrenByType<T extends ElementType>(children: ReactNode, type: T, options?: QueryOptions): ElementOfType<T>[];
87
133
 
88
134
  /**
89
135
  * Returns the direct child elements that satisfy the provided predicate.
90
136
  *
91
137
  * @param children The React children value to inspect.
92
138
  * @param predicate A predicate that is called with each direct child element to determine whether it should be included in the result.
139
+ * @param options Optional query metadata used to configure how child elements are inspected.
93
140
  * @returns An array of direct child elements that satisfy the provided predicate.
94
141
  */
95
- declare function useChildrenMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): T[];
96
- declare function useChildrenMatching(children: ReactNode, predicate: (element: ReactElement) => boolean): ReactElement[];
142
+ declare function useChildrenMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: QueryOptions): T[];
143
+ declare function useChildrenMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: QueryOptions): ReactElement[];
97
144
 
98
145
  /**
99
146
  * Returns the direct child elements whose React element type exactly matches the provided type, or throws when the exact count is not met.
@@ -123,10 +170,11 @@ declare function useExactChildrenMatching(children: ReactNode, predicate: (eleme
123
170
  *
124
171
  * @param children The React children value to inspect.
125
172
  * @param predicate A predicate that is called with each direct child element to determine whether it matches.
173
+ * @param options Optional query metadata used to configure how child elements are inspected.
126
174
  * @returns `true` when at least one direct child element satisfies the provided predicate; otherwise `false`.
127
175
  */
128
- declare function useHasChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): boolean;
129
- declare function useHasChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean): boolean;
176
+ declare function useHasChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: QueryOptions): boolean;
177
+ declare function useHasChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: QueryOptions): boolean;
130
178
 
131
179
  /**
132
180
  * Returns the direct child elements whose React element type exactly matches the provided type, or throws when more than the maximum count are found.
@@ -174,6 +222,27 @@ declare function useMinimumChildrenByType<T extends ElementType>(children: React
174
222
  declare function useMinimumChildrenMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, minimumCount: number, options?: ValidationOptions): T[];
175
223
  declare function useMinimumChildrenMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, minimumCount: number, options?: ValidationOptions): ReactElement[];
176
224
 
225
+ /**
226
+ * Returns the optional direct child element whose React element type exactly matches the provided type, or throws when more than one match is found.
227
+ *
228
+ * @param children The React children value to inspect.
229
+ * @param type The element or component type to match against each direct child element.
230
+ * @param options Optional reporting metadata used to derive the thrown validation message.
231
+ * @returns The optional direct child element whose type matches the provided element type, or `null` when no match is found.
232
+ */
233
+ declare function useOptionalChildByType<T extends ElementType>(children: ReactNode, type: T, options?: ValidationOptions): ElementOfType<T> | null;
234
+
235
+ /**
236
+ * Returns the optional direct child element that satisfies the provided predicate, or throws when more than one match is found.
237
+ *
238
+ * @param children The React children value to inspect.
239
+ * @param predicate A predicate that is called with each direct child element to determine whether it matches.
240
+ * @param options Optional reporting metadata used to derive the thrown validation message.
241
+ * @returns The optional direct child element that satisfies the provided predicate, or `null` when no match is found.
242
+ */
243
+ declare function useOptionalChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: ValidationOptions): T | null;
244
+ declare function useOptionalChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: ValidationOptions): ReactElement | null;
245
+
177
246
  /**
178
247
  * Returns the first direct child element whose React element type exactly matches the provided type, or throws when no match is found.
179
248
  *
@@ -184,6 +253,15 @@ declare function useMinimumChildrenMatching(children: ReactNode, predicate: (ele
184
253
  */
185
254
  declare function useRequiredChildByType<T extends ElementType>(children: ReactNode, type: T, options?: ValidationOptions): ElementOfType<T>;
186
255
 
256
+ /**
257
+ * Returns the first direct callback child from the provided children value, or throws when none is found.
258
+ *
259
+ * @param children The direct children value to inspect.
260
+ * @param options Optional reporting metadata used to derive the thrown validation message.
261
+ * @returns The first direct callback child from the provided children value.
262
+ */
263
+ declare function useRequiredCallbackChild<TArguments extends unknown[] = [], TResult = ReactNode>(children: CallbackChildren<TArguments, TResult>, options?: ValidationOptions): CallbackChild<TArguments, TResult>;
264
+
187
265
  /**
188
266
  * Returns the first direct child element that satisfies the provided predicate, or throws when no match is found.
189
267
  *
@@ -196,12 +274,34 @@ declare function useRequiredChildMatching<T extends ReactElement>(children: Reac
196
274
  declare function useRequiredChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: ValidationOptions): ReactElement;
197
275
 
198
276
  /**
199
- * Normalizes a React children value into an array containing only valid direct child elements.
277
+ * Returns the only direct child element whose React element type exactly matches the provided type, or throws when the match is not unique.
278
+ *
279
+ * @param children The React children value to inspect.
280
+ * @param type The element or component type to match against each direct child element.
281
+ * @param options Optional reporting metadata used to derive the thrown validation message.
282
+ * @returns The only direct child element whose type matches the provided element type.
283
+ */
284
+ declare function useUniqueChildByType<T extends ElementType>(children: ReactNode, type: T, options?: ValidationOptions): ElementOfType<T>;
285
+
286
+ /**
287
+ * Returns the only direct child element that satisfies the provided predicate, or throws when the match is not unique.
288
+ *
289
+ * @param children The React children value to inspect.
290
+ * @param predicate A predicate that is called with each direct child element to determine whether it matches.
291
+ * @param options Optional reporting metadata used to derive the thrown validation message.
292
+ * @returns The only direct child element that satisfies the provided predicate.
293
+ */
294
+ declare function useUniqueChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: ValidationOptions): T;
295
+ declare function useUniqueChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: ValidationOptions): ReactElement;
296
+
297
+ /**
298
+ * Normalizes a React children value into an array containing valid child elements within the configured depth range.
200
299
  *
201
300
  * @param children The React children value to normalize.
202
- * @returns An array of valid React elements from the provided direct children.
301
+ * @param options Optional traversal bounds that control which child depths are included.
302
+ * @returns An array of valid React elements from the provided child depths.
203
303
  */
204
- declare function childrenToElements(children: ReactNode): ReactElement[];
304
+ declare function childrenToElements(children: ReactNode, options?: TraversalOptions): ReactElement[];
205
305
 
206
306
  /**
207
307
  * Determines whether a React element exactly matches the provided element or component type.
@@ -220,4 +320,4 @@ declare function isElementOfType<T extends ElementType>(element: ReactElement, t
220
320
  */
221
321
  declare function isReactElement(node: ReactNode): node is ReactElement;
222
322
 
223
- export { type ChildrenCountBounds, type ElementOfType, type ValidationOptions, childrenToElements, isElementOfType, isReactElement, useBoundedChildrenByType, useBoundedChildrenMatching, useChildByType, useChildMatching, useChildrenByType, useChildrenMatching, useExactChildrenByType, useExactChildrenMatching, useHasChildMatching, useMaximumChildrenByType, useMaximumChildrenMatching, useMinimumChildrenByType, useMinimumChildrenMatching, useRequiredChildByType, useRequiredChildMatching };
323
+ export { type CallbackChild, type CallbackChildren, type ChildrenCountBounds, type ElementOfType, type QueryOptions, type TraversalOptions, type ValidationOptions, childrenToElements, isElementOfType, isReactElement, useBoundedChildrenByType, useBoundedChildrenMatching, useCallbackChild, useChildByType, useChildMatching, useChildrenByType, useChildrenMatching, useExactChildrenByType, useExactChildrenMatching, useHasChildMatching, useMaximumChildrenByType, useMaximumChildrenMatching, useMinimumChildrenByType, useMinimumChildrenMatching, useOptionalChildByType, useOptionalChildMatching, useRequiredCallbackChild, useRequiredChildByType, useRequiredChildMatching, useUniqueChildByType, useUniqueChildMatching };
package/dist/index.d.ts CHANGED
@@ -14,16 +14,47 @@ type ChildrenCountBounds = {
14
14
  */
15
15
  maximum: number;
16
16
  };
17
+ /**
18
+ * Optional traversal bounds used by the element-based query and validation hooks.
19
+ */
20
+ type TraversalOptions = {
21
+ /**
22
+ * The minimum inclusive child depth to include in results, where `0` represents direct children.
23
+ */
24
+ depth?: number;
25
+ /**
26
+ * The maximum inclusive child depth to include in results, where `0` represents direct children.
27
+ */
28
+ maximumDepth?: number;
29
+ };
30
+ /**
31
+ * Optional traversal metadata used by the element-based query hooks.
32
+ */
33
+ type QueryOptions = TraversalOptions;
17
34
  /**
18
35
  * Represents a React element whose props and element type are narrowed to the provided React element type.
19
36
  *
20
37
  * @typeParam T The React element type used to narrow the element's props and type.
21
38
  */
22
39
  type ElementOfType<T extends React.ElementType> = React.ReactElement<React.ComponentProps<T>, T>;
40
+ /**
41
+ * A callback child, also known as a render-prop child.
42
+ *
43
+ * @typeParam TArguments The positional argument tuple accepted by the callback.
44
+ * @typeParam TResult The value returned by the callback.
45
+ */
46
+ type CallbackChild<TArguments extends unknown[] = [], TResult = React.ReactNode> = (...args: TArguments) => TResult;
47
+ /**
48
+ * A direct-children value that may include callback children alongside regular React children.
49
+ *
50
+ * @typeParam TArguments The positional argument tuple accepted by callback children.
51
+ * @typeParam TResult The value returned by callback children.
52
+ */
53
+ type CallbackChildren<TArguments extends unknown[] = [], TResult = React.ReactNode> = React.ReactNode | CallbackChild<TArguments, TResult> | readonly CallbackChildren<TArguments, TResult>[];
23
54
  /**
24
55
  * Optional reporting metadata used by the validation hooks to derive thrown validation messages.
25
56
  */
26
- type ValidationOptions = {
57
+ type ValidationMessageOptions = {
27
58
  /**
28
59
  * An optional consumer-defined trace code that is prefixed to the thrown validation message.
29
60
  */
@@ -33,25 +64,39 @@ type ValidationOptions = {
33
64
  */
34
65
  childName?: string;
35
66
  };
67
+ /**
68
+ * Optional reporting and traversal metadata used by the validation hooks.
69
+ */
70
+ type ValidationOptions = ValidationMessageOptions & TraversalOptions;
36
71
 
37
72
  /**
38
73
  * Returns the first direct child element whose React element type exactly matches the provided type.
39
74
  *
40
75
  * @param children The React children value to inspect.
41
76
  * @param type The element or component type to match against each direct child element.
77
+ * @param options Optional query metadata used to configure how child elements are inspected.
42
78
  * @returns The first direct child element whose type matches the provided element type, or `null` when no match is found.
43
79
  */
44
- declare function useChildByType<T extends ElementType>(children: ReactNode, type: T): ElementOfType<T> | null;
80
+ declare function useChildByType<T extends ElementType>(children: ReactNode, type: T, options?: QueryOptions): ElementOfType<T> | null;
81
+
82
+ /**
83
+ * Returns the first direct callback child from the provided children value.
84
+ *
85
+ * @param children The direct children value to inspect.
86
+ * @returns The first direct callback child, or `null` when no callback child is found.
87
+ */
88
+ declare function useCallbackChild<TArguments extends unknown[] = [], TResult = ReactNode>(children: CallbackChildren<TArguments, TResult>): CallbackChild<TArguments, TResult> | null;
45
89
 
46
90
  /**
47
91
  * Returns the first direct child element that satisfies the provided predicate.
48
92
  *
49
93
  * @param children The React children value to inspect.
50
94
  * @param predicate A predicate that is called with each direct child element to determine whether it matches.
95
+ * @param options Optional query metadata used to configure how child elements are inspected.
51
96
  * @returns The first direct child element that satisfies the provided predicate, or `null` when no match is found.
52
97
  */
53
- declare function useChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): T | null;
54
- declare function useChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean): ReactElement | null;
98
+ declare function useChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: QueryOptions): T | null;
99
+ declare function useChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: QueryOptions): ReactElement | null;
55
100
 
56
101
  /**
57
102
  * Returns the direct child elements whose React element type exactly matches the provided type, or throws when the count falls outside the inclusive bounds.
@@ -81,19 +126,21 @@ declare function useBoundedChildrenMatching(children: ReactNode, predicate: (ele
81
126
  *
82
127
  * @param children The React children value to inspect.
83
128
  * @param type The element or component type to match against each direct child element.
129
+ * @param options Optional query metadata used to configure how child elements are inspected.
84
130
  * @returns An array of direct child elements whose type matches the provided element type.
85
131
  */
86
- declare function useChildrenByType<T extends ElementType>(children: ReactNode, type: T): ElementOfType<T>[];
132
+ declare function useChildrenByType<T extends ElementType>(children: ReactNode, type: T, options?: QueryOptions): ElementOfType<T>[];
87
133
 
88
134
  /**
89
135
  * Returns the direct child elements that satisfy the provided predicate.
90
136
  *
91
137
  * @param children The React children value to inspect.
92
138
  * @param predicate A predicate that is called with each direct child element to determine whether it should be included in the result.
139
+ * @param options Optional query metadata used to configure how child elements are inspected.
93
140
  * @returns An array of direct child elements that satisfy the provided predicate.
94
141
  */
95
- declare function useChildrenMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): T[];
96
- declare function useChildrenMatching(children: ReactNode, predicate: (element: ReactElement) => boolean): ReactElement[];
142
+ declare function useChildrenMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: QueryOptions): T[];
143
+ declare function useChildrenMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: QueryOptions): ReactElement[];
97
144
 
98
145
  /**
99
146
  * Returns the direct child elements whose React element type exactly matches the provided type, or throws when the exact count is not met.
@@ -123,10 +170,11 @@ declare function useExactChildrenMatching(children: ReactNode, predicate: (eleme
123
170
  *
124
171
  * @param children The React children value to inspect.
125
172
  * @param predicate A predicate that is called with each direct child element to determine whether it matches.
173
+ * @param options Optional query metadata used to configure how child elements are inspected.
126
174
  * @returns `true` when at least one direct child element satisfies the provided predicate; otherwise `false`.
127
175
  */
128
- declare function useHasChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): boolean;
129
- declare function useHasChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean): boolean;
176
+ declare function useHasChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: QueryOptions): boolean;
177
+ declare function useHasChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: QueryOptions): boolean;
130
178
 
131
179
  /**
132
180
  * Returns the direct child elements whose React element type exactly matches the provided type, or throws when more than the maximum count are found.
@@ -174,6 +222,27 @@ declare function useMinimumChildrenByType<T extends ElementType>(children: React
174
222
  declare function useMinimumChildrenMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, minimumCount: number, options?: ValidationOptions): T[];
175
223
  declare function useMinimumChildrenMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, minimumCount: number, options?: ValidationOptions): ReactElement[];
176
224
 
225
+ /**
226
+ * Returns the optional direct child element whose React element type exactly matches the provided type, or throws when more than one match is found.
227
+ *
228
+ * @param children The React children value to inspect.
229
+ * @param type The element or component type to match against each direct child element.
230
+ * @param options Optional reporting metadata used to derive the thrown validation message.
231
+ * @returns The optional direct child element whose type matches the provided element type, or `null` when no match is found.
232
+ */
233
+ declare function useOptionalChildByType<T extends ElementType>(children: ReactNode, type: T, options?: ValidationOptions): ElementOfType<T> | null;
234
+
235
+ /**
236
+ * Returns the optional direct child element that satisfies the provided predicate, or throws when more than one match is found.
237
+ *
238
+ * @param children The React children value to inspect.
239
+ * @param predicate A predicate that is called with each direct child element to determine whether it matches.
240
+ * @param options Optional reporting metadata used to derive the thrown validation message.
241
+ * @returns The optional direct child element that satisfies the provided predicate, or `null` when no match is found.
242
+ */
243
+ declare function useOptionalChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: ValidationOptions): T | null;
244
+ declare function useOptionalChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: ValidationOptions): ReactElement | null;
245
+
177
246
  /**
178
247
  * Returns the first direct child element whose React element type exactly matches the provided type, or throws when no match is found.
179
248
  *
@@ -184,6 +253,15 @@ declare function useMinimumChildrenMatching(children: ReactNode, predicate: (ele
184
253
  */
185
254
  declare function useRequiredChildByType<T extends ElementType>(children: ReactNode, type: T, options?: ValidationOptions): ElementOfType<T>;
186
255
 
256
+ /**
257
+ * Returns the first direct callback child from the provided children value, or throws when none is found.
258
+ *
259
+ * @param children The direct children value to inspect.
260
+ * @param options Optional reporting metadata used to derive the thrown validation message.
261
+ * @returns The first direct callback child from the provided children value.
262
+ */
263
+ declare function useRequiredCallbackChild<TArguments extends unknown[] = [], TResult = ReactNode>(children: CallbackChildren<TArguments, TResult>, options?: ValidationOptions): CallbackChild<TArguments, TResult>;
264
+
187
265
  /**
188
266
  * Returns the first direct child element that satisfies the provided predicate, or throws when no match is found.
189
267
  *
@@ -196,12 +274,34 @@ declare function useRequiredChildMatching<T extends ReactElement>(children: Reac
196
274
  declare function useRequiredChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: ValidationOptions): ReactElement;
197
275
 
198
276
  /**
199
- * Normalizes a React children value into an array containing only valid direct child elements.
277
+ * Returns the only direct child element whose React element type exactly matches the provided type, or throws when the match is not unique.
278
+ *
279
+ * @param children The React children value to inspect.
280
+ * @param type The element or component type to match against each direct child element.
281
+ * @param options Optional reporting metadata used to derive the thrown validation message.
282
+ * @returns The only direct child element whose type matches the provided element type.
283
+ */
284
+ declare function useUniqueChildByType<T extends ElementType>(children: ReactNode, type: T, options?: ValidationOptions): ElementOfType<T>;
285
+
286
+ /**
287
+ * Returns the only direct child element that satisfies the provided predicate, or throws when the match is not unique.
288
+ *
289
+ * @param children The React children value to inspect.
290
+ * @param predicate A predicate that is called with each direct child element to determine whether it matches.
291
+ * @param options Optional reporting metadata used to derive the thrown validation message.
292
+ * @returns The only direct child element that satisfies the provided predicate.
293
+ */
294
+ declare function useUniqueChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: ValidationOptions): T;
295
+ declare function useUniqueChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: ValidationOptions): ReactElement;
296
+
297
+ /**
298
+ * Normalizes a React children value into an array containing valid child elements within the configured depth range.
200
299
  *
201
300
  * @param children The React children value to normalize.
202
- * @returns An array of valid React elements from the provided direct children.
301
+ * @param options Optional traversal bounds that control which child depths are included.
302
+ * @returns An array of valid React elements from the provided child depths.
203
303
  */
204
- declare function childrenToElements(children: ReactNode): ReactElement[];
304
+ declare function childrenToElements(children: ReactNode, options?: TraversalOptions): ReactElement[];
205
305
 
206
306
  /**
207
307
  * Determines whether a React element exactly matches the provided element or component type.
@@ -220,4 +320,4 @@ declare function isElementOfType<T extends ElementType>(element: ReactElement, t
220
320
  */
221
321
  declare function isReactElement(node: ReactNode): node is ReactElement;
222
322
 
223
- export { type ChildrenCountBounds, type ElementOfType, type ValidationOptions, childrenToElements, isElementOfType, isReactElement, useBoundedChildrenByType, useBoundedChildrenMatching, useChildByType, useChildMatching, useChildrenByType, useChildrenMatching, useExactChildrenByType, useExactChildrenMatching, useHasChildMatching, useMaximumChildrenByType, useMaximumChildrenMatching, useMinimumChildrenByType, useMinimumChildrenMatching, useRequiredChildByType, useRequiredChildMatching };
323
+ export { type CallbackChild, type CallbackChildren, type ChildrenCountBounds, type ElementOfType, type QueryOptions, type TraversalOptions, type ValidationOptions, childrenToElements, isElementOfType, isReactElement, useBoundedChildrenByType, useBoundedChildrenMatching, useCallbackChild, useChildByType, useChildMatching, useChildrenByType, useChildrenMatching, useExactChildrenByType, useExactChildrenMatching, useHasChildMatching, useMaximumChildrenByType, useMaximumChildrenMatching, useMinimumChildrenByType, useMinimumChildrenMatching, useOptionalChildByType, useOptionalChildMatching, useRequiredCallbackChild, useRequiredChildByType, useRequiredChildMatching, useUniqueChildByType, useUniqueChildMatching };