@nasser-sw/fabric 7.0.0-beta1

package/src/util/index.ts

@@ -0,0 +1,116 @@
+export { cos } from './misc/cos';
+export { sin } from './misc/sin';
+export {
+  rotateVector,
+  createVector,
+  calcAngleBetweenVectors,
+  getUnitVector,
+  calcVectorRotation,
+  crossProduct,
+  dotProduct,
+  getOrthonormalVector,
+  isBetweenVectors,
+  magnitude,
+} from './misc/vectors';
+export {
+  degreesToRadians,
+  radiansToDegrees,
+} from './misc/radiansDegreesConversion';
+export * from './misc/projectStroke';
+export type {
+  TComposeMatrixArgs,
+  TQrDecomposeOut,
+  TRotateMatrixArgs,
+  TScaleMatrixArgs,
+  TTranslateMatrixArgs,
+} from './misc/matrix';
+export {
+  transformPoint,
+  invertTransform,
+  composeMatrix,
+  qrDecompose,
+  createTranslateMatrix,
+  createRotateMatrix,
+  createScaleMatrix,
+  createSkewXMatrix,
+  createSkewYMatrix,
+  calcDimensionsMatrix,
+  multiplyTransformMatrices,
+  multiplyTransformMatrixArray,
+  isIdentityMatrix,
+} from './misc/matrix';
+export type { TextStyleArray } from './misc/textStyles';
+export {
+  stylesFromArray,
+  stylesToArray,
+  hasStyleChanged,
+} from './misc/textStyles';
+export {
+  createCanvasElement,
+  createImage,
+  copyCanvasElement,
+  toDataURL,
+  toBlob,
+} from './misc/dom';
+export { toFixed } from './misc/toFixed';
+export {
+  parsePreserveAspectRatioAttribute,
+  parseUnit,
+  getSvgAttributes,
+} from './misc/svgParsing';
+export { matrixToSVG } from './misc/svgExport';
+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,
+  sendVectorToPlane,
+  sendObjectToPlane,
+} from './misc/planeChange';
+export * as string from './lang_string';
+export type {
+  EnlivenObjectOptions,
+  LoadImageOptions,
+} from './misc/objectEnlive';
+export {
+  loadImage,
+  enlivenObjects,
+  enlivenObjectEnlivables,
+} from './misc/objectEnlive';
+export { pick } from './misc/pick';
+export type * from './path/typedefs';
+export {
+  joinPath,
+  parsePath,
+  makePathSimpler,
+  getSmoothPathFromPoints,
+  getPathSegmentsInfo,
+  getBoundsOfCurve,
+  getPointOnPath,
+  transformPath,
+  getRegularPolygonPath,
+} from './path';
+export { isTouchEvent, getPointer } from './dom_event';
+export { isTransparent } from './misc/isTransparent';
+export { mergeClipPaths } from './misc/mergeClipPaths';
+export * from './animation';
+export * as ease from './animation/easing';
+export {
+  requestAnimFrame,
+  cancelAnimFrame,
+} from './animation/AnimationFrameProvider';
+export { removeFromArray } from './internals/removeFromArray';
+export { getRandomInt } from './internals/getRandomInt';
+
+// for test compatibility. We don't want to export it
+export { removeTransformMatrixForSvgParsing } from './transform_matrix_removal';

package/src/util/internals/applyCanvasTransform.ts

@@ -0,0 +1,19 @@
+import type { StaticCanvas } from '../../canvas/StaticCanvas';
+
+/**
+ * Set the transform of the passed context to the same of a specific Canvas or StaticCanvas.
+ * setTransform is used since this utility will RESET the ctx transform to the basic value
+ * of retina scaling and viewport transform
+ * It is not meant to be added to other transforms, it is used internally to preapre canvases to draw
+ * @param ctx
+ * @param canvas
+ */
+export const applyCanvasTransform = (
+  ctx: CanvasRenderingContext2D,
+  canvas: StaticCanvas,
+) => {
+  const scale = canvas.getRetinaScaling();
+  ctx.setTransform(scale, 0, 0, scale, 0, 0);
+  const v = canvas.viewportTransform;
+  ctx.transform(v[0], v[1], v[2], v[3], v[4], v[5]);
+};

package/src/util/internals/cleanupSvgAttribute.test.ts

@@ -0,0 +1,17 @@
+import { cleanupSvgAttribute } from './cleanupSvgAttribute';
+import { expect, it, describe } from 'vitest';
+
+describe('cleanupSvgAttribute', () => {
+  it('add space around a single number', () => {
+    const cleaned = cleanupSvgAttribute('1');
+    expect(cleaned).toBe(' 1 ');
+  });
+  it('replace multiple spaces with a single one', () => {
+    const cleaned = cleanupSvgAttribute('     1    ');
+    expect(cleaned).toBe(' 1 ');
+  });
+  it('replace commas with spaces or commas and multiple spaces with a single space', () => {
+    const cleaned = cleanupSvgAttribute('1,2 , 4');
+    expect(cleaned).toBe(' 1 2 4 ');
+  });
+});

