feat(lib): Adds findChildren & restructure child query utils (#3156)

* mv existing utils

* isChildWithProperty

* Update findChild.tsx

* findChildren

* Fix isChildWithProperty tests

* update findChild tests

* Update findChildren.spec.tsx

* mv componentQueries

* update index files

* mv child queries

* Update index.ts

* Apply suggestions from code review

`allChildren.length === 1`

Co-authored-by: Copilot <[email protected]>

* Creates unwrapRootFragment

* update findChild/children with unwrapRootFragment

* Update findChildren.ts

* Update findChildren.ts

* Create lib-find-children.md

* Update packages/lib/src/childQueries/findChild/findChild.tsx

Co-authored-by: Stephen Lee <[email protected]>

* Update packages/lib/src/childQueries/findChildren/findChildren.ts

Co-authored-by: Stephen Lee <[email protected]>

* adds 2 level fragment test

* update index files

* rm wizard

* rm todo

* Update isChildWithProperty.spec.tsx

---------

Co-authored-by: Copilot <[email protected]>
Co-authored-by: Stephen Lee <[email protected]>

Author: 3 people

.changeset/lib-find-children.md

@@ -0,0 +1,5 @@
+---
+'@leafygreen-ui/lib': minor
+---
+
+Adds `findChildren` utility to `lib`. Also adds `unwrapRootFragment` and `isChildWithProperty` helpers

packages/lib/src/filterChildren/filterChildren.spec.tsx renamed to packages/lib/src/childQueries/filterChildren/filterChildren.spec.tsx

@@ -1,3 +1,9 @@
+/**
+ * Disabling `react/jsx-key` lets us pass `children` as an Iterable<ReactNode> directly to the test function
+ * instead of needing to wrap everything in a Fragment,
+ * which is not representative of real use-cases
+ */
+/* eslint-disable react/jsx-key */
 import React from 'react';
 import styled from '@emotion/styled';
 
@@ -24,28 +30,30 @@ Baz.displayName = 'Baz';
 (Bar as any).isBar = true;
 (Baz as any).isBaz = true;
 
-describe('findChild', () => {
+describe('packages/lib/findChild', () => {
+  test('should find a child component with matching static property', () => {
+    // Create an iterable to test different iteration scenarios
+    const children = [<Foo text="Foo" />, <Bar text="Bar" />];
+
+    const found = findChild(children, 'isFoo');
+    expect(found).toBeDefined();
+    expect((found as React.ReactElement).props.text).toBe('Foo');
+  });
+
   test('should find the first child component with matching static property', () => {
-    const children = (
-      <>
-        <Foo text="first" />
-        <Bar text="second" />
-        <Foo text="third" />
-      </>
-    );
+    const children = [
+      <Foo text="first" />,
+      <Bar text="second" />,
+      <Foo text="third" />,
+    ];
 
     const found = findChild(children, 'isFoo');
     expect(found).toBeDefined();
     expect((found as React.ReactElement).props.text).toBe('first');
   });
 
   test('should return undefined if no child matches', () => {
-    const children = (
-      <>
-        <Foo text="first" />
-        <Bar text="second" />
-      </>
-    );
+    const children = [<Foo text="first" />, <Bar text="second" />];
 
     const found = findChild(children, 'isBaz');
     expect(found).toBeUndefined();
@@ -56,18 +64,7 @@ describe('findChild', () => {
     expect(found).toBeUndefined();
   });
 
-  test('should work with array children', () => {
-    const children = [
-      <Foo key="1" text="first" />,
-      <Bar key="2" text="second" />,
-    ];
-
-    const found = findChild(children, 'isBar');
-    expect(found).toBeDefined();
-    expect((found as React.ReactElement).props.text).toBe('second');
-  });
-
-  test('should handle fragment children', () => {
+  test('should handle a single-level of fragment children', () => {
     const children = (
       <React.Fragment>
         <Foo text="in-fragment" />
@@ -80,62 +77,41 @@ describe('findChild', () => {
     expect((found as React.ReactElement).props.text).toBe('also-in-fragment');
   });
 
-  test('should find first match even with multiple matches', () => {
+  test('should NOT find components in deeply nested fragments (search depth limitation)', () => {
     const children = (
-      <>
-        <Foo text="first-match" />
-        <Foo text="second-match" />
-        <Bar text="different" />
-      </>
+      <React.Fragment>
+        <React.Fragment>
+          <Foo text="deeply-nested" />
+          <Bar text="also-in-fragment" />
+        </React.Fragment>
+      </React.Fragment>
     );
 
+    // Should NOT find the deeply nested Foo instances
     const found = findChild(children, 'isFoo');
-    expect(found).toBeDefined();
-    expect((found as React.ReactElement).props.text).toBe('first-match');
+    expect(found).toBeUndefined();
   });
 
-  test('should NOT find deeply nested components (search depth limitation)', () => {
+  test('should NOT find components wrapped in other elements', () => {
     const children = (
-      <>
-        {/* Nested fragment - should NOT find */}
-        <React.Fragment>
-          <React.Fragment>
-            <Foo text="deeply-nested" />
-          </React.Fragment>
-        </React.Fragment>
-
-        {/* Component inside div - should NOT find */}
-        <div>
-          <Foo text="inside-div" />
-        </div>
-
-        <Bar text="direct-child" />
-      </>
+      <div>
+        <Foo text="inside-div" />
+      </div>
     );
 
     // Should NOT find the deeply nested Foo instances
     const found = findChild(children, 'isFoo');
     expect(found).toBeUndefined();
-
-    // Should find the direct Bar
-    const found2 = findChild(children, 'isBar');
-    expect(found2).toBeDefined();
-    expect((found2 as React.ReactElement).props.text).toBe('direct-child');
   });
 
   test('should work with styled components from @emotion/styled', () => {
     // Create a real styled component using the actual styled() function
-    const RealStyledFoo = styled(Foo)`
+    const StyledFoo = styled(Foo)`
       background-color: red;
       padding: 8px;
     `;
 
-    const children = (
-      <>
-        <RealStyledFoo text="real-styled" />
-        <Bar text="regular" />
-      </>
-    );
+    const children = [<StyledFoo text="real-styled" />, <Bar text="regular" />];
 
     // The key test: findChild should find the styled component
     const found = findChild(children, 'isFoo');

packages/lib/src/filterChildren/filterChildren.tsx renamed to packages/lib/src/childQueries/filterChildren/filterChildren.tsx

@@ -0,0 +1,49 @@
+import { Children, ReactElement, ReactNode } from 'react';
+
+import { isChildWithProperty } from '../isChildWithProperty';
+import { unwrapRootFragment } from '../unwrapRootFragment';
+
+/**
+ * Find the first child component with a matching static property
+ *
+ * **Search Depth:** This function only searches 1 level deep:
+ * - Direct children of the provided children
+ * - Direct children inside React.Fragment components (1 level of fragment nesting)
+ * - Does NOT recursively search nested fragments or deeply nested components
+ *
+ * **Styled Component Support:** Checks component.target and component.__emotion_base
+ * for styled() wrapped components.
+ *
+ * @example
+ * ```ts
+ * // ✅ Will find: Direct child
+ * findChild(<Foo />, 'isFoo') // <Foo />
+ *
+ * // ✅ Will find: Child inside a single fragment
+ * findChild(<><Foo /></>, 'isFoo') // <Foo />
+ *
+ * // ❌ Will NOT find: Deeply nested fragments
+ * findChild(<><><Foo /></></>, 'isFoo') // undefined
+ *
+ * // ❌ Will NOT find: Nested in other elements
+ * findChild(<div><Foo /></div>, 'isFoo') // undefined
+ * ```
+ *
+ * @param children Any React children
+ * @param staticProperty The static property name to check for
+ * @returns The first matching ReactElement or undefined if not found
+ */
+export const findChild = (
+  children: ReactNode,
+  staticProperty: string,
+): ReactElement | undefined => {
+  if (!children || Children.count(children) === 0) {
+    return undefined;
+  }
+
+  const allChildren = unwrapRootFragment(children);
+
+  return allChildren?.find(child =>
+    isChildWithProperty(child, staticProperty),
+  ) as ReactElement | undefined;
+};

packages/lib/src/filterChildren/index.ts renamed to packages/lib/src/childQueries/filterChildren/index.ts

@@ -0,0 +1,186 @@
+/**
+ * Disabling `react/jsx-key` lets us pass `children` as an Iterable<ReactNode> directly to the test function
+ * instead of needing to wrap everything in a Fragment,
+ * which is not representative of real use-cases
+ */
+/* eslint-disable react/jsx-key */
+import React, { Fragment } from 'react';
+import styled from '@emotion/styled';
+
+import { findChildren } from './findChildren';
+
+// Test components
+const Foo = React.forwardRef<HTMLDivElement, { text: string }>(
+  ({ text }, ref) => <div ref={ref}>{text}</div>,
+);
+Foo.displayName = 'Foo';
+
+const Bar = React.forwardRef<HTMLDivElement, { text: string }>(
+  ({ text }, ref) => <div ref={ref}>{text}</div>,
+);
+Bar.displayName = 'Bar';
+
+const Baz = React.forwardRef<HTMLDivElement, { text: string }>(
+  ({ text }, ref) => <div ref={ref}>{text}</div>,
+);
+Baz.displayName = 'Baz';
+
+// Add static properties to test components with type assertion
+(Foo as any).isFoo = true;
+(Bar as any).isBar = true;
+(Baz as any).isBaz = true;
+
+describe('packages/lib/findChildren', () => {
+  describe('basic functionality', () => {
+    it('should find all children with matching static property', () => {
+      const children = [
+        <Foo text="first" />,
+        <Bar text="second" />,
+        <Foo text="third" />,
+        <Baz text="fourth" />,
+        <Foo text="fifth" />,
+      ];
+
+      const found = findChildren(children, 'isFoo');
+      expect(found).toHaveLength(3);
+      expect(found[0].props.text).toBe('first');
+      expect(found[1].props.text).toBe('third');
+      expect(found[2].props.text).toBe('fifth');
+    });
+
+    it('should return empty array if no children match', () => {
+      const children = [<Foo text="first" />, <Bar text="second" />];
+
+      const found = findChildren(children, 'isBaz');
+      expect(found).toEqual([]);
+    });
+
+    it('should find single matching child', () => {
+      const children = [
+        <Foo key="1" text="only-foo" />,
+        <Bar key="2" text="second" />,
+      ];
+
+      const found = findChildren(children, 'isFoo');
+      expect(found).toHaveLength(1);
+      expect(found[0].props.text).toBe('only-foo');
+    });
+  });
+
+  describe('empty and null children handling', () => {
+    it('should handle null children', () => {
+      const found = findChildren(null, 'isFoo');
+      expect(found).toEqual([]);
+    });
+
+    it('should handle undefined children', () => {
+      const found = findChildren(undefined, 'isFoo');
+      expect(found).toEqual([]);
+    });
+
+    it('should handle empty fragment', () => {
+      const children = <></>;
+      const found = findChildren(children, 'isFoo');
+      expect(found).toEqual([]);
+    });
+
+    it('should handle empty array children', () => {
+      const children: Array<React.ReactElement> = [];
+      const found = findChildren(children, 'isFoo');
+      expect(found).toEqual([]);
+    });
+  });
+
+  describe('Fragment handling', () => {
+    it('should handle single-level fragment children', () => {
+      const children = (
+        <React.Fragment>
+          <Foo text="foo-in-fragment" />
+          <Bar text="bar-in-fragment" />
+          <Foo text="another-foo" />
+        </React.Fragment>
+      );
+
+      const found = findChildren(children, 'isFoo');
+      expect(found).toHaveLength(2);
+      expect(found[0].props.text).toBe('foo-in-fragment');
+      expect(found[1].props.text).toBe('another-foo');
+    });
+
+    it('should NOT find children in deeply nested Fragments', () => {
+      const children = (
+        <React.Fragment>
+          <Foo text="direct-foo" />
+          <React.Fragment>
+            <React.Fragment>
+              <Foo text="deeply-nested-foo" />
+            </React.Fragment>
+          </React.Fragment>
+          <Bar text="direct-bar" />
+        </React.Fragment>
+      );
+
+      // Should only find direct children, not double-nested ones
+      const found = findChildren(children, 'isFoo');
+      expect(found).toHaveLength(1);
+      expect(found[0].props.text).toBe('direct-foo');
+    });
+  });
+
+  describe('styled components', () => {
+    it('should work with styled components from @emotion/styled', () => {
+      const StyledFoo = styled(Foo)`
+        background-color: red;
+        padding: 8px;
+      `;
+
+      const children = [
+        <Foo text="regular-foo" />,
+        <StyledFoo text="styled-foo" />,
+        <StyledFoo text="styled-foo-two" />,
+        <Bar text="regular-bar" />,
+        <Foo text="another-foo" />,
+      ];
+
+      const found = findChildren(children, 'isFoo');
+      expect(found).toHaveLength(4);
+      expect(found.map(c => c.props.text)).toEqual([
+        'regular-foo',
+        'styled-foo',
+        'styled-foo-two',
+        'another-foo',
+      ]);
+
+      // Verify the styled component is actually styled
+      const styledComponent = found[1];
+      const styledType = styledComponent.type as any;
+      const hasEmotionProps = !!(
+        styledType.target || styledType.__emotion_base
+      );
+      expect(hasEmotionProps).toBe(true);
+    });
+  });
+
+  describe('search depth limitations', () => {
+    it('should NOT find deeply nested components', () => {
+      const children = [
+        <Fragment>
+          <Foo text="single-fragment" />
+        </Fragment>,
+        <Fragment>
+          <Fragment>
+            <Foo text="double-nested" />
+          </Fragment>
+        </Fragment>,
+        <div>
+          <Foo text="inside-div" />
+        </div>,
+        <Foo text="direct-child" />,
+      ];
+
+      const found = findChildren(children, 'isFoo');
+      expect(found).toHaveLength(1);
+      expect(found[0].props.text).toBe('direct-child');
+    });
+  });
+});