@openway/ui 1.0.0 → 1.0.1

package/docs/components/carousel.md

@@ -0,0 +1,354 @@
+# 🎠 Carousel Component (`@owa/ui`)
+
+Component **Carousel** (băng chuyền / slider) hiện đại, hiệu năng cao, thiết kế chuẩn **Compound Components Pattern** (`<Carousel>`, `<CarouselContent>`, `<CarouselSlide>`, `<CarouselPrevious>`, `<CarouselNext>`, `<CarouselPagination>`), hỗ trợ **Pointer Drag/Touch Gestures**, **Autoplay thông minh**, **Infinite Looping**, **Glassmorphism Design**, **Dynamic Slide Registration**, **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 các thành phần `<Carousel>`, `<CarouselContent>`, `<CarouselSlide>`, `<CarouselPrevious>`, `<CarouselNext>`, `<CarouselPagination>`, mang lại khả năng tùy biến bố cục không giới hạn.
+- **Dynamic Slide Registration (`registerSlide` / `unregisterSlide`)**: Tự động đếm và đồng bộ số lượng slide (`totalSlides`) theo thời gian thực dựa trên vòng đời của từng `<CarouselSlide>`, không phụ thuộc vào thứ tự hay cách thức render children.
+- **Tương tác kéo vuốt mượt mà (Touch & Pointer Gestures)**: Hỗ trợ kéo vuốt cả chuột và màn hình cảm ứng mượt mà qua Pointer Events (`setPointerCapture`), có hiệu ứng lực cản (drag resistance) khi kéo quá mép đầu/cuối.
+- **Autoplay thông minh**: Tự động chuyển slide theo chu kỳ `interval`, tự động tạm dừng khi rê chuột (`pauseOnHover`), khi focus (`pauseOnFocus`), hoặc khi đang kéo chuột/vuốt màn hình.
+- **Vòng lặp vô hạn (Infinite Loop)**: Tự động tính toán chuyển động vòng tròn liền mạch giữa slide đầu và slide cuối.
+- **Hiển thị nhiều slide cùng lúc (Multi-slides)**: Hỗ trợ `slidesToShow`, `slidesToScroll`, và khoảng cách gap `spacing` linh hoạt (nhận `number` theo px hoặc chuỗi CSS).
+- **Thiết kế Kính Mờ (Frosted Glass / Glassmorphism)**: Phong cách nút và thanh phân trang kính mờ hiện đại với `backdrop-blur-md`, tự động thích ứng hoàn hảo cho cả Light Mode và Dark Mode.
+- **Định vị mặc định thông minh**:
+  - `CarouselPrevious`: Nút lùi kính mờ đặt sát mép trái (`absolute left-2 top-1/2 -translate-y-1/2`).
+  - `CarouselNext`: Nút tiến kính mờ đặt sát mép phải (`absolute right-2 top-1/2 -translate-y-1/2`).
+  - `CarouselPagination`: Thanh phân trang đặt tại đáy giữa (`absolute bottom-2.5 left-1/2 -translate-x-1/2`).
+  - Dễ dàng ghi đè hoặc đặt vào custom toolbar/slot bằng cách truyền `className`.
+- **4 Biến thể nút điều hướng (`variant`)**: `glass` (*mặc định*), `filled`, `outline`, `ghost`.
+- **3 Kiểu dáng phân trang (`type`)**: `dots` (*mặc định*), `line` (thanh ngang co giãn), `fraction` (tỉ lệ dạng `1 / 4`).
+- **3 Kích thước tiêu chuẩn (`size`)**: `sm`, `md` (*mặc định*), `lg`.
+- **6 Kiểu bo góc (`radius`)**: `none`, `sm`, `md` (*mặc định*), `lg`, `xl`, `full`.
+- **Chế độ Controlled & Uncontrolled**: Hỗ trợ đầy đủ `currentIndex` + `onIndexChange` (Controlled) và `defaultIndex` (Uncontrolled).
+- **Điều hướng bàn phím & Trợ năng (A11y)**: Hỗ trợ `role="region"`, `role="tablist"`, `role="tab"`, `role="group"`, `aria-roledescription="carousel"`, phím `ArrowLeft`, `ArrowRight`, `Home`, `End`.
+- **Safe Config Fallback**: Tích hợp `getSafeConfig` từ `@/utils/function` giúp component luôn an toàn, không bị crash kể cả khi truyền prop không hợp lệ.
+
+---
+
+## 🚀 Cài đặt & Import
+
+```tsx
+import {
+  Carousel,
+  CarouselContent,
+  CarouselSlide,
+  CarouselPrevious,
+  CarouselNext,
+  CarouselPagination,
+  useCarousel,
+  CarouselContext,
+  useCarouselContext,
+  carouselSizeConfig,
+  carouselRadiusConfig,
+  carouselNavVariantConfig,
+  carouselDotStyleConfig,
+  carouselGlassPaginationWrapper,
+} from "@owa/ui";
+
+import type {
+  CarouselProps,
+  CarouselContentProps,
+  CarouselSlideProps,
+  CarouselNavigationProps,
+  CarouselPaginationProps,
+  CarouselSize,
+  CarouselRadius,
+  CarouselPaginationType,
+  CarouselArrowPosition,
+  CarouselNavigationVariant,
+  CarouselContextValue,
+} from "@owa/ui";
+```
+
+---
+
+## 📖 Hướng dẫn sử dụng
+
+### 1. Sử dụng cơ bản (Compound Components)
+
+```tsx
+import {
+  Carousel,
+  CarouselContent,
+  CarouselSlide,
+  CarouselPrevious,
+  CarouselNext,
+  CarouselPagination,
+} from "@owa/ui";
+
+export function BasicCarousel() {
+  return (
+    <Carousel loop className="w-full max-w-lg shadow-lg">
+      <CarouselContent>
+        <CarouselSlide>
+          <div className="h-56 bg-primary-600 text-white flex items-center justify-center text-xl font-bold">
+            Slide 1: Khám Phá Công Nghệ
+          </div>
+        </CarouselSlide>
+        <CarouselSlide>
+          <div className="h-56 bg-primary-700 text-white flex items-center justify-center text-xl font-bold">
+            Slide 2: Trải Nghiệm Tối Ưu
+          </div>
+        </CarouselSlide>
+        <CarouselSlide>
+          <div className="h-56 bg-primary-800 text-white flex items-center justify-center text-xl font-bold">
+            Slide 3: Thiết Kế Hiện Đại
+          </div>
+        </CarouselSlide>
+      </CarouselContent>
+
+      {/* Nút điều hướng kính mờ tự động đặt sát 2 mép */}
+      <CarouselPrevious />
+      <CarouselNext />
+
+      {/* Phân trang tự động đặt ở đáy giữa */}
+      <CarouselPagination type="dots" />
+    </Carousel>
+  );
+}
+```
+
+---
+
+### 2. Tự động chuyển slide (Autoplay) & Vòng lặp vô hạn (Loop)
+
+```tsx
+<Carousel
+  autoPlay={true}
+  interval={3500}
+  transitionDuration={650}
+  loop={true}
+  pauseOnHover={true}
+  pauseOnFocus={true}
+  className="w-full max-w-xl"
+>
+  <CarouselContent>
+    <CarouselSlide>
+      <img src="/banner-1.jpg" alt="Banner 1" className="w-full h-64 object-cover" />
+    </CarouselSlide>
+    <CarouselSlide>
+      <img src="/banner-2.jpg" alt="Banner 2" className="w-full h-64 object-cover" />
+    </CarouselSlide>
+    <CarouselSlide>
+      <img src="/banner-3.jpg" alt="Banner 3" className="w-full h-64 object-cover" />
+    </CarouselSlide>
+  </CarouselContent>
+  <CarouselPrevious />
+  <CarouselNext />
+  <CarouselPagination type="line" />
+</Carousel>
+```
+
+---
+
+### 3. Hiển thị nhiều slide cùng lúc (Multi-slides Grid)
+
+```tsx
+<Carousel slidesToShow={3} slidesToScroll={1} spacing={16} loop className="w-full max-w-4xl">
+  <CarouselContent>
+    {products.map((product) => (
+      <CarouselSlide key={product.id}>
+        <div className="p-4 border border-neutral-200 dark:border-neutral-800 rounded-xl bg-white dark:bg-neutral-900 shadow-sm">
+          <img src={product.image} alt={product.name} className="h-40 w-full object-cover rounded-lg" />
+          <h3 className="mt-2 font-semibold text-neutral-900 dark:text-white">{product.name}</h3>
+          <p className="text-primary-600 font-bold">{product.price}</p>
+        </div>
+      </CarouselSlide>
+    ))}
+  </CarouselContent>
+  <CarouselPrevious />
+  <CarouselNext />
+</Carousel>
+```
+
+---
+
+### 4. Các kiểu phân trang (Pagination Types)
+
+Hỗ trợ 3 kiểu phân trang:
+
+```tsx
+{/* 1. Dạng chấm tròn tinh gọn (mặc định) */}
+<CarouselPagination type="dots" />
+
+{/* 2. Dạng thanh gạch ngang co giãn khi active */}
+<CarouselPagination type="line" />
+
+{/* 3. Dạng phân số tỉ lệ (ví dụ: 1 / 4) */}
+<CarouselPagination type="fraction" />
+```
+
+---
+
+### 5. Biến thể nút điều hướng (Navigation Variants)
+
+Hỗ trợ 4 biến thể giao diện: `glass` (*mặc định*), `filled`, `outline`, `ghost`:
+
+```tsx
+<Carousel className="w-full max-w-lg shadow">
+  <CarouselContent>
+    <CarouselSlide><div className="h-44 bg-primary-600 text-white flex items-center justify-center">Filled Buttons</div></CarouselSlide>
+    <CarouselSlide><div className="h-44 bg-primary-700 text-white flex items-center justify-center">Filled Buttons</div></CarouselSlide>
+  </CarouselContent>
+  <CarouselPrevious variant="filled" />
+  <CarouselNext variant="filled" />
+</Carousel>
+```
+
+---
+
+### 6. Tùy biến vị trí tự do (Custom Slot / Bottom Toolbar)
+
+Bạn có thể dễ dàng đặt nút điều hướng và phân trang vào trong một thanh công cụ tùy biến dưới đáy bằng cách thêm `className="static"` hoặc class định vị mong muốn:
+
+```tsx
+<Carousel defaultIndex={1} className="w-full max-w-md border border-neutral-200 dark:border-neutral-700 p-2 rounded-xl">
+  <CarouselContent>
+    <CarouselSlide><div className="h-36 bg-linear-to-r from-primary-600 to-primary-800 text-white rounded-lg flex items-center justify-center font-semibold">Slide 1</div></CarouselSlide>
+    <CarouselSlide><div className="h-36 bg-linear-to-r from-primary-700 to-primary-900 text-white rounded-lg flex items-center justify-center font-semibold">Slide 2</div></CarouselSlide>
+    <CarouselSlide><div className="h-36 bg-linear-to-r from-primary-800 to-primary-950 text-white rounded-lg flex items-center justify-center font-semibold">Slide 3</div></CarouselSlide>
+  </CarouselContent>
+
+  {/* Custom Bottom Toolbar */}
+  <div className="flex justify-between items-center mt-3 px-2">
+    <CarouselPrevious className="static translate-y-0" variant="glass" />
+    <CarouselPagination className="static translate-x-0" type="dots" />
+    <CarouselNext className="static translate-y-0" variant="glass" />
+  </div>
+</Carousel>
+```
+
+---
+
+### 7. Chế độ Controlled Mode (Quản lý State chủ động)
+
+```tsx
+import { useState } from "react";
+import { Carousel, CarouselContent, CarouselSlide, CarouselPrevious, CarouselNext, CarouselPagination } from "@owa/ui";
+
+export function ControlledDemo() {
+  const [index, setIndex] = useState(0);
+
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center gap-3">
+        <span className="text-sm font-semibold">Slide hiện tại: {index + 1}</span>
+        <button
+          type="button"
+          onClick={() => setIndex(2)}
+          className="px-3 py-1 bg-primary-600 text-white text-xs rounded-md shadow hover:bg-primary-700"
+        >
+          Nhảy tới Slide 3
+        </button>
+      </div>
+
+      <Carousel
+        currentIndex={index}
+        onIndexChange={setIndex}
+        className="w-full max-w-md shadow"
+      >
+        <CarouselContent>
+          <CarouselSlide><div className="h-36 bg-blue-600 text-white flex items-center justify-center">Slide 1</div></CarouselSlide>
+          <CarouselSlide><div className="h-36 bg-indigo-600 text-white flex items-center justify-center">Slide 2</div></CarouselSlide>
+          <CarouselSlide><div className="h-36 bg-purple-600 text-white flex items-center justify-center">Slide 3</div></CarouselSlide>
+        </CarouselContent>
+        <CarouselPrevious />
+        <CarouselNext />
+        <CarouselPagination />
+      </Carousel>
+    </div>
+  );
+}
+```
+
+---
+
+## 📊 Bảng thuộc tính Props
+
+### `<Carousel>`
+
+| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `currentIndex` | `number` | - | Chỉ số slide đang active (sử dụng trong Controlled mode) |
+| `defaultIndex` | `number` | `0` | Chỉ số slide mặc định khi khởi tạo (Uncontrolled mode) |
+| `onIndexChange` | `(index: number) => void` | - | Callback kích hoạt khi chỉ số slide thay đổi |
+| `loop` | `boolean` | `false` | Cho phép cuộn vòng tròn vô hạn |
+| `slidesToShow` | `number` | `1` | Số lượng slide hiển thị đồng thời trên một khung nhìn |
+| `slidesToScroll` | `number` | `1` | Số lượng slide di chuyển mỗi lần cuộn |
+| `spacing` | `number \| string` | `0` | Khoảng cách gap giữa các slide (`16` hoặc `"1rem"`) |
+| `autoPlay` | `boolean` | `true` | Tự động chuyển slide định kỳ |
+| `interval` | `number` | `3000` | Thời gian chờ giữa mỗi lần tự động chuyển slide (ms) |
+| `transitionDuration` | `number` | `650` | Thời gian hiệu ứng chuyển đổi giữa các slide (ms) |
+| `pauseOnHover` | `boolean` | `true` | Tạm dừng autoplay khi rê chuột vào carousel |
+| `pauseOnFocus` | `boolean` | `true` | Tạm dừng autoplay khi focus vào carousel |
+| `draggable` | `boolean` | `true` | Cho phép kéo/vuốt bằng chuột hoặc ngón tay cảm ứng |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Kích thước chung của carousel |
+| `radius` | `"none" \| "sm" \| "md" \| "lg" \| "xl" \| "full"` | `"md"` | Bo góc của container carousel |
+| `children` | `ReactNode` | - | Các component con bên trong Carousel |
+
+---
+
+### `<CarouselContent>`
+
+| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `ref` | `Ref<HTMLDivElement>` | - | Ref đến dải trượt track |
+| `children` | `ReactNode` | - | Danh sách các `<CarouselSlide>` |
+| `className` | `string` | `""` | Tùy biến class cho container track |
+
+---
+
+### `<CarouselSlide>`
+
+| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `ref` | `Ref<HTMLDivElement>` | - | Ref đến phần tử DOM của slide |
+| `index` | `number` | - | Chỉ số vị trí của slide |
+| `children` | `ReactNode` | - | Nội dung bên trong slide |
+| `className` | `string` | `""` | Class tùy biến cho slide |
+
+---
+
+### `<CarouselPrevious>` & `<CarouselNext>`
+
+| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `ref` | `Ref<HTMLButtonElement>` | - | Ref đến phần tử button |
+| `variant` | `"glass" \| "filled" \| "outline" \| "ghost"` | `"glass"` | Biến thể hiển thị giao diện nút |
+| `icon` | `ReactNode` | `<ChevronIcon />` | Biểu tượng icon tùy biến |
+| `disabled` | `boolean` | - | Trạng thái vô hiệu hóa (tự động tính nếu không truyền) |
+| `className` | `string` | `""` | Class tùy biến (có thể dùng `static` để gỡ bỏ định vị absolute) |
+
+---
+
+### `<CarouselPagination>`
+
+| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `ref` | `Ref<HTMLDivElement>` | - | Ref đến container phân trang |
+| `type` | `"dots" \| "line" \| "fraction" \| "none"` | `"dots"` | Kiểu dáng hiển thị phân trang |
+| `clickable` | `boolean` | `true` | Cho phép người dùng click vào chấm/thanh để chuyển slide |
+| `className` | `string` | `""` | Class tùy biến |
+
+---
+
+## ⌨️ Phím tắt & Trợ năng (Accessibility)
+
+- **`role="region"` & `aria-roledescription="carousel"`**: Báo hiệu với Screen Reader đây là một vùng băng chuyền nội dung.
+- **`role="tablist"` & `role="tab"`**: Đánh dấu thanh phân trang và từng slide chỉ số chuẩn ngữ nghĩa.
+- **Phím `ArrowLeft` / `ArrowRight`**: Chuyển đổi slide trước / sau.
+- **Phím `Home` / `End`**: Nhảy nhanh về slide đầu tiên hoặc slide cuối cùng.
+- **Tập trung bàn phím (Focus Ring)**: Có viền sáng `focus-visible:ring-2 focus-visible:ring-primary-500/50` rõ ràng khi dùng phím `Tab`.
+
+---
+
+## 🧪 Kiểm thử Component (Cypress Testing)
+
+Component được kiểm thử 100% bằng **Cypress Component Testing** tại [`Carousel.cy.tsx`](Carousel.cy.tsx):
+
+```bash
+pnpm --filter @owa/ui cypress:run --spec "src/components/carousel/Carousel.cy.tsx"
+```

