@flowgram-vue/core 0.2.0

package/src/core/utils/use-gesture/core/types/config.ts

@@ -0,0 +1,255 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Vector2, Target, PointerType, NonUndefined } from './utils';
+import { State } from './state';
+
+export type GestureKey = Exclude<keyof State, 'shared'>;
+export type CoordinatesKey = Exclude<GestureKey, 'pinch'>;
+
+export type GenericOptions = {
+  /**
+   * Lets you specify a dom node or ref you want to attach the gesture to.
+   */
+  target?: Target;
+  /**
+   * Lets you specify which window element the gesture should bind events to
+   * (only relevant for the drag gesture).
+   */
+  window?: EventTarget;
+  /**
+   * Lets you customize if you want events to be passive or captured.
+   */
+  eventOptions?: AddEventListenerOptions;
+  /**
+   * When set to false none of the handlers will be fired.
+   */
+  enabled?: boolean;
+  /**
+   * A function that you can use to transform movement and offset values. Useful
+   * to map your screen coordinates to custom space coordinates such as a
+   * canvas.
+   */
+  transform?: (v: Vector2) => Vector2;
+};
+
+export type GestureOptions<T extends GestureKey> = GenericOptions & {
+  /**
+   * Whether the gesture is enabled.
+   */
+  enabled?: boolean;
+  /**
+   * Lets you customize if you want events to be passive or captured.
+   */
+  eventOptions?: AddEventListenerOptions;
+  /**
+   * The position `offset` will start from.
+   */
+  from?: Vector2 | ((state: NonUndefined<State[T]>) => Vector2);
+  /**
+   * The handler will fire only when the gesture displacement is greater than
+   * the threshold.
+   */
+  threshold?: number | Vector2;
+  /**
+   * The handler will preventDefault all events when `true`.
+   */
+  preventDefault?: boolean;
+  /**
+   * Forces the handler to fire even for non intentional displacement (ignores
+   * the threshold). In that case, the intentional attribute from state will
+   * remain false until the threshold is reached.
+   */
+  triggerAllEvents?: boolean;
+  /**
+   * The elasticity coefficient of the gesture when going out of bounds. When
+   * set to true, the elasticiy coefficient will be defaulted to 0.15
+   */
+  rubberband?: boolean | number | Vector2;
+  /**
+   * A function that you can use to transform movement and offset values. Useful
+   * to map your screen coordinates to custom space coordinates such as a
+   * canvas.
+   */
+  transform?: (v: Vector2) => Vector2;
+};
+
+export type Bounds = {
+  top?: number;
+  bottom?: number;
+  left?: number;
+  right?: number;
+};
+
+export type CoordinatesConfig<Key extends CoordinatesKey = CoordinatesKey> = GestureOptions<Key> & {
+  /**
+   * The handler will only trigger if a movement is detected on the specified
+   * axis.
+   */
+  axis?: 'x' | 'y' | 'lock';
+  /**
+   * Limits the gesture `offset` to the specified bounds.
+   */
+  bounds?: Bounds | ((state: State[Key]) => Bounds);
+  /**
+   * Determines the number of pixels in one direction needed for axises to be
+   * calculated.
+   */
+  axisThreshold?: number;
+};
+
+export type PinchBounds = { min?: number; max?: number };
+export type ModifierKey = 'ctrlKey' | 'altKey' | 'metaKey' | null;
+
+export type PinchConfig = GestureOptions<'pinch'> & {
+  pointer?: {
+    /**
+     * If true, pinch will use touch events on touch-enabled devices.
+     */
+    touch?: boolean;
+  };
+  /**
+   * Limits the scale `offset` to the specified bounds.
+   */
+  scaleBounds?: PinchBounds | ((state: State['pinch']) => PinchBounds);
+  /**
+   * Limits the angle `offset` to the specified bounds.
+   */
+  angleBounds?: PinchBounds | ((state: State['pinch']) => PinchBounds);
+  /**
+   * Scales OR rotates when set to 'lock'.
+   */
+  axis?: 'lock' | undefined;
+  /**
+   * Key that triggers scale when using the wheel. Defaults to `'ctrlKey'`.
+   */
+  modifierKey?: ModifierKey | NonNullable<ModifierKey>[];
+  /**
+   * Whether wheel should trigger a pinch at all.
+   */
+  pinchOnWheel?: boolean;
+};
+
+export type DragBounds = Bounds | HTMLElement | { current: HTMLElement | null };
+
+type MoveAndHoverMouseOnly = {
+  /**
+   * If false, onMove or onHover handlers will also fire on touch devices.
+   */
+  mouseOnly?: boolean;
+};
+
+export type MoveConfig = CoordinatesConfig<'move'> & MoveAndHoverMouseOnly;
+
+export type HoverConfig = MoveAndHoverMouseOnly;
+
+export type DragConfig = Omit<CoordinatesConfig<'drag'>, 'axisThreshold' | 'bounds'> & {
+  /**
+   * If true, the component won't trigger your drag logic if the user just clicked on the component.
+   */
+  filterTaps?: boolean;
+  /**
+   * The maximum total displacement a tap can have
+   */
+  tapsThreshold?: number;
+  /**
+   * Set this option to true when using with @react-three/fiber objects.
+   */
+  /**
+   * Limits the gesture `offset` to the specified bounds. Can be a ref or a dom
+   * node.
+   */
+  bounds?: DragBounds | ((state: State['drag']) => DragBounds);
+  pointer?: {
+    /**
+     * The buttons combination that would trigger the drag. Use `-1` to allow
+     * for any button combination to start the drag.
+     */
+    buttons?: number | number[];
+    /**
+     * If true, drag will use touch events on touch-enabled devices.
+     */
+    touch?: boolean;
+    /**
+     * If true, drag will use touch events on touch-enabled devices, and use
+     * mouse events on non touch devices.
+     */
+    mouse?: boolean;
+    /**
+     * If false, will disable KeyboardEvents that would otherwise trigger the
+     * drag gesture when the element is focused. Defaults to true.
+     */
+    keys?: boolean;
+    /**
+     * Doesn't use setPointerCapture when false and delegate drag handling to
+     * window
+     */
+    capture?: boolean;
+    /**
+     * Will perform a pointer lock when drag starts, and exit pointer lock when
+     * drag ends,
+     */
+    lock?: boolean;
+  };
+  swipe?: {
+    /**
+     * The minimum velocity per axis (in pixels / ms) the drag gesture needs to
+     * reach before the pointer is released.
+     */
+    velocity?: number | Vector2;
+    /**
+     * The minimum distance per axis (in pixels) the drag gesture needs to
+     * travel to trigger a swipe. Defaults to 50.
+     */
+    distance?: number | Vector2;
+    /**
+     * The maximum duration in milliseconds that a swipe is detected. Defaults
+     * to 250.
+     */
+    duration?: number;
+  };
+  /**
+   * If set, the drag will be triggered after the duration of the delay (in ms).
+   * When set to true, delay is defaulted to 250ms.
+   */
+  preventScroll?: boolean | number;
+  /**
+   * If set, the drag will allow scrolling in the direction of this axis until
+   * the preventScroll duration has elapsed. Defaults to only 'y'.
+   */
+  preventScrollAxis?: 'x' | 'y' | 'xy';
+  /**
+   * If set, the handler will be delayed for the duration of the delay (in ms)
+   * — or if the user starts moving. When set to true, delay is defaulted
+   * to 180ms.
+   */
+  delay?: boolean | number;
+  /**
+   * Key-number record that determines for each device (`'mouse'`, `'touch'`,
+   * `'pen'`) the number of pixels of drag in one direction needed for axises to
+   * be calculated.
+   */
+  axisThreshold?: Partial<Record<PointerType, number>>;
+  /**
+   * The distance (in pixels) emulated by arrow keys.
+   */
+  keyboardDisplacement?: number;
+};
+
+export type UserDragConfig = GenericOptions & DragConfig;
+export type UserPinchConfig = GenericOptions & PinchConfig;
+export type UserWheelConfig = GenericOptions & CoordinatesConfig<'wheel'>;
+export type UserScrollConfig = GenericOptions & CoordinatesConfig<'scroll'>;
+export type UserMoveConfig = GenericOptions & MoveConfig;
+export type UserHoverConfig = GenericOptions & HoverConfig;
+
+export type UserGestureConfig = GenericOptions & {
+  drag?: DragConfig;
+  wheel?: CoordinatesConfig<'wheel'>;
+  scroll?: CoordinatesConfig<'scroll'>;
+  move?: MoveConfig;
+  pinch?: PinchConfig;
+  hover?: { enabled?: boolean } & HoverConfig;
+};

