iOS VO selection improvements (#2521)

* iOS VO selection improvements

* remove dead code

* remove more dead code

* fix imports

* fix ts

* Only announce if NOT after keyboard navigation

* Better comment

* Add keyboard information, add some new strings

* don't break the tests

* review comments and tests

* fixed tests

* Update from code review

* fix lint and tests

* Have our announcer handle everything

* handle select all cases as well

* cleanup and add a test that tries row based onAction

* get test working with no onAction to useTable

* fix lint

* for real fix lint

* now fix ts

* add an odd story that shows some difficulties with onAction

* uses onrow/cellaction on grid state

* remove dead comment

* move long press announcement to useGrid and test

* move out to selection, simplify if expressions

* remove unused strings

* cleanup

* push listbox example for consideration

* fix lint

* Backwards compat with onAction

* cleanup and doc comments

* add deprecated notices

* Move new actions to weak map

* Cleanup

* review followup, move description back to grid for now

* handle if a VO user hasn't interacted with the application

Co-authored-by: Devon Govett <[email protected]>

Author: snowystinger

packages/@react-aria/grid/intl/ar-AE.json

@@ -3,5 +3,6 @@
   "select": "تحديد",
   "selectedAll": "جميع العناصر المحددة.",
   "selectedCount": "{count, plural, =0 {لم يتم تحديد عناصر} one {# عنصر محدد} other {# عنصر محدد}}.",
-  "selectedItem": "{item} المحدد"
+  "selectedItem": "{item} المحدد",
+  "longPressToSelect": "Long press to enter selection mode."
 }

packages/@react-aria/grid/intl/en-US.json

@@ -3,5 +3,6 @@
   "select": "Select",
   "selectedCount": "{count, plural, =0 {No items selected} one {# item selected} other {# items selected}}.",
   "selectedAll": "All items selected.",
-  "selectedItem": "{item} selected."
+  "selectedItem": "{item} selected.",
+  "longPressToSelect": "Long press to enter selection mode."
 }

packages/@react-aria/grid/package.json

@@ -25,6 +25,7 @@
     "@react-aria/selection": "^3.7.0",
     "@react-aria/utils": "^3.10.0",
     "@react-stately/grid": "^3.1.0",
+    "@react-stately/selection": "^3.8.0",
     "@react-stately/virtualizer": "^3.1.6",
     "@react-types/checkbox": "^3.2.3",
     "@react-types/grid": "^3.0.0",

packages/@react-aria/grid/src/useGrid.ts

@@ -15,12 +15,13 @@ import {AriaLabelingProps, DOMProps, KeyboardDelegate, Selection} from '@react-t
 import {filterDOMProps, mergeProps, useId, useUpdateEffect} from '@react-aria/utils';
 import {GridCollection} from '@react-types/grid';
 import {GridKeyboardDelegate} from './GridKeyboardDelegate';
-import {gridKeyboardDelegates} from './utils';
+import {gridMap} from './utils';
 import {GridState} from '@react-stately/grid';
 import {HTMLAttributes, Key, RefObject, useMemo, useRef} from 'react';
 // @ts-ignore
 import intlMessages from '../intl/*.json';
 import {useCollator, useLocale, useMessageFormatter} from '@react-aria/i18n';
