@pisell/materials 1.8.38 → 1.8.41

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

@@ -0,0 +1,148 @@
+---
+title: 设计文档
+order: 2
+category: atom
+---
+
+# 资源链接
+
+## 任务链接
+
+ 
+
+## Figma链接
+
+Implement this design from Figma.
+@https://www.figma.com/design/pM8Ho6d7kCMv9vIBvFHUlj/Pisell-2.0-Component-Library?node-id=1624-526&m=dev
+
+# 1. 组件概述
+
+| **组件名称（英文）** | Action Panel                                                                                                                                                     |
+|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **组件编号**     | pcp\_ge\_actionPanel\_V1.0                                                                                                                                       |
+| **组件类型**     | Pro Components                                                                                                                                                   |
+| **组件分类**     | General                                                                                                                                                          |
+| **简介**<br /> | Action Panel 是一个用于统一承载、编排和呈现一组用户可执行操作（Actions）的Pro组件。<br />它不直接绑定业务数据，而是通过标准化 Action 结构，处理操作的布局、分组、层级、状态、权限以及多终端自适应。<br />Action Panel 是行为编排容器，而不是 Button 的简单集合。 |
+
+# 2. 版本
+
+| **版本**   | 1.0  |
+|----------|------|
+| **更新简介** | 首次发布 |
+
+# 3. 组件设计目的
+
+* 统一页面操作区范式，避免按钮随意堆叠&#x20;
+
+* 解耦“行为语义”与“视觉表现”
+
+* 支持复杂业务（权限/条件显隐 /危险操作）
+
+* 适配低代码/无代码配置体系
+
+# 4. 适用场景
+
+* 表单页底部操作区
+
+* 详情页主/次操作区
+
+* 列表页批量操作区
+
+* 弹窗 / Drawer 操作区
+
+* Kiosk /POS 大按钮操作区
+
+# 5. 组件能力说明
+
+### 核心能力
+
+* Action 分组与对齐
+
+* 主/次/危险操作层级
+
+* 条件显隐与权限控制
+
+* 二次确认（Confirm）
+
+* 响应式与终端策略
+
+* 操作溢出自动收纳
+
+# 6. UI 设计
+
+## 6.1 组件结构
+
+* Action Panel（Pro）
+
+  * Action Group （1..n）
+
+    * Action Item （1..n）
+
+      * Button / IconButton / MenuItem（Atom）
+
+## 6.2 展示样式
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=YTc3MTQ0ZTM1MTAxNjE0NDRjM2UwZmQ2NTlmZGU1YmJfMVI3OWZzbnBzaXl1bTNBYjlEalNvQkg0V2NQMjl3VzBfVG9rZW46R3c2cWJlQVJvb2JlTjB4S3FpZ2MyckZhbndiXzE3NzI5OTE1MTM6MTc3Mjk5NTExM19WNA)
+
+## 6.3 **视觉设计规范（需要主题模块完成）**
+
+### 6.3.1 颜色规范
+
+### 6.3.2 尺寸规范
+
+### 6.3.3 间距规范
+
+# 7. 配置项
+
+## 7.1 低代码配置项
+
+### 7.1.1 Panel级
+
+* 布局方式layout：horizontal / vertical /grid
+
+* 对齐方式align：left / center / right /space-between
+
+* 溢出策略overflowStrategy：wrap / scroll / moreMenu
+
+* 响应策略responsiveStrategy：PC/ Mobile / Kiosk 策略
+
+* 组间距自定义
+
+* 操作间距自定义
+
+* 背景边框圆角阴影样式自定义
+
+### 7.1.2 Action Group
+
+* 组内对齐方式
+
+* 优先级priority：primary / secondary / danger
+
+* 条件显隐visible
+
+* 是否进入更多collapseToMore
+
+* 背景边框圆角阴影样式自定义
+
+### 7.1.3 Action Item
+
+* 文案自定义
+
+* 图标更换自定义
+
+* button样式自定义
+
+## 7.2 无代码配置项
+
+* 操作显隐开关
+
+* 操作排序
+
+* 移动到「更多」
+
+* 设置默认主操作
+
+* 保存为个人/ 页面 / 商家 View
+
+# 8. 示例
+

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

