@cdc/core 4.25.8 → 4.25.10

package/helpers/palettes/utils.ts

@@ -0,0 +1,267 @@
+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'
+
+/**
+ * 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 => {
+  // Check new v2 format first
+  if (config?.general?.palette?.name) {
+    return config.general.palette.name
+  }
+
+  // Check legacy v1 formats
+  if (config?.palette) {
+    return config.palette
+  }
+
+  if (config?.color) {
+    return config.color
+  }
+
+  const paletteVersion = getColorPaletteVersion(config)
+  return paletteVersion === 1 ? FALLBACK_COLOR_PALETTE_V1 : FALLBACK_COLOR_PALETTE_V2
+}
+
+/**
+ * Gets the palette colors array from a visualization config
+ * @param config - The visualization config object
+ * @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[] => {
+  // First check for custom colors (v2 format)
+  if (config?.general?.palette?.customColors) {
+    return config.general.palette.customColors
+  }
+
+  // Get the raw palette name
+  let paletteName = getCurrentPaletteName(config)
+
+  // Apply v1 palette name migrations if this is a v1 config
+  const paletteVersion = getColorPaletteVersion(config)
+  if (paletteVersion === 1) {
+    paletteName = migratePaletteWithMap(paletteName, chartPaletteMigrationMap, true)
+  }
+
+  // Get the versioned palette accessor
+  const versionedPalettes = getPaletteAccessor(colorPalettes, config)
+
+  if (paletteName && versionedPalettes?.[paletteName]) {
+    return versionedPalettes[paletteName]
+  }
+
+  return []
+}
+
+/**
+ * Determines if the config is using a v1 palette configuration
+ * @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 => {
+  // If v2 migration is disabled globally, don't treat as v1 (no conversion modal)
+  if (!USE_V2_MIGRATION) {
+    return false
+  }
+
+  const currentVersion = getColorPaletteVersion(config)
+  return (
+    currentVersion === 1 ||
+    config?.general?.palette?.version === '1.0' ||
+    !config?.general?.palette?.version
+  )
+}
+
+/**
+ * Returns the appropriate fallback color palette based on the palette version
+ * @param config - The visualization config object
+ * @returns The fallback palette name for the detected version
+ */
+export const getFallbackColorPalette = (config: any): string => {
+  const paletteVersion = getColorPaletteVersion(config)
+  return paletteVersion === 1 ? FALLBACK_COLOR_PALETTE_V1 : FALLBACK_COLOR_PALETTE_V2
+}
+
+/**
+ * Finds a palette name in a migration map using exact match first, then case-insensitive fallback
+ * @param paletteName - The palette name to look up
+ * @param migrationMap - The migration map to search in
+ * @returns The migrated palette name or null if not found
+ */
+export const findPaletteInMigrationMap = (paletteName: string, migrationMap: Record<string, string>): string | null => {
+  // Try exact match first
+  if (migrationMap[paletteName]) {
+    return migrationMap[paletteName]
+  }
+
+  // Try case-insensitive match
+  const lowerCaseName = paletteName.toLowerCase()
+  const matchingKey = Object.keys(migrationMap).find(key => key.toLowerCase() === lowerCaseName)
+
+  return matchingKey ? migrationMap[matchingKey] : null
+}
+
+/**
+ * Handles reverse palette suffix logic for chart palettes
+ * @param originalPaletteName - The original palette name that may have 'reverse' suffix
+ * @param migratedBase - The migrated base name
+ * @returns The properly formatted migrated palette name with reverse suffix if needed
+ */
+export const handleReversePalette = (originalPaletteName: string, migratedBase: string): string => {
+  const isReverse = originalPaletteName.endsWith('reverse')
+  return isReverse ? migratedBase + 'reverse' : migratedBase
+}
+
+/**
+ * Generic migration function that works with any migration map
+ * @param oldPaletteName - The palette name to migrate
+ * @param migrationMap - The migration map to use
+ * @param handleReverse - Whether to handle reverse palette suffixes (for chart palettes)
+ * @returns The migrated palette name or original if no migration found
+ */
+export const migratePaletteWithMap = (
+  oldPaletteName: string,
+  migrationMap: Record<string, string>,
+  handleReverse: boolean = false
+): string => {
+  // Handle null/undefined/empty cases - maintain original behavior
+  if (!oldPaletteName) {
+    return oldPaletteName
+  }
+
+  if (handleReverse) {
+    // Chart palette logic - handle reverse suffix
+    const isReverse = oldPaletteName.endsWith('reverse')
+    const basePaletteName = isReverse ? oldPaletteName.slice(0, -7) : oldPaletteName
+
+    const migratedBase = findPaletteInMigrationMap(basePaletteName, migrationMap)
+    if (migratedBase) {
+      return handleReversePalette(oldPaletteName, migratedBase)
+    }
+  } else {
+    // Map palette logic - direct lookup
+    const migrated = findPaletteInMigrationMap(oldPaletteName, migrationMap)
+    if (migrated) {
+      return migrated
+    }
+  }
+
+  return oldPaletteName
+}
+
+/**
+ * Checks if a config has palette backup data available for rollback
+ * @param config - The visualization config object
+ * @returns True if backup data exists
+ */
+export const hasPaletteBackup = (config: any): boolean => {
+  return !!(config?.general?.palette?.backups?.length > 0)
+}
+
+/**
+ * Gets the original palette name from backup data
+ * @param config - The visualization config object
+ * @returns The original palette name or null if no backup exists
+ */
+export const getOriginalPaletteName = (config: any): string | null => {
+  const backups = config?.general?.palette?.backups
+  if (!backups || backups.length === 0) return null
+
+  // Get the most recent backup (last in array)
+  const latestBackup = backups[backups.length - 1]
+  return latestBackup?.name || null
+}
+
+/**
+ * Gets the original two-color palette name from backup data
+ * @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 => {
+  const backups = config?.general?.palette?.backups
+  if (!backups || backups.length === 0) return null
+
+  // Find the two-color palette backup
+  const twoColorBackup = backups.find((backup: any) => backup.type === 'twoColor')
+  return twoColorBackup?.name || null
+}
+
+/**
+ * Checks if a config has two-color palette backup data available for rollback
+ * @param config - The visualization config object
+ * @returns True if two-color backup data exists
+ */
+export const hasTwoColorPaletteBackup = (config: any): boolean => {
+  const backups = config?.general?.palette?.backups
+  if (!backups || backups.length === 0) return false
+  return backups.some((backup: any) => backup.type === 'twoColor')
+}
+
+/**
+ * Rolls back palette configuration to original pre-migration state
+ * @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 => {
+  const backups = config?.general?.palette?.backups
+  if (!backups || backups.length === 0) {
+    return false
+  }
+
+  // Get the most recent backup
+  const latestBackup = backups[backups.length - 1]
+  if (!latestBackup?.name) {
+    return false
+  }
+
+  // Restore the original configuration
+  if (config.type === 'map') {
+    config.general.palette.name = newMapPaletteNames[latestBackup.name] || latestBackup.name
+    config.general.palette.version = '1.0' // Reset to v1
+  } else if (config.type === 'chart') {
+    config.general.palette.name = chartPaletteMigrationMap[latestBackup.name] || latestBackup.name
+    config.general.palette.version = '1.0' // Reset to v1
+  }
+
+  return config
+}
+
+/**
+ * Rolls back two-color palette configuration to original pre-migration state
+ * @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 => {
+  const backups = config?.general?.palette?.backups
+  if (!backups || backups.length === 0) {
+    return false
+  }
+
+  // Find the two-color palette backup
+  const twoColorBackup = backups.find((backup: any) => backup.type === 'twoColor')
+  if (!twoColorBackup?.name) {
+    return false
+  }
+
+  // Restore the original two-color palette configuration
+  if (config.twoColor) {
+    config.twoColor.palette = twoColorBackup.name
+    config.twoColor.isPaletteReversed = twoColorBackup.isReversed || false
+  }
+
+  // Reset to v1
+  if (config.general?.palette) {
+    config.general.palette.version = twoColorBackup.version || '1.0'
+    // Remove the two-color backup since we've rolled back
+    config.general.palette.backups = backups.filter((backup: any) => backup.type !== 'twoColor')
+  }
+
+  return true
+}

package/helpers/queryStringUtils.ts

@@ -49,3 +49,16 @@ export function removeQueryParam(key: string) {
   delete queryParams[key]
   updateQueryString(queryParams)
 }
+
+/**
+ * Checks if developer mode is enabled via URL parameter
+ * @returns true if isCoveDeveloper URL parameter is present and truthy
+ */
+export function isCoveDeveloperMode(): boolean {
+  const param = getQueryParam('isCoveDeveloper')
+  if (!param) return false
+
+  // Handle various truthy values
+  const lowerParam = param.toLowerCase()
+  return lowerParam === 'true' || lowerParam === '1' || lowerParam === 'yes'
+}

