@chronogrove/ui 0.81.0 → 0.82.1

package/README.md

@@ -12,7 +12,7 @@ pnpm add @chronogrove/ui
 
 Use **`pnpm publish`** for releases so `workspace:` dependencies in dependents are rewritten; see [pnpm workspaces — publishing](https://pnpm.io/workspaces#publishing-workspace-packages).
 
-**Shared dependencies with `gatsby-theme-chronogrove`:** both packages depend on Theme UI, Emotion, and related libraries, with versions driven by the root [pnpm catalog](../../pnpm-workspace.yaml). When you bump those catalog entries, update **`packages/ui`** and **`theme`** in the **same change** so the theme and `@chronogrove/ui` stay aligned and you avoid duplicate or mismatched installs.
+**Shared dependencies with `gatsby-theme-chronogrove`:** both packages depend on Theme UI, Emotion, **`three`** (where WebGL backgrounds or artwork import it), and related libraries, with versions driven by the root [pnpm catalog](../../pnpm-workspace.yaml). When you bump those catalog entries, update **`packages/ui`**, **`theme`**, and any other workspace `package.json` files that reference `catalog:` for the same keys in the **same change** so installs stay aligned and you avoid duplicate or mismatched trees.
 
 ## Subpath exports
 
@@ -24,9 +24,8 @@ Prefer deep imports so bundles stay lean:
 | `@chronogrove/ui/theme`                    | Default Theme UI theme object + named exports                                                                                                                                                                                                                                                                                                    |
 | `@chronogrove/ui/provider`                 | `ChronogroveThemeProvider`                                                                                                                                                                                                                                                                                                                       |
 | `@chronogrove/ui/color-mode`               | Storage key, reconcile event, SSR inline builders, `chronogroveHeadTheme` (RSC-safe), `resolveChronogroveSurfaceColors`, `useDocumentColorModeSurface`, browser sync, `reconcileThemeUiColorModeOnNavigation`                                                                                                                                    |
-| `@chronogrove/ui/animated-page-background` | **`ChronogroveAnimatedPageBackground`** — same stack as the Gatsby home: fixed `z-index: 0`, light = solid theme background, dark = **three.js** Color Bends + scroll-linked gradient overlay and parallax (`three` is a dependency of this package). **Not** the same as `page-backdrop`.                                                       |
+| `@chronogrove/ui/animated-page-background` | **`ChronogroveAnimatedPageBackground`** — same stack as the Gatsby home: fixed `z-index: 0`, light = solid theme background, dark = **three.js** Color Bends + scroll-linked gradient overlay and parallax (`three` is a dependency of this package). Animation timing uses **`THREE.Timer`** (not deprecated `Clock`, three.js r183+).          |
 | `@chronogrove/ui/color-bends`              | **`ColorBends`** — lower-level three.js gradient background used inside `ChronogroveAnimatedPageBackground`. Prefer the full **`animated-page-background`** or **`@chronogrove/ui/next`** shell unless you need the raw component.                                                                                                               |
-| `@chronogrove/ui/page-backdrop`            | **`ChronogrovePageBackdrop`** — lightweight alternative: fixed `z-index: 0` fill without WebGL (CSS gradients in dark mode). Use when you cannot ship `three`.                                                                                                                                                                                   |
 | `@chronogrove/ui/next`                     | **Next.js App Router helpers:** `ChronogroveNextRootLayoutHead` (RSC `<head>` injections), `ChronogroveNextEmotionRegistry`, `ChronogroveNextAppShell` (theme + three.js background + surface sync + soft-nav reconcile), `ChronogroveNextThemeUiColorModeRouteSync` (standalone). Requires `next` (peer, optional for the rest of the package). |
 | `@chronogrove/ui/action-card-layout`       | **`actionCardPinnedLayoutSx`** — layout `sx` for `Card variant="actionCard"` (matches GitHub pinned cards).                                                                                                                                                                                                                                      |
 | `@chronogrove/ui/emotion-cache`            | `createChronogroveEmotionCache`, `getChronogroveEmotionCache`                                                                                                                                                                                                                                                                                    |
@@ -41,8 +40,12 @@ Prefer deep imports so bundles stay lean:
 | `@chronogrove/ui/lazy-load`                | Defer children until in viewport (`react-intersection-observer`)                                                                                                                                                                                                                                                                                 |
 | `@chronogrove/ui/header`                   | Masthead shell (`variant: styles.Header`)                                                                                                                                                                                                                                                                                                        |
 | `@chronogrove/ui/page-header`              | Blog-style `h1` heading (`p-name`)                                                                                                                                                                                                                                                                                                               |
+| `@chronogrove/ui/profile-metrics-badge`    | Metrics row (`Badge variant="metrics"`) for dashboard widget headers                                                                                                                                                                                                                                                                             |
+| `@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`**.
+
 ## Next.js (App Router)
 
 **Reference app:** [`examples/chronogrove-next`](../../examples/chronogrove-next) (`chronogrove-next`). Run `pnpm --filter chronogrove-next dev` from the repo root.
@@ -54,7 +57,9 @@ Prefer deep imports so bundles stay lean:
 - **Server `layout`:** Keep the root layout a Server Component. **Do not** import `@chronogrove/ui/theme` here—it loads `theme-ui`’s `merge` and triggers React `createContext`, which Next.js disallows in RSC. Use **`ChronogroveNextRootLayoutHead`** from `@chronogrove/ui/next`, or manually pass **`chronogroveHeadTheme`** from `@chronogrove/ui/color-mode` to `resolveChronogroveSurfaceColors` and emit **in order**: `<meta name="emotion-insertion-point" content="" />`, then the Theme UI no-flash script, HTML background script, and fallback CSS (same composition as [`buildThemeUiColorModeHeadComponents`](./src/gatsby/build-theme-ui-color-mode-head-components.js) in `@chronogrove/ui/gatsby`).
 - **Client Emotion registry + theme:** Use **`ChronogroveNextEmotionRegistry`** from `@chronogrove/ui/next`, or wrap the app in Emotion’s `CacheProvider` with a **per-request** cache with `key: 'css'` and Next’s `useServerInsertedHTML` ([Next.js: CSS-in-JS](https://nextjs.org/docs/app/building-your-application/styling/css-in-js)). **Do not** rely on `getChronogroveEmotionCache()` for SSR—it is a browser-oriented singleton. Import the **full** theme from `@chronogrove/ui/theme` only inside client components. Anything using `useColorMode`, `useThemeUI`, or `ChronogroveThemeProvider` must be `'use client'`. **Order:** `CacheProvider` (registry) **outside** `ChronogroveThemeProvider` **inside** `<body>`.
 - **Document surface (match Gatsby `RootWrapper`):** **`ChronogroveNextAppShell`** calls **`useDocumentColorModeSurface`** from `@chronogrove/ui/color-mode` once. It syncs `document.documentElement`’s `theme-ui-*` class, `data-theme-ui-color-mode`, and inline page background from the **resolved** Theme UI theme (`rawColors` / `colors.background`). Without it, Emotion can win the cascade over head fallback CSS and panel tokens (`bg: 'panel-background'`) may not update in dark mode after hydration.
-- **Animated page background (match Gatsby home):** **`ChronogroveNextAppShell`** includes **`ChronogroveAnimatedPageBackground`** (three.js Color Bends). For a **CSS-only** backdrop without `three`, use **`ChronogrovePageBackdrop`** from `@chronogrove/ui/page-backdrop` instead and compose your own shell. Content should sit in a **`position: relative; z-index: 1`** wrapper.
+- **Animated page background (match Gatsby home):** **`ChronogroveNextAppShell`** includes **`ChronogroveAnimatedPageBackground`** (three.js Color Bends). Content should sit in a **`position: relative; z-index: 1`** wrapper above the fixed background layer.
+- **`WidgetHeader` + icons:** This package depends on **`@fortawesome/fontawesome-svg-core`** and **`@fortawesome/react-fontawesome`**. Icon **definitions** (e.g. `faGithub`) come from a Font Awesome kit you add to **your** app—typically **`@fortawesome/free-brands-svg-icons`** for brands—the same pattern as **`gatsby-theme-chronogrove`** widgets.
+- **`MetricCard` loading state:** Pass **`loading`** or **`showPlaceholder`** (equivalent) for the built-in pulse placeholder (or **`loadingSlot`** to override).
 - **Soft navigations:** **`ChronogroveNextAppShell`** includes **`ChronogroveNextThemeUiColorModeRouteSync`**, which calls `reconcileThemeUiColorModeOnNavigation` after pathname changes (not on initial mount). Running reconcile on mount can fight `useColorMode` toggles. Gatsby’s equivalent is `onRouteUpdateThemeUiColorMode` (no initial `onRouteUpdate`).
 - **Hydration:** Set `suppressHydrationWarning` on `<html>` and `<body>`. The inline no-flash / background scripts run before React hydrates and update `<html>` (`theme-ui-*` classes, `data-theme-ui-color-mode`, background), so the DOM no longer matches the server-rendered markup—React would warn without this flag (similar to [next-themes](https://github.com/pacocoursey/next-themes) on Next.js App Router).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chronogrove/ui",
-  "version": "0.81.0",
+  "version": "0.82.1",
   "description": "Chronogrove Theme UI theme, color mode helpers, and shared UI primitives",
   "license": "MIT",
   "type": "module",
@@ -102,6 +102,10 @@
       "import": "./src/widget-call-to-action.js",
       "default": "./src/widget-call-to-action.js"
     },
+    "./widget-header": {
+      "import": "./src/widget-header.js",
+      "default": "./src/widget-header.js"
+    },
     "./lazy-load": {
       "import": "./src/lazy-load.js",
       "default": "./src/lazy-load.js"
@@ -118,9 +122,9 @@
       "import": "./src/page-header.js",
       "default": "./src/page-header.js"
     },
-    "./page-backdrop": {
-      "import": "./src/page-backdrop.js",
-      "default": "./src/page-backdrop.js"
+    "./profile-metrics-badge": {
+      "import": "./src/profile-metrics-badge.js",
+      "default": "./src/profile-metrics-badge.js"
     },
     "./animated-page-background": {
       "import": "./src/animated-page-background/index.js",
@@ -140,7 +144,7 @@
     }
   },
   "peerDependencies": {
-    "next": "^14.0.0 || ^15.0.0",
+    "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
@@ -152,6 +156,8 @@
   "dependencies": {
     "@emotion/cache": "^11.14.0",
     "@emotion/react": "^11.14.0",
+    "@fortawesome/fontawesome-svg-core": "^7.2.0",
+    "@fortawesome/react-fontawesome": "^3.3.0",
     "@theme-toggles/react": "^4.1.0",
     "@theme-ui/components": "^0.17.4",
     "@theme-ui/presets": "^0.17.4",
@@ -168,7 +174,7 @@
     "babel-jest": "^30.3.0",
     "jest": "^30.3.0",
     "jest-environment-jsdom": "^30.3.0",
-    "next": "^15.1.0",
+    "next": "^16.2.3",
     "react": "^19.2.5",
     "react-dom": "^19.2.5"
   },

package/src/__snapshots__/profile-metrics-badge.spec.js.snap

@@ -0,0 +1,20 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`ProfileMetricsBadge matches the snapshot with metrics 1`] = `
+<DocumentFragment>
+  <div
+    class="css-1182k7c"
+  >
+    <div
+      class="css-1njnxko"
+    >
+      10 Followers
+    </div>
+    <div
+      class="css-137c6l"
+    >
+      20 Following
+    </div>
+  </div>
+</DocumentFragment>
+`;

package/src/__snapshots__/widget-header.spec.js.snap

@@ -0,0 +1,33 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`WidgetHeader matches the snapshot 1`] = `
+<DocumentFragment>
+  <header
+    class="css-7pzsne"
+  >
+    <div
+      class="css-s076pz"
+    >
+      <h2
+        class="css-16f4ihe"
+      >
+        <span
+          class="css-2s41mq"
+        >
+          <span
+            aria-hidden="true"
+            data-icon="spotify"
+            data-testid="fa-icon"
+          />
+        </span>
+        Neat & Interesting Widget
+      </h2>
+      <div
+        class="sidebar-content"
+      >
+        Sidebar
+      </div>
+    </div>
+  </header>
+</DocumentFragment>
+`;

package/src/animated-page-background/ColorBends.js

@@ -178,7 +178,8 @@ export default function ColorBends({
 
     container.appendChild(renderer.domElement)
 
-    const clock = new THREE.Clock()
+    const timer = new THREE.Timer()
+    timer.connect(document)
 
     const handleResize = () => {
       const w = container.clientWidth || 1
@@ -197,9 +198,10 @@ export default function ColorBends({
       window.addEventListener('resize', handleResize)
     }
 
-    const loop = () => {
-      const dt = clock.getDelta()
-      const elapsed = clock.elapsedTime
+    const loop = time => {
+      timer.update(time)
+      const dt = timer.getDelta()
+      const elapsed = timer.getElapsed()
 
       material.uniforms.uTime.value = elapsed
 
@@ -222,6 +224,7 @@ export default function ColorBends({
     rafRef.current = requestAnimationFrame(loop)
 
     return () => {
+      timer.dispose()
       if (rafRef.current !== null) cancelAnimationFrame(rafRef.current)
       if (resizeObserverRef.current) resizeObserverRef.current.disconnect()
       else window.removeEventListener('resize', handleResize)

package/src/metric-card.js

@@ -6,13 +6,14 @@ 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).
+ * When `loading` or `showPlaceholder` is true, renders `loadingSlot` or a lightweight pulse placeholder (no react-placeholder dependency).
  */
-const MetricCard = ({ title, value, loading = false, loadingSlot, sx, ...props }) => {
+const MetricCard = ({ title, value, loading = false, showPlaceholder, loadingSlot, sx, ...props }) => {
   const { colorMode } = useThemeUI()
   const variant = isDarkMode(colorMode) ? 'metricCardDark' : 'metricCard'
+  const isLoading = Boolean(loading || showPlaceholder)
 
-  const body = loading ? (
+  const body = isLoading ? (
     (loadingSlot ?? (
       <Box
         aria-busy='true'

package/src/metric-card.spec.js

@@ -39,6 +39,15 @@ describe('MetricCard', () => {
     expect(screen.getByRole('status')).toBeInTheDocument()
   })
 
+  it('treats showPlaceholder as loading', () => {
+    render(
+      <ThemeUIProvider theme={theme}>
+        <MetricCard title='F' value='1' showPlaceholder />
+      </ThemeUIProvider>
+    )
+    expect(screen.getByRole('status')).toBeInTheDocument()
+  })
+
   it('uses metricCardDark when dark', () => {
     useThemeUI.mockReturnValue({ colorMode: 'dark' })
     render(

package/src/profile-metrics-badge.js

@@ -0,0 +1,32 @@
+import React from 'react'
+import { Badge, Box } from '@theme-ui/components'
+
+const ProfileMetricsBadge = ({ compact = false, isLoading, metrics = [] }) => {
+  let metricsToShow
+  if (isLoading) {
+    metricsToShow = [{}, {}]
+  } else if (Array.isArray(metrics)) {
+    metricsToShow = metrics
+  } else {
+    metricsToShow = []
+  }
+
+  return (
+    <Box
+      sx={{
+        fontFamily: 'heading',
+        ...(compact ? { mt: 0, pb: 0, pt: 0 } : { mt: 2, pb: 4, pt: 1 }),
+        display: 'flex',
+        justifyContent: ['center', 'unset']
+      }}
+    >
+      {metricsToShow.map(({ displayName, id, value }, idx) => (
+        <Badge key={id || idx} variant='metrics' ml={idx !== 0 && 2}>
+          {value} {displayName}
+        </Badge>
+      ))}
+    </Box>
+  )
+}
+
+export default ProfileMetricsBadge

package/src/profile-metrics-badge.spec.js

@@ -0,0 +1,89 @@
+import { render, screen } from '@testing-library/react'
+import { ThemeUIProvider } from 'theme-ui'
+
+import chronogroveTheme from './theme.js'
+import ProfileMetricsBadge from './profile-metrics-badge.js'
+
+describe('ProfileMetricsBadge', () => {
+  it('uses default props when none are passed', () => {
+    const { container } = render(
+      <ThemeUIProvider theme={chronogroveTheme}>
+        <ProfileMetricsBadge />
+      </ThemeUIProvider>
+    )
+    expect(container.firstChild).toBeInTheDocument()
+  })
+
+  it('matches the snapshot with metrics', () => {
+    const metrics = [
+      { displayName: 'Followers', id: 'followers', value: 10 },
+      { displayName: 'Following', id: 'following', value: 20 }
+    ]
+    const { asFragment } = render(
+      <ThemeUIProvider theme={chronogroveTheme}>
+        <ProfileMetricsBadge metrics={metrics} />
+      </ThemeUIProvider>
+    )
+    expect(asFragment()).toMatchSnapshot()
+  })
+
+  it('renders metrics with value and displayName', () => {
+    const metrics = [{ displayName: 'Friends', id: 'friends', value: 5 }]
+    render(
+      <ThemeUIProvider theme={chronogroveTheme}>
+        <ProfileMetricsBadge metrics={metrics} />
+      </ThemeUIProvider>
+    )
+    expect(screen.getByText('5 Friends')).toBeInTheDocument()
+  })
+
+  it('uses compact spacing when compact is true', () => {
+    const metrics = [{ displayName: 'Count', id: 'count', value: 1 }]
+    const { container } = render(
+      <ThemeUIProvider theme={chronogroveTheme}>
+        <ProfileMetricsBadge compact metrics={metrics} />
+      </ThemeUIProvider>
+    )
+    expect(container.firstChild).toBeInTheDocument()
+    expect(screen.getByText('1 Count')).toBeInTheDocument()
+  })
+
+  it('shows placeholder badges when isLoading', () => {
+    const { container } = render(
+      <ThemeUIProvider theme={chronogroveTheme}>
+        <ProfileMetricsBadge isLoading metrics={[]} />
+      </ThemeUIProvider>
+    )
+    const wrapper = container.querySelector('[class*="css-"]')
+    expect(wrapper).toBeInTheDocument()
+    expect(wrapper.children).toHaveLength(2)
+  })
+
+  it('handles non-array metrics with default empty array', () => {
+    const { container } = render(
+      <ThemeUIProvider theme={chronogroveTheme}>
+        <ProfileMetricsBadge metrics={null} />
+      </ThemeUIProvider>
+    )
+    expect(container.firstChild).toBeInTheDocument()
+  })
+
+  it('treats non-array metrics as empty when not loading', () => {
+    const { container } = render(
+      <ThemeUIProvider theme={chronogroveTheme}>
+        <ProfileMetricsBadge metrics='nope' />
+      </ThemeUIProvider>
+    )
+    expect(container.firstChild).toBeInTheDocument()
+    expect(container.textContent).toBe('')
+  })
+
+  it('renders nothing when metrics is an empty array', () => {
+    const { container } = render(
+      <ThemeUIProvider theme={chronogroveTheme}>
+        <ProfileMetricsBadge metrics={[]} />
+      </ThemeUIProvider>
+    )
+    expect(container.textContent).toBe('')
+  })
+})

package/src/widget-header.js

@@ -0,0 +1,93 @@
+import React from 'react'
+import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
+import { Box, Heading } from '@theme-ui/components'
+
+import ProfileMetricsBadge from './profile-metrics-badge.js'
+
+const baseHeaderStyles = {
+  display: 'flex',
+  flexDirection: ['column', 'row'],
+  alignItems: ['center', 'baseline'],
+  justifyContent: ['center', 'space-between'],
+  gap: [2, 3],
+  flexWrap: 'wrap',
+  pb: 2,
+  // Soft separator: visible but not harsh (gray[4] in theme scale; fallback ~12% black)
+  borderBottom: '1px solid',
+  borderColor: theme => theme?.colors?.gray?.[4] ?? 'rgba(0,0,0,0.12)'
+}
+
+/**
+ * Groups headline + CTA so they sit together on the left; metrics stay on the right.
+ * Always row so headline + CTA stay on one line at every breakpoint (including mobile).
+ */
+const titleGroupStyles = {
+  display: 'flex',
+  flexDirection: 'row',
+  alignItems: 'baseline',
+  gap: [1, 2],
+  order: 1
+}
+
+/**
+ * Override default heading margin, padding, and line-height so the headline and CTA
+ * align on the same baseline at every breakpoint. Theme/global styles often add
+ * vertical space to h2; zeroing it and using a tight line-height prevents offset.
+ * Baseline alignment for icon + text keeps the headline baseline consistent.
+ */
+const headingStyles = {
+  fontSize: [4, 5],
+  display: 'flex',
+  alignItems: 'baseline',
+  m: 0,
+  py: 0,
+  pt: 0,
+  pb: 0,
+  lineHeight: 1
+}
+
+const metricsStyles = {
+  order: 2
+}
+
+const WidgetHeader = ({ aside, children, icon, metrics, metricsLoading }) => {
+  const hasMetrics = (Array.isArray(metrics) && metrics.length > 0) || metricsLoading
+  return (
+    <Box
+      as='header'
+      sx={{
+        ...baseHeaderStyles,
+        // Extra margin below header when metrics are present so spacing matches Latest Posts (no metrics)
+        mb: hasMetrics ? 4 : 2
+      }}
+    >
+      <Box sx={titleGroupStyles}>
+        <Heading as='h2' sx={headingStyles}>
+          {icon && (
+            <Box
+              as='span'
+              sx={{
+                display: 'inline-flex',
+                alignItems: 'baseline',
+                mr: 2,
+                fontSize: 4,
+                '& svg': { width: '1em', height: '1em' }
+              }}
+            >
+              <FontAwesomeIcon icon={icon} aria-hidden='true' />
+            </Box>
+          )}
+          {children}
+        </Heading>
+        {aside}
+      </Box>
+      {((Array.isArray(metrics) && metrics.length > 0) || metricsLoading) && (
+        <Box sx={metricsStyles}>
+          <ProfileMetricsBadge compact isLoading={metricsLoading} metrics={metrics} />
+        </Box>
+      )}
+    </Box>
+  )
+}
+
+export default WidgetHeader

package/src/widget-header.spec.js

@@ -0,0 +1,76 @@
+import React from 'react'
+import { render, screen } from '@testing-library/react'
+import { ThemeUIProvider } from 'theme-ui'
+
+import chronogroveTheme from './theme.js'
+import WidgetHeader from './widget-header.js'
+
+jest.mock('@fortawesome/react-fontawesome', () => ({
+  FontAwesomeIcon: ({ icon }) => <span data-testid='fa-icon' data-icon={icon?.iconName ?? ''} aria-hidden />
+}))
+
+const aside = <div className='sidebar-content'>Sidebar</div>
+const mockIcon = { iconName: 'spotify', prefix: 'fab' }
+
+describe('WidgetHeader', () => {
+  it('matches the snapshot', () => {
+    const widgetTitle = 'Neat & Interesting Widget'
+    const { asFragment } = render(
+      <ThemeUIProvider theme={chronogroveTheme}>
+        <WidgetHeader aside={aside} icon={mockIcon}>
+          {widgetTitle}
+        </WidgetHeader>
+      </ThemeUIProvider>
+    )
+    expect(asFragment()).toMatchSnapshot()
+  })
+
+  it('renders metrics row when metrics are provided', () => {
+    const metrics = [{ displayName: 'Stars', id: 's', value: 12 }]
+    const { getByText } = render(
+      <ThemeUIProvider theme={chronogroveTheme}>
+        <WidgetHeader metrics={metrics}>Title</WidgetHeader>
+      </ThemeUIProvider>
+    )
+    expect(getByText('12 Stars')).toBeInTheDocument()
+  })
+
+  it('renders loading metrics placeholders when metricsLoading', () => {
+    const { container } = render(
+      <ThemeUIProvider theme={chronogroveTheme}>
+        <WidgetHeader metrics={[]} metricsLoading>
+          Title
+        </WidgetHeader>
+      </ThemeUIProvider>
+    )
+    const badges = container.querySelectorAll('[class*="css-"]')
+    expect(badges.length).toBeGreaterThan(0)
+  })
+
+  it('renders without icon', () => {
+    render(
+      <ThemeUIProvider theme={chronogroveTheme}>
+        <WidgetHeader aside={aside}>No icon</WidgetHeader>
+      </ThemeUIProvider>
+    )
+    expect(screen.getByText('No icon')).toBeInTheDocument()
+    expect(screen.queryByTestId('fa-icon')).not.toBeInTheDocument()
+  })
+
+  it('uses borderColor fallback when gray[4] is missing', () => {
+    const themeMissingGray4 = {
+      ...chronogroveTheme,
+      colors: {
+        ...chronogroveTheme.colors,
+        gray: { 0: '#111', 1: '#222', 2: '#333', 3: '#444' }
+      }
+    }
+    const { container } = render(
+      <ThemeUIProvider theme={themeMissingGray4}>
+        <WidgetHeader>Border test</WidgetHeader>
+      </ThemeUIProvider>
+    )
+    expect(container.querySelector('header')).toBeTruthy()
+    expect(screen.getByText('Border test')).toBeInTheDocument()
+  })
+})

package/src/page-backdrop.js

@@ -1,42 +0,0 @@
-'use client'
-
-import { Box } from '@theme-ui/components'
-import { useColorMode } from 'theme-ui'
-
-import isDarkMode from './helpers/isDarkMode.js'
-
-/**
- * Fixed viewport layer behind page content (`z-index: 0`), matching the role of
- * `AnimatedPageBackground` on the Gatsby home: a real surface under `z-index: 1` UI so
- * frosted panels (`backdrop-filter` + `panel-background`) have something to blur and tint
- * against. The full site uses WebGL Color Bends there; this package ships a **lightweight**
- * CSS gradient treatment only (no three.js).
- */
-export function ChronogrovePageBackdrop() {
-  const [colorMode] = useColorMode()
-  const dark = isDarkMode(colorMode)
-
-  return (
-    <Box
-      aria-hidden
-      sx={{
-        position: 'fixed',
-        inset: 0,
-        width: '100vw',
-        minHeight: '100vh',
-        zIndex: 0,
-        pointerEvents: 'none',
-        bg: 'background',
-        // Dark: subtle primary/secondary glows — same intent as Color Bends, fraction of the cost.
-        backgroundImage: dark
-          ? `
-            radial-gradient(ellipse 120% 85% at 50% -15%, rgba(74, 158, 255, 0.16) 0%, transparent 52%),
-            radial-gradient(ellipse 90% 70% at 95% 85%, rgba(113, 30, 155, 0.12) 0%, transparent 48%),
-            radial-gradient(ellipse 70% 50% at 10% 60%, rgba(128, 0, 128, 0.08) 0%, transparent 45%)
-          `
-          : 'none',
-        transition: 'background-image 0.3s ease'
-      }}
-    />
-  )
-}

package/src/page-backdrop.spec.js

@@ -1,41 +0,0 @@
-/**
- * @jest-environment jsdom
- */
-import React from 'react'
-import { render } from '@testing-library/react'
-import { ThemeUIProvider } from 'theme-ui'
-
-import chronogroveTheme from './theme.js'
-import { ChronogrovePageBackdrop } from './page-backdrop.js'
-
-describe('ChronogrovePageBackdrop', () => {
-  beforeEach(() => {
-    window.localStorage.removeItem('theme-ui-color-mode')
-  })
-
-  it('renders a fixed backdrop layer', () => {
-    const { container } = render(
-      <ThemeUIProvider theme={chronogroveTheme}>
-        <ChronogrovePageBackdrop />
-      </ThemeUIProvider>
-    )
-    const layer = container.querySelector('[aria-hidden="true"]')
-    expect(layer).toBeTruthy()
-  })
-
-  it('adds gradient overlays in dark mode', () => {
-    window.localStorage.setItem('theme-ui-color-mode', 'dark')
-    const { container } = render(
-      <ThemeUIProvider
-        theme={{
-          ...chronogroveTheme,
-          config: { useLocalStorage: true, useColorSchemeMediaQuery: false }
-        }}
-      >
-        <ChronogrovePageBackdrop />
-      </ThemeUIProvider>
-    )
-    const layer = container.querySelector('[aria-hidden="true"]')
-    expect(window.getComputedStyle(layer).backgroundImage).toMatch(/radial-gradient/)
-  })
-})