@openway/ui 1.0.0 → 1.0.2

package/docs/components/radio.md

@@ -0,0 +1,245 @@
+# 🔘 Radio & RadioGroup Component (`@owa/ui`)
+
+Bộ đôi component **Radio** và **RadioGroup** 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. Radio
+- **Độ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ệ ô tròn, dot indicator bên trong, 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 đặc tương phản cao khi được chọn.
+  - `outline`: Nền trong suốt, viền và dot mang màu chủ đề.
+  - `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`.
+- **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. RadioGroup
+- **Kiến trúc Data-driven thuần túy**: Nhận danh sách lựa chọn qua prop `options: RadioOptionItem<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 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 mục thực sự được chọn).
+- **2 Bố cục sắp xếp (`orientation`)**: `vertical` (*mặc định*) và `horizontal`.
+
+---
+
+## 🚀 Cài đặt & Import
+
+```tsx
+import { Radio, RadioGroup } from "@owa/ui";
+import type {
+  RadioProps,
+  RadioGroupProps,
+  RadioOptionItem,
+  RadioSize,
+  RadioVariant,
+  RadioColor,
+  RadioLabelPlacement,
+  RadioSearchMode,
+} from "@owa/ui";
+```
+
+---
+
+## 📖 Hướng dẫn sử dụng
+
+### 1. Sử dụng Radio đơn lẻ
+
+```tsx
+import { useState } from "react";
+import { Radio } from "@owa/ui";
+
+export function SingleRadioExample() {
+  const [selected, setSelected] = useState(false);
+
+  return (
+    <Radio
+      checked={selected}
+      onChange={(e) => setSelected(e.target.checked)}
+      label="Nhận thông báo qua email"
+      helperText="Bạn có thể hủy đăng ký bất cứ lúc nào"
+    />
+  );
+}
+```
+
+---
+
+### 2. RadioGroup cơ bản (Data-driven)
+
+```tsx
+import { useState } from "react";
+import { RadioGroup } from "@owa/ui";
+
+export function BasicGroupExample() {
+  const [delivery, setDelivery] = useState<string | null>("standard");
+
+  return (
+    <RadioGroup
+      label="Phương thức giao hàng"
+      helperText="Chọn hình thức vận chuyển phù hợp"
+      value={delivery}
+      onChange={setDelivery}
+      color="primary"
+      orientation="vertical"
+      options={[
+        { value: "standard", label: "Giao hàng tiêu chuẩn (2-3 ngày)" },
+        { value: "express", label: "Giao hàng hỏa tốc (1 ngày)" },
+        { value: "same_day", label: "Giao hàng trong ngày" },
+      ]}
+    />
+  );
+}
+```
+
+---
+
+### 3. Tìm kiếm Client Mode (Fuzzy Search & Đa trường)
+
+```tsx
+import { useState } from "react";
+import { RadioGroup } 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 | null>("react");
+
+  return (
+    <RadioGroup
+      label="Chọn Framework chính"
+      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 { RadioGroup } from "@owa/ui";
+
+export function ServerSearchExample() {
+  const [selectedProduct, setSelectedProduct] = useState<string | null>(null);
+
+  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 (
+    <RadioGroup
+      label="Chọn sản phẩm yêu thích"
+      searchable
+      searchMode="server"
+      debounceMs={300}
+      onSearch={handleSearchProducts}
+      searchPlaceholder="Tìm kiếm sản phẩm từ máy chủ..."
+      preserveSelected
+      value={selectedProduct}
+      onChange={setSelectedProduct}
+      color="info"
+    />
+  );
+}
+```
+
+---
+
+## 🎛️ Bảng Props & API Reference
+
+### `RadioProps`
+
+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 tròn, dot và nhãn |
+| `variant` | `'filled' \| 'outline' \| 'soft' \| 'other'` | `'filled'` | Kiểu dáng hiển thị của box khi checked |
+| `color` | `'primary' \| 'secondary' \| 'error' \| 'success' \| 'warning' \| 'info' \| 'neutral'` | `'primary'` | Chủ đề màu sắc |
+| `disabled` | `boolean` | `false` | Vô hiệu hóa tương tác |
+| `readOnly` | `boolean` | `false` | Chế độ chỉ đọc |
+| `isLoading` | `boolean` | `false` | Trạng thái đang tải (spinner thay thế dot) |
+| `isRequired` | `boolean` | `false` | Đánh dấu bắt buộc (dấu `*` đỏ) |
+| `isInvalid` | `boolean` | `false` | Trạng thái báo lỗi viền đỏ |
+| `labelPlacement` | `'right' \| 'left'` | `'right'` | Vị trí hiển thị nhãn |
+| `label` | `ReactNode` | `undefined` | Nhãn văn bản cạnh ô radio |
+| `helperText` | `ReactNode` | `undefined` | Chú thích bên dưới |
+| `errorMessage` | `ReactNode` | `undefined` | Thông báo lỗi |
+| `dotIcon` | `ReactNode` | `RadioDotIcon` | Icon tùy biến thay thế dot bên trong |
+
+---
+
+### `RadioGroupProps<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` | `RadioOptionItem<TData>[]` | `[]` | Mảng dữ liệu các lựa chọn (Data-driven) |
+| `value` | `string \| null` | `undefined` | Giá trị đang chọn (Controlled) |
+| `defaultValue` | `string \| null` | `null` | Giá trị mặc định (Uncontrolled) |
+| `onChange` | `(value: string \| null) => void` | `undefined` | Callback khi lựa 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: RadioOptionItem<TData>, query: string) => boolean` | `undefined` | Hàm lọc tùy biến phía client |
+| `onSearch` | `(query: string) => Promise<RadioOptionItem<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 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` | `RadioSize` | `'md'` | Kích cỡ truyền xuống toàn bộ radio con |
+| `color` | `RadioColor` | `'primary'` | Màu sắc truyền xuống toàn bộ radio con |
+| `variant` | `RadioVariant` | `'filled'` | Biến thể truyền xuống toàn bộ radio 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 |
+
+---
+
+### `RadioOptionItem<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 |
+| `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`) |

