fabric 5.3.0 → 6.0.0-beta1

package/src/controls/Control.ts

@@ -0,0 +1,377 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { halfPI } from '../constants';
+import {
+  ControlActionHandler,
+  TPointerEvent,
+  TransformActionHandler,
+} from '../EventTypeDefs';
+import { Point } from '../Point';
+import type { FabricObject } from '../shapes/Object/Object';
+import { TDegree, TMat2D } from '../typedefs';
+import { cos } from '../util/misc/cos';
+import { degreesToRadians } from '../util/misc/radiansDegreesConversion';
+import { sin } from '../util/misc/sin';
+import {
+  ControlRenderingStyleOverride,
+  renderCircleControl,
+  renderSquareControl,
+} from './controls.render';
+
+export class Control {
+  /**
+   * keep track of control visibility.
+   * mainly for backward compatibility.
+   * if you do not want to see a control, you can remove it
+   * from the control set.
+   * @type {Boolean}
+   * @default true
+   */
+  visible = true;
+
+  /**
+   * Name of the action that the control will likely execute.
+   * This is optional. FabricJS uses to identify what the user is doing for some
+   * extra optimizations. If you are writing a custom control and you want to know
+   * somewhere else in the code what is going on, you can use this string here.
+   * you can also provide a custom getActionName if your control run multiple actions
+   * depending on some external state.
+   * default to scale since is the most common, used on 4 corners by default
+   * @type {String}
+   * @default 'scale'
+   */
+  actionName = 'scale';
+
+  /**
+   * Drawing angle of the control.
+   * NOT used for now, but name marked as needed for internal logic
+   * example: to reuse the same drawing function for different rotated controls
+   * @type {Number}
+   * @default 0
+   */
+  angle = 0;
+
+  /**
+   * Relative position of the control. X
+   * 0,0 is the center of the Object, while -0.5 (left) or 0.5 (right) are the extremities
+   * of the bounding box.
+   * @type {Number}
+   * @default 0
+   */
+  x = 0;
+
+  /**
+   * Relative position of the control. Y
+   * 0,0 is the center of the Object, while -0.5 (top) or 0.5 (bottom) are the extremities
+   * of the bounding box.
+   * @type {Number}
+   * @default 0
+   */
+  y = 0;
+
+  /**
+   * Horizontal offset of the control from the defined position. In pixels
+   * Positive offset moves the control to the right, negative to the left.
+   * It used when you want to have position of control that does not scale with
+   * the bounding box. Example: rotation control is placed at x:0, y: 0.5 on
+   * the boundind box, with an offset of 30 pixels vertically. Those 30 pixels will
+   * stay 30 pixels no matter how the object is big. Another example is having 2
+   * controls in the corner, that stay in the same position when the object scale.
+   * of the bounding box.
+   * @type {Number}
+   * @default 0
+   */
+  offsetX = 0;
+
+  /**
+   * Vertical offset of the control from the defined position. In pixels
+   * Positive offset moves the control to the bottom, negative to the top.
+   * @type {Number}
+   * @default 0
+   */
+  offsetY = 0;
+
+  /**
+   * Sets the length of the control. If null, defaults to object's cornerSize.
+   * Expects both sizeX and sizeY to be set when set.
+   * @type {?Number}
+   * @default null
+   */
+  sizeX: number | null = null;
+
+  /**
+   * Sets the height of the control. If null, defaults to object's cornerSize.
+   * Expects both sizeX and sizeY to be set when set.
+   * @type {?Number}
+   * @default null
+   */
+  sizeY: number | null = null;
+
+  /**
+   * Sets the length of the touch area of the control. If null, defaults to object's touchCornerSize.
+   * Expects both touchSizeX and touchSizeY to be set when set.
+   * @type {?Number}
+   * @default null
+   */
+  touchSizeX: number | null = null;
+
+  /**
+   * Sets the height of the touch area of the control. If null, defaults to object's touchCornerSize.
+   * Expects both touchSizeX and touchSizeY to be set when set.
+   * @type {?Number}
+   * @default null
+   */
+  touchSizeY: number | null = null;
+
+  /**
+   * Css cursor style to display when the control is hovered.
+   * if the method `cursorStyleHandler` is provided, this property is ignored.
+   * @type {String}
+   * @default 'crosshair'
+   */
+  cursorStyle = 'crosshair';
+
+  /**
+   * If controls has an offsetY or offsetX, draw a line that connects
+   * the control to the bounding box
+   * @type {Boolean}
+   * @default false
+   */
+  withConnection = false;
+
+  constructor(options: Partial<Control>) {
+    Object.assign(this, options);
+  }
+
+  /**
+   * The control actionHandler, provide one to handle action ( control being moved )
+   * @param {Event} eventData the native mouse event
+   * @param {Transform} transformData properties of the current transform
+   * @param {Number} x x position of the cursor
+   * @param {Number} y y position of the cursor
+   * @return {Boolean} true if the action/event modified the object
+   */
+  declare actionHandler: TransformActionHandler;
+
+  /**
+   * The control handler for mouse down, provide one to handle mouse down on control
+   * @param {Event} eventData the native mouse event
+   * @param {Transform} transformData properties of the current transform
+   * @param {Number} x x position of the cursor
+   * @param {Number} y y position of the cursor
+   * @return {Boolean} true if the action/event modified the object
+   */
+  declare mouseDownHandler?: ControlActionHandler;
+
+  /**
+   * The control mouseUpHandler, provide one to handle an effect on mouse up.
+   * @param {Event} eventData the native mouse event
+   * @param {Transform} transformData properties of the current transform
+   * @param {Number} x x position of the cursor
+   * @param {Number} y y position of the cursor
+   * @return {Boolean} true if the action/event modified the object
+   */
+  declare mouseUpHandler?: ControlActionHandler;
+
+  /**
+   * Returns control actionHandler
+   * @param {Event} eventData the native mouse event
+   * @param {FabricObject} fabricObject on which the control is displayed
+   * @param {Control} control control for which the action handler is being asked
+   * @return {Function} the action handler
+   */
+  getActionHandler(
+    eventData: TPointerEvent,
+    fabricObject: FabricObject,
+    control: Control
+  ): TransformActionHandler | undefined {
+    return this.actionHandler;
+  }
+
+  /**
+   * Returns control mouseDown handler
+   * @param {Event} eventData the native mouse event
+   * @param {FabricObject} fabricObject on which the control is displayed
+   * @param {Control} control control for which the action handler is being asked
+   * @return {Function} the action handler
+   */
+  getMouseDownHandler(
+    eventData: TPointerEvent,
+    fabricObject: FabricObject,
+    control: Control
+  ): ControlActionHandler | undefined {
+    return this.mouseDownHandler;
+  }
+
+  /**
+   * Returns control mouseUp handler.
+   * During actions the fabricObject or the control can be of different obj
+   * @param {Event} eventData the native mouse event
+   * @param {FabricObject} fabricObject on which the control is displayed
+   * @param {Control} control control for which the action handler is being asked
+   * @return {Function} the action handler
+   */
+  getMouseUpHandler(
+    eventData: TPointerEvent,
+    fabricObject: FabricObject,
+    control: Control
+  ): ControlActionHandler | undefined {
+    return this.mouseUpHandler;
+  }
+
+  /**
+   * Returns control cursorStyle for css using cursorStyle. If you need a more elaborate
+   * function you can pass one in the constructor
+   * the cursorStyle property
+   * @param {Event} eventData the native mouse event
+   * @param {Control} control the current control ( likely this)
+   * @param {FabricObject} object on which the control is displayed
+   * @return {String}
+   */
+  cursorStyleHandler(
+    eventData: TPointerEvent,
+    control: Control,
+    fabricObject: FabricObject
+  ) {
+    return control.cursorStyle;
+  }
+
+  /**
+   * Returns the action name. The basic implementation just return the actionName property.
+   * @param {Event} eventData the native mouse event
+   * @param {Control} control the current control ( likely this)
+   * @param {FabricObject} object on which the control is displayed
+   * @return {String}
+   */
+  getActionName(
+    eventData: TPointerEvent,
+    control: Control,
+    fabricObject: FabricObject
+  ) {
+    return control.actionName;
+  }
+
+  /**
+   * Returns controls visibility
+   * @param {FabricObject} object on which the control is displayed
+   * @param {String} controlKey key where the control is memorized on the
+   * @return {Boolean}
+   */
+  getVisibility(fabricObject: FabricObject, controlKey: string) {
+    // @ts-expect-error TODO remove directive once fixed
+    return fabricObject._controlsVisibility?.[controlKey] ?? this.visible;
+  }
+
+  /**
+   * Sets controls visibility
+   * @param {Boolean} visibility for the object
+   * @return {Void}
+   */
+  setVisibility(visibility: boolean, name: string, fabricObject: FabricObject) {
+    this.visible = visibility;
+  }
+
+  positionHandler(
+    dim: Point,
+    finalMatrix: TMat2D,
+    fabricObject: FabricObject,
+    currentControl: Control
+  ) {
+    return new Point(
+      this.x * dim.x + this.offsetX,
+      this.y * dim.y + this.offsetY
+    ).transform(finalMatrix);
+  }
+
+  /**
+   * Returns the coords for this control based on object values.
+   * @param {Number} objectAngle angle from the fabric object holding the control
+   * @param {Number} objectCornerSize cornerSize from the fabric object holding the control (or touchCornerSize if
+   *   isTouch is true)
+   * @param {Number} centerX x coordinate where the control center should be
+   * @param {Number} centerY y coordinate where the control center should be
+   * @param {boolean} isTouch true if touch corner, false if normal corner
+   */
+  calcCornerCoords(
+    objectAngle: TDegree,
+    objectCornerSize: number,
+    centerX: number,
+    centerY: number,
+    isTouch: boolean
+  ) {
+    let cosHalfOffset, sinHalfOffset, cosHalfOffsetComp, sinHalfOffsetComp;
+    const xSize = isTouch ? this.touchSizeX : this.sizeX,
+      ySize = isTouch ? this.touchSizeY : this.sizeY;
+    if (xSize && ySize && xSize !== ySize) {
+      // handle rectangular corners
+      const controlTriangleAngle = Math.atan2(ySize, xSize);
+      const cornerHypotenuse = Math.sqrt(xSize * xSize + ySize * ySize) / 2;
+      const newTheta = controlTriangleAngle - degreesToRadians(objectAngle);
+      const newThetaComp =
+        halfPI - controlTriangleAngle - degreesToRadians(objectAngle);
+      cosHalfOffset = cornerHypotenuse * cos(newTheta);
+      sinHalfOffset = cornerHypotenuse * sin(newTheta);
+      // use complementary angle for two corners
+      cosHalfOffsetComp = cornerHypotenuse * cos(newThetaComp);
+      sinHalfOffsetComp = cornerHypotenuse * sin(newThetaComp);
+    } else {
+      // handle square corners
+      // use default object corner size unless size is defined
+      const cornerSize = xSize && ySize ? xSize : objectCornerSize;
+      const cornerHypotenuse = cornerSize * Math.SQRT1_2;
+      // complementary angles are equal since they're both 45 degrees
+      const newTheta = degreesToRadians(45 - objectAngle);
+      cosHalfOffset = cosHalfOffsetComp = cornerHypotenuse * cos(newTheta);
+      sinHalfOffset = sinHalfOffsetComp = cornerHypotenuse * sin(newTheta);
+    }
+
+    return {
+      tl: new Point(centerX - sinHalfOffsetComp, centerY - cosHalfOffsetComp),
+      tr: new Point(centerX + cosHalfOffset, centerY - sinHalfOffset),
+      bl: new Point(centerX - cosHalfOffset, centerY + sinHalfOffset),
+      br: new Point(centerX + sinHalfOffsetComp, centerY + cosHalfOffsetComp),
+    };
+  }
+
+  /**
+   * Render function for the control.
+   * When this function runs the context is unscaled. unrotate. Just retina scaled.
+   * all the functions will have to translate to the point left,top before starting Drawing
+   * if they want to draw a control where the position is detected.
+   * left and top are the result of the positionHandler function
+   * @param {RenderingContext2D} ctx the context where the control will be drawn
+   * @param {Number} left position of the canvas where we are about to render the control.
+   * @param {Number} top position of the canvas where we are about to render the control.
+   * @param {Object} styleOverride
+   * @param {FabricObject} fabricObject the object where the control is about to be rendered
+   */
+  render(
+    ctx: CanvasRenderingContext2D,
+    left: number,
+    top: number,
+    styleOverride: ControlRenderingStyleOverride | undefined,
+    fabricObject: FabricObject
+  ) {
+    styleOverride = styleOverride || {};
+    switch (styleOverride.cornerStyle || fabricObject.cornerStyle) {
+      case 'circle':
+        renderCircleControl.call(
+          this,
+          ctx,
+          left,
+          top,
+          styleOverride,
+          fabricObject
+        );
+        break;
+      default:
+        renderSquareControl.call(
+          this,
+          ctx,
+          left,
+          top,
+          styleOverride,
+          fabricObject
+        );
+    }
+  }
+}

