@pisell/materials 1.0.1034 → 1.0.1035

package/es/components/pisellRecordBoard/PisellRecordBoard.js

@@ -0,0 +1,148 @@
+import { _objectSpread2 } from "../../_virtual/_@oxc-project_runtime@0.108.0/helpers/objectSpread2.js";
+import { _objectWithoutProperties } from "../../_virtual/_@oxc-project_runtime@0.108.0/helpers/objectWithoutProperties.js";
+import { RecordBoardProvider } from "./context/RecordBoardProvider.js";
+import React, { useCallback, useMemo, useState } from "react";
+
+//#region src/components/pisellRecordBoard/PisellRecordBoard.tsx
+const _excluded = [
+	"children",
+	"layoutType",
+	"rowKey",
+	"data",
+	"loading",
+	"total",
+	"pagination",
+	"onPageChange",
+	"searchParams",
+	"onSearch",
+	"onReset"
+];
+const defaultPagination = {
+	pageNumber: 1,
+	pageSize: 10
+};
+/**
+* 从打散 props 合并出 childComponentProps（供 context 使用）。
+*/
+function mergeChildComponentProps(props) {
+	if (!(props.grid != null || props.toolBar != null || props.search != null || props.paginationConfig != null || props.batchActionBar != null || props.cardList != null)) return void 0;
+	return _objectSpread2(_objectSpread2(_objectSpread2(_objectSpread2(_objectSpread2(_objectSpread2({}, props.grid != null && { grid: props.grid }), props.toolBar != null && { toolBar: props.toolBar }), props.search != null && { search: props.search }), props.paginationConfig != null && { pagination: props.paginationConfig }), props.batchActionBar != null && { batchActionBar: props.batchActionBar }), props.cardList != null && { cardList: props.cardList });
+}
+/**
+* 默认的 context 值（用于无数据源时的占位 / 设计态）
+*/
+function getDefaultRecordBoardContext(layoutType, selection, rowKey) {
+	return {
+		data: [],
+		loading: false,
+		total: 0,
+		pagination: defaultPagination,
+		onPageChange: () => {},
+		searchParams: {},
+		onSearch: () => {},
+		onReset: () => {},
+		layoutType,
+		selectedKeys: selection.selectedKeys,
+		selectedRows: selection.selectedRows,
+		onSelectionChange: selection.onSelectionChange,
+		rowKey,
+		childComponentProps: void 0
+	};
+}
+/**
+* RecordBoard 容器：提供统一的 data / pagination / search 上下文。
+* 仅接受打散 props：列表/分页/搜索/多选/列显隐、以及 grid/toolBar/search/paginationConfig/batchActionBar/cardList。
+*/
+const PisellRecordBoard = (props) => {
+	const { children, layoutType = "grid", rowKey: rowKeyProp, data: dataProp, loading: loadingProp, total: totalProp, pagination: paginationProp, onPageChange: onPageChangeProp, searchParams: searchParamsProp, onSearch: onSearchProp, onReset: onResetProp } = props;
+	_objectWithoutProperties(props, _excluded);
+	const mergedChildComponentProps = useMemo(() => mergeChildComponentProps(props), [
+		props.grid,
+		props.toolBar,
+		props.search,
+		props.paginationConfig,
+		props.batchActionBar,
+		props.cardList
+	]);
+	const [internalSelectedKeys, setInternalSelectedKeys] = useState([]);
+	const [internalSelectedRows, setInternalSelectedRows] = useState([]);
+	const [internalColumnVisibility, setInternalColumnVisibility] = useState(() => {
+		var _props$grid;
+		const keys = (_props$grid = props.grid) === null || _props$grid === void 0 ? void 0 : _props$grid.defaultHiddenColumnKeys;
+		if (!Array.isArray(keys) || keys.length === 0) return {};
+		const vis = {};
+		keys.forEach((k) => {
+			vis[k] = false;
+		});
+		return vis;
+	});
+	const onSelectionChangeInternal = useCallback((keys, rows) => {
+		setInternalSelectedKeys(keys);
+		setInternalSelectedRows(rows);
+	}, []);
+	const onColumnVisibilityChangeInternal = useCallback((visibility) => {
+		setInternalColumnVisibility((prev) => _objectSpread2(_objectSpread2({}, prev), visibility));
+	}, []);
+	const contextValue = useMemo(() => {
+		var _gridSelection$select;
+		const defaultCtx = getDefaultRecordBoardContext(layoutType, {
+			selectedKeys: internalSelectedKeys,
+			selectedRows: internalSelectedRows,
+			onSelectionChange: onSelectionChangeInternal
+		}, rowKeyProp);
+		const data = dataProp !== void 0 ? dataProp : defaultCtx.data;
+		const loading = loadingProp !== void 0 ? loadingProp : defaultCtx.loading;
+		const total = totalProp !== void 0 ? totalProp : defaultCtx.total;
+		const pagination = paginationProp !== void 0 ? paginationProp : defaultCtx.pagination;
+		const onPageChange = onPageChangeProp !== null && onPageChangeProp !== void 0 ? onPageChangeProp : defaultCtx.onPageChange;
+		const searchParams = searchParamsProp !== void 0 ? searchParamsProp : defaultCtx.searchParams;
+		const onSearch = onSearchProp !== null && onSearchProp !== void 0 ? onSearchProp : defaultCtx.onSearch;
+		const onReset = onResetProp !== null && onResetProp !== void 0 ? onResetProp : defaultCtx.onReset;
+		const rowKey = rowKeyProp !== null && rowKeyProp !== void 0 ? rowKeyProp : defaultCtx.rowKey;
+		const gridSelection = props.grid;
+		const hasControlledSelection = (gridSelection === null || gridSelection === void 0 ? void 0 : gridSelection.selectedKeys) != null && Array.isArray(gridSelection.selectedKeys) && typeof gridSelection.onSelectionChange === "function";
+		const selectedKeys = hasControlledSelection ? gridSelection.selectedKeys : internalSelectedKeys;
+		const selectedRows = hasControlledSelection ? (_gridSelection$select = gridSelection.selectedRows) !== null && _gridSelection$select !== void 0 ? _gridSelection$select : [] : internalSelectedRows;
+		const onSelectionChange = hasControlledSelection ? gridSelection.onSelectionChange : onSelectionChangeInternal;
+		return _objectSpread2(_objectSpread2({}, defaultCtx), {}, {
+			layoutType,
+			rowKey,
+			data,
+			loading,
+			total,
+			pagination,
+			onPageChange,
+			searchParams,
+			onSearch,
+			onReset,
+			selectedKeys,
+			selectedRows,
+			onSelectionChange,
+			columnVisibility: internalColumnVisibility,
+			onColumnVisibilityChange: onColumnVisibilityChangeInternal,
+			childComponentProps: mergedChildComponentProps !== null && mergedChildComponentProps !== void 0 ? mergedChildComponentProps : defaultCtx.childComponentProps
+		});
+	}, [
+		layoutType,
+		rowKeyProp,
+		dataProp,
+		loadingProp,
+		totalProp,
+		paginationProp,
+		onPageChangeProp,
+		searchParamsProp,
+		onSearchProp,
+		onResetProp,
+		mergedChildComponentProps,
+		internalSelectedKeys,
+		internalSelectedRows,
+		onSelectionChangeInternal,
+		internalColumnVisibility,
+		onColumnVisibilityChangeInternal
+	]);
+	return /* @__PURE__ */ React.createElement(RecordBoardProvider, { value: contextValue }, children);
+};
+var PisellRecordBoard_default = PisellRecordBoard;
+
+//#endregion
+export { PisellRecordBoard_default as default };

