@carto/ps-react-ui 4.6.3 → 4.7.1

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

@@ -0,0 +1,65 @@
+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

@@ -0,0 +1,45 @@
+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/style.ts

@@ -1,4 +1,5 @@
 import type { SxProps, Theme } from '@mui/material'
+import type { CSSProperties } from 'react'
 
 export const styles = {
   container: {
@@ -12,3 +13,34 @@ export const styles = {
     },
   },
 } satisfies Record<string, SxProps<Theme>>
+
+/**
+ * Plain CSS objects for the brush overlay — we're outside MUI's sx pipeline
+ * here because the rectangles are rendered via a React portal into the chart
+ * div (not part of the MUI tree). Colors borrow from the base palette; if
+ * theme-aware styling is needed later, move to styled components.
+ */
+export const overlayStyles: Record<string, CSSProperties> = {
+  // `top` and `height` are filled in at render time from the chart's plot
+  // rect so rectangles don't bleed over the legend / axis labels.
+  //
+  // Colors track ECharts 6's `backgroundTint` token (used by the default
+  // brush) — a barely-visible pale blue-gray translucent fill that washes
+  // bars underneath rather than masking them. Border is a hairline dark
+  // alpha so the selection edges are just findable, not prominent.
+  rect: {
+    position: 'absolute',
+    background: 'rgba(234, 237, 245, 0.2)',
+    border: '1px dashed rgba(0, 0, 0, 0.15)',
+    pointerEvents: 'none',
+  },
+  // Live drag preview — identical to committed rect (no "in-progress" vs
+  // "committed" visual distinction; the preview just disappears on
+  // `pointerup` as the rect takes its place).
+  rectPreview: {
+    position: 'absolute',
+    background: 'rgba(234, 237, 245, 0.6)',
+    border: '1px dashed rgba(0, 0, 0, 0.15)',
+    pointerEvents: 'none',
+  },
+}

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

@@ -14,10 +14,30 @@ export interface BrushSelectedItems {
 }
 
 /**
- * State stored in widget store for brush functionality
+ * 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>
@@ -27,6 +47,21 @@ export interface BrushToggleProps {
   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) */

package/src/widgets/histogram/config.ts

@@ -211,9 +211,7 @@ function getOption({
 
         const marker = typeof item.marker === 'string' ? item.marker : ''
         const seriesName = item.seriesName ? `${item.seriesName}: ` : ''
-        const name = labelFormatter
-          ? String(labelFormatter(item.name ?? ''))
-          : (item.name ?? '')
+        const name = item.name
 
         return { name, seriesName, marker, value: formattedValue }
       }),