react-children-hooks 0.3.0 → 0.5.0

package/README.md

@@ -6,12 +6,13 @@
 
 ### Query Hooks
 
+- [`useCallbackChild`](./docs/useCallbackChild.md)
 - [`useChildByType`](./docs/useChildByType.md)
 - [`useChildMatching`](./docs/useChildMatching.md)
 - [`useChildrenByType`](./docs/useChildrenByType.md)
 - [`useChildrenMatching`](./docs/useChildrenMatching.md)
 
-### Validation + Query Hooks
+### Query + Validation Hooks
 
 - [`useBoundedChildrenByType`](./docs/useBoundedChildrenByType.md)
 - [`useBoundedChildrenMatching`](./docs/useBoundedChildrenMatching.md)
@@ -21,21 +22,26 @@
 - [`useMaximumChildrenMatching`](./docs/useMaximumChildrenMatching.md)
 - [`useMinimumChildrenByType`](./docs/useMinimumChildrenByType.md)
 - [`useMinimumChildrenMatching`](./docs/useMinimumChildrenMatching.md)
+- [`useOptionalCallbackChild`](./docs/useOptionalCallbackChild.md)
+- [`useOptionalChildByType`](./docs/useOptionalChildByType.md)
+- [`useOptionalChildMatching`](./docs/useOptionalChildMatching.md)
+- [`useRequiredCallbackChild`](./docs/useRequiredCallbackChild.md)
 - [`useRequiredChildByType`](./docs/useRequiredChildByType.md)
 - [`useRequiredChildMatching`](./docs/useRequiredChildMatching.md)
+- [`useUniqueCallbackChild`](./docs/useUniqueCallbackChild.md)
+- [`useUniqueChildByType`](./docs/useUniqueChildByType.md)
+- [`useUniqueChildMatching`](./docs/useUniqueChildMatching.md)
 
 ### Validation Hooks
 
 - [`useHasChildMatching`](./docs/useHasChildMatching.md)
 
-### Utilities
-
-- [`childrenToElements`](./docs/childrenToElements.md)
-- [`isElementOfType`](./docs/isElementOfType.md)
-- [`isReactElement`](./docs/isReactElement.md)
-
 ### Types
 
-- `ChildrenCountBounds`
-- `ElementOfType`
-- `ValidationOptions`
+- [`CallbackChild`](./src/types.ts)
+- [`CallbackChildren`](./src/types.ts)
+- [`ChildrenCountBounds`](./src/types.ts)
+- [`ElementOfType`](./src/types.ts)
+- [`QueryOptions`](./src/types.ts)
+- [`TraversalOptions`](./src/types.ts)
+- [`ValidationOptions`](./src/types.ts)

package/dist/index.cjs

@@ -20,24 +20,29 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  childrenToElements: () => childrenToElements,
-  isElementOfType: () => isElementOfType,
-  isReactElement: () => isReactElement,
   useBoundedChildrenByType: () => useBoundedChildrenByType,
-  useBoundedChildrenMatching: () => useBoundedChildrenMatching,
+  useBoundedChildrenMatching: () => useBoundedChildrenMatching_default,
+  useCallbackChild: () => useCallbackChild,
   useChildByType: () => useChildByType,
-  useChildMatching: () => useChildMatching,
+  useChildMatching: () => useChildMatching_default,
   useChildrenByType: () => useChildrenByType,
-  useChildrenMatching: () => useChildrenMatching,
+  useChildrenMatching: () => useChildrenMatching_default,
   useExactChildrenByType: () => useExactChildrenByType,
-  useExactChildrenMatching: () => useExactChildrenMatching,
-  useHasChildMatching: () => useHasChildMatching,
+  useExactChildrenMatching: () => useExactChildrenMatching_default,
+  useHasChildMatching: () => useHasChildMatching_default,
   useMaximumChildrenByType: () => useMaximumChildrenByType,
-  useMaximumChildrenMatching: () => useMaximumChildrenMatching,
+  useMaximumChildrenMatching: () => useMaximumChildrenMatching_default,
   useMinimumChildrenByType: () => useMinimumChildrenByType,
