@flowgram-vue/core 0.2.0

package/src/core/utils/playground-gesture.spec.ts

@@ -0,0 +1,135 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+
+import { PlaygroundGesture } from './playground-gesture';
+
+vi.mock('@use-gesture/vanilla', () => {
+  class Gesture {}
+  return {
+    Gesture,
+  };
+});
+
+describe('PlaygroundGesture', () => {
+  const el = document.createElement('div');
+  const playgroundGesture = new PlaygroundGesture(el, {
+    config: {
+      minZoom: 0.4,
+      maxZoom: 2.2,
+      resolution: 1,
+    },
+  } as any);
+  it('getScaleBounds', () => {
+    expect(playgroundGesture.getScaleBounds()).toEqual({
+      min: 0.4,
+      max: 2.2,
+    });
+  });
+  it('pinching', () => {
+    expect(playgroundGesture.pinching).toBeFalsy();
+  });
+});
+
+describe('PlaygroundGesture', () => {
+  let el: HTMLElement;
+  let config: any;
+  let playgroundGesture: PlaygroundGesture;
+
+  beforeEach(() => {
+    el = document.createElement('div');
+    config = {
+      config: {
+        minZoom: 0.4,
+        maxZoom: 2.2,
+        resolution: 1,
+        scrollX: 0,
+        scrollY: 0,
+      },
+      finalScale: 1,
+      getPosFromMouseEvent: vi.fn().mockReturnValue({ x: 50, y: 50 }),
+      updateConfig: vi.fn(),
+    };
+    playgroundGesture = new PlaygroundGesture(el, config);
+  });
+
+  describe('PlaygroundGesture handlePinch', () => {
+    it('should not update config when newScale is NaN', () => {
+      playgroundGesture.handlePinch({
+        first: true,
+        last: false,
+        originX: 100,
+        originY: 100,
+        newScale: NaN,
+      });
+
+      expect(config.updateConfig).not.toHaveBeenCalled();
+    });
+
+    it('should set _pinching to true on first pinch', () => {
+      playgroundGesture.handlePinch({
+        first: true,
+        last: false,
+        originX: 100,
+        originY: 100,
+        newScale: 1.5,
+      });
+
+      expect(playgroundGesture.pinching).toBe(true);
+    });
+
+    it('should set _pinching to false on last pinch', () => {
+      playgroundGesture.handlePinch({
+        first: false,
+        last: true,
+        originX: 100,
+        originY: 100,
+        newScale: 1.5,
+      });
+
+      expect(playgroundGesture.pinching).toBe(false);
+    });
+
+    it('should call updateConfig with correct parameters', () => {
+      playgroundGesture.handlePinch({
+        first: false,
+        last: false,
+        originX: 100,
+        originY: 100,
+        newScale: 2,
+      });
+
+      expect(config.updateConfig).toHaveBeenCalledWith(
+        expect.objectContaining({
+          scrollX: expect.any(Number),
+          scrollY: expect.any(Number),
+          zoom: 2,
+        })
+      );
+    });
+
+    it('should calculate correct scroll values', () => {
+      config.getPosFromMouseEvent.mockReturnValue({ x: 100, y: 100 });
+      config.finalScale = 1;
+      config.config.scrollX = 0;
+      config.config.scrollY = 0;
+
+      playgroundGesture.handlePinch({
+        first: false,
+        last: false,
+        originX: 100,
+        originY: 100,
+        newScale: 2,
+      });
+
+      expect(config.updateConfig).toHaveBeenCalledWith({
+        scrollX: 100,
+        scrollY: 100,
+        zoom: 2,
+      });
+    });
+  });
+});

package/src/core/utils/playground-gesture.ts

