@carto/ps-react-ui 5.1.0 → 6.0.0

package/src/widgets/actions/brush-toggle/brush-overlay.tsx

@@ -1,408 +0,0 @@
-import {
-  useCallback,
-  useEffect,
-  useRef,
-  useState,
-  useSyncExternalStore,
-} from 'react'
-import type { CSSProperties, PointerEvent as ReactPointerEvent } from 'react'
-import { createPortal } from 'react-dom'
-import type { ECharts } from 'echarts'
-import { useWidgetStore, widgetStoreActions } from '../../stores/widget-store'
-import { useWidgetSelector } from '../../stores/use-widget-selector'
-import type { EchartWidgetState } from '../../echart/types'
-import { observeResize } from '../../echart/shared-resize-observer'
-import { hitTestRects } from './hit-test'
-import type { BrushRect, BrushState } from './types'
-import { overlayStyles } from './style'
-
-interface BrushOverlayProps {
-  id: string
-  multiBrush?: boolean
-}
-
-interface PixelRect {
-  left: number
-  right: number
-}
-
-interface PlotRect {
-  x: number
-  y: number
-  width: number
-  height: number
-}
-
-// Shape of the internal ECharts API we reach into to get the grid rectangle.
-// It's undocumented but stable across v5/v6; falling back gracefully if
-// ECharts ever changes the shape is handled by a try/catch at the call site.
-interface EChartsGridInternals {
-  getModel: () => {
-    getComponent: (
-      type: string,
-      index?: number,
-    ) => { coordinateSystem?: { getRect: () => PlotRect } } | null
-  }
-}
-
-// Clicks (tiny drags) are ignored — distinguishes intent to select vs. misclick.
-const MIN_DRAG_PX = 2
-
-// Stable empty-array references. Returning `[]` from the Zustand selector
-// on every call breaks shallow-equality memoization (each `[]` is a new
-// reference) — which ripples into `rects` being a fresh reference on every
-// render, which re-runs the re-projection effect, which `setProjectedRects`,
-// which re-renders, producing an infinite loop.
-const EMPTY_RECTS: readonly BrushRect[] = Object.freeze([])
-const EMPTY_PIXEL_RECTS: readonly PixelRect[] = Object.freeze([])
-
-/**
- * Reads the plot-area (grid) rectangle from an ECharts instance. Uses the
- * internal model API because ECharts doesn't expose this publicly; returns
- * `null` if the grid is missing or the API shape has drifted.
- */
-function readPlotRect(instance: ECharts): PlotRect | null {
-  try {
-    const model = (instance as unknown as EChartsGridInternals).getModel()
-    const grid = model.getComponent('grid', 0)
-    const rect = grid?.coordinateSystem?.getRect()
-    if (!rect) return null
-    if (
-      !Number.isFinite(rect.x) ||
-      !Number.isFinite(rect.y) ||
-      !Number.isFinite(rect.width) ||
-      !Number.isFinite(rect.height)
-    ) {
-      return null
-    }
-    return { x: rect.x, y: rect.y, width: rect.width, height: rect.height }
-  } catch {
-    return null
-  }
-}
-
-function plotRectEquals(a: PlotRect | null, b: PlotRect | null): boolean {
-  if (a === b) return true
-  if (!a || !b) return false
-  return (
-    a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height
-  )
-}
-
-/**
- * Portaled overlay rendered inside the ECharts chart `<div>`. Handles brush
- * drawing entirely in DOM, independent of ECharts' built-in brush.
- *
- * Rectangles are stored in x-axis data coords (category indices) in the
- * widget store. The overlay re-projects them to pixel coords on every chart
- * `finished` event and container resize, so `setOption({ notMerge: true })`
- * by the config pipeline is a non-event.
- *
- * Pointer capture and rectangle rendering are both clamped to the ECharts
- * grid (plot area), so the legend, axis labels, and other chart chrome
- * receive their usual events and aren't visually covered.
- *
- * Hit-testing happens on `pointerup` using `hitTestRects` against the widget's
- * data length (derived from `widget.data`). The result is written to
- * `brushSelection` in the store; `BrushToggle` subscribes to that and invokes
- * the consumer's `onBrushSelected` callback.
- */
-export function BrushOverlay({ id, multiBrush }: BrushOverlayProps) {
-  const { enabled, rects, dataLength } = useWidgetSelector(id, (w) => {
-    const brushState = w as BrushState | undefined
-    // Bar and histogram both expose data as a nested array of series;
-    // all series share the same category count.
-    const widgetData = w?.data as unknown[][] | undefined
-    const firstSeries = widgetData?.[0]
-    const length = Array.isArray(firstSeries) ? firstSeries.length : 0
-    return {
-      enabled: brushState?.brush ?? false,
-      rects: brushState?.brushRects ?? (EMPTY_RECTS as BrushRect[]),
-      dataLength: length,
-    }
-  })
-
-  // Surface the chart DOM element and ECharts instance via `useSyncExternalStore`.
-  // Reading `ref.current` inside a `getSnapshot` callback is idiomatic and
-  // satisfies React Compiler's "don't read refs during render" guardrail.
-  // The store notifies us when EchartUI registers the refs via `setWidget`;
-  // `getSnapshot` then resolves the current values.
-  const subscribe = useCallback(
-    (notify: () => void) => useWidgetStore.subscribe(notify),
-    [],
-  )
-  const chartEl = useSyncExternalStore(
-    subscribe,
-    useCallback((): HTMLElement | null => {
-      return (
-        widgetStoreActions.getWidget<EchartWidgetState>(id)?.refUI?.current ??
-        null
-      )
-    }, [id]),
-    () => null,
-  )
-  const instance = useSyncExternalStore(
-    subscribe,
-    useCallback((): ECharts | null => {
-      return (
-        widgetStoreActions.getWidget<EchartWidgetState>(id)?.instance
-          ?.current ?? null
-      )
-    }, [id]),
-    () => null,
-  )
-
-  const plotCaptureRef = useRef<HTMLDivElement | null>(null)
-  const dragStartRef = useRef<number | null>(null)
-  const pointerIdRef = useRef<number | null>(null)
-  const [projectedRects, setProjectedRects] = useState<PixelRect[]>(
-    EMPTY_PIXEL_RECTS as PixelRect[],
-  )
-  const [drawing, setDrawing] = useState<PixelRect | null>(null)
-  const [plotRect, setPlotRect] = useState<PlotRect | null>(null)
-
-  // Anchor the absolute-positioned overlay to the chart div. Look the element
-  // up by id so React Compiler doesn't flag the style mutation; `chartEl` is
-  // a normal state value here so using it as a trigger is safe.
-  useEffect(() => {
-    if (!chartEl) return
-    const el = document.getElementById(id)
-    if (!el) return
-    const previous = el.style.position
-    if (!previous) el.style.position = 'relative'
-    return () => {
-      if (!previous) el.style.position = ''
-    }
-  }, [id, chartEl])
-
-  // Re-project stored rects to pixel coords and refresh the plot-area bounds
-  // on every chart render (ECharts `finished` event) and on container
-  // resize. This is what makes `setOption({ notMerge: true })` a non-event —
-  // the store is untouched and the overlay just re-paints.
-  useEffect(() => {
-    if (!instance || !chartEl) return
-
-    const project = () => {
-      // Plot area bounds — if the grid isn't laid out yet we can't project
-      // anything meaningfully, so skip this pass and wait for the next
-      // `finished` event.
-      const nextPlot = readPlotRect(instance)
-      setPlotRect((prev) => (plotRectEquals(prev, nextPlot) ? prev : nextPlot))
-      if (!nextPlot) return
-
-      const next: PixelRect[] = []
-      for (const r of rects) {
-        const leftPx = instance.convertToPixel({ xAxisIndex: 0 }, r.xStart)
-        const rightPx = instance.convertToPixel({ xAxisIndex: 0 }, r.xEnd)
-        if (
-          typeof leftPx !== 'number' ||
-          typeof rightPx !== 'number' ||
-          !Number.isFinite(leftPx) ||
-          !Number.isFinite(rightPx)
-        ) {
-          continue
-        }
-        // Clamp to plot area horizontally so rectangles never bleed onto
-        // adjacent padding/legend.
-        const lo = Math.max(nextPlot.x, Math.min(leftPx, rightPx))
-        const hi = Math.min(
-          nextPlot.x + nextPlot.width,
-          Math.max(leftPx, rightPx),
-        )
-        if (hi <= lo) continue
-        next.push({ left: lo, right: hi })
-      }
-      // Reuse the frozen empty reference so successive "no rectangles"
-      // updates hit React's `Object.is` bail-out instead of re-rendering.
-      setProjectedRects(
-        next.length === 0 ? (EMPTY_PIXEL_RECTS as PixelRect[]) : next,
-      )
-    }
-
-    project()
-    instance.on('finished', project)
-    const unobserve = observeResize(chartEl, project)
-    return () => {
-      instance.off('finished', project)
-      unobserve()
-    }
-  }, [instance, chartEl, rects])
-
-  const handlePointerDown = useCallback(
-    (e: ReactPointerEvent<HTMLDivElement>) => {
-      if (!enabled || !chartEl || !plotRect) return
-      const capture = plotCaptureRef.current
-      if (!capture) return
-      e.preventDefault()
-      capture.setPointerCapture(e.pointerId)
-      pointerIdRef.current = e.pointerId
-      // Hide the tooltip so it doesn't overlap the brush selection.
-      instance?.dispatchAction({ type: 'hideTip' })
-      // Work in chart-container pixel space so conversions via
-      // `convertFromPixel` (which expects container-relative coords) stay
-      // consistent with the rectangle positions we store.
-      const chartBBox = chartEl.getBoundingClientRect()
-      const x = clampX(e.clientX - chartBBox.left, plotRect)
-      dragStartRef.current = x
-      setDrawing({ left: x, right: x })
-    },
-    [enabled, instance, chartEl, plotRect],
-  )
-
-  const handlePointerMove = useCallback(
-    (e: ReactPointerEvent<HTMLDivElement>) => {
-      // No active drag — forward the hover to ECharts so its tooltip works.
-      if (pointerIdRef.current === null) {
-        if (instance && chartEl) {
-          const chartBBox = chartEl.getBoundingClientRect()
-          instance.dispatchAction({
-            type: 'showTip',
-            x: e.clientX - chartBBox.left,
-            y: e.clientY - chartBBox.top,
-          })
-        }
-        return
-      }
-      if (pointerIdRef.current !== e.pointerId) return
-      const start = dragStartRef.current
-      if (start === null || !chartEl || !plotRect) return
-      const chartBBox = chartEl.getBoundingClientRect()
-      const x = clampX(e.clientX - chartBBox.left, plotRect)
-      setDrawing({ left: Math.min(start, x), right: Math.max(start, x) })
-    },
-    [instance, chartEl, plotRect],
-  )
-
-  const handlePointerLeave = useCallback(() => {
-    // Don't hide the tooltip during a drag — the pointer may leave the
-    // element bounds while captured and we don't want flickering.
-    if (pointerIdRef.current !== null) return
-    instance?.dispatchAction({ type: 'hideTip' })
-  }, [instance])
-
-  const handlePointerUp = useCallback(
-    (e: ReactPointerEvent<HTMLDivElement>) => {
-      if (pointerIdRef.current !== e.pointerId) return
-      const start = dragStartRef.current
-      const capture = plotCaptureRef.current
-      pointerIdRef.current = null
-      dragStartRef.current = null
-      setDrawing(null)
-
-      if (start === null || !capture || !instance || !chartEl || !plotRect) {
-        return
-      }
-
-      try {
-        capture.releasePointerCapture(e.pointerId)
-      } catch {
-        // releasePointerCapture throws if the pointer is no longer captured;
-        // ignore and continue.
-      }
-
-      const chartBBox = chartEl.getBoundingClientRect()
-      const x = clampX(e.clientX - chartBBox.left, plotRect)
-      const leftPx = Math.min(start, x)
-      const rightPx = Math.max(start, x)
-      if (rightPx - leftPx < MIN_DRAG_PX) return
-
-      const xStart = instance.convertFromPixel({ xAxisIndex: 0 }, leftPx)
-      const xEnd = instance.convertFromPixel({ xAxisIndex: 0 }, rightPx)
-      if (
-        typeof xStart !== 'number' ||
-        typeof xEnd !== 'number' ||
-        !Number.isFinite(xStart) ||
-        !Number.isFinite(xEnd)
-      ) {
-        return
-      }
-
-      const newRect: BrushRect = { xStart, xEnd }
-      const nextRects = multiBrush ? [...rects, newRect] : [newRect]
-      const selection = {
-        dataIndex: hitTestRects(nextRects, dataLength),
-        seriesIndex: 0,
-      }
-
-      widgetStoreActions.setWidget(id, {
-        brushRects: nextRects,
-        brushSelection: selection,
-        // Single-brush: auto-disable after selection (matches prior UX).
-        ...(multiBrush ? {} : { brush: false }),
-      })
-    },
-    [id, instance, multiBrush, rects, dataLength, chartEl, plotRect],
-  )
-
-  if (!chartEl) return null
-
-  // Outer container spans the whole chart but never captures pointer events,
-  // so the legend / axis labels / other chart chrome remain interactive.
-  const containerStyle: CSSProperties = {
-    position: 'absolute',
-    inset: 0,
-    pointerEvents: 'none',
-    zIndex: 1,
-  }
-
-  // Inner capture layer sits over the plot area only. This is the element
-  // that gets the pointer events when brush is active.
-  const captureStyle: CSSProperties | undefined = plotRect
-    ? {
-        position: 'absolute',
-        left: plotRect.x,
-        top: plotRect.y,
-        width: plotRect.width,
-        height: plotRect.height,
-        pointerEvents: enabled ? 'auto' : 'none',
-        cursor: enabled ? 'crosshair' : 'default',
-        userSelect: 'none',
-        touchAction: 'none',
-      }
-    : undefined
-
-  return createPortal(
-    <div style={containerStyle}>
-      {captureStyle && (
-        <div
-          ref={plotCaptureRef}
-          style={captureStyle}
-          onPointerDown={handlePointerDown}
-          onPointerMove={handlePointerMove}
-          onPointerUp={handlePointerUp}
-          onPointerCancel={handlePointerUp}
-          onPointerLeave={handlePointerLeave}
-        />
-      )}
-      {plotRect &&
-        projectedRects.map((r, i) => (
-          <div
-            key={`${r.left}-${r.right}-${i}`}
-            style={{
-              ...overlayStyles.rect,
-              left: r.left,
-              width: Math.max(0, r.right - r.left),
-              top: plotRect.y,
-              height: plotRect.height,
-            }}
-          />
-        ))}
-      {plotRect && drawing && (
-        <div
-          style={{
-            ...overlayStyles.rectPreview,
-            left: drawing.left,
-            width: Math.max(0, drawing.right - drawing.left),
-            top: plotRect.y,
-            height: plotRect.height,
-          }}
-        />
-      )}
-    </div>,
-    chartEl,
-  )
-}
-
-function clampX(x: number, plot: PlotRect): number {
-  return Math.max(plot.x, Math.min(plot.x + plot.width, x))
-}

