@cdc/chart 4.26.7 → 4.26.10

package/src/components/Dendrogram/helpers/layoutDendrogram.ts

@@ -0,0 +1,56 @@
+import { stratify } from '@visx/hierarchy'
+import { cluster } from 'd3-hierarchy'
+
+import type { DendrogramLayout, DendrogramLayoutNode, DendrogramOrientation, DendrogramPreparedData } from '../types'
+
+type LayoutOptions = {
+  orientation: DendrogramOrientation
+  leafSpacing: number
+  depthSpacing: number
+  nodeRadius: number
+}
+
+const getPositiveNumber = (value: unknown, fallback: number, minimum: number, maximum: number) => {
+  const parsed = Number(value)
+  return Math.min(maximum, Math.max(minimum, Number.isFinite(parsed) ? parsed : fallback))
+}
+
+export const layoutDendrogram = (prepared: DendrogramPreparedData, options: LayoutOptions): DendrogramLayout => {
+  if (!prepared.rootId || prepared.error || !prepared.nodes.length) return { nodes: [], links: [] }
+
+  const leafSpacing = getPositiveNumber(options.leafSpacing, 40, 12, 10000)
+  const depthSpacing = getPositiveNumber(options.depthSpacing, 140, 24, 10000)
+  const nodeRadius = getPositiveNumber(options.nodeRadius, 6, 2, 1000)
+  const root = stratify<(typeof prepared.nodes)[number]>()
+    .id(node => node.id)
+    .parentId(node => node.parentId)(prepared.nodes)
+
+  cluster<(typeof prepared.nodes)[number]>().nodeSize([leafSpacing, depthSpacing])(root)
+
+  const descendants = root.descendants()
+  const minimumCrossAxis = descendants.reduce((minimum, node) => Math.min(minimum, node.x), Infinity)
+  const padding = nodeRadius + 12
+  const nodes = descendants.map(node => {
+    const depthPosition = node.y + padding
+    const leafPosition = node.x - minimumCrossAxis + padding
+    const x = options.orientation === 'vertical' ? leafPosition : depthPosition
+    const y = options.orientation === 'vertical' ? depthPosition : leafPosition
+    return {
+      ...node.data,
+      depth: node.depth,
+      x,
+      y
+    } satisfies DendrogramLayoutNode
+  })
+  const nodesById = new Map(nodes.map(node => [node.id, node]))
+  const links = nodes
+    .filter(node => node.parentId !== null)
+    .map(node => ({
+      id: JSON.stringify([node.parentId, node.id]),
+      source: nodesById.get(node.parentId!)!,
+      target: node,
+      style: node.style
+    }))
+
+  return { nodes, links }
+}

package/src/components/Dendrogram/helpers/prepareDendrogramData.test.ts

