@carto/ps-react-ui 5.0.0 → 6.0.0

package/src/migration/v4/widgets-v1.ts

@@ -0,0 +1,199 @@
+/**
+ * The names widgets v1 exported that widgets v2 does not export anywhere.
+ *
+ * Generated with the TypeScript checker from every `./widgets/*` entry point
+ * of the last release that shipped v1, minus every `./widgets-v2/*` export.
+ * The 89 names both surfaces share (`CategoryUI`, `Download`, the
+ * `*Skeleton`s, …) are left out on purpose: after the rename they resolve to
+ * v2, so a leftover v1 use of one fails in `tsc` on its props, not here.
+ * That is also what keeps the rule idempotent: a second run over renamed v2
+ * imports finds none of these names.
+ */
+export const WIDGETS_V1_ONLY: ReadonlySet<string> = new Set([
+  'Actions',
+  'BRUSH_TOGGLE_TOOL_ID',
+  'BarConfig',
+  'BarWidgetConfig',
+  'BarWidgetState',
+  'BaseWidgetState',
+  'BrushConfig',
+  'BrushSelectedItems',
+  'BrushState',
+  'CHANGE_COLUMN_TOOL_ID',
+  'CategoryDownloadConfig',
+  'CategoryWidgetConfig',
+  'CategoryWidgetState',
+  'CellHeader',
+  'CellHeaderProps',
+  'ChartWidgetBaseConfig',
+  'ConfigOrFn',
+  'ConfigProps',
+  'CreateChartWidgetConfigParams',
+  'DataItem',
+  'EchartOptionsProps',
+  'EchartWidgetData',
+  'EchartWidgetState',
+  'FormulaDownloadConfig',
+  'FormulaWidgetConfig',
+  'FormulaWidgetState',
+  'FullScreenConfig',
+  'FullScreenProps',
+  'FullScreenState',
+  'HistogramConfig',
+  'HistogramDownloadConfigProps',
+  'HistogramWidgetConfig',
+  'HistogramWidgetState',
+  'Item',
+  'ItemProps',
+  'LOCK_SELECTION_TOOL_ID',
+  'LockSelectionState',
+  'LockSelectionStateProps',
+  'MarkdownComponentProps',
+  'MarkdownDataItem',
+  'MarkdownDownloadConfig',
+  'MarkdownWidgetConfig',
+  'MarkdownWidgetState',
+  'MaxValue',
+  'MinValue',
+  'Mode',
+  'Options',
+  'Pagination',
+  'PaginationActions',
+  'PaginationActionsProps',
+  'PaginationProps',
+  'PieConfig',
+  'PieWidgetConfig',
+  'PieWidgetState',
+  'RELATIVE_DATA_CONFIG_TOOL_ID',
+  'RELATIVE_DATA_TOOL_ID',
+  'RangeDownloadConfig',
+  'RangeItem',
+  'RangeItemProps',
+  'RangeWidgetConfig',
+  'RangeWidgetState',
+  'RelativeDataState',
+  'Row',
+  'RowProps',
+  'SEARCHER_TOOL_ID',
+  'STACK_TOGGLE_TOOL_ID',
+  'ScatterplotConfig',
+  'ScatterplotWidgetConfig',
+  'ScatterplotWidgetState',
+  'SearcherFilterFn',
+  'SearcherState',
+  'SearcherStateProps',
+  'SeriesConfig',
+  'SkeletonLoader',
+  'SkeletonLoaderProps',
+  'SortDirection',
+  'SortState',
+  'SpreadDownloadConfig',
+  'SpreadWidgetConfig',
+  'SpreadWidgetState',
+  'StackToggleState',
+  'TableDownloadConfig',
+  'TablePaginationState',
+  'TableWidgetConfig',
+  'TimeseriesConfig',
+  'TimeseriesWidgetConfig',
+  'TimeseriesWidgetState',
+  'Title',
+  'ToolRegistration',
+  'ToolTransformFunction',
+  'ToolType',
+  'ToolbarAction',
+  'ToolbarActions',
+  'ToolbarActionsLabels',
+  'ToolbarActionsProps',
+  'UsePaginationResult',
+  'UseSelectionOptions',
+  'UseSelectionResult',
+  'UseSortResult',
+  'WidgetError',
+  'WidgetErrorProps',
+  'WidgetLoader',
+  'WidgetLoaderProps',
+  'WidgetNoData',
+  'WidgetNoDataProps',
+  'WidgetNote',
+  'WidgetNoteProps',
+  'WidgetSelectionSummary',
+  'WidgetSelectionSummaryProps',
+  'WidgetStore',
+  'WidgetStoreActions',
+  'WidgetStoreState',
+  'WidgetSubHeader',
+  'WidgetSubHeaderProps',
+  'WidgetWrapper',
+  'WidgetsStoreProps',
+  'WrapperActionsProps',
+  'WrapperOption',
+  'WrapperOptionsProps',
+  'WrapperState',
+  'WrapperUI',
+  'WrapperUIProps',
+  'ZOOM_TOGGLE_TOOL_ID',
+  'ZoomConfig',
+  'ZoomState',
+  'applyXAxisFormatter',
+  'applyYAxisFormatter',
+  'barConfig',
+  'barDownloadConfig',
+  'baseSkeletonStyles',
+  'buildGridConfig',
+  'buildLegendConfig',
+  'categoryConfig',
+  'categoryDownloadConfig',
+  'createAxisLabelFormatter',
+  'createChartDownloadConfig',
+  'createChartWidgetConfig',
+  'createTooltipFormatter',
+  'createTooltipPositioner',
+  'defaultFormatter',
+  'defaultLabelFormatter',
+  'downloadToPNG',
+  'flattenObjectArrayToCSV',
+  'formulaConfig',
+  'formulaDownloadConfig',
+  'getCellValue',
+  'getCommonOptions',
+  'getEChartBrushConfig',
+  'getEChartStackConfig',
+  'getEChartZoomConfig',
+  'histogramConfig',
+  'histogramDataToCSV',
+  'histogramDownloadConfig',
+  'markdownConfig',
+  'markdownDownloadConfig',
+  'mergeEchartWidgetConfig',
+  'mergeWidgetConfig',
+  'niceNum',
+  'paginateData',
+  'pieConfig',
+  'pieDownloadConfig',
+  'rangeConfig',
+  'resolveConfig',
+  'sanitizeDataItem',
+  'sanitizeDataItems',
+  'sanitizeRangeDataItem',
+  'sanitizeRangeDataItems',
+  'sanitizeTableData',
+  'sanitizeTableRow',
+  'scatterplotConfig',
+  'scatterplotDataToCSV',
+  'scatterplotDownloadConfig',
+  'sortData',
+  'spreadConfig',
+  'spreadDownloadConfig',
+  'tableConfig',
+  'tableDownloadConfig',
+  'tableStyles',
+  'timeseriesConfig',
+  'timeseriesDownloadConfig',
+  'usePagination',
+  'useSelection',
+  'useSort',
+  'useWidgetSelector',
+  'useWidgetStore',
+  'widgetStoreActions',
+])

