add support for custom gradient fills

Author: jasonlundien

src/components/FontAwesomeIcon.js

@@ -153,6 +153,10 @@ export default defineComponent({
     widthAuto: {
       type: Boolean,
       default: false
+    },
+    gradientFill: {
+      type: Object,
+      default: null
     }
   },
 
@@ -188,7 +192,7 @@ export default defineComponent({
       { immediate: true }
     )
 
-    const vnode = computed(() => (renderedIcon.value ? convert(renderedIcon.value.abstract[0], {}, attrs) : null))
+    const vnode = computed(() => (renderedIcon.value ? convert(renderedIcon.value.abstract[0], {}, attrs, props.gradientFill) : null))
     return () => vnode.value
   }
 })

src/components/__tests__/FontAwesomeIcon.test.js

@@ -580,3 +580,87 @@ describe('using a family', () => {
     })
   }
 })
+
+describe('gradientFill prop', () => {
+  test('applies a linearGradient element and fill reference to svg', () => {
+    const wrapper = mountFromProps({
+      icon: faCoffee,
+      gradientFill: {
+        id: 'myLinearGradient',
+        type: 'linear',
+        x1: '0%',
+        y1: '0%',
+        x2: '100%',
+        y2: '0%',
+        stops: [
+          { offset: '0%', color: '#FF5F6D' },
+          { offset: '100%', color: '#FFC371' }
+        ]
+      }
+    })
+
+    expect(wrapper.element.getAttribute('fill')).toBe('url(#myLinearGradient)')
+    const gradient = wrapper.element.querySelector('linearGradient')
+    expect(gradient).toBeTruthy()
+    expect(gradient.getAttribute('id')).toBe('myLinearGradient')
+    expect(gradient.getAttribute('x1')).toBe('0%')
+    expect(gradient.getAttribute('x2')).toBe('100%')
+    const stops = gradient.querySelectorAll('stop')
+    expect(stops.length).toBe(2)
+    expect(stops[0].getAttribute('offset')).toBe('0%')
+    expect(stops[0].getAttribute('stop-color')).toBe('#FF5F6D')
+    expect(stops[1].getAttribute('offset')).toBe('100%')
+    expect(stops[1].getAttribute('stop-color')).toBe('#FFC371')
+  })
+
+  test('applies a radialGradient element and fill reference to svg', () => {
+    const wrapper = mountFromProps({
+      icon: faCoffee,
+      gradientFill: {
+        id: 'myRadialGradient',
+        type: 'radial',
+        r: '150%',
+        cx: '30%',
+        cy: '107%',
+        stops: [
+          { offset: '0', color: '#FDF497' },
+          { offset: '0.45', color: '#FD5949', opacity: 0.8 },
+          { offset: '0.9', color: '#285AEB' }
+        ]
+      }
+    })
+
+    expect(wrapper.element.getAttribute('fill')).toBe('url(#myRadialGradient)')
+    const gradient = wrapper.element.querySelector('radialGradient')
+    expect(gradient).toBeTruthy()
+    expect(gradient.getAttribute('id')).toBe('myRadialGradient')
+    const stops = gradient.querySelectorAll('stop')
+    expect(stops.length).toBe(3)
+    expect(stops[1].getAttribute('stop-opacity')).toBe('0.8')
+  })
+
+  test('strips fill from child path elements when gradientFill is provided', () => {
+    const wrapper = mountFromProps({
+      icon: faCoffee,
+      gradientFill: {
+        id: 'testGradient',
+        type: 'linear',
+        stops: [{ offset: '0%', color: 'red' }]
+      }
+    })
+
+    const paths = wrapper.element.querySelectorAll('path')
+    paths.forEach(path => {
+      expect(path.getAttribute('fill')).toBeNull()
+    })
+  })
+
+  test('does not render gradient elements when gradientFill is not provided', () => {
+    const wrapper = mountFromProps({ icon: faCoffee })
+
+    expect(wrapper.element.querySelector('linearGradient')).toBeNull()
+    expect(wrapper.element.querySelector('radialGradient')).toBeNull()
+    const fill = wrapper.element.getAttribute('fill')
+    expect(fill === null || !fill.includes('url(')).toBe(true)
+  })
+})

src/converter.js

@@ -39,22 +39,49 @@ function classToObject (classes) {
     )
 }
 
+/**
+ * Creates a Vue VNode for an SVG gradient stop element.
+ * @param {Object} stop The gradient stop definition.
+ * @param {string|number} stop.offset The offset of the stop.
+ * @param {string} stop.color The color of the stop.
+ * @param {number} [stop.opacity] The opacity of the stop.
+ * @param {number} index The index of the stop.
+ * @returns {VNode}
+ */
+function createGradientStop (stop, index) {
+  return h('stop', {
+    key: `${index}-${stop.offset}`,
+    offset: stop.offset,
+    'stop-color': stop.color,
+    ...(stop.opacity !== undefined && { 'stop-opacity': stop.opacity })
+  })
+}
+
 /**
  * Converts a FontAwesome abstract element of an icon into a Vue VNode.
  * @param {AbstractElement | String} abstractElement The element to convert.
  * @param {Object} props The user-defined props.
  * @param {Object} attrs The user-defined native HTML attributes.
+ * @param {Object} [gradientFill] Optional gradient fill config.
  * @returns {VNode}
  */
-export default function convert (abstractElement, props = {}, attrs = {}) {
+export default function convert (abstractElement, props = {}, attrs = {}, gradientFill = null) {
   // If the abstract element is a string, we'll just return a string render function
   if (typeof abstractElement === 'string') {
     return abstractElement
   }
 
   // Converting abstract element children into Vue VNodes
+  // If a gradientFill (or fill attr) is provided, strip fill from child path elements
+  // so the gradient/fill takes precedence over the icon's built-in fill
+  const hasFillOverride = gradientFill || ('fill' in attrs)
   const children = (abstractElement.children || [])
-    .map(child => convert(child))
+    .map(child => {
+      if (hasFillOverride && child.tag === 'path' && child.attributes && 'fill' in child.attributes) {
+        return convert({ ...child, attributes: { ...child.attributes, fill: undefined } })
+      }
+      return convert(child)
+    })
 
   // Converting abstract element attributes into valid Vue format
   const mixins = Object.keys(abstractElement.attributes || {})
@@ -85,6 +112,26 @@ export default function convert (abstractElement, props = {}, attrs = {}) {
   // Now, we'll return the VNode
   const { class: _aClass = {}, style: aStyle = {}, ...otherAttrs } = attrs
 
+  // If a gradientFill is provided, inject the gradient element and set fill to reference it
+  if (gradientFill) {
+    const { type: gradientType, stops = [], id, ...gradientProps } = gradientFill
+    const gradientTag = gradientType === 'linear' ? 'linearGradient' : 'radialGradient'
+    const gradientVNode = h(gradientTag, { ...gradientProps, id }, stops.map(createGradientStop))
+
+    return h(
+      abstractElement.tag,
+      {
+        ...props,
+        class: mixins.class,
+        style: { ...mixins.style, ...aStyle },
+        ...mixins.attrs,
+        ...otherAttrs,
+        fill: `url(#${id})`
+      },
+      [gradientVNode, ...children]
+    )
+  }
+
   return h(
     abstractElement.tag,
     {