@carto/ps-react-ui 4.17.3 → 4.18.0

package/src/widgets-v2/actions/lock-selection/lock-selection.tsx

@@ -1,4 +1,10 @@
-import { useCallback, useEffect, useMemo, type ComponentType } from 'react'
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  type ComponentType,
+} from 'react'
 import { IconButton, type SvgIconProps } from '@mui/material'
 import { Lock as LockIcon } from '@mui/icons-material'
 import { LockOpen as LockOpenIcon } from '@mui/icons-material'
@@ -20,28 +26,40 @@ const LOCK_SELECTION_DESCRIPTOR = {
 
 export type LockSelectionKey = string | number
 
-export interface LockSelectionProps {
+export interface LockSelectionProps<
+  K extends LockSelectionKey = LockSelectionKey,
+> {
   /**
    * Currently-selected items (destination-owned). On lock, this set is
    * snapshotted into `lockedItems` via `onLockChange`.
    */
-  selection: readonly LockSelectionKey[]
+  selection: readonly K[]
   /**
    * Currently-locked items (destination-owned). When non-empty, the widget's
    * data is filtered to these items via the registered transform.
    */
-  lockedItems: readonly LockSelectionKey[]
+  lockedItems: readonly K[]
   /**
    * Fires when the user toggles the lock. The destination is responsible for
    * persisting the new locked set (and re-feeding it via `lockedItems`).
    */
-  onLockChange: (next: readonly LockSelectionKey[]) => void
+  onLockChange: (next: readonly K[]) => void
   labels?: Partial<LockSelectionLabels>
   /** Lock icon (default: `LockIcon`). */
   lockIcon?: ComponentType<SvgIconProps>
   /** Unlock icon (default: `LockOpenIcon`). */
   unlockIcon?: ComponentType<SvgIconProps>
   iconProps?: SvgIconProps
+  /**
+   * Data transform applied while locked. Defaults to {@link filterByLockedItems}
+   * (keeps only `{name, ...}` items whose `name` is in `lockedItems`, across a
+   * `X[][]` series shape — matches Bar/Pie/Category/Timeseries data). Widgets
+   * whose data shape or selection identity differs (bin index, composite
+   * point key, flat rows) pass their own — e.g. Histogram's
+   * `filterHistogramByLockedBins`, Scatterplot's
+   * `filterScatterplotByLockedPoints`, Table's `filterTableByLockedRows`.
+   */
+  filterFn?: (data: unknown, lockedItems: readonly K[]) => unknown
 }
 
 /**
@@ -52,7 +70,7 @@ export interface LockSelectionProps {
  *
  * The trigger is disabled when there is nothing to lock and nothing locked.
  */
-export function LockSelection({
+export function LockSelection<K extends LockSelectionKey = LockSelectionKey>({
   selection,
   lockedItems,
   onLockChange,
@@ -60,7 +78,8 @@ export function LockSelection({
   lockIcon: LockSvg = LockIcon,
   unlockIcon: UnlockSvg = LockOpenIcon,
   iconProps,
-}: LockSelectionProps) {
+  filterFn = filterByLockedItems,
+}: LockSelectionProps<K>) {
   const id = useWidgetId()
   const _labels = { ...DEFAULT_LOCK_SELECTION_LABELS, ...labels }
   const isLocked = lockedItems.length > 0
@@ -69,7 +88,7 @@ export function LockSelection({
   // Pair memoized on lockedItems identity — useTransform re-registers the fn
   // (which closes over the current locked set) whenever the destination feeds
   // a new array. setEnabled drives the middleware-level `enabled` flag.
-  const pairs = useMemoPair(lockedItems)
+  const pairs = useMemoPair(lockedItems, filterFn)
   const { enabled, setEnabled } = useTransform(id, pairs, {
     initialEnabled: isLocked,
   })
@@ -116,14 +135,27 @@ export function LockSelection({
 
 /**
  * Builds a stable `[{ descriptor, fn }]` pair where `fn` closes over the
- * latest `lockedItems`. Re-memoized whenever the array identity changes so
- * `useTransform` re-registers the closure with the freshest data.
+ * latest `lockedItems` and reads `filterFn` from a ref kept fresh via
+ * `useEffect` (never mutated during render — that would break the compiler's
+ * memoization guarantees). `filterFn` is deliberately NOT a `useCallback`
+ * dep — callers (see `filterTableByLockedRows`'s JSDoc) are expected to pass
+ * an inline closure like `(data, locked) => filterTableByLockedRows(data,
+ * locked, keyColumn)`, which has a new identity every render; depending on
+ * it directly would rebuild the transform pair (and everything downstream
+ * of it) every render instead of only when `lockedItems` actually changes.
+ * `fn` itself is invoked later by the data pipeline, not during this
+ * component's render, so reading a ref there is safe.
  */
-function useMemoPair(
-  lockedItems: readonly LockSelectionKey[],
+function useMemoPair<K extends LockSelectionKey>(
+  lockedItems: readonly K[],
+  filterFn: (data: unknown, lockedItems: readonly K[]) => unknown,
 ): readonly TransformPair[] {
+  const filterFnRef = useRef(filterFn)
+  useEffect(() => {
+    filterFnRef.current = filterFn
+  })
   const fn = useCallback(
-    (data: unknown) => filterByLockedItems(data, lockedItems),
+    (data: unknown) => filterFnRef.current(data, lockedItems),
     [lockedItems],
   )
   return useMemo(() => [{ descriptor: LOCK_SELECTION_DESCRIPTOR, fn }], [fn])

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

@@ -338,6 +338,35 @@ describe('<CategoryUI>', () => {
       // The text "A" is still present from the row label.
       expect(screen.getAllByText('A')).toHaveLength(1)
     })
+
+    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()
+    })
+
+    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()
+    })
   })
 
   // ── Selection visual ───────────────────────────────────────────────
@@ -716,6 +745,32 @@ describe('<CategoryUI>', () => {
       expect(screen.getByText('Series 2: 32')).toBeTruthy()
     })
 
+    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()
+    })
+
     it('stacked is a no-op for single-series data (still renders CategoryRowSingle)', () => {
       const { container } = render(
         <CategoryUI data={[[{ name: 'A', value: 10 }]]} stacked />,

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

@@ -281,6 +281,48 @@ export function CategoryUI({
     [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) => {
+        const next = new Set(prev)
+        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 =
@@ -290,6 +332,12 @@ export function CategoryUI({
 
   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 visibleIdx = Array.from({ length: seriesCount }, (_, i) => i).filter(
+    (i) => !hiddenSeries.has(i),
+  )
 
   // Fallback viewport height matches the documented "8 × ROW_HEIGHT_PX"
   // (see the constants at the top of the file). Earlier code multiplied
@@ -323,6 +371,10 @@ export function CategoryUI({
           // 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
@@ -341,9 +393,11 @@ export function CategoryUI({
                   key={String(row.name)}
                   name={row.name}
                   displayName={displayName}
-                  values={row.values}
-                  colors={row.values.map((_, i) => fill(i))}
-                  seriesNames={series?.map((s) => s.name) ?? []}
+                  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}
@@ -356,8 +410,8 @@ export function CategoryUI({
                 key={String(row.name)}
                 name={row.name}
                 displayName={displayName}
-                values={row.values}
-                colors={row.values.map((_, i) => fill(i))}
+                values={visibleIdx.map((i) => row.values[i]!)}
+                colors={visibleIdx.map((i) => fill(i))}
                 maxValue={maxValue}
                 formatter={fmt}
                 selected={selected}
@@ -392,7 +446,12 @@ export function CategoryUI({
         )}
       </Box>
       {hasLegend && series && (
-        <CategoryLegend series={series} colorAt={(i) => colorAt(i)} />
+        <CategoryLegend
+          series={series}
+          colorAt={(i) => colorAt(i)}
+          hiddenSeries={hiddenSeries}
+          onToggle={toggleSeries}
+        />
       )}
     </Box>
   )

package/src/widgets-v2/category/components/category-legend.test.tsx

@@ -1,13 +1,21 @@
-import { describe, it, expect } from 'vitest'
+import { describe, it, expect, vi } from 'vitest'
 import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
 import { CategoryLegend } from './category-legend'
 
 const noColors = () => undefined
+const noHidden = new Set<number>()
+const noop = vi.fn()
 
 describe('<CategoryLegend>', () => {
   it('renders nothing when series is empty', () => {
     const { container } = render(
-      <CategoryLegend series={[]} colorAt={noColors} />,
+      <CategoryLegend
+        series={[]}
+        colorAt={noColors}
+        hiddenSeries={noHidden}
+        onToggle={noop}
+      />,
     )
     expect(container.firstChild).toBeNull()
   })
@@ -17,6 +25,8 @@ describe('<CategoryLegend>', () => {
       <CategoryLegend
         series={[{ name: '2024' }, { name: '2025' }]}
         colorAt={(i) => (i === 0 ? 'rgb(1, 1, 1)' : 'rgb(2, 2, 2)')}
+        hiddenSeries={noHidden}
+        onToggle={noop}
       />,
     )
     expect(screen.getByText('2024')).toBeTruthy()
@@ -28,6 +38,8 @@ describe('<CategoryLegend>', () => {
       <CategoryLegend
         series={[{ name: 'S1', color: 'rgb(99, 0, 0)' }]}
         colorAt={() => 'rgb(0, 0, 0)'}
+        hiddenSeries={noHidden}
+        onToggle={noop}
       />,
     )
     const dot = Array.from(container.querySelectorAll('div')).find(
@@ -41,6 +53,8 @@ describe('<CategoryLegend>', () => {
       <CategoryLegend
         series={[{ name: 'S1' }]}
         colorAt={() => 'rgb(7, 7, 7)'}
+        hiddenSeries={noHidden}
+        onToggle={noop}
       />,
     )
     const dot = Array.from(container.querySelectorAll('div')).find(
@@ -48,4 +62,41 @@ describe('<CategoryLegend>', () => {
     )
     expect(dot).toBeTruthy()
   })
+
+  it('clicking a legend item calls onToggle with its series index', async () => {
+    const onToggle = vi.fn()
+    render(
+      <CategoryLegend
+        series={[{ name: '2024' }, { name: '2025' }]}
+        colorAt={noColors}
+        hiddenSeries={noHidden}
+        onToggle={onToggle}
+      />,
+    )
+    await userEvent.click(screen.getByText('2025'))
+    expect(onToggle).toHaveBeenCalledWith(1)
+  })
+
+  it('marks a hidden series as aria-checked=false (dimmed)', () => {
+    render(
+      <CategoryLegend
+        series={[{ name: '2024' }, { name: '2025' }]}
+        colorAt={noColors}
+        hiddenSeries={new Set([1])}
+        onToggle={noop}
+      />,
+    )
+    expect(
+      screen
+        .getByText('2024')
+        .closest('[role="checkbox"]')
+        ?.getAttribute('aria-checked'),
+    ).toBe('true')
+    expect(
+      screen
+        .getByText('2025')
+        .closest('[role="checkbox"]')
+        ?.getAttribute('aria-checked'),
+    ).toBe('false')
+  })
 })

package/src/widgets-v2/category/components/category-legend.tsx

@@ -13,27 +13,70 @@ export interface CategoryLegendProps {
    * same source).
    */
   colorAt: (index: number) => string | undefined
+  /**
+   * Series indices currently hidden from the chart. Renders dimmed.
+   * Optional — defaults to none hidden. Added after this component's first
+   * release; kept optional (not required) so it stays a non-breaking
+   * addition for any direct consumer of `CategoryLegend` (a public
+   * subpath export) that predates the hide feature.
+   */
+  hiddenSeries?: ReadonlySet<number>
+  /**
+   * Fires with the series index when its legend item is clicked. Optional
+   * — omitting it renders a legend with no hide affordance (same
+   * reasoning as `hiddenSeries`).
+   */
+  onToggle?: (index: number) => void
 }
 
+const NO_HIDDEN_SERIES: ReadonlySet<number> = new Set()
+
 /**
  * Sticky color legend rendered below a multi-series Category list.
- * Per-series `color` overrides the matching `colorAt(i)` result.
+ * Per-series `color` overrides the matching `colorAt(i)` result. Clicking an
+ * item toggles that series' visibility in the rows above (mirrors ECharts'
+ * native legend click-to-hide).
  */
-export function CategoryLegend({ series, colorAt }: CategoryLegendProps) {
+export function CategoryLegend({
+  series,
+  colorAt,
+  hiddenSeries = NO_HIDDEN_SERIES,
+  onToggle,
+}: CategoryLegendProps) {
   if (series.length === 0) return null
   return (
     <Box sx={styles.legend}>
-      {series.map((s, i) => (
-        <Box key={s.name} sx={styles.legendItem}>
+      {series.map((s, i) => {
+        const hidden = hiddenSeries.has(i)
+        return (
           <Box
-            sx={styles.legendDot}
-            style={{ backgroundColor: s.color ?? colorAt(i) }}
-          />
-          <Typography variant='caption' sx={styles.legendLabel}>
-            {s.name}
-          </Typography>
-        </Box>
-      ))}
+            key={s.name}
+            // `checkbox`/`aria-checked`, not `button`/`aria-pressed` — this
+            // toggles a persistent visibility state (closer to a checkbox)
+            // AND keeps it out of `getByRole('button')` queries that count
+            // category ROWS throughout this widget's test suite.
+            role='checkbox'
+            aria-checked={!hidden}
+            tabIndex={0}
+            onClick={() => onToggle?.(i)}
+            onKeyDown={(e) => {
+              if (e.key === 'Enter' || e.key === ' ') {
+                e.preventDefault()
+                onToggle?.(i)
+              }
+            }}
+            sx={hidden ? styles.legendItemHidden : styles.legendItem}
+          >
+            <Box
+              sx={styles.legendDot}
+              style={{ backgroundColor: s.color ?? colorAt(i) }}
+            />
+            <Typography variant='caption' sx={styles.legendLabel}>
+              {s.name}
+            </Typography>
+          </Box>
+        )
+      })}
     </Box>
   )
 }

package/src/widgets-v2/category/components/category-row-stacked.test.tsx

@@ -69,20 +69,24 @@ describe('<CategoryRowStacked>', () => {
     expect(screen.getByText('Men: 32')).toBeTruthy()
   })
 
-  it('falls back to "Series N" for missing series names (1-indexed)', () => {
+  it("renders whatever seriesNames it is given — fallback resolution is the caller's responsibility", () => {
+    // The component has no notion of which series were hidden upstream, so
+    // it must not recompute a positional "Series N" fallback itself — the
+    // caller (category-ui.tsx) resolves names, including fallbacks, using
+    // each series' ORIGINAL index before this component ever sees them.
     render(
       <CategoryRowStacked
         name='Cat'
         values={[45, 32]}
         colors={COLORS}
-        seriesNames={[]}
+        seriesNames={['Series 1', 'Series 3']}
         formatter={(n) => String(n)}
         selected={false}
         onToggle={vi.fn()}
       />,
     )
     expect(screen.getByText('Series 1: 45')).toBeTruthy()
-    expect(screen.getByText('Series 2: 32')).toBeTruthy()
+    expect(screen.getByText('Series 3: 32')).toBeTruthy()
   })
 
   it('per-row normalization: bar fills 100% with segments proportional to the row sum', () => {

package/src/widgets-v2/category/components/category-row-stacked.tsx

@@ -13,7 +13,12 @@ export interface CategoryRowStackedProps {
   values: readonly number[]
   /** One color per series (palette + per-series overrides resolved upstream). */
   colors: readonly string[]
-  /** Series names for the breakdown row. Missing entries fall back to `Series N`. */
+  /**
+   * Series names for the breakdown row, one per visible series, already
+   * resolved by the caller (unnamed series fall back to `Series N` using
+   * their ORIGINAL series index — this component has no notion of which
+   * series were hidden, so it must not recompute a positional fallback).
+   */
   seriesNames: readonly string[]
   formatter: (n: number) => string
   selected: boolean
@@ -86,11 +91,11 @@ export function CategoryRowStacked({
         {values.map((v, i) => (
           // Series name is the stable identity for the breakdown line.
           <Typography
-            key={`breakdown-${seriesNames[i] ?? `series-${i}`}`}
+            key={`breakdown-${seriesNames[i]}`}
             variant='body2'
             sx={styles.stackedBreakdownItem}
           >
-            {`${seriesNames[i] ?? `Series ${i + 1}`}: ${formatter(v)}`}
+            {`${seriesNames[i]}: ${formatter(v)}`}
           </Typography>
         ))}
       </Box>

package/src/widgets-v2/category/style.ts

@@ -260,10 +260,18 @@ export const styles = {
     display: 'flex',
     alignItems: 'center',
     gap: 1,
+    cursor: 'pointer',
+  },
+  legendItemHidden: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 1,
+    cursor: 'pointer',
+    opacity: 0.5,
   },
   legendDot: {
-    width: 8,
-    height: 8,
+    width: 14,
+    height: 14,
     borderRadius: '50%',
   },
   legendLabel: {

package/src/widgets-v2/echart/echart-ui.test.tsx

@@ -11,6 +11,7 @@ const mockChart = {
   resize: vi.fn(),
   on: vi.fn(),
   off: vi.fn(),
+  dispatchAction: vi.fn(),
   // Stubbed for the edge-label clamp; tests override per-case.
   convertToPixel: vi.fn((_finder: unknown, index: number) =>
     index === 0 ? 4 : 296,
@@ -39,6 +40,15 @@ function fireFinished(): void {
   }
 }
 
+/** Invoke the `legendselectchanged` listener the bridge bound on the mock chart. */
+function fireLegendSelectChanged(selected: Record<string, boolean>): void {
+  for (const [event, handler] of mockChart.on.mock.calls) {
+    if (event === 'legendselectchanged') {
+      ;(handler as (params: unknown) => void)({ selected })
+    }
+  }
+}
+
 // Resize observer mock — capture the callback so tests can trigger it.
 let resizeCb: (() => void) | null = null
 const observeResizeSpy = vi.fn((_node: HTMLElement, cb: () => void) => {
@@ -60,6 +70,7 @@ beforeEach(() => {
   mockChart.resize.mockReset()
   mockChart.on.mockReset()
   mockChart.off.mockReset()
+  mockChart.dispatchAction.mockReset()
   mockChart.convertToPixel.mockClear()
   mockChart.getWidth.mockClear()
   initSpy.mockClear()
@@ -219,6 +230,20 @@ describe('<EchartUI>', () => {
     expect(mockChart.dispose).toHaveBeenCalledTimes(1)
   })
 
+  it('restores every legend item when a legend click hides the last one', () => {
+    render(<EchartUI option={{}} />)
+    fireLegendSelectChanged({ A: false, B: false, C: false })
+    expect(mockChart.dispatchAction).toHaveBeenCalledWith({
+      type: 'legendAllSelect',
+    })
+  })
+
+  it('does nothing while at least one legend item stays visible', () => {
+    render(<EchartUI option={{}} />)
+    fireLegendSelectChanged({ A: true, B: false, C: false })
+    expect(mockChart.dispatchAction).not.toHaveBeenCalled()
+  })
+
   it('clamps overflowing edge labels on `finished` (category x-axis)', () => {
     render(<EchartUI option={categoryOption} />)
     mockChart.setOption.mockClear()

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

@@ -114,8 +114,28 @@ export function EchartUI({
       )
     }
     chart.on('finished', onFinished)
+    // Never let the legend end up with every item hidden — a user can click
+    // series off one by one until the chart goes blank. `selected` on this
+    // event is always the FULL name→boolean map (not just the clicked item),
+    // so "every value false" reliably means "nothing left visible". Restore
+    // all of them instead. `legendAllSelect` fires its own `legendselectall`
+    // event, not `legendselectchanged`, so this can't re-trigger itself.
+    // Always-on and independent of the consumer's `onEvents` — applies to
+    // every ECharts widget in the library for free. A widget that disables
+    // legend clicks entirely (e.g. Pie's `selectedMode: false`) never fires
+    // `legendselectchanged`, so this is a no-op there.
+    const onLegendSelectChanged = (params: unknown): void => {
+      const { selected } = params as { selected?: Record<string, boolean> }
+      if (!selected) return
+      const names = Object.keys(selected)
+      if (names.length > 0 && names.every((name) => !selected[name])) {
+        chart.dispatchAction({ type: 'legendAllSelect' })
+      }
+    }
+    chart.on('legendselectchanged', onLegendSelectChanged)
     return () => {
       chart.off('finished', onFinished)
+      chart.off('legendselectchanged', onLegendSelectChanged)
       // Notify observers *before* disposal so any queued imperative
       // dispatches (e.g. ZoomToggle's `setOption` cleanup) see the
       // instance disappear before its DOM is torn down.

package/src/widgets-v2/echart/use-chart-selection.test.tsx

@@ -61,7 +61,7 @@ describe('useChartSelection', () => {
     expect(onSelectionChange).toHaveBeenLastCalledWith([3, 7, 11])
   })
 
-  it('reports null `selection` when the consumer passes nothing or an empty list', () => {
+  it('collapses undefined/null/an explicit empty list to null, since no merger treats them differently', () => {
     const { result, rerender } = renderHook(
       ({ selection }: { selection?: readonly string[] }) =>
         useChartSelection<string>({
@@ -81,6 +81,8 @@ describe('useChartSelection', () => {
     expect(result.current.selection).toBeNull()
     rerender({ selection: ['A'] })
     expect(result.current.selection).toEqual(['A'])
+    rerender({ selection: undefined })
+    expect(result.current.selection).toBeNull()
   })
 
   it('is a no-op when `onSelectionChange` is missing', () => {