@@ -0,0 +1,53 @@
+---
+title: 开发文档
+order: 3
+category: atom
+---
+
+# PisellActionPanel 开发文档
+
+## 1. 基础信息
+
+- **组件名称**：PisellActionPanel（Action Panel）
+- **组件版本**：1.0
+- **组件分类**：Pro Components / General
+- **依赖**：Ant Design Button、Space；无业务数据绑定。
+
+## 2. 需求点罗列
+
+1. **分组**：支持多组 Action Group，每组内多条 Action Item；顺序即展示顺序。
+2. **布局**：layout 支持 horizontal / vertical / grid；align 支持 left / center / right / space-between。
+3. **层级**：单条 item 支持 priority：primary / secondary / danger / default，映射为 Button type 与 danger。
+4. **条件显隐**：Group 与 Item 均支持 visible，过滤后仅渲染可见项。
+5. **溢出**：overflowStrategy 支持 wrap（换行）、scroll（横向滚动）、moreMenu（后续可扩展收纳到「更多」）。
+6. **间距**：groupGap（组间）、itemGap（组内项间）可配置。
+
+## 3. 组件描述
+
+PisellActionPanel 是行为编排容器，通过 groups 配置多组、每组多条操作项，统一处理布局、对齐、主/次/危险样式与显隐，适用于表单底部、详情页、弹窗等操作区。
+
+## 4. 组件 API 罗列
+
+- **groups**：PisellActionPanelGroup[]，必填；每组含 items: PisellActionPanelItem[]。
+- **layout**：horizontal | vertical | grid，默认 horizontal。
+- **align**：left | center | right | space-between，默认 left。
+- **overflowStrategy**：wrap | scroll | moreMenu，默认 wrap。
+- **groupGap**、**itemGap**：间距；itemGap 默认 8。
+- **className**、**style**：根节点扩展。
+
+## 5. 模块拆解与实现方案
+
+### 5.1 组成
+
+- 根节点：.pisell-action-panel-root，flex/grid，根据 layout/align 设置 direction 与 justify-content。
+- 每组：.pisell-action-panel-group，内嵌 antd Space，Space 的 size=itemGap，direction 随 layout。
+- 每条操作：antd Button，type/danger 由 item.priority 映射；icon + label。
+
+### 5.2 数据流
+
+- groups 先过滤 visible !== false 的 group，再过滤每组内 visible !== false 的 item，得到 effectiveGroups。
+- effectiveGroups 映射为若干 .pisell-action-panel-group，每组内 items 映射为 Button。
+
+### 5.3 样式约定
+
+- 类名前缀 pisell-action-panel-；不设置 font-family；覆盖 antd 时使用 pisell-lowcode-xxx。

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

