@pisell/materials 3.3.88 → 3.3.89

package/es/components/pisellPhone/utils/countryCodeHelper.d.ts

@@ -0,0 +1,35 @@
+import type { CountryCode, PisellPhoneProps } from '../types';
+/**
+ * 根据国家码获取国旗 emoji
+ * @param countryCode 国家码
+ * @returns 国旗 emoji
+ */
+export declare function getCountryFlag(countryCode: string): string;
+/**
+ * 根据国家码获取最大长度
+ * @param countryCode 国家码
+ * @param countryCodes 国家码列表
+ * @returns 最大长度
+ */
+export declare function getMaxLength(countryCode: string, countryCodes: CountryCode[]): number;
+/**
+ * 根据国家码获取配置
+ * @param countryCode 国家码
+ * @param countryCodes 国家码列表
+ * @returns 国家码配置
+ */
+export declare function getCountryConfig(countryCode: string, countryCodes: CountryCode[]): CountryCode | undefined;
+/**
+ * 获取最终的国家码列表
+ *
+ * 优先级：
+ * 1. props.countryCodes（完全自定义）
+ * 2. props.availableCountryCodes（从预设中过滤）
+ * 3. PRESET_COUNTRY_CODES（默认全部24个）
+ *
+ * 然后根据 props.commonCountryCodes 排序（置顶）
+ *
+ * @param props 组件 Props
+ * @returns 国家码列表
+ */
+export declare function getCountryCodes(props: PisellPhoneProps): CountryCode[];

package/es/components/pisellPhone/utils/phoneFormatter.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 电话号码格式化工具
+ */
+/**
+ * 中国大陆手机号格式化：138 0000 0000
+ */
+export declare function formatChinaMobile(phone: string): string;
+/**
+ * 美国/加拿大号码格式化：(555) 123-4567
+ */
+export declare function formatUSPhone(phone: string): string;
+/**
+ * 英国号码格式化：1234 567 8900
+ */
+export declare function formatUKPhone(phone: string): string;
+/**
+ * 根据国家码格式化电话号码
+ * @param phone 电话号码（纯数字）
+ * @param countryCode 国家码
+ * @returns 格式化后的电话号码
+ */
+export declare function formatPhone(phone: string, countryCode: string): string;
+/**
+ * 电话号码脱敏
+ * @param phone 电话号码
+ * @param pattern 脱敏模式
+ * @returns 脱敏后的号码
+ *
+ * @example
+ * maskPhone('13800000000', 'middle') // '138****0000'
+ * maskPhone('13800000000', 'last')   // '1380000****'
+ */
+export declare function maskPhone(phone: string, pattern?: 'middle' | 'last'): string;
+/**
+ * 检测号码类型（中国）
+ * @param phone 电话号码
+ * @returns 号码类型
+ */
+export declare function detectPhoneType(phone: string): 'mobile' | 'landline' | 'unknown';

package/es/components/pisellQuickFilter/type.d.ts

@@ -0,0 +1,12 @@
+/// <reference types="react" />
+import { FilterItemProps } from '../filter/types';
+import { FormInstance } from 'antd';
+export declare type PisellQuickFilterProps = FormInstance & {
+    hasForm?: boolean;
+    children?: React.ReactNode;
+    formFiltersPrefix: string;
+    filterList?: FilterItemProps[];
+    quickFilterMaxLength: number;
+    hiddenQuickFilter: boolean;
+    hiddenOtherFilter: boolean;
+};

package/es/components/pisellRating/PisellRating.d.ts

@@ -0,0 +1,31 @@
+import React from 'react';
+import type { PisellRatingProps } from './types';
+import './PisellRating.less';
+/**
+ * PisellRating 评分组件
+ *
+ * 基于 Ant Design Rate 组件开发，提供直观的星级评分交互。
+ * 支持只读、编辑、禁用三种状态。
+ *
+ * @param props 组件 Props
+ *
+ * @example
+ * // 基础使用
+ * const [rating, setRating] = useState(0);
+ * <PisellRating value={rating} onChange={setRating} />
+ *
+ * @example
+ * // 只读态
+ * <PisellRating mode="read" value={4.5} allowHalf />
+ *
+ * @example
+ * // 带评分描述
+ * <PisellRating
+ *   value={rating}
+ *   onChange={setRating}
+ *   tooltips={['很差', '差', '一般', '好', '很好']}
+ * />
+ */
+export declare const PisellRating: React.FC<PisellRatingProps>;
+declare const _default: React.NamedExoticComponent<PisellRatingProps>;
+export default _default;

