@pisell/materials 6.11.17 → 6.11.18

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

@@ -0,0 +1,73 @@
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : String(i); }
+function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+import React from 'react';
+import classNames from 'classnames';
+/**
+ * 刻度层：渲染时间刻度与标签
+ * 横向：整点数字 + 小圆点；竖向：整点/半点数字 + 分割线
+ */
+export function ScaleLayer(_ref) {
+  var orientation = _ref.orientation,
+    ticks = _ref.ticks,
+    stepMinutes = _ref.stepMinutes,
+    majorStepMinutes = _ref.majorStepMinutes,
+    timeFormat = _ref.timeFormat,
+    locale = _ref.locale,
+    style = _ref.style,
+    className = _ref.className,
+    horizontalCellSizePx = _ref.horizontalCellSizePx;
+  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 */
+    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 compactPad = cw != null ? cw < 36 ? 2 : cw < 52 ? 6 : 10 : undefined;
+      return /*#__PURE__*/React.createElement("div", {
+        key: i,
+        className: classNames('pisell-time-navigator-scale-cell', 'pisell-time-navigator-scale-cell--h', {
+          'pisell-time-navigator-scale-cell--major': isMajor
+        }),
+        style: cw != null ? _objectSpread({
+          width: cw,
+          minWidth: cw,
+          maxWidth: cw,
+          flex: '0 0 auto',
+          boxSizing: 'border-box'
+        }, compactPad != null ? {
+          padding: compactPad
+        } : {}) : undefined
+      }, isMajor && /*#__PURE__*/React.createElement("span", {
+        className: "pisell-time-navigator-scale-label",
+        style: cw != null && cw < 48 ? {
+          fontSize: Math.max(10, Math.round(cw * 0.32)),
+          lineHeight: 1.15
+        } : undefined
+      }, label), !isMajor && /*#__PURE__*/React.createElement("span", {
+        className: "pisell-time-navigator-scale-dot",
+        "aria-hidden": true
+      }));
+    }
+
+    /* 竖向：仅展示整点时间；整点格加 --major，顶部粗线 */
+    return /*#__PURE__*/React.createElement("div", {
+      key: i,
+      className: classNames('pisell-time-navigator-scale-cell', 'pisell-time-navigator-scale-cell--v', {
+        'pisell-time-navigator-scale-cell--major': isMajor
+      })
+    }, /*#__PURE__*/React.createElement("span", {
+      className: "pisell-time-navigator-scale-divider",
+      "aria-hidden": true
+    }), isMajor && /*#__PURE__*/React.createElement("span", {
+      className: "pisell-time-navigator-scale-label"
+    }, label));
+  }));
+}

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/components/index.js

@@ -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/index.js

@@ -0,0 +1,3 @@
+export { useTimeAxis } from "./useTimeAxis";
+export { useRealtime } from "./useRealtime";
+export { useDragInertia } 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/useDragInertia.js

