@chronogrove/ui 0.82.3 → 0.83.0

package/README.md

@@ -44,7 +44,7 @@ Prefer deep imports so bundles stay lean:
 | `@chronogrove/ui/widget-header`            | Widget section title row (optional Font Awesome icon, aside slot, optional metrics)                                                                                                                                                                                                                                                              |
 | `@chronogrove/ui/gatsby`                   | Color-mode Gatsby SSR/browser helpers                                                                                                                                                                                                                                                                                                            |
 
-**Additional subpaths:** The table lists the most common entry points. Also published: **`pagination`** (full bar; composes **`pagination-button`**), **`category-label`**, **`metric-badge`**, **`metric-card`**, **`muted-card-footer`**, **`status-card`**, **`widget-section`**, **`widget-call-to-action`**, **`external-link-icon`**. The authoritative list is **`package.json`** → **`exports`**.
+**Additional subpaths:** The table lists the most common entry points. Also published: **`pagination`** (full bar; composes **`pagination-button`**), **`category-label`**, **`metric-badge`**, **`metric-card`**, **`muted-card-footer`**, **`status-card`**, **`widget-section`**, **`widget-call-to-action`**, **`external-link-icon`**, **`thumbnail-strip`**, **`image-thumbnails`** (`optimizeSrc` for CDN resizing; Gatsby passes a Cloudinary helper). The authoritative list is **`package.json`** → **`exports`**.
 
 ## Next.js (App Router)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chronogrove/ui",
-  "version": "0.82.3",
+  "version": "0.83.0",
   "description": "Chronogrove Theme UI theme, color mode helpers, and shared UI primitives",
   "license": "MIT",
   "type": "module",
@@ -138,6 +138,14 @@
       "import": "./src/action-card-layout.js",
       "default": "./src/action-card-layout.js"
     },
+    "./thumbnail-strip": {
+      "import": "./src/thumbnail-strip.js",
+      "default": "./src/thumbnail-strip.js"
+    },
+    "./image-thumbnails": {
+      "import": "./src/image-thumbnails.js",
+      "default": "./src/image-thumbnails.js"
+    },
     "./gatsby": {
       "import": "./src/gatsby/index.js",
       "default": "./src/gatsby/index.js"

package/src/__snapshots__/image-thumbnails.spec.js.snap

@@ -0,0 +1,61 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`ImageThumbnails matches snapshot with custom maxImages 1`] = `
+<DocumentFragment>
+  <div
+    class="css-1ud2rd2"
+  >
+    <div
+      class="css-1jg6seg"
+    >
+      <div
+        class="css-m0n9e0"
+      />
+    </div>
+    <div
+      class="css-1da34oq"
+    >
+      <div
+        class="css-1yk8ryr"
+      />
+    </div>
+  </div>
+</DocumentFragment>
+`;
+
+exports[`ImageThumbnails matches snapshot with default props 1`] = `
+<DocumentFragment>
+  <div
+    class="css-1ud2rd2"
+  >
+    <div
+      class="css-1jg6seg"
+    >
+      <div
+        class="css-m0n9e0"
+      />
+    </div>
+    <div
+      class="css-1da34oq"
+    >
+      <div
+        class="css-1yk8ryr"
+      />
+    </div>
+    <div
+      class="css-1jg6seg"
+    >
+      <div
+        class="css-1udw8eu"
+      />
+    </div>
+    <div
+      class="css-1da34oq"
+    >
+      <div
+        class="css-dvh21o"
+      />
+    </div>
+  </div>
+</DocumentFragment>
+`;

package/src/__snapshots__/thumbnail-strip.spec.js.snap

@@ -0,0 +1,61 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`ThumbnailStrip matches snapshot with custom maxImages and size 1`] = `
+<DocumentFragment>
+  <div
+    class="css-dpp4jp"
+  >
+    <div
+      class="css-1p4ud4e"
+    >
+      <div
+        class="css-m0n9e0"
+      />
+    </div>
+    <div
+      class="css-zlkqv4"
+    >
+      <div
+        class="css-1yk8ryr"
+      />
+    </div>
+  </div>
+</DocumentFragment>
+`;
+
+exports[`ThumbnailStrip matches snapshot with default props 1`] = `
+<DocumentFragment>
+  <div
+    class="css-1httq4l"
+  >
+    <div
+      class="css-1jl8pr3"
+    >
+      <div
+        class="css-m0n9e0"
+      />
+    </div>
+    <div
+      class="css-f02gwb"
+    >
+      <div
+        class="css-1yk8ryr"
+      />
+    </div>
+    <div
+      class="css-44fsif"
+    >
+      <div
+        class="css-1udw8eu"
+      />
+    </div>
+    <div
+      class="css-ladzy1"
+    >
+      <div
+        class="css-dvh21o"
+      />
+    </div>
+  </div>
+</DocumentFragment>
+`;

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

