@pisell/materials 1.8.38 → 1.8.41

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

@@ -0,0 +1,144 @@
+# 资源链接
+
+## 任务链接
+
+ 
+
+## Figma链接
+
+Implement this design from Figma.
+@https://www.figma.com/design/pM8Ho6d7kCMv9vIBvFHUlj/Pisell-2.0-Component-Library?node-id=431-1221&m=dev
+
+# 1. 组件概述
+
+| **组件名称（英文）** | Base Card                          |
+|--------------|------------------------------------|
+| **组件编号**     | pca\_dd\_baseCard\_V1.0            |
+| **组件类型**     | Atom Components                    |
+| **组件分类**     | Data Display                       |
+| **简介**       | 基础卡片容器组件，提供高度可定制的容器用于承载和组织任意类型的子内容 |
+
+# 2. 版本
+
+| **版本**   | 1.0  |
+|----------|------|
+| **更新简介** | 首次发布 |
+
+# 3. 组件设计目的
+
+1. 信息分组展示
+
+2. 内容卡片式布局
+
+3. 作为更复杂Pro组件的构建基础
+
+4. 创建视觉层次和焦点区域
+
+# 4. 适用场景
+
+<table>
+<thead>
+<tr>
+<th><h4>场景</h4></th>
+<th><h4>示例</h4></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><strong>电商平台</strong></td>
+<td>商品展示卡片</td>
+</tr>
+<tr>
+<td><strong>SaaS应用</strong></td>
+<td>数据卡片</td>
+</tr>
+<tr>
+<td><strong>内容平台</strong></td>
+<td>文章卡片</td>
+</tr>
+<tr>
+<td><strong>企业应用</strong></td>
+<td>仪表板卡片</td>
+</tr>
+</tbody>
+</table>
+
+# 5. UI 设计
+
+## 5.1 展示样式
+
+Base Card 可分为两部分，结构清晰：
+
+* 外层容器​​：外层为一个容器组件，可以更改显示样式
+
+* 内层插槽​​：内层为一个插槽，可往插槽中增添东西
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=ZTJiNzE3YWQwYmQ4NTZjZTE2YjQyOTU1MGRjOWMxZDZfZ0E4bXBUc0k2S1pycTg3Z0h3NHBhTFdhYlhDNVBaMExfVG9rZW46TTRDWWJJb2hGb040Sml4U1hoVGNlSVlJbnV1XzE3NzI2Nzg3Njc6MTc3MjY4MjM2N19WNA)
+
+* 给到此组件的默认四个状态（默认样式、鼠标悬浮、选中、禁用）样式，支持更改四个状态下的样式
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=NjY0YTU5MDU1YmRhOTc4ZGUxNjE5NTU0NDMxMjE5ZmNfOGozd3FTWDdKblZPMThwMWtiSHZlcmNza2pDNjZnQ0tfVG9rZW46Qmx6UWJ5YjFzb1FjU2F4SEE4NmNwcDNCblBBXzE3NzI2Nzg3Njc6MTc3MjY4MjM2N19WNA)
+
+## 5.2 自适应规则
+
+* 默认组件的宽度是跟随父集容器的宽度
+
+* 当父集容器的宽度变小，此组件的宽度也随之缩小
+
+* 此组件最小缩到padding值为2px，不能再小，确保内容与边框不重合
+
+## 5.3 **视觉设计规范（需要主题模块完成）**
+
+### 5.3.1 颜色规范
+
+### 5.3.2 尺寸规范
+
+### 5.3.3 间距规范
+
+## 5.4 基础交互规则
+
+<table>
+<thead>
+<tr>
+<th><h4>交互类型</h4></th>
+<th><h4>行为描述</h4></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><strong>悬停</strong></td>
+<td>根据hoverEffect配置变化</td>
+</tr>
+<tr>
+<td><strong>点击</strong></td>
+<td>触发onClick事件</td>
+</tr>
+</tbody>
+</table>
+
+## 5.5 复合交互逻辑
+
+* 鼠标悬停时应用动画效果
+
+* 可点击卡片支持键盘导航
+
+* 触摸设备支持轻点和长按手势
+
+# 6. 配置项
+
+## 6.1 样式自定义
+
+* 外层容器可以更改其背景色、圆角、边框、阴影的样式
+
+* 外层容器可以更改padding值
+
+* 可以更改鼠标悬停的样式、点击的样式、禁用的样式
+
+* 可更改宽度和高度，默认为跟随父集高度，也可根据内容撑满，也可固定宽高
+
+## 6.2 功能配置
+
+* 是否可点击，默认为可点击的
+
+# 7. 示例
+

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