package/src/controls/changeWidth.ts

@@ -0,0 +1,52 @@
+import { TransformActionHandler } from '../EventTypeDefs';
+import { getLocalPoint, isTransformCentered } from './util';
+import { wrapWithFireEvent } from './wrapWithFireEvent';
+import { wrapWithFixedAnchor } from './wrapWithFixedAnchor';
+
+/**
+ * Action handler to change object's width
+ * Needs to be wrapped with `wrapWithFixedAnchor` to be effective
+ * @param {Event} eventData javascript event that is doing the transform
+ * @param {Object} transform javascript object containing a series of information around the current transform
+ * @param {number} x current mouse x position, canvas normalized
+ * @param {number} y current mouse y position, canvas normalized
+ * @return {Boolean} true if some change happened
+ */
+export const changeObjectWidth: TransformActionHandler = (
+  eventData,
+  transform,
+  x,
+  y
+) => {
+  const localPoint = getLocalPoint(
+    transform,
+    transform.originX,
+    transform.originY,
+    x,
+    y
+  );
+  //  make sure the control changes width ONLY from it's side of target
+  if (
+    transform.originX === 'center' ||
+    (transform.originX === 'right' && localPoint.x < 0) ||
+    (transform.originX === 'left' && localPoint.x > 0)
+  ) {
+    const { target } = transform,
+      strokePadding =
+        target.strokeWidth / (target.strokeUniform ? target.scaleX : 1),
+      multiplier = isTransformCentered(transform) ? 2 : 1,
+      oldWidth = target.width,
+      newWidth = Math.ceil(
+        Math.abs((localPoint.x * multiplier) / target.scaleX) - strokePadding
+      );
+    target.set('width', Math.max(newWidth, 0));
+    //  check against actual target width in case `newWidth` was rejected
+    return oldWidth !== target.width;
+  }
+  return false;
+};
+
+export const changeWidth = wrapWithFireEvent(
+  'resizing',
+  wrapWithFixedAnchor(changeObjectWidth)
+);

