@chronogrove/ui 0.82.1 → 0.83.0

package/src/color-mode/head-inline-resolution.spec.js

@@ -0,0 +1,111 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import { CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME, THEME_UI_COLOR_MODE_STORAGE_KEY } from './constants.js'
+import { buildInitialThemeUiColorModeResolutionInlineFragment } from './head-inline.js'
+
+function expireCrossDomainColorModeCookie() {
+  document.cookie = `${CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME}=; Path=/; Max-Age=0`
+}
+
+/**
+ * Executes the same inline fragment used in no-flash / HTML background scripts to verify
+ * cookie-vs-localStorage precedence without a full browser.
+ */
+function runResolutionFragment({ cookie, localStorageMap, prefersDark, crossDomainColorMode = null }) {
+  expireCrossDomainColorModeCookie()
+  document.cookie = cookie || ''
+  window.localStorage.clear()
+  if (localStorageMap) {
+    for (const [k, v] of Object.entries(localStorageMap)) {
+      window.localStorage.setItem(k, v)
+    }
+  }
+  window.matchMedia = jest.fn(() => ({
+    matches: Boolean(prefersDark),
+    media: '(prefers-color-scheme: dark)',
+    addListener: jest.fn(),
+    removeListener: jest.fn(),
+    addEventListener: jest.fn(),
+    removeEventListener: jest.fn(),
+    dispatchEvent: jest.fn(),
+    onchange: null
+  }))
+
+  const fragment = buildInitialThemeUiColorModeResolutionInlineFragment(
+    THEME_UI_COLOR_MODE_STORAGE_KEY,
+    crossDomainColorMode
+  )
+
+  const getMode = new Function(`
+    ${fragment}
+    return mode;
+  `)
+  return getMode()
+}
+
+describe('buildInitialThemeUiColorModeResolutionInlineFragment', () => {
+  beforeEach(() => {
+    expireCrossDomainColorModeCookie()
+    window.localStorage.clear()
+  })
+
+  it('prefers cookie over localStorage when both differ', () => {
+    const mode = runResolutionFragment({
+      cookie: 'chronogrove-theme-ui-color-mode=default',
+      localStorageMap: { [THEME_UI_COLOR_MODE_STORAGE_KEY]: 'dark' },
+      prefersDark: true,
+      crossDomainColorMode: { registrableDomain: 'example.com' }
+    })
+    expect(mode).toBe('default')
+    expect(window.localStorage.getItem(THEME_UI_COLOR_MODE_STORAGE_KEY)).toBe('default')
+  })
+
+  it('ignores cookie when registrableDomain is invalid (falls back to local-only logic)', () => {
+    const mode = runResolutionFragment({
+      cookie: 'chronogrove-theme-ui-color-mode=default',
+      localStorageMap: { [THEME_UI_COLOR_MODE_STORAGE_KEY]: 'dark' },
+      prefersDark: true,
+      crossDomainColorMode: { registrableDomain: 'bad..tld' }
+    })
+    expect(mode).toBe('dark')
+  })
+
+  it('uses localStorage when cookie is absent', () => {
+    const mode = runResolutionFragment({
+      cookie: '',
+      localStorageMap: { [THEME_UI_COLOR_MODE_STORAGE_KEY]: 'dark' },
+      prefersDark: false
+    })
+    expect(mode).toBe('dark')
+  })
+
+  it('falls back to prefers-color-scheme when cookie and storage are empty', () => {
+    const dark = runResolutionFragment({ cookie: '', localStorageMap: null, prefersDark: true })
+    expect(dark).toBe('dark')
+    expect(window.localStorage.getItem(THEME_UI_COLOR_MODE_STORAGE_KEY)).toBe('dark')
+
+    window.localStorage.clear()
+    const light = runResolutionFragment({ cookie: '', localStorageMap: null, prefersDark: false })
+    expect(light).toBe('default')
+  })
+
+  it('normalizes light in localStorage to default', () => {
+    const mode = runResolutionFragment({
+      cookie: '',
+      localStorageMap: { [THEME_UI_COLOR_MODE_STORAGE_KEY]: 'light' },
+      prefersDark: false
+    })
+    expect(mode).toBe('default')
+  })
+
+  it('handles localStorage getItem throwing in legacy fragment', () => {
+    const spy = jest.spyOn(Storage.prototype, 'getItem').mockImplementation(() => {
+      throw new Error('blocked')
+    })
+    const mode = runResolutionFragment({ cookie: '', localStorageMap: null, prefersDark: false })
+    expect(mode).toBe('default')
+    spy.mockRestore()
+  })
+})

