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

package/src/legend/components/legend-group-menu/legend-group-menu-items.tsx

@@ -0,0 +1,132 @@
+import type { MouseEvent } from 'react'
+import { CircularProgress, MenuItem } from '@mui/material'
+import {
+  getLegendStore,
+  selectAllGroupsCollapsed,
+  selectGroupVisibility,
+  selectHasGroups,
+  selectLayersByGroup,
+  selectOrderedGroups,
+  useLegendId,
+  useLegendStore,
+} from '../../stores'
+import { useLegendConfig } from '../../provider'
+import { useLegendGroupId, useLegendMenu } from '../contexts'
+import { runAsyncMenuAction } from '../run-async-menu-action'
+
+/**
+ * Show only this group (hide all other layers).
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendShowOnlyGroup() {
+  const id = useLegendId()
+  const groupId = useLegendGroupId()
+  const { labels } = useLegendConfig()
+
+  if (groupId === null) return null
+
+  const showOnly = () => {
+    const state = getLegendStore(id).getState()
+    for (const group of selectOrderedGroups(state)) {
+      state.setGroupVisibility(group.id, group.id === groupId)
+    }
+    // Exclusive: the ungrouped layers hide too.
+    for (const layer of selectLayersByGroup(state, undefined)) {
+      state.setVisibility(layer.id, false)
+    }
+  }
+
+  return <MenuItem onClick={showOnly}>{labels.showOnlyGroup}</MenuItem>
+}
+
+/**
+ * Show every layer (panel-level `Legend.PanelMenu` only).
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendShowAllGroups() {
+  const id = useLegendId()
+  const hasGroups = useLegendStore(id, selectHasGroups)
+  const { labels } = useLegendConfig()
+
+  if (!hasGroups) return null
+
+  const showAll = () => {
+    const state = getLegendStore(id).getState()
+    for (const group of selectOrderedGroups(state)) {
+      state.setGroupVisibility(group.id, true)
+    }
+    for (const layer of selectLayersByGroup(state, undefined)) {
+      state.setVisibility(layer.id, true)
+    }
+  }
+
+  return <MenuItem onClick={showAll}>{labels.showAllGroups}</MenuItem>
+}
+
+/**
+ * Collapse / expand all groups (panel-level `Legend.PanelMenu` only).
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendCollapseAllGroups() {
+  const id = useLegendId()
+  const hasGroups = useLegendStore(id, selectHasGroups)
+  const allCollapsed = useLegendStore(id, selectAllGroupsCollapsed)
+  const { labels } = useLegendConfig()
+
+  if (!hasGroups) return null
+
+  const toggleAll = () => {
+    const state = getLegendStore(id).getState()
+    const collapsed = selectAllGroupsCollapsed(state)
+    for (const group of selectOrderedGroups(state)) {
+      state.setGroupCollapsed(group.id, !collapsed)
+    }
+  }
+
+  return (
+    <MenuItem onClick={toggleAll}>
+      {allCollapsed ? labels.expandAllGroups : labels.collapseAllGroups}
+    </MenuItem>
+  )
+}
+
+export interface LegendZoomToGroupProps {
+  /** Fit viewport to the group; may return a Promise for async menu feedback. */
+  onZoomTo: (groupId: string) => void | Promise<void>
+}
+
+/**
+ * Zoom-to-group menu item for `Legend.GroupMenu`. Self-hides when all members are hidden.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendZoomToGroup({ onZoomTo }: LegendZoomToGroupProps) {
+  const id = useLegendId()
+  const groupId = useLegendGroupId()
+  const menu = useLegendMenu()
+  const hidden = useLegendStore(
+    id,
+    (s) => groupId !== null && selectGroupVisibility(s, groupId) === 'hidden',
+  )
+  const { labels } = useLegendConfig()
+
+  if (groupId === null || hidden) return null
+
+  const busy = menu?.busy ?? false
+
+  const handleClick = (e: MouseEvent) => {
+    e.stopPropagation()
+    if (!menu) return
+    void runAsyncMenuAction(menu, () => onZoomTo(groupId))
+  }
+
+  return (
+    <MenuItem disabled={busy} onClick={handleClick}>
+      {busy && <CircularProgress size={16} sx={{ mr: 1 }} />}
+      {busy ? labels.loading : labels.zoomToGroup}
+    </MenuItem>
+  )
+}

package/src/legend/components/legend-group-menu/legend-group-menu.tsx

@@ -0,0 +1,25 @@
+import type { ReactNode } from 'react'
+import { useLegendConfig } from '../../provider'
+import { useLegendGroupId } from '../contexts'
+import { LegendOverflowMenu } from '../legend-overflow-menu/legend-overflow-menu'
+
+export interface LegendGroupMenuProps {
+  /** Menu items; async items use `stopPropagation` + `runAsyncMenuAction`. */
+  children?: ReactNode
+}
+
+/**
+ * Overflow (⋮) menu for a group header. Renders nothing outside a `Legend.Group`.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendGroupMenu({ children }: LegendGroupMenuProps) {
+  const groupId = useLegendGroupId()
+  const { labels } = useLegendConfig()
+
+  return (
+    <LegendOverflowMenu gate={groupId !== null} ariaLabel={labels.groupOptions}>
+      {children}
+    </LegendOverflowMenu>
+  )
+}

package/src/legend/components/legend-icon/legend-icon-ui.tsx

@@ -0,0 +1,56 @@
+import { Box, Typography } from '@mui/material'
+import { styles } from './styles'
+import type { LegendIconVariable } from '../../stores'
+
+export interface LegendIconUIProps {
+  data: LegendIconVariable
+}
+
+/**
+ * Icon legend — a list of icon images with labels (and optional values).
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendIconUI({ data }: LegendIconUIProps) {
+  const orientation = data.orientation ?? 'vertical'
+  const horizontal = orientation === 'horizontal'
+
+  return (
+    <Box
+      data-orientation={orientation}
+      sx={{ ...styles.list, ...(horizontal ? styles.listHorizontal : null) }}
+    >
+      {data.items.map((item, index) => (
+        <Box
+          key={`${item.label}-${index}`}
+          sx={{
+            ...styles.item,
+            ...(horizontal ? styles.itemHorizontal : null),
+          }}
+        >
+          <Box component='img' src={item.icon} alt='' sx={styles.icon} />
+          <Typography
+            variant='caption'
+            color='text.primary'
+            sx={{
+              ...styles.label,
+              ...(horizontal ? styles.labelHorizontal : null),
+            }}
+          >
+            {item.label}
+          </Typography>
+          {item.value != null && (
+            <Typography
+              className='PsLegend-value'
+              variant='caption'
+              color='text.secondary'
+              sx={styles.value}
+            >
+              {item.value}
+            </Typography>
+          )}
+        </Box>
+      ))}
+    </Box>
+  )
+}

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

@@ -0,0 +1,56 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  list: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 0.5,
+    // Values are hidden until the legend content is hovered (or keyboard-
+    // focused). On hover-incapable (touch) devices they're always visible —
+    // tap-:hover is unreliable on non-interactive elements.
+    '&:hover .PsLegend-value, &:focus-within .PsLegend-value': {
+      opacity: 1,
+    },
+    '@media (hover: none)': {
+      '& .PsLegend-value': { opacity: 1 },
+    },
+  },
+  item: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 1,
+  },
+  icon: {
+    flexShrink: 0,
+    width: 16,
+    height: 16,
+    objectFit: 'contain',
+  },
+  label: {
+    flex: 1,
+    minWidth: 0,
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+  },
+  value: {
+    flexShrink: 0,
+    opacity: 0,
+    transition: 'opacity 120ms',
+  },
+  // ─── Horizontal orientation modifiers (spread over the vertical base) ───
+  listHorizontal: {
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    columnGap: 2,
+    rowGap: 0.5,
+  },
+  itemHorizontal: {
+    gap: 0.5,
+  },
+  labelHorizontal: {
+    flex: '0 0 auto',
+    overflow: 'visible',
+    textOverflow: 'clip',
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/legend/components/legend-item/legend-item-ui.test.tsx

@@ -0,0 +1,362 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { formatNumber } from '@carto/ps-utils'
+import { LegendItemUI } from './legend-item-ui'
+import { LegendRampUI } from '../legend-ramp/legend-ramp-ui'
+import { LegendProportionUI } from '../legend-proportion/legend-proportion-ui'
+import type {
+  LegendCategoryVariable,
+  LegendIconVariable,
+  LegendProportionVariable,
+  LegendRampVariable,
+} from '../../stores'
+
+describe('<LegendItemUI> dispatch', () => {
+  it('renders the category renderer', () => {
+    const data: LegendCategoryVariable = {
+      type: 'category',
+      items: [{ label: 'A', color: '#000' }],
+    }
+    render(<LegendItemUI data={data} />)
+    expect(screen.getByText('A')).toBeTruthy()
+  })
+
+  it('renders the icon renderer', () => {
+    const data: LegendIconVariable = {
+      type: 'icon',
+      items: [{ label: 'Store', icon: 'x.svg' }],
+    }
+    const { container } = render(<LegendItemUI data={data} />)
+    expect(screen.getByText('Store')).toBeTruthy()
+    expect(container.querySelector('img')).toBeTruthy()
+  })
+
+  it('exposes the orientation on the list (default vertical, opt-in horizontal)', () => {
+    const category: LegendCategoryVariable = {
+      type: 'category',
+      items: [
+        { label: 'A', color: '#111' },
+        { label: 'B', color: '#222' },
+      ],
+    }
+    const { container, rerender } = render(<LegendItemUI data={category} />)
+    expect(
+      container.querySelector('[data-orientation="vertical"]'),
+    ).toBeTruthy()
+
+    rerender(<LegendItemUI data={{ ...category, orientation: 'horizontal' }} />)
+    expect(
+      container.querySelector('[data-orientation="horizontal"]'),
+    ).toBeTruthy()
+    // Both items still render in horizontal mode.
+    expect(screen.getByText('A')).toBeTruthy()
+    expect(screen.getByText('B')).toBeTruthy()
+
+    // Icon legend honors the same flag.
+    const icon: LegendIconVariable = {
+      type: 'icon',
+      orientation: 'horizontal',
+      items: [{ label: 'Store', icon: 'x.svg' }],
+    }
+    rerender(<LegendItemUI data={icon} />)
+    expect(
+      container.querySelector('[data-orientation="horizontal"]'),
+    ).toBeTruthy()
+    expect(screen.getByText('Store')).toBeTruthy()
+  })
+
+  it('renders category and icon values verbatim — the consumer pre-formats', () => {
+    // A plain pre-formatted string (e.g. a percent) renders as-is.
+    const category: LegendCategoryVariable = {
+      type: 'category',
+      items: [{ label: 'A', color: '#000', value: '12%' }],
+    }
+    const { rerender } = render(<LegendItemUI data={category} />)
+    expect(screen.getByText('12%')).toBeTruthy()
+
+    // An arbitrary node is allowed too.
+    rerender(
+      <LegendItemUI
+        data={{
+          type: 'category',
+          items: [{ label: 'A', color: '#000', value: <strong>1.2K</strong> }],
+        }}
+      />,
+    )
+    expect(screen.getByText('1.2K').tagName).toBe('STRONG')
+
+    const icon: LegendIconVariable = {
+      type: 'icon',
+      items: [{ label: 'Store', icon: 'x.svg', value: '5.6M' }],
+    }
+    rerender(<LegendItemUI data={icon} />)
+    expect(screen.getByText('5.6M')).toBeTruthy()
+  })
+
+  it('passes the variable shape + pattern through to the swatch', () => {
+    const data: LegendCategoryVariable = {
+      type: 'category',
+      shape: 'square',
+      fillPattern: 'dots',
+      items: [
+        { label: 'A', color: '#111' },
+        { label: 'B', color: '#222' },
+      ],
+    }
+    const { container } = render(<LegendItemUI data={data} />)
+    const swatches = container.querySelectorAll('svg')
+    expect(swatches).toHaveLength(2)
+    expect(swatches[0]!.getAttribute('data-shape')).toBe('square')
+    expect(container.querySelector('pattern')).toBeTruthy()
+  })
+
+  it('items override the variable-level swatch style (mixed list)', () => {
+    const data: LegendCategoryVariable = {
+      type: 'category',
+      shape: 'square',
+      fillPattern: 'solid', // variable default
+      items: [
+        { label: 'Solid', color: '#111' },
+        { label: 'Dotted', color: '#222', fillPattern: 'dots' },
+        { label: 'Line', color: '#333', shape: 'line' },
+        { label: 'Outline', color: '#444', isStrokeColor: true },
+      ],
+    }
+    const { container } = render(<LegendItemUI data={data} />)
+    const swatches = Array.from(container.querySelectorAll('svg'))
+    expect(swatches.map((s) => s.getAttribute('data-shape'))).toEqual([
+      'square',
+      'square',
+      'line',
+      'square',
+    ])
+    // Only the dots-override item emits a fill <pattern>.
+    expect(container.querySelectorAll('pattern')).toHaveLength(1)
+    expect(swatches[1]!.querySelector('pattern')).toBeTruthy()
+    // The isStrokeColor-override item strokes instead of fills.
+    const outlineRect = swatches[3]!.querySelector('rect')!
+    expect(outlineRect.getAttribute('fill')).toBe('none')
+    expect(outlineRect.getAttribute('stroke')).toBe('#444')
+  })
+})
+
+describe('<LegendRampUI> ordering (regression)', () => {
+  it('boundary contract: N+1 stops label the lines between N colors, in order', () => {
+    const data: LegendRampVariable = {
+      type: 'ramp',
+      isContinuous: false,
+      colors: ['#aaa', '#bbb', '#ccc'],
+      stops: [
+        { label: 'a', value: 0 },
+        { label: 'b', value: 1 },
+        { label: 'c', value: 2 },
+        { label: 'd', value: 3 },
+      ],
+    }
+    render(<LegendRampUI data={data} />)
+    // One step per color; each step's accessible name is its boundary range,
+    // in low→high order — colors and labels never reversed.
+    const steps = screen.getAllByRole('img')
+    expect(steps.map((s) => s.getAttribute('aria-label'))).toEqual([
+      'a – b',
+      'b – c',
+      'c – d',
+    ])
+    // Every boundary label renders; the outer two clamp inside the bar
+    // (no transform / right-aligned) while interior ones stay centered.
+    for (const label of ['a', 'b', 'c', 'd']) {
+      expect(screen.getByText(label)).toBeTruthy()
+    }
+    expect(screen.getByText('a').style.transform).toBe('')
+    expect(screen.getByText('b').style.transform).toBe('translateX(-50%)')
+    expect(screen.getByText('c').style.transform).toBe('translateX(-50%)')
+    expect(screen.getByText('d').style.transform).toBe('translateX(-100%)')
+    expect(screen.getByText('d').style.left).toBe('100%')
+  })
+
+  it('invalid discrete (stops ≠ colors + 1) renders an error, not a bar', () => {
+    const data: LegendRampVariable = {
+      type: 'ramp',
+      isContinuous: false,
+      colors: ['#aaa', '#bbb', '#ccc'], // 3 colors → needs 4 stops
+      stops: [
+        { label: 'low', value: 0 },
+        { label: 'mid', value: 1 },
+        { label: 'high', value: 2 },
+      ],
+      attribute: 'income',
+    }
+    render(<LegendRampUI data={data} />)
+    // The incoherent state shows an error message with the expected counts…
+    expect(screen.getByText(/needs 4 stops .* but got 3/)).toBeTruthy()
+    // …the attribute header stays for context…
+    expect(screen.getByText('income')).toBeTruthy()
+    // …and no bar/steps render.
+    expect(screen.queryAllByRole('img')).toHaveLength(0)
+    expect(screen.queryByText('low')).toBeNull()
+  })
+
+  it('renders the avg marker at its linear position with a formatted tooltip', () => {
+    const data: LegendRampVariable = {
+      type: 'ramp',
+      isContinuous: true,
+      colors: ['#aaa', '#ccc'],
+      stops: [
+        { label: '0', value: 0 },
+        { label: '100', value: 100 },
+      ],
+      avg: 25,
+    }
+    render(<LegendRampUI data={data} />)
+    // MUI Tooltip exposes its (string) title as the child's accessible name.
+    const line = screen.getByLabelText('25')
+    expect(line.style.left).toBe('25%')
+  })
+
+  it('clamps an out-of-range avg to the bar edge; hides it without a scale', () => {
+    const base: LegendRampVariable = {
+      type: 'ramp',
+      isContinuous: true,
+      colors: ['#aaa', '#ccc'],
+      stops: [
+        { label: '0', value: 0 },
+        { label: '100', value: 100 },
+      ],
+      avg: 500,
+    }
+    const { rerender } = render(<LegendRampUI data={base} />)
+    expect(screen.getByLabelText('500').style.left).toBe('100%')
+
+    // Zero-width range → no scale → no marker.
+    rerender(
+      <LegendRampUI
+        data={{
+          ...base,
+          stops: [
+            { label: 'x', value: 5 },
+            { label: 'x', value: 5 },
+          ],
+        }}
+      />,
+    )
+    expect(screen.queryByLabelText('500')).toBeNull()
+  })
+
+  it('renders a continuous gradient bar instead of steps', () => {
+    const data: LegendRampVariable = {
+      type: 'ramp',
+      isContinuous: true,
+      colors: ['#aaa', '#ccc'],
+      stops: [
+        { label: '0', value: 0 },
+        { label: '10', value: 10 },
+      ],
+    }
+    render(<LegendRampUI data={data} />)
+    // The gradient bar is the only role=img element; no discrete steps.
+    const imgs = screen.getAllByRole('img')
+    expect(imgs).toHaveLength(1)
+    expect(imgs[0]!.getAttribute('aria-label')).toBe('Color gradient')
+  })
+})
+
+describe('<LegendProportionUI>', () => {
+  // The MAX/MIN labels render the prefix and the formatted value as separate
+  // text nodes, so match on the element's full textContent.
+  const fullText =
+    (text: string) =>
+    (_content: string, el: Element | null): boolean =>
+      el?.textContent === text
+  const compact = (value: number): string => formatNumber(value, 'en-US')
+
+  it('labels the breaks with MAX/MIN prefixes via the supplied formatValue', () => {
+    const data: LegendProportionVariable = {
+      type: 'proportion',
+      min: 13_000,
+      max: 36_000_000,
+      stops: [36_000_000, 310_000, 110_000, 13_000],
+      formatValue: compact,
+    }
+    const { container } = render(<LegendProportionUI data={data} />)
+    expect(screen.getByText(fullText('MAX: 36M'))).toBeTruthy()
+    expect(screen.getByText(fullText('MIN: 13K'))).toBeTruthy()
+    // Middle breaks are bare (single text node).
+    expect(screen.getByText('310K')).toBeTruthy()
+    expect(screen.getByText('110K')).toBeTruthy()
+    // One decorative circle per break; no dashed tick connectors.
+    expect(container.querySelectorAll('[aria-hidden="true"]')).toHaveLength(4)
+  })
+
+  it('defaults to String(value) when no formatValue is given', () => {
+    const data: LegendProportionVariable = {
+      type: 'proportion',
+      min: 0,
+      max: 36_000_000,
+      stops: [36_000_000, 13_000],
+    }
+    render(<LegendProportionUI data={data} />)
+    expect(screen.getByText(fullText('MAX: 36000000'))).toBeTruthy()
+    expect(screen.getByText(fullText('MIN: 13000'))).toBeTruthy()
+  })
+
+  it('clamps `steps` to 2–4 and regenerates the values dynamically', () => {
+    const data: LegendProportionVariable = {
+      type: 'proportion',
+      min: 0,
+      max: 100,
+      steps: 6, // clamped to 4
+    }
+    const { container, rerender } = render(<LegendProportionUI data={data} />)
+    expect(container.querySelectorAll('[aria-hidden="true"]')).toHaveLength(4)
+
+    rerender(<LegendProportionUI data={{ ...data, steps: 1 }} />) // clamped to 2
+    expect(container.querySelectorAll('[aria-hidden="true"]')).toHaveLength(2)
+    // Values follow the step count: only the endpoints remain.
+    expect(screen.getByText(fullText('MAX: 100'))).toBeTruthy()
+    expect(screen.getByText(fullText('MIN: 0'))).toBeTruthy()
+
+    rerender(<LegendProportionUI data={{ ...data, steps: 3 }} />)
+    expect(container.querySelectorAll('[aria-hidden="true"]')).toHaveLength(3)
+    expect(screen.getByText('50')).toBeTruthy() // dynamic middle break
+  })
+
+  it('caps explicit stops at the 4 largest; circles match labels 1:1', () => {
+    const data: LegendProportionVariable = {
+      type: 'proportion',
+      min: 0,
+      max: 500,
+      stops: [500, 400, 300, 200, 100], // 5 stops → 4 largest kept
+      steps: 2, // ignored when stops are provided
+    }
+    const { container } = render(<LegendProportionUI data={data} />)
+    expect(container.querySelectorAll('[aria-hidden="true"]')).toHaveLength(4)
+    expect(screen.getByText(fullText('MAX: 500'))).toBeTruthy()
+    expect(screen.getByText(fullText('MIN: 200'))).toBeTruthy() // smallest shown
+    expect(screen.queryByText('100')).toBeNull() // dropped
+  })
+
+  it('falls back to evenly-spaced breaks from min/max when stops omitted', () => {
+    const data: LegendProportionVariable = {
+      type: 'proportion',
+      min: 0,
+      max: 1000,
+      steps: 3,
+      formatValue: compact,
+    }
+    render(<LegendProportionUI data={data} />)
+    expect(screen.getByText(fullText('MAX: 1K'))).toBeTruthy()
+    expect(screen.getByText(fullText('MIN: 0'))).toBeTruthy()
+  })
+
+  it('renders the "Radius range by" attribute header when set', () => {
+    const data: LegendProportionVariable = {
+      type: 'proportion',
+      min: 1,
+      max: 10,
+      attribute: 'revenue',
+    }
+    render(<LegendProportionUI data={data} />)
+    expect(screen.getByText('Radius range by')).toBeTruthy()
+    expect(screen.getByText('revenue')).toBeTruthy()
+  })
+})

package/src/legend/components/legend-item/legend-item-ui.tsx

@@ -0,0 +1,43 @@
+import { LegendCategoryUI } from '../legend-category/legend-category-ui'
+import { LegendRampUI } from '../legend-ramp/legend-ramp-ui'
+import { LegendProportionUI } from '../legend-proportion/legend-proportion-ui'
+import { LegendIconUI } from '../legend-icon/legend-icon-ui'
+import type { LegendLabels } from '../../provider/labels'
+import type { LegendVariable } from '../../stores'
+
+export interface LegendItemUIProps {
+  data: LegendVariable
+  /** Forwarded to the renderers that show text (ramp header, proportion labels). */
+  labels?: Pick<
+    LegendLabels,
+    | 'colorBasedOn'
+    | 'colorGradient'
+    | 'radiusRangeBy'
+    | 'maxPrefix'
+    | 'minPrefix'
+  >
+}
+
+/**
+ * Dispatches to the matching pure renderer based on the discriminated
+ * `variables.type`. Adding a new legend type is localized to this switch.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendItemUI({ data, labels }: LegendItemUIProps) {
+  switch (data.type) {
+    case 'category':
+      return <LegendCategoryUI data={data} />
+    case 'ramp':
+      return <LegendRampUI data={data} labels={labels} />
+    case 'proportion':
+      return <LegendProportionUI data={data} labels={labels} />
+    case 'icon':
+      return <LegendIconUI data={data} />
+    default: {
+      // Exhaustiveness guard — a new variant must be handled above.
+      const _exhaustive: never = data
+      return _exhaustive
+    }
+  }
+}