react-children-hooks 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -1,12 +1,38 @@
 import * as React from 'react';
 import { ElementType, ReactNode, ReactElement } from 'react';
 
+/**
+ * Inclusive minimum and maximum bounds used by the bounded validation hooks.
+ */
+type ChildrenCountBounds = {
+    /**
+     * The minimum number of matching direct child elements required.
+     */
+    minimum: number;
+    /**
+     * The maximum number of matching direct child elements allowed.
+     */
+    maximum: number;
+};
 /**
  * Represents a React element whose props and element type are narrowed to the provided React element type.
  *
  * @typeParam T The React element type used to narrow the element's props and type.
  */
 type ElementOfType<T extends React.ElementType> = React.ReactElement<React.ComponentProps<T>, T>;
+/**
+ * Optional reporting metadata used by the validation hooks to derive thrown validation messages.
+ */
+type ValidationOptions = {
+    /**
+     * An optional consumer-defined trace code that is prefixed to the thrown validation message.
+     */
+    traceCode?: string;
+    /**
+     * An optional human-readable child name that is included in the thrown validation message.
+     */
+    childName?: string;
+};
 
 /**
  * Returns the first direct child element whose React element type exactly matches the provided type.
@@ -24,8 +50,31 @@ declare function useChildByType<T extends ElementType>(children: ReactNode, type
  * @param predicate A predicate that is called with each direct child element to determine whether it matches.
  * @returns The first direct child element that satisfies the provided predicate, or `null` when no match is found.
  */
-declare function useChildWhere<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): T | null;
-declare function useChildWhere(children: ReactNode, predicate: (element: ReactElement) => boolean): ReactElement | null;
+declare function useChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): T | null;
+declare function useChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean): ReactElement | null;
+
+/**
+ * Returns the direct child elements whose React element type exactly matches the provided type, or throws when the count falls outside the inclusive bounds.
+ *
+ * @param children The React children value to inspect.
+ * @param type The element or component type to match against each direct child element.
+ * @param bounds The inclusive minimum and maximum number of matching direct child elements allowed.
+ * @param options Optional reporting metadata used to derive the thrown validation message.
+ * @returns The direct child elements whose type matches the provided element type.
+ */
+declare function useBoundedChildrenByType<T extends ElementType>(children: ReactNode, type: T, bounds: ChildrenCountBounds, options?: ValidationOptions): ElementOfType<T>[];
+
+/**
+ * Returns the direct child elements that satisfy the provided predicate, or throws when the count falls outside the inclusive bounds.
+ *
+ * @param children The React children value to inspect.
+ * @param predicate A predicate that is called with each direct child element to determine whether it matches.
+ * @param bounds The inclusive minimum and maximum number of matching direct child elements allowed.
+ * @param options Optional reporting metadata used to derive the thrown validation message.
+ * @returns The direct child elements that satisfy the provided predicate.
+ */
+declare function useBoundedChildrenMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, bounds: ChildrenCountBounds, options?: ValidationOptions): T[];
+declare function useBoundedChildrenMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, bounds: ChildrenCountBounds, options?: ValidationOptions): ReactElement[];
 
 /**
  * Returns the direct child elements whose React element type exactly matches the provided type.
@@ -43,19 +92,20 @@ declare function useChildrenByType<T extends ElementType>(children: ReactNode, t
  * @param predicate A predicate that is called with each direct child element to determine whether it should be included in the result.
  * @returns An array of direct child elements that satisfy the provided predicate.
  */
-declare function useChildrenWhere<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): T[];
-declare function useChildrenWhere(children: ReactNode, predicate: (element: ReactElement) => boolean): ReactElement[];
+declare function useChildrenMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): T[];
+declare function useChildrenMatching(children: ReactNode, predicate: (element: ReactElement) => boolean): ReactElement[];
+
+/**
+ * Returns the direct child elements whose React element type exactly matches the provided type, or throws when the exact count is not met.
+ *
+ * @param children The React children value to inspect.
+ * @param type The element or component type to match against each direct child element.
+ * @param exactCount The exact number of matching direct child elements required.
+ * @param options Optional reporting metadata used to derive the thrown validation message.
+ * @returns The direct child elements whose type matches the provided element type.
+ */
+declare function useExactChildrenByType<T extends ElementType>(children: ReactNode, type: T, exactCount: number, options?: ValidationOptions): ElementOfType<T>[];
 
