@comitor/ui 0.1.0 → 0.2.1

package/README.md

@@ -8,11 +8,16 @@ component ghép sẵn và khung ứng dụng (shell) kiểu workspace × app.
 - Token brand nằm ở **`styles.css`** — đổi token, bump version, mọi app nhận cùng một thay đổi.
 - Server-component-friendly: `"use client"` chỉ nằm ở file thật sự cần.
 
-> Trạng thái: `0.1.0` — **đã port xong** 51 primitive + 24 composite + 18 file shell + chart, và đã qua
-> **một đợt sửa theo review** (tương phản màu theo WCAG, thang đổ bóng 4 bậc, a11y tầng shell, chuỗi
-> hiển thị của Tier 2 override được). `typecheck`, `build`, `lint`, `verify:directives`, `check:exports`
-> đều xanh. API còn có thể đổi cho tới `1.0.0` — thay đổi phá vỡ tương thích ghi ở
-> [docs/quyet-dinh-tich-hop.md](docs/quyet-dinh-tich-hop.md).
+> Trạng thái: `0.2.0` — 51 primitive + 24 composite + 18 file shell + chart, đã qua **một đợt sửa theo
+> review** (tương phản màu theo WCAG, thang đổ bóng 4 bậc, a11y tầng shell, chuỗi hiển thị của Tier 2
+> override được) và **một đợt dọn bề mặt API** (0.1.0 chưa app nào import — lần cuối đổi/xoá tên mà
+> không ai phải viết codemod).
+>
+> ⚠ **`0.2.0` phá vỡ tương thích với `0.1.0`**: đổi tên hàm màu avatar, bỏ `avatarPalette` /
+> `LETTER_AVATAR_TONES` / `hashString` / `pickByString`, `useIsMac` chỉ còn một cửa, `DataTable` đổi
+> tên prop, và **giá trị một số token màu đã đổi**. Bảng chuyển đổi đầy đủ:
+> [CHANGELOG.md](CHANGELOG.md). Trong dải `0.x`, thay đổi phá vỡ tương thích đi kèm bump **minor**;
+> API chốt ở `1.0.0`.
 
 ---
 
@@ -36,9 +41,19 @@ pnpm add react-hook-form    # cho @comitor/ui/form
 | `lucide-react` | `>=0.540.0` | ✅ | luôn (tránh 2 bản icon trong bundle) |
 | `next` | `>=15` | — | `/shell` |
 | `next-themes` | `>=0.4` | — | `/shell` (context singleton — app và package phải dùng **cùng một bản**) |
-| `recharts` | `^2.15.0` | — | `/chart` |
+| `recharts` | `>=2.15.0` | — | `/chart` (kiểu đã dựng cho **cả 2.x lẫn 3.x**, xem ghi chú dưới) |
 | `react-hook-form` | `^7.54.0` | — | `/form` (context singleton) |
 
+> **Vì sao `recharts` là `>=` chứ không phải `^`.** `^2.15.0` loại thẳng recharts 3 — mà 3.x
+> chạy tốt với gói này, nên app nào đã lên 3.x cũng ăn một dòng `unmet peer` không có cách sửa.
+> Kiểu của tầng `/chart` không còn dẫn xuất `payload`/`label` từ `TooltipProps`/`LegendProps`
+> của recharts (3.x đã bỏ hai trường đó khỏi props, chuyển sang context nội bộ) mà tự khai
+> `ChartPayloadItem` — phần giao của hai bản. `pnpm typecheck && pnpm build` được chạy **trên cả
+> recharts 2.15.4 lẫn 3.10.1** trước khi nới dải này.
+>
+> `lucide-react` cũng là `>=` vì cùng lý do: thang phiên bản của nó nhảy `0.x` → `1.x` mà API
+> icon không đổi. Đã kiểm typecheck + build với `1.33.0`.
+
 ## 2. Nạp `styles.css` — ĐỌC KỸ, đây là chỗ dễ sai nhất
 
 Đặt import trong **`app/globals.css`**, ngay sau `@import "tailwindcss"`:
@@ -117,7 +132,7 @@ barrel chính re-export **một** file có `import` tới peer optional là mọ
 
 | Entry | Nội dung | Peer optional kéo theo |
 |---|---|---|
-| `@comitor/ui` | Tier 1 (primitive) + Tier 2 (composite) + `cn` + token TS | **không có** — chạy được ở Vite, Storybook, test runner |
+| `@comitor/ui` | Tier 1 (primitive) + Tier 2 (composite) + `cn` + token TS + `useIsMac` | **không có** — chạy được ở Vite, Storybook, test runner |
 | `@comitor/ui/shell` | Tier 3: `AppShell`, `Sidebar`, `AppHeader`, `WorkspaceSwitcher`, `AppLauncher`, `UserMenu`, `ThemeProvider`, `SonnerToaster` | `next`, `next-themes` |
 | `@comitor/ui/chart` | `Chart*` (shadcn) + `ComitorAreaChart/BarChart/LineChart` + `CHART_COLORS` | `recharts` (~100KB) |
 | `@comitor/ui/form` | Binding shadcn ⇄ react-hook-form: `Form`, `FormField`, `FormItem`, `FormControl`, `FormMessage`, `useFormField` | `react-hook-form` |
@@ -126,20 +141,25 @@ barrel chính re-export **một** file có `import` tới peer optional là mọ
 
 ### Tên xuất hiện ở nhiều entry
 
-Số tên mỗi entry xuất ra (đo bằng trình biên dịch TypeScript, không đếm tay): `.` **631** · `/shell` **70**
-· `/chart` **27** · `/form` **15** · `/tokens` **11**. Giao nhau đúng **4 nhóm** dưới đây — `export *`
-chỉ báo đỏ khi trùng tên trong **cùng một** entry, nên trùng xuyên entry phải tra bằng bảng này:
+Số tên mỗi entry xuất ra (đo bằng trình biên dịch TypeScript trên đúng 5 file entry, giải alias về khai
+báo gốc — không đếm tay): `.` **637** · `/shell` **70** · `/chart` **29** · `/form` **15** · `/tokens`
+**15**. Đúng **19 tên** xuất hiện ở nhiều hơn một entry, gom thành 4 nhóm dưới đây — `export *` chỉ báo
+đỏ khi trùng tên trong **cùng một** entry, nên trùng xuyên entry phải tra bằng bảng này:
 
 | Tên | Ở `@comitor/ui` | Ở entry khác | Cùng một cài đặt? |
 |---|---|---|---|
 | `FormField`, `FormFieldProps` | Tier 2 — bố cục 12 cột (label + control + mô tả + lỗi) | `/form` — wrapper của `Controller` (API shadcn) | **KHÔNG** — hai component khác hẳn nhau |