package/es/components/pisellRecordBoard/README.md

@@ -0,0 +1,183 @@
+# PisellRecordBoard 记录看板
+
+记录看板容器组件，提供统一的列表数据、分页、搜索/筛选/排序、多选等上下文，支持 Grid（表格）与 Card 两种布局。ToolBar
+左侧为快速筛选（QuickFilter）+ 搜索（PisellFind），右侧为排序、筛选弹层、重置。
+
+## 快速开始
+
+```tsx
+import PisellRecordBoard from '@pisell/materials';
+
+// 受控：打散传入 data、pagination、searchParams、onSearch 等；多选通过 grid 传入
+const value = {
+    data: list,
+    loading: false,
+    total: 100,
+    pagination: { pageNumber: 1, pageSize: 10 },
+    onPageChange: (num, size) => {},
+    searchParams: {},
+    onSearch: (params) => {},
+    layoutType: 'grid',
+    rowKey: 'id',
+};
+
+<PisellRecordBoard rowKey="id" {...value} grid={{ columns, selectedKeys, selectedRows, onSelectionChange }} />
+    <PisellRecordBoard.ShellFrame>
+        <PisellRecordBoard.GridLayout/>
+    </PisellRecordBoard.ShellFrame>
+</PisellRecordBoard>
+```
+
+通过 `grid.columns` 传入列配置，ToolBar 会根据 columns 自动派生筛选与排序；列上配置 `type` 时，表格会用对应
+Pisell 组件只读渲染，筛选用编辑态。`grid` 支持 antd Table 其他 props 透传，如 `onRow`（行点击等）、`onHeaderRow`、`expandable`、`rowClassName`、`summary` 等。
+
+## 核心特性
+
+- **统一上下文**：data、pagination、searchParams、onSearch、多选等由 Context 提供，子组件通过 `useRecordBoardContext()` 消费。
+- **列驱动筛选/排序**：列配置（`grid.columns`）驱动 ToolBar 内筛选项与排序项，无需单独维护 filter 列表。
+- **有 type / 无 type**：有 `type` 时表格/筛选/排序可自动派生；无 `type` 时需自行配置 `render`、`filter`、`sort`；有 type
+  时也可传 `render`/`filter`/`sort` 覆盖。
+- **快速筛选**：支持左侧内联 QuickFilter（如下单时间 RangePicker），右侧筛选弹层仅高级筛选。
+- **多选**：支持表格/卡片多选，BatchActionBar 展示批量操作。
+
+## 子组件
+
+| 子组件                                       | 说明                                                                 |
+|-------------------------------------------|--------------------------------------------------------------------|
+| `PisellRecordBoard.ShellFrame`            | 外壳：ToolBar + BatchActionBar + children（Layout）+ Pagination；分页使用定制样式（见 shellFrame/Pagination/index.less） |
+| `PisellRecordBoard.GridLayout`            | 表格布局（Grid + 分页）                                                    |
+| `PisellRecordBoard.CardLayout`            | 卡片列表布局                                                             |
+| `PisellRecordBoard.ToolBar`               | 工具栏（搜索、QuickFilter、Sort、Filter、列设置、Reset、slots）                      |
+| `PisellRecordBoard.Search`                | 独立搜索槽（PisellFind）                                                  |
+| `PisellRecordBoard.Pagination`            | 独立分页槽                                                            |
+| `PisellRecordBoard.Grid`                  | 独立表格视图（支持 columnVisibility 列显示隐藏）                                   |
+| `PisellRecordBoard.CardList`              | 独立卡片列表视图                                                         |
+| `PisellRecordBoard.BatchActionBar`        | 多选操作栏                                                            |
+| `PisellRecordBoard.useRecordBoardContext` | 消费 RecordBoard 上下文的 Hook                                         |
+
+## 列配置逻辑（有 type / 无 type）
+
+| 能力       | **有 type**（如 `singleLineText`）             | **无 type**                                                                                 |
+|----------|--------------------------------------------|--------------------------------------------------------------------------------------------|
+| **表格展示** | 自动用对应 Pisell 组件只读渲染；可传 `render` 覆盖         | 无 `render` 则纯文本；可自定义 `render`                                                              |
+| **筛选**   | 自动用对应组件编辑态；可传 `filter`（type 或 component）覆盖 | 需配置 `filterable` + `filter`（`filter.type` 或 `filter.component`，component 需 value/onChange） |
+| **排序**   | 自动从组件 SortOptions 派生；可传 `sort` 覆盖          | 需配置 `sortable` + `sort`（`sort.type` 或 `sort.getSortItems`）                                 |
+
+### 支持的列 type（RecordBoardFieldType）
+
+`singleLineText` | `longText` | `email` | `phone` | `url` | `number` | `currency` | `percent` | `rating` |
+`singleSelect` | `multipleSelect` | `dateTime`
+
+### 有 type 示例（options 或 getOptions）
+
+列 type 为 singleSelect/multipleSelect 时，`fieldProps` 可传 `options` 或 `getOptions`（同步/异步返回选项列表）；筛选同理，`filter.options` 或 `filter.getOptions`。
+
+```tsx
+const columns = [
+    {title: '订单号', dataIndex: 'orderNo', key: 'orderNo', width: 160, type: 'singleLineText'},
+    {
+        title: '状态',
+        dataIndex: 'status',
+        key: 'status',
+        type: 'singleSelect',
+        fieldProps: {options: [{label: '全部', value: 'all'}, {label: '启用', value: 'enabled'}]},
+    },
+    {
+        title: '下单时间',
+        dataIndex: 'createTime',
+        key: 'createTime',
+        type: 'dateTime',
+        fieldProps: {customFormat: 'YYYY-MM-DD HH:mm'},
+        filterable: true,
+        filter: {quickFilter: true},  // 放在左侧快筛
+    },
+];
+```
+
+### 无 type + 自定义 filter 示例
+
+```tsx
+const MyFilterInput = ({value, onChange}) => (
+    <Input value={value} onChange={(e) => onChange?.(e.target.value)} placeholder="自定义"/>
+);
+
+const columns = [
+    {
+        title: '备注',
+        dataIndex: 'remark',
+        key: 'remark',
+        filterable: true,
+        filter: {component: MyFilterInput},
+    },
+    {
+        title: '状态',
+        dataIndex: 'status',
+        key: 'status',
+        sortable: true,
+        sort: {getSortItems: (key) => [{key: `${key}:asc`, label: 'A-Z'}, {key: `${key}:desc`, label: 'Z-A'}]},
+    },
+];
+```
+
+## Props
+
+仅支持**打散传参**（有明确关系的成组，其余独立）。
+
+**列表/分页/搜索**：`data`、`loading`、`total`、`pagination`、`onPageChange`、`searchParams`、`onSearch`、`onReset`、`rowKey`、`layoutType`。**多选**：通过 `grid.selectedKeys`、`grid.selectedRows`、`grid.onSelectionChange` 传入。**列显示隐藏**：由容器内部维护，不通过 props 传入，通过 context 提供给 ToolBar 列设置与 Grid。
+
+**子组件配置**：`grid`、`toolBar`、`search`、`paginationConfig`、`batchActionBar`、`cardList`。
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `rowKey` | `string \| (record) => Key` | 行主键 |
+| `layoutType` | `'grid' \| 'card'` | 布局类型 |
+| `data` / `loading` / `total` / `pagination` / `onPageChange` / `searchParams` / `onSearch` / `onReset` | 各自类型 | 打散的数据与回调 |
+| `grid` / `toolBar` / `search` / `paginationConfig` / `batchActionBar` / `cardList` | 各自类型 | 打散的子组件配置。**grid** 类型为 RecordBoardGridProps（基于 antd TableProps 省略 dataSource/loading/pagination/columns/scroll/size/rowSelection），多选在 grid 内；支持 Table 透传（onRow、onHeaderRow、expandable、rowClassName、summary 等） |
+
+## Context（RecordBoardContextValue）
+
+- `data`、`loading`、`total`、`pagination`、`onPageChange`
+- `searchParams`（含 keyword、filter、sort）、`onSearch`、`onReset`
+- `layoutType`、`selectedKeys`、`selectedRows`、`onSelectionChange`、`rowKey`
+- `columnVisibility`、`onColumnVisibilityChange`（由容器内部维护并注入 context，供 Grid/CardList 与 ToolBar 列设置使用；不通过 props 传入）
+- `childComponentProps`（由容器从打散 props 合并注入）
+
+子组件通过 `PisellRecordBoard.useRecordBoardContext()` 获取。
+
+## 文档
+
+- [使用文档](./docs/PisellRecordBoard.md)
+- [架构说明](./docs/architecture.md)
+- [列与筛选/排序绑定](./docs/columns-filter-binding.md)
+- [设计文档](./docs/PisellRecordBoard.$tab-design.md)
+- [开发文档](./docs/PisellRecordBoard.$tab-dev.md)
+- [测试文档](./docs/PisellRecordBoard.$tab-test.md)
+
+## 目录结构
+
+```
+pisellRecordBoard/
+├── index.tsx                 # 导出入口与子组件挂载
+├── PisellRecordBoard.tsx     # 主容器与 Provider
+├── types.ts                  # RecordBoardColumnType、RecordBoardContextValue 等
+├── context/                  # RecordBoardContext、RecordBoardProvider
+├── hooks/
+│   └── useRecordBoardContext.ts
+├── shellFrame/               # ToolBar、ColumnSetting、ToolBarQuickFilter、BatchActionBar、Pagination（含 index.less 分页样式）、Search
+├── layouts/
+│   ├── GridLayout/           # 表格布局
+│   └── CardLayout/           # 卡片布局
+├── utils/
+│   ├── recordBoardColumns.tsx  # processColumnsForGrid、deriveFilterFromColumns、deriveSortFromColumns
+│   └── withRecordBoard.tsx
+├── docs/
+│   ├── architecture.md
+│   ├── columns-filter-binding.md
+│   └── PisellRecordBoard.$tab-design.md
+├── PisellRecordBoard.stories.tsx
+└── README.md                 # 本文档
+```
+
+## License
+
+MIT

