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

package/src/hooks/use-skeleton.ts

@@ -0,0 +1,19 @@
+import { useState } from 'react'
+
+export function useSkeleton(isLoading: boolean) {
+  // Track render phase: 0=never shown, 1=showing now, 2=already shown
+  const [phase, setPhase] = useState(() => (isLoading ? 1 : 0))
+
+  // Transition from phase 0 to 1 when loading starts
+  if (isLoading && phase === 0) {
+    setPhase(1)
+  }
+
+  // Transition from phase 1 to 2 when loading ends (skeleton was shown, now done)
+  if (!isLoading && phase === 1) {
+    setPhase(2)
+  }
+
+  // Show skeleton only in phase 1 (first time loading)
+  return phase === 1
+}

package/src/hooks/use-widget-ref.ts

@@ -0,0 +1,34 @@
+import { useEffect, useRef } from 'react'
+import type * as echarts from 'echarts'
+import { widgetStoreActions } from '../widgets/stores/widget-store'
+
+/**
+ * Registers a DOM element ref and an ECharts instance ref with the widget store.
+ * This allows other parts of the application (e.g., screenshot export) to access the widget's DOM element.
+ *
+ * @param widgetId - The widget ID to register the refs under.
+ * @returns An object with `ref` (DOM element) and `instance` (ECharts instance) refs.
+ *
+ * @example
+ * ```tsx
+ * function MyWidget({ id }: { id: string }) {
+ *   const { ref } = useWidgetRef<HTMLDivElement>(id)
+ *
+ *   return <div ref={ref}>Widget content</div>
+ * }
+ * ```
+ */
+export function useWidgetRef<T extends HTMLElement = HTMLElement>(
+  widgetId: string,
+) {
+  const ref = useRef<T | null>(null)
+  const instance = useRef<echarts.ECharts | null>(null)
+
+  useEffect(() => {
+    if (ref.current) {
+      widgetStoreActions.setWidget(widgetId, { refUI: ref, instance: instance })
+    }
+  }, [widgetId])
+
+  return { ref, instance }
+}

package/src/legend/components/a11y.ts

@@ -0,0 +1,14 @@
+import type { KeyboardEvent } from 'react'
+
+/**
+ * Enter/Space activate a non-native `role='button'` element (the accordion
+ * title areas of `Legend.Row` / `Legend.Group`), like a real button.
+ */
+export function accordionKeyDown(toggle: () => void) {
+  return (event: KeyboardEvent<HTMLElement>) => {
+    if (event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault()
+      toggle()
+    }
+  }
+}

package/src/legend/components/contexts.ts

@@ -0,0 +1,57 @@
+import { createContext, useContext } from 'react'
+
+/**
+ * Per-row composition context provided by `Legend.Row`. Actions placed inside
+ * the row resolve their target layer from here instead of taking a `layerId`
+ * prop, and the opacity compound (`Legend.Opacity.Item` / `.Inline`) shares
+ * its open state through it.
+ */
+export interface LegendRowContextValue {
+  layerId: string
+  opacityOpen: boolean
+  setOpacityOpen: (open: boolean) => void
+}
+
+export const LegendRowContext = createContext<LegendRowContextValue | null>(
+  null,
+)
+
+/** Nearest `Legend.Row` composition context, or `null` outside a row. */
+export function useLegendRow(): LegendRowContextValue | null {
+  return useContext(LegendRowContext)
+}
+
+/** Per-group composition context provided by `Legend.Group` (the group id). */
+export const LegendGroupContext = createContext<string | null>(null)
+
+/** Nearest `Legend.Group` id, or `null` outside a group. */
+export function useLegendGroupId(): string | null {
+  return useContext(LegendGroupContext)
+}
+
+/**
+ * Overflow-menu controller for `Legend.RowMenu` / `Legend.GroupMenu` /
+ * `Legend.PanelMenu`. Async items (e.g. `Legend.ZoomTo`) use `setBusy` to keep
+ * the menu open and show in-item loading feedback, then `close()` when the
+ * handler settles. Prefer `runAsyncMenuAction` over calling these by hand.
+ */
+export interface LegendMenuController {
+  /** Reactive busy flag for UI (spinner / disabled). */
+  busy: boolean
+  /**
+   * Synchronous busy check (ref-backed) — use this to gate clicks so a second
+   * press before React re-renders cannot start another async action.
+   */
+  isBusy: () => boolean
+  setBusy: (busy: boolean) => void
+  close: () => void
+}
+
+export const LegendMenuContext = createContext<LegendMenuController | null>(
+  null,
+)
+
+/** Nearest overflow-menu controller, or `null` outside a row/group menu. */
+export function useLegendMenu(): LegendMenuController | null {
+  return useContext(LegendMenuContext)
+}