package/docs/components/select.md

@@ -0,0 +1,254 @@
+# 🔽 Select & MultiSelect Component (`@openway/ui`)
+
+Bộ đôi component **Select** (Chọn đơn) và **MultiSelect** (Chọn nhiều) cao cấp, thiết kế theo chuẩn **Design System**, tuân thủ nghiêm ngặt **WAI-ARIA 1.2 Combobox/Listbox**, hỗ trợ **Zero `any`**, tìm kiếm **Client & Server**, phân trang vô tận với **TanStack Query v5** và hiệu ứng **Skeleton Loading**.
+
+---
+
+## 🌟 Điểm nổi bật
+
+- **2 Component chuyên biệt**:
+  - `<Select>`: Chọn 1 giá trị duy nhất, hỗ trợ placeholder, clearable, render custom value/option.
+  - `<MultiSelect>`: Chọn nhiều giá trị dưới dạng tags/chips, hỗ trợ xóa nhanh từng tag, nút clear all, giới hạn số lượng tag hiển thị (`maxTags`).
+- **2 Chế độ Tìm kiếm (`searchMode`)**:
+  - `client`: Tìm kiếm và sắp xếp kết quả ngay trên client với thuật toán xếp hạng từ khóa thông minh (`searchField`, `filterFn`).
+  - `server`: Tìm kiếm phía máy chủ. Tự động debounce từ khóa gõ theo `debounceMs` trước khi gọi `onSearch(query, filters)`.
+- **Tích hợp TanStack Query v5 & Infinite Scroll (`@openway/ui/query`)**:
+  - Hook chuyên dụng `useSelectInfiniteQuery` kết hợp `useInfiniteQuery` với `useInfiniteScroll`.
+  - Tự động gộp options từ tất cả các trang, khử trùng lặp theo `value`.
+  - Hiệu ứng **Skeleton** nhấp nháy ở đáy danh sách khi đang tải thêm trang (`isFetchingNextPage`).
+  - Không bị double-debounce, tải mượt mà qua native `IntersectionObserver`.
+- **Đầy đủ tính năng UI nâng cao**:
+  - `menuFilters`: Bộ lọc đa điều kiện tích hợp ngay trên thanh đầu của menu dropdown.
+  - `renderOption` & `renderValue`: Tùy biến hiển thị từng hàng option (avatar, description, badge...) và giá trị được chọn.
+  - `startContent` & `endContent`: Bổ sung icon hoặc nội dung phụ ở hai đầu trigger box.
+  - `portal={true}`: Render menu ra ngoài DOM qua `@floating-ui/react`, không bị tràn hoặc che khuất bởi `overflow: hidden`.
+- **Trợ năng WAI-ARIA & Điều hướng bàn phím**:
+  - Hỗ trợ đầy đủ phím mũi tên `ArrowUp`, `ArrowDown`, `Home`, `End`, `Enter` để chọn, `Escape` để đóng dropdown.
+
+---
+
+## 🚀 Cài đặt & Import
+
+```tsx
+// 1. Components & Types cơ bản
+import { Select, MultiSelect } from "@openway/ui";
+import type {
+  SelectProps,
+  MultiSelectProps,
+  SelectOptionItem,
+  SelectFilterField,
+} from "@openway/ui";
+
+// 2. Query Hook cho Server Infinite Scroll (Tùy chọn, cần @tanstack/react-query v5)
+import { useSelectInfiniteQuery } from "@openway/ui/query";
+```
+
+---
+
+## 📖 Hướng dẫn sử dụng
+
+### 1. Select cơ bản (Client Mode)
+
+```tsx
+import { useState } from "react";
+import { Select, SelectOptionItem } from "@openway/ui";
+
+const departments: SelectOptionItem<string>[] = [
+  { value: "hr", label: "Phòng Nhân sự" },
+  { value: "it", label: "Phòng Công nghệ Thông tin" },
+  { value: "sales", label: "Phòng Kinh doanh" },
+  { value: "mkt", label: "Phòng Marketing" },
+];
+
+export function BasicSelectExample() {
+  const [value, setValue] = useState<string | number | null>("it");
+
+  return (
+    <div className="max-w-sm">
+      <Select
+        label="Phòng ban"
+        placeholder="Chọn phòng ban..."
+        options={departments}
+        value={value}
+        onChange={(val) => setValue(val)}
+        clearable
+      />
+    </div>
+  );
+}
+```
+
+---
+
+### 2. MultiSelect với Tags
+
+```tsx
+import { useState } from "react";
+import { MultiSelect, SelectOptionItem } from "@openway/ui";
+
+const roles: SelectOptionItem[] = [
+  { value: "admin", label: "Quản trị viên" },
+  { value: "editor", label: "Biên tập viên" },
+  { value: "moderator", label: "Điều hành viên" },
+  { value: "viewer", label: "Người xem" },
+];
+
+export function MultiSelectExample() {
+  const [selectedRoles, setSelectedRoles] = useState<(string | number)[]>(["editor"]);
+
+  return (
+    <div className="max-w-md">
+      <MultiSelect
+        label="Vai trò người dùng"
+        placeholder="Chọn các vai trò..."
+        options={roles}
+        value={selectedRoles}
+        onChange={(vals) => setSelectedRoles(vals)}
+        searchable
+        clearable
+      />
+    </div>
+  );
+}
+```
+
+---
+
+### 3. Server Pagination & Infinite Scroll (`useSelectInfiniteQuery`)
+
+Đây là phương thức khuyên dùng khi dữ liệu từ máy chủ có số lượng lớn hoặc trả về theo từng trang:
+
+```tsx
+import { Select } from "@openway/ui";
+import { useSelectInfiniteQuery } from "@openway/ui/query";
+
+interface UserItem {
+  id: number;
+  name: string;
+  email: string;
+}
+
+export function ServerInfiniteSelectExample() {
+  const { selectProps, query } = useSelectInfiniteQuery<
+    UserItem,
+    { users: UserItem[]; nextCursor?: number },
+    number
+  >({
+    queryKey: ["users-infinite"],
+    queryFn: async ({ pageParam, search }) => {
+      const res = await fetch(
+        `/api/users?cursor=${pageParam}&q=${encodeURIComponent(search)}`
+      );
+      return res.json();
+    },
+    initialPageParam: 1,
+    getNextPageParam: (lastPage) => lastPage.nextCursor,
+    // Biến đổi entity trả về thành định dạng SelectOptionItem chuẩn
+    mapOption: (item) => {
+      const user = item as UserItem;
+      return {
+        value: user.id,
+        label: user.name,
+        description: user.email,
+        data: user,
+      };
+    },
+    debounceMs: 300,
+    endMessage: "Đã hiển thị toàn bộ người dùng",
+  });
+
+  return (
+    <div className="max-w-md">
+      <Select
+        {...selectProps}
+        label="Chọn thành viên"
+        placeholder="Tìm kiếm thành viên..."
+        searchable
+        clearable
+      />
+    </div>
+  );
+}
+```
+
+---
+
+### 4. Tùy biến Option (`renderOption`) & Rich Layout
+
+```tsx
+<Select
+  label="Chọn người dùng"
+  options={userOptions}
+  renderOption={(option, { isSelected, isFocused }) => (
+    <div className="flex items-center gap-2.5 py-1">
+      <img
+        src={option.data?.avatarUrl}
+        alt={option.label}
+        className="w-7 h-7 rounded-full object-cover"
+      />
+      <div>
+        <div className="font-medium text-sm text-neutral-800 dark:text-neutral-100">
+          {option.label}
+        </div>
+        <div className="text-xs text-neutral-400 dark:text-neutral-500">
+          {option.description}
+        </div>
+      </div>
+    </div>
+  )}
+/>
+```
+
+---
+
+### 5. Bộ lọc tích hợp trong Menu (`menuFilters`)
+
+```tsx
+const filterFields: SelectFilterField[] = [
+  {
+    name: "status",
+    label: "Trạng thái",
+    type: "select",
+    options: [
+      { value: "active", label: "Hoạt động" },
+      { value: "inactive", label: "Đã khóa" },
+    ],
+  },
+];
+
+<Select
+  label="Khách hàng"
+  options={customerOptions}
+  menuFilters={filterFields}
+  onMenuFilterChange={(filters) => {
+    console.log("Filter áp dụng:", filters);
+  }}
+/>
+```
+
+---
+
+## 🎛️ Bảng Props Chi tiết
+
+### Props dùng chung (`BaseSelectProps`)
+
+| Tên Prop | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `options` | `SelectOptionItem<TData>[]` | `[]` | Mảng danh sách các lựa chọn. |
+| `label` | `ReactNode` | `undefined` | Nhãn hiển thị phía trên trigger. |
+| `placeholder` | `string` | `"Select..."` | Văn bản gợi ý khi chưa chọn giá trị. |
+| `searchable` | `boolean` | `false` | Bật ô nhập tìm kiếm trong menu. |
+| `searchMode` | `"client" \| "server"` | `"client"` | Chế độ tìm kiếm nội bộ hay gọi server. |
+| `debounceMs` | `number` | `300` | Thời gian hoãn tìm kiếm server (ms). |
+| `onSearch` | `(query, filters) => void` | `undefined` | Callback khi người dùng tìm kiếm ở chế độ server. |
+| `listFooter` | `ReactNode` | `undefined` | Phần tử hiển thị dưới đáy danh sách (dùng cho Sentinel / Skeleton). |
+| `clearable` | `boolean` | `false` | Hiển thị nút xóa nhanh giá trị đã chọn. |
+| `disabled` | `boolean` | `false` | Khóa không cho phép tương tác. |
+| `isLoading` | `boolean` | `false` | Hiển thị trạng thái đang tải dữ liệu. |
+| `portal` | `boolean` | `true` | Render menu qua portal chống tràn khung nhìn. |
+| `maxMenuHeight` | `number` | `280` | Chiều cao tối đa của khung menu cuộn (px). |
+| `renderOption` | `(option, state) => ReactNode` | `undefined` | Hàm custom render từng option trong listbox. |
+| `renderValue` | `(selected) => ReactNode` | `undefined` | Hàm custom hiển thị giá trị trên trigger. |
+| `menuFilters` | `SelectFilterField[]` | `undefined` | Danh sách bộ lọc bổ sung gắn ở đầu dropdown. |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Kích thước trigger box. |
+| `variant` | `"outline" \| "filled" \| "soft"`| `"outline"` | Biến thể giao diện đường viền / nền. |

