@cdc/core 4.25.11 → 4.26.2

package/helpers/ver/4.26.2.ts

@@ -0,0 +1,84 @@
+import cloneConfig from '../cloneConfig'
+import { DashboardConfig } from '@cdc/dashboard/src/types/DashboardConfig'
+
+const migrateAnnotationDimensions = config => {
+  if (config.annotations && Array.isArray(config.annotations)) {
+    // Calculate chart area height for Y conversion (matches calcInitialHeight)
+    const isHorizontal = config.orientation === 'horizontal'
+    const chartAreaHeight = isHorizontal
+      ? Number(config.heights?.horizontal) || 750 // default horizontal height
+      : Number(config.heights?.vertical) || 300 // default vertical height
+
+    config.annotations = config.annotations.map(annotation => {
+      if (!annotation) return annotation
+      if (annotation.y !== undefined && chartAreaHeight > 0) {
+        // Convert Y from pixels to percentage using the chart area height
+        annotation.y = (annotation.y / chartAreaHeight) * 100
+      } else {
+        annotation.y = 50
+      }
+
+      // Delete savedDimensions to preserve old dx/dy behavior (fixed pixel offsets).
+      // The scaling function falls back to raw dx/dy when savedDimensions is missing.
+      // Once user drags the annotation, savedDimensions will be set with current chart
+      // dimensions, enabling responsive scaling from that point forward.
+      delete annotation.savedDimensions
+
+      return annotation
+    })
+  }
+
+  if (config.type === 'dashboard' && config.visualizations) {
+    Object.values((config as DashboardConfig).visualizations).forEach(visualization => {
+      migrateAnnotationDimensions(visualization)
+    })
+  }
+}
+
+const migrateAnnotationDataModel = config => {
+  if (config.annotations && Array.isArray(config.annotations)) {
+    config.annotations = config.annotations.map(annotation => {
+      if (!annotation) return annotation
+      // Set all existing annotations to fixed mode
+      annotation.anchorMode = 'fixed'
+
+      // Delete xKey entirely - old format stored timestamps for dates,
+      // but new dataX expects raw data values. Format is incompatible.
+      // User can re-enable data mode which will set fresh dataX value.
+      delete annotation.xKey
+
+      // Delete yKey entirely (Y will be calculated dynamically in data mode)
+      delete annotation.yKey
+
+      // Delete empty seriesKey - it would cause yScale(undefined) errors in data mode
+      if (!annotation.seriesKey) {
+        delete annotation.seriesKey
+      }
+
+      // Delete deprecated properties
+      delete annotation.snapToNearestPoint
+      delete annotation.originalX
+      delete annotation.originalDX
+      delete annotation.originalY
+
+      return annotation
+    })
+  }
+
+  if (config.type === 'dashboard' && config.visualizations) {
+    Object.values((config as DashboardConfig).visualizations).forEach(visualization => {
+      migrateAnnotationDataModel(visualization)
+    })
+  }
+}
+
+const update_4_26_2 = config => {
+  const ver = '4.26.2'
+  const newConfig = cloneConfig(config)
+  migrateAnnotationDimensions(newConfig)
+  migrateAnnotationDataModel(newConfig)
+  newConfig.version = ver
+  return newConfig
+}
+
+export default update_4_26_2

package/helpers/ver/tests/4.26.1.test.ts

