docs: update

website/pages/docs/FloatingFocusManager.mdx

@@ -268,3 +268,21 @@ The order in which focus cycles.
   {/* floating element */}
 </FloatingFocusManager>
 ```
+
+## Troubleshooting
+
+### Page scrolls to top when opening the floating element
+
+This can happen if you're placing the `autoFocus{:.keyword}` prop
+on an element inside the floating element. This is because the
+floating element is initially rendered at the top-left of the
+page, and the browser scrolls to it when it receives focus.
+
+Instead, use the `initialFocus{:.keyword}` prop on
+`<FloatingFocusManager>{:js}` to focus the desired element, which
+waits for the position to be ready first.
+
+### Usage with `<FloatingPortal>{:js}`
+
+Ensure the focus manager is rendered as a child (can be a nested
+descendant) of `<FloatingPortal>{:js}`.

website/pages/docs/FloatingOverlay.mdx

@@ -21,15 +21,15 @@ floating element, in addition to locking the body scroll.
 
 ## Usage
 
-It renders a `<div>{:js}` with base styling. Can be styled with
-any CSS solution.
+It renders a `<div>{:js}` with base styling.
 
 ```js
 function App() {
   return (
-    <FloatingOverlay>
-      <div />
-    </FloatingOverlay>
+    <>
+      <FloatingOverlay />
+      <div>Floating element</div>
+    </>
   );
 }
 ```
@@ -61,3 +61,23 @@ If you need a more advanced solution,
 is a great option.
 
 </Notice>
+
+## Troubleshooting
+
+### Sibling Overlay
+
+When using anchor positioning and the overlay in scrollable
+contexts, prefer making the overlay a sibling of the floating
+element rather than a parent container.
+
+This will ensure the floating element does not get contained by
+the overlay, allowing it to be positioned out of its bounds,
+preventing scroll issues. It also allows the overlay to be
+independently animated.
+
+```js
+<>
+  <FloatingOverlay />
+  <div ref={refs.setFloating} />
+</>
+```

website/pages/docs/FloatingPortal.mdx

@@ -24,13 +24,15 @@ tree.
 
 ```js
 function Tooltip() {
-  return (
-    isOpen && (
+  if (isOpen) {
+    return (
       <FloatingPortal>
         <div>Floating element</div>
       </FloatingPortal>
-    )
-  );
+    );
+  }
+
+  return null;
 }
 ```
 
@@ -40,8 +42,8 @@ appended to their respective parent.
 <Notice>
   The portal component should be conditionally rendered based on
   the `isOpen` or mounted state (as seen above), rather than
-  always rendered. This allows React Suspense to work as
-  expected.
+  always rendered. This prevents a portal container from being
+  mounted to the DOM when not in use.
 </Notice>
 
 ## Props

website/pages/docs/autoUpdate.mdx

@@ -89,7 +89,7 @@ cleaning up `autoUpdate` based on the presence of the reference
 and floating element.
 
 Alternatively, if you've hidden the floating element with CSS
-(based on an `isOpen` state), use an effect to handle it instead:
+(based on an `isOpen` state), use an Effect to handle it instead:
 
 ```js {18}
 const [isOpen, setIsOpen] = useState(false);

website/pages/docs/computePosition.mdx

@@ -145,6 +145,15 @@ positioned.
 Certain CSS styles must be applied **before**
 `computePosition(){:js}` is called:
 
+```css {2-5}
+#floating {
+  position: absolute;
+  width: max-content;
+  top: 0;
+  left: 0;
+}
+```
+
 - `position: absolute{:sass}`
 
 This makes the element float on top of the UI with intrinsic

website/pages/docs/popover.mdx

