fabric 5.3.0 → 6.0.0-beta3

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,189 @@
+import { noop } from '../../constants';
+import type { Gradient } from '../../gradient/Gradient';
+import type { Pattern } from '../../Pattern';
+import type { FabricObject } from '../../shapes/Object/FabricObject';
+import type { TCrossOrigin, TFiller } from '../../typedefs';
+import { createImage } from './dom';
+import { classRegistry } from '../../ClassRegistry';
+
+export type LoadImageOptions = {
+  /**
+   * see https://developer.mozilla.org/en-US/docs/Web/API/AbortController/signal
+   */
+  signal?: AbortSignal;
+  /**
+   * 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 = {
+  /**
+   * handle aborting, see https://developer.mozilla.org/en-US/docs/Web/API/AbortController/signal
+   */
+  signal?: AbortSignal;
+  /**
+   * Method for further parsing of object elements,
+   * called after each fabric object created.
+   */
+  reviver?: (
+    serializedObj: Record<string, any>,
+    instance: FabricObject
+  ) => void;
+  /**
+   * Namespace to get klass "Class" object from
+   */
+  namespace?: any;
+};
+
+/**
+ * Creates corresponding fabric instances from their object representations
+ * @param {Object[]} objects Objects to enliven
+ * @param {EnlivenObjectOptions} [options]
+ * @param {object} [options.namespace] Namespace to get klass "Class" object from
+ * @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)
+          // @ts-ignore
+          .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 }: { signal?: AbortSignal } = {}
+) =>
+  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,129 @@
+import { Point } from '../../Point';
+import type { FabricObject } from '../../shapes/Object/Object';
+import { 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>);
+};

package/src/util/misc/planeChange.ts

@@ -0,0 +1,136 @@
+import { iMatrix } from '../../constants';
+import type { Point } from '../../Point';
+import type { FabricObject } from '../../shapes/Object/Object';
+import type { TMat2D } from '../../typedefs';
+import type { StaticCanvas } from '../../canvas/StaticCanvas';
+import { invertTransform, multiplyTransformMatrices } from './matrix';
+import { applyTransformToObject } from './objectTransforms';
+
+export const enum ObjectRelation {
+  sibling = 'sibling',
+  child = 'child',
+}
+
+/**
+ * We are actually looking for the transformation from the destination plane to the source plane (change of basis matrix)\
+ * The object will exist on the destination plane and we want it to seem unchanged by it so we invert the destination matrix (`to`) and then apply the source matrix (`from`)
+ * @param [from]
+ * @param [to]
+ * @returns
+ */
+export const calcPlaneChangeMatrix = (
+  from: TMat2D = iMatrix,
+  to: TMat2D = iMatrix
+) => multiplyTransformMatrices(invertTransform(to), from);
+
+/**
+ * Sends a point from the source coordinate plane to the destination coordinate plane.\
+ * From the canvas/viewer's perspective the point remains unchanged.
+ *
+ * @example <caption>Send point from canvas plane to group plane</caption>
+ * var obj = new Rect({ left: 20, top: 20, width: 60, height: 60, strokeWidth: 0 });
+ * var group = new Group([obj], { strokeWidth: 0 });
+ * var sentPoint1 = sendPointToPlane(new Point(50, 50), undefined, group.calcTransformMatrix());
+ * var sentPoint2 = sendPointToPlane(new Point(50, 50), iMatrix, group.calcTransformMatrix());
+ * console.log(sentPoint1, sentPoint2) //  both points print (0,0) which is the center of group
+ *
+ * @see {transformPointRelativeToCanvas} for transforming relative to canvas
+ * @param {Point} point
+ * @param {TMat2D} [from] plane matrix containing object. Passing `undefined` is equivalent to passing the identity matrix, which means `point` exists in the canvas coordinate plane.
+ * @param {TMat2D} [to] destination plane matrix to contain object. Passing `undefined` means `point` should be sent to the canvas coordinate plane.
+ * @returns {Point} transformed point
+ */
+export const sendPointToPlane = (
+  point: Point,
+  from: TMat2D = iMatrix,
+  to: TMat2D = iMatrix
+): Point =>
+  //  we are actually looking for the transformation from the destination plane to the source plane (which is a linear mapping)
+  //  the object will exist on the destination plane and we want it to seem unchanged by it so we reverse the destination matrix (to) and then apply the source matrix (from)
+  point.transform(calcPlaneChangeMatrix(from, to));
+
+/**
+ * Transform point relative to canvas.
+ * From the viewport/viewer's perspective the point remains unchanged.
+ *
+ * `child` relation means `point` exists in the coordinate plane created by `canvas`.
+ * In other words point is measured according to canvas' top left corner
+ * meaning that if `point` is equal to (0,0) it is positioned at canvas' top left corner.
+ *
+ * `sibling` relation means `point` exists in the same coordinate plane as canvas.
+ * In other words they both relate to the same (0,0) and agree on every point, which is how an event relates to canvas.
+ *
+ * @param {Point} point
+ * @param {StaticCanvas} canvas
+ * @param {'sibling'|'child'} relationBefore current relation of point to canvas
+ * @param {'sibling'|'child'} relationAfter desired relation of point to canvas
+ * @returns {Point} transformed point
+ */
+export const transformPointRelativeToCanvas = (
+  point: Point,
+  canvas: StaticCanvas,
+  relationBefore: ObjectRelation,
+  relationAfter: ObjectRelation
+): Point => {
+  // is this still needed with TS?
+  if (
+    relationBefore !== ObjectRelation.child &&
+    relationBefore !== ObjectRelation.sibling
+  ) {
+    throw new Error(`fabric.js: received bad argument ${relationBefore}`);
+  }
+  if (
+    relationAfter !== ObjectRelation.child &&
+    relationAfter !== ObjectRelation.sibling
+  ) {
+    throw new Error(`fabric.js: received bad argument ${relationAfter}`);
+  }
+  if (relationBefore === relationAfter) {
+    return point;
+  }
+  const t = canvas.viewportTransform;
+  return point.transform(relationAfter === 'child' ? invertTransform(t) : t);
+};
+
+/**
+ *
+ * A util that abstracts applying transform to objects.\
+ * Sends `object` to the destination coordinate plane by applying the relevant transformations.\
+ * Changes the space/plane where `object` is drawn.\
+ * From the canvas/viewer's perspective `object` remains unchanged.
+ *
+ * @example <caption>Move clip path from one object to another while preserving it's appearance as viewed by canvas/viewer</caption>
+ * let obj, obj2;
+ * let clipPath = new Circle({ radius: 50 });
+ * obj.clipPath = clipPath;
+ * // render
+ * sendObjectToPlane(clipPath, obj.calcTransformMatrix(), obj2.calcTransformMatrix());
+ * obj.clipPath = undefined;
+ * obj2.clipPath = clipPath;
+ * // render, clipPath now clips obj2 but seems unchanged from the eyes of the viewer
+ *
+ * @example <caption>Clip an object's clip path with an existing object</caption>
+ * let obj, existingObj;
+ * let clipPath = new Circle({ radius: 50 });
+ * obj.clipPath = clipPath;
+ * let transformTo = multiplyTransformMatrices(obj.calcTransformMatrix(), clipPath.calcTransformMatrix());
+ * sendObjectToPlane(existingObj, existingObj.group?.calcTransformMatrix(), transformTo);
+ * clipPath.clipPath = existingObj;
+ *
+ * @param {FabricObject} object
+ * @param {Matrix} [from] plane matrix containing object. Passing `undefined` is equivalent to passing the identity matrix, which means `object` is a direct child of canvas.
+ * @param {Matrix} [to] destination plane matrix to contain object. Passing `undefined` means `object` should be sent to the canvas coordinate plane.
+ * @returns {Matrix} the transform matrix that was applied to `object`
+ */
+export const sendObjectToPlane = (
+  object: FabricObject,
+  from?: TMat2D,
+  to?: TMat2D
+): TMat2D => {
+  const t = calcPlaneChangeMatrix(from, to);
+  applyTransformToObject(
+    object,
+    multiplyTransformMatrices(t, object.calcOwnMatrix())
+  );
+  return t;
+};

