@openway/ui 1.0.0 → 1.0.2

package/docs/components/upload-file.md

@@ -0,0 +1,245 @@
+# 📄 Upload File Component Suite (`@openway/ui`)
+
+Bộ component **UploadFile** toàn diện, linh hoạt và hiệu năng cao dành cho việc tải lên, kéo thả (Drag & Drop), quản lý danh sách, xem trước (Preview) và kiểm tra các loại tệp tin tài liệu (PDF, Word, Excel, PowerPoint, ZIP, Media, Code, v.v.).
+
+Component được xây dựng đồng bộ 100% với hệ thống **Design System** của `@openway/ui`, tương đương cấu trúc với `UploadImage`, sử dụng chung kiểu dữ liệu `PreviewFile` và tích hợp sâu với `<FileContainer>` để xem trước tệp tin tức thì.
+
+---
+
+## 🌟 Điểm nổi bật
+
+- **Kiểu dữ liệu đồng nhất toàn hệ sinh thái**:
+  - Tái sử dụng trực tiếp kiểu dữ liệu `PreviewFile` (`File | ServerFile | string`) từ `file-preview` tương thích hoàn toàn với `UploadImage` và `FileContainer`.
+- **Hệ thống nhận diện `FileIcon` thông minh**:
+  - Tự động phân tích phần mở rộng và MIME type để hiển thị icon tài liệu và huy hiệu màu sắc đặc trưng:
+    - 🔴 **PDF**: Huy hiệu đỏ (`PDF`)
+    - 🔵 **Word / Docs** (`doc`, `docx`): Huy hiệu xanh dương (`DOC`)
+    - 🟢 **Excel / Sheets** (`xls`, `xlsx`, `csv`): Huy hiệu xanh lá (`XLS`)
+    - 🟠 **PowerPoint** (`ppt`, `pptx`): Huy hiệu cam (`PPT`)
+    - 🟡 **Archive / ZIP** (`zip`, `rar`, `7z`, `tar`): Huy hiệu vàng/hổ phách (`ZIP`)
+    - 🟣 **Audio**: Huy hiệu tím (`AUD`)
+    - 🔷 **Video**: Huy hiệu xanh ngọc (`VID`)
+    - ⬛ **Code**: Huy hiệu chàm (`DEV`)
+    - ⚪ **Khác**: Huy hiệu trung tính (`FILE`)
+- **3 Chế độ hiển thị (`viewMode`)**:
+  - `dropzone` *(mặc định)*: Khung viền nét đứt lớn hỗ trợ kéo thả và nhấn chọn tệp. Danh sách các tệp tin đã tải lên luôn hiển thị trực quan ngay bên dưới.
+  - `button`: Nút bấm kích hoạt tải tệp gọn gàng kèm icon, thích hợp cho toolbar hoặc khu vực hẹp.
+  - `compact`: Khung kéo thả thu gọn dạng thanh ngang 1 dòng tiết kiệm diện tích.
+- **2 Kiểu hiển thị danh sách (`listType`)**:
+  - `list` *(mặc định)*: Dạng hàng ngang chi tiết với icon, tên file, dung lượng format (`formatBytes`), thanh tiến trình và các nút hành động.
+  - `grid`: Bố cục dạng thẻ (card) trên lưới responsive.
+- **Theo dõi tiến trình & Trạng thái lỗi**:
+  - Hỗ trợ hiển thị thanh tiến trình mini động khi `status: "uploading"` kèm tỷ lệ `%` hoàn thành.
+  - Hiển thị thông báo lỗi chi tiết khi `status: "error"` và nút **Thử lại** (`onRetry`).
+- **Tích hợp sẵn xem trước & Tải xuống**:
+  - Click vào tên tệp hoặc nút Xem trước (`EyeIcon`) tự động kích hoạt modal `<FileContainer>` đa năng.
+  - Hỗ trợ tải trực tiếp tệp về máy tính qua `downloadFile` hoặc callback `onDownload`.
+- **Chuẩn Design System**:
+  - 5 kích thước: `xs`, `sm`, `md`, `lg`, `xl`.
+  - 7 bảng màu: `primary`, `secondary`, `neutral`, `error`, `success`, `warning`, `info`.
+  - 4 biến thể: `outline`, `filled`, `ghost`, `other`.
+  - Bo góc: `none`, `sm`, `md`, `lg`, `xl`, `full`.
+  - Safe Config Fallback với `getSafeConfig`.
+  - Nhãn form hỗ trợ `isRequired` (dấu sao đỏ) và đổi màu khi focus (`group-focus-within/field`).
+- **Hỗ trợ tiếp cận (A11y)**:
+  - Tương thích bàn phím: <kbd>Tab</kbd>, <kbd>Enter</kbd> / <kbd>Space</kbd> để chọn file, <kbd>Delete</kbd> / <kbd>Backspace</kbd> để xóa tệp.
+  - Vùng thông báo động Screen Reader qua `aria-live="polite"`.
+
+---
+
+## 🚀 Cài đặt & Import
+
+```tsx
+import {
+  UploadFile,
+  UploadFileDropzone,
+  UploadFileList,
+  UploadFileItemRow,
+  FileIcon,
+  formatBytes,
+  getFileCategory,
+} from "@openway/ui";
+
+import type {
+  UploadFileProps,
+  UploadFileConfig,
+  UploadFileViewMode,
+  UploadFileListType,
+  UploadFileSize,
+  UploadFileColor,
+  UploadFileVariant,
+  UploadFileRadius,
+  PreviewFile,
+  ServerFile,
+} from "@openway/ui";
+```
+
+---
+
+## 📖 Hướng dẫn sử dụng
+
+### 1. Chế độ Dropzone mặc định (1 tệp hoặc nhiều tệp)
+
+```tsx
+import { useState } from "react";
+import { UploadFile, PreviewFile } from "@openway/ui";
+
+export function BasicExample() {
+  const [files, setFiles] = useState<PreviewFile[]>([]);
+
+  return (
+    <UploadFile
+      value={files}
+      onChange={setFiles}
+      label="Tài liệu đính kèm"
+      config={{ isRequired: true }}
+      helperText="Hỗ trợ PDF, DOCX, XLSX tối đa 10MB"
+      maxSize={10 * 1024 * 1024}
+    />
+  );
+}
+```
+
+---
+
+### 2. Bố cục danh sách dạng Grid (`listType="grid"`)
+
+```tsx
+<UploadFile
+  listType="grid"
+  config={{ multiple: true }}
+  label="Hồ sơ nghiệm thu dự án"
+  defaultValue={[
+    { id: "1", name: "bien-ban-nghiem-thu.pdf", size: 1450000 },
+    { id: "2", name: "phu-luc-khoi-luong.xlsx", size: 850000 },
+  ]}
+/>
+```
+
+---
+
+### 3. Chế độ Button Trigger
+
+```tsx
+<UploadFile
+  viewMode="button"
+  buttonText="Chọn tài liệu"
+  config={{ multiple: true }}
+  label="Hồ sơ đính kèm"
+  onChange={(items) => console.log("Danh sách tệp:", items)}
+/>
+```
+
+---
+
+### 4. Chế độ Compact Dropzone (Thanh ngang 1 dòng)
+
+```tsx
+<UploadFile
+  viewMode="compact"
+  label="Bản sao chứng minh thư"
+  dropzoneTitle="Kéo thả CMND/CCCD hoặc nhấn để duyệt"
+/>
+```
+
+---
+
+### 5. Quản lý trạng thái Uploading & Lỗi
+
+```tsx
+const fileList: ServerFile[] = [
+  {
+    id: "1",
+    name: "bao-cao-tai-chinh.xlsx",
+    size: 2500000,
+    status: "uploading",
+    progress: 75,
+  },
+  {
+    id: "2",
+    name: "ho-so-loi.zip",
+    size: 15000000,
+    status: "error",
+    error: "Dung lượng vượt quá cấu hình máy chủ",
+  },
+];
+
+<UploadFile
+  value={fileList}
+  onRetry={(item, index) => {
+    console.log("Thử lại tải tệp:", item);
+  }}
+/>
+```
+
+---
+
+### 6. Sử dụng độc lập `FileIcon`
+
+```tsx
+import { FileIcon } from "@openway/ui";
+
+<div className="flex items-center gap-3">
+  <FileIcon fileName="bao-cao.pdf" size="md" />
+  <FileIcon fileName="bang-luong.xlsx" size="md" />
+  <FileIcon fileName="du-an.zip" size="md" />
+  <FileIcon fileName="source-code.ts" size="md" />
+</div>
+```
+
+---
+
+## ⚙️ Bảng Props `UploadFileProps`
+
+| Prop | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `config` | `UploadFileConfig` | `undefined` | Cấu hình tập trung các cờ boolean (`multiple`, `isRequired`, `isInvalid`, `isLoading`, `showFileList`...) |
+| `value` | `PreviewFile[] \| PreviewFile \| null` | `undefined` | Danh sách tệp tin (Controlled mode) |
+| `defaultValue` | `PreviewFile[] \| PreviewFile \| null` | `undefined` | Giá trị ban đầu (Uncontrolled mode) |
+| `onChange` | `(items: PreviewFile[]) => void` | `undefined` | Callback khi danh sách tệp thay đổi |
+| `onRemove` | `(item: PreviewFile, index: number) => void` | `undefined` | Callback khi xóa 1 tệp tin |
+| `onPreview` | `(item: PreviewFile) => void` | `undefined` | Callback khi bấm xem trước |
+| `onDownload` | `(item: PreviewFile) => void` | `undefined` | Callback khi bấm tải xuống |
+| `onRetry` | `(item: PreviewFile, index: number) => void` | `undefined` | Callback khi bấm nút thử lại |
+| `viewMode` | `'dropzone' \| 'button' \| 'compact'` | `'dropzone'` | Chế độ hiển thị giao diện tải |
+| `listType` | `'list' \| 'grid'` | `'list'` | Kiểu bố cục danh sách tệp |
+| `shape` | `'rectangle' \| 'square'` | `'rectangle'` | Hình dạng khung Dropzone |
+| `maxCount` | `number` | `1` (khi !multiple) | Số lượng tệp tối đa |
+| `maxSize` | `number` | `undefined` | Dung lượng tệp tối đa (bytes) |
+| `minSize` | `number` | `undefined` | Dung lượng tệp tối thiểu (bytes) |
+| `accept` | `string \| Accept` | `undefined` | Định dạng cho phép (ví dụ: `".pdf,.docx"`) |
+| `beforeUpload` | `(file: File) => boolean \| string \| Promise<...>` | `undefined` | Hook kiểm tra tệp trước khi nạp |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Kích thước component |
+| `color` | `'primary' \| 'secondary' \| 'neutral' \| ...` | `'primary'` | Bảng màu chủ đề |
+| `variant` | `'outline' \| 'filled' \| 'ghost' \| 'other'` | `'outline'` | Biến thể đường viền/nền |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'` | Độ bo góc |
+| `label` | `ReactNode` | `undefined` | Tiêu đề nhãn của trường form |
+| `labelClassName` | `string` | `""` | Lớp CSS tùy biến cho nhãn |
+| `helperText` | `ReactNode` | `undefined` | Văn bản gợi ý |
+| `errorMessage`| `ReactNode` | `undefined` | Thông báo lỗi |
+| `disabled` | `boolean` | `false` | Vô hiệu hóa tương tác |
+| `readOnly` | `boolean` | `false` | Chế độ chỉ đọc |
+| `renderItem` | `(item, index, actions) => ReactNode` | `undefined` | Tùy biến render từng mục tệp |
+
+### Cấu trúc `UploadFileConfig`
+
+| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `multiple` | `boolean` | `false` | Cho phép tải lên nhiều tệp tin cùng lúc |
+| `isRequired` | `boolean` | `false` | Đánh dấu trường bắt buộc nhập (dấu * đỏ) |
+| `isInvalid` | `boolean` | `false` | Đánh dấu trạng thái lỗi |
+| `isLoading` | `boolean` | `false` | Trạng thái đang tải / xử lý |
+| `showSpinner` | `boolean` | `false` | Hiển thị biểu tượng xoay spinner khi đang loading |
+| `showFileList`| `boolean` | `true` | Hiển thị danh sách tệp bên dưới |
+| `showPreviewButton` | `boolean` | `true` | Hiển thị nút xem trước trên từng mục tệp |
+| `showDownloadButton`| `boolean` | `true` | Hiển thị nút tải xuống trên từng mục tệp |
+| `showRemoveButton` | `boolean` | `true` | Hiển thị nút xóa trên từng mục tệp |
+
+---
+
+## ⌨️ Phím tắt & Trợ năng (Accessibility)
+
+- <kbd>Tab</kbd>: Di chuyển tiêu điểm bàn phím vào vùng Dropzone, nút Tải hoặc từng mục tệp tin.
+- <kbd>Enter</kbd> hoặc <kbd>Space</kbd>: Mở hộp thoại chọn tệp của hệ thống hoặc kích hoạt xem trước.
+- <kbd>Delete</kbd> hoặc <kbd>Backspace</kbd>: Xóa tệp đang được focus khỏi danh sách (trừ chế độ `readOnly` hoặc `disabled`).
+- Tự động phát âm thanh/thông báo trợ năng qua vùng `<div aria-live="polite" className="sr-only">`.

