@pisell/materials 1.8.38 → 1.8.41

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

@@ -0,0 +1,109 @@
+---
+title: 设计文档
+order: 2
+category: pro
+---
+
+# 资源链接
+
+## 任务链接
+
+ 
+
+## Figma链接
+
+Implement this design from Figma.
+@https://www.figma.com/design/pM8Ho6d7kCMv9vIBvFHUlj/Pisell-2.0-Component-Library?node-id=11133-8737&m=dev
+
+# 1. 组件概述
+
+| **组件名称（英文）** | PisellContactBrief                                                                                              |
+|--------------|-----------------------------------------------------------------------------------------------------------------|
+| **组件编号**     | pcl\_contactInfo\_V1.0                                                                                          |
+| **组件类型**     | Plus Components                                                                                                 |
+| **组件分类**     | Plus Components                                                                                                 |
+| **依赖组件**     | [ Entity Card](https://m1ed09stz4r.feishu.cn/wiki/ID7qwQrWai0mDFkEIb6c7Ymbnde)                                  |
+| **简介**       | **Contact Info** 是一个基于 **Entity Card** 的 Plus 组件，用于展示**与某个客户或组织关联的联系人（Contact）实体信息**。<br />它强调“可联系性”，而非客户级业务属性。 |
+
+# 2. 版本
+
+| **版本**   | 1.0  |
+|----------|------|
+| **更新简介** | 首次发布 |
+
+# 3. 组件设计目的
+
+* 统一联系人信息展示规范
+
+* 区分联系人与客户实体
+
+* 支持多联系人并列展示
+
+# 4. 适用场景
+
+### 适用场景
+
+* 客户详情页中的联系人列表
+
+* 表单中的联系人选择
+
+* 沟通 / 通知相关模块
+
+### 不适用场景
+
+* 客户主体展示（应使用 Customer Info）
+
+* 人员（内部员工）展示
+
+# 5. UI 设计
+
+## 5.1 展示样式
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=NjZmZjhkMmViOTY0YWQ2NDEyMTgyZjIxMmY4NzYyYzRfVEptSWdpZ3VZSTJHWWN6UEVuYkNvVUpLbkloSk5Ibk1fVG9rZW46WmlsamJwa2Z5b2U2WnJ4TzkxemN5U01wbkZjXzE3NzI3NjMyNTU6MTc3Mjc2Njg1NV9WNA)
+
+## 5.2 新建流程
+
+点击弹出弹窗
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=NzMwYmM3MDEwMDE4ZGExMmY1NzgwZWVjNDRmNTcyOWJfUEh6VU05Q1B1c0trSThZMEZqWnIwSENDMGFmVGh0Y3NfVG9rZW46WDhROWJwZEtQbzJTeWd4RWpsdWNLQnR2bmVlXzE3NzI3NjMyNTU6MTc3Mjc2Njg1NV9WNA)
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=NzE2YmUwYzBiZmQyNDM0MzYwMzVlNDRhODViNjE3MDZfQmtHQkFvblJqMnEwaWlzd05qR1lmdDVYbDJnNlRaR1pfVG9rZW46WGprOGJrOXZ0b2pZcEp4eHZpVmMzQk9ZblNiXzE3NzI3NjMyNTU6MTc3Mjc2Njg1NV9WNA)
+
+保存后展示联系人信息
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=YWRjNzFjMDdiZGY3ZWM4NWI5ZjVlYTNmMGZmNDU2ZmVfbFFaSEtuTW0wdzY3ZllYbnZLOFJUN3pyaHRRRU8xSDdfVG9rZW46R1RrMmJzZm9Qb1hMckt4UUJEOGNzSVR5bmtnXzE3NzI3NjMyNTU6MTc3Mjc2Njg1NV9WNA)
+
+## 5.3 文本换行
+
+宽度变小时，文本空间不够，自动换行，始终与右侧保持8px间距
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=YzVlMjBjYTYxNWU0MjkxZjIyZDY1MzUxODg0NDdjMWJfakpYNTZURXJEVVUzQUdTZ1lEWUtrOFAxWFZURkYydHJfVG9rZW46U3BNUWJsUEpEb01SUGt4d2UwVGNDcGxjblRmXzE3NzI3NjMyNTU6MTc3Mjc2Njg1NV9WNA)
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=MjMwYzhiN2M3ZDM0ZGU1OGM2YTJlNWEyZGIyNGRmNWRfenU3enlEbjJhS1cyRFU5VnpzM2UzcHNvZjR3ekI4ZWNfVG9rZW46SlplYWJPUXNub3hKWVh4TGtBSmNTQzAzbk9vXzE3NzI3NjMyNTU6MTc3Mjc2Njg1NV9WNA)
+
+## 5.4 **视觉设计规范（需要主题模块完成）**
+
+### 5.4.1 颜色规范
+
+### 5.4.2 尺寸规范
+
+### 5.4.3 间距规范
+
+# 6. 交互准则
+
+* 无头像：显示默认占位 Avatar
+
+* 文本过长：按配置进行省略
+
+# 7. 配置项
+
+## 7.1 可增加字段
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=YzFmOGYyYmVmODZhMGZjNGI3MjhkNDhmMmY5OTcyZGJfa2c3VnR3b3ZleGdZMldlT3gwb3M2VXRWSDM5R1NhZUJfVG9rZW46UUNsSmJiZzVxbzlIWFZ4QVhremNlOXZxbmtjXzE3NzI3NjMyNTU6MTc3Mjc2Njg1NV9WNA)
+
+对应的弹窗里也需要
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=YmI2YzYxZTVkZjYzYjgxYWY0NGI1N2MyZTg1NzEzZWRfRldkS0tKZHZ5WVlxWWJpWVNBOTQzQllwaUZYWFpoRFpfVG9rZW46WEo3UmJ3YUZTb1FudjF4MnE3ZGNvMjczbjZiXzE3NzI3NjMyNTU6MTc3Mjc2Njg1NV9WNA)
+
+# 8. 示例
+

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

