@pisell/materials 1.8.38 → 1.8.41

package/lib/components/pisellExport/docs/pisellExport.$tab-design.md

@@ -0,0 +1,116 @@
+# 资源链接
+
+## 任务链接
+
+ 
+
+## Figma链接
+
+Implement this design from Figma.
+@https://www.figma.com/design/pM8Ho6d7kCMv9vIBvFHUlj/Pisell-2.0-Component-Library?node-id=12671-97136&m=dev
+Implement this design from Figma.
+@https://www.figma.com/design/pM8Ho6d7kCMv9vIBvFHUlj/Pisell-2.0-Component-Library?node-id=12671-97155&m=dev
+
+# 1. 组件概述
+
+| **组件名称（英文）** | Export                                                                        |
+|--------------|-------------------------------------------------------------------------------|
+| **组件编号**     | pca\_de\_export\_V1.0                                                         |
+| **组件类型**     | Atom Components                                                               |
+| **组件分类**     | Data Entry                                                                    |
+| **简介**       | 提供数据导出能力，将结构化数据转换为多种格式（如Excel、CSV、PDF）的文件，支持同步和异步两种导出模式，满足从简单报表到大数据量导出的各类业务场景 |
+
+# 2. 版本
+
+| **版本**   | 1.0  |
+|----------|------|
+| **更新简介** | 首次发布 |
+
+# 3. 组件设计目的
+
+* 简化数据输出流程
+
+* 保障导出性能与可靠性
+
+* 提升用户体验
+
+# 4. 适用场景
+
+<table>
+<thead>
+<tr>
+<th><h4>场景</h4></th>
+<th><h4>示例</h4></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><strong>销售管理</strong></td>
+<td>本季度销售业绩报表导出为Excel，包含多Sheet页和复杂样式</td>
+</tr>
+<tr>
+<td><strong>用户管理</strong></td>
+<td>将筛选后的用户列表导出为CSV文件，用于邮件群发或数据分析</td>
+</tr>
+</tbody>
+</table>
+
+# 5. UI 设计
+
+## 5.1 展示样式
+
+Export 目前分为两种样式：
+
+* Icon 样式​​：显示样式只有一个icon
+
+* Button 样式​​：显示内容为icon加文本
+
+| ![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=Y2E5NGEyNjdiMWRlYzQzZmE5MjNmNmZiZTdkNGIxYzZfbjk4TDZmdVp4MjZoRWdMdXl3Y0kxMmNsU1NTamxoYW9fVG9rZW46SFdaZWJZdDkzb0RuZk94c2FsTGNXTE0wbjhjXzE3NzIwMDQzMTM6MTc3MjAwNzkxM19WNA) | ![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=ODI0MmI3MWY2NmU3NTlhYWY4OWMzNWNjNTdmMTFlMmFfc0FuY0NVVXdQTnlCWkRmcDhsRXo1ckR0bjY0MlhTa1JfVG9rZW46SWhxQmJOc1VLb0xFS0x4MWpxM2NkalN0bnpmXzE3NzIwMDQzMTM6MTc3MjAwNzkxM19WNA) |
+|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+
+* 给到此组件的六个状态（默认样式、鼠标悬浮、focused、激活、禁用、激活禁用）样式，支持更改六个状态下的样式
+
+* 同时组件有小、中、大三中大小可供选择
+
+Implement this design from Figma.
+
+@https://www.figma.com/design/pM8Ho6d7kCMv9vIBvFHUlj/Pisell-2.0-Component-Library?node-id=12671-96989\&m=dev
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=M2M0MDc2NTJjMjZiYTI4MDE1MzE3MzYzNjY2NGNlMDNfdk1sa3ZXNXlsUk1ZMnE3d0FFRDJqandpdUhzcGZLWXlfVG9rZW46RGJtWWJLeFRsb3ViVXV4ODVxbmNSdk5NbnJiXzE3NzIwMDQzMTM6MTc3MjAwNzkxM19WNA)
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=NTIzZDE1NTYzOTc0NWQ0OWE0NWE3OTlmNjJlMGM1MDFfSnRuRWg4Sm1Bd1JscDY4TU00ZlgyaW84a3U3R3NYSGxfVG9rZW46VzVVMWJKd1l2b1hnVHJ4NjgxT2NCckRhbjNiXzE3NzIwMDQzMTM6MTc3MjAwNzkxM19WNA)
+
+## 5.2 **视觉设计规范（需要主题模块完成）**
+
+### 5.2.1 颜色规范
+
+### 5.2.2 尺寸规范
+
+### 5.2.3 间距规范
+
+# 6. 配置项
+
+## 6.1 样式自定义
+
+* 按钮的外观可以自定义样式，包括背景色、边框、padding、gap、阴影
+
+* 按钮内的icon可以自定义样式，包括icon的切换、icon大小、颜色
+
+* 按钮内文本的样式可自定义，包括文本内容、文本大小、颜色、粗细
+
+* 按钮的六种不同状态的样式也可自定义
+
+## 6.2 功能配置
+
+* 可以选择按钮的大小
+
+* 可以切换按钮的样式
+
+* 可控制导出的格式
+
+* 可控制轮询间隔
+
+* 是否支持预览，默认不支持
+
+# 7. 示例
+