-type UseExactChildrenWhereOptions = {
-    /**
-     * An optional consumer-defined trace code that is prefixed to the thrown validation message.
-     */
-    traceCode?: string;
-    /**
-     * An optional human-readable child name that is included in the thrown validation message.
-     */
-    childName?: string;
-};
 /**
  * Returns the direct child elements that satisfy the provided predicate, or throws when the exact count is not met.
  *
@@ -65,8 +115,8 @@ type UseExactChildrenWhereOptions = {
  * @param options Optional reporting metadata used to derive the thrown validation message.
  * @returns The direct child elements that satisfy the provided predicate.
  */
-declare function useExactChildrenWhere<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, exactCount: number, options?: UseExactChildrenWhereOptions): T[];
-declare function useExactChildrenWhere(children: ReactNode, predicate: (element: ReactElement) => boolean, exactCount: number, options?: UseExactChildrenWhereOptions): ReactElement[];
+declare function useExactChildrenMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, exactCount: number, options?: ValidationOptions): T[];
+declare function useExactChildrenMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, exactCount: number, options?: ValidationOptions): ReactElement[];
 
 /**
  * Determines whether any direct child element satisfies the provided predicate.
@@ -75,19 +125,20 @@ declare function useExactChildrenWhere(children: ReactNode, predicate: (element:
  * @param predicate A predicate that is called with each direct child element to determine whether it matches.
  * @returns `true` when at least one direct child element satisfies the provided predicate; otherwise `false`.
  */
-declare function useHasChildWhere<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): boolean;
-declare function useHasChildWhere(children: ReactNode, predicate: (element: ReactElement) => boolean): boolean;
+declare function useHasChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): boolean;
+declare function useHasChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean): boolean;
+
+/**
+ * Returns the direct child elements whose React element type exactly matches the provided type, or throws when more than the maximum count are found.
+ *
+ * @param children The React children value to inspect.
+ * @param type The element or component type to match against each direct child element.
+ * @param maximumCount The maximum number of matching direct child elements allowed.
+ * @param options Optional reporting metadata used to derive the thrown validation message.
+ * @returns The direct child elements whose type matches the provided element type.
+ */
+declare function useMaximumChildrenByType<T extends ElementType>(children: ReactNode, type: T, maximumCount: number, options?: ValidationOptions): ElementOfType<T>[];
 
-type UseMaximumChildrenWhereOptions = {
-    /**
-     * An optional consumer-defined trace code that is prefixed to the thrown validation message.
-     */
-    traceCode?: string;
-    /**
-     * An optional human-readable child name that is included in the thrown validation message.
-     */
-    childName?: string;
-};
 /**
  * Returns the direct child elements that satisfy the provided predicate, or throws when more than the maximum count are found.
  *
@@ -97,19 +148,20 @@ type UseMaximumChildrenWhereOptions = {
  * @param options Optional reporting metadata used to derive the thrown validation message.
  * @returns The direct child elements that satisfy the provided predicate.
  */
