@pisell/materials 6.11.224 → 6.12.1

package/es/components/pisellRecordBoard/shellFrame/ResourceWall/NoteTicker.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+import './VenueWallMarquee.less';
+export interface NoteTickerProps {
+    text: string;
+    color: string;
+    /** 跑完一整段所需秒数 */
+    duration?: number;
+    shouldMarquee: boolean;
+}
+/**
+ * 底部说明条：短文案省略静态展示，长文案无缝跑马灯（多段 copy 与 `VenueWallMarquee.less` 中 -33.333% 动画配套）。
+ * 系统「减少动态效果」时强制静态展示；跑马灯区对读屏 `aria-hidden` 避免重复朗读。
+ */
+export declare const NoteTicker: React.NamedExoticComponent<NoteTickerProps>;

package/es/components/pisellRecordBoard/shellFrame/ResourceWall/ResourceWallViewportToolbar.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+export interface ResourceWallViewportToolbarProps {
+    now: Date;
+    appearanceMode: 'light' | 'dark';
+    onAppearanceModeChange: (m: 'light' | 'dark') => void;
+    pseudoFullscreen: boolean;
+    onTogglePseudoFullscreen: () => void;
+    onOpenControlPanel: () => void;
+    headerBorder: string;
+    headerBg: string;
+    clockColor: string;
+    mutedText: string;
+    toolbarBtnBorder: string;
+    toolbarBtnBg: string;
+    toolbarBtnBgActive: string;
+}
+/** 资源墙顶栏：时钟、浅深切换、伪全屏、控制台入口 */
+export declare const ResourceWallViewportToolbar: React.FC<ResourceWallViewportToolbarProps>;

package/es/components/pisellRecordBoard/shellFrame/ResourceWall/resourceWallConstants.d.ts

@@ -0,0 +1,2 @@
+/** 说明文案超过该长度时用跑马灯（与 NoteTicker / VenueWallCard 共用） */
+export declare const RESOURCE_WALL_NOTE_MARQUEE_MIN_CHARS = 32;

package/es/components/pisellRecordBoard/shellFrame/ToolBar/recordBoardToolBarConstants.d.ts

@@ -0,0 +1,8 @@
+/** 与 RecordBoard ToolBar 行为绑定的 searchParams 字段名 */
+export declare const DEFAULT_SEARCH_FIELD = "keyword";
+/** 筛选在 searchParams 中的字段名 */
+export declare const FILTER_PARAMS_FIELD = "filter";
+/** 排序在 searchParams 中的字段名 */
+export declare const SORT_PARAMS_FIELD = "sort";
+/** 与 ResourceWall 默认 `filterFieldKey` 一致 */
+export declare const RESOURCE_WALL_QUICK_FILTER_KEY = "resource_wall_resource_ids";

package/es/components/pisellReservationSchedule/PisellReservationSchedule.stories.d.ts

@@ -0,0 +1,12 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { PisellReservationSchedule } from './PisellReservationSchedule';
+/**
+ * PisellReservationSchedule：预约营业日导航（上一天 / 日期文案 / 下一天）。
+ * 多语言与日期格式依赖 LowCode 引擎 locale。详见组件目录下 docs/PisellReservationSchedule.md。
+ */
+declare const meta: Meta<typeof PisellReservationSchedule>;
+export default meta;
+declare type Story = StoryObj<typeof PisellReservationSchedule>;
+export declare const Default: Story;
+export declare const WithMinMax: Story;
+export declare const Controlled: Story;

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

@@ -0,0 +1,2 @@
+export { PisellReservationSchedule } from './PisellReservationSchedule';
+export type { PisellReservationScheduleProps, ReservationScheduleValue, } from './types';

package/es/components/pisellReservationSchedule/locales.d.ts

