@pisell/materials 1.0.1048 → 1.0.1050

package/es/components/pisellImport/PisellImport.d.ts

@@ -0,0 +1,13 @@
+import { PisellImportProps } from "./types.js";
+import React from "react";
+import "./PisellImport.less";
+
+//#region src/components/pisellImport/PisellImport.d.ts
+/**
+ * PisellImport 导入触发器组件
+ *
+ * @description 点击后打开文件选择，支持 accept、multiple、maxSize 校验，选择完成后回调 onImport(files)
+ */
+declare function PisellImport(props: PisellImportProps): React.JSX.Element;
+//#endregion
+export { PisellImport };

package/es/components/pisellImport/PisellImport.js

@@ -0,0 +1,83 @@
+import { getText } from "../../locales/index.js";
+import iconfont_default from "../iconfont/index.js";
+import React, { useCallback, useRef } from "react";
+import classNames from "classnames";
+import "./PisellImport.less";
+
+//#region src/components/pisellImport/PisellImport.tsx
+/** 默认导入图标（upload-cloud，与 Export 的 download-cloud 对应） */
+const DEFAULT_ICON_TYPE = "pisell2-upload-cloud-01";
+const BYTES_PER_MB = 1024 * 1024;
+/**
+* PisellImport 导入触发器组件
+*
+* @description 点击后打开文件选择，支持 accept、multiple、maxSize 校验，选择完成后回调 onImport(files)
+*/
+function PisellImport(props) {
+	const { variant = "button", size = "medium", type = "default", disabled = false, label, icon, accept, multiple = false, maxSize, onImport, onError, className, style } = props;
+	const inputRef = useRef(null);
+	const displayLabel = label !== void 0 ? label : getText("pisell-import-button-label");
+	const iconNode = icon !== void 0 ? icon : /* @__PURE__ */ React.createElement(iconfont_default, {
+		type: DEFAULT_ICON_TYPE,
+		className: "pisell-import-icon",
+		style: {
+			fontSize: 20,
+			width: 20,
+			height: 20,
+			display: "inline-flex",
+			alignItems: "center",
+			justifyContent: "center"
+		}
+	});
+	const handleClick = useCallback((e) => {
+		var _inputRef$current;
+		if (disabled) return;
+		(_inputRef$current = inputRef.current) === null || _inputRef$current === void 0 || _inputRef$current.click();
+	}, [disabled]);
+	const handleFileChange = useCallback((e) => {
+		const { files } = e.target;
+		if (!files || files.length === 0) return;
+		const fileList = Array.from(files);
+		const maxBytes = maxSize != null ? maxSize * BYTES_PER_MB : void 0;
+		if (maxBytes != null) {
+			for (const file of fileList) if (file.size > maxBytes) {
+				const rawMsg = getText("pisell-import-error-max-size");
+				const message = typeof rawMsg === "string" ? rawMsg.replace(/\{\{maxSize\}\}/g, String(maxSize)) : `文件 ${file.name} 超过 ${maxSize}MB 限制`;
+				onError === null || onError === void 0 || onError({
+					type: "MAX_SIZE",
+					message,
+					file
+				});
+				e.target.value = "";
+				return;
+			}
+		}
+		onImport === null || onImport === void 0 || onImport(fileList, e);
+		e.target.value = "";
+	}, [
+		maxSize,
+		onImport,
+		onError
+	]);
+	const rootClass = classNames("pisell-import", `pisell-import--${variant}`, `pisell-import--${size}`, `pisell-import--${type}`, disabled && "pisell-import--disabled", className);
+	return /* @__PURE__ */ React.createElement(React.Fragment, null, /* @__PURE__ */ React.createElement("input", {
+		ref: inputRef,
+		type: "file",
+		accept,
+		multiple,
+		onChange: handleFileChange,
+		style: { display: "none" },
+		tabIndex: -1,
+		"aria-hidden": true
+	}), /* @__PURE__ */ React.createElement("button", {
+		type: "button",
+		className: rootClass,
+		style,
+		disabled,
+		onClick: handleClick,
+		"aria-label": typeof displayLabel === "string" ? displayLabel : void 0
+	}, /* @__PURE__ */ React.createElement("span", { className: "pisell-import-icon-wrap" }, iconNode), variant === "button" && /* @__PURE__ */ React.createElement("span", { className: "pisell-import-label" }, displayLabel)));
+}
+
+//#endregion
+export { PisellImport };

