react-children-hooks 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +16 -10
  2. package/dist/index.cjs +245 -59
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.d.cts +115 -23
  5. package/dist/index.d.ts +115 -23
  6. package/dist/index.js +236 -55
  7. package/dist/index.js.map +1 -1
  8. package/package.json +4 -3
package/dist/index.cjs.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"sources":["../src/index.ts","../src/isElementOfType.ts","../src/useChildMatching.ts","../src/childrenToElements.ts","../src/isReactElement.ts","../src/useChildByType.ts","../src/reporter.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/useRequiredChildMatching.ts","../src/useRequiredChildByType.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 { 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 { useRequiredChildByType } from \"./useRequiredChildByType\";\nexport { useRequiredChildMatching } from \"./useRequiredChildMatching\";\nexport { childrenToElements } from \"./childrenToElements\";\nexport { isElementOfType } from \"./isElementOfType\";\nexport { isReactElement } from \"./isReactElement\";\nexport type {\n ChildrenCountBounds,\n ElementOfType,\n ValidationOptions\n} 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\";\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 useChildMatching<T extends ReactElement>(\n children: ReactNode,\n predicate: (element: ReactElement) => element is T\n): T | null;\nexport function useChildMatching(\n children: ReactNode,\n predicate: (element: ReactElement) => boolean\n): ReactElement | null;\nexport function useChildMatching(\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 type { ElementOfType } 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 * @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 useChildMatching(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_MATCHING_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_MATCHING_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_MATCHING_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_MATCHING_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 code: \"BOUNDED_CHILDREN_MATCHING_PREDICATE_FAILED\";\n template: \"{{ traceCodePrefix }}Bounded children validation failed{{ childNameSegment }} because {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected between {{ minimumCount }} and {{ maximumCount }} inclusive.\";\n tokens:\n | \"traceCodePrefix\"\n | \"childNameSegment\"\n | \"actualCount\"\n | \"actualCountPluralSuffix\"\n | \"minimumCount\"\n | \"maximumCount\";\n }\n> = {\n REQUIRED_CHILD_MATCHING_PREDICATE_FAILED:\n \"{{ traceCodePrefix }}Required child validation failed{{ childNameSegment }} because no direct child satisfied the provided predicate.\",\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};\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 { 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 useChildrenMatching<T extends ReactElement>(\n children: ReactNode,\n predicate: (element: ReactElement) => element is T\n): T[];\nexport function useChildrenMatching(\n children: ReactNode,\n predicate: (element: ReactElement) => boolean\n): ReactElement[];\nexport function useChildrenMatching(\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 { 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);\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 } 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 * @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 useChildrenMatching(\n children,\n (element): element is ElementOfType<T> => isElementOfType(element, type)\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);\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\";\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 useHasChildMatching<T extends ReactElement>(\n children: ReactNode,\n predicate: (element: ReactElement) => element is T\n): boolean;\nexport function useHasChildMatching(\n children: ReactNode,\n predicate: (element: ReactElement) => boolean\n): boolean;\nexport function useHasChildMatching(\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 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);\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);\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 { 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);\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"],"mappings":"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","names":["import_react","import_react","import_react","import_react"]}
1
+ {"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/callbackChildrenToArray.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/useOptionalCallbackChild.ts","../src/useOptionalChildMatching.ts","../src/useOptionalChildByType.ts","../src/useRequiredChildMatching.ts","../src/useRequiredChildByType.ts","../src/useRequiredCallbackChild.ts","../src/useUniqueCallbackChild.ts","../src/useUniqueChildMatching.ts","../src/useUniqueChildByType.ts"],"sourcesContent":["export { default as useChildByType } from \"./useChildByType\";\nexport { default as useCallbackChild } from \"./useCallbackChild\";\nexport { default as useChildMatching } from \"./useChildMatching\";\nexport { default as useBoundedChildrenByType } from \"./useBoundedChildrenByType\";\nexport { default as useBoundedChildrenMatching } from \"./useBoundedChildrenMatching\";\nexport { default as useChildrenByType } from \"./useChildrenByType\";\nexport { default as useChildrenMatching } from \"./useChildrenMatching\";\nexport { default as useExactChildrenByType } from \"./useExactChildrenByType\";\nexport { default as useExactChildrenMatching } from \"./useExactChildrenMatching\";\nexport { default as useHasChildMatching } from \"./useHasChildMatching\";\nexport { default as useMaximumChildrenByType } from \"./useMaximumChildrenByType\";\nexport { default as useMaximumChildrenMatching } from \"./useMaximumChildrenMatching\";\nexport { default as useMinimumChildrenByType } from \"./useMinimumChildrenByType\";\nexport { default as useMinimumChildrenMatching } from \"./useMinimumChildrenMatching\";\nexport { default as useOptionalCallbackChild } from \"./useOptionalCallbackChild\";\nexport { default as useOptionalChildByType } from \"./useOptionalChildByType\";\nexport { default as useOptionalChildMatching } from \"./useOptionalChildMatching\";\nexport { default as useRequiredChildByType } from \"./useRequiredChildByType\";\nexport { default as useRequiredCallbackChild } from \"./useRequiredCallbackChild\";\nexport { default as useRequiredChildMatching } from \"./useRequiredChildMatching\";\nexport { default as useUniqueCallbackChild } from \"./useUniqueCallbackChild\";\nexport { default as useUniqueChildByType } from \"./useUniqueChildByType\";\nexport { default as useUniqueChildMatching } from \"./useUniqueChildMatching\";\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 default 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 */\nfunction useChildMatching<T extends ReactElement>(\n children: ReactNode,\n predicate: (element: ReactElement) => element is T,\n options?: QueryOptions\n): T | null;\nfunction useChildMatching(\n children: ReactNode,\n predicate: (element: ReactElement) => boolean,\n options?: QueryOptions\n): ReactElement | null;\nfunction 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\nexport default useChildMatching;\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 default 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 default 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 OPTIONAL_CALLBACK_CHILD_FAILED:\n \"{{ traceCodePrefix }}Optional callback child validation failed{{ childNameSegment }} because {{ actualCount }} direct callback children were found; expected at most 1.\",\n UNIQUE_CALLBACK_CHILD_FAILED:\n \"{{ traceCodePrefix }}Unique callback child validation failed{{ childNameSegment }} because {{ actualCount }} direct callback children were found; expected exactly 1.\",\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 default 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 callbackChildrenToArray from \"./callbackChildrenToArray\";\nimport type { CallbackChild, CallbackChildren } from \"./types\";\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 default function useCallbackChild<\n TArguments extends unknown[] = [],\n TResult = ReactNode\n>(\n children: CallbackChildren<TArguments, TResult>\n): CallbackChild<TArguments, TResult> | null {\n return useMemo(\n () => callbackChildrenToArray(children)[0] ?? null,\n [children]\n );\n}\n","import type { ReactNode } from \"react\";\n\nimport type { CallbackChild, CallbackChildren } from \"./types\";\n\n/**\n * Collects direct callback children from the provided children value.\n *\n * Arrays are flattened, but callback values nested inside React elements are ignored.\n *\n * @param children The direct children value to inspect.\n * @returns An array of direct callback children.\n */\nexport default function callbackChildrenToArray<\n TArguments extends unknown[] = [],\n TResult = ReactNode\n>(\n children: CallbackChildren<TArguments, TResult>\n): CallbackChild<TArguments, TResult>[] {\n if (typeof children === \"function\") {\n return [children];\n }\n\n if (!Array.isArray(children)) {\n return [];\n }\n\n return children.flatMap((child) =>\n callbackChildrenToArray<TArguments, TResult>(child)\n );\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 */\nfunction useChildrenMatching<T extends ReactElement>(\n children: ReactNode,\n predicate: (element: ReactElement) => element is T,\n options?: QueryOptions\n): T[];\nfunction useChildrenMatching(\n children: ReactNode,\n predicate: (element: ReactElement) => boolean,\n options?: QueryOptions\n): ReactElement[];\nfunction 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\nexport default useChildrenMatching;\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 */\nfunction useBoundedChildrenMatching<T extends ReactElement>(\n children: ReactNode,\n predicate: (element: ReactElement) => element is T,\n bounds: ChildrenCountBounds,\n options?: ValidationOptions\n): T[];\nfunction useBoundedChildrenMatching(\n children: ReactNode,\n predicate: (element: ReactElement) => boolean,\n bounds: ChildrenCountBounds,\n options?: ValidationOptions\n): ReactElement[];\nfunction 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\nexport default useBoundedChildrenMatching;\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 default 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 default 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 */\nfunction useExactChildrenMatching<T extends ReactElement>(\n children: ReactNode,\n predicate: (element: ReactElement) => element is T,\n exactCount: number,\n options?: ValidationOptions\n): T[];\nfunction useExactChildrenMatching(\n children: ReactNode,\n predicate: (element: ReactElement) => boolean,\n exactCount: number,\n options?: ValidationOptions\n): ReactElement[];\nfunction 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\nexport default useExactChildrenMatching;\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 default 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 */\nfunction useHasChildMatching<T extends ReactElement>(\n children: ReactNode,\n predicate: (element: ReactElement) => element is T,\n options?: QueryOptions\n): boolean;\nfunction useHasChildMatching(\n children: ReactNode,\n predicate: (element: ReactElement) => boolean,\n options?: QueryOptions\n): boolean;\nfunction 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\nexport default useHasChildMatching;\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 */\nfunction useMaximumChildrenMatching<T extends ReactElement>(\n children: ReactNode,\n predicate: (element: ReactElement) => element is T,\n maximumCount: number,\n options?: ValidationOptions\n): T[];\nfunction useMaximumChildrenMatching(\n children: ReactNode,\n predicate: (element: ReactElement) => boolean,\n maximumCount: number,\n options?: ValidationOptions\n): ReactElement[];\nfunction 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\nexport default useMaximumChildrenMatching;\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 default 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 */\nfunction useMinimumChildrenMatching<T extends ReactElement>(\n children: ReactNode,\n predicate: (element: ReactElement) => element is T,\n minimumCount: number,\n options?: ValidationOptions\n): T[];\nfunction useMinimumChildrenMatching(\n children: ReactNode,\n predicate: (element: ReactElement) => boolean,\n minimumCount: number,\n options?: ValidationOptions\n): ReactElement[];\nfunction 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\nexport default useMinimumChildrenMatching;\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 default 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 { useMemo, type ReactNode } from \"react\";\n\nimport callbackChildrenToArray from \"./callbackChildrenToArray\";\nimport reporter from \"./reporter\";\nimport type {\n CallbackChild,\n CallbackChildren,\n ValidationOptions\n} from \"./types\";\n\n/**\n * Returns the optional direct callback child from the provided children value, or throws when more than one 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 optional direct callback child from the provided children value, or `null` when none is found.\n */\nexport default function useOptionalCallbackChild<\n TArguments extends unknown[] = [],\n TResult = ReactNode\n>(\n children: CallbackChildren<TArguments, TResult>,\n options?: ValidationOptions\n): CallbackChild<TArguments, TResult> | null {\n const callbackChildren = useMemo(\n () => callbackChildrenToArray(children),\n [children]\n );\n\n if (callbackChildren.length <= 1) {\n return callbackChildren[0] ?? null;\n }\n\n return reporter.fail(\"OPTIONAL_CALLBACK_CHILD_FAILED\", {\n traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : \"\",\n childNameSegment: options?.childName ? ` for ${options.childName}` : \"\",\n actualCount: callbackChildren.length\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 */\nfunction useOptionalChildMatching<T extends ReactElement>(\n children: ReactNode,\n predicate: (element: ReactElement) => element is T,\n options?: ValidationOptions\n): T | null;\nfunction useOptionalChildMatching(\n children: ReactNode,\n predicate: (element: ReactElement) => boolean,\n options?: ValidationOptions\n): ReactElement | null;\nfunction 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\nexport default useOptionalChildMatching;\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 default 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 */\nfunction useRequiredChildMatching<T extends ReactElement>(\n children: ReactNode,\n predicate: (element: ReactElement) => element is T,\n options?: ValidationOptions\n): T;\nfunction useRequiredChildMatching(\n children: ReactNode,\n predicate: (element: ReactElement) => boolean,\n options?: ValidationOptions\n): ReactElement;\nfunction 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\nexport default useRequiredChildMatching;\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 default 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 default 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 { useMemo, type ReactNode } from \"react\";\n\nimport callbackChildrenToArray from \"./callbackChildrenToArray\";\nimport reporter from \"./reporter\";\nimport type {\n CallbackChild,\n CallbackChildren,\n ValidationOptions\n} from \"./types\";\n\n/**\n * Returns the only direct callback child from the provided children value, or throws when the match is not unique.\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 only direct callback child from the provided children value.\n */\nexport default function useUniqueCallbackChild<\n TArguments extends unknown[] = [],\n TResult = ReactNode\n>(\n children: CallbackChildren<TArguments, TResult>,\n options?: ValidationOptions\n): CallbackChild<TArguments, TResult> {\n const callbackChildren = useMemo(\n () => callbackChildrenToArray(children),\n [children]\n );\n\n if (callbackChildren.length === 1) {\n return callbackChildren[0] as CallbackChild<TArguments, TResult>;\n }\n\n return reporter.fail(\"UNIQUE_CALLBACK_CHILD_FAILED\", {\n traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : \"\",\n childNameSegment: options?.childName ? ` for ${options.childName}` : \"\",\n actualCount: callbackChildren.length\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 */\nfunction useUniqueChildMatching<T extends ReactElement>(\n children: ReactNode,\n predicate: (element: ReactElement) => element is T,\n options?: ValidationOptions\n): T;\nfunction useUniqueChildMatching(\n children: ReactNode,\n predicate: (element: ReactElement) => boolean,\n options?: ValidationOptions\n): ReactElement;\nfunction 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\nexport default useUniqueChildMatching;\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 default 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":"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","names":["import_react","import_react","import_react","import_react","import_react","import_react","import_react","import_react"]}
package/dist/index.d.cts CHANGED
@@ -14,16 +14,47 @@ type ChildrenCountBounds = {
14
14
  */
15
15
  maximum: number;
16
16
  };
