feat(Brush API): Observable, clipPath

.eslintrc.json

@@ -2,6 +2,9 @@
   "env": {
     "browser": true
   },
+  "parserOptions": {
+    "ecmaVersion": 8
+  },
   "globals": {
     "Promise": true,
     "define": true,

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [next]
 
+- feat(Brush): new API, extend `Observable`, support `clipPath` [#8476](https://github.com/fabricjs/fabric.js/pull/8476)
+  BREAKING:
+  - brush doesn't add result to canvas anymore
+  - `path:created`, `before:path:created` events are deprecated, use `interaction:completed` instead
+  - `_render` method is now protected, use `render` instead
+  - renamed `PencilBrush#convertPointsToSVGPath` => `getPathFromPoints`
+  - `Canvas#freeDrawingCursor` => `Brush#cursor`
+- feat(): DrawShape, DrawOval, DrawPoly [#8430](https://github.com/fabricjs/fabric.js/pull/8430)
 - patch(): Added WebGLProbe to env, removed isLikelyNode, added specific env dispose ( instead of cleanup JSDOM ) [#8652](https://github.com/fabricjs/fabric.js/pull/8652)
 - ci(): Removed the browser publish script [#8656](https://github.com/fabricjs/fabric.js/pull/8656)
 - feat(): Node entry point [#8632](https://github.com/fabricjs/fabric.js/pull/8632)

fabric.ts

@@ -326,6 +326,7 @@ import { Canvas2dFilterBackend } from './src/filters/Canvas2dFilterBackend';
 import { WebGLFilterBackend } from './src/filters/WebGLFilterBackend';
 import { runningAnimations } from './src/util/animation/AnimationRegistry';
 import { Observable } from './src/Observable';
+import { FabricEvent as Event } from './src/FabricEvent';
 import { Point } from './src/Point';
 import { Intersection } from './src/Intersection';
 import { Color } from './src/color/Color';
@@ -334,10 +335,15 @@ import { Gradient } from './src/gradient/Gradient';
 import { Pattern } from './src/Pattern';
 import { Shadow } from './src/Shadow';
 import { BaseBrush } from './src/brushes/BaseBrush';
+import { SimpleBrush } from './src/brushes/SimpleBrush';
 import { PencilBrush } from './src/brushes/PencilBrush';
 import { CircleBrush } from './src/brushes/CircleBrush';
 import { SprayBrush } from './src/brushes/SprayBrush';
 import { PatternBrush } from './src/brushes/PatternBrush';
+import { DrawOval } from './src/brushes/DrawOval';
+import { DrawPoly } from './src/brushes/DrawPoly';
+import { DrawShape } from './src/brushes/DrawShape';
+import { DrawShapeBase } from './src/brushes/DrawShapeBase';
 import { FabricObject as Object } from './src/shapes/Object/FabricObject';
 import { Line } from './src/shapes/Line';
 import { Circle } from './src/shapes/Circle';
@@ -386,14 +392,20 @@ export {
   Color,
   Control,
   Observable,
+  Event,
   Gradient,
   Pattern,
   Shadow,
   BaseBrush,
+  SimpleBrush,
   PencilBrush,
   CircleBrush,
   SprayBrush,
   PatternBrush,
+  DrawOval,
+  DrawPoly,
+  DrawShape,
+  DrawShapeBase,
   Object,
   Line,
   Circle,

src/EventTypeDefs.ts

@@ -132,7 +132,6 @@ export type TPointerEventInfo<E extends TPointerEvent = TPointerEvent> =
   TEvent<E> & {
     target?: FabricObject;
     subTargets?: FabricObject[];
-    button?: number;
     isClick: boolean;
     pointer: Point;
     transform?: Transform | null;
@@ -260,6 +259,8 @@ export type StaticCanvasEvents = CollectionEvents & {
   // rendering
   'before:render': { ctx: CanvasRenderingContext2D };
   'after:render': { ctx: CanvasRenderingContext2D };
+
+  resize: never;
 };
 
 export type CanvasEvents = StaticCanvasEvents &
@@ -269,8 +270,7 @@ export type CanvasEvents = StaticCanvasEvents &
   CanvasModificationEvents &
   CanvasSelectionEvents & {
     // brushes
-    'before:path:created': { path: FabricObject };
-    'path:created': { path: FabricObject };
+    'interaction:completed': { result?: FabricObject };
 
     // erasing
     'erasing:start': never;

src/FabricEvent.ts

@@ -0,0 +1,71 @@
+import type { Observable } from './Observable';
+
+export type TFabricEvent<T> = FabricEvent<T> & T;
+
+export enum PropagationState {
+  propagate = 1,
+  stop = 0,
+  stopImmediately = -1,
+}
+
+export class FabricEvent<T> {
+  declare defaultPrevented: boolean;
+  declare propagate: PropagationState;
+  declare path: Observable<any>[];
+
+  static init<T>(data?: T) {
+    return new FabricEvent<T>(data) as TFabricEvent<T>;
+  }
+
+  private constructor(data?: T) {
+    Object.defineProperties(this, {
+      defaultPrevented: {
+        value: false,
+        enumerable: false,
+        configurable: false,
+        writable: true,
+      },
+      propagate: {
+        value: PropagationState.propagate,
+        enumerable: false,
+        configurable: false,
+        writable: true,
+      },
+      path: {
+        value: [],
+        enumerable: false,
+        configurable: false,
+        writable: true,
+      },
+    });
+    Object.assign(this, data || {});
+  }
+
+  /**
+   * https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault
+   */
+  preventDefault() {
+    this.defaultPrevented = true;
+  }
+
+  /**
+   * https://developer.mozilla.org/en-US/docs/Web/API/Event/stopPropagation
+   */
+  stopPropagation() {
+    this.propagate = PropagationState.stop;
+  }
+
+  /**
+   * https://developer.mozilla.org/en-US/docs/Web/API/Event/stopImmediatePropagation
+   */
+  stopImmediatePropagation() {
+    this.propagate = PropagationState.stopImmediately;
+  }
+
+  /**
+   * https://developer.mozilla.org/en-US/docs/Web/API/Event/composedPath
+   */
+  composedPath() {
+    return this.path;
+  }
+}

src/Observable.ts

@@ -1,4 +1,6 @@
-export type TEventCallback<T = any> = (options: T) => any;
+import { FabricEvent, PropagationState, TFabricEvent } from './FabricEvent';
+
+export type TEventCallback<T = any> = (options: TFabricEvent<T>) => any;
 
 type EventRegistryObject<
   K extends string | number | symbol = string,
@@ -160,16 +162,31 @@ export class Observable<EventSpec> {
    * @param {String} eventName Event name to fire
    * @param {Object} [options] Options object
    */
-  fire<K extends keyof EventSpec>(eventName: K, options?: EventSpec[K]) {
-    if (!this.__eventListeners) {
-      return;
-    }
-
-    const listenersForEvent = this.__eventListeners[eventName]?.concat();
-    if (listenersForEvent) {
+  fire<K extends keyof EventSpec>(
+    eventName: K,
+    options?: EventSpec[K] | TFabricEvent<EventSpec[K]>
+  ): TFabricEvent<EventSpec[K]> {
+    const ev =
+      options instanceof FabricEvent ? options : FabricEvent.init(options);
+    if (
+      this.__eventListeners &&
+      this.__eventListeners[eventName] &&
+      ev.propagate === PropagationState.propagate
+    ) {
+      let called = false;
+      const listenersForEvent = this.__eventListeners[eventName].concat();
       for (let i = 0; i < listenersForEvent.length; i++) {
-        listenersForEvent[i].call(this, options || {});
+        if (
+          (ev.propagate as PropagationState) ===
+          PropagationState.stopImmediately
+        ) {
+          break;
+        }
+        called = true;
+        listenersForEvent[i].call(this, ev);
       }
+      called && ev.path.push(this);
     }
+    return ev;
   }
 }