package/src/core/utils/use-gesture/core/types/handlers.ts

@@ -0,0 +1,73 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { DOMHandlers, EventHandler } from './utils';
+import { FullGestureState, State, EventTypes } from './state';
+import { GestureKey } from './config';
+
+export type Handler<Key extends GestureKey, EventType = EventTypes[Key]> = (
+  state: Omit<FullGestureState<Key>, 'event'> & { event: EventType },
+) => any | void;
+
+// if no type is provided in the user generic for a given key
+// then return the default EventTypes that key
+type check<T extends AnyHandlerEventTypes, Key extends GestureKey> = undefined extends T[Key]
+  ? EventTypes[Key]
+  : T[Key];
+
+export type UserHandlers<T extends AnyHandlerEventTypes = EventTypes> = {
+  onDrag: Handler<'drag', check<T, 'drag'>>;
+  onDragStart: Handler<'drag', check<T, 'drag'>>;
+  onDragEnd: Handler<'drag', check<T, 'drag'>>;
+  onPinch: Handler<'pinch', check<T, 'pinch'>>;
+  onPinchStart: Handler<'pinch', check<T, 'pinch'>>;
+  onPinchEnd: Handler<'pinch', check<T, 'pinch'>>;
+  onWheel: Handler<'wheel', check<T, 'wheel'>>;
+  onWheelStart: Handler<'wheel', check<T, 'wheel'>>;
+  onWheelEnd: Handler<'wheel', check<T, 'wheel'>>;
+  onMove: Handler<'move', check<T, 'move'>>;
+  onMoveStart: Handler<'move', check<T, 'move'>>;
+  onMoveEnd: Handler<'move', check<T, 'move'>>;
+  onScroll: Handler<'scroll', check<T, 'scroll'>>;
+  onScrollStart: Handler<'scroll', check<T, 'scroll'>>;
+  onScrollEnd: Handler<'scroll', check<T, 'scroll'>>;
+  onHover: Handler<'hover', check<T, 'hover'>>;
+};
+
+type NativeHandlersKeys = keyof Omit<DOMHandlers, keyof UserHandlers>;
+
+type GetEventType<Key extends NativeHandlersKeys> = DOMHandlers[Key] extends
+  | EventHandler<infer EventType>
+  | undefined
+  ? EventType
+  : UIEvent;
+
+export type NativeHandlers<T extends AnyHandlerEventTypes = {}> = {
+  [key in NativeHandlersKeys]?: (
+    state: State['shared'] & {
+      event: undefined extends T[key] ? GetEventType<key> : T[key];
+      args: any;
+    },
+    ...args: any
+  ) => void;
+};
+
+// allows overriding the event type from the returned state in handlers
+export type AnyHandlerEventTypes = Partial<
+  {
+    drag: any;
+    wheel: any;
+    scroll: any;
+    move: any;
+    pinch: any;
+    hover: any;
+  } & { [key in NativeHandlersKeys]: any }
+>;
+
+export type GestureHandlers<HandlerType extends AnyHandlerEventTypes = EventTypes> = Partial<
+  NativeHandlers<HandlerType> & UserHandlers<HandlerType>
+>;
+
+export type InternalHandlers = { [Key in GestureKey]?: Handler<Key, any> };