package/docs/components/checkbox.md

@@ -0,0 +1,252 @@
+# ☑️ Checkbox & CheckboxGroup Component (`@owa/ui`)
+
+Bộ đôi component **Checkbox** và **CheckboxGroup** chuyên nghiệp, thiết kế theo kiến trúc **Data-driven thuần túy (Pure Data-driven)**, không sử dụng React Context, loại bỏ hoàn toàn `useEffect` gây cascading render, tích hợp **Live Search (Client & Server modes)** thông qua component `Input` variant `outline`, hỗ trợ **bảo lưu mục đã chọn (Preserve Selected)** và tuân thủ chặt chẽ tiêu chuẩn **WAI-ARIA Accessibility**.
+
+---
+
+## 🌟 Điểm nổi bật
+
+### 1. Checkbox
+- **Độc lập & Tối ưu**: Không phụ thuộc vào Context, nhận props trực tiếp, hỗ trợ chuyển tiếp `ref` chuẩn React 19 mà không cần wrapper trung gian.
+- **5 Kích thước tiêu chuẩn (`size`)**: `xs`, `sm`, `md` (*mặc định*), `lg`, `xl` đồng bộ tỉ lệ ô tick, icon SVG, nhãn và văn bản chú thích.
+- **4 Biến thể giao diện (`variant`)**:
+  - `filled` (*mặc định*): Nền màu chủ đề khi được chọn.
+  - `outline`: Viền nét màu chủ đề, nền trong suốt.
+  - `soft`: Nền pastel dịu mắt (`bg-{color}-100`).
+  - `other`: Tự do tùy biến style qua `boxClassName`.
+- **7 Chủ đề màu sắc (`color`)**: `primary`, `secondary`, `error`, `success`, `warning`, `info`, `neutral`.
+- **6 Mức độ bo góc (`radius`)**: `none`, `sm`, `md` (*mặc định*), `lg`, `xl`, `full`.
+- **Trạng thái gạch ngang (`indeterminate`)**: Hỗ trợ trạng thái chọn một phần với thuộc tính chuẩn `aria-checked="mixed"` và icon trừ (`MinusIcon`).
+- **2 Vị trí đặt nhãn (`labelPlacement`)**: `right` (*mặc định*) và `left` (căn đều hai bên).
+- **Safe Config Fallback**: Sử dụng `getSafeConfig` đảm bảo component luôn an toàn, không bao giờ bị lỗi hiển thị khi nhận giá trị không hợp lệ.
+
+### 2. CheckboxGroup
+- **Kiến trúc Data-driven thuần túy**: Nhận danh sách lựa chọn qua prop `options: CheckboxOptionItem<TData>[]`. Không còn cấu trúc compound component cồng kềnh, không tốn chi phí Context Provider.
+- **Tích hợp tìm kiếm trực quan (`searchable`)**:
+  - Sử dụng component `Input` variant `outline` với icon tìm kiếm (`SearchIcon`) và nút xóa nhanh (`isClearable`).
+  - **Không làm mất focus**: Trạng thái tải ngầm hiển thị spinner ở góc phải qua `rightIcon`, không disable input trong khi người dùng đang gõ phím.
+- **2 Chế độ tìm kiếm linh hoạt (`searchMode`)**:
+  - `client` (*mặc định*): Tìm kiếm thông minh bằng thuật toán fuzzy ranking của `@tanstack/match-sorter-utils`. Hỗ trợ tìm theo đa trường dữ liệu (`searchField`) hoặc custom function (`filterFn`).
+  - `server`: Tìm kiếm qua API máy chủ với `onSearch` và bộ đệm thời gian `debounceMs`.
+- **Bảo lưu mục đã chọn (`preserveSelected`)**: Tự động ghim lại các mục đã chọn lên đầu danh sách khi chuyển đổi từ khóa tìm kiếm mới, quản lý bộ nhớ thông minh (chỉ lưu các mục thực sự được tick chọn).
+- **2 Bố cục sắp xếp (`orientation`)**: `vertical` (*mặc định*) và `horizontal`.
+
+---
+
+## 🚀 Cài đặt & Import
+
+```tsx
+import { Checkbox, CheckboxGroup } from "@owa/ui";
+import type {
+  CheckboxProps,
+  CheckboxGroupProps,
+  CheckboxOptionItem,
+  CheckboxSize,
+  CheckboxVariant,
+  CheckboxColor,
+  CheckboxRadius,
+  CheckboxLabelPlacement,
+  CheckboxSearchMode,
+} from "@owa/ui";
+```
+
+---
+
+## 📖 Hướng dẫn sử dụng
+
+### 1. Sử dụng Checkbox đơn lẻ
+
+```tsx
+import { useState } from "react";
+import { Checkbox } from "@owa/ui";
+
+export function SingleCheckboxExample() {
+  const [agree, setAgree] = useState(false);
+
+  return (
+    <Checkbox
+      checked={agree}
+      onChange={(e) => setAgree(e.target.checked)}
+      label="Tôi đồng ý với các điều khoản và chính sách dịch vụ"
+      helperText="Vui lòng đọc kỹ trước khi tiếp tục"
+      config={{ isRequired: true }}
+    />
+  );
+}
+```
+
+---
+
+### 2. CheckboxGroup cơ bản (Data-driven)
+
+```tsx
+import { useState } from "react";
+import { CheckboxGroup } from "@owa/ui";
+
+export function BasicGroupExample() {
+  const [selected, setSelected] = useState<string[]>(["react"]);
+
+  return (
+    <CheckboxGroup
+      label="Kỹ năng công nghệ"
+      helperText="Chọn các kỹ năng bạn có kinh nghiệm làm việc"
+      value={selected}
+      onChange={setSelected}
+      color="primary"
+      orientation="horizontal"
+      options={[
+        { value: "react", label: "React 19" },
+        { value: "vue", label: "Vue.js 3" },
+        { value: "tailwind", label: "Tailwind CSS v4" },
+        { value: "typescript", label: "TypeScript" },
+      ]}
+    />
+  );
+}
+```
+
+---
+
+### 3. Tìm kiếm Client Mode (Fuzzy Search & Đa trường)
+
+```tsx
+import { useState } from "react";
+import { CheckboxGroup } from "@owa/ui";
+
+const frameworks = [
+  { value: "react", label: "React JS", code: "FE-01", description: "Facebook library" },
+  { value: "vue", label: "Vue JS", code: "FE-02", description: "Progressive framework" },
+  { value: "angular", label: "Angular", code: "FE-03", description: "Google platform" },
+  { value: "svelte", label: "Svelte", code: "FE-04", description: "Cybernetically enhanced" },
+];
+
+export function ClientSearchExample() {
+  const [selected, setSelected] = useState<string[]>(["react"]);
+
+  return (
+    <CheckboxGroup
+      label="Tìm kiếm Framework"
+      searchable
+      searchField={["label", "code", "description"]}
+      searchPlaceholder="Tìm theo tên, mã code hoặc mô tả..."
+      preserveSelected
+      value={selected}
+      onChange={setSelected}
+      options={frameworks}
+    />
+  );
+}
+```
+
+---
+
+### 4. Tìm kiếm Server Mode (Gọi API với Debounce & Bảo lưu mục đã chọn)
+
+```tsx
+import { useState } from "react";
+import { CheckboxGroup } from "@owa/ui";
+
+export function ServerSearchExample() {
+  const [selectedProducts, setSelectedProducts] = useState<string[]>([]);
+
+  const handleSearchProducts = async (query: string) => {
+    const res = await fetch(
+      `https://dummyjson.com/products/search?q=${encodeURIComponent(query)}&limit=5`
+    );
+    if (!res.ok) throw new Error("API request failed");
+    const data = await res.json();
+    
+    return data.products.map((p: any) => ({
+      value: String(p.id),
+      label: p.title,
+      description: `$${p.price} - ${p.category}`,
+    }));
+  };
+
+  return (
+    <CheckboxGroup
+      label="Chọn sản phẩm"
+      searchable
+      searchMode="server"
+      debounceMs={300}
+      onSearch={handleSearchProducts}
+      searchPlaceholder="Tìm kiếm sản phẩm từ máy chủ..."
+      preserveSelected
+      value={selectedProducts}
+      onChange={setSelectedProducts}
+      color="info"
+    />
+  );
+}
+```
+
+---
+
+## 🎛️ Bảng Props & API Reference
+
+### `CheckboxProps`
+
+Kế thừa `Omit<InputHTMLAttributes<HTMLInputElement>, "size" | "type">`:
+
+| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Kích cỡ ô chọn, icon và nhãn |
+| `variant` | `'filled' \| 'outline' \| 'soft' \| 'other'` | `'filled'` | Kiểu dáng hiển thị của box |
+| `color` | `'primary' \| 'secondary' \| 'error' \| 'success' \| 'warning' \| 'info' \| 'neutral'` | `'primary'` | Chủ đề màu sắc |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'` | Mức độ bo góc |
+| `config` | `CheckboxConfig` | `undefined` | Cấu hình cờ trạng thái (`isRequired`, `indeterminate`, `isLoading`, `isInvalid`,...) |
+| `disabled` | `boolean` | `false` | Vô hiệu hóa tương tác |
+| `readOnly` | `boolean` | `false` | Chế độ chỉ đọc |
+| `labelPlacement` | `'right' \| 'left'` | `'right'` | Vị trí hiển thị nhãn |
+| `label` | `ReactNode` | `undefined` | Nhãn văn bản cạnh ô checkbox |
+| `helperText` | `ReactNode` | `undefined` | Chú thích bên dưới |
+| `errorMessage` | `ReactNode` | `undefined` | Thông báo lỗi |
+| `icon` | `ReactNode` | `CheckIcon` | Icon tùy biến khi checked |
+| `indeterminateIcon` | `ReactNode` | `MinusIcon` | Icon tùy biến khi indeterminate |
+
+---
+
+### `CheckboxGroupProps<TData = unknown>`
+
+Kế thừa `Omit<HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue" | "children">`:
+
+| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `options` | `CheckboxOptionItem<TData>[]` | `[]` | Mảng dữ liệu các lựa chọn (Data-driven) |
+| `value` | `string[]` | `undefined` | Danh sách giá trị đã chọn (Controlled) |
+| `defaultValue` | `string[]` | `[]` | Danh sách giá trị mặc định (Uncontrolled) |
+| `onChange` | `(values: string[]) => void` | `undefined` | Callback khi danh sách chọn thay đổi |
+| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Bố cục sắp xếp các mục |
+| `searchable` | `boolean` | `false` | Bật/tắt thanh tìm kiếm |
+| `searchMode` | `'client' \| 'server'` | `'client'` | Chế độ tìm kiếm phía client hoặc gọi API server |
+| `searchField` | `string \| string[]` | `'label'` | Các trường dữ liệu dùng để tìm kiếm |
+| `filterFn` | `(item: CheckboxOptionItem<TData>, query: string) => boolean` | `undefined` | Hàm lọc tùy biến phía client |
+| `onSearch` | `(query: string) => Promise<CheckboxOptionItem<TData>[]>` | `undefined` | Hàm gọi API tìm kiếm phía server |
+| `debounceMs` | `number` | `300` | Thời gian trễ gọi hàm `onSearch` (ms) |
+| `preserveSelected` | `boolean` | `true` | Bảo lưu các mục đã chọn khi từ khóa tìm kiếm thay đổi |
+| `emptyText` | `ReactNode` | `'Không tìm thấy kết quả'` | Thông báo khi không có kết quả |
+| `size` | `CheckboxSize` | `'md'` | Kích cỡ truyền xuống toàn bộ checkbox con |
+| `color` | `CheckboxColor` | `'primary'` | Màu sắc truyền xuống toàn bộ checkbox con |
+| `variant` | `CheckboxVariant` | `'filled'` | Biến thể truyền xuống toàn bộ checkbox con |
+| `radius` | `CheckboxRadius` | `undefined` | Bo góc truyền xuống toàn bộ checkbox con |
+| `disabled` | `boolean` | `false` | Vô hiệu hóa toàn bộ nhóm |
+| `isReadOnly` | `boolean` | `false` | Chế độ chỉ đọc cho toàn bộ nhóm |
+| `isLoading` | `boolean` | `false` | Trạng thái đang tải của nhóm |
+| `label` | `ReactNode` | `undefined` | Tiêu đề của nhóm |
+| `helperText` | `ReactNode` | `undefined` | Chú thích của nhóm |
+| `errorMessage` | `ReactNode` | `undefined` | Thông báo lỗi của nhóm |
+
+---
+
+### `CheckboxOptionItem<TData = unknown>`
+
+| Trường | Kiểu dữ liệu | Mô tả |
+| :--- | :--- | :--- |
+| `value` | `string` | Giá trị định danh duy nhất của ô chọn |
+| `label` | `ReactNode` | Nhãn hiển thị chính |
+| `description` | `ReactNode` | Đoạn chú thích/mô tả phụ bên dưới nhãn |
+| `disabled` | `boolean` | Vô hiệu hóa ô chọn này |
+| `isReadOnly` | `boolean` | Chế độ chỉ đọc cho ô chọn này |
+| `indeterminate`| `boolean` | Trạng thái gạch ngang cho ô chọn này |
+| `data` | `TData` | Đối tượng dữ liệu gốc đính kèm |
+| `[key: string]` | `unknown` | Mở rộng các trường tùy ý (phục vụ lọc theo `searchField`) |