@navecss/base-ui 0.1.0 → 0.3.0

package/README.md

@@ -4,9 +4,9 @@ NaveCSS styles Base UI's components with Nave's tokens: the same parts, the same
 
 This package is not affiliated with, endorsed by or sponsored by MUI or the Base UI project.
 
-`@base-ui/react` is a separately installed peer, built and maintained by its own maintainers; this package does not include it. You change `@base-ui/react/<component>` to `@navecss/base-ui/<component>` in your imports, add one stylesheet, and every part keeps Base UI's props, types, refs and behaviour while gaining Nave's styling. The styling is zero-runtime styling: static classes and one static stylesheet, with all behaviour still Base UI's.
+`@base-ui/react` is a separately installed peer, built and maintained by its own maintainers; this package does not include it. You change `@base-ui/react/<component>` to `@navecss/base-ui/<component>` in your imports, add one stylesheet, and every part keeps Base UI's props, refs and behaviour while gaining Nave's styling. The styling is zero-runtime styling: static classes and one static stylesheet, with all behaviour still Base UI's.
 
-On this page: [Install](#install) · [Use it](#use-it) · [The stylesheet](#the-stylesheet) · [Variants](#variants) · [Overriding](#overriding) · [What is styled](#what-is-styled) · [Things to know](#things-to-know) · [License](#license)
+On this page: [Install](#install) · [Use it](#use-it) · [The stylesheet](#the-stylesheet) · [Variants](#variants) · [Overriding](#overriding) · [Copy a component](#copy-a-component-into-your-project) · [What is styled](#what-is-styled) · [Feedback and navigation](#feedback-and-navigation) · [Things to know](#things-to-know) · [License](#license)
 
 ## Install
 
@@ -48,7 +48,9 @@ export default function RenameDialog() {
 }
 ```
 
-Every subpath of Base UI that this package wraps is listed under [What is styled](#what-is-styled). Each one also re-exports every type Base UI exports there, so type imports change the same way. The package root, `@navecss/base-ui`, re-exports the same components.
+Every subpath of Base UI that this package wraps is listed under [What is styled](#what-is-styled). Each one also re-exports every flat type name Base UI exports there, such as `DialogRootProps`, so those imports change the same way. Base UI's dotted type names, such as `Dialog.Root.Props`, come through as well, but not all of them: where one does not compile through this package, import Base UI's flat name for the same type from the same subpath. The end of [What is styled](#what-is-styled) names the ones left out by design. The package root, `@navecss/base-ui`, re-exports the same components.
+
+A Server Component can import a namespace such as `Dialog` from a subpath and render its parts, `Dialog.Root` among them, without a `'use client'` directive of its own.
 
 ## The stylesheet
 
@@ -60,7 +62,7 @@ Import Nave's tokens, then this package's stylesheet, before any stylesheet of y
 @import url('@navecss/base-ui/styles.css');
 ```
 
-Both files begin with Nave's `@layer` order statement, and the order holds only if that statement is the first `@layer` declaration your page sees. The stylesheet is already built: nothing in your build needs to know about Nave, so it takes no plugin and no directive. Every rule in it sits in `@layer components.nave`, it declares no custom property and sets no `z-index`.
+Both files begin with Nave's `@layer` order statement, and the order holds only if that statement is the first `@layer` declaration your page sees. The stylesheet is already built: nothing in your build needs to know about Nave, so it takes no plugin and no directive. Every rule in it sits in `@layer components.nave` and it declares no custom property. It sets one `z-index`, on the toast area, from `--nave-layer-toast`.
 
 Nave's colours need Chrome or Edge 125, Firefox 128 or Safari 18, and your CSS build has to target the same floor, or it rewrites the colours into a form that does not follow the page's colour scheme. In Vite:
 
@@ -76,12 +78,14 @@ Tokens are CSS custom properties. If you scope a token yourself, set it on the p
 
 The Button family takes two optional props.
 
-| Prop      | Values                     | Default       |
-| --------- | -------------------------- | ------------- |
-| `variant` | `'secondary'`, `'primary'` | `'secondary'` |
-| `size`    | `'md'`, `'sm'`             | `'md'`        |
+| Prop      | Values                                | Default       |
+| --------- | ------------------------------------- | ------------- |
+| `variant` | `'secondary'`, `'primary'`, `'ghost'` | `'secondary'` |
+| `size`    | `'md'`, `'sm'`                        | `'md'`        |
+
+They are accepted by `Button`, `Toolbar.Button`, and the trigger and close parts of Dialog, Alert Dialog and Popover, `Menu.Trigger` and `Tooltip.Trigger`. `ghost` is a button with no fill or border at rest that fills under the pointer and while the menu it opens is showing: it is the look of a Menubar's triggers. `Toggle` takes `size` only. Both are typed as those unions and neither reaches the DOM as a prop.
 
-They are accepted by `Button`, `Toolbar.Button`, and the trigger and close parts of Dialog and Popover, `Menu.Trigger` and `Tooltip.Trigger`. `Toggle` takes `size` only. Both are typed as those unions and neither reaches the DOM as a prop.
+`Toast.Action` and `Toast.Close` take both props too. `NavigationMenu.Trigger` has a quieter look of its own and takes neither. `Avatar.Root` takes a `size` of its own: `'sm'`, `'md'` (the default) or `'lg'`.
 
 ```tsx
 import { Button } from '@navecss/base-ui/button'
@@ -97,11 +101,12 @@ export default function SaveButton() {
 
 ## Overriding
 
-There are three steps, from the lightest:
+There are four steps, from the lightest:
 
 1. **Tokens.** Re-theme with Nave's tokens and every part follows. Nothing else is needed for a different palette, radius or spacing.
 2. **`className`.** Pass a class to any part, as a string or as Base UI's function of the part's state. Put its rules in `@layer components.consumer`: that layer comes after Nave's, so your class wins in every state, whatever the specificity of Nave's rule. It also means that restyling a property restyles it in every state: set `background-color` on a Button and your colour replaces the `primary` variant's hover and active colours and a disabled button's too, so write the states you want yourself.
-3. **The raw Base UI part.** Import the part from `@base-ui/react/<component>` and style it from scratch. It mixes freely with wrapped parts.
+3. **A copy of the component.** To change Nave's rules for a component rather than override them, copy its files into your project with shadcn's CLI and change the copy: see [Copy a component into your project](#copy-a-component-into-your-project).
+4. **The raw Base UI part.** Import the part from `@base-ui/react/<component>` and style it from scratch. It mixes freely with wrapped parts.
 
 ```css
 /* menu.module.css */
@@ -134,15 +139,292 @@ export default function ActionsMenu() {
 
 Behaviour is Base UI's. Parts Nave does not style, such as `Portal`, `Positioner`, `Provider` and `Form`, are Base UI's own parts, passed through unchanged.
 
+## Copy a component into your project
+
+Every component this package styles is also in Nave's shadcn registry: one command copies the component's files into your project, and you then change its rules in the copy instead of overriding them.
+
+With `@navecss/base-ui` installed, add a component from the files of the version you have:
+
+```bash
+npx shadcn@latest add ./node_modules/@navecss/base-ui/dist/registry/base-ui-dialog.json
+```
+
+Replace `dialog` with the subpath of the component you want, from [What is styled](#what-is-styled), and list several paths to add several components. The copy then comes from the same release as the components you still import from the package, with no version to type: `add` reads the files it copies from `node_modules` instead of downloading them. The command needs no Tailwind, no `components.json` and no `shadcn init`: every file in the registry says where it goes, so `add` installs it into a project that has none of them. Run `add` for Nave's components alone, with no item from another registry in the same command: shadcn's CLI decides from the first item it is given whether the project needs that setup.
+
+The registry is also served at an exact version of `@navecss/base-ui`. Use that address in a project without the package installed, or with Yarn Plug'n'Play, which has no `node_modules`:
+
+```bash
+npx shadcn@latest add https://cdn.jsdelivr.net/npm/@navecss/base-ui@<version>/dist/registry/base-ui-dialog.json
+```
+
+Replace `<version>` with the version of `@navecss/base-ui` your project has, if it has one (`npm ls @navecss/base-ui` or `pnpm list @navecss/base-ui` prints it), so the copy matches the components you still import from the package; if not, use the latest version.
+
+For shadcn's MCP server, which agents use, and for `shadcn search`, map the `@navecss` namespace to that address once. shadcn's CLI writes the mapping into your `package.json`, under `registries`, with the version in the address, so change the version there when you upgrade:
+
+```bash
+npx shadcn@latest registry add '@navecss=https://cdn.jsdelivr.net/npm/@navecss/base-ui@<version>/dist/registry/{name}.json'
+npx shadcn@latest add @navecss/base-ui-dialog
+```
+
+`add` writes the files to `components/nave/`, or to `src/components/nave/` in a project with a `src` folder; `--path <folder>` writes them to that folder instead. For Dialog, in the order `add` writes them:
+
+- `nave-dialog.ts`, the module you import;
+- `nave-dialog.parts.ts`, its parts;
+- `nave-dialog.wrap.ts`, the code that adds the classes to those parts;
+- `nave-dialog.module.css`, the rules for those parts;
+- `NAVECSS-LICENSE`.
+
+Then import the component from the copy instead of from the package, with a path relative to the importing file, for example `import { Dialog } from './components/nave/nave-dialog'`. The copy's parts take the same props as the package's, `variant` and `size` included.
+
+The copied rules read Nave's tokens, so keep `@navecss/tokens/css` imported as [The stylesheet](#the-stylesheet) shows. The copy imports neither `@navecss/base-ui` nor its `styles.css`: keep those while you still import any component from the package; a copy and the package's components work side by side. The first rule of each `.module.css` is Nave's `@layer` order statement, as in `styles.css`, and your build has to support CSS Modules, as Vite and Next.js do without setup. A change to one copy reaches no other copy and no component from the package.
+
+A component added this way keeps its rules in `@layer components.consumer`, the layer your classes use, so a class you pass to one of its parts no longer wins in every state as it does on the package's components: the copied rules for hover, focus, disabled and the other states are more specific than one class, and still apply. A change to those states takes effect in the copied rules.
+
+No later release of `@navecss/base-ui` changes the copied files. To take a later release's version of a component, upgrade the package and run `add` again, or use that release's address. `add` asks before it replaces a copied file whose content differs from the new one, whether you changed it or the release did, and `--overwrite` replaces them without asking. In a run with no terminal to answer, such as an agent or a CI job, it stops at the first such file and still exits with success, so that file and the ones after it stay as they were. The exit status does not show that it stopped, but the output does: it ends with the question about that file.
+
+The registry names no versions for the packages a copy depends on, so `add` leaves the versions in your `package.json` as they are, and installs the latest version of any that is missing. A copy needs `@base-ui/react` 1.3 or later in the 1.x line, `@navecss/tokens` 0.4.0 or later before 1.0, and React 18 or 19.
+
 ## What is styled
 
 | Group      | Subpaths                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Overlays   | `@navecss/base-ui/dialog`, `@navecss/base-ui/popover`, `@navecss/base-ui/menu`, `@navecss/base-ui/select`, `@navecss/base-ui/tooltip`                                                                                                                                                                                                                                                                                                        |
+| Overlays   | `@navecss/base-ui/dialog`, `@navecss/base-ui/popover`, `@navecss/base-ui/menu`, `@navecss/base-ui/select`, `@navecss/base-ui/tooltip`, `@navecss/base-ui/alert-dialog`, `@navecss/base-ui/context-menu`, `@navecss/base-ui/menubar`, `@navecss/base-ui/preview-card`, `@navecss/base-ui/combobox`, `@navecss/base-ui/autocomplete`                                                                                                           |
 | Disclosure | `@navecss/base-ui/accordion`, `@navecss/base-ui/collapsible`, `@navecss/base-ui/tabs`                                                                                                                                                                                                                                                                                                                                                        |
 | Controls   | `@navecss/base-ui/button`, `@navecss/base-ui/input`, `@navecss/base-ui/number-field`, `@navecss/base-ui/field`, `@navecss/base-ui/fieldset`, `@navecss/base-ui/form`, `@navecss/base-ui/checkbox`, `@navecss/base-ui/checkbox-group`, `@navecss/base-ui/radio`, `@navecss/base-ui/radio-group`, `@navecss/base-ui/switch`, `@navecss/base-ui/slider`, `@navecss/base-ui/toggle`, `@navecss/base-ui/toggle-group`, `@navecss/base-ui/toolbar` |
+| Feedback   | `@navecss/base-ui/toast`, `@navecss/base-ui/progress`, `@navecss/base-ui/meter`                                                                                                                                                                                                                                                                                                                                                              |
+| Navigation | `@navecss/base-ui/navigation-menu`, `@navecss/base-ui/scroll-area`                                                                                                                                                                                                                                                                                                                                                                           |
+| Display    | `@navecss/base-ui/avatar`, `@navecss/base-ui/separator`                                                                                                                                                                                                                                                                                                                                                                                      |
 
-Version 1 does not paint everything. It has no highlight on the hovered or arrowed item of a menu or select, no scrim colour behind a dialog (its backdrop has no paint, and this package recommends no value for one), no motion on popups, tooltips or the tab indicator, an arrow that sits on physical sides only (top, bottom, left and right, not the logical start and end), and no fill on a slider's range. Button comes in `secondary` and `primary`, in sizes `md` and `sm`, and no other. What it leaves out you can add with a class of your own, as above.
+What this package does not paint: no backdrop colour behind a Dialog, no fill on the Slider's range, and Button sizes `md` and `sm` only. Toasts form a plain list, not a stack of cards that fans out, and there is no motion when the Navigation Menu panel closes. It paints an Alert Dialog's backdrop as a scrim and recommends no other scrim value. What it leaves out you can add with a class of your own, as above.
+
+Menubar's menus come from `@navecss/base-ui/menu`: the same `Menu` as anywhere else, and the triggers take `variant="ghost"`.
+
+```tsx
+import { Menu } from '@navecss/base-ui/menu'
+import { Menubar } from '@navecss/base-ui/menubar'
+
+export default function AppMenubar() {
+  return (
+    <Menubar>
+      <Menu.Root>
+        <Menu.Trigger variant="ghost">File</Menu.Trigger>
+        <Menu.Portal>
+          <Menu.Positioner>
+            <Menu.Popup>
+              <Menu.Item>New</Menu.Item>
+            </Menu.Popup>
+          </Menu.Positioner>
+        </Menu.Portal>
+      </Menu.Root>
+      <Menu.Root>
+        <Menu.Trigger variant="ghost">Edit</Menu.Trigger>
+        <Menu.Portal>
+          <Menu.Positioner>
+            <Menu.Popup>
+              <Menu.Item>Undo</Menu.Item>
+            </Menu.Popup>
+          </Menu.Positioner>
+        </Menu.Portal>
+      </Menu.Root>
+    </Menubar>
+  )
+}
+```
+
+A Combobox puts its input inside an `InputGroup`:
+
+```tsx
+import { Combobox } from '@navecss/base-ui/combobox'
+
+export default function FruitCombobox() {
+  return (
+    <Combobox.Root items={['apple', 'banana']}>
+      <Combobox.InputGroup>
+        <Combobox.Input />
+        <Combobox.Trigger>
+          <Combobox.Icon />
+        </Combobox.Trigger>
+      </Combobox.InputGroup>
+      <Combobox.Portal>
+        <Combobox.Positioner>
+          <Combobox.Popup>
+            <Combobox.List>
+              {(item: string) => (
+                <Combobox.Item key={item} value={item}>
+                  {item}
+                </Combobox.Item>
+              )}
+            </Combobox.List>
+          </Combobox.Popup>
+        </Combobox.Positioner>
+      </Combobox.Portal>
+    </Combobox.Root>
+  )
+}
+```
+
+A right-to-left app needs both `dir="rtl"` on `<html>` (or on the element you pass as a Portal's `container`) and Base UI's `DirectionProvider`, imported from `@base-ui/react/direction-provider`, with the same direction. With only one of them, a popup that opens on the `inline-start` or `inline-end` side shows its arrow pointing away from what opened it.
+
+Context Menu's trigger area is your own element, and Nave paints nothing on it.
+
+Combobox's `createItems` is not exported here: Base UI added it in 1.8.0, and this package supports Base UI from 1.3. On 1.8.0 or later, import it from Base UI and pass what it returns to `items` on this package's `Combobox.Root`:
+
+```ts
+import { Combobox as BaseCombobox } from '@base-ui/react/combobox'
+
+const fruits = BaseCombobox.createItems(
+  [
+    { id: 1, name: 'Apple' },
+    { id: 2, name: 'Banana' },
+  ],
+  { getValue: (fruit) => fruit.id, getLabel: (fruit) => fruit.name },
+)
+```
+
+The types under a part, such as `Menu.Item.Props`, take their names and type parameters from Base UI 1.3, so nine that Base UI added up to 1.9.0 do not come through: `ContextMenu.Root.Actions`, the third type parameter of `Combobox.Root.Props` (`Item`), the type parameter of `NavigationMenu.Root.Props`, `NavigationMenu.Root.Value`, `OpenChangeEventDetails` under the roots of Select, Combobox and Autocomplete, and `Menu.Root.HighlightEventDetails` and `Menu.Root.HighlightEventReason`. Import `ContextMenuRootActions` from `@navecss/base-ui/context-menu`, `ComboboxRootProps<Value, Multiple, Item>` from `@navecss/base-ui/combobox`, `NavigationMenuRootProps<Value>` and `NavigationMenuRoot.Value<Value>` from `@navecss/base-ui/navigation-menu`, `SelectRootOpenChangeEventDetails`, `ComboboxRootOpenChangeEventDetails` and `AutocompleteRootOpenChangeEventDetails` from their own subpaths, and `MenuRootHighlightEventDetails` and `MenuRootHighlightEventReason` from `@navecss/base-ui/menu` instead.
+
+Two more things Base UI 1.9.0 added are not exported here, because this package supports Base UI from 1.3. The Menu's filtering parts (`Menu.FilterProvider`, `Menu.Input`, `Menu.List`, `Menu.Empty`, `Menu.Clear` and `Menu.useFilter`), which Base UI marks as a preview, are left out, and Nave does not style them; import them from `@base-ui/react/menu` if you use them. Their flat type names, such as `MenuInputProps` and `MenuFilter`, still come through. The objects that name each part's data attributes and CSS variables, such as `DialogPopupDataAttributes`, come through as types only: to read their values, import them from Base UI's subpath.
+
+## Feedback and navigation
+
+Toast, Navigation Menu, Scroll Area, Meter, Progress, Avatar and Separator are imported with the same prefix swap as the rest: `@navecss/base-ui/toast`, `@navecss/base-ui/navigation-menu`, `@navecss/base-ui/scroll-area`, `@navecss/base-ui/meter`, `@navecss/base-ui/progress`, `@navecss/base-ui/avatar` and `@navecss/base-ui/separator`. `Separator` is the separator the Toolbar already uses and needs nothing more.
+
+### Toast
+
+Toast needs one `Toast.Provider` around both the code that raises toasts and the place they appear, and you render the toasts yourself: map the `toasts` from `Toast.useToastManager()` to one `Toast.Root` each, inside `Toast.Viewport`, inside `Toast.Portal`. To raise a toast from outside React, create a manager with `Toast.createToastManager()`, pass it to the provider's `toastManager` prop and call its `add` method.
+
+```tsx
+'use client'
+import type { ReactNode } from 'react'
+import { Toast } from '@navecss/base-ui/toast'
+
+export const toastManager = Toast.createToastManager()
+
+function Toasts() {
+  const { toasts } = Toast.useToastManager()
+  return (
+    <>
+      {toasts.map((toast) => (
+        <Toast.Root key={toast.id} toast={toast}>
+          <Toast.Title />
+          <Toast.Description />
+          <Toast.Close>Dismiss</Toast.Close>
+        </Toast.Root>
+      ))}
+    </>
+  )
+}
+
+export default function ToastArea({ children }: { children: ReactNode }) {
+  return (
+    <Toast.Provider toastManager={toastManager}>
+      {children}
+      <Toast.Portal>
+        <Toast.Viewport>
+          <Toasts />
+        </Toast.Viewport>
+      </Toast.Portal>
+    </Toast.Provider>
+  )
+}
+```
+
+`toastManager.add({ title: 'Saved', description: 'Your changes were saved.' })` then raises a toast from anywhere in your app.
+
+Call `Toast.createToastManager()` in a module that starts with `'use client'`, as in the example, and import the manager from that module.
+
+`Toast.Title` renders an `<h2>`. Pass `render` to use another element.
+
+While a toast is open, pressing F6 moves keyboard focus to the region that holds the toasts, and Tab moves on into them. This is Base UI's behaviour; Nave's styles add none.
+
+A toast closes on its own after its `timeout`, 5000 milliseconds unless you set another on the toast or on the provider. Base UI pauses that timer while the pointer is over the toasts, while keyboard focus is in them and while the window is in the background. A toast whose `timeout` is `0` stays until it is closed, which suits a toast that carries an action the reader needs.
+
+If a toast holds a control that opens a popover, menu or other popup, give that toast a `timeout` of `0`. When keyboard focus moves into a popup rendered outside the toast area, Base UI resumes the toast's timer, so the toast can close while the popup is open, and keyboard focus is then lost.
+
+When more toasts are open than the provider's `limit` (three unless you set it), Base UI keeps the oldest ones on the page but makes them inert, and Nave hides them. Each one comes back when a newer toast closes, unless its own timer runs out first, because a hidden toast's timer keeps running.
+
+Nave fixes the toasts to a bottom corner of the window, above Nave's dialogs and other popups, and an anchored toast, which Base UI places beside its anchor, sits at that same level. So a toast can cover part of your page, a popup or an open dialog, including the control that has keyboard focus. If your page, popups or dialogs can put controls where toasts appear, move the toasts with your own CSS, or move an anchored toast with the `side`, `align` and `sideOffset` of its `Toast.Positioner`.
+
+A popover, menu or tooltip opened from a toast opens under the other toasts where they overlap, unless you pass the toast viewport to its `Portal` as `container`. It then renders inside the region Base UI uses to announce toasts.
+
+Nave paints every toast alike, whatever its `type`. Say what kind of message it is in its title or description.
+
+Base UI moves a toast under the pointer while it is being swiped away, whatever Nave's styles and the reduced-motion setting say; `swipeDirection={[]}` on `Toast.Root` turns swiping off.
+
+### Navigation Menu
+
+A Navigation Menu is a `NavigationMenu.List` of `NavigationMenu.Item`s, each holding either a `NavigationMenu.Trigger` with its `NavigationMenu.Content`, or a single `NavigationMenu.Link`. The open item's content appears in one `NavigationMenu.Popup`, which you render once, after the list, through `NavigationMenu.Portal` and `NavigationMenu.Positioner`, with a `NavigationMenu.Viewport` inside it.
+
+```tsx
+import { NavigationMenu } from '@navecss/base-ui/navigation-menu'
+
+export default function SiteNav() {
+  return (
+    <NavigationMenu.Root>
+      <NavigationMenu.List>
+        <NavigationMenu.Item>
+          <NavigationMenu.Trigger>
+            Guides
+            <NavigationMenu.Icon>
+              <svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true">
+                <path d="M3 6l5 5 5-5" />
+              </svg>
+            </NavigationMenu.Icon>
+          </NavigationMenu.Trigger>
+          <NavigationMenu.Content>
+            <NavigationMenu.Link href="/guides/start" active>
+              Quick start
+            </NavigationMenu.Link>
+            <NavigationMenu.Link href="/guides/theming">Theming</NavigationMenu.Link>
+          </NavigationMenu.Content>
+        </NavigationMenu.Item>
+        <NavigationMenu.Item>
+          <NavigationMenu.Link href="/blog">Blog</NavigationMenu.Link>
+        </NavigationMenu.Item>
+      </NavigationMenu.List>
+      <NavigationMenu.Portal>
+        <NavigationMenu.Positioner>
+          <NavigationMenu.Popup>
+            <NavigationMenu.Viewport />
+          </NavigationMenu.Popup>
+        </NavigationMenu.Positioner>
+      </NavigationMenu.Portal>
+    </NavigationMenu.Root>
+  )
+}
+```
+
+`NavigationMenu.Icon` turns half a turn while its item is open, so put the arrow you want turned inside it.
+
+The panel takes the size of the open item's content, and changes size at once when you move to another item: Nave does not animate it.
+
+Pass `active` to the `NavigationMenu.Link` for the page the reader is on. Base UI then gives it `aria-current="page"`, which marks it as the current page for assistive technology, and Nave gives it a thicker underline than the other links.
+
+Nave removes the bullets from `NavigationMenu.List`. Safari still treats it as a list for screen readers because Base UI renders it inside a `nav` element; if you give the menu's root or popup another element through `render`, add `role="list"` to the list.
+
+Nave does not dim a disabled `NavigationMenu.Trigger` and only withholds its hover fill, because before Base UI 1.6 a disabled trigger still opens its menu on hover. If you disable one, style it yourself.
+
+### Scroll Area
+
+Give `ScrollArea.Root` a height in a class of your own, with `block-size` or `max-block-size`, and its viewport fills it. Render one `ScrollArea.Scrollbar` with a `ScrollArea.Thumb` for each direction that can scroll, and a `ScrollArea.Corner` when both can: Base UI hides the browser's own scrollbars, so a direction without them shows none. Base UI does that with a `<style>` element it renders, so under a Content Security Policy pass your nonce through Base UI's `CSPProvider`. Nave gives the scrollbar and the corner the page's base surface; on a raised panel, set the panel's `background-color` on both with a class of your own.
+
+While its content overflows, a Scroll Area's viewport is a Tab stop, so a keyboard can reach and scroll it. Nave leaves its focus ring to the browser and paints the scrollbars whenever there is something to scroll.
+
+If you pass `keepMounted` to a `ScrollArea.Scrollbar`, it stays on screen over the edge of the content even when there is nothing to scroll in its direction, but Nave makes room for a scrollbar only while its direction can scroll. Give the viewport that room yourself on that edge, as both `padding` and `scroll-padding`: `calc(var(--nave-size-control-xs) + var(--nave-spacing-control-xs))`.
+
+### Meter and Progress
+
+Meter and Progress draw their value as a bar inside an outlined track, in the text colour: set `color` on the `Indicator` to change it. Making the `Track` taller leaves the bar as thick as Nave draws it, centred in the track. To draw it thicker, set the `Indicator`'s `border-block-width` to half the thickness you want and its `max-block-size` to the whole of it, in a class of your own.
+
+Meter and Progress look alike in Nave, but Base UI gives Meter the `meter` role and Progress the `progressbar` role, so choose by meaning: Meter for a measurement within a known range, such as storage used, and Progress for how far a task has got.
+
+An indeterminate Progress (`value={null}`) shows only its empty track: Nave hides the bar, because a full bar would look like a finished task. If you restyle Progress, give the track its height, not the indicator, or an indeterminate bar will fill the track.
+
+### Avatar
+
+`Avatar.Fallback` takes Base UI's `delay` prop, which holds the fallback back for that many milliseconds, so an image that loads quickly does not flash it.
+
+Give `Avatar.Image` an `alt` that names the person, or `alt=""` when their name is written next to it. Until the image loads, or if it fails to load, Base UI shows the fallback in its place, and a screen reader reads the fallback's text instead.
 
 ## Things to know
 
@@ -179,9 +461,19 @@ The Accordion and Collapsible panels set `overflow: hidden` so their height can
 
 When nothing inside a popup can take focus, Base UI focuses the popup itself and the browser draws its focus ring around the panel. This package leaves that ring alone. Removing it with `outline: 0`, as Base UI's own demos do, leaves a keyboard user with no visible sign of where focus is.
 
-In Base UI 1.8.0, `Menu.LinkItem` has no disabled state: a `disabled` prop reaches the `<a>` as a plain attribute, the link still activates, and it does not take the disabled colour Nave gives the other menu items.
+In Combobox and Autocomplete, keyboard focus stays in the text field while the arrow keys move through the list, so Nave marks the option that Enter will choose with the same ring it draws around a focused control. Hovering an option makes it the one Enter chooses, so the ring follows the pointer too. The ring is drawn on the option's `::before`; a rule of yours that sets `::before` on options replaces it.
+
+Nave draws the Combobox and Autocomplete field's border on `InputGroup`, not on the input. If you place the input outside an `InputGroup`, wrap it in an element with a visible border of your own, or the field has no visible edge until it is focused.
+
+In Chromium, opening a Context Menu with a right-click shows focus rings: the browser's own ring around the menu, then a focus ring on whichever item the pointer is over. Chromium decides when a focus ring shows; Nave does not hide it, and other browsers may show it differently.
+
+A Preview Card opens when its link is hovered or focused, but its contents are not reachable with Tab: the next Tab moves past the card and closes it. Keep anything a reader must act on, such as a link or a button, out of the card, or offer it on the page as well.
+
+In a Menubar, moving to the next menu with the arrow keys puts focus on that menu's panel before any item, so the browser's ring around the panel shows where you are until the next arrow key reaches an item.
+
+In Base UI 1.8.0 and 1.9.0, `Menu.LinkItem` has no disabled state: a `disabled` prop reaches the `<a>` as a plain attribute, the link still activates, and it does not take the disabled colour Nave gives the other menu items.
 
-When the reader's system asks for reduced motion, this package turns off the motion of Accordion and Collapsible panels opening and closing, the turn of the icon in their triggers and the switch's slide, even if you have changed Nave's motion tokens. Motion you add or restyle yourself is yours to switch off.
+When the reader's system asks for reduced motion, this package turns off the popups' fade, the tooltip's fade, the backdrop's fade, the toasts' fade, the turn of the icon in Navigation Menu triggers, the tab indicator's slide, the motion of Accordion and Collapsible panels opening and closing, the turn of the icon in their triggers and the switch's slide, even if you have changed Nave's motion tokens. Motion you add or restyle yourself is yours to switch off.
 
 ## License
 

package/dist/accordion/index.js

@@ -1,2 +1 @@
-'use client';
 export * as Accordion from "./parts.generated.js";

package/dist/alert-dialog/index.d.ts

@@ -0,0 +1,2 @@
+export * as AlertDialog from './parts.generated.ts';
+export type * from '@base-ui/react/alert-dialog';

package/dist/alert-dialog/index.js

@@ -0,0 +1 @@
+export * as AlertDialog from "./parts.generated.js";

package/dist/alert-dialog/parts.generated.d.ts

@@ -0,0 +1,55 @@
+import type { ReactElement, RefAttributes } from 'react';
+import { AlertDialog as Base } from '@base-ui/react/alert-dialog';
+import { type VariantProps } from '../part.ts';
+export declare const Root: typeof Base.Root;
+export declare namespace Root {
+    type State = Base.Root.State;
+    type Props<Payload = unknown> = Base.Root.Props<Payload>;
+    type Actions = Base.Root.Actions;
+    type ChangeEventReason = Base.Root.ChangeEventReason;
+    type ChangeEventDetails = Base.Root.ChangeEventDetails;
+}
+export declare const Backdrop: typeof Base.Backdrop;
+export declare namespace Backdrop {
+    type Props = Base.Backdrop.Props;
+    type State = Base.Backdrop.State;
+}
+export declare const Close: (props: Omit<Base.Close.Props, 'ref'> & RefAttributes<HTMLButtonElement> & VariantProps) => ReactElement;
+export declare namespace Close {
+    type Props = Base.Close.Props & VariantProps;
+    type State = Base.Close.State;
+}
+export declare const Description: typeof Base.Description;
+export declare namespace Description {
+    type Props = Base.Description.Props;
+    type State = Base.Description.State;
+}
+export declare const Popup: typeof Base.Popup;
+export declare namespace Popup {
+    type Props = Base.Popup.Props;
+    type State = Base.Popup.State;
+}
+export declare const Portal: typeof Base.Portal;
+export declare namespace Portal {
+    type State = Base.Portal.State;
+    type Props = Base.Portal.Props;
+}
+export declare const Title: typeof Base.Title;
+export declare namespace Title {
+    type Props = Base.Title.Props;
+    type State = Base.Title.State;
+}
+export declare const Trigger: <Payload>(props: Omit<Base.Trigger.Props<Payload>, 'ref'> & RefAttributes<HTMLElement> & VariantProps) => ReactElement;
+export type Trigger = typeof Trigger;
+export declare namespace Trigger {
+    type Props<Payload = unknown> = Base.Trigger.Props<Payload> & VariantProps;
+    type State = Base.Trigger.State;
+}
+export declare const Viewport: typeof Base.Viewport;
+export declare namespace Viewport {
+    type State = Base.Viewport.State;
+    type Props = Base.Viewport.Props;
+}
+export declare const Handle: typeof Base.Handle;
+export type Handle<Payload> = Base.Handle<Payload>;
+export declare const createHandle: typeof Base.createHandle;

package/dist/alert-dialog/parts.generated.js

@@ -0,0 +1,14 @@
+'use client';
+import { AlertDialog as Base } from '@base-ui/react/alert-dialog';
+import { wrapPart, wrapVariantPart } from "../part.js";
+export const Root = /*#__PURE__*/ (() => Base.Root)();
+export const Backdrop = /*#__PURE__*/ (() => wrapPart(Base.Backdrop, 'nave-base-ui-backdrop'))();
+export const Close = /*#__PURE__*/ (() => wrapVariantPart(Base.Close, 'nave-base-ui-button'))();
+export const Description = /*#__PURE__*/ (() => wrapPart(Base.Description, 'nave-base-ui-description'))();
+export const Popup = /*#__PURE__*/ (() => wrapPart(Base.Popup, 'nave-base-ui-dialog-popup nave-base-ui-popup-fade'))();
+export const Portal = /*#__PURE__*/ (() => Base.Portal)();
+export const Title = /*#__PURE__*/ (() => wrapPart(Base.Title, 'nave-base-ui-title'))();
+export const Trigger = /*#__PURE__*/ (() => wrapVariantPart(Base.Trigger, 'nave-base-ui-button'))();
+export const Viewport = /*#__PURE__*/ (() => Base.Viewport)();
+export const Handle = /*#__PURE__*/ (() => Base.Handle)();
+export const createHandle = /*#__PURE__*/ (() => Base.createHandle)();

package/dist/autocomplete/index.d.ts

@@ -0,0 +1,2 @@
+export * as Autocomplete from './parts.generated.ts';
+export type * from '@base-ui/react/autocomplete';

package/dist/autocomplete/index.js

@@ -0,0 +1 @@
+export * as Autocomplete from "./parts.generated.js";

package/dist/autocomplete/parts.generated.d.ts

@@ -0,0 +1,116 @@
+import { Autocomplete as Base } from '@base-ui/react/autocomplete';
+export declare const Root: typeof Base.Root;
+export declare namespace Root {
+    type Props<ItemValue> = Base.Root.Props<ItemValue>;
+    type State = Base.Root.State;
+    type Actions = Base.Root.Actions;
+    type ChangeEventReason = Base.Root.ChangeEventReason;
+    type ChangeEventDetails = Base.Root.ChangeEventDetails;
+    type HighlightEventReason = Base.Root.HighlightEventReason;
+    type HighlightEventDetails = Base.Root.HighlightEventDetails;
+}
+export declare const Value: typeof Base.Value;
+export declare namespace Value {
+    type State = Base.Value.State;
+    type Props = Base.Value.Props;
+}
+export declare const Trigger: typeof Base.Trigger;
+export type Trigger = typeof Trigger;
+export declare namespace Trigger {
+    type State = Base.Trigger.State;
+    type Props = Base.Trigger.Props;
+}
+export declare const Input: typeof Base.Input;
+export declare namespace Input {
+    type State = Base.Input.State;
+    type Props = Base.Input.Props;
+}
+export declare const InputGroup: typeof Base.InputGroup;
+export type InputGroup = typeof InputGroup;
+export declare namespace InputGroup {
+    type State = Base.InputGroup.State;
+    type Props = Base.InputGroup.Props;
+}
+export declare const Icon: typeof Base.Icon;
+export declare namespace Icon {
+    type State = Base.Icon.State;
+    type Props = Base.Icon.Props;
+}
+export declare const Clear: typeof Base.Clear;
+export declare namespace Clear {
+    type State = Base.Clear.State;
+    type Props = Base.Clear.Props;
+}
+export declare const List: typeof Base.List;
+export declare namespace List {
+    type State = Base.List.State;
+    type Props = Base.List.Props;
+}
+export declare const Status: typeof Base.Status;
+export declare namespace Status {
+    type State = Base.Status.State;
+    type Props = Base.Status.Props;
+}
+export declare const Portal: typeof Base.Portal;
+export declare namespace Portal {
+    type State = Base.Portal.State;
+    type Props = Base.Portal.Props;
+}
+export declare const Backdrop: typeof Base.Backdrop;
+export declare namespace Backdrop {
+    type Props = Base.Backdrop.Props;
+    type State = Base.Backdrop.State;
+}
+export declare const Positioner: typeof Base.Positioner;
+export declare namespace Positioner {
+    type State = Base.Positioner.State;
+    type Props = Base.Positioner.Props;
+}
+export declare const Popup: typeof Base.Popup;
+export declare namespace Popup {
+    type State = Base.Popup.State;
+    type Props = Base.Popup.Props;
+}
+export declare const Arrow: typeof Base.Arrow;
+export declare namespace Arrow {
+    type State = Base.Arrow.State;
+    type Props = Base.Arrow.Props;
+}
+export declare const Group: typeof Base.Group;
+export declare namespace Group {
+    type State = Base.Group.State;
+    type Props = Base.Group.Props;
+}
+export declare const GroupLabel: typeof Base.GroupLabel;
+export declare namespace GroupLabel {
+    type State = Base.GroupLabel.State;
+    type Props = Base.GroupLabel.Props;
+}
+export declare const Item: typeof Base.Item;
+export type Item = typeof Item;
+export declare namespace Item {
+    type State = Base.Item.State;
+    type Props = Base.Item.Props;
+}
+export declare const Row: typeof Base.Row;
+export declare namespace Row {
+    type State = Base.Row.State;
+    type Props = Base.Row.Props;
+}
+export declare const Collection: typeof Base.Collection;
+export declare namespace Collection {
+    type State = Base.Collection.State;
+    type Props = Base.Collection.Props;
+}
+export declare const Empty: typeof Base.Empty;
+export declare namespace Empty {
+    type State = Base.Empty.State;
+    type Props = Base.Empty.Props;
+}
+export declare const Separator: typeof Base.Separator;
+export declare namespace Separator {
+    type Props = Base.Separator.Props;
+    type State = Base.Separator.State;
+}
+export declare const useFilter: typeof Base.useFilter;
+export declare const useFilteredItems: typeof Base.useFilteredItems;

package/dist/autocomplete/parts.generated.js

@@ -0,0 +1,27 @@
+'use client';
+// Generated by scripts/generate-wrappers.ts: change the roster or the generator, not this file.
+import { Autocomplete as Base } from '@base-ui/react/autocomplete';
+import { wrapPart } from "../part.js";
+export const Root = /*#__PURE__*/ (() => Base.Root)();
+export const Value = /*#__PURE__*/ (() => Base.Value)();
+export const Trigger = /*#__PURE__*/ (() => wrapPart(Base.Trigger, 'nave-base-ui-combobox-trigger'))();
+export const Input = /*#__PURE__*/ (() => wrapPart(Base.Input, 'nave-base-ui-number-field-input'))();
+export const InputGroup = /*#__PURE__*/ (() => wrapPart(Base.InputGroup, 'nave-base-ui-input-group'))();
+export const Icon = /*#__PURE__*/ (() => wrapPart(Base.Icon, 'nave-base-ui-select-icon'))();
+export const Clear = /*#__PURE__*/ (() => wrapPart(Base.Clear, 'nave-base-ui-number-field-stepper'))();
+export const List = /*#__PURE__*/ (() => Base.List)();
+export const Status = /*#__PURE__*/ (() => Base.Status)();
+export const Portal = /*#__PURE__*/ (() => Base.Portal)();
+export const Backdrop = /*#__PURE__*/ (() => Base.Backdrop)();
+export const Positioner = /*#__PURE__*/ (() => Base.Positioner)();
+export const Popup = /*#__PURE__*/ (() => wrapPart(Base.Popup, 'nave-base-ui-list-popup nave-base-ui-popup-fade'))();
+export const Arrow = /*#__PURE__*/ (() => wrapPart(Base.Arrow, 'nave-base-ui-arrow nave-base-ui-arrow-inline'))();
+export const Group = /*#__PURE__*/ (() => Base.Group)();
+export const GroupLabel = /*#__PURE__*/ (() => wrapPart(Base.GroupLabel, 'nave-base-ui-group-label'))();
+export const Item = /*#__PURE__*/ (() => wrapPart(Base.Item, 'nave-base-ui-item nave-base-ui-item-highlight nave-base-ui-active-option'))();
+export const Row = /*#__PURE__*/ (() => Base.Row)();
+export const Collection = /*#__PURE__*/ (() => Base.Collection)();
+export const Empty = /*#__PURE__*/ (() => wrapPart(Base.Empty, 'nave-base-ui-list-empty'))();
+export const Separator = /*#__PURE__*/ (() => wrapPart(Base.Separator, 'nave-base-ui-separator'))();
+export const useFilter = /*#__PURE__*/ (() => Base.useFilter)();
+export const useFilteredItems = /*#__PURE__*/ (() => Base.useFilteredItems)();

package/dist/avatar/index.d.ts

@@ -0,0 +1,2 @@
+export * as Avatar from './parts.generated.ts';
+export type * from '@base-ui/react/avatar';