feat: add gradient support to Circles component and enhance type definitions (fixes #188)

Author: mhnpd

package-lock.json

@@ -52,11 +52,11 @@
     "jest": "^30.1.3",
     "jest-environment-jsdom": "^30.1.2",
     "parcel": "^2.15.4",
-    "tsup": "^8.3.0",
     "prettier": "3.6.2",
     "react": "19.1.1",
     "react-dom": "19.1.1",
     "ts-jest": "^29.4.4",
+    "tsup": "^8.3.0",
     "typescript": "^5.9.2"
   },
   "peerDependencies": {

package.json

@@ -2,56 +2,65 @@ import React, { FunctionComponent, ReactElement } from 'react'
 import { BaseProps, DEFAULT_COLOR, DEFAULT_WAI_ARIA_ATTRIBUTE } from '../type'
 import { SvgWrapper } from '../shared/svg-wrapper'
 import { SVG_NAMESPACE } from '../shared/constants'
+import { useGradient } from '../shared/gradient'
 
 interface CirclesProps extends BaseProps {}
 
 export const Circles: FunctionComponent<CirclesProps> = ({
   height = 80,
   width = 80,
   color = DEFAULT_COLOR,
+  colors,
+  gradientType,
+  gradientAngle,
   ariaLabel = 'circles-loading',
   wrapperStyle,
   wrapperClass,
   visible = true,
-}): ReactElement => (
-  <SvgWrapper
-    style={wrapperStyle}
-    $visible={visible}
-    className={wrapperClass}
-    aria-label={ariaLabel}
-    data-testid="circles-loading"
-    {...DEFAULT_WAI_ARIA_ATTRIBUTE}
-  >
-    <svg
-      width={width}
-      height={height}
-      viewBox="0 0 135 135"
-      xmlns={SVG_NAMESPACE}
-      fill={color}
-      data-testid="circles-svg"
+}): ReactElement => {
+  const { defs, url } = useGradient({ colors, gradientType, gradientAngle })
+  const fillValue = url || color
+  return (
+    <SvgWrapper
+      style={wrapperStyle}
+      $visible={visible}
+      className={wrapperClass}
+      aria-label={ariaLabel}
+      data-testid="circles-loading"
+      {...DEFAULT_WAI_ARIA_ATTRIBUTE}
     >
-      <title>circles-loading</title>
-      <desc>Animated representation of circles</desc>
-      <path d="M67.447 58c5.523 0 10-4.477 10-10s-4.477-10-10-10-10 4.477-10 10 4.477 10 10 10zm9.448 9.447c0 5.523 4.477 10 10 10 5.522 0 10-4.477 10-10s-4.478-10-10-10c-5.523 0-10 4.477-10 10zm-9.448 9.448c-5.523 0-10 4.477-10 10 0 5.522 4.477 10 10 10s10-4.478 10-10c0-5.523-4.477-10-10-10zM58 67.447c0-5.523-4.477-10-10-10s-10 4.477-10 10 4.477 10 10 10 10-4.477 10-10z">
-        <animateTransform
-          attributeName="transform"
-          type="rotate"
-          from="0 67 67"
-          to="-360 67 67"
-          dur="2.5s"
-          repeatCount="indefinite"
-        />
-      </path>
-      <path d="M28.19 40.31c6.627 0 12-5.374 12-12 0-6.628-5.373-12-12-12-6.628 0-12 5.372-12 12 0 6.626 5.372 12 12 12zm30.72-19.825c4.686 4.687 12.284 4.687 16.97 0 4.686-4.686 4.686-12.284 0-16.97-4.686-4.687-12.284-4.687-16.97 0-4.687 4.686-4.687 12.284 0 16.97zm35.74 7.705c0 6.627 5.37 12 12 12 6.626 0 12-5.373 12-12 0-6.628-5.374-12-12-12-6.63 0-12 5.372-12 12zm19.822 30.72c-4.686 4.686-4.686 12.284 0 16.97 4.687 4.686 12.285 4.686 16.97 0 4.687-4.686 4.687-12.284 0-16.97-4.685-4.687-12.283-4.687-16.97 0zm-7.704 35.74c-6.627 0-12 5.37-12 12 0 6.626 5.373 12 12 12s12-5.374 12-12c0-6.63-5.373-12-12-12zm-30.72 19.822c-4.686-4.686-12.284-4.686-16.97 0-4.686 4.687-4.686 12.285 0 16.97 4.686 4.687 12.284 4.687 16.97 0 4.687-4.685 4.687-12.283 0-16.97zm-35.74-7.704c0-6.627-5.372-12-12-12-6.626 0-12 5.373-12 12s5.374 12 12 12c6.628 0 12-5.373 12-12zm-19.823-30.72c4.687-4.686 4.687-12.284 0-16.97-4.686-4.686-12.284-4.686-16.97 0-4.687 4.686-4.687 12.284 0 16.97 4.686 4.687 12.284 4.687 16.97 0z">
-        <animateTransform
-          attributeName="transform"
-          type="rotate"
-          from="0 67 67"
-          to="360 67 67"
-          dur="8s"
-          repeatCount="indefinite"
-        />
-      </path>
-    </svg>
-  </SvgWrapper>
-)
+      <svg
+        width={width}
+        height={height}
+        viewBox="0 0 135 135"
+        xmlns={SVG_NAMESPACE}
+        fill={fillValue}
+        data-testid="circles-svg"
+      >
+        {defs && <defs>{defs}</defs>}
+        <title>circles-loading</title>
+        <desc>Animated representation of circles</desc>
+        <path d="M67.447 58c5.523 0 10-4.477 10-10s-4.477-10-10-10-10 4.477-10 10 4.477 10 10 10zm9.448 9.447c0 5.523 4.477 10 10 10 5.522 0 10-4.477 10-10s-4.478-10-10-10c-5.523 0-10 4.477-10 10zm-9.448 9.448c-5.523 0-10 4.477-10 10 0 5.522 4.477 10 10 10s10-4.478 10-10c0-5.523-4.477-10-10-10zM58 67.447c0-5.523-4.477-10-10-10s-10 4.477-10 10 4.477 10 10 10 10-4.477 10-10z">
+          <animateTransform
+            attributeName="transform"
+            type="rotate"
+            from="0 67 67"
+            to="-360 67 67"
+            dur="2.5s"
+            repeatCount="indefinite"
+          />
+        </path>
+        <path d="M28.19 40.31c6.627 0 12-5.374 12-12 0-6.628-5.373-12-12-12-6.628 0-12 5.372-12 12 0 6.626 5.372 12 12 12zm30.72-19.825c4.686 4.687 12.284 4.687 16.97 0 4.686-4.686 4.686-12.284 0-16.97-4.686-4.687-12.284-4.687-16.97 0-4.687 4.686-4.687 12.284 0 16.97zm35.74 7.705c0 6.627 5.37 12 12 12 6.626 0 12-5.373 12-12 0-6.628-5.374-12-12-12-6.63 0-12 5.372-12 12zm19.822 30.72c-4.686 4.686-4.686 12.284 0 16.97 4.687 4.686 12.285 4.686 16.97 0 4.687-4.686 4.687-12.284 0-16.97-4.685-4.687-12.283-4.687-16.97 0zm-7.704 35.74c-6.627 0-12 5.37-12 12 0 6.626 5.373 12 12 12s12-5.374 12-12c0-6.63-5.373-12-12-12zm-30.72 19.822c-4.686-4.686-12.284-4.686-16.97 0-4.686 4.687-4.686 12.285 0 16.97 4.686 4.687 12.284 4.687 16.97 0 4.687-4.685 4.687-12.283 0-16.97zm-35.74-7.704c0-6.627-5.372-12-12-12-6.626 0-12 5.373-12 12s5.374 12 12 12c6.628 0 12-5.373 12-12zm-19.823-30.72c4.687-4.686 4.687-12.284 0-16.97-4.686-4.686-12.284-4.686-16.97 0-4.687 4.686-4.687 12.284 0 16.97 4.686 4.687 12.284 4.687 16.97 0z">
+          <animateTransform
+            attributeName="transform"
+            type="rotate"
+            from="0 67 67"
+            to="360 67 67"
+            dur="8s"
+            repeatCount="indefinite"
+          />
+        </path>
+      </svg>
+    </SvgWrapper>
+  )
+}