@@ -0,0 +1,92 @@
+---
+title: 开发文档
+order: 3
+category: atom
+---
+
+# PisellBaseCard 开发文档
+
+## 1. 组件信息
+
+- **组件名称**: PisellBaseCard
+- **组件版本**: 1.0.0
+- **组件分类**: Atom Components / Data Display
+- **描述**: 基础卡片容器组件，提供高度可定制的容器用于承载和组织任意类型的子内容；支持默认/悬停/按下/禁用四种状态的样式配置，可作为更复杂 Pro 组件的构建基础。
+
+## 2. 需求点罗列
+
+1. **结构**
+   - 外层容器：可配置背景、圆角、边框、阴影、padding、宽高。
+   - 内层插槽：仅渲染 `children`，不展示占位（占位由低代码插槽处理）。
+2. **状态与样式**
+   - 四态样式可配置：默认、悬停、按下、禁用（选中态由低代码包裹类名等实现，组件无选中逻辑）。
+   - 默认态视觉：背景 #FFFFFF，边框 1px #EAECF0，圆角 12px，padding 16px，阴影 0px 1px 2px rgba(16,24,40,0.05)；先写死，后续接主题。
+3. **交互**
+   - 可配置是否可点击，默认可点击。
+   - 可点击时：支持 onClick；可 focus（Tab 聚焦，Enter/Space 触发点击）；悬停/按下应用对应样式。
+   - 禁用时应用 disabledStyle，不响应点击与焦点。
+4. **自适应**
+   - 宽度默认跟随父容器；支持通过 style 设置固定宽高或由内容撑开。
+   - 最小 padding 2px，避免内容与边框重合。
+
+## 3. 组件 API
+
+### Props 定义
+
+见 `types.ts`。核心包括：
+
+- **内容**: `children`
+- **样式**: `className`, `style`, `hoverStyle?`, `activeStyle?`, `disabledStyle?`
+- **行为**: `clickable`（默认 true）, `disabled`, `onClick`
+- 无 `hoverEffect`（本期不实现）；无 `selected`（选中由低代码处理）。
+
+## 4. 组件模块拆解
+
+1. **PisellBaseCard（主组件）**
+   - 解析 Props、合并四态样式（default / hover / active / disabled）。
+   - 使用单根 div：可点击时为 button 语义或 div + role="button" + tabIndex + 键盘事件；不可点击时为普通 div。
+   - 内层仅渲染 `children`，无占位内容。
+
+2. **样式（Less）**
+   - 默认样式写死设计稿数值；类名带 `pisell-base-card-` 前缀。
+   - 最小 padding 2px 通过 CSS 约束；状态样式优先使用 props 传入的 style/hoverStyle/activeStyle/disabledStyle 合并。
+
+## 5. 实现方案
+
+### 5.1 根节点与可访问性
+
+- 使用 `<div>` 作为根节点；当 `clickable && !disabled` 时设置 `role="button"`、`tabIndex={0}`，并在 `onKeyDown` 中对 Enter/Space 调用 `onClick`，阻止默认以避免页面滚动。
+- `disabled` 时设置 `aria-disabled="true"`，且不设置 tabIndex，不触发 onClick。
+
+### 5.2 状态样式合并
+
+- 默认应用 `style`。
+- 使用 React 状态 `isHover`、`isActive`（mousedown/pointerdown 置 true，mouseup/pointerup/leave 置 false）。
+- 当 `disabled` 时优先应用 `disabledStyle`（覆盖 style）；否则在 isActive 时合并 `activeStyle`，在 isHover 时合并 `hoverStyle`（合并顺序：style + hoverStyle + activeStyle，或 disabled 时 style + disabledStyle）。
+
+### 5.3 尺寸与自适应
+
+- 不设置默认 width/height，由父容器或 style 控制；通过 style 支持 `width: '100%'`、固定宽高或 `fit-content`。
+- 使用 Less 变量或 min padding 保证最小 2px padding（若 style 传入 padding，用 min() 或文档说明由调用方保证）。
+
+## 6. 组成部分与引用
+
+- **现有组件**: 不依赖其他 Pisell 业务组件；仅使用原生 div 与 React。
+- **样式**: 独立 Less，不依赖 antd Card；若需与 antd 区分，类名使用 `pisell-base-card-*`，覆盖 antd 时使用 `pisell-lowcode-*`。
+- **结构图**:
+
+```
+PisellBaseCard
+  └── div.pisell-base-card-root (role="button" | 无)
+        └── children
+```
+
+## 7. 扩展性
+
+- 通过 `className`、`style`、`hoverStyle`、`activeStyle`、`disabledStyle` 扩展外观。
+- 通过 `children` 承载任意内容；低代码通过插槽注入内容，组件内不渲染占位。
+
+## 8. 依赖
+
+- react
+- 无额外 npm 依赖；样式为 Less。

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