@@ -0,0 +1,109 @@
+import { useCallback, useRef } from 'react';
+var DECAY = 0.95;
+var MIN_VELOCITY = 0.5;
+var SAMPLE_MS = 50;
+/**
+ * 惯性滚动：根据拖动末段速度在松手后继续滚动并衰减
+ */
+export function useDragInertia(options) {
+  var enabled = options.enabled,
+    orientation = options.orientation,
+    getScrollContainer = options.getScrollContainer;
+  var rafId = useRef(null);
+  var lastPos = useRef(0);
+  var lastTime = useRef(0);
+  var velocity = useRef(0);
+  var samples = useRef([]);
+  var applyScroll = useCallback(function (delta) {
+    var el = getScrollContainer();
+    if (!el) return;
+    if (orientation === 'horizontal') {
+      el.scrollLeft = Math.max(0, el.scrollLeft + delta);
+    } else {
+      el.scrollTop = Math.max(0, el.scrollTop + delta);
+    }
+  }, [getScrollContainer, orientation]);
+  var lastTickTime = useRef(0);
+  var tick = useCallback(function (now) {
+    var t = now !== null && now !== void 0 ? now : performance.now();
+    var dt = lastTickTime.current ? (t - lastTickTime.current) / 1000 : 0.016;
+    lastTickTime.current = t;
+    var v = velocity.current;
+    if (Math.abs(v) < MIN_VELOCITY) {
+      velocity.current = 0;
+      lastTickTime.current = 0;
+      return;
+    }
+    applyScroll(v * dt);
+    velocity.current = v * DECAY;
+    rafId.current = requestAnimationFrame(tick);
+  }, [applyScroll]);
+  var stopInertia = useCallback(function () {
+    if (rafId.current != null) {
+      cancelAnimationFrame(rafId.current);
+      rafId.current = null;
+    }
+    velocity.current = 0;
+    samples.current = [];
+  }, []);
+  var onPointerDown = useCallback(function (e) {
+    if (!enabled) return;
+    stopInertia();
+    var pos = orientation === 'horizontal' ? e.clientX : e.clientY;
+    lastPos.current = pos;
+    lastTime.current = Date.now();
+    samples.current = [{
+      pos: pos,
+      t: lastTime.current
+    }];
+  }, [enabled, orientation, stopInertia]);
+  var onPointerMove = useCallback(function (e) {
+    if (!enabled) return;
+    var pos = orientation === 'horizontal' ? e.clientX : e.clientY;
+    var t = Date.now();
+    var el = getScrollContainer();
+    if (el) {
+      var scroll = orientation === 'horizontal' ? el.scrollLeft : el.scrollTop;
+      var delta = pos - lastPos.current;
+      var maxScroll = orientation === 'horizontal' ? el.scrollWidth - el.clientWidth : el.scrollHeight - el.clientHeight;
+      var next = Math.max(0, Math.min(maxScroll, scroll + delta));
+      if (orientation === 'horizontal') {
+        el.scrollLeft = next;
+      } else {
+        el.scrollTop = next;
+      }
+    }
+    lastPos.current = pos;
+    lastTime.current = t;
+    samples.current.push({
+      pos: pos,
+      t: t
+    });
+    var cutoff = t - SAMPLE_MS;
+    while (samples.current.length > 1 && samples.current[0].t < cutoff) {
+      samples.current.shift();
+    }
+  }, [enabled, orientation, getScrollContainer]);
+  var onPointerUp = useCallback(function (e) {
+    if (!enabled) return;
+    var arr = samples.current;
+    if (arr.length < 2) return;
+    var first = arr[0];
+    var last = arr[arr.length - 1];
+    var dt = (last.t - first.t) / 1000;
+    if (dt <= 0) return;
+    var scrollEl = getScrollContainer();
+    if (!scrollEl) return;
+    var scroll = orientation === 'horizontal' ? scrollEl.scrollLeft : scrollEl.scrollTop;
+    var totalDelta = last.pos - first.pos;
+    velocity.current = totalDelta / dt;
+    stopInertia();
+    rafId.current = requestAnimationFrame(tick);
+  }, [enabled, orientation, getScrollContainer, stopInertia, tick]);
+  return {
+    onPointerDown: onPointerDown,
+    onPointerMove: onPointerMove,
+    onPointerUp: onPointerUp,
+    stopInertia: stopInertia
+  };
+}

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/useRealtime.js

@@ -0,0 +1,16 @@
+import { useEffect } from 'react';
+import dayjs from 'dayjs';
+/**
+ * Realtime 模式：每秒将当前系统时间通过 onTick 回传
+ */
+export function useRealtime(enabled, onTick) {
+  useEffect(function () {
+    if (!enabled) return;
+    var id = setInterval(function () {
+      onTick(dayjs());
+    }, 1000);
+    return function () {
+      return clearInterval(id);
+    };
+  }, [enabled, onTick]);
+}

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

@@ -0,0 +1,27 @@
+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;
+    ticks: Dayjs[];
+    /** 时间转主轴偏移（px） */
+    timeToOffset: (t: Dayjs) => number;
+    /** 主轴偏移（px）转时间（最近刻度，用于刻度对齐） */
+    offsetToTime: (offset: number) => Dayjs | null;
+    /** 主轴偏移（px）转时间（连续插值，用于拖动时按分钟步长显示） */
+    offsetToTimeContinuous: (offset: number) => Dayjs | null;
+    /** 主轴总长度（px） */
+    totalLengthPx: number;
+}
+/**
+ * 时间轴刻度与时间↔像素换算
+ */
+export declare function useTimeAxis(options: UseTimeAxisOptions): TimeAxisState;

package/es/components/pisellTimeNavigator/hooks/useTimeAxis.js

