react-children-hooks 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark McCann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# react-children-hooks
+
+`react-children-hooks` is a TypeScript-first React library for inspecting, traversing, querying, and validating `props.children`.
+
+## 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 Hooks
+
+- [`useHasChildWhere`](./docs/api/useHasChildWhere.md)
+- [`useMinimumChildrenWhere`](./docs/api/useMinimumChildrenWhere.md)
+- [`useRequiredChildWhere`](./docs/api/useRequiredChildWhere.md)
+
+### Utilities
+
+- [`childrenToElements`](./docs/api/childrenToElements.md)
+- [`isElementOfType`](./docs/api/isElementOfType.md)
+- [`isReactElement`](./docs/api/isReactElement.md)
+
+### Types
+
+- [`ElementOfType`](./docs/api/ElementOfType.md)

package/dist/index.cjs

@@ -0,0 +1,151 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  childrenToElements: () => childrenToElements,
+  isElementOfType: () => isElementOfType,
+  isReactElement: () => isReactElement,
+  useChildByType: () => useChildByType,
+  useChildWhere: () => useChildWhere,
+  useChildrenByType: () => useChildrenByType,
+  useChildrenWhere: () => useChildrenWhere,
+  useHasChildWhere: () => useHasChildWhere,
+  useMinimumChildrenWhere: () => useMinimumChildrenWhere,
+  useRequiredChildWhere: () => useRequiredChildWhere
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/isElementOfType.ts
+function isElementOfType(element, type) {
+  return element.type === type;
+}
+
+// src/useChildWhere.ts
+var import_react3 = require("react");
+
+// src/childrenToElements.ts
+var import_react2 = require("react");
+
+// src/isReactElement.ts
+var import_react = require("react");
+function isReactElement(node) {
+  return (0, import_react.isValidElement)(node);
+}
+
+// src/childrenToElements.ts
+function childrenToElements(children) {
+  return import_react2.Children.toArray(children).filter(isReactElement);
+}
+
+// src/useChildWhere.ts
+function useChildWhere(children, predicate) {
+  return (0, import_react3.useMemo)(
+    () => childrenToElements(children).find(predicate) ?? null,
+    [children, predicate]
+  );
+}
+
+// src/useChildByType.ts
+function useChildByType(children, type) {
+  return useChildWhere(
+    children,
+    (element) => isElementOfType(element, type)
+  );
+}
+
+// src/useChildrenWhere.ts
+var import_react4 = require("react");
+function useChildrenWhere(children, predicate) {
+  return (0, import_react4.useMemo)(
+    () => childrenToElements(children).filter(predicate),
+    [children, predicate]
+  );
+}
+
+// src/useChildrenByType.ts
+function useChildrenByType(children, type) {
+  return useChildrenWhere(
+    children,
+    (element) => isElementOfType(element, type)
+  );
+}
+
+// src/useHasChildWhere.ts
+var import_react5 = require("react");
+function useHasChildWhere(children, predicate) {
+  return (0, import_react5.useMemo)(
+    () => childrenToElements(children).some(predicate),
+    [children, predicate]
+  );
+}
+
+// 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 }}."
+};
+var reporter = (0, import_runtime_reporter.createReporter)(
+  process.env.NODE_ENV === "production" ? {} : messages,
+  { formatMessage: (message) => message }
+);
+var reporter_default = reporter;
+
+// src/useMinimumChildrenWhere.ts
+function useMinimumChildrenWhere(children, predicate, minimumCount, options) {
+  const matchingChildren = useChildrenWhere(children, predicate);
+  if (matchingChildren.length >= minimumCount) {
+    return matchingChildren;
+  }
+  return reporter_default.fail("MINIMUM_CHILDREN_WHERE_PREDICATE_FAILED", {
+    traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : "",
+    childNameSegment: options?.childName ? ` for ${options.childName}` : "",
+    actualCount: matchingChildren.length,
+    actualCountPluralSuffix: matchingChildren.length === 1 ? "" : "ren",
+    minimumCount
+  });
+}
+
+// src/useRequiredChildWhere.ts
+function useRequiredChildWhere(children, predicate, options) {
+  const child = useChildWhere(children, predicate);
+  if (child !== null) {
+    return child;
+  }
+  return reporter_default.fail("REQUIRED_CHILD_WHERE_PREDICATE_FAILED", {
+    traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : "",
+    childNameSegment: options?.childName ? ` for ${options.childName}` : ""
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  childrenToElements,
+  isElementOfType,
+  isReactElement,
+  useChildByType,
+  useChildWhere,
+  useChildrenByType,
+  useChildrenWhere,
+  useHasChildWhere,
+  useMinimumChildrenWhere,
+  useRequiredChildWhere
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/isElementOfType.ts","../src/useChildWhere.ts","../src/childrenToElements.ts","../src/isReactElement.ts","../src/useChildByType.ts","../src/useChildrenWhere.ts","../src/useChildrenByType.ts","../src/useHasChildWhere.ts","../src/reporter.ts","../src/useMinimumChildrenWhere.ts","../src/useRequiredChildWhere.ts"],"sourcesContent":["/**\n * Public package entrypoint.\n *\n * Hooks and child utilities will be exported here as the API is defined.\n */\nexport { useChildByType } from \"./useChildByType\";\nexport { useChildWhere } from \"./useChildWhere\";\nexport { useChildrenByType } from \"./useChildrenByType\";\nexport { useChildrenWhere } from \"./useChildrenWhere\";\nexport { useHasChildWhere } from \"./useHasChildWhere\";\nexport { useMinimumChildrenWhere } from \"./useMinimumChildrenWhere\";\nexport { useRequiredChildWhere } from \"./useRequiredChildWhere\";\nexport { childrenToElements } from \"./childrenToElements\";\nexport { isElementOfType } from \"./isElementOfType\";\nexport { isReactElement } from \"./isReactElement\";\nexport type { ElementOfType } from \"./types\";\nexport type { UseMinimumChildrenWhereOptions } from \"./useMinimumChildrenWhere\";\nexport type { UseRequiredChildWhereOptions } from \"./useRequiredChildWhere\";\n","import type { ElementType, ReactElement } from \"react\";\n\nimport type { ElementOfType } from \"./types\";\n\n/**\n * Determines whether a React element exactly matches the provided element or component type.\n *\n * @param element The React element to compare.\n * @param type The element or component type to match.\n * @returns `true` when the element's type exactly matches the provided type; otherwise `false`.\n */\nexport function isElementOfType<T extends ElementType>(\n    element: ReactElement,\n    type: T\n): element is ElementOfType<T> {\n    return element.type === type;\n}\n","import { useMemo, type ReactElement, type ReactNode } from \"react\";\n\nimport { childrenToElements } from \"./childrenToElements\";\n\n/**\n * Returns the first direct child element that satisfies the provided predicate.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it matches.\n * @returns The first direct child element that satisfies the provided predicate, or `null` when no match is found.\n */\nexport function useChildWhere<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T\n): T | null;\nexport function useChildWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean\n): ReactElement | null;\nexport function useChildWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean\n): ReactElement | null {\n    return useMemo(\n        () => childrenToElements(children).find(predicate) ?? null,\n        [children, predicate]\n    );\n}\n","import { Children, type ReactElement, type ReactNode } from \"react\";\n\nimport { isReactElement } from \"./isReactElement\";\n\n/**\n * Normalizes a React children value into an array containing only valid direct child elements.\n *\n * @param children The React children value to normalize.\n * @returns An array of valid React elements from the provided direct children.\n */\nexport function childrenToElements(children: ReactNode): ReactElement[] {\n    return Children.toArray(children).filter(isReactElement);\n}\n","import { isValidElement, type ReactElement, type ReactNode } from \"react\";\n\n/**\n * Determines whether a React node is a valid React element.\n *\n * @param node The React node to check.\n * @returns `true` when the node is a valid React element; otherwise `false`.\n */\nexport function isReactElement(node: ReactNode): node is ReactElement {\n    return isValidElement(node);\n}\n","import type { ElementType, ReactNode } from \"react\";\n\nimport { isElementOfType } from \"./isElementOfType\";\nimport { useChildWhere } from \"./useChildWhere\";\nimport type { ElementOfType } from \"./types\";\n\n/**\n * Returns the first direct child element whose React element type exactly matches the provided type.\n *\n * @param children The React children value to inspect.\n * @param type The element or component type to match against each direct child element.\n * @returns The first direct child element whose type matches the provided element type, or `null` when no match is found.\n */\nexport function useChildByType<T extends ElementType>(\n    children: ReactNode,\n    type: T\n): ElementOfType<T> | null {\n    return useChildWhere(children, (element): element is ElementOfType<T> =>\n        isElementOfType(element, type)\n    );\n}\n","import { useMemo, type ReactElement, type ReactNode } from \"react\";\n\nimport { childrenToElements } from \"./childrenToElements\";\n\n/**\n * Returns the direct child elements that satisfy the provided predicate.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it should be included in the result.\n * @returns An array of direct child elements that satisfy the provided predicate.\n */\nexport function useChildrenWhere<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T\n): T[];\nexport function useChildrenWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean\n): ReactElement[];\nexport function useChildrenWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean\n): ReactElement[] {\n    return useMemo(\n        () => childrenToElements(children).filter(predicate),\n        [children, predicate]\n    );\n}\n","import type { ElementType, ReactNode } from \"react\";\n\nimport { isElementOfType } from \"./isElementOfType\";\nimport { useChildrenWhere } from \"./useChildrenWhere\";\nimport type { ElementOfType } from \"./types\";\n\n/**\n * Returns the direct child elements whose React element type exactly matches the provided type.\n *\n * @param children The React children value to inspect.\n * @param type The element or component type to match against each direct child element.\n * @returns An array of direct child elements whose type matches the provided element type.\n */\nexport function useChildrenByType<T extends ElementType>(\n    children: ReactNode,\n    type: T\n): ElementOfType<T>[] {\n    return useChildrenWhere(children, (element): element is ElementOfType<T> =>\n        isElementOfType(element, type)\n    );\n}\n","import { useMemo, type ReactElement, type ReactNode } from \"react\";\n\nimport { childrenToElements } from \"./childrenToElements\";\n\n/**\n * Determines whether any direct child element satisfies the provided predicate.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it matches.\n * @returns `true` when at least one direct child element satisfies the provided predicate; otherwise `false`.\n */\nexport function useHasChildWhere<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T\n): boolean;\nexport function useHasChildWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean\n): boolean;\nexport function useHasChildWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean\n): boolean {\n    return useMemo(\n        () => childrenToElements(children).some(predicate),\n        [children, predicate]\n    );\n}\n","import { createReporter, type RuntimeReporterMessages } from \"runtime-reporter\";\n\nconst messages: RuntimeReporterMessages<\n    | {\n          code: \"REQUIRED_CHILD_WHERE_PREDICATE_FAILED\";\n          template: \"{{ traceCodePrefix }}Required child validation failed{{ childNameSegment }} because no direct child satisfied the provided predicate.\";\n          tokens: \"traceCodePrefix\" | \"childNameSegment\";\n      }\n    | {\n          code: \"MINIMUM_CHILDREN_WHERE_PREDICATE_FAILED\";\n          template: \"{{ traceCodePrefix }}Minimum children validation failed{{ childNameSegment }} because only {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected at least {{ minimumCount }}.\";\n          tokens:\n              | \"traceCodePrefix\"\n              | \"childNameSegment\"\n              | \"actualCount\"\n              | \"actualCountPluralSuffix\"\n              | \"minimumCount\";\n      }\n> = {\n    REQUIRED_CHILD_WHERE_PREDICATE_FAILED:\n        \"{{ traceCodePrefix }}Required child validation failed{{ childNameSegment }} because no direct child satisfied the provided predicate.\",\n    MINIMUM_CHILDREN_WHERE_PREDICATE_FAILED:\n        \"{{ traceCodePrefix }}Minimum children validation failed{{ childNameSegment }} because only {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected at least {{ minimumCount }}.\"\n};\n\n/** The runtime reporter for react-children-hooks */\nconst reporter = createReporter(\n    process.env.NODE_ENV === \"production\" ? ({} as typeof messages) : messages,\n    { formatMessage: (message) => message }\n);\n\nexport default reporter;\n","import type { ReactElement, ReactNode } from \"react\";\n\nimport reporter from \"./reporter\";\nimport { useChildrenWhere } from \"./useChildrenWhere\";\n\nexport type UseMinimumChildrenWhereOptions = {\n    /**\n     * An optional consumer-defined trace code that is prefixed to the thrown validation message.\n     */\n    traceCode?: string;\n    /**\n     * An optional human-readable child name that is included in the thrown validation message.\n     */\n    childName?: string;\n};\n\n/**\n * Returns the direct child elements that satisfy the provided predicate, or throws when fewer than the minimum count are found.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it matches.\n * @param minimumCount The minimum number of matching direct child elements required.\n * @param options Optional reporting metadata used to derive the thrown validation message.\n * @returns The direct child elements that satisfy the provided predicate.\n */\nexport function useMinimumChildrenWhere<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T,\n    minimumCount: number,\n    options?: UseMinimumChildrenWhereOptions\n): T[];\nexport function useMinimumChildrenWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    minimumCount: number,\n    options?: UseMinimumChildrenWhereOptions\n): ReactElement[];\nexport function useMinimumChildrenWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    minimumCount: number,\n    options?: UseMinimumChildrenWhereOptions\n): ReactElement[] {\n    const matchingChildren = useChildrenWhere(children, predicate);\n\n    if (matchingChildren.length >= minimumCount) {\n        return matchingChildren;\n    }\n\n    return reporter.fail(\"MINIMUM_CHILDREN_WHERE_PREDICATE_FAILED\", {\n        traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : \"\",\n        childNameSegment: options?.childName ? ` for ${options.childName}` : \"\",\n        actualCount: matchingChildren.length,\n        actualCountPluralSuffix: matchingChildren.length === 1 ? \"\" : \"ren\",\n        minimumCount\n    });\n}\n","import type { ReactElement, ReactNode } from \"react\";\n\nimport reporter from \"./reporter\";\nimport { useChildWhere } from \"./useChildWhere\";\n\nexport type UseRequiredChildWhereOptions = {\n    /**\n     * An optional consumer-defined trace code that is prefixed to the thrown validation message.\n     */\n    traceCode?: string;\n    /**\n     * An optional human-readable child name that is included in the thrown validation message.\n     */\n    childName?: string;\n};\n\n/**\n * Returns the first direct child element that satisfies the provided predicate, or throws when no match is found.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it matches.\n * @param options Optional reporting metadata used to derive the thrown validation message.\n * @returns The first direct child element that satisfies the provided predicate.\n */\nexport function useRequiredChildWhere<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T,\n    options?: UseRequiredChildWhereOptions\n): T;\nexport function useRequiredChildWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    options?: UseRequiredChildWhereOptions\n): ReactElement;\nexport function useRequiredChildWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    options?: UseRequiredChildWhereOptions\n): ReactElement {\n    const child = useChildWhere(children, predicate);\n\n    if (child !== null) {\n        return child;\n    }\n\n    return reporter.fail(\"REQUIRED_CHILD_WHERE_PREDICATE_FAILED\", {\n        traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : \"\",\n        childNameSegment: options?.childName ? ` for ${options.childName}` : \"\"\n    });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACWO,SAAS,gBACZ,SACA,MAC2B;AAC3B,SAAO,QAAQ,SAAS;AAC5B;;;AChBA,IAAAA,gBAA2D;;;ACA3D,IAAAC,gBAA4D;;;ACA5D,mBAAkE;AAQ3D,SAAS,eAAe,MAAuC;AAClE,aAAO,6BAAe,IAAI;AAC9B;;;ADAO,SAAS,mBAAmB,UAAqC;AACpE,SAAO,uBAAS,QAAQ,QAAQ,EAAE,OAAO,cAAc;AAC3D;;;ADOO,SAAS,cACZ,UACA,WACmB;AACnB,aAAO;AAAA,IACH,MAAM,mBAAmB,QAAQ,EAAE,KAAK,SAAS,KAAK;AAAA,IACtD,CAAC,UAAU,SAAS;AAAA,EACxB;AACJ;;;AGdO,SAAS,eACZ,UACA,MACuB;AACvB,SAAO;AAAA,IAAc;AAAA,IAAU,CAAC,YAC5B,gBAAgB,SAAS,IAAI;AAAA,EACjC;AACJ;;;ACpBA,IAAAC,gBAA2D;AAmBpD,SAAS,iBACZ,UACA,WACc;AACd,aAAO;AAAA,IACH,MAAM,mBAAmB,QAAQ,EAAE,OAAO,SAAS;AAAA,IACnD,CAAC,UAAU,SAAS;AAAA,EACxB;AACJ;;;ACdO,SAAS,kBACZ,UACA,MACkB;AAClB,SAAO;AAAA,IAAiB;AAAA,IAAU,CAAC,YAC/B,gBAAgB,SAAS,IAAI;AAAA,EACjC;AACJ;;;ACpBA,IAAAC,gBAA2D;AAmBpD,SAAS,iBACZ,UACA,WACO;AACP,aAAO;AAAA,IACH,MAAM,mBAAmB,QAAQ,EAAE,KAAK,SAAS;AAAA,IACjD,CAAC,UAAU,SAAS;AAAA,EACxB;AACJ;;;AC3BA,8BAA6D;AAE7D,IAAM,WAgBF;AAAA,EACA,uCACI;AAAA,EACJ,yCACI;AACR;AAGA,IAAM,eAAW;AAAA,EACb,QAAQ,IAAI,aAAa,eAAgB,CAAC,IAAwB;AAAA,EAClE,EAAE,eAAe,CAAC,YAAY,QAAQ;AAC1C;AAEA,IAAO,mBAAQ;;;ACMR,SAAS,wBACZ,UACA,WACA,cACA,SACc;AACd,QAAM,mBAAmB,iBAAiB,UAAU,SAAS;AAE7D,MAAI,iBAAiB,UAAU,cAAc;AACzC,WAAO;AAAA,EACX;AAEA,SAAO,iBAAS,KAAK,2CAA2C;AAAA,IAC5D,iBAAiB,SAAS,YAAY,IAAI,QAAQ,SAAS,OAAO;AAAA,IAClE,kBAAkB,SAAS,YAAY,QAAQ,QAAQ,SAAS,KAAK;AAAA,IACrE,aAAa,iBAAiB;AAAA,IAC9B,yBAAyB,iBAAiB,WAAW,IAAI,KAAK;AAAA,IAC9D;AAAA,EACJ,CAAC;AACL;;;ACtBO,SAAS,sBACZ,UACA,WACA,SACY;AACZ,QAAM,QAAQ,cAAc,UAAU,SAAS;AAE/C,MAAI,UAAU,MAAM;AAChB,WAAO;AAAA,EACX;AAEA,SAAO,iBAAS,KAAK,yCAAyC;AAAA,IAC1D,iBAAiB,SAAS,YAAY,IAAI,QAAQ,SAAS,OAAO;AAAA,IAClE,kBAAkB,SAAS,YAAY,QAAQ,QAAQ,SAAS,KAAK;AAAA,EACzE,CAAC;AACL;","names":["import_react","import_react","import_react","import_react"]}

package/dist/index.d.cts

@@ -0,0 +1,127 @@
+import * as React from 'react';
+import { ElementType, ReactNode, ReactElement } from 'react';
+
+/**
+ * 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>;
+
+/**
+ * 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.
+ * @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;
+
+/**
+ * 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.
+ * @returns The first direct child element that satisfies the provided predicate, or `null` when no match is found.
+ */
+declare function useChildWhere<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): T | null;
+declare function useChildWhere(children: ReactNode, predicate: (element: ReactElement) => boolean): ReactElement | null;
+
+/**
+ * Returns the direct child elements 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.
+ * @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>[];
+
+/**
+ * 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.
+ * @returns An array of direct child elements that satisfy the provided predicate.
+ */
+declare function useChildrenWhere<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): T[];
+declare function useChildrenWhere(children: ReactNode, predicate: (element: ReactElement) => boolean): ReactElement[];
+
+/**
+ * Determines whether any direct child element 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.
+ * @returns `true` when at least one direct child element satisfies the provided predicate; otherwise `false`.
+ */
+declare function useHasChildWhere<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): boolean;
+declare function useHasChildWhere(children: ReactNode, predicate: (element: ReactElement) => boolean): boolean;
+
+type UseMinimumChildrenWhereOptions = {
+    /**
+     * An optional consumer-defined trace code that is prefixed to the thrown validation message.
+     */
+    traceCode?: string;
+    /**
+     * An optional human-readable child name that is included in the thrown validation message.
+     */
+    childName?: string;
+};
+/**
+ * Returns the direct child elements that satisfy the provided predicate, or throws when fewer than the minimum count are 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 minimumCount The minimum number of matching direct child elements required.
+ * @param options Optional reporting metadata used to derive the thrown validation message.
+ * @returns The direct child elements that satisfy the provided predicate.
+ */
+declare function useMinimumChildrenWhere<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, minimumCount: number, options?: UseMinimumChildrenWhereOptions): T[];
+declare function useMinimumChildrenWhere(children: ReactNode, predicate: (element: ReactElement) => boolean, minimumCount: number, options?: UseMinimumChildrenWhereOptions): ReactElement[];
+
+type UseRequiredChildWhereOptions = {
+    /**
+     * An optional consumer-defined trace code that is prefixed to the thrown validation message.
+     */
+    traceCode?: string;
+    /**
+     * An optional human-readable child name that is included in the thrown validation message.
+     */
+    childName?: string;
+};
+/**
+ * Returns the first direct child element that satisfies the provided predicate, or throws when no 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 first direct child element that satisfies the provided predicate.
+ */
+declare function useRequiredChildWhere<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: UseRequiredChildWhereOptions): T;
+declare function useRequiredChildWhere(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: UseRequiredChildWhereOptions): ReactElement;
+
+/**
+ * Normalizes a React children value into an array containing only valid direct child elements.
+ *
+ * @param children The React children value to normalize.
+ * @returns An array of valid React elements from the provided direct children.
+ */
+declare function childrenToElements(children: ReactNode): 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 ElementOfType, type UseMinimumChildrenWhereOptions, type UseRequiredChildWhereOptions, childrenToElements, isElementOfType, isReactElement, useChildByType, useChildWhere, useChildrenByType, useChildrenWhere, useHasChildWhere, useMinimumChildrenWhere, useRequiredChildWhere };

