fabric 5.3.0 → 6.0.0-beta3

package/src/util/dom_style.ts

@@ -0,0 +1,20 @@
+//@ts-nocheck
+// TODO this file needs to go away, cross browser style support is not fabricjs domain.
+
+/**
+ * wrapper for setting element's style
+ * @param {HTMLElement} element
+ * @param {Object | string} styles
+ */
+export function setStyle(element, styles) {
+  const elementStyle = element.style;
+  if (!elementStyle) {
+    return;
+  } else if (typeof styles === 'string') {
+    element.style.cssText += ';' + styles;
+  } else {
+    Object.entries(styles).forEach(([property, value]) =>
+      elementStyle.setProperty(property, value)
+    );
+  }
+}

package/src/util/fireEvent.ts

@@ -0,0 +1,15 @@
+import { BasicTransformEvent, TModificationEvents } from '../EventTypeDefs';
+
+export const fireEvent = (
+  eventName: TModificationEvents,
+  options: BasicTransformEvent
+) => {
+  const {
+    transform: { target },
+  } = options;
+  target.canvas?.fire(`object:${eventName}`, {
+    ...options,
+    target,
+  });
+  target.fire(eventName, options);
+};

package/src/util/index.ts

@@ -0,0 +1,102 @@
+export { cos } from './misc/cos';
+export { sin } from './misc/sin';
+export {
+  rotateVector,
+  createVector,
+  calcAngleBetweenVectors,
+  getUnitVector,
+  getBisector,
+} from './misc/vectors';
+export {
+  degreesToRadians,
+  radiansToDegrees,
+} from './misc/radiansDegreesConversion';
+export { rotatePoint } from './misc/rotatePoint';
+export { projectStrokeOnPoints } from './misc/projectStroke';
+export {
+  transformPoint,
+  invertTransform,
+  composeMatrix,
+  qrDecompose,
+  calcDimensionsMatrix,
+  calcRotateMatrix,
+  multiplyTransformMatrices,
+  isIdentityMatrix,
+} from './misc/matrix';
+export {
+  stylesFromArray,
+  stylesToArray,
+  hasStyleChanged,
+} from './misc/textStyles';
+export {
+  createCanvasElement,
+  createImage,
+  copyCanvasElement,
+  toDataURL,
+} from './misc/dom';
+export { toFixed } from './misc/toFixed';
+export {
+  matrixToSVG,
+  parsePreserveAspectRatioAttribute,
+  parseUnit,
+  getSvgAttributes,
+} from './misc/svgParsing';
+export { groupSVGElements } from './misc/groupSVGElements';
+export { findScaleToFit, findScaleToCover } from './misc/findScaleTo';
+export { capValue } from './misc/capValue';
+export {
+  saveObjectTransform,
+  resetObjectTransform,
+  addTransformToObject,
+  applyTransformToObject,
+  removeTransformFromObject,
+  sizeAfterTransform,
+} from './misc/objectTransforms';
+export { makeBoundingBoxFromPoints } from './misc/boundingBoxFromPoints';
+export {
+  calcPlaneChangeMatrix,
+  sendPointToPlane,
+  transformPointRelativeToCanvas,
+  sendObjectToPlane,
+} from './misc/planeChange';
+export * as string from './lang_string';
+export {
+  loadImage,
+  enlivenObjects,
+  enlivenObjectEnlivables,
+} from './misc/objectEnlive';
+export { pick } from './misc/pick';
+export {
+  joinPath,
+  parsePath,
+  makePathSimpler,
+  getSmoothPathFromPoints,
+  getPathSegmentsInfo,
+  getBoundsOfCurve,
+  getPointOnPath,
+  transformPath,
+  getRegularPolygonPath,
+} from './path';
+export { setStyle } from './dom_style';
+export { isTouchEvent, getPointer } from './dom_event';
+export {
+  // getScrollLeftTop,
+  getElementOffset,
+  makeElementUnselectable,
+  makeElementSelectable,
+} from './dom_misc';
+export { isTransparent } from './misc/isTransparent';
+export { mergeClipPaths } from './misc/mergeClipPaths';
+export { animate, animateColor } from './animation/animate';
+export * as ease from './animation/easing';
+export {
+  requestAnimFrame,
+  cancelAnimFrame,
+} from './animation/AnimationFrameProvider';
+export { removeFromArray } from './internals/removeFromArray';
+export { getRandomInt } from './internals/getRandomInt';
+export { wrapElement } from './dom_misc';
+export { request } from './dom_request';
+
+// for test compatibility. We don't want to export it
+export { removeTransformMatrixForSvgParsing } from './transform_matrix_removal';