package/src/util/misc/projectStroke/StrokeLineCapProjections.ts

@@ -0,0 +1,112 @@
+import { XY, Point } from '../../../Point';
+import { createVector, getOrthonormalVector, getUnitVector } from '../vectors';
+import { StrokeLineJoinProjections } from './StrokeLineJoinProjections';
+import { StrokeProjectionsBase } from './StrokeProjectionsBase';
+import { TProjection, TProjectStrokeOnPointsOptions } from './types';
+
+/**
+ * class in charge of finding projections for each type of line cap for start/end of an open path
+ * @see {@link [Open path projections at #8344](https://github.com/fabricjs/fabric.js/pull/8344#1-open-path)}
+ *
+ * Reference:
+ * - MDN:
+ *   - https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap
+ *   - https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-linecap
+ * - Spec: https://html.spec.whatwg.org/multipage/canvas.html#dom-context-2d-linecap-dev
+ * - Playground to understand how the line joins works: https://hypertolosana.github.io/efficient-webgl-stroking/index.html
+ * - View the calculated projections for each of the control points: https://codesandbox.io/s/project-stroke-points-with-context-to-trace-b8jc4j?file=/src/index.js
+ */
+export class StrokeLineCapProjections extends StrokeProjectionsBase {
+  /**
+   * edge point
+   */
+  declare A: Point;
+  /**
+   * point next to edge point
+   */
+  declare T: Point;
+
+  constructor(A: XY, T: XY, options: TProjectStrokeOnPointsOptions) {
+    super(options);
+    this.A = new Point(A);
+    this.T = new Point(T);
+  }
+
+  calcOrthogonalProjection(
+    from: Point,
+    to: Point,
+    magnitude: number = this.strokeProjectionMagnitude
+  ) {
+    const vector = this.createSideVector(from, to);
+    return this.scaleUnitVector(getOrthonormalVector(vector), magnitude);
+  }
+
+  /**
+   * OPEN PATH START/END - Line cap: Butt
+   * Calculation: to find the projections, just find the points orthogonal to the stroke
+   *
+   * @see https://github.com/fabricjs/fabric.js/pull/8344#1-1-butt
+   */
+  projectButt() {
+    return [
+      this.projectOrthogonally(this.A, this.T, this.strokeProjectionMagnitude),
+      this.projectOrthogonally(this.A, this.T, -this.strokeProjectionMagnitude),
+    ];
+  }
+
+  /**
+   * OPEN PATH START/END - Line cap: Round
+   * Calculation: same as stroke line join `round`
+   *
+   * @see https://github.com/fabricjs/fabric.js/pull/8344#1-2-round
+   */
+  projectRound() {
+    return new StrokeLineJoinProjections(
+      this.A,
+      this.T,
+      this.T,
+      this.options
+    ).projectRound();
+  }
+
+  /**
+   * OPEN PATH START/END - Line cap: Square
+   * Calculation: project a rectangle of points on the stroke in the opposite direction of the vector `AT`
+   *
+   * @see https://github.com/fabricjs/fabric.js/pull/8344#1-3-square
+   */
+  projectSquare() {
+    const orthogonalProjection = this.calcOrthogonalProjection(
+      this.A,
+      this.T,
+      this.strokeProjectionMagnitude
+    );
+    const strokePointingOut = this.scaleUnitVector(
+      getUnitVector(createVector(this.A, this.T)),
+      -this.strokeProjectionMagnitude
+    );
+    const projectedA = this.A.add(strokePointingOut);
+    return [
+      projectedA.add(orthogonalProjection),
+      projectedA.subtract(orthogonalProjection),
+    ].map((p) => this.applySkew(p));
+  }
+
+  protected projectPoints() {
+    switch (this.options.strokeLineCap) {
+      case 'round':
+        return this.projectRound();
+      case 'square':
+        return this.projectSquare();
+      default:
+        return this.projectButt();
+    }
+  }
+
+  public project(): TProjection[] {
+    return this.projectPoints().map((point) => ({
+      originPoint: this.A,
+      projectedPoint: point,
+    }));
+  }
+}