+import {useHighlightSelectionDescription} from './useHighlightSelectionDescription';
 import {useSelectableCollection} from '@react-aria/selection';
 
 export interface GridProps extends DOMProps, AriaLabelingProps {
@@ -44,7 +45,11 @@ export interface GridProps extends DOMProps, AriaLabelingProps {
   /**
    * The ref attached to the scrollable body. Used to provided automatic scrolling on item focus for non-virtualized grids.
    */
-  scrollRef?: RefObject<HTMLElement>
+  scrollRef?: RefObject<HTMLElement>,
+  /** Handler that is called when a user performs an action on the row. */
+  onRowAction?: (key: Key) => void,
+  /** Handler that is called when a user performs an action on the cell. */
+  onCellAction?: (key: Key) => void
 }
 
 export interface GridAria {
@@ -65,7 +70,9 @@ export function useGrid<T>(props: GridProps, state: GridState<T, GridCollection<
     keyboardDelegate,
     focusMode,
     getRowText = (key) => state.collection.getItem(key)?.textValue,
-    scrollRef
+    scrollRef,
+    onRowAction,
+    onCellAction
   } = props;
   let formatMessage = useMessageFormatter(intlMessages);
 
@@ -85,6 +92,7 @@ export function useGrid<T>(props: GridProps, state: GridState<T, GridCollection<
     collator,
     focusMode
   }), [keyboardDelegate, state.collection, state.disabledKeys, ref, direction, collator, focusMode]);
