@pisell/materials 1.0.1036 → 1.0.1037

package/lib/components/pisellRecordBoard/docs/ShellFrame.md

@@ -0,0 +1,94 @@
+---
+nav:
+  title: 组件
+  order: 1
+group:
+  title: Data Display
+  order: 1
+title: Shell Frame（记录看板外壳）
+order: 2
+category: pro
+---
+
+# Shell Frame 记录看板外壳
+
+Shell Frame 是 **PisellRecordBoard** 的外壳子组件，基于 `PisellShellFrame` 实现，提供「工具栏 + 多选操作栏 + 内容区 + 分页」的完整布局，与 **GridLayout** / **CardLayout** 搭配使用。
+
+## 组件介绍
+
+- **使用方式**：在 `PisellRecordBoard` 下使用 `PisellRecordBoard.ShellFrame` 包裹内容区（Layout），即可获得工具栏、多选操作栏和底部分页。
+- **数据与配置**：Shell Frame 内各子组件通过 **useRecordBoardContext** 消费容器的 `data`、`searchParams`、`onSearch`、`columnVisibility` 等；工具栏、分页、批量操作栏的展示与行为由 **grid** / **toolBar** / **pagination** / **batchActionBar** 等打散配置控制。
+
+## 结构示意
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ ToolBar（左侧：QuickFilter + 搜索；右侧：列设置、排序、筛选、重置）   │
+├─────────────────────────────────────────────────────────────────┤
+│ BatchActionBar（有选中项时展示：全选/反选/清空/删除 + 自定义 actions）│
+├─────────────────────────────────────────────────────────────────┤
+│ children（通常为 GridLayout 或 CardLayout）                        │
+├─────────────────────────────────────────────────────────────────┤
+│ Pagination（底部分页）                                            │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## 使用方式
+
+```tsx
+import React from 'react';
+import { PisellRecordBoard } from '@pisell/materials';
+
+export default () => (
+  <PisellRecordBoard
+    rowKey="id"
+    data={list}
+    loading={false}
+    total={100}
+    pagination={{ pageNumber: 1, pageSize: 10 }}
+    onPageChange={(page, size) => {}}
+    searchParams={{}}
+    onSearch={(params) => {}}
+    grid={{ columns }}
+  >
+    <PisellRecordBoard.ShellFrame>
+      <PisellRecordBoard.GridLayout />
+    </PisellRecordBoard.ShellFrame>
+  </PisellRecordBoard>
+);
+```
+
+## 子模块说明
+
+| 模块 | 说明 |
+|------|------|
+| **ToolBar** | 工具栏。左侧：QuickFilter（可选）+ PisellFind 搜索；右侧：列设置、Sort、PisellFilter、ToolBarReset、slots.topRight。筛选项与排序项可由 `grid.columns` 派生，或通过 `toolBar.filter` / `toolBar.sort` 覆盖。 |
+| **BatchActionBar** | 多选操作栏。有选中行时展示；全选/反选/清空基于当前页 data；删除与自定义操作通过 `batchActionBar.actions` 等配置。 |
+| **Pagination** | 底部分页。从 context 取 `pagination`、`total`、`onPageChange`；可透传 `childComponentProps.pagination`。样式类名：`record-board-shell-frame-pagination`。 |
+| **Search** | 独立搜索槽（非 ToolBar 内嵌）。绑定 `searchParams.keyword` 与 `onSearch`，可通过 `childComponentProps.search` 透传 PisellFind 的 props。 |
+| **ToolBarReset** | 重置按钮。清空筛选与排序（filter.values、sort），并调用 `onSearch` / `onReset`。 |
+| **ToolBarQuickFilter** | 左侧内联快速筛选。将 quickFilter 直接展示在 ToolBar 左侧；与 `searchParams.filter` 联动。启用时建议 Filter 弹层传 `hiddenQuickFilter: true`。 |
+| **ColumnSetting** | 列显示隐藏入口。有 `grid.columns` 且 `toolBar.columnSetting !== false` 时在 ToolBar 右侧展示；点击弹出列显隐勾选。 |
+
+## 配置入口（childComponentProps）
+
+Shell Frame 内各块通过 RecordBoard 打散传入的 **grid**、**toolBar**、**pagination**、**batchActionBar** 等生效，对应关系如下。
+
+| 配置键 | 作用范围 | 说明 |
+|--------|----------|------|
+| **grid** | 列、滚动、多选、列默认隐藏 | `columns`、`defaultHiddenColumnKeys`、列上 `hidden: true` 参与列显隐；ColumnSetting 据此展示列列表。 |
+| **toolBar** | ToolBar | `search`：true/对象/false，控制搜索展示与透传。`filter`：同上，控制筛选弹层。`sort`：同上，控制排序。`quickFilter`：true 或 `{ filterList, formFiltersPrefix, size }`。`columnSetting`：是否显示列设置入口，默认 true。`topLeft` / `topRight` / `bottomLeft` / `bottomRight` / `tabs`：插槽。 |
+| **pagination** | Pagination | 透传给底部分页组件（如 showSizeChanger、sizeOptions 等）。 |
+| **batchActionBar** | BatchActionBar | 与 PisellBatchActionBar 的 props 对齐：`actions`、`defaultActions`、`overflowThreshold`、`onDelete` 等。 |
+
+## 搜索与筛选约定
+
+- **搜索**：默认绑定 `searchParams.keyword`，变更时调用 `onSearch({ ...searchParams, keyword: value })`。
+- **筛选**：绑定 `searchParams.filter`，结构为 `{ quickFilter, otherFilter, values }`；ToolBar 内右侧 Filter 弹层默认 `hiddenQuickFilter: true`，快筛全部在左侧 QuickFilter 展示。
+- **排序**：绑定 `searchParams.sort`，单值字符串；Sort 与 Filter 变更均通过 `onSearch` 写回 `searchParams`。
+
+## 相关文档
+
+- [PisellRecordBoard](./PisellRecordBoard.md)
+- [架构说明](./architecture.md)
+- [列与筛选/排序绑定](./columns-filter-binding.md)

