@openway/ui 1.0.0 → 1.0.2

package/docs/components/tabs.md

@@ -0,0 +1,432 @@
+# 📑 Tabs Component (`@owa/ui`)
+
+Bộ component **Tabs** tương tác cao, thiết kế chuẩn **Compound Components Pattern** (`<Tabs>`, `<TabList>`, `<Tab>`, `<TabPanels>`, `<TabPanel>`), tích hợp **Sliding Animated Indicator**, **Overflow Scroll**, **Custom Hook `useTabIndicator`**, **Safe Config Fallback** 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 `<Tabs>`, `<TabList>`, `<Tab>`, `<TabPanels>`, `<TabPanel>`, tối đa hóa khả năng tùy biến layout và composition.
+- **Sliding Animated Indicator mượt mà**: Tự động tính toán vị trí, kích thước và chuyển động trượt mượt mà cho mọi variant (`line`, `solid`, `bordered`, `flat`), hỗ trợ tự động căn chỉnh khi resize màn hình thông qua `ResizeObserver`.
+- **Custom Hook `useTabIndicator` độc lập**: Tách biệt toàn bộ logic tính toán toạ độ indicator, kiểm tra tràn viền và điều hướng bàn phím thành hook riêng để dễ bảo trì và tái sử dụng.
+- **Controlled & Uncontrolled Mode**: Hỗ trợ linh hoạt cả `activeKey` + `onChange` (Controlled) và `defaultActiveKey` (Uncontrolled).
+- **3 Kích thước tiêu chuẩn (`size`)**: `sm`, `md` (*mặc định*), `lg`.
+- **5 Biến thể giao diện (`variant`)**:
+  - `line` *(mặc định)*: Thanh gạch dưới/bên trượt mượt mà.
+  - `solid`: Khối pill nền đậm nổi bật.
+  - `bordered`: Bao khung viền quanh tab.
+  - `flat`: Khối pill nền mềm nhạt (soft pill).
+  - `other`: Tự do tùy biến 100% qua `className`.
+- **7 Chủ đề màu sắc (`color`)**: `primary`, `secondary`, `neutral`, `error`, `success`, `warning`, `info`.
+- **6 Tùy chỉnh bo góc (`radius`)**: `none`, `sm`, `md` (*mặc định*), `lg`, `xl`, `full`.
+- **Hướng & Vị trí đa dạng (`orientation` & `placement`)**:
+  - Ngang (`horizontal`): `top` (*mặc định*), `bottom`.
+  - Dọc (`vertical`): `left`, `right`.
+- **Cuộn khi tràn viền (Scrollable Overflow & Chevrons)**: Tự động hiển thị 2 nút chevron cuộn trái/phải khi danh sách tabs vượt quá chiều rộng container, tự động cuộn `scrollIntoView` tab active.
+- **Đóng / Xóa tab tiện lợi (`closable`)**: Cho phép click nút đóng hoặc nhấn phím `Delete` / `Backspace` khi đang focus vào tab.
+- **WAI-ARIA Accessibility & Keyboard Navigation**: Hỗ trợ đầy đủ `role="tablist"`, `role="tab"`, `role="tabpanel"`, `aria-selected`, `aria-controls`, phím mũi tên `ArrowLeft` / `ArrowRight` / `ArrowUp` / `ArrowDown`, `Home`, `End`.
+- **Safe Config Fallback**: Tích hợp hàm `getSafeConfig` 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 {
+  Tabs,
+  TabList,
+  Tab,
+  TabPanels,
+  TabPanel,
+  useTabsContext,
+  useTabIndicator,
+} from "@owa/ui";
+
+import type {
+  TabsProps,
+  TabListProps,
+  TabProps,
+  TabPanelsProps,
+  TabPanelProps,
+  TabSize,
+  TabVariant,
+  TabColor,
+  TabRadius,
+  TabOrientation,
+  TabPlacement,
+  UseTabIndicatorOptions,
+} from "@owa/ui";
+```
+
+---
+
+## 📖 Hướng dẫn sử dụng
+
+### 1. Cách sử dụng cơ bản (Compound Components)
+
+```tsx
+import { Tabs, TabList, Tab, TabPanels, TabPanel } from "@owa/ui";
+
+export function BasicTabsExample() {
+  return (
+    <Tabs defaultActiveKey="overview" variant="line" color="primary">
+      <TabList>
+        <Tab value="overview" label="Tổng quan" />
+        <Tab value="profile" label="Hồ sơ" />
+        <Tab value="settings" label="Cài đặt" />
+      </TabList>
+
+      <TabPanels>
+        <TabPanel value="overview">
+          <p className="p-4 text-neutral-700">Nội dung trang tổng quan</p>
+        </TabPanel>
+        <TabPanel value="profile">
+          <p className="p-4 text-neutral-700">Thông tin hồ sơ người dùng</p>
+        </TabPanel>
+        <TabPanel value="settings">
+          <p className="p-4 text-neutral-700">Cấu hình cài đặt hệ thống</p>
+        </TabPanel>
+      </TabPanels>
+    </Tabs>
+  );
+}
+```
+
+---
+
+### 2. Chế độ điều khiển (Controlled vs Uncontrolled)
+
+#### a) Controlled Mode (Quản lý state từ bên ngoài)
+```tsx
+import { useState } from "react";
+import { Tabs, TabList, Tab, TabPanels, TabPanel } from "@owa/ui";
+
+export function ControlledTabs() {
+  const [activeKey, setActiveKey] = useState<string | number>("tab-1");
+
+  return (
+    <Tabs activeKey={activeKey} onChange={(key) => setActiveKey(key)}>
+      <TabList>
+        <Tab value="tab-1" label="Tab 1" />
+        <Tab value="tab-2" label="Tab 2" />
+      </TabList>
+      <TabPanels>
+        <TabPanel value="tab-1">Nội dung 1</TabPanel>
+        <TabPanel value="tab-2">Nội dung 2</TabPanel>
+      </TabPanels>
+    </Tabs>
+  );
+}
+```
+
+#### b) Uncontrolled Mode (Tự quản lý nội bộ với `defaultActiveKey`)
+```tsx
+<Tabs defaultActiveKey="tab-2">
+  <TabList>
+    <Tab value="tab-1" label="Tab 1" />
+    <Tab value="tab-2" label="Tab 2" />
+  </TabList>
+  <TabPanels>
+    <TabPanel value="tab-1">Nội dung 1</TabPanel>
+    <TabPanel value="tab-2">Nội dung 2</TabPanel>
+  </TabPanels>
+</Tabs>
+```
+
+---
+
+### 3. Các kích thước (`size`)
+
+Hỗ trợ 3 kích cỡ: `sm`, `md` (*mặc định*), `lg`:
+
+```tsx
+<Tabs size="sm" defaultActiveKey="1">
+  <TabList>
+    <Tab value="1" label="Small Tab" />
+    <Tab value="2" label="Tab 2" />
+  </TabList>
+  <TabPanels>
+    <TabPanel value="1">Nội dung kích thước nhỏ</TabPanel>
+    <TabPanel value="2">Nội dung 2</TabPanel>
+  </TabPanels>
+</Tabs>
+
+<Tabs size="md" defaultActiveKey="1">
+  <TabList>
+    <Tab value="1" label="Medium Tab (Mặc định)" />
+    <Tab value="2" label="Tab 2" />
+  </TabList>
+  <TabPanels>
+    <TabPanel value="1">Nội dung kích thước vừa</TabPanel>
+    <TabPanel value="2">Nội dung 2</TabPanel>
+  </TabPanels>
+</Tabs>
+
+<Tabs size="lg" defaultActiveKey="1">
+  <TabList>
+    <Tab value="1" label="Large Tab" />
+    <Tab value="2" label="Tab 2" />
+  </TabList>
+  <TabPanels>
+    <TabPanel value="1">Nội dung kích thước lớn</TabPanel>
+    <TabPanel value="2">Nội dung 2</TabPanel>
+  </TabPanels>
+</Tabs>
+```
+
+---
+
+### 4. Các biến thể giao diện (`variant`)
+
+```tsx
+// 1. Line (Mặc định): Thanh gạch dưới/bên trượt
+<Tabs variant="line" defaultActiveKey="1">...</Tabs>
+
+// 2. Solid: Khối pill nền nổi bật
+<Tabs variant="solid" defaultActiveKey="1">...</Tabs>
+
+// 3. Bordered: Bao viền khung
+<Tabs variant="bordered" defaultActiveKey="1">...</Tabs>
+
+// 4. Flat: Khối pill nền mềm nhạt
+<Tabs variant="flat" defaultActiveKey="1">...</Tabs>
+
+// 5. Other: Tự do tùy biến class hoàn toàn
+<Tabs variant="other" defaultActiveKey="1">...</Tabs>
+```
+
+---
+
+### 5. Các chủ đề màu sắc (`color`)
+
+Cung cấp 7 màu sắc theo chuẩn Design System:
+
+```tsx
+<Tabs color="primary" variant="solid" defaultActiveKey="1">...</Tabs>
+<Tabs color="secondary" variant="solid" defaultActiveKey="1">...</Tabs>
+<Tabs color="neutral" variant="solid" defaultActiveKey="1">...</Tabs>
+<Tabs color="error" variant="solid" defaultActiveKey="1">...</Tabs>
+<Tabs color="success" variant="solid" defaultActiveKey="1">...</Tabs>
+<Tabs color="warning" variant="solid" defaultActiveKey="1">...</Tabs>
+<Tabs color="info" variant="solid" defaultActiveKey="1">...</Tabs>
+```
+
+---
+
+### 6. Hướng và Vị trí (`orientation` & `placement`)
+
+```tsx
+// Dọc bên trái (Vertical Left)
+<Tabs orientation="vertical" placement="left" defaultActiveKey="1">
+  <TabList>
+    <Tab value="1" label="Menu 1" />
+    <Tab value="2" label="Menu 2" />
+  </TabList>
+  <TabPanels>
+    <TabPanel value="1">Nội dung menu 1</TabPanel>
+    <TabPanel value="2">Nội dung menu 2</TabPanel>
+  </TabPanels>
+</Tabs>
+
+// Dọc bên phải (Vertical Right)
+<Tabs orientation="vertical" placement="right" defaultActiveKey="1">...</Tabs>
+
+// Ngang phía dưới (Horizontal Bottom)
+<Tabs orientation="horizontal" placement="bottom" defaultActiveKey="1">...</Tabs>
+```
+
+---
+
+### 7. Icon, Badge & Tab có thể đóng (`closable` & `onClose`)
+
+```tsx
+import { Tabs, TabList, Tab, TabPanels, TabPanel } from "@owa/ui";
+import { HomeIcon, UserIcon, SettingsIcon } from "@/components/icons";
+
+export function RichTabsExample() {
+  const handleClose = (key: string | number) => {
+    console.log("Đóng tab:", key);
+  };
+
+  return (
+    <Tabs defaultActiveKey="tab-1" onClose={handleClose}>
+      <TabList>
+        {/* Tab có icon đầu */}
+        <Tab value="tab-1" startIcon={<HomeIcon />} label="Trang chủ" />
+        
+        {/* Tab có badge số lượng */}
+        <Tab value="tab-2" startIcon={<UserIcon />} badge={5} label="Thông báo" />
+        
+        {/* Tab có thể đóng (closable) & vô hiệu hóa */}
+        <Tab value="tab-3" startIcon={<SettingsIcon />} label="Tạm thời" closable />
+        <Tab value="tab-4" label="Bị khóa" disabled />
+      </TabList>
+
+      <TabPanels>
+        <TabPanel value="tab-1">Nội dung trang chủ</TabPanel>
+        <TabPanel value="tab-2">Nội dung thông báo</TabPanel>
+        <TabPanel value="tab-3">Nội dung tab tạm thời</TabPanel>
+        <TabPanel value="tab-4">Nội dung bị khóa</TabPanel>
+      </TabPanels>
+    </Tabs>
+  );
+}
+```
+
+---
+
+### 8. Cuộn ngang khi tràn viền (Scrollable Overflow) & Canh giữa (`centered`)
+
+Khi danh sách tab có độ dài lớn vượt quá container, `TabList` sẽ tự động hiển thị 2 nút chevron trái/phải để người dùng cuộn mượt mà:
+
+```tsx
+// Canh giữa các tab trong container
+<Tabs defaultActiveKey="1">
+  <TabList centered>
+    <Tab value="1" label="Tab 1" />
+    <Tab value="2" label="Tab 2" />
+  </TabList>
+  <TabPanels>...</TabPanels>
+</Tabs>
+
+// Tabs fullWidth tràn đều 100%
+<Tabs fullWidth defaultActiveKey="1">
+  <TabList>
+    <Tab value="1" label="Tab 1" />
+    <Tab value="2" label="Tab 2" />
+  </TabList>
+  <TabPanels>...</TabPanels>
+</Tabs>
+```
+
+---
+
+### 9. Nội dung mở rộng (`extra`) & Tối ưu DOM (`destroyInactiveTabPane`)
+
+```tsx
+<Tabs defaultActiveKey="1" destroyInactiveTabPane>
+  <TabList
+    extra={
+      <button className="px-3 py-1.5 text-xs bg-primary-50 text-primary-700 rounded-md font-medium hover:bg-primary-100">
+        + Thêm mới
+      </button>
+    }
+  >
+    <Tab value="1" label="Tab 1" />
+    <Tab value="2" label="Tab 2" />
+  </TabList>
+  <TabPanels>
+    {/* Khi tab không active, DOM của TabPanel sẽ được unmount hoàn toàn để tiết kiệm bộ nhớ */}
+    <TabPanel value="1">Nội dung 1</TabPanel>
+    <TabPanel value="2">Nội dung 2</TabPanel>
+  </TabPanels>
+</Tabs>
+```
+
+---
+
+## 🛠️ API Reference
+
+### 1. `TabsProps`
+
+Kế thừa các thuộc tính HTML `HTMLAttributes<HTMLDivElement>` ngoại trừ `onChange`:
+
+| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `activeKey` | `string \| number` | `undefined` | Khóa của tab đang active (Controlled mode). |
+| `defaultActiveKey` | `string \| number` | `undefined` | Khóa của tab active mặc định ban đầu (Uncontrolled mode). |
+| `onChange` | `(key: string \| number) => void` | `undefined` | Callback kích hoạt khi thay đổi tab được chọn. |
+| `onClose` | `(key: string \| number) => void` | `undefined` | Callback kích hoạt khi người dùng bấm nút đóng tab (`closable`). |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Kích thước giao diện chung cho các tab con. |
+| `variant` | `"line" \| "solid" \| "bordered" \| "flat" \| "other"` | `"line"` | Biến thể kiểu dáng thanh tab & indicator. |
+| `color` | `"primary" \| "secondary" \| "neutral" \| "error" \| "success" \| "warning" \| "info"` | `"primary"` | Chủ đề màu sắc theo Design System. |
+| `radius` | `"none" \| "sm" \| "md" \| "lg" \| "xl" \| "full"` | `"md"` | Độ bo góc của tab và sliding indicator. |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Chiều hiển thị danh sách tabs (ngang hoặc dọc). |
+| `placement` | `"top" \| "bottom" \| "left" \| "right"` | `"top"` | Vị trí đặt `TabList` so với `TabPanels`. |
+| `fullWidth` | `boolean` | `false` | Tự động giãn đều chiều rộng các tab vừa khớp 100% container. |
+| `disabled` | `boolean` | `false` | Vô hiệu hóa toàn bộ tabs trong nhóm. |
+| `destroyInactiveTabPane` | `boolean` | `false` | Tự động unmount nội dung khỏi DOM khi tab không active. |
+| `children` | `ReactNode` | `undefined` | Các component con (`<TabList>`, `<TabPanels>`). |
+| `className` | `string` | `""` | Class CSS tùy biến cho container bao ngoài. |
+| `ref` | `Ref<HTMLDivElement>` | `undefined` | Ref chuyển tiếp đến container Tabs. |
+
+---
+
+### 2. `TabListProps`
+
+Kế thừa `HTMLAttributes<HTMLDivElement>`:
+
+| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `children` | `ReactNode` | `undefined` | Danh sách các phần tử `<Tab>` con. |
+| `extra` | `ReactNode` | `undefined` | Nội dung hoặc nút hành động phụ đặt ở góc thanh tab list. |
+| `centered` | `boolean` | `false` | Canh giữa danh sách tabs trong container (`orientation="horizontal"`). |
+| `className` | `string` | `""` | Class CSS tùy biến bổ sung cho TabList. |
+| `ref` | `Ref<HTMLDivElement>` | `undefined` | Ref chuyển tiếp đến thẻ tablist. |
+
+---
+
+### 3. `TabProps`
+
+Kế thừa `ButtonHTMLAttributes<HTMLButtonElement>` ngoại trừ `value`:
+
+| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `value` | `string \| number` | *(Bắt buộc)* | Khóa định danh duy nhất của tab để liên kết với `TabPanel`. |
+| `label` | `ReactNode` | `undefined` | Tiêu đề hiển thị của tab. |
+| `startIcon` | `ReactNode` | `undefined` | Icon hiển thị trước tiêu đề. |
+| `endIcon` | `ReactNode` | `undefined` | Icon hiển thị sau tiêu đề. |
+| `badge` | `ReactNode` | `undefined` | Huy hiệu hoặc số lượng hiển thị trên tab. |
+| `disabled` | `boolean` | `false` | Vô hiệu hóa riêng tab này. |
+| `closable` | `boolean` | `false` | Cho phép hiển thị nút đóng tab (hỗ trợ phím Delete/Backspace). |
+| `onClose` | `(e: MouseEvent) => void` | `undefined` | Callback khi bấm nút đóng trên tab này. |
+| `children` | `ReactNode` | `undefined` | Nội dung tùy biến thay thế cho prop `label`. |
+| `className` | `string` | `""` | Class CSS tùy biến cho nút tab. |
+| `ref` | `Ref<HTMLButtonElement>` | `undefined` | Ref chuyển tiếp đến thẻ `<button>` của tab. |
+
+---
+
+### 4. `TabPanelsProps` & `TabPanelProps`
+
+#### `TabPanelsProps`
+| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `children` | `ReactNode` | `undefined` | Danh sách các component `<TabPanel>` con. |
+| `className` | `string` | `""` | Class CSS tùy biến cho khung chứa TabPanels. |
+| `ref` | `Ref<HTMLDivElement>` | `undefined` | Ref chuyển tiếp đến container TabPanels. |
+
+#### `TabPanelProps`
+| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả |
+| :--- | :--- | :--- | :--- |
+| `value` | `string \| number` | *(Bắt buộc)* | Khóa liên kết trực tiếp với `value` của `<Tab>` tương ứng. |
+| `destroyInactiveTabPane` | `boolean` | `undefined` | Ghi đè cấu hình unmount khỏi DOM khi tab không active riêng cho panel này. |
+| `children` | `ReactNode` | `undefined` | Nội dung hiển thị khi tab tương ứng đang active. |
+| `className` | `string` | `""` | Class CSS tùy biến cho panel nội dung. |
+| `ref` | `Ref<HTMLDivElement>` | `undefined` | Ref chuyển tiếp đến thẻ tabpanel. |
+
+---
+
+### 5. Hook `useTabIndicator`
+
+```tsx
+import { useTabIndicator } from "@owa/ui";
+
+const {
+  listRef,
+  indicatorStyle,
+  canScrollLeft,
+  canScrollRight,
+  checkScroll,
+  updateIndicator,
+  handleScrollLeft,
+  handleScrollRight,
+  handleKeyDown,
+} = useTabIndicator({
+  activeKey,
+  orientation,
+  placement,
+  variant,
+  color,
+  radius,
+});
+```

package/docs/components/textarea.md

@@ -0,0 +1,193 @@
+# 📝 TextArea Component (`@owa/ui`)
+
+Component **TextArea** đa năng, hỗ trợ **tự động co giãn chiều cao (AutoResize)** bằng thư viện `react-textarea-autosize`, tích hợp **Safe Config Fallback**, **quản lý Ref tối ưu** qua `@floating-ui/react`, **bộ đếm ký tự (Character Counter)** và tuân thủ đầy đủ tiêu chuẩn **WAI-ARIA Accessibility**.
+
+---
+
+## 🌟 Điểm nổi bật
+
+- **Tích hợp `react-textarea-autosize`**: Tự động tăng giảm chiều cao mượt mà theo nội dung nhập mà không làm giật khung hình (`layout shift`). Hỗ trợ cấu hình `minRows`, `maxRows`, `cacheMeasurements` và callback `onHeightChange`.
+- **Tùy chọn chuyển đổi linh hoạt**: Dễ dàng tắt chế độ co giãn tự động bằng `autoResize={false}` để chuyển về thẻ `<textarea>` truyền thống.
+- **5 Kích thước tiêu chuẩn (`size`)**: `xs`, `sm`, `md` (*mặc định*), `lg`, `xl` với font chữ, padding, kích thước nhãn và thông báo phụ được đồng bộ tỉ lệ.
+- **3 Biến thể giao diện (`variant`)**:
+  - `outline` *(mặc định)*: Viền nét rõ ràng quanh khung soạn thảo, hover/focus đổi màu viền chủ đề.
+  - `filled`: Nền pastel nhạt (`bg-{color}-50/60`), có viền bao quanh.
+  - `ghost`: Nền trong suốt, chỉ nổi bật khi hover hoặc focus.
+  - `other`: Bỏ qua các class màu mặc định, tự do áp dụng custom style qua `textareaWrapperClassName`.
+- **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`.
+- **3 Vị trí đặt nhãn (`labelPlacement`)**:
+  - `top` *(mặc định)*: Nhãn nằm phía trên ô textarea.
+  - `left`: Nhãn nằm ngang bên trái ô textarea (tự động căn chỉnh theo dạng flex-row).
+  - `floating`: Nhãn nổi bật vắt ngang viền trên của khung textarea.
+- **Trạng thái Loading & Xoay Spinner (`isLoading` & `showSpinner`)**:
+  - `isLoading={true}`: Tự động vô hiệu hóa ô nhập liệu (`disabled`), kích hoạt `aria-busy="true"` và `aria-disabled="true"`.
+  - `showSpinner`: Mặc định là `false`. Đặt `showSpinner={true}` khi muốn hiển thị icon xoay vòng ở góc phải trên.
+- **Nút xóa nhanh (`isClearable` & `onClear`)**: Hiển thị nút bấm xóa sạch nội dung ở góc phải trên khi ô có văn bản.
+- **Bộ đếm số lượng ký tự (`showCount` & `maxLength`)**:
+  - Hiển thị số lượng ký tự trực tiếp ở góc dưới bên phải (ví dụ: `45/500`).
+  - Tự động chặn nhập vượt quá số ký tự cho phép cả khi gõ và khi dán (paste).
+- **Quản lý Ref nâng cao**: Sử dụng `useMergeRefs` từ `@floating-ui/react` giúp gộp và chuyển tiếp `ref` mượt mà trong React 19.
+- **Safe Config Fallback**: Tích hợp hàm `getSafeConfig` đảm bảo component hoạt động an toàn, không bị crash kể cả khi truyền prop không hợp lệ.
+
+---
+
+## 🚀 Cài đặt & Import
+
+```tsx
+import { TextArea } from "@owa/ui";
+import type {
+  TextAreaProps,
+  TextAreaConfig,
+  TextAreaSize,
+  TextAreaVariant,
+  TextAreaColor,
+  TextAreaRadius,
+  TextAreaLabelPlacement,
+  TextAreaResize,
+} from "@owa/ui";
+```
+
+---
+
+## 📖 Hướng dẫn sử dụng
+
+### 1. Cách sử dụng cơ bản
+
+```tsx
+import { TextArea } from "@owa/ui";
+
+export function BasicTextAreaExample() {
+  return (
+    <div className="flex flex-col gap-4 max-w-md">
+      <TextArea
+        label="Mô tả chi tiết"
+        placeholder="Nhập mô tả sản phẩm của bạn..."
+      />
+    </div>
+  );
+}
+```
+
+---
+
+### 2. Tự động co giãn chiều cao (AutoResize)
+
+Mặc định `autoResize={true}` với số dòng tối thiểu `minRows={3}`:
+
+```tsx
+// Co giãn tự do từ 3 dòng trở lên
+<TextArea
+  label="Phản hồi ý kiến"
+  autoResize={true}
+  minRows={3}
+  maxRows={8}
+  onHeightChange={(height) => console.log("Chiều cao hiện tại:", height)}
+/>
+
+// Tắt autoResize để dùng chiều cao cố định
+<TextArea
+  label="Ghi chú cố định"
+  autoResize={false}
+  rows={4}
+  resize="vertical"
+/>
+```
+
+---
+
+### 3. Vị trí đặt nhãn (`labelPlacement`)
+
+```tsx
+// 1. Top (Mặc định)
+<TextArea label="Nhãn phía trên" labelPlacement="top" placeholder="Nhập văn bản..." />
+
+// 2. Left (Ngang bên trái)
+<TextArea label="Nhãn bên trái" labelPlacement="left" placeholder="Nhập văn bản..." />
+
+// 3. Floating (Nổi trên viền)
+<TextArea label="Nhãn nổi viền" labelPlacement="floating" placeholder="Nhập văn bản..." />
+```
+
+---
+
+### 4. Giới hạn ký tự & Bộ đếm (`showCount` & `maxLength`)
+
+```tsx
+<TextArea
+  label="Đánh giá sản phẩm"
+  maxLength={200}
+  showCount={true}
+  placeholder="Tối đa 200 ký tự (tự động chặn khi đạt giới hạn)..."
+/>
+```
+
+---
+
+### 5. Xóa nhanh & Trạng thái Loading
+
+```tsx
+<TextArea
+  label="Tìm kiếm nội dung"
+  isClearable={true}
+  onClear={() => console.log("Đã xóa sạch nội dung")}
+  defaultValue="Nội dung ban đầu"
+/>
+
+<TextArea
+  label="Đang đồng bộ dữ liệu"
+  isLoading={true}
+  showSpinner={true}
+  defaultValue="Vui lòng đợi..."
+/>
+```
+
+---
+
+### 6. Trạng thái Báo lỗi & Hướng dẫn (`errorMessage` & `helperText`)
+
+```tsx
+<TextArea
+  label="Địa chỉ giao hàng"
+  isRequired={true}
+  errorMessage="Địa chỉ không được để trống!"
+  isInvalid={true}
+/>
+
+<TextArea
+  label="Tiểu sử bản thân"
+  helperText="Hãy viết ngắn gọn 1-2 câu về kinh nghiệm của bạn."
+/>
+```
+
+---
+
+## 🛠 Bảng thông số Props (`TextAreaProps`)
+
+| Tên Prop | Kiểu dữ liệu | Giá trị mặc định | Mô tả |
+| :--- | :--- | :---: | :--- |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Kích cỡ giao diện (font chữ, padding, kích thước nhãn). |
+| `variant` | `'outline' \| 'filled' \| 'ghost' \| 'other'` | `'outline'` | Biến thể hiển thị giao diện. |
+| `color` | `'primary' \| 'secondary' \| 'error' \| 'success' \| 'warning' \| 'info' \| 'neutral'` | `'primary'` | Chủ đề màu sắc theo Design System. |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'` | Độ bo góc của khung viền textarea. |
+| `label` | `ReactNode` | — | Nhãn tiêu đề hiển thị cho ô nhập liệu. |
+| `labelPlacement` | `'top' \| 'left' \| 'floating'` | `'top'` | Vị trí hiển thị của nhãn. |
+| `config` | `TextAreaConfig` | — | Cấu hình tập trung các cờ trạng thái / tính năng (`isRequired`, `isInvalid`, `isLoading`, `showSpinner`, `isClearable`, `autoResize`, `showCount`, `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}`. |
+| `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. |
+| `autoResize` | `boolean` | `true` | Tự động co giãn chiều cao theo nội dung nhập. |
+| `minRows` | `number` | `3` | Số dòng hiển thị tối thiểu khi `autoResize` bật. |
+| `maxRows` | `number` | — | Số dòng hiển thị tối đa trước khi xuất hiện thanh cuộn. |
+| `onHeightChange` | `(height: number, meta: { rowHeight: number }) => void` | — | Callback khi chiều cao thay đổi do autoResize. |
+| `cacheMeasurements` | `boolean` | — | Bật bộ nhớ đệm kết quả đo chiều cao để tối ưu render. |
+| `showCount` | `boolean` | `false` | Hiển thị bộ đếm số lượng ký tự ở góc phải dưới. |
+| `maxLength` | `number` | — | Số ký tự tối đa cho phép nhập (chặn tự động khi đạt giới hạn). |
+| `resize` | `'none' \| 'vertical' \| 'horizontal' \| 'both'` | `'none'` | Tùy chọn kéo giãn khung thủ công. |
+| `isFullWidth` | `boolean` | `false` | Mở rộng chiếm toàn bộ 100% chiều ngang container cha. |
+| `ref` | `Ref<HTMLTextAreaElement>` | — | Ref chuyển tiếp đến thẻ `<textarea>` HTML bên dưới. |