-| `useIsMac` | `composite/keyboard-hint.tsx` — `useState` + `useEffect`, đọc `navigator.userAgent` | `/shell` (`shell-context.tsx`) — `useSyncExternalStore`, đọc `navigator.platform` rồi mới tới `userAgent` | **KHÔNG** — hai thân hàm. Hợp đồng thì giống nhau: **render đầu luôn trả `false`** ở cả hai bản, nên không bản nào gây hydration mismatch |
+| `normalizeVi` | `composite/text-utils.ts` | `/shell` — **re-export đúng bản đó** | **CÓ** — một thân hàm duy nhất (`0.2.0` gộp; trước đó là hai khai báo riêng giống nhau chữ-cho-chữ) |
 | `getVietnameseInitials` | `composite/text-utils.ts` (`toLocaleUpperCase("vi-VN")`) | `/shell` — **re-export đúng bản đó** | **CÓ** — một thân hàm duy nhất |
-| 11 token: `gold`, `ash`, `accent`, `brandNeutral`, `semantic`, `status`, `chart`, `avatarPalette`, `layout`, `typography`, `ThemeMode` | `export * from "./tokens.js"` | `/tokens` — **cùng một module** | **CÓ** — `/tokens` là tập con của `.`, tách ra cho nơi chỉ cần hằng số (email HTML, PDF, canvas) |
+| 15 token: `gold`, `ash`, `accent`, `accentInk`, `accentForeground`, `brandNeutral`, `semantic`, `status`, `chart`, `layout`, `typography`, `ThemeMode`, `getAvatarToneColors`, `getAvatarToneIndex`, `AvatarToneColors` | `export * from "./tokens.js"` | `/tokens` — **cùng một module** | **CÓ** — `/tokens` là tập con của `.`, tách ra cho nơi chỉ cần hằng số (email HTML, PDF, canvas) |
 
 Quy tắc dùng: hằng ngày lấy bản ở `@comitor/ui`; chỉ với tới `/form` khi app đã dùng react-hook-form.
-Trong một app, hãy import `useIsMac` từ **một** entry duy nhất — trộn cả hai là hai đăng ký hook khác nhau
-cho cùng một thông tin.
+Chỉ `FormField` là thật sự hai component khác nhau, phải nhìn đúng entry.
+
+`0.2.0` đã dọn ba chỗ của `0.1.0`: **`useIsMac`** (từng có hai thân hàm khác nhau ở `.` và `/shell`)
+nay chỉ còn cửa `@comitor/ui`; **`avatarPalette`** (bảng màu avatar thứ hai) bị xoá; **`normalizeVi`**
+gộp về một binding. Còn đúng **`FormField`/`FormFieldProps`** là hai cài đặt khác nhau trong bảng trên
+— 16/18 tên còn lại đều trỏ vào cùng một binding. Xem [CHANGELOG.md](CHANGELOG.md).
 
 > **`Toaster` KHÔNG phải tên trùng.** Có hai toaster nhưng chúng mang hai tên: `Toaster` ở
 > `@comitor/ui` (toast có icon theo trạng thái, nhận prop `theme`) và **`SonnerToaster`** ở
@@ -281,6 +301,39 @@ import { ThemeProvider } from "@comitor/ui/shell";
 App **không chạy trên Next**: truyền `pathname` và `LinkComponent` cho `ShellProvider`/`AppShell`
 để khỏi chạm `next/navigation`.
 
+#### Mục menu phân biệt nhau bằng query — prop `searchParams`
+
+`usePathname()` của Next **không bao giờ** chứa `?query`. Vì vậy mục khai
+`href: "/cai-dat?tab=thanh-vien"` được so bằng phần ĐƯỜNG DẪN (`/cai-dat`) — nó sáng khi bạn đang
+ở `/cai-dat`, và nếu menu có nhiều tab cùng đường dẫn thì **tất cả cùng sáng**, vì shell không
+thấy query.
+
+Muốn đúng từng tab thì đưa query cho shell qua prop **optional** `searchParams`:
+
+```tsx
+"use client";
+import { useSearchParams } from "next/navigation";
+import { AppShell } from "@comitor/ui/shell";
+
+export function Shell({ children }: { children: React.ReactNode }) {
+  const searchParams = useSearchParams();   // nhớ có <Suspense> ở trên trang
+  return <AppShell nav={nav} searchParams={searchParams}>{children}</AppShell>;
+}
+```
+
+Nhận cả `URLSearchParams`, chuỗi `"?tab=x"`, lẫn object `searchParams` của Server Component.
+Luật khi đã có nó:
+
+- mục có query sáng khi query của nó là **tập con** của URL hiện tại (`?tab=a` vẫn sáng ở
+  `?tab=a&q=abc&trang=2`);
+- mục **không** query nhường cho mục cùng đường dẫn có query khớp — tab mặc định không sáng cùng
+  lúc với tab đang mở;
+- luật cũ "chỉ `startsWith` khi không có mục nào khớp chính xác" giữ nguyên.
+
+> Shell **không** tự gọi `useSearchParams()`: hook đó ép trang phải bọc `<Suspense>` và đẩy trang
+> sang render phía client khi build tĩnh. Cái giá đó phải do app chọn, không phải hệ quả của việc
+> import shell.
+
 > ⚠ Entry `/shell` chỉ nạp được **qua bundler** (webpack/turbopack/vite). Nạp bằng Node ESM thuần sẽ
 > lỗi `Cannot find module 'next/link'` — vì `next@16` không khai `exports` map nên Node không resolve
 > được subpath không đuôi. Test runner chạy resolution kiểu Node thì alias `next/link` → `next/link.js`,
@@ -290,17 +343,27 @@ App **không chạy trên Next**: truyền `pathname` và `LinkComponent` cho `S
 ### 4.3 Token ngoài Tailwind
 
 ```ts
-import { chart, gold, layout } from "@comitor/ui/tokens";
+import { chart, getAvatarToneColors, layout, semantic } from "@comitor/ui/tokens";
+
+const seriesColor = chart.light[0];      // #E8B824
+const headerPx = layout.headerHeight;    // 56
+const errorText = semantic.dark.destructiveInk;  // mực đỏ trên nền tối
 
