@comitor/ui 1.10.0 → 2.0.0

package/README.md

@@ -37,6 +37,7 @@ pnpm add -D tailwindcss @tailwindcss/postcss
 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
+pnpm add @tanstack/react-table         # cho @comitor/ui/data-grid
 pnpm add @uppy/core @uppy/xhr-upload   # cho @comitor/ui/uploader
 ```
 
@@ -49,6 +50,7 @@ pnpm add @uppy/core @uppy/xhr-upload   # cho @comitor/ui/uploader
 | `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` (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) |
+| `@tanstack/react-table` | `>=8.21.0 <9` | — | `/data-grid` (app và gói phải dùng **cùng một bản**, nếu không `ColumnDef` app tự khai sẽ lệch kiểu) |
 | `@uppy/core` | `^6.0.0` | — | `/uploader` |
 | `@uppy/xhr-upload` | `^6.0.0` | — | `/uploader` |
 
@@ -105,13 +107,14 @@ buộc ở thẻ `<html>`: https://design-system.comitor.ai/shell
 
 ## 3. Entry point
 
-Package có **6 entry**, tách theo peer optional mà mỗi tầng kéo theo:
+Package có **7 entry**, tách theo peer optional mà mỗi tầng kéo theo:
 
 | Entry | Nội dung | Peer optional kéo theo |
 |---|---|---|
 | `@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: khung ứng dụng workspace × app, theme, ba trục hiển thị | `next`, `next-themes` |
 | `@comitor/ui/chart` | Lớp shadcn bọc recharts + `Comitor*Chart` + `CHART_COLORS` | `recharts` (~100KB) |
+| `@comitor/ui/data-grid` | `DataGrid` — lưới sửa trực tiếp kiểu bảng tính: ảo hoá dòng, chọn vùng bằng bàn phím, copy/paste với Excel, ghim cột, lọc/sắp xếp nhiều tiêu chí, hoàn tác/làm lại | `@tanstack/react-table` (peer); kèm `@tanstack/react-virtual` + `@dnd-kit/*` (dependency của gói) |
 | `@comitor/ui/uploader` | `FileUpload` (tệp tài liệu) · `ImageUploadField` (ảnh đại diện, logo) · `useFileUpload` | `@uppy/core`, `@uppy/xhr-upload` (~13KB gzip) |
 | `@comitor/ui/form` | Binding shadcn ⇄ react-hook-form | `react-hook-form` |
 | `@comitor/ui/tokens` | Token dạng object TS — cho nơi không có Tailwind: canvas, email HTML, PDF | không có |
@@ -159,7 +162,7 @@ https://design-system.comitor.ai/foundations/server-client
 
 ## 5. Bảng component
 
-Số file nguồn hiện tại: **52 primitive · 31 composite · 25 shell · 4 chart · 5 uploader**. Mỗi component có trang
+Số file nguồn hiện tại: **52 primitive · 31 composite · 25 shell · 4 chart · 33 data-grid · 5 uploader**. Mỗi component có trang
 riêng kèm demo, bảng prop và cạm bẫy của nó:
 
 | Tầng | Là gì | Trang |
@@ -168,12 +171,21 @@ riêng kèm demo, bảng prop và cạm bẫy của nó:
 | **Tier 2 — composite** · 31 file · `@comitor/ui` | Giá trị thật của gói: pattern lặp ở mọi app, ghép từ nhiều primitive (`DataTable`, `PageHeader`, `Combobox`, `DatePicker`, `StatCard`…) | https://design-system.comitor.ai/composites |
 | **Tier 3 — shell** · 25 file · `@comitor/ui/shell` | Khung ứng dụng workspace × app: sidebar, header, theme, ba trục hiển thị (tương phản · mật độ · cỡ chữ) | https://design-system.comitor.ai/shell |
 | **chart** · 4 file · `@comitor/ui/chart` | Lớp shadcn bọc recharts, cùng ba bản dựng sẵn theo brand. ⚠ Ba wrapper `Comitor*Chart` **mặc định TẮT** hiệu ứng vẽ dần (`isAnimationActive = false`) — bật lại là biểu đồ kẹt ở khung đầu: có trục, có lưới, KHÔNG có dữ liệu. Mặc định đó KHÔNG áp cho `<ChartContainer>` + recharts do app tự lắp | https://design-system.comitor.ai/components/chart |
