@lucasvu/scope-ui 0.0.3 → 0.0.5

package/AI_SETUP.md

@@ -5,10 +5,13 @@ Mục tiêu của file này là để AI của project dùng `@lucasvu/scope-ui`
 Nếu project consumer đã cài package, cách nhanh nhất là chạy:
 
 ```bash
-npx scope-ui-init
+npx scope-ui-init --list-themes
+npx scope-ui-init --theme forest
 ```
 
-CLI này sẽ tạo `AGENTS.md` và `src/styles/ui-theme.css` theo đúng convention bên dưới.
+Nếu chưa cài `@lucasvu/scope-ui`, lệnh trên sẽ báo `E404` vì npm sẽ cố tải package tên `scope-ui-init`.
+
+CLI này sẽ tạo `AGENTS.md` và `src/styles/ui-theme.css` theo đúng convention bên dưới. Nếu không truyền `--theme`, preset mặc định là `ocean`.
 
 ## 1. Import style đúng thứ tự
 
@@ -21,10 +24,19 @@ import './styles/ui-theme.css'
 
 `ui-theme.css` nên là nơi duy nhất override màu, surface, border, shadow và gradient của thư viện.
 
-## 2. Tạo file theme của project
+## 2. Chọn preset theme của project
 
 Đặt file tại `src/styles/ui-theme.css`.
 
+Dùng `--list-themes` để xem preset được duyệt, rồi generate preset đã chọn:
+
+```bash
+npx scope-ui-init --list-themes
+npx scope-ui-init --theme graphite
+```
+
+File generate ra sẽ là source of truth cho palette, surface, radius và shadow của project. Agent phải bám vào file này thay vì tự nghĩ màu mới.
+
 ```css
 :root {
   --tw-primary: 12 88% 56%;
@@ -54,11 +66,13 @@ Always:
 - import `@lucasvu/scope-ui/styles.css` once at the app entry
 - import the project theme override file after the package stylesheet
 - use root exports from `@lucasvu/scope-ui`
+- stay inside the approved preset declared by `src/styles/ui-theme.css`
 - read `uiAiManifest` to choose the right component by intent
 - read `uiThemeContract` before changing colors, surfaces, borders, or shadows
 
 Do not:
 - import from `MainFe` unless the task explicitly targets a legacy screen
+- invent a second palette outside the preset file
 - hardcode brand colors inside page components when a theme token already exists
 - create duplicate Button/Input/Select wrappers unless a project-specific behavior is required
 
@@ -79,11 +93,12 @@ Component choice:
 Trong code, AI có thể đọc trực tiếp:
 
 ```ts
-import { uiAiManifest, uiThemeContract, uiProjectAiRules } from '@lucasvu/scope-ui'
+import { uiAiManifest, uiThemeContract, uiThemePresets, uiProjectAiRules } from '@lucasvu/scope-ui'
 ```
 
 - `uiAiManifest`: chọn component theo intent
 - `uiThemeContract`: biết override token nào và override ở đâu
+- `uiThemePresets`: danh sách preset được duyệt để nhiều project dùng chung một visual language
 - `uiProjectAiRules`: rule ngắn gọn để inject vào agent của project
 
 ## 5. Chỗ override theme
@@ -98,4 +113,5 @@ Nếu project có nhiều brand/theme:
 
 - giữ `:root` là theme mặc định
 - tạo selector như `[data-ui-theme='brand-a']`, `[data-ui-theme='brand-b']`
+- vẫn nên xuất phát từ một preset duyệt sẵn rồi mới override token cần thiết
 - chỉ override token trong file theme, không fork component

package/README.md

@@ -2,56 +2,32 @@
 
 Bộ component phong cách **shadcn** dùng chung cho các app/micro-frontend trong workspace. Tất cả đều là React component thuần, kèm sẵn theme tối và hiệu ứng kính mờ.
 
-## Publish lên npm
-
-Nếu muốn publish public để người khác chỉ cần cài và import:
-
-1. Đổi `name` trong `package.json` sang package name hoặc scope bạn thực sự sở hữu trên npm.
-2. Chạy `npm install` để cài thêm tool build mới nếu máy chưa có lockfile/deps tương ứng.
-3. Build package:
-
-```bash
-npm run build
-```
-
-4. Kiểm tra package trước khi publish:
-
-```bash
-npm pack --dry-run
-```
-
-5. Đăng nhập npm và publish:
-
-```bash
-npm login
-npm publish
-```
-
-`publishConfig.access: public` đã được bật sẵn, nên với package dạng scope như `@lucasvu/scope-ui` không cần nhớ thêm `--access public`.
-
 ## Cách dùng nhanh
 
-1) Cài package:
+1. Cài package:
 
 ```bash
 npm install @lucasvu/scope-ui
 ```
 
-2) Import global style một lần ở entry (ví dụ `main.tsx`):
+2. Import global style một lần ở entry (ví dụ `main.tsx`):
 
 ```ts
