@nasser-sw/fabric 7.0.0-beta1

package/src/gradient/Gradient.ts

@@ -0,0 +1,404 @@
+import { iMatrix } from '../constants';
+import { parseTransformAttribute } from '../parser/parseTransformAttribute';
+import type { FabricObject } from '../shapes/Object/FabricObject';
+import type { TMat2D } from '../typedefs';
+import { uid } from '../util/internals/uid';
+import { pick } from '../util/misc/pick';
+import { matrixToSVG } from '../util/misc/svgExport';
+import { linearDefaultCoords, radialDefaultCoords } from './constants';
+import { parseColorStops } from './parser/parseColorStops';
+import { parseCoords } from './parser/parseCoords';
+import { parseType, parseGradientUnits } from './parser/misc';
+import type {
+  ColorStop,
+  GradientCoords,
+  GradientOptions,
+  GradientType,
+  GradientUnits,
+  SVGOptions,
+  SerializedGradientProps,
+} from './typedefs';
+import { classRegistry } from '../ClassRegistry';
+import { isPath } from '../util/typeAssertions';
+
+/**
+ * Gradient class
+ * @class Gradient
+ * @see {@link http://fabricjs.com/fabric-intro-part-2#gradients}
+ */
+export class Gradient<
+  S,
+  T extends GradientType = S extends GradientType ? S : 'linear',
+> {
+  /**
+   * Horizontal offset for aligning gradients coming from SVG when outside pathgroups
+   * @type Number
+   * @default 0
+   */
+  declare offsetX: number;
+
+  /**
+   * Vertical offset for aligning gradients coming from SVG when outside pathgroups
+   * @type Number
+   * @default 0
+   */
+  declare offsetY: number;
+
+  /**
+   * A transform matrix to apply to the gradient before painting.
+   * Imported from svg gradients, is not applied with the current transform in the center.
+   * Before this transform is applied, the origin point is at the top left corner of the object
+   * plus the addition of offsetY and offsetX.
+   * @type Number[]
+   * @default null
+   */
+  declare gradientTransform?: TMat2D;
+
+  /**
+   * coordinates units for coords.
+   * If `pixels`, the number of coords are in the same unit of width / height.
+   * If set as `percentage` the coords are still a number, but 1 means 100% of width
+   * for the X and 100% of the height for the y. It can be bigger than 1 and negative.
+   * allowed values pixels or percentage.
+   * @type GradientUnits
+   * @default 'pixels'
+   */
+  declare gradientUnits: GradientUnits;
+
+  /**
+   * Gradient type linear or radial
+   * @type GradientType
+   * @default 'linear'
+   */
+  declare type: T;
+
+  /**
+   * Defines how the gradient is located in space and spread
+   * @type GradientCoords
+   */
+  declare coords: GradientCoords<T>;
+
+  /**
+   * Defines how many colors a gradient has and how they are located on the axis
+   * defined by coords
+   * @type GradientCoords
+   */
+  declare colorStops: ColorStop[];
+
+  /**
+   * 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 | string
+   */
+  declare readonly id: string | number;
+
+  static type = 'Gradient';
+
+  constructor(options: GradientOptions<T>) {
+    const {
+      type = 'linear' as T,
+      gradientUnits = 'pixels',
+      coords = {},
+      colorStops = [],
+      offsetX = 0,
+      offsetY = 0,
+      gradientTransform,
+      id,
+    } = options || {};
+    Object.assign(this, {
+      type,
+      gradientUnits,
+      coords: {
+        ...(type === 'radial' ? radialDefaultCoords : linearDefaultCoords),
+        ...coords,
+      },
+      colorStops,
+      offsetX,
+      offsetY,
+      gradientTransform,
+      id: id ? `${id}_${uid()}` : uid(),
+    });
+  }
+
+  /**
+   * Adds another colorStop
+   * @param {Record<string, string>} colorStop Object with offset and color
+   * @return {Gradient} thisArg
+   */
+  addColorStop(colorStops: Record<string, string>) {
+    for (const position in colorStops) {
+      this.colorStops.push({
+        offset: parseFloat(position),
+        color: colorStops[position],
+      });
+    }
+    return this;
+  }
+
+  /**
+   * Returns object representation of a gradient
+   * @param {string[]} [propertiesToInclude] Any properties that you might want to additionally include in the output
+   * @return {object}
+   */
+  toObject(
+    propertiesToInclude?: (keyof this | string)[],
+  ): SerializedGradientProps<T> {
+    return {
+      ...pick(this, propertiesToInclude as (keyof this)[]),
+      type: this.type,
+      coords: { ...this.coords },
+      colorStops: this.colorStops.map((colorStop) => ({ ...colorStop })),
+      offsetX: this.offsetX,
+      offsetY: this.offsetY,
+      gradientUnits: this.gradientUnits,
+      gradientTransform: this.gradientTransform
+        ? [...this.gradientTransform]
+        : undefined,
+    };
+  }
+
+  /* _TO_SVG_START_ */
+  /**
+   * Returns SVG representation of an gradient
+   * @param {FabricObject} object Object to create a gradient for
+   * @return {String} SVG representation of an gradient (linear/radial)
+   */
+  toSVG(
+    object: FabricObject,
+    {
+      additionalTransform: preTransform,
+    }: { additionalTransform?: string } = {},
+  ) {
+    const markup = [],
+      transform = (
+        this.gradientTransform
+          ? this.gradientTransform.concat()
+          : iMatrix.concat()
+      ) as TMat2D,
+      gradientUnits =
+        this.gradientUnits === 'pixels'
+          ? 'userSpaceOnUse'
+          : 'objectBoundingBox';
+    // colorStops must be sorted ascending, and guarded against deep mutations
+    const colorStops = this.colorStops
+      .map((colorStop) => ({ ...colorStop }))
+      .sort((a, b) => {
+        return a.offset - b.offset;
+      });
+
+    let offsetX = -this.offsetX,
+      offsetY = -this.offsetY;
+    if (gradientUnits === 'objectBoundingBox') {
+      offsetX /= object.width;
+      offsetY /= object.height;
+    } else {
+      offsetX += object.width / 2;
+      offsetY += object.height / 2;
+    }
+    // todo what about polygon/polyline?
+    if (isPath(object) && this.gradientUnits !== 'percentage') {
+      offsetX -= object.pathOffset.x;
+      offsetY -= object.pathOffset.y;
+    }
+    transform[4] -= offsetX;
+    transform[5] -= offsetY;
+
+    const commonAttributes = [
+      `id="SVGID_${this.id}"`,
+      `gradientUnits="${gradientUnits}"`,
+      `gradientTransform="${
+        preTransform ? preTransform + ' ' : ''
+      }${matrixToSVG(transform)}"`,
+      '',
+    ].join(' ');
+
+    if (this.type === 'linear') {
+      const { x1, y1, x2, y2 } = this.coords;
+      markup.push(
+        '<linearGradient ',
+        commonAttributes,
+        ' x1="',
+        x1,
+        '" y1="',
+        y1,
+        '" x2="',
+        x2,
+        '" y2="',
+        y2,
+        '">\n',
+      );
+    } else if (this.type === 'radial') {
+      const { x1, y1, x2, y2, r1, r2 } = this
+        .coords as GradientCoords<'radial'>;
+      const needsSwap = r1 > r2;
+      // svg radial gradient has just 1 radius. the biggest.
+      markup.push(
+        '<radialGradient ',
+        commonAttributes,
+        ' cx="',
+        needsSwap ? x1 : x2,
+        '" cy="',
+        needsSwap ? y1 : y2,
+        '" r="',
+        needsSwap ? r1 : r2,
+        '" fx="',
+        needsSwap ? x2 : x1,
+        '" fy="',
+        needsSwap ? y2 : y1,
+        '">\n',
+      );
+      if (needsSwap) {
+        // svg goes from internal to external radius. if radius are inverted, swap color stops.
+        colorStops.reverse(); //  mutates array
+        colorStops.forEach((colorStop) => {
+          colorStop.offset = 1 - colorStop.offset;
+        });
+      }
+      const minRadius = Math.min(r1, r2);
+      if (minRadius > 0) {
+        // i have to shift all colorStops and add new one in 0.
+        const maxRadius = Math.max(r1, r2),
+          percentageShift = minRadius / maxRadius;
+        colorStops.forEach((colorStop) => {
+          colorStop.offset += percentageShift * (1 - colorStop.offset);
+        });
+      }
+    }
+
+    colorStops.forEach(({ color, offset }) => {
+      markup.push(
+        `<stop offset="${offset * 100}%" style="stop-color:${color};"/>\n`,
+      );
+    });
+
+    markup.push(
+      this.type === 'linear' ? '</linearGradient>' : '</radialGradient>',
+      '\n',
+    );
+
+    return markup.join('');
+  }
+  /* _TO_SVG_END_ */
+
+  /**
+   * Returns an instance of CanvasGradient
+   * @param {CanvasRenderingContext2D} ctx Context to render on
+   * @return {CanvasGradient}
+   */
+  toLive(ctx: CanvasRenderingContext2D): CanvasGradient {
+    const { x1, y1, x2, y2, r1, r2 } = this.coords as GradientCoords<'radial'>;
+    const gradient =
+      this.type === 'linear'
+        ? ctx.createLinearGradient(x1, y1, x2, y2)
+        : ctx.createRadialGradient(x1, y1, r1, x2, y2, r2);
+
+    this.colorStops.forEach(({ color, offset }) => {
+      gradient.addColorStop(offset, color);
+    });
+
+    return gradient;
+  }
+
+  static async fromObject(
+    options: GradientOptions<'linear'>,
+  ): Promise<Gradient<'linear'>>;
+  static async fromObject(
+    options: GradientOptions<'radial'>,
+  ): Promise<Gradient<'radial'>>;
+  static async fromObject(
+    options: GradientOptions<'linear'> | GradientOptions<'radial'>,
+  ) {
+    const { colorStops, gradientTransform } = options;
+    return new this({
+      ...options,
+      colorStops: colorStops
+        ? colorStops.map((colorStop) => ({ ...colorStop }))
+        : undefined,
+      gradientTransform: gradientTransform ? [...gradientTransform] : undefined,
+    });
+  }
+
+  /* _FROM_SVG_START_ */
+  /**
+   * Returns {@link Gradient} instance from an SVG element
+   * @param {SVGGradientElement} el SVG gradient element
+   * @param {FabricObject} instance
+   * @param {String} opacity A fill-opacity or stroke-opacity attribute to multiply to each stop's opacity.
+   * @param {SVGOptions} svgOptions an object containing the size of the SVG in order to parse correctly gradients
+   * that uses gradientUnits as 'userSpaceOnUse' and percentages.
+   * @return {Gradient} Gradient instance
+   * @see http://www.w3.org/TR/SVG/pservers.html#LinearGradientElement
+   * @see http://www.w3.org/TR/SVG/pservers.html#RadialGradientElement
+   *
+   *  @example
+   *
+   *  <linearGradient id="linearGrad1">
+   *    <stop offset="0%" stop-color="white"/>
+   *    <stop offset="100%" stop-color="black"/>
+   *  </linearGradient>
+   *
+   *  OR
+   *
+   *  <linearGradient id="linearGrad2">
+   *    <stop offset="0" style="stop-color:rgb(255,255,255)"/>
+   *    <stop offset="1" style="stop-color:rgb(0,0,0)"/>
+   *  </linearGradient>
+   *
+   *  OR
+   *
+   *  <radialGradient id="radialGrad1">
+   *    <stop offset="0%" stop-color="white" stop-opacity="1" />
+   *    <stop offset="50%" stop-color="black" stop-opacity="0.5" />
+   *    <stop offset="100%" stop-color="white" stop-opacity="1" />
+   *  </radialGradient>
+   *
+   *  OR
+   *
+   *  <radialGradient id="radialGrad2">
+   *    <stop offset="0" stop-color="rgb(255,255,255)" />
+   *    <stop offset="0.5" stop-color="rgb(0,0,0)" />
+   *    <stop offset="1" stop-color="rgb(255,255,255)" />
+   *  </radialGradient>
+   *
+   */
+  static fromElement(
+    el: SVGGradientElement,
+    instance: FabricObject,
+    svgOptions: SVGOptions,
+  ): Gradient<GradientType> {
+    const gradientUnits = parseGradientUnits(el);
+    const center = instance._findCenterFromElement();
+    return new this({
+      id: el.getAttribute('id') || undefined,
+      type: parseType(el),
+      coords: parseCoords(el, {
+        width: svgOptions.viewBoxWidth || svgOptions.width,
+        height: svgOptions.viewBoxHeight || svgOptions.height,
+      }),
+      colorStops: parseColorStops(el, svgOptions.opacity),
+      gradientUnits,
+      gradientTransform: parseTransformAttribute(
+        el.getAttribute('gradientTransform') || '',
+      ),
+      ...(gradientUnits === 'pixels'
+        ? {
+            offsetX: instance.width / 2 - center.x,
+            offsetY: instance.height / 2 - center.y,
+          }
+        : {
+            offsetX: 0,
+            offsetY: 0,
+          }),
+    });
+  }
+  /* _FROM_SVG_END_ */
+}
+
+classRegistry.setClass(Gradient, 'gradient');
+classRegistry.setClass(Gradient, 'linear');
+classRegistry.setClass(Gradient, 'radial');