-const seriesColor = chart.light[0]; // #E8B824
-const headerPx = layout.headerHeight; // 56
+// Avatar trong email HTML / canvas / PDF — cùng tone với avatar trên web
+const { background, foreground } = getAvatarToneColors("Nguyễn Đức Thành", "light");
+// { background: "#E0F2E9", foreground: "#216A48" }
 ```
 
+> Hai cửa cho **một** bảng màu avatar: `getAvatarToneClasses(name)` ở `@comitor/ui` (có Tailwind → trả
+> chuỗi class, đổi theo theme) và `getAvatarToneColors(name, mode)` ở `@comitor/ui/tokens` (không có
+> Tailwind → trả hex đục đã trộn sẵn tint). Cùng bảng tone, cùng hàm băm, nên một người ra một màu ở cả
+> hai nơi. **Đừng** tự băm tên rồi bốc màu từ `accent` — đó là đường ngắn nhất để web và email lệch màu.
+
 ## 5. Bảng component
 
-Số liệu thực tế của `0.1.0`: **51 file primitive · 24 file composite · 18 file shell · 2 file chart**
-(chưa kể barrel) — số tên xuất ra theo entry: `.` **631** · `/shell` **70** · `/chart` **27** · `/form`
-**15** · `/tokens` **11** (xem §3 cho các tên xuất hiện ở nhiều entry). Bảng dưới liệt kê component gốc;
+Số liệu thực tế của `0.2.1`: **51 file primitive · 24 file composite · 18 file shell · 2 file chart**
+(chưa kể barrel) — số tên xuất ra theo entry: `.` **637** · `/shell` **70** · `/chart` **29** · `/form`
+**15** · `/tokens` **15** (xem §3 cho các tên xuất hiện ở nhiều entry). Bảng dưới liệt kê component gốc;
 các thành phần con (`CardHeader`, `DialogFooter`, `SelectItem`…) export kèm theo file tương ứng.
 
 ### Tier 1 — primitive (`@comitor/ui`)
@@ -324,6 +387,35 @@ shadcn/ui style `new-york`, đã tùy biến token theo brand Comitor.
 > cookie riêng. App nào thật sự cần bản shadcn thì `npx shadcn@latest add sidebar` vào repo của mình.
 > Lý do đầy đủ: [docs/quyet-dinh-tich-hop.md](docs/quyet-dinh-tich-hop.md) §17.
 
+#### `CardHeader` có nút ở góc phải — prop `actions`
+
+`CardHeader` mặc định xếp DỌC (`flex-col space-y-1.5`). Thẻ có nút ở góc phải vì thế phải ghi đè
+đúng một chuỗi bốn lớp, ở mọi app, mọi thẻ:
+
+```tsx
+/* ✗ Cách cũ — chép tay, dễ sót `space-y-0` (thiếu nó thì nút bị đẩy lệch xuống) */
+<CardHeader className="flex-row items-start justify-between gap-3 space-y-0">
+  <div>
+    <CardTitle>Thông tin đơn vị</CardTitle>
+    <CardDescription>Cập nhật lần cuối hôm qua</CardDescription>
+  </div>
+  <Button size="sm" variant="ghost">Sửa</Button>
+</CardHeader>
+
+/* ✓ Từ 0.2.1 — `actions` gói đúng chuỗi đó lại */
+<CardHeader actions={<Button size="sm" variant="ghost">Sửa</Button>}>
+  <CardTitle>Thông tin đơn vị</CardTitle>
+  <CardDescription>Cập nhật lần cuối hôm qua</CardDescription>
+</CardHeader>
+```
+
+Không truyền `actions` thì lớp và cây DOM **y hệt `0.2.0`** — prop này chỉ thêm một nhánh, không
+đổi mặc định. Cụm nút nhận `actionsClassName` riêng khi cần đổi `gap`/cho xuống dòng.
+
+Quan hệ với `CardAction`: `CardAction` là ô `ml-auto` để tự lắp khi bạn **đã** tự đặt header thành
+hàng ngang; `actions` làm cả hai việc (đổi bố cục *và* đặt chỗ) nên là đường đi mặc định.
+`CardAction` giữ nguyên cho ai đã dùng.
+
 ### Tier 2 — composite (`@comitor/ui`)
 
 Giá trị thật của package: pattern lặp đi lặp lại ở mọi app, ghép từ nhiều primitive.
@@ -331,31 +423,37 @@ Giá trị thật của package: pattern lặp đi lặp lại ở mọi app, gh
 | Component | Công dụng |
 |---|---|
 | `PageHeader`, `PageContainer` | Khung đầu trang (breadcrumb + hành động) và khung nội dung chuẩn |
-| `DataTable`, `DataTableColumnToggle`, `TablePagination` | Bảng dữ liệu: sort, chọn dòng, ẩn/hiện cột, phân trang. Mọi chuỗi (kể cả `aria-label`) override được qua prop `labels` — xem `DataTableLabels` / `DEFAULT_DATA_TABLE_LABELS` |
-| `SearchFilterBar`, `FilterChips` | Thanh tìm + lọc + đếm kết quả |
+| `DataTable`, `DataTableColumnToggle` | Bảng dữ liệu: sort, chọn dòng, ẩn/hiện cột. Mọi chuỗi (kể cả `aria-label`) override được qua prop `labels` — xem `DataTableLabels` / `DEFAULT_DATA_TABLE_LABELS` |
+| `TablePagination` | Phân trang đi kèm bảng. Chuỗi override qua prop `labels` — `TablePaginationLabels` / `DEFAULT_TABLE_PAGINATION_LABELS` (khoá có số/đơn vị chèn vào là **hàm**, vd `range(start, end, total, unitLabel)`) |
+| `SearchFilterBar`, `FilterChips` | Thanh tìm + lọc + đếm kết quả. `SearchFilterBar` override chuỗi qua `labels` — `SearchFilterBarLabels` / `DEFAULT_SEARCH_FILTER_BAR_LABELS`; `FilterChips` nhận nhãn thẳng trong dữ liệu chip nên không có `labels` |
 | `StatCard`, `StatusPill`, `EmptyState` | Số liệu có delta, nhãn trạng thái, trạng thái rỗng |
 | `FormSection`, `FormField` | Bố cục form 12 cột; uỷ quyền label/mô tả/lỗi xuống `Field` |
-| `Combobox`, `MultiCombobox` | Chọn có tìm kiếm, **khớp không dấu tiếng Việt** |
+| `Combobox`, `MultiCombobox` | Chọn có tìm kiếm, **khớp không dấu tiếng Việt**. `aria-invalid` đổi trigger sang **viền đỏ** (`--destructive-ink`), cùng tín hiệu với `Input`; nhận cả `boolean` lẫn `"true"`/`"false"` để dùng thẳng `aria-invalid={!!errors.x}` |
 | `DatePicker`, `DateRangePicker` | Chọn ngày/khoảng ngày, locale `vi`, preset dựng sẵn |
-| `LetterAvatar`, `AvatarGroup` | Avatar chữ cái theo tên tiếng Việt (tông màu deterministic), nhóm người tham gia |
+| `LetterAvatar`, `AvatarGroup` | Avatar chữ cái theo tên tiếng Việt (tông màu deterministic), nhóm người tham gia. Lấy tone bằng `getAvatarToneClasses(name)`; bản hex cho canvas/email/PDF là `getAvatarToneColors(name, mode)` ở `/tokens` — **cùng một bảng tone**, cùng một hàm băm |
 | `ConfirmDialog`, `CommandPalette` | Hộp xác nhận, bảng lệnh `⌘K` |
 | `Toaster`, `toast()`, `toastPromise()`, `dismissToast()` | Thông báo có icon theo trạng thái |
 | `CopyButton`, `RelativeTime`, `InlineEdit`, `KeyboardHint` | Tiện ích nhỏ dùng khắp nơi |
-| `useIsMac` | Hook đi kèm `KeyboardHint` — `true` khi chạy trên macOS (render đầu luôn `false`, xem §3) |
+| `useIsMac` | Hook đi kèm `KeyboardHint` — `true` khi chạy trên macOS (render đầu luôn `false`, xem §3). **Cửa xuất duy nhất của cả gói**; `/shell` không re-export |
 
 Kèm 2 module thuần (không phải component, dùng được cả hai phía):
 
 | Module | Export |
 |---|---|
 | `status-config` | `STATUS_TONES`, `getStatusConfig`, `getStatusClasses`, `getStatusLabel`, `sortByStatusPriority` |
-| `text-utils` | `removeVietnameseTones`, `matchesSearch`, `getVietnameseInitials`, `hashString`, `pickByString`, `truncate` |
+| `text-utils` | `removeVietnameseTones`, `normalizeVi`, `matchesSearch`, `getVietnameseInitials`, `truncate` |
+
+> `text-utils` **không còn** `hashString` / `pickByString` (0.1.0 có). Hàm băm là chuyện nội bộ của phép
+> chọn tone avatar; xuất nó ra ngoài chỉ mời app dựng lại phép chọn của riêng mình — đúng thứ làm cùng
+> một người hiện hai màu ở web và email. Cần màu avatar thì dùng `getAvatarToneClasses` /
+> `getAvatarToneColors`; cần một màu tuỳ ý thì truyền `toneClassName` cho `LetterAvatar`.
 
 ### Tier 3 — shell (`@comitor/ui/shell`)
 
 | Component | Công dụng |
 |---|---|
 | `AppShell` | Lắp sẵn `ShellProvider` + `Sidebar` + `AppHeader` + `<main>` + `MobileMenu`; hai layout `sidebar-first` / `header-first` |
-| `ShellProvider`, `useShell`, `useIsMac` | Context + phím tắt toàn cục; dùng khi tự lắp khung |
+| `ShellProvider`, `useShell` | Context + phím tắt toàn cục; dùng khi tự lắp khung. (`useIsMac` **không** ở entry này — nhập từ `@comitor/ui`) |
 | `WorkspaceSwitcher` | **Trục 1** — đổi ngữ cảnh dữ liệu; dùng `Popover` (không `DropdownMenu`, vì typeahead của Radix cướp phím ô tìm kiếm) |
 | `AppLauncher`, `AppLauncherPanel` | **Trục 2** — lưới 3×3 đổi sản phẩm; app chưa mua hiện khoá và gọi `onUpsell` |
 | `AppHeader`, `Sidebar`, `SidebarGroup`, `SidebarMenuItem`, `MobileMenu` | Thành phần khung điều hướng |
@@ -363,7 +461,7 @@ Kèm 2 module thuần (không phải component, dùng được cả hai phía):
 | `ThemeProvider`, `ThemeToggle`, `SonnerToaster` | Theme (next-themes) + toast bám theme |
 | `ShellNavLink` | Link nội bộ của shell; thay `next/link` bằng `LinkComponent` khi không chạy Next |
 | `ComitorLogo`, `ComitorLockup` | Vector brand — **không** có `"use client"`, RSC render thẳng (hex trong SVG là brand book, không tokenize) |
-| `DEFAULT_SHELL_LABELS` + `utils` | Chuỗi hiển thị mặc định; helper `flattenNavItems`, `isNavItemActive`, `resolveCurrentApp`, `getEntitledApps`, `normalizeVi`… |
+| `DEFAULT_SHELL_LABELS` + `utils` | Chuỗi hiển thị mặc định (`ShellLabels`, 32 khoá); helper `flattenNavItems`, `isNavItemActive`, `isNavBranchActive`, `toNavGroups`, `resolveCurrentApp`, `getEntitledApps`, `getLockedApps`, `appAccentStyle`, `normalizeVi`, `getVietnameseInitials` |
 
 Hợp đồng dữ liệu (type): `Workspace`, `AppDescriptor`, `NavItem`, `NavGroup`, `ShellNav`, `ShellUser`,
 `UserMenuItem`, `ShellLabels`, `ShellIcon`, `ShellLinkComponent`.
@@ -382,29 +480,163 @@ Hợp đồng dữ liệu (type): `Workspace`, `AppDescriptor`, `NavItem`, `NavG
 `Form`, `FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormDescription`, `FormMessage`, `useFormField`
 — binding shadcn ⇄ react-hook-form. ⚠ `FormField` ở đây **khác** `FormField` của Tier 2 (§3).
 
