@chronogrove/ui 0.82.3 → 0.83.1

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)
 
@@ -67,6 +67,79 @@ Prefer deep imports so bundles stay lean:
 
 **JSX + bundlers:** Primitives such as [`button`](./src/button.js) use [`Box`](https://theme-ui.com/components/box) from `@theme-ui/components` with an `as` prop for native elements, so `sx` works with Gatsby’s classic JSX runtime and Next’s SWC without a Theme UI file pragma. Jest uses [`babel.config.cjs`](./babel.config.cjs) (automatic JSX).
 
+## Global CSS, Prism / third-party CSS, and fonts
+
+Styles load in three layers. Understanding the split prevents accidental duplicates and keeps each host's build minimal.
+
+### Layer order
+
+| #   | Layer                                           | Mechanism                                                                                                                                                                                                               |
+| --- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **Head — color-mode + Emotion insertion point** | Gatsby: `theme/gatsby-ssr.js` + `@chronogrove/ui/gatsby` helpers. Next: `ChronogroveNextRootLayoutHead` from `@chronogrove/ui/next`. Emit before any `<style>` tags so Emotion and Theme UI no-flash scripts run first. |
+| 2   | **Theme UI globals (`theme.global`)**           | `ChronogroveThemeProvider` renders `<Global styles={theme.global} />` via Emotion. This applies identical baseline CSS under both Gatsby and Next as long as the provider wraps the app. No extra import needed.        |
+| 3   | **Host global CSS**                             | Each host owns its plain-CSS files. See below for Gatsby and Next specifics.                                                                                                                                            |
+
+### Gatsby
+
+The theme's own global CSS entry is the side-effect import block in [`theme/gatsby-browser.js`](../../theme/gatsby-browser.js):
+
+```javascript
+import './src/styles/global.css' // layout, .sr-only, Prism overrides
+import 'lightgallery/css/lightgallery.css'
+import 'lightgallery/css/lg-thumbnail.css'
+import 'lightgallery/css/lg-zoom.css'
+import 'prismjs/themes/prism-solarizedlight.css'
+import 'prismjs/plugins/line-numbers/prism-line-numbers.css'
+```
+
+[`theme/src/styles/global.css`](../../theme/src/styles/global.css) also contains `@import '@chronogrove/ui/color-toggle-styles'` for the theme toggle animation.
+
+Prism is **tightly coupled to `gatsby-remark-prismjs`** (configured in [`theme/gatsby-config.js`](../../theme/gatsby-config.js)). The CSS theme and helper overrides (`.gatsby-highlight`, line-number padding, etc.) only make sense when that plugin is active. They are intentionally kept in the Gatsby theme rather than in this package.
+
+Sites that shadow or extend the theme can add additional side-effect imports in their own `gatsby-browser.js` alongside (not instead of) the theme's entry.
+
+### Next.js (App Router)
+
+The reference app is [`examples/chronogrove-next`](../../examples/chronogrove-next). Its [`app/globals.css`](../../examples/chronogrove-next/app/globals.css) shows the minimal baseline:
+
+```css
+/* Required if you use ColorToggle */
+@import '@chronogrove/ui/color-toggle-styles';
+
+html {
+  scroll-behavior: smooth;
+}
+
+body {
+  background-color: var(--theme-ui-colors-background);
+  -webkit-font-smoothing: antialiased;
+}
+```
+
+Import `globals.css` once from the root `layout.jsx`/`layout.tsx` — the same file that renders `ChronogroveNextRootLayoutHead` and `ChronogroveNextEmotionRegistry`. See [`examples/chronogrove-next/app/layout.jsx`](../../examples/chronogrove-next/app/layout.jsx).
+
+For syntax highlighting in a Next MDX pipeline, use whatever highlighter fits your setup (e.g. [Shiki via rehype-pretty-code](https://rehype-pretty.pages.dev/)) and load only its CSS. There is no dependency on `prismjs` in this package, and you should not add the Prism CSS from the Gatsby theme to a Next app unless your MDX pipeline explicitly emits Prism class names.
+
+### Fonts
+
+The default Chronogrove theme uses **system font stacks** only (defined in [`src/theme.js`](./src/theme.js)):
+
+```js
+sans: '-apple-system, BlinkMacSystemFont, avenir next, ..., sans-serif'
+mono: 'Menlo, Consolas, ..., monospace'
+```
+
+No `@font-face` rules or external font URLs are shipped by this package. Web fonts are **host-owned**:
+
+- **Next.js:** use [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to load faces with zero layout shift; then pass the resulting CSS variable or family name into a theme override: `{ fonts: { body: 'var(--font-inter), sans-serif' } }`.
+- **Gatsby:** use [`gatsby-plugin-google-gtag`](https://www.gatsbyjs.com/plugins/gatsby-plugin-google-gtag/) or a `<link>` in `gatsby-ssr.js`, then extend `theme.fonts` in your `gatsby-config.js` theme options.
+
+Changing `theme.fonts` is the only hook needed; `ChronogroveThemeProvider` merges the override automatically via Theme UI.
+
+### Font Awesome (icons)
+
+`@chronogrove/ui` depends on `@fortawesome/fontawesome-svg-core` and `@fortawesome/react-fontawesome` for `WidgetHeader`. Icon **definitions** (e.g. `faGithub`) come from a kit you add to your own app — see the `WidgetHeader + icons` bullet in the [Next.js](#nextjs-app-router) section above.
+
 ## Changelog
 
 Releases are recorded in the repository root [`CHANGELOG.md`](../../CHANGELOG.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chronogrove/ui",
-  "version": "0.82.3",
+  "version": "0.83.1",
   "description": "Chronogrove Theme UI theme, color mode helpers, and shared UI primitives",
   "license": "MIT",
   "type": "module",
@@ -138,6 +138,26 @@
       "import": "./src/action-card-layout.js",
       "default": "./src/action-card-layout.js"
     },
+    "./article-column-container": {
+      "import": "./src/article-column-container.js",
+      "default": "./src/article-column-container.js"
+    },
+    "./home-dashboard-layout": {
+      "import": "./src/home-dashboard-layout.js",
+      "default": "./src/home-dashboard-layout.js"
+    },
+    "./page-shell-layout": {
+      "import": "./src/page-shell-layout.js",
+      "default": "./src/page-shell-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/article-column-container.js

@@ -0,0 +1,23 @@
+import React from 'react'
+import { Container } from '@theme-ui/components'
+
+/**
+ * Primary text column width for MDX posts, blog index, and about-style pages.
+ * Keep in sync wherever the article measure must match (Gatsby post template, blog index, etc.).
+ */
+export const articleColumnContainerSx = {
+  position: 'relative',
+  width: ['', '', 'max(80ch, 50vw)'],
+  lineHeight: 1.7
+}
+
+/**
+ * Theme UI `Container` with {@link articleColumnContainerSx}. Pass `sx` to merge (e.g. `flexGrow: 1` on the blog index).
+ */
+export function ArticleColumnContainer({ children, sx = {}, ...rest }) {
+  return (
+    <Container sx={{ ...articleColumnContainerSx, ...sx }} {...rest}>
+      {children}
+    </Container>
+  )
+}

package/src/article-column-container.spec.js

@@ -0,0 +1,40 @@
+import React from 'react'
+import { render, screen } from '@testing-library/react'
+import { ChronogroveThemeProvider } from './provider.js'
+import chronogroveTheme from './theme.js'
+
+import { ArticleColumnContainer, articleColumnContainerSx } from './article-column-container.js'
+
+describe('articleColumnContainerSx', () => {
+  it('defines the shared article measure', () => {
+    expect(articleColumnContainerSx).toMatchObject({
+      position: 'relative',
+      width: ['', '', 'max(80ch, 50vw)'],
+      lineHeight: 1.7
+    })
+  })
+})
+
+describe('ArticleColumnContainer', () => {
+  it('renders children with merged sx', () => {
+    render(
+      <ChronogroveThemeProvider theme={chronogroveTheme}>
+        <ArticleColumnContainer sx={{ flexGrow: 1 }} data-testid='ac'>
+          <span>body</span>
+        </ArticleColumnContainer>
+      </ChronogroveThemeProvider>
+    )
+    expect(screen.getByTestId('ac')).toContainElement(screen.getByText('body'))
+  })
+
+  it('renders with base article sx when sx is omitted', () => {
+    render(
+      <ChronogroveThemeProvider theme={chronogroveTheme}>
+        <ArticleColumnContainer data-testid='ac-base'>
+          <span>only-base</span>
+        </ArticleColumnContainer>
+      </ChronogroveThemeProvider>
+    )
+    expect(screen.getByTestId('ac-base')).toContainElement(screen.getByText('only-base'))
+  })
+})

package/src/home-dashboard-layout.js

@@ -0,0 +1,58 @@
+import React from 'react'
+import { Box, Grid } from '@theme-ui/components'
+
+/** Theme UI `Grid` `columns` for the home dashboard: single column until `md`, then sidebar + main. */
+export const homeDashboardGridColumns = [
+  null,
+  null,
+  'minmax(200px, 0.375fr) minmax(0, 1.625fr)',
+  'minmax(200px, 0.4fr) minmax(0, 1.6fr)'
+]
+
+export const homeDashboardGridGap = [null, 4]
+
+/** Default aside spacing; merge with site-specific `sx` (e.g. sticky side nav in demos). */
+export const homeDashboardAsideSx = {
+  mb: [4, null]
+}
+
+/** Rounded “glass” panel shell around the main home column (matches gatsby-theme-chronogrove home). */
+export const homeDashboardMainShellSx = {
+  position: 'relative',
+  borderTopRightRadius: '3em',
+  borderTopLeftRadius: '.5em',
+  px: [3, 4],
+  pt: [2, 3]
+}
+
+export const homeDashboardMainInnerMaxWidthSx = {
+  maxWidth: '1200px'
+}
+
+/** Outer stack below the page chrome on the home template (`minHeight`, top padding). */
+export const homeDashboardPageOuterSx = {
+  minHeight: '500px',
+  pt: 3,
+  px: 0
+}
+
+/**
+ * Two-column home dashboard grid (sidebar + main). Pass full `main` node so callers can set
+ * `role="main"`, skip-nav targets, footer, and microformats in one place.
+ *
+ * @param {object} props
+ * @param {React.ReactNode} props.aside
+ * @param {React.ReactNode} props.main
+ * @param {import('theme-ui').ThemeUIStyleObject} [props.asideSx] merged after {@link homeDashboardAsideSx}
+ * @param {React.ComponentProps<typeof Grid>} [props.gridProps] forwarded to `Grid`
+ */
+export function HomeDashboardGrid({ aside, main, asideSx = {}, gridProps = {}, ...gridRest }) {
+  return (
+    <Grid columns={homeDashboardGridColumns} gap={homeDashboardGridGap} {...gridProps} {...gridRest}>
+      <Box as='aside' sx={{ ...homeDashboardAsideSx, ...asideSx }}>
+        {aside}
+      </Box>
+      {main}
+    </Grid>
+  )
+}

package/src/home-dashboard-layout.spec.js

@@ -0,0 +1,60 @@
+import React from 'react'
+import { render, screen } from '@testing-library/react'
+import { ChronogroveThemeProvider } from './provider.js'
+import chronogroveTheme from './theme.js'
+
+import {
+  HomeDashboardGrid,
+  homeDashboardAsideSx,
+  homeDashboardGridColumns,
+  homeDashboardGridGap,
+  homeDashboardMainInnerMaxWidthSx,
+  homeDashboardMainShellSx,
+  homeDashboardPageOuterSx
+} from './home-dashboard-layout.js'
+
+describe('home dashboard layout tokens', () => {
+  it('exports grid columns and gap used by the Gatsby home template', () => {
+    expect(homeDashboardGridColumns[2]).toContain('minmax(200px')
+    expect(homeDashboardGridGap).toEqual([null, 4])
+    expect(homeDashboardAsideSx).toEqual({ mb: [4, null] })
+    expect(homeDashboardMainShellSx.borderTopRightRadius).toBe('3em')
+    expect(homeDashboardMainInnerMaxWidthSx.maxWidth).toBe('1200px')
+    expect(homeDashboardPageOuterSx.minHeight).toBe('500px')
+  })
+})
+
+describe('HomeDashboardGrid', () => {
+  it('renders aside and main slots', () => {
+    render(
+      <ChronogroveThemeProvider theme={chronogroveTheme}>
+        <HomeDashboardGrid aside={<span>nav</span>} main={<div data-testid='main'>content</div>} />
+      </ChronogroveThemeProvider>
+    )
+    expect(screen.getByText('nav')).toBeInTheDocument()
+    expect(screen.getByTestId('main')).toHaveTextContent('content')
+  })
+
+  it('merges asideSx onto the aside', () => {
+    const { container } = render(
+      <ChronogroveThemeProvider theme={chronogroveTheme}>
+        <HomeDashboardGrid aside={<span>a</span>} main={<span>b</span>} asideSx={{ position: 'sticky' }} />
+      </ChronogroveThemeProvider>
+    )
+    const aside = container.querySelector('aside')
+    expect(aside).toBeTruthy()
+  })
+
+  it('forwards gridProps to Grid', () => {
+    const { container } = render(
+      <ChronogroveThemeProvider theme={chronogroveTheme}>
+        <HomeDashboardGrid
+          aside={<span>l</span>}
+          main={<span>r</span>}
+          gridProps={{ 'data-testid': 'hdg', id: 'home-dash-grid' }}
+        />
+      </ChronogroveThemeProvider>
+    )
+    expect(container.querySelector('#home-dash-grid')).toBeTruthy()
+  })
+})

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/page-shell-layout.js

@@ -0,0 +1,57 @@
+import React from 'react'
+import { Box } from '@theme-ui/components'
+
+import { SkipNavContent, SkipNavLink } from './skip-nav/index.js'
+
+/**
+ * Default page chrome: skip link, optional header and footer slots, and a main landmark (unless disabled).
+ * Wire Gatsby-specific nav/footer and Zustand-driven `paddingBottom` from the site package.
+ *
+ * @param {object} props
+ * @param {React.ReactNode} props.children
+ * @param {boolean} [props.disableMainWrapper]
+ * @param {boolean} [props.hideHeader] when true, `header` is not rendered
+ * @param {boolean} [props.hideFooter] when true, `footer` is not rendered
+ * @param {boolean} [props.transparentBackground]
+ * @param {number|string} [props.paddingBottom] bottom padding (e.g. room for a fixed audio bar)
+ * @param {React.ReactNode} [props.header] placed inside `<header role="banner">` when not hidden
+ * @param {React.ReactNode} [props.footer]
+ */
+export function ChronogrovePageShell({
+  children,
+  disableMainWrapper = false,
+  hideHeader = false,
+  hideFooter = false,
+  transparentBackground = false,
+  paddingBottom = 0,
+  header = null,
+  footer = null
+}) {
+  return (
+    <Box
+      sx={{
+        backgroundColor: transparentBackground ? 'transparent' : 'background',
+        display: 'flex',
+        flexDirection: 'column',
+        flexGrow: 1,
+        color: theme => theme?.colors?.text,
+        pb: paddingBottom
+      }}
+    >
+      <SkipNavLink />
+
+      {!hideHeader && header ? <header role='banner'>{header}</header> : null}
+
+      {disableMainWrapper ? (
+        children
+      ) : (
+        <Box as='main' role='main'>
+          <SkipNavContent />
+          {children}
+        </Box>
+      )}
+
+      {!hideFooter && footer ? footer : null}
+    </Box>
+  )
+}

package/src/page-shell-layout.spec.js

@@ -0,0 +1,71 @@
+import React from 'react'
+import { render, screen } from '@testing-library/react'
+import { ChronogroveThemeProvider } from './provider.js'
+import chronogroveTheme from './theme.js'
+
+import { ChronogrovePageShell } from './page-shell-layout.js'
+
+function shellRender(ui) {
+  return render(<ChronogroveThemeProvider theme={chronogroveTheme}>{ui}</ChronogroveThemeProvider>)
+}
+
+describe('ChronogrovePageShell', () => {
+  it('renders skip link, header, main with skip target, children, and footer', () => {
+    shellRender(
+      <ChronogrovePageShell header={<span>hdr</span>} footer={<span>ftr</span>} paddingBottom='12px'>
+        <span>inner</span>
+      </ChronogrovePageShell>
+    )
+    expect(screen.getByText('inner')).toBeInTheDocument()
+    expect(screen.getByText('hdr')).toBeInTheDocument()
+    expect(screen.getByText('ftr')).toBeInTheDocument()
+    expect(document.querySelector('main[role="main"]')).toBeTruthy()
+  })
+
+  it('omits header when hideHeader', () => {
+    shellRender(
+      <ChronogrovePageShell hideHeader header={<span>no</span>} footer={null}>
+        <span>x</span>
+      </ChronogrovePageShell>
+    )
+    expect(screen.queryByText('no')).not.toBeInTheDocument()
+  })
+
+  it('omits footer when hideFooter', () => {
+    shellRender(
+      <ChronogrovePageShell hideFooter footer={<span>no</span>}>
+        <span>x</span>
+      </ChronogrovePageShell>
+    )
+    expect(screen.queryByText('no')).not.toBeInTheDocument()
+  })
+
+  it('renders children without main wrapper when disableMainWrapper', () => {
+    shellRender(
+      <ChronogrovePageShell disableMainWrapper>
+        <span data-testid='bare'>bare</span>
+      </ChronogrovePageShell>
+    )
+    expect(screen.getByTestId('bare')).toBeInTheDocument()
+    expect(document.querySelector('main[role="main"]')).toBeFalsy()
+  })
+
+  it('uses transparent background when requested', () => {
+    const { container } = shellRender(
+      <ChronogrovePageShell transparentBackground>
+        <span>t</span>
+      </ChronogrovePageShell>
+    )
+    expect(container.firstChild).toBeTruthy()
+  })
+
+  it('does not render a banner when header is null', () => {
+    shellRender(
+      <ChronogrovePageShell header={null}>
+        <span>no-banner</span>
+      </ChronogrovePageShell>
+    )
+    expect(screen.getByText('no-banner')).toBeInTheDocument()
+    expect(document.querySelector('header[role="banner"]')).toBeFalsy()
+  })
+})

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()
+  })
+})