@comitor/ui 0.2.1 → 0.3.0

package/README.md

@@ -53,6 +53,11 @@ pnpm add react-hook-form    # cho @comitor/ui/form
 >
 > `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`.
+>
+> **Hiệu ứng vẽ dần của recharts 2.15.x hỏng với React 19.2**, nên `ComitorAreaChart` /
+> `ComitorBarChart` / `ComitorLineChart` mặc định **tắt** hiệu ứng từ `0.2.2` (§4.4). Nếu tự lắp
+> recharts trong `<ChartContainer>` thì gói không tắt hộ được — app phải tự ghi
+> `isAnimationActive={false}` lên từng `<Bar>`/`<Line>`/`<Area>` (§4.4 mục 1b).
 
 ## 2. Nạp `styles.css` — ĐỌC KỸ, đây là chỗ dễ sai nhất
 
@@ -334,11 +339,13 @@ Luật khi đã có nó:
 > 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`,
-> hoặc dùng `ShellProvider` với `LinkComponent`/`pathname` tự cấp. Các entry `.`, `/chart`, `/form`,
-> `/tokens` **không** dính vấn đề này.
+> **Từ `0.2.2`, cả 5 entry — kể cả `/shell` — nạp được bằng Node ESM thuần.** Ở `0.2.1` thì không:
+> `next@16` không khai `exports` map, nên với Node thì `next/link` chỉ là một đường dẫn file thiếu
+> đuôi và `import("@comitor/ui/shell")` chết ngay lúc nạp
+> (`ERR_MODULE_NOT_FOUND … Did you mean next/link.js?`), trong khi app Next không hề hấn vì bundler
+> tự thêm đuôi. Nay shell ghi thẳng `next/link.js` / `next/navigation.js` — **cùng một file** mà
+> bundler vẫn resolve tới, nên client-side navigation và `usePathname()` không đổi.
+> `pnpm smoke:entries` canh lại điều này ở mỗi lần publish.
 
 ### 4.3 Token ngoài Tailwind
 
@@ -359,11 +366,130 @@ const { background, foreground } = getAvatarToneColors("Nguyễn Đức Thành",
 > 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.
 
+### 4.4 Biểu đồ, và hằng của gói khi dùng ở Server Component
+
+Hai điều phải biết trước khi vẽ biểu đồ đầu tiên. Cả hai đều do app mẫu `comitor-starter` phát
+hiện bằng cách *dùng thật*, và cả hai đều IM LẶNG — không có lỗi, không có warning. Mục 1 có **hai
+nửa**: một nửa gói tự lo (`Comitor*Chart`), một nửa app phải tự lo (`ChartContainer` + recharts tự
+lắp) — đừng đọc nửa đầu rồi bỏ nửa sau.
+
+**1. Hiệu ứng vẽ dần mặc định TẮT (từ `0.2.2`).** Với `recharts` 2.15.x + React 19.2, hiệu ứng
+không bao giờ chạy tới khung hình cuối, nên mark đứng nguyên ở khung đầu — tức là vô hình. Đo trên
+DOM thật, ba dạng cùng một lỗi:
+
+| | biểu hiện trong SVG | thấy trên màn hình |
+|---|---|---|
+| `<Bar>` | `<g class="recharts-bar-rectangle">` **rỗng** (`Rectangle` trả `null` khi cao 0) | không có cột |
+| `<Line>` | path có `d` đúng nhưng `stroke-dasharray="0px 634px"` | không có đường |
+| `<Area>` | path có `d` đúng nhưng `<clipPath><rect width="0">` | không có vùng |
+
+Kết quả giống hệt nhau: đủ trục, đủ lưới, đủ chú giải, KHÔNG có dữ liệu — và chờ bao lâu cũng
+không tự hết. Nay ba component nhận prop **optional** `isAnimationActive`, mặc định `false`:
+
+```tsx
+<ComitorBarChart data={data} xAxisKey="thang" series={series} />          // hiện ngay
+<ComitorBarChart data={data} xAxisKey="thang" series={series} isAnimationActive />  // bật lại
+```
+
+Bật lại chỉ nên làm khi app chạy **recharts 3.x**; trên 2.15.x nó dựng lại đúng cái biểu đồ trống
+ở trên.
+
+**1b. Tự lắp recharts (`ChartContainer`) thì PHẢI TỰ TẮT — gói không đặt hộ được.** Mặc định mới ở
+trên chỉ có hiệu lực bên trong ba wrapper `Comitor*Chart`. Entry `/chart` còn một đường dùng thứ
+hai, đúng lối shadcn quen thuộc: `<ChartContainer>` + recharts do app tự lắp. Ở đường đó
+`<Bar>`/`<Line>`/`<Area>` là **children do app viết**, container không sờ vào được, nên trên
+`recharts` 2.15.x app gặp lại y nguyên lỗi im lặng của `0.2.1` — đủ trục, đủ lưới, KHÔNG có dữ liệu:
+
+```tsx
+"use client";
+import { ChartContainer } from "@comitor/ui/chart";
+import { Bar, BarChart, XAxis } from "recharts";
+
+// ✗ recharts 2.15.x — <g class="recharts-bar-rectangle"> rỗng, không cột nào
+<ChartContainer config={{ doanhThu: { label: "Doanh thu", color: "var(--chart-1)" } }}>
+  <BarChart data={data}>
+    <XAxis dataKey="thang" />
+    <Bar dataKey="doanhThu" fill="var(--color-doanhThu)" />
+  </BarChart>
+</ChartContainer>
+
+// ✓ tắt tay, trên TỪNG mark
+<Bar dataKey="doanhThu" fill="var(--color-doanhThu)" isAnimationActive={false} />
+<Line dataKey="doanhThu" stroke="var(--color-doanhThu)" isAnimationActive={false} />
+<Area dataKey="doanhThu" fill="var(--color-doanhThu)" isAnimationActive={false} />
+```
+
+Đo trên DOM thật (Next 16.3.2 · React 19.2.8 · recharts 2.15.4, `next build` + `next start`, chờ
+5000ms sau hydrate), cùng một trang chỉ khác một prop:
+
+| mark trong `<ChartContainer>` | thiếu prop | có `isAnimationActive={false}` |
+|---|---|---|
+| `<Bar>` | 3 `<g.recharts-bar-rectangle>`, **0** `path.recharts-rectangle` | **3/3** path, cao 273/410/342px |
+| `<Line>` | `stroke-dasharray="0px 818.84px"` | `stroke-dasharray` = `null` |
+| `<Area>` | `<clipPath><rect width="0">` | không còn rect `width="0"` |
+
+Trên **recharts 3.x** thì bỏ prop đi cũng được — lỗi không tồn tại ở đó. Nhưng dải peer của gói là
+`>=2.15.0`, nên cứ ghi `isAnimationActive={false}`: trên 3.x nó chỉ còn nghĩa "không hoạt hình".
+
+**2. `CHART_COLORS` (và mọi hằng khác của gói) đọc được từ Server Component.** Ở `0.2.1` thì
+không: hai hằng đó export từ `chart/comitor-chart.tsx`, mà file đó có `"use client"`. Bundler RSC
+cắt ranh giới theo FILE, nên mọi export của một module client tới phía server đều là
+client-reference proxy — `CHART_COLORS.gold` ra `undefined`, **không throw, không warning**, trong
+khi TypeScript vẫn khai kiểu literal. Kịch bản gãy đúng như JSDoc của gói đang khuyên viết:
+
+```tsx
+// page.tsx — Server Component
+const series = [{ key: "loi", color: CHART_COLORS.red }];   // 0.2.1: color = undefined (im lặng)
+```
+
+`0.2.2` chuyển **10 hằng** sang module không có directive (`chart/chart-colors.ts`,
+`components/composite/*-constants.ts`) và cho barrel xuất thẳng từ đó. Tên export không đổi, chỗ
+import không đổi:
+
+| Đọc từ Server Component | `0.2.1` | `0.2.2` |
+|---|---|---|
+| `CHART_COLORS.gold` | `undefined` | `"var(--chart-1)"` |
+| `CHART_SERIES_COLORS[0]` | `undefined` | `"var(--chart-1)"` |
+| `DEFAULT_DATA_TABLE_LABELS.emptyTitle` | `undefined` | `"Chưa có dữ liệu"` |
+| `VI_DATE_FORMAT` | `undefined` | `"dd/MM/yyyy"` |
+| `DEFAULT_DATE_PRESETS.length` | `0` | `3` |
+| `DEFAULT_DATE_RANGE_PRESETS.length` | `0` | `5` |
+| `DEFAULT_PAGE_SIZE_OPTIONS[0]` | `undefined` | `20` |
+| `SELECT_EMPTY_VALUE` | `undefined` | `"__empty__"` |
+| `DEFAULT_TABLE_PAGINATION_LABELS.region` | `undefined` | `"Phân trang"` |
+| `DEFAULT_SEARCH_FILTER_BAR_LABELS.searchPlaceholder` | `undefined` | `"Tìm kiếm…"` |
+
+`toSelectValue` / `fromSelectValue` đi cùng `SELECT_EMPTY_VALUE`, nên nay gọi được trong Server
+Action. `pnpm verify:directives` canh không cho hằng thuần lọt ngược vào file `"use client"`.
+
+> **Vẫn còn nằm sau ranh giới client — 13 tên, và tất cả đều BÁO LỖI TO, không im lặng.** Chúng là
+> hàm export từ file `"use client"`; gọi ở Server Component ném `Attempted to call <tên>() from the
+> server but <tên> is on the client`. Đã kiểm bằng trang Server Component prerender thật
+> (Next 16.3.2, `next build`, đọc HTML sinh ra trên đĩa): **13/13 ném đúng lỗi đó, 10/10 đối chứng
+> chạy bình thường**.
+>
+> | | tên | vì sao vẫn ở đó |
+> |---|---|---|
+> | dựng chuỗi class (`cva`) | `buttonVariants`, `toggleVariants`, `fieldVariants`, `inputGroupAddonVariants`, `inputGroupButtonVariants` | sống cùng file với component client tương ứng |
+> | gọi lệnh toast | `toast`, `dismissToast`, `toastPromise` | vốn chỉ có nghĩa trong trình duyệt |
+> | hook | `useIsMac`, `useCarousel`, `useShell` (`/shell`), `useChart` (`/chart`), `useFormField` (`/form`) | hook thì đương nhiên client |
+>
+> Nhóm đầu là nhóm dễ vấp nhất, vì chúng chỉ ghép chuỗi class — không có lý do trực giác nào để
+> chúng không chạy ở trang server. Muốn dựng class nút cho một `<a>` ở trang server thì để phần đó
+> trong một client component.
+>
+> Chín helper `cva` còn lại **KHÔNG** kẹt — `alertVariants`, `badgeVariants`, `buttonGroupVariants`,
+> `cardVariants`, `emptyMediaVariants`, `itemVariants`, `itemMediaVariants`,
+> `navigationMenuTriggerStyle`, `statCardIconVariants`, cùng `cn`, đều gọi được từ Server Component
+> (đã đo cùng lượt, cùng trang). Danh sách trên là đầy đủ, không phải trích: nó dựng từ đồ thị
+> re-export của cả 5 entry, lọc mọi tên có giá trị runtime mà khai báo nằm trong file `"use client"`.
+
 ## 5. Bảng component
 
-Số liệu thực tế của `0.2.1`: **51 file primitive · 24 file composite · 18 file shell · 2 file chart**
+Số liệu thực tế của `0.2.2`: **51 file primitive · 29 file composite · 18 file shell · 3 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;
+**15** · `/tokens` **15** (xem §3 cho các tên xuất hiện ở nhiều entry). `0.2.2` **không thêm/bớt tên
+nào**; số file tăng vì hằng dữ liệu được tách sang module riêng (§4.4). 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`)
@@ -458,7 +584,8 @@ Kèm 2 module thuần (không phải component, dùng được cả hai phía):
 | `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 |
 | `UserMenu`, `UserAvatar`, `NotificationsButton` | Vùng phải của header |
-| `ThemeProvider`, `ThemeToggle`, `SonnerToaster` | Theme (next-themes) + toast bám theme |
+| `ThemeProvider`, `ThemeToggle`, `SonnerToaster` | Theme sáng/tối (next-themes) + toast bám theme |
+| `ContrastProvider`, `ContrastToggle`, `useContrast`, `ContrastScript` | **Trục thứ hai của giao diện**: chọn BẢNG MÀU (bản duyệt comitor-ds ⇄ bản tương phản cao). Độc lập với sáng/tối; lưu ở localStorage `comitor-contrast`. Provider tự render script chống nháy — xem §6.0 |
 | `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 (`ShellLabels`, 32 khoá); helper `flattenNavItems`, `isNavItemActive`, `isNavBranchActive`, `toNavGroups`, `resolveCurrentApp`, `getEntitledApps`, `getLockedApps`, `appAccentStyle`, `normalizeVi`, `getVietnameseInitials` |
@@ -470,10 +597,11 @@ Hợp đồng dữ liệu (type): `Workspace`, `AppDescriptor`, `NavItem`, `NavG
 
 | Component | Công dụng |
 |---|---|
-| `ChartContainer`, `ChartTooltip`, `ChartTooltipContent`, `ChartLegend`, `ChartLegendContent`, `ChartStyle`, `useChart` | Lớp shadcn bọc recharts (giữ tên trần theo API gốc) |
+| `ChartContainer`, `ChartTooltip`, `ChartTooltipContent`, `ChartLegend`, `ChartLegendContent`, `ChartStyle`, `useChart` | Lớp shadcn bọc recharts (giữ tên trần theo API gốc). ⚠ Tự lắp `<Bar>`/`<Line>`/`<Area>` ở đây thì trên **recharts 2.15.x phải tự ghi `isAnimationActive={false}` lên từng mark** — container không đặt hộ được, quên là biểu đồ trống không báo lỗi (§4.4 mục 1b) |
 | `ComitorAreaChart`, `ComitorBarChart`, `ComitorLineChart` | Bản dựng sẵn theo brand — truyền `data` + `series` là xong |
 | `ComitorChartContainer`, `ComitorChartTooltip` | Bản tiện dụng; **có tiền tố `Comitor`** để không đụng tên trần ở trên |
-| `CHART_COLORS`, `CHART_SERIES_COLORS` | Bảng màu series mặc định |
+| `CHART_COLORS`, `CHART_SERIES_COLORS` | Bảng màu series mặc định — **hằng dữ liệu thuần, đọc được từ Server Component** (§4.4) |
+| `ChartColorName` | Khoá của `CHART_COLORS` |
 
 ### Form (`@comitor/ui/form`)
 
@@ -530,6 +658,63 @@ trong component.
 
 Toàn bộ token nằm ở [`styles.css`](./styles.css); bản mirror TS ở [`src/tokens.ts`](./src/tokens.ts).
 
+### 6.0 HAI bảng màu — đọc trước §6.1
+
+Gói có **hai** bảng màu, cùng một bộ component:
+
+| | Bật bằng | Là gì |
+|---|---|---|
+| **Mặc định** | (không cần gì) | Bảng của **comitor-ds** — repo design system đã được duyệt. Đây là nguồn sự thật về hình thức. |
+| **Tương phản cao** | `<html data-contrast="high">` | Bảng đã đo WCAG (chính là bảng của `0.2.x`). Dành cho màn hình độ sáng thấp, màn hình rẻ, hoặc dùng ngoài trời. |
+
+Bảng mặc định **cố ý có những cặp dưới ngưỡng** — đó là quyết định của người duyệt, không phải lỗi bỏ
+sót. Danh sách đầy đủ nằm ở khối `NGUỒN SỰ THẬT` đầu `styles.css`; những khoản chính:
+
+```
+viền control (--input) trên nền trang        1,16:1   (1.4.11 đòi 3:1)
+rãnh Switch BẬT, gạch active Tabs (gold)     1,86:1   (1.4.11 đòi 3:1)
+--muted-foreground trên --muted              3,58:1   (1.4.3  đòi 4,5:1)
+chữ trắng trên nền --destructive             4,38:1   (1.4.3  đòi 4,5:1)
+Button variant link (--gold-400)             3,15:1   (1.4.3  đòi 4,5:1)
+```
+
+Hai ngoại lệ giữ bản sửa ở **cả hai** bảng, vì màu chữ của bản duyệt gần trùng màu nền tới mức không
+đọc nổi trên bất kỳ màn hình nào: `Badge` variant `warning` (1,52:1 → 6,24:1) và `success`
+(2,82:1 → 5,88:1). Nền giữ nguyên của bản duyệt, chỉ đậm chữ.
+
+**Cách bật trong app** — hai bước, app không sở hữu màu nào:
+
+```tsx
+// app/layout.tsx (Server Component)
+import { ContrastProvider, ThemeProvider } from "@comitor/ui/shell";
+
+<html lang="vi" suppressHydrationWarning>
+  <body>
+    <ThemeProvider>
+      <ContrastProvider>{children}</ContrastProvider>
+    </ThemeProvider>
+  </body>
+</html>
+```
+
+```tsx
+// trang cài đặt (client)
+import { ContrastToggle } from "@comitor/ui/shell";
+
+<ContrastToggle />
+```
+
+`ContrastProvider` tự render script chống nháy trong `<body>` — app **không** phải thêm gì vào
+`<head>`, và **đừng** đặt `<ContrastScript />` vào `<head>`: React 19 báo lỗi console ở mọi lần
+render client (script inline không nằm trong nhóm phần tử React hoisted được).
+
+> ⚠ **Điều kiện để hai bảng cùng sống**: mọi component đi qua **token vai trò**
+> (`--control-on`, `--control-edge`, `--control-check`, `--switch-track`, `--slider-track`,
+> `--input-fill`, `--primary-ink`, `--link-ink`…) chứ **không** viết thẳng `bg-gold-300` /
+> `bg-ash-300` / `text-gold-400`. Viết thẳng thang màu là khoá cứng một bảng, và bảng kia lặng lẽ
+> sai. Cổng `pnpm lint:a11y` bắt được lỗi này vì nó đo **bảng tương phản cao**: giá trị viết thẳng
+> không đổi theo bảng nên sẽ hiện ra ở đó đúng bằng con số của bảng mặc định — tức là đỏ.
+
 ### 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:
@@ -550,9 +735,15 @@ 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:`.
+Ở **dark** không có bậc riêng: `--x-ink` 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:`. Ở bảng **mặc định**, comitor-ds dùng cùng một hex cho
+cả hai theme nên bậc ink ở dark bằng bậc ở light; ở bảng **tương phản cao**, khối
+`.dark[data-contrast="high"]` nâng `--teal/--green/--red/--yellow` lên bậc sáng và `--x-ink` đi theo.
+
+> ⚠ Hợp đồng `-ink` chỉ còn ràng buộc chặt ở các cụm **tonal** mà comitor-ds không có (`Badge`
+> success/warning, `StatusPill`, `LetterAvatar`, `StatCard`, `Toast`) — đó là chỗ chữ đứng trên tint
+> của chính nó và bậc ink là thứ duy nhất giữ chữ đọc được. Với primitive **có** trong comitor-ds, bản
+> duyệt thắng: ở bảng mặc định `--primary-ink` = `--primary` và `--destructive-ink` = `--destructive`.
 
 Ba vai trò áp cho mọi họ token:
 
@@ -563,29 +754,36 @@ Ba vai trò áp cho mọi họ token:
 | 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.
+Brand cũng có bậc `-ink`, nhưng **giá trị của nó phụ thuộc bảng màu** (§6.0): 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**.
+comitor-ds chấp nhận con số đó, nên ở bảng mặc định `--primary-ink` = `--primary`; ở bảng tương phản
+cao nó mượn `--gold-500` `#7A5800` (**6,51:1** ✓ light) và trỏ về `--primary` ở dark (**12,67:1** ✓).
+Đây là màu của rãnh `Switch` khi BẬT và ô `Checkbox` đã chọn — component viết `bg-control-on`, token
+đó trỏ vào `--primary-ink`. `--ring` **cố ý vẫn là** `--primary` ở cả hai bảng: vòng focus thuộc tiêu
+chí AAA của WCAG 2.2, ngoài mục tiêu của gói.
 
-Ba lỗi hay gặp nhất, và cách sửa:
+Các lỗi hay gặp nhất, và cách sửa. **Số đo trong bảng là của bảng TƯƠNG PHẢN CAO** — đó là bảng có hợp
+đồng; ở bảng mặc định vài cặp thấp hơn theo đúng bản duyệt (§6.0):
 
 | 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) |
+| `bg-primary` / `bg-gold-300` làm rãnh `Switch` khi BẬT | Khoá cứng một bảng màu: bảng tương phản cao không đổi được nó nữa | `bg-control-on` |
+| `bg-ash-300` làm rãnh `Switch` khi TẮT, `bg-muted` làm rãnh `Slider` | Cùng lý do — thang màu thô không theo bảng | `bg-switch-track` / `bg-slider-track` |
+| `text-ink` làm dấu check của `Checkbox` | Ở bảng tương phản cao nền ô là gold-500 TỐI, dấu mực chỉ 1,86:1 ✗ | `text-control-check` |
+| `border-border` làm viền của control | `--border` là ranh giới **TRANG TRÍ**; `--control-edge` mới là thứ bảng tương phản cao kéo đậm lên | `border-input` (= `--control-edge`) |
+| `bg-input/30` làm lớp tô ô nhập ở dark | Ở bảng tương phản cao `--input` là #7E8290, tô 30% ra mảng xám sáng làm placeholder tụt còn 3,22:1 ✗ | `dark:bg-input-fill` |
 | `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) |
+| `text-destructive` cho chữ trên nền trang | `--destructive` là màu **NỀN**; ở bảng tương phản cao nó là bậc đậm cho chữ trắng đứng lên và làm chữ thì chỉ 3,76:1 ✗ ở dark | `text-destructive-ink` (7,15:1 light / 6,42:1 dark ở bảng tương phản cao; = `--destructive` ở bảng mặc định, đúng `text-destructive` của comitor-ds) |
 
 > ⚠ **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.
+> ⚠ **Ghi đè `--primary` thì nên set kèm `--primary-ink`** nếu app muốn một bậc tối riêng cho brand
+> của mình. Ở bảng mặc định hai biến này trùng nhau nên quên cũng không sai màu; ở bảng tương phản cao
+> thì `--primary-ink` là thứ điều khiển control BẬT, quên là control giữ nguyên gold-500 mặc định.
 >
 > ⚠ **Đổ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
@@ -599,13 +797,15 @@ Bản mirror TS đi theo đúng hợp đồng này: `accent` (nền) ⇄ `accent
 
 | Nhóm | Token | Ghi chú |
 |---|---|---|
-| 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 |
+| Brand | `gold-50 … gold-600` | `gold-300 #E8B824` = `--primary` (light); dark nâng lên `gold-200 #F5D060`. `--primary-ink` = `--primary` ở bảng mặc định; ở bảng tương phản cao là `gold-500 #7A5800` (light) / `= --primary` (dark) — xem §6.0 và §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ụ (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àu phụ (NỀN) | `navy`, `teal`, `red`, `green`, `yellow` | Vai trò **tô nền** (fill đặc hoặc tint). Bảng mặc định dùng một hex cho cả hai theme (đúng comitor-ds); bảng tương phản cao nâng sáng ở dark. ⚠ `--destructive` là token RIÊNG (nền nút xoá): `#D64545` ở bảng mặc định, `#C93B3B` ở bảng tương phản cao để 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ố ý) |
+| Trạng thái | `success`, `warning`, `info`, `destructive` (+ `-foreground`, `-ink`, `destructive-hover`) | Ba cái đầu alias sang `green` / `yellow` / `teal`; `destructive` ghim một giá trị cho cả hai theme. `-ink` là bậc để làm **chữ** trạng thái. `--destructive-hover` phải là token riêng vì hai bảng đi **ngược chiều**: comitor-ds viết `hover:bg-red/90` (nhạt dần), bảng tương phản cao phải đậm thêm |
+| Ranh giới control | `control-edge`, `control-edge-strong`, `input`, `input-fill` | **Ranh giới của control** (viền ô nhập, ô checkbox chưa chọn). `--control-edge` trỏ vào `--input`. Bảng mặc định: `#EDEEF1` / `#1E2128` — bằng bậc trang trí, đúng comitor-ds. Bảng tương phản cao: `#7E8290` cho cả hai theme (3,83:1 / 4,94:1). `--control-edge-strong` là bậc hover. `--input-fill` là lớp tô mờ ở dark (`dark:bg-input-fill`) — ở bảng mặc định nó là thứ duy nhất còn khoanh vùng ô Radio/OTP, ở bảng tương phản cao nó trong suốt |
+| Control BẬT / ĐÃ CHỌN | `control-on`, `control-knob`, `control-check`, `switch-track`, `slider-track` | Rãnh `Switch` BẬT / ô `Checkbox` đã chọn dùng `bg-control-on` (= `--primary-ink`); núm Switch là `bg-control-knob`; dấu check và chữ trên ngày đang chọn của `Calendar` là `text-control-check` (MỰC ở bảng mặc định vì nền là gold sáng, màu nền trang ở bảng tương phản cao vì nền là gold-500 tối). `switch-track`/`slider-track` là rãnh lúc TẮT — comitor-ds cho hai thứ này hai bậc khác nhau nên không gộp được |
+| Link | `link-ink`, `link-ink-hover` | Button variant `link`. Tách khỏi `--primary-ink` vì comitor-ds dùng `gold-400` cho chữ link nhưng `gold-300` cho viền focus |
 | 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) |
@@ -673,7 +873,8 @@ 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 verify:directives   # ranh giới server/client: directive còn sau build + không hằng thuần kẹt trong file client
+pnpm smoke:entries       # nạp cả 5 entry bằng Node ESM thuần, qua đúng `exports` map (chạy SAU build)
 pnpm check:exports       # publint --strict + attw
 ```
 
@@ -701,7 +902,12 @@ in ra đúng con số này — đừng chép số từ đây mà không chạy l
 
 `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
+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.
+
+⚠ Cổng đo **bảng tương phản cao** (`:root` + `[data-contrast="high"]`), không đo bảng mặc định — bảng
+mặc định là bản duyệt và đã được chấp nhận với đúng những con số dưới ngưỡng ở §6.0; bắt nó là bắt một
+quyết định, và một cổng lúc nào cũng đỏ thì lần sau không ai chạy nữa. Hệ quả có lợi: component nào viết
+thẳng thang màu thay vì token vai trò sẽ đỏ ngay, vì giá trị viết thẳng không đổi theo bảng. 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).

package/dist/chart/chart-colors.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Bảng màu biểu đồ — **module dữ liệu thuần, CỐ Ý không có `"use client"`**.
+ *
+ * ─ VÌ SAO TÁCH RA KHỎI `comitor-chart.tsx` ─
+ * Hai hằng này từng nằm chung file với `<ComitorBarChart>`, mà file đó bắt buộc phải mở đầu
+ * bằng `"use client"` (recharts đo kích thước bằng DOM). Hệ quả trong React Server Components:
+ * mọi export của một module client — kể cả hằng dữ liệu — đến tay Server Component dưới dạng
+ * **client-reference proxy**, không phải giá trị thật. Đọc `CHART_COLORS.gold` ở trang server
+ * trả về `undefined`, KHÔNG throw, KHÔNG warning, trong khi TypeScript vẫn khai kiểu literal
+ * `"var(--chart-1)"`. Bằng chứng đo được (Next 16, `next build`, trang server prerender):
+ *
+ *     CHART_COLORS.gold        → undefined      (khi export từ file có "use client")
+ *     gold[300] @ ui/tokens    → "#E8B824"      (module thuần, cùng lúc, cùng trang)
+ *
+ * Kịch bản gãy điển hình: dựng mảng `series` ngay trong Server Component rồi truyền xuống
+ * biểu đồ — `series: [{ key: "loi", color: CHART_COLORS.red }]` ra `color: undefined`, biểu đồ
+ * lặng lẽ rơi về màu xoay vòng mặc định. Chính JSDoc của gói đang khuyên viết như vậy.
+ *
+ * ─ RE-EXPORT PHẢI ĐI THẲNG TỪ BARREL ─
+ * `chart/index.ts` phải `export * from "./chart-colors.js"` TRỰC TIẾP. Re-export vòng qua
+ * `comitor-chart.tsx` là vô nghĩa: bundler RSC cắt ranh giới ở FILE, nên bất cứ thứ gì đi qua
+ * một file `"use client"` — kể cả re-export — đều thành proxy trở lại. Cũng vì thế
+ * `comitor-chart.tsx` chỉ được `import` hai hằng này, tuyệt đối không `export` lại chúng
+ * (vừa vô hiệu, vừa đụng tên với `export *` của barrel).
+ */
+/**
+ * Bảng màu series mặc định — trỏ vào `--chart-1…5` trong `styles.css`.
+ *
+ * Vì sao không lấy thẳng `var(--gold-300)`, `var(--teal)`… như comitor-ds: bảng màu biểu đồ
+ * cần đổi ĐỘC LẬP với brand (app đổi `--chart-*` ở `<body>` là xong), và `--chart-3` có bản
+ * dark riêng (navy nguyên bản chìm vào nền tối).
+ *
+ * Dùng `var(--chart-N)` chứ KHÔNG dùng `var(--color-chart-N)`: bản `--chart-*` được khai
+ * tường minh trong `:root` của `styles.css` nên chắc chắn tồn tại, còn `--color-chart-*` là
+ * biến do `@theme inline` của Tailwind sinh ra.
+ */
+declare const CHART_SERIES_COLORS: readonly ["var(--chart-1)", "var(--chart-2)", "var(--chart-3)", "var(--chart-4)", "var(--chart-5)"];
+/**
+ * Màu gọi theo tên — dùng khi muốn chỉ định màu cho một series cụ thể
+ * (`series: [{ key: "loi", color: CHART_COLORS.red }]`).
+ *
+ * ⚠ Khoá `gray` của comitor-ds đổi thành `ash`: thang xám của package là `--ash-*`,
+ * `gray-*` để nguyên cho Tailwind (xem chú thích thang màu trong `styles.css`).
+ */
+declare const CHART_COLORS: {
+    readonly gold: "var(--chart-1)";
+    readonly goldLight: "var(--gold-100)";
+    readonly teal: "var(--chart-2)";
+    readonly navy: "var(--chart-3)";
+    readonly green: "var(--chart-4)";
+    readonly red: "var(--chart-5)";
+    readonly ash: "var(--ash-300)";
+};
+type ChartColorName = keyof typeof CHART_COLORS;
+
+export { CHART_COLORS, CHART_SERIES_COLORS, type ChartColorName };