package/src/gradient/constants.ts

@@ -0,0 +1,12 @@
+export const linearDefaultCoords = {
+  x1: 0,
+  y1: 0,
+  x2: 0,
+  y2: 0,
+};
+
+export const radialDefaultCoords = {
+  ...linearDefaultCoords,
+  r1: 0,
+  r2: 0,
+};

package/src/gradient/index.ts

@@ -0,0 +1,2 @@
+export * from './Gradient';
+export type * from './typedefs';

package/src/gradient/parser/misc.ts

@@ -0,0 +1,13 @@
+import type { GradientType, GradientUnits } from '../typedefs';
+
+export function parseType(el: SVGGradientElement): GradientType {
+  return el.nodeName === 'linearGradient' || el.nodeName === 'LINEARGRADIENT'
+    ? 'linear'
+    : 'radial';
+}
+
+export function parseGradientUnits(el: SVGGradientElement): GradientUnits {
+  return el.getAttribute('gradientUnits') === 'userSpaceOnUse'
+    ? 'pixels'
+    : 'percentage';
+}

package/src/gradient/parser/parseColorStops.ts

@@ -0,0 +1,58 @@
+import { Color } from '../../color/Color';
+import { parsePercent } from '../../parser/percent';
+import { ifNaN } from '../../util/internals/ifNaN';
+import type { ColorStop } from '../typedefs';
+
+const RE_KEY_VALUE_PAIRS = /\s*;\s*/;
+const RE_KEY_VALUE = /\s*:\s*/;
+
+function parseColorStop(el: SVGStopElement, opacityMultiplier: number) {
+  let colorValue, opacityValue;
+  const style = el.getAttribute('style');
+  if (style) {
+    const keyValuePairs = style.split(RE_KEY_VALUE_PAIRS);
+
+    if (keyValuePairs[keyValuePairs.length - 1] === '') {
+      keyValuePairs.pop();
+    }
+
+    for (let i = keyValuePairs.length; i--; ) {
+      const [key, value] = keyValuePairs[i]
+        .split(RE_KEY_VALUE)
+        .map((s) => s.trim());
+      if (key === 'stop-color') {
+        colorValue = value;
+      } else if (key === 'stop-opacity') {
+        opacityValue = value;
+      }
+    }
+  }
+
+  colorValue = colorValue || el.getAttribute('stop-color') || 'rgb(0,0,0)';
+  opacityValue = ifNaN(
+    parseFloat(opacityValue || el.getAttribute('stop-opacity') || ''),
+    1,
+  );
+
+  const color = new Color(colorValue);
+
+  color.setAlpha(color.getAlpha() * opacityValue * opacityMultiplier);
+
+  return {
+    offset: parsePercent(el.getAttribute('offset'), 0),
+    color: color.toRgba(),
+  };
+}
+
+export function parseColorStops(
+  el: SVGGradientElement,
+  opacityAttr: string | null,
+) {
+  const colorStops: ColorStop[] = [],
+    colorStopEls = el.getElementsByTagName('stop'),
+    multiplier = parsePercent(opacityAttr, 1);
+  for (let i = colorStopEls.length; i--; ) {
+    colorStops.push(parseColorStop(colorStopEls[i], multiplier));
+  }
+  return colorStops;
+}