package/docs/components/upload-image.md

@@ -0,0 +1,126 @@
+# 🖼️ UploadImage Component (`@openway/ui`)
+
+Component tải lên hình ảnh chuyên nghiệp, hỗ trợ kéo thả (`drag-and-drop`), xem trước ảnh tức thời (`preview`), crop/cắt ảnh trực quan, hiển thị dạng danh sách hoặc lưới thẻ (`picture wall`), và tuân thủ các quy chuẩn **Design System** & **Accessibility**.
+
+---
+
+## 🌟 Điểm nổi bật
+
+- **3 Chế độ hiển thị (`viewMode`)**:
+  - `dropzone` *(mặc định)*: Khung kéo thả lớn với icon, tiêu đề và mô tả trực quan.
+  - `card-grid`: Lưới thẻ ảnh dạng thumbnail vuông (picture wall), nút thêm ảnh hiển thị như 1 ô trong lưới.
+  - `button`: Nút bấm kích hoạt mở hộp thoại chọn ảnh gọn gàng.
+- **Tích hợp cắt ảnh linh hoạt (`enableCrop`)**:
+  - Hỗ trợ modal crop ảnh trực quan (`react-easy-crop`) với tỷ lệ tùy biến (`cropAspectRatio`).
+  - Hỗ trợ xoay, zoom và kiểm soát chất lượng ảnh sau crop.
+- **Xem trước ảnh tiện lợi (`enablePreview`)**:
+  - Tích hợp modal phóng to ảnh đầy đủ màn hình, xem chi tiết kích thước và tên tệp.
+- **Kiểm soát dung lượng & Định dạng tệp**:
+  - Giới hạn dung lượng tối đa (`maxSize`), tối thiểu (`minSize`).
+  - Giới hạn số lượng tệp tải lên (`maxFiles`).
+  - Tùy chỉnh danh sách định dạng ảnh cho phép (`accept`, ví dụ: `image/jpeg`, `image/png`, `image/webp`).
+- **Phản hồi lỗi & Trạng thái tải trực quan**:
+  - Báo lỗi tự động khi vượt quá dung lượng hoặc sai loại tệp.
+  - Thanh tiến trình tải lên (`progress`) và hiệu ứng hover sinh động.
+
+---
+
+## 🚀 Cài đặt & Import
+
+```tsx
+import { UploadImage } from "@openway/ui";
+import type { UploadImageProps, UploadImageFileItem } from "@openway/ui";
+```
+
+---
+
+## 📖 Hướng dẫn sử dụng
+
+### 1. UploadImage cơ bản dạng Dropzone
+
+```tsx
+import { useState } from "react";
+import { UploadImage, UploadImageFileItem } from "@openway/ui";
+
+export function BasicUploadImageExample() {
+  const [files, setFiles] = useState<UploadImageFileItem[]>([]);
+
+  return (
+    <div className="max-w-md">
+      <UploadImage
+        label="Ảnh đại diện bài viết"
+        value={files}
+        onChange={(newFiles) => setFiles(newFiles)}
+        maxFiles={1}
+        maxSize={5 * 1024 * 1024} // 5MB
+        helperText="Định dạng PNG, JPG, WEBP tối đa 5MB"
+      />
+    </div>
+  );
+}
+```
+
+---
+
+### 2. Dạng Lưới thẻ (Picture Wall - `card-grid`)
+
+Thích hợp cho tải album ảnh sản phẩm hoặc thư viện ảnh:
+
+```tsx
+import { useState } from "react";
+import { UploadImage, UploadImageFileItem } from "@openway/ui";
+
+export function PictureWallExample() {
+  const [gallery, setGallery] = useState<UploadImageFileItem[]>([]);
+
+  return (
+    <div className="max-w-xl">
+      <UploadImage
+        viewMode="card-grid"
+        shape="square"
+        maxFiles={8}
+        value={gallery}
+        onChange={(newFiles) => setGallery(newFiles)}
+        label="Bộ sưu tập ảnh sản phẩm"
+        enablePreview
+      />
+    </div>
+  );
+}
+```
+
+---
+
+### 3. Kích hoạt tính năng Crop ảnh (`enableCrop`)
+
+```tsx
+<UploadImage
+  label="Tải ảnh bìa (Tỷ lệ 16:9)"
+  maxFiles={1}
+  enableCrop
+  cropAspectRatio={16 / 9}
+  value={files}
+  onChange={setFiles}
+/>
+```
+
+---
+
+## 🎛️ Bảng Props Chi tiết
+
+| Tên Prop | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `value` | `UploadImageFileItem[]` | `[]` | Danh sách tệp ảnh hiện tại. |
+| `onChange` | `(files: UploadImageFileItem[]) => void` | `undefined` | Callback khi danh sách ảnh thay đổi (thêm, xóa, crop). |
+| `viewMode` | `"dropzone" \| "card-grid" \| "button"` | `"dropzone"` | Kiểu giao diện tải ảnh. |
+| `shape` | `"rectangle" \| "square"` | `"rectangle"` | Hình dạng khung hiển thị ảnh. |
+| `maxFiles` | `number` | `1` | Số lượng tệp ảnh tối đa được phép tải. |
+| `maxSize` | `number` | `10 * 1024 * 1024` | Kích thước tối đa mỗi tệp (bytes). |
+| `accept` | `Record<string, string[]>` | Ảnh thông dụng | Đối tượng định dạng MIME types cho phép. |
+| `enableCrop` | `boolean` | `false` | Mở hộp thoại crop ảnh trước khi thêm vào danh sách. |
+| `cropAspectRatio` | `number` | `1` | Tỷ lệ khung hình khi crop (ví dụ: `1` cho ảnh vuông, `16/9` cho banner). |
+| `enablePreview` | `boolean` | `true` | Cho phép nhấn vào ảnh để mở modal xem ảnh kích thước lớn. |
+| `disabled` | `boolean` | `false` | Khóa chức năng tải ảnh. |
+| `color` | `ThemeColor` | `"primary"` | Chủ đề màu sắc theo Design System. |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Kích thước khung tải ảnh. |
+| `radius` | `Radius` | `"md"` | Độ bo góc của khung tải và thumbnail. |

