@chronogrove/ui 0.83.0 → 0.83.1

package/README.md

@@ -67,6 +67,79 @@ Prefer deep imports so bundles stay lean:
 
 **JSX + bundlers:** Primitives such as [`button`](./src/button.js) use [`Box`](https://theme-ui.com/components/box) from `@theme-ui/components` with an `as` prop for native elements, so `sx` works with Gatsby’s classic JSX runtime and Next’s SWC without a Theme UI file pragma. Jest uses [`babel.config.cjs`](./babel.config.cjs) (automatic JSX).
 
+## Global CSS, Prism / third-party CSS, and fonts
+
+Styles load in three layers. Understanding the split prevents accidental duplicates and keeps each host's build minimal.
+
+### Layer order
+
+| #   | Layer                                           | Mechanism                                                                                                                                                                                                               |
+| --- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **Head — color-mode + Emotion insertion point** | Gatsby: `theme/gatsby-ssr.js` + `@chronogrove/ui/gatsby` helpers. Next: `ChronogroveNextRootLayoutHead` from `@chronogrove/ui/next`. Emit before any `<style>` tags so Emotion and Theme UI no-flash scripts run first. |
+| 2   | **Theme UI globals (`theme.global`)**           | `ChronogroveThemeProvider` renders `<Global styles={theme.global} />` via Emotion. This applies identical baseline CSS under both Gatsby and Next as long as the provider wraps the app. No extra import needed.        |
+| 3   | **Host global CSS**                             | Each host owns its plain-CSS files. See below for Gatsby and Next specifics.                                                                                                                                            |
+
+### Gatsby
+
+The theme's own global CSS entry is the side-effect import block in [`theme/gatsby-browser.js`](../../theme/gatsby-browser.js):
+
+```javascript
+import './src/styles/global.css' // layout, .sr-only, Prism overrides
+import 'lightgallery/css/lightgallery.css'
+import 'lightgallery/css/lg-thumbnail.css'
+import 'lightgallery/css/lg-zoom.css'
+import 'prismjs/themes/prism-solarizedlight.css'
+import 'prismjs/plugins/line-numbers/prism-line-numbers.css'
+```
+
+[`theme/src/styles/global.css`](../../theme/src/styles/global.css) also contains `@import '@chronogrove/ui/color-toggle-styles'` for the theme toggle animation.
+
+Prism is **tightly coupled to `gatsby-remark-prismjs`** (configured in [`theme/gatsby-config.js`](../../theme/gatsby-config.js)). The CSS theme and helper overrides (`.gatsby-highlight`, line-number padding, etc.) only make sense when that plugin is active. They are intentionally kept in the Gatsby theme rather than in this package.
+
+Sites that shadow or extend the theme can add additional side-effect imports in their own `gatsby-browser.js` alongside (not instead of) the theme's entry.
+
+### Next.js (App Router)
+
+The reference app is [`examples/chronogrove-next`](../../examples/chronogrove-next). Its [`app/globals.css`](../../examples/chronogrove-next/app/globals.css) shows the minimal baseline:
+
+```css
+/* Required if you use ColorToggle */
+@import '@chronogrove/ui/color-toggle-styles';
+
+html {
+  scroll-behavior: smooth;
+}
+
+body {
+  background-color: var(--theme-ui-colors-background);
+  -webkit-font-smoothing: antialiased;
+}
+```
+
+Import `globals.css` once from the root `layout.jsx`/`layout.tsx` — the same file that renders `ChronogroveNextRootLayoutHead` and `ChronogroveNextEmotionRegistry`. See [`examples/chronogrove-next/app/layout.jsx`](../../examples/chronogrove-next/app/layout.jsx).
+
+For syntax highlighting in a Next MDX pipeline, use whatever highlighter fits your setup (e.g. [Shiki via rehype-pretty-code](https://rehype-pretty.pages.dev/)) and load only its CSS. There is no dependency on `prismjs` in this package, and you should not add the Prism CSS from the Gatsby theme to a Next app unless your MDX pipeline explicitly emits Prism class names.
+
+### Fonts
+
+The default Chronogrove theme uses **system font stacks** only (defined in [`src/theme.js`](./src/theme.js)):
+
+```js
+sans: '-apple-system, BlinkMacSystemFont, avenir next, ..., sans-serif'
+mono: 'Menlo, Consolas, ..., monospace'
+```
+
+No `@font-face` rules or external font URLs are shipped by this package. Web fonts are **host-owned**:
+
+- **Next.js:** use [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to load faces with zero layout shift; then pass the resulting CSS variable or family name into a theme override: `{ fonts: { body: 'var(--font-inter), sans-serif' } }`.
+- **Gatsby:** use [`gatsby-plugin-google-gtag`](https://www.gatsbyjs.com/plugins/gatsby-plugin-google-gtag/) or a `<link>` in `gatsby-ssr.js`, then extend `theme.fonts` in your `gatsby-config.js` theme options.
+
+Changing `theme.fonts` is the only hook needed; `ChronogroveThemeProvider` merges the override automatically via Theme UI.
+
+### Font Awesome (icons)
+
+`@chronogrove/ui` depends on `@fortawesome/fontawesome-svg-core` and `@fortawesome/react-fontawesome` for `WidgetHeader`. Icon **definitions** (e.g. `faGithub`) come from a kit you add to your own app — see the `WidgetHeader + icons` bullet in the [Next.js](#nextjs-app-router) section above.
+
 ## Changelog
 
 Releases are recorded in the repository root [`CHANGELOG.md`](../../CHANGELOG.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chronogrove/ui",
-  "version": "0.83.0",
+  "version": "0.83.1",
   "description": "Chronogrove Theme UI theme, color mode helpers, and shared UI primitives",
   "license": "MIT",
   "type": "module",
@@ -138,6 +138,18 @@
       "import": "./src/action-card-layout.js",
       "default": "./src/action-card-layout.js"
     },
+    "./article-column-container": {
+      "import": "./src/article-column-container.js",
+      "default": "./src/article-column-container.js"
+    },
+    "./home-dashboard-layout": {
+      "import": "./src/home-dashboard-layout.js",
+      "default": "./src/home-dashboard-layout.js"
+    },
+    "./page-shell-layout": {
+      "import": "./src/page-shell-layout.js",
+      "default": "./src/page-shell-layout.js"
+    },
     "./thumbnail-strip": {
       "import": "./src/thumbnail-strip.js",
       "default": "./src/thumbnail-strip.js"

package/src/article-column-container.js

@@ -0,0 +1,23 @@
+import React from 'react'
+import { Container } from '@theme-ui/components'
+
+/**
+ * Primary text column width for MDX posts, blog index, and about-style pages.
+ * Keep in sync wherever the article measure must match (Gatsby post template, blog index, etc.).
+ */
+export const articleColumnContainerSx = {
+  position: 'relative',
+  width: ['', '', 'max(80ch, 50vw)'],
+  lineHeight: 1.7
+}
+
+/**
+ * Theme UI `Container` with {@link articleColumnContainerSx}. Pass `sx` to merge (e.g. `flexGrow: 1` on the blog index).
+ */
+export function ArticleColumnContainer({ children, sx = {}, ...rest }) {
+  return (
+    <Container sx={{ ...articleColumnContainerSx, ...sx }} {...rest}>
+      {children}
+    </Container>
+  )
+}

package/src/article-column-container.spec.js

@@ -0,0 +1,40 @@
+import React from 'react'
+import { render, screen } from '@testing-library/react'
+import { ChronogroveThemeProvider } from './provider.js'
+import chronogroveTheme from './theme.js'
+
+import { ArticleColumnContainer, articleColumnContainerSx } from './article-column-container.js'
+
+describe('articleColumnContainerSx', () => {
+  it('defines the shared article measure', () => {
+    expect(articleColumnContainerSx).toMatchObject({
+      position: 'relative',
+      width: ['', '', 'max(80ch, 50vw)'],
+      lineHeight: 1.7
+    })
+  })
+})
+
+describe('ArticleColumnContainer', () => {
+  it('renders children with merged sx', () => {
+    render(
+      <ChronogroveThemeProvider theme={chronogroveTheme}>
+        <ArticleColumnContainer sx={{ flexGrow: 1 }} data-testid='ac'>
+          <span>body</span>
+        </ArticleColumnContainer>
+      </ChronogroveThemeProvider>
+    )
+    expect(screen.getByTestId('ac')).toContainElement(screen.getByText('body'))
+  })
+
+  it('renders with base article sx when sx is omitted', () => {
+    render(
+      <ChronogroveThemeProvider theme={chronogroveTheme}>
+        <ArticleColumnContainer data-testid='ac-base'>
+          <span>only-base</span>
+        </ArticleColumnContainer>
+      </ChronogroveThemeProvider>
+    )
+    expect(screen.getByTestId('ac-base')).toContainElement(screen.getByText('only-base'))
+  })
+})

package/src/home-dashboard-layout.js

@@ -0,0 +1,58 @@
+import React from 'react'
+import { Box, Grid } from '@theme-ui/components'
+
+/** Theme UI `Grid` `columns` for the home dashboard: single column until `md`, then sidebar + main. */
+export const homeDashboardGridColumns = [
+  null,
+  null,
+  'minmax(200px, 0.375fr) minmax(0, 1.625fr)',
+  'minmax(200px, 0.4fr) minmax(0, 1.6fr)'
+]
+
+export const homeDashboardGridGap = [null, 4]
+
+/** Default aside spacing; merge with site-specific `sx` (e.g. sticky side nav in demos). */
+export const homeDashboardAsideSx = {
+  mb: [4, null]
+}
+
+/** Rounded “glass” panel shell around the main home column (matches gatsby-theme-chronogrove home). */
+export const homeDashboardMainShellSx = {
+  position: 'relative',
+  borderTopRightRadius: '3em',
+  borderTopLeftRadius: '.5em',
+  px: [3, 4],
+  pt: [2, 3]
+}
+
+export const homeDashboardMainInnerMaxWidthSx = {
+  maxWidth: '1200px'
+}
+
+/** Outer stack below the page chrome on the home template (`minHeight`, top padding). */
+export const homeDashboardPageOuterSx = {
+  minHeight: '500px',
+  pt: 3,
+  px: 0
+}
+
+/**
+ * Two-column home dashboard grid (sidebar + main). Pass full `main` node so callers can set
+ * `role="main"`, skip-nav targets, footer, and microformats in one place.
+ *
+ * @param {object} props
+ * @param {React.ReactNode} props.aside
+ * @param {React.ReactNode} props.main
+ * @param {import('theme-ui').ThemeUIStyleObject} [props.asideSx] merged after {@link homeDashboardAsideSx}
+ * @param {React.ComponentProps<typeof Grid>} [props.gridProps] forwarded to `Grid`
+ */
+export function HomeDashboardGrid({ aside, main, asideSx = {}, gridProps = {}, ...gridRest }) {
+  return (
+    <Grid columns={homeDashboardGridColumns} gap={homeDashboardGridGap} {...gridProps} {...gridRest}>
+      <Box as='aside' sx={{ ...homeDashboardAsideSx, ...asideSx }}>
+        {aside}
+      </Box>
+      {main}
+    </Grid>
+  )
+}

package/src/home-dashboard-layout.spec.js

@@ -0,0 +1,60 @@
+import React from 'react'
+import { render, screen } from '@testing-library/react'
+import { ChronogroveThemeProvider } from './provider.js'
+import chronogroveTheme from './theme.js'
+
+import {
+  HomeDashboardGrid,
+  homeDashboardAsideSx,
+  homeDashboardGridColumns,
+  homeDashboardGridGap,
+  homeDashboardMainInnerMaxWidthSx,
+  homeDashboardMainShellSx,
+  homeDashboardPageOuterSx
+} from './home-dashboard-layout.js'
+
+describe('home dashboard layout tokens', () => {
+  it('exports grid columns and gap used by the Gatsby home template', () => {
+    expect(homeDashboardGridColumns[2]).toContain('minmax(200px')
+    expect(homeDashboardGridGap).toEqual([null, 4])
+    expect(homeDashboardAsideSx).toEqual({ mb: [4, null] })
+    expect(homeDashboardMainShellSx.borderTopRightRadius).toBe('3em')
+    expect(homeDashboardMainInnerMaxWidthSx.maxWidth).toBe('1200px')
+    expect(homeDashboardPageOuterSx.minHeight).toBe('500px')
+  })
+})
+
+describe('HomeDashboardGrid', () => {
+  it('renders aside and main slots', () => {
+    render(
+      <ChronogroveThemeProvider theme={chronogroveTheme}>
+        <HomeDashboardGrid aside={<span>nav</span>} main={<div data-testid='main'>content</div>} />
+      </ChronogroveThemeProvider>
+    )
+    expect(screen.getByText('nav')).toBeInTheDocument()
+    expect(screen.getByTestId('main')).toHaveTextContent('content')
+  })
+
+  it('merges asideSx onto the aside', () => {
+    const { container } = render(
+      <ChronogroveThemeProvider theme={chronogroveTheme}>
+        <HomeDashboardGrid aside={<span>a</span>} main={<span>b</span>} asideSx={{ position: 'sticky' }} />
+      </ChronogroveThemeProvider>
+    )
+    const aside = container.querySelector('aside')
+    expect(aside).toBeTruthy()
+  })
+
+  it('forwards gridProps to Grid', () => {
+    const { container } = render(
+      <ChronogroveThemeProvider theme={chronogroveTheme}>
+        <HomeDashboardGrid
+          aside={<span>l</span>}
+          main={<span>r</span>}
+          gridProps={{ 'data-testid': 'hdg', id: 'home-dash-grid' }}
+        />
+      </ChronogroveThemeProvider>
+    )
+    expect(container.querySelector('#home-dash-grid')).toBeTruthy()
+  })
+})

package/src/page-shell-layout.js

@@ -0,0 +1,57 @@
+import React from 'react'
+import { Box } from '@theme-ui/components'
+
+import { SkipNavContent, SkipNavLink } from './skip-nav/index.js'
+
+/**
+ * Default page chrome: skip link, optional header and footer slots, and a main landmark (unless disabled).
+ * Wire Gatsby-specific nav/footer and Zustand-driven `paddingBottom` from the site package.
+ *
+ * @param {object} props
+ * @param {React.ReactNode} props.children
+ * @param {boolean} [props.disableMainWrapper]
+ * @param {boolean} [props.hideHeader] when true, `header` is not rendered
+ * @param {boolean} [props.hideFooter] when true, `footer` is not rendered
+ * @param {boolean} [props.transparentBackground]
+ * @param {number|string} [props.paddingBottom] bottom padding (e.g. room for a fixed audio bar)
+ * @param {React.ReactNode} [props.header] placed inside `<header role="banner">` when not hidden
+ * @param {React.ReactNode} [props.footer]
+ */
+export function ChronogrovePageShell({
+  children,
+  disableMainWrapper = false,
+  hideHeader = false,
+  hideFooter = false,
+  transparentBackground = false,
+  paddingBottom = 0,
+  header = null,
+  footer = null
+}) {
+  return (
+    <Box
+      sx={{
+        backgroundColor: transparentBackground ? 'transparent' : 'background',
+        display: 'flex',
+        flexDirection: 'column',
+        flexGrow: 1,
+        color: theme => theme?.colors?.text,
+        pb: paddingBottom
+      }}
+    >
+      <SkipNavLink />
+
+      {!hideHeader && header ? <header role='banner'>{header}</header> : null}
+
+      {disableMainWrapper ? (
+        children
+      ) : (
+        <Box as='main' role='main'>
+          <SkipNavContent />
+          {children}
+        </Box>
+      )}
+
+      {!hideFooter && footer ? footer : null}
+    </Box>
+  )
+}

package/src/page-shell-layout.spec.js

@@ -0,0 +1,71 @@
+import React from 'react'
+import { render, screen } from '@testing-library/react'
+import { ChronogroveThemeProvider } from './provider.js'
+import chronogroveTheme from './theme.js'
+
+import { ChronogrovePageShell } from './page-shell-layout.js'
+
+function shellRender(ui) {
+  return render(<ChronogroveThemeProvider theme={chronogroveTheme}>{ui}</ChronogroveThemeProvider>)
+}
+
+describe('ChronogrovePageShell', () => {
+  it('renders skip link, header, main with skip target, children, and footer', () => {
+    shellRender(
+      <ChronogrovePageShell header={<span>hdr</span>} footer={<span>ftr</span>} paddingBottom='12px'>
+        <span>inner</span>
+      </ChronogrovePageShell>
+    )
+    expect(screen.getByText('inner')).toBeInTheDocument()
+    expect(screen.getByText('hdr')).toBeInTheDocument()
+    expect(screen.getByText('ftr')).toBeInTheDocument()
+    expect(document.querySelector('main[role="main"]')).toBeTruthy()
+  })
+
+  it('omits header when hideHeader', () => {
+    shellRender(
+      <ChronogrovePageShell hideHeader header={<span>no</span>} footer={null}>
+        <span>x</span>
+      </ChronogrovePageShell>
+    )
+    expect(screen.queryByText('no')).not.toBeInTheDocument()
+  })
+
+  it('omits footer when hideFooter', () => {
+    shellRender(
+      <ChronogrovePageShell hideFooter footer={<span>no</span>}>
+        <span>x</span>
+      </ChronogrovePageShell>
+    )
+    expect(screen.queryByText('no')).not.toBeInTheDocument()
+  })
+
+  it('renders children without main wrapper when disableMainWrapper', () => {
+    shellRender(
+      <ChronogrovePageShell disableMainWrapper>
+        <span data-testid='bare'>bare</span>
+      </ChronogrovePageShell>
+    )
+    expect(screen.getByTestId('bare')).toBeInTheDocument()
+    expect(document.querySelector('main[role="main"]')).toBeFalsy()
+  })
+
+  it('uses transparent background when requested', () => {
+    const { container } = shellRender(
+      <ChronogrovePageShell transparentBackground>
+        <span>t</span>
+      </ChronogrovePageShell>
+    )
+    expect(container.firstChild).toBeTruthy()
+  })
+
+  it('does not render a banner when header is null', () => {
+    shellRender(
+      <ChronogrovePageShell header={null}>
+        <span>no-banner</span>
+      </ChronogrovePageShell>
+    )
+    expect(screen.getByText('no-banner')).toBeInTheDocument()
+    expect(document.querySelector('header[role="banner"]')).toBeFalsy()
+  })
+})