@@ -0,0 +1,64 @@
+---
+title: 测试文档
+order: 4
+category: atom
+---
+
+# PisellActionPanel 组件测试用例文档
+
+## 测试概览
+
+本文档列出 PisellActionPanel 组件的测试用例点，基于 types.ts 与组件实现。
+
+---
+
+## 一、基础渲染测试
+
+| 测试项 | 测试步骤 | 预期结果 | 测试类型 |
+|--------|---------|---------|---------|
+| 根节点渲染 | 传入一组一条 item | 存在 .pisell-action-panel-root | 自动化 |
+| 单条操作渲染 | groups=[{ items: [{ label: '确定' }] }] | 页面显示「确定」按钮 | 自动化 |
+| 多组渲染 | 传入两组，每组若干 item | 两组均渲染，顺序正确 | 自动化 |
+| primary 样式 | item priority='primary' | 按钮为主按钮样式（type=primary） | 自动化 |
+| danger 样式 | item priority='danger' | 按钮为危险样式（danger） | 自动化 |
+| className 合并 | 传入 className="custom" | 根节点 class 包含 custom | 自动化 |
+| style 透传 | 传入 style={{ padding: 16 }} | 根节点应用对应样式 | 自动化 |
+
+---
+
+## 二、显隐测试
+
+| 测试项 | 测试步骤 | 预期结果 | 测试类型 |
+|--------|---------|---------|---------|
+| item visible=false | 某条 item 设置 visible: false | 该条不渲染 | 自动化 |
+| group visible=false | 某组设置 visible: false | 该组整组不渲染 | 自动化 |
+| 整组 items 均不可见 | 组内所有 item visible: false | 该组不占位（过滤后组为空） | 自动化 |
+
+---
+
+## 三、布局与对齐测试
+
+| 测试项 | 测试步骤 | 预期结果 | 测试类型 |
+|--------|---------|---------|---------|
+| layout=horizontal | layout='horizontal' | 根节点含 layout-horizontal，组横向排 | 自动化 |
+| layout=vertical | layout='vertical' | 根节点含 layout-vertical | 自动化 |
+| align=right | align='right' | 根节点含 align-right，justify-content: flex-end | 自动化 |
+| align=space-between | align='space-between' | 根节点含 align-space-between | 自动化 |
+
+---
+
+## 四、交互测试
+
+| 测试项 | 测试步骤 | 预期结果 | 测试类型 |
+|--------|---------|---------|---------|
+| 点击触发 onClick | item 配置 onClick 为 jest.fn()，点击该按钮 | onClick 被调用一次 | 自动化 |
+| disabled 不触发 | item disabled: true，点击 | onClick 不触发 | 自动化 |
+
+---
+
+## 五、间距测试
+
+| 测试项 | 测试步骤 | 预期结果 | 测试类型 |
+|--------|---------|---------|---------|
+| itemGap 生效 | 传入 itemGap={16} | Space size 为 16 | 自动化 |
+| groupGap 生效 | 传入 groupGap={24} | 根节点 gap 为 24px | 自动化 |

package/es/components/pisellActionPanel/docs/pisellActionPanel.md

