@payfit/unity-illustrations 0.0.0-alpha.9 → 1.1.0

package/src/components/illustration/Illustration.tsx

@@ -0,0 +1,146 @@
+import { forwardRef } from 'react'
+
+import type { VariantProps } from '@payfit/unity-themes'
+import type { ImgHTMLAttributes } from 'react'
+
+import type { UnityIllustrationAsset } from '../../generated/illustrationAssets'
+
+import { uyTv } from '@payfit/unity-themes'
+
+export const illustratedPicture = uyTv({
+  base: 'uy:object-contain uy:aspect-auto',
+})
+
+export const illustratedIcon = uyTv({
+  base: 'uy:object-contain uy:aspect-square',
+  variants: {
+    size: {
+      sm: 'uy:size-7',
+      md: 'uy:size-9',
+      lg: 'uy:size-12',
+    },
+  },
+})
+
+interface IllustrationPropsCore
+  extends Omit<
+    ImgHTMLAttributes<HTMLImageElement>,
+    'src' | 'children' | 'alt'
+  > {
+  /**
+   * The illustration asset to render. Must be imported from @payfit/unity-illustrations
+   */
+  src: UnityIllustrationAsset
+}
+
+interface NonDecorativeIllustrationProps extends IllustrationPropsCore {
+  /** Whether this is decorative (hidden from screen readers) */
+  isDecorative?: false | undefined
+  /** Accessible name for the illustration - required when not decorative */
+  alt: string
+  /** Optional description for complex illustrations */
+  description?: string
+}
+
+interface DecorativeIllustrationProps extends IllustrationPropsCore {
+  /** Whether this is decorative (hidden from screen readers) */
+  isDecorative: true
+  /** Accessible name for the illustration - optional when decorative */
+  alt?: string
+}
+
+export type IllustrationPropsBase =
+  | NonDecorativeIllustrationProps
+  | DecorativeIllustrationProps
+
+export type IllustratedPictureProps = IllustrationPropsBase &
+  VariantProps<typeof illustratedPicture> & {
+    /**
+     * The illustration variant. It can be a regular picture or an illustrated icon
+     */
+    variant: 'picture'
+  }
+
+export type IllustratedIconProps = IllustrationPropsBase &
+  VariantProps<typeof illustratedIcon> & {
+    /**
+     * The illustration variant. It can be a regular picture or an illustrated icon
+     */
+    variant: 'icon'
+    /**
+     * The size of the illustration. It only applies to illustrated icons
+     */
+    size: VariantProps<typeof illustratedIcon>['size']
+  }
+
+export type IllustrationProps = IllustratedPictureProps | IllustratedIconProps
+
+/**
+ * Renders illustrations from the Unity design system with consistent styling and accessibility features.
+ *
+ * The Illustration component provides a standardized way to display SVG illustrations and images
+ * , ensuring consistent sizing, responsive behavior, and accessibility compliance.
+ * @param {IllustrationProps} props - Component props including variant, src, size, and standard HTML attributes
+ * @see {@link IllustrationProps} for all available props
+ * @example
+ * ```tsx
+ * import { Illustration } from '@payfit/unity-illustrations'
+ * import FAQ from '@payfit/unity-illustrations/FAQ'
+ *
+ * function Example() {
+ *   return (
+ *     <Illustration
+ *       variant="picture"
+ *       src={FAQ}
+ *       className="uy:size-[150px]"
+ *       alt="FAQ illustration"
+ *     />
+ *   )
+ * }
+ * ```
+ * @remarks
+ * You must import illustration assets individually from `@payfit/unity-illustrations/[AssetName]` to use with this component.
+ * See the [usage documentation](https://unity-illustrations.payfit.io/?path=/docs/introduction-usage--docs) for complete examples and best practices.
+ */
+export const Illustration = forwardRef<HTMLImageElement, IllustrationProps>(
+  (
+    {
+      src,
+      alt,
+      isDecorative: decorative = false,
+      variant,
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    const clsx =
+      variant === 'picture'
+        ? illustratedPicture({ className })
+        : illustratedIcon({
+            className,
+            size: (props as IllustratedIconProps).size,
+          })
+
+    const description = decorative
+      ? (props as NonDecorativeIllustrationProps).description
+      : undefined
+
+    return (
+      <img
+        ref={ref}
+        src={src.url}
+        alt={decorative ? '' : alt}
+        title={decorative ? undefined : alt}
+        className={clsx}
+        role={decorative ? 'presentation' : 'img'}
+        aria-hidden={decorative}
+        aria-description={description}
+        loading="lazy"
+        {...props}
+      />
+    )
+  },
+)
+
+Illustration.displayName = 'Illustration'

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

@@ -0,0 +1,149 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+
+import { LazyIllustration } from './LazyIllustration'
+
+/**
+ * The LazyIllustration component dynamically imports illustrations based on their name.
+ * It uses the lazyIllustrationsMap from the generated illustrationAssets file to load
+ * the corresponding illustration and pass it to the Illustration component.
+ */
+const meta = {
+  title: 'Components/LazyIllustration',
+  component: LazyIllustration,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    name: {
+      control: 'select',
+      options: [
+        'FAQ',
+        'Binoculars',
+        'WriteBook',
+        'VisuallyImpaired',
+        'Library',
+      ],
+      description:
+        'The name of the illustration to load dynamically. This must be one of the valid illustration names from the Unity illustration library',
+      table: {
+        type: { summary: 'UnityIllustrationName' },
+        category: 'Required',
+      },
+    },
+    variant: {
+      control: 'select',
+      options: ['picture', 'icon'],
+      description:
+        'The illustration variant. It can be a regular picture or an illustrated icon',
+      table: {
+        type: { summary: "'picture' | 'icon'" },
+        category: 'Required',
+      },
+    },
+    alt: {
+      control: 'text',
+      description:
+        'Accessible name for the illustration. Required when isDecorative is `true`',
+      table: {
+        type: { summary: 'string' },
+        category: 'Accessibility',
+      },
+    },
+    // @ts-expect-error - Typescript can't handle the union type properly, but the prop exist
+    description: {
+      control: 'text',
+      description:
+        'Optional description for complex illustrations. Active only when isDecorative is `true`',
+      table: {
+        type: { summary: 'string' },
+        category: 'Accessibility',
+      },
+    },
+    isDecorative: {
+      control: 'boolean',
+      description:
+        'Whether the illustration is decorative (hidden from screen readers). When `true`, `alt` becomes optional',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+        category: 'Accessibility',
+      },
+    },
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg'],
+      description: 'The size of the illustration. Only applies to icon variant',
+      if: { arg: 'variant', eq: 'icon' },
+      table: {
+        type: { summary: "'sm' | 'md' | 'lg'" },
+        category: 'Icon Variant',
+      },
+    },
+    className: {
+      control: 'text',
+      description: 'Additional CSS classes for styling',
+      table: {
+        type: { summary: 'string' },
+        category: 'Styling',
+      },
+    },
+  },
+} satisfies Meta<typeof LazyIllustration>
+
+export default meta
+
+type Story = StoryObj<typeof LazyIllustration>
+
+/**
+ * Basic usage of the LazyIllustration component with a picture variant.
+ * Simply provide the name of the illustration you want to load.
+ */
+export const Primary: Story = {
+  args: {
+    variant: 'picture',
+    name: 'Binoculars',
+    className: 'uy:size-[150px]',
+    alt: 'Binoculars Illustration',
+  },
+}
+
+/**
+ * You can create responsive illustrations that adapt to different screen sizes by using responsive
+ * Tailwind classes in the `className` prop. Set the `alt` prop to provide accessible descriptions
+ * for screen readers when using the picture variant.
+ */
+export const IllustratedPicture: Story = {
+  args: {
+    variant: 'picture',
+    name: 'VisuallyImpaired',
+    className: 'uy:size-[50vmin]',
+    alt: 'Visually impaired person illustration',
+  },
+}
+
+/**
+ * You can use the LazyIllustration component with the icon variant as well.
+ * Specify the size prop to control the dimensions of the icon.
+ */
+export const IconVariant: Story = {
+  args: {
+    variant: 'icon',
+    name: 'Binoculars',
+    size: 'md',
+    alt: 'Binoculars Illustration',
+  },
+}
+
+/**
+ * You can create responsive illustrations that adapt to different screen sizes
+ * by using responsive Tailwind classes in the className prop.
+ */
+export const Responsive: Story = {
+  args: {
+    variant: 'picture',
+    name: 'WriteBook',
+    className: 'uy:size-[50vmin]',
+    alt: 'Write Book Illustration',
+  },
+}

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