-declare function useMaximumChildrenWhere<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, maximumCount: number, options?: UseMaximumChildrenWhereOptions): T[];
-declare function useMaximumChildrenWhere(children: ReactNode, predicate: (element: ReactElement) => boolean, maximumCount: number, options?: UseMaximumChildrenWhereOptions): ReactElement[];
+declare function useMaximumChildrenMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, maximumCount: number, options?: ValidationOptions): T[];
+declare function useMaximumChildrenMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, maximumCount: number, options?: ValidationOptions): ReactElement[];
+
+/**
+ * Returns the direct child elements whose React element type exactly matches the provided type, or throws when fewer than the minimum count are found.
+ *
+ * @param children The React children value to inspect.
+ * @param type The element or component type to match against each direct child element.
+ * @param minimumCount The minimum number of matching direct child elements required.
+ * @param options Optional reporting metadata used to derive the thrown validation message.
+ * @returns The direct child elements whose type matches the provided element type.
+ */
+declare function useMinimumChildrenByType<T extends ElementType>(children: ReactNode, type: T, minimumCount: number, options?: ValidationOptions): ElementOfType<T>[];
 
-type UseMinimumChildrenWhereOptions = {
-    /**
-     * An optional consumer-defined trace code that is prefixed to the thrown validation message.
-     */
-    traceCode?: string;
-    /**
-     * An optional human-readable child name that is included in the thrown validation message.
-     */
-    childName?: string;
-};
 /**
  * Returns the direct child elements that satisfy the provided predicate, or throws when fewer than the minimum count are found.
  *
@@ -119,19 +171,19 @@ type UseMinimumChildrenWhereOptions = {
  * @param options Optional reporting metadata used to derive the thrown validation message.
  * @returns The direct child elements that satisfy the provided predicate.
  */
-declare function useMinimumChildrenWhere<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, minimumCount: number, options?: UseMinimumChildrenWhereOptions): T[];
-declare function useMinimumChildrenWhere(children: ReactNode, predicate: (element: ReactElement) => boolean, minimumCount: number, options?: UseMinimumChildrenWhereOptions): ReactElement[];
+declare function useMinimumChildrenMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, minimumCount: number, options?: ValidationOptions): T[];
+declare function useMinimumChildrenMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, minimumCount: number, options?: ValidationOptions): ReactElement[];
+
+/**
+ * Returns the first direct child element whose React element type exactly matches the provided type, or throws when no match is found.
+ *
+ * @param children The React children value to inspect.
+ * @param type The element or component type to match against each direct child element.
+ * @param options Optional reporting metadata used to derive the thrown validation message.
+ * @returns The first direct child element whose type matches the provided element type.
+ */
+declare function useRequiredChildByType<T extends ElementType>(children: ReactNode, type: T, options?: ValidationOptions): ElementOfType<T>;
 
-type UseRequiredChildWhereOptions = {
-    /**
-     * An optional consumer-defined trace code that is prefixed to the thrown validation message.
-     */
-    traceCode?: string;
-    /**
-     * An optional human-readable child name that is included in the thrown validation message.
-     */
-    childName?: string;
-};
 /**
  * Returns the first direct child element that satisfies the provided predicate, or throws when no match is found.
  *
@@ -140,8 +192,8 @@ type UseRequiredChildWhereOptions = {
  * @param options Optional reporting metadata used to derive the thrown validation message.
  * @returns The first direct child element that satisfies the provided predicate.
  */
-declare function useRequiredChildWhere<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: UseRequiredChildWhereOptions): T;
-declare function useRequiredChildWhere(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: UseRequiredChildWhereOptions): ReactElement;
+declare function useRequiredChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: ValidationOptions): T;
+declare function useRequiredChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: ValidationOptions): ReactElement;
 
 /**
  * Normalizes a React children value into an array containing only valid direct child elements.
@@ -168,4 +220,4 @@ declare function isElementOfType<T extends ElementType>(element: ReactElement, t
  */
 declare function isReactElement(node: ReactNode): node is ReactElement;
 
-export { type ElementOfType, type UseExactChildrenWhereOptions, type UseMaximumChildrenWhereOptions, type UseMinimumChildrenWhereOptions, type UseRequiredChildWhereOptions, childrenToElements, isElementOfType, isReactElement, useChildByType, useChildWhere, useChildrenByType, useChildrenWhere, useExactChildrenWhere, useHasChildWhere, useMaximumChildrenWhere, useMinimumChildrenWhere, useRequiredChildWhere };
+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 };

