@cdc/chart 4.26.5 → 4.26.7

package/src/components/PieChart/helpers/labelPlacement.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest'
+import { getPieLabelPlacement, getPieLabelPosition } from './labelPlacement'
+
+describe('pie label placement', () => {
+  it('keeps labels inside regular pie slices when the slice has enough room', () => {
+    expect(
+      getPieLabelPlacement({
+        startAngle: 0,
+        endAngle: Math.PI / 2,
+        innerRadius: 0,
+        outerRadius: 120,
+        labelWidth: 50,
+        labelHeight: 28,
+        isDonut: false
+      })
+    ).toBe('inside')
+  })
+
+  it('moves regular pie labels outside when they are too wide for the slice', () => {
+    expect(
+      getPieLabelPlacement({
+        startAngle: 0,
+        endAngle: Math.PI / 8,
+        innerRadius: 0,
+        outerRadius: 120,
+        labelWidth: 80,
+        labelHeight: 28,
+        isDonut: false
+      })
+    ).toBe('outside')
+  })
+
+  it('always places donut labels outside the partition', () => {
+    expect(
+      getPieLabelPlacement({
+        startAngle: 0,
+        endAngle: Math.PI,
+        innerRadius: 60,
+        outerRadius: 120,
+        labelWidth: 20,
+        labelHeight: 20,
+        isDonut: true
+      })
+    ).toBe('outside')
+  })
+
+  it('anchors outside labels by side of the pie', () => {
+    const rightSide = getPieLabelPosition({
+      startAngle: 0,
+      endAngle: Math.PI / 8,
+      innerRadius: 0,
+      outerRadius: 120,
+      labelWidth: 80,
+      labelHeight: 28,
+      isDonut: false
+    })
+
+    const leftSide = getPieLabelPosition({
+      startAngle: Math.PI,
+      endAngle: Math.PI + Math.PI / 8,
+      innerRadius: 0,
+      outerRadius: 120,
+      labelWidth: 80,
+      labelHeight: 28,
+      isDonut: false
+    })
+
+    expect(rightSide.placement).toBe('outside')
+    expect(rightSide.textAnchor).toBe('start')
+    expect(leftSide.placement).toBe('outside')
+    expect(leftSide.textAnchor).toBe('end')
+  })
+
+  it('uses the same angle orientation as the arc generator', () => {
+    const topLabel = getPieLabelPosition({
+      startAngle: 0,
+      endAngle: Math.PI / 12,
+      innerRadius: 0,
+      outerRadius: 120,
+      labelWidth: 80,
+      labelHeight: 28,
+      isDonut: false
+    })
+
+    expect(topLabel.placement).toBe('outside')
+    expect(topLabel.y).toBeLessThan(0)
+  })
+})

package/src/components/PieChart/helpers/labelPlacement.ts