package/es/components/pisellImport/PisellImport.less

@@ -0,0 +1,141 @@
+// PisellImport - 导入触发器样式（与 PisellExport 一致）
+// 设计规范：边框 #D0D5DD，文案 #344054，主色 #7F56D9，阴影 0px 1px 2px rgba(16,24,40,0.05)，圆角 8px
+
+.pisell-import {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  border-radius: 8px;
+  border: 1px solid #d0d5dd;
+  background: #fff;
+  color: #344054;
+  box-shadow: 0 1px 2px rgba(16, 24, 40, 0.05);
+  cursor: pointer;
+  outline: none;
+  transition: background-color 0.2s, border-color 0.2s, color 0.2s;
+
+  /* 三尺寸统一：图标 20×20px，与文案间距 8px */
+  .pisell-import-icon-wrap {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    flex-shrink: 0;
+    width: 20px;
+    height: 20px;
+  }
+
+  .pisell-import-icon {
+    font-size: 20px !important;
+    width: 20px;
+    height: 20px;
+    display: inline-flex !important;
+    align-items: center;
+    justify-content: center;
+    line-height: 1;
+    flex-shrink: 0;
+  }
+
+  .pisell-import-label {
+    font-weight: 600;
+    white-space: nowrap;
+  }
+
+  // ----- 尺寸（与 PisellExport / Figma 一致）-----
+  // line-height：small 20 / medium 20 / large 24
+  &--small {
+    padding: 8px 14px;
+    .pisell-import-label {
+      font-size: 14px;
+      line-height: 20px;
+    }
+  }
+
+  &--medium {
+    padding: 10px 16px;
+    .pisell-import-label {
+      font-size: 14px;
+      line-height: 20px;
+    }
+  }
+
+  &--large {
+    padding: 12px 20px;
+    .pisell-import-label {
+      font-size: 16px;
+      line-height: 24px;
+    }
+  }
+
+  // Icon 形态
+  &--icon.pisell-import--small {
+    padding: 10px;
+  }
+  &--icon.pisell-import--medium {
+    padding: 10px;
+  }
+  &--icon.pisell-import--large {
+    padding: 14px;
+  }
+
+  // ----- 视觉类型：primary -----
+  &--primary {
+    border-color: #7f56d9;
+    color: #344054;
+    background: #fff;
+
+    &:hover:not(.pisell-import--disabled) {
+      border-color: #7f56d9;
+      background: #f9f5ff;
+      color: #475467;
+    }
+    &:focus-visible {
+      box-shadow: 0 0 0 2px rgba(127, 86, 217, 0.2);
+    }
+    &:active:not(.pisell-import--disabled) {
+      background: #f4ebff;
+    }
+  }
+
+  &--primary .pisell-import-icon {
+    color: #7f56d9;
+  }
+
+  &--primary:hover:not(.pisell-import--disabled) .pisell-import-icon {
+    color: #7f56d9;
+  }
+
+  // ----- 默认类型 hover / focus / active -----
+  &:hover:not(.pisell-import--disabled):not(.pisell-import--primary) {
+    background: #f2f4f7;
+    border-color: #d0d5dd;
+  }
+  &:focus-visible:not(.pisell-import--primary) {
+    box-shadow: 0 0 0 2px rgba(16, 24, 40, 0.08);
+  }
+  &:active:not(.pisell-import--disabled):not(.pisell-import--primary) {
+    background: #e4e7ec;
+  }
+
+  // ----- 禁用 -----
+  &--disabled {
+    cursor: not-allowed;
+    background: #f2f4f7;
+    border-color: #e4e7ec;
+    color: #98a2b3;
+    box-shadow: none;
+  }
+
+  &--disabled .pisell-import-icon {
+    color: #98a2b3;
+  }
+
+  &--primary.pisell-import--disabled {
+    background: #f9f5ff;
+    border-color: #e9d7fe;
+    color: #98a2b3;
+  }
+  &--primary.pisell-import--disabled .pisell-import-icon {
+    color: #98a2b3;
+  }
+}