package/dist/index.d.ts

@@ -1,12 +1,38 @@
 import * as React from 'react';
 import { ElementType, ReactNode, ReactElement } from 'react';
 
+/**
+ * Inclusive minimum and maximum bounds used by the bounded validation hooks.
+ */
+type ChildrenCountBounds = {
+    /**
+     * The minimum number of matching direct child elements required.
+     */
+    minimum: number;
+    /**
+     * The maximum number of matching direct child elements allowed.
+     */
+    maximum: number;
+};
 /**
  * Represents a React element whose props and element type are narrowed to the provided React element type.
  *
  * @typeParam T The React element type used to narrow the element's props and type.
  */
 type ElementOfType<T extends React.ElementType> = React.ReactElement<React.ComponentProps<T>, T>;
+/**
+ * Optional reporting metadata used by the validation hooks to derive thrown validation messages.
+ */
+type ValidationOptions = {
+    /**
+     * An optional consumer-defined trace code that is prefixed to the thrown validation message.
+     */
+    traceCode?: string;
+    /**
+     * An optional human-readable child name that is included in the thrown validation message.
+     */
+    childName?: string;
+};
 
 /**
  * Returns the first direct child element whose React element type exactly matches the provided type.
@@ -24,8 +50,31 @@ declare function useChildByType<T extends ElementType>(children: ReactNode, type
  * @param predicate A predicate that is called with each direct child element to determine whether it matches.
  * @returns The first direct child element that satisfies the provided predicate, or `null` when no match is found.
  */
-declare function useChildWhere<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): T | null;
-declare function useChildWhere(children: ReactNode, predicate: (element: ReactElement) => boolean): ReactElement | null;
+declare function useChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): T | null;
+declare function useChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean): ReactElement | null;
+
+/**
+ * Returns the direct child elements whose React element type exactly matches the provided type, or throws when the count falls outside the inclusive bounds.
+ *
+ * @param children The React children value to inspect.
+ * @param type The element or component type to match against each direct child element.
+ * @param bounds The inclusive minimum and maximum number of matching direct child elements allowed.
+ * @param options Optional reporting metadata used to derive the thrown validation message.
+ * @returns The direct child elements whose type matches the provided element type.
+ */
+declare function useBoundedChildrenByType<T extends ElementType>(children: ReactNode, type: T, bounds: ChildrenCountBounds, options?: ValidationOptions): ElementOfType<T>[];
+
+/**
+ * Returns the direct child elements that satisfy the provided predicate, or throws when the count falls outside the inclusive bounds.
+ *
+ * @param children The React children value to inspect.
+ * @param predicate A predicate that is called with each direct child element to determine whether it matches.
+ * @param bounds The inclusive minimum and maximum number of matching direct child elements allowed.
+ * @param options Optional reporting metadata used to derive the thrown validation message.
+ * @returns The direct child elements that satisfy the provided predicate.
+ */
+declare function useBoundedChildrenMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, bounds: ChildrenCountBounds, options?: ValidationOptions): T[];
+declare function useBoundedChildrenMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, bounds: ChildrenCountBounds, options?: ValidationOptions): ReactElement[];
 
 /**
  * Returns the direct child elements whose React element type exactly matches the provided type.
@@ -43,19 +92,20 @@ declare function useChildrenByType<T extends ElementType>(children: ReactNode, t
  * @param predicate A predicate that is called with each direct child element to determine whether it should be included in the result.
  * @returns An array of direct child elements that satisfy the provided predicate.
  */
-declare function useChildrenWhere<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): T[];
-declare function useChildrenWhere(children: ReactNode, predicate: (element: ReactElement) => boolean): ReactElement[];
+declare function useChildrenMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): T[];
+declare function useChildrenMatching(children: ReactNode, predicate: (element: ReactElement) => boolean): ReactElement[];
+
+/**
+ * Returns the direct child elements whose React element type exactly matches the provided type, or throws when the exact count is not met.
+ *
+ * @param children The React children value to inspect.
+ * @param type The element or component type to match against each direct child element.
+ * @param exactCount The exact number of matching direct child elements required.
+ * @param options Optional reporting metadata used to derive the thrown validation message.
+ * @returns The direct child elements whose type matches the provided element type.
+ */
+declare function useExactChildrenByType<T extends ElementType>(children: ReactNode, type: T, exactCount: number, options?: ValidationOptions): ElementOfType<T>[];
 
