fabric 5.3.0 → 6.0.0-beta1

package/src/Collection.ts

@@ -0,0 +1,311 @@
+import type { Constructor } from './typedefs';
+import type { BaseFabricObject } from './EventTypeDefs';
+import { removeFromArray } from './util/internals';
+
+export function createCollectionMixin<TBase extends Constructor>(Base: TBase) {
+  class Collection extends Base {
+    /**
+     * @type {BaseFabricObject[]}
+     * @TODO needs to end up in the constructor too
+     */
+    _objects: BaseFabricObject[] = [];
+
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _onObjectAdded(object: BaseFabricObject) {
+      // subclasses should override this method
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _onObjectRemoved(object: BaseFabricObject) {
+      // subclasses should override this method
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _onStackOrderChanged(object: BaseFabricObject) {
+      // subclasses should override this method
+    }
+
+    /**
+     * Adds objects to collection
+     * Objects should be instances of (or inherit from) BaseFabricObject
+     * @param {...BaseFabricObject[]} objects to add
+     * @returns {number} new array length
+     */
+    add(...objects: BaseFabricObject[]): number {
+      const size = this._objects.push(...objects);
+      objects.forEach((object) => this._onObjectAdded(object));
+      return size;
+    }
+
+    /**
+     * Inserts an object into collection at specified index
+     * @param {number} index Index to insert object at
+     * @param {...BaseFabricObject[]} objects Object(s) to insert
+     * @returns {number} new array length
+     */
+    insertAt(index: number, ...objects: BaseFabricObject[]) {
+      this._objects.splice(index, 0, ...objects);
+      objects.forEach((object) => this._onObjectAdded(object));
+      return this._objects.length;
+    }
+
+    /**
+     * Removes objects from a collection, then renders canvas (if `renderOnAddRemove` is not `false`)
+     * @private
+     * @param {...BaseFabricObject[]} objects objects to remove
+     * @returns {BaseFabricObject[]} removed objects
+     */
+    remove(...objects: BaseFabricObject[]) {
+      const array = this._objects,
+        removed: BaseFabricObject[] = [];
+      objects.forEach((object) => {
+        const index = array.indexOf(object);
+        // only call onObjectRemoved if an object was actually removed
+        if (index !== -1) {
+          array.splice(index, 1);
+          removed.push(object);
+          this._onObjectRemoved(object);
+        }
+      });
+      return removed;
+    }
+
+    /**
+     * Executes given function for each object in this group
+     * A simple shortcut for getObjects().forEach, before es6 was more complicated,
+     * now is just a shortcut.
+     * @param {Function} callback
+     *                   Callback invoked with current object as first argument,
+     *                   index - as second and an array of all objects - as third.
+     */
+    forEachObject(
+      callback: (
+        object: BaseFabricObject,
+        index: number,
+        array: BaseFabricObject[]
+      ) => any
+    ) {
+      this.getObjects().forEach((object, index, objects) =>
+        callback(object, index, objects)
+      );
+    }
+
+    /**
+     * Returns an array of children objects of this instance
+     * @param {...String} [types] When specified, only objects of these types are returned
+     * @return {Array}
+     */
+    getObjects(...types: string[]) {
+      if (types.length === 0) {
+        return [...this._objects];
+      }
+      return this._objects.filter((o) => types.includes(o.type));
+    }
+
+    /**
+     * Returns object at specified index
+     * @param {Number} index
+     * @return {Object} object at index
+     */
+    item(index: number) {
+      return this._objects[index];
+    }
+
+    /**
+     * Returns true if collection contains no objects
+     * @return {Boolean} true if collection is empty
+     */
+    isEmpty() {
+      return this._objects.length === 0;
+    }
+
+    /**
+     * Returns a size of a collection (i.e: length of an array containing its objects)
+     * @return {Number} Collection size
+     */
+    size() {
+      return this._objects.length;
+    }
+
+    /**
+     * Returns true if collection contains an object.\
+     * **Prefer using {@link `BaseFabricObject#isDescendantOf`} for performance reasons**
+     * instead of `a.contains(b)` use `b.isDescendantOf(a)`
+     * @param {Object} object Object to check against
+     * @param {Boolean} [deep=false] `true` to check all descendants, `false` to check only `_objects`
+     * @return {Boolean} `true` if collection contains an object
+     */
+    contains(object: BaseFabricObject, deep?: boolean): boolean {
+      if (this._objects.includes(object)) {
+        return true;
+      } else if (deep) {
+        return this._objects.some(
+          (obj) =>
+            obj instanceof Collection &&
+            (obj as unknown as Collection).contains(object, true)
+        );
+      }
+      return false;
+    }
+
+    /**
+     * Returns number representation of a collection complexity
+     * @return {Number} complexity
+     */
+    complexity() {
+      return this._objects.reduce((memo, current) => {
+        memo += current.complexity ? current.complexity() : 0;
+        return memo;
+      }, 0);
+    }
+
+    /**
+     * Moves an object or the objects of a multiple selection
+     * to the bottom of the stack of drawn objects
+     * @param {fabric.Object} object Object to send to back
+     * @returns {boolean} true if change occurred
+     */
+    sendObjectToBack(object: BaseFabricObject) {
+      if (!object || object === this._objects[0]) {
+        return false;
+      }
+      removeFromArray(this._objects, object);
+      this._objects.unshift(object);
+      this._onStackOrderChanged(object);
+      return true;
+    }
+
+    /**
+     * Moves an object or the objects of a multiple selection
+     * to the top of the stack of drawn objects
+     * @param {fabric.Object} object Object to send
+     * @returns {boolean} true if change occurred
+     */
+    bringObjectToFront(object: BaseFabricObject) {
+      if (!object || object === this._objects[this._objects.length - 1]) {
+        return false;
+      }
+      removeFromArray(this._objects, object);
+      this._objects.push(object);
+      this._onStackOrderChanged(object);
+      return true;
+    }
+
+    /**
+     * Moves an object or a selection down in stack of drawn objects
+     * An optional parameter, `intersecting` allows to move the object in behind
+     * the first intersecting object. Where intersection is calculated with
+     * bounding box. If no intersection is found, there will not be change in the
+     * stack.
+     * @param {fabric.Object} object Object to send
+     * @param {boolean} [intersecting] If `true`, send object behind next lower intersecting object
+     * @returns {boolean} true if change occurred
+     */
+    sendObjectBackwards(object: BaseFabricObject, intersecting?: boolean) {
+      if (!object) {
+        return false;
+      }
+      const idx = this._objects.indexOf(object);
+      if (idx !== 0) {
+        // if object is not on the bottom of stack
+        const newIdx = this.findNewLowerIndex(object, idx, intersecting);
+        removeFromArray(this._objects, object);
+        this._objects.splice(newIdx, 0, object);
+        this._onStackOrderChanged(object);
+        return true;
+      }
+      return false;
+    }
+
+    /**
+     * Moves an object or a selection up in stack of drawn objects
+     * An optional parameter, intersecting allows to move the object in front
+     * of the first intersecting object. Where intersection is calculated with
+     * bounding box. If no intersection is found, there will not be change in the
+     * stack.
+     * @param {fabric.Object} object Object to send
+     * @param {boolean} [intersecting] If `true`, send object in front of next upper intersecting object
+     * @returns {boolean} true if change occurred
+     */
+    bringObjectForward(object: BaseFabricObject, intersecting?: boolean) {
+      if (!object) {
+        return false;
+      }
+      const idx = this._objects.indexOf(object);
+      if (idx !== this._objects.length - 1) {
+        // if object is not on top of stack (last item in an array)
+        const newIdx = this.findNewUpperIndex(object, idx, intersecting);
+        removeFromArray(this._objects, object);
+        this._objects.splice(newIdx, 0, object);
+        this._onStackOrderChanged(object);
+        return true;
+      }
+      return false;
+    }
+
+    /**
+     * Moves an object to specified level in stack of drawn objects
+     * @param {fabric.Object} object Object to send
+     * @param {number} index Position to move to
+     * @returns {boolean} true if change occurred
+     */
+    moveObjectTo(object: BaseFabricObject, index: number) {
+      if (object === this._objects[index]) {
+        return false;
+      }
+      removeFromArray(this._objects, object);
+      this._objects.splice(index, 0, object);
+      this._onStackOrderChanged(object);
+      return true;
+    }
+
+    findNewLowerIndex(
+      object: BaseFabricObject,
+      idx: number,
+      intersecting?: boolean
+    ) {
+      let newIdx;
+
+      if (intersecting) {
+        newIdx = idx;
+        // traverse down the stack looking for the nearest intersecting object
+        for (let i = idx - 1; i >= 0; --i) {
+          if (object.isOverlapping(this._objects[i])) {
+            newIdx = i;
+            break;
+          }
+        }
+      } else {
+        newIdx = idx - 1;
+      }
+
+      return newIdx;
+    }
+
+    findNewUpperIndex(
+      object: BaseFabricObject,
+      idx: number,
+      intersecting?: boolean
+    ) {
+      let newIdx;
+
+      if (intersecting) {
+        newIdx = idx;
+        // traverse up the stack looking for the nearest intersecting object
+        for (let i = idx + 1; i < this._objects.length; ++i) {
+          if (object.isOverlapping(this._objects[i])) {
+            newIdx = i;
+            break;
+          }
+        }
+      } else {
+        newIdx = idx + 1;
+      }
+
+      return newIdx;
+    }
+  }
+
+  // https://github.com/microsoft/TypeScript/issues/32080
+  return Collection as typeof Collection & TBase;
+}

package/src/CommonMethods.ts

@@ -0,0 +1,63 @@
+//@ts-nocheck
+import { Observable } from './Observable';
+
+export class CommonMethods<EventSpec> extends Observable<EventSpec> {
+  /**
+   * Sets object's properties from options, for initialization only
+   * @protected
+   * @param {Object} [options] Options object
+   */
+  protected _setOptions(options: any = {}) {
+    for (const prop in options) {
+      this.set(prop, options[prop]);
+    }
+  }
+
+  /**
+   * @private
+   */
+  _setObject(obj: Record<string, any>) {
+    for (const prop in obj) {
+      this._set(prop, obj[prop]);
+    }
+  }
+
+  /**
+   * Sets property to a given value. When changing position/dimension -related properties (left, top, scale, angle, etc.) `set` does not update position of object's borders/controls. If you need to update those, call `setCoords()`.
+   * @param {String|Object} key Property name or object (if object, iterate over the object properties)
+   * @param {Object|Function} value Property value (if function, the value is passed into it and its return value is used as a new one)
+   */
+  set(key: string | Record<string, any>, value?: any) {
+    if (typeof key === 'object') {
+      this._setObject(key);
+    } else {
+      this._set(key, value);
+    }
+    return this;
+  }
+
+  _set(key: string, value: any) {
+    this[key] = value;
+  }
+
+  /**
+   * Toggles specified property from `true` to `false` or from `false` to `true`
+   * @param {String} property Property to toggle
+   */
+  toggle(property: string) {
+    const value = this.get(property);
+    if (typeof value === 'boolean') {
+      this.set(property, !value);
+    }
+    return this;
+  }
+
+  /**
+   * Basic getter
+   * @param {String} property Property name
+   * @return {*} value of a property
+   */
+  get(property: string) {
+    return this[property];
+  }
+}

package/src/EventTypeDefs.ts

@@ -0,0 +1,294 @@
+import type { Control } from './controls/Control';
+import type { Point } from './Point';
+import type { FabricObject } from './shapes/Object/FabricObject';
+import type { FabricObject as StaticFabricObject } from './shapes/Object/Object';
+import type { FabricObjectSVGExportMixin } from './shapes/Object/FabricObjectSVGExportMixin';
+import type { Group } from './shapes/Group';
+import type { TOriginX, TOriginY, TRadian } from './typedefs';
+import type { saveObjectTransform } from './util/misc/objectTransforms';
+import type { Canvas } from './canvas/Canvas';
+import type { IText } from './shapes/IText/IText';
+import type { StaticCanvas } from './canvas/StaticCanvas';
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface, @typescript-eslint/no-unused-vars
+export interface BaseFabricObject
+  extends StaticFabricObject,
+    FabricObjectSVGExportMixin {}
+
+export type ModifierKey = keyof Pick<
+  MouseEvent | PointerEvent | TouchEvent,
+  'altKey' | 'shiftKey' | 'ctrlKey' | 'metaKey'
+>;
+
+export type TOptionalModifierKey = ModifierKey | null | undefined;
+
+export type TPointerEvent = MouseEvent | TouchEvent | PointerEvent;
+
+export type TransformAction<T extends Transform = Transform, R = void> = (
+  eventData: TPointerEvent,
+  transform: T,
+  x: number,
+  y: number
+) => R;
+
+/**
+ * Control handlers that define a transformation
+ * Those handlers run when the user starts a transform and during a transform
+ */
+export type TransformActionHandler<T extends Transform = Transform> =
+  TransformAction<T, boolean>;
+
+/**
+ * Control handlers that run on control click/down/up
+ * Those handlers run with or without a transform defined
+ */
+export type ControlActionHandler = TransformAction<Transform, any>;
+
+export type ControlCallback<R = void> = (
+  eventData: TPointerEvent,
+  control: Control,
+  fabricObject: FabricObject
+) => R;
+
+export type ControlCursorCallback = ControlCallback<string>;
+
+/**
+ * relative to target's containing coordinate plane
+ * both agree on every point
+ */
+export type Transform = {
+  target: FabricObject;
+  action: string;
+  actionHandler?: TransformActionHandler;
+  corner: string | 0;
+  scaleX: number;
+  scaleY: number;
+  skewX: number;
+  skewY: number;
+  offsetX: number;
+  offsetY: number;
+  originX: TOriginX;
+  originY: TOriginY;
+  ex: number;
+  ey: number;
+  lastX: number;
+  lastY: number;
+  theta: TRadian;
+  width: number;
+  height: number;
+  shiftKey: boolean;
+  altKey: boolean;
+  original: ReturnType<typeof saveObjectTransform> & {
+    originX: TOriginX;
+    originY: TOriginY;
+  };
+  actionPerformed: boolean;
+};
+
+export type TEvent<E extends Event = TPointerEvent> = {
+  e: E;
+};
+
+type TEventWithTarget<E extends Event = TPointerEvent> = TEvent<E> & {
+  target: FabricObject;
+};
+
+export type BasicTransformEvent<E extends Event = TPointerEvent> = TEvent<E> & {
+  transform: Transform;
+  pointer: Point;
+};
+
+export type TModificationEvents =
+  | 'moving'
+  | 'scaling'
+  | 'rotating'
+  | 'skewing'
+  | 'resizing';
+
+export type ModifiedEvent<E extends Event = TPointerEvent> = TEvent<E> & {
+  transform: Transform;
+  target: FabricObject;
+  action: string;
+};
+
+type ModificationEventsSpec<
+  Prefix extends string = '',
+  Modification = BasicTransformEvent,
+  Modified = ModifiedEvent | never
+> = Record<`${Prefix}${TModificationEvents}`, Modification> &
+  Record<`${Prefix}modified`, Modified>;
+
+type ObjectModificationEvents = ModificationEventsSpec;
+
+type CanvasModificationEvents = ModificationEventsSpec<
+  'object:',
+  BasicTransformEvent & { target: FabricObject },
+  ModifiedEvent | { target: FabricObject }
+> & {
+  'before:transform': TEvent & { transform: Transform };
+};
+
+export type TPointerEventInfo<E extends TPointerEvent = TPointerEvent> =
+  TEvent<E> & {
+    target?: FabricObject;
+    subTargets?: FabricObject[];
+    button?: number;
+    isClick: boolean;
+    pointer: Point;
+    transform?: Transform | null;
+    absolutePointer: Point;
+    currentSubTargets?: FabricObject[];
+    currentTarget?: FabricObject | null;
+  };
+
+type SimpleEventHandler<T extends Event = TPointerEvent> = TEvent<T> & {
+  target?: FabricObject;
+  subTargets: FabricObject[];
+};
+
+type InEvent = {
+  previousTarget?: FabricObject;
+};
+
+type OutEvent = {
+  nextTarget?: FabricObject;
+};
+
+export type DragEventData = TEvent<DragEvent> & {
+  target?: FabricObject;
+  subTargets?: FabricObject[];
+  dragSource?: FabricObject;
+  canDrop?: boolean;
+  didDrop?: boolean;
+  dropTarget?: FabricObject;
+};
+
+export type DropEventData = DragEventData & { pointer: Point };
+
+type DnDEvents = {
+  dragstart: TEventWithTarget<DragEvent>;
+  drag: DragEventData;
+  dragover: DragEventData;
+  dragenter: DragEventData & InEvent;
+  dragleave: DragEventData & OutEvent;
+  dragend: DragEventData;
+  'drop:before': DropEventData;
+  drop: DropEventData;
+  'drop:after': DropEventData;
+};
+
+type CanvasDnDEvents = DnDEvents & {
+  'drag:enter': DragEventData & InEvent;
+  'drag:leave': DragEventData & OutEvent;
+};
+
+type CanvasSelectionEvents = {
+  'selection:created': Partial<TEvent> & {
+    selected: FabricObject[];
+  };
+  'selection:updated': Partial<TEvent> & {
+    selected: FabricObject[];
+    deselected: FabricObject[];
+  };
+  'before:selection:cleared': Partial<TEvent> & {
+    deselected: FabricObject[];
+  };
+  'selection:cleared': Partial<TEvent> & {
+    deselected: FabricObject[];
+  };
+};
+
+export type CollectionEvents = {
+  'object:added': { target: StaticFabricObject };
+  'object:removed': { target: StaticFabricObject };
+};
+
+type BeforeSuffix<T extends string> = `${T}:before`;
+type WithBeforeSuffix<T extends string> = T | BeforeSuffix<T>;
+
+type TPointerEvents<Prefix extends string> = Record<
+  `${Prefix}${
+    | WithBeforeSuffix<'down'>
+    | WithBeforeSuffix<'move'>
+    | WithBeforeSuffix<'up'>
+    | 'dblclick'}`,
+  TPointerEventInfo
+> &
+  Record<`${Prefix}wheel`, TPointerEventInfo<WheelEvent>> &
+  Record<`${Prefix}over`, TPointerEventInfo & InEvent> &
+  Record<`${Prefix}out`, TPointerEventInfo & OutEvent>;
+
+export type TPointerEventNames =
+  | WithBeforeSuffix<'down'>
+  | WithBeforeSuffix<'move'>
+  | WithBeforeSuffix<'up'>
+  | 'dblclick'
+  | 'wheel';
+
+export type ObjectPointerEvents = TPointerEvents<'mouse'>;
+export type CanvasPointerEvents = TPointerEvents<'mouse:'>;
+
+export type MiscEvents = {
+  'contextmenu:before': SimpleEventHandler<Event>;
+  contextmenu: SimpleEventHandler<Event>;
+};
+
+export type ObjectEvents = ObjectPointerEvents &
+  DnDEvents &
+  MiscEvents &
+  ObjectModificationEvents & {
+    // selection
+    selected: Partial<TEvent> & {
+      target: FabricObject;
+    };
+    deselected: Partial<TEvent> & {
+      target: FabricObject;
+    };
+
+    // tree
+    added: { target: Group | Canvas | StaticCanvas };
+    removed: { target: Group | Canvas | StaticCanvas };
+
+    // erasing
+    'erasing:end': { path: FabricObject };
+  };
+
+export type StaticCanvasEvents = CollectionEvents & {
+  // tree
+  'canvas:cleared': never;
+
+  // rendering
+  'before:render': { ctx: CanvasRenderingContext2D };
+  'after:render': { ctx: CanvasRenderingContext2D };
+};
+
+export type CanvasEvents = StaticCanvasEvents &
+  CanvasPointerEvents &
+  CanvasDnDEvents &
+  MiscEvents &
+  CanvasModificationEvents &
+  CanvasSelectionEvents & {
+    // brushes
+    'before:path:created': { path: FabricObject };
+    'path:created': { path: FabricObject };
+
+    // erasing
+    'erasing:start': never;
+    'erasing:end':
+      | never
+      | {
+          path: FabricObject;
+          targets: FabricObject[];
+          subTargets: FabricObject[];
+          drawables: {
+            backgroundImage?: FabricObject;
+            overlayImage?: FabricObject;
+          };
+        };
+
+    // IText
+    'text:selection:changed': { target: IText };
+    'text:changed': { target: IText };
+    'text:editing:entered': { target: IText };
+    'text:editing:exited': { target: IText };
+  };