react-children-hooks 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -14,16 +14,47 @@ type ChildrenCountBounds = {
      */
     maximum: number;
 };
+/**
+ * Optional traversal bounds used by the element-based query and validation hooks.
+ */
+type TraversalOptions = {
+    /**
+     * The minimum inclusive child depth to include in results, where `0` represents direct children.
+     */
+    depth?: number;
+    /**
+     * The maximum inclusive child depth to include in results, where `0` represents direct children.
+     */
+    maximumDepth?: number;
+};
+/**
+ * Optional traversal metadata used by the element-based query hooks.
+ */
+type QueryOptions = TraversalOptions;
 /**
  * Represents a React element whose props and element type are narrowed to the provided React element type.
  *
  * @typeParam T The React element type used to narrow the element's props and type.
  */
 type ElementOfType<T extends React.ElementType> = React.ReactElement<React.ComponentProps<T>, T>;
+/**
+ * A callback child, also known as a render-prop child.
+ *
+ * @typeParam TArguments The positional argument tuple accepted by the callback.
+ * @typeParam TResult The value returned by the callback.
+ */
+type CallbackChild<TArguments extends unknown[] = [], TResult = React.ReactNode> = (...args: TArguments) => TResult;
+/**
+ * A direct-children value that may include callback children alongside regular React children.
+ *
+ * @typeParam TArguments The positional argument tuple accepted by callback children.
+ * @typeParam TResult The value returned by callback children.
+ */
+type CallbackChildren<TArguments extends unknown[] = [], TResult = React.ReactNode> = React.ReactNode | CallbackChild<TArguments, TResult> | readonly CallbackChildren<TArguments, TResult>[];
 /**
  * Optional reporting metadata used by the validation hooks to derive thrown validation messages.
  */
-type ValidationOptions = {
+type ValidationMessageOptions = {
     /**
      * An optional consumer-defined trace code that is prefixed to the thrown validation message.
      */
@@ -33,25 +64,39 @@ type ValidationOptions = {
      */
     childName?: string;
 };
+/**
+ * Optional reporting and traversal metadata used by the validation hooks.
+ */
+type ValidationOptions = ValidationMessageOptions & TraversalOptions;
 
 /**
  * Returns the first direct child element whose React element type exactly matches the provided type.
  *
  * @param children The React children value to inspect.
  * @param type The element or component type to match against each direct child element.
+ * @param options Optional query metadata used to configure how child elements are inspected.
  * @returns The first direct child element whose type matches the provided element type, or `null` when no match is found.
  */
-declare function useChildByType<T extends ElementType>(children: ReactNode, type: T): ElementOfType<T> | null;
+declare function useChildByType<T extends ElementType>(children: ReactNode, type: T, options?: QueryOptions): ElementOfType<T> | null;
+
+/**
+ * Returns the first direct callback child from the provided children value.
+ *
+ * @param children The direct children value to inspect.
+ * @returns The first direct callback child, or `null` when no callback child is found.
+ */
+declare function useCallbackChild<TArguments extends unknown[] = [], TResult = ReactNode>(children: CallbackChildren<TArguments, TResult>): CallbackChild<TArguments, TResult> | null;
 
 /**
  * Returns the first direct child element that satisfies the provided predicate.
  *
  * @param children The React children value to inspect.
  * @param predicate A predicate that is called with each direct child element to determine whether it matches.
+ * @param options Optional query metadata used to configure how child elements are inspected.
  * @returns The first direct child element that satisfies the provided predicate, or `null` when no match is found.
  */
-declare function useChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): T | null;
-declare function useChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean): ReactElement | null;
+declare function useChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: QueryOptions): T | null;
+declare function useChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: QueryOptions): ReactElement | null;
 
 /**
  * Returns the direct child elements whose React element type exactly matches the provided type, or throws when the count falls outside the inclusive bounds.
@@ -81,19 +126,21 @@ declare function useBoundedChildrenMatching(children: ReactNode, predicate: (ele
  *
  * @param children The React children value to inspect.
  * @param type The element or component type to match against each direct child element.
+ * @param options Optional query metadata used to configure how child elements are inspected.
  * @returns An array of direct child elements whose type matches the provided element type.
  */
