@chronogrove/ui 0.78.0 → 0.80.0

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

@@ -22,12 +22,41 @@ describe('head-inline scripts', () => {
 
   it('buildThemeUiColorModeFallbackCss sets CSS vars', () => {
     const css = buildThemeUiColorModeFallbackCss({
+      defaultBackgroundHex: '#fdf8f5',
+      darkBackgroundHex: '#14141F',
       defaultTextHex: '#111',
       defaultTextMutedHex: '#333',
       darkTextHex: '#fff',
       darkTextMutedHex: '#ccc'
     })
+    expect(css).toContain(':root {')
+    expect(css).toContain('--theme-ui-colors-background: #fdf8f5')
     expect(css).toContain('--theme-ui-colors-text: #111')
     expect(css).toContain('--theme-ui-colors-text: #fff')
+    expect(css).toContain('--theme-ui-colors-panel-background:')
+    expect(css).toContain('--theme-ui-colors-panel-text:')
+  })
+
+  it('buildThemeUiColorModeFallbackCss uses default background hexes when omitted', () => {
+    const css = buildThemeUiColorModeFallbackCss({
+      defaultTextHex: '#111',
+      defaultTextMutedHex: '#333',
+      darkTextHex: '#fff',
+      darkTextMutedHex: '#ccc'
+    })
+    expect(css).toContain('--theme-ui-colors-background: #fdf8f5')
+    expect(css).toContain('--theme-ui-colors-background: #14141F')
+  })
+
+  it('buildThemeUiColorModeFallbackCss uses chronogrove-theme-surface-colors when called with no options', () => {
+    const css = buildThemeUiColorModeFallbackCss()
+    expect(css).toContain('--theme-ui-colors-background: #fdf8f5')
+    expect(css).toContain('--theme-ui-colors-background: #14141F')
+    expect(css).toContain('rgba(255, 255, 255, 0.45)')
+    expect(css).toContain('rgba(20, 20, 31, 0.45)')
+    expect(css).toMatch(/--theme-ui-colors-text: #111/)
+    expect(css).toMatch(/--theme-ui-colors-text-muted: #333/)
+    expect(css).toMatch(/--theme-ui-colors-text: #fff/)
+    expect(css).toMatch(/--theme-ui-colors-text-muted: #d8d8d8/)
   })
 })

package/src/color-mode/index.js

@@ -5,9 +5,12 @@ export {
 } from './constants.js'
 export { normalizeThemeUiColorMode } from './normalize.js'
 export { resolveChronogroveSurfaceColors } from './resolve-theme-colors.js'
+export { chronogroveHeadTheme } from './chronogrove-head-theme.js'
 export {
   buildThemeUiNoFlashInlineScript,
   buildHtmlBackgroundInlineScript,
   buildThemeUiColorModeFallbackCss
 } from './head-inline.js'
 export { resolveThemeUiColorMode, syncThemeUiColorMode, scheduleThemeUiColorModeSync } from './browser-sync.js'
+export { reconcileThemeUiColorModeOnNavigation } from './spa-navigation.js'
+export { useDocumentColorModeSurface } from './use-document-color-mode-surface.js'

package/src/color-mode/resolve-theme-colors.js

@@ -1,3 +1,8 @@
+import {
+  chronogroveThemeSurfaceColorsDark,
+  chronogroveThemeSurfaceColorsLight
+} from '../chronogrove-theme-surface-colors.js'
+
 function pickColor(value) {
   if (typeof value === 'string') {
     return value
@@ -12,12 +17,19 @@ function pickColor(value) {
 export function resolveChronogroveSurfaceColors(theme) {
   const colors = theme?.colors || {}
   const dark = colors.modes?.dark || {}
+  const light = chronogroveThemeSurfaceColorsLight
+  const darkSurface = chronogroveThemeSurfaceColorsDark
   return {
-    defaultBackgroundHex: pickColor(colors.background) || '#fdf8f5',
-    darkBackgroundHex: pickColor(dark.background) || '#14141F',
-    defaultTextHex: pickColor(colors.text) || '#111',
-    defaultTextMutedHex: pickColor(colors.textMuted) || '#333',
-    darkTextHex: pickColor(dark.text) || '#fff',
-    darkTextMutedHex: pickColor(dark.textMuted) || '#d8d8d8'
+    defaultBackgroundHex: pickColor(colors.background) || light.background,
+    darkBackgroundHex: pickColor(dark.background) || darkSurface.background,
+    defaultTextHex: pickColor(colors.text) || light.text,
+    defaultTextMutedHex: pickColor(colors.textMuted) || light.textMuted,
+    darkTextHex: pickColor(dark.text) || darkSurface.text,
+    darkTextMutedHex: pickColor(dark.textMuted) || darkSurface.textMuted,
+    defaultPanelBackground: pickColor(colors['panel-background']) || light['panel-background'],
+    darkPanelBackground: pickColor(dark['panel-background']) || darkSurface['panel-background'],
+    /** Head fallback only; panel copy usually uses `color: 'text'` — no separate `panel-text` token required. */
+    defaultPanelText: pickColor(colors['panel-text']) || pickColor(colors.text) || light.text,
+    darkPanelText: pickColor(dark['panel-text']) || pickColor(dark.text) || darkSurface.text
   }
 }

package/src/color-mode/resolve-theme-colors.spec.js

@@ -7,11 +7,13 @@ describe('resolveChronogroveSurfaceColors', () => {
         background: '#fdf8f5',
         text: '#111',
         textMuted: '#333',
+        'panel-background': 'rgba(255, 255, 255, 0.45)',
         modes: {
           dark: {
             background: '#14141F',
             text: '#fff',
-            textMuted: '#d8d8d8'
+            textMuted: '#d8d8d8',
+            'panel-background': 'rgba(20, 20, 31, 0.45)'
           }
         }
       }
@@ -22,7 +24,11 @@ describe('resolveChronogroveSurfaceColors', () => {
       defaultTextHex: '#111',
       defaultTextMutedHex: '#333',
       darkTextHex: '#fff',
-      darkTextMutedHex: '#d8d8d8'
+      darkTextMutedHex: '#d8d8d8',
+      defaultPanelBackground: 'rgba(255, 255, 255, 0.45)',
+      darkPanelBackground: 'rgba(20, 20, 31, 0.45)',
+      defaultPanelText: '#111',
+      darkPanelText: '#fff'
     })
   })
 
@@ -33,7 +39,11 @@ describe('resolveChronogroveSurfaceColors', () => {
       defaultTextHex: '#111',
       defaultTextMutedHex: '#333',
       darkTextHex: '#fff',
-      darkTextMutedHex: '#d8d8d8'
+      darkTextMutedHex: '#d8d8d8',
+      defaultPanelBackground: 'rgba(255, 255, 255, 0.45)',
+      darkPanelBackground: 'rgba(20, 20, 31, 0.45)',
+      defaultPanelText: '#111',
+      darkPanelText: '#fff'
     })
   })
 })

package/src/color-mode/spa-navigation.js

@@ -0,0 +1,14 @@
+import { RECONCILE_COLOR_MODE_EVENT } from './constants.js'
+import { scheduleThemeUiColorModeSync } from './browser-sync.js'
+
+/**
+ * Run after client-side navigations (e.g. Next.js App Router) so Theme UI color mode stays aligned
+ * with `localStorage` and the document. Dispatches {@link RECONCILE_COLOR_MODE_EVENT} for listeners.
+ * Same behavior as {@link onRouteUpdateThemeUiColorMode} in `@chronogrove/ui/gatsby`.
+ */
+export function reconcileThemeUiColorModeOnNavigation() {
+  scheduleThemeUiColorModeSync()
+  if (typeof window !== 'undefined' && typeof window.CustomEvent === 'function') {
+    window.dispatchEvent(new window.CustomEvent(RECONCILE_COLOR_MODE_EVENT))
+  }
+}

package/src/color-mode/spa-navigation.spec.js

@@ -0,0 +1,25 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import { reconcileThemeUiColorModeOnNavigation } from './spa-navigation.js'
+import { RECONCILE_COLOR_MODE_EVENT } from './constants.js'
+
+describe('reconcileThemeUiColorModeOnNavigation', () => {
+  beforeEach(() => {
+    window.localStorage.removeItem('theme-ui-color-mode')
+    document.documentElement.removeAttribute('data-theme-ui-color-mode')
+    document.documentElement.className = ''
+  })
+
+  it('syncs DOM from localStorage and dispatches reconcile event', () => {
+    window.localStorage.setItem('theme-ui-color-mode', 'dark')
+    const listener = jest.fn()
+    window.addEventListener(RECONCILE_COLOR_MODE_EVENT, listener)
+
+    reconcileThemeUiColorModeOnNavigation()
+
+    expect(document.documentElement.getAttribute('data-theme-ui-color-mode')).toBe('dark')
+    expect(listener).toHaveBeenCalled()
+  })
+})

package/src/color-mode/use-document-color-mode-surface.js

@@ -0,0 +1,52 @@
+'use client'
+
+import { useLayoutEffect } from 'react'
+import { useColorMode, useThemeUI } from 'theme-ui'
+
+import { resolveChronogroveSurfaceColors } from './resolve-theme-colors.js'
+
+/**
+ * Applies Theme UI color mode + page background to `document.documentElement`. Exposed for tests;
+ * prefer {@link useDocumentColorModeSurface} in app code.
+ */
+export function applyDocumentColorModeSurface(colorMode, theme, surface) {
+  if (typeof document === 'undefined') {
+    return
+  }
+  const normalizedColorMode = colorMode === 'light' ? 'default' : colorMode || 'default'
+  const isDark = normalizedColorMode === 'dark'
+  const bgColorRaw =
+    theme?.rawColors?.background ||
+    theme?.colors?.background ||
+    (isDark ? surface.darkBackgroundHex : surface.defaultBackgroundHex)
+  const htmlElement = document.documentElement
+  Array.from(htmlElement.classList)
+    .filter(className => className.startsWith('theme-ui-'))
+    .forEach(className => htmlElement.classList.remove(className))
+  htmlElement.classList.add(`theme-ui-${normalizedColorMode}`)
+  htmlElement.setAttribute('data-theme-ui-color-mode', normalizedColorMode)
+  htmlElement.style.backgroundColor = bgColorRaw
+}
+
+/**
+ * Keeps `document.documentElement` aligned with Theme UI color mode — same responsibility as
+ * `RootWrapper`’s layout effect in the Gatsby theme (`theme/src/components/root-wrapper.js`):
+ * `theme-ui-*` class, `data-theme-ui-color-mode`, and inline page background from the **resolved**
+ * theme (including `rawColors` / `colors.background` for the active mode).
+ *
+ * Without this on App Router, head fallback CSS and inline scripts can disagree with React
+ * hydration, and Emotion-injected `--theme-ui-colors-*` can win the cascade so panel surfaces
+ * (`bg: 'panel-background'`) never pick up dark tokens.
+ *
+ * Call once inside `ChronogroveThemeProvider` (client boundary). Optional on Gatsby if you
+ * already use the same hook from `RootWrapper`.
+ */
+export function useDocumentColorModeSurface() {
+  const [colorMode] = useColorMode()
+  const { theme } = useThemeUI()
+  const surface = resolveChronogroveSurfaceColors(theme)
+
+  useLayoutEffect(() => {
+    applyDocumentColorModeSurface(colorMode, theme, surface)
+  }, [colorMode, theme, surface.darkBackgroundHex, surface.defaultBackgroundHex])
+}

package/src/color-mode/use-document-color-mode-surface.node.spec.js

@@ -0,0 +1,12 @@
+/**
+ * @jest-environment node
+ */
+
+import { resolveChronogroveSurfaceColors } from './resolve-theme-colors.js'
+import { applyDocumentColorModeSurface } from './use-document-color-mode-surface.js'
+
+describe('applyDocumentColorModeSurface (node / no DOM)', () => {
+  it('returns immediately when document is not available', () => {
+    expect(applyDocumentColorModeSurface('default', {}, resolveChronogroveSurfaceColors({}))).toBeUndefined()
+  })
+})

package/src/color-mode/use-document-color-mode-surface.spec.js

@@ -0,0 +1,154 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import React from 'react'
+import { render, act } from '@testing-library/react'
+import { ThemeUIProvider } from 'theme-ui'
+
+import { resolveChronogroveSurfaceColors } from './resolve-theme-colors.js'
+import { applyDocumentColorModeSurface, useDocumentColorModeSurface } from './use-document-color-mode-surface.js'
+
+function SurfaceHarness() {
+  useDocumentColorModeSurface()
+  return null
+}
+
+const baseTheme = {
+  config: { useLocalStorage: true, useColorSchemeMediaQuery: false },
+  colors: {
+    background: '#fdf8f5',
+    modes: {
+      dark: { background: '#14141F' }
+    }
+  }
+}
+
+describe('useDocumentColorModeSurface', () => {
+  beforeEach(() => {
+    document.documentElement.className = 'theme-ui-stale'
+    document.documentElement.removeAttribute('data-theme-ui-color-mode')
+    document.documentElement.style.backgroundColor = ''
+    window.localStorage.removeItem('theme-ui-color-mode')
+  })
+
+  it('syncs documentElement class, data attribute, and background from resolved theme', () => {
+    window.localStorage.setItem('theme-ui-color-mode', 'default')
+
+    act(() => {
+      render(
+        <ThemeUIProvider theme={baseTheme}>
+          <SurfaceHarness />
+        </ThemeUIProvider>
+      )
+    })
+
+    expect(document.documentElement.classList.contains('theme-ui-stale')).toBe(false)
+    expect(document.documentElement.classList.contains('theme-ui-default')).toBe(true)
+    expect(document.documentElement.getAttribute('data-theme-ui-color-mode')).toBe('default')
+    expect(document.documentElement.style.backgroundColor).toBeTruthy()
+  })
+
+  it('maps light color mode to theme-ui-default', () => {
+    window.localStorage.setItem('theme-ui-color-mode', 'light')
+
+    act(() => {
+      render(
+        <ThemeUIProvider theme={baseTheme}>
+          <SurfaceHarness />
+        </ThemeUIProvider>
+      )
+    })
+
+    expect(document.documentElement.classList.contains('theme-ui-default')).toBe(true)
+    expect(document.documentElement.getAttribute('data-theme-ui-color-mode')).toBe('default')
+  })
+
+  it('applies dark surface when color mode is dark', () => {
+    window.localStorage.setItem('theme-ui-color-mode', 'dark')
+
+    act(() => {
+      render(
+        <ThemeUIProvider theme={baseTheme}>
+          <SurfaceHarness />
+        </ThemeUIProvider>
+      )
+    })
+
+    expect(document.documentElement.classList.contains('theme-ui-dark')).toBe(true)
+    expect(document.documentElement.getAttribute('data-theme-ui-color-mode')).toBe('dark')
+  })
+
+  it('prefers rawColors.background when set', () => {
+    window.localStorage.setItem('theme-ui-color-mode', 'default')
+    const theme = {
+      config: { useLocalStorage: true, useColorSchemeMediaQuery: false },
+      rawColors: { background: '#abcdef' },
+      colors: {
+        modes: {
+          dark: { background: '#14141F' }
+        }
+      }
+    }
+
+    act(() => {
+      render(
+        <ThemeUIProvider theme={theme}>
+          <SurfaceHarness />
+        </ThemeUIProvider>
+      )
+    })
+
+    expect(document.documentElement.style.backgroundColor).toBe('rgb(171, 205, 239)')
+  })
+
+  it('normalizes light and missing color modes when applying to the document', () => {
+    window.localStorage.setItem('theme-ui-color-mode', 'default')
+    document.documentElement.className = ''
+    act(() => {
+      applyDocumentColorModeSurface('light', baseTheme, resolveChronogroveSurfaceColors(baseTheme))
+    })
+    expect(document.documentElement.getAttribute('data-theme-ui-color-mode')).toBe('default')
+
+    document.documentElement.removeAttribute('data-theme-ui-color-mode')
+    act(() => {
+      applyDocumentColorModeSurface(undefined, baseTheme, resolveChronogroveSurfaceColors(baseTheme))
+    })
+    expect(document.documentElement.getAttribute('data-theme-ui-color-mode')).toBe('default')
+  })
+
+  it('prefers rawColors.background over colors.background', () => {
+    act(() => {
+      applyDocumentColorModeSurface(
+        'default',
+        { rawColors: { background: '#112233' }, colors: { background: '#eeeeee' } },
+        resolveChronogroveSurfaceColors({})
+      )
+    })
+    expect(document.documentElement.style.backgroundColor).toBe('rgb(17, 34, 51)')
+  })
+
+  it('uses colors.background when raw background is absent', () => {
+    act(() => {
+      applyDocumentColorModeSurface(
+        'default',
+        { colors: { background: '#00ff00' } },
+        resolveChronogroveSurfaceColors({})
+      )
+    })
+    expect(document.documentElement.style.backgroundColor).toBe('rgb(0, 255, 0)')
+  })
+
+  it('uses surface fallbacks when theme omits background colors', () => {
+    const surface = resolveChronogroveSurfaceColors(null)
+    act(() => {
+      applyDocumentColorModeSurface('default', null, surface)
+    })
+    expect(document.documentElement.style.backgroundColor).toBe('rgb(253, 248, 245)')
+
+    act(() => {
+      applyDocumentColorModeSurface('dark', null, surface)
+    })
+    expect(document.documentElement.style.backgroundColor).toBe('rgb(20, 20, 31)')
+  })
+})

package/src/color-toggle-styles.css

@@ -0,0 +1,10 @@
+/* Styles for `@chronogrove/ui/color-toggle` (`@theme-toggles/react` Expand). Import once in global CSS, e.g. `@import '@chronogrove/ui/color-toggle-styles';` */
+@import '@theme-toggles/react/css/Expand.css';
+
+.theme-toggle,
+.theme-toggle svg {
+  color: inherit;
+  fill: currentColor;
+  width: 16px;
+  height: 16px;
+}

package/src/color-toggle.js

@@ -1,16 +1,25 @@
-import React from 'react'
+import React, { useEffect } from 'react'
 import { useColorMode } from 'theme-ui'
 import { Expand } from '@theme-toggles/react'
-import isDarkMode from '@chronogrove/ui/is-dark-mode'
+import { scheduleThemeUiColorModeSync } from './color-mode/browser-sync.js'
+import isDarkMode from './helpers/isDarkMode.js'
 
 export default function ColorToggle() {
   const [colorMode, setColorMode] = useColorMode()
 
+  // Theme UI updates Emotion + localStorage on toggle but does not sync `document.documentElement`
+  // (`theme-ui-*` classes, `data-theme-ui-color-mode`). Chronogrove's head fallback CSS targets
+  // `:root[data-theme-ui-color-mode="..."]` with `!important` (see head-inline.js), so a stale
+  // attribute makes toggles appear to do nothing. Run after ancestor effects so localStorage matches.
+  useEffect(() => {
+    scheduleThemeUiColorModeSync()
+  }, [colorMode])
+
   return (
     <Expand
       className='theme-toggle'
       toggled={isDarkMode(colorMode)}
-      toggle={() => setColorMode(colorMode === 'default' ? 'dark' : 'default')}
+      toggle={preferDark => setColorMode(preferDark ? 'dark' : 'default')}
       duration={750}
       aria-label='Toggle color mode'
       id='theme-toggle'

package/src/emotion-cache.node.spec.js

@@ -0,0 +1,13 @@
+/**
+ * @jest-environment node
+ */
+
+describe('createChronogroveEmotionCache (node / no DOM)', () => {
+  it('creates a cache without a document insertion point', () => {
+    jest.isolateModules(() => {
+      const { createChronogroveEmotionCache } = require('./emotion-cache.js')
+      const cache = createChronogroveEmotionCache()
+      expect(cache.key).toBe('css')
+    })
+  })
+})

package/src/emotion-cache.spec.js

@@ -27,4 +27,16 @@ describe('getChronogroveEmotionCache', () => {
     })
     document.head.removeChild(meta)
   })
+
+  it('passes a real insertion point meta when present', () => {
+    const meta = document.createElement('meta')
+    meta.setAttribute('name', 'emotion-insertion-point')
+    document.head.appendChild(meta)
+    jest.isolateModules(() => {
+      const { createChronogroveEmotionCache } = require('./emotion-cache')
+      const cache = createChronogroveEmotionCache()
+      expect(cache).toBeTruthy()
+    })
+    document.head.removeChild(meta)
+  })
 })

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

