svg · strarsis · Sep 2, 2020 · Sep 4, 2020 · Sep 4, 2020 · Mar 19, 2021
diff --git a/docs/04-plugins/dereferenceUses.mdx b/docs/04-plugins/dereferenceUses.mdx
@@ -0,0 +1,15 @@
+---
+title: dereferenceUses
+svgo:
+  pluginId: dereferenceUses
+  defaultPlugin: false
+  parameters:
+    keepHref:
+      description: keep (xlink:)href attributes
+      default: false
+    symbolContainer:
+      description: browsers use <svg/> as container of <symbol/> content (e.g. <g> could also be used)
+      default: 'svg'
+---
+
+Dereferences <use/> elements.
diff --git a/lib/builtin.js b/lib/builtin.js
@@ -14,6 +14,7 @@ import * as convertPathData from '../plugins/convertPathData.js';
 import * as convertShapeToPath from '../plugins/convertShapeToPath.js';
 import * as convertStyleToAttrs from '../plugins/convertStyleToAttrs.js';
 import * as convertTransform from '../plugins/convertTransform.js';
+import * as dereferenceUses from '../plugins/dereferenceUses.js';
 import * as mergeStyles from '../plugins/mergeStyles.js';
 import * as inlineStyles from '../plugins/inlineStyles.js';
 import * as mergePaths from '../plugins/mergePaths.js';
