@carto/ps-react-ui 4.17.2 → 4.18.0

package/src/legend/components/legend-group/styles.ts

@@ -15,16 +15,46 @@ export const styles = {
       borderTop: '1px solid',
       borderColor: 'divider',
     },
-    // Hover-fade group actions (widgets-v2 Wrapper parity). Revealed by
-    // hovering anywhere in the group block (including member rows); a control
-    // carrying `.active` (hidden group) stays visible. Touch devices always
-    // show them. The collapse chevron sits outside the fade group. Member
-    // rows use the distinct `PsLegend-rowFade` class, so group hover never
-    // lights up row actions.
+  },
+  // The original stays in place, dimmed, while its overlay clone is dragged.
+  groupDragging: {
+    opacity: 0.4,
+  },
+  // Figma: 48px tall, 16px left inset (matches the row's own left inset),
+  // 8px gap to the label, actions right-aligned with ~8px edge inset (the
+  // small icon-button padding brings the glyphs to the design's 16px optical
+  // inset), hairline divider below. Sticky: pins to the top of the panel's
+  // scroll container.
+  header: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 1,
+    padding: ({ spacing }) => spacing(1.5, 2, 1.5, 2),
+    minHeight: LEGEND_GROUP_HEADER_HEIGHT,
+    borderBottom: '1px solid',
+    borderColor: 'divider',
+    position: 'sticky',
+    top: 0,
+    // Above the sticky row headers (2), which in turn sit above MUI's
+    // z-index-1 form internals in row content.
+    zIndex: 3,
+    // Distinct from the row header / panel body (both `background.paper`) so
+    // the group header visually separates from the rest.
+    backgroundColor: 'background.default',
+    // Hover-fade group actions (widgets-v2 Wrapper parity). Scoped to the
+    // header itself (not the group root) so hovering a member row's body
+    // below never lights up the group's own actions/handle — only hovering
+    // the header (title/handle/actions) does. A control carrying `.active`
+    // (hidden group) stays visible. Touch devices always show them. The
+    // collapse chevron sits outside the fade group. Each non-active child
+    // also collapses to zero width on its own (not just the whole actions
+    // slot) so a sibling's `.active` pin (e.g. the eye on a mixed-visibility
+    // group) doesn't leave a same-sized invisible hole where the still-faded
+    // ⋮ menu would've been.
     '& .PsLegend-groupFade > *': {
       opacity: 1,
       transition: ({ transitions }: Theme) =>
-        transitions.create('opacity', {
+        transitions.create(['opacity', 'width'], {
           duration: transitions.duration.standard,
           easing: transitions.easing.easeInOut,
         }),
@@ -35,14 +65,21 @@ export const styles = {
         opacity: 1,
       },
     },
-    '&:hover .PsLegend-groupFade > *, &:focus-within .PsLegend-groupFade > *': {
-      opacity: 1,
-    },
     // Faded actions don't reserve flex space on fine-pointer devices — the
     // label grows to the trailing edge. Hover/focus-within restores the slot
     // so the label reflows with the buttons; a dirty `.active` child keeps
     // the slot open even outside hover.
     '@media (hover: hover)': {
+      '& .PsLegend-groupFade > *:not(.active)': {
+        width: 0,
+        minWidth: 0,
+        // border-box IconButtons keep their padding inside `width` — zero it
+        // too, otherwise the fixed 2px+2px padding survives as a tiny but
+        // needless residual gap.
+        padding: 0,
+        overflow: 'hidden',
+        pointerEvents: 'none',
+      },
       '& .PsLegend-groupActions:not(:has(.active))': {
         width: 0,
         minWidth: 0,
@@ -52,6 +89,14 @@ export const styles = {
         pointerEvents: 'none',
       },
     },
+    '&:hover .PsLegend-groupFade > *, &:focus-within .PsLegend-groupFade > *': {
+      opacity: 1,
+      width: 'auto',
+      minWidth: 0,
+      padding: '2px',
+      overflow: 'visible',
+      pointerEvents: 'auto',
+    },
     '&:hover .PsLegend-groupActions, &:focus-within .PsLegend-groupActions': {
       width: 'auto',
       minWidth: 0,
@@ -78,31 +123,6 @@ export const styles = {
         opacity: 1,
       },
   },
-  // The original stays in place, dimmed, while its overlay clone is dragged.
-  groupDragging: {
-    opacity: 0.4,
-  },
-  // Figma: 48px tall, icon at 12px from the left, 8px gap to the label,
-  // actions right-aligned with ~8px edge inset (the small icon-button padding
-  // brings the glyphs to the design's 16px optical inset), hairline divider
-  // below. Sticky: pins to the top of the panel's scroll container.
-  header: {
-    display: 'flex',
-    alignItems: 'center',
-    gap: 1,
-    padding: ({ spacing }) => spacing(1.5, 2, 1.5, 1),
-    minHeight: LEGEND_GROUP_HEADER_HEIGHT,
-    borderBottom: '1px solid',
-    borderColor: 'divider',
-    position: 'sticky',
-    top: 0,
-    // Above the sticky row headers (2), which in turn sit above MUI's
-    // z-index-1 form internals in row content.
-    zIndex: 3,
-    // Distinct from the row header / panel body (both `background.paper`) so
-    // the group header visually separates from the rest.
-    backgroundColor: 'background.default',
-  },
   // Accordion click target: everything in the header but the actions box.
   // Non-native button (role='button'), so it carries its own focus ring.
   titleArea: {
@@ -123,8 +143,11 @@ export const styles = {
     display: 'flex',
     color: 'text.secondary',
   },
+  // No `flex:1` here — the label sizes to its own text (shrinking to
+  // ellipsis when too long) so the chevron sits right after it, instead of
+  // being dragged to the trailing edge of `titleArea` (which keeps its own
+  // `flex:1` to fill the header up to the actions).
   label: {
-    flex: 1,
     minWidth: 0,
     overflow: 'hidden',
     textOverflow: 'ellipsis',

package/src/legend/components/legend-row/legend-row.tsx

@@ -74,7 +74,10 @@ export function LegendRow({ layerId, children }: LegendRowProps) {
           sortableProps?.dragging === true && styles.rowDragging,
         ]}
       >
-        <Box sx={styles.header} style={{ top: stickyTop }}>
+        <Box
+          sx={[styles.header, inGroup && styles.headerGrouped]}
+          style={{ top: stickyTop }}
+        >
           {sortableProps?.handle}
           <Box
             sx={[styles.titleBox, canToggle && styles.titleBoxInteractive]}
@@ -122,16 +125,16 @@ export function LegendRow({ layerId, children }: LegendRowProps) {
 
         <Collapse in={!effectivelyCollapsed}>
           <Box
-            sx={
-              layer.visible
-                ? styles.content
-                : { ...styles.content, ...styles.dimmed }
-            }
+            sx={[
+              styles.content,
+              inGroup && styles.contentGrouped,
+              !layer.visible && styles.dimmed,
+            ]}
           >
             {body}
           </Box>
           {layer.helperText && (
-            <Box sx={styles.footer}>
+            <Box sx={[styles.footer, inGroup && styles.footerGrouped]}>
               {typeof layer.helperText === 'string' ? (
                 <Typography variant='caption' color='text.secondary'>
                   {layer.helperText}

package/src/legend/components/legend-row/styles.ts

@@ -16,14 +16,16 @@ export const styles = {
     // `.PsLegend-rowFade` are hidden on fine-pointer devices and fade in when
     // the row is hovered or holds focus; a control carrying `.active` (dirty
     // state — hidden layer, open menu, opacity ≠ 1) stays visible. Coarse-
-    // pointer (touch) devices always show them. The actions slot itself also
-    // collapses to zero width while faded (see `PsLegend-rowActions` below)
-    // so the title can grow to the trailing edge. The collapse chevron sits
-    // outside the fade group and never fades.
+    // pointer (touch) devices always show them. Each non-active child also
+    // collapses to zero width on its own (not just the whole actions slot —
+    // see `PsLegend-rowActions` below) so a sibling's `.active` pin (e.g. the
+    // eye while hidden) doesn't leave a same-sized invisible hole where the
+    // still-faded ⋮ menu would've been; the title grows into that space. The
+    // collapse chevron sits outside the fade group and never fades.
     '& .PsLegend-rowFade > *': {
       opacity: 1,
       transition: ({ transitions }: Theme) =>
-        transitions.create('opacity', {
+        transitions.create(['opacity', 'width'], {
           duration: transitions.duration.standard,
           easing: transitions.easing.easeInOut,
         }),
@@ -34,14 +36,21 @@ export const styles = {
         opacity: 1,
       },
     },
-    '&:hover .PsLegend-rowFade > *, &:focus-within .PsLegend-rowFade > *': {
-      opacity: 1,
-    },
     // Faded actions don't reserve flex space on fine-pointer devices — the
     // title grows to the trailing edge. Hover/focus-within restores the slot
     // so the title reflows with the buttons; a dirty `.active` child keeps
     // the slot open even outside hover.
     '@media (hover: hover)': {
+      '& .PsLegend-rowFade > *:not(.active)': {
+        width: 0,
+        minWidth: 0,
+        // border-box IconButtons keep their padding inside `width` — zero it
+        // too, otherwise the fixed 2px+2px padding survives as a tiny but
+        // needless residual gap.
+        padding: 0,
+        overflow: 'hidden',
+        pointerEvents: 'none',
+      },
       '& .PsLegend-rowActions:not(:has(.active))': {
         width: 0,
         minWidth: 0,
@@ -51,6 +60,14 @@ export const styles = {
         pointerEvents: 'none',
       },
     },
+    '&:hover .PsLegend-rowFade > *, &:focus-within .PsLegend-rowFade > *': {
+      opacity: 1,
+      width: 'auto',
+      minWidth: 0,
+      padding: '2px',
+      overflow: 'visible',
+      pointerEvents: 'auto',
+    },
     '&:hover .PsLegend-rowActions, &:focus-within .PsLegend-rowActions': {
       width: 'auto',
       minWidth: 0,
@@ -91,7 +108,9 @@ export const styles = {
   // band (subtitle flows below them) — hence `flex-start` with the title
   // optically centered against the 30px icon-button row. Sticky: pins inside
   // the panel's scroll container; `top` is applied inline per row (0, or the
-  // group-header height for grouped rows).
+  // group-header height for grouped rows). Grouped rows get an extra 20px
+  // left inset (36px total) so member layers read as nested under the group
+  // and line up with the group's own icon+label text start.
   header: {
     display: 'flex',
     alignItems: 'flex-start',
@@ -104,6 +123,9 @@ export const styles = {
     zIndex: 2,
     backgroundColor: 'background.paper',
   },
+  headerGrouped: {
+    paddingLeft: 4.5,
+  },
   titleBox: {
     flex: 1,
     minWidth: 0,
@@ -130,8 +152,11 @@ export const styles = {
     alignItems: 'center',
     gap: 0.5,
   },
+  // No `flex:1` here — the title sizes to its own text (shrinking to
+  // ellipsis when too long) so the chevron sits right after it, instead of
+  // being dragged to the trailing edge of `titleLine` (which spans the full
+  // width of `titleBox`, itself `flex:1` to fill the header up to actions).
   title: {
-    flex: 1,
     minWidth: 0,
     overflow: 'hidden',
     textOverflow: 'ellipsis',
@@ -178,10 +203,16 @@ export const styles = {
     gap: 1,
     padding: ({ spacing }) => spacing(0.5, 2, 1, 2),
   },
+  contentGrouped: {
+    paddingLeft: 4.5,
+  },
   // ~16px above the note (content's 8px bottom inset + 8px here), per design.
   footer: {
     padding: ({ spacing }) => spacing(1, 2, 1, 2),
   },
+  footerGrouped: {
+    paddingLeft: 4.5,
+  },
   dimmed: {
     opacity: 0.5,
   },

package/src/legend/components/legend-sortable/styles.ts

@@ -1,20 +1,29 @@
 import type { SxProps, Theme } from '@mui/material'
+import { LEGEND_GROUP_HEADER_HEIGHT } from '../legend-group/styles'
 
 export const styles = {
-  // Absolute handle — no flex slot; sticky header is the containing block.
+  // Absolute handle, flush against the header's top-left corner — no flex
+  // slot; sticky header is the containing block.
   handleSlot: {
     position: 'absolute',
     zIndex: 1,
     display: 'flex',
     alignItems: 'center',
     justifyContent: 'center',
-    height: 24,
+    left: 0,
+    top: 0,
   },
+  // Both headers center their title on the same 24px band from the header's
+  // top edge (group: 48px header, `alignItems:'center'`; row: 12px top
+  // padding + 24px `titleLine`, `alignItems:'flex-start'`) — so `height:48`
+  // centers the icon on the title in both cases, even though the row's own
+  // header is only 32px tall (a 32px-tall slot would center at 16px, 8px
+  // short of the title).
   handleSlotLayer: {
-    right: 2,
+    height: LEGEND_GROUP_HEADER_HEIGHT,
   },
   handleSlotGroup: {
-    right: 2,
+    height: LEGEND_GROUP_HEADER_HEIGHT,
   },
   handle: {
     padding: '2px',

package/src/legend/stores/legend-store-registry.ts

@@ -238,15 +238,21 @@ function mergeLayerEntity(
   } as LegendLayer
 }
 
-/** Group counterpart of {@link mergeLayerEntity}. */
+/**
+ * Group counterpart of {@link mergeLayerEntity}. A group with no `prev`
+ * state (first sync) defaults collapsed when none of its member layers is
+ * visible yet — `hasVisibleLayer` is ignored once the group exists so a
+ * user's manual expand/collapse always sticks.
+ */
 function mergeGroupEntity(
   prev: LegendGroup | undefined,
   input: LegendGroupInput,
   fallbackOrder: number,
+  hasVisibleLayer: boolean,
 ): LegendGroup {
   return {
     ...input,
-    collapsed: prev?.collapsed ?? input.collapsed ?? false,
+    collapsed: prev?.collapsed ?? input.collapsed ?? !hasVisibleLayer,
     collapsedBeforeHide: prev?.collapsedBeforeHide,
     order: prev?.order ?? input.order ?? fallbackOrder,
   } as LegendGroup
@@ -274,9 +280,19 @@ function syncState(
   }))
   normalizeOrders(layerEntries, (l) => l.groupId)
 
+  const groupsWithVisibleLayer = new Set(
+    layerEntries
+      .filter(({ merged }) => merged.visible && merged.groupId != null)
+      .map(({ merged }) => merged.groupId!),
+  )
   const groupEntries = groupInputs.map((input, index) => ({
     index,
-    merged: mergeGroupEntity(state.groups[input.id], input, index),
+    merged: mergeGroupEntity(
+      state.groups[input.id],
+      input,
+      index,
+      groupsWithVisibleLayer.has(input.id),
+    ),
   }))
   normalizeOrders(groupEntries, () => undefined)
 
@@ -382,7 +398,15 @@ function upsertGroupState(
   const count = Object.values(state.groups).filter(
     (g) => g.id !== input.id,
   ).length
-  const merged = mergeGroupEntity(state.groups[input.id], input, count)
+  const hasVisibleLayer = Object.values(state.layers).some(
+    (l) => l.groupId === input.id && l.visible,
+  )
+  const merged = mergeGroupEntity(
+    state.groups[input.id],
+    input,
+    count,
+    hasVisibleLayer,
+  )
   const groups = rebuildRecord(
     state.groups,
     { ...state.groups, [input.id]: merged },

package/src/legend/stores/legend-store.test.ts

@@ -148,6 +148,29 @@ describe('legend store', () => {
     expect(store.getState().groups.g1!.collapsed).toBe(true)
   })
 
+  it('a group with no visible member starts collapsed', () => {
+    const store = createLegendStore('s', {
+      layers: layers.map((l) =>
+        l.groupId === 'g1' ? { ...l, visible: false } : l,
+      ),
+      groups: [
+        { id: 'g1', label: 'One' },
+        { id: 'g2', label: 'Empty' },
+      ],
+    })
+    expect(store.getState().groups.g1!.collapsed).toBe(true)
+    // No members at all also counts as "nothing enabled".
+    expect(store.getState().groups.g2!.collapsed).toBe(true)
+  })
+
+  it('a group with at least one visible member starts expanded', () => {
+    const store = createLegendStore('s', {
+      layers,
+      groups: [{ id: 'g1', label: 'One' }],
+    })
+    expect(store.getState().groups.g1!.collapsed).toBe(false)
+  })
+
   it('selectGroupVisibility derives the tri-state from member layers', () => {
     const store = createLegendStore('s', {
       layers,

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

@@ -124,6 +124,68 @@ describe('<LockSelection>', () => {
     expect(unlocked.flat().length).toBe(3)
   })
 
+  it('uses a custom filterFn instead of filterByLockedItems when supplied', () => {
+    const customFilter = vi.fn(
+      (data: unknown, locked: readonly (string | number)[]) =>
+        (data as unknown[][]).map((series) =>
+          series.filter((_, i) => locked.includes(i)),
+        ),
+    )
+    render(
+      <Provider id='ls8' data={DATA}>
+        <LockSelection
+          selection={[0]}
+          lockedItems={[0]}
+          onLockChange={() => undefined}
+          filterFn={customFilter}
+        />
+      </Provider>,
+    )
+    expect(customFilter).toHaveBeenCalledWith(DATA, [0])
+    const locked = getWidgetStore('ls8').getState().data as unknown[][]
+    expect(locked).toEqual([[{ name: 'A', value: 10 }]])
+  })
+
+  it('does not rebuild the registered transform when filterFn gets a fresh identity but lockedItems is unchanged', () => {
+    // Mirrors the documented usage in table/transforms.ts: an inline lambda
+    // closing over `filterFn`, a new function identity on every render.
+    // `SELECTION`/`LOCKED` are hoisted so their *reference* stays stable
+    // across renders — only `filterFn`'s identity should vary here.
+    const SELECTION = ['A']
+    const LOCKED = ['A']
+    let renderCount = 0
+    const Wrapper = () => {
+      renderCount++
+      return (
+        <LockSelection
+          selection={SELECTION}
+          lockedItems={LOCKED}
+          onLockChange={() => undefined}
+          filterFn={(data, locked) => filterByLockedItems(data, locked)}
+        />
+      )
+    }
+    const { rerender } = render(
+      <Provider id='ls9' data={DATA}>
+        <Wrapper />
+      </Provider>,
+    )
+    const firstTransforms = getWidgetStore('ls9').getState().dataTransforms
+    rerender(
+      <Provider id='ls9' data={DATA}>
+        <Wrapper />
+      </Provider>,
+    )
+    expect(renderCount).toBe(2)
+    const secondTransforms = getWidgetStore('ls9').getState().dataTransforms
+    // Same reference — `useMemoPair`'s `useCallback` only depends on
+    // `lockedItems`, so a fresh inline `filterFn` each render must not
+    // rebuild the transform pair.
+    expect(secondTransforms).toBe(firstTransforms)
+    const locked = getWidgetStore('ls9').getState().data as unknown[][]
+    expect(locked).toEqual([[{ name: 'A', value: 10 }]])
+  })
+
   it('lets the destination feed a different lockedItems set later', () => {
     const { rerender } = render(
       <Provider id='ls7' data={DATA}>

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 />,