-declare function useChildrenByType<T extends ElementType>(children: ReactNode, type: T): ElementOfType<T>[];
+declare function useChildrenByType<T extends ElementType>(children: ReactNode, type: T, options?: QueryOptions): ElementOfType<T>[];
 
 /**
  * Returns the direct child elements that satisfy the provided predicate.
  *
  * @param children The React children value to inspect.
  * @param predicate A predicate that is called with each direct child element to determine whether it should be included in the result.
+ * @param options Optional query metadata used to configure how child elements are inspected.
  * @returns An array of direct child elements that satisfy the provided predicate.
  */
-declare function useChildrenMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): T[];
-declare function useChildrenMatching(children: ReactNode, predicate: (element: ReactElement) => boolean): ReactElement[];
+declare function useChildrenMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: QueryOptions): T[];
+declare function useChildrenMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: QueryOptions): ReactElement[];
 
 /**
  * Returns the direct child elements whose React element type exactly matches the provided type, or throws when the exact count is not met.
@@ -123,10 +170,11 @@ declare function useExactChildrenMatching(children: ReactNode, predicate: (eleme
  *
  * @param children The React children value to inspect.
  * @param predicate A predicate that is called with each direct child element to determine whether it matches.
+ * @param options Optional query metadata used to configure how child elements are inspected.
  * @returns `true` when at least one direct child element satisfies the provided predicate; otherwise `false`.
  */
-declare function useHasChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): boolean;
-declare function useHasChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean): boolean;
+declare function useHasChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: QueryOptions): boolean;
+declare function useHasChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: QueryOptions): boolean;
 
 /**
  * Returns the direct child elements whose React element type exactly matches the provided type, or throws when more than the maximum count are found.
@@ -174,6 +222,36 @@ declare function useMinimumChildrenByType<T extends ElementType>(children: React
 declare function useMinimumChildrenMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, minimumCount: number, options?: ValidationOptions): T[];
 declare function useMinimumChildrenMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, minimumCount: number, options?: ValidationOptions): ReactElement[];
 
+/**
+ * Returns the optional direct callback child from the provided children value, or throws when more than one is found.
+ *
+ * @param children The direct children value to inspect.
+ * @param options Optional reporting metadata used to derive the thrown validation message.
+ * @returns The optional direct callback child from the provided children value, or `null` when none is found.
+ */
+declare function useOptionalCallbackChild<TArguments extends unknown[] = [], TResult = ReactNode>(children: CallbackChildren<TArguments, TResult>, options?: ValidationOptions): CallbackChild<TArguments, TResult> | null;
+
+/**
+ * Returns the optional direct child element whose React element type exactly matches the provided type, or throws when more than one match is found.
+ *
+ * @param children The React children value to inspect.
+ * @param type The element or component type to match against each direct child element.
+ * @param options Optional reporting metadata used to derive the thrown validation message.
+ * @returns The optional direct child element whose type matches the provided element type, or `null` when no match is found.
+ */
+declare function useOptionalChildByType<T extends ElementType>(children: ReactNode, type: T, options?: ValidationOptions): ElementOfType<T> | null;
+
+/**
+ * Returns the optional direct child element that satisfies the provided predicate, or throws when more than one match is found.
+ *
+ * @param children The React children value to inspect.
+ * @param predicate A predicate that is called with each direct child element to determine whether it matches.
+ * @param options Optional reporting metadata used to derive the thrown validation message.
+ * @returns The optional direct child element that satisfies the provided predicate, or `null` when no match is found.
+ */
+declare function useOptionalChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: ValidationOptions): T | null;
+declare function useOptionalChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: ValidationOptions): ReactElement | null;
+
 /**
  * Returns the first direct child element whose React element type exactly matches the provided type, or throws when no match is found.
  *
@@ -184,6 +262,15 @@ declare function useMinimumChildrenMatching(children: ReactNode, predicate: (ele
  */
 declare function useRequiredChildByType<T extends ElementType>(children: ReactNode, type: T, options?: ValidationOptions): ElementOfType<T>;
 
+/**
+ * Returns the first direct callback child from the provided children value, or throws when none is found.
+ *
+ * @param children The direct children value to inspect.
+ * @param options Optional reporting metadata used to derive the thrown validation message.
+ * @returns The first direct callback child from the provided children value.
+ */
+declare function useRequiredCallbackChild<TArguments extends unknown[] = [], TResult = ReactNode>(children: CallbackChildren<TArguments, TResult>, options?: ValidationOptions): CallbackChild<TArguments, TResult>;
+
 /**
  * Returns the first direct child element that satisfies the provided predicate, or throws when no match is found.
  *
@@ -196,28 +283,33 @@ declare function useRequiredChildMatching<T extends ReactElement>(children: Reac
 declare function useRequiredChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: ValidationOptions): ReactElement;
 
 /**
- * Normalizes a React children value into an array containing only valid direct child elements.
+ * Returns the only direct callback child from the provided children value, or throws when the match is not unique.
  *
- * @param children The React children value to normalize.
- * @returns An array of valid React elements from the provided direct children.
+ * @param children The direct children value to inspect.
+ * @param options Optional reporting metadata used to derive the thrown validation message.
+ * @returns The only direct callback child from the provided children value.
  */
