@cdc/core 4.25.11 → 4.26.2

package/helpers/prepareScreenshot.ts

@@ -0,0 +1,288 @@
+/**
+ * Helpers for preparing screenshot containers for image downloads
+ */
+
+export interface ClonedElements {
+  clonedTree: HTMLElement
+  clonedViz: HTMLElement
+}
+
+interface VisualizationWrapper {
+  parentChildren: Element[]
+  wrapperIndex: number
+}
+
+/**
+ * Walk up from viz to find a parent container that has:
+ * - Multiple children
+ * - At least one child (before viz) that contains H2/H3 but NOT the viz
+ *
+ * Stops climbing at section boundaries (never goes above <section> or .dfe-section)
+ */
+function findParentWithContext(viz: HTMLElement): HTMLElement | null {
+  let current = viz.parentElement
+
+  while (current) {
+    const isSection = current.tagName === 'SECTION' || current.classList.contains('dfe-section')
+
+    const children = Array.from(current.children)
+
+    // Need at least 2 children (heading + viz wrapper)
+    if (children.length < 2) {
+      if (isSection) {
+        return null
+      }
+      current = current.parentElement
+      continue
+    }
+
+    // Find which child contains the viz (guaranteed to exist since we're walking up from viz)
+    const vizChildIndex = children.findIndex(child => child.contains(viz))
+
+    // Check children before the viz for heading
+    for (let i = 0; i < vizChildIndex; i++) {
+      const child = children[i] as HTMLElement
+      const isHeading = child.tagName === 'H2' || child.tagName === 'H3'
+      const containsHeading = child.querySelector('h2, h3') !== null
+
+      if (isHeading || containsHeading) {
+        return current
+      }
+    }
+
+    // Don't climb above section boundaries
+    if (isSection) {
+      return null
+    }
+
+    // No suitable heading found in this parent's children, go up
+    current = current.parentElement
+  }
+
+  return null
+}
+
+/**
+ * Find which direct child of the parent container contains the visualization
+ */
+function findVisualizationWrapper(viz: HTMLElement, parent: Element): VisualizationWrapper {
+  const parentChildren = Array.from(parent.children)
+  const wrapperIndex = parentChildren.findIndex(child => child.contains(viz))
+  return { parentChildren, wrapperIndex }
+}
+
+/**
+ * Walk backwards from viz to find nearest H2 or H3
+ * Stops early if another visualization is encountered
+ */
+function findNearestHeadingIndex(parentChildren: Element[], vizWrapperIndex: number): number {
+  for (let i = vizWrapperIndex - 1; i >= 0; i--) {
+    const child = parentChildren[i] as HTMLElement
+
+    // STOP: Another visualization found - don't include its content
+    if (child.classList.contains('cdc-open-viz-module') || child.querySelector('.cdc-open-viz-module')) {
+      return -1
+    }
+
+    // Found direct H2/H3
+    if (child.tagName === 'H2' || child.tagName === 'H3') {
+      return i
+    }
+
+    // Found nested H2/H3
+    if (child.querySelector('h2, h3')) {
+      return i
+    }
+  }
+
+  return -1 // No heading found
+}
+
+/**
+ * Build cloned parent container with only selected children (heading through viz)
+ */
+function buildContextClone(
+  parent: Element,
+  headingIndex: number,
+  vizWrapperIndex: number,
+  elementToCapture: string
+): ClonedElements {
+  const parentChildren = Array.from(parent.children)
+
+  // Shallow clone parent (preserves classes/styling)
+  const clonedTree = parent.cloneNode(false) as HTMLElement
+
+  // Append only selected children (heading → viz wrapper)
+  for (let i = headingIndex; i <= vizWrapperIndex; i++) {
+    clonedTree.appendChild(parentChildren[i].cloneNode(true))
+  }
+
+  // Find viz in cloned tree
+  const clonedViz = clonedTree.querySelector(`[data-download-id="${elementToCapture}"]`) as HTMLElement
+
+  // Container styling adjustments
+  clonedTree.style.marginBottom = '0'
+
+  // Remove top margin from context headings (not inside viz)
+  const allHeadings = clonedTree.querySelectorAll('h2, h3')
+  allHeadings.forEach(heading => {
+    if (!clonedViz.contains(heading)) {
+      ;(heading as HTMLElement).style.marginTop = '0'
+    }
+  })
+
+  return { clonedTree, clonedViz }
+}
+
+function isInEditorMode(element: HTMLElement): boolean {
+  return element.closest('.cdc-open-viz-module.isEditor') !== null
+}
+
+/**
+ * Prepare cloned elements (with or without context)
+ * Returns viz-only clone as fallback for any failure
+ * Exported for testing
+ */
+export function prepareClonedElements(
+  baseSvg: HTMLElement,
+  includeContextInDownload: boolean,
+  elementToCapture: string
+): ClonedElements {
+  const defaultClone = (): ClonedElements => {
+    const tree = baseSvg.cloneNode(true) as HTMLElement
+    return { clonedTree: tree, clonedViz: tree }
+  }
+
+  // Early return: context not requested or in editor mode (editor downloads should not include context)
+  if (!includeContextInDownload || isInEditorMode(baseSvg)) {
+    return defaultClone()
+  }
+
+  // Early return: no parent with context found
+  const parent = findParentWithContext(baseSvg)
+  if (!parent) {
+    return defaultClone()
+  }
+
+  // Get viz wrapper (guaranteed to exist since findParentWithContext found it)
+  const { parentChildren, wrapperIndex } = findVisualizationWrapper(baseSvg, parent as Element)
+
+  // Early return: no heading found (or another viz in the way)
+  const headingIndex = findNearestHeadingIndex(parentChildren, wrapperIndex)
+  if (headingIndex < 0) {
+    return defaultClone()
+  }
+
+  // Build with context
+  return buildContextClone(parent, headingIndex, wrapperIndex, elementToCapture)
+}
+
+/**
+ * Strip all <a> tags from cloned tree (links aren't clickable in PNG)
+ */
+function stripLinks(clonedTree: HTMLElement): void {
+  const allLinks = clonedTree.querySelectorAll('a')
+  allLinks.forEach(link => {
+    const textNode = document.createTextNode(link.textContent || '')
+    link.parentNode?.replaceChild(textNode, link)
+  })
+}
+
+/**
+ * Convert canvas elements to images (canvas pixel data doesn't clone)
+ */
+function convertCanvasToImages(baseSvg: HTMLElement, clonedViz: HTMLElement): void {
+  const originalCanvases = baseSvg.querySelectorAll('canvas')
+  const clonedCanvases = clonedViz.querySelectorAll('canvas')
+
+  clonedCanvases.forEach((clonedCanvas, index) => {
+    const originalCanvas = originalCanvases[index] as HTMLCanvasElement
+    if (originalCanvas && originalCanvas.width > 0 && originalCanvas.height > 0) {
+      const img = document.createElement('img')
+      img.src = originalCanvas.toDataURL('image/png')
+      img.width = originalCanvas.width
+      img.height = originalCanvas.height
+      img.className = originalCanvas.className
+      clonedCanvas.parentNode?.replaceChild(img, clonedCanvas)
+    }
+  })
+}
+
+/**
+ * Remove width classes that interfere with screenshot sizing
+ */
+function removeWidthClasses(clonedTree: HTMLElement): void {
+  const classesToRemove = ['dfe-block--width-wide', 'dfe-block--width-full_width']
+
+  classesToRemove.forEach(className => {
+    const elements = clonedTree.querySelectorAll(`.${className}`)
+    elements.forEach(el => el.classList.remove(className))
+  })
+
+  // Also check the root element itself
+  classesToRemove.forEach(className => {
+    clonedTree.classList.remove(className)
+  })
+}
+
+/**
+ * Expand SVG widths and remove animation classes
+ */
+function expandSvgWidths(clonedViz: HTMLElement): void {
+  const svgWidthBuffer = 25
+  const svgElements = clonedViz.querySelectorAll('svg')
+
+  svgElements.forEach(svg => {
+    const currentWidth = parseInt(svg.getAttribute('width') || '0')
+    if (currentWidth > 0) {
+      svg.setAttribute('width', (currentWidth + svgWidthBuffer).toString())
+    }
+
+    // Remove animation classes to show final state immediately
+    svg.classList.remove('animated', 'animate')
+  })
+}
+
+/**
+ * Main function: Prepare a complete container ready for html2canvas screenshot
+ */
+export function prepareScreenshotContainer(
+  baseSvg: HTMLElement,
+  includeContextInDownload: boolean,
+  elementToCapture: string
+): HTMLDivElement {
+  // 1. Clone elements (with or without context)
+  const { clonedTree, clonedViz } = prepareClonedElements(baseSvg, includeContextInDownload, elementToCapture)
+
+  // 2. Remove width classes that interfere with screenshot sizing
+  removeWidthClasses(clonedTree)
+
+  // 3. Strip all links (not clickable in static image)
+  stripLinks(clonedTree)
+
+  // 4. Convert canvas elements to images
+  convertCanvasToImages(baseSvg, clonedViz)
+
+  // 5. Expand SVG widths to prevent clipping
+  expandSvgWidths(clonedViz)
+
+  // 6. Calculate viz dimensions
+  const computedStyle = getComputedStyle(baseSvg)
+  const vizWidth =
+    parseFloat(computedStyle.width) -
+    (parseFloat(computedStyle.paddingLeft) || 0) -
+    (parseFloat(computedStyle.paddingRight) || 0)
+
+  // 7. Create and style container
+  const container = document.createElement('div')
+  container.style.width = `${vizWidth + 36}px`
+  container.style.padding = '18px'
+
+  // 8. Reset viz padding
+  clonedViz.style.padding = '0'
+
+  // 9. Append cloned tree to container
+  container.appendChild(clonedTree)
+
+  return container
+}