-## 6. Token
+### Cơ chế `labels` — đổi ngôn ngữ mà không fork component
+
+Chuỗi hiển thị mặc định của gói là **tiếng Việt**, kể cả chuỗi chỉ trình đọc màn hình nghe thấy
+(`aria-label`, `sr-only`). App dùng ngôn ngữ khác override qua prop `labels` — không phải fork
+component, không phải bọc lại.
+
+| Component | Type | Hằng mặc định |
+|---|---|---|
+| `DataTable`, `DataTableColumnToggle` | `DataTableLabels` | `DEFAULT_DATA_TABLE_LABELS` |
+| `TablePagination` | `TablePaginationLabels` | `DEFAULT_TABLE_PAGINATION_LABELS` |
+| `SearchFilterBar` | `SearchFilterBarLabels` | `DEFAULT_SEARCH_FILTER_BAR_LABELS` |
+| Toàn bộ Tier 3 (`AppShell`/`ShellProvider` truyền xuống) | `ShellLabels` (32 khoá) | `DEFAULT_SHELL_LABELS` |
+| `ThemeToggle` (dùng độc lập, ngoài shell) | `ThemeToggleLabels` = 4 khoá theme của `ShellLabels` | `DEFAULT_SHELL_LABELS` |
+
+Ba quy tắc chung cho mọi bộ nhãn:
+
+1. **`Partial<>` — override từng khoá.** Component luôn trải `{ ...DEFAULT_*, ...labels }`, nên truyền
+   một khoá không làm mất phần còn lại.
+2. **Khoá có số/đơn vị chèn vào là HÀM, không phải chuỗi có placeholder.** Nối chuỗi bằng dấu cộng ở
+   phía app là cách chắc chắn sai trật tự từ với ngôn ngữ khác:
+   `range(start, end, total, unitLabel)`, `pageStatus(page, pageCount)`, `filterCount(count)`,
+   `pageSizeSelect(unitLabel)`. `resultSummary` còn trả `ReactNode` vì con số cần thẻ riêng
+   (`tabular-nums` để số không nhảy cột).
+3. **Prop rời thắng `labels`.** `unitLabel`, `label`, `searchPlaceholder` vẫn là prop riêng và vẫn ghi
+   đè giá trị trong `labels`: chúng là chuỗi theo **nội dung** của từng bảng ("việc", "liên hệ"), còn
+   `labels` là chuỗi theo **ngôn ngữ** ("mục" / "items").
+
+```tsx
+const EN_PAGINATION: Partial<TablePaginationLabels> = {
+  region: "Pagination",
+  unitLabel: "items",
+  pageSizePrefix: "Show",
+  range: (start, end, total, unit) => `${start}–${end} of ${total} ${unit}`,
+  pageStatus: (page, count) => `Page ${page} of ${count}`,
+  firstPage: "First page",
+  previousPage: "Previous page",
+  nextPage: "Next page",
+  lastPage: "Last page"
+};
+
+<TablePagination {...paging} labels={EN_PAGINATION} unitLabel="contacts" />
+```
+
+`FilterChips` **không** có `labels` — nhãn của nó nằm thẳng trong dữ liệu chip, không có chuỗi nào chôn
+trong component.
+
+## 6. Màu và token
 
 Toàn bộ token nằm ở [`styles.css`](./styles.css); bản mirror TS ở [`src/tokens.ts`](./src/tokens.ts).
 