package/es/components/pisellRecordBoard/context/RecordBoardContext.js

@@ -0,0 +1,7 @@
+import { createContext } from "react";
+
+//#region src/components/pisellRecordBoard/context/RecordBoardContext.ts
+const RecordBoardContext = createContext(null);
+
+//#endregion
+export { RecordBoardContext };

package/es/components/pisellRecordBoard/context/RecordBoardProvider.js

@@ -0,0 +1,14 @@
+import { RecordBoardContext } from "./RecordBoardContext.js";
+import React from "react";
+
+//#region src/components/pisellRecordBoard/context/RecordBoardProvider.tsx
+/**
+* 仅负责注入 RecordBoard 上下文。
+* 实际的数据源、onSearch/onPageChange 由上层（如接 DataSourceContainer 或独立 fetch）提供。
+*/
+const RecordBoardProvider = ({ value, children }) => {
+	return /* @__PURE__ */ React.createElement(RecordBoardContext.Provider, { value }, children);
+};
+
+//#endregion
+export { RecordBoardProvider };

package/es/components/pisellRecordBoard/docs/PisellRecordBoard.$tab-design.md

@@ -0,0 +1,128 @@
+---
+title: 设计文档
+order: 2
+category: pro
+---
+
+# PisellRecordBoard 组件设计文档
+
+## 1 组件概述
+
+### 1.1 组件定位
+
+PisellRecordBoard 是记录看板容器组件，提供统一的 data / pagination / search 上下文，支持表格（Grid）与卡片（Card）两种内容区布局，并可搭配 Shell Frame 获得工具栏、批量操作栏、分页等外壳能力。
+
+### 1.2 使用场景
+
+- 列表页、数据看板（表格或卡片）
+- 与 DataSourceContainer / useRequest 等对接的受控数据展示
+- 需要搜索、筛选、分页、多选批量操作的记录视图
+
+## 2 概念
+
+- **RecordBoard**：记录看板容器，提供统一的 data / pagination / search 上下文。
+- **Shell Frame**：与 Layouts 同级，对 Layout 的扩展。提供「外壳」能力：ToolBar（含搜索、筛选）、BatchActionBar、Pagination。包裹在 Layout 外层使用。
+- **Layout**：一种「内容区视图的集合」。仅负责数据展示（表格/卡片），不包含 ToolBar / BatchActionBar / 分页。
+- **Grid 布局**：仅内容区 = 表格。分页与工具栏、多选栏由 **Shell Frame** 提供。
+- **Card 布局**：仅内容区 = 卡片列表。分页与工具栏、多选栏由 **Shell Frame** 提供。
+- 后续可扩展 list、kanban 等 Layout；Shell Frame 可扩展更多外壳槽位。
+
+## 3 数据流
+
+- 容器通过 **RecordBoardProvider** 提供与 layout 类型无关的上下文：`data`、`loading`、`total`、`pagination`、`searchParams`、`onSearch`、`onPageChange`、`layoutType`、多选等；列显示隐藏（`columnVisibility`、`onColumnVisibilityChange`）由容器内部维护并注入 context，不通过 props 传入。
+- **Shell Frame** 内使用 **PisellRecordBoard.ToolBar**、**PisellRecordBoard.BatchActionBar**、**PisellRecordBoard.Pagination**；ToolBar 内搜索默认 PisellFind，通过打散传入的 **toolBar.search** 透传或关闭；右侧默认 PisellFilter，筛选值存于 **searchParams.filter**；列设置入口由 **toolBar.columnSetting** 控制（默认 true，有 grid.columns 时显示）。Shell Frame 内分页使用定制样式（`shellFrame/Pagination/index.less`）。
+- Layout（GridLayout / CardLayout）只渲染内容区（Grid / CardList，不含分页），通过 **useRecordBoardContext** 消费上下文。
+- 也可单独使用 Search、ToolBar、BatchActionBar、Grid、CardList、Pagination 做自定义组合。
+
+## 4 多选与 BatchActionBar
+
+- 容器在 context 中提供 `selectedKeys`、`selectedRows`、`onSelectionChange`、`rowKey`（多选由 **grid.selectedKeys / grid.selectedRows / grid.onSelectionChange** 传入，容器合并进 context）。
+- **PisellRecordBoard.BatchActionBar** 对接 **PisellBatchActionBar**：有选中项时展示，全选/反选/清空基于当前页 `data`；删除、自定义 actions 等通过打散传入的 **batchActionBar** 或直接传 props。
+- 使用 **Shell Frame** 时已包含 BatchActionBar；Grid/卡片视图需将 `rowSelection` 与 context 的 `selectedKeys`、`onSelectionChange` 对接，多选勾选才会生效。
+
+## 5 使用方式
+
+以下示例自包含：所需类型与变量均在块内定义或从 `@pisell/materials`、`antd` 引入。
+
+```tsx
+import React from 'react';
+import { PisellRecordBoard } from '@pisell/materials';
+import { Button } from 'antd';
+
+const list: { id: string; name: string }[] = [];
+const contextValue = {
+  data: list,
+  loading: false,
+  total: 0,
+  pagination: { pageNumber: 1, pageSize: 10 },
+  onPageChange: () => {},
+  searchParams: {},
+  onSearch: () => {},
+  layoutType: 'grid' as const,
+  rowKey: 'id',
+};
+
+// 推荐：Shell Frame + Layout（工具栏、多选栏由 Shell Frame 提供）
+function ExampleWithShellFrame() {
+  return (
+    <PisellRecordBoard layoutType="grid" rowKey="id" {...contextValue} grid={{ columns: [] }}>
+      <PisellRecordBoard.ShellFrame>
+        <PisellRecordBoard.GridLayout />
+      </PisellRecordBoard.ShellFrame>
+    </PisellRecordBoard>
+  );
+}
+
+// 仅内容区（无 ToolBar / BatchActionBar）
+function ExampleContentOnly() {
+  return (
+    <PisellRecordBoard {...contextValue}>
+      <PisellRecordBoard.GridLayout />
+    </PisellRecordBoard>
+  );
+}
+
+// 自定义组合：ToolBar + BatchActionBar + Grid + 分页
+function ExampleCustomCombo() {
+  return (
+    <PisellRecordBoard rowKey="id" {...contextValue}>
+      <PisellRecordBoard.ToolBar />
+      <PisellRecordBoard.BatchActionBar />
+      <PisellRecordBoard.Grid />
+      <PisellRecordBoard.Pagination />
+    </PisellRecordBoard>
+  );
+}
+
+// 工具栏透传（打散传入 toolBar）
+function ExampleWithToolBarProps() {
+  return (
+    <PisellRecordBoard
+      layoutType="grid"
+      rowKey="id"
+      {...contextValue}
+      toolBar={{
+        topLeft: <Button>新建</Button>,
+        search: { triggerType: 'input' },
+        filter: { hiddenOtherFilter: false },
+      }}
+    >
+      <PisellRecordBoard.ShellFrame>
+        <PisellRecordBoard.GridLayout />
+      </PisellRecordBoard.ShellFrame>
+    </PisellRecordBoard>
+  );
+}
+
+// 默认导出：推荐用法（Shell Frame + GridLayout），便于文档/Story 直接渲染
+export default ExampleWithShellFrame;
+```
+
+## 6 扩展
+
+- **扩展新 Layout**：在 `layouts/` 下新建 XXXLayout，只实现内容区（如列表 + 分页），在根 index 挂到 `PisellRecordBoard.XXXLayout`。使用时由 Shell Frame 包裹即可获得 ToolBar、BatchActionBar。
+- **扩展 Shell Frame**：在 `shellFrame/` 中增加新槽位（如筛选栏、Tab），在 ShellFrame 组件内按需渲染。
+
+## 7 与 DataSourceContainer 对接
+
+容器支持受控用法：传入打散的 **data**、**loading**、**pagination**、**onPageChange**、**searchParams**、**onSearch**、**onReset** 等，由上层（如基于 `PisellDataSourceContainer` 或 useRequest）维护后再传给本组件即可；子组件配置通过 **grid**、**toolBar**、**search**、**paginationConfig**、**batchActionBar**、**cardList** 打散传入。

