fabric 5.3.0 → 6.0.0-beta10

package/src/util/misc/matrix.ts

@@ -0,0 +1,313 @@
+import { iMatrix } from '../../constants';
+import type { XY } from '../../Point';
+import { Point } from '../../Point';
+import type { TDegree, TRadian, TMat2D } from '../../typedefs';
+import { cos } from './cos';
+import { degreesToRadians, radiansToDegrees } from './radiansDegreesConversion';
+import { sin } from './sin';
+
+type TRotateMatrixArgs = {
+  angle?: TDegree;
+};
+
+type TTranslateMatrixArgs = {
+  translateX?: number;
+  translateY?: number;
+};
+
+export type TScaleMatrixArgs = {
+  scaleX?: number;
+  scaleY?: number;
+  flipX?: boolean;
+  flipY?: boolean;
+  skewX?: TDegree;
+  skewY?: TDegree;
+};
+
+export type TComposeMatrixArgs = TTranslateMatrixArgs &
+  TRotateMatrixArgs &
+  TScaleMatrixArgs;
+
+export type TQrDecomposeOut = Required<
+  Omit<TComposeMatrixArgs, 'flipX' | 'flipY'>
+>;
+
+export const isIdentityMatrix = (mat: TMat2D) =>
+  mat.every((value, index) => value === iMatrix[index]);
+
+/**
+ * Apply transform t to point p
+ * @param  {Point | XY} p The point to transform
+ * @param  {Array} t The transform
+ * @param  {Boolean} [ignoreOffset] Indicates that the offset should not be applied
+ * @return {Point} The transformed point
+ */
+export const transformPoint = (
+  p: XY,
+  t: TMat2D,
+  ignoreOffset?: boolean
+): Point => new Point(p).transform(t, ignoreOffset);
+
+/**
+ * Invert transformation t
+ * @param {Array} t The transform
+ * @return {Array} The inverted transform
+ */
+export const invertTransform = (t: TMat2D): TMat2D => {
+  const a = 1 / (t[0] * t[3] - t[1] * t[2]),
+    r = [a * t[3], -a * t[1], -a * t[2], a * t[0], 0, 0] as TMat2D,
+    { x, y } = new Point(t[4], t[5]).transform(r, true);
+  r[4] = -x;
+  r[5] = -y;
+  return r;
+};
+
+/**
+ * Multiply matrix A by matrix B to nest transformations
+ * @param  {TMat2D} a First transformMatrix
+ * @param  {TMat2D} b Second transformMatrix
+ * @param  {Boolean} is2x2 flag to multiply matrices as 2x2 matrices
+ * @return {TMat2D} The product of the two transform matrices
+ */
+export const multiplyTransformMatrices = (
+  a: TMat2D,
+  b: TMat2D,
+  is2x2?: boolean
+): TMat2D =>
+  [
+    a[0] * b[0] + a[2] * b[1],
+    a[1] * b[0] + a[3] * b[1],
+    a[0] * b[2] + a[2] * b[3],
+    a[1] * b[2] + a[3] * b[3],
+    is2x2 ? 0 : a[0] * b[4] + a[2] * b[5] + a[4],
+    is2x2 ? 0 : a[1] * b[4] + a[3] * b[5] + a[5],
+  ] as TMat2D;
+
+/**
+ * Multiplies {@link matrices} such that a matrix defines the plane for the rest of the matrices **after** it
+ *
+ * `multiplyTransformMatrixArray([A, B, C, D])` is equivalent to `A(B(C(D)))`
+ *
+ * @param matrices an array of matrices
+ * @param [is2x2] flag to multiply matrices as 2x2 matrices
+ * @returns the multiplication product
+ */
+export const multiplyTransformMatrixArray = (
+  matrices: (TMat2D | undefined | null | false)[],
+  is2x2?: boolean
+) =>
+  matrices.reduceRight(
+    (product: TMat2D, curr) =>
+      curr ? multiplyTransformMatrices(curr, product, is2x2) : product,
+    iMatrix
+  );
+
+/**
+ * Decomposes standard 2x3 matrix into transform components
+ * @param  {TMat2D} a transformMatrix
+ * @return {Object} Components of transform
+ */
+export const qrDecompose = (a: TMat2D): TQrDecomposeOut => {
+  const angle = Math.atan2(a[1], a[0]),
+    denom = Math.pow(a[0], 2) + Math.pow(a[1], 2),
+    scaleX = Math.sqrt(denom),
+    scaleY = (a[0] * a[3] - a[2] * a[1]) / scaleX,
+    skewX = Math.atan2(a[0] * a[2] + a[1] * a[3], denom);
+  return {
+    angle: radiansToDegrees(angle),
+    scaleX,
+    scaleY,
+    skewX: radiansToDegrees(skewX),
+    skewY: 0 as TDegree,
+    translateX: a[4] || 0,
+    translateY: a[5] || 0,
+  };
+};
+
+/**
+ * Generate a translation matrix
+ *
+ * A translation matrix in the form of
+ * [ 1 0 x ]
+ * [ 0 1 y ]
+ * [ 0 0 1 ]
+ *
+ * See @link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/transform#translate for more details
+ *
+ * @param {number} x translation on X axis
+ * @param {number} [y] translation on Y axis
+ * @returns {TMat2D} matrix
+ */
+export const createTranslateMatrix = (x: number, y = 0): TMat2D => [
+  1,
+  0,
+  0,
+  1,
+  x,
+  y,
+];
+
+/**
+ * Generate a rotation matrix around around a point (x,y), defaulting to (0,0)
+ *
+ * A matrix in the form of
+ * [cos(a) -sin(a) -x*cos(a)+y*sin(a)+x]
+ * [sin(a)  cos(a) -x*sin(a)-y*cos(a)+y]
+ * [0       0      1                 ]
+ *
+ *
+ * @param {TDegree} angle rotation in degrees
+ * @param {XY} [pivotPoint] pivot point to rotate around
+ * @returns {TMat2D} matrix
+ */
+export function createRotateMatrix(
+  { angle = 0 }: TRotateMatrixArgs = {},
+  { x = 0, y = 0 }: Partial<XY> = {}
+): TMat2D {
+  const angleRadiant = degreesToRadians(angle),
+    cosValue = cos(angleRadiant),
+    sinValue = sin(angleRadiant);
+  return [
+    cosValue,
+    sinValue,
+    -sinValue,
+    cosValue,
+    x ? x - (cosValue * x - sinValue * y) : 0,
+    y ? y - (sinValue * x + cosValue * y) : 0,
+  ];
+}
+
+/**
+ * Generate a scale matrix around the point (0,0)
+ *
+ * A matrix in the form of
+ * [x 0 0]
+ * [0 y 0]
+ * [0 0 1]
+ *
+ * @link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/transform#scale
+ *
+ * @param {number} x scale on X axis
+ * @param {number} [y] scale on Y axis
+ * @returns {TMat2D} matrix
+ */
+export const createScaleMatrix = (x: number, y: number = x): TMat2D => [
+  x,
+  0,
+  0,
+  y,
+  0,
+  0,
+];
+
+export const angleToSkew = (angle: TDegree) =>
+  Math.tan(degreesToRadians(angle));
+
+export const skewToAngle = (value: TRadian) =>
+  radiansToDegrees(Math.atan(value));
+
+/**
+ * Generate a skew matrix for the X axis
+ *
+ * A matrix in the form of
+ * [1 x 0]
+ * [0 1 0]
+ * [0 0 1]
+ *
+ * @link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/transform#skewx
+ *
+ * @param {TDegree} skewValue translation on X axis
+ * @returns {TMat2D} matrix
+ */
+export const createSkewXMatrix = (skewValue: TDegree): TMat2D => [
+  1,
+  0,
+  angleToSkew(skewValue),
+  1,
+  0,
+  0,
+];
+
+/**
+ * Generate a skew matrix for the Y axis
+ *
+ * A matrix in the form of
+ * [1 0 0]
+ * [y 1 0]
+ * [0 0 1]
+ *
+ * @link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/transform#skewy
+ *
+ * @param {TDegree} skewValue translation on Y axis
+ * @returns {TMat2D} matrix
+ */
+export const createSkewYMatrix = (skewValue: TDegree): TMat2D => [
+  1,
+  angleToSkew(skewValue),
+  0,
+  1,
+  0,
+  0,
+];
+
+/**
+ * Returns a transform matrix starting from an object of the same kind of
+ * the one returned from qrDecompose, useful also if you want to calculate some
+ * transformations from an object that is not enlived yet.
+ * is called DimensionsTransformMatrix because those properties are the one that influence
+ * the size of the resulting box of the object.
+ * @param  {Object} options
+ * @param  {Number} [options.scaleX]
+ * @param  {Number} [options.scaleY]
+ * @param  {Boolean} [options.flipX]
+ * @param  {Boolean} [options.flipY]
+ * @param  {Number} [options.skewX]
+ * @param  {Number} [options.skewY]
+ * @return {Number[]} transform matrix
+ */
+export const calcDimensionsMatrix = ({
+  scaleX = 1,
+  scaleY = 1,
+  flipX = false,
+  flipY = false,
+  skewX = 0 as TDegree,
+  skewY = 0 as TDegree,
+}: TScaleMatrixArgs) => {
+  return multiplyTransformMatrixArray(
+    [
+      createScaleMatrix(flipX ? -scaleX : scaleX, flipY ? -scaleY : scaleY),
+      skewX && createSkewXMatrix(skewX),
+      skewY && createSkewYMatrix(skewY),
+    ],
+    true
+  );
+};
+
+/**
+ * Returns a transform matrix starting from an object of the same kind of
+ * the one returned from qrDecompose, useful also if you want to calculate some
+ * transformations from an object that is not enlived yet
+ * @param  {Object} options
+ * @param  {Number} [options.angle]
+ * @param  {Number} [options.scaleX]
+ * @param  {Number} [options.scaleY]
+ * @param  {Boolean} [options.flipX]
+ * @param  {Boolean} [options.flipY]
+ * @param  {Number} [options.skewX]
+ * @param  {Number} [options.skewY]
+ * @param  {Number} [options.translateX]
+ * @param  {Number} [options.translateY]
+ * @return {Number[]} transform matrix
+ */
+export const composeMatrix = ({
+  translateX = 0,
+  translateY = 0,
+  angle = 0 as TDegree,
+  ...otherOptions
+}: TComposeMatrixArgs): TMat2D => {
+  return multiplyTransformMatrixArray([
+    createTranslateMatrix(translateX, translateY),
+    angle && createRotateMatrix({ angle }),
+    calcDimensionsMatrix(otherOptions),
+  ]);
+};