+### 6.1 Hợp đồng BA VAI TRÒ của màu — đọc trước khi dùng bất kỳ màu nào
+
+Đây là quy tắc quan trọng nhất của gói. Mỗi màu có **ba** biến thể, đọc tên là biết dùng ở đâu:
+
+| Tên | Vai trò | Đo tương phản với | Ví dụ dùng |
+|---|---|---|---|
+| `--x` | tô **NỀN** — fill đặc hoặc tint `/10`–`/25` | — | `bg-teal`, `bg-teal/15` |
+| `--x-foreground` | chữ/icon **NẰM TRÊN** nền `--x` đặc | `--x` | `bg-destructive text-destructive-foreground` |
+| `--x-ink` | **chính màu đó** khi đi lên nền TRANG: chữ, icon rời, viền, vạch active | `--background` / `--card` / `--muted`, hoặc tint của chính nó | `text-teal-ink`, `border-red-ink` |
+
+**Vì sao phải có bậc `-ink` riêng thay vì dùng thẳng `--teal` / `--green` / `--red`**: bản light của màu
+phụ được chọn để tô **nền** nên quá nhạt cho vai trò chữ. Đo trên tint 15% của chính nó — nền thật mà
+chữ initials avatar và badge tonal đứng lên:
+
+```
+teal   #1F8A8B trên #DDEDEE = 3,44:1 ✗   →  --teal-ink  #1A6668 = 5,54:1 ✓
+green  #2EA56A trên #E0F2E9 = 2,69:1 ✗   →  --green-ink #216A48 = 5,60:1 ✓
+red    #D64545 trên #F9E3E3 = 3,57:1 ✗   →  --red-ink   #9A3537 = 5,83:1 ✓
+```
+
+Ở **dark** không có bậc riêng: khối `.dark` vốn đã nâng `--teal/--green/--red/--yellow` lên mức làm chữ
+được, nên bên đó `--x-ink` chỉ trỏ về `var(--x)`. Nhờ vậy `text-teal-ink` viết **một lần** là đúng cả
+hai theme, không cần biến thể `dark:`.
+
+Ba vai trò áp cho mọi họ token:
+
+| Họ | Nền | Chữ trên nền đó | Trên nền trang |
+|---|---|---|---|
+| Màu phụ | `--teal` `--green` `--red` `--yellow` `--navy` | — (dùng `--ink`/`--paper` tuỳ nền) | `--teal-ink` `--green-ink` `--red-ink` `--yellow-ink` `--navy-ink` |
+| Trạng thái | `--success` `--warning` `--info` `--destructive` | `--success-foreground` … `--destructive-foreground` | `--success-ink` `--warning-ink` `--info-ink` `--destructive-ink` |
+| Brand | `--primary` | `--primary-foreground` | `--primary-ink` |
+| Accent theo app | `--app-accent` | `--app-accent-foreground` | `--app-accent-ink` (mặc định `= --primary-ink`) |
+
+Brand cũng cần bậc `-ink` vì đúng lý do trên: gold `#E8B824` là màu **sáng** nên tô nền thì tuyệt, còn
+làm ranh giới trạng thái trên nền trang chỉ được **1,86:1** ✗. `--primary-ink` mượn `--gold-500`
+`#7A5800` ở light (**6,51:1** ✓) và trỏ về chính `--primary` ở dark (**12,67:1** ✓). Đây là màu của
+rãnh `Switch` khi BẬT và ô `Checkbox` đã chọn. `--ring` **cố ý vẫn là** `--primary`: vòng focus thuộc
+tiêu chí AAA của WCAG 2.2, ngoài mục tiêu AA của gói.
+
+Ba lỗi hay gặp nhất, và cách sửa:
+
+| Viết sai | Hỏng ở đâu | Viết đúng |
+|---|---|---|
+| `text-red` cho dòng báo lỗi | 4,38:1 ở light ✗; ở dark thì đây là thang brand thô | `text-destructive-ink` |
+| `text-success` / `text-info` / `text-warning` cho chữ hoặc icon trạng thái | Token TÔ NỀN: trên tint `/15` của chính nó chỉ 2,69:1 / 3,44:1 ✗ ở light; trên nền trang 3,13:1 / 4,14:1 ✗ | `text-success-ink` / `text-info-ink` / `text-warning-ink` (5,5–6,7:1 light · 7,1–12,4:1 dark) |
+| `bg-primary` làm rãnh `Switch` khi BẬT / ô `Checkbox` đã chọn | 1,86:1 với nền trắng ✗ — trạng thái BẬT chỉ còn phân biệt bằng vị trí núm | `bg-primary-ink` (6,51:1 light / 12,67:1 dark) |
+| `border-border` làm viền của control | `--border` là ranh giới **TRANG TRÍ**, 1,16:1 ✗ | `border-input` (= `--control-edge`, 3,83:1 / 4,94:1) |
+| `text-app-accent` cho icon/vạch active | accent mặc định là gold `#E8B824` → 1,7–1,9:1 trên nền sidebar ✗ | `text-app-accent-ink`, hoặc nền ĐẶC + `text-app-accent-foreground` |
+| `text-destructive` cho chữ trên nền trang | `--destructive` là màu **NỀN** (ghim một giá trị đậm cho chữ trắng đứng lên); dùng làm chữ ở dark chỉ 3,76:1 ✗ | `text-destructive-ink` (7,15:1 light / 6,42:1 dark) |
+
+> ⚠ **App ghi đè `--app-accent` thì PHẢI set kèm `--app-accent-ink`** (và `--app-accent-foreground` nếu
+> accent sáng). Gói cố ý **không** dẫn xuất `-ink` bằng `color-mix` từ `--app-accent`: dẫn xuất tự động
+> cho ra con số tương phản không ai kiểm, và mỗi màu nền cần một hệ số khác nhau.
+>
+> ⚠ **Ghi đè `--primary` cũng PHẢI set kèm `--primary-ink`** — cùng một luật, cùng một lý do. Quên thì
+> công tắc/checkbox vẫn đọc được nhưng còn màu gold mặc định: sai màu, không sai chuẩn.
+>
+> ⚠ **Đổi `--teal` / `--green` / `--red` thì phải tính lại bậc `-ink` tương ứng** — chúng là hex đã đóng
+> băng, không tự đi theo. Đóng băng là chủ ý: một chỗ duy nhất để đo lại, component không phải nhắc lại
+> chuỗi `color-mix(…)` (dễ chép lệch % giữa `Badge`/`LetterAvatar`/`Input`), và `tokens.ts` mirror được
+> ra hex thật cho canvas/email/PDF.
+
+Bản mirror TS đi theo đúng hợp đồng này: `accent` (nền) ⇄ `accentInk` (mực), `status.light.success` ⇄
+`status.light.successInk`, `semantic.light.destructive` ⇄ `semantic.light.destructiveInk`.
+
+### 6.2 Bảng token
+
 | Nhóm | Token | Ghi chú |
 |---|---|---|
