@pisell/materials 6.11.65 → 6.11.67

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

@@ -0,0 +1,10 @@
+import React from 'react';
+import type { PisellReservationScheduleBandProps } from './types';
+import './PisellReservationScheduleBand.less';
+/**
+ * 预约顶栏组合：营业日切换 + 锚定到选中日的时间导航轴
+ */
+export declare function PisellReservationScheduleBand(props: PisellReservationScheduleBandProps): React.JSX.Element;
+export declare namespace PisellReservationScheduleBand {
+    var displayName: string;
+}

package/es/components/pisellReservationScheduleBand/PisellReservationScheduleBand.stories.d.ts

@@ -0,0 +1,16 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { PisellReservationScheduleBand } from './PisellReservationScheduleBand';
+/**
+ * PisellReservationScheduleBand：营业日条 + 横向时间轴顶栏组合，统一 value `{ date, at }`。
+ * 详见组件目录下 docs/PisellReservationScheduleBand.md。
+ */
+declare const meta: Meta<typeof PisellReservationScheduleBand>;
+export default meta;
+declare type Story = StoryObj<typeof PisellReservationScheduleBand>;
+export declare const Default: Story;
+export declare const CustomTimeNavigator: Story;
+export declare const ScheduleMinMax: Story;
+export declare const Controlled: Story;
+export declare const InitialPastDay: Story;
+/** 日程行左右插槽：左标题 + 中间 PisellReservationSchedule + 右操作区（整条顶栏暗色背景需在业务外层自行包一层，避免压住下方时间轴） */
+export declare const WithScheduleSlots: Story;

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

@@ -0,0 +1,2 @@
+export { PisellReservationScheduleBand } from './PisellReservationScheduleBand';
+export type { PisellReservationScheduleBandProps, ReservationScheduleBandValue, TimeNavigatorPassthroughProps, } from './types';

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

@@ -0,0 +1,61 @@
+import type { CSSProperties, ReactNode } from 'react';
+import type { Dayjs } from 'dayjs';
+import type { PisellTimeNavigatorProps } from '../pisellTimeNavigator/types';
+import type { PisellReservationScheduleProps } from '../pisellReservationSchedule/types';
+/** 组合值：日历日 + 该日上的时刻（与 PisellTimeNavigator 对齐） */
+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;
+}

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

@@ -0,0 +1,10 @@
+import React from 'react';
+import type { PisellTimeNavigatorProps } from './types';
+import './PisellTimeNavigator.less';
+/**
+ * PisellTimeNavigator：可拖动的时间导航轴，时间范围内浏览、选择、控制
+ */
+export declare function PisellTimeNavigator(props: PisellTimeNavigatorProps): React.JSX.Element;
+export declare namespace PisellTimeNavigator {
+    var displayName: string;
+}

package/es/components/pisellTimeNavigator/PisellTimeNavigator.js