package/src/controls/controls.render.ts

@@ -0,0 +1,138 @@
+import { twoMathPi } from '../constants';
+import type { FabricObject } from '../shapes/Object/Object';
+import { degreesToRadians } from '../util/misc/radiansDegreesConversion';
+import type { Control } from './Control';
+
+export type ControlRenderingStyleOverride = Partial<
+  Pick<
+    FabricObject,
+    | 'cornerStyle'
+    | 'cornerSize'
+    | 'cornerColor'
+    | 'cornerStrokeColor'
+    | 'cornerDashArray'
+    | 'transparentCorners'
+  >
+>;
+
+export type ControlRenderer = (
+  ctx: CanvasRenderingContext2D,
+  left: number,
+  top: number,
+  styleOverride: ControlRenderingStyleOverride,
+  fabricObject: FabricObject
+) => void;
+
+/**
+ * Render a round control, as per fabric features.
+ * This function is written to respect object properties like transparentCorners, cornerSize
+ * cornerColor, cornerStrokeColor
+ * plus the addition of offsetY and offsetX.
+ * @param {CanvasRenderingContext2D} ctx context to render on
+ * @param {Number} left x coordinate where the control center should be
+ * @param {Number} top y coordinate where the control center should be
+ * @param {Object} styleOverride override for FabricObject controls style
+ * @param {FabricObject} fabricObject the fabric object for which we are rendering controls
+ */
+export function renderCircleControl(
+  this: Control,
+  ctx: CanvasRenderingContext2D,
+  left: number,
+  top: number,
+  styleOverride: ControlRenderingStyleOverride,
+  fabricObject: FabricObject
+) {
+  styleOverride = styleOverride || {};
+  const xSize =
+      this.sizeX || styleOverride.cornerSize || fabricObject.cornerSize,
+    ySize = this.sizeY || styleOverride.cornerSize || fabricObject.cornerSize,
+    transparentCorners =
+      typeof styleOverride.transparentCorners !== 'undefined'
+        ? styleOverride.transparentCorners
+        : fabricObject.transparentCorners,
+    methodName = transparentCorners ? 'stroke' : 'fill',
+    stroke =
+      !transparentCorners &&
+      (styleOverride.cornerStrokeColor || fabricObject.cornerStrokeColor);
+  let myLeft = left,
+    myTop = top,
+    size;
+  ctx.save();
+  ctx.fillStyle = styleOverride.cornerColor || fabricObject.cornerColor || '';
+  ctx.strokeStyle =
+    styleOverride.cornerStrokeColor || fabricObject.cornerStrokeColor || '';
+  // TODO: use proper ellipse code.
+  if (xSize > ySize) {
+    size = xSize;
+    ctx.scale(1.0, ySize / xSize);
+    myTop = (top * xSize) / ySize;
+  } else if (ySize > xSize) {
+    size = ySize;
+    ctx.scale(xSize / ySize, 1.0);
+    myLeft = (left * ySize) / xSize;
+  } else {
+    size = xSize;
+  }
+  // this is still wrong
+  ctx.lineWidth = 1;
+  ctx.beginPath();
+  ctx.arc(myLeft, myTop, size / 2, 0, twoMathPi, false);
+  ctx[methodName]();
+  if (stroke) {
+    ctx.stroke();
+  }
+  ctx.restore();
+}
+
+/**
+ * Render a square control, as per fabric features.
+ * This function is written to respect object properties like transparentCorners, cornerSize
+ * cornerColor, cornerStrokeColor
+ * plus the addition of offsetY and offsetX.
+ * @param {CanvasRenderingContext2D} ctx context to render on
+ * @param {Number} left x coordinate where the control center should be
+ * @param {Number} top y coordinate where the control center should be
+ * @param {Object} styleOverride override for FabricObject controls style
+ * @param {FabricObject} fabricObject the fabric object for which we are rendering controls
+ */
+export function renderSquareControl(
+  this: Control,
+  ctx: CanvasRenderingContext2D,
+  left: number,
+  top: number,
+  styleOverride: ControlRenderingStyleOverride,
+  fabricObject: FabricObject
+) {
+  styleOverride = styleOverride || {};
+  const xSize =
+      this.sizeX || styleOverride.cornerSize || fabricObject.cornerSize,
+    ySize = this.sizeY || styleOverride.cornerSize || fabricObject.cornerSize,
+    transparentCorners =
+      typeof styleOverride.transparentCorners !== 'undefined'
+        ? styleOverride.transparentCorners
+        : fabricObject.transparentCorners,
+    methodName = transparentCorners ? 'stroke' : 'fill',
+    stroke =
+      !transparentCorners &&
+      (styleOverride.cornerStrokeColor || fabricObject.cornerStrokeColor),
+    xSizeBy2 = xSize / 2,
+    ySizeBy2 = ySize / 2;
+  ctx.save();
+  ctx.fillStyle = styleOverride.cornerColor || fabricObject.cornerColor || '';
+  ctx.strokeStyle =
+    styleOverride.cornerStrokeColor || fabricObject.cornerStrokeColor || '';
+  // this is still wrong
+  ctx.lineWidth = 1;
+  ctx.translate(left, top);
+  //  angle is relative to canvas plane
+  const angle = fabricObject.getTotalAngle();
+  ctx.rotate(degreesToRadians(angle));
+  // this does not work, and fixed with ( && ) does not make sense.
+  // to have real transparent corners we need the controls on upperCanvas
+  // transparentCorners || ctx.clearRect(-xSizeBy2, -ySizeBy2, xSize, ySize);
+  ctx[`${methodName}Rect`](-xSizeBy2, -ySizeBy2, xSize, ySize);
+  if (stroke) {
+    ctx.strokeRect(-xSizeBy2, -ySizeBy2, xSize, ySize);
+  }
+  ctx.restore();
+}

