@chronogrove/ui 0.79.0 → 0.81.0

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

package/src/lazy-load.spec.js

@@ -1,5 +1,5 @@
 import React from 'react'
-import { render, screen } from '@testing-library/react'
+import { render, screen, waitFor } from '@testing-library/react'
 import '@testing-library/jest-dom'
 import LazyLoad from './lazy-load.js'
 
@@ -31,7 +31,7 @@ describe('LazyLoad', () => {
     expect(screen.queryByTestId('content')).not.toBeInTheDocument()
   })
 
-  it('renders the children when visible', () => {
+  it('renders the children when visible', async () => {
     mockInView = true
 
     render(
@@ -40,7 +40,9 @@ describe('LazyLoad', () => {
       </LazyLoad>
     )
 
-    expect(screen.getByTestId('content')).toBeInTheDocument()
+    await waitFor(() => {
+      expect(screen.getByTestId('content')).toBeInTheDocument()
+    })
   })
 
   it('renders the custom placeholder when provided', () => {
@@ -54,7 +56,7 @@ describe('LazyLoad', () => {
     expect(screen.queryByTestId('content')).not.toBeInTheDocument()
   })
 
-  it('does not re-render children if already visible', () => {
+  it('does not re-render children if already visible', async () => {
     mockInView = true
 
     const { rerender } = render(
@@ -63,7 +65,9 @@ describe('LazyLoad', () => {
       </LazyLoad>
     )
 
-    expect(screen.getByTestId('content')).toBeInTheDocument()
+    await waitFor(() => {
+      expect(screen.getByTestId('content')).toBeInTheDocument()
+    })
 
     mockInView = false
 

package/src/metric-badge.js

@@ -0,0 +1,10 @@
+import React from 'react'
+import { Badge } from '@theme-ui/components'
+
+const MetricBadge = ({ children, ...props }) => (
+  <Badge mr={3} {...props}>
+    {children}
+  </Badge>
+)
+
+export default MetricBadge

package/src/metric-badge.spec.js

@@ -0,0 +1,15 @@
+import { render, screen } from '@testing-library/react'
+import { ThemeUIProvider } from 'theme-ui'
+
+import MetricBadge from './metric-badge.js'
+
+describe('MetricBadge', () => {
+  it('renders children', () => {
+    render(
+      <ThemeUIProvider theme={{}}>
+        <MetricBadge>42</MetricBadge>
+      </ThemeUIProvider>
+    )
+    expect(screen.getByText('42')).toBeInTheDocument()
+  })
+})

package/src/metric-card.js

@@ -0,0 +1,95 @@
+import React from 'react'
+import { Box, Card, Text } from '@theme-ui/components'
+import { useThemeUI } from 'theme-ui'
+
+import isDarkMode from './helpers/isDarkMode.js'
+
+/**
+ * Metric summary card (e.g. Goodreads profile metrics). Uses `metricCard` / `metricCardDark` card variants.
+ * When `loading` is true, renders `loadingSlot` or a lightweight pulse placeholder (no react-placeholder dependency).
+ */
+const MetricCard = ({ title, value, loading = false, loadingSlot, sx, ...props }) => {
+  const { colorMode } = useThemeUI()
+  const variant = isDarkMode(colorMode) ? 'metricCardDark' : 'metricCard'
+
+  const body = loading ? (
+    (loadingSlot ?? (
+      <Box
+        aria-busy='true'
+        role='status'
+        sx={{
+          minHeight: '3rem',
+          borderRadius: 'default',
+          bg: 'muted',
+          opacity: 0.7,
+          animation: 'cgPulse 1.2s ease-in-out infinite',
+          '@keyframes cgPulse': {
+            '0%, 100%': { opacity: 0.45 },
+            '50%': { opacity: 0.85 }
+          }
+        }}
+      />
+    ))
+  ) : (
+    <Box
+      sx={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 1,
+        alignItems: 'center',
+        justifyContent: 'center',
+        textAlign: 'center',
+        minWidth: 0,
+        width: '100%'
+      }}
+    >
+      <Text
+        as='span'
+        sx={{
+          fontFamily: 'heading',
+          fontWeight: 'bold',
+          fontSize: [4, 5],
+          lineHeight: 1.1,
+          color: 'text',
+          m: 0,
+          letterSpacing: '-0.02em'
+        }}
+      >
+        {value}
+      </Text>
+      <Text
+        as='span'
+        sx={{
+          fontSize: 0,
+          color: 'textMuted',
+          lineHeight: 1.35,
+          m: 0,
+          textTransform: 'uppercase',
+          letterSpacing: '0.06em',
+          fontWeight: 'medium'
+        }}
+      >
+        {title}
+      </Text>
+    </Box>
+  )
+
+  return (
+    <Card
+      variant={variant}
+      sx={{
+        display: 'flex',
+        alignItems: 'stretch',
+        justifyContent: 'center',
+        minHeight: '6rem',
+        py: 3,
+        ...sx
+      }}
+      {...props}
+    >
+      {body}
+    </Card>
+  )
+}
+
+export default MetricCard

package/src/metric-card.spec.js

@@ -0,0 +1,60 @@
+import { render, screen } from '@testing-library/react'
+import { ThemeUIProvider } from 'theme-ui'
+
+import MetricCard from './metric-card.js'
+
+jest.mock('theme-ui', () => {
+  const actual = jest.requireActual('theme-ui')
+  return {
+    ...actual,
+    useThemeUI: jest.fn(() => ({ colorMode: 'default' }))
+  }
+})
+
+const { useThemeUI } = require('theme-ui')
+
+const theme = { colors: { modes: { dark: {} } } }
+
+describe('MetricCard', () => {
+  beforeEach(() => {
+    useThemeUI.mockReturnValue({ colorMode: 'default' })
+  })
+
+  it('renders value and title when not loading', () => {
+    render(
+      <ThemeUIProvider theme={theme}>
+        <MetricCard title='Followers' value='12' />
+      </ThemeUIProvider>
+    )
+    expect(screen.getByText('12')).toBeInTheDocument()
+    expect(screen.getByText('Followers')).toBeInTheDocument()
+  })
+
+  it('shows default loading placeholder when loading', () => {
+    render(
+      <ThemeUIProvider theme={theme}>
+        <MetricCard title='F' value='1' loading />
+      </ThemeUIProvider>
+    )
+    expect(screen.getByRole('status')).toBeInTheDocument()
+  })
+
+  it('uses metricCardDark when dark', () => {
+    useThemeUI.mockReturnValue({ colorMode: 'dark' })
+    render(
+      <ThemeUIProvider theme={theme}>
+        <MetricCard title='T' value='v' loading={false} />
+      </ThemeUIProvider>
+    )
+    expect(screen.getByText('v')).toBeInTheDocument()
+  })
+
+  it('uses custom loadingSlot', () => {
+    render(
+      <ThemeUIProvider theme={theme}>
+        <MetricCard title='t' value='v' loading loadingSlot={<span data-testid='slot'>wait</span>} />
+      </ThemeUIProvider>
+    )
+    expect(screen.getByTestId('slot')).toBeInTheDocument()
+  })
+})

package/src/muted-card-footer.js

@@ -0,0 +1,22 @@
+import React from 'react'
+import { Box } from '@theme-ui/components'
+
+/**
+ * Muted footer row for dashboard-style cards. Uses `styles.mutedCardFooter` on the theme.
+ */
+const MutedCardFooter = ({ children, customStyles, ...props }) => (
+  <Box
+    sx={{
+      variant: 'styles.mutedCardFooter',
+      color: 'textMuted',
+      fontFamily: 'sans',
+      fontSize: 1,
+      ...(typeof customStyles === 'object' && customStyles !== null ? customStyles : {})
+    }}
+    {...props}
+  >
+    {children}
+  </Box>
+)
+
+export default MutedCardFooter

package/src/muted-card-footer.spec.js

@@ -0,0 +1,25 @@
+import { render, screen } from '@testing-library/react'
+import { ThemeUIProvider } from 'theme-ui'
+
+import MutedCardFooter from './muted-card-footer.js'
+
+const theme = { styles: { mutedCardFooter: { mt: 2 } } }
+
+const wrap = ui => render(<ThemeUIProvider theme={theme}>{ui}</ThemeUIProvider>)
+
+describe('MutedCardFooter', () => {
+  it('renders children', () => {
+    wrap(<MutedCardFooter>Footer text</MutedCardFooter>)
+    expect(screen.getByText('Footer text')).toBeInTheDocument()
+  })
+
+  it('merges customStyles when an object', () => {
+    wrap(<MutedCardFooter customStyles={{ mt: 4 }}>A</MutedCardFooter>)
+    expect(screen.getByText('A')).toBeInTheDocument()
+  })
+
+  it('ignores non-object customStyles', () => {
+    wrap(<MutedCardFooter customStyles='invalid'>B</MutedCardFooter>)
+    expect(screen.getByText('B')).toBeInTheDocument()
+  })
+})

package/src/next/app-shell.js

@@ -0,0 +1,34 @@
+'use client'
+
+import { Box } from '@theme-ui/components'
+
+import { ChronogroveAnimatedPageBackground } from '../animated-page-background/index.js'
+import { useDocumentColorModeSurface } from '../color-mode/index.js'
+import { ChronogroveThemeProvider } from '../provider.js'
+import chronogroveTheme from '../theme.js'
+
+import { ChronogroveNextThemeUiColorModeRouteSync } from './theme-ui-color-mode-route-sync.js'
+
+/** Mirrors Gatsby `RootWrapper`: sync html class, data attribute, and surface bg from the live theme. */
+function DocumentColorModeSurface() {
+  useDocumentColorModeSurface()
+  return null
+}
+
+/**
+ * Default Next.js App Router shell: Theme UI provider, three.js Color Bends background (same as
+ * Gatsby home), document surface sync, and soft-navigation color-mode reconcile. Wrap with
+ * {@link ChronogroveNextEmotionRegistry} in `layout.jsx` outside this component.
+ */
+export function ChronogroveNextAppShell({ children, theme = chronogroveTheme }) {
+  return (
+    <ChronogroveThemeProvider theme={theme}>
+      <ChronogroveAnimatedPageBackground />
+      <DocumentColorModeSurface />
+      <Box sx={{ position: 'relative', zIndex: 1, bg: 'transparent', color: 'text' }}>
+        <ChronogroveNextThemeUiColorModeRouteSync />
+        {children}
+      </Box>
+    </ChronogroveThemeProvider>
+  )
+}

package/src/next/emotion-registry.js

@@ -0,0 +1,68 @@
+'use client'
+
+import * as React from 'react'
+import { CacheProvider } from '@emotion/react'
+import createCache from '@emotion/cache'
+import { useServerInsertedHTML } from 'next/navigation'
+
+/**
+ * Emotion cache for Next.js App Router: streaming SSR via `useServerInsertedHTML`, key `css`
+ * to match Theme UI / Chronogrove.
+ *
+ * Intercepts `cache.insert` and flushes only *new* rule names on each `useServerInsertedHTML`
+ * invocation. Do **not** use `Object.keys(cache.inserted)` (or similar) in the hook body — that
+ * re-emits every rule on every chunk during streaming SSR. Here, `flush()` drains a per-request
+ * queue so each rule is serialized once; `cache.inserted` stays as Emotion’s dedupe store.
+ *
+ * Next.js **pushes** a new callback from every render (`serverInsertedHTMLCallbacks.push`); all
+ * closures call the same `flush`, so only the first callback in a flush pass drains pending names.
+ *
+ * @see https://github.com/emotion-js/emotion/issues/2928
+ *
+ * @see https://nextjs.org/docs/app/building-your-application/styling/css-in-js
+ */
+export function ChronogroveNextEmotionRegistry({ children }) {
+  const [{ cache, flush }] = React.useState(() => {
+    const c = createCache({ key: 'css' })
+    c.compat = true
+    const prevInsert = c.insert
+    let pendingNames = []
+    c.insert = (...args) => {
+      const serialized = args[1]
+      if (serialized != null && c.inserted[serialized.name] === undefined) {
+        pendingNames.push(serialized.name)
+      }
+      return prevInsert(...args)
+    }
+    const flush = () => {
+      const names = pendingNames
+      pendingNames = []
+      return names
+    }
+    return { cache: c, flush }
+  })
+
+  useServerInsertedHTML(() => {
+    const names = flush()
+    if (names.length === 0) {
+      return null
+    }
+    let styles = ''
+    for (const name of names) {
+      const inserted = cache.inserted[name]
+      // `inserted` can be `true` for Global/keyframes when rules are already in a sheet (Next.js + Emotion pattern).
+      if (typeof inserted === 'string') {
+        styles += inserted
+      }
+    }
+    return (
+      <style
+        key={cache.key}
+        data-emotion={`${cache.key} ${names.join(' ')}`}
+        dangerouslySetInnerHTML={{ __html: styles }}
+      />
+    )
+  })
+
+  return <CacheProvider value={cache}>{children}</CacheProvider>
+}

package/src/next/emotion-registry.spec.js

@@ -0,0 +1,99 @@
+/**
+ * @jest-environment jsdom
+ */
+
+jest.mock('next/navigation', () => ({
+  useServerInsertedHTML: jest.fn()
+}))
+
+import React from 'react'
+import { render } from '@testing-library/react'
+import { Global, css } from '@emotion/react'
+import { useServerInsertedHTML } from 'next/navigation'
+
+import { ChronogroveNextEmotionRegistry } from './emotion-registry.js'
+
+/** `className={css({...})}` does not always hit `cache.insert` in Jest/jsdom; `Global` does. */
+function EmotionChild({ color }) {
+  return (
+    <Global
+      styles={css`
+        body {
+          color: ${color};
+        }
+      `}
+    />
+  )
+}
+
+describe('ChronogroveNextEmotionRegistry', () => {
+  let flushCallbacks
+
+  beforeEach(() => {
+    flushCallbacks = []
+    useServerInsertedHTML.mockImplementation(cb => {
+      flushCallbacks.push(cb)
+    })
+  })
+
+  it('flushes only new insertions per useServerInsertedHTML call (avoids duplicate style tags when streaming)', () => {
+    const { rerender } = render(
+      <ChronogroveNextEmotionRegistry>
+        <EmotionChild color='tomato' />
+      </ChronogroveNextEmotionRegistry>
+    )
+
+    const first = flushCallbacks[flushCallbacks.length - 1]()
+    expect(first).not.toBeNull()
+    // `cache.inserted[id]` can be `true` for Global in jsdom; must not stringify to invalid CSS.
+    expect(first.props.dangerouslySetInnerHTML.__html).not.toMatch(/^true+$/)
+
+    expect(flushCallbacks[flushCallbacks.length - 1]()).toBeNull()
+
+    rerender(
+      <ChronogroveNextEmotionRegistry>
+        <EmotionChild color='steelblue' />
+      </ChronogroveNextEmotionRegistry>
+    )
+
+    const afterNewRules = flushCallbacks[flushCallbacks.length - 1]()
+    expect(afterNewRules).not.toBeNull()
+    expect(flushCallbacks[flushCallbacks.length - 1]()).toBeNull()
+  })
+
+  /**
+   * Next.js registers `useServerInsertedHTML` once per render (`push` onto an array). All handlers
+   * share one `flush`; only the first invocation per drain should emit — not N copies of the full
+   * `cache.inserted` map.
+   */
+  it('drains pending styles once when multiple handlers run (matches Next.js callback stacking)', () => {
+    const { rerender } = render(
+      <ChronogroveNextEmotionRegistry>
+        <EmotionChild color='tomato' />
+      </ChronogroveNextEmotionRegistry>
+    )
+
+    expect(flushCallbacks).toHaveLength(1)
+
+    rerender(
+      <ChronogroveNextEmotionRegistry>
+        <EmotionChild color='tomato' />
+      </ChronogroveNextEmotionRegistry>
+    )
+    rerender(
+      <ChronogroveNextEmotionRegistry>
+        <EmotionChild color='tomato' />
+      </ChronogroveNextEmotionRegistry>
+    )
+
+    expect(flushCallbacks).toHaveLength(3)
+
+    const html0 = flushCallbacks[0]()
+    const html1 = flushCallbacks[1]()
+    const html2 = flushCallbacks[2]()
+
+    expect(html0).not.toBeNull()
+    expect(html1).toBeNull()
+    expect(html2).toBeNull()
+  })
+})

package/src/next/index.js

@@ -0,0 +1,4 @@
+export { ChronogroveNextAppShell } from './app-shell.js'
+export { ChronogroveNextEmotionRegistry } from './emotion-registry.js'
+export { ChronogroveNextRootLayoutHead } from './root-layout-head.js'
+export { ChronogroveNextThemeUiColorModeRouteSync } from './theme-ui-color-mode-route-sync.js'