@@ -0,0 +1,135 @@
+import { prepareDendrogramData } from './prepareDendrogramData'
+
+describe('prepareDendrogramData', () => {
+  const columns = { node: 'id', parent: 'parentId', style: 'linkStyle', nodeColor: 'color' }
+
+  it('prepares one row per node with optional styles and literal colors', () => {
+    const result = prepareDendrogramData(
+      [
+        { id: 'root', parentId: '', linkStyle: 'dashed', color: '#005eaa' },
+        { id: 'child', parentId: 'root', linkStyle: 'DASHED', color: 'not-a-color' },
+        { id: 3, parentId: 'child' }
+      ],
+      columns
+    )
+
+    expect(result).toEqual({
+      rootId: 'root',
+      rejectedRowCount: 0,
+      nodes: [
+        { id: 'root', parentId: null, label: 'root', style: 'dashed', color: '#005eaa' },
+        { id: 'child', parentId: 'root', label: 'child', style: 'dashed' },
+        { id: '3', parentId: 'child', label: '3', style: 'solid' }
+      ]
+    })
+  })
+
+  it('rejects malformed rows and non-scalar identifiers', () => {
+    const result = prepareDendrogramData(
+      [
+        null,
+        ['root'],
+        { id: { value: 'root' }, parentId: '' },
+        { id: 'root', parentId: [] },
+        { id: 'ok', parentId: '' }
+      ],
+      columns
+    )
+
+    expect(result.rejectedRowCount).toBe(4)
+    expect(result.nodes).toEqual([{ id: 'ok', parentId: null, label: 'ok', style: 'solid' }])
+    expect(result.error).toBeUndefined()
+  })
+
+  it('handles null mappings and deeply nested hierarchies without recursion', () => {
+    expect(prepareDendrogramData([{ id: 'root', parentId: '' }], null as any)).toEqual({
+      nodes: [],
+      rejectedRowCount: 1
+    })
+
+    const rows = Array.from({ length: 5000 }, (_, index) => ({
+      id: `node-${index}`,
+      parentId: index === 0 ? '' : `node-${index - 1}`
+    }))
+    const result = prepareDendrogramData(rows, columns)
+    expect(result.error).toBeUndefined()
+    expect(result.nodes).toHaveLength(5000)
+  })
+
+  it('counts duplicate node IDs as rejected rows', () => {
+    const result = prepareDendrogramData(
+      [
+        { id: 'root', parentId: '' },
+        { id: 'root', parentId: '' }
+      ],
+      columns
+    )
+
+    expect(result.error?.code).toBe('duplicate-node')
+    expect(result.rejectedRowCount).toBe(1)
+  })
+
+  it.each([
+    {
+      name: 'duplicate IDs',
+      rows: [
+        { id: 'root', parentId: '' },
+        { id: 'root', parentId: '' }
+      ],
+      code: 'duplicate-node'
+    },
+    {
+      name: 'multiple roots',
+      rows: [
+        { id: 'root-a', parentId: '' },
+        { id: 'root-b', parentId: '' }
+      ],
+      code: 'multiple-roots'
+    },
+    {
+      name: 'missing parents',
+      rows: [
+        { id: 'root', parentId: '' },
+        { id: 'child', parentId: 'missing' }
+      ],
+      code: 'missing-parent'
+    },
+    {
+      name: 'self-parenting',
+      rows: [
+        { id: 'root', parentId: '' },
+        { id: 'child', parentId: 'child' }
+      ],
+      code: 'self-parent'
+    },
+    {
+      name: 'cycles',
+      rows: [
+        { id: 'root', parentId: '' },
+        { id: 'a', parentId: 'b' },
+        { id: 'b', parentId: 'a' }
+      ],
+      code: 'cycle'
+    }
+  ])('returns an actionable validation error for $name', ({ rows, code }) => {
+    const result = prepareDendrogramData(rows, columns)
+
+    expect(result.error?.code).toBe(code)
+    expect(result.error?.message).toBeTruthy()
+    expect(result.rootId).toBeUndefined()
+  })
+
+  it('does not mutate source rows or config mappings', () => {
+    const rows = [
+      { id: 'root', parentId: '' },
+      { id: 'child', parentId: 'root' }
+    ]
+    const rowsBefore = structuredClone(rows)
+    const columnsBefore = structuredClone(columns)
+
+    prepareDendrogramData(rows, columns)
+
+    expect(rows).toEqual(rowsBefore)
+    expect(columns).toEqual(columnsBefore)
+  })
+})

package/src/components/Dendrogram/helpers/prepareDendrogramData.ts

