@lovett/ui 0.0.11 → 0.2.0

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

@@ -0,0 +1,809 @@
+/**
+ * BarChart contract tests — ADR-146 D5 / D7 / D9, acceptance criterion 8.
+ *
+ * The suite runs with `css: false`, so nothing here measures a painted
+ * pixel. What it CAN assert is the set of things that were silently wrong in
+ * every hand-rolled bar strip this primitive replaces:
+ *
+ *   • the monochrome contract — exactly ONE bar at full accent, never a bar
+ *     coloured by its own value (D7);
+ *   • that a negative bar descends from the zero baseline instead of being
+ *     clamped to nothing, which is a chart that lies;
+ *   • that the degenerate inputs a charting library would have handled for
+ *     us — no data, one bar, all zero, one category — each render something
+ *     honest rather than a blank panel;
+ *   • that identity, the readout and the table view exist for keyboard and
+ *     assistive tech, not just for a mouse.
+ *
+ * jsdom reports every box as 0×0 and its ResizeObserver is a no-op stub, so
+ * the component's measurement path never fires here. That is deliberate: the
+ * layout is percentage-based precisely so that a chart renders correctly
+ * before anything has been measured. These tests exercise that path.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import { render, screen, within } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+
+import { BarChart, type BarChartDatum, type BarChartSeries } from '../bar-chart'
+
+const DATA: BarChartDatum[] = [
+  { key: 'mon', label: 'Mon', value: 40 },
+  { key: 'tue', label: 'Tue', value: 120 },
+  { key: 'wed', label: 'Wed', value: 90 },
+]
+
+const SERIES: BarChartSeries[] = [
+  { key: 'paid', label: 'Paid', slot: 0 },
+  { key: 'organic', label: 'Organic', slot: 1 },
+]
+
+const GROUPED: BarChartDatum[] = [
+  { key: 'q1', label: 'Q1', values: [10, 20] },
+  { key: 'q2', label: 'Q2', values: [30, 5] },
+]
+
+/** Every drawn mark. Marks are aria-hidden; the hit layer carries the names. */
+function marks(container: HTMLElement): HTMLElement[] {
+  return Array.from(
+    container.querySelectorAll<HTMLElement>('[aria-hidden="true"]'),
+  ).filter((el) => el.style.background !== '' && el.style.borderRadius !== '')
+}
+
+function fills(container: HTMLElement): string[] {
+  return marks(container).map((el) => el.style.background)
+}
+
+/**
+ * Only the drawn BARS — both axes sized in percent. `marks` also matches the
+ * legend and readout swatches, which are token-sized; filtering on the unit
+ * is what separates a bar from a swatch without depending on colour.
+ */
+function bars(container: HTMLElement): HTMLElement[] {
+  return marks(container).filter(
+    (el) => el.style.width.endsWith('%') && el.style.height.endsWith('%'),
+  )
+}
+
+/**
+ * jsdom reports every box as 0x0. This gives the layout real numbers so the
+ * MEASURED paths — the density floor and the readout's clamp bounds — can be
+ * exercised. Returns the undo.
+ */
+function stubLayout(width: number, height: number): () => void {
+  const proto = HTMLElement.prototype
+  const w = Object.getOwnPropertyDescriptor(proto, 'offsetWidth')
+  const h = Object.getOwnPropertyDescriptor(proto, 'offsetHeight')
+  Object.defineProperty(proto, 'offsetWidth', { configurable: true, get: () => width })
+  Object.defineProperty(proto, 'offsetHeight', { configurable: true, get: () => height })
+  return () => {
+    if (w !== undefined) Object.defineProperty(proto, 'offsetWidth', w)
+    if (h !== undefined) Object.defineProperty(proto, 'offsetHeight', h)
+  }
+}
+
+describe('BarChart — the monochrome contract (ADR-146 D7)', () => {
+  it('paints exactly one bar at full accent and the rest at the tint', () => {
+    const { container } = render(<BarChart title="Volume" data={DATA} />)
+    const painted = fills(container).filter((f) => f.includes('--accent'))
+    const full = painted.filter((f) => f === 'rgb(var(--accent))')
+    const tint = painted.filter((f) => f === 'rgb(var(--accent) / 0.14)')
+
+    expect(full).toHaveLength(1)
+    expect(tint).toHaveLength(DATA.length - 1)
+  })
+
+  it('never reaches for a series token when there is one series', () => {
+    const { container } = render(<BarChart data={DATA} />)
+    for (const fill of fills(container)) {
+      expect(fill).not.toMatch(/--series-/)
+    }
+  })
+
+  it('emphasizes the peak by default, not the first or last bar', () => {
+    const { container } = render(<BarChart data={DATA} />)
+    const index = fills(container).indexOf('rgb(var(--accent))')
+    // Tue (120) is the peak, and it is neither the first nor the last bar —
+    // so an off-by-one in the peak search cannot pass this.
+    expect(index).toBe(1)
+  })
+
+  it('lets selectedKey override the peak', () => {
+    const { container } = render(<BarChart data={DATA} selectedKey="wed" />)
+    expect(fills(container).indexOf('rgb(var(--accent))')).toBe(2)
+  })
+
+  it('emphasizes nothing when selectedKey matches nothing', () => {
+    // Falling back to the peak would make a failed lookup invisible.
+    const { container } = render(<BarChart data={DATA} selectedKey="nope" />)
+    expect(fills(container).filter((f) => f === 'rgb(var(--accent))')).toEqual([])
+  })
+
+  it('emphasizes nothing when asked for none', () => {
+    const { container } = render(<BarChart data={DATA} emphasis="none" />)
+    expect(fills(container).filter((f) => f === 'rgb(var(--accent))')).toEqual([])
+  })
+})
+
+describe('BarChart — series colour follows the entity, not the rank (D7)', () => {
+  it('colours a grouped chart from the frozen series lookup', () => {
+    const { container } = render(
+      <BarChart data={GROUPED} series={SERIES} title="Channels" />,
+    )
+    const painted = fills(container).filter((f) => f.includes('--series-'))
+    expect(painted).toContain('rgb(var(--series-1))')
+    expect(painted).toContain('rgb(var(--series-2))')
+    // Never a constructed name (D8): the lookup is a frozen literal array,
+    // so nothing can produce `--series-undefined` or `--series-9`.
+    for (const fill of painted) {
+      expect(fill).toMatch(/^rgb\(var\(--series-[1-8]\)\)$/)
+    }
+  })
+
+  it('keeps a series on its own hue when an earlier series is filtered out', () => {
+    const survivor = SERIES[1]!
+    const { container } = render(
+      <BarChart
+        data={[{ key: 'q1', label: 'Q1', values: [20] }]}
+        series={[survivor]}
+      />,
+    )
+    // Organic is slot 1, so it stays --series-2 even though it is now the
+    // only (and therefore first) series in the array.
+    expect(fills(container)).toContain('rgb(var(--series-2))')
+  })
+
+  it('renders a legend for two series and none for one', () => {
+    const { rerender } = render(<BarChart data={GROUPED} series={SERIES} />)
+    expect(screen.getByRole('list', { name: /series/i })).toBeInTheDocument()
+
+    rerender(<BarChart data={DATA} />)
+    expect(screen.queryByRole('list', { name: /series/i })).not.toBeInTheDocument()
+  })
+})
+
+describe('BarChart — the degenerate inputs (acceptance criterion 8)', () => {
+  it('renders the empty state for no data', () => {
+    render(<BarChart data={[]} emptyMessage="Nothing in this range." />)
+    expect(screen.getByText('Nothing in this range.')).toBeInTheDocument()
+  })
+
+  it('renders a single bar as a legal chart', () => {
+    const { container } = render(
+      <BarChart data={[{ key: 'only', label: 'Only', value: 7 }]} />,
+    )
+    expect(fills(container).filter((f) => f.includes('--accent'))).toEqual([
+      'rgb(var(--accent))',
+    ])
+    expect(screen.getByRole('img', { name: 'Only: 7' })).toBeInTheDocument()
+  })
+
+  it('says so for an all-zero series instead of drawing invisible bars', () => {
+    const { container } = render(
+      <BarChart
+        data={[
+          { key: 'a', label: 'A', value: 0 },
+          { key: 'b', label: 'B', value: 0 },
+        ]}
+      />,
+    )
+    expect(screen.getByText(/every value in this range is zero/i)).toBeInTheDocument()
+    expect(fills(container).filter((f) => f.includes('--accent'))).toEqual([])
+  })
+
+  it('descends a negative bar from the baseline instead of clamping it', () => {
+    const { container } = render(
+      <BarChart
+        data={[
+          { key: 'up', label: 'Up', value: 100 },
+          { key: 'down', label: 'Down', value: -50 },
+        ]}
+      />,
+    )
+    const drawn = marks(container).filter((el) =>
+      el.style.background.includes('--accent'),
+    )
+    expect(drawn).toHaveLength(2)
+    // A clamped negative would be a zero-height bar sitting on the baseline.
+    // Both bars have real height, and they sit at different offsets.
+    const heights = drawn.map((el) => parseFloat(el.style.height))
+    const bottoms = drawn.map((el) => parseFloat(el.style.bottom))
+    expect(heights.every((h) => h > 0)).toBe(true)
+    expect(bottoms[0]).not.toBe(bottoms[1])
+    // The zero rule is drawn in the darker axis token, not the grid token.
+    const zeroRule = Array.from(
+      container.querySelectorAll<HTMLElement>('div'),
+    ).filter((el) => el.style.background === 'rgb(var(--chart-axis))')
+    expect(zeroRule.length).toBeGreaterThan(0)
+  })
+
+  it('leaves the axis token free of a second alpha', () => {
+    // `--chart-axis` / `--chart-grid` / `--chart-band` already carry alpha;
+    // a second one is invalid CSS the browser discards silently.
+    const { container } = render(
+      <BarChart data={[{ key: 'a', label: 'A', value: -5 }]} />,
+    )
+    for (const el of Array.from(container.querySelectorAll<HTMLElement>('div'))) {
+      expect(el.style.background).not.toMatch(/--chart-[a-z]+\)\s*\//)
+    }
+  })
+
+  it('absorbs a non-finite value without voiding the bars around it', () => {
+    const { container } = render(
+      <BarChart
+        data={[
+          { key: 'a', label: 'A', value: Number.NaN },
+          { key: 'b', label: 'B', value: 10 },
+        ]}
+      />,
+    )
+    for (const el of marks(container)) {
+      expect(el.style.height).not.toMatch(/NaN/)
+      expect(el.style.bottom).not.toMatch(/NaN/)
+    }
+    // NaN is ABSENT, not zero: it draws nothing, and the measured bar next
+    // to it still draws. (See the Truthful block below for the rest.)
+    expect(bars(container)).toHaveLength(1)
+    expect(screen.getByRole('img', { name: 'A: —' })).toBeInTheDocument()
+  })
+
+  it('refuses to draw mush once a measurement says the bars are illegible', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const restore = stubLayout(480, 150)
+    try {
+      const many: BarChartDatum[] = Array.from({ length: 400 }, (_, i) => ({
+        key: `d${i}`,
+        label: `${i}`,
+        value: i + 1,
+      }))
+      const { container } = render(<BarChart data={many} minBarSize={4} />)
+      // 480px over 400 bars is ~1.2px each — mush. We say so, and the
+      // frame's table toggle is still the way out.
+      expect(screen.getByText(/too many categories to chart legibly \(400\)/i))
+        .toBeInTheDocument()
+      expect(fills(container).filter((f) => f.includes('--accent'))).toEqual([])
+      expect(warn).toHaveBeenCalledTimes(1)
+      expect(screen.getByRole('button', { name: 'Table view' })).toBeInTheDocument()
+    } finally {
+      restore()
+      warn.mockRestore()
+    }
+  })
+
+  it('draws normally when the same measurement leaves room', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const restore = stubLayout(480, 150)
+    try {
+      const { container } = render(<BarChart data={DATA} minBarSize={4} />)
+      // The guard is a MEASURED floor, not a count heuristic — three bars in
+      // 480px clear it comfortably. Remove the comparison and this goes red.
+      expect(screen.queryByText(/too many categories/i)).not.toBeInTheDocument()
+      expect(fills(container).filter((f) => f.includes('--accent'))).toHaveLength(3)
+      expect(warn).not.toHaveBeenCalled()
+    } finally {
+      restore()
+      warn.mockRestore()
+    }
+  })
+})
+
+describe('BarChart — interaction and accessibility (D9, D10)', () => {
+  it('gives every band a hit target that names its datum', () => {
+    render(<BarChart data={DATA} />)
+    expect(screen.getByRole('img', { name: 'Mon: 40' })).toBeInTheDocument()
+    expect(screen.getByRole('img', { name: 'Tue: 120' })).toBeInTheDocument()
+    expect(screen.getByRole('img', { name: 'Wed: 90' })).toBeInTheDocument()
+  })
+
+  it('names every series in a grouped hit target', () => {
+    render(<BarChart data={GROUPED} series={SERIES} />)
+    expect(
+      screen.getByRole('img', { name: 'Q1: Paid 10, Organic 20' }),
+    ).toBeInTheDocument()
+  })
+
+  it('is a button only when it actually does something', async () => {
+    const onSelect = vi.fn()
+    const { rerender } = render(<BarChart data={DATA} />)
+    expect(screen.queryAllByRole('button', { name: /Mon/ })).toEqual([])
+
+    rerender(<BarChart data={DATA} onSelect={onSelect} />)
+    await userEvent.click(screen.getByRole('button', { name: 'Mon: 40' }))
+    expect(onSelect).toHaveBeenCalledWith('mon')
+  })
+
+  it('marks the selected band pressed', () => {
+    render(<BarChart data={DATA} onSelect={() => {}} selectedKey="tue" />)
+    expect(screen.getByRole('button', { name: 'Tue: 120' })).toHaveAttribute(
+      'aria-pressed',
+      'true',
+    )
+    expect(screen.getByRole('button', { name: 'Mon: 40' })).toHaveAttribute(
+      'aria-pressed',
+      'false',
+    )
+  })
+
+  it('reveals the readout on hover and hides it without unmounting', async () => {
+    render(<BarChart data={DATA} />)
+    const tooltip = screen.getByRole('tooltip', { hidden: true })
+    expect(tooltip).toHaveAttribute('aria-hidden', 'true')
+
+    await userEvent.hover(screen.getByRole('img', { name: 'Wed: 90' }))
+    expect(tooltip).toHaveAttribute('aria-hidden', 'false')
+    expect(within(tooltip).getByText('Wed')).toBeInTheDocument()
+    expect(within(tooltip).getByText('90')).toBeInTheDocument()
+
+    await userEvent.unhover(screen.getByRole('img', { name: 'Wed: 90' }))
+    expect(tooltip).toHaveAttribute('aria-hidden', 'true')
+    // Still mounted: re-showing must cost no measurement and no reflow.
+    expect(screen.getByRole('tooltip', { hidden: true })).toBe(tooltip)
+  })
+
+  it('reveals the readout on keyboard focus too', async () => {
+    render(<BarChart data={DATA} />)
+    // The frame's table toggle is the first tab stop; the bands follow it.
+    await userEvent.tab()
+    await userEvent.tab()
+    expect(screen.getByRole('img', { name: 'Mon: 40' })).toHaveFocus()
+    const tooltip = screen.getByRole('tooltip', { hidden: true })
+    expect(tooltip).toHaveAttribute('aria-hidden', 'false')
+    expect(within(tooltip).getByText('Mon')).toBeInTheDocument()
+  })
+
+  it('offers the table view as the accessible representation', async () => {
+    render(<BarChart title="Volume" data={DATA} valueLabel="Sessions" />)
+    await userEvent.click(screen.getByRole('button', { name: 'Table view' }))
+    const table = screen.getByRole('table')
+    expect(within(table).getByRole('columnheader', { name: 'Category' })).toBeInTheDocument()
+    expect(within(table).getByRole('columnheader', { name: 'Sessions' })).toBeInTheDocument()
+    expect(within(table).getByRole('rowheader', { name: 'Tue' })).toBeInTheDocument()
+    expect(within(table).getByRole('cell', { name: '120' })).toBeInTheDocument()
+  })
+
+  it('formats through the caller formatter everywhere it shows a number', async () => {
+    const format = (value: number) => `$${value}`
+    render(<BarChart data={DATA} formatValue={format} />)
+    expect(screen.getByRole('img', { name: 'Mon: $40' })).toBeInTheDocument()
+    await userEvent.click(screen.getByRole('button', { name: 'Table view' }))
+    expect(screen.getByRole('cell', { name: '$120' })).toBeInTheDocument()
+  })
+})
+
+describe('BarChart — orientation', () => {
+  it('draws its own vertical gridlines and category gutter when horizontal', () => {
+    const { container } = render(
+      <BarChart data={DATA} orientation="horizontal" title="Volume" />,
+    )
+    const gridlines = Array.from(
+      container.querySelectorAll<HTMLElement>('div'),
+    ).filter((el) => el.style.background === 'rgb(var(--chart-grid))')
+    // Vertical rules: a width, not a height.
+    expect(gridlines.length).toBeGreaterThan(0)
+    for (const line of gridlines) {
+      expect(line.style.width).toBe('1px')
+    }
+    // The category labels move into the chart's own gutter, because the
+    // frame's y-gutter is a VALUE axis. (`Mon` also appears in the mounted-
+    // but-hidden readout, so this asserts the gutter span specifically.)
+    const gutterLabels = Array.from(
+      container.querySelectorAll<HTMLElement>('span'),
+    ).filter((el) => el.style.transform === 'translateY(-50%)')
+    expect(gutterLabels.map((el) => el.textContent)).toEqual([
+      'Mon',
+      'Tue',
+      'Wed',
+    ])
+  })
+
+  it('lays bars along the value axis when horizontal', () => {
+    const { container } = render(
+      <BarChart data={DATA} orientation="horizontal" />,
+    )
+    const drawn = marks(container).filter((el) =>
+      el.style.background.includes('--accent'),
+    )
+    expect(drawn).toHaveLength(3)
+    for (const bar of drawn) {
+      expect(bar.style.width).not.toBe('')
+      expect(bar.style.height).toMatch(/%$/)
+    }
+  })
+})
+
+describe('BarChart — stacked mode', () => {
+  it('seams adjacent segments in the panel colour, and not the top one', () => {
+    const { container } = render(
+      <BarChart data={GROUPED} series={SERIES} mode="stacked" />,
+    )
+    const seamed = marks(container).filter(
+      (el) => el.style.borderTopColor !== '' || el.style.borderTop !== '',
+    )
+    // One seam per category — the lower of the two segments only.
+    expect(seamed).toHaveLength(GROUPED.length)
+    for (const el of seamed) {
+      expect(el.style.borderTop).toContain('rgb(var(--surface-card))')
+    }
+  })
+})
+
+describe('BarChart — review additions (reserved space, honesty, a11y noise)', () => {
+  it('keeps the value-axis structure when every value is zero', () => {
+    // The gutter and its gridlines are what stop the plot changing WIDTH
+    // between a range with data and one without (D9, reserved space). They
+    // stay, unlabelled — a single nice tick at zero would be centred at
+    // mid-height by the frame, which would draw a zero line that is not
+    // where zero is.
+    const zeros: BarChartDatum[] = [
+      { key: 'a', label: 'A', value: 0 },
+      { key: 'b', label: 'B', value: 0 },
+    ]
+    const { container } = render(<BarChart data={zeros} />)
+    const gridlines = Array.from(
+      container.querySelectorAll<HTMLElement>('div'),
+    ).filter((el) => el.style.background === 'rgb(var(--chart-grid))')
+    expect(gridlines.length).toBeGreaterThan(0)
+    // Structure, not numbers: no tick reading "0" anywhere in the gutter.
+    expect(screen.queryByText('0')).not.toBeInTheDocument()
+  })
+
+  it('drops the category labels when it has declined to draw the bars', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const restore = stubLayout(480, 150)
+    try {
+      const many: BarChartDatum[] = Array.from({ length: 300 }, (_, i) => ({
+        key: `d${i}`,
+        label: `L${i}`,
+        value: i + 1,
+      }))
+      render(<BarChart data={many} />)
+      // 300 crushed ellipses under a "too dense" message is the same mush
+      // the refusal exists to avoid.
+      expect(screen.queryByText('L299')).not.toBeInTheDocument()
+      expect(screen.queryByText('L0')).not.toBeInTheDocument()
+    } finally {
+      restore()
+      warn.mockRestore()
+    }
+  })
+
+  it('warns rather than silently clamping a negative in a stacked chart', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      render(
+        <BarChart
+          data={[{ key: 'q1', label: 'Q1', values: [10, -4] }]}
+          series={SERIES}
+          mode="stacked"
+        />,
+      )
+      expect(warn).toHaveBeenCalledTimes(1)
+      expect(String(warn.mock.calls[0]?.[0])).toMatch(/stacked chart cannot draw a negative/i)
+    } finally {
+      warn.mockRestore()
+    }
+  })
+
+  it('does not draw a negative in a grouped chart from the same data', () => {
+    // The clamp is a STACKED limitation, not a BarChart one: grouped mode
+    // draws the negative properly and must not warn.
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      const { container } = render(
+        <BarChart
+          data={[{ key: 'q1', label: 'Q1', values: [10, -4] }]}
+          series={SERIES}
+        />,
+      )
+      expect(warn).not.toHaveBeenCalled()
+      const drawn = bars(container).filter((el) =>
+        el.style.background.includes('--series-'),
+      )
+      expect(drawn).toHaveLength(2)
+      expect(drawn.every((el) => parseFloat(el.style.height) > 0)).toBe(true)
+    } finally {
+      warn.mockRestore()
+    }
+  })
+
+  it('announces a pressed state only when the caller models selection', () => {
+    const { rerender } = render(<BarChart data={DATA} onSelect={() => {}} />)
+    expect(screen.getByRole('button', { name: 'Mon: 40' })).not.toHaveAttribute(
+      'aria-pressed',
+    )
+
+    rerender(<BarChart data={DATA} onSelect={() => {}} selectedKey={null} />)
+    expect(screen.getByRole('button', { name: 'Mon: 40' })).toHaveAttribute(
+      'aria-pressed',
+      'false',
+    )
+  })
+
+  it('insets the horizontal category label off the bar region', () => {
+    // Padding on the gutter would be DEAD style: an absolutely-positioned
+    // child resolves its offsets against the ancestor's padding box, so the
+    // labels would sit flush against the bars.
+    const { container } = render(
+      <BarChart data={DATA} orientation="horizontal" />,
+    )
+    const gutterLabels = Array.from(
+      container.querySelectorAll<HTMLElement>('span'),
+    ).filter((el) => el.style.transform === 'translateY(-50%)')
+    expect(gutterLabels).toHaveLength(3)
+    for (const label of gutterLabels) {
+      expect(label.style.right).toBe('var(--space-2)')
+    }
+  })
+
+  it('never tweens with `all`, and never with a spring', () => {
+    const { container } = render(<BarChart data={DATA} />)
+    // `className` is an SVGAnimatedString on the frame's Lucide icons, so
+    // read the attribute rather than the property.
+    for (const el of Array.from(container.querySelectorAll('*'))) {
+      expect(el.getAttribute('class') ?? '').not.toMatch(/transition-all/)
+    }
+    for (const el of Array.from(container.querySelectorAll<HTMLElement>('div'))) {
+      expect(el.style.transitionTimingFunction).not.toMatch(/spring/)
+    }
+    const animated = bars(container)
+    expect(animated).toHaveLength(DATA.length)
+    for (const mark of animated) {
+      expect(mark.style.transitionTimingFunction).toBe('var(--ease-out)')
+      expect(mark.className).toMatch(/^.*motion-safe:transition-\[/)
+    }
+  })
+})
+
+describe('BarChart — an absent value is not a measured zero (Truthful)', () => {
+  const PARTIAL: BarChartDatum[] = [
+    { key: 'a', label: 'A', value: 10 },
+    // No `value` at all: this category was never measured. "0" is a
+    // different fact, and a chart that prints one for the other lies.
+    { key: 'b', label: 'B' },
+  ]
+
+  it('names an absent category with an em dash, not a zero', () => {
+    render(<BarChart title="Volume" data={PARTIAL} />)
+    expect(screen.getByRole('img', { name: 'B: —' })).toBeInTheDocument()
+    expect(screen.queryByRole('img', { name: 'B: 0' })).not.toBeInTheDocument()
+  })
+
+  it('draws no bar where there is no measurement', () => {
+    const { container } = render(<BarChart title="Volume" data={PARTIAL} />)
+    // A zero-length bar sitting on the baseline is indistinguishable from a
+    // measured zero, so there must be no mark at all.
+    expect(bars(container)).toHaveLength(1)
+  })
+
+  it('reads an em dash in the readout, never a zero', async () => {
+    render(<BarChart title="Volume" data={PARTIAL} />)
+    await userEvent.hover(screen.getByRole('img', { name: 'B: —' }))
+    const tooltip = screen.getByRole('tooltip', { hidden: true })
+    expect(within(tooltip).getByText('B')).toBeInTheDocument()
+    expect(within(tooltip).getByText('—')).toBeInTheDocument()
+    expect(within(tooltip).queryByText('0')).not.toBeInTheDocument()
+  })
+
+  it('writes an em dash in the table view', async () => {
+    render(<BarChart title="Volume" data={PARTIAL} />)
+    await userEvent.click(screen.getByRole('button', { name: 'Table view' }))
+    const table = screen.getByRole('table')
+    expect(within(table).getByRole('cell', { name: '—' })).toBeInTheDocument()
+    expect(within(table).queryByRole('cell', { name: '0' })).not.toBeInTheDocument()
+  })
+
+  it('never lets an absent value win the peak emphasis', () => {
+    const { container } = render(
+      <BarChart
+        data={[
+          { key: 'a', label: 'A', value: -5 },
+          { key: 'b', label: 'B' },
+          { key: 'c', label: 'C', value: -20 },
+        ]}
+      />,
+    )
+    // Read as zero, B is the largest number in the set and steals the accent
+    // for a bar that does not exist. The peak is the largest MEASURED value.
+    expect(bars(container).map((el) => el.style.background)).toEqual([
+      'rgb(var(--accent))',
+      'rgb(var(--accent) / 0.14)',
+    ])
+  })
+
+  it('says there is no data, not that every value is zero, when nothing was measured', () => {
+    render(
+      <BarChart
+        data={[
+          { key: 'a', label: 'A' },
+          { key: 'b', label: 'B' },
+        ]}
+      />,
+    )
+    expect(screen.queryByText(/every value in this range is zero/i)).not.toBeInTheDocument()
+    expect(screen.getByText('No data for this range.')).toBeInTheDocument()
+  })
+
+  it('keeps a missing grouped entry absent rather than reporting a zero', () => {
+    const { container } = render(
+      <BarChart data={[{ key: 'q1', label: 'Q1', values: [10] }]} series={SERIES} />,
+    )
+    expect(
+      screen.getByRole('img', { name: 'Q1: Paid 10, Organic —' }),
+    ).toBeInTheDocument()
+    // One segment drawn, not a second one of zero length.
+    expect(bars(container).filter((el) => el.style.background.includes('--series-')))
+      .toHaveLength(1)
+  })
+
+  it('skips an absent segment in a stack rather than seaming a zero onto it', () => {
+    const { container } = render(
+      <BarChart
+        data={[{ key: 'q1', label: 'Q1', values: [10] }]}
+        series={SERIES}
+        mode="stacked"
+      />,
+    )
+    const drawn = bars(container).filter((el) =>
+      el.style.background.includes('--series-'),
+    )
+    expect(drawn).toHaveLength(1)
+    // Nothing sits above the only segment, so it wears no seam.
+    expect(drawn[0]?.style.borderTop).toBe('')
+  })
+})
+
+describe('BarChart — what the all-zero message is allowed to claim', () => {
+  it('says every value is zero only when every value was measured', () => {
+    render(
+      <BarChart
+        data={[
+          { key: 'a', label: 'A', value: 0 },
+          { key: 'b', label: 'B', value: 0 },
+        ]}
+      />,
+    )
+    expect(screen.getByText('Every value in this range is zero.')).toBeInTheDocument()
+  })
+
+  it('narrows the claim to the measured values when one is absent', () => {
+    render(
+      <BarChart
+        data={[
+          { key: 'a', label: 'A', value: 0 },
+          { key: 'b', label: 'B' },
+        ]}
+      />,
+    )
+    // B was never measured, so "every value is zero" would over-claim.
+    expect(
+      screen.getByText('Every value measured in this range is zero.'),
+    ).toBeInTheDocument()
+    expect(screen.getByRole('img', { name: 'B: —' })).toBeInTheDocument()
+  })
+})
+
+describe('BarChart — an in-plot message is not tangled in the gridlines', () => {
+  /**
+   * MEASURED in a browser, not read out of the source. On the all-zero demo
+   * the message box spanned y 241-260 while a `rgba(0,0,0,0.08)` gridline
+   * 608px wide sat at y=250 — a rule running dead centre through "Every value
+   * in this range is zero." Both the message element and its parent computed
+   * to a transparent background.
+   *
+   * The all-zero and too-dense states deliberately KEEP the axis chrome (that
+   * is the point — live gridlines are what prove the chart is not broken), so
+   * the fix is not to hide the rules but to give the message an opaque
+   * knock-out on the panel surface.
+   *
+   * WHAT THIS TEST CAN AND CANNOT SEE. jsdom stores a `var()` value verbatim
+   * without computing it, so it can prove the backing is DECLARED and that
+   * the gridlines are still drawn behind it. It cannot prove the two colours
+   * actually match at computed-value time, and it cannot re-measure the
+   * overlap — that is the browser pass.
+   */
+
+  /** The opaque backing the plot notice must declare. */
+  const BACKING = 'rgb(var(--surface-card))'
+
+  it('backs the all-zero message opaquely while the gridlines stay live', () => {
+    const { container } = render(
+      <BarChart
+        data={[
+          { key: 'a', label: 'A', value: 0 },
+          { key: 'b', label: 'B', value: 0 },
+        ]}
+      />,
+    )
+    const message = screen.getByText('Every value in this range is zero.')
+    expect(message.style.background).toBe(BACKING)
+    // Padding and radius, so it reads as a label rather than a text run with
+    // a coloured box clamped to its glyphs.
+    expect(message.style.paddingBlock).toBe('var(--space-1)')
+    expect(message.style.paddingInline).toBe('var(--space-3)')
+    expect(message.style.borderRadius).toBe('var(--radius-sm)')
+
+    // The rules are still there — the notice masks them, it does not
+    // replace them. A fix that deleted the gridlines would pass a naive
+    // "no rule through the text" check and lose the axis.
+    const gridlines = Array.from(
+      container.querySelectorAll<HTMLElement>('div'),
+    ).filter((el) => el.style.background === 'rgb(var(--chart-grid))')
+    expect(gridlines.length).toBeGreaterThan(0)
+  })
+
+  it('backs the too-dense message the same way', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const restore = stubLayout(480, 150)
+    try {
+      const many: BarChartDatum[] = Array.from({ length: 300 }, (_, i) => ({
+        key: `d${i}`,
+        label: `L${i}`,
+        value: i + 1,
+      }))
+      render(<BarChart data={many} />)
+      const message = screen.getByText(/too many categories to chart legibly/i)
+      expect(message.style.background).toBe(BACKING)
+      expect(message.style.borderRadius).toBe('var(--radius-sm)')
+    } finally {
+      restore()
+      warn.mockRestore()
+    }
+  })
+
+  it('lets a pointer through the notice to the marks underneath', () => {
+    // `absolute inset-0` over the whole plot would otherwise swallow every
+    // hover the chart's own interaction layer depends on (D9).
+    render(
+      <BarChart
+        data={[
+          { key: 'a', label: 'A', value: 0 },
+          { key: 'b', label: 'B', value: 0 },
+        ]}
+      />,
+    )
+    const overlay = screen.getByText('Every value in this range is zero.')
+      .parentElement as HTMLElement
+    expect(overlay.className).toContain('pointer-events-none')
+  })
+})
+
+describe('BarChart category axis (the 2026-09-06 browser findings)', () => {
+  /**
+   * jsdom cannot tell whether a label LOOKS like it is under its bar. What
+   * it can assert is the number the browser lays it out from: the inline
+   * `left` percentage, which must be the band's own centre — the same
+   * `bandScale.center` the bar is drawn on. The visual result is a browser
+   * measurement and is recorded in the fix report.
+   */
+  function xLabelLefts(container: HTMLElement): { text: string; left: string }[] {
+    const rows = container.querySelectorAll('figure > div[aria-hidden="true"]')
+    const row = rows[rows.length - 1]
+    if (!(row instanceof HTMLElement)) throw new Error('no x-label row')
+    return Array.from(row.querySelectorAll('span')).map((span) => ({
+      text: span.textContent ?? '',
+      left: span.style.left,
+    }))
+  }
+
+  it('puts each category label at its BAND CENTRE, not on an even spread', () => {
+    // Three bands across the plot: centres at 1/6, 3/6 and 5/6. An even
+    // spread would have put them at 0, 1/2 and 1 — which is what
+    // `justify-between` did, and why "Paid search" sat 65px from its bar on
+    // the 3-category demo in Chromium at 1440.
+    const { container } = render(<BarChart data={DATA} title="Sessions" />)
+    const labels = xLabelLefts(container)
+    expect(labels.map((label) => label.text)).toEqual(['Mon', 'Tue', 'Wed'])
+    // Percentages, so epsilon rather than `toBe` (CLAUDE.md §7).
+    const pct = (value: string | undefined): number =>
+      Number((value ?? '').replace('%', ''))
+    expect(pct(labels[0]?.left)).toBeCloseTo((1 / 6) * 100, 6)
+    expect(pct(labels[1]?.left)).toBeCloseTo(50, 6)
+    expect(pct(labels[2]?.left)).toBeCloseTo((5 / 6) * 100, 6)
+  })
+
+  it('centres a single category rather than pinning it to the left edge', () => {
+    const { container } = render(
+      <BarChart data={[{ key: 'only', label: 'Only', value: 5 }]} title="One" />,
+    )
+    expect(xLabelLefts(container)[0]?.left).toBe('50%')
+  })
+})