@@ -0,0 +1,43 @@
+/** PisellReservationSchedule 多语言；使用前 locales.init 合并 */
+declare const _default: {
+    en: {
+        'pisell-reservation-schedule.today': string;
+        'pisell-reservation-schedule.prev': string;
+        'pisell-reservation-schedule.next': string;
+        'pisell-reservation-schedule.prev-week': string;
+        'pisell-reservation-schedule.next-week': string;
+        'pisell-reservation-schedule.prev-month': string;
+        'pisell-reservation-schedule.next-month': string;
+        'pisell-reservation-schedule.pick-date': string;
+        'pisell-reservation-schedule.pick-date-title': string;
+        'pisell-reservation-schedule.pick-week-title': string;
+        'pisell-reservation-schedule.pick-month-title': string;
+    };
+    'zh-CN': {
+        'pisell-reservation-schedule.today': string;
+        'pisell-reservation-schedule.prev': string;
+        'pisell-reservation-schedule.next': string;
+        'pisell-reservation-schedule.prev-week': string;
+        'pisell-reservation-schedule.next-week': string;
+        'pisell-reservation-schedule.prev-month': string;
+        'pisell-reservation-schedule.next-month': string;
+        'pisell-reservation-schedule.pick-date': string;
+        'pisell-reservation-schedule.pick-date-title': string;
+        'pisell-reservation-schedule.pick-week-title': string;
+        'pisell-reservation-schedule.pick-month-title': string;
+    };
+    'zh-HK': {
+        'pisell-reservation-schedule.today': string;
+        'pisell-reservation-schedule.prev': string;
+        'pisell-reservation-schedule.next': string;
+        'pisell-reservation-schedule.prev-week': string;
+        'pisell-reservation-schedule.next-week': string;
+        'pisell-reservation-schedule.prev-month': string;
+        'pisell-reservation-schedule.next-month': string;
+        'pisell-reservation-schedule.pick-date': string;
+        'pisell-reservation-schedule.pick-date-title': string;
+        'pisell-reservation-schedule.pick-week-title': string;
+        'pisell-reservation-schedule.pick-month-title': string;
+    };
+};
+export default _default;

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

@@ -0,0 +1,52 @@
+import type { CSSProperties } from 'react';
+import type { Dayjs } from 'dayjs';
+/** 与 PisellTimeNavigator 一致：dayjs 或可解析字符串 */
+export declare type ReservationScheduleValue = Dayjs | string | null | undefined;
+/**
+ * PisellReservationSchedule：营业日切换条（上一日 / 文案 / 下一日）
+ */
+export interface PisellReservationScheduleProps {
+    /**
+     * 当前选中日（受控），日历日语义，建议使用 startOf('day') 对齐
+     */
+    value?: ReservationScheduleValue;
+    /**
+     * 选中日变更
+     */
+    onChange?: (date: Dayjs) => void;
+    /**
+     * 非受控初始日
+     */
+    defaultValue?: ReservationScheduleValue;
+    /**
+     * 不可早于该日（含）
+     */
+    minDate?: ReservationScheduleValue;
+    /**
+     * 不可晚于该日（含）
+     */
+    maxDate?: ReservationScheduleValue;
+    /**
+     * 自定义类名
+     */
+    className?: string;
+    /**
+     * 根节点样式
+     */
+    style?: CSSProperties;
+    /**
+     * 为 true 时禁用上一日/下一日、日期点选（弹日历）；用于「跟随当前时刻」等只读日期条
+     * @default false
+     */
+    navigationLocked?: boolean;
+    /**
+     * `navigationLocked` 时的展示形态：`full` 保留左右箭头占位；`labelOnly` 仅展示中间日期文案（如场控页）。
+     * @default 'full'
+     */
+    navigationLockedDisplay?: 'full' | 'labelOnly';
+    /**
+     * 顶栏切换步长：`day` 按日；`week` 按周；`month` 按月（与 RecordBoard 日历视图联动）。
+     * @default 'day'
+     */
+    navigationUnit?: 'day' | 'week' | 'month';
+}

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