@@ -0,0 +1,105 @@
+import update_4_26_1 from '../4.26.1'
+import { expect, describe, it } from 'vitest'
+
+describe('update_4_26_1', () => {
+  describe('normalizeFilterParents', () => {
+    it('should convert string parents to array in shared filters', () => {
+      const config: any = {
+        type: 'dashboard',
+        version: '4.26.0',
+        dashboard: {
+          sharedFilters: [
+            {
+              type: 'datafilter',
+              parents: 'parent-filter-id'
+            }
+          ]
+        }
+      }
+
+      const result = update_4_26_1(config)
+
+      expect(result.dashboard.sharedFilters[0].parents).toEqual(['parent-filter-id'])
+      expect(result.version).toBe('4.26.1')
+    })
+
+    it('should leave array parents unchanged', () => {
+      const config: any = {
+        type: 'dashboard',
+        version: '4.26.0',
+        dashboard: {
+          sharedFilters: [
+            {
+              type: 'datafilter',
+              parents: ['parent1', 'parent2']
+            }
+          ]
+        }
+      }
+
+      const result = update_4_26_1(config)
+
+      expect(result.dashboard.sharedFilters[0].parents).toEqual(['parent1', 'parent2'])
+    })
+  })
+
+  describe('removeOldBrushKeys', () => {
+    it('should remove brush config from chart', () => {
+      const config: any = {
+        type: 'chart',
+        version: '4.26.0',
+        brush: { enabled: true }
+      }
+
+      const result = update_4_26_1(config)
+
+      expect(result.brush).toBeUndefined()
+    })
+
+    it('should remove brush config from dashboard visualizations', () => {
+      const config: any = {
+        type: 'dashboard',
+        version: '4.26.0',
+        visualizations: {
+          chart1: {
+            type: 'chart',
+            brush: { enabled: true }
+          }
+        }
+      }
+
+      const result = update_4_26_1(config)
+
+      expect(result.visualizations.chart1.brush).toBeUndefined()
+    })
+  })
+
+  describe('combined migrations', () => {
+    it('should run all migrations together', () => {
+      const config: any = {
+        type: 'dashboard',
+        version: '4.26.0',
+        dashboard: {
+          sharedFilters: [
+            {
+              type: 'datafilter',
+              parents: 'parent-id'
+            }
+          ]
+        },
+        visualizations: {
+          chart1: {
+            type: 'chart',
+            brush: { enabled: true }
+          }
+        }
+      }
+
+      const result = update_4_26_1(config)
+
+      expect(result.dashboard.sharedFilters[0].parents).toEqual(['parent-id'])
+      expect(result.visualizations.chart1.brush).toBeUndefined()
+      expect(result.version).toBe('4.26.1')
+    })
+  })
+})

package/helpers/ver/tests/4.26.2.test.ts

