@carto/ps-react-ui 5.0.0-widgets.9 → 5.1.0

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

@@ -0,0 +1,237 @@
+import { useId } from 'react'
+import type {
+  LegendFillPattern,
+  LegendStrokeStyle,
+  LegendSwatchShape,
+} from '../../stores'
+
+export interface LegendSwatchProps {
+  /** Shape to render. Default `'circle'`. */
+  shape?: LegendSwatchShape
+  /** CSS color string (hex / rgb / named). */
+  color: string
+  /** Paint the outline/border instead of the fill (square/circle only). */
+  isStrokeColor?: boolean
+  /** Fill pattern when filled. Default `'solid'`. */
+  fillPattern?: LegendFillPattern
+  /** Border style (stroked square/circle) or line style (`shape: 'line'`). Default `'solid'`. */
+  strokeStyle?: LegendStrokeStyle
+  /** Primary dimension in px (square side / circle diameter / line length). Default 12. */
+  size?: number
+}
+
+/** Default swatch dimension in px — shared with the category renderer. */
+export const DEFAULT_SWATCH_SIZE = 12
+
+const STROKE_WIDTH = 1.5
+const LINE_WIDTH = 2
+const HAIRLINE = 1
+
+/** Dash array for stroked square/circle borders. */
+function borderDash(style: LegendStrokeStyle): {
+  dash?: string
+  round?: boolean
+} {
+  switch (style) {
+    case 'dashed':
+      return { dash: '3 2' }
+    case 'dotted':
+      return { dash: `0.1 ${STROKE_WIDTH * 2}`, round: true }
+    // `dash-dot` is line-only and `corners` is handled separately: both
+    // degrade to a solid border here.
+    default:
+      return {}
+  }
+}
+
+/** Dash array for `shape: 'line'`. */
+function lineDash(style: LegendStrokeStyle): {
+  dash?: string
+  round?: boolean
+} {
+  switch (style) {
+    case 'dashed':
+      return { dash: '4 3' }
+    case 'dotted':
+      return { dash: `0.1 ${LINE_WIDTH * 2}`, round: true }
+    case 'dash-dot':
+      return { dash: '5 2 0.1 2', round: true }
+    // `corners` is square-only → solid line.
+    default:
+      return {}
+  }
+}
+
+/** SVG children for a fill `<pattern>` tile, drawn in `color`. */
+function patternTile(pattern: LegendFillPattern, color: string) {
+  const line = (d: string) => (
+    <path d={d} stroke={color} strokeWidth={1.2} fill='none' />
+  )
+  switch (pattern) {
+    case 'horizontal':
+      return { size: 4, content: line('M0 2 H4') }
+    case 'vertical':
+      return { size: 4, content: line('M2 0 V4') }
+    case 'diagonal':
+      // "/" with wrap segments for a seamless tile.
+      return { size: 4, content: line('M0 4 L4 0 M-1 1 L1 -1 M3 5 L5 3') }
+    case 'diagonal-alt':
+      // "\"
+      return { size: 4, content: line('M0 0 L4 4 M-1 3 L1 5 M3 -1 L5 1') }
+    case 'cross':
+      return {
+        size: 4,
+        content: line(
+          'M0 4 L4 0 M-1 1 L1 -1 M3 5 L5 3 M0 0 L4 4 M-1 3 L1 5 M3 -1 L5 1',
+        ),
+      }
+    case 'dots':
+      return { size: 4, content: <circle cx={2} cy={2} r={0.9} fill={color} /> }
+    case 'grid':
+      return {
+        size: 3,
+        content: <circle cx={1.5} cy={1.5} r={0.7} fill={color} />,
+      }
+    default:
+      return null
+  }
+}
+
+/**
+ * A single legend swatch rendered as inline SVG: a square, circle, or line,
+ * painted as a solid/patterned fill or a styled outline. Pure and theme-free —
+ * `color` is a raw CSS color. Decorative (`aria-hidden`); the adjacent label
+ * carries the accessible text.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendSwatch({
+  shape = 'circle',
+  color,
+  isStrokeColor = false,
+  fillPattern = 'solid',
+  strokeStyle = 'solid',
+  size = DEFAULT_SWATCH_SIZE,
+}: LegendSwatchProps) {
+  const patternId = useId()
+
+  // ── Line ──────────────────────────────────────────────────────────────────
+  if (shape === 'line') {
+    const { dash, round } = lineDash(strokeStyle)
+    return (
+      <svg
+        width={size}
+        height={size}
+        viewBox={`0 0 ${size} ${size}`}
+        aria-hidden
+        data-shape='line'
+        style={{ display: 'block', overflow: 'visible' }}
+      >
+        <line
+          x1={0}
+          y1={size / 2}
+          x2={size}
+          y2={size / 2}
+          stroke={color}
+          strokeWidth={LINE_WIDTH}
+          strokeDasharray={dash}
+          strokeLinecap={round ? 'round' : 'butt'}
+        />
+      </svg>
+    )
+  }
+
+  // ── Square / circle ────────────────────────────────────────────────────────
+  const inset = isStrokeColor ? STROKE_WIDTH / 2 : 0
+  const usePattern = !isStrokeColor && fillPattern !== 'solid'
+  const tile = usePattern ? patternTile(fillPattern, color) : null
+
+  // corner-marks only apply to a stroked square.
+  const isCorners =
+    isStrokeColor && strokeStyle === 'corners' && shape === 'square'
+
+  const { dash, round } = isStrokeColor
+    ? borderDash(strokeStyle)
+    : { dash: undefined, round: false }
+
+  const commonStroke = {
+    stroke: color,
+    strokeWidth: isStrokeColor ? STROKE_WIDTH : HAIRLINE,
+    strokeDasharray: isStrokeColor ? dash : undefined,
+    strokeLinecap: round ? ('round' as const) : ('butt' as const),
+  }
+
+  const fill = isStrokeColor
+    ? 'none'
+    : usePattern
+      ? `url(#${patternId})`
+      : color
+
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox={`0 0 ${size} ${size}`}
+      aria-hidden
+      data-shape={shape}
+      style={{ display: 'block' }}
+    >
+      {tile && (
+        <defs>
+          <pattern
+            id={patternId}
+            patternUnits='userSpaceOnUse'
+            width={tile.size}
+            height={tile.size}
+          >
+            {tile.content}
+          </pattern>
+        </defs>
+      )}
+
+      {isCorners ? (
+        <CornerMarks size={size} color={color} />
+      ) : shape === 'circle' ? (
+        <circle
+          cx={size / 2}
+          cy={size / 2}
+          r={size / 2 - inset}
+          fill={fill}
+          {...commonStroke}
+          // A solid-color filled circle needs no border.
+          stroke={isStrokeColor || usePattern ? color : 'none'}
+        />
+      ) : (
+        <rect
+          x={inset}
+          y={inset}
+          width={size - inset * 2}
+          height={size - inset * 2}
+          fill={fill}
+          {...commonStroke}
+          stroke={isStrokeColor || usePattern ? color : 'none'}
+        />
+      )}
+    </svg>
+  )
+}
+
+/** Four L-shaped corner brackets for the `corners` border style (square). */
+function CornerMarks({ size, color }: { size: number; color: string }) {
+  const arm = Math.max(2, size * 0.3)
+  const o = STROKE_WIDTH / 2
+  const max = size - o
+  const props = {
+    stroke: color,
+    strokeWidth: STROKE_WIDTH,
+    fill: 'none',
+  }
+  return (
+    <>
+      <path d={`M${o} ${o + arm} V${o} H${o + arm}`} {...props} />
+      <path d={`M${max - arm} ${o} H${max} V${o + arm}`} {...props} />
+      <path d={`M${max} ${max - arm} V${max} H${max - arm}`} {...props} />
+      <path d={`M${o + arm} ${max} H${o} V${max - arm}`} {...props} />
+    </>
+  )
+}

