@react-aria/collections 3.0.0-alpha.1 → 3.0.0-nightly.2986

package/dist/useCachedChildren.module.js

@@ -0,0 +1,58 @@
+import {useMemo as $luMFQ$useMemo, cloneElement as $luMFQ$cloneElement} from "react";
+
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */ 
+function $e948873055cbafe4$export$727c8fc270210f13(props) {
+    let { children: children, items: items, idScope: idScope, addIdAndValue: addIdAndValue, dependencies: dependencies = [] } = props;
+    // Invalidate the cache whenever the parent value changes.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    let cache = (0, $luMFQ$useMemo)(()=>new WeakMap(), dependencies);
+    return (0, $luMFQ$useMemo)(()=>{
+        if (items && typeof children === 'function') {
+            let res = [];
+            for (let item of items){
+                let rendered = cache.get(item);
+                if (!rendered) {
+                    rendered = children(item);
+                    var _rendered_props_id, _ref;
+                    // @ts-ignore
+                    let key = (_ref = (_rendered_props_id = rendered.props.id) !== null && _rendered_props_id !== void 0 ? _rendered_props_id : item.key) !== null && _ref !== void 0 ? _ref : item.id;
+                    // eslint-disable-next-line max-depth
+                    if (key == null) throw new Error('Could not determine key for item');
+                    // eslint-disable-next-line max-depth
+                    if (idScope) key = idScope + ':' + key;
+                    // Note: only works if wrapped Item passes through id...
+                    rendered = (0, $luMFQ$cloneElement)(rendered, addIdAndValue ? {
+                        key: key,
+                        id: key,
+                        value: item
+                    } : {
+                        key: key
+                    });
+                    cache.set(item, rendered);
+                }
+                res.push(rendered);
+            }
+            return res;
+        } else if (typeof children !== 'function') return children;
+    }, [
+        children,
+        items,
+        cache,
+        idScope,
+        addIdAndValue
+    ]);
+}
+
+
+export {$e948873055cbafe4$export$727c8fc270210f13 as useCachedChildren};
+//# sourceMappingURL=useCachedChildren.module.js.map

package/dist/useCachedChildren.module.js.map