-| Brand | `gold-50 … gold-600` | `gold-300 #E8B824` = `--primary` (light); dark nâng lên `gold-200 #F5D060` |
+| Brand | `gold-50 … gold-600` | `gold-300 #E8B824` = `--primary` (light); dark nâng lên `gold-200 #F5D060`. `--primary-ink` = `gold-500 #7A5800` (light) / `= --primary` (dark) — bậc gold cho vai trò **trên nền trang**, xem §6.1 |
 | Trung tính brand | `ink`, `ink-soft`, `paper`, `warm` | `warm #EDE8D8` = `--secondary` (light) |
 | Thang xám | `ash-50/100/300/500/700/900` | **Không phải `gray-*`** — xem cạm bẫy bên dưới |
-| Màu phụ | `navy`, `teal`, `red`, `green`, `yellow` | `red #D64545` = `--destructive` |
-| Trạng thái | `success`, `warning`, `info` (+ `-foreground`) | Alias sang `green` / `yellow` / `teal`, tự sáng lên ở dark |
-| Biểu đồ | `chart-1 … chart-5` | Đổi bảng màu biểu đồ độc lập với brand |
-| Theo app | `app-accent`, `app-accent-foreground` | Mỗi app Comitor tô một accent riêng — set ở `<body>`, không cần build lại package |
+| Màu phụ (NỀN) | `navy`, `teal`, `red`, `green`, `yellow` | Vai trò **tô nền** (fill đặc hoặc tint). Bản dark đã được nâng sáng. ⚠ `red #D64545` **khác** `--destructive` `#C93B3B` — cái sau là nền nút xoá, ghim một giá trị cho cả hai theme để chữ trắng đạt 5,03:1 |
+| Mực của màu phụ | `teal-ink`, `green-ink`, `red-ink`, `yellow-ink`, `navy-ink` | Cùng màu đó ở vai trò **chữ/icon/viền trên nền trang** — xem §6.1. Ở light là hex đã đóng băng (`#1A6668` / `#216A48` / `#9A3537` / `= gold-500` / `= navy`); ở dark trỏ về chính màu phụ |
+| Trạng thái | `success`, `warning`, `info`, `destructive` (+ `-foreground`, + `-ink`) | Ba cái đầu alias sang `green` / `yellow` / `teal` và tự sáng lên ở dark; `destructive` ghim một giá trị cho cả hai theme. `-ink` là bậc để làm **chữ** trạng thái (`text-destructive-ink` cho dòng lỗi) |
+| Ranh giới control | `control-edge` `#7E8290` | Token dành riêng cho **ranh giới của control** (rãnh `Switch` khi tắt, viền ô nhập/checkbox chưa chọn) — WCAG 1.4.11 đòi ≥3:1 cho thành phần phi văn bản. Ghim một giá trị cho cả hai theme: 3,83:1 với nền trắng, 4,94:1 với nền dark. **`--input` trỏ vào đúng token này**; `--border` thì KHÔNG — nó là ranh giới trang trí (1,16:1, cố ý) |
+| Biểu đồ | `chart-1 … chart-5` | Đổi bảng màu biểu đồ độc lập với brand. `chart-3` trỏ vào `--navy-ink` (nét biểu đồ phải NỔI trên nền trang) |
+| Avatar | `getAvatarToneColors(name, mode)`, `getAvatarToneIndex(name)`, type `AvatarToneColors` | Trả `{ background, foreground }` dạng **hex đục** cho canvas/email/PDF — đã trộn sẵn tint với nền `--card` vì ngoài CSS không có gì để hợp thành. Cùng bảng tone, cùng hàm băm với `getAvatarToneClasses(name)` ở `@comitor/ui`, nên một người luôn ra một màu ở mọi nơi. Khoá băm là **tên hiển thị**, không phải email/slug |
+| Theo app | `app-accent`, `app-accent-foreground`, `app-accent-ink` | Mỗi app Comitor tô một accent riêng — khai ở CSS của app (có nhánh `.dark`), không cần build lại package. Ghi đè `--app-accent` thì **phải** set kèm `--app-accent-ink` (§6.1) |
 | Khung | `--sidebar-width`, `--sidebar-width-icon`, `--header-height` | Có utility `w-sidebar`, `w-sidebar-icon`, `h-header` |
 | Đổ bóng | `--elevation-surface`, `--elevation-control`, `--elevation-card`, `--elevation-overlay` | 4 bậc độ cao, sinh utility `shadow-surface` / `shadow-control` / `shadow-card` / `shadow-overlay`. Đổi theo theme (bản dark dùng đen thuần, alpha cao hơn) |
 | Khác | `--radius 0.375rem` | Bo góc 6px là chữ ký thị giác |
 
-Đổi accent theo app:
+Đổi accent theo app — khai bằng **CSS, có nhánh dark**, không phải inline style trên `<body>`:
 