@@ -0,0 +1,298 @@
+import update_4_26_2 from '../4.26.2'
+import { expect, describe, it } from 'vitest'
+
+describe('update_4_26_2', () => {
+  describe('migrateAnnotationDimensions', () => {
+    it('should convert Y position from absolute pixels to percentage and delete savedDimensions', () => {
+      const config: any = {
+        type: 'chart',
+        version: '4.26.1',
+        heights: { vertical: 400 },
+        annotations: [
+          {
+            text: 'Test Annotation',
+            x: 50,
+            y: 200,
+            savedDimensions: [800, 560], // old format: will be deleted
+            dx: 10,
+            dy: -10
+          }
+        ]
+      }
+
+      const result = update_4_26_2(config)
+
+      // Y is now calculated as percentage of heights.vertical (400)
+      expect(result.annotations[0].y).toBe(50) // 200 / 400 * 100 = 50
+      expect(result.annotations[0].x).toBe(50)
+      // savedDimensions should be deleted to preserve old dx/dy behavior
+      expect(result.annotations[0].savedDimensions).toBeUndefined()
+      // dx/dy should be preserved unchanged
+      expect(result.annotations[0].dx).toBe(10)
+      expect(result.annotations[0].dy).toBe(-10)
+      expect(result.version).toBe('4.26.2')
+    })
+
+    it('should handle multiple annotations with different Y positions', () => {
+      const config: any = {
+        type: 'chart',
+        version: '4.26.1',
+        heights: { vertical: 500 },
+        annotations: [
+          {
+            text: 'Top',
+            x: 25,
+            y: 100,
+            savedDimensions: [1000, 700]
+          },
+          {
+            text: 'Middle',
+            x: 75,
+            y: 250,
+            savedDimensions: [1000, 700]
+          }
+        ]
+      }
+
+      const result = update_4_26_2(config)
+
+      // Y calculated as percentage of heights.vertical (500)
+      expect(result.annotations[0].y).toBe(20) // 100 / 500 * 100 = 20
+      expect(result.annotations[1].y).toBe(50) // 250 / 500 * 100 = 50
+      // savedDimensions should be deleted
+      expect(result.annotations[0].savedDimensions).toBeUndefined()
+      expect(result.annotations[1].savedDimensions).toBeUndefined()
+    })
+
+    it('should use default vertical height (300) when heights not specified', () => {
+      const config: any = {
+        type: 'chart',
+        version: '4.26.1',
+        annotations: [
+          {
+            text: 'No heights config',
+            x: 50,
+            y: 150,
+            savedDimensions: [800, 560]
+          }
+        ]
+      }
+
+      const result = update_4_26_2(config)
+
+      // Uses default vertical height of 300
+      expect(result.annotations[0].y).toBe(50) // 150 / 300 * 100 = 50
+      expect(result.annotations[0].savedDimensions).toBeUndefined()
+    })
+
+    it('should use horizontal height for horizontal orientation', () => {
+      const config: any = {
+        type: 'chart',
+        version: '4.26.1',
+        orientation: 'horizontal',
+        heights: { horizontal: 750 },
+        annotations: [
+          {
+            text: 'Horizontal chart annotation',
+            x: 50,
+            y: 375,
+            savedDimensions: [800, 900]
+          }
+        ]
+      }
+
+      const result = update_4_26_2(config)
+
+      // Uses heights.horizontal for horizontal charts
+      expect(result.annotations[0].y).toBe(50) // 375 / 750 * 100 = 50
+      expect(result.annotations[0].savedDimensions).toBeUndefined()
+    })
+
+    it('should handle dashboard configs with nested visualizations', () => {
+      const config: any = {
+        type: 'dashboard',
+        version: '4.26.1',
+        visualizations: {
+          chart1: {
+            type: 'chart',
+            heights: { vertical: 300 },
+            annotations: [
+              {
+                text: 'Chart 1 Annotation',
+                x: 30,
+                y: 150,
+                savedDimensions: [600, 450]
+              }
+            ]
+          }
+        }
+      }
+
+      const result = update_4_26_2(config)
+
+      expect(result.visualizations.chart1.annotations[0].y).toBe(50) // 150 / 300 * 100 = 50
+      expect(result.visualizations.chart1.annotations[0].savedDimensions).toBeUndefined()
+    })
+
+    it('should preserve all other annotation properties and delete xKey entirely', () => {
+      const config: any = {
+        type: 'chart',
+        version: '4.26.1',
+        heights: { vertical: 500 },
+        annotations: [
+          {
+            text: 'Complex Annotation',
+            x: 50,
+            y: 250,
+            savedDimensions: [1000, 700],
+            dx: 20,
+            dy: -30,
+            xKey: 1577836800000,
+            yKey: '42',
+            seriesKey: 'series1',
+            marker: 'arrow'
+          }
+        ]
+      }
+
+      const result = update_4_26_2(config)
+
+      const annotation = result.annotations[0]
+      expect(annotation.y).toBe(50) // 250 / 500 * 100 = 50
+      expect(annotation.text).toBe('Complex Annotation')
+      expect(annotation.dx).toBe(20)
+      expect(annotation.dy).toBe(-30)
+      // xKey is deleted entirely (not renamed to dataX) because old format
+      // stored timestamps but new dataX expects raw data values
+      expect(annotation.xKey).toBeUndefined()
+      expect(annotation.dataX).toBeUndefined()
+      expect(annotation.yKey).toBeUndefined()
+      // Non-empty seriesKey is preserved
+      expect(annotation.seriesKey).toBe('series1')
+      expect(annotation.savedDimensions).toBeUndefined()
+    })
+
+    it('should delete empty seriesKey', () => {
+      const config: any = {
+        type: 'chart',
+        version: '4.26.1',
+        heights: { vertical: 300 },
+        annotations: [
+          {
+            text: 'Annotation with empty seriesKey',
+            x: 50,
+            y: 150,
+            seriesKey: ''
+          }
+        ]
+      }
+
+      const result = update_4_26_2(config)
+
+      // Empty seriesKey should be deleted to prevent yScale(undefined) errors
+      expect(result.annotations[0].seriesKey).toBeUndefined()
+    })
+
+    it('should handle config with no annotations', () => {
+      const config: any = {
+        type: 'chart',
+        version: '4.26.1',
+        title: 'Chart without annotations'
+      }
+
+      const result = update_4_26_2(config)
+
+      expect(result.annotations).toBeUndefined()
+      expect(result.title).toBe('Chart without annotations')
+    })
+
+    it('should handle annotation without savedDimensions', () => {
+      const config: any = {
+        type: 'chart',
+        version: '4.26.1',
+        heights: { vertical: 300 },
+        annotations: [
+          {
+            text: 'No savedDimensions',
+            x: 50,
+            y: 150
+          }
+        ]
+      }
+
+      const result = update_4_26_2(config)
+
+      expect(result.annotations[0].y).toBe(50) // 150 / 300 * 100 = 50
+      expect(result.annotations[0].savedDimensions).toBeUndefined()
+    })
+  })
+
+  describe('combined migrations', () => {
+    it('should run all migrations together', () => {
+      const config: any = {
+        type: 'dashboard',
+        version: '4.26.1',
+        dashboard: {
+          sharedFilters: [
+            {
+              type: 'datafilter',
+              parents: 'parent-id'
+            }
+          ]
+        },
+        visualizations: {
+          chart1: {
+            type: 'chart',
+            heights: { vertical: 400 },
+            brush: { enabled: true },
+            annotations: [
+              {
+                x: 50,
+                y: 200,
+                savedDimensions: [800, 560]
+              }
+            ]
+          }
+        }
+      }
+
+      const result = update_4_26_2(config)
+
+      expect(result.visualizations.chart1.annotations[0].y).toBe(50) // 200 / 400 * 100 = 50
+      expect(result.visualizations.chart1.annotations[0].anchorMode).toBe('fixed')
+      expect(result.visualizations.chart1.annotations[0].savedDimensions).toBeUndefined()
+      expect(result.visualizations.chart1.annotations[0].dataX).toBeUndefined()
+      expect(result.version).toBe('4.26.2')
+    })
+
+    it('should migrate data model along with Y position', () => {
+      const config: any = {
+        type: 'chart',
+        version: '4.26.1',
+        heights: { vertical: 400 },
+        annotations: [
+          {
+            x: 50,
+            y: 200,
+            savedDimensions: [800, 560],
+            xKey: 1577836800000,
+            yKey: '42',
+            snapToNearestPoint: true
+          }
+        ]
+      }
+
+      const result = update_4_26_2(config)
+
+      const annotation = result.annotations[0]
+      expect(annotation.y).toBe(50) // 200 / 400 * 100 = 50
+      expect(annotation.anchorMode).toBe('fixed')
+      // xKey is deleted entirely (not renamed to dataX) - format incompatible
+      expect(annotation.dataX).toBeUndefined()
+      expect(annotation.xKey).toBeUndefined()
+      expect(annotation.yKey).toBeUndefined()
+      expect(annotation.snapToNearestPoint).toBeUndefined()
+      expect(annotation.savedDimensions).toBeUndefined()
+    })
+  })
+})