package/es/components/pisellImport/docs/pisellImport.$tab-design.md

@@ -0,0 +1,121 @@
+---
+title: 设计文档
+order: 2
+category: atom
+---
+
+# 资源链接
+
+## 任务链接
+
+ 
+
+## Figma链接
+
+Implement this design from Figma.
+@https://www.figma.com/design/pM8Ho6d7kCMv9vIBvFHUlj/Pisell-2.0-Component-Library?node-id=12671-96841&m=dev
+
+Implement this design from Figma.
+@https://www.figma.com/design/pM8Ho6d7kCMv9vIBvFHUlj/Pisell-2.0-Component-Library?node-id=12671-96860&m=dev
+
+# 1. 组件概述
+
+| **组件名称（英文）** | Import                       |
+|--------------|------------------------------|
+| **组件编号**     | pca\_de\_import\_V1.0        |
+| **组件类型**     | Atom Components              |
+| **组件分类**     | Data Entry                   |
+| **简介**       | Import 用于向数据源写入批量数据，但不关心业务校验 |
+
+# 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模板批量导入商品信息（名称、价格、库存等）</td>
+</tr>
+<tr>
+<td><strong>用户管理</strong></td>
+<td>从HR系统导出的CSV文件中批量导入员工账号信息</td>
+</tr>
+</tbody>
+</table>
+
+# 5. UI 设计
+
+## 5.1 展示样式
+
+Import 目前分为两种样式：
+
+* Icon 样式​​：显示样式只有一个icon
+
+* Button 样式​​：显示内容为icon加文本
+
+| ![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=ZWZhMThjZjIxNDU5NDI3OWYxMGU4YzU5YTJjZmM2MWJfdGNuZDNqV2pVallzVk83bU1vbzdOSE8wUTBoUkpjNlpfVG9rZW46RUNlSWJtQVdHb2NXVEd4NDNGQmNHTERqbnZkXzE3NzIwOTA2MjU6MTc3MjA5NDIyNV9WNA) | ![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=NGQ1MGU1NWIwNDUyMWQyZTE4YmI3ZjZlYWZlMDYwNThfWk9UUXNObm13SU1EWnVyN2FMWGV2Rnowa25BRkRkQzhfVG9rZW46SWNncmJ3UzZ4b1MxOUd4cG9UYWNWWFd1bjllXzE3NzIwOTA2MjU6MTc3MjA5NDIyNV9WNA) |
+|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+
+* 给到此组件的六个状态（默认样式、鼠标悬浮、focused、激活、禁用、激活禁用）样式，支持更改六个状态下的样式
+
+* 同时组件有小、中、大三中大小可供选择
+
+Implement this design from Figma.
+
+@https://www.figma.com/design/pM8Ho6d7kCMv9vIBvFHUlj/Pisell-2.0-Component-Library?node-id=12671-96693\&m=dev
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=Yjc0Zjc5YTQ3MzhjNmViM2EzNzhkZGQ4NmM5YTBjZTVfWkRHcjFqdjUwVmgyNUowRlVhbzMwUk1RMlR5R1hJWU5fVG9rZW46UzBkbmJMUndBbzhsNDR4TnR0TGNvdXFxbjllXzE3NzIwOTA2MjU6MTc3MjA5NDIyNV9WNA)
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=ODExYjU5NjYwMGE3N2Q1NTQ5OTUzNjlmMGI3ZTNiN2NfNDhzdHJZcmpPZmgwUlBTNTQ2SjY5dFdsZ3RhbFllZHdfVG9rZW46UmtQNmJZRHF6b2NEcGh4MjQwc2NLUExCbjVmXzE3NzIwOTA2MjU6MTc3MjA5NDIyNV9WNA)
+
+## 5.2 **视觉设计规范（需要主题模块完成）**
+
+### 5.2.1 颜色规范
+
+### 5.2.2 尺寸规范
+
+### 5.2.3 间距规范
+
+# 6. 配置项
+
+## 6.1 样式自定义
+
+* 按钮的外观可以自定义样式，包括背景色、边框、padding、gap、阴影
+
+* 按钮内的icon可以自定义样式，包括icon的切换、icon大小、颜色
+
+* 按钮内文本的样式可自定义，包括文本内容、文本大小、颜色、粗细
+
+* 按钮的六种不同状态的样式也可自定义
+
+## 6.2 功能配置
+
+* 可以选择按钮的大小
+
+* 可以切换按钮的样式
+
+* 可控制接受的文件类型
+
+* 可控制导入的文件最大文件大小（MB）
+
+# 7. 示例
+