package/src/legend/components/icons.tsx

@@ -0,0 +1,22 @@
+import { createSvgIcon } from '@mui/material'
+
+/**
+ * Indeterminate visibility — an outlined eye with an internal slash, shown on
+ * a group whose member layers are partially hidden ("mixed" state). Path data
+ * exported from the Figma source (`MUI_visibility_indeterminate`, CARTO PS Lib
+ * Documentation node 5877-16982); the glyph is centered at (184, 24) in the
+ * header frame and drawn on a 18px grid (75% of the 24px box), so it is
+ * re-centered into the standard viewBox and scaled by 4/3 — the resulting
+ * 22×15-unit eye matches the MUI `Visibility*` icons exactly.
+ */
+export const VisibilityIndeterminateIcon = createSvgIcon(
+  <g transform='translate(12 12) scale(1.33333) translate(-184 -24)'>
+    <path
+      fillRule='evenodd'
+      clipRule='evenodd'
+      d='M184.901 29.5794L185.217 29.5415C185.803 29.4604 186.372 29.3216 186.918 29.1319L187 29.1007L187 29.1033L187.208 29.0255L187.536 28.8904C187.722 28.8088 187.906 28.721 188.086 28.6272L188.366 28.4747C188.381 28.4663 188.395 28.4578 188.41 28.4493C188.418 28.4451 188.425 28.4408 188.432 28.4365C188.455 28.4234 188.478 28.4102 188.5 28.3969C188.551 28.3668 188.601 28.3362 188.652 28.3052L188.912 28.1374C189.598 27.6788 190.217 27.1271 190.75 26.5002L190.751 26.4954C190.989 26.2164 191.21 25.9226 191.413 25.6152C191.488 25.5007 191.561 25.3843 191.631 25.2662L191.757 25.0445L191.878 24.8189L192.021 24.5306L192.15 24.2443L192.25 24C190.98 20.7776 187.885 18.4747 184.239 18.3782L184 18.375L183.716 18.3795L183.637 18.3823L183.373 18.3967L183.103 18.4198L182.838 18.4506L182.666 18.4749L182.426 18.5146C182.19 18.557 181.957 18.6087 181.728 18.6684L181.55 18.7175L181.271 18.8039L182.508 20.04L182.801 19.9854C183.194 19.9182 183.592 19.875 184 19.875C186.842 19.875 189.378 21.4725 190.615 24C190.172 24.915 189.55 25.7025 188.807 26.34L188.811 26.3446C188.71 26.4323 188.606 26.5172 188.5 26.5991C188.455 26.6337 188.41 26.6679 188.364 26.7015C188.108 26.8897 187.84 27.0611 187.562 27.2145C187.088 27.4755 186.585 27.6844 186.058 27.836L186.062 27.84L185.778 27.9125C185.707 27.9293 185.635 27.9452 185.563 27.9602C185.297 28.0173 185.025 28.06 184.75 28.0876V28.0866C184.503 28.1118 184.253 28.125 184 28.125C181.158 28.125 178.622 26.5275 177.385 24C177.91 22.9275 178.675 22.0425 179.582 21.3525L180.895 22.665L180.826 22.844C180.697 23.2065 180.625 23.595 180.625 24C180.625 25.86 182.14 27.375 184 27.375C184.258 27.375 184.509 27.3459 184.75 27.2915C185.462 27.129 186.09 26.7397 186.553 26.2048L179.79 19.4389C179.339 19.6833 178.912 19.9656 178.512 20.2817L178.517 20.2875L178.271 20.4884C177.704 20.9671 177.197 21.516 176.766 22.1227C176.404 22.6333 176.095 23.1838 175.845 23.7662L175.75 24C177.048 27.2925 180.25 29.625 184 29.625L184.285 29.6205L184.492 29.6116L184.628 29.6025L184.901 29.5794ZM182.133 23.9025L184.09 25.86L184.045 25.8703L184 25.875C182.965 25.875 182.125 25.035 182.125 24L182.133 23.9025Z'
+    />
+    <path d='M187.368 23.9925C187.375 22.1325 185.86 20.625 184 20.625C183.722 20.625 183.46 20.6625 183.198 20.73L184.75 22.2825L184.889 22.3507C185.252 22.5477 185.543 22.8625 185.71 23.2425L187.263 24.795L187.304 24.6011C187.342 24.4045 187.368 24.2006 187.368 23.9925Z' />
+  </g>,
+  'VisibilityIndeterminate',
+)