@@ -70,6 +71,7 @@ export const builtin = Object.freeze([
   convertShapeToPath,
   convertStyleToAttrs,
   convertTransform,
+  dereferenceUses,
   inlineStyles,
   mergePaths,
   mergeStyles,

diff --git a/plugins/dereferenceUses.js b/plugins/dereferenceUses.js
@@ -0,0 +1,172 @@
+import * as csstree from 'css-tree';
+
+import { visitSkip, querySelector } from '../lib/xast.js';
+
+/**
+ * @typedef {import('../lib/types.js').XastElement} XastElement
+ * @typedef {import('../lib/types.js').XastParent} XastParent
+ */
+
+export const name = 'dereferenceUses';
+export const description = 'dereferences <use/> elements';
+
+export const params = {
+  keepHref: false, // keep (xlink:)href attributes
+  symbolContainer: 'svg', // browsers use <svg/> as container of <symbol/> content (e.g. <g> could also be used)
+};
+
+const OverridingUseAttributeNames = [
+  'x',
+  'y',
+  'width',
+  'height',
+  'href',
+  'xlink:href',
+];
+
+const HrefAttributeNames = [
+  'href', // By spec, `href` has precedence over (deprecated) `xlink:href`
+  'xlink:href',
+];
+
+/**
+ * Dereferences <use> elements
+ *
+ * @author strarsis <strarsis@gmail.com>
+ *
+ * @type {import('./plugins-types.js').Plugin<'dereferenceUses'>}
+ */
+export const fn = (root, params) => {
+  const { keepHref = false, symbolContainer = 'svg' } = params;
+
+  /**
+   * @type {Array<{ node: XastElement, parentNode: XastParent, targetNode?: XastElement }>}
+   */
+  let useElements = [];
+
+  return {
+    element: {
+      enter: (node, parentNode) => {
+        if (node.name === 'use') {
+          useElements.push({
+            node,
+            parentNode,
+          });
+          return visitSkip;
+        }
+      },
+    },
+
+    root: {
+      exit: (root) => {
+        // replace each <use/> with its referenced node
+        for (const useElement of useElements) {
+          // `href`/`xlink:href` value
+          let href = '';
+          for (let hrefAttributeName of HrefAttributeNames) {
+            href = useElement.node.attributes[hrefAttributeName];
+            if (href) {
+              break; // The first occurence is to be used (spec).
+            }
+          }
+          if (!href) {
+            continue;
+          }
+
+          // look up referenced element
+          const targetElement = querySelector(root, href);
+          if (!targetElement || targetElement.type !== 'element') {
+            continue;
+          }
+
+          // clone referenced element for insertion
+          const insertElement = structuredClone(targetElement);
+
+          // Attribute inheritance of the referenced element
+          // @see https://developer.mozilla.org/en-US/docs/Web/SVG/Element/use
+          //   "Only the attributes x, y, width, height and href on the use element will override those set on the referenced element.
+          //    However, any other attributes not set on the referenced element will be applied to the use element."
+          const insertElementAttributeNames = Object.keys(
+            insertElement.attributes,
+          );
+          for (const attributeName in useElement.node.attributes) {
+            // don't remove attributes from the referenced element that, by spec, override the one of the <use> element
+            if (
+              insertElementAttributeNames.includes(attributeName) &&
+              !OverridingUseAttributeNames.includes(attributeName)
+            ) {
+              continue;
+            }
+
+            // don't remove href attribute with keepHref option turned on
+            if (!keepHref && HrefAttributeNames.includes(attributeName)) {
+              continue;
+            }
+
+            // styles must be appended, not overriden
+            if (attributeName === 'style') {
+              continue;
+            }
+
+            // set overriding attributes from referenced node
+            insertElement.attributes[attributeName] =
+              useElement.node.attributes[attributeName];
+          }
+
+          // only the original node is allowed to have this ID (IDs must be unique)
+          delete insertElement.attributes['id']; // remove ID attribute
+
+          // <symbol/> elements are template elements (hence not visible),
+          // browsers would place a <symbol/> element as a different element
+          if (insertElement.name === 'symbol') {
+            insertElement.name = symbolContainer;
+          }
+
+          // apply styles of <use/> element also on top of the referenced element
+          const useElementStyles = useElement.node.attributes.style;
+          const insertElementStyles = insertElement.attributes.style;
+          const styleParseOpts = { context: 'declarationList' };
+          if (useElementStyles) {
+            const useElementStylesAst = csstree.parse(
+              useElementStyles,
+              styleParseOpts,
+            );
+            if (useElementStylesAst.type !== 'DeclarationList') {
+              continue;
+            }
+
+            const insertElementStylesAst = csstree.parse(
+              insertElementStyles,
+              styleParseOpts,
+            );
+            if (insertElementStylesAst.type !== 'DeclarationList') {
+              continue;
+            }
+
+            insertElementStylesAst.children.appendList(
+              useElementStylesAst.children,
+            );
+
+            const insertElementStylesAppended = csstree.generate(
+              insertElementStylesAst,
+            );
+            insertElement.attributes.style = insertElementStylesAppended; // append styles (styles from <use/> have higher priority)
+          }
+
+          // replace the <use/> element with the referenced, resolved element
+
+          // position of <use/> in parent
+          const useElementPosition = useElement.parentNode.children.indexOf(
+            useElement.node,
+          );
+
+          useElement.parentNode.children.splice(
+            useElementPosition,
+            1,
+            insertElement,
+          );
+        }
+      },
+    },
+  };
+};
diff --git a/plugins/plugins-types.d.ts b/plugins/plugins-types.d.ts
@@ -208,6 +208,10 @@ type DefaultPlugins = {
     xmlnsOrder?: 'front' | 'alphabetical';
   };
   sortDefsChildren: void;
+  dereferenceUses: {
+    keepHref?: boolean;
+    symbolContainer?: 'svg';
+  };
 };
 
 type PresetDefaultOverrides = {

diff --git a/test/plugins/dereferenceUses.01.svg.txt b/test/plugins/dereferenceUses.01.svg.txt
@@ -0,0 +1,21 @@
+Dereference multiple <use/> elements while keeping the href attributes.
+
+===
+
+<svg viewBox="0 0 30 10" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <circle id="myCircle" cx="5" cy="5" r="4" />
+    <use xlink:href="#myCircle" />
+    <use       href="#myCircle" />
+</svg>
+
+@@@
+
+<svg viewBox="0 0 30 10" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <circle id="myCircle" cx="5" cy="5" r="4"/>
+    <circle cx="5" cy="5" r="4" xlink:href="#myCircle"/>
+    <circle cx="5" cy="5" r="4" href="#myCircle"/>
+</svg>
+
+@@@
+
+{"keepHref":true}
diff --git a/test/plugins/dereferenceUses.02.svg.txt b/test/plugins/dereferenceUses.02.svg.txt
@@ -0,0 +1,19 @@
+Works with <use/> elements that reference to IDs without element, while keeping the href attributes.
+
+===
+
+<svg viewBox="0 0 30 10" xmlns="http://www.w3.org/2000/svg">
+    <circle id="myCircle" cx="5" cy="5" r="4" />
+    <use href="#nonExisting" />
+</svg>
+
+@@@
+
+<svg viewBox="0 0 30 10" xmlns="http://www.w3.org/2000/svg">
+    <circle id="myCircle" cx="5" cy="5" r="4"/>
+    <use href="#nonExisting"/>
+</svg>
+
+@@@
+
+{"keepHref":true}
diff --git a/test/plugins/dereferenceUses.03.svg.txt b/test/plugins/dereferenceUses.03.svg.txt
@@ -0,0 +1,21 @@
+Works with dereferencing multiple <use/> elements that reference the same element, while keeping the href attributes.
+
+===
+
+<svg viewBox="0 0 30 10" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <circle id="myCircle" cx="5" cy="5" r="4" x="5" />
+    <use href="#myCircle" x="10" />
+    <use href="#myCircle" x="20" />
+</svg>
+
+@@@
+
+<svg viewBox="0 0 30 10" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <circle id="myCircle" cx="5" cy="5" r="4" x="5"/>
+    <circle cx="5" cy="5" r="4" x="10" href="#myCircle"/>
+    <circle cx="5" cy="5" r="4" x="20" href="#myCircle"/>
+</svg>
+
+@@@
+
+{"keepHref":true}
diff --git a/test/plugins/dereferenceUses.04.svg.txt b/test/plugins/dereferenceUses.04.svg.txt
@@ -0,0 +1,21 @@
+Correctly keeps and overrides attributes of <use/> and referenced elements adhering to spec, while keeping the href attributes.
+
+===
+
+<svg viewBox="0 0 30 10" xmlns="http://www.w3.org/2000/svg">
+    <circle id="myCircle" cx="5" cy="5" r="4" stroke="blue"/>
+    <use href="#myCircle" x="10" fill="blue"/>
+    <use href="#myCircle" x="20" fill="white" stroke="red"/>
+</svg>
+
+@@@
+
+<svg viewBox="0 0 30 10" xmlns="http://www.w3.org/2000/svg">
+    <circle id="myCircle" cx="5" cy="5" r="4" stroke="blue"/>
+    <circle cx="5" cy="5" r="4" stroke="blue" href="#myCircle" x="10" fill="blue"/>
+    <circle cx="5" cy="5" r="4" stroke="blue" href="#myCircle" x="20" fill="white"/>
+</svg>
+
+@@@
+
+{"keepHref":true}
diff --git a/test/plugins/dereferenceUses.05.svg.txt b/test/plugins/dereferenceUses.05.svg.txt
@@ -0,0 +1,17 @@
+Correctly keeps and overrides attributes that exist on both, the <use/> element and the references element, without keeping the href attributes.
+
+===
+
+<svg viewBox="0 0 30 10" xmlns="http://www.w3.org/2000/svg">
+    <circle id="myCircle" cx="5" cy="5" r="4" stroke="blue"/>
+    <use href="#myCircle" x="10" fill="blue"/>
+    <use href="#myCircle" x="20" fill="white" stroke="red"/>
+</svg>
+
+@@@
+
+<svg viewBox="0 0 30 10" xmlns="http://www.w3.org/2000/svg">
+    <circle id="myCircle" cx="5" cy="5" r="4" stroke="blue"/>
+    <circle cx="5" cy="5" r="4" stroke="blue" x="10" fill="blue"/>
+    <circle cx="5" cy="5" r="4" stroke="blue" x="20" fill="white"/>
+</svg>
diff --git a/test/plugins/dereferenceUses.06.svg.txt b/test/plugins/dereferenceUses.06.svg.txt
@@ -0,0 +1,29 @@
+Use a symbol container explicitly passed as option and handle more complex SVGs.
+
+===
+
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="423" height="75" viewBox="0 0 317 56">
+    <defs>
+        <symbol overflow="visible" id="a">
+            <path d="M9.281-8.438c0-.03-.219-.25-.328-.25a.701.701 0 00-.328.172l-.672.75c0 .016-.672-.921-2-.921-2.672 0-5.562 2.765-5.562 5.546C.39-1.17 2.016.266 3.844.266c1.031 0 2.078-.516 2.703-1.063C7.657-1.78 7.922-2.969 7.922-3c0-.125-.203-.031-.203-.031l-.125-.219c-.078 0-.344.156-.36.25-.109.344-.328 1.094-1.156 1.797-.812.672-1.422.828-2.047.828-1.078 0-2.156-.484-2.156-2.344 0-.687.188-2.531 1.39-3.922C4-7.5 4.986-8.062 6.048-8.062c1.219 0 1.719.796 1.719 2.187 0 .469-.032.484-.032.61 0 .109.329.25.375.25.157 0 .36-.157.407-.376zm0 0"/>
+        </symbol>
+    </defs>
+    <use xlink:href="#a" x="-.475" y="30.513"/>
+</svg>
+
+@@@
+
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="423" height="75" viewBox="0 0 317 56">
+    <defs>
+        <symbol overflow="visible" id="a">
+            <path d="M9.281-8.438c0-.03-.219-.25-.328-.25a.701.701 0 00-.328.172l-.672.75c0 .016-.672-.921-2-.921-2.672 0-5.562 2.765-5.562 5.546C.39-1.17 2.016.266 3.844.266c1.031 0 2.078-.516 2.703-1.063C7.657-1.78 7.922-2.969 7.922-3c0-.125-.203-.031-.203-.031l-.125-.219c-.078 0-.344.156-.36.25-.109.344-.328 1.094-1.156 1.797-.812.672-1.422.828-2.047.828-1.078 0-2.156-.484-2.156-2.344 0-.687.188-2.531 1.39-3.922C4-7.5 4.986-8.062 6.048-8.062c1.219 0 1.719.796 1.719 2.187 0 .469-.032.484-.032.61 0 .109.329.25.375.25.157 0 .36-.157.407-.376zm0 0"/>
+        </symbol>
+    </defs>
+    <g overflow="visible" x="-.475" y="30.513">
+        <path d="M9.281-8.438c0-.03-.219-.25-.328-.25a.701.701 0 00-.328.172l-.672.75c0 .016-.672-.921-2-.921-2.672 0-5.562 2.765-5.562 5.546C.39-1.17 2.016.266 3.844.266c1.031 0 2.078-.516 2.703-1.063C7.657-1.78 7.922-2.969 7.922-3c0-.125-.203-.031-.203-.031l-.125-.219c-.078 0-.344.156-.36.25-.109.344-.328 1.094-1.156 1.797-.812.672-1.422.828-2.047.828-1.078 0-2.156-.484-2.156-2.344 0-.687.188-2.531 1.39-3.922C4-7.5 4.986-8.062 6.048-8.062c1.219 0 1.719.796 1.719 2.187 0 .469-.032.484-.032.61 0 .109.329.25.375.25.157 0 .36-.157.407-.376zm0 0"/>
+    </g>
+</svg>
+
+@@@
+
+{"symbolContainer":"g"}
diff --git a/test/plugins/dereferenceUses.07.svg.txt b/test/plugins/dereferenceUses.07.svg.txt
@@ -0,0 +1,29 @@
+Correctly overrides attributes of referenced elements adhering to spec, while keeping the href attributes.
+
+===
+
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 1 1" height="64" width="64">
+    <defs>
+        <symbol id="a" overflow="visible">
+            <path/>
+        </symbol>
+    </defs>
+    <use xlink:href="#a" style="fill:#000"/>
+</svg>
+
+@@@
+
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 1 1" height="64" width="64">
+    <defs>
+        <symbol id="a" overflow="visible">
+            <path/>
+        </symbol>
+    </defs>
+    <svg overflow="visible" xlink:href="#a" style="fill:#000">
+        <path/>
+    </svg>
+</svg>
+
+@@@
+
+{"keepHref":true}
diff --git a/test/plugins/dereferenceUses.08.svg.txt b/test/plugins/dereferenceUses.08.svg.txt
@@ -0,0 +1,13 @@
+Does not break when there are actually no <use/> elements at all.
+
+===
+
+<svg viewBox="0 0 30 10" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <circle id="myCircle" cx="5" cy="5" r="4" x="5" />
+</svg>
+
+@@@
+
+<svg viewBox="0 0 30 10" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <circle id="myCircle" cx="5" cy="5" r="4" x="5"/>
+</svg>