package/src/util/misc/mergeClipPaths.ts

@@ -0,0 +1,40 @@
+import type { FabricObject } from '../../shapes/Object/FabricObject';
+import { sendObjectToPlane } from './planeChange';
+import { Group } from '../../shapes/Group';
+/**
+ * Merges 2 clip paths into one visually equal clip path
+ *
+ * **IMPORTANT**:\
+ * Does **NOT** clone the arguments, clone them proir if necessary.
+ *
+ * Creates a wrapper (group) that contains one clip path and is clipped by the other so content is kept where both overlap.
+ * Use this method if both the clip paths may have nested clip paths of their own, so assigning one to the other's clip path property is not possible.
+ *
+ * In order to handle the `inverted` property we follow logic described in the following cases:\
+ * **(1)** both clip paths are inverted - the clip paths pass the inverted prop to the wrapper and loose it themselves.\
+ * **(2)** one is inverted and the other isn't - the wrapper shouldn't become inverted and the inverted clip path must clip the non inverted one to produce an identical visual effect.\
+ * **(3)** both clip paths are not inverted - wrapper and clip paths remain unchanged.
+ *
+ * @memberOf fabric.util
+ * @param {fabric.Object} c1
+ * @param {fabric.Object} c2
+ * @returns {fabric.Object} merged clip path
+ */
+export const mergeClipPaths = (c1: FabricObject, c2: FabricObject) => {
+  let a = c1,
+    b = c2;
+  if (a.inverted && !b.inverted) {
+    //  case (2)
+    a = c2;
+    b = c1;
+  }
+  //  `b` becomes `a`'s clip path so we transform `b` to `a` coordinate plane
+  sendObjectToPlane(b, b.group?.calcTransformMatrix(), a.calcTransformMatrix());
+  //  assign the `inverted` prop to the wrapping group
+  const inverted = a.inverted && b.inverted;
+  if (inverted) {
+    //  case (1)
+    a.inverted = b.inverted = false;
+  }
+  return new Group([a], { clipPath: b, inverted });
+};

