@cdc/core 4.26.1 → 4.26.3

package/helpers/embed/embedCodeGenerator.ts

@@ -0,0 +1,80 @@
+/**
+ * Generates iframe embed code for COVE visualizations
+ * Used by editor's "Share with Partners" feature
+ */
+
+interface EmbedCodeOptions {
+  configUrl: string
+  /** Additional URL parameters (e.g., filter values, hide flags) */
+  urlParams?: Record<string, string>
+}
+
+/**
+ * Detect if we're in development mode
+ */
+export function isDevMode(): boolean {
+  if (typeof window === 'undefined') return false
+  return window.location.hostname === 'localhost' || window.location.hostname === '127.0.0.1'
+}
+
+/**
+ * Get the embed page URL for creating iframes.
+ * - In dev mode: returns localhost URL
+ * - On cdc.gov domains: returns relative path for same-origin iframe loading
+ * - On partner sites: returns full absolute URL to www.cdc.gov
+ */
+export function getEmbedPageUrl(): string {
+  if (isDevMode()) {
+    return 'http://localhost:8080'
+  }
+
+  const embedPath = '/TemplatePackage/contrib/widgets/openVizWrapper/dist/embed/embed.html'
+
+  // On cdc.gov domains, use relative path for same-origin
+  if (typeof window !== 'undefined') {
+    const hostname = window.location.hostname
+    if (hostname === 'cdc.gov' || hostname.endsWith('.cdc.gov')) {
+      return embedPath
+    }
+  }
+
+  // For partner sites, use full absolute URL
+  return `https://www.cdc.gov${embedPath}`
+}
+
+/**
+ * Get default embed helper script URL based on environment
+ */
+export function getHelperScriptUrl(): string {
+  if (isDevMode()) {
+    return 'http://localhost:8080/src/embed-helper/index.js'
+  }
+  return 'https://www.cdc.gov/TemplatePackage/contrib/widgets/openVizWrapper/dist/embed/embed-helper.js'
+}
+
+/**
+ * Generate embed code for partners (div-based)
+ *
+ * @param options.configUrl - URL to the published config JSON
+ * @param options.urlParams - Additional URL parameters (e.g., filter values, hide flags)
+ * @returns HTML string with div container and script tag (width/height are hardcoded in embed-helper)
+ */
+export function generateEmbedCode(options: EmbedCodeOptions): string {
+  const { configUrl, urlParams = {} } = options
+
+  // Build full config URL with query parameters
+  const params = new URLSearchParams()
+  Object.entries(urlParams).forEach(([key, value]) => {
+    if (value) params.set(key, value)
+  })
+  const fullConfigUrl = params.toString() ? `${configUrl}?${params.toString()}` : configUrl
+
+  // Generate div-based embed code (width and height are hardcoded in embed-helper)
+  const embedCode = `<div
+  data-cove-embed
+  data-config-url="${fullConfigUrl}"
+></div>
+<script type="module" src="${getHelperScriptUrl()}"></script>`
+
+  return embedCode
+}

package/helpers/embed/embedHelper.js

