@react-aria/selection 3.18.1 → 3.19.1

package/src/DOMLayoutDelegate.ts

@@ -0,0 +1,57 @@
+/*
+ * 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 {Key, LayoutDelegate, Rect, RefObject, Size} from '@react-types/shared';
+
+export class DOMLayoutDelegate implements LayoutDelegate {
+  private ref: RefObject<HTMLElement>;
+
+  constructor(ref: RefObject<HTMLElement>) {
+    this.ref = ref;
+  }
+
+  getItemRect(key: Key): Rect | null {
+    let container = this.ref.current;
+    let item = key != null ? container.querySelector(`[data-key="${CSS.escape(key.toString())}"]`) : null;
+    if (!item) {
+      return null;
+    }
+
+    let containerRect = container.getBoundingClientRect();
+    let itemRect = item.getBoundingClientRect();
+
+    return {
+      x: itemRect.left - containerRect.left + container.scrollLeft,
+      y: itemRect.top - containerRect.top + container.scrollTop,
+      width: itemRect.width,
+      height: itemRect.height
+    };
+  }
+
+  getContentSize(): Size {
+    let container = this.ref.current;
+    return {
+      width: container.scrollWidth,
+      height: container.scrollHeight
+    };
+  }
+
+  getVisibleRect(): Rect {
+    let container = this.ref.current;
+    return {
+      x: container.scrollLeft,
+      y: container.scrollTop,
+      width: container.offsetWidth,
+      height: container.offsetHeight
+    };
+  }
+}

package/src/ListKeyboardDelegate.ts

@@ -10,32 +10,34 @@
  * governing permissions and limitations under the License.
  */
 
-import {Collection, Direction, DisabledBehavior, Key, KeyboardDelegate, Node, Orientation} from '@react-types/shared';
+import {Collection, Direction, DisabledBehavior, Key, KeyboardDelegate, LayoutDelegate, Node, Orientation, Rect, RefObject} from '@react-types/shared';
+import {DOMLayoutDelegate} from './DOMLayoutDelegate';
 import {isScrollable} from '@react-aria/utils';
