@react-aria/collections 3.0.0-rc.4 → 3.0.0-rc.6

package/src/BaseCollection.ts

@@ -17,8 +17,11 @@ export type Mutable<T> = {
   -readonly[P in keyof T]: T[P]
 }
 
+type FilterFn<T> = (textValue: string, node: Node<T>) => boolean;
+
 /** An immutable object representing a Node in a Collection. */
 export class CollectionNode<T> implements Node<T> {
+  static readonly type: string;
   readonly type: string;
   readonly key: Key;
   readonly value: T | null = null;
@@ -38,8 +41,8 @@ export class CollectionNode<T> implements Node<T> {
   readonly colSpan: number | null = null;
   readonly colIndex: number | null = null;
 
-  constructor(type: string, key: Key) {
-    this.type = type;
+  constructor(key: Key) {
+    this.type = (this.constructor as typeof CollectionNode).type;
     this.key = key;
   }
 
@@ -47,8 +50,8 @@ export class CollectionNode<T> implements Node<T> {
     throw new Error('childNodes is not supported');
   }
 
-  clone(): CollectionNode<T> {
-    let node: Mutable<CollectionNode<T>> = new CollectionNode(this.type, this.key);
+  clone(): this {
+    let node: Mutable<this> = new (this.constructor as any)(this.key);
     node.value = this.value;
     node.level = this.level;
     node.hasChildNodes = this.hasChildNodes;
@@ -67,6 +70,63 @@ export class CollectionNode<T> implements Node<T> {
     node.colIndex = this.colIndex;
     return node;
   }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  filter(collection: BaseCollection<T>, newCollection: BaseCollection<T>, filterFn: FilterFn<T>): CollectionNode<T> | null {
+    let clone = this.clone();
+    newCollection.addDescendants(clone, collection);
+    return clone;
+  }
+}
+
+export class FilterableNode<T> extends CollectionNode<T> {
+  filter(collection: BaseCollection<T>, newCollection: BaseCollection<T>, filterFn: FilterFn<T>): CollectionNode<T> | null {
+    let [firstKey, lastKey] = filterChildren(collection, newCollection, this.firstChildKey, filterFn);
+    let newNode: Mutable<CollectionNode<T>> = this.clone();
+    newNode.firstChildKey = firstKey;
+    newNode.lastChildKey = lastKey;
+    return newNode;
+  }
+}
+
+export class HeaderNode extends CollectionNode<unknown> {
+  static readonly type = 'header';
+}
+
+export class LoaderNode extends CollectionNode<unknown> {
+  static readonly type = 'loader';
+}
+
+export class ItemNode<T> extends FilterableNode<T> {
+  static readonly type = 'item';
+
+  filter(collection: BaseCollection<T>, newCollection: BaseCollection<T>, filterFn: FilterFn<T>): ItemNode<T> | null {
+    if (filterFn(this.textValue, this)) {
+      let clone = this.clone();
+      newCollection.addDescendants(clone, collection);
+      return clone;
+    }
+
+    return null;
+  }
+}
+
+export class SectionNode<T> extends FilterableNode<T> {
+  static readonly type = 'section';
+
+  filter(collection: BaseCollection<T>, newCollection: BaseCollection<T>, filterFn: FilterFn<T>): SectionNode<T> | null {
+    let filteredSection = super.filter(collection, newCollection, filterFn);
+    if (filteredSection) {
+      if (filteredSection.lastChildKey !== null) {
+        let lastChild = collection.getItem(filteredSection.lastChildKey);
+        if (lastChild && lastChild.type !== 'header') {
+          return filteredSection;
+        }
+      }
+    }
+
+    return null;
+  }
 }
 
 /**
@@ -201,6 +261,15 @@ export class BaseCollection<T> implements ICollection<Node<T>> {
     this.keyMap.set(node.key, node);
   }
 
+  // Deeply add a node and its children to the collection from another collection, primarily used when filtering a collection
+  addDescendants(node: CollectionNode<T>, oldCollection: BaseCollection<T>): void {
+    this.addNode(node);
+    let children = oldCollection.getChildren(node.key);
+    for (let child of children) {
+      this.addDescendants(child as CollectionNode<T>, oldCollection);
+    }
+  }
+
   removeNode(key: Key): void {
     if (this.frozen) {
       throw new Error('Cannot remove a node to a frozen collection');
@@ -224,134 +293,61 @@ export class BaseCollection<T> implements ICollection<Node<T>> {
     this.frozen = !isSSR;
   }
 
-  // TODO: this is pretty specific to menu, will need to check if it is generic enough
-  // Will need to handle varying levels I assume but will revisit after I get searchable menu working for base menu
-  // TODO: an alternative is to simply walk the collection and add all item nodes that match the filter and any sections/separators we encounter
-  // to an array, then walk that new array and fix all the next/Prev keys while adding them to the new collection
-  UNSTABLE_filter(filterFn: (nodeValue: string) => boolean): BaseCollection<T> {
-    let newCollection = new BaseCollection<T>();
-    // This tracks the absolute last node we've visited in the collection when filtering, used for setting up the filteredCollection's lastKey and
-    // for updating the next/prevKey for every non-filtered node.
-    let lastNode: Mutable<CollectionNode<T>> | null = null;
-
-    for (let node of this) {
-      if (node.type === 'section' && node.hasChildNodes) {
-        let clonedSection: Mutable<CollectionNode<T>> = (node as CollectionNode<T>).clone();
-        let lastChildInSection: Mutable<CollectionNode<T>> | null = null;
-        for (let child of this.getChildren(node.key)) {
-          if (shouldKeepNode(child, filterFn, this, newCollection)) {
-            let clonedChild: Mutable<CollectionNode<T>> = (child as CollectionNode<T>).clone();
-            // eslint-disable-next-line max-depth
-            if (lastChildInSection == null) {
-              clonedSection.firstChildKey = clonedChild.key;
-            }
-
-            // eslint-disable-next-line max-depth
-            if (newCollection.firstKey == null) {
-              newCollection.firstKey = clonedSection.key;
-            }
-
-            // eslint-disable-next-line max-depth
-            if (lastChildInSection && lastChildInSection.parentKey === clonedChild.parentKey) {
-              lastChildInSection.nextKey = clonedChild.key;
-              clonedChild.prevKey = lastChildInSection.key;
-            } else {
-              clonedChild.prevKey = null;
-            }
-
-            clonedChild.nextKey = null;
-            newCollection.addNode(clonedChild);
-            lastChildInSection = clonedChild;
-          }
-        }
+  filter(filterFn: FilterFn<T>): this {
+    let newCollection = new (this.constructor as any)();
+    let [firstKey, lastKey] = filterChildren(this, newCollection, this.firstKey, filterFn);
+    newCollection?.commit(firstKey, lastKey);
+    return newCollection;
+  }
+}
 
-        // Add newly filtered section to collection if it has any valid child nodes, otherwise remove it and its header if any
-        if (lastChildInSection) {
-          if (lastChildInSection.type !== 'header') {
-            clonedSection.lastChildKey = lastChildInSection.key;
-
-            // If the old prev section was filtered out, will need to attach to whatever came before
-            // eslint-disable-next-line max-depth
-            if (lastNode == null) {
-              clonedSection.prevKey = null;
-            } else if (lastNode.type === 'section' || lastNode.type === 'separator') {
-              lastNode.nextKey = clonedSection.key;
-              clonedSection.prevKey = lastNode.key;
-            }
-            clonedSection.nextKey = null;
-            lastNode = clonedSection;
-            newCollection.addNode(clonedSection);
-          } else {
-            if (newCollection.firstKey === clonedSection.key) {
-              newCollection.firstKey = null;
-            }
-            newCollection.removeNode(lastChildInSection.key);
-          }
-        }
-      } else if (node.type === 'separator') {
-        // will need to check if previous section key exists, if it does then we add the separator to the collection.
-        // After the full collection is created we'll need to remove it it is the last node in the section (aka no following section after the separator)
-        let clonedSeparator: Mutable<CollectionNode<T>> = (node as CollectionNode<T>).clone();
-        clonedSeparator.nextKey = null;
-        if (lastNode?.type === 'section') {
-          lastNode.nextKey = clonedSeparator.key;
-          clonedSeparator.prevKey = lastNode.key;
-          lastNode = clonedSeparator;
-          newCollection.addNode(clonedSeparator);
-        }
-      } else {
-        // At this point, the node is either a subdialogtrigger node or a standard row/item
-        let clonedNode: Mutable<CollectionNode<T>> = (node as CollectionNode<T>).clone();
-        if (shouldKeepNode(clonedNode, filterFn, this, newCollection)) {
-          if (newCollection.firstKey == null) {
-            newCollection.firstKey = clonedNode.key;
-          }
-
-          if (lastNode != null && (lastNode.type !== 'section' && lastNode.type !== 'separator') && lastNode.parentKey === clonedNode.parentKey) {
-            lastNode.nextKey = clonedNode.key;
-            clonedNode.prevKey = lastNode.key;
-          } else {
-            clonedNode.prevKey = null;
-          }
-
-          clonedNode.nextKey = null;
-          newCollection.addNode(clonedNode);
-          lastNode = clonedNode;
-        }
+function filterChildren<T>(collection: BaseCollection<T>, newCollection: BaseCollection<T>, firstChildKey: Key | null, filterFn: FilterFn<T>): [Key | null, Key | null] {
+  // loop over the siblings for firstChildKey
+  // create new nodes based on calling node.filter for each child
+  // if it returns null then don't include it, otherwise update its prev/next keys
+  // add them to the newCollection
+  if (firstChildKey == null) {
+    return [null, null];
+  }
+
+  let firstNode: Node<T> | null = null;
+  let lastNode: Node<T> | null = null;
+  let currentNode = collection.getItem(firstChildKey);
+
+  while (currentNode != null) {
+    let newNode: Mutable<CollectionNode<T>> | null = (currentNode as CollectionNode<T>).filter(collection, newCollection, filterFn);
+    if (newNode != null) {
+      newNode.nextKey = null;
+      if (lastNode) {
+        newNode.prevKey = lastNode.key;
+        lastNode.nextKey = newNode.key;
       }
-    }
 
-    if (lastNode?.type === 'separator' && lastNode.nextKey === null) {
-      let lastSection;
-      if (lastNode.prevKey != null) {
-        lastSection = newCollection.getItem(lastNode.prevKey) as Mutable<CollectionNode<T>>;
-        lastSection.nextKey = null;
+      if (firstNode == null) {
+        firstNode = newNode;
       }
-      newCollection.removeNode(lastNode.key);
-      lastNode = lastSection;
-    }
 
-    newCollection.lastKey = lastNode?.key || null;
+      newCollection.addNode(newNode);
+      lastNode = newNode;
+    }
 
-    return newCollection;
+    currentNode = currentNode.nextKey ? collection.getItem(currentNode.nextKey) : null;
   }
-}
 
-function shouldKeepNode<T>(node: Node<T>, filterFn: (nodeValue: string) => boolean, oldCollection: BaseCollection<T>, newCollection: BaseCollection<T>): boolean {
-  if (node.type === 'subdialogtrigger' || node.type === 'submenutrigger') {
-    // Subdialog wrapper should only have one child, if it passes the filter add it to the new collection since we don't need to
-    // do any extra handling for its first/next key
-    let triggerChild = [...oldCollection.getChildren(node.key)][0];
-    if (triggerChild && filterFn(triggerChild.textValue)) {
-      let clonedChild: Mutable<CollectionNode<T>> = (triggerChild as CollectionNode<T>).clone();
-      newCollection.addNode(clonedChild);
-      return true;
+  // TODO: this is pretty specific to dividers but doesn't feel like there is a good way to get around it since we only can know
+  // to filter the last separator in a collection only after performing a filter for the rest of the contents after it
+  // Its gross that it needs to live here, might be nice if somehow we could have this live in the separator code
+  if (lastNode && lastNode.type === 'separator') {
+    let prevKey = lastNode.prevKey;
+    newCollection.removeNode(lastNode.key);
+
+    if (prevKey) {
+      lastNode = newCollection.getItem(prevKey) as Mutable<CollectionNode<T>>;
+      lastNode.nextKey = null;
     } else {
-      return false;
+      lastNode = null;
     }
-  } else if (node.type === 'header') {
-    return true;
-  } else {
-    return filterFn(node.textValue);
   }
+
+  return [firstNode?.key ?? null, lastNode?.key ?? null];
 }

package/src/CollectionBuilder.tsx

@@ -10,12 +10,12 @@
  * governing permissions and limitations under the License.
  */
 
-import {BaseCollection} from './BaseCollection';
+import {BaseCollection, CollectionNode} from './BaseCollection';
 import {BaseNode, Document, ElementNode} from './Document';
 import {CachedChildrenOptions, useCachedChildren} from './useCachedChildren';
 import {createPortal} from 'react-dom';
 import {FocusableContext} from '@react-aria/interactions';
-import {forwardRefType, Node} from '@react-types/shared';
+import {forwardRefType, Key, 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';
@@ -127,22 +127,39 @@ function useCollectionDocument<T extends object, C extends BaseCollection<T>>(cr
 
 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) {
+export type CollectionNodeClass<T> = {
+  new (key: Key): CollectionNode<T>,
+  readonly type: string
+};
+
+function createCollectionNodeClass(type: string): CollectionNodeClass<any> {
+  let NodeClass = class extends CollectionNode<any> {
+    static readonly type = type;
+  };
+  return NodeClass;
+}
+
+function useSSRCollectionNode<T extends Element>(CollectionNodeClass: CollectionNodeClass<T> | string, props: object, ref: ForwardedRef<T>, rendered?: any, children?: ReactNode, render?: (node: Node<any>) => ReactElement) {
+  // To prevent breaking change, if CollectionNodeClass is a string, create a CollectionNodeClass using the string as the type
+  if (typeof CollectionNodeClass === 'string') {
+    CollectionNodeClass = createCollectionNodeClass(CollectionNodeClass);
+  }
+
   // 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]);
+    element?.setProps(props, ref, CollectionNodeClass, rendered, render);
+  }, [props, ref, rendered, render, CollectionNodeClass]);
   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);
+      element = parentNode.ownerDocument.createElement(CollectionNodeClass.type);
+      element.setProps(props, ref, CollectionNodeClass, rendered, render);
       parentNode.appendChild(element);
       parentNode.ownerDocument.updateCollection();
       parentNode.ownerDocument.nodesByProps.set(props, element);
@@ -154,13 +171,12 @@ function useSSRCollectionNode<T extends Element>(Type: string, props: object, re
   }
 
   // @ts-ignore
-  return <Type ref={itemRef}>{children}</Type>;
+  return <CollectionNodeClass.type ref={itemRef}>{children}</CollectionNodeClass.type>;
 }
 
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-export function createLeafComponent<T extends object, P extends object, E extends Element>(type: string, render: (props: P, ref: ForwardedRef<E>) => ReactElement | null): (props: P & React.RefAttributes<E>) => ReactElement | null;
-export function createLeafComponent<T extends object, P extends object, E extends Element>(type: string, render: (props: P, ref: ForwardedRef<E>, node: Node<T>) => ReactElement | null): (props: P & React.RefAttributes<E>) => ReactElement | null;
-export function createLeafComponent<P extends object, E extends Element>(type: string, render: (props: P, ref: ForwardedRef<E>, node?: any) => ReactElement | null): (props: P & React.RefAttributes<any>) => ReactElement | null {
+export function createLeafComponent<T extends object, P extends object, E extends Element>(CollectionNodeClass: CollectionNodeClass<any> | string, render: (props: P, ref: ForwardedRef<E>) => ReactElement | null): (props: P & React.RefAttributes<T>) => ReactElement | null;
+export function createLeafComponent<T extends object, P extends object, E extends Element>(CollectionNodeClass: CollectionNodeClass<any> | string, render: (props: P, ref: ForwardedRef<E>, node: Node<T>) => ReactElement | null): (props: P & React.RefAttributes<T>) => ReactElement | null;
+export function createLeafComponent<P extends object, E extends Element>(CollectionNodeClass: CollectionNodeClass<any> | string, render: (props: P, ref: ForwardedRef<E>, node?: any) => ReactElement | null): (props: P & React.RefAttributes<any>) => ReactElement | null {
   let Component = ({node}) => render(node.props, node.props.ref, node);
   let Result = (forwardRef as forwardRefType)((props: P, ref: ForwardedRef<E>) => {
     let focusableProps = useContext(FocusableContext);
@@ -173,7 +189,7 @@ export function createLeafComponent<P extends object, E extends Element>(type: s
     }
 
     return useSSRCollectionNode(
-      type,
+      CollectionNodeClass,
       props,
       ref,
       'children' in props ? props.children : null,
@@ -191,11 +207,11 @@ export function createLeafComponent<P extends object, E extends Element>(type: s
   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>) => ReactElement | null, useChildren: (props: P) => ReactNode = useCollectionChildren): (props: P & React.RefAttributes<E>) => ReactElement | null {
+export function createBranchComponent<T extends object, P extends {children?: any}, E extends Element>(CollectionNodeClass: CollectionNodeClass<any> | string, render: (props: P, ref: ForwardedRef<E>, node: Node<T>) => ReactElement | null, useChildren: (props: P) => ReactNode = useCollectionChildren): (props: P & React.RefAttributes<E>) => ReactElement | null {
   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} />) ?? <></>;
+    return useSSRCollectionNode(CollectionNodeClass, props, ref, null, children, node => <Component node={node} />) ?? <></>;
   });
   // @ts-ignore
   Result.displayName = render.name;

package/src/Document.ts

@@ -11,6 +11,7 @@
  */
 
 import {BaseCollection, CollectionNode, Mutable} from './BaseCollection';
+import {CollectionNodeClass} from './CollectionBuilder';
 import {CSSProperties, ForwardedRef, ReactElement, ReactNode} from 'react';
 import {Node} from '@react-types/shared';
 
@@ -256,15 +257,14 @@ export class BaseNode<T> {
  */
 export class ElementNode<T> extends BaseNode<T> {
   nodeType = 8; // COMMENT_NODE (we'd use ELEMENT_NODE but React DevTools will fail to get its dimensions)
-  node: CollectionNode<T>;
+  private _node: CollectionNode<T> | null;
   isMutated = true;
   private _index: number = 0;
-  hasSetProps = false;
   isHidden = false;
 
   constructor(type: string, ownerDocument: Document<T, any>) {
     super(ownerDocument);
-    this.node = new CollectionNode(type, `react-aria-${++ownerDocument.nodeId}`);
+    this._node = null;
   }
 
   get index(): number {
@@ -278,12 +278,24 @@ export class ElementNode<T> extends BaseNode<T> {
 
   get level(): number {
     if (this.parentNode instanceof ElementNode) {
-      return this.parentNode.level + (this.node.type === 'item' ? 1 : 0);
+      return this.parentNode.level + (this.node?.type === 'item' ? 1 : 0);
     }
 
     return 0;
   }
 
+  get node(): CollectionNode<T> {
+    if (this._node == null) {
+      throw Error('Attempted to access node before it was defined. Check if setProps wasn\'t called before attempting to access the node.');
+    }
+
+    return this._node;
+  }
+
+  set node(node: CollectionNode<T>) {
+    this._node = node;
+  }
+
   /**
    * Lazily gets a mutable instance of a Node. If the node has already
    * been cloned during this update cycle, it just returns the existing one.
@@ -321,9 +333,16 @@ export class ElementNode<T> extends BaseNode<T> {
     }
   }
 
-  setProps<E extends Element>(obj: {[key: string]: any}, ref: ForwardedRef<E>, rendered?: ReactNode, render?: (node: Node<T>) => ReactElement): void {
-    let node = this.getMutableNode();
+  setProps<E extends Element>(obj: {[key: string]: any}, ref: ForwardedRef<E>, CollectionNodeClass: CollectionNodeClass<any>, rendered?: ReactNode, render?: (node: Node<T>) => ReactElement): void {
+    let node;
     let {value, textValue, id, ...props} = obj;
+    if (this._node == null) {
+      node = new CollectionNodeClass(id ?? `react-aria-${++this.ownerDocument.nodeId}`);
+      this.node = node;
+    } else {
+      node = this.getMutableNode();
+    }
+
     props.ref = ref;
     node.props = props;
     node.rendered = rendered;
@@ -331,17 +350,13 @@ export class ElementNode<T> extends BaseNode<T> {
     node.value = value;
     node.textValue = textValue || (typeof props.children === 'string' ? props.children : '') || obj['aria-label'] || '';
     if (id != null && id !== node.key) {
-      if (this.hasSetProps) {
-        throw new Error('Cannot change the id of an item');
-      }
-      node.key = id;
+      throw new Error('Cannot change the id of an item');
     }
 
     if (props.colSpan != null) {
       node.colSpan = props.colSpan;
     }
 
-    this.hasSetProps = true;
     if (this.isConnected) {
       this.ownerDocument.queueUpdate();
     }
@@ -446,7 +461,7 @@ export class Document<T, C extends BaseCollection<T> = BaseCollection<T>> extend
       }
     }
 
-    collection.addNode(element.node);
+    collection.addNode(element.node!);
   }
 
   private removeNode(node: ElementNode<T>): void {

package/src/index.ts

@@ -13,7 +13,7 @@
 export {CollectionBuilder, Collection, createLeafComponent, createBranchComponent} from './CollectionBuilder';
 export {createHideableComponent, useIsHidden} from './Hidden';
 export {useCachedChildren} from './useCachedChildren';
-export {BaseCollection, CollectionNode} from './BaseCollection';
+export {BaseCollection, CollectionNode, ItemNode, SectionNode, FilterableNode, LoaderNode, HeaderNode} from './BaseCollection';
 
 export type {CollectionBuilderProps, CollectionProps} from './CollectionBuilder';
 export type {CachedChildrenOptions} from './useCachedChildren';