package/src/util/internals/cloneDeep.ts

@@ -0,0 +1,2 @@
+export const cloneDeep = <T extends object>(object: T): T =>
+  JSON.parse(JSON.stringify(object));

package/src/util/internals/getRandomInt.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns random number between 2 specified ones.
+ * @param {Number} min lower limit
+ * @param {Number} max upper limit
+ * @return {Number} random value (between min and max)
+ */
+export const getRandomInt = (min: number, max: number): number =>
+  Math.floor(Math.random() * (max - min + 1)) + min;

package/src/util/internals/ifNaN.ts

@@ -0,0 +1,9 @@
+/**
+ *
+ * @param value value to check if NaN
+ * @param [valueIfNaN]
+ * @returns `fallback` is `value is NaN
+ */
+export const ifNaN = (value: number, valueIfNaN?: number) => {
+  return isNaN(value) && typeof valueIfNaN === 'number' ? valueIfNaN : value;
+};

package/src/util/internals/index.ts

@@ -0,0 +1,3 @@
+export { getRandomInt } from './getRandomInt';
+export { ifNaN } from './ifNaN';
+export { removeFromArray } from './removeFromArray';

package/src/util/internals/removeFromArray.ts

@@ -0,0 +1,14 @@
+/**
+ * Removes value from an array.
+ * Presence of value (and its position in an array) is determined via `Array.prototype.indexOf`
+ * @param {Array} array
+ * @param {*} value
+ * @return {Array} original array
+ */
+export const removeFromArray = <T>(array: T[], value: T): T[] => {
+  const idx = array.indexOf(value);
+  if (idx !== -1) {
+    array.splice(idx, 1);
+  }
+  return array;
+};

package/src/util/internals/uid.ts

@@ -0,0 +1,3 @@
+let id = 0;
+
+export const uid = () => id++;

package/src/util/lang_string.ts