package/src/gradient/parser/parseCoords.ts

@@ -0,0 +1,76 @@
+import { isPercent } from '../../parser/percent';
+import type { TSize } from '../../typedefs';
+import type { GradientCoords, GradientType, GradientUnits } from '../typedefs';
+import { parseGradientUnits, parseType } from './misc';
+
+function convertPercentUnitsToValues<
+  T extends GradientType,
+  K extends keyof GradientCoords<T>,
+>(
+  valuesToConvert: Record<K, string | number>,
+  { width, height, gradientUnits }: TSize & { gradientUnits: GradientUnits },
+) {
+  let finalValue;
+  return (Object.keys(valuesToConvert) as K[]).reduce(
+    (acc, prop) => {
+      const propValue = valuesToConvert[prop];
+      if (propValue === 'Infinity') {
+        finalValue = 1;
+      } else if (propValue === '-Infinity') {
+        finalValue = 0;
+      } else {
+        finalValue =
+          typeof propValue === 'string' ? parseFloat(propValue) : propValue;
+        if (typeof propValue === 'string' && isPercent(propValue)) {
+          finalValue *= 0.01;
+          if (gradientUnits === 'pixels') {
+            // then we need to fix those percentages here in svg parsing
+            if (prop === 'x1' || prop === 'x2' || prop === 'r2') {
+              finalValue *= width;
+            }
+            if (prop === 'y1' || prop === 'y2') {
+              finalValue *= height;
+            }
+          }
+        }
+      }
+      acc[prop] = finalValue;
+      return acc;
+    },
+    {} as Record<K, number>,
+  );
+}
+
+function getValue(el: SVGGradientElement, key: string) {
+  return el.getAttribute(key);
+}
+
+export function parseLinearCoords(el: SVGGradientElement) {
+  return {
+    x1: getValue(el, 'x1') || 0,
+    y1: getValue(el, 'y1') || 0,
+    x2: getValue(el, 'x2') || '100%',
+    y2: getValue(el, 'y2') || 0,
+  };
+}
+
+export function parseRadialCoords(el: SVGGradientElement) {
+  return {
+    x1: getValue(el, 'fx') || getValue(el, 'cx') || '50%',
+    y1: getValue(el, 'fy') || getValue(el, 'cy') || '50%',
+    r1: 0,
+    x2: getValue(el, 'cx') || '50%',
+    y2: getValue(el, 'cy') || '50%',
+    r2: getValue(el, 'r') || '50%',
+  };
+}
+
+export function parseCoords(el: SVGGradientElement, size: TSize) {
+  return convertPercentUnitsToValues(
+    parseType(el) === 'linear' ? parseLinearCoords(el) : parseRadialCoords(el),
+    {
+      ...size,
+      gradientUnits: parseGradientUnits(el),
+    },
+  );
+}

