@nasser-sw/fabric 7.0.0-beta1

package/src/parser/getCSSRules.ts

@@ -0,0 +1,68 @@
+import type { CSSRules } from './typedefs';
+
+/**
+ * Returns CSS rules for a given SVG document
+ * @param {HTMLElement} doc SVG document to parse
+ * @return {Object} CSS rules of this document
+ */
+export function getCSSRules(doc: Document) {
+  const styles = doc.getElementsByTagName('style');
+  const allRules: CSSRules = {};
+
+  // very crude parsing of style contents
+  for (let i = 0; i < styles.length; i++) {
+    const styleContents = (styles[i].textContent || '').replace(
+      // remove comments
+      /\/\*[\s\S]*?\*\//g,
+      '',
+    );
+
+    if (styleContents.trim() === '') {
+      continue;
+    }
+    // recovers all the rule in this form `body { style code... }`
+    // rules = styleContents.match(/[^{]*\{[\s\S]*?\}/g);
+    styleContents
+      .split('}')
+      // remove empty rules and remove everything if we didn't split in at least 2 pieces
+      .filter((rule, index, array) => array.length > 1 && rule.trim())
+      // at this point we have hopefully an array of rules `body { style code... `
+      .forEach((rule) => {
+        // if there is more than one opening bracket and the rule starts with '@', it is likely
+        // a nested at-rule like @media, @supports, @scope, etc. Ignore these as the code below
+        // can not handle it.
+        if (
+          (rule.match(/{/g) || []).length > 1 &&
+          rule.trim().startsWith('@')
+        ) {
+          return;
+        }
+
+        const match = rule.split('{'),
+          ruleObj: Record<string, string> = {},
+          declaration = match[1].trim(),
+          propertyValuePairs = declaration.split(';').filter(function (pair) {
+            return pair.trim();
+          });
+
+        for (let j = 0; j < propertyValuePairs.length; j++) {
+          const pair = propertyValuePairs[j].split(':'),
+            property = pair[0].trim(),
+            value = pair[1].trim();
+          ruleObj[property] = value;
+        }
+        rule = match[0].trim();
+        rule.split(',').forEach((_rule) => {
+          _rule = _rule.replace(/^svg/i, '').trim();
+          if (_rule === '') {
+            return;
+          }
+          allRules[_rule] = {
+            ...(allRules[_rule] || {}),
+            ...ruleObj,
+          };
+        });
+      });
+  }
+  return allRules;
+}

package/src/parser/getGlobalStylesForElement.ts

@@ -0,0 +1,22 @@
+import { elementMatchesRule } from './elementMatchesRule';
+import type { CSSRules } from './typedefs';
+
+/**
+ * @private
+ */
+
+export function getGlobalStylesForElement(
+  element: HTMLElement | SVGElement,
+  cssRules: CSSRules = {},
+) {
+  let styles: Record<string, string> = {};
+  for (const rule in cssRules) {
+    if (elementMatchesRule(element, rule.split(' '))) {
+      styles = {
+        ...styles,
+        ...cssRules[rule],
+      };
+    }
+  }
+  return styles;
+}

package/src/parser/getGradientDefs.ts

@@ -0,0 +1,33 @@
+import { getMultipleNodes } from './getMultipleNodes';
+import { recursivelyParseGradientsXlink } from './recursivelyParseGradientsXlink';
+
+const tagArray = [
+  'linearGradient',
+  'radialGradient',
+  'svg:linearGradient',
+  'svg:radialGradient',
+];
+
+/**
+ * Parses an SVG document, returning all of the gradient declarations found in it
+ * @param {SVGDocument} doc SVG document to parse
+ * @return {Object} Gradient definitions; key corresponds to element id, value -- to gradient definition element
+ */
+export function getGradientDefs(
+  doc: Document,
+): Record<string, SVGGradientElement> {
+  const elList = getMultipleNodes(doc, tagArray);
+  const gradientDefs: Record<string, SVGGradientElement> = {};
+  let j = elList.length;
+  while (j--) {
+    const el = elList[j];
+    if (el.getAttribute('xlink:href')) {
+      recursivelyParseGradientsXlink(doc, el);
+    }
+    const id = el.getAttribute('id');
+    if (id) {
+      gradientDefs[id] = el as SVGGradientElement;
+    }
+  }
+  return gradientDefs;
+}

package/src/parser/getMultipleNodes.ts

@@ -0,0 +1,19 @@
+export function getMultipleNodes(
+  doc: Document,
+  nodeNames: string[],
+): Element[] {
+  let nodeName,
+    nodeArray: Element[] = [],
+    nodeList,
+    i,
+    len;
+  for (i = 0, len = nodeNames.length; i < len; i++) {
+    nodeName = nodeNames[i];
+    nodeList = doc.getElementsByTagNameNS(
+      'http://www.w3.org/2000/svg',
+      nodeName,
+    );
+    nodeArray = nodeArray.concat(Array.from(nodeList));
+  }
+  return nodeArray;
+}

package/src/parser/getSvgRegex.ts

@@ -0,0 +1,3 @@
+export function getSvgRegex(arr: string[]) {
+  return new RegExp('^(' + arr.join('|') + ')\\b', 'i');
+}

package/src/parser/getTagName.ts

@@ -0,0 +1 @@
+export const getTagName = (node: Element) => node.tagName.replace('svg:', '');

package/src/parser/hasInvalidAncestor.ts

@@ -0,0 +1,20 @@
+import { svgInvalidAncestors } from './constants';
+import { getSvgRegex } from './getSvgRegex';
+import { getTagName } from './getTagName';
+
+const svgInvalidAncestorsRegEx = getSvgRegex(svgInvalidAncestors);
+
+export function hasInvalidAncestor(element: Element) {
+  let _element: Element | null = element;
+  while (_element && (_element = _element.parentElement)) {
+    if (
+      _element &&
+      _element.nodeName &&
+      svgInvalidAncestorsRegEx.test(getTagName(_element)) &&
+      !_element.getAttribute('instantiated_by_use')
+    ) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/parser/loadSVGFromString.test.ts

@@ -0,0 +1,75 @@
+import { Path } from '../shapes/Path';
+import { Rect } from '../shapes/Rect';
+import { loadSVGFromString } from './loadSVGFromString';
+
+import { describe, expect, it } from 'vitest';
+import { Polygon } from '../../fabric';
+
+const SVG_DOC_AS_STRING =
+  '<?xml version="1.0"?>\
+    <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">\
+    <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">\
+      <polygon fill="red" stroke="blue" stroke-width="10" points="350, 75 379,161 469,161\
+        397,215 423,301 350,250 277,301 303,215 231,161 321,161" />\
+    </svg>';
+
+describe('loadSVGFromString', () => {
+  it('returns successful parse of svg with use tag containing bad reference', async () => {
+    // in this case, ignore bad use but still load rest of svg
+    const str = `<svg viewBox="0 0 128 128" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+      <rect width="10" height="10" />
+      <use href="#missing" x="50" y="50" ></use>
+      </svg>`;
+
+    const parsedSvg = await loadSVGFromString(str);
+    expect(parsedSvg.objects[0]).not.toBeNull();
+    if (parsedSvg.objects[0] !== null) {
+      expect(parsedSvg.objects[0].isType('Rect')).toBe(true);
+    }
+  });
+
+  it('returns successful parse of svg with use tag containing bad clip-path', async () => {
+    // in this case, load svg but ignore clip-path attribute in <use>
+    const str = `<svg viewBox="0 0 128 128" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+      <defs>
+      <path id="heart" d="M10,30 A20,20,0,0,1,50,30 A20,20,0,0,1,90,30 Q90,60,50,90 Q10,60,10,30 Z" />
+      </defs>
+      <use clip-path="url(#myClip)" href="#heart" fill="red" />
+      </svg>`;
+
+    const parsedSvg = await loadSVGFromString(str);
+    if (parsedSvg.objects[0] !== null) {
+      expect(parsedSvg.objects[0] instanceof Path).toBe(true);
+    }
+  });
+
+  it('returns successful parse of svg with id starting with number', async () => {
+    const str = `<svg viewBox="0 0 128 128" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+      <rect id="123xyz" width="10" height="10" />
+      </svg>`;
+
+    const parsedSvg = await loadSVGFromString(str);
+
+    expect(
+      parsedSvg.objects[0] instanceof Rect &&
+        (parsedSvg.objects[0] as Rect & { id: string }).id,
+    ).toBe('123xyz');
+  });
+
+  it('loads SVG from string correctly', async () => {
+    expect(loadSVGFromString).toBeTypeOf('function');
+
+    const { objects: loadedObjects } =
+      await loadSVGFromString(SVG_DOC_AS_STRING);
+    expect(loadedObjects[0]).toBeInstanceOf(Polygon);
+    expect(loadedObjects[0]!.fill).toBe('red');
+  });
+
+  it('loads SVG with surrounding whitespace correctly', async () => {
+    const { objects } = await loadSVGFromString(
+      '   \n\n  ' + SVG_DOC_AS_STRING + '  ',
+    );
+    expect(objects[0]).toBeInstanceOf(Polygon);
+    expect(objects[0]!.fill).toBe('red');
+  });
+});

package/src/parser/loadSVGFromString.ts

@@ -0,0 +1,28 @@
+import { getFabricWindow } from '../env';
+import type { LoadImageOptions } from '../util/misc/objectEnlive';
+import { parseSVGDocument } from './parseSVGDocument';
+import type { SVGParsingOutput, TSvgReviverCallback } from './typedefs';
+
+/**
+ * Takes string corresponding to an SVG document, and parses it into a set of fabric objects
+ * @param {String} string representing the svg
+ * @param {TSvgParsedCallback} callback Invoked when the parsing is done, with null if parsing wasn't possible with the list of svg nodes.
+ * {@link TSvgParsedCallback} also receives `allElements` array as the last argument. This is the full list of svg nodes available in the document.
+ * You may want to use it if you are trying to regroup the objects as they were originally grouped in the SVG. ( This was the reason why it was added )
+ * @param {TSvgReviverCallback} [reviver] Extra callback for further parsing of SVG elements, called after each fabric object has been created.
+ * Takes as input the original svg element and the generated `FabricObject` as arguments. Used to inspect extra properties not parsed by fabric,
+ * or extra custom manipulation
+ * @param {Object} [options] Object containing options for parsing
+ * @param {String} [options.crossOrigin] crossOrigin setting to use for external resources
+ * @param {AbortSignal} [options.signal] handle aborting, see https://developer.mozilla.org/en-US/docs/Web/API/AbortController/signal
+ */
+export function loadSVGFromString(
+  string: string,
+  reviver?: TSvgReviverCallback,
+  options?: LoadImageOptions,
+): Promise<SVGParsingOutput> {
+  const parser = new (getFabricWindow().DOMParser)(),
+    // should we use `image/svg+xml` here?
+    doc = parser.parseFromString(string.trim(), 'text/xml');
+  return parseSVGDocument(doc, reviver, options);
+}

package/src/parser/loadSVGFromURL.ts

@@ -0,0 +1,42 @@
+import { createEmptyResponse } from './parseSVGDocument';
+import { loadSVGFromString } from './loadSVGFromString';
+import type { SVGParsingOutput, TSvgReviverCallback } from './typedefs';
+import type { LoadImageOptions } from '../util/misc/objectEnlive';
+import { FabricError } from '../util/internals/console';
+
+/**
+ * Takes url corresponding to an SVG document, and parses it into a set of fabric objects.
+ * Note that SVG is fetched via fetch API, so it needs to conform to SOP (Same Origin Policy)
+ * @param {string} url where the SVG is
+ * @param {TSvgParsedCallback} callback Invoked when the parsing is done, with null if parsing wasn't possible with the list of svg nodes.
+ * {@link TSvgParsedCallback} also receives `allElements` array as the last argument. This is the full list of svg nodes available in the document.
+ * You may want to use it if you are trying to regroup the objects as they were originally grouped in the SVG. ( This was the reason why it was added )
+ * @param {TSvgReviverCallback} [reviver] Extra callback for further parsing of SVG elements, called after each fabric object has been created.
+ * Takes as input the original svg element and the generated `FabricObject` as arguments. Used to inspect extra properties not parsed by fabric,
+ * or extra custom manipulation
+ * @param {Object} [options] Object containing options for parsing
+ * @param {String} [options.crossOrigin] crossOrigin setting to use for external resources
+ * @param {AbortSignal} [options.signal] handle aborting, see https://developer.mozilla.org/en-US/docs/Web/API/AbortController/signal
+ */
+export function loadSVGFromURL(
+  url: string,
+  reviver?: TSvgReviverCallback,
+  options: LoadImageOptions = {},
+): Promise<SVGParsingOutput> {
+  return fetch(url.replace(/^\n\s*/, '').trim(), {
+    signal: options.signal,
+  })
+    .then((response) => {
+      if (!response.ok) {
+        throw new FabricError(`HTTP error! status: ${response.status}`);
+      }
+      return response.text();
+    })
+    .then((svgText) => {
+      return loadSVGFromString(svgText, reviver, options);
+    })
+    .catch(() => {
+      // this is an unhappy path, we dont care about speed
+      return createEmptyResponse();
+    });
+}

package/src/parser/normalizeAttr.ts

@@ -0,0 +1,5 @@
+import { attributesMap } from './constants';
+
+export const normalizeAttr = (
+  attr: keyof typeof attributesMap | string,
+): string => attributesMap[attr as keyof typeof attributesMap] ?? attr;

package/src/parser/normalizeValue.ts

@@ -0,0 +1,76 @@
+import { multiplyTransformMatrices } from '../util/misc/matrix';
+import { parseUnit } from '../util/misc/svgParsing';
+import { parseTransformAttribute } from './parseTransformAttribute';
+import { CENTER, LEFT, RIGHT, NONE, FILL, STROKE } from '../constants';
+import { TEXT_DECORATION_THICKNESS } from '../shapes/Text/constants';
+
+export function normalizeValue(
+  attr: string,
+  value: any,
+  parentAttributes: Record<string, any>,
+  fontSize: number,
+): string | null | boolean | number[] | number {
+  const isArray = Array.isArray(value);
+  let parsed: number | number[];
+  let ouputValue: string | null | boolean | number[] | number = value;
+  if ((attr === FILL || attr === STROKE) && value === NONE) {
+    ouputValue = '';
+  } else if (attr === 'strokeUniform') {
+    return value === 'non-scaling-stroke';
+  } else if (attr === 'strokeDashArray') {
+    if (value === NONE) {
+      ouputValue = null;
+    } else {
+      ouputValue = value.replace(/,/g, ' ').split(/\s+/).map(parseFloat);
+    }
+  } else if (attr === 'transformMatrix') {
+    if (parentAttributes && parentAttributes.transformMatrix) {
+      ouputValue = multiplyTransformMatrices(
+        parentAttributes.transformMatrix,
+        parseTransformAttribute(value),
+      );
+    } else {
+      ouputValue = parseTransformAttribute(value);
+    }
+  } else if (attr === 'visible') {
+    ouputValue = value !== NONE && value !== 'hidden';
+    // display=none on parent element always takes precedence over child element
+    if (parentAttributes && parentAttributes.visible === false) {
+      ouputValue = false;
+    }
+  } else if (attr === 'opacity') {
+    ouputValue = parseFloat(value);
+    if (parentAttributes && typeof parentAttributes.opacity !== 'undefined') {
+      ouputValue *= parentAttributes.opacity as number;
+    }
+  } else if (attr === 'textAnchor' /* text-anchor */) {
+    ouputValue = value === 'start' ? LEFT : value === 'end' ? RIGHT : CENTER;
+  } else if (attr === 'charSpacing' || attr === TEXT_DECORATION_THICKNESS) {
+    // parseUnit returns px and we convert it to em
+    parsed = (parseUnit(value, fontSize) / fontSize) * 1000;
+  } else if (attr === 'paintFirst') {
+    const fillIndex = value.indexOf(FILL);
+    const strokeIndex = value.indexOf(STROKE);
+    ouputValue = FILL;
+    if (fillIndex > -1 && strokeIndex > -1 && strokeIndex < fillIndex) {
+      ouputValue = STROKE;
+    } else if (fillIndex === -1 && strokeIndex > -1) {
+      ouputValue = STROKE;
+    }
+  } else if (
+    attr === 'href' ||
+    attr === 'xlink:href' ||
+    attr === 'font' ||
+    attr === 'id'
+  ) {
+    return value;
+  } else if (attr === 'imageSmoothing') {
+    return value === 'optimizeQuality';
+  } else {
+    parsed = isArray
+      ? (value as string[]).map(parseUnit)
+      : parseUnit(value, fontSize);
+  }
+
+  return !isArray && isNaN(parsed! as number) ? ouputValue : parsed!;
+}

package/src/parser/parseAttributes.ts

@@ -0,0 +1,92 @@
+import { DEFAULT_SVG_FONT_SIZE } from '../constants';
+import { parseUnit } from '../util/misc/svgParsing';
+import { cPath, fSize, svgValidParentsRegEx } from './constants';
+import { getGlobalStylesForElement } from './getGlobalStylesForElement';
+import { normalizeAttr } from './normalizeAttr';
+import { normalizeValue } from './normalizeValue';
+import { parseFontDeclaration } from './parseFontDeclaration';
+import { parseStyleAttribute } from './parseStyleAttribute';
+import { setStrokeFillOpacity } from './setStrokeFillOpacity';
+import type { CSSRules } from './typedefs';
+
+/**
+ * Returns an object of attributes' name/value, given element and an array of attribute names;
+ * Parses parent "g" nodes recursively upwards.
+ * @param {SVGElement | HTMLElement} element Element to parse
+ * @param {Array} attributes Array of attributes to parse
+ * @return {Object} object containing parsed attributes' names/values
+ */
+export function parseAttributes(
+  element: HTMLElement | SVGElement | null,
+  attributes: string[],
+  cssRules?: CSSRules,
+): Record<string, any> {
+  if (!element) {
+    return {};
+  }
+
+  let parentAttributes: Record<string, string> = {},
+    fontSize: number,
+    parentFontSize = DEFAULT_SVG_FONT_SIZE;
+
+  // if there's a parent container (`g` or `a` or `symbol` node), parse its attributes recursively upwards
+  if (
+    element.parentNode &&
+    svgValidParentsRegEx.test(element.parentNode.nodeName)
+  ) {
+    parentAttributes = parseAttributes(
+      element.parentElement,
+      attributes,
+      cssRules,
+    );
+    if (parentAttributes.fontSize) {
+      fontSize = parentFontSize = parseUnit(parentAttributes.fontSize);
+    }
+  }
+
+  const ownAttributes: Record<string, string> = {
+    ...attributes.reduce<Record<string, string>>((memo, attr) => {
+      const value = element.getAttribute(attr);
+      if (value) {
+        memo[attr] = value;
+      }
+      return memo;
+    }, {}),
+    // add values parsed from style, which take precedence over attributes
+    // (see: http://www.w3.org/TR/SVG/styling.html#UsingPresentationAttributes)
+    ...getGlobalStylesForElement(element, cssRules),
+    ...parseStyleAttribute(element),
+  };
+
+  if (ownAttributes[cPath]) {
+    element.setAttribute(cPath, ownAttributes[cPath]);
+  }
+  if (ownAttributes[fSize]) {
+    // looks like the minimum should be 9px when dealing with ems. this is what looks like in browsers.
+    fontSize = parseUnit(ownAttributes[fSize], parentFontSize);
+    ownAttributes[fSize] = `${fontSize}`;
+  }
+
+  // this should have its own complex type
+  const normalizedStyle: Record<
+    string,
+    string | boolean | number | number[] | null
+  > = {};
+  for (const attr in ownAttributes) {
+    const normalizedAttr = normalizeAttr(attr);
+    const normalizedValue = normalizeValue(
+      normalizedAttr,
+      ownAttributes[attr],
+      parentAttributes,
+      fontSize!,
+    );
+    normalizedStyle[normalizedAttr] = normalizedValue;
+  }
+  if (normalizedStyle && normalizedStyle.font) {
+    parseFontDeclaration(normalizedStyle.font as string, normalizedStyle);
+  }
+  const mergedAttrs = { ...parentAttributes, ...normalizedStyle };
+  return svgValidParentsRegEx.test(element.nodeName)
+    ? mergedAttrs
+    : setStrokeFillOpacity(mergedAttrs);
+}

package/src/parser/parseFontDeclaration.ts

@@ -0,0 +1,43 @@
+import { parseUnit } from '../util/misc/svgParsing';
+import { reFontDeclaration } from './constants';
+
+/**
+ * Parses a short font declaration, building adding its properties to a style object
+ * @param {String} value font declaration
+ * @param {Object} oStyle definition
+ */
+export function parseFontDeclaration(
+  value: string,
+  oStyle: Record<string, any>,
+): void {
+  const match = value.match(reFontDeclaration);
+
+  if (!match) {
+    return;
+  }
+  const fontStyle = match[1],
+    // font variant is not used
+    // fontVariant = match[2],
+    fontWeight = match[3],
+    fontSize = match[4],
+    lineHeight = match[5],
+    fontFamily = match[6];
+
+  if (fontStyle) {
+    oStyle.fontStyle = fontStyle;
+  }
+  if (fontWeight) {
+    oStyle.fontWeight = isNaN(parseFloat(fontWeight))
+      ? fontWeight
+      : parseFloat(fontWeight);
+  }
+  if (fontSize) {
+    oStyle.fontSize = parseUnit(fontSize);
+  }
+  if (fontFamily) {
+    oStyle.fontFamily = fontFamily;
+  }
+  if (lineHeight) {
+    oStyle.lineHeight = lineHeight === 'normal' ? 1 : lineHeight;
+  }
+}

package/src/parser/parsePointsAttribute.ts

@@ -0,0 +1,31 @@
+import type { XY } from '../Point';
+
+/**
+ * Parses "points" attribute, returning an array of values
+ * @param {String} points points attribute string
+ * @return {Array} array of points
+ */
+export function parsePointsAttribute(points: string | null): XY[] {
+  // points attribute is required and must not be empty
+  if (!points) {
+    return [];
+  }
+
+  // replace commas with whitespace and remove bookending whitespace
+  const pointsSplit: string[] = points.replace(/,/g, ' ').trim().split(/\s+/);
+
+  const parsedPoints = [];
+
+  for (let i = 0; i < pointsSplit.length; i += 2) {
+    parsedPoints.push({
+      x: parseFloat(pointsSplit[i]),
+      y: parseFloat(pointsSplit[i + 1]),
+    });
+  }
+
+  // odd number of points is an error
+  // if (parsedPoints.length % 2 !== 0) {
+  //   return null;
+  // }
+  return parsedPoints;
+}

package/src/parser/parseSVGDocument.ts

@@ -0,0 +1,93 @@
+import { applyViewboxTransform } from './applyViewboxTransform';
+import { svgValidTagNamesRegEx } from './constants';
+import { hasInvalidAncestor } from './hasInvalidAncestor';
+import { parseUseDirectives } from './parseUseDirectives';
+import type { SVGParsingOutput, TSvgReviverCallback } from './typedefs';
+import type { LoadImageOptions } from '../util/misc/objectEnlive';
+import { ElementsParser } from './elements_parser';
+import { log, SignalAbortedError } from '../util/internals/console';
+import { getTagName } from './getTagName';
+
+const isValidSvgTag = (el: Element) =>
+  svgValidTagNamesRegEx.test(getTagName(el));
+
+export const createEmptyResponse = (): SVGParsingOutput => ({
+  objects: [],
+  elements: [],
+  options: {},
+  allElements: [],
+});
+
+/**
+ * Parses an SVG document, converts it to an array of corresponding fabric.* instances and passes them to a callback
+ * @param {HTMLElement} doc SVG document to parse
+ * @param {TSvgParsedCallback} callback Invoked when the parsing is done, with null if parsing wasn't possible with the list of svg nodes.
+ * @param {TSvgReviverCallback} [reviver] Extra callback for further parsing of SVG elements, called after each fabric object has been created.
+ * Takes as input the original svg element and the generated `FabricObject` as arguments. Used to inspect extra properties not parsed by fabric,
+ * or extra custom manipulation
+ * @param {Object} [options] Object containing options for parsing
+ * @param {String} [options.crossOrigin] crossOrigin setting to use for external resources
+ * @param {AbortSignal} [options.signal] handle aborting, see https://developer.mozilla.org/en-US/docs/Web/API/AbortController/signal
+ * @return {SVGParsingOutput}
+ * {@link SVGParsingOutput} also receives `allElements` array as the last argument. This is the full list of svg nodes available in the document.
+ * You may want to use it if you are trying to regroup the objects as they were originally grouped in the SVG. ( This was the reason why it was added )
+ */
+export async function parseSVGDocument(
+  doc: Document,
+  reviver?: TSvgReviverCallback,
+  { crossOrigin, signal }: LoadImageOptions = {},
+): Promise<SVGParsingOutput> {
+  if (signal && signal.aborted) {
+    log('log', new SignalAbortedError('parseSVGDocument'));
+    // this is an unhappy path, we dont care about speed
+    return createEmptyResponse();
+  }
+  const documentElement = doc.documentElement;
+  parseUseDirectives(doc);
+
+  const descendants = Array.from(documentElement.getElementsByTagName('*')),
+    options = {
+      ...applyViewboxTransform(documentElement),
+      crossOrigin,
+      signal,
+    };
+  const elements = descendants.filter((el) => {
+    applyViewboxTransform(el);
+    return isValidSvgTag(el) && !hasInvalidAncestor(el); // http://www.w3.org/TR/SVG/struct.html#DefsElement
+  });
+  if (!elements || (elements && !elements.length)) {
+    return {
+      ...createEmptyResponse(),
+      options,
+      allElements: descendants,
+    };
+  }
+  const localClipPaths: Record<string, Element[]> = {};
+  descendants
+    .filter((el) => getTagName(el) === 'clipPath')
+    .forEach((el) => {
+      el.setAttribute('originalTransform', el.getAttribute('transform') || '');
+      const id = el.getAttribute('id')!;
+      localClipPaths[id] = Array.from(el.getElementsByTagName('*')).filter(
+        (el) => isValidSvgTag(el),
+      );
+    });
+
+  // Precedence of rules:   style > class > attribute
+  const elementParser = new ElementsParser(
+    elements,
+    options,
+    reviver,
+    doc,
+    localClipPaths,
+  );
+
+  const instances = await elementParser.parse();
+
+  return {
+    objects: instances,
+    elements,
+    options,
+    allElements: descendants,
+  };
+}