@@ -0,0 +1,79 @@
+/**
+ * Capitalizes a string
+ * @param {String} string String to capitalize
+ * @param {Boolean} [firstLetterOnly] If true only first letter is capitalized
+ * and other letters stay untouched, if false first letter is capitalized
+ * and other letters are converted to lowercase.
+ * @return {String} Capitalized version of a string
+ */
+export const capitalize = (string: string, firstLetterOnly = false): string =>
+  `${string.charAt(0).toUpperCase()}${
+    firstLetterOnly ? string.slice(1) : string.slice(1).toLowerCase()
+  }`;
+
+/**
+ * Escapes XML in a string
+ * @param {String} string String to escape
+ * @return {String} Escaped version of a string
+ */
+export const escapeXml = (string: string): string =>
+  string
+    .replace(/&/g, '&')
+    .replace(/"/g, '"')
+    .replace(/'/g, ''')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+
+/**
+ * Divide a string in the user perceived single units
+ * @param {String} textstring String to escape
+ * @return {Array} array containing the graphemes
+ */
+export const graphemeSplit = (textstring: string): string[] => {
+  const graphemes = [];
+  for (let i = 0, chr; i < textstring.length; i++) {
+    if ((chr = getWholeChar(textstring, i)) === false) {
+      continue;
+    }
+    graphemes.push(chr as string);
+  }
+  return graphemes;
+};
+
+// taken from mdn in the charAt doc page.
+const getWholeChar = (str: string, i: number): string | boolean => {
+  const code = str.charCodeAt(i);
+  if (isNaN(code)) {
+    return ''; // Position not found
+  }
+  if (code < 0xd800 || code > 0xdfff) {
+    return str.charAt(i);
+  }
+
+  // High surrogate (could change last hex to 0xDB7F to treat high private
+  // surrogates as single characters)
+  if (0xd800 <= code && code <= 0xdbff) {
+    if (str.length <= i + 1) {
+      throw 'High surrogate without following low surrogate';
+    }
+    const next = str.charCodeAt(i + 1);
+    if (0xdc00 > next || next > 0xdfff) {
+      throw 'High surrogate without following low surrogate';
+    }
+    return str.charAt(i) + str.charAt(i + 1);
+  }
+  // Low surrogate (0xDC00 <= code && code <= 0xDFFF)
+  if (i === 0) {
+    throw 'Low surrogate without preceding high surrogate';
+  }
+  const prev = str.charCodeAt(i - 1);
+
+  // (could change last hex to 0xDB7F to treat high private
+  // surrogates as single characters)
+  if (0xd800 > prev || prev > 0xdbff) {
+    throw 'Low surrogate without preceding high surrogate';
+  }
+  // We can pass over low surrogates now as the second component
+  // in a pair which we have already processed
+  return false;
+};

package/src/util/misc/boundingBoxFromPoints.ts

@@ -0,0 +1,37 @@
+import { XY, Point } from '../../Point';
+import { TBBox } from '../../typedefs';
+
+/**
+ * Calculates bounding box (left, top, width, height) from given `points`
+ * @param {XY[]} points
+ * @return {Object} Object with left, top, width, height properties
+ */
+export const makeBoundingBoxFromPoints = (points: XY[]): TBBox => {
+  if (points.length === 0) {
+    return {
+      left: 0,
+      top: 0,
+      width: 0,
+      height: 0,
+    };
+  }
+
+  const { min, max } = points.reduce(
+    ({ min, max }, curr) => {
+      return {
+        min: min.min(curr),
+        max: max.max(curr),
+      };
+    },
+    { min: new Point(points[0]), max: new Point(points[0]) }
+  );
+
+  const size = max.subtract(min);
+
+  return {
+    left: min.x,
+    top: min.y,
+    width: size.x,
+    height: size.y,
+  };
+};

package/src/util/misc/capValue.ts

@@ -0,0 +1,2 @@
+export const capValue = (min: number, value: number, max: number) =>
+  Math.max(min, Math.min(value, max));

package/src/util/misc/cos.ts

@@ -0,0 +1,24 @@
+import type { TRadian } from '../../typedefs';
+import { halfPI } from '../../constants';
+
+/**
+ * Calculate the cos of an angle, avoiding returning floats for known results
+ * This function is here just to avoid getting 0.999999999999999 when dealing
+ * with numbers that are really 1 or 0.
+ * @param {TRadian} angle the angle
+ * @return {Number} the cosin value for angle.
+ */
+export const cos = (angle: TRadian): number => {
+  if (angle === 0) {
+    return 1;
+  }
+  const angleSlice = Math.abs(angle) / halfPI;
+  switch (angleSlice) {
+    case 1:
+    case 3:
+      return 0;
+    case 2:
+      return -1;
+  }
+  return Math.cos(angle);
+};

package/src/util/misc/dom.ts

@@ -0,0 +1,50 @@
+import { getDocument } from '../../env';
+import { ImageFormat } from '../../typedefs';
+/**
+ * Creates canvas element
+ * @return {CanvasElement} initialized canvas element
+ */
+export const createCanvasElement = (): HTMLCanvasElement =>
+  getDocument().createElement('canvas');
+
+/**
+ * Creates image element (works on client and node)
+ * @return {HTMLImageElement} HTML image element
+ */
+export const createImage = (): HTMLImageElement =>
+  getDocument().createElement('img');
+
+/**
+ * Creates a canvas element that is a copy of another and is also painted
+ * @param {CanvasElement} canvas to copy size and content of
+ * @return {CanvasElement} initialized canvas element
+ */
+export const copyCanvasElement = (
+  canvas: HTMLCanvasElement
+): HTMLCanvasElement => {
+  const newCanvas = createCanvasElement();
+  newCanvas.width = canvas.width;
+  newCanvas.height = canvas.height;
+  newCanvas.getContext('2d')?.drawImage(canvas, 0, 0);
+  return newCanvas;
+};
+
+/**
+ * since 2.6.0 moved from canvas instance to utility.
+ * possibly useless
+ * @param {CanvasElement} canvasEl to copy size and content of
+ * @param {String} format 'jpeg' or 'png', in some browsers 'webp' is ok too
+ * @param {Number} quality <= 1 and > 0
+ * @return {String} data url
+ */
+export const toDataURL = (
+  canvasEl: HTMLCanvasElement,
+  format: ImageFormat,
+  quality: number
+) => canvasEl.toDataURL(`image/${format}`, quality);
+
+export const isHTMLCanvas = (
+  canvas: HTMLCanvasElement | string
+): canvas is HTMLCanvasElement => {
+  return !!canvas && (canvas as HTMLCanvasElement).getContext !== undefined;
+};

package/src/util/misc/findScaleTo.ts

@@ -0,0 +1,44 @@
+export interface IWithDimensions {
+  /**
+   * natural unscaled width of the object
+   */
+  width: number;
+  /**
+   * natural unscaled height of the object
+   */
+  height: number;
+}
+
+/**
+ * Finds the scale for the object source to fit inside the object destination,
+ * keeping aspect ratio intact.
+ * respect the total allowed area for the cache.
+ * @param {IWithDimensions} source
+ * @param {IWithDimensions} destination
+ * @return {Number} scale factor to apply to source to fit into destination
+ */
+export const findScaleToFit = (
+  source: IWithDimensions,
+  destination: IWithDimensions
+) =>
+  Math.min(
+    destination.width / source.width,
+    destination.height / source.height
+  );
+
+/**
+ * Finds the scale for the object source to cover entirely the object destination,
+ * keeping aspect ratio intact.
+ * respect the total allowed area for the cache.
+ * @param {IWithDimensions} source
+ * @param {IWithDimensions} destination
+ * @return {Number} scale factor to apply to source to cover destination
+ */
+export const findScaleToCover = (
+  source: IWithDimensions,
+  destination: IWithDimensions
+) =>
+  Math.max(
+    destination.width / source.width,
+    destination.height / source.height
+  );

package/src/util/misc/groupSVGElements.ts

@@ -0,0 +1,15 @@
+import type { FabricObject } from '../../shapes/Object/FabricObject';
+import { Group } from '../../shapes/Group';
+
+/**
+ * Groups SVG elements (usually those retrieved from SVG document)
+ * @static
+ * @param {FabricObject[]} elements FabricObject(s) parsed from svg, to group
+ * @return {FabricObject | Group}
+ */
+export const groupSVGElements = (elements: FabricObject[]) => {
+  if (elements && elements.length === 1) {
+    return elements[0];
+  }
+  return new Group(elements);
+};

package/src/util/misc/isTransparent.ts

@@ -0,0 +1,28 @@
+/**
+ * Returns true if context has transparent pixel
+ * at specified location (taking tolerance into account)
+ * @param {CanvasRenderingContext2D} ctx context
+ * @param {Number} x x coordinate in canvasElementCoordinate, not fabric space. integer
+ * @param {Number} y y coordinate in canvasElementCoordinate, not fabric space. integer
+ * @param {Number} tolerance Tolerance pixels around the point, not alpha tolerance, integer
+ * @return {boolean} true if transparent
+ */
+export const isTransparent = (
+  ctx: CanvasRenderingContext2D,
+  x: number,
+  y: number,
+  tolerance: number
+): boolean => {
+  tolerance = Math.round(tolerance);
+  const size = tolerance * 2 + 1;
+  const { data } = ctx.getImageData(x - tolerance, y - tolerance, size, size);
+
+  // Split image data - for tolerance > 1, pixelDataSize = 4;
+  for (let i = 3; i < data.length; i += 4) {
+    const alphaChannel = data[i];
+    if (alphaChannel > 0) {
+      return false;
+    }
+  }
+  return true;
+};

package/src/util/misc/matrix.ts

@@ -0,0 +1,207 @@
+import { iMatrix } from '../../constants';
+import { XY, Point } from '../../Point';
+import { TDegree, 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 } = transformPoint(new Point(t[4], t[5]), 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;
+
+/**
+ * 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,
+  };
+};
+
+/**
+ * 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] angle in degrees
+ * @return {TMat2D} transform matrix
+ */
+export const calcRotateMatrix = ({ angle }: TRotateMatrixArgs): TMat2D => {
+  if (!angle) {
+    return iMatrix;
+  }
+  const theta = degreesToRadians(angle),
+    cosin = cos(theta),
+    sinus = sin(theta);
+  return [cosin, sinus, -sinus, cosin, 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) => {
+  let scaleMatrix = iMatrix;
+  if (scaleX !== 1 || scaleY !== 1 || flipX || flipY) {
+    scaleMatrix = [
+      flipX ? -scaleX : scaleX,
+      0,
+      0,
+      flipY ? -scaleY : scaleY,
+      0,
+      0,
+    ] as TMat2D;
+  }
+  if (skewX) {
+    scaleMatrix = multiplyTransformMatrices(
+      scaleMatrix,
+      [1, 0, Math.tan(degreesToRadians(skewX)), 1] as unknown as TMat2D,
+      true
+    );
+  }
+  if (skewY) {
+    scaleMatrix = multiplyTransformMatrices(
+      scaleMatrix,
+      [1, Math.tan(degreesToRadians(skewY)), 0, 1] as unknown as TMat2D,
+      true
+    );
+  }
+  return scaleMatrix;
+};
+
+/**
+ * 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 => {
+  let matrix = [1, 0, 0, 1, translateX, translateY] as TMat2D;
+  if (angle) {
+    matrix = multiplyTransformMatrices(matrix, calcRotateMatrix({ angle }));
+  }
+  const scaleMatrix = calcDimensionsMatrix(otherOptions);
+  if (scaleMatrix !== iMatrix) {
+    matrix = multiplyTransformMatrices(matrix, scaleMatrix);
+  }
+  return matrix;
+};