package/es/components/pisellImport/docs/pisellImport.$tab-dev.md

@@ -0,0 +1,137 @@
+---
+title: 开发文档
+order: 3
+category: atom
+---
+
+# PisellImport 开发文档
+
+## 1. 基本信息
+
+| 项目     | 内容                      |
+| -------- | ------------------------- |
+| 组件名称 | PisellImport              |
+| 组件分类 | 原子组件 (atom) / Data Entry |
+| 技术栈   | React + TypeScript + Less |
+| 依赖组件 | IconFont（内置图标）、input[type=file] 隐藏触发 |
+
+## 2. 组件描述
+
+PisellImport 是导入功能的 UI 触发器组件，提供「仅图标」与「图标+文案」两种展示形态，支持小/中/大三种尺寸与默认、主色、禁用等状态。点击后打开系统文件选择框，可选择文件并做类型（accept）、大小（maxSize）校验，通过后通过 `onImport(files)` 回调将文件列表交给调用方处理上传或解析；校验失败时通过 `onError` 回调通知。
+
+**核心特点**：
+
+- 两种展示形态：Icon 样式、Button 样式（icon + 文案）
+- 与 PisellExport 一致的六种交互状态样式与三种尺寸
+- 隐藏的 `<input type="file">` 由按钮点击触发，支持 accept、multiple、maxSize 校验
+- 不内置上传/解析逻辑，由调用方在 onImport 中实现
+
+## 3. 需求点罗列
+
+### 3.1 UI 展示
+
+- [x] 支持 Icon 样式（仅图标）
+- [x] 支持 Button 样式（图标 + 文案）
+- [x] 支持小、中、大三种尺寸
+- [x] 六种状态样式：默认、悬浮、focused、激活、禁用、激活禁用
+- [x] 默认图标为 upload-cloud-01 语义（可由 icon 覆盖）
+
+### 3.2 功能
+
+- [x] 点击触发隐藏 input[type=file]，选择文件后回调 `onImport(files, e)`
+- [x] 支持 `accept` 限制文件类型
+- [x] 支持 `multiple` 多选
+- [x] 支持 `maxSize`（MB）单文件大小校验，超限时调用 `onError` 不调用 onImport
+- [x] 支持 `disabled` 禁用
+- [x] 支持自定义文案 `label`、自定义图标 `icon`
+
+### 3.3 扩展
+
+- [x] 支持 `className`、`style`
+
+## 4. 组件 API
+
+### 4.1 Props 定义
+
+| 属性       | 类型        | 默认值    | 必填 | 说明 |
+| ---------- | ----------- | --------- | ---- | ---- |
+| variant    | VariantType | 'button'  | 否   | 展示形态：icon / button |
+| size       | SizeType    | 'medium'  | 否   | 尺寸：small / medium / large |
+| type       | ImportButtonType | 'default' | 否 | 视觉类型：default / primary |
+| disabled   | boolean     | false     | 否   | 是否禁用 |
+| label      | ReactNode   | getText 或默认导入文案 | 否 | Button 形态文案 |
+| icon       | ReactNode   | 内置上传图标 | 否 | 自定义图标 |
+| accept     | string      | -         | 否   | 接受的文件类型，如 ".xlsx,.csv" |
+| multiple   | boolean     | false     | 否   | 是否多选文件 |
+| maxSize    | number      | -         | 否   | 单文件最大体积（MB），超限触发 onError |
+| onImport   | (files: File[], e: ChangeEvent) => void | - | 否 | 选择并校验通过后回调 |
+| onError    | (error: { type: 'MAX_SIZE'; message: string; file: File }) => void | - | 否 | 校验失败时回调（如超限） |
+| className  | string      | -         | 否   | 自定义类名 |
+| style      | CSSProperties | -       | 否   | 自定义样式 |
+
+### 4.2 类型定义
+
+```
+type VariantType = 'icon' | 'button';
+type SizeType = 'small' | 'medium' | 'large';
+type ImportButtonType = 'default' | 'primary';
+```
+
+## 5. 组件模块拆解
+
+```
+pisellImport/
+├── index.tsx                      # 组件导出入口
+├── PisellImport.tsx               # 组件核心实现（按钮 + 隐藏 input）
+├── PisellImport.less              # 组件样式（与 Export 一致）
+├── types.ts                       # TypeScript 类型定义
+└── docs/
+    ├── pisellImport.md
+    ├── pisellImport.$tab-design.md
+    ├── pisellImport.$tab-dev.md
+    └── pisellImport.$tab-test.md
+```
+
+### 5.1 模块职责
+
+| 模块             | 职责 |
+| ---------------- | ---- |
+| PisellImport.tsx | 渲染 button + 隐藏 input；点击 button 触发 input.click()；onChange 中做 maxSize 校验，通过则 onImport(fileList, e)，超限则 onError；应用 variant/size/type/disabled 类名 |
+| PisellImport.less| 与 PisellExport 一致的尺寸、状态样式，类名前缀 `.pisell-import` |
+| types.ts         | VariantType、SizeType、ImportButtonType、PisellImportProps |
+
+## 6. 实现方案
+
+### 6.1 结构
+
+- 根为 Fragment：内层为隐藏的 `<input type="file" ref={inputRef} accept={accept} multiple={multiple} onChange={handleFileChange} />`，以及可见的 `<button>`。
+- 点击 button 时调用 `inputRef.current?.click()` 打开文件选择。
+- Button 形态：图标 + label，类名 `pisell-import`、`pisell-import--${variant}`、`pisell-import--${size}`、`pisell-import--${type}`，disabled 时 `pisell-import--disabled`。
+
+### 6.2 文件选择与校验
+
+- `handleFileChange`：从 `e.target.files` 取 `File[]`，若存在 `maxSize` 则遍历校验，任一文件超过 `maxSize * 1024 * 1024` 字节则调用 `onError({ type: 'MAX_SIZE', message, file })`，清空 input.value 并 return；否则调用 `onImport(fileList, e)`，再清空 input.value。
+- `message` 使用 locales `getText('pisell-import-error-max-size')`，支持 `{{maxSize}}` 占位替换为数字。
+
+### 6.3 样式
+
+- 使用 Less，类名前缀 `.pisell-import`，与 PisellExport 设计一致：边框 #D0D5DD、文案 #344054、主色、圆角 8px、阴影等。
+- 尺寸：small 8px 14px、medium 10px 16px、large 12px 20px；图标 20×20px，gap 8px。
+
+### 6.4 图标与文案
+
+- 无 `icon` 时使用 IconFont `pisell2-upload-cloud-01`；无 `label` 时使用 `getText('pisell-import-button-label')`。
+
+## 7. 组成部分与引用关系
+
+```
+PisellImport
+├── <input type="file" />（隐藏，ref 触发）
+└── <button>
+    ├── 图标区域（icon 或 IconFont upload-cloud-01）
+    └── [Button 形态] 文案 (label / getText)
+```
+
+---
+
+**不包含**：上传请求、解析 Excel/CSV、进度条等；均由调用方在 `onImport` 中实现。

