@carto/ps-react-ui 4.12.2 → 4.14.0

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

@@ -0,0 +1,111 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  // Padding lives on header/content/footer (not the root) so the sticky
+  // header is opaque and full-bleed while pinned.
+  row: {
+    display: 'flex',
+    flexDirection: 'column',
+    '& + &': {
+      borderTop: '1px solid',
+      borderColor: 'divider',
+    },
+    // Hover-fade actions (widgets-v2 Wrapper parity). Direct children of
+    // `.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 collapse chevron sits
+    // outside the fade group and never fades.
+    '& .PsLegend-rowFade > *': {
+      opacity: 1,
+      transition: ({ transitions }: Theme) =>
+        transitions.create('opacity', {
+          duration: transitions.duration.standard,
+          easing: transitions.easing.easeInOut,
+        }),
+      '@media (hover: hover)': {
+        opacity: 0,
+      },
+      '&.active': {
+        opacity: 1,
+      },
+    },
+    '&:hover .PsLegend-rowFade > *, &:focus-within .PsLegend-rowFade > *': {
+      opacity: 1,
+    },
+    // Hovering anywhere in the row also reveals the category/icon values
+    // (the renderers keep their own list-scoped rule for standalone usage).
+    '&:hover .PsLegend-value, &:focus-within .PsLegend-value': {
+      opacity: 1,
+    },
+  },
+  // Figma `_Legend header`: 16px top/left inset (title glyphs start at
+  // y≈17, x=16 in the 68px-tall header), actions share the title's vertical
+  // 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).
+  header: {
+    display: 'flex',
+    alignItems: 'flex-start',
+    gap: 0.5,
+    minHeight: 32,
+    padding: ({ spacing }) => spacing(1.5, 2, 1.5, 2),
+    position: 'sticky',
+    // Above MUI's z-index-1 form internals (e.g. InputLabel) in row content,
+    // below the group header (3).
+    zIndex: 2,
+    backgroundColor: 'background.paper',
+  },
+  titleBox: {
+    flex: 1,
+    minWidth: 0,
+    display: 'flex',
+    flexDirection: 'column',
+  },
+  // The title line and the actions box share the same 24px band, centered,
+  // so the title and the action icons stay aligned under the header's
+  // `flex-start` — no padding magic. The subtitle flows below.
+  titleLine: {
+    minHeight: 24,
+    display: 'flex',
+    alignItems: 'center',
+  },
+  title: {
+    flex: 1,
+    minWidth: 0,
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+  },
+  // Same 24px band as the title line, so both sides of the header stay
+  // aligned even when the composed actions are shorter (or fade out).
+  // Icon buttons (actions + collapse chevron) are squeezed to 24×24:
+  // 2px padding around the 20px small icon.
+  actions: {
+    minHeight: 24,
+    display: 'flex',
+    alignItems: 'center',
+    gap: 0.25,
+    flexShrink: 0,
+    '& .MuiIconButton-root': {
+      padding: '2px',
+    },
+  },
+  // Figma rhythm: ~16px from the subtitle to the select (8px header bottom
+  // padding + 4px here + line leading), 8px between body blocks, 8px bottom
+  // inset before the next row's divider.
+  content: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 1,
+    padding: ({ spacing }) => spacing(0.5, 2, 1, 2),
+  },
+  // ~16px above the note (content's 8px bottom inset + 8px here), per design.
+  footer: {
+    padding: ({ spacing }) => spacing(1, 2, 1, 2),
+  },
+  dimmed: {
+    opacity: 0.5,
+  },
+} satisfies Record<string, SxProps<Theme>>

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