package/src/legend/components/legend-visibility-toggle/legend-visibility-toggle.tsx

@@ -0,0 +1,133 @@
+import { useEffect } from 'react'
+import { IconButton } from '@mui/material'
+import {
+  VisibilityOutlined as VisibilityIcon,
+  VisibilityOffOutlined as VisibilityOffIcon,
+} from '@mui/icons-material'
+import { Tooltip } from '../../../components/tooltip/tooltip'
+import {
+  selectGroupVisibility,
+  useLegendId,
+  useLegendShallow,
+  useLegendStore,
+  type LegendVisibility,
+} from '../../stores'
+import { useLegendConfig } from '../../provider'
+import type { LegendLabels } from '../../provider/labels'
+import { VisibilityIndeterminateIcon } from '../icons'
+import { useLegendGroupId, useLegendRow } from '../contexts'
+
+const ICONS = {
+  visible: VisibilityIcon,
+  hidden: VisibilityOffIcon,
+  mixed: VisibilityIndeterminateIcon,
+} as const
+
+export type LegendVisibilityToggleProps = {
+  /**
+   * Override the aria labels (defaults: the layer pair in rows and controlled
+   * mode, the group pair in group headers) — e.g.
+   * `labels={{ hideLayer: 'Hide section', showLayer: 'Show section' }}`.
+   */
+  labels?: Pick<LegendLabels, 'hideLayer' | 'showLayer'>
+} & (
+  | {
+      /**
+       * Controlled mode: current state — renders the matching eye (`mixed` →
+       * the indeterminate icon). Use it for element kinds beyond layer/group.
+       */
+      visibility: LegendVisibility
+      /**
+       * Controlled mode: called with the **next** visibility (`hidden` →
+       * `true`; `visible`/`mixed` → `false`) — mirrors the store setters.
+       */
+      onToggle: (visible: boolean) => void
+    }
+  | { visibility?: never; onToggle?: never }
+)
+
+/**
+ * Agnostic visibility eye. Pass `visibility` + `onToggle` to control it for
+ * any element kind (no context needed); without them it wires itself to the
+ * nearest context — the layer eye inside a `Legend.Row`, the tri-state group
+ * eye (cascading to every member) inside a `Legend.Group`. Pinned `.active`
+ * in the hover-fade group while not fully visible. Renders nothing without
+ * props or context (dev-only warning).
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendVisibilityToggle({
+  visibility,
+  onToggle,
+  labels,
+}: LegendVisibilityToggleProps) {
+  const id = useLegendId()
+  const row = useLegendRow()
+  const groupId = useLegendGroupId()
+  const { labels: configLabels } = useLegendConfig()
+
+  const controlled = visibility !== undefined && onToggle !== undefined
+
+  const layerVisible = useLegendStore(id, (s) =>
+    !controlled && row ? (s.layers[row.layerId]?.visible ?? true) : true,
+  )
+  const groupVisibility = useLegendShallow(id, (s) =>
+    !controlled && !row && groupId
+      ? selectGroupVisibility(s, groupId)
+      : 'visible',
+  )
+  const setVisibility = useLegendStore(id, (s) => s.setVisibility)
+  const setGroupVisibility = useLegendStore(id, (s) => s.setGroupVisibility)
+
+  useEffect(() => {
+    if (!controlled && !row && !groupId) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        'Legend.VisibilityToggle needs `visibility`/`onToggle` props or a Legend.Row / Legend.Group context.',
+      )
+    }
+  }, [controlled, row, groupId])
+
+  // Resolve the tri-state + handler + label pair for the three modes.
+  let state: LegendVisibility
+  let handleToggle: () => void
+  let labelPair: Pick<LegendLabels, 'hideLayer' | 'showLayer'> | undefined =
+    labels
+
+  if (controlled) {
+    state = visibility
+    handleToggle = () => onToggle(visibility === 'hidden')
+  } else if (row) {
+    state = layerVisible ? 'visible' : 'hidden'
+    handleToggle = () => setVisibility(row.layerId, !layerVisible)
+  } else if (groupId) {
+    state = groupVisibility
+    handleToggle = () =>
+      setGroupVisibility(groupId, groupVisibility === 'hidden')
+    labelPair = labels ?? {
+      hideLayer: configLabels.hideGroup,
+      showLayer: configLabels.showGroup,
+    }
+  } else {
+    return null
+  }
+
+  const { hideLayer, showLayer } = labelPair ?? configLabels
+  const EyeIcon = ICONS[state]
+  const label = state === 'hidden' ? showLayer : hideLayer
+
+  return (
+    // Tooltip clones the button (no wrapper element), so the hover-fade
+    // group's direct-child rules and the `.active` pin keep working.
+    <Tooltip title={label}>
+      <IconButton
+        size='small'
+        className={state === 'visible' ? undefined : 'active'}
+        onClick={handleToggle}
+        aria-label={label}
+      >
+        <EyeIcon fontSize='small' />
+      </IconButton>
+    </Tooltip>
+  )
+}

package/src/legend/components/legend-visible-layers/legend-visible-layers.test.tsx

@@ -0,0 +1,86 @@
+import { afterEach, describe, it, expect } from 'vitest'
+import { act, fireEvent, render, screen } from '@testing-library/react'
+import { LegendProvider } from '../../provider'
+import { LegendVisibleLayers } from './legend-visible-layers'
+import {
+  clearAllLegendStores,
+  getLegendStore,
+  type LegendLayerInput,
+  type LegendVariable,
+} from '../../stores'
+
+const cat: LegendVariable = {
+  type: 'category',
+  items: [{ label: 'A', color: '#123456' }],
+}
+
+const layers: LegendLayerInput[] = [
+  { id: 'a', name: 'Suitability', groupId: 'g1', variables: [cat] },
+  { id: 'b', name: 'Population', groupId: 'g2', variables: [cat] },
+  { id: 'c', name: 'Facilities', variables: [cat] }, // ungrouped → last
+]
+const groups = [
+  { id: 'g1', label: 'Site selection' },
+  { id: 'g2', label: 'Demographics' },
+]
+
+afterEach(() => clearAllLegendStores())
+
+function renderSummary(id: string, layerInputs = layers) {
+  return render(
+    <LegendProvider id={id} layers={layerInputs} groups={groups}>
+      <LegendVisibleLayers />
+    </LegendProvider>,
+  )
+}
+
+describe('<LegendVisibleLayers>', () => {
+  it('lists only visible layers grouped under their captions, ungrouped last', () => {
+    renderSummary('vl1', [
+      ...layers.slice(0, 2),
+      { ...layers[2]!, visible: false } as LegendLayerInput,
+    ])
+    fireEvent.click(screen.getByLabelText('Enabled layers'))
+    // Count excludes the hidden ungrouped layer.
+    expect(screen.getByText('Enabled layers (2)')).toBeTruthy()
+    expect(screen.getByText('Site selection')).toBeTruthy()
+    expect(screen.getByText('Suitability')).toBeTruthy()
+    expect(screen.getByText('Population')).toBeTruthy()
+    // Hidden layer (and its would-be section) not listed.
+    expect(screen.queryByText('Facilities')).toBeNull()
+  })
+
+  it('clicking an entry hides the layer and removes it without closing the menu', () => {
+    renderSummary('vl2')
+    fireEvent.click(screen.getByLabelText('Enabled layers'))
+    expect(screen.getByText('Enabled layers (3)')).toBeTruthy()
+
+    // The whole item is the hide action (keyboard-reachable menu item).
+    fireEvent.click(screen.getByRole('menuitem', { name: 'Suitability' }))
+    expect(getLegendStore('vl2').getState().layers.a!.visible).toBe(false)
+    // Menu stayed open, entry gone, count updated live.
+    expect(screen.getByText('Enabled layers (2)')).toBeTruthy()
+    expect(screen.queryByText('Suitability')).toBeNull()
+  })
+
+  it('hiding the last visible layer closes the menu and disables the trigger', () => {
+    renderSummary('vl3', [layers[0]!])
+    const trigger = screen.getByLabelText<HTMLButtonElement>('Enabled layers')
+    fireEvent.click(trigger)
+    fireEvent.click(screen.getByRole('menuitem', { name: 'Suitability' }))
+    // Nothing left to list → the menu closed itself (role queries skip the
+    // aria-hidden exit transition)…
+    expect(screen.queryByRole('menu')).toBeNull()
+    // …and the trigger is disabled until a layer is shown again.
+    expect(trigger.disabled).toBe(true)
+  })
+
+  it('closes when the last visible layer is hidden from elsewhere', () => {
+    renderSummary('vl4', [layers[0]!])
+    fireEvent.click(screen.getByLabelText('Enabled layers'))
+    expect(screen.getByRole('menu')).toBeTruthy()
+    // External change (e.g. a row eye) while the menu is open.
+    act(() => getLegendStore('vl4').getState().setVisibility('a', false))
+    expect(screen.queryByRole('menu')).toBeNull()
+  })
+})

package/src/legend/components/legend-visible-layers/legend-visible-layers.tsx

@@ -0,0 +1,135 @@
+import { useState, type MouseEvent } from 'react'
+import {
+  Box,
+  Divider,
+  IconButton,
+  Menu,
+  MenuItem,
+  Typography,
+} from '@mui/material'
+import {
+  ChecklistOutlined as ChecklistIcon,
+  VisibilityOutlined as VisibilityIcon,
+} from '@mui/icons-material'
+import { Tooltip } from '../../../components/tooltip/tooltip'
+import {
+  getLegendStore,
+  selectVisibleLayersGrouped,
+  useLegendId,
+  useLegendShallow,
+  useLegendStore,
+} from '../../stores'
+import { useLegendConfig } from '../../provider'
+import { styles } from './styles'
+
+/** `key` ties section derivation to the visibility fingerprint subscription. */
+function sectionsForKey(legendId: string, key: string) {
+  void key
+  return selectVisibleLayersGrouped(getLegendStore(legendId).getState())
+}
+
+/**
+ * Panel checklist of visible layers — each entry hides its layer; the menu
+ * closes when nothing remains to list.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendVisibleLayers() {
+  const id = useLegendId()
+  const [anchorEl, setAnchorEl] = useState<HTMLElement | null>(null)
+  // Fingerprint avoids opacity-driven re-renders (React Compiler would hoist stale useMemo).
+  const visibleKey = useLegendStore(id, (s) =>
+    selectVisibleLayersGrouped(s)
+      .map(
+        ({ group, layers }) =>
+          `${group?.id ?? ''}\x1f${group?.label ?? ''}:${layers
+            .map((l) => `${l.id}\x1f${l.name}`)
+            .join(',')}`,
+      )
+      .join('|'),
+  )
+  const sections = sectionsForKey(id, visibleKey)
+  const setVisibility = useLegendShallow(id, (s) => s.setVisibility)
+  const { labels } = useLegendConfig()
+
+  const count = sections.reduce((n, s) => n + s.layers.length, 0)
+  // Derived close when count hits 0; clear anchor on exit so it can't reopen stale.
+  const open = Boolean(anchorEl) && count > 0
+
+  const handleOpen = (e: MouseEvent<HTMLElement>) =>
+    setAnchorEl(e.currentTarget)
+  const handleClose = () => setAnchorEl(null)
+
+  return (
+    <>
+      <Tooltip title={labels.toggleEnabledLayers}>
+        {/* Span: MUI Tooltip can't attach listeners to a disabled button. */}
+        <Box component='span' sx={styles.triggerWrap}>
+          <IconButton
+            size='small'
+            className={open ? 'active' : undefined}
+            disabled={count === 0}
+            onClick={handleOpen}
+            aria-label={labels.enabledLayers}
+            aria-haspopup='menu'
+            aria-expanded={open}
+          >
+            <ChecklistIcon fontSize='small' />
+          </IconButton>
+        </Box>
+      </Tooltip>
+      <Menu
+        anchorEl={anchorEl}
+        open={open}
+        onClose={handleClose}
+        TransitionProps={{ onExited: handleClose }}
+        // No list padding — sticky header sits flush (avoids scroll peek-through).
+        MenuListProps={{ disablePadding: true }}
+        slotProps={{ paper: { sx: styles.paper } }}
+      >
+        <Typography
+          component='div'
+          variant='caption'
+          color='text.primary'
+          sx={styles.stickyHeader}
+        >
+          {`${labels.enabledLayers} (${count})`}
+        </Typography>
+        {sections.flatMap((section, index) => [
+          index > 0 ? (
+            <Divider
+              key={`divider-${section.group?.id ?? 'ungrouped'}`}
+              sx={styles.divider}
+            />
+          ) : null,
+          section.group ? (
+            <Typography
+              key={`caption-${section.group.id}`}
+              variant='caption'
+              fontWeight='medium'
+              color='text.secondary'
+              sx={styles.groupCaption}
+            >
+              {section.group.label}
+            </Typography>
+          ) : null,
+          ...section.layers.map((layer) => (
+            <MenuItem
+              key={layer.id}
+              disableRipple
+              sx={styles.item}
+              onClick={() => setVisibility(layer.id, false)}
+            >
+              <Typography variant='body2' sx={styles.itemName}>
+                {layer.name}
+              </Typography>
+              <Tooltip title={labels.hideLayer}>
+                <VisibilityIcon sx={styles.eye} />
+              </Tooltip>
+            </MenuItem>
+          )),
+        ])}
+      </Menu>
+    </>
+  )
+}

