@pisell/materials 1.8.38 → 1.8.41

package/lib/components/pisellGridPro/docs/PisellGridPro.md

@@ -12,7 +12,13 @@ category: pro
 
 # PisellGridPro 页面布局
 
-PisellGridPro 是一个强大的页面布局组件，为后台管理系统提供标准的页面结构和布局能力，帮助开发者快速搭建规范统一的页面。
+PisellGridPro 是后台管理系统的标准页面布局组件，提供统一的页头、工具栏、数据卡片、内容区与页脚结构，便于快速搭建规范一致的列表页、统计页与详情页。
+
+## 何时使用
+
+- 需要标准后台页面结构（标题栏 + 工具栏 + 内容区 + 底栏）
+- 列表页、数据统计页、详情页、工作台等需统一布局规范
+- 希望主内容区单独滚动、其余区域固定
 
 ## 设计理念
 
@@ -31,13 +37,13 @@ PisellGridPro 是一个强大的页面布局组件，为后台管理系统提供
 │  Header                                     │
 │  (标题、徽章、副标题、操作按钮)                │
 ├─────────────────────────────────────────────┤
-│  ToolBar                                    │
+│  PisellToolBar                              │
 │  (标签页、筛选器、排序等)                      │
 ├─────────────────────────────────────────────┤
 │  DataCard                                   │
 │  (统计数据卡片)                               │
 ├─────────────────────────────────────────────┤
-│  View                                       │
+│  PisellGridView                             │
 │  (主内容区，自带滚动)                          │
 │                                             │
 │                                             │
@@ -53,17 +59,17 @@ PisellGridPro 是一个强大的页面布局组件，为后台管理系统提供
 
 页面顶部标题栏，包含标题、徽章、副标题和操作按钮。
 
-### PisellGridPro.ToolBar - 工具栏组件
+### PisellToolBar - 工具栏组件
 
-灵活的工具栏组件，支持标签页和四个位置的内容区域。
+灵活的工具栏组件，支持标签页和四个位置的内容区域。需从 `@pisell/materials` 单独引入 **PisellToolBar** 使用。
 
 ### PisellGridPro.DataCard - 数据卡片组件
 
 用于展示统计数据的卡片组件，支持趋势显示。
 
-### PisellGridPro.View - 内容视图组件
+### PisellGridView - 内容视图组件
 
-主内容区域，内置滚动能力。
+主内容区域，内置滚动能力。需从 `@pisell/materials` 单独引入 **PisellGridView** 使用。
 
 ### PisellGridPro.Footer - 页脚组件
 
@@ -74,15 +80,16 @@ PisellGridPro 是一个强大的页面布局组件，为后台管理系统提供
 ### 简单页面布局
 
 ```tsx
-import { PisellGridPro } from '@pisell/materials';
+import React from 'react';
+import { PisellGridPro, PisellGridView } from '@pisell/materials';
 
 export default () => {
   return (
     <PisellGridPro>
       <PisellGridPro.Header title="页面标题" />
-      <PisellGridPro.View>
+      <PisellGridView>
         <div>主内容区域</div>
-      </PisellGridPro.View>
+      </PisellGridView>
     </PisellGridPro>
   );
 };
@@ -91,7 +98,8 @@ export default () => {
 ### 完整页面布局
 
 ```tsx