package/src/color-mode/head-inline.js

@@ -3,26 +3,104 @@ import {
   chronogroveThemeSurfaceColorsLight
 } from '../chronogrove-theme-surface-colors.js'
 
-import { THEME_UI_COLOR_MODE_STORAGE_KEY } from './constants.js'
+import { CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME, THEME_UI_COLOR_MODE_STORAGE_KEY } from './constants.js'
+import { validateRegistrableDomain } from './registrable-domain.js'
 
 function q(str) {
   return JSON.stringify(str)
 }
 
-export function buildThemeUiNoFlashInlineScript(storageKey = THEME_UI_COLOR_MODE_STORAGE_KEY) {
-  const key = q(storageKey)
-  return `
-    (function() {
-      try {
-        var mode = localStorage.getItem(${key});
+/**
+ * Inline JS that sets `mode` and syncs `localStorage`. When `crossDomainColorMode.registrableDomain`
+ * is set (validated), reads the shared cookie first so subdomains stay aligned.
+ *
+ * @param {string} [storageKey]
+ * @param {{ registrableDomain?: string, cookieName?: string } | null} [crossDomainColorMode]
+ */
+export function buildInitialThemeUiColorModeResolutionInlineFragment(
+  storageKey = THEME_UI_COLOR_MODE_STORAGE_KEY,
+  crossDomainColorMode = null
+) {
+  const cookieName = crossDomainColorMode?.cookieName ?? CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME
+  const domainOk =
+    crossDomainColorMode &&
+    typeof crossDomainColorMode.registrableDomain === 'string' &&
+    validateRegistrableDomain(crossDomainColorMode.registrableDomain)
+
+  if (!domainOk) {
+    const keyOnly = q(storageKey)
+    return `
+        var __cgKey = ${keyOnly};
+        var mode;
+        try {
+          mode = localStorage.getItem(__cgKey);
+        } catch (e) {
+          mode = null;
+        }
         if (!mode) {
           var prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
           mode = prefersDark ? 'dark' : 'default';
-          localStorage.setItem(${key}, mode);
         }
         if (mode === 'light') {
           mode = 'default';
         }
+        try { localStorage.setItem(__cgKey, mode); } catch (e2) {}
+  `.trim()
+  }
+
+  const key = q(storageKey)
+  const cname = q(cookieName)
+  return `
+        function __cgGetCookie(name) {
+          try {
+            var parts = ('; ' + document.cookie).split('; ' + name + '=');
+            if (parts.length < 2) return null;
+            var raw = parts.pop().split(';').shift() || '';
+            try { return decodeURIComponent(raw.trim()); } catch (e1) { return raw.trim(); }
+          } catch (e) { return null; }
+        }
+        function __cgNormMode(m) {
+          if (m === 'light') return 'default';
+          if (m === 'dark' || m === 'default') return m;
+          return null;
+        }
+        var __cgKey = ${key};
+        var __cgCookieMode = __cgNormMode(__cgGetCookie(${cname}));
+        var mode;
+        if (__cgCookieMode) {
+          mode = __cgCookieMode;
+          try { localStorage.setItem(__cgKey, mode); } catch (e) {}
+        } else {
+          try {
+            mode = localStorage.getItem(__cgKey);
+          } catch (e) {
+            mode = null;
+          }
+          if (!mode) {
+            var prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+            mode = prefersDark ? 'dark' : 'default';
+          }
+          if (mode === 'light') {
+            mode = 'default';
+          }
+          try { localStorage.setItem(__cgKey, mode); } catch (e2) {}
+        }
+        if (mode === 'light') {
+          mode = 'default';
+        }
+  `.trim()
+}
+
+/**
+ * @param {string | { storageKey?: string, crossDomainColorMode?: { registrableDomain?: string, cookieName?: string } | null }} [options]
+ */
+export function buildThemeUiNoFlashInlineScript(options) {
+  const { storageKey, crossDomainColorMode } = normalizeNoFlashInlineScriptOptions(options)
+  const fragment = buildInitialThemeUiColorModeResolutionInlineFragment(storageKey, crossDomainColorMode)
+  return `
+    (function() {
+      try {
+        ${fragment}
         var htmlElement = document.documentElement;
         var classesToRemove = [];
         for (var i = 0; i < htmlElement.classList.length; i++) {
@@ -41,23 +119,32 @@ export function buildThemeUiNoFlashInlineScript(storageKey = THEME_UI_COLOR_MODE
   `
 }
 
+function normalizeNoFlashInlineScriptOptions(options) {
+  if (options == null || typeof options === 'string') {
+    return {
+      storageKey: typeof options === 'string' ? options : THEME_UI_COLOR_MODE_STORAGE_KEY,
+      crossDomainColorMode: null
+    }
+  }
+  return {
+    storageKey: options.storageKey ?? THEME_UI_COLOR_MODE_STORAGE_KEY,
+    crossDomainColorMode: options.crossDomainColorMode ?? null
+  }
+}
+
 export function buildHtmlBackgroundInlineScript({
   storageKey = THEME_UI_COLOR_MODE_STORAGE_KEY,
   defaultBackgroundHex,
-  darkBackgroundHex
-}) {
-  const key = q(storageKey)
+  darkBackgroundHex,
+  crossDomainColorMode = null
+} = {}) {
+  const fragment = buildInitialThemeUiColorModeResolutionInlineFragment(storageKey, crossDomainColorMode)
   const lightBg = q(defaultBackgroundHex)
   const darkBg = q(darkBackgroundHex)
   return `
     (function() {
       try {
-        var mode = localStorage.getItem(${key});
-        if (!mode) {
-          var prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
-          mode = prefersDark ? 'dark' : 'default';
-          localStorage.setItem(${key}, mode);
-        }
+        ${fragment}
         var bgColor = mode === 'dark' ? ${darkBg} : ${lightBg};
         document.documentElement.style.backgroundColor = bgColor;
       } catch (e) {}

package/src/color-mode/head-inline.spec.js

@@ -1,16 +1,68 @@
 import {
   buildHtmlBackgroundInlineScript,
+  buildInitialThemeUiColorModeResolutionInlineFragment,
   buildThemeUiColorModeFallbackCss,
   buildThemeUiNoFlashInlineScript
 } from './head-inline.js'
 
 describe('head-inline scripts', () => {
-  it('buildThemeUiNoFlashInlineScript references storage and data attribute', () => {
+  it('buildInitialThemeUiColorModeResolutionInlineFragment() uses default args (local-only)', () => {
+    const fragment = buildInitialThemeUiColorModeResolutionInlineFragment()
+    expect(fragment).not.toContain('__cgGetCookie')
+  })
+
+  it('buildThemeUiNoFlashInlineScript uses localStorage-only resolution when cross-domain is off', () => {
     const s = buildThemeUiNoFlashInlineScript()
     expect(s).toContain('theme-ui-color-mode')
+    expect(s).toContain('localStorage.getItem')
+    expect(s).not.toContain('__cgGetCookie')
     expect(s).toContain('data-theme-ui-color-mode')
   })
 
+  it('embeds cookie merge when crossDomainColorMode.registrableDomain is set', () => {
+    const s = buildThemeUiNoFlashInlineScript({
+      crossDomainColorMode: { registrableDomain: 'example.com' }
+    })
+    expect(s).toContain('__cgGetCookie')
+    expect(s).toContain('chronogrove-theme-ui-color-mode')
+  })
+
+  it('respects optional cookieName when registrableDomain is set', () => {
+    const s = buildThemeUiNoFlashInlineScript({
+      crossDomainColorMode: { registrableDomain: 'example.com', cookieName: 'my-shared-mode' }
+    })
+    expect(s).toContain('__cgGetCookie')
+    expect(s).toContain('my-shared-mode')
+  })
+
+  it('treats crossDomainColorMode without registrableDomain as local-only', () => {
+    const s = buildThemeUiNoFlashInlineScript({
+      crossDomainColorMode: { cookieName: 'orphan-name' }
+    })
+    expect(s).not.toContain('__cgGetCookie')
+  })
+
+  it('omits cookie merge when registrableDomain is invalid', () => {
+    const s = buildThemeUiNoFlashInlineScript({
+      crossDomainColorMode: { registrableDomain: 'a..b' }
+    })
+    expect(s).not.toContain('__cgGetCookie')
+  })
+
+  it('accepts a custom storage key string (legacy signature)', () => {
+    const s = buildThemeUiNoFlashInlineScript('my-mode-key')
+    expect(s).toContain('my-mode-key')
+  })
+
+  it('accepts storageKey on the options object with cross-domain config', () => {
+    const s = buildThemeUiNoFlashInlineScript({
+      storageKey: 'custom-storage',
+      crossDomainColorMode: { registrableDomain: 'example.com' }
+    })
+    expect(s).toContain('custom-storage')
+    expect(s).toContain('__cgGetCookie')
+  })
+
   it('buildHtmlBackgroundInlineScript embeds background hexes', () => {
     const s = buildHtmlBackgroundInlineScript({
       defaultBackgroundHex: '#aaa',
@@ -20,6 +72,21 @@ describe('head-inline scripts', () => {
     expect(s).toContain('#bbb')
   })
 
+  it('passes crossDomainColorMode through to the resolution fragment', () => {
+    const s = buildHtmlBackgroundInlineScript({
+      defaultBackgroundHex: '#aaa',
+      darkBackgroundHex: '#bbb',
+      crossDomainColorMode: { registrableDomain: 'example.com' }
+    })
+    expect(s).toContain('__cgGetCookie')
+    expect(s).toContain('#aaa')
+  })
+
+  it('applies the default empty options object when buildHtmlBackgroundInlineScript is called with no args', () => {
+    const s = buildHtmlBackgroundInlineScript()
+    expect(s).toContain('document.documentElement.style.backgroundColor')
+  })
+
   it('buildThemeUiColorModeFallbackCss sets CSS vars', () => {
     const css = buildThemeUiColorModeFallbackCss({
       defaultBackgroundHex: '#fdf8f5',

package/src/color-mode/index.js

@@ -1,15 +1,30 @@
 export {
   THEME_UI_COLOR_MODE_STORAGE_KEY,
   RECONCILE_COLOR_MODE_EVENT,
-  CHRONOGROVE_COLOR_MODE_HEAD_PRIORITY_KEYS
+  CHRONOGROVE_COLOR_MODE_HEAD_PRIORITY_KEYS,
+  CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_NAME,
+  CHRONOGROVE_CROSS_DOMAIN_COLOR_MODE_COOKIE_MAX_AGE_SEC
 } from './constants.js'
+export {
+  getHostnameForChronogroveCrossDomainCookie,
+  shouldUseSecureChronogroveCrossDomainCookie,
+  parseChronogroveColorModeCookie,
+  getChronogroveCrossDomainColorModeFromCookie,
+  setChronogroveCrossDomainColorModeCookie
+} from './cross-domain-color-mode-cookie.js'
+export {
+  setChronogroveCrossDomainColorModeClientConfig,
+  getChronogroveCrossDomainColorModeClientConfig
+} from './cross-domain-color-mode-client-config.js'
+export { validateRegistrableDomain, isHostnameUnderRegistrableDomain } from './registrable-domain.js'
 export { normalizeThemeUiColorMode } from './normalize.js'
 export { resolveChronogroveSurfaceColors } from './resolve-theme-colors.js'
 export { chronogroveHeadTheme } from './chronogrove-head-theme.js'
 export {
   buildThemeUiNoFlashInlineScript,
   buildHtmlBackgroundInlineScript,
-  buildThemeUiColorModeFallbackCss
+  buildThemeUiColorModeFallbackCss,
+  buildInitialThemeUiColorModeResolutionInlineFragment
 } from './head-inline.js'
 export { resolveThemeUiColorMode, syncThemeUiColorMode, scheduleThemeUiColorModeSync } from './browser-sync.js'
 export { reconcileThemeUiColorModeOnNavigation } from './spa-navigation.js'

package/src/color-mode/registrable-domain.js

@@ -0,0 +1,30 @@
+/**
+ * Public suffix / site registrable domain used for `Domain=` on shared cookies (e.g. `example.com`,
+ * not `www.example.com`). Must be safe to embed in a Set-Cookie line.
+ */
+export function validateRegistrableDomain(registrableDomain) {
+  if (typeof registrableDomain !== 'string') {
+    return null
+  }
+  const t = registrableDomain.trim().toLowerCase()
+  if (!t || t.includes('..') || !/^[a-z0-9.-]+$/.test(t)) {
+    return null
+  }
+  return t
+}
+
+/**
+ * True when `hostname` is the apex or a subdomain of `registrableDomain` (e.g. `www.example.com`
+ * under `example.com`). Rejects lookalikes like `notexample.com`.
+ */
+export function isHostnameUnderRegistrableDomain(hostname, registrableDomain) {
+  const base = validateRegistrableDomain(registrableDomain)
+  if (!base) {
+    return false
+  }
+  if (!hostname || typeof hostname !== 'string') {
+    return false
+  }
+  const h = hostname.trim().toLowerCase()
+  return h === base || h.endsWith(`.${base}`)
+}

package/src/color-mode/registrable-domain.spec.js

@@ -0,0 +1,28 @@
+import { isHostnameUnderRegistrableDomain, validateRegistrableDomain } from './registrable-domain.js'
+
+describe('validateRegistrableDomain', () => {
+  it('normalizes and rejects unsafe values', () => {
+    expect(validateRegistrableDomain(' Example.COM ')).toBe('example.com')
+    expect(validateRegistrableDomain('')).toBe(null)
+    expect(validateRegistrableDomain('a..b')).toBe(null)
+    expect(validateRegistrableDomain('bad;path')).toBe(null)
+  })
+})
+
+describe('isHostnameUnderRegistrableDomain', () => {
+  it('matches apex and subdomains', () => {
+    expect(isHostnameUnderRegistrableDomain('www.example.com', 'example.com')).toBe(true)
+    expect(isHostnameUnderRegistrableDomain('example.com', 'example.com')).toBe(true)
+  })
+
+  it('rejects hosts outside the registrable domain', () => {
+    expect(isHostnameUnderRegistrableDomain('notexample.com', 'example.com')).toBe(false)
+    expect(isHostnameUnderRegistrableDomain('localhost', 'example.com')).toBe(false)
+  })
+
+  it('rejects invalid inputs', () => {
+    expect(isHostnameUnderRegistrableDomain('', 'example.com')).toBe(false)
+    expect(isHostnameUnderRegistrableDomain('www.example.com', '')).toBe(false)
+    expect(isHostnameUnderRegistrableDomain('www.example.com', 'bad..')).toBe(false)
+  })
+})

package/src/color-toggle.js

@@ -2,6 +2,8 @@ import React, { useEffect } from 'react'
 import { useColorMode } from 'theme-ui'
 import { Expand } from '@theme-toggles/react'
 import { scheduleThemeUiColorModeSync } from './color-mode/browser-sync.js'
+import { getChronogroveCrossDomainColorModeClientConfig } from './color-mode/cross-domain-color-mode-client-config.js'
+import { setChronogroveCrossDomainColorModeCookie } from './color-mode/cross-domain-color-mode-cookie.js'
 import isDarkMode from './helpers/isDarkMode.js'
 
 export default function ColorToggle() {
@@ -13,6 +15,7 @@ export default function ColorToggle() {
   // attribute makes toggles appear to do nothing. Run after ancestor effects so localStorage matches.
   useEffect(() => {
     scheduleThemeUiColorModeSync()
+    setChronogroveCrossDomainColorModeCookie(colorMode, getChronogroveCrossDomainColorModeClientConfig() ?? undefined)
   }, [colorMode])
 
   return (

package/src/gatsby/build-theme-ui-color-mode-head-components.js

@@ -11,15 +11,16 @@ import {
  * React head elements for Theme UI color mode: no-flash script, HTML background script, fallback CSS.
  * Compose with your own meta tags (e.g. Emotion insertion point) in `onRenderBody`.
  *
- * @param {{ theme: object }} options — Theme UI theme object (same as `ThemeUIProvider`)
+ * @param {{ theme: object, crossDomainColorMode?: { registrableDomain?: string, cookieName?: string } | null }} options — Theme UI theme object (same as `ThemeUIProvider`). Optional `crossDomainColorMode` enables subdomain cookie sync (must match the same object passed to `setChronogroveCrossDomainColorModeClientConfig` in the browser).
  * @returns {import('react').ReactElement[]}
  */
-export function buildThemeUiColorModeHeadComponents({ theme }) {
+export function buildThemeUiColorModeHeadComponents({ theme, crossDomainColorMode = null }) {
   const surface = resolveChronogroveSurfaceColors(theme)
-  const colorModeScript = buildThemeUiNoFlashInlineScript()
+  const colorModeScript = buildThemeUiNoFlashInlineScript({ crossDomainColorMode })
   const htmlBackgroundScript = buildHtmlBackgroundInlineScript({
     defaultBackgroundHex: surface.defaultBackgroundHex,
-    darkBackgroundHex: surface.darkBackgroundHex
+    darkBackgroundHex: surface.darkBackgroundHex,
+    crossDomainColorMode
   })
   const colorModeFallbackCSS = buildThemeUiColorModeFallbackCss({
     defaultBackgroundHex: surface.defaultBackgroundHex,

package/src/gatsby/index.spec.js

@@ -28,7 +28,8 @@ describe('@chronogrove/ui/gatsby', () => {
 
       const { container: colorModeScriptContainer } = render(head[0])
       const colorModeScriptTag = colorModeScriptContainer.querySelector('script')
-      expect(colorModeScriptTag).toHaveTextContent(/localStorage\.getItem\(['"]theme-ui-color-mode['"]\)/)
+      expect(colorModeScriptTag).toHaveTextContent(/localStorage\.getItem\(__cgKey\)/)
+      expect(colorModeScriptTag.textContent).not.toContain('__cgGetCookie')
       expect(colorModeScriptTag).toHaveTextContent(/data-theme-ui-color-mode/)
 
       const { container: htmlBgScriptContainer } = render(head[1])
@@ -43,6 +44,15 @@ describe('@chronogrove/ui/gatsby', () => {
       expect(fallbackStyle).toHaveTextContent(/--theme-ui-colors-panel-background:/)
       expect(fallbackStyle).toHaveTextContent(/--theme-ui-colors-panel-text:/)
     })
+
+    it('embeds cookie merge when crossDomainColorMode.registrableDomain is set', () => {
+      const head = buildThemeUiColorModeHeadComponents({
+        theme: chronogroveTheme,
+        crossDomainColorMode: { registrableDomain: 'example.com' }
+      })
+      const { container } = render(head[0])
+      expect(container.querySelector('script').textContent).toContain('__cgGetCookie')
+    })
   })
 
   describe('onPreRenderHTMLSortThemeUiColorModeFirst', () => {

package/src/image-thumbnails.js

@@ -0,0 +1,89 @@
+import React from 'react'
+import { Box } from '@theme-ui/components'
+
+/** Default cap on thumbnails shown when `images` exceeds this count. */
+export const IMAGE_THUMBNAILS_DEFAULT_MAX = 4
+
+/** Thumbnail box size (px); retina-friendly optimizers typically use ~2× for width/height. */
+export const IMAGE_THUMBNAILS_SIZE_PX = 64
+
+/**
+ * Pass-through optimizer (CDN-agnostic default).
+ *
+ * @param {string | null | undefined} src
+ * @returns {string | null | undefined}
+ */
+export const IMAGE_THUMBNAILS_DEFAULT_OPTIMIZE_SRC = src => src
+
+/**
+ * Horizontal row of small circular image previews — e.g. post cards (`Recap`).
+ * Supply `optimizeSrc` for CDN-specific resizing (Gatsby theme uses a Cloudinary helper).
+ *
+ * @param {object} props
+ * @param {Array<string | null | undefined>} [props.images]
+ * @param {number} [props.maxImages]
+ * @param {(src: string) => string | null | undefined} [props.optimizeSrc]
+ */
+const ImageThumbnails = ({
+  images = [],
+  maxImages = IMAGE_THUMBNAILS_DEFAULT_MAX,
+  optimizeSrc = IMAGE_THUMBNAILS_DEFAULT_OPTIMIZE_SRC
+}) => {
+  if (!images || images.length === 0) {
+    return null
+  }
+
+  const displayImages = images.slice(0, maxImages)
+  const size = IMAGE_THUMBNAILS_SIZE_PX
+
+  return (
+    <Box
+      sx={{
+        display: 'flex',
+        gap: 2,
+        mb: 2,
+        flexWrap: 'wrap'
+      }}
+    >
+      {displayImages.map((src, index) => {
+        const input = typeof src === 'string' ? src : ''
+        const optimized = optimizeSrc(input)
+        const url = optimized !== null && optimized !== undefined ? String(optimized) : ''
+
+        return (
+          <Box
+            key={index}
+            sx={{
+              width: `${size}px`,
+              height: `${size}px`,
+              borderRadius: '50%',
+              overflow: 'hidden',
+              flexShrink: 0,
+              boxShadow: '0 2px 8px rgba(0, 0, 0, 0.15)',
+              border: '2px solid',
+              borderColor: 'background',
+              transform: `translateY(${index % 2 === 0 ? 0 : 5}px)`
+            }}
+          >
+            <Box
+              sx={{
+                width: '100%',
+                height: '100%',
+                ...(url
+                  ? {
+                      backgroundImage: `url(${url})`,
+                      backgroundSize: 'cover',
+                      backgroundPosition: 'center',
+                      backgroundRepeat: 'no-repeat'
+                    }
+                  : {})
+              }}
+            />
+          </Box>
+        )
+      })}
+    </Box>
+  )
+}
+
+export default ImageThumbnails