package/helpers/queryStringUtils.ts

@@ -13,6 +13,35 @@ export function getQueryStringFilterValue(filter) {
   }
 }
 
+/**
+ * Check if a filter should be hidden based on URL query parameters
+ * Checks for hide{setByQueryParameter}=true|1|yes in the URL
+ *
+ * @param filter - Filter object with setByQueryParameter property
+ * @returns true if filter should be hidden, false otherwise
+ *
+ * @example
+ * // If filter has setByQueryParameter: "state"
+ * // URL: ?hidestate=true  -> returns true
+ * // URL: ?hideState=true  -> returns false (case sensitive!)
+ */
+export function isFilterHiddenByQuery(filter) {
+  if (!filter) return false
+
+  // Only check setByQueryParameter - this is the standard way filters are identified in URL params
+  const paramName = filter.setByQueryParameter
+  if (!paramName) return false
+
+  const urlParams = new URLSearchParams(window.location.search)
+  const hideParamName = `hide${paramName}`
+  const hideValue = urlParams.get(hideParamName)
+
+  if (!hideValue) return false
+
+  const lower = hideValue.toLowerCase()
+  return lower === 'true' || hideValue === '1' || lower === 'yes'
+}
+
 export function getQueryParams() {
   const queryParams = {}
   for (const [key, value] of Array.from(new URLSearchParams(window.location.search).entries())) {

package/helpers/testing.ts

@@ -313,6 +313,50 @@ export const testBooleanControl = async (checkbox: HTMLInputElement, getVisualSt
   expect(secondToggleVisualState).toEqual(initialVisualState)
 }
 
+// ============================================================================
+// VISUALIZATION RENDERING ASSERTIONS
+// ============================================================================
+
+/**
+ * Assert that a visualization has rendered successfully.
+ * Uses performAndAssert to poll until one of these conditions is met:
+ *   ((svgCount > 0 || canvasCount > 0) && hasCoveModule) || isDataBite || isDataTable
+ *
+ * Handles all visualization types:
+ * - Charts (SVG-based)
+ * - Maps with SVG rendering (US state, world, hex, etc.)
+ * - Maps with canvas rendering (county maps via UsaMap.County)
+ * - Data bites (.bite-content)
+ * - Data tables (.data-table)
+ * - Waffle charts (SVG-based)
+ *
+ * Use as a play function in any Components/Templates/ story:
+ *   play: async ({ canvasElement }) => {
+ *     await assertVisualizationRendered(canvasElement)
+ *   }
+ *
+ * @param vizElement The story's canvas element (Storybook's canvasElement)
+ */
+export const assertVisualizationRendered = async (vizElement: HTMLElement) => {
+  await performAndAssert(
+    'Wait for visualization to render',
+    () => {
+      const svgCount = vizElement.querySelectorAll('svg').length
+      const canvasCount = vizElement.querySelectorAll('canvas').length
+      const hasCoveModule = !!vizElement.querySelector('.cdc-open-viz-module')
+      const isDataBite = !!vizElement.querySelector('.bite-content')
+      const isDataTable = !!vizElement.querySelector('.type-data-table')
+      return { svgCount, canvasCount, hasCoveModule, isDataBite, isDataTable }
+    },
+    async () => {},
+    (_before, after) => {
+      return (
+        ((after.svgCount > 0 || after.canvasCount > 0) && after.hasCoveModule) || after.isDataBite || after.isDataTable
+      )
+    }
+  )
+}
+
 // ============================================================================
 // DATA EXTRACTION HELPERS
 // ============================================================================

package/helpers/tests/DataTransform.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect } from 'vitest'
+import DataTransform from '../DataTransform'
+
+describe('DataTransform', () => {
+  let transformer: DataTransform
+
+  beforeEach(() => {
+    transformer = new DataTransform()
+  })
+
+  describe('autoStandardize', () => {
+    it('returns undefined for empty data', () => {
+      expect(transformer.autoStandardize([])).toBeUndefined()
+      expect(transformer.autoStandardize(null)).toBeUndefined()
+      expect(transformer.autoStandardize(undefined)).toBeUndefined()
+    })
+
+    it('returns undefined for invalid data format', () => {
+      expect(transformer.autoStandardize(['string', 'array'])).toBeUndefined()
+      expect(transformer.autoStandardize([1, 2, 3])).toBeUndefined()
+    })
+
+    it('returns data unchanged when already in object format', () => {
+      const data = [
+        { name: 'Alice', value: 10 },
+        { name: 'Bob', value: 20 }
+      ]
+      const result = transformer.autoStandardize(data)
+      expect(result).toEqual(data)
+    })
+
+    it('converts array of arrays to array of objects', () => {
+      const data = [
+        ['name', 'value'],
+        ['Alice', 10],
+        ['Bob', 20]
+      ]
+      const result = transformer.autoStandardize(data)
+      expect(result).toEqual([
+        { name: 'Alice', value: 10 },
+        { name: 'Bob', value: 20 }
+      ])
+    })
+
+    it('handles array of arrays with multiple columns', () => {
+      const data = [
+        ['state', 'year', 'population'],
+        ['CA', 2020, 39538223],
+        ['TX', 2020, 29145505]
+      ]
+      const result = transformer.autoStandardize(data)
+      expect(result).toEqual([
+        { state: 'CA', year: 2020, population: 39538223 },
+        { state: 'TX', year: 2020, population: 29145505 }
+      ])
+    })
+  })
+
+  describe('cleanDataPoint', () => {
+    it('removes commas from numbers', () => {
+      expect(transformer.cleanDataPoint('1,234')).toBe('1234')
+      expect(transformer.cleanDataPoint('1,234,567')).toBe('1234567')
+    })
+
+    it('removes dollar signs', () => {
+      expect(transformer.cleanDataPoint('$100')).toBe('100')
+      expect(transformer.cleanDataPoint('$1,234')).toBe('1234')
+    })
+
+    it('removes percent signs', () => {
+      expect(transformer.cleanDataPoint('50%')).toBe('50')
+      expect(transformer.cleanDataPoint('99.9%')).toBe('99.9')
+    })
+
+    it('handles combined formatting', () => {
+      expect(transformer.cleanDataPoint('$1,234,567')).toBe('1234567')
+    })
+
+    it('handles null and empty values', () => {
+      expect(transformer.cleanDataPoint(null)).toBe('')
+      expect(transformer.cleanDataPoint('')).toBe('')
+    })
+
+    it('handles non-string values', () => {
+      expect(transformer.cleanDataPoint(123)).toBe(123)
+      expect(transformer.cleanDataPoint(0)).toBe(0)
+    })
+
+    it('returns plain numbers unchanged', () => {
+      expect(transformer.cleanDataPoint('123')).toBe('123')
+      expect(transformer.cleanDataPoint('45.67')).toBe('45.67')
+    })
+  })
+
+  describe('developerStandardize', () => {
+    it('returns empty array when data is falsy', () => {
+      expect(transformer.developerStandardize(null, {})).toEqual([])
+      expect(transformer.developerStandardize(undefined, {})).toEqual([])
+    })
+
+    it('returns undefined when description is missing', () => {
+      const data = [{ a: 1 }]
+      expect(transformer.developerStandardize(data, null)).toBeUndefined()
+      expect(transformer.developerStandardize(data, undefined)).toBeUndefined()
+    })
+
+    it('returns undefined when description is incomplete', () => {
+      const data = [{ a: 1 }]
+      expect(transformer.developerStandardize(data, {})).toBeUndefined()
+      expect(transformer.developerStandardize(data, { horizontal: true })).toBeUndefined()
+      expect(transformer.developerStandardize(data, { series: true })).toBeUndefined()
+    })
+
+    it('handles horizontal data without series', () => {
+      const data = [
+        { category: 'A', val1: 10, val2: 20 },
+        { category: 'B', val1: 30, val2: 40 }
+      ]
+      const description = { horizontal: true, series: false }
+      const result = transformer.developerStandardize(data, description)
+      expect(result).toBeDefined()
+      expect(Array.isArray(result)).toBe(true)
+    })
+  })
+})

package/helpers/tests/date.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest'
+import { getDateRenderFormat, formatDate } from '../cove/date'
+
+const NBSP = '\u00A0'
+
+describe('getDateRenderFormat', () => {
+  it('replaces space between %b. and %-d with NBSP', () => {
+    expect(getDateRenderFormat('%b. %-d %Y')).toBe(`%b.${NBSP}%-d %Y`)
+  })
+
+  it('replaces space between %b and %-d with NBSP', () => {
+    expect(getDateRenderFormat('%b %-d %Y')).toBe(`%b${NBSP}%-d %Y`)
+  })
+
+  it('replaces space between %B and %-d (full month name)', () => {
+    expect(getDateRenderFormat('%B %-d, %Y')).toBe(`%B${NBSP}%-d, %Y`)
+  })
+
+  it('leaves format unchanged when no month-day space pattern', () => {
+    expect(getDateRenderFormat('%Y-%m-%d')).toBe('%Y-%m-%d')
+  })
+
+  it('does not replace existing NBSP (idempotent)', () => {
+    const alreadyNbsp = `%b.${NBSP}%-d %Y`
+    expect(getDateRenderFormat(alreadyNbsp)).toBe(alreadyNbsp)
+  })
+
+  it('returns undefined for undefined input', () => {
+    expect(getDateRenderFormat(undefined)).toBeUndefined()
+  })
+
+  it('returns empty string for empty string input', () => {
+    expect(getDateRenderFormat('')).toBe('')
+  })
+})
+
+describe('formatDate', () => {
+  it('renders date with NBSP when format has space between month and day', () => {
+    const date = new Date(2025, 0, 15) // Jan 15, 2025
+    const result = formatDate('%b. %-d %Y', date)
+    expect(result).toContain(NBSP)
+    expect(result).toBe(`Jan.${NBSP}15 2025`)
+  })
+
+  it('strips trailing period from "May." when using %b. format', () => {
+    const date = new Date(2025, 4, 15) // May 15, 2025
+    const result = formatDate('%b. %-d, %Y', date)
+    expect(result).not.toContain('May.')
+    expect(result).toContain('May')
+  })
+
+  it('leaves "May" alone when format does not use %b.', () => {
+    const date = new Date(2025, 4, 15) // May 15, 2025
+    const result = formatDate('%b %-d, %Y', date)
+    expect(result).toContain('May')
+    expect(result).not.toContain('May.')
+  })
+
+  it('does not strip period from other months when using %b. format', () => {
+    const date = new Date(2025, 0, 15) // Jan 15, 2025
+    const result = formatDate('%b. %-d, %Y', date)
+    expect(result).toContain('Jan.')
+  })
+})