package/dist/index.d.ts

@@ -0,0 +1,127 @@
+import * as React from 'react';
+import { ElementType, ReactNode, ReactElement } from 'react';
+
+/**
+ * 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>;
+
+/**
+ * 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.
+ * @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;
+
+/**
+ * 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.
+ * @returns The first direct child element that satisfies the provided predicate, or `null` when no match is found.
+ */
+declare function useChildWhere<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): T | null;
+declare function useChildWhere(children: ReactNode, predicate: (element: ReactElement) => boolean): ReactElement | null;
+
+/**
+ * Returns the direct child elements 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.
+ * @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>[];
+
+/**
+ * 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.
+ * @returns An array of direct child elements that satisfy the provided predicate.
+ */
+declare function useChildrenWhere<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): T[];
+declare function useChildrenWhere(children: ReactNode, predicate: (element: ReactElement) => boolean): ReactElement[];
+
+/**
+ * Determines whether any direct child element 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.
+ * @returns `true` when at least one direct child element satisfies the provided predicate; otherwise `false`.
+ */
+declare function useHasChildWhere<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T): boolean;
+declare function useHasChildWhere(children: ReactNode, predicate: (element: ReactElement) => boolean): boolean;
+
+type UseMinimumChildrenWhereOptions = {
+    /**
+     * An optional consumer-defined trace code that is prefixed to the thrown validation message.
+     */
+    traceCode?: string;
+    /**
+     * An optional human-readable child name that is included in the thrown validation message.
+     */
+    childName?: string;
+};
+/**
+ * Returns the direct child elements that satisfy the provided predicate, or throws when fewer than the minimum count are 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 minimumCount The minimum number of matching direct child elements required.
+ * @param options Optional reporting metadata used to derive the thrown validation message.
+ * @returns The direct child elements that satisfy the provided predicate.
+ */
+declare function useMinimumChildrenWhere<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, minimumCount: number, options?: UseMinimumChildrenWhereOptions): T[];
+declare function useMinimumChildrenWhere(children: ReactNode, predicate: (element: ReactElement) => boolean, minimumCount: number, options?: UseMinimumChildrenWhereOptions): ReactElement[];
+
+type UseRequiredChildWhereOptions = {
+    /**
+     * An optional consumer-defined trace code that is prefixed to the thrown validation message.
+     */
+    traceCode?: string;
+    /**
+     * An optional human-readable child name that is included in the thrown validation message.
+     */
+    childName?: string;
+};
+/**
+ * Returns the first direct child element that satisfies the provided predicate, or throws when no 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 first direct child element that satisfies the provided predicate.
+ */
+declare function useRequiredChildWhere<T extends ReactElement>(children: ReactNode, predicate: (element: ReactElement) => element is T, options?: UseRequiredChildWhereOptions): T;
+declare function useRequiredChildWhere(children: ReactNode, predicate: (element: ReactElement) => boolean, options?: UseRequiredChildWhereOptions): ReactElement;
+
+/**
+ * Normalizes a React children value into an array containing only valid direct child elements.
+ *
+ * @param children The React children value to normalize.
+ * @returns An array of valid React elements from the provided direct children.
+ */
+declare function childrenToElements(children: ReactNode): 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 ElementOfType, type UseMinimumChildrenWhereOptions, type UseRequiredChildWhereOptions, childrenToElements, isElementOfType, isReactElement, useChildByType, useChildWhere, useChildrenByType, useChildrenWhere, useHasChildWhere, useMinimumChildrenWhere, useRequiredChildWhere };

