@carto/ps-react-ui 5.0.0-widgets.8 → 5.0.0

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

@@ -0,0 +1,479 @@
+import { useCallback, useMemo, useRef, useState } from 'react'
+import { Box, useTheme } from '@mui/material'
+import { CategoryRowSingle } from './components/category-row-single'
+import { CategoryRowMulti } from './components/category-row-multi'
+import { CategoryRowStacked } from './components/category-row-stacked'
+import { CategoryRowOther } from './components/category-row-other'
+import { CategoryLegend } from './components/category-legend'
+import type {
+  CategoryKey,
+  CategoryLabels,
+  CategorySeriesConfig,
+  CategorySize,
+  CategoryWidgetData,
+} from './types'
+import { styles } from './style'
+
+const DEFAULT_MAX_ITEMS = 20
+
+// Fallback viewport height used in scroll mode ONLY when no natural
+// measurement is available yet — i.e., the consumer mounts directly into
+// `maxItems === 0` (e.g., SearcherToggle pre-enabled), so the list has
+// never rendered in capped form for us to measure.
+//
+//   small: label(~20) + gap(4) + bar(4) + list-gap(8) ≈ 36
+//   medium: label(~20) + gap(4) + bar(12) + list-gap(8) ≈ 44
+const ROW_HEIGHT_PX: Record<CategorySize, number> = { small: 36, medium: 44 }
+const SCROLL_VIEWPORT_FALLBACK_ROWS = 8
+
+export interface CategoryUIProps {
+  data: CategoryWidgetData
+  /** Currently-selected category names (destination-owned). */
+  selection?: readonly CategoryKey[]
+  /** Fires with the next selection set when a row is clicked. */
+  onSelectionChange?: (next: readonly CategoryKey[]) => void
+  /** Number formatter applied to each row's value. */
+  formatter?: (value: number) => string
+  /**
+   * Display-only transform for category names. Selection callbacks always
+   * receive the raw `item.name` regardless of this formatter.
+   */
+  labelFormatter?: (value: string | number) => string | number
+  /**
+   * Per-series metadata. Enables the legend (for multi-series) and
+   * overrides palette colors per series index. Length need not match
+   * `data.length`; mismatches degrade gracefully (extras ignored, gaps
+   * fall back to palette).
+   */
+  series?: readonly CategorySeriesConfig[]
+  /**
+   * Caps the number of visible category rows.
+   *
+   * - `undefined` (omitted) — caps at {@link DEFAULT_MAX_ITEMS} (20).
+   *   Surplus rows fold into a single "Others <count>" footer row.
+   *   `undefined` cannot mean "no cap" because it's consumed by the
+   *   default-parameter syntax — pass `null` instead.
+   * - positive finite N — same as the default but with a custom cap.
+   * - `0` — **no cap WITH scroll**: every row renders inside a
+   *   fixed-height viewport that scrolls internally. The viewport's
+   *   max-height is the list's natural `clientHeight` measured on the
+   *   first render where the list was NOT in scroll mode (i.e., the
+   *   capped view) — frozen for the component's lifetime. If the
+   *   consumer mounts directly into scroll mode and we never see a
+   *   capped render, the viewport falls back to `8 × ROW_HEIGHT_PX`.
+   *   Composers flip into this mode while the user is searching
+   *   (`maxItems = searcherOpen ? 0 : userMaxItems`) so the widget
+   *   card height stays stable.
+   * - `null` / `Infinity` / negative — **no cap, no scroll**: render
+   *   every row; the list grows with content. Matches v1's "undefined"
+   *   behavior. Use `null` as the canonical explicit form.
+   */
+  maxItems?: number | null
+  /** Labels for the "Other" overflow row. `{count}` placeholder is replaced. */
+  labels?: CategoryLabels
+  /**
+   * When provided, the "Other" overflow row becomes a button — clicking it
+   * fires `onShowAll`, which a composer typically wires to expand the widget
+   * (drop the row cap) so every category becomes reachable. When omitted the
+   * overflow row stays a static summary.
+   */
+  onShowAll?: () => void
+  /** Manual override for the bar-width denominator. */
+  maxOverride?: number
+  /**
+   * Visual density of the bar primitive. `'small'` (default) keeps the
+   * historical 4px-tall pill; `'medium'` switches to a 12px-tall track
+   * with a 2px corner radius. Only the bar track + fill change.
+   */
+  size?: CategorySize
+  /**
+   * Multi-series stacked mode. When `true` and `data.length > 1`, each
+   * category renders as a single segmented bar (one segment per series)
+   * with a `formatter(sum)` total in the header and a per-series
+   * breakdown line below. Composers typically thread this from
+   * `useTransformEnabled(id, 'stack-toggle')`.
+   *
+   * No-op for single-series data — same convention as the legend.
+   */
+  stacked?: boolean
+}
+
+interface GroupedRow {
+  name: CategoryKey
+  values: number[]
+  /** Per-series per-row color override (first non-undefined wins). */
+  rowColors: (string | undefined)[]
+}
+
+/**
+ * The hidden set as the chart applies it: indices past the current series
+ * count are ignored, and an all-hidden result falls back to all visible.
+ * The stored set is never rewritten from here, so hidden indices survive a
+ * data shrink and come back if the data regrows.
+ */
+function effectiveHidden(
+  hidden: ReadonlySet<number>,
+  seriesCount: number,
+): Set<number> {
+  const clamped = new Set([...hidden].filter((i) => i < seriesCount))
+  return clamped.size >= seriesCount ? new Set<number>() : clamped
+}
+
+/**
+ * Group items by `name` across series so each unique name produces one
+ * row containing N values (zero-filled where a series has no entry for
+ * that name). First-seen order across series is preserved.
+ *
+ * Ported from v1
+ * (`packages/react-ui/src/widgets/category/category-ui.tsx:137-166`)
+ * with readonly typing + per-row color capture.
+ */
+function generateGroupedData(data: CategoryWidgetData): GroupedRow[] {
+  if (!data || data.length === 0) return []
+  const seriesCount = Math.max(data.length, 1)
+  const grouped = new Map<CategoryKey, GroupedRow>()
+  const order: CategoryKey[] = []
+  for (let s = 0; s < data.length; s++) {
+    const series = data[s] ?? []
+    for (const item of series) {
+      let row = grouped.get(item.name)
+      if (!row) {
+        row = {
+          name: item.name,
+          values: new Array<number>(seriesCount).fill(0),
+          rowColors: new Array<string | undefined>(seriesCount).fill(undefined),
+        }
+        grouped.set(item.name, row)
+        order.push(item.name)
+      }
+      row.values[s] = item.value
+      row.rowColors[s] = item.color
+    }
+  }
+  return order.map((k) => grouped.get(k)!)
+}
+
+/**
+ * Pure presentational component for the Category widget. Renders
+ * single-series rows (`data.length === 1`) as a compact grid or
+ * multi-series rows (`data.length > 1`) as stacked-bar groups, capped at
+ * `maxItems` with an overflow summary, and an optional sticky color
+ * legend when `series` metadata is supplied.
+ *
+ * Selection is destination-owned: clicking a row fires
+ * `onSelectionChange(next)` with the toggled set; the consumer keeps the
+ * list in their own store. `aria-pressed` + Enter/Space keyboard
+ * activation give full a11y parity with the mouse path.
+ *
+ * Returns `null` when there's nothing to render — `Widget.State` is the
+ * empty-state authority in the canonical compositor.
+ */
+export function CategoryUI({
+  data,
+  selection,
+  onSelectionChange,
+  formatter,
+  labelFormatter,
+  series,
+  maxItems = DEFAULT_MAX_ITEMS,
+  labels,
+  onShowAll,
+  maxOverride,
+  size = 'small',
+  stacked = false,
+}: CategoryUIProps) {
+  const theme = useTheme()
+  const fmt = formatter ?? ((n: number) => String(n))
+
+  const hasSelection = !!selection && selection.length > 0
+  const selectionSet = useMemo(
+    () => new Set<CategoryKey>(selection ?? []),
+    [selection],
+  )
+
+  const toggle = useCallback(
+    (name: CategoryKey) => {
+      if (!onSelectionChange) return
+      const cur = selection ?? []
+      const next = cur.includes(name)
+        ? cur.filter((n) => n !== name)
+        : [...cur, name]
+      onSelectionChange(next)
+    },
+    [onSelectionChange, selection],
+  )
+
+  // Palette: same convention as Bar/Pie/Histogram/Scatterplot/Timeseries v2.
+  const paletteColors = useMemo<readonly string[]>(
+    () => [
+      theme.palette.secondary.main,
+      ...Object.values(
+        (theme.palette as { qualitative?: { bold?: Record<string, string> } })
+          .qualitative?.bold ?? {},
+      ),
+    ],
+    [theme],
+  )
+
+  const colorAt = useCallback(
+    (seriesIndex: number, rowColor?: string): string => {
+      if (rowColor) return rowColor
+      const seriesColor = series?.[seriesIndex]?.color
+      if (seriesColor) return seriesColor
+      return (
+        paletteColors[seriesIndex % paletteColors.length] ??
+        theme.palette.secondary.main
+      )
+    },
+    [series, paletteColors, theme],
+  )
+
+  // Dim color for non-selected rows when a selection exists. Swapped in
+  // at the bar-fill level only — text + track stay at their real colors.
+  // Theme-driven so it survives palette swaps.
+  const dimColor = theme.palette.action.disabled
+
+  const grouped = useMemo(() => generateGroupedData(data), [data])
+
+  const maxValue = useMemo(() => {
+    if (typeof maxOverride === 'number' && maxOverride > 0) return maxOverride
+    let m = 0
+    for (const row of grouped) {
+      for (const v of row.values) if (v > m) m = v
+    }
+    return m
+  }, [grouped, maxOverride])
+
+  // Three modes:
+  //   * positive finite N (default `DEFAULT_MAX_ITEMS = 20` when prop
+  //     omitted): cap at N rows; surplus folds into "Others <count>".
+  //   * `0`: no cap WITH scroll — every row renders, the list locks to a
+  //     fixed viewport and scrolls internally. Composers use this to
+  //     bypass pagination while the user is searching:
+  //         `maxItems = searcherOpen ? 0 : userMaxItems`
+  //   * `null` / `Infinity` / negative: no cap, no scroll — every row
+  //     renders and the list grows with content. `null` is the canonical
+  //     explicit form (`undefined` is consumed by the default param above).
+  const scrollMode = maxItems === 0
+
+  // Natural-height measurement. In scroll mode (`maxItems === 0`,
+  // set by the composer when the SearcherToggle is open) every row
+  // renders inside a scrollable viewport. The viewport's max-height
+  // must match the pre-overflow content area — i.e., whatever the
+  // list was rendering BEFORE the composer dropped the cap.
+  //
+  // We measure the list's `clientHeight` exactly once, the first time
+  // it attaches while NOT in scroll mode (otherwise we'd capture the
+  // wrong layout). Once set, `naturalHeight` is the lock anchor
+  // forever — matches v1's frozen-at-mount semantics, just with a
+  // real DOM measurement instead of a hard-coded constant.
+  //
+  // Implemented via a callback ref instead of `useLayoutEffect` so
+  // setState fires during commit, not inside an effect — satisfies
+  // the `react-hooks/set-state-in-effect` rule. React invokes
+  // callback refs on attach (and re-invokes them when the callback
+  // identity changes, which it does when `scrollMode` flips), so
+  // toggling the searcher off after a scroll-mode mount triggers the
+  // first measurement at that point.
+  //
+  // Fallback: if the consumer never lands a non-scroll render
+  // (e.g., searcher pre-enabled and never closed), `naturalHeight`
+  // stays `null` → viewport falls back to `8 × ROW_HEIGHT_PX`.
+  const measuredRef = useRef(false)
+  const [naturalHeight, setNaturalHeight] = useState<number | null>(null)
+  const listRefCallback = useCallback(
+    (node: HTMLDivElement | null) => {
+      if (!node) return
+      if (measuredRef.current) return
+      if (scrollMode) return
+      const h = node.clientHeight
+      if (h > 0) {
+        measuredRef.current = true
+        setNaturalHeight(h)
+      }
+    },
+    [scrollMode],
+  )
+
+  // Which series are hidden via a legend click. Local UI-only state — not
+  // synced to `selection`/`onSelectionChange` (that's row-level filter
+  // selection, unrelated). Never allowed to reach "every series hidden":
+  // toggling the last visible one instead resets to "all visible" rather
+  // than leaving the widget blank.
+  const [hiddenSeries, setHiddenSeries] = useState<ReadonlySet<number>>(
+    () => new Set(),
+  )
+  // A reload with a different series breakdown invalidates hidden indices —
+  // index 2 may now point at an entirely different series. Reset rather
+  // than keep hiding whatever now occupies a stale index. Adjusted directly
+  // during render (React's documented "adjusting state when a prop changes"
+  // pattern) instead of in a `useEffect`, which would commit the stale
+  // hidden-set for one extra frame before the effect fires. Compared by a
+  // content-derived key, not the raw `series` reference — an inline
+  // `series={[...]}` literal (no useMemo) gets a new reference on every
+  // unrelated parent re-render, which would otherwise reset hiddenSeries
+  // right after the user hides one.
+  const seriesKey = JSON.stringify(series?.map((s) => s.name) ?? [])
+  const [prevSeriesKey, setPrevSeriesKey] = useState(seriesKey)
+  if (seriesKey !== prevSeriesKey) {
+    setPrevSeriesKey(seriesKey)
+    setHiddenSeries(new Set())
+  }
+  // Real number of data series — NOT `series?.length`, which is legend
+  // metadata and may legitimately be shorter than the actual series count
+  // (unnamed trailing series fall back to `Series N`). Using the metadata
+  // length here would trip the "never fully hidden" guard early whenever
+  // `series` is shorter than `data`.
+  const seriesCount = Math.max(data.length, 1)
+  const toggleSeries = useCallback(
+    (index: number) => {
+      setHiddenSeries((prev) => {
+        // Start from what the user sees, not the stored set: `data` can
+        // shrink while the `series` names hold (the reset only watches the
+        // names), and a stale index would otherwise count toward the guard
+        // below — or make unchecking one series hide a different one.
+        const next = effectiveHidden(prev, seriesCount)
+        if (next.has(index)) next.delete(index)
+        else next.add(index)
+        return next.size >= seriesCount ? new Set() : next
+      })
+    },
+    [seriesCount],
+  )
+
+  if (grouped.length === 0) return null
+
+  const hasCap =
+    typeof maxItems === 'number' && Number.isFinite(maxItems) && maxItems > 0
+  const visible = hasCap ? grouped.slice(0, maxItems) : grouped
+  const hiddenCount = hasCap ? grouped.length - visible.length : 0
+
+  const isMulti = data.length > 1
+  const hasLegend = isMulti && !!series && series.length > 0
+  // Invariant across every row in this render — only depends on
+  // `hiddenSeries`/`seriesCount`, not on any particular row's data — so
+  // it's computed once here instead of per row inside the render loop.
+  const activeHidden = effectiveHidden(hiddenSeries, seriesCount)
+  const visibleIdx = Array.from({ length: seriesCount }, (_, i) => i).filter(
+    (i) => !activeHidden.has(i),
+  )
+
+  // Fallback viewport height matches the documented "8 × ROW_HEIGHT_PX"
+  // (see the constants at the top of the file). Earlier code multiplied
+  // this by `seriesCount`, making a 3-series widget render 3× the
+  // intended viewport on the first frame before `naturalHeight` was
+  // measured — a visible layout jump.
+  const scrollMaxHeight = scrollMode
+    ? (naturalHeight ?? ROW_HEIGHT_PX[size] * SCROLL_VIEWPORT_FALLBACK_ROWS)
+    : undefined
+
+  return (
+    <Box sx={styles.root}>
+      <Box
+        ref={listRefCallback}
+        sx={scrollMode ? { ...styles.list, ...styles.listScroll } : styles.list}
+        style={
+          scrollMaxHeight !== undefined
+            ? { maxHeight: scrollMaxHeight, overflowY: 'auto' }
+            : undefined
+        }
+      >
+        {visible.map((row) => {
+          const selected = selectionSet.has(row.name)
+          const dimmed = hasSelection && !selected
+          const displayName = labelFormatter
+            ? labelFormatter(row.name)
+            : undefined
+          // When the row is dimmed, every series' bar fill is replaced
+          // with `dimColor`. Text + track are untouched. This is the
+          // ONLY visual difference between selected and non-selected
+          // rows — no row-level opacity, no `rowSelected` bg tint.
+          const fill = (i: number): string =>
+            dimmed ? dimColor : colorAt(i, row.rowColors[i])
+          // Series hidden via the legend are dropped before reaching the
+          // row components — they render whatever arrays they're given
+          // with no notion of "hidden" themselves. `visibleIdx` is hoisted
+          // above this loop (same for every row).
+          if (isMulti) {
+            if (stacked) {
+              // Stacked-mode branch: one segmented bar per row. Toggling
+              // `stacked` after the natural-height measurement does NOT
+              // re-trigger measurement (see the `naturalHeight` comment
+              // above) — accepted trade-off: stacked rows have a slightly
+              // different height, so the scroll viewport may show extra
+              // whitespace after the toggle. Visual only, not functional.
+              // Stacked rows are per-row normalized — they don't take
+              // the global `maxValue`. Each row's bar fills 100% of the
+              // track and the segments split it by `value_i / sum`. The
+              // numeric total in the header preserves the per-row
+              // magnitude information.
+              return (
+                <CategoryRowStacked
+                  key={String(row.name)}
+                  name={row.name}
+                  displayName={displayName}
+                  values={visibleIdx.map((i) => row.values[i]!)}
+                  colors={visibleIdx.map((i) => fill(i))}
+                  seriesNames={visibleIdx.map(
+                    (i) => series?.[i]?.name ?? `Series ${i + 1}`,
+                  )}
+                  formatter={fmt}
+                  selected={selected}
+                  onToggle={toggle}
+                  size={size}
+                />
+              )
+            }
+            return (
+              <CategoryRowMulti
+                key={String(row.name)}
+                name={row.name}
+                displayName={displayName}
+                values={visibleIdx.map((i) => row.values[i]!)}
+                colors={visibleIdx.map((i) => fill(i))}
+                maxValue={maxValue}
+                formatter={fmt}
+                selected={selected}
+                onToggle={toggle}
+                size={size}
+              />
+            )
+          }
+          return (
+            <CategoryRowSingle
+              key={String(row.name)}
+              name={row.name}
+              displayName={displayName}
+              value={row.values[0] ?? 0}
+              maxValue={maxValue}
+              color={fill(0)}
+              formatter={fmt}
+              selected={selected}
+              onToggle={toggle}
+              size={size}
+            />
+          )
+        })}
+        {hiddenCount > 0 && (
+          <CategoryRowOther
+            hiddenCount={hiddenCount}
+            otherLabel={labels?.other}
+            otherCountLabel={labels?.otherCount}
+            showAllLabel={labels?.showAll}
+            onShowAll={onShowAll}
+          />
+        )}
+      </Box>
+      {hasLegend && series && (
+        <CategoryLegend
+          // Trimmed: `series` is caller metadata and may outrun `data`,
+          // and an entry with no data behind it has nothing to hide.
+          series={series.slice(0, seriesCount)}
+          colorAt={(i) => colorAt(i)}
+          hiddenSeries={activeHidden}
+          onToggle={toggleSeries}
+        />
+      )}
+    </Box>
+  )
+}