@@ -0,0 +1,76 @@
+function _slicedToArray(arr, i) { return _arrayWithHoles(arr) || _iterableToArrayLimit(arr, i) || _unsupportedIterableToArray(arr, i) || _nonIterableRest(); }
+function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
+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";
+/**
+ * 时间轴刻度与时间↔像素换算
+ */
+export function useTimeAxis(options) {
+  var range = options.range,
+    stepMinutes = options.stepMinutes,
+    referenceDate = options.referenceDate,
+    orientation = options.orientation,
+    cellSizePx = options.cellSizePx;
+  return useMemo(function () {
+    var _getRangeBounds = getRangeBounds(range, referenceDate),
+      _getRangeBounds2 = _slicedToArray(_getRangeBounds, 2),
+      rangeStart = _getRangeBounds2[0],
+      rangeEnd = _getRangeBounds2[1];
+    var ticks = getTicks(rangeStart, rangeEnd, stepMinutes);
+    /**
+     * 仅当范围结束晚于最后一个刻度时（如全天 23:59）才多一格尾段，使最后一刻可滚到视口中心。
+     * 自定义范围如 08:00–20:00 的最后一格已是 20:00，不再多一格。
+     */
+    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;
+    /** 防止异常 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;
+    var timeToOffset = function timeToOffset(t) {
+      var diffMs = t.diff(rangeStart);
+      var diffMin = diffMs / (60 * 1000);
+      var index = diffMin / stepMinutes;
+      var px = dotOffsetPx + index * cellSizePx;
+      return Math.max(dotOffsetPx, Math.min(px, maxOffsetPx));
+    };
+    var offsetToTime = function offsetToTime(offset) {
+      var index = Math.round((offset - dotOffsetPx) / cellSizePx);
+      var tick = effectiveTicks[index];
+      return tick !== null && tick !== void 0 ? tick : null;
+    };
+
+    /** 偏移对应连续时间；横向以格点为中心，竖向以格顶为基准 */
+    var offsetToTimeContinuous = function offsetToTimeContinuous(offset) {
+      var index = (offset - dotOffsetPx) / cellSizePx;
+      var minutesFromStart = index * stepMinutes;
+      var t = rangeStart.add(minutesFromStart, 'minute');
+      if (t.isBefore(rangeStart)) return rangeStart;
+      if (t.isAfter(rangeEnd)) return rangeEnd;
+      return t;
+    };
+    return {
+      rangeStart: rangeStart,
+      rangeEnd: rangeEnd,
+      ticks: effectiveTicks,
+      timeToOffset: timeToOffset,
+      offsetToTime: offsetToTime,
+      offsetToTimeContinuous: offsetToTimeContinuous,
+      totalLengthPx: totalLengthPx
+    };
+  }, [range === null || range === void 0 ? void 0 : range.start, range === null || range === void 0 ? void 0 : range.end, stepMinutes, referenceDate.valueOf(), orientation, cellSizePx]);
+}

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

@@ -0,0 +1,5 @@
+export { PisellTimeNavigator } from './PisellTimeNavigator';
+export { getHorizontalAxisSlotCount, getRangeBounds } 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/index.js

@@ -0,0 +1,4 @@
+export { PisellTimeNavigator } from "./PisellTimeNavigator";
+export { getHorizontalAxisSlotCount, getRangeBounds } from "./utils";
+/** 多语言文案（en / zh-CN / zh-HK / ja / pt），使用前请在应用内通过 locales.init(pisellTimeNavigatorLocales, lang) 合并 */
+export { default as pisellTimeNavigatorLocales } from "./locales";

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/locales.js

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

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