@@ -0,0 +1,118 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Disposable, DisposableImpl } from '@flowgram-vue/utils';
+
+import { type PlaygroundConfigEntity } from '../layer/config/playground-config-entity';
+import { Gesture } from './use-gesture';
+
+/* istanbul ignore next */
+export class PlaygroundGesture extends DisposableImpl {
+  private _pinching = false;
+
+  constructor(
+    public readonly target: HTMLElement,
+    protected readonly config: PlaygroundConfigEntity
+  ) {
+    super();
+    this.preventDefault();
+    const gesture = new Gesture(
+      target,
+      {
+        // onDrag: ({pinching, cancel, offset: [x, y], ...rest}) => {
+        //   if (pinching) return cancel();
+        //   onChange({ ...style, x, y })
+        //   api.start({ x, y })
+        // },
+        onPinch: ({
+          origin: [originX, originY],
+          first,
+          last,
+          movement: [ms],
+          offset: [newScale, a],
+        }) => {
+          this.handlePinch({ first, last, originX, originY, newScale });
+        },
+      },
+      {
+        // drag: { from: () => [startState.x, startState.y] },
+        pinch: {
+          scaleBounds: () => this.getScaleBounds(),
+          from: () => [this.config.finalScale, 0],
+          /**
+           * 支持 command 和 ctrl
+           */
+          modifierKey: ['metaKey', 'ctrlKey'],
+          // rubberband: true
+        },
+      }
+    );
+    this.toDispose.push(
+      Disposable.create(() => {
+        gesture.destroy();
+      })
+    );
+  }
+
+  handlePinch(params: {
+    first: boolean;
+    last: boolean;
+    originX: number;
+    originY: number;
+    newScale: number;
+  }) {
+    const { first, last, originX, originY, newScale } = params;
+    if (Number.isNaN(params.newScale)) {
+      // 防止画布无法缩放
+      return;
+    }
+    if (first) {
+      this._pinching = true;
+    }
+    if (last) {
+      this._pinching = false;
+    }
+    const oldScale = this.config.finalScale;
+    const origin = this.config.getPosFromMouseEvent({ clientX: originX, clientY: originY }, false);
+    // 放大后的位置
+    const finalPos = {
+      x: (origin.x / oldScale) * newScale,
+      y: (origin.y / oldScale) * newScale,
+    };
+    this.config.updateConfig({
+      scrollX: this.config.config.scrollX + finalPos.x - origin.x,
+      scrollY: this.config.config.scrollY + finalPos.y - origin.y,
+      zoom: newScale,
+    });
+  }
+
+  getScaleBounds(): { min: number; max: number } {
+    return {
+      min: this.config.config.minZoom,
+      max: this.config.config.maxZoom,
+    };
+  }
+
+  protected preventDefault(): void {
+    // 阻止默认手势
+    const handler = (e: MouseEvent) => e.preventDefault();
+    // @ts-ignore
+    document.addEventListener('gesturestart', handler);
+    // @ts-ignore
+    document.addEventListener('gesturechange', handler);
+    this.toDispose.push(
+      Disposable.create(() => {
+        // @ts-ignore
+        document.removeEventListener('gesturestart', handler);
+        // @ts-ignore
+        document.removeEventListener('gesturechange', handler);
+      })
+    );
+  }
+
+  get pinching(): boolean {
+    return this._pinching;
+  }
+}

package/src/core/utils/tween.ts