@@ -0,0 +1,125 @@
+import { forwardRef, useEffect, useState } from 'react'
+
+import type {
+  UnityIllustrationAsset,
+  UnityIllustrationName,
+} from '../../generated/illustrationAssets'
+import type {
+  IllustratedIconProps,
+  IllustratedPictureProps,
+} from '../illustration/Illustration'
+
+import { lazyIllustrationsMap } from '../../generated/illustrationAssets'
+import {
+  illustratedIcon,
+  illustratedPicture,
+  Illustration,
+} from '../illustration/Illustration'
+
+/**
+ * Props for the LazyIllustration component.
+ *
+ * This type is a union of two possible prop types:
+ * 1. Props for the picture variant (omitting 'src' and adding 'name')
+ * 2. Props for the icon variant (omitting 'src' and adding 'name')
+ * @property {UnityIllustrationName} name - The name of the illustration to load dynamically.
+ *   This must be one of the valid illustration names from the Unity illustration library.
+ * @property {'picture' | 'icon'} variant - The illustration variant. It can be a regular picture or an illustrated icon.
+ * @property {string} alt - Accessible name for the illustration (required when isDecorative is false or undefined).
+ * @property {string} [description] - Optional description for complex illustrations.
+ * @property {boolean} [isDecorative] - Whether this is decorative (hidden from screen readers).
+ * @property {'sm' | 'md' | 'lg'} [size] - The size of the illustration. Required when variant is 'icon'.
+ */
+export type LazyIllustrationProps =
+  | (Omit<IllustratedPictureProps, 'src'> & { name: UnityIllustrationName })
+  | (Omit<IllustratedIconProps, 'src'> & { name: UnityIllustrationName })
+
+/**
+ * A component that lazily loads illustrations by name and renders them using the Illustration component.
+ *
+ * The LazyIllustration component dynamically imports illustrations based on their name using the
+ * lazyIllustrationsMap from the generated illustrationAssets file. This allows for code-splitting
+ * and on-demand loading of illustrations, which can significantly improve initial load performance.
+ * @param {LazyIllustrationProps} props - Component props including name, variant, and standard HTML attributes
+ * @see {@link LazyIllustrationProps} for all available props
+ * @example
+ * ```tsx
+ * import { LazyIllustration } from '@payfit/unity-illustrations'
+ *
+ * function Example() {
+ *   return (
+ *     <LazyIllustration
+ *       variant="picture"
+ *       name="FAQ"
+ *       className="uy:size-[150px]"
+ *       alt="FAQ illustration"
+ *     />
+ *   )
+ * }
+ * ```
+ * @example
+ * ```tsx
+ * // Using with icon variant
+ * import { LazyIllustration } from '@payfit/unity-illustrations'
+ *
+ * function IconExample() {
+ *   return (
+ *     <LazyIllustration
+ *       variant="icon"
+ *       size="md"
+ *       name="Binoculars"
+ *       alt="Binoculars icon"
+ *     />
+ *   )
+ * }
+ * ```
+ * @remarks
+ * Unlike the Illustration component, you don't need to import illustration assets individually.
+ * Simply provide the name of the illustration you want to use, and LazyIllustration will handle
+ * the dynamic import for you. The component returns null during loading, so you may want to
+ * provide your own loading state or placeholder.
+ */
+export const LazyIllustration = forwardRef<
+  HTMLImageElement,
+  LazyIllustrationProps
+>(({ name, ...props }, ref) => {
+  const [illustration, setIllustration] =
+    useState<UnityIllustrationAsset | null>(null)
+  const [isLoading, setIsLoading] = useState(true)
+
+  useEffect(() => {
+    const loadIllustration = async () => {
+      try {
+        setIsLoading(true)
+        const importFn = lazyIllustrationsMap[name]
+
+        const module = await importFn()
+        setIllustration(module.default)
+      } catch (error) {
+        console.error(`Failed to load illustration "${name}":`, error)
+      } finally {
+        setIsLoading(false)
+      }
+    }
+
+    void loadIllustration()
+  }, [name])
+
+  if (isLoading || !illustration) {
+    const clsx =
+      props.variant === 'picture'
+        ? illustratedPicture({ className: props.className })
+        : illustratedIcon({
+            className: props.className,
+            size: (props as IllustratedIconProps).size,
+          })
+    return <div className={clsx} />
+  }
+
+  // Handle the discriminated union by using type assertion
+  // This is safe because LazyIllustrationProps inherits from IllustrationProps (excluding src and name)
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return <Illustration ref={ref} src={illustration} {...(props as any)} />
+})
+
+LazyIllustration.displayName = 'LazyIllustration'

