@pisell/materials 6.11.223 → 6.11.225

package/lib/components/pisellRecordBoard/shellFrame/Calendar/bookingCalendarViewShared.d.ts

@@ -0,0 +1,34 @@
+/// <reference types="react" />
+/** UI 层：状态徽标文案走 i18n（utils 侧为 {@link statusTagMetaParts}） */
+export declare function statusTagMeta(tag: string | null | undefined): {
+    label: string;
+    className: string;
+} | null;
+/** 锁台卡片副标题：操作人、锁台时间等拼接一行 */
+export declare function getBlockMetaLine(item: any): string;
+export declare function getRemainingToneClass(ratio: any, isLight?: boolean): "theme-text-muted" | "text-zinc-400" | "text-red-600" | "text-red-300" | "text-amber-600" | "text-amber-300";
+/**
+ * @param options.flattenWhenAllGroupsCollapsed
+ *   若为 `true`：全部分组折叠时仅有 group 头、无 court 行，会退化为平铺 court（易与「全部展开」混淆）。
+ *   日/周/月日历统一为默认 `false`，保留分组头行与折叠态（与底部「全部关闭」预期一致）。
+ *
+ * 若全部资源只属于**一个**分组（含仅 VIP、仅 Standard、或仅一种自定义 type），日/周视图不展示分组头行，
+ * 直接平铺资源行（单组折叠时也同样平铺资源，避免只剩一条分组栏）。
+ */
+export declare function buildGroupedCourtRows(courts: any, collapsedGroups?: {}, options?: {}): any;
+/** 周/月/资源跨窗口 pill 左右续画标记（◀/▶）；自定义 `renderMonthWeekBooking` 时由格容器包裹渲染 */
+export declare function CalendarGridBookingClipMarkers({ clippedLeft, clippedRight, size, }: {
+    clippedLeft?: boolean;
+    clippedRight?: boolean;
+    /** `xs` 月视图 banner；`sm` 周/资源 pill */
+    size?: 'xs' | 'sm';
+}): JSX.Element;
+/** 日视图 overlay 内单条预约/锁台：窄宽自适应与 Tooltip */
+export declare function BookingCard({ booking, dayKey, onOpenDetail, onDragStart, onJumpNext, overlayWidthPx, }: {
+    booking: any;
+    dayKey: any;
+    onOpenDetail: any;
+    onDragStart: any;
+    onJumpNext: any;
+    overlayWidthPx: any;
+}): any;

package/lib/components/pisellRecordBoard/shellFrame/Calendar/calendarI18n.d.ts

@@ -0,0 +1,4 @@
+/** 日历视图文案：占位符 `{name}`、`{date}` 等由调用方替换 */
+export declare function tCal(id: string, vars?: Record<string, string | number>): string;
+/** 月/周表头：周一为 0（与 rangeDays / startOfWeek 一致） */
+export declare const CALENDAR_WEEKDAY_IDS: readonly ["pisell2.recordBoard.calendar.weekday.mon", "pisell2.recordBoard.calendar.weekday.tue", "pisell2.recordBoard.calendar.weekday.wed", "pisell2.recordBoard.calendar.weekday.thu", "pisell2.recordBoard.calendar.weekday.fri", "pisell2.recordBoard.calendar.weekday.sat", "pisell2.recordBoard.calendar.weekday.sun"];

package/lib/components/pisellRecordBoard/shellFrame/Calendar/calendarPersistGuard.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+/** 日历内会改本地预约数据的动作类型，供业务层拦截（如平面图未支持写接口时 toast） */
+export declare type CalendarPersistKind = 'moveBooking' | 'createBooking' | 'removeBlocks' | 'createBlock' | 'checkin' | 'checkinReschedule' | 'mergeOrder' | 'other';
+export interface CalendarPersistContextValue {
+    /**
+     * 返回 false 时日历组件应取消本次本地数据变更（由调用方决定是否已 toast）。
+     * 未提供时默认允许所有本地变更（Story / 独立演示）。
+     */
+    beforePersist?: (kind: CalendarPersistKind) => boolean;
+}
+export declare const CalendarPersistProvider: React.FC<{
+    children: React.ReactNode;
+    value?: CalendarPersistContextValue;
+}>;
+/**
+ * 在日历 Demo 内判断某类写操作是否允许执行本地 state 更新。
+ */
+export declare function useCalendarPersist(): (kind: CalendarPersistKind) => boolean;