package/src/core/utils/use-gesture/core/types/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './config';
+export * from './internalConfig';
+export * from './state';
+export * from './utils';
+export * from './handlers';
+export * from './action';

package/src/core/utils/use-gesture/core/types/internalConfig.ts

@@ -0,0 +1,80 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { PointerType, Vector2 } from './utils';
+import { State } from './state';
+import { GestureKey, CoordinatesKey, ModifierKey } from './config';
+
+export type InternalGenericOptions = {
+  target?: () => EventTarget;
+  eventOptions: AddEventListenerOptions;
+  window: EventTarget;
+  enabled: boolean;
+  transform?: (v: Vector2) => Vector2;
+};
+
+export type InternalGestureOptions<Key extends GestureKey = GestureKey> = {
+  enabled: boolean;
+  eventOptions: AddEventListenerOptions;
+  from: Vector2 | ((state: State[Key]) => Vector2);
+  threshold: Vector2;
+  preventDefault: boolean;
+  triggerAllEvents: boolean;
+  rubberband: Vector2;
+  bounds: [Vector2, Vector2] | ((state: State[Key]) => [Vector2, Vector2]);
+  hasCustomTransform: boolean;
+  transform: (v: Vector2) => Vector2;
+};
+
+export type InternalCoordinatesOptions<Key extends CoordinatesKey = CoordinatesKey> =
+  InternalGestureOptions<Key> & {
+    axis?: 'x' | 'y';
+    lockDirection: boolean;
+    axisThreshold: number;
+  };
+
+export type InternalDragOptions = Omit<InternalCoordinatesOptions<'drag'>, 'axisThreshold'> & {
+  filterTaps: boolean;
+  tapsThreshold: number;
+  pointerButtons: number | number[];
+  pointerCapture: boolean;
+  preventScrollDelay?: number;
+  preventScrollAxis?: 'x' | 'y' | 'xy';
+  pointerLock: boolean;
+  keys: boolean;
+  device: 'pointer' | 'touch' | 'mouse';
+  swipe: {
+    velocity: Vector2;
+    distance: Vector2;
+    duration: number;
+  };
+  delay: number;
+  axisThreshold: Record<PointerType, number>;
+  keyboardDisplacement: number;
+};
+
+export type InternalPinchOptions = InternalGestureOptions<'pinch'> & {
+  /**
+   * When device is undefined, we'll be using wheel to zoom.
+   */
+  device: 'gesture' | 'pointer' | 'touch' | undefined;
+  lockDirection: boolean;
+  modifierKey: ModifierKey | NonNullable<ModifierKey>[];
+  pinchOnWheel: boolean;
+};
+
+type MoveAndHoverMouseOnly = {
+  mouseOnly: boolean;
+};
+
+export type InternalConfig = {
+  shared: InternalGenericOptions;
+  drag?: InternalDragOptions;
+  wheel?: InternalCoordinatesOptions<'wheel'>;
+  scroll?: InternalCoordinatesOptions<'scroll'>;
+  move?: InternalCoordinatesOptions<'move'> & MoveAndHoverMouseOnly;
+  hover?: InternalCoordinatesOptions<'hover'> & MoveAndHoverMouseOnly;
+  pinch?: InternalPinchOptions;
+};