@@ -0,0 +1,106 @@
+---
+title: 开发文档
+order: 3
+category: pro
+---
+
+# PisellContactBrief 开发文档
+
+## 1. 基础信息
+
+- **组件名称**：PisellContactBrief（Contact Info）
+- **组件版本**：1.0
+- **组件分类**：Data Display / Plus 类展示组件
+- **依赖**：基于 PisellEntityCard 封装；新建/编辑弹窗内部实现。
+
+## 2. 需求点罗列
+
+1. **联系人展示**：基于 Entity Card，展示头像（无则占位）、姓名（主文案）、电话（副标题同行）、邮箱及扩展字段（次级文案），右侧编辑图标点击调起编辑弹窗。
+2. **CreateButton**：独立导出 `PisellContactBrief.CreateButton`，点击后打开新建联系人弹窗，保存后由调用方更新数据并展示新联系人。
+3. **新建/编辑弹窗**：组件内部实现；表单含姓名、电话、邮箱 + 可配置扩展字段（key/label）；支持取消、保存；提交回调 `onSubmit`
+   回传表单值。
+4. **可增加字段**：扩展字段由 props 配置（如 `extraFields: { key, label }[]`），卡片展示顺序与弹窗表单项顺序一致。
+5. **左滑删除**：复用 PisellEntityCard 的 swipeToDelete / onDelete，无额外实现。
+6. **多语言**：使用 `locales.getText(key)`，提供中、英、繁文案（组件内 locales 文件，由业务 init 或组件内 init）。
+7. **布局与换行**：支持 horizontal/vertical；宽度不足时文本换行，与右侧保持 8px 间距。
+8. **文本过长**：按配置省略（主文案/次级文案行数限制）。
+
+## 3. 组件描述
+
+PisellContactBrief 是基于 PisellEntityCard
+的联系人简要信息展示组件，用于客户详情、表单选择、沟通模块等场景。提供联系人卡片（内置编辑入口）与“新建联系人”按钮（CreateButton），新建/编辑弹窗在组件内部实现，表单包含基础字段与可配置扩展字段。
+
+## 4. 组件 API 罗列
+
+### 4.1 PisellContactBrief（卡片）
+
+- **数据**：`name`, `phone`, `email`, `avatar`（可选）, `extraData`（扩展字段 key-value，与 extraFields 配置对应）。
+- **扩展字段配置**：`extraFields?: { key: string; label: string }[]`，顺序即展示与表单顺序。
+- **弹窗回调**：`onSubmit?: (values: ContactFormValues) => void`（编辑时提交）, `onDelete?: () => void`（左滑删除时）。
+- **显隐**：`showAvatar`, `showPhone`, `showEmail` 等（缺省按有值则展示）。
+- **布局**：`layout?: 'horizontal' | 'vertical'`，透传 Entity Card。
+- **左滑删除**：`swipeToDelete?: boolean`, `onDelete?: () => void`，透传 Entity Card。
+- **样式**：继承 BaseCard 的 className, style 等；主/次级行数限制 `primaryLineClamp`, `secondaryLineClamp`。
+- **多语言**：文案通过 locales.getText 获取，键名见 locales 文件。
+
+### 4.2 PisellContactBrief.CreateButton（新建入口）
+
+- **点击**：`onClick` 打开新建弹窗（或 `onClick?: () => void` 由调用方自行打开弹窗时，则仅渲染按钮不内置弹窗；此处采用内置弹窗方案）。
+- **新建提交**：弹窗内提交后触发 `onCreate?: (values: ContactFormValues) => void`，调用方保存数据后可将新联系人加入列表。
+- **扩展字段**：与卡片一致，通过 `extraFields` 传入，弹窗内表单项与之一致。
+- **样式**：`className`, `style`；展示“Add Contact”+ 占位头像 + plus 图标（与设计稿一致）。
+
+### 4.3 新建/编辑弹窗（内部）
+
+- **标题**：新建 / 编辑，由 getText 获取。
+- **表单**：姓名、电话、邮箱 + extraFields 中每项的 input。
+- **按钮**：取消、保存（编辑时可选删除，或删除由左滑暴露，弹窗内仅取消/保存）。
+- **受控**：visible 由内部 state 控制；CreateButton 点击设为 true，关闭设为 false；卡片编辑点击同理。
+
+## 5. 模块拆解与实现方案
+
+### 5.1 组成与引用
+
+- **PisellEntityCard**：直接复用，将 contact 数据映射为
+  media、primaryText、subtitleText、secondaryTexts；右侧操作区渲染编辑图标，点击打开编辑弹窗。
+- **PisellContactBrief**：负责数据映射、编辑弹窗 state、弹窗表单与提交/取消逻辑；左滑删除透传 Entity Card。
+- **CreateButton**：占位头像 + “Add Contact” 文案 + plus 图标，点击打开新建弹窗；弹窗表单与编辑弹窗共用组件。
+- **ContactFormModal**：内部子组件，表单含 name、phone、email + extraFields；提交触发 onCreate（新建）或 onSubmit（编辑），取消关闭弹窗。
+
+### 5.2 结构图
+
+```
+PisellContactBrief（根：PisellEntityCard）
+├── 数据映射：name → primaryText, phone → subtitleText, email + extraData → secondaryTexts
+├── 媒体区：avatar 或默认占位
+├── 右侧操作：编辑图标 → 打开 ContactFormModal（mode=edit）
+└── 左滑删除：swipeToDelete / onDelete 透传 Entity Card
+
+PisellContactBrief.CreateButton
+├── 占位 Avatar + 文案 "Add Contact" + plus 图标
+└── 点击 → 打开 ContactFormModal（mode=create）→ onCreate(values)
+
+ContactFormModal（内部）
+├── Modal 标题：新建 / 编辑（getText）
+├── Form：name, phone, email + extraFields 动态表单项
+└── 取消 / 保存（+ 可选删除，若需要）
+```
+
+### 5.3 实现要点
+
+- **数据映射**：contact.name → primaryText；contact.phone → subtitleText；contact.email + extraFields 顺序映射 extraData 到
+  secondaryTexts。
+- **无头像**：Entity Card media 使用默认占位 Avatar（src 不传即可）。
+- **弹窗复用**：新建与编辑共用 ContactFormModal，通过 mode 区分标题与提交回调（onCreate vs onSubmit）。
+- **扩展字段**：extraFields 遍历生成 Form.Item 与 secondaryTexts 项，key 与 extraData[key] 对应。
+- **多语言**：组件内维护 locales 文件（中/英/繁），键如 `pisell.contact.brief.addContact`、`pisell.contact.brief.edit`、
+  `pisell.contact.brief.modal.title.create`、`pisell.contact.brief.modal.title.edit`、`pisell.contact.brief.modal.cancel`、
+  `pisell.contact.brief.modal.save`、`pisell.contact.brief.delete` 等；使用 `locales.getText(key)`。Entity Card
+  若需多语言（如“删除”按钮文案），在 Entity Card 侧补充 locales 或由调用方通过 props 传入文案。
+- **样式**：类名前缀 `pisell-contact-brief-`；换行与 8px 间距由布局与 padding 保证。
+
+## 6. 组件通用性与扩展
+
+- 通过 extraFields + extraData 适配不同业务的可增加字段，无需改组件结构。
+- 通过 layout、行数限制适配列表与详情等不同布局。
+- 新建/编辑逻辑内聚，调用方只需提供 onCreate/onSubmit 与数据源。

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

