fabric 5.3.0 → 6.0.0-beta3

package/src/shapes/ActiveSelection.ts

@@ -0,0 +1,189 @@
+import type { ControlRenderingStyleOverride } from '../controls/controlRendering';
+import { classRegistry } from '../ClassRegistry';
+import { Group } from './Group';
+import type { FabricObject } from './Object/FabricObject';
+
+export class ActiveSelection extends Group {
+  declare _objects: FabricObject[];
+
+  /**
+   * controls how selected objects are added during a multiselection event
+   * - `canvas-stacking` adds the selected object to the active selection while respecting canvas object stacking order
+   * - `selection-order` adds the selected object to the top of the stack,
+   * meaning that the stack is ordered by the order in which objects were selected
+   * @default `canvas-stacking`
+   */
+  multiSelectionStacking: 'canvas-stacking' | 'selection-order' =
+    'canvas-stacking';
+
+  constructor(
+    objects?: FabricObject[],
+    options?: any,
+    objectsRelativeToGroup?: boolean
+  ) {
+    super(objects, options, objectsRelativeToGroup);
+    this.setCoords();
+  }
+
+  /**
+   * @private
+   */
+  _shouldSetNestedCoords() {
+    return true;
+  }
+
+  /**
+   * @private
+   * @override we don't want the selection monitor to be active
+   */
+  __objectSelectionMonitor() {
+    //  noop
+  }
+
+  /**
+   * Adds objects with respect to {@link multiSelectionStacking}
+   * @param targets object to add to selection
+   */
+  multiSelectAdd(...targets: FabricObject[]) {
+    if (this.multiSelectionStacking === 'selection-order') {
+      this.add(...targets);
+    } else {
+      //  respect object stacking as it is on canvas
+      //  perf enhancement for large ActiveSelection: consider a binary search of `isInFrontOf`
+      targets.forEach((target) => {
+        const index = this._objects.findIndex((obj) => obj.isInFrontOf(target));
+        const insertAt =
+          index === -1
+            ? //  `target` is in front of all other objects
+              this.size()
+            : index;
+        this.insertAt(insertAt, target);
+      });
+    }
+  }
+
+  /**
+   * @private
+   * @param {FabricObject} object
+   * @param {boolean} [removeParentTransform] true if object is in canvas coordinate plane
+   * @returns {boolean} true if object entered group
+   */
+  enterGroup(object: FabricObject, removeParentTransform?: boolean) {
+    if (object.group) {
+      //  save ref to group for later in order to return to it
+      const parent = object.group;
+      parent._exitGroup(object);
+      object.__owningGroup = parent;
+    }
+    this._enterGroup(object, removeParentTransform);
+    return true;
+  }
+
+  /**
+   * we want objects to retain their canvas ref when exiting instance
+   * @private
+   * @param {FabricObject} object
+   * @param {boolean} [removeParentTransform] true if object should exit group without applying group's transform to it
+   */
+  exitGroup(object: FabricObject, removeParentTransform?: boolean) {
+    this._exitGroup(object, removeParentTransform);
+    const parent = object.__owningGroup;
+    if (parent) {
+      //  return to owning group
+      parent._enterGroup(object, true);
+      delete object.__owningGroup;
+    }
+  }
+
+  /**
+   * @private
+   * @param {'added'|'removed'} type
+   * @param {FabricObject[]} targets
+   */
+  _onAfterObjectsChange(type: 'added' | 'removed', targets: FabricObject[]) {
+    super._onAfterObjectsChange(type, targets);
+    const groups: Group[] = [];
+    targets.forEach((object) => {
+      object.group &&
+        !groups.includes(object.group) &&
+        groups.push(object.group);
+    });
+    if (type === 'removed') {
+      //  invalidate groups' layout and mark as dirty
+      groups.forEach((group) => {
+        group._onAfterObjectsChange('added', targets);
+      });
+    } else {
+      //  mark groups as dirty
+      groups.forEach((group) => {
+        group._set('dirty', true);
+      });
+    }
+  }
+
+  /**
+   * If returns true, deselection is cancelled.
+   * @since 2.0.0
+   * @return {Boolean} [cancel]
+   */
+  onDeselect() {
+    this.removeAll();
+    return false;
+  }
+
+  /**
+   * Returns string representation of a group
+   * @return {String}
+   */
+  toString() {
+    return `#<ActiveSelection: (${this.complexity()})>`;
+  }
+
+  /**
+   * Decide if the object should cache or not. Create its own cache level
+   * objectCaching is a global flag, wins over everything
+   * needsItsOwnCache should be used when the object drawing method requires
+   * a cache step. None of the fabric classes requires it.
+   * Generally you do not cache objects in groups because the group outside is cached.
+   * @return {Boolean}
+   */
+  shouldCache() {
+    return false;
+  }
+
+  /**
+   * Check if this group or its parent group are caching, recursively up
+   * @return {Boolean}
+   */
+  isOnACache() {
+    return false;
+  }
+
+  /**
+   * Renders controls and borders for the object
+   * @param {CanvasRenderingContext2D} ctx Context to render on
+   * @param {Object} [styleOverride] properties to override the object style
+   * @param {Object} [childrenOverride] properties to override the children overrides
+   */
+  _renderControls(
+    ctx: CanvasRenderingContext2D,
+    styleOverride?: ControlRenderingStyleOverride,
+    childrenOverride?: ControlRenderingStyleOverride
+  ) {
+    ctx.save();
+    ctx.globalAlpha = this.isMoving ? this.borderOpacityWhenMoving : 1;
+    super._renderControls(ctx, styleOverride);
+    const options = {
+      hasControls: false,
+      ...childrenOverride,
+      forActiveSelection: true,
+    };
+    for (let i = 0; i < this._objects.length; i++) {
+      this._objects[i]._renderControls(ctx, options);
+    }
+    ctx.restore();
+  }
+}
+
+classRegistry.setClass(ActiveSelection);
+classRegistry.setClass(ActiveSelection, 'activeSelection');