@@ -0,0 +1,86 @@
+---
+title: 测试文档
+order: 4
+category: atom
+---
+
+# PisellBaseCard 组件测试用例文档
+
+## 测试概览
+
+本文档列出 PisellBaseCard 组件的测试用例点，基于 types.ts 与组件实现。
+
+---
+
+## 一、基础渲染测试
+
+| 测试项 | 测试步骤 | 预期结果 | 测试类型 |
+|--------|---------|---------|---------|
+| 根节点渲染 | 不传 props 渲染组件 | 存在 `.pisell-base-card-root` | 自动化 |
+| 空 children | 不传 children | 根节点内无占位内容，可空渲染 | 自动化 |
+| children 渲染 | 传入 `children={<span>内容</span>}` | 根节点内显示「内容」 | 自动化 |
+| className 合并 | 传入 `className="custom"` | 根节点 class 包含 `pisell-base-card-root` 与 `custom` | 自动化 |
+| style 应用 | 传入 `style={{ padding: 8 }}` | 根节点内联样式包含 padding: 8px（与默认合并） | 自动化 |
+
+---
+
+## 二、Props 与默认值测试
+
+| 测试项 | 测试步骤 | 预期结果 | 测试类型 |
+|--------|---------|---------|---------|
+| clickable 默认 true | 不传 clickable | 根节点有 `role="button"`、`tabIndex={0}` | 自动化 |
+| disabled 默认 false | 不传 disabled | 根节点无 `aria-disabled`，可交互 | 自动化 |
+| clickable=false | 传入 `clickable={false}` | 无 role、无 tabIndex，不响应点击 | 自动化 |
+| disabled=true | 传入 `disabled={true}` | 有 `aria-disabled="true"`，不响应点击 | 自动化 |
+
+---
+
+## 三、交互与事件测试
+
+| 测试项 | 测试步骤 | 预期结果 | 测试类型 |
+|--------|---------|---------|---------|
+| onClick 触发 | clickable=true, disabled=false，传入 onClick，点击根节点 | onClick 被调用一次 | 自动化 |
+| 禁用时不触发 | disabled=true，传入 onClick，点击根节点 | onClick 不触发 | 自动化 |
+| 不可点击时不触发 | clickable=false，传入 onClick，点击根节点 | onClick 不触发 | 自动化 |
+| 键盘 Enter 触发点击 | 聚焦后按 Enter | 触发与点击相同效果（调用 onClick） | 自动化 |
+| 键盘 Space 触发点击 | 聚焦后按 Space | 触发与点击相同效果，且不滚动页面 | 自动化 |
+| 键盘其他键不触发 | 聚焦后按其他键 | 不触发 onClick | 自动化 |
+
+---
+
+## 四、状态样式测试
+
+| 测试项 | 测试步骤 | 预期结果 | 测试类型 |
+|--------|---------|---------|---------|
+| style 生效 | 传入 `style={{ backgroundColor: 'red' }}` | 根节点背景色为 red | 自动化 |
+| disabledStyle 生效 | 传入 `disabled={true}`, `disabledStyle={{ opacity: 0.5 }}` | 根节点 opacity 为 0.5 | 自动化 |
+| data 属性 | 传入 clickable/disabled 不同组合 | `data-clickable`、`data-disabled` 与 props 一致 | 自动化 |
+
+---
+
+## 五、人工测试点
+
+| 测试项 | 测试步骤 | 预期结果 |
+|--------|---------|---------|
+| 悬停样式 | 传入 hoverStyle，鼠标悬停 | 悬停时应用 hoverStyle |
+| 按下样式 | 传入 activeStyle，鼠标按下不松开 | 按下时应用 activeStyle |
+| 默认视觉 | 不传 style | 背景 #fff、边框 #eaecf0、圆角 12px、padding 16px、阴影符合设计稿 |
+| 可点击时光标 | clickable=true | 光标为 pointer |
+| 禁用时光标 | disabled=true | 光标为 not-allowed |
+| 焦点环 | Tab 聚焦可点击卡片 | 有可见焦点指示 |
+
+---
+
+## Bug 汇总
+
+### 待修复的 Bug
+
+| Bug ID | 描述 | 优先级 | 状态 | 发现时间 |
+|--------|------|--------|------|---------|
+| - | - | - | - | - |
+
+### 已修复的 Bug
+
+| Bug ID | 描述 | 优先级 | 修复时间 | 修复方案 |
+|--------|------|--------|---------|---------|
+| - | - | - | - | - |