package/dist/chart/chart-colors.js

@@ -0,0 +1,21 @@
+const CHART_SERIES_COLORS = [
+  "var(--chart-1)",
+  "var(--chart-2)",
+  "var(--chart-3)",
+  "var(--chart-4)",
+  "var(--chart-5)"
+];
+const CHART_COLORS = {
+  gold: "var(--chart-1)",
+  goldLight: "var(--gold-100)",
+  teal: "var(--chart-2)",
+  navy: "var(--chart-3)",
+  green: "var(--chart-4)",
+  red: "var(--chart-5)",
+  ash: "var(--ash-300)"
+};
+export {
+  CHART_COLORS,
+  CHART_SERIES_COLORS
+};
+//# sourceMappingURL=chart-colors.js.map

package/dist/chart/chart-colors.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/chart/chart-colors.ts"],"sourcesContent":["/**\n * Bảng màu biểu đồ — **module dữ liệu thuần, CỐ Ý không có `\"use client\"`**.\n *\n * ─ VÌ SAO TÁCH RA KHỎI `comitor-chart.tsx` ─\n * Hai hằng này từng nằm chung file với `<ComitorBarChart>`, mà file đó bắt buộc phải mở đầu\n * bằng `\"use client\"` (recharts đo kích thước bằng DOM). Hệ quả trong React Server Components:\n * mọi export của một module client — kể cả hằng dữ liệu — đến tay Server Component dưới dạng\n * **client-reference proxy**, không phải giá trị thật. Đọc `CHART_COLORS.gold` ở trang server\n * trả về `undefined`, KHÔNG throw, KHÔNG warning, trong khi TypeScript vẫn khai kiểu literal\n * `\"var(--chart-1)\"`. Bằng chứng đo được (Next 16, `next build`, trang server prerender):\n *\n *     CHART_COLORS.gold        → undefined      (khi export từ file có \"use client\")\n *     gold[300] @ ui/tokens    → \"#E8B824\"      (module thuần, cùng lúc, cùng trang)\n *\n * Kịch bản gãy điển hình: dựng mảng `series` ngay trong Server Component rồi truyền xuống\n * biểu đồ — `series: [{ key: \"loi\", color: CHART_COLORS.red }]` ra `color: undefined`, biểu đồ\n * lặng lẽ rơi về màu xoay vòng mặc định. Chính JSDoc của gói đang khuyên viết như vậy.\n *\n * ─ RE-EXPORT PHẢI ĐI THẲNG TỪ BARREL ─\n * `chart/index.ts` phải `export * from \"./chart-colors.js\"` TRỰC TIẾP. Re-export vòng qua\n * `comitor-chart.tsx` là vô nghĩa: bundler RSC cắt ranh giới ở FILE, nên bất cứ thứ gì đi qua\n * một file `\"use client\"` — kể cả re-export — đều thành proxy trở lại. Cũng vì thế\n * `comitor-chart.tsx` chỉ được `import` hai hằng này, tuyệt đối không `export` lại chúng\n * (vừa vô hiệu, vừa đụng tên với `export *` của barrel).\n */\n\n/**\n * Bảng màu series mặc định — trỏ vào `--chart-1…5` trong `styles.css`.\n *\n * Vì sao không lấy thẳng `var(--gold-300)`, `var(--teal)`… như comitor-ds: bảng màu biểu đồ\n * cần đổi ĐỘC LẬP với brand (app đổi `--chart-*` ở `<body>` là xong), và `--chart-3` có bản\n * dark riêng (navy nguyên bản chìm vào nền tối).\n *\n * Dùng `var(--chart-N)` chứ KHÔNG dùng `var(--color-chart-N)`: bản `--chart-*` được khai\n * tường minh trong `:root` của `styles.css` nên chắc chắn tồn tại, còn `--color-chart-*` là\n * biến do `@theme inline` của Tailwind sinh ra.\n */\nexport const CHART_SERIES_COLORS = [\n  \"var(--chart-1)\",\n  \"var(--chart-2)\",\n  \"var(--chart-3)\",\n  \"var(--chart-4)\",\n  \"var(--chart-5)\"\n] as const;\n\n/**\n * Màu gọi theo tên — dùng khi muốn chỉ định màu cho một series cụ thể\n * (`series: [{ key: \"loi\", color: CHART_COLORS.red }]`).\n *\n * ⚠ Khoá `gray` của comitor-ds đổi thành `ash`: thang xám của package là `--ash-*`,\n * `gray-*` để nguyên cho Tailwind (xem chú thích thang màu trong `styles.css`).\n */\nexport const CHART_COLORS = {\n  gold: \"var(--chart-1)\",\n  goldLight: \"var(--gold-100)\",\n  teal: \"var(--chart-2)\",\n  navy: \"var(--chart-3)\",\n  green: \"var(--chart-4)\",\n  red: \"var(--chart-5)\",\n  ash: \"var(--ash-300)\"\n} as const;\n\nexport type ChartColorName = keyof typeof CHART_COLORS;\n"],"mappings":"AAqCO,MAAM,sBAAsB;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AASO,MAAM,eAAe;AAAA,EAC1B,MAAM;AAAA,EACN,WAAW;AAAA,EACX,MAAM;AAAA,EACN,MAAM;AAAA,EACN,OAAO;AAAA,EACP,KAAK;AAAA,EACL,KAAK;AACP;","names":[]}