@@ -0,0 +1,125 @@
+---
+title: 测试文档
+order: 4
+category: pro
+---
+
+# PisellContactBrief 组件测试用例文档
+
+## 测试概览
+
+本文档列出 PisellContactBrief 及 CreateButton 的测试用例点，基于 types.ts 与组件实现。
+
+---
+
+## 一、基础渲染测试（PisellContactBrief）
+
+| 测试项          | 测试步骤                                                                                     | 预期结果                                           | 测试类型 |
+|--------------|------------------------------------------------------------------------------------------|------------------------------------------------|------|
+| 根节点渲染        | 传入 name="张三"                                                                             | 存在 `.pisell-contact-brief-wrap` 且内含 EntityCard | 自动化  |
+| 姓名渲染         | 传入 name="张三"                                                                             | 页面显示「张三」                                       | 自动化  |
+| 电话渲染         | 传入 name、phone="+86 138 0000 0000"                                                        | 页面显示该电话（副标题区）                                  | 自动化  |
+| 邮箱渲染         | 传入 name、email="a@b.com"                                                                  | 页面显示该邮箱（次级文案）                                  | 自动化  |
+| 头像渲染         | 传入 avatar="https://..."                                                                  | EntityCard 媒体区显示头像                             | 自动化  |
+| 无头像占位        | 不传 avatar，传 name                                                                         | 显示默认占位 Avatar                                  | 自动化  |
+| 扩展字段渲染       | 传入 extraFields=[{ key: 'birthday', label: '生日' }]、extraData={{ birthday: '1990-01-01' }} | 次级区显示「1990-01-01」                              | 自动化  |
+| className 透传 | 传入 className="custom"                                                                    | 根或 EntityCard 应用 custom                        | 自动化  |
+| style 透传     | 传入 style                                                                                 | 样式应用到卡片                                        | 自动化  |
+
+---
+
+## 二、显隐与默认值测试
+
+| 测试项                | 测试步骤                     | 预期结果         | 测试类型 |
+|--------------------|--------------------------|--------------|------|
+| showAvatar 默认 true | 传入 name，不传 showAvatar    | 显示媒体区（占位或头像） | 自动化  |
+| showAvatar=false   | 传入 name、showAvatar=false | 不显示媒体区       | 自动化  |
+| showPhone 默认 true  | 传入 phone，不传 showPhone    | 显示电话         | 自动化  |
+| showPhone=false    | 传入 phone、showPhone=false | 不显示电话        | 自动化  |
+| showEmail=false    | 传入 email、showEmail=false | 不显示邮箱        | 自动化  |
+
+---
+
+## 三、布局测试
+
+| 测试项                  | 测试步骤                      | 预期结果             | 测试类型 |
+|----------------------|---------------------------|------------------|------|
+| layout 默认 horizontal | 不传 layout                 | EntityCard 为横向排布 | 自动化  |
+| layout=vertical      | 传入 layout="vertical"      | EntityCard 为竖向排布 | 自动化  |
+| primaryLineClamp     | 传入 primaryLineClamp={1}   | 主文案单行省略          | 自动化  |
+| secondaryLineClamp   | 传入 secondaryLineClamp={2} | 次级最多 2 行         | 自动化  |
+
+---
+
+## 四、编辑弹窗测试
+
+| 测试项                    | 测试步骤                                                | 预期结果                             | 测试类型 |
+|------------------------|-----------------------------------------------------|----------------------------------|------|
+| 编辑图标存在                 | 渲染卡片                                                | 存在编辑图标（如 EditOutlined 或对应 class） | 自动化  |
+| 点击编辑打开弹窗               | 点击编辑图标                                              | Modal 出现，标题为编辑相关文案               | 自动化  |
+| 弹窗表单含 name/phone/email | 打开编辑弹窗                                              | 表单项包含姓名、电话、邮箱                    | 自动化  |
+| 弹窗含 extraFields 表单项    | extraFields=[{ key: 'birthday', label: '生日' }]，打开编辑 | 表单中有「生日」项                        | 自动化  |
+| 提交回调 onSubmit          | 打开编辑、填写后保存，onSubmit 为 jest.fn()                     | onSubmit 被调用，参数含表单值              | 自动化  |
+| 取消关闭弹窗                 | 打开编辑后点击取消                                           | 弹窗关闭                             | 自动化  |
+
+---
+
+## 五、左滑删除测试
+
+| 测试项   | 测试步骤                           | 预期结果                    | 测试类型 |
+|-------|--------------------------------|-------------------------|------|
+| 未开启左滑 | 不传 swipeToDelete 或 false       | 无左滑删除层                  | 自动化  |
+| 开启左滑  | swipeToDelete=true、onDelete 传入 | 存在左滑容器（由 EntityCard 提供） | 自动化  |
+
+---
+
+## 六、CreateButton 测试
+
+| 测试项             | 测试步骤                                  | 预期结果                                 | 测试类型 |
+|-----------------|---------------------------------------|--------------------------------------|------|
+| CreateButton 渲染 | 渲染 PisellContactBrief.CreateButton    | 存在「Add Contact」或对应多语言文案、占位头像、plus 图标 | 自动化  |
+| 点击打开新建弹窗        | 不传 onClick，点击 CreateButton            | 新建弹窗打开，标题为新建相关                       | 自动化  |
+| 自定义 onClick     | 传入 onClick（jest.fn()），点击 CreateButton | onClick 被调用，不打开内置弹窗                  | 自动化  |
+| 新建提交 onCreate   | 打开新建弹窗、填写后保存，onCreate 为 jest.fn()     | onCreate 被调用，参数含 name 等              | 自动化  |
+
+---
+
+## 七、BaseCard 透传与事件测试
+
+| 测试项          | 测试步骤                          | 预期结果           | 测试类型 |
+|--------------|-------------------------------|----------------|------|
+| clickable 透传 | 传入 clickable=false            | 卡片不响应点击（或无点击态） | 自动化  |
+| disabled 透传  | 传入 disabled=true              | 禁用态生效          | 自动化  |
+| onClick 触发   | 传入 onClick（jest.fn()），点击卡片内容区 | onClick 被调用    | 自动化  |
+
+---
+
+## 八、人工测试点
+
+| 测试项     | 测试步骤                       | 预期结果                      |
+|---------|----------------------------|---------------------------|
+| 横向布局视觉  | layout=horizontal，姓名+电话+邮箱 | 头像在左，文案在右，编辑图标在右端，间距合理    |
+| 竖向布局视觉  | layout=vertical            | 头像在上、文案在下，居中对齐            |
+| 无头像占位样式 | 不传 avatar                  | 占位圆形区域与设计稿一致              |
+| 编辑弹窗样式  | 点击编辑                       | 弹窗标题、表单项、取消/保存按钮布局正确      |
+| 新建弹窗样式  | 点击 CreateButton            | 弹窗标题为「新建联系人」类文案，表单为空      |
+| 扩展字段在弹窗 | extraFields 含多字段，打开编辑      | 表单项顺序与 extraFields 一致     |
+| 文本换行    | 宽度收窄，电话/邮箱较长               | 文本换行，与右侧保持约 8px 间距        |
+| 左滑删除手势  | 移动端或模拟 touch，左滑卡片          | 露出删除按钮，点击触发 onDelete      |
+| 多语言     | 切换语言后渲染                    | Add Contact、编辑、保存等文案随语言变化 |
+
+---
+
+## Bug 汇总
+
+### 待修复的 Bug
+
+| Bug ID | 描述 | 优先级 | 状态 | 发现时间 |
+|--------|----|-----|----|------|
+| -      | -  | -   | -  | -    |
+
+### 已修复的 Bug
+
+| Bug ID | 描述 | 优先级 | 修复时间 | 修复方案 |
+|--------|----|-----|------|------|
+| -      | -  | -   | -    | -    |

