@taskctrl/canvas-timeline 0.8.1 → 0.10.1

package/dist/dom/DateHeader.d.ts

@@ -1,5 +1,5 @@
 import type { TimelineTheme } from '../types';
-export type DateUnit = 'year' | 'month' | 'week' | 'day' | 'hour';
+export type DateUnit = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour';
 export interface DateHeaderProps {
     unit: DateUnit;
     visibleTimeStart?: number;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { Group, Item, ItemBounds, ItemState, DrawHelpers, CanvasItemRenderer, CanvasGroupItemRenderer, DayStyle, RowStyle, Dependency, TimeRangeHighlight, TimelineTheme, MarkerConfig, InteractionInfo, CanvasTimelineProps, CanvasTimelineRef, CaptureOptions, } from './types';
+export type { Group, Item, ItemBounds, ItemState, DrawHelpers, CanvasItemRenderer, CanvasGroupItemRenderer, DayStyle, RowStyle, Dependency, TimeRangeHighlight, TimelineTheme, MarkerConfig, InteractionInfo, DragSnapFn, DragSnapResult, DragSnapAnchor, CanvasTimelineProps, CanvasTimelineRef, CaptureOptions, } from './types';
 export { DEFAULT_THEME } from './types';
 export { CanvasTimeline } from './CanvasTimeline';
 export { HierarchyEngine } from './core/HierarchyEngine';

package/dist/interaction/InteractionHandler.d.ts

@@ -1,4 +1,4 @@
-import type { Item } from '../types';
+import type { Item, DragSnapFn } from '../types';
 export type InteractionMode = 'move' | 'resize-left' | 'resize-right';
 export interface InteractionState {
     item: Item;
@@ -15,7 +15,7 @@ export declare class InteractionHandler {
     private state;
     private dragSnap;
     private activated;
-    constructor(dragSnap: number);
+    constructor(dragSnap: number | DragSnapFn | undefined);
     startInteraction(item: Item, mode: InteractionMode, x: number, y: number): void;
     update(x: number, y: number): void;
     setCurrentGroup(groupId: string | number): void;

package/dist/interaction/interactionInfo.d.ts

@@ -1,4 +1,4 @@
-import type { Item, InteractionInfo } from '../types';
+import type { Item, InteractionInfo, DragSnapFn } from '../types';
 import type { ViewState } from '../core/ViewState';
 import type { IntervalTree } from '../core/IntervalTree';
 import type { HierarchyEngine } from '../core/HierarchyEngine';
@@ -6,7 +6,8 @@ import type { InteractionState } from './InteractionHandler';
 /** The subset of props the snap helpers need. */
 export interface SnapDeps {
     canvasWidth: number;
-    dragSnap: number;
+    dragSnap?: number | DragSnapFn;
+    timezone?: string;
     intervalTree: IntervalTree<Item>;
     hierarchyEngine: HierarchyEngine;
 }

package/dist/interaction/snapResolve.d.ts

@@ -0,0 +1,41 @@
+import type { Item, DragSnapFn, DragSnapResult } from '../types';
+/** Reset the once-per-session invalid-snap warning. Test-only. */
+export declare function _resetSnapWarning(): void;
+/**
+ * Resolve a `dragSnap` prop to a concrete snap spec for the given item/edge.
+ *
+ * - `undefined` → `1` (no snap).
+ * - `number` → returned as-is (preserves legacy behavior, including `0`).
+ * - `DragSnapFn` → invoked with `(item, edge)`. `edge` is `'left' | 'right'`
+ *   during a resize and `undefined` during a move. It may return either a bare
+ *   interval (ms) — tz-aware default anchoring (see {@link gridSnap}) — or a
+ *   `{ interval, anchor }` spec to control phase explicitly. An invalid return
+ *   (`interval` that is `0`, `NaN`, or negative, or a non-finite `anchor`) falls
+ *   back to `1` (no snap) and warns once per session.
+ *
+ * Hot path: called on every pointer-move frame. Returns the consumer's object
+ * by reference — no allocation or copying here.
+ */
+export declare function resolveDragSnap(dragSnap: number | DragSnapFn | undefined, item: Item, edge?: 'left' | 'right'): DragSnapResult;
+/**
+ * Snap `time` (epoch ms) to a snap grid.
+ *
+ * When `snap` is a `{ interval, anchor }` spec, the grid is `anchor + N *
+ * interval` and the `timezone` is ignored — the consumer owns the phase (see
+ * {@link DragSnapAnchor} for the DST caveat). This branch is pure arithmetic
+ * (no dayjs), so it is the cheapest path.
+ *
+ * When `snap` is a bare `number` interval:
+ * - For day-or-larger intervals with a `timezone`, the grid is anchored to
+ *   tz-local midnight rather than the UTC epoch, so the snap lands on the same
+ *   day boundaries the grid/headers render (which are also tz-local). Day
+ *   boundaries in a tz with a non-zero UTC offset are not multiples of
+ *   86_400_000 since the epoch, so a naive `Math.round(time / interval) *
+ *   interval` drifts by the offset. The snap is computed in local-calendar-day
+ *   space, so it stays correct across DST transitions (where a local day is 23
+ *   or 25 hours long).
+ * - Sub-day intervals (1h, 15min, …) stay UTC-anchored: hours and quarter-hours
+ *   line up between UTC and any whole- or fractional-hour offset, so no
+ *   translation is needed.
+ */
+export declare function gridSnap(time: number, snap: DragSnapResult, timezone?: string): number;

package/dist/interaction/snapUtils.d.ts

@@ -11,5 +11,5 @@ export declare function collectItemEdges(items: SnapItem[], excludeItemId: numbe
  * Find the best snap target from a list of edge X positions.
  * Returns the snapped X position if an edge is within threshold, or null to fall back to time-grid snap.
  */
-export declare function findSnapTarget(currentX: number, edgeXPositions: number[], thresholdPx: number, _pixelsPerMs: number, _dragSnap: number): number | null;
+export declare function findSnapTarget(currentX: number, edgeXPositions: number[], thresholdPx: number, _pixelsPerMs: number, _dragSnap: import('../types').DragSnapResult): number | null;
 export {};

package/dist/types.d.ts

@@ -129,6 +129,38 @@ export interface InteractionInfo {
     pointerX: number;
     pointerY: number;
 }
+/** Anchored snap grid: snap to `anchor + N * interval`. Returning this from a
+ *  {@link DragSnapFn} overrides the default tz-local-midnight anchoring — the
+ *  consumer is fully in charge of phase. */
+export interface DragSnapAnchor {
+    /** Snap interval in ms. Must be finite and `> 0`, else snapping is disabled
+     *  (falls back to no snap, one `console.warn` per session). */
+    interval: number;
+    /** Absolute epoch ms. The snap grid is built as
+     *  `anchor + N * interval`. Because `interval` is exact ms, the grid does
+     *  NOT track wall-clock hour across DST — at the spring-forward boundary the
+     *  snapped position will drift one hour from local time and stay drifted
+     *  until the next anchor reset. Consumers that need wall-clock-stable
+     *  snapping should re-pick an anchor on the DST side they care about.
+     *  The timeline's `timezone` prop is ignored when an anchor is supplied. */
+    anchor: number;
+}
+/** What a {@link DragSnapFn} may return: a bare interval (ms) — tz-aware
+ *  default anchoring — or an explicit `{ interval, anchor }` grid. */
+export type DragSnapResult = number | DragSnapAnchor;
+/**
+ * Per-drag snap resolver. Called on every pointer-move frame during a
+ * drag/resize, so keep it cheap — the library does not memoize the result.
+ *
+ * @param item The item being dragged/resized.
+ * @param edge `'left' | 'right'` during a resize; `undefined` during a move.
+ * @returns Either a snap interval in ms (varies only the *interval*; phase stays
+ *   grid-aligned to multiples of it — tz-local midnight for day-or-larger
+ *   intervals when `timezone` is set), or a {@link DragSnapAnchor} `{ interval,
+ *   anchor }` to also control phase (tz is ignored in that case). A `0`, `NaN`,
+ *   or negative `interval` (or non-finite `anchor`) falls back to no snap.
+ */
+export type DragSnapFn = (item: Item, edge?: 'left' | 'right') => DragSnapResult;
 export interface CanvasTimelineProps {
     groups: Group[];
     items: Item[];
@@ -144,7 +176,10 @@ export interface CanvasTimelineProps {
     canMove: boolean;
     canResize: false | 'left' | 'right' | 'both';
     canChangeGroup: boolean;
-    dragSnap: number;
+    /** Snap interval for drag/resize, in ms. A `number` snaps everything to that
+     *  interval; a {@link DragSnapFn} resolves the interval per item/edge. When
+     *  omitted, no snapping is applied. */
+    dragSnap?: number | DragSnapFn;
     minZoom: number;
     maxZoom: number;
     theme?: Partial<TimelineTheme>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taskctrl/canvas-timeline",
-  "version": "0.8.1",
+  "version": "0.10.1",
   "description": "High-performance canvas-based timeline component for React",
   "scripts": {
     "build": "rimraf ./dist && tsc && vite build",