package/src/core/utils/use-gesture/core/types/state.ts

@@ -0,0 +1,275 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { NonUndefined, Vector2, WebKitGestureEvent } from './utils';
+import { GestureKey } from './config';
+
+export type IngKey = 'dragging' | 'wheeling' | 'moving' | 'hovering' | 'scrolling' | 'pinching';
+
+export type SharedGestureState = {
+  /**
+   * True if the element is being dragged.
+   */
+  dragging?: boolean;
+  /**
+   * True if the element is being wheeled.
+   */
+  wheeling?: boolean;
+  /**
+   * True if the element is being moved.
+   */
+  moving?: boolean;
+  /**
+   * True if the element is being hovered.
+   */
+  hovering?: boolean;
+  /**
+   * True if the element is being scrolled.
+   */
+  scrolling?: boolean;
+  /**
+   * True if the element is being pinched.
+   */
+  pinching?: boolean;
+  /**
+   * Number of fingers touching the screen.
+   */
+  touches: number;
+  /**
+   * True when the main mouse button or touch is pressed.
+   */
+  pressed: boolean;
+  /**
+   * Alias for pressed.
+   */
+  down: boolean;
+  /**
+   * True if the document is in lock mode.
+   */
+  locked: boolean;
+  /**
+   * Indicates which buttons are pressed (https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/buttons).
+   */
+  buttons: number;
+  /**
+   * True when the Shift key is pressed.
+   */
+  shiftKey: boolean;
+  /**
+   * True when the Alt key is pressed.
+   */
+  altKey: boolean;
+  /**
+   * True when the Meta key is pressed.
+   */
+  metaKey: boolean;
+  /**
+   * True when the Control key is pressed.
+   */
+  ctrlKey: boolean;
+};
+
+export type CommonGestureState = {
+  _active: boolean;
+  _blocked: boolean;
+  _force: boolean;
+  _step: [false | number, false | number];
+  _movementBound: [false | number, false | number];
+  _values: Vector2;
+  _initial: Vector2;
+  _movement: Vector2;
+  _distance: Vector2;
+  _direction: Vector2;
+  _delta: Vector2;
+  _bounds: [Vector2, Vector2];
+  /**
+   * The event triggering the gesture.
+   */
+  event: UIEvent;
+  /**
+   * The event target.
+   */
+  target: EventTarget;
+  /**
+   * The event current target.
+   */
+  currentTarget: EventTarget;
+  /**
+   * True when the gesture is intentional (passed the threshold).
+   */
+  intentional: boolean;
+  /**
+   * Cumulative distance of the gesture. Deltas are summed with their absolute
+   * values.
+   */
+  distance: Vector2;
+  /**
+   * Displacement of the current gesture.
+   */
+  movement: Vector2;
+  /**
+   * Difference between the current movement and the previous movement.
+   */
+  delta: Vector2;
+  /**
+   * Cumulative displacements of all gestures (sum of all movements triggered
+   * by the handler)
+   */
+  offset: Vector2;
+  /**
+   * Offset when the gesture started.
+   */
+  lastOffset: Vector2;
+  /**
+   * Velocity vector.
+   */
+  velocity: Vector2;
+  /**
+   * Current raw values of the gesture. Can be coordinates or distance / angle
+   * depending on the gesture.
+   */
+  values: Vector2;
+  /**
+   * Raw values when the gesture started.
+   */
+  initial: Vector2;
+  /**
+   * Direction per axis. `-1` when going down, `1` when going up, `0` when still.
+   */
+  direction: Vector2;
+  /**
+   * Bound overflow per axis. `-1` when overflowing bounds to the left/top, `1` when overflowing bounds to the right/bottom.
+   */
+  overflow: Vector2;
+  /**
+   * True when it's the first event of the active gesture.
+   */
+  first: boolean;
+  /**
+   * True when it's the last event of the active gesture.
+   */
+  last: boolean;
+  /**
+   * True when the gesture is active.
+   */
+  active: boolean;
+  /**
+   * The timestamp (ms) of when the gesture started.
+   */
+  startTime: number;
+  /**
+   * The timestamp (ms) of the current event.
+   */
+  timeStamp: number;
+  /**
+   * Elapsed time (ms) of the current gesture.
+   */
+  elapsedTime: number;
+  /**
+   * Time delta (ms) with the previous event.
+   */
+  timeDelta: number;
+  /**
+   * Event type.
+   */
+  type: string;
+  /**
+   * Value returned by your handler on its previous run.
+   */
+  memo?: any;
+  /**
+   * The arguments passed to the bind function (only relevant in React when
+   * using `<div {...bind(someArgument)} />`)
+   */
+  args?: any;
+};
+
+export type CoordinatesState = CommonGestureState & {
+  /**
+   * The initial axis (x or y) of the gesture.
+   */
+  axis: 'x' | 'y' | undefined;
+  /**
+   * Pointer coordinates (alias to values)
+   */
+  xy: Vector2;
+};
+
+export type DragState = CoordinatesState & {
+  _pointerId?: number;
+  _pointerActive: boolean;
+  _keyboardActive: boolean;
+  _preventScroll: boolean;
+  _delayed: boolean;
+  /**
+   * True when the drag gesture has been canceled by the `cancel` function.
+   */
+  canceled: boolean;
+  /**
+   * Function that can be called to cancel the drag.
+   */
+  cancel(): void;
+  /**
+   * True if the drag gesture is recognized as a tap (ie when the displacement
+   * is lower than 3px per axis).
+   */
+  tap: boolean;
+  /**
+   * [swipeX, swipeY] is [0, 0] if no swipe detected, -1 or 1 otherwise.
+   */
+  swipe: Vector2;
+};
+
+export interface PinchState extends CommonGestureState {
+  _pointerEvents: Map<number, PointerEvent>;
+  _touchIds: [] | [number, number];
+  /**
+   * Distance and angle raw values (alias to values).
+   */
+  da: Vector2;
+  /**
+   * The initial axis (scale or angle) of the gesture.
+   */
+  axis: 'scale' | 'angle' | undefined;
+  /**
+   * Coordinates of the center of touch events, or the cursor when using wheel
+   * to pinch.
+   */
+  origin: Vector2;
+  /**
+   * The number of full rotation the current gesture has performed.
+   */
+  turns: number;
+  /**
+   * True when the pinch gesture has been canceled by the `cancel` function.
+   */
+  canceled: boolean;
+  /**
+   * Function that can be called to cancel the pinch.
+   */
+  cancel(): void;
+}
+
+export type EventTypes = {
+  drag: PointerEvent | TouchEvent | MouseEvent | KeyboardEvent;
+  wheel: WheelEvent;
+  scroll: UIEvent;
+  move: PointerEvent;
+  hover: PointerEvent;
+  pinch: PointerEvent | TouchEvent | WheelEvent | WebKitGestureEvent;
+};
+
+export interface State {
+  shared: SharedGestureState;
+  drag?: DragState & { event: EventTypes['drag'] };
+  wheel?: CoordinatesState & { event: EventTypes['wheel'] };
+  scroll?: CoordinatesState & { event: EventTypes['scroll'] };
+  move?: CoordinatesState & { event: EventTypes['move'] };
+  hover?: CoordinatesState & { event: EventTypes['hover'] };
+  pinch?: PinchState & { event: EventTypes['pinch'] };
+}
+
+export type FullGestureState<Key extends GestureKey> = SharedGestureState &
+  NonUndefined<State[Key]>;