package/src/util/internals/cleanupSvgAttribute.ts

@@ -0,0 +1,10 @@
+import { reNum } from '../../parser/constants';
+
+const regex = new RegExp(`(${reNum})`, 'gi');
+
+export const cleanupSvgAttribute = (attributeValue: string) =>
+  attributeValue
+    .replace(regex, ' $1 ')
+    // replace annoying commas and arbitrary whitespace with single spaces
+    .replace(/,/gi, ' ')
+    .replace(/\s+/gi, ' ');

package/src/util/internals/cloneStyles.spec.ts

@@ -0,0 +1,48 @@
+import { cloneStyles } from './cloneStyles';
+import type {
+  TextStyle,
+  CompleteTextStyleDeclaration,
+} from '../../shapes/Text/StyledText';
+
+import { describe, expect, it } from 'vitest';
+
+describe('cloneStyles', () => {
+  it('clones a styles object deeply', () => {
+    const style: CompleteTextStyleDeclaration = {
+      fill: 'blue',
+      stroke: 'red',
+      strokeWidth: 8,
+      fontSize: 44,
+      fontFamily: 'Roboto',
+      fontWeight: 'bold',
+      fontStyle: 'italic',
+      textBackgroundColor: 'green',
+      deltaY: -5,
+      overline: true,
+      underline: false,
+      linethrough: true,
+    };
+
+    const testObject: TextStyle = {
+      0: {
+        0: style,
+        6: style,
+      },
+      1: {
+        0: style,
+        3: style,
+      },
+      2: {
+        0: style,
+        3: style,
+      },
+    };
+    const cloned = cloneStyles(testObject);
+    expect(cloned).toEqual(testObject);
+    expect(cloned).not.toBe(testObject);
+    expect(cloned[0]).toEqual(testObject[0]);
+    expect(cloned[0]).not.toBe(testObject[0]);
+    expect(cloned[2][3]).toEqual(testObject[2][3]);
+    expect(cloned[2][3]).not.toBe(testObject[2][3]);
+  });
+});

package/src/util/internals/cloneStyles.ts

@@ -0,0 +1,12 @@
+import type { TextStyle } from '../../shapes/Text/StyledText';
+
+export const cloneStyles = (style: TextStyle): TextStyle => {
+  const newObj: TextStyle = {};
+  Object.keys(style).forEach((key) => {
+    newObj[key] = {};
+    Object.keys(style[key]).forEach((keyInner) => {
+      newObj[key][keyInner] = { ...style[key][keyInner] };
+    });
+  });
+  return newObj;
+};

package/src/util/internals/console.ts

@@ -0,0 +1,18 @@
+export const log = (
+  severity: 'log' | 'warn' | 'error',
+  ...optionalParams: any[]
+) =>
+  // eslint-disable-next-line no-restricted-syntax
+  console[severity]('fabric', ...optionalParams);
+
+export class FabricError extends Error {
+  constructor(message?: string, options?: ErrorOptions) {
+    super(`fabric: ${message}`, options);
+  }
+}
+
+export class SignalAbortedError extends FabricError {
+  constructor(context: string) {
+    super(`${context} 'options.signal' is in 'aborted' state`);
+  }
+}

package/src/util/internals/dom_style.spec.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+import { getFabricDocument } from '../../env';
+import { setStyle } from './dom_style';
+
+/**
+ * Running this test in browser mode since jsdom doesn't implement `cssText` properly
+ */
+describe('dom_style', () => {
+  describe('setStyle', () => {
+    it('applies styles to DOM elements from strings and objects', () => {
+      const el = getFabricDocument().createElement('div');
+      setStyle(el, { color: 'yellow', width: '45px' });
+      expect(el.style.color).toBe('yellow');
+      expect(el.style.width).toBe('45px');
+    });
+  });
+});

package/src/util/internals/dom_style.ts

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

package/src/util/internals/findRight.ts

@@ -0,0 +1,11 @@
+export const findIndexRight = <T>(
+  array: T[],
+  predicate: (value: T, index: number, array: T[]) => boolean,
+) => {
+  for (let index = array.length - 1; index >= 0; index--) {
+    if (predicate(array[index], index, array)) {
+      return index;
+    }
+  }
+  return -1;
+};

package/src/util/internals/getRandomInt.test.ts