-import {RefObject} from 'react';
 
 interface ListKeyboardDelegateOptions<T> {
   collection: Collection<Node<T>>,
-  ref: RefObject<HTMLElement>,
+  ref: RefObject<HTMLElement | null>,
   collator?: Intl.Collator,
   layout?: 'stack' | 'grid',
   orientation?: Orientation,
   direction?: Direction,
   disabledKeys?: Set<Key>,
-  disabledBehavior?: DisabledBehavior
+  disabledBehavior?: DisabledBehavior,
+  layoutDelegate?: LayoutDelegate
 }
 
 export class ListKeyboardDelegate<T> implements KeyboardDelegate {
   private collection: Collection<Node<T>>;
   private disabledKeys: Set<Key>;
   private disabledBehavior: DisabledBehavior;
-  private ref: RefObject<HTMLElement>;
+  private ref: RefObject<HTMLElement | null>;
   private collator: Intl.Collator | undefined;
   private layout: 'stack' | 'grid';
   private orientation?: Orientation;
   private direction?: Direction;
+  private layoutDelegate: LayoutDelegate;
 
-  constructor(collection: Collection<Node<T>>, disabledKeys: Set<Key>, ref: RefObject<HTMLElement>, collator?: Intl.Collator);
+  constructor(collection: Collection<Node<T>>, disabledKeys: Set<Key>, ref: RefObject<HTMLElement | null>, collator?: Intl.Collator);
   constructor(options: ListKeyboardDelegateOptions<T>);
   constructor(...args: any[]) {
     if (args.length === 1) {
@@ -45,9 +47,10 @@ export class ListKeyboardDelegate<T> implements KeyboardDelegate {
       this.collator = opts.collator;
       this.disabledKeys = opts.disabledKeys || new Set();
       this.disabledBehavior = opts.disabledBehavior || 'all';
-      this.orientation = opts.orientation;
+      this.orientation = opts.orientation || 'vertical';
       this.direction = opts.direction;
       this.layout = opts.layout || 'stack';
+      this.layoutDelegate = opts.layoutDelegate || new DOMLayoutDelegate(opts.ref);
     } else {
       this.collection = args[0];
       this.disabledKeys = args[1];
@@ -56,6 +59,7 @@ export class ListKeyboardDelegate<T> implements KeyboardDelegate {
       this.layout = 'stack';
       this.orientation = 'vertical';
       this.disabledBehavior = 'all';
+      this.layoutDelegate = new DOMLayoutDelegate(this.ref);
     }
 
     // If this is a vertical stack, remove the left/right methods completely
@@ -101,29 +105,29 @@ export class ListKeyboardDelegate<T> implements KeyboardDelegate {
   private findKey(
     key: Key,
     nextKey: (key: Key) => Key,
-    shouldSkip: (prevRect: DOMRect, itemRect: DOMRect) => boolean
+    shouldSkip: (prevRect: Rect, itemRect: Rect) => boolean
   ) {
-    let item = this.getItem(key);
-    if (!item) {
+    let itemRect = this.layoutDelegate.getItemRect(key);
+    if (!itemRect) {
       return null;
     }
 
     // Find the item above or below in the same column.
-    let prevRect = item.getBoundingClientRect();
+    let prevRect = itemRect;
     do {
       key = nextKey(key);
-      item = this.getItem(key);
-    } while (item && shouldSkip(prevRect, item.getBoundingClientRect()));
+      itemRect = this.layoutDelegate.getItemRect(key);
+    } while (itemRect && shouldSkip(prevRect, itemRect));
 
     return key;
   }
 
-  private isSameRow(prevRect: DOMRect, itemRect: DOMRect) {
-    return prevRect.top === itemRect.top || prevRect.left !== itemRect.left;
+  private isSameRow(prevRect: Rect, itemRect: Rect) {
+    return prevRect.y === itemRect.y || prevRect.x !== itemRect.x;
   }
 
-  private isSameColumn(prevRect: DOMRect, itemRect: DOMRect) {
-    return prevRect.left === itemRect.left || prevRect.top !== itemRect.top;
+  private isSameColumn(prevRect: Rect, itemRect: Rect) {
+    return prevRect.x === itemRect.x || prevRect.y !== itemRect.y;
   }
 
   getKeyBelow(key: Key) {
@@ -202,14 +206,10 @@ export class ListKeyboardDelegate<T> implements KeyboardDelegate {
     return null;
   }
 
-  private getItem(key: Key): HTMLElement {
-    return key !== null ? this.ref.current.querySelector(`[data-key="${CSS.escape(key.toString())}"]`) : null;
-  }
-
   getKeyPageAbove(key: Key) {
     let menu = this.ref.current;
-    let item = this.getItem(key);
-    if (!item) {
+    let itemRect = this.layoutDelegate.getItemRect(key);
+    if (!itemRect) {
       return null;
     }
 
@@ -217,25 +217,19 @@ export class ListKeyboardDelegate<T> implements KeyboardDelegate {
       return this.getFirstKey();
     }
 
-    let containerRect = menu.getBoundingClientRect();
-    let itemRect = item.getBoundingClientRect();
     if (this.orientation === 'horizontal') {
-      let containerX = containerRect.x - menu.scrollLeft;
-      let pageX = Math.max(0, (itemRect.x - containerX) + itemRect.width - containerRect.width);
+      let pageX = Math.max(0, itemRect.x + itemRect.width - this.layoutDelegate.getVisibleRect().width);
 
-      while (item && (itemRect.x - containerX) > pageX) {
+      while (itemRect && itemRect.x > pageX) {
         key = this.getKeyAbove(key);
-        item = key == null ? null : this.getItem(key);
-        itemRect = item?.getBoundingClientRect();
+        itemRect = key == null ? null : this.layoutDelegate.getItemRect(key);
       }
     } else {
-      let containerY = containerRect.y - menu.scrollTop;
-      let pageY = Math.max(0, (itemRect.y - containerY) + itemRect.height - containerRect.height);
+      let pageY = Math.max(0, itemRect.y + itemRect.height - this.layoutDelegate.getVisibleRect().height);
 
-      while (item && (itemRect.y - containerY) > pageY) {
+      while (itemRect && itemRect.y > pageY) {
         key = this.getKeyAbove(key);
-        item = key == null ? null : this.getItem(key);
-        itemRect = item?.getBoundingClientRect();
+        itemRect = key == null ? null : this.layoutDelegate.getItemRect(key);
       }
     }
 
@@ -244,8 +238,8 @@ export class ListKeyboardDelegate<T> implements KeyboardDelegate {
 
   getKeyPageBelow(key: Key) {
     let menu = this.ref.current;
-    let item = this.getItem(key);
-    if (!item) {
+    let itemRect = this.layoutDelegate.getItemRect(key);
+    if (!itemRect) {
       return null;
     }
 
@@ -253,25 +247,19 @@ export class ListKeyboardDelegate<T> implements KeyboardDelegate {
       return this.getLastKey();
     }
 
-    let containerRect = menu.getBoundingClientRect();
-    let itemRect = item.getBoundingClientRect();
     if (this.orientation === 'horizontal') {
-      let containerX = containerRect.x - menu.scrollLeft;
-      let pageX = Math.min(menu.scrollWidth, (itemRect.x - containerX) - itemRect.width + containerRect.width);
+      let pageX = Math.min(this.layoutDelegate.getContentSize().width, itemRect.y - itemRect.width + this.layoutDelegate.getVisibleRect().width);
 
-      while (item && (itemRect.x - containerX) < pageX) {
+      while (itemRect && itemRect.x < pageX) {
         key = this.getKeyBelow(key);
-        item = key == null ? null : this.getItem(key);
-        itemRect = item?.getBoundingClientRect();
+        itemRect = key == null ? null : this.layoutDelegate.getItemRect(key);
       }
     } else {
-      let containerY = containerRect.y - menu.scrollTop;
-      let pageY = Math.min(menu.scrollHeight, (itemRect.y - containerY) - itemRect.height + containerRect.height);
+      let pageY = Math.min(this.layoutDelegate.getContentSize().height, itemRect.y - itemRect.height + this.layoutDelegate.getVisibleRect().height);
 
-      while (item && (itemRect.y - containerY) < pageY) {
+      while (itemRect && itemRect.y < pageY) {
         key = this.getKeyBelow(key);
-        item = key == null ? null : this.getItem(key);
-        itemRect = item?.getBoundingClientRect();
+        itemRect = key == null ? null : this.layoutDelegate.getItemRect(key);
       }
     }
 

package/src/index.ts

@@ -14,6 +14,7 @@ export {useSelectableCollection} from './useSelectableCollection';
 export {useSelectableItem} from './useSelectableItem';
 export {useSelectableList} from './useSelectableList';
 export {ListKeyboardDelegate} from './ListKeyboardDelegate';
+export {DOMLayoutDelegate} from './DOMLayoutDelegate';
 export {useTypeSelect} from './useTypeSelect';
 
 export type {AriaSelectableCollectionOptions, SelectableCollectionAria} from './useSelectableCollection';

package/src/useSelectableCollection.ts

@@ -10,9 +10,9 @@
  * governing permissions and limitations under the License.
  */
 
-import {DOMAttributes, FocusableElement, FocusStrategy, Key, KeyboardDelegate} from '@react-types/shared';
+import {DOMAttributes, FocusableElement, FocusStrategy, Key, KeyboardDelegate, RefObject} from '@react-types/shared';
 import {flushSync} from 'react-dom';
-import {FocusEvent, KeyboardEvent, RefObject, useEffect, useRef} from 'react';
+import {FocusEvent, KeyboardEvent, useEffect, useRef} from 'react';
 import {focusSafely, getFocusableTreeWalker} from '@react-aria/focus';
 import {focusWithoutScrolling, mergeProps, scrollIntoView, scrollIntoViewport, useEvent, useRouter} from '@react-aria/utils';
 import {getInteractionModality} from '@react-aria/interactions';
@@ -33,7 +33,7 @@ export interface AriaSelectableCollectionOptions {
   /**
    * The ref attached to the element representing the collection.
    */
-  ref: RefObject<HTMLElement>,
+  ref: RefObject<HTMLElement | null>,
   /**
    * Whether the collection or one of its items should be automatically focused upon render.
    * @default false
@@ -80,7 +80,7 @@ export interface AriaSelectableCollectionOptions {
    * The ref attached to the scrollable body. Used to provide automatic scrolling on item focus for non-virtualized collections.
    * If not provided, defaults to the collection ref.
    */
-  scrollRef?: RefObject<HTMLElement>,
+  scrollRef?: RefObject<HTMLElement | null>,
   /**
    * The behavior of links in the collection.
    * - 'action': link behaves like onAction.
@@ -293,6 +293,7 @@ export function useSelectableCollection(options: AriaSelectableCollectionOptions
   };
 
   // Store the scroll position so we can restore it later.
+  /// TODO: should this happen all the time??
   let scrollPos = useRef({top: 0, left: 0});
   useEvent(scrollRef, 'scroll', isVirtualized ? null : () => {
     scrollPos.current = {
@@ -342,7 +343,7 @@ export function useSelectableCollection(options: AriaSelectableCollectionOptions
       scrollRef.current.scrollLeft = scrollPos.current.left;
     }
 
-    if (!isVirtualized && manager.focusedKey != null) {
+    if (manager.focusedKey != null) {
       // Refocus and scroll the focused item into view if it exists within the scrollable region.
       let element = scrollRef.current.querySelector(`[data-key="${CSS.escape(manager.focusedKey.toString())}"]`) as HTMLElement;
       if (element) {
@@ -400,17 +401,21 @@ export function useSelectableCollection(options: AriaSelectableCollectionOptions
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
-  // If not virtualized, scroll the focused element into view when the focusedKey changes.
-  // When virtualized, Virtualizer handles this internally.
+  // Scroll the focused element into view when the focusedKey changes.
   let lastFocusedKey = useRef(manager.focusedKey);
   useEffect(() => {
-    let modality = getInteractionModality();
-    if (manager.isFocused && manager.focusedKey != null && scrollRef?.current) {
-      let element = scrollRef.current.querySelector(`[data-key="${CSS.escape(manager.focusedKey.toString())}"]`) as HTMLElement;
-      if (element && (modality === 'keyboard' || autoFocusRef.current)) {
-        if (!isVirtualized) {
-          scrollIntoView(scrollRef.current, element);
-        }
+    if (manager.isFocused && manager.focusedKey != null && (manager.focusedKey !== lastFocusedKey.current || autoFocusRef.current) && scrollRef?.current) {
+      let modality = getInteractionModality();
+      let element = ref.current.querySelector(`[data-key="${CSS.escape(manager.focusedKey.toString())}"]`) as HTMLElement;
+      if (!element) {
+        // If item element wasn't found, return early (don't update autoFocusRef and lastFocusedKey).
+        // The collection may initially be empty (e.g. virtualizer), so wait until the element exists.
+        return;
+      }
+
+      if (modality === 'keyboard' || autoFocusRef.current) {
+        scrollIntoView(scrollRef.current, element);
+
         // Avoid scroll in iOS VO, since it may cause overlay to close (i.e. RAC submenu)
         if (modality !== 'virtual') {
           scrollIntoViewport(element, {containingElement: ref.current});
@@ -425,7 +430,13 @@ export function useSelectableCollection(options: AriaSelectableCollectionOptions
 
     lastFocusedKey.current = manager.focusedKey;
     autoFocusRef.current = false;
-  }, [isVirtualized, scrollRef, manager.focusedKey, manager.isFocused, ref]);
+  });
+
+  // Intercept FocusScope restoration since virtualized collections can reuse DOM nodes.
+  useEvent(ref, 'react-aria-focus-scope-restore', e => {
+    e.preventDefault();
+    manager.setFocused(true);
+  });
 
   let handlers = {
     onKeyDown,

package/src/useSelectableItem.ts

@@ -10,13 +10,13 @@
  * governing permissions and limitations under the License.
  */
 
-import {DOMAttributes, FocusableElement, Key, LongPressEvent, PressEvent} from '@react-types/shared';
+import {DOMAttributes, FocusableElement, Key, LongPressEvent, PressEvent, RefObject} from '@react-types/shared';
 import {focusSafely} from '@react-aria/focus';
 import {isCtrlKeyPressed, isNonContiguousSelectionModifier} from './utils';
 import {mergeProps, openLink, useRouter} from '@react-aria/utils';
 import {MultipleSelectionManager} from '@react-stately/selection';
 import {PressProps, useLongPress, usePress} from '@react-aria/interactions';
-import {RefObject, useEffect, useRef} from 'react';
+import {useEffect, useRef} from 'react';
 
 export interface SelectableItemOptions {
   /**
@@ -30,7 +30,7 @@ export interface SelectableItemOptions {
   /**
    * Ref to the item.
    */
-  ref: RefObject<FocusableElement>,
+  ref: RefObject<FocusableElement | null>,
   /**
    * By default, selection occurs on pointer down. This can be strange if selecting an
    * item causes the UI to disappear immediately (e.g. menus).

package/src/useSelectableList.ts

@@ -11,7 +11,7 @@
  */
 
 import {AriaSelectableCollectionOptions, useSelectableCollection} from './useSelectableCollection';
-import {Collection, DOMAttributes, Key, KeyboardDelegate, Node} from '@react-types/shared';
+import {Collection, DOMAttributes, Key, KeyboardDelegate, LayoutDelegate, Node} from '@react-types/shared';
 import {ListKeyboardDelegate} from './ListKeyboardDelegate';
 import {useCollator} from '@react-aria/i18n';
 import {useMemo} from 'react';
@@ -25,6 +25,12 @@ export interface AriaSelectableListOptions extends Omit<AriaSelectableCollection
    * A delegate object that implements behavior for keyboard focus movement.
    */
   keyboardDelegate?: KeyboardDelegate,
+  /**
+   * A delegate object that provides layout information for items in the collection.
+   * By default this uses the DOM, but this can be overridden to implement things like
+   * virtualized scrolling.
+   */
+  layoutDelegate?: LayoutDelegate,
   /**
    * The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
    */
@@ -47,7 +53,8 @@ export function useSelectableList(props: AriaSelectableListOptions): SelectableL
     collection,
     disabledKeys,
     ref,
-    keyboardDelegate
+    keyboardDelegate,
+    layoutDelegate
   } = props;
 
   // By default, a KeyboardDelegate is provided which uses the DOM to query layout information (e.g. for page up/page down).
@@ -60,9 +67,10 @@ export function useSelectableList(props: AriaSelectableListOptions): SelectableL
       disabledKeys,
       disabledBehavior,
       ref,
-      collator
+      collator,
+      layoutDelegate
     })
-  ), [keyboardDelegate, collection, disabledKeys, ref, collator, disabledBehavior]);
+  ), [keyboardDelegate, layoutDelegate, collection, disabledKeys, ref, collator, disabledBehavior]);
 
   let {collectionProps} = useSelectableCollection({
     ...props,