17
+ /**
18
+ * Optional traversal bounds used by the element-based query and validation hooks.
19
+ */
20
+ type TraversalOptions = {
21
+ /**
22
+ * The minimum inclusive child depth to include in results, where `0` represents direct children.
23
+ */
24
+ depth?: number;
25
+ /**
26
+ * The maximum inclusive child depth to include in results, where `0` represents direct children.
27
+ */
28
+ maximumDepth?: number;
29
+ };
30
+ /**
31
+ * Optional traversal metadata used by the element-based query hooks.
32
+ */
33
+ type QueryOptions = TraversalOptions;
17
34
  /**
18
35
  * Represents a React element whose props and element type are narrowed to the provided React element type.
19
36
  *
20
37
  * @typeParam T The React element type used to narrow the element's props and type.
21
38
  */
22
39
  type ElementOfType<T extends React.ElementType> = React.ReactElement<React.ComponentProps<T>, T>;
40
+ /**
41
+ * A callback child, also known as a render-prop child.
42
+ *
43
+ * @typeParam TArguments The positional argument tuple accepted by the callback.
44
+ * @typeParam TResult The value returned by the callback.
45
+ */
46
+ type CallbackChild<TArguments extends unknown[] = [], TResult = React.ReactNode> = (...args: TArguments) => TResult;
47
+ /**
48
+ * A direct-children value that may include callback children alongside regular React children.
49
+ *
50
+ * @typeParam TArguments The positional argument tuple accepted by callback children.
51
+ * @typeParam TResult The value returned by callback children.
52
+ */
53
+ type CallbackChildren<TArguments extends unknown[] = [], TResult = React.ReactNode> = React.ReactNode | CallbackChild<TArguments, TResult> | readonly CallbackChildren<TArguments, TResult>[];
23
54
  /**
24
55
  * Optional reporting metadata used by the validation hooks to derive thrown validation messages.
25
56
  */
