@carto/ps-react-ui 4.9.1 → 4.11.0

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

@@ -50,7 +50,7 @@ export interface CategoryUIProps {
    * Caps the number of visible category rows.
    *
    * - `undefined` (omitted) — caps at {@link DEFAULT_MAX_ITEMS} (20).
-   *   Surplus rows fold into a single italic "Other (X more)" footer.
+   *   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.
@@ -71,6 +71,13 @@ export interface CategoryUIProps {
   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
   /**
@@ -156,6 +163,7 @@ export function CategoryUI({
   series,
   maxItems = DEFAULT_MAX_ITEMS,
   labels,
+  onShowAll,
   maxOverride,
   size = 'small',
   stacked = false,
@@ -224,7 +232,7 @@ export function CategoryUI({
 
   // Three modes:
   //   * positive finite N (default `DEFAULT_MAX_ITEMS = 20` when prop
-  //     omitted): cap at N rows; surplus folds into "Other (X more)".
+  //     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:
@@ -296,7 +304,7 @@ export function CategoryUI({
     <Box sx={styles.root}>
       <Box
         ref={listRefCallback}
-        sx={styles.list}
+        sx={scrollMode ? { ...styles.list, ...styles.listScroll } : styles.list}
         style={
           scrollMaxHeight !== undefined
             ? { maxHeight: scrollMaxHeight, overflowY: 'auto' }
@@ -378,6 +386,8 @@ export function CategoryUI({
             hiddenCount={hiddenCount}
             otherLabel={labels?.other}
             otherCountLabel={labels?.otherCount}
+            showAllLabel={labels?.showAll}
+            onShowAll={onShowAll}
           />
         )}
       </Box>

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

@@ -96,7 +96,7 @@ describe('<Category> bridge', () => {
     // 3 visible rows + Other footer.
     expect(screen.getAllByRole('button')).toHaveLength(3)
     expect(screen.getByText('Rest')).toBeTruthy()
-    expect(screen.getByText('((3 hidden))')).toBeTruthy()
+    expect(screen.getByText('(3 hidden)')).toBeTruthy()
   })
 
   it('does NOT read `transformStates.searcher.enabled` from the store (composer-mediation contract)', () => {
@@ -119,7 +119,7 @@ describe('<Category> bridge', () => {
       </Provider>,
     )
     expect(screen.getAllByRole('button')).toHaveLength(3)
-    expect(screen.getByText('Other')).toBeTruthy()
+    expect(screen.getByText('Others')).toBeTruthy()
 
     // Flip the searcher flag in the store — bridge should NOT react.
     act(() => {
@@ -134,7 +134,7 @@ describe('<Category> bridge', () => {
 
     // Still capped, Other still there.
     expect(screen.getAllByRole('button')).toHaveLength(3)
-    expect(screen.getByText('Other')).toBeTruthy()
+    expect(screen.getByText('Others')).toBeTruthy()
   })
 
   it('respects maxItems=0 (no-cap sentinel) from the consumer', () => {
@@ -153,7 +153,7 @@ describe('<Category> bridge', () => {
     )
     // No cap → all rows render, Other footer is suppressed.
     expect(screen.getAllByRole('button')).toHaveLength(10)
-    expect(screen.queryByText('Other')).toBeNull()
+    expect(screen.queryByText('Others')).toBeNull()
   })
 
   it('forwards size="medium" through to the rendered bars', () => {

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

@@ -40,7 +40,7 @@ export interface CategoryProps {
   /** Per-series metadata. Enables the legend + overrides palette per index. */
   series?: readonly CategorySeriesConfig[]
   /**
-   * Cap visible rows; overflow folds into "Other (X more)". Default 20
+   * Cap visible rows; overflow folds into an "Others <count>" row. Default 20
    * (when omitted). Pass `0` to swap the cap for a scrollable viewport
    * (composers use this when the user opens the SearcherToggle —
    * `maxItems = searcherOpen ? 0 : userMaxItems`). Pass `null` to disable
@@ -49,6 +49,13 @@ export interface CategoryProps {
   maxItems?: number | null
   /** Labels for the "Other" overflow row. */
   labels?: CategoryLabels
+  /**
+   * When provided, the "Other" overflow row becomes a button that fires this
+   * callback. Composers wire it to expand the widget (e.g. flip the
+   * `show-all` flag) so every category is shown. Forwarded to
+   * {@link CategoryUI}.
+   */
+  onShowAll?: () => void
   /**
    * Manual override for the bar-width denominator. When omitted, the
    * bridge auto-fills from the widget store's `rawData` so bar widths
@@ -85,6 +92,7 @@ export function Category({
   series,
   maxItems,
   labels,
+  onShowAll,
   maxOverride,
   size,
   stacked,
@@ -113,6 +121,7 @@ export function Category({
       series={series}
       maxItems={maxItems}
       labels={labels}
+      onShowAll={onShowAll}
       maxOverride={effectiveMaxOverride}
       size={size}
       stacked={stacked}

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

@@ -1,12 +1,13 @@
-import { describe, it, expect } from 'vitest'
-import { render, screen } from '@testing-library/react'
+import { describe, it, expect, vi } from 'vitest'
+import { fireEvent, render, screen } from '@testing-library/react'
 import { CategoryRowOther } from './category-row-other'
 
 describe('<CategoryRowOther>', () => {
-  it('renders the default labels with substituted count', () => {
+  it('renders the default label + bare count (no parentheses)', () => {
     render(<CategoryRowOther hiddenCount={7} />)
-    expect(screen.getByText('Other')).toBeTruthy()
-    expect(screen.getByText('(7 more)')).toBeTruthy()
+    expect(screen.getByText('Others')).toBeTruthy()
+    expect(screen.getByText('7')).toBeTruthy()
+    expect(screen.queryByText('(7 more)')).toBeNull()
   })
 
   it('honors custom labels with {count} placeholder', () => {
@@ -18,11 +19,39 @@ describe('<CategoryRowOther>', () => {
       />,
     )
     expect(screen.getByText('Hidden')).toBeTruthy()
-    expect(screen.getByText('(+3 not shown)')).toBeTruthy()
+    expect(screen.getByText('+3 not shown')).toBeTruthy()
   })
 
-  it('is not a button (non-interactive)', () => {
+  it('is not a button when onShowAll is omitted (static fallback)', () => {
     const { container } = render(<CategoryRowOther hiddenCount={1} />)
     expect(container.querySelectorAll('[role="button"]').length).toBe(0)
   })
+
+  describe('when onShowAll is provided', () => {
+    it('renders as a button', () => {
+      render(<CategoryRowOther hiddenCount={4} onShowAll={vi.fn()} />)
+      expect(screen.getByRole('button')).toBeTruthy()
+    })
+
+    it('fires onShowAll on click', () => {
+      const onShowAll = vi.fn()
+      render(<CategoryRowOther hiddenCount={4} onShowAll={onShowAll} />)
+      fireEvent.click(screen.getByRole('button'))
+      expect(onShowAll).toHaveBeenCalledTimes(1)
+    })
+
+    it('fires onShowAll on Enter and Space', () => {
+      const onShowAll = vi.fn()
+      render(<CategoryRowOther hiddenCount={4} onShowAll={onShowAll} />)
+      const btn = screen.getByRole('button')
+      fireEvent.keyDown(btn, { key: 'Enter' })
+      fireEvent.keyDown(btn, { key: ' ' })
+      expect(onShowAll).toHaveBeenCalledTimes(2)
+    })
+
+    it('is keyboard-focusable', () => {
+      render(<CategoryRowOther hiddenCount={4} onShowAll={vi.fn()} />)
+      expect(screen.getByRole('button').getAttribute('tabindex')).toBe('0')
+    })
+  })
 })

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

@@ -1,33 +1,84 @@
+import type { KeyboardEvent } from 'react'
 import { Box, Typography } from '@mui/material'
+import { Tooltip } from '../../../components'
 import { styles } from '../style'
 
 export interface CategoryRowOtherProps {
   hiddenCount: number
-  /** Label for the overflow row. Defaults to `'Other'`. */
+  /** Label for the overflow row. Defaults to `'Others'`. */
   otherLabel?: string
-  /** Count text with `{count}` placeholder. Defaults to `'{count} more'`. */
+  /** Count text with `{count}` placeholder. Defaults to `'{count}'`. */
   otherCountLabel?: string
+  /**
+   * When provided, the row becomes a button: clicking it (or Enter/Space)
+   * fires `onShowAll`, expanding the widget to reveal every category. When
+   * omitted the row renders as a static, non-interactive summary.
+   */
+  onShowAll?: () => void
+  /** Tooltip shown over the button form. Defaults to `'Show all'`. */
+  showAllLabel?: string
 }
 
 /**
- * Static "Other (X more)" overflow summary row. Rendered after the last
- * visible category row when `data.length > maxItems`. Non-interactive —
- * no selection, no keyboard target.
+ * Overflow summary row rendered after the last visible category row when
+ * `data.length > maxItems`. Shows `Others <count>` (count muted, no
+ * parentheses).
+ *
+ * When `onShowAll` is supplied the row is an interactive button — clicking
+ * it (or Enter/Space) expands the widget to show all categories, mirroring
+ * the Searcher's full-list view. Without `onShowAll` it stays a static,
+ * non-interactive summary (backward-compatible default).
  */
 export function CategoryRowOther({
   hiddenCount,
-  otherLabel = 'Other',
-  otherCountLabel = '{count} more',
+  otherLabel = 'Others',
+  otherCountLabel = '{count}',
+  onShowAll,
+  showAllLabel = 'Show all',
 }: CategoryRowOtherProps) {
   const countText = otherCountLabel.replace('{count}', String(hiddenCount))
+
+  const count = (
+    <Typography variant='body2' sx={styles.otherCount}>
+      {countText}
+    </Typography>
+  )
+
+  if (!onShowAll) {
+    return (
+      <Box sx={styles.otherRow}>
+        <Typography variant='body2' sx={styles.otherLabel}>
+          {otherLabel}
+        </Typography>
+        {count}
+      </Box>
+    )
+  }
+
+  const handleKey = (e: KeyboardEvent<HTMLSpanElement>): void => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault()
+      onShowAll()
+    }
+  }
+
+  // Only the label is the click target; the count stays static beside it.
   return (
     <Box sx={styles.otherRow}>
-      <Typography variant='body2' sx={styles.otherLabel}>
-        {otherLabel}
-      </Typography>
-      <Typography variant='body2' sx={styles.otherCount}>
-        ({countText})
-      </Typography>
+      <Tooltip title={showAllLabel}>
+        <Typography
+          variant='body2'
+          component='span'
+          role='button'
+          tabIndex={0}
+          onClick={onShowAll}
+          onKeyDown={handleKey}
+          sx={{ ...styles.otherLabel, ...styles.otherLabelButton }}
+        >
+          {otherLabel}
+        </Typography>
+      </Tooltip>
+      {count}
     </Box>
   )
 }

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