package/es/components/pisellBaseCard/docs/pisellBaseCard.md

@@ -0,0 +1,165 @@
+---
+nav:
+  title: 组件
+  order: 1
+group:
+  title: Data Display
+  order: 1
+title: PisellBaseCard
+order: 1
+category: atom
+---
+
+# PisellBaseCard 基础卡片
+
+## 组件介绍
+
+PisellBaseCard 是基础卡片容器组件，用于承载和组织任意类型的子内容。提供默认/悬停/按下/禁用四种状态的样式配置，可作为更复杂 Pro 组件的构建基础。
+
+**核心特性**：
+
+- 仅渲染 `children`，不展示占位（占位由低代码插槽处理）
+- 支持 `style`、`hoverStyle`、`activeStyle`、`disabledStyle` 四态样式
+- 可配置是否可点击（默认可点击），可点击时支持焦点与 Enter/Space 触发
+- 无选中逻辑，选中态由低代码通过包裹类名等方式实现
+
+---
+
+## 基础用法
+
+### 简单示例
+
+```tsx
+import { PisellBaseCard } from '@pisell/materials';
+
+export default () => {
+  return (
+    <PisellBaseCard>
+      <div>卡片内容</div>
+    </PisellBaseCard>
+  );
+};
+```
+
+### 可点击与 onClick
+
+```tsx
+import { PisellBaseCard } from '@pisell/materials';
+
+export default () => {
+  return (
+    <PisellBaseCard onClick={() => console.log('clicked')}>
+      <div>点击我</div>
+    </PisellBaseCard>
+  );
+};
+```
+
+### 不可点击（仅容器）
+
+```tsx
+import { PisellBaseCard } from '@pisell/materials';
+
+export default () => {
+  return (
+    <PisellBaseCard clickable={false}>
+      <div>仅作为容器，无 role="button"</div>
+    </PisellBaseCard>
+  );
+};
+```
+
+### 禁用
+
+```tsx
+import { PisellBaseCard } from '@pisell/materials';
+
+export default () => {
+  return (
+    <PisellBaseCard disabled>
+      <div>禁用状态</div>
+    </PisellBaseCard>
+  );
+};
+```
+
+---
+
+## 样式与状态
+
+### 自定义默认样式
+
+```tsx
+import { PisellBaseCard } from '@pisell/materials';
+
+export default () => {
+  return (
+    <PisellBaseCard
+      style={{
+        backgroundColor: '#f0f5ff',
+        borderRadius: 16,
+        padding: 24,
+      }}
+    >
+      <div>自定义背景与圆角</div>
+    </PisellBaseCard>
+  );
+};
+```
+
+### 悬停与按下样式
+
+```tsx
+import { PisellBaseCard } from '@pisell/materials';
+
+export default () => {
+  return (
+    <PisellBaseCard
+      hoverStyle={{ backgroundColor: '#e6f4ff', borderColor: '#91caff' }}
+      activeStyle={{ backgroundColor: '#bae0ff' }}
+    >
+      <div>悬停/按下时有样式变化</div>
+    </PisellBaseCard>
+  );
+};
+```
+
+### 禁用样式
+
+```tsx
+import { PisellBaseCard } from '@pisell/materials';
+
+export default () => {
+  return (
+    <PisellBaseCard disabled disabledStyle={{ opacity: 0.6 }}>
+      <div>禁用时透明度降低</div>
+    </PisellBaseCard>
+  );
+};
+```
+
+---
+
+## API
+
+### PisellBaseCardProps
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| children | 卡片内容 | `ReactNode` | - |
+| className | 根节点类名 | `string` | - |
+| style | 默认状态内联样式 | `CSSProperties` | - |
+| hoverStyle | 悬停时样式覆盖 | `CSSProperties` | - |
+| activeStyle | 按下时样式覆盖 | `CSSProperties` | - |
+| disabledStyle | 禁用时样式覆盖 | `CSSProperties` | - |
+| clickable | 是否可点击（可聚焦并触发 onClick） | `boolean` | `true` |
+| disabled | 是否禁用 | `boolean` | `false` |
+| onClick | 点击回调 | `(e: React.MouseEvent<HTMLDivElement>) => void` | - |
+
+---
+
+## 说明
+
+- 默认视觉：背景 `#ffffff`、边框 `1px solid #eaecf0`、圆角 `12px`、内边距 `16px`、阴影与设计稿一致；可通过 `style` 覆盖。
+- 可点击时根节点为 `role="button"`、`tabIndex={0}`，支持 Tab 聚焦与 Enter/Space 触发点击。
+- 选中态由低代码侧控制，本组件不提供 `selected` 等 props。

