@openway/ui 1.0.1 → 1.0.3

package/dist/{useInfiniteScroll-DAlgjUN4.d.ts → useInfiniteScroll-C5t7bvLu.d.ts}

@@ -1,6 +1,279 @@
 import { HTMLAttributes, Ref, ReactNode, RefObject } from 'react';
+import { ToasterProps as ToasterProps$1, ToastT } from 'sonner';
 import { Placement } from '@floating-ui/react';
 
+/**
+ * Các kích cỡ tiêu chuẩn của Alert:
+ * - 'xs': Siêu nhỏ (text-xs, padding p-2)
+ * - 'sm': Nhỏ (text-xs, title text-sm, padding p-2.5)
+ * - 'md': Vừa - mặc định (text-sm, padding p-3.5)
+ * - 'lg': Lớn (text-base, padding p-4)
+ * - 'xl': Rất lớn (text-lg, padding p-5)
+ */
+type AlertSize = "xs" | "sm" | "md" | "lg" | "xl";
+/**
+ * Các biến thể giao diện và phong cách hiển thị màu sắc của Alert:
+ * - 'soft': Nền nhạt pastel, viền mờ 2px, chữ đậm (mặc định)
+ * - '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 dày 4px bên trái
+ * - 'ghost': Nền và viền trong suốt
+ * - 'other': Bỏ qua màu mặc định, tự do styling qua className
+ */
+type AlertVariant = "soft" | "filled" | "outline" | "accent-left" | "ghost" | "other";
+/**
+ * 7 chủ đề màu sắc theo Design System:
+ * - 'primary': Màu chủ đạo
+ * - 'secondary': Màu phụ
+ * - 'neutral': Màu trung tính
+ * - 'error': Màu đỏ cảnh báo lỗi nguy cấp
+ * - 'success': Màu xanh lá thông báo thành công
+ * - 'warning': Màu vàng/cam cảnh báo
+ * - 'info': Màu xanh dương thông tin (mặc định)
+ */
+type AlertColor = "primary" | "secondary" | "neutral" | "error" | "success" | "warning" | "info";
+/**
+ * Độ bo góc của khung thông báo Alert:
+ * - 'none': Góc vuông phẳng (rounded-none)
+ * - 'sm': Bo góc nhỏ (rounded-sm)
+ * - 'md': Bo góc vừa (rounded-md)
+ * - 'lg': Bo góc lớn (rounded-lg - mặc định)
+ * - 'xl': Bo góc rất lớn (rounded-xl)
+ * - 'full': Bo tròn hoàn toàn (rounded-2xl)
+ */
+type AlertRadius = "none" | "sm" | "md" | "lg" | "xl" | "full";
+/**
+ * Props cho component `Alert`.
+ */
+interface AlertProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+    /**
+     * Ref chuyển tiếp đến phần tử HTML div của Alert
+     */
+    ref?: Ref<HTMLDivElement>;
+    /**
+     * Kích cỡ của Alert (5 sizes: xs, sm, md, lg, xl)
+     * @default 'md'
+     */
+    size?: AlertSize;
+    /**
+     * Biến thể giao diện của Alert:
+     * - 'soft': nền nhạt pastel, viền mờ, chữ đậm tương ứng (mặc định)
+     * - 'filled': nền màu đậm, chữ tương phản cao
+     * - 'outline': nền trắng, viền rõ nét theo màu chủ đề
+     * - 'accent-left': viền nhấn dày bên trái, nền pastel
+     * - 'ghost': nền và viền trong suốt
+     * - 'other': không áp dụng style màu mặc định, tự do tùy biến qua className
+     * @default 'soft'
+     */
+    variant?: AlertVariant;
+    /**
+     * Chủ đề màu sắc (primary, secondary, neutral, error, success, warning, info)
+     * @default 'info'
+     */
+    color?: AlertColor;
+    /**
+     * Tùy chỉnh độ bo góc:
+     * - 'none': góc vuông 0px
+     * - 'sm': bo góc nhỏ
+     * - 'md': bo góc vừa
+     * - 'lg': bo góc lớn (mặc định)
+     * - 'xl': bo góc rất lớn
+     * - 'full': bo tròn hoàn toàn
+     * @default 'lg'
+     */
+    radius?: AlertRadius;
+    /**
+     * Tiêu đề của Alert
+     */
+    title?: ReactNode;
+    /**
+     * Nội dung mô tả chi tiết của Alert (có thể truyền qua prop description hoặc children)
+     */
+    description?: ReactNode;
+    /**
+     * Icon hiển thị ở đầu thông báo:
+     * - `true` (hoặc không truyền): tự động hiển thị icon theo `color`
+     * - `false`: ẩn icon
+     * - `ReactNode`: icon tùy chỉnh
+     * @default true
+     */
+    icon?: ReactNode | boolean;
+    /**
+     * Phần tử hành động phụ (Action slot, ví dụ: Nút bấm, liên kết thao tác)
+     */
+    action?: ReactNode;
+    /**
+     * Hiển thị nút đóng (Close button x) để người dùng có thể tắt thông báo. Tự động ẩn Alert khi click.
+     * @default true
+     */
+    closable?: boolean;
+    /**
+     * Callback khi người dùng bấm nút đóng
+     */
+    onClose?: () => void;
+    /**
+     * Nhãn accessibility cho nút đóng
+     * @default 'Close alert'
+     */
+    closeAriaLabel?: string;
+    /**
+     * Chế độ Banner: Full width, không bo góc (`rounded-none`), không viền 2 bên (`border-x-0`), thích hợp gắn cố định trên cùng màn hình
+     * @default false
+     */
+    banner?: boolean;
+    /**
+     * Class tùy biến cho phần tiêu đề (title)
+     */
+    titleClassName?: string;
+    /**
+     * Class tùy biến cho phần nội dung mô tả (description / children)
+     */
+    descriptionClassName?: string;
+    /**
+     * Class tùy biến cho vùng action slot
+     */
+    actionClassName?: string;
+    /**
+     * Class tùy biến cho icon wrapper
+     */
+    iconClassName?: string;
+    /**
+     * Class tùy biến cho nút đóng
+     */
+    closeButtonClassName?: string;
+    /**
+     * Class tùy biến cho container bao ngoài
+     */
+    className?: string;
+    /**
+     * Nội dung tùy biến bên trong Alert
+     */
+    children?: ReactNode;
+}
+
+/**
+ * Vị trí hiển thị của danh sách thông báo Toast trên màn hình.
+ */
+type ToastPosition = "top-left" | "top-right" | "top-center" | "bottom-left" | "bottom-right" | "bottom-center";
+/**
+ * Cấu hình tùy chọn cho từng thông báo Toast đơn lẻ:
+ * - Dạng gọi hàm chuẩn: `toast.success(title, description?, options?)`
+ */
+interface ToastOptions extends Omit<AlertProps, "title" | "description"> {
+    /**
+     * Thời gian hiển thị thông báo trước khi tự động đóng (miliseconds). Mặc định 4000ms.
+     * @default 4000
+     */
+    duration?: number;
+    /**
+     * Vị trí hiển thị riêng cho thông báo này trên màn hình.
+     */
+    position?: ToastPosition;
+    /**
+     * Callback được gọi khi thông báo bị đóng/gỡ bỏ khỏi màn hình.
+     */
+    onDismiss?: (toast: ToastT) => void;
+    /**
+     * Callback được gọi khi thông báo tự động đóng do hết thời gian duration.
+     */
+    onAutoClose?: (toast: ToastT) => void;
+}
+/**
+ * Cấu trúc thông báo dạng Object chi tiết cho `toast.promise`.
+ */
+interface ToastMessageObject {
+    title?: ReactNode;
+    description?: ReactNode;
+    color?: AlertColor;
+    variant?: AlertVariant;
+}
+/**
+ * Kiểu dữ liệu linh hoạt cho nội dung thông báo trả về trong `toast.promise`:
+ * - `ReactNode`: Chuỗi text hoặc phần tử JSX thông thường.
+ * - `ToastMessageObject`: Object chi tiết gồm `{ title, description, color, variant }`.
+ */
+type ToastMessageResult = ReactNode | ToastMessageObject;
+/**
+ * Hàm tạo nội dung thông báo thành công động dựa theo dữ liệu `data: T` trả về từ Promise.
+ */
+type ToastPromiseFunction<T> = (data: T) => ToastMessageResult;
+/**
+ * Cấu hình các trạng thái cho `toast.promise(promise, options)`.
+ */
+interface ToastPromiseOptions<T = unknown> {
+    /**
+     * Nội dung hiển thị trong lúc Promise đang thực thi (Loading state).
+     */
+    loading: ToastMessageResult;
+    /**
+     * Nội dung hiển thị khi Promise thực thi thành công (Resolve state).
+     * Có thể truyền trực tiếp nội dung hoặc một hàm nhận `data: T`.
+     */
+    success: ToastMessageResult | ToastPromiseFunction<T>;
+    /**
+     * Nội dung hiển thị khi Promise gặp lỗi (Reject state).
+     * Có thể truyền trực tiếp nội dung hoặc một hàm nhận `error: unknown`.
+     */
+    error: ToastMessageResult | ((error: unknown) => ToastMessageResult);
+    /**
+     * Callback chạy sau khi Promise hoàn tất (cả khi resolve hoặc reject).
+     */
+    finally?: () => void | Promise<void>;
+    /**
+     * Thời gian hiển thị thông báo kết quả (ms). Mặc định 4000ms.
+     * @default 4000
+     */
+    duration?: number;
+    /**
+     * Kích cỡ của Alert hiển thị trong Toast.
+     */
+    size?: AlertSize;
+    /**
+     * Biến thể giao diện của Alert hiển thị trong Toast.
+     */
+    variant?: AlertVariant;
+    /**
+     * Tùy chỉnh độ bo góc của Alert hiển thị trong Toast.
+     */
+    radius?: AlertRadius;
+}
+/**
+ * Props cho component `<Toaster />` được mount tại root layout của ứng dụng.
+ */
+interface ToasterProps extends ToasterProps$1 {
+    /**
+     * Vị trí mặc định của toàn bộ danh sách toasts trên màn hình.
+     * @default 'top-right'
+     */
+    position?: ToastPosition;
+    /**
+     * Số lượng toast tối đa hiển thị cùng lúc trước khi tự động xếp chồng 3D (stack).
+     * @default 3
+     */
+    visibleToasts?: number;
+    /**
+     * Mở rộng toàn bộ danh sách toasts thay vì gộp lại thành 1 stack 3D.
+     * - `false` (mặc định): Tự động gộp thẻ 3D, chỉ bung ra khi hover chuột.
+     * - `true`: Luôn luôn mở rộng trải dài toàn bộ danh sách.
+     * @default false
+     */
+    expand?: boolean;
+    /**
+     * Thời gian hiển thị mặc định của các toasts (miliseconds).
+     * @default 4000
+     */
+    duration?: number;
+    /**
+     * Cho phép hiển thị nút đóng `(X)` trên các toasts.
+     * @default true
+     */
+    closeButton?: boolean;
+    /**
+     * Tùy biến className bao ngoài container của Toaster.
+     */
+    className?: string;
+}
+
 type EmptySize = "sm" | "md" | "lg";
 type EmptyPresetImage = "default" | "search" | "error" | "folder" | "simple";
 type EmptyLayout = "vertical" | "horizontal";