@@ -78,6 +78,13 @@ export const styles = {
     gap: 1,
     py: 0.5,
   },
+  // Layered on `list` only in scroll mode (`maxItems === 0`): right padding
+  // so the bars + right-aligned values clear the scrollbar. Right side only
+  // — the left edge stays at 0 so content stays aligned with the capped
+  // view. `overflowY` + the dynamic `maxHeight` remain on the inline style.
+  listScroll: {
+    pr: 1,
+  },
 
   // ── Single-series row ─────────────────────────────────────────────
   // v1 layout: label + value share a top flex row (justify-between); the
@@ -266,20 +273,44 @@ export const styles = {
   },
 
   // ── "Other" overflow row ──────────────────────────────────────────
+  // Left-aligned `Others <count>` — the label sits next to a muted count
+  // (no parentheses). Only the label is the click target when interactive;
+  // the count is always static text beside it.
   otherRow: {
     display: 'flex',
-    justifyContent: 'space-between',
     alignItems: 'center',
+    gap: 1,
     py: 0.5,
     px: 0.5,
   },
+  // Interactive affordances layered onto the "Others" label only (cursor,
+  // hover tint, focus ring). A negative LEFT margin + matching padding keep
+  // the hover pill breathing without shifting the label's text edge (it
+  // stays aligned with the category rows above). No right margin, so the
+  // row `gap` is preserved between the pill and the count.
+  otherLabelButton: {
+    cursor: 'pointer',
+    userSelect: 'none',
+    borderRadius: 1,
+    px: 0.5,
+    ml: -0.5,
+    transition: 'background-color 80ms ease',
+    '&:hover': {
+      bgcolor: 'action.hover',
+    },
+    '&:focus-visible': {
+      outline: '2px solid',
+      outlineColor: 'primary.main',
+      outlineOffset: 2,
+    },
+  },
   otherLabel: {
-    fontStyle: 'italic',
-    color: 'text.secondary',
+    color: 'text.primary',
     fontWeight: 'medium',
   },
   otherCount: {
-    color: 'text.disabled',
+    color: 'text.secondary',
+    fontVariantNumeric: 'tabular-nums',
   },
   // `bar` / `barFill` are size-keyed (`Record<CategorySize, SxProps>`);
   // every other entry is a single `SxProps<Theme>`. The mixed shape means

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

