@chronogrove/ui 0.77.0 → 0.78.0

package/README.md

@@ -16,17 +16,24 @@ Use **`pnpm publish`** for releases so `workspace:` dependencies in dependents a
 
 Prefer deep imports so bundles stay lean:
 
-| Import path                     | Contents                                                                                           |
-| ------------------------------- | -------------------------------------------------------------------------------------------------- |
-| `@chronogrove/ui`               | `ChronogroveThemeProvider`                                                                         |
-| `@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, `resolveChronogroveSurfaceColors`, browser sync |
-| `@chronogrove/ui/emotion-cache` | `createChronogroveEmotionCache`, `getChronogroveEmotionCache`                                      |
-| `@chronogrove/ui/button`        | Theme UI `components` button                                                                       |
-| `@chronogrove/ui/color-toggle`  | Theme UI + `@theme-toggles/react` toggle                                                           |
-| `@chronogrove/ui/skip-nav`      | `SkipNavLink`, `SkipNavContent`                                                                    |
-| `@chronogrove/ui/is-dark-mode`  | `colorMode === 'dark'` helper                                                                      |
+| Import path                         | Contents                                                                                           |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `@chronogrove/ui`                   | `ChronogroveThemeProvider`                                                                         |
+| `@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, `resolveChronogroveSurfaceColors`, browser sync |
+| `@chronogrove/ui/emotion-cache`     | `createChronogroveEmotionCache`, `getChronogroveEmotionCache`                                      |
+| `@chronogrove/ui/button`            | Theme UI `components` button                                                                       |
+| `@chronogrove/ui/color-toggle`      | Theme UI + `@theme-toggles/react` toggle                                                           |
+| `@chronogrove/ui/skip-nav`          | `SkipNavLink`, `SkipNavContent`                                                                    |
+| `@chronogrove/ui/is-dark-mode`      | `colorMode === 'dark'` helper                                                                      |
+| `@chronogrove/ui/color-utils`       | `hexToRgb`, `hexToRgba`, `BUTTON_PRIMARY_COLORS`                                                   |
+| `@chronogrove/ui/action-button`     | Outline CTA as `<button>` or `<a>`                                                                 |
+| `@chronogrove/ui/pagination-button` | Compact paginator control                                                                          |
+| `@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/gatsby`            | Color-mode Gatsby SSR/browser helpers                                                              |
 
 ## Next.js (App Router)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chronogrove/ui",
-  "version": "0.77.0",
+  "version": "0.78.0",
   "description": "Chronogrove Theme UI theme, color mode helpers, and shared UI primitives",
   "license": "MIT",
   "repository": {
@@ -46,6 +46,30 @@
       "import": "./src/helpers/isDarkMode.js",
       "default": "./src/helpers/isDarkMode.js"
     },
+    "./color-utils": {
+      "import": "./src/color-utils.js",
+      "default": "./src/color-utils.js"
+    },
+    "./action-button": {
+      "import": "./src/action-button.js",
+      "default": "./src/action-button.js"
+    },
+    "./pagination-button": {
+      "import": "./src/pagination-button.js",
+      "default": "./src/pagination-button.js"
+    },
+    "./lazy-load": {
+      "import": "./src/lazy-load.js",
+      "default": "./src/lazy-load.js"
+    },
+    "./header": {
+      "import": "./src/header.js",
+      "default": "./src/header.js"
+    },
+    "./page-header": {
+      "import": "./src/page-header.js",
+      "default": "./src/page-header.js"
+    },
     "./gatsby": {
       "import": "./src/gatsby/index.js",
       "default": "./src/gatsby/index.js"
@@ -61,6 +85,7 @@
     "@theme-toggles/react": "^4.1.0",
     "@theme-ui/components": "^0.17.4",
     "@theme-ui/presets": "^0.17.4",
+    "react-intersection-observer": "^10.0.3",
     "theme-ui": "^0.17.4"
   },
   "devDependencies": {

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

@@ -0,0 +1,69 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`Header renders with children 1`] = `
+<DocumentFragment>
+  <header
+    class="css-1u8qly9"
+    role="banner"
+  >
+    <div
+      class="css-1u8qly9"
+    >
+      <h1>
+        Test Header
+      </h1>
+    </div>
+  </header>
+</DocumentFragment>
+`;
+
+exports[`Header renders with custom styles 1`] = `
+<DocumentFragment>
+  <header
+    class="css-1u8qly9"
+    role="banner"
+  >
+    <div
+      class="css-10n8us"
+    >
+      <h1>
+        Test Header with Styles
+      </h1>
+    </div>
+  </header>
+</DocumentFragment>
+`;
+
+exports[`Header renders with empty styles object 1`] = `
+<DocumentFragment>
+  <header
+    class="css-1u8qly9"
+    role="banner"
+  >
+    <div
+      class="css-1u8qly9"
+    >
+      <h1>
+        Test Header with Empty Styles
+      </h1>
+    </div>
+  </header>
+</DocumentFragment>
+`;
+
+exports[`Header renders without styles prop 1`] = `
+<DocumentFragment>
+  <header
+    class="css-1u8qly9"
+    role="banner"
+  >
+    <div
+      class="css-1u8qly9"
+    >
+      <h1>
+        Test Header without Styles
+      </h1>
+    </div>
+  </header>
+</DocumentFragment>
+`;

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