package/docs/components/skeleton.md

@@ -0,0 +1,150 @@
+# 💀 Skeleton & LoadingImage Component (`@openway/ui`)
+
+Bộ đôi component **Skeleton** và **LoadingImage** hiện đại, hiệu năng cao, thiết kế chuẩn **Design System**, hỗ trợ placeholder tải dữ liệu mượt mà, chống giật layout (Cumulative Layout Shift - CLS), tích hợp **Safe Config Fallback** (`getSafeConfig`) và tuân thủ tiêu chuẩn **WAI-ARIA Accessibility**.
+
+---
+
+## 🌟 Điểm nổi bật
+
+- **Skeleton Placeholder**:
+  - **3 Biến thể animation (`variant`)**:
+    - `pulse` *(mặc định)*: Hiệu ứng nhịp thở mờ dần mượt mà.
+    - `wave`: Hiệu ứng shimmer ánh sáng lướt chéo từ góc trên-trái xuống góc dưới-phải (sử dụng GPU-accelerated CSS).
+    - `none`: Placeholder tĩnh không chuyển động.
+  - **2 Kiểu hình dạng (`shape`)**:
+    - `rectangle` *(mặc định)*: Hình chữ nhật hoặc vuông, kết hợp với `radius`.
+    - `circle`: Hình tròn hoàn hảo (`rounded-full`), tự động bỏ qua `radius`.
+  - **6 Mức bo góc (`radius`)**: `none`, `sm`, `md` *(mặc định)*, `lg`, `xl`, `full`.
+  - **Multi-line mode (`lines`)**: Tự động xếp chồng nhiều dòng văn bản theo dạng đoạn văn, với dòng cuối cùng tự động thu hẹp 60% chiều rộng để tạo cảm giác tự nhiên.
+  - **Linh hoạt kích thước (`width`, `height`, `gap`)**: Nhận cả số nguyên (`px`) lẫn chuỗi CSS (`rem`, `%`, `vh`...).
+
+- **LoadingImage**:
+  - **Tích hợp Next.js Image**: Kế thừa toàn bộ tối ưu hóa của `next/image` (`fill`, `priority`, `sizes`, `quality`...).
+  - **Hỗ trợ đa dạng nguồn ảnh (`src`)**: Nhận đường dẫn ảnh URL/StaticImport, đồng thời hỗ trợ trực tiếp đối tượng **`File`** hoặc **`Blob`** (tự động tạo & giải phóng Object URL an toàn, không memory leak).
+  - **Tự động tối ưu `unoptimized`**: Tự động kích hoạt khi nhận `File` / `Blob` để tránh lỗi phân giải trên Image Optimization server của Next.js.
+  - **Tùy biến căn chỉnh (`objectFit`)**: Hỗ trợ 5 kiểu `cover` *(mặc định)*, `contain`, `fill`, `none`, `scale-down`.
+  - **Tự động reset trạng thái**: Reset `isLoaded` và `hasError` khi `src` thay đổi.
+  - **Fallback Error State**: Tự động hiển thị icon placeholder dự phòng khi ảnh tải lỗi (`onError`).
+
+- **Safe Config Fallback**: Tích hợp hàm `getSafeConfig` từ `@/utils/function` đảm bảo an toàn tuyệt đối, không crash giao diện khi nhận giá trị `variant`, `radius`, `objectFit` không hợp lệ.
+- **Trợ năng (Accessibility)**: Tích hợp đầy đủ `role="status"`, `aria-label="Loading..."`.
+
+---
+
+## 🚀 Cài đặt & Import
+
+```tsx
+import { Skeleton, LoadingImage } from "@openway/ui";
+import type {
+  SkeletonProps,
+  SkeletonVariant,
+  SkeletonShape,
+  SkeletonRadius,
+  SkeletonObjectFit,
+  LoadingImageProps,
+} from "@openway/ui";
+```
+
+---
+
+## 📖 Hướng dẫn sử dụng
+
+### 1. Skeleton cơ bản
+
+```tsx
+import { Skeleton } from "@openway/ui";
+
+export function BasicSkeletonExample() {
+  return (
+    <div className="space-y-4">
+      {/* Khối đơn */}
+      <Skeleton width="100%" height="2rem" />
+
+      {/* Avatar tròn */}
+      <Skeleton shape="circle" width={48} height={48} />
+
+      {/* Hiệu ứng sóng wave */}
+      <Skeleton variant="wave" width="200px" height="1.5rem" />
+    </div>
+  );
+}
+```
+
+### 2. Multi-line Skeleton (Đoạn văn bản)
+
+```tsx
+<Skeleton lines={3} height="1rem" gap="0.75rem" />
+```
+
+### 3. LoadingImage với URL hoặc File / Blob
+
+```tsx
+import { LoadingImage } from "@openway/ui";
+
+export function ImageExamples({ file }: { file?: File }) {
+  return (
+    <div className="flex gap-4">
+      {/* Load ảnh qua URL với bo góc lg */}
+      <LoadingImage
+        src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=400"
+        alt="Mountain view"
+        width={300}
+        height={200}
+        radius="lg"
+        objectFit="cover"
+      />
+
+      {/* Load ảnh trực tiếp từ đối tượng File (Upload preview) */}
+      {file && (
+        <LoadingImage
+          src={file}
+          alt="Upload preview"
+          width={150}
+          height={150}
+          radius="full"
+          objectFit="contain"
+        />
+      )}
+    </div>
+  );
+}
+```
+
+---
+
+## ⚙️ Props API Reference
+
+### `SkeletonProps`
+
+| Prop | Type | Default | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `variant` | `'pulse' \| 'wave' \| 'none'` | `'pulse'` | Kiểu hiệu ứng hoạt ảnh placeholder |
+| `shape` | `'rectangle' \| 'circle'` | `'rectangle'` | Hình dạng hiển thị |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'` | Độ bo góc (chỉ áp dụng khi `shape === 'rectangle'`) |
+| `width` | `string \| number` | — | Chiều rộng (px hoặc chuỗi CSS) |
+| `height` | `string \| number` | `'1rem'` | Chiều cao (px hoặc chuỗi CSS) |
+| `lines` | `number` | `1` | Số dòng hiển thị dạng cột (khi > 1) |
+| `gap` | `string \| number` | `'0.5rem'` | Khoảng cách giữa các dòng khi `lines > 1` |
+| `className` | `string` | `""` | Tùy biến class Tailwind bên ngoài |
+| `ref` | `React.Ref<HTMLDivElement>` | — | Ref trỏ tới thẻ div gốc |
+
+### `LoadingImageProps`
+
+| Prop | Type | Default | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `src` | `ImageProps['src'] \| File \| Blob \| ServerFile` | — | Nguồn ảnh (URL, import tĩnh, File/Blob hoặc ServerFile) |
+| `alt` | `string` | `""` | Văn bản thay thế cho ảnh |
+| `width` | `number` | — | Chiều rộng hiển thị (nếu không dùng `fill`) |
+| `height` | `number` | — | Chiều cao hiển thị (nếu không dùng `fill`) |
+| `fill` | `boolean` | `false` | Co giãn ảnh lấp đầy wrapper cha |
+| `skeletonVariant` | `'pulse' \| 'wave' \| 'none'` | `'pulse'` | Variant của skeleton khi đang tải |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'` | Bo góc áp dụng cho cả skeleton và ảnh |
+| `objectFit` | `'cover' \| 'contain' \| 'fill' \| 'none' \| 'scale-down'` | `'cover'` | Kiểu căn chỉnh ảnh |
+| `preview` | `boolean` | `true` | Bật xem trước ảnh phóng to trong modal khi click (qua FilePreview & FileContainer) |
+| `wrapperClassName` | `string` | `""` | Class tùy biến cho wrapper div |
+| `wrapperStyle` | `CSSProperties` | — | Style inline cho wrapper div |
+| `onClick` | `(e) => void` | — | Callback khi click vào ảnh / wrapper |
+| `onLoad` | `(e) => void` | — | Callback khi ảnh tải thành công |
+| `onError` | `(e) => void` | — | Callback khi ảnh gặp lỗi tải |
+| `ref` | `React.Ref<HTMLDivElement>` | — | Ref trỏ tới thẻ wrapper div |
+