package/lib/components/pisellRecordBoard/layouts/GridLayout/Grid.js

@@ -1,8 +1,8 @@
 const require_rolldown_runtime = require('../../../../_virtual/rolldown_runtime.js');
 const require_objectSpread2 = require('../../../../_virtual/_@oxc-project_runtime@0.108.0/helpers/objectSpread2.js');
 const require_objectWithoutProperties = require('../../../../_virtual/_@oxc-project_runtime@0.108.0/helpers/objectWithoutProperties.js');
-const require_useRecordBoardContext = require('../../hooks/useRecordBoardContext.js');
 const require_recordBoardColumns = require('../../utils/recordBoardColumns.js');
+const require_useRecordBoardContext = require('../../hooks/useRecordBoardContext.js');
 let antd = require("antd");
 let react = require("react");
 react = require_rolldown_runtime.__toESM(react);

package/lib/components/pisellRecordBoard/shellFrame/ColumnSetting/index.js

@@ -1,6 +1,6 @@
 const require_rolldown_runtime = require('../../../../_virtual/rolldown_runtime.js');
-const require_useRecordBoardContext = require('../../hooks/useRecordBoardContext.js');
 const require_recordBoardColumns = require('../../utils/recordBoardColumns.js');
+const require_useRecordBoardContext = require('../../hooks/useRecordBoardContext.js');
 const require_ColumnSettingPopover = require('./ColumnSettingPopover.js');
 let antd = require("antd");
 let react = require("react");

package/lib/components/pisellRecordBoard/shellFrame/ToolBar/index.js

@@ -3,8 +3,8 @@ const require_objectSpread2 = require('../../../../_virtual/_@oxc-project_runtim
 const require_index = require('../../../../locales/index.js');
 const require_index$1 = require('../../../sort/index.js');
 const require_index$2 = require('../../../pisellFind/index.js');
-const require_useRecordBoardContext = require('../../hooks/useRecordBoardContext.js');
 const require_recordBoardColumns = require('../../utils/recordBoardColumns.js');
+const require_useRecordBoardContext = require('../../hooks/useRecordBoardContext.js');
 const require_index$3 = require('../../../pisellGridPro/ToolBar/index.js');
 const require_index$4 = require('../../../pisellFilter/index.js');
 const require_index$5 = require('../ToolBarReset/index.js');

package/lib/components/pisellRecordBoard/types.d.ts

@@ -92,6 +92,8 @@ interface RecordBoardColumnType<RecordType = any> {
       label: string;
     }>;
   };
+  /** 默认隐藏该列，与 grid.defaultHiddenColumnKeys 合并参与初始化列显隐 */
+  hidden?: boolean;
 }
 /**
  * 分页状态（与容器内部一致）

package/lib/index.js

@@ -171,8 +171,8 @@ const require_index$138 = require('./components/PisellTabbar/template/Template1/
 const require_index$139 = require('./components/PisellTabbar/index.js');
 const require_PisellTabbar = require('./components/PisellTabbar2/PisellTabbar.js');
 const require_index$140 = require('./components/pisellDataSourceContainer/index.js');
-const require_useRecordBoardContext = require('./components/pisellRecordBoard/hooks/useRecordBoardContext.js');
 const require_PisellDateTimeDisplay = require('./components/pisellDateTimeDisplay/PisellDateTimeDisplay.js');
+const require_useRecordBoardContext = require('./components/pisellRecordBoard/hooks/useRecordBoardContext.js');
 const require_PisellShellFrame = require('./components/pisellShellFrame/PisellShellFrame.js');
 const require_index$141 = require('./components/pisellGridPro/ToolBar/index.js');
 const require_index$142 = require('./components/pisellFilter/index.js');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pisell/materials",
-  "version": "1.0.1036",
+  "version": "1.0.1037",
   "main": "./lib/index.js",
   "module": "./es/index.js",
   "types": "./lib/index.d.ts",