docs: update

website/lib/components/PackageSelect.js

@@ -98,7 +98,7 @@ const ReactPackageButton = forwardRef(({package: pkg, ...props}, ref) => {
 
 export function ReactSelect() {
   return (
-    <Composite className="-mt-2 flex gap-1" role="group">
+    <Composite className="-mt-2 mb-4 flex gap-1" role="group">
       <CompositeItem render={<ReactPackageButton package="react" />}>
         React (all features)
       </CompositeItem>
@@ -235,7 +235,7 @@ function Option({
     >
       <div
         className={cn('relative top-[1px] h-3 w-3 rounded-full', {
-          'bg-gray-100 dark:bg-gray-400': selectedIndex !== index,
+          'bg-gray-900/30 dark:bg-gray-200/50': selectedIndex !== index,
           'bg-rose-500 dark:bg-rose-400': selectedIndex === index,
         })}
       />

website/pages/docs/Composite.mdx

@@ -10,6 +10,10 @@ contexts.
 import {Composite, CompositeItem} from '@floating-ui/react';
 ```
 
+This is useful to enable navigation of a list of items that
+aren't part of a floating element. A menubar is an example of a
+composite, with each reference element being an item.
+
 <ShowFor packages={['react-dom']}>
 
 <PackageLimited>@floating-ui/react only</PackageLimited>
@@ -18,8 +22,6 @@ import {Composite, CompositeItem} from '@floating-ui/react';
 
 </PageCard>
 
-A menubar is an example of a composite.
-
 ## Usage
 
 ```js
@@ -31,8 +33,8 @@ A menubar is an example of a composite.
 ```
 
 The `render{:.keyword}` prop can be used to customize the
-rendering of the composite components. Both `Composite{:.class}` and
-`CompositeItem{:.class}` accept a JSX element:
+rendering of the composite components. Both `Composite{:.class}`
+and `CompositeItem{:.class}` accept a JSX element:
 
 ```js
 <CompositeItem render={<select />}>
@@ -158,24 +160,27 @@ return <Composite onNavigate={setActiveIndex} />;
 
 default: `undefined{:js}`
 
-Only for grid navigation, an array of `Dimensions` objects, which specify the
-width (number of columns) and height (number of rows) of each item, so
-the navigation algorithm can take the variable sizes into account.
-If not specified, every item will be treated as if it has a size of 1
-row and 1 column.
+Only for grid navigation, an array of `Dimensions` objects, which
+specify the width (number of columns) and height (number of rows)
+of each item, so the navigation algorithm can take the variable
+sizes into account. If not specified, every item will be treated
+as if it has a size of 1 row and 1 column.
 
 ```js
 <Composite
-  itemSizes={[{ width: 2, height: 2 }, { width: 1, height: 3 }]}
+  itemSizes={[
+    {width: 2, height: 2},
+    {width: 1, height: 3},
+  ]}
 />
 ```
 
 ### `dense{:.keyword}`
 
 default: `false{:js}`
 
-Only for grid navigation, determines if the grid positioning algorithm
-should follow CSS Grid's `auto-flow` `dense` algorithm.
+Only for grid navigation, determines if the grid positioning
+algorithm should follow CSS Grid's `auto-flow` `dense` algorithm.
 
 ```js
 <Composite dense />

website/pages/docs/FloatingDelayGroup.mdx

@@ -10,11 +10,17 @@ after the first floating element of the group opens.
 import {FloatingDelayGroup} from '@floating-ui/react';
 ```
 
-</PageCard>
+This is useful to enable higher discovery of floating elements
+when they have a hover delay (like tooltips) when their reference
+elements are placed near each other.
+
+<ShowFor packages={['react-dom']}>
+
+<PackageLimited>@floating-ui/react only</PackageLimited>
 
-This allows higher discovery of floating elements when they have
-a hover delay (like tooltips) when their reference elements are
-placed near each other.
+</ShowFor>
+
+</PageCard>
 
 ```js
 function App() {
@@ -46,7 +52,7 @@ To enable delay grouping:
   `<FloatingDelayGroup />{:js}` provider.
 - Call `useDelayGroupContext(){:js}` to read the data from
   `<FloatingDelayGroup />{:js}`, which provides the
-  <WordHighlight id='a'>delay</WordHighlight> for the group to
+    <WordHighlight id='a'>delay</WordHighlight> for the group to
 pass to the `useHover(){:js}` Hook.
 - `useDelayGroup(){:js}`, a Hook called inside the component,
   enables grouping for the component.

website/pages/docs/FloatingFocusManager.mdx

@@ -10,6 +10,9 @@ trapped inside the floating element while it is rendered.
 import {FloatingFocusManager} from '@floating-ui/react';
 ```
 
+This is necessary to ensure that focus is properly managed for
+keyboard interaction.
+
 <ShowFor packages={['react-dom']}>
 
 <PackageLimited>@floating-ui/react only</PackageLimited>

website/pages/docs/FloatingList.mdx

@@ -3,14 +3,16 @@
 # FloatingList
 
 Provides the ability to create composable children APIs for list
-components, without needing to keep track of a list item index
-for [`useListNavigation`](/docs/useListNavigation) or
-[`useTypeahead`](/docs/useTypeahead).
+components
 
 ```js
 import {FloatingList, useListItem} from '@floating-ui/react';
 ```
 
+This is useful to prevent the need to keep track of a list item's
+index for [`useListNavigation`](/docs/useListNavigation) or
+[`useTypeahead`](/docs/useTypeahead).
+
 <ShowFor packages={['react-dom']}>
 
 <PackageLimited>@floating-ui/react only</PackageLimited>
@@ -76,7 +78,8 @@ return (
 
 This Hook is used to register a list item and its index (DOM
 position) in the `FloatingList`. It returns two properties:
-<WordHighlight id="a">ref</WordHighlight> and 
+
+<WordHighlight id="a">ref</WordHighlight> and
 <WordHighlight id="b">index</WordHighlight>.
 
 ```js {3} /ref/1,3#a /index/#b

website/pages/docs/FloatingOverlay.mdx

@@ -2,13 +2,15 @@
 
 # FloatingOverlay
 
-Provides base styling for a fixed overlay element to dim content
-or block pointer events behind a floating element.
+Provides base styling for a fixed overlay element.
 
 ```js
 import {FloatingOverlay} from '@floating-ui/react';
 ```
 
+This is useful to dim content or block pointer events behind a
+floating element, in addition to locking the body scroll.
+
 <ShowFor packages={['react-dom']}>
 
 <PackageLimited>@floating-ui/react only</PackageLimited>

website/pages/docs/FloatingPortal.mdx

@@ -9,6 +9,11 @@ default, outside of the app root and into the body.
 import {FloatingPortal} from '@floating-ui/react';
 ```
 
+This is necessary to ensure the floating element can appear
+outside any potential parent containers that cause clipping (such
+as `overflow: hidden`), while retaining its location in the React
+tree.
+
 <ShowFor packages={['react-dom']}>
 
 <PackageLimited>@floating-ui/react only</PackageLimited>

website/pages/docs/FloatingTree.mdx

@@ -13,18 +13,15 @@ children of each other on the DOM.
 
 </PageCard>
 
-<Notice>
-  This is not necessary in all cases, except when there must be
-  explicit communication between parent and child floating elements. 
-  It is necessary for:
+This is not necessary in all cases, except when there must be
+explicit communication between parent and child floating
+elements. It is necessary for:
 
 - The `bubbles{:.key}` option in the `useDismiss(){:js}` Hook
 - [Nested virtual list navigation](/docs/useListNavigation#virtualitemref)
 - Nested floating elements that each open on hover
 - Custom communication between parent and child floating elements
 
-</Notice>
-
 ## Usage
 
 The following creates an infinitely nestable `<Popover>{:js}`
@@ -146,6 +143,7 @@ export function Popover(props) {
 
 ## Troubleshooting
 
-Ensure that the component that you're calling `useFloatingNodeId(){:js}` is a 
-_child_ of the `<FloatingTree>{:js}` wrapper. If it is not, then it will not
-be able to find the tree context.
+Ensure that the component that you're calling
+`useFloatingNodeId(){:js}` is a _child_ of the
+`<FloatingTree>{:js}` wrapper. If it is not, then it will not be
+able to find the tree context.

website/pages/docs/autoUpdate.mdx

@@ -75,8 +75,6 @@ especially with many floating elements being created.
 
 <ShowFor packages={['react', 'react-dom']}>
 
-### Conditional rendering
-
 If you're conditionally rendering the floating element
 (recommended), use the `whileElementsMounted{:.key}` option:
 
@@ -90,8 +88,6 @@ useFloating({
 cleaning up `autoUpdate` based on the presence of the reference
 and floating element.
 
-### CSS
-
 Alternatively, if you've hidden the floating element with CSS
 (based on an `isOpen` state), use an effect to handle it instead:
 

website/pages/docs/flip.mdx

@@ -367,26 +367,12 @@ In each of the following demos, the `placement{:.key}` is
   </Chrome>
 </div>
 
-#### Combining with `shift(){:js}`
+<Notice title="Recommended reading" gap="above">
 
-If `shift(){:js}` is in use in the middleware array, you may
-desire to disable `crossAxis{:.key}` overflow checking, which
-will allow `shift(){:js}` to perform its work without falling
-back to the opposite axis (therefore preserving the original axis
-as best as possible):
+Check [combining with `shift`](/docs/flip#combining-with-shift)
+when using this option.
 
-```js {4}
-const middleware = [
-  flip({
-    fallbackAxisSideDirection: 'start',
-    crossAxis: false,
-  }),
-  shift(),
-];
-```
-
-If your placement is not edge aligned, disabling it is usually a
-good choice.
+</Notice>
 
 ### `flipAlignment{:.key}`
 
@@ -459,6 +445,13 @@ In the above example, if `placement{:.key}` is set to
   explicit list is preferred, they will be ignored.
 </Notice>
 
+<Notice title="Recommended reading" gap="above">
+
+Check [combining with `shift`](/docs/flip#combining-with-shift)
+when using this option.
+
+</Notice>
+
 ### `fallbackStrategy{:.key}`
 
 default: `'bestFit'{:js}`
@@ -538,6 +531,63 @@ const {placement} = useFloating(reference, floating, {
 
 </ShowFor>
 
+## Combining with `shift(){:js}`
+
+If you're allowing fallback to the opposite axis of the preferred
+placement via `fallbackAxisSideDirection{:.key}` or
+`fallbackPlacements{:.key}`, then you may want to determine what
+behavior you want when combining `flip(){:js}` with
+`shift(){:js}`.
+
+If you want to ensure the placement side is preserved as best as
+possible without flipping, then you have two options to consider:
+
+1. Disabling the cross axis check in `flip(){:js}` places top
+   priority on `shift(){:js}` to do its work, with `flip(){:js}`
+   only taking action when absolutely necessary. The preferred
+   placement of the floating element will be conserved as much as
+   possible.
+
+```js {4}
+const middleware = [
+  flip({
+    fallbackAxisSideDirection: 'start',
+    crossAxis: false,
+  }),
+  shift(),
+];
+```
+
+2. Placing `shift(){:js}` _before_ `flip(){:js}` in the array
+   ensures it can do its work before `flip(){:js}` tries to
+   change the placement. This is similar to the first technique
+   above, but allows `flip(){:js}` to take action on its
+   `crossAxis{:.key}` too -- useful if `shift(){:js}` has a
+   limiter.
+
+```js {3}
+const middleware = [
+  shift({
+    limiter: limitShift(),
+  }),
+  flip({
+    fallbackAxisSideDirection: 'start',
+  }),
+];
+```
+
+<Notice>
+
+The second method is only recommended if your placement is not
+edge aligned, e.g. `'top'{:js}` instead of `'top-start'{:js}`.
+This is because alignment flipping will no longer be possible
+since `shift` takes over first.
+
+For reusable/generic components, you can use basic conditional
+checks on the supplied preferred placement to alter the ordering.
+
+</Notice>
+
 ## Conflict with `autoPlacement(){:js}`
 
 `flip(){:js}` and `autoPlacement(){:js}` cannot be used together

website/pages/docs/middleware.mdx

@@ -3,7 +3,7 @@
 # Middleware
 
 Objects that change the positioning of the floating element,
-executed in order as a stack.
+executed in order as a queue.
 
 </PageCard>