@@ -60,12 +60,12 @@ function Popover() {
 currently open on the screen. It is used for conditional
 rendering.
 
-### useFloating hook
+### useFloating Hook
 
-The `useFloating(){:js}` hook provides positioning and context
+The `useFloating(){:js}` Hook provides positioning and context
 for our popover. We need to pass it some information:
 
-- `open{:.key}`: The open state from our `useState(){:js}` hook
+- `open{:.key}`: The open state from our `useState(){:js}` Hook
   above.
 - `onOpenChange{:.key}`: A callback function that will be called
   when the popover is opened or closed. We'll use this to update
@@ -153,7 +153,7 @@ prop getters which can be used for rendering.
 
 ### Rendering
 
-Now we have all the variables and hooks set up, we can render out
+Now we have all the variables and Hooks set up, we can render out
 our elements.
 
 ```js
@@ -238,7 +238,7 @@ like so:
 
 It is better to create a reusable component API that can be used
 in a variety of different scenarios more easily. We can place all
-of our Hooks into a single custom hook for better reusability,
+of our Hooks into a single custom Hook for better reusability,
 which is then used by a controller component which encapsulates
 the state.
 

website/pages/docs/react-native.mdx

@@ -110,7 +110,7 @@ function App() {
 `useFloating(){:js}` only calculates the position **once** on
 render, or when the reference/floating elements changed.
 Depending on the context in which the floating element lives, you
-may need to update its position in an effect.
+may need to update its position in an Effect.
 
 The Hook returns an `update(){:js}` function to update the
 position at will:
@@ -126,7 +126,7 @@ To access the elements, you can either access the refs:
 ```js
 const {refs} = useFloating();
 
-// Inside an effect or event handler:
+// Inside an Effect or event handler:
 refs.reference.current;
 refs.floating.current;
 ```

website/pages/docs/react.mdx

@@ -4,8 +4,8 @@ import {ReactSelect} from '../../lib/components/PackageSelect';
 
 # React
 
-A toolkit to position and create interactions for floating
-elements with React.
+A React toolkit to position floating elements and optionally
+create interactions for them.
 
 ```bash
 npm install @floating-ui/react
@@ -24,12 +24,14 @@ Choose the package you installed for better docs:
 
 </PageCard>
 
-The goal of this package is to provide primitives to create
-components for tooltips, popovers, dropdown menus, hover cards,
-modal dialogs, select menus, comboboxes, and more. Instead of
-providing any pre-built components, it gives you the tools to
-create them more easily. This is ideal if you want lots of
-control, but does require more work to get started. The full
+The goal of this package is to provide primitives — features
+common to all types of floating elements — to create components
+for tooltips, popovers, dropdown menus, hover cards, modal
+dialogs, select menus, comboboxes, and more.
+
+Instead of providing any pre-built components, it gives you the
+tools to create them more easily. This is ideal if you want lots
+of control, but does require more work to get started. The full
 guides in [React Examples](/docs/react-examples) contain some
 copy-pasteable examples to get you started more quickly.
 
@@ -40,12 +42,12 @@ Floating UI's usage can be broken down into two disparate parts:
 - [Positioning](/docs/react#positioning) (available for both
   `@floating-ui/react{:.string}` and
   `@floating-ui/react-dom{:.string}`).
-- [Interactions](/docs/react#interactions) (available for just
+- [Interactions](/docs/react#interactions) (available for only
   `@floating-ui/react{:.string}`).
 
 ## Positioning
 
-`useFloating(){:js}` is the main hook of each package.
+`useFloating(){:js}` is the main Hook of each package.
 
 <ShowFor packages={['react']}>
 
@@ -83,17 +85,17 @@ function App() {
 This will position the floating `Tooltip` element at the **bottom
 center** of the `Button` element by default.
 
-- `refs.setReference{:js}` is the reference (or anchor) element
+- `refs.setReference{:js}` sets the reference (or anchor) element
   that is being referred to for positioning.
-- `refs.setFloating{:js}` is the floating element that is being
+- `refs.setFloating{:js}` sets the floating element that is being
   positioned relative to the reference element.
 - `floatingStyles{:js}` is an object of positioning styles to
   apply to the floating element's `style{:.keyword}` prop.
 
-The refs are functions to make them **reactive** — this ensures
-changes to the reference or floating elements, such as with
-conditional rendering, are handled correctly by updating the
-position.
+The refs are callback refs (functions) to make them **reactive**
+— this ensures changes to the reference or floating elements,
+such as with conditional rendering, are handled correctly by
+updating the position.
 
 ## Anchoring
 
@@ -126,7 +128,7 @@ const {refs, floatingStyles} = useFloating({
 
 <Notice type="warning">
   Only use this option if your floating element is _conditionally
-  rendered_, not hidden with CSS. Use an effect to call and clean
+  rendered_, not hidden with CSS. Use an Effect to call and clean
   up `autoUpdate` in the latter scenario.
 </Notice>
 

website/pages/docs/tooltip.mdx

@@ -61,12 +61,12 @@ function Tooltip() {
 currently open on the screen. It is used for conditional
 rendering.
 
-### useFloating hook
+### useFloating Hook
 
-The `useFloating(){:js}` hook provides positioning and context
+The `useFloating(){:js}` Hook provides positioning and context
 for our tooltip. We need to pass it some information:
 
-- `open{:.key}`: The open state from our `useState(){:js}` hook
+- `open{:.key}`: The open state from our `useState(){:js}` Hook
   above.
 - `onOpenChange{:.key}`: A callback function that will be called
   when the tooltip is opened or closed. We'll use this to update
@@ -166,7 +166,7 @@ prop getters which can be used for rendering.
 
 ### Rendering
 
-Now we have all the variables and hooks set up, we can render out
+Now we have all the variables and Hooks set up, we can render out
 our elements.
 
 ```js
@@ -203,7 +203,7 @@ function Tooltip() {
 
 It is better to create a reusable component API that can be used
 in a variety of different scenarios more easily. We can place all
-of our hooks into a single custom hook for better reusability,
+of our Hooks into a single custom Hook for better reusability,
 which is then used by a controller component which encapsulates
 the state.