@openway/ui 1.0.0 → 1.0.2

package/docs/components/modal.md

@@ -0,0 +1,293 @@
+# 📦 Modal Component (`@owa/ui`)
+
+Bộ component **Modal** hiệu năng cao, chuẩn **HTML5 Native `<dialog>`** và thiết kế theo mô hình **Pure Compound Pattern** linh hoạt.
+
+---
+
+## 🌟 Điểm nổi bật
+
+- **Native Top Layer**: Sử dụng thẻ `<dialog>` kết hợp phương thức `dialog.showModal()` của trình duyệt. Modal tự động nổi lên tầng cao nhất (`#top-layer`), không bao giờ bị cắt xén bởi phần tử cha có `overflow: hidden`, `overflow: auto` hay xung đột `z-index`.
+- **Zero Global Store**: Loại bỏ hoàn toàn Zustand / Redux / React Portal. Bạn có thể render Modal ở bất kỳ đâu trong cây JSX.
+- **Mượt mà với Exit Animation**: Tích hợp sẵn hiệu ứng mở và thoát (**Exit Animation 250ms**) cho cả hộp thoại lẫn nền mờ backdrop.
+- **Pure Compound Architecture**: Tách rời hoàn toàn giữa tầng Container (`<ModalContainer>`) và tầng giao diện (`<Modal>`, `<ModalHeader>`, `<ModalBody>`, `<ModalFooter>`, `<ModalClose>`).
+- **Tự động liên kết Context**: Nút đóng `(X)` trong `<ModalHeader>` và component `<ModalClose>` tự động kích hoạt đóng kèm Exit Animation mà không cần truyền lặp lại state `open/onClose`.
+- **Hỗ trợ Loading an toàn (`isLoading`)**: Tự động khóa đóng modal (chặn click backdrop, chặn ESC, tự động disable nút đóng và nút bọc `<ModalClose>`) khi đang trong tiến trình xử lý API/tải dữ liệu.
+- **Hỗ trợ đầy đủ Accessibility (a11y)**: Tự động khóa cuộn trang (`body scroll lock`), bắt phím `ESC`, focus trap của trình duyệt, liên kết `aria-labelledby` và `aria-describedby`.
+
+---
+
+## 🚀 Cài đặt & Import
+
+```tsx
+import {
+  ModalContainer,
+  Modal,
+  ModalHeader,
+  ModalBody,
+  ModalFooter,
+  ModalClose,
+  useModalContext,
+} from "@owa/ui";
+```
+
+---
+
+## 📖 Hướng dẫn sử dụng
+
+### 1. Cách sử dụng cơ bản (Basic Modal)
+
+```tsx
+import { useState } from "react";
+import {
+  Button,
+  ModalContainer,
+  Modal,
+  ModalHeader,
+  ModalBody,
+  ModalFooter,
+  ModalClose,
+} from "@owa/ui";
+
+export function BasicModalExample() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <div>
+      <Button onClick={() => setOpen(true)}>Mở Modal</Button>
+
+      <ModalContainer open={open} onClose={() => setOpen(false)}>
+        <Modal size="md" radius="xl">
+          <ModalHeader
+            title="Xác nhận cập nhật"
+            description="Vui lòng kiểm tra lại thông tin trước khi tiếp tục."
+          />
+          <ModalBody>
+            <p className="text-sm text-neutral-600">
+              Hệ thống sẽ lưu các thay đổi của bạn vào cơ sở dữ liệu.
+            </p>
+          </ModalBody>
+          <ModalFooter>
+            <ModalClose>
+              <Button variant="outline">Hủy bỏ</Button>
+            </ModalClose>
+            <ModalClose>
+              <Button color="primary">Đồng ý</Button>
+            </ModalClose>
+          </ModalFooter>
+        </Modal>
+      </ModalContainer>
+    </div>
+  );
+}
+```
+
+---
+
+### 2. Form nhập liệu phức tạp & Xử lý Loading (`isLoading`)
+
+Khi submit form và gọi API bất đồng bộ, chỉ cần truyền prop `isLoading={loading}` vào `<ModalContainer>`. Hệ thống sẽ tự động:
+- Chặn người dùng đóng Modal khi bấm phím `ESC` hoặc click ra ngoài vùng nền mờ `backdrop`.
+- Tự động `disabled` nút đóng `(X)` ở Header và nút bọc bên trong `<ModalClose>`.
+
+```tsx
+export function CreateUserModal({ open, onClose, onSuccess }) {
+  const [loading, setLoading] = useState(false);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setLoading(true);
+    try {
+      // 1. Gọi API lưu dữ liệu
+      await apiCreateUser();
+      onSuccess?.();
+      // 2. Đóng modal sau khi hoàn thành
+      onClose();
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <ModalContainer open={open} isLoading={loading} onClose={onClose}>
+      <Modal size="lg">
+        <ModalHeader
+          title="Tạo người dùng mới"
+          description="Điền thông tin chi tiết của thành viên mới"
+        />
+        <form onSubmit={handleSubmit}>
+          <ModalBody className="space-y-4">
+            <div>
+              <label className="block text-sm font-medium mb-1">Họ và tên</label>
+              <input required className="w-full border rounded-md px-3 py-2 text-sm" />
+            </div>
+            <div>
+              <label className="block text-sm font-medium mb-1">Email</label>
+              <input type="email" required className="w-full border rounded-md px-3 py-2 text-sm" />
+            </div>
+          </ModalBody>
+          <ModalFooter>
+            {/* Tự động disabled khi isLoading = true */}
+            <ModalClose>
+              <Button variant="outline" type="button">Hủy</Button>
+            </ModalClose>
+            <Button color="primary" type="submit" loading={loading}>
+              Lưu thành viên
+            </Button>
+          </ModalFooter>
+        </form>
+      </Modal>
+    </ModalContainer>
+  );
+}
+```
+
+---
+
+### 3. Đóng Modal lập trình qua Hook (`useModalContext`)
+
+Nếu cần thực hiện logic bất đồng bộ (validate, fetch) trong các component con nằm sâu bên trong Modal:
+
+```tsx
+import { useModalContext, Button } from "@owa/ui";
+
+function CustomAction() {
+  const { onClose, isLoading } = useModalContext();
+
+  const handleSaveAndClose = async () => {
+    await saveApi();
+    onClose?.(); // Kích hoạt animation thoát 250ms của ModalContainer
+  };
+
+  return (
+    <Button onClick={handleSaveAndClose} disabled={isLoading}>
+      Lưu và Đóng
+    </Button>
+  );
+}
+```
+
+---
+
+### 4. Tùy biến kích thước (`size`) & Bo góc (`radius`)
+
+Modal hỗ trợ 6 kích thước chiều rộng và 6 mức độ bo góc. Bạn có thể truyền `size` trực tiếp vào `<ModalContainer size="lg">` để tự động đồng bộ kích thước xuống toàn bộ các component con (`Modal`, `ModalHeader`, `ModalBody`, `ModalFooter`):
+
+> **Độ ưu tiên kích thước:** `Prop truyền trực tiếp vào component con` > `Prop size từ ModalContainer qua Context` > `Mặc định ("md")`.
+
+```tsx
+// Đồng bộ toàn bộ Modal, Header, Body, Footer thành kích thước "lg"
+<ModalContainer open={open} size="lg" onClose={() => setOpen(false)}>
+  <Modal radius="full">
+    <ModalHeader title="Modal Kích Thước Lớn (LG)" />
+    <ModalBody>...</ModalBody>
+    <ModalFooter>...</ModalFooter>
+  </Modal>
+</ModalContainer>
+```
+
+| Kích thước (`size`) | Chiều rộng (`max-w`) | Mục đích sử dụng |
+| :--- | :--- | :--- |
+| `xs` | `320px` | Thông báo ngắn gọn, prompt đơn giản |
+| `sm` | `400px` | Hộp thoại xác nhận, form 1-2 trường nhập |
+| `md` *(mặc định)* | `540px` | Form nhập liệu tiêu chuẩn |
+| `lg` | `720px` | Form nhiều cột, cắt ảnh (avatar crop) |
+| `xl` | `960px` | Xem tài liệu, bảng dữ liệu biểu mẫu |
+| `full` | `100vw` | Trải nghiệm toàn màn hình |
+
+---
+
+## 📚 Bảng tra cứu Props (API Reference)
+
+### `<ModalContainer>`
+
+Tầng Wrapper quản lý Overlay Backdrop, Native Dialog, Animation thoát và phím ESC.
+
+| Prop | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `open` | `boolean` | `false` | Trạng thái hiển thị mở/đóng Modal |
+| `onClose` | `() => void` | `undefined` | Callback khi Modal đóng (click backdrop, bấm ESC, bấm nút X) |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'` | Kích thước tổng thể đồng bộ xuống Context cho `Modal`, `ModalHeader`, `ModalBody`, `ModalFooter` |
+| `isLoading` | `boolean` | `false` | Trạng thái đang tải/xử lý. Khi `true`, sẽ chặn đóng Modal (qua click backdrop, phím ESC, nút X, `<ModalClose>`) và tự động `disabled` các nút đóng |
+| `closeOnOverlayClick` | `boolean` | `true` | Cho phép đóng Modal khi click vào lớp nền backdrop bên ngoài (bị chặn khi `isLoading = true`) |
+| `closeOnEsc` | `boolean` | `true` | Cho phép đóng Modal khi nhấn phím `ESC` trên bàn phím (bị chặn khi `isLoading = true`) |
+| `lockScroll` | `boolean` | `true` | Tự động khóa cuộn trang (`body overflow: hidden`) khi mở Modal |
+| `overlayClassName` | `string` | `""` | Class CSS tùy biến cho lớp nền backdrop mờ toàn màn hình |
+| `className` | `string` | `""` | Class CSS cho container bao ngoài dialog |
+| `children` | `ReactNode` | — | Nội dung bên trong container (thường là `<Modal>`) |
+
+---
+
+### `<Modal>`
+
+Khung giao diện hộp thoại (Dialog Box).
+
+| Prop | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'` | Kích thước chiều rộng của hộp thoại |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'rounded-lg'` | Mức độ bo góc của hộp thoại |
+| `className` | `string` | `""` | Class CSS tùy biến cho hộp thoại |
+| `ref` | `Ref<HTMLDivElement>` | `undefined` | Ref trỏ trực tiếp đến thẻ div hộp thoại |
+| `children` | `ReactNode` | — | Các component con (`<ModalHeader>`, `<ModalBody>`, `<ModalFooter>`) |
+
+---
+
+### `<ModalHeader>`
+
+Phần đầu của hộp thoại Modal.
+
+| Prop | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `title` | `ReactNode` | `undefined` | Tiêu đề chính của Modal |
+| `description` | `ReactNode` | `undefined` | Đoạn văn bản mô tả phụ bên dưới tiêu đề |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'` | Kích thước áp dụng cho tiêu đề và padding |
+| `showCloseButton` | `boolean` | `true` | Hiển thị nút đóng `(X)` ở góc trên bên phải (tự động `disabled` khi `isLoading = true`) |
+| `onClose` | `() => void` | `undefined` | Callback tùy biến khi click nút `(X)` (vẫn luôn chạy kèm animation thoát của ModalContainer) |
+| `titleClassName` | `string` | `""` | Class CSS riêng cho text tiêu đề |
+| `descriptionClassName`| `string` | `""` | Class CSS riêng cho text mô tả |
+| `closeButtonClassName`| `string` | `""` | Class CSS tùy biến nút đóng `(X)` |
+| `className` | `string` | `""` | Class CSS cho toàn bộ khối header |
+
+---
+
+### `<ModalBody>`
+
+Phần thân chứa nội dung chính (tự động bật thanh cuộn dọc khi nội dung dài).
+
+| Prop | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'` | Kích thước padding và font size (tự động kế thừa từ ModalContainer) |
+| `className` | `string` | `""` | Class CSS tùy biến cho khối body |
+| `children` | `ReactNode` | — | Nội dung form, bảng biểu, danh sách... |
+
+---
+
+### `<ModalFooter>`
+
+Phần chân trang chứa các nút hành động xác nhận hoặc hủy.
+
+| Prop | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'` | Kích thước padding và khoảng cách gap giữa các nút |
+| `className` | `string` | `""` | Class CSS cho toàn bộ khối footer |
+| `children` | `ReactNode` | — | Các nút bấm (`<Button>`, `<ModalClose>`) |
+
+---
+
+### `<ModalClose>`
+
+Wrapper bọc quanh bất kỳ nút bấm hoặc phần tử nào bên trong Modal (ví dụ: nút Hủy bỏ trong Footer). Khi click, `<ModalClose>` sẽ tự động kích hoạt hiệu ứng đóng mượt mà (**Exit Animation 250ms**) trước khi unmount (tự động `disabled` khi `isLoading = true`).
+
+```tsx
+<ModalFooter>
+  {/* asChild=true (mặc định) sẽ ghép thẳng sự kiện vào Button mà không sinh thêm thẻ div thừa */}
+  <ModalClose>
+    <Button variant="outline">Hủy bỏ</Button>
+  </ModalClose>
+  <Button color="primary" onClick={handleSave}>Lưu thay đổi</Button>
+</ModalFooter>
+```
+
+| Prop | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `children` | `ReactNode` | — | Nút bấm hoặc phần tử con cần kích hoạt sự kiện đóng |
+| `asChild` | `boolean` | `true` | Truyền thẳng sự kiện `onClick` và prop `disabled` vào phần tử con thay vì bọc ngoài bằng thẻ `div` |