package/es/components/pisellRecordBoard/context/RecordBoardContext.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="react" />
+import type { RecordBoardContextValue } from '../types';
+export declare const RecordBoardContext: import("react").Context<RecordBoardContextValue | null>;

package/es/components/pisellRecordBoard/context/RecordBoardProvider.d.ts

@@ -0,0 +1,11 @@
+import React, { ReactNode } from 'react';
+import type { RecordBoardContextValue } from '../types';
+export interface RecordBoardProviderProps {
+    value: RecordBoardContextValue;
+    children: ReactNode;
+}
+/**
+ * 仅负责注入 RecordBoard 上下文。
+ * 实际的数据源、onSearch/onPageChange 由上层（如接 DataSourceContainer 或独立 fetch）提供。
+ */
+export declare const RecordBoardProvider: React.FC<RecordBoardProviderProps>;

package/es/components/pisellRecordBoard/hooks/useRecordBoardContext.d.ts

@@ -0,0 +1,16 @@
+import type { RecordBoardContextValue, RecordBoardChildComponentProps, RecordBoardGridProps } from '../types';
+export interface UseRecordBoardContextOptions {
+    /** 子组件 displayName，用于从 childComponentProps 中取对应 props */
+    displayName?: keyof RecordBoardChildComponentProps;
+    /** 上层传入的 childComponentProps（若 Context 未提供则从参数传入） */
+    childComponentProps?: RecordBoardChildComponentProps;
+}
+/**
+ * 消费 RecordBoard 上下文，供各 layout 内子组件（Search / ToolBar / Grid / CardList / Pagination）使用。
+ * 若传入 displayName，返回会合并 childComponentProps[displayName] 便于透传。
+ * 当 displayName 为 'grid' 时，返回类型包含 RecordBoardGridProps（columns、scroll、size）。
+ */
+export declare function useRecordBoardContext(options: UseRecordBoardContextOptions & {
+    displayName: 'grid';
+}): RecordBoardContextValue & RecordBoardGridProps;
+export declare function useRecordBoardContext(options?: UseRecordBoardContextOptions): RecordBoardContextValue;

package/es/components/pisellRecordBoard/layouts/CardLayout/CardList.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import type { RecordBoardContextValue } from '../../types';
+export interface RecordBoardCardListProps extends Partial<Pick<RecordBoardContextValue, 'data' | 'loading'>> {
+    className?: string;
+    style?: React.CSSProperties;
+    render?: (ctx: RecordBoardContextValue) => React.ReactNode;
+}
+/**
+ * Card 布局下的数据视图：从 context 取 data / loading。
+ */
+declare const RecordBoardCardList: React.FC<RecordBoardCardListProps>;
+export default RecordBoardCardList;

package/es/components/pisellRecordBoard/layouts/CardLayout/index.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+import RecordBoardCardList from './CardList';
+/**
+ * Card 布局：仅内容区 = 卡片列表（不含分页）。
+ * 工具栏、多选操作栏、分页由 Shell Frame 提供，使用时用 ShellFrame 包裹：
+ * <PisellRecordBoard.ShellFrame><PisellRecordBoard.CardLayout /></PisellRecordBoard.ShellFrame>
+ */
+declare const CardLayout: React.FC<{
+    className?: string;
+    style?: React.CSSProperties;
+}>;
+export default CardLayout;
+export { RecordBoardCardList as CardLayoutCardList };

package/es/components/pisellRecordBoard/shellFrame/BatchActionBar/index.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+import type { PisellBatchActionBarProps } from '../../../pisellBatchActionBar';
+/**
+ * RecordBoard 下的多选操作栏：从 context 取选中态与数据，渲染 PisellBatchActionBar。
+ * 仅在有选中项时展示；全选/反选/清空基于当前页 data。
+ */
+declare const RecordBoardBatchActionBar: React.FC<Partial<PisellBatchActionBarProps>>;
+export default RecordBoardBatchActionBar;

