@comitor/ui 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Comitor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,458 @@
+# @comitor/ui
+
+Hệ thống thiết kế dùng chung của hệ sinh thái **Comitor** (Tasks, Chat, CRM, HR, admin console,
+marketing site). Đóng gói shadcn/ui style `new-york` đã tùy biến theo brand Comitor, cộng thêm các
+component ghép sẵn và khung ứng dụng (shell) kiểu workspace × app.
+
+- **React 19 · Tailwind v4 (CSS-first) · TypeScript strict · ESM-only**
+- 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).
+
+---
+
+## 1. Cài đặt
+
+```bash
+pnpm add @comitor/ui
+# peer bắt buộc
+pnpm add react react-dom lucide-react
+pnpm add -D tailwindcss @tailwindcss/postcss
+# peer optional — cài khi dùng entry tương ứng
+pnpm add next next-themes   # cho @comitor/ui/shell
+pnpm add recharts           # cho @comitor/ui/chart
+pnpm add react-hook-form    # cho @comitor/ui/form
+```
+
+| Peer | Range | Bắt buộc | Cần khi |
+|---|---|---|---|
+| `react`, `react-dom` | `^19.0.0` | ✅ | luôn |
+| `tailwindcss` | `^4.1.0` | ✅ | luôn (`styles.css` phải được TW4 biên dịch) |
+| `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` |
+| `react-hook-form` | `^7.54.0` | — | `/form` (context singleton) |
+
+## 2. Nạp `styles.css` — ĐỌC KỸ, đây là chỗ dễ sai nhất
+
+Đặt import trong **`app/globals.css`**, ngay sau `@import "tailwindcss"`:
+
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@import "@comitor/ui/styles.css";
+```
+
+```ts
+// app/layout.tsx — chỉ import globals.css của chính app
+import "./globals.css";
+```
+
+> **KHÔNG** viết `import "@comitor/ui/styles.css"` trong `layout.tsx` (thói quen Tailwind 3).
+> File này chứa `@theme` / `@custom-variant` / `@source` — những at-rule **chỉ có nghĩa khi được
+> Tailwind biên dịch**. Import ở `layout.tsx` thì biến CSS vẫn chạy nhưng **không utility nào**
+> (`bg-gold-300`, `dark:*`…) được sinh ra → giao diện vỡ mà không có lỗi build.
+
+`styles.css` đã tự khai `@source "./dist"` để Tailwind quét class trong package (Tailwind v4 mặc
+định bỏ qua `node_modules`). Nếu dùng pnpm strict và thấy style bị mất, khai thêm ở app:
+
+```css
+@source "../node_modules/@comitor/ui/dist";
+```
+
+### Font
+
+App tự nạp Inter (subsets `latin` + `vietnamese`) và gán vào biến `--font-inter`; package chỉ tiêu thụ:
+
+```ts
+// app/layout.tsx
+import { Inter } from "next/font/google";
+
+const inter = Inter({
+  subsets: ["latin", "vietnamese"],
+  weight: ["400", "500", "600", "700", "800"],
+  display: "swap",
+  variable: "--font-inter"
+});
+```
+
+Package đọc **hai** biến font, cả hai đều tuỳ chọn:
+
+| Biến | Ai gán | Không gán thì sao |
+|---|---|---|
+| `--font-inter` | app (như trên) | `--font-sans` rơi về `"Inter", system-ui, sans-serif` — vẫn đúng nếu máy có Inter |
+| `--font-inter-mono` | app, **nếu muốn** đổi font chữ đều (số trong tooltip biểu đồ, `Kbd`…) | `--font-mono` rơi về `"Geist Mono", ui-monospace, monospace` |
+
+`--font-inter-mono` được tiêu thụ dưới dạng `var(--font-inter-mono, "Geist Mono")` — **fallback nằm ngay
+trong `var()`** là bắt buộc: `var()` không có fallback mà biến lại chưa khai thì cả khai báo `--font-mono`
+thành *invalid at computed-value time*, và `font-mono` rơi về font kế thừa chứ **không** rơi về phần còn
+lại của danh sách. Muốn dùng font mono riêng thì gán y hệt cách gán `--font-inter`:
+
+```ts
+const mono = Geist_Mono({ subsets: ["latin"], display: "swap", variable: "--font-inter-mono" });
+```
+
+### Dark mode
+
+Theo **class** (`@custom-variant dark (&:is(.dark *))`), khớp `next-themes`:
+
+```tsx
+<ThemeProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
+```
+
+Lưu ý: biến thể `dark` chỉ khớp **con cháu** của `.dark`, không khớp chính phần tử mang class đó.
+Muốn dựng preview 2 theme cạnh nhau phải bọc thêm một lớp: `<div class="dark"><div>…</div></div>`.
+
+## 3. Entry point
+
+Package có **5 entry**. Lý do tách: `tsup` build ở chế độ `bundle: false` (ESM per-file), nên chỉ cần
+barrel chính re-export **một** file có `import` tới peer optional là mọi app dùng `@comitor/ui`
+đều buộc phải cài gói đó — không cài thì bundler gãy ngay ở bước resolve.
+
+| 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/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` |
+| `@comitor/ui/tokens` | Token dạng object TS | không — cho nơi không có Tailwind: canvas, email HTML, PDF |
+| `@comitor/ui/styles.css` | Nguồn token Tailwind v4 | xem §2 |
+
+### 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:
+
+| 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 |
+| `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) |
+
+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.
+
+> **`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`** ở
+> `@comitor/ui/shell` (tự đọc `useTheme()` của next-themes). Dùng `SonnerToaster` khi app đã có
+> `ThemeProvider` của shell, còn lại dùng `Toaster`. Đừng gộp hai cái làm một.
+
+## 4. Ví dụ
+
+### 4.1 Trang nội dung — primitive + composite
+
+```tsx
+// Không có "use client": PageHeader/StatCard/StatusPill là component tĩnh → RSC render thẳng.
+import { PageContainer, PageHeader, StatCard, STATUS_TONES, StatusPill } from "@comitor/ui";
+import type { StatusConfig } from "@comitor/ui";
+
+// Bảng trạng thái là của APP, không phải của package — truyền vào qua `configs`.
+const TASK_STATUSES: StatusConfig<"todo" | "doing" | "done">[] = [
+  { value: "todo", label: "Cần làm", shortLabel: "CL", priority: 1, ...STATUS_TONES.neutral },
+  { value: "doing", label: "Đang làm", shortLabel: "ĐL", priority: 2, ...STATUS_TONES.info },
+  { value: "done", label: "Hoàn thành", shortLabel: "HT", priority: 3, ...STATUS_TONES.success }
+];
+
+export default function TasksPage() {
+  return (
+    <PageContainer width="lg">
+      <PageHeader title="Công việc" description="Toàn bộ task của workspace" />
+
+      <div className="grid gap-4 sm:grid-cols-3">
+        <StatCard
+          label="Đang mở"
+          value={128}
+          delta={{ value: "+12,5%", direction: "up", label: "so với tuần trước" }}
+        />
+        {/* polarity: quá hạn TĂNG là xấu → mũi tên lên phải tô đỏ, không tô xanh */}
+        <StatCard
+          label="Quá hạn"
+          value={7}
+          tone="destructive"
+          delta={{ value: "3 việc", direction: "up", polarity: "positive-down" }}
+        />
+        <StatCard label="Hoàn thành tuần này" value={43} tone="success" />
+      </div>
+
+      <StatusPill configs={TASK_STATUSES} value="doing" />
+    </PageContainer>
+  );
+}
+```
+
+### 4.2 Khung ứng dụng — `AppShell` + `WorkspaceSwitcher` + `AppLauncher`
+
+Shell dựng trên **hai trục điều hướng** kiểu Linear/Lark:
+
+- **Trục 1 — `WorkspaceSwitcher`**: đổi *ngữ cảnh dữ liệu* (Acme Corp ▸ Beta Ltd).
+- **Trục 2 — `AppLauncher`**: đổi *sản phẩm* trong cùng workspace (Tasks ▸ Chat ▸ CRM ▸ HR).
+
+Cả hai **không nhận dữ liệu qua prop** — chúng đọc từ context của `ShellProvider`, mà `AppShell`
+đã bọc sẵn. Vì vậy chỉ cần truyền `workspaces` / `apps` / `nav` một lần cho `AppShell`.
+
+```tsx
+// app/(app)/layout.tsx — root layout đặt ThemeProvider, layout con đặt AppShell.
+"use client";
+
+import { CheckSquare, LayoutDashboard, MessageSquare, Users } from "lucide-react";
+import { useRouter } from "next/navigation";
+import type { AppDescriptor, NavGroup, Workspace } from "@comitor/ui/shell";
+import { AppShell } from "@comitor/ui/shell";
+
+const workspaces: Workspace[] = [
+  { id: "acme", name: "Acme Corp", slug: "acme", plan: "Pro", role: "Quản trị viên", memberCount: 42 },
+  { id: "beta", name: "Beta Ltd", slug: "beta", plan: "Free", role: "Thành viên", memberCount: 6 }
+];
+
+const apps: AppDescriptor[] = [
+  { id: "tasks", name: "Công việc", icon: CheckSquare, href: "/tasks", accent: "var(--color-teal)" },
+  { id: "chat", name: "Trò chuyện", icon: MessageSquare, href: "/chat", badge: 3 },
+  { id: "crm", name: "CRM", icon: Users, href: "/crm", entitled: false } // chưa mua → hiện khoá
+];
+
+const nav: NavGroup[] = [
+  {
+    id: "main",
+    items: [
+      { id: "overview", label: "Tổng quan", href: "/tasks", icon: LayoutDashboard },
+      { id: "mine", label: "Của tôi", href: "/tasks/mine", icon: CheckSquare, badge: 12 }
+    ]
+  }
+];
+
+export default function AppLayout({ children }: { children: React.ReactNode }) {
+  const router = useRouter();
+
+  return (
+    <AppShell
+      workspaces={workspaces}
+      currentWorkspaceId="acme"
+      apps={apps}
+      currentAppId="tasks"
+      nav={nav}
+      user={{ id: "u1", name: "Nguyễn Đức Thành", email: "thanh@acme.vn", role: "Quản trị viên" }}
+      onWorkspaceChange={(id) => router.push(`/w/${id}`)}
+      onAppSelect={(app) => router.push(app.href)}
+      onUpsell={(appId) => router.push(`/billing?app=${appId}`)}
+      onLogout={signOut}
+    >
+      {children}
+    </AppShell>
+  );
+}
+```
+
+Cần tự lắp thay vì dùng `AppShell` trọn gói (vd header riêng)? Bọc `ShellProvider` rồi đặt
+`WorkspaceSwitcher` / `AppLauncher` ở đâu tuỳ ý — chúng vẫn lấy dữ liệu từ context:
+
+```tsx
+import { AppLauncher, ShellProvider, WorkspaceSwitcher } from "@comitor/ui/shell";
+
+<ShellProvider workspaces={workspaces} apps={apps} nav={nav} user={user}>
+  <header className="flex h-header items-center gap-2 px-3">
+    <WorkspaceSwitcher align="start" />
+    <AppLauncher />        {/* nút lưới 3×3, phím tắt ⌘/Ctrl + Shift + K */}
+  </header>
+  <main>{children}</main>
+</ShellProvider>
+```
+
+**Bọc `ThemeProvider` ở root layout, NGOÀI `AppShell`** — next-themes phải nằm trên cùng để không
+nháy theme lúc hydrate:
+
+```tsx
+// app/layout.tsx
+import { ThemeProvider } from "@comitor/ui/shell";
+
+<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
+  {children}
+</ThemeProvider>
+```
+
+App **không chạy trên Next**: truyền `pathname` và `LinkComponent` cho `ShellProvider`/`AppShell`
+để khỏi chạm `next/navigation`.
+
+> ⚠ 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.
+
+### 4.3 Token ngoài Tailwind
+
+```ts
+import { chart, gold, layout } from "@comitor/ui/tokens";
+
+const seriesColor = chart.light[0]; // #E8B824
+const headerPx = layout.headerHeight; // 56
+```
+
+## 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;
+các thành phần con (`CardHeader`, `DialogFooter`, `SelectItem`…) export kèm theo file tương ứng.
+
+### Tier 1 — primitive (`@comitor/ui`)
+
+shadcn/ui style `new-york`, đã tùy biến token theo brand Comitor.
+
+| Nhóm | Component |
+|---|---|
+| Hành động | `Button`, `ButtonGroup`, `Toggle`, `ToggleGroup`, `Kbd` |
+| Nhập liệu | `Input`, `InputGroup`, `InputOTP`, `Textarea`, `Label`, `Field`, `Checkbox`, `RadioGroup`, `Switch`, `Slider`, `Select`, `Calendar` |
+| Hiển thị | `Card`, `Badge`, `Avatar`, `Table`, `Separator`, `AspectRatio`, `Skeleton`, `Spinner`, `Progress`, `Empty`, `Item`, `Alert` |
+| Lớp phủ | `Dialog`, `AlertDialog`, `Sheet`, `Drawer`, `Popover`, `HoverCard`, `Tooltip`, `DropdownMenu`, `ContextMenu`, `Menubar`, `Command` |
+| Điều hướng | `Tabs`, `Breadcrumb`, `Pagination`, `NavigationMenu`, `Accordion`, `Collapsible` |
+| Khác | `ScrollArea`, `Resizable`, `Carousel` |
+
+> Hai file primitive **không** nằm ở entry chính: `form.tsx` → `@comitor/ui/form`;
+> `sonner.tsx` → `@comitor/ui/shell` (tên `SonnerToaster`). Xem §3.
+> **Không có `Sidebar` / `SidebarNav` ở Tier 1** — cố ý, không phải sót: shell Tier 3 đã có sidebar riêng
+> (hai trục điều hướng, thu gọn, nhớ trạng thái theo workspace) và bản shadcn sẽ trùng đúng 3 tên
+> `Sidebar` / `SidebarGroup` / `SidebarMenuItem` với Tier 3 nhưng API khác hẳn, lại giữ trạng thái bằng
+> 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.
+
+### 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.
+
+| 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ả |
+| `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** |
+| `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 |
+| `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) |
+
+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` |
+
+### 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 |
+| `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 |
+| `UserMenu`, `UserAvatar`, `NotificationsButton` | Vùng phải của header |
+| `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`… |
+
+Hợp đồng dữ liệu (type): `Workspace`, `AppDescriptor`, `NavItem`, `NavGroup`, `ShellNav`, `ShellUser`,
+`UserMenuItem`, `ShellLabels`, `ShellIcon`, `ShellLinkComponent`.
+
+### Chart (`@comitor/ui/chart`)
+
+| 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) |
+| `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 |
+
+### Form (`@comitor/ui/form`)
+
+`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
+
+Toàn bộ token nằm ở [`styles.css`](./styles.css); bản mirror TS ở [`src/tokens.ts`](./src/tokens.ts).
+
+| Nhóm | Token | Ghi chú |
+|---|---|---|
+| Brand | `gold-50 … gold-600` | `gold-300 #E8B824` = `--primary` (light); dark nâng lên `gold-200 #F5D060` |
+| 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 |
+| 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:
+
+```tsx
+<body style={{ "--app-accent": "#1F8A8B", "--app-accent-foreground": "#FFFFFF" } as React.CSSProperties}>
+```
+
+Đổi độ nổi (bóng) toàn hệ — ghi đè đúng 4 biến `--elevation-*`, **không** ghi đè `--shadow-*`:
+
+```css
+/* app/globals.css — sau @import "@comitor/ui/styles.css" */
+:root { --elevation-overlay: 0 12px 40px rgba(14, 17, 22, 0.2); }
+```
+
+> 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ớ
+
+1. **`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
+   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
+   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 }`
+   đổ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
+
+```bash
+pnpm install
+pnpm build        # tsup: ESM, bundle:false (transpile từng file để giữ "use client"), dts
+pnpm typecheck    # tsc --noEmit
+pnpm lint         # biome check .
+pnpm lint:fix
+pnpm verify:directives   # mọi file nguồn có "use client" ⇄ file dist tương ứng
+pnpm check:exports       # publint --strict + attw
+```
+
+> 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ì
+> `pnpm build` fail.
+
+Quy ước `"use client"`: đặt **per-file**, ở dòng đầu tiên. `tsup` chạy `bundle: false` nên mỗi file
+`.tsx` ra một file `.js` và directive được giữ nguyên → Next.js đánh đúng ranh giới server/client.
+File thuần dữ liệu (`lib/cn.ts`, `tokens.ts`, `shell/types.ts`) **không** có directive.
+
+`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
+`grep -L "use client" dist/shell/*.js`: lệnh đó soi chưa tới một phần ba số file phải soi.
+
+## 8. Giấy phép
+
+[MIT](./LICENSE) © Comitor

package/dist/chart/chart.d.ts

@@ -0,0 +1,88 @@
+import * as React from 'react';
+import * as RechartsPrimitive from 'recharts';
+
+/**
+ * Chart primitive của shadcn/ui (style new-york) — port nguyên trạng từ comitor-ds để
+ * `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`.
+ *
+ * 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
+ * chỉ việc trỏ `fill="var(--color-desktop)"`. Nhờ vậy màu vẫn nằm trong TOKEN (không hex
+ * rải trong JSX) và đổi được theo light/dark khi config khai `theme: { light, dark }`.
+ */
+declare const THEMES: {
+    readonly light: "";
+    readonly dark: ".dark";
+};
+/**
+ * Khai báo hiển thị cho từng series: nhãn, icon và màu.
+ * Dùng `color` cho màu dùng chung, hoặc `theme` khi cần màu khác nhau giữa light/dark.
+ * Giá trị màu nên là token: `"var(--chart-1)"`, `"var(--teal)"`… — đừng ghi hex.
+ */
+type ChartConfig = {
+    [k in string]: {
+        label?: React.ReactNode;
+        icon?: React.ComponentType;
+    } & ({
+        color?: string;
+        theme?: never;
+    } | {
+        color?: never;
+        theme: Record<keyof typeof THEMES, string>;
+    });
+};
+type ChartContextProps = {
+    config: ChartConfig;
+};
+/** Đọc `config` của `<ChartContainer>` gần nhất. Ném lỗi nếu gọi ngoài container. */
+declare function useChart(): ChartContextProps;
+type ChartContainerProps = React.ComponentProps<"div"> & {
+    /** Khai báo nhãn/màu cho từng series — nguồn của biến `--color-<key>`. */
+    config: ChartConfig;
+    children: React.ComponentProps<typeof RechartsPrimitive.ResponsiveContainer>["children"];
+};
+/**
+ * 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"`.
+ */
+declare function ChartContainer({ id, className, children, config, ...props }: ChartContainerProps): React.JSX.Element;
+type ChartStyleProps = {
+    /** Giá trị của thuộc tính `data-chart` trên container — dùng làm phạm vi cho biến màu. */
+    id: string;
+    config: ChartConfig;
+};
+/**
+ * Sinh thẻ `<style>` chứa `--color-<key>` cho từng series, phạm vi `[data-chart=<id>]`.
+ * `ChartContainer` đã render sẵn; chỉ export riêng cho ai tự dựng container.
+ */
+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;
+type ChartTooltipContentProps = React.ComponentProps<typeof RechartsPrimitive.Tooltip> & React.ComponentProps<"div"> & {
+    /** Ẩn dòng nhãn (trục X) ở đầu tooltip. */
+    hideLabel?: boolean;
+    /** Ẩn ô màu đứng trước tên series. */
+    hideIndicator?: boolean;
+    /** Kiểu ô màu: chấm tròn / vạch đứng / vạch đứt. */
+    indicator?: "line" | "dot" | "dashed";
+    /** Khoá dùng để tra `config` cho TÊN series (mặc định `name` rồi tới `dataKey`). */
+    nameKey?: string;
+    /** Khoá dùng để tra `config` cho NHÃN trục X. */
+    labelKey?: string;
+};
+/** 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"> & {
+    /** Ẩn icon riêng của series (nếu `config` có khai `icon`). */
+    hideIcon?: boolean;
+    /** Khoá dùng để tra `config` (mặc định `dataKey`). */
+    nameKey?: string;
+};
+/** 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 };