@@ -121,9 +394,43 @@ interface SelectFilterField<TValue = unknown> {
         onChange: (val: TValue) => void;
     }) => ReactNode;
 }
+interface SelectConfig {
+    /**
+     * Đánh dấu trường bắt buộc nhập (hiển thị dấu * đỏ cạnh label)
+     * @default false
+     */
+    isRequired?: boolean;
+    /**
+     * Trạng thái báo lỗi (viền đỏ)
+     * @default false
+     */
+    isInvalid?: boolean;
+    /**
+     * Trạng thái đang tải dữ liệu
+     * @default false
+     */
+    isLoading?: boolean;
+    /**
+     * Hiển thị biểu tượng xoay spinner khi đang ở trạng thái loading
+     * @default false
+     */
+    showSpinner?: boolean;
+    /**
+     * Hiển thị nút xóa nhanh nội dung khi select có giá trị
+     * @default false
+     */
+    isClearable?: boolean;
+    /**
+     * Mở rộng chiều rộng 100% của container chứa
+     * @default true
+     */
+    isFullWidth?: boolean;
+}
 interface BaseSelectProps<TData = unknown, TFilters extends Record<string, unknown> = Record<string, unknown>> {
     /** Ref chuyển tiếp tới root wrapper element */
     ref?: Ref<HTMLDivElement>;
+    /** Cấu hình tập trung các cờ trạng thái / tính năng */
+    config?: SelectConfig;
     /** Kích thước: xs, sm, md, lg, xl. Mặc định 'md' */
     size?: SelectSize;
     /** Biến thể giao diện: outline, filled, ghost, other. Mặc định 'outline' */
@@ -138,7 +445,7 @@ interface BaseSelectProps<TData = unknown, TFilters extends Record<string, unkno
     id?: string;
     /** Nhãn tiêu đề của Select */
     label?: ReactNode;
-    /** Vị trí nhãn: top, left, floating. Mặc định 'top' */
+    /** Vị trí nhãn: top, left, floating. Mặc định 'floating' */
     labelPlacement?: LabelPlacement;
     /** ClassName tùy biến cho nhãn */
     labelClassName?: string;
@@ -148,10 +455,6 @@ interface BaseSelectProps<TData = unknown, TFilters extends Record<string, unkno
     helperText?: ReactNode;
     /** Thông báo lỗi khi không hợp lệ */
     errorMessage?: ReactNode;
-    /** Trạng thái không hợp lệ */
-    isInvalid?: boolean;
-    /** Bắt buộc chọn */
-    isRequired?: boolean;
     /** Vô hiệu hóa Select */
     isDisabled?: boolean;
     /** Chỉ đọc, không cho phép thay đổi */
@@ -198,16 +501,14 @@ interface BaseSelectProps<TData = unknown, TFilters extends Record<string, unkno
     debounceMs?: number;
     /** Hàm custom predicate lọc options ở chế độ client */
     filterFn?: (option: SelectOptionItem<TData>, query: string, filters: TFilters) => boolean;
-    /** Trạng thái đang tải dữ liệu */
-    isLoading?: boolean;
     /** Văn bản hiển thị khi không có dữ liệu */
     emptyText?: ReactNode;
     /** Props tùy biến chuyển tiếp đến component Empty */
     emptyProps?: Partial<EmptyProps>;
-    /** Hiển thị nút xoá nhanh toàn bộ giá trị đã chọn */
-    clearable?: boolean;
     /** Render menu qua Portal để tránh bị che bởi overflow hidden. Mặc định true */
     portal?: boolean;
+    /** Container để gắn portal menu vào (mặc định document.body, tự động nhận diện `<dialog>` nếu Select nằm trong Modal/Confirm) */
+    portalRoot?: HTMLElement | null | React.RefObject<HTMLElement | null>;
     /** Vị trí hiển thị của popup dropdown. Mặc định 'bottom-start' */
     placement?: Placement;
     /** Chiều cao tối đa của vùng cuộn menu. Mặc định 280px */
@@ -231,6 +532,8 @@ interface BaseSelectProps<TData = unknown, TFilters extends Record<string, unkno
     triggerClassName?: string;
     /** ClassName cho popup dropdown menu */
     menuClassName?: string;
+    /** ClassName cho phần thông báo helper/error text */
+    helperClassName?: string;
 }
 /** Props cho component Select (Single Select) */
 interface SelectProps<TData = unknown, TFilters extends Record<string, unknown> = Record<string, unknown>> extends BaseSelectProps<TData, TFilters> {
@@ -322,4 +625,4 @@ interface UseInfiniteScrollReturn {
  */
 declare function useInfiniteScroll({ onLoadMore, hasMore, isLoading, disabled, rootMargin, threshold, root, }: UseInfiniteScrollOptions): UseInfiniteScrollReturn;
 
-export { type BaseSelectProps as B, type EmptyProps as E, type MultiSelectProps as M, type SelectProps as S, type UseInfiniteScrollOptions as U, type EmptyPresetImage as a, type SelectOptionItem as b, type SelectSize as c, type SelectVariant as d, type SelectColor as e, type SelectRadius as f, type SelectSearchPlacement as g, type SelectFilterField as h, type SelectFilterLayout as i, type EmptyLayout as j, type EmptySize as k, type SelectFilterType as l, type SelectSearchMode as m, type SingleSelectProps as n, type UseInfiniteScrollReturn as o, useInfiniteScroll as u };
+export { type AlertProps as A, type BaseSelectProps as B, type EmptyProps as E, type MultiSelectProps as M, type SelectProps as S, type ToasterProps as T, type UseInfiniteScrollOptions as U, type ToastOptions as a, type ToastPromiseOptions as b, type EmptyPresetImage as c, type SelectOptionItem as d, type SelectSize as e, type SelectVariant as f, type SelectColor as g, type SelectRadius as h, type SelectSearchPlacement as i, type SelectFilterField as j, type SelectFilterLayout as k, type AlertColor as l, type AlertRadius as m, type AlertSize as n, type AlertVariant as o, type EmptyLayout as p, type EmptySize as q, type SelectFilterType as r, type SelectSearchMode as s, type SingleSelectProps as t, type ToastMessageObject as u, type ToastMessageResult as v, type ToastPosition as w, type ToastPromiseFunction as x, type UseInfiniteScrollReturn as y, useInfiniteScroll as z };

package/docs/AGENTS.md

@@ -131,8 +131,6 @@ Tất cả tài liệu chi tiết của từng component được lưu trữ t
    - `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:`.
 
 ---
 

package/docs/README.md

@@ -147,4 +147,3 @@ Tài liệu chi tiết của các hooks được lưu trữ tại thư mục [`h
 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/components/carousel.md

@@ -1,4 +1,4 @@
-# 🎠 Carousel Component (`@owa/ui`)
+# 🎠 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**.
 
@@ -12,7 +12,7 @@ Component **Carousel** (băng chuyền / slider) hiện đại, hiệu năng cao
 - **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.
+- **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`.
 - **Đị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`).
@@ -151,9 +151,9 @@ export function BasicCarousel() {
   <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">
+        <div className="p-4 border border-neutral-200 rounded-xl bg-white 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>
+          <h3 className="mt-2 font-semibold text-neutral-900">{product.name}</h3>
           <p className="text-primary-600 font-bold">{product.price}</p>
         </div>
       </CarouselSlide>
@@ -205,7 +205,7 @@ Hỗ trợ 4 biến thể giao diện: `glass` (*mặc định*), `filled`, `out
 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">
+<Carousel defaultIndex={1} className="w-full max-w-md border border-neutral-200 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>

package/docs/components/input.md

@@ -162,19 +162,13 @@ export function BasicInputExample() {
 | `label` | `ReactNode` | — | Nhãn tiêu đề hiển thị cho ô nhập liệu. |
 | `labelPlacement` | `'floating' \| 'top' \| 'left'` | `'floating'` | Vị trí hiển thị của nhãn. |
 | `config` | `InputConfig` | — | Cấu hình tập trung các cờ trạng thái / tính năng (`isRequired`, `isInvalid`, `isLoading`, `showSpinner`, `isClearable`, `isFullWidth`). |
-| `isRequired` | `boolean` | `false` | Hiển thị dấu sao đỏ `*` và đánh dấu `aria-required="true"`. |
 | `helperText` | `ReactNode` | — | Đoạn văn bản hướng dẫn/trợ giúp bên dưới ô. |
 | `errorMessage` | `ReactNode` | — | Thông báo lỗi khi nhập sai (tự kích hoạt trạng thái báo lỗi). |
-| `isInvalid` | `boolean` | `false` | Bật trạng thái viền đỏ báo lỗi và `aria-invalid="true"`. |
-| `isLoading` | `boolean` | `false` | Khóa tương tác, bật `aria-busy="true"` và `aria-disabled="true"`. |
-| `showSpinner` | `boolean` | `false` | Hiển thị biểu tượng xoay spinner khi `isLoading={true}`. |
 | `leftIcon` | `ReactNode` | — | Icon hiển thị ở đầu ô input. |
 | `rightIcon` | `ReactNode` | — | Icon hiển thị ở cuối ô input. |
 | `leftAddon` | `ReactNode` | — | Addon / prefix cố định ở đầu ô input (vd: `'https://'`). |
 | `rightAddon` | `ReactNode` | — | Addon / suffix cố định ở cuối ô input (vd: `'.com'`). |
-| `isClearable` | `boolean` | `false` | Hiển thị nút xóa nhanh nội dung khi có văn bản. |
 | `onClear` | `() => void` | — | Callback được gọi khi bấm nút xóa nhanh. |
-| `isFullWidth` | `boolean` | `false` | Mở rộng chiếm toàn bộ 100% chiều ngang container cha. |
 | `ref` | `Ref<HTMLInputElement>` | — | Ref chuyển tiếp đến thẻ `<input>` HTML bên dưới. |
 
 ---

package/docs/components/select.md

@@ -187,10 +187,10 @@ export function ServerInfiniteSelectExample() {
         className="w-7 h-7 rounded-full object-cover"
       />
       <div>
-        <div className="font-medium text-sm text-neutral-800 dark:text-neutral-100">
+        <div className="font-medium text-sm text-neutral-800">
           {option.label}
         </div>
-        <div className="text-xs text-neutral-400 dark:text-neutral-500">
+        <div className="text-xs text-neutral-400">
           {option.description}
         </div>
       </div>

package/docs/components/slider.md

@@ -159,8 +159,8 @@ Hỗ trợ 5 kích thước: `xs`, `sm`, `md` (*mặc định*), `lg`, `xl`:
   variant="other"
   label="Custom Other"
   defaultValue={60}
-  trackClassName="bg-purple-200 dark:bg-purple-900/40"
-  fillerClassName="bg-purple-600 dark:bg-purple-500"
+  trackClassName="bg-purple-200"
+  fillerClassName="bg-purple-600"
   thumbClassName="border-purple-600"
 />
 ```

package/docs/components/table.md

@@ -19,8 +19,13 @@ Bộ component **Table** và **DataTable** chuyên nghiệp, tích hợp sâu v
   - 📄 **Phân trang chuyên nghiệp (Pagination)**: Điều hướng trang đầu, trang trước, trang sau, trang cuối; chọn số dòng mỗi trang (10, 20, 50, 100).
   - ☑️ **Chọn dòng (Row Selection)**: Tự động render checkbox chọn từng dòng hoặc chọn toàn bộ dòng trên trang, kèm thanh hiển thị số lượng dòng đã chọn và khu vực Bulk Actions.
   - 👁️ **Ẩn/hiện cột (Column Visibility)**: Dropdown menu popover cho phép người dùng chủ động chọn cột cần xem.
+  - 🌲 **Mở rộng dòng & Dữ liệu cây (Row Expanding & Tree Data)**:
+    - Hỗ trợ mở rộng xem chi tiết phụ (Detail Panel / Sub-component) gộp toàn bộ cột (`renderExpandedRow`), dễ dàng tích hợp `useQuery` để fetch dữ liệu chi tiết.
+    - Hỗ trợ dữ liệu cây phân cấp đệ quy nhiều tầng (Cha ➔ Con ➔ Cháu...) hiển thị CÙNG HÀNG & CÙNG CỘT với bảng chính (`getSubRows`).
+    - Nút Chevron mở rộng tự động với animation xoay mượt mà, nút mở rộng/thu gọn tất cả trên header.
+    - Tự động thụt đầu dòng theo cấp độ sâu (`row.depth`), tích hợp cơ chế khống chế mức thụt tối đa (`maxIndentDepth`) để bảo vệ layout.
   - ⏳ **Trạng thái tải & Rỗng thông minh**: Tự động render Skeleton rows khi `isLoading={true}` và hiển thị `<Empty>` minh họa khi bảng không có dữ liệu hoặc không tìm thấy kết quả tìm kiếm.
-  - 🌐 **Hỗ trợ cả Client-side & Server-side (Manual Mode)**: Linh hoạt kết nối API phân trang, tìm kiếm từ máy chủ với `manualPagination`, `manualSorting`, `pageCount`, `rowCount`.
+  - 🌐 **Hỗ trợ cả Client-side & Server-side (Manual Mode)**: Linh hoạt kết nối API phân trang, tìm kiếm từ máy chủ với `manualPagination`, `manualSorting`, `manualExpanding`, `pageCount`, `rowCount`.
 - **3 Kích cỡ hiển thị (`size`)**: `sm` (gọn gàng, dense), `md` (chuẩn - *mặc định*), `lg` (thoáng đãng).
 - **3 Biến thể giao diện (`variant`)**: `default` (viền thanh lịch), `striped` (xen kẽ màu dòng), `bordered` (viền ô đầy đủ).
 
@@ -58,6 +63,7 @@ import type {
   ColumnOrderState,
   TablePaginationProps,
   TableToolbarProps,
+  ExpandedState,
 } from "@openway/ui";
 ```
 
@@ -254,6 +260,97 @@ export function ServerSideTableExample() {
 
 ---
 
+### 5. Mở rộng xem chi tiết phụ (Detail Panel với `renderExpandedRow` & `useQuery`)
+
+Khi người dùng bấm nút mở rộng dòng, bạn có thể render một component con tùy biến. Bên trong component con có thể sử dụng trực tiếp hook `useQuery` của TanStack Query để lấy dữ liệu chi tiết:
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+import { DataTable, Skeleton } from "@openway/ui";
+
+function OrderDetailPanel({ orderId }: { orderId: string }) {
+  // useQuery chỉ chạy khi dòng cha được bấm mở rộng (component mount)
+  const { data: orderDetail, isLoading } = useQuery({
+    queryKey: ["order-detail", orderId],
+    queryFn: () => fetch(`/api/orders/${orderId}`).then((res) => res.json()),
+  });
+
+  if (isLoading) {
+    return (
+      <div className="p-3">
+        <Skeleton className="h-10 w-full rounded" />
+      </div>
+    );
+  }
+
+  return (
+    <div className="p-4 bg-neutral-50 rounded">
+      <h4 className="font-semibold text-neutral-800">Chi tiết đơn hàng #{orderId}</h4>
+      <p className="text-sm text-neutral-600">Địa chỉ giao hàng: {orderDetail?.shippingAddress}</p>
+    </div>
+  );
+}
+
+export function ExpandableDetailTableExample() {
+  return (
+    <DataTable
+      columns={columns}
+      data={ordersData}
+      enableExpanding={true}
+      renderExpandedRow={(row) => <OrderDetailPanel orderId={row.original.id} />}
+    />
+  );
+}
+```
+
+---
+
+### 6. Dữ liệu cây phân cấp đệ quy đa tầng (Multi-level Tree Data với `getSubRows`)
+
+Khi các dòng con có **cùng kiểu dữ liệu và hiển thị CÙNG HÀNG & CÙNG CỘT** với bảng cha (hỗ trợ nhiều cấp cha ➔ con ➔ cháu...), chỉ cần cung cấp hàm `getSubRows`. Hệ thống tự động render dòng con với đầy đủ các cột và tự động thụt lề theo `row.depth`:
+
+```tsx
+import { DataTable, createTableColumnHelper } from "@openway/ui";
+
+interface Department {
+  id: string;
+  name: string;
+  leader: string;
+  budget: number;
+  subRows?: Department[]; // Danh sách phòng ban con
+}
+
+const deptColumnHelper = createTableColumnHelper<Department>();
+
+const deptColumns = deptColumnHelper.columns([
+  deptColumnHelper.accessor("name", {
+    header: "Tên đơn vị",
+  }),
+  deptColumnHelper.accessor("leader", {
+    header: "Trưởng đơn vị",
+  }),
+  deptColumnHelper.accessor("budget", {
+    header: "Ngân sách",
+    cell: (info) => `${info.getValue().toLocaleString("vi-VN")} đ`,
+  }),
+]);
+
+export function DepartmentTreeTableExample() {
+  return (
+    <DataTable
+      columns={deptColumns}
+      data={departmentsData}
+      enableExpanding={true}
+      getSubRows={(row) => row.subRows}
+      maxIndentDepth={4}  // Giới hạn thụt dòng tối đa 4 cấp để không làm co hẹp layout
+      indentSize={1.25}   // 1.25rem mỗi cấp
+    />
+  );
+}
+```
+
+---
+
 ## ⚙️ Bảng thuộc tính (Props Table)
 
 ### `<DataTable />`
@@ -278,6 +375,21 @@ export function ServerSideTableExample() {
 | `enableColumnOrdering` | `boolean` | `false` | Bật tính năng kéo thả thay đổi thứ tự các cột (Drag-and-Drop Column Ordering) |
 | `columnOrder` | `string[]` | `undefined` | Trạng thái mảng thứ tự các cột điều khiển ngoài |
 | `onColumnOrderChange` | `(order) => void` | `undefined` | Callback khi thứ tự cột thay đổi do kéo thả |
+| `enableExpanding` | `boolean` | `false` | Bật tính năng mở rộng dòng (tự động bật nếu có `renderExpandedRow` hoặc `getSubRows`) |
+| `expanded` | `ExpandedState` | `undefined` | Trạng thái dòng mở rộng điều khiển ngoài (Controlled state) |
+| `onExpandedChange` | `(expanded) => void` | `undefined` | Callback khi trạng thái mở rộng dòng thay đổi |
+| `getSubRows` | `(row, index) => TData[] \| undefined` | `undefined` | Hàm lấy dữ liệu con cho cấu trúc cây đa tầng |
+| `getRowCanExpand` | `(row) => boolean` | `undefined` | Điều kiện tùy biến xác định dòng nào có thể mở rộng |
+| `renderExpandedRow` | `(row) => ReactNode` | `undefined` | Render component tùy biến (Detail Panel) bên dưới dòng cha khi mở rộng |
+| `showExpandColumn` | `boolean` | `true` | Tự động hiển thị nút mở rộng dòng khi bật expanding |
+| `expandColumnMode` | `'integrated' \| 'standalone' \| 'none'` | `'integrated'` | Chế độ hiển thị nút mở rộng (`integrated` gộp vào cột đầu tiên, `standalone` tách thành cột `_expand` riêng) |
+| `expandColumnId` | `string` | `undefined` | ID của cột được gộp nút mở rộng khi dùng `expandColumnMode='integrated'` (mặc định lấy cột nội dung đầu tiên) |
+| `expandColumnPosition` | `'start' \| 'end'` | `'start'` | Vị trí đặt cột nút mở rộng dòng khi ở chế độ `standalone` |
+| `maxIndentDepth` | `number` | `4` | Cấp độ sâu thụt lề tối đa cho Tree Data (tránh làm vỡ layout khi lồng sâu) |
+| `indentSize` | `number` | `1.25` | Kích thước thụt lề mỗi cấp tính theo đơn vị `rem` |
+| `manualExpanding` | `boolean` | `false` | Bật chế độ mở rộng thủ công từ máy chủ (Server-side) |
+| `autoResetExpanded` | `boolean` | `true` | Tự động thu gọn các dòng khi dữ liệu thay đổi |
+| `paginateExpandedRows` | `boolean` | `true` | Phân trang các dòng con cùng với các dòng chính của bảng |
 | `searchPlaceholder`| `string` | `"Tìm kiếm trong bảng..."` | Placeholder cho ô tìm kiếm |
 | `toolbarActions` | `ReactNode` | `undefined` | Các nút hành động thêm ở góc phải toolbar |
 | `renderBulkActions`| `(selectedRows) => ReactNode` | `undefined` | Render các nút hành động hàng loạt khi chọn dòng |
@@ -286,6 +398,7 @@ export function ServerSideTableExample() {
 | `manualPagination` | `boolean` | `false` | Bật chế độ phân trang từ máy chủ (Server-side) |
 | `manualSorting` | `boolean` | `false` | Bật chế độ sắp xếp từ máy chủ (Server-side) |
 | `manualFiltering` | `boolean` | `false` | Bật chế độ tìm kiếm từ máy chủ (Server-side) |
+| `debounceMs` | `number` | `300` | Thời gian trì hoãn debounce (ms) khi thay đổi bộ lọc hoặc tìm kiếm ở Server-side (`manualFiltering: true`). Đặt 0 để tắt debounce. |
 | `pageCount` | `number` | `undefined` | Tổng số trang (khi dùng `manualPagination`) |
 | `rowCount` | `number` | `undefined` | Tổng số dòng dữ liệu thực tế (khi dùng `manualPagination`) |
 | `onRowClick` | `(row) => void` | `undefined` | Sự kiện click chuột vào một dòng |

package/docs/hooks/useInfiniteScroll.md

@@ -58,7 +58,7 @@ export function PostFeed() {
   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">
+        <div key={idx} className="p-4 border rounded-lg shadow-sm bg-white">
           {post}
         </div>
       ))}