-declare function childrenToElements(children: ReactNode): ReactElement[];
+declare function useUniqueCallbackChild<TArguments extends unknown[] = [], TResult = ReactNode>(children: CallbackChildren<TArguments, TResult>, options?: ValidationOptions): CallbackChild<TArguments, TResult>;
 
 /**
- * Determines whether a React element exactly matches the provided element or component type.
+ * Returns the only direct child element whose React element type exactly matches the provided type, or throws when the match is not unique.
  *
- * @param element The React element to compare.
- * @param type The element or component type to match.
- * @returns `true` when the element's type exactly matches the provided type; otherwise `false`.
+ * @param children The React children value to inspect.
+ * @param type The element or component type to match against each direct child element.
+ * @param options Optional reporting metadata used to derive the thrown validation message.
+ * @returns The only direct child element whose type matches the provided element type.
  */
-declare function isElementOfType<T extends ElementType>(element: ReactElement, type: T): element is ElementOfType<T>;
+declare function useUniqueChildByType<T extends ElementType>(children: ReactNode, type: T, options?: ValidationOptions): ElementOfType<T>;
 
 /**
- * Determines whether a React node is a valid React element.
+ * Returns the only direct child element that satisfies the provided predicate, or throws when the match is not unique.
  *
- * @param node The React node to check.
- * @returns `true` when the node is a valid React element; otherwise `false`.
+ * @param children The React children value to inspect.
+ * @param predicate A predicate that is called with each direct child element to determine whether it matches.
+ * @param options Optional reporting metadata used to derive the thrown validation message.
+ * @returns The only direct child element that satisfies the provided predicate.
  */
-declare function isReactElement(node: ReactNode): node is ReactElement;
+declare function useUniqueChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: ValidationOptions): T;
+declare function useUniqueChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: ValidationOptions): ReactElement;
 
-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 };
+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 };

package/dist/index.js

@@ -15,54 +15,128 @@ function isReactElement(node) {
   return isValidElement(node);
 }
 
-// src/childrenToElements.ts
-function childrenToElements(children) {
-  return Children.toArray(children).filter(isReactElement);
-}
-
-// src/useChildMatching.ts
-function useChildMatching(children, predicate) {
-  return useMemo(
-    () => childrenToElements(children).find(predicate) ?? null,
-    [children, predicate]
-  );
-}
-
-// src/useChildByType.ts
-function useChildByType(children, type) {
-  return useChildMatching(
-    children,
-    (element) => isElementOfType(element, type)
-  );
-}
-
 // src/reporter.ts
 import { createReporter } from "runtime-reporter";
-var messages = {
+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.",
+  OPTIONAL_CALLBACK_CHILD_FAILED: "{{ traceCodePrefix }}Optional callback child validation failed{{ childNameSegment }} because {{ actualCount }} direct callback children were found; expected at most 1.",
+  UNIQUE_CALLBACK_CHILD_FAILED: "{{ traceCodePrefix }}Unique callback child validation failed{{ childNameSegment }} because {{ actualCount }} direct callback children were found; expected exactly 1.",
   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/useChildrenMatching.ts
+// src/childrenToElements.ts
+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, options) {
+  return useMemo(
+    () => childrenToElements(children, options).find(predicate) ?? null,
+    [children, options, predicate]
+  );
+}
+var useChildMatching_default = useChildMatching;
+
+// src/useChildByType.ts
+function useChildByType(children, type, options) {
+  return useChildMatching_default(
+    children,
+    (element) => isElementOfType(element, type),
+    options
+  );
+}
+
+// src/useCallbackChild.ts
 import { useMemo as useMemo2 } from "react";
