@pisell/materials 6.11.65 → 6.11.66

package/es/components/pisellTimeNavigator/utils/index.js

@@ -123,7 +123,9 @@ export function isInDisabledRanges(t, disabledRanges) {
 }
 
 /**
- * 在 [rangeStart, rangeEnd] 内按 stepMinutes 生成刻度时间列表（Dayjs）
+ * 在 [rangeStart, rangeEnd] 内按 stepMinutes 生成等步刻度时间列表（Dayjs）。
+ *
+ * @deprecated 仅用于不需要「头/尾 partial 格」的场景；时间轴渲染请用 {@link getAxisCells}。
  */
 export function getTicks(rangeStart, rangeEnd, stepMinutes) {
   var out = [];
@@ -136,15 +138,73 @@ export function getTicks(rangeStart, rangeEnd, stepMinutes) {
 }
 
 /**
- * 横向时间轴「格」数量，与 useTimeAxis 中 totalLengthPx 算法一致（含尾格）
+ * 时间轴上一格的描述：起始时间 + 跨度（分钟）。
+ * - 中间格：跨度 = `stepMinutes`，起点对齐到 step 网格（如 15 分钟一格时落在 `:00/:15/:30/:45`）；
+ * - head 格：当 `rangeStart` 不在网格上时存在，起点 = `rangeStart`，跨度 < step；
+ * - tail 格：当 `rangeEnd` 不在网格上时存在，起点 = 最后一个对齐点，跨度 < step。
+ */
+
+/**
+ * 把 [`rangeStart`, `rangeEnd`] 切成「对齐到 step 网格」的格子序列：
+ *
+ * 1. 找到第一个 ≥ `rangeStart` 且分钟为 `stepMinutes` 整数倍的对齐点；
+ * 2. 若对齐点严格大于 `rangeStart`，先放一格 head（`rangeStart` → 对齐点），跨度 < step；
+ * 3. 中间按 step 步进，每格起点都落在网格上；
+ * 4. 若 `rangeEnd` 落在两个对齐点之间，最后多出一格 tail（最后对齐点 → `rangeEnd`），跨度 < step。
+ *
+ * `rangeStart` / `rangeEnd` 都恰落在网格上时退化为完全等步格。
+ */
+export function getAxisCells(rangeStart, rangeEnd, stepMinutes) {
+  var out = [];
+  if (!rangeEnd.isAfter(rangeStart) || stepMinutes <= 0) return out;
+  var startMin = rangeStart.minute();
+  var remainder = (startMin % stepMinutes + stepMinutes) % stepMinutes;
+  var isStartAligned = remainder === 0 && rangeStart.second() === 0 && rangeStart.millisecond() === 0;
+  var firstAligned = isStartAligned ? rangeStart : rangeStart.startOf('hour').minute(startMin - remainder + stepMinutes).second(0).millisecond(0);
+  if (firstAligned.isAfter(rangeStart)) {
+    var headMin = firstAligned.diff(rangeStart, 'minute', true);
+    if (headMin > 0) {
+      out.push({
+        start: rangeStart,
+        widthMinutes: headMin
+      });
+    }
+  }
+  var cur = firstAligned;
+  /**
+   * 防御：超大 / 非法 range 时（如 1 年）直接挂死。这里限制最多 2 天 + 1 步的格数，
+   * 与 useTimeAxis 的 `totalLengthPx` 上限呼应。
+   */
+  var safetyLimit = 2 * 24 * 60 / stepMinutes + 4;
+  while (cur.isBefore(rangeEnd) && out.length < safetyLimit) {
+    var next = cur.add(stepMinutes, 'minute');
+    if (next.isAfter(rangeEnd)) {
+      var tailMin = rangeEnd.diff(cur, 'minute', true);
+      if (tailMin > 0) {
+        out.push({
+          start: cur,
+          widthMinutes: tailMin
+        });
+      }
+      break;
+    }
+    out.push({
+      start: cur,
+      widthMinutes: stepMinutes
+    });
+    cur = next;
+  }
+  return out;
+}
+
+/**
+ * 横向时间轴「格」数量，与 useTimeAxis 中 cells 算法一致。
+ * 用于 cursor-moves 模式下计算压缩后的每格像素宽度。
  */
 export function getHorizontalAxisSlotCount(range, referenceDate, stepMinutes) {
   var _getRangeBounds5 = getRangeBounds(range, referenceDate),
     _getRangeBounds6 = _slicedToArray(_getRangeBounds5, 2),
     rangeStart = _getRangeBounds6[0],
     rangeEnd = _getRangeBounds6[1];
-  var ticks = getTicks(rangeStart, rangeEnd, stepMinutes);
-  var lastTick = ticks.length > 0 ? ticks[ticks.length - 1] : null;
-  var needTailCell = lastTick != null && rangeEnd.isAfter(lastTick);
-  return ticks.length + (needTailCell ? 1 : 0);
+  return getAxisCells(rangeStart, rangeEnd, stepMinutes).length;
 }

package/lib/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/lib/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/lib/components/pisellReservationScheduleBand/index.d.ts

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

package/lib/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/lib/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/lib/components/pisellTimeNavigator/PisellTimeNavigator.js

@@ -186,7 +186,7 @@ function PisellTimeNavigator(props) {
     const span = Math.max(1, maxV - minV);
     const h = import_timeNavigatorConstants.DENSITY_LAYER_HEIGHT;
     const points = slice.map((v, i) => {
-      const x = i * cellSizePx + cellSizePx / 2;
+      const x = axis.timeToOffset(axis.ticks[i]);
       const t = (v - minV) / span;
       const y = h - 1 - t * (h - 3);
       return { x, y };
@@ -214,6 +214,7 @@ function PisellTimeNavigator(props) {
     isHorizontal,
     resolvedDensity,
     axis.ticks,
+    axis.timeToOffset,
     axis.totalLengthPx,
     cellSizePx
   ]);
@@ -867,7 +868,10 @@ function PisellTimeNavigator(props) {
                     timeFormat,
                     locale,
                     style: scaleStyle,
-                    horizontalCellSizePx: isHorizontal ? cellSizePx : void 0
+                    horizontalCellSizePx: isHorizontal ? cellSizePx : void 0,
+                    cellWidthsPx: isHorizontal ? axis.cellWidthsPx : void 0,
+                    leadingPaddingPx: isHorizontal ? dotOffsetPx : void 0,
+                    trailingPaddingPx: isHorizontal ? dotOffsetPx : void 0
                   }
                 ),
                 isHorizontal && currentTimeOffsetPx != null && currentTimeOffsetPx >= 0 && /* @__PURE__ */ import_react.default.createElement(

package/lib/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/lib/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/lib/components/pisellTimeNavigator/components/ScaleLayer.js

@@ -43,7 +43,10 @@ function ScaleLayer({
   locale,
   style,
   className,
-  horizontalCellSizePx
+  horizontalCellSizePx,
+  cellWidthsPx,
+  leadingPaddingPx,
+  trailingPaddingPx
 }) {
   const isHorizontal = orientation === "horizontal";
   return /* @__PURE__ */ import_react.default.createElement(
@@ -56,11 +59,24 @@ function ScaleLayer({
       ),
       style
     },
+    isHorizontal && leadingPaddingPx != null && leadingPaddingPx > 0 && /* @__PURE__ */ import_react.default.createElement(
+      "div",
+      {
+        "aria-hidden": true,
+        style: {
+          width: leadingPaddingPx,
+          minWidth: leadingPaddingPx,
+          maxWidth: leadingPaddingPx,
+          flex: "0 0 auto"
+        }
+      }
+    ),
     ticks.map((tick, i) => {
-      const isMajor = tick.minute() % majorStepMinutes === 0;
+      const isMajor = tick.minute() === 0 && tick.second() === 0;
       const label = isHorizontal && isMajor ? locale ? tick.locale(locale).format("H") : tick.format("H") : locale ? tick.locale(locale).format(timeFormat) : tick.format(timeFormat);
       if (isHorizontal) {
-        const cw = horizontalCellSizePx != null && horizontalCellSizePx > 0 ? horizontalCellSizePx : void 0;
+        const baseCw = horizontalCellSizePx != null && horizontalCellSizePx > 0 ? horizontalCellSizePx : void 0;
+        const cw = cellWidthsPx != null && cellWidthsPx[i] != null ? cellWidthsPx[i] : baseCw;
         const compactPad = cw != null ? cw < 36 ? 2 : cw < 52 ? 6 : 10 : void 0;
         return /* @__PURE__ */ import_react.default.createElement(
           "div",
@@ -107,7 +123,19 @@ function ScaleLayer({
         /* @__PURE__ */ import_react.default.createElement("span", { className: "pisell-time-navigator-scale-divider", "aria-hidden": true }),
         isMajor && /* @__PURE__ */ import_react.default.createElement("span", { className: "pisell-time-navigator-scale-label" }, label)
       );
-    })
+    }),
+    isHorizontal && trailingPaddingPx != null && trailingPaddingPx > 0 && /* @__PURE__ */ import_react.default.createElement(
+      "div",
+      {
+        "aria-hidden": true,
+        style: {
+          width: trailingPaddingPx,
+          minWidth: trailingPaddingPx,
+          maxWidth: trailingPaddingPx,
+          flex: "0 0 auto"
+        }
+      }
+    )
   );
 }
 // Annotate the CommonJS export names for ESM import in node:

package/lib/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/lib/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/lib/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/lib/components/pisellTimeNavigator/hooks/useTimeAxis.js

@@ -34,31 +34,42 @@ function useTimeAxis(options) {
   } = options;
   return (0, import_react.useMemo)(() => {
     const [rangeStart, rangeEnd] = (0, import_utils.getRangeBounds)(range, referenceDate);
-    const ticks = (0, import_utils.getTicks)(rangeStart, rangeEnd, stepMinutes);
-    const lastTick = ticks.length > 0 ? ticks[ticks.length - 1] : null;
-    const needTailCell = orientation === "horizontal" && lastTick != null && rangeEnd.isAfter(lastTick);
-    const noTailVertical = orientation === "vertical" && lastTick != null && !rangeEnd.isAfter(lastTick);
-    const effectiveTicks = noTailVertical && ticks.length > 0 ? ticks.slice(0, -1) : ticks;
-    const rawTotalPx = orientation === "vertical" ? effectiveTicks.length * cellSizePx : (ticks.length + (needTailCell ? 1 : 0)) * cellSizePx;
-    const totalLengthPx = Math.min(rawTotalPx, 5e5);
+    const safeStep = Math.max(1, stepMinutes);
+    const cells = (0, import_utils.getAxisCells)(rangeStart, rangeEnd, safeStep);
+    const ticks = cells.map((c) => c.start);
+    const cellWidthsPx = cells.map(
+      (c) => c.widthMinutes / safeStep * cellSizePx
+    );
+    const cellsTotalPx = cellWidthsPx.reduce((s, w) => s + w, 0);
     const dotOffsetPx = orientation === "vertical" ? 0 : cellSizePx / 2;
-    const maxOffsetPx = orientation === "vertical" ? totalLengthPx : dotOffsetPx + (needTailCell ? ticks.length : Math.max(0, ticks.length - 1)) * cellSizePx;
+    const rawTotalPx = orientation === "horizontal" ? cellsTotalPx + cellSizePx : cellsTotalPx;
+    const totalLengthPx = Math.min(rawTotalPx, 5e5);
+    const maxOffsetPx = orientation === "vertical" ? cellsTotalPx : dotOffsetPx + cellsTotalPx;
     const timeToOffset = (t) => {
       const diffMs = t.diff(rangeStart);
       const diffMin = diffMs / (60 * 1e3);
-      const index = diffMin / stepMinutes;
+      const index = diffMin / safeStep;
       const px = dotOffsetPx + index * cellSizePx;
       return Math.max(dotOffsetPx, Math.min(px, maxOffsetPx));
     };
     const offsetToTime = (offset) => {
-      const index = Math.round((offset - dotOffsetPx) / cellSizePx);
-      const tick = effectiveTicks[index];
-      return tick ?? null;
+      if (ticks.length === 0) return null;
+      let bestIdx = 0;
+      let bestDist = Infinity;
+      for (let i = 0; i < ticks.length; i += 1) {
+        const px = timeToOffset(ticks[i]);
+        const d = Math.abs(px - offset);
+        if (d < bestDist) {
+          bestDist = d;
+          bestIdx = i;
+        }
+      }
+      return ticks[bestIdx];
     };
     const offsetToTimeContinuous = (offset) => {
       const index = (offset - dotOffsetPx) / cellSizePx;
-      const minutesFromStart = index * stepMinutes;
-      let t = rangeStart.add(minutesFromStart, "minute");
+      const minutesFromStart = index * safeStep;
+      const t = rangeStart.add(minutesFromStart, "minute");
       if (t.isBefore(rangeStart)) return rangeStart;
       if (t.isAfter(rangeEnd)) return rangeEnd;
       return t;
@@ -66,7 +77,8 @@ function useTimeAxis(options) {
     return {
       rangeStart,
       rangeEnd,
-      ticks: effectiveTicks,
+      ticks,
+      cellWidthsPx,
       timeToOffset,
       offsetToTime,
       offsetToTimeContinuous,

package/lib/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/lib/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;

package/lib/components/pisellTimeNavigator/utils/index.js

@@ -32,6 +32,7 @@ __export(utils_exports, {
   DEFAULT_CALENDAR_SLOT_STEP_MINUTES: () => DEFAULT_CALENDAR_SLOT_STEP_MINUTES,
   buildCalendarHourSlotsFromRange: () => buildCalendarHourSlotsFromRange,
   buildCalendarTimelineSlotStartsFromRange: () => buildCalendarTimelineSlotStartsFromRange,
+  getAxisCells: () => getAxisCells,
   getHorizontalAxisSlotCount: () => getHorizontalAxisSlotCount,
   getRangeBounds: () => getRangeBounds,
   getTicks: () => getTicks,
@@ -118,18 +119,45 @@ function getTicks(rangeStart, rangeEnd, stepMinutes) {
   }
   return out;
 }
+function getAxisCells(rangeStart, rangeEnd, stepMinutes) {
+  const out = [];
+  if (!rangeEnd.isAfter(rangeStart) || stepMinutes <= 0) return out;
+  const startMin = rangeStart.minute();
+  const remainder = (startMin % stepMinutes + stepMinutes) % stepMinutes;
+  const isStartAligned = remainder === 0 && rangeStart.second() === 0 && rangeStart.millisecond() === 0;
+  const firstAligned = isStartAligned ? rangeStart : rangeStart.startOf("hour").minute(startMin - remainder + stepMinutes).second(0).millisecond(0);
+  if (firstAligned.isAfter(rangeStart)) {
+    const headMin = firstAligned.diff(rangeStart, "minute", true);
+    if (headMin > 0) {
+      out.push({ start: rangeStart, widthMinutes: headMin });
+    }
+  }
+  let cur = firstAligned;
+  const safetyLimit = 2 * 24 * 60 / stepMinutes + 4;
+  while (cur.isBefore(rangeEnd) && out.length < safetyLimit) {
+    const next = cur.add(stepMinutes, "minute");
+    if (next.isAfter(rangeEnd)) {
+      const tailMin = rangeEnd.diff(cur, "minute", true);
+      if (tailMin > 0) {
+        out.push({ start: cur, widthMinutes: tailMin });
+      }
+      break;
+    }
+    out.push({ start: cur, widthMinutes: stepMinutes });
+    cur = next;
+  }
+  return out;
+}
 function getHorizontalAxisSlotCount(range, referenceDate, stepMinutes) {
   const [rangeStart, rangeEnd] = getRangeBounds(range, referenceDate);
-  const ticks = getTicks(rangeStart, rangeEnd, stepMinutes);
-  const lastTick = ticks.length > 0 ? ticks[ticks.length - 1] : null;
-  const needTailCell = lastTick != null && rangeEnd.isAfter(lastTick);
-  return ticks.length + (needTailCell ? 1 : 0);
+  return getAxisCells(rangeStart, rangeEnd, stepMinutes).length;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_CALENDAR_SLOT_STEP_MINUTES,
   buildCalendarHourSlotsFromRange,
   buildCalendarTimelineSlotStartsFromRange,
+  getAxisCells,
   getHorizontalAxisSlotCount,
   getRangeBounds,
   getTicks,