@@ -0,0 +1,49 @@
+import { getRandomInt } from './getRandomInt';
+import { describe, expect, vi, it, beforeEach, afterEach } from 'vitest';
+
+const originalMathRandom = globalThis.Math.random;
+
+describe('getRandomInt', () => {
+  beforeEach(() => {
+    globalThis.Math.random = vi.fn(() => 0.1);
+  });
+  afterEach(() => {
+    globalThis.Math.random = originalMathRandom;
+  });
+  it('return a number between min and max', () => {
+    vi.mocked(globalThis.Math.random).mockReturnValue(0.1);
+    const semiRandom = getRandomInt(0, 10);
+    expect(semiRandom).toBe(1);
+  });
+  it('it could return min', () => {
+    vi.mocked(globalThis.Math.random).mockReturnValue(0);
+    const semiRandom = getRandomInt(4, 9);
+    expect(semiRandom).toBe(4);
+  });
+  it('it can return max when approaching 1', () => {
+    vi.mocked(globalThis.Math.random).mockReturnValue(0.999999999999999);
+    const semiRandom = getRandomInt(4, 9);
+    expect(semiRandom).toBe(9);
+  });
+  it('thanks to js sillyness could also go out of bounds', () => {
+    // eslint-disable-next-line no-loss-of-precision
+    vi.mocked(globalThis.Math.random).mockReturnValue(0.9999999999999999999);
+    const semiRandom = getRandomInt(4, 9);
+    expect(semiRandom).toBe(10);
+  });
+
+  it('generates random integers within specified range', () => {
+    globalThis.Math.random = originalMathRandom;
+
+    const randomInts: number[] = [];
+    for (let i = 100; i--; ) {
+      const randomInt = getRandomInt(100, 200);
+      randomInts.push(randomInt);
+      expect(randomInt).toBeGreaterThanOrEqual(100);
+      expect(randomInt).toBeLessThanOrEqual(200);
+    }
+
+    const areAllTheSame = randomInts.every((value) => value === randomInts[0]);
+    expect(areAllTheSame).toBeFalsy();
+  });
+});

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/removeFromArray.spec.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from 'vitest';
+import { removeFromArray } from './removeFromArray';
+
+describe('removeFromArray', () => {
+  it('removes elements from arrays correctly', () => {
+    let testArray: (string | number)[] = [1, 2, 3, 4, 5];
+
+    expect(removeFromArray).toBeTypeOf('function');
+
+    removeFromArray(testArray, 2);
+    expect(testArray).toEqual([1, 3, 4, 5]);
+    expect(removeFromArray(testArray, 1)).toBe(testArray);
+
+    testArray = [1, 2, 3, 1];
+    removeFromArray(testArray, 1);
+    expect(testArray).toEqual([2, 3, 1]);
+
+    testArray = [1, 2, 3];
+    removeFromArray(testArray, 12);
+    expect(testArray).toEqual([1, 2, 3]);
+
+    testArray = [];
+    removeFromArray(testArray, 1);
+    expect(testArray).toEqual([]);
+
+    testArray = ['0'];
+    removeFromArray(testArray, 0);
+    expect(testArray).toEqual(['0']);
+  });
+});

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.spec.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+import { capitalize, escapeXml, graphemeSplit } from './lang_string';
+
+describe('lang_string', () => {
+  describe('string.graphemeSplit', () => {
+    it('correctly splits strings including emojis into graphemes', () => {
+      expect(graphemeSplit('foo')).toEqual(['f', 'o', 'o']);
+      expect(graphemeSplit('f🙂o')).toEqual(['f', '🙂', 'o']);
+    });
+
+    it('correctly splits strings including flag emojis into graphmes', () => {
+      expect(graphemeSplit('f🇱🇹🇱🇹o')).toEqual(['f', '🇱🇹', '🇱🇹', 'o']);
+    });
+
+    it('correctly splits strings including new emojis into graphmes', () => {
+      expect(graphemeSplit('f🧚🏿‍♂️o')).toEqual(['f', '🧚🏿‍♂️', 'o']);
+    });
+  });
+
+  describe('string.escapeXml', () => {
+    it('properly escapes XML special characters in strings', () => {
+      // borrowed from Prototype.js
+      expect(escapeXml('foo bar')).toBe('foo bar');
+      expect(escapeXml('foo <span>bar</span>')).toBe(
+        'foo &lt;span&gt;bar&lt;/span&gt;',
+      );
+
+      expect(
+        escapeXml(
+          'a<a href="blah">blub</a>b<span><div></div></span>cdef<strong>!!!!</strong>g',
+        ),
+      ).toBe(
+        'a&lt;a href=&quot;blah&quot;&gt;blub&lt;/a&gt;b&lt;span&gt;&lt;div&gt;&lt;/div&gt;&lt;/span&gt;cdef&lt;strong&gt;!!!!&lt;/strong&gt;g',
+      );
+
+      expect(escapeXml('1\n2')).toBe('1\n2');
+    });
+  });
+
+  describe('string.capitalize', () => {
+    it('correctly capitalizes strings', () => {
+      expect(capitalize('foo')).toBe('Foo');
+      expect(capitalize('')).toBe('');
+      expect(capitalize('Foo')).toBe('Foo');
+      expect(capitalize('foo-bar-baz')).toBe('Foo-bar-baz');
+      expect(capitalize('FOO')).toBe('Foo');
+      expect(capitalize('FoobaR')).toBe('Foobar');
+      expect(capitalize('2foo')).toBe('2foo');
+    });
+  });
+});