package/es/components/PisellContactBrief/docs/PisellContactBrief.md

@@ -0,0 +1,129 @@
+---
+nav:
+  title: 组件
+  order: 1
+group:
+  title: Data Display
+  order: 1
+title: PisellContactBrief
+order: 1
+category: pro
+---
+
+# PisellContactBrief 联系人简要卡片
+
+基于 **PisellEntityCard** 的 Plus 组件，用于展示**与某个客户或组织关联的联系人（Contact）实体信息**
+。强调“可联系性”，提供姓名、电话、邮箱及扩展字段，内置编辑弹窗；另提供 CreateButton 用于新建联系人。
+
+## 设计文档
+
+详见 [设计文档](./PisellContactBrief.$tab-design.md)。
+
+## 何时使用
+
+- 客户详情、订单等模块中的联系人引用
+- 表单选择联系人
+- 沟通/协作模块中的联系人展示
+
+## 代码示例
+
+### 基础用法
+
+```tsx
+import React from 'react';
+import { PisellContactBrief } from '@pisell/materials';
+
+export default function Demo() {
+  return (
+    <PisellContactBrief
+      name="张三"
+      phone="+86 138 0000 0000"
+      email="zhangsan@example.com"
+    />
+  );
+}
+```
+
+### 带扩展字段与编辑回调
+
+```tsx
+import React from 'react';
+import { PisellContactBrief } from '@pisell/materials';
+
+export default function Demo() {
+  return (
+    <PisellContactBrief
+      name="李四"
+      phone="+86 139 0000 0000"
+      email="lisi@example.com"
+      extraFields={[{ key: 'department', label: '部门' }]}
+      extraData={{ department: '产品部' }}
+      onSubmit={(values) => console.log('提交', values)}
+    />
+  );
+}
+```
+
+### 新建联系人按钮（CreateButton）
+
+```tsx
+import React from 'react';
+import { PisellContactBrief } from '@pisell/materials';
+
+export default function Demo() {
+  return (
+    <PisellContactBrief.CreateButton
+      extraFields={[{ key: 'department', label: '部门' }]}
+      onCreate={(values) => console.log('新建', values)}
+    />
+  );
+}
+```
+
+### 左滑删除
+
+```tsx
+import React from 'react';
+import { PisellContactBrief } from '@pisell/materials';
+
+export default function Demo() {
+  return (
+    <PisellContactBrief
+      name="王五"
+      phone="+86 137 0000 0000"
+      swipeToDelete
+      onDelete={() => console.log('删除')}
+    />
+  );
+}
+```
+
+## API
+
+### PisellContactBrief（卡片）
+
+| 属性            | 说明                      | 类型                                  | 默认值          |
+|---------------|-------------------------|-------------------------------------|--------------|
+| name          | 联系人姓名（主文案）              | string                              | -            |
+| phone         | 电话（副标题）                 | string                              | -            |
+| email         | 邮箱（次级文案）                | string                              | -            |
+| avatar        | 头像地址，不传则默认占位            | string                              | -            |
+| extraData     | 扩展字段值                   | Record<string, string>              | -            |
+| extraFields   | 扩展字段配置 [{ key, label }] | ContactBriefExtraField[]            | []           |
+| onSubmit      | 编辑弹窗提交回调                | (values: ContactFormValues) => void | -            |
+| onDelete      | 左滑删除回调                  | () => void                          | -            |
+| swipeToDelete | 是否开启左滑删除                | boolean                             | false        |
+| layout        | 布局方向                    | 'horizontal' \| 'vertical'          | 'horizontal' |
+| showAvatar    | 是否显示头像                  | boolean                             | true         |
+| showPhone     | 是否显示电话                  | boolean                             | true         |
+| showEmail     | 是否显示邮箱                  | boolean                             | true         |
+
+### PisellContactBrief.CreateButton
+
+| 属性          | 说明           | 类型                                            | 默认值 |
+|-------------|--------------|-----------------------------------------------|-----|
+| extraFields | 扩展字段配置，与卡片一致 | ContactBriefExtraField[]                      | []  |
+| onCreate    | 新建弹窗提交回调     | (values: ContactFormValues) => void           | -   |
+| onClick     | 自定义点击行为      | `(e: React.MouseEvent) => void` | -   |
+
+更多见 [types.ts](../types.ts)。

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