@@ -0,0 +1,95 @@
+export type PieLabelPlacement = 'inside' | 'outside'
+
+export type PieLabelAnchor = 'start' | 'middle' | 'end'
+
+export type PieLabelPosition = {
+  placement: PieLabelPlacement
+  x: number
+  y: number
+  textAnchor: PieLabelAnchor
+}
+
+type PieLabelPlacementOptions = {
+  startAngle: number
+  endAngle: number
+  innerRadius: number
+  outerRadius: number
+  labelWidth: number
+  labelHeight: number
+  isDonut: boolean
+  insidePadding?: number
+}
+
+type PieLabelPositionOptions = PieLabelPlacementOptions & {
+  outsideOffset?: number
+}
+
+const DEFAULT_INSIDE_PADDING = 12
+const DEFAULT_OUTSIDE_OFFSET = 22
+
+const getMidAngle = (startAngle: number, endAngle: number) => startAngle + (endAngle - startAngle) / 2
+const getArcPoint = (angle: number, radius: number) => ({
+  x: Math.sin(angle) * radius,
+  y: -Math.cos(angle) * radius
+})
+
+export const getPieLabelPlacement = ({
+  startAngle,
+  endAngle,
+  innerRadius,
+  outerRadius,
+  labelWidth,
+  labelHeight,
+  isDonut,
+  insidePadding = DEFAULT_INSIDE_PADDING
+}: PieLabelPlacementOptions): PieLabelPlacement => {
+  if (isDonut) return 'outside'
+
+  const angle = Math.abs(endAngle - startAngle)
+  const labelRadius = innerRadius + (outerRadius - innerRadius) * 0.62
+  const availableChord = 2 * labelRadius * Math.sin(angle / 2)
+  const availableRadialDepth = outerRadius - innerRadius
+
+  const hasEnoughArcWidth = labelWidth + insidePadding <= availableChord
+  const hasEnoughRadialDepth = labelHeight + insidePadding <= availableRadialDepth
+
+  return hasEnoughArcWidth && hasEnoughRadialDepth ? 'inside' : 'outside'
+}
+
+export const getPieLabelPosition = ({
+  startAngle,
+  endAngle,
+  innerRadius,
+  outerRadius,
+  labelWidth,
+  labelHeight,
+  isDonut,
+  insidePadding,
+  outsideOffset = DEFAULT_OUTSIDE_OFFSET
+}: PieLabelPositionOptions): PieLabelPosition => {
+  const placement = getPieLabelPlacement({
+    startAngle,
+    endAngle,
+    innerRadius,
+    outerRadius,
+    labelWidth,
+    labelHeight,
+    isDonut,
+    insidePadding
+  })
+  const midAngle = getMidAngle(startAngle, endAngle)
+  const labelRadius =
+    placement === 'inside' ? innerRadius + (outerRadius - innerRadius) * 0.62 : outerRadius + outsideOffset
+  const { x, y } = getArcPoint(midAngle, labelRadius)
+
+  if (placement === 'inside') {
+    return { placement, x, y, textAnchor: 'middle' }
+  }
+
+  return {
+    placement,
+    x,
+    y,
+    textAnchor: x < 0 ? 'end' : 'start'
+  }
+}

package/src/components/ScatterPlot/ScatterPlot.jsx

@@ -5,8 +5,9 @@ import { formatNumber as formatColNumber } from '@cdc/core/helpers/cove/number'
 import { publishAnalyticsEvent } from '@cdc/core/helpers/metrics/helpers'
 import { getVizTitle, getVizSubType } from '@cdc/core/helpers/metrics/utils'
 import { buildSeriesTooltipListHtml } from '../../helpers/tooltipHelpers'
+import { getSeriesColumnFormattingParams } from '../../helpers/seriesColumnSettings'
 