@@ -0,0 +1,11 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`PageHeader matches snapshot 1`] = `
+<DocumentFragment>
+  <h1
+    class="p-name css-1sus4jf"
+  >
+    Hello, World!
+  </h1>
+</DocumentFragment>
+`;

package/src/action-button.js

@@ -0,0 +1,83 @@
+/** @jsx jsx */
+import React from 'react'
+import { jsx, useThemeUI } from 'theme-ui'
+import isDarkMode from './helpers/isDarkMode.js'
+import { hexToRgb } from './color-utils.js'
+
+const ActionButton = ({ children, href, onClick, variant = 'primary', size = 'medium', icon, ...props }) => {
+  const { colorMode, theme } = useThemeUI()
+  const darkModeActive = isDarkMode(colorMode)
+
+  const colorVariants = {
+    secondary: { light: '#666', dark: '#888' },
+    success: { light: '#28a745', dark: '#4CAF50' },
+    warning: { light: '#ffc107', dark: '#FF9800' },
+    danger: { light: '#dc3545', dark: '#f44336' }
+  }
+  const isPrimary = variant === 'primary' || !colorVariants[variant]
+  const primaryColor = isPrimary
+    ? (theme?.colors?.primary ?? '#422EA3')
+    : darkModeActive
+      ? colorVariants[variant].dark
+      : colorVariants[variant].light
+  const rgb = isPrimary ? (theme?.colors?.primaryRgb ?? '66, 46, 163') : hexToRgb(primaryColor)
+
+  const sizeVariants = {
+    small: { fontSize: ['11px', '12px'], padding: '6px 10px', gap: 1 },
+    medium: { fontSize: ['12px', '13px'], padding: '8px 12px', gap: 1 },
+    large: { fontSize: ['13px', '14px'], padding: '10px 16px', gap: 2 }
+  }
+  const sizeStyles = sizeVariants[size] || sizeVariants.medium
+
+  const baseStyles = {
+    color: primaryColor,
+    textDecoration: 'none',
+    fontWeight: 'medium',
+    fontSize: sizeStyles.fontSize,
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: sizeStyles.gap,
+    padding: sizeStyles.padding,
+    borderRadius: '6px',
+    background: `rgba(${rgb}, 0.1)`,
+    border: `1px solid rgba(${rgb}, 0.2)`,
+    transition: 'all 0.2s ease',
+    cursor: 'pointer',
+    outline: 'none',
+    '&:hover': {
+      background: `rgba(${rgb}, 0.2)`,
+      textDecoration: 'none',
+      transform: 'scale(1.02)'
+    },
+    '&:focus': {
+      outline: 'none',
+      boxShadow: `0 0 0 2px ${primaryColor}20`
+    },
+    '&:active': {
+      transform: 'scale(0.98)'
+    }
+  }
+
+  const content = (
+    <>
+      {children}
+      {icon && icon}
+    </>
+  )
+
+  if (href) {
+    return (
+      <a href={href} sx={baseStyles} {...props}>
+        {content}
+      </a>
+    )
+  }
+
+  return (
+    <button type='button' onClick={onClick} sx={baseStyles} {...props}>
+      {content}
+    </button>
+  )
+}
+
+export default ActionButton

package/src/action-button.spec.js