+| **data-grid** · 36 file · `@comitor/ui/data-grid` | `DataGrid` — lưới sửa trực tiếp kiểu bảng tính, cho màn nhập liệu hàng loạt. Port từ [tablecn](https://www.tablecn.com/data-grid) (MIT) sang primitive + token của gói. ⚠ Là tầng DUY NHẤT có peer **`@tanstack/react-table`**, tầng duy nhất mặc định **tiếng Anh** (prop `locale`, xem dưới), và mọi thứ trong nó là client component | [docs/data-grid.md](docs/data-grid.md) |
 | **uploader** · 5 file · `@comitor/ui/uploader` | `FileUpload` (tệp) · `ImageUploadField` (ảnh) · `useFileUpload` — kéo thả, xem trước, tiến độ. Peer optional: `@uppy/core` + `@uppy/xhr-upload` | https://design-system.comitor.ai/components |
 | **form** · `@comitor/ui/form` | Binding shadcn ⇄ react-hook-form | https://design-system.comitor.ai/components/form |
 
 **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`. Kiểu là `Partial<>` và component luôn trải `{ ...DEFAULT_*, ...labels }`,
+override qua prop `labels`.
+
+⚠ **`DataGrid` là ngoại lệ, ở cả hai vế.** Nó mặc định **tiếng Anh**, và nó không dùng `labels` mà
+dùng prop **`locale`** — `"en"` · `"vi"`, hoặc cả một object `DataGridMessages` tự soạn. Lý do:
+phần lớn chuỗi của nó là chuỗi gốc của tablecn, nên giữ tiếng Anh làm bản gốc thì đối chiếu ngược
+với thượng nguồn là so trực tiếp. Muốn tiếng Việt thì khai một lần bằng `DataGridLocaleProvider`,
+và nhớ truyền `locale` cho cả `useDataGrid` — thanh công cụ nằm ngoài `<DataGrid>` nên nó KHÔNG
+nhận được prop của lưới, còn hook thì bắn toast ở ngoài cây DOM của lưới nên nó không đọc được
+provider. Chi tiết: [docs/data-grid.md](docs/data-grid.md) §11. Kiểu là `Partial<>` và 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. Component chỉ có một hai chuỗi thì mở bằng **prop
 rời** thay cho cả một object — `clearLabel`, `pendingLabel`, `overflowLabel`, `placeholder`,
 `emptyText`: cùng cơ chế, chỉ khác hình dạng. ⚠ Khoá có số/đơn vị chèn vào là **HÀM**, không phải
@@ -225,7 +237,7 @@ https://design-system.comitor.ai/foundations/colors
 
 Mỗi bản publish đi qua cùng một chuỗi cổng (`prepublishOnly` nối chúng lại): typecheck → build →
 `verify:directives` → `smoke:entries` → `check:exports` → `test:nav-active` → `test:grid-contract`
-→ `test:a11y-gate` → `lint:a11y`. Những cổng đáng để người dùng gói biết là chúng tồn tại:
+→ `test:grid-render` → `test:a11y-gate` → `lint:a11y`. Những cổng đáng để người dùng gói biết là chúng tồn tại:
 
 - **`lint:a11y` — hợp đồng màu.** 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
@@ -245,9 +257,16 @@ Mỗi bản publish đi qua cùng một chuỗi cổng (`prepublishOnly` nối c
 - **`verify:directives` — ranh giới server/client.** 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), và không hằng dữ
   liệu thuần nào được kẹt trong file client (§4.2).
-- **`smoke:entries`** nạp cả 6 entry bằng Node ESM thuần, qua đúng `exports` map (§3).
+- **`smoke:entries`** nạp cả 7 entry bằng Node ESM thuần, qua đúng `exports` map (§3).
 - **`test:a11y-gate`** tự kiểm chính cổng màu (cổng còn bắt đủ không); **`test:nav-active`** khoá
   toàn bộ luật active matching của sidebar dưới dạng hàm thuần (§4.1).
+- **`test:grid-render`** render THẬT `DataGrid` bằng `react-dom/server` rồi soi HTML ra được. Nó
+  bắt đúng lớp lỗi mà mọi cổng trên đều mù, vì chúng đọc kiểu / đọc chuỗi lớp / chỉ NẠP module chứ
+  không gọi component nào: `style` inline còn mang dấu vết của hệ token repo gốc. Ca thật đã bắt
+  được lúc port — `hsl(var(--card))` là khai báo KHÔNG hợp lệ với hệ token của gói này (`--card`
+  là màu đầy đủ `#ffffff`), CSS bỏ qua rồi rơi về `transparent`, và cột ghim trong suốt.
+  ⚠ Nó KHÔNG thay cho một bộ test: mọi thứ cần DOM (gõ vào ô, chọn vùng, copy/paste, ảo hoá dòng)
+  nằm ngoài tầm với của nó.
 
 Quy ước `"use client"` của gói: đặt **per-file**, ở dòng đầu tiên, và directive được giữ nguyên
 trong `dist/` → Next.js đánh đúng ranh giới server/client. Module thuần dữ liệu (`lib/cn.ts`,

package/dist/data-grid/compose-refs.d.ts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+
+/**
+ * @see https://github.com/radix-ui/primitives/blob/main/packages/react/compose-refs/src/compose-refs.tsx
+ */
+
+type PossibleRef<T> = React.Ref<T> | undefined;
+/**
+ * A utility to compose multiple refs together
+ * Accepts callback refs and RefObject(s)
+ */
+declare function composeRefs<T>(...refs: PossibleRef<T>[]): React.RefCallback<T>;
+/**
+ * A custom hook that composes multiple refs
+ * Accepts callback refs and RefObject(s)
+ */
+declare function useComposedRefs<T>(...refs: PossibleRef<T>[]): React.RefCallback<T>;
+
+export { composeRefs, useComposedRefs };

package/dist/data-grid/compose-refs.js

@@ -0,0 +1,41 @@
+import * as React from "react";
+function setRef(ref, value) {
+  if (typeof ref === "function") {
+    return ref(value);
+  }
+  if (ref !== null && ref !== void 0) {
+    ref.current = value;
+  }
+}
+function composeRefs(...refs) {
+  return (node) => {
+    let hasCleanup = false;
+    const cleanups = refs.map((ref) => {
+      const cleanup = setRef(ref, node);
+      if (!hasCleanup && typeof cleanup === "function") {
+        hasCleanup = true;
+      }
+      return cleanup;
+    });
+    if (hasCleanup) {
+      return () => {
+        for (let i = 0; i < cleanups.length; i++) {
+          const cleanup = cleanups[i];
+          if (typeof cleanup === "function") {
+            cleanup();
+          } else {
+            setRef(refs[i], null);
+          }
+        }
+      };
+    }
+  };
+}
+function useComposedRefs(...refs) {
+  return React.useCallback(composeRefs(...refs), refs);
+}
+export {
+  composeRefs,
+  useComposedRefs
+};
+//# sourceMappingURL=compose-refs.js.map

package/dist/data-grid/compose-refs.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/data-grid/compose-refs.ts"],"sourcesContent":["/**\n * @see https://github.com/radix-ui/primitives/blob/main/packages/react/compose-refs/src/compose-refs.tsx\n */\n\nimport * as React from \"react\";\n\ntype PossibleRef<T> = React.Ref<T> | undefined;\n\n/**\n * Set a given ref to a given value\n * This utility takes care of different types of refs: callback refs and RefObject(s)\n */\nfunction setRef<T>(ref: PossibleRef<T>, value: T) {\n  if (typeof ref === \"function\") {\n    return ref(value);\n  }\n\n  if (ref !== null && ref !== undefined) {\n    ref.current = value;\n  }\n}\n\n/**\n * A utility to compose multiple refs together\n * Accepts callback refs and RefObject(s)\n */\nfunction composeRefs<T>(...refs: PossibleRef<T>[]): React.RefCallback<T> {\n  return (node) => {\n    let hasCleanup = false;\n    const cleanups = refs.map((ref) => {\n      const cleanup = setRef(ref, node);\n      if (!hasCleanup && typeof cleanup === \"function\") {\n        hasCleanup = true;\n      }\n      return cleanup;\n    });\n\n    // React <19 will log an error to the console if a callback ref returns a\n    // value. We don't use ref cleanups internally so this will only happen if a\n    // user's ref callback returns a value, which we only expect if they are\n    // using the cleanup functionality added in React 19.\n    if (hasCleanup) {\n      return () => {\n        for (let i = 0; i < cleanups.length; i++) {\n          const cleanup = cleanups[i];\n          if (typeof cleanup === \"function\") {\n            cleanup();\n          } else {\n            setRef(refs[i], null);\n          }\n        }\n      };\n    }\n  };\n}\n\n/**\n * A custom hook that composes multiple refs\n * Accepts callback refs and RefObject(s)\n */\nfunction useComposedRefs<T>(...refs: PossibleRef<T>[]): React.RefCallback<T> {\n  // biome-ignore lint/correctness/useExhaustiveDependencies: we don't want to re-run this callback when the refs change\n  return React.useCallback(composeRefs(...refs), refs);\n}\n\nexport { composeRefs, useComposedRefs };\n"],"mappings":"AAIA,YAAY,WAAW;AAQvB,SAAS,OAAU,KAAqB,OAAU;AAChD,MAAI,OAAO,QAAQ,YAAY;AAC7B,WAAO,IAAI,KAAK;AAAA,EAClB;AAEA,MAAI,QAAQ,QAAQ,QAAQ,QAAW;AACrC,QAAI,UAAU;AAAA,EAChB;AACF;AAMA,SAAS,eAAkB,MAA8C;AACvE,SAAO,CAAC,SAAS;AACf,QAAI,aAAa;AACjB,UAAM,WAAW,KAAK,IAAI,CAAC,QAAQ;AACjC,YAAM,UAAU,OAAO,KAAK,IAAI;AAChC,UAAI,CAAC,cAAc,OAAO,YAAY,YAAY;AAChD,qBAAa;AAAA,MACf;AACA,aAAO;AAAA,IACT,CAAC;AAMD,QAAI,YAAY;AACd,aAAO,MAAM;AACX,iBAAS,IAAI,GAAG,IAAI,SAAS,QAAQ,KAAK;AACxC,gBAAM,UAAU,SAAS,CAAC;AAC1B,cAAI,OAAO,YAAY,YAAY;AACjC,oBAAQ;AAAA,UACV,OAAO;AACL,mBAAO,KAAK,CAAC,GAAG,IAAI;AAAA,UACtB;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;AAMA,SAAS,mBAAsB,MAA8C;AAE3E,SAAO,MAAM,YAAY,YAAY,GAAG,IAAI,GAAG,IAAI;AACrD;","names":[]}

