@openway/ui 1.0.0 → 1.0.2

package/docs/AGENTS.md

@@ -0,0 +1,144 @@
+# 🎨 OpenWay Design System — Antigravity Guide (`@openway/ui`)
+
+Tài liệu hướng dẫn chuyên sâu dành riêng cho **Antigravity AI Agent** khi làm việc với thư viện component `@openway/ui`.
+
+---
+
+## ⚡ Chỉ dẫn cấu hình cho Dự án con (Consumer Projects)
+
+Khi cài đặt `@openway/ui` vào dự án bất kỳ, thêm đoạn sau vào file `AGENTS.md` ở thư mục gốc của dự án để Antigravity tự động kích hoạt kiến thức Design System:
+
+```markdown
+<!-- openway-ui:start -->
+# OpenWay UI Components Guideline
+Khi tạo mới, sửa đổi hoặc sử dụng các component UI trong dự án:
+- **LUÔN LUÔN** ưu tiên sử dụng các component từ `@openway/ui` thay vì tự viết HTML thẻ trần hoặc cài thư viện ngoài.
+- Đọc chi tiết danh mục và tài liệu API tại: `node_modules/@openway/ui/docs/AGENTS.md`.
+- Tra cứu từng component cụ thể tại: `node_modules/@openway/ui/docs/components/<component-name>.md`.
+- Với phân trang server / infinite scroll cho Select: Dùng `useSelectInfiniteQuery` từ `@openway/ui/query`.
+- Tuân thủ nghiêm ngặt chuẩn TypeScript **Zero `any`** và token màu **Tailwind CSS v4**.
+<!-- openway-ui:end -->
+```
+
+---
+
+## 📦 Quy tắc Import Chuẩn
+
+```tsx
+// 1. Tất cả 32 UI Components, Icons, và Core Hooks dùng chung
+import {
+  Button,
+  IconButton,
+  Input,
+  Textarea,
+  Select,
+  MultiSelect,
+  Checkbox,
+  CheckboxGroup,
+  Radio,
+  RadioGroup,
+  Toggle,
+  Slider,
+  Table,
+  Modal,
+  Confirm,
+  Dropdown,
+  Popover,
+  Tooltip,
+  Alert,
+  Badge,
+  Skeleton,
+  Toast,
+  Tabs,
+  Collapse,
+  Empty,
+  DatePicker,
+  DateRangePicker,
+  TimePicker,
+  TimeRangePicker,
+  DateTimePicker,
+  DateTimeRangePicker,
+  UploadFile,
+  UploadAvatar,
+  UploadImage,
+  FilePreview,
+  Carousel,
+  useInfiniteScroll,
+  useDebounce,
+  useDebouncedCallback,
+} from "@openway/ui";
+
+// 2. Query Hooks chuyên dụng cho TanStack Query v5 (phân trang server, infinite scroll)
+import { useSelectInfiniteQuery } from "@openway/ui/query";
+```
+
+---
+
+## 🧭 Danh mục 32 Components & Tài liệu Chi tiết
+
+Tất cả tài liệu chi tiết của từng component được lưu trữ tại `node_modules/@openway/ui/docs/components/<name>.md`:
+
+| Phân nhóm | Component | File Tài liệu | Mục đích sử dụng |
+| :--- | :--- | :--- | :--- |
+| **Buttons & Actions** | `<Button>`, `<IconButton>` | [`button.md`](./components/button.md) | Nút bấm chính/phụ, nút icon tròn/vuông, 6 variants, loading spinner. |
+| **Form Inputs** | `<Input>` | [`input.md`](./components/input.md) | Nhập văn bản, số, password với mắt ẩn/hiện, start/end content. |
+| | `<Textarea>` | [`textarea.md`](./components/textarea.md) | Nhập văn bản nhiều dòng, tự động co giãn độ cao theo nội dung. |
+| | `<Select>`, `<MultiSelect>` | [`select.md`](./components/select.md) | Chọn đơn/nhiều, tìm kiếm client/server, menu filters, skeleton infinite scroll. |
+| | `<Checkbox>`, `<CheckboxGroup>` | [`checkbox.md`](./components/checkbox.md) | Chọn nhiều giá trị, trạng thái indeterminate, bố cục ngang/dọc. |
+| | `<Radio>`, `<RadioGroup>` | [`radio.md`](./components/radio.md) | Chọn 1 trong danh sách phương án, hỗ trợ custom card option. |
+| | `<Toggle>` | [`toggle.md`](./components/toggle.md) | Công tắc bật/tắt (Switch), hỗ trợ icon và nhãn mô tả. |
+| | `<Slider>` | [`slider.md`](./components/slider.md) | Thanh trượt chọn giá trị số hoặc dải giá trị (Radix Slider). |
+| **Data Display** | `<Table>` | [`table.md`](./components/table.md) | Bảng dữ liệu TanStack Table v9, sort, filter, pagination, row selection, resize cột. |
+| | `<Badge>` | [`badge.md`](./components/badge.md) | Huy hiệu số lượng, chấm trạng thái (dot), gắn góc avatar/nút. |
+| | `<Empty>` | [`empty.md`](./components/empty.md) | Màn hình thông báo không có dữ liệu, minh họa trực quan kèm nút CTA. |
+| | `<Carousel>` | [`carousel.md`](./components/carousel.md) | Trình chiếu slide ảnh/nội dung, điều hướng nút bấm & dot. |
+| | `<Collapse>` | [`collapse.md`](./components/collapse.md) | Danh sách xếp gọn (Accordion), mở đơn lẻ hoặc mở đồng thời nhiều mục. |
+| **Feedback & Status** | `<Alert>` | [`alert.md`](./components/alert.md) | Banner cảnh báo inline: success, error, warning, info, có nút đóng. |
+| | `<Skeleton>` | [`skeleton.md`](./components/skeleton.md) | Khung placeholder nhấp nháy mô phỏng layout đang tải dữ liệu. |
+| | `<Toast>` | [`toast.md`](./components/toast.md) | Thông báo góc màn hình nổi (dựa trên Sonner), hỗ trợ promise toast. |
+| **Navigation** | `<Tabs>` | [`tabs.md`](./components/tabs.md) | Chuyển đổi tab nội dung với thanh chỉ thị hoạt họa mượt mà. |
+| | `<Dropdown>` | [`dropdown.md`](./components/dropdown.md) | Menu thả xuống cho các thao tác phụ (hành động người dùng, menu bảng). |
+| **Overlays & Dialogs** | `<Modal>` | [`modal.md`](./components/modal.md) | Hộp thoại modal, khóa scroll body, hỗ trợ animation mở/đóng. |
+| | `<Confirm>` | [`confirm.md`](./components/confirm.md) | Hộp thoại xác nhận hành động nguy hiểm (Xóa, Hủy) kèm trạng thái loading. |
+| | `<Popover>` | [`popover.md`](./components/popover.md) | Khung thông tin phụ nổi theo phần tử neo (Floating UI). |
+| | `<Tooltip>` | [`tooltip.md`](./components/tooltip.md) | Gợi ý văn bản ngắn khi hover/focus vào nút hoặc icon. |
+| **Date & Time Pickers** | `<DatePicker>`, `<DateRangePicker>` | [`datepicker.md`](./components/datepicker.md), [`daterangepicker.md`](./components/daterangepicker.md) | Chọn ngày, chọn khoảng ngày với preset tiện ích (Hôm nay, Tuần này). |
+| | `<TimePicker>`, `<TimeRangePicker>` | [`timepicker.md`](./components/timepicker.md), [`timerangepicker.md`](./components/timerangepicker.md) | Chọn giờ phút giây dạng cột cuộn trực quan. |
+| | `<DateTimePicker>`, `<DateTimeRangePicker>` | [`datetimepicker.md`](./components/datetimepicker.md), [`datetimerangepicker.md`](./components/datetimerangepicker.md) | Chọn kết hợp cả ngày và giờ trong cùng một popup. |
+| **File & Media** | `<UploadFile>` | [`upload-file.md`](./components/upload-file.md) | Tải tệp tin đa định dạng (PDF, DOCX, ZIP...), thanh tiến trình, drag & drop. |
+| | `<UploadAvatar>` | [`upload-avatar.md`](./components/upload-avatar.md) | Tải và xem trước ảnh đại diện người dùng dạng hình tròn. |
+| | `<UploadImage>` | [`upload-image.md`](./components/upload-image.md) | Tải nhiều ảnh dạng Dropzone hoặc Picture Wall, tích hợp modal Crop ảnh. |
+| | `<FilePreview>` | [`file-preview.md`](./components/file-preview.md) | Xem trước nội dung tệp tin, hình ảnh, tài liệu trực tiếp trên giao diện. |
+
+---
+
+## 🪝 Utility & Query Hooks
+
+- **[`useInfiniteScroll`](./hooks/useInfiniteScroll.md)**: Tải dữ liệu vô tận thuần React 19 qua `IntersectionObserver`, tự động kích hoạt `onLoadMore` khi sentinel vào viewport.
+- **[`useDebounce` & `useDebouncedCallback`](./hooks/useDebounce.md)**: Bộ đôi hoãn cập nhật giá trị hoặc hàm callback theo mili-giây, chống spam request.
+- **[`useTableQuery`](./hooks/useTableQuery.md)** (`@openway/ui/query`): Adapter kết nối TanStack Query v5 với `<Table />`, hỗ trợ phân trang máy chủ, multi-column sorting, column filtering và `keepPreviousData`.
+- **[`useSelectInfiniteQuery`](./hooks/useSelectInfiniteQuery.md)** (`@openway/ui/query`): Adapter kết nối TanStack Query v5 với `<Select />` và `<MultiSelect />`, tự động cuộn tải trang, debounce từ khóa và Skeleton loading.
+
+---
+
+## 🎨 Quy chuẩn Design Tokens & Styling
+
+1. **Bảng màu Tailwind CSS v4 Theme-Agnostic**:
+   - Component không cố định mã màu HEX mà sử dụng các biến theme:
+     `primary`, `secondary`, `neutral`, `error`, `success`, `warning`, `info`.
+   - Các mức sắc độ: `50`, `100`, `200`, `300`, `400`, `500` (màu chính), `600` (hover), `700` (focus ring), `800`, `900`, `950`.
+2. **Kích thước (`size`)**:
+   - `xs` (24px), `sm` (32px), `md` (40px - chuẩn cho form input/nút), `lg` (48px), `xl` (56px).
+3. **Bo góc (`radius`)**:
+   - `none` (0px), `sm` (4px), `md` (6px), `lg` (8px - chuẩn mặc định), `xl` (12px), `full` (tròn).
+4. **Hỗ trợ chế độ Tối (Dark Mode)**:
+   - Tất cả component tự động thích ứng qua class Tailwind `dark:`.
+
+---
+
+## 🚨 Nguyên tắc cốt lõi cho AI Agent khi code
+
+1. **KHÔNG tự chế component trần**: Khi cần nút, ô nhập, bảng, modal, dialog, picker -> Luôn import component tương ứng từ `@openway/ui`.
+2. **KHÔNG dùng `any`**: Sử dụng chính xác Generic Types exported từ thư viện (ví dụ `SelectOptionItem<TData>`, `ColumnDef<TData>`).
+3. **Tránh Double Debounce**: Khi dùng `useSelectInfiniteQuery`, `<Select>` đã tự động debounce từ khóa theo `debounceMs` rồi mới truyền vào `onSearch`.
+4. **Trợ năng WAI-ARIA**: Khi dùng `<IconButton>`, bắt buộc phải truyền `aria-label` để màn hình đọc hỗ trợ người khiếm thị.