package/es/components/pisellRecordBoard/docs/PisellRecordBoard.$tab-dev.md

@@ -0,0 +1,82 @@
+---
+title: 开发文档
+order: 3
+category: pro
+---
+
+# PisellRecordBoard 组件开发文档
+
+## 1 组件信息
+
+### 1.1 基本信息
+
+- **组件名称**：PisellRecordBoard
+- **组件分类**：Pro 容器 / 列表看板
+- **开发状态**：维护中
+
+### 1.2 组件描述
+
+PisellRecordBoard 是记录看板容器，提供统一的 data、pagination、searchParams、onSearch、多选等上下文，支持 Grid 与 Card 两种布局。ToolBar 根据 grid.columns 自动派生筛选与排序；列上配置 type 时表格用 Pisell 组件只读渲染、筛选用编辑态、排序从 SortOptions 派生；无 type 时需自行配置 render、filter、sort，且支持 filter.component 自定义筛选组件。
+
+## 2 功能点
+
+### 2.1 核心功能
+
+- 受控 Context：value 注入 data、pagination、searchParams、onSearch、onReset、多选等
+- ShellFrame：ToolBar + BatchActionBar + Layout + Pagination
+- GridLayout / CardLayout：表格布局、卡片布局
+- 列驱动：processColumnsForGrid、deriveFilterFromColumns、deriveSortFromColumns
+
+### 2.2 列配置
+
+- 有 type：表格只读、筛选编辑态、排序 SortOptions，可被 render/filter/sort 覆盖
+- 无 type：表格纯文本或 render；筛选需 filter（type 或 component）；排序需 sort（type 或 getSortItems）
+- filter.component：无 type 时可用，组件需 value/onChange，由 Form 注入
+
+### 2.3 工具栏
+
+- 左侧：QuickFilter（仅 quickFilter: true 的列）+ PisellFind + slots.topLeft
+- 右侧：列设置（ColumnSetting，有 grid.columns 且 toolBar.columnSetting !== false 时显示）、Sort、PisellFilter（仅 otherFilter）、ToolBarReset、slots.topRight
+- toolBar.quickFilter：true 或对象（filterList、formFiltersPrefix、size）
+- toolBar.columnSetting：是否显示列显示隐藏入口，默认 true
+
+## 3 组件 API
+
+### 3.1 类型
+
+- **RecordBoardColumnType**：列配置，兼容 antd Table Column，扩展 type、fieldProps（含 options/getOptions）、filterable、filter、sortable、sort
+- **RecordBoardOptionItem**：选项格式 `{ label, value, color? }`，用于 options/getOptions；color 用于只读态 Tag
+- **RecordBoardGetOptions**：同步或异步返回选项列表，用于 fieldProps.getOptions、filter.getOptions
+- **RecordBoardColumnFilterConfig**：filter 配置，type 或 component（value/onChange）；type 为 single 时支持 options 或 getOptions
+- **RecordBoardContextValue**：Context 值，data、pagination、searchParams、onSearch、多选等；columnVisibility、onColumnVisibilityChange 由容器内部维护并注入
+- **RecordBoardChildComponentProps**：grid、toolBar（含 columnSetting）、pagination、batchActionBar 等透传
+
+### 3.2 工具函数（recordBoardColumns.tsx）
+
+- **processColumnsForGrid(columns)**：对带 type 的列注入 Pisell 只读 render（有 render 则用 render）；支持 getOptions 异步选项
+- **getRecordBoardColumnKey(column)**：获取列唯一 key，供列显示隐藏等使用
+- **deriveFilterFromColumns(columns)**：返回 quickFilter、otherFilter，有 type 可由 filter 覆盖；支持 filter.getOptions
+- **deriveSortFromColumns(columns)**：返回 SortItemProps 数组，有 type 可由 sort 覆盖
+
+## 4 目录结构
+
+```
+pisellRecordBoard/
+├── index.tsx
+├── PisellRecordBoard.tsx
+├── types.ts
+├── context/
+├── hooks/
+├── shellFrame/  # ToolBar、ColumnSetting、Pagination（含 index.less 分页样式）等
+├── layouts/GridLayout | CardLayout
+├── utils/recordBoardColumns.tsx, withRecordBoard.tsx
+├── docs/
+├── PisellRecordBoard.stories.tsx
+└── README.md
+```
+
+## 5 扩展说明
+
+- 扩展新 Layout：在 layouts 下新建 XXXLayout，挂到 PisellRecordBoard.XXXLayout
+- 扩展 ToolBar 槽位：在 shellFrame/ToolBar 中增加 slots 或 quickFilter/search 配置
+- 新增列 type：在 recordBoardColumns 与 FilterItem 的映射中注册