package/lib/components/pisellExport/docs/pisellExport.$tab-dev.md

@@ -0,0 +1,132 @@
+---
+title: 开发文档
+order: 3
+category: atom
+---
+
+# PisellExport 开发文档
+
+## 1. 基本信息
+
+| 项目     | 内容                      |
+| -------- | ------------------------- |
+| 组件名称 | PisellExport              |
+| 组件版本 | 1.0.0                     |
+| 组件分类 | 原子组件 (atom) / Data Entry |
+| 技术栈   | React + TypeScript + Less |
+| 依赖组件 | 无（可选复用 antd Button 或仅用原生语义） |
+
+## 2. 组件描述
+
+PisellExport 是导出功能的 UI 触发器组件，提供「仅图标」与「图标+文案」两种展示形态，支持小/中/大三种尺寸与默认、主色、禁用等状态。**阶段一仅做 UI 与回调**：不内置导出逻辑，点击后通过 `onExport` 回调由调用方完成导出请求、轮询、下载等。
+
+**核心特点**：
+
+- 两种展示形态：Icon 样式、Button 样式（icon + 文案）
+- 六种交互状态样式：默认、hover、focused、激活、禁用、激活态禁用
+- 三种尺寸：small / medium / large
+- 样式与设计稿一致（Figma），支持 className / style 扩展
+
+## 3. 需求点罗列
+
+### 3.1 UI 展示
+
+- [x] 支持 Icon 样式（仅图标）
+- [x] 支持 Button 样式（图标 + 文案）
+- [x] 支持小、中、大三种尺寸
+- [x] 六种状态样式：默认、悬浮、focused、激活、禁用、激活禁用
+- [x] 默认图标为 download-cloud-02 语义（可由 icon 覆盖）
+
+### 3.2 功能（阶段一）
+
+- [x] 点击触发回调 `onExport`，不内置导出逻辑
+- [x] 支持 `disabled` 禁用
+- [x] 支持自定义文案 `label`（Button 形态）
+- [x] 支持自定义图标 `icon`
+
+### 3.3 扩展
+
+- [x] 支持 `className`、`style`
+- [ ] 六态样式深度自定义（预留，后续可加）
+
+## 4. 组件 API
+
+### 4.1 Props 定义
+
+| 属性       | 类型        | 默认值    | 必填 | 说明 |
+| ---------- | ----------- | --------- | ---- | ---- |
+| variant    | VariantType | 'button'  | 否   | 展示形态：icon / button |
+| size       | SizeType    | 'medium'  | 否   | 尺寸：small / medium / large |
+| type       | ExportButtonType | 'default' | 否 | 视觉类型：default / primary |
+| disabled   | boolean     | false     | 否   | 是否禁用 |
+| label      | ReactNode   | getText 或 'Export' | 否 | Button 形态文案 |
+| icon       | ReactNode   | 内置下载图标 | 否 | 自定义图标 |
+| onExport   | (e: MouseEvent) => void | - | 否 | 点击触发导出，由调用方实现 |
+| className  | string      | -         | 否   | 自定义类名 |
+| style      | CSSProperties | -       | 否   | 自定义样式 |
+
+### 4.2 类型定义
+
+```
+type VariantType = 'icon' | 'button';
+type SizeType = 'small' | 'medium' | 'large';
+type ExportButtonType = 'default' | 'primary';
+```
+
+## 5. 组件模块拆解
+
+```
+pisellExport/
+├── index.tsx                      # 组件导出入口
+├── PisellExport.tsx               # 组件核心实现
+├── PisellExport.less              # 组件样式（六态、三尺寸）
+├── types.ts                       # TypeScript 类型定义
+└── docs/
+    ├── pisellExport.$tab-design.md
+    └── pisellExport.$tab-dev.md
+```
+
+### 5.1 模块职责
+
+| 模块             | 职责 |
+| ---------------- | ---- |
+| PisellExport.tsx | 根据 variant 渲染 icon 或 icon+label，绑定 onExport，应用 size/type/disabled 类名与样式 |
+| PisellExport.less| 小/中/大尺寸 padding、gap；default/primary 及 hover/focus/active/disabled 状态样式 |
+| types.ts         | VariantType、SizeType、ExportButtonType、PisellExportProps |
+
+## 6. 实现方案
+
+### 6.1 结构
+
+- 根节点为 `button` 或 `span`（可访问性用 button），避免在禁用时触发点击。
+- Icon 形态：单图标容器，尺寸由 size 控制 padding（设计稿 Icon 小 10px、中 10px、大 14px）。
+- Button 形态：图标 + label，gap 8px，padding 随 size（小 14×8、中 16×10、大 20×12）。
+
+### 6.2 样式
+
+- 使用 Less，类名前缀 `.pisell-export-`。
+- 尺寸与设计稿一致：small 14px/8px，medium 16px/10px，large 20px/12px；图标 24px。
+- 颜色：default 边框 #D0D5DD、文案 #344054；primary 主色 #7F56D9、背景 #F9F5FF 等；禁用灰化。
+- 阴影：0px 1px 2px rgba(16,24,40,0.05)；圆角 8px。
+
+### 6.3 图标
+
+- 若无 `icon` 传入，使用项目内已有下载图标或占位 SVG（download-cloud-02 语义）；若有则渲染 `icon`。
+
+### 6.4 回调
+
+- 点击时调用 `onExport?.(e)`，不阻止默认、不内置下载/请求逻辑。
+
+## 7. 组成部分与引用关系
+
+```
+PisellExport
+├── 根节点 (button/span)
+│   ├── 图标区域 (传入 icon 或默认图标)
+│   └── [Button 形态] 文案 (label)
+└── 无子组件引用，仅使用项目 locales（getText）与样式
+```
+
+---
+
+**阶段一不包含**：导出格式选择、轮询间隔、预览能力、内置请求逻辑；均由调用方在 `onExport` 中实现。