package/helpers/testing.ts

@@ -0,0 +1,345 @@
+import { expect, userEvent } from 'storybook/test'
+import { waitFor } from '@testing-library/react'
+
+/**
+ * Shared Testing Helpers for Editor Story Tests
+ *
+ * This file contains common testing utilities used across all visualization
+ * editor story tests (Chart, Map, Data Bite, Waffle Chart, etc.).
+ *
+ * Key Features:
+ * - Adaptive animation delays for test environments vs UI
+ * - Robust polling utilities for async state changes
+ * - Generic before/after assertion patterns
+ * - Element presence/absence waiting
+ * - Text content change detection
+ * - Editor loading and accordion interaction helpers
+ *
+ */
+
+// ============================================================================
+// ENVIRONMENT DETECTION & TIMING
+// ============================================================================
+
+/**
+ * Use 500ms delay for visual perception in Storybook UI, but skip in automated tests
+ * This ensures smooth visual feedback for manual testing while keeping automated tests fast
+ */
+export const MIN_ANIMATION_DELAY_MS = (() => {
+  // Check if we're in automated test environment (Vitest/Jest)
+  if (typeof process !== 'undefined' && process.env.NODE_ENV === 'test') {
+    return 0
+  }
+
+  // Check if we're running via test runner (Vitest has __vitest__ global)
+  if (typeof globalThis !== 'undefined' && '__vitest__' in globalThis) {
+    return 0
+  }
+
+  return 500
+})()
+
+const WAIT_FOR_TIMEOUT_MS = 5000
+
+// ============================================================================
+// CORE POLLING UTILITIES
+// ============================================================================
+
+// Wrapper for waitFor that includes explicit animation delay
+const waitForWithDelay = async (predicate: () => void, options?: { timeout?: number }) => {
+  if (MIN_ANIMATION_DELAY_MS > 0) {
+    await new Promise(resolve => setTimeout(resolve, MIN_ANIMATION_DELAY_MS))
+  }
+
+  await waitFor(predicate, {
+    timeout: options?.timeout || WAIT_FOR_TIMEOUT_MS
+  })
+}
+
+/**
+ * Perform an action and assert the result using polling
+ * This is the core pattern for testing state changes in editor components
+ *
+ * @param label Descriptive label for the test action
+ * @param read Function that reads the current state
+ * @param act Function that performs the action
+ * @param predicate Function that validates the state change
+ * @param extraAssert Optional additional assertion on the final value
+ */
+export const performAndAssert = async <T extends unknown>(
+  label: string,
+  read: () => T,
+  act: () => Promise<void> | void,
+  predicate: (before: T, after: T) => boolean,
+  extraAssert?: (after: T) => void
+): Promise<void> => {
+  // Capture the call site stack trace
+  const callSite = new Error().stack
+
+  const before = read()
+  await act()
+
+  await waitForWithDelay(() => {
+    const after = read()
+    const result = predicate(before, after)
+    if (!result) {
+      // Create a more informative error with the original call site
+      const error = new Error(
+        `${label} failed: Expected predicate to return true. Before: ${JSON.stringify(before)}, After: ${JSON.stringify(
+          after
+        )}`
+      )
+
+      // Try to preserve the original call site in the stack trace
+      if (callSite) {
+        const originalStack = callSite.split('\n')
+        // Replace the generic helper stack with the original call site
+        if (originalStack.length > 2) {
+          error.stack = [
+            error.message,
+            ...originalStack.slice(2) // Skip the first two lines (error creation in helper)
+          ].join('\n')
+        }
+      }
+
+      throw error
+    }
+    if (extraAssert) extraAssert(after)
+  })
+}
+
+// ============================================================================
+// ELEMENT WAITING UTILITIES
+// ============================================================================
+
+/**
+ * Wait for an element to appear in the DOM
+ *
+ * @param selector CSS selector for the element
+ * @param canvasElement Container element to search within
+ * @returns Promise that resolves to the found element
+ */
+export const waitForPresence = async (selector: string, canvasElement: HTMLElement) => {
+  await waitForWithDelay(() => {
+    const element = canvasElement.querySelector(selector)
+    expect(element).toBeTruthy()
+  })
+  return canvasElement.querySelector(selector)
+}
+
+/**
+ * Wait for an element to disappear from the DOM
+ *
+ * @param selector CSS selector for the element
+ * @param canvasElement Container element to search within
+ */
+export const waitForAbsence = async (selector: string, canvasElement: HTMLElement) => {
+  await waitForWithDelay(() => {
+    const element = canvasElement.querySelector(selector)
+    expect(element).toBeFalsy()
+  })
+}
+
+/**
+ * Wait for a select element's options to populate
+ *
+ * @param selectElement The select element to monitor
+ * @param minCount The minimum number of expected elements
+ */
+export const waitForOptionsToPopulate = async (selectElement: HTMLSelectElement, minCount: number = 2) => {
+  await waitForWithDelay(() => {
+    expect(selectElement.options.length).toBeGreaterThanOrEqual(minCount)
+  })
+}
+
+/**
+ * Wait for an element's text content to change to a specific value
+ *
+ * @param el The element to monitor
+ * @param expected The expected text content
+ */
+export const waitForTextContent = async (el: HTMLElement | null, expected: string) => {
+  expect(el).toBeTruthy()
+  await waitForWithDelay(() => {
+    expect(el!.textContent?.trim()).toBe(expected.trim())
+  })
+}
+
+// ============================================================================
+// EDITOR-SPECIFIC UTILITIES
+// ============================================================================
+
+/**
+ * Wait for the editor to load and become interactive
+ * This ensures all accordion sections are present and the component is ready for testing
+ *
+ * @param canvas Storybook canvas object from within(canvasElement)
+ */
+export const waitForEditor = async (canvas: any) => {
+  await waitForWithDelay(() => {
+    const editorElement = canvas.queryAllByText(/general|data|visual/i)
+    expect(editorElement[0]).toBeVisible()
+  })
+}
+
+/**
+ * Open an accordion section in the editor
+ *
+ * @param canvas Storybook canvas object from within(canvasElement)
+ * @param sectionName Name of the accordion section (case-insensitive)
+ */
+export const openAccordion = async (canvas: any, sectionName: string) => {
+  const accordion = canvas.getByRole('button', { name: new RegExp(sectionName, 'i') })
+  await userEvent.click(accordion)
+  await waitForWithDelay(() => {
+    const accordionContent = accordion.closest('.accordion-item, .accordion-section, [class*="accordion"]')
+    expect(accordionContent).toBeTruthy()
+  })
+}
+
+// ============================================================================
+// VISUAL STATE HELPERS
+// ============================================================================
+
+/**
+ * Get visual state for boolean/checkbox testing
+ * This is a flexible helper that can be customized for different visual properties
+ *
+ * @param element The element to analyze
+ * @param options Configuration for what visual properties to check
+ * @returns Object containing the visual state
+ */
+export const getVisualState = (
+  element: HTMLElement | null,
+  options: {
+    checkClasses?: string[] // CSS classes to check for presence
+    checkStyles?: string[] // CSS properties to read from computed styles
+    checkAttributes?: string[] // HTML attributes to read
+    customChecks?: ((el: HTMLElement) => Record<string, any>)[] // Custom visual checks
+  } = {}
+) => {
+  if (!element) return null
+
+  const state: Record<string, any> = {}
+
+  // Check for specific CSS classes
+  if (options.checkClasses) {
+    for (const className of options.checkClasses) {
+      state[`has_${className.replace(/[^a-zA-Z0-9]/g, '_')}`] = element.classList.contains(className)
+    }
+  }
+
+  // Check computed styles
+  if (options.checkStyles) {
+    const computedStyle = getComputedStyle(element)
+    for (const property of options.checkStyles) {
+      state[`style_${property.replace(/[^a-zA-Z0-9]/g, '_')}`] = computedStyle.getPropertyValue(property)
+    }
+  }
+
+  // Check attributes
+  if (options.checkAttributes) {
+    for (const attr of options.checkAttributes) {
+      state[`attr_${attr.replace(/[^a-zA-Z0-9]/g, '_')}`] = element.getAttribute(attr)
+    }
+  }
+
+  // Run custom checks
+  if (options.customChecks) {
+    for (const customCheck of options.customChecks) {
+      Object.assign(state, customCheck(element))
+    }
+  }
+
+  // Always include basic visibility state
+  state.isVisible = element.offsetParent !== null
+  state.classList = Array.from(element.classList).sort().join(' ')
+
+  return state
+}
+
+/**
+ * Create a comprehensive boolean testing function for checkbox controls
+ * Tests both enable/disable directions and verifies visual changes
+ *
+ * @param checkbox The checkbox element to test
+ * @param getVisualState Function that returns the current visual state
+ * @param testName Descriptive name for the test
+ */
+export const testBooleanControl = async (checkbox: HTMLInputElement, getVisualState: () => any, testName: string) => {
+  // Get initial state
+  const initialCheckboxState = checkbox.checked
+  const initialVisualState = getVisualState()
+
+  // First toggle: change to opposite state
+  await userEvent.click(checkbox)
+  await new Promise(resolve => setTimeout(resolve, 100))
+  const firstToggleCheckboxState = checkbox.checked
+  const firstToggleVisualState = getVisualState()
+
+  // Verify checkbox changed
+  expect(firstToggleCheckboxState).not.toBe(initialCheckboxState)
+
+  // Verify visualization changed (with flexible handling)
+  if (JSON.stringify(firstToggleVisualState) === JSON.stringify(initialVisualState)) {
+    // Note: This warns but doesn't fail, allowing for controls that may not have
+    // visible effects under current data/settings
+    console.warn(`⚠️ ${testName}: Checkbox toggled but no visual change detected`)
+  } else {
+    expect(firstToggleVisualState).not.toEqual(initialVisualState)
+  }
+
+  // Second toggle: return to original state
+  await userEvent.click(checkbox)
+  await new Promise(resolve => setTimeout(resolve, 100))
+  const secondToggleCheckboxState = checkbox.checked
+  const secondToggleVisualState = getVisualState()
+
+  // Verify both checkbox AND visualization returned to original
+  expect(secondToggleCheckboxState).toBe(initialCheckboxState)
+  expect(secondToggleVisualState).toEqual(initialVisualState)
+}
+
+// ============================================================================
+// DATA EXTRACTION HELPERS
+// ============================================================================
+
+/**
+ * Get the primary data value displayed in a visualization
+ * Tries multiple common selectors for data values
+ *
+ * @param canvasElement The container element to search within
+ * @returns The data value as a string, or empty string if not found
+ */
+export const getDisplayValue = (canvasElement: HTMLElement): string => {
+  const selectors = ['svg text', '.bite-text', '.data-value', '[data-testid="data-value"]']
+
+  for (const selector of selectors) {
+    const elements = canvasElement.querySelectorAll(selector)
+    for (let i = 0; i < elements.length; i++) {
+      const element = elements[i]
+      const text = element.textContent?.trim()
+      if (text && /[\d,]+/.test(text)) {
+        return text
+      }
+    }
+  }
+
+  return ''
+}
+
+/**
+ * Get the title text from a visualization
+ * Tries multiple common selectors for titles
+ *
+ * @param canvas Storybook canvas object from within(canvasElement)
+ * @returns The title text as a string, or empty string if not found
+ */
+export const getTitleText = (canvas: any): string => {
+  try {
+    const titleElement = canvas.getByRole('heading') || canvas.querySelector('h1, h2, h3, .title')
+    return titleElement?.textContent?.trim() || ''
+  } catch {
+    return ''
+  }
+}

