Merge pull request #625 from FortAwesome/feat/support-custom-gradient-fills

feat(style): add support for custom gradient fills

Author: charles4221

.github/workflows/ci.yml

@@ -38,6 +38,8 @@ jobs:
   build-and-test:
     runs-on: ubuntu-latest
     needs: validate
+    # Ensure we only run the full test matrix for pull requests and pushes to the main branch to save resources being spent on in-progress work.
+    if: github.event_name == 'pull_request' || (github.event_name == 'push' && github.ref == 'refs/heads/main')
     strategy:
       matrix:
         free-solid-svg-icons: [7.x, 6.x]

.vscode/settings.json

@@ -24,6 +24,9 @@
   "[typescriptreact]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
   },
+  "[yaml]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
   // Extension Settings
   "eslint.enable": true,
   "eslint.format.enable": false, // formatting is handled by prettier

src/__tests__/converter.test.ts

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { SVGAttributes } from 'react'
 
 import type { AbstractElement } from '@fortawesome/fontawesome-svg-core'
 
@@ -79,6 +79,76 @@ describe('convert function performance', () => {
 
       expect(mockCreateElement).toHaveBeenCalledTimes(2)
     })
+
+    it('should handle custom fill prop precedence', () => {
+      const child = createMockElement('path', { fill: 'red', d: 'M0,0 L10,10' })
+      const parent = createMockElement('svg', {}, [child])
+
+      convert(mockCreateElement, parent, {
+        fill: 'blue',
+      } as SVGAttributes<SVGSVGElement>)
+
+      expect(mockCreateElement).toHaveBeenNthCalledWith(
+        1,
+        'path',
+        expect.objectContaining({
+          fill: undefined, // Should be removed to allow prop to take precedence
+          d: 'M0,0 L10,10',
+        }),
+      )
+
+      expect(mockCreateElement).toHaveBeenNthCalledWith(
+        2,
+        'svg',
+        expect.objectContaining({
+          fill: 'blue', // Should be applied to parent
+        }),
+        expect.objectContaining({
+          props: {
+            children: [],
+            d: 'M0,0 L10,10',
+          },
+          type: 'path',
+        }),
+      )
+    })
+
+    it('should handle gradientFill prop precedence', () => {
+      const child = createMockElement('path', { fill: 'red', d: 'M0,0 L10,10' })
+      const parent = createMockElement('svg', {}, [child])
+
+      convert(mockCreateElement, parent, {
+        gradientFill: { id: 'gradient1' },
+      } as FontAwesomeIconProps)
+
+      expect(mockCreateElement).toHaveBeenNthCalledWith(
+        1,
+        'path',
+        expect.objectContaining({
+          fill: undefined, // Should be removed to allow gradient to take precedence
+          d: 'M0,0 L10,10',
+        }),
+      )
+
+      expect(mockCreateElement).toHaveBeenNthCalledWith(
+        2,
+        'radialGradient',
+        expect.objectContaining({
+          id: 'gradient1',
+        }),
+        expect.anything(), // Gradient stops would be here
+      )
+
+      expect(mockCreateElement).toHaveBeenNthCalledWith(
+        3,
+        'svg',
+        expect.objectContaining({
+          fill: `url(#gradient1)`, // Should be applied to parent
+        }),
+        expect.anything(),
+        expect.anything(),
+      )
+    })
   })
 
   describe('style parsing performance', () => {

src/converter.ts

@@ -1,3 +1,4 @@
+/* eslint-disable unicorn/no-array-callback-reference */
 import React, {
   HTMLAttributes,
   RefAttributes,
@@ -7,7 +8,9 @@ import React, {
 
 import type { AbstractElement } from '@fortawesome/fontawesome-svg-core'
 
+import type { FontAwesomeIconProps } from './types/icon-props'
 import { camelize } from './utils/camelize'
+import { createGradientStops } from './utils/gradients'
 
 function capitalize(val: string): string {
   return val.charAt(0).toUpperCase() + val.slice(1)
@@ -80,14 +83,34 @@ export function convert<
   element: Omit<AbstractElement, 'attributes'> & {
     attributes: AttributesOverride
   },
-  extraProps: Attr & RefAttributes<El> = {} as Attr & RefAttributes<El>,
+  extraProps: Attr &
+    RefAttributes<El> & {
+      gradientFill?: FontAwesomeIconProps['gradientFill']
+    } = {} as Attr & RefAttributes<El>,
 ): React.JSX.Element {
   if (typeof element === 'string') {
     return element
   }
 
   const children = (element.children || []).map((child) => {
-    return convert(createElement, child)
+    let element = child
+
+    if (
+      ('fill' in extraProps || extraProps.gradientFill) &&
+      child.tag === 'path' &&
+      'fill' in child.attributes
+    ) {
+      // If a `fill` prop or a gradient is provided, remove the `fill` attribute from child elements to allow the prop to take precedence
+      element = {
+        ...child,
+        attributes: {
+          ...child.attributes,
+          fill: undefined,
+        } as AttributesOverride,
+      }
+    }
+
+    return convert(createElement, element)
   })
 
   const elementAttributes: AttributesOverride = element.attributes || {}
@@ -120,6 +143,7 @@ export function convert<
     style: existingStyle,
     role: existingRole,
     'aria-label': ariaLabel,
+    gradientFill,
     ...remaining
   } = extraProps
 
@@ -139,6 +163,28 @@ export function convert<
     attrs['aria-hidden'] = 'false'
   }
 
+  // If a `gradientFill` prop is provided, set the fill attribute to reference the gradient and create the gradient element
+  if (gradientFill) {
+    attrs.fill = `url(#${gradientFill.id})`
+
+    const {
+      type: gradientType,
+      stops: gradientStops = [],
+      ...gradientProps
+    } = gradientFill
+
+    children.unshift(
+      createElement(
+        gradientType === 'linear' ? 'linearGradient' : 'radialGradient',
+        {
+          ...gradientProps,
+          id: gradientFill.id,
+        },
+        gradientStops.map(createGradientStops),
+      ),
+    )
+  }
+
   return createElement(element.tag, { ...attrs, ...remaining }, ...children)
 }
 

src/types/gradients.ts

@@ -0,0 +1,50 @@
+export type GradientStop = {
+  /** The offset of the gradient stop, specified as a percentage (e.g., '0%', '50%', '100%') or a number between 0 and 1 (e.g., 0, 0.5, 1). */
+  offset: string | number
+  /** The color of the gradient stop, specified as a valid CSS color string (e.g., '#FF0000', 'rgb(255, 0, 0)', 'red'). */
+  color: string
+  /** The opacity of the gradient stop, specified as a number between 0 and 1 (e.g., 0, 0.5, 1). This is optional and defaults to 1 if not provided. */
+  opacity?: number | undefined
+}
+
+export type LinearGradient = {
+  /**
+   * The `id` of the gradient, which is used to reference the gradient in the `fill` attribute of the icon's svg element.
+   * This must be a unique value to prevent conflicts with other elements on the page.
+   */
+  id: string
+  /** The x-coordinate of the start of the gradient. Can be a number or a string (e.g., '0%', '50%', '100%'). */
+  x1?: number | string | undefined
+  /** The x-coordinate of the end of the gradient. Can be a number or a string (e.g., '0%', '50%', '100%'). */
+  x2?: number | string | undefined
+  /** The y-coordinate of the start of the gradient. Can be a number or a string (e.g., '0%', '50%', '100%'). */
+  y1?: number | string | undefined
+  /** The y-coordinate of the end of the gradient. Can be a number or a string (e.g., '0%', '50%', '100%'). */
+  y2?: number | string | undefined
+  stops: GradientStop[]
+}
+
+export type RadialGradient = {
+  /**
+   * The `id` of the gradient, which is used to reference the gradient in the `fill` attribute of the icon's svg element.
+   * This must be a unique value to prevent conflicts with other elements on the page.
+   */
+  id: string
+  /** The x-coordinate of the center of the gradient. Can be a number or a string (e.g., '0%', '50%', '100%'). */
+  cx?: number | string | undefined
+  /** The y-coordinate of the center of the gradient. Can be a number or a string (e.g., '0%', '50%', '100%'). */
+  cy?: number | string | undefined
+  /** The radius of the gradient. Can be a number or a string (e.g., '0%', '50%', '100%'). */
+  r?: number | string | undefined
+  /** The x-coordinate of the focal point of the gradient. Can be a number or a string (e.g., '0%', '50%', '100%'). */
+  fx?: number | string | undefined
+  /** The y-coordinate of the focal point of the gradient. Can be a number or a string (e.g., '0%', '50%', '100%'). */
+  fy?: number | string | undefined
+  stops: GradientStop[]
+}
+
+export type Gradient<T extends 'linear' | 'radial'> = T extends 'linear'
+  ? { type: 'linear' } & LinearGradient
+  : T extends 'radial'
+    ? { type: 'radial' } & RadialGradient
+    : never

src/types/icon-props.ts

@@ -4,6 +4,7 @@ import type { IconProp, SizeProp } from '@fortawesome/fontawesome-svg-core'
 
 import type { AnimationProps } from './animation-props'
 import { CSSVariables } from './css-variables'
+import { Gradient } from './gradients'
 import type { TransformProps } from './transform-props'
 
 export interface FontAwesomeIconProps
@@ -30,6 +31,57 @@ export interface FontAwesomeIconProps
   className?: string | undefined
   /** The color of the icon. Can be any valid CSS color value */
   color?: string | undefined
+  /**
+   * Creates a `<linearGradient />` or `<radialGradient />` element inside the icon svg, and applies it as a fill to the icon.
+   *
+   * If you also provide a `fill` prop, the `fill` prop will take precedence over the gradient.
+   * Omit the `fill` prop to allow the gradient to be applied correctly.
+   *
+   * @example
+   * Linear Gradient Example:
+   * ```tsx
+   * <FontAwesomeIcon
+   *   icon="coffee"
+   *   gradientFill={{
+   *     id: 'myGradient',
+   *     type: 'linear',
+   *     x1: '0%',
+   *     y1: '0%',
+   *     x2: '100%',
+   *     y2: '0%',
+   *     stops: [
+   *       { offset: '0%', color: '#FF5F6D' },
+   *       { offset: '100%', color: '#FFC371' },
+   *     ],
+   *   }}
+   * />
+   * ```
+   *
+   * @example
+   * Radial Gradient Example:
+   * ```tsx
+   * <FontAwesomeIcon
+   *   icon="coffee"
+   *   gradientFill={{
+   *     id: 'myGradient',
+   *     type: 'radial',
+   *     r: '150%',
+   *     cx: '30%',
+   *     cy: '107%',
+   *     stops: [
+   *       { offset: '0', color: '#FDF497' },
+   *       { offset: '0.05', color: '#FDF497' },
+   *       { offset: '0.45', color: '#FD5949' },
+   *       { offset: '0.6', color: '#D6249F' },
+   *       { offset: '0.9', color: '#285AEB' },
+   *     ],
+   *   }}
+   * />
+   * ```
+   *
+   * NOTE: Only supports one gradient type, providing both linear and radial gradient props will have undesired side-effects.
+   */
+  gradientFill?: Gradient<'linear'> | Gradient<'radial'> | undefined
   /**
    * Applies a border to the icon
    * @see {@link https://docs.fontawesome.com/web/use-with/react/style#bordered-icons}