@@ -0,0 +1 @@
+{"mappings":";;AAAA;;;;;;;;;;CAUC;AAsBM,SAAS,0CAAoC,KAA+B;IACjF,IAAI,YAAC,QAAQ,SAAE,KAAK,WAAE,OAAO,iBAAE,aAAa,gBAAE,eAAe,EAAE,EAAC,GAAG;IAEnE,0DAA0D;IAC1D,uDAAuD;IACvD,IAAI,QAAQ,CAAA,GAAA,cAAM,EAAE,IAAM,IAAI,WAAW;IACzC,OAAO,CAAA,GAAA,cAAM,EAAE;QACb,IAAI,SAAS,OAAO,aAAa,YAAY;YAC3C,IAAI,MAAsB,EAAE;YAC5B,KAAK,IAAI,QAAQ,MAAO;gBACtB,IAAI,WAAW,MAAM,GAAG,CAAC;gBACzB,IAAI,CAAC,UAAU;oBACb,WAAW,SAAS;wBAEV,oBAAA;oBADV,aAAa;oBACb,IAAI,MAAM,CAAA,OAAA,CAAA,qBAAA,SAAS,KAAK,CAAC,EAAE,cAAjB,gCAAA,qBAAqB,KAAK,GAAG,cAA7B,kBAAA,OAAiC,KAAK,EAAE;oBAClD,qCAAqC;oBACrC,IAAI,OAAO,MACT,MAAM,IAAI,MAAM;oBAElB,qCAAqC;oBACrC,IAAI,SACF,MAAM,UAAU,MAAM;oBAExB,wDAAwD;oBACxD,WAAW,CAAA,GAAA,mBAAW,EACpB,UACA,gBAAgB;6BAAC;wBAAK,IAAI;wBAAK,OAAO;oBAAI,IAAI;6BAAC;oBAAG;oBAEpD,MAAM,GAAG,CAAC,MAAM;gBAClB;gBACA,IAAI,IAAI,CAAC;YACX;YACA,OAAO;QACT,OAAO,IAAI,OAAO,aAAa,YAC7B,OAAO;IAEX,GAAG;QAAC;QAAU;QAAO;QAAO;QAAS;KAAc;AACrD","sources":["packages/@react-aria/collections/src/useCachedChildren.ts"],"sourcesContent":["/*\n * Copyright 2024 Adobe. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nimport {cloneElement, ReactElement, ReactNode, useMemo} from 'react';\nimport {Key} from '@react-types/shared';\n\nexport interface CachedChildrenOptions<T> {\n  /** Item objects in the collection. */\n  items?: Iterable<T>,\n  /** The contents of the collection. */\n  children?: ReactNode | ((item: T) => ReactNode),\n  /** Values that should invalidate the item cache when using dynamic collections. */\n  dependencies?: any[],\n  /** A scope to prepend to all child item ids to ensure they are unique. */\n  idScope?: Key,\n  /** Whether to add `id` and `value` props to all child items. */\n  addIdAndValue?: boolean\n}\n\n/**\n * Maps over a list of items and renders React elements for them. Each rendered item is\n * cached based on object identity, and React keys are generated from the `key` or `id` property.\n */\nexport function useCachedChildren<T extends object>(props: CachedChildrenOptions<T>): ReactNode {\n  let {children, items, idScope, addIdAndValue, dependencies = []} = props;\n\n  // Invalidate the cache whenever the parent value changes.\n  // eslint-disable-next-line react-hooks/exhaustive-deps\n  let cache = useMemo(() => new WeakMap(), dependencies);\n  return useMemo(() => {\n    if (items && typeof children === 'function') {\n      let res: ReactElement[] = [];\n      for (let item of items) {\n        let rendered = cache.get(item);\n        if (!rendered) {\n          rendered = children(item);\n          // @ts-ignore\n          let key = rendered.props.id ?? item.key ?? item.id;\n          // eslint-disable-next-line max-depth\n          if (key == null) {\n            throw new Error('Could not determine key for item');\n          }\n          // eslint-disable-next-line max-depth\n          if (idScope) {\n            key = idScope + ':' + key;\n          }\n          // Note: only works if wrapped Item passes through id...\n          rendered = cloneElement(\n            rendered,\n            addIdAndValue ? {key, id: key, value: item} : {key}\n          );\n          cache.set(item, rendered);\n        }\n        res.push(rendered);\n      }\n      return res;\n    } else if (typeof children !== 'function') {\n      return children;\n    }\n  }, [children, items, cache, idScope, addIdAndValue]);\n}\n"],"names":[],"version":3,"file":"useCachedChildren.module.js.map"}

package/package.json

