@ui-sdk/react 0.0.0-stage → 0.1.0-beta.1

package/docs/parts-and-composition.md

@@ -0,0 +1,93 @@
+# Parts and Composition
+
+Put a component's parts together and choose what each one renders.
+
+A component can have several parts. A Popover has a root to hold its state, a trigger to open it, and content to show.
+
+## Put Parts Together
+
+Import the parts you need and nest them as shown in the component's Composition:
+
+```tsx
+import {
+  Popover,
+  PopoverClose,
+  PopoverContent,
+  PopoverTitle,
+  PopoverTrigger,
+} from "@ui-sdk/react/popover"
+
+function Example() {
+  return (
+    <Popover>
+      <PopoverTrigger>Details</PopoverTrigger>
+      <PopoverContent sideOffset={8}>
+        <PopoverTitle>Project Details</PopoverTitle>
+        <p>Last updated today.</p>
+        <PopoverClose>Done</PopoverClose>
+      </PopoverContent>
+    </Popover>
+  )
+}
+
+export { Example }
+```
+
+`Popover` shares state with its parts without adding an element. Other roots, such as `Tabs`, do render an element. Each component's page shows its structure.
+
+Parts find their root through React context. You can put your own components or layout elements between them.
+
+## Choose the Element
+
+Use `render` to replace a part's default element. For example, render a menu item as a link:
+
+```tsx
+import { Menu, MenuContent, MenuItem, MenuTrigger } from "@ui-sdk/react/menu"
+
+function Example() {
+  return (
+    <Menu>
+      <MenuTrigger>Account</MenuTrigger>
+      <MenuContent>
+        <MenuItem render={<a href="/settings" />}>Settings</MenuItem>
+      </MenuContent>
+    </Menu>
+  )
+}
+
+export { Example }
+```
+
+The part passes its attributes, handlers, and ref to the element. A custom component used here needs to forward those props and the ref to its DOM element.
+
+Your event handler runs first. Calling `event.preventDefault()` skips the part's built-in handler. Class names, styles, and refs combine.
+
+## Read the State
+
+Pass a function to `children` when the content depends on state:
+
+```tsx
+"use client"
+
+import { Toggle } from "@ui-sdk/react/toggle"
+
+function Example() {
+  return (
+    <Toggle aria-label="Mute">
+      {(state) => (state.pressed ? "Mute on" : "Mute off")}
+    </Toggle>
+  )
+}
+
+export { Example }
+```
+
+Keep the accessible name stable when the content changes. Here, `aria-label="Mute"` names the toggle and `aria-pressed` reports its state.
+
+`render` can also be a function of the props and state. [Custom Parts](./custom-parts.md) covers writing a part with logic of its own.
+
+## Name the Control
+
+Use the component's label or title part, such as `FieldLabel` or `DialogTitle`. For a control without visible text, give it an `aria-label`.
+
+Parts manage their own roles, IDs, and ARIA state. Those attributes take precedence over conflicting props passed directly to the part. Props on the element passed to `render` can override them, so leave the managed attributes intact. If you use a render function, forward the supplied props to its element. A name or typing hint you pass replaces the part's own: `aria-label`, `aria-labelledby`, `aria-description`, `title`, `autoComplete`, `autoCapitalize`, `autoCorrect`, `inputMode` and `spellCheck`. Roles, `tabindex`, references like `aria-controls` and `aria-describedby`, state attributes and `data-slot` stay the part's, since its behavior reads them.

package/docs/popups.md