@@ -0,0 +1,68 @@
+import type { CSSProperties, ReactNode } from 'react';
+import type { Dayjs } from 'dayjs';
+import type { PisellTimeNavigatorProps } from '../pisellTimeNavigator/types';
+import type { PisellReservationScheduleProps } from '../pisellReservationSchedule/types';
+/**
+ * 组合值：顶栏选中日（营业日锚定）+ 时间轴游标绝对时刻 `at`。
+ * 跨日营业时 `at` 可为其它自然日时刻，顶栏 `date` 通常不变；展示用 {@link formatScheduleAtLabel}（带日期）。
+ */
+export interface ReservationScheduleBandValue {
+    date: Dayjs;
+    at: Dayjs;
+}
+export declare type TimeNavigatorPassthroughProps = Omit<PisellTimeNavigatorProps, 'value' | 'onChange' | 'defaultValue'>;
+/**
+ * PisellReservationScheduleBand：营业日条 + 横向时间轴
+ */
+export interface PisellReservationScheduleBandProps {
+    /**
+     * 受控：选中日 + 轴上时刻
+     */
+    value?: ReservationScheduleBandValue;
+    /**
+     * 日历日或时刻任一变化时触发
+     */
+    onChange?: (next: ReservationScheduleBandValue) => void;
+    /**
+     * 非受控初始值（可只传部分字段）
+     */
+    defaultValue?: Partial<ReservationScheduleBandValue>;
+    /**
+     * 透传给 PisellReservationSchedule（如 minDate / maxDate）
+     */
+    scheduleProps?: Omit<PisellReservationScheduleProps, 'value' | 'onChange' | 'defaultValue'>;
+    /**
+     * 透传给 PisellTimeNavigator（不含 value/onChange/referenceDate）
+     */
+    timeNavigatorProps?: TimeNavigatorPassthroughProps;
+    /**
+     * 顶栏日程行：PisellReservationSchedule 左侧自定义内容（如标题）
+     */
+    scheduleStartSlot?: ReactNode;
+    /**
+     * 顶栏日程行：PisellReservationSchedule 右侧自定义内容（如状态、主按钮）
+     */
+    scheduleEndSlot?: ReactNode;
+    /**
+     * 顶栏日程行：紧挨在选日组件之后（如「跟随当前」），与中间列同一 flex 区
+     */
+    scheduleAfterDateSlot?: ReactNode;
+    /**
+     * 为 true 时隐藏下方时间导航轴（如日历视图仅需要选日/选周/选月）
+     */
+    hideTimeNavigator?: boolean;
+    /**
+     * 为 true 时在整个日程带上叠加载层（如切换营业日后拉预约列表期间）
+     */
+    dataLoading?: boolean;
+    /**
+     * 加载层内文案，由业务侧 {@link locales.getText} 等注入
+     */
+    dataLoadingTip?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    /**
+     * 追加到内部 `.pisell-reservation-schedule-band-schedule-row` 的类名（如手机端无视图切换时改为一行布局）。
+     */
+    scheduleRowClassName?: string;
+}

package/es/components/pisellReservationScheduleBand/utils/formatScheduleAtLabel.d.ts

@@ -0,0 +1,9 @@
+import type { Dayjs } from 'dayjs';
+/**
+ * 预约顶栏游标文案：与顶栏锚定日同一天只显示 HH:mm；跨自然日则带日期（MM-DD HH:mm）。
+ * 顶栏 `date` 不变，仅展示层标明 `at` 的真实日历日。
+ *
+ * @param at 时间轴绝对时刻（可落在锚定日的次日等）
+ * @param anchorDate 顶栏选中的日历日（营业日锚定，不因拖轴而改）
+ */
+export declare function formatScheduleAtLabel(at: Dayjs, anchorDate: Dayjs): string;

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,62 @@
+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;
+    /**
+     * 工具栏正下方、统计/正文之上的"附加条"插槽，渲染于 header 内部。
+     * 适用于「统计摘要 / 当前所选筛选标签」等需要紧贴 toolbar 的轻量条目。
+     * 当为空时不占位、不渲染外壳。
+     */
+    belowToolbar?: ReactNode;
+    /** 统计列表内容（如 PisellStatisticList 或自定义） */
+    statisticList?: ReactNode;
+    /** 主内容（表格/看板/日历/楼层图等），当 config.scroll 为 true 时会被滚动容器包裹 */
+    children?: ReactNode;
+    /** 批量操作条，通常按选中状态显隐由调用方控制 */
+    batchActionBar?: ReactNode;
+    /** 状态提示（加载/错误/同步提示等） */
+    statusArea?: ReactNode;
+}

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

@@ -0,0 +1,4 @@
+/// <reference types="react" />
+import { PisellSortProps } from './type';
+declare const PisellSort: (props: PisellSortProps) => JSX.Element;
+export default PisellSort;

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

@@ -0,0 +1,7 @@
+import { SortListProps } from '../sort/types';
+import { FormInstance } from 'antd';
+export declare type PisellSortProps = SortListProps & {
+    name?: string;
+} & FormInstance & {
+    hasForm?: boolean;
+};