26
- type ValidationOptions = {
57
+ type ValidationMessageOptions = {
27
58
  /**
28
59
  * An optional consumer-defined trace code that is prefixed to the thrown validation message.
29
60
  */
@@ -33,25 +64,39 @@ type ValidationOptions = {
33
64
  */
34
65
  childName?: string;
35
66
  };
67
+ /**
68
+ * Optional reporting and traversal metadata used by the validation hooks.
69
+ */
70
+ type ValidationOptions = ValidationMessageOptions & TraversalOptions;
36
71
 
37
72
  /**
38
73
  * Returns the first direct child element whose React element type exactly matches the provided type.
39
74
  *
40
75
  * @param children The React children value to inspect.
41
76
  * @param type The element or component type to match against each direct child element.
77
+ * @param options Optional query metadata used to configure how child elements are inspected.
42
78
  * @returns The first direct child element whose type matches the provided element type, or `null` when no match is found.
43
79
  */
44
- declare function useChildByType<T extends ElementType>(children: ReactNode, type: T): ElementOfType<T> | null;
80
+ declare function useChildByType<T extends ElementType>(children: ReactNode, type: T, options?: QueryOptions): ElementOfType<T> | null;
81
+
82
+ /**
83
+ * Returns the first direct callback child from the provided children value.
84
+ *
85
+ * @param children The direct children value to inspect.
86
+ * @returns The first direct callback child, or `null` when no callback child is found.
87
+ */
88
+ declare function useCallbackChild<TArguments extends unknown[] = [], TResult = ReactNode>(children: CallbackChildren<TArguments, TResult>): CallbackChild<TArguments, TResult> | null;
45
89
 
46
90
  /**
47
91
  * Returns the first direct child element that satisfies the provided predicate.
48
92
  *
49
93
  * @param children The React children value to inspect.
50
94
  * @param predicate A predicate that is called with each direct child element to determine whether it matches.
95
+ * @param options Optional query metadata used to configure how child elements are inspected.
51
96
  * @returns The first direct child element that satisfies the provided predicate, or `null` when no match is found.
52
97
  */
53
- declare function useChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): T | null;
54
- declare function useChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean): ReactElement | null;
98
+ declare function useChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: QueryOptions): T | null;
99
+ declare function useChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: QueryOptions): ReactElement | null;
55
100
 
