@cdc/chart 4.26.1 → 4.26.3

package/src/components/Legend/Legend.Component.tsx

@@ -1,5 +1,5 @@
 import parse from 'html-react-parser'
-import React from 'react'
+import React, { useMemo } from 'react'
 import { LegendOrdinal, LegendItem, LegendLabel } from '@visx/legend'
 import { PatternLines, PatternCircles, PatternWaves } from '@visx/pattern'
 import LegendShape from '@cdc/core/components/LegendShape'
@@ -17,6 +17,8 @@ import { DimensionsType } from '@cdc/core/types/Dimensions'
 import { isLegendWrapViewport } from '@cdc/core/helpers/viewports'
 import LegendLineShape from './LegendLine.Shape'
 import LegendGroup from './LegendGroup'
+import LegendValueRange from './LegendValueRange'
+import { getHorizonLayerColors, getHorizonMaxValue } from '../../components/HorizonChart/helpers/getHorizonLayerColors'
 import { getSeriesWithData } from '../../helpers/dataHelpers'
 import { publishAnalyticsEvent } from '@cdc/core/helpers/metrics/helpers'
 import { getVizTitle, getVizSubType } from '@cdc/core/helpers/metrics/utils'
@@ -28,6 +30,7 @@ interface LegendProps {
   config: ChartConfig
   currentViewport: ViewportSize
   formatLabels: (labels: Label[]) => Label[]
+  formatNumber?: (value: number, axis?: string) => string
   highlight: Function
   handleShowAll: Function
   ref: React.Ref<() => void>
@@ -48,6 +51,7 @@ const Legend: React.FC<LegendProps> = forwardRef(
       handleShowAll,
       currentViewport,
       formatLabels,
+      formatNumber,
       skipId = 'legend',
       dimensions,
       transformedData: data,
@@ -60,7 +64,10 @@ const Legend: React.FC<LegendProps> = forwardRef(
     const { series } = runtime
 
     const seriesWithData = getSeriesWithData(config)
-    const dontFilterLegendItems = !series.length || legend.unified || !seriesWithData.length
+    // For Radar charts, seriesWithData contains dimension keys but legend shows entity names
+    // so we skip the series filter for radar charts
+    const isRadarChart = config.visualizationType === 'Radar'
+    const dontFilterLegendItems = !series.length || legend.unified || !seriesWithData.length || isRadarChart
 
     const isLegendBottom =
       legend?.position === 'bottom' ||
@@ -74,6 +81,29 @@ const Legend: React.FC<LegendProps> = forwardRef(
     const { HighLightedBarUtils } = useHighlightedBars(config)
     let highLightedLegendItems = HighLightedBarUtils.findDuplicates(config.highlightedBarValues)
 
+    const horizonLegendData = useMemo(() => {
+      if (config.visualizationType !== 'Horizon Chart') {
+        return null
+      }
+      const numLayers = config.horizon?.numLayers || 4
+      const runtimeSeriesKeys = config.runtime?.seriesKeys
+      const seriesKeys =
+        (Array.isArray(runtimeSeriesKeys) && runtimeSeriesKeys.length > 0
+          ? runtimeSeriesKeys
+          : config.series?.map(s => s.dataKey)) || []
+      const maxValue = getHorizonMaxValue(data, seriesKeys)
+      const layerColors = getHorizonLayerColors(config, numLayers)
+
+      return { numLayers, maxValue, layerColors }
+    }, [
+      config.visualizationType,
+      config.horizon?.numLayers,
+      config.runtime?.seriesKeys,
+      config.series,
+      config.general?.palette?.name,
+      data
+    ])
+
     if (!legend) return null
     return (
       <aside
@@ -99,6 +129,20 @@ const Legend: React.FC<LegendProps> = forwardRef(
         />
         <LegendGroup formatLabels={formatLabels} />
 
+        {/* Value Range Legend for Horizon Chart (and future chart types) */}
+        {horizonLegendData && (
+          <LegendValueRange
+            maxValue={horizonLegendData.maxValue}
+            numRanges={horizonLegendData.numLayers}
+            colors={horizonLegendData.layerColors}
+            formatNumber={formatNumber}
+            innerClasses={innerClasses}
+            shape={config.legend.style === 'boxes' ? 'square' : 'circle'}
+            onClick={undefined}
+            reverseLabelOrder={config.legend.reverseLabelOrder}
+          />
+        )}
+
         <LegendOrdinal scale={colorScale} itemDirection='row' labelMargin='0 20px 0 0' shapeMargin='0 10px 0'>
           {labels => {
             return (
@@ -130,8 +174,12 @@ const Legend: React.FC<LegendProps> = forwardRef(
                         } else className.push('highlighted')
                       }
 
-                      if (config.legend.style === 'gradient' || config.legend.groupBy) {
-                        return <></>
+                      if (
+                        config.legend.style === 'gradient' ||
+                        config.legend.groupBy ||
+                        config.visualizationType === 'Horizon Chart'
+                      ) {
+                        return null
                       }
 
                       return (

package/src/components/Legend/Legend.tsx

@@ -3,7 +3,6 @@ import ConfigContext from '../../ConfigContext'
 import LegendComponent from './Legend.Component'
 import { createFormatLabels } from './helpers/createFormatLabels'
 
-/* eslint-disable jsx-a11y/no-noninteractive-tabindex, jsx-a11y/no-static-element-interactions */
 const Legend = forwardRef((props, ref) => {
   // prettier-ignore
   const {
@@ -42,6 +41,7 @@ const Legend = forwardRef((props, ref) => {
         handleShowAll={handleShowAll}
         currentViewport={currentViewport}
         formatLabels={createLegendLabels}
+        formatNumber={formatNumber}
         interactionLabel={interactionLabel}
       />
     </Fragment>

package/src/components/Legend/LegendGroup/LegendGroup.styles.css

@@ -6,14 +6,14 @@
     margin-bottom: 0.5rem;
 
     .group-item .visx-legend-label {
-      font-weight: 400;
       font-size: 0.889rem;
+      font-weight: 400;
       margin-bottom: 0.5rem;
     }
     .group-label {
-      font-weight: 500;
       font-family: Nunito, sans-serif;
       font-size: 1rem;
+      font-weight: 500;
     }
   }
 
@@ -22,9 +22,9 @@
     grid-gap: 10px;
 
     &.group-item {
+      align-items: flex-start;
       display: flex;
       flex-direction: column;
-      align-items: flex-start;
     }
 
     & .inactive {
@@ -32,9 +32,9 @@
       transition: 0.2s all;
     }
     & .highlighted {
+      border-radius: 1px;
       outline: 1px solid #005ea2;
       outline-offset: 5px;
-      border-radius: 1px;
     }
   }
 }

package/src/components/Legend/LegendValueRange.tsx

@@ -0,0 +1,77 @@
+import React from 'react'
+import { LegendItem, LegendLabel } from '@visx/legend'
+import LegendShape from '@cdc/core/components/LegendShape'
+import { generateValueRanges, GenerateValueRangesOptions, ValueRange } from './helpers/generateValueRanges'
+
+export type LegendValueRangeProps = GenerateValueRangesOptions & {
+  colors: string[]
+  shape?: 'circle' | 'square'
+  onClick?: (index: number, range: ValueRange) => void
+  innerClasses?: string[]
+  reverseLabelOrder?: boolean
+}
+
+/**
+ * LegendValueRange - Generic component for displaying value range legends
+ *
+ * Used by Horizon Charts to show layer intensity ranges (e.g., 1-100, 101-200).
+ * Can be reused by other chart types that need binned value legends.
+ */
+const LegendValueRange: React.FC<LegendValueRangeProps> = ({
+  minValue = 0,
+  maxValue,
+  numRanges,
+  distribution = 'equal',
+  formatNumber,
+  colors,
+  shape = 'square',
+  onClick,
+  innerClasses = ['legend-container__inner'],
+  reverseLabelOrder = false
+}) => {
+  const ranges = generateValueRanges({ minValue, maxValue, numRanges, distribution, formatNumber })
+
+  if (ranges.length === 0) return null
+
+  // Reverse both ranges and colors when reverseLabelOrder is true
+  const displayRanges = reverseLabelOrder ? [...ranges].reverse() : ranges
+  const displayColors = reverseLabelOrder ? [...colors].reverse() : colors
+
+  return (
+    <div className={innerClasses.join(' ')}>
+      {displayRanges.map((range, i) => {
+        const color = displayColors[i % displayColors.length]
+        const isClickable = typeof onClick === 'function'
+        const className = ['legend-item', `legend-text--range-${i}`, !isClickable && 'not-clickable'].filter(Boolean)
+
+        return (
+          <LegendItem
+            className={className.join(' ')}
+            tabIndex={isClickable ? 0 : -1}
+            key={`legend-range-${i}`}
+            onKeyDown={e => {
+              if (isClickable && e.key === 'Enter') {
+                e.preventDefault()
+                onClick(i, range)
+              }
+            }}
+            onClick={e => {
+              if (isClickable) {
+                e.preventDefault()
+                onClick(i, range)
+              }
+            }}
+            role={isClickable ? 'button' : undefined}
+          >
+            <LegendShape shape={shape} fill={color} />
+            <LegendLabel align='left' className='m-0'>
+              {range.label}
+            </LegendLabel>
+          </LegendItem>
+        )
+      })}
+    </div>
+  )
+}
+
+export default LegendValueRange

package/src/components/Legend/helpers/createFormatLabels.tsx

@@ -17,7 +17,8 @@ import { FaStar } from 'react-icons/fa'
 import { Label } from '../../../types/Label'
 import { ColorScale, TransformedData } from '../../../types/ChartContext'
 import { ChartConfig } from '../../../types/ChartConfig'
-import _ from 'lodash'
+import cloneDeep from 'lodash/cloneDeep'
+import sortBy from 'lodash/sortBy'
 import { scaleSequential } from 'd3-scale'
 import { interpolateRgbBasis } from 'd3-interpolate'
 import { filterChartColorPalettes } from '@cdc/core/helpers/filterColorPalettes'
@@ -173,7 +174,7 @@ export const createFormatLabels =
 
     const sortVertical = labels =>
       legend.verticalSorted
-        ? _.sortBy(_.cloneDeep(labels), label => {
+        ? sortBy(cloneDeep(labels), label => {
             const match = label.datum?.match(/-?\d+(\.\d+)?/)
             return match ? parseFloat(match[0]) : Number.MAX_SAFE_INTEGER
           })
@@ -342,6 +343,19 @@ export const createFormatLabels =
       return reverseLabels(seriesLabels)
     }
 
+    // For Radar charts, use the entity names from runtime.seriesKeys (set from xAxis.dataKey values)
+    // not the series names (which are the dimension keys)
+    if (visualizationType === 'Radar') {
+      const entityNames = runtime.seriesKeys || []
+      const radarLabels = entityNames.map((val, i) => ({
+        datum: val,
+        index: i,
+        text: String(val),
+        value: colorScale(val)
+      }))
+      return reverseLabels(radarLabels)
+    }
+
     if (config.series.some(item => item.name)) {
       const uniqueLabels = Array.from(new Set(config.series.map(d => d.name || d.dataKey))).map((val, i) => ({
         datum: val,

package/src/components/Legend/helpers/generateValueRanges.ts

@@ -0,0 +1,92 @@
+/**
+ * generateValueRanges - Creates value range bins for legend display
+ *
+ * Supports equal interval distribution with scaffolding for future quantile support.
+ * Ranges are inclusive with no overlap, starting at minValue or 0 (e.g., 1-100, 101-200).
+ */
+
+export type RangeDistribution = 'equal' | 'quantile'
+
+export type ValueRange = {
+  min: number
+  max: number
+  label: string
+}
+
+export type GenerateValueRangesOptions = {
+  minValue?: number
+  maxValue: number
+  numRanges: number
+  distribution?: RangeDistribution
+  formatNumber?: (value: number, axis?: string) => string
+}
+
+/**
+ * Generates an array of value ranges for legend display
+ */
+export const generateValueRanges = ({
+  minValue = 0,
+  maxValue,
+  numRanges,
+  distribution = 'equal',
+  formatNumber
+}: GenerateValueRangesOptions): ValueRange[] => {
+  if (numRanges <= 0 || maxValue <= minValue) {
+    return []
+  }
+
+  const ranges: ValueRange[] = []
+
+  if (distribution === 'equal') {
+    const rangeSize = (maxValue - minValue) / numRanges
+
+    for (let i = 0; i < numRanges; i++) {
+      // Calculate raw boundaries
+      const rawMin = minValue + i * rangeSize
+      const rawMax = minValue + (i + 1) * rangeSize
+
+      // For display:
+      // - First range starts at floor of minValue
+      // - Subsequent ranges start at previous max + 1 (monotonic constraint)
+      // - Last range ends exactly at ceil of maxValue
+      let displayMin: number
+      let displayMax: number
+
+      if (i === 0) {
+        displayMin = Math.floor(rawMin)
+      } else {
+        // Start at previous range's max + 1 to avoid overlap
+        displayMin = ranges[i - 1].max + 1
+      }
+
+      if (i === numRanges - 1) {
+        // Last range ends exactly at maxValue
+        displayMax = Math.ceil(maxValue)
+      } else {
+        displayMax = Math.floor(rawMax)
+      }
+
+      // Ensure min <= max (can happen with very small ranges)
+      if (displayMin > displayMax) {
+        displayMax = displayMin
+      }
+
+      // Format numbers if formatter provided
+      const formattedMin = formatNumber ? formatNumber(displayMin, 'left') : displayMin.toLocaleString()
+      const formattedMax = formatNumber ? formatNumber(displayMax, 'left') : displayMax.toLocaleString()
+
+      ranges.push({
+        min: displayMin,
+        max: displayMax,
+        label: displayMin === displayMax ? formattedMin : `${formattedMin}–${formattedMax}`
+      })
+    }
+  } else if (distribution === 'quantile') {
+    // Scaffolding for future quantile-based distribution
+    // Would require passing in the actual data values to calculate percentiles
+    // Currently, silently fall back to equal interval distribution
+    return generateValueRanges({ minValue, maxValue, numRanges, distribution: 'equal', formatNumber })
+  }
+
+  return ranges
+}

package/src/components/LineChart/helpers/README.md

@@ -0,0 +1,292 @@
+# Line Chart Label Positioning Algorithm
+
+## Overview
+
+This algorithm intelligently positions data point labels on line charts to prevent overlap with the chart lines themselves. It uses a quadrant-based system that analyzes line segment angles to determine optimal label placement.
+
+The algorithm is based on standard unit circle angle measurements (0° = right/east, 90° = up/north, 180° = left/west, 270° = down/south) and accounts for SVG's inverted y-axis.
+
+## Algorithm Design
+
+### Quadrant System
+
+Line segments are classified into quadrants based on their angle in the standard unit circle:
+
+- **Quadrant 1 (Q1)**: 1° - 89° (steep upward slope, right and up)
+- **Quadrant 2 (Q2)**: 91° - 179° (gentle downward slope, left and up)
+- **Quadrant 3 (Q3)**: 181° - 269° (steep downward slope, left and down)
+- **Quadrant 4 (Q4)**: 271° - 359° (gentle upward slope, right and down)
+
+### Constants
+
+- **Vertical Offset**: 9px (0.5rem) - used for vertical spacing
+- **Horizontal Offset**:
+  - **4.5px** (0.25rem) for first/last points
+  - **9px** (0.5rem) for middle points (more separation needed)
+- **Near X-Axis Threshold**: ≤20px from the bottom of the chart
+
+### Data Point Classification
+
+1. **First Point**: Only has an **ending segment** (line going OUT of the point, shown in pink)
+2. **Last Point**: Only has a **starting segment** (line coming INTO the point, shown in purple)
+3. **Middle Points**: Have both **starting** and **ending** segments
+
+## Positioning Rules
+
+### First Data Point Rules
+
+Only has ending segment (line going out):
+
+| Ending Segment Range | Near X-Axis (≤20px) | Position |
+|---------------------|---------------------|----------|
+| 180°–269° (Q3) | Any | 9px above |
+| 91°–179° (Q2) | NO | 9px below |
+| 91°–179° (Q2) | YES | 9px above, 4.5px left |
+| 269°–360° (Q4) | Any | 9px above |
+| Other | Any | 9px above (default) |
+
+### Last Data Point Rules
+
+Only has starting segment (line coming in):
+
+| Starting Segment Range | Near X-Axis (≤20px) | Position |
+|-----------------------|---------------------|----------|
+| 269°–360° (Q4) | Any (even near x-axis) | 9px above |
+| 1°–89° (Q1) | NO | 9px below |
+| 0°–89° (Q1) | YES | 9px above, 4.5px right |
+| Other | Any | 9px above (default) |
+
+### Middle Data Point Rules
+
+Has both starting and ending segments:
+
+#### Starting Q1 + Ending Q2 (Peak/Local Maximum)
+
+| Angle Between Segments | Near X-Axis | Additional Condition | Position |
+|------------------------|-------------|---------------------|----------|
+| 1°–179° | NO | - | 9px below |
+| ≥135° | YES | - | 9px above (centered) |
+| <135° | YES | Ending angle ≥68° | 9px above, 9px right |
+| <135° | YES | Ending angle <68° | 9px above, 9px left |
+
+#### Starting Q4 + Ending Q3
+
+| Angle Between Segments | Position |
+|------------------------|----------|
+| 0°–180° | 9px above |
+
+#### Starting Q4 + Ending Q2
+
+| Angle Between Segments | Position |
+|------------------------|----------|
+| 92°–269° | 9px above, 9px left |
+
+#### Starting Q1 + Ending Q3
+
+| Angle Between Segments | Position |
+|------------------------|----------|
+| 92°–269° | 9px above, 9px right |
+
+#### Default for All Other Middle Point Cases
+
+Position: **9px above** (centered)
+
+## API Reference
+
+### Primary Function
+
+```typescript
+function getLabelPositionForDataPoint(
+  dataPoints: Point[],
+  dataIndex: number,
+  chartHeight: number
+): LabelOffset
+
+interface Point {
+  x: number  // SVG x-coordinate
+  y: number  // SVG y-coordinate
+}
+
+interface LabelOffset {
+  dx: number              // Horizontal offset (positive = right)
+  dy: number              // Vertical offset (positive = down)
+  textAnchor?: 'start' | 'middle' | 'end'
+  verticalAnchor?: 'start' | 'middle' | 'end'
+}
+```
+
+### Alternative Function (Direct Angle Input)
+
+```typescript
+function calculateLabelOffset(
+  pointIndex: number,
+  pointY: number,
+  startingSegmentAngle: number | null,  // null for first point
+  endingSegmentAngle: number | null,    // null for last point
+  xAxisY: number
+): { offsetX: number; offsetY: number }
+```
+
+**Parameters:**
+- `pointY`: Y-coordinate of the point in SVG coordinates
+- `startingSegmentAngle`: Angle of line segment coming INTO point (null for first point)
+- `endingSegmentAngle`: Angle of line segment going OUT OF point (null for last point)
+- `xAxisY`: Y-coordinate of x-axis for "near axis" calculation
+- Returns: `offsetX` (positive = right), `offsetY` (positive = down)
+
+### Utility Functions
+
+```typescript
+// Calculate angle between two points (returns 0°-360°)
+function calculateAngle(fromPoint: Point, toPoint: Point): number
+
+// Determine which quadrant an angle belongs to
+function getQuadrant(angle: number): Quadrant
+
+// Calculate angle between two segments
+function calculateAngleBetweenSegments(
+  startingSegmentAngle: number,
+  endingSegmentAngle: number
+): number
+
+// Check if point is near x-axis (≤20px from bottom)
+function isNearXAxis(yPosition: number, chartHeight: number): boolean
+```
+
+## Usage Examples
+
+### Basic Integration
+
+```typescript
+import { getLabelPositionForDataPoint } from './labelPositioning'
+
+// Build array of point coordinates from your data
+const dataPoints = sortedData
+  .filter(item => isNumber(item[seriesKey]))
+  .map(item => ({
+    x: xScale(item.xValue),
+    y: yScale(item.yValue)
+  }))
+
+// For each data point, calculate label position
+dataPoints.forEach((point, index) => {
+  const labelOffset = getLabelPositionForDataPoint(
+    dataPoints,
+    index,
+    Number(chartHeight)
+  )
+
+  // Render label with offset
+  <Text
+    x={point.x + labelOffset.dx}
+    y={point.y + labelOffset.dy}
+    textAnchor={labelOffset.textAnchor || 'middle'}
+    verticalAnchor={labelOffset.verticalAnchor || 'middle'}
+  >
+    {formatNumber(data[index].value)}
+  </Text>
+})
+```
+
+### Using Pre-Calculated Angles
+
+```typescript
+import { calculateLabelOffset } from './labelPositioning'
+
+// If you already have angles calculated
+const startAngle = 45   // Coming from bottom-right
+const endAngle = 135    // Going to top-left
+const pointY = 200
+const xAxisY = 450
+
+const offset = calculateLabelOffset(
+  5,           // Point index (for determining first/last/middle)
+  pointY,
+  startAngle,
+  endAngle,
+  xAxisY
+)
+
+// offset.offsetX and offset.offsetY contain the pixel offsets
+```
+
+## Testing
+
+### Unit Tests
+
+Run tests with: `npm test labelPositioning.test.ts`
+
+Tests verify:
+- Angle calculations (0°, 90°, 180°, 270°, and diagonals)
+- Quadrant classification
+- Near x-axis detection
+- All first point rules
+- All last point rules
+- All middle point rules including Q1→Q2 special cases
+- Edge cases (vertical/horizontal lines, boundary angles)
+
+### Visual Testing in Storybook
+
+Navigate to: **Components → Templates → Chart → QuadrantAngles**
+
+Available test scenarios:
+- **All Quadrants** - Combined view of all angles
+- **Q1 Steep Upward** - Isolated testing of 1°-89° angles
+- **Q2 Gentle Downward** - Isolated testing of 91°-179° angles
+- **Q3 Steep Downward** - Isolated testing of 181°-269° angles
+- **Q4 Gentle Upward** - Isolated testing of 271°-359° angles
+- **Near Zero Rise** - Edge case near 0°/360°
+- **Near Zero Fall** - Edge case near 180°
+
+## Implementation Details
+
+### Angle Calculation
+
+The algorithm uses `Math.atan2(-dy, dx)` to calculate angles:
+- Negative `dy` accounts for SVG's inverted y-axis
+- Result is normalized to [0, 360) range
+- Standard unit circle convention: 0° = right, 90° = up, 180° = left, 270° = down
+
+### Coordinate Systems
+
+**SVG Coordinates:**
+- x increases rightward
+- y increases downward (inverted from Cartesian)
+
+**Angle Measurement:**
+- Standard unit circle (0° = east, counterclockwise)
+- Algorithm internally converts SVG coordinates to standard angles
+
+### Near X-Axis Detection
+
+A point is considered "near x-axis" when:
+```typescript
+(chartHeight - pointY) <= 20
+```
+
+Where `chartHeight` is the bottom of the chart (y-axis maximum in SVG coords).
+
+## Performance Considerations
+
+1. **Per-Point Calculation**: Algorithm runs for each data point on every render
+2. **Optimization Strategies**:
+   - Consider memoizing results for static datasets
+   - Pre-calculate all points during data transformation
+   - Use `React.useMemo` for data point arrays
+
+## Constraints and Limitations
+
+1. **No Label-to-Label Collision Detection**: Algorithm only prevents line overlap, not label overlap
+2. **Fixed Offsets**: Doesn't adapt to label text width/height
+3. **Single Series**: Doesn't consider proximity to other series' lines
+4. **Static Rules**: No learning or adaptation based on actual rendered results
+
+## Future Enhancements
+
+- [ ] Dynamic collision detection between labels
+- [ ] Adaptive offset scaling based on chart dimensions
+- [ ] Support for rotated/angled labels
+- [ ] Label width-aware positioning
+- [ ] Multi-series collision avoidance
+- [ ] Configurable offset constants
+- [ ] Label priority system for dense datasets