npm package: @flexhaul/ui
Description: FlexHaul UI Component Library - React components with styled-components and MUI
Author: FlexHaul Team
Latest version: 0.2.0

# @flexhaul/ui

FlexHaul UI 组件库 - 基于 React + styled-components + MUI 的企业级组件库

[![npm version](https://img.shields.io/npm/v/@flexhaul/ui.svg)](https://www.npmjs.com/package/@flexhaul/ui)
[![license](https://img.shields.io/npm/l/@flexhaul/ui.svg)](https://github.com/flexhaul/ui/blob/main/LICENSE)

## ✨ 特性

- 🎨 **Design Token 系统** - 统一的颜色、间距、字体等设计规范
- 📦 **开箱即用** - 50+ 组件，覆盖常见业务场景
- 🔧 **TypeScript** - 完整的类型定义
- 💅 **styled-components** - 自研样式系统，灵活可定制
- 🎯 **MUI 兼容** - 基于 MUI 封装，保持 API 一致性

## 📦 安装

```bash
npm install @flexhaul/ui
# or
yarn add @flexhaul/ui
# or
pnpm add @flexhaul/ui
```

### Peer Dependencies

```bash
npm install react react-dom @mui/material @mui/icons-material @emotion/react @emotion/styled styled-components
```

## 🚀 快速开始

### 1. 配置 Provider

在应用根组件中使用 `FHProvider`：

```tsx
import { FHProvider } from '@flexhaul/ui';

function App() {
  return (
    <FHProvider>
      <YourApp />
    </FHProvider>
  );
}
```

### 2. 使用组件

```tsx
import { FHButton, FHTextField, FHDialog, FHTable, FHToast } from '@flexhaul/ui';

function MyComponent() {
  return (
    <div>
      <FHButton variant="primary" onClick={() => console.log('clicked')}>
        Submit
      </FHButton>
      
      <FHTextField 
        label="Email" 
        placeholder="Enter your email"
        errorText="Invalid email format"
      />
    </div>
  );
}
```

## 📚 核心组件

### 按钮 Button

```tsx
// 变体: primary | secondary | danger | success | ghost | text
<FHButton variant="primary">Primary</FHButton>
<FHButton variant="secondary">Secondary</FHButton>
<FHButton variant="danger">Delete</FHButton>

// 尺寸: sm | md | lg
<FHButton size="sm">Small</FHButton>
<FHButton size="lg">Large</FHButton>

// 加载状态
<FHButton loading>Saving...</FHButton>

// 图标按钮
<FHIconButton aria-label="delete">
  <DeleteIcon />
</FHIconButton>
```

### 输入框 TextField

```tsx
<FHTextField
  label="Email"
  value={email}
  onChange={(e) => setEmail(e.target.value)}
  required
  error={!!error}
  errorText={error}
/>

// 多行文本
<FHTextArea label="Description" rows={4} />

// 搜索框
<FHSearchField placeholder="Search..." onChange={handleSearch} />
```

### 对话框 Dialog

```tsx
// 确认对话框
<FHConfirmDialog
  open={open}
  title="Delete Item"
  message="Are you sure you want to delete this item?"
  onClose={() => setOpen(false)}
  onConfirm={handleDelete}
  confirmVariant="danger"
/>

// 表单对话框
<FHFormDialog
  open={open}
  title="Edit User"
  onClose={handleClose}
  onSubmit={handleSubmit}
  loading={isSubmitting}
>
  <FHTextField label="Name" />
  <FHTextField label="Email" />
</FHFormDialog>
```

### 表格 Table

```tsx
<FHTable
  columns={[
    { key: 'name', title: 'Name', sortable: true },
    { key: 'email', title: 'Email' },
    { key: 'status', title: 'Status', render: (val) => <FHChip>{val}</FHChip> },
  ]}
  data={users}
  rowKey="id"
  loading={isLoading}
  pagination={{
    page,
    pageSize,
    total,
    onChange: handlePageChange,
  }}
  selection={{
    selectedKeys,
    onChange: handleSelectionChange,
  }}
/>
```

### Toast 消息提示

```tsx
// 使用 Hook
const { showToast } = useFHToast();

showToast({ message: 'Saved!', severity: 'success' });
showToast({ message: 'Error occurred', severity: 'error' });

// 使用 Provider (推荐)
<FHToastProvider>
  <App />
</FHToastProvider>
```

## 🎨 Design Tokens

```tsx
import { theme, colors, spacing, borderRadius } from '@flexhaul/ui';

// 颜色
colors.primary.main      // #00a79d
colors.error.main        // #dc3545
colors.text.primary      // #344559

// 间距
spacing.xs   // 4px
spacing.sm   // 8px
spacing.md   // 16px
spacing.lg   // 24px

// 圆角
borderRadius.sm   // 4px
borderRadius.md   // 8px
borderRadius.lg   // 12px
```

## 📖 完整组件列表

### 核心组件
- `FHButton`, `FHIconButton`, `FHButtonGroup`
- `FHTextField`, `FHTextArea`, `FHSearchField`
- `FHDialog`, `FHConfirmDialog`, `FHFormDialog`, `FHAlertDialog`
- `FHTable`, `FHResponsiveTable`, `FHSelectableTable`
- `FHToast`, `FHToastProvider`

### 布局组件
- `FHBox`, `FHFlex`, `FHStack`, `FHCenter`
- `FHGrid`, `FHGridItem`
- `FHContainer`, `FHDivider`, `FHPaper`

### 表单组件
- `FHSelect`
- `FHCheckbox`, `FHRadio`, `FHRadioGroup`, `FHSwitch`

### 反馈组件
- `FHAlert`, `FHSnackbarAlert`
- `FHSpinner`, `FHLoading`
- `FHModal`, `FHTooltip`
- `FHChip`

### 导航组件
- `FHTabs`, `FHTab`
- `FHPagination`

### 文字组件
- `FHTypography`, `FHText`, `FHLabel`, `FHCaption`
- `FHPageTitle`, `FHSectionTitle`

### 数据展示
- `FHStatusBadge`, `FHSuccessBadge`, `FHErrorBadge`, `FHWarningBadge`

## 🔄 从 MUI 迁移

| MUI | @flexhaul/ui | 说明 |
|-----|--------------|------|
| `<Button variant="contained">` | `<FHButton variant="primary">` | variant 映射 |
| `<TextField helperText={error}>` | `<FHTextField errorText={error}>` | 错误提示 |
| `<Dialog>` + `<DialogActions>` | `<FHDialog onConfirm={...}>` | 简化 API |
| `<Table>` | `<FHTable columns={...}>` | 声明式配置 |
| `<Snackbar>` + `<Alert>` | `<FHToast>` | 统一消息 |

## 📝 License

MIT © FlexHaul Team