package/lib/components/pisellExport/docs/pisellExport.$tab-test.md

@@ -0,0 +1,61 @@
+---
+title: 测试文档
+order: 4
+category: atom
+---
+
+# PisellExport 测试文档
+
+## 测试策略
+
+PisellExport 为导出触发器 UI 组件，阶段一仅做 UI 与回调。测试覆盖：
+
+1. **基础渲染**：默认及不同 variant/size/type 下的 DOM 与类名
+2. **Props 透传**：label、disabled、className、style 等是否生效
+3. **交互**：点击触发 onExport、disabled 时不触发
+4. **边界**：无 onExport 时点击不报错
+
+## 测试用例
+
+### 1. 基础渲染
+
+| 用例编号 | 描述 | 预期 |
+| -------- | ---- | ---- |
+| R.1 | 默认渲染（variant=button） | 根节点为 button，包含图标与默认文案（getText 或「导出」） |
+| R.2 | variant=icon | 仅渲染图标，无文案节点 |
+| R.3 | size=small/medium/large | 根节点分别带类名 pisell-export--small/medium/large |
+| R.4 | type=default/primary | 根节点分别带类名 pisell-export--default/primary |
+| R.5 | disabled=true | 根节点带 pisell-export--disabled，button 的 disabled 为 true |
+
+### 2. Props
+
+| 用例编号 | 描述 | 预期 |
+| -------- | ---- | ---- |
+| P.1 | 传入 label | 文案区域显示传入的 label |
+| P.2 | 传入 icon | 使用传入的 icon 节点，不显示默认图标 |
+| P.3 | 传入 className | 根节点 class 包含该 className |
+| P.4 | 传入 style | 根节点应用对应内联样式 |
+
+### 3. 交互
+
+| 用例编号 | 描述 | 预期 |
+| -------- | ---- | ---- |
+| I.1 | 点击且未 disabled | 调用 onExport 一次，并传入事件对象 |
+| I.2 | disabled 时点击 | 不调用 onExport |
+| I.3 | 未传入 onExport 时点击 | 不报错，不抛错 |
+
+### 4. 人工测试点（Storybook）
+
+- 各尺寸、各类型在 Chrome 下视觉与设计稿一致（边框、圆角、阴影、主色）
+- hover / focus / active 状态样式正常
+- 禁用态灰化、不可点击
+
+---
+
+## bug 汇总
+
+（人工测试阶段将发现的 bug 记录于此）
+
+| 日期 | 描述 | 状态 |
+| ---- | ---- | ---- |
+|      |      |      |

package/lib/components/pisellExport/docs/pisellExport.md

