@lovett/ui 0.0.10 → 0.1.0

package/src/__tests__/donut-chart.test.tsx

@@ -0,0 +1,397 @@
+/**
+ * DonutChart — the named edge cases from ADR-146 acceptance criterion 8.
+ *
+ * A donut is the chart where the arithmetic edge cases bite hardest: an
+ * empty series divides by zero, a single category is a degenerate arc, a
+ * sub-1% slice is a sub-pixel dash, and a ninth entity has no hue to be
+ * drawn in. Each of those is pinned below.
+ *
+ * The suite runs with `css: false`, so a test cannot measure a painted
+ * colour. What it CAN assert is the value handed to the browser — a
+ * dasharray, a token expression, a rendered percentage — which is where
+ * every one of these defects actually lives.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import { fireEvent, render, screen } from '@testing-library/react'
+
+import {
+  DONUT_OTHER_KEY,
+  DonutChart,
+  foldDonutData,
+  withMinimumArc,
+  type DonutChartDatum,
+} from '../donut-chart'
+import { SERIES_SLOT_COUNT, isSeriesSlot } from '../lib/series'
+
+const EPS = 1e-9
+
+function datum(key: string, value: number): DonutChartDatum {
+  return { key, label: key, value }
+}
+
+/** Every arc segment in the plot, in draw order. The track and the focus
+ *  halo are excluded — they are the circles WITHOUT a dasharray. */
+function arcs(container: HTMLElement): SVGCircleElement[] {
+  return Array.from(
+    container.querySelectorAll<SVGCircleElement>('circle[stroke-dasharray]'),
+  ).filter((el) => el.getAttribute('aria-hidden') !== 'true')
+}
+
+describe('foldDonutData — the series cap (ADR-146 D2)', () => {
+  it('never assigns a ninth hue', () => {
+    const data = Array.from({ length: 12 }, (_, i) => datum(`k${i}`, 10))
+    const { slices, foldedCount } = foldDonutData(data)
+
+    expect(slices).toHaveLength(SERIES_SLOT_COUNT)
+    expect(foldedCount).toBe(12 - (SERIES_SLOT_COUNT - 1))
+    for (const slice of slices) {
+      if (slice.slot === 'other') continue
+      expect(isSeriesSlot(slice.slot)).toBe(true)
+    }
+  })
+
+  it('folds the remainder into one Other slice carrying its total', () => {
+    const data = [
+      datum('a', 50),
+      datum('b', 30),
+      datum('c', 7),
+      datum('d', 3),
+      datum('e', 2),
+    ]
+    const { slices, foldedCount } = foldDonutData(data, 3)
+
+    expect(foldedCount).toBe(3)
+    expect(slices).toHaveLength(3)
+    const other = slices[2]!
+    expect(other.key).toBe(DONUT_OTHER_KEY)
+    expect(other.slot).toBe('other')
+    expect(other.value).toBeCloseTo(12, 10)
+    expect(other.foldedCount).toBe(3)
+  })
+
+  it('does not fold when the data fits, and keeps a pinned slot', () => {
+    const { slices, foldedCount } = foldDonutData([
+      { key: 'a', label: 'A', value: 1, slot: 5 },
+      datum('b', 1),
+    ])
+    expect(foldedCount).toBe(0)
+    // Colour follows the entity, never its rank (D7).
+    expect(slices[0]!.slot).toBe(5)
+    expect(slices[1]!.slot).toBe(1)
+  })
+
+  it('clamps an out-of-range cap instead of asking for a hue that does not exist', () => {
+    const data = Array.from({ length: 20 }, (_, i) => datum(`k${i}`, 1))
+    expect(foldDonutData(data, 99).slices).toHaveLength(SERIES_SLOT_COUNT)
+    expect(foldDonutData(data, 0).slices).toHaveLength(1)
+  })
+})
+
+describe('withMinimumArc — a sub-1% slice is still visible', () => {
+  it('lifts a tiny slice to the floor and still closes the ring', () => {
+    const lifted = withMinimumArc([0.997, 0.003], 0.012)
+    expect(lifted[1]!).toBeCloseTo(0.012, 10)
+    expect(lifted[0]! + lifted[1]!).toBeCloseTo(1, 10)
+  })
+
+  it('leaves fractions that already clear the floor untouched', () => {
+    const lifted = withMinimumArc([0.5, 0.3, 0.2], 0.012)
+    expect(lifted[0]! - 0.5).toBeLessThan(EPS)
+    expect(lifted[2]! - 0.2).toBeLessThan(EPS)
+  })
+
+  it('does not lift a genuine zero into a visible arc', () => {
+    const lifted = withMinimumArc([1, 0], 0.012)
+    expect(lifted[1]!).toBe(0)
+  })
+
+  it('degrades to an even split rather than demanding more ring than exists', () => {
+    const many = Array.from({ length: 200 }, () => 1 / 200)
+    const lifted = withMinimumArc(many, 0.05)
+    const total = lifted.reduce((sum, f) => sum + f, 0)
+    expect(total).toBeCloseTo(1, 8)
+  })
+
+  it('reports all zeroes for an all-zero series instead of dividing by zero', () => {
+    expect(withMinimumArc([0, 0, 0], 0.012)).toEqual([0, 0, 0])
+  })
+})
+
+describe('DonutChart edge cases', () => {
+  it('draws one complete ring and no gaps for a single category', () => {
+    const { container } = render(
+      <DonutChart data={[datum('only', 42)]} label="Solo" />,
+    )
+    const segments = arcs(container)
+    expect(segments).toHaveLength(1)
+    // A full turn: the whole circumference painted, nothing left over.
+    expect(segments[0]!.getAttribute('stroke-dasharray')).toMatch(/ 0$/)
+    expect(segments[0]!.getAttribute('stroke-dashoffset')).toBe('0')
+    // One cut in an unbroken ring reads as a rendering fault.
+    expect(container.querySelectorAll('line')).toHaveLength(0)
+  })
+
+  it('renders an empty ring plus an empty state for all-zero values', () => {
+    const { container } = render(
+      <DonutChart
+        data={[datum('a', 0), datum('b', 0)]}
+        emptyMessage="Nothing yet."
+      />,
+    )
+    expect(arcs(container)).toHaveLength(0)
+    expect(screen.getByText('Nothing yet.')).toBeInTheDocument()
+    // The track still paints, so the widget reads as an empty ring rather
+    // than as a missing element.
+    const track = container.querySelector('circle:not([stroke-dasharray])')
+    expect(track).not.toBeNull()
+    expect(track!.getAttribute('stroke')).toBe('rgb(var(--muted))')
+  })
+
+  it('gives a <1% slice a visible arc while the legend reports the true share', () => {
+    const { container } = render(
+      <DonutChart data={[datum('big', 997), datum('tiny', 3)]} />,
+    )
+    const segments = arcs(container)
+    expect(segments).toHaveLength(2)
+
+    const dash = Number(
+      segments[1]!.getAttribute('stroke-dasharray')!.split(' ')[0],
+    )
+    const circumference =
+      dash + Number(segments[1]!.getAttribute('stroke-dasharray')!.split(' ')[1])
+    // Lifted to the 1.2% floor, well above the 0.3% it would otherwise get.
+    expect(dash / circumference).toBeGreaterThan(0.01)
+
+    // ...and the number the reader compares is still the TRUE fraction —
+    // reported as "<1%" rather than "0%", because a slice that is visibly
+    // drawn and labelled as nothing reads as a rendering fault.
+    expect(screen.getByText('tiny (<1%)')).toBeInTheDocument()
+    expect(screen.getByText('big (100%)')).toBeInTheDocument()
+  })
+
+  it('scales the sub-rounding label to the requested precision', () => {
+    render(
+      <DonutChart
+        data={[datum('big', 99970), datum('tiny', 30)]}
+        percentDecimals={1}
+      />,
+    )
+    expect(screen.getByText('tiny (<0.1%)')).toBeInTheDocument()
+  })
+
+  it('puts the percentage inside the legend label, not in a third column', () => {
+    render(
+      <DonutChart
+        data={[datum('Website', 50), datum('Referral', 50)]}
+        formatValue={(v) => `${v}`}
+      />,
+    )
+    expect(screen.getByText('Website (50%)')).toBeInTheDocument()
+    expect(screen.getByText('Referral (50%)')).toBeInTheDocument()
+  })
+
+  it('makes the fold explicit in the legend', () => {
+    const data = Array.from({ length: 11 }, (_, i) => datum(`k${i}`, 10))
+    render(<DonutChart data={data} />)
+    expect(screen.getByText(/^Other \(/)).toBeInTheDocument()
+    expect(screen.getByText('4 smaller categories')).toBeInTheDocument()
+  })
+})
+
+describe('DonutChart interaction', () => {
+  const data = [datum('a', 60), datum('b', 40)]
+
+  it('raises the hovered segment and shows a tooltip', () => {
+    const { container } = render(<DonutChart data={data} />)
+    const segments = arcs(container)
+    const base = segments[0]!.getAttribute('stroke-width')
+
+    expect(container.querySelector('[role="tooltip"]')).toBeNull()
+    fireEvent.mouseEnter(segments[0]!.parentElement!)
+
+    const raised = arcs(container)[0]!.getAttribute('stroke-width')
+    expect(Number(raised)).toBeGreaterThan(Number(base))
+    expect(container.querySelector('[role="tooltip"]')).not.toBeNull()
+
+    fireEvent.mouseLeave(segments[0]!.parentElement!)
+    expect(container.querySelector('[role="tooltip"]')).toBeNull()
+  })
+
+  it('is keyboard reachable and activates on Enter', () => {
+    const onSelect = vi.fn()
+    render(<DonutChart data={data} onSelect={onSelect} />)
+
+    const marks = screen.getAllByRole('button', { name: /^a,/ })
+    const mark = marks[0]!
+    expect(mark.getAttribute('tabindex')).toBe('0')
+
+    fireEvent.focus(mark)
+    fireEvent.keyDown(mark, { key: 'Enter' })
+    expect(onSelect).toHaveBeenCalledWith('a')
+  })
+
+  it('cuts deep enough to still divide a RAISED segment', () => {
+    // The hover "raise" grows the stroke around the same centreline, so a cut
+    // sized for the resting stroke leaves a coloured nub at each end of the
+    // hovered segment. The cut has to reach past the widest stroke a segment
+    // can paint.
+    const { container } = render(<DonutChart data={data} />)
+    const strokeWidth = Number(arcs(container)[0]!.getAttribute('stroke-width'))
+
+    fireEvent.mouseEnter(arcs(container)[0]!.parentElement!)
+    const raised = Number(arcs(container)[0]!.getAttribute('stroke-width'))
+    expect(raised).toBeGreaterThan(strokeWidth)
+
+    const cut = container.querySelector('line')!
+    const length = Math.hypot(
+      Number(cut.getAttribute('x2')) - Number(cut.getAttribute('x1')),
+      Number(cut.getAttribute('y2')) - Number(cut.getAttribute('y1')),
+    )
+    expect(length).toBeGreaterThanOrEqual(raised)
+  })
+
+  it('dims nothing when a controlled activeKey no longer names a slice', () => {
+    // A filter can drop the series that was hovered. The chart must not grey
+    // itself out with no segment raised to explain why.
+    const { container } = render(
+      <DonutChart data={data} activeKey="removed-by-a-filter" />,
+    )
+    for (const arc of arcs(container)) {
+      expect(arc.getAttribute('opacity')).toBe('1')
+    }
+    expect(container.querySelector('[role="tooltip"]')).toBeNull()
+  })
+
+  it('is inert — no button role — when no onSelect is given', () => {
+    const { container } = render(<DonutChart data={data} />)
+    expect(container.querySelectorAll('g[role="button"]')).toHaveLength(0)
+    expect(container.querySelectorAll('g[role="img"]')).toHaveLength(2)
+  })
+
+  it('swaps the centre readout to the hovered segment without unmounting it', () => {
+    const { container } = render(
+      <DonutChart
+        data={data}
+        centerValue="100"
+        centerCaption="Sessions"
+        formatValue={(v) => `${v}`}
+      />,
+    )
+    expect(screen.getByText('100')).toBeInTheDocument()
+    expect(screen.getByText('Sessions')).toBeInTheDocument()
+
+    fireEvent.mouseEnter(arcs(container)[0]!.parentElement!)
+    // "60" now reads in two places — the centre and the tooltip — which is
+    // the point: they are the same number resolved the same way.
+    expect(screen.getAllByText('60').length).toBeGreaterThanOrEqual(1)
+    expect(screen.queryByText('100')).toBeNull()
+    expect(screen.getAllByText('a').length).toBeGreaterThanOrEqual(1)
+  })
+})
+
+/**
+ * The two narrow-width defects measured in a real browser on 2026-09-06,
+ * light and dark, at a 390px viewport.
+ *
+ * WHAT jsdom CAN SEE, AND WHAT IT CANNOT
+ * --------------------------------------
+ * These tests assert the MECHANISM — the geometry handed to the browser and
+ * the layout contract the fix depends on. They cannot prove the fix, because
+ * jsdom has no layout: every `getBoundingClientRect()` is zero, no flex line
+ * ever wraps, and the measured type-fit therefore stays at scale 1 here.
+ *
+ * The proof is a browser measurement, and it is the one that gates this:
+ *   - legend labels: `width` > 0 and `scrollWidth <= width` at 390 / 900 /
+ *     1440 in both themes;
+ *   - centre readout: its client rect sits inside the hole's rect for the
+ *     resting value AND for every value a focused segment can swap in.
+ * Both were run against the running app; neither is expressible below.
+ */
+describe('narrow widths — the legend and the centre (browser-measured)', () => {
+  const data = [datum('a', 60), datum('b', 40)]
+
+  it('lays the row out so the legend can WRAP rather than be starved', () => {
+    // The plot is `shrink-0`, so without `flex-wrap` a root narrower than
+    // plot + gap + legend gives the legend 0px and every label renders at
+    // `width: 0` — five series identified by colour alone. Measured at 390:
+    // legend column 0px wide, labels 0px against scrollWidths of 73-124px.
+    const { container } = render(<DonutChart data={data} />)
+    const root = container.firstElementChild
+    expect(root?.className).toContain('flex-wrap')
+  })
+
+  it('does not put a wrap basis on the column layout, where it would size height', () => {
+    // `flex-basis` in a column container is a HEIGHT, so the row layout's
+    // basis must not leak into `orientation="column"`.
+    const { container } = render(<DonutChart data={data} orientation="column" />)
+    const legend = container.querySelector('ul[aria-label$="legend"]')
+    const column = legend?.parentElement
+    expect(column?.getAttribute('style')).toContain('flex: 1 1 auto')
+  })
+
+  it('gives every legend label a width floor and a recoverable full label', () => {
+    // The floor is what a starved flex column runs into instead of crushing
+    // the label to zero, and `min(..., 100%)` is what keeps the floor from
+    // overflowing its container instead. `title` makes a truncated label
+    // recoverable — identity is never colour alone (ADR-146 D10.1).
+    const { container } = render(<DonutChart data={data} />)
+    const rows = container.querySelectorAll<HTMLElement>(
+      'ul[aria-label$="legend"] li',
+    )
+    expect(rows.length).toBe(2)
+    for (const row of rows) {
+      const label = row.querySelector<HTMLElement>('span[title]')
+      expect(label).not.toBeNull()
+      expect(label?.title).not.toBe('')
+      const wrapper = label?.parentElement
+      expect(wrapper?.style.minWidth).toBe(
+        'min(calc(var(--space-12) * 2), 100%)',
+      )
+      expect(row.firstElementChild?.className).toContain('flex-wrap')
+    }
+  })
+
+  it('reserves the centre against the HOLE, not the plot box', () => {
+    // size 160, default thickness -> stroke 27; outerRadius 80 - EDGE_RESERVE
+    // (4) = 76; centreline radius 76 - 27/2 = 62.5; hole at the RAISED stroke
+    // = 2*62.5 - 27 - HOVER_BUMP(4) = 94. Before the fix the readout was
+    // `inset-0` on the 160px plot box, and "$116,120" painted onto the arcs
+    // at both ends.
+    const { container } = render(
+      <DonutChart data={data} centerValue="$116,120" centerCaption="Spend" />,
+    )
+    const reserve = container.querySelector<HTMLElement>(
+      '.pointer-events-none.absolute > div',
+    )
+    expect(reserve).not.toBeNull()
+    expect(reserve?.style.width).toBe('94px')
+    expect(reserve?.style.width).not.toBe('160px')
+  })
+
+  it('tracks the hole through size and thickness', () => {
+    // 120 / stroke 12: outerRadius 60 - 4 = 56; radius 56 - 6 = 50;
+    // hole = 100 - 12 - 4 = 84.
+    const { container } = render(
+      <DonutChart data={data} size={120} thickness={12} centerValue="1" />,
+    )
+    const reserve = container.querySelector<HTMLElement>(
+      '.pointer-events-none.absolute > div',
+    )
+    expect(reserve?.style.width).toBe('84px')
+  })
+
+  it('keeps the measurement gauges out of the readable tree', () => {
+    // The fit is measured by filling ONE empty span per line, not by
+    // rendering every candidate as a hidden node — hidden duplicates of the
+    // value would put the same string in the DOM twice.
+    render(
+      <DonutChart
+        data={data}
+        centerValue="100"
+        centerCaption="Sessions"
+        formatValue={(v) => `${v}`}
+      />,
+    )
+    expect(screen.getAllByText('100')).toHaveLength(1)
+  })
+})