@base-ui/react 1.6.0 → 1.7.0

package/docs/react/components/preview-card.md

@@ -25,7 +25,7 @@ import { PreviewCard } from '@base-ui/react/preview-card';
 export default function ExamplePreviewCard() {
   return (
     <PreviewCard.Root>
-      <p className="m-0 text-base text-neutral-950 text-balance dark:text-white">
+      <p className="text-base text-neutral-950 text-balance dark:text-white">
         The principles of good{' '}
         <PreviewCard.Trigger
           className="text-neutral-950 underline decoration-neutral-950/60 decoration-1 underline-offset-2 outline-0 hover:decoration-neutral-950 data-popup-open:decoration-neutral-950 focus-visible:no-underline focus-visible:outline-2 focus-visible:outline-neutral-950 dark:text-white dark:decoration-white/60 dark:hover:decoration-white dark:data-popup-open:decoration-white dark:focus-visible:outline-white"
@@ -48,7 +48,7 @@ export default function ExamplePreviewCard() {
                 src="https://images.unsplash.com/photo-1619615391095-dfa29e1672ef?q=80&w=448&h=300"
                 alt="Station Hofplein signage in Rotterdam, Netherlands"
               />
-              <p className="m-0 text-sm text-pretty">
+              <p className="text-sm">
                 <strong>Typography</strong> is the art and science of arranging type to make written
                 language clear, visually appealing, and effective in communication.
               </p>
@@ -209,7 +209,6 @@ export default function ExamplePreviewCard() {
   margin: 0;
   font-size: 0.875rem;
   line-height: 1.25rem;
-  text-wrap: pretty;
 }
 
 .Container {
@@ -370,6 +369,9 @@ For simple, one-off interactions, place the `<PreviewCard.Trigger>` inside `<Pre
 However, if defining the preview card's content next to its trigger is not practical, you can use a detached trigger.
 This involves placing the `<PreviewCard.Trigger>` outside of `<PreviewCard.Root>` and linking them with a `handle` created by the `PreviewCard.createHandle()` function.
 
+The imperative methods on the handle, such as `open()` and `close()`, require a `<PreviewCard.Root>` using the same handle to be mounted.
+Calls made while no root is attached to the handle — before one mounts, or after it unmounts — are ignored. Each time a root mounts, it starts from fresh state: a call made while no root was attached is not replayed, and no open state carries over from a previous mount.
+
 ```jsx title="Detached triggers"
 const demoPreviewCard = PreviewCard.createHandle();
 
@@ -402,7 +404,7 @@ const demoPreviewCard = PreviewCard.createHandle();
 export default function PreviewCardDetachedTriggersSimpleDemo() {
   return (
     <div>
-      <p className="m-0 text-base text-neutral-950 text-balance dark:text-white">
+      <p className="text-base text-neutral-950 text-balance dark:text-white">
         The principles of good{' '}
         <PreviewCard.Trigger
           className="text-neutral-950 underline decoration-neutral-950/60 decoration-1 underline-offset-2 outline-0 hover:decoration-neutral-950 data-popup-open:decoration-neutral-950 focus-visible:no-underline focus-visible:outline-2 focus-visible:outline-neutral-950 dark:text-white dark:decoration-white/60 dark:hover:decoration-white dark:data-popup-open:decoration-white dark:focus-visible:outline-white"
@@ -427,7 +429,7 @@ export default function PreviewCardDetachedTriggersSimpleDemo() {
                   src="https://images.unsplash.com/photo-1619615391095-dfa29e1672ef?q=80&w=448&h=300"
                   alt="Station Hofplein signage in Rotterdam, Netherlands"
                 />
-                <p className="m-0 text-sm text-pretty">
+                <p className="text-sm">
                   <strong>Typography</strong> is the art and science of arranging type to make
                   written language clear, visually appealing, and effective in communication.
                 </p>
@@ -595,7 +597,6 @@ export default function PreviewCardDetachedTriggersSimpleDemo() {
   margin: 0;
   font-size: 0.875rem;
   line-height: 1.25rem;
-  text-wrap: pretty;
 }
 
 .Container {
@@ -821,7 +822,7 @@ const cardContents = {
         src="https://images.unsplash.com/photo-1619615391095-dfa29e1672ef?q=80&w=448&h=300"
         alt="Station Hofplein signage in Rotterdam, Netherlands"
       />
-      <p className="m-0 text-sm text-pretty">
+      <p className="text-sm">
         <strong>Typography</strong> is the art and science of arranging type.
       </p>
     </div>
@@ -835,7 +836,7 @@ const cardContents = {
         src="https://upload.wikimedia.org/wikipedia/commons/thumb/b/b7/Braun_ABW30_%28schwarz%29.jpg/250px-Braun_ABW30_%28schwarz%29.jpg"
         alt="Braun ABW30"
       />
-      <p className="m-0 text-sm text-pretty">
+      <p className="text-sm">
         A <strong>design</strong> is the concept or proposal for an object, process, or system.
       </p>
     </div>
@@ -849,7 +850,7 @@ const cardContents = {
         src="https://upload.wikimedia.org/wikipedia/commons/thumb/5/5f/MonaLisa_sfumato.jpeg/250px-MonaLisa_sfumato.jpeg"
         alt="Mona Lisa"
       />
-      <p className="m-0 text-sm text-pretty">
+      <p className="text-sm">
         <strong>Art</strong> is a diverse range of cultural activity centered around works utilizing
         creative or imaginative talents, which are expected to evoke a worthwhile experience,
         generally through an expression of emotional power, conceptual ideas, technical proficiency,
@@ -871,7 +872,7 @@ export default function PreviewCardDetachedTriggersControlledDemo() {
   return (
     <div>
       <div className="flex flex-wrap items-baseline justify-center gap-2">
-        <p className="m-0 text-base text-neutral-950 text-balance dark:text-white">
+        <p className="text-base text-neutral-950 text-balance dark:text-white">
           Discover{' '}
           <PreviewCard.Trigger
             className="text-neutral-950 underline decoration-neutral-950/60 decoration-1 underline-offset-2 outline-0 hover:decoration-neutral-950 data-popup-open:decoration-neutral-950 focus-visible:no-underline focus-visible:outline-2 focus-visible:outline-neutral-950 dark:text-white dark:decoration-white/60 dark:hover:decoration-white dark:data-popup-open:decoration-white dark:focus-visible:outline-white"
@@ -1181,7 +1182,6 @@ export default function PreviewCardDetachedTriggersControlledDemo() {
   margin: 0;
   font-size: 0.875rem;
   line-height: 1.25rem;
-  text-wrap: pretty;
 }
 
 .Container {
@@ -1324,7 +1324,7 @@ This is useful when different triggers display different content within the same
 
 To enable content animations, wrap the content in the `<PreviewCard.Viewport>` part.
 This part provides features to create direction-aware animations.
-It renders a `div` with a `data-activation-direction` attribute (`left`, `right`, `up`, or `down`) that indicates the new trigger's position relative to the previous one.
+It renders a `div` with a `data-activation-direction` attribute that indicates the new trigger's position relative to the previous one. The value is a space-separated set of up to two tokens (one per axis) — `left` or `right` for the horizontal axis and `up` or `down` for the vertical axis (for example, `right down`). Match a single token with the `~=` attribute selector, such as `[data-activation-direction~='right']`.
 
 Inside the `<PreviewCard.Viewport>`, the content is further wrapped in `div`s with data attributes to help with styling:
 
@@ -1357,7 +1357,7 @@ const cardContents = {
         src="https://images.unsplash.com/photo-1619615391095-dfa29e1672ef?q=80&w=448&h=300"
         alt="Station Hofplein signage in Rotterdam, Netherlands"
       />
-      <p className="m-0 text-sm text-pretty">
+      <p className="text-sm">
         <strong>Typography</strong> is the art and science of arranging type.
       </p>
     </div>
@@ -1371,7 +1371,7 @@ const cardContents = {
         src="https://upload.wikimedia.org/wikipedia/commons/thumb/b/b7/Braun_ABW30_%28schwarz%29.jpg/250px-Braun_ABW30_%28schwarz%29.jpg"
         alt="Braun ABW30"
       />
-      <p className="m-0 text-sm text-pretty">
+      <p className="text-sm">
         A <strong>design</strong> is the concept or proposal for an object, process, or system.
       </p>
     </div>
@@ -1385,7 +1385,7 @@ const cardContents = {
         src="https://upload.wikimedia.org/wikipedia/commons/thumb/5/5f/MonaLisa_sfumato.jpeg/250px-MonaLisa_sfumato.jpeg"
         alt="Mona Lisa"
       />
-      <p className="m-0 text-sm text-pretty">
+      <p className="text-sm">
         <strong>Art</strong> is a diverse range of cultural activity centered around works utilizing
         creative or imaginative talents, which are expected to evoke a worthwhile experience,
         generally through an expression of emotional power, conceptual ideas, technical proficiency,
@@ -1398,7 +1398,7 @@ const cardContents = {
 export default function PreviewCardDetachedTriggersFullDemo() {
   return (
     <div>
-      <p className="m-0 text-base text-neutral-950 text-balance dark:text-white">
+      <p className="text-base text-neutral-950 text-balance dark:text-white">
         Discover{' '}
         <PreviewCard.Trigger
           className="text-neutral-950 underline decoration-neutral-950/60 decoration-1 underline-offset-2 outline-0 hover:decoration-neutral-950 data-popup-open:decoration-neutral-950 focus-visible:no-underline focus-visible:outline-2 focus-visible:outline-neutral-950 dark:text-white dark:decoration-white/60 dark:hover:decoration-white dark:data-popup-open:decoration-white dark:focus-visible:outline-white"
@@ -1608,7 +1608,6 @@ This example shows how to implement the component using CSS Modules.
   margin: 0;
   font-size: 0.875rem;
   line-height: 1.25rem;
-  text-wrap: pretty;
 }
 
 .Paragraph {
@@ -1856,15 +1855,15 @@ Renders an `<a>` element.
 
 **Trigger Props:**
 
-| Prop       | Type                                                                                              | Default | Description                                                                                                                                                                                   |
-| :--------- | :------------------------------------------------------------------------------------------------ | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| handle     | `PreviewCard.Handle<Payload>`                                                                     | -       | A handle to associate the trigger with a preview card.                                                                                                                                        |
-| payload    | `Payload`                                                                                         | -       | A payload to pass to the preview card when it is opened.                                                                                                                                      |
-| delay      | `number`                                                                                          | `600`   | How long to wait before the preview card opens. Specified in milliseconds.                                                                                                                    |
-| closeDelay | `number`                                                                                          | `300`   | How long to wait before closing the preview card. Specified in milliseconds.                                                                                                                  |
-| className  | `string \| ((state: PreviewCard.Trigger.State) => string \| undefined)`                           | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                      |
-| style      | `React.CSSProperties \| ((state: PreviewCard.Trigger.State) => React.CSSProperties \| undefined)` | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                   |
-| render     | `ReactElement \| ((props: HTMLProps, state: PreviewCard.Trigger.State) => ReactElement)`          | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
+| Prop       | Type                                                                                                                                                                     | Default | Description                                                                                                                                                                                   |
+| :--------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| handle     | `PreviewCard.Handle<Payload>`                                                                                                                                            | -       | A handle to associate the trigger with a preview card.                                                                                                                                        |
+| payload    | `Payload`                                                                                                                                                                | -       | A payload to pass to the preview card when it is opened.                                                                                                                                      |
+| delay      | `number`                                                                                                                                                                 | `600`   | How long to wait before the preview card opens. Specified in milliseconds.                                                                                                                    |
+| closeDelay | `number`                                                                                                                                                                 | `300`   | How long to wait before closing the preview card. Specified in milliseconds.                                                                                                                  |
+| className  | `string \| ((state: PreviewCard.Trigger.State) => string \| undefined)`                                                                                                  | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                      |
+| style      | `React.CSSProperties \| ((state: PreviewCard.Trigger.State) => React.CSSProperties \| undefined)`                                                                        | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                   |
+| render     | `ReactElement \| ((props: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, state: PreviewCard.Trigger.State) => ReactElement)` | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
 
 **Trigger Data Attributes:**
 
@@ -1913,7 +1912,7 @@ type PreviewCardPortalState = {};
 
 ### Backdrop
 
-An overlay displayed beneath the popup.
+A presentational overlay displayed beneath the popup.
 Renders a `<div>` element.
 
 **Backdrop Props:**
@@ -1926,12 +1925,12 @@ Renders a `<div>` element.
 
 **Backdrop Data Attributes:**
 
-| Attribute           | Type | Description                                     |
-| :------------------ | :--- | :---------------------------------------------- |
-| data-open           | -    | Present when the preview card is open.          |
-| data-closed         | -    | Present when the preview card is closed.        |
-| data-starting-style | -    | Present when the preview card is animating in.  |
-| data-ending-style   | -    | Present when the preview card is animating out. |
+| Attribute           | Type | Description                                        |
+| :------------------ | :--- | :------------------------------------------------- |
+| data-open           | -    | Present when the preview card is open.             |
+| data-closed         | -    | Present when the preview card is closed.           |
+| data-starting-style | -    | Present when the preview card begins animating in. |
+| data-ending-style   | -    | Present when the preview card is animating out.    |
 
 ### Backdrop.Props
 
@@ -2017,13 +2016,15 @@ Renders a `<div>` element.
 
 **Positioner CSS Variables:**
 
-| Variable             | Type     | Description                                                                            |
-| :------------------- | :------- | :------------------------------------------------------------------------------------- |
-| `--anchor-height`    | `number` | The anchor's height.                                                                   |
-| `--anchor-width`     | `number` | The anchor's width.                                                                    |
-| `--available-height` | `number` | The available height between the trigger and the edge of the viewport.                 |
-| `--available-width`  | `number` | The available width between the trigger and the edge of the viewport.                  |
-| `--transform-origin` | `string` | The coordinates that this element is anchored to. Used for animations and transitions. |
+| Variable              | Type     | Description                                                                                                                            |
+| :-------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------- |
+| `--anchor-height`     | `number` | The anchor's height.                                                                                                                   |
+| `--anchor-width`      | `number` | The anchor's width.                                                                                                                    |
+| `--available-height`  | `number` | The available height between the trigger and the edge of the viewport.                                                                 |
+| `--available-width`   | `number` | The available width between the trigger and the edge of the viewport.                                                                  |
+| `--positioner-height` | `number` | The height of the preview card's positioner.&#xA;It is important to set `height` to this value when using CSS to animate size changes. |
+| `--positioner-width`  | `number` | The width of the preview card's positioner.&#xA;It is important to set `width` to this value when using CSS to animate size changes.   |
+| `--transform-origin`  | `string` | The coordinates that this element is anchored to. Used for animations and transitions.                                                 |
 
 ### Positioner.Props
 
@@ -2067,7 +2068,7 @@ Renders a `<div>` element.
 | data-closed         | -                                                                          | Present when the preview card is closed.                              |
 | data-align          | `'start' \| 'center' \| 'end'`                                             | Indicates how the popup is aligned relative to specified side.        |
 | data-side           | `'top' \| 'bottom' \| 'left' \| 'right' \| 'inline-end' \| 'inline-start'` | Indicates which side the popup is positioned relative to the trigger. |
-| data-starting-style | -                                                                          | Present when the preview card is animating in.                        |
+| data-starting-style | -                                                                          | Present when the preview card begins animating in.                    |
 | data-ending-style   | -                                                                          | Present when the preview card is animating out.                       |
 
 ### Popup.Props
@@ -2195,13 +2196,18 @@ type ReturnValue = PreviewCard.Handle<Payload>;
 
 ### Handle
 
-A handle to control a preview card imperatively and to associate detached triggers with it.
+Controls a PreviewCard imperatively and associates detached `PreviewCard.Trigger` components with
+a `PreviewCard.Root`. Create one with `PreviewCard.createHandle()` and pass it to the `handle`
+prop of the root and of any triggers rendered outside of it.
+
+The imperative methods take effect only while a root using this handle is mounted; calls made
+before a root attaches (or after it unmounts) are ignored.
 
 **Properties:**
 
-| Property | Type      | Modifiers | Description                                           |
-| :------- | :-------- | :-------- | :---------------------------------------------------- |
-| isOpen   | `boolean` | readonly  | Indicates whether the preview card is currently open. |
+| Property | Type      | Modifiers | Description                                                                                          |
+| :------- | :-------- | :-------- | :--------------------------------------------------------------------------------------------------- |
+| isOpen   | `boolean` | readonly  | Whether the preview card is currently open. Returns `false` while no root is attached to the handle. |
 
 **Methods:**
 
@@ -2209,8 +2215,7 @@ A handle to control a preview card imperatively and to associate detached trigge
 function open(triggerId: string): void;
 ```
 
-Opens the preview card and associates it with the trigger with the given ID.
-The trigger must be a PreviewCard.Trigger component with this handle passed as a prop.
+Opens the preview card and associates it with the trigger with the given id.
 
 This method should only be called in an event handler or an effect (not during rendering).
 
@@ -2220,6 +2225,8 @@ function close(): void;
 
 Closes the preview card.
 
+This method should only be called in an event handler or an effect (not during rendering).
+
 ## External Types
 
 ### PayloadChildRenderFunction
@@ -2295,6 +2302,8 @@ Maps `Canonical`: `Alias` — Use Canonical when its namespace is already import
 - `PreviewCard.Viewport.Props`: `PreviewCardViewportProps`
 - `PreviewCard.Viewport.State`: `PreviewCardViewportState`
 
+The `Viewport` is optional — reach for it only when a single popup is opened by multiple triggers, its content differs per trigger, and the switch between them is animated. When used, set `width: var(--positioner-width)` and `height: var(--positioner-height)` on the `Positioner` so its box is frozen to the measured size during the transition; otherwise content-driven resizing can make the popup thrash or flip to another side.
+
 ## createHandle
 
 [//]: # '@exclude-table-of-contents'

package/docs/react/components/progress.md

@@ -163,9 +163,9 @@ Renders a `<div>` element.
 
 | Prop             | Type                                                                                        | Default | Description                                                                                                                                                                                   |
 | :--------------- | :------------------------------------------------------------------------------------------ | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| value\*          | `number \| null`                                                                            | `null`  | The current value. The component is indeterminate when value is `null`.                                                                                                                       |
+| value\*          | `number \| null`                                                                            | -       | The current value. The component is indeterminate when value is `null`.                                                                                                                       |
 | aria-valuetext   | `string`                                                                                    | -       | A string value that provides a user-friendly name for `aria-valuenow`, the current value of the progress bar.                                                                                 |
-| getAriaValueText | `((formattedValue: string \| null, value: number \| null) => string)`                       | -       | Accepts a function which returns a string value that provides a human-readable text alternative for the current value of the progress bar.                                                    |
+| getAriaValueText | `((formattedValue: string, value: number \| null) => string)`                               | -       | Accepts a function which returns a string value that provides a human-readable text alternative for the current value of the progress bar.                                                    |
 | locale           | `Intl.LocalesArgument`                                                                      | -       | The locale used by `Intl.NumberFormat` when formatting the value.&#xA;Defaults to the user's runtime locale.                                                                                  |
 | min              | `number`                                                                                    | `0`     | The minimum value.                                                                                                                                                                            |
 | max              | `number`                                                                                    | `100`   | The maximum value.                                                                                                                                                                            |
@@ -197,7 +197,7 @@ type ProgressRootState = {
 
 ### Value
 
-A text label displaying the current value.
+A text element displaying the current value.
 Renders a `<span>` element.
 
 **Value Props:**

package/docs/react/components/radio.md

@@ -500,7 +500,7 @@ Renders a `<span>` element.
 | data-touched        | -    | Present when the radio has been touched (when wrapped in Field.Root).       |
 | data-filled         | -    | Present when the radio is checked (when wrapped in Field.Root).             |
 | data-focused        | -    | Present when the radio is focused (when wrapped in Field.Root).             |
-| data-starting-style | -    | Present when the radio indicator is animating in.                           |
+| data-starting-style | -    | Present when the radio indicator begins animating in.                       |
 | data-ending-style   | -    | Present when the radio indicator is animating out.                          |
 
 ### Indicator.Props