@@ -0,0 +1,117 @@
+# Popups
+
+Place popup content, control dismissal, and choose when it stays mounted.
+
+Popovers, menus, selects, and dialogs use the browser's top layer. They render in place, above the page, so you don't need a Portal or Positioner part. Their events bubble through the elements around them like any other child's, so a click handler or a link wrapped around a popup also gets the clicks inside it. Keep popups outside clickable cards and links.
+
+## Place the Content
+
+Set placement on the content part:
+
+```tsx
+import { Popover, PopoverContent, PopoverTrigger } from "@ui-sdk/react/popover"
+
+function Example() {
+  return (
+    <Popover>
+      <PopoverTrigger>Details</PopoverTrigger>
+      <PopoverContent side="bottom" align="start" sideOffset={8}>
+        Last updated today.
+      </PopoverContent>
+    </Popover>
+  )
+}
+
+export { Example }
+```
+
+The popup flips or shifts when there isn't enough room.
+
+| Prop               | What It Does                                                                                         |
+| ------------------ | ---------------------------------------------------------------------------------------------------- |
+| `side`             | Chooses `top`, `bottom`, `left`, `right`, `start`, or `end`. Start and end follow reading direction. |
+| `align`            | Aligns the popup to the `start`, `center`, or `end` of that side.                                    |
+| `sideOffset`       | Sets the gap from the anchor, in pixels.                                                             |
+| `alignOffset`      | Shifts the popup along its side, in pixels.                                                          |
+| `collisionPadding` | Leaves space from the window's edges.                                                                |
+| `arrowPadding`     | Keeps an arrow away from the popup's corners.                                                        |
+
+An `anchor` can position the popup against another element. The component's page lists the anchors it accepts.
+
+## Control Dismissal
+
+Set `dismissible={false}` to stop Escape, outside presses, focus leaving, Back, and sheet swipes from closing a popup. Its trigger, Close part, and controller can still close it.
+
+```tsx
+<Popover
+  dismissible={false}
+  onDismissAttempt={(details) => console.log(details.reason)}
+>
+  {/* Trigger, content, and a Close part. */}
+</Popover>
+```
+
+Use [State and Events](./state-and-events.md) when you want to cancel only a particular reason, such as an outside press while a form has unsaved changes.
+
+## Modals and Sheets
+
+`modal` makes the rest of the page inert and locks scrolling. Each component documents its default.
+
+Menu, Select, Combobox, Autocomplete, Popover, and Dialog support `presentation="auto"` to become a sheet on small touch screens. Use `presentation="sheet"` to always show a sheet.
+
+```tsx
+<Popover presentation="auto">{/* Trigger and content. */}</Popover>
+```
+
+## Focus
+
+Dialogs, alert dialogs, drawers, and popovers move focus into their content when they open. Where it lands depends on how they opened:
+
+| Opened With                                  | Focus Goes To                                                |
+| -------------------------------------------- | ------------------------------------------------------------ |
+| Keyboard, screen reader, mouse, pen, or code | The element `initialFocus` picks.                            |
+| Touch                                        | The content itself, so no on-screen keyboard appears.        |
+| Hover                                        | Nowhere. Focus stays where it is.                            |
+| Rendered open                                | Nowhere, except in a dialog, which takes focus as it mounts. |
+
+`initialFocus` defaults to `"auto"`: the first focusable element, or the content when it has none. A dialog tries an element with `autofocus` first, and an alert dialog tries its first Close part. Pass `"content"` to focus the content itself, `"none"` to leave focus alone, or a CSS selector, an element, or a function that returns one.
+
+`modal` decides whether Tab can leave. With `true` or `"trap-focus"`, Tab and Shift+Tab wrap inside the content. With `false`, Tab moves from the trigger into a popover and on to the page after it, and focus leaving closes the popover. A non-modal dialog stays open.
+
+When a popup closes while focus is inside it, focus returns to the trigger. If the trigger is gone or can't take focus, focus goes to the element focused before the popup opened, then where the popup it was opened from would return focus, then to the nearest focusable element after where the trigger was. A popup a controller opened returns to the element focused before it first. Set `finalFocus` to `"none"` to leave focus alone, or to a selector, an element, or a function to send it somewhere else. Closing because focus moved away never moves it back, and neither does pressing something focusable outside a non-modal popup.
+
+Menus, selects, and comboboxes handle focus within their own lists, and tooltips never move it. Each component's page covers its own.
+
+## Mounting and Containers
+
+Closed content unmounts after its exit animation. `keepMounted` leaves it in the page, hidden. `onOpenChangeComplete` runs when opening or closing finishes, including animations.
+
+Use `container` to render into another element, a shadow root, or an element in an iframe. Focus, Escape, and scroll locking then work in the document and shadow root the content renders in. Keep a dialog containing a form outside any surrounding form, or move its content with `container`, to avoid nested forms.
+
+In a tree a hidden `<Activity>` or a Suspense fallback hides, an open popup hides with it, from its `container` too, and comes back open when the tree shows, with focus in it if it's modal.
+
+[Styling and Animation](./styling-and-animation.md) shows how to animate the content.
+
+## Toasts and Confirms
+
+Mount `OverlayHost` once near your app's root, then call `toast()` from event handlers:
+
+```tsx
+"use client"
+
+import { OverlayHost } from "@ui-sdk/react/overlays"
+import { toast } from "@ui-sdk/react/toast"
+
+function Example() {
+  return (
+    <>
+      <OverlayHost />
+      <button onClick={() => toast.success("Saved")}>Save</button>
+    </>
+  )
+}
+
+export { Example }
+```
+
+See [Toast](./components/toast.md) and [Alert Dialog](./components/alert-dialog.md) for the complete APIs.

