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

package/src/components/lasso-tool/lasso-tool.tsx

@@ -0,0 +1,673 @@
+import {
+  ArrowDropDown,
+  LayersOutlined,
+  MoreVertOutlined,
+} from '@mui/icons-material'
+import {
+  Box,
+  Divider,
+  IconButton,
+  ListItemIcon,
+  ListItemText,
+  Menu,
+  MenuItem,
+  Paper,
+  SvgIcon,
+  ToggleButton,
+  Typography,
+  type SxProps,
+  type Theme,
+} from '@mui/material'
+import deepmerge from 'deepmerge'
+import {
+  useMemo,
+  useState,
+  type ComponentProps,
+  type JSX,
+  type MouseEvent,
+  type PropsWithChildren,
+  type ReactNode,
+} from 'react'
+import type { PickDeep } from 'type-fest'
+import { Tooltip } from '../tooltip/tooltip'
+import type { LassoToolsModes } from '../types'
+import { LassoToolsUIChip } from './chip'
+import { LASSO_TOOLS_LABELS } from './const'
+import { InteractionModeSection } from './options-sections'
+import { LassoUndoRedoUI } from './undo-redo'
+import { LassoToolsUIProvider, useLassoToolsUIArgs } from './tools-context'
+import { mergeSx, styles } from './styles'
+import type {
+  LassoToolsComponentProps,
+  LassoToolsUIContextValue,
+  OptionsChildrenProps,
+} from './types'
+
+const EMPTY_VALUES: LassoToolsComponentProps['values'] = []
+const EMPTY_PAPER_PROPS: NonNullable<LassoToolsComponentProps['PaperProps']> =
+  {}
+
+/**
+ * Floating interface for spatial selection and drawing — a shell that publishes
+ * wiring props on context. **Which blocks it has is the consumer's call** —
+ * list them as children. See `stories/modules/lasso/lasso-tools-toolbar.tsx`
+ * for the full CARTO design.
+ *
+ * @example
+ * ```tsx
+ * <LassoToolsUI {...props}>
+ *   <LassoToolsUI.Action />
+ *   <LassoToolsUI.OptionsMenu />
+ *   <LassoToolsUI.UndoRedo />
+ *   <LassoToolsUI.Chips />
+ *   <LassoToolsUI.SecondaryActions />
+ * </LassoToolsUI>
+ * ```
+ */
+export function LassoToolsUI({
+  enabled,
+  values = EMPTY_VALUES,
+  actionProps,
+  chipProps,
+  labels,
+  modes,
+  modesMapping,
+  modeSelected,
+  interactionMode,
+  PaperProps: { sx, ...PaperProps } = EMPTY_PAPER_PROPS,
+  onActionToggle,
+  onChipToggle,
+  onDelete,
+  onChangeMode,
+  onChangeInteractionMode,
+  interactionModeMaskDisabled,
+  onAllChipToggle,
+  onAllDelete,
+  onLayerFilters,
+  canUndo,
+  canRedo,
+  onUndo,
+  onRedo,
+  shortcuts,
+  children,
+}: LassoToolsComponentProps): JSX.Element {
+  const contextValue: LassoToolsUIContextValue = {
+    enabled,
+    values,
+    actionProps,
+    chipProps,
+    labels,
+    modes,
+    modesMapping,
+    modeSelected,
+    interactionMode,
+    PaperProps,
+    onActionToggle,
+    onChipToggle,
+    onDelete,
+    onChangeMode,
+    onChangeInteractionMode,
+    interactionModeMaskDisabled,
+    onAllChipToggle,
+    onAllDelete,
+    onLayerFilters,
+    canUndo,
+    canRedo,
+    onUndo,
+    onRedo,
+    shortcuts,
+  }
+  return (
+    <Paper
+      // Array merge: `sx` can be an object, a function or an array (see mergeSx).
+      sx={mergeSx(styles.container, sx)}
+      {...PaperProps}
+    >
+      <LassoToolsUIProvider value={contextValue}>
+        {children}
+      </LassoToolsUIProvider>
+    </Paper>
+  )
+}
+
+function LassoToolsUIAction({
+  actionProps,
+  labels,
+  enabled,
+  children,
+  onActionToggle,
+}: PropsWithChildren<
+  Pick<
+    LassoToolsComponentProps,
+    'actionProps' | 'enabled' | 'onActionToggle'
+  > & {
+    labels?: PickDeep<LassoToolsComponentProps['labels'], 'action'>['action']
+  }
+>) {
+  const actionState = enabled ? 'active' : 'inactive'
+  const actionLabel =
+    labels?.tooltip?.[actionState] ??
+    LASSO_TOOLS_LABELS.action.tooltip[actionState]
+
+  return (
+    <Tooltip
+      title={actionLabel}
+      placement='right'
+      {...actionProps?.TooltipProps}
+    >
+      <ToggleButton
+        value='toggle'
+        sx={styles.actions.icon}
+        onClick={() => onActionToggle(!enabled)}
+        aria-label={actionLabel}
+        selected={enabled}
+      >
+        {children}
+      </ToggleButton>
+    </Tooltip>
+  )
+}
+
+const EMPTY_TRIGGER_PROPS: { Icon?: ReactNode; sx?: SxProps<Theme> } = {}
+
+function Options({
+  TriggerProps = EMPTY_TRIGGER_PROPS,
+  MenuProps,
+  children,
+}: {
+  TriggerProps?: {
+    Icon?: ReactNode
+    sx?: SxProps<Theme>
+    /** Accessible name for the (icon-only) trigger button. */
+    'aria-label'?: string
+  }
+  MenuProps?: Partial<ComponentProps<typeof Menu>>
+  children: (props: OptionsChildrenProps) => JSX.Element
+}) {
+  const {
+    Icon,
+    sx,
+    'aria-label': ariaLabel = LASSO_TOOLS_LABELS.options.mode.title,
+  } = TriggerProps
+  const IconNode = Icon ?? <ArrowDropDown />
+
+  const [anchorEl, setAnchorEl] = useState<null | HTMLElement>(null)
+
+  const open = Boolean(anchorEl)
+
+  const handleToggle = (event: MouseEvent<HTMLButtonElement>) => {
+    setAnchorEl(event.currentTarget)
+  }
+
+  const handleClose = () => {
+    setAnchorEl(null)
+  }
+
+  return (
+    <>
+      <IconButton
+        aria-label={ariaLabel}
+        sx={mergeSx(styles.options.icon, sx)}
+        onClick={handleToggle}
+      >
+        {IconNode}
+      </IconButton>
+      <Menu
+        id='lasso-menu'
+        anchorEl={anchorEl}
+        open={open}
+        onClose={handleClose}
+        MenuListProps={{
+          sx: styles.options.menu,
+          // Focus the LIST on open. The menu's children come from a render
+          // prop (a component element), so MUI can never index an item to
+          // auto-focus: focus would stay on the Paper and the first ArrowDown
+          // would escape to the focus-trap sentinel — keyboard-unreachable.
+          // With the list focused, arrow keys traverse the DOM children.
+          autoFocus: true,
+        }}
+        // The paper carries the same height ceiling as the list — it clips it
+        // otherwise. `slotProps.paper` because `PaperProps` is deprecated.
+        slotProps={{ paper: { sx: styles.options.paper } }}
+        {...MenuProps}
+      >
+        {/* No wrapper: MenuList expects its MenuItem/Divider children
+            directly, or arrow-key navigation and typeahead break. */}
+        {children({ onClose: handleClose })}
+      </Menu>
+    </>
+  )
+}
+
+function ModeList({
+  data,
+  labels,
+  children,
+}: {
+  labels?: PickDeep<LassoToolsComponentProps['labels'], 'options'>['options']
+  data: LassoToolsComponentProps['modes'][keyof LassoToolsModes][]
+  children: ReactNode
+}) {
+  if (data.length <= 1) {
+    return null
+  }
+
+  const modeTitle = labels?.mode?.title ?? LASSO_TOOLS_LABELS.options.mode.title
+
+  return (
+    <>
+      <Typography
+        variant='subtitle2'
+        color='text.secondary'
+        sx={styles.options.title}
+      >
+        {modeTitle}
+      </Typography>
+      {children}
+    </>
+  )
+}
+
+function OptionsList({
+  data,
+  modeSelected,
+  labels,
+  onChangeMode,
+  onClose,
+}: Required<Pick<LassoToolsComponentProps, 'modeSelected' | 'onChangeMode'>> & {
+  labels?: PickDeep<LassoToolsComponentProps['labels'], 'options'>['options']
+  data: (LassoToolsComponentProps['modes'] &
+    LassoToolsComponentProps['modesMapping'])[keyof LassoToolsModes][]
+  onClose: OptionsChildrenProps['onClose']
+}) {
+  const handleClick = (
+    e: MouseEvent<HTMLLIElement>,
+    value: NonNullable<(typeof data)[number]>['value'],
+  ) => {
+    e.preventDefault()
+    onChangeMode?.(value)
+    onClose()
+  }
+
+  return (
+    data
+      // `modesMapping` keys with no matching `modes` entry carry an icon but no
+      // `value`: unselectable and unlabelled, so they never render.
+      .filter((mode): mode is NonNullable<typeof mode> => Boolean(mode?.value))
+      .map((mode) => {
+        const options =
+          labels?.mode?.options ?? LASSO_TOOLS_LABELS.options.mode.options
+        // Falls back to the raw value for a custom mode the caller didn't
+        // label: an empty ListItemText would otherwise leave the item with
+        // no visible text and no accessible name.
+        const label = options[mode.value] ?? mode.value
+
+        return (
+          <MenuItem
+            key={mode.value}
+            disabled={!!mode.disabled}
+            onClick={(e) => handleClick(e, mode.value)}
+            selected={mode.value === modeSelected}
+          >
+            <ListItemIcon sx={styles.options.icons}>
+              {/* Deliberate svg-in-svg: see the inline OptionsList's note. */}
+              <SvgIcon>{mode.icon}</SvgIcon>
+            </ListItemIcon>
+            <ListItemText>{label}</ListItemText>
+          </MenuItem>
+        )
+      })
+  )
+}
+
+function SecondaryActionsWrapper({
+  values,
+  labels,
+  onAllChipToggle,
+  onAllDelete,
+}: LassoToolsUIContextValue) {
+  // Chip strip is mask-only; omit draw even if a caller passes them.
+  const chipValues = values?.filter((value) => value.type !== 'draw') ?? []
+
+  if (chipValues.length <= 1) {
+    return null
+  }
+
+  const hasVisible = chipValues.some((value) => value.visible)
+
+  const toggleAllLabel = hasVisible
+    ? (labels?.actions?.toggleAll?.active ??
+      LASSO_TOOLS_LABELS.actions.toggleAll.active)
+    : (labels?.actions?.toggleAll?.inactive ??
+      LASSO_TOOLS_LABELS.actions.toggleAll.inactive)
+
+  const deleteAllLabel =
+    labels?.actions?.deleteAll ?? LASSO_TOOLS_LABELS.actions.deleteAll
+
+  return (
+    <>
+      <Divider orientation='vertical' flexItem />
+      <Options
+        TriggerProps={{
+          Icon: <MoreVertOutlined />,
+          sx: styles.options.more,
+          'aria-label':
+            labels?.actions?.more ?? LASSO_TOOLS_LABELS.actions.more,
+        }}
+        MenuProps={{
+          anchorOrigin: {
+            vertical: 'bottom',
+            horizontal: 'right',
+          },
+          transformOrigin: {
+            vertical: 'top',
+            horizontal: 'right',
+          },
+        }}
+      >
+        {(props) => {
+          return (
+            <>
+              <MenuItem
+                color='inherit'
+                onClick={() => {
+                  onAllChipToggle?.()
+                  props.onClose()
+                }}
+              >
+                {toggleAllLabel}
+              </MenuItem>
+              <Divider />
+              <MenuItem
+                color='error'
+                onClick={() => {
+                  onAllDelete?.()
+                  props.onClose()
+                }}
+              >
+                <Typography variant='body2' color='error'>
+                  {deleteAllLabel}
+                </Typography>
+              </MenuItem>
+            </>
+          )
+        }}
+      </Options>
+    </>
+  )
+}
+
+const ActionsWrapperBase = function ActionsWrapperBase({
+  modes,
+  modesMapping,
+  modeSelected,
+  actionProps,
+  enabled,
+  labels,
+  onActionToggle,
+}: LassoToolsUIContextValue & {
+  labels?: PickDeep<LassoToolsComponentProps['labels'], 'actions'>['actions']
+}) {
+  const data = useMemo(() => {
+    return deepmerge(modes ?? {}, modesMapping ?? {})
+  }, [modes, modesMapping])
+
+  const handleToggle: LassoToolsComponentProps['onActionToggle'] = (data) => {
+    return onActionToggle?.(data)
+  }
+
+  const modeExists = modeSelected ? modeSelected in (modes ?? {}) : false
+
+  // Fallback taken from `modes`, not from the merge: a `modesMapping`-only key
+  // is not a real mode and must never be marked as the active one.
+  const mode = (modeExists ? modeSelected : Object.keys(modes ?? {})[0]) as
+    keyof typeof data | undefined
+
+  // Guarded: an empty `modes` registry leaves no fallback key at all, and
+  // indexing with `undefined` would silently coerce to the string key
+  // "undefined" instead of just being unset.
+  const modeSelectedValue = mode != null ? data[mode] : null
+
+  return (
+    <LassoToolsUIAction
+      actionProps={actionProps}
+      labels={labels?.action}
+      enabled={enabled ?? false}
+      onActionToggle={handleToggle}
+    >
+      {modeSelectedValue?.icon}
+    </LassoToolsUIAction>
+  )
+}
+
+const ChipsWrapperBase = function ChipsWrapperBase({
+  values,
+  labels,
+  chipProps,
+  onDelete,
+  onChipToggle,
+  onActionToggle,
+}: LassoToolsUIContextValue) {
+  const handleDelete: LassoToolsComponentProps['onDelete'] = (valueId) => {
+    onActionToggle?.(false)
+    return onDelete?.(valueId)
+  }
+
+  // Chip strip is mask-only; omit draw even if a caller passes them.
+  // Undefined type = legacy mask and is kept.
+  const chipValues = values?.filter((value) => value.type !== 'draw') ?? []
+
+  return (
+    !!chipValues.length && (
+      <Box sx={styles.chip.container}>
+        {chipValues.map((value) => (
+          <LassoToolsUIChip
+            key={value.id}
+            value={value}
+            labels={labels?.chip}
+            chipProps={chipProps}
+            onDelete={handleDelete}
+            onChipToggle={(id, data) => onChipToggle?.(id, data)}
+          />
+        ))}
+      </Box>
+    )
+  )
+}
+
+const SecondaryActionsWrapperBase = SecondaryActionsWrapper
+
+const UndoRedoWrapperBase = function UndoRedoWrapperBase({
+  enabled,
+  labels,
+  canUndo,
+  canRedo,
+  onUndo,
+  onRedo,
+  shortcuts,
+}: LassoToolsUIContextValue) {
+  // Only meaningful while the tool is on and history handlers are wired.
+  if (!enabled || !onUndo || !onRedo) {
+    return null
+  }
+
+  return (
+    <>
+      <Divider orientation='vertical' flexItem />
+      <LassoUndoRedoUI
+        canUndo={!!canUndo}
+        canRedo={!!canRedo}
+        onUndo={onUndo}
+        onRedo={onRedo}
+        labels={labels?.undoRedo}
+        shortcuts={shortcuts}
+      />
+    </>
+  )
+}
+
+const OptionsWrapperBase = function OptionsWrapperBase({
+  modes,
+  modesMapping,
+  modeSelected,
+  interactionMode,
+  interactionModeMaskDisabled,
+  labels,
+  onChangeMode,
+  onChangeInteractionMode,
+  ...props
+}: LassoToolsUIContextValue & OptionsChildrenProps) {
+  const data = useMemo(() => {
+    return deepmerge(modes ?? {}, modesMapping ?? {})
+  }, [modes, modesMapping])
+
+  // Selection modes render in their own "Selection tools" section.
+  const { select, 'lasso-select': lassoSelect, ..._modes } = data
+
+  const modeExists = modeSelected ? modeSelected in (modes ?? {}) : false
+
+  // Fallback taken from `modes`, not from the merge: a `modesMapping`-only key
+  // is not a real mode and must never be marked as the active one. `null` (not
+  // a smuggled `undefined`) when `modes` is empty — OptionsList's contract is
+  // `M | null`.
+  const mode =
+    ((modeExists ? modeSelected : Object.keys(modes ?? {})[0]) as
+      keyof typeof data | undefined) ?? null
+
+  // Filtered here, not just inside OptionsList: these counts gate the section
+  // heading and the divider, so a mapping-only key would render a "Selection
+  // tools" header (or a drawing-tools title) with nothing under it.
+  const modesValues = Object.values(_modes).filter((mode) => mode?.value)
+  const selectionModes = [select, lassoSelect].filter((mode) => mode?.value)
+
+  const handleChangeMode: LassoToolsComponentProps['onChangeMode'] = (data) => {
+    return onChangeMode?.(data)
+  }
+
+  const selectionTitle =
+    labels?.options?.selection?.title ??
+    LASSO_TOOLS_LABELS.options.selection.title
+
+  return (
+    <>
+      {!!onChangeInteractionMode && (
+        <>
+          <InteractionModeSection
+            value={interactionMode ?? 'mask'}
+            labels={labels?.options?.interactionMode}
+            onChange={onChangeInteractionMode}
+            maskDisabled={interactionModeMaskDisabled}
+          />
+          <Divider />
+        </>
+      )}
+      <ModeList data={modesValues} labels={labels?.options}>
+        <OptionsList
+          {...props}
+          labels={labels?.options}
+          data={modesValues}
+          modeSelected={mode}
+          onChangeMode={handleChangeMode}
+        />
+      </ModeList>
+      {selectionModes.length > 0 && (
+        <>
+          <Divider />
+          <Typography
+            variant='subtitle2'
+            color='text.secondary'
+            sx={styles.options.title}
+          >
+            {selectionTitle}
+          </Typography>
+          {/*
+            Never gated on `values`: that is the chips list (masks only), so a
+            draw-only map would have its selection modes disabled and its draw
+            geometries unreachable — they have no chips either. Entering select
+            mode with nothing to select is a harmless no-op.
+          */}
+          <OptionsList
+            {...props}
+            labels={labels?.options}
+            data={selectionModes}
+            modeSelected={mode}
+            onChangeMode={handleChangeMode}
+          />
+        </>
+      )}
+      {!!props.onLayerFilters && (
+        <>
+          <Divider />
+          <MenuItem
+            onClick={() => {
+              props.onLayerFilters?.()
+              props.onClose()
+            }}
+          >
+            <ListItemIcon sx={styles.options.icons}>
+              <LayersOutlined />
+            </ListItemIcon>
+            <ListItemText>
+              {labels?.options?.layerFilters ?? 'Layer filters'}
+            </ListItemText>
+          </MenuItem>
+        </>
+      )}
+    </>
+  )
+}
+
+// ==================== Blocks ====================
+//
+// Every block works two ways: with explicit props (how the default composition
+// spreads them) or bare inside `children`, where it reads them from the
+// toolbar's context — the widgets-v2 contract.
+
+type BlockProps = Parameters<typeof ActionsWrapperBase>[0]
+
+LassoToolsUI.Action = function Action(props: BlockProps) {
+  return <ActionsWrapperBase {...useLassoToolsUIArgs(props)} />
+}
+
+LassoToolsUI.Chips = function Chips(
+  props: Parameters<typeof ChipsWrapperBase>[0],
+) {
+  return <ChipsWrapperBase {...useLassoToolsUIArgs(props)} />
+}
+
+LassoToolsUI.SecondaryActions = function SecondaryActions(
+  props: Parameters<typeof SecondaryActionsWrapperBase>[0],
+) {
+  return <SecondaryActionsWrapperBase {...useLassoToolsUIArgs(props)} />
+}
+
+LassoToolsUI.UndoRedo = function UndoRedo(
+  props: Parameters<typeof UndoRedoWrapperBase>[0],
+) {
+  return <UndoRedoWrapperBase {...useLassoToolsUIArgs(props)} />
+}
+
+/** Menu contents for a custom options trigger. Prefer `.OptionsMenu` for the bundled trigger + menu. */
+LassoToolsUI.Options = function Options(
+  props: Parameters<typeof OptionsWrapperBase>[0],
+) {
+  return <OptionsWrapperBase {...useLassoToolsUIArgs(props)} />
+}
+
+/**
+ * Trigger + dropdown + default options contents in one block.
+ */
+LassoToolsUI.OptionsMenu = function OptionsMenu(
+  props: Omit<
+    Parameters<typeof OptionsWrapperBase>[0],
+    keyof OptionsChildrenProps
+  >,
+) {
+  const args = useLassoToolsUIArgs(props)
+
+  return (
+    <Options>
+      {(childrenProps) => <OptionsWrapperBase {...args} {...childrenProps} />}
+    </Options>
+  )
+}