package/docs/hooks/useDebounce.md

@@ -0,0 +1,92 @@
+# ⏱️ Hooks `useDebounce` & `useDebouncedCallback` (`@openway/ui`)
+
+Bộ đôi hook tối ưu hiệu năng giúp hoãn thực thi và chống spam request khi người dùng nhập dữ liệu hoặc thao tác liên tục.
+
+---
+
+## 🌟 Phân biệt 2 Hook
+
+- **`useDebounce<T>(value, delay)`**: Dùng để debounce một **giá trị (value)** (ví dụ: chuỗi tìm kiếm text input, giá trị thanh trượt slider). Khi người dùng ngừng thay đổi sau khoảng thời gian `delay`, giá trị mới được cập nhật.
+- **`useDebouncedCallback(callback, delay)`**: Dùng để debounce một **hàm callback** (ví dụ: hàm gọi API, resize window, autosave form). Trả về hàm `{ debounced, cancel }`. Luôn giữ tham chiếu callback mới nhất mà không gây re-render dư thừa.
+
+---
+
+## 🚀 Import
+
+```tsx
+import { useDebounce, useDebouncedCallback } from "@openway/ui";
+```
+
+---
+
+## 📖 Hướng dẫn sử dụng
+
+### 1. Sử dụng `useDebounce` với giá trị
+
+```tsx
+import { useState, useEffect } from "react";
+import { Input, useDebounce } from "@openway/ui";
+
+export function SearchFilter() {
+  const [keyword, setKeyword] = useState("");
+  // debouncedKeyword chỉ thay đổi sau khi ngừng gõ 400ms
+  const debouncedKeyword = useDebounce(keyword, 400);
+
+  useEffect(() => {
+    if (debouncedKeyword) {
+      console.log("Tìm kiếm với từ khóa:", debouncedKeyword);
+    }
+  }, [debouncedKeyword]);
+
+  return (
+    <Input
+      label="Tìm kiếm"
+      value={keyword}
+      onChange={(e) => setKeyword(e.target.value)}
+      placeholder="Gõ từ khóa..."
+    />
+  );
+}
+```
+
+---
+
+### 2. Sử dụng `useDebouncedCallback` với hàm xử lý
+
+```tsx
+import { useDebouncedCallback, Button } from "@openway/ui";
+
+export function AutoSaveForm() {
+  const { debounced: handleAutoSave, cancel } = useDebouncedCallback((formData: Record<string, unknown>) => {
+    console.log("Tự động lưu dữ liệu lên server:", formData);
+  }, 500);
+
+  return (
+    <div className="space-y-2">
+      <Button onClick={() => handleAutoSave({ title: "Bản nháp mới" })}>
+        Cập nhật dữ liệu
+      </Button>
+      <Button variant="ghost" color="error" onClick={cancel}>
+        Hủy lưu tự động
+      </Button>
+    </div>
+  );
+}
+```
+
+---
+
+## 🎛️ Bảng Tham số
+
+### `useDebounce<T>(value: T, delay?: number): T`
+| Tham số | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `value` | `T` | **Bắt buộc** | Giá trị cần debounce. |
+| `delay` | `number` | `300` | Thời gian hoãn tính theo mili-giây (ms). |
+
+### `useDebouncedCallback(callback, delay?: number)`
+| Tham số | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `callback` | `(...args: Args) => R` | **Bắt buộc** | Hàm cần debounce. |
+| `delay` | `number` | `300` | Thời gian hoãn tính theo mili-giây (ms). |
+- Trả về object: `{ debounced: (...args) => void, cancel: () => void }`.