package/lib/components/pisellRecordBoard/shellFrame/Calendar/const/bookingCalendarConstants.d.ts

@@ -0,0 +1,102 @@
+/** BookingCalendarDemo：布局数值与虚拟列表高度等（无演示种子数据）。 */
+export declare const timeSliceMinutes = 60;
+/** 未传 timelineRange 时默认营业日界钟 */
+export declare const DEFAULT_CALENDAR_TIMELINE: {
+    start: string;
+    end: string;
+};
+export declare const frozenColWidth = 132;
+export declare const dayColWidth = 92;
+/**
+ * 日历「资源视图」横向每一「日」列宽度（按月天数铺开）。
+ * 略大于 {@link dayColWidth}，仅作用于资源视图；日视图时间轴仍用 dayColWidth。
+ */
+export declare const resourceViewDayColWidth = 102;
+/**
+ * 日/周视图空档虚线框：在父级为 column flex 且占满格高时 `flex-1 min-h-0` 纵向铺满剩余区域。
+ */
+export declare const CALENDAR_EMPTY_DASHED_SLOT_CLASSNAME = "flex min-h-0 flex-1 w-full flex-col items-center justify-center rounded-lg border border-dashed px-2 py-1 text-xs";
+/** 日视图无 overlay 时资源行默认高度；周视图 court 行与各日期格 `minHeight` 与之对齐 */
+export declare const dayRowHeight = 44;
+/**
+ * 资源视图月格：单条预约卡片**实际 min-height** 与「行高估算」共用此值。
+ * 调整此常量即可同步改变卡片显示高度与父行预留高度，避免行高与卡片高度不一致导致的截断 / 留白。
+ */
+export declare const RESOURCE_VIEW_BOOKING_CARD_EST_PX = 48;
+/** 资源视图「+N」tile 的 min-height */
+export declare const RESOURCE_VIEW_MORE_TILE_MIN_PX = 48;
+/** 资源视图单元格 p-1 上下合计 */
+export declare const RESOURCE_VIEW_CELL_PADDING_Y_PX = 8;
+/** 资源视图 fullyBooked 占位块 min-height */
+export declare const RESOURCE_VIEW_FULLY_BOOKED_BLOCK_PX = 28;
+/**
+ * 资源视图：单 court 行最多展示的 lane 数；超出 → 该天落入 cell 级 `+N` 溢出
+ */
+export declare const RESOURCE_VIEW_MAX_LANE = 3;
+/**
+ * 周视图：单 court 行最多展示的 lane 数（含 pill）。
+ * 比资源视图小：周列宽 ≈ 1 天，行高过大会让 5/27–5/31 这种"中间天"出现大块底部空白
+ * （短跨日 pill 只占 5/25–5/26 的 lane 2，但行高被全周 max 撑到 3 lane）。
+ * 这里取 2 → 长跨日两条占顶 lane 0/1，短跨日和单日全部进 cell 级 +N tile，行高紧凑。
+ */
+export declare const WEEK_VIEW_MAX_LANE = 2;
+/** 月视图：每周内最多展示的 lane 数；超出 → cell 级 `+N` 溢出（M1：跨自然周续画时端部加 ◀/▶） */
+export declare const MONTH_VIEW_MAX_LANE = 3;
+/** 月视图 banner 高度（细于周视图 pill，节省每个 cell 的垂直空间） */
+export declare const MONTH_VIEW_BANNER_H = 22;
+/** 月视图 banner 之间纵向间距 */
+export declare const MONTH_VIEW_BANNER_GAP = 2;
+/** 月视图 banner 区域顶部留白（cell header 已留 padding，这里只补 banner 自身上边距） */
+export declare const MONTH_VIEW_BANNER_PAD_Y = 2;
+/** 月视图 cell header 估算高度：日期数字 + 占用 dot，banner 起点的 top 偏移 */
+export declare const MONTH_VIEW_DAY_HEADER_H = 52;
+/** 月视图 +N tile 高度（与 banner 一致以对齐 lane 槽） */
+export declare const MONTH_VIEW_MORE_TILE_PX = 22;
+/** 月视图：给定可见 lane 数与是否有 +N，banner 区所需高度（px） */
+export declare function monthWeekBannerContentHeightPx(visibleLanes: number, hasOverflow: boolean): number;
+/**
+ * 月视图：在固定行高、不可滚动的前提下，根据 banner 区可用高度推算本行最多展示几条。
+ * 超出部分走 cell 级 +N，避免底部 banner 被裁切却看不到 +N。
+ */
+export declare function monthViewEffectiveMaxLanes(bannerZoneHeightPx: number, totalLaneCount: number): number;
+/** 日视图分组行默认高度（须容纳左侧折叠按钮等） */
+export declare const groupRowHeight = 38;
+export declare const dayHeaderHeight = 56;
+/** 日视图 overlay 内单条预约卡片区最小高度（与 BookingCard、行高计算一致） */
+export declare const DAY_BOOKING_CARD_MIN_PX = 64;
+/** 日视图同一资源行内每条 lane 的最小高度（须 ≥ DAY_BOOKING_CARD_MIN_PX）；并行时抬高该行 */
+export declare const DAY_OVERLAY_LANE_MIN_PX = 64;
+export declare const DAY_OVERLAY_INNER_TOP = 8;
+export declare const DAY_OVERLAY_INNER_BOTTOM = 8;
+export declare const DAY_OVERLAY_LANE_GAP = 2;
+/** 同一重叠簇内最多展示的预约条数；超出合并为第 4 行的 +N（与日/周时间轴 overlay 一致） */
+export declare const DAY_OVERLAY_VISIBLE_BOOKING_CAP = 3;
+/**
+ * 日视图：某 court 行在「有预约 overlay」时的总高度（px），随并行展示条数 `displayLaneCount` 变高而变高（非固定常数）。
+ * `displayLaneCount` 由 `effectiveDayOverlayDisplayLaneCount(最大并行数)` 得到，与 3+N 截断规则一致。
+ */
+export declare function dayCourtOverlayRowHeightPx(displayLaneCount: number): number;
+/**
+ * 资源视图：按某一格「courtDaySummary」结果估算该格所需最小高度（px）。
+ * 用于横向虚拟化仅挂载可见日期列时，仍按**全月**最大内容撑开行高，避免日程只在屏幕外列时出现行高塌陷。
+ */
+export declare function estimateResourceViewCourtCellHeightPx(summary: {
+    fullyBooked: boolean;
+    items: unknown[];
+}): number;
+/** 低于该宽度时日视图预约条内难以排下两行文案，默认用 Tooltip 展示完整信息 */
+export declare const DAY_BOOKING_NARROW_PX = 88;
+/** 低于该宽度时条内仅保留居中首字/圆点，避免文字竖排或完全不可读 */
+export declare const DAY_BOOKING_MICRO_PX = 32;
+/** 日视图横向：视口外多渲染的槽列数（减轻快速滚动白边） */
+export declare const DAY_VIEW_COL_BUFFER = 5;
+/** 日视图纵向：视口外多渲染的像素边距 */
+export declare const DAY_VIEW_ROW_BUFFER_PX = 240;
+/** 月/周/资源 +N 弹层内置列表行内容区高度（名称 + 时间） */
+export declare const OVERFLOW_MODAL_SIMPLE_CARD_H = 56;
+/** 日视图 lane +N：RoomCard 单行内容区高度（略大于格内条 min，可裁切次要信息） */
+export declare const OVERFLOW_MODAL_DAY_CARD_H = 80;
+export declare const OVERFLOW_MODAL_ROW_GAP = 8;
+export declare const OVERFLOW_MODAL_SIMPLE_ROW_H: number;
+export declare const OVERFLOW_MODAL_DAY_ROW_H: number;
+export declare const OVERFLOW_MODAL_LIST_MAX_H = 420;

