docs: update for v0.10 (floating-ui#1892)

Author: atomiks

website/pages/docs/FloatingFocusManager.mdx

@@ -37,7 +37,6 @@ interface Props {
     | number
     | React.MutableRefObject<HTMLElement | null>;
   returnFocus?: boolean;
-  preventTabbing?: boolean;
   endGuard?: boolean;
   modal?: boolean;
 }
@@ -85,9 +84,6 @@ Which element to initially focus. Can be either a number
 (tabbable index as specified by the `order{:.objectKey}`) or a
 ref.
 
-> This does not have an effect when `preventTabbing{:.keyword}`
-> is enabled.
-
 ```js
 <FloatingFocusManager
   context={context}
@@ -105,35 +101,12 @@ Determines if focus should be returned to the element that was
 focused prior to opening the floating element (usually the
 reference element).
 
-> This does not have an effect when `preventTabbing{:.keyword}`
-> is enabled.
-
 ```js
 <FloatingFocusManager context={context} returnFocus={false}>
   {/* floating element */}
 </FloatingFocusManager>
 ```
 
-### preventTabbing
-
-default: `false{:js}`
-
-Determines if the tab key does not perform any action, so that
-focus cannot escape the floating element. Focus is instead
-handled by `useListNavigation(){:js}` (i.e. arrow key
-navigation).
-
-This prop is required when the focus is
-[modal](/docs/FloatingFocusManager#modal) and the floating
-element is portalled outside of the reference element's DOM
-context.
-
-```js
-<FloatingFocusManager context={context} preventTabbing={true}>
-  {/* floating element */}
-</FloatingFocusManager>
-```
-
 ### endGuard
 
 default: `true{:js}`
@@ -157,20 +130,44 @@ Determines if focus is "modal", meaning focus is fully trapped
 inside the floating element and outside content cannot be
 accessed. This includes screen reader virtual cursors.
 
-> If `false{:js}`, the floating element must be rendered directly
-> after its reference element (e.g. not in a FloatingPortal).
-
 ```js
 <FloatingFocusManager context={context} modal={false}>
   {/* floating element */}
 </FloatingFocusManager>
 ```
 
-#### Input comboboxes
+#### Non-modal behavior
+
+The floating element must be rendered directly after its
+reference element (e.g. not in a FloatingPortal) when non-modal.
+
+#### Modal behavior
+
+Ensure you have an explicit "close" button. This can be either
+visible to all users, or visually-hidden so it is only available
+to assistive tech.
+
+Touch-based screen readers often will not have an `esc` key
+available to dismiss the element, so an explicit close button is
+required.
+
+You may use the reference element as the close button with some
+components, so the user can navigate to it and use it as a toggle
+to both close and open the floating element. This can be achieved
+with the `order{:.keyword}` prop and adding the reference as a
+string.
+
+#### Comboboxes
+
+The listbox part of a combobox should be rendered directly after
+the input reference element when possible.
+
+If the listbox is portaled, detection is added so that DOM focus
+does not become modal in this case, but screen reader virtual
+cursors do become modal. This ensures a touch user can swipe
+right (e.g. iOS screen reader) to navigate the listbox options
+immediately.
 
-`<input />{:js}` comboboxes should not be modal when possible.
-When setting them to modal, focus does not become modal but
-screen reader virtual cursors do become modal. Therefore, the
-listbox should have a visually-hidden dismiss button to ensure
-touch-based screen reader users can escape the list without
-needing to select anything.
+As with all modal-based focus management, the listbox should have
+a visually-hidden dismiss button to ensure touch-based screen
+reader users can escape the list due to a lack of an `esc` key.

website/pages/docs/useClick.mdx

@@ -23,7 +23,7 @@ const {getReferenceProps, getFloatingProps} = useInteractions([
 ```js
 interface Props {
   enabled?: boolean;
-  pointerDown?: boolean;
+  event?: 'click' | 'mousedown';
   toggle?: boolean;
   ignoreMouse?: boolean;
   keyboardHandlers?: boolean;
@@ -42,17 +42,16 @@ useClick(context, {
 });
 ```
 
-### pointerDown
+### event
 
-default: `false{:js}`
+default: `'click'{:js}`
 
-Whether to prefer the `pointerdown{:.string}` event over
-`click{:.string}` (for faster feedback). Keyboard clicks will
-continue to work.
+The type of event to use to determine a "click" with mouse input.
+Keyboard clicks work as normal.
 
 ```js
 useClick(context, {
-  pointerDown: true,
+  event: 'mousedown',
 });
 ```
 

website/pages/docs/useDismiss.mdx

@@ -24,8 +24,10 @@ const {getReferenceProps, getFloatingProps} = useInteractions([
 interface Props {
   enabled?: boolean;
   escapeKey?: boolean;
-  referencePointerDown?: boolean;
-  outsidePointerDown?: boolean;
+  referencePress?: boolean;
+  referencePressEvent?: 'pointerdown' | 'mousedown' | 'click';
+  outsidePress?: boolean;
+  outsidePressEvent?: 'pointerdown' | 'mousedown' | 'click';
   ancestorScroll?: boolean;
   bubbles?: boolean;
 }
@@ -56,29 +58,81 @@ useDismiss(context, {
 });
 ```
 
-### referencePointerDown
+### referencePress
 
 default: `false{:js}`
 
-Whether to dismiss the floating element upon pointer down of the
+Whether to dismiss the floating element upon pressing the
 reference element.
 
 ```js
 useDismiss(context, {
-  referencePointerDown: true,
+  referencePress: true,
 });
 ```
 
-### outsidePointerDown
+You likely want to ensure the `move{:.objectKey}` option in the
+`useHover(){:js}` hook has been disabled when this is in use.
+
+#### Keyboard press dismissal
+
+If you'd like to ensure the floating element is also dismissed
+upon "pressing" the reference element via the keyboard, you can
+add in your own handler(s) for this.
+
+```js
+getReferenceProps({
+  // for a native <button>
+  onClick() {
+    setOpen(false);
+  },
+});
+```
+
+### referencePressEvent
+
+default: `'pointerdown'{:js}`
+
+The type of event to use to determine a "press".
+
+```js
+useDismiss(context, {
+  // eager on both mouse + touch input
+  referencePressEvent: 'pointerdown',
+  // eager on mouse input, lazy on touch input
+  referencePressEvent: 'mousedown',
+  // lazy on both mouse + touch input
+  referencePressEvent: 'click',
+});
+```
+
+### outsidePress
 
 default: `true{:js}`
 
-Whether to dismiss the floating element upon pointer down outside
-of both the floating and reference elements.
+Whether to dismiss the floating element upon pressing outside of
+both the floating and reference elements.
+
+```js
+useDismiss(context, {
+  outsidePress: false,
+});
+```
+
+### outsidePressEvent
+
+default: `'pointerdown'{:js}`
+
+The type of event to use to determine a "press".
 
 ```js
 useDismiss(context, {
-  outsidePointerDown: false,
+  // eager on both mouse + touch input
+  outsidePressEvent: 'pointerdown',
+  // eager on mouse input, lazy on touch input
+  outsidePressEvent: 'mousedown',
+  // lazy on both mouse + touch input
+  outsidePressEvent: 'click',
 });
 ```