package/es/components/pisellRecordBoard/shellFrame/Search/index.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+export interface RecordBoardSearchProps {
+    [key: string]: any;
+}
+/**
+ * RecordBoard 下的独立搜索槽：使用 PisellFind，绑定 context.searchParams.keyword 与 onSearch。
+ * 可通过 childComponentProps.search 透传 PisellFind 的 props。
+ */
+declare const RecordBoardSearch: React.FC<RecordBoardSearchProps>;
+export default RecordBoardSearch;

package/es/components/pisellRecordBoard/shellFrame/ToolBarReset/index.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+import './index.less';
+export interface ToolBarResetProps {
+    /** 按钮尺寸，与 antd Button 一致，默认与筛选按钮对齐为 large */
+    size?: 'small' | 'middle' | 'large';
+    /** 按钮类型 */
+    type?: 'default' | 'primary' | 'link' | 'text';
+    /** 按钮文案，默认使用多语言「重置」 */
+    children?: React.ReactNode;
+}
+/**
+ * RecordBoard 工具栏重置按钮：清空筛选与排序并刷新表格。
+ * 点击后以空 filter.values、清空 sort 调用 onSearch，并调用 onReset（若提供）。
+ */
+declare const ToolBarReset: React.FC<ToolBarResetProps>;
+export default ToolBarReset;

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