package/es/components/pisellBaseCard/index.d.ts

@@ -0,0 +1,2 @@
+import { PisellBaseCardProps } from "./types.js";
+import { PisellBaseCard } from "./PisellBaseCard.js";

package/es/components/pisellBaseCard/types.d.ts

@@ -0,0 +1,49 @@
+import { CSSProperties, ReactNode } from "react";
+
+//#region src/components/pisellBaseCard/types.d.ts
+/**
+ * PisellBaseCard 组件 Props
+ * @description 基础卡片容器，支持四态样式与可点击配置，无选中逻辑（选中由低代码处理）
+ */
+interface PisellBaseCardProps {
+  /**
+   * 卡片内容，由低代码插槽或直接传入
+   */
+  children?: ReactNode;
+  /**
+   * 自定义类名，应用于根节点
+   */
+  className?: string;
+  /**
+   * 默认状态下的内联样式（背景、圆角、边框、阴影、padding、宽高等）
+   */
+  style?: CSSProperties;
+  /**
+   * 悬停时的样式覆盖，与 style 合并后应用
+   */
+  hoverStyle?: CSSProperties;
+  /**
+   * 按下（active）时的样式覆盖，与 style 合并后应用
+   */
+  activeStyle?: CSSProperties;
+  /**
+   * 禁用时的样式覆盖，与 style 合并后应用
+   */
+  disabledStyle?: CSSProperties;
+  /**
+   * 是否可点击（可聚焦并触发 onClick）
+   * @default true
+   */
+  clickable?: boolean;
+  /**
+   * 是否禁用，禁用时应用 disabledStyle 且不响应点击与焦点
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * 点击回调，仅在 clickable 且非 disabled 时触发
+   */
+  onClick?: (e: React.MouseEvent<HTMLDivElement>) => void;
+}
+//#endregion
+export { PisellBaseCardProps };

package/es/components/pisellCardList/index.js

@@ -1,7 +1,7 @@
 import { _objectSpread2 } from "../../_virtual/_@oxc-project_runtime@0.122.0/helpers/objectSpread2.js";
-import PisellEmpty from "../pisellEmpty/index.js";
 import PisellCheckboxGroup from "../pisellCheckboxGroup/index.js";
 import PisellWalletPassCard from "../pisellWalletPassCard/index.js";
+import PisellEmpty from "../pisellEmpty/index.js";
 import React, { memo } from "react";
 import "./index.less";
 //#region src/components/pisellCardList/index.tsx

package/es/components/pisellCurrency/PisellCurrency.js

@@ -1,8 +1,10 @@
+import { getPisellComponentsThemeConfig } from "../../theme/pisell-components.js";
 import ReadOnlyView from "./components/ReadOnlyView.js";
 import EditView from "./components/EditView.js";
 import DisabledView from "./components/DisabledView.js";
 import React from "react";
 import { getDisplayState } from "@pisell/utils";
+import { ConfigProvider } from "antd";
 import "./PisellCurrency.less";
 //#region src/components/pisellCurrency/PisellCurrency.tsx
 /**
@@ -40,12 +42,17 @@ import "./PisellCurrency.less";
 */
 const PisellCurrency = (props) => {
 	const { mode = "edit", disabled = false } = props;
-	switch (getDisplayState(mode, disabled)) {
-		case "read": return /* @__PURE__ */ React.createElement(ReadOnlyView, props);
-		case "edit": return /* @__PURE__ */ React.createElement(EditView, props);
-		case "disabled": return /* @__PURE__ */ React.createElement(DisabledView, props);
-		default: return null;
-	}
+	const displayState = getDisplayState(mode, disabled);
+	const render = () => {
+		switch (displayState) {
+			case "read": return /* @__PURE__ */ React.createElement(ReadOnlyView, props);
+			case "edit": return /* @__PURE__ */ React.createElement(EditView, props);
+			case "disabled": return /* @__PURE__ */ React.createElement(DisabledView, props);
+			default: return null;
+		}
+	};
+	const theme = getPisellComponentsThemeConfig();
+	return /* @__PURE__ */ React.createElement(ConfigProvider, { theme }, render());
 };
 const MemoizedPisellCurrency = React.memo(PisellCurrency, (prevProps, nextProps) => {
 	return prevProps.value === nextProps.value && prevProps.mode === nextProps.mode && prevProps.disabled === nextProps.disabled && prevProps.currencySymbol === nextProps.currencySymbol && prevProps.symbolPosition === nextProps.symbolPosition;