@@ -0,0 +1,169 @@
+/**
+ * CDC COVE Embed Helper
+ *
+ * Standalone script that handles iframe creation and resizing for embedded COVE visualizations.
+ * Partners place a div container on their page with data-config-url attribute.
+ * This script finds the div, creates an iframe (width: 100%, initial height: 400px),
+ * and handles dynamic resizing.
+ *
+ * Usage:
+ * <div data-cove-embed data-config-url="/path/to/config.json"></div>
+ * <script src="https://www.cdc.gov/.../embed-helper.js"></script>
+ */
+
+import { isValidMessageOrigin } from './urlValidation'
+import { getEmbedPageUrl } from './embedCodeGenerator'
+
+let iframeCounter = 0
+
+// Initialize an iframe with unique ID and event listener
+function initializeIframe(iframe) {
+  // Skip if already initialized
+  if (iframe.hasAttribute('data-cove-id')) {
+    return
+  }
+
+  const id = `cove-${iframeCounter++}`
+  iframe.setAttribute('data-cove-id', id)
+
+  // Send the ID and embed page URL to the iframe via postMessage
+  const sendId = () => {
+    if (iframe.contentWindow) {
+      iframe.contentWindow.postMessage(
+        {
+          type: 'cove:setId',
+          id: id,
+          embedPageUrl: window.location.origin + window.location.pathname
+        },
+        '*'
+      )
+    }
+  }
+
+  // If iframe is already loaded, send immediately
+  if (iframe.contentDocument && iframe.contentDocument.readyState === 'complete') {
+    sendId()
+  }
+
+  // Also listen for load event in case it hasn't loaded yet
+  iframe.addEventListener('load', sendId)
+}
+
+// Create iframe from div container
+function createIframeFromContainer(container) {
+  // Skip if already processed
+  if (container.hasAttribute('data-cove-processed')) {
+    return
+  }
+  container.setAttribute('data-cove-processed', 'true')
+
+  // Read configuration from data attributes
+  const configUrl = container.dataset.configUrl
+
+  if (!configUrl) {
+    console.error('CDC COVE Embed: data-config-url attribute is required')
+    return
+  }
+
+  // Parse config URL to separate base path from query parameters
+  // data-config-url might be: "/path/config.json?state=CA&hidestate=true"
+  // We need to split into: configUrl + separate params for embed page
+  const [baseConfigUrl, queryString] = configUrl.split('?')
+
+  // Build clean URL manually (avoid encoding configUrl path)
+  let iframeSrc = `${getEmbedPageUrl()}?configUrl=${baseConfigUrl}`
+
+  // Add any additional query parameters from the config URL
+  if (queryString) {
+    iframeSrc += `&${queryString}`
+  }
+
+  // Create iframe element with hardcoded dimensions
+  const iframe = document.createElement('iframe')
+  iframe.src = iframeSrc
+
+  iframe.width = '100%'
+  iframe.height = '400'
+  iframe.frameBorder = '0'
+  iframe.title = 'CDC Data Visualization'
+  iframe.setAttribute('data-cove-embed', '')
+
+  // Apply min-height style to container
+  container.style.minHeight = '400px'
+
+  // Inject iframe into container
+  container.appendChild(iframe)
+
+  // Initialize the iframe for resizing
+  initializeIframe(iframe)
+}
+
+// Process existing div containers
+const existingContainers = document.querySelectorAll('div[data-cove-embed]')
+if (existingContainers.length > 0) {
+  existingContainers.forEach(createIframeFromContainer)
+}
+
+// Watch for dynamically added containers (for React/SPA apps)
+const observer = new MutationObserver(mutations => {
+  mutations.forEach(mutation => {
+    mutation.addedNodes.forEach(node => {
+      if (node.nodeType === Node.ELEMENT_NODE) {
+        // Check for div containers
+        if (node.matches && node.matches('div[data-cove-embed]')) {
+          createIframeFromContainer(node)
+        }
+        // Also check children in case a container was added
+        const containers = node.querySelectorAll && node.querySelectorAll('div[data-cove-embed]')
+        if (containers && containers.length > 0) {
+          containers.forEach(createIframeFromContainer)
+        }
+      }
+    })
+  })
+})
+
+// Start observing the document for iframe additions
+observer.observe(document.body, {
+  childList: true,
+  subtree: true
+})
+
+// Listen for resize messages from embedded visualizations
+window.addEventListener('message', function (event) {
+  const type = event?.data?.type
+
+  // Ignore unrelated cross-window traffic (extensions, frameworks, etc.).
+  if (typeof type !== 'string' || !type.startsWith('cove:')) {
+    return
+  }
+
+  if (!isValidMessageOrigin(event.origin)) {
+    console.warn('CDC COVE Embed Helper: Rejected COVE message from invalid origin', {
+      origin: event.origin,
+      type,
+      id: event?.data?.id
+    })
+    return
+  }
+
+  // Handle resize events
+  if (type === 'cove:resize') {
+    const iframeId = event.data.id
+    const height = event.data.height
+
+    if (!height || typeof height !== 'number') {
+      console.warn('CDC COVE Embed Helper: Invalid height received:', height)
+      return
+    }
+
+    // Find the corresponding iframe
+    const iframe = document.querySelector(`iframe[data-cove-id="${iframeId}"]`)
+
+    if (iframe) {
+      iframe.style.height = height + 'px'
+    } else {
+      console.warn(`[Embed Helper] ✗ Could not find iframe with id "${iframeId}"`)
+    }
+  }
+})

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,17 @@
+/**
+ * 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'

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/extractDataAndMetadata.ts

@@ -0,0 +1,20 @@
+type DataWithMetadata = {
+  data: any[]
+  dataMetadata: Record<string, string>
+}
+
+/**
+ * Separates a data file response into the data array and any sibling metadata fields.
+ * Supports both plain arrays (current format) and the wrapper format:
+ *   { "lastUpdated": "...", "source": "...", "data": [...] }
+ */
+export function extractDataAndMetadata(response: any): DataWithMetadata {
+  if (Array.isArray(response)) {
+    return { data: response, dataMetadata: {} }
+  }
+  if (response && typeof response === 'object' && Array.isArray(response.data)) {
+    const { data, ...dataMetadata } = response
+    return { data, dataMetadata }
+  }
+  return { data: response, dataMetadata: {} }
+}