package/docs/components/popover.md

@@ -0,0 +1,255 @@
+# 💬 Popover Component (`@owa/ui`)
+
+Bộ component **Popover** (hộp thoại nổi tương tác) xây dựng theo mô hình **Compound Component** trên nền tảng **`@floating-ui/react`**, hỗ trợ **chuẩn WAI-ARIA Dialog**, **quản lý tiêu điểm thông minh (FloatingFocusManager)**, **tự động căn vị trí thông minh (flip/shift/offset)**, và tương thích hoàn toàn với **React 19 / React Compiler**.
+
+---
+
+## 🌟 Điểm nổi bật
+
+- **Compound Component Pattern**: Cấu trúc module rõ ràng gồm `<Popover>`, `<PopoverTrigger>`, `<PopoverContent>`, `<PopoverHeader>`, `<PopoverBody>`, `<PopoverFooter>`, `<PopoverClose>`.
+- **Hỗ trợ React 19 & React Compiler**: Áp dụng mô hình `Slot` component trên cả `PopoverTrigger` và `PopoverClose`, đảm bảo xử lý `ref` sạch sẽ và an toàn tuyệt đối khi render.
+- **Quản lý tiêu điểm (Focus Management)**: Tích hợp `FloatingFocusManager`, tự động bẫy/khóa focus bên trong popover khi ở chế độ `modal={true}` và khôi phục focus về trigger khi đóng.
+- **Hệ thống z-index đồng bộ**: Sử dụng `DEFAULT_Z_INDEX.POPOVER` (mặc định `50`) từ hệ thống constants của `@owa/ui`.
+- **Luôn nổi trên cùng (Floating Portal)**: Nội dung popover luôn được gắn vào `<FloatingPortal>`, không bị ảnh hưởng bởi layout cha hay `overflow: hidden`.
+- **Safe Config Fallback**: Tích hợp hàm `getSafeConfig` giúp các subcomponents (`PopoverContent`, `PopoverHeader`, `PopoverBody`, `PopoverFooter`) lấy an toàn cấu hình `sizeConfig` và `radiusConfig`.
+- **WAI-ARIA Accessibility**:
+  - `role="dialog"` cho popover container.
+  - `aria-expanded`, `aria-haspopup="dialog"`.
+  - Tự động đóng khi nhấn phím `Escape` (`closeOnEsc`) hoặc click ra ngoài (`closeOnClickOutside`).
+- **Tùy biến linh hoạt**:
+  - 5 kích cỡ: `xs`, `sm`, `md` (*mặc định*), `lg`, `xl`.
+  - 6 cấp độ bo góc: `none`, `sm`, `md` (*mặc định*), `lg`, `xl`, `full`.
+  - 2 cơ chế kích hoạt: `click` (*mặc định*) hoặc `hover` (hỗ trợ `safePolygon` giúp di chuột mượt mà sang popover).
+
+---
+
+## 🚀 Cài đặt & Import
+
+```tsx
+import {
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+  PopoverHeader,
+  PopoverBody,
+  PopoverFooter,
+  PopoverClose,
+} from "@owa/ui";
+import type {
+  PopoverProps,
+  PopoverTriggerProps,
+  PopoverContentProps,
+  PopoverHeaderProps,
+  PopoverBodyProps,
+  PopoverFooterProps,
+  PopoverCloseProps,
+  PopoverPlacement,
+  PopoverTriggerType,
+  PopoverSize,
+  PopoverRadius,
+  PopoverColor,
+} from "@owa/ui";
+```
+
+---
+
+## 📖 Hướng dẫn sử dụng
+
+### 1. Popover cơ bản (Form nhập liệu / Bộ lọc)
+
+```tsx
+import {
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+  PopoverHeader,
+  PopoverBody,
+  PopoverFooter,
+  PopoverClose,
+  Button,
+} from "@owa/ui";
+
+export function BasicPopover() {
+  return (
+    <Popover placement="bottom-start" size="md">
+      <PopoverTrigger>
+        <Button variant="outline">Mở bộ lọc</Button>
+      </PopoverTrigger>
+      <PopoverContent minWidth={280}>
+        <PopoverHeader>Bộ lọc nâng cao</PopoverHeader>
+        <PopoverBody>
+          <div className="space-y-3">
+            <div>
+              <label className="block text-xs font-medium text-neutral-600 mb-1">Từ khóa</label>
+              <input
+                type="text"
+                placeholder="Nhập từ khóa..."
+                className="w-full px-2.5 py-1.5 border border-neutral-300 rounded text-sm outline-none focus:border-primary-500"
+              />
+            </div>
+            <div>
+              <label className="block text-xs font-medium text-neutral-600 mb-1">Trạng thái</label>
+              <select className="w-full px-2.5 py-1.5 border border-neutral-300 rounded text-sm outline-none focus:border-primary-500">
+                <option value="all">Tất cả</option>
+                <option value="active">Đang hoạt động</option>
+                <option value="inactive">Đã tạm dừng</option>
+              </select>
+            </div>
+          </div>
+        </PopoverBody>
+        <PopoverFooter className="flex justify-end gap-2">
+          <PopoverClose asChild>
+            <Button variant="ghost" size="sm">Hủy</Button>
+          </PopoverClose>
+          <Button size="sm">Áp dụng</Button>
+        </PopoverFooter>
+      </PopoverContent>
+    </Popover>
+  );
+}
+```
+
+---
+
+### 2. Tùy biến Trigger với `asChild`
+
+```tsx
+import { Popover, PopoverTrigger, PopoverContent, PopoverBody, IconButton } from "@owa/ui";
+import { InfoIcon } from "@/components/icons";
+
+export function InfoPopover() {
+  return (
+    <Popover trigger="hover" placement="top">
+      <PopoverTrigger asChild>
+        <IconButton icon={<InfoIcon />} aria-label="Xem giải thích" variant="ghost" size="sm" />
+      </PopoverTrigger>
+      <PopoverContent maxWidth={320}>
+        <PopoverBody>
+          <p className="text-xs text-neutral-600 leading-relaxed">
+            Dữ liệu này được tự động đồng bộ từ máy chủ mỗi 5 phút một lần.
+          </p>
+        </PopoverBody>
+      </PopoverContent>
+    </Popover>
+  );
+}
+```
+
+---
+
+### 3. Kích hoạt bằng Hover (`trigger="hover"`)
+
+Với chế độ `hover`, Popover tích hợp thuật toán `safePolygon()` của Floating UI, cho phép người dùng di chuyển con trỏ chuột theo đường chéo từ trigger sang khung popover mà không bị tắt đột ngột:
+
+```tsx
+<Popover trigger="hover" placement="bottom">
+  <PopoverTrigger>
+    <Button variant="soft">Rê chuột xem chi tiết</Button>
+  </PopoverTrigger>
+  <PopoverContent>
+    <PopoverBody>
+      <p className="text-sm">Nội dung chi tiết được hiển thị khi hover!</p>
+    </PopoverBody>
+  </PopoverContent>
+</Popover>
+```
+
+---
+
+### 4. Chế độ Modal Popover (`modal={true}`)
+
+Khi bật `modal={true}`, Popover sẽ khóa toàn bộ tương tác bên ngoài và bẫy phím `Tab` chỉ tuần hoàn bên trong nội dung của Popover:
+
+```tsx
+<Popover modal={true} placement="bottom-start">
+  <PopoverTrigger>
+    <Button color="error">Xóa dữ liệu quan trọng</Button>
+  </PopoverTrigger>
+  <PopoverContent minWidth={300}>
+    <PopoverHeader>Xác nhận xóa</PopoverHeader>
+    <PopoverBody>
+      <p className="text-sm text-neutral-700">
+        Bạn có chắc chắn muốn xóa bản ghi này? Hành động này không thể hoàn tác.
+      </p>
+    </PopoverBody>
+    <PopoverFooter className="flex justify-end gap-2">
+      <PopoverClose asChild>
+        <Button variant="outline" size="sm">Hủy</Button>
+      </PopoverClose>
+      <Button color="error" size="sm">Đồng ý xóa</Button>
+    </PopoverFooter>
+  </PopoverContent>
+</Popover>
+```
+
+---
+
+## ♿ Khả năng truy cập & Điều hướng bàn phím
+
+| Phím bấm | Hành vi |
+| :--- | :--- |
+| `Enter` / `Space` | Kích hoạt mở hoặc đóng popover khi đang focus tại trigger. |
+| `Tab` | Di chuyển focus tuần tự qua các phần tử tương tác (inputs, buttons) bên trong popover. |
+| `Shift + Tab` | Di chuyển ngược lại phần tử tương tác trước đó trong popover. |
+| `Escape` | Đóng popover và tự động khôi phục focus về lại trigger element. |
+
+---
+
+## 📋 API Reference
+
+### `<Popover>` (Root Component)
+
+| Prop | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `children` | `ReactNode` | — | Các subcomponents (`PopoverTrigger`, `PopoverContent`). |
+| `open` | `boolean` | — | Trạng thái mở popover (chế độ Controlled). |
+| `defaultOpen` | `boolean` | `false` | Trạng thái mở ban đầu (chế độ Uncontrolled). |
+| `onOpenChange` | `(open: boolean) => void` | — | Callback khi trạng thái mở/đóng thay đổi. |
+| `trigger` | `'click' \| 'hover'` | `'click'` | Kiểu kích hoạt mở popover. |
+| `placement` | `PopoverPlacement` | `'bottom'` | Hướng hiển thị của popover so với trigger. |
+| `offset` | `number` | `8` | Khoảng cách (px) giữa trigger và popover. |
+| `flip` | `boolean` | `true` | Tự động đảo hướng khi popover bị tràn mép màn hình. |
+| `shift` | `boolean` | `true` | Tự động dịch chuyển popover để không bị che khuất. |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Kích thước áp dụng cho padding/font của popover. |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'` | Độ bo góc của khung popover. |
+| `color` | `PopoverColor` | `'neutral'` | Tông màu chủ đề của popover. |
+| `disabled` | `boolean` | `false` | Vô hiệu hóa toàn bộ Popover. |
+| `animated` | `boolean` | `true` | Bật/tắt hiệu ứng chuyển động khi mở/đóng. |
+| `animationDuration` | `number` | `150` | Thời lượng hiệu ứng (ms). |
+| `modal` | `boolean` | `false` | Khóa tiêu điểm bên trong popover và ngăn tương tác nền ngoài. |
+| `closeOnEsc` | `boolean` | `true` | Đóng popover khi nhấn phím `Escape`. |
+| `closeOnClickOutside` | `boolean` | `true` | Đóng popover khi click ra ngoài. |
+
+---
+
+### `<PopoverTrigger>`
+
+| Prop | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `children` | `ReactNode` | — | Phần tử con làm trigger. |
+| `asChild` | `boolean` | `false` | Truyền trực tiếp props/events vào phần tử con thay vì bọc button mặc định. |
+| `className` | `string` | `""` | Class CSS tùy biến bổ sung. |
+| `ref` | `Ref<HTMLElement>` | — | React 19 Ref trực tiếp vào trigger element. |
+
+---
+
+### `<PopoverContent>`
+
+| Prop | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `children` | `ReactNode` | — | Nội dung bên trong popover. |
+| `minWidth` | `string \| number` | — | Độ rộng tối thiểu của popover. |
+| `maxWidth` | `string \| number` | — | Độ rộng tối đa của popover. |
+| `zIndex` | `number` | `DEFAULT_Z_INDEX.POPOVER` (50) | Thứ tự z-index của popover nổi. |
+| `className` | `string` | `""` | Class CSS tùy biến bổ sung. |
+| `style` | `CSSProperties` | — | Style inline tùy biến bổ sung. |
+| `ref` | `Ref<HTMLDivElement>` | — | React 19 Ref trực tiếp vào content container. |
+
+---
+
+### `<PopoverHeader>`, `<PopoverBody>`, `<PopoverFooter>`, `<PopoverClose>`
+
+- `<PopoverHeader>`: Tiêu đề của popover (chuẩn WAI-ARIA `<h2>` ngữ nghĩa dialog).
+- `<PopoverBody>`: Phần thân chính chứa văn bản, inputs hoặc controls.
+- `<PopoverFooter>`: Chân trang chứa các nút hành động (Cancel, Submit).
+- `<PopoverClose>`: Nút kích hoạt đóng popover (hỗ trợ `asChild` để gắn vào bất kỳ component Button tùy ý).