@cdc/core 4.26.1 → 4.26.2

package/helpers/embed/filterUtils.ts

@@ -0,0 +1,121 @@
+/**
+ * Utilities for working with COVE filters in embed contexts
+ */
+
+export type FilterMetadata = {
+  label: string
+  key: string
+  setByQueryParameter?: string
+  values?: any[]
+  defaultValue?: string
+  active?: string
+}
+
+export type FilterState = {
+  value: string
+  hide: boolean
+}
+
+/**
+ * Extract filter metadata from a COVE config
+ * Handles both regular viz filters and dashboard shared filters
+ */
+export function extractFilters(config: any): FilterMetadata[] {
+  if (!config) return []
+
+  // Try regular filters first (charts, maps, etc.)
+  if (config.filters && Array.isArray(config.filters) && config.filters.length > 0) {
+    return config.filters.map(filter => normalizeFilter(filter))
+  }
+
+  // Try dashboard shared filters
+  if (config.dashboard?.sharedFilters && Array.isArray(config.dashboard.sharedFilters)) {
+    return config.dashboard.sharedFilters.map(filter => normalizeFilter(filter))
+  }
+
+  return []
+}
+
+/**
+ * Normalize a filter object to consistent metadata format
+ *
+ * Different filter types (chart filters vs dashboard filters) may use different field names.
+ * This function provides fallbacks to handle these variations:
+ *
+ * - label: Priority for readability: label > setByQueryParameter > columnName
+ * - key: May be called key, columnName, or id depending on the viz type
+ * - setByQueryParameter: MUST be used exactly as provided. COVE only recognizes this specific
+ *   field for URL parameters - there are no fallbacks. Filters without this field cannot be
+ *   controlled via URL parameters.
+ */
+function normalizeFilter(filter: any): FilterMetadata {
+  const normalized = {
+    label: filter.label || filter.setByQueryParameter || filter.columnName || 'Unnamed Filter',
+    key: filter.key || filter.columnName || String(filter.id) || '',
+    setByQueryParameter: filter.setByQueryParameter,
+    values: filter.values || [],
+    defaultValue: filter.defaultValue,
+    active: filter.active
+  }
+  return normalized
+}
+
+/**
+ * Get initial/default value for a filter
+ */
+export function getDefaultFilterValue(filter: FilterMetadata): string {
+  if (filter.defaultValue) return filter.defaultValue
+  if (filter.active) return filter.active
+  if (filter.values && filter.values.length > 0) return filter.values[0]
+  return ''
+}
+
+/**
+ * Initialize filter state from filter metadata
+ */
+export function initializeFilterState(filters: FilterMetadata[]): Record<string, FilterState> {
+  const state: Record<string, FilterState> = {}
+
+  filters.forEach(filter => {
+    state[filter.key] = {
+      value: getDefaultFilterValue(filter),
+      hide: false
+    }
+  })
+
+  return state
+}
+
+/**
+ * Build URL parameters from filter state
+ * Returns an object with URL parameters for both filter values and hide states
+ */
+export function buildFilterUrlParams(
+  filters: FilterMetadata[],
+  filterState: Record<string, FilterState>
+): Record<string, string> {
+  const urlParams: Record<string, string> = {}
+
+  filters.forEach(filter => {
+    if (!filter.setByQueryParameter) {
+      return
+    }
+
+    const state = filterState[filter.key]
+    if (!state) {
+      return
+    }
+
+    // Add filter value
+    if (state.value) {
+      urlParams[filter.setByQueryParameter] = state.value
+    }
+
+    // Add hide parameter
+    if (state.hide) {
+      urlParams[`hide${filter.setByQueryParameter}`] = 'true'
+    }
+  })
+
+  return urlParams
+}