package/src/legend/components/legend-visible-layers/styles.ts

@@ -0,0 +1,60 @@
+import type { SxProps, Theme } from '@mui/material'
+
+// Figma "Menu" (node 6962-12862): 232px paper, sticky caption header with a
+// hairline below, caption-medium group subtitles, 32px items (12px left / 8px
+// right inset) with an 18px eye, and 8px-padded dividers between sections.
+export const styles = {
+  // Tooltip wrapper around the (possibly disabled) trigger button. A plain
+  // inline span would be sized by the line box and end up taller than the
+  // button inside.
+  triggerWrap: {
+    display: 'inline-flex',
+  },
+  paper: {
+    width: 240,
+    maxHeight: 320,
+    // List padding is disabled (flush sticky header); keep a small bottom
+    // inset so the last 32px item doesn't touch the paper edge.
+    paddingBottom: 0.5,
+  },
+  stickyHeader: {
+    position: 'sticky',
+    top: 0,
+    zIndex: 1,
+    backgroundColor: 'background.paper',
+    padding: 1,
+    marginBlockEnd: 1,
+    lineHeight: '16px',
+    borderBottom: '1px solid',
+    borderColor: 'divider',
+  },
+  groupCaption: {
+    display: 'block',
+    padding: ({ spacing }) => spacing(0.5, 1.5),
+  },
+  // The whole item is the hide action (keyboard-friendly); the eye is its
+  // visual affordance.
+  item: {
+    minHeight: 32,
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    gap: 1,
+    padding: ({ spacing }) => spacing(0, 1, 0, 1.5),
+  },
+  itemName: {
+    minWidth: 0,
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+  },
+  // Design's 18px glyph — decorative (the item itself is the action).
+  eye: {
+    fontSize: 18,
+    color: 'action.active',
+    flexShrink: 0,
+  },
+  divider: {
+    marginY: 1,
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/legend/components/run-async-menu-action.ts

@@ -0,0 +1,20 @@
+import type { LegendMenuController } from './contexts'
+
+/**
+ * Run an async menu action with busy gating. Uses `isBusy()` (ref-backed) so a
+ * second click before React re-renders cannot fire the handler twice. Keeps
+ * the menu open while pending, then clears busy and closes when it settles.
+ */
+export async function runAsyncMenuAction(
+  menu: LegendMenuController,
+  action: () => void | Promise<void>,
+): Promise<void> {
+  if (menu.isBusy()) return
+  menu.setBusy(true)
+  try {
+    await action()
+  } finally {
+    menu.setBusy(false)
+    menu.close()
+  }
+}