package/lib/components/pisellRecordBoard/shellFrame/Calendar/hooks/useBookingCalendarDayOverlayLayout.d.ts

@@ -0,0 +1,18 @@
+import { type CalendarBookingSegmentInput } from '../utils/bookingCalendarDateUtils';
+export declare function useBookingCalendarDayOverlayLayout(visibleCourtRows: unknown[], dayKey: string, bookings: CalendarBookingSegmentInput[], hourSlots: number[], slotStepHours: number): {
+    dayRowHeights: number[];
+    dayRowTopMap: Record<string, number>;
+    overlayBookings: import("../utils/bookingCalendarDateUtils").BuiltDayOverlay[];
+    courtDayDisplayLaneCount: Record<string, number>;
+    hiddenDayOverlayIdSet: Set<string>;
+    dayOverlayOverflowPluses: {
+        key: string;
+        courtId: string;
+        rowTop: number;
+        rowHeight: number;
+        start: number;
+        span: number;
+        plusCount: number;
+        overflowItems: CalendarBookingSegmentInput[];
+    }[];
+};

package/lib/components/pisellRecordBoard/shellFrame/Calendar/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 看板日历子模块导出：持久化守卫、日历根视图、Shell 槽位占位组件。
+ */
+export { CalendarPersistProvider, useCalendarPersist, } from './calendarPersistGuard';
+export type { CalendarPersistContextValue, CalendarPersistKind, } from './calendarPersistGuard';
+export { PisellRecordBoardCalendarView, type PisellRecordBoardCalendarViewProps, } from './PisellRecordBoardCalendarView';
+export { default as RecordBoardCalendar } from './RecordBoardCalendar';

