shared-design-system 1.6.0 → 1.8.0

package/README.md

@@ -1,258 +1,153 @@
-# Shared Design System
-
-Bộ thư viện thành phần giao diện dùng chung (Common Components) dành cho kiến trúc Microfrontend Portal.
-
-> **v1.4.0** — Toàn bộ 21 component đã được migrate sang **TypeScript** với strict prop interfaces và full IntelliSense support.
-
-## 🚀 Cài đặt
-
-Thư viện này được quản lý như một package nội bộ trong monorepo. Các MFE có thể sử dụng bằng cách import trực tiếp:
-
-```typescript
-// Import component + type
-import { Button, type ButtonProps } from 'shared-design-system';
-import { Card, Badge, tokens } from 'shared-design-system';
-```
-
-## 🎨 Design Tokens
-
-Thư viện sử dụng hệ thống Design Tokens tập trung tại `src/tokens.ts`. Bạn nên sử dụng các token này thay vì mã màu hardcode để đảm bảo tính nhất quán.
-
-```typescript
-import { tokens, type DesignTokens } from 'shared-design-system';
-
-const myStyle = {
-  color: tokens.color.primary,
-  padding: tokens.spacing['4'],
-  borderRadius: tokens.radius.md
-};
-```
-
-## 🧱 Các thành phần chính
-
-### 1. Button
-Thành phần nút bấm đa năng với các biến thể: `primary`, `secondary`, `danger`, `ghost`.
-
-```jsx
-<Button variant="primary" onClick={handleClick}>Xác nhận</Button>
-<Button variant="ghost" size="sm">Hủy</Button>
-```
-
-### 2. Badge
-Dùng để hiển thị trạng thái hoặc nhãn dán. Các variant: `success`, `warning`, `danger`, `info`, `slate`.
-
-```jsx
-<Badge variant="success">Hoàn thành</Badge>
-<Badge variant="warning">Chờ duyệt</Badge>
-```
-
-### 3. Form Components
-Bộ công cụ nhập liệu đồng bộ: `Input`, `Textarea`, `Select`, `Checkbox`.
-
-```jsx
-<Input label="Họ và tên" placeholder="Nhập tên..." required />
-<Select label="Phòng ban">
-  <option value="IT">Công nghệ thông tin</option>
-  <option value="HR">Nhân sự</option>
-</Select>
-```
-
-### 4. Card
-Thành phần container dùng để nhóm nội dung. Hỗ trợ `title`, `subtitle` và `footer`.
-
-```jsx
-<Card title="Thông tin cá nhân" subtitle="Chi tiết hồ sơ nhân viên">
-  <Text>Thông tin bên trong card...</Text>
-</Card>
-```
-
-### 5. Typography
-Enforce font types và hierarchy: `Heading`, `Text`, `SectionHeader`.
-
-```jsx
-<Heading level={2}>Tiêu đề lớn</Heading>
-<Text size="sm" color="muted">Ghi chú nhỏ</Text>
-<SectionHeader title="Thông tin nghiệp vụ" />
-```
-
-### 6. ReadOnlyField
-Sử dụng trong các màn hình chi tiết để hiển thị dữ liệu ở chế độ chỉ đọc một cách chuyên nghiệp.
-
-```jsx
-<ReadOnlyField label="Mã yêu cầu" value="RQ-2024-001" />
-```
-
-### 7. LoadingSpinner
-Animation quay đều sử dụng màu thương hiệu để biểu thị trạng thái đang tải.
-
-```jsx
-<LoadingSpinner size="md" />
-```
-
----
-
-## 🌟 Thành phần nâng cao (Phase 2 - Cảm hứng từ MUI)
-
-### 8. Avatar
-Hiển thị ảnh đại diện hoặc chữ cái đầu. Hỗ trợ nhiều kích thước (`xs` đến `xl`) và hình dạng (`circle`, `rounded`, `square`).
-
-```jsx
-<Avatar src="/path/to/img.jpg" size="lg" />
-<Avatar variant="rounded">JD</Avatar>
-```
-
-### 9. Switch
-Nút gạt bật/tắt hiện đại thay thế cho Checkbox.
-
-```jsx
-<Switch checked={isActive} onChange={toggle} label="Kích hoạt tính năng" />
-```
-
-### 10. Tabs & Tab
-Hệ thống chuyển đổi nội dung dạng tab. Hỗ trợ variant `standard` và `pills`.
-
-```jsx
-<Tabs value={tabIndex} onChange={setTabIndex}>
-  <Tab value={0} label="Tổng quan" icon={<HomeIcon />} />
-  <Tab value={1} label="Lịch sử" />
-</Tabs>
-```
-
-### 11. Breadcrumbs
-Định vị vị trí trong cấu trúc trang.
-
-```jsx
-<Breadcrumbs items={[
-  { label: 'Trang chủ', onClick: goHome },
-  { label: 'Cài đặt', onClick: goSettings },
-  { label: 'Thông tin cá nhân' }
-]} />
-```
-
-### 12. Skeleton
-Hiệu ứng placeholder khi đang tải dữ liệu.
-
-```jsx
-<Skeleton variant="circle" width="40px" height="40px" />
-<Skeleton variant="rectangular" height="200px" />
-<Skeleton variant="text" width="60%" />
-```
-
-### 13. Tooltip
-Hiển thị chú thích khi di chuột. Hỗ trợ 4 hướng: `top`, `bottom`, `left`, `right`.
-
-```jsx
-<Tooltip title="Xóa bản ghi này" position="top">
-  <Button variant="danger">Xóa</Button>
-</Tooltip>
-```
-
-### 14. Divider
-Đường kẻ phân tách nội dung.
-
-```jsx
-<Divider orientation="horizontal" margin="lg" />
-```
-
----
-
-## 🚀 Tính năng mở rộng (Phase 3 - Robust System)
-
-### 15. Stack
-Công cụ quản lý bố cục và khoảng cách tự động.
-
-```jsx
-<Stack direction="row" spacing="md" align="center">
-  <Button>Lưu</Button>
-  <Button variant="ghost">Hủy</Button>
-</Stack>
-```
-
-### 16. Alert
-Thanh thông báo theo mức độ nghiêm trọng: `success`, `info`, `warning`, `error`.
-
-```jsx
-<Alert severity="success" title="Thành công">Dữ liệu đã được lưu.</Alert>
-<Alert severity="error">Có lỗi xảy ra, vui lòng thử lại.</Alert>
-```
-
-### 17. Tag/Chip
-Nhãn dán cho dữ liệu, hỗ trợ nút đóng (close).
-
-```jsx
-<Tag color="primary" variant="solid">Mới</Tag>
-<Tag color="danger" onClose={handleDelete}>Hết hạn</Tag>
-```
-
-### 18. Progress
-Thanh tiến trình dạng đường thẳng (Linear Progress).
-
-```jsx
-<Progress value={75} showLabel color="success" />
-```
-
-### 19. Steps
-Thanh điều hướng quy trình (Workflow). Hỗ trợ chiều dọc và chiều ngang.
-
-```jsx
-<Steps 
-  current={1} 
-  items={[
-    { title: 'Khởi tạo', description: 'User gửi yêu cầu' },
-    { title: 'Phê duyệt', description: 'Đang chờ quản lý' },
-    { title: 'Hoàn tất' }
-  ]} 
-/>
-```
-
-### 20. Table (Styled)
-Bộ thành phần xây dựng bảng dữ liệu chuyên nghiệp.
-
-```jsx
-<TableContainer>
-  <THead>
-    <TR>
-      <TH>Họ Tên</TH>
-      <TH>Trạng Thái</TH>
-    </TR>
-  </THead>
-  <TBody>
-    <TR>
-      <TD>Nguyễn Văn A</TD>
-      <TD><Badge variant="success">Active</Badge></TD>
-    </TR>
-  </TBody>
-</TableContainer>
-```
-
-### 21. Radio & RadioGroup
-Lựa chọn duy nhất trong danh sách.
-
-```jsx
-<RadioGroup direction="row">
-  <Radio name="gender" value="male" label="Nam" checked />
-  <Radio name="gender" value="female" label="Nữ" />
-</RadioGroup>
-```
-
-## 🛠 Nguyên tắc phát triển
-
-1. **Tokens First**: Luôn kiểm tra `src/tokens.ts` trước khi thêm giá trị mới.
-2. **Stateless**: Giữ component đơn giản nhất có thể, chỉ xử lý UI và nhận data qua props.
-3. **Prefixing**: Khi kết hợp với Tailwind trong từng MFE, hãy sử dụng prefix tương ứng của MFE đó để tránh xung đột style với Portal.
-4. **Type-safe**: Mỗi component có Props interface riêng. Luôn import type khi chỉ cần dùng cho annotation.
-
-## 📦 Build & Publish
-
-```bash
-# Type-check
-npm run typecheck
-
-# Build ra dist/ (tự động chạy khi publish)
-npm run build
-
-# Publish (tự động chạy typecheck + build trước)
-npm publish
-```
-
-> **Lưu ý:** File `dist/` được generate tự động, không commit vào git.
+# Shared Design System
+
+Bộ thư viện thành phần giao diện dùng chung (Common Components) và hệ thống Design Tokens dành cho kiến trúc Microfrontend Portal.
+
+> **Current Version: v1.7.0** — Hệ thống đã được nâng cấp toàn diện với TypeScript, Tailwind Preset và 23+ components sẵn sàng cho sản xuất.
+
+---
+
+## 🚀 Cài đặt
+
+Thư viện này được quản lý như một package nội bộ trong monorepo. Bạn có thể sử dụng trực tiếp trong các ứng dụng MFE:
+
+```bash
+# Trong package.json của MFE
+"dependencies": {
+  "shared-design-system": "workspace:*"
+}
+```
+
+Dùng trong code:
+```typescript
+import { Button, Card, tokens } from 'shared-design-system';
+```
+
+---
+
+## 🎨 Tích hợp Tailwind CSS
+
+Thư viện cung cấp một Tailwind Preset để đồng bộ hóa bảng màu và cấu hình font.
+
+### 1. Cấu hình `tailwind.config.ts`
+Trong project MFE của bạn, hãy import và sử dụng preset:
+
+```typescript
+import type { Config } from 'tailwindcss';
+import sharedPreset from 'shared-design-system/tailwind.preset';
+
+const config: Config = {
+  presets: [sharedPreset],
+  content: [
+    "./src/**/*.{js,ts,jsx,tsx}",
+    // Quan trọng: Thêm đường dẫn tới file source của shared-design-system để Tailwind scan classes
+    "./node_modules/shared-design-system/src/components/**/*.{js,ts,jsx,tsx}"
+  ],
+  theme: {
+    extend: {
+      // Các tùy chỉnh riêng cho MFE của bạn
+    },
+  },
+  plugins: [],
+};
+
+export default config;
+```
+
+---
+
+## 🧱 Hệ thống Thành phần (Components)
+
+### 🔹 Cơ bản (Basic Elements)
+*   **Button**: Nút bấm đa năng (`primary`, `secondary`, `danger`, `ghost`).
+*   **Badge**: Nhãn trạng thái (`success`, `warning`, `danger`, `info`).
+*   **Typography**: Hệ thống phân cấp chữ (`Heading`, `Text`, `SectionHeader`).
+*   **LoadingSpinner**: Hiệu ứng xoay khi đang tải dữ liệu.
+*   **Divider**: Đường kẻ phân tách nội dung.
+*   **Progress**: Thanh tiến trình (Linear Progress).
+
+### 🔹 Nhập liệu (Form & Inputs)
+*   **Input / Textarea**: Ô nhập văn bản hỗ trợ label và validation state.
+*   **Select**: Menu lựa chọn dropdown.
+*   **Checkbox / Radio**: Lựa chọn đơn hoặc nhiều.
+*   **Switch**: Nút gạt bật/tắt hiện đại.
+
+### 🔹 Điều hướng & Cấu trúc (Navigation & Layout)
+*   **Breadcrumbs**: Chỉ dẫn vị trí trang.
+*   **Tabs**: Hệ thống chuyển đổi nội dung.
+*   **Steps**: Quy trình thực hiện (Workflow).
+*   **Stack**: Quản lý khoảng cách tự động giữa các phần tử.
+*   **Card**: Container bọc nội dung cao cấp.
+
+### 🔹 Dữ liệu & Danh sách (Data Display)
+*   **Table**: Bộ component xây dựng bảng dữ liệu chuyên nghiệp.
+*   **List & ListItem**:
+    ```jsx
+    import { List, ListItem } from 'shared-design-system';
+
+    <List>
+      <ListItem icon={<UserIcon />}>Thông tin người dùng</ListItem>
+      <ListItem action={<Button size="sm">Sửa</Button>}>Cài đặt hệ thống</ListItem>
+    </List>
+    ```
+*   **Tag/Chip**: Nhãn dán hỗ trợ nút đóng (close).
+*   **Avatar**: Ảnh đại diện hoặc tên viết tắt.
+*   **ReadOnlyField**: Hiển thị dữ liệu ở chế độ chỉ đọc.
+*   **Skeleton**: Placeholder khi đang tải.
+
+### 🔹 Tương tác (Feedback & Overlays)
+*   **Alert**: Thông báo mức độ nghiêm trọng (`success`, `error`, etc.).
+*   **Tooltip**: Chú thích khi di chuột.
+*   **ConfirmModal**:
+    ```jsx
+    <ConfirmModal
+      isOpen={showModal}
+      title="Xác nhận xóa"
+      message="Bạn có chắc chắn muốn xóa bản ghi này?"
+      variant="danger"
+      onConfirm={handleDelete}
+      onCancel={() => setShowModal(false)}
+    />
+    ```
+
+---
+
+## 🔧 Design Tokens
+
+Tránh sử dụng mã màu hardcoded. Hãy sử dụng hệ thống tokens để đảm bảo tính nhất quán và hỗ trợ Theming trong tương lai.
+
+```typescript
+import { tokens } from 'shared-design-system';
+
+const style = {
+  backgroundColor: tokens.color.surfaceAlt,
+  padding: tokens.spacing[4],
+  borderRadius: tokens.radius.lg,
+  boxShadow: tokens.shadow.md
+};
+```
+
+---
+
+## 🛠 Nguyên tắc phát triển
+
+1.  **Strict Typing**: Tất cả components phải có Props interface được export rõ ràng.
+2.  **Stateless First**: Ưu tiên logic xử lý ở phía ứng dụng, component chỉ tập trung vào hiển thị (UI).
+3.  **Semantic HTML**: Sử dụng đúng các thẻ HTML (button, nav, section) để tối ưu SEO và Accessibility.
+4.  **Composition Over Inheritance**: Tận dụng `children` prop để tạo ra các layout linh hoạt.
+
+---
+
+## 📦 Quy trình Build
+
+```bash
+# Kiểm tra lỗi Type
+npm run typecheck
+
+# Build ra thư mục dist/
+npm run build
+```
+
+> **Lưu ý:** Thư mục `dist/` sẽ chứa mã JS đã transpose và các file `.d.ts`. Luôn chạy build trước khi tích hợp vào Portal.
+
+---
+© 2024 Portal Design System Team.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shared-design-system",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Shared Tailwind Design System & UI Tokens for all Micro Frontends",
   "main": "dist/src/index.js",
   "module": "dist/src/index.js",
@@ -40,14 +40,14 @@
     "access": "public"
   },
   "peerDependencies": {
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "tailwindcss": "^3.0.0"
   },
   "devDependencies": {
-    "typescript": "^5.4.0",
-    "@types/react": "^18.2.0",
-    "@types/react-dom": "^18.2.0",
+    "typescript": "^5.6.3",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
     "@types/node": "^20.11.0"
   }
 }