@@ -0,0 +1,201 @@
+/** @jsx jsx */
+import { jsx } from 'theme-ui'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { ThemeUIProvider } from 'theme-ui'
+
+import ActionButton from './action-button.js'
+import { BUTTON_PRIMARY_COLORS } from './color-utils.js'
+
+const mockUseThemeUI = jest.fn(() => ({
+  colorMode: 'default',
+  theme: {
+    colors: {
+      primary: BUTTON_PRIMARY_COLORS.light,
+      primaryRgb: '66, 46, 163'
+    }
+  }
+}))
+
+jest.mock('theme-ui', () => ({
+  ...jest.requireActual('theme-ui'),
+  useThemeUI: () => mockUseThemeUI()
+}))
+
+const mockTheme = {
+  colors: {
+    primary: BUTTON_PRIMARY_COLORS.light,
+    primaryRgb: '66, 46, 163',
+    modes: {
+      dark: {
+        text: '#ffffff',
+        background: '#000000'
+      }
+    }
+  }
+}
+
+const renderWithProviders = (component, customTheme = null) => {
+  const themeToUse = customTheme ?? mockTheme
+  return render(<ThemeUIProvider theme={themeToUse}>{component}</ThemeUIProvider>)
+}
+
+describe('ActionButton', () => {
+  it('renders as a button by default', () => {
+    renderWithProviders(<ActionButton>Test Button</ActionButton>)
+
+    const button = screen.getByRole('button', { name: /test button/i })
+    expect(button).toBeInTheDocument()
+    expect(button.tagName).toBe('BUTTON')
+  })
+
+  it('renders as a link when href is provided', () => {
+    renderWithProviders(<ActionButton href='/test'>Test Link</ActionButton>)
+
+    const link = screen.getByRole('link')
+    expect(link).toBeInTheDocument()
+    expect(link.tagName).toBe('A')
+    expect(link).toHaveAttribute('href', '/test')
+  })
+
+  it('handles click events', () => {
+    const handleClick = jest.fn()
+    renderWithProviders(<ActionButton onClick={handleClick}>Click Me</ActionButton>)
+
+    const button = screen.getByRole('button', { name: /click me/i })
+    fireEvent.click(button)
+
+    expect(handleClick).toHaveBeenCalledTimes(1)
+  })
+
+  it('applies primary variant styles by default', () => {
+    renderWithProviders(<ActionButton>Primary Button</ActionButton>)
+
+    const button = screen.getByRole('button', { name: /primary button/i })
+    expect(button).toHaveStyle({ fontWeight: 'medium' })
+    expect(button).toBeInTheDocument()
+  })
+
+  it('applies secondary variant styles', () => {
+    renderWithProviders(<ActionButton variant='secondary'>Secondary Button</ActionButton>)
+
+    const button = screen.getByRole('button', { name: /secondary button/i })
+    expect(button).toHaveStyle({
+      color: '#666'
+    })
+  })
+
+  it('applies small size styles', () => {
+    renderWithProviders(<ActionButton size='small'>Small Button</ActionButton>)
+
+    const button = screen.getByRole('button', { name: /small button/i })
+    expect(button).toHaveStyle({
+      fontSize: '11px',
+      padding: '6px 10px'
+    })
+  })
+
+  it('applies large size styles', () => {
+    renderWithProviders(<ActionButton size='large'>Large Button</ActionButton>)
+
+    const button = screen.getByRole('button', { name: /large button/i })
+    expect(button).toHaveStyle({
+      fontSize: '13px',
+      padding: '10px 16px'
+    })
+  })
+
+  it('renders with icon', () => {
+    const TestIcon = () => <span data-testid='test-icon'>→</span>
+    renderWithProviders(<ActionButton icon={<TestIcon />}>Button with Icon</ActionButton>)
+
+    expect(screen.getByTestId('test-icon')).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: /button with icon/i })).toBeInTheDocument()
+  })
+
+  it('passes through additional props', () => {
+    renderWithProviders(
+      <ActionButton data-testid='custom-button' aria-label='Custom label'>
+        Custom Button
+      </ActionButton>
+    )
+
+    const button = screen.getByTestId('custom-button')
+    expect(button).toHaveAttribute('aria-label', 'Custom label')
+  })
+
+  it('has proper accessibility attributes', () => {
+    renderWithProviders(<ActionButton>Accessible Button</ActionButton>)
+
+    const button = screen.getByRole('button', { name: /accessible button/i })
+    expect(button).toHaveAttribute('type', 'button')
+  })
+
+  it('falls back to primary variant when invalid variant is provided', () => {
+    renderWithProviders(<ActionButton variant='invalid'>Invalid Variant</ActionButton>)
+
+    const button = screen.getByRole('button', { name: /invalid variant/i })
+    expect(button).toBeInTheDocument()
+    expect(button).toHaveStyle({ fontWeight: 'medium' })
+  })
+
+  it('falls back to medium size when invalid size is provided', () => {
+    renderWithProviders(<ActionButton size='invalid'>Invalid Size</ActionButton>)
+
+    const button = screen.getByRole('button', { name: /invalid size/i })
+    expect(button).toHaveStyle({
+      fontSize: '12px',
+      padding: '8px 12px'
+    })
+  })
+
+  describe('theme fallbacks', () => {
+    beforeEach(() => {
+      mockUseThemeUI.mockReturnValue({
+        colorMode: 'default',
+        theme: {
+          colors: {
+            primary: BUTTON_PRIMARY_COLORS.light,
+            primaryRgb: '66, 46, 163'
+          }
+        }
+      })
+    })
+
+    it('uses fallback primary color when theme.colors.primary is undefined', () => {
+      mockUseThemeUI.mockReturnValueOnce({
+        colorMode: 'default',
+        theme: { colors: {} }
+      })
+
+      renderWithProviders(<ActionButton>Fallback Test</ActionButton>)
+
+      const button = screen.getByRole('button', { name: /fallback test/i })
+      expect(button).toBeInTheDocument()
+      expect(button).toHaveStyle({ fontWeight: 'medium' })
+    })
+
+    it('uses fallback primaryRgb when theme.colors.primaryRgb is undefined', () => {
+      mockUseThemeUI.mockReturnValueOnce({
+        colorMode: 'default',
+        theme: { colors: { primary: '#422EA3' } }
+      })
+
+      renderWithProviders(<ActionButton>Fallback RGB Test</ActionButton>)
+
+      const button = screen.getByRole('button', { name: /fallback rgb test/i })
+      expect(button).toBeInTheDocument()
+    })
+
+    it('uses fallback when theme itself is undefined', () => {
+      mockUseThemeUI.mockReturnValueOnce({
+        colorMode: 'default',
+        theme: undefined
+      })
+
+      renderWithProviders(<ActionButton>Undefined Theme Test</ActionButton>)
+
+      const button = screen.getByRole('button', { name: /undefined theme test/i })
+      expect(button).toBeInTheDocument()
+    })
+  })
+})

