@lucasvu/scope-ui 0.0.2 → 0.0.4

package/AI_SETUP.md

@@ -0,0 +1,103 @@
+# AI Setup
+
+Mục tiêu của file này là để AI của project dùng `@lucasvu/scope-ui` đúng cách, không import lung tung, không hardcode màu sai chỗ và không chọn nhầm component.
+
+Nếu project consumer đã cài package, cách nhanh nhất là chạy:
+
+```bash
+npx scope-ui-init
+```
+
+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.
+
+## 1. Import style đúng thứ tự
+
+Import package CSS trước, rồi mới import file override theme của project.
+
+```ts
+import '@lucasvu/scope-ui/styles.css'
+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
+
+Đặt file tại `src/styles/ui-theme.css`.
+
+```css
+:root {
+  --tw-primary: 12 88% 56%;
+  --tw-accent: 24 95% 52%;
+  --primary-grad-from: 24 95% 52%;
+  --primary-grad-to: 12 88% 56%;
+  --surface: rgba(255, 248, 240, 0.92);
+}
+
+.dark {
+  --tw-primary: 18 100% 62%;
+  --tw-accent: 35 100% 58%;
+  --surface: rgba(24, 24, 27, 0.82);
+}
+```
+
+Không nên override màu trực tiếp trong từng component nếu chỉ đang đổi theme.
+
+## 3. Rule cho AI của project
+
+Copy phần này vào system prompt, repo instructions, `AGENTS.md`, Cursor rules, hoặc bất kỳ chỗ nào project đang dùng để ép AI theo convention:
+
+```md
+Use `@lucasvu/scope-ui` as the default UI library.
+
+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`
+- 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
+- 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
+
+Component choice:
+- `Input` for short text
+- `Textarea` for multiline text
+- `Select` for small fixed options
+- `SearchableSelect` for larger local option sets
+- `Combobox` for type-and-pick
+- `AsyncCombobox` for remote search
+- `MultiSelect` for multi-pick
+- `Field` only for custom controls or grouped content
+- `DataTable` for tabular records
+```
+
+## 4. Runtime contract cho AI/codegen
+
+Trong code, AI có thể đọc trực tiếp:
+
+```ts
+import { uiAiManifest, uiThemeContract, uiProjectAiRules } from '@lucasvu/scope-ui'
+```
+
+- `uiAiManifest`: chọn component theo intent
+- `uiThemeContract`: biết override token nào và override ở đâu
+- `uiProjectAiRules`: rule ngắn gọn để inject vào agent của project
+
+## 5. Chỗ override theme
+
+Nếu project có app shell:
+
+- import `@lucasvu/scope-ui/styles.css` ở app entry
+- import `src/styles/ui-theme.css` ngay sau đó
+- toggle dark mode bằng class `.dark` trên `html` hoặc `body`, hoặc dùng `[data-ui-theme='dark']`
+
+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']`
+- chỉ override token trong file theme, không fork component

package/README.md

@@ -2,48 +2,31 @@
 
 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:
+## Cách dùng nhanh
 
-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:
+1. Cài package:
 
 ```bash
-npm run build
+npm install @lucasvu/scope-ui
 ```
 
-4. Kiểm tra package trước khi publish:
+2. Import global style một lần ở entry (ví dụ `main.tsx`):
 
-```bash
-npm pack --dry-run
+```ts
+import '@lucasvu/scope-ui/styles.css';
 ```
 
-5. Đăng nhập npm và publish:
+3. Nếu muốn bootstrap rule/theme cho AI trong project consumer:
 
 ```bash
