Merge branch 'main' of github.com:adobe-private/react-spectrum-v3

Author: devongovett

packages/@react-aria/interactions/docs/useHover.mdx

@@ -49,6 +49,8 @@ but `:hover` is problematic on touch devices due to mouse emulation in mobile br
 and device, `:hover` may never apply, or may apply continuously until the user touches another element.
 `useHover` only applies when the pointer is truly capable of hovering, and emulated mouse events are ignored.
 
+Read our [blog post](/blog/building-a-button-part-2.html) about the complexities of hover event handling to learn more.
+
 ## Usage
 
 `useHover` returns props that you should spread onto the target element:

packages/@react-aria/interactions/docs/useLongPress.mdx

@@ -0,0 +1,130 @@
+<!-- Copyright 2020 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 {Layout} from '@react-spectrum/docs';
+export default Layout;
+
+import docs from 'docs:@react-aria/interactions';
+import typesDocs from 'docs:@react-types/shared/src/events.d.ts';
+import {HeaderInfo, FunctionAPI, TypeContext, InterfaceType, TypeLink} from '@react-spectrum/docs';
+import packageData from '@react-aria/interactions/package.json';
+
+```jsx import
+import {useLongPress, usePress} from '@react-aria/interactions';
+```
+
+---
+category: Interactions
+keywords: [long press interactions, long press events, long press gesture, aria]
+---
+
+# useLongPress
+
+<p>{docs.exports.useLongPress.description}</p>
+
+<HeaderInfo
+  packageData={packageData}
+  componentNames={['useLongPress']} />
+
+## API
+
+<FunctionAPI function={docs.exports.useLongPress} links={docs.links} />
+
+## Features
+
+`useLongPress` handles long press interactions across both mouse and touch devices. A long press is triggered when a user presses
+and holds their pointer over a target for a minimum period of time. If the user moves their pointer off of the target before the
+time threshold, the interaction is canceled. Once a long press event is triggered, other pointer interactions that may be active
+such as `usePress` and `useMove` will be canceled so that only the long press is activated.
+
+* Handles mouse and touch events
+* Uses pointer events where available, with fallbacks to mouse and touch events
+* Ignores emulated mouse events in mobile browsers
+* Prevents text selection on touch devices while long pressing
+* Prevents browser and OS context menus from appearing while long pressing
+* Customizable time threshold for long press
+* Supports an accessibility description to indicate to assistive technology users that a long press action is available
+
+## Usage
+
+`useLongPress` returns props that you should spread onto the target element:
+
+<TypeContext.Provider value={docs.links}>
+  <InterfaceType properties={docs.links[docs.exports.useLongPress.return.id].properties} />
+</TypeContext.Provider>
+
+`useLongPress` supports the following event handlers and options:
+
+<TypeContext.Provider value={docs.links}>
+  <InterfaceType properties={docs.links[docs.exports.useLongPress.parameters[0].value.id].properties} />
+</TypeContext.Provider>
+
+Each of these handlers is fired with a `LongPressEvent`, which exposes information about the target and the
+type of event that triggered the interaction.
+
+<TypeContext.Provider value={typesDocs.links}>
+  <InterfaceType properties={typesDocs.exports.LongPressEvent.properties} />
+</TypeContext.Provider>
+
+## Example
+
+This example shows a button that has both a normal press action using [usePress](usePress.html), as well as a long
+press action using `useLongPress`. Pressing the button will set the mode to "Normal speed", and long pressing it will
+set the mode to "Hyper speed". All of the emitted events are also logged below. Note that when long pressing the button,
+only a long press is emitted, and no normal press is emitted on pointer up.
+
+**Note**: this example does not have a keyboard accessible way to trigger the long press action. Because the method of triggering
+this action will differ depending on the component, it is outside the scope of `useLongPress`. Make sure to implement a keyboard
+friendly alternative to all long press interactions if you are using this hook directly.
+
+```tsx example
+import {mergeProps} from '@react-aria/utils';
+
+function Example() {
+  let [events, setEvents] = React.useState([]);
+  let [mode, setMode] = React.useState('Activate');
+  let {longPressProps} = useLongPress({
+    accessibilityDescription: 'Long press to activate hyper speed',
+    onLongPressStart: e => setEvents(
+      events => [`long press start with ${e.pointerType}`, ...events]
+    ),
+    onLongPressEnd: e => setEvents(
+      events => [`long press end with ${e.pointerType}`, ...events]
+    ),
+    onLongPress: e => {
+      setMode('Hyper speed');
+      setEvents(
+        events => [`long press with ${e.pointerType}`, ...events]
+      );
+    }
+  });
+
+  let {pressProps} = usePress({
+    onPress: e => {
+      setMode('Normal speed');
+      setEvents(
+        events => [`press with ${e.pointerType}`, ...events]
+      );
+    }
+  });
+
+  return (
+    <>
+      <button {...mergeProps(pressProps, longPressProps)}>{mode}</button>
+      <ul
+        style={{
+          maxHeight: '200px',
+          overflow: 'auto'
+        }}>
+        {events.map((e, i) => <li key={i}>{e}</li>)}
+      </ul>
+    </>
+  );
+}
+```