package/helpers/fetchRemoteData.ts

@@ -1,7 +1,10 @@
 import { isSolrCsv } from '@cdc/core/helpers/isSolr'
 import { parseCsvWithQuotes } from '@cdc/core/helpers/parseCsvWithQuotes'
+import { extractDataAndMetadata } from '@cdc/core/helpers/extractDataAndMetadata'
 
-export default function fetchRemoteData(_url) {
+type FetchResult = { data: any[]; dataMetadata: Record<string, string> }
+
+export default function fetchRemoteData(_url): Promise<FetchResult> {
   let url = new URL(_url, window.location.origin)
   const path = url.pathname
   const regex = /(?:\.([^.]+))?$/
@@ -11,17 +14,20 @@ export default function fetchRemoteData(_url) {
     return fetch(url.href)
       .then(response => response.text())
       .then(responseText => {
-        return parseCsvWithQuotes(responseText, {
+        const data = parseCsvWithQuotes(responseText, {
           delimiter: '|',
           dynamicTyping: false
         })
+        return { data, dataMetadata: {} }
       })
   } else {
-    return fetch(isSolrCsv(_url) ? _url : url.href).then(response => {
-      if (!response.ok) {
-        return Promise.reject(response)
-      }
-      return response.json()
-    })
+    return fetch(isSolrCsv(_url) ? _url : url.href)
+      .then(response => {
+        if (!response.ok) {
+          return Promise.reject(response)
+        }
+        return response.json()
+      })
+      .then(json => extractDataAndMetadata(json))
   }
 }

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/labelHash.ts

@@ -14,6 +14,15 @@ export const labelHash = {
   'filtered-text': 'Filtered Text',
   dashboardFilters: 'Filter Dropdowns',
   Sankey: 'Sankey Chart',
+  Combo: 'Combo',
+  'Scatter Plot': 'Scatter Plot',
+  'Area Chart': 'Area Chart',
+  'Deviation Bar': 'Deviation Bar',
+  'Paired Bar': 'Paired Bar',
+  'Box Plot': 'Box Plot',
+  'Forest Plot': 'Forest Plot',
+  Forecasting: 'Forecasting',
+  'Warming Stripes': 'Warming Stripes',
   table: 'Table',
   'data-table': 'Data Table',
   chart: 'Chart',