@@ -0,0 +1,156 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import TWEEN from '@tweenjs/tween.js';
+import { Disposable } from '@flowgram-vue/utils';
+
+let started = 0;
+
+// Setup the animation loop.
+function startTweenLoop(): void {
+  started++;
+  function animate(time: number): void {
+    if (started <= 0) return;
+    requestAnimationFrame(animate);
+    TWEEN.update(time);
+  }
+  requestAnimationFrame(animate);
+}
+
+function stopTweenLoop(): void {
+  started--;
+}
+
+interface TweenValues {
+  [key: string]: number;
+}
+
+export interface TweenOpts<V> {
+  from: V;
+  to: V;
+  onUpdate?: (v: V) => void;
+  onComplete?: (v: V) => void;
+  onDispose?: (v: V) => void;
+  easing?: (num: number) => number;
+  duration: number;
+}
+
+export function startTween<V extends TweenValues = TweenValues>(opts: TweenOpts<V>): Disposable {
+  startTweenLoop();
+  let stopped = false;
+  const tween = new TWEEN.Tween(opts.from)
+    .to(opts.to, opts.duration)
+    .easing(opts.easing || TWEEN.Easing.Quadratic.Out)
+    .onUpdate(() => {
+      if (stopped) return;
+      if (opts.onUpdate) opts.onUpdate(opts.from);
+    })
+    .onComplete(() => {
+      if (stopped) return;
+      stopped = true;
+      stopTweenLoop();
+      if (opts.onComplete) opts.onComplete(opts.from);
+    })
+    .start();
+  return Disposable.create(() => {
+    if (stopped) return;
+    stopped = true;
+    stopTweenLoop();
+    tween.stop();
+    if (opts.onDispose) opts.onDispose(opts.from);
+  });
+}
+
+export interface ScrollIntoViewOpts {
+  getScrollParent(): HTMLElement | undefined;
+
+  getTargetNode(): HTMLElement | undefined;
+
+  duration?: number;
+  scrollY?: boolean; // 默认 true
+  scrollX?: boolean; // 默认 true
+}
+
+const defaultScrollIntoViewOpts = {
+  duration: 300,
+  scrollY: true,
+  scrollX: true,
+};
+
+const preTweenMap = new WeakMap<HTMLElement, Disposable>();
+
+/**
+ * 滚动到可视区域
+ * @param opts
+ */
+export function scrollIntoViewWithTween(opts: ScrollIntoViewOpts): Disposable {
+  opts = { ...defaultScrollIntoViewOpts, ...opts };
+  const parentNode = opts.getScrollParent();
+  const targetNode = opts.getTargetNode();
+  if (!parentNode || !targetNode) return Disposable.NULL;
+  // 销毁上一次的
+  if (preTweenMap.has(parentNode)) {
+    preTweenMap.get(parentNode)!.dispose();
+  }
+  const startScrollTop = parentNode.scrollTop;
+  const startScrollLeft = parentNode.scrollLeft;
+  let endScrollTop = startScrollTop;
+  let endScrollLeft = startScrollLeft;
+  const parentBound = parentNode.getBoundingClientRect();
+  const targetBound = targetNode.getBoundingClientRect();
+  const top = targetBound.top - parentBound.top + startScrollTop;
+  const left = targetBound.left - parentBound.left + startScrollLeft;
+  if (startScrollTop > top) {
+    endScrollTop = top;
+  } else {
+    const bottom = top + targetNode.clientHeight - parentNode.clientHeight;
+    if (startScrollTop < bottom && targetNode.clientHeight < parentNode.clientHeight) {
+      endScrollTop = bottom;
+    }
+  }
+  if (startScrollLeft > left) {
+    endScrollLeft = left;
+  } else {
+    const right = left + targetNode.clientWidth - parentNode.clientWidth;
+    if (startScrollLeft < right && targetNode.clientWidth < parentNode.clientWidth) {
+      endScrollLeft = right;
+    }
+  }
+  if (startScrollTop !== endScrollTop || startScrollLeft !== endScrollLeft) {
+    const from: { scrollTop?: number; scrollLeft?: number } = {};
+    const to: { scrollTop?: number; scrollLeft?: number } = {};
+    if (opts.scrollY) {
+      from.scrollTop = startScrollTop;
+      to.scrollTop = endScrollTop;
+    }
+    if (opts.scrollX) {
+      from.scrollLeft = startScrollLeft;
+      to.scrollLeft = endScrollLeft;
+    }
+    const scrollTween = startTween<{ scrollTop?: number; scrollLeft?: number }>({
+      from,
+      to,
+      onUpdate: v => {
+        if (v.scrollTop !== undefined) {
+          parentNode.scrollTop = v.scrollTop;
+        }
+        if (v.scrollLeft !== undefined) {
+          parentNode.scrollLeft = v.scrollLeft;
+        }
+      },
+      onComplete: () => {
+        toDispose.dispose();
+      },
+      duration: opts.duration!,
+    });
+    const toDispose = Disposable.create(() => {
+      scrollTween.dispose();
+      preTweenMap.delete(parentNode);
+    });
+    preTweenMap.set(parentNode, toDispose);
+    return toDispose;
+  }
+  return Disposable.NULL;
+}

package/src/core/utils/use-gesture/core/Controller.ts