package/dist/index.js

@@ -0,0 +1,115 @@
+// src/isElementOfType.ts
+function isElementOfType(element, type) {
+  return element.type === type;
+}
+
+// src/useChildWhere.ts
+import { useMemo } from "react";
+
+// src/childrenToElements.ts
+import { Children } from "react";
+
+// src/isReactElement.ts
+import { isValidElement } from "react";
+function isReactElement(node) {
+  return isValidElement(node);
+}
+
+// src/childrenToElements.ts
+function childrenToElements(children) {
+  return Children.toArray(children).filter(isReactElement);
+}
+
+// src/useChildWhere.ts
+function useChildWhere(children, predicate) {
+  return useMemo(
+    () => childrenToElements(children).find(predicate) ?? null,
+    [children, predicate]
+  );
+}
+
+// src/useChildByType.ts
+function useChildByType(children, type) {
+  return useChildWhere(
+    children,
+    (element) => isElementOfType(element, type)
+  );
+}
+
+// src/useChildrenWhere.ts
+import { useMemo as useMemo2 } from "react";
+function useChildrenWhere(children, predicate) {
+  return useMemo2(
+    () => childrenToElements(children).filter(predicate),
+    [children, predicate]
+  );
+}
+
+// src/useChildrenByType.ts
+function useChildrenByType(children, type) {
+  return useChildrenWhere(
+    children,
+    (element) => isElementOfType(element, type)
+  );
+}
+
+// src/useHasChildWhere.ts
+import { useMemo as useMemo3 } from "react";
+function useHasChildWhere(children, predicate) {
+  return useMemo3(
+    () => childrenToElements(children).some(predicate),
+    [children, predicate]
+  );
+}
+
+// src/reporter.ts
+import { createReporter } from "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 }}."
+};
+var reporter = createReporter(
+  process.env.NODE_ENV === "production" ? {} : messages,
+  { formatMessage: (message) => message }
+);
+var reporter_default = reporter;
+
+// src/useMinimumChildrenWhere.ts
+function useMinimumChildrenWhere(children, predicate, minimumCount, options) {
+  const matchingChildren = useChildrenWhere(children, predicate);
+  if (matchingChildren.length >= minimumCount) {
+    return matchingChildren;
+  }
+  return reporter_default.fail("MINIMUM_CHILDREN_WHERE_PREDICATE_FAILED", {
+    traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : "",
+    childNameSegment: options?.childName ? ` for ${options.childName}` : "",
+    actualCount: matchingChildren.length,
+    actualCountPluralSuffix: matchingChildren.length === 1 ? "" : "ren",
+    minimumCount
+  });
+}
+
+// src/useRequiredChildWhere.ts
+function useRequiredChildWhere(children, predicate, options) {
+  const child = useChildWhere(children, predicate);
+  if (child !== null) {
+    return child;
+  }
+  return reporter_default.fail("REQUIRED_CHILD_WHERE_PREDICATE_FAILED", {
+    traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : "",
+    childNameSegment: options?.childName ? ` for ${options.childName}` : ""
+  });
+}
+export {
+  childrenToElements,
+  isElementOfType,
+  isReactElement,
+  useChildByType,
+  useChildWhere,
+  useChildrenByType,
+  useChildrenWhere,
+  useHasChildWhere,
+  useMinimumChildrenWhere,
+  useRequiredChildWhere
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/isElementOfType.ts","../src/useChildWhere.ts","../src/childrenToElements.ts","../src/isReactElement.ts","../src/useChildByType.ts","../src/useChildrenWhere.ts","../src/useChildrenByType.ts","../src/useHasChildWhere.ts","../src/reporter.ts","../src/useMinimumChildrenWhere.ts","../src/useRequiredChildWhere.ts"],"sourcesContent":["import type { ElementType, ReactElement } from \"react\";\n\nimport type { ElementOfType } from \"./types\";\n\n/**\n * Determines whether a React element exactly matches the provided element or component type.\n *\n * @param element The React element to compare.\n * @param type The element or component type to match.\n * @returns `true` when the element's type exactly matches the provided type; otherwise `false`.\n */\nexport function isElementOfType<T extends ElementType>(\n    element: ReactElement,\n    type: T\n): element is ElementOfType<T> {\n    return element.type === type;\n}\n","import { useMemo, type ReactElement, type ReactNode } from \"react\";\n\nimport { childrenToElements } from \"./childrenToElements\";\n\n/**\n * Returns the first direct child element that satisfies the provided predicate.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it matches.\n * @returns The first direct child element that satisfies the provided predicate, or `null` when no match is found.\n */\nexport function useChildWhere<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T\n): T | null;\nexport function useChildWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean\n): ReactElement | null;\nexport function useChildWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean\n): ReactElement | null {\n    return useMemo(\n        () => childrenToElements(children).find(predicate) ?? null,\n        [children, predicate]\n    );\n}\n","import { Children, type ReactElement, type ReactNode } from \"react\";\n\nimport { isReactElement } from \"./isReactElement\";\n\n/**\n * Normalizes a React children value into an array containing only valid direct child elements.\n *\n * @param children The React children value to normalize.\n * @returns An array of valid React elements from the provided direct children.\n */\nexport function childrenToElements(children: ReactNode): ReactElement[] {\n    return Children.toArray(children).filter(isReactElement);\n}\n","import { isValidElement, type ReactElement, type ReactNode } from \"react\";\n\n/**\n * Determines whether a React node is a valid React element.\n *\n * @param node The React node to check.\n * @returns `true` when the node is a valid React element; otherwise `false`.\n */\nexport function isReactElement(node: ReactNode): node is ReactElement {\n    return isValidElement(node);\n}\n","import type { ElementType, ReactNode } from \"react\";\n\nimport { isElementOfType } from \"./isElementOfType\";\nimport { useChildWhere } from \"./useChildWhere\";\nimport type { ElementOfType } from \"./types\";\n\n/**\n * Returns the first direct child element whose React element type exactly matches the provided type.\n *\n * @param children The React children value to inspect.\n * @param type The element or component type to match against each direct child element.\n * @returns The first direct child element whose type matches the provided element type, or `null` when no match is found.\n */\nexport function useChildByType<T extends ElementType>(\n    children: ReactNode,\n    type: T\n): ElementOfType<T> | null {\n    return useChildWhere(children, (element): element is ElementOfType<T> =>\n        isElementOfType(element, type)\n    );\n}\n","import { useMemo, type ReactElement, type ReactNode } from \"react\";\n\nimport { childrenToElements } from \"./childrenToElements\";\n\n/**\n * Returns the direct child elements that satisfy the provided predicate.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it should be included in the result.\n * @returns An array of direct child elements that satisfy the provided predicate.\n */\nexport function useChildrenWhere<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T\n): T[];\nexport function useChildrenWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean\n): ReactElement[];\nexport function useChildrenWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean\n): ReactElement[] {\n    return useMemo(\n        () => childrenToElements(children).filter(predicate),\n        [children, predicate]\n    );\n}\n","import type { ElementType, ReactNode } from \"react\";\n\nimport { isElementOfType } from \"./isElementOfType\";\nimport { useChildrenWhere } from \"./useChildrenWhere\";\nimport type { ElementOfType } from \"./types\";\n\n/**\n * Returns the direct child elements whose React element type exactly matches the provided type.\n *\n * @param children The React children value to inspect.\n * @param type The element or component type to match against each direct child element.\n * @returns An array of direct child elements whose type matches the provided element type.\n */\nexport function useChildrenByType<T extends ElementType>(\n    children: ReactNode,\n    type: T\n): ElementOfType<T>[] {\n    return useChildrenWhere(children, (element): element is ElementOfType<T> =>\n        isElementOfType(element, type)\n    );\n}\n","import { useMemo, type ReactElement, type ReactNode } from \"react\";\n\nimport { childrenToElements } from \"./childrenToElements\";\n\n/**\n * Determines whether any direct child element satisfies the provided predicate.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it matches.\n * @returns `true` when at least one direct child element satisfies the provided predicate; otherwise `false`.\n */\nexport function useHasChildWhere<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T\n): boolean;\nexport function useHasChildWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean\n): boolean;\nexport function useHasChildWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean\n): boolean {\n    return useMemo(\n        () => childrenToElements(children).some(predicate),\n        [children, predicate]\n    );\n}\n","import { createReporter, type RuntimeReporterMessages } from \"runtime-reporter\";\n\nconst messages: RuntimeReporterMessages<\n    | {\n          code: \"REQUIRED_CHILD_WHERE_PREDICATE_FAILED\";\n          template: \"{{ traceCodePrefix }}Required child validation failed{{ childNameSegment }} because no direct child satisfied the provided predicate.\";\n          tokens: \"traceCodePrefix\" | \"childNameSegment\";\n      }\n    | {\n          code: \"MINIMUM_CHILDREN_WHERE_PREDICATE_FAILED\";\n          template: \"{{ traceCodePrefix }}Minimum children validation failed{{ childNameSegment }} because only {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected at least {{ minimumCount }}.\";\n          tokens:\n              | \"traceCodePrefix\"\n              | \"childNameSegment\"\n              | \"actualCount\"\n              | \"actualCountPluralSuffix\"\n              | \"minimumCount\";\n      }\n> = {\n    REQUIRED_CHILD_WHERE_PREDICATE_FAILED:\n        \"{{ traceCodePrefix }}Required child validation failed{{ childNameSegment }} because no direct child satisfied the provided predicate.\",\n    MINIMUM_CHILDREN_WHERE_PREDICATE_FAILED:\n        \"{{ traceCodePrefix }}Minimum children validation failed{{ childNameSegment }} because only {{ actualCount }} direct child{{ actualCountPluralSuffix }} satisfied the provided predicate; expected at least {{ minimumCount }}.\"\n};\n\n/** The runtime reporter for react-children-hooks */\nconst reporter = createReporter(\n    process.env.NODE_ENV === \"production\" ? ({} as typeof messages) : messages,\n    { formatMessage: (message) => message }\n);\n\nexport default reporter;\n","import type { ReactElement, ReactNode } from \"react\";\n\nimport reporter from \"./reporter\";\nimport { useChildrenWhere } from \"./useChildrenWhere\";\n\nexport type UseMinimumChildrenWhereOptions = {\n    /**\n     * An optional consumer-defined trace code that is prefixed to the thrown validation message.\n     */\n    traceCode?: string;\n    /**\n     * An optional human-readable child name that is included in the thrown validation message.\n     */\n    childName?: string;\n};\n\n/**\n * Returns the direct child elements that satisfy the provided predicate, or throws when fewer than the minimum count are found.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it matches.\n * @param minimumCount The minimum number of matching direct child elements required.\n * @param options Optional reporting metadata used to derive the thrown validation message.\n * @returns The direct child elements that satisfy the provided predicate.\n */\nexport function useMinimumChildrenWhere<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T,\n    minimumCount: number,\n    options?: UseMinimumChildrenWhereOptions\n): T[];\nexport function useMinimumChildrenWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    minimumCount: number,\n    options?: UseMinimumChildrenWhereOptions\n): ReactElement[];\nexport function useMinimumChildrenWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    minimumCount: number,\n    options?: UseMinimumChildrenWhereOptions\n): ReactElement[] {\n    const matchingChildren = useChildrenWhere(children, predicate);\n\n    if (matchingChildren.length >= minimumCount) {\n        return matchingChildren;\n    }\n\n    return reporter.fail(\"MINIMUM_CHILDREN_WHERE_PREDICATE_FAILED\", {\n        traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : \"\",\n        childNameSegment: options?.childName ? ` for ${options.childName}` : \"\",\n        actualCount: matchingChildren.length,\n        actualCountPluralSuffix: matchingChildren.length === 1 ? \"\" : \"ren\",\n        minimumCount\n    });\n}\n","import type { ReactElement, ReactNode } from \"react\";\n\nimport reporter from \"./reporter\";\nimport { useChildWhere } from \"./useChildWhere\";\n\nexport type UseRequiredChildWhereOptions = {\n    /**\n     * An optional consumer-defined trace code that is prefixed to the thrown validation message.\n     */\n    traceCode?: string;\n    /**\n     * An optional human-readable child name that is included in the thrown validation message.\n     */\n    childName?: string;\n};\n\n/**\n * Returns the first direct child element that satisfies the provided predicate, or throws when no match is found.\n *\n * @param children The React children value to inspect.\n * @param predicate A predicate that is called with each direct child element to determine whether it matches.\n * @param options Optional reporting metadata used to derive the thrown validation message.\n * @returns The first direct child element that satisfies the provided predicate.\n */\nexport function useRequiredChildWhere<T extends ReactElement>(\n    children: ReactNode,\n    predicate: (element: ReactElement) => element is T,\n    options?: UseRequiredChildWhereOptions\n): T;\nexport function useRequiredChildWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    options?: UseRequiredChildWhereOptions\n): ReactElement;\nexport function useRequiredChildWhere(\n    children: ReactNode,\n    predicate: (element: ReactElement) => boolean,\n    options?: UseRequiredChildWhereOptions\n): ReactElement {\n    const child = useChildWhere(children, predicate);\n\n    if (child !== null) {\n        return child;\n    }\n\n    return reporter.fail(\"REQUIRED_CHILD_WHERE_PREDICATE_FAILED\", {\n        traceCodePrefix: options?.traceCode ? `[${options.traceCode}] ` : \"\",\n        childNameSegment: options?.childName ? ` for ${options.childName}` : \"\"\n    });\n}\n"],"mappings":";AAWO,SAAS,gBACZ,SACA,MAC2B;AAC3B,SAAO,QAAQ,SAAS;AAC5B;;;AChBA,SAAS,eAAkD;;;ACA3D,SAAS,gBAAmD;;;ACA5D,SAAS,sBAAyD;AAQ3D,SAAS,eAAe,MAAuC;AAClE,SAAO,eAAe,IAAI;AAC9B;;;ADAO,SAAS,mBAAmB,UAAqC;AACpE,SAAO,SAAS,QAAQ,QAAQ,EAAE,OAAO,cAAc;AAC3D;;;ADOO,SAAS,cACZ,UACA,WACmB;AACnB,SAAO;AAAA,IACH,MAAM,mBAAmB,QAAQ,EAAE,KAAK,SAAS,KAAK;AAAA,IACtD,CAAC,UAAU,SAAS;AAAA,EACxB;AACJ;;;AGdO,SAAS,eACZ,UACA,MACuB;AACvB,SAAO;AAAA,IAAc;AAAA,IAAU,CAAC,YAC5B,gBAAgB,SAAS,IAAI;AAAA,EACjC;AACJ;;;ACpBA,SAAS,WAAAA,gBAAkD;AAmBpD,SAAS,iBACZ,UACA,WACc;AACd,SAAOC;AAAA,IACH,MAAM,mBAAmB,QAAQ,EAAE,OAAO,SAAS;AAAA,IACnD,CAAC,UAAU,SAAS;AAAA,EACxB;AACJ;;;ACdO,SAAS,kBACZ,UACA,MACkB;AAClB,SAAO;AAAA,IAAiB;AAAA,IAAU,CAAC,YAC/B,gBAAgB,SAAS,IAAI;AAAA,EACjC;AACJ;;;ACpBA,SAAS,WAAAC,gBAAkD;AAmBpD,SAAS,iBACZ,UACA,WACO;AACP,SAAOC;AAAA,IACH,MAAM,mBAAmB,QAAQ,EAAE,KAAK,SAAS;AAAA,IACjD,CAAC,UAAU,SAAS;AAAA,EACxB;AACJ;;;AC3BA,SAAS,sBAAoD;AAE7D,IAAM,WAgBF;AAAA,EACA,uCACI;AAAA,EACJ,yCACI;AACR;AAGA,IAAM,WAAW;AAAA,EACb,QAAQ,IAAI,aAAa,eAAgB,CAAC,IAAwB;AAAA,EAClE,EAAE,eAAe,CAAC,YAAY,QAAQ;AAC1C;AAEA,IAAO,mBAAQ;;;ACMR,SAAS,wBACZ,UACA,WACA,cACA,SACc;AACd,QAAM,mBAAmB,iBAAiB,UAAU,SAAS;AAE7D,MAAI,iBAAiB,UAAU,cAAc;AACzC,WAAO;AAAA,EACX;AAEA,SAAO,iBAAS,KAAK,2CAA2C;AAAA,IAC5D,iBAAiB,SAAS,YAAY,IAAI,QAAQ,SAAS,OAAO;AAAA,IAClE,kBAAkB,SAAS,YAAY,QAAQ,QAAQ,SAAS,KAAK;AAAA,IACrE,aAAa,iBAAiB;AAAA,IAC9B,yBAAyB,iBAAiB,WAAW,IAAI,KAAK;AAAA,IAC9D;AAAA,EACJ,CAAC;AACL;;;ACtBO,SAAS,sBACZ,UACA,WACA,SACY;AACZ,QAAM,QAAQ,cAAc,UAAU,SAAS;AAE/C,MAAI,UAAU,MAAM;AAChB,WAAO;AAAA,EACX;AAEA,SAAO,iBAAS,KAAK,yCAAyC;AAAA,IAC1D,iBAAiB,SAAS,YAAY,IAAI,QAAQ,SAAS,OAAO;AAAA,IAClE,kBAAkB,SAAS,YAAY,QAAQ,QAAQ,SAAS,KAAK;AAAA,EACzE,CAAC;AACL;","names":["useMemo","useMemo","useMemo","useMemo"]}

