# @pisell/materials

> Pisell 2.0 基础物料库 - 包含原子组件和 Pro 组件

[![Version](https://img.shields.io/npm/v/@pisell/materials.svg)](https://www.npmjs.com/package/@pisell/materials)
[![License](https://img.shields.io/npm/l/@pisell/materials.svg)](https://github.com/your-org/pisell2)

## 📦 安装

```bash
npm install @pisell/materials
# or
pnpm add @pisell/materials
```

## 🚀 快速开始

### ✨ 方式一：命名空间导入（推荐）

```tsx
import { PisellFields, PisellMetrics, PisellLayouts, PisellCards } from '@pisell/materials';

// 字段组件 - 支持编辑/只读/禁用三态
<PisellFields.SingleLineText value="Hello" viewMode="edit" />
<PisellFields.Currency value={1000} currencySymbol="$" />
<PisellFields.Percent value={0.85} />

// 数据展示 - 指标卡片
<PisellMetrics.MetricCard 
  title="Total Sales" 
  value={1580}
  comparison={120}
  showTrendIcon 
/>

// 布局组件 - 网格布局
<PisellLayouts.BasicGrid columns={3} gap={16}>
  {items.map(item => <Card key={item.id} {...item} />)}
</PisellLayouts.BasicGrid>

// 卡片组件
<PisellCards.TextCard title="标题" content="内容" />
```

### ✅ 方式二：单独导入（兼容历史）

```tsx
import { 
  PisellSingleLineText, 
  PisellMetricCard, 
  PisellBasicGrid 
} from '@pisell/materials';

// 使用方式完全一致
<PisellSingleLineText value="Hello" viewMode="edit" />
<PisellMetricCard title="Total Sales" value={1580} />
<PisellBasicGrid columns={3}>{children}</PisellBasicGrid>
```

> 💡 **两种方式完全等价**，选择你喜欢的方式！详见 [命名空间使用指南](./NAMESPACE_GUIDE.md)

---

## 📚 组件分类

### 🌟 命名空间（推荐使用）

| 命名空间 | 说明 | 组件数量 | 使用方式 |
|---------|------|---------|----------|
| **`PisellFields`** | 字段组件（三态视图） | 11 个 | `<PisellFields.SingleLineText />` |
| **`PisellMetrics`** | 指标展示组件 | 3 个 | `<PisellMetrics.MetricCard />` |
| **`PisellLayouts`** | 布局组件 | 10 个 | `<PisellLayouts.BasicGrid />` |
| **`PisellCards`** | 卡片组件 | 5 个 | `<PisellCards.TextCard />` |

### 📦 完整组件列表

| 分类 | 组件数量 | 说明 |
|------|---------|------|
| 字段组件 | 11 个 | 支持编辑/只读/禁用三态的表单字段 |
| 卡片组件 | 12+ 个 | 各类内容展示卡片 |
| 数据展示 | 10+ 个 | 指标、统计、KPI 展示 |
| 布局组件 | 10+ 个 | 页面布局和容器 |
| 表格组件 | 5 个 | 数据表格及增强功能 |
| 表单组件 | 15+ 个 | 表单输入和编辑 |
| 导航组件 | 10+ 个 | 菜单、步骤条、标签页 |

---

## ⭐ 核心特性

### 命名空间组件示例

#### 1. PisellFields - 字段组件（最新开发）

```tsx
import { PisellFields } from '@pisell/materials';

// 支持三态视图：编辑态、只读态、禁用态
<PisellFields.SingleLineText
  value="Hello"
  viewMode="edit"  // edit | readonly | disabled
  onChange={setValue}
/>

<PisellFields.Currency
  value={1000}
  currencySymbol="$"
  precision={2}
  useGrouping
/>

<PisellFields.Percent
  value={0.85}
  showAsDecimal={false}  // 显示为 85%
/>
```

**完整字段列表：**
- SingleLineText, LongText
- Number, Currency, Percent
- Phone, Email, Url
- Rating, SingleSelect, MultipleSelect

#### 2. PisellMetrics - 指标展示

```tsx
import { PisellMetrics } from '@pisell/materials';

// 完整功能的指标卡片
<PisellMetrics.MetricCard
  title="Total Sales"
  value={1580}
  showCurrencySymbol
  currencySymbol="$"
  comparison={120}        // 环比数据
  showComparison
  showTrendIcon          // 自动显示上升/下降箭头
/>
```

#### 3. PisellLayouts - 布局组合

```tsx
import { PisellLayouts, PisellCards } from '@pisell/materials';

// 推荐组合：快速搭建列表/网格场景
<PisellLayouts.ScrollView direction="horizontal">
  <PisellLayouts.BasicGrid columns={3} gap={16}>
    {items.map(item => (
      <PisellCards.TextCard key={item.id} {...item} />
    ))}
  </PisellLayouts.BasicGrid>
</PisellLayouts.ScrollView>
```

---

## 📖 完整文档

- **命名空间指南**：[NAMESPACE_GUIDE.md](./NAMESPACE_GUIDE.md) - ✨ 新的命名空间使用方式
- **组件索引**：[COMPONENTS.md](./COMPONENTS.md) - 162 个组件的完整分类索引
- **开发规范**：[.cursor/rules/create-component-rule.mdc](../../.cursor/rules/create-component-rule.mdc)
- **LowCode 配置**：[.cursor/rules/lowcode-meta-rule.mdc](../../.cursor/rules/lowcode-meta-rule.mdc)
- **在线文档**：查看 application/docs

---

## 🛠️ 开发

```bash
# 安装依赖
pnpm install

# 开发模式（低代码）
pnpm run lowcode:dev

# 开发模式（ES 模块）
pnpm run dev

# 构建
pnpm run build

# 测试
pnpm run test
```

---

## 📦 构建产物

### ESM/CJS 模块

```bash
lib/       # CommonJS 格式
es/        # ES Module 格式
```

### LowCode 物料

```bash
build/lowcode/
├── assets-prod.json   # 物料描述文件
├── view.js            # UMD 格式组件包
└── view.css           # 样式文件
```

---

## 🔧 配置

### TypeScript

```tsx
import type { 
  PisellMetricCardProps,
  PisellSingleLineTextProps,
  PisellBasicGridProps 
} from '@pisell/materials';
```

### 低代码集成

```typescript
// 在低代码引擎中使用
import assets from '@pisell/materials/build/lowcode/assets-prod.json';

// 加载物料
await loadAssets(assets);
```

### 主题定制

```tsx
import { PisellConfigProvider } from '@pisell/materials';

<PisellConfigProvider theme={{...}}>
  <App />
</PisellConfigProvider>
```

---

## 📋 组件命名规范

| 前缀 | 说明 | 示例 |
|------|------|------|
| `Pisell*` | Pisell 系列组件 | PisellButton, PisellMetricCard |
| `DataSource*` | 数据源组件 | DataSourceForm, DataSourceTable |
| `FormItem*` | 表单项组件 | FormItemInput, FormItemSelect |

---

## 🎯 使用建议

### 新项目
- ✅ 使用命名空间导入：`PisellFields`, `PisellMetrics` 等
- ✅ 更清晰的代码组织
- ✅ 更好的 IDE 提示

### 历史项目
- ✅ 保持现有导入方式
- ✅ 无需修改任何代码
- ✅ 100% 向后兼容

### 混合使用
- ✅ 两种方式可以同时使用
- ✅ 根据场景灵活选择

---

## 🤝 贡献

请参考 [组件开发规范](../../.cursor/rules/create-component-rule.mdc)

---

## 📄 许可

MIT

---

**💡 提示**：
- 查看 [NAMESPACE_GUIDE.md](./NAMESPACE_GUIDE.md) 了解命名空间详细用法
- 查看 [COMPONENTS.md](./COMPONENTS.md) 获取完整组件列表