react-children-hooks 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,61 +1,158 @@
 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;
+};
+/**
+ * Optional traversal bounds used by the element-based query and validation hooks.
+ */
+type TraversalOptions = {
+    /**
+     * The minimum inclusive child depth to include in results, where `0` represents direct children.
+     */
+    depth?: number;
+    /**
+     * The maximum inclusive child depth to include in results, where `0` represents direct children.
+     */
+    maximumDepth?: number;
+};
+/**
+ * Optional traversal metadata used by the element-based query hooks.
+ */
+type QueryOptions = TraversalOptions;
 /**
  * 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>;
+/**
+ * A callback child, also known as a render-prop child.
+ *
+ * @typeParam TArguments The positional argument tuple accepted by the callback.
+ * @typeParam TResult The value returned by the callback.
+ */
+type CallbackChild<TArguments extends unknown[] = [], TResult = React.ReactNode> = (...args: TArguments) => TResult;
+/**
+ * A direct-children value that may include callback children alongside regular React children.
+ *
+ * @typeParam TArguments The positional argument tuple accepted by callback children.
+ * @typeParam TResult The value returned by callback children.
+ */
+type CallbackChildren<TArguments extends unknown[] = [], TResult = React.ReactNode> = React.ReactNode | CallbackChild<TArguments, TResult> | readonly CallbackChildren<TArguments, TResult>[];
+/**
+ * Optional reporting metadata used by the validation hooks to derive thrown validation messages.
+ */
+type ValidationMessageOptions = {
+    /**
+     * 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;
+};
+/**
+ * Optional reporting and traversal metadata used by the validation hooks.
+ */
+type ValidationOptions = ValidationMessageOptions & TraversalOptions;
 
 /**
  * Returns the first direct child element whose React element type exactly matches the provided type.
  *
  * @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 query metadata used to configure how child elements are inspected.
  * @returns The first direct child element whose type matches the provided element type, or `null` when no match is found.
  */
-declare function useChildByType<T extends ElementType>(children: ReactNode, type: T): ElementOfType<T> | null;
+declare function useChildByType<T extends ElementType>(children: ReactNode, type: T, options?: QueryOptions): ElementOfType<T> | null;
+
+/**
+ * Returns the first direct callback child from the provided children value.
+ *
+ * @param children The direct children value to inspect.
+ * @returns The first direct callback child, or `null` when no callback child is found.
+ */
+declare function useCallbackChild<TArguments extends unknown[] = [], TResult = ReactNode>(children: CallbackChildren<TArguments, TResult>): CallbackChild<TArguments, TResult> | null;
 
 /**
  * Returns the first direct child element that satisfies the provided predicate.
  *
  * @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 options Optional query metadata used to configure how child elements are inspected.
  * @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, options?: QueryOptions): T | null;
+declare function useChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: QueryOptions): 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.
  *
  * @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 query metadata used to configure how child elements are inspected.
  * @returns An array of direct child elements whose type matches the provided element type.
  */
-declare function useChildrenByType<T extends ElementType>(children: ReactNode, type: T): ElementOfType<T>[];
+declare function useChildrenByType<T extends ElementType>(children: ReactNode, type: T, options?: QueryOptions): ElementOfType<T>[];
 
 /**
  * Returns the direct child elements that satisfy the provided predicate.
  *
  * @param children The React children value to inspect.
  * @param predicate A predicate that is called with each direct child element to determine whether it should be included in the result.
+ * @param options Optional query metadata used to configure how child elements are inspected.
  * @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, options?: QueryOptions): T[];
+declare function useChildrenMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: QueryOptions): 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,29 +162,31 @@ 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.
  *
  * @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 options Optional query metadata used to configure how child elements are inspected.
  * @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, options?: QueryOptions): boolean;
+declare function useHasChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: QueryOptions): 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 +196,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 +219,49 @@ 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 optional direct child element whose React element type exactly matches the provided type, or throws when more than one 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 optional direct child element whose type matches the provided element type, or `null` when no match is found.
+ */
+declare function useOptionalChildByType<T extends ElementType>(children: ReactNode, type: T, options?: ValidationOptions): ElementOfType<T> | null;
+
+/**
+ * Returns the optional direct child element that satisfies the provided predicate, or throws when more than one match is found.
+ *
+ * @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 options Optional reporting metadata used to derive the thrown validation message.
+ * @returns The optional direct child element that satisfies the provided predicate, or `null` when no match is found.
+ */
+declare function useOptionalChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: ValidationOptions): T | null;
+declare function useOptionalChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: ValidationOptions): ReactElement | null;
+
+/**
+ * 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>;
+
+/**
+ * Returns the first direct callback child from the provided children value, or throws when none is found.
+ *
+ * @param children The direct children value to inspect.
+ * @param options Optional reporting metadata used to derive the thrown validation message.
+ * @returns The first direct callback child from the provided children value.
+ */
+declare function useRequiredCallbackChild<TArguments extends unknown[] = [], TResult = ReactNode>(children: CallbackChildren<TArguments, TResult>, options?: ValidationOptions): CallbackChild<TArguments, TResult>;
 
-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,16 +270,38 @@ 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;
+
+/**
+ * Returns the only direct child element whose React element type exactly matches the provided type, or throws when the match is not unique.
+ *
+ * @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 only direct child element whose type matches the provided element type.
+ */
+declare function useUniqueChildByType<T extends ElementType>(children: ReactNode, type: T, options?: ValidationOptions): ElementOfType<T>;
+
+/**
+ * Returns the only direct child element that satisfies the provided predicate, or throws when the match is not unique.
+ *
+ * @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 options Optional reporting metadata used to derive the thrown validation message.
+ * @returns The only direct child element that satisfies the provided predicate.
+ */
+declare function useUniqueChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: ValidationOptions): T;
+declare function useUniqueChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: ValidationOptions): ReactElement;
 
 /**
- * Normalizes a React children value into an array containing only valid direct child elements.
+ * Normalizes a React children value into an array containing valid child elements within the configured depth range.
  *
  * @param children The React children value to normalize.
- * @returns An array of valid React elements from the provided direct children.
+ * @param options Optional traversal bounds that control which child depths are included.
+ * @returns An array of valid React elements from the provided child depths.
  */
-declare function childrenToElements(children: ReactNode): ReactElement[];
+declare function childrenToElements(children: ReactNode, options?: TraversalOptions): ReactElement[];
 
 /**
  * Determines whether a React element exactly matches the provided element or component type.
@@ -168,4 +320,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 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 };