-const ScatterPlot = ({ xScale, yScale, yAxisWidth }) => {
+const ScatterPlot = ({ xScale, yScale, yAxisWidth, getXAxisData }) => {
   const {
     transformedData: data,
     config,
@@ -25,16 +26,7 @@ const ScatterPlot = ({ xScale, yScale, yAxisWidth }) => {
   // tooltips for additional columns
   const additionalColumns = Object.entries(config.columns)
     .filter(([_, value]) => value.tooltips)
-    .map(([_, value]) => [
-      value.label || value.name,
-      value.name,
-      {
-        addColPrefix: value.prefix,
-        addColSuffix: value.suffix,
-        addColRoundTo: value.roundToPlace,
-        addColCommas: value.commas
-      }
-    ])
+    .map(([_, value]) => [value.label || value.name, value.name, getSeriesColumnFormattingParams(value)])
   const handleTooltip = (item, s, dataIndex) => `<div>
     ${buildSeriesTooltipListHtml({
       config,
@@ -61,7 +53,7 @@ const ScatterPlot = ({ xScale, yScale, yAxisWidth }) => {
         return config.runtime.seriesKeys.map((s, index) => {
           const transparentArea = config.legend.behavior === 'highlight' && seriesHighlight.length > 0 && seriesHighlight.indexOf(s) === -1
           const displayArea = config.legend.behavior === 'highlight' || seriesHighlight.length === 0 || seriesHighlight.indexOf(s) !== -1
-          const seriesColor = config?.general?.palette?.customColors ? config.general.palette.customColors[index] : colorScale(config.runtime.seriesLabels?.[s] || s)
+          const seriesColor = colorScale(config.runtime.seriesLabels?.[s] || s)
 
           let pointStyles = {
             filter: 'unset',
@@ -78,7 +70,7 @@ const ScatterPlot = ({ xScale, yScale, yAxisWidth }) => {
             <circle
               key={`${dataIndex}-${index}`}
               r={circleRadii}
-              cx={xScale(item[config.xAxis.dataKey])}
+              cx={xScale(getXAxisData(item))}
               cy={yScale(item[s])}
               fill={displayArea ? seriesColor : 'transparent'}
               fillOpacity={transparentArea ? 0.25 : 1}

package/src/components/SmallMultiples/SmallMultipleTile.tsx

@@ -23,6 +23,7 @@ interface SmallMultipleTileProps {
   parentHeight?: number
   globalYAxisMax?: number
   globalYAxisMin?: number
+  globalYAxisTickValues?: number[]
   isFirstInRow?: boolean
   onHeightChange?: (tileKey: string, height: number) => void
   onChartRef?: (ref: any) => void
@@ -43,6 +44,7 @@ const SmallMultipleTile: React.FC<SmallMultipleTileProps> = ({
   parentWidth,
   globalYAxisMax,
   globalYAxisMin,
+  globalYAxisTickValues,
   isFirstInRow,
   onHeightChange,
   onChartRef,
@@ -152,6 +154,7 @@ const SmallMultipleTile: React.FC<SmallMultipleTileProps> = ({
     tableData: tileData, // Override with tile-specific filtered data (important for tooltip data lookup)
     parentRef: tileParentRef, // Override with tile-specific parentRef
     updateConfig: () => {}, // Prevent tile hooks from modifying global config
+    yAxisTickValues: globalYAxisTickValues,
     ...(customColorScale && { colorScale: customColorScale }) // Override colorScale if provided
   }
 

package/src/components/SmallMultiples/SmallMultiples.tsx

@@ -3,7 +3,7 @@ import SmallMultipleTile from './SmallMultipleTile'
 import ConfigContext from '../../ConfigContext'
 import useReduceData from '../../hooks/useReduceData'
 import useScales from '../../hooks/useScales'
-import { getYAxisAutoPaddingMode } from '../../helpers/getYAxisAutoPaddingMode'
+import { hasSpacedInlineLabel } from '../../helpers/hasSpacedInlineLabel'
 import { createCombinedDataForYAxis, applyTileOrder, createTileColorScale } from '../../helpers/smallMultiplesHelpers'
 import { isMobileSmallMultiplesViewport } from '@cdc/core/helpers/viewports'
 import './SmallMultiples.css'
@@ -12,6 +12,8 @@ import { ChartConfig } from '../../types/ChartConfig'
 interface SmallMultiplesProps {
   config: ChartConfig
   data: object[]
+  yAxisDomainData?: object[]
+  hasBoundarySuppression?: boolean
   svgRef?: React.RefObject<SVGAElement>
   parentWidth?: number
   parentHeight?: number
@@ -34,12 +36,21 @@ type TileHeaderRows = Array<Array<HTMLDivElement>>
 
 type TileHeaderEntries = Array<[string, HTMLDivElement]>
 
-const SmallMultiples: React.FC<SmallMultiplesProps> = ({ config, data, svgRef, parentWidth, parentHeight }) => {
+const SmallMultiples: React.FC<SmallMultiplesProps> = ({
+  config,
+  data,
+  yAxisDomainData,
+  hasBoundarySuppression = false,
+  svgRef,
+  parentWidth,
+  parentHeight
+}) => {
   const { currentViewport, colorScale, parentRef } = useContext(ConfigContext)
   const { mode, tileColumn, tilesPerRowDesktop, tilesPerRowMobile } = config.smallMultiples || {}
 
   const isMobile = isMobileSmallMultiplesViewport(currentViewport)
   const tilesPerRow = isMobile ? tilesPerRowMobile || 1 : tilesPerRowDesktop || 3
+  const dataForSharedYAxis = Array.isArray(yAxisDomainData) && yAxisDomainData.length > 0 ? yAxisDomainData : data
 
   // Figure out what objects to iterate over based on mode - memoized to prevent recalculation
   const tileItems = useMemo<Array<TileItem>>(() => {
@@ -80,6 +91,22 @@ const SmallMultiples: React.FC<SmallMultiplesProps> = ({ config, data, svgRef, p
     config.smallMultiples?.tileTitles
   ])
 
+  const sharedYAxisTileItems = useMemo<Array<TileItem>>(
+    () =>
+      mode === 'by-column'
+        ? Array.from(new Set(dataForSharedYAxis.map(row => row[tileColumn])))
+            .filter(val => val != null)
+            .sort()
+            .map(value => ({
+              key: value,
+              mode: 'by-column' as const,
+              tileValue: value,
+              tileColumn: tileColumn
+            }))
+        : tileItems,
+    [mode, dataForSharedYAxis, tileColumn, tileItems]
+  )
+
   // Calculate the grid styling based on tiles per row
   const gridGap = isMobile ? '1rem' : '2rem'
   const gridStyle = {
@@ -97,8 +124,8 @@ const SmallMultiples: React.FC<SmallMultiplesProps> = ({ config, data, svgRef, p
 
   // Create combined data and config for consistent Y-axis calculation
   const combinedDataForYAxis = useMemo(
-    () => createCombinedDataForYAxis(config, data, tileItems),
-    [config, data, tileItems]
+    () => createCombinedDataForYAxis(config, dataForSharedYAxis, sharedYAxisTileItems),
+    [config, dataForSharedYAxis, sharedYAxisTileItems]
   )
 
   const { minValue, maxValue, existPositiveValue, isAllLine } = useReduceData(
@@ -106,12 +133,13 @@ const SmallMultiples: React.FC<SmallMultiplesProps> = ({ config, data, svgRef, p
     combinedDataForYAxis.data
   )
 
-  const yAxisAutoPaddingMode = getYAxisAutoPaddingMode(config)
+  const usesSpacedInlineLabel = hasSpacedInlineLabel(config)
 
-  const { min, max } = useScales({
+  const { min, max, yTickValues } = useScales({
     config: combinedDataForYAxis.config,
     data: combinedDataForYAxis.data,
     tableData: combinedDataForYAxis.data,
+    hasBoundarySuppression,
     minValue,
     maxValue,
     existPositiveValue,
@@ -119,7 +147,7 @@ const SmallMultiples: React.FC<SmallMultiplesProps> = ({ config, data, svgRef, p
     xAxisDataMapped: [],
     xMax: parentWidth,
     yMax: parentHeight,
-    yAxisAutoPaddingMode,
+    hasSpacedInlineLabel: usesSpacedInlineLabel,
     currentViewport
   })
 
@@ -129,8 +157,8 @@ const SmallMultiples: React.FC<SmallMultiplesProps> = ({ config, data, svgRef, p
     if (typeof min !== 'number' || typeof max !== 'number') return null
     if (combinedDataForYAxis.data.length === 0) return null
 
-    return { min, max }
-  }, [config.smallMultiples?.independentYAxis, min, max, combinedDataForYAxis.data.length])
+    return { min, max, tickValues: yTickValues }
+  }, [config.smallMultiples?.independentYAxis, min, max, yTickValues, combinedDataForYAxis.data.length])
 
   const numberOfRows = useMemo(() => Math.ceil(tileItems.length / tilesPerRow), [tileItems.length, tilesPerRow])
 
@@ -257,6 +285,7 @@ const SmallMultiples: React.FC<SmallMultiplesProps> = ({ config, data, svgRef, p
               parentHeight={parentHeight}
               globalYAxisMax={globalYAxisValues?.max}
               globalYAxisMin={globalYAxisValues?.min}
+              globalYAxisTickValues={globalYAxisValues?.tickValues}
               isFirstInRow={index % tilesPerRow === 0}
               onHeightChange={handleTileHeightChange}
               onChartRef={ref => {

package/src/components/SmallMultiples/tests/SmallMultiples.test.tsx

@@ -0,0 +1,170 @@
+import React from 'react'
+import { render } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import ConfigContext from '../../../ConfigContext'
+import SmallMultiples from '../SmallMultiples'
+import { createMockChartContext, createMockConfig } from '../../LinearChart/tests/mockConfigContext'
+
+const tileProps = vi.hoisted(() => [] as any[])
+const mockUseReduceData = vi.hoisted(() => vi.fn())
+const mockUseScales = vi.hoisted(() => vi.fn())
+
+vi.mock('../SmallMultipleTile', () => ({
+  default: props => {
+    tileProps.push(props)
+    return <div data-testid={`tile-${props.tileKey}`} />
+  }
+}))
+
+vi.mock('../../../hooks/useReduceData', () => ({
+  default: (...args: any[]) => mockUseReduceData(...args)
+}))
+
+vi.mock('../../../hooks/useScales', () => ({
+  default: (...args: any[]) => mockUseScales(...args)
+}))
+
+describe('SmallMultiples', () => {
+  const createSmallMultiplesConfig = () =>
+    createMockConfig({
+      smallMultiples: {
+        mode: 'by-column',
+        tileColumn: 'Sex',
+        independentYAxis: false,
+        tilesPerRowDesktop: 2,
+        tilesPerRowMobile: 1
+      },
+      series: [{ dataKey: 'Cases', type: 'Bar' }] as any,
+      runtime: {
+        ...createMockConfig().runtime,
+        series: [{ dataKey: 'Cases', type: 'Bar' }],
+        seriesKeys: ['Cases'],
+        seriesLabelsAll: ['Cases']
+      } as any
+    })
+
+  beforeEach(() => {
+    tileProps.length = 0
+    mockUseReduceData.mockReset()
+    mockUseScales.mockReset()
+    mockUseReduceData.mockReturnValue({
+      minValue: 0,
+      maxValue: 100,
+      existPositiveValue: true,
+      isAllLine: false
+    })
+    mockUseScales.mockReturnValue({
+      min: 0,
+      max: 100,
+      yTickValues: [0, 50, 100]
+    })
+  })
+
+  it('uses stable domain data for the shared Y-axis while rendering filtered tile data', () => {
+    const filteredRows = [
+      { Sex: 'Male', Year: '2019', Cases: 10 },
+      { Sex: 'Female', Year: '2019', Cases: 20 }
+    ]
+    const stableDomainRows = [
+      ...filteredRows,
+      { Sex: 'Male', Year: '2020', Cases: 100 },
+      { Sex: 'Female', Year: '2020', Cases: 80 }
+    ]
+    const config = createSmallMultiplesConfig()
+    const context = createMockChartContext(config, {
+      colorScale: vi.fn(),
+      parentRef: { current: document.createElement('div') }
+    } as any)
+
+    render(
+      <ConfigContext.Provider value={context}>
+        <SmallMultiples
+          config={config}
+          data={filteredRows}
+          yAxisDomainData={stableDomainRows}
+          parentWidth={600}
+          parentHeight={300}
+        />
+      </ConfigContext.Provider>
+    )
+
+    const expectedSharedAxisRows = [
+      { Sex: 'Female', Year: '2019', Cases: 20 },
+      { Sex: 'Female', Year: '2020', Cases: 80 },
+      { Sex: 'Male', Year: '2019', Cases: 10 },
+      { Sex: 'Male', Year: '2020', Cases: 100 }
+    ]
+
+    expect(mockUseReduceData.mock.calls[0][1]).toEqual(expectedSharedAxisRows)
+    expect(mockUseScales.mock.calls[0][0].data).toEqual(expectedSharedAxisRows)
+    expect(mockUseScales.mock.calls[0][0].hasBoundarySuppression).toBe(false)
+    expect(tileProps).toHaveLength(2)
+    expect(tileProps[0].data).toBe(filteredRows)
+    expect(tileProps[0].globalYAxisMax).toBe(100)
+    expect(tileProps[0].globalYAxisTickValues).toEqual([0, 50, 100])
+  })
+
+  it('includes filtered-out tile values when calculating a stable shared Y-axis', () => {
+    const filteredRows = [{ Sex: 'Male', Year: '2019', Cases: 10 }]
+    const stableDomainRows = [...filteredRows, { Sex: 'Female', Year: '2019', Cases: 200 }]
+    const config = createSmallMultiplesConfig()
+    const context = createMockChartContext(config, {
+      colorScale: vi.fn(),
+      parentRef: { current: document.createElement('div') }
+    } as any)
+
+    render(
+      <ConfigContext.Provider value={context}>
+        <SmallMultiples
+          config={config}
+          data={filteredRows}
+          yAxisDomainData={stableDomainRows}
+          parentWidth={600}
+          parentHeight={300}
+        />
+      </ConfigContext.Provider>
+    )
+
+    expect(mockUseReduceData.mock.calls[0][1]).toEqual([
+      { Sex: 'Female', Year: '2019', Cases: 200 },
+      { Sex: 'Male', Year: '2019', Cases: 10 }
+    ])
+    expect(mockUseScales.mock.calls[0][0].data).toEqual([
+      { Sex: 'Female', Year: '2019', Cases: 200 },
+      { Sex: 'Male', Year: '2019', Cases: 10 }
+    ])
+    expect(mockUseScales.mock.calls[0][0].hasBoundarySuppression).toBe(false)
+    expect(tileProps).toHaveLength(1)
+    expect(tileProps[0].tileValue).toBe('Male')
+    expect(tileProps[0].data).toBe(filteredRows)
+  })
+
+  it('passes hasBoundarySuppression from shared stable-domain boundary rows', () => {
+    const filteredRows = [{ Sex: 'Male', Year: '2019', Cases: 10 }]
+    const stableDomainRows = [
+      { Sex: 'Female', Year: '2018', Cases: 'ABC' },
+      { Sex: 'Male', Year: '2019', Cases: 10 }
+    ]
+    const config = createSmallMultiplesConfig()
+    config.preliminaryData = [{ type: 'suppression', style: 'Dashed Small', column: '', value: 'ABC' }] as any
+    const context = createMockChartContext(config, {
+      colorScale: vi.fn(),
+      parentRef: { current: document.createElement('div') }
+    } as any)
+
+    render(
+      <ConfigContext.Provider value={context}>
+        <SmallMultiples
+          config={config}
+          data={filteredRows}
+          yAxisDomainData={stableDomainRows as any}
+          hasBoundarySuppression={true}
+          parentWidth={600}
+          parentHeight={300}
+        />
+      </ConfigContext.Provider>
+    )
+
+    expect(mockUseScales.mock.calls[0][0].hasBoundarySuppression).toBe(true)
+  })
+})

package/src/data/initial-state.js

@@ -78,6 +78,7 @@ const createInitialState = () => {
       titlePlacement: 'top',
       scalePadding: 10,
       tickRotation: 0,
+      autoMaxStrategy: 'clean-top-tick',
       anchors: [],
       shoMissingDataLabel: true,
       showMissingDataLine: true,
@@ -143,6 +144,8 @@ const createInitialState = () => {
       padding: 5,
       showYearsOnce: false,
       sortByRecentDate: false,
+      categoryOrder: [],
+      categoryOrderType: 'data',
       brushActive: false,
       brushDefaultRecentDateCount: undefined,
       brushDynamicYAxis: false,

package/src/helpers/calculateLeftYAxisWidth.ts

@@ -11,6 +11,7 @@ type CalculateLeftYAxisWidthProps = {
   data: any[]
   yScale: any
   numTicks: number
+  tickValues?: number[]
   parentWidth: number
   tickLabelFont: string
   axisLabelFontSize: number
@@ -28,7 +29,11 @@ type TickValueProps = Omit<
   'parentWidth' | 'tickLabelFont' | 'axisLabelFontSize' | 'handleLeftTickFormatting'
 >
 
-const getTickValues = ({ config, data, yScale, numTicks }: TickValueProps) => {
+const getTickValues = ({ config, data, yScale, numTicks, tickValues }: TickValueProps) => {
+  if (tickValues) {
+    return tickValues
+  }
+
   if (config.visualizationType === 'Forest Plot') {
     return data.map((_, index) => index)
   }
@@ -142,6 +147,7 @@ export const calculateLeftYAxisWidth = ({
   data,
   yScale,
   numTicks,
+  tickValues,
   parentWidth,
   tickLabelFont,
   axisLabelFontSize,
@@ -153,10 +159,10 @@ export const calculateLeftYAxisWidth = ({
     return getHorizonChartWidth({ config, parentWidth, tickLabelFont, axisLabelFontSize })
   }
 
-  const tickValues = getTickValues({ config, data, yScale, numTicks })
+  const measuredTickValues = getTickValues({ config, data, yScale, numTicks, tickValues })
   const { hideAxis, inlineLabel, labelsAboveGridlines } = config.yAxis
   const formattedTicks = formatMeasuredTickLabels({
-    tickValues,
+    tickValues: measuredTickValues,
     handleLeftTickFormatting,
     inlineLabel,
     labelsAboveGridlines

package/src/helpers/categoryOrder.ts

@@ -0,0 +1,60 @@
+import { ChartConfig } from '../types/ChartConfig'
+
+type DataRow = Record<string, any>
+
+export const isCustomCategoryOrderActive = (config: Pick<ChartConfig, 'xAxis'>) => {
+  return (
+    config.xAxis?.type === 'categorical' &&
+    config.xAxis?.categoryOrderType === 'custom' &&
+    Array.isArray(config.xAxis?.categoryOrder) &&
+    config.xAxis.categoryOrder.length > 0 &&
+    Boolean(config.xAxis?.dataKey)
+  )
+}
+
+export const getCategoryValues = (data: DataRow[] = [], dataKey?: string): string[] => {
+  if (!dataKey || !Array.isArray(data)) return []
+
+  const values: string[] = []
+  for (const row of data) {
+    const value = String(row?.[dataKey] ?? '')
+    if (value !== '') values.push(value)
+  }
+
+  return Array.from(new Set(values))
+}
+
+export const getOrderedCategoryValues = (
+  data: DataRow[] = [],
+  dataKey?: string,
+  categoryOrder: string[] = []
+): string[] => {
+  const values = getCategoryValues(data, dataKey)
+  if (!categoryOrder?.length) return values
+
+  const configuredValues = categoryOrder.map(String)
+  const configuredValueSet = new Set(configuredValues)
+  const valueSet = new Set(values)
+  const extras = values.filter(value => !configuredValueSet.has(value))
+
+  return [...configuredValues.filter(value => valueSet.has(value)), ...extras]
+}
+
+export const sortByCategoryOrder = (data: DataRow[] = [], config: Pick<ChartConfig, 'xAxis'>): DataRow[] => {
+  if (!Array.isArray(data) || !isCustomCategoryOrderActive(config)) return data
+
+  const dataKey = config.xAxis.dataKey
+  const categoryOrder = Array.from(new Set((config.xAxis.categoryOrder || []).map(String)))
+  const indexByValue = new Map(categoryOrder.map((value, index) => [value, index]))
+  return data
+    .map((row, originalIndex) => ({ row, originalIndex }))
+    .sort((a, b) => {
+      const indexA = indexByValue.get(String(a.row?.[dataKey] ?? ''))
+      const indexB = indexByValue.get(String(b.row?.[dataKey] ?? ''))
+      const rankA = indexA ?? Number.MAX_SAFE_INTEGER
+      const rankB = indexB ?? Number.MAX_SAFE_INTEGER
+
+      return rankA === rankB ? a.originalIndex - b.originalIndex : rankA - rankB
+    })
+    .map(({ row }) => row)
+}