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

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

@@ -0,0 +1,34 @@
+import { Box } from '@mui/material'
+import { useLegendId, useLegendShallow } from '../../stores'
+import { useLegendConfig } from '../../provider'
+import { useLegendRow } from '../contexts'
+import { LegendItemUI } from './legend-item-ui'
+import { styles } from './styles'
+
+/**
+ * Store-connected item renderer — reads the layer's `variables` from the
+ * enclosing `Legend.Row` context (plus the Provider's labels) and stacks one
+ * pure renderer per variable, top-to-bottom with the design's 16px section
+ * gap. Use `Legend.ItemUI` directly for store-free, single-variable
+ * composition.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendItem() {
+  const id = useLegendId()
+  const row = useLegendRow()
+  const variables = useLegendShallow(id, (s) =>
+    row ? s.layers[row.layerId]?.variables : undefined,
+  )
+  const { labels } = useLegendConfig()
+
+  if (!variables || variables.length === 0) return null
+
+  return (
+    <Box sx={styles.stack}>
+      {variables.map((variable, index) => (
+        <LegendItemUI key={index} data={variable} labels={labels} />
+      ))}
+    </Box>
+  )
+}

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

@@ -0,0 +1,11 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  // Figma: stacked variable sections sit ~16px apart (wider than the row
+  // content's 8px block gap).
+  stack: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 2,
+  },
+} satisfies Record<string, SxProps<Theme>>

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

@@ -0,0 +1,152 @@
+import { useState } from 'react'
+import {
+  Box,
+  IconButton,
+  InputAdornment,
+  MenuItem,
+  OutlinedInput,
+  Slider,
+  Typography,
+} from '@mui/material'
+import { Close as CloseIcon } from '@mui/icons-material'
+import { Tooltip } from '../../../components/tooltip/tooltip'
+import { useLegendId, useLegendShallow, useLegendStore } from '../../stores'
+import { useLegendConfig } from '../../provider'
+import { useLegendRow } from '../contexts'
+import { styles } from './styles'
+
+const clampPercent = (value: number): number =>
+  Math.min(100, Math.max(0, Math.round(value)))
+
+/**
+ * Opacity menu item — toggles the row's inline bar; self-hides when hidden or no `opacityControl`.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+function OpacityItem() {
+  const id = useLegendId()
+  const row = useLegendRow()
+  const layer = useLegendShallow(id, (s) =>
+    row ? s.layers[row.layerId] : undefined,
+  )
+  const setCollapsed = useLegendShallow(id, (s) => s.setCollapsed)
+  const { labels } = useLegendConfig()
+
+  if (!row || !layer?.visible || !layer.opacityControl) return null
+
+  const toggle = () => {
+    const next = !row.opacityOpen
+    row.setOpacityOpen(next)
+    if (next && layer.collapsed) setCollapsed(row.layerId, false)
+  }
+
+  return (
+    <MenuItem selected={row.opacityOpen} onClick={toggle}>
+      {labels.opacity}
+    </MenuItem>
+  )
+}
+
+/**
+ * Inline opacity bar (first body child of `Legend.Row`). Slider commits on release; input commits live.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+function OpacityInline() {
+  const id = useLegendId()
+  const row = useLegendRow()
+  const layerId = row?.layerId
+  const opacity = useLegendStore(id, (s) =>
+    layerId ? (s.layers[layerId]?.opacity ?? 1) : 1,
+  )
+  const setOpacity = useLegendStore(id, (s) => s.setOpacity)
+  const { labels } = useLegendConfig()
+
+  const [dragPercent, setDragPercent] = useState<number | null>(null)
+  const [draft, setDraft] = useState<string | null>(null)
+
+  if (!row || !layerId || !row.opacityOpen) return null
+
+  const percent = dragPercent ?? clampPercent(opacity * 100)
+
+  const commitPercent = (value: number): number => {
+    const clamped = clampPercent(value)
+    setOpacity(layerId, clamped / 100)
+    return clamped
+  }
+
+  const handleInputChange = (raw: string) => {
+    setDraft(raw)
+    if (raw.trim() === '') return
+    const parsed = Number(raw)
+    if (!Number.isFinite(parsed)) return
+    const clamped = commitPercent(parsed)
+    if (clamped !== parsed) setDraft(String(clamped))
+  }
+
+  const handleClose = () => {
+    row.setOpacityOpen(false)
+    setDraft(null)
+    setDragPercent(null)
+  }
+
+  return (
+    <Box sx={styles.inline}>
+      <Box sx={styles.inlineHeader}>
+        <Typography variant='caption' fontWeight='medium' color='text.primary'>
+          {labels.opacity}
+        </Typography>
+        <Tooltip title={labels.close}>
+          <IconButton
+            size='small'
+            onClick={handleClose}
+            aria-label={labels.close}
+          >
+            <CloseIcon fontSize='small' />
+          </IconButton>
+        </Tooltip>
+      </Box>
+      <Box sx={styles.inlineControls}>
+        <Slider
+          size='small'
+          min={0}
+          max={100}
+          step={1}
+          value={percent}
+          onChange={(_, value) => {
+            setDragPercent(value as number)
+            setDraft(null)
+          }}
+          onChangeCommitted={(_, value) => {
+            commitPercent(value as number)
+            setDragPercent(null)
+          }}
+          aria-label={labels.opacity}
+          sx={styles.slider}
+        />
+        <OutlinedInput
+          size='small'
+          value={draft ?? String(percent)}
+          onChange={(event) => handleInputChange(event.target.value)}
+          onBlur={() => setDraft(null)}
+          onKeyDown={(event) => {
+            if (event.key === 'Enter') (event.target as HTMLElement).blur()
+          }}
+          endAdornment={<InputAdornment position='end'>%</InputAdornment>}
+          inputProps={{ inputMode: 'numeric', 'aria-label': labels.opacity }}
+          sx={styles.input}
+        />
+      </Box>
+    </Box>
+  )
+}
+
+/**
+ * Compound opacity control: `Item` in the row menu, `Inline` in the body.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export const LegendOpacity = {
+  Item: OpacityItem,
+  Inline: OpacityInline,
+}

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

@@ -0,0 +1,33 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  // Figma "Legend Opacity": a soft rounded bar between the row header and the
+  // body — caption label + ✕ on the first line, slider + % input below.
+  inline: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 0.5,
+    borderRadius: 1,
+  },
+  inlineHeader: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+  },
+  inlineControls: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 1.5,
+  },
+  slider: {
+    flex: 1,
+  },
+  // Wide enough for "100 %" — the value must never ellipsize.
+  input: {
+    width: 72,
+    flexShrink: 0,
+    '& input': {
+      textAlign: 'right',
+    },
+  },
+} satisfies Record<string, SxProps<Theme>>

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

@@ -0,0 +1,84 @@
+import {
+  useCallback,
+  useMemo,
+  useRef,
+  useState,
+  type MouseEvent,
+  type ReactNode,
+} from 'react'
+import { IconButton, Menu } from '@mui/material'
+import { MoreVert as MoreVertIcon } from '@mui/icons-material'
+import { Tooltip } from '../../../components/tooltip/tooltip'
+import { useLegendConfig } from '../../provider'
+import { LegendMenuContext, type LegendMenuController } from '../contexts'
+
+export interface LegendOverflowMenuProps {
+  /** Menu items; async items use `stopPropagation` + `runAsyncMenuAction`. */
+  children?: ReactNode
+  /** When `false`, render nothing. Defaults to `true`. */
+  gate?: boolean
+  /** `aria-label` for the ⋮ trigger. */
+  ariaLabel: string
+  /** Extra `.active` pin (e.g. inline opacity bar open). */
+  active?: boolean
+}
+export function LegendOverflowMenu({
+  children,
+  gate = true,
+  ariaLabel,
+  active = false,
+}: LegendOverflowMenuProps) {
+  const [anchorEl, setAnchorEl] = useState<HTMLElement | null>(null)
+  const [busy, setBusyState] = useState(false)
+  // Ref so close-guards and click gates see the flag before the next render.
+  const busyRef = useRef(false)
+  const open = Boolean(anchorEl)
+  const { labels } = useLegendConfig()
+
+  const close = useCallback(() => setAnchorEl(null), [])
+  const setBusy = useCallback((next: boolean) => {
+    busyRef.current = next
+    setBusyState(next)
+  }, [])
+  const isBusy = useCallback(() => busyRef.current, [])
+  const handleClose = useCallback(() => {
+    if (busyRef.current) return
+    close()
+  }, [close])
+  const menu = useMemo<LegendMenuController>(
+    () => ({ busy, isBusy, setBusy, close }),
+    [busy, isBusy, setBusy, close],
+  )
+
+  if (!gate || !children) return null
+
+  const handleOpen = (e: MouseEvent<HTMLElement>) => {
+    e.stopPropagation()
+    setAnchorEl(e.currentTarget)
+  }
+
+  return (
+    <LegendMenuContext.Provider value={menu}>
+      <Tooltip title={labels.moreOptions}>
+        <IconButton
+          size='small'
+          className={open || busy || active ? 'active' : undefined}
+          onClick={handleOpen}
+          aria-label={ariaLabel}
+          aria-haspopup='menu'
+          aria-expanded={open}
+        >
+          <MoreVertIcon fontSize='small' />
+        </IconButton>
+      </Tooltip>
+      <Menu
+        anchorEl={anchorEl}
+        open={open}
+        onClose={handleClose}
+        onClick={handleClose}
+      >
+        {children}
+      </Menu>
+    </LegendMenuContext.Provider>
+  )
+}

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