package/src/image-thumbnails.spec.js

@@ -0,0 +1,95 @@
+import { render } from '@testing-library/react'
+import { ThemeUIProvider } from 'theme-ui'
+import React from 'react'
+
+import ImageThumbnails from './image-thumbnails.js'
+
+const stubTheme = { colors: { background: '#fff' } }
+
+const wrap = ui => render(<ThemeUIProvider theme={stubTheme}>{ui}</ThemeUIProvider>)
+
+describe('ImageThumbnails', () => {
+  const sampleImages = [
+    'https://example.com/image1.jpg',
+    'https://example.com/image2.jpg',
+    'https://example.com/image3.jpg',
+    'https://example.com/image4.jpg',
+    'https://example.com/image5.jpg'
+  ]
+
+  it('renders thumbnails when images are provided', () => {
+    const { container } = wrap(<ImageThumbnails images={sampleImages} />)
+
+    const wrapper = container.firstChild
+    expect(wrapper).toBeTruthy()
+    expect(wrapper.children).toHaveLength(4)
+  })
+
+  it('renders correct number of thumbnails based on maxImages prop', () => {
+    const { container } = wrap(<ImageThumbnails images={sampleImages} maxImages={3} />)
+
+    const wrapper = container.firstChild
+    expect(wrapper).toBeTruthy()
+    expect(wrapper.children).toHaveLength(3)
+  })
+
+  it('returns null when images array is empty', () => {
+    const { container } = wrap(<ImageThumbnails images={[]} />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  it('returns null when images is null', () => {
+    const { container } = wrap(<ImageThumbnails images={null} />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  it('returns null when images is undefined', () => {
+    const { container } = wrap(<ImageThumbnails />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  it('renders fewer thumbnails when fewer images are provided than maxImages', () => {
+    const twoImages = ['https://example.com/image1.jpg', 'https://example.com/image2.jpg']
+    const { container } = wrap(<ImageThumbnails images={twoImages} maxImages={4} />)
+
+    const wrapper = container.firstChild
+    expect(wrapper).toBeTruthy()
+    expect(wrapper.children).toHaveLength(2)
+  })
+
+  it('uses optimizeSrc when provided', () => {
+    const optimizer = jest.fn(s => `${s}?x=1`)
+    const { container } = wrap(<ImageThumbnails images={['https://example.com/a.jpg']} optimizeSrc={optimizer} />)
+    expect(optimizer).toHaveBeenCalledWith('https://example.com/a.jpg')
+    expect(container.firstChild).toBeTruthy()
+  })
+
+  it('omits inner background when optimizeSrc returns null', () => {
+    const { container } = wrap(<ImageThumbnails images={['https://example.com/z.jpg']} optimizeSrc={() => null} />)
+    expect(container.firstChild?.firstChild?.firstChild).toBeTruthy()
+  })
+
+  it('omits inner background when optimizeSrc returns undefined', () => {
+    const { container } = wrap(<ImageThumbnails images={['https://example.com/z.jpg']} optimizeSrc={() => undefined} />)
+    expect(container.firstChild?.firstChild?.firstChild).toBeTruthy()
+  })
+
+  it('handles null and non-string slots as empty thumbnails (same slot count)', () => {
+    const mixedImages = ['https://example.com/image1.jpg', null, 'https://example.com/image2.jpg', undefined]
+    const { container } = wrap(<ImageThumbnails images={mixedImages} maxImages={4} />)
+
+    const wrapper = container.firstChild
+    expect(wrapper).toBeTruthy()
+    expect(wrapper.children).toHaveLength(4)
+  })
+
+  it('matches snapshot with default props', () => {
+    const { asFragment } = wrap(<ImageThumbnails images={sampleImages} />)
+    expect(asFragment()).toMatchSnapshot()
+  })
+
+  it('matches snapshot with custom maxImages', () => {
+    const { asFragment } = wrap(<ImageThumbnails images={sampleImages} maxImages={2} />)
+    expect(asFragment()).toMatchSnapshot()
+  })
+})

package/src/thumbnail-strip.js

@@ -0,0 +1,72 @@
+import React from 'react'
+import { Box } from '@theme-ui/components'
+
+/**
+ * Compact vertical strip of thumbnail images — staggered/offset for card side rails.
+ */
+const ThumbnailStrip = ({ images = [], maxImages = 4, size = 36 }) => {
+  if (!images || images.length === 0) {
+    return null
+  }
+
+  const displayImages = images.slice(0, maxImages)
+  const overlap = size * 0.35 // 35% overlap for compact stacking
+  const stripW = size + 8
+  const stripH = displayImages.length * (size - overlap) + overlap
+
+  return (
+    <Box
+      sx={{
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        position: 'relative',
+        // Theme UI maps bare numbers in `sx` to theme scales — use explicit px for layout math.
+        width: `${stripW}px`,
+        height: `${stripH}px`,
+        flexShrink: 0
+      }}
+    >
+      {displayImages.map((src, index) => (
+        <Box
+          key={index}
+          sx={{
+            position: 'absolute',
+            top: `${index * (size - overlap)}px`,
+            left: index % 2 === 0 ? 0 : '8px',
+            width: `${size}px`,
+            height: `${size}px`,
+            borderRadius: '6px',
+            overflow: 'hidden',
+            boxShadow: '0 2px 6px rgba(0, 0, 0, 0.12)',
+            border: '2px solid',
+            borderColor: 'background',
+            transition: 'transform 0.2s ease',
+            zIndex: displayImages.length - index,
+            '&:hover': {
+              transform: 'scale(1.08)',
+              zIndex: displayImages.length + 1
+            }
+          }}
+        >
+          <Box
+            sx={{
+              width: '100%',
+              height: '100%',
+              ...(typeof src === 'string' && src
+                ? {
+                    backgroundImage: `url(${src})`,
+                    backgroundSize: 'cover',
+                    backgroundPosition: 'center',
+                    backgroundRepeat: 'no-repeat'
+                  }
+                : {})
+            }}
+          />
+        </Box>
+      ))}
+    </Box>
+  )
+}
+
+export default ThumbnailStrip

package/src/thumbnail-strip.spec.js

@@ -0,0 +1,83 @@
+import { render } from '@testing-library/react'
+import { ThemeUIProvider } from 'theme-ui'
+import React from 'react'
+
+import ThumbnailStrip from './thumbnail-strip.js'
+
+const stubTheme = { colors: { background: '#fff' } }
+
+const wrap = ui => render(<ThemeUIProvider theme={stubTheme}>{ui}</ThemeUIProvider>)
+
+describe('ThumbnailStrip', () => {
+  const sampleImages = [
+    'https://example.com/image1.jpg',
+    'https://example.com/image2.jpg',
+    'https://example.com/image3.jpg',
+    'https://example.com/image4.jpg',
+    'https://example.com/image5.jpg'
+  ]
+
+  it('renders thumbnails when images are provided', () => {
+    const { container } = wrap(<ThumbnailStrip images={sampleImages} />)
+
+    const wrapper = container.firstChild
+    expect(wrapper).toBeTruthy()
+    expect(wrapper.children).toHaveLength(4)
+  })
+
+  it('renders correct number of thumbnails based on maxImages prop', () => {
+    const { container } = wrap(<ThumbnailStrip images={sampleImages} maxImages={3} />)
+
+    const wrapper = container.firstChild
+    expect(wrapper).toBeTruthy()
+    expect(wrapper.children).toHaveLength(3)
+  })
+
+  it('returns null when images array is empty', () => {
+    const { container } = wrap(<ThumbnailStrip images={[]} />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  it('returns null when images is null', () => {
+    const { container } = wrap(<ThumbnailStrip images={null} />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  it('returns null when images is undefined', () => {
+    const { container } = wrap(<ThumbnailStrip />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  it('renders fewer thumbnails when fewer images are provided than maxImages', () => {
+    const twoImages = ['https://example.com/image1.jpg', 'https://example.com/image2.jpg']
+    const { container } = wrap(<ThumbnailStrip images={twoImages} maxImages={4} />)
+
+    const wrapper = container.firstChild
+    expect(wrapper).toBeTruthy()
+    expect(wrapper.children).toHaveLength(2)
+  })
+
+  it('accepts custom size prop', () => {
+    const { container } = wrap(<ThumbnailStrip images={sampleImages} size={50} />)
+
+    const wrapper = container.firstChild
+    expect(wrapper).toBeTruthy()
+    expect(wrapper.children).toHaveLength(4)
+  })
+
+  it('omits background when an entry is not a non-empty string', () => {
+    const mixed = ['https://example.com/a.jpg', '', null]
+    const { container } = wrap(<ThumbnailStrip images={mixed} maxImages={4} />)
+    expect(container.firstChild?.children?.length).toBe(3)
+  })
+
+  it('matches snapshot with default props', () => {
+    const { asFragment } = wrap(<ThumbnailStrip images={sampleImages} />)
+    expect(asFragment()).toMatchSnapshot()
+  })
+
+  it('matches snapshot with custom maxImages and size', () => {
+    const { asFragment } = wrap(<ThumbnailStrip images={sampleImages} maxImages={2} size={48} />)
+    expect(asFragment()).toMatchSnapshot()
+  })
+})