-function useChildrenMatching(children, predicate) {
+
+// src/callbackChildrenToArray.ts
+function callbackChildrenToArray(children) {
+  if (typeof children === "function") {
+    return [children];
+  }
+  if (!Array.isArray(children)) {
+    return [];
+  }
+  return children.flatMap(
+    (child) => callbackChildrenToArray(child)
+  );
+}
+
+// src/useCallbackChild.ts
+function useCallbackChild(children) {
   return useMemo2(
-    () => childrenToElements(children).filter(predicate),
-    [children, predicate]
+    () => callbackChildrenToArray(children)[0] ?? null,
+    [children]
+  );
+}
+
+// src/useChildrenMatching.ts
+import { useMemo as useMemo3 } from "react";
+function useChildrenMatching(children, predicate, options) {
+  return useMemo3(
+    () => childrenToElements(children, options).filter(predicate),
+    [children, options, predicate]
   );
 }
+var useChildrenMatching_default = useChildrenMatching;
 
 // src/useBoundedChildrenMatching.ts
 function useBoundedChildrenMatching(children, predicate, bounds, options) {
-  const matchingChildren = useChildrenMatching(children, predicate);
+  const matchingChildren = useChildrenMatching_default(children, predicate, options);
   if (matchingChildren.length >= bounds.minimum && matchingChildren.length <= bounds.maximum) {
     return matchingChildren;
   }
@@ -75,10 +149,11 @@ function useBoundedChildrenMatching(children, predicate, bounds, options) {
     maximumCount: bounds.maximum
   });
 }