@@ -1,32 +1,39 @@
 {
   "name": "@react-aria/collections",
-  "version": "3.0.0-alpha.1",
+  "version": "3.0.0-nightly.2986+b940126e4",
   "description": "Spectrum UI components in React",
   "license": "Apache-2.0",
   "main": "dist/main.js",
   "module": "dist/module.js",
   "types": "dist/types.d.ts",
+  "exports": {
+    "types": "./dist/types.d.ts",
+    "import": "./dist/import.mjs",
+    "require": "./dist/main.js"
+  },
   "source": "src/index.ts",
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "sideEffects": false,
   "repository": {
     "type": "git",
-    "url": "https://github.com/adobe-private/react-spectrum-v3"
+    "url": "https://github.com/adobe/react-spectrum"
   },
   "dependencies": {
-    "@babel/runtime": "^7.6.2",
-    "@react-aria/utils": "^3.0.0-rc.2",
-    "@react-stately/collections": "^3.0.0-alpha.1",
-    "@react-types/shared": "^3.0.0-rc.2"
+    "@react-aria/ssr": "3.9.5-nightly.4698+b940126e4",
+    "@react-aria/utils": "3.0.0-nightly.2986+b940126e4",
+    "@react-types/shared": "3.0.0-nightly.2986+b940126e4",
+    "@swc/helpers": "^0.5.0",
+    "use-sync-external-store": "^1.2.0"
   },
   "peerDependencies": {
-    "react": "^16.8.0",
-    "react-dom": "^16.8.0"
+    "react": "^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0",
+    "react-dom": "^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "207e6ee9076905c96638a7f81a367758872e1410"
+  "gitHead": "b940126e4d67a11d28b7c0b098eab23205598b6c"
 }

package/src/BaseCollection.ts

@@ -0,0 +1,211 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import {Collection as ICollection, Key, Node} from '@react-types/shared';
+import {ReactElement, ReactNode} from 'react';
+
+export type Mutable<T> = {
+  -readonly[P in keyof T]: T[P]
+}
+
+/** An immutable object representing a Node in a Collection. */
+export class NodeValue<T> implements Node<T> {
+  readonly type: string;
+  readonly key: Key;
+  readonly value: T | null = null;
+  readonly level: number = 0;
+  readonly hasChildNodes: boolean = false;
+  readonly rendered: ReactNode = null;
+  readonly textValue: string = '';
+  readonly 'aria-label'?: string = undefined;
+  readonly index: number = 0;
+  readonly parentKey: Key | null = null;
+  readonly prevKey: Key | null = null;
+  readonly nextKey: Key | null = null;
+  readonly firstChildKey: Key | null = null;
+  readonly lastChildKey: Key | null = null;
+  readonly props: any = {};
+  readonly render?: (node: Node<any>) => ReactElement;
+
+  constructor(type: string, key: Key) {
+    this.type = type;
+    this.key = key;
+  }
+
+  get childNodes(): Iterable<Node<T>> {
+    throw new Error('childNodes is not supported');
+  }
+
+  clone(): NodeValue<T> {
+    let node: Mutable<NodeValue<T>> = new NodeValue(this.type, this.key);
+    node.value = this.value;
+    node.level = this.level;
+    node.hasChildNodes = this.hasChildNodes;
+    node.rendered = this.rendered;
+    node.textValue = this.textValue;
+    node['aria-label'] = this['aria-label'];
+    node.index = this.index;
+    node.parentKey = this.parentKey;
+    node.prevKey = this.prevKey;
+    node.nextKey = this.nextKey;
+    node.firstChildKey = this.firstChildKey;
+    node.lastChildKey = this.lastChildKey;
+    node.props = this.props;
+    node.render = this.render;
+    return node;
+  }
+}
+
+/**
+ * An immutable Collection implementation. Updates are only allowed
+ * when it is not marked as frozen. This can be subclassed to implement
+ * custom collection behaviors.
+ */
+export class BaseCollection<T> implements ICollection<Node<T>> {
+  private keyMap: Map<Key, NodeValue<T>> = new Map();
+  private firstKey: Key | null = null;
+  private lastKey: Key | null = null;
+  private frozen = false;
+
+  get size() {
+    return this.keyMap.size;
+  }
+
+  getKeys() {
+    return this.keyMap.keys();
+  }
+
+  *[Symbol.iterator]() {
+    let node: Node<T> | undefined = this.firstKey != null ? this.keyMap.get(this.firstKey) : undefined;
+    while (node) {
+      yield node;
+      node = node.nextKey != null ? this.keyMap.get(node.nextKey) : undefined;
+    }
+  }
+
+  getChildren(key: Key): Iterable<Node<T>> {
+    let keyMap = this.keyMap;
+    return {
+      *[Symbol.iterator]() {
+        let parent = keyMap.get(key);
+        let node = parent?.firstChildKey != null ? keyMap.get(parent.firstChildKey) : null;
+        while (node) {
+          yield node as Node<T>;
+          node = node.nextKey != null ? keyMap.get(node.nextKey) : undefined;
+        }
+      }
+    };
+  }
+
+  getKeyBefore(key: Key) {
+    let node = this.keyMap.get(key);
+    if (!node) {
+      return null;
+    }
+
+    if (node.prevKey != null) {
+      node = this.keyMap.get(node.prevKey);
+
+      while (node && node.type !== 'item' && node.lastChildKey != null) {
+        node = this.keyMap.get(node.lastChildKey);
+      }
+
+      return node?.key ?? null;
+    }
+
+    return node.parentKey;
+  }
+
+  getKeyAfter(key: Key) {
+    let node = this.keyMap.get(key);
+    if (!node) {
+      return null;
+    }
+
+    if (node.type !== 'item' && node.firstChildKey != null) {
+      return node.firstChildKey;
+    }
+
+    while (node) {
+      if (node.nextKey != null) {
+        return node.nextKey;
+      }
+
+      if (node.parentKey != null) {
+        node = this.keyMap.get(node.parentKey);
+      } else {
+        return null;
+      }
+    }
+
+    return null;
+  }
+
+  getFirstKey() {
+    return this.firstKey;
+  }
+
+  getLastKey() {
+    let node = this.lastKey != null ? this.keyMap.get(this.lastKey) : null;
+    while (node?.lastChildKey != null) {
+      node = this.keyMap.get(node.lastChildKey);
+    }
+
+    return node?.key ?? null;
+  }
+
+  getItem(key: Key): Node<T> | null {
+    return this.keyMap.get(key) ?? null;
+  }
+
+  at(): Node<T> {
+    throw new Error('Not implemented');
+  }
+
+  clone(): this {
+    // We need to clone using this.constructor so that subclasses have the right prototype.
+    // TypeScript isn't happy about this yet.
+    // https://github.com/microsoft/TypeScript/issues/3841
+    let Constructor: any = this.constructor;
+    let collection: this = new Constructor();
+    collection.keyMap = new Map(this.keyMap);
+    collection.firstKey = this.firstKey;
+    collection.lastKey = this.lastKey;
+    return collection;
+  }
+
+  addNode(node: NodeValue<T>) {
+    if (this.frozen) {
+      throw new Error('Cannot add a node to a frozen collection');
+    }
+
+    this.keyMap.set(node.key, node);
+  }
+
+  removeNode(key: Key) {
+    if (this.frozen) {
+      throw new Error('Cannot remove a node to a frozen collection');
+    }
+
+    this.keyMap.delete(key);
+  }
+
+  commit(firstKey: Key | null, lastKey: Key | null, isSSR = false) {
+    if (this.frozen) {
+      throw new Error('Cannot commit a frozen collection');
+    }
+
+    this.firstKey = firstKey;
+    this.lastKey = lastKey;
+    this.frozen = !isSSR;
+  }
+}

package/src/CollectionBuilder.tsx

@@ -0,0 +1,237 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import {BaseCollection} from './BaseCollection';
+import {BaseNode, Document, ElementNode} from './Document';
+import {CachedChildrenOptions, useCachedChildren} from './useCachedChildren';
+import {createPortal} from 'react-dom';
+import {forwardRefType, Node} from '@react-types/shared';
+import {Hidden} from './Hidden';
+import React, {createContext, ForwardedRef, forwardRef, JSX, ReactElement, ReactNode, useCallback, useContext, useMemo, useRef, useState} from 'react';
+import {useIsSSR} from '@react-aria/ssr';
+import {useLayoutEffect} from '@react-aria/utils';
+import {useSyncExternalStore as useSyncExternalStoreShim} from 'use-sync-external-store/shim/index.js';
+
+const ShallowRenderContext = createContext(false);
+const CollectionDocumentContext = createContext<Document<any, BaseCollection<any>> | null>(null);
+
+export interface CollectionBuilderProps<C extends BaseCollection<object>> {
+  content: ReactNode,
+  children: (collection: C) => ReactNode,
+  createCollection?: () => C
+}
+
+/**
+ * Builds a `Collection` from the children provided to the `content` prop, and passes it to the child render prop function.
+ */
+export function CollectionBuilder<C extends BaseCollection<object>>(props: CollectionBuilderProps<C>) {
+  // If a document was provided above us, we're already in a hidden tree. Just render the content.
+  let doc = useContext(CollectionDocumentContext);
+  if (doc) {
+    return props.content;
+  }
+
+  // Otherwise, render a hidden copy of the children so that we can build the collection before constructing the state.
+  // This should always come before the real DOM content so we have built the collection by the time it renders during SSR.
+
+  // This is fine. CollectionDocumentContext never changes after mounting.
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  let {collection, document} = useCollectionDocument(props.createCollection);
+  return (
+    <>
+      <Hidden>
+        <CollectionDocumentContext.Provider value={document}>
+          {props.content}
+        </CollectionDocumentContext.Provider>
+      </Hidden>
+      <CollectionInner render={props.children} collection={collection} />
+    </>
+  );
+}
+
+function CollectionInner({collection, render}) {
+  return render(collection);
+}
+
+interface CollectionDocumentResult<T, C extends BaseCollection<T>> {
+  collection: C,
+  document: Document<T, C>
+}
+
+// React 16 and 17 don't support useSyncExternalStore natively, and the shim provided by React does not support getServerSnapshot.
+// This wrapper uses the shim, but additionally calls getServerSnapshot during SSR (according to SSRProvider).
+function useSyncExternalStoreFallback<C>(subscribe: (onStoreChange: () => void) => () => void, getSnapshot: () => C, getServerSnapshot: () => C): C {
+  let isSSR = useIsSSR();
+  let isSSRRef = useRef(isSSR);
+  // This is read immediately inside the wrapper, which also runs during render.
+  // We just need a ref to avoid invalidating the callback itself, which
+  // would cause React to re-run the callback more than necessary.
+  // eslint-disable-next-line rulesdir/pure-render
+  isSSRRef.current = isSSR;
+
+  let getSnapshotWrapper = useCallback(() => {
+    return isSSRRef.current ? getServerSnapshot() : getSnapshot();
+  }, [getSnapshot, getServerSnapshot]);
+  return useSyncExternalStoreShim(subscribe, getSnapshotWrapper);
+}
+
+const useSyncExternalStore = typeof React['useSyncExternalStore'] === 'function'
+  ? React['useSyncExternalStore']
+  : useSyncExternalStoreFallback;
+
+function useCollectionDocument<T extends object, C extends BaseCollection<T>>(createCollection?: () => C): CollectionDocumentResult<T, C> {
+  // The document instance is mutable, and should never change between renders.
+  // useSyncExternalStore is used to subscribe to updates, which vends immutable Collection objects.
+  let [document] = useState(() => new Document<T, C>(createCollection?.() || new BaseCollection() as C));
+  let subscribe = useCallback((fn: () => void) => document.subscribe(fn), [document]);
+  let getSnapshot = useCallback(() => {
+    let collection = document.getCollection();
+    if (document.isSSR) {
+      // After SSR is complete, reset the document to empty so it is ready for React to render the portal into.
+      // We do this _after_ getting the collection above so that the collection still has content in it from SSR
+      // during the current render, before React has finished the client render.
+      document.resetAfterSSR();
+    }
+    return collection;
+  }, [document]);
+  let getServerSnapshot = useCallback(() => {
+    document.isSSR = true;
+    return document.getCollection();
+  }, [document]);
+  let collection = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+  useLayoutEffect(() => {
+    document.isMounted = true;
+    return () => {
+      // Mark unmounted so we can skip all of the collection updates caused by 
+      // React calling removeChild on every item in the collection.
+      document.isMounted = false;
+    };
+  }, [document]);
+  return {collection, document};
+}
+
+const SSRContext = createContext<BaseNode<any> | null>(null);
+
+function useSSRCollectionNode<T extends Element>(Type: string, props: object, ref: ForwardedRef<T>, rendered?: any, children?: ReactNode, render?: (node: Node<T>) => ReactElement) {
+  // During SSR, portals are not supported, so the collection children will be wrapped in an SSRContext.
+  // Since SSR occurs only once, we assume that the elements are rendered in order and never re-render.
+  // Therefore we can create elements in our collection document during render so that they are in the
+  // collection by the time we need to use the collection to render to the real DOM.
+  // After hydration, we switch to client rendering using the portal.
+  let itemRef = useCallback((element: ElementNode<any> | null) => {
+    element?.setProps(props, ref, rendered, render);
+  }, [props, ref, rendered, render]);
+  let parentNode = useContext(SSRContext);
+  if (parentNode) {
+    // Guard against double rendering in strict mode.
+    let element = parentNode.ownerDocument.nodesByProps.get(props);
+    if (!element) {
+      element = parentNode.ownerDocument.createElement(Type);
+      element.setProps(props, ref, rendered, render);
+      parentNode.appendChild(element);
+      parentNode.ownerDocument.updateCollection();
+      parentNode.ownerDocument.nodesByProps.set(props, element);
+    }
+
+    return children
+      ? <SSRContext.Provider value={element}>{children}</SSRContext.Provider>
+      : null;
+  }
+
+  // @ts-ignore
+  return <Type ref={itemRef}>{children}</Type>;
+}
+
+export function createLeafComponent<T extends object, P extends object, E extends Element>(type: string, render: (props: P, ref: ForwardedRef<E>) => ReactNode): (props: P & React.RefAttributes<T>) => ReactNode | null;
+export function createLeafComponent<T extends object, P extends object, E extends Element>(type: string, render: (props: P, ref: ForwardedRef<E>, node: Node<T>) => ReactNode): (props: P & React.RefAttributes<T>) => ReactNode | null;
+export function createLeafComponent<P extends object, E extends Element>(type: string, render: (props: P, ref: ForwardedRef<E>, node?: any) => ReactNode) {
+  let Component = ({node}) => render(node.props, node.props.ref, node);
+  let Result = (forwardRef as forwardRefType)((props: P, ref: ForwardedRef<E>) => {
+    let isShallow = useContext(ShallowRenderContext);
+    if (!isShallow) {
+      if (render.length >= 3) {
+        throw new Error(render.name + ' cannot be rendered outside a collection.');
+      }
+      return render(props, ref);
+    }
+
+    return useSSRCollectionNode(type, props, ref, 'children' in props ? props.children : null, null, node => <Component node={node} />);
+  });
+  // @ts-ignore
+  Result.displayName = render.name;
+  return Result;
+}
+
+export function createBranchComponent<T extends object, P extends {children?: any}, E extends Element>(type: string, render: (props: P, ref: ForwardedRef<E>, node: Node<T>) => ReactNode, useChildren: (props: P) => ReactNode = useCollectionChildren) {
+  let Component = ({node}) => render(node.props, node.props.ref, node);
+  let Result = (forwardRef as forwardRefType)((props: P, ref: ForwardedRef<E>) => {
+    let children = useChildren(props);
+    return useSSRCollectionNode(type, props, ref, null, children, node => <Component node={node} />) ?? <></>;
+  });
+  // @ts-ignore
+  Result.displayName = render.name;
+  return Result;
+}
+
+function useCollectionChildren<T extends object>(options: CachedChildrenOptions<T>) {
+  return useCachedChildren({...options, addIdAndValue: true});
+}
+
+export interface CollectionProps<T> extends CachedChildrenOptions<T> {}
+
+const CollectionContext = createContext<CachedChildrenOptions<unknown> | null>(null);
+
+/** A Collection renders a list of items, automatically managing caching and keys. */
+export function Collection<T extends object>(props: CollectionProps<T>): JSX.Element {
+  let ctx = useContext(CollectionContext)!;
+  let dependencies = (ctx?.dependencies || []).concat(props.dependencies);
+  let idScope = props.idScope || ctx?.idScope;
+  let children = useCollectionChildren({
+    ...props,
+    idScope,
+    dependencies
+  });
+
+  let doc = useContext(CollectionDocumentContext);
+  if (doc) {
+    children = <CollectionRoot>{children}</CollectionRoot>;
+  }
+
+  // Propagate dependencies and idScope to child collections.
+  ctx = useMemo(() => ({
+    dependencies,
+    idScope
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }), [idScope, ...dependencies]);
+
+  return (
+    <CollectionContext.Provider value={ctx}>
+      {children}
+    </CollectionContext.Provider>
+  );
+}
+
+function CollectionRoot({children}) {
+  let doc = useContext(CollectionDocumentContext);
+  let wrappedChildren = useMemo(() => (
+    <CollectionDocumentContext.Provider value={null}>
+      <ShallowRenderContext.Provider value>
+        {children}
+      </ShallowRenderContext.Provider>
+    </CollectionDocumentContext.Provider>
+  ), [children]);
+  // During SSR, we render the content directly, and append nodes to the document during render.
+  // The collection children return null so that nothing is actually rendered into the HTML.
+  return useIsSSR()
+    ? <SSRContext.Provider value={doc}>{wrappedChildren}</SSRContext.Provider>
+    : createPortal(wrappedChildren, doc as unknown as Element);
+}