@@ -0,0 +1,160 @@
+---
+nav:
+  title: 组件
+  order: 1
+group:
+  title: General
+  order: 1
+title: PisellActionPanel
+order: 1
+category: atom
+---
+
+# PisellActionPanel 操作面板
+
+用于统一承载、编排和呈现一组用户可执行操作（Actions）的 Pro 组件。不直接绑定业务数据，通过标准化 Action 结构处理操作的布局、分组、层级、状态与条件显隐。
+
+## 设计文档
+
+详见 [设计文档](./pisellActionPanel.$tab-design.md)。
+
+## 何时使用
+
+- 表单页底部操作区
+- 详情页主/次操作区
+- 列表页批量操作区
+- 弹窗 / Drawer 操作区
+
+## 代码示例
+
+### 基础用法（单组）
+
+```tsx
+import { PisellActionPanel } from '@pisell/materials';
+
+export default function Demo() {
+  return (
+    <PisellActionPanel
+      groups={[
+        {
+          items: [
+            { label: '取消', onClick: () => console.log('取消') },
+            { label: '提交', priority: 'primary', onClick: () => console.log('提交') },
+          ],
+        },
+      ]}
+    />
+  );
+}
+```
+
+### 分组与主/次/危险
+
+```tsx
+import { PisellActionPanel } from '@pisell/materials';
+import { DeleteOutlined, EditOutlined } from '@ant-design/icons';
+
+export default function Demo() {
+  return (
+    <PisellActionPanel
+      groups={[
+        {
+          items: [
+            { label: '编辑', icon: <EditOutlined />, onClick: () => console.log('编辑') },
+            { label: '删除', icon: <DeleteOutlined />, priority: 'danger', onClick: () => console.log('删除') },
+          ],
+        },
+        {
+          items: [
+            { label: '取消', onClick: () => console.log('取消') },
+            { label: '确定', priority: 'primary', onClick: () => console.log('确定') },
+          ],
+        },
+      ]}
+      align="right"
+      groupGap={16}
+      itemGap={8}
+    />
+  );
+}
+```
+
+### 竖向布局
+
+```tsx
+import { PisellActionPanel } from '@pisell/materials';
+
+export default function Demo() {
+  return (
+    <PisellActionPanel
+      layout="vertical"
+      groups={[
+        {
+          items: [
+            { label: '主操作', priority: 'primary', onClick: () => {} },
+            { label: '次操作', onClick: () => {} },
+          ],
+        },
+      ]}
+    />
+  );
+}
+```
+
+### 条件显隐
+
+```tsx
+import { PisellActionPanel } from '@pisell/materials';
+
+export default function Demo() {
+  const showDanger = true;
+  return (
+    <PisellActionPanel
+      groups={[
+        {
+          items: [
+            { label: '保存', priority: 'primary', onClick: () => {}, visible: true },
+            { label: '删除', priority: 'danger', onClick: () => {}, visible: showDanger },
+          ],
+        },
+      ]}
+    />
+  );
+}
+```
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| groups | 操作分组列表 | PisellActionPanelGroup[] | - |
+| layout | 布局方式 | 'horizontal' \| 'vertical' \| 'grid' | 'horizontal' |
+| align | 整体对齐方式 | 'left' \| 'center' \| 'right' \| 'space-between' | 'left' |
+| overflowStrategy | 溢出策略 | 'wrap' \| 'scroll' \| 'moreMenu' | 'wrap' |
+| groupGap | 组间距 | number \| string | - |
+| itemGap | 组内项间距 | number \| string | 8 |
+| className | 根节点类名 | string | - |
+| style | 根节点样式 | CSSProperties | - |
+
+### PisellActionPanelGroup
+
+| 属性 | 说明 | 类型 |
+|------|------|------|
+| items | 本组操作项 | PisellActionPanelItem[] |
+| key | 唯一 key | string |
+| priority | 组内默认层级 | ActionPanelItemPriority |
+| visible | 是否显示该组 | boolean |
+| align | 组内对齐 | 'start' \| 'center' \| 'end' |
+
+### PisellActionPanelItem
+
+| 属性 | 说明 | 类型 |
+|------|------|------|
+| label | 文案 | string |
+| icon | 图标 | ReactNode |
+| onClick | 点击回调 | () => void |
+| disabled | 是否禁用 | boolean |
+| visible | 是否显示 | boolean |
+| priority | 主/次/危险 | 'primary' \| 'secondary' \| 'danger' \| 'default' |
+
+更多见 [types.ts](../types.ts)。

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

@@ -0,0 +1,2 @@
+import { ActionPanelAlign, ActionPanelItemPriority, ActionPanelLayout, ActionPanelOverflowStrategy, PisellActionPanelGroup, PisellActionPanelItem, PisellActionPanelProps } from "./types.js";
+import { PisellActionPanel } from "./PisellActionPanel.js";

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