56
101
  /**
57
102
  * Returns the direct child elements whose React element type exactly matches the provided type, or throws when the count falls outside the inclusive bounds.
@@ -81,19 +126,21 @@ declare function useBoundedChildrenMatching(children: ReactNode, predicate: (ele
81
126
  *
82
127
  * @param children The React children value to inspect.
83
128
  * @param type The element or component type to match against each direct child element.
129
+ * @param options Optional query metadata used to configure how child elements are inspected.
84
130
  * @returns An array of direct child elements whose type matches the provided element type.
85
131
  */
86
- declare function useChildrenByType<T extends ElementType>(children: ReactNode, type: T): ElementOfType<T>[];
132
+ declare function useChildrenByType<T extends ElementType>(children: ReactNode, type: T, options?: QueryOptions): ElementOfType<T>[];
87
133
 
88
134
  /**
89
135
  * Returns the direct child elements that satisfy the provided predicate.
90
136
  *
91
137
  * @param children The React children value to inspect.
92
138
  * @param predicate A predicate that is called with each direct child element to determine whether it should be included in the result.
139
+ * @param options Optional query metadata used to configure how child elements are inspected.
93
140
  * @returns An array of direct child elements that satisfy the provided predicate.
94
141
  */
95
- declare function useChildrenMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): T[];
96
- declare function useChildrenMatching(children: ReactNode, predicate: (element: ReactElement) => boolean): ReactElement[];
142
+ declare function useChildrenMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: QueryOptions): T[];
143
+ declare function useChildrenMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: QueryOptions): ReactElement[];
97
144
 