-```tsx
-<body style={{ "--app-accent": "#1F8A8B", "--app-accent-foreground": "#FFFFFF" } as React.CSSProperties}>
+```css
+/* app/globals.css — sau @import "@comitor/ui/styles.css" */
+:root {
+  --app-accent: #1f8a8b;            /* NỀN đặc                                        */
+  --app-accent-foreground: #0e1116; /* chữ trên nền đó         → 4,56:1 ✓             */
+  --app-accent-ink: #1a6668;        /* màu app trên nền trang  → 6,68:1 trên trắng ✓  */
+}
+.dark {
+  --app-accent: #2dd4bf;
+  --app-accent-foreground: #0e1116; /* 10,16:1 ✓                                      */
+  --app-accent-ink: #2dd4bf;        /* 10,16:1 trên --background ✓                    */
+}
 ```
 
+Ba biến, không phải hai: bỏ `--app-accent-ink` thì icon/vạch active của app rơi về gold mặc định.
+Và phải khai ở CSS chứ không phải inline style vì **một giá trị inline không có nhánh `dark`** — accent
+sáng vừa đủ cho light mode thường quá tối trên nền `#0E1116`.
+
+> Trong `AppLauncher`, mỗi app còn tự tô ô icon của mình qua `AppDescriptor.accent` /
+> `accentForeground` (inline style, đúng vai trò nền + chữ-trên-nền). Ô icon dùng **nền đặc**, nên hai
+> biến đó là đủ; `--app-accent-ink` là chuyện của cả trang.
+
 Đổi độ nổi (bóng) toàn hệ — ghi đè đúng 4 biến `--elevation-*`, **không** ghi đè `--shadow-*`:
 
 ```css
@@ -415,16 +647,19 @@ Toàn bộ token nằm ở [`styles.css`](./styles.css); bản mirror TS ở [`s
 > Vì `--shadow-*` giữ giá trị dạng `var()`, Tailwind không tách được phần màu: `shadow-card/50` và
 > `shadow-<màu>` **không** có tác dụng. Đổi tông/độ đậm thì ghi đè `--elevation-*` như trên.
 
-### Cạm bẫy phải nhớ
+### 6.3 Cạm bẫy phải nhớ
 
-1. **`ash-*` chứ không phải `gray-*`.** Thang xám Comitor chỉ có 6 bậc; nếu đặt tên `gray-*` thì
+1. **Nền hay mực? Chọn sai vai trò là hỏng tương phản, không phải hỏng thẩm mỹ.** `--x` tô nền,
+   `--x-ink` làm chữ/icon/viền trên nền trang (§6.1). Utility `text-teal` / `text-app-accent` **vẫn được
+   Tailwind sinh ra** — nó sinh cả bộ cho mọi `--color-*` — nên trình biên dịch sẽ không nhắc gì cả.
+2. **`ash-*` chứ không phải `gray-*`.** Thang xám Comitor chỉ có 6 bậc; nếu đặt tên `gray-*` thì
    `gray-200/400/600/800` rơi về gray mặc định của Tailwind (ám xanh) và trộn với gray Comitor
    (ám tím) → lệch tông. Đổi namespace để hai thang không đụng nhau.
-2. **Không sinh class động** (`` `bg-${color}-300` ``) ở bất kỳ đâu — Tailwind quét tĩnh, class động
+3. **Không sinh class động** (`` `bg-${color}-300` ``) ở bất kỳ đâu — Tailwind quét tĩnh, class động
    bị loại khỏi bundle của app.
-3. **Không hardcode hex trong component** — trừ vector logo brand. Đọc hex từ `/tokens` rồi nhét vào
+4. **Không hardcode hex trong component** — trừ vector logo brand. Đọc hex từ `/tokens` rồi nhét vào
    style inline là mất dark mode.
-4. `@theme **inline**` là chủ ý: `inline` nhúng thẳng `var(--x)` vào utility nên `.dark { --primary }`
+5. `@theme **inline**` là chủ ý: `inline` nhúng thẳng `var(--x)` vào utility nên `.dark { --primary }`
    đổi được màu tại runtime. Dùng `@theme` thường sẽ đóng băng giá trị lúc build → dark mode chết.
 
 ## 7. Phát triển
@@ -435,10 +670,18 @@ pnpm build        # tsup: ESM, bundle:false (transpile từng file để giữ "
 pnpm typecheck    # tsc --noEmit
 pnpm lint         # biome check .
 pnpm lint:fix