package/es/components/pisellRecordBoard/docs/PisellRecordBoard.$tab-test.md

@@ -0,0 +1,70 @@
+---
+title: 测试文档
+order: 4
+category: pro
+---
+
+# PisellRecordBoard 组件测试用例文档
+
+## 1 测试概述
+
+### 1.1 测试目标
+
+确保 PisellRecordBoard 容器的 Context 注入、子组件组合、列驱动筛选/排序逻辑正确，覆盖有 type/无 type、覆盖行为及边界情况。
+
+### 1.2 测试范围
+
+- 打散传入的 data / pagination / grid / toolBar 等与默认占位 context
+- ShellFrame + GridLayout / CardLayout 组合渲染
+- 列配置：有 type 时表格/筛选/排序自动派生
+- 列配置：无 type 时 filterable + filter、sortable + sort
+- 列配置：有 type 时 render、filter、sort 覆盖
+- processColumnsForGrid、deriveFilterFromColumns、deriveSortFromColumns 工具函数
+- ToolBar QuickFilter 与 Filter 弹层（quickFilter / otherFilter 分配）
+- 多选与 BatchActionBar 展示
+
+### 1.3 测试方法
+
+- 单元测试：Context 值、列派生结果、工具函数
+- Storybook：交互与 UI 验证
+- 人工测试：筛选/排序/分页/多选全流程
+
+## 2 单元测试用例（建议）
+
+### 2.1 工具函数
+
+#### processColumnsForGrid
+
+- 无 columns 或空数组返回原样
+- 有 type 且无 render 时注入 Pisell 只读 render
+- 有 type 且有 render 时保留 render，不注入
+
+#### deriveFilterFromColumns
+
+- filterable === false 的列不生成筛项
+- 有 type 且无显式 filter 时按 FIELD_TYPE_TO_FILTER_TYPE 生成
+- 有 type 且有 filter（type 或 component）时用 filter 生成
+- 无 type 且 filterable + filter 时按 filter.type 或 filter.component 生成
+- quickFilter: true 的项进入 quickFilter，否则进入 otherFilter
+
+#### deriveSortFromColumns
+
+- sortable === false 的列不生成排序项
+- 有 type 且无 sort 时按 SortOptions 派生
+- 有 type 且有 sort 时用 sort 生成
+- 无 type 且 sortable + sort 时按 sort.type 或 sort.getSortItems 生成
+
+### 2.2 容器与 Context
+
+- 不传打散 props 时使用默认占位 context（data 空数组、空 searchParams）
+- 传入打散 props 时 context 由容器合并得到（含 data、layoutType、rowKey、grid、toolBar 等）
+- 多选由 grid.selectedKeys / grid.selectedRows / grid.onSelectionChange 传入；未传时使用内部 selectedKeys/selectedRows 与 onSelectionChange
+
+### 2.3 子组件挂载
+
+- PisellRecordBoard.ShellFrame、GridLayout、ToolBar、Grid、Pagination、BatchActionBar、useRecordBoardContext 等子组件存在且可调用
+
+## 3 Storybook 覆盖
+
+- GridLayoutWithTable、GridLayoutWithQuickFilterOnLeft、CustomFilterSortRender 等 story 覆盖列驱动、QuickFilter、自定义 filter/sort/render
+- 排序、筛选、重置、分页、多选交互可在 Storybook 中人工验证