package/es/components/pisellTimeNavigator/components/BackgroundLayer.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+export interface BackgroundLayerProps {
+    orientation: 'horizontal' | 'vertical';
+    /** 过去时间淡化色 */
+    pastTimeFade?: string;
+    /** 营业时间区间 [startPx, endPx]，用于视觉高亮 */
+    businessHoursPx?: [number, number];
+    className?: string;
+    style?: React.CSSProperties;
+}
+/**
+ * 背景区间层：营业时间高亮、过去时间淡化等（当前时间渐变已拆为独立块，见 axis-wrap 内 .pisell-time-navigator-current-gradient）
+ */
+export declare function BackgroundLayer({ orientation, pastTimeFade, businessHoursPx, className, style, }: BackgroundLayerProps): JSX.Element;

package/es/components/pisellTimeNavigator/components/CursorLayer.d.ts

@@ -0,0 +1,29 @@
+import React from 'react';
+import type { Dayjs } from 'dayjs';
+export interface CursorLayerProps {
+    orientation: 'horizontal' | 'vertical';
+    value: Dayjs | null;
+    timeFormat: string;
+    /** 优先于 timeFormat + locale */
+    formatTimeLabel?: (value: Dayjs) => string;
+    locale?: string;
+    isRealtime: boolean;
+    offsetPx: number;
+    /** axis-moves 时固定于视口中央，不应用 offsetPx */
+    fixedCenter?: boolean;
+    style?: React.CSSProperties;
+    className?: string;
+    /** cursor-moves：允许拖指针改时间 */
+    dragInteractive?: boolean;
+    /** 当前是否正处于拖拽（按下未抬起）：用于驱动气泡放大反馈样式 */
+    isDragging?: boolean;
+    onDragPointerDown?: React.PointerEventHandler<HTMLDivElement>;
+    onDragPointerMove?: React.PointerEventHandler<HTMLDivElement>;
+    onDragPointerUp?: React.PointerEventHandler<HTMLDivElement>;
+    onDragPointerCancel?: React.PointerEventHandler<HTMLDivElement>;
+}
+/**
+ * 时间指示器层：横向为「顶三角 + 竖长方条」SVG，竖向为横线 + 时间气泡
+ * 对齐基准为几何中心。Realtime 态 #FF692E，浏览态 #344054
+ */
+export declare function CursorLayer({ orientation, value, timeFormat, formatTimeLabel, locale, isRealtime, offsetPx, fixedCenter, style, className, dragInteractive, isDragging, onDragPointerDown, onDragPointerMove, onDragPointerUp, onDragPointerCancel, }: CursorLayerProps): JSX.Element | null;

package/es/components/pisellTimeNavigator/components/GestureLayer.d.ts

@@ -0,0 +1,41 @@
+import React from 'react';
+import type { Dayjs } from 'dayjs';
+export interface GestureLayerProps {
+    orientation: 'horizontal' | 'vertical';
+    cellSizePx: number;
+    /** 轴在滚动内容中的起始边距（左/上），用于把「滚动内容坐标」转为「轴内偏移」（与 dot 对齐） */
+    axisStartMarginPx: number;
+    /**
+     * 偏移 → 整点对齐的「最近 tick」时间。`snapToStep=true` 时点击 / 方向键吸到 step 网格上用。
+     */
+    offsetToTime: (offset: number) => Dayjs | null;
+    /**
+     * 偏移 → 连续时间（不吸附）。`snapToStep=false` 时点击与方向键都走这条，
+     * 让用户点哪儿就跳到哪一秒，不再被 stepMinutes 强行回弹。
+     */
+    offsetToTimeContinuous: (offset: number) => Dayjs | null;
+    onSelectTime: (t: Dayjs) => void;
+    isInDisabledRanges: (t: Dayjs) => boolean;
+    snapToStep: boolean;
+    stepMinutes: number;
+    snapFn: (t: Dayjs) => Dayjs;
+    scrollPosition: {
+        scrollLeft: number;
+        scrollTop: number;
+    };
+    viewportSize: {
+        w: number;
+        h: number;
+    };
+    onPointerDown?: React.PointerEventHandler;
+    onPointerMove?: React.PointerEventHandler;
+    onPointerUp?: React.PointerEventHandler;
+    onPointerLeave?: React.PointerEventHandler;
+    /** 轴上任意指针按下（含惯性拖轴） */
+    onUserInteraction?: () => void;
+    children: React.ReactNode;
+}
+/**
+ * 交互层：点击刻度跳转、键盘左右/上下 + 回车
+ */
+export declare function GestureLayer({ orientation, cellSizePx, axisStartMarginPx, offsetToTime, offsetToTimeContinuous, onSelectTime, isInDisabledRanges, snapToStep, stepMinutes, snapFn, scrollPosition, viewportSize, onPointerDown, onPointerMove, onPointerUp, onPointerLeave, onUserInteraction, children, }: GestureLayerProps): JSX.Element;