package/docs/rendering.md

@@ -0,0 +1,121 @@
+# Rendering Primitives
+
+Turn a Core primitive into React components with createParts.
+
+This page renders the rating from [Compose Behaviors](./core.md#compose-behaviors). Start with that guide's [complete `rating.ts`](./core.md#complete-primitive): it already handles selection, arrow keys, and focus. Here we'll connect its `root` and `star` slots to React.
+
+## Create the Parts
+
+`createParts` maps slots to elements. Save this beside `rating.ts`:
+
+```ts title="rating-parts.ts"
+"use client"
+
+import { createParts } from "@ui-sdk/react/primitive"
+import { rating } from "./rating"
+
+const { Root: RatingRoot, Star: RatingStar } = createParts(rating, {
+  root: "div",
+  star: "button",
+})
+
+export { RatingRoot, RatingStar }
+```
+
+`Root` creates the instance and shares it with the parts inside. Each mapped slot becomes a component. Slot names become Pascal case: `star` becomes `Star`, and `tab-icon` would become `TabIcon`.
+
+If you leave out the `root` tag, `Root` still shares the instance but renders only its children.
+
+## Render the Rating
+
+The root accepts the primitive's options and the element's props. Each star receives its slot value and a name a screen reader can announce:
+
+```tsx
+"use client"
+
+import { RatingRoot, RatingStar } from "./rating-parts"
+
+function Example() {
+  return (
+    <RatingRoot defaultValue={4} aria-label="Rating" className="flex gap-1">
+      {Array.from({ length: 5 }, (_, index) => index + 1).map((star) => (
+        <RatingStar
+          key={star}
+          value={String(star)}
+          aria-label={`${star} ${star === 1 ? "star" : "stars"}`}
+          className="opacity-40 data-filled:opacity-100"
+        >
+          ★
+        </RatingStar>
+      ))}
+    </RatingRoot>
+  )
+}
+
+export { Example }
+```
+
+The primitive supplies `data-filled`; these classes make the filled stars easier to see. [Styling and Animation](./styling-and-animation.md) covers other ways to style parts.
+
+Generated parts also support the same `render` prop and state callbacks as the components in the catalog. Use [Parts and Composition](./parts-and-composition.md) when you want to change their markup.
+
+## Wrap the Parts
+
+If callers always want a row of stars, wrap the parts in one `Rating` component. This version adds `max` and `starLabel` while forwarding the primitive options and root element props. You can use it instead of the separate parts above.
+
+```tsx
+// rating-react.tsx
+"use client"
+
+import { createParts, type PartProps } from "@ui-sdk/react/primitive"
+import { rating, type RatingOptions } from "./rating"
+
+const parts = createParts(rating, { root: "div", star: "button" })
+
+function Rating({
+  max = 5,
+  starLabel = (star) => `${star} ${star === 1 ? "star" : "stars"}`,
+  ...props
+}: RatingOptions & {
+  max?: number
+  starLabel?: (star: number) => string
+} & Omit<PartProps<"div">, "defaultValue">) {
+  return (
+    <parts.Root {...props}>
+      {Array.from({ length: max }, (_, index) => index + 1).map((star) => (
+        <parts.Star
+          key={star}
+          value={String(star)}
+          aria-label={starLabel(star)}
+        >
+          ★
+        </parts.Star>
+      ))}
+    </parts.Root>
+  )
+}
+
+export { Rating }
+```
+
+```tsx
+import { Rating } from "./rating-react"
+
+function Example() {
+  return (
+    <Rating
+      defaultValue={4}
+      aria-label="Rating"
+      className="flex gap-1 [&>button]:opacity-40 [&>[data-filled]]:opacity-100"
+    />
+  )
+}
+
+export { Example }
+```
+
+Pass classes to the rendered parts. [Styling and Animation](./styling-and-animation.md) also shows how to use CSS Modules.
+
+## Add Logic to a Part
+
+Keep `createParts` when mapping slots to elements is enough. [Custom Parts](./custom-parts.md) uses the same rating to show how `usePrimitive` and `usePart` let you write your own root or child part.

package/docs/server-rendering.md

@@ -0,0 +1,253 @@
+# Server Rendering
+
+Render the initial HTML on the server and add interactions when React hydrates.
+
+ui-sdk parts render their initial HTML on the server, including ARIA state and keyboard tab stops. Hydration connects the event handlers in the browser.
+
+## Render from a Server Component
+
+In an app with React Server Components, such as Next.js, you can render ui-sdk components directly from a server page. Their modules already include `"use client"`:
+
+```tsx
+import { Toggle } from "@ui-sdk/react/toggle"
+
+function Page() {
+  return <Toggle defaultPressed>Bold</Toggle>
+}
+
+export { Page }
+```
+
+The server sends a button with `aria-pressed="true"`. It can toggle after hydration. Native HTML behavior, such as submitting a form, can work before hydration.
+
+## Wrappers in a Server Component
+
+A wrapper that only renders markup can stay on the server. `renderElement` lets it support the same `render` prop as other parts:
+
+```tsx
+import { renderElement, type PartProps } from "@ui-sdk/react/primitive"
+
+function Card({ render, ...props }: PartProps<"div">) {
+  return renderElement("div", { ...props, "data-card": "" }, render)
+}
+
+function Page() {
+  return (
+    <Card render={<section />} className="card">
+      Your plan renews on May 1.
+    </Card>
+  )
+}
+
+export { Card, Page }
+```
+
+The server renders a `section` with the card’s props.
+
+Put custom parts built with `usePrimitive`, `usePart`, or `createParts` in a client module. A Server Component can then render those exported parts, just like `Toggle` above.
+
+## Add Your Own Client Boundary
+
+If your component owns React state, callbacks, or render functions, put `"use client"` at the top of its entry file:
+
+```tsx title="mute-button.tsx"
+"use client"
+
+import { Toggle } from "@ui-sdk/react/toggle"
+import { useState } from "react"
+
+function MuteButton() {
+  const [muted, setMuted] = useState(false)
+
+  return (
+    <>
+      <Toggle pressed={muted} onPressedChange={setMuted}>
+        Mute
+      </Toggle>
+      <output>{muted ? "Sound is off" : "Sound is on"}</output>
+    </>
+  )
+}
+
+export { MuteButton }
+```
+
+Render `MuteButton` from your server page. Clicking Mute changes its pressed state and the output; the button keeps the same accessible name.
+
+Keep ordinary callbacks and render functions inside the client boundary. They cannot cross from a Server Component as props.
+
+## Saved Preferences and Storage
+
+Preferences like a color scheme or an emoji skin tone are saved in the browser, so the server can't render them. [Preferences](./core.md#preferences) covers the preferences themselves; this is how they fit server rendering.
+
+### Show Them Before Hydration
+
+Render `Preferences` at the top of `<body>`. On the server it renders one inline script as its first child, which puts every saved value on its `data-*` attribute as the page loads, before React hydrates, so CSS that selects those attributes is right from the first paint. Preferences hold functions, which can't cross from a Server Component as props, so give them to `Preferences` in a client module:
+
+```tsx title="app-preferences.tsx"
+"use client"
+
+import { Preferences } from "@ui-sdk/react/preferences"
+import { colorScheme, skinTone } from "./preferences"
+
+function AppPreferences({ children }: { children: React.ReactNode }) {
+  return (
+    <Preferences preferences={[colorScheme, skinTone]}>{children}</Preferences>
+  )
+}
+
+export { AppPreferences }
+```
+
+```tsx title="root.tsx"
+import { AppPreferences } from "./app-preferences"
+
+function Root({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <AppPreferences>{children}</AppPreferences>
+      </body>
+    </html>
+  )
+}
+
+export { Root }
+```
+
+A preference made with `global: true` goes on `<html>`, which the script sets before hydration, so `<html>` needs `suppressHydrationWarning`. Pass `nonce` to `Preferences` if your Content Security Policy only allows inline scripts with one.
+
+Content that reads a preference through `usePreference` renders the default on the server and the saved value right after hydration. Style by the attribute instead wherever the first paint has to be right, as [Style by Preferences](./core.md#style-by-preferences) shows.
+
+### Read a Cookie on the Server
+
+A preference kept in a cookie can render on the server too, content included. Read the request's `Cookie` header on the server, however your server or framework gives you the request, and pass it to your root as a prop, like `<Root cookie={request.headers.get("cookie")}>`. A preference made from a request belongs to that request, so create it in the client boundary, once per render of the app, and share it through context:
+
+```tsx title="root.tsx"
+import { AppPreferences } from "./app-preferences"
+
+function Root({
+  cookie,
+  children,
+}: {
+  cookie: string | null
+  children: React.ReactNode
+}) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <AppPreferences cookie={cookie}>{children}</AppPreferences>
+      </body>
+    </html>
+  )
+}
+
+export { Root }
+```
+
+```tsx title="app-preferences.tsx"
+"use client"
+
+import { createCookieStorage, createPreference } from "@ui-sdk/core"
+import { Preferences } from "@ui-sdk/react/preferences"
+import { createContext, useState } from "react"
+
+const createSkinTone = (cookie: string | null) =>
+  createPreference({
+    values: ["default", "light", "medium", "dark"],
+    defaultValue: "default",
+    attribute: "data-skin-tone",
+    storage: createCookieStorage("skin-tone", { cookie }),
+  })
+
+const SkinToneContext = createContext<ReturnType<typeof createSkinTone> | null>(
+  null
+)
+
+function AppPreferences({
+  cookie,
+  children,
+}: {
+  cookie: string | null
+  children: React.ReactNode
+}) {
+  const [skinTone] = useState(() => createSkinTone(cookie))
+  return (
+    <SkinToneContext value={skinTone}>
+      <Preferences preferences={[skinTone]}>{children}</Preferences>
+    </SkinToneContext>
+  )
+}
+
+export { AppPreferences, SkinToneContext }
+```
+
+The server reads the value from `cookie`, and the browser from `document.cookie`, so both render it and hydration matches. `usePreference(skinTone)` returns the saved value from the first render.
+
+### Render the Storage Script Yourself
+
+`Preferences` is the usual way. For one component that keeps its own value, like a toolbar's density, a storage's `script` returns the same kind of inline script for a single element. Render it right after the element, since it writes to the element right before it:
+
+```tsx title="toolbar.tsx"
+"use client"
+
+import { createLocalStorage } from "@ui-sdk/core"
+import { useEffect, useState, useSyncExternalStore } from "react"
+
+const density = createLocalStorage("density")
+const script = density.script({
+  attribute: "data-density",
+  values: ["comfortable", "compact"],
+})
+const noSubscribe = () => () => {}
+
+function Toolbar({ children }: { children: React.ReactNode }) {
+  const [value, setValue] = useState("comfortable")
+  // True on the server and while hydrating, when the script is in the HTML.
+  const fromServer = useSyncExternalStore(
+    noSubscribe,
+    () => false,
+    () => true
+  )
+  useEffect(
+    () => setValue(density.get() === "compact" ? "compact" : "comfortable"),
+    []
+  )
+  return (
+    <>
+      <div data-density={value} suppressHydrationWarning>
+        {children}
+      </div>
+      {fromServer && script ? (
+        <script dangerouslySetInnerHTML={{ __html: script }} />
+      ) : null}
+    </>
+  )
+}
+
+export { Toolbar }
+```
+
+- **Only from the server.** The browser never runs a script React inserts, and React warns about one, so leave it out of a render in the browser only. `fromServer` is true on the server and while hydrating, and false after.
+- **The element differs until hydration.** The script changes its attribute before React hydrates, so `suppressHydrationWarning` goes on that element. After hydration, render the saved value from state, as above.
+- **Shared by ID.** Every script with the same storage kind and ID reads the storage once, however many elements render it, and the scripts are identical, so compression shrinks the repeats.
+- **Only safe values.** Any script on your site can write the saved value, so `script` only sets attributes that start with `data-`, and only to one of `values`.
+- **Not for cookies.** A cookie storage's `script` returns undefined, since the server reads the cookie and renders the value itself.
+
+To run before the page's content at all, render `preferencesScript([...])` from `@ui-sdk/core` in `<head>` yourself. Only global preferences make sense there, since the others go on the script's parent element.
+
+## Keep the First Render Consistent
+
+Use the same initial values on the server and client. Read browser-only values in an effect or event handler, after hydration.
+
+### IDs
+
+Parts generate IDs for their relationships, such as a Dialog trigger’s `aria-controls` and a Field label’s `for`. You usually do not need to supply them.
+
+Pass an explicit `id` when something outside the component needs to refer to a part. On the server, render order matters: if a Field label renders before a control with your ID, the label initially uses the generated ID. Hydration updates the reference to yours. The same applies to Dialog triggers, titles, and descriptions.
+
+Keep a part with your ID in the same Suspense boundary as the parts that reference it so they hydrate together. Pass the ID to the part or its `render` element; an ID assigned inside a render function cannot be read ahead and is picked up during hydration.
+
+Use classes or data attributes for styling, rather than generated IDs.
+
+Popups render in place, so they don't need a portal root in your server layout. [Popups](./popups.md) covers their placement and containers; [Forms](./forms.md) covers submission and validation.

package/docs/state-and-events.md

@@ -0,0 +1,105 @@
+# State and Events
+
+Set an initial value, control it from React, and respond to changes.
+
+Components manage their own state unless you pass a controlled value. A change callback lets you respond in either case.
+
+## Set the Starting Value
+
+Use a default prop to choose the starting state. Here, Bold starts pressed and changes when you click it:
+
+```tsx
+import { Toggle } from "@ui-sdk/react/toggle"
+
+function Example() {
+  return <Toggle defaultPressed>Bold</Toggle>
+}
+
+export { Example }
+```
+
+The prop depends on the component: `defaultPressed`, `defaultChecked`, `defaultOpen`, or `defaultValue`.
+
+## Control the Value
+
+Pass the value and its change callback to keep it in React state:
+
+```tsx
+"use client"
+
+import { Toggle } from "@ui-sdk/react/toggle"
+import { useState } from "react"
+
+function Example() {
+  const [pressed, setPressed] = useState(false)
+
+  return (
+    <>
+      <Toggle pressed={pressed} onPressedChange={setPressed}>
+        Bold
+      </Toggle>
+      <output>{pressed ? "On" : "Off"}</output>
+    </>
+  )
+}
+
+export { Example }
+```
+
+Other components use pairs such as `open` and `onOpenChange`, or `value` and `onValueChange`. The component requests the next value; your callback updates the state you pass back. If you keep passing `false`, the toggle stays off.
+
+To keep a value in the URL, still update your state in the callback, then navigate. A value that changes only when the navigation finishes leaves the component showing the old one until then, and logs a warning in development.
+
+## Understand a Change
+
+The first callback argument is the requested value. The second, `details`, tells you where the request came from and lets you cancel it:
+
+| Detail     | What It Tells You                                                                                     |
+| ---------- | ----------------------------------------------------------------------------------------------------- |
+| `reason`   | What requested the change, such as `trigger-press` or `escape-key`. Each component lists its reasons. |
+| `event`    | The DOM event, when the change came from one.                                                         |
+| `source`   | `keyboard`, `mouse`, `touch`, `pen`, `virtual`, `programmatic`, or `agent`.                           |
+| `cancel()` | Stops the requested change.                                                                           |
+
+For example, keep a popover open when someone clicks outside it:
+
+```tsx
+"use client"
+
+import {
+  Popover,
+  PopoverClose,
+  PopoverContent,
+  PopoverTitle,
+  PopoverTrigger,
+} from "@ui-sdk/react/popover"
+
+function Example() {
+  return (
+    <Popover
+      onOpenChange={(open, details) => {
+        if (!open && details.reason === "outside-press") {
+          details.cancel()
+        }
+      }}
+    >
+      <PopoverTrigger>Details</PopoverTrigger>
+      <PopoverContent>
+        <PopoverTitle>Project Details</PopoverTitle>
+        <p>Last updated today.</p>
+        <PopoverClose>Done</PopoverClose>
+      </PopoverContent>
+    </Popover>
+  )
+}
+
+export { Example }
+```
+
+The Done button and Escape still close the popover. Cancellation works for controlled and uncontrolled state. Add `debug` to a root to log changes and their reasons while you work.
+
+## Empty and Multiple Values
+
+Select, Tabs, and Radio Group report `null` when nothing is selected. A multiple Select or Combobox uses an array. Accordion and Toggle Group always use arrays.
+
+To change a component from outside its React tree, use a [Controller](./controllers.md).