@@ -0,0 +1,166 @@
+import { sanitizePaletteColor } from '@cdc/core/helpers/palettes/colorValidation'
+
+import type {
+  DendrogramColumns,
+  DendrogramNode,
+  DendrogramPreparedData,
+  DendrogramRawRow,
+  DendrogramValidationError
+} from '../types'
+
+const getScalar = (row: DendrogramRawRow, column?: string): string | null => {
+  if (!column) return null
+  const value = row[column]
+  if (!['string', 'number'].includes(typeof value)) return null
+  const normalized = String(value).trim()
+  return normalized || null
+}
+
+const getParent = (row: DendrogramRawRow, column?: string): string | null | undefined => {
+  if (!column) return undefined
+  const value = row[column]
+  if (value === null || typeof value === 'undefined' || value === '') return null
+  if (!['string', 'number'].includes(typeof value)) return undefined
+  return String(value).trim() || null
+}
+
+const getError = (nodes: DendrogramNode[]): { rootId?: string; error?: DendrogramValidationError } => {
+  const nodesById = new Map<string, DendrogramNode>()
+  for (const node of nodes) {
+    if (nodesById.has(node.id)) {
+      return {
+        error: {
+          code: 'duplicate-node',
+          message: `Node ID “${node.id}” appears more than once. Each node must have a unique ID.`
+        }
+      }
+    }
+    nodesById.set(node.id, node)
+  }
+
+  const selfParent = nodes.find(node => node.parentId === node.id)
+  if (selfParent) {
+    return {
+      error: {
+        code: 'self-parent',
+        message: `Node “${selfParent.id}” cannot be its own parent.`
+      }
+    }
+  }
+
+  const missingParentNode = nodes.find(node => node.parentId !== null && !nodesById.has(node.parentId))
+  if (missingParentNode) {
+    return {
+      error: {
+        code: 'missing-parent',
+        message: `Node “${missingParentNode.id}” references missing parent “${missingParentNode.parentId}”.`
+      }
+    }
+  }
+
+  const visited = new Set<string>()
+  for (const node of nodes) {
+    if (visited.has(node.id)) continue
+    const path = new Set<string>()
+    const pathNodes: string[] = []
+    let current: DendrogramNode | undefined = node
+    while (current && !visited.has(current.id)) {
+      if (path.has(current.id)) {
+        return {
+          error: {
+            code: 'cycle',
+            message: `The hierarchy contains a cycle involving node “${current.id}”. Remove the circular parent relationship.`
+          }
+        }
+      }
+      path.add(current.id)
+      pathNodes.push(current.id)
+      current = current.parentId === null ? undefined : nodesById.get(current.parentId)
+    }
+    pathNodes.forEach(id => visited.add(id))
+  }
+
+  const roots = nodes.filter(node => node.parentId === null)
+  if (!roots.length) {
+    return {
+      error: {
+        code: 'missing-root',
+        message: 'The hierarchy needs one root row with a blank Parent ID.'
+      }
+    }
+  }
+  if (roots.length > 1) {
+    return {
+      error: {
+        code: 'multiple-roots',
+        message: `The hierarchy has ${roots.length} roots. Leave Parent ID blank for exactly one row.`
+      }
+    }
+  }
+
+  const rootId = roots[0].id
+  const childrenByParent = new Map<string, string[]>()
+  nodes.forEach(node => {
+    if (node.parentId === null) return
+    const siblings = childrenByParent.get(node.parentId)
+    if (siblings) siblings.push(node.id)
+    else childrenByParent.set(node.parentId, [node.id])
+  })
+  const reachable = new Set<string>()
+  const pending = [rootId]
+  while (pending.length) {
+    const id = pending.pop()!
+    if (reachable.has(id)) continue
+    reachable.add(id)
+    childrenByParent.get(id)?.forEach(childId => pending.push(childId))
+  }
+  if (reachable.size !== nodes.length) {
+    return {
+      error: {
+        code: 'disconnected',
+        message: 'Every node must connect to the single root. Check the Parent ID relationships.'
+      }
+    }
+  }
+
+  return { rootId }
+}
+
+export const prepareDendrogramData = (data: unknown, columns: DendrogramColumns = {}): DendrogramPreparedData => {
+  const safeColumns = columns && typeof columns === 'object' ? columns : {}
+  const rawRows = Array.isArray(data) ? data : []
+  const nodes: DendrogramNode[] = []
+  let rejectedRowCount = 0
+
+  rawRows.forEach(rawRow => {
+    if (!rawRow || typeof rawRow !== 'object' || Array.isArray(rawRow)) {
+      rejectedRowCount += 1
+      return
+    }
+
+    const row = rawRow as DendrogramRawRow
+    const id = getScalar(row, safeColumns.node)
+    const parentId = getParent(row, safeColumns.parent)
+    if (!id || typeof parentId === 'undefined') {
+      rejectedRowCount += 1
+      return
+    }
+
+    const style = String(safeColumns.style ? row[safeColumns.style] ?? '' : '')
+      .trim()
+      .toLowerCase()
+    const color = safeColumns.nodeColor ? sanitizePaletteColor(row[safeColumns.nodeColor]) : ''
+    nodes.push({
+      id,
+      parentId,
+      label: id,
+      style: style === 'dashed' ? 'dashed' : 'solid',
+      ...(color ? { color } : {})
+    })
+  })
+
+  if (!nodes.length) return { nodes, rejectedRowCount }
+
+  const duplicateCount = nodes.length - new Set(nodes.map(node => node.id)).size
+  return { nodes, rejectedRowCount: rejectedRowCount + duplicateCount, ...getError(nodes) }
+}

package/src/components/Dendrogram/helpers/resolveDendrogramLabels.test.ts