@@ -0,0 +1,212 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { chain } from './utils/fn';
+import { isTouch, parseProp, toHandlerProp, touchIds } from './utils/events';
+import {
+  GestureKey,
+  InternalConfig,
+  InternalHandlers,
+  NativeHandlers,
+  State,
+  UserGestureConfig,
+} from './types';
+import { TimeoutStore } from './TimeoutStore';
+import { EventStore } from './EventStore';
+import { parse } from './config/resolver';
+import { EngineMap } from './actions';
+
+export class Controller {
+  /**
+   * The list of gestures handled by the Controller.
+   */
+  public gestures = new Set<GestureKey>();
+
+  /**
+   * The event store that keeps track of the config.target listeners.
+   */
+  private _targetEventStore = new EventStore(this);
+
+  /**
+   * Object that keeps track of all gesture event listeners.
+   */
+  public gestureEventStores: { [key in GestureKey]?: EventStore } = {};
+
+  public gestureTimeoutStores: { [key in GestureKey]?: TimeoutStore } = {};
+
+  public handlers: InternalHandlers = {};
+
+  private nativeHandlers?: NativeHandlers;
+
+  public config = {} as InternalConfig;
+
+  public pointerIds = new Set<number>();
+
+  public touchIds = new Set<number>();
+
+  public state = {
+    shared: {
+      shiftKey: false,
+      metaKey: false,
+      ctrlKey: false,
+      altKey: false,
+    },
+  } as State;
+
+  constructor(handlers: InternalHandlers) {
+    resolveGestures(this, handlers);
+  }
+
+  /**
+   * Sets pointer or touch ids based on the event.
+   * @param event
+   */
+  setEventIds(event: TouchEvent | PointerEvent) {
+    if (isTouch(event)) {
+      this.touchIds = new Set(touchIds(event as TouchEvent));
+      return this.touchIds;
+    } else if ('pointerId' in event) {
+      if (event.type === 'pointerup' || event.type === 'pointercancel')
+        this.pointerIds.delete(event.pointerId);
+      else if (event.type === 'pointerdown') this.pointerIds.add(event.pointerId);
+      return this.pointerIds;
+    }
+  }
+
+  /**
+   * Attaches handlers to the controller.
+   * @param handlers
+   * @param nativeHandlers
+   */
+  applyHandlers(handlers: InternalHandlers, nativeHandlers?: NativeHandlers) {
+    this.handlers = handlers;
+    this.nativeHandlers = nativeHandlers;
+  }
+
+  /**
+   * Compute and attaches a config to the controller.
+   * @param config
+   * @param gestureKey
+   */
+  applyConfig(config: UserGestureConfig, gestureKey?: GestureKey) {
+    this.config = parse(config, gestureKey, this.config);
+  }
+
+  /**
+   * Cleans all side effects (listeners, timeouts). When the gesture is
+   * destroyed (in React, when the component is unmounted.)
+   */
+  clean() {
+    this._targetEventStore.clean();
+    for (const key of this.gestures) {
+      this.gestureEventStores[key]!.clean();
+      this.gestureTimeoutStores[key]!.clean();
+    }
+  }
+
+  /**
+   * Executes side effects (attaching listeners to a `config.target`). Ran on
+   * each render.
+   */
+  effect() {
+    if (this.config.shared.target) this.bind();
+    return () => this._targetEventStore.clean();
+  }
+
+  /**
+   * The bind function that can be returned by the gesture handler (a hook in
+   * React for example.)
+   * @param args
+   */
+  bind(...args: any[]) {
+    const sharedConfig = this.config.shared;
+    const props: any = {};
+
+    let target;
+    if (sharedConfig.target) {
+      target = sharedConfig.target();
+      // if target is undefined let's stop
+      if (!target) return;
+    }
+
+    if (sharedConfig.enabled) {
+      // Adding gesture handlers
+      for (const gestureKey of this.gestures) {
+        const gestureConfig = this.config[gestureKey]!;
+        const bindFunction = bindToProps(props, gestureConfig.eventOptions, !!target);
+        if (gestureConfig.enabled) {
+          const Engine = EngineMap.get(gestureKey)!;
+          // @ts-ignore
+          new Engine(this, args, gestureKey).bind(bindFunction);
+        }
+      }
+
+      // Adding native handlers
+      const nativeBindFunction = bindToProps(props, sharedConfig.eventOptions, !!target);
+      for (const eventKey in this.nativeHandlers) {
+        nativeBindFunction(
+          eventKey,
+          '',
+          // @ts-ignore
+          event => this.nativeHandlers[eventKey]({ ...this.state.shared, event, args }),
+          undefined,
+          true,
+        );
+      }
+    }
+
+    // If target isn't set, we return an object that contains gesture handlers
+    // mapped to props handler event keys.
+    for (const handlerProp in props) {
+      props[handlerProp] = chain(...props[handlerProp]);
+    }
+
+    // When target isn't specified then return hanlder props.
+    if (!target) return props;
+
+    // When target is specified, then add listeners to the controller target
+    // store.
+    for (const handlerProp in props) {
+      const { device, capture, passive } = parseProp(handlerProp);
+      this._targetEventStore.add(target, device, '', props[handlerProp], { capture, passive });
+    }
+  }
+}
+
+function setupGesture(ctrl: Controller, gestureKey: GestureKey) {
+  ctrl.gestures.add(gestureKey);
+  ctrl.gestureEventStores[gestureKey] = new EventStore(ctrl, gestureKey);
+  ctrl.gestureTimeoutStores[gestureKey] = new TimeoutStore();
+}
+
+function resolveGestures(ctrl: Controller, internalHandlers: InternalHandlers) {
+  // make sure hover handlers are added first to prevent bugs such as #322
+  // where the hover pointerLeave handler is removed before the move
+  // pointerLeave, which prevents hovering: false to be fired.
+  if (internalHandlers.drag) setupGesture(ctrl, 'drag');
+  if (internalHandlers.wheel) setupGesture(ctrl, 'wheel');
+  if (internalHandlers.scroll) setupGesture(ctrl, 'scroll');
+  if (internalHandlers.move) setupGesture(ctrl, 'move');
+  if (internalHandlers.pinch) setupGesture(ctrl, 'pinch');
+  if (internalHandlers.hover) setupGesture(ctrl, 'hover');
+}
+
+const bindToProps =
+  (props: any, eventOptions: AddEventListenerOptions, withPassiveOption: boolean) =>
+  (
+    device: string,
+    action: string,
+    handler: (event: any) => void,
+    options: AddEventListenerOptions = {},
+    isNative = false,
+  ) => {
+    const capture = options.capture ?? eventOptions.capture;
+    const passive = options.passive ?? eventOptions.passive;
+    // a native handler is already passed as a prop like "onMouseDown"
+    let handlerProp = isNative ? device : toHandlerProp(device, action, capture);
+    if (withPassiveOption && passive) handlerProp += 'Passive';
+    props[handlerProp] = props[handlerProp] || [];
+    props[handlerProp].push(handler);
+  };