package/src/widgets-v2/category/category.relative-data.test.tsx

@@ -0,0 +1,107 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { Provider } from '../provider/widget-provider'
+import {
+  clearAllWidgetStores,
+  useTransformEnabled,
+  useWidgetId,
+} from '../stores'
+import { Category } from './category'
+import { RelativeData } from '../actions/relative-data/relative-data'
+import type { CategoryWidgetData } from './types'
+
+beforeEach(() => clearAllWidgetStores())
+afterEach(() => clearAllWidgetStores())
+
+// Replicates `CategoryActionWiring` from the storybook composer
+// (apps/storybook/stories/modules/widgets/category/category.tsx). The
+// composer-level wiring isn't testable in `apps/storybook` (no vitest
+// infra), so we re-implement just the relative-data branch here and
+// assert the bar-width math end-to-end through Provider → action →
+// bridge → UI.
+function Wired({ maxOverride }: { maxOverride?: number }) {
+  const id = useWidgetId()
+  const relativeDataActive = useTransformEnabled(id, 'relative-data')
+  const effectiveMaxOverride = relativeDataActive ? 100 : maxOverride
+  return <Category maxOverride={effectiveMaxOverride} />
+}
+
+// Single-series dataset where the max value is 1000 so percent values
+// map to round numbers we can match exactly against bar widths.
+const DATA: CategoryWidgetData = [
+  [
+    { name: 'A', value: 1000 },
+    { name: 'B', value: 500 },
+    { name: 'C', value: 250 },
+  ],
+]
+
+function getBarFills(): HTMLElement[] {
+  return Array.from(
+    document.querySelectorAll<HTMLElement>('[data-bar-fill="true"]'),
+  )
+}
+
+describe('Category + RelativeData composer wiring', () => {
+  it('default (RelativeData off) → bars scale to data max', () => {
+    render(
+      <Provider id='cat-rd-off' data={DATA}>
+        <RelativeData />
+        <Wired />
+      </Provider>,
+    )
+    const fills = getBarFills()
+    expect(fills).toHaveLength(3)
+    // 1000/1000, 500/1000, 250/1000
+    expect(fills[0]!.style.width).toBe('100%')
+    expect(fills[1]!.style.width).toBe('50%')
+    expect(fills[2]!.style.width).toBe('25%')
+  })
+
+  it('clicking the % action flips bars to a 100-denominator', () => {
+    render(
+      <Provider id='cat-rd-toggle' data={DATA}>
+        <RelativeData />
+        <Wired />
+      </Provider>,
+    )
+    // Toggle ON. RelativeData rewrites data values into percentages
+    // (A=1000/1750 ≈ 57.14, B=500/1750 ≈ 28.57, C=250/1750 ≈ 14.29) AND
+    // the composer wiring forces maxOverride=100 so the bar widths
+    // match those percent values directly.
+    fireEvent.click(screen.getByRole('button', { name: /relative|percent/i }))
+    const fills = getBarFills()
+    expect(fills).toHaveLength(3)
+    // Allow a small rounding tolerance — the percent transform produces
+    // floats, the bar math multiplies by 100 again.
+    const a = parseFloat(fills[0]!.style.width)
+    const b = parseFloat(fills[1]!.style.width)
+    const c = parseFloat(fills[2]!.style.width)
+    expect(a).toBeGreaterThan(55)
+    expect(a).toBeLessThan(60)
+    expect(b).toBeGreaterThan(27)
+    expect(b).toBeLessThan(30)
+    expect(c).toBeGreaterThan(13)
+    expect(c).toBeLessThan(16)
+    // The largest bar must be NOT 100% — that's the whole point of the
+    // fix. Without the wiring, A would have been 100% (largest of the
+    // percent series).
+    expect(a).toBeLessThan(100)
+  })
+
+  it('toggling off again restores data-max scaling', () => {
+    render(
+      <Provider id='cat-rd-restore' data={DATA}>
+        <RelativeData />
+        <Wired />
+      </Provider>,
+    )
+    const button = screen.getByRole('button', { name: /relative|percent/i })
+    fireEvent.click(button) // on
+    fireEvent.click(button) // off
+    const fills = getBarFills()
+    expect(fills[0]!.style.width).toBe('100%')
+    expect(fills[1]!.style.width).toBe('50%')
+    expect(fills[2]!.style.width).toBe('25%')
+  })
+})