package/src/color-utils.js

@@ -0,0 +1,37 @@
+/**
+ * Shared color utilities and constants for consistent button and UI styling.
+ * Single source of truth for primary button colors and hex conversion.
+ */
+
+/** Fallback RGB string when hex is invalid (blue) */
+const HEX_TO_RGB_FALLBACK = '74, 158, 255'
+
+/**
+ * Converts hex color to RGB string for use in rgba()
+ * @param {string} hex - Hex color code (with or without #)
+ * @returns {string} RGB values as comma-separated string (e.g. "66, 46, 163")
+ */
+export const hexToRgb = hex => {
+  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex)
+  if (!result) return HEX_TO_RGB_FALLBACK
+  return `${parseInt(result[1], 16)}, ${parseInt(result[2], 16)}, ${parseInt(result[3], 16)}`
+}
+
+/**
+ * Converts hex color to rgba string
+ * @param {string} hex - Hex color code (with or without #)
+ * @param {number} alpha - Alpha value 0–1
+ * @returns {string} rgba() CSS value
+ */
+export const hexToRgba = (hex, alpha) => {
+  return `rgba(${hexToRgb(hex)}, ${alpha})`
+}
+
+/**
+ * Primary button/CTA colors for light and dark mode.
+ * Aligns with theme colors.primary and theme.colors.primaryRgb.
+ */
+export const BUTTON_PRIMARY_COLORS = {
+  light: '#422EA3',
+  dark: '#4a9eff'
+}

package/src/color-utils.spec.js

