react-children-hooks 0.2.0 → 0.4.0

package/README.md

@@ -2,32 +2,52 @@
 
 `react-children-hooks` is a TypeScript-first React library for inspecting, traversing, querying, and validating `props.children`.
 
+Element-based query and validation hooks inspect direct children by default, and can optionally traverse deeper descendant levels through `QueryOptions`, `TraversalOptions`, and `ValidationOptions`.
+
 ## API Reference
 
 ### Query Hooks
 
-- [`useChildByType`](./docs/api/useChildByType.md)
-- [`useChildWhere`](./docs/api/useChildWhere.md)
-- [`useChildrenByType`](./docs/api/useChildrenByType.md)
-- [`useChildrenWhere`](./docs/api/useChildrenWhere.md)
-
-### Validation + Query Hooks
-
-- [`useExactChildrenWhere`](./docs/api/useExactChildrenWhere.md)
-- [`useMaximumChildrenWhere`](./docs/api/useMaximumChildrenWhere.md)
-- [`useMinimumChildrenWhere`](./docs/api/useMinimumChildrenWhere.md)
-- [`useRequiredChildWhere`](./docs/api/useRequiredChildWhere.md)
+- [`useCallbackChild`](./docs/useCallbackChild.md)
+- [`useChildByType`](./docs/useChildByType.md)
+- [`useChildMatching`](./docs/useChildMatching.md)
+- [`useChildrenByType`](./docs/useChildrenByType.md)
+- [`useChildrenMatching`](./docs/useChildrenMatching.md)
+
+### Query + Validation Hooks
+
+- [`useBoundedChildrenByType`](./docs/useBoundedChildrenByType.md)
+- [`useBoundedChildrenMatching`](./docs/useBoundedChildrenMatching.md)
+- [`useExactChildrenByType`](./docs/useExactChildrenByType.md)
+- [`useExactChildrenMatching`](./docs/useExactChildrenMatching.md)
+- [`useMaximumChildrenByType`](./docs/useMaximumChildrenByType.md)
+- [`useMaximumChildrenMatching`](./docs/useMaximumChildrenMatching.md)
+- [`useMinimumChildrenByType`](./docs/useMinimumChildrenByType.md)
+- [`useMinimumChildrenMatching`](./docs/useMinimumChildrenMatching.md)
+- [`useOptionalChildByType`](./docs/useOptionalChildByType.md)
+- [`useOptionalChildMatching`](./docs/useOptionalChildMatching.md)
+- [`useRequiredCallbackChild`](./docs/useRequiredCallbackChild.md)
+- [`useRequiredChildByType`](./docs/useRequiredChildByType.md)
+- [`useRequiredChildMatching`](./docs/useRequiredChildMatching.md)
+- [`useUniqueChildByType`](./docs/useUniqueChildByType.md)
+- [`useUniqueChildMatching`](./docs/useUniqueChildMatching.md)
 
 ### Validation Hooks
 
-- [`useHasChildWhere`](./docs/api/useHasChildWhere.md)
+- [`useHasChildMatching`](./docs/useHasChildMatching.md)
 
 ### Utilities
 
-- [`childrenToElements`](./docs/api/childrenToElements.md)
-- [`isElementOfType`](./docs/api/isElementOfType.md)
-- [`isReactElement`](./docs/api/isReactElement.md)
+- [`childrenToElements`](./docs/childrenToElements.md)
+- [`isElementOfType`](./docs/isElementOfType.md)
+- [`isReactElement`](./docs/isReactElement.md)
 
 ### Types
 
