@openway/ui 1.0.0 → 1.0.2

package/docs/components/collapse.md

@@ -0,0 +1,318 @@
+# 🗂️ Collapse Component (`@owa/ui`)
+
+Component **Collapse** (Accordion / Collapsible panel) hiện đại, hiệu năng cao, thiết kế chuẩn **Declarative Compound Components Pattern** (`<Collapse>`, `<CollapsePanel>`, `<CollapseHeader>`, `<CollapseContent>`, `<Collapsible>`), tích hợp **CSS Grid Height Transition**, **Accordion Mode**, **Custom Slots & Subcomponents**, **Safe Config Fallback** (`getSafeConfig`) và tuân thủ đầy đủ tiêu chuẩn **WAI-ARIA Accessibility**.
+
+---
+
+## 🌟 Điểm nổi bật
+
+- **Compound Components Pattern chuẩn chỉ**: Tách biệt rõ ràng `<Collapse>`, `<CollapsePanel>`, `<CollapseHeader>`, `<CollapseContent>`, hỗ trợ 2 phong cách viết linh hoạt (khai báo nhanh qua Props hoặc tùy biến sâu qua Subcomponents).
+- **Hiệu ứng gập mở siêu mượt (CSS Grid Transition)**: Sử dụng kỹ thuật chuyển đổi `transition-[grid-template-rows]` (`grid-rows-[1fr]` khi mở và `grid-rows-[0fr]` khi đóng), tự động tính toán chiều cao nội dung động mà không cần đo đạc DOM bằng JavaScript.
+- **Chế độ Accordion & Multiple Open**:
+  - `accordion={true}`: Tự động đóng các panel khác khi mở một panel mới.
+  - `accordion={false}`: Cho phép mở nhiều panel đồng thời.
+- **Chế độ Controlled & Uncontrolled**:
+  - **Controlled**: Quản lý bằng `activeKey` + callback `onChange`.
+  - **Uncontrolled**: Tự quản lý nội bộ với `defaultActiveKey`.
+- **5 Biến thể giao diện (`variant`)**:
+  - `outlined` (*mặc định*): Khung viền ngoài và các đường kẻ phân cách mang màu sắc chủ đề.
+  - `filled`: Khối nền mang màu sắc chủ đề nhẹ tạo cảm giác liền mạch.
+  - `ghost`: Trong suốt, không viền ngoài tối giản.
+  - `separated`: Mỗi panel là một thẻ card riêng biệt cách nhau bởi khoảng trống `space-y-3`.
+  - `other`: Không áp dụng style mặc định, tự do tùy biến qua `className`.
+- **3 Kích thước tiêu chuẩn (`size`)**: `sm`, `md` (*mặc định*), `lg`.
+- **7 Chủ đề màu sắc (`color`)**: `primary`, `secondary`, `neutral`, `error`, `success`, `warning`, `info`.
+- **6 Kiểu bo góc (`radius`)**: `none`, `sm`, `md` (*mặc định*), `lg`, `xl`, `full`.
+- **Tùy biến icon & vị trí mũi tên (`expandIconPosition`)**:
+  - `expandIconPosition`: `"right"` (*mặc định*), `"left"`, hoặc `"none"`.
+  - `expandIcon`: Tùy biến icon hoặc render function `({ isActive, disabled }) => ReactNode`.
+- **Extra Slot & Hành động phụ**: Hỗ trợ truyền badge, nút bấm, icon action (`extra`) vào header mà không kích hoạt sự kiện toggle của header.
+- **Giải phóng bộ nhớ (`destroyInactivePanel`)**: Tự động unmount nội dung khỏi DOM khi panel bị đóng.
+- **Component độc lập `<Collapsible>`**: Cung cấp khung gập mở độc lập nhẹ nhàng cho bất kỳ nội dung nào.
+- **WAI-ARIA Accessibility & Bàn phím**: Tự động gắn `role="region"`, `aria-expanded`, `aria-controls`, `aria-labelledby`, hỗ trợ đầy đủ phím `Enter` và `Space`.
+- **Safe Config Fallback**: Tích hợp `getSafeConfig` từ `@/utils/function` đảm bảo an toàn tuyệt đối, không crash ứng dụng khi truyền prop không hợp lệ.
+
+---
+
+## 🚀 Cài đặt & Import
+
+```tsx
+import {
+  Collapse,
+  CollapsePanel,
+  CollapseHeader,
+  CollapseContent,
+  Collapsible,
+  useCollapseContext,
+  useCollapsePanelContext,
+  collapseSizeConfig,
+  collapseRadiusConfig,
+  collapseVariantContainerConfig,
+  collapseVariantPanelConfig,
+  collapseVariantHeaderConfig,
+  collapseColorConfig,
+} from "@owa/ui";
+
+import type {
+  CollapseProps,
+  CollapsePanelProps,
+  CollapseHeaderProps,
+  CollapseContentProps,
+  CollapsibleProps,
+  CollapseSize,
+  CollapseVariant,
+  CollapseColor,
+  CollapseRadius,
+  CollapseExpandIconPosition,
+  CollapseActiveKey,
+} from "@owa/ui";
+```
+
+---
+
+## 📖 Hướng dẫn sử dụng
+
+### 1. Cách 1: Khai báo nhanh qua Props (Declarative Panel Props)
+
+Phù hợp cho hầu hết các trường hợp thông dụng:
+
+```tsx
+import { Collapse, CollapsePanel } from "@owa/ui";
+
+export function BasicCollapse() {
+  return (
+    <Collapse defaultActiveKey={["1"]} variant="outlined" color="primary">
+      <CollapsePanel
+        value="1"
+        label="1. Giới thiệu tổng quan"
+        description="Thông tin nền tảng và kiến trúc hệ thống"
+      >
+        <p className="text-neutral-600">
+          Đây là nội dung chi tiết của panel đầu tiên.
+        </p>
+      </CollapsePanel>
+
+      <CollapsePanel value="2" label="2. Hướng dẫn cài đặt nhanh">
+        <p className="text-neutral-600">
+          Chạy lệnh <code>pnpm add @owa/ui</code> để bắt đầu sử dụng.
+        </p>
+      </CollapsePanel>
+
+      <CollapsePanel value="3" label="3. Câu hỏi thường gặp" disabled>
+        <p className="text-neutral-600">
+          Panel này đang bị vô hiệu hóa.
+        </p>
+      </CollapsePanel>
+    </Collapse>
+  );
+}
+```
+
+---
+
+### 2. Cách 2: Tùy biến sâu qua Subcomponents (`<CollapseHeader>` & `<CollapseContent>`)
+
+Cho phép bạn tự do composition cấu trúc giao diện phức tạp:
+
+```tsx
+import { Collapse, CollapsePanel, CollapseHeader, CollapseContent } from "@owa/ui";
+import { Badge, Button } from "@owa/ui";
+
+export function CustomSlotCollapse() {
+  return (
+    <Collapse variant="separated">
+      <CollapsePanel value="order-101">
+        <CollapseHeader
+          extra={
+            <div className="flex items-center gap-2">
+              <Badge color="success">Đã thanh toán</Badge>
+              <Button size="sm" variant="ghost">In hóa đơn</Button>
+            </div>
+          }
+        >
+          <span className="font-bold text-neutral-900">
+            Đơn hàng #101 - $149.00
+          </span>
+        </CollapseHeader>
+        <CollapseContent>
+          <div className="space-y-2">
+            <p>Khách hàng: Nguyễn Văn A</p>
+            <p>Địa chỉ: 123 Đường Lê Lợi, Q.1, TP.HCM</p>
+          </div>
+        </CollapseContent>
+      </CollapsePanel>
+    </Collapse>
+  );
+}
+```
+
+---
+
+### 3. Chế độ Accordion (Chỉ mở 1 panel tại một thời điểm)
+
+```tsx
+<Collapse accordion defaultActiveKey="faq-1" color="primary">
+  <CollapsePanel value="faq-1" label="Làm sao để đổi mật khẩu?">
+    <p>Truy cập mục Cài đặt tài khoản và chọn Đổi mật khẩu.</p>
+  </CollapsePanel>
+  <CollapsePanel value="faq-2" label="Chính sách hoàn tiền như thế nào?">
+    <p>Chúng tôi hoàn tiền 100% trong vòng 30 ngày đầu tiên.</p>
+  </CollapsePanel>
+</Collapse>
+```
+
+---
+
+### 4. Các biến thể giao diện (`variant`)
+
+```tsx
+{/* 1. Outlined (Mặc định) */}
+<Collapse variant="outlined">...</Collapse>
+
+{/* 2. Filled */}
+<Collapse variant="filled">...</Collapse>
+
+{/* 3. Ghost (Tối giản) */}
+<Collapse variant="ghost">...</Collapse>
+
+{/* 4. Separated (Thẻ card rời rạc) */}
+<Collapse variant="separated">...</Collapse>
+```
+
+---
+
+### 5. Chế độ điều khiển chủ động (Controlled Mode)
+
+```tsx
+import { useState } from "react";
+import { Collapse, CollapsePanel } from "@owa/ui";
+
+export function ControlledCollapse() {
+  const [activeKeys, setActiveKeys] = useState<string | number | (string | number)[]>(["1"]);
+
+  return (
+    <div>
+      <div className="flex gap-2 mb-3">
+        <button onClick={() => setActiveKeys(["1"])} className="px-3 py-1 bg-primary-600 text-white rounded">
+          Mở Panel 1
+        </button>
+        <button onClick={() => setActiveKeys(["1", "2"])} className="px-3 py-1 bg-primary-600 text-white rounded">
+          Mở cả 1 và 2
+        </button>
+        <button onClick={() => setActiveKeys([])} className="px-3 py-1 bg-neutral-600 text-white rounded">
+          Đóng tất cả
+        </button>
+      </div>
+
+      <Collapse activeKey={activeKeys} onChange={setActiveKeys}>
+        <CollapsePanel value="1" label="Panel 1">Nội dung 1</CollapsePanel>
+        <CollapsePanel value="2" label="Panel 2">Nội dung 2</CollapsePanel>
+      </Collapse>
+    </div>
+  );
+}
+```
+
+---
+
+### 6. Sử dụng component gập mở độc lập `<Collapsible>`
+
+```tsx
+import { useState } from "react";
+import { Collapsible, Button } from "@owa/ui";
+
+export function CollapsibleDemo() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <div className="border p-4 rounded-xl">
+      <Button onClick={() => setOpen(!open)}>
+        {open ? "Thu gọn chi tiết" : "Xem thêm chi tiết"}
+      </Button>
+
+      <Collapsible open={open} className="mt-3">
+        <div className="p-3 bg-neutral-50 rounded-lg">
+          Nội dung mở rộng linh hoạt không cần nằm trong Collapse list.
+        </div>
+      </Collapsible>
+    </div>
+  );
+}
+```
+
+---
+
+## 📊 Bảng thuộc tính Props
+
+### `<Collapse>`
+
+| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `activeKey` | `string \| number \| (string \| number)[]` | - | Khóa các panel đang mở (Controlled mode) |
+| `defaultActiveKey` | `string \| number \| (string \| number)[]` | - | Khóa các panel mở ban đầu (Uncontrolled mode) |
+| `onChange` | `(activeKey) => void` | - | Callback kích hoạt khi trạng thái mở/đóng thay đổi |
+| `accordion` | `boolean` | `false` | Chế độ chỉ mở tối đa 1 panel |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Kích thước hiển thị |
+| `variant` | `"outlined" \| "filled" \| "ghost" \| "separated" \| "other"` | `"outlined"` | Biến thể kiểu dáng giao diện |
+| `color` | `"primary" \| "secondary" \| "neutral" \| "error" \| "success" \| "warning" \| "info"` | `"primary"` | Chủ đề màu sắc |
+| `radius` | `"none" \| "sm" \| "md" \| "lg" \| "xl" \| "full"` | `"md"` | Tùy chỉnh bo góc |
+| `expandIconPosition` | `"left" \| "right" \| "none"` | `"right"` | Vị trí icon mũi tên |
+| `expandIcon` | `ReactNode \| ((props) => ReactNode)` | - | Custom icon mũi tên |
+| `destroyInactivePanel`| `boolean` | `false` | Tự động unmount nội dung DOM khi panel đóng |
+| `children` | `ReactNode` | - | Danh sách các `<CollapsePanel>` |
+
+---
+
+### `<CollapsePanel>`
+
+| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `value` | `string \| number` | **Bắt buộc** | Khóa định danh duy nhất của panel |
+| `label` | `ReactNode` | - | Tiêu đề panel (khi dùng cách khai báo nhanh) |
+| `description` | `ReactNode` | - | Phụ đề mô tả ngắn |
+| `startIcon` | `ReactNode` | - | Icon đặt phía trước tiêu đề |
+| `extra` | `ReactNode` | - | Nội dung phụ bên phải (badge, action) |
+| `disabled` | `boolean` | `false` | Vô hiệu hóa panel |
+| `showArrow` | `boolean` | `true` | Hiển thị icon mũi tên |
+| `destroyInactivePanel`| `boolean` | - | Ghi đè cấu hình unmount cho riêng panel này |
+| `children` | `ReactNode` | - | Nội dung body hoặc `<CollapseHeader>` & `<CollapseContent>` |
+
+---
+
+### `<CollapseHeader>`
+
+| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `startIcon` | `ReactNode` | - | Icon đặt phía trước tiêu đề |
+| `description` | `ReactNode` | - | Phụ đề mô tả |
+| `extra` | `ReactNode` | - | Vùng hành động phụ bên phải |
+| `showArrow` | `boolean` | `true` | Hiển thị mũi tên mở rộng |
+| `children` | `ReactNode` | - | Nội dung tiêu đề JSX |
+
+---
+
+### `<CollapseContent>`
+
+| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `destroyInactivePanel`| `boolean` | - | Tự động gỡ nội dung khỏi DOM khi đóng |
+| `children` | `ReactNode` | - | Nội dung chi tiết bên trong panel |
+
+---
+
+## ⌨️ Phím tắt & Trợ năng (Accessibility)
+
+- **`role="region"`**: Thẻ nội dung được đánh dấu là vùng nội dung bổ sung.
+- **`aria-expanded` & `aria-controls`**: Nút Header tự động đồng bộ trạng thái đóng/mở với ID của Content panel.
+- **Phím `Enter` / `Space`**: Nhấn để đóng hoặc mở panel khi đang focus vào tiêu đề.
+- **Ngăn chặn xung đột sự kiện**: Vùng `extra` được tách biệt bên ngoài thẻ `<button>` trigger để tránh lỗi nested interactive element.
+
+---
+
+## 🧪 Kiểm thử Component (Cypress Testing)
+
+Component được kiểm thử 100% bằng **Cypress Component Testing** tại [`Collapse.cy.tsx`](Collapse.cy.tsx):
+
+```bash
+pnpm --filter @owa/ui cypress:run --spec "src/components/collapse/Collapse.cy.tsx"
+```