package/helpers/tests/addValuesToFilters.test.ts

@@ -2,7 +2,6 @@ import _ from 'lodash'
 import { VizFilter } from '../../types/VizFilter'
 import { addValuesToFilters } from '../addValuesToFilters'
 import { describe, it, expect, vi } from 'vitest'
-import { FILTER_STYLE } from '@cdc/dashboard/src/types/FilterStyles'
 
 describe('addValuesToFilters', () => {
   const parentFilter = { columnName: 'parentColumn', id: 11, active: 'apple', values: [] } as VizFilter
@@ -52,7 +51,7 @@ describe('addValuesToFilters', () => {
   it('works for nested dropdowns', () => {
     const nestedParentFilter = {
       ...parentFilter,
-      filterStyle: FILTER_STYLE.nestedDropdown,
+      filterStyle: 'nested-dropdown',
       subGrouping: { columnName: 'childColumn' }
     }
     const newFilters = addValuesToFilters([nestedParentFilter], data)

package/helpers/tests/generateColorsArray.test.ts

@@ -0,0 +1,24 @@
+import { generateColorsArray } from '../generateColorsArray'
+import { describe, it, expect } from 'vitest'
+
+describe('generateColorsArray', () => {
+  it('should return an array of colors', () => {
+    const colors = generateColorsArray('#fde0dd', false)
+    expect(colors).toEqual(expect.arrayContaining(['#fde0dd', '#ffd0c9', '#edd1ce']))
+  })
+
+  it('should return a brighter hover color when special flag is true', () => {
+    const colors = generateColorsArray('#fde0dd', true)
+    expect(colors[1]).toEqual('#fffaf7')
+  })
+
+  it('should return a darker color for the third element in the array', () => {
+    const colors = generateColorsArray('#fde0dd', false)
+    expect(colors[2]).toBe('#edd1ce')
+  })
+
+  it('should use black as default color', () => {
+    const colors = generateColorsArray()
+    expect(colors[0]).toBe('#000000')
+  })
+})