@@ -22,10 +22,16 @@ export function buildThemeUiColorModeHeadComponents({ theme }) {
     darkBackgroundHex: surface.darkBackgroundHex
   })
   const colorModeFallbackCSS = buildThemeUiColorModeFallbackCss({
+    defaultBackgroundHex: surface.defaultBackgroundHex,
+    darkBackgroundHex: surface.darkBackgroundHex,
     defaultTextHex: surface.defaultTextHex,
     defaultTextMutedHex: surface.defaultTextMutedHex,
     darkTextHex: surface.darkTextHex,
-    darkTextMutedHex: surface.darkTextMutedHex
+    darkTextMutedHex: surface.darkTextMutedHex,
+    defaultPanelBackground: surface.defaultPanelBackground,
+    darkPanelBackground: surface.darkPanelBackground,
+    defaultPanelText: surface.defaultPanelText,
+    darkPanelText: surface.darkPanelText
   })
 
   return [

package/src/gatsby/index.spec.js

@@ -40,6 +40,8 @@ describe('@chronogrove/ui/gatsby', () => {
       const fallbackStyle = fallbackStyleContainer.querySelector('style')
       expect(fallbackStyle).toHaveTextContent(/:root\[data-theme-ui-color-mode="default"\]/)
       expect(fallbackStyle).toHaveTextContent(/--theme-ui-colors-text: #111 !important/)
+      expect(fallbackStyle).toHaveTextContent(/--theme-ui-colors-panel-background:/)
+      expect(fallbackStyle).toHaveTextContent(/--theme-ui-colors-panel-text:/)
     })
   })
 
