react-children-hooks 0.3.0 → 0.4.0

package/dist/index.js

@@ -15,54 +15,123 @@ function isReactElement(node) {
   return isValidElement(node);
 }
 
+// src/reporter.ts
+import { createReporter } from "runtime-reporter";
+var validationMessages = {
+  OPTIONAL_CHILD_MATCHING_PREDICATE_FAILED: "{{ traceCodePrefix }}Optional child validation failed{{ childNameSegment }} because {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected at most 1.",
+  UNIQUE_CHILD_MATCHING_PREDICATE_FAILED: "{{ traceCodePrefix }}Unique child validation failed{{ childNameSegment }} because {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected exactly 1.",
+  REQUIRED_CHILD_MATCHING_PREDICATE_FAILED: "{{ traceCodePrefix }}Required child validation failed{{ childNameSegment }} because no direct child satisfied the provided predicate.",
+  REQUIRED_CALLBACK_CHILD_FAILED: "{{ traceCodePrefix }}Required callback child validation failed{{ childNameSegment }} because no direct callback child was found.",
+  MINIMUM_CHILDREN_MATCHING_PREDICATE_FAILED: "{{ traceCodePrefix }}Minimum children validation failed{{ childNameSegment }} because only {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected at least {{ minimumCount }}.",
+  MAXIMUM_CHILDREN_MATCHING_PREDICATE_FAILED: "{{ traceCodePrefix }}Maximum children validation failed{{ childNameSegment }} because {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected at most {{ maximumCount }}.",
+  EXACT_CHILDREN_MATCHING_PREDICATE_FAILED: "{{ traceCodePrefix }}Exact children validation failed{{ childNameSegment }} because {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected exactly {{ exactCount }}.",
+  BOUNDED_CHILDREN_MATCHING_PREDICATE_FAILED: "{{ traceCodePrefix }}Bounded children validation failed{{ childNameSegment }} because {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected between {{ minimumCount }} and {{ maximumCount }} inclusive."
+};
+var publicMessages = {
+  RCH001: '[RCH001] Traversal option "depth" must be a non-negative integer.',
+  RCH002: '[RCH002] Traversal option "maximumDepth" must be a non-negative integer.',
+  RCH003: '[RCH003] Traversal option "depth" cannot be greater than "maximumDepth".'
+};
+var messages = {
+  ...validationMessages,
+  ...publicMessages
+};
+var reporter = createReporter(
+  process.env.NODE_ENV === "production" ? {} : messages,
+  { formatMessage: (message) => message }
+);
+var reporter_default = reporter;
+
 // src/childrenToElements.ts
