npm package: @funhub/platform
Description: 现代化的 React 组件库和工具函数集合，为 FunHub 项目提供统一的设计系统和开发工具。
Latest version: 0.2.150

# @funhub/platform

现代化的 React 组件库和工具函数集合，为 FunHub 项目提供统一的设计系统和开发工具。

## 技术栈

- React 18+
- TypeScript
- Zustand + Immer (状态管理)
- TanStack Query (数据获取)
- Vite (构建工具)

## 安装

```bash
pnpm add @funhub/platform
```

## 初始化应用

```bash
npx @funhub/platform init my-funhub-app
```

可选参数：

- `--template base`：使用内置最小 starter 模板
- `--pm pnpm`：指定包管理器
- `--no-install`：只生成文件，不安装依赖
- `--no-git`：跳过 Git 仓库初始化

## 监听第三方包产物同步

当你在本地开发第三方包，希望把构建后的产物持续覆盖到某个已安装目录时，可以使用 `watch-module`：

```bash
npx @funhub/platform watch-module
```

默认会读取当前目录下的 `watchModule.json`。你也可以显式指定配置目录：

```bash
npx @funhub/platform watch-module /path/to/project
```

配置示例：

```json
[
  {
    "source": "/project/npm-last/packages/node/config/dist",
    "target": "/Desktop/dist"
  }
]
```

说明：

- `source` 和 `target` 都支持绝对路径。
- `source` 和 `target` 也支持相对路径，相对路径会基于 `watchModule.json` 所在目录解析。
- 只有当 `source` 与 `target` 都存在时，该项才会被监听。
- 命令启动后会先执行一次同步，再持续监听 `source` 变化并覆盖到 `target`。

## 导出模块

| 模块 | 路径 | 说明 |
|------|------|------|
| common | `@funhub/platform/components/common` | 公共组件 |
| biz | `@funhub/platform/biz` | 业务组件 |
| utils | `@funhub/platform/utils` | 工具函数 |
| service | `@funhub/platform/service` | API 服务层 |
| hooks | `@funhub/platform/hooks` | React Hooks |
| types | `@funhub/platform/types` | TypeScript 类型定义 |
| store | `@funhub/platform/store` | 状态管理 |
| config/tailwind | `@funhub/platform/config/tailwind` | Tailwind 预设与 content 工具 |

## Tailwind 配置复用

```js
// tailwind.config.js
const {
  platformTailwindPreset,
  withPlatformTailwindContent,
} = require('@funhub/platform/config/tailwind');

module.exports = {
  content: withPlatformTailwindContent([
    './app/**/*.{js,ts,jsx,tsx}',
    './components/**/*.{js,ts,jsx,tsx}',
  ]),
  presets: [platformTailwindPreset],
};
```

## 公共组件 (Common)

```
Empty   MediaPreview   useMediaPreview   PopupVideo
CommonPlayer   PhotoGrid   CommonPhotoGrid
photoPreview   closePhotoPreview   DebugLocaleSwitcher
```

### FunhubProvider（推荐入口）

- 接入说明：`components/common/funhub-provider/README.md`
- 使用要求：必须传入 `intl` 配置（建议通过 `@funhub/platform/i18n` 的 `getMessages` 获取语言包）

### 渲染模式约定

- `AppContext` / `useAppContext` 已移除。
- 物料组件统一通过 props 传递 `mode`，并在组件内部使用 `mode = 'renderer'` 作为默认值。
- 当子组件也需要区分编辑态与渲染态时，继续透传 `mode`。

## 业务组件 (Biz)

### Basics (基础业务组件)
- **header-nav** - 头部导航组件
- **logo** - Logo 组件
- **search** - 搜索组件
  - basic-search - 基础搜索
  - filter-search - 过滤搜索
  - tag-search - 标签搜索

### Business (业务组件)
- **search-bar** - 搜索栏组件
  - basic-search-bar - 基础搜索栏
  - filter-search-bar - 过滤搜索栏
  - tag-search-bar - 标签搜索栏

## 使用示例

### 使用公共组件

```tsx
import { Empty } from '@funhub/platform/components/common';

function App() {
  return (
    <Empty
      icon='img_empty_nodata'
      title='暂无数据'
    />
  );
}
```

### 使用业务组件

```tsx
import { BasicSearch } from '@funhub/platform/biz';

function App() {
  return <BasicSearch />;
}
```

### 使用工具函数

```ts
import { http } from '@funhub/platform/utils';

const data = await http.get('/api/data');
```

### 使用状态管理

```ts
import { useDemoStore } from '@funhub/platform/store';

function App() {
  const { data, setData } = useDemoStore();
  // ...
}
```

## 开发

```bash
# 开发模式（监听文件变化）
pnpm dev

# 构建
pnpm build

# 发布
pnpm pp
```

## 代码规范

### ESLint

```bash
pnpm lint         # 检查代码问题
pnpm fix          # 自动修复问题
```

### 文件组织规范

#### 命名规范
所有文件和文件夹使用 **kebab-case** 命名。

#### 组件组织方式

**方式一：多文件组件（文件夹组织）**

```
list/
├── index.ts           # 统一导出
├── list.tsx           # 主组件
└── list-item.tsx      # 子组件
```

**方式二：单文件组件**

```
button.tsx
card.tsx
input.tsx
```

## 相关文档

- [完整文档](https://funhub.example.com) (待上线)
- [更新日志](./CHANGELOG.md)