-npm login
-npm publish
+npx scope-ui-init
 ```
 
-`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:
+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`.
 
-```bash
-npm install @lucasvu/scope-ui
-```
+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.
 
-2) Import global style một lần ở entry (ví dụ `main.tsx`):
-
-```ts
-import '@lucasvu/scope-ui/styles.css'
-```
-
-3) Dùng component:
+4. Dùng component:
 
 ```tsx
 import {
@@ -56,7 +39,7 @@ import {
   Field,
   Input,
   Select,
-} from '@lucasvu/scope-ui'
+} from '@lucasvu/scope-ui';
 
 export function Example() {
   return (
@@ -89,7 +72,7 @@ export function Example() {
       </CardContent>
       <Button block>Tiếp tục</Button>
     </Card>
-  )
+  );
 }
 ```
 
@@ -120,27 +103,32 @@ 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 sau khi đã cài `@lucasvu/scope-ui` để tạo `AGENTS.md` và `src/styles/ui-theme.css`
 - 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
 
 ```ts
-import { uiAiManifest, uiProjectAiRules, uiThemeContract } from '@lucasvu/scope-ui'
+import {
+  uiAiManifest,
+  uiProjectAiRules,
+  uiThemeContract,
+} 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ỗ.
 
-`AI_SETUP.md` chứa sẵn đoạn rule/prompt để copy vào settings của agent trong project.
+`AI_SETUP.md` và CLI `scope-ui-init` giúp bootstrap rule/theme cho repo consumer mà không cần copy tay.
 
 ## Theme Override
 
 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`.
 
 ```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ụ:
@@ -204,12 +192,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
@@ -237,7 +220,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
@@ -280,13 +263,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;
 };
 ```
@@ -362,7 +345,7 @@ Checkbox chỉ hiện khi truyền `rowSelection`. Không truyền thì sẽ ẩ
     selectedRowKeys,
     onChange: setSelectedRowKeys,
   }}
-/>;
+/>
 ```
 
 ### Pagination + chọn page size
@@ -400,7 +383,7 @@ const [pageSize, setPageSize] = useState(20);
   rowKey="id"
   onRowClick={(row) => console.log(row)}
   renderActions={(row) => <ActionMenu row={row} />}
-/>;
+/>
 ```
 
 ### Loading + empty
@@ -412,7 +395,7 @@ const [pageSize, setPageSize] = useState(20);
   rowKey="id"
   loading={isLoading}
   emptyText="No data"
-/>;
+/>
 ```
 
 ### Sticky header khi scroll
@@ -440,7 +423,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}
@@ -449,7 +432,7 @@ import { LineClampTooltip } from '@lucasvu/scope-ui'
   side="top"
   wrap
   portal