@@ -47,6 +47,8 @@ export type CategorySeriesConfig = WidgetSeries
 export interface CategoryLabels {
   other?: string
   otherCount?: string
+  /** Tooltip shown over the clickable "Others" row. Defaults to `'Show all'`. */
+  showAll?: string
 }
 
 /**

package/src/widgets-v2/index.ts

@@ -22,6 +22,7 @@ import {
   Searcher,
   SearcherToggle,
   StackToggle,
+  ShowAllToggle,
   ZoomToggle,
   BrushToggle,
   RelativeData,
@@ -83,6 +84,7 @@ export const Widget = {
   Searcher,
   SearcherToggle,
   StackToggle,
+  ShowAllToggle,
   ZoomToggle,
   BrushToggle,
   RelativeData,
@@ -149,6 +151,7 @@ export type {
   SearcherProps,
   SearcherToggleProps,
   StackToggleProps,
+  ShowAllToggleProps,
   ZoomToggleProps,
   BrushToggleProps,
   RelativeDataProps,

package/src/widgets-v2/selection-summary/labels.ts

@@ -1,11 +1,15 @@
+import type { ReactNode } from 'react'
+
 export interface SelectionSummaryLabels {
-  allSelected: string
-  selections: (count: number) => string
+  /**
+   * Optional custom renderer for the count. Defaults to the built-in two-tone
+   * `selected / total` rendering. Receives the already-resolved displayed
+   * number (which equals `total` when nothing is selected).
+   */
+  summary?: (selected: number, total: number) => ReactNode
   clear: string
 }
 
 export const DEFAULT_SELECTION_SUMMARY_LABELS: SelectionSummaryLabels = {
-  allSelected: 'All selected',
-  selections: (count) => `${count} selected`,
   clear: 'Clear',
 }