package/docs/README.md

@@ -0,0 +1,150 @@
+# 📚 OpenWay UI — Thư viện Tài liệu Toàn diện (`@openway/ui`)
+
+Chào mừng bạn đến với trung tâm tài liệu chính thức của **OpenWay UI Design System**. Thư mục này được đóng gói sẵn trong package `node_modules/@openway/ui/docs/` để lập trình viên và các **AI Assistant (Antigravity)** có thể tra cứu và sử dụng nhanh chóng, chuẩn xác.
+
+---
+
+## 🚀 Mục lục Nhanh
+
+- [1. Hướng dẫn Tích hợp Antigravity AI](#1-hướng-dẫn-tích-hợp-antigravity-ai)
+- [2. Cài đặt & Cấu hình Theme Tailwind CSS](#2-cài-đặt--cấu-hình-theme-tailwind-css)
+- [3. Danh mục 32 Components](#3-danh-mục-32-components)
+- [4. Danh mục Hooks (`@openway/ui` & `@openway/ui/query`)](#4-danh-mục-hooks)
+- [5. Quy chuẩn Thiết kế (Design Tokens)](#5-quy-chuẩn-thiết-kế-design-tokens)
+
+---
+
+## 1. Hướng dẫn Tích hợp Antigravity AI
+
+Thư viện được tối ưu hóa đặc biệt cho **Antigravity AI Agent**. Bạn có thể tận dụng ngay 2 tài liệu cốt lõi:
+
+- **[`AGENTS.md`](./AGENTS.md)**: Bản chỉ dẫn hành vi, sitemap, quy tắc import và checklist cho Antigravity.
+- **[`SKILL.md`](./SKILL.md)**: Antigravity Skill định dạng chuẩn (`openway-ui`), cho phép Antigravity tự động kích hoạt on-demand khi tạo mới hoặc sửa đổi UI.
+
+### Cấu hình cho Dự án con (Consumer Project):
+Thêm khối chỉ dẫn sau vào file `AGENTS.md` ở thư mục gốc dự án của bạn:
+
+```markdown
+<!-- openway-ui:start -->
+# OpenWay UI Components
+Khi viết giao diện hoặc tạo/sửa component:
+1. Luôn ưu tiên dùng component có sẵn từ `@openway/ui`.
+2. Tham khảo tài liệu và ví dụ code mẫu tại: `node_modules/@openway/ui/docs/AGENTS.md`.
+3. Tra cứu từng component cụ thể tại: `node_modules/@openway/ui/docs/components/<component>.md`.
+4. Với phân trang server / infinite scroll: dùng hook từ `@openway/ui/query`.
+5. Tuyệt đối tuân thủ Zero `any` và token màu Tailwind CSS v4.
+<!-- openway-ui:end -->
+```
+
+---
+
+## 2. Cài đặt & Cấu hình Theme Tailwind CSS
+
+### Cài đặt Package
+
+```bash
+pnpm add @openway/ui
+# hoặc
+npm install @openway/ui
+```
+
+### Cấu hình Bảng màu trong `app/globals.css` (Tailwind CSS v4)
+
+Thư viện theo triết lý **Theme-Agnostic** (không cố định màu HEX, dự án tự định nghĩa màu):
+
+```css
+@import "tailwindcss";
+
+/* 1. Quét các class của thư viện */
+@source "../node_modules/@openway/ui";
+
+/* 2. Cung cấp bảng màu thương hiệu của bạn */
+@theme {
+  --color-primary-500: #0284c7; /* Màu chính của nút, checkbox active... */
+  --color-primary-600: #0369a1; /* Màu khi hover, active... */
+  --color-primary-700: #075985; /* Màu focus ring */
+
+  --color-secondary-500: #a855f7;
+  --color-secondary-600: #9333ea;
+
+  --color-error-500: #ef4444;
+  --color-warning-500: #f59e0b;
+  --color-success-500: #10b981;
+  --color-info-500: #3b82f6;
+}
+```
+
+---
+
+## 3. Danh mục 32 Components
+
+Tất cả tài liệu chi tiết của từng component được lưu trữ tại thư mục [`components/`](./components/):
+
+### Buttons & Actions
+- **[`button.md`](./components/button.md)**: Nút bấm `<Button>` và nút icon `<IconButton>`, 5 kích cỡ, 6 biến thể (`filled`, `soft`, `outline`, `ghost`, `text`, `other`), loading spinner.
+
+### Form Inputs & Controls
+- **[`input.md`](./components/input.md)**: Trường nhập văn bản `<Input>`, hiển thị mật khẩu ẩn/hiện, start/end content.
+- **[`textarea.md`](./components/textarea.md)**: Vùng văn bản nhiều dòng `<Textarea>`, tự động co giãn độ cao (`autosize`).
+- **[`select.md`](./components/select.md)**: Chọn đơn `<Select>` và chọn nhiều `<MultiSelect>`, tìm kiếm client/server, menu filters, skeleton infinite scroll.
+- **[`checkbox.md`](./components/checkbox.md)**: Hộp kiểm `<Checkbox>` và nhóm `<CheckboxGroup>`, trạng thái indeterminate, bố cục flex.
+- **[`radio.md`](./components/radio.md)**: Nút chọn 1 phương án `<Radio>` và nhóm `<RadioGroup>`, hỗ trợ giao diện dạng thẻ card.
+- **[`toggle.md`](./components/toggle.md)**: Công tắc gạt `<Toggle>` (Switch), hỗ trợ icon bật/tắt và nhãn mô tả.
+- **[`slider.md`](./components/slider.md)**: Thanh trượt `<Slider>` chọn số hoặc dải giá trị (Radix UI Slider).
+
+### Data Display
+- **[`table.md`](./components/table.md)**: Bảng dữ liệu mạnh mẽ `<Table>` (TanStack Table v9), sắp xếp, lọc cột, phân trang, resize cột.
+- **[`badge.md`](./components/badge.md)**: Huy hiệu `<Badge>` đếm số, chấm trạng thái (dot), gắn góc avatar/nút.
+- **[`empty.md`](./components/empty.md)**: Màn hình trống `<Empty>` hiển thị khi không có dữ liệu kèm nút hành động CTA.
+- **[`carousel.md`](./components/carousel.md)**: Trình chiếu slide `<Carousel>`, điều hướng nút bấm, autoplay, pagination dots.
+- **[`collapse.md`](./components/collapse.md)**: Khối thu gọn `<Collapse>` (Accordion), hỗ trợ mở đơn mục hoặc đa mục.
+
+### Feedback & Status
+- **[`alert.md`](./components/alert.md)**: Khung cảnh báo inline `<Alert>` (success, error, warning, info), nút đóng dismiss.
+- **[`skeleton.md`](./components/skeleton.md)**: Khung placeholder nhấp nháy `<Skeleton>` giả lập layout đang tải.
+- **[`toast.md`](./components/toast.md)**: Thông báo góc màn hình `<Toast>` (Sonner), hỗ trợ promise toast.
+
+### Navigation & Overlays
+- **[`tabs.md`](./components/tabs.md)**: Chuyển đổi thẻ `<Tabs>`, thanh chỉ thị hoạt họa mượt mà.
+- **[`dropdown.md`](./components/dropdown.md)**: Menu thả xuống `<Dropdown>` cho các thao tác phụ.
+- **[`modal.md`](./components/modal.md)**: Hộp thoại `<Modal>`, khóa cuộn màn hình, hiệu ứng animation.
+- **[`confirm.md`](./components/confirm.md)**: Hộp thoại xác nhận nguy hiểm `<Confirm>` (Xóa, Hủy) kèm loading state.
+- **[`popover.md`](./components/popover.md)**: Khung nổi `<Popover>` neo theo phần tử (Floating UI).
+- **[`tooltip.md`](./components/tooltip.md)**: Chú thích nhanh `<Tooltip>` khi hover/focus.
+
+### Date & Time Pickers
+- **[`datepicker.md`](./components/datepicker.md)**: Bộ chọn ngày `<DatePicker>`, hỗ trợ các preset (Hôm nay, Hôm qua).
+- **[`daterangepicker.md`](./components/daterangepicker.md)**: Bộ chọn khoảng ngày `<DateRangePicker>`.
+- **[`timepicker.md`](./components/timepicker.md)**: Bộ chọn giờ phút giây `<TimePicker>` cột cuộn trực quan.
+- **[`timerangepicker.md`](./components/timerangepicker.md)**: Bộ chọn khoảng thời gian `<TimeRangePicker>`.
+- **[`datetimepicker.md`](./components/datetimepicker.md)**: Bộ chọn ngày và giờ kết hợp `<DateTimePicker>`.
+- **[`datetimerangepicker.md`](./components/datetimerangepicker.md)**: Bộ chọn khoảng ngày và giờ `<DateTimeRangePicker>`.
+
+### File & Media Upload
+- **[`upload-file.md`](./components/upload-file.md)**: Tải tệp tin đa năng `<UploadFile>`, thanh tiến trình, kéo thả.
+- **[`upload-avatar.md`](./components/upload-avatar.md)**: Tải ảnh đại diện `<UploadAvatar>` hình tròn kèm xem trước.
+- **[`upload-image.md`](./components/upload-image.md)**: Tải nhiều ảnh `<UploadImage>` (Dropzone / Picture Wall), tích hợp modal crop ảnh.
+- **[`file-preview.md`](./components/file-preview.md)**: Xem trước tệp tin `<FilePreview>` (ảnh, tài liệu, video).
+
+---
+
+## 4. Danh mục Hooks
+
+Tài liệu chi tiết của các hooks được lưu trữ tại thư mục [`hooks/`](./hooks/):
+
+### Core Hooks (`@openway/ui`)
+- **[`useInfiniteScroll`](./hooks/useInfiniteScroll.md)**: Cơ chế tải vô tận thuần React 19 qua native `IntersectionObserver`, zero scroll event listener, an toàn với mutex lock.
+- **[`useDebounce` & `useDebouncedCallback`](./hooks/useDebounce.md)**: Tối ưu hiệu năng, chống spam API cho giá trị tìm kiếm hoặc hàm callback.
+
+### TanStack Query v5 Adapters (`@openway/ui/query`)
+- **[`useTableQuery`](./hooks/useTableQuery.md)**: Kết nối TanStack Query v5 với `<Table />`, quản lý phân trang, sorting, column filtering và `keepPreviousData`.
+- **[`useSelectInfiniteQuery`](./hooks/useSelectInfiniteQuery.md)**: Kết nối TanStack Query v5 với `<Select />` và `<MultiSelect />`, tự động cuộn tải trang tiếp, debounce từ khóa và Skeleton loading.
+
+---
+
+## 5. Quy chuẩn Thiết kế (Design Tokens)
+
+1. **Zero `any`**: 100% các component và hook đều được khai báo TypeScript chặt chẽ, type-safe.
+2. **5 Kích thước Chuẩn (`size`)**: `xs` (24px), `sm` (32px), `md` (40px - chuẩn form), `lg` (48px), `xl` (56px).
+3. **Độ Bo Góc Chuẩn (`radius`)**: `none` (0px), `sm` (4px), `md` (6px), `lg` (8px - chuẩn mặc định), `xl` (12px), `full` (tròn).
+4. **Dark Mode**: Toàn bộ component hỗ trợ tự động thích ứng qua selector `dark:`.

package/docs/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: openway-ui
+description: Comprehensive guide and API reference for the OpenWay UI Design System (@openway/ui). Use this skill whenever generating, modifying, or refactoring UI components, forms, tables, modals, pickers, or infinite scroll queries.
+---
+
+# OpenWay UI Design System Skill
+
+This skill teaches the Antigravity agent how to leverage the `@openway/ui` component library effectively when building user interfaces.
+
+## Quick Lookup by Functional Need
+
+When the user asks for:
+- **Button, action trigger**: Use `<Button>` or `<IconButton>` ([docs/components/button.md](./components/button.md)).
+- **Text, number input**: Use `<Input>` ([docs/components/input.md](./components/input.md)).
+- **Long text input**: Use `<Textarea>` ([docs/components/textarea.md](./components/textarea.md)).
+- **Dropdown single/multi select**: Use `<Select>` or `<MultiSelect>` ([docs/components/select.md](./components/select.md)).
+- **Server pagination / Infinite scroll dropdown**: Use `<Select>` with `useSelectInfiniteQuery` from `@openway/ui/query` ([docs/components/select.md](./components/select.md)).
+- **Checkboxes**: Use `<Checkbox>` or `<CheckboxGroup>` ([docs/components/checkbox.md](./components/checkbox.md)).
+- **Radio options**: Use `<Radio>` or `<RadioGroup>` ([docs/components/radio.md](./components/radio.md)).
+- **Switch / Toggle**: Use `<Toggle>` ([docs/components/toggle.md](./components/toggle.md)).
+- **Data Table**: Use `<Table>` ([docs/components/table.md](./components/table.md)).
+- **Modal / Popup dialog**: Use `<Modal>` or `<Confirm>` ([docs/components/modal.md](./components/modal.md), [docs/components/confirm.md](./components/confirm.md)).
+- **Tooltip**: Use `<Tooltip>` ([docs/components/tooltip.md](./components/tooltip.md)).
+- **Inline Alert / Notification**: Use `<Alert>` ([docs/components/alert.md](./components/alert.md)).
+- **Floating Toast**: Use `toast` ([docs/components/toast.md](./components/toast.md)).
+- **Date/Time Picker**: Use `<DatePicker>`, `<DateRangePicker>`, `<TimePicker>`, or `<DateTimePicker>` ([docs/components/datepicker.md](./components/datepicker.md)).
+- **File / Image Upload**: Use `<UploadFile>`, `<UploadAvatar>`, or `<UploadImage>` ([docs/components/upload-image.md](./components/upload-image.md)).
+- **Infinite scroll list**: Use `useInfiniteScroll` from `@openway/ui` ([docs/hooks/useInfiniteScroll.md](./hooks/useInfiniteScroll.md)).
+- **Server-side Table Query**: Use `useTableQuery` from `@openway/ui/query` ([docs/hooks/useTableQuery.md](./hooks/useTableQuery.md)).
+- **Server-side Select Infinite Query**: Use `useSelectInfiniteQuery` from `@openway/ui/query` ([docs/hooks/useSelectInfiniteQuery.md](./hooks/useSelectInfiniteQuery.md)).
+- **Debounce Value / Callback**: Use `useDebounce` or `useDebouncedCallback` ([docs/hooks/useDebounce.md](./hooks/useDebounce.md)).
+
+## Code Generation Guidelines
+
+1. **Imports**:
+   ```tsx
+   import { Button, Input, Select, Table, Modal } from "@openway/ui";
+   // For TanStack Query server integration:
+   import { useSelectInfiniteQuery } from "@openway/ui/query";
+   ```
+2. **Zero `any`**:
+   Always type props, states, and option entities strictly:
+   ```tsx
+   interface Department {
+     id: string;
+     name: string;
+   }
+   const options: SelectOptionItem<Department>[] = ...;
+   ```
+3. **Accessibility (WAI-ARIA)**:
+   Always supply `aria-label` when using `<IconButton>`.
+   Always associate labels with inputs using `label` prop.
+4. **Tailwind CSS v4 Tokens**:
+   Rely on theme tokens (`primary`, `secondary`, `neutral`, `error`, `success`, `warning`, `info`) rather than raw hex codes (`#123456`).

package/docs/components/alert.md

@@ -0,0 +1,246 @@
+# 📢 Alert Component (`@owa/ui`)
+
+Component **Alert** hiển thị thông báo, cảnh báo theo ngữ cảnh (Inline Alert / Banner) với hiệu năng cao, thiết kế chuẩn **Design System**, **Pure Stateless Component** (0 dependencies) và hỗ trợ đầy đủ **WAI-ARIA Accessibility**.
+
+---
+
+## 🌟 Điểm nổi bật
+
+- **Pure Stateless Component**: Hoàn toàn không phụ thuộc vào global store (Zustand/Redux). Render trực tiếp tại bất kỳ vị trí nào trong cây JSX.
+- **Tự động đóng thông minh (`closable`)**: Mặc định `closable={true}`, khi bấm nút `(X)` Alert sẽ **tự động đóng/ẩn ngay lập tức** mà không bắt buộc phải viết hàm `onClose`. Nếu có truyền callback `onClose`, Alert sẽ tự động kích hoạt callback này.
+- **Hỗ trợ linh hoạt cả `description` & `children`**: Cho phép truyền nội dung mô tả qua prop `description` (chuỗi text hoặc JSX ngắn) hoặc bọc qua `children` (JSX phức tạp).
+- **5 Kích thước tiêu chuẩn (`size`)**: `xs`, `sm`, `md` *(mặc định)*, `lg`, `xl` với typography và spacing được căn chỉnh chính xác.
+- **6 Biến thể giao diện (`variant`)**:
+  - `soft` *(mặc định)*: Nền pastel nhạt, viền mờ 2px tinh tế.
+  - `filled`: Nền màu đậm, chữ trắng tương phản cao.
+  - `outline`: Nền trắng, viền rõ nét theo màu chủ đề.
+  - `accent-left`: Nền pastel kèm viền nhấn bên trái dày 4px (`border-l-4`).
+  - `ghost`: Nền và viền trong suốt.
+  - `other`: Bỏ qua các class màu mặc định, tự do tùy biến màu sắc qua `className`.
+- **7 Chủ đề màu sắc (`color`)**: `primary`, `secondary`, `neutral`, `error`, `success`, `warning`, `info` *(mặc định)*.
+- **Tùy chỉnh bo góc (`radius`)**: `none`, `sm`, `md`, `lg` *(mặc định)*, `xl`, `full`.
+- **Chế độ Banner (`banner`)**: Chiều rộng 100% (`w-full`), góc vuông phẳng (`rounded-none`), không viền 2 bên (`border-x-0`), thích hợp gắn cố định trên đầu trang.
+- **Hỗ trợ Icon thông minh (`icon`)**:
+  - Tự động hiển thị icon SVG chuẩn theo `color` (`CheckCircleIcon`, `AlertTriangleIcon`, `AlertCircleIcon`, `InfoCircleIcon`).
+  - Tắt icon dễ dàng với `icon={false}`.
+  - Hỗ trợ truyền custom icon dạng JSX (`ReactNode`).
+- **Action Slot (`action`)**: Vùng chuyên biệt để chèn nút bấm, liên kết thao tác nhanh.
+- **Chuẩn Accessibility (A11y)**:
+  - Tự động thiết lập `role="alert"` và `aria-live="assertive"` cho các trạng thái nguy cấp (`error`, `warning`).
+  - Thiết lập `role="status"` và `aria-live="polite"` cho các trạng thái thông thường (`info`, `success`, `primary`, `secondary`, `neutral`).
+
+---
+
+## 🚀 Cài đặt & Import
+
+```tsx
+import { Alert } from "@owa/ui";
+import type { AlertProps, AlertColor, AlertVariant, AlertSize, AlertRadius } from "@owa/ui";
+```
+
+---
+
+## 📖 Hướng dẫn sử dụng
+
+### 1. Cách sử dụng cơ bản (Inline Alert)
+
+Bạn có thể truyền nội dung thông báo qua prop `description` hoặc qua thẻ con `children`:
+
+```tsx
+import { Alert } from "@owa/ui";
+
+// Cách 1: Sử dụng prop description (ngắn gọn)
+export function BasicAlertExample() {
+  return (
+    <Alert
+      color="info"
+      variant="soft"
+      title="Thông tin hệ thống"
+      description="Hệ thống sẽ tiến hành bảo trì định kỳ vào cuối tuần này."
+    />
+  );
+}
+
+// Cách 2: Sử dụng children (dành cho JSX tùy biến)
+export function ChildrenAlertExample() {
+  return (
+    <Alert color="success" title="Đã lưu thành công!">
+      <p className="mt-1">Dữ liệu hồ sơ của bạn đã được cập nhật.</p>
+    </Alert>
+  );
+}
+```
+
+---
+
+### 2. Tự động đóng thông báo (`closable` & `onClose`)
+
+Nút đóng `(X)` mặc định luôn bật (`closable=true`). Người dùng có thể click để tắt thông báo ngay mà **không cần truyền bất kỳ hàm nào**:
+
+```tsx
+// 1. Tự động đóng/ẩn ngay khi click (x) mà không cần viết thêm hàm gì:
+<Alert title="Thông báo" description="Click nút x bên phải sẽ tự ẩn thông báo này." />
+
+// 2. Tự động đóng kèm theo callback onClose (nếu muốn xử lý thêm logic):
+<Alert
+  title="Thông báo"
+  description="Thực hiện logic khi người dùng tắt thông báo."
+  onClose={() => console.log("Alert đã được đóng!")}
+/>
+
+// 3. Tắt nút đóng (không cho người dùng đóng):
+<Alert closable={false} title="Thông báo bắt buộc" description="Nội dung không thể đóng." />
+```
+
+---
+
+### 3. Các chủ đề màu sắc (`color`)
+
+Component cung cấp 7 tông màu chuẩn Design System:
+
+```tsx
+<Alert color="primary" title="Primary" description="Thông báo chính của ứng dụng." />
+<Alert color="secondary" title="Secondary" description="Thông báo phụ bổ sung thông tin." />
+<Alert color="neutral" title="Neutral" description="Thông báo trung tính dạng ghi chú." />
+<Alert color="info" title="Info" description="Thông tin hướng dẫn sử dụng." />
+<Alert color="success" title="Success" description="Dữ liệu đã được lưu thành công." />
+<Alert color="warning" title="Warning" description="Dung lượng bộ nhớ đã đạt mức 90%." />
+<Alert color="error" title="Error" description="Không thể kết nối đến máy chủ." />
+```
+
+---
+
+### 4. Các biến thể giao diện (`variant`)
+
+```tsx
+// 1. Soft (Mặc định)
+<Alert variant="soft" color="success" title="Soft Variant" description="Nền pastel nhạt, chữ và viền cùng tông màu." />
+
+// 2. Filled
+<Alert variant="filled" color="error" title="Filled Variant" description="Nền màu đậm, độ tương phản cao, nổi bật." />
+
+// 3. Outline
+<Alert variant="outline" color="primary" title="Outline Variant" description="Nền trắng, viền rõ nét theo màu chủ đề." />
+
+// 4. Accent Left
+<Alert variant="accent-left" color="warning" title="Accent Left Variant" description="Nền pastel kèm viền nhấn dày 4px bên trái." />
+
+// 5. Ghost
+<Alert variant="ghost" color="info" title="Ghost Variant" description="Nền và viền trong suốt, chỉ hiển thị icon và chữ." />
+
+// 6. Other (Tự do tùy biến)
+<Alert
+  variant="other"
+  className="bg-purple-100 text-purple-900 border-2 border-purple-300"
+  title="Other Variant"
+  description="Tự do áp dụng class Tailwind tùy chỉnh bên ngoài."
+/>
+```
+
+---
+
+### 5. Kích cỡ (`size`) & Độ bo góc (`radius`)
+
+```tsx
+// 5 kích cỡ tiêu chuẩn
+<Alert size="xs" title="Size XS" description="Thông báo kích cỡ rất nhỏ" />
+<Alert size="sm" title="Size SM" description="Thông báo kích cỡ nhỏ" />
+<Alert size="md" title="Size MD" description="Thông báo kích cỡ vừa (mặc định)" />
+<Alert size="lg" title="Size LG" description="Thông báo kích cỡ lớn" />
+<Alert size="xl" title="Size XL" description="Thông báo kích cỡ rất lớn" />
+
+// Tùy chỉnh độ bo góc
+<Alert radius="none" title="Không bo góc" description="Góc vuông 0px" />
+<Alert radius="sm" title="Bo góc nhỏ" description="rounded-sm" />
+<Alert radius="md" title="Bo góc vừa" description="rounded-md" />
+<Alert radius="lg" title="Bo góc lớn" description="rounded-lg (mặc định)" />
+<Alert radius="xl" title="Bo góc rất lớn" description="rounded-xl" />
+<Alert radius="full" title="Bo tròn" description="rounded-2xl" />
+```
+
+---
+
+### 6. Chế độ Banner (`banner`)
+
+Chế độ Banner giúp thông báo trải rộng toàn bộ chiều ngang (`w-full`), loại bỏ bo góc (`rounded-none`) và viền 2 bên, rất phù hợp gắn cố định trên cùng màn hình:
+
+```tsx
+<Alert
+  banner
+  color="error"
+  title="Sự cố đường truyền"
+  description="Hiện tại một số dịch vụ thanh toán đang bị gián đoạn."
+  action={
+    <button className="text-xs underline font-medium cursor-pointer">
+      Xem chi tiết
+    </button>
+  }
+/>
+```
+
+---
+
+### 7. Icon tùy biến & Action Slot
+
+```tsx
+import { Alert, Button } from "@owa/ui";
+
+export function AdvancedAlertExample() {
+  return (
+    <div className="space-y-4">
+      {/* Ẩn Icon */}
+      <Alert icon={false} color="neutral" title="Không có icon" description="Nội dung không kèm icon đầu dòng." />
+
+      {/* Custom Icon bằng JSX */}
+      <Alert
+        icon={<span className="text-lg">🚀</span>}
+        color="primary"
+        title="Tính năng mới"
+        description="Trải nghiệm phiên bản 2.0 với nhiều cải tiến vượt bậc."
+      />
+
+      {/* Action Slot kèm Button */}
+      <Alert
+        color="info"
+        title="Bản cập nhật mới sẵn sàng"
+        description="Vui lòng tải lại ứng dụng để áp dụng bản vá mới nhất."
+        action={
+          <Button size="xs" variant="filled" color="info">
+            Cập nhật ngay
+          </Button>
+        }
+      />
+    </div>
+  );
+}
+```
+
+---
+
+## 🛠️ API Reference (`AlertProps`)
+
+Component `Alert` nhận các props mở rộng từ thẻ HTML chuẩn `HTMLAttributes<HTMLDivElement>` (ngoại trừ prop `title`):
+
+| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Kích cỡ của Alert (ảnh hưởng padding, font size, icon size). |
+| `variant` | `"soft" \| "filled" \| "outline" \| "accent-left" \| "ghost" \| "other"` | `"soft"` | Biến thể giao diện và phong cách hiển thị màu sắc. |
+| `color` | `"primary" \| "secondary" \| "neutral" \| "error" \| "success" \| "warning" \| "info"` | `"info"` | Chủ đề màu sắc theo Design System. |
+| `radius` | `"none" \| "sm" \| "md" \| "lg" \| "xl" \| "full"` | `"lg"` | Độ bo góc của khung thông báo. |
+| `title` | `ReactNode` | `undefined` | Tiêu đề in đậm của Alert. |
+| `description` | `ReactNode` | `undefined` | Nội dung mô tả ngắn của thông báo. |
+| `children` | `ReactNode` | `undefined` | Nội dung mô tả tùy biến bằng JSX bên trong Alert. |
+| `icon` | `ReactNode \| boolean` | `true` | Icon đầu thông báo: `true` = tự động theo màu, `false` = ẩn, `ReactNode` = custom icon. |
+| `action` | `ReactNode` | `undefined` | Phần tử hành động phụ nằm ở góc phải (Button, Link, Tag). |
+| `closable` | `boolean` | `true` | Hiển thị nút đóng `(X)` và tự động ẩn Alert khi click. |
+| `onClose` | `() => void` | `undefined` | Callback được gọi khi người dùng bấm nút đóng. |
+| `closeAriaLabel` | `string` | `"Close alert"` | Nhãn trợ năng (accessibility) cho nút đóng. |
+| `banner` | `boolean` | `false` | Bật chế độ Banner: Full width (`w-full`), góc vuông (`rounded-none`), không viền 2 bên. |
+| `titleClassName` | `string` | `""` | Tùy biến className riêng cho phần tiêu đề (`title`). |
+| `descriptionClassName` | `string` | `""` | Tùy biến className riêng cho phần nội dung (`description` / `children`). |
+| `actionClassName` | `string` | `""` | Tùy biến className riêng cho vùng `action`. |
+| `iconClassName` | `string` | `""` | Tùy biến className riêng cho vùng chứa icon. |
+| `closeButtonClassName` | `string` | `""` | Tùy biến className riêng cho nút đóng `(X)`. |
+| `className` | `string` | `""` | Class tùy biến cho khung container bao ngoài. |
+| `role` | `string` | Tự động | ARIA role (`"alert"` cho error/warning, `"status"` cho các màu khác). |
+| `ref` | `Ref<HTMLDivElement>` | `undefined` | Ref chuyển tiếp đến phần tử thẻ `<div>` bọc ngoài. |