+pnpm lint:a11y           # hợp đồng màu: vai trò token + tương phản WCAG ở CẢ hai theme
+pnpm test:cong-a11y      # tự kiểm chính cổng trên: 56 khẳng định, cổng còn bắt đủ không
+pnpm test:nav-active     # active matching của sidebar (hàm thuần) — 34 ca
 pnpm verify:directives   # mọi file nguồn có "use client" ⇄ file dist tương ứng
 pnpm check:exports       # publint --strict + attw
 ```
 
+`pnpm test:nav-active` chạy `scripts/kiem-nav-active.mjs`: Node trần bóc kiểu ngay trên
+`src/shell/utils.ts`, không test runner, không dependency mới. Nó khoá lại đúng lỗi mà
+comitor-starter báo về ở `0.2.0` — mục menu có `?query` trong `href` không bao giờ sáng — cùng
+toàn bộ hành vi active matching cũ, để lần sửa sau không đổi ngầm luật nào.
+
 > Gặp `ERR_PNPM_IGNORED_BUILDS: esbuild` khi cài? Đã xử lý sẵn trong `pnpm-workspace.yaml`
 > (`allowBuilds: { esbuild: true }`) — pnpm 11 không còn đọc setting từ trường `pnpm` của
 > `package.json` nữa. esbuild cần chạy postinstall để nạp binary theo nền tảng, cấm chạy thì
@@ -450,9 +693,26 @@ File thuần dữ liệu (`lib/cn.ts`, `tokens.ts`, `shell/types.ts`) **không**
 
 `scripts/verify-directives.mjs` đi bộ **toàn bộ `src/`** (không riêng `shell/`): file nguồn nào mở đầu
 bằng `"use client"` thì file `dist/` tương ứng phải mở đầu y hệt — thiếu file build cũng tính là hỏng.
-Hiện **70/101** file nguồn cần directive, trải khắp cả composite lẫn primitive. Đừng thay script bằng
+Hiện **70/102** file nguồn cần directive, trải khắp cả composite lẫn primitive (`pnpm verify:directives`
+in ra đúng con số này — đừng chép số từ đây mà không chạy lại). Đừng thay script bằng
 `grep -L "use client" dist/shell/*.js`: lệnh đó soi chưa tới một phần ba số file phải soi.
 
+### Cổng hợp đồng màu — `pnpm lint:a11y`
+
+`scripts/check-contrast.mjs` quét **toàn bộ** `src/**/*.{ts,tsx}` theo QUY TẮC (không theo danh sách
+phát hiện) và đối chiếu với `styles.css`: token TÔ NỀN đem làm màu chữ/icon/viền là sai *vai trò*, và
+mọi cặp chữ/nền phải đạt 4,5:1 (chữ) hoặc 3:1 (thành phần phi văn bản) ở **cả** light lẫn dark. Mọi loại
+phát hiện đều `exit 1` — kể cả lớp dùng bảng màu mặc định của Tailwind và miễn trừ đã thừa. Miễn trừ ghi
+ở `scripts/contrast-exemptions.json`, mỗi mục bắt buộc kèm lý do bằng chữ. Hợp đồng đầy đủ + giới hạn đã
+biết: [docs/hop-dong-mau.md](docs/hop-dong-mau.md).
+
+App tiêu thụ chạy được cùng cổng này trên bảng token đã ghi đè của mình: lấy script từ repo rồi trỏ
+`COMITOR_UI_STYLES` / `COMITOR_UI_SRC` sang file của app (script **không** nằm trong tarball npm).
+
+Trước khi phát hành: bump `version`, ghi mục mới trong [CHANGELOG.md](CHANGELOG.md), rồi chạy lại **cả
+khối lệnh ở đầu mục này** (`lint` và `lint:fix` là hai dạng của cùng một bước) — quy trình đầy đủ ở
+[CLAUDE.md](CLAUDE.md) §Publish.
+
 ## 8. Giấy phép
 
 [MIT](./LICENSE) © Comitor

package/dist/chart/chart.d.ts

@@ -60,7 +60,35 @@ type ChartStyleProps = {
 declare const ChartStyle: ({ id, config }: ChartStyleProps) => React.JSX.Element | null;
 /** `Tooltip` của recharts — đặt `content={<ChartTooltipContent />}` để có giao diện theo token. */
 declare const ChartTooltip: typeof RechartsPrimitive.Tooltip;
+/**
+ * Một phần tử `payload` do recharts bơm vào `content` của Tooltip/Legend.
+ *
+ * ─ VÌ SAO KHAI TẠI ĐÂY, KHÔNG DẪN XUẤT TỪ `TooltipProps`/`LegendProps` ─
+ * recharts **3** đã bỏ `payload` (và `label`) khỏi props của `<Tooltip>`/`<Legend>` — hai
+ * trường đó nay đi qua context nội bộ, nên `ComponentProps<typeof Tooltip>["payload"]` và
+ * `Pick<LegendProps, "payload">` **không còn tồn tại** ở 3.x. Dẫn xuất từ chúng khiến chính
+ * file `.d.ts` phát hành ra npm hỏng kiểu ngay khi app cài recharts 3 (app nào tắt
+ * `skipLibCheck` là thấy liền), tức peer `>=2.15.0` sẽ là một lời hứa suông.
+ *
+ * Hình dạng dưới đây là phần GIAO của 2.x và 3.x, và chỉ gồm đúng những trường component
+ * này thật sự đọc. Ở 2.x nó **giao** với kiểu gốc của recharts (props Tooltip vẫn còn
+ * `payload`) nên không nới lỏng gì; ở 3.x nó là nguồn duy nhất.
+ */
+interface ChartPayloadItem {
+    value?: number;
+    name?: string;
+    dataKey?: string | number;
+    color?: string;
+    /** Bản ghi gốc của điểm dữ liệu — nơi `fill` và các cột khác của hàng nằm. */
+    payload?: Record<string, unknown> & {
+        fill?: string;
+    };
+}
 type ChartTooltipContentProps = React.ComponentProps<typeof RechartsPrimitive.Tooltip> & React.ComponentProps<"div"> & {
+    /** Do recharts bơm vào — đừng truyền tay. */
+    payload?: ChartPayloadItem[];
+    /** Do recharts bơm vào — đừng truyền tay. */
+    label?: React.ReactNode;
     /** Ẩn dòng nhãn (trục X) ở đầu tooltip. */
     hideLabel?: boolean;
     /** Ẩn ô màu đứng trước tên series. */
@@ -75,8 +103,12 @@ type ChartTooltipContentProps = React.ComponentProps<typeof RechartsPrimitive.To
 /** Nội dung tooltip theo design token Comitor: nền `bg-background`, viền `border-border/50`. */
 declare function ChartTooltipContent({ active, payload, className, indicator, hideLabel, hideIndicator, label, labelFormatter, labelClassName, formatter, color, nameKey, labelKey }: ChartTooltipContentProps): React.JSX.Element | null;
 /** `Legend` của recharts — đặt `content={<ChartLegendContent />}` để lấy nhãn từ `config`. */
-declare const ChartLegend: typeof RechartsPrimitive.Legend;
-type ChartLegendContentProps = React.ComponentProps<"div"> & Pick<RechartsPrimitive.LegendProps, "payload" | "verticalAlign"> & {
+declare const ChartLegend: React.MemoExoticComponent<(outsideProps: RechartsPrimitive.LegendProps) => React.ReactPortal | null>;
+type ChartLegendContentProps = React.ComponentProps<"div"> & {
+    /** Do recharts bơm vào — đừng truyền tay. Xem `ChartPayloadItem` về lý do không dẫn xuất từ `LegendProps`. */
+    payload?: ChartPayloadItem[];
+    /** Do recharts bơm vào — quyết định chú giải đệm trên hay đệm dưới. */
+    verticalAlign?: "top" | "middle" | "bottom";
     /** Ẩn icon riêng của series (nếu `config` có khai `icon`). */
     hideIcon?: boolean;
     /** Khoá dùng để tra `config` (mặc định `dataKey`). */
@@ -85,4 +117,4 @@ type ChartLegendContentProps = React.ComponentProps<"div"> & Pick<RechartsPrimit
 /** Chú giải nằm ngang, nhãn lấy từ `config` chứ không phải `dataKey` thô. */
 declare function ChartLegendContent({ className, hideIcon, payload, verticalAlign, nameKey }: ChartLegendContentProps): React.JSX.Element | null;
 
-export { type ChartConfig, ChartContainer, type ChartContainerProps, ChartLegend, ChartLegendContent, type ChartLegendContentProps, ChartStyle, type ChartStyleProps, ChartTooltip, ChartTooltipContent, type ChartTooltipContentProps, useChart };
+export { type ChartConfig, ChartContainer, type ChartContainerProps, ChartLegend, ChartLegendContent, type ChartLegendContentProps, type ChartPayloadItem, ChartStyle, type ChartStyleProps, ChartTooltip, ChartTooltipContent, type ChartTooltipContentProps, useChart };