@@ -0,0 +1,315 @@
+import type { ReactNode, Key, ComponentType } from 'react';
+import type { TableProps } from 'antd';
+/**
+ * 布局类型：一种 layout 对应一种「视图的集合」
+ * - grid: 搜索 + 表格 + 分页
+ * - card: 搜索 + 卡片列表 + 分页
+ * 后续可扩展 list、kanban 等
+ */
+export declare type RecordBoardLayoutType = 'grid' | 'card';
+/**
+ * 列字段类型：对应 Pisell 表单组件，传入列 type 时用该组件自动渲染列（只读）与筛选项（编辑）
+ */
+export declare type RecordBoardFieldType = 'singleLineText' | 'longText' | 'email' | 'phone' | 'url' | 'number' | 'currency' | 'percent' | 'rating' | 'singleSelect' | 'multipleSelect' | 'dateTime';
+/** 无 type 时筛选项可传入自定义组件，需支持 value / onChange 以接入 Form */
+export declare type RecordBoardFilterComponentProps = {
+    value?: any;
+    onChange?: (value: any) => void;
+    [key: string]: any;
+};
+/** 选项格式，用于 getOptions / options；color 用于只读态 Tag 展示 */
+export declare type RecordBoardOptionItem = {
+    label: string;
+    value: any;
+    /** 只读态 Tag 颜色，如 '#e6f7ff' 或 antd 预设 'blue' */
+    color?: string;
+};
+/** 同步或异步返回选项列表，singleSelect/multipleSelect 的 fieldProps.getOptions 或 filter.getOptions 使用 */
+export declare type RecordBoardGetOptions = (() => RecordBoardOptionItem[]) | (() => Promise<RecordBoardOptionItem[]>);
+/** 列筛选配置：不传列 type 时使用。可配置 type + options/props，或传入 component（接收 value/onChange）。 */
+export interface RecordBoardColumnFilterConfig {
+    type?: 'single' | 'input' | 'datePicker' | 'rangePicker' | 'rangePickerNew' | 'search';
+    label?: string;
+    options?: RecordBoardOptionItem[];
+    /** 同步或异步获取选项，与 options 二选一；支持 singleSelect/multipleSelect 及无 type 时 type:'single' */
+    getOptions?: RecordBoardGetOptions;
+    props?: Record<string, any>;
+    /** 放在快速筛选(true)还是高级筛选(false) */
+    quickFilter?: boolean;
+    /** 无 type 时可用：自定义筛选组件，由 Form 注入 value/onChange */
+    component?: ComponentType<RecordBoardFilterComponentProps>;
+}
+/**
+ * RecordBoard 列类型扩展（与 antd Table Column 兼容，仅增加可选字段）。
+ *
+ * 有 type（如 singleLineText）时：
+ * - 表格：自动用对应 Pisell 组件只读渲染；传入 render 则优先使用（覆盖）。
+ * - 筛选：自动用对应组件编辑态；传入 filter（type 或 component）则优先使用（覆盖）。
+ * - 排序：自动从组件 SortOptions 派生；传入 sort 则优先使用（覆盖）。
+ *
+ * 无 type 时：
+ * - 表格：无 render 则纯文本；可自定义 render。
+ * - 筛选：需配置 filterable + filter（type 或 component，component 需 value/onChange）。
+ * - 排序：需配置 sortable + sort（type 或 getSortItems）。
+ */
+export interface RecordBoardColumnType<RecordType = any> {
+    title?: ReactNode;
+    dataIndex?: string | string[];
+    key?: string;
+    width?: number | string;
+    align?: 'left' | 'right' | 'center';
+    fixed?: 'left' | 'right' | boolean;
+    ellipsis?: boolean;
+    /** 列渲染；无 type 时必靠此或默认纯文本；有 type 时可选，传入则覆盖自动派生 */
+    render?: (value: any, record: RecordType, index: number) => ReactNode;
+    /** 其他 antd 列属性 */
+    [key: string]: any;
+    /** 字段类型；传入则表格/筛选/排序自动派生，可被 render/filter/sort 覆盖 */
+    type?: RecordBoardFieldType;
+    /**
+     * 传给 Pisell 组件的额外 props（type 存在且未用 filter/render 覆盖时生效）。
+     * singleSelect/multipleSelect 时支持 options 或 getOptions（同步/异步返回选项列表）。
+     */
+    fieldProps?: Record<string, any>;
+    /** 是否参与筛选；false 时不生成筛项；有 type 时默认 true */
+    filterable?: boolean;
+    /** 筛选配置；无 type 时必传 type 或 component；有 type 时可选，传入则覆盖自动派生 */
+    filter?: RecordBoardColumnFilterConfig;
+    /** 是否参与排序；false 时不生成排序项；有 type 时默认 true */
+    sortable?: boolean;
+    /**
+     * 排序配置；无 type 时需 sortable + sort；有 type 时可选，传入则覆盖自动派生。
+     * - type：内置排序子项（string/number/option 等）。
+     * - getSortItems：(fieldKey) => [{ key, label }]。
+     */
+    sort?: {
+        type?: 'date' | 'string' | 'number' | 'option';
+        label?: string;
+        isHidden?: boolean;
+        /** 自定义排序子项，优先于 type；fieldKey 为列 key/dataIndex */
+        getSortItems?: (fieldKey: string) => Array<{
+            key: string;
+            label: string;
+        }>;
+    };
+    /** 默认隐藏该列，与 grid.defaultHiddenColumnKeys 合并参与初始化列显隐 */
+    hidden?: boolean;
+    /**
+     * 当开启 grid.collapseUniformColumns 时，用此函数从 (value, record) 得到用于比较的值；
+     * 返回 string 或 number 时参与全等比较，返回 null/undefined 则该列不参与折叠。
+     * 未传则用 dataIndex 取值；与 render 类似，便于从复杂数据中抽取值再判断是否全同。
+     */
+    uniformCompare?: (value: any, record: any) => string | number | null | undefined;
+    /**
+     * 当开启 grid.collapseUniformColumns 时，为 false 则该列即使全列同值/全空也不折叠、不进入总结区；默认 true。
+     */
+    collapseWhenUniform?: boolean;
+}
+/**
+ * 分页状态（与容器内部一致）
+ */
+export interface RecordBoardPaginationState {
+    pageNumber: number;
+    pageSize: number;
+}
+/**
+ * 列表请求结果（与 dataSource / useRequest 等对齐）
+ */
+export interface RecordBoardListResult {
+    list: any[];
+    count?: number;
+    total?: number;
+}
+/**
+ * RecordBoard 容器 Context 值
+ * 与具体 layout 类型无关，所有 layout 共用同一套数据与操作
+ */
+export interface RecordBoardContextValue {
+    /** 当前列表数据 */
+    data: any[];
+    /** 加载态 */
+    loading: boolean;
+    /** 总数（用于分页） */
+    total: number;
+    /** 分页状态 */
+    pagination: RecordBoardPaginationState;
+    /** 分页变更 */
+    onPageChange: (pageNumber: number, pageSize: number) => void;
+    /** 搜索/筛选参数 */
+    searchParams: Record<string, any>;
+    /** 触发搜索（会重置到第一页） */
+    onSearch: (params: Record<string, any>) => void;
+    /** 重置搜索 */
+    onReset?: () => void;
+    /** 当前布局类型，供子组件按需做差异化 */
+    layoutType: RecordBoardLayoutType;
+    /** 多选：当前选中的 key 列表 */
+    selectedKeys: Key[];
+    /** 多选：当前选中的行数据 */
+    selectedRows: any[];
+    /** 多选：选择变更回调（表格/卡片勾选、BatchActionBar 全选/清空/反选时调用） */
+    onSelectionChange: (keys: Key[], rows: any[]) => void;
+    /** 行主键，用于多选与列表渲染，如 'id' 或 (record) => record.id */
+    rowKey?: string | ((record: any) => Key);
+    /**
+     * 列显示隐藏状态（仅影响表格/卡片列展示，不影响 filter/sort 配置）。
+     * key 为列 key/dataIndex，value 为是否显示；未出现的列默认显示。
+     */
+    columnVisibility?: Record<string, boolean>;
+    /** 列显示隐藏变更回调 */
+    onColumnVisibilityChange?: (visibility: Record<string, boolean>) => void;
+    /** 列 key 顺序（用于列设置弹层拖拽排序），未设置时按 grid.columns 顺序 */
+    columnOrder?: string[] | null;
+    /** 列顺序变更回调（拖拽排序后） */
+    onColumnOrderChange?: (columnKeys: string[]) => void;
+    /** 各子组件透传 props，由 Provider 注入 */
+    childComponentProps?: RecordBoardChildComponentProps;
+    /** 是否占满父容器高度，供 ShellFrame 做弹性布局（内容区纯 CSS 滚动 + 表头 sticky；scroll.autoCalc 时用测量高度） */
+    fillHeight?: boolean;
+    /** 内容区滚动容器高度（fillHeight 且 grid.scroll.autoCalc 时由 ShellFrame 测量），供 Grid 计算 scroll.y */
+    scrollAreaHeight?: number | null;
+    /** 设置内容区滚动容器高度（由 ShellFrame 测量组件调用） */
+    setScrollAreaHeight?: (height: number | null) => void;
+    /** 点击重置时递增，供 ToolBar 给 PisellFilter 设 key 以强制重挂载，清空弹窗内表单 */
+    filterResetKey?: number;
+    /** 递增 filterResetKey，由 ToolBarReset 在重置时调用 */
+    setFilterResetKey?: (fn: (prev: number) => number) => void;
+}
+/**
+ * 各 layout 下子组件的可选透传配置（类似 ChildComponentProps）
+ */
+/**
+ * BatchActionBar 透传配置，与 PisellBatchActionBar 的 props 对齐。
+ * 具体类型见 PisellBatchActionBarProps，此处仅做透传用。
+ */
+export declare type RecordBoardBatchActionBarProps = Record<string, any>;
+/** Filter 透传配置，与 PisellFilter 的 props 对齐 */
+export declare type RecordBoardFilterProps = Record<string, any>;
+/**
+ * ToolBar 透传配置。
+ * - 继承 PisellToolBar 的 slots：topLeft、topRight、bottomLeft、bottomRight、tabs。
+ * - search：默认在工具栏内渲染 PisellFind；为对象时透传为 PisellFind 的 props；为 false 时不渲染搜索。
+ * - filter：默认在工具栏右侧渲染 PisellFilter；为对象时透传 PisellFilter props；为 false 时不渲染。筛选值绑定 searchParams.filter，变更触发 onSearch。
+ */
+export interface RecordBoardToolBarProps {
+    className?: string;
+    style?: React.CSSProperties;
+    tabs?: React.ReactNode;
+    topLeft?: React.ReactNode;
+    topRight?: React.ReactNode;
+    bottomLeft?: React.ReactNode;
+    bottomRight?: React.ReactNode;
+    /** 在 ToolBar 内渲染搜索：默认 PisellFind；对象透传 PisellFind props；false 不渲染 */
+    search?: boolean | RecordBoardSearchProps;
+    /** 在 ToolBar 右侧渲染筛选：默认 PisellFilter；对象透传 PisellFilter props；false 不渲染。值存于 searchParams.filter */
+    filter?: boolean | RecordBoardFilterProps;
+    /** 在 ToolBar 内、筛选左侧渲染排序：默认 Sort；对象可传 list、placement 等；false 不渲染。值存于 searchParams.sort */
+    sort?: boolean | Record<string, any>;
+    /**
+     * 在 ToolBar 左侧展示内联快速筛选（替代 Filter 弹层内的 quickFilter）。
+     * 为 true 时使用 columns 派生的 quickFilter 列表；为对象时可传 filterList、formFiltersPrefix、size 等。
+     * 启用后建议对 filter 传 hiddenQuickFilter: true，弹层内仅保留高级筛选。
+     */
+    quickFilter?: boolean | Record<string, any>;
+    /** 列显示隐藏设置入口；默认 true（有 grid.columns 时显示）；false 时不渲染 */
+    columnSetting?: boolean;
+}
+/** Search 透传配置，与 PisellFind 的 props 对齐 */
+export declare type RecordBoardSearchProps = Record<string, any>;
+/**
+ * Grid 布局透传配置，对应 RecordBoardGridView 的 props（useRecordBoardContext('grid') 会将其合并到 context）。
+ * 基于 antd TableProps，省略由 context 注入或组件自管的项（dataSource、loading、pagination、columns、scroll、size、rowSelection）。
+ * 多选用 selectedKeys/selectedRows/onSelectionChange；其余 Table props（如 onRow、onHeaderRow、expandable、rowClassName、summary）透传。
+ */
+export declare type RecordBoardGridProps = {
+    /** 列配置；ToolBar 据此派生筛选与排序，ColumnSetting 据此做列显示隐藏 */
+    columns?: RecordBoardColumnType[];
+    /** 默认隐藏的列 key 列表（对应 columns 的 key 或 dataIndex），用于初始化列显隐状态 */
+    defaultHiddenColumnKeys?: string[];
+    /**
+     * 当前页某列全部同值或全部为空时：隐藏该列，并在表格上方展示总结区（列名 + 统一值/空数据）。
+     * 比较规则：列可配置 uniformCompare(value, record) 返回用于比较的 string/number；否则用 dataIndex 取值；仅 string/number 参与比较，undefined/null 不参与。
+     * 默认 true；传 false 可关闭。
+     */
+    collapseUniformColumns?: boolean;
+    /**
+     * 表格滚动配置，对齐 materials Table useGenScroll。
+     * - x / y：同 antd Table scroll。
+     * - autoCalc：为 true 时根据内容区高度自动计算 scroll.y（需 fillHeight），表头固定、表体滚动。
+     * - scrollToFirstRowOnChange：翻页后是否滚动到第一行。
+     */
+    scroll?: {
+        x?: number | string;
+        y?: number | string;
+        autoCalc?: boolean;
+        scrollToFirstRowOnChange?: boolean;
+    };
+    /** 表格尺寸 */
+    size?: 'small' | 'middle' | 'default';
+    /** 当前选中的行 key 列表（多选） */
+    selectedKeys?: Key[];
+    /** 当前选中的行数据（多选） */
+    selectedRows?: unknown[];
+    /** 多选变更回调 */
+    onSelectionChange?: (keys: Key[], rows: unknown[]) => void;
+    /** 多选列配置：fixed、columnWidth 等，与 selectedKeys/onSelectionChange 合并为 Table rowSelection */
+    rowSelection?: Partial<Omit<NonNullable<TableProps<unknown>['rowSelection']>, 'selectedRowKeys' | 'onChange'>>;
+} & Omit<TableProps<unknown>, 'dataSource' | 'loading' | 'pagination' | 'columns' | 'scroll' | 'size' | 'rowSelection'>;
+export interface RecordBoardChildComponentProps {
+    /** 搜索配置，透传给 PisellFind；关键词绑定 searchParams.keyword */
+    search?: RecordBoardSearchProps;
+    /** 工具栏配置，透传给 PisellToolBar；内置搜索会接 context.searchParams/onSearch */
+    toolBar?: RecordBoardToolBarProps;
+    pagination?: Record<string, any>;
+    /** Grid 布局配置：列、滚动、尺寸等，透传给 RecordBoardGridView */
+    grid?: RecordBoardGridProps;
+    cardList?: Record<string, any>;
+    /** 多选操作栏配置，透传给 PisellBatchActionBar */
+    batchActionBar?: RecordBoardBatchActionBarProps;
+}
+/**
+ * RecordBoard 容器 Props。
+ * 仅打散传参：列表/分页/搜索/多选/列显隐、以及 grid/toolBar/search/paginationConfig/batchActionBar/cardList 独立传入。
+ */
+export interface RecordBoardProps {
+    /** 子节点，一般为某种 Layout 或自定义组合 */
+    children?: ReactNode;
+    /** 当前使用的布局类型 */
+    layoutType?: RecordBoardLayoutType;
+    /** 行主键，用于多选与列表 */
+    rowKey?: string | ((record: any) => Key);
+    /** 当前列表数据 */
+    data?: any[];
+    /** 加载态 */
+    loading?: boolean;
+    /** 总数（用于分页） */
+    total?: number;
+    /** 分页状态 */
+    pagination?: RecordBoardPaginationState;
+    /** 分页变更 */
+    onPageChange?: (pageNumber: number, pageSize: number) => void;
+    /** 搜索/筛选参数 */
+    searchParams?: Record<string, any>;
+    /** 触发搜索（会重置到第一页） */
+    onSearch?: (params: Record<string, any>) => void;
+    /** 重置搜索 */
+    onReset?: () => void;
+    /** 列显隐持久化：传入则用 @pisell/utils 的 getComponentStorageKey 规则写入 localStorage；低代码可传 __id */
+    columnVisibilityStorageKey?: string;
+    /** Grid 配置：列、滚动、尺寸等 */
+    grid?: RecordBoardGridProps;
+    /** 工具栏配置 */
+    toolBar?: RecordBoardToolBarProps;
+    /** 搜索配置，透传给 PisellFind */
+    search?: RecordBoardSearchProps;
+    /** 分页组件透传配置（与 pagination 状态区分，此处为 Pagination 组件 props） */
+    paginationConfig?: Record<string, any>;
+    /** 多选操作栏配置 */
+    batchActionBar?: RecordBoardBatchActionBarProps;
+    /** 卡片列表配置 */
+    cardList?: Record<string, any>;
+    /** 是否启用分页（与 pagination 状态区分） */
+    enablePagination?: boolean;
+    /** 其他 */
+    [key: string]: any;
+}

