@janbox/storefront-ui 2.0.28 → 2.0.30

package/dist/lib/menu/README.md

@@ -0,0 +1,92 @@
+# Menu
+
+Dropdown menu component hiển thị danh sách actions hoặc options khi được kích hoạt. Xây dựng trên Floating UI, hỗ trợ tương tác hover và click với safe polygon hover detection.
+
+## Import
+
+```tsx
+import { Menu } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `placement` | `Placement` | `'bottom'` | Vị trí của menu so với trigger (vd: `'top'`, `'bottom'`, `'left'`, `'right'`, và các biến thể như `'top-start'`) |
+| `open` | `boolean` | - | Controlled open state của menu |
+| `onOpenChange` | `(open: boolean, event?: Event, reason?: string) => void` | - | Callback khi trạng thái open thay đổi |
+| `clickProps` | `UseClickProps` | - | Cấu hình tương tác click (bật mặc định) |
+| `dismissProps` | `UseDismissProps` | - | Cấu hình dismiss khi click ra ngoài (bật mặc định) |
+| `hoverProps` | `UseHoverProps` | - | Cấu hình tương tác hover (dùng `safePolygon` mặc định để tránh đóng nhầm) |
+| `focusProps` | `UseFocusProps` | - | Cấu hình tương tác focus |
+| `offsetOptions` | `OffsetOptions` | - | Khoảng cách giữa trigger và menu content |
+| `sizeOptions` | `SizeOptions` | - | Ràng buộc kích thước của floating menu |
+| `autoUpdateOptions` | `AutoUpdateOptions` | - | Tùy chọn tự động cập nhật vị trí menu |
+| `children` * | `ReactNode` | - | Nội dung menu (thường là `MenuTrigger` và `MenuList`) |
+
+*Bắt buộc
+
+## Examples
+
+### Basic Menu
+
+```tsx
+<Menu>
+  <MenuTrigger>
+    <button>Open Menu ▼</button>
+  </MenuTrigger>
+  <MenuList>
+    <MenuItem>Profile</MenuItem>
+    <MenuItem>Settings</MenuItem>
+    <MenuItem>Help</MenuItem>
+    <MenuItem>Logout</MenuItem>
+  </MenuList>
+</Menu>
+```
+
+### Menu with Icons
+
+```tsx
+<Menu>
+  <MenuTrigger>
+    <button>Actions ▼</button>
+  </MenuTrigger>
+  <MenuList>
+    <MenuItem>✏️ Edit</MenuItem>
+    <MenuItem>📋 Copy</MenuItem>
+    <MenuItem>🗑️ Delete</MenuItem>
+  </MenuList>
+</Menu>
+```
+
+### Top Placement Menu
+
+```tsx
+<Menu placement="top">
+  <MenuTrigger>
+    <button>Open Top ▲</button>
+  </MenuTrigger>
+  <MenuList>
+    <MenuItem>Option 1</MenuItem>
+    <MenuItem>Option 2</MenuItem>
+    <MenuItem>Option 3</MenuItem>
+  </MenuList>
+</Menu>
+```
+
+## Related Components
+
+- [Floating](../floating/README.md)
+- [FloatingTrigger](../floating-trigger/README.md)
+- [FloatingContent](../floating-content/README.md)
+- [Button](../button/README.md)
+
+## Dependencies
+
+- `@floating-ui/react`
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./menu.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/multiple-select/README.md

@@ -0,0 +1,108 @@
+# MultipleSelect
+
+A generic multi-select dropdown component that renders selected values as tags inside an input trigger. It supports search filtering, virtualized option lists, controlled/uncontrolled state, and responsive sizing.
+
+## Import
+
+```tsx
+import { MultipleSelect } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `options*` | `O[]` | - | Array of option objects to display in the dropdown list. |
+| `value` | `Array<Partial<O> \| MultipleSelectOptionValue>` | - | Controlled selected values. Can be full option objects or primitive values (string \| number). |
+| `defaultValue` | `Array<Partial<O> \| MultipleSelectOptionValue>` | - | Initial selected values for uncontrolled usage. |
+| `onChange` | `(value: O[]) => void` | - | Callback fired when the selection changes, receiving the full array of selected option objects. |
+| `optionValue` | `keyof O \| ((option: O) => MultipleSelectOptionValue)` | `'value'` | Key or function to derive the unique value from an option object. |
+| `optionLabel` | `keyof O \| ((option: O) => React.ReactNode)` | `'label'` | Key or function to derive the display label from an option object. |
+| `tagLabel` | `keyof O \| ((option: O) => React.ReactNode)` | - | Key or function to derive the label shown inside the selected tag chip. Falls back to `optionLabel` if not set. |
+| `optionSearchLabel` | `keyof O \| Array<keyof O> \| ((option: O) => string \| string[])` | - | Field(s) or function used when filtering options by the search input. Defaults to `optionLabel`. |
+| `searchable` | `boolean` | `true` | Whether to show a search input inside the dropdown for filtering options. |
+| `displayCount` | `number` | `1` | Maximum number of tag chips shown in the trigger before collapsing into a `+N` badge. Use `Infinity` to show all. |
+| `placeholder` | `string` | - | Placeholder text shown in the trigger when no values are selected. |
+| `open` | `boolean` | - | Controlled open state of the dropdown. |
+| `onOpenChange` | `UseFloatingOptions['onOpenChange']` | - | Callback fired when the open state changes. |
+| `placement` | `Placement` | `'bottom-start'` | Floating UI placement for the dropdown panel. |
+| `error` | `boolean` | - | When true, renders the trigger in an error/invalid visual state. |
+| `helperText` | `string` | - | Helper or validation message rendered below the trigger via `FormHelperText`. |
+| `containerProps` | `PrimitiveProps<JSX.IntrinsicElements['div']>` | - | Props forwarded to the outer container `Primitive` wrapper. |
+| `inputProps` | `InputProps` | - | Props forwarded to the search `Input` rendered inside the dropdown panel. |
+| `listProps` | `PropsWithoutRef<HTMLProps<HTMLDivElement>>` | - | Props forwarded to the `VirtualizedList` container element. |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Size variant controlling height, padding, and font size of the trigger and option rows. |
+
+*Required props
+
+## Examples
+
+### Basic usage
+
+```tsx
+type Option = { label: string; value: string };
+
+const fruits: Option[] = [
+  { label: 'Apple', value: 'apple' },
+  { label: 'Banana', value: 'banana' },
+  { label: 'Cherry', value: 'cherry' },
+];
+
+<MultipleSelect<Option>
+  options={fruits}
+  placeholder="Select fruits..."
+  onChange={(selected) => console.log(selected)}
+/>
+```
+
+### Controlled with error state
+
+```tsx
+const [selected, setSelected] = useState<string[]>([]);
+
+<MultipleSelect
+  options={fruits}
+  value={selected}
+  onChange={(opts) => setSelected(opts.map((o) => o.value))}
+  error={selected.length === 0}
+  helperText={selected.length === 0 ? 'Please select at least one option' : undefined}
+  placeholder="Select fruits..."
+/>
+```
+
+### Display multiple tags with overflow badge
+
+```tsx
+// Shows up to 2 tag chips, remaining selections collapse into '+N' badge
+<MultipleSelect<Option>
+  options={fruits}
+  value={['apple', 'banana', 'cherry']}
+  displayCount={2}
+  placeholder="Select fruits..."
+  onChange={handleChange}
+/>
+```
+
+## Related Components
+
+- [Input](../input/README.md)
+- [InputMask](../inputmask/README.md)
+- [Checkbox](../checkbox/README.md)
+- [Floating](../floating/README.md)
+- [FloatingTrigger](../floatingtrigger/README.md)
+- [FloatingContent](../floatingcontent/README.md)
+- [FormHelperText](../formhelpertext/README.md)
+- [VirtualizedList](../virtualizedlist/README.md)
+- [Primitive](../primitive/README.md)
+
+## Dependencies
+
+- @floating-ui/react
+- @tanstack/react-virtual
+- lodash-es
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./multipleselect.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/nav-link/README.md