-type UseExactChildrenWhereOptions = {
-    /**
-     * An optional consumer-defined trace code that is prefixed to the thrown validation message.
-     */
-    traceCode?: string;
-    /**
-     * An optional human-readable child name that is included in the thrown validation message.
-     */
-    childName?: string;
-};
 /**
  * Returns the direct child elements that satisfy the provided predicate, or throws when the exact count is not met.
  *
@@ -65,8 +115,8 @@ type UseExactChildrenWhereOptions = {
  * @param options Optional reporting metadata used to derive the thrown validation message.
  * @returns The direct child elements that satisfy the provided predicate.
  */
-declare function useExactChildrenWhere<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, exactCount: number, options?: UseExactChildrenWhereOptions): T[];
-declare function useExactChildrenWhere(children: ReactNode, predicate: (element: ReactElement) => boolean, exactCount: number, options?: UseExactChildrenWhereOptions): ReactElement[];
+declare function useExactChildrenMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, exactCount: number, options?: ValidationOptions): T[];
+declare function useExactChildrenMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, exactCount: number, options?: ValidationOptions): ReactElement[];
 
 /**
  * Determines whether any direct child element satisfies the provided predicate.
@@ -75,19 +125,20 @@ declare function useExactChildrenWhere(children: ReactNode, predicate: (element:
  * @param predicate A predicate that is called with each direct child element to determine whether it matches.
  * @returns `true` when at least one direct child element satisfies the provided predicate; otherwise `false`.
  */
-declare function useHasChildWhere<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): boolean;
-declare function useHasChildWhere(children: ReactNode, predicate: (element: ReactElement) => boolean): boolean;
+declare function useHasChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): boolean;
+declare function useHasChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean): boolean;
+
+/**
+ * Returns the direct child elements whose React element type exactly matches the provided type, or throws when more than the maximum count are found.
+ *
+ * @param children The React children value to inspect.
+ * @param type The element or component type to match against each direct child element.
+ * @param maximumCount The maximum number of matching direct child elements allowed.
+ * @param options Optional reporting metadata used to derive the thrown validation message.
+ * @returns The direct child elements whose type matches the provided element type.
+ */
+declare function useMaximumChildrenByType<T extends ElementType>(children: ReactNode, type: T, maximumCount: number, options?: ValidationOptions): ElementOfType<T>[];
 
-type UseMaximumChildrenWhereOptions = {
-    /**
-     * An optional consumer-defined trace code that is prefixed to the thrown validation message.
-     */
-    traceCode?: string;
-    /**
-     * An optional human-readable child name that is included in the thrown validation message.
-     */
-    childName?: string;
-};
 /**
  * Returns the direct child elements that satisfy the provided predicate, or throws when more than the maximum count are found.
  *
@@ -97,19 +148,20 @@ type UseMaximumChildrenWhereOptions = {
  * @param options Optional reporting metadata used to derive the thrown validation message.
  * @returns The direct child elements that satisfy the provided predicate.
  */
