@lucasvu/scope-ui 0.0.1

package/README.md

@@ -0,0 +1,394 @@
+# @base/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ờ.
+
+## 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ư `@your-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
+```
+
+2) Import global style một lần ở entry (ví dụ `main.tsx`):
+
+```ts
+import '@your-scope/ui/styles.css'
+```
+
+3) Dùng component:
+
+```tsx
+import { Button, Card, CardHeader, CardTitle, CardContent, DataTable, Field, Input } from '@your-scope/ui'
+
+export function Example() {
+  return (
+    <Card>
+      <CardHeader>
+        <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>
+        <Field label="Gói sử dụng">
+          <DataTable
+            data={[{ name: 'Starter', price: '$19' }]}
+            rowKey="name"
+            columns={[
+              { key: 'name', title: 'Tên', sortable: true },
+              { key: 'price', title: 'Giá' },
+            ]}
+          />
+        </Field>
+      </CardContent>
+      <Button block>Tiếp tục</Button>
+    </Card>
+  )
+}
+```
+
+## 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`)
+- 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)
+- 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)
+- Số liệu: `Stat` (label, value, delta, trend up/down/flat)
+- 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)
+
+## NumericInput
+
+`NumericInput` dùng cho các ô số cần giữ trải nghiệm nhập liệu mượt (không nhảy caret, chấp nhận trạng thái tạm như `.` hoặc `12.`), đồng thời parse/format có kiểm soát.
+
+### Public API
+
+```ts
+type NumericInputProps = {
+  value?: string | number;
+  defaultValue?: string | number;
+  onValueChange?: (raw: string) => void;
+  onNumberChange?: (num: number | null) => void;
+  mode?: 'integer' | 'decimal'; // default: 'decimal'
+  decimalScale?: number;
+  maxDecimalScale?: number;
+  min?: number;
+  max?: number;
+  allowNegative?: boolean; // default: false
+  decimalSeparator?: '.' | ',' | 'auto'; // default: 'auto'
+  formatOnBlur?: 'none' | 'trim' | 'fixed'; // default: 'trim'
+  clampOnBlur?: boolean; // default: false
+  disabled?: boolean;
+  readOnly?: boolean;
+  name?: string;
+  onBlur?: (e) => void;
+  onFocus?: (e) => void;
+  // + các input props khác: className, placeholder, ...
+};
+```
+
+### Rule chính
+
+- Luôn giữ `rawValue` theo đúng ký tự user nhập.
+- `onValueChange` luôn bắn khi user gõ.
+- `onNumberChange` trả `number` khi parse được, ngược lại trả `null`.
+- Không tự chèn dấu phân tách hàng nghìn trong lúc gõ.
+- Có hỗ trợ paste chuỗi như `1,234.50` hoặc `1.234,50` (`decimalSeparator="auto"`).
+- Với `maxDecimalScale`, input sẽ chặn vượt số chữ số phần thập phân.
+
+### Ví dụ dùng
+
+```tsx
+import { NumericInput } from '@base/ui';
+
+// 1) Integer qty
+<NumericInput
+  mode="integer"
+  min={0}
+  value={qty}
+  onValueChange={setQty}
+/>;
+
+// 2) Money
+<NumericInput
+  mode="decimal"
+  decimalScale={2}
+  maxDecimalScale={2}
+  formatOnBlur="fixed"
+  value={price}
+  onValueChange={setPrice}
+/>;
+
+// 3) Percent
+<NumericInput
+  mode="decimal"
+  decimalScale={2}
+  maxDecimalScale={2}
+  min={0}
+  max={100}
+  clampOnBlur
+  value={percent}
+  onValueChange={setPercent}
+/>;
+```
+
+## DataTable
+
+```tsx
+import type { DataTableColumn, DataTableSortState } from '@base/ui'
+```
+
+### Tối thiểu
+
+- `data`: mảng record
+- `columns`: cấu hình cột
+- `rowKey`: key của record (string/number) hoặc hàm `(record) => key`
+
+### Props chính
+
+```tsx
+type DataTableProps<T> = {
+  columns: DataTableColumn<T>[];
+  data: T[];
+  rowKey: keyof T | ((record: T) => string | number);
+  loading?: boolean;
+  emptyText?: ReactNode;
+  pagination?: {
+    page: number;
+    pageSize: number;
+    total: number;
+    onChange: (page: number) => void;
+    pageSizeOptions?: number[];
+    onPageSizeChange?: (pageSize: number) => void;
+  };
+  sort?: DataTableSortState | null;
+  onSortChange?: (sort: DataTableSortState | null) => void;
+  sortMode?: 'client' | 'server';
+  onRowClick?: (record: T) => void;
+  rowSelection?: {
+    selectedRowKeys: Array<string | number>;
+    onChange: (keys: Array<string | number>) => void;
+  };
+  renderActions?: (record: T) => ReactNode;
+  className?: string;
+};
+```
+
+### Cấu hình cộ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%')
+  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
+  sortValue?: (record) => string | number | Date | null;
+};
+```
+
+### Độ rộng cột (width)
+
+- Nếu cần giữ độ rộng cố định cho một cột, đặt `width` trong cấu hình cột.
+- Cột có `width` sẽ ưu tiên theo giá trị này; các cột còn lại vẫn tự đo theo nội dung.
+
+```tsx
+const columns: DataTableColumn<User>[] = [
+  { key: 'name', title: 'Name', dataIndex: 'name', width: 180 },
+  { key: 'email', title: 'Email', dataIndex: 'email' },
+];
+```
+
+### Bật/tắt nhanh
+
+- Sort: set `sortable: true` (hoặc `sorter`/`sortValue`); muốn tắt hẳn thì `sortable: false`.
+- Checkbox: truyền `rowSelection` để hiện; bỏ `rowSelection` để ẩn.
+- Actions column: truyền `renderActions` để hiện; bỏ `renderActions` để ẩn.
+- Pagination: truyền `pagination` để hiện; bỏ `pagination` để ẩn.
+- Page size dropdown: truyền `pagination.onPageSizeChange` (kèm `pageSizeOptions` nếu cần).
+
+### Sort (client)
+
+Chỉ cột có `sortable`, `sorter`, hoặc `sortValue` mới hiện icon sort. Nếu muốn tắt hẳn, đặt `sortable: false`. Thứ tự click: `asc` -> `desc` -> bỏ sort.
+
+```tsx
+const columns: DataTableColumn<User>[] = [
+  { key: 'name', title: 'Name', dataIndex: 'name', sortable: true },
+  {
+    key: 'createdAt',
+    title: 'Created',
+    dataIndex: 'createdAt',
+    sortValue: (row) => new Date(row.createdAt),
+  },
+  {
+    key: 'status',
+    title: 'Status',
+    sorter: (a, b) => a.status.localeCompare(b.status),
+  },
+];
+```
+
+### Sort (server)
+
+Khi gọi API để sort/paginate, dùng `sortMode="server"` để DataTable không tự sort dữ liệu. `onSortChange` trả về `{ key, direction } | null`, bạn tự gọi API và set data mới.
+
+```tsx
+const [sort, setSort] = useState<DataTableSortState | null>(null);
+
+<DataTable
+  data={rows}
+  columns={columns}
+  rowKey="id"
+  sort={sort}
+  sortMode="server"
+  onSortChange={setSort}
+/>;
+```
+
+### Checkbox chọn dòng
+
+Checkbox chỉ hiện khi truyền `rowSelection`. Không truyền thì sẽ ẩn.
+
+```tsx
+<DataTable
+  data={rows}
+  columns={columns}
+  rowKey="id"
+  rowSelection={{
+    selectedRowKeys,
+    onChange: setSelectedRowKeys,
+  }}
+/>;
+```
+
+### Pagination + chọn page size
+
+Nếu truyền `onPageSizeChange`, DataTable sẽ hiện dropdown chọn số dòng mỗi trang.
+
+```tsx
+const [page, setPage] = useState(1);
+const [pageSize, setPageSize] = useState(20);
+
+<DataTable
+  data={rows}
+  columns={columns}
+  rowKey="id"
+  pagination={{
+    page,
+    pageSize,
+    total,
+    onChange: setPage,
+    pageSizeOptions: [10, 20, 50, 100],
+    onPageSizeChange: (size) => {
+      setPageSize(size);
+      setPage(1);
+    },
+  }}
+/>;
+```
+
+### Actions + click row
+
+```tsx
+<DataTable
+  data={rows}
+  columns={columns}
+  rowKey="id"
+  onRowClick={(row) => console.log(row)}
+  renderActions={(row) => <ActionMenu row={row} />}
+/>;
+```
+
+### Loading + empty
+
+```tsx
+<DataTable
+  data={rows}
+  columns={columns}
+  rowKey="id"
+  loading={isLoading}
+  emptyText="No data"
+/>;
+```
+
+### Sticky header khi scroll
+
+Nếu muốn header dính khi scroll trang, không đặt `overflow` ở container cha. Nếu muốn scroll trong bảng, đặt `max-height` + `overflow-auto` cho DataTable.
+
+```tsx
+<DataTable className="max-h-[60vh] overflow-auto" ... />
+```
+
+### Scroll ngang trên màn nhỏ
+
+DataTable tự hỗ trợ scroll ngang khi nội dung vượt chiều rộng (đặc biệt trên màn nhỏ). Không cần cấu hình thêm.
+
+### Lưu ý
+
+- `rowKey` phải ổn định và unique, đặc biệt khi dùng `rowSelection`.
+- Nếu truyền `sort` (controlled), bạn cần cập nhật lại state trong `onSortChange`.
+- `sortMode="server"` chỉ đổi trạng thái UI, dữ liệu phải tự fetch/sort từ API.
+- `pagination.onChange` dùng page bắt đầu từ 1.
+- Dropdown page size chỉ hiện khi có `pagination.onPageSizeChange`.
+
+## LineClampTooltip
+
+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'
+
+<LineClampTooltip
+  text={record.apiEndpoint}
+  lineClamp={3}
+  className="w-[320px]"
+  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-*`).
+- 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
+
+- Import `@base/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`.