package/src/legend/components/index.ts

@@ -0,0 +1,38 @@
+export { LegendGroup } from './legend-group/legend-group'
+export type { LegendGroupProps } from './legend-group/legend-group'
+export { LegendRow } from './legend-row/legend-row'
+export type { LegendRowProps } from './legend-row/legend-row'
+export { LegendActions } from './legend-actions/legend-actions'
+export type { LegendActionsProps } from './legend-actions/legend-actions'
+export {
+  LegendRowContext,
+  LegendGroupContext,
+  LegendMenuContext,
+  useLegendRow,
+  useLegendGroupId,
+  useLegendMenu,
+} from './contexts'
+export type { LegendRowContextValue, LegendMenuController } from './contexts'
+
+export { LegendVisibilityToggle } from './legend-visibility-toggle/legend-visibility-toggle'
+export { LegendRowMenu } from './legend-row-menu/legend-row-menu'
+export { LegendZoomTo } from './legend-row-menu/legend-zoom-to'
+export { LegendOpacity } from './legend-opacity/legend-opacity'
+export { LegendConfigSelect } from './legend-config-select/legend-config-select'
+export { LegendItem } from './legend-item/legend-item'
+
+export { LegendItemUI } from './legend-item/legend-item-ui'
+export type { LegendItemUIProps } from './legend-item/legend-item-ui'
+export {
+  LegendSwatch,
+  DEFAULT_SWATCH_SIZE,
+} from './legend-swatch/legend-swatch'
+export type { LegendSwatchProps } from './legend-swatch/legend-swatch'
+export { LegendCategoryUI } from './legend-category/legend-category-ui'
+export type { LegendCategoryUIProps } from './legend-category/legend-category-ui'
+export { LegendRampUI } from './legend-ramp/legend-ramp-ui'
+export type { LegendRampUIProps } from './legend-ramp/legend-ramp-ui'
+export { LegendProportionUI } from './legend-proportion/legend-proportion-ui'
+export type { LegendProportionUIProps } from './legend-proportion/legend-proportion-ui'
+export { LegendIconUI } from './legend-icon/legend-icon-ui'
+export type { LegendIconUIProps } from './legend-icon/legend-icon-ui'

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

@@ -0,0 +1,58 @@
+import {
+  Children,
+  isValidElement,
+  type ReactElement,
+  type ReactNode,
+} from 'react'
+import { Box } from '@mui/material'
+import { useLegendRow } from '../contexts'
+import { styles } from './styles'
+
+export interface LegendActionsProps {
+  children?: ReactNode
+}
+
+/**
+ * Header actions slot for `Legend.Row` / `Legend.Group` (widgets-v2 `Actions`
+ * parity): the wrapper partitions its children by component identity and
+ * renders this slot inside the header, wrapped in the hover-fade group
+ * (`PsLegend-rowFade` in rows, `PsLegend-groupFade` in group headers —
+ * resolved from the nearest context). Compose the visibility toggle last so
+ * it sits rightmost, per design.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendActions({ children }: LegendActionsProps) {
+  const inRow = useLegendRow() !== null
+  return (
+    <Box
+      className={inRow ? 'PsLegend-rowFade' : 'PsLegend-groupFade'}
+      sx={styles.fadeGroup}
+    >
+      {children}
+    </Box>
+  )
+}
+
+/**
+ * Splits a wrapper's children by component identity: `<Legend.Actions>`
+ * elements belong in the header, everything else in the collapsible body.
+ * Identity comparison works because consumers import the slot from the same
+ * module (same pattern as widgets-v2 `Wrapper`).
+ */
+export function partitionLegendChildren(children: ReactNode): {
+  actions: ReactNode[]
+  body: ReactNode[]
+} {
+  const actions: ReactNode[] = []
+  const body: ReactNode[] = []
+  for (const child of Children.toArray(children)) {
+    if (isSlot(child, LegendActions)) actions.push(child)
+    else body.push(child)
+  }
+  return { actions, body }
+}
+
+function isSlot(node: ReactNode, type: unknown): node is ReactElement {
+  return isValidElement(node) && node.type === type
+}

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