-  useMinimumChildrenMatching: () => useMinimumChildrenMatching,
+  useMinimumChildrenMatching: () => useMinimumChildrenMatching_default,
+  useOptionalCallbackChild: () => useOptionalCallbackChild,
+  useOptionalChildByType: () => useOptionalChildByType,
+  useOptionalChildMatching: () => useOptionalChildMatching_default,
+  useRequiredCallbackChild: () => useRequiredCallbackChild,
   useRequiredChildByType: () => useRequiredChildByType,
-  useRequiredChildMatching: () => useRequiredChildMatching
+  useRequiredChildMatching: () => useRequiredChildMatching_default,
+  useUniqueCallbackChild: () => useUniqueCallbackChild,
+  useUniqueChildByType: () => useUniqueChildByType,
+  useUniqueChildMatching: () => useUniqueChildMatching_default
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -58,54 +63,128 @@ function isReactElement(node) {
   return (0, import_react.isValidElement)(node);
 }
 
-// src/childrenToElements.ts
-function childrenToElements(children) {
-  return import_react2.Children.toArray(children).filter(isReactElement);
-}
-
-// src/useChildMatching.ts
-function useChildMatching(children, predicate) {
-  return (0, import_react3.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
 var import_runtime_reporter = require("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 = (0, import_runtime_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 = import_react2.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 (0, import_react3.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
 var import_react4 = require("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 (0, import_react4.useMemo)(
-    () => childrenToElements(children).filter(predicate),
-    [children, predicate]
+    () => callbackChildrenToArray(children)[0] ?? null,
+    [children]
+  );
+}
+
+// src/useChildrenMatching.ts
+var import_react5 = require("react");
+function useChildrenMatching(children, predicate, options) {
+  return (0, import_react5.useMemo)(
+    () => 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;
   }
@@ -118,10 +197,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,
@@ -130,16 +210,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;
   }
@@ -151,10 +232,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,
@@ -163,17 +245,18 @@ function useExactChildrenByType(children, type, exactCount, options) {
 }
 
 // src/useHasChildMatching.ts
-var import_react5 = require("react");
-function useHasChildMatching(children, predicate) {
-  return (0, import_react5.useMemo)(
-    () => childrenToElements(children).some(predicate),
-    [children, predicate]
+var import_react6 = require("react");
+function useHasChildMatching(children, predicate, options) {
+  return (0, import_react6.useMemo)(
+    () => 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;
   }
@@ -185,10 +268,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,
@@ -198,7 +282,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;
   }
@@ -210,10 +294,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,
@@ -221,9 +306,50 @@ function useMinimumChildrenByType(children, type, minimumCount, options) {
   );
 }
 
+// src/useOptionalCallbackChild.ts
+var import_react7 = require("react");
+function useOptionalCallbackChild(children, options) {
+  const callbackChildren = (0, import_react7.useMemo)(
+    () => 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;
   }
@@ -232,10 +358,65 @@ 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
+var import_react8 = require("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
+var import_react9 = require("react");
+function useUniqueCallbackChild(children, options) {
+  const callbackChildren = (0, import_react9.useMemo)(
+    () => 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
@@ -243,11 +424,9 @@ function useRequiredChildByType(children, type, options) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  childrenToElements,
-  isElementOfType,
-  isReactElement,
   useBoundedChildrenByType,
   useBoundedChildrenMatching,
+  useCallbackChild,
   useChildByType,
   useChildMatching,
   useChildrenByType,
@@ -259,7 +438,14 @@ function useRequiredChildByType(children, type, options) {
   useMaximumChildrenMatching,
   useMinimumChildrenByType,
   useMinimumChildrenMatching,
+  useOptionalCallbackChild,
+  useOptionalChildByType,
+  useOptionalChildMatching,
+  useRequiredCallbackChild,
   useRequiredChildByType,
-  useRequiredChildMatching
+  useRequiredChildMatching,
+  useUniqueCallbackChild,
+  useUniqueChildByType,
+  useUniqueChildMatching
 });
 //# sourceMappingURL=index.cjs.map