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

package/src/components/illustration/Illustration.tsx

@@ -0,0 +1,128 @@
+import { forwardRef } from 'react'
+
+import type { ImgHTMLAttributes } from 'react'
+import type { VariantProps } from 'tailwind-variants'
+
+import type { UnityIllustrationAsset } from '../../generated/illustrationAssets'
+
+import { tv } from 'tailwind-variants'
+
+export const illustratedPicture = tv({
+  base: 'uy:object-contain uy:aspect-auto',
+})
+
+export const illustratedIcon = tv({
+  base: 'uy:object-contain uy:aspect-square',
+  variants: {
+    size: {
+      sm: 'uy:size-7',
+      md: 'uy:size-9',
+      lg: 'uy:size-12',
+    },
+  },
+})
+
+export interface IllustrationPropsBase
+  extends Omit<ImgHTMLAttributes<HTMLImageElement>, 'src' | 'children'> {
+  /**
+   * The illustration asset to render. Must be imported from @payfit/unity-illustrations
+   */
+  src: UnityIllustrationAsset
+  /** Accessible name for the illustration */
+  alt: string
+  /** Optional description for complex illustrations */
+  description?: string
+  /** Whether this is decorative (hidden from screen readers) */
+  isDecorative?: boolean
+}
+
+export interface IllustratedPictureProps
+  extends IllustrationPropsBase,
+    VariantProps<typeof illustratedPicture> {
+  /**
+   * The illustration variant. It can be a regular picture or an illustrated icon
+   */
+  variant: 'picture'
+}
+
+export interface IllustratedIconProps
+  extends 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,
+      description,
+      isDecorative: decorative = false,
+      variant,
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    const clsx =
+      variant === 'picture'
+        ? illustratedPicture({ className })
+        : illustratedIcon({
+            className,
+            size: (props as IllustratedIconProps).size,
+          })
+
+    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,85 @@
+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',
+      ],
+    },
+  },
+} 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]',
+  },
+}
+
+/**
+ * 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,122 @@
+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.
+ * @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} />
+  }
+
+  return <Illustration ref={ref} src={illustration} {...props} />
+})
+
+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 />

package/src/docs/blocks/Cards.tsx

@@ -0,0 +1,74 @@
+import React from 'react'
+
+type CardProps = React.PropsWithChildren
+
+export const Card: React.FC<CardProps> = ({ children }) => {
+  return (
+    <article className="sb-unstyled uy:bg-surface-neutral uy:border uy:border-solid uy:border-border-neutral uy:shadow-raising uy:rounded-200 uy:p-300 uy:flex uy:flex-col uy:gap-150">
+      {children}
+    </article>
+  )
+}
+
+export const CardWithCover: React.FC<
+  CardProps & { coverSrc: string; coverAlt: string }
+> = ({ children, coverSrc, coverAlt }) => {
+  return (
+    <article className="sb-unstyled uy:bg-surface-neutral uy:border uy:border-solid uy:border-border-neutral uy:shadow-raising uy:rounded-200 uy:flex uy:flex-col uy:overflow-hidden uy:sm:flex-row">
+      <img
+        src={coverSrc}
+        alt={coverAlt}
+        className="sb-unstyled uy:w-full uy:h-[180px] uy:object-contain uy:bg-blue-l3 uy:sm:object-fill uy:sm:h-full uy:sm:max-w-[200px]"
+      />
+      <section className="uy:p-300 uy:space-y-100">{children}</section>
+    </article>
+  )
+}
+export const CardHeader: React.FC<React.PropsWithChildren> = ({ children }) => {
+  return <header>{children}</header>
+}
+
+export const CardTitle: React.FC<React.PropsWithChildren> = ({ children }) => {
+  return <h3 className="sb-unstyled uy:typography-h3 uy:m-0">{children}</h3>
+}
+
+export const CardContent: React.FC<React.PropsWithChildren> = ({
+  children,
+}) => {
+  return <section className="uy:typography-body">{children}</section>
+}
+
+export const CardActions: React.FC<React.PropsWithChildren> = ({
+  children,
+}) => {
+  return <footer className="uy:flex uy:flex-col uy:gap-100">{children}</footer>
+}
+
+export const Link: React.FC<React.ComponentProps<'a'>> = ({
+  children,
+  ...rest
+}) => {
+  return (
+    <a
+      className="uy:typography-action uy:block uy:text-content-primary uy:underline"
+      {...rest}
+    >
+      {children}
+    </a>
+  )
+}
+
+type CardGridProps = {
+  children: React.ReactNode
+  cols?: number
+}
+
+export const CardGrid: React.FC<CardGridProps> = ({ children, cols = 2 }) => {
+  return (
+    <div
+      className={`uy:grid uy:grid-cols-1 uy:gap-150 uy:md:grid-cols-${cols}`}
+    >
+      {children}
+    </div>
+  )
+}