feat(ids): prefix all ids and references with a unique string [KHCP-13216]

package.json

@@ -59,7 +59,6 @@
     "@semantic-release/git": "^10.0.1",
     "@types/jsdom": "^21.1.7",
     "@types/node": "^20.15.0",
-    "@types/node-emoji": "^2.1.0",
     "@vitejs/plugin-vue": "^5.1.2",
     "@vitest/ui": "^2.0.5",
     "@vue/test-utils": "^2.4.6",

scripts/utilities/__snapshots__/generate-icon-components.spec.ts.snap

@@ -730,6 +730,7 @@ exports[`generate > does not remove icons from the previous build 1`] = `
   "InsomniaIcon.vue",
   "ItalicIcon.vue",
   "KeyboardReturnIcon.vue",
+  "KongGradientIcon.vue",
   "KongIcon.vue",
   "LanguageBashIcon.vue",
   "LanguageCIcon.vue",

src/__template__/ComponentTemplate.vue

@@ -1,6 +1,6 @@
 <script lang="ts" setup>
 /** {%%ICON_COMPONENT_FILE_HEADER%%} */
-import { computed } from 'vue'
+import { computed, ref, onMounted } from 'vue'
 import { KUI_ICON_SIZE_50 } from '@kong/design-tokens'
 
 const props = defineProps({
@@ -56,8 +56,19 @@ const props = defineProps({
     required: false,
     default: 'span',
   },
+  /**
+   * A boolean to enable prefixing any internal SVG ids with a unique string; useful when there are potentially multiple SVG instances on the same page and the SVG utilizes ids and references internally (e.g. in the `<defs>` tag).
+   * Typically only set to false during snapshot testing.
+   * Defaults to `true`.
+   */
+  randomizeIds: {
+    type: Boolean,
+    default: true,
+  },
 })
 
+const svgElement = ref<SVGElement | null>(null)
+
 const iconSize = computed((): string => {
   // If props.size is a number, ensure it's greater than zero
   if (typeof props.size === 'number' && props.size > 0) {
@@ -90,6 +101,70 @@ const rootElementStyles = computed((): Record<string, string> => ({
   lineHeight: '0',
   width: iconSize.value,
 }))
+
+/**
+ * Prefix all ids within the SVG element and update all corresponding references to these ids. This is useful to avoid id conflicts when utilizing multiple instances of the same SVG in the DOM.
+ *
+ * @param {SVGElement} svgElement - The SVG element whose potential IDs need to be prefixed.
+ */
+const prefixSvgIds = (svgElement: SVGElement): void => {
+  if (!svgElement) {
+    return
+  }
+
+  const defsElement = svgElement.querySelector('defs')
+
+  // Prepare a map to store the original and new IDs for quick lookups
+  const idMap: Record<string, string> = {}
+
+  if (defsElement) {
+    // Prefix all direct children of <defs> that have an `id`
+    defsElement.querySelectorAll('[id]').forEach((element) => {
+      const originalId = element.getAttribute('id')
+      const newId = `${Math.random().toString(36).substring(2, 12)}-${originalId}`
+
+      // Map old id to new id
+      idMap[originalId!] = newId
+
+      // Update the element's id with the new prefixed id
+      element.setAttribute('id', newId)
+    })
+  }
+
+  // Update all references to these prefixed ids in attributes like `url(#id)`, `href`, `xlink:href`
+  const referencingAttributes = ['fill', 'stroke', 'filter', 'mask', 'clip-path', 'xlink:href', 'href']
+
+  // Function to update references to ids in attributes
+  const updateReferences = (element: Element): void => {
+    referencingAttributes.forEach((attr) => {
+      const attrValue = element.getAttribute(attr)
+      if (attrValue) {
+        // Match any url(#id) or href="#id" references
+        const updatedValue = attrValue.replace(/url\(#([^)]+)\)/g, (match, id) => {
+          return idMap[id] ? `url(#${idMap[id]})` : match
+        }).replace(/#([^\s]+)/g, (match, id) => {
+          return idMap[id] ? `#${idMap[id]}` : match
+        })
+
+        // If the value changed, update the attribute
+        if (updatedValue !== attrValue) {
+          element.setAttribute(attr, updatedValue)
+        }
+      }
+    })
+  }
+
+  // Traverse all elements in the SVG to update id references
+  svgElement.querySelectorAll('*').forEach((element) => {
+    updateReferences(element)
+  })
+}
+
+onMounted(() => {
+  if (props.randomizeIds && svgElement.value) {
+    prefixSvgIds(svgElement.value)
+  }
+})
 </script>
 
 <template>
@@ -101,6 +176,7 @@ const rootElementStyles = computed((): Record<string, string> => ({
     :style="rootElementStyles"
   >
     <svg
+      ref="svgElement"
       :aria-hidden="decorative ? 'true' : undefined"
       data-testid="kui-icon-svg-{%%KONG_COMPONENT_ICON_CLASS%%}"
       fill="none"

src/tests/generated-component.spec.ts

@@ -7,6 +7,7 @@ import { KUI_COLOR_TEXT_PRIMARY } from '@kong/design-tokens'
 for (const [componentName, IconComponent] of Object.entries(importedComponents)) {
   describe(`${componentName}.vue`, () => {
     it('has proper default structure', () => {
+      // @ts-ignore: dynamic component
       const wrapper = mount(IconComponent)
 
       expect(wrapper.exists()).toBe(true)
@@ -22,8 +23,10 @@ for (const [componentName, IconComponent] of Object.entries(importedComponents))
     })
 
     it('matches snapshot', () => {
+      // @ts-ignore: dynamic component interface
       const wrapper = mount(IconComponent, {
         props: {
+          randomizeIds: false, // Prevents random IDs from being generated for consistent snapshot testing
           title: 'My custom title',
           color: KUI_COLOR_TEXT_PRIMARY,
           display: 'inline-flex',