-import { PisellGridPro } from '@pisell/materials';
+import React from 'react';
+import { PisellGridPro, PisellToolBar, PisellGridView } from '@pisell/materials';
 import { Button, Badge } from 'antd';
 
 export default () => {
@@ -111,7 +119,7 @@ export default () => {
       />
 
       {/* 工具栏 */}
-      <PisellGridPro.ToolBar
+      <PisellToolBar
         topLeft={<div>筛选器</div>}
         topRight={<div>排序</div>}
         bottomLeft={<div>批量操作</div>}
@@ -139,9 +147,9 @@ export default () => {
       />
 
       {/* 内容区 */}
-      <PisellGridPro.View>
+      <PisellGridView>
         <div>订单列表内容</div>
-      </PisellGridPro.View>
+      </PisellGridView>
 
       {/* 页脚 */}
       <PisellGridPro.Footer>
@@ -155,7 +163,8 @@ export default () => {
 ### 带标签页的布局
 
 ```tsx
-import { PisellGridPro } from '@pisell/materials';
+import React from 'react';
+import { PisellGridPro, PisellToolBar, PisellGridView } from '@pisell/materials';
 import { Tabs } from 'antd';
 
 export default () => {
@@ -163,7 +172,7 @@ export default () => {
     <PisellGridPro>
       <PisellGridPro.Header title="商品管理" />
 
-      <PisellGridPro.ToolBar
+      <PisellToolBar
         tabs={
           <Tabs
             items={[
@@ -176,9 +185,9 @@ export default () => {
         topRight={<div>搜索框</div>}
       />
 
-      <PisellGridPro.View>
+      <PisellGridView>
         <div>商品列表</div>
-      </PisellGridPro.View>
+      </PisellGridView>
     </PisellGridPro>
   );
 };
@@ -187,7 +196,8 @@ export default () => {
 ### 数据统计页面
 
 ```tsx
-import { PisellGridPro } from '@pisell/materials';
+import React from 'react';
+import { PisellGridPro, PisellGridView, PisellToolBar } from '@pisell/materials';
 
 export default () => {
   const statsData = [
@@ -228,9 +238,9 @@ export default () => {
 
       <PisellGridPro.DataCard dataItems={statsData} />
 
-      <PisellGridPro.View>
+      <PisellGridView>
         <div>图表内容</div>
-      </PisellGridPro.View>
+      </PisellGridView>
     </PisellGridPro>
   );
 };
@@ -239,7 +249,8 @@ export default () => {
 ### 可点击的数据卡片
 
 ```tsx
-import { PisellGridPro } from '@pisell/materials';
+import React from 'react';
+import { PisellGridPro, PisellGridView, PisellToolBar } from '@pisell/materials';
 import { message } from 'antd';
 
 export default () => {
@@ -272,9 +283,9 @@ export default () => {
         ]}
       />
 
-      <PisellGridPro.View>
+      <PisellGridView>
         <div>详细内容</div>
-      </PisellGridPro.View>
+      </PisellGridView>
     </PisellGridPro>
   );
 };
@@ -301,7 +312,7 @@ export default () => {
 | className   | 自定义类名     | `string`        | -      | ❌   |
 | style       | 自定义样式     | `CSSProperties` | -      | ❌   |
 
-### ToolBar Props
+### PisellToolBar Props
 
 | 参数        | 说明         | 类型            | 默认值 | 必填 |
 | ----------- | ------------ | --------------- | ------ | ---- |
@@ -336,7 +347,7 @@ export default () => {
 | className     | 自定义类名       | `string`         | -            | ❌   |
 | style         | 自定义样式       | `CSSProperties`  | -            | ❌   |
 
-### View Props
+### PisellGridView Props
 
 | 参数      | 说明       | 类型            | 默认值 | 必填 |
 | --------- | ---------- | --------------- | ------ | ---- |
@@ -356,119 +367,169 @@ export default () => {
 
 ### 1. 列表页面
 
-```
-<PisellGridPro>
-  <PisellGridPro.Header title="用户列表" />
-  <PisellGridPro.ToolBar
-    topLeft={<SearchBar />}
-    topRight={<FilterButton />}
-  />
-  <PisellGridPro.View>
-    <UserTable />
-  </PisellGridPro.View>
-  <PisellGridPro.Footer>
-    <Pagination />
-  </PisellGridPro.Footer>
-</PisellGridPro>
+```tsx
+import React from 'react';
+import { PisellGridPro, PisellGridView, PisellToolBar } from '@pisell/materials';
+
+export default () => (
+  <PisellGridPro>
+    <PisellGridPro.Header title="用户列表" />
+    <PisellToolBar
+      topLeft={<div>搜索栏</div>}
+      topRight={<div>筛选</div>}
+    />
+    <PisellGridView>
+      <div>用户表格</div>
+    </PisellGridView>
+    <PisellGridPro.Footer>
+      <div>分页</div>
+    </PisellGridPro.Footer>
+  </PisellGridPro>
+);
 ```
 
 ### 2. 数据统计页面
 
-```
-<PisellGridPro>
-  <PisellGridPro.Header title="销售统计" />
-  <PisellGridPro.DataCard dataItems={statsData} />
-  <PisellGridPro.View>
-    <Charts />
-  </PisellGridPro.View>
-</PisellGridPro>
+```tsx
+import React from 'react';
+import { PisellGridPro, PisellGridView, PisellToolBar } from '@pisell/materials';
+
+const statsData = [
+  { key: '1', title: '销售额', value: '¥12,345', compareValue: '+10%', trend: 'up' as const },
+];
+
+export default () => (
+  <PisellGridPro>
+    <PisellGridPro.Header title="销售统计" />
+    <PisellGridPro.DataCard dataItems={statsData} />
+    <PisellGridView>
+      <div>图表区域</div>
+    </PisellGridView>
+  </PisellGridPro>
+);
 ```
 
 ### 3. 详情页面
 
-```
-<PisellGridPro>
-  <PisellGridPro.Header
-    title="订单详情"
-    actionsList={<Button>编辑</Button>}
-  />
-  <PisellGridPro.View>
-    <OrderDetail />
-  </PisellGridPro.View>
-  <PisellGridPro.Footer>
-    <Button>取消</Button>
-    <Button type="primary">保存</Button>
-  </PisellGridPro.Footer>
-</PisellGridPro>
+```tsx
+import React from 'react';
+import { PisellGridPro, PisellGridView, PisellToolBar } from '@pisell/materials';
+import { Button } from 'antd';
+
+export default () => (
+  <PisellGridPro>
+    <PisellGridPro.Header
+      title="订单详情"
+      actionsList={<Button>编辑</Button>}
+    />
+    <PisellGridView>
+      <div>订单详情内容</div>
+    </PisellGridView>
+    <PisellGridPro.Footer>
+      <Button>取消</Button>
+      <Button type="primary">保存</Button>
+    </PisellGridPro.Footer>
+  </PisellGridPro>
+);
 ```
 
 ### 4. 工作台页面
 
-```
-<PisellGridPro>
-  <PisellGridPro.Header
-    title="工作台"
-    subTitle="欢迎回来"
-  />
-  <PisellGridPro.DataCard dataItems={dashboardData} />
-  <PisellGridPro.ToolBar
-    tabs={<Tabs items={tabItems} />}
-  />
-  <PisellGridPro.View>
-    <DashboardContent />
-  </PisellGridPro.View>
-</PisellGridPro>
+```tsx
+import React from 'react';
+import { PisellGridPro, PisellGridView, PisellToolBar } from '@pisell/materials';
+import { Tabs } from 'antd';
+
+const tabItems = [
+  { key: '1', label: '概览' },
+  { key: '2', label: '任务' },
+];
+const dashboardData = [
+  { key: '1', title: '今日任务', value: '8', compareValue: '2 待办', trend: 'up' as const },
+];
+
+export default () => (
+  <PisellGridPro>
+    <PisellGridPro.Header title="工作台" subTitle="欢迎回来" />
+    <PisellGridPro.DataCard dataItems={dashboardData} />
+    <PisellToolBar tabs={<Tabs items={tabItems} />} />
+    <PisellGridView>
+      <div>工作台内容</div>
+    </PisellGridView>
+  </PisellGridPro>
+);
 ```
 
 ## 样式定制
 
 ### 自定义主容器样式
 
-```
-<PisellGridPro
-  style={{
-    background: '#f5f5f5',
-    padding: '0 32px',
-  }}
->
-  {/* 子组件 */}
-</PisellGridPro>
+```tsx
+import React from 'react';
+import { PisellGridPro, PisellGridView, PisellToolBar } from '@pisell/materials';
+
+export default () => (
+  <PisellGridPro
+    style={{
+      background: '#f5f5f5',
+      padding: '0 32px',
+    }}
+  >
+    <PisellGridPro.Header title="页面标题" />
+    <PisellGridView>
+      <div>内容</div>
+    </PisellGridView>
+  </PisellGridPro>
+);
 ```
 
 ### 自定义子组件样式
 
-```
-<PisellGridPro>
-  <PisellGridPro.Header
-    className="custom-header"
-    style={{ borderBottom: '2px solid #1890ff' }}
-    title="自定义样式"
-  />
+```tsx
+import React from 'react';
+import { PisellGridPro, PisellGridView, PisellToolBar } from '@pisell/materials';
 
-  <PisellGridPro.View
-    style={{ background: '#fff', padding: '24px' }}
-  >
-    <div>内容</div>
-  </PisellGridPro.View>
-</PisellGridPro>
+export default () => (
+  <PisellGridPro>
+    <PisellGridPro.Header
+      className="custom-header"
+      style={{ borderBottom: '2px solid #1890ff' }}
+      title="自定义样式"
+    />
+    <PisellGridView style={{ background: '#fff', padding: '24px' }}>
+      <div>内容</div>
+    </PisellGridView>
+  </PisellGridPro>
+);
 ```
 
 ### 自定义数据卡片样式
 
-```
-<PisellGridPro.DataCard
-  dataItems={[
-    {
-      key: '1',
-      title: '自定义样式',
-      value: '1,234',
-      style: {
-        background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
-        color: '#fff',
-      },
-    },
-  ]}
-/>
+```tsx
+import React from 'react';
+import { PisellGridPro, PisellGridView, PisellToolBar } from '@pisell/materials';
+
+export default () => (
+  <PisellGridPro>
+    <PisellGridPro.Header title="数据概览" />
+    <PisellGridPro.DataCard
+      dataItems={[
+        {
+          key: '1',
+          title: '自定义样式',
+          value: '1,234',
+          style: {
+            background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
+            color: '#fff',
+          },
+        },
+      ]}
+    />
+    <PisellGridView>
+      <div>内容</div>
+    </PisellGridView>
+  </PisellGridPro>
+);
 ```
 
 ## 扩展开发
@@ -480,10 +541,10 @@ export default () => {
 
 ## 注意事项
 
-1. **布局顺序**: 建议按照 Header → ToolBar → DataCard → View → Footer 的顺序使用子组件
-2. **高度控制**: PisellGridPro 默认占满视口高度（100vh），View 组件会自动占据剩余空间
-3. **滚动区域**: 只有 View 组件内部可滚动，其他组件固定不滚动
-4. **性能优化**: View 组件使用了 PisellScrollView，会自动处理滚动性能问题
+1. **布局顺序**: 建议按照 Header → PisellToolBar → DataCard → PisellGridView → Footer 的顺序使用子组件
+2. **高度控制**: PisellGridPro 默认占满视口高度（100vh），PisellGridView 会自动占据剩余空间
+3. **滚动区域**: 只有 PisellGridView 内部可滚动，其他组件固定不滚动
+4. **性能优化**: PisellGridView 使用 PisellScrollView，会自动处理滚动性能问题
 5. **响应式**: 组件支持响应式布局，会自动适配不同屏幕尺寸
 6. **可选组件**: 所有子组件都是可选的，可以按需组合使用
 
@@ -493,70 +554,88 @@ export default () => {
 
 在团队中统一使用 PisellGridPro 作为页面布局基础，保证视觉一致性。
 
-```
+```tsx
+import React from 'react';
+import { PisellGridPro, PisellGridView, PisellToolBar } from '@pisell/materials';
+
 // Good: 统一的布局结构
-<PisellGridPro>
-  <PisellGridPro.Header title="页面标题" />
-  <PisellGridPro.View>内容</PisellGridPro.View>
-</PisellGridPro>
-
-// Bad: 自定义不一致的布局
-<div className="custom-layout">
-  <div className="header">页面标题</div>
-  <div className="content">内容</div>
-</div>
+export default () => (
+  <PisellGridPro>
+    <PisellGridPro.Header title="页面标题" />
+    <PisellGridView>内容</PisellGridView>
+  </PisellGridPro>
+);
 ```
 
 ### 2. 合理使用数据卡片
 
-数据卡片适合展示关键指标，不宜放置过多卡片。
+数据卡片适合展示关键指标，建议 3–6 个核心指标，不宜过多。
 
-```
-// Good: 3-6 个核心指标
-<PisellGridPro.DataCard
-  dataItems={[
-    { key: '1', title: '总收入', value: '$45,231' },
-    { key: '2', title: '订单数', value: '2,340' },
-    { key: '3', title: '转化率', value: '68.2%' },
-  ]}
-/>
-
-// Bad: 过多卡片影响视觉
-<PisellGridPro.DataCard dataItems={tenCards} />
+```tsx
+import React from 'react';
+import { PisellGridPro, PisellGridView, PisellToolBar } from '@pisell/materials';
+
+export default () => (
+  <PisellGridPro>
+    <PisellGridPro.Header title="数据概览" />
+    <PisellGridPro.DataCard
+      dataItems={[
+        { key: '1', title: '总收入', value: '$45,231' },
+        { key: '2', title: '订单数', value: '2,340' },
+        { key: '3', title: '转化率', value: '68.2%' },
+      ]}
+    />
+    <PisellGridView>
+      <div>内容</div>
+    </PisellGridView>
+  </PisellGridPro>
+);
 ```
 
 ### 3. 灵活使用 ToolBar
 
-ToolBar 提供了 4 个位置，合理分配功能区域。
+ToolBar 提供 tabs、topLeft、topRight、bottomLeft、bottomRight，可合理分配搜索、筛选、操作按钮等。
 
-```
-<PisellGridPro.ToolBar
-  topLeft={<SearchBar />}        // 左侧：搜索、筛选
-  topRight={<Button>创建</Button>} // 右侧：操作按钮
-  bottomLeft={<BatchActions />}   // 底部左侧：批量操作
-  bottomRight={<ViewSwitch />}    // 底部右侧：视图切换
-/>
+```tsx
+import React from 'react';
+import { PisellGridPro, PisellGridView, PisellToolBar } from '@pisell/materials';
+import { Button } from 'antd';
+
+export default () => (
+  <PisellToolBar
+    topLeft={<div>搜索 / 筛选</div>}
+    topRight={<Button type="primary">创建</Button>}
+    bottomLeft={<div>批量操作</div>}
+    bottomRight={<div>视图切换</div>}
+  />
+);
 ```
 
 ### 4. 页脚用于固定操作
 
 Footer 适合放置分页、批量操作确认等固定在底部的元素。
 
-```
-<PisellGridPro.Footer>
-  <div style={{ display: 'flex', justifyContent: 'space-between' }}>
-    <div>已选择 10 项</div>
-    <Pagination total={100} />
-  </div>
-</PisellGridPro.Footer>
+```tsx
+import React from 'react';
+import { PisellGridPro, PisellGridView, PisellToolBar } from '@pisell/materials';
+
+export default () => (
+  <PisellGridPro.Footer>
+    <div style={{ display: 'flex', justifyContent: 'space-between' }}>
+      <div>已选择 10 项</div>
+      <div>分页组件</div>
+    </div>
+  </PisellGridPro.Footer>
+);
 ```
 
-### 5. View 内容区域的组织
+### 5. PisellGridView 内容区域的组织
 
-View 组件内应该是主要的业务内容，保持内容区域的简洁。
+PisellGridView 内放主要业务内容，保持简洁；可与 Table、列表等配合使用。
 
 ```tsx
-import { PisellGridPro } from '@pisell/materials';
+import React from 'react';
+import { PisellGridView } from '@pisell/materials';
 import { Table } from 'antd';
 
 const data = [
@@ -569,10 +648,9 @@ const columns = [
 ];
 
 export default () => (
-  <PisellGridPro.View>
+  <PisellGridView>
     <Table dataSource={data} columns={columns} />
-    {/* 或其他业务组件 */}
-  </PisellGridPro.View>
+  </PisellGridView>
 );
 ```
 
@@ -590,24 +668,35 @@ View 组件会自动占据剩余空间，无需额外配置。
 
 直接不渲染该子组件即可。
 
-```
-<PisellGridPro>
-  <PisellGridPro.Header title="标题" />
-  {/* 不需要 ToolBar 就不渲染 */}
-  <PisellGridPro.View>内容</PisellGridPro.View>
-</PisellGridPro>
+```tsx
+import React from 'react';
+import { PisellGridPro, PisellGridView, PisellToolBar } from '@pisell/materials';
+
+export default () => (
+  <PisellGridPro>
+    <PisellGridPro.Header title="标题" />
+    {/* 不需要 ToolBar 就不渲染 */}
+    <PisellGridView>内容</PisellGridView>
+  </PisellGridPro>
+);
 ```
 
 ### 4. 如何自定义内边距？
 
-通过 style 属性自定义。
+通过 `style` 属性设置。
 
-```
-<PisellGridPro style={{ padding: '0 32px' }}>
-  {/* 子组件 */}
-</PisellGridPro>
+```tsx
+import React from 'react';
+import { PisellGridPro, PisellGridView, PisellToolBar } from '@pisell/materials';
+
+export default () => (
+  <PisellGridPro style={{ padding: '0 32px' }}>
+    <PisellGridPro.Header title="标题" />
+    <PisellGridView>内容</PisellGridView>
+  </PisellGridPro>
+);
 ```
 
 ### 5. DataCard 为空时会怎样？
 
-当 dataItems 为空数组时，DataCard 不会渲染任何内容。
+当 `dataItems` 为空数组时，DataCard 不渲染任何内容。

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

@@ -53,7 +53,8 @@ category: atom
 
 ## 3. 组件描述
 
-`PisellHierarchicalSummaryList` 是一个结构型“层级汇总列表”组件，专注于**层级展示 + 展开交互 + 聚合展示**能力，不绑定金额/订单/支付等业务语义。适用于费用构成、统计汇总、规则来源解释等场景。
+`PisellHierarchicalSummaryList` 是一个结构型“层级汇总列表”组件，专注于**层级展示 + 展开交互 + 聚合展示**
+能力，不绑定金额/订单/支付等业务语义。适用于费用构成、统计汇总、规则来源解释等场景。
 
 ## 4. 组件 API 设计
 
@@ -175,11 +176,13 @@ PisellHierarchicalSummaryList
 ### 6.1 关键点
 
 - **key 策略**：优先使用 `item.key`；未提供则由 `getKey` 或“层级路径”生成，确保 expandedKeys 稳定可复现。
-- **展开态管理**：封装一个 `useExpandedKeys`，同时支持受控与非受控；`defaultExpandedLevel` 在初始化阶段计算并合并到默认展开 keys。
+- **展开态管理**：封装一个 `useExpandedKeys`，同时支持受控与非受控；`defaultExpandedLevel` 在初始化阶段计算并合并到默认展开
+  keys。
 - **手风琴模式**：在同一父级下切换展开时，收起兄弟节点（基于 pathKeys 判断同级）。
 - **聚合**：
   - 若 `item.value` 已提供：直接渲染；
-  - 若未提供且 `aggregate.mode==='sum'`：对 children 使用 `getNumberValue` 提取 number 后求和，`format` 负责展示（例如 `$${sum}`）。
+  - 若未提供且 `aggregate.mode==='sum'`：对 children 使用 `getNumberValue` 提取 number 后求和，`format` 负责展示（例如
+    `$${sum}`）。
 - **排版**：Left 允许换行；Right（value/extra）不换行，整体 `justify-content: space-between`，value 右对齐。
 
 ### 6.2 视觉基线（来自 Figma 节点）