@react-aria/collections 3.0.3 → 3.1.0

package/src/BaseCollection.ts

@@ -1,353 +0,0 @@
-/*
- * 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]
-}
-
-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;
-  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;
-  readonly colSpan: number | null = null;
-  readonly colIndex: number | null = null;
-
-  constructor(key: Key) {
-    this.type = (this.constructor as typeof CollectionNode).type;
-    this.key = key;
-  }
-
-  get childNodes(): Iterable<Node<T>> {
-    throw new Error('childNodes is not supported');
-  }
-
-  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;
-    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;
-    node.colSpan = this.colSpan;
-    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;
-  }
-}
-
-/**
- * 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>> {
-  protected keyMap: Map<Key, CollectionNode<T>> = new Map();
-  protected firstKey: Key | null = null;
-  protected lastKey: Key | null = null;
-  protected frozen = false;
-  protected itemCount: number = 0;
-
-  get size(): number {
-    return this.itemCount;
-  }
-
-  getKeys(): IterableIterator<Key> {
-    return this.keyMap.keys();
-  }
-
-  *[Symbol.iterator](): IterableIterator<Node<T>> {
-    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): Key | null {
-    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): Key | null {
-    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(): Key | null {
-    return this.firstKey;
-  }
-
-  getLastKey(): Key | null {
-    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;
-    collection.itemCount = this.itemCount;
-    return collection;
-  }
-
-  addNode(node: CollectionNode<T>): void {
-    if (this.frozen) {
-      throw new Error('Cannot add a node to a frozen collection');
-    }
-
-    if (node.type === 'item' && this.keyMap.get(node.key) == null) {
-      this.itemCount++;
-    }
-
-    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');
-    }
-
-    let node = this.keyMap.get(key);
-    if (node != null && node.type === 'item') {
-      this.itemCount--;
-    }
-
-    this.keyMap.delete(key);
-  }
-
-  commit(firstKey: Key | null, lastKey: Key | null, isSSR = false): void {
-    if (this.frozen) {
-      throw new Error('Cannot commit a frozen collection');
-    }
-
-    this.firstKey = firstKey;
-    this.lastKey = lastKey;
-    this.frozen = !isSSR;
-  }
-
-  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;
-  }
-}
-
-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 (firstNode == null) {
-        firstNode = newNode;
-      }
-
-      newCollection.addNode(newNode);
-      lastNode = newNode;
-    }
-
-    currentNode = currentNode.nextKey ? collection.getItem(currentNode.nextKey) : null;
-  }
-
-  // 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 {
-      lastNode = null;
-    }
-  }
-
-  return [firstNode?.key ?? null, lastNode?.key ?? null];
-}

package/src/CollectionBuilder.tsx

@@ -1,265 +0,0 @@
-/*
- * 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, 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, 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';
-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>): ReactElement {
-  // If a document was provided above us, we're already in a hidden tree. Just render the content.
-  let doc = useContext(CollectionDocumentContext);
-  if (doc) {
-    // The React types prior to 18 did not allow returning ReactNode from components
-    // even though the actual implementation since React 16 did.
-    // We must return ReactElement so that TS does not complain that <CollectionBuilder>
-    // is not a valid JSX element with React 16 and 17 types.
-    // https://github.com/DefinitelyTyped/DefinitelyTyped/issues/20544
-    return props.content as ReactElement;
-  }
-
-  // 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);
-  return {collection, document};
-}
-
-const SSRContext = createContext<BaseNode<any> | null>(null);
-
-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, 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(CollectionNodeClass.type);
-      element.setProps(props, ref, CollectionNodeClass, 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 <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>(CollectionNodeClass: CollectionNodeClass<any> | 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>(CollectionNodeClass: CollectionNodeClass<any> | 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>(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);
-    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(
-      CollectionNodeClass,
-      props,
-      ref,
-      'children' in props ? props.children : null,
-      null,
-      node => (
-        // Forward FocusableContext to real DOM tree so tooltips work.
-        <FocusableContext.Provider value={focusableProps}>
-          <Component node={node} />
-        </FocusableContext.Provider>
-      )
-    );
-  });
-  // @ts-ignore
-  Result.displayName = render.name;
-  return Result;
-}
-
-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(CollectionNodeClass, 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);
-}