@@ -0,0 +1,162 @@
+---
+nav:
+  title: 组件
+  order: 1
+group:
+  title: Data Entry
+  order: 1
+title: PisellExport
+order: 1
+category: atom
+---
+
+# PisellExport 导出按钮
+
+导出触发器组件，提供「仅图标」与「图标+文案」两种形态，支持小/中/大三种尺寸与默认、主色、禁用等状态。点击后通过 `onExport` 回调由调用方实现导出请求、下载等逻辑。
+
+## 何时使用
+
+- 表格、列表的导出为 Excel/CSV
+- 报表、数据导出
+- 需要与 PisellImport 搭配使用的导入导出场景
+
+## 代码演示
+
+### 基础用法
+
+默认 Button 形态，点击后触发 `onExport`，由调用方实现导出逻辑。
+
+```tsx
+import React from 'react';
+import { PisellExport } from '@pisell/materials';
+
+export default () => {
+  return (
+    <PisellExport
+      onExport={(e) => {
+        console.log('点击导出', e);
+        // 调用方：请求导出接口、轮询、下载等
+      }}
+    />
+  );
+};
+```
+
+### 仅图标
+
+`variant="icon"` 时只显示图标，不显示文案。
+
+```tsx
+import React from 'react';
+import { PisellExport } from '@pisell/materials';
+
+export default () => {
+  return <PisellExport variant="icon" onExport={() => console.log('export')} />;
+};
+```
+
+### 三种尺寸
+
+`size` 支持 `small`、`medium`、`large`。
+
+```tsx
+import React from 'react';
+import { PisellExport } from '@pisell/materials';
+
+export default () => {
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
+      <PisellExport size="small" onExport={() => {}} />
+      <PisellExport size="medium" onExport={() => {}} />
+      <PisellExport size="large" onExport={() => {}} />
+    </div>
+  );
+};
+```
+
+### 默认与主色
+
+`type="default"` 为灰边样式，`type="primary"` 为主色描边样式。
+
+```tsx
+import React from 'react';
+import { PisellExport } from '@pisell/materials';
+
+export default () => {
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
+      <PisellExport type="default" onExport={() => {}} />
+      <PisellExport type="primary" onExport={() => {}} />
+    </div>
+  );
+};
+```
+
+### 禁用
+
+`disabled` 为 true 时不可点击。
+
+```tsx
+import React from 'react';
+import { PisellExport } from '@pisell/materials';
+
+export default () => {
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
+      <PisellExport disabled onExport={() => {}} />
+      <PisellExport type="primary" disabled onExport={() => {}} />
+    </div>
+  );
+};
+```
+
+### 自定义文案与图标
+
+通过 `label`、`icon` 自定义按钮文案和图标。
+
+```tsx
+import React from 'react';
+import { PisellExport } from '@pisell/materials';
+import { DownloadOutlined } from '@ant-design/icons';
+
+export default () => {
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
+      <PisellExport label="导出 Excel" onExport={() => {}} />
+      <PisellExport
+        icon={<DownloadOutlined style={{ fontSize: 20 }} />}
+        label="下载"
+        onExport={() => {}}
+      />
+    </div>
+  );
+};
+```
+
+## API
+
+### PisellExport Props
+
+| 参数      | 说明                     | 类型                                              | 默认值    | 必填 |
+| --------- | ------------------------ | ------------------------------------------------- | --------- | ---- |
+| variant   | 展示形态                 | `'icon' \| 'button'`                             | `'button'` | ❌   |
+| size      | 尺寸                     | `'small' \| 'medium' \| 'large'`                 | `'medium'` | ❌   |
+| type      | 视觉类型                 | `'default' \| 'primary'`                         | `'default'` | ❌   |
+| disabled  | 是否禁用                 | `boolean`                                         | `false`   | ❌   |
+| label     | Button 形态文案           | `ReactNode`                                       | 国际化默认 | ❌   |
+| icon      | 自定义图标               | `ReactNode`                                       | 内置下载图标 | ❌   |
+| onExport  | 点击触发导出             | `(e: React.MouseEvent<HTMLElement>) => void`       | -         | ❌   |
+| className | 自定义类名               | `string`                                          | -         | ❌   |
+| style     | 自定义样式               | `CSSProperties`                                   | -         | ❌   |
+
+## 注意事项
+
+1. **回调必传**：实际使用中建议传入 `onExport`，在回调中实现导出请求、轮询、下载等逻辑，组件本身不内置导出能力
+2. **形态与尺寸**：与 PisellImport 保持一致，支持 `variant="icon"`、`size`、`type`，便于并排使用
+3. **搭配使用**：常与 PisellImport 并排使用，形成导入导出能力
+
+## 相关文档
+
+- [设计文档](./pisellExport.$tab-design.md)
+- [开发文档](./pisellExport.$tab-dev.md)
+- [测试文档](./pisellExport.$tab-test.md)

