@payfit/unity-illustrations 1.1.0 → 1.2.0

package/dist/esm/generated/types.d.ts

@@ -12,7 +12,15 @@ export interface BaseImageAsset {
     readonly url: string;
     readonly animated: boolean;
 }
-export type IllustrationAsset<T extends (BaseSvgAsset | BaseImageAsset) & {
+export interface BaseAnimatedImageAsset extends BaseImageAsset {
+    readonly animated: true;
+    readonly dimensions: {
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly category: 'animation';
+}
+export type IllustrationAsset<T extends (BaseSvgAsset | BaseImageAsset | BaseAnimatedImageAsset) & {
     readonly name: string;
 }> = T & IllustrationAssetBrand;
 export {};

package/dist/esm/scripts/templates/assetTemplate.d.ts

@@ -4,4 +4,9 @@
 export declare function generateAssetModule(componentName: string, optimizedAssetPath: string, assetType: {
     type: 'svg' | 'image';
     animated: boolean;
+    category?: string;
+    dimensions?: {
+        width: number;
+        height: number;
+    };
 }, originalFileName: string): string;

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@payfit/unity-illustrations",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "module": "./dist/esm/index.js",
   "type": "module",
   "sideEffects": false,
+  "storybook": {
+    "url": "https://unity-illustrations.payfit.io/"
+  },
   "exports": {
     ".": {
       "import": {
@@ -26,31 +29,33 @@
     "src"
   ],
   "dependencies": {
+    "image-size": "1.0.2",
     "svgo": "3.3.2"
   },
   "devDependencies": {
     "@payfit/code-pushup-tools": "0.0.0-use.local",
     "@payfit/hr-app-eslint": "0.0.0-use.local",
     "@payfit/hr-apps-tsconfigs": "0.0.0-use.local",
-    "@payfit/unity-themes": "1.1.0",
+    "@payfit/unity-themes": "1.2.0",
     "@payfit/vite-configs": "0.0.0-use.local",
-    "@storybook/addon-a11y": "9.1.5",
-    "@storybook/addon-docs": "9.1.5",
-    "@storybook/addon-links": "9.1.5",
-    "@storybook/react-vite": "9.1.5",
+    "@storybook/addon-a11y": "9.1.7",
+    "@storybook/addon-docs": "9.1.7",
+    "@storybook/addon-links": "9.1.7",
+    "@storybook/react-vite": "9.1.7",
     "@storybook/test-runner": "0.23.0",
     "@types/react": "18.3.18",
     "@types/react-dom": "18.3.5",
+    "image-size": "1.0.2",
     "react": "18.3.1",
     "react-dom": "18.3.1",
-    "storybook": "9.1.5",
+    "storybook": "9.1.7",
     "svgo": "3.3.2",
     "tailwindcss": "4.1.11",
     "tsx": "4.17.0",
-    "vite": "6.3.5"
+    "vite": "7.1.6"
   },
   "peerDependencies": {
-    "@payfit/unity-themes": "1.1.0",
+    "@payfit/unity-themes": "1.2.0",
     "react": "18.3.1",
     "react-dom": "18.3.1"
   }

package/src/components/illustration/Illustration.stories.tsx

@@ -1,6 +1,10 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 
+// Animated illustrations - import directly from individual files
+import AccountingAnimation from '../../generated/AccountingAnimation'
 import Binoculars from '../../generated/Binoculars'
+import BinocularsAnimation from '../../generated/BinocularsAnimation'
+import CardAnimation from '../../generated/CardAnimation'
 import FAQ from '../../generated/FAQ'
 import FAQWithBackground from '../../generated/FAQWithBackground'
 import VisuallyImpaired from '../../generated/VisuallyImpaired'
@@ -259,3 +263,65 @@ export const Responsive: Story = {
     )
   },
 }
+
+/**
+ * Unity illustrations supports animated illustrations in WEBP format. All the animated illustrations have the `Animation` suffix on their name
+ * Animated illustrations will grow fluidly depending on its container size but are capped at their original dimensions to prevent oversizing.
+ */
+export const AnimatedIllustrations: Story = {
+  parameters: {
+    chromatic: { disableSnapshot: true },
+  },
+  render: () => {
+    return (
+      <div className="uy:space-y-300">
+        <div>
+          <h3 className="uy:typography-h3 uy:mb-200">
+            Large Animation (Fluid)
+          </h3>
+          <div className="uy:border uy:border-dashed uy:border-border-neutral uy:p-200 uy:rounded-100 uy:w-[50dvw]">
+            <Illustration
+              src={AccountingAnimation}
+              variant="picture"
+              alt="Accounting animation showing financial calculations"
+            />
+          </div>
+          <p className="uy:typography-caption uy:text-content-tertiary uy:mt-100">
+            Max dimensions: 969×852px • Scales down responsively
+          </p>
+        </div>
+
+        <div>
+          <h3 className="uy:typography-h3 uy:mb-200">
+            Medium Animation (Fluid)
+          </h3>
+          <div className="uy:border uy:border-dashed uy:border-border-neutral uy:p-200 uy:rounded-100 uy:w-[25dvw]">
+            <Illustration
+              src={BinocularsAnimation}
+              variant="picture"
+              alt="Binoculars animation for search or discovery"
+            />
+          </div>
+          <p className="uy:typography-caption uy:text-content-tertiary uy:mt-100">
+            Max dimensions: 750×750px • Scales down responsively
+          </p>
+        </div>
+        <div>
+          <h3 className="uy:typography-h3 uy:mb-200">
+            Small Animation (Fluid)
+          </h3>
+          <div className="uy:border uy:border-dashed uy:border-border-neutral uy:p-200 uy:rounded-100">
+            <Illustration
+              src={CardAnimation}
+              variant="picture"
+              alt="Card animation for payment or identification"
+            />
+          </div>
+          <p className="uy:typography-caption uy:text-content-tertiary uy:mt-100">
+            Max dimensions: 224×224px • Scales down responsively
+          </p>
+        </div>
+      </div>
+    )
+  },
+}

package/src/components/illustration/Illustration.tsx

@@ -1,4 +1,4 @@
-import { forwardRef } from 'react'
+import { forwardRef, useMemo } from 'react'
 
 import type { VariantProps } from '@payfit/unity-themes'
 import type { ImgHTMLAttributes } from 'react'
@@ -110,6 +110,7 @@ export const Illustration = forwardRef<HTMLImageElement, IllustrationProps>(
       isDecorative: decorative = false,
       variant,
       className,
+      style,
       ...props
     },
     ref,
@@ -126,13 +127,34 @@ export const Illustration = forwardRef<HTMLImageElement, IllustrationProps>(
       ? (props as NonDecorativeIllustrationProps).description
       : undefined
 
+    // Apply max dimensions for animated assets and generate CSS custom properties
+    const { enhancedStyle, enhancedClassName } = useMemo(() => {
+      if ('category' in src && 'dimensions' in src) {
+        const animationClasses =
+          'uy:max-w-[var(--uy-illustration-max-width)] uy:max-h-[var(--uy-illustration-max-height)] uy:w-full uy:h-auto'
+        return {
+          enhancedStyle: {
+            '--uy-illustration-max-width': `${src.dimensions.width}px`,
+            '--uy-illustration-max-height': `${src.dimensions.height}px`,
+            ...style,
+          },
+          enhancedClassName: `${clsx} ${animationClasses}`.trim(),
+        }
+      }
+      return {
+        enhancedStyle: style,
+        enhancedClassName: clsx,
+      }
+    }, [src, style, clsx])
+
     return (
       <img
         ref={ref}
         src={src.url}
         alt={decorative ? '' : alt}
         title={decorative ? undefined : alt}
-        className={clsx}
+        className={enhancedClassName}
+        style={enhancedStyle}
         role={decorative ? 'presentation' : 'img'}
         aria-hidden={decorative}
         aria-description={description}

package/src/components/lazy-illustration/LazyIllustration.stories.tsx

@@ -23,6 +23,9 @@ const meta = {
         'WriteBook',
         'VisuallyImpaired',
         'Library',
+        'AccountingAnimation',
+        'BinocularsAnimation',
+        'CardAnimation',
       ],
       description:
         'The name of the illustration to load dynamically. This must be one of the valid illustration names from the Unity illustration library',
@@ -147,3 +150,19 @@ export const Responsive: Story = {
     alt: 'Write Book Illustration',
   },
 }
+
+/**
+ * You can use animated illustrations with the LazyIllustration component. Animated illustrations
+ * have the `Animation` suffix and are automatically loaded with their fluid sizing behavior.
+ * The component detects animated assets and applies maximum dimension constraints to prevent oversizing.
+ */
+export const AnimatedIllustrations: Story = {
+  parameters: {
+    chromatic: { disableSnapshot: true },
+  },
+  args: {
+    variant: 'picture',
+    name: 'AccountingAnimation',
+    alt: 'Accounting animation showing financial calculations',
+  },
+}

package/src/docs/2-Reference/2-Find my animation.mdx

@@ -0,0 +1,14 @@
+import {Meta} from "@storybook/addon-docs/blocks";
+import AnimationLibrary from "../blocks/AnimationLibrary"
+
+<Meta title="Reference/Find my animation" />
+
+# Find my animation
+
+Unity Illustrations includes a collection of animated illustrations in WEBP format. Each animated illustration has the `Animation` suffix in its name and follows the same usage patterns as static illustrations. You can browse and search for the animation you need in the gallery below.
+
+Animated illustrations are fluid and responsive, but capped at their original dimensions to prevent oversizing. They use CSS custom properties to maintain optimal aspect ratios across different screen sizes.
+
+Refer to the [Usage](/?path=/docs/introduction-3-usage--docs) section to learn how to use animation names to render them in your application.
+
+<AnimationLibrary />

package/src/docs/blocks/AnimationLibrary.tsx

@@ -0,0 +1,144 @@
+import React, { memo, useCallback, useMemo, useState } from 'react'
+
+import { LazyIllustration } from '../../components/lazy-illustration/LazyIllustration'
+import { illustrationNames } from '../../generated/illustrationAssets'
+
+const debounce = <P = unknown,>(
+  callback: (...args: P[]) => unknown,
+  wait: number,
+) => {
+  let timeoutId: number
+  return (...args: P[]) => {
+    if (timeoutId) {
+      window.clearTimeout(timeoutId)
+    }
+    timeoutId = window.setTimeout(() => {
+      callback(...args)
+    }, wait)
+  }
+}
+
+const AnimationItem = memo(
+  ({
+    children,
+    name,
+    copyText,
+    onClick,
+  }: React.PropsWithChildren<{
+    name: string
+    copyText: string
+    onClick: () => void
+  }>) => {
+    return (
+      <li>
+        <button
+          onClick={onClick}
+          className="uy:group uy:flex uy:flex-col uy:w-full uy:items-center uy:gap-125 uy:p-200 uy:transition-all uy:rounded-100 uy:bg-surface-neutral uy:hover:bg-surface-neutral-low-hover uy:shadow-raising uy:hover:shadow-floating uy:focus-visible:shadow-floating uy:focus-visible:outline-none uy:focus-visible:ring-2 uy:focus-visible:ring-ring uy:focus-visible:ring-offset-2 uy:focus-visible:ring-utility-focus-ring uy:focus-visible:border-border-form-hover uy:focus-visible:bg-surface-neutral-low-hover uy:border uy:border-solid uy:border-border-neutral"
+        >
+          <figure className="uy:flex uy:flex-col uy:items-center uy:w-full">
+            <div
+              className="uy:flex uy:justify-center uy:items-center uy:w-full uy:transition-all uy:group-hover:scale-105"
+              style={{ maxWidth: '200px' }}
+            >
+              {children}
+            </div>
+            <figcaption className="uy:flex uy:flex-col uy:items-center">
+              <span className="uy:typography-body-strong uy:text-content-neutral uy:cursor-pointer uy:truncate uy:w-full uy:block">
+                {name}
+              </span>
+              <span className="uy:typography-action-small uy:bg-transparent uy:text-content-primary">
+                {copyText}
+              </span>
+            </figcaption>
+          </figure>
+        </button>
+      </li>
+    )
+  },
+)
+
+const AnimationLibrary = () => {
+  const [query, setQuery] = useState<string>('')
+  const [copiedAnimation, setCopiedAnimation] = useState<string | null>(null)
+
+  // Filter only animation names (those ending with 'Animation')
+  const animationList = useMemo(() => {
+    return illustrationNames.filter(name => name.endsWith('Animation'))
+  }, [])
+
+  const copyToClipboard = useCallback((animationName: string) => {
+    const importStatement = `import ${animationName} from '@payfit/unity-illustrations/assets/${animationName}'`
+
+    navigator.clipboard
+      .writeText(importStatement)
+      .then(() => {
+        setCopiedAnimation(animationName)
+        setTimeout(() => {
+          setCopiedAnimation(null)
+        }, 5000)
+      })
+      .catch((error: unknown) => {
+        console.error('Failed to copy: ', error)
+      })
+  }, [])
+
+  const updateSearchQuery = debounce((animationName: string) => {
+    setQuery(animationName)
+  }, 150)
+
+  const animationListMatchingSearch = animationList.filter(animationName =>
+    animationName.toLowerCase().includes(query.toLowerCase()),
+  )
+
+  return (
+    <section className="uy:flex uy:flex-col uy:gap-300 uy:max-w-[80vmax] uy:mx-auto">
+      <header>
+        <h3>Animation Gallery</h3>
+        <p className="uy:m-0!">
+          Click on any animation to copy its import path to the clipboard. All animations are displayed with a maximum width of 600px to ensure optimal viewing.
+        </p>
+      </header>
+      <input
+        type="search"
+        placeholder="Search for an animation..."
+        className="uy:flex uy:h-500 uy:w-full uy:text-content-form-enabled uy:rounded-100 uy:border uy:border-solid uy:border-border-form-enabled uy:bg-background uy:px-150 uy:py-100 uy:typography-body uy:placeholder:text-content-neutral-lowest uy:hover:border-border-form-hover uy:focus-visible:outline-none uy:focus-visible:ring-2 uy:focus-visible:ring-ring uy:focus-visible:ring-offset-2 uy:focus-visible:ring-utility-focus-ring"
+        onChange={e => {
+          updateSearchQuery(e.target.value)
+        }}
+      />
+
+      {animationListMatchingSearch.length === 0 ? (
+        <div className="uy:text-center uy:py-800">
+          <p className="uy:typography-body uy:text-content-tertiary">
+            {query ? `No animations found matching "${query}"` : 'No animations available'}
+          </p>
+        </div>
+      ) : (
+        <ul className="sb-unstyled uy:list-none uy:grid uy:grid-cols-[repeat(auto-fill,minmax(200px,_1fr))] uy:gap-200">
+          {animationListMatchingSearch.map(name => {
+            return (
+              <AnimationItem
+                name={name}
+                copyText={
+                  copiedAnimation === name ? 'Copied!' : 'Click to Copy'
+                }
+                key={name}
+                onClick={() => {
+                  copyToClipboard(name)
+                }}
+              >
+                <LazyIllustration
+                  variant="picture"
+                  alt={`${name} animation`}
+                  name={name}
+                />
+              </AnimationItem>
+            )
+          })}
+        </ul>
+      )}
+    </section>
+  )
+}
+
+export default AnimationLibrary

package/src/docs/blocks/IllustrationLibrary.tsx

@@ -69,7 +69,9 @@ const IllustrationLibrary = ({
       filter !== undefined
         ? (name: string) => name.toLowerCase().includes(filter)
         : () => true
-    return illustrationNames.filter(name => predicate(name))
+    return illustrationNames
+      .filter(name => !name.endsWith('Animation'))
+      .filter(name => predicate(name))
   }, [filter])
 
   const copyToClipboard = useCallback((illustrationName: string) => {

package/src/generated/AccountingAnimation.ts

@@ -0,0 +1,33 @@
+// AUTO-GENERATED FILE. DO NOT EDIT.
+// Source: Type=Animation,Name=accounting.webp (Animated WEBP - 969x852)
+import assetUrl from './assets/AccountingAnimation.webp'
+import type { IllustrationAsset, BaseAnimatedImageAsset } from './types'
+
+export type AccountingAnimationAsset = IllustrationAsset<BaseAnimatedImageAsset & {
+  readonly name: 'AccountingAnimation'
+}>
+
+/**
+ * AccountingAnimation animated illustration asset (969x852)
+ * @example
+ * ```tsx
+ * import { Illustration } from '@payfit/unity-illustrations'
+ * import AccountingAnimation from '@payfit/unity-illustrations/AccountingAnimation'
+ *
+ * <Illustration
+ *   variant="picture"
+ *   src={AccountingAnimation}
+ *   alt="Accounting animation"
+ * />
+ * ```
+ */
+const AccountingAnimation: AccountingAnimationAsset = {
+  type: 'image',
+  url: assetUrl,
+  animated: true,
+  dimensions: { width: 969, height: 852 },
+  category: 'animation',
+  name: 'AccountingAnimation',
+} as AccountingAnimationAsset
+
+export default AccountingAnimation

package/src/generated/BinocularsAnimation.ts

@@ -0,0 +1,33 @@
+// AUTO-GENERATED FILE. DO NOT EDIT.
+// Source: Type=Animation,Name=binoculars.webp (Animated WEBP - 750x750)
+import assetUrl from './assets/BinocularsAnimation.webp'
+import type { IllustrationAsset, BaseAnimatedImageAsset } from './types'
+
+export type BinocularsAnimationAsset = IllustrationAsset<BaseAnimatedImageAsset & {
+  readonly name: 'BinocularsAnimation'
+}>
+
+/**
+ * BinocularsAnimation animated illustration asset (750x750)
+ * @example
+ * ```tsx
+ * import { Illustration } from '@payfit/unity-illustrations'
+ * import BinocularsAnimation from '@payfit/unity-illustrations/BinocularsAnimation'
+ *
+ * <Illustration
+ *   variant="picture"
+ *   src={BinocularsAnimation}
+ *   alt="Binoculars animation"
+ * />
+ * ```
+ */
+const BinocularsAnimation: BinocularsAnimationAsset = {
+  type: 'image',
+  url: assetUrl,
+  animated: true,
+  dimensions: { width: 750, height: 750 },
+  category: 'animation',
+  name: 'BinocularsAnimation',
+} as BinocularsAnimationAsset
+
+export default BinocularsAnimation

package/src/generated/BlankPayslip.ts

@@ -0,0 +1,31 @@
+// AUTO-GENERATED FILE. DO NOT EDIT.
+// Source: Size=large, Type=generic, Name=blank_payslip, With background=no.svg
+import svgUrl from './assets/BlankPayslip.svg'
+import type { IllustrationAsset, BaseSvgAsset } from './types'
+
+export type BlankPayslipAsset = IllustrationAsset<BaseSvgAsset & {
+  readonly name: 'BlankPayslip'
+}>
+
+/**
+ * BlankPayslip illustration asset
+ * @example
+ * ```tsx
+ * import { Illustration } from '@payfit/unity-illustrations'
+ * import BlankPayslip from '@payfit/unity-illustrations/BlankPayslip'
+ *
+ * <Illustration
+ *   illustration={BlankPayslip}
+ *   alt="BlankPayslip illustration"
+ *   size="md"
+ * />
+ * ```
+ */
+const BlankPayslip: BlankPayslipAsset = {
+  type: 'svg',
+  url: svgUrl,
+  animated: false,
+  name: 'BlankPayslip',
+} as BlankPayslipAsset
+
+export default BlankPayslip

package/src/generated/CardAnimation.ts

@@ -0,0 +1,33 @@
+// AUTO-GENERATED FILE. DO NOT EDIT.
+// Source: Type=Animation,Name=card.webp (Animated WEBP - 224x224)
+import assetUrl from './assets/CardAnimation.webp'
+import type { IllustrationAsset, BaseAnimatedImageAsset } from './types'
+
+export type CardAnimationAsset = IllustrationAsset<BaseAnimatedImageAsset & {
+  readonly name: 'CardAnimation'
+}>
+
+/**
+ * CardAnimation animated illustration asset (224x224)
+ * @example
+ * ```tsx
+ * import { Illustration } from '@payfit/unity-illustrations'
+ * import CardAnimation from '@payfit/unity-illustrations/CardAnimation'
+ *
+ * <Illustration
+ *   variant="picture"
+ *   src={CardAnimation}
+ *   alt="Card animation"
+ * />
+ * ```
+ */
+const CardAnimation: CardAnimationAsset = {
+  type: 'image',
+  url: assetUrl,
+  animated: true,
+  dimensions: { width: 224, height: 224 },
+  category: 'animation',
+  name: 'CardAnimation',
+} as CardAnimationAsset
+
+export default CardAnimation

package/src/generated/ClockAnimation.ts

@@ -0,0 +1,33 @@
+// AUTO-GENERATED FILE. DO NOT EDIT.
+// Source: Type=Animation,Name=clock.webp (Animated WEBP - 224x224)
+import assetUrl from './assets/ClockAnimation.webp'
+import type { IllustrationAsset, BaseAnimatedImageAsset } from './types'
+
+export type ClockAnimationAsset = IllustrationAsset<BaseAnimatedImageAsset & {
+  readonly name: 'ClockAnimation'
+}>
+
+/**
+ * ClockAnimation animated illustration asset (224x224)
+ * @example
+ * ```tsx
+ * import { Illustration } from '@payfit/unity-illustrations'
+ * import ClockAnimation from '@payfit/unity-illustrations/ClockAnimation'
+ *
+ * <Illustration
+ *   variant="picture"
+ *   src={ClockAnimation}
+ *   alt="Clock animation"
+ * />
+ * ```
+ */
+const ClockAnimation: ClockAnimationAsset = {
+  type: 'image',
+  url: assetUrl,
+  animated: true,
+  dimensions: { width: 224, height: 224 },
+  category: 'animation',
+  name: 'ClockAnimation',
+} as ClockAnimationAsset
+
+export default ClockAnimation

package/src/generated/ConfettisAnimation.ts

@@ -0,0 +1,33 @@
+// AUTO-GENERATED FILE. DO NOT EDIT.
+// Source: Type=Animation,Name=confettis.webp (Animated WEBP - 224x224)
+import assetUrl from './assets/ConfettisAnimation.webp'
+import type { IllustrationAsset, BaseAnimatedImageAsset } from './types'
+
+export type ConfettisAnimationAsset = IllustrationAsset<BaseAnimatedImageAsset & {
+  readonly name: 'ConfettisAnimation'
+}>
+
+/**
+ * ConfettisAnimation animated illustration asset (224x224)
+ * @example
+ * ```tsx
+ * import { Illustration } from '@payfit/unity-illustrations'
+ * import ConfettisAnimation from '@payfit/unity-illustrations/ConfettisAnimation'
+ *
+ * <Illustration
+ *   variant="picture"
+ *   src={ConfettisAnimation}
+ *   alt="Confettis animation"
+ * />
+ * ```
+ */
+const ConfettisAnimation: ConfettisAnimationAsset = {
+  type: 'image',
+  url: assetUrl,
+  animated: true,
+  dimensions: { width: 224, height: 224 },
+  category: 'animation',
+  name: 'ConfettisAnimation',
+} as ConfettisAnimationAsset
+
+export default ConfettisAnimation

package/src/generated/DocumentAnimation.ts

@@ -0,0 +1,33 @@
+// AUTO-GENERATED FILE. DO NOT EDIT.
+// Source: Type=Animation,Name=document.webp (Animated WEBP - 224x224)
+import assetUrl from './assets/DocumentAnimation.webp'
+import type { IllustrationAsset, BaseAnimatedImageAsset } from './types'
+
+export type DocumentAnimationAsset = IllustrationAsset<BaseAnimatedImageAsset & {
+  readonly name: 'DocumentAnimation'
+}>
+
+/**
+ * DocumentAnimation animated illustration asset (224x224)
+ * @example
+ * ```tsx
+ * import { Illustration } from '@payfit/unity-illustrations'
+ * import DocumentAnimation from '@payfit/unity-illustrations/DocumentAnimation'
+ *
+ * <Illustration
+ *   variant="picture"
+ *   src={DocumentAnimation}
+ *   alt="Document animation"
+ * />
+ * ```
+ */
+const DocumentAnimation: DocumentAnimationAsset = {
+  type: 'image',
+  url: assetUrl,
+  animated: true,
+  dimensions: { width: 224, height: 224 },
+  category: 'animation',
+  name: 'DocumentAnimation',
+} as DocumentAnimationAsset
+
+export default DocumentAnimation