@@ -0,0 +1,87 @@
+import { CSSProperties, ReactNode } from "react";
+
+//#region src/components/pisellActionPanel/types.d.ts
+/**
+ * 操作项层级（主/次/危险）
+ */
+type ActionPanelItemPriority = 'primary' | 'secondary' | 'danger' | 'default';
+/**
+ * Action Panel 单条操作项
+ * 对应设计文档 Action Item，可渲染为 Button / IconButton
+ */
+interface PisellActionPanelItem {
+  /** 唯一 key，用于 React key；不传则用 index */
+  key?: string;
+  /** 展示文案（Button 时显示） */
+  label?: string;
+  /** 图标节点（可单独图标或与 label 同显） */
+  icon?: ReactNode;
+  /** 点击回调 */
+  onClick?: () => void;
+  /** 是否禁用 */
+  disabled?: boolean;
+  /** 是否显示（条件显隐） @default true */
+  visible?: boolean;
+  /** 层级：主/次/危险/默认，影响按钮样式 */
+  priority?: ActionPanelItemPriority;
+  /** 单项内联样式 */
+  style?: CSSProperties;
+  /** 单项类名 */
+  className?: string;
+}
+/**
+ * Action Panel 分组
+ * 对应设计文档 Action Group，内包含多个 Action Item
+ */
+interface PisellActionPanelGroup {
+  /** 唯一 key；不传则用 index */
+  key?: string;
+  /** 本组操作项 */
+  items: PisellActionPanelItem[];
+  /** 组内整体优先级（可影响组内按钮默认 priority） */
+  priority?: ActionPanelItemPriority;
+  /** 是否显示该组 @default true */
+  visible?: boolean;
+  /** 组内对齐方式（组内多个 item 时的对齐） */
+  align?: 'start' | 'center' | 'end';
+  /** 组容器类名 */
+  className?: string;
+  /** 组容器样式 */
+  style?: CSSProperties;
+}
+/**
+ * Panel 布局方式
+ */
+type ActionPanelLayout = 'horizontal' | 'vertical' | 'grid';
+/**
+ * Panel 对齐方式
+ */
+type ActionPanelAlign = 'left' | 'center' | 'right' | 'space-between';
+/**
+ * 溢出策略：换行 / 滚动 / 更多菜单收纳
+ */
+type ActionPanelOverflowStrategy = 'wrap' | 'scroll' | 'moreMenu';
+/**
+ * PisellActionPanel 组件 Props
+ * 设计文档：Action Panel (pcp_ge_actionPanel_V1.0)
+ */
+interface PisellActionPanelProps {
+  /** 操作分组列表，顺序即展示顺序 */
+  groups: PisellActionPanelGroup[];
+  /** 布局方式 @default 'horizontal' */
+  layout?: ActionPanelLayout;
+  /** 整体对齐方式 @default 'left' */
+  align?: ActionPanelAlign;
+  /** 溢出策略 @default 'wrap' */
+  overflowStrategy?: ActionPanelOverflowStrategy;
+  /** 组与组之间的间距（CSS gap 或 number px） */
+  groupGap?: number | string;
+  /** 组内操作项之间的间距（CSS gap 或 number px） */
+  itemGap?: number | string;
+  /** 根节点类名 */
+  className?: string;
+  /** 根节点样式 */
+  style?: CSSProperties;
+}
+//#endregion
+export { ActionPanelAlign, ActionPanelItemPriority, ActionPanelLayout, ActionPanelOverflowStrategy, PisellActionPanelGroup, PisellActionPanelItem, PisellActionPanelProps };

package/es/components/pisellAppCard/PisellAppCard.js

@@ -1,7 +1,7 @@
 import PisellCard from "../pisellCard/index.js";
-import PisellAvatar from "../pisellAvatar/index.js";
 import icon_default from "../icon/index.js";
 import PisellTags from "../pisellTags/index.js";
+import PisellAvatar from "../pisellAvatar/index.js";
 import React from "react";
 import { Button, Dropdown } from "antd";
 import classNames from "classnames";

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

@@ -0,0 +1,20 @@
+import { PisellBaseCardProps } from "./types.js";
+import React from "react";
+//#region src/components/pisellBaseCard/PisellBaseCard.d.ts
+/**
+ * PisellBaseCard 基础卡片容器
+ * 提供可定制的容器用于承载子内容，支持默认/悬停/按下/禁用四态样式，可点击时支持焦点与键盘触发
+ */
+declare function PisellBaseCard({
+  children,
+  className,
+  style,
+  hoverStyle,
+  activeStyle,
+  disabledStyle,
+  clickable,
+  disabled,
+  onClick
+}: PisellBaseCardProps): React.JSX.Element;
+//#endregion
+export { PisellBaseCard };

package/es/components/pisellBaseCard/PisellBaseCard.js