@@ -0,0 +1,160 @@
+import type { CSSProperties, ReactNode } from 'react';
+import type { Dayjs } from 'dayjs';
+/**
+ * value / defaultValue 的 dayjs 兼容类型（组件内部统一为 Dayjs）
+ */
+export declare type TimeNavigatorValue = Dayjs | string | null;
+/**
+ * 时间范围（HH:mm 或 HH:mm:ss，相对 referenceDate 的营业日）
+ * - 同自然日：如 08:00–22:00
+ * - 跨日：结束钟面 ≤ 开始时视为次日结束，如 02:01–02:00 表示至次日 02:00
+ */
+export interface TimeRangeOption {
+    start: string;
+    end: string;
+}
+/**
+ * 拖动/指示器模式
+ * - axis-moves：指示器固定视口中央，刻度移动（默认）
+ * - cursor-moves：刻度固定，指示器在轴上移动
+ */
+export declare type CursorMode = 'axis-moves' | 'cursor-moves';
+/**
+ * 布局方向
+ */
+export declare type TimeNavigatorOrientation = 'horizontal' | 'vertical';
+/**
+ * PisellTimeNavigator 组件 Props
+ */
+export interface PisellTimeNavigatorProps {
+    /**
+     * 当前选中时间（受控）。支持 dayjs 实例或可被 dayjs 解析的字符串
+     */
+    value?: TimeNavigatorValue;
+    /**
+     * 时间变更回调（受控时必传）
+     */
+    onChange?: (value: Dayjs) => void;
+    /**
+     * 默认选中时间（非受控）
+     */
+    defaultValue?: TimeNavigatorValue;
+    /**
+     * 时间轴锚定到的日历日（startOf day）。`range` 的 HH:mm 均相对于该日。
+     * 不传则与历史一致：取「当天」0 点，避免跨天后刻度错位。
+     */
+    referenceDate?: TimeNavigatorValue;
+    /**
+     * 是否 Realtime 模式：value 自动跟随系统当前时间更新
+     * @default false
+     */
+    realtime?: boolean;
+    /**
+     * 时间范围（支持跨日营业，见 {@link TimeRangeOption}）。不传则默认当日 00:00–24:00
+     */
+    range?: TimeRangeOption;
+    /**
+     * 吸附步长（分钟），如 15、30、60
+     * @default 15
+     */
+    stepMinutes?: number;
+    /**
+     * 大刻度间隔（分钟），用于整点刻度；不传则与 stepMinutes 一致或 60
+     * @default 60
+     */
+    majorStepMinutes?: number;
+    /**
+     * 指示器/轴移动模式
+     * @default 'axis-moves'
+     */
+    cursorMode?: CursorMode;
+    /**
+     * 横向或竖向展示
+     * @default 'horizontal'
+     */
+    orientation?: TimeNavigatorOrientation;
+    /**
+     * 营业时间范围（视觉高亮，可选限制选择范围）
+     */
+    businessHours?: TimeRangeOption;
+    /**
+     * 禁用时间段，禁止选中（点击/吸附到该区间无效）
+     */
+    disabledRanges?: TimeRangeOption[];
+    /**
+     * 是否显示 Now 按钮（固定入口）
+     * @default true
+     */
+    showNowButton?: boolean;
+    /**
+     * 为 true 时禁止用户拖动/滚动时间轴、点击刻度改时间（仍随 `value` 程序性对齐视口；用于「跟随当前时刻」等只读轴）
+     * @default false
+     */
+    userInteractionLocked?: boolean;
+    /**
+     * 是否吸附到 step 刻度
+     * @default false
+     */
+    snapToStep?: boolean;
+    /**
+     * 是否开启惯性滚动（拖动松手后减速）
+     * @default false
+     */
+    inertia?: boolean;
+    /**
+     * 过去时间淡化背景色（CSS 颜色值）
+     */
+    pastTimeFade?: string;
+    /**
+     * 容器样式覆盖
+     */
+    containerStyle?: CSSProperties;
+    /**
+     * 刻度层样式覆盖
+     */
+    scaleStyle?: CSSProperties;
+    /**
+     * 时间气泡/竖线样式覆盖（区分 realtime 时由组件内部应用主题色）
+     */
+    cursorStyle?: CSSProperties;
+    /**
+     * Now 按钮样式覆盖
+     */
+    nowButtonStyle?: CSSProperties;
+    /**
+     * 自定义类名
+     */
+    className?: string;
+    /**
+     * 根节点自定义样式
+     */
+    style?: CSSProperties;
+    /**
+     * dayjs locale
+     */
+    locale?: string;
+    /**
+     * 时间气泡展示格式（dayjs format）
+     * @default 'HH:mm'
+     */
+    timeFormat?: string;
+    /**
+     * 自定义 Now 按钮内容（覆盖默认文案与图标时使用）
+     */
+    renderNowButton?: () => ReactNode;
+    /**
+     * 横向轴上与刻度槽位数一致的密度序列（任意正数，内部按最大值归一化折线高度）
+     */
+    densitySeries?: number[];
+    /**
+     * 未传 `densitySeries` 时按 `referenceDate` 拉取；日历日变更会重新请求，过期响应丢弃
+     */
+    loadDensity?: (params: {
+        referenceDate: Dayjs;
+        stepMinutes: number;
+    }) => Promise<number[]>;
+    /**
+     * 用户开始操作时间轴（拖轴、点刻度、键盘、拖指针等）时回调；用于上层关闭「跟随当前」等。
+     */
+    onUserInteraction?: () => void;
+}

package/es/components/pisellTimeNavigator/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,30 @@
+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;
+/**
+ * 将 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）
+ */
+export declare function getTicks(rangeStart: Dayjs, rangeEnd: Dayjs, stepMinutes: number): Dayjs[];
+/**
+ * 横向时间轴「格」数量，与 useTimeAxis 中 totalLengthPx 算法一致（含尾格）
+ */
+export declare function getHorizontalAxisSlotCount(range: TimeRangeOption | undefined, referenceDate: Dayjs, stepMinutes: number): number;