@@ -0,0 +1,9 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  fadeGroup: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 0.25,
+  },
+} satisfies Record<string, SxProps<Theme>>

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

@@ -0,0 +1,91 @@
+import { Box, Typography } from '@mui/material'
+import { styles } from './styles'
+import {
+  LegendSwatch,
+  DEFAULT_SWATCH_SIZE,
+} from '../legend-swatch/legend-swatch'
+import type { LegendCategoryVariable } from '../../stores'
+
+export interface LegendCategoryUIProps {
+  data: LegendCategoryVariable
+}
+
+const MIN_GUTTER = 16
+
+/**
+ * Categorical legend — a list of swatches with labels (and optional trailing
+ * values, compact-formatted). The variable-level shape / fill pattern /
+ * stroke style / `isStrokeColor` act as defaults; each item may override any
+ * of them, so one list can mix patterns (or shapes) across entries.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendCategoryUI({ data }: LegendCategoryUIProps) {
+  const {
+    items,
+    shape = 'circle',
+    isStrokeColor = false,
+    fillPattern = 'solid',
+    strokeStyle = 'solid',
+    orientation = 'vertical',
+  } = data
+  const horizontal = orientation === 'horizontal'
+
+  // Fixed gutter wide enough for the largest swatch so labels align — only
+  // meaningful in the vertical list; horizontal chips size to content.
+  const maxSize = items.reduce(
+    (m, it) => Math.max(m, it.size ?? DEFAULT_SWATCH_SIZE),
+    0,
+  )
+  const gutter = Math.max(MIN_GUTTER, maxSize)
+
+  return (
+    <Box
+      data-orientation={orientation}
+      sx={{ ...styles.list, ...(horizontal ? styles.listHorizontal : null) }}
+    >
+      {items.map((item, index) => (
+        <Box
+          key={`${item.label}-${index}`}
+          sx={{
+            ...styles.item,
+            ...(horizontal ? styles.itemHorizontal : null),
+          }}
+        >
+          <Box
+            sx={{ ...styles.gutter, width: horizontal ? undefined : gutter }}
+          >
+            <LegendSwatch
+              shape={item.shape ?? shape}
+              color={item.color}
+              isStrokeColor={item.isStrokeColor ?? isStrokeColor}
+              fillPattern={item.fillPattern ?? fillPattern}
+              strokeStyle={item.strokeStyle ?? strokeStyle}
+              size={item.size ?? DEFAULT_SWATCH_SIZE}
+            />
+          </Box>
+          <Typography
+            variant='caption'
+            color='text.primary'
+            sx={{
+              ...styles.label,
+              ...(horizontal ? styles.labelHorizontal : null),
+            }}
+          >
+            {item.label}
+          </Typography>
+          {item.value != null && (
+            <Typography
+              className='PsLegend-value'
+              variant='caption'
+              color='text.secondary'
+              sx={styles.value}
+            >
+              {item.value}
+            </Typography>
+          )}
+        </Box>
+      ))}
+    </Box>
+  )
+}

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

@@ -0,0 +1,61 @@
+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,
+  },
+  // Fixed-width gutter so labels stay column-aligned regardless of swatch
+  // shape or per-item size; the swatch is centered within it.
+  gutter: {
+    flexShrink: 0,
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  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) ───
+  // Items flow left-to-right and wrap; each is a compact swatch+label pair.
+  listHorizontal: {
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    columnGap: 2,
+    rowGap: 0.5,
+  },
+  // No fixed gutter — the swatch sits at its natural size next to the label.
+  itemHorizontal: {
+    gap: 0.5,
+  },
+  // Each chip sizes to its content (no flex-grow / ellipsis).
+  labelHorizontal: {
+    flex: '0 0 auto',
+    overflow: 'visible',
+    textOverflow: 'clip',
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/legend/components/legend-config-select/legend-config-select.tsx

@@ -0,0 +1,96 @@
+import { useState } from 'react'
+import { ButtonBase, Menu, MenuItem, Typography } from '@mui/material'
+import { ArrowDropDown as ArrowDropDownIcon } from '@mui/icons-material'
+import { useLegendId, useLegendShallow } from '../../stores'
+import { useLegendConfig } from '../../provider'
+import { useLegendRow } from '../contexts'
+import { styles } from './styles'
+
+/**
+ * The layer configuration select — resolves its layer from the enclosing
+ * `Legend.Row` context. The closed field shows the **first section's** active
+ * option; the menu lists every section under its title (omitted when the
+ * layer has a single section) and each section highlights its own active
+ * option. Picking an option writes `setSectionValue` and closes the menu.
+ * Renders nothing when the layer declares no sections (or outside a row).
+ *
+ * A native single-value `Select` can't represent one active per section,
+ * hence the outlined-trigger + `Menu` composition.
+ *
+ * @experimental This API is new and may change in a future release.
+ */
+export function LegendConfigSelect() {
+  const id = useLegendId()
+  const row = useLegendRow()
+  const layerId = row?.layerId
+  const sections = useLegendShallow(id, (s) =>
+    layerId ? s.layers[layerId]?.sections : undefined,
+  )
+  const setSectionValue = useLegendShallow(id, (s) => s.setSectionValue)
+  const { labels } = useLegendConfig()
+  const [anchorEl, setAnchorEl] = useState<HTMLElement | null>(null)
+  const open = Boolean(anchorEl)
+
+  if (!layerId || !sections || sections.length === 0) return null
+
+  const display = sections[0]!.active
+  const showTitles = sections.length > 1
+
+  return (
+    <>
+      <ButtonBase
+        sx={styles.trigger}
+        onClick={(event) => setAnchorEl(event.currentTarget)}
+        aria-label={labels.attribute}
+        aria-haspopup='listbox'
+        aria-expanded={open}
+      >
+        <Typography variant='body2' sx={styles.value}>
+          {display}
+        </Typography>
+        <ArrowDropDownIcon
+          fontSize='small'
+          sx={
+            open ? { ...styles.chevron, ...styles.chevronOpen } : styles.chevron
+          }
+        />
+      </ButtonBase>
+
+      <Menu
+        anchorEl={anchorEl}
+        open={open}
+        onClose={() => setAnchorEl(null)}
+        slotProps={{
+          paper: { sx: { width: anchorEl?.clientWidth } },
+        }}
+      >
+        {sections.map((section) => [
+          showTitles && section.title ? (
+            <Typography
+              key={`${section.id}-title`}
+              variant='overline'
+              color='text.secondary'
+              component='li'
+              sx={styles.sectionTitle}
+            >
+              {section.title}
+            </Typography>
+          ) : null,
+          ...section.options.map((option) => (
+            <MenuItem
+              key={`${section.id}-${option}`}
+              selected={option === section.active}
+              sx={styles.option}
+              onClick={() => {
+                setSectionValue(layerId, section.id, option)
+                setAnchorEl(null)
+              }}
+            >
+              {option}
+            </MenuItem>
+          )),
+        ])}
+      </Menu>
+    </>
+  )
+}