@@ -0,0 +1,43 @@
+import { hexToRgb, hexToRgba, BUTTON_PRIMARY_COLORS } from './color-utils'
+
+describe('hexToRgb', () => {
+  it('converts hex with hash to RGB', () => {
+    expect(hexToRgb('#422EA3')).toBe('66, 46, 163')
+  })
+
+  it('converts hex without hash to RGB', () => {
+    expect(hexToRgb('4a9eff')).toBe('74, 158, 255')
+  })
+
+  it('returns fallback for invalid hex', () => {
+    expect(hexToRgb('invalid')).toBe('74, 158, 255')
+  })
+
+  it('returns fallback for empty string', () => {
+    expect(hexToRgb('')).toBe('74, 158, 255')
+  })
+})
+
+describe('hexToRgba', () => {
+  it('converts hex to rgba string', () => {
+    expect(hexToRgba('#422EA3', 0.5)).toBe('rgba(66, 46, 163, 0.5)')
+  })
+
+  it('accepts hex without hash', () => {
+    expect(hexToRgba('4a9eff', 1)).toBe('rgba(74, 158, 255, 1)')
+  })
+
+  it('uses fallback RGB for invalid hex', () => {
+    expect(hexToRgba('invalid', 0.2)).toBe('rgba(74, 158, 255, 0.2)')
+  })
+})
+
+describe('BUTTON_PRIMARY_COLORS', () => {
+  it('exports light mode color', () => {
+    expect(BUTTON_PRIMARY_COLORS.light).toBe('#422EA3')
+  })
+
+  it('exports dark mode color', () => {
+    expect(BUTTON_PRIMARY_COLORS.dark).toBe('#4a9eff')
+  })
+})

package/src/header.js

@@ -0,0 +1,28 @@
+/** @jsx jsx */
+import { jsx } from 'theme-ui'
+
+/**
+ * Header
+ *
+ * A decorative masthead element that can be used across page layouts.
+ */
+const Header = ({ children, styles }) => {
+  return (
+    <header
+      role='banner'
+      sx={{
+        variant: 'styles.Header'
+      }}
+    >
+      <div
+        sx={{
+          ...(styles ? styles : {})
+        }}
+      >
+        {children}
+      </div>
+    </header>
+  )
+}
+
+export default Header

package/src/header.spec.js

@@ -0,0 +1,47 @@
+import React from 'react'
+import { render } from '@testing-library/react'
+import '@testing-library/jest-dom'
+
+import Header from './header.js'
+
+describe('Header', () => {
+  it('renders with children', () => {
+    const { asFragment } = render(
+      <Header>
+        <h1>Test Header</h1>
+      </Header>
+    )
+    expect(asFragment()).toMatchSnapshot()
+  })
+
+  it('renders with custom styles', () => {
+    const customStyles = {
+      backgroundColor: 'red',
+      color: 'white'
+    }
+    const { asFragment } = render(
+      <Header styles={customStyles}>
+        <h1>Test Header with Styles</h1>
+      </Header>
+    )
+    expect(asFragment()).toMatchSnapshot()
+  })
+
+  it('renders without styles prop', () => {
+    const { asFragment } = render(
+      <Header>
+        <h1>Test Header without Styles</h1>
+      </Header>
+    )
+    expect(asFragment()).toMatchSnapshot()
+  })
+
+  it('renders with empty styles object', () => {
+    const { asFragment } = render(
+      <Header styles={{}}>
+        <h1>Test Header with Empty Styles</h1>
+      </Header>
+    )
+    expect(asFragment()).toMatchSnapshot()
+  })
+})

package/src/lazy-load.js

@@ -0,0 +1,41 @@
+/** @jsx jsx */
+import { jsx } from 'theme-ui'
+import { useState, useEffect } from 'react'
+import { useInView } from 'react-intersection-observer'
+
+const DefaultPlaceholder = ({ height = '100%', width = '100%' }) => (
+  <div
+    data-testid='default-placeholder'
+    sx={{
+      minHeight: '1px',
+      minWidth: '1px',
+      height,
+      width
+    }}
+  >
+    {' '}
+  </div>
+)
+
+/**
+ * Lazy Loader
+ *
+ * Hides a component until it's been visible in the viewport.
+ */
+const LazyLoad = ({ children, placeholder = <DefaultPlaceholder /> }) => {
+  const [hasBeenVisible, setHasBeenVisible] = useState(false)
+  const { ref, inView } = useInView({
+    triggerOnce: true,
+    threshold: 0
+  })
+
+  useEffect(() => {
+    if (inView && !hasBeenVisible) {
+      setHasBeenVisible(true)
+    }
+  }, [inView, hasBeenVisible])
+
+  return <div ref={ref}>{hasBeenVisible ? children : placeholder}</div>
+}
+
+export default LazyLoad

package/src/lazy-load.spec.js