@@ -0,0 +1,23 @@
+import type { ReactNode } from 'react'
+import { useLegendConfig } from '../../provider'
+import { LegendOverflowMenu } from '../legend-overflow-menu/legend-overflow-menu'
+
+export interface LegendPanelMenuProps {
+  /** Menu items; async items use `stopPropagation` + `runAsyncMenuAction`. */
+  children?: ReactNode
+}
+
+/**
+ * Overflow (⋮) menu for the panel header (no row/group context).
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendPanelMenu({ children }: LegendPanelMenuProps) {
+  const { labels } = useLegendConfig()
+
+  return (
+    <LegendOverflowMenu ariaLabel={labels.panelOptions}>
+      {children}
+    </LegendOverflowMenu>
+  )
+}

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

@@ -0,0 +1,122 @@
+import type { ReactNode } from 'react'
+import { Box, Typography } from '@mui/material'
+import { styles } from './styles'
+import { DEFAULT_LEGEND_LABELS, type LegendLabels } from '../../provider/labels'
+import type { LegendProportionVariable } from '../../stores'
+
+export interface LegendProportionUIProps {
+  data: LegendProportionVariable
+  /** Override the renderer's user-facing strings. */
+  labels?: Pick<LegendLabels, 'radiusRangeBy' | 'maxPrefix' | 'minPrefix'>
+}
+
+const MAX_DIAMETER = 72
+const RATIO_FLOOR = 0.3
+const MIN_STEPS = 2
+const MAX_STEPS = 4
+
+/**
+ * Value breaks, largest→smallest. Explicit `stops` (≥2 entries) win, capped at
+ * the 4 largest; otherwise breaks are derived evenly from `min`/`max` over
+ * `steps` clamped to 2–4. Circles map 1:1 to the breaks.
+ */
+function resolveBreaks(data: LegendProportionVariable): number[] {
+  const explicit = (data.stops ?? []).filter((n) => Number.isFinite(n))
+  if (explicit.length >= MIN_STEPS) {
+    return explicit.sort((a, b) => b - a).slice(0, MAX_STEPS)
+  }
+  const { min, max } = data
+  if (min === max) return [max]
+  const steps = Math.min(
+    MAX_STEPS,
+    Math.max(MIN_STEPS, data.steps ?? MAX_STEPS),
+  )
+  return Array.from(
+    { length: steps },
+    (_, i) => max - ((max - min) * i) / (steps - 1),
+  )
+}
+
+/** Decorative nested-circle diameter for circle `i` of `n` (i=0 outermost). */
+function diameterFor(i: number, n: number): number {
+  if (n <= 1) return MAX_DIAMETER
+  const ratio = 1 - (1 - RATIO_FLOOR) * (i / (n - 1))
+  return MAX_DIAMETER * ratio
+}
+
+/**
+ * Proportional-symbol legend — a stack of decorative nested circles with the
+ * value breaks labelled beside them (largest = MAX, smallest = MIN). Circle
+ * sizes are fixed/decorative, not value-derived, so the legend stays readable
+ * across very wide ranges.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendProportionUI({
+  data,
+  labels = DEFAULT_LEGEND_LABELS,
+}: LegendProportionUIProps) {
+  const { attribute, formatValue = String } = data
+  const breaks = resolveBreaks(data)
+  const n = breaks.length
+
+  const labelFor = (value: number, i: number): ReactNode => {
+    const formatted = formatValue(value)
+    if (n <= 1) return formatted
+    if (i === 0)
+      return (
+        <>
+          {labels.maxPrefix}
+          {formatted}
+        </>
+      )
+    if (i === n - 1)
+      return (
+        <>
+          {labels.minPrefix}
+          {formatted}
+        </>
+      )
+    return formatted
+  }
+
+  return (
+    <Box sx={styles.root}>
+      {attribute && (
+        <Box sx={styles.attribute}>
+          <Typography variant='overline' color='text.secondary'>
+            {labels.radiusRangeBy}
+          </Typography>
+          <Typography variant='caption' color='text.primary'>
+            {attribute}
+          </Typography>
+        </Box>
+      )}
+
+      <Box sx={styles.body}>
+        <Box
+          sx={{ ...styles.circles, width: MAX_DIAMETER, height: MAX_DIAMETER }}
+        >
+          {breaks.map((_, i) => {
+            const diameter = diameterFor(i, n)
+            return (
+              <Box
+                key={i}
+                aria-hidden
+                sx={{ ...styles.circle, width: diameter, height: diameter }}
+              />
+            )
+          })}
+        </Box>
+
+        <Box sx={{ ...styles.labels, height: MAX_DIAMETER }}>
+          {breaks.map((value, i) => (
+            <Typography key={i} variant='caption' color='text.secondary'>
+              {labelFor(value, i)}
+            </Typography>
+          ))}
+        </Box>
+      </Box>
+    </Box>
+  )
+}

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

@@ -0,0 +1,43 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  root: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 1,
+  },
+  attribute: {
+    display: 'flex',
+    flexDirection: 'column',
+  },
+  body: {
+    display: 'flex',
+    alignItems: 'flex-end',
+    gap: 2,
+    paddingTop: 0.5,
+  },
+  circles: {
+    position: 'relative',
+    flexShrink: 0,
+  },
+  // All circles share the bottom and right edges (anchored bottom-right), so
+  // they nest along the diagonal — largest fanning up-left, smallest in the
+  // bottom-right. Every circle has the SAME opaque fill, so overlaps don't
+  // compound (uniform colour) while the borders still read as nested rings.
+  circle: {
+    position: 'absolute',
+    right: 0,
+    bottom: 0,
+    borderRadius: '50%',
+    backgroundColor: 'grey.50',
+    border: '1px solid',
+    borderColor: 'grey.100',
+    boxSizing: 'border-box',
+  },
+  labels: {
+    flex: 1,
+    display: 'flex',
+    flexDirection: 'column',
+    justifyContent: 'space-between',
+  },
+} satisfies Record<string, SxProps<Theme>>

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

@@ -0,0 +1,160 @@
+import { Box, Typography } from '@mui/material'
+import { Tooltip } from '../../../components/tooltip/tooltip'
+import { ErrorOutline as ErrorIcon } from '@mui/icons-material'
+import { styles } from './styles'
+import { DEFAULT_LEGEND_LABELS, type LegendLabels } from '../../provider/labels'
+import type { LegendRampVariable } from '../../stores'
+
+export interface LegendRampUIProps {
+  data: LegendRampVariable
+  /** Override the renderer's user-facing strings. */
+  labels?: Pick<LegendLabels, 'colorBasedOn' | 'colorGradient'>
+}
+
+/**
+ * Horizontal position (0–100) of `avg` on the bar — linear between the first
+ * and last stop values, clamped to the edges. `null` when there's no scale
+ * (fewer than 2 stops or a zero-width range).
+ */
+function avgPercent(data: LegendRampVariable): number | null {
+  const { avg, stops } = data
+  if (avg == null || stops.length < 2) return null
+  const v0 = stops[0]!.value
+  const vn = stops[stops.length - 1]!.value
+  if (v0 === vn) return null
+  const pct = ((avg - v0) / (vn - v0)) * 100
+  return Math.min(100, Math.max(0, pct))
+}
+
+/**
+ * Color-ramp legend. `colors` and `stops` are both ordered low→high and are
+ * never reversed, so step colors and their labels stay aligned.
+ *
+ * Continuous mode renders a gradient with the endpoint labels. Discrete mode
+ * **requires `stops.length === colors.length + 1`** — stops are the boundaries
+ * between color steps (including both outer edges) and each label is centered
+ * on its boundary line. A discrete ramp with any other stop count is an
+ * incoherent state and renders a compact inline error instead of the bar.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendRampUI({
+  data,
+  labels = DEFAULT_LEGEND_LABELS,
+}: LegendRampUIProps) {
+  const { colors, stops, isContinuous, attribute, formatValue = String } = data
+  const avgPct = avgPercent(data)
+
+  const first = stops[0]
+  const last = stops[stops.length - 1]
+  const gradient = `linear-gradient(90deg, ${colors.join(', ')})`
+
+  // Discrete ramps need one stop per color boundary (colors.length + 1).
+  // `isBoundary` is therefore equivalent to "valid discrete".
+  const isBoundary = !isContinuous && stops.length === colors.length + 1
+  const invalidDiscrete = !isContinuous && !isBoundary
+
+  // Boundary range for assistive tech (valid discrete only reaches here).
+  const stepAriaLabel = (index: number): string =>
+    `${stops[index]?.label ?? ''} – ${stops[index + 1]?.label ?? ''}`
+
+  const attributeHeader = attribute && (
+    <Box sx={styles.attribute}>
+      <Typography variant='overline' color='text.secondary'>
+        {labels.colorBasedOn}
+      </Typography>
+      <Typography variant='caption' color='text.primary'>
+        {attribute}
+      </Typography>
+    </Box>
+  )
+
+  if (invalidDiscrete) {
+    return (
+      <Box sx={styles.container}>
+        {attributeHeader}
+        <Box sx={styles.error}>
+          <ErrorIcon fontSize='small' />
+          <Typography variant='caption' color='error'>
+            {`Discrete ramp needs ${colors.length + 1} stops (one per color boundary) but got ${stops.length}.`}
+          </Typography>
+        </Box>
+      </Box>
+    )
+  }
+
+  return (
+    <Box sx={styles.container}>
+      {attributeHeader}
+
+      <Box sx={styles.barWrap}>
+        <Box sx={styles.bar}>
+          {isContinuous ? (
+            <Box
+              role='img'
+              aria-label={labels.colorGradient}
+              sx={{ width: '100%', height: '100%', background: gradient }}
+            />
+          ) : (
+            colors.map((color, index) => (
+              <Box
+                key={index}
+                role='img'
+                aria-label={stepAriaLabel(index)}
+                sx={{ ...styles.step, backgroundColor: color }}
+              />
+            ))
+          )}
+        </Box>
+
+        {avgPct != null && data.avg != null && (
+          <Tooltip title={formatValue(data.avg)} placement='top' arrow>
+            {/* Inline style: per-instance dynamic value, no emotion class churn. */}
+            <Box sx={styles.avgLine} style={{ left: `${avgPct}%` }} />
+          </Tooltip>
+        )}
+      </Box>
+
+      {isBoundary ? (
+        <Box sx={styles.boundaryLabels}>
+          {stops.map((stop, index) => {
+            // Interior labels center on their boundary line; the outer two
+            // clamp inside the bar (first left-aligned, last right-aligned)
+            // so the row never overflows.
+            const isLast = index === stops.length - 1
+            const transform =
+              index === 0
+                ? undefined
+                : isLast
+                  ? 'translateX(-100%)'
+                  : 'translateX(-50%)'
+            return (
+              <Typography
+                key={`${stop.label}-${index}`}
+                variant='overline'
+                color='text.secondary'
+                sx={styles.boundaryLabel}
+                style={{
+                  left: `${(index / colors.length) * 100}%`,
+                  transform,
+                }}
+              >
+                {stop.label}
+              </Typography>
+            )
+          })}
+        </Box>
+      ) : (
+        // Continuous gradients show only the range endpoints.
+        <Box sx={styles.labels}>
+          <Typography variant='overline' color='text.secondary'>
+            {first?.label}
+          </Typography>
+          <Typography variant='overline' color='text.secondary'>
+            {last?.label}
+          </Typography>
+        </Box>
+      )}
+    </Box>
+  )
+}