@@ -0,0 +1,61 @@
+# NavLink
+
+A wrapper around React Router's NavLink component that adds safe handling for undefined `to` prop. When `to` is nil, the link prevents navigation and treats itself as inactive, making it safe to render navigation items that may not yet have a destination.
+
+## Import
+
+```tsx
+import { NavLink } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `to` | `ReactRouterNavLinkProps['to'] \| undefined` | - | Đường dẫn hoặc location object. Khi `undefined` hoặc `null`, link sẽ ngăn navigation và được coi là inactive (`isActive = false`). |
+| `children` | `React.ReactNode \| ((props: NavLinkRenderProps) => React.ReactNode)` | - | Nội dung bên trong link. Có thể là render function nhận NavLink render props gồm `isActive`, `isPending`, `isTransitioning`. Khi `to` là nil, `isActive` luôn là `false`. |
+| `className` | `string \| ((props: NavLinkRenderProps) => string \| undefined)` | - | Class name hoặc function nhận render props để tính class động. `isActive` trong render props tuân theo nil-to override. |
+| `style` | `React.CSSProperties \| ((props: NavLinkRenderProps) => React.CSSProperties \| undefined)` | - | Inline styles hoặc function nhận render props để tính styles động. `isActive` trong render props tuân theo nil-to override. |
+| `end` | `boolean` | - | Khi `true`, active class/style chỉ được áp dụng khi URL hiện tại khớp chính xác với `to` (không partial matching). |
+| `ref` | `Ref<HTMLAnchorElement>` | - | Forwarded ref đến anchor element bên dưới. |
+| `onClick` | `(event: React.MouseEvent<HTMLAnchorElement>) => void` | - | Click handler. Navigation tự động bị ngăn khi `to` là nil hoặc khi `aria-disabled` là `true`. |
+
+## Examples
+
+### Basic navigation link
+
+```tsx
+<NavLink to="/home">Home</NavLink>
+```
+
+### Active state with exact match and dynamic class
+
+```tsx
+<NavLink
+  to="/dashboard"
+  end
+  className={({ isActive }) => isActive ? 'nav-item nav-item--active' : 'nav-item'}
+>
+  Dashboard
+</NavLink>
+```
+
+### Placeholder link with no destination (disabled navigation)
+
+```tsx
+<NavLink to={undefined} aria-disabled="true">
+  {({ isActive }) => (
+    <span style={{ opacity: isActive ? 1 : 0.5 }}>Coming Soon</span>
+  )}
+</NavLink>
+```
+
+## Dependencies
+
+- react-router
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./navlink.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/notifications/README.md

@@ -0,0 +1,103 @@
+# Notifications
+
+A toast notification system that renders dismissible notification cards in a fixed portal overlay at the top-right of the screen. It uses an external store (`notificationStore`) and the `useNotifications` hook to push notifications imperatively from anywhere in the app.
+
+## Import
+
+```tsx
+import { Notifications } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+
+## Examples
+
+### Basic usage — mount Notifications once and push via hook
+
+```tsx
+import { Notifications, useNotifications } from '@janbox/storefront-ui';
+
+const App = () => (
+  <>
+    {/* Mount once at the root level */}
+    <Notifications />
+    <MyPage />
+  </>
+);
+
+const MyPage = () => {
+  const { pushNotifications } = useNotifications();
+
+  return (
+    <button
+      onClick={() =>
+        pushNotifications({
+          title: 'Success',
+          message: 'Your changes have been saved.',
+          color: 'green',
+        })
+      }
+    >
+      Save
+    </button>
+  );
+};
+```
+
+### Push multiple notifications with custom duration
+
+```tsx
+const { pushNotifications } = useNotifications();
+
+pushNotifications([
+  {
+    title: 'Item added',
+    message: 'Product has been added to your cart.',
+    color: 'primary',
+    duration: 4000,
+  },
+  {
+    title: 'Stock low',
+    message: 'Only 2 items left in stock.',
+    color: 'orange',
+    duration: 6000,
+  },
+]);
+```
+
+### Error notification on API failure
+
+```tsx
+const { pushNotifications } = useNotifications();
+
+try {
+  await submitOrder();
+} catch (err) {
+  pushNotifications({
+    title: 'Order failed',
+    message: 'Something went wrong. Please try again.',
+    color: 'red',
+    duration: 5000,
+  });
+}
+```
+
+## Related Components
+
+- [IconButton](../icon-button/README.md)
+- [Primitive](../primitive/README.md)
+
+## Dependencies
+
+- @floating-ui/react
+- lodash-es
+- motion/react
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./notifications.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/otp-input/README.md