@@ -0,0 +1,2 @@
+import { ContactBriefExtraField, ContactFormValues, PisellContactBriefComponent, PisellContactBriefCreateButtonProps, PisellContactBriefProps } from "./types.js";
+import { PisellContactBrief } from "./PisellContactBrief.js";

package/es/components/PisellContactBrief/locales.js

@@ -0,0 +1,57 @@
+//#region src/components/PisellContactBrief/locales.ts
+/**
+* PisellContactBrief 多语言文案
+* 中、英、繁；由业务 locales.init 合并或组件内 init 后使用 locales.getText(key)
+*/
+var locales_default = {
+	en: {
+		"pisell.contact.brief.addContact": "Add Contact",
+		"pisell.contact.brief.edit": "Edit",
+		"pisell.contact.brief.delete": "Delete",
+		"pisell.contact.brief.modal.title.create": "Add Contact",
+		"pisell.contact.brief.modal.title.edit": "Edit Contact",
+		"pisell.contact.brief.modal.cancel": "Cancel",
+		"pisell.contact.brief.modal.save": "Save",
+		"pisell.contact.brief.modal.field.firstname": "Firstname",
+		"pisell.contact.brief.modal.field.lastname": "Lastname",
+		"pisell.contact.brief.modal.field.phone": "Phone number",
+		"pisell.contact.brief.modal.field.email": "Email address",
+		"pisell.contact.brief.modal.field.phone.placeholder": "+1 (555) 000-0000",
+		"pisell.contact.brief.modal.field.email.placeholder": "Enter your email",
+		"pisell.contact.brief.modal.field.required": "Required"
+	},
+	"zh-CN": {
+		"pisell.contact.brief.addContact": "添加联系人",
+		"pisell.contact.brief.edit": "编辑",
+		"pisell.contact.brief.delete": "删除",
+		"pisell.contact.brief.modal.title.create": "新建联系人",
+		"pisell.contact.brief.modal.title.edit": "编辑联系人",
+		"pisell.contact.brief.modal.cancel": "取消",
+		"pisell.contact.brief.modal.save": "保存",
+		"pisell.contact.brief.modal.field.firstname": "名",
+		"pisell.contact.brief.modal.field.lastname": "姓",
+		"pisell.contact.brief.modal.field.phone": "电话",
+		"pisell.contact.brief.modal.field.email": "邮箱",
+		"pisell.contact.brief.modal.field.phone.placeholder": "请输入电话",
+		"pisell.contact.brief.modal.field.email.placeholder": "请输入邮箱",
+		"pisell.contact.brief.modal.field.required": "必填"
+	},
+	"zh-HK": {
+		"pisell.contact.brief.addContact": "添加聯繫人",
+		"pisell.contact.brief.edit": "編輯",
+		"pisell.contact.brief.delete": "刪除",
+		"pisell.contact.brief.modal.title.create": "新建聯繫人",
+		"pisell.contact.brief.modal.title.edit": "編輯聯繫人",
+		"pisell.contact.brief.modal.cancel": "取消",
+		"pisell.contact.brief.modal.save": "保存",
+		"pisell.contact.brief.modal.field.firstname": "名",
+		"pisell.contact.brief.modal.field.lastname": "姓",
+		"pisell.contact.brief.modal.field.phone": "電話",
+		"pisell.contact.brief.modal.field.email": "郵箱",
+		"pisell.contact.brief.modal.field.phone.placeholder": "請輸入電話",
+		"pisell.contact.brief.modal.field.email.placeholder": "請輸入郵箱",
+		"pisell.contact.brief.modal.field.required": "必填"
+	}
+};
+//#endregion
+export { locales_default as default };

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