-import '@lucasvu/scope-ui/styles.css'
+import '@lucasvu/scope-ui/styles.css';
 ```
 
-3) Nếu muốn bootstrap rule/theme cho AI trong project consumer:
+3. Nếu muốn bootstrap rule/theme cho AI trong project consumer:
 
 ```bash
-npx scope-ui-init
+npx scope-ui-init --list-themes
+npx scope-ui-init --theme sunset
 ```
 
-Lệnh này sẽ tạo `AGENTS.md` và `src/styles/ui-theme.css` trong repo hiện tại. Dùng `--force` nếu muốn overwrite file đã tồn tại.
+Lưu ý: lệnh này chỉ chạy được sau khi project đã cài `@lucasvu/scope-ui`. Nếu chưa cài package, `npx` sẽ đi tìm một package riêng tên `scope-ui-init` trên npm và báo `E404`.
 
-4) Dùng component:
+Lệnh này sẽ tạo `AGENTS.md` và `src/styles/ui-theme.css` trong repo hiện tại theo preset đã chọn. Nếu không truyền `--theme`, preset mặc định là `ocean`. Dùng `--force` nếu muốn overwrite file đã tồn tại.
+
+4. Dùng component:
 
 ```tsx
 import {
@@ -64,7 +40,7 @@ import {
   Field,
   Input,
   Select,
-} from '@lucasvu/scope-ui'
+} from '@lucasvu/scope-ui';
 
 export function Example() {
   return (
@@ -97,7 +73,7 @@ export function Example() {
       </CardContent>
       <Button block>Tiếp tục</Button>
     </Card>
-  )
+  );
 }
 ```
 
@@ -128,18 +104,27 @@ Nếu muốn AI render UI đúng và ổn định theo thư viện này, đừng
 
 - Import CSS global một lần: `@lucasvu/scope-ui/styles.css`
 - Import file theme override của project ngay sau package CSS, ví dụ `./styles/ui-theme.css`
-- Chạy `npx scope-ui-init` ở project consumer để tạo `AGENTS.md` và `src/styles/ui-theme.css`
+- Chạy `npx scope-ui-init --list-themes` để xem preset được duyệt
+- Chạy `npx scope-ui-init --theme <preset>` ở project consumer sau khi đã cài `@lucasvu/scope-ui` để tạo `AGENTS.md` và `src/styles/ui-theme.css`
+- Khoá project vào một preset thay vì tự bịa palette mới cho từng page
 - Chỉ dùng các component canonical ở root package; tránh `MainFe` nếu không phải legacy screen
 - Cho agent đọc `uiAiManifest` để biết component nào dùng cho intent nào, props quan trọng là gì, và khi nào không nên dùng
-- Cho agent đọc `uiThemeContract` để biết màu/token phải override ở đâu
+- Cho agent đọc `uiThemeContract` và `uiThemePresets` để biết danh sách preset và token nào được phép override
 
 ```ts
-import { uiAiManifest, uiProjectAiRules, uiThemeContract } from '@lucasvu/scope-ui'
+import {
+  uiAiManifest,
+  uiProjectAiRules,
+  uiThemeContract,
+  uiThemePresets,
+} from '@lucasvu/scope-ui';
 ```
 
 `uiAiManifest` mô tả luật chọn component theo intent như: text input, textarea, fixed select, searchable select, async combobox, multi select, data table, alert, card và field wrapper.
 
-`uiThemeContract` mô tả token màu, surface, border, shadow, gradient và selector theme (`:root`, `.dark`, `[data-ui-theme='*']`) để AI không hardcode màu sai chỗ.
+`uiThemeContract` mô tả token màu, surface, border, shadow, radius, gradient và selector theme (`:root`, `.dark`, `[data-ui-theme='*']`) để AI không hardcode màu sai chỗ.
+
+`uiThemePresets` là danh sách preset được duyệt sẵn để nhiều project có thể chọn cùng một visual language mà không cần tự dựng theme từ đầu.
 
 `AI_SETUP.md` và CLI `scope-ui-init` giúp bootstrap rule/theme cho repo consumer mà không cần copy tay.
 
@@ -147,9 +132,16 @@ import { uiAiManifest, uiProjectAiRules, uiThemeContract } from '@lucasvu/scope-
 
 Nên để toàn bộ override theme của project vào một file riêng, ví dụ `src/styles/ui-theme.css`, rồi import file này sau `@lucasvu/scope-ui/styles.css`.
 
+Cách nhanh nhất là generate file này từ preset:
+
+```bash
+npx scope-ui-init --list-themes
+npx scope-ui-init --theme ocean
+```
+
 ```ts
