@pisell/materials 1.8.41 → 1.8.42

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

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

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

@@ -53,8 +53,7 @@ category: atom
 
 ## 3. 组件描述
 
-`PisellHierarchicalSummaryList` 是一个结构型“层级汇总列表”组件，专注于**层级展示 + 展开交互 + 聚合展示**
-能力，不绑定金额/订单/支付等业务语义。适用于费用构成、统计汇总、规则来源解释等场景。
+`PisellHierarchicalSummaryList` 是一个结构型“层级汇总列表”组件，专注于**层级展示 + 展开交互 + 聚合展示**能力，不绑定金额/订单/支付等业务语义。适用于费用构成、统计汇总、规则来源解释等场景。
 
 ## 4. 组件 API 设计
 
@@ -176,13 +175,11 @@ 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 节点）