+var useBoundedChildrenMatching_default = useBoundedChildrenMatching;
 
 // src/useBoundedChildrenByType.ts
 function useBoundedChildrenByType(children, type, bounds, options) {
-  return useBoundedChildrenMatching(
+  return useBoundedChildrenMatching_default(
     children,
     (element) => isElementOfType(element, type),
     bounds,
@@ -87,16 +162,17 @@ function useBoundedChildrenByType(children, type, bounds, options) {
 }
 
 // src/useChildrenByType.ts
-function useChildrenByType(children, type) {
-  return useChildrenMatching(
+function useChildrenByType(children, type, options) {
+  return useChildrenMatching_default(
     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_default(children, predicate, options);
   if (matchingChildren.length === exactCount) {
     return matchingChildren;
   }
@@ -108,10 +184,11 @@ function useExactChildrenMatching(children, predicate, exactCount, options) {
     exactCount
   });
 }
+var useExactChildrenMatching_default = useExactChildrenMatching;
 
 // src/useExactChildrenByType.ts
 function useExactChildrenByType(children, type, exactCount, options) {
-  return useExactChildrenMatching(
+  return useExactChildrenMatching_default(
     children,
     (element) => isElementOfType(element, type),
     exactCount,
@@ -120,17 +197,18 @@ 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]
   );
 }
+var useHasChildMatching_default = useHasChildMatching;
 
 // src/useMaximumChildrenMatching.ts
 function useMaximumChildrenMatching(children, predicate, maximumCount, options) {
-  const matchingChildren = useChildrenMatching(children, predicate);
+  const matchingChildren = useChildrenMatching_default(children, predicate, options);
   if (matchingChildren.length <= maximumCount) {
     return matchingChildren;
   }
@@ -142,10 +220,11 @@ function useMaximumChildrenMatching(children, predicate, maximumCount, options)
     maximumCount
   });
 }
+var useMaximumChildrenMatching_default = useMaximumChildrenMatching;
 
 // src/useMaximumChildrenByType.ts
 function useMaximumChildrenByType(children, type, maximumCount, options) {
-  return useMaximumChildrenMatching(
+  return useMaximumChildrenMatching_default(
     children,
     (element) => isElementOfType(element, type),
     maximumCount,
@@ -155,7 +234,7 @@ function useMaximumChildrenByType(children, type, maximumCount, options) {
 
 // src/useMinimumChildrenMatching.ts
 function useMinimumChildrenMatching(children, predicate, minimumCount, options) {
-  const matchingChildren = useChildrenMatching(children, predicate);
+  const matchingChildren = useChildrenMatching_default(children, predicate, options);
   if (matchingChildren.length >= minimumCount) {
     return matchingChildren;
   }
@@ -167,10 +246,11 @@ function useMinimumChildrenMatching(children, predicate, minimumCount, options)
     minimumCount
   });
 }
+var useMinimumChildrenMatching_default = useMinimumChildrenMatching;
 
 // src/useMinimumChildrenByType.ts
 function useMinimumChildrenByType(children, type, minimumCount, options) {
-  return useMinimumChildrenMatching(
+  return useMinimumChildrenMatching_default(
     children,
     (element) => isElementOfType(element, type),
     minimumCount,
@@ -178,9 +258,50 @@ function useMinimumChildrenByType(children, type, minimumCount, options) {
   );
 }
 
+// src/useOptionalCallbackChild.ts
+import { useMemo as useMemo5 } from "react";
+function useOptionalCallbackChild(children, options) {
+  const callbackChildren = useMemo5(
+    () => callbackChildrenToArray(children),
+    [children]
+  );
+  if (callbackChildren.length <= 1) {
+    return callbackChildren[0] ?? null;
+  }
+  return reporter_default.fail("OPTIONAL_CALLBACK_CHILD_FAILED", {
+    traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : "",
+    childNameSegment: options?.childName ? ` for ${options.childName}` : "",
+    actualCount: callbackChildren.length
+  });
+}
+
+// src/useOptionalChildMatching.ts
+function useOptionalChildMatching(children, predicate, options) {
+  const matchingChildren = useChildrenMatching_default(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"
+  });
+}
+var useOptionalChildMatching_default = useOptionalChildMatching;
+
+// src/useOptionalChildByType.ts
+function useOptionalChildByType(children, type, options) {
+  return useOptionalChildMatching_default(
+    children,
+    (element) => isElementOfType(element, type),
+    options
+  );
+}
+
 // src/useRequiredChildMatching.ts
 function useRequiredChildMatching(children, predicate, options) {
-  const child = useChildMatching(children, predicate);
+  const child = useChildMatching_default(children, predicate, options);
   if (child !== null) {
     return child;
   }
@@ -189,33 +310,93 @@ function useRequiredChildMatching(children, predicate, options) {
     childNameSegment: options?.childName ? ` for ${options.childName}` : ""
   });
 }
+var useRequiredChildMatching_default = useRequiredChildMatching;
 
 // src/useRequiredChildByType.ts
 function useRequiredChildByType(children, type, options) {
-  return useRequiredChildMatching(
+  return useRequiredChildMatching_default(
+    children,
+    (element) => isElementOfType(element, type),
+    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/useUniqueCallbackChild.ts
+import { useMemo as useMemo6 } from "react";
+function useUniqueCallbackChild(children, options) {
+  const callbackChildren = useMemo6(
+    () => callbackChildrenToArray(children),
+    [children]
+  );
+  if (callbackChildren.length === 1) {
+    return callbackChildren[0];
+  }
+  return reporter_default.fail("UNIQUE_CALLBACK_CHILD_FAILED", {
+    traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : "",
+    childNameSegment: options?.childName ? ` for ${options.childName}` : "",
+    actualCount: callbackChildren.length
+  });
+}
+
+// src/useUniqueChildMatching.ts
+function useUniqueChildMatching(children, predicate, options) {
+  const matchingChildren = useChildrenMatching_default(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"
+  });
+}
+var useUniqueChildMatching_default = useUniqueChildMatching;
+
+// src/useUniqueChildByType.ts
+function useUniqueChildByType(children, type, options) {
+  return useUniqueChildMatching_default(
     children,
     (element) => isElementOfType(element, type),
     options
   );
 }
 export {
-  childrenToElements,
-  isElementOfType,
-  isReactElement,
   useBoundedChildrenByType,
-  useBoundedChildrenMatching,
+  useBoundedChildrenMatching_default as useBoundedChildrenMatching,
+  useCallbackChild,
   useChildByType,
-  useChildMatching,
+  useChildMatching_default as useChildMatching,
   useChildrenByType,
-  useChildrenMatching,
+  useChildrenMatching_default as useChildrenMatching,
   useExactChildrenByType,
-  useExactChildrenMatching,
-  useHasChildMatching,
+  useExactChildrenMatching_default as useExactChildrenMatching,
+  useHasChildMatching_default as useHasChildMatching,
   useMaximumChildrenByType,
-  useMaximumChildrenMatching,
+  useMaximumChildrenMatching_default as useMaximumChildrenMatching,
   useMinimumChildrenByType,
-  useMinimumChildrenMatching,
+  useMinimumChildrenMatching_default as useMinimumChildrenMatching,
+  useOptionalCallbackChild,
+  useOptionalChildByType,
+  useOptionalChildMatching_default as useOptionalChildMatching,
+  useRequiredCallbackChild,
   useRequiredChildByType,
-  useRequiredChildMatching
+  useRequiredChildMatching_default as useRequiredChildMatching,
+  useUniqueCallbackChild,
+  useUniqueChildByType,
+  useUniqueChildMatching_default as useUniqueChildMatching
 };
 //# sourceMappingURL=index.js.map