@@ -0,0 +1,68 @@
+import { useState, type MouseEvent, type ReactNode } from 'react'
+import { IconButton, Menu } from '@mui/material'
+import { MoreVert as MoreVertIcon } from '@mui/icons-material'
+import { useLegendId, useLegendStore } from '../../stores'
+import { useLegendConfig } from '../../provider'
+import { useLegendRow } from '../contexts'
+
+export interface LegendRowMenuProps {
+  /**
+   * The menu items — composed by the consumer (e.g. `<Legend.ZoomTo>` or any
+   * MUI `MenuItem`). A click on any item bubbles to the menu and closes it;
+   * an item that must keep the menu open should `event.stopPropagation()`.
+   */
+  children?: ReactNode
+}
+
+/**
+ * Agnostic overflow (⋮) menu shell for a layer row — the items are passed as
+ * children, like `Legend.Actions`. Renders nothing without children, outside
+ * a row, or while the layer is hidden (a hidden row keeps only its
+ * visibility eye + collapse chevron).
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendRowMenu({ children }: LegendRowMenuProps) {
+  const id = useLegendId()
+  const [anchorEl, setAnchorEl] = useState<HTMLElement | null>(null)
+  const open = Boolean(anchorEl)
+  const row = useLegendRow()
+  const visible = useLegendStore(id, (s) =>
+    row ? (s.layers[row.layerId]?.visible ?? true) : true,
+  )
+  const { labels } = useLegendConfig()
+
+  if (!row || !children || !visible) return null
+
+  const handleOpen = (e: MouseEvent<HTMLElement>) => {
+    e.stopPropagation()
+    setAnchorEl(e.currentTarget)
+  }
+  const handleClose = () => setAnchorEl(null)
+
+  return (
+    <>
+      <IconButton
+        size='small'
+        className={open ? 'active' : undefined}
+        disabled={!visible}
+        onClick={handleOpen}
+        aria-label={labels.layerOptions}
+        aria-haspopup='menu'
+        aria-expanded={open}
+      >
+        <MoreVertIcon fontSize='small' />
+      </IconButton>
+      {/* Menu-level onClick: any item click (bubbling) closes the menu, so
+          consumer items need no legend wiring. */}
+      <Menu
+        anchorEl={anchorEl}
+        open={open}
+        onClose={handleClose}
+        onClick={handleClose}
+      >
+        {children}
+      </Menu>
+    </>
+  )
+}

package/src/legend/components/legend-row-menu/legend-zoom-to.tsx