@@ -0,0 +1,88 @@
+import React from 'react'
+import { render, screen } from '@testing-library/react'
+import '@testing-library/jest-dom'
+import LazyLoad from './lazy-load.js'
+
+let mockInView = false
+
+jest.mock('react-intersection-observer', () => ({
+  useInView: () => ({
+    ref: jest.fn(),
+    inView: mockInView
+  })
+}))
+
+const MockPlaceholder = () => <div data-testid='placeholder'>Placeholder</div>
+
+describe('LazyLoad', () => {
+  afterEach(() => {
+    jest.clearAllMocks()
+    mockInView = false
+  })
+
+  it('renders the default placeholder initially', () => {
+    render(
+      <LazyLoad>
+        <div data-testid='content'>Lazy Loaded Content</div>
+      </LazyLoad>
+    )
+
+    expect(screen.getByTestId('default-placeholder')).toBeInTheDocument()
+    expect(screen.queryByTestId('content')).not.toBeInTheDocument()
+  })
+
+  it('renders the children when visible', () => {
+    mockInView = true
+
+    render(
+      <LazyLoad>
+        <div data-testid='content'>Lazy Loaded Content</div>
+      </LazyLoad>
+    )
+
+    expect(screen.getByTestId('content')).toBeInTheDocument()
+  })
+
+  it('renders the custom placeholder when provided', () => {
+    render(
+      <LazyLoad placeholder={<MockPlaceholder />}>
+        <div data-testid='content'>Lazy Loaded Content</div>
+      </LazyLoad>
+    )
+
+    expect(screen.getByTestId('placeholder')).toBeInTheDocument()
+    expect(screen.queryByTestId('content')).not.toBeInTheDocument()
+  })
+
+  it('does not re-render children if already visible', () => {
+    mockInView = true
+
+    const { rerender } = render(
+      <LazyLoad>
+        <div data-testid='content'>Lazy Loaded Content</div>
+      </LazyLoad>
+    )
+
+    expect(screen.getByTestId('content')).toBeInTheDocument()
+
+    mockInView = false
+
+    rerender(
+      <LazyLoad>
+        <div data-testid='content'>Lazy Loaded Content</div>
+      </LazyLoad>
+    )
+
+    expect(screen.getByTestId('content')).toBeInTheDocument()
+  })
+
+  it('does not render children when visibility remains false', () => {
+    render(
+      <LazyLoad>
+        <div data-testid='content'>Lazy Loaded Content</div>
+      </LazyLoad>
+    )
+
+    expect(screen.queryByTestId('content')).not.toBeInTheDocument()
+  })
+})

package/src/page-header.js

@@ -0,0 +1,10 @@
+import React from 'react'
+import { Heading } from '@theme-ui/components'
+
+const PageHeader = ({ children }) => (
+  <Heading as='h1' className='p-name' sx={{ mb: 2, lineHeight: 1.5, fontSize: [6, 'calc(1.25em + 2vw)'] }}>
+    {children}
+  </Heading>
+)
+
+export default PageHeader

package/src/page-header.spec.js

@@ -0,0 +1,17 @@
+import React from 'react'
+import { render, screen } from '@testing-library/react'
+import '@testing-library/jest-dom'
+import PageHeader from './page-header.js'
+
+describe('PageHeader', () => {
+  it('renders correctly with given children', () => {
+    render(<PageHeader>Hello, World!</PageHeader>)
+    const headingElement = screen.getByRole('heading', { name: /Hello, World!/i })
+    expect(headingElement).toBeInTheDocument()
+  })
+
+  it('matches snapshot', () => {
+    const { asFragment } = render(<PageHeader>Hello, World!</PageHeader>)
+    expect(asFragment()).toMatchSnapshot()
+  })
+})

package/src/pagination-button.js

