@payfit/unity-illustrations 2.49.1 → 2.50.0

package/src/docs/2-Reference/3-Multi brand support.mdx

@@ -0,0 +1,146 @@
+import { Canvas, Meta } from '@storybook/addon-docs/blocks'
+import * as IllustrationStories from '../../components/illustration/Illustration.stories'
+import * as LazyIllustrationStories from '../../components/lazy-illustration/LazyIllustration.stories'
+
+<Meta title="Reference/Multi brand support" />
+
+# Multi brand support
+
+Unity illustrations can resolve different visual assets for the legacy and rebrand themes while keeping the same logical illustration name.
+
+The theme-aware behavior is available through both rendering APIs:
+
+- `Illustration`, when you import an asset directly from `@payfit/unity-illustrations/assets/{Name}`
+- `LazyIllustration`, when you render an asset by its generated `name`
+
+Both APIs ultimately render the same generated asset contract.
+
+## Generated asset contract
+
+Every generated asset keeps the original `url` field for backwards compatibility and can also expose a `urls` object keyed by Unity theme.
+
+```tsx
+const FAQ = {
+  type: 'svg',
+  url: legacySvgUrl,
+  urls: {
+    legacy: legacySvgUrl,
+    rebrand: rebrandSvgUrl,
+  },
+  animated: false,
+  name: 'FAQ',
+}
+```
+
+`url` remains the default source. `urls.legacy` and `urls.rebrand` are used by Unity illustration components when a `UnityThemeProvider` is active.
+
+## Runtime resolution
+
+`Illustration` reads the active theme from `UnityThemeProvider` and resolves the rendered source as:
+
+```tsx
+const resolvedUrl = asset.urls?.[theme] ?? asset.url
+```
+
+`LazyIllustration` first loads the asset by name from the generated lazy map, then delegates rendering to `Illustration`. This means `LazyIllustration` has the same brand-aware behavior after the asset has loaded.
+
+## Direct asset imports
+
+Use direct imports when you know the asset at build time and want the import to stay explicit.
+
+<Canvas of={IllustrationStories.ThemeVariants} meta={IllustrationStories} sourceState="shown" />
+
+```tsx
+import { UnityThemeProvider } from '@payfit/unity-themes'
+import { Illustration } from '@payfit/unity-illustrations'
+import FAQ from '@payfit/unity-illustrations/assets/FAQ'
+
+function Example() {
+  return (
+    <UnityThemeProvider theme="rebrand">
+      <Illustration src={FAQ} variant="icon" size="lg" alt="FAQ icon" />
+    </UnityThemeProvider>
+  )
+}
+```
+
+## Lazy illustrations
+
+Use `LazyIllustration` when the illustration name is selected dynamically or when the asset should be loaded on demand.
+
+<Canvas of={LazyIllustrationStories.ThemeVariants} meta={LazyIllustrationStories} sourceState="shown" />
+
+```tsx
+import { UnityThemeProvider } from '@payfit/unity-themes'
+import { LazyIllustration } from '@payfit/unity-illustrations'
+
+function Example() {
+  return (
+    <UnityThemeProvider theme="rebrand">
+      <LazyIllustration name="FAQ" variant="icon" size="lg" alt="FAQ icon" />
+    </UnityThemeProvider>
+  )
+}
+```
+
+## Brand support states
+
+The Reference catalogs show a brand-support badge for each illustration. Those badges describe the visual migration state, not only whether two generated URLs exist.
+
+### Dual brand
+
+An illustration is considered `Dual brand` when the legacy and rebrand sources are both available and their optimized asset contents are different.
+
+When the active theme is `legacy`, the legacy source is rendered. When the active theme is `rebrand`, the rebrand source is rendered.
+
+### Legacy only
+
+An illustration is considered `Legacy only` when there is no distinct rebrand visual yet.
+
+This includes two cases:
+
+- The generated asset only has a legacy/default source.
+- A rebrand source file exists, but its optimized contents are identical to the legacy SVG.
+
+In the second case, the runtime may still resolve `urls.rebrand` under the rebrand theme, but the rendered image is visually the same as the legacy asset. The catalog keeps this in `Legacy only` so it can be used as a migration checklist.
+
+### Rebrand only
+
+An illustration is considered `Rebrand only` when it exists only in the rebrand catalog.
+
+For compatibility, these assets populate every URL field with the rebrand source:
+
+```tsx
+const RebrandOnlyAsset = {
+  url: rebrandSvgUrl,
+  urls: {
+    legacy: rebrandSvgUrl,
+    rebrand: rebrandSvgUrl,
+  },
+}
+```
+
+This means the same rebrand image renders in both themes.
+
+## Catalog filters
+
+Use the brand-support filters in [Find my illustration](/?path=/docs/reference-find-my-illustration--docs) and [Find my animation](/?path=/docs/reference-find-my-animation--docs) to inspect migration progress:
+
+- `All` shows every generated asset in that catalog.
+- `Dual` shows assets that visibly switch between legacy and rebrand.
+- `Legacy only` shows assets that still render legacy visuals.
+- `Rebrand only` shows assets that only exist in the rebrand catalog.
+
+Animated WEBP assets keep the same generated image URL unless a future asset pipeline introduces theme-specific animated sources.
+
+## Figma automation
+
+The Figma sync no longer distinguishes between illustrated icons and illustrated pictures. Static exports are treated as illustrations and are written to `assets/rebrand/` with the exact Figma variant filename.
+
+The current source nodes are configured in `.figma-sync.json` under `download.illustrations.nodeIds`:
+
+```json
+["19134:5", "19134:8607", "19134:9880"]
+```
+
+`assets/legacy/` is the frozen fallback catalog. The sync does not create, update, or delete files there. Filename properties such as `Type`, `Name`, `With background`, and `Size` remain the source of truth for generating the public Unity illustration name.