package/src/{widgets-v2 → widgets}/PERFORMANCE.md

@@ -35,11 +35,11 @@ once on mount and once per data refresh in the dynamic variants:
 
 ### Stories
 
-|                | v1                                                                                                     | v2                                                                                                        |
-| -------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
-| Source         | [performance.stories.tsx](../../../../apps/storybook/stories/react-ui/widgets/performance.stories.tsx) | [performance.stories.tsx](../../../../apps/storybook/stories/react-ui/widgets-v2/performance.stories.tsx) |
-| Storybook path | `React Ui/Widgets/Performance`                                                                         | `React UI/Widgets v2/Performance`                                                                         |
-| Console prefix | `[Performance]`                                                                                        | `[Performance v2]`                                                                                        |
+|                | v1                                                                                                     | v2                                                                                                     |
+| -------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| Source         | [performance.stories.tsx](../../../../apps/storybook/stories/react-ui/widgets/performance.stories.tsx) | [performance.stories.tsx](../../../../apps/storybook/stories/react-ui/widgets/performance.stories.tsx) |
+| Storybook path | `React Ui/Widgets/Performance`                                                                         | `React UI/Widgets/Performance`                                                                         |
+| Console prefix | `[Performance]`                                                                                        | `[Performance v2]`                                                                                     |
 
 ### Procedure
 

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