package/es/components/pisellImport/docs/pisellImport.$tab-test.md

@@ -0,0 +1,69 @@
+---
+title: 测试文档
+order: 4
+category: atom
+---
+
+# PisellImport 测试文档
+
+## 测试策略
+
+PisellImport 为导入触发器 UI 组件，点击打开文件选择，支持 accept、multiple、maxSize 校验，通过后回调 onImport，超限回调 onError。测试覆盖：
+
+1. **基础渲染**：默认及不同 variant/size/type 下的 DOM、类名与隐藏 input 的 accept/multiple
+2. **Props 透传**：label、icon、disabled、className、style、accept、multiple 是否生效
+3. **交互**：点击触发 input 选择、选择文件后 onImport 被调用且参数正确、maxSize 超限时 onError 被调用且不调用 onImport、disabled 时不触发
+4. **边界**：无 onImport/onError 时选择文件不报错；多选时 files 数量正确
+
+## 测试用例
+
+### 1. 基础渲染
+
+| 用例编号 | 描述 | 预期 |
+| -------- | ---- | ---- |
+| R.1 | 默认渲染（variant=button） | 根节点为 button，包含图标与默认文案（getText 或「导入」）；存在隐藏的 input[type=file] |
+| R.2 | variant=icon | 仅渲染图标，无文案节点 |
+| R.3 | size=small/medium/large | 根节点分别带类名 pisell-import--small/medium/large |
+| R.4 | type=default/primary | 根节点分别带类名 pisell-import--default/primary |
+| R.5 | disabled=true | 根节点带 pisell-import--disabled，button 的 disabled 为 true |
+| R.6 | 传入 accept | input 的 accept 属性为传入值（如 ".xlsx,.csv"） |
+| R.7 | multiple=true | input 的 multiple 为 true |
+
+### 2. Props
+
+| 用例编号 | 描述 | 预期 |
+| -------- | ---- | ---- |
+| P.1 | 传入 label | 文案区域显示传入的 label |
+| P.2 | 传入 icon | 使用传入的 icon 节点，不显示默认图标 |
+| P.3 | 传入 className | 根 button 的 class 包含该 className |
+| P.4 | 传入 style | 根 button 应用对应内联样式 |
+
+### 3. 交互
+
+| 用例编号 | 描述 | 预期 |
+| -------- | ---- | ---- |
+| I.1 | 点击且未 disabled | 触发 input 的 click（可通过 ref 或模拟用户选择文件后触发 onChange） |
+| I.2 | 选择文件且未设 maxSize | 调用 onImport 一次，第一个参数为 File[]，第二个为 ChangeEvent |
+| I.3 | 选择文件且 multiple=true | onImport 收到的 files 长度与选择数量一致 |
+| I.4 | 设置 maxSize，选择文件均未超限 | 调用 onImport，不调用 onError |
+| I.5 | 设置 maxSize，其中一文件超限 | 调用 onError 一次，参数 type 为 'MAX_SIZE'，含 message、file；不调用 onImport；input value 被清空 |
+| I.6 | disabled 时点击 | 不触发 input.click（或点击无效） |
+| I.7 | 未传入 onImport 时选择文件 | 不报错，不抛错 |
+| I.8 | 未传入 onError 时 maxSize 超限 | 不报错，不调用 onImport |
+
+### 4. 人工测试点（Storybook）
+
+- 各尺寸、各类型在 Chrome 下视觉与设计稿一致，与 PisellExport 对齐
+- hover / focus / active 状态样式正常
+- 禁用态灰化、不可点击
+- 点击后系统文件选择框弹出，选择文件后回调行为符合预期；超限时仅 onError、不 onImport
+
+---
+
+## bug 汇总
+
+（人工测试阶段将发现的 bug 记录于此）
+
+| 日期 | 描述 | 状态 |
+| ---- | ---- | ---- |
+|      |      |      |