# @maquan/ui

真实 React 组件、TypeScript 属性类型、共享 CSS 和 196 个独立示例。76 个公开条目包括两个基础展示板块、基础控件、数据图表和 Agent 组件。

## 在已有 React 项目中使用

```sh
npm install /absolute/path/to/maquan-react
```

```tsx
import { Button } from '@maquan/ui';
import '@maquan/ui/styles.css';

export default function Example() {
  return <Button variant="secondary">继续</Button>;
}
```

组件包在本地提供，尚未发布到 npm；`@maquan/ui` 是此包真实的包名和导出路径。

- React / React DOM 为 peer dependencies，应用使用 React 19。
- Radix UI 提供弹窗、菜单、标签页和表单控件的基础交互。
- Recharts 提供 10 类真实图表。
- Lucide React 提供统一的线性图标。
- React Hook Form 提供完整表单的验证、提交及重置状态。
- shadcn/ui 官方当前 64 类组件均有对应条目，覆盖快照保存在 `src/shadcn-components.json`，映射结果见 `dist/coverage.json`。
- 样式通过 `@maquan/ui/styles.css` 统一导入；无需在每个调用示例里复制实现。
- 图片示例默认使用 `assets/carousel`。将包内 `assets` 目录复制到应用的 `public/assets`，或使用组件的 `src`、`slides`、附件等数据属性提供自己的图片。

## 项目结构

- `src/shared.tsx`：Button、Icon、公共布局及通知 helper。
- `src/components/*.tsx`：原生 React 组件实现，状态通过 React hooks 和公开回调管理。
- `src/examples/*-N.tsx`：网页中实际渲染的 196 个简短示例。
- `dist/index.js`、`dist/index.d.ts`：ESM 导出和 TypeScript 声明。
- `dist/styles.css`：公共样式；变量统一以 `--mq-` 开头。
- `dist/gallery.js`：当前离线文档使用的 React 运行包，包含展示所需依赖。
- `dist/manifest.json`：组件、变体、真实导出名称和源码路径。

组件支持数据属性和回调，例如 `Tabs.items/onValueChange`、`Table.rows/columns/onSelectionChange`、`AgentComposer.onSubmit(payload, signal)`。具体类型可在 `dist/*.d.ts` 或源码接口中查看。Agent 默认是本地交互演示；接入真实服务时传入公开回调。

## 开发与检查

```sh
npm ci
npm run typecheck
npm run build
npm run check
```

检查覆盖所有公开导出、196 个示例编译和服务端渲染、目录及文档与实际源码逐项映射、独立使用与预览的基础样式，以及真实 React DOM 中的关键交互。DOM 检查使用 jsdom，不属于浏览器视觉验收。

当前主文档：同级目录 `../maquan-ui-component-library.html`。用浏览器打开并刷新即可；文档加载本地经典脚本，不要求开发服务器。旧 HTML 预览保留为 `../maquan-ui-legacy-preview.html`。

目录、网页导航、预览注册和调用示例由 `src/catalog.json` 同时生成。代码页的“组件源码（所在文件）”显示实际源文件全文，“公共样式”显示完整 `dist/styles.css`；复制调用示例即可沿用预览的基础样式。