@chronogrove/ui 0.76.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/jest.config.cjs

@@ -15,6 +15,7 @@ module.exports = {
     'src/index.js',
     'src/skip-nav/index.js',
     'src/color-mode/index.js',
+    'src/gatsby/index.js',
     'src/theme.js'
   ],
   moduleNameMapper: {

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@chronogrove/ui",
-  "version": "0.76.0",
+  "version": "0.78.0",
   "description": "Chronogrove Theme UI theme, color mode helpers, and shared UI primitives",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chrisvogt/gatsby-theme-chronogrove.git",
+    "directory": "packages/ui"
+  },
   "sideEffects": false,
   "exports": {
     ".": {
@@ -40,6 +45,34 @@
     "./is-dark-mode": {
       "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"
     }
   },
   "peerDependencies": {
@@ -52,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/gatsby/build-theme-ui-color-mode-head-components.js

@@ -0,0 +1,36 @@
+import React from 'react'
+
+import { resolveChronogroveSurfaceColors } from '../color-mode/resolve-theme-colors.js'
+import {
+  buildThemeUiNoFlashInlineScript,
+  buildHtmlBackgroundInlineScript,
+  buildThemeUiColorModeFallbackCss
+} from '../color-mode/head-inline.js'
+
+/**
+ * React head elements for Theme UI color mode: no-flash script, HTML background script, fallback CSS.
+ * Compose with your own meta tags (e.g. Emotion insertion point) in `onRenderBody`.
+ *
+ * @param {{ theme: object }} options — Theme UI theme object (same as `ThemeUIProvider`)
+ * @returns {import('react').ReactElement[]}
+ */
+export function buildThemeUiColorModeHeadComponents({ theme }) {
+  const surface = resolveChronogroveSurfaceColors(theme)
+  const colorModeScript = buildThemeUiNoFlashInlineScript()
+  const htmlBackgroundScript = buildHtmlBackgroundInlineScript({
+    defaultBackgroundHex: surface.defaultBackgroundHex,
+    darkBackgroundHex: surface.darkBackgroundHex
+  })
+  const colorModeFallbackCSS = buildThemeUiColorModeFallbackCss({
+    defaultTextHex: surface.defaultTextHex,
+    defaultTextMutedHex: surface.defaultTextMutedHex,
+    darkTextHex: surface.darkTextHex,
+    darkTextMutedHex: surface.darkTextMutedHex
+  })
+
+  return [
+    <script key='theme-ui-no-flash' dangerouslySetInnerHTML={{ __html: colorModeScript }} />,
+    <script key='html-bg-color' dangerouslySetInnerHTML={{ __html: htmlBackgroundScript }} />,
+    <style key='theme-ui-color-mode-fallback' dangerouslySetInnerHTML={{ __html: colorModeFallbackCSS }} />
+  ]
+}

package/src/gatsby/index.js

@@ -0,0 +1,4 @@
+export { buildThemeUiColorModeHeadComponents } from './build-theme-ui-color-mode-head-components.js'
+export { onPreRenderHTMLSortThemeUiColorModeFirst } from './on-pre-render-html-sort.js'
+export { onRouteUpdateThemeUiColorMode } from './on-route-update-color-mode.js'
+export { RECONCILE_COLOR_MODE_EVENT } from '../color-mode/constants.js'