@chronogrove/ui 0.83.1 → 0.83.3

package/README.md

@@ -44,7 +44,7 @@ Prefer deep imports so bundles stay lean:
 | `@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`**, **`thumbnail-strip`**, **`image-thumbnails`** (`optimizeSrc` for CDN resizing; Gatsby passes a Cloudinary helper). The authoritative list is **`package.json`** → **`exports`**.
+**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`** (dashboard `<section>`; when **`id`** is passed, **`tabIndex={-1}`** defaults so hosts can **`focus`** the landmark after hash / in-page navigation), **`widget-call-to-action`**, **`external-link-icon`**, **`thumbnail-strip`**, **`image-thumbnails`** (`optimizeSrc` for CDN resizing; Gatsby passes a Cloudinary helper). The authoritative list is **`package.json`** → **`exports`**.
 
 ## Next.js (App Router)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chronogrove/ui",
-  "version": "0.83.1",
+  "version": "0.83.3",
   "description": "Chronogrove Theme UI theme, color mode helpers, and shared UI primitives",
   "license": "MIT",
   "type": "module",
@@ -177,26 +177,26 @@
     "@emotion/cache": "^11.14.0",
     "@emotion/react": "^11.14.0",
     "@fortawesome/fontawesome-svg-core": "^7.2.0",
-    "@fortawesome/react-fontawesome": "^3.3.0",
+    "@fortawesome/react-fontawesome": "^3.3.1",
     "@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",
-    "three": "^0.183.2"
+    "three": "^0.184.0"
   },
   "devDependencies": {
     "@babel/core": "^7.29.0",
-    "@babel/preset-env": "^7.29.2",
+    "@babel/preset-env": "^7.29.5",
     "@babel/preset-react": "^7.28.5",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
-    "babel-jest": "^30.3.0",
-    "jest": "^30.3.0",
-    "jest-environment-jsdom": "^30.3.0",
-    "next": "^16.2.3",
-    "react": "^19.2.5",
-    "react-dom": "^19.2.5"
+    "babel-jest": "^30.4.1",
+    "jest": "^30.4.2",
+    "jest-environment-jsdom": "^30.4.1",
+    "next": "^16.2.6",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6"
   },
   "scripts": {
     "test": "jest --config jest.config.cjs",

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

@@ -115,8 +115,8 @@ exports[`Theme Configuration a snapshot of the configuration matches the snapsho
         "paddingLeft": "8px",
       },
       "&:hover, &:focus": {
-        "boxShadow": "lg",
-        "transform": "scale(1.015)",
+        "boxShadow": "0 1px 0 rgba(0,0,0,0.06), 0 2px 0 rgba(0,0,0,0.04), 0 3px 0 rgba(0,0,0,0.03), 0 8px 20px rgba(66,46,163,0.14)",
+        "transform": "translateY(-3px) scale(1.008)",
       },
       ".card-media": {
         "mb": 2,
@@ -145,7 +145,7 @@ exports[`Theme Configuration a snapshot of the configuration matches the snapsho
       "height": "100%",
       "padding": 3,
       "textDecoration": "none",
-      "transition": "all 200ms ease-in-out",
+      "transition": "transform 200ms ease-in-out, box-shadow 200ms ease-in-out",
     },
     "StatusCardDark": {
       "backgroundColor": "#1e2530",
@@ -175,8 +175,8 @@ exports[`Theme Configuration a snapshot of the configuration matches the snapsho
     },
     "actionCard": {
       "&:hover, &:focus": {
-        "boxShadow": "lg",
-        "transform": "scale(1.015)",
+        "boxShadow": "0 1px 0 rgba(0,0,0,0.06), 0 2px 0 rgba(0,0,0,0.04), 0 3px 0 rgba(0,0,0,0.03), 0 8px 20px rgba(66,46,163,0.14)",
+        "transform": "translateY(-3px) scale(1.008)",
       },
       "WebkitBackdropFilter": "blur(10px)",
       "a": {
@@ -196,7 +196,7 @@ exports[`Theme Configuration a snapshot of the configuration matches the snapsho
       ],
       "padding": 3,
       "textDecoration": "none",
-      "transition": "all 200ms ease-in-out",
+      "transition": "transform 200ms ease-in-out, box-shadow 200ms ease-in-out",
     },
     "aiSummary": {
       "@keyframes blink": {
@@ -356,7 +356,7 @@ exports[`Theme Configuration a snapshot of the configuration matches the snapsho
       "backdropFilter": "blur(12px) saturate(150%)",
       "bg": "panel-background",
       "borderRadius": "card",
-      "boxShadow": "default",
+      "boxShadow": "0 1px 0 rgba(0,0,0,0.06), 0 2px 0 rgba(0,0,0,0.04), 0 3px 0 rgba(0,0,0,0.03), 0 4px 12px rgba(66,46,163,0.08)",
       "color": "text",
       "flexGrow": 1,
       "fontSize": [
@@ -762,8 +762,8 @@ exports[`Theme Configuration a snapshot of the configuration matches the snapsho
     },
     "InstagramItem": {
       "&:hover, &:focus": {
-        "boxShadow": "lg",
-        "transform": "scale(1.015)",
+        "boxShadow": "0 1px 0 rgba(0,0,0,0.06), 0 2px 0 rgba(0,0,0,0.04), 0 3px 0 rgba(0,0,0,0.03), 0 8px 20px rgba(66,46,163,0.14)",
+        "transform": "translateY(-3px) scale(1.008)",
       },
       "background": "none",
       "border": "none",
@@ -772,7 +772,7 @@ exports[`Theme Configuration a snapshot of the configuration matches the snapsho
       "cursor": "pointer",
       "overflow": "hidden",
       "p": 0,
-      "transition": "all 200ms ease-in-out",
+      "transition": "transform 200ms ease-in-out, box-shadow 200ms ease-in-out",
     },
     "IntroExperienceSlide": {
       "&.active-slide": {

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

@@ -3,29 +3,34 @@
 exports[`WidgetHeader matches the snapshot 1`] = `
 <DocumentFragment>
   <header
-    class="css-7pzsne"
+    class="css-ubozo4"
   >
     <div
-      class="css-s076pz"
+      class="css-3vwaby"
     >
-      <h2
-        class="css-16f4ihe"
+      <div
+        aria-hidden="true"
+        class="css-1muvmnm"
       >
         <span
-          class="css-2s41mq"
-        >
-          <span
-            aria-hidden="true"
-            data-icon="spotify"
-            data-testid="fa-icon"
-          />
-        </span>
-        Neat & Interesting Widget
-      </h2>
+          aria-hidden="true"
+          data-icon="spotify"
+          data-testid="fa-icon"
+        />
+      </div>
       <div
-        class="sidebar-content"
+        class="css-m8374l"
       >
-        Sidebar
+        <h2
+          class="css-1tfs9qy"
+        >
+          Neat & Interesting Widget
+        </h2>
+        <div
+          class="sidebar-content"
+        >
+          Sidebar
+        </div>
       </div>
     </div>
   </header>

package/src/color-utils.js

@@ -6,13 +6,38 @@
 /** Fallback RGB string when hex is invalid (blue) */
 const HEX_TO_RGB_FALLBACK = '74, 158, 255'
 
+/**
+ * Normalizes #rgb / #rgba shorthand, #rrggbb, or #rrggbbaa to #rrggbb for RGB extraction.
+ * Appending two hex digits to 3-digit theme colors (e.g. `#111` + `22`) is not valid CSS.
+ *
+ * @param {string} hex
+ * @returns {string|null} `#rrggbb` or null if not parseable as hex
+ */
+export const normalizeHexToRrggbb = hex => {
+  if (typeof hex !== 'string') return null
+  const raw = hex.trim().replace(/^#/, '')
+  if (!raw || !/^[a-f\d]+$/i.test(raw)) return null
+  if (raw.length === 3) {
+    return `#${[...raw].map(c => c + c).join('')}`
+  }
+  if (raw.length === 4) {
+    const [r, g, b] = raw
+    return `#${r}${r}${g}${g}${b}${b}`
+  }
+  if (raw.length === 6) return `#${raw}`
+  if (raw.length === 8) return `#${raw.slice(0, 6)}`
+  return null
+}
+
 /**
  * Converts hex color to RGB string for use in rgba()
- * @param {string} hex - Hex color code (with or without #)
+ * @param {string} hex - Hex color code (with or without #); 3- and 4-digit shorthand supported
  * @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)
+  const rrggbb = normalizeHexToRrggbb(hex)
+  if (!rrggbb) return HEX_TO_RGB_FALLBACK
+  const result = /^#([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(rrggbb)
   if (!result) return HEX_TO_RGB_FALLBACK
   return `${parseInt(result[1], 16)}, ${parseInt(result[2], 16)}, ${parseInt(result[3], 16)}`
 }

package/src/color-utils.spec.js

@@ -1,10 +1,39 @@
-import { hexToRgb, hexToRgba, BUTTON_PRIMARY_COLORS } from './color-utils'
+import { hexToRgb, hexToRgba, normalizeHexToRrggbb, BUTTON_PRIMARY_COLORS } from './color-utils'
+
+describe('normalizeHexToRrggbb', () => {
+  it('expands 3-digit shorthand', () => {
+    expect(normalizeHexToRrggbb('#111')).toBe('#111111')
+    expect(normalizeHexToRrggbb('#fff')).toBe('#ffffff')
+    expect(normalizeHexToRrggbb('abc')).toBe('#aabbcc')
+  })
+
+  it('expands 4-digit shorthand to RGB only', () => {
+    expect(normalizeHexToRrggbb('#f0f8')).toBe('#ff00ff')
+  })
+
+  it('passes through 6-digit and strips alpha from 8-digit', () => {
+    expect(normalizeHexToRrggbb('#112233')).toBe('#112233')
+    expect(normalizeHexToRrggbb('#11223344')).toBe('#112233')
+  })
+
+  it('returns null for invalid input', () => {
+    expect(normalizeHexToRrggbb('')).toBeNull()
+    expect(normalizeHexToRrggbb('not-hex')).toBeNull()
+    expect(normalizeHexToRrggbb('#12')).toBeNull()
+    expect(normalizeHexToRrggbb(null)).toBeNull()
+  })
+})
 
 describe('hexToRgb', () => {
   it('converts hex with hash to RGB', () => {
     expect(hexToRgb('#422EA3')).toBe('66, 46, 163')
   })
 
+  it('converts 3-digit shorthand (theme text colors)', () => {
+    expect(hexToRgb('#111')).toBe('17, 17, 17')
+    expect(hexToRgb('#fff')).toBe('255, 255, 255')
+  })
+
   it('converts hex without hash to RGB', () => {
     expect(hexToRgb('4a9eff')).toBe('74, 158, 255')
   })
@@ -23,6 +52,10 @@ describe('hexToRgba', () => {
     expect(hexToRgba('#422EA3', 0.5)).toBe('rgba(66, 46, 163, 0.5)')
   })
 
+  it('supports 3-digit shorthand with fractional alpha', () => {
+    expect(hexToRgba('#111', 34 / 255)).toBe('rgba(17, 17, 17, 0.13333333333333333)')
+  })
+
   it('accepts hex without hash', () => {
     expect(hexToRgba('4a9eff', 1)).toBe('rgba(74, 158, 255, 1)')
   })

package/src/theme.js

@@ -14,11 +14,12 @@ const fonts = {
 }
 
 export const floatOnHover = {
-  transition: 'all 200ms ease-in-out',
+  transition: 'transform 200ms ease-in-out, box-shadow 200ms ease-in-out',
 
   '&:hover, &:focus': {
-    transform: 'scale(1.015)',
-    boxShadow: 'lg'
+    transform: 'translateY(-3px) scale(1.008)',
+    boxShadow:
+      '0 1px 0 rgba(0,0,0,0.06), 0 2px 0 rgba(0,0,0,0.04), 0 3px 0 rgba(0,0,0,0.03), 0 8px 20px rgba(66,46,163,0.14)'
   }
 }
 
@@ -81,7 +82,9 @@ export const card = {
   borderRadius: 'card',
   bg: 'panel-background',
   color: 'text',
-  boxShadow: 'default',
+  // Layered paper-stack shadow: each layer is a 1px offset slice, the final spread is the ambient
+  boxShadow:
+    '0 1px 0 rgba(0,0,0,0.06), 0 2px 0 rgba(0,0,0,0.04), 0 3px 0 rgba(0,0,0,0.03), 0 4px 12px rgba(66,46,163,0.08)',
   flexGrow: 1,
   padding: 3,
   fontSize: [1, 2],

package/src/widget-header.js

@@ -2,88 +2,177 @@ import React from 'react'
 import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
 import { Box, Heading } from '@theme-ui/components'
 
-import ProfileMetricsBadge from './profile-metrics-badge.js'
+import { hexToRgba, normalizeHexToRrggbb } from './color-utils.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
-}
+/** Alpha matching prior intent of appending `22` to 8-digit #RRGGBBAA (34/255) */
+const METRIC_CHIP_BORDER_ALPHA = 34 / 255
 
 /**
- * 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.
+ * WidgetHeader
+ *
+ * Social-dashboard section headline: a large clean heading paired with square
+ * data-chip metrics. No horizontal rules — section identity comes from the
+ * colored icon chip and typographic weight alone.
+ *
+ * Layout:
+ *   [icon chip] [Heading]  [CTA aside]          [metrics chips →]
+ *
+ * The icon chip is a small square badge (accent bg, white icon) that reads like
+ * a label on a physical card index tab. Metrics are monospaced square chips:
+ * number + unit in a bordered box, no rounded pills.
  */
-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
+
+  // Placeholder chips while loading
+  const metricsToShow = metricsLoading ? [{}, {}] : Array.isArray(metrics) ? metrics : []
+
   return (
     <Box
       as='header'
       sx={{
-        ...baseHeaderStyles,
-        // Extra margin below header when metrics are present so spacing matches Latest Posts (no metrics)
+        display: 'flex',
+        flexDirection: ['column', 'row'],
+        alignItems: ['flex-start', 'center'],
+        justifyContent: ['flex-start', 'space-between'],
+        gap: [2, 3],
+        flexWrap: 'wrap',
+        pb: 3,
         mb: hasMetrics ? 4 : 2
       }}
     >
-      <Box sx={titleGroupStyles}>
-        <Heading as='h2' sx={headingStyles}>
-          {icon && (
+      {/* Left cluster: icon chip (center-aligned) + heading/CTA sub-row (baseline-aligned) */}
+      <Box
+        sx={{
+          display: 'flex',
+          flexDirection: 'row',
+          alignItems: 'center',
+          gap: 2,
+          order: 1,
+          minWidth: 0
+        }}
+      >
+        {/* Colored square icon chip — center-aligned with the heading block */}
+        {icon && (
+          <Box
+            aria-hidden='true'
+            sx={{
+              flexShrink: 0,
+              width: '32px',
+              height: '32px',
+              borderRadius: '6px',
+              backgroundColor: 'primary',
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              boxShadow: theme =>
+                `inset 0 -2px 0 rgba(0,0,0,0.2), 0 1px 3px rgba(${theme.colors?.primaryRgb ?? '66,46,163'},0.3)`
+            }}
+          >
+            <FontAwesomeIcon icon={icon} style={{ width: 14, height: 14, color: '#fff' }} />
+          </Box>
+        )}
+
+        {/* Heading + CTA aside: baseline-aligned with each other, same as original */}
+        <Box
+          sx={{
+            display: 'flex',
+            flexDirection: 'row',
+            alignItems: 'baseline',
+            gap: [1, 2],
+            minWidth: 0
+          }}
+        >
+          <Heading
+            as='h2'
+            sx={{
+              fontSize: [4, 5],
+              fontFamily: 'heading',
+              fontWeight: 'bold',
+              lineHeight: 1,
+              m: 0,
+              p: 0,
+              textShadow: '0 1px 0 rgba(255,255,255,0.5), 0 -1px 0 rgba(0,0,0,0.07)',
+              letterSpacing: '-0.01em'
+            }}
+          >
+            {children}
+          </Heading>
+
+          {aside}
+        </Box>
+      </Box>
+
+      {/* Right cluster: square metric chips */}
+      {hasMetrics && (
+        <Box
+          sx={{
+            display: 'flex',
+            flexDirection: 'row',
+            gap: '6px',
+            alignItems: 'center',
+            order: 2,
+            flexShrink: 0
+          }}
+        >
+          {metricsToShow.map(({ displayName, id, value } = {}, idx) => (
             <Box
-              as='span'
+              key={id || idx}
               sx={{
                 display: 'inline-flex',
-                alignItems: 'baseline',
-                mr: 2,
-                fontSize: 4,
-                '& svg': { width: '1em', height: '1em' }
+                flexDirection: 'column',
+                alignItems: 'center',
+                justifyContent: 'center',
+                minWidth: '52px',
+                px: '6px',
+                py: '4px',
+                borderRadius: '4px',
+                border: '1px solid',
+                // Text-based border: theme `text` is often 3-digit hex (#111 / #fff); appending
+                // `22` for alpha is invalid CSS — use rgba() from expanded hex instead.
+                borderColor: theme => {
+                  const text = theme?.colors?.text ?? '#111'
+                  const base = normalizeHexToRrggbb(text)
+                  return base ? hexToRgba(base, METRIC_CHIP_BORDER_ALPHA) : 'rgba(17, 17, 17, 0.133)'
+                },
+                // panel-background is defined for both light + dark in chronogrove-theme-surface-colors
+                backgroundColor: 'panel-background',
+                ...(metricsLoading
+                  ? {
+                      animation: 'cgPulse 1.4s ease-in-out infinite',
+                      opacity: 0.5
+                    }
+                  : {})
               }}
             >
-              <FontAwesomeIcon icon={icon} aria-hidden='true' />
+              <Box
+                sx={{
+                  fontFamily: 'monospace',
+                  fontSize: '0.8rem',
+                  fontWeight: 'bold',
+                  lineHeight: 1.1,
+                  color: 'primary',
+                  letterSpacing: '-0.02em'
+                }}
+              >
+                {value ?? '—'}
+              </Box>
+              <Box
+                sx={{
+                  fontFamily: 'heading',
+                  fontSize: '0.6rem',
+                  fontWeight: 'normal',
+                  lineHeight: 1.2,
+                  color: 'textMuted',
+                  textTransform: 'uppercase',
+                  letterSpacing: '0.06em',
+                  whiteSpace: 'nowrap'
+                }}
+              >
+                {displayName ?? ''}
+              </Box>
             </Box>
-          )}
-          {children}
-        </Heading>
-        {aside}
-      </Box>
-      {((Array.isArray(metrics) && metrics.length > 0) || metricsLoading) && (
-        <Box sx={metricsStyles}>
-          <ProfileMetricsBadge compact isLoading={metricsLoading} metrics={metrics} />
+          ))}
         </Box>
       )}
     </Box>

package/src/widget-header.spec.js

@@ -29,22 +29,25 @@ describe('WidgetHeader', () => {
     const metrics = [{ displayName: 'Stars', id: 's', value: 12 }]
     const { getByText } = render(
       <ThemeUIProvider theme={chronogroveTheme}>
-        <WidgetHeader metrics={metrics}>Title</WidgetHeader>
+        <WidgetHeader icon={mockIcon} metrics={metrics}>
+          Title
+        </WidgetHeader>
       </ThemeUIProvider>
     )
-    expect(getByText('12 Stars')).toBeInTheDocument()
+    expect(getByText('12')).toBeInTheDocument()
+    expect(getByText('Stars')).toBeInTheDocument()
   })
 
   it('renders loading metrics placeholders when metricsLoading', () => {
-    const { container } = render(
+    render(
       <ThemeUIProvider theme={chronogroveTheme}>
-        <WidgetHeader metrics={[]} metricsLoading>
+        <WidgetHeader icon={mockIcon} metrics={[]} metricsLoading>
           Title
         </WidgetHeader>
       </ThemeUIProvider>
     )
-    const badges = container.querySelectorAll('[class*="css-"]')
-    expect(badges.length).toBeGreaterThan(0)
+    const placeholders = screen.getAllByText('—')
+    expect(placeholders).toHaveLength(2)
   })
 
   it('renders without icon', () => {
@@ -57,20 +60,73 @@ describe('WidgetHeader', () => {
     expect(screen.queryByTestId('fa-icon')).not.toBeInTheDocument()
   })
 
-  it('uses borderColor fallback when gray[4] is missing', () => {
-    const themeMissingGray4 = {
+  it('renders metric chips when theme omits gray scale entries', () => {
+    const themeMissingGray = {
       ...chronogroveTheme,
       colors: {
         ...chronogroveTheme.colors,
-        gray: { 0: '#111', 1: '#222', 2: '#333', 3: '#444' }
+        gray: undefined
       }
     }
-    const { container } = render(
-      <ThemeUIProvider theme={themeMissingGray4}>
-        <WidgetHeader>Border test</WidgetHeader>
+    render(
+      <ThemeUIProvider theme={themeMissingGray}>
+        <WidgetHeader icon={mockIcon} metrics={[{ displayName: 'X', id: 'x', value: 1 }]}>
+          Border test
+        </WidgetHeader>
       </ThemeUIProvider>
     )
-    expect(container.querySelector('header')).toBeTruthy()
     expect(screen.getByText('Border test')).toBeInTheDocument()
+    expect(screen.getByText('1')).toBeInTheDocument()
+    expect(screen.getByText('X')).toBeInTheDocument()
+  })
+
+  it('renders icon chip when theme omits primaryRgb (shadow fallback)', () => {
+    const colorsRest = { ...chronogroveTheme.colors }
+    delete colorsRest.primaryRgb
+    const themeNoPrimaryRgb = { ...chronogroveTheme, colors: colorsRest }
+    render(
+      <ThemeUIProvider theme={themeNoPrimaryRgb}>
+        <WidgetHeader icon={mockIcon}>Chip</WidgetHeader>
+      </ThemeUIProvider>
+    )
+    expect(screen.getByText('Chip')).toBeInTheDocument()
+    expect(screen.getByTestId('fa-icon')).toBeInTheDocument()
+  })
+
+  it('renders metric chip border when theme omits colors.text (fallback)', () => {
+    const colorsRest = { ...chronogroveTheme.colors }
+    delete colorsRest.text
+    const themeNoText = { ...chronogroveTheme, colors: colorsRest }
+    render(
+      <ThemeUIProvider theme={themeNoText}>
+        <WidgetHeader icon={mockIcon} metrics={[{ displayName: 'Y', id: 'y', value: 2 }]}>
+          T
+        </WidgetHeader>
+      </ThemeUIProvider>
+    )
+    expect(screen.getByText('2')).toBeInTheDocument()
+    expect(screen.getByText('Y')).toBeInTheDocument()
+  })
+
+  it('handles metrics array with undefined entry (default destructuring)', () => {
+    render(
+      <ThemeUIProvider theme={chronogroveTheme}>
+        <WidgetHeader icon={mockIcon} metrics={[undefined]}>
+          T
+        </WidgetHeader>
+      </ThemeUIProvider>
+    )
+    expect(screen.getByText('—')).toBeInTheDocument()
+  })
+
+  it('uses metricsToShow empty array when metrics is not an array', () => {
+    render(
+      <ThemeUIProvider theme={chronogroveTheme}>
+        <WidgetHeader icon={mockIcon} metrics={null}>
+          No metrics prop array
+        </WidgetHeader>
+      </ThemeUIProvider>
+    )
+    expect(screen.getByText('No metrics prop array')).toBeInTheDocument()
   })
 })

package/src/widget-section.js

@@ -13,7 +13,7 @@ const sectionSx = {
 /**
  * Wraps a dashboard widget: vertical spacing and optional fatal-error overlay.
  */
-const WidgetSection = ({ children, hasFatalError, id, styleOverrides = {}, ...props }) => {
+const WidgetSection = ({ children, hasFatalError, id, styleOverrides = {}, tabIndex, ...props }) => {
   const { colorMode } = useThemeUI()
   const darkMode = isDarkMode(colorMode)
 
@@ -30,6 +30,7 @@ const WidgetSection = ({ children, hasFatalError, id, styleOverrides = {}, ...pr
           : {})
       }}
       {...(id ? { id } : {})}
+      tabIndex={id ? (tabIndex ?? -1) : tabIndex}
       {...props}
     >
       {hasFatalError && (

package/src/widget-section.spec.js

@@ -36,6 +36,38 @@ describe('WidgetSection', () => {
     expect(document.getElementById('w1')).toBeTruthy()
   })
 
+  it('sets tabIndex -1 when id is provided so the section can receive programmatic focus', () => {
+    useThemeUI.mockReturnValue({ colorMode: 'default' })
+    render(
+      <ThemeUIProvider theme={{}}>
+        <WidgetSection id='w1'>x</WidgetSection>
+      </ThemeUIProvider>
+    )
+    expect(document.getElementById('w1')).toHaveAttribute('tabindex', '-1')
+  })
+
+  it('respects an explicit tabIndex when id is provided', () => {
+    useThemeUI.mockReturnValue({ colorMode: 'default' })
+    render(
+      <ThemeUIProvider theme={{}}>
+        <WidgetSection id='w1' tabIndex={0}>
+          x
+        </WidgetSection>
+      </ThemeUIProvider>
+    )
+    expect(document.getElementById('w1')).toHaveAttribute('tabindex', '0')
+  })
+
+  it('does not set tabIndex when id is omitted', () => {
+    useThemeUI.mockReturnValue({ colorMode: 'default' })
+    render(
+      <ThemeUIProvider theme={{}}>
+        <WidgetSection>plain</WidgetSection>
+      </ThemeUIProvider>
+    )
+    expect(screen.getByText('plain').closest('section')).not.toHaveAttribute('tabindex')
+  })
+
   it('shows fatal error overlay', () => {
     useThemeUI.mockReturnValue({ colorMode: 'dark' })
     render(