@@ -0,0 +1,71 @@
+# OtpInput
+
+A one-time password input component that renders multiple individual input fields for entering verification codes. Supports auto-focus, paste handling, keyboard navigation, and automatic progression between fields.
+
+## Import
+
+```tsx
+import { OtpInput } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `length` | `number` | 6 | Number of OTP input fields to render |
+| `onChange` | `(otp: string) => void` | - | Callback fired when any digit changes, receives the complete OTP string |
+| `onFullfilled` | `(otp: string) => void` | - | Callback fired when all digits are filled, receives the complete OTP string |
+| `disabled` | `boolean` | - | Disables all input fields |
+| `autoFocus` | `boolean` | - | Auto-focuses the first input field on mount |
+| `isLoading` | `boolean` | - | Makes all input fields read-only during loading state |
+| `defaultValue` | `string` | - | Default OTP value (uncontrolled) |
+| `value` | `string` | - | Controlled OTP value |
+| `error` | `boolean` | - | Shows error state styling on all input fields |
+| `size` | `InputSizeVariant` | - | Size variant for all input fields |
+| `sm` | `InputResponsiveProps` | - | Responsive props for small breakpoint (768px+) |
+| `md` | `InputResponsiveProps` | - | Responsive props for medium breakpoint (1280px+) |
+| `lg` | `InputResponsiveProps` | - | Responsive props for large breakpoint (1680px+) |
+
+## Examples
+
+### Basic 6-digit OTP
+
+```tsx
+<OtpInput length={6} onChange={(otp) => console.log(otp)} />
+```
+
+### 4-digit PIN with auto-submit
+
+```tsx
+<OtpInput
+  length={4}
+  autoFocus
+  onFullfilled={(otp) => handleVerify(otp)}
+/>
+```
+
+### Controlled with error state
+
+```tsx
+<OtpInput
+  length={6}
+  value={otpValue}
+  onChange={setOtpValue}
+  error={hasError}
+  disabled={isSubmitting}
+/>
+```
+
+## Related Components
+
+- [Input](../input/README.md)
+
+## Dependencies
+
+- lodash-es
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./otpinput.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/pagination/README.md

@@ -0,0 +1,84 @@
+# Pagination
+
+A pagination component for navigating through multiple pages of content. Displays page numbers with ellipsis for large page counts, supports customizable navigation buttons, and provides responsive sizing.
+
+## Import
+
+```tsx
+import { Pagination } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `page` | `number` | 1 | Current active page number |
+| `totalPages` | `number` | 1 | Total number of pages available |
+| `onChange` | `(page: number) => void` | - | Callback function triggered when page changes |
+| `disabled` | `boolean` | - | Disables all pagination interactions |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `sm` | Size variant for pagination buttons and text |
+| `showPrevPageButton` | `boolean` | `true` | Show/hide the previous page navigation button |
+| `showNextPageButton` | `boolean` | `true` | Show/hide the next page navigation button |
+| `showFirstPageButton` | `boolean` | `false` | Show/hide the first page navigation button |
+| `showLastPageButton` | `boolean` | `false` | Show/hide the last page navigation button |
+| `siblingCount` | `number` | `2` | Number of pages to show on each side of the current page |
+| `states` | `Partial<Record<'normal' \| 'active', { color?: IconButtonProps['color']; variant?: IconButtonProps['variant']; }>>` | `{ normal: { color: 'neutral', variant: 'outlined' }, active: { color: 'primary', variant: 'outlined' } }` | Customize color and variant for normal and active pagination button states |
+| `sm` | `{ size?: SizeVariant }` | - | Responsive props for small breakpoint (768px) |
+| `md` | `{ size?: SizeVariant }` | - | Responsive props for medium breakpoint (1280px) |
+| `lg` | `{ size?: SizeVariant }` | - | Responsive props for large breakpoint (1680px) |
+
+## Examples
+
+### Basic pagination with 10 pages
+
+```tsx
+<Pagination
+  page={5}
+  totalPages={10}
+  onChange={(page) => console.log('Navigate to page:', page)}
+/>
+```
+
+### Pagination with first/last buttons and custom sibling count
+
+```tsx
+<Pagination
+  page={7}
+  totalPages={50}
+  siblingCount={2}
+  showFirstPageButton
+  showLastPageButton
+  onChange={(page) => setCurrentPage(page)}
+/>
+```
+
+### Disabled pagination with custom button states
+
+```tsx
+<Pagination
+  page={3}
+  totalPages={10}
+  disabled
+  states={{
+    normal: { color: 'neutral', variant: 'outlined' },
+    active: { color: 'blue', variant: 'contained' }
+  }}
+  onChange={(page) => handlePageChange(page)}
+/>
+```
+
+## Related Components
+
+- [IconButton](../iconbutton/README.md)
+- [Icon](../icon/README.md)
+- [Text](../text/README.md)
+
+## Dependencies
+
+- @emotion/react
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./pagination.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/phone-input/README.md