package/src/gradient/typedefs.ts

@@ -0,0 +1,108 @@
+import type { Percent, TMat2D } from '../typedefs';
+
+export type GradientUnits = 'pixels' | 'percentage';
+
+export type GradientType = 'linear' | 'radial';
+
+export type GradientCoordValue = number | Percent | string;
+
+export type ColorStop = {
+  color: string;
+  offset: number;
+};
+
+export type LinearGradientCoords<T extends GradientCoordValue> = {
+  /**
+   * X coordiante of the first point
+   */
+  x1: T;
+  /**
+   * Y coordiante of the first point
+   */
+  y1: T;
+  /**
+   * X coordiante of the second point
+   */
+  x2: T;
+  /**
+   * Y coordiante of the second point
+   */
+  y2: T;
+};
+
+export type RadialGradientCoords<T extends GradientCoordValue> = {
+  /**
+   * X coordinate of the first focal point
+   */
+  x1: T;
+  /**
+   * Y coordiante of the first focal point
+   */
+  y1: T;
+  /**
+   * X coordiante of the second focal point
+   */
+  x2: T;
+  /**
+   * Y coordiante of the second focal point
+   */
+  y2: T;
+  /**
+   * radius of the inner circle
+   */
+  r1: T;
+  /**
+   * radius of the outer circle
+   */
+  r2: T;
+};
+
+export type GradientCoords<T extends GradientType> = T extends 'linear'
+  ? LinearGradientCoords<number>
+  : RadialGradientCoords<number>;
+
+export type GradientOptions<T extends GradientType> = {
+  type?: T;
+  gradientUnits?: GradientUnits;
+  colorStops?: ColorStop[];
+  coords?: Partial<GradientCoords<T>>;
+  /**
+   * @todo rename?
+   */
+  gradientTransform?: TMat2D;
+  id?: string;
+  /**
+   * SVG import compatibility
+   */
+  offsetX?: number;
+  /**
+   * SVG import compatibility
+   */
+  offsetY?: number;
+};
+
+export type SVGOptions = {
+  /**
+   * width part of the viewBox attribute on svg
+   */
+  viewBoxWidth: number;
+  /**
+   * height part of the viewBox attribute on svg
+   */
+  viewBoxHeight: number;
+  /**
+   * width part of the svg tag if viewBox is not specified
+   */
+  width: number;
+  /**
+   * height part of the svg tag if viewBox is not specified
+   */
+  height: number;
+
+  opacity: string | null;
+};
+
+export type SerializedGradientProps<T extends GradientType> = Omit<
+  GradientOptions<T>,
+  'id'
+>;