package/helpers/viewports.ts

@@ -15,4 +15,6 @@ export const isMobileTerritoryViewport = currentViewport => isBelowBreakpoint('s
 
 export const isMobileFontViewport = currentViewport => isBelowBreakpoint('sm', currentViewport)
 
+export const isMobileAnnotationViewport = currentViewport => isBelowBreakpoint('sm', currentViewport)
+
 export const isMobileSmallMultiplesViewport = currentViewport => isBelowBreakpoint('md', currentViewport)

package/hooks/useDataColumns.ts

@@ -0,0 +1,63 @@
+import { useMemo } from 'react'
+
+export interface UseDataColumnsOptions {
+  /** Columns to exclude from the result */
+  excludeColumns?: string[]
+  /** Include only columns with specific data types */
+  dataTypes?: ('string' | 'number' | 'boolean' | 'date')[]
+}
+
+/**
+ * Extracts unique column names from data with memoization
+ *
+ * Performance optimization: Replaces the common getColumns() pattern
+ * that was duplicated across multiple packages and called multiple times per render.
+ *
+ * @param data - Array of data objects
+ * @param options - Optional configuration for filtering columns
+ * @returns Sorted array of unique column names
+ *
+ * @example
+ * // Basic usage
+ * const columns = useDataColumns(data)
+ *
+ * @example
+ * // With exclusions
+ * const columns = useDataColumns(data, { excludeColumns: [config.groupBy] })
+ *
+ * @example
+ * // Filter by data type
+ * const numericColumns = useDataColumns(data, { dataTypes: ['number'] })
+ */
+export const useDataColumns = (data: any[], options?: UseDataColumnsOptions): string[] => {
+  const { excludeColumns = [], dataTypes } = options || {}
+
+  return useMemo(() => {
+    if (!data?.length) return []
+
+    const columnsSet = new Set<string>()
+
+    // Single iteration through all rows (optimized from previous pattern)
+    data.forEach(row => {
+      Object.keys(row).forEach(columnName => {
+        if (excludeColumns.includes(columnName)) return
+
+        // Optional: filter by data type
+        if (dataTypes && dataTypes.length > 0) {
+          const value = row[columnName]
+          const valueType = typeof value
+          if (!dataTypes.includes(valueType as any)) return
+        }
+
+        columnsSet.add(columnName)
+      })
+    })
+
+    return Array.from(columnsSet).sort()
+  }, [
+    data,
+    // Stringify arrays for stable dependency tracking
+    excludeColumns.join(','),
+    dataTypes?.join(',')
+  ])
+}

package/hooks/useFilterManagement.ts

@@ -0,0 +1,94 @@
+/**
+ * Custom hook for managing filter operations in visualizations
+ *
+ * Provides common filter management functionality including:
+ * - Adding new filters
+ * - Removing filters
+ * - Updating filter properties
+ * - Getting unique column values for filter options
+ *
+ * @example
+ * ```tsx
+ * const { addNewFilter, removeFilter, updateFilterProp, getFilterColumnValues } =
+ *   useFilterManagement(config, updateConfig, data)
+ *
+ * // Add a new filter
+ * <Button onClick={addNewFilter}>Add Filter</Button>
+ *
+ * // Remove a filter
+ * <button onClick={() => removeFilter(index)}>Remove</button>
+ *
+ * // Update filter property
+ * <Select onChange={e => updateFilterProp('columnName', index, e.target.value)} />
+ *
+ * // Get column values for filter dropdown
+ * <Select options={getFilterColumnValues(index)} />
+ * ```
+ */
+export const useFilterManagement = <TConfig extends { filters?: any[] }>(
+  config: TConfig,
+  updateConfig: (config: TConfig) => void,
+  data: any[]
+) => {
+  /**
+   * Adds a new empty filter to the config
+   */
+  const addNewFilter = () => {
+    const filters = config.filters ? [...config.filters] : []
+    filters.push({ values: [] })
+    updateConfig({ ...config, filters })
+  }
+
+  /**
+   * Removes a filter at the specified index
+   * @param index - The index of the filter to remove
+   */
+  const removeFilter = (index: number) => {
+    const filters = [...(config.filters || [])]
+    filters.splice(index, 1)
+    updateConfig({ ...config, filters })
+  }
+
+  /**
+   * Updates a specific property of a filter
+   * @param name - The property name to update
+   * @param index - The index of the filter
+   * @param value - The new value for the property
+   */
+  const updateFilterProp = (name: string, index: number, value: any) => {
+    const filters = [...(config.filters || [])]
+    filters[index][name] = value
+    updateConfig({ ...config, filters })
+  }
+
+  /**
+   * Gets unique values from a data column for filter options
+   * @param index - The index of the filter (to get its columnName)
+   * @returns Array of unique, sorted values from the specified column
+   */
+  const getFilterColumnValues = (index: number): any[] => {
+    const filterDataOptions: any[] = []
+    const filterColumnName = config.filters?.[index]?.columnName
+
+    // Return empty array if no column name or no data
+    if (!filterColumnName || !data || !Array.isArray(data) || data.length === 0) {
+      return filterDataOptions
+    }
+
+    data.forEach(function (row: any) {
+      if (undefined !== row[filterColumnName] && -1 === filterDataOptions.indexOf(row[filterColumnName])) {
+        filterDataOptions.push(row[filterColumnName])
+      }
+    })
+    filterDataOptions.sort()
+
+    return filterDataOptions
+  }
+
+  return {
+    addNewFilter,
+    removeFilter,
+    updateFilterProp,
+    getFilterColumnValues
+  }
+}

package/hooks/useLegendSeparators.ts

@@ -0,0 +1,26 @@
+import { clamp } from 'lodash'
+
+// TODO: generalize this to be used in legends other than linear block gradient
+
+const LEGEND_SEPARATOR_SIZE = 0.02
+const LEGEND_SEPARATOR_SIZE_MAX = 20
+const LEGEND_SEPARATOR_SIZE_MIN = 8
+
+const useLegendSeparators = (separators, legendWidth, allowsLegendSeparators) => {
+  const legendSeparators = allowsLegendSeparators
+    ? separators?.replace(' ', '').split(',').map(Number).filter(Boolean) || []
+    : []
+  const separatorSize = clamp(legendWidth * LEGEND_SEPARATOR_SIZE, LEGEND_SEPARATOR_SIZE_MIN, LEGEND_SEPARATOR_SIZE_MAX)
+  const legendSeparatorsToSubtract = legendSeparators.length * separatorSize
+  const getTickSeparatorsAdjustment = (index: number) =>
+    legendSeparators.reduce((acc, separators) => (index >= separators ? acc + separatorSize : acc), 0)
+
+  return {
+    legendSeparators,
+    separatorSize,
+    legendSeparatorsToSubtract,
+    getTickSeparatorsAdjustment
+  }
+}
+
+export default useLegendSeparators