package/es/components/pisellTimeNavigator/components/ScaleLayer.d.ts

@@ -0,0 +1,40 @@
+import React from 'react';
+import type { Dayjs } from 'dayjs';
+export interface ScaleLayerProps {
+    orientation: 'horizontal' | 'vertical';
+    ticks: Dayjs[];
+    stepMinutes: number;
+    majorStepMinutes: number;
+    timeFormat: string;
+    locale?: string;
+    style?: React.CSSProperties;
+    className?: string;
+    /**
+     * 横向每格宽度（px），须与 useTimeAxis 的 cellSizePx 一致；
+     * 不传时样式表默认 82（axis-moves）；cursor-moves 压缩比例时必传
+     */
+    horizontalCellSizePx?: number;
+    /**
+     * 每个 tick 对应「格」的实际宽度（px）。范围起止不在 step 网格上时，首尾会出现宽度
+     * 小于 `horizontalCellSizePx` 的 head/tail 格；中间仍保持整步宽。
+     * 不传时退化为「全部按 horizontalCellSizePx 等宽」。
+     */
+    cellWidthsPx?: number[];
+    /**
+     * 横向时，整体两端各留出 `cellSize/2` 的居中留白（与 `useTimeAxis.dotOffsetPx` 一致），
+     * 使 rangeStart / rangeEnd 的实际像素位置落在头格 / 尾格的左 / 右边沿，
+     * 与拖拽光标的 `timeToOffset` 像素对齐。
+     */
+    leadingPaddingPx?: number;
+    trailingPaddingPx?: number;
+}
+/**
+ * 刻度层：渲染时间刻度与标签
+ * - 横向：整点数字 + 小圆点；当 range 起止不在 step 网格上时，首尾两个格按时间比例**变窄**
+ *   （宽度 = `widthMinutes / step × cellSize`），中间格保持整步宽并落在整点 / 半点等对齐位置上。
+ * - 竖向：整点数字 + 分割线。
+ *
+ * 标签仅在「整点」（`tick.minute() === 0` 且秒为 0）时显示数字；非整点格只渲染圆点 / 分割线，
+ * 配合变窄的 head/tail 让起止时刻在视觉上自然衔接到第一个 / 最后一个整点。
+ */
+export declare function ScaleLayer({ orientation, ticks, stepMinutes, majorStepMinutes, timeFormat, locale, style, className, horizontalCellSizePx, cellWidthsPx, leadingPaddingPx, trailingPaddingPx, }: ScaleLayerProps): JSX.Element;

package/es/components/pisellTimeNavigator/hooks/index.d.ts

@@ -0,0 +1,5 @@
+export { useTimeAxis } from './useTimeAxis';
+export type { UseTimeAxisOptions, TimeAxisState } from './useTimeAxis';
+export { useRealtime } from './useRealtime';
+export { useDragInertia } from './useDragInertia';
+export type { UseDragInertiaOptions } from './useDragInertia';

package/es/components/pisellTimeNavigator/hooks/useDragInertia.d.ts

@@ -0,0 +1,14 @@
+export interface UseDragInertiaOptions {
+    enabled: boolean;
+    orientation: 'horizontal' | 'vertical';
+    getScrollContainer: () => HTMLElement | null;
+}
+/**
+ * 惯性滚动：根据拖动末段速度在松手后继续滚动并衰减
+ */
+export declare function useDragInertia(options: UseDragInertiaOptions): {
+    onPointerDown: (e: React.PointerEvent) => void;
+    onPointerMove: (e: React.PointerEvent) => void;
+    onPointerUp: (e: React.PointerEvent) => void;
+    stopInertia: () => void;
+};

package/es/components/pisellTimeNavigator/hooks/useRealtime.d.ts

@@ -0,0 +1,5 @@
+import type { Dayjs } from 'dayjs';
+/**
+ * Realtime 模式：每秒将当前系统时间通过 onTick 回传
+ */
+export declare function useRealtime(enabled: boolean, onTick: (now: Dayjs) => void): void;