@@ -0,0 +1,73 @@
+import { _objectSpread2 } from "../../_virtual/_@oxc-project_runtime@0.122.0/helpers/objectSpread2.js";
+import React, { useCallback, useState } from "react";
+import classNames from "classnames";
+import "./PisellBaseCard.less";
+//#region src/components/pisellBaseCard/PisellBaseCard.tsx
+/**
+* 合并默认样式与状态样式
+*/
+function mergeStateStyle(base, hover, active, disabled, isHover, isActive, isDisabled) {
+	let s = _objectSpread2({}, base);
+	if (isDisabled && disabled) {
+		Object.assign(s, disabled);
+		return s;
+	}
+	if (isActive && active) Object.assign(s, active);
+	if (isHover && hover) Object.assign(s, hover);
+	return s;
+}
+/**
+* PisellBaseCard 基础卡片容器
+* 提供可定制的容器用于承载子内容，支持默认/悬停/按下/禁用四态样式，可点击时支持焦点与键盘触发
+*/
+function PisellBaseCard({ children, className, style, hoverStyle, activeStyle, disabledStyle, clickable = true, disabled = false, onClick }) {
+	const [isHover, setIsHover] = useState(false);
+	const [isActive, setIsActive] = useState(false);
+	const mergedStyle = mergeStateStyle(style, hoverStyle, activeStyle, disabledStyle, isHover, isActive, disabled);
+	const handleClick = useCallback((e) => {
+		if (!clickable || disabled) return;
+		onClick === null || onClick === void 0 || onClick(e);
+	}, [
+		clickable,
+		disabled,
+		onClick
+	]);
+	const handleKeyDown = useCallback((e) => {
+		if (!clickable || disabled) return;
+		if (e.key === "Enter" || e.key === " ") {
+			e.preventDefault();
+			e.target.click();
+		}
+	}, [clickable, disabled]);
+	const handlePointerEnter = useCallback(() => {
+		if (!disabled) setIsHover(true);
+	}, [disabled]);
+	const handlePointerLeave = useCallback(() => {
+		setIsHover(false);
+		setIsActive(false);
+	}, []);
+	const handlePointerDown = useCallback(() => {
+		if (clickable && !disabled) setIsActive(true);
+	}, [clickable, disabled]);
+	const handlePointerUp = useCallback(() => {
+		setIsActive(false);
+	}, []);
+	const canInteract = clickable && !disabled;
+	return /* @__PURE__ */ React.createElement("div", {
+		className: classNames("pisell-base-card-root", className),
+		style: mergedStyle,
+		"data-clickable": clickable,
+		"data-disabled": disabled,
+		role: canInteract ? "button" : void 0,
+		"aria-disabled": disabled ? true : void 0,
+		tabIndex: canInteract ? 0 : void 0,
+		onClick: handleClick,
+		onKeyDown: handleKeyDown,
+		onPointerEnter: handlePointerEnter,
+		onPointerLeave: handlePointerLeave,
+		onPointerDown: handlePointerDown,
+		onPointerUp: handlePointerUp
+	}, children);
+}
+//#endregion
+export { PisellBaseCard };

package/es/components/pisellBaseCard/PisellBaseCard.less

@@ -0,0 +1,25 @@
+/**
+ * PisellBaseCard 样式
+ * 默认态依设计稿写死：背景 #FFF、边框 #EAECF0、圆角 12px、padding 16px、阴影
+ */
+.pisell-base-card-root {
+  box-sizing: border-box;
+  /* 设计稿默认：背景、边框、圆角、内边距、阴影 */
+  background-color: #ffffff;
+  border: 1px solid #eaecf0;
+  border-radius: 12px;
+  padding: 16px;
+  box-shadow: 0 1px 2px 0 rgba(16, 24, 40, 0.05);
+  /* 最小 padding 避免内容贴边 */
+  min-height: 0;
+  min-width: 0;
+
+  /* 可点击时鼠标指针 */
+  &[data-clickable='true'] {
+    cursor: pointer;
+  }
+
+  &[data-disabled='true'] {
+    cursor: not-allowed;
+  }
+}