@carto/ps-react-ui 4.12.2 → 4.13.0

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
+    }
+  }
+}

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,179 @@
+import { useState } from 'react'
+import {
+  Box,
+  IconButton,
+  InputAdornment,
+  OutlinedInput,
+  Popover,
+  Slider,
+  Tooltip,
+} from '@mui/material'
+import { Opacity as OpacityIcon } from '@carto/meridian-ds/custom-icons'
+import { useLegendId, 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 header action for a layer row: a checkerboard icon button, pinned
+ * `.active` in the hover-fade group while opacity ≠ 1 or the popover is open,
+ * disabled while the layer is hidden. Opens `Legend.Opacity.Popover` through
+ * the row context. Place it inside `<Legend.Actions>` of a `Legend.Row`.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+function OpacityTrigger() {
+  const id = useLegendId()
+  const row = useLegendRow()
+  const layerId = row?.layerId
+  const opacity = useLegendStore(id, (s) =>
+    layerId ? (s.layers[layerId]?.opacity ?? 1) : 1,
+  )
+  const visible = useLegendStore(id, (s) =>
+    layerId ? (s.layers[layerId]?.visible ?? true) : true,
+  )
+  const { labels } = useLegendConfig()
+
+  // A hidden layer shows only its visibility eye + collapse chevron — the
+  // opacity action disappears entirely until the layer is shown again.
+  if (!row || !visible) return null
+  const dirty = opacity !== 1
+
+  return (
+    // The wrapper keeps the Tooltip working on the button; as the fade
+    // group's direct child it also carries the `.active` pin.
+    <Tooltip title={labels.opacity}>
+      <Box
+        component='span'
+        className={dirty || row.opacityOpen ? 'active' : undefined}
+        sx={styles.triggerWrap}
+      >
+        <IconButton
+          size='small'
+          onClick={() => row.setOpacityOpen(true)}
+          aria-label={labels.opacity}
+        >
+          <OpacityIcon fontSize='small' />
+        </IconButton>
+      </Box>
+    </Tooltip>
+  )
+}
+
+/**
+ * The opacity editing surface — a popover **anchored to the row's sticky
+ * header, spanning its full width**, holding a slider (writes `setOpacity`
+ * only on release, widgets-v2 parity) and a percent input (commits live as
+ * soon as the draft parses, clamped 0–100; never ellipsizes "100 %").
+ * Declare it anywhere inside the `Legend.Row` (it renders in a portal);
+ * open it with `Legend.Opacity.Trigger`.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+function OpacityPopover() {
+  const id = useLegendId()
+  const row = useLegendRow()
+  const layerId = row?.layerId
+  const opacity = useLegendStore(id, (s) =>
+    layerId ? (s.layers[layerId]?.opacity ?? 1) : 1,
+  )
+  const visible = useLegendStore(id, (s) =>
+    layerId ? (s.layers[layerId]?.visible ?? true) : true,
+  )
+  const setOpacity = useLegendStore(id, (s) => s.setOpacity)
+  const { labels } = useLegendConfig()
+
+  // Drag and typing drafts: the thumb and the input track each other through
+  // `percent` while only commits reach the store (and the map).
+  const [dragPercent, setDragPercent] = useState<number | null>(null)
+  const [draft, setDraft] = useState<string | null>(null)
+
+  // The trigger is gone while hidden; also gate `open` so a popover left open
+  // can't survive the layer being hidden elsewhere.
+  if (!row || !layerId || !visible) 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)
+    // Out-of-range entries snap the visible draft to the committed value.
+    if (clamped !== parsed) setDraft(String(clamped))
+  }
+
+  const handleClose = () => {
+    row.setOpacityOpen(false)
+    setDraft(null)
+    setDragPercent(null)
+  }
+
+  return (
+    <Popover
+      open={row.opacityOpen && Boolean(row.headerEl)}
+      anchorEl={row.headerEl}
+      onClose={handleClose}
+      anchorOrigin={{ vertical: 'bottom', horizontal: 'left' }}
+      transformOrigin={{ vertical: 'top', horizontal: 'left' }}
+      // Full row width: the paper matches the sticky header it anchors to.
+      slotProps={{ paper: { sx: { width: row.headerEl?.clientWidth } } }}
+    >
+      <Box sx={styles.popover}>
+        <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)}
+          // An abandoned draft (empty / non-numeric) snaps back to the
+          // store value on blur.
+          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>
+    </Popover>
+  )
+}
+
+/**
+ * Compound opacity control for layer rows (widgets-v2 `FullScreen` parity):
+ * `Trigger` lives in the header `<Legend.Actions>`, `Popover` anywhere in the
+ * row body — they share state through the row context.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export const LegendOpacity = {
+  Trigger: OpacityTrigger,
+  Popover: OpacityPopover,
+}