@@ -0,0 +1,86 @@
+import { PisellBaseCardProps } from "../pisellBaseCard/types.js";
+import { EntityCardLayout } from "../pisellEntityCard/types.js";
+import React from "react";
+
+//#region src/components/PisellContactBrief/types.d.ts
+/**
+ * 联系人表单值（新建/编辑弹窗提交结构）
+ * 基础字段 name、phone、email + 扩展字段（与 extraFields[].key 对应）扁平在同一对象
+ */
+interface ContactFormValues {
+  /** 姓名 */
+  name: string;
+  /** 电话 */
+  phone?: string;
+  /** 邮箱 */
+  email?: string;
+  /** 扩展字段及任意表单项，key 与 extraFields 配置对应 */
+  [key: string]: string | undefined;
+}
+/**
+ * 可增加字段配置项
+ * 顺序即卡片展示与弹窗表单项顺序
+ */
+interface ContactBriefExtraField {
+  /** 字段 key，与 extraData / ContactFormValues 对应 */
+  key: string;
+  /** 展示与表单项 label（可配合多语言） */
+  label: string;
+}
+/**
+ * PisellContactBrief 组件 Props
+ * 基于 PisellEntityCard 展示联系人简要信息，内置编辑弹窗
+ */
+interface PisellContactBriefProps extends Pick<PisellBaseCardProps, 'className' | 'style' | 'hoverStyle' | 'activeStyle' | 'disabledStyle' | 'clickable' | 'disabled' | 'onClick'> {
+  /** 联系人姓名（主文案） */
+  name: string;
+  /** 电话（副标题，与姓名同行） */
+  phone?: string;
+  /** 邮箱（次级文案） */
+  email?: string;
+  /** 头像图片地址，不传则显示默认占位 */
+  avatar?: string;
+  /** 扩展字段值，key 与 extraFields 配置对应 */
+  extraData?: Record<string, string>;
+  /** 可增加字段配置，顺序即展示与表单顺序 */
+  extraFields?: ContactBriefExtraField[];
+  /** 编辑弹窗提交回调 */
+  onSubmit?: (values: ContactFormValues) => void;
+  /** 左滑删除回调（透传 Entity Card） */
+  onDelete?: () => void;
+  /** 是否开启左滑删除 @default false */
+  swipeToDelete?: boolean;
+  /** 布局方向 @default 'horizontal' */
+  layout?: EntityCardLayout;
+  /** 是否显示头像 @default true */
+  showAvatar?: boolean;
+  /** 是否显示电话 @default true */
+  showPhone?: boolean;
+  /** 是否显示邮箱 @default true */
+  showEmail?: boolean;
+  /** 主文案行数限制 */
+  primaryLineClamp?: number;
+  /** 次级文案行数限制 */
+  secondaryLineClamp?: number;
+}
+/**
+ * PisellContactBrief.CreateButton 组件 Props
+ * 点击后打开新建联系人弹窗
+ */
+interface PisellContactBriefCreateButtonProps extends Pick<PisellBaseCardProps, 'className' | 'style'> {
+  /** 可增加字段配置，与卡片一致，弹窗内表单项与之对应 */
+  extraFields?: ContactBriefExtraField[];
+  /** 新建弹窗提交回调，调用方保存数据后可更新列表 */
+  onCreate?: (values: ContactFormValues) => void;
+  /** 自定义点击行为；不传则使用内置打开新建弹窗 */
+  onClick?: (e: React.MouseEvent<HTMLDivElement>) => void;
+}
+/**
+ * 复合组件类型：PisellContactBrief + CreateButton
+ */
+interface PisellContactBriefComponent {
+  (props: PisellContactBriefProps): React.ReactElement;
+  CreateButton: React.ComponentType<PisellContactBriefCreateButtonProps>;
+}
+//#endregion
+export { ContactBriefExtraField, ContactFormValues, PisellContactBriefComponent, PisellContactBriefCreateButtonProps, PisellContactBriefProps };

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