package/src/widgets-v2/category/category.stack-toggle.test.tsx

@@ -0,0 +1,85 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { Provider } from '../provider/widget-provider'
+import {
+  clearAllWidgetStores,
+  useTransformEnabled,
+  useWidgetId,
+} from '../stores'
+import { Category } from './category'
+import { StackToggle } from '../actions/stack-toggle/stack-toggle'
+import type { CategoryWidgetData } from './types'
+
+beforeEach(() => clearAllWidgetStores())
+afterEach(() => clearAllWidgetStores())
+
+// Replicates the stack-toggle branch of `CategoryActionWiring` from the
+// storybook composer. The composer-level wiring isn't testable in
+// `apps/storybook` (no vitest infra), so we re-implement just the
+// stack-toggle branch here and assert the action → bridge → UI path
+// end-to-end through Provider → action → bridge → UI.
+function Wired() {
+  const id = useWidgetId()
+  const stacked = useTransformEnabled(id, 'stack-toggle')
+  return (
+    <Category series={[{ name: 'Women' }, { name: 'Men' }]} stacked={stacked} />
+  )
+}
+
+const DATA: CategoryWidgetData = [
+  [
+    { name: 'A', value: 45 },
+    { name: 'B', value: 30 },
+  ],
+  [
+    { name: 'A', value: 32 },
+    { name: 'B', value: 18 },
+  ],
+]
+
+describe('Category + StackToggle composer wiring', () => {
+  it('default (StackToggle off) → multi-series renders one bar per series per row', () => {
+    const { container } = render(
+      <Provider id='cat-stack-off' data={DATA}>
+        <StackToggle />
+        <Wired />
+      </Provider>,
+    )
+    // CategoryRowMulti renders one track per series per row → 2 rows × 2 = 4.
+    expect(container.querySelectorAll('[data-size]').length).toBe(4)
+    // No breakdown text from the stacked row.
+    expect(screen.queryByText(/Women: 45/)).toBeNull()
+  })
+
+  it('clicking the stack action flips multi-series rendering to stacked rows', () => {
+    const { container } = render(
+      <Provider id='cat-stack-on' data={DATA}>
+        <StackToggle />
+        <Wired />
+      </Provider>,
+    )
+    fireEvent.click(screen.getByRole('button', { name: /stack|unstack/i }))
+    // Stacked rendering: one track per row → 2 tracks total.
+    expect(container.querySelectorAll('[data-size]').length).toBe(2)
+    // Breakdown text appears.
+    expect(screen.getByText('Women: 45')).toBeTruthy()
+    expect(screen.getByText('Men: 32')).toBeTruthy()
+    // Totals show in the header.
+    expect(screen.getByText('77')).toBeTruthy() // A: 45 + 32
+    expect(screen.getByText('48')).toBeTruthy() // B: 30 + 18
+  })
+
+  it('toggling off again restores CategoryRowMulti rendering', () => {
+    const { container } = render(
+      <Provider id='cat-stack-restore' data={DATA}>
+        <StackToggle />
+        <Wired />
+      </Provider>,
+    )
+    const button = screen.getByRole('button', { name: /stack|unstack/i })
+    fireEvent.click(button) // on
+    fireEvent.click(button) // off
+    expect(container.querySelectorAll('[data-size]').length).toBe(4)
+    expect(screen.queryByText(/Women: 45/)).toBeNull()
+  })
+})