fabric 5.3.0 → 6.0.0-beta3

package/src/util/animation/AnimationBase.ts

@@ -0,0 +1,166 @@
+import { noop } from '../../constants';
+import { requestAnimFrame } from './AnimationFrameProvider';
+import { runningAnimations } from './AnimationRegistry';
+import { defaultEasing } from './easing';
+import {
+  AnimationState,
+  TAbortCallback,
+  TBaseAnimationOptions,
+  TEasingFunction,
+  TOnAnimationChangeCallback,
+} from './types';
+
+const defaultAbort = () => false;
+
+export abstract class AnimationBase<
+  T extends number | number[] = number | number[]
+> {
+  declare readonly startValue: T;
+  declare readonly endValue: T;
+  declare readonly duration: number;
+  declare readonly delay: number;
+
+  protected declare readonly byValue: T;
+  protected declare readonly easing: TEasingFunction<T>;
+
+  private declare readonly _onStart: VoidFunction;
+  private declare readonly _onChange: TOnAnimationChangeCallback<T, void>;
+  private declare readonly _onComplete: TOnAnimationChangeCallback<T, void>;
+  private declare readonly _abort: TAbortCallback<T>;
+
+  /**
+   * Used to register the animation to a target object
+   * so that it can be cancelled within the object context
+   */
+  declare readonly target?: unknown;
+
+  private _state: AnimationState = 'pending';
+  /**
+   * Time %, or the ratio of `timeElapsed / duration`
+   * @see tick
+   */
+  durationProgress = 0;
+  /**
+   * Value %, or the ratio of `(currentValue - startValue) / (endValue - startValue)`
+   */
+  valueProgress = 0;
+  /**
+   * Current value
+   */
+  declare value: T;
+  /**
+   * Animation start time ms
+   */
+  private declare startTime: number;
+
+  constructor({
+    startValue,
+    byValue,
+    duration = 500,
+    delay = 0,
+    easing = defaultEasing,
+    onStart = noop,
+    onChange = noop,
+    onComplete = noop,
+    abort = defaultAbort,
+    target,
+  }: TBaseAnimationOptions<T>) {
+    this.tick = this.tick.bind(this);
+
+    this.duration = duration;
+    this.delay = delay;
+    this.easing = easing;
+    this._onStart = onStart;
+    this._onChange = onChange;
+    this._onComplete = onComplete;
+    this._abort = abort;
+    this.target = target;
+
+    this.startValue = startValue;
+    this.byValue = byValue;
+    this.value = this.startValue;
+    this.endValue = Object.freeze(this.calculate(this.duration).value);
+  }
+
+  get state() {
+    return this._state;
+  }
+
+  isDone() {
+    return this._state === 'aborted' || this._state === 'completed';
+  }
+
+  /**
+   * Calculate the current value based on the easing parameters
+   * @param timeElapsed in ms
+   * @protected
+   */
+  protected abstract calculate(timeElapsed: number): {
+    value: T;
+    valueProgress: number;
+  };
+
+  start() {
+    const firstTick: FrameRequestCallback = (timestamp) => {
+      if (this._state !== 'pending') return;
+      this.startTime = timestamp || +new Date();
+      this._state = 'running';
+      this._onStart();
+      this.tick(this.startTime);
+    };
+
+    this.register();
+
+    // setTimeout(cb, 0) will run cb on the next frame, causing a delay
+    // we don't want that
+    if (this.delay > 0) {
+      setTimeout(() => requestAnimFrame(firstTick), this.delay);
+    } else {
+      requestAnimFrame(firstTick);
+    }
+  }
+
+  private tick(t: number) {
+    const durationMs = (t || +new Date()) - this.startTime;
+    const boundDurationMs = Math.min(durationMs, this.duration);
+    this.durationProgress = boundDurationMs / this.duration;
+    const { value, valueProgress } = this.calculate(boundDurationMs);
+    this.value = Object.freeze(value);
+    this.valueProgress = valueProgress;
+
+    if (this._state === 'aborted') {
+      return;
+    } else if (
+      this._abort(this.value, this.valueProgress, this.durationProgress)
+    ) {
+      this._state = 'aborted';
+      this.unregister();
+    } else if (durationMs >= this.duration) {
+      this.durationProgress = this.valueProgress = 1;
+      this._onChange(this.endValue, this.valueProgress, this.durationProgress);
+      this._state = 'completed';
+      this._onComplete(
+        this.endValue,
+        this.valueProgress,
+        this.durationProgress
+      );
+      this.unregister();
+    } else {
+      this._onChange(this.value, this.valueProgress, this.durationProgress);
+      requestAnimFrame(this.tick);
+    }
+  }
+
+  private register() {
+    runningAnimations.push(this as unknown as AnimationBase);
+  }
+
+  private unregister() {
+    runningAnimations.remove(this as unknown as AnimationBase);
+  }
+
+  abort() {
+    this._state = 'aborted';
+    this.unregister();
+  }
+}