package/src/core/utils/use-gesture/core/EventStore.ts

@@ -0,0 +1,46 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { toDomEventType } from './utils/events';
+import { GestureKey } from './types';
+import type { Controller } from './Controller';
+
+export class EventStore {
+  private _listeners = new Set<() => void>();
+
+  private _ctrl: Controller;
+
+  private _gestureKey?: GestureKey;
+
+  constructor(ctrl: Controller, gestureKey?: GestureKey) {
+    this._ctrl = ctrl;
+    this._gestureKey = gestureKey;
+  }
+
+  add(
+    element: EventTarget,
+    device: string,
+    action: string,
+    handler: (event: any) => void,
+    options?: AddEventListenerOptions,
+  ) {
+    const listeners = this._listeners;
+    const type = toDomEventType(device, action);
+    const _options = this._gestureKey ? this._ctrl.config[this._gestureKey]!.eventOptions : {};
+    const eventOptions = { ..._options, ...options };
+    element.addEventListener(type, handler, eventOptions);
+    const remove = () => {
+      element.removeEventListener(type, handler, eventOptions);
+      listeners.delete(remove);
+    };
+    listeners.add(remove);
+    return remove;
+  }
+
+  clean() {
+    this._listeners.forEach(remove => remove());
+    this._listeners.clear(); // just for safety
+  }
+}

package/src/core/utils/use-gesture/core/TimeoutStore.ts

@@ -0,0 +1,28 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export class TimeoutStore {
+  private _timeouts = new Map<string, number>();
+
+  add<FunctionType extends (...args: any[]) => any>(
+    key: string,
+    callback: FunctionType,
+    ms = 140,
+    ...args: Parameters<FunctionType>
+  ) {
+    this.remove(key);
+    this._timeouts.set(key, window.setTimeout(callback, ms, ...args));
+  }
+
+  remove(key: string) {
+    const timeout = this._timeouts.get(key);
+    if (timeout) window.clearTimeout(timeout);
+  }
+
+  clean() {
+    this._timeouts.forEach(timeout => void window.clearTimeout(timeout));
+    this._timeouts.clear();
+  }
+}