react-children-hooks 0.2.0 → 0.4.0

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/isElementOfType.ts","../src/useChildWhere.ts","../src/childrenToElements.ts","../src/isReactElement.ts","../src/useChildByType.ts","../src/useChildrenWhere.ts","../src/useChildrenByType.ts","../src/reporter.ts","../src/useExactChildrenWhere.ts","../src/useHasChildWhere.ts","../src/useMaximumChildrenWhere.ts","../src/useMinimumChildrenWhere.ts","../src/useRequiredChildWhere.ts"],"sourcesContent":["/**\n * Public package entrypoint.\n *\n * Hooks and child utilities will be exported here as the API is defined.\n */\nexport { useChildByType } from \"./useChildByType\";\nexport { useChildWhere } from \"./useChildWhere\";\nexport { useChildrenByType } from \"./useChildrenByType\";\nexport { useChildrenWhere } from \"./useChildrenWhere\";\nexport { useExactChildrenWhere } from \"./useExactChildrenWhere\";\nexport { useHasChildWhere } from \"./useHasChildWhere\";\nexport { useMaximumChildrenWhere } from \"./useMaximumChildrenWhere\";\nexport { useMinimumChildrenWhere } from \"./useMinimumChildrenWhere\";\nexport { useRequiredChildWhere } from \"./useRequiredChildWhere\";\nexport { childrenToElements } from \"./childrenToElements\";\nexport { isElementOfType } from \"./isElementOfType\";\nexport { isReactElement } from \"./isReactElement\";\nexport type { ElementOfType } from \"./types\";\nexport type { UseExactChildrenWhereOptions } from \"./useExactChildrenWhere\";\nexport type { UseMaximumChildrenWhereOptions } from \"./useMaximumChildrenWhere\";\nexport type { UseMinimumChildrenWhereOptions } from \"./useMinimumChildrenWhere\";\nexport type { UseRequiredChildWhereOptions } from \"./useRequiredChildWhere\";\n","import type { ElementType, ReactElement } from \"react\";\n\nimport type { ElementOfType } from \"./types\";\n\n/**\n * Determines whether a React element exactly matches the provided element or component type.\n *\n * @param element The React element to compare.\n * @param type The element or component type to match.\n * @returns `true` when the element's type exactly matches the provided type; otherwise `false`.\n */\nexport function isElementOfType<T extends ElementType>(\n    element: ReactElement,\n    type: T\n): element is ElementOfType<T> {\n    return element.type === type;\n}\n","import { useMemo, type ReactElement, type ReactNode } from \"react\";\n\nimport { childrenToElements } from \"./childrenToElements\";\n\n/**\n * Returns the first direct child element that satisfies the provided predicate.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it matches.\n * @returns The first direct child element that satisfies the provided predicate, or `null` when no match is found.\n */\nexport function useChildWhere<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T\n): T | null;\nexport function useChildWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean\n): ReactElement | null;\nexport function useChildWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean\n): ReactElement | null {\n    return useMemo(\n        () => childrenToElements(children).find(predicate) ?? null,\n        [children, predicate]\n    );\n}\n","import { Children, type ReactElement, type ReactNode } from \"react\";\n\nimport { isReactElement } from \"./isReactElement\";\n\n/**\n * Normalizes a React children value into an array containing only valid direct child elements.\n *\n * @param children The React children value to normalize.\n * @returns An array of valid React elements from the provided direct children.\n */\nexport function childrenToElements(children: ReactNode): ReactElement[] {\n    return Children.toArray(children).filter(isReactElement);\n}\n","import { isValidElement, type ReactElement, type ReactNode } from \"react\";\n\n/**\n * Determines whether a React node is a valid React element.\n *\n * @param node The React node to check.\n * @returns `true` when the node is a valid React element; otherwise `false`.\n */\nexport function isReactElement(node: ReactNode): node is ReactElement {\n    return isValidElement(node);\n}\n","import type { ElementType, ReactNode } from \"react\";\n\nimport { isElementOfType } from \"./isElementOfType\";\nimport { useChildWhere } from \"./useChildWhere\";\nimport type { ElementOfType } from \"./types\";\n\n/**\n * Returns the first direct child element whose React element type exactly matches the provided type.\n *\n * @param children The React children value to inspect.\n * @param type The element or component type to match against each direct child element.\n * @returns The first direct child element whose type matches the provided element type, or `null` when no match is found.\n */\nexport function useChildByType<T extends ElementType>(\n    children: ReactNode,\n    type: T\n): ElementOfType<T> | null {\n    return useChildWhere(children, (element): element is ElementOfType<T> =>\n        isElementOfType(element, type)\n    );\n}\n","import { useMemo, type ReactElement, type ReactNode } from \"react\";\n\nimport { childrenToElements } from \"./childrenToElements\";\n\n/**\n * Returns the direct child elements that satisfy the provided predicate.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it should be included in the result.\n * @returns An array of direct child elements that satisfy the provided predicate.\n */\nexport function useChildrenWhere<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T\n): T[];\nexport function useChildrenWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean\n): ReactElement[];\nexport function useChildrenWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean\n): ReactElement[] {\n    return useMemo(\n        () => childrenToElements(children).filter(predicate),\n        [children, predicate]\n    );\n}\n","import type { ElementType, ReactNode } from \"react\";\n\nimport { isElementOfType } from \"./isElementOfType\";\nimport { useChildrenWhere } from \"./useChildrenWhere\";\nimport type { ElementOfType } from \"./types\";\n\n/**\n * Returns the direct child elements whose React element type exactly matches the provided type.\n *\n * @param children The React children value to inspect.\n * @param type The element or component type to match against each direct child element.\n * @returns An array of direct child elements whose type matches the provided element type.\n */\nexport function useChildrenByType<T extends ElementType>(\n    children: ReactNode,\n    type: T\n): ElementOfType<T>[] {\n    return useChildrenWhere(children, (element): element is ElementOfType<T> =>\n        isElementOfType(element, type)\n    );\n}\n","import { createReporter, type RuntimeReporterMessages } from \"runtime-reporter\";\n\nconst messages: RuntimeReporterMessages<\n    | {\n          code: \"REQUIRED_CHILD_WHERE_PREDICATE_FAILED\";\n          template: \"{{ traceCodePrefix }}Required child validation failed{{ childNameSegment }} because no direct child satisfied the provided predicate.\";\n          tokens: \"traceCodePrefix\" | \"childNameSegment\";\n      }\n    | {\n          code: \"MINIMUM_CHILDREN_WHERE_PREDICATE_FAILED\";\n          template: \"{{ traceCodePrefix }}Minimum children validation failed{{ childNameSegment }} because only {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected at least {{ minimumCount }}.\";\n          tokens:\n              | \"traceCodePrefix\"\n              | \"childNameSegment\"\n              | \"actualCount\"\n              | \"actualCountPluralSuffix\"\n              | \"minimumCount\";\n      }\n    | {\n          code: \"MAXIMUM_CHILDREN_WHERE_PREDICATE_FAILED\";\n          template: \"{{ traceCodePrefix }}Maximum children validation failed{{ childNameSegment }} because {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected at most {{ maximumCount }}.\";\n          tokens:\n              | \"traceCodePrefix\"\n              | \"childNameSegment\"\n              | \"actualCount\"\n              | \"actualCountPluralSuffix\"\n              | \"maximumCount\";\n      }\n    | {\n          code: \"EXACT_CHILDREN_WHERE_PREDICATE_FAILED\";\n          template: \"{{ traceCodePrefix }}Exact children validation failed{{ childNameSegment }} because {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected exactly {{ exactCount }}.\";\n          tokens:\n              | \"traceCodePrefix\"\n              | \"childNameSegment\"\n              | \"actualCount\"\n              | \"actualCountPluralSuffix\"\n              | \"exactCount\";\n      }\n> = {\n    REQUIRED_CHILD_WHERE_PREDICATE_FAILED:\n        \"{{ traceCodePrefix }}Required child validation failed{{ childNameSegment }} because no direct child satisfied the provided predicate.\",\n    MINIMUM_CHILDREN_WHERE_PREDICATE_FAILED:\n        \"{{ traceCodePrefix }}Minimum children validation failed{{ childNameSegment }} because only {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected at least {{ minimumCount }}.\",\n    MAXIMUM_CHILDREN_WHERE_PREDICATE_FAILED:\n        \"{{ traceCodePrefix }}Maximum children validation failed{{ childNameSegment }} because {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected at most {{ maximumCount }}.\",\n    EXACT_CHILDREN_WHERE_PREDICATE_FAILED:\n        \"{{ traceCodePrefix }}Exact children validation failed{{ childNameSegment }} because {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected exactly {{ exactCount }}.\"\n};\n\n/** The runtime reporter for react-children-hooks */\nconst reporter = createReporter(\n    process.env.NODE_ENV === \"production\" ? ({} as typeof messages) : messages,\n    { formatMessage: (message) => message }\n);\n\nexport default reporter;\n","import type { ReactElement, ReactNode } from \"react\";\n\nimport reporter from \"./reporter\";\nimport { useChildrenWhere } from \"./useChildrenWhere\";\n\nexport type UseExactChildrenWhereOptions = {\n    /**\n     * An optional consumer-defined trace code that is prefixed to the thrown validation message.\n     */\n    traceCode?: string;\n    /**\n     * An optional human-readable child name that is included in the thrown validation message.\n     */\n    childName?: string;\n};\n\n/**\n * Returns the direct child elements that satisfy the provided predicate, or throws when the exact count is not met.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it matches.\n * @param exactCount The exact number of matching direct child elements required.\n * @param options Optional reporting metadata used to derive the thrown validation message.\n * @returns The direct child elements that satisfy the provided predicate.\n */\nexport function useExactChildrenWhere<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T,\n    exactCount: number,\n    options?: UseExactChildrenWhereOptions\n): T[];\nexport function useExactChildrenWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    exactCount: number,\n    options?: UseExactChildrenWhereOptions\n): ReactElement[];\nexport function useExactChildrenWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    exactCount: number,\n    options?: UseExactChildrenWhereOptions\n): ReactElement[] {\n    const matchingChildren = useChildrenWhere(children, predicate);\n\n    if (matchingChildren.length === exactCount) {\n        return matchingChildren;\n    }\n\n    return reporter.fail(\"EXACT_CHILDREN_WHERE_PREDICATE_FAILED\", {\n        traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : \"\",\n        childNameSegment: options?.childName ? ` for ${options.childName}` : \"\",\n        actualCount: matchingChildren.length,\n        actualCountPluralSuffix: matchingChildren.length === 1 ? \"\" : \"ren\",\n        exactCount\n    });\n}\n","import { useMemo, type ReactElement, type ReactNode } from \"react\";\n\nimport { childrenToElements } from \"./childrenToElements\";\n\n/**\n * Determines whether any direct child element satisfies the provided predicate.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it matches.\n * @returns `true` when at least one direct child element satisfies the provided predicate; otherwise `false`.\n */\nexport function useHasChildWhere<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T\n): boolean;\nexport function useHasChildWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean\n): boolean;\nexport function useHasChildWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean\n): boolean {\n    return useMemo(\n        () => childrenToElements(children).some(predicate),\n        [children, predicate]\n    );\n}\n","import type { ReactElement, ReactNode } from \"react\";\n\nimport reporter from \"./reporter\";\nimport { useChildrenWhere } from \"./useChildrenWhere\";\n\nexport type UseMaximumChildrenWhereOptions = {\n    /**\n     * An optional consumer-defined trace code that is prefixed to the thrown validation message.\n     */\n    traceCode?: string;\n    /**\n     * An optional human-readable child name that is included in the thrown validation message.\n     */\n    childName?: string;\n};\n\n/**\n * Returns the direct child elements that satisfy the provided predicate, or throws when more than the maximum count are found.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it matches.\n * @param maximumCount The maximum number of matching direct child elements allowed.\n * @param options Optional reporting metadata used to derive the thrown validation message.\n * @returns The direct child elements that satisfy the provided predicate.\n */\nexport function useMaximumChildrenWhere<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T,\n    maximumCount: number,\n    options?: UseMaximumChildrenWhereOptions\n): T[];\nexport function useMaximumChildrenWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    maximumCount: number,\n    options?: UseMaximumChildrenWhereOptions\n): ReactElement[];\nexport function useMaximumChildrenWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    maximumCount: number,\n    options?: UseMaximumChildrenWhereOptions\n): ReactElement[] {\n    const matchingChildren = useChildrenWhere(children, predicate);\n\n    if (matchingChildren.length <= maximumCount) {\n        return matchingChildren;\n    }\n\n    return reporter.fail(\"MAXIMUM_CHILDREN_WHERE_PREDICATE_FAILED\", {\n        traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : \"\",\n        childNameSegment: options?.childName ? ` for ${options.childName}` : \"\",\n        actualCount: matchingChildren.length,\n        actualCountPluralSuffix: matchingChildren.length === 1 ? \"\" : \"ren\",\n        maximumCount\n    });\n}\n","import type { ReactElement, ReactNode } from \"react\";\n\nimport reporter from \"./reporter\";\nimport { useChildrenWhere } from \"./useChildrenWhere\";\n\nexport type UseMinimumChildrenWhereOptions = {\n    /**\n     * An optional consumer-defined trace code that is prefixed to the thrown validation message.\n     */\n    traceCode?: string;\n    /**\n     * An optional human-readable child name that is included in the thrown validation message.\n     */\n    childName?: string;\n};\n\n/**\n * Returns the direct child elements that satisfy the provided predicate, or throws when fewer than the minimum count are found.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it matches.\n * @param minimumCount The minimum number of matching direct child elements required.\n * @param options Optional reporting metadata used to derive the thrown validation message.\n * @returns The direct child elements that satisfy the provided predicate.\n */\nexport function useMinimumChildrenWhere<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T,\n    minimumCount: number,\n    options?: UseMinimumChildrenWhereOptions\n): T[];\nexport function useMinimumChildrenWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    minimumCount: number,\n    options?: UseMinimumChildrenWhereOptions\n): ReactElement[];\nexport function useMinimumChildrenWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    minimumCount: number,\n    options?: UseMinimumChildrenWhereOptions\n): ReactElement[] {\n    const matchingChildren = useChildrenWhere(children, predicate);\n\n    if (matchingChildren.length >= minimumCount) {\n        return matchingChildren;\n    }\n\n    return reporter.fail(\"MINIMUM_CHILDREN_WHERE_PREDICATE_FAILED\", {\n        traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : \"\",\n        childNameSegment: options?.childName ? ` for ${options.childName}` : \"\",\n        actualCount: matchingChildren.length,\n        actualCountPluralSuffix: matchingChildren.length === 1 ? \"\" : \"ren\",\n        minimumCount\n    });\n}\n","import type { ReactElement, ReactNode } from \"react\";\n\nimport reporter from \"./reporter\";\nimport { useChildWhere } from \"./useChildWhere\";\n\nexport type UseRequiredChildWhereOptions = {\n    /**\n     * An optional consumer-defined trace code that is prefixed to the thrown validation message.\n     */\n    traceCode?: string;\n    /**\n     * An optional human-readable child name that is included in the thrown validation message.\n     */\n    childName?: string;\n};\n\n/**\n * Returns the first direct child element that satisfies the provided predicate, or throws when no match is found.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it matches.\n * @param options Optional reporting metadata used to derive the thrown validation message.\n * @returns The first direct child element that satisfies the provided predicate.\n */\nexport function useRequiredChildWhere<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T,\n    options?: UseRequiredChildWhereOptions\n): T;\nexport function useRequiredChildWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    options?: UseRequiredChildWhereOptions\n): ReactElement;\nexport function useRequiredChildWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    options?: UseRequiredChildWhereOptions\n): ReactElement {\n    const child = useChildWhere(children, predicate);\n\n    if (child !== null) {\n        return child;\n    }\n\n    return reporter.fail(\"REQUIRED_CHILD_WHERE_PREDICATE_FAILED\", {\n        traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : \"\",\n        childNameSegment: options?.childName ? ` for ${options.childName}` : \"\"\n    });\n}\n"],"mappings":"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","names":["import_react","import_react","import_react","import_react"]}
+{"version":3,"sources":["../src/index.ts","../src/isElementOfType.ts","../src/useChildMatching.ts","../src/childrenToElements.ts","../src/isReactElement.ts","../src/reporter.ts","../src/useChildByType.ts","../src/useCallbackChild.ts","../src/useChildrenMatching.ts","../src/useBoundedChildrenMatching.ts","../src/useBoundedChildrenByType.ts","../src/useChildrenByType.ts","../src/useExactChildrenMatching.ts","../src/useExactChildrenByType.ts","../src/useHasChildMatching.ts","../src/useMaximumChildrenMatching.ts","../src/useMaximumChildrenByType.ts","../src/useMinimumChildrenMatching.ts","../src/useMinimumChildrenByType.ts","../src/useOptionalChildMatching.ts","../src/useOptionalChildByType.ts","../src/useRequiredChildMatching.ts","../src/useRequiredChildByType.ts","../src/useRequiredCallbackChild.ts","../src/useUniqueChildMatching.ts","../src/useUniqueChildByType.ts"],"sourcesContent":["export { useChildByType } from \"./useChildByType\";\nexport { useCallbackChild } from \"./useCallbackChild\";\nexport { useChildMatching } from \"./useChildMatching\";\nexport { useBoundedChildrenByType } from \"./useBoundedChildrenByType\";\nexport { useBoundedChildrenMatching } from \"./useBoundedChildrenMatching\";\nexport { useChildrenByType } from \"./useChildrenByType\";\nexport { useChildrenMatching } from \"./useChildrenMatching\";\nexport { useExactChildrenByType } from \"./useExactChildrenByType\";\nexport { useExactChildrenMatching } from \"./useExactChildrenMatching\";\nexport { useHasChildMatching } from \"./useHasChildMatching\";\nexport { useMaximumChildrenByType } from \"./useMaximumChildrenByType\";\nexport { useMaximumChildrenMatching } from \"./useMaximumChildrenMatching\";\nexport { useMinimumChildrenByType } from \"./useMinimumChildrenByType\";\nexport { useMinimumChildrenMatching } from \"./useMinimumChildrenMatching\";\nexport { useOptionalChildByType } from \"./useOptionalChildByType\";\nexport { useOptionalChildMatching } from \"./useOptionalChildMatching\";\nexport { useRequiredChildByType } from \"./useRequiredChildByType\";\nexport { useRequiredCallbackChild } from \"./useRequiredCallbackChild\";\nexport { useRequiredChildMatching } from \"./useRequiredChildMatching\";\nexport { useUniqueChildByType } from \"./useUniqueChildByType\";\nexport { useUniqueChildMatching } from \"./useUniqueChildMatching\";\nexport { childrenToElements } from \"./childrenToElements\";\nexport { isElementOfType } from \"./isElementOfType\";\nexport { isReactElement } from \"./isReactElement\";\nexport type * from \"./types\";\n","import type { ElementType, ReactElement } from \"react\";\n\nimport type { ElementOfType } from \"./types\";\n\n/**\n * Determines whether a React element exactly matches the provided element or component type.\n *\n * @param element The React element to compare.\n * @param type The element or component type to match.\n * @returns `true` when the element's type exactly matches the provided type; otherwise `false`.\n */\nexport function isElementOfType<T extends ElementType>(\n    element: ReactElement,\n    type: T\n): element is ElementOfType<T> {\n    return element.type === type;\n}\n","import { useMemo, type ReactElement, type ReactNode } from \"react\";\n\nimport { childrenToElements } from \"./childrenToElements\";\nimport type { QueryOptions } from \"./types\";\n\n/**\n * Returns the first direct child element that satisfies the provided predicate.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it matches.\n * @param options Optional query metadata used to configure how child elements are inspected.\n * @returns The first direct child element that satisfies the provided predicate, or `null` when no match is found.\n */\nexport function useChildMatching<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T,\n    options?: QueryOptions\n): T | null;\nexport function useChildMatching(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    options?: QueryOptions\n): ReactElement | null;\nexport function useChildMatching(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    options?: QueryOptions\n): ReactElement | null {\n    return useMemo(\n        () => childrenToElements(children, options).find(predicate) ?? null,\n        [children, options, predicate]\n    );\n}\n","import { Children, type ReactElement, type ReactNode } from \"react\";\n\nimport { isReactElement } from \"./isReactElement\";\nimport reporter from \"./reporter\";\nimport type { TraversalOptions } from \"./types\";\n\n/**\n * Normalizes traversal bounds and validates that the provided options define a valid inclusive depth range.\n *\n * @param options Optional traversal bounds supplied to an element-inspection API.\n * @returns The normalized inclusive traversal bounds, defaulting to direct children only when omitted.\n */\nfunction getTraversalBounds(options?: TraversalOptions): {\n    depth: number;\n    maximumDepth: number;\n} {\n    const depth = options?.depth ?? 0;\n    const maximumDepth = options?.maximumDepth ?? 0;\n\n    if (!Number.isInteger(depth) || depth < 0) {\n        return reporter.fail(\"RCH001\");\n    }\n\n    if (!Number.isInteger(maximumDepth) || maximumDepth < 0) {\n        return reporter.fail(\"RCH002\");\n    }\n\n    if (depth > maximumDepth) {\n        return reporter.fail(\"RCH003\");\n    }\n\n    return { depth, maximumDepth };\n}\n\n/**\n * Recursively collects valid React child elements within the provided inclusive depth range.\n *\n * @param children The React children value to inspect at the current traversal level.\n * @param currentDepth The zero-based depth of the current traversal level, where `0` represents direct children.\n * @param depth The minimum inclusive child depth to include in the collected results.\n * @param maximumDepth The maximum inclusive child depth to include in the collected results.\n * @returns An array of valid React elements collected from the current level and any eligible descendant levels.\n */\nfunction collectElementsAtDepth(\n    children: ReactNode,\n    currentDepth: number,\n    depth: number,\n    maximumDepth: number\n): ReactElement[] {\n    const directElements = Children.toArray(children).filter(isReactElement);\n    let elements: ReactElement[] = [];\n\n    if (currentDepth >= depth && currentDepth <= maximumDepth) {\n        elements = [...directElements];\n    }\n\n    for (const element of directElements) {\n        const elementProps = element.props as { children?: ReactNode };\n        const elementsAtDepth = collectElementsAtDepth(\n            elementProps.children,\n            currentDepth + 1,\n            depth,\n            maximumDepth\n        );\n\n        elements.push(...elementsAtDepth);\n    }\n\n    return elements;\n}\n\n/**\n * Normalizes a React children value into an array containing valid child elements within the configured depth range.\n *\n * @param children The React children value to normalize.\n * @param options Optional traversal bounds that control which child depths are included.\n * @returns An array of valid React elements from the provided child depths.\n */\nexport function childrenToElements(\n    children: ReactNode,\n    options?: TraversalOptions\n): ReactElement[] {\n    const { depth, maximumDepth } = getTraversalBounds(options);\n\n    return collectElementsAtDepth(children, 0, depth, maximumDepth);\n}\n","import { isValidElement, type ReactElement, type ReactNode } from \"react\";\n\n/**\n * Determines whether a React node is a valid React element.\n *\n * @param node The React node to check.\n * @returns `true` when the node is a valid React element; otherwise `false`.\n */\nexport function isReactElement(node: ReactNode): node is ReactElement {\n    return isValidElement(node);\n}\n","import { createReporter } from \"runtime-reporter\";\n\n/** Internal validation reporter messages used by the hook validation APIs */\nconst validationMessages = {\n    OPTIONAL_CHILD_MATCHING_PREDICATE_FAILED:\n        \"{{ traceCodePrefix }}Optional child validation failed{{ childNameSegment }} because {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected at most 1.\",\n    UNIQUE_CHILD_MATCHING_PREDICATE_FAILED:\n        \"{{ traceCodePrefix }}Unique child validation failed{{ childNameSegment }} because {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected exactly 1.\",\n    REQUIRED_CHILD_MATCHING_PREDICATE_FAILED:\n        \"{{ traceCodePrefix }}Required child validation failed{{ childNameSegment }} because no direct child satisfied the provided predicate.\",\n    REQUIRED_CALLBACK_CHILD_FAILED:\n        \"{{ traceCodePrefix }}Required callback child validation failed{{ childNameSegment }} because no direct callback child was found.\",\n    MINIMUM_CHILDREN_MATCHING_PREDICATE_FAILED:\n        \"{{ traceCodePrefix }}Minimum children validation failed{{ childNameSegment }} because only {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected at least {{ minimumCount }}.\",\n    MAXIMUM_CHILDREN_MATCHING_PREDICATE_FAILED:\n        \"{{ traceCodePrefix }}Maximum children validation failed{{ childNameSegment }} because {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected at most {{ maximumCount }}.\",\n    EXACT_CHILDREN_MATCHING_PREDICATE_FAILED:\n        \"{{ traceCodePrefix }}Exact children validation failed{{ childNameSegment }} because {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected exactly {{ exactCount }}.\",\n    BOUNDED_CHILDREN_MATCHING_PREDICATE_FAILED:\n        \"{{ traceCodePrefix }}Bounded children validation failed{{ childNameSegment }} because {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected between {{ minimumCount }} and {{ maximumCount }} inclusive.\"\n} as const;\n\n/** Public-facing reporter messages for this library */\nconst publicMessages = {\n    RCH001: '[RCH001] Traversal option \"depth\" must be a non-negative integer.',\n    RCH002: '[RCH002] Traversal option \"maximumDepth\" must be a non-negative integer.',\n    RCH003: '[RCH003] Traversal option \"depth\" cannot be greater than \"maximumDepth\".'\n} as const;\n\n/** All reporter messages for this library */\nconst messages = {\n    ...validationMessages,\n    ...publicMessages\n} as const;\n\n/** The runtime reporter for react-children-hooks */\nconst reporter = createReporter(\n    process.env.NODE_ENV === \"production\" ? ({} as typeof messages) : messages,\n    { formatMessage: (message) => message }\n);\n\nexport default reporter;\n","import type { ElementType, ReactNode } from \"react\";\n\nimport { isElementOfType } from \"./isElementOfType\";\nimport type { ElementOfType, QueryOptions } from \"./types\";\nimport { useChildMatching } from \"./useChildMatching\";\n\n/**\n * Returns the first direct child element whose React element type exactly matches the provided type.\n *\n * @param children The React children value to inspect.\n * @param type The element or component type to match against each direct child element.\n * @param options Optional query metadata used to configure how child elements are inspected.\n * @returns The first direct child element whose type matches the provided element type, or `null` when no match is found.\n */\nexport function useChildByType<T extends ElementType>(\n    children: ReactNode,\n    type: T,\n    options?: QueryOptions\n): ElementOfType<T> | null {\n    return useChildMatching(\n        children,\n        (element): element is ElementOfType<T> =>\n            isElementOfType(element, type),\n        options\n    );\n}\n","import { useMemo, type ReactNode } from \"react\";\n\nimport type { CallbackChild, CallbackChildren } from \"./types\";\n\nfunction findFirstCallbackChild<TArguments extends unknown[], TResult>(\n    children: CallbackChildren<TArguments, TResult>\n): CallbackChild<TArguments, TResult> | null {\n    if (typeof children === \"function\") {\n        return children;\n    }\n\n    if (!Array.isArray(children)) {\n        return null;\n    }\n\n    for (const child of children) {\n        const callbackChild = findFirstCallbackChild<TArguments, TResult>(\n            child\n        );\n\n        if (callbackChild) {\n            return callbackChild;\n        }\n    }\n\n    return null;\n}\n\n/**\n * Returns the first direct callback child from the provided children value.\n *\n * @param children The direct children value to inspect.\n * @returns The first direct callback child, or `null` when no callback child is found.\n */\nexport function useCallbackChild<\n    TArguments extends unknown[] = [],\n    TResult = ReactNode\n>(\n    children: CallbackChildren<TArguments, TResult>\n): CallbackChild<TArguments, TResult> | null {\n    return useMemo(() => findFirstCallbackChild(children), [children]);\n}\n","import { useMemo, type ReactElement, type ReactNode } from \"react\";\n\nimport { childrenToElements } from \"./childrenToElements\";\nimport type { QueryOptions } from \"./types\";\n\n/**\n * Returns the direct child elements that satisfy the provided predicate.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it should be included in the result.\n * @param options Optional query metadata used to configure how child elements are inspected.\n * @returns An array of direct child elements that satisfy the provided predicate.\n */\nexport function useChildrenMatching<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T,\n    options?: QueryOptions\n): T[];\nexport function useChildrenMatching(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    options?: QueryOptions\n): ReactElement[];\nexport function useChildrenMatching(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    options?: QueryOptions\n): ReactElement[] {\n    return useMemo(\n        () => childrenToElements(children, options).filter(predicate),\n        [children, options, predicate]\n    );\n}\n","import type { ReactElement, ReactNode } from \"react\";\n\nimport reporter from \"./reporter\";\nimport type { ChildrenCountBounds, ValidationOptions } from \"./types\";\nimport { useChildrenMatching } from \"./useChildrenMatching\";\n\n/**\n * Returns the direct child elements that satisfy the provided predicate, or throws when the count falls outside the inclusive bounds.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it matches.\n * @param bounds The inclusive minimum and maximum number of matching direct child elements allowed.\n * @param options Optional reporting metadata used to derive the thrown validation message.\n * @returns The direct child elements that satisfy the provided predicate.\n */\nexport function useBoundedChildrenMatching<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T,\n    bounds: ChildrenCountBounds,\n    options?: ValidationOptions\n): T[];\nexport function useBoundedChildrenMatching(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    bounds: ChildrenCountBounds,\n    options?: ValidationOptions\n): ReactElement[];\nexport function useBoundedChildrenMatching(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    bounds: ChildrenCountBounds,\n    options?: ValidationOptions\n): ReactElement[] {\n    const matchingChildren = useChildrenMatching(children, predicate, options);\n\n    if (\n        matchingChildren.length >= bounds.minimum &&\n        matchingChildren.length <= bounds.maximum\n    ) {\n        return matchingChildren;\n    }\n\n    return reporter.fail(\"BOUNDED_CHILDREN_MATCHING_PREDICATE_FAILED\", {\n        traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : \"\",\n        childNameSegment: options?.childName ? ` for ${options.childName}` : \"\",\n        actualCount: matchingChildren.length,\n        actualCountPluralSuffix: matchingChildren.length === 1 ? \"\" : \"ren\",\n        minimumCount: bounds.minimum,\n        maximumCount: bounds.maximum\n    });\n}\n","import type { ElementType, ReactNode } from \"react\";\n\nimport { isElementOfType } from \"./isElementOfType\";\nimport type {\n    ChildrenCountBounds,\n    ElementOfType,\n    ValidationOptions\n} from \"./types\";\nimport { useBoundedChildrenMatching } from \"./useBoundedChildrenMatching\";\n\n/**\n * Returns the direct child elements whose React element type exactly matches the provided type, or throws when the count falls outside the inclusive bounds.\n *\n * @param children The React children value to inspect.\n * @param type The element or component type to match against each direct child element.\n * @param bounds The inclusive minimum and maximum number of matching direct child elements allowed.\n * @param options Optional reporting metadata used to derive the thrown validation message.\n * @returns The direct child elements whose type matches the provided element type.\n */\nexport function useBoundedChildrenByType<T extends ElementType>(\n    children: ReactNode,\n    type: T,\n    bounds: ChildrenCountBounds,\n    options?: ValidationOptions\n): ElementOfType<T>[] {\n    return useBoundedChildrenMatching(\n        children,\n        (element): element is ElementOfType<T> =>\n            isElementOfType(element, type),\n        bounds,\n        options\n    );\n}\n","import type { ElementType, ReactNode } from \"react\";\n\nimport { isElementOfType } from \"./isElementOfType\";\nimport type { ElementOfType, QueryOptions } from \"./types\";\nimport { useChildrenMatching } from \"./useChildrenMatching\";\n\n/**\n * Returns the direct child elements whose React element type exactly matches the provided type.\n *\n * @param children The React children value to inspect.\n * @param type The element or component type to match against each direct child element.\n * @param options Optional query metadata used to configure how child elements are inspected.\n * @returns An array of direct child elements whose type matches the provided element type.\n */\nexport function useChildrenByType<T extends ElementType>(\n    children: ReactNode,\n    type: T,\n    options?: QueryOptions\n): ElementOfType<T>[] {\n    return useChildrenMatching(\n        children,\n        (element): element is ElementOfType<T> =>\n            isElementOfType(element, type),\n        options\n    );\n}\n","import type { ReactElement, ReactNode } from \"react\";\n\nimport reporter from \"./reporter\";\nimport type { ValidationOptions } from \"./types\";\nimport { useChildrenMatching } from \"./useChildrenMatching\";\n\n/**\n * Returns the direct child elements that satisfy the provided predicate, or throws when the exact count is not met.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it matches.\n * @param exactCount The exact number of matching direct child elements required.\n * @param options Optional reporting metadata used to derive the thrown validation message.\n * @returns The direct child elements that satisfy the provided predicate.\n */\nexport function useExactChildrenMatching<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T,\n    exactCount: number,\n    options?: ValidationOptions\n): T[];\nexport function useExactChildrenMatching(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    exactCount: number,\n    options?: ValidationOptions\n): ReactElement[];\nexport function useExactChildrenMatching(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    exactCount: number,\n    options?: ValidationOptions\n): ReactElement[] {\n    const matchingChildren = useChildrenMatching(children, predicate, options);\n\n    if (matchingChildren.length === exactCount) {\n        return matchingChildren;\n    }\n\n    return reporter.fail(\"EXACT_CHILDREN_MATCHING_PREDICATE_FAILED\", {\n        traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : \"\",\n        childNameSegment: options?.childName ? ` for ${options.childName}` : \"\",\n        actualCount: matchingChildren.length,\n        actualCountPluralSuffix: matchingChildren.length === 1 ? \"\" : \"ren\",\n        exactCount\n    });\n}\n","import type { ElementType, ReactNode } from \"react\";\n\nimport { isElementOfType } from \"./isElementOfType\";\nimport type { ElementOfType, ValidationOptions } from \"./types\";\nimport { useExactChildrenMatching } from \"./useExactChildrenMatching\";\n\n/**\n * Returns the direct child elements whose React element type exactly matches the provided type, or throws when the exact count is not met.\n *\n * @param children The React children value to inspect.\n * @param type The element or component type to match against each direct child element.\n * @param exactCount The exact number of matching direct child elements required.\n * @param options Optional reporting metadata used to derive the thrown validation message.\n * @returns The direct child elements whose type matches the provided element type.\n */\nexport function useExactChildrenByType<T extends ElementType>(\n    children: ReactNode,\n    type: T,\n    exactCount: number,\n    options?: ValidationOptions\n): ElementOfType<T>[] {\n    return useExactChildrenMatching(\n        children,\n        (element): element is ElementOfType<T> =>\n            isElementOfType(element, type),\n        exactCount,\n        options\n    );\n}\n","import { useMemo, type ReactElement, type ReactNode } from \"react\";\n\nimport { childrenToElements } from \"./childrenToElements\";\nimport type { QueryOptions } from \"./types\";\n\n/**\n * Determines whether any direct child element satisfies the provided predicate.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it matches.\n * @param options Optional query metadata used to configure how child elements are inspected.\n * @returns `true` when at least one direct child element satisfies the provided predicate; otherwise `false`.\n */\nexport function useHasChildMatching<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T,\n    options?: QueryOptions\n): boolean;\nexport function useHasChildMatching(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    options?: QueryOptions\n): boolean;\nexport function useHasChildMatching(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    options?: QueryOptions\n): boolean {\n    return useMemo(\n        () => childrenToElements(children, options).some(predicate),\n        [children, options, predicate]\n    );\n}\n","import type { ReactElement, ReactNode } from \"react\";\n\nimport reporter from \"./reporter\";\nimport type { ValidationOptions } from \"./types\";\nimport { useChildrenMatching } from \"./useChildrenMatching\";\n\n/**\n * Returns the direct child elements that satisfy the provided predicate, or throws when more than the maximum count are found.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it matches.\n * @param maximumCount The maximum number of matching direct child elements allowed.\n * @param options Optional reporting metadata used to derive the thrown validation message.\n * @returns The direct child elements that satisfy the provided predicate.\n */\nexport function useMaximumChildrenMatching<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T,\n    maximumCount: number,\n    options?: ValidationOptions\n): T[];\nexport function useMaximumChildrenMatching(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    maximumCount: number,\n    options?: ValidationOptions\n): ReactElement[];\nexport function useMaximumChildrenMatching(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    maximumCount: number,\n    options?: ValidationOptions\n): ReactElement[] {\n    const matchingChildren = useChildrenMatching(children, predicate, options);\n\n    if (matchingChildren.length <= maximumCount) {\n        return matchingChildren;\n    }\n\n    return reporter.fail(\"MAXIMUM_CHILDREN_MATCHING_PREDICATE_FAILED\", {\n        traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : \"\",\n        childNameSegment: options?.childName ? ` for ${options.childName}` : \"\",\n        actualCount: matchingChildren.length,\n        actualCountPluralSuffix: matchingChildren.length === 1 ? \"\" : \"ren\",\n        maximumCount\n    });\n}\n","import type { ElementType, ReactNode } from \"react\";\n\nimport { isElementOfType } from \"./isElementOfType\";\nimport type { ElementOfType, ValidationOptions } from \"./types\";\nimport { useMaximumChildrenMatching } from \"./useMaximumChildrenMatching\";\n\n/**\n * Returns the direct child elements whose React element type exactly matches the provided type, or throws when more than the maximum count are found.\n *\n * @param children The React children value to inspect.\n * @param type The element or component type to match against each direct child element.\n * @param maximumCount The maximum number of matching direct child elements allowed.\n * @param options Optional reporting metadata used to derive the thrown validation message.\n * @returns The direct child elements whose type matches the provided element type.\n */\nexport function useMaximumChildrenByType<T extends ElementType>(\n    children: ReactNode,\n    type: T,\n    maximumCount: number,\n    options?: ValidationOptions\n): ElementOfType<T>[] {\n    return useMaximumChildrenMatching(\n        children,\n        (element): element is ElementOfType<T> =>\n            isElementOfType(element, type),\n        maximumCount,\n        options\n    );\n}\n","import type { ReactElement, ReactNode } from \"react\";\n\nimport reporter from \"./reporter\";\nimport type { ValidationOptions } from \"./types\";\nimport { useChildrenMatching } from \"./useChildrenMatching\";\n\n/**\n * Returns the direct child elements that satisfy the provided predicate, or throws when fewer than the minimum count are found.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it matches.\n * @param minimumCount The minimum number of matching direct child elements required.\n * @param options Optional reporting metadata used to derive the thrown validation message.\n * @returns The direct child elements that satisfy the provided predicate.\n */\nexport function useMinimumChildrenMatching<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T,\n    minimumCount: number,\n    options?: ValidationOptions\n): T[];\nexport function useMinimumChildrenMatching(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    minimumCount: number,\n    options?: ValidationOptions\n): ReactElement[];\nexport function useMinimumChildrenMatching(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    minimumCount: number,\n    options?: ValidationOptions\n): ReactElement[] {\n    const matchingChildren = useChildrenMatching(children, predicate, options);\n\n    if (matchingChildren.length >= minimumCount) {\n        return matchingChildren;\n    }\n\n    return reporter.fail(\"MINIMUM_CHILDREN_MATCHING_PREDICATE_FAILED\", {\n        traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : \"\",\n        childNameSegment: options?.childName ? ` for ${options.childName}` : \"\",\n        actualCount: matchingChildren.length,\n        actualCountPluralSuffix: matchingChildren.length === 1 ? \"\" : \"ren\",\n        minimumCount\n    });\n}\n","import type { ElementType, ReactNode } from \"react\";\n\nimport { isElementOfType } from \"./isElementOfType\";\nimport type { ElementOfType, ValidationOptions } from \"./types\";\nimport { useMinimumChildrenMatching } from \"./useMinimumChildrenMatching\";\n\n/**\n * Returns the direct child elements whose React element type exactly matches the provided type, or throws when fewer than the minimum count are found.\n *\n * @param children The React children value to inspect.\n * @param type The element or component type to match against each direct child element.\n * @param minimumCount The minimum number of matching direct child elements required.\n * @param options Optional reporting metadata used to derive the thrown validation message.\n * @returns The direct child elements whose type matches the provided element type.\n */\nexport function useMinimumChildrenByType<T extends ElementType>(\n    children: ReactNode,\n    type: T,\n    minimumCount: number,\n    options?: ValidationOptions\n): ElementOfType<T>[] {\n    return useMinimumChildrenMatching(\n        children,\n        (element): element is ElementOfType<T> =>\n            isElementOfType(element, type),\n        minimumCount,\n        options\n    );\n}\n","import type { ReactElement, ReactNode } from \"react\";\n\nimport reporter from \"./reporter\";\nimport type { ValidationOptions } from \"./types\";\nimport { useChildrenMatching } from \"./useChildrenMatching\";\n\n/**\n * Returns the optional direct child element that satisfies the provided predicate, or throws when more than one match is found.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it matches.\n * @param options Optional reporting metadata used to derive the thrown validation message.\n * @returns The optional direct child element that satisfies the provided predicate, or `null` when no match is found.\n */\nexport function useOptionalChildMatching<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T,\n    options?: ValidationOptions\n): T | null;\nexport function useOptionalChildMatching(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    options?: ValidationOptions\n): ReactElement | null;\nexport function useOptionalChildMatching(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    options?: ValidationOptions\n): ReactElement | null {\n    const matchingChildren = useChildrenMatching(children, predicate, options);\n\n    if (matchingChildren.length <= 1) {\n        return matchingChildren[0] ?? null;\n    }\n\n    return reporter.fail(\"OPTIONAL_CHILD_MATCHING_PREDICATE_FAILED\", {\n        traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : \"\",\n        childNameSegment: options?.childName ? ` for ${options.childName}` : \"\",\n        actualCount: matchingChildren.length,\n        actualCountPluralSuffix: matchingChildren.length === 1 ? \"\" : \"ren\"\n    });\n}\n","import type { ElementType, ReactNode } from \"react\";\n\nimport { isElementOfType } from \"./isElementOfType\";\nimport type { ElementOfType, ValidationOptions } from \"./types\";\nimport { useOptionalChildMatching } from \"./useOptionalChildMatching\";\n\n/**\n * Returns the optional direct child element whose React element type exactly matches the provided type, or throws when more than one match is found.\n *\n * @param children The React children value to inspect.\n * @param type The element or component type to match against each direct child element.\n * @param options Optional reporting metadata used to derive the thrown validation message.\n * @returns The optional direct child element whose type matches the provided element type, or `null` when no match is found.\n */\nexport function useOptionalChildByType<T extends ElementType>(\n    children: ReactNode,\n    type: T,\n    options?: ValidationOptions\n): ElementOfType<T> | null {\n    return useOptionalChildMatching(\n        children,\n        (element): element is ElementOfType<T> =>\n            isElementOfType(element, type),\n        options\n    );\n}\n","import type { ReactElement, ReactNode } from \"react\";\n\nimport reporter from \"./reporter\";\nimport type { ValidationOptions } from \"./types\";\nimport { useChildMatching } from \"./useChildMatching\";\n\n/**\n * Returns the first direct child element that satisfies the provided predicate, or throws when no match is found.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it matches.\n * @param options Optional reporting metadata used to derive the thrown validation message.\n * @returns The first direct child element that satisfies the provided predicate.\n */\nexport function useRequiredChildMatching<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T,\n    options?: ValidationOptions\n): T;\nexport function useRequiredChildMatching(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    options?: ValidationOptions\n): ReactElement;\nexport function useRequiredChildMatching(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    options?: ValidationOptions\n): ReactElement {\n    const child = useChildMatching(children, predicate, options);\n\n    if (child !== null) {\n        return child;\n    }\n\n    return reporter.fail(\"REQUIRED_CHILD_MATCHING_PREDICATE_FAILED\", {\n        traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : \"\",\n        childNameSegment: options?.childName ? ` for ${options.childName}` : \"\"\n    });\n}\n","import type { ElementType, ReactNode } from \"react\";\n\nimport { isElementOfType } from \"./isElementOfType\";\nimport type { ElementOfType, ValidationOptions } from \"./types\";\nimport { useRequiredChildMatching } from \"./useRequiredChildMatching\";\n\n/**\n * Returns the first direct child element whose React element type exactly matches the provided type, or throws when no match is found.\n *\n * @param children The React children value to inspect.\n * @param type The element or component type to match against each direct child element.\n * @param options Optional reporting metadata used to derive the thrown validation message.\n * @returns The first direct child element whose type matches the provided element type.\n */\nexport function useRequiredChildByType<T extends ElementType>(\n    children: ReactNode,\n    type: T,\n    options?: ValidationOptions\n): ElementOfType<T> {\n    return useRequiredChildMatching(\n        children,\n        (element): element is ElementOfType<T> =>\n            isElementOfType(element, type),\n        options\n    );\n}\n","import { type ReactNode } from \"react\";\n\nimport reporter from \"./reporter\";\nimport type {\n    CallbackChild,\n    CallbackChildren,\n    ValidationOptions\n} from \"./types\";\nimport { useCallbackChild } from \"./useCallbackChild\";\n\n/**\n * Returns the first direct callback child from the provided children value, or throws when none is found.\n *\n * @param children The direct children value to inspect.\n * @param options Optional reporting metadata used to derive the thrown validation message.\n * @returns The first direct callback child from the provided children value.\n */\nexport function useRequiredCallbackChild<\n    TArguments extends unknown[] = [],\n    TResult = ReactNode\n>(\n    children: CallbackChildren<TArguments, TResult>,\n    options?: ValidationOptions\n): CallbackChild<TArguments, TResult> {\n    const callbackChild = useCallbackChild(children);\n\n    if (callbackChild !== null) {\n        return callbackChild;\n    }\n\n    return reporter.fail(\"REQUIRED_CALLBACK_CHILD_FAILED\", {\n        traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : \"\",\n        childNameSegment: options?.childName ? ` for ${options.childName}` : \"\"\n    });\n}\n","import type { ReactElement, ReactNode } from \"react\";\n\nimport reporter from \"./reporter\";\nimport type { ValidationOptions } from \"./types\";\nimport { useChildrenMatching } from \"./useChildrenMatching\";\n\n/**\n * Returns the only direct child element that satisfies the provided predicate, or throws when the match is not unique.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it matches.\n * @param options Optional reporting metadata used to derive the thrown validation message.\n * @returns The only direct child element that satisfies the provided predicate.\n */\nexport function useUniqueChildMatching<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T,\n    options?: ValidationOptions\n): T;\nexport function useUniqueChildMatching(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    options?: ValidationOptions\n): ReactElement;\nexport function useUniqueChildMatching(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    options?: ValidationOptions\n): ReactElement {\n    const matchingChildren = useChildrenMatching(children, predicate, options);\n\n    if (matchingChildren.length === 1) {\n        return matchingChildren[0] as ReactElement;\n    }\n\n    return reporter.fail(\"UNIQUE_CHILD_MATCHING_PREDICATE_FAILED\", {\n        traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : \"\",\n        childNameSegment: options?.childName ? ` for ${options.childName}` : \"\",\n        actualCount: matchingChildren.length,\n        actualCountPluralSuffix: matchingChildren.length === 1 ? \"\" : \"ren\"\n    });\n}\n","import type { ElementType, ReactNode } from \"react\";\n\nimport { isElementOfType } from \"./isElementOfType\";\nimport type { ElementOfType, ValidationOptions } from \"./types\";\nimport { useUniqueChildMatching } from \"./useUniqueChildMatching\";\n\n/**\n * Returns the only direct child element whose React element type exactly matches the provided type, or throws when the match is not unique.\n *\n * @param children The React children value to inspect.\n * @param type The element or component type to match against each direct child element.\n * @param options Optional reporting metadata used to derive the thrown validation message.\n * @returns The only direct child element whose type matches the provided element type.\n */\nexport function useUniqueChildByType<T extends ElementType>(\n    children: ReactNode,\n    type: T,\n    options?: ValidationOptions\n): ElementOfType<T> {\n    return useUniqueChildMatching(\n        children,\n        (element): element is ElementOfType<T> =>\n            isElementOfType(element, type),\n        options\n    );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACWO,SAAS,gBACZ,SACA,MAC2B;AAC3B,SAAO,QAAQ,SAAS;AAC5B;;;AChBA,IAAAA,gBAA2D;;;ACA3D,IAAAC,gBAA4D;;;ACA5D,mBAAkE;AAQ3D,SAAS,eAAe,MAAuC;AAClE,aAAO,6BAAe,IAAI;AAC9B;;;ACVA,8BAA+B;AAG/B,IAAM,qBAAqB;AAAA,EACvB,0CACI;AAAA,EACJ,wCACI;AAAA,EACJ,0CACI;AAAA,EACJ,gCACI;AAAA,EACJ,4CACI;AAAA,EACJ,4CACI;AAAA,EACJ,0CACI;AAAA,EACJ,4CACI;AACR;AAGA,IAAM,iBAAiB;AAAA,EACnB,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,QAAQ;AACZ;AAGA,IAAM,WAAW;AAAA,EACb,GAAG;AAAA,EACH,GAAG;AACP;AAGA,IAAM,eAAW;AAAA,EACb,QAAQ,IAAI,aAAa,eAAgB,CAAC,IAAwB;AAAA,EAClE,EAAE,eAAe,CAAC,YAAY,QAAQ;AAC1C;AAEA,IAAO,mBAAQ;;;AF7Bf,SAAS,mBAAmB,SAG1B;AACE,QAAM,QAAQ,SAAS,SAAS;AAChC,QAAM,eAAe,SAAS,gBAAgB;AAE9C,MAAI,CAAC,OAAO,UAAU,KAAK,KAAK,QAAQ,GAAG;AACvC,WAAO,iBAAS,KAAK,QAAQ;AAAA,EACjC;AAEA,MAAI,CAAC,OAAO,UAAU,YAAY,KAAK,eAAe,GAAG;AACrD,WAAO,iBAAS,KAAK,QAAQ;AAAA,EACjC;AAEA,MAAI,QAAQ,cAAc;AACtB,WAAO,iBAAS,KAAK,QAAQ;AAAA,EACjC;AAEA,SAAO,EAAE,OAAO,aAAa;AACjC;AAWA,SAAS,uBACL,UACA,cACA,OACA,cACc;AACd,QAAM,iBAAiB,uBAAS,QAAQ,QAAQ,EAAE,OAAO,cAAc;AACvE,MAAI,WAA2B,CAAC;AAEhC,MAAI,gBAAgB,SAAS,gBAAgB,cAAc;AACvD,eAAW,CAAC,GAAG,cAAc;AAAA,EACjC;AAEA,aAAW,WAAW,gBAAgB;AAClC,UAAM,eAAe,QAAQ;AAC7B,UAAM,kBAAkB;AAAA,MACpB,aAAa;AAAA,MACb,eAAe;AAAA,MACf;AAAA,MACA;AAAA,IACJ;AAEA,aAAS,KAAK,GAAG,eAAe;AAAA,EACpC;AAEA,SAAO;AACX;AASO,SAAS,mBACZ,UACA,SACc;AACd,QAAM,EAAE,OAAO,aAAa,IAAI,mBAAmB,OAAO;AAE1D,SAAO,uBAAuB,UAAU,GAAG,OAAO,YAAY;AAClE;;;AD9DO,SAAS,iBACZ,UACA,WACA,SACmB;AACnB,aAAO;AAAA,IACH,MAAM,mBAAmB,UAAU,OAAO,EAAE,KAAK,SAAS,KAAK;AAAA,IAC/D,CAAC,UAAU,SAAS,SAAS;AAAA,EACjC;AACJ;;;AIlBO,SAAS,eACZ,UACA,MACA,SACuB;AACvB,SAAO;AAAA,IACH;AAAA,IACA,CAAC,YACG,gBAAgB,SAAS,IAAI;AAAA,IACjC;AAAA,EACJ;AACJ;;;ACzBA,IAAAC,gBAAwC;AAIxC,SAAS,uBACL,UACyC;AACzC,MAAI,OAAO,aAAa,YAAY;AAChC,WAAO;AAAA,EACX;AAEA,MAAI,CAAC,MAAM,QAAQ,QAAQ,GAAG;AAC1B,WAAO;AAAA,EACX;AAEA,aAAW,SAAS,UAAU;AAC1B,UAAM,gBAAgB;AAAA,MAClB;AAAA,IACJ;AAEA,QAAI,eAAe;AACf,aAAO;AAAA,IACX;AAAA,EACJ;AAEA,SAAO;AACX;AAQO,SAAS,iBAIZ,UACyC;AACzC,aAAO,uBAAQ,MAAM,uBAAuB,QAAQ,GAAG,CAAC,QAAQ,CAAC;AACrE;;;ACzCA,IAAAC,gBAA2D;AAuBpD,SAAS,oBACZ,UACA,WACA,SACc;AACd,aAAO;AAAA,IACH,MAAM,mBAAmB,UAAU,OAAO,EAAE,OAAO,SAAS;AAAA,IAC5D,CAAC,UAAU,SAAS,SAAS;AAAA,EACjC;AACJ;;;ACLO,SAAS,2BACZ,UACA,WACA,QACA,SACc;AACd,QAAM,mBAAmB,oBAAoB,UAAU,WAAW,OAAO;AAEzE,MACI,iBAAiB,UAAU,OAAO,WAClC,iBAAiB,UAAU,OAAO,SACpC;AACE,WAAO;AAAA,EACX;AAEA,SAAO,iBAAS,KAAK,8CAA8C;AAAA,IAC/D,iBAAiB,SAAS,YAAY,IAAI,QAAQ,SAAS,OAAO;AAAA,IAClE,kBAAkB,SAAS,YAAY,QAAQ,QAAQ,SAAS,KAAK;AAAA,IACrE,aAAa,iBAAiB;AAAA,IAC9B,yBAAyB,iBAAiB,WAAW,IAAI,KAAK;AAAA,IAC9D,cAAc,OAAO;AAAA,IACrB,cAAc,OAAO;AAAA,EACzB,CAAC;AACL;;;AC/BO,SAAS,yBACZ,UACA,MACA,QACA,SACkB;AAClB,SAAO;AAAA,IACH;AAAA,IACA,CAAC,YACG,gBAAgB,SAAS,IAAI;AAAA,IACjC;AAAA,IACA;AAAA,EACJ;AACJ;;;AClBO,SAAS,kBACZ,UACA,MACA,SACkB;AAClB,SAAO;AAAA,IACH;AAAA,IACA,CAAC,YACG,gBAAgB,SAAS,IAAI;AAAA,IACjC;AAAA,EACJ;AACJ;;;ACEO,SAAS,yBACZ,UACA,WACA,YACA,SACc;AACd,QAAM,mBAAmB,oBAAoB,UAAU,WAAW,OAAO;AAEzE,MAAI,iBAAiB,WAAW,YAAY;AACxC,WAAO;AAAA,EACX;AAEA,SAAO,iBAAS,KAAK,4CAA4C;AAAA,IAC7D,iBAAiB,SAAS,YAAY,IAAI,QAAQ,SAAS,OAAO;AAAA,IAClE,kBAAkB,SAAS,YAAY,QAAQ,QAAQ,SAAS,KAAK;AAAA,IACrE,aAAa,iBAAiB;AAAA,IAC9B,yBAAyB,iBAAiB,WAAW,IAAI,KAAK;AAAA,IAC9D;AAAA,EACJ,CAAC;AACL;;;AC/BO,SAAS,uBACZ,UACA,MACA,YACA,SACkB;AAClB,SAAO;AAAA,IACH;AAAA,IACA,CAAC,YACG,gBAAgB,SAAS,IAAI;AAAA,IACjC;AAAA,IACA;AAAA,EACJ;AACJ;;;AC5BA,IAAAC,gBAA2D;AAuBpD,SAAS,oBACZ,UACA,WACA,SACO;AACP,aAAO;AAAA,IACH,MAAM,mBAAmB,UAAU,OAAO,EAAE,KAAK,SAAS;AAAA,IAC1D,CAAC,UAAU,SAAS,SAAS;AAAA,EACjC;AACJ;;;ACLO,SAAS,2BACZ,UACA,WACA,cACA,SACc;AACd,QAAM,mBAAmB,oBAAoB,UAAU,WAAW,OAAO;AAEzE,MAAI,iBAAiB,UAAU,cAAc;AACzC,WAAO;AAAA,EACX;AAEA,SAAO,iBAAS,KAAK,8CAA8C;AAAA,IAC/D,iBAAiB,SAAS,YAAY,IAAI,QAAQ,SAAS,OAAO;AAAA,IAClE,kBAAkB,SAAS,YAAY,QAAQ,QAAQ,SAAS,KAAK;AAAA,IACrE,aAAa,iBAAiB;AAAA,IAC9B,yBAAyB,iBAAiB,WAAW,IAAI,KAAK;AAAA,IAC9D;AAAA,EACJ,CAAC;AACL;;;AC/BO,SAAS,yBACZ,UACA,MACA,cACA,SACkB;AAClB,SAAO;AAAA,IACH;AAAA,IACA,CAAC,YACG,gBAAgB,SAAS,IAAI;AAAA,IACjC;AAAA,IACA;AAAA,EACJ;AACJ;;;ACDO,SAAS,2BACZ,UACA,WACA,cACA,SACc;AACd,QAAM,mBAAmB,oBAAoB,UAAU,WAAW,OAAO;AAEzE,MAAI,iBAAiB,UAAU,cAAc;AACzC,WAAO;AAAA,EACX;AAEA,SAAO,iBAAS,KAAK,8CAA8C;AAAA,IAC/D,iBAAiB,SAAS,YAAY,IAAI,QAAQ,SAAS,OAAO;AAAA,IAClE,kBAAkB,SAAS,YAAY,QAAQ,QAAQ,SAAS,KAAK;AAAA,IACrE,aAAa,iBAAiB;AAAA,IAC9B,yBAAyB,iBAAiB,WAAW,IAAI,KAAK;AAAA,IAC9D;AAAA,EACJ,CAAC;AACL;;;AC/BO,SAAS,yBACZ,UACA,MACA,cACA,SACkB;AAClB,SAAO;AAAA,IACH;AAAA,IACA,CAAC,YACG,gBAAgB,SAAS,IAAI;AAAA,IACjC;AAAA,IACA;AAAA,EACJ;AACJ;;;ACJO,SAAS,yBACZ,UACA,WACA,SACmB;AACnB,QAAM,mBAAmB,oBAAoB,UAAU,WAAW,OAAO;AAEzE,MAAI,iBAAiB,UAAU,GAAG;AAC9B,WAAO,iBAAiB,CAAC,KAAK;AAAA,EAClC;AAEA,SAAO,iBAAS,KAAK,4CAA4C;AAAA,IAC7D,iBAAiB,SAAS,YAAY,IAAI,QAAQ,SAAS,OAAO;AAAA,IAClE,kBAAkB,SAAS,YAAY,QAAQ,QAAQ,SAAS,KAAK;AAAA,IACrE,aAAa,iBAAiB;AAAA,IAC9B,yBAAyB,iBAAiB,WAAW,IAAI,KAAK;AAAA,EAClE,CAAC;AACL;;;AC3BO,SAAS,uBACZ,UACA,MACA,SACuB;AACvB,SAAO;AAAA,IACH;AAAA,IACA,CAAC,YACG,gBAAgB,SAAS,IAAI;AAAA,IACjC;AAAA,EACJ;AACJ;;;ACDO,SAAS,yBACZ,UACA,WACA,SACY;AACZ,QAAM,QAAQ,iBAAiB,UAAU,WAAW,OAAO;AAE3D,MAAI,UAAU,MAAM;AAChB,WAAO;AAAA,EACX;AAEA,SAAO,iBAAS,KAAK,4CAA4C;AAAA,IAC7D,iBAAiB,SAAS,YAAY,IAAI,QAAQ,SAAS,OAAO;AAAA,IAClE,kBAAkB,SAAS,YAAY,QAAQ,QAAQ,SAAS,KAAK;AAAA,EACzE,CAAC;AACL;;;ACzBO,SAAS,uBACZ,UACA,MACA,SACgB;AAChB,SAAO;AAAA,IACH;AAAA,IACA,CAAC,YACG,gBAAgB,SAAS,IAAI;AAAA,IACjC;AAAA,EACJ;AACJ;;;ACzBA,IAAAC,gBAA+B;AAiBxB,SAAS,yBAIZ,UACA,SACkC;AAClC,QAAM,gBAAgB,iBAAiB,QAAQ;AAE/C,MAAI,kBAAkB,MAAM;AACxB,WAAO;AAAA,EACX;AAEA,SAAO,iBAAS,KAAK,kCAAkC;AAAA,IACnD,iBAAiB,SAAS,YAAY,IAAI,QAAQ,SAAS,OAAO;AAAA,IAClE,kBAAkB,SAAS,YAAY,QAAQ,QAAQ,SAAS,KAAK;AAAA,EACzE,CAAC;AACL;;;ACVO,SAAS,uBACZ,UACA,WACA,SACY;AACZ,QAAM,mBAAmB,oBAAoB,UAAU,WAAW,OAAO;AAEzE,MAAI,iBAAiB,WAAW,GAAG;AAC/B,WAAO,iBAAiB,CAAC;AAAA,EAC7B;AAEA,SAAO,iBAAS,KAAK,0CAA0C;AAAA,IAC3D,iBAAiB,SAAS,YAAY,IAAI,QAAQ,SAAS,OAAO;AAAA,IAClE,kBAAkB,SAAS,YAAY,QAAQ,QAAQ,SAAS,KAAK;AAAA,IACrE,aAAa,iBAAiB;AAAA,IAC9B,yBAAyB,iBAAiB,WAAW,IAAI,KAAK;AAAA,EAClE,CAAC;AACL;;;AC3BO,SAAS,qBACZ,UACA,MACA,SACgB;AAChB,SAAO;AAAA,IACH;AAAA,IACA,CAAC,YACG,gBAAgB,SAAS,IAAI;AAAA,IACjC;AAAA,EACJ;AACJ;","names":["import_react","import_react","import_react","import_react","import_react","import_react"]}

package/dist/index.d.cts

@@ -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 };