package/docs/hooks/useInfiniteScroll.md

@@ -0,0 +1,95 @@
+# ♾️ Hook `useInfiniteScroll` (`@openway/ui`)
+
+Hook React độc lập, hiệu năng cao phục vụ cơ chế tải dữ liệu vô tận (Infinite Scroll) dựa trên 100% **IntersectionObserver** nguyên bản của trình duyệt.
+
+---
+
+## 🌟 Điểm nổi bật
+
+- **Zero Main-Thread Overhead**: Hoàn toàn không gắn event listener `scroll` thủ công trên container, loại bỏ hiện tượng giật lag khung hình khi cuộn nhanh.
+- **Pure React 19 Compliant**: Không sử dụng ref dư thừa để lưu primitives (`hasMore`, `isLoading`, `disabled`), hoàn toàn tuân thủ quy chuẩn render của React 19.
+- **Chống Request Trùng lặp (Mutex Lock)**: Sử dụng duy nhất một cờ khóa an toàn `isTriggeringRef` để ngăn chặn các lượt gọi API async liên tiếp trong cùng một chu kỳ render.
+- **Tự động kích hoạt khi hoàn tất tải**: Nếu dữ liệu trang trước đã tải xong (`isLoading: false`) mà phần tử sentinel vẫn đang nằm trong tầm quan sát, hook sẽ tự động kích hoạt tải tiếp trang kế tiếp một cách mượt mà.
+
+---
+
+## 🚀 Import
+
+```tsx
+import { useInfiniteScroll } from "@openway/ui";
+import type { UseInfiniteScrollOptions, UseInfiniteScrollReturn } from "@openway/ui";
+```
+
+---
+
+## 📖 Hướng dẫn sử dụng
+
+### Sử dụng với Danh sách thẻ (Card List / Feed)
+
+```tsx
+import { useState } from "react";
+import { useInfiniteScroll, Skeleton } from "@openway/ui";
+
+export function PostFeed() {
+  const [posts, setPosts] = useState<string[]>(["Bài viết 1", "Bài viết 2"]);
+  const [hasMore, setHasMore] = useState(true);
+  const [isLoading, setIsLoading] = useState(false);
+
+  const loadMorePosts = async () => {
+    setIsLoading(true);
+    // Giả lập gọi API
+    await new Promise((resolve) => setTimeout(resolve, 800));
+    setPosts((prev) => [
+      ...prev,
+      `Bài viết ${prev.length + 1}`,
+      `Bài viết ${prev.length + 2}`,
+    ]);
+    if (posts.length > 20) setHasMore(false);
+    setIsLoading(false);
+  };
+
+  const { sentinelRef } = useInfiniteScroll({
+    onLoadMore: loadMorePosts,
+    hasMore,
+    isLoading,
+    rootMargin: "150px", // Bắt đầu tải trước khi chạm đáy 150px
+  });
+
+  return (
+    <div className="max-w-md mx-auto space-y-3">
+      {posts.map((post, idx) => (
+        <div key={idx} className="p-4 border rounded-lg shadow-sm bg-white dark:bg-neutral-900">
+          {post}
+        </div>
+      ))}
+
+      {/* Phần tử Sentinel để IntersectionObserver theo dõi */}
+      <div ref={sentinelRef} className="py-2">
+        {isLoading && (
+          <Skeleton lines={2} height="2.5rem" className="w-full" />
+        )}
+      </div>
+
+      {!hasMore && (
+        <p className="text-center text-xs text-neutral-400 py-2">
+          Đã tải hết toàn bộ bài viết
+        </p>
+      )}
+    </div>
+  );
+}
+```
+
+---
+
+## 🎛️ Bảng Options
+
+| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `onLoadMore` | `() => void \| Promise<void>` | **Bắt buộc** | Callback kích hoạt khi sentinel xuất hiện trong tầm nhìn. |
+| `hasMore` | `boolean` | `true` | Còn dữ liệu trang sau hay không. Nếu `false`, hook không kích hoạt nữa. |
+| `isLoading` | `boolean` | `false` | Trạng thái đang tải dữ liệu. Ngăn chặn kích hoạt lượt tải mới khi lượt cũ chưa hoàn tất. |
+| `disabled` | `boolean` | `false` | Vô hiệu hóa toàn bộ cơ chế theo dõi. |
+| `rootMargin` | `string` | `"100px"` | Khoảng cách biên quan sát trước khi người dùng chạm tới đáy. |
+| `threshold` | `number \| number[]` | `0` | Ngưỡng hiển thị của phần tử sentinel (từ `0` đến `1`). |
+| `root` | `Element \| null \| RefObject` | `null` | Khung cuộn gốc. Mặc định là viewport trình duyệt. |