@lucasvu/scope-ui 0.0.1 → 0.0.2

package/README.md

@@ -1,4 +1,4 @@
-# @base/ui
+# @lucasvu/scope-ui
 
 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ờ.
 
@@ -27,26 +27,36 @@ npm login
 npm publish
 ```
 
-`publishConfig.access: public` đã được bật sẵn, nên với package dạng scope như `@your-scope/ui` không cần nhớ thêm `--access public`.
+`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:
 
 ```bash
-npm install @your-scope/ui
+npm install @lucasvu/scope-ui
 ```
 
 2) Import global style một lần ở entry (ví dụ `main.tsx`):
 
 ```ts
-import '@your-scope/ui/styles.css'
+import '@lucasvu/scope-ui/styles.css'
 ```
 
 3) Dùng component:
 
 ```tsx
-import { Button, Card, CardHeader, CardTitle, CardContent, DataTable, Field, Input } from '@your-scope/ui'
+import {
+  Button,
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+  DataTable,
+  Field,
+  Input,
+  Select,
+} from '@lucasvu/scope-ui'
 
 export function Example() {
   return (
@@ -55,10 +65,18 @@ export function Example() {
         <CardTitle>Form đăng ký</CardTitle>
       </CardHeader>
       <CardContent className="ui-grid ui-grid--two">
-        <Field label="Email" required>
-          <Input type="email" placeholder="you@example.com" />
+        <Field label="Email" required htmlFor="email">
+          <Input id="email" type="email" placeholder="you@example.com" />
         </Field>
-        <Field label="Gói sử dụng">
+        <Select
+          label="Gói sử dụng"
+          placeholder="Chọn gói"
+          options={[
+            { label: 'Starter', value: 'starter' },
+            { label: 'Pro', value: 'pro' },
+          ]}
+        />
+        <Field label="Bảng giá theo gói" helperText="Ví dụ DataTable cơ bản">
           <DataTable
             data={[{ name: 'Starter', price: '$19' }]}
             rowKey="name"
@@ -77,10 +95,10 @@ export function Example() {
 
 ## Thành phần có sẵn
 
-- Nút: `Button` (variant `primary | secondary | ghost | outline | destructive | link | accent`, size `sm | md | lg | icon`, hỗ trợ `block`)
+- Nút: `Button` (variant `default | secondary | ghost | outline | destructive | link | confirm | create`, size `sm | md | lg | icon`, hỗ trợ `block`)
 - Badge: `Badge` (solid, outline, success, warning)
 - Thẻ: `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`
-- Form: `Field`, `Label`, `Input`, `Select`, `Textarea`, `Combobox` (searchable input + dropdown giống shadcn)
+- Form: `Form`, `Field`, `Item`, `Label`, `Control`, `Description`, `Message`, `Input`, `Textarea`, `Select`, `SearchableSelect`, `Combobox`, `AsyncCombobox`, `MultiSelect`
 - Numeric: `NumericInput` (hỗ trợ integer/decimal, parse an toàn, format/clamp khi blur, dùng cho price/amount)
 - Tabs: `Tabs` với mảng `items` `{ value, label, content, badge? }`
 - Thông báo: `Alert` (tone info/success/warning/danger)
@@ -88,7 +106,58 @@ export function Example() {
 - Bảng: `DataTable<T>` với `columns` và `render` tuỳ biến
 - Tooltip: `Tooltip`, `OverflowTooltip`, `LineClampTooltip` (hiển thị tooltip khi bị cắt theo dòng)
 - Lưới tiện dụng: class `ui-grid`, `ui-grid--two`, `ui-grid--three` để xếp block nhanh
-- `Showcase`: một view mẫu kết hợp stats + tabs + form + bảng (import từ `@base/ui` để demo)
+- `MainFe`: nhóm component dành cho main frontend cũ vẫn được export riêng để tương thích ngược
+
+## Ghi chú DX
+
+- `Input`, `Textarea`, `Select`, `SearchableSelect`, `Combobox` đã hỗ trợ trực tiếp `label`, `helperText`, `errorMessage`.
+- `Field` phù hợp khi bạn cần bọc một control custom hoặc gom nhiều control dưới cùng một nhãn.
+- Nếu bạn đổi tên package trước khi publish, thay `@lucasvu/scope-ui` trong các ví dụ bằng package name mới.
+
+## Dùng cho AI/codegen
+
+Nếu muốn AI render UI đúng và ổn định theo thư viện này, đừng chỉ đưa mỗi tên package. Hãy để agent bám vào một surface chuẩn:
+
+- 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ỉ 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'
+```
+
+`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.
+
+## 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'
+```
+
+Ví dụ:
+
+```css
+:root {
+  --tw-primary: 12 88% 56%;
+  --tw-accent: 24 95% 52%;
+  --primary-grad-from: 24 95% 52%;
+  --primary-grad-to: 12 88% 56%;
+}
+
+.dark {
+  --tw-primary: 18 100% 62%;
+  --tw-accent: 35 100% 58%;
+}
+```
 
 ## NumericInput
 
@@ -132,7 +201,7 @@ type NumericInputProps = {
 ### Ví dụ dùng
 
 ```tsx
-import { NumericInput } from '@base/ui';
+import { NumericInput } from '@lucasvu/scope-ui';
 
 // 1) Integer qty
 <NumericInput
@@ -168,7 +237,7 @@ import { NumericInput } from '@base/ui';
 ## DataTable
 
 ```tsx
-import type { DataTableColumn, DataTableSortState } from '@base/ui'
+import type { DataTableColumn, DataTableSortState } from '@lucasvu/scope-ui'
 ```
 
 ### Tối thiểu
@@ -371,7 +440,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 '@base/ui'
+import { LineClampTooltip } from '@lucasvu/scope-ui'
 
 <LineClampTooltip
   text={record.apiEndpoint}
@@ -390,5 +459,5 @@ import { LineClampTooltip } from '@base/ui'
 
 ## Gợi ý tích hợp
 
-- Import `@base/ui/styles.css` ở host để các remote có thể tái sử dụng cùng theme.
+- Import `@lucasvu/scope-ui/styles.css` ở host để các remote có thể tái sử dụng cùng theme.
 - Nếu muốn kết hợp với Tailwind/shadcn gốc, giữ nguyên class `ui-*` và thêm `content` trỏ tới `packages/ui/src/**/*` trong `tailwind.config`.