package/src/util/animation/AnimationFrameProvider.ts

@@ -0,0 +1,9 @@
+import { getWindow } from '../../env';
+
+export function requestAnimFrame(callback: FrameRequestCallback): number {
+  return getWindow().requestAnimationFrame(callback);
+}
+
+export function cancelAnimFrame(handle: number): void {
+  return getWindow().cancelAnimationFrame(handle);
+}

package/src/util/animation/AnimationRegistry.ts

@@ -0,0 +1,58 @@
+import type { Canvas } from '../../canvas/Canvas';
+import type { FabricObject } from '../../shapes/Object/FabricObject';
+import type { AnimationBase } from './AnimationBase';
+
+/**
+ * Array holding all running animations
+ */
+class AnimationRegistry extends Array<AnimationBase> {
+  /**
+   * Remove a single animation using an animation context
+   * @param {AnimationBase} context
+   */
+  remove(context: AnimationBase) {
+    const index = this.indexOf(context);
+    index > -1 && this.splice(index, 1);
+  }
+
+  /**
+   * Cancel all running animations on the next frame
+   */
+  cancelAll() {
+    const animations = this.splice(0);
+    animations.forEach((animation) => animation.abort());
+    return animations;
+  }
+
+  /**
+   * Cancel all running animations attached to a Canvas on the next frame
+   * @param {Canvas} canvas
+   */
+  cancelByCanvas(canvas: Canvas) {
+    if (!canvas) {
+      return [];
+    }
+    const animations = this.filter(
+      (animation) =>
+        typeof animation.target === 'object' &&
+        (animation.target as FabricObject)?.canvas === canvas
+    );
+    animations.forEach((animation) => animation.abort());
+    return animations;
+  }
+
+  /**
+   * Cancel all running animations for target on the next frame
+   * @param target
+   */
+  cancelByTarget(target: AnimationBase['target']) {
+    if (!target) {
+      return [];
+    }
+    const animations = this.filter((animation) => animation.target === target);
+    animations.forEach((animation) => animation.abort());
+    return animations;
+  }
+}
+
+export const runningAnimations = new AnimationRegistry();

package/src/util/animation/ArrayAnimation.ts

@@ -0,0 +1,27 @@
+import { AnimationBase } from './AnimationBase';
+import { ArrayAnimationOptions } from './types';
+
+export class ArrayAnimation extends AnimationBase<number[]> {
+  constructor({
+    startValue = [0],
+    endValue = [100],
+    ...options
+  }: ArrayAnimationOptions) {
+    super({
+      ...options,
+      startValue,
+      byValue: endValue.map((value, i) => value - startValue[i]),
+    });
+  }
+  protected calculate(timeElapsed: number) {
+    const values = this.startValue.map((value, i) =>
+      this.easing(timeElapsed, value, this.byValue[i], this.duration, i)
+    );
+    return {
+      value: values,
+      valueProgress: Math.abs(
+        (values[0] - this.startValue[0]) / this.byValue[0]
+      ),
+    };
+  }
+}

package/src/util/animation/ColorAnimation.ts

@@ -0,0 +1,74 @@
+import { Color } from '../../color/Color';
+import { TRGBAColorSource } from '../../color/Color';
+import { halfPI } from '../../constants';
+import { capValue } from '../misc/capValue';
+import { AnimationBase } from './AnimationBase';
+import type {
+  ColorAnimationOptions,
+  TEasingFunction,
+  TOnAnimationChangeCallback,
+} from './types';
+
+const defaultColorEasing: TEasingFunction = (
+  timeElapsed,
+  startValue,
+  byValue,
+  duration
+) => {
+  const durationProgress = 1 - Math.cos((timeElapsed / duration) * halfPI);
+  return startValue + byValue * durationProgress;
+};
+
+const wrapColorCallback = <R>(
+  callback?: TOnAnimationChangeCallback<string, R>
+) =>
+  callback &&
+  ((rgba: TRGBAColorSource, valueProgress: number, durationProgress: number) =>
+    callback(new Color(rgba).toRgba(), valueProgress, durationProgress));
+
+export class ColorAnimation extends AnimationBase<TRGBAColorSource> {
+  constructor({
+    startValue,
+    endValue,
+    easing = defaultColorEasing,
+    onChange,
+    onComplete,
+    abort,
+    ...options
+  }: ColorAnimationOptions) {
+    const startColor = new Color(startValue).getSource();
+    const endColor = new Color(endValue).getSource();
+    super({
+      ...options,
+      startValue: startColor,
+      byValue: endColor.map(
+        (value, i) => value - startColor[i]
+      ) as TRGBAColorSource,
+      easing,
+      onChange: wrapColorCallback(onChange),
+      onComplete: wrapColorCallback(onComplete),
+      abort: wrapColorCallback(abort),
+    });
+  }
+  protected calculate(timeElapsed: number) {
+    const [r, g, b, a] = this.startValue.map((value, i) =>
+      this.easing(timeElapsed, value, this.byValue[i], this.duration, i)
+    ) as TRGBAColorSource;
+    const value = [
+      ...[r, g, b].map(Math.round),
+      capValue(0, a, 1),
+    ] as TRGBAColorSource;
+    return {
+      value,
+      valueProgress:
+        // to correctly calculate the change ratio we must find a changed value
+        value
+          .map((p, i) =>
+            this.byValue[i] !== 0
+              ? Math.abs((p - this.startValue[i]) / this.byValue[i])
+              : 0
+          )
+          .find((p) => p !== 0) || 0,
+    };
+  }
+}