package/src/widgets-v2/selection-summary/selection-summary.test.tsx

@@ -9,15 +9,22 @@ describe('<SelectionSummary>', () => {
     expect(container.textContent).toBe('')
   })
 
-  it('renders the "All selected" label when count === 0 and total > 0 (R34)', () => {
+  it('renders nothing when total is omitted (undefined)', () => {
+    const { container } = render(<SelectionSummary count={0} />)
+    expect(container.textContent).toBe('')
+  })
+
+  it('renders total / total when nothing is selected (count === 0)', () => {
     render(<SelectionSummary count={0} total={10} />)
-    expect(screen.getByText('All selected')).toBeTruthy()
+    expect(screen.getByLabelText('10 / 10')).toBeTruthy()
+    // No Clear button when nothing is selected.
+    expect(screen.queryByText('Clear')).toBeNull()
   })
 
-  it('renders the count + Clear link when count > 0', () => {
+  it('renders count / total + Clear when count > 0', () => {
     const onClear = vi.fn()
     render(<SelectionSummary count={3} total={10} onClear={onClear} />)
-    expect(screen.getByText(/3/)).toBeTruthy()
+    expect(screen.getByLabelText('3 / 10')).toBeTruthy()
     fireEvent.click(screen.getByText('Clear'))
     expect(onClear).toHaveBeenCalledTimes(1)
   })
@@ -27,24 +34,23 @@ describe('<SelectionSummary>', () => {
     expect(screen.queryByText('Clear')).toBeNull()
   })
 
-  it('honors custom labels for empty + populated + clear', () => {
+  it('honors a custom summary renderer and clear label', () => {
     render(
       <SelectionSummary
         count={3}
         total={10}
         labels={{
-          allSelected: 'Showing all',
-          selections: (n) => `${n} pinned`,
+          summary: (selected, total) => `${selected} of ${total} pinned`,
           clear: 'Reset',
         }}
         onClear={() => undefined}
       />,
     )
-    expect(screen.getByText('3 pinned')).toBeTruthy()
+    expect(screen.getByText('3 of 10 pinned')).toBeTruthy()
     expect(screen.getByText('Reset')).toBeTruthy()
   })
 
-  it('renders the custom icon component when provided in the empty state', () => {
+  it('renders the custom icon component when provided', () => {
     const { container } = render(
       <SelectionSummary count={0} total={10} icon={StarIcon} />,
     )

package/src/widgets-v2/selection-summary/selection-summary.tsx

@@ -9,9 +9,9 @@ import { styles } from './style'
 export interface SelectionSummaryProps {
   /** Number of currently selected items. */
   count: number
-  /** Optional total — when 0 the component renders nothing (no data to summarize). */
+  /** Optional total — when `undefined` or `0` the component renders nothing (no data). */
   total?: number
-  /** Clear callback. Shown only when count > 0. */
+  /** Clear callback. The Clear control is shown only when `count > 0` and `onClear` is provided. */
   onClear?: () => void
   labels?: Partial<SelectionSummaryLabels>
   icon?: ComponentType<SvgIconProps>
@@ -19,11 +19,18 @@ export interface SelectionSummaryProps {
 }
 
 /**
+ * Renders a `selected / total` count.
+ *
  * Render rules:
- *   - `total === 0` → render nothing.
- *   - `count === 0` → render `labels.allSelected` (matches v1 default),
- *     prefixed with the optional `icon` glyph when provided.
- *   - `count > 0`   → render `labels.selections(count)` + Clear (when `onClear`).
+ *   - `!total` (undefined or 0) → render nothing (no data to summarize).
+ *   - `count === 0` → display `total / total` (everything is implicitly in
+ *     scope); no Clear button.
+ *   - `count > 0` → display `count / total` + Clear (when `onClear` is given).
+ *
+ * The count is two-tone by default (selected number bold/`text.primary`,
+ * ` / total` in `text.secondary`). Pass `labels.summary` to render a custom
+ * node instead — it receives the already-resolved displayed number (which
+ * equals `total` when nothing is selected).
  */
 export function SelectionSummary({
   count,
@@ -33,26 +40,39 @@ export function SelectionSummary({
   icon: Icon,
   iconProps,
 }: SelectionSummaryProps) {
-  if (total === 0) return null
+  if (!total) return null
   const _labels = { ...DEFAULT_SELECTION_SUMMARY_LABELS, ...labels }
-
-  if (count === 0) {
-    return (
-      <Box sx={styles.root}>
-        {Icon ? <Icon fontSize='small' {...iconProps} /> : null}
-        <Typography variant='caption' sx={styles.label}>
-          {_labels.allSelected}
-        </Typography>
-      </Box>
-    )
-  }
+  const shown = count === 0 ? total : count
 
   return (
     <Box sx={styles.root}>
-      <Typography variant='caption' sx={styles.label}>
-        {_labels.selections(count)}
-      </Typography>
-      {onClear && (
+      {Icon ? <Icon fontSize='small' {...iconProps} /> : null}
+      <Box
+        component='span'
+        sx={styles.count}
+        aria-label={`${shown} / ${total}`}
+      >
+        {_labels.summary ? (
+          _labels.summary(shown, total)
+        ) : (
+          <>
+            <Typography component='span' variant='caption' sx={styles.selected}>
+              {shown}
+            </Typography>
+            <Typography
+              component='span'
+              variant='caption'
+              sx={styles.separator}
+            >
+              /
+            </Typography>
+            <Typography component='span' variant='caption' sx={styles.total}>
+              {total}
+            </Typography>
+          </>
+        )}
+      </Box>
+      {count > 0 && onClear && (
         <Button size='small' variant='text' onClick={onClear}>
           {_labels.clear}
         </Button>

package/src/widgets-v2/selection-summary/style.ts

@@ -10,6 +10,21 @@ export const styles = {
   label: {
     color: 'text.secondary',
   },
+  count: {
+    display: 'inline-flex',
+    alignItems: 'baseline',
+    gap: 0.5,
+  },
+  selected: {
+    color: 'text.primary',
+    fontWeight: 600,
+  },
+  separator: {
+    color: 'text.secondary',
+  },
+  total: {
+    color: 'text.secondary',
+  },
   clear: {
     color: 'primary.main',
     cursor: 'pointer',