@@ -0,0 +1,106 @@
+/** @jsx jsx */
+import React from 'react'
+import { jsx, useThemeUI } from 'theme-ui'
+import isDarkMode from './helpers/isDarkMode.js'
+import { hexToRgb } from './color-utils.js'
+
+const PaginationButton = ({
+  children,
+  onClick,
+  disabled = false,
+  active = false,
+  variant = 'primary',
+  size = 'medium',
+  icon,
+  ...props
+}) => {
+  const { colorMode, theme } = useThemeUI()
+  const darkModeActive = isDarkMode(colorMode)
+
+  const colorVariants = {
+    secondary: { light: '#666', dark: '#888' },
+    success: { light: '#28a745', dark: '#4CAF50' },
+    warning: { light: '#ffc107', dark: '#FF9800' },
+    danger: { light: '#dc3545', dark: '#f44336' }
+  }
+  const isPrimary = variant === 'primary' || !colorVariants[variant]
+  const primaryColor = isPrimary
+    ? (theme?.colors?.primary ?? '#422EA3')
+    : darkModeActive
+      ? colorVariants[variant].dark
+      : colorVariants[variant].light
+  const rgb = isPrimary ? (theme?.colors?.primaryRgb ?? '66, 46, 163') : hexToRgb(primaryColor)
+
+  const sizeVariants = {
+    small: {
+      fontSize: ['10px', '11px'],
+      padding: '4px 8px',
+      minWidth: ['24px', '28px'],
+      height: ['24px', '28px'],
+      gap: 1
+    },
+    medium: {
+      fontSize: ['11px', '12px'],
+      padding: '6px 10px',
+      minWidth: ['28px', '32px'],
+      height: ['28px', '32px'],
+      gap: 1
+    },
+    large: {
+      fontSize: ['12px', '13px'],
+      padding: '8px 12px',
+      minWidth: ['32px', '36px'],
+      height: ['32px', '36px'],
+      gap: 2
+    }
+  }
+  const sizeStyles = sizeVariants[size] || sizeVariants.medium
+
+  const baseStyles = {
+    color: active ? 'white' : primaryColor,
+    textDecoration: 'none',
+    fontWeight: active ? 'bold' : 'medium',
+    fontSize: sizeStyles.fontSize,
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: sizeStyles.gap,
+    padding: sizeStyles.padding,
+    minWidth: sizeStyles.minWidth,
+    height: sizeStyles.height,
+    borderRadius: '6px',
+    background: active ? primaryColor : `rgba(${rgb}, 0.1)`,
+    border: active ? `1px solid ${primaryColor}` : `1px solid rgba(${rgb}, 0.2)`,
+    transition: 'all 0.2s ease',
+    cursor: disabled ? 'not-allowed' : 'pointer',
+    outline: 'none',
+    opacity: disabled ? 0.5 : 1,
+    '&:hover:not(:disabled)': {
+      background: active ? primaryColor : `rgba(${rgb}, 0.2)`,
+      textDecoration: 'none',
+      transform: 'scale(1.02)'
+    },
+    '&:focus:not(:disabled)': {
+      outline: 'none',
+      boxShadow: `0 0 0 2px ${primaryColor}20`
+    },
+    '&:active:not(:disabled)': {
+      transform: 'scale(0.98)'
+    }
+  }
+
+  const content = (
+    <>
+      {children}
+      {icon && icon}
+    </>
+  )
+
+  return (
+    <button type='button' onClick={onClick} disabled={disabled} sx={baseStyles} {...props}>
+      {content}
+    </button>
+  )
+}
+
+export default PaginationButton

package/src/pagination-button.spec.js