package/src/widgets/actions/brush-toggle/hit-test.test.ts

@@ -1,65 +0,0 @@
-import { describe, test, expect } from 'vitest'
-import { hitTestCategoryRange, hitTestRects } from './hit-test'
-
-describe('hitTestCategoryRange', () => {
-  test('returns empty when dataLength is zero', () => {
-    expect(hitTestCategoryRange(0, 5, 0)).toEqual([])
-  })
-
-  test('snaps fractional range outward so partial overlaps are included', () => {
-    // xStart=1.3, xEnd=3.7 → floor(1.3)=1, ceil(3.7)=4 → [1, 2, 3, 4]
-    expect(hitTestCategoryRange(1.3, 3.7, 10)).toEqual([1, 2, 3, 4])
-  })
-
-  test('handles integer endpoints inclusively', () => {
-    expect(hitTestCategoryRange(2, 4, 10)).toEqual([2, 3, 4])
-  })
-
-  test('clamps to [0, dataLength - 1]', () => {
-    expect(hitTestCategoryRange(-2.5, 12.8, 5)).toEqual([0, 1, 2, 3, 4])
-  })
-
-  test('normalizes reversed inputs (xEnd < xStart)', () => {
-    expect(hitTestCategoryRange(3.7, 1.3, 10)).toEqual([1, 2, 3, 4])
-  })
-
-  test('returns empty when range is entirely out of bounds', () => {
-    expect(hitTestCategoryRange(10, 12, 5)).toEqual([])
-    expect(hitTestCategoryRange(-5, -1, 5)).toEqual([])
-  })
-
-  test('returns adjacent indices for a very narrow fractional range when snapping outward', () => {
-    // xStart=2.1, xEnd=2.3 partially overlaps both categories, so floor=2 and ceil=3 → [2, 3]
-    expect(hitTestCategoryRange(2.1, 2.3, 10)).toEqual([2, 3])
-  })
-})
-
-describe('hitTestRects', () => {
-  test('returns empty for no rects', () => {
-    expect(hitTestRects([], 10)).toEqual([])
-  })
-
-  test('unions and dedups across overlapping rects', () => {
-    const rects = [
-      { xStart: 1, xEnd: 3 },
-      { xStart: 2, xEnd: 4 },
-    ]
-    expect(hitTestRects(rects, 10)).toEqual([1, 2, 3, 4])
-  })
-
-  test('returns sorted ascending indices for disjoint rects', () => {
-    const rects = [
-      { xStart: 7, xEnd: 8 },
-      { xStart: 1, xEnd: 2 },
-    ]
-    expect(hitTestRects(rects, 10)).toEqual([1, 2, 7, 8])
-  })
-
-  test('drops rects entirely out of bounds', () => {
-    const rects = [
-      { xStart: 20, xEnd: 25 },
-      { xStart: 1, xEnd: 2 },
-    ]
-    expect(hitTestRects(rects, 10)).toEqual([1, 2])
-  })
-})

