react-children-hooks 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -222,6 +222,15 @@ 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.
  *
@@ -273,6 +282,15 @@ declare function useRequiredCallbackChild<TArguments extends unknown[] = [], TRe
 declare function useRequiredChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: ValidationOptions): T;
 declare function useRequiredChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: ValidationOptions): ReactElement;
 
+/**
+ * Returns the only direct callback child from the provided children value, or throws when the match is not unique.
+ *
+ * @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 useUniqueCallbackChild<TArguments extends unknown[] = [], TResult = ReactNode>(children: CallbackChildren<TArguments, TResult>, options?: ValidationOptions): CallbackChild<TArguments, TResult>;
+
 /**
  * Returns the only direct child element whose React element type exactly matches the provided type, or throws when the match is not unique.
  *
@@ -294,30 +312,4 @@ declare function useUniqueChildByType<T extends ElementType>(children: ReactNode
 declare function useUniqueChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: ValidationOptions): T;
 declare function useUniqueChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: ValidationOptions): ReactElement;
 
-/**
- * Normalizes a React children value into an array containing valid child elements within the configured depth range.
- *
- * @param children The React children value to normalize.
- * @param options Optional traversal bounds that control which child depths are included.
- * @returns An array of valid React elements from the provided child depths.
- */
-declare function childrenToElements(children: ReactNode, options?: TraversalOptions): ReactElement[];
-
-/**
- * Determines whether a React element exactly matches the provided element or component type.
- *
- * @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`.
- */
-declare function isElementOfType<T extends ElementType>(element: ReactElement, type: T): element is ElementOfType<T>;
-
-/**
- * Determines whether a React node is a valid React element.
- *
- * @param node The React node to check.
- * @returns `true` when the node is a valid React element; otherwise `false`.
- */
-declare function isReactElement(node: ReactNode): node is ReactElement;
-
-export { type CallbackChild, type CallbackChildren, type ChildrenCountBounds, type ElementOfType, type QueryOptions, type TraversalOptions, type ValidationOptions, childrenToElements, isElementOfType, isReactElement, useBoundedChildrenByType, useBoundedChildrenMatching, useCallbackChild, useChildByType, useChildMatching, useChildrenByType, useChildrenMatching, useExactChildrenByType, useExactChildrenMatching, useHasChildMatching, useMaximumChildrenByType, useMaximumChildrenMatching, useMinimumChildrenByType, useMinimumChildrenMatching, useOptionalChildByType, useOptionalChildMatching, useRequiredCallbackChild, useRequiredChildByType, useRequiredChildMatching, useUniqueChildByType, useUniqueChildMatching };
+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.d.ts

@@ -222,6 +222,15 @@ 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.
  *
@@ -273,6 +282,15 @@ declare function useRequiredCallbackChild<TArguments extends unknown[] = [], TRe
 declare function useRequiredChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: ValidationOptions): T;
 declare function useRequiredChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: ValidationOptions): ReactElement;
 
+/**
+ * Returns the only direct callback child from the provided children value, or throws when the match is not unique.
+ *
+ * @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 useUniqueCallbackChild<TArguments extends unknown[] = [], TResult = ReactNode>(children: CallbackChildren<TArguments, TResult>, options?: ValidationOptions): CallbackChild<TArguments, TResult>;
+
 /**
  * Returns the only direct child element whose React element type exactly matches the provided type, or throws when the match is not unique.
  *
@@ -294,30 +312,4 @@ declare function useUniqueChildByType<T extends ElementType>(children: ReactNode
 declare function useUniqueChildMatching<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: ValidationOptions): T;
 declare function useUniqueChildMatching(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: ValidationOptions): ReactElement;
 
-/**
- * Normalizes a React children value into an array containing valid child elements within the configured depth range.
- *
- * @param children The React children value to normalize.
- * @param options Optional traversal bounds that control which child depths are included.
- * @returns An array of valid React elements from the provided child depths.
- */
-declare function childrenToElements(children: ReactNode, options?: TraversalOptions): ReactElement[];
-
-/**
- * Determines whether a React element exactly matches the provided element or component type.
- *
- * @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`.
- */
-declare function isElementOfType<T extends ElementType>(element: ReactElement, type: T): element is ElementOfType<T>;
-
-/**
- * Determines whether a React node is a valid React element.
- *
- * @param node The React node to check.
- * @returns `true` when the node is a valid React element; otherwise `false`.
- */
-declare function isReactElement(node: ReactNode): node is ReactElement;
-
-export { type CallbackChild, type CallbackChildren, type ChildrenCountBounds, type ElementOfType, type QueryOptions, type TraversalOptions, type ValidationOptions, childrenToElements, isElementOfType, isReactElement, useBoundedChildrenByType, useBoundedChildrenMatching, useCallbackChild, useChildByType, useChildMatching, useChildrenByType, useChildrenMatching, useExactChildrenByType, useExactChildrenMatching, useHasChildMatching, useMaximumChildrenByType, useMaximumChildrenMatching, useMinimumChildrenByType, useMinimumChildrenMatching, useOptionalChildByType, useOptionalChildMatching, useRequiredCallbackChild, useRequiredChildByType, useRequiredChildMatching, useUniqueChildByType, useUniqueChildMatching };
+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

@@ -22,6 +22,8 @@ var validationMessages = {
   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 }}.",
@@ -87,10 +89,11 @@ function useChildMatching(children, predicate, options) {
     [children, options, predicate]
   );
 }