package/dist/chart/chart.d.ts

@@ -6,6 +6,10 @@ import * as RechartsPrimitive from 'recharts';
  * `shadcn add` vẫn dùng lại được. Đây là tầng "thô": bạn tự lắp recharts bên trong.
  * Muốn dựng nhanh 3 loại biểu đồ quen thuộc thì xem `comitor-chart.tsx`.
  *
+ * ⚠⚠ TỰ LẮP RECHARTS 2.15.x THÌ PHẢI TỰ TẮT HIỆU ỨNG VẼ DẦN ⚠⚠
+ * Xem chú thích của {@link ChartContainer} ngay dưới. Tầng này KHÔNG đặt hộ được
+ * `isAnimationActive={false}` như `Comitor*Chart` làm, vì mark là children do app viết.
+ *
  * Cơ chế màu (điểm hay nhất, và cũng dễ hiểu sai nhất):
  * `<ChartContainer>` render kèm `<ChartStyle>` — thẻ này sinh ra biến CSS `--color-<key>`
  * cho từng key trong `config`, giới hạn phạm vi bằng `[data-chart=<id>]`. Series recharts
@@ -46,6 +50,42 @@ type ChartContainerProps = React.ComponentProps<"div"> & {
 /**
  * Khung biểu đồ: cấp context `config`, bơm biến màu, và bọc sẵn `ResponsiveContainer`.
  * Tỉ lệ mặc định `aspect-video`; muốn cao cố định thì truyền `className="h-64 aspect-auto"`.
+ *
+ * ─ ⚠ RECHARTS 2.15.x: PHẢI TỰ GHI `isAnimationActive={false}` LÊN TỪNG MARK ─
+ * Với `recharts` 2.15.x + React 19.2, hiệu ứng vẽ dần (mặc định BẬT của recharts) không bao giờ
+ * chạy tới khung hình cuối: mark đứng nguyên ở khung đầu, tức là **vô hình**. Biểu đồ ra đủ trục,
+ * đủ lưới, đủ chú giải, KHÔNG có dữ liệu — không lỗi, không warning, chờ bao lâu cũng không tự hết.
+ *
+ * `<ComitorBarChart>` / `<ComitorLineChart>` / `<ComitorAreaChart>` đã đặt sẵn `false` từ `0.2.2`.
+ * **`<ChartContainer>` thì KHÔNG đặt hộ được** — `<Bar>` / `<Line>` / `<Area>` là children do app
+ * viết, container không sờ vào. Đi lối shadcn quen thuộc mà quên prop này là gặp đúng lỗi im lặng
+ * của `0.2.1`:
+ *
+ * ```tsx
+ * // ✗ recharts 2.15.x: <g class="recharts-bar-rectangle"> rỗng, không cột nào
+ * <ChartContainer config={config}>
+ *   <BarChart data={data}>
+ *     <XAxis dataKey="thang" />
+ *     <Bar dataKey="doanhThu" fill="var(--color-doanhThu)" />
+ *   </BarChart>
+ * </ChartContainer>
+ *
+ * // ✓ tắt tay trên TỪNG mark
+ * <Bar dataKey="doanhThu" fill="var(--color-doanhThu)" isAnimationActive={false} />
+ * ```
+ *
+ * Đo trên DOM thật (Next 16.3.2 · React 19.2.8 · recharts 2.15.4, `next build` + `next start`,
+ * chờ 5000ms sau hydrate) — cùng một trang, chỉ khác một prop:
+ *
+ * | mark | thiếu prop | có `isAnimationActive={false}` |
+ * |---|---|---|
+ * | `<Bar>`  | 3 `<g.recharts-bar-rectangle>` nhưng **0** `path.recharts-rectangle` | **3/3** path, cao 273/410/342px |
+ * | `<Line>` | `stroke-dasharray="0px 818.84px"` | `stroke-dasharray` = `null` |
+ * | `<Area>` | `<clipPath><rect width="0">` | không còn rect width 0 |
+ *
+ * `recharts` 3.x không dính lỗi này — bỏ prop đi là được. Dải peer của gói là `>=2.15.0` nên
+ * 2.15.x vẫn là cấu hình hợp lệ và phổ biến; cứ ghi `isAnimationActive={false}` cho chắc, trên
+ * 3.x nó chỉ có nghĩa "không hoạt hình".
  */
 declare function ChartContainer({ id, className, children, config, ...props }: ChartContainerProps): React.JSX.Element;
 type ChartStyleProps = {