package/es/components/pisellRecordBoard/utils/withRecordBoard.d.ts

@@ -0,0 +1,9 @@
+import React, { ComponentType } from 'react';
+import type { RecordBoardContextValue, RecordBoardChildComponentProps } from '../types';
+declare type RecordBoardDisplayName = keyof RecordBoardChildComponentProps;
+/**
+ * 为 RecordBoard 下的子组件注入 context，并合并 childComponentProps[displayName]。
+ * 用于 Search / ToolBar / Pagination / Grid / CardList 等「被接管」的通用组件封装。
+ */
+declare function withRecordBoard<P extends object, R = any>(WrappedComponent: ComponentType<P & RecordBoardContextValue>, displayName: RecordBoardDisplayName): React.ForwardRefExoticComponent<React.PropsWithoutRef<P> & React.RefAttributes<R>>;
+export default withRecordBoard;

package/es/components/pisellShellFrame/PisellShellFrame.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+import type { PisellShellFrameProps } from './types';
+import './PisellShellFrame.less';
+/**
+ * PisellShellFrame：通用壳层布局组件。
+ * 支持通过 config 控制各区域显隐，不同展示类型（表格/看板/日历/楼层图等）复用同一壳层。
+ *
+ * - 顶部：标题区（标题/副标题/辅助信息）、工具区（Toolbar）、统计区（Statistic List，可选折叠）
+ * - 中间：滚动承载（可选）+ Layout 插槽（children）
+ * - 底部：批量操作条（按选中状态出现）、状态提示区（加载/错误/同步提示等）
+ */
+export declare const PisellShellFrame: React.FC<PisellShellFrameProps>;
+export default PisellShellFrame;