package/src/docs/1-Introduction/1-Welcome.mdx

@@ -0,0 +1,111 @@
+import { Meta, Subtitle } from '@storybook/addon-docs/blocks'
+import { Card, CardWithCover, CardHeader, CardTitle, CardContent, CardActions, Link } from '../blocks/Cards'
+
+<Meta title="Introduction/1-Welcome" />
+
+<img src="/images/unity-illustrations-cover.jpg" alt="Unity illustrations cover" style={{ width: '100%', marginBottom: '2rem' }} />
+
+# Unity Illustrations
+
+<Subtitle>Unity Illustrations is the Illustration library for the Unity Design system. Illustrations are scalable graphics that can be used to represent concepts, objects, or actions, and create visual interest and appeal. They can be static or animated.</Subtitle>
+
+<section className="uy:grid uy:grid-cols-1 uy:gap-150 uy:sm:grid-cols-2">
+    <Card>
+        <CardHeader>
+            <CardTitle>Getting Started</CardTitle>
+        </CardHeader>
+        <CardContent>
+            <p className="sb-unstyled uy:m-0">Set up a new project with Unity Illustrations or add it to an existing project.</p>
+        </CardContent>
+        <CardActions>
+            <Link href="/?path=/docs/introduction-2-getting-started--docs">Get Started</Link>
+        </CardActions>
+    </Card>
+    <Card>
+        <CardHeader>
+            <CardTitle>Usage</CardTitle>
+        </CardHeader>
+        <CardContent>
+            <p className="sb-unstyled uy:m-0">Learn how to use the Illustrations in your project.</p>
+        </CardContent>
+        <CardActions>
+            <Link href="/?path=/docs/introduction-3-usage--docs">Learn to use</Link>
+        </CardActions>
+    </Card>
+</section>
+
+## Our approach
+
+### Performant
+
+Unity Illustrations are designed to be lightweight and tree-shakable, ensuring that you only bundle the illustrations you need.
+
+### Easy to use
+
+Unity Illustrations are easy to use and integrate into your project. You can use them in any React project.
+
+### Accessible
+
+Unity Illustrations are built with accessibility in mind and follow the best practices for creating accessible illustrations.
+
+## Related packages
+
+Unity Illustrations is part of the Unity Design System, and is particularly thought out to work with the Unity components library. Here are the main packages you might want to use in conjunction with Unity Illustrations:
+
+<section className="uy:grid uy:grid-cols-1 uy:gap-150 uy:sm:grid-cols-2">
+    <CardWithCover coverSrc="images/unity-themes-cover.png" coverAlt="Unity themes">
+        <CardHeader>
+            <CardTitle>Unity themes</CardTitle>
+        </CardHeader>
+        <CardContent>
+            <p className="sb-unstyled uy:m-0">
+                Unity themes provides the base implementation of the foundational principles of the Unity Design system as a TailwindCSS preset.
+            </p>
+        </CardContent>
+        <CardActions>
+            <Link href="https://unity-theme.payfit.io/" target="_blank" rel="noopener noreferrer">Visit Unity themes</Link>
+        </CardActions>
+    </CardWithCover>
+    <CardWithCover coverSrc="images/unity-components-cover.png" coverAlt="Unity components">
+        <CardHeader>
+            <CardTitle>Unity components</CardTitle>
+        </CardHeader>
+        <CardContent>
+            <p className="sb-unstyled uy:m-0">
+                Unity components is a library of React components that implement the Unity Design system.
+            </p>
+        </CardContent>
+        <CardActions>
+            <Link href="https://unity-components.payfit.io/" target="_blank" rel="noopener noreferrer">Visit Unity components</Link>
+        </CardActions>
+    </CardWithCover>
+</section>
+
+## Need help?
+
+If you have any questions or a request related to Unity Illustrations, feel free to reach out to the Frontend Framework team on Slack. If you need to know more about the foundations and guidelines of Unity, visit the design system's main documentation.
+
+<section className="uy:grid uy:grid-cols-1 uy:gap-150 uy:sm:grid-cols-2">
+    <Card>
+        <CardHeader>
+            <CardTitle>Contact the team</CardTitle>
+        </CardHeader>
+        <CardContent>
+            <p className="sb-unstyled uy:m-0">Send us any questions, help requests or bug reports to The Front-end Framework's team slack channel</p>
+        </CardContent>
+        <CardActions>
+            <Link href="https://payfit.slack.com/archives/C05UJ6A1FJT" target="_blank" rel="noopener noreferrer">#ask-frontend-framework</Link>
+        </CardActions>
+    </Card>
+    <Card>
+        <CardHeader>
+            <CardTitle>Payfit.design</CardTitle>
+        </CardHeader>
+        <CardContent>
+            <p className="sb-unstyled uy:m-0">Learn more about the design foundation and component usage guidelines of Unity</p>
+        </CardContent>
+        <CardActions>
+            <Link href="https://www.payfit.design/24f360409/p/35fcc1-payfit-design-system" target="_blank" rel="noopener noreferrer">Visit payfit.design</Link>
+        </CardActions>
+    </Card>
+</section>

