sgod-library-frontend/README.md

Thư viện component UI Frontend

# Thư viện Component UI

Thư viện component UI được thiết kế cho microfrontend sgod

## Cài đặt

```bash
npm install sgod-library-frontend

# hoặc sử dụng yarn
yarn add sgod-library-frontend
```

## Cấu trúc thư viện

Thư viện được tổ chức theo phương pháp Atomic Design:

```
src/
├── components/
│   ├── atoms/         # Các component cơ bản, không thể chia nhỏ hơn
│   ├── molecules/     # Các component được tạo từ nhiều atoms
│   ├── organisms/     # Các component phức tạp, kết hợp nhiều molecules
│   ├── templates/     # Bố cục trang với vị trí các component
│   └── pages/         # Các trang hoàn chỉnh
├── hooks/             # Custom React hooks
├── utils/             # Các tiện ích
│   ├── eventBus.ts    # Event bus cho giao tiếp giữa micro-frontends
│   └── constants.ts   # Các hằng số và sự kiện
└── styles/            # CSS và các styles
    └── tokens.ts      # Design tokens cho hệ thống thiết kế
```

## Design System

Thư viện này tuân theo các nguyên tắc thiết kế UI/UX cho hệ thống Micro Front End:

### 1. Tính nhất quán (Consistency)

#### Hệ thống màu sắc
- **Màu chính (Primary)**: Sử dụng cho các thành phần tương tác chính
- **Màu phụ (Secondary)**: Sử dụng cho các thành phần tương tác thứ yếu
- **Màu ngữ nghĩa (Semantic)**: Success, Warning, Error, Info
- Mỗi màu có 9 sắc độ (50-900) cho các trạng thái khác nhau
- Mẫu sử dụng: `color.primary.500`, `color.error.100`...

#### Typography
- Font chữ: Inter (cho cả tiêu đề và nội dung)
- Hệ thống kích thước font: xs(12px), sm(14px), base(16px), lg(18px), xl(20px), ...
- Font weight: Regular(400), Medium(500), Bold(700)
- Line height: Tight(1.25) cho tiêu đề, Normal(1.5) cho nội dung

#### Spacing
- Hệ thống spacing nhất quán: 0.25rem(4px), 0.5rem(8px), 0.75rem(12px), ...
- Grid system: 12 cột, gutter tùy chỉnh
- Padding và margin tuân thủ theo spacing scale

#### Border radius
- Nhỏ: 0.25rem(4px) cho buttons, inputs
- Trung bình: 0.5rem(8px) cho cards, panels
- Lớn: 1rem(16px) cho modals, dialogs

#### Shadow
- xs: Cho hover states
- sm: Cho cards, dropdowns nhỏ
- md, lg, xl: Cho cards, dialogs, modals theo mức độ nổi

#### Iconography
- Bộ icons nhất quán với 2 variants: outline và solid
- Kích thước: xs(12px), sm(16px), md(20px), lg(24px), xl(32px)

### 2. Nguyên tắc thiết kế

#### Thời gian phản hồi
- Mỗi component đều có trạng thái loading/skeleton để hiển thị trong khi chờ dữ liệu
- Spinner, progress bar và shimmer effect được sử dụng để báo hiệu quá trình loading

#### Gesture và Motion
- Các animation và transition nhất quán giữa các component
- Sử dụng Tailwind để đảm bảo tính nhất quán

#### Tính module hoá
- Mỗi component được thiết kế để có thể sử dụng độc lập
- Sử dụng CSS Module và Tailwind JIT để đảm bảo CSS không bị xung đột
- Isolation giữa các component giúp chúng không ảnh hưởng lẫn nhau

#### Giao tiếp giữa các micro-frontend
- Sử dụng Event Bus (dựa trên mitt) để phát và nhận sự kiện
- Hook `useEventBus` giúp dễ dàng lắng nghe và phát sự kiện

#### Trạng thái và phản hồi người dùng
- Empty state: Hiển thị trạng thái trống với hướng dẫn hành động
- Error state: Hiển thị lỗi với khả năng thử lại
- Skeleton UI: Hiển thị khung sườn khi loading

## Cách sử dụng

### Setup Tailwind CSS

Thư viện này sử dụng Tailwind CSS. Bạn cần đảm bảo dự án của bạn đã được cấu hình Tailwind CSS:

```js
// tailwind.config.js
module.exports = {
  content: [
    "./src/**/*.{js,jsx,ts,tsx}",
    "./node_modules/sgod-library-frontend/**/*.{js,jsx,ts,tsx}"
  ],
  theme: {
    extend: {
      // ... các theme mở rộng của bạn
    },
  },
  plugins: [],
}
```

### Import và sử dụng component
```jsx
import { Button, Card, EmptyState, Typography, Grid, Icon } from 'sgod-library-frontend';
import 'sgod-library-frontend/dist/index.css'; // Import CSS

function App() {
  return (
    <Card title="Thẻ ví dụ">
      <Typography variant="h3" color="primary">Tiêu đề</Typography>
      <Typography variant="body1">Nội dung thẻ</Typography>
      
      <Grid container cols={2} spacing={4}>
        <Grid item>
          <Button 
            variant="primary" 
            leftIcon={<Icon name="check" />}
          >
            Đồng ý
          </Button>
        </Grid>
        <Grid item>
          <Button variant="outline">Hủy bỏ</Button>
        </Grid>
      </Grid>
    </Card>
  );
}
```

### Sử dụng Event Bus
```jsx
import { useEffect } from 'react';
import { eventBus, EVENTS, useEventBus } from 'sgod-library-frontend';

function UserProfile() {
  // Lắng nghe sự kiện USER.UPDATED_PROFILE và gọi hàm handleProfileUpdate khi có sự kiện
  const emitProfileUpdated = useEventBus(EVENTS.USER.UPDATED_PROFILE, handleProfileUpdate);
  
  function handleProfileUpdate(data) {
    console.log('Hồ sơ đã được cập nhật:', data);
  }
  
  function updateProfile() {
    // Cập nhật hồ sơ...
    
    // Sau đó phát sự kiện để thông báo cho các micro-frontend khác
    emitProfileUpdated({ name: 'Nguyễn Văn A', email: 'a@example.com' });
  }
  
  return (
    <Button onClick={updateProfile}>Cập nhật hồ sơ</Button>
  );
}
```

## Các Components có sẵn

### Atoms
- **Button**: Nút bấm với nhiều variants, sizes và states
- **Input**: Trường nhập liệu với validation
- **Skeleton**: Hiệu ứng loading cho components
- **Grid**: Hệ thống lưới linh hoạt
- **Icon**: Biểu tượng với nhiều kích thước và variants
- **Typography**: Định dạng văn bản nhất quán

### Molecules
- **Card**: Thẻ hiển thị nội dung với header và footer tùy chọn
- **EmptyState**: Hiển thị khi không có dữ liệu
- **ErrorState**: Hiển thị khi có lỗi
- **FormField**: Trường form với label và validation
- **Alert**: Thông báo với các trạng thái khác nhau

### Organisms
- **DataTable**: Bảng dữ liệu với sorting, pagination
- **Form**: Form với validation

## Tiêu chuẩn kỹ thuật

- React 17+ hoặc 18+
- TypeScript
- Tailwind CSS
- Module CSS cho styling
- Mitt cho Event Bus