package/src/docs/blocks/AnimationLibrary.tsx

@@ -1,7 +1,22 @@
 import React, { memo, useCallback, useMemo, useState } from 'react'
 
+import { UnityThemeProvider } from '@payfit/unity-themes'
+
 import { LazyIllustration } from '../../components/lazy-illustration/LazyIllustration'
+import type { UnityIllustrationName } from '../../generated/illustrationAssets'
+
 import { illustrationNames } from '../../generated/illustrationAssets'
+import type { BrandSupportFilter } from './BrandSupportFilter'
+
+import {
+  BrandSupportBadge,
+  useBrandSupportRecords,
+} from './BrandSupportBadge'
+import {
+  BrandSupportFilterControl,
+  matchesBrandSupportFilter,
+} from './BrandSupportFilter'
+import { useStorybookTheme } from './useStorybookTheme'
 
 const debounce = <P = unknown,>(
   callback: (...args: P[]) => unknown,
@@ -25,7 +40,7 @@ const AnimationItem = memo(
     copyText,
     onClick,
   }: React.PropsWithChildren<{
-    name: string
+    name: UnityIllustrationName
     copyText: string
     onClick: () => void
   }>) => {
@@ -33,23 +48,26 @@ const AnimationItem = memo(
       <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"
+          className="uy:group uy:flex uy:h-full uy:w-full uy:flex-col uy:gap-150 uy:p-200 uy:transition-all uy:rounded-lg uy:bg-surface-neutral uy:shadow-raising uy:hover:shadow-flying uy:focus-visible:shadow-flying 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">
+          <figure className="uy:flex uy:h-full uy:w-full uy:flex-col uy:items-center uy:gap-150">
+            <figcaption className="uy:w-full uy:text-left">
+              <span className="uy:block uy:w-full uy:truncate uy:font-mono uy:text-50 uy:leading-normal uy:text-content-neutral">
+                {name}
+              </span>
+            </figcaption>
             <div
-              className="uy:flex uy:justify-center uy:items-center uy:w-full uy:transition-all uy:group-hover:scale-105"
+              className="uy:flex uy:h-[160px] uy:w-full uy:items-center uy:justify-center 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">
+            <div className="uy:mt-auto uy:flex uy:w-full uy:items-center uy:justify-between uy:gap-100">
+              <BrandSupportBadge name={name} />
+              <span className="uy:typography-action-small uy:bg-transparent uy:theme-legacy:text-content-primary uy:theme-rebrand:text-content-neutral uy:theme-rebrand:underline uy:whitespace-nowrap">
                 {copyText}
               </span>
-            </figcaption>
+            </div>
           </figure>
         </button>
       </li>
@@ -58,13 +76,16 @@ const AnimationItem = memo(
 )
 
 const AnimationLibrary = () => {
+  const theme = useStorybookTheme()
   const [query, setQuery] = useState<string>('')
   const [copiedAnimation, setCopiedAnimation] = useState<string | null>(null)
+  const [brandFilter, setBrandFilter] = useState<BrandSupportFilter>('all')
 
   // Filter only animation names (those ending with 'Animation')
   const animationList = useMemo(() => {
     return illustrationNames.filter(name => name.endsWith('Animation'))
   }, [])
+  const brandSupportByName = useBrandSupportRecords(animationList)
 
   const copyToClipboard = useCallback((animationName: string) => {
     const importStatement = `import ${animationName} from '@payfit/unity-illustrations/assets/${animationName}'`
@@ -87,57 +108,73 @@ const AnimationLibrary = () => {
   }, 150)
 
   const animationListMatchingSearch = animationList.filter(animationName =>
-    animationName.toLowerCase().includes(query.toLowerCase()),
+    animationName.toLowerCase().includes(query.toLowerCase()) &&
+    matchesBrandSupportFilter(
+      brandSupportByName.get(animationName) ?? 'loading',
+      brandFilter,
+    ),
   )
 
   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'}
+    <UnityThemeProvider key={theme} theme={theme}>
+      <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>
+        <div className="uy:flex uy:flex-col uy:gap-150">
+          <BrandSupportFilterControl
+            name="animation-brand-support-filter"
+            value={brandFilter}
+            onChange={setBrandFilter}
+          />
+          <input
+            type="search"
+            aria-label="Search for an animation"
+            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)
+            }}
+          />
         </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`}
+
+        {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}
-                />
-              </AnimationItem>
-            )
-          })}
-        </ul>
-      )}
-    </section>
+                  copyText={
+                    copiedAnimation === name ? 'Copied!' : 'Click to Copy'
+                  }
+                  key={name}
+                  onClick={() => {
+                    copyToClipboard(name)
+                  }}
+                >
+                  <LazyIllustration
+                    variant="picture"
+                    alt={`${name} animation`}
+                    name={name}
+                  />
+                </AnimationItem>
+              )
+            })}
+          </ul>
+        )}
+      </section>
+    </UnityThemeProvider>
   )
 }
 

package/src/docs/blocks/BrandSupportBadge.tsx

@@ -0,0 +1,190 @@
+import { useSyncExternalStore } from 'react'
+
+import type {
+  UnityIllustrationAsset,
+  UnityIllustrationName,
+} from '../../generated/illustrationAssets'
+
+import { lazyIllustrationsMap } from '../../generated/illustrationAssets'
+
+export type BrandSupport = 'loading' | 'dual' | 'legacy-only' | 'rebrand-only'
+
+const brandSupportByName = new Map<UnityIllustrationName, BrandSupport>()
+const pendingNames = new Set<UnityIllustrationName>()
+const listenersByName = new Map<UnityIllustrationName, Set<() => void>>()
+const listeners = new Set<() => void>()
+let version = 0
+
+async function haveSameContent(firstUrl: string, secondUrl: string) {
+  if (typeof fetch === 'undefined') {
+    return false
+  }
+
+  const [firstResponse, secondResponse] = await Promise.all([
+    fetch(firstUrl),
+    fetch(secondUrl),
+  ])
+  const [firstBuffer, secondBuffer] = await Promise.all([
+    firstResponse.arrayBuffer(),
+    secondResponse.arrayBuffer(),
+  ])
+
+  if (firstBuffer.byteLength !== secondBuffer.byteLength) {
+    return false
+  }
+
+  const firstBytes = new Uint8Array(firstBuffer)
+  const secondBytes = new Uint8Array(secondBuffer)
+
+  return firstBytes.every((byte, index) => byte === secondBytes[index])
+}
+
+async function classifyBrandSupport(
+  asset: UnityIllustrationAsset,
+): Promise<BrandSupport> {
+  const legacyUrl = asset.urls?.legacy ?? asset.url
+  const rebrandUrl = asset.urls?.rebrand ?? asset.url
+
+  if (
+    legacyUrl !== rebrandUrl &&
+    !(await haveSameContent(legacyUrl, rebrandUrl))
+  ) {
+    return 'dual'
+  }
+
+  if (legacyUrl.includes('.rebrand.')) {
+    return 'rebrand-only'
+  }
+
+  return 'legacy-only'
+}
+
+function notify(name: UnityIllustrationName) {
+  version += 1
+  listenersByName.get(name)?.forEach(listener => {
+    listener()
+  })
+  listeners.forEach(listener => {
+    listener()
+  })
+}
+
+function loadBrandSupport(name: UnityIllustrationName) {
+  if (brandSupportByName.has(name) || pendingNames.has(name)) {
+    return
+  }
+
+  pendingNames.add(name)
+
+  void lazyIllustrationsMap[name]()
+    .then(async module => {
+      brandSupportByName.set(
+        name,
+        await classifyBrandSupport(module.default),
+      )
+    })
+    .catch(() => {
+      brandSupportByName.set(name, 'legacy-only')
+    })
+    .finally(() => {
+      pendingNames.delete(name)
+      notify(name)
+    })
+}
+
+function subscribeToBrandSupport(
+  name: UnityIllustrationName,
+  onStoreChange: () => void,
+) {
+  const listeners = listenersByName.get(name) ?? new Set<() => void>()
+  listeners.add(onStoreChange)
+  listenersByName.set(name, listeners)
+
+  loadBrandSupport(name)
+
+  return () => {
+    listeners.delete(onStoreChange)
+
+    if (listeners.size === 0) {
+      listenersByName.delete(name)
+    }
+  }
+}
+
+function getBrandSupportSnapshot(name: UnityIllustrationName): BrandSupport {
+  return brandSupportByName.get(name) ?? 'loading'
+}
+
+function useBrandSupport(name: UnityIllustrationName): BrandSupport {
+  return useSyncExternalStore(
+    onStoreChange => subscribeToBrandSupport(name, onStoreChange),
+    () => getBrandSupportSnapshot(name),
+    () => 'loading',
+  )
+}
+
+function subscribeToBrandSupportRecords(
+  names: readonly UnityIllustrationName[],
+  onStoreChange: () => void,
+) {
+  listeners.add(onStoreChange)
+  names.forEach(loadBrandSupport)
+
+  return () => {
+    listeners.delete(onStoreChange)
+  }
+}
+
+export function useBrandSupportRecords(
+  names: readonly UnityIllustrationName[],
+) {
+  useSyncExternalStore(
+    onStoreChange => subscribeToBrandSupportRecords(names, onStoreChange),
+    () => version,
+    () => version,
+  )
+
+  return new Map(
+    names.map(name => [name, getBrandSupportSnapshot(name)] as const),
+  )
+}
+
+const badgeContent: Record<
+  BrandSupport,
+  { label: string; className: string; title: string }
+> = {
+  loading: {
+    label: 'Checking brand',
+    className: 'uy:bg-surface-neutral-low uy:text-content-neutral',
+    title: 'Checking illustration brand support',
+  },
+  dual: {
+    label: 'Dual brand',
+    className: 'uy:bg-surface-success-low uy:text-content-success-high',
+    title: 'This illustration switches between legacy and rebrand assets',
+  },
+  'legacy-only': {
+    label: 'Legacy only',
+    className: 'uy:bg-surface-warning-low uy:text-content-warning-high',
+    title: 'This illustration uses the legacy asset for every theme',
+  },
+  'rebrand-only': {
+    label: 'Rebrand only',
+    className: 'uy:bg-surface-info-low uy:text-content-info-high',
+    title: 'This illustration uses the rebrand asset for every theme',
+  },
+}
+
+export function BrandSupportBadge({ name }: { name: UnityIllustrationName }) {
+  const brandSupport = useBrandSupport(name)
+  const { label, className, title } = badgeContent[brandSupport]
+
+  return (
+    <span
+      className={`uy:typography-action-small uy:inline-flex uy:h-300 uy:items-center uy:rounded-50 uy:px-100 ${className}`}
+      title={title}
+    >
+      {label}
+    </span>
+  )
+}

package/src/docs/blocks/BrandSupportFilter.tsx

@@ -0,0 +1,72 @@
+import type { BrandSupport } from './BrandSupportBadge'
+
+export type BrandSupportFilter = Exclude<BrandSupport, 'loading'> | 'all'
+
+const options: ReadonlyArray<{
+  label: string
+  value: BrandSupportFilter
+}> = [
+  { label: 'All', value: 'all' },
+  { label: 'Dual', value: 'dual' },
+  { label: 'Legacy only', value: 'legacy-only' },
+  { label: 'Rebrand only', value: 'rebrand-only' },
+]
+
+export function matchesBrandSupportFilter(
+  brandSupport: BrandSupport,
+  filter: BrandSupportFilter,
+) {
+  return filter === 'all' || brandSupport === filter
+}
+
+export function BrandSupportFilterControl({
+  name,
+  value,
+  onChange,
+}: {
+  name: string
+  value: BrandSupportFilter
+  onChange: (value: BrandSupportFilter) => void
+}) {
+  return (
+    <fieldset className="uy:m-0 uy:border-0 uy:p-0">
+      <legend className="uy:sr-only">Filter illustrations by brand support</legend>
+      <div className="uy:flex uy:w-fit uy:gap-50 uy:rounded-75 uy:bg-surface-neutral-low uy:px-50 uy:py-50">
+        {options.map(option => {
+          const isSelected = option.value === value
+
+          return (
+            <label
+              key={option.value}
+              className={`uy:group uy:flex uy:h-400 uy:cursor-pointer uy:items-center uy:gap-25 uy:rounded-50 uy:px-150 uy:py-50 ${
+                isSelected
+                  ? 'uy:bg-surface-neutral-enabled uy:shadow-raising'
+                  : 'uy:hover:bg-surface-neutral-hover'
+              }`}
+            >
+              <input
+                type="radio"
+                name={name}
+                value={option.value}
+                checked={isSelected}
+                onChange={() => {
+                  onChange(option.value)
+                }}
+                className="uy:sr-only"
+              />
+              <span
+                className={`uy:flex uy:items-center uy:gap-50 uy:typography-action ${
+                  isSelected
+                    ? 'uy:text-content-neutral'
+                    : 'uy:text-content-neutral-enabled uy:group-hover:text-content-neutral-hover'
+                }`}
+              >
+                {option.label}
+              </span>
+            </label>
+          )
+        })}
+      </div>
+    </fieldset>
+  )
+}