@pisell/materials 1.8.41 → 1.8.42

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

@@ -1,6 +1,7 @@
 import { FloorMapDataSources, FloorMapLayoutContextValue, PisellFloorMapLayoutProps, PisellFloorMapLayoutRef } from "../pisellFloorMapLayout/types.js";
 import { TimeRangeOption } from "../pisellTimeNavigator/types.js";
 import { CalendarPersistContextValue } from "./shellFrame/Calendar/calendarPersistGuard.js";
+import { VenueWallAppearanceTheme, VenueWallStatusToneOverrides } from "./shellFrame/ResourceWall/venueWallUtils.js";
 import { CSSProperties, ComponentType, Key, ReactNode, Ref } from "react";
 import { TableProps } from "antd";
 
@@ -12,6 +13,11 @@ import { TableProps } from "antd";
  * 后续可扩展 list、kanban 等
  */
 type RecordBoardLayoutType = 'grid' | 'card';
+/**
+ * 列表区布局变体：`phone` 时 Grid 收紧列宽与单元格 padding，ToolBar 可配合 compact-narrow。
+ * 与业务组件 `variant="phone"` 对齐，由宿主显式传入 RecordBoard。
+ */
+type RecordBoardLayoutVariant = 'default' | 'phone';
 /**
  * 列字段类型：对应 Pisell 表单组件，传入列 type 时用该组件自动渲染列（只读）与筛选项（编辑）
  */
@@ -115,8 +121,8 @@ interface RecordBoardPaginationState {
   pageNumber: number;
   pageSize: number;
 }