@@ -34,7 +34,7 @@ declare const PisellLayouts: {
   BasicGrid: <T>(props: PisellBasicGridProps<T>) => _$react.JSX.Element;
   ScrollView: _$react.ForwardRefExoticComponent<Omit<PisellScrollViewProps, "ref"> & _$react.RefAttributes<PisellScrollViewRef>>;
   FloorMapLayout: <T_1 extends FloorMapItemBase = FloorMapItemBase>(props: PisellFloorMapLayoutProps<T_1> & {
-    ref?: _$react.Ref<PisellFloorMapLayoutRef | null> | undefined;
+    ref?: _$react.Ref<PisellFloorMapLayoutRef> | undefined;
   }) => _$react.ReactElement<any, string | _$react.JSXElementConstructor<any>>;
   Layout: CompoundedComponent;
   Content: _$react.FC<PisellContentProps>;

package/es/components/PisellProcedure/components/ProcedureHeader.js

@@ -2,8 +2,8 @@ import { getText } from "../../../locales/index.js";
 import { _objectSpread2 } from "../../../_virtual/_@oxc-project_runtime@0.122.0/helpers/objectSpread2.js";
 import PisellHeader from "../../pisellLayout/header.js";
 import PisellModal from "../../pisellModal/index.js";
-import { mergeClassNames } from "../utils/classNames.js";
 import PisellSteps_default from "../../PisellSteps/index.js";
+import { mergeClassNames } from "../utils/classNames.js";
 import React, { useCallback, useMemo, useState } from "react";
 //#region src/components/PisellProcedure/components/ProcedureHeader.tsx
 /**

package/es/components/PisellTabbar/PisellTabbar.js

@@ -2,8 +2,8 @@ import { getText } from "../../locales/index.js";
 import { _objectSpread2 } from "../../_virtual/_@oxc-project_runtime@0.122.0/helpers/objectSpread2.js";
 import IconFont from "../iconfont/index.js";
 import PisellCards from "../PisellCards/index.js";
-import PisellSuperTabs_default from "../PisellSuperTabs/index.js";
 import { PisellFind } from "../pisellFind/index.js";
+import PisellSuperTabs_default from "../PisellSuperTabs/index.js";
 import { DEFAULT_LEVEL_CONFIG, LEVEL_ADD_ITEMS, getExpandConfig } from "./constants.js";
 import useActiveKey from "./hooks/useActiveKey.js";
 import useExpand from "./hooks/useExpand.js";

package/es/components/PisellTabbar/template/Template1/PisellTabbar.js

@@ -2,8 +2,8 @@ import { getText } from "../../../../locales/index.js";
 import { _objectSpread2 } from "../../../../_virtual/_@oxc-project_runtime@0.122.0/helpers/objectSpread2.js";
 import IconFont from "../../../iconfont/index.js";
 import PisellCards from "../../../PisellCards/index.js";
-import PisellSuperTabs_default from "../../../PisellSuperTabs/index.js";
 import { PisellFind } from "../../../pisellFind/index.js";
+import PisellSuperTabs_default from "../../../PisellSuperTabs/index.js";
 import { getExpandConfig } from "../../constants.js";
 import useActiveKey from "../../hooks/useActiveKey.js";
 import useExpand from "../../hooks/useExpand.js";