@@ -0,0 +1,35 @@
+import { ListItemIcon, MenuItem } from '@mui/material'
+import { CenterFocusStrong as ZoomIcon } from '@mui/icons-material'
+import { useLegendConfig } from '../../provider'
+import { useLegendRow } from '../contexts'
+
+export interface LegendZoomToProps {
+  /**
+   * Fit the map viewport to the layer. The handler lives at the composition
+   * site (not the Provider) — each menu can wire its own behavior.
+   */
+  onZoomTo: (layerId: string) => void
+}
+
+/**
+ * "Zoom to" menu item for `Legend.RowMenu` — resolves its layer from the
+ * enclosing `Legend.Row` context and calls the `onZoomTo` it was composed
+ * with. The click bubbles to the menu, which closes itself.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendZoomTo({ onZoomTo }: LegendZoomToProps) {
+  const row = useLegendRow()
+  const { labels } = useLegendConfig()
+
+  if (!row) return null
+
+  return (
+    <MenuItem onClick={() => onZoomTo(row.layerId)}>
+      <ListItemIcon>
+        <ZoomIcon fontSize='small' />
+      </ListItemIcon>
+      {labels.zoomTo}
+    </MenuItem>
+  )
+}

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

@@ -0,0 +1,109 @@
+import { describe, it, expect } from 'vitest'
+import { render } from '@testing-library/react'
+import { LegendSwatch } from './legend-swatch'
+
+function swatch(container: HTMLElement) {
+  return container.querySelector<SVGSVGElement>('svg')!
+}
+
+describe('<LegendSwatch>', () => {
+  it('renders a circle by default (filled, no border)', () => {
+    const { container } = render(<LegendSwatch color='#f00' />)
+    const svg = swatch(container)
+    expect(svg.getAttribute('data-shape')).toBe('circle')
+    const circle = svg.querySelector('circle')!
+    expect(circle.getAttribute('fill')).toBe('#f00')
+    expect(circle.getAttribute('stroke')).toBe('none')
+  })
+
+  it('renders a square shape', () => {
+    const { container } = render(<LegendSwatch shape='square' color='#f00' />)
+    expect(swatch(container).querySelector('rect')).toBeTruthy()
+  })
+
+  it('renders a line shape', () => {
+    const { container } = render(<LegendSwatch shape='line' color='#f00' />)
+    const svg = swatch(container)
+    expect(svg.getAttribute('data-shape')).toBe('line')
+    expect(svg.querySelector('line')).toBeTruthy()
+  })
+
+  it('isStrokeColor paints the border, not the fill', () => {
+    const { container } = render(
+      <LegendSwatch shape='square' color='#0f0' isStrokeColor />,
+    )
+    const rect = swatch(container).querySelector('rect')!
+    expect(rect.getAttribute('fill')).toBe('none')
+    expect(rect.getAttribute('stroke')).toBe('#0f0')
+  })
+
+  it('emits a <pattern> def for a patterned fill and references it', () => {
+    const { container } = render(
+      <LegendSwatch shape='square' color='#00f' fillPattern='diagonal' />,
+    )
+    const svg = swatch(container)
+    const pattern = svg.querySelector('pattern')!
+    expect(pattern).toBeTruthy()
+    const rect = svg.querySelector('rect')!
+    expect(rect.getAttribute('fill')).toBe(`url(#${pattern.id})`)
+  })
+
+  it('solid fill emits no <pattern>', () => {
+    const { container } = render(<LegendSwatch shape='square' color='#00f' />)
+    expect(swatch(container).querySelector('pattern')).toBeNull()
+  })
+
+  it('dashed border sets a stroke-dasharray', () => {
+    const { container } = render(
+      <LegendSwatch
+        shape='square'
+        color='#000'
+        isStrokeColor
+        strokeStyle='dashed'
+      />,
+    )
+    expect(
+      swatch(container).querySelector('rect')!.getAttribute('stroke-dasharray'),
+    ).toBeTruthy()
+  })
+
+  it('corner-marks render four paths (square only)', () => {
+    const { container } = render(
+      <LegendSwatch
+        shape='square'
+        color='#000'
+        isStrokeColor
+        strokeStyle='corners'
+      />,
+    )
+    const svg = swatch(container)
+    expect(svg.querySelectorAll('path')).toHaveLength(4)
+    expect(svg.querySelector('rect')).toBeNull()
+  })
+
+  it('gracefully degrades: corners on a circle falls back to a solid border', () => {
+    const { container } = render(
+      <LegendSwatch
+        shape='circle'
+        color='#000'
+        isStrokeColor
+        strokeStyle='corners'
+      />,
+    )
+    const svg = swatch(container)
+    // No corner paths; a plain stroked circle instead.
+    expect(svg.querySelectorAll('path')).toHaveLength(0)
+    const circle = svg.querySelector('circle')!
+    expect(circle.getAttribute('stroke')).toBe('#000')
+    expect(circle.getAttribute('stroke-dasharray')).toBeFalsy()
+  })
+
+  it('dash-dot line sets the dash-dot dasharray', () => {
+    const { container } = render(
+      <LegendSwatch shape='line' color='#000' strokeStyle='dash-dot' />,
+    )
+    expect(
+      swatch(container).querySelector('line')!.getAttribute('stroke-dasharray'),
+    ).toBe('5 2 0.1 2')
+  })
+})

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,127 @@
+import { useEffect } from 'react'
+import { IconButton } from '@mui/material'
+import {
+  VisibilityOutlined as VisibilityIcon,
+  VisibilityOffOutlined as VisibilityOffIcon,
+} from '@mui/icons-material'
+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]
+
+  return (
+    <IconButton
+      size='small'
+      className={state === 'visible' ? undefined : 'active'}
+      onClick={handleToggle}
+      aria-label={state === 'hidden' ? showLayer : hideLayer}
+    >
+      <EyeIcon fontSize='small' />
+    </IconButton>
+  )
+}