@@ -100,6 +102,46 @@ describe('@chronogrove/ui/gatsby', () => {
       onPreRenderHTMLSortThemeUiColorModeFirst({ getHeadComponents, replaceHeadComponents })
       expect(replaceHeadComponents.mock.calls[0][0].map(c => c.key)).toEqual(['html-bg-color', 'theme-ui-no-flash'])
     })
+
+    it('treats missing component keys as empty string', () => {
+      const getHeadComponents = jest.fn(() => [{ type: 'meta' }, { key: 'theme-ui-no-flash', type: 'script' }])
+      const replaceHeadComponents = jest.fn()
+      onPreRenderHTMLSortThemeUiColorModeFirst({ getHeadComponents, replaceHeadComponents })
+      const sorted = replaceHeadComponents.mock.calls[0][0]
+      expect(sorted[0].key).toBe('theme-ui-no-flash')
+    })
+
+    it('handles null or undefined head entries when sorting', () => {
+      const getHeadComponents = jest.fn(() => [
+        null,
+        undefined,
+        { key: 'theme-ui-no-flash', type: 'script' },
+        { key: 'other', type: 'meta' }
+      ])
+      const replaceHeadComponents = jest.fn()
+      onPreRenderHTMLSortThemeUiColorModeFirst({ getHeadComponents, replaceHeadComponents })
+      const sorted = replaceHeadComponents.mock.calls[0][0]
+      expect(sorted[0].key).toBe('theme-ui-no-flash')
+    })
+
+    it('treats explicit null keys like missing keys', () => {
+      const getHeadComponents = jest.fn(() => [
+        { key: null, type: 'meta' },
+        { key: 'theme-ui-no-flash', type: 'script' }
+      ])
+      const replaceHeadComponents = jest.fn()
+      onPreRenderHTMLSortThemeUiColorModeFirst({ getHeadComponents, replaceHeadComponents })
+      const sorted = replaceHeadComponents.mock.calls[0][0]
+      expect(sorted[0].key).toBe('theme-ui-no-flash')
+    })
+
+    it('sorts when the right-hand entry is null', () => {
+      const getHeadComponents = jest.fn(() => [{ key: 'theme-ui-no-flash', type: 'script' }, null])
+      const replaceHeadComponents = jest.fn()
+      onPreRenderHTMLSortThemeUiColorModeFirst({ getHeadComponents, replaceHeadComponents })
+      const sorted = replaceHeadComponents.mock.calls[0][0]
+      expect(sorted[0].key).toBe('theme-ui-no-flash')
+    })
   })
 
   describe('onRouteUpdateThemeUiColorMode', () => {

package/src/gatsby/on-route-update-color-mode.js

@@ -1,14 +1 @@
-import { RECONCILE_COLOR_MODE_EVENT } from '../color-mode/constants.js'
-import { scheduleThemeUiColorModeSync } from '../color-mode/browser-sync.js'
-
-/**
- * Call from Gatsby `onRouteUpdate` so Theme UI color mode stays aligned with `localStorage` and the
- * document after client-side navigations. Dispatches {@link RECONCILE_COLOR_MODE_EVENT} for app code
- * that listens (e.g. React context reconciliation).
- */
-export function onRouteUpdateThemeUiColorMode() {
-  scheduleThemeUiColorModeSync()
-  if (typeof window !== 'undefined' && typeof window.CustomEvent === 'function') {
-    window.dispatchEvent(new window.CustomEvent(RECONCILE_COLOR_MODE_EVENT))
-  }
-}
+export { reconcileThemeUiColorModeOnNavigation as onRouteUpdateThemeUiColorMode } from '../color-mode/spa-navigation.js'

package/src/header.js

@@ -1,5 +1,4 @@
-/** @jsx jsx */
-import { jsx } from 'theme-ui'
+import { Box } from '@theme-ui/components'
 
 /**
  * Header
@@ -8,20 +7,9 @@ import { jsx } from 'theme-ui'
  */
 const Header = ({ children, styles }) => {
   return (
-    <header
-      role='banner'
-      sx={{
-        variant: 'styles.Header'
-      }}
-    >
-      <div
-        sx={{
-          ...(styles ? styles : {})
-        }}
-      >
-        {children}
-      </div>
-    </header>
+    <Box as='header' role='banner' sx={{ variant: 'styles.Header' }}>
+      <Box sx={{ ...(styles ? styles : {}) }}>{children}</Box>
+    </Box>
   )
 }
 

package/src/lazy-load.js

@@ -1,10 +1,9 @@
-/** @jsx jsx */
-import { jsx } from 'theme-ui'
 import { useState, useEffect } from 'react'
+import { Box } from '@theme-ui/components'
 import { useInView } from 'react-intersection-observer'
 
 const DefaultPlaceholder = ({ height = '100%', width = '100%' }) => (
-  <div
+  <Box
     data-testid='default-placeholder'
     sx={{
       minHeight: '1px',
@@ -14,28 +13,48 @@ const DefaultPlaceholder = ({ height = '100%', width = '100%' }) => (
     }}
   >
     {' '}
-  </div>
+  </Box>
 )
 
 /**
  * Lazy Loader
  *
  * Hides a component until it's been visible in the viewport.
+ *
+ * IntersectionObserver does not run on the server; children are never included in SSR HTML.
+ * On the client, observation is deferred until after mount so Next.js (and other SSR
+ * frameworks) hydrate the placeholder first, then attach the observer — avoiding a
+ * first-paint flash of real content when the block is already in view.
+ *
+ * @param {object} [props.useInViewOptions] -
+ *   Passed to `useInView` after defaults (`triggerOnce: true`, `threshold: 0`,
+ *   `initialInView: false`). Use `rootMargin` or `threshold` for stricter visibility.
+ *   Pass `skip` to disable observation (merged with the internal client-only `skip`).
  */
-const LazyLoad = ({ children, placeholder = <DefaultPlaceholder /> }) => {
-  const [hasBeenVisible, setHasBeenVisible] = useState(false)
+const LazyLoad = ({ children, placeholder = <DefaultPlaceholder />, useInViewOptions = {} }) => {
+  const [mounted, setMounted] = useState(false)
+  const [revealed, setRevealed] = useState(false)
+  const { skip: skipFromOptions, ...restInViewOptions } = useInViewOptions
+
   const { ref, inView } = useInView({
     triggerOnce: true,
-    threshold: 0
+    threshold: 0,
+    initialInView: false,
+    ...restInViewOptions,
+    skip: !mounted || !!skipFromOptions
   })
 
   useEffect(() => {
-    if (inView && !hasBeenVisible) {
-      setHasBeenVisible(true)
+    setMounted(true)
+  }, [])
+
+  useEffect(() => {
+    if (mounted && inView) {
+      setRevealed(true)
     }
-  }, [inView, hasBeenVisible])
+  }, [mounted, inView])
 
-  return <div ref={ref}>{hasBeenVisible ? children : placeholder}</div>
+  return <Box ref={ref}>{revealed ? children : placeholder}</Box>
 }
 
 export default LazyLoad