-/** ShellFrame 内容区：表格、平面图或日历（与 GridLayout 同级切换） */
-type RecordBoardBodyView = 'grid' | 'floorMap' | 'calendar';
+/** ShellFrame 内容区：表格、平面图、日历或大屏资源墙（与 GridLayout 同级切换） */
+type RecordBoardBodyView = 'grid' | 'floorMap' | 'calendar' | 'resourceWall';
 /** 日历 Y 轴资源行（与 BookingCalendarDemo 中 court 对齐） */
 interface RecordBoardCalendarResource {
   id: string;
@@ -143,9 +149,180 @@ interface RecordBoardCalendarBookingLike {
   blockedAt?: string;
   raw?: Record<string, unknown>;
 }
+/** 日视图时间轴上的一条预约 overlay（与 BookingCalendarDemo 内部结构对齐） */
+interface RecordBoardCalendarDayOverlayBooking {
+  item: RecordBoardCalendarBookingLike;
+  courtId: string;
+  start: number;
+  end: number;
+  span: number;
+  rowTop: number;
+  rowHeight: number;
+  rowIndex: number;
+  lane?: number;
+  laneCount?: number;
+  continuesNext?: boolean;
+  continuesPrev?: boolean;
+}
+/** 表头时间分组合并（声明式）；与 {@link RecordBoardCalendarProps.renderTimelineHeader} 二选一优先用 render */
+interface RecordBoardCalendarTimelineHeaderGroup {
+  /** 含 0，对应 `hourSlots` 下标 */
+  startSlotIndex: number;
+  /** 含，须 ≥ startSlotIndex */
+  endSlotIndex: number;
+  label: ReactNode;
+}
+/** 自定义时间列表头时注入的上下文 */
+interface RecordBoardCalendarTimelineHeaderRenderContext {
+  anchorDate: Date;
+  /** 各列左边界钟点（相对锚日 0 点的浮点小时，与现 hourSlots 一致） */
+  hourSlots: number[];
+  slotStepMinutes: number;
+  /** 单列像素宽：与历史日视图整点列宽一致（每槽一列，细粒度时列数变多、横向滚动） */
+  slotColWidthPx: number;
+  isLight: boolean;
+  firstTimelineHour: number;
+  endTimelineExclusive: number;
+  isBusinessHour: (hour: number) => boolean;
+  formatHourLabel: (hour: number) => string;
+  /** 与 `hourSlots[i]` 一致 */
+  getSlotStartHour: (slotIndex: number) => number;
+  slotCount: number;
+  /** 每槽「空闲场地数 / 总场地」等，键为槽起点钟点 */
+  dayHourRemaining: Record<number, {
+    remaining: number;
+    total: number;
+    ratio: number;
+  }>;
+}
+/** 自定义左侧资源格 */
+interface RecordBoardCalendarResourceRenderArgs {
+  view: 'resource' | 'day' | 'week' | 'month';
+  row: {
+    kind: 'court' | 'group';
+    id: string;
+    name?: string;
+    label?: string;
+    count?: number;
+    collapsed?: boolean;
+    type?: string;
+  };
+  isLight: boolean;
+  /** 分组行折叠切换（仅 group 行有意义） */
+  onToggleGroup?: (groupLabel: string) => void;
+}
+/** 自定义日视图中间预约条外层容器内层（定位仍由日历负责） */
+interface RecordBoardCalendarBookingRenderArgs {
+  booking: RecordBoardCalendarDayOverlayBooking;
+  dayKey: string;
+  calendarView: 'resource' | 'day' | 'week' | 'month';
+  isLight: boolean;
+  /** 日视图时间轴上该预约条当前绘制宽度（像素），便于窄条用 Tooltip / minWidth 等策略展示信息 */
+  overlayWidthPx: number;
+  onOpenDetail: (item: RecordBoardCalendarBookingLike) => void;
+  onDragStart: (item: RecordBoardCalendarBookingLike) => void;
+  onJumpNext: () => void;
+}
+/**
+ * 月 / 周格内单条预约插槽参数。
+ * 未使用 {@link RecordBoardCalendarProps.renderMonthWeekBooking} 时，月 / 周格仅默认 booking（紫）/ block（红），不展示状态徽标与按状态的底色。
+ */
+interface RecordBoardCalendarGridBookingRenderArgs {
+  item: RecordBoardCalendarBookingLike;
+  dateKey: string;
+  view: 'month' | 'week' | 'resource';
+  isLight: boolean;
+  /**
+   * 日历建议的外层样式（圆角、内边距、默认 booking/block 底色），可与自定义 `className` 拼接。
+   * 宿主若完全自定义外观，可忽略本字段。
+   */
+  layoutClassName: string;
+  onOpenDetail: (item: RecordBoardCalendarBookingLike) => void;
+  /** 开始拖拽（月视图内置会处理 `draggable`；周格当前未挂 draggable，可自行在插槽内处理） */
+  onDragStart?: (item: RecordBoardCalendarBookingLike) => void;
+  draggable: boolean;
+}
+/** 拖拽改期的投放目标（与日历内部确认态 moveDraft 字段一致）。 */
+interface RecordBoardBookingMoveDraft {
+  targetCourtId: string;
+  /** `YYYY-MM-DD` */
+  targetDate: string;
+  /** 与日历 `hourSlots` 一致的浮点起点小时（可含半格如 9.5） */
+  targetHour: number;
+}
+/**
+ * 对接 `POST /shop/schedule/blocked-time` 的请求体（与后台字段一致）。
+ */
+interface RecordBoardCalendarBlockedTimePayload {
+  name: string;
+  note?: string;
+  resource_ids: number[];
+  blocked_sales_channels: string[];
+  /** `YYYY-MM-DD HH:mm` */
+  start_time: string;
+  /** `YYYY-MM-DD HH:mm` */
+  end_time: string;
+}
+/** 日视图连续空闲槽合并后的一段（与内置锁台面版预填一致） */
+interface RecordBoardBlockedTimeMergedRange {
+  courtId: string;
+  /** `YYYY-MM-DD` */
+  date: string;
+  /** 与时间轴一致的浮点小时 */
+  startHour: number;
+  endHour: number;
+}
+/** 日视图多选的空闲格 */
+interface RecordBoardCalendarSelectedFreeSlot {
+  courtId: string;
+  date: string;
+  hour: number;
+  court?: string;
+}
+/**
+ * 日视图「从选区新建」：与 {@link groupSelectedSlots} 合并后的一段一致（单 court、单日、连续小时）。
+ */
+interface RecordBoardCreateBookingDayGroup {
+  courtId: string;
+  /** `YYYY-MM-DD` */
+  date: string;
+  startHour: number;
+  endHour: number;
+}
+/**
+ * 底部栏「新建预约」传给宿主的上下文。
+ * 传入 {@link RecordBoardCalendarProps.onCreateBookingFromSelection} 后，
+ * 日历**不再**调用 {@link CalendarPersistContextValue.beforePersist} / **不再**写入本地 `bookings`
+ *（适用于 Pisell Reservation 等受控数据源场景）。
+ */
+type RecordBoardCreateBookingFromSelectionPayload = {
+  mode: 'day';
+  groups: RecordBoardCreateBookingDayGroup[];
+} | {
+  mode: 'resource';
+  courtId: string; /** 升序 `YYYY-MM-DD` */
+  dates: string[];
+  startHour: number;
+  endHour: number;
+};
+/** 宿主弹出锁台/屏蔽表单时由日历传入的上下文（替代内置锁台面版） */
+interface RecordBoardBlockedTimePanelPayload {
+  /** 槽位步长（小时），与日历内部 `slotStepHours` 一致 */
+  slotStepHours: number;
+  /** 与 {@link RecordBoardCalendarProps.slotStepMinutes} 一致 */
+  slotStepMinutes: number;
+  /** 日视图锚定日 `YYYY-MM-DD` */
+  dayKey: string;
+  selectedFreeSlots: RecordBoardCalendarSelectedFreeSlot[];
+  mergedRange: RecordBoardBlockedTimeMergedRange;
+}
 /** 日历视图槽位 props：由 Shell 合并根级与子槽后传入 PisellRecordBoardCalendarView */
 interface RecordBoardCalendarProps {
   persistGuard?: CalendarPersistContextValue;
+  /**
+   * 日历画布外观：亮色切换 `theme-root.theme-light`；未传或 `dark` 为深色（默认）。
+   */
+  appearance?: 'light' | 'dark';
   className?: string;
   style?: CSSProperties;
   /** 受控：画布等资源行；不传则使用内置演示数据 */
@@ -157,8 +334,18 @@ interface RecordBoardCalendarProps {
    * 点击预约条。返回 true 表示已消费（不再打开内置详情抽屉）。
    */
   onBookingClick?: (item: RecordBoardCalendarBookingLike) => boolean | void;
+  /**
+   * 拖拽预约条松手且投放合法后，由宿主接管确认与持久化（例如业务侧 booking 改约弹窗）。
+   * **传入后**日历不再弹出内置 MoveConfirmModal，也不会写入本地 bookings。
+   * 返回 `true` 表示宿主已视为完成（一般由弹窗 resolve）；`false`/`undefined`/reject 表示未生效。
+   */
+  onBookingMoveRequest?: (payload: {
+    item: RecordBoardCalendarBookingLike;
+    draft: RecordBoardBookingMoveDraft;
+  }) => Promise<boolean | void>;
   /**
    * 锚点日 / 视图变化（月、周、日），用于父级扩展 booking 请求时间窗。
+   * 宿主导出时建议对拉数做 **debounce**（如 200–300ms），与切 `bodyView`、切日等快速操作对齐，避免重复请求。
    */
   onViewportChange?: (payload: {
     view: string;
@@ -167,8 +354,8 @@ interface RecordBoardCalendarProps {
     rangeEnd: Date;
   }) => void;
   /** 当前日历粒度（与顶栏 Segmented 一致）；不传则组件内默认 `month` */
-  calendarView?: 'day' | 'week' | 'month';
-  onCalendarViewChange?: (view: 'day' | 'week' | 'month') => void;
+  calendarView?: 'resource' | 'day' | 'week' | 'month';
+  onCalendarViewChange?: (view: 'resource' | 'day' | 'week' | 'month') => void;
   /** 锚点日（通常与营业日 `schedule.date` 对齐）；不传则组件内默认日期 */
   anchorDate?: Date;
   /** 日历内交互（如跨日跳转）更新锚点时回调，由父级写回日程 */
@@ -178,11 +365,156 @@ interface RecordBoardCalendarProps {
    * 不传时日历演示默认 02:00–次日 02:00。
    */
   timelineRange?: TimeRangeOption;
+  /**
+   * 日视图时间轴列步长（分钟）。须能整除 60 或与业务约定一致；默认 **60**（与历史「整点列」一致）。
+   * Pisell Reservation 等业务可在私有包组装 props 时默认传 10。
+   */
+  slotStepMinutes?: number;
+  /**
+   * 保存「屏蔽时间」时提交（如 `/shop/schedule/blocked-time`）。
+   * 返回 `false` 表示未成功（弹窗保持）；`true` 或 `undefined` 视为成功并关闭弹窗、清空选中。
+   * 若同时传 {@link onBlockedTimePanelRequest}，内置锁台面版不再展示，本回调仅在内置路径生效。
+   */
+  onBlockedTimeSave?: (payload: RecordBoardCalendarBlockedTimePayload) => Promise<boolean | void>;
+  /**
+   * 日视图选中连续空闲槽并点「屏蔽」时，由宿主弹出锁台表单（替代内置锁台面版）。
+   * **传入后**不再渲染内置屏蔽弹层；未传时仍使用内置表单 + {@link onBlockedTimeSave}。
+   */
+  onBlockedTimePanelRequest?: (payload: RecordBoardBlockedTimePanelPayload) => Promise<boolean | void>;
+  /**
+   * 日视图 / 资源视图：选中合法连续区间并点「新建预约」时由宿主接管（打开新建弹窗、跳转路由等）。
+   * **传入后**日历跳过内置本地写入与 {@link persistGuard} 拦截。
+   * 返回 `false` 表示未消费，选中态保留；其余视为成功并清空选区。
+   */
+  onCreateBookingFromSelection?: (payload: RecordBoardCreateBookingFromSelectionPayload) => boolean | void | Promise<boolean | void>;
+  /** 与接口 `blocked_sales_channels` 一致；默认 `['online_store']` */
+  blockedTimeSalesChannels?: string[];
+  /**
+   * 完全自定义日视图时间列表头（不含左上角日期角格）。未传时按槽渲染默认表头；
+   * 若同时传 {@link timelineHeaderGroups}，则先渲染分组行再渲染默认/本插槽由实现约定：当前实现为先分组行再默认槽行。
+   */
+  renderTimelineHeader?: (ctx: RecordBoardCalendarTimelineHeaderRenderContext) => ReactNode;
+  /**
+   * 在时间槽行上方增加一行合并表头（列宽与槽位对齐）。
+   * 若同时传 {@link renderTimelineHeader}，则仅渲染插槽，**忽略**本字段。
+   */
+  timelineHeaderGroups?: RecordBoardCalendarTimelineHeaderGroup[];
+  /**
+   * 自定义日视图时间轴上的预约条内容（仅日视图 overlay 生效；月 / 周见 {@link renderMonthWeekBooking}）。
+   */
+  renderBooking?: (args: RecordBoardCalendarBookingRenderArgs) => ReactNode;
+  /**
+   * 自定义月 / 周格内单条预约。未传时仅默认 booking / block 样式与名称、时间，不展示迟到/取消等状态徽标与状态变色。
+   */
+  renderMonthWeekBooking?: (args: RecordBoardCalendarGridBookingRenderArgs) => ReactNode;
+  /** 自定义周/日视图左侧资源列单元 */
+  renderResourceCell?: (args: RecordBoardCalendarResourceRenderArgs) => ReactNode;
 }
 /**
  * 平面图槽位 props：与 PisellFloorMapLayout 对齐；items/renderItem 可省略（由 RecordBoard 默认 [] / () => null）。
  */
 type RecordBoardFloorMapProps = Partial<PisellFloorMapLayoutProps>;
+/** 大屏资源墙单卡数据（与画布资源 id 对齐，见 {@link resourceId}） */
+interface RecordBoardResourceWallCardModel {
+  /** 与日历/画布 `form_record` id 一致 */
+  resourceId: string;
+  resource: string;
+  /** 资源类型等次级标签（如表单 `form_code`）；大屏卡左上角展示于资源名上方 */
+  area?: string;
+  /**
+   * 资源墙展示态：由业务兼容层（如预约页）基于 booking.status + now + start/end 计算。
+   * materials 侧仅按该字段渲染，不再做 light/时间窗口推断。
+   */
+  status?: 'available' | 'inUse' | 'boardingSoon' | 'late' | 'endingSoon' | 'expired';
+  currentTime?: string;
+  currentBooking?: string;
+  /** boardingSoon：距离开始分钟；inUse/endingSoon/expired：距离结束分钟 */
+  startsInMin?: number;
+  /** late：已超过开始时间但仍未占用（分钟，递增） */
+  lateMin?: number;
+  remainingMin?: number;
+  /**
+   * 占用态当前场次 Unix 毫秒时间戳（宿主可用 booking start/end 回填）。
+   * 大屏进度条优先用其与墙钟差值连续更新；缺省时退回「剩余分钟漂移 / 60」。
+   */
+  sessionStartMs?: number;
+  sessionEndMs?: number;
+  nextList?: Array<{
+    time: string;
+    booking: string;
+    startInMin: number;
+  }>;
+  /**
+   * 当前区展示的是「尚未开始」的预约时：主面板小标题用「下一预约」文案，且不再单独渲染下方 Next 条带。
+   */
+  wallUseNextLabelHideNextRow?: boolean;
+  /**
+   * @deprecated light 相关状态已弃用（2026-04）：资源墙仅保留 5 态，不再渲染 light 文案。
+   * 旧字段暂保留以兼容历史数据源，但不会再被 materials 使用。
+   */
+  lightState?: 'off' | 'off_soon_on' | 'on_soon_off';
+  /** @deprecated */
+  lightOnInMin?: number;
+  /** @deprecated */
+  lightOffInMin?: number;
+}
+/**
+ * 控制台「Resource & Layout」中与版式/轮播相关的可持久化字段（不含资源多选，其走 filter；不含配色，其走 appearanceTheme）。
+ */
+interface RecordBoardResourceWallLayoutPersist {
+  layoutKey: string;
+  customCols: number;
+  customRows: number;
+  pageDurationSec: number;
+  boardingSoonBeforeMin: number;
+  heroMaxWidthRatio: number;
+}
+/** {@link RecordBoardResourceWallLayoutPersist} 默认值，与 {@link PisellRecordBoardResourceWallView} 历史初始 state 一致 */
+declare const DEFAULT_RESOURCE_WALL_LAYOUT_PERSIST: RecordBoardResourceWallLayoutPersist;
+/**
+ * 大屏资源墙视图 props；与 Shell 内 `PisellRecordBoard.ResourceWall` 合并（子优先）。
+ * 展示顺序默认由 `searchParams.filter.values[filterFieldKey]`（默认 `resource_wall_resource_ids`）非空 `string[]` 决定；
+ * **未写该键、值非数组、或 `[]`**：不展示卡片。**仅渲染 `cards` 中能按 `resourceId` 命中的项**；
+ * 命中不到的 id（例如磁盘残留的旧店铺 / 已删资源）直接剔除、不再回退成「数字占位卡」，磁盘清洗由宿主负责。
+ * 当 `searchParams.sort` 的字段名与 {@link RecordBoardResourceWallProps.statusSortFieldKeys} 匹配（默认 `status`）时，
+ * 在筛选顺序基础上按卡占用态重排：升序空闲在前，降序占用（inUse/将结/已结束）在前。
+ */
+interface RecordBoardResourceWallProps {
+  className?: string;
+  style?: CSSProperties;
+  /** 全量卡片；展示时按快筛字段过滤 */
+  cards?: RecordBoardResourceWallCardModel[];
+  loading?: boolean;
+  /**
+   * 与 ToolBar 快筛里多选字段的 `name`/`key` 一致，用于从 context.searchParams.filter.values 读取 string[]。
+   * @default 'resource_wall_resource_ids'
+   */
+  filterFieldKey?: string;
+  /**
+   * 与 ToolBar `searchParams.sort` 首段字段名比对（忽略大小写）；命中时资源墙按卡状态重排。
+   * 列 key 不是 `status` 时传入实际字段名，例如 `['courtStatus']`。
+   * @default ['status']
+   */
+  statusSortFieldKeys?: string[];
+  /** 六态文案/配色覆盖（与默认 map 浅合并）；通常由宿主从 localStorage 水合 */
+  statusToneOverrides?: VenueWallStatusToneOverrides;
+  /** 覆盖变更时回调，宿主可写入 localStorage */
+  onStatusToneOverridesChange?: (next: VenueWallStatusToneOverrides) => void;
+  /**
+   * 浅 / 深外观各自的卡面主色与六态覆盖；与 {@link onAppearanceThemeChange} 配合由宿主持久化。
+   * 未传入时由视图内部维护（刷新丢失）。
+   */
+  appearanceTheme?: VenueWallAppearanceTheme;
+  onAppearanceThemeChange?: (next: VenueWallAppearanceTheme) => void;
+  /** 当前大屏外观：浅色 / 深色；与 {@link onAppearanceModeChange} 一并由宿主导入 localStorage */
+  appearanceMode?: 'light' | 'dark';
+  onAppearanceModeChange?: (mode: 'light' | 'dark') => void;
+  /**
+   * 版式与轮播等；与 {@link onResourceWallLayoutChange} 由宿主导入 localStorage（预约页）。
+   */
+  resourceWallLayout?: Partial<RecordBoardResourceWallLayoutPersist>;
+  onResourceWallLayoutChange?: (next: RecordBoardResourceWallLayoutPersist) => void;
+}
 /**
  * RecordBoard 容器 Context 值
  * 与具体 layout 类型无关，所有 layout 共用同一套数据与操作
@@ -215,6 +547,11 @@ interface RecordBoardContextValue {
   onReset?: () => void;
   /** 当前布局类型，供子组件按需做差异化 */
   layoutType: RecordBoardLayoutType;
+  /**
+   * 表格/工具栏手机紧凑布局；`phone` 时 Grid 应用列宽缩放与 `--phone` 样式。
+   * @default 'default'
+   */
+  layoutVariant?: RecordBoardLayoutVariant;
   /** 多选：当前选中的 key 列表 */
   selectedKeys: Key[];
   /** 多选：当前选中的行数据 */
@@ -236,6 +573,15 @@ interface RecordBoardContextValue {
   onColumnOrderChange?: (columnKeys: string[]) => void;
   /** 各子组件透传 props，由 Provider 注入 */
   childComponentProps?: RecordBoardChildComponentProps;
+  /**
+   * 业务方完全自定义的分页渲染（从根 props 透传过来）。
+   * `<RecordBoardPagination />` 优先级：组件 `render` prop > 此 ctx 字段 > 默认 materials Pagination。
+   */
+  paginationRender?: (ctx: RecordBoardContextValue) => React.ReactNode;
+  /**
+   * 与 `grid.infiniteScroll` 同步：为 true 时不渲染 ShellFrame 底部分页，由 Grid 表体触底触发翻页。
+   */
+  gridInfiniteScroll?: boolean;
   /** 是否占满父容器高度，供 ShellFrame 做弹性布局（内容区纯 CSS 滚动 + 表头 sticky；scroll.autoCalc 时用测量高度） */
   fillHeight?: boolean;
   /** 内容区滚动容器高度（fillHeight 且 grid.scroll.autoCalc 时由 ShellFrame 测量），供 Grid 计算 scroll.y */
@@ -268,6 +614,8 @@ interface RecordBoardContextValue {
   floorMapFooter?: ReactNode;
   /** 根级传入的日历视图 props（可选）；与 ShellFrame 内 Calendar 子组件合并，子优先 */
   calendarProps?: RecordBoardCalendarProps;
+  /** 根级传入的大屏资源墙 props（可选）；与 ShellFrame 内 ResourceWall 子组件合并，子优先 */
+  resourceWallProps?: RecordBoardResourceWallProps;
 }
 /**
  * 各 layout 下子组件的可选透传配置（类似 ChildComponentProps）
@@ -288,9 +636,13 @@ type RecordBoardFilterProps = Record<string, any>;
 interface RecordBoardToolBarProps {
   /**
    * `compact`：Find / 快筛 / 排序筛选 / 重置 / 视图切换等统一小号，用于窄容器（如 HUD 内嵌表）。
+   * `compact-narrow`：极窄容器（如 HUD 抽屉）下的进一步压缩 ──
+   *   - Find 退化为图标触发器（弹搜索 Modal/Drawer），不再常驻 input
+   *   - 列显示 / 排序 / 筛选合并到一个齿轮按钮的 Popover 内
+   *   - Reset 仍单独保留（快捷高频动作）
    * @default 'default'
    */
-  toolbarDensity?: 'default' | 'compact';
+  toolbarDensity?: 'default' | 'compact' | 'compact-narrow';
   className?: string;
   style?: React.CSSProperties;
   tabs?: React.ReactNode;
@@ -302,7 +654,11 @@ interface RecordBoardToolBarProps {
   search?: boolean | RecordBoardSearchProps;
   /** 在 ToolBar 右侧渲染筛选：默认 PisellFilter；对象透传 PisellFilter props；false 不渲染。值存于 searchParams.filter */
   filter?: boolean | RecordBoardFilterProps;
-  /** 在 ToolBar 内、筛选左侧渲染排序：默认 Sort；对象可传 list、placement 等；false 不渲染。值存于 searchParams.sort */
+  /**
+   * 在 ToolBar 内、筛选左侧渲染排序：默认 Sort；对象可传 list、placement 等；false 不渲染。值存于 searchParams.sort。
+   * 资源墙视图：排序**菜单内**仅保留「状态」相关项（其余排序仅在表格等视图出现）；若无状态列派生项，会注入「空闲优先 / 占用优先」子项。
+   * 可传 `resourceWallSortFieldKeys: string[]` 与非 `status` 列 key 对齐。表格/平面图/日历仍使用完整排序列表。
+   */
   sort?: boolean | Record<string, any>;
   /**
    * 在 ToolBar 左侧展示内联快速筛选（替代 Filter 弹层内的 quickFilter）。
@@ -313,6 +669,17 @@ interface RecordBoardToolBarProps {
   quickFilter?: boolean | Record<string, any>;
   /** 列显示隐藏设置入口；默认 true（有 grid.columns 时显示）；false 时不渲染 */
   columnSetting?: boolean;
+  /**
+   * 为 true 时不渲染顶栏 Segmented 视图切换（业务在 topLeft / tabs 内自绘切换器时使用，如手机 Table 下拉）。
+   * @default false
+   */
+  hideBodyViewToggle?: boolean;
+  /**
+   * 仅 `toolbarDensity: 'compact-narrow'` 且存在左侧内联快筛时生效：
+   * 将搜索图标 + 齿轮与快筛同置于一行 `flex-wrap` 容器，尾部 `margin-inline-start: auto`，
+   * 以便快筛按钮换行后图标组与**最后一行**快筛右缘对齐（HUD 抽屉等极窄场景）。
+   */
+  mergeCompactNarrowTrailingWithQuickFilterRow?: boolean;
 }
 /** Search 透传配置，与 PisellFind 的 props 对齐 */
 type RecordBoardSearchProps = Record<string, any>;
@@ -341,7 +708,25 @@ type RecordBoardGridProps = {
     y?: number | string;
     autoCalc?: boolean;
     scrollToFirstRowOnChange?: boolean;
-  }; /** 表格尺寸 */
+  };
+  /**
+   * 为 true 时：表体滚动触底触发 `onPageChange` 加载下一页，ShellFrame **不展示**底部分页条。
+   * 宿主需保证 `data` 为已加载的**累积**行（或 dataSources 模式由容器做累积切片），且 `total` 为总量；触底停更条件为 `data.length < total`。
+   */
+  infiniteScroll?: boolean;
+  /**
+   * 仅 `layoutVariant="phone"` 时生效：列 key → 最大宽度（px）。
+   */
+  phoneColumnWidthCaps?: Record<string, number>;
+  /**
+   * 仅 `layoutVariant="phone"` 时生效：列 key → 相对原 width 的缩放比例；未配置列使用 phoneColumnWidthRatio。
+   */
+  phoneColumnWidthRatioByKey?: Record<string, number>;
+  /**
+   * 仅 `layoutVariant="phone"` 时生效：默认列宽缩放比例。
+   * @default 5/6
+   */
+  phoneColumnWidthRatio?: number; /** 表格尺寸 */
   size?: 'small' | 'middle' | 'default'; /** 当前选中的行 key 列表（多选） */
   selectedKeys?: Key[]; /** 当前选中的行数据（多选） */
   selectedRows?: unknown[]; /** 多选变更回调 */
@@ -407,10 +792,25 @@ interface RecordBoardProps {
   search?: RecordBoardSearchProps;
   /** 分页组件透传配置（与 pagination 状态区分，此处为 Pagination 组件 props） */
   paginationConfig?: Record<string, any>;
+  /**
+   * 完全自定义分页渲染：传入则 ShellFrame 内置的 `<RecordBoardPagination />` 用此函数替换默认渲染。
+   *
+   * 适用场景：业务方需要在窄容器（如 hud 抽屉）里不要 materials Pagination
+   * 那套 50px 高、Previous/Next 大按钮、灰底边框容器，直接用 antd 原生 small Pagination
+   * 或其它紧凑实现。比 `paginationConfig` 更彻底（后者只是 props 透传，外壳样式仍在）。
+   *
+   * 入参 ctx 包含 pagination/total/onPageChange 等当前分页所需上下文。
+   */
+  paginationRender?: (ctx: RecordBoardContextValue) => React.ReactNode;
   /** 多选操作栏配置 */
   batchActionBar?: RecordBoardBatchActionBarProps;
   /** 卡片列表配置 */
   cardList?: Record<string, any>;
+  /**
+   * 列表区布局变体；传 `phone` 时由 RecordBoard Grid 统一收窄列宽与单元格 padding。
+   * @default 'default'
+   */
+  layoutVariant?: RecordBoardLayoutVariant;
   /** 是否启用分页（与 pagination 状态区分） */
   enablePagination?: boolean;
   /**
@@ -418,6 +818,11 @@ interface RecordBoardProps {
    * 推荐在 ShellFrame 内使用 PisellRecordBoard.Calendar 声明；若同时传根级与本项，Shell 内子组件 props 优先合并。
    */
   calendar?: RecordBoardCalendarProps;
+  /**
+   * 大屏资源墙（可选）：与 Shell 内 `PisellRecordBoard.ResourceWall` 对齐。
+   * 推荐在 ShellFrame 内声明子组件；若同时传根级与本项，Shell 内子组件 props 优先合并。
+   */
+  resourceWall?: RecordBoardResourceWallProps;
   /**
    * 平面图（可选，兼容低代码 / SalesGrid 等）：与 PisellFloorMapLayout 对齐。
    * 推荐在 ShellFrame 内使用 PisellRecordBoard.FloorMap 声明；若同时传根级与本项，Shell 内子组件 props 优先合并。
@@ -452,4 +857,4 @@ interface RecordBoardProps {
   [key: string]: any;
 }
 //#endregion
-export { RecordBoardBodyView, RecordBoardCalendarBookingLike, RecordBoardCalendarProps, RecordBoardCalendarResource, RecordBoardChildComponentProps, RecordBoardColumnFilterConfig, RecordBoardColumnType, RecordBoardContextValue, RecordBoardFieldType, RecordBoardFloorMapProps, RecordBoardGetOptions, RecordBoardGridProps, RecordBoardLayoutType, RecordBoardOptionItem, RecordBoardProps, RecordBoardToolBarProps };
+export { DEFAULT_RESOURCE_WALL_LAYOUT_PERSIST, RecordBoardBlockedTimeMergedRange, RecordBoardBlockedTimePanelPayload, RecordBoardBodyView, RecordBoardBookingMoveDraft, RecordBoardCalendarBlockedTimePayload, RecordBoardCalendarBookingLike, RecordBoardCalendarBookingRenderArgs, RecordBoardCalendarDayOverlayBooking, RecordBoardCalendarProps, RecordBoardCalendarResource, RecordBoardCalendarResourceRenderArgs, RecordBoardCalendarSelectedFreeSlot, RecordBoardCalendarTimelineHeaderGroup, RecordBoardCalendarTimelineHeaderRenderContext, RecordBoardChildComponentProps, RecordBoardColumnFilterConfig, RecordBoardColumnType, RecordBoardContextValue, RecordBoardCreateBookingDayGroup, RecordBoardCreateBookingFromSelectionPayload, RecordBoardFieldType, RecordBoardFloorMapProps, RecordBoardGetOptions, RecordBoardGridProps, RecordBoardLayoutType, RecordBoardLayoutVariant, RecordBoardOptionItem, RecordBoardProps, RecordBoardResourceWallCardModel, RecordBoardResourceWallLayoutPersist, RecordBoardResourceWallProps, RecordBoardToolBarProps };

package/es/components/pisellRecordBoard/types.js

@@ -0,0 +1,12 @@
+//#region src/components/pisellRecordBoard/types.ts
+/** {@link RecordBoardResourceWallLayoutPersist} 默认值，与 {@link PisellRecordBoardResourceWallView} 历史初始 state 一致 */
+const DEFAULT_RESOURCE_WALL_LAYOUT_PERSIST = {
+	layoutKey: "2x3",
+	customCols: 3,
+	customRows: 2,
+	pageDurationSec: 10,
+	boardingSoonBeforeMin: 10,
+	heroMaxWidthRatio: .6
+};
+//#endregion
+export { DEFAULT_RESOURCE_WALL_LAYOUT_PERSIST };

package/es/components/pisellRecordBoard/utils/partitionShellFrameChildren.js

@@ -1,11 +1,14 @@
 import RecordBoardFloorMap from "../shellFrame/FloorMap.js";
 import RecordBoardCalendar from "../shellFrame/Calendar/RecordBoardCalendar.js";
+import RecordBoardResourceWall from "../shellFrame/ResourceWall/RecordBoardResourceWall.js";
 import React from "react";
 //#region src/components/pisellRecordBoard/utils/partitionShellFrameChildren.tsx
 /** 与 shellFrame/FloorMap 上定义的 displayName 一致，用于从 ShellFrame children 中识别平面图槽 */
 const RECORD_BOARD_FLOOR_MAP_DISPLAY_NAME = "RecordBoard.FloorMap";
 /** 与 shellFrame/Calendar 上定义的 displayName 一致 */
 const RECORD_BOARD_CALENDAR_DISPLAY_NAME = "RecordBoard.Calendar";
+/** 与 shellFrame/ResourceWall 上定义的 displayName 一致 */
+const RECORD_BOARD_RESOURCE_WALL_DISPLAY_NAME = "RecordBoard.ResourceWall";
 /** displayName 在部分构建下可能被摇掉；与 RecordBoardFloorMap 引用一致时仍可识别 */
 function isRecordBoardFloorMapElementType(type) {
 	if (type === RecordBoardFloorMap) return true;
@@ -15,6 +18,10 @@ function isRecordBoardCalendarElementType(type) {
 	if (type === RecordBoardCalendar) return true;
 	return (type === null || type === void 0 ? void 0 : type.displayName) === RECORD_BOARD_CALENDAR_DISPLAY_NAME;
 }
+function isRecordBoardResourceWallElementType(type) {
+	if (type === RecordBoardResourceWall) return true;
+	return (type === null || type === void 0 ? void 0 : type.displayName) === RECORD_BOARD_RESOURCE_WALL_DISPLAY_NAME;
+}
 /**
 * 将 ShellFrame 的 children 拆成：供表格区渲染的子树 + 可选的 FloorMap / Calendar 透传 props。
 * 支持 Fragment 嵌套；多个同槽时以最后一个为准。
@@ -24,6 +31,8 @@ function partitionShellFrameChildren(children) {
 	let floorProps;
 	let foundCalendar = false;
 	let calendarProps;
+	let foundResourceWall = false;
+	let resourceWallProps;
 	const gridChunks = [];
 	const walk = (node) => {
 		React.Children.forEach(node, (child) => {
@@ -46,6 +55,11 @@ function partitionShellFrameChildren(children) {
 				calendarProps = child.props;
 				return;
 			}
+			if (isRecordBoardResourceWallElementType(child.type)) {
+				foundResourceWall = true;
+				resourceWallProps = child.props;
+				return;
+			}
 			gridChunks.push(child);
 		});
 	};
@@ -61,6 +75,8 @@ function partitionShellFrameChildren(children) {
 		floorMapPropsFromChild: floorProps,
 		hasCalendarChild: foundCalendar,
 		calendarPropsFromChild: calendarProps,
+		hasResourceWallChild: foundResourceWall,
+		resourceWallPropsFromChild: resourceWallProps,
 		hasGridContent
 	};
 }

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

@@ -0,0 +1,22 @@
+import { RecordBoardColumnType } from "../types.js";
+
+//#region src/components/pisellRecordBoard/utils/recordBoardPhoneGrid.d.ts
+/** Grid 根节点在 `layoutVariant="phone"` 时追加的 class，用于收紧单元格 padding 等 */
+declare const RECORD_BOARD_PHONE_GRID_CLASS = "pisell-record-board-grid--phone";
+interface AdaptColumnsForPhoneLayoutOptions {
+  /** 列 key → 最大宽度（px），在比例缩放后再取 min */
+  widthCapsByKey?: Record<string, number>;
+  /** 列 key → 宽度缩放比例（相对原 width）；未配置则用 defaultWidthRatio */
+  widthRatioByKey?: Record<string, number>;
+  /** 默认 numeric width 缩放比例 @default 5/6 */
+  defaultWidthRatio?: number;
+  /** 是否去掉 fixed 列（手机横向滚动场景） @default true */
+  unsetFixed?: boolean;
+}
+/**
+ * 手机 Table：收窄列宽并去掉 fixed，供 RecordBoard Grid 在 layoutVariant=phone 时统一调用。
+ * 业务可通过 grid.phoneColumnWidthCaps / phoneColumnWidthRatioByKey 覆盖特定列。
+ */
+declare function adaptColumnsForPhoneLayout(columns: RecordBoardColumnType[], options?: AdaptColumnsForPhoneLayoutOptions): RecordBoardColumnType[];
+//#endregion
+export { AdaptColumnsForPhoneLayoutOptions, RECORD_BOARD_PHONE_GRID_CLASS, adaptColumnsForPhoneLayout };