package/lib/components/pisellRecordBoard/shellFrame/Calendar/modal/BookingCalendarBlockPanel.d.ts

@@ -0,0 +1,26 @@
+import React from 'react';
+import type { BlockTimeRange } from '../bookingCalendarInternalTypes';
+export declare type BookingCalendarBlockPanelProps = {
+    blockPanelRef: React.RefObject<HTMLDivElement | null>;
+    isLight: boolean;
+    blockFormName: string;
+    setBlockFormName: (v: string) => void;
+    blockModalNote: string;
+    setBlockModalNote: (v: string) => void;
+    blockResourceId: string;
+    setBlockResourceId: (v: string) => void;
+    blockTimeRange: BlockTimeRange;
+    setBlockTimeRange: (v: BlockTimeRange) => void;
+    resolvedSlotMinutes: number;
+    visibleCourts: Array<{
+        id: string;
+        name: string;
+    }>;
+    blockSaving: boolean;
+    onClose: () => void;
+    onSave: () => void;
+};
+/**
+ * 内置锁台 / 屏蔽时间表单（宿主未传 `onBlockedTimePanelRequest` 时使用）。
+ */
+export declare function BookingCalendarBlockPanel({ blockPanelRef, isLight, blockFormName, setBlockFormName, blockModalNote, setBlockModalNote, blockResourceId, setBlockResourceId, blockTimeRange, setBlockTimeRange, resolvedSlotMinutes, visibleCourts, blockSaving, onClose, onSave, }: BookingCalendarBlockPanelProps): JSX.Element;

package/lib/components/pisellRecordBoard/shellFrame/Calendar/modal/BookingCalendarOverflowListLayer.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+import type { RecordBoardCalendarBookingLike, RecordBoardCalendarBookingRenderArgs } from '../../../types';
+import type { OverflowListModalState } from '../bookingCalendarInternalTypes';
+export declare type BookingCalendarOverflowListLayerProps = {
+    overflowPanelRef: React.RefObject<HTMLDivElement | null>;
+    isLight: boolean;
+    modal: OverflowListModalState;
+    onClose: () => void;
+    onPickItem: (item: RecordBoardCalendarBookingLike) => void;
+    /** 仅日视图 lane 溢出：透传宿主 `renderBooking`（RoomCard） */
+    renderBooking?: (args: RecordBoardCalendarBookingRenderArgs) => React.ReactNode;
+    onDragStart?: (item: RecordBoardCalendarBookingLike) => void;
+};
+/**
+ * 全局溢出预约列表弹层（日视图 lane 与月/周/资源 `+N` 点开后）。
+ * 日视图列表行可走宿主 RoomCard；其它视图使用内置列表行。
+ */
+export declare function BookingCalendarOverflowListLayer({ overflowPanelRef, isLight, modal, onClose, onPickItem, renderBooking, onDragStart, }: BookingCalendarOverflowListLayerProps): JSX.Element;