package/helpers/embed/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Embed-related helpers for COVE visualizations
+ * Used for generating embed codes and managing filter customization
+ */
+
+export { generateEmbedCode, getEmbedPageUrl, getHelperScriptUrl, isDevMode } from './embedCodeGenerator'
+
+export {
+  extractFilters,
+  getDefaultFilterValue,
+  initializeFilterState,
+  buildFilterUrlParams,
+  type FilterMetadata,
+  type FilterState
+} from './filterUtils'
+
+export { getConfigUrlParam, isValidConfigUrl, isValidMessageOrigin } from './urlValidation'
+
+// Import embed helper to initialize iframe resizing
+// This runs immediately when imported
+import './embedHelper.js'

package/helpers/embed/urlValidation.ts

@@ -0,0 +1,119 @@
+/**
+ * URL validation utilities for embed functionality
+ */
+
+/**
+ * Gets and validates the configUrl parameter from the current URL
+ * Returns the validated configUrl if it's a valid relative URL, null otherwise
+ *
+ * @returns The validated configUrl or null if missing/invalid
+ *
+ * @example
+ * const configUrl = getConfigUrlParam()
+ * if (!configUrl) {
+ *   // Show error - missing or invalid
+ * }
+ */
+export function getConfigUrlParam(): string | null {
+  const params = new URLSearchParams(window.location.search)
+  const configUrl = params.get('configUrl')
+
+  if (!configUrl) {
+    return null
+  }
+
+  // Validate that it's a relative URL
+  if (!isValidConfigUrl(configUrl)) {
+    return null
+  }
+
+  return configUrl
+}
+
+/**
+ * Validates that a configUrl is a relative URL (no protocol or host)
+ *
+ * Only relative URLs are allowed to ensure configs
+ * are loaded from the same origin as the embed page.
+ *
+ * @param configUrl - The URL to validate
+ * @returns true if the URL is valid (relative only), false otherwise
+ *
+ * @example
+ * isValidConfigUrl('/path/to/config.json') // true
+ * isValidConfigUrl('../config.json') // true
+ * isValidConfigUrl('config.json') // true
+ * isValidConfigUrl('https://evil.com/config.json') // false
+ * isValidConfigUrl('//evil.com/config.json') // false
+ * isValidConfigUrl('http://localhost/config.json') // false
+ */
+export function isValidConfigUrl(configUrl: string | null): boolean {
+  if (!configUrl || typeof configUrl !== 'string') {
+    return false
+  }
+
+  const trimmed = configUrl.trim()
+
+  if (trimmed.length === 0) {
+    return false
+  }
+
+  // Reject any URL that contains a protocol (http://, https://, ftp://, etc.)
+  if (trimmed.match(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//)) {
+    return false
+  }
+
+  // Reject protocol-relative URLs (//example.com/path)
+  if (trimmed.startsWith('//')) {
+    return false
+  }
+
+  // Reject URLs with protocols but no slashes (javascript:, data:, etc.)
+  if (trimmed.match(/^[a-zA-Z][a-zA-Z0-9+.-]*:/)) {
+    return false
+  }
+
+  // Additional validation: Try to parse it as a URL relative to current origin
+  try {
+    const parsed = new URL(trimmed, window.location.origin)
+
+    // Verify it's same origin
+    if (parsed.origin !== window.location.origin) {
+      return false
+    }
+
+    return true
+  } catch (error) {
+    return false
+  }
+}
+
+/**
+ * Validates a postMessage origin against allowed CDC domains
+ *
+ * @param origin - The origin to validate (from MessageEvent.origin)
+ * @returns true if the origin is allowed, false otherwise
+ */
+export function isValidMessageOrigin(origin: string): boolean {
+  if (!origin || typeof origin !== 'string') {
+    return false
+  }
+
+  try {
+    const url = new URL(origin)
+
+    // Allow localhost for development (HTTP only)
+    if (url.hostname === 'localhost' || url.hostname === '127.0.0.1') {
+      return url.protocol === 'http:' || url.protocol === 'https:'
+    }
+
+    // Allow cdc.gov and any subdomain (HTTPS only)
+    if (url.hostname === 'cdc.gov' || url.hostname.endsWith('.cdc.gov')) {
+      return url.protocol === 'https:'
+    }
+
+    return false
+  } catch (error) {
+    return false
+  }
+}

package/helpers/filterVizData.ts

@@ -16,10 +16,15 @@ export const filterVizData = (filters: Filter[], data) => {
     return []
   }
 
+  if (!Array.isArray(data)) {
+    console.warn('COVE: Data is not an array, received:', typeof data)
+    return []
+  }
+
   if (!filters) return data
   const filteredData: any[] = []
 
-  data?.forEach(row => {
+  data.forEach(row => {
     let add = true
     filters
       .filter(filter => filter.type !== 'url')

package/helpers/getFileExtension.ts

@@ -1,9 +1,3 @@
-// export const getFileExtensionx = (path: string): string => {
-//   const regex = /(?:\.([^.]+))?$/
-//   const outCome: RegExpExecArray | null = regex.exec(path)
-//   return outCome ? outCome[1] : ''
-// }
-
 export const getFileExtension = (url: string): string => {
   const regexForExtension = /(?:\.([^.]+))$/
   const regexForQueryParam = /[?&]wt=(csv|json)(?:&|$)/ // Regular expression for 'wt' query parameter

package/helpers/metrics/types.ts

@@ -80,3 +80,6 @@ export type ANALYTICS_EVENT_TYPES =
 
   // Image/export events
   | 'image_download' // generic image download event
+
+  // Embed events
+  | 'embed_loaded' // fired when a visualization is loaded via the embed system

package/helpers/palettes/colorDistributions.ts

@@ -53,4 +53,4 @@ export const mapV1ColorDistribution = {
   8: [0, 2, 3, 4, 5, 6, 7, 8],
   9: [0, 1, 2, 3, 4, 5, 6, 7, 8],
   10: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
-}
+}

package/helpers/palettes/utils.ts

@@ -1,16 +1,16 @@
-import { map } from 'lodash'
 import { FALLBACK_COLOR_PALETTE_V1, FALLBACK_COLOR_PALETTE_V2, USE_V2_MIGRATION } from '../constants'
 import { getColorPaletteVersion } from '../getColorPaletteVersion'
 import { getPaletteAccessor } from '../getPaletteAccessor'
 import { chartPaletteMigrationMap } from './migratePaletteName'
 import { newMapPaletteNames } from './standardizePaletteNames'
+import { Visualization } from '../../types/Visualization'
 
 /**
  * Gets the current palette name from a visualization config
  * @param config - The visualization config object
  * @returns The current palette name or empty string if not found
  */
-export const getCurrentPaletteName = (config: any): string => {
+export const getCurrentPaletteName = (config: Partial<Visualization>): string => {
   // Check new v2 format first
   if (config?.general?.palette?.name) {
     return config.general.palette.name
@@ -35,7 +35,7 @@ export const getCurrentPaletteName = (config: any): string => {
  * @param colorPalettes - The color palettes object (e.g., mapColorPalettes, chartColorPalettes)
  * @returns The palette colors array or empty array if not found
  */
-export const getPaletteColors = (config: any, colorPalettes: any): string[] => {
+export const getPaletteColors = (config: Partial<Visualization>, colorPalettes: Record<string, Record<string, string[]>>): string[] => {
   // First check for custom colors (v2 format)
   if (config?.general?.palette?.customColors) {
     return config.general.palette.customColors
@@ -65,7 +65,7 @@ export const getPaletteColors = (config: any, colorPalettes: any): string[] => {
  * @param config - The visualization config object
  * @returns True if the config is using v1 palette configuration (which would show conversion modal)
  */
-export const isV1Palette = (config: any): boolean => {
+export const isV1Palette = (config: Partial<Visualization>): boolean => {
   // If v2 migration is disabled globally, don't treat as v1 (no conversion modal)
   if (!USE_V2_MIGRATION) {
     return false
@@ -84,7 +84,7 @@ export const isV1Palette = (config: any): boolean => {
  * @param config - The visualization config object
  * @returns The fallback palette name for the detected version
  */
-export const getFallbackColorPalette = (config: any): string => {
+export const getFallbackColorPalette = (config: Partial<Visualization>): string => {
   const paletteVersion = getColorPaletteVersion(config)
   return paletteVersion === 1 ? FALLBACK_COLOR_PALETTE_V1 : FALLBACK_COLOR_PALETTE_V2
 }
@@ -161,7 +161,7 @@ export const migratePaletteWithMap = (
  * @param config - The visualization config object
  * @returns True if backup data exists
  */
-export const hasPaletteBackup = (config: any): boolean => {
+export const hasPaletteBackup = (config: Partial<Visualization>): boolean => {
   return !!(config?.general?.palette?.backups?.length > 0)
 }
 
@@ -170,7 +170,7 @@ export const hasPaletteBackup = (config: any): boolean => {
  * @param config - The visualization config object
  * @returns The original palette name or null if no backup exists
  */
-export const getOriginalPaletteName = (config: any): string | null => {
+export const getOriginalPaletteName = (config: Partial<Visualization>): string | null => {
   const backups = config?.general?.palette?.backups
   if (!backups || backups.length === 0) return null
 
@@ -184,7 +184,7 @@ export const getOriginalPaletteName = (config: any): string | null => {
  * @param config - The visualization config object
  * @returns The original two-color palette name or null if no backup exists
  */
-export const getOriginalTwoColorPaletteName = (config: any): string | null => {
+export const getOriginalTwoColorPaletteName = (config: Partial<Visualization>): string | null => {
   const backups = config?.general?.palette?.backups
   if (!backups || backups.length === 0) return null
 
@@ -198,7 +198,7 @@ export const getOriginalTwoColorPaletteName = (config: any): string | null => {
  * @param config - The visualization config object
  * @returns True if two-color backup data exists
  */
-export const hasTwoColorPaletteBackup = (config: any): boolean => {
+export const hasTwoColorPaletteBackup = (config: Partial<Visualization>): boolean => {
   const backups = config?.general?.palette?.backups
   if (!backups || backups.length === 0) return false
   return backups.some((backup: any) => backup.type === 'twoColor')
@@ -209,7 +209,7 @@ export const hasTwoColorPaletteBackup = (config: any): boolean => {
  * @param config - The visualization config object to modify
  * @returns True if rollback was successful, false if no backup available
  */
-export const rollbackPaletteToOriginal = (config: any): boolean => {
+export const rollbackPaletteToOriginal = (config: Partial<Visualization>): boolean => {
   const backups = config?.general?.palette?.backups
   if (!backups || backups.length === 0) {
     return false
@@ -230,7 +230,7 @@ export const rollbackPaletteToOriginal = (config: any): boolean => {
     config.general.palette.version = '1.0' // Reset to v1
   }
 
-  return config
+  return true
 }
 
 /**
@@ -238,7 +238,7 @@ export const rollbackPaletteToOriginal = (config: any): boolean => {
  * @param config - The visualization config object to modify
  * @returns True if rollback was successful, false if no backup available
  */
-export const rollbackTwoColorPaletteToOriginal = (config: any): boolean => {
+export const rollbackTwoColorPaletteToOriginal = (config: Partial<Visualization>): boolean => {
   const backups = config?.general?.palette?.backups
   if (!backups || backups.length === 0) {
     return false

package/helpers/parseCsvWithQuotes.ts

@@ -2,7 +2,7 @@ import Papa from 'papaparse'
 
 /**
  * Parses CSV text while preserving newlines and commas within quoted fields.
- * 
+ *
  * @param responseText - The raw CSV text to parse
  * @param options - Parsing options
  * @param options.delimiter - The delimiter to use after processing (default: '|')
@@ -17,27 +17,28 @@ export function parseCsvWithQuotes(
   } = {}
 ): any[] {
   const { delimiter = '|', dynamicTyping = false } = options
-  
+
   const NEWLINE_PLACEHOLDER = '__COVE_NEWLINE__'
-  
+  const newlinePlaceholderRegex = new RegExp(NEWLINE_PLACEHOLDER, 'g')
+
   // Preserve newlines in quoted fields by replacing with placeholder
   const quotedFields: string[] = []
   let placeholderIndex = 0
-  let sanitizedText = responseText.replace(/("(?:[^"\\]|\\.|[\s\S])*?")/g, (match) => {
+  let sanitizedText = responseText.replace(/("(?:[^"\\]|\\.|[\s\S])*?")/g, match => {
     const preserved = match.replace(/\n/g, NEWLINE_PLACEHOLDER)
     quotedFields.push(preserved)
     return `__QUOTED_FIELD_${placeholderIndex++}__`
   })
-  
+
   // Replace commas outside quoted fields with pipe delimiter
   sanitizedText = sanitizedText.replace(/(__QUOTED_FIELD_\d+__)|,/g, (...m) => m[1] || delimiter)
-  
-  // Restore quoted fields without outer quotes
-  quotedFields.forEach((field, index) => {
-    const unquoted = field.slice(1, -1).replace(new RegExp(NEWLINE_PLACEHOLDER, 'g'), '\n')
-    sanitizedText = sanitizedText.replace(`__QUOTED_FIELD_${index}__`, unquoted)
+
+  // Restore quoted fields without outer quotes (single pass instead of N passes)
+  sanitizedText = sanitizedText.replace(/__QUOTED_FIELD_(\d+)__/g, (_, idx) => {
+    const field = quotedFields[parseInt(idx, 10)]
+    return field.slice(1, -1).replace(newlinePlaceholderRegex, '\n')
   })
-  
+
   // Parse with Papa.parse
   const parsedCsv = Papa.parse(sanitizedText, {
     header: true,
@@ -45,21 +46,21 @@ export function parseCsvWithQuotes(
     delimiter,
     dynamicTyping
   })
-  
+
   // Restore newlines in parsed data
   const restoredData = parsedCsv.data.map((row: any) => {
     const restoredRow: any = {}
     Object.keys(row).forEach(key => {
       const value = row[key]
       if (typeof value === 'string') {
-        restoredRow[key] = value.replace(new RegExp(NEWLINE_PLACEHOLDER, 'g'), '\n')
+        restoredRow[key] = value.replace(newlinePlaceholderRegex, '\n')
       } else {
         restoredRow[key] = value
       }
     })
     return restoredRow
   })
-  
+
   return restoredData
 }
 

package/helpers/prepareScreenshot.ts

@@ -208,6 +208,23 @@ function convertCanvasToImages(baseSvg: HTMLElement, clonedViz: HTMLElement): vo
   })
 }
 
+/**
+ * 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
  */
@@ -237,31 +254,34 @@ export function prepareScreenshotContainer(
   // 1. Clone elements (with or without context)
   const { clonedTree, clonedViz } = prepareClonedElements(baseSvg, includeContextInDownload, elementToCapture)
 
-  // 2. Strip all links (not clickable in static image)
+  // 2. Remove width classes that interfere with screenshot sizing
+  removeWidthClasses(clonedTree)
+
+  // 3. Strip all links (not clickable in static image)
   stripLinks(clonedTree)
 
-  // 3. Convert canvas elements to images
+  // 4. Convert canvas elements to images
   convertCanvasToImages(baseSvg, clonedViz)
 
-  // 4. Expand SVG widths to prevent clipping
+  // 5. Expand SVG widths to prevent clipping
   expandSvgWidths(clonedViz)
 
-  // 5. Calculate viz dimensions
+  // 6. Calculate viz dimensions
   const computedStyle = getComputedStyle(baseSvg)
   const vizWidth =
     parseFloat(computedStyle.width) -
     (parseFloat(computedStyle.paddingLeft) || 0) -
     (parseFloat(computedStyle.paddingRight) || 0)
 
-  // 6. Create and style container
+  // 7. Create and style container
   const container = document.createElement('div')
   container.style.width = `${vizWidth + 36}px`
   container.style.padding = '18px'
 
-  // 7. Reset viz padding
+  // 8. Reset viz padding
   clonedViz.style.padding = '0'
 
-  // 8. Append cloned tree to container
+  // 9. Append cloned tree to container
   container.appendChild(clonedTree)
 
   return container

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
 // ============================================================================