package/src/controls/default_controls.ts

@@ -0,0 +1,132 @@
+import { FabricObject } from '../shapes/Object/FabricObject';
+import { Textbox } from '../shapes/Textbox';
+import { scaleCursorStyleHandler, scalingEqually } from './scale';
+import { changeWidth } from './changeWidth';
+import { rotationStyleHandler, rotationWithSnapping } from './rotate';
+import {
+  scaleOrSkewActionName,
+  scaleSkewCursorStyleHandler,
+  scalingXOrSkewingY,
+  scalingYOrSkewingX,
+} from './scaleSkew';
+import { Control } from './Control';
+
+// use this function if you want to generate new controls for every instance
+export const createObjectDefaultControls = () => ({
+  ml: new Control({
+    x: -0.5,
+    y: 0,
+    cursorStyleHandler: scaleSkewCursorStyleHandler,
+    actionHandler: scalingXOrSkewingY,
+    getActionName: scaleOrSkewActionName,
+  }),
+
+  mr: new Control({
+    x: 0.5,
+    y: 0,
+    cursorStyleHandler: scaleSkewCursorStyleHandler,
+    actionHandler: scalingXOrSkewingY,
+    getActionName: scaleOrSkewActionName,
+  }),
+
+  mb: new Control({
+    x: 0,
+    y: 0.5,
+    cursorStyleHandler: scaleSkewCursorStyleHandler,
+    actionHandler: scalingYOrSkewingX,
+    getActionName: scaleOrSkewActionName,
+  }),
+
+  mt: new Control({
+    x: 0,
+    y: -0.5,
+    cursorStyleHandler: scaleSkewCursorStyleHandler,
+    actionHandler: scalingYOrSkewingX,
+    getActionName: scaleOrSkewActionName,
+  }),
+
+  tl: new Control({
+    x: -0.5,
+    y: -0.5,
+    cursorStyleHandler: scaleCursorStyleHandler,
+    actionHandler: scalingEqually,
+  }),
+
+  tr: new Control({
+    x: 0.5,
+    y: -0.5,
+    cursorStyleHandler: scaleCursorStyleHandler,
+    actionHandler: scalingEqually,
+  }),
+
+  bl: new Control({
+    x: -0.5,
+    y: 0.5,
+    cursorStyleHandler: scaleCursorStyleHandler,
+    actionHandler: scalingEqually,
+  }),
+
+  br: new Control({
+    x: 0.5,
+    y: 0.5,
+    cursorStyleHandler: scaleCursorStyleHandler,
+    actionHandler: scalingEqually,
+  }),
+
+  mtr: new Control({
+    x: 0,
+    y: -0.5,
+    actionHandler: rotationWithSnapping,
+    cursorStyleHandler: rotationStyleHandler,
+    offsetY: -40,
+    withConnection: true,
+    actionName: 'rotate',
+  }),
+});
+
+export const createResizeControls = () => ({
+  mr: new Control({
+    x: 0.5,
+    y: 0,
+    actionHandler: changeWidth,
+    cursorStyleHandler: scaleSkewCursorStyleHandler,
+    actionName: 'resizing',
+  }),
+  ml: new Control({
+    x: -0.5,
+    y: 0,
+    actionHandler: changeWidth,
+    cursorStyleHandler: scaleSkewCursorStyleHandler,
+    actionName: 'resizing',
+  }),
+});
+
+export const createTextboxDefaultControls = () => ({
+  ...createObjectDefaultControls(),
+  ...createResizeControls(),
+});
+
+export const defaultControls = createObjectDefaultControls();
+
+// shared with the default object on purpose
+export const textboxDefaultControls = {
+  ...defaultControls,
+  ...createResizeControls(),
+};
+
+FabricObject.prototype.controls = {
+  ...(FabricObject.prototype.controls || {}),
+  ...defaultControls,
+};
+
+if (Textbox) {
+  // this is breaking the prototype inheritance, no time / ideas to fix it.
+  // is important to document that if you want to have all objects to have a
+  // specific custom control, you have to add it to Object prototype and to Textbox
+  // prototype. The controls are shared as references. So changes to control `tr`
+  // can still apply to all objects if needed.
+  Textbox.prototype.controls = {
+    ...(Textbox.prototype.controls || {}),
+    ...textboxDefaultControls,
+  };
+}