package/dist/data-grid/data-grid-cell-variants.d.ts

@@ -0,0 +1,15 @@
+import * as React from 'react';
+import { DataGridCellProps } from './types.js';
+import '@tanstack/react-table';
+
+declare function ShortTextCell<TData>({ cell, tableMeta, rowIndex, columnId, rowHeight, isEditing, isFocused, isSelected, isSearchMatch, isActiveSearchMatch, readOnly }: DataGridCellProps<TData>): React.JSX.Element;
+declare function LongTextCell<TData>({ cell, tableMeta, rowIndex, columnId, rowHeight, isFocused, isEditing, isSelected, isSearchMatch, isActiveSearchMatch, readOnly }: DataGridCellProps<TData>): React.JSX.Element;
+declare function NumberCell<TData>({ cell, tableMeta, rowIndex, columnId, rowHeight, isFocused, isEditing, isSelected, isSearchMatch, isActiveSearchMatch, readOnly }: DataGridCellProps<TData>): React.JSX.Element;
+declare function UrlCell<TData>({ cell, tableMeta, rowIndex, columnId, rowHeight, isEditing, isFocused, isSelected, isSearchMatch, isActiveSearchMatch, readOnly }: DataGridCellProps<TData>): React.JSX.Element;
+declare function CheckboxCell<TData>({ cell, tableMeta, rowIndex, columnId, rowHeight, isFocused, isSelected, isSearchMatch, isActiveSearchMatch, readOnly }: Omit<DataGridCellProps<TData>, "isEditing">): React.JSX.Element;
+declare function SelectCell<TData>({ cell, tableMeta, rowIndex, columnId, rowHeight, isFocused, isEditing, isSelected, isSearchMatch, isActiveSearchMatch, readOnly }: DataGridCellProps<TData>): React.JSX.Element;
+declare function MultiSelectCell<TData>({ cell, tableMeta, rowIndex, columnId, rowHeight, isFocused, isEditing, isSelected, isSearchMatch, isActiveSearchMatch, readOnly }: DataGridCellProps<TData>): React.JSX.Element;
+declare function DateCell<TData>({ cell, tableMeta, rowIndex, columnId, rowHeight, isFocused, isEditing, isSelected, isSearchMatch, isActiveSearchMatch, readOnly }: DataGridCellProps<TData>): React.JSX.Element;
+declare function FileCell<TData>({ cell, tableMeta, rowIndex, columnId, rowHeight, isFocused, isEditing, isSelected, isSearchMatch, isActiveSearchMatch, readOnly }: DataGridCellProps<TData>): React.JSX.Element;
+
+export { CheckboxCell, DateCell, FileCell, LongTextCell, MultiSelectCell, NumberCell, SelectCell, ShortTextCell, UrlCell };