package/lib/components/pisellExport/index.d.ts

@@ -0,0 +1,2 @@
+import { ExportButtonType, PisellExportProps, SizeType, VariantType } from "./types.js";
+import { PisellExport } from "./PisellExport.js";

package/lib/components/pisellExport/types.d.ts

@@ -0,0 +1,67 @@
+import { CSSProperties, MouseEvent, ReactNode } from "react";
+
+//#region src/components/pisellExport/types.d.ts
+/**
+ * 展示形态
+ * @description icon：仅图标；button：图标 + 文案
+ */
+type VariantType = 'icon' | 'button';
+/**
+ * 尺寸
+ * @description 小、中、大三种尺寸，对应设计稿 padding 与字体
+ */
+type SizeType = 'small' | 'medium' | 'large';
+/**
+ * 视觉类型
+ * @description default：默认边框/灰字；primary：主色描边或填充
+ */
+type ExportButtonType = 'default' | 'primary';
+/**
+ * PisellExport 组件 Props
+ * @description 导出触发器 UI 组件，仅负责展示与点击回调，不内置导出逻辑
+ */
+interface PisellExportProps {
+  /**
+   * 展示形态
+   * @default 'button'
+   */
+  variant?: VariantType;
+  /**
+   * 尺寸
+   * @default 'medium'
+   */
+  size?: SizeType;
+  /**
+   * 视觉类型（默认样式 / 主色样式）
+   * @default 'default'
+   */
+  type?: ExportButtonType;
+  /**
+   * 是否禁用
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * Button 形态下的文案，不传时使用国际化默认文案
+   */
+  label?: ReactNode;
+  /**
+   * 自定义图标，不传时使用内置下载图标（download-cloud-01）
+   */
+  icon?: ReactNode;
+  /**
+   * 点击触发导出
+   * @description 由调用方在此回调中实现导出请求、轮询、下载等逻辑
+   */
+  onExport?: (e: MouseEvent<HTMLElement>) => void;
+  /**
+   * 自定义类名
+   */
+  className?: string;
+  /**
+   * 自定义样式
+   */
+  style?: CSSProperties;
+}
+//#endregion
+export { ExportButtonType, PisellExportProps, SizeType, VariantType };

package/lib/components/pisellFilter/docs/PisellFilter.md

@@ -137,7 +137,7 @@ export default Demo;
 
 ### 高级筛选模式
 
-```tsx
+```
 import {PisellFilter} from '@pisell/materials';
 
 const Demo = () => {
@@ -180,7 +180,7 @@ export default Demo;
 
 ### 混合模式
 
-```tsx
+```
 import {PisellFilter} from '@pisell/materials';
 
 const Demo = () => {

package/lib/components/pisellFind/docs/pisellFind.md

@@ -3,7 +3,7 @@ nav:
   title: 组件
   order: 1
 group:
-  title: Form Fields
+  title: Data Entry
   order: 1
 title: PisellFind
 order: 1
@@ -105,7 +105,7 @@ const filterData = (keyword: string) => {
 export default () => (
     <>
         {/* 使用 PisellFind（推荐） */}
-        <PisellFind onSearch={(keyword) => filterData(keyword)} />
+        <PisellFind onSearch={(keyword) => filterData(keyword)}/>
         {/* 等价于使用 PisellLookup */}
         <PisellLookup
             triggerType="button"

package/lib/components/pisellFloorMapLayout/PisellFloorMapLayout.d.ts

@@ -1,9 +1,8 @@
 import { FloorMapItemBase, PisellFloorMapLayoutProps, PisellFloorMapLayoutRef } from "./types.js";
 import React from "react";
 //#region src/components/pisellFloorMapLayout/PisellFloorMapLayout.d.ts
-/** 空间布局根组件：阅读/编辑、列表与平面图双模式，ref 见 {@link PisellFloorMapLayoutRef} */
 declare const PisellFloorMapLayout: <T extends FloorMapItemBase = FloorMapItemBase>(props: PisellFloorMapLayoutProps<T> & {
-  ref?: React.Ref<PisellFloorMapLayoutRef | null> | undefined;
+  ref?: React.Ref<PisellFloorMapLayoutRef> | undefined;
 }) => React.ReactElement;
 //#endregion
 export { PisellFloorMapLayout };