package/src/widgets/actions/brush-toggle/hit-test.ts

@@ -1,45 +0,0 @@
-import type { BrushRect } from './types'
-
-/**
- * Returns integer dataIndices covered by a brush rectangle on a category axis.
- *
- * `xStart` / `xEnd` come from `instance.convertFromPixel({ xAxisIndex: 0 }, …)`
- * which, for a category axis, returns fractional positions around integer
- * category indices (e.g. `1.3` lands between categories 1 and 2). We snap the
- * range outward (`floor` / `ceil`) so a drag that visually covers any part of
- * a category's bar includes that index.
- *
- * Results are clamped to `[0, dataLength - 1]` and returned in ascending order.
- */
-export function hitTestCategoryRange(
-  xStart: number,
-  xEnd: number,
-  dataLength: number,
-): number[] {
-  if (dataLength <= 0) return []
-  const [lo, hi] = xStart <= xEnd ? [xStart, xEnd] : [xEnd, xStart]
-
-  const start = Math.max(0, Math.floor(lo))
-  const end = Math.min(dataLength - 1, Math.ceil(hi))
-  if (start > end) return []
-
-  const indices: number[] = []
-  for (let i = start; i <= end; i += 1) indices.push(i)
-  return indices
-}
-
-/**
- * Union of `hitTestCategoryRange` across multiple rectangles. Used for
- * multi-brush selections where each drawn rectangle contributes to the
- * combined selection.
- */
-export function hitTestRects(rects: BrushRect[], dataLength: number): number[] {
-  if (rects.length === 0) return []
-  const seen = new Set<number>()
-  for (const rect of rects) {
-    for (const i of hitTestCategoryRange(rect.xStart, rect.xEnd, dataLength)) {
-      seen.add(i)
-    }
-  }
-  return Array.from(seen).sort((a, b) => a - b)
-}