package/lib/components/pisellRecordBoard/shellFrame/Calendar/modal/MoveConfirmModal.d.ts

@@ -0,0 +1,17 @@
+/// <reference types="react" />
+/** 拖拽改期后的确认弹窗（Court / 日期 / 起止时间） */
+export declare function MoveConfirmModal({ moveConfirm, moveDraft, setMoveDraft, panelRef, isLight, courts, visibleCourts, hourSlots, isBusinessHour, firstTimelineHour, endTimelineExclusive, onConfirm, onClose, }: {
+    moveConfirm: any;
+    moveDraft: any;
+    setMoveDraft: any;
+    panelRef: any;
+    isLight: any;
+    courts: any;
+    visibleCourts: any;
+    hourSlots: any;
+    isBusinessHour: any;
+    firstTimelineHour: any;
+    endTimelineExclusive: any;
+    onConfirm: any;
+    onClose: any;
+}): JSX.Element | null;

package/lib/components/pisellRecordBoard/shellFrame/Calendar/modal/OverflowListModal.d.ts

@@ -0,0 +1,30 @@
+import React from 'react';
+import { type CalendarBookingSegmentInput } from '../utils/bookingCalendarDateUtils';
+import type { RecordBoardCalendarBookingLike, RecordBoardCalendarBookingRenderArgs } from '../../../types';
+export declare type OverflowListModalVirtualListProps = {
+    items: CalendarBookingSegmentInput[];
+    dateKey: string;
+    onPickItem: (item: CalendarBookingSegmentInput) => void;
+    onClose: () => void;
+    /**
+     * 为 true 时按日视图逻辑展示状态徽标与状态底色（日视图 lane 溢出列表）。
+     * 月 / 周 / 资源 +N 弹层为 false，使用内置列表行（名称 + 时间）。
+     * @default true
+     */
+    showStatusUi?: boolean;
+    /**
+     * 为 true 且宿主提供 `renderBooking` 时，列表行复用日视图 RoomCard；
+     * 月 / 周 / 资源 +N 弹层恒为 false，不走宿主格内卡片。
+     */
+    isDayLaneOverflow?: boolean;
+    isLight?: boolean;
+    /** 仅日视图 lane 溢出：透传宿主 `renderBooking` */
+    renderBooking?: (args: RecordBoardCalendarBookingRenderArgs) => React.ReactNode;
+    onDragStart?: (item: RecordBoardCalendarBookingLike) => void;
+};
+/**
+ * 溢出预约列表弹层：`FixedSizeList` 虚拟列表。
+ * - 日视图 lane +N：宿主 `renderBooking`（RoomCard）
+ * - 月 / 周 / 资源 +N：内置列表行（名称 + 时间），不用格内自定义卡片
+ */
+export declare function OverflowListModalVirtualList({ items, dateKey, onPickItem, onClose, showStatusUi, isDayLaneOverflow, isLight, renderBooking, onDragStart, }: OverflowListModalVirtualListProps): JSX.Element | null;

package/lib/components/pisellRecordBoard/shellFrame/Calendar/utils/BookingCalendarStyle.d.ts

