@carto/ps-react-ui 5.1.0 → 6.0.0

package/src/widgets/category/category-ui.test.tsx

@@ -1,399 +1,928 @@
-import { describe, test, expect, beforeEach } from 'vitest'
-import { render, screen } from '@testing-library/react'
-import { ThemeProvider, createTheme } from '@mui/material/styles'
+import { describe, it, expect, vi } from 'vitest'
+import { fireEvent, render, screen, within } from '@testing-library/react'
 import { CategoryUI } from './category-ui'
-import { useWidgetStore } from '../stores/widget-store'
-import type { CategoryWidgetState } from './types'
-
-// Create a test theme with qualitative colors
-const testTheme = createTheme({
-  palette: {
-    primary: {
-      main: '#1976d2',
-    },
-    qualitative: {
-      bold: {
-        0: '#1f77b4',
-        1: '#ff7f0e',
-        2: '#2ca02c',
-        3: '#d62728',
-        4: '#9467bd',
-        5: '#8c564b',
-        6: '#e377c2',
-        7: '#7f7f7f',
-      },
-    },
-  },
-})
 
-// Helper function to render with theme
-function renderWithTheme(ui: React.ReactElement) {
-  return render(<ThemeProvider theme={testTheme}>{ui}</ThemeProvider>)
-}
+describe('<CategoryUI>', () => {
+  // ── Rendering basics ────────────────────────────────────────────────
+  describe('rendering', () => {
+    it('renders one row per item with name + value', () => {
+      render(
+        <CategoryUI
+          data={[
+            [
+              { name: 'A', value: 10 },
+              { name: 'B', value: 20 },
+            ],
+          ]}
+        />,
+      )
+      expect(screen.getByText('A')).toBeTruthy()
+      expect(screen.getByText('B')).toBeTruthy()
+      expect(screen.getByText('10')).toBeTruthy()
+      expect(screen.getByText('20')).toBeTruthy()
+      expect(screen.getAllByRole('button')).toHaveLength(2)
+    })
 
-describe('CategoryUI', () => {
-  beforeEach(() => {
-    useWidgetStore.getState().clearWidgets()
-  })
+    it('returns null when data is empty (no rows, no container)', () => {
+      const { container } = render(<CategoryUI data={[]} />)
+      expect(container.firstChild).toBeNull()
+    })
 
-  test('returns null when widget does not exist', () => {
-    const { container } = renderWithTheme(<CategoryUI id='non-existent' />)
-    expect(container.firstChild).toBeNull()
+    it('returns null when all series are empty', () => {
+      const { container } = render(<CategoryUI data={[[], [], []]} />)
+      expect(container.firstChild).toBeNull()
+    })
   })
 
-  test('returns null when data is empty', () => {
-    useWidgetStore.getState().setWidget<CategoryWidgetState>('test-category', {
-      type: 'category',
-      data: [[]],
+  // ── maxItems + "Other" overflow ────────────────────────────────────
+  describe('maxItems + Other row', () => {
+    const oneToTwelve = () =>
+      Array.from({ length: 12 }, (_, i) => ({
+        name: `n${i}`,
+        value: 12 - i,
+      }))
+
+    it('defaults to 20 → no Other row when data fits', () => {
+      render(<CategoryUI data={[oneToTwelve()]} />)
+      expect(screen.queryByText(/more/)).toBeNull()
+      expect(screen.getAllByRole('button')).toHaveLength(12)
     })
 
-    const { container } = renderWithTheme(<CategoryUI id='test-category' />)
-    expect(container.firstChild).toBeNull()
-  })
-
-  test('renders basic category data', () => {
-    useWidgetStore.getState().setWidget<CategoryWidgetState>('test-category', {
-      type: 'category',
-      data: [
-        [
-          { name: 'Category A', value: 100 },
-          { name: 'Category B', value: 50 },
-        ],
-      ],
+    it('default caps at 20 when data exceeds it → "Others <count>" footer', () => {
+      const twentyFive = Array.from({ length: 25 }, (_, i) => ({
+        name: `n${i}`,
+        value: 25 - i,
+      }))
+      render(<CategoryUI data={[twentyFive]} />)
+      expect(screen.getAllByRole('button')).toHaveLength(20)
+      expect(screen.getByText('Others')).toBeTruthy()
+      expect(screen.getByText('5')).toBeTruthy()
     })
 
-    renderWithTheme(<CategoryUI id='test-category' />)
+    it('maxItems=null → no cap, no scroll (canonical form)', () => {
+      // Explicit opt-out from both the default cap AND the searcher's
+      // scroll viewport. `null` is required because `undefined` resolves
+      // to the 20-row default-parameter value.
+      const twentyFive = Array.from({ length: 25 }, (_, i) => ({
+        name: `n${i}`,
+        value: 25 - i,
+      }))
+      const { container } = render(
+        <CategoryUI data={[twentyFive]} maxItems={null} />,
+      )
+      expect(screen.queryByText('Others')).toBeNull()
+      expect(screen.getAllByRole('button')).toHaveLength(25)
+      const root = container.firstChild as HTMLElement
+      const list = root.firstChild as HTMLElement
+      expect(list.style.maxHeight).toBe('')
+      expect(list.style.overflowY).toBe('')
+    })
 
-    expect(screen.getByText('Category A')).toBeTruthy()
-    expect(screen.getByText('Category B')).toBeTruthy()
-    expect(screen.getByText('100')).toBeTruthy()
-    expect(screen.getByText('50')).toBeTruthy()
-  })
+    it('maxItems=Infinity also yields no cap, no scroll (alias)', () => {
+      const twentyFive = Array.from({ length: 25 }, (_, i) => ({
+        name: `n${i}`,
+        value: 25 - i,
+      }))
+      render(
+        <CategoryUI data={[twentyFive]} maxItems={Number.POSITIVE_INFINITY} />,
+      )
+      expect(screen.queryByText('Others')).toBeNull()
+      expect(screen.getAllByRole('button')).toHaveLength(25)
+    })
 
-  test('auto-calculates max value from data when max prop not provided', () => {
-    useWidgetStore.getState().setWidget<CategoryWidgetState>('test-category', {
-      type: 'category',
-      data: [
-        [
-          { name: 'Category A', value: 100 },
-          { name: 'Category B', value: 150 },
-          { name: 'Category C', value: 75 },
-        ],
-      ],
+    it('slices to maxItems and shows "Others <count>" footer', () => {
+      render(<CategoryUI data={[oneToTwelve()]} maxItems={5} />)
+      expect(screen.getAllByRole('button')).toHaveLength(5)
+      expect(screen.getByText('Others')).toBeTruthy()
+      expect(screen.getByText('7')).toBeTruthy()
     })
 
-    renderWithTheme(<CategoryUI id='test-category' />)
+    it('onShowAll makes the Other row a button that fires the callback', () => {
+      const onShowAll = vi.fn()
+      render(
+        <CategoryUI
+          data={[oneToTwelve()]}
+          maxItems={5}
+          onShowAll={onShowAll}
+        />,
+      )
+      // 5 category rows + the now-interactive "Others" row = 6 buttons.
+      const buttons = screen.getAllByRole('button')
+      expect(buttons).toHaveLength(6)
+      fireEvent.click(screen.getByText('Others'))
+      expect(onShowAll).toHaveBeenCalledTimes(1)
+    })
 
-    // Verify all categories are rendered
-    expect(screen.getByText('Category A')).toBeTruthy()
-    expect(screen.getByText('Category B')).toBeTruthy()
-    expect(screen.getByText('Category C')).toBeTruthy()
-    expect(screen.getByText('100')).toBeTruthy()
-    expect(screen.getByText('150')).toBeTruthy()
-    expect(screen.getByText('75')).toBeTruthy()
-  })
+    it('maxItems=0 is the no-cap-with-scroll sentinel: every row renders inside a fixed scroll viewport', () => {
+      // `0` is the composer-driven "disable pagination" sentinel —
+      // used e.g. when the SearcherToggle is open so the search filter
+      // has the full dataset to chew through. The "Other" footer is
+      // suppressed because nothing is hidden, and the list locks to a
+      // scrollable viewport so the widget card height stays stable.
+      const { container } = render(
+        <CategoryUI data={[oneToTwelve()]} maxItems={0} />,
+      )
+      expect(screen.getAllByRole('button')).toHaveLength(12)
+      expect(screen.queryByText('Others')).toBeNull()
+      expect(screen.queryByText(/more/)).toBeNull()
+      // List has the scroll viewport inline style applied.
+      const root = container.firstChild as HTMLElement
+      const list = root.firstChild as HTMLElement
+      expect(list.style.maxHeight).not.toBe('')
+      expect(list.style.overflowY).toBe('auto')
+    })
 
-  test('uses custom max value when provided', () => {
-    useWidgetStore.getState().setWidget<CategoryWidgetState>('test-category', {
-      type: 'category',
-      data: [
-        [
-          { name: 'Category A', value: 100 },
-          { name: 'Category B', value: 150 },
-        ],
-      ],
-      max: 200,
+    // ── Natural-height measurement ────────────────────────────────
+    //
+    // Scroll mode (`maxItems === 0`) sizes its viewport from the
+    // list's `clientHeight` measured on the first render where the
+    // list was NOT in scroll mode (i.e., the capped view). jsdom's
+    // layout engine reports `clientHeight === 0`, so the tests stub
+    // it on `HTMLDivElement.prototype` for the renders they care
+    // about.
+    describe('scroll mode height (measure-once)', () => {
+      const stubClientHeight = (value: number) => {
+        Object.defineProperty(HTMLDivElement.prototype, 'clientHeight', {
+          configurable: true,
+          get: () => value,
+        })
+      }
+      const restoreClientHeight = () => {
+        // Delete the stub so other tests aren't affected.
+        delete (HTMLDivElement.prototype as { clientHeight?: unknown })
+          .clientHeight
+      }
+
+      it('locks scroll viewport to the capped view height after the user toggles into scroll mode', () => {
+        stubClientHeight(240)
+        try {
+          const { rerender, container } = render(
+            <CategoryUI data={[oneToTwelve()]} maxItems={5} />,
+          )
+          // First render: capped, no scroll lock. Effect measures 240.
+          const root = container.firstChild as HTMLElement
+          const list = root.firstChild as HTMLElement
+          expect(list.style.maxHeight).toBe('')
+          // Composer flips to scroll mode → viewport uses the measured
+          // 240px, NOT the hard-coded fallback.
+          rerender(<CategoryUI data={[oneToTwelve()]} maxItems={0} />)
+          expect(list.style.maxHeight).toBe('240px')
+          expect(list.style.overflowY).toBe('auto')
+        } finally {
+          restoreClientHeight()
+        }
+      })
+
+      it('freezes the lock anchor: subsequent re-measures while in scroll mode are ignored', () => {
+        stubClientHeight(180)
+        try {
+          const { rerender, container } = render(
+            <CategoryUI data={[oneToTwelve()]} maxItems={5} />,
+          )
+          const root = container.firstChild as HTMLElement
+          const list = root.firstChild as HTMLElement
+          rerender(<CategoryUI data={[oneToTwelve()]} maxItems={0} />)
+          expect(list.style.maxHeight).toBe('180px')
+          // Change the stub mid-flight. The lock must hold — measurement
+          // is one-shot, taken on the first non-scroll render.
+          stubClientHeight(999)
+          rerender(<CategoryUI data={[oneToTwelve()]} maxItems={0} />)
+          expect(list.style.maxHeight).toBe('180px')
+        } finally {
+          restoreClientHeight()
+        }
+      })
+
+      it('falls back to 8 × ROW_HEIGHT_PX[size] when mounted directly into scroll mode (no capped render to measure)', () => {
+        // No stub — clientHeight reads 0 in jsdom by default, so the
+        // effect's `if (h > 0)` guard skips the setState. The viewport
+        // must still have a sane size: 36 × 8 = 288px for small.
+        const { container } = render(
+          <CategoryUI data={[oneToTwelve()]} maxItems={0} />,
+        )
+        const root = container.firstChild as HTMLElement
+        const list = root.firstChild as HTMLElement
+        expect(list.style.maxHeight).toBe('288px')
+        expect(list.style.overflowY).toBe('auto')
+      })
+
+      it('uses the same fallback for multi-series widgets (no seriesCount multiplier)', () => {
+        // Regression: a 3-series widget mounted directly into scroll
+        // mode previously rendered at 3× the intended viewport (864px)
+        // because the fallback was multiplied by `seriesCount`. The
+        // fallback should be 288px regardless of series count.
+        const threeSeries = [oneToTwelve(), oneToTwelve(), oneToTwelve()]
+        const { container } = render(
+          <CategoryUI data={threeSeries} maxItems={0} />,
+        )
+        const root = container.firstChild as HTMLElement
+        const list = root.firstChild as HTMLElement
+        expect(list.style.maxHeight).toBe('288px')
+      })
     })
 
-    renderWithTheme(<CategoryUI id='test-category' />)
+    it('honors custom labels.other + labels.otherCount with {count} substitution', () => {
+      render(
+        <CategoryUI
+          data={[oneToTwelve()]}
+          maxItems={3}
+          labels={{
+            other: 'Others',
+            otherCount: '+{count} hidden',
+          }}
+        />,
+      )
+      expect(screen.getByText('Others')).toBeTruthy()
+      expect(screen.getByText('+9 hidden')).toBeTruthy()
+    })
 
-    // Verify categories are rendered with custom max
-    expect(screen.getByText('Category A')).toBeTruthy()
-    expect(screen.getByText('Category B')).toBeTruthy()
-    expect(screen.getByText('100')).toBeTruthy()
-    expect(screen.getByText('150')).toBeTruthy()
+    it('large maxItems = no Other row', () => {
+      render(<CategoryUI data={[oneToTwelve()]} maxItems={1_000} />)
+      expect(screen.queryByText(/more/)).toBeNull()
+      expect(screen.getAllByRole('button')).toHaveLength(12)
+    })
   })
 
-  test('handles max value of 0', () => {
-    useWidgetStore.getState().setWidget<CategoryWidgetState>('test-category', {
-      type: 'category',
-      data: [
-        [
-          { name: 'Category A', value: 100 },
-          { name: 'Category B', value: 50 },
-        ],
+  // ── Multi-series grouped rendering ─────────────────────────────────
+  describe('multi-series', () => {
+    const twoSeries = () => [
+      [
+        { name: 'A', value: 10 },
+        { name: 'B', value: 20 },
       ],
-      max: 0,
+      [
+        { name: 'A', value: 5 },
+        { name: 'B', value: 8 },
+      ],
+    ]
+
+    it('renders one row per unique name across series', () => {
+      render(<CategoryUI data={twoSeries()} />)
+      // 2 unique names → 2 row buttons (not 4 like a per-series layout would give).
+      expect(screen.getAllByRole('button')).toHaveLength(2)
+      expect(screen.getByText('A')).toBeTruthy()
+      expect(screen.getByText('B')).toBeTruthy()
     })
 
-    renderWithTheme(<CategoryUI id='test-category' />)
+    it('renders both values per row, formatted', () => {
+      render(<CategoryUI data={twoSeries()} formatter={(n) => `$${n}`} />)
+      const rowA = screen.getAllByRole('button')[0]!
+      expect(within(rowA).getByText('A')).toBeTruthy()
+      expect(within(rowA).getByText('$10')).toBeTruthy()
+      expect(within(rowA).getByText('$5')).toBeTruthy()
+    })
 
-    // Verify categories are rendered even with max=0
-    expect(screen.getByText('Category A')).toBeTruthy()
-    expect(screen.getByText('Category B')).toBeTruthy()
-    expect(screen.getByText('100')).toBeTruthy()
-    expect(screen.getByText('50')).toBeTruthy()
-  })
+    it('clicking a multi-row toggles by name with raw key', () => {
+      const onSelectionChange = vi.fn()
+      render(
+        <CategoryUI
+          data={twoSeries()}
+          selection={[]}
+          onSelectionChange={onSelectionChange}
+        />,
+      )
+      fireEvent.click(screen.getAllByRole('button')[1]!)
+      expect(onSelectionChange).toHaveBeenCalledWith(['B'])
+    })
 
-  test('handles max value less than actual data values', () => {
-    useWidgetStore.getState().setWidget<CategoryWidgetState>('test-category', {
-      type: 'category',
-      data: [
-        [
-          { name: 'Category A', value: 150 },
-          { name: 'Category B', value: 75 },
-        ],
-      ],
-      max: 100,
+    it('resolves a series colour given as a theme path before painting it', () => {
+      // The bars and the legend dot paint through inline `style`, which has no
+      // theme resolver: an unresolved `'primary.main'` is invalid CSS and the
+      // browser drops it, so the swatch comes out unpainted.
+      const { container } = render(
+        <CategoryUI
+          data={[[{ name: 'A', value: 1 }]]}
+          series={[{ name: 'S1', color: 'primary.main' }]}
+        />,
+      )
+      const painted = Array.from(container.querySelectorAll('div')).filter(
+        (d) => (d as HTMLElement).style.backgroundColor !== '',
+      )
+      expect(painted.length).toBeGreaterThan(0)
+      for (const el of painted) {
+        expect((el as HTMLElement).style.backgroundColor).not.toContain('.')
+      }
     })
 
-    renderWithTheme(<CategoryUI id='test-category' />)
+    it('falls back gracefully when data.length > series.length (extra series unlabeled)', () => {
+      render(<CategoryUI data={twoSeries()} series={[{ name: 'Only-One' }]} />)
+      // 2 rows still render (data.length = 2 is the truth).
+      expect(screen.getAllByRole('button')).toHaveLength(2)
+      // Legend has just one entry.
+      expect(screen.getByText('Only-One')).toBeTruthy()
+    })
 
-    // Verify categories are rendered when values exceed max
-    expect(screen.getByText('Category A')).toBeTruthy()
-    expect(screen.getByText('Category B')).toBeTruthy()
-    expect(screen.getByText('150')).toBeTruthy()
-    expect(screen.getByText('75')).toBeTruthy()
+    it('falls back gracefully when series.length > data.length (extras ignored, no legend overflow)', () => {
+      render(
+        <CategoryUI
+          data={[[{ name: 'A', value: 1 }]]}
+          series={[{ name: 'S1' }, { name: 'S2' }, { name: 'S3' }]}
+        />,
+      )
+      // data.length === 1 → single-series layout, no legend.
+      expect(screen.queryByText('S2')).toBeNull()
+    })
   })
 
-  test('uses custom max with multi-series data', () => {
-    useWidgetStore.getState().setWidget<CategoryWidgetState>('test-category', {
-      type: 'category',
-      data: [
-        [
-          { name: 'Product A', value: 80 },
-          { name: 'Product B', value: 60 },
-        ],
-        [
-          { name: 'Product A', value: 90 },
-          { name: 'Product B', value: 70 },
-        ],
-      ],
-      max: 100,
-      series: [{ name: 'Q1' }, { name: 'Q2' }],
+  // ── Legend ─────────────────────────────────────────────────────────
+  describe('legend', () => {
+    it('renders the legend when multi-series + series prop supplied', () => {
+      render(
+        <CategoryUI
+          data={[[{ name: 'A', value: 1 }], [{ name: 'A', value: 2 }]]}
+          series={[{ name: '2024' }, { name: '2025' }]}
+        />,
+      )
+      expect(screen.getByText('2024')).toBeTruthy()
+      expect(screen.getByText('2025')).toBeTruthy()
     })
 
-    renderWithTheme(<CategoryUI id='test-category' />)
+    it('does NOT render the legend for single-series even when series is given', () => {
+      render(
+        <CategoryUI
+          data={[[{ name: 'A', value: 1 }]]}
+          series={[{ name: 'OnlySeries' }]}
+        />,
+      )
+      expect(screen.queryByText('OnlySeries')).toBeNull()
+    })
 
-    // Multi-series should show legend
-    expect(screen.getByText('Q1')).toBeTruthy()
-    expect(screen.getByText('Q2')).toBeTruthy()
+    it('does NOT render the legend for multi-series when series is omitted', () => {
+      render(
+        <CategoryUI
+          data={[[{ name: 'A', value: 1 }], [{ name: 'A', value: 2 }]]}
+        />,
+      )
+      // No legend element should be in the DOM (no series names to show).
+      // The text "A" is still present from the row label.
+      expect(screen.getAllByText('A')).toHaveLength(1)
+    })
 
-    // Verify product names are displayed
-    expect(screen.getByText('Product A')).toBeTruthy()
-    expect(screen.getByText('Product B')).toBeTruthy()
-  })
+    it('clicking a legend item hides that series from the rows', () => {
+      render(
+        <CategoryUI
+          data={[[{ name: 'A', value: 10 }], [{ name: 'A', value: 5 }]]}
+          series={[{ name: '2024' }, { name: '2025' }]}
+        />,
+      )
+      expect(screen.getByText('10')).toBeTruthy()
+      expect(screen.getByText('5')).toBeTruthy()
+      fireEvent.click(screen.getByText('2025'))
+      expect(screen.queryByText('5')).toBeNull()
+      expect(screen.getByText('10')).toBeTruthy()
+    })
 
-  test('updates when max value changes', () => {
-    useWidgetStore.getState().setWidget<CategoryWidgetState>('test-category', {
-      type: 'category',
-      data: [[{ name: 'Category A', value: 100 }]],
-      max: 200,
+    it('renders no legend item for a series with no data behind it', () => {
+      render(
+        <CategoryUI
+          data={[[{ name: 'A', value: 10 }], [{ name: 'A', value: 5 }]]}
+          series={[{ name: '2024' }, { name: '2025' }, { name: 'Phantom' }]}
+        />,
+      )
+      expect(screen.getByText('2024')).toBeTruthy()
+      expect(screen.getByText('2025')).toBeTruthy()
+      expect(screen.queryByText('Phantom')).toBeNull()
+      expect(screen.getAllByRole('checkbox')).toHaveLength(2)
     })
 
-    renderWithTheme(<CategoryUI id='test-category' />)
+    it('hiding a real series still works when the caller supplied extra series metadata', () => {
+      // The phantom item used to be toggleable and counted against
+      // `seriesCount = data.length`: hiding it and then a real series hit
+      // `next.size >= seriesCount` and reset everything to visible, with no
+      // way out except un-toggling the phantom.
+      render(
+        <CategoryUI
+          data={[[{ name: 'A', value: 10 }], [{ name: 'A', value: 5 }]]}
+          series={[{ name: '2024' }, { name: '2025' }, { name: 'Phantom' }]}
+        />,
+      )
+      fireEvent.click(screen.getByText('2025'))
+      expect(screen.queryByText('5')).toBeNull()
+      expect(screen.getByText('10')).toBeTruthy()
+    })
 
-    expect(screen.getByText('Category A')).toBeTruthy()
-    expect(screen.getByText('100')).toBeTruthy()
+    it('keeps a hidden series hidden after data shrinks under a stable series list', () => {
+      // `hiddenSeries` is only reset when the series *names* change, and
+      // `series` is static caller metadata while `data` varies — so a stale
+      // index survives a shrink and still counts toward the reset guard.
+      const SERIES = [{ name: '2023' }, { name: '2024' }, { name: '2025' }]
+      const three = [
+        [{ name: 'A', value: 10 }],
+        [{ name: 'A', value: 20 }],
+        [{ name: 'A', value: 30 }],
+      ]
+      const two = [[{ name: 'A', value: 10 }], [{ name: 'A', value: 20 }]]
+
+      const { rerender } = render(<CategoryUI data={three} series={SERIES} />)
+      fireEvent.click(screen.getByText('2025'))
+      expect(screen.queryByText('30')).toBeNull()
+
+      rerender(<CategoryUI data={two} series={SERIES} />)
+      fireEvent.click(screen.getByText('2024'))
+
+      expect(screen.queryByText('20')).toBeNull()
+      expect(screen.getByText('10')).toBeTruthy()
+    })
 
-    // Update max value
-    useWidgetStore.getState().setWidget<CategoryWidgetState>('test-category', {
-      type: 'category',
-      data: [[{ name: 'Category A', value: 100 }]],
-      max: 100,
+    it('applies the hidden set as the chart sees it: a shrink never blanks, a regrow restores, a click matches the legend', () => {
+      // The stored set is never rewritten on a data change, so a shrink can
+      // leave every remaining index hidden. The read side has to apply the
+      // "never fully hidden" guard too, and a click has to start from what
+      // the user sees, not from the stored set.
+      const SERIES = [{ name: '2023' }, { name: '2024' }, { name: '2025' }]
+      const three = [
+        [{ name: 'A', value: 10 }],
+        [{ name: 'A', value: 20 }],
+        [{ name: 'A', value: 30 }],
+      ]
+      const two = [[{ name: 'A', value: 10 }], [{ name: 'A', value: 20 }]]
+
+      const { rerender } = render(<CategoryUI data={three} series={SERIES} />)
+      fireEvent.click(screen.getByText('2023'))
+      fireEvent.click(screen.getByText('2024'))
+      expect(screen.queryByText('10')).toBeNull()
+      expect(screen.queryByText('20')).toBeNull()
+      expect(screen.getByText('30')).toBeTruthy()
+
+      // Shrink with no click: both remaining indices are hidden, so the
+      // guard falls back to all visible instead of a blank chart.
+      rerender(<CategoryUI data={two} series={SERIES} />)
+      expect(screen.getByText('10')).toBeTruthy()
+      expect(screen.getByText('20')).toBeTruthy()
+
+      // Regrow with no click: the stored set survived, the hides come back.
+      rerender(<CategoryUI data={three} series={SERIES} />)
+      expect(screen.queryByText('10')).toBeNull()
+      expect(screen.queryByText('20')).toBeNull()
+      expect(screen.getByText('30')).toBeTruthy()
+
+      // Shrink again and click: the toggle starts from the effective (empty)
+      // set, so unchecking 2024 hides 2024 — not 2023 via the stored {0,1}.
+      rerender(<CategoryUI data={two} series={SERIES} />)
+      fireEvent.click(screen.getByText('2024'))
+      expect(screen.queryByText('20')).toBeNull()
+      expect(screen.getByText('10')).toBeTruthy()
     })
 
-    // Widget should still render after update
-    expect(screen.getByText('Category A')).toBeTruthy()
-    expect(screen.getByText('100')).toBeTruthy()
+    it('hiding the last visible series reverts to showing all (never leaves it blank)', () => {
+      render(
+        <CategoryUI
+          data={[[{ name: 'A', value: 10 }], [{ name: 'A', value: 5 }]]}
+          series={[{ name: '2024' }, { name: '2025' }]}
+        />,
+      )
+      fireEvent.click(screen.getByText('2025'))
+      expect(screen.queryByText('5')).toBeNull()
+      fireEvent.click(screen.getByText('2024'))
+      // Both would be hidden — guard reverts to showing every series instead.
+      expect(screen.getByText('10')).toBeTruthy()
+      expect(screen.getByText('5')).toBeTruthy()
+    })
   })
 
-  test('uses formatter when provided', () => {
-    useWidgetStore.getState().setWidget<CategoryWidgetState>('test-category', {
-      type: 'category',
-      data: [[{ name: 'Category A', value: 1234 }]],
-      formatter: (value: number) => `$${value}`,
+  // ── Selection visual ───────────────────────────────────────────────
+  describe('selection visual', () => {
+    it('marks selected rows aria-pressed=true', () => {
+      render(
+        <CategoryUI
+          data={[
+            [
+              { name: 'A', value: 10 },
+              { name: 'B', value: 20 },
+            ],
+          ]}
+          selection={['A']}
+        />,
+      )
+      const pressed = screen.getAllByRole('button', { pressed: true })
+      expect(pressed).toHaveLength(1)
+      expect(pressed[0]!.textContent).toContain('A')
     })
 
-    renderWithTheme(<CategoryUI id='test-category' />)
+    it('fires onSelectionChange with the toggled set on click', () => {
+      const onSelectionChange = vi.fn()
+      render(
+        <CategoryUI
+          data={[
+            [
+              { name: 'A', value: 10 },
+              { name: 'B', value: 20 },
+            ],
+          ]}
+          selection={[]}
+          onSelectionChange={onSelectionChange}
+        />,
+      )
+      fireEvent.click(screen.getByText('B'))
+      expect(onSelectionChange).toHaveBeenCalledWith(['B'])
+    })
 
-    expect(screen.getByText('$1234')).toBeTruthy()
+    it('removes a selected item on second click', () => {
+      const onSelectionChange = vi.fn()
+      render(
+        <CategoryUI
+          data={[
+            [
+              { name: 'A', value: 10 },
+              { name: 'B', value: 20 },
+            ],
+          ]}
+          selection={['A', 'B']}
+          onSelectionChange={onSelectionChange}
+        />,
+      )
+      fireEvent.click(screen.getByText('A'))
+      expect(onSelectionChange).toHaveBeenCalledWith(['B'])
+    })
+
+    it('toggles via keyboard Enter and Space', () => {
+      const onSelectionChange = vi.fn()
+      render(
+        <CategoryUI
+          data={[[{ name: 'A', value: 10 }]]}
+          selection={[]}
+          onSelectionChange={onSelectionChange}
+        />,
+      )
+      const row = screen.getByRole('button')
+      fireEvent.keyDown(row, { key: 'Enter' })
+      expect(onSelectionChange).toHaveBeenCalledWith(['A'])
+      onSelectionChange.mockClear()
+      fireEvent.keyDown(row, { key: ' ' })
+      expect(onSelectionChange).toHaveBeenCalledWith(['A'])
+    })
   })
 
-  test('uses formatter with custom max', () => {
-    useWidgetStore.getState().setWidget<CategoryWidgetState>('test-category', {
-      type: 'category',
-      data: [[{ name: 'Sales', value: 125000 }]],
-      max: 200000,
-      formatter: (value: number) =>
-        new Intl.NumberFormat('en-US', {
-          style: 'currency',
-          currency: 'USD',
-          maximumFractionDigits: 0,
-        }).format(value),
+  // ── Selection dim color (bar-fill-only signal) ─────────────────────
+  //
+  // When a selection exists, non-selected rows' bar fills swap to
+  // `theme.palette.action.disabled` — the ONLY visual difference
+  // between selected and non-selected rows. Text colors stay at full
+  // values; rows have no bg tint, no opacity rule.
+  //
+  // jsdom + MUI default light theme: `action.disabled` resolves to
+  // `rgba(0, 0, 0, 0.26)` — what the browser writes to
+  // `style.backgroundColor`.
+  describe('selection dim color', () => {
+    const DIM = 'rgba(0, 0, 0, 0.26)'
+
+    function getBarFill(row: HTMLElement): HTMLElement | null {
+      return row.querySelector('div[style*="width:"]')
+    }
+
+    it('non-selected rows render the bar fill in the theme dim color when a selection exists', () => {
+      render(
+        <CategoryUI
+          data={[
+            [
+              { name: 'A', value: 10, color: 'rgb(255, 0, 0)' },
+              { name: 'B', value: 20, color: 'rgb(0, 255, 0)' },
+            ],
+          ]}
+          selection={['A']}
+        />,
+      )
+      const rows = screen.getAllByRole('button')
+      const aRow = rows.find((r) => r.textContent?.includes('A'))!
+      const bRow = rows.find((r) => r.textContent?.includes('B'))!
+      // Selected: keeps its real color.
+      expect(getBarFill(aRow)!.style.backgroundColor).toBe('rgb(255, 0, 0)')
+      // Non-selected: swaps to the dim color.
+      expect(getBarFill(bRow)!.style.backgroundColor).toBe(DIM)
     })
 
-    renderWithTheme(<CategoryUI id='test-category' />)
+    it('without a selection, no row is dimmed (every bar keeps its real color)', () => {
+      render(
+        <CategoryUI
+          data={[
+            [
+              { name: 'A', value: 10, color: 'rgb(255, 0, 0)' },
+              { name: 'B', value: 20, color: 'rgb(0, 255, 0)' },
+            ],
+          ]}
+        />,
+      )
+      const rows = screen.getAllByRole('button')
+      for (const row of rows) {
+        expect(getBarFill(row)!.style.backgroundColor).not.toBe(DIM)
+      }
+    })
 
-    // Should show formatted value
-    expect(screen.getByText('$125,000')).toBeTruthy()
-    expect(screen.getByText('Sales')).toBeTruthy()
+    it('multi-series: every bar in a dimmed row gets the dim color', () => {
+      render(
+        <CategoryUI
+          data={[
+            [
+              { name: 'A', value: 10, color: 'rgb(255, 0, 0)' },
+              { name: 'B', value: 20, color: 'rgb(255, 0, 0)' },
+            ],
+            [
+              { name: 'A', value: 5, color: 'rgb(0, 0, 255)' },
+              { name: 'B', value: 7, color: 'rgb(0, 0, 255)' },
+            ],
+          ]}
+          selection={['A']}
+        />,
+      )
+      const rows = screen.getAllByRole('button')
+      const bRow = rows.find((r) => r.textContent?.includes('B'))!
+      const fills = bRow.querySelectorAll<HTMLElement>('div[style*="width:"]')
+      expect(fills.length).toBe(2)
+      fills.forEach((f) => {
+        expect(f.style.backgroundColor).toBe(DIM)
+      })
+    })
   })
 
-  test('max prop works with maxItems configuration', () => {
-    useWidgetStore.getState().setWidget<CategoryWidgetState>('test-category', {
-      type: 'category',
-      data: [
-        [
-          { name: 'Item 1', value: 80 },
-          { name: 'Item 2', value: 60 },
-          { name: 'Item 3', value: 40 },
-          { name: 'Item 4', value: 20 },
-        ],
-      ],
-      max: 100,
-      maxItems: 2,
+  // ── labelFormatter (selection-key integrity) ───────────────────────
+  describe('labelFormatter', () => {
+    it('transforms displayed names without changing selection keys', () => {
+      const onSelectionChange = vi.fn()
+      render(
+        <CategoryUI
+          data={[
+            [
+              { name: 'dog', value: 10 },
+              { name: 'cat', value: 20 },
+            ],
+          ]}
+          labelFormatter={(n) => String(n).toUpperCase()}
+          selection={[]}
+          onSelectionChange={onSelectionChange}
+        />,
+      )
+      // Display labels are upper-cased.
+      expect(screen.getByText('DOG')).toBeTruthy()
+      expect(screen.getByText('CAT')).toBeTruthy()
+      expect(screen.queryByText('dog')).toBeNull()
+      // Selection callback receives the RAW name.
+      fireEvent.click(screen.getByText('DOG'))
+      expect(onSelectionChange).toHaveBeenCalledWith(['dog'])
     })
 
-    renderWithTheme(<CategoryUI id='test-category' />)
+    it('formats names in multi-series rows too, with raw selection keys', () => {
+      const onSelectionChange = vi.fn()
+      render(
+        <CategoryUI
+          data={[[{ name: 'dog', value: 1 }], [{ name: 'dog', value: 2 }]]}
+          labelFormatter={(n) => `[${n}]`}
+          selection={[]}
+          onSelectionChange={onSelectionChange}
+        />,
+      )
+      expect(screen.getByText('[dog]')).toBeTruthy()
+      fireEvent.click(screen.getByText('[dog]'))
+      expect(onSelectionChange).toHaveBeenCalledWith(['dog'])
+    })
+  })
 
-    // Should show only first 2 items
-    expect(screen.getByText('Item 1')).toBeTruthy()
-    expect(screen.getByText('Item 2')).toBeTruthy()
+  // ── Palette + per-item / per-series color overrides ────────────────
+  describe('color palette', () => {
+    function getBarFill(row: HTMLElement): HTMLElement | null {
+      // The bar fill is the second <div> inside the bar track div.
+      return row.querySelector(
+        // The MUI Box renders as a div; the fill has inline style with width.
+        'div[style*="width:"]',
+      )
+    }
+
+    it('per-item color (data[s][r].color) wins over series + palette', () => {
+      render(
+        <CategoryUI
+          data={[[{ name: 'A', value: 10, color: 'rgb(255, 0, 0)' }]]}
+          series={[{ name: 'S', color: 'rgb(0, 255, 0)' }]}
+        />,
+      )
+      const row = screen.getByRole('button')
+      const fill = getBarFill(row)
+      expect(fill).toBeTruthy()
+      // jsdom resolves theme tokens but inline color literals come through.
+      expect(fill!.style.backgroundColor).toBe('rgb(255, 0, 0)')
+    })
 
-    // Should show values
-    expect(screen.getByText('80')).toBeTruthy()
-    expect(screen.getByText('60')).toBeTruthy()
+    it('series-level color (series[i].color) wins over palette', () => {
+      render(
+        <CategoryUI
+          data={[[{ name: 'A', value: 10 }]]}
+          series={[{ name: 'S', color: 'rgb(123, 45, 67)' }]}
+        />,
+      )
+      const fill = getBarFill(screen.getByRole('button'))
+      expect(fill!.style.backgroundColor).toBe('rgb(123, 45, 67)')
+    })
   })
 
-  describe('Overflow behavior', () => {
-    test('applies overflow auto when hiddenCount is 0 (no maxItems)', () => {
-      useWidgetStore
-        .getState()
-        .setWidget<CategoryWidgetState>('test-category', {
-          type: 'category',
-          data: [
-            [
-              { name: 'Item 1', value: 100 },
-              { name: 'Item 2', value: 50 },
-            ],
-          ],
-          // No maxItems set, so hiddenCount will be 0
-        })
-
-      const { container } = renderWithTheme(<CategoryUI id='test-category' />)
-      // The list Box has inline style for overflow
-      const listBox = container.querySelector<HTMLElement>(
-        '[style*="overflow"]',
-      )!
+  // ── maxOverride ────────────────────────────────────────────────────
+  describe('maxOverride', () => {
+    it('changes the bar width denominator (different markup)', () => {
+      const { rerender, container } = render(
+        <CategoryUI data={[[{ name: 'A', value: 100 }]]} />,
+      )
+      const before = container.innerHTML
+      rerender(
+        <CategoryUI data={[[{ name: 'A', value: 100 }]]} maxOverride={200} />,
+      )
+      expect(container.innerHTML).not.toBe(before)
+    })
+  })
 
-      expect(listBox).toBeTruthy()
-      expect(listBox.style.overflow).toBe('auto')
+  // ── formatter ──────────────────────────────────────────────────────
+  describe('formatter', () => {
+    it('uses formatter for the value display', () => {
+      render(
+        <CategoryUI
+          data={[[{ name: 'A', value: 1234 }]]}
+          formatter={(n) => n.toLocaleString('en-US')}
+        />,
+      )
+      expect(screen.getByText('1,234')).toBeTruthy()
     })
+  })
 
-    test('applies overflow hidden when hiddenCount is greater than 0', () => {
-      useWidgetStore
-        .getState()
-        .setWidget<CategoryWidgetState>('test-category', {
-          type: 'category',
-          data: [
+  // ── Size variant ───────────────────────────────────────────────────
+  describe('size variant', () => {
+    const TWO_SERIES = [
+      [
+        { name: 'A', value: 10 },
+        { name: 'B', value: 20 },
+      ],
+      [
+        { name: 'A', value: 5 },
+        { name: 'B', value: 15 },
+      ],
+    ]
+
+    it('defaults to size="small" — every bar carries data-size="small"', () => {
+      const { container } = render(
+        <CategoryUI
+          data={[
             [
-              { name: 'Item 1', value: 100 },
-              { name: 'Item 2', value: 80 },
-              { name: 'Item 3', value: 60 },
-              { name: 'Item 4', value: 40 },
+              { name: 'A', value: 10 },
+              { name: 'B', value: 20 },
             ],
-          ],
-          maxItems: 2, // This creates hiddenCount = 2
-        })
-
-      const { container } = renderWithTheme(<CategoryUI id='test-category' />)
-      // The list Box has inline style for overflow
-      const listBox = container.querySelector<HTMLElement>(
-        '[style*="overflow"]',
-      )!
-
-      expect(listBox).toBeTruthy()
-      expect(listBox.style.overflow).toBe('hidden')
+          ]}
+        />,
+      )
+      const tracks = container.querySelectorAll('[data-size]')
+      expect(tracks.length).toBe(2)
+      tracks.forEach((t) => {
+        expect(t.getAttribute('data-size')).toBe('small')
+      })
     })
 
-    test('maintains overflow auto when maxItems equals data length', () => {
-      useWidgetStore
-        .getState()
-        .setWidget<CategoryWidgetState>('test-category', {
-          type: 'category',
-          data: [
+    it('propagates size="medium" to every bar (single-series)', () => {
+      const { container } = render(
+        <CategoryUI
+          data={[
             [
-              { name: 'Item 1', value: 100 },
-              { name: 'Item 2', value: 50 },
+              { name: 'A', value: 10 },
+              { name: 'B', value: 20 },
             ],
-          ],
-          maxItems: 2, // Same as data length, hiddenCount = 0
-        })
+          ]}
+          size='medium'
+        />,
+      )
+      const tracks = container.querySelectorAll('[data-size]')
+      expect(tracks.length).toBe(2)
+      tracks.forEach((t) => {
+        expect(t.getAttribute('data-size')).toBe('medium')
+      })
+    })
 
-      const { container } = renderWithTheme(<CategoryUI id='test-category' />)
-      // The list Box has inline style for overflow
-      const listBox = container.querySelector<HTMLElement>(
-        '[style*="overflow"]',
-      )!
+    it('propagates size="medium" to every bar (multi-series — N bars per row)', () => {
+      const { container } = render(
+        <CategoryUI data={TWO_SERIES} size='medium' />,
+      )
+      // 2 rows × 2 series = 4 bars
+      const tracks = container.querySelectorAll('[data-size]')
+      expect(tracks.length).toBe(4)
+      tracks.forEach((t) => {
+        expect(t.getAttribute('data-size')).toBe('medium')
+      })
+    })
+  })
 
-      expect(listBox).toBeTruthy()
-      expect(listBox.style.overflow).toBe('auto')
+  // ── Stacked mode ────────────────────────────────────────────────────
+  describe('stacked', () => {
+    const TWO_SERIES = [
+      [
+        { name: 'A', value: 45 },
+        { name: 'B', value: 30 },
+      ],
+      [
+        { name: 'A', value: 32 },
+        { name: 'B', value: 18 },
+      ],
+    ]
+
+    it('multi-series + stacked → one stacked row per group with one bar track per row', () => {
+      const { container } = render(
+        <CategoryUI
+          data={TWO_SERIES}
+          series={[{ name: 'Women' }, { name: 'Men' }]}
+          stacked
+        />,
+      )
+      // 2 unique names → 2 stacked rows → 2 bar tracks (NOT 4 like CategoryRowMulti).
+      const tracks = container.querySelectorAll('[data-size]')
+      expect(tracks.length).toBe(2)
+      // Each track has 2 segments (data-bar-fill) for the two non-zero series.
+      const fills = container.querySelectorAll('[data-bar-fill="true"]')
+      expect(fills.length).toBe(4)
     })
 
-    test('applies overflow auto when maxItems exceeds data length', () => {
-      useWidgetStore
-        .getState()
-        .setWidget<CategoryWidgetState>('test-category', {
-          type: 'category',
-          data: [
-            [
-              { name: 'Item 1', value: 100 },
-              { name: 'Item 2', value: 50 },
-            ],
-          ],
-          maxItems: 5, // More than data length, hiddenCount = 0
-        })
+    it('renders the formatted total in the header and the breakdown line under each row', () => {
+      render(
+        <CategoryUI
+          data={TWO_SERIES}
+          series={[{ name: 'Women' }, { name: 'Men' }]}
+          stacked
+          formatter={(n) => `${n}K`}
+        />,
+      )
+      // Totals: A=45+32=77, B=30+18=48
+      expect(screen.getByText('77K')).toBeTruthy()
+      expect(screen.getByText('48K')).toBeTruthy()
+      // Breakdown labels per row.
+      expect(screen.getByText('Women: 45K')).toBeTruthy()
+      expect(screen.getByText('Men: 32K')).toBeTruthy()
+      expect(screen.getByText('Women: 30K')).toBeTruthy()
+      expect(screen.getByText('Men: 18K')).toBeTruthy()
+    })
 
-      const { container } = renderWithTheme(<CategoryUI id='test-category' />)
-      // The list Box has inline style for overflow
-      const listBox = container.querySelector<HTMLElement>(
-        '[style*="overflow"]',
-      )!
+    it('falls back to "Series N" in the breakdown when series prop is omitted', () => {
+      render(<CategoryUI data={TWO_SERIES} stacked formatter={(n) => `${n}`} />)
+      expect(screen.getByText('Series 1: 45')).toBeTruthy()
+      expect(screen.getByText('Series 2: 32')).toBeTruthy()
+    })
 
-      expect(listBox).toBeTruthy()
-      expect(listBox.style.overflow).toBe('auto')
+    it('numbers the "Series N" fallback by ORIGINAL series index, not by visible position, after hiding an earlier series via the legend', () => {
+      // 3 data series; series[2] is unnamed (metadata array shorter than
+      // data — a supported "gap" per this prop's own doc). Hiding series 0
+      // ("Women") via the legend leaves series 1 ("Men") and 2 (unnamed)
+      // visible — series 2's fallback must still read "Series 3" (its
+      // ORIGINAL index), not "Series 2" (its now-first visible position).
+      const THREE_SERIES = [
+        [{ name: 'A', value: 45 }],
+        [{ name: 'A', value: 32 }],
+        [{ name: 'A', value: 12 }],
+      ]
+      render(
+        <CategoryUI
+          data={THREE_SERIES}
+          series={[{ name: 'Women' }, { name: 'Men' }]}
+          stacked
+          formatter={(n) => `${n}`}
+        />,
+      )
+      const checkbox = screen.getByRole('checkbox', { name: 'Women' })
+      fireEvent.click(checkbox)
+      expect(screen.queryByText(/Women:/)).toBeNull()
+      expect(screen.getByText('Men: 32')).toBeTruthy()
+      expect(screen.getByText('Series 3: 12')).toBeTruthy()
     })
 
-    test('works correctly with multi-series data', () => {
-      useWidgetStore
-        .getState()
-        .setWidget<CategoryWidgetState>('test-category', {
-          type: 'category',
-          data: [
-            [
-              { name: 'Product A', value: 100 },
-              { name: 'Product B', value: 80 },
-              { name: 'Product C', value: 60 },
-            ],
-            [
-              { name: 'Product A', value: 90 },
-              { name: 'Product B', value: 70 },
-              { name: 'Product C', value: 50 },
-            ],
-          ],
-          series: [{ name: 'Q1' }, { name: 'Q2' }],
-          maxItems: 2, // hiddenCount = 1
-        })
+    it('stacked is a no-op for single-series data (still renders CategoryRowSingle)', () => {
+      const { container } = render(
+        <CategoryUI data={[[{ name: 'A', value: 10 }]]} stacked />,
+      )
+      // Single-series row has no breakdown text — assert by the lack of
+      // "Series 1: ..." pattern (which would appear in stacked rendering).
+      expect(screen.queryByText(/Series 1:/)).toBeNull()
+      // 1 bar track for the one row.
+      expect(container.querySelectorAll('[data-size]').length).toBe(1)
+    })
 
-      const { container } = renderWithTheme(<CategoryUI id='test-category' />)
-      // The list Box has inline style for overflow
-      const listBox = container.querySelector<HTMLElement>(
-        '[style*="overflow"]',
-      )!
+    it('clicking a stacked row toggles by raw name', () => {
+      const onSelectionChange = vi.fn()
+      render(
+        <CategoryUI
+          data={TWO_SERIES}
+          series={[{ name: 'Women' }, { name: 'Men' }]}
+          stacked
+          selection={[]}
+          onSelectionChange={onSelectionChange}
+        />,
+      )
+      fireEvent.click(screen.getAllByRole('button')[1]!)
+      expect(onSelectionChange).toHaveBeenCalledWith(['B'])
+    })
 
-      expect(listBox).toBeTruthy()
-      expect(listBox.style.overflow).toBe('hidden')
+    it('dim color applies to every segment of non-selected rows when a selection exists', () => {
+      const DIM = 'rgba(0, 0, 0, 0.26)'
+      render(
+        <CategoryUI
+          data={TWO_SERIES}
+          series={[{ name: 'Women' }, { name: 'Men' }]}
+          stacked
+          selection={['A']}
+        />,
+      )
+      const rows = screen.getAllByRole('button')
+      const bRow = rows.find((r) => r.textContent?.includes('B'))!
+      const fills = bRow.querySelectorAll<HTMLElement>('[data-bar-fill="true"]')
+      expect(fills.length).toBe(2)
+      fills.forEach((f) => expect(f.style.backgroundColor).toBe(DIM))
     })
   })
 })