+
   let {collectionProps} = useSelectableCollection({
     ref,
     selectionManager: state.selectionManager,
@@ -94,16 +102,25 @@ export function useGrid<T>(props: GridProps, state: GridState<T, GridCollection<
   });
 
   let id = useId();
-  gridKeyboardDelegates.set(state, delegate);
+  gridMap.set(state, {keyboardDelegate: delegate, actions: {onRowAction, onCellAction}});
 
-  let domProps = filterDOMProps(props, {labelable: true});
-  let gridProps: HTMLAttributes<HTMLElement> = mergeProps(domProps, {
-    role: 'grid',
-    id,
-    'aria-multiselectable': state.selectionManager.selectionMode === 'multiple' ? 'true' : undefined,
-    ...collectionProps
+  let descriptionProps = useHighlightSelectionDescription({
+    selectionManager: state.selectionManager,
+    hasItemActions: !!(onRowAction || onCellAction)
   });
 
+  let domProps = filterDOMProps(props, {labelable: true});
+  let gridProps: HTMLAttributes<HTMLElement> = mergeProps(
+    domProps,
+    {
+      role: 'grid',
+      id,
+      'aria-multiselectable': state.selectionManager.selectionMode === 'multiple' ? 'true' : undefined
+    },
+    collectionProps,
+    descriptionProps
+  );
+
   if (isVirtualized) {
     gridProps['aria-rowcount'] = state.collection.size;
     gridProps['aria-colcount'] = state.collection.columnCount;
@@ -114,9 +131,7 @@ export function useGrid<T>(props: GridProps, state: GridState<T, GridCollection<
   let selection = state.selectionManager.rawSelection;
   let lastSelection = useRef(selection);
   useUpdateEffect(() => {
-    // Do not do this when using selectionBehavior = 'replace' to avoid selection announcements
-    // every time the user presses the arrow keys.
-    if (!state.selectionManager.isFocused || state.selectionManager.selectionBehavior === 'replace') {
+    if (!state.selectionManager.isFocused) {
       lastSelection.current = selection;
 
       return;
@@ -126,8 +141,17 @@ export function useGrid<T>(props: GridProps, state: GridState<T, GridCollection<
     let removedKeys = diffSelection(lastSelection.current, selection);
 
     // If adding or removing a single row from the selection, announce the name of that item.
+    let isReplace = state.selectionManager.selectionBehavior === 'replace';
     let messages = [];
-    if (addedKeys.size === 1 && removedKeys.size === 0) {
+
+    if ((state.selectionManager.selectedKeys.size === 1 && isReplace)) {
+      if (state.collection.getItem(state.selectionManager.selectedKeys.keys().next().value)) {
+        let currentSelectionText = getRowText(state.selectionManager.selectedKeys.keys().next().value);
+        if (currentSelectionText) {
+          messages.push(formatMessage('selectedItem', {item: currentSelectionText}));
+        }
+      }
+    } else if (addedKeys.size === 1 && removedKeys.size === 0) {
       let addedText = getRowText(addedKeys.keys().next().value);
       if (addedText) {
         messages.push(formatMessage('selectedItem', {item: addedText}));
@@ -143,7 +167,7 @@ export function useGrid<T>(props: GridProps, state: GridState<T, GridCollection<
 
     // Announce how many items are selected, except when selecting the first item.
     if (state.selectionManager.selectionMode === 'multiple') {
-      if (messages.length === 0 || selection === 'all' || selection.size > 1 || lastSelection.current === 'all' || lastSelection.current.size > 1) {
+      if (messages.length === 0 || selection === 'all' || selection.size > 1 || lastSelection.current === 'all' || lastSelection.current?.size > 1) {
         messages.push(selection === 'all'
           ? formatMessage('selectedAll')
           : formatMessage('selectedCount', {count: selection.size})

packages/@react-aria/grid/src/useGridCell.ts

@@ -12,7 +12,7 @@
 
 import {focusSafely, getFocusableTreeWalker} from '@react-aria/focus';
 import {GridCollection} from '@react-types/grid';
-import {gridKeyboardDelegates} from './utils';
+import {gridMap} from './utils';
 import {GridState} from '@react-stately/grid';
 import {HTMLAttributes, KeyboardEvent as ReactKeyboardEvent, RefObject} from 'react';
 import {isFocusVisible} from '@react-aria/interactions';
@@ -30,7 +30,11 @@ interface GridCellProps {
   focusMode?: 'child' | 'cell',
   /** Whether selection should occur on press up instead of press down. */
   shouldSelectOnPressUp?: boolean,
-  /** Handler that is called when a user performs an action on the cell. */
+  /**
+   * Handler that is called when a user performs an action on the cell.
+   * Please use onCellAction at the collection level instead.
+   * @deprecated
+   **/
   onAction?: () => void
 }
 
@@ -56,7 +60,7 @@ export function useGridCell<T, C extends GridCollection<T>>(props: GridCellProps
   } = props;
 
   let {direction} = useLocale();
-  let keyboardDelegate = gridKeyboardDelegates.get(state);
+  let {keyboardDelegate, actions: {onCellAction}} = gridMap.get(state);
 
   // Handles focusing the cell. If there is a focusable child,
   // it is focused, otherwise the cell itself is focused.
@@ -84,7 +88,7 @@ export function useGridCell<T, C extends GridCollection<T>>(props: GridCellProps
     isVirtualized,
     focus,
     shouldSelectOnPressUp,
-    onAction
+    onAction: onCellAction ? () => onCellAction(node.key) : onAction
   });
 
   let onKeyDown = (e: ReactKeyboardEvent) => {

packages/@react-aria/grid/src/useGridRow.ts

@@ -11,6 +11,7 @@
  */
 
 import {GridCollection} from '@react-types/grid';
+import {gridMap} from './utils';
 import {GridState} from '@react-stately/grid';
 import {HTMLAttributes, RefObject} from 'react';
 import {Node} from '@react-types/shared';
@@ -23,7 +24,11 @@ export interface GridRowProps<T> {
   isVirtualized?: boolean,
   /** Whether selection should occur on press up instead of press down. */
   shouldSelectOnPressUp?: boolean,
-  /** Handler that is called when a user performs an action on the row. */
+  /**
+   * Handler that is called when a user performs an action on the row.
+   * Please use onCellAction at the collection level instead.
+   * @deprecated
+   **/
   onAction?: () => void
 }
 
@@ -47,13 +52,14 @@ export function useGridRow<T, C extends GridCollection<T>, S extends GridState<T
     onAction
   } = props;
 
+  let {actions: {onRowAction}} = gridMap.get(state);
   let {itemProps, isPressed} = useSelectableItem({
     selectionManager: state.selectionManager,
     key: node.key,
     ref,
     isVirtualized,
     shouldSelectOnPressUp,
-    onAction
+    onAction: onRowAction ? () => onRowAction(node.key) : onAction
   });
 
   let isSelected = state.selectionManager.isSelected(node.key);

packages/@react-aria/grid/src/useHighlightSelectionDescription.ts

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2021 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 {AriaLabelingProps} from '@react-types/shared';
+// @ts-ignore
+import intlMessages from '../intl/*.json';
+import {MultipleSelectionManager} from '@react-stately/selection';
+import {useDescription} from '@react-aria/utils';
+import {useInteractionModality} from '@react-aria/interactions';
+import {useMemo} from 'react';
+import {useMessageFormatter} from '@react-aria/i18n';
+
+interface UseHighlightSelectionDescriptionProps {
+  selectionManager: MultipleSelectionManager,
+  hasItemActions?: boolean
+}
+
+/**
+ * Computes the description for a grid selectable collection.
+ * @param props
+ */
+export function useHighlightSelectionDescription(props: UseHighlightSelectionDescriptionProps): AriaLabelingProps {
+  let formatMessage = useMessageFormatter(intlMessages);
+  let modality = useInteractionModality();
+  // null is the default if the user hasn't interacted with the table at all yet or the rest of the page
+  let shouldLongPress = (modality === 'pointer' || modality === 'virtual' || modality == null) && 'ontouchstart' in window;
+
+  let interactionDescription = useMemo(() => {
+    let selectionMode = props.selectionManager.selectionMode;
+    let selectionBehavior = props.selectionManager.selectionBehavior;
+
+    let message = undefined;
+    if (shouldLongPress) {
+      message = formatMessage('longPressToSelect');
+    }
+
+    return selectionBehavior === 'replace' && selectionMode !== 'none' && props.hasItemActions ? message : undefined;
+  }, [props.selectionManager.selectionMode, props.selectionManager.selectionBehavior, props.hasItemActions, formatMessage, shouldLongPress]);
+
+  let descriptionProps = useDescription(interactionDescription);
+  return descriptionProps;
+}

packages/@react-aria/grid/src/utils.ts

@@ -12,7 +12,18 @@
 
 import type {GridCollection} from '@react-types/grid';
 import type {GridState} from '@react-stately/grid';
+import {Key} from 'react';
 import type {KeyboardDelegate} from '@react-types/shared';
 
-// Used to share keyboard delegate between useGrid and useGridCell
-export const gridKeyboardDelegates = new WeakMap<GridState<unknown, GridCollection<unknown>>, KeyboardDelegate>();
+interface GridMapShared {
+  keyboardDelegate: KeyboardDelegate,
+  actions: {
+    onRowAction: (key: Key) => void,
+    onCellAction: (key: Key) => void
+  }
+}
+
+// Used to share:
+// keyboard delegate between useGrid and useGridCell
+// onRowAction/onCellAction across hooks
+export const gridMap = new WeakMap<GridState<unknown, GridCollection<unknown>>, GridMapShared>();

packages/@react-aria/grid/test/useGrid.test.js

@@ -38,6 +38,13 @@ function renderGrid(props = {}) {
 }
 
 describe('useGrid', () => {
+  beforeAll(() => {
+    jest.useFakeTimers('modern');
+  });
+  afterEach(() => {
+    // run out notifications
+    act(() => {jest.runAllTimers();});
+  });
   it('gridFocusMode = row, cellFocusMode = cell', () => {
     let tree = renderGrid({gridFocusMode: 'row', cellFocusMode: 'cell'});
 

packages/@react-aria/table/src/useTable.ts

@@ -117,6 +117,13 @@ export function useTable<T>(props: TableProps<T>, state: TableState<T>, ref: Ref
   }, [sortDescription]);
 
   return {
-    gridProps: mergeProps(gridProps, descriptionProps)
+    gridProps: mergeProps(
+      gridProps,
+      descriptionProps,
+      {
+        // merge sort description with long press information
+        'aria-describedby': [descriptionProps['aria-describedby'], gridProps['aria-describedby']].filter(Boolean).join(' ')
+      }
+    )
   };
 }