@carto/ps-react-ui 5.1.0 → 5.3.0

package/src/legend/stores/types.ts

@@ -96,7 +96,8 @@ export interface LegendRampVariable {
    * Ordered low→high stops. Discrete ramps **require `colors.length + 1`**
    * stops — the boundaries between color steps, including both outer edges —
    * and each label is centered on its boundary line (keep labels short, e.g.
-   * `20K`; there is no collision handling). A discrete ramp with any other
+   * `20K`; there is no collision handling; pass `''` to hide one — each step's
+   * tooltip still shows its full range). A discrete ramp with any other
    * stop count is incoherent and renders an inline error instead of the bar.
    * Continuous ramps show only the first/last endpoints.
    */
@@ -110,7 +111,8 @@ export interface LegendRampVariable {
    */
   avg?: number
   /**
-   * Formats `avg` for its tooltip. Default `String(avg)` — pass e.g.
+   * Formats `avg` and, on discrete ramps, the stop values shown in each
+   * step's range tooltip. Default `String(value)` — pass e.g.
    * `(v) => formatNumber(v, 'es-ES')` or `(v) => `${v}%``. Use a stable
    * reference (same contract as the other variable fields).
    */

package/src/widgets-v2/actions/download/csv-item.test.tsx

@@ -47,7 +47,7 @@ describe('buildCsvDownloadItem', () => {
         ['a', 1],
       ],
     })
-    const handle = await item.resolve()
+    const handle = await item.resolve({ id: null })
     expect(handle.url).toBe('blob:csv')
     expect(handle.filename).toBe('sales.csv')
     expect(csvText).toBe('name,value\na,1')
@@ -60,7 +60,7 @@ describe('buildCsvDownloadItem', () => {
       filename: 'sales',
       getRows: () => [['=SUM(A1)']],
     })
-    await item.resolve()
+    await item.resolve({ id: null })
     expect(csvText).toBe("'=SUM(A1)")
   })
 
@@ -69,7 +69,7 @@ describe('buildCsvDownloadItem', () => {
       filename: 'table',
       getCsv: () => 'col\n=raw',
     })
-    const handle = await item.resolve()
+    const handle = await item.resolve({ id: null })
     expect(handle.filename).toBe('table.csv')
     // getCsv is an escape hatch — content is used as-is, no extra escaping.
     expect(csvText).toBe('col\n=raw')

package/src/widgets-v2/actions/download/csv-item.tsx

@@ -1,7 +1,7 @@
 import { DOWNLOAD_ITEM_IDS } from './constants'
 import { downloadToCSV } from './exports'
 import { CSVIcon } from './icons'
-import type { DownloadItem } from './types'
+import type { DownloadContext, DownloadItem } from './types'
 
 interface BuildCsvDownloadItemBase {
   /** Base filename (without extension). The item appends `.csv`. */
@@ -23,7 +23,7 @@ export type BuildCsvDownloadItemArgs =
        * through `toCsvString` so escaping (incl. the spreadsheet
        * formula-injection guard) stays consistent across widgets.
        */
-      getRows: () => readonly (readonly unknown[])[]
+      getRows: (ctx: DownloadContext) => readonly (readonly unknown[])[]
       getCsv?: never
     })
   | (BuildCsvDownloadItemBase & {
@@ -32,7 +32,7 @@ export type BuildCsvDownloadItemArgs =
        * (e.g. Table) that already serialise their own CSV with bespoke
        * header/cell handling.
        */
-      getCsv: () => string
+      getCsv: (ctx: DownloadContext) => string
       getRows?: never
     })
 