@@ -0,0 +1,197 @@
+/** @jsx jsx */
+import { jsx } from 'theme-ui'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { ThemeUIProvider } from 'theme-ui'
+
+import PaginationButton from './pagination-button.js'
+import { BUTTON_PRIMARY_COLORS } from './color-utils.js'
+
+const mockUseThemeUI = jest.fn(() => ({
+  colorMode: 'default',
+  theme: {
+    colors: {
+      primary: BUTTON_PRIMARY_COLORS.light,
+      primaryRgb: '66, 46, 163'
+    }
+  }
+}))
+
+jest.mock('theme-ui', () => ({
+  ...jest.requireActual('theme-ui'),
+  useThemeUI: () => mockUseThemeUI()
+}))
+
+const mockTheme = {
+  colors: {
+    primary: BUTTON_PRIMARY_COLORS.light,
+    primaryRgb: '66, 46, 163',
+    modes: {
+      dark: {
+        text: '#ffffff',
+        background: '#000000'
+      }
+    }
+  }
+}
+
+const renderWithProviders = (component, customTheme = null) => {
+  const themeToUse = customTheme ?? mockTheme
+  return render(<ThemeUIProvider theme={themeToUse}>{component}</ThemeUIProvider>)
+}
+
+describe('PaginationButton', () => {
+  it('renders as a button', () => {
+    renderWithProviders(<PaginationButton>1</PaginationButton>)
+
+    const button = screen.getByRole('button', { name: /1/i })
+    expect(button).toBeInTheDocument()
+    expect(button.tagName).toBe('BUTTON')
+  })
+
+  it('handles click events', () => {
+    const handleClick = jest.fn()
+    renderWithProviders(<PaginationButton onClick={handleClick}>1</PaginationButton>)
+
+    const button = screen.getByRole('button', { name: /1/i })
+    fireEvent.click(button)
+
+    expect(handleClick).toHaveBeenCalledTimes(1)
+  })
+
+  it('applies active state styles', () => {
+    renderWithProviders(<PaginationButton active>1</PaginationButton>)
+
+    const button = screen.getByRole('button', { name: /1/i })
+    expect(button).toHaveStyle({
+      color: 'rgb(255, 255, 255)',
+      fontWeight: 'bold'
+    })
+  })
+
+  it('applies disabled state', () => {
+    renderWithProviders(<PaginationButton disabled>1</PaginationButton>)
+
+    const button = screen.getByRole('button', { name: /1/i })
+    expect(button).toBeDisabled()
+    expect(button).toHaveStyle({
+      opacity: '0.5',
+      cursor: 'not-allowed'
+    })
+  })
+
+  it('applies primary variant styles by default', () => {
+    renderWithProviders(<PaginationButton>1</PaginationButton>)
+
+    const button = screen.getByRole('button', { name: /1/i })
+    expect(button).toHaveStyle({ fontWeight: 'medium' })
+    expect(button).toBeInTheDocument()
+  })
+
+  it('applies secondary variant styles', () => {
+    renderWithProviders(<PaginationButton variant='secondary'>1</PaginationButton>)
+
+    const button = screen.getByRole('button', { name: /1/i })
+    expect(button).toHaveStyle({
+      color: '#666'
+    })
+  })
+
+  it('applies small size styles', () => {
+    renderWithProviders(<PaginationButton size='small'>1</PaginationButton>)
+
+    const button = screen.getByRole('button', { name: /1/i })
+    expect(button).toHaveStyle({
+      fontSize: '10px',
+      minWidth: '24px',
+      height: '24px'
+    })
+  })
+
+  it('applies large size styles', () => {
+    renderWithProviders(<PaginationButton size='large'>1</PaginationButton>)
+
+    const button = screen.getByRole('button', { name: /1/i })
+    expect(button).toHaveStyle({
+      fontSize: '12px',
+      minWidth: '32px',
+      height: '32px'
+    })
+  })
+
+  it('renders with icon', () => {
+    const TestIcon = () => <span data-testid='test-icon'>←</span>
+    renderWithProviders(<PaginationButton icon={<TestIcon />}>Prev</PaginationButton>)
+
+    expect(screen.getByTestId('test-icon')).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: /prev/i })).toBeInTheDocument()
+  })
+
+  it('passes through additional props', () => {
+    renderWithProviders(
+      <PaginationButton data-testid='custom-button' aria-label='Custom label'>
+        1
+      </PaginationButton>
+    )
+
+    const button = screen.getByTestId('custom-button')
+    expect(button).toHaveAttribute('aria-label', 'Custom label')
+  })
+
+  it('has proper accessibility attributes', () => {
+    renderWithProviders(<PaginationButton>1</PaginationButton>)
+
+    const button = screen.getByRole('button', { name: /1/i })
+    expect(button).toHaveAttribute('type', 'button')
+  })
+
+  describe('theme fallbacks', () => {
+    beforeEach(() => {
+      mockUseThemeUI.mockReturnValue({
+        colorMode: 'default',
+        theme: {
+          colors: {
+            primary: BUTTON_PRIMARY_COLORS.light,
+            primaryRgb: '66, 46, 163'
+          }
+        }
+      })
+    })
+
+    it('uses fallback primary color when theme.colors.primary is undefined', () => {
+      mockUseThemeUI.mockReturnValueOnce({
+        colorMode: 'default',
+        theme: { colors: {} }
+      })
+
+      renderWithProviders(<PaginationButton>1</PaginationButton>)
+
+      const button = screen.getByRole('button', { name: /1/i })
+      expect(button).toBeInTheDocument()
+      expect(button).toHaveStyle({ fontWeight: 'medium' })
+    })
+
+    it('uses fallback primaryRgb when theme.colors.primaryRgb is undefined', () => {
+      mockUseThemeUI.mockReturnValueOnce({
+        colorMode: 'default',
+        theme: { colors: { primary: '#422EA3' } }
+      })
+
+      renderWithProviders(<PaginationButton>1</PaginationButton>)
+
+      const button = screen.getByRole('button', { name: /1/i })
+      expect(button).toBeInTheDocument()
+    })
+
+    it('uses fallback when theme itself is undefined', () => {
+      mockUseThemeUI.mockReturnValueOnce({
+        colorMode: 'default',
+        theme: undefined
+      })
+
+      renderWithProviders(<PaginationButton>1</PaginationButton>)
+
+      const button = screen.getByRole('button', { name: /1/i })
+      expect(button).toBeInTheDocument()
+    })
+  })
+})