@@ -0,0 +1,196 @@
+import type { DendrogramLayoutLink, DendrogramLayoutNode } from '../types'
+import { layoutDendrogram } from './layoutDendrogram'
+import { prepareDendrogramData } from './prepareDendrogramData'
+import {
+  estimateDendrogramLabelWidth,
+  resolveDendrogramLabels,
+  resolveDendrogramLabelsWithDiagnostics
+} from './resolveDendrogramLabels'
+
+const makeNode = (id: string, x: number, y: number, depth = 0): DendrogramLayoutNode => ({
+  id,
+  parentId: depth ? 'root' : null,
+  label: id,
+  style: 'solid',
+  depth,
+  x,
+  y
+})
+
+const makeLink = (source: DendrogramLayoutNode, target: DendrogramLayoutNode): DendrogramLayoutLink => ({
+  id: `${source.id}-${target.id}`,
+  source,
+  target,
+  style: 'solid'
+})
+
+describe('resolveDendrogramLabels', () => {
+  it('moves an internal horizontal label away from its outgoing connector', () => {
+    const root = makeNode('A long root label', 20, 40)
+    const child = makeNode('Child', 160, 40, 1)
+    const placements = resolveDendrogramLabels([root, child], [makeLink(root, child)], {
+      orientation: 'horizontal',
+      connectionType: 'line',
+      nodeRadius: 6
+    })
+
+    expect(placements.find(placement => placement.nodeId === root.id)?.anchor).toBe('top')
+    expect(placements.find(placement => placement.nodeId === child.id)?.anchor).toBe('right')
+  })
+
+  it('moves an internal vertical label away from its outgoing connector', () => {
+    const root = makeNode('A long root label', 40, 20)
+    const child = makeNode('Child', 40, 160, 1)
+    const placements = resolveDendrogramLabels([root, child], [makeLink(root, child)], {
+      orientation: 'vertical',
+      connectionType: 'curve',
+      nodeRadius: 6
+    })
+
+    expect(placements.find(placement => placement.nodeId === root.id)?.anchor).toBe('right')
+    expect(placements.find(placement => placement.nodeId === child.id)?.anchor).toBe('bottom')
+  })
+
+  it('avoids previously placed label bounds when another candidate is available', () => {
+    const first = makeNode('Long first label', 40, 40)
+    const second = makeNode('Long second label', 40, 50)
+    const placements = resolveDendrogramLabels([first, second], [], {
+      orientation: 'horizontal',
+      connectionType: 'elbow',
+      nodeRadius: 2
+    })
+
+    expect(placements[0].anchor).toBe('right')
+    expect(placements[1].anchor).not.toBe('right')
+  })
+
+  it('uses stable orientation priority when every candidate conflicts', () => {
+    const target = makeNode('Target', 100, 100)
+    const blockers = [
+      makeNode('top', 100, 75),
+      makeNode('right', 145, 100),
+      makeNode('bottom', 100, 125),
+      makeNode('left', 55, 100)
+    ]
+    const options = {
+      orientation: 'horizontal' as const,
+      connectionType: 'line' as const,
+      nodeRadius: 20,
+      characterWidth: 7,
+      labelHeight: 14,
+      labelGap: 0
+    }
+
+    const first = resolveDendrogramLabels([target, ...blockers], [], options)
+    const second = resolveDendrogramLabels([target, ...blockers], [], options)
+
+    expect(second).toEqual(first)
+    expect(first[0].anchor).toBe('right')
+  })
+
+  it('does not mutate layout input', () => {
+    const root = makeNode('Root', 20, 20)
+    const child = makeNode('Child', 160, 20, 1)
+    const nodes = [root, child]
+    const links = [makeLink(root, child)]
+    const before = structuredClone({ nodes, links })
+
+    resolveDendrogramLabels(nodes, links, {
+      orientation: 'horizontal',
+      connectionType: 'curve',
+      nodeRadius: 6
+    })
+
+    expect({ nodes, links }).toEqual(before)
+  })
+
+  it('uses conservative deterministic estimates for wide and non-ASCII glyphs', () => {
+    expect(estimateDendrogramLabelWidth('MMMM')).toBeGreaterThan(estimateDendrogramLabelWidth('iiii'))
+    expect(estimateDendrogramLabelWidth('健康')).toBeGreaterThan(estimateDendrogramLabelWidth('ii'))
+    expect(estimateDendrogramLabelWidth('健康')).toBeGreaterThanOrEqual(24)
+    expect(estimateDendrogramLabelWidth('🙂')).toBeGreaterThanOrEqual(12)
+    expect(estimateDendrogramLabelWidth('A🙂')).toBe(estimateDendrogramLabelWidth('A🙂'))
+  })
+
+  it('reserves the rendered line box for the 16px label font', () => {
+    const [placement] = resolveDendrogramLabels([makeNode('Label', 20, 20)], [], {
+      orientation: 'horizontal',
+      connectionType: 'line',
+      nodeRadius: 4
+    })
+
+    expect(placement.bounds.height).toBe(18)
+  })
+
+  it('detects a curved connector crossing a candidate label box', () => {
+    const labeled = makeNode('Crossing label', 90, 100)
+    const source = makeNode('Source', 0, 0)
+    const target = makeNode('Target', 200, 200, 1)
+    const placements = resolveDendrogramLabels([labeled, source, target], [makeLink(source, target)], {
+      orientation: 'horizontal',
+      connectionType: 'curve',
+      nodeRadius: 6
+    })
+
+    expect(placements[0].anchor).not.toBe('right')
+  })
+
+  it('spatially prefilters a large tree while preserving deterministic output', () => {
+    const rowCount = 1023
+    const prepared = prepareDendrogramData(
+      Array.from({ length: rowCount }, (_, index) => ({
+        id: `node-${index}`,
+        parentId: index === 0 ? '' : `node-${Math.floor((index - 1) / 2)}`
+      })),
+      { node: 'id', parent: 'parentId' }
+    )
+    const layout = layoutDendrogram(prepared, {
+      orientation: 'horizontal',
+      leafSpacing: 20,
+      depthSpacing: 100,
+      nodeRadius: 4
+    })
+    const options = { orientation: 'horizontal' as const, connectionType: 'curve' as const, nodeRadius: 4 }
+    const first = resolveDendrogramLabelsWithDiagnostics(layout.nodes, layout.links, options)
+    const second = resolveDendrogramLabelsWithDiagnostics(layout.nodes, layout.links, options)
+    const bruteForceChecks = layout.nodes.length * layout.nodes.length * 4
+
+    expect(first.placements).toHaveLength(rowCount)
+    expect(second).toEqual(first)
+    expect(first.diagnostics.nodeChecks).toBeLessThan(bruteForceChecks / 20)
+    expect(first.diagnostics.labelChecks).toBeLessThan(bruteForceChecks / 20)
+    expect(first.diagnostics.linkChecks).toBeLessThan(bruteForceChecks / 4)
+  })
+
+  it('deduplicates connector conflicts by link identity within each candidate', () => {
+    const labeled = makeNode('Crossing label', 90, 100)
+    const source = makeNode('Source', 0, 0)
+    const target = makeNode('Target', 200, 200, 1)
+    const nodes = [labeled, source, target]
+    const links = [makeLink(source, target)]
+    const baseOptions = {
+      orientation: 'horizontal' as const,
+      connectionType: 'curve' as const,
+      nodeRadius: 6
+    }
+    const coarse = resolveDendrogramLabelsWithDiagnostics(nodes, links, { ...baseOptions, curveTolerance: 2 })
+    const dense = resolveDendrogramLabelsWithDiagnostics(nodes, links, { ...baseOptions, curveTolerance: 0.01 })
+
+    expect(dense.diagnostics.linkChecks).toBeGreaterThan(coarse.diagnostics.linkChecks)
+    expect(coarse.diagnostics.linkConflicts).toBeLessThanOrEqual(nodes.length * 4)
+    expect(dense.diagnostics.linkConflicts).toBeLessThanOrEqual(nodes.length * 4)
+    expect(dense.placements).toEqual(coarse.placements)
+  })
+
+  it('handles labels spanning far more cells than the spatial-grid cap', () => {
+    const extremelyLongLabel = 'W'.repeat(100_000)
+    const nodes = [makeNode(extremelyLongLabel, 20, 20), makeNode('Nearby', 20, 40)]
+    const options = { orientation: 'horizontal' as const, connectionType: 'line' as const, nodeRadius: 4 }
+    const first = resolveDendrogramLabelsWithDiagnostics(nodes, [], options)
+    const second = resolveDendrogramLabelsWithDiagnostics(nodes, [], options)
+
+    expect(first.placements).toHaveLength(2)
+    expect(first.placements[0].bounds.width).toBe(1_600_000)
+    expect(second).toEqual(first)
+  })
+})