@@ -0,0 +1,80 @@
+# PhoneInput
+
+A phone number input component that combines a country dial code selector with a national number text field. It supports controlled and uncontrolled usage, auto-parses country codes from dial codes, and displays formatted phone numbers when not focused.
+
+## Import
+
+```tsx
+import { PhoneInput } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `PhoneInputValue` | - | Controlled value object containing countryCode, dialCode, and nationalNumber. |
+| `defaultValue` | `PhoneInputValue` | - | Uncontrolled default value. Defaults to the first country in the countries list if not provided. |
+| `onChange` | `(value: PhoneInputValue) => void` | - | Callback fired when either the country dial code or the national number changes. Receives a PhoneInputValue object. |
+| `error` | `boolean` | `false` | Puts the input into an error state, rendering the border in red. |
+| `helperText` | `string` | - | Helper or error message displayed below the input via FormHelperText. |
+| `disabled` | `boolean` | `false` | Disables both the country select and the number input, applying a disabled surface color. |
+| `containerProps` | `PrimitiveProps<JSX.IntrinsicElements['div']>` | - | Props forwarded to the outer container Primitive div, useful for layout overrides via sx. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size variant for the input. xs is excluded. Supports responsive values via sm/md/lg breakpoint keys. |
+| `css` | `Interpolation` | - | Emotion CSS interpolation applied directly to the InputMask wrapper element. |
+
+## Examples
+
+### Default (uncontrolled)
+
+```tsx
+<div style={{ width: 300 }}>
+  <PhoneInput onChange={(value) => console.log(value)} />
+</div>
+```
+
+### Controlled with initial value
+
+```tsx
+const [phone, setPhone] = useState<PhoneInputValue>({
+  countryCode: 'JP',
+  dialCode: '+81',
+  nationalNumber: '9012345678',
+});
+
+<PhoneInput
+  value={phone}
+  onChange={setPhone}
+/>
+```
+
+### Error state with helper text
+
+```tsx
+<PhoneInput
+  error
+  helperText="Please enter a valid phone number."
+  defaultValue={{ countryCode: 'VN' }}
+  onChange={(value) => console.log(value)}
+/>
+```
+
+## Related Components
+
+- [Input](../input/README.md)
+- [InputMask](../inputmask/README.md)
+- [Select](../select/README.md)
+- [Flag](../flag/README.md)
+- [FormHelperText](../formhelpertext/README.md)
+- [Primitive](../primitive/README.md)
+
+## Dependencies
+
+- phone
+- @floating-ui/react
+- lodash-es
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./phoneinput.stories.tsx)
+- [Main README](../../README.md)

package/dist/lib/popover/README.md

@@ -0,0 +1,93 @@
+# Popover
+
+A floating overlay component for displaying contextual content anchored to a trigger element. Built on top of @floating-ui/react, it supports click-to-open, dismiss-on-outside-click, and controlled/uncontrolled open state — composed via Popover, PopoverTrigger, PopoverContent, and PopoverClose sub-components.
+
+## Import
+
+```tsx
+import { Popover } from '@janbox/storefront-ui';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open` | `boolean` | - | Controlled open state of the popover. |
+| `onOpenChange` | `UseFloatingOptions['onOpenChange']` | - | Callback fired when the open state changes. Receives (open: boolean, event: Event | undefined, reason: OpenChangeReason | undefined). |
+| `placement` | `Placement` | `bottom` | Preferred placement of the floating content relative to the trigger. Accepts all @floating-ui/react Placement values (e.g. `'top'`, `'bottom'`, `'left'`, `'right'` and their `'-start'`/`'-end'` variants). |
+| `clickProps` | `UseClickProps` | `{ enabled: true }` | Options forwarded to @floating-ui/react useClick interaction hook. Enabled by default in Popover. |
+| `dismissProps` | `UseDismissProps` | `{ enabled: true }` | Options forwarded to @floating-ui/react useDismiss interaction hook (close on outside click / Escape key). Enabled by default in Popover. |
+| `hoverProps` | `UseHoverProps` | - | Options forwarded to @floating-ui/react useHover interaction hook. |
+| `focusProps` | `UseFocusProps` | - | Options forwarded to @floating-ui/react useFocus interaction hook. |
+| `offsetOptions` | `OffsetOptions` | - | Distance (in px) between the trigger and the floating content. |
+| `sizeOptions` | `SizeOptions` | - | Options for the @floating-ui/react size middleware — constrain the floating element dimensions. |
+| `autoUpdateOptions` | `AutoUpdateOptions` | - | Options passed to @floating-ui/react autoUpdate to control when the position recalculates. |
+| `elements` | `UseFloatingOptions['elements']` | - | Override the reference or floating elements used by floating-ui. |
+| `ref` | `React.Ref<FloatingRef>` | - | Ref forwarded to the underlying UseFloatingReturn object, exposing the full floating-ui context. |
+| `children` | `React.ReactNode` | - | Should contain PopoverTrigger and PopoverContent (and optionally PopoverClose inside content). |
+
+## Examples
+
+### Default (click to open, dismiss on outside click)
+
+```tsx
+<Popover>
+  <PopoverTrigger>
+    <button>Open Popover</button>
+  </PopoverTrigger>
+  <PopoverContent>
+    <p>Popover content here</p>
+    <PopoverClose>
+      <button>Close</button>
+    </PopoverClose>
+  </PopoverContent>
+</Popover>
+```
+
+### Top placement
+
+```tsx
+<Popover placement="top">
+  <PopoverTrigger>
+    <button>Open Top</button>
+  </PopoverTrigger>
+  <PopoverContent>
+    <p>Popover anchored above the trigger</p>
+  </PopoverContent>
+</Popover>
+```
+
+### Controlled open state
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Popover open={open} onOpenChange={(next) => setOpen(next)}>
+  <PopoverTrigger>
+    <button>Toggle</button>
+  </PopoverTrigger>
+  <PopoverContent>
+    <p>Controlled popover</p>
+    <PopoverClose>
+      <button onClick={() => setOpen(false)}>Close</button>
+    </PopoverClose>
+  </PopoverContent>
+</Popover>
+```
+
+## Related Components
+
+- [Floating](../floating/README.md)
+- [FloatingTrigger](../floating-trigger/README.md)
+- [FloatingContent](../floating-content/README.md)
+- [FloatingClose](../floating-close/README.md)
+
+## Dependencies
+
+- @floating-ui/react
+
+## See Also
+
+- [Component Source](./index.ts)
+- [Storybook Stories](./popover.stories.tsx)
+- [Main README](../../README.md)