-declare function useMaximumChildrenWhere<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, maximumCount: number, options?: UseMaximumChildrenWhereOptions): T[];
-declare function useMaximumChildrenWhere(children: ReactNode, predicate: (element: ReactElement) => boolean, maximumCount: number, options?: UseMaximumChildrenWhereOptions): ReactElement[];
+declare function useMaximumChildrenMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, maximumCount: number, options?: ValidationOptions): T[];
+declare function useMaximumChildrenMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, maximumCount: number, options?: ValidationOptions): ReactElement[];
+
+/**
+ * Returns the direct child elements whose React element type exactly matches the provided type, or throws when fewer than the minimum count are found.
+ *
+ * @param children The React children value to inspect.
+ * @param type The element or component type to match against each direct child element.
+ * @param minimumCount The minimum number of matching direct child elements required.
+ * @param options Optional reporting metadata used to derive the thrown validation message.
+ * @returns The direct child elements whose type matches the provided element type.
+ */
+declare function useMinimumChildrenByType<T extends ElementType>(children: ReactNode, type: T, minimumCount: number, options?: ValidationOptions): ElementOfType<T>[];
 
-type UseMinimumChildrenWhereOptions = {
-    /**
-     * An optional consumer-defined trace code that is prefixed to the thrown validation message.
-     */
-    traceCode?: string;
-    /**
-     * An optional human-readable child name that is included in the thrown validation message.
-     */
-    childName?: string;
-};
 /**
  * Returns the direct child elements that satisfy the provided predicate, or throws when fewer than the minimum count are found.
  *
@@ -119,19 +171,19 @@ type UseMinimumChildrenWhereOptions = {
  * @param options Optional reporting metadata used to derive the thrown validation message.
  * @returns The direct child elements that satisfy the provided predicate.
  */
-declare function useMinimumChildrenWhere<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, minimumCount: number, options?: UseMinimumChildrenWhereOptions): T[];
-declare function useMinimumChildrenWhere(children: ReactNode, predicate: (element: ReactElement) => boolean, minimumCount: number, options?: UseMinimumChildrenWhereOptions): ReactElement[];
+declare function useMinimumChildrenMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, minimumCount: number, options?: ValidationOptions): T[];
+declare function useMinimumChildrenMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, minimumCount: number, options?: ValidationOptions): ReactElement[];
+
+/**
+ * Returns the first direct child element whose React element type exactly matches the provided type, or throws when no match is found.
+ *
+ * @param children The React children value to inspect.
+ * @param type The element or component type to match against each direct child element.
+ * @param options Optional reporting metadata used to derive the thrown validation message.
+ * @returns The first direct child element whose type matches the provided element type.
+ */
+declare function useRequiredChildByType<T extends ElementType>(children: ReactNode, type: T, options?: ValidationOptions): ElementOfType<T>;
 
-type UseRequiredChildWhereOptions = {
-    /**
-     * An optional consumer-defined trace code that is prefixed to the thrown validation message.
-     */
-    traceCode?: string;
-    /**
-     * An optional human-readable child name that is included in the thrown validation message.
-     */
-    childName?: string;
-};
 /**
  * Returns the first direct child element that satisfies the provided predicate, or throws when no match is found.
  *
@@ -140,8 +192,8 @@ type UseRequiredChildWhereOptions = {
  * @param options Optional reporting metadata used to derive the thrown validation message.
  * @returns The first direct child element that satisfies the provided predicate.
  */
-declare function useRequiredChildWhere<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: UseRequiredChildWhereOptions): T;
-declare function useRequiredChildWhere(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: UseRequiredChildWhereOptions): ReactElement;
+declare function useRequiredChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: ValidationOptions): T;
+declare function useRequiredChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: ValidationOptions): ReactElement;
 
 /**
  * Normalizes a React children value into an array containing only valid direct child elements.
@@ -168,4 +220,4 @@ declare function isElementOfType<T extends ElementType>(element: ReactElement, t
  */
 declare function isReactElement(node: ReactNode): node is ReactElement;
 
-export { type ElementOfType, type UseExactChildrenWhereOptions, type UseMaximumChildrenWhereOptions, type UseMinimumChildrenWhereOptions, type UseRequiredChildWhereOptions, childrenToElements, isElementOfType, isReactElement, useChildByType, useChildWhere, useChildrenByType, useChildrenWhere, useExactChildrenWhere, useHasChildWhere, useMaximumChildrenWhere, useMinimumChildrenWhere, useRequiredChildWhere };
+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 };