@@ -200,7 +200,12 @@ export function PisellTimeNavigator(props) {
     var span = Math.max(1, maxV - minV);
     var h = DENSITY_LAYER_HEIGHT;
     var points = slice.map(function (v, i) {
-      var x = i * cellSizePx + cellSizePx / 2;
+      /**
+       * 用 `timeToOffset(ticks[i])` 而非 `i * cellSize + cellSize/2` 取 x：
+       * head/tail partial 格存在时，每格宽度不再等于 `cellSize`，按索引等比相乘会跑偏。
+       * `timeToOffset` 始终随时间线性映射（含两端 dotOffsetPx 留白），与刻度层视觉对齐。
+       */
+      var x = axis.timeToOffset(axis.ticks[i]);
       /** 映射到 [0,1]：最低值贴底，最高值接近顶部，基本吃满密度层高度 */
       var t = (v - minV) / span;
       var y = h - 1 - t * (h - 3);
@@ -228,7 +233,7 @@ export function PisellTimeNavigator(props) {
       h: h,
       w: axis.totalLengthPx
     };
-  }, [isHorizontal, resolvedDensity, axis.ticks, axis.totalLengthPx, cellSizePx]);
+  }, [isHorizontal, resolvedDensity, axis.ticks, axis.timeToOffset, axis.totalLengthPx, cellSizePx]);
   var isControlled = valueProp !== undefined;
   var _useState5 = useState(function () {
       var v = valueProp !== null && valueProp !== void 0 ? valueProp : defaultValue;
@@ -848,7 +853,10 @@ export function PisellTimeNavigator(props) {
     timeFormat: timeFormat,
     locale: locale,
     style: scaleStyle,
-    horizontalCellSizePx: isHorizontal ? cellSizePx : undefined
+    horizontalCellSizePx: isHorizontal ? cellSizePx : undefined,
+    cellWidthsPx: isHorizontal ? axis.cellWidthsPx : undefined,
+    leadingPaddingPx: isHorizontal ? dotOffsetPx : undefined,
+    trailingPaddingPx: isHorizontal ? dotOffsetPx : undefined
   }), isHorizontal && currentTimeOffsetPx != null && currentTimeOffsetPx >= 0 && /*#__PURE__*/React.createElement("span", {
     className: "pisell-time-navigator-current-time-bubble",
     style: {

package/es/components/pisellTimeNavigator/PisellTimeNavigator.stories.d.ts

@@ -0,0 +1,79 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { PisellTimeNavigator } from './PisellTimeNavigator';
+/**
+ * PisellTimeNavigator 组件 Storybook
+ * 时间导航轴：时间范围内浏览、选择、控制
+ */
+declare const meta: Meta<typeof PisellTimeNavigator>;
+export default meta;
+declare type Story = StoryObj<typeof PisellTimeNavigator>;
+/**
+ * 默认：横向、轴动、显示 Now
+ */
+export declare const Default: Story;
+/** 默认 - 竖向 */
+export declare const DefaultVertical: Story;
+/**
+ * 受控 + 默认 12:00
+ */
+export declare const Controlled: Story;
+/** 受控 - 竖向 */
+export declare const ControlledVertical: Story;
+/**
+ * 非受控 + 默认 14:30
+ */
+export declare const Uncontrolled: Story;
+/** 非受控 - 竖向 */
+export declare const UncontrolledVertical: Story;
+/**
+ * 竖向
+ */
+export declare const Vertical: Story;
+/**
+ * 指针动模式（cursor-moves）
+ */
+export declare const CursorMoves: Story;
+/** 指针动模式 - 竖向 */
+export declare const CursorMovesVertical: Story;
+/**
+ * 营业时间高亮 10:00–22:00
+ */
+export declare const BusinessHours: Story;
+/** 营业时间高亮 - 竖向 */
+export declare const BusinessHoursVertical: Story;
+/**
+ * 自定义时间范围 08:00–20:00
+ */
+export declare const CustomRange: Story;
+/** 自定义时间范围 - 竖向 */
+export declare const CustomRangeVertical: Story;
+/**
+ * 步长 30 分钟
+ */
+export declare const Step30: Story;
+/** 步长 30 分钟 - 竖向 */
+export declare const Step30Vertical: Story;
+/**
+ * 惯性滚动开启
+ */
+export declare const Inertia: Story;
+/** 惯性滚动 - 竖向 */
+export declare const InertiaVertical: Story;
+/**
+ * 吸附到整点（松手后自动吸附到 0/15/30/45 分刻度）
+ */
+export declare const SnapToStep: Story;
+/** 吸附到整点 - 竖向 */
+export declare const SnapToStepVertical: Story;
+/**
+ * 隐藏 Now 按钮
+ */
+export declare const NoNowButton: Story;
+/** 隐藏 Now 按钮 - 竖向 */
+export declare const NoNowButtonVertical: Story;
+/**
+ * 实时模式（仅演示，实际会跟随系统时间）
+ */
+export declare const Realtime: Story;
+/** 实时模式 - 竖向 */
+export declare const RealtimeVertical: Story;

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): React.JSX.Element;

package/es/components/pisellTimeNavigator/components/ScaleLayer.js

@@ -8,7 +8,12 @@ import React from 'react';
 import classNames from 'classnames';
 /**
  * 刻度层：渲染时间刻度与标签
- * 横向：整点数字 + 小圆点；竖向：整点/半点数字 + 分割线
+ * - 横向：整点数字 + 小圆点；当 range 起止不在 step 网格上时，首尾两个格按时间比例**变窄**
+ *   （宽度 = `widthMinutes / step × cellSize`），中间格保持整步宽并落在整点 / 半点等对齐位置上。
+ * - 竖向：整点数字 + 分割线。
+ *
+ * 标签仅在「整点」（`tick.minute() === 0` 且秒为 0）时显示数字；非整点格只渲染圆点 / 分割线，
+ * 配合变窄的 head/tail 让起止时刻在视觉上自然衔接到第一个 / 最后一个整点。
  */
 export function ScaleLayer(_ref) {
   var orientation = _ref.orientation,
@@ -19,17 +24,35 @@ export function ScaleLayer(_ref) {
     locale = _ref.locale,
     style = _ref.style,
     className = _ref.className,
-    horizontalCellSizePx = _ref.horizontalCellSizePx;
+    horizontalCellSizePx = _ref.horizontalCellSizePx,
+    cellWidthsPx = _ref.cellWidthsPx,
+    leadingPaddingPx = _ref.leadingPaddingPx,
+    trailingPaddingPx = _ref.trailingPaddingPx;
   var isHorizontal = orientation === 'horizontal';
   return /*#__PURE__*/React.createElement("div", {
     className: classNames('pisell-time-navigator-scale', "pisell-time-navigator-scale--".concat(orientation), className),
     style: style
-  }, ticks.map(function (tick, i) {
-    var isMajor = tick.minute() % majorStepMinutes === 0;
-    /** 横向整点只展示小时，非整点用 timeFormat；竖向沿用 timeFormat */
+  }, isHorizontal && leadingPaddingPx != null && leadingPaddingPx > 0 && /*#__PURE__*/React.createElement("div", {
+    "aria-hidden": true,
+    style: {
+      width: leadingPaddingPx,
+      minWidth: leadingPaddingPx,
+      maxWidth: leadingPaddingPx,
+      flex: '0 0 auto'
+    }
+  }), ticks.map(function (tick, i) {
+    var isMajor = tick.minute() === 0 && tick.second() === 0;
+    /**
+     * 横向整点只展示小时（如 `16`）；竖向 / 非整点（理论不会进 isMajor 分支）走 timeFormat。
+     */
     var label = isHorizontal && isMajor ? locale ? tick.locale(locale).format('H') : tick.format('H') : locale ? tick.locale(locale).format(timeFormat) : tick.format(timeFormat);
     if (isHorizontal) {
-      var cw = horizontalCellSizePx != null && horizontalCellSizePx > 0 ? horizontalCellSizePx : undefined;
+      var baseCw = horizontalCellSizePx != null && horizontalCellSizePx > 0 ? horizontalCellSizePx : undefined;
+      /**
+       * 优先用调用方传入的 `cellWidthsPx[i]`（首尾 partial 格宽 < 整步），
+       * 退化为 baseCw（CSS 默认 54）以兼容旧调用路径。
+       */
+      var cw = cellWidthsPx != null && cellWidthsPx[i] != null ? cellWidthsPx[i] : baseCw;
       var compactPad = cw != null ? cw < 36 ? 2 : cw < 52 ? 6 : 10 : undefined;
       return /*#__PURE__*/React.createElement("div", {
         key: i,
@@ -69,5 +92,13 @@ export function ScaleLayer(_ref) {
     }), isMajor && /*#__PURE__*/React.createElement("span", {
       className: "pisell-time-navigator-scale-label"
     }, label));
+  }), isHorizontal && trailingPaddingPx != null && trailingPaddingPx > 0 && /*#__PURE__*/React.createElement("div", {
+    "aria-hidden": true,
+    style: {
+      width: trailingPaddingPx,
+      minWidth: trailingPaddingPx,
+      maxWidth: trailingPaddingPx,
+      flex: '0 0 auto'
+    }
   }));
 }

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

@@ -0,0 +1,5 @@
+export { BackgroundLayer } from './BackgroundLayer';
+export { CursorLayer } from './CursorLayer';
+export { GestureLayer } from './GestureLayer';
+export { NowButton } from './NowButton';
+export { ScaleLayer } from './ScaleLayer';

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/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/hooks/useTimeAxis.js

@@ -5,9 +5,16 @@ function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len
 function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t.return && (u = t.return(), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
 function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
 import { useMemo } from 'react';
-import { getRangeBounds, getTicks } from "../utils";
+import { getAxisCells, getRangeBounds } from "../utils";
 /**
- * 时间轴刻度与时间↔像素换算
+ * 时间轴刻度与时间↔像素换算。
+ *
+ * 格子拆分策略见 {@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 function useTimeAxis(options) {
   var range = options.range,
@@ -20,44 +27,60 @@ export function useTimeAxis(options) {
       _getRangeBounds2 = _slicedToArray(_getRangeBounds, 2),
       rangeStart = _getRangeBounds2[0],
       rangeEnd = _getRangeBounds2[1];
-    var ticks = getTicks(rangeStart, rangeEnd, stepMinutes);
+    var safeStep = Math.max(1, stepMinutes);
+    var cells = getAxisCells(rangeStart, rangeEnd, safeStep);
+    var ticks = cells.map(function (c) {
+      return c.start;
+    });
+    var cellWidthsPx = cells.map(function (c) {
+      return c.widthMinutes / safeStep * cellSizePx;
+    });
+    var cellsTotalPx = cellWidthsPx.reduce(function (s, w) {
+      return s + w;
+    }, 0);
     /**
-     * 仅当范围结束晚于最后一个刻度时（如全天 23:59）才多一格尾段，使最后一刻可滚到视口中心。
-     * 自定义范围如 08:00–20:00 的最后一格已是 20:00，不再多一格。
+     * 横向：每格中心为「时间下面的点」，dotOffsetPx = cellSizePx/2，rangeStart / rangeEnd
+     * 在轴上分别留 cellSize/2 留白以便居中。
+     * 竖向：对齐整点上面的粗线（格顶），dotOffsetPx = 0，无两端留白。
      */
-    var lastTick = ticks.length > 0 ? ticks[ticks.length - 1] : null;
-    /** 横向：仅当范围结束晚于最后刻度时多一格尾段 */
-    var needTailCell = orientation === 'horizontal' && lastTick != null && rangeEnd.isAfter(lastTick);
-    /** 竖向：范围结束恰在最后刻度时（如 08:00–20:00 的 20:00）不保留最后一格高度，与横向自定义范围一致 */
-    var noTailVertical = orientation === 'vertical' && lastTick != null && !rangeEnd.isAfter(lastTick);
-    var effectiveTicks = noTailVertical && ticks.length > 0 ? ticks.slice(0, -1) : ticks;
-    var rawTotalPx = orientation === 'vertical' ? effectiveTicks.length * cellSizePx : (ticks.length + (needTailCell ? 1 : 0)) * cellSizePx;
+    var dotOffsetPx = orientation === 'vertical' ? 0 : cellSizePx / 2;
+    var rawTotalPx = orientation === 'horizontal' ? cellsTotalPx + cellSizePx : cellsTotalPx;
     /** 防止异常 range/step 导致轴长爆炸（如竖向出现 33M 高度），上限约 2 天 15 分钟步进 */
     var totalLengthPx = Math.min(rawTotalPx, 500000);
-    /**
-     * 横向：每格中心为「时间下面的点」，dotOffsetPx = cellSizePx/2。
-     * 竖向：对齐整点上面的粗线（格顶），dotOffsetPx = 0。
-     */
-    var dotOffsetPx = orientation === 'vertical' ? 0 : cellSizePx / 2;
-    /** 最大偏移：竖向为最后一格顶；横向有尾格时为最后一格中心延伸，无尾格时为最后一格中心 */
-    var maxOffsetPx = orientation === 'vertical' ? totalLengthPx : dotOffsetPx + (needTailCell ? ticks.length : Math.max(0, ticks.length - 1)) * cellSizePx;
+    /** rangeEnd 在轴上的像素位置；横向 = dotOffsetPx + cellsTotalPx，竖向 = cellsTotalPx */
+    var maxOffsetPx = orientation === 'vertical' ? cellsTotalPx : dotOffsetPx + cellsTotalPx;
     var timeToOffset = function timeToOffset(t) {
       var diffMs = t.diff(rangeStart);
       var diffMin = diffMs / (60 * 1000);
-      var index = diffMin / stepMinutes;
+      var index = diffMin / safeStep;
       var px = dotOffsetPx + index * cellSizePx;
       return Math.max(dotOffsetPx, Math.min(px, maxOffsetPx));
     };
+
+    /**
+     * 吸附到最近的「格起点」：
+     * head/tail 长度可能小于 step 整步，传统的「按 cellSize 等分四舍五入」无法直接定位 tick；
+     * 这里按 ticks 实际像素位置线性扫描求最近邻，ticks 数组通常 ≤ ~200，开销可忽略。
+     */
     var offsetToTime = function offsetToTime(offset) {
-      var index = Math.round((offset - dotOffsetPx) / cellSizePx);
-      var tick = effectiveTicks[index];
-      return tick !== null && tick !== void 0 ? tick : null;
+      if (ticks.length === 0) return null;
+      var bestIdx = 0;
+      var bestDist = Infinity;
+      for (var i = 0; i < ticks.length; i += 1) {
+        var px = timeToOffset(ticks[i]);
+        var d = Math.abs(px - offset);
+        if (d < bestDist) {
+          bestDist = d;
+          bestIdx = i;
+        }
+      }
+      return ticks[bestIdx];
     };
 
     /** 偏移对应连续时间；横向以格点为中心，竖向以格顶为基准 */
     var offsetToTimeContinuous = function offsetToTimeContinuous(offset) {
       var index = (offset - dotOffsetPx) / cellSizePx;
-      var minutesFromStart = index * stepMinutes;
+      var minutesFromStart = index * safeStep;
       var t = rangeStart.add(minutesFromStart, 'minute');
       if (t.isBefore(rangeStart)) return rangeStart;
       if (t.isAfter(rangeEnd)) return rangeEnd;
@@ -66,7 +89,8 @@ export function useTimeAxis(options) {
     return {
       rangeStart: rangeStart,
       rangeEnd: rangeEnd,
-      ticks: effectiveTicks,
+      ticks: ticks,
+      cellWidthsPx: cellWidthsPx,
       timeToOffset: timeToOffset,
       offsetToTime: offsetToTime,
       offsetToTimeContinuous: offsetToTimeContinuous,

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

@@ -0,0 +1,5 @@
+export { PisellTimeNavigator } from './PisellTimeNavigator';
+export { getHorizontalAxisSlotCount, getRangeBounds, buildCalendarHourSlotsFromRange, buildCalendarTimelineSlotStartsFromRange, DEFAULT_CALENDAR_SLOT_STEP_MINUTES, } from './utils';
+export type { PisellTimeNavigatorProps, TimeNavigatorValue, TimeRangeOption, CursorMode, TimeNavigatorOrientation, } from './types';
+/** 多语言文案（en / zh-CN / zh-HK / ja / pt），使用前请在应用内通过 locales.init(pisellTimeNavigatorLocales, lang) 合并 */
+export { default as pisellTimeNavigatorLocales } from './locales';

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

@@ -0,0 +1,65 @@
+import { type Dayjs } from 'dayjs';
+import type { TimeNavigatorValue, TimeRangeOption } from '../types';
+/**
+ * 解析 value 为 Dayjs，无效则返回 null。
+ * 支持 dayjs 可解析的日期时间；纯时间字符串（如 '12:00'、'14:30'）会基于 reference 的日期解析。
+ */
+export declare function parseValue(value: TimeNavigatorValue, reference?: Dayjs): Dayjs | null;
+/** 日历时间轴默认步长（分钟），与历史「整点列」一致 */
+export declare const DEFAULT_CALENDAR_SLOT_STEP_MINUTES = 60;
+/**
+ * 按营业日 {@link TimeRangeOption} 在锚定自然日零点展开，生成日视图时间轴「列左边界」：
+ * 值为相对 `reference.startOf('day')` 的**浮点小时**（可 ≥24，表示次日时刻），步长为 `slotStepMinutes`。
+ */
+export declare function buildCalendarTimelineSlotStartsFromRange(range: TimeRangeOption | undefined, anchorDate: Date | Dayjs, slotStepMinutes?: number): number[];
+/**
+ * @deprecated 语义上等价于 {@link buildCalendarTimelineSlotStartsFromRange}(..., 60)；保留兼容导出。
+ */
+export declare function buildCalendarHourSlotsFromRange(range: TimeRangeOption | undefined, anchorDate: Date | Dayjs): number[];
+/**
+ * 将 range 转为 [startDayjs, endDayjs]（reference 为营业锚定日的 0 点）
+ * - 同日内：如 08:00–22:00
+ * - 跨日营业：结束钟面早于或等于开始（如 02:01–次日 02:00）时，end 解析为 reference 的次日同一时刻
+ */
+export declare function getRangeBounds(range: TimeRangeOption | undefined, reference: Dayjs): [Dayjs, Dayjs];
+/**
+ * 将时间吸附到 step 分钟刻度（0、15、30、45 等）：四舍五入到最近刻度。
+ */
+export declare function snapToStepMinutes(t: Dayjs, stepMinutes: number): Dayjs;
+/**
+ * 判断时间是否落在任一禁用区间内（按绝对时间与区间 [start,end) 比较）
+ * 注：与主时间轴同 reference 的跨日 range 一致时需传入同一营业锚定日解析出的区间。
+ */
+export declare function isInDisabledRanges(t: Dayjs, disabledRanges: TimeRangeOption[] | undefined): boolean;
+/**
+ * 在 [rangeStart, rangeEnd] 内按 stepMinutes 生成等步刻度时间列表（Dayjs）。
+ *
+ * @deprecated 仅用于不需要「头/尾 partial 格」的场景；时间轴渲染请用 {@link getAxisCells}。
+ */
+export declare function getTicks(rangeStart: Dayjs, rangeEnd: Dayjs, stepMinutes: number): Dayjs[];
+/**
+ * 时间轴上一格的描述：起始时间 + 跨度（分钟）。
+ * - 中间格：跨度 = `stepMinutes`，起点对齐到 step 网格（如 15 分钟一格时落在 `:00/:15/:30/:45`）；
+ * - head 格：当 `rangeStart` 不在网格上时存在，起点 = `rangeStart`，跨度 < step；
+ * - tail 格：当 `rangeEnd` 不在网格上时存在，起点 = 最后一个对齐点，跨度 < step。
+ */
+export interface AxisCell {
+    start: Dayjs;
+    widthMinutes: number;
+}
+/**
+ * 把 [`rangeStart`, `rangeEnd`] 切成「对齐到 step 网格」的格子序列：
+ *
+ * 1. 找到第一个 ≥ `rangeStart` 且分钟为 `stepMinutes` 整数倍的对齐点；
+ * 2. 若对齐点严格大于 `rangeStart`，先放一格 head（`rangeStart` → 对齐点），跨度 < step；
+ * 3. 中间按 step 步进，每格起点都落在网格上；
+ * 4. 若 `rangeEnd` 落在两个对齐点之间，最后多出一格 tail（最后对齐点 → `rangeEnd`），跨度 < step。
+ *
+ * `rangeStart` / `rangeEnd` 都恰落在网格上时退化为完全等步格。
+ */
+export declare function getAxisCells(rangeStart: Dayjs, rangeEnd: Dayjs, stepMinutes: number): AxisCell[];
+/**
+ * 横向时间轴「格」数量，与 useTimeAxis 中 cells 算法一致。
+ * 用于 cursor-moves 模式下计算压缩后的每格像素宽度。
+ */
+export declare function getHorizontalAxisSlotCount(range: TimeRangeOption | undefined, referenceDate: Dayjs, stepMinutes: number): number;