package/es/components/pisellShellFrame/PisellShellFrame.stories.d.ts

@@ -0,0 +1,15 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { PisellShellFrame } from './PisellShellFrame';
+declare const meta: Meta<typeof PisellShellFrame>;
+export default meta;
+declare type Story = StoryObj<typeof PisellShellFrame>;
+/** 仅标题区 */
+export declare const TitleOnly: Story;
+/** 标题 + 工具区 */
+export declare const WithToolbar: Story;
+/** 标题 + 统计区（可折叠，国际化） */
+export declare const WithStatisticCollapsible: Story;
+/** 中间滚动 + 底部批量条 + 状态区 */
+export declare const WithScrollBatchAndStatus: Story;
+/** 全区域展示（默认展开统计） */
+export declare const Full: Story;

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

@@ -0,0 +1,2 @@
+export { PisellShellFrame, default } from './PisellShellFrame';
+export type { PisellShellFrameProps, PisellShellFrameConfig, PisellShellFrameScrollConfig, } from './types';

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

@@ -0,0 +1,56 @@
+import type { ReactNode, CSSProperties } from 'react';
+/**
+ * 滚动配置：为 true 时使用默认滚动；为对象时传入样式或 scroll 相关配置。
+ */
+export declare type PisellShellFrameScrollConfig = boolean | {
+    style?: CSSProperties;
+    className?: string;
+};
+/**
+ * PisellShellFrame 配置：控制各区域的展示与行为。
+ * 不同展示类型（表格/看板/日历等）复用同一壳层，通过配置控制显隐。
+ */
+export interface PisellShellFrameConfig {
+    /** 是否展示顶部标题区（标题/副标题/辅助信息） */
+    showTitle?: boolean;
+    /** 是否展示顶部工具区（Toolbar） */
+    showToolbar?: boolean;
+    /** 是否展示顶部统计区（Statistic List） */
+    showStatistic?: boolean;
+    /** 统计区是否支持折叠，仅 showStatistic 为 true 时有效 */
+    statisticCollapsible?: boolean;
+    /** 中间内容区是否使用滚动承载包裹；为 true 时默认 overflow auto */
+    scroll?: PisellShellFrameScrollConfig;
+    /** 是否展示底部批量操作条（按选中状态出现由调用方控制，此处仅控制是否渲染该槽位） */
+    showBatchActionBar?: boolean;
+    /** 是否展示底部状态提示区（加载/错误/同步提示等） */
+    showStatusArea?: boolean;
+}
+/**
+ * PisellShellFrame 组件 Props。
+ * 通过 config 控制各区域显隐，通过 slot props 传入各区域内容。
+ */
+export interface PisellShellFrameProps {
+    /** 类名 */
+    className?: string;
+    /** 内联样式 */
+    style?: CSSProperties;
+    /** 区域显隐与行为配置，未传则默认不展示可选区域 */
+    config?: PisellShellFrameConfig;
+    /** 标题 */
+    title?: ReactNode;
+    /** 副标题 */
+    subtitle?: ReactNode;
+    /** 标题区右侧辅助信息 */
+    titleExtra?: ReactNode;
+    /** 工具栏内容 */
+    toolbar?: ReactNode;
+    /** 统计列表内容（如 PisellStatisticList 或自定义） */
+    statisticList?: ReactNode;
+    /** 主内容（表格/看板/日历/楼层图等），当 config.scroll 为 true 时会被滚动容器包裹 */
+    children?: ReactNode;
+    /** 批量操作条，通常按选中状态显隐由调用方控制 */
+    batchActionBar?: ReactNode;
+    /** 状态提示（加载/错误/同步提示等） */
+    statusArea?: ReactNode;
+}