package/es/components/pisellTimeNavigator/hooks/useTimeAxis.d.ts

@@ -0,0 +1,37 @@
+import type { Dayjs } from 'dayjs';
+import type { TimeRangeOption } from '../types';
+export interface UseTimeAxisOptions {
+    range?: TimeRangeOption;
+    stepMinutes: number;
+    referenceDate: Dayjs;
+    orientation: 'horizontal' | 'vertical';
+    /** 横向时每格宽度（px），竖向时每格高度（px） */
+    cellSizePx: number;
+}
+export interface TimeAxisState {
+    rangeStart: Dayjs;
+    rangeEnd: Dayjs;
+    /** 每格起点时间序列（含 head / tail，对齐到 step 网格） */
+    ticks: Dayjs[];
+    /** 与 `ticks` 一一对应的格宽（px）；head / tail 可 < cellSizePx，中间格 = cellSizePx */
+    cellWidthsPx: number[];
+    /** 时间转主轴偏移（px） */
+    timeToOffset: (t: Dayjs) => number;
+    /** 主轴偏移（px）转时间（最近刻度，用于刻度对齐） */
+    offsetToTime: (offset: number) => Dayjs | null;
+    /** 主轴偏移（px）转时间（连续插值，用于拖动时按分钟步长显示） */
+    offsetToTimeContinuous: (offset: number) => Dayjs | null;
+    /** 主轴总长度（px） */
+    totalLengthPx: number;
+}
+/**
+ * 时间轴刻度与时间↔像素换算。
+ *
+ * 格子拆分策略见 {@link getAxisCells}：当 `range.start` / `range.end` 不在 `stepMinutes` 网格上时，
+ * 首尾出现宽度按时间比例缩小的 head/tail 格，中间格保持 step 整步并落在网格整点上。
+ *
+ * 时间→像素仍是线性映射 `dotOffsetPx + (t - rangeStart) / step × cellSize`，与 head/tail 是否存在无关：
+ * `dotOffsetPx`（横向 = `cellSize/2`，竖向 = 0）为 rangeStart 在轴内的像素位置；轴两端各保留 `dotOffsetPx`
+ * 留白以居中 rangeStart / rangeEnd。
+ */
+export declare function useTimeAxis(options: UseTimeAxisOptions): TimeAxisState;

package/es/components/pisellTimeNavigator/locales.d.ts

@@ -0,0 +1,22 @@
+/**
+ * PisellTimeNavigator 多语言文案
+ * 使用前请在应用内通过 locales.init() 合并本模块导出的 key
+ */
+declare const _default: {
+    en: {
+        'pisell-time-navigator.now': string;
+    };
+    'zh-CN': {
+        'pisell-time-navigator.now': string;
+    };
+    'zh-HK': {
+        'pisell-time-navigator.now': string;
+    };
+    ja: {
+        'pisell-time-navigator.now': string;
+    };
+    pt: {
+        'pisell-time-navigator.now': string;
+    };
+};
+export default _default;

package/es/components/pisellTimeNavigator/timeNavigatorConstants.d.ts

@@ -0,0 +1,20 @@
+/**
+ * PisellTimeNavigator 布局与尺寸常量（与 Figma / 交互 spec 对齐）
+ */
+/** 横向每格宽度（px），Figma 约 82；axis-moves 固定用此值 */
+export declare const CELL_SIZE_H = 82;
+/**
+ * 横向「此刻」橙区目标宽度（px）：按 axis-moves 下一格多的比例换算；
+ * 滚动轴与 cursor-moves 压格时同宽。
+ */
+export declare const CURRENT_TIME_GRADIENT_WIDTH_H_PX: number;
+/** 竖向每格高度（px） */
+export declare const CELL_SIZE_V = 20;
+/** 横向「Now」按钮占位，避免刻度被挡 */
+export declare const CURSOR_MOVES_NOW_RESERVE_PX = 56;
+/** cursor-moves 横向：轴与视口左右边距 */
+export declare const CURSOR_MOVES_H_PADDING_PX = 8;
+/** cursor-moves 横向：每格最小宽度（再小刻度不可读） */
+export declare const CURSOR_MOVES_MIN_CELL_PX = 8;
+/** 密度层高度：时间轴 48px 内留少量上下边距 */
+export declare const DENSITY_LAYER_HEIGHT = 46;