@@ -49,9 +49,9 @@ export function buildCsvDownloadItem(
     id: DOWNLOAD_ITEM_IDS.csv,
     label: args.label ?? 'CSV',
     icon: <CSVIcon fontSize='small' />,
-    resolve: () => {
+    resolve: (ctx) => {
       if (args.getCsv) {
-        const csv = args.getCsv()
+        const csv = args.getCsv(ctx)
         const blob = new Blob([csv], { type: 'text/csv;charset=utf-8;' })
         const url = URL.createObjectURL(blob)
         return Promise.resolve({
@@ -60,7 +60,7 @@ export function buildCsvDownloadItem(
           revoke: () => URL.revokeObjectURL(url),
         })
       }
-      const handle = downloadToCSV(args.getRows())
+      const handle = downloadToCSV(args.getRows(ctx))
       return Promise.resolve({
         url: handle.url,
         filename: `${args.filename}.csv`,

package/src/widgets-v2/actions/download/download.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useState, type ComponentType } from 'react'
+import { useCallback, useContext, useState, type ComponentType } from 'react'
 import {
   CircularProgress,
   IconButton,
@@ -10,6 +10,7 @@ import {
 } from '@mui/material'
 import { FileDownload as DownloadIcon } from '@mui/icons-material'
 import { Tooltip } from '../../../components'
+import { WidgetContext } from '../../stores'
 import { triggerLinkDownload } from './exports'
 import type { DownloadItem } from './types'
 import { DEFAULT_DOWNLOAD_LABELS, type DownloadLabels } from './labels'
@@ -37,6 +38,7 @@ export function Download({
 }: DownloadProps) {
   const _labels = { ...DEFAULT_DOWNLOAD_LABELS, ...labels }
   const [anchorEl, setAnchorEl] = useState<HTMLElement | null>(null)
+  const id = useContext(WidgetContext)
   const [isDownloading, setIsDownloading] = useState(false)
   const [error, setError] = useState<Error | null>(null)
 
@@ -59,7 +61,7 @@ export function Download({
       setIsDownloading(true)
       setError(null)
       item
-        .resolve()
+        .resolve({ id })
         .then(({ url, filename, revoke }) => {
           // `item.filename` overrides what `resolve()` returns — lets consumers
           // template the filename with widget metadata declaratively.
@@ -78,7 +80,7 @@ export function Download({
           setIsDownloading(false)
         })
     },
-    [close, isDownloading, onError],
+    [close, id, isDownloading, onError],
   )
 
   const triggerLabel = isDownloading

package/src/widgets-v2/actions/download/index.ts

@@ -11,5 +11,5 @@ export { CSVIcon, PNGIcon, MarkdownIcon } from './icons'
 export { buildPngDownloadItem, type BuildPngDownloadItemArgs } from './png-item'
 export { buildCsvDownloadItem, type BuildCsvDownloadItemArgs } from './csv-item'
 export { DOWNLOAD_ITEM_IDS, type DownloadItemId } from './constants'
-export type { DownloadItem } from './types'
+export type { DownloadItem, DownloadContext } from './types'
 export { DEFAULT_DOWNLOAD_LABELS, type DownloadLabels } from './labels'

package/src/widgets-v2/actions/download/png-item.test.tsx

@@ -44,7 +44,7 @@ describe('buildPngDownloadItem', () => {
       filename: 'sales',
       getCaptureEl: () => document.createElement('div'),
     })
-    const handle = await item.resolve()
+    const handle = await item.resolve({ id: null })
     expect(handle.url).toBe('blob:png')
     expect(handle.filename).toBe('sales.png')
     handle.revoke?.()
@@ -56,7 +56,9 @@ describe('buildPngDownloadItem', () => {
       filename: 'demo',
       getCaptureEl: () => null,
     })
-    await expect(item.resolve()).rejects.toThrow(/No PNG capture element/)
+    await expect(item.resolve({ id: null })).rejects.toThrow(
+      /No PNG capture element/,
+    )
   })
 
   it('forwards pixelRatio and backgroundColor overrides', async () => {
@@ -66,7 +68,7 @@ describe('buildPngDownloadItem', () => {
       pixelRatio: 4,
       backgroundColor: '#fff',
     })
-    const handle = await item.resolve()
+    const handle = await item.resolve({ id: null })
     expect(handle.filename).toBe('sales.png')
   })
 })

package/src/widgets-v2/actions/download/png-item.tsx

@@ -1,7 +1,7 @@
 import { DOWNLOAD_ITEM_IDS } from './constants'
 import { downloadDOMToPNG } from './exports'
 import { PNGIcon } from './icons'
-import type { DownloadItem } from './types'
+import type { DownloadContext, DownloadItem } from './types'
 
 export interface BuildPngDownloadItemArgs {
   /** Base filename (without extension). The item appends `.png`. */
@@ -11,7 +11,7 @@ export interface BuildPngDownloadItemArgs {
    * download config doesn't capture a stale reference. Wire it to
    * `() => getCaptureEl(id)` from `widgets-v2/stores`.
    */
-  getCaptureEl: () => HTMLElement | null
+  getCaptureEl: (ctx: DownloadContext) => HTMLElement | null
   /** html2canvas `scale`. Default 2. */
   pixelRatio?: number
   /** html2canvas `backgroundColor`. Default transparent (`null`). */
@@ -33,8 +33,8 @@ export function buildPngDownloadItem(
     id: DOWNLOAD_ITEM_IDS.png,
     label: args.label ?? 'PNG',
     icon: <PNGIcon fontSize='small' />,
-    resolve: async () => {
-      const el = args.getCaptureEl()
+    resolve: async (ctx) => {
+      const el = args.getCaptureEl(ctx)
       if (!el) {
         throw new Error('[widgets-v2] No PNG capture element available')
       }

package/src/widgets-v2/actions/download/types.ts

@@ -1,5 +1,17 @@
 import type { ReactElement } from 'react'
 
+/**
+ * Passed to {@link DownloadItem.resolve} by `<Widget.Download>`.
+ */
+export interface DownloadContext {
+  /**
+   * Id of the widget store the menu was opened from — the dialog's own
+   * store when opened from `FullScreen.Slot`'s header, so an export matches
+   * what the user is looking at. `null` outside a `<Widget.Provider>`.
+   */
+  id: string | null
+}
+
 export interface DownloadItem {
   /** Unique key (also used as menu label key). */
   id: string
@@ -28,5 +40,7 @@ export interface DownloadItem {
    * Resolves to a Blob URL the trigger will click. Optional `revoke` is
    * called after the click is dispatched.
    */
-  resolve: () => Promise<{ url: string; filename: string; revoke?: () => void }>
+  resolve: (
+    ctx: DownloadContext,
+  ) => Promise<{ url: string; filename: string; revoke?: () => void }>
 }

package/src/widgets-v2/actions/fullscreen/fullscreen-store.test.tsx

@@ -0,0 +1,155 @@
+import { describe, it, expect, afterEach, vi } from 'vitest'
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { Provider } from '../../provider/widget-provider'
+import type { ECharts } from 'echarts'
+import {
+  clearAllWidgetStores,
+  getWidgetStore,
+  hasWidgetStore,
+  setEchartInstance,
+  useWidget,
+  useWidgetId,
+} from '../../stores'
+import { Download } from '../download/download'
+import { FullScreen, fullScreenStoreId } from './fullscreen'
+
+afterEach(() => clearAllWidgetStores())
+
+// A stand-in for any action: reads and writes one flag on whichever store
+// its copy runs on.
+function Flag() {
+  const id = useWidgetId()
+  const on = useWidget(id, (s) => s.transformStates.flag?.enabled ?? false)
+  return (
+    <button
+      type='button'
+      data-testid={`flag-${id}`}
+      aria-pressed={on}
+      onClick={() =>
+        getWidgetStore(id).setState((s) => ({
+          transformStates: { ...s.transformStates, flag: { enabled: !on } },
+        }))
+      }
+    >
+      flag
+    </button>
+  )
+}
+
+function DataProbe() {
+  const id = useWidgetId()
+  const data = useWidget(id, (s) => s.rawData)
+  return <span data-testid={`data-${id}`}>{String(data)}</span>
+}
+
+function Widget({ data = 'a' }: { data?: string }) {
+  return (
+    <Provider id='w' data={data}>
+      <FullScreen.Trigger labels={{ open: 'OpenT', close: 'CloseT' }} />
+      <FullScreen.Slot>
+        <Flag />
+        <DataProbe />
+      </FullScreen.Slot>
+    </Provider>
+  )
+}
+
+const dialogId = fullScreenStoreId('w')
+const flag = (id: string) =>
+  screen.getByTestId(`flag-${id}`).getAttribute('aria-pressed')
+
+async function close() {
+  fireEvent.click(screen.getByLabelText('CloseT'))
+  await waitFor(() =>
+    expect(screen.queryByTestId(`flag-${dialogId}`)).toBeNull(),
+  )
+}
+
+describe('<FullScreen.Slot> — the dialog runs on its own store', () => {
+  it('starts from the card, runs apart while open, and hands back on close', async () => {
+    render(<Widget />)
+    fireEvent.click(screen.getByTestId('flag-w'))
+    expect(flag('w')).toBe('true')
+
+    fireEvent.click(screen.getByLabelText('OpenT'))
+    // Seeded from the card.
+    expect(flag(dialogId)).toBe('true')
+
+    // Changes in the dialog don't reach the card while open…
+    fireEvent.click(screen.getByTestId(`flag-${dialogId}`))
+    expect(flag(dialogId)).toBe('false')
+    expect(flag('w')).toBe('true')
+
+    // …and do once it closes. The dialog's store goes with it.
+    await close()
+    expect(flag('w')).toBe('false')
+    expect(hasWidgetStore(dialogId)).toBe(false)
+  })
+
+  it('keeps the consumer props flowing into the dialog while it is open', () => {
+    const { rerender } = render(<Widget data='a' />)
+    fireEvent.click(screen.getByLabelText('OpenT'))
+    expect(screen.getByTestId(`data-${dialogId}`).textContent).toBe('a')
+    rerender(<Widget data='b' />)
+    expect(screen.getByTestId(`data-${dialogId}`).textContent).toBe('b')
+  })
+
+  it('reopening starts from the card again, not from the last dialog', async () => {
+    render(<Widget />)
+    fireEvent.click(screen.getByLabelText('OpenT'))
+    await close()
+    act(() =>
+      getWidgetStore('w').setState({
+        transformStates: { flag: { enabled: true } },
+      }),
+    )
+    fireEvent.click(screen.getByLabelText('OpenT'))
+    expect(flag(dialogId)).toBe('true')
+  })
+
+  it('downloads from the dialog header resolve against the dialog store', async () => {
+    const resolve = vi.fn(() =>
+      Promise.resolve({ url: 'blob:x', filename: 'x.csv' }),
+    )
+    render(
+      <Provider id='w' data='a'>
+        <FullScreen.Trigger labels={{ open: 'OpenT', close: 'CloseT' }} />
+        <FullScreen.Slot
+          actions={<Download items={[{ id: 'csv', label: 'CSV', resolve }]} />}
+        >
+          <span>body</span>
+        </FullScreen.Slot>
+      </Provider>,
+    )
+    fireEvent.click(screen.getByLabelText('OpenT'))
+    fireEvent.click(screen.getByLabelText('Download'))
+    fireEvent.click(await screen.findByText('CSV'))
+    expect(resolve).toHaveBeenCalledWith({ id: dialogId })
+  })
+
+  // Legend / dataZoom / brush live in the chart instance, not the store.
+  // The Slot moves them through the instance registry, so Widget.Echart
+  // doesn't need to know about fullscreen.
+  it('starts the dialog chart from the card chart and hands it back on close', async () => {
+    const fakeChart = (option: object) =>
+      ({
+        getOption: vi.fn(() => option),
+        setOption: vi.fn(),
+        dispatchAction: vi.fn(),
+        isDisposed: () => false,
+      }) as unknown as ECharts & {
+        setOption: ReturnType<typeof vi.fn>
+      }
+    const card = fakeChart({ from: 'card' })
+    const dialog = fakeChart({ from: 'dialog' })
+    render(<Widget />)
+    act(() => setEchartInstance('w', card))
+
+    fireEvent.click(screen.getByLabelText('OpenT'))
+    act(() => setEchartInstance(dialogId, dialog))
+    expect(dialog.setOption).toHaveBeenCalledWith({ from: 'card' })
+
+    await close()
+    expect(card.setOption).toHaveBeenCalledWith({ from: 'dialog' })
+  })
+})

package/src/widgets-v2/actions/fullscreen/fullscreen.test.tsx

@@ -1,6 +1,6 @@
-import { useEffect, useRef } from 'react'
+import { useEffect } from 'react'
 import { describe, it, expect, beforeEach, afterEach } from 'vitest'
-import { fireEvent, render, screen } from '@testing-library/react'
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
 import { Provider } from '../../provider/widget-provider'
 import { clearAllWidgetStores, getWidgetStore } from '../../stores'
 import { FullScreen } from './fullscreen'
@@ -61,22 +61,35 @@ describe('<FullScreen.Trigger> — store toggle', () => {
 })
 
 describe('<FullScreen.Slot> — render-prop body + portal', () => {
-  it('passes the live isFullScreen flag to the render prop', () => {
-    let received: boolean | undefined
+  it('passes false to the card copy and true to the dialog copy', () => {
     render(
       <Provider id='fs-rp' data={[]}>
         <FullScreen.Trigger />
         <FullScreen.Slot>
-          {(isFullScreen) => {
-            received = isFullScreen
-            return <span data-testid='body'>body</span>
-          }}
+          {(isFullScreen) => (
+            <span data-testid={isFullScreen ? 'dialog' : 'card'}>body</span>
+          )}
         </FullScreen.Slot>
       </Provider>,
     )
-    expect(received).toBe(false)
+    expect(screen.getByTestId('card')).toBeTruthy()
+    expect(screen.queryByTestId('dialog')).toBeNull()
     fireEvent.click(screen.getByLabelText('Open in full screen'))
-    expect(received).toBe(true)
+    expect(screen.getByTestId('card')).toBeTruthy()
+    expect(screen.getByTestId('dialog')).toBeTruthy()
+  })
+
+  it('renders plain children identically in both copies', () => {
+    render(
+      <Provider id='fs-plain' data={[]}>
+        <FullScreen.Trigger />
+        <FullScreen.Slot>
+          <span data-testid='body'>body</span>
+        </FullScreen.Slot>
+      </Provider>,
+    )
+    fireEvent.click(screen.getByLabelText('Open in full screen'))
+    expect(screen.getAllByTestId('body')).toHaveLength(2)
   })
 
   it('renders the title above the body when open', async () => {
@@ -166,47 +179,32 @@ describe('<FullScreen.Slot> — render-prop body + portal', () => {
     expect(css.maxWidth).toBe('921.6px')
   })
 
-  it('keeps the same DOM node across the fullscreen toggle (portal reparent)', () => {
-    render(
-      <Provider id='fs-reparent' data={[]}>
-        <FullScreen.Trigger />
-        <FullScreen.Slot title='X'>
-          {() => <span data-testid='inner'>inner</span>}
-        </FullScreen.Slot>
-      </Provider>,
-    )
-    const before = screen.getByTestId('inner')
-    fireEvent.click(screen.getByLabelText('Open in full screen'))
-    const after = screen.getByTestId('inner')
-    expect(after).toBe(before)
-  })
-
-  it('mounts the body exactly once across multiple fullscreen toggles', () => {
-    let mountCount = 0
+  it('keeps the card body mounted while the dialog mounts its own copy', async () => {
+    let mounts = 0
     function CountingChild() {
-      const counted = useRef(false)
       useEffect(() => {
-        if (counted.current) return
-        counted.current = true
-        mountCount += 1
+        mounts += 1
       }, [])
       return <div data-testid='counter'>x</div>
     }
-    // Distinct labels for the trigger so its "close" aria-label can't collide
-    // with the modal's own close button (also "Exit full screen" by default
-    // when keepMounted=true keeps the modal in DOM).
     render(
-      <Provider id='fs-mount-once' data={[]}>
+      <Provider id='fs-two-copies' data={[]}>
         <FullScreen.Trigger labels={{ open: 'OpenT', close: 'CloseT' }} />
-        <FullScreen.Slot title='Z'>{() => <CountingChild />}</FullScreen.Slot>
+        <FullScreen.Slot title='Z'>
+          <CountingChild />
+        </FullScreen.Slot>
       </Provider>,
     )
-    expect(mountCount).toBe(1)
+    const card = screen.getByTestId('counter')
+    expect(mounts).toBe(1)
     fireEvent.click(screen.getByLabelText('OpenT'))
-    expect(mountCount).toBe(1)
+    expect(mounts).toBe(2)
+    expect(screen.getAllByTestId('counter')).toHaveLength(2)
+    expect(screen.getAllByTestId('counter')).toContain(card)
     fireEvent.click(screen.getByLabelText('CloseT'))
-    expect(mountCount).toBe(1)
-    fireEvent.click(screen.getByLabelText('OpenT'))
-    expect(mountCount).toBe(1)
+    await waitFor(() =>
+      expect(screen.getAllByTestId('counter')).toHaveLength(1),
+    )
+    expect(screen.getByTestId('counter')).toBe(card)
   })
 })