@carto/ps-react-ui 4.12.1 → 4.13.0

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

@@ -0,0 +1,28 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  // Tooltip wrapper around the (possibly disabled) trigger button. A plain
+  // inline span would be sized by the line box (baseline + descender) and
+  // end up ~1px taller than the 24px button inside.
+  triggerWrap: {
+    display: 'inline-flex',
+  },
+  popover: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 1.5,
+    padding: ({ spacing }) => spacing(1, 1.5),
+    width: 280,
+  },
+  slider: {
+    flex: 1,
+  },
+  // Wide enough for "100 %" — the value must never ellipsize.
+  input: {
+    width: 76,
+    flexShrink: 0,
+    '& input': {
+      textAlign: 'right',
+    },
+  },
+} satisfies Record<string, SxProps<Theme>>

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,159 @@
+import { Box, Tooltip, Typography } from '@mui/material'
+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>
+  )
+}

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

@@ -0,0 +1,62 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  container: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 0.5,
+  },
+  attribute: {
+    display: 'flex',
+    flexDirection: 'column',
+  },
+  // Inline error shown when a discrete ramp's stop count is incoherent.
+  error: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 0.5,
+    color: 'error.main',
+  },
+  // Positioning context for the avg marker; the inner bar keeps its rounded
+  // clip while the line is free to overflow vertically.
+  barWrap: {
+    position: 'relative',
+  },
+  bar: {
+    height: 8,
+    borderRadius: '2px',
+    overflow: 'hidden',
+    display: 'flex',
+  },
+  avgLine: {
+    position: 'absolute',
+    top: -2,
+    bottom: -2,
+    width: 0,
+    borderLeft: '1.5px dashed',
+    borderColor: 'text.primary',
+    transform: 'translateX(-50%)',
+  },
+  step: {
+    flex: 1,
+    height: '100%',
+  },
+  labels: {
+    display: 'flex',
+    justifyContent: 'space-between',
+    gap: 1,
+  },
+  // Boundary mode: labels absolutely positioned so each centers on the line
+  // between adjacent color steps. The outer two clamp inside the bar's width
+  // (first left-aligned, last right-aligned) so nothing overflows the row.
+  // `left`/`transform` are applied inline per label in the renderer.
+  boundaryLabels: {
+    position: 'relative',
+    height: 16,
+  },
+  boundaryLabel: {
+    position: 'absolute',
+    top: 0,
+    whiteSpace: 'nowrap',
+  },
+} satisfies Record<string, SxProps<Theme>>