-/>
+/>;
 ```
 
 ## Tuỳ chỉnh theme

package/bin/scope-ui-init.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import process from 'node:process'
+
+const PACKAGE_NAME = '@lucasvu/scope-ui'
+
+function parseArgs(argv) {
+  const args = {
+    force: false,
+    agentsFile: 'AGENTS.md',
+    themeFile: 'src/styles/ui-theme.css',
+  }
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+    if (arg === '--force') {
+      args.force = true
+      continue
+    }
+    if (arg === '--agents-file') {
+      args.agentsFile = argv[index + 1] ?? args.agentsFile
+      index += 1
+      continue
+    }
+    if (arg === '--theme-file') {
+      args.themeFile = argv[index + 1] ?? args.themeFile
+      index += 1
+      continue
+    }
+    if (arg === '--help' || arg === '-h') {
+      printHelp()
+      process.exit(0)
+    }
+  }
+
+  return args
+}
+
+function printHelp() {
+  console.log(`scope-ui-init
+
+Create bootstrap files for using ${PACKAGE_NAME} with AI/codegen.
+
+Usage:
+  npx scope-ui-init
+    Run this after @lucasvu/scope-ui has been installed in the consumer project.
+
+  npx scope-ui-init --force
+  npx scope-ui-init --agents-file AGENTS.md --theme-file src/styles/ui-theme.css
+
+Options:
+  --force        overwrite existing files
+  --agents-file  target path for the generated AGENTS.md file
+  --theme-file   target path for the generated theme override file
+  --help, -h     show this help
+`)
+}
+
+function createAgentsTemplate({ themeFile }) {
+  return `# Agent Rules
+
+This repo uses \`${PACKAGE_NAME}\` as the default UI library.
+
+Primary references:
+- \`node_modules/${PACKAGE_NAME}/README.md\`
+- \`node_modules/${PACKAGE_NAME}/AI_SETUP.md\`
+- \`${themeFile}\`
+
+Always:
+- import \`${PACKAGE_NAME}/styles.css\` once at the app entry
+- import the project theme override file after the package stylesheet
+- use root exports from \`${PACKAGE_NAME}\`
+- read \`uiAiManifest\` before choosing components
+- read \`uiThemeContract\` before changing colors, surfaces, borders, or shadows
+- keep UI token-driven and theme-driven
+
+Do not:
+- import from \`MainFe\` unless the task explicitly targets a legacy screen
+- 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
+
+Component choice:
+- \`Input\` for short text
+- \`Textarea\` for multiline text
+- \`Select\` for small fixed options
+- \`SearchableSelect\` for larger local option sets
+- \`Combobox\` for type-and-pick
+- \`AsyncCombobox\` for remote search
+- \`MultiSelect\` for multi-pick
+- \`Field\` only for custom controls or grouped content
+- \`DataTable\` for tabular records
+`
+}
+
+function createThemeTemplate() {
+  return `:root {
+  /* Override only the tokens you need for the project brand. */
+  /* --tw-primary: 221.2 83.2% 53.3%; */
+  /* --tw-accent: 199 89% 48%; */
+  /* --primary-grad-from: 199 89% 48%; */
+  /* --primary-grad-to: 221.2 83.2% 53.3%; */
+  /* --surface: rgba(255, 255, 255, 0.92); */
+}
+
+.dark {
+  /* --tw-primary: 217.2 91.2% 59.8%; */
+  /* --tw-accent: 199 89% 48%; */
+  /* --surface: rgba(15, 23, 42, 0.78); */
+}
+`
+}
+
+function writeFile(targetPath, content, force) {
+  const absolutePath = resolve(process.cwd(), targetPath)
+  const alreadyExists = existsSync(absolutePath)
+
+  if (alreadyExists && !force) {
+    return { path: targetPath, status: 'skipped' }
+  }
+
+  mkdirSync(dirname(absolutePath), { recursive: true })
+  writeFileSync(absolutePath, content, 'utf8')
+  return { path: targetPath, status: alreadyExists ? 'overwritten' : 'created' }
+}
+
+const options = parseArgs(process.argv.slice(2))
+
+const agentsResult = writeFile(
+  options.agentsFile,
+  createAgentsTemplate({ themeFile: options.themeFile }),
+  options.force,
+)
+
+const themeResult = writeFile(
+  options.themeFile,
+  createThemeTemplate(),
+  options.force,
+)
+
+console.log(`Initialized ${PACKAGE_NAME}`)
+console.log(`- ${agentsResult.path}: ${agentsResult.status}`)
+console.log(`- ${themeResult.path}: ${themeResult.status}`)
+console.log('')
+console.log('Next steps:')
+console.log(`1. Import \`${PACKAGE_NAME}/styles.css\` once at your app entry.`)
+console.log(`2. Import \`${options.themeFile}\` right after the package stylesheet.`)
+console.log(`3. Let your agent read \`${options.agentsFile}\` before generating UI.`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lucasvu/scope-ui",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -14,13 +14,19 @@
     "./styles.css": "./dist/styles.css",
     "./package.json": "./package.json"
   },
+  "bin": {
+    "scope-ui-init": "./bin/scope-ui-init.mjs"
+  },
   "files": [
-    "dist"
+    "dist",
+    "bin",
+    "AI_SETUP.md"
   ],
   "scripts": {
     "build": "npm run build:js && npm run build:css",
     "build:js": "tsup",
     "build:css": "tailwindcss -c ./tailwind.config.js -i ./src/styles.css -o ./dist/styles.css --minify",
+    "init-ai": "node ./bin/scope-ui-init.mjs",
     "prepublishOnly": "npm run build"
   },
   "publishConfig": {
@@ -47,4 +53,4 @@
     "tsup": "^8.5.0",
     "typescript": "^5.8.3"
   }
-}
+}