package/src/shapes/Circle.ts

@@ -0,0 +1,242 @@
+import type { ObjectEvents } from '../EventTypeDefs';
+import { SHARED_ATTRIBUTES } from '../parser/attributes';
+import { parseAttributes } from '../parser/parseAttributes';
+import { cos } from '../util/misc/cos';
+import { degreesToRadians } from '../util/misc/radiansDegreesConversion';
+import { sin } from '../util/misc/sin';
+import { classRegistry } from '../ClassRegistry';
+import { FabricObject, cacheProperties } from './Object/FabricObject';
+import { TClassProperties } from '../typedefs';
+import {
+  FabricObjectProps,
+  SerializedObjectProps,
+  TProps,
+} from './Object/types';
+
+interface UniqueCircleProps {
+  /**
+   * Radius of this circle
+   * @type Number
+   * @default 0
+   */
+  radius: number;
+
+  /**
+   * degrees of start of the circle.
+   * probably will change to degrees in next major version
+   * @type Number 0 - 359
+   * @default 0
+   */
+  startAngle: number;
+
+  /**
+   * End angle of the circle
+   * probably will change to degrees in next major version
+   * @type Number 1 - 360
+   * @default 360
+   */
+  endAngle: number;
+}
+
+export interface SerializedCircleProps
+  extends SerializedObjectProps,
+    UniqueCircleProps {}
+
+export interface CircleProps extends FabricObjectProps, UniqueCircleProps {}
+
+const CIRCLE_PROPS = ['radius', 'startAngle', 'endAngle'] as const;
+
+export const circleDefaultValues: UniqueCircleProps = {
+  radius: 0,
+  startAngle: 0,
+  endAngle: 360,
+};
+
+export class Circle<
+    Props extends TProps<CircleProps> = Partial<CircleProps>,
+    SProps extends SerializedCircleProps = SerializedCircleProps,
+    EventSpec extends ObjectEvents = ObjectEvents
+  >
+  extends FabricObject<Props, SProps, EventSpec>
+  implements UniqueCircleProps
+{
+  declare radius: number;
+  declare startAngle: number;
+  declare endAngle: number;
+
+  static cacheProperties = [...cacheProperties, ...CIRCLE_PROPS];
+
+  static ownDefaults: Record<string, any> = circleDefaultValues;
+
+  static getDefaults(): Record<string, any> {
+    return {
+      ...super.getDefaults(),
+      ...Circle.ownDefaults,
+    };
+  }
+
+  /**
+   * @private
+   * @param {String} key
+   * @param {*} value
+   */
+  _set(key: string, value: any) {
+    super._set(key, value);
+
+    if (key === 'radius') {
+      this.setRadius(value);
+    }
+
+    return this;
+  }
+
+  /**
+   * @private
+   * @param {CanvasRenderingContext2D} ctx context to render on
+   */
+  _render(ctx: CanvasRenderingContext2D) {
+    ctx.beginPath();
+    ctx.arc(
+      0,
+      0,
+      this.radius,
+      degreesToRadians(this.startAngle),
+      degreesToRadians(this.endAngle),
+      false
+    );
+    this._renderPaintInOrder(ctx);
+  }
+
+  /**
+   * Returns horizontal radius of an object (according to how an object is scaled)
+   * @return {Number}
+   */
+  getRadiusX(): number {
+    return this.get('radius') * this.get('scaleX');
+  }
+
+  /**
+   * Returns vertical radius of an object (according to how an object is scaled)
+   * @return {Number}
+   */
+  getRadiusY(): number {
+    return this.get('radius') * this.get('scaleY');
+  }
+
+  /**
+   * Sets radius of an object (and updates width accordingly)
+   */
+  setRadius(value: number) {
+    this.radius = value;
+    this.set({ width: value * 2, height: value * 2 });
+  }
+
+  /**
+   * Returns object representation of an instance
+   * @param {Array} [propertiesToInclude] Any properties that you might want to additionally include in the output
+   * @return {Object} object representation of an instance
+   */
+  toObject<
+    T extends Omit<Props & TClassProperties<this>, keyof SProps>,
+    K extends keyof T = never
+  >(propertiesToInclude: K[] = []): Pick<T, K> & SProps {
+    return super.toObject([...CIRCLE_PROPS, ...propertiesToInclude]);
+  }
+
+  /* _TO_SVG_START_ */
+
+  /**
+   * Returns svg representation of an instance
+   * @return {Array} an array of strings with the specific svg representation
+   * of the instance
+   */
+  _toSVG(): (string | number)[] {
+    const angle = (this.endAngle - this.startAngle) % 360;
+
+    if (angle === 0) {
+      return [
+        '<circle ',
+        'COMMON_PARTS',
+        'cx="0" cy="0" ',
+        'r="',
+        this.radius,
+        '" />\n',
+      ];
+    } else {
+      const { radius } = this;
+      const start = degreesToRadians(this.startAngle),
+        end = degreesToRadians(this.endAngle),
+        startX = cos(start) * radius,
+        startY = sin(start) * radius,
+        endX = cos(end) * radius,
+        endY = sin(end) * radius,
+        largeFlag = angle > 180 ? '1' : '0';
+      return [
+        `<path d="M ${startX} ${startY}`,
+        ` A ${radius} ${radius}`,
+        ' 0 ',
+        `${largeFlag} 1`,
+        ` ${endX} ${endY}`,
+        '" ',
+        'COMMON_PARTS',
+        ' />\n',
+      ];
+    }
+  }
+  /* _TO_SVG_END_ */
+
+  /* _FROM_SVG_START_ */
+  /**
+   * List of attribute names to account for when parsing SVG element (used by {@link Circle.fromElement})
+   * @static
+   * @memberOf Circle
+   * @see: http://www.w3.org/TR/SVG/shapes.html#CircleElement
+   */
+  static ATTRIBUTE_NAMES = ['cx', 'cy', 'r', ...SHARED_ATTRIBUTES];
+
+  /**
+   * Returns {@link Circle} instance from an SVG element
+   * @static
+   * @memberOf Circle
+   * @param {SVGElement} element Element to parse
+   * @param {Function} [callback] Options callback invoked after parsing is finished
+   * @param {Object} [options] Partial Circle object to default missing properties on the element.
+   * @throws {Error} If value of `r` attribute is missing or invalid
+   */
+  static fromElement(element: SVGElement, callback: (circle: Circle) => any) {
+    const {
+      left = 0,
+      top = 0,
+      radius,
+      ...otherParsedAttributes
+    } = parseAttributes(element, this.ATTRIBUTE_NAMES) as Partial<CircleProps>;
+
+    if (!radius || radius < 0) {
+      throw new Error(
+        'value of `r` attribute is required and can not be negative'
+      );
+    }
+
+    // this probably requires to be fixed for default origins not being top/left.
+    callback(
+      new this({
+        ...otherParsedAttributes,
+        radius,
+        left: left - radius,
+        top: top - radius,
+      })
+    );
+  }
+
+  /* _FROM_SVG_END_ */
+
+  /**
+   * @todo how do we declare this??
+   */
+  static fromObject<T extends TProps<SerializedCircleProps>>(object: T) {
+    return super._fromObject<Circle>(object);
+  }
+}
+
+classRegistry.setClass(Circle);
+classRegistry.setSVGClass(Circle);