package/src/docs/1-Introduction/2-Getting Started.mdx

@@ -0,0 +1,25 @@
+import {Meta} from "@storybook/addon-docs/blocks";
+
+<Meta title="Introduction/2-Getting Started" />
+
+# Getting Started
+
+## Installation
+
+Install the package in your project. We recommend you use this package alongside `@payfit/unity-themes`.
+
+```bash
+yarn add @payfit/unity-themes @payfit/unity-illustrations
+```
+
+Ensure that `react` and `react-dom` are also installed in your project:
+
+```bash
+yarn add react react-dom
+```
+
+You are now ready to use the illustrations in your application.
+
+## Browser Support
+
+This package supports all modern evergreen browsers. It does not support IE.

package/src/docs/1-Introduction/3-Usage.mdx

@@ -0,0 +1,73 @@
+import {Meta} from "@storybook/addon-docs/blocks";
+
+<Meta title="Introduction/3-Usage" />
+
+# Usage
+
+Unity illustrations has two main concepts:
+
+- Import the illustration asset you want to use from `@payfit/unity-illustrations` as a direct import
+- render any illustration asset with the `Illustration` component
+
+```tsx
+import { Illustration } from '@payfit/unity-illustrations'
+import DashboardIllustration from '@payfit/unity-illustrations/assets/Dashboard'
+
+function MyComponent() {
+  return <Illustration src={DashboardIllustration} alt="Dashboard illustration" variant="picture" />
+}
+```
+
+You can customize the illustration's size and other properties using the class names from `@payfit/unity-themes`.
+
+```tsx
+import { Illustration } from '@payfit/unity-illustrations'
+import DashboardIllustration from '@payfit/unity-illustrations/assets/Dashboard'
+
+function MyComponent() {
+  // square illustration with dimention --uy:spacing-600 (48px)
+  return <Illustration src={DashboardIllustration} alt="Dashboard illustration" variant="picture" className="uy:size-600" />
+}
+```
+
+## API
+
+### Individual imports
+
+The illustrations library exports all the illustrations as named imports, referencing the underlying SVG or Image asset internally. This allows you to use the illustrations in your project without bundling the entire library, and to have better discoverability and type-safety over the assets that you can use.
+
+```tsx
+import { Illustration } from '@payfit/unity-illustrations'
+import DashboardIllustration from '@payfit/unity-illustrations/assets/Dashboard'
+
+function MyComponent() {
+  return <Illustration src={DashboardIllustration} alt="Dashboard illustration" variant="picture" />
+}
+```
+
+
+### Dynamic imports
+
+You can also use dynamic imports to import illustrations on demand. This is useful if you want to import illustrations only when they are needed or under certain dynamic conditions. For this case, make sure to use the individual import syntax.
+
+```tsx
+import { LazyIllustration } from '@payfit/unity-illustrations'
+
+function MyComponent() {
+  return <LazyIllustration name="Dashboard" alt="Dashboard illustration" variant="picture" className="uy:size-600" />
+}
+```
+
+> **Note:** Avoid using variables in dynamic imports, like `const Dashboard = await import('@payfit/unity-illustrations/${illustrationName}')`, as it will not be able to be tree-shaken.
+
+## TypeScript Support
+
+This package includes TypeScript definitions, and a list of all the available illustration names is exported as a type.
+
+```tsx
+import { type UnityIllustrationName, illustrationNames } from '@payfit/unity-illustrations'
+
+const myIllustrations: UnityIllustrationName[] = ['Dashboard', 'FAQ', 'Library']
+
+console.log(illustrationNames) // ['Dashboard', 'DashboardOutlined', ...+309 illustrations more]
+```

package/src/docs/1-Introduction/4-Changelog.mdx

@@ -0,0 +1,6 @@
+import {Meta, Markdown} from "@storybook/addon-docs/blocks";
+import changelog from '../../../CHANGELOG.md?raw';
+
+<Meta title="Introduction/4-Changelog" />
+
+<Markdown>{changelog}</Markdown>

package/src/docs/2-Reference/1-Find my illustration.mdx

@@ -0,0 +1,12 @@
+import {Meta} from "@storybook/addon-docs/blocks";
+import IllustrationLibrary from "../blocks/IllustrationLibrary"
+
+<Meta title="Reference/Find my illustration" />
+
+# Find my illustration
+
+Unity Illustrations is made up of more than 200 SVG illustrations and animated images. Each illustration is referenced by its name in Pascal Case. You can look for the illustration you need in the table using the search field.
+
+Refer to the [Usage](/?path=/docs/introduction-3-usage--docs) section to learn how to use the names to render icons in your application.
+
+<IllustrationLibrary />