package/src/util/animation/ValueAnimation.ts

@@ -0,0 +1,29 @@
+import { AnimationBase } from './AnimationBase';
+import { ValueAnimationOptions } from './types';
+
+export class ValueAnimation extends AnimationBase<number> {
+  constructor({
+    startValue = 0,
+    endValue = 100,
+    ...otherOptions
+  }: ValueAnimationOptions) {
+    super({
+      ...otherOptions,
+      startValue,
+      byValue: endValue - startValue,
+    });
+  }
+
+  protected calculate(timeElapsed: number) {
+    const value = this.easing(
+      timeElapsed,
+      this.startValue,
+      this.byValue,
+      this.duration
+    );
+    return {
+      value,
+      valueProgress: Math.abs((value - this.startValue) / this.byValue),
+    };
+  }
+}

package/src/util/animation/animate.ts

@@ -0,0 +1,74 @@
+import { ValueAnimation } from './ValueAnimation';
+import { ArrayAnimation } from './ArrayAnimation';
+import { ColorAnimation } from './ColorAnimation';
+import {
+  ValueAnimationOptions,
+  ArrayAnimationOptions,
+  ColorAnimationOptions,
+} from './types';
+import { TColorArg } from '../../color/Color';
+
+export type TAnimation<T extends number | number[] | TColorArg> =
+  T extends TColorArg
+    ? ColorAnimation
+    : T extends number[]
+    ? ArrayAnimation
+    : ValueAnimation;
+
+const isArrayAnimation = (
+  options: ArrayAnimationOptions | ValueAnimationOptions
+): options is ArrayAnimationOptions => {
+  return Array.isArray(options.startValue) || Array.isArray(options.endValue);
+};
+
+/**
+ * Changes value(s) from startValue to endValue within a certain period of time,
+ * invoking callbacks as the value(s) change.
+ *
+ * @example
+ * animate({
+ *   startValue: 1,
+ *   endValue: 0,
+ *   onChange: (v) => {
+ *     obj.set('opacity', v);
+ *     // since we are running in a requested frame we should call `renderAll` and not `requestRenderAll`
+ *     canvas.renderAll();
+ *   }
+ * });
+ *
+ * @example Using lists:
+ * animate({
+ *   startValue: [1, 2, 3],
+ *   endValue: [2, 4, 6],
+ *   onChange: ([x, y, zoom]) => {
+ *     canvas.zoomToPoint(new Point(x, y), zoom);
+ *     canvas.renderAll();
+ *   }
+ * });
+ *
+ */
+export function animate(options: ArrayAnimationOptions): ArrayAnimation;
+export function animate(options: ValueAnimationOptions): ValueAnimation;
+export function animate<
+  T extends ValueAnimationOptions | ArrayAnimationOptions
+>(
+  options: T
+): T extends ArrayAnimationOptions ? ArrayAnimation : ValueAnimation;
+export function animate<
+  T extends ValueAnimationOptions | ArrayAnimationOptions,
+  R extends T extends ArrayAnimationOptions ? ArrayAnimation : ValueAnimation
+>(options: T): R {
+  const animation = (
+    isArrayAnimation(options)
+      ? new ArrayAnimation(options)
+      : new ValueAnimation(options)
+  ) as R;
+  animation.start();
+  return animation;
+}
+
+export function animateColor(options: ColorAnimationOptions) {
+  const animation = new ColorAnimation(options);
+  animation.start();
+  return animation;
+}