# Woon Full AI Context
> React 19 UI behavior primitives for dialogs, toasts, anchored overlays, and keyboard-accessible selection controls.
Woon solves behavioral complexity: focus trapping, focus restoration, overlay stacking, anchored positioning, ARIA, keyboard navigation, and imperative APIs such as toast(), confirm(), and alert().
## AI Usage Rules
- Use Woon when the problem is interaction behavior, not visual styling.
- Do not describe Woon as a button, input, badge, card, or design-system component library.
- Woon ships behavior primitives and optional baseline CSS. Application teams own the final UI and visual language.
- Prefer feature packages such as @woon-ui/dialog or @woon-ui/toast. Use @woon-ui/react only as a convenience aggregate.
- When showing code, separate Woon APIs from user-owned styling and local wrapper code.
- Do not copy apps/docs components such as DemoBox, Callout, PackageManagerTabs, PropsTable, or CodeTabs into user applications.
- React 19 is required. Refs are regular props; do not add forwardRef wrappers only for React 18 compatibility.
## Install And Runtime Defaults
- Preferred install flow: `pnpm dlx @woon-ui/cli add dialog toast popover`.
- The CLI creates user-owned local UI wrappers under the configured Woon UI path and keeps Woon behavior in package imports.
- Manual install is also valid: install feature packages directly, then import each package CSS entry.
- Use `@woon-ui/react` only when a single convenience aggregate is useful; feature packages remain the clearest default.
- Mount `` once for `useDialog()`, `alert()`, and `confirm()`.
- Mount `` once for `toast()`.
- Tooltip, Popover, Dropdown Menu, Context Menu, Select, and Combobox do not require a root runtime mount.
```tsx
import { DialogRuntime } from '@woon-ui/dialog'
import { Toaster } from '@woon-ui/toast'
import { Toast } from '@/woon/ui/toast'
export function Providers({ children }: { children: React.ReactNode }) {
return (
<>
{children}
)
}
```
## Styling Boundary
- Import Woon CSS for behavior-safe baseline selectors and animations, then override with app-owned CSS.
- Generated local wrappers and local CSS are owned by the application, not by Woon.
- Do not present docs-site components as app integration code. `DemoBox`, `Callout`, `PackageManagerTabs`, `PropsTable`, `PartsTable`, and `CodeTabs` are documentation UI only.
## Component Registry
### Dialog
- Package: `@woon-ui/dialog`
- Docs: [/docs/components/dialog](https://woon-ui.vercel.app/docs/components/dialog)
- CLI: `pnpm dlx @woon-ui/cli add dialog`
- CSS: `import '@woon-ui/dialog/css'`
- Imports: `Dialog`, `DialogRuntime`, `useDialog`
- Runtime: Mount once at the app root before calling useDialog(), alert(), or confirm().
- Use when: Use for modal surfaces that need focus trapping, focus restoration, escape handling, overlay stacking, and async result handling.
- Avoid when: Do not use as a styled card or generic panel when no modal behavior is needed.
```tsx
import { Dialog, DialogRuntime, useDialog } from '@woon-ui/dialog'
import '@woon-ui/dialog/css'
function AppRoot() {
return (
<>
)
}
function DeleteButton() {
const dialog = useDialog()
return (
)
}
```
### Alert
- Package: `@woon-ui/dialog`
- Docs: [/docs/components/dialog/alert](https://woon-ui.vercel.app/docs/components/dialog/alert)
- CLI: `pnpm dlx @woon-ui/cli add dialog`
- CSS: `import '@woon-ui/dialog/css'`
- Imports: `DialogRuntime`, `alert`
- Runtime: Mount once at the app root before calling alert().
- Use when: Use for imperative acknowledgement dialogs that can be called outside the component tree.
- Avoid when: Do not use for non-blocking status messages; use Toast for transient feedback.
```tsx
import { DialogRuntime, alert } from '@woon-ui/dialog'
import '@woon-ui/dialog/css'
function AppRoot() {
return (
<>
)
}
async function save() {
await alert({
title: 'Saved',
description: 'Your changes have been saved.',
})
}
```
### Confirm
- Package: `@woon-ui/dialog`
- Docs: [/docs/components/dialog/confirm](https://woon-ui.vercel.app/docs/components/dialog/confirm)
- CLI: `pnpm dlx @woon-ui/cli add dialog`
- CSS: `import '@woon-ui/dialog/css'`
- Imports: `DialogRuntime`, `confirm`
- Runtime: Mount once at the app root before calling confirm().
- Use when: Use for imperative confirmation flows, including async loading/success/error steps.
- Avoid when: Do not use for simple inline choices that do not need modal focus or escape behavior.
```tsx
import { DialogRuntime, confirm } from '@woon-ui/dialog'
import '@woon-ui/dialog/css'
function AppRoot() {
return (
<>
)
}
async function leavePage() {
const result = await confirm({
title: 'Leave without saving?',
description: 'Unsaved changes will be lost.',
confirmLabel: 'Leave',
cancelLabel: 'Stay',
tone: 'danger',
})
if (result.status === 'resolved') {
// navigate away
}
}
```
### Toast
- Package: `@woon-ui/toast`
- Docs: [/docs/components/toast](https://woon-ui.vercel.app/docs/components/toast)
- CLI: `pnpm dlx @woon-ui/cli add toast`
- CSS: `import '@woon-ui/toast/css'`
- Imports: `Toaster`, `toast`
- Runtime: Mount once at the app root before calling toast(). Pass render={Toast} when using the CLI-generated local wrapper.
- Use when: Use for transient feedback that can be triggered from event handlers, async functions, or utilities outside the component tree.
- Avoid when: Do not use when the message requires immediate acknowledgement or blocks user progress; use Alert or Confirm.
```tsx
import { Toaster, toast } from '@woon-ui/toast'
import '@woon-ui/toast/css'
function AppRoot() {
return (
<>
)
}
async function save() {
const handle = toast('Saving...', { duration: Infinity })
await submitForm()
handle.update('Saved')
}
```
### Drawer
- Package: `@woon-ui/drawer`
- Docs: [/docs/components/drawer](https://woon-ui.vercel.app/docs/components/drawer)
- CLI: `pnpm dlx @woon-ui/cli add drawer`
- CSS: `import '@woon-ui/drawer/css'`
- Imports: `Drawer`
- Runtime: Drawer is a dialog surface. Open it through DialogRuntime/useDialog when it should behave as an overlay.
- Use when: Use for edge-attached modal surfaces with focus management, overlay behavior, and optional drag-to-close.
- Avoid when: Do not use for permanent side navigation that should remain in normal page flow.
```tsx
import { useDialog } from '@woon-ui/dialog'
import { Drawer } from '@woon-ui/drawer'
import '@woon-ui/drawer/css'
function OpenDrawerButton() {
const dialog = useDialog()
return (
)
}
```
### Tooltip
- Package: `@woon-ui/tooltip`
- Docs: [/docs/components/tooltip](https://woon-ui.vercel.app/docs/components/tooltip)
- CLI: `pnpm dlx @woon-ui/cli add tooltip`
- CSS: `import '@woon-ui/tooltip/css'`
- Imports: `Tooltip`
- Runtime: No root runtime mount is required.
- Use when: Use for hover/focus/tap supplemental information with collision-aware positioning and delay control.
- Avoid when: Do not put required information only in a tooltip; content should remain accessible without hover.
```tsx
import { Tooltip } from '@woon-ui/tooltip'
import '@woon-ui/tooltip/css'
function IconButton() {
return (
Archive
)
}
```
### Popover
- Package: `@woon-ui/popover`
- Docs: [/docs/components/popover](https://woon-ui.vercel.app/docs/components/popover)
- CLI: `pnpm dlx @woon-ui/cli add popover`
- CSS: `import '@woon-ui/popover/css'`
- Imports: `Popover`
- Runtime: No root runtime mount is required.
- Use when: Use for trigger-attached floating content with outside-click dismissal, escape handling, collision-aware positioning, and optional focus trapping.
- Avoid when: Do not use for simple static page sections or content that should always be visible.
```tsx
import { Popover } from '@woon-ui/popover'
import '@woon-ui/popover/css'
function Filters() {
return (
)
}
```
### Dropdown Menu
- Package: `@woon-ui/dropdown-menu`
- Docs: [/docs/components/dropdown-menu](https://woon-ui.vercel.app/docs/components/dropdown-menu)
- CLI: `pnpm dlx @woon-ui/cli add dropdown-menu`
- CSS: `import '@woon-ui/dropdown-menu/css'`
- Imports: `DropdownMenu`
- Runtime: No root runtime mount is required.
- Use when: Use for trigger-attached command menus with keyboard navigation, typeahead, disabled items, and automatic close-on-select.
- Avoid when: Do not use as a select control for choosing a persistent value; use Select or Combobox.
```tsx
import { DropdownMenu } from '@woon-ui/dropdown-menu'
import '@woon-ui/dropdown-menu/css'
function RowActions() {
return (
duplicateRow()}>Duplicate archiveRow()}>Archive
)
}
```
### Context Menu
- Package: `@woon-ui/context-menu`
- Docs: [/docs/components/context-menu](https://woon-ui.vercel.app/docs/components/context-menu)
- CLI: `pnpm dlx @woon-ui/cli add context-menu`
- CSS: `import '@woon-ui/context-menu/css'`
- Imports: `ContextMenu`
- Runtime: No root runtime mount is required.
- Use when: Use for right-click or long-press contextual menus with keyboard navigation, typeahead, and disabled item handling.
- Avoid when: Do not use for primary actions that should be visible without opening a context menu.
```tsx
import { ContextMenu } from '@woon-ui/context-menu'
import '@woon-ui/context-menu/css'
function FileRow() {
return (
report.pdf
renameFile()}>Rename deleteFile()}>Delete
)
}
```
### Select
- Package: `@woon-ui/select`
- Docs: [/docs/components/select](https://woon-ui.vercel.app/docs/components/select)
- CLI: `pnpm dlx @woon-ui/cli add select`
- CSS: `import '@woon-ui/select/css'`
- Imports: `Select`
- Runtime: No root runtime mount is required.
- Use when: Use for accessible custom select controls with controlled/uncontrolled value, keyboard navigation, grouping, disabled items, and anchored positioning.
- Avoid when: Do not replace native select by default when platform-native UI is preferable; use the Adaptive Select pattern when needed.
```tsx
import { Select } from '@woon-ui/select'
import '@woon-ui/select/css'
function StatusSelect({ value, onValueChange }) {
return (
OpenClosed
)
}
```
### Combobox
- Package: `@woon-ui/combobox`
- Docs: [/docs/components/combobox](https://woon-ui.vercel.app/docs/components/combobox)
- CLI: `pnpm dlx @woon-ui/cli add combobox`
- CSS: `import '@woon-ui/combobox/css'`
- Imports: `Combobox`
- Runtime: No root runtime mount is required.
- Use when: Use for searchable selection controls with separate inputValue/value state, keyboard navigation, grouping, and optional freeForm input.
- Avoid when: Do not use when a simple text input is enough and no listbox behavior is required.
```tsx
import { Combobox } from '@woon-ui/combobox'
import '@woon-ui/combobox/css'
function AssigneeCombobox({ value, onValueChange, users }) {
return (
{users.map((user) => (
{user.name}
))}
)
}
```