Add observer methods to fragment instances (#32619)

This implements `observeUsing(observer)` and `unobserverUsing(observer)`
on fragment instances. IntersectionObservers and ResizeObservers can be
passed to observe each host child of the fragment. This is the
equivalent to calling `observer.observe(child)` or
`observer.unobserve(child)` for each child target.

Just like the addEventListener, the observer is held on the fragment
instance and applied to any newly mounted child. So you can do things
like wrap a paginated list in a fragment and have each child
automatically observed as they commit in.

Unlike, the event listeners though, we don't `unobserve` when a child is
removed. If a removed child is currently intersecting, the observer
callback will be called when it is removed with an empty rect. This lets
you track all the currently intersecting elements by setting state from
the observer callback and either adding or removing them from your list
depending on the intersecting state. If you want to track the removal of
items offscreen, you'd have to maintain that state separately and append
intersecting data to it in the observer callback. This is what the
fixture example does.

There could be more convenient ways of managing the state of multiple
child intersections, but basic examples are able to be modeled with the
simple implementation. Let's see how the usage goes as we integrate this
with more advanced loggers and other features.

For now you can only attach one observer to an instance. This could
change based on usage but the fragments are composable and could be
stacked as one way to apply multiple observers to the same elements.

In practice, one pattern we expect to enable is more composable logging
such as

```javascript
function Feed({ items }) {
  return (
    <ImpressionLogger>
      {items.map((item) => (
        <FeedItem />
      ))}
    </ImpressionLogger>
  );
}
```

where `ImpressionLogger` would set up the IntersectionObserver using a
fragment ref with the required business logic and various components
could layer it wherever the logging is needed. Currently most callsites
use a hook form, which can require wiring up refs through the tree and
merging refs for multiple loggers.

Author: jackpope

fixtures/dom/src/components/fixtures/fragment-refs/EventListenerCase.js

@@ -0,0 +1,96 @@
+import TestCase from '../../TestCase';
+import Fixture from '../../Fixture';
+
+const React = window.React;
+const {Fragment, useEffect, useRef, useState} = React;
+
+function WrapperComponent(props) {
+  return props.children;
+}
+
+function handler(e) {
+  const text = e.currentTarget.innerText;
+  alert('You clicked: ' + text);
+}
+
+export default function EventListenerCase() {
+  const fragmentRef = useRef(null);
+  const [extraChildCount, setExtraChildCount] = useState(0);
+
+  useEffect(() => {
+    fragmentRef.current.addEventListener('click', handler);
+
+    const lastFragmentRefValue = fragmentRef.current;
+    return () => {
+      lastFragmentRefValue.removeEventListener('click', handler);
+    };
+  });
+
+  return (
+    <TestCase title="Event Registration">
+      <TestCase.Steps>
+        <li>Click one of the children, observe the alert</li>
+        <li>Add a new child, click it, observe the alert</li>
+        <li>Remove the event listeners, click a child, observe no alert</li>
+        <li>Add the event listeners back, click a child, observe the alert</li>
+      </TestCase.Steps>
+
+      <TestCase.ExpectedResult>
+        <p>
+          Fragment refs can manage event listeners on the first level of host
+          children. This page loads with an effect that sets up click event
+          hanndlers on each child card. Clicking on a card will show an alert
+          with the card's text.
+        </p>
+        <p>
+          New child nodes will also have event listeners applied. Removed nodes
+          will have their listeners cleaned up.
+        </p>
+      </TestCase.ExpectedResult>
+
+      <Fixture>
+        <div className="control-box">
+          <div>Target count: {extraChildCount + 3}</div>
+          <button
+            onClick={() => {
+              setExtraChildCount(prev => prev + 1);
+            }}>
+            Add Child
+          </button>
+          <button
+            onClick={() => {
+              fragmentRef.current.addEventListener('click', handler);
+            }}>
+            Add click event listeners
+          </button>
+          <button
+            onClick={() => {
+              fragmentRef.current.removeEventListener('click', handler);
+            }}>
+            Remove click event listeners
+          </button>
+          <div class="card-container">
+            <Fragment ref={fragmentRef}>
+              <div className="card" id="child-a">
+                Child A
+              </div>
+              <div className="card" id="child-b">
+                Child B
+              </div>
+              <WrapperComponent>
+                <div className="card" id="child-c">
+                  Child C
+                </div>
+                {Array.from({length: extraChildCount}).map((_, index) => (
+                  <div className="card" id={'extra-child-' + index} key={index}>
+                    Extra Child {index}
+                  </div>
+                ))}
+              </WrapperComponent>
+            </Fragment>
+          </div>
+        </div>
+      </Fixture>
+    </TestCase>
+  );
+}

fixtures/dom/src/components/fixtures/fragment-refs/IntersectionObserverCase.js

@@ -0,0 +1,153 @@
+import TestCase from '../../TestCase';
+import Fixture from '../../Fixture';
+
+const React = window.React;
+const {Fragment, useEffect, useRef, useState} = React;
+
+function WrapperComponent(props) {
+  return props.children;
+}
+
+function ObservedChild({id}) {
+  return (
+    <div id={id} className="observable-card">
+      {id}
+    </div>
+  );
+}
+
+const initialItems = [
+  ['A', false],
+  ['B', false],
+  ['C', false],
+];
+
+export default function IntersectionObserverCase() {
+  const fragmentRef = useRef(null);
+  const [items, setItems] = useState(initialItems);
+  const addedItems = items.slice(3);
+  const anyOnScreen = items.some(([, onScreen]) => onScreen);
+  const observerRef = useRef(null);
+
+  useEffect(() => {
+    if (observerRef.current === null) {
+      observerRef.current = new IntersectionObserver(
+        entries => {
+          setItems(prev => {
+            const newItems = [...prev];
+            entries.forEach(entry => {
+              const index = newItems.findIndex(
+                ([id]) => id === entry.target.id
+              );
+              newItems[index] = [entry.target.id, entry.isIntersecting];
+            });
+            return newItems;
+          });
+        },
+        {
+          threshold: [0.5],
+        }
+      );
+    }
+    fragmentRef.current.observeUsing(observerRef.current);
+
+    const lastFragmentRefValue = fragmentRef.current;
+    return () => {
+      lastFragmentRefValue.unobserveUsing(observerRef.current);
+      observerRef.current = null;
+    };
+  }, []);
+
+  return (
+    <TestCase title="Intersection Observer">
+      <TestCase.Steps>
+        <li>
+          Scroll the children into view, observe the sidebar appears and shows
+          which children are in the viewport
+        </li>
+        <li>
+          Add a new child and observe that the Intersection Observer is applied
+        </li>
+        <li>
+          Click Unobserve and observe that the state of children in the viewport
+          is no longer updated
+        </li>
+        <li>
+          Click Observe and observe that the state of children in the viewport
+          is updated again
+        </li>
+      </TestCase.Steps>
+
+      <TestCase.ExpectedResult>
+        <p>
+          Fragment refs manage Intersection Observers on the first level of host
+          children. This page loads with an effect that sets up an Inersection
+          Observer applied to each child card.
+        </p>
+        <p>
+          New child nodes will also have the observer applied. Removed nodes
+          will be unobserved.
+        </p>
+      </TestCase.ExpectedResult>
+      <Fixture>
+        <button
+          onClick={() => {
+            setItems(prev => [
+              ...prev,
+              [`Extra child: ${prev.length + 1}`, false],
+            ]);
+          }}>
+          Add Child
+        </button>
+        <button
+          onClick={() => {
+            setItems(prev => {
+              if (prev.length === 3) {
+                return prev;
+              }
+              return prev.slice(0, prev.length - 1);
+            });
+          }}>
+          Remove Child
+        </button>
+        <button
+          onClick={() => {
+            fragmentRef.current.observeUsing(observerRef.current);
+          }}>
+          Observe
+        </button>
+        <button
+          onClick={() => {
+            fragmentRef.current.unobserveUsing(observerRef.current);
+            setItems(prev => {
+              return prev.map(item => [item[0], false]);
+            });
+          }}>
+          Unobserve
+        </button>
+        {anyOnScreen && (
+          <div className="fixed-sidebar card-container">
+            <p>
+              <strong>Children on screen:</strong>
+            </p>
+            {items.map(item => (
+              <div className={`card ${item[1] ? 'onscreen' : null}`}>
+                {item[0]}
+              </div>
+            ))}
+          </div>
+        )}
+        <Fragment ref={fragmentRef}>
+          <ObservedChild id="A" />
+          <WrapperComponent>
+            <ObservedChild id="B" />
+          </WrapperComponent>
+          <ObservedChild id="C" />
+          {addedItems.map((_, index) => (
+            <ObservedChild id={`Extra child: ${index + 4}`} />
+          ))}
+        </Fragment>
+      </Fixture>
+    </TestCase>
+  );
+}

fixtures/dom/src/components/fixtures/fragment-refs/ResizeObserverCase.js

@@ -0,0 +1,63 @@
+import TestCase from '../../TestCase';
+import Fixture from '../../Fixture';
+
+const React = window.React;
+const {Fragment, useEffect, useRef, useState} = React;
+
+export default function ResizeObserverCase() {
+  const fragmentRef = useRef(null);
+  const [width, setWidth] = useState([0, 0, 0]);
+
+  useEffect(() => {
+    const resizeObserver = new window.ResizeObserver(entries => {
+      if (entries.length > 0) {
+        setWidth(prev => {
+          const newWidth = [...prev];
+          entries.forEach(entry => {
+            const index = parseInt(entry.target.id, 10);
+            newWidth[index] = Math.round(entry.contentRect.width);
+          });
+          return newWidth;
+        });
+      }
+    });
+
+    fragmentRef.current.observeUsing(resizeObserver);
+    const lastFragmentRefValue = fragmentRef.current;
+    return () => {
+      lastFragmentRefValue.unobserveUsing(resizeObserver);
+    };
+  }, []);
+
+  return (
+    <TestCase title="Resize Observer">
+      <TestCase.Steps>
+        <li>Resize the viewport width until the children respond</li>
+        <li>See that the width data updates as they elements resize</li>
+      </TestCase.Steps>
+      <TestCase.ExpectedResult>
+        The Fragment Ref has a ResizeObserver attached which has a callback to
+        update the width state of each child node.
+      </TestCase.ExpectedResult>
+      <Fixture>
+        <Fragment ref={fragmentRef}>
+          <div className="card" id="0" style={{width: '100%'}}>
+            <p>
+              Width: <b>{width[0]}px</b>
+            </p>
+          </div>
+          <div className="card" id="1" style={{width: '80%'}}>
+            <p>
+              Width: <b>{width[1]}px</b>
+            </p>
+          </div>
+          <div className="card" id="2" style={{width: '50%'}}>
+            <p>
+              Width: <b>{width[2]}px</b>
+            </p>
+          </div>
+        </Fragment>
+      </Fixture>
+    </TestCase>
+  );
+}