@@ -0,0 +1,10 @@
+import { type CalendarBookingSegmentInput } from './bookingCalendarDateUtils';
+export declare function getDrawerStatusTheme(item: CalendarBookingSegmentInput, dateKey: string): "bg-red-700/88 border-b-4 border-red-300/55" | "bg-zinc-700/88 border-b-4 border-zinc-400/45" | "bg-zinc-700/88 border-b-4 border-red-400/75" | "bg-violet-700/92 border-b-4 border-amber-400/95" | "bg-violet-700/92 border-b-4 border-zinc-300/45" | "bg-violet-700/92 border-b-4 border-violet-300/30";
+export declare function paymentTagClass(label: string, isLight?: boolean): "theme-success-chip border" | "bg-emerald-500 text-white" | "theme-warning-chip border" | "bg-amber-500 text-white" | "theme-info-chip border" | "bg-sky-500 text-white" | "theme-danger-chip border" | "bg-red-500 text-white";
+export declare function fulfillmentTagClass(label: string, isLight?: boolean): "bg-violet-600 text-white" | "theme-success-chip border" | "theme-warning-chip border" | "bg-amber-500 text-white" | "theme-info-chip border" | "theme-danger-chip border" | "bg-emerald-600 text-white" | "bg-cyan-500 text-white" | "bg-red-600 text-white" | "border border-[var(--border-strong)] bg-[var(--bg-input)] theme-text-soft" | "bg-zinc-600 text-white" | "border border-[var(--brand-light)] bg-[var(--brand-surface)] theme-brand-text";
+export declare function getBookingStateClasses(item: CalendarBookingSegmentInput, dateKey: string): "bg-zinc-700/55 border border-zinc-500/70 text-zinc-100 grayscale-[0.2]" | "bg-zinc-700/55 border border-red-500/70 text-zinc-200 grayscale-[0.15]" | "bg-violet-700/90 border border-amber-400/80 text-violet-50" | "bg-red-700/70 text-red-100" | "bg-violet-700/90 text-violet-50";
+/**
+ * 月 / 周紧凑格：不按签到/取消/迟到等状态变色，仅区分 booking（默认紫）与 block（红）。
+ * 与 {@link getBookingStateClasses} 在无状态分支时一致，但不读取 `dateKey`。
+ */
+export declare function getGridBookingRowStateClasses(item: CalendarBookingSegmentInput): string;

package/lib/components/pisellRecordBoard/shellFrame/Calendar/utils/bookingCalendarAxis.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 日历主轴映射纯函数：把一条 booking 在主轴方向的连续区间 [startUnit, endUnit)
+ * 按「精确比例 proportional」或「补全到刻度结束 snap」映射成 { offset, size }。
+ * 单位无关：scalePerUnit 既可是 px（固定列宽视图）也可是 %（弹性列视图）。
+ */
+export declare type TickFillMode = 'proportional' | 'snap';
+export declare type CalendarViewKind = 'day' | 'week' | 'resource' | 'month';
+export interface TickAxis {
+    /** 主轴起点对应的"绝对单位坐标"（日视图=firstTimelineHour；天维度=0） */
+    originUnit: number;
+    /** 每 1 单位的输出量（日视图=每小时 px；天维度=每列 px 或 %） */
+    scalePerUnit: number;
+    /** snap 的对齐粒度（单位）（日视图=slotStepHours；天维度=1） */
+    tickUnit: number;
+    /** 输出尺寸下限（与 scalePerUnit 同量纲），比例模式兜底可点击宽度 */
+    minSize: number;
+}
+export interface AxisSpan {
+    offset: number;
+    size: number;
+}
+export declare function mapAxisSpan(axis: TickAxis, startUnit: number, endUnit: number, mode: TickFillMode): AxisSpan;
+/**
+ * 天维度：把（列下标, 当天浮点小时）折算成连续「天单位」坐标。
+ * frac 限制在 [0,1]，使跨日首尾按当天营业小时占比收口。
+ *
+ * 营业窗口起点 `dayGridMin` 可能不是 0 点、甚至接近午夜（跨午夜营业，如 23:59 起）。
+ * 此时 `hour - dayGridMin` 对白天小时会变负而被 clamp 成 0，导致所有预约挤到格子开头。
+ * 因此先对 24h 做环绕，得到「距营业起点的正向偏移」，再按 span 归一化。
+ */
+export declare function dayGridUnit(colIndex: number, hour: number, dayGridMin: number, dayGridSpan: number): number;
+export declare function resolveTickFillMode(view: CalendarViewKind, override: TickFillMode | undefined): TickFillMode;