package/src/util/lang_string.ts

@@ -0,0 +1,106 @@
+import { getFabricWindow } from '../env';
+
+/**
+ * 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;');
+
+let segmenter: Intl.Segmenter | false;
+
+const getSegmenter = () => {
+  if (!segmenter) {
+    segmenter =
+      'Intl' in getFabricWindow() &&
+      'Segmenter' in Intl &&
+      new Intl.Segmenter(undefined, {
+        granularity: 'grapheme',
+      });
+  }
+  return segmenter;
+};
+
+/**
+ * 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[] => {
+  segmenter || getSegmenter();
+  if (segmenter) {
+    const segments = segmenter.segment(textstring);
+    return Array.from(segments).map(({ segment }) => segment);
+  }
+
+  //Fallback
+  return graphemeSplitImpl(textstring);
+};
+
+const graphemeSplitImpl = (textstring: string): string[] => {
+  const graphemes: string[] = [];
+  for (let i = 0, chr; i < textstring.length; i++) {
+    if ((chr = getWholeChar(textstring, i)) === false) {
+      continue;
+    }
+    graphemes.push(chr);
+  }
+  return graphemes;
+};
+
+// taken from mdn in the charAt doc page.
+const getWholeChar = (str: string, i: number): string | false => {
+  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.spec.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import { Point } from '../../Point';
+import { makeBoundingBoxFromPoints } from './boundingBoxFromPoints';
+
+describe('boundingBoxFromPoints', () => {
+  it('creates correct bounding box from array of points', () => {
+    expect(
+      makeBoundingBoxFromPoints([
+        new Point(50, 50),
+        new Point(-50, 50),
+        new Point(50, -50),
+        new Point(-50, -50),
+        new Point(50, 50),
+        new Point(80, -30),
+        new Point(100, 50),
+      ]),
+      'bbox should match',
+    ).toEqual({
+      left: -50,
+      top: -50,
+      width: 150,
+      height: 100,
+    });
+  });
+});

package/src/util/misc/boundingBoxFromPoints.ts

@@ -0,0 +1,29 @@
+import type { XY } from '../../Point';
+import type { 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 => {
+  let left = 0,
+    top = 0,
+    width = 0,
+    height = 0;
+
+  for (let i = 0, len = points.length; i < len; i++) {
+    const { x, y } = points[i];
+    if (x > width || !i) width = x;
+    if (x < left || !i) left = x;
+    if (y > height || !i) height = y;
+    if (y < top || !i) top = y;
+  }
+
+  return {
+    left,
+    top,
+    width: width - left,
+    height: height - top,
+  };
+};

package/src/util/misc/capValue.spec.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { capValue } from './capValue';
+
+describe('capValue', () => {
+  it('returns uncapped value when within range', () => {
+    expect(typeof capValue === 'function').toBeTruthy();
+    const val = capValue(3, 10, 70);
+    expect(val, 'value is not capped').toBe(10);
+  });
+
+  it('applies minimum cap when value is too low', () => {
+    expect(typeof capValue === 'function').toBeTruthy();
+    const val = capValue(3, 1, 70);
+    expect(val, 'min cap').toBe(3);
+  });
+
+  it('applies maximum cap when value is too high', () => {
+    expect(typeof capValue === 'function').toBeTruthy();
+    const val = capValue(3, 80, 70);
+    expect(val, 'max cap').toBe(70);
+  });
+});

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.spec.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest';
+import { cos } from './cos';
+
+describe('cos', () => {
+  it('calculates cosine values correctly', () => {
+    expect(typeof cos === 'function').toBeTruthy();
+    expect(cos(0), 'cos 0 correct').toBe(1);
+    expect(cos(Math.PI / 2), 'cos 90 correct').toBe(0);
+    expect(cos(Math.PI), 'cos 180 correct').toBe(-1);
+    expect(cos((3 * Math.PI) / 2), 'cos 270 correct').toBe(0);
+  });
+});