package/src/util/misc/objectEnlive.ts

@@ -0,0 +1,174 @@
+import { noop } from '../../constants';
+import type { Pattern } from '../../Pattern';
+import type { FabricObject } from '../../shapes/Object/FabricObject';
+import type { Abortable, TCrossOrigin, TFiller } from '../../typedefs';
+import { createImage } from './dom';
+import { classRegistry } from '../../ClassRegistry';
+
+export type LoadImageOptions = Abortable & {
+  /**
+   * cors value for the image loading, default to anonymous
+   */
+  crossOrigin?: TCrossOrigin;
+};
+
+/**
+ * Loads image element from given url and resolve it, or catch.
+ * @param {String} url URL representing an image
+ * @param {LoadImageOptions} [options] image loading options
+ * @returns {Promise<HTMLImageElement>} the loaded image.
+ */
+export const loadImage = (
+  url: string,
+  { signal, crossOrigin = null }: LoadImageOptions = {}
+) =>
+  new Promise<HTMLImageElement>(function (resolve, reject) {
+    if (signal && signal.aborted) {
+      return reject(new Error('`options.signal` is in `aborted` state'));
+    }
+    const img = createImage();
+    let abort: EventListenerOrEventListenerObject;
+    if (signal) {
+      abort = function (err: Event) {
+        img.src = '';
+        reject(err);
+      };
+      signal.addEventListener('abort', abort, { once: true });
+    }
+    const done = function () {
+      img.onload = img.onerror = null;
+      abort && signal?.removeEventListener('abort', abort);
+      resolve(img);
+    };
+    if (!url) {
+      done();
+      return;
+    }
+    img.onload = done;
+    img.onerror = function () {
+      abort && signal?.removeEventListener('abort', abort);
+      reject(new Error('Error loading ' + img.src));
+    };
+    crossOrigin && (img.crossOrigin = crossOrigin);
+    img.src = url;
+  });
+
+export type EnlivenObjectOptions = Abortable & {
+  /**
+   * Method for further parsing of object elements,
+   * called after each fabric object created.
+   */
+  reviver?: (
+    serializedObj: Record<string, any>,
+    instance: FabricObject
+  ) => void;
+};
+
+/**
+ * Creates corresponding fabric instances from their object representations
+ * @param {Object[]} objects Objects to enliven
+ * @param {EnlivenObjectOptions} [options]
+ * @param {(serializedObj: object, instance: FabricObject) => any} [options.reviver] Method for further parsing of object elements,
+ * called after each fabric object created.
+ * @param {AbortSignal} [options.signal] handle aborting, see https://developer.mozilla.org/en-US/docs/Web/API/AbortController/signal
+ * @returns {Promise<FabricObject[]>}
+ */
+export const enlivenObjects = (
+  objects: any[],
+  { signal, reviver = noop }: EnlivenObjectOptions = {}
+) =>
+  new Promise<FabricObject[]>((resolve, reject) => {
+    const instances: FabricObject[] = [];
+    signal && signal.addEventListener('abort', reject, { once: true });
+    Promise.all(
+      objects.map((obj) =>
+        classRegistry
+          .getClass(obj.type)
+          .fromObject(obj, {
+            signal,
+            reviver,
+          })
+          .then((fabricInstance: FabricObject) => {
+            reviver(obj, fabricInstance);
+            instances.push(fabricInstance);
+            return fabricInstance;
+          })
+      )
+    )
+      .then(resolve)
+      .catch((error) => {
+        // cleanup
+        instances.forEach(function (instance) {
+          instance.dispose && instance.dispose();
+        });
+        reject(error);
+      })
+      .finally(() => {
+        signal && signal.removeEventListener('abort', reject);
+      });
+  });
+
+/**
+ * Creates corresponding fabric instances residing in an object, e.g. `clipPath`
+ * @param {Object} object with properties to enlive ( fill, stroke, clipPath, path )
+ * @param {object} [options]
+ * @param {AbortSignal} [options.signal] handle aborting, see https://developer.mozilla.org/en-US/docs/Web/API/AbortController/signal
+ * @returns {Promise<Record<string, FabricObject | TFiller | null>>} the input object with enlived values
+ */
+export const enlivenObjectEnlivables = <
+  R = Record<string, FabricObject | TFiller | null>
+>(
+  serializedObject: any,
+  { signal }: Abortable = {}
+) =>
+  new Promise<R>((resolve, reject) => {
+    const instances: (FabricObject | TFiller)[] = [];
+    signal && signal.addEventListener('abort', reject, { once: true });
+    // enlive every possible property
+    const promises = Object.values(serializedObject).map((value: any) => {
+      if (!value) {
+        return value;
+      }
+      // gradient
+      if (value.colorStops) {
+        return new (classRegistry.getClass('gradient'))(value);
+      }
+      // clipPath
+      if (value.type) {
+        return enlivenObjects([value], { signal }).then(([enlived]) => {
+          instances.push(enlived);
+          return enlived;
+        });
+      }
+      // pattern
+      if (value.source) {
+        return classRegistry
+          .getClass('pattern')
+          .fromObject(value, { signal })
+          .then((pattern: Pattern) => {
+            instances.push(pattern);
+            return pattern;
+          });
+      }
+      return value;
+    });
+    const keys = Object.keys(serializedObject);
+    Promise.all(promises)
+      .then((enlived) => {
+        return enlived.reduce((acc, instance, index) => {
+          acc[keys[index]] = instance;
+          return acc;
+        }, {});
+      })
+      .then(resolve)
+      .catch((error) => {
+        // cleanup
+        instances.forEach((instance: any) => {
+          instance.dispose && instance.dispose();
+        });
+        reject(error);
+      })
+      .finally(() => {
+        signal && signal.removeEventListener('abort', reject);
+      });
+  });