+var useChildMatching_default = useChildMatching;
 
 // src/useChildByType.ts
 function useChildByType(children, type, options) {
-  return useChildMatching(
+  return useChildMatching_default(
     children,
     (element) => isElementOfType(element, type),
     options
@@ -99,25 +102,26 @@ function useChildByType(children, type, options) {
 
 // src/useCallbackChild.ts
 import { useMemo as useMemo2 } from "react";
-function findFirstCallbackChild(children) {
+
+// src/callbackChildrenToArray.ts
+function callbackChildrenToArray(children) {
   if (typeof children === "function") {
-    return children;
+    return [children];
   }
   if (!Array.isArray(children)) {
-    return null;
-  }
-  for (const child of children) {
-    const callbackChild = findFirstCallbackChild(
-      child
-    );
-    if (callbackChild) {
-      return callbackChild;
-    }
+    return [];
   }
-  return null;
+  return children.flatMap(
+    (child) => callbackChildrenToArray(child)
+  );
 }
+
+// src/useCallbackChild.ts
 function useCallbackChild(children) {
-  return useMemo2(() => findFirstCallbackChild(children), [children]);
+  return useMemo2(
+    () => callbackChildrenToArray(children)[0] ?? null,
+    [children]
+  );
 }
 
 // src/useChildrenMatching.ts
@@ -128,10 +132,11 @@ function useChildrenMatching(children, predicate, options) {
     [children, options, predicate]
   );
 }
+var useChildrenMatching_default = useChildrenMatching;
 
 // src/useBoundedChildrenMatching.ts
 function useBoundedChildrenMatching(children, predicate, bounds, options) {
-  const matchingChildren = useChildrenMatching(children, predicate, options);
+  const matchingChildren = useChildrenMatching_default(children, predicate, options);
   if (matchingChildren.length >= bounds.minimum && matchingChildren.length <= bounds.maximum) {
     return matchingChildren;
   }
@@ -144,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,
@@ -157,7 +163,7 @@ function useBoundedChildrenByType(children, type, bounds, options) {
 
 // src/useChildrenByType.ts
 function useChildrenByType(children, type, options) {
-  return useChildrenMatching(
+  return useChildrenMatching_default(
     children,
     (element) => isElementOfType(element, type),
     options
@@ -166,7 +172,7 @@ function useChildrenByType(children, type, options) {
 
 // src/useExactChildrenMatching.ts
 function useExactChildrenMatching(children, predicate, exactCount, options) {
-  const matchingChildren = useChildrenMatching(children, predicate, options);
+  const matchingChildren = useChildrenMatching_default(children, predicate, options);
   if (matchingChildren.length === exactCount) {
     return matchingChildren;
   }
@@ -178,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,
@@ -197,10 +204,11 @@ function useHasChildMatching(children, predicate, options) {
     [children, options, predicate]
   );
 }
+var useHasChildMatching_default = useHasChildMatching;
 
 // src/useMaximumChildrenMatching.ts
 function useMaximumChildrenMatching(children, predicate, maximumCount, options) {
-  const matchingChildren = useChildrenMatching(children, predicate, options);
+  const matchingChildren = useChildrenMatching_default(children, predicate, options);
   if (matchingChildren.length <= maximumCount) {
     return matchingChildren;
   }
@@ -212,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,
@@ -225,7 +234,7 @@ function useMaximumChildrenByType(children, type, maximumCount, options) {
 
 // src/useMinimumChildrenMatching.ts
 function useMinimumChildrenMatching(children, predicate, minimumCount, options) {
-  const matchingChildren = useChildrenMatching(children, predicate, options);
+  const matchingChildren = useChildrenMatching_default(children, predicate, options);
   if (matchingChildren.length >= minimumCount) {
     return matchingChildren;
   }
@@ -237,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,
@@ -248,9 +258,26 @@ 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(children, predicate, options);
+  const matchingChildren = useChildrenMatching_default(children, predicate, options);
   if (matchingChildren.length <= 1) {
     return matchingChildren[0] ?? null;
   }
@@ -261,10 +288,11 @@ function useOptionalChildMatching(children, predicate, options) {
     actualCountPluralSuffix: matchingChildren.length === 1 ? "" : "ren"
   });
 }
+var useOptionalChildMatching_default = useOptionalChildMatching;
 
 // src/useOptionalChildByType.ts
 function useOptionalChildByType(children, type, options) {
-  return useOptionalChildMatching(
+  return useOptionalChildMatching_default(
     children,
     (element) => isElementOfType(element, type),
     options
@@ -273,7 +301,7 @@ function useOptionalChildByType(children, type, options) {
 
 // src/useRequiredChildMatching.ts
 function useRequiredChildMatching(children, predicate, options) {
-  const child = useChildMatching(children, predicate, options);
+  const child = useChildMatching_default(children, predicate, options);
   if (child !== null) {
     return child;
   }
@@ -282,10 +310,11 @@ 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
@@ -305,9 +334,26 @@ function useRequiredCallbackChild(children, options) {
   });
 }
 
+// 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(children, predicate, options);
+  const matchingChildren = useChildrenMatching_default(children, predicate, options);
   if (matchingChildren.length === 1) {
     return matchingChildren[0];
   }
@@ -318,39 +364,39 @@ function useUniqueChildMatching(children, predicate, options) {
     actualCountPluralSuffix: matchingChildren.length === 1 ? "" : "ren"
   });
 }
+var useUniqueChildMatching_default = useUniqueChildMatching;
 
 // src/useUniqueChildByType.ts
 function useUniqueChildByType(children, type, options) {
-  return useUniqueChildMatching(
+  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,
+  useOptionalChildMatching_default as useOptionalChildMatching,
   useRequiredCallbackChild,
   useRequiredChildByType,
-  useRequiredChildMatching,
+  useRequiredChildMatching_default as useRequiredChildMatching,
+  useUniqueCallbackChild,
   useUniqueChildByType,
-  useUniqueChildMatching
+  useUniqueChildMatching_default as useUniqueChildMatching
 };
 //# sourceMappingURL=index.js.map