@taskctrl/canvas-timeline 0.8.0 → 0.10.0

package/dist/core/HitTest.d.ts

@@ -19,3 +19,18 @@ export declare function resolveCanResize(item: Item, globalCanResize: false | 'l
  * falling through to the global value.
  */
 export declare function resolveCanMove(item: Item, globalCanMove: boolean): boolean;
+/**
+ * Decide which interaction (if any) a pointer-down at `edge` should start for
+ * `item`, given the timeline-wide `canResize`/`canMove` props. Returns `null`
+ * when nothing is permitted — the caller then starts no interaction (no ghost)
+ * and shows no affordance (default cursor). Centralising this keeps the cursor
+ * and the interaction decision in lockstep.
+ *
+ * An item explicitly resize-locked per-item (`item.canResize === false`) has
+ * inert edges: grabbing an edge returns `null` rather than falling through to a
+ * move, so a user trying to resize a locked item sees no UI. This is scoped to
+ * the *explicit* per-item override — an item inheriting a global `canResize:
+ * false` (field undefined) keeps the move-only behaviour where the whole item,
+ * edges included, is draggable.
+ */
+export declare function resolveInteractionMode(item: Item, edge: 'left' | 'right' | 'body', globalCanResize: false | 'left' | 'right' | 'both', globalCanMove: boolean): 'move' | 'resize-left' | 'resize-right' | null;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { Group, Item, ItemBounds, ItemState, DrawHelpers, CanvasItemRenderer, CanvasGroupItemRenderer, DayStyle, RowStyle, Dependency, TimeRangeHighlight, TimelineTheme, MarkerConfig, 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

@@ -0,0 +1,27 @@
+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';
+import type { InteractionState } from './InteractionHandler';
+/** The subset of props the snap helpers need. */
+export interface SnapDeps {
+    canvasWidth: number;
+    dragSnap?: number | DragSnapFn;
+    timezone?: string;
+    intervalTree: IntervalTree<Item>;
+    hierarchyEngine: HierarchyEngine;
+}
+/** Snapped new start time for a move, matching the pointer-up commit path:
+ *  item-edge snap (start edge first, then end edge) with grid snap as fallback. */
+export declare function snappedMoveStart(state: InteractionState, vs: ViewState, p: SnapDeps): number;
+/** Snapped edge time for a resize, matching the pointer-up commit path: item-edge
+ *  snap with grid-snap fallback, then hierarchy resize constraints. */
+export declare function snappedResizeEdge(state: InteractionState, vs: ViewState, p: SnapDeps): {
+    edge: 'left' | 'right';
+    time: number;
+};
+/** Build the public InteractionInfo payload for the current drag/resize state. */
+export declare function buildInteractionInfo(state: InteractionState, vs: ViewState, p: SnapDeps, pointer: {
+    x: number;
+    y: number;
+}): InteractionInfo;

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

@@ -107,6 +107,60 @@ export interface MarkerConfig {
     width: number;
     label?: string;
 }
+/** Live state of an in-progress drag/resize, emitted via `onInteractionUpdate`.
+ *  All times are the snapped values that will commit on drop (item-edge snap +
+ *  grid snap, plus hierarchy resize constraints) — i.e. where the item will
+ *  actually land, matching the snap guide. The consumer-supplied
+ *  `moveResizeValidator` is NOT applied here (it may run per frame). */
+export interface InteractionInfo {
+    itemId: number;
+    mode: 'move' | 'resize-left' | 'resize-right';
+    /** Set for resize interactions; which edge is being dragged. */
+    edge?: 'left' | 'right';
+    /** The headline time to display: the new start for `move`/`resize-left`, the
+     *  new end for `resize-right`. */
+    time: number;
+    /** The item's snapped start time during this interaction. */
+    startTime: number;
+    /** The item's snapped end time during this interaction. */
+    endTime: number;
+    /** Pointer position in viewport coordinates (clientX/clientY), for
+     *  positioning a `position: fixed` tooltip without further math. */
+    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[];
@@ -122,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>;
@@ -148,6 +205,11 @@ export interface CanvasTimelineProps {
     /** Validate and optionally constrain move/resize. Return the (possibly modified) time. */
     moveResizeValidator?: (action: 'move' | 'resize', itemId: number, time: number, edge?: 'left' | 'right') => number;
     onItemHover?: (itemId: number | null, e: PointerEvent) => void;
+    /** Fires once per animation frame during an active drag/resize, then once with
+     *  `null` when it ends. Intended for a live "current time" tooltip. This is a
+     *  hot path: do NOT call setState here — mutate a ref'd DOM node's text/transform
+     *  directly so neither the library nor your app re-renders per frame. */
+    onInteractionUpdate?: (info: InteractionInfo | null) => void;
     onCanvasDoubleClick?: (groupId: number, time: number) => void;
     onCanvasContextMenu?: (groupId: number, time: number, e: PointerEvent) => void;
     onTimeChange?: (start: number, end: number) => void;

package/package.json

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