package/package.json

@@ -0,0 +1,91 @@
+{
+    "name": "react-children-hooks",
+    "version": "0.1.0",
+    "description": "React hooks for inspecting, traversing, querying, and validating props.children.",
+    "keywords": [
+        "react",
+        "children",
+        "hooks",
+        "components",
+        "typescript"
+    ],
+    "homepage": "https://github.com/marksmccann/react-children-hooks#readme",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/marksmccann/react-children-hooks.git"
+    },
+    "bugs": {
+        "url": "https://github.com/marksmccann/react-children-hooks/issues"
+    },
+    "license": "MIT",
+    "author": "Mark McCann",
+    "type": "module",
+    "main": "./dist/index.cjs",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "require": "./dist/index.cjs"
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "sideEffects": false,
+    "engines": {
+        "node": ">=18"
+    },
+    "scripts": {
+        "build": "tsup",
+        "commit": "cz",
+        "dev": "tsup --watch",
+        "format": "prettier --write .",
+        "lint": "eslint .",
+        "prepublishOnly": "npm run build",
+        "release": "release-it",
+        "typecheck": "tsc --project tsconfig.json --noEmit",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "prepare": "husky"
+    },
+    "config": {
+        "commitizen": {
+            "path": "cz-conventional-changelog"
+        }
+    },
+    "peerDependencies": {
+        "react": "^18.0.0 || ^19.0.0"
+    },
+    "devDependencies": {
+        "@commitlint/cli": "^19.8.0",
+        "@commitlint/config-conventional": "^19.8.0",
+        "@eslint/js": "^9.27.0",
+        "@release-it/conventional-changelog": "^10.0.2",
+        "@testing-library/react": "^16.3.2",
+        "@types/node": "^22.15.30",
+        "@types/react": "^19.1.5",
+        "@vitest/coverage-v8": "^3.1.4",
+        "commitizen": "^4.3.1",
+        "cz-conventional-changelog": "^3.3.0",
+        "eslint": "^9.27.0",
+        "eslint-config-prettier": "^10.1.5",
+        "eslint-plugin-react-hooks": "^5.2.0",
+        "globals": "^16.1.0",
+        "husky": "^9.1.7",
+        "jsdom": "^26.1.0",
+        "lint-staged": "^15.5.2",
+        "prettier": "^3.5.3",
+        "react": "^19.2.6",
+        "react-dom": "^19.2.6",
+        "release-it": "^19.0.4",
+        "tsup": "^8.5.0",
+        "typescript": "^5.8.3",
+        "typescript-eslint": "^8.32.1",
+        "vitest": "^3.1.4"
+    },
+    "dependencies": {
+        "runtime-reporter": "^0.7.0"
+    }
+}