package/src/util/misc/objectTransforms.ts

@@ -0,0 +1,130 @@
+import { Point } from '../../Point';
+import { CENTER } from '../../constants';
+import type { FabricObject } from '../../shapes/Object/Object';
+import type { TMat2D } from '../../typedefs';
+import { makeBoundingBoxFromPoints } from './boundingBoxFromPoints';
+import type { TScaleMatrixArgs } from './matrix';
+import {
+  calcDimensionsMatrix,
+  invertTransform,
+  multiplyTransformMatrices,
+  qrDecompose,
+} from './matrix';
+
+/**
+ * given an object and a transform, apply the inverse transform to the object,
+ * this is equivalent to remove from that object that transformation, so that
+ * added in a space with the removed transform, the object will be the same as before.
+ * Removing from an object a transform that scale by 2 is like scaling it by 1/2.
+ * Removing from an object a transform that rotate by 30deg is like rotating by 30deg
+ * in the opposite direction.
+ * This util is used to add objects inside transformed groups or nested groups.
+ * @param {FabricObject} object the object you want to transform
+ * @param {TMat2D} transform the destination transform
+ */
+export const removeTransformFromObject = (
+  object: FabricObject,
+  transform: TMat2D
+) => {
+  const inverted = invertTransform(transform),
+    finalTransform = multiplyTransformMatrices(
+      inverted,
+      object.calcOwnMatrix()
+    );
+  applyTransformToObject(object, finalTransform);
+};
+
+/**
+ * given an object and a transform, apply the transform to the object.
+ * this is equivalent to change the space where the object is drawn.
+ * Adding to an object a transform that scale by 2 is like scaling it by 2.
+ * This is used when removing an object from an active selection for example.
+ * @param {FabricObject} object the object you want to transform
+ * @param {Array} transform the destination transform
+ */
+export const addTransformToObject = (object: FabricObject, transform: TMat2D) =>
+  applyTransformToObject(
+    object,
+    multiplyTransformMatrices(transform, object.calcOwnMatrix())
+  );
+
+/**
+ * discard an object transform state and apply the one from the matrix.
+ * @param {FabricObject} object the object you want to transform
+ * @param {Array} transform the destination transform
+ */
+export const applyTransformToObject = (
+  object: FabricObject,
+  transform: TMat2D
+) => {
+  const { translateX, translateY, scaleX, scaleY, ...otherOptions } =
+      qrDecompose(transform),
+    center = new Point(translateX, translateY);
+  object.flipX = false;
+  object.flipY = false;
+  Object.assign(object, otherOptions);
+  object.set({ scaleX, scaleY });
+  object.setPositionByOrigin(center, CENTER, CENTER);
+};
+/**
+ * reset an object transform state to neutral. Top and left are not accounted for
+ * @param  {FabricObject} target object to transform
+ */
+export const resetObjectTransform = (target: FabricObject) => {
+  target.scaleX = 1;
+  target.scaleY = 1;
+  target.skewX = 0;
+  target.skewY = 0;
+  target.flipX = false;
+  target.flipY = false;
+  target.rotate(0);
+};
+
+/**
+ * Extract Object transform values
+ * @param  {FabricObject} target object to read from
+ * @return {Object} Components of transform
+ */
+export const saveObjectTransform = (target: FabricObject) => ({
+  scaleX: target.scaleX,
+  scaleY: target.scaleY,
+  skewX: target.skewX,
+  skewY: target.skewY,
+  angle: target.angle,
+  left: target.left,
+  flipX: target.flipX,
+  flipY: target.flipY,
+  top: target.top,
+});
+
+/**
+ * given a width and height, return the size of the bounding box
+ * that can contains the box with width/height with applied transform
+ * described in options.
+ * Use to calculate the boxes around objects for controls.
+ * @param {Number} width
+ * @param {Number} height
+ * @param {Object} options
+ * @param {Number} options.scaleX
+ * @param {Number} options.scaleY
+ * @param {Number} options.skewX
+ * @param {Number} options.skewY
+ * @returns {Point} size
+ */
+export const sizeAfterTransform = (
+  width: number,
+  height: number,
+  options: TScaleMatrixArgs
+) => {
+  const dimX = width / 2,
+    dimY = height / 2,
+    transformMatrix = calcDimensionsMatrix(options),
+    points = [
+      new Point(-dimX, -dimY),
+      new Point(dimX, -dimY),
+      new Point(-dimX, dimY),
+      new Point(dimX, dimY),
+    ].map((p) => p.transform(transformMatrix)),
+    bbox = makeBoundingBoxFromPoints(points);
+  return new Point(bbox.width, bbox.height);
+};

package/src/util/misc/pick.ts

@@ -0,0 +1,29 @@
+/**
+ * Populates an object with properties of another object
+ * @param {Object} source Source object
+ * @param {string[]} properties Properties names to include
+ * @returns object populated with the picked keys
+ */
+export const pick = <T extends Record<string, any>>(
+  source: T,
+  keys: (keyof T)[] = []
+) => {
+  return keys.reduce((o, key) => {
+    if (key in source) {
+      o[key] = source[key];
+    }
+    return o;
+  }, {} as Partial<T>);
+};
+
+export const pickBy = <T extends Record<string, any>>(
+  source: T,
+  predicate: <K extends keyof T>(value: T[K], key: K, collection: T) => boolean
+) => {
+  return (Object.keys(source) as (keyof T)[]).reduce((o, key) => {
+    if (predicate(source[key], key, source)) {
+      o[key] = source[key];
+    }
+    return o;
+  }, {} as Partial<T>);
+};