@carto/ps-react-ui 4.4.0-chat-ui.5 → 4.4.0-chat-ui.7

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

@@ -0,0 +1,408 @@
+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/brush-toggle.test.tsx

@@ -0,0 +1,208 @@
+/**
+ * Render tests for BrushToggle covering the previously-uncovered branches
+ * in src/widgets/actions/brush-toggle/brush-toggle.tsx (0/72 baseline).
+ *
+ * Coverage focus:
+ * - useWidgetSelector default (defaultEnabled when no store entry)
+ * - Initial seed useEffect only fires when brush is undefined
+ * - handleToggle: brush=false → true (clears rectangles + invokes consumer
+ *   callback) vs brush=true → false (preserves rectangles)
+ * - Consumer-driven clear effect (`selections === 0` branch with vs without
+ *   rectangles/selection)
+ * - lastSelectionRef gating (callback fires only once per new selection)
+ * - Custom labels, custom Icon, custom IconButtonProps
+ *
+ * Does NOT render BrushOverlay logic — that's a separate file with its own
+ * 177-branch surface. BrushOverlay is included via the BrushToggle JSX, but
+ * its rendering happens lazily and the overlay's pointer logic isn't
+ * exercised here.
+ */
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { ThemeProvider, createTheme } from '@mui/material/styles'
+import { useWidgetStore, widgetStoreActions } from '../../stores/widget-store'
+import { BrushToggle } from './brush-toggle'
+import type { BrushState } from './types'
+
+const theme = createTheme({
+  palette: {
+    common: { white: '#ffffff', black: '#000000' },
+    secondary: { main: '#3366ff' },
+    // @ts-expect-error - `black` is a CARTO-specific MUI palette extension
+    black: { 60: 'rgba(0,0,0,0.6)' },
+  },
+})
+
+function renderWithTheme(ui: React.ReactElement) {
+  return render(<ThemeProvider theme={theme}>{ui}</ThemeProvider>)
+}
+
+beforeEach(() => {
+  useWidgetStore.getState().clearWidgets()
+})
+
+describe('BrushToggle render', () => {
+  it('renders with brush off (default)', () => {
+    renderWithTheme(<BrushToggle id='bt-1' />)
+    const button = screen.getByRole('button')
+    expect(button.getAttribute('data-active')).toBe('false')
+  })
+
+  it('seeds the widget store on mount when brush is undefined', () => {
+    renderWithTheme(<BrushToggle id='bt-seed' defaultEnabled />)
+    const widget = widgetStoreActions.getWidget<BrushState>('bt-seed')
+    expect(widget?.brush).toBe(true)
+  })
+
+  it('does NOT seed when brush is already set in the store', () => {
+    widgetStoreActions.setWidget('bt-noseed', { brush: false })
+    renderWithTheme(<BrushToggle id='bt-noseed' defaultEnabled />)
+    const widget = widgetStoreActions.getWidget<BrushState>('bt-noseed')
+    expect(widget?.brush).toBe(false)
+  })
+
+  it('uses custom labels for aria-label', () => {
+    renderWithTheme(
+      <BrushToggle
+        id='bt-labels'
+        labels={{ enable: 'Brush on', disable: 'Brush off' }}
+      />,
+    )
+    expect(screen.getByRole('button', { name: 'Brush on' })).toBeDefined()
+  })
+
+  it('respects an explicit ariaLabel', () => {
+    renderWithTheme(
+      <BrushToggle
+        id='bt-aria'
+        labels={{ ariaLabel: 'Toggle brush selection' }}
+      />,
+    )
+    expect(
+      screen.getByRole('button', { name: 'Toggle brush selection' }),
+    ).toBeDefined()
+  })
+
+  it('renders custom Icon when provided', () => {
+    renderWithTheme(
+      <BrushToggle id='bt-icon' Icon={<span data-testid='custom-icon' />} />,
+    )
+    expect(screen.getByTestId('custom-icon')).toBeDefined()
+  })
+})
+
+describe('BrushToggle interactions', () => {
+  it('handleToggle: brush=false → true clears rectangles and invokes consumer callback with empty selection', () => {
+    const onBrushSelected = vi.fn()
+    widgetStoreActions.setWidget('bt-on', { brush: false })
+    renderWithTheme(
+      <BrushToggle id='bt-on' onBrushSelected={onBrushSelected} />,
+    )
+    fireEvent.click(screen.getByRole('button'))
+    const w = widgetStoreActions.getWidget<BrushState>('bt-on')
+    expect(w?.brush).toBe(true)
+    expect(w?.brushRects).toEqual([])
+    expect(onBrushSelected).toHaveBeenCalledWith({
+      dataIndex: [],
+      seriesIndex: 0,
+    })
+  })
+
+  it('handleToggle: brush=true → false does NOT clear rectangles', () => {
+    widgetStoreActions.setWidget('bt-off', {
+      brush: true,
+      brushRects: [{ x: 1, y: 2, w: 3, h: 4 }],
+    })
+    const onBrushSelected = vi.fn()
+    renderWithTheme(
+      <BrushToggle id='bt-off' onBrushSelected={onBrushSelected} />,
+    )
+    fireEvent.click(screen.getByRole('button'))
+    const w = widgetStoreActions.getWidget<BrushState>('bt-off')
+    expect(w?.brush).toBe(false)
+    // Rectangles preserved
+    expect(w?.brushRects).toHaveLength(1)
+    // Consumer callback not invoked on the disable transition
+    expect(onBrushSelected).not.toHaveBeenCalled()
+  })
+
+  it('works when onBrushSelected is not provided (`?.` short-circuit)', () => {
+    widgetStoreActions.setWidget('bt-no-cb', { brush: false })
+    renderWithTheme(<BrushToggle id='bt-no-cb' />)
+    fireEvent.click(screen.getByRole('button'))
+    const w = widgetStoreActions.getWidget<BrushState>('bt-no-cb')
+    expect(w?.brush).toBe(true)
+  })
+})
+
+describe('BrushToggle consumer-driven clear (selections=0)', () => {
+  it('clears stored rectangles + selection when `selections` transitions to 0', () => {
+    widgetStoreActions.setWidget('bt-clear', {
+      brush: true,
+      brushRects: [{ x: 1, y: 2, w: 3, h: 4 }],
+      brushSelection: { dataIndex: [1, 2, 3], seriesIndex: 0 },
+    })
+    renderWithTheme(<BrushToggle id='bt-clear' selections={0} />)
+    const w = widgetStoreActions.getWidget<BrushState>('bt-clear')
+    expect(w?.brushRects).toEqual([])
+    expect(w?.brushSelection?.dataIndex).toEqual([])
+  })
+
+  it('is a no-op when there is nothing to clear', () => {
+    widgetStoreActions.setWidget('bt-clear-nop', {
+      brush: true,
+      brushRects: [],
+      brushSelection: { dataIndex: [], seriesIndex: 0 },
+    })
+    renderWithTheme(<BrushToggle id='bt-clear-nop' selections={0} />)
+    const w = widgetStoreActions.getWidget<BrushState>('bt-clear-nop')
+    // Still empty; effect should have short-circuited
+    expect(w?.brushRects).toEqual([])
+  })
+
+  it('does nothing when `selections` is non-zero', () => {
+    widgetStoreActions.setWidget('bt-nonzero', {
+      brush: true,
+      brushRects: [{ x: 0, y: 0, w: 1, h: 1 }],
+      brushSelection: { dataIndex: [5], seriesIndex: 0 },
+    })
+    renderWithTheme(<BrushToggle id='bt-nonzero' selections={3} />)
+    const w = widgetStoreActions.getWidget<BrushState>('bt-nonzero')
+    expect(w?.brushRects).toHaveLength(1)
+    expect(w?.brushSelection?.dataIndex).toEqual([5])
+  })
+})
+
+describe('BrushToggle selection-callback effect', () => {
+  it('invokes onBrushSelected when the store selection changes', () => {
+    const onBrushSelected = vi.fn()
+    widgetStoreActions.setWidget('bt-sel', {
+      brush: true,
+      brushSelection: { dataIndex: [1, 2], seriesIndex: 0 },
+    })
+    renderWithTheme(
+      <BrushToggle id='bt-sel' onBrushSelected={onBrushSelected} />,
+    )
+    expect(onBrushSelected).toHaveBeenCalledWith({
+      dataIndex: [1, 2],
+      seriesIndex: 0,
+    })
+  })
+
+  it('does not double-invoke for the same selection reference', () => {
+    const onBrushSelected = vi.fn()
+    widgetStoreActions.setWidget('bt-sel-dup', {
+      brush: true,
+      brushSelection: { dataIndex: [1], seriesIndex: 0 },
+    })
+    const { rerender } = renderWithTheme(
+      <BrushToggle id='bt-sel-dup' onBrushSelected={onBrushSelected} />,
+    )
+    rerender(
+      <ThemeProvider theme={theme}>
+        <BrushToggle id='bt-sel-dup' onBrushSelected={onBrushSelected} />
+      </ThemeProvider>,
+    )
+    expect(onBrushSelected).toHaveBeenCalledTimes(1)
+  })
+})