packages/@react-aria/interactions/docs/usePress.mdx

@@ -52,6 +52,8 @@ the visual appearance of the target. If the pointer is released over the target,
 * Handles canceling press interactions on scroll
 * Normalizes many cross browser inconsistencies
 
+Read our [blog post](/blog/building-a-button-part-1.html) about the complexities of press event handling to learn more.
+
 ## Usage
 
 `usePress` returns props that you should spread onto the target element, along with the current press state:

packages/@react-aria/table/docs/useTable.mdx

@@ -64,6 +64,9 @@ HTML tables are meant for static content, rather than tables with rich interacti
 * Single, multiple, or no row selection via mouse, touch, or keyboard interactions
 * Support for disabled rows, which cannot be selected
 * Optional support for checkboxes in each row for selection, as well as in the header to select all rows
+* Support for both `toggle` and `replace` selection behaviors
+* Support for row actions via double click, <kbd>Enter</kbd> key, or tapping
+* Long press to enter selection mode on touch when there is both selection and row actions
 * Column sorting support
 * Async loading, infinite scrolling, filtering, and sorting support
 * Support for column groups via nested columns
@@ -132,7 +135,12 @@ import {useRef} from 'react';
 import {useFocusRing} from '@react-aria/focus';
 
 function Table(props) {
-  let state = useTableState({...props, showSelectionCheckboxes: props.selectionMode === 'multiple'});
+  let {selectionMode, selectionBehavior, onAction} = props;
+  let state = useTableState({
+    ...props,
+    showSelectionCheckboxes: selectionMode === 'multiple' && selectionBehavior !== 'replace'
+  });
+
   let ref = useRef();
   let {collection} = state;
   let {gridProps} = useTable(props, state, ref);
@@ -152,7 +160,7 @@ function Table(props) {
       </TableRowGroup>
       <TableRowGroup type="tbody">
         {[...collection.body.childNodes].map(row => (
-          <TableRow key={row.key} item={row} state={state}>
+          <TableRow key={row.key} item={row} state={state} onAction={onAction}>
             {[...row.childNodes].map(cell =>
               cell.props.isSelectionCell
                 ? <TableCheckboxCell key={cell.key} cell={cell} state={state} />
@@ -251,27 +259,32 @@ Now that we've covered the table header, let's move on to the body. We'll use
 the <TypeLink links={docs.links} type={docs.exports.useTableRow} /> hook to render each row in the table.
 Table rows can be focused and navigated to using the keyboard via the arrow keys. In addition, table rows
 can optionally support selection via mouse, touch, or keyboard. Clicking, tapping, or pressing the <kbd>Space</kbd>
-key anywhere in the row selects it.
+key anywhere in the row selects it. Row actions are also supported via the provided `onAction` prop. See [below](#row-and-cell-actions) for details.
 
 We'll use the <TypeLink links={selectionDocs.links} type={selectionDocs.exports.SelectionManager} /> object exposed
 by the `state` to determine if a row is selected, and render a pink background if so. We'll also use the <TypeLink links={focusDocs.links} type={focusDocs.exports.useFocusRing} />
 hook to render a focus ring when the user navigates to the row with the keyboard.
 
 ```tsx example export=true render=false
-function TableRow({item, children, state}) {
+function TableRow({item, children, state, onAction}) {
   let ref = useRef();
   let isSelected = state.selectionManager.isSelected(item.key);
-  let {rowProps} = useTableRow({node: item}, state, ref);
+  let {rowProps, isPressed} = useTableRow({
+    node: item,
+    onAction: onAction && (() => onAction(item.key))
+  }, state, ref);
   let {isFocusVisible, focusProps} = useFocusRing();
 
   return (
     <tr
       style={{
         background: isSelected
           ? 'blueviolet'
-          : item.index % 2
-            ? 'var(--spectrum-alias-highlight-hover)'
-            : 'none',
+          : isPressed
+            ? 'var(--spectrum-global-color-gray-400)'
+            : item.index % 2
+              ? 'var(--spectrum-alias-highlight-hover)'
+              : 'none',
         color: isSelected ? 'white' : null,
         outline: isFocusVisible ? '2px solid orange' : 'none'
       }}
@@ -584,6 +597,26 @@ Note that you are responsible for the styling of disabled rows, however, the sel
 <PokemonTable selectionMode="multiple" disabledKeys={[3]} />
 ```
 
+### Selection behavior
+
+By default, `useTable` uses the `"toggle"` selection behavior, which behaves like a checkbox group: clicking, tapping, or pressing the <kbd>Space</kbd> or <kbd>Enter</kbd> keys toggles selection for the focused row. Using the arrow keys moves focus but does not change selection. The `"toggle"` selection mode is often paired with a column of checkboxes in each row as an explicit affordance for selection.
+
+When the `selectionBehavior` prop is set to `"replace"`, clicking a row with the mouse _replaces_ the selection with only that row. Using the arrow keys moves both focus and selection. To select multiple rows, modifier keys such as <kbd>Ctrl</kbd>, <kbd>Cmd</kbd>, and <kbd>Shift</kbd> can be used. To move focus without moving selection, the <kbd>Ctrl</kbd> key on Windows or the <kbd>Option</kbd> key on macOS can be held while pressing the arrow keys. Holding this modifier while pressing the <kbd>Space</kbd> key toggles selection for the focused row, which allows multiple selection of non-contiguous items. On touch screen devices, selection always behaves as toggle since modifier keys may not be available. This behavior emulates native platforms such as macOS and Windows, and is often used when checkboxes in each row are not desired.
+
+```tsx example
+<PokemonTable selectionMode="multiple" selectionBehavior="replace" />
+```
+
+### Row and cell actions
+
+`useTable` may be used in use cases where users can perform actions on rows or cells, such as navigating into items to open them or get more details. In the default `"toggle"` selection behavior, it is recommended to use a link in the first column for navigation.
+
+In the `"replace"` selection behavior, the `onAction` prop can be used to enable row and cell actions, which differ depending on the interaction method. When provided to `useTableRow` or `useTableCell`, double clicking with a mouse or pressing the <kbd>Enter</kbd> key triggers `onAction`, while single click and the <kbd>Space</kbd> key are reserved for selection. On touch devices, `onAction` becomes the primary tap interaction, and a long press enters into selection mode, which temporarily swaps the selection behavior to `"toggle"` to perform selection (you may wish to display checkboxes when this happens). Deselecting all items exits selection mode and reverts the selection behavior back to `"replace"`. Double clicking matches the behavior of desktop platforms like macOS and Windows, and a separate selection mode matches mobile platforms like iOS and Android.
+
+```tsx example
+<PokemonTable selectionMode="multiple" selectionBehavior="replace" onAction={key => alert(`Opening item ${key}...`)} />
+```
+
 ### Sorting
 
 Table supports sorting its data when a column header is pressed. To designate that a Column should support sorting, provide it with

packages/@react-spectrum/table/docs/TableView.mdx

@@ -465,6 +465,28 @@ You can disable specific rows by providing an array of keys to TableView via the
 <PokemonTable selectionMode="multiple" disabledKeys={[3]} />
 ```
 
+### Highlight selection
+
+By default, TableView uses the checkbox selection style, which includes a column of checkboxes in each row for selection. When the `selectionStyle` prop is set to `"highlight"`, the checkboxes are hidden, and the selected rows are displayed with a highlighted background instead.
+
+In addition to changing the appearance, the selection behavior also changes depending on the `selectionStyle` prop. In the default checkbox selection style, clicking, tapping, or pressing the <kbd>Space</kbd> or <kbd>Enter</kbd> keys toggles selection for the focused row. Using the arrow keys moves focus but does not change selection.
+
+In the highlight selection style, however, clicking a row with the mouse _replaces_ the selection with only that row. Using the arrow keys moves both focus and selection. To select multiple rows, modifier keys such as <kbd>Ctrl</kbd>, <kbd>Cmd</kbd>, and <kbd>Shift</kbd> can be used.  To move focus without moving selection, the <kbd>Ctrl</kbd> key on Windows or the <kbd>Option</kbd> key on macOS can be held while pressing the arrow keys. Holding this modifier while pressing the <kbd>Space</kbd> key toggles selection for the focused row, which allows multiple selection of non-contiguous items. On touch screen devices, selection always behaves as toggle since modifier keys may not be available. This behavior emulates native platforms such as macOS and Windows.
+
+```tsx example
+<PokemonTable selectionMode="multiple" selectionStyle="highlight" />
+```
+
+### Row actions
+
+TableView may be used in use cases where users can perform actions on rows, such as navigating into items to open them or get more details. In the default checkbox selection style, it is recommended to use a [Link](Link.html) component in the first column for navigation.
+
+In the highlight selection style, the `onAction` prop can be used to enable row actions, which differ depending on the interaction method. When provided, double clicking with a mouse or pressing the <kbd>Enter</kbd> key triggers `onAction`, while single click and the <kbd>Space</kbd> key are reserved for selection. On touch devices, `onAction` becomes the primary tap interaction, and a long press enters into selection mode, which displays checkboxes to perform selection. Deselecting all items exits selection mode and hides the checkboxes. Double clicking matches the behavior of desktop platforms like macOS and Windows, and a separate selection mode matches mobile platforms like iOS and Android.
+
+```tsx example
+<PokemonTable selectionMode="multiple" selectionStyle="highlight" onAction={key => alert(`Opening item ${key}...`)} />
+```
+
 ## Sorting
 
 TableView supports sorting its data when a column header is pressed. To designate that a Column should support sorting, provide it with