package/src/shapes/Ellipse.ts

@@ -0,0 +1,179 @@
+import { twoMathPi } from '../constants';
+import { SHARED_ATTRIBUTES } from '../parser/attributes';
+import { parseAttributes } from '../parser/parseAttributes';
+import { TClassProperties } from '../typedefs';
+import { classRegistry } from '../ClassRegistry';
+import { FabricObject, cacheProperties } from './Object/FabricObject';
+import type {
+  FabricObjectProps,
+  SerializedObjectProps,
+  TProps,
+} from './Object/types';
+import type { ObjectEvents } from '../EventTypeDefs';
+
+export const ellipseDefaultValues: UniqueEllipseProps = {
+  rx: 0,
+  ry: 0,
+};
+
+interface UniqueEllipseProps {
+  rx: number;
+  ry: number;
+}
+
+export interface SerializedEllipseProps
+  extends SerializedObjectProps,
+    UniqueEllipseProps {}
+
+export interface EllipseProps extends FabricObjectProps, UniqueEllipseProps {}
+
+const ELLIPSE_PROPS = ['rx', 'ry'] as const;
+
+export class Ellipse<
+    Props extends TProps<EllipseProps> = Partial<EllipseProps>,
+    SProps extends SerializedEllipseProps = SerializedEllipseProps,
+    EventSpec extends ObjectEvents = ObjectEvents
+  >
+  extends FabricObject<Props, SProps, EventSpec>
+  implements EllipseProps
+{
+  /**
+   * Horizontal radius
+   * @type Number
+   * @default
+   */
+  declare rx: number;
+
+  /**
+   * Vertical radius
+   * @type Number
+   * @default
+   */
+  declare ry: number;
+
+  static cacheProperties = [...cacheProperties, ...ELLIPSE_PROPS];
+
+  static ownDefaults: Record<string, any> = ellipseDefaultValues;
+
+  static getDefaults() {
+    return {
+      ...super.getDefaults(),
+      ...Ellipse.ownDefaults,
+    };
+  }
+
+  /**
+   * @private
+   * @param {String} key
+   * @param {*} value
+   * @return {Ellipse} thisArg
+   */
+  _set(key: string, value: any) {
+    super._set(key, value);
+    switch (key) {
+      case 'rx':
+        this.rx = value;
+        this.set('width', value * 2);
+        break;
+
+      case 'ry':
+        this.ry = value;
+        this.set('height', value * 2);
+        break;
+    }
+    return this;
+  }
+
+  /**
+   * Returns horizontal radius of an object (according to how an object is scaled)
+   * @return {Number}
+   */
+  getRx() {
+    return this.get('rx') * this.get('scaleX');
+  }
+
+  /**
+   * Returns Vertical radius of an object (according to how an object is scaled)
+   * @return {Number}
+   */
+  getRy() {
+    return this.get('ry') * this.get('scaleY');
+  }
+
+  /**
+   * Returns object representation of an instance
+   * @param {Array} [propertiesToInclude] Any properties that you might want to additionally include in the output
+   * @return {Object} object representation of an instance
+   */
+  toObject<
+    T extends Omit<Props & TClassProperties<this>, keyof SProps>,
+    K extends keyof T = never
+  >(propertiesToInclude: K[] = []): Pick<T, K> & SProps {
+    return super.toObject([...ELLIPSE_PROPS, ...propertiesToInclude]);
+  }
+
+  /**
+   * Returns svg representation of an instance
+   * @return {Array} an array of strings with the specific svg representation
+   * of the instance
+   */
+  _toSVG() {
+    return [
+      '<ellipse ',
+      'COMMON_PARTS',
+      'cx="0" cy="0" ',
+      'rx="',
+      this.rx,
+      '" ry="',
+      this.ry,
+      '" />\n',
+    ];
+  }
+
+  /**
+   * @private
+   * @param {CanvasRenderingContext2D} ctx context to render on
+   */
+  _render(ctx: CanvasRenderingContext2D) {
+    ctx.beginPath();
+    ctx.save();
+    ctx.transform(1, 0, 0, this.ry / this.rx, 0, 0);
+    ctx.arc(0, 0, this.rx, 0, twoMathPi, false);
+    ctx.restore();
+    this._renderPaintInOrder(ctx);
+  }
+
+  /* _FROM_SVG_START_ */
+
+  /**
+   * List of attribute names to account for when parsing SVG element (used by {@link Ellipse.fromElement})
+   * @static
+   * @memberOf Ellipse
+   * @see http://www.w3.org/TR/SVG/shapes.html#EllipseElement
+   */
+  static ATTRIBUTE_NAMES = [...SHARED_ATTRIBUTES, 'cx', 'cy', 'rx', 'ry'];
+
+  /**
+   * Returns {@link Ellipse} instance from an SVG element
+   * @static
+   * @memberOf Ellipse
+   * @param {SVGElement} element Element to parse
+   * @param {Function} [callback] Options callback invoked after parsing is finished
+   * @return {Ellipse}
+   */
+  static fromElement(
+    element: SVGElement,
+    callback: (ellipse: Ellipse) => void
+  ) {
+    const parsedAttributes = parseAttributes(element, this.ATTRIBUTE_NAMES);
+
+    parsedAttributes.left = (parsedAttributes.left || 0) - parsedAttributes.rx;
+    parsedAttributes.top = (parsedAttributes.top || 0) - parsedAttributes.ry;
+    callback(new this(parsedAttributes));
+  }
+
+  /* _FROM_SVG_END_ */
+}
+
+classRegistry.setClass(Ellipse);
+classRegistry.setSVGClass(Ellipse);