98
145
  /**
99
146
  * Returns the direct child elements whose React element type exactly matches the provided type, or throws when the exact count is not met.
@@ -123,10 +170,11 @@ declare function useExactChildrenMatching(children: ReactNode, predicate: (eleme
123
170
  *
124
171
  * @param children The React children value to inspect.
125
172
  * @param predicate A predicate that is called with each direct child element to determine whether it matches.
173
+ * @param options Optional query metadata used to configure how child elements are inspected.
126
174
  * @returns `true` when at least one direct child element satisfies the provided predicate; otherwise `false`.
127
175
  */
128
- declare function useHasChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): boolean;
129
- declare function useHasChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean): boolean;
176
+ declare function useHasChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: QueryOptions): boolean;
177
+ declare function useHasChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: QueryOptions): boolean;
130
178
 
131
179
  /**
132
180
  * Returns the direct child elements whose React element type exactly matches the provided type, or throws when more than the maximum count are found.
@@ -174,6 +222,36 @@ declare function useMinimumChildrenByType<T extends ElementType>(children: React
174
222
  declare function useMinimumChildrenMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, minimumCount: number, options?: ValidationOptions): T[];
175
223
  declare function useMinimumChildrenMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, minimumCount: number, options?: ValidationOptions): ReactElement[];
176
224
 
225
+ /**
226
+ * Returns the optional direct callback child from the provided children value, or throws when more than one is found.
227
+ *
228
+ * @param children The direct children value to inspect.
229
+ * @param options Optional reporting metadata used to derive the thrown validation message.
230
+ * @returns The optional direct callback child from the provided children value, or `null` when none is found.
231
+ */
232
+ declare function useOptionalCallbackChild<TArguments extends unknown[] = [], TResult = ReactNode>(children: CallbackChildren<TArguments, TResult>, options?: ValidationOptions): CallbackChild<TArguments, TResult> | null;
233
+
234
+ /**
235
+ * Returns the optional direct child element whose React element type exactly matches the provided type, or throws when more than one match is found.
236
+ *
237
+ * @param children The React children value to inspect.
238
+ * @param type The element or component type to match against each direct child element.
239
+ * @param options Optional reporting metadata used to derive the thrown validation message.
240
+ * @returns The optional direct child element whose type matches the provided element type, or `null` when no match is found.
241
+ */
242
+ declare function useOptionalChildByType<T extends ElementType>(children: ReactNode, type: T, options?: ValidationOptions): ElementOfType<T> | null;
243
+
244
+ /**
245
+ * Returns the optional direct child element that satisfies the provided predicate, or throws when more than one match is found.
246
+ *
247
+ * @param children The React children value to inspect.
248
+ * @param predicate A predicate that is called with each direct child element to determine whether it matches.
249
+ * @param options Optional reporting metadata used to derive the thrown validation message.
250
+ * @returns The optional direct child element that satisfies the provided predicate, or `null` when no match is found.
251
+ */
252
+ declare function useOptionalChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: ValidationOptions): T | null;
253
+ declare function useOptionalChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: ValidationOptions): ReactElement | null;
254
+
177
255
  /**
178
256
  * Returns the first direct child element whose React element type exactly matches the provided type, or throws when no match is found.
179
257
  *
@@ -184,6 +262,15 @@ declare function useMinimumChildrenMatching(children: ReactNode, predicate: (ele
184
262
  */