-function childrenToElements(children) {
-  return Children.toArray(children).filter(isReactElement);
+function getTraversalBounds(options) {
+  const depth = options?.depth ?? 0;
+  const maximumDepth = options?.maximumDepth ?? 0;
+  if (!Number.isInteger(depth) || depth < 0) {
+    return reporter_default.fail("RCH001");
+  }
+  if (!Number.isInteger(maximumDepth) || maximumDepth < 0) {
+    return reporter_default.fail("RCH002");
+  }
+  if (depth > maximumDepth) {
+    return reporter_default.fail("RCH003");
+  }
+  return { depth, maximumDepth };
+}
+function collectElementsAtDepth(children, currentDepth, depth, maximumDepth) {
+  const directElements = Children.toArray(children).filter(isReactElement);
+  let elements = [];
+  if (currentDepth >= depth && currentDepth <= maximumDepth) {
+    elements = [...directElements];
+  }
+  for (const element of directElements) {
+    const elementProps = element.props;
+    const elementsAtDepth = collectElementsAtDepth(
+      elementProps.children,
+      currentDepth + 1,
+      depth,
+      maximumDepth
+    );
+    elements.push(...elementsAtDepth);
+  }
+  return elements;
+}
+function childrenToElements(children, options) {
+  const { depth, maximumDepth } = getTraversalBounds(options);
+  return collectElementsAtDepth(children, 0, depth, maximumDepth);
 }
 
 // src/useChildMatching.ts
-function useChildMatching(children, predicate) {
+function useChildMatching(children, predicate, options) {
   return useMemo(
-    () => childrenToElements(children).find(predicate) ?? null,
-    [children, predicate]
+    () => childrenToElements(children, options).find(predicate) ?? null,
+    [children, options, predicate]
   );
 }
 
 // src/useChildByType.ts
-function useChildByType(children, type) {
+function useChildByType(children, type, options) {
   return useChildMatching(
     children,
-    (element) => isElementOfType(element, type)
+    (element) => isElementOfType(element, type),
+    options
   );
 }
 
-// src/reporter.ts
-import { createReporter } from "runtime-reporter";
-var messages = {
-  REQUIRED_CHILD_MATCHING_PREDICATE_FAILED: "{{ traceCodePrefix }}Required child validation failed{{ childNameSegment }} because no direct child satisfied the provided predicate.",
-  MINIMUM_CHILDREN_MATCHING_PREDICATE_FAILED: "{{ traceCodePrefix }}Minimum children validation failed{{ childNameSegment }} because only {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected at least {{ minimumCount }}.",
-  MAXIMUM_CHILDREN_MATCHING_PREDICATE_FAILED: "{{ traceCodePrefix }}Maximum children validation failed{{ childNameSegment }} because {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected at most {{ maximumCount }}.",
-  EXACT_CHILDREN_MATCHING_PREDICATE_FAILED: "{{ traceCodePrefix }}Exact children validation failed{{ childNameSegment }} because {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected exactly {{ exactCount }}.",
-  BOUNDED_CHILDREN_MATCHING_PREDICATE_FAILED: "{{ traceCodePrefix }}Bounded children validation failed{{ childNameSegment }} because {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected between {{ minimumCount }} and {{ maximumCount }} inclusive."
-};
-var reporter = createReporter(
-  process.env.NODE_ENV === "production" ? {} : messages,
-  { formatMessage: (message) => message }
-);
-var reporter_default = reporter;
+// src/useCallbackChild.ts
+import { useMemo as useMemo2 } from "react";
+function findFirstCallbackChild(children) {
+  if (typeof children === "function") {
+    return children;
+  }
+  if (!Array.isArray(children)) {
+    return null;
+  }
+  for (const child of children) {
+    const callbackChild = findFirstCallbackChild(
+      child
+    );
+    if (callbackChild) {
+      return callbackChild;
+    }
+  }
+  return null;
+}
+function useCallbackChild(children) {
+  return useMemo2(() => findFirstCallbackChild(children), [children]);
+}
 
 // src/useChildrenMatching.ts
-import { useMemo as useMemo2 } from "react";
-function useChildrenMatching(children, predicate) {
-  return useMemo2(
-    () => childrenToElements(children).filter(predicate),
-    [children, predicate]
+import { useMemo as useMemo3 } from "react";
+function useChildrenMatching(children, predicate, options) {
+  return useMemo3(
+    () => childrenToElements(children, options).filter(predicate),
+    [children, options, predicate]
   );
 }
 
 // src/useBoundedChildrenMatching.ts
 function useBoundedChildrenMatching(children, predicate, bounds, options) {
-  const matchingChildren = useChildrenMatching(children, predicate);
+  const matchingChildren = useChildrenMatching(children, predicate, options);
   if (matchingChildren.length >= bounds.minimum && matchingChildren.length <= bounds.maximum) {
     return matchingChildren;
   }
@@ -87,16 +156,17 @@ function useBoundedChildrenByType(children, type, bounds, options) {
 }
 
 // src/useChildrenByType.ts
-function useChildrenByType(children, type) {
+function useChildrenByType(children, type, options) {
   return useChildrenMatching(
     children,
-    (element) => isElementOfType(element, type)
+    (element) => isElementOfType(element, type),
+    options
   );
 }
 
 // src/useExactChildrenMatching.ts
 function useExactChildrenMatching(children, predicate, exactCount, options) {
-  const matchingChildren = useChildrenMatching(children, predicate);
+  const matchingChildren = useChildrenMatching(children, predicate, options);
   if (matchingChildren.length === exactCount) {
     return matchingChildren;
   }
@@ -120,17 +190,17 @@ function useExactChildrenByType(children, type, exactCount, options) {
 }
 
 // src/useHasChildMatching.ts
-import { useMemo as useMemo3 } from "react";
-function useHasChildMatching(children, predicate) {
-  return useMemo3(
-    () => childrenToElements(children).some(predicate),
-    [children, predicate]
+import { useMemo as useMemo4 } from "react";
+function useHasChildMatching(children, predicate, options) {
+  return useMemo4(
+    () => childrenToElements(children, options).some(predicate),
+    [children, options, predicate]
   );
 }
 
 // src/useMaximumChildrenMatching.ts
 function useMaximumChildrenMatching(children, predicate, maximumCount, options) {
-  const matchingChildren = useChildrenMatching(children, predicate);
+  const matchingChildren = useChildrenMatching(children, predicate, options);
   if (matchingChildren.length <= maximumCount) {
     return matchingChildren;
   }
@@ -155,7 +225,7 @@ function useMaximumChildrenByType(children, type, maximumCount, options) {
 
 // src/useMinimumChildrenMatching.ts
 function useMinimumChildrenMatching(children, predicate, minimumCount, options) {
-  const matchingChildren = useChildrenMatching(children, predicate);
+  const matchingChildren = useChildrenMatching(children, predicate, options);
   if (matchingChildren.length >= minimumCount) {
     return matchingChildren;
   }
@@ -178,9 +248,32 @@ function useMinimumChildrenByType(children, type, minimumCount, options) {
   );
 }
 
+// src/useOptionalChildMatching.ts
+function useOptionalChildMatching(children, predicate, options) {
+  const matchingChildren = useChildrenMatching(children, predicate, options);
+  if (matchingChildren.length <= 1) {
+    return matchingChildren[0] ?? null;
+  }
+  return reporter_default.fail("OPTIONAL_CHILD_MATCHING_PREDICATE_FAILED", {
+    traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : "",
+    childNameSegment: options?.childName ? ` for ${options.childName}` : "",
+    actualCount: matchingChildren.length,
+    actualCountPluralSuffix: matchingChildren.length === 1 ? "" : "ren"
+  });
+}
+
+// src/useOptionalChildByType.ts
+function useOptionalChildByType(children, type, options) {
+  return useOptionalChildMatching(
+    children,
+    (element) => isElementOfType(element, type),
+    options
+  );
+}
+
 // src/useRequiredChildMatching.ts
 function useRequiredChildMatching(children, predicate, options) {
-  const child = useChildMatching(children, predicate);
+  const child = useChildMatching(children, predicate, options);
   if (child !== null) {
     return child;
   }
@@ -198,12 +291,49 @@ function useRequiredChildByType(children, type, options) {
     options
   );
 }
+
+// src/useRequiredCallbackChild.ts
+import "react";
+function useRequiredCallbackChild(children, options) {
+  const callbackChild = useCallbackChild(children);
+  if (callbackChild !== null) {
+    return callbackChild;
+  }
+  return reporter_default.fail("REQUIRED_CALLBACK_CHILD_FAILED", {
+    traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : "",
+    childNameSegment: options?.childName ? ` for ${options.childName}` : ""
+  });
+}
+
+// src/useUniqueChildMatching.ts
+function useUniqueChildMatching(children, predicate, options) {
+  const matchingChildren = useChildrenMatching(children, predicate, options);
+  if (matchingChildren.length === 1) {
+    return matchingChildren[0];
+  }
+  return reporter_default.fail("UNIQUE_CHILD_MATCHING_PREDICATE_FAILED", {
+    traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : "",
+    childNameSegment: options?.childName ? ` for ${options.childName}` : "",
+    actualCount: matchingChildren.length,
+    actualCountPluralSuffix: matchingChildren.length === 1 ? "" : "ren"
+  });
+}
+
+// src/useUniqueChildByType.ts
+function useUniqueChildByType(children, type, options) {
+  return useUniqueChildMatching(
+    children,
+    (element) => isElementOfType(element, type),
+    options
+  );
+}
 export {
   childrenToElements,
   isElementOfType,
   isReactElement,
   useBoundedChildrenByType,
   useBoundedChildrenMatching,
+  useCallbackChild,
   useChildByType,
   useChildMatching,
   useChildrenByType,
@@ -215,7 +345,12 @@ export {
   useMaximumChildrenMatching,
   useMinimumChildrenByType,
   useMinimumChildrenMatching,
+  useOptionalChildByType,
+  useOptionalChildMatching,
+  useRequiredCallbackChild,
   useRequiredChildByType,
-  useRequiredChildMatching
+  useRequiredChildMatching,
+  useUniqueChildByType,
+  useUniqueChildMatching
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../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":["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":["useMemo","useMemo","useMemo","useMemo"]}
+{"version":3,"sources":["../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":["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":"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","names":["useMemo","useMemo","useMemo","useMemo","useMemo"]}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "react-children-hooks",
-    "version": "0.3.0",
+    "version": "0.4.0",
     "description": "React hooks for inspecting, traversing, querying, and validating props.children.",
     "keywords": [
         "react",
@@ -86,6 +86,6 @@
         "vitest": "^3.1.4"
     },
     "dependencies": {
-        "runtime-reporter": "^0.7.0"
+        "runtime-reporter": "^0.9.0"
     }
 }