-- [`ElementOfType`](./docs/api/ElementOfType.md)
+- [`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

@@ -23,15 +23,27 @@ __export(index_exports, {
   childrenToElements: () => childrenToElements,
   isElementOfType: () => isElementOfType,
   isReactElement: () => isReactElement,
+  useBoundedChildrenByType: () => useBoundedChildrenByType,
+  useBoundedChildrenMatching: () => useBoundedChildrenMatching,
+  useCallbackChild: () => useCallbackChild,
   useChildByType: () => useChildByType,
-  useChildWhere: () => useChildWhere,
+  useChildMatching: () => useChildMatching,
   useChildrenByType: () => useChildrenByType,
-  useChildrenWhere: () => useChildrenWhere,
-  useExactChildrenWhere: () => useExactChildrenWhere,
-  useHasChildWhere: () => useHasChildWhere,
-  useMaximumChildrenWhere: () => useMaximumChildrenWhere,
-  useMinimumChildrenWhere: () => useMinimumChildrenWhere,
-  useRequiredChildWhere: () => useRequiredChildWhere
+  useChildrenMatching: () => useChildrenMatching,
+  useExactChildrenByType: () => useExactChildrenByType,
+  useExactChildrenMatching: () => useExactChildrenMatching,
+  useHasChildMatching: () => useHasChildMatching,
+  useMaximumChildrenByType: () => useMaximumChildrenByType,
+  useMaximumChildrenMatching: () => useMaximumChildrenMatching,
+  useMinimumChildrenByType: () => useMinimumChildrenByType,
+  useMinimumChildrenMatching: () => useMinimumChildrenMatching,
+  useOptionalChildByType: () => useOptionalChildByType,
+  useOptionalChildMatching: () => useOptionalChildMatching,
+  useRequiredCallbackChild: () => useRequiredCallbackChild,
+  useRequiredChildByType: () => useRequiredChildByType,
+  useRequiredChildMatching: () => useRequiredChildMatching,
+  useUniqueChildByType: () => useUniqueChildByType,
+  useUniqueChildMatching: () => useUniqueChildMatching
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -40,7 +52,7 @@ function isElementOfType(element, type) {
   return element.type === type;
 }
 
-// src/useChildWhere.ts
+// src/useChildMatching.ts
 var import_react3 = require("react");
 
 // src/childrenToElements.ts
@@ -52,65 +64,162 @@ function isReactElement(node) {
   return (0, import_react.isValidElement)(node);
 }
 
+// src/reporter.ts
+var import_runtime_reporter = require("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 = (0, import_runtime_reporter.createReporter)(
+  process.env.NODE_ENV === "production" ? {} : messages,
+  { formatMessage: (message) => message }
+);
+var reporter_default = reporter;
+
 // src/childrenToElements.ts
-function childrenToElements(children) {
-  return import_react2.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 = 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/useChildWhere.ts
-function useChildWhere(children, predicate) {
+// src/useChildMatching.ts
+function useChildMatching(children, predicate, options) {
   return (0, import_react3.useMemo)(
-    () => childrenToElements(children).find(predicate) ?? null,
-    [children, predicate]
+    () => childrenToElements(children, options).find(predicate) ?? null,
+    [children, options, predicate]
   );
 }
 
 // src/useChildByType.ts
-function useChildByType(children, type) {
-  return useChildWhere(
+function useChildByType(children, type, options) {
+  return useChildMatching(
     children,
-    (element) => isElementOfType(element, type)
+    (element) => isElementOfType(element, type),
+    options
   );
 }
 
-// src/useChildrenWhere.ts
+// src/useCallbackChild.ts
 var import_react4 = require("react");
-function useChildrenWhere(children, predicate) {
-  return (0, import_react4.useMemo)(
-    () => childrenToElements(children).filter(predicate),
-    [children, predicate]
+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 (0, import_react4.useMemo)(() => findFirstCallbackChild(children), [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]
   );
 }
 
-// src/useChildrenByType.ts
-function useChildrenByType(children, type) {
-  return useChildrenWhere(
+// src/useBoundedChildrenMatching.ts
+function useBoundedChildrenMatching(children, predicate, bounds, options) {
+  const matchingChildren = useChildrenMatching(children, predicate, options);
+  if (matchingChildren.length >= bounds.minimum && matchingChildren.length <= bounds.maximum) {
+    return matchingChildren;
+  }
+  return reporter_default.fail("BOUNDED_CHILDREN_MATCHING_PREDICATE_FAILED", {
+    traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : "",
+    childNameSegment: options?.childName ? ` for ${options.childName}` : "",
+    actualCount: matchingChildren.length,
+    actualCountPluralSuffix: matchingChildren.length === 1 ? "" : "ren",
+    minimumCount: bounds.minimum,
+    maximumCount: bounds.maximum
+  });
+}
+
+// src/useBoundedChildrenByType.ts
+function useBoundedChildrenByType(children, type, bounds, options) {
+  return useBoundedChildrenMatching(
     children,
-    (element) => isElementOfType(element, type)
+    (element) => isElementOfType(element, type),
+    bounds,
+    options
   );
 }
 
-// src/reporter.ts
-var import_runtime_reporter = require("runtime-reporter");
-var messages = {
-  REQUIRED_CHILD_WHERE_PREDICATE_FAILED: "{{ traceCodePrefix }}Required child validation failed{{ childNameSegment }} because no direct child satisfied the provided predicate.",
-  MINIMUM_CHILDREN_WHERE_PREDICATE_FAILED: "{{ traceCodePrefix }}Minimum children validation failed{{ childNameSegment }} because only {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected at least {{ minimumCount }}.",
-  MAXIMUM_CHILDREN_WHERE_PREDICATE_FAILED: "{{ traceCodePrefix }}Maximum children validation failed{{ childNameSegment }} because {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected at most {{ maximumCount }}.",
-  EXACT_CHILDREN_WHERE_PREDICATE_FAILED: "{{ traceCodePrefix }}Exact children validation failed{{ childNameSegment }} because {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected exactly {{ exactCount }}."
-};
-var reporter = (0, import_runtime_reporter.createReporter)(
-  process.env.NODE_ENV === "production" ? {} : messages,
-  { formatMessage: (message) => message }
-);
-var reporter_default = reporter;
+// src/useChildrenByType.ts
+function useChildrenByType(children, type, options) {
+  return useChildrenMatching(
+    children,
+    (element) => isElementOfType(element, type),
+    options
+  );
+}
 
-// src/useExactChildrenWhere.ts
-function useExactChildrenWhere(children, predicate, exactCount, options) {
-  const matchingChildren = useChildrenWhere(children, predicate);
+// src/useExactChildrenMatching.ts
+function useExactChildrenMatching(children, predicate, exactCount, options) {
+  const matchingChildren = useChildrenMatching(children, predicate, options);
   if (matchingChildren.length === exactCount) {
     return matchingChildren;
   }
-  return reporter_default.fail("EXACT_CHILDREN_WHERE_PREDICATE_FAILED", {
+  return reporter_default.fail("EXACT_CHILDREN_MATCHING_PREDICATE_FAILED", {
     traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : "",
     childNameSegment: options?.childName ? ` for ${options.childName}` : "",
     actualCount: matchingChildren.length,
@@ -119,22 +228,32 @@ function useExactChildrenWhere(children, predicate, exactCount, options) {
   });
 }
 
-// src/useHasChildWhere.ts
-var import_react5 = require("react");
-function useHasChildWhere(children, predicate) {
-  return (0, import_react5.useMemo)(
-    () => childrenToElements(children).some(predicate),
-    [children, predicate]
+// src/useExactChildrenByType.ts
+function useExactChildrenByType(children, type, exactCount, options) {
+  return useExactChildrenMatching(
+    children,
+    (element) => isElementOfType(element, type),
+    exactCount,
+    options
+  );
+}
+
+// src/useHasChildMatching.ts
+var import_react6 = require("react");
+function useHasChildMatching(children, predicate, options) {
+  return (0, import_react6.useMemo)(
+    () => childrenToElements(children, options).some(predicate),
+    [children, options, predicate]
   );
 }
 
-// src/useMaximumChildrenWhere.ts
-function useMaximumChildrenWhere(children, predicate, maximumCount, options) {
-  const matchingChildren = useChildrenWhere(children, predicate);
+// src/useMaximumChildrenMatching.ts
+function useMaximumChildrenMatching(children, predicate, maximumCount, options) {
+  const matchingChildren = useChildrenMatching(children, predicate, options);
   if (matchingChildren.length <= maximumCount) {
     return matchingChildren;
   }
-  return reporter_default.fail("MAXIMUM_CHILDREN_WHERE_PREDICATE_FAILED", {
+  return reporter_default.fail("MAXIMUM_CHILDREN_MATCHING_PREDICATE_FAILED", {
     traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : "",
     childNameSegment: options?.childName ? ` for ${options.childName}` : "",
     actualCount: matchingChildren.length,
@@ -143,13 +262,23 @@ function useMaximumChildrenWhere(children, predicate, maximumCount, options) {
   });
 }
 
-// src/useMinimumChildrenWhere.ts
-function useMinimumChildrenWhere(children, predicate, minimumCount, options) {
-  const matchingChildren = useChildrenWhere(children, predicate);
+// src/useMaximumChildrenByType.ts
+function useMaximumChildrenByType(children, type, maximumCount, options) {
+  return useMaximumChildrenMatching(
+    children,
+    (element) => isElementOfType(element, type),
+    maximumCount,
+    options
+  );
+}
+
+// src/useMinimumChildrenMatching.ts
+function useMinimumChildrenMatching(children, predicate, minimumCount, options) {
+  const matchingChildren = useChildrenMatching(children, predicate, options);
   if (matchingChildren.length >= minimumCount) {
     return matchingChildren;
   }
-  return reporter_default.fail("MINIMUM_CHILDREN_WHERE_PREDICATE_FAILED", {
+  return reporter_default.fail("MINIMUM_CHILDREN_MATCHING_PREDICATE_FAILED", {
     traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : "",
     childNameSegment: options?.childName ? ` for ${options.childName}` : "",
     actualCount: matchingChildren.length,
@@ -158,30 +287,120 @@ function useMinimumChildrenWhere(children, predicate, minimumCount, options) {
   });
 }
 
-// src/useRequiredChildWhere.ts
-function useRequiredChildWhere(children, predicate, options) {
-  const child = useChildWhere(children, predicate);
+// src/useMinimumChildrenByType.ts
+function useMinimumChildrenByType(children, type, minimumCount, options) {
+  return useMinimumChildrenMatching(
+    children,
+    (element) => isElementOfType(element, 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, options);
   if (child !== null) {
     return child;
   }
-  return reporter_default.fail("REQUIRED_CHILD_WHERE_PREDICATE_FAILED", {
+  return reporter_default.fail("REQUIRED_CHILD_MATCHING_PREDICATE_FAILED", {
+    traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : "",
+    childNameSegment: options?.childName ? ` for ${options.childName}` : ""
+  });
+}
+
+// src/useRequiredChildByType.ts
+function useRequiredChildByType(children, type, options) {
+  return useRequiredChildMatching(
+    children,
+    (element) => isElementOfType(element, type),
+    options
+  );
+}
+
+// src/useRequiredCallbackChild.ts
+var import_react7 = 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/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
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   childrenToElements,
   isElementOfType,
   isReactElement,
+  useBoundedChildrenByType,
+  useBoundedChildrenMatching,
+  useCallbackChild,
   useChildByType,
-  useChildWhere,
+  useChildMatching,
   useChildrenByType,
-  useChildrenWhere,
-  useExactChildrenWhere,
-  useHasChildWhere,
-  useMaximumChildrenWhere,
-  useMinimumChildrenWhere,
-  useRequiredChildWhere
+  useChildrenMatching,
+  useExactChildrenByType,
+  useExactChildrenMatching,
+  useHasChildMatching,
+  useMaximumChildrenByType,
+  useMaximumChildrenMatching,
+  useMinimumChildrenByType,
+  useMinimumChildrenMatching,
+  useOptionalChildByType,
+  useOptionalChildMatching,
+  useRequiredCallbackChild,
+  useRequiredChildByType,
+  useRequiredChildMatching,
+  useUniqueChildByType,
+  useUniqueChildMatching
 });
 //# sourceMappingURL=index.cjs.map