fabric 5.3.0 → 6.0.0-beta3

package/src/Observable.ts

@@ -0,0 +1,181 @@
+export type TEventCallback<T = any> = (options: T) => any;
+
+type EventRegistryObject<
+  K extends string | number | symbol = string,
+  E = any
+> = Record<K, TEventCallback<E>>;
+
+/**
+ * @tutorial {@link http://fabricjs.com/fabric-intro-part-2#events}
+ * @see {@link http://fabricjs.com/events|Events demo}
+ */
+export class Observable<EventSpec> {
+  private __eventListeners: Record<keyof EventSpec, TEventCallback[]> =
+    {} as Record<keyof EventSpec, TEventCallback[]>;
+
+  /**
+   * Observes specified event
+   * @alias on
+   * @param {string} eventName Event name (eg. 'after:render')
+   * @param {EventRegistryObject} handlers key/value pairs (eg. {'after:render': handler, 'selection:cleared': handler})
+   * @param {Function} handler Function that receives a notification when an event of the specified type occurs
+   * @return {Function} disposer
+   */
+  on<K extends keyof EventSpec, E extends EventSpec[K]>(
+    eventName: K,
+    handler: TEventCallback<E>
+  ): VoidFunction;
+  on<K extends string, E>(
+    eventName: K,
+    handler: TEventCallback<E>
+  ): VoidFunction;
+  on<K extends keyof EventSpec, E extends EventSpec[K]>(
+    handlers: EventRegistryObject<K, E>
+  ): VoidFunction;
+  on<K extends keyof EventSpec, E extends EventSpec[K]>(
+    arg0: K | EventRegistryObject<K, E>,
+    handler?: TEventCallback<E>
+  ): VoidFunction {
+    if (!this.__eventListeners) {
+      this.__eventListeners = {} as Record<keyof EventSpec, TEventCallback[]>;
+    }
+    if (typeof arg0 === 'object') {
+      // one object with key/value pairs was passed
+      for (const eventName in arg0) {
+        this.on(eventName as K, arg0[eventName]);
+      }
+      return () => this.off(arg0);
+    } else if (handler) {
+      const eventName = arg0;
+      if (!this.__eventListeners[eventName]) {
+        this.__eventListeners[eventName] = [];
+      }
+      this.__eventListeners[eventName].push(handler);
+      return () => this.off(eventName, handler);
+    } else {
+      // noop
+      return () => false;
+    }
+  }
+
+  /**
+   * Observes specified event **once**
+   * @alias once
+   * @param {string} eventName Event name (eg. 'after:render')
+   * @param {EventRegistryObject} handlers key/value pairs (eg. {'after:render': handler, 'selection:cleared': handler})
+   * @param {Function} handler Function that receives a notification when an event of the specified type occurs
+   * @return {Function} disposer
+   */
+  once<K extends keyof EventSpec, E extends EventSpec[K]>(
+    eventName: K,
+    handler: TEventCallback<E>
+  ): VoidFunction;
+  once<K extends string, E>(
+    eventName: K,
+    handler: TEventCallback<E>
+  ): VoidFunction;
+  once<K extends keyof EventSpec, E extends EventSpec[K]>(
+    handlers: EventRegistryObject<K, E>
+  ): VoidFunction;
+  once<K extends keyof EventSpec, E extends EventSpec[K]>(
+    arg0: K | EventRegistryObject<K, E>,
+    handler?: TEventCallback<E>
+  ): VoidFunction {
+    if (typeof arg0 === 'object') {
+      // one object with key/value pairs was passed
+      const disposers: VoidFunction[] = [];
+      for (const eventName in arg0) {
+        disposers.push(this.once(eventName as K, arg0[eventName]));
+      }
+      return () => disposers.forEach((d) => d());
+    } else if (handler) {
+      const disposer = this.on<K, E>(arg0, (...args) => {
+        handler(...args);
+        disposer();
+      });
+      return disposer;
+    } else {
+      // noop
+      return () => false;
+    }
+  }
+
+  /**
+   * @private
+   * @param {string} eventName
+   * @param {Function} [handler]
+   */
+  private _removeEventListener<K extends keyof EventSpec>(
+    eventName: K,
+    handler?: TEventCallback
+  ) {
+    if (!this.__eventListeners[eventName]) {
+      return;
+    }
+
+    if (handler) {
+      const eventListener = this.__eventListeners[eventName];
+      const index = eventListener.indexOf(handler);
+      index > -1 && eventListener.splice(index, 1);
+    } else {
+      this.__eventListeners[eventName] = [];
+    }
+  }
+
+  /**
+   * unsubscribe an event listener
+   * @param {string} eventName event name (eg. 'after:render')
+   * @param {TEventCallback} handler event listener to unsubscribe
+   */
+  off<K extends keyof EventSpec>(eventName: K, handler: TEventCallback): void;
+  /**
+   * unsubscribe event listeners
+   * @param handlers handlers key/value pairs (eg. {'after:render': handler, 'selection:cleared': handler})
+   */
+  off(handlers: EventRegistryObject): void;
+  /**
+   * unsubscribe all event listeners
+   */
+  off(): void;
+  off<K extends keyof EventSpec>(
+    arg0?: K | EventRegistryObject,
+    handler?: TEventCallback
+  ) {
+    if (!this.__eventListeners) {
+      return;
+    }
+
+    // remove all key/value pairs (event name -> event handler)
+    if (typeof arg0 === 'undefined') {
+      for (const eventName in this.__eventListeners) {
+        this._removeEventListener(eventName);
+      }
+    }
+    // one object with key/value pairs was passed
+    else if (typeof arg0 === 'object') {
+      for (const eventName in arg0) {
+        this._removeEventListener(eventName as K, arg0[eventName]);
+      }
+    } else {
+      this._removeEventListener(arg0, handler);
+    }
+  }
+
+  /**
+   * Fires event with an optional options object
+   * @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) {
+      for (let i = 0; i < listenersForEvent.length; i++) {
+        listenersForEvent[i].call(this, options || {});
+      }
+    }
+  }
+}

package/src/Pattern.ts

@@ -0,0 +1,227 @@
+import { config } from './config';
+import { TCrossOrigin, TMat2D, TSize } from './typedefs';
+import { ifNaN } from './util/internals';
+import { uid } from './util/internals/uid';
+import { loadImage } from './util/misc/objectEnlive';
+import { pick } from './util/misc/pick';
+import { toFixed } from './util/misc/toFixed';
+import { classRegistry } from './ClassRegistry';
+
+export type TPatternRepeat = 'repeat' | 'repeat-x' | 'repeat-y' | 'no-repeat';
+
+type TExportedKeys =
+  | 'crossOrigin'
+  | 'offsetX'
+  | 'offsetY'
+  | 'patternTransform'
+  | 'repeat'
+  | 'source';
+
+export type TPatternOptions = Partial<Pick<Pattern, TExportedKeys>>;
+
+export type TPatternSerialized = TPatternOptions & {
+  source: string;
+};
+
+export type TPatternHydrationOptions = {
+  /**
+   * handle aborting
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/AbortController/signal
+   */
+  signal?: AbortSignal;
+};
+
+type TImageSource = { source: HTMLImageElement };
+type TCanvasSource = { source: HTMLCanvasElement };
+
+/**
+ * @see {@link http://fabricjs.com/patterns demo}
+ * @see {@link http://fabricjs.com/dynamic-patterns demo}
+ */
+export class Pattern {
+  /**
+   * Legacy identifier of the class. Prefer using this.constructor.name 'Pattern'
+   * or utils like isPattern
+   * Will be removed in fabric 7 or 8.
+   * @TODO add sustainable warning message
+   * @type string
+   * @deprecated
+   */
+  get type() {
+    return 'pattern';
+  }
+
+  set type(value) {
+    console.warn('Setting type has no effect', value);
+  }
+
+  /**
+   * @type TPatternRepeat
+   * @defaults
+   */
+  repeat: TPatternRepeat = 'repeat';
+
+  /**
+   * Pattern horizontal offset from object's left/top corner
+   * @type Number
+   * @default
+   */
+  offsetX = 0;
+
+  /**
+   * Pattern vertical offset from object's left/top corner
+   * @type Number
+   * @default
+   */
+  offsetY = 0;
+
+  /**
+   * @type TCrossOrigin
+   * @default
+   */
+  crossOrigin: TCrossOrigin = '';
+
+  /**
+   * transform matrix to change the pattern, imported from svgs.
+   * @todo verify if using the identity matrix as default makes the rest of the code more easy
+   * @type Array
+   * @default
+   */
+  patternTransform: TMat2D | null = null;
+
+  /**
+   * The actual pixel source of the pattern
+   */
+  declare source: CanvasImageSource;
+
+  /**
+   * If true, this object will not be exported during the serialization of a canvas
+   * @type boolean
+   */
+  declare excludeFromExport?: boolean;
+
+  /**
+   * ID used for SVG export functionalities
+   * @type number
+   */
+  declare readonly id: number;
+
+  /**
+   * Constructor
+   * @param {Object} [options] Options object
+   * @param {option.source} [source] the pattern source, eventually empty or a drawable
+   */
+  constructor(options: TPatternOptions = {}) {
+    this.id = uid();
+    Object.assign(this, options);
+  }
+
+  /**
+   * @returns true if {@link source} is an <img> element
+   */
+  isImageSource(): this is TImageSource {
+    return (
+      !!this.source && typeof (this.source as HTMLImageElement).src === 'string'
+    );
+  }
+
+  /**
+   * @returns true if {@link source} is a <canvas> element
+   */
+  isCanvasSource(): this is TCanvasSource {
+    return !!this.source && !!(this.source as HTMLCanvasElement).toDataURL;
+  }
+
+  sourceToString(): string {
+    return this.isImageSource()
+      ? this.source.src
+      : this.isCanvasSource()
+      ? this.source.toDataURL()
+      : '';
+  }
+
+  /**
+   * Returns an instance of CanvasPattern
+   * @param {CanvasRenderingContext2D} ctx Context to create pattern
+   * @return {CanvasPattern}
+   */
+  toLive(ctx: CanvasRenderingContext2D): CanvasPattern | null {
+    if (
+      // if the image failed to load, return, and allow rest to continue loading
+      !this.source ||
+      // if an image
+      (this.isImageSource() &&
+        (!this.source.complete ||
+          this.source.naturalWidth === 0 ||
+          this.source.naturalHeight === 0))
+    ) {
+      return null;
+    }
+
+    return ctx.createPattern(this.source, this.repeat)!;
+  }
+
+  /**
+   * Returns object representation of a pattern
+   * @param {Array} [propertiesToInclude] Any properties that you might want to additionally include in the output
+   * @return {object} Object representation of a pattern instance
+   */
+  toObject(propertiesToInclude: string[] = []): Record<string, any> {
+    const { repeat, crossOrigin } = this;
+    return {
+      ...pick(this, propertiesToInclude as (keyof this)[]),
+      type: 'pattern',
+      source: this.sourceToString(),
+      repeat,
+      crossOrigin,
+      offsetX: toFixed(this.offsetX, config.NUM_FRACTION_DIGITS),
+      offsetY: toFixed(this.offsetY, config.NUM_FRACTION_DIGITS),
+      patternTransform: this.patternTransform
+        ? [...this.patternTransform]
+        : null,
+    };
+  }
+
+  /* _TO_SVG_START_ */
+  /**
+   * Returns SVG representation of a pattern
+   */
+  toSVG({ width, height }: TSize): string {
+    const { source: patternSource, repeat, id } = this,
+      patternOffsetX = ifNaN(this.offsetX / width, 0),
+      patternOffsetY = ifNaN(this.offsetY / height, 0),
+      patternWidth =
+        repeat === 'repeat-y' || repeat === 'no-repeat'
+          ? 1 + Math.abs(patternOffsetX || 0)
+          : ifNaN((patternSource.width as number) / width, 0),
+      patternHeight =
+        repeat === 'repeat-x' || repeat === 'no-repeat'
+          ? 1 + Math.abs(patternOffsetY || 0)
+          : ifNaN((patternSource.height as number) / height, 0);
+
+    return [
+      `<pattern id="SVGID_${id}" x="${patternOffsetX}" y="${patternOffsetY}" width="${patternWidth}" height="${patternHeight}">`,
+      `<image x="0" y="0" width="${patternSource.width}" height="${
+        patternSource.height
+      }" xlink:href="${this.sourceToString()}"></image>`,
+      `</pattern>`,
+      '',
+    ].join('\n');
+  }
+  /* _TO_SVG_END_ */
+
+  static async fromObject(
+    { source, ...serialized }: TPatternSerialized,
+    options: TPatternHydrationOptions
+  ): Promise<Pattern> {
+    const img = await loadImage(source, {
+      ...options,
+      crossOrigin: serialized.crossOrigin,
+    });
+    return new this({ ...serialized, source: img });
+  }
+}
+
+classRegistry.setClass(Pattern);
+// kept for compatibility reason
+classRegistry.setClass(Pattern, 'pattern');