185
263
  declare function useRequiredChildByType<T extends ElementType>(children: ReactNode, type: T, options?: ValidationOptions): ElementOfType<T>;
186
264
 
265
+ /**
266
+ * Returns the first direct callback child from the provided children value, or throws when none is found.
267
+ *
268
+ * @param children The direct children value to inspect.
269
+ * @param options Optional reporting metadata used to derive the thrown validation message.
270
+ * @returns The first direct callback child from the provided children value.
271
+ */
272
+ declare function useRequiredCallbackChild<TArguments extends unknown[] = [], TResult = ReactNode>(children: CallbackChildren<TArguments, TResult>, options?: ValidationOptions): CallbackChild<TArguments, TResult>;
273
+
187
274
  /**
188
275
  * Returns the first direct child element that satisfies the provided predicate, or throws when no match is found.
189
276
  *
@@ -196,28 +283,33 @@ declare function useRequiredChildMatching<T extends ReactElement>(children: Reac
196
283
  declare function useRequiredChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: ValidationOptions): ReactElement;
197
284
 
198
285
  /**
199
- * Normalizes a React children value into an array containing only valid direct child elements.
286
+ * Returns the only direct callback child from the provided children value, or throws when the match is not unique.
200
287
  *
201
- * @param children The React children value to normalize.
202
- * @returns An array of valid React elements from the provided direct children.
288
+ * @param children The direct children value to inspect.
289
+ * @param options Optional reporting metadata used to derive the thrown validation message.
290
+ * @returns The only direct callback child from the provided children value.
203
291
  */