package/docs/components/confirm.md

@@ -0,0 +1,322 @@
+# 📦 Confirm Component (`@owa/ui`)
+
+Bộ component **Confirm** (Hộp thoại xác nhận) 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. Confirm 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 Confirm ở 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 300ms**) 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 (`<ConfirmContainer>`) và tầng giao diện (`<Confirm>`, `<ConfirmHeader>`, `<ConfirmBody>`, `<ConfirmFooter>`, `<ConfirmClose>`).
+- **Tự động liên kết Context**: Nút đóng `(X)` trong `<ConfirmHeader>` và component `<ConfirmClose>` 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 `(X)`, nút Hủy và nút bọc `<ConfirmClose>`) 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 {
+  ConfirmContainer,
+  Confirm,
+  ConfirmHeader,
+  ConfirmBody,
+  ConfirmFooter,
+  ConfirmClose,
+  useConfirmContext,
+} from "@owa/ui";
+```
+
+---
+
+## 📖 Hướng dẫn sử dụng
+
+### 1. Cách sử dụng cơ bản (Pure Compound Pattern)
+
+```tsx
+import { useState } from "react";
+import {
+  Button,
+  ConfirmContainer,
+  Confirm,
+  ConfirmHeader,
+  ConfirmBody,
+  ConfirmFooter,
+} from "@owa/ui";
+
+export function BasicConfirmExample() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <div>
+      <Button color="error" onClick={() => setOpen(true)}>
+        Xóa mục này
+      </Button>
+
+      <ConfirmContainer open={open} size="md" color="error" onClose={() => setOpen(false)}>
+        <Confirm>
+          <ConfirmHeader title="Xác nhận xóa dữ liệu?" />
+          <ConfirmBody>
+            Hành động này không thể hoàn tác. Bạn có chắc chắn muốn xóa không?
+          </ConfirmBody>
+          <ConfirmFooter
+            confirmText="Xóa vĩnh viễn"
+            cancelText="Hủy bỏ"
+            onConfirm={() => {
+              console.log("Đã xóa!");
+              setOpen(false);
+            }}
+            onCancel={() => setOpen(false)}
+          />
+        </Confirm>
+      </ConfirmContainer>
+    </div>
+  );
+}
+```
+
+---
+
+### 2. Xử lý bất đồng bộ & Khóa an toàn (`isLoading`)
+
+Khi xử lý logic bất đồng bộ (API call) trong `onConfirm`, bạn có thể truyền hàm async cho `onConfirm` trên `<ConfirmFooter>` hoặc kiểm soát prop `isLoading={loading}` trên `<ConfirmContainer>`:
+
+```tsx
+import { useState } from "react";
+import {
+  Button,
+  ConfirmContainer,
+  Confirm,
+  ConfirmHeader,
+  ConfirmBody,
+  ConfirmFooter,
+} from "@owa/ui";
+
+export function AsyncConfirmExample() {
+  const [open, setOpen] = useState(false);
+
+  const handleConfirmAction = async () => {
+    // Tự động bật Spinner và khóa tương tác trong suốt thời gian API chạy
+    await apiDeleteResource();
+    setOpen(false);
+  };
+
+  return (
+    <div>
+      <Button onClick={() => setOpen(true)}>Xóa tài khoản</Button>
+
+      <ConfirmContainer open={open} color="error" onClose={() => setOpen(false)}>
+        <Confirm>
+          <ConfirmHeader title="Xác nhận xóa tài khoản" />
+          <ConfirmBody>
+            Quá trình này có thể mất vài giây để hoàn tất dọn dẹp dữ liệu.
+          </ConfirmBody>
+          <ConfirmFooter
+            confirmText="Xóa tài khoản"
+            onConfirm={handleConfirmAction}
+            onCancel={() => setOpen(false)}
+          />
+        </Confirm>
+      </ConfirmContainer>
+    </div>
+  );
+}
+```
+
+Khi đang loading:
+- Người dùng bấm phím `ESC` sẽ **bị chặn**.
+- Click ra ngoài vùng backdrop overlay sẽ **bị chặn**.
+- Nút đóng `(X)` và nút `Hủy` tự động bị **vô hiệu hóa (`disabled`)**.
+- Nút `Xác nhận` hiển thị Spinner loading.
+
+---
+
+### 3. Thiết kế Compound Components tùy biến linh hoạt
+
+Bạn có thể tự do tùy biến giao diện bên trong Confirm bằng các sub-component:
+
+```tsx
+import {
+  ConfirmContainer,
+  Confirm,
+  ConfirmHeader,
+  ConfirmBody,
+  ConfirmFooter,
+  ConfirmClose,
+  Button,
+} from "@owa/ui";
+
+export function CompoundConfirmExample({ open, onClose }) {
+  return (
+    <ConfirmContainer open={open} size="lg" color="warning" onClose={onClose}>
+      <Confirm>
+        <ConfirmHeader title="Cảnh báo cập nhật hệ thống" showCloseButton />
+        <ConfirmBody>
+          <div className="space-y-3">
+            <p className="text-sm text-neutral-600">
+              Một số dịch vụ có thể tạm ngưng trong ít phút khi bảo trì.
+            </p>
+            <div className="p-3 bg-warning-50 border border-warning-200 rounded-md text-xs text-warning-800">
+              ⚠️ Vui lòng lưu lại công việc hiện tại trước khi tiếp tục.
+            </div>
+          </div>
+        </ConfirmBody>
+        <ConfirmFooter>
+          {/* ConfirmClose tự động đóng kèm Exit Animation */}
+          <ConfirmClose>
+            <Button variant="outline">Để sau</Button>
+          </ConfirmClose>
+          <Button color="warning" onClick={() => proceedUpdate()}>
+            Bắt đầu cập nhật
+          </Button>
+        </ConfirmFooter>
+      </Confirm>
+    </ConfirmContainer>
+  );
+}
+```
+
+---
+
+### 4. Đóng Confirm lập trình qua Hook (`useConfirmContext`)
+
+```tsx
+import { useConfirmContext, Button } from "@owa/ui";
+
+function CustomChildAction() {
+  const { onClose, isLoading } = useConfirmContext();
+
+  return (
+    <Button onClick={onClose} disabled={isLoading}>
+      Đóng hộp thoại
+    </Button>
+  );
+}
+```
+
+---
+
+### 5. Tùy biến Kích thước (`size`), Chủ đề màu (`color`) & Bo góc (`radius`)
+
+Confirm hỗ trợ 5 kích thước chiều rộng và 7 chủ đề màu sắc:
+
+| Kích thước (`size`) | Chiều rộng (`max-w`) |
+| :--- | :--- |
+| `xs` | `320px` |
+| `sm` | `380px` |
+| `md` *(mặc định)* | `440px` |
+| `lg` | `520px` |
+| `xl` | `600px` |
+
+Chủ đề màu (`color`):
+- `primary`, `secondary`, `neutral`, `error`, `success`, `warning` *(mặc định)*, `info`.
+
+Độ ưu tiên truyền props:
+> **`Prop truyền trực tiếp vào component con`** > **`Prop size / color từ ConfirmContainer qua Context`** > **`Mặc định ("md" / "warning")`**.
+
+---
+
+## 📚 Bảng tra cứu Props (API Reference)
+
+### `<ConfirmContainer>`
+
+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 Confirm |
+| `onClose` | `() => void` | `undefined` | Callback khi Confirm đóng (click backdrop, bấm ESC, bấm nút X) |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Kích thước tổng thể của Confirm (truyền xuống context để đồng bộ kích thước cho Confirm, Header, Body, Footer) |
+| `color` | `'primary' \| 'secondary' \| 'neutral' \| 'error' \| 'success' \| 'warning' \| 'info'` | `'warning'` | Chủ đề màu sắc tổng thể (truyền xuống context để đồng bộ cho Confirm, Header, Footer) |
+| `isLoading` | `boolean` | `false` | Trạng thái đang tải/xử lý. Khi `true`, sẽ chặn đóng Confirm và tự động `disabled` các nút đóng |
+| `closeOnOverlayClick` | `boolean` | `true` | Cho phép đóng Confirm 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 Confirm 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ở Confirm |
+| `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à `<Confirm>`) |
+
+---
+
+### `<Confirm>`
+
+Khung giao diện hộp thoại xác nhận (Pure Compound Dialog Box).
+
+| Prop | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | *Kế thừa từ ConfirmContainer* | 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 |
+| `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 sub-component con (`<ConfirmHeader>`, `<ConfirmBody>`, `<ConfirmFooter>`) |
+
+---
+
+### `<ConfirmHeader>`
+
+Phần đầu của hộp thoại Confirm (hiển thị icon badge, tiêu đề và nút đóng X).
+
+| Prop | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `title` | `ReactNode` | `undefined` | Tiêu đề chính của Confirm |
+| `icon` | `ReactNode \| boolean` | `true` | Icon hiển thị cạnh tiêu đề (`true` để lấy theo màu, `false` để ẩn) |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | *Kế thừa từ Context* | Kích thước áp dụng cho tiêu đề, icon và padding |
+| `color` | `'primary' \| 'secondary' \| ...` | *Kế thừa từ Context* | Chủ đề màu sắc cho icon badge |
+| `showCloseButton` | `boolean` | `false` | 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 khi click nút `(X)` (tự động kích hoạt Exit Animation của ConfirmContainer) |
+| `iconClassName` | `string` | `""` | Class CSS riêng cho container icon badge |
+| `titleClassName` | `string` | `""` | Class CSS riêng cho text tiêu đề |
+| `closeButtonClassName`| `string` | `""` | Class CSS tùy biến nút đóng `(X)` |
+| `className` | `string` | `""` | Class CSS cho toàn bộ khối header |
+| `children` | `ReactNode` | `undefined` | Nội dung tùy biến bên trong header |
+
+---
+
+### `<ConfirmBody>`
+
+Phần thân chứa nội dung mô tả hoặc nội dung tùy biến của Confirm.
+
+| Prop | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `description` | `ReactNode` | `undefined` | Đoạn văn bản mô tả ngắn (tự động bọc trong thẻ `<p>` với typography chuẩn) |
+| `descriptionClassName` | `string` | `""` | Class CSS riêng cho thẻ `<p>` mô tả |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | *Kế thừa từ Context* | Kích thước áp dụng cho cỡ chữ và padding |
+| `className` | `string` | `""` | Class CSS cho toàn bộ khối body |
+| `children` | `ReactNode` | `undefined` | Nội dung tùy biến bên trong body |
+
+---
+
+### `<ConfirmFooter>`
+
+Phần chân chứa các nút hành động xác nhận và hủy.
+
+| Prop | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `confirmText` | `ReactNode` | `'Xác nhận'` | Nhãn nút Xác nhận |
+| `cancelText` | `ReactNode \| false` | `'Hủy'` | Nhãn nút Hủy (`false` để ẩn nút Hủy) |
+| `confirmVariant` | `ButtonVariant` | `'filled'` | Biến thể hiển thị của nút Xác nhận |
+| `cancelVariant` | `ButtonVariant` | `'outline'` | Biến thể hiển thị của nút Hủy |
+| `confirmColor` | `ButtonColor` | *Kế thừa theo `color`* | Màu nút Xác nhận |
+| `cancelColor` | `ButtonColor` | `'secondary'` | Màu nút Hủy |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | *Kế thừa từ Context* | Kích thước áp dụng cho nút bấm và padding |
+| `onConfirm` | `() => void \| Promise<unknown>` | `undefined` | Callback khi bấm nút Xác nhận (hỗ trợ hàm Async tự động bật Loading Spinner) |
+| `onCancel` | `() => void` | `undefined` | Callback khi bấm nút Hủy |
+| `onClose` | `() => void` | `undefined` | Callback khi đóng |
+| `confirmButtonProps` | `Partial<ButtonProps>` | `undefined` | Props bổ sung truyền trực tiếp cho Button Xác nhận |
+| `cancelButtonProps` | `Partial<ButtonProps>` | `undefined` | Props bổ sung truyền trực tiếp cho Button Hủy |
+| `className` | `string` | `""` | Class CSS cho toàn bộ khối footer |
+| `children` | `ReactNode` | `undefined` | Các nút bấm tùy chỉnh khi tự định nghĩa footer |
+
+---
+
+### `<ConfirmClose>`
+
+Wrapper bọc quanh bất kỳ nút bấm hoặc phần tử nào bên trong Confirm. Khi click, `<ConfirmClose>` sẽ tự động kích hoạt hiệu ứng đóng mượt mà trước khi unmount (tự động `disabled` khi `isLoading = true`).
+
+| 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` |