@@ -1,208 +1,180 @@
-/**
- * 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 { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { act, fireEvent, render, screen } from '@testing-library/react'
+import type { ECharts } from 'echarts'
 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>)
+import { Provider } from '../../provider/widget-provider'
+import {
+  applyTransforms,
+  clearAllWidgetStores,
+  getWidgetStore,
+  setEchartInstance,
+} from '../../stores'
+
+interface ChartHandlers {
+  finished?: () => void
 }
 
-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')
-  })
+interface MockChart {
+  dispatchAction: ReturnType<typeof vi.fn>
+  on: (ev: string, cb: () => void) => void
+  off: (ev: string, cb: () => void) => void
+  __handlers: ChartHandlers
+}
 
-  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)
-  })
+function makeMockChart(): MockChart {
+  const handlers: ChartHandlers = {}
+  return {
+    dispatchAction: vi.fn(),
+    on: (ev, cb) => {
+      if (ev === 'finished') handlers.finished = cb
+    },
+    off: (ev) => {
+      if (ev === 'finished') handlers.finished = undefined
+    },
+    __handlers: handlers,
+  }
+}
 
-  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)
-  })
+beforeEach(() => clearAllWidgetStores())
+afterEach(() => clearAllWidgetStores())
 
-  it('uses custom labels for aria-label', () => {
-    renderWithTheme(
-      <BrushToggle
-        id='bt-labels'
-        labels={{ enable: 'Brush on', disable: 'Brush off' }}
-      />,
+describe('<BrushToggle>', () => {
+  it('starts disabled by default', () => {
+    render(
+      <Provider id='bt-1' data={[]}>
+        <BrushToggle />
+      </Provider>,
     )
-    expect(screen.getByRole('button', { name: 'Brush on' })).toBeDefined()
+    expect(screen.getByLabelText('Enable brush selection')).toBeTruthy()
   })
 
-  it('respects an explicit ariaLabel', () => {
-    renderWithTheme(
-      <BrushToggle
-        id='bt-aria'
-        labels={{ ariaLabel: 'Toggle brush selection' }}
-      />,
+  it('respects initialEnabled=true', () => {
+    render(
+      <Provider id='bt-2' data={[]}>
+        <BrushToggle initialEnabled />
+      </Provider>,
     )
-    expect(
-      screen.getByRole('button', { name: 'Toggle brush selection' }),
-    ).toBeDefined()
+    expect(screen.getByLabelText('Disable brush selection')).toBeTruthy()
   })
 
-  it('renders custom Icon when provided', () => {
-    renderWithTheme(
-      <BrushToggle id='bt-icon' Icon={<span data-testid='custom-icon' />} />,
+  it('clicking enables the transform — brush config appears in the post-pipeline option', () => {
+    render(
+      <Provider id='bt-3' data={[1]}>
+        <BrushToggle />
+      </Provider>,
     )
-    expect(screen.getByTestId('custom-icon')).toBeDefined()
+    fireEvent.click(screen.getByLabelText('Enable brush selection'))
+    // configTransforms now apply inside <Widget.Echart>; replay the
+    // pipeline locally over a blank structural option.
+    const configTransforms = getWidgetStore('bt-3').getState().configTransforms
+    const opts = applyTransforms({}, configTransforms) as {
+      brush?: { xAxisIndex?: string }
+    }
+    expect(opts.brush).toBeTruthy()
+    expect(opts.brush?.xAxisIndex).toBe('all')
   })
-})
 
-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} />,
+  it('dispatches takeGlobalCursor with brush config when enabled and a chart is registered', () => {
+    const chart = makeMockChart()
+    setEchartInstance('bt-4', chart as unknown as ECharts)
+    render(
+      <Provider id='bt-4' data={[1]}>
+        <BrushToggle initialEnabled />
+      </Provider>,
     )
-    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,
+    expect(chart.dispatchAction).toHaveBeenCalledWith({
+      type: 'takeGlobalCursor',
+      key: 'brush',
+      brushOption: { brushType: 'lineX', brushMode: 'multiple' },
     })
   })
 
-  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} />,
+  it("re-dispatches takeGlobalCursor on the chart's 'finished' event", () => {
+    const chart = makeMockChart()
+    setEchartInstance('bt-5', chart as unknown as ECharts)
+    render(
+      <Provider id='bt-5' data={[1]}>
+        <BrushToggle initialEnabled />
+      </Provider>,
     )
-    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 },
+    chart.dispatchAction.mockClear()
+    act(() => chart.__handlers.finished?.())
+    expect(chart.dispatchAction).toHaveBeenCalledWith({
+      type: 'takeGlobalCursor',
+      key: 'brush',
+      brushOption: { brushType: 'lineX', brushMode: 'multiple' },
     })
-    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 },
+  it('on disable: clears the global cursor and wipes drawn areas', () => {
+    const chart = makeMockChart()
+    setEchartInstance('bt-6', chart as unknown as ECharts)
+    render(
+      <Provider id='bt-6' data={[1]}>
+        <BrushToggle initialEnabled />
+      </Provider>,
+    )
+    chart.dispatchAction.mockClear()
+    fireEvent.click(screen.getByLabelText('Disable brush selection'))
+    expect(chart.dispatchAction).toHaveBeenCalledWith({
+      type: 'takeGlobalCursor',
     })
-    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 },
+    expect(chart.dispatchAction).toHaveBeenCalledWith({
+      type: 'brush',
+      areas: [],
     })
-    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} />,
+  it('honors brushType=rect and brushMode=single', () => {
+    const chart = makeMockChart()
+    setEchartInstance('bt-7', chart as unknown as ECharts)
+    render(
+      <Provider id='bt-7' data={[1]}>
+        <BrushToggle initialEnabled brushType='rect' brushMode='single' />
+      </Provider>,
     )
-    expect(onBrushSelected).toHaveBeenCalledWith({
-      dataIndex: [1, 2],
-      seriesIndex: 0,
+    expect(chart.dispatchAction).toHaveBeenCalledWith({
+      type: 'takeGlobalCursor',
+      key: 'brush',
+      brushOption: { brushType: 'rect', brushMode: 'single' },
     })
   })
 
-  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} />,
+  it('wipes drawn brush areas when an external selection is cleared while enabled', () => {
+    const chart = makeMockChart()
+    setEchartInstance('bt-9', chart as unknown as ECharts)
+    const { rerender } = render(
+      <Provider id='bt-9' data={[1]}>
+        <BrushToggle initialEnabled selection={['a', 'b']} />
+      </Provider>,
     )
+    chart.dispatchAction.mockClear()
     rerender(
-      <ThemeProvider theme={theme}>
-        <BrushToggle id='bt-sel-dup' onBrushSelected={onBrushSelected} />
-      </ThemeProvider>,
+      <Provider id='bt-9' data={[1]}>
+        <BrushToggle initialEnabled selection={[]} />
+      </Provider>,
     )
-    expect(onBrushSelected).toHaveBeenCalledTimes(1)
+    expect(chart.dispatchAction).toHaveBeenCalledWith({
+      type: 'brush',
+      areas: [],
+    })
+  })
+
+  it('attaches the cursor reactively when the chart arrives *after* the toggle mounts', () => {
+    const chart = makeMockChart()
+    render(
+      <Provider id='bt-8' data={[1]}>
+        <BrushToggle initialEnabled />
+      </Provider>,
+    )
+    // Chart not yet registered — no dispatch should have happened.
+    expect(chart.dispatchAction).not.toHaveBeenCalled()
+    // Simulate the bridge mounting and publishing the instance.
+    act(() => setEchartInstance('bt-8', chart as unknown as ECharts))
+    expect(chart.dispatchAction).toHaveBeenCalledWith({
+      type: 'takeGlobalCursor',
+      key: 'brush',
+      brushOption: { brushType: 'lineX', brushMode: 'multiple' },
+    })
   })
 })