-import '@lucasvu/scope-ui/styles.css'
-import './styles/ui-theme.css'
+import '@lucasvu/scope-ui/styles.css';
+import './styles/ui-theme.css';
 ```
 
 Ví dụ:
@@ -213,12 +205,7 @@ type NumericInputProps = {
 import { NumericInput } from '@lucasvu/scope-ui';
 
 // 1) Integer qty
-<NumericInput
-  mode="integer"
-  min={0}
-  value={qty}
-  onValueChange={setQty}
-/>;
+<NumericInput mode="integer" min={0} value={qty} onValueChange={setQty} />;
 
 // 2) Money
 <NumericInput
@@ -246,7 +233,7 @@ import { NumericInput } from '@lucasvu/scope-ui';
 ## DataTable
 
 ```tsx
-import type { DataTableColumn, DataTableSortState } from '@lucasvu/scope-ui'
+import type { DataTableColumn, DataTableSortState } from '@lucasvu/scope-ui';
 ```
 
 ### Tối thiểu
@@ -289,13 +276,13 @@ type DataTableProps<T> = {
 
 ```tsx
 type DataTableColumn<T> = {
-  key: string;                 // khóa duy nhất của cột
-  title: ReactNode;            // tiêu đề hiển thị ở header
-  dataIndex?: keyof T;         // map dữ liệu (mặc định lấy theo key)
-  width?: number | string;     // độ rộng ưu tiên (vd: 180, '180px', '20%')
+  key: string; // khóa duy nhất của cột
+  title: ReactNode; // tiêu đề hiển thị ở header
+  dataIndex?: keyof T; // map dữ liệu (mặc định lấy theo key)
+  width?: number | string; // độ rộng ưu tiên (vd: 180, '180px', '20%')
   render?: (value, record, index) => ReactNode; // custom cell
-  sortable?: boolean;          // bật/tắt sort cho cột (ưu tiên cao nhất)
-  sorter?: (a, b) => number;   // so sánh asc/desc
+  sortable?: boolean; // bật/tắt sort cho cột (ưu tiên cao nhất)
+  sorter?: (a, b) => number; // so sánh asc/desc
   sortValue?: (record) => string | number | Date | null;
 };
 ```
@@ -371,7 +358,7 @@ Checkbox chỉ hiện khi truyền `rowSelection`. Không truyền thì sẽ ẩ
     selectedRowKeys,
     onChange: setSelectedRowKeys,
   }}
-/>;
+/>
 ```
 
 ### Pagination + chọn page size
@@ -409,7 +396,7 @@ const [pageSize, setPageSize] = useState(20);
   rowKey="id"
   onRowClick={(row) => console.log(row)}
   renderActions={(row) => <ActionMenu row={row} />}
-/>;
+/>
 ```
 
 ### Loading + empty
@@ -421,7 +408,7 @@ const [pageSize, setPageSize] = useState(20);
   rowKey="id"
   loading={isLoading}
   emptyText="No data"
-/>;
+/>
 ```
 
 ### Sticky header khi scroll
@@ -449,7 +436,7 @@ DataTable tự hỗ trợ scroll ngang khi nội dung vượt chiều rộng (đ
 Dùng khi cần hiển thị tối đa N dòng, nếu text bị cắt sẽ hiện tooltip đầy đủ khi hover.
 
 ```tsx
-import { LineClampTooltip } from '@lucasvu/scope-ui'
+import { LineClampTooltip } from '@lucasvu/scope-ui';
 
 <LineClampTooltip
   text={record.apiEndpoint}
@@ -458,12 +445,13 @@ import { LineClampTooltip } from '@lucasvu/scope-ui'
   side="top"
   wrap
   portal
-/>
+/>;
 ```
 
 ## Tuỳ chỉnh theme
 
-- Sửa tông màu, radius, shadow trong `packages/ui/src/styles.css` (biến `--primary`, `--radius`, `--shadow-*`).
+- Ưu tiên chọn một preset duyệt sẵn qua `npx scope-ui-init --theme <preset>` để giữ UI đồng bộ giữa các project.
+- Nếu cần tinh chỉnh thêm, chỉ sửa token trong `src/styles/ui-theme.css`, không restyle từng component riêng lẻ.
 - Các lớp `ui-*` đã được namespaced để tránh va chạm với CSS hiện tại.
 
 ## Gợi ý tích hợp