@openway/ui 1.0.0 → 1.0.2

package/docs/components/dropdown.md

@@ -0,0 +1,275 @@
+# 🔽 Dropdown Component (`@owa/ui`)
+
+Bộ component **Dropdown Menu** xây dựng theo mô hình **Compound Component** trên nền tảng **`@floating-ui/react`**, hỗ trợ **điều hướng bàn phím WAI-ARIA Menu hoàn chỉnh**, **tự động căn chỉnh vị trí thông minh (flip/shift/offset)**, **hiệu ứng chuyển động mượt mà**, 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 linh hoạt gồm `<Dropdown>`, `<DropdownTrigger>`, `<DropdownMenu>`, `<DropdownItem>`, `<DropdownHeader>`, `<DropdownGroup>`, `<DropdownSeparator>`.
+- **Hỗ trợ React 19 & React Compiler**: Áp dụng mô hình `Slot` component giúp xử lý `ref` sạch sẽ qua JSX, không gây lỗi runtime hay cảnh báo `Cannot access refs during render`.
+- **Hệ thống z-index đồng bộ**: Tích hợp với `DEFAULT_Z_INDEX.DROPDOWN` (mặc định `50`) từ hệ thống constant toàn cục.
+- **Tự động định vị thông minh**: Tính toán vị trí nổi thông minh qua `@floating-ui/react` với các middleware `offset`, `flip`, `shift`.
+- **Luôn nổi trên cùng (Floating Portal)**: Menu luôn được render qua `<FloatingPortal>` để không bị ảnh hưởng bởi CSS `overflow: hidden` hoặc `z-index` của cha.
+- **Safe Config Fallback**: Tích hợp hàm `getSafeConfig` giúp lấy an toàn `sizeConfig`, `radiusConfig`, `colorConfig`, ngăn ngừa crash giao diện khi nhận giá trị không hợp lệ.
+- **WAI-ARIA Accessibility**:
+  - `role="menu"` cho dropdown menu container.
+  - `role="menuitem"` cho từng item lựa chọn.
+  - `role="group"` cho nhóm menu item.
+  - `aria-expanded`, `aria-haspopup="menu"`, `aria-disabled`.
+  - Hỗ trợ đầy đủ phím tắt bàn phím: `ArrowDown`, `ArrowUp`, `Home`, `End`, `Enter`, `Space`, `Escape`.
+- **Nhiều tùy chọn kích thước & màu sắc**:
+  - 5 kích cỡ: `xs`, `sm`, `md` (*mặc định*), `lg`, `xl`.
+  - 7 chủ đề màu: `primary`, `secondary`, `neutral`, `error`, `success`, `warning`, `info`.
+  - 6 cấp độ bo góc: `none`, `sm`, `md` (*mặc định*), `lg`, `xl`, `full`.
+
+---
+
+## 🚀 Cài đặt & Import
+
+```tsx
+import {
+  Dropdown,
+  DropdownTrigger,
+  DropdownMenu,
+  DropdownItem,
+  DropdownHeader,
+  DropdownGroup,
+  DropdownSeparator,
+} from "@owa/ui";
+import type {
+  DropdownProps,
+  DropdownTriggerProps,
+  DropdownMenuProps,
+  DropdownItemProps,
+  DropdownHeaderProps,
+  DropdownGroupProps,
+  DropdownSeparatorProps,
+  DropdownPlacement,
+  DropdownSize,
+  DropdownRadius,
+  DropdownColor,
+} from "@owa/ui";
+```
+
+---
+
+## 📖 Hướng dẫn sử dụng
+
+### 1. Menu cơ bản
+
+```tsx
+import {
+  Dropdown,
+  DropdownTrigger,
+  DropdownMenu,
+  DropdownItem,
+  Button,
+} from "@owa/ui";
+
+export function BasicDropdown() {
+  return (
+    <Dropdown>
+      <DropdownTrigger>
+        <Button>Mở Menu</Button>
+      </DropdownTrigger>
+      <DropdownMenu>
+        <DropdownItem onClick={() => console.log("Hồ sơ")}>Hồ sơ cá nhân</DropdownItem>
+        <DropdownItem onClick={() => console.log("Cài đặt")}>Cài đặt tài khoản</DropdownItem>
+        <DropdownItem isDanger onClick={() => console.log("Đăng xuất")}>Đăng xuất</DropdownItem>
+      </DropdownMenu>
+    </Dropdown>
+  );
+}
+```
+
+---
+
+### 2. Menu đầy đủ tính năng (Header, Group, Icon, Shortcut, Danger)
+
+```tsx
+import {
+  Dropdown,
+  DropdownTrigger,
+  DropdownMenu,
+  DropdownHeader,
+  DropdownGroup,
+  DropdownItem,
+  DropdownSeparator,
+  Button,
+} from "@owa/ui";
+import { UserIcon, SettingsIcon, LockIcon, TrashIcon } from "@/components/icons";
+
+export function AdvancedDropdown() {
+  return (
+    <Dropdown placement="bottom-start" size="md">
+      <DropdownTrigger>
+        <Button variant="outline">Tài khoản của tôi</Button>
+      </DropdownTrigger>
+      <DropdownMenu minWidth={240}>
+        <DropdownHeader>
+          <div className="font-semibold text-neutral-900">Nguyễn Văn A</div>
+          <div className="text-xs text-neutral-500">vana@example.com</div>
+        </DropdownHeader>
+        <DropdownSeparator />
+
+        <DropdownGroup title="Quản lý">
+          <DropdownItem icon={<UserIcon />} shortcut="⌘P" onClick={() => {}}>
+            Hồ sơ cá nhân
+          </DropdownItem>
+          <DropdownItem icon={<SettingsIcon />} shortcut="⌘S" onClick={() => {}}>
+            Cài đặt
+          </DropdownItem>
+        </DropdownGroup>
+        <DropdownSeparator />
+
+        <DropdownGroup title="Bảo mật">
+          <DropdownItem icon={<LockIcon />} onClick={() => {}}>
+            Đổi mật khẩu
+          </DropdownItem>
+          <DropdownItem
+            icon={<TrashIcon />}
+            isDanger
+            shortcut="⌘⌫"
+            onClick={() => {}}
+          >
+            Xóa tài khoản
+          </DropdownItem>
+        </DropdownGroup>
+      </DropdownMenu>
+    </Dropdown>
+  );
+}
+```
+
+---
+
+### 3. Tùy chỉnh Trigger qua `asChild`
+
+Khi bật `asChild` (hoặc truyền trực tiếp một phần tử con hợp lệ), `DropdownTrigger` sẽ truyền toàn bộ accessibility attributes và sự kiện vào phần tử con mà không bọc thêm thẻ `<button>` thừa:
+
+```tsx
+import { Dropdown, DropdownTrigger, DropdownMenu, DropdownItem, IconButton } from "@owa/ui";
+import { MoreVerticalIcon } from "@/components/icons";
+
+export function CustomTriggerDropdown() {
+  return (
+    <Dropdown placement="bottom-end">
+      <DropdownTrigger asChild>
+        <IconButton icon={<MoreVerticalIcon />} aria-label="Tùy chọn khác" variant="ghost" />
+      </DropdownTrigger>
+      <DropdownMenu>
+        <DropdownItem>Chỉnh sửa</DropdownItem>
+        <DropdownItem>Sao chép liên kết</DropdownItem>
+        <DropdownItem isDanger>Xóa mục này</DropdownItem>
+      </DropdownMenu>
+    </Dropdown>
+  );
+}
+```
+
+---
+
+### 4. Kích hoạt bằng Hover (`trigger="hover"`)
+
+```tsx
+<Dropdown trigger="hover" placement="bottom-start">
+  <DropdownTrigger>
+    <Button variant="soft">Rê chuột để mở</Button>
+  </DropdownTrigger>
+  <DropdownMenu>
+    <DropdownItem>Tùy chọn 1</DropdownItem>
+    <DropdownItem>Tùy chọn 2</DropdownItem>
+  </DropdownMenu>
+</Dropdown>
+```
+
+---
+
+## ♿ Khả năng truy cập & Điều hướng bàn phím
+
+| Phím bấm | Hành vi |
+| :--- | :--- |
+| `Enter` / `Space` / `ArrowDown` | Mở menu khi đang focus tại trigger và focus vào item đầu tiên. |
+| `ArrowDown` | Di chuyển focus xuống item tiếp theo (tự động bỏ qua item bị `disabled` hoặc separator). |
+| `ArrowUp` | Di chuyển focus lên item phía trên (hỗ trợ vòng lặp danh sách `loop: true`). |
+| `Home` | Nhảy nhanh tới item đầu tiên trong menu. |
+| `End` | Nhảy nhanh tới item cuối cùng trong menu. |
+| `Escape` | Đóng menu và trả focus về lại trigger element. |
+| `Enter` / `Space` | Kích hoạt sự kiện `onClick` của item đang chọn và đóng menu (nếu `closeOnSelect={true}`). |
+
+---
+
+## 📋 API Reference
+
+### `<Dropdown>` (Root Component)
+
+| Prop | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `children` | `ReactNode` | — | Các component con (`DropdownTrigger`, `DropdownMenu`). |
+| `open` | `boolean` | — | Trạng thái mở menu (chế độ Controlled). |
+| `defaultOpen` | `boolean` | `false` | Trạng thái mở ban đầu (chế độ Uncontrolled). |
+| `onOpenChange` | `(open: boolean) => void` | — | Callback khi trạng thái đóng/mở thay đổi. |
+| `trigger` | `'click' \| 'hover'` | `'click'` | Kiểu kích hoạt mở dropdown. |
+| `placement` | `DropdownPlacement` | `'bottom-start'` | Vị trí hiển thị menu so với trigger. |
+| `offset` | `number` | `4` | Khoảng cách (px) giữa trigger và menu. |
+| `flip` | `boolean` | `true` | Tự động đảo hướng khi bị tràn mép màn hình. |
+| `shift` | `boolean` | `true` | Tự động dịch chuyển menu để không bị che khuất. |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Kích thước áp dụng cho menu và items. |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'` | Độ bo góc của khung menu. |
+| `color` | `DropdownColor` | `'primary'` | Tông màu chủ đạo khi item được active/hover. |
+| `disabled` | `boolean` | `false` | Vô hiệu hóa toàn bộ Dropdown. |
+| `animated` | `boolean` | `true` | Bật/tắt animation mở/đóng menu. |
+| `animationDuration` | `number` | `150` | Thời lượng animation (ms). |
+| `closeOnSelect` | `boolean` | `true` | Tự động đóng menu khi chọn một item. |
+| `closeOnEsc` | `boolean` | `true` | Đóng menu khi nhấn phím `Escape`. |
+| `closeOnClickOutside` | `boolean` | `true` | Đóng menu khi click ra ngoài. |
+
+---
+
+### `<DropdownTrigger>`
+
+| Prop | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `children` | `ReactNode` | — | Phần tử con làm trigger. |
+| `asChild` | `boolean` | `false` | Sử dụng chính 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. |
+
+---
+
+### `<DropdownMenu>`
+
+| Prop | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `children` | `ReactNode` | — | Nội dung bên trong menu (Header, Group, Item, Separator). |
+| `minWidth` | `string \| number` | — | Độ rộng tối thiểu của menu. |
+| `zIndex` | `number` | `DEFAULT_Z_INDEX.DROPDOWN` (50) | Thứ tự z-index của menu. |
+| `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 menu container. |
+
+---
+
+### `<DropdownItem>`
+
+| Prop | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `children` | `ReactNode` | — | Nhãn hoặc nội dung của item. |
+| `icon` | `ReactNode` | — | Icon hiển thị ở phía trước (bên trái). |
+| `shortcut` | `string` | — | Ký hiệu phím tắt hiển thị ở bên phải (ví dụ: `"⌘K"`, `"Ctrl+S"`). |
+| `color` | `DropdownColor` | — | Ghi đè màu sắc riêng cho item này. |
+| `size` | `DropdownSize` | — | Ghi đè kích thước riêng cho item này. |
+| `disabled` | `boolean` | `false` | Vô hiệu hóa item (không thể hover hay click). |
+| `isDanger` | `boolean` | `false` | Định dạng item theo phong cách cảnh báo/hành động nguy hiểm (chữ đỏ, hover nền đỏ nhạt). |
+| `onClick` | `(e: MouseEvent) => void` | — | Callback khi người dùng click vào item. |
+| `className` | `string` | `""` | Class CSS tùy biến bổ sung. |
+| `ref` | `Ref<HTMLDivElement>` | — | React 19 Ref trực tiếp vào item. |
+
+---
+
+### `<DropdownHeader>`, `<DropdownGroup>`, `<DropdownSeparator>`
+
+- `<DropdownHeader>`: Hiển thị thông tin tiêu đề/tài khoản đầu menu (`<div>` chuẩn WAI-ARIA menu).
+- `<DropdownGroup title="Tiêu đề nhóm">`: Gom nhóm các item và hiển thị nhãn nhóm `role="group"`.
+- `<DropdownSeparator>`: Đường kẻ ngang phân cách ngữ cảnh giữa các nhóm menu (thẻ `<hr>` ngữ nghĩa HTML5).

package/docs/components/empty.md

@@ -0,0 +1,200 @@
+# 📭 Empty Component (`@openway/ui`)
+
+Component **Empty** (Trạng thái rỗng) hiển thị khi một danh sách, bảng dữ liệu, tìm kiếm hoặc trang web không có dữ liệu để hiển thị. Được thiết kế chuẩn **Design System**, hỗ trợ đa dạng **Preset Illustrations**, tùy biến **Hình ảnh/Icon/URL**, căn chỉnh bố cục **Vertical / Horizontal**, tích hợp **Safe Config Fallback** (`getSafeConfig`) và tuân thủ đầy đủ tiêu chuẩn **WAI-ARIA Accessibility**.
+
+---
+
+## 🌟 Điểm nổi bật
+
+- **5 Preset Illustrations tích hợp sẵn**:
+  - `default`: Minh họa hộp dữ liệu rỗng tiêu chuẩn.
+  - `search`: Kính lúp không tìm thấy kết quả.
+  - `error`: Lỗi tải dữ liệu hoặc mất kết nối mạng.
+  - `folder`: Thư mục rỗng.
+  - `simple`: Minh họa tối giản, gọn nhẹ.
+- **Hỗ trợ đa dạng nguồn ảnh (`image`)**:
+  - Tên preset (`default`, `search`, `error`, `folder`, `simple`).
+  - Đường dẫn URL ảnh (tự động render qua `next/image` với tối ưu hóa hình ảnh).
+  - Custom JSX (`ReactNode`) như SVG Icon, Emoji hoặc component tùy biến.
+- **3 Kích thước tiêu chuẩn (`size`)**:
+  - `sm`: Gọn nhẹ, thích hợp cho dropdown, popover, select menu, bảng nhỏ.
+  - `md` *(mặc định)*: Tiêu chuẩn, thích hợp cho section, thẻ card, modal dialog.
+  - `lg`: Kích thước lớn, thích hợp cho trang dashboard hoặc toàn màn hình.
+- **2 Bố cục hiển thị (`layout`)**:
+  - `vertical` *(mặc định)*: Xếp dọc từ trên xuống (Ảnh -> Tiêu đề -> Mô tả -> Actions).
+  - `horizontal`: Bố cục hàng ngang (Ảnh bên trái, nội dung & actions bên phải), tối ưu khi diện tích theo chiều ngang rộng rãi.
+- **Khu vực hành động linh hoạt (`actions`)**: Cung cấp slot chuyên biệt để chèn Button (Tạo mới, Thử lại, Tải lại...).
+- **Safe Config Fallback**: Tích hợp hàm `getSafeConfig` từ `@/utils/function` đảm bảo an toàn tuyệt đối, không crash giao diện khi nhận giá trị `size` hoặc `layout` không hợp lệ.
+- **Trợ năng (Accessibility)**: Tự động gắn `role="status"` và `aria-live="polite"` giúp các trình đọc màn hình (Screen Reader) thông báo trạng thái rỗng một cách rõ ràng.
+
+---
+
+## 🚀 Cài đặt & Import
+
+```tsx
+import { Empty, EmptyIllustration } from "@openway/ui";
+import type { EmptyProps, EmptySize, EmptyLayout, EmptyPresetImage } from "@openway/ui";
+```
+
+---
+
+## 📖 Hướng dẫn sử dụng
+
+### 1. Trạng thái rỗng cơ bản
+
+```tsx
+import { Empty } from "@openway/ui";
+
+export function BasicEmptyExample() {
+  return (
+    <Empty
+      title="Không có dữ liệu"
+      description="Hiện tại chưa có dữ liệu nào trong danh sách này."
+    />
+  );
+}
+```
+
+---
+
+### 2. Các Presets minh họa (`image`)
+
+```tsx
+import { Empty } from "@openway/ui";
+
+export function PresetExamples() {
+  return (
+    <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
+      {/* Tìm kiếm không thấy */}
+      <Empty
+        image="search"
+        title="Không tìm thấy kết quả"
+        description="Vui lòng thử lại với từ khóa khác."
+      />
+
+      {/* Lỗi kết nối */}
+      <Empty
+        image="error"
+        title="Tải thất bại"
+        description="Không thể kết nối đến máy chủ. Vui lòng thử lại."
+      />
+
+      {/* Thư mục rỗng */}
+      <Empty
+        image="folder"
+        title="Thư mục trống"
+        description="Chưa có tệp tin nào được tải lên thư mục này."
+      />
+    </div>
+  );
+}
+```
+
+---
+
+### 3. Tùy chỉnh kích thước (`size`) & Kèm nút hành động (`actions`)
+
+```tsx
+import { Empty, Button } from "@openway/ui";
+
+export function ActionsExample() {
+  return (
+    <Empty
+      size="md"
+      image="default"
+      title="Chưa có dự án nào"
+      description="Hãy bắt đầu khởi tạo dự án đầu tiên của bạn để quản lý công việc hiệu quả."
+      actions={
+        <Button variant="filled" color="primary" onClick={() => console.log("Tạo mới")}>
+          Tạo dự án mới
+        </Button>
+      }
+    />
+  );
+}
+```
+
+---
+
+### 4. Bố cục ngang (`layout="horizontal"`)
+
+```tsx
+import { Empty, Button } from "@openway/ui";
+
+export function HorizontalEmptyExample() {
+  return (
+    <div className="border rounded-xl p-4">
+      <Empty
+        layout="horizontal"
+        size="sm"
+        image="folder"
+        title="Không tìm thấy tệp tin"
+        description="Thư mục hiện đang trống hoặc bạn không có quyền truy cập."
+        actions={
+          <Button size="xs" variant="outline" color="primary">
+            Tải tệp lên
+          </Button>
+        }
+      />
+    </div>
+  );
+}
+```
+
+---
+
+### 5. Dùng URL ảnh ngoài hoặc Custom ReactNode
+
+```tsx
+import { Empty } from "@openway/ui";
+
+export function CustomImageExample() {
+  return (
+    <Empty
+      image="https://images.unsplash.com/photo-1579546929518-9e396f3cc809?w=160&auto=format&fit=crop&q=60"
+      imageSize={120}
+      imageAlt="Custom Image"
+      title="Bộ sưu tập ảnh trống"
+      description="Hãy thêm các bức ảnh yêu thích của bạn."
+    />
+  );
+}
+```
+
+---
+
+## 🛡️ Safe Config Fallback
+
+Component `Empty` tích hợp hàm tiện ích `getSafeConfig` từ `@/utils/function`:
+
+```tsx
+import { getSafeConfig } from "@/utils/function";
+
+const currentSize = getSafeConfig(size, emptySizeConfig, "md");
+const currentLayout = getSafeConfig(layout, emptyLayoutConfig, "vertical");
+```
+
+- Nếu `size` truyền vào không thuộc `"sm" | "md" | "lg"`, component tự động fallback về kích cỡ chuẩn `"md"`.
+- Nếu `layout` truyền vào không hợp lệ, component tự động fallback về bố cục chuẩn `"vertical"`.
+- Giúp ứng dụng hoạt động ổn định, loại bỏ hoàn toàn nguy cơ runtime error / crash giao diện khi nhận dữ liệu không mong muốn từ bên ngoài.
+
+---
+
+## 📋 Danh sách Props (`EmptyProps`)
+
+| Tên Prop | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Kích cỡ tổng thể của component |
+| `layout` | `'vertical' \| 'horizontal'` | `'vertical'` | Bố cục xếp dọc hoặc dàn ngang |
+| `image` | `EmptyPresetImage \| string \| ReactNode` | `'default'` | Preset minh họa, URL ảnh hoặc JSX node tùy biến |
+| `imageSize` | `number \| string` | Theo `size` | Chiều rộng & chiều cao tùy chỉnh cho phần ảnh |
+| `imageClassName`| `string` | `""` | Class CSS cho thẻ bao ngoài ảnh |
+| `imageAlt` | `string` | `'Trống'` | Thuộc tính alt cho hình ảnh |
+| `title` | `ReactNode` | `undefined` | Tiêu đề trạng thái rỗng |
+| `titleClassName`| `string` | `""` | Class CSS tùy chỉnh tiêu đề |
+| `description` | `ReactNode` | `'Không có dữ liệu'` | Nội dung mô tả chi tiết |
+| `descriptionClassName` | `string` | `""` | Class CSS tùy chỉnh mô tả |
+| `actions` | `ReactNode` | `undefined` | Khu vực chứa nút bấm hành động (CTA) |
+| `actionsClassName` | `string` | `""` | Class CSS tùy chỉnh khu vực actions |
+| `children` | `ReactNode` | `undefined` | Nội dung bổ sung tùy biến |
+| `ref` | `Ref<HTMLDivElement>` | `undefined` | Ref chuyển tiếp đến container chính |

package/docs/components/file-preview.md

@@ -0,0 +1,180 @@
+# 📁 File Preview Components (`@owa/ui`)
+
+Bộ component xem trước tệp tin hiệu năng cao, xây dựng trên nền tảng **HTML5 Native `<dialog>`** và kiến trúc **React Context + Compound Component**:
+
+- **`<FileContainer>`**: Hộp thoại bọc ngoài Modal dialog quản lý Backdrop, Top layer breakout, ESC, Lock scroll và Header. Nhận prop `file` và chia sẻ `file` cùng `headerTitle` xuống dưới thông qua `FileContext`.
+- **`<FilePreview>`**: Component xác định loại tệp (`image`, `pdf`, `video`, `audio`, `document`, `other`) và chuyển tiếp tới component hiển thị tương ứng. Tự động tiêu thụ `file` và `headerTitle` từ `useFileContext()`.
+- **`<ImagePreview>`**: Khối hiển thị hình ảnh với đầy đủ tính năng Zoom, Rotate, Flip, Drag-to-pan, Reset và Tải ảnh.
+
+---
+
+## 🌟 Điểm nổi bật
+
+- **Zero Global Store**: Hoàn toàn không phụ thuộc Zustand / Redux.
+- **Context-driven Compound Architecture**:
+  - `FileContainer` nhận `file` (và tùy chọn `title`) rồi cung cấp qua `FileContext`.
+  - `FilePreview` tự động nhận `file` và `headerTitle` từ `useFileContext()`.
+- **Lồng ghép linh hoạt**:
+  ```tsx
+  <FileContainer open={open} onClose={handleClose} file={selectedFile}>
+    <FilePreview imageProps={{ minZoom: 0.5, maxZoom: 3 }} />
+  </FileContainer>
+  ```
+- **Tự động quản lý bộ nhớ**: Tự động giải phóng `ObjectURL` (`URL.revokeObjectURL`) khi truyền `File` object để tránh memory leak.
+
+---
+
+## 🚀 Cài đặt & Import
+
+```tsx
+import {
+  FileContainer,
+  FilePreview,
+  ImagePreview,
+  ImagePreviewToolbar,
+  FileContext,
+  useFileContext,
+  getFileName,
+  getFileType,
+  getFileExtension,
+  normalizePreviewFile,
+  downloadFile,
+} from "@owa/ui";
+```
+
+---
+
+## 📖 Hướng dẫn sử dụng
+
+### 1. Sử dụng kết hợp qua Context (Khuyên dùng)
+
+```tsx
+import { useState } from "react";
+import { Button, FileContainer, FilePreview } from "@owa/ui";
+
+export function Example() {
+  const [open, setOpen] = useState(false);
+  const [file, setFile] = useState<File | null>(null);
+
+  return (
+    <div>
+      <Button onClick={() => setOpen(true)}>Xem file</Button>
+
+      <FileContainer
+        open={open}
+        onClose={() => setOpen(false)}
+        file={file}
+      >
+        <FilePreview
+          imageProps={{
+            minZoom: 0.5,
+            maxZoom: 4,
+            toolbarProps: {
+              tools: { rotate: true, flip: true, download: true },
+            },
+          }}
+        />
+      </FileContainer>
+    </div>
+  );
+}
+```
+
+---
+
+### 2. Sử dụng gọn nhẹ (Tự động render `<FilePreview />`)
+
+```tsx
+<FileContainer
+  open={open}
+  onClose={() => setOpen(false)}
+  file={selectedFile}
+/>
+```
+
+---
+
+### 3. Sử dụng bọc trực tiếp `<ImagePreview>`
+
+```tsx
+<FileContainer open={open} onClose={() => setOpen(false)} title="Xem ảnh">
+  <ImagePreview src="https://images.unsplash.com/photo-1579783902614-a3fb3927b675" name="artwork.jpg" />
+</FileContainer>
+```
+
+---
+
+## 📚 Bảng tra cứu Props (API Reference)
+
+### `<FileContainer>` (Hộp thoại Modal)
+
+| Prop | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `open` | `boolean` | `false` | Trạng thái hiển thị mở/đóng FileContainer |
+| `onClose` | `() => void` | `undefined` | Callback khi đóng hộp thoại |
+| `file` | `File \| ServerFile` | `undefined` | Dữ liệu file truyền vào để chia sẻ qua Context |
+| `title` | `ReactNode` | `undefined` | Tiêu đề tùy chỉnh cho phần header (mặc định lấy tên file) |
+| `description` | `ReactNode` | `undefined` | Đoạn văn bản mô tả phụ bên dưới tiêu đề header |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'lg'` | Kích thước chiều rộng của hộp thoại Modal |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'xl'` | Mức độ bo góc của hộp thoại Modal |
+| `showCloseButton` | `boolean` | `true` | Hiển thị nút đóng (X) ở header |
+| `closeOnOverlayClick` | `boolean` | `true` | Cho phép đóng khi click ra ngoài backdrop |
+| `closeOnEsc` | `boolean` | `true` | Cho phép đóng khi nhấn phím ESC |
+| `lockScroll` | `boolean` | `true` | Khóa cuộn trang khi đang hiển thị |
+| `className` | `string` | `""` | Class CSS tùy biến cho hộp thoại |
+| `overlayClassName`| `string` | `""` | Class CSS tùy biến cho backdrop |
+| `children` | `ReactNode` | `undefined` | Nội dung bên trong (mặc định tự động render `<FilePreview />`) |
+
+---
+
+### `<FilePreview>` (Xác định loại file & Điều hướng Viewer)
+
+> **Lưu ý**: `<FilePreview>` tự động lấy `file` và `headerTitle` từ `FileContainer` thông qua `useFileContext()`.
+
+| Prop | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `onDownload` | `(file: PreviewFile) => void` | `undefined` | Callback tùy biến khi bấm nút tải file xuống |
+| `imageProps` | `Partial<ImagePreviewProps>` | `undefined` | Cấu hình chi tiết cho phần hiển thị ảnh (`minZoom`, `maxZoom`, `toolbarProps`, ...) |
+| `className` | `string` | `""` | Class CSS tùy biến cho container nội dung |
+
+---
+
+### `<ImagePreview>` (Hiển thị và tương tác ảnh)
+
+| Prop | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `src` | `string` | **Bắt buộc** | Đường dẫn ảnh hoặc data URL |
+| `name` | `string` | `undefined` | Tên file ảnh hiển thị khi tải xuống |
+| `alt` | `string` | `undefined` | Thẻ alt mô tả cho ảnh |
+| `minZoom` | `number` | `0.2` | Mức độ thu nhỏ tối thiểu (20%) |
+| `maxZoom` | `number` | `5` | Mức độ phóng to tối đa (500%) |
+| `showToolbar` | `boolean` | `true` | Hiển thị thanh công cụ điều khiển phía dưới |
+| `toolbarProps` | `Partial<ImagePreviewToolbarProps>` | `undefined` | Cấu hình chi tiết các nút bấm trên toolbar (`tools`) |
+| `className` | `string` | `""` | Class CSS tùy biến cho container bao ngoài |
+| `children` | `ReactNode` | `undefined` | Phần tử React con bổ sung |
+
+### `<ImagePreviewToolbar>` (Thanh công cụ điều khiển ảnh)
+
+| Prop | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `zoom` | `number` | `1` | Mức độ phóng to hiện tại |
+| `minZoom` | `number` | `0.2` | Mức thu nhỏ tối thiểu |
+| `maxZoom` | `number` | `5` | Mức phóng to tối đa |
+| `step` | `number` | `0.05` | Bước nhảy zoom khi kéo thanh trượt Slider |
+| `onZoomChange` | `(zoom: number) => void` | `undefined` | Callback khi zoom thay đổi qua Slider |
+| `sliderProps` | `Partial<SliderProps>` | `undefined` | Tùy biến props cho component Slider bên trong |
+| `tools` | `ToolbarToolsConfig` | `{}` | Cấu hình bật/tắt các nút và công cụ |
+
+---
+
+### `ToolbarToolsConfig` (Cấu hình nút trên thanh công cụ)
+
+| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `zoomIn` | `boolean` | `true` | Nút phóng to (+) |
+| `zoomOut` | `boolean` | `true` | Nút thu nhỏ (-) |
+| `zoomSlider` | `boolean` | `true` | Thanh trượt Slider điều chỉnh zoom trực tiếp |
+| `reset` | `boolean` | `true` | Nút hiển thị % và reset tỉ lệ (1:1) |
+| `rotate` | `boolean` | `true` | Cặp nút xoay ảnh theo & ngược chiều kim đồng hồ |
+| `flip` | `boolean` | `true` | Nút lật ảnh theo chiều ngang |
+| `download` | `boolean` | `true` | Nút tải ảnh xuống máy tính |