204
- declare function childrenToElements(children: ReactNode): ReactElement[];
292
+ declare function useUniqueCallbackChild<TArguments extends unknown[] = [], TResult = ReactNode>(children: CallbackChildren<TArguments, TResult>, options?: ValidationOptions): CallbackChild<TArguments, TResult>;
205
293
 
206
294
  /**
207
- * Determines whether a React element exactly matches the provided element or component type.
295
+ * Returns the only direct child element whose React element type exactly matches the provided type, or throws when the match is not unique.
208
296
  *
209
- * @param element The React element to compare.
210
- * @param type The element or component type to match.
211
- * @returns `true` when the element's type exactly matches the provided type; otherwise `false`.
297
+ * @param children The React children value to inspect.
298
+ * @param type The element or component type to match against each direct child element.
299
+ * @param options Optional reporting metadata used to derive the thrown validation message.
300
+ * @returns The only direct child element whose type matches the provided element type.
212
301
  */
213
- declare function isElementOfType<T extends ElementType>(element: ReactElement, type: T): element is ElementOfType<T>;
302
+ declare function useUniqueChildByType<T extends ElementType>(children: ReactNode, type: T, options?: ValidationOptions): ElementOfType<T>;
214
303
 
215
304
  /**
216
- * Determines whether a React node is a valid React element.
305
+ * Returns the only direct child element that satisfies the provided predicate, or throws when the match is not unique.
217
306
  *
218
- * @param node The React node to check.
219
- * @returns `true` when the node is a valid React element; otherwise `false`.
307
+ * @param children The React children value to inspect.
308
+ * @param predicate A predicate that is called with each direct child element to determine whether it matches.
309
+ * @param options Optional reporting metadata used to derive the thrown validation message.
310
+ * @returns The only direct child element that satisfies the provided predicate.
220
311
  */
221
- declare function isReactElement(node: ReactNode): node is ReactElement;
312
+ declare function useUniqueChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: ValidationOptions): T;
313
+ declare function useUniqueChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: ValidationOptions): ReactElement;
222
314
 
223
- export { type ChildrenCountBounds, type ElementOfType, type ValidationOptions, childrenToElements, isElementOfType, isReactElement, useBoundedChildrenByType, useBoundedChildrenMatching, useChildByType, useChildMatching, useChildrenByType, useChildrenMatching, useExactChildrenByType, useExactChildrenMatching, useHasChildMatching, useMaximumChildrenByType, useMaximumChildrenMatching, useMinimumChildrenByType, useMinimumChildrenMatching, useRequiredChildByType, useRequiredChildMatching };
315
+ export { type CallbackChild, type CallbackChildren, type ChildrenCountBounds, type ElementOfType, type QueryOptions, type TraversalOptions, type ValidationOptions, useBoundedChildrenByType, useBoundedChildrenMatching, useCallbackChild, useChildByType, useChildMatching, useChildrenByType, useChildrenMatching, useExactChildrenByType, useExactChildrenMatching, useHasChildMatching, useMaximumChildrenByType, useMaximumChildrenMatching, useMinimumChildrenByType, useMinimumChildrenMatching, useOptionalCallbackChild, useOptionalChildByType, useOptionalChildMatching, useRequiredCallbackChild, useRequiredChildByType, useRequiredChildMatching, useUniqueCallbackChild, useUniqueChildByType, useUniqueChildMatching };