package/src/legend/components/legend-config-select/styles.ts

@@ -0,0 +1,48 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  // Outlined-input look-alike trigger (the design's select has no floating
+  // label — just the value + chevron in a 32px bordered field).
+  trigger: {
+    width: '100%',
+    minHeight: 32,
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    gap: 1,
+    padding: ({ spacing }) => spacing(0, 1.5),
+    border: '1px solid',
+    borderColor: 'divider',
+    borderRadius: 1,
+    backgroundColor: 'background.paper',
+    color: 'text.primary',
+    '&:hover': {
+      borderColor: 'text.primary',
+    },
+  },
+  value: {
+    minWidth: 0,
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+  },
+  chevron: {
+    flexShrink: 0,
+    color: 'action.active',
+    transition: ({ transitions }: Theme) => transitions.create('transform'),
+  },
+  chevronOpen: {
+    transform: 'rotate(180deg)',
+  },
+  sectionTitle: {
+    padding: ({ spacing }) => spacing(1, 2, 0.5, 2),
+    lineHeight: 1.5,
+  },
+  // Figma: the active option reads as primary-colored text, no background.
+  option: {
+    '&.Mui-selected, &.Mui-selected:hover': {
+      backgroundColor: 'transparent',
+      color: 'primary.main',
+    },
+  },
+} satisfies Record<string, SxProps<Theme>>