package/src/widgets/actions/brush-toggle/types.ts

@@ -1,78 +0,0 @@
-import type { IconButtonProps } from '@mui/material'
-import type { ReactNode } from 'react'
-import type { BaseWidgetState } from '../../stores/types'
-
-/**
- * Brush selection result emitted by BrushToggle.
- * Contains raw indices so consumers can resolve data according to their widget type.
- */
-export interface BrushSelectedItems {
-  /** Data indices of the selected items in the dataset */
-  dataIndex: number[]
-  /** Series index from the brush event (defaults to 0) */
-  seriesIndex: number
-}
-
-/**
- * A selection rectangle in x-axis data coords. Stored in the widget store so
- * it survives config-pipeline re-renders (which call `setOption` with
- * `notMerge: true` and wipe any ECharts-side state). The overlay re-projects
- * these to pixel positions on every chart render / resize.
- *
- * Both bar and histogram widgets use `xAxis.type === 'category'`, so the
- * coords are category indices (possibly fractional — `convertFromPixel`
- * returns floats like `1.3` between categories 1 and 2).
- */
-export interface BrushRect {
-  xStart: number
-  xEnd: number
-}
-
-/**
- * State stored in widget store for brush functionality.
- */
-export interface BrushConfig {
-  /** Whether brush mode is enabled. */
-  brush?: boolean
-  /** Persisted selection rectangles in data-axis coords. */
-  brushRects?: BrushRect[]
-  /** Last selection emitted to the `onBrushSelected` callback. */
-  brushSelection?: BrushSelectedItems
-}
-
-export type BrushState<T = unknown> = BaseWidgetState<T & BrushConfig>
-
-export interface BrushToggleProps {
-  /** Widget ID to update brush state in the widget store */
-  id: string
-  /** Callback fired when items are selected via brush */
-  onBrushSelected?: (items: BrushSelectedItems) => void
-  /** When true, allows multiple brush selection areas. Brush stays active after each selection. */
-  multiBrush?: boolean
-  /**
-   * Initial brush-enabled state. Only applied on first mount if the widget
-   * store has no `brush` value yet — subsequent remounts preserve whatever
-   * state the user has toggled to.
-   */
-  defaultEnabled?: boolean
-  /**
-   * Current selection count from the consumer (e.g. `selectedItems.length`).
-   * When this transitions to `0` (typically when the user presses the clear
-   * button in `WidgetSelectionSummary`), BrushToggle clears its persisted
-   * brush rectangles and the on-chart selection.
-   */
-  selections?: number
-  /** Custom labels for the action */
-  labels?: {
-    /** Tooltip when brush is disabled (button will enable brush) */
-    enable?: string
-    /** Tooltip when brush is enabled (button will disable brush) */
-    disable?: string
-    /** Accessibility label */
-    ariaLabel?: string
-  }
-  /** Props passed to the IconButton component */
-  IconButtonProps?: IconButtonProps
-  /** Custom icon to display for brush toggle */
-  Icon?: ReactNode
-}