src/loader/circles.tsx

@@ -0,0 +1,40 @@
+import React, { useMemo } from 'react'
+
+export interface GradientConfig {
+  colors?: string[]
+  gradientType?: 'linear' | 'radial'
+  gradientAngle?: number
+}
+
+export const useGradient = ({
+  colors,
+  gradientType = 'linear',
+  gradientAngle = 0,
+}: GradientConfig) => {
+  const isGradient = !!colors && colors.length > 1
+  // Lightweight id generator to avoid pulling ESM-only libs for test env
+  const gradientId = useMemo(() => (isGradient ? `rls-grad-${Math.random().toString(36).slice(2, 8)}` : undefined), [isGradient])
+
+  const defs = useMemo(() => {
+    if (!isGradient || !gradientId || !colors) return null
+    if (gradientType === 'radial') {
+      return (
+        <radialGradient id={gradientId} cx="50%" cy="50%" r="50%">
+          {colors.map((c, i) => (
+            <stop key={c + i} offset={`${(i / (colors.length - 1)) * 100}%`} stopColor={c} />
+          ))}
+        </radialGradient>
+      )
+    }
+    return (
+      <linearGradient id={gradientId} x1="0%" y1="0%" x2="100%" y2="0%" gradientTransform={`rotate(${gradientAngle})`}>
+        {colors.map((c, i) => (
+            <stop key={c + i} offset={`${(i / (colors.length - 1)) * 100}%`} stopColor={c} />
+          ))}
+      </linearGradient>
+    )
+  }, [colors, gradientAngle, gradientId, gradientType, isGradient])
+
+  const url = gradientId ? `url(#${gradientId})` : undefined
+  return { isGradient, gradientId, defs, url }
+}

src/shared/gradient.tsx

@@ -20,4 +20,14 @@ export interface PrimaryProps {
 
 export interface BaseProps extends PrimaryProps {
   color?: string
+  /**
+   * Provide multiple colors to render a gradient instead of a solid color.
+   * When 2 or more colors are supplied a gradient <defs> will be injected and
+   * the primary color reference (fill or stroke) becomes url(#gradientId).
+   */
+  colors?: string[]
+  /** Type of gradient (linear or radial). Defaults to linear. */
+  gradientType?: 'linear' | 'radial'
+  /** Angle (in degrees) applied via rotate() transform for linear gradients. */
+  gradientAngle?: number
 }