@carto/ps-react-ui 6.0.0 → 6.1.0

package/src/widgets/actions/fullscreen/fullscreen.tsx

@@ -1,11 +1,12 @@
+import type { ECharts } from 'echarts'
 import {
   useCallback,
   useLayoutEffect,
+  useRef,
   useState,
   type ComponentType,
   type ReactNode,
 } from 'react'
-import { createPortal } from 'react-dom'
 import {
   Box,
   Dialog,
@@ -24,7 +25,19 @@ import { Fullscreen as FullscreenIcon } from '@mui/icons-material'
 import { FullscreenExit as FullscreenExitIcon } from '@mui/icons-material'
 import { Close as CloseIcon } from '@mui/icons-material'
 import { Tooltip } from '../../../components'
-import { getWidgetStore, useWidget, useWidgetId } from '../../stores'
+import { Provider } from '../../provider/widget-provider'
+import {
+  createWidgetStore,
+  getEchartInstance,
+  getWidgetStore,
+  hasWidgetStore,
+  setWidgetStoreEntry,
+  subscribeEchartInstance,
+  useWidget,
+  useWidgetId,
+  useWidgetShallow,
+  type WidgetState,
+} from '../../stores'
 import { DEFAULT_FULLSCREEN_LABELS, type FullScreenLabels } from './labels'
 import type { FullScreenWidgetState } from './types'
 import { styles } from './style'
@@ -38,11 +51,18 @@ export interface FullScreenTriggerProps {
 
 export interface FullScreenSlotProps {
   /**
-   * Render-prop body. Receives the live `isFullScreen` flag so the consumer
-   * can branch per-mode props (e.g., `Widget.Toolbox visibleCount`) without
-   * duplicating the JSX.
+   * The widget body. Rendered twice, identically: in the card, and again in
+   * the dialog while it's open. The components inside don't know which copy
+   * they are; the dialog's just runs on a widget store of its own — a copy
+   * of the card's taken on open, handed back to the card on close — so read
+   * the widget id with `useWidgetId()` inside the body rather than closing
+   * over the card's `id`.
+   *
+   * @deprecated The function form `(isFullScreen) => ReactNode` still works
+   * (`false` for the card, `true` for the dialog copy) but will be removed
+   * in the next major: pass the body as plain children.
    */
-  children: (isFullScreen: boolean) => ReactNode
+  children: ReactNode | ((isFullScreen: boolean) => ReactNode)
   /** Header text rendered above the body when the modal is open. */
   title?: ReactNode
   /**
@@ -113,15 +133,42 @@ function FullScreenTrigger({
   )
 }
 
+/** Id of the widget store the dialog copy runs on. */
+export function fullScreenStoreId(id: string): string {
+  return `${id}::fullscreen`
+}
+
+// Fields a copy doesn't carry between the card's store and the dialog's:
+// what the consumer feeds through Provider props (kept live on both), what
+// the pipeline derives, the transforms (functions each copy's actions
+// register in their own store) and the open flag itself.
+const NOT_COPIED = new Set<string>([
+  'rawData',
+  'data',
+  'dataTransforms',
+  'configTransforms',
+  'isLoading',
+  'isFetching',
+  'error',
+  'rawFormatter',
+  'labelFormatter',
+  'isFullScreen',
+])
+
+/** The UI state a copy carries: toggles, search text, sort, page… */
+function copiedState(state: WidgetState): Partial<WidgetState> {
+  return Object.fromEntries(
+    Object.entries(state).filter(([key]) => !NOT_COPIED.has(key)),
+  ) as Partial<WidgetState>
+}
+
 /**
- * Body wrapper. Renders its render-prop children once, via a single
- * `createPortal` call whose container is a stable `<div>` we hold as a ref.
- * That div is moved imperatively between an inline placeholder and the
- * `<DialogContent>` of an MUI `<Dialog keepMounted>`. Because both the
- * React parent (the portal call site) AND the portal container are
- * identical across the toggle, the subtree keeps its fiber identity and
- * ECharts (or any other heavy child) stays mounted while only its DOM
- * parent changes.
+ * Body wrapper. The card keeps its copy of the body while the dialog is
+ * open, and the dialog mounts a second one on a store of its own: a copy
+ * of the card's UI state taken on open, and handed back to the card when
+ * the dialog closes. While open the two don't affect each other. MUI
+ * mounts the dialog copy on open and unmounts it after the close
+ * transition, which drops its store.
  */
 function FullScreenSlot({
   children,
@@ -144,59 +191,34 @@ function FullScreenSlot({
   // margins — on a screen that small, fullscreen should mean fullscreen.
   const theme = useTheme()
   const fullBleed = useMediaQuery(theme.breakpoints.down('sm'))
-  const [inlineEl, setInlineEl] = useState<HTMLElement | null>(null)
-  const [dialogEl, setDialogEl] = useState<HTMLElement | null>(null)
-  // Stable, never-changing portal container created once per slot. Held in
-  // state (not a ref) so the React Compiler is happy reading it during
-  // render — it's immutable from React's perspective, only its DOM parent
-  // changes via `appendChild`. Switching `createPortal`'s `container`
-  // argument makes React unmount and remount the children, defeating the
-  // single-mount goal; keeping the container identical and moving the div
-  // imperatively avoids that.
-  const [portalDiv] = useState<HTMLDivElement | null>(() => {
-    if (typeof document === 'undefined') return null
-    const div = document.createElement('div')
-    // `display: contents` keeps the wrapper transparent in flow so it
-    // doesn't introduce a stray block when nested inside the inline slot.
-    div.style.display = 'contents'
-    return div
-  })
-
   const handleClose = useCallback(() => {
     getWidgetStore(id).setState({
       isFullScreen: false,
     } as Partial<FullScreenWidgetState>)
   }, [id])
 
-  // Reparent the portal div into the active host whenever `open` (or either
-  // host) changes. `useLayoutEffect` runs synchronously after commit (after
-  // refs have been written), so the dialog ref is already live when we read
-  // it.
-  //
-  // Anti-blink: pin a `min-height` on the inline shell that's always live —
-  // not just while fullscreen is open. We re-measure whenever the body is
-  // inline (open=false) so the lock tracks data-driven height changes
-  // (Formula adding rows, Table growing, ECharts re-init…) and survives
-  // every fullscreen toggle. Briefly clearing minHeight before the measure
-  // lets the lock shrink as well as grow; both operations are synchronous
-  // within useLayoutEffect, so the browser never paints the intermediate
-  // "no lock" frame.
+  // Closing hands the dialog's state back to the card. Keyed on the flag,
+  // not on the close button, so every way out (Escape, backdrop, a Trigger)
+  // counts. The dialog copy is still mounted here — it unmounts after the
+  // transition — so its store still exists.
+  const wasOpen = useRef(open)
   useLayoutEffect(() => {
-    if (!portalDiv || !inlineEl) return
-    const host = open ? dialogEl : inlineEl
-    if (host && portalDiv.parentNode !== host) {
-      host.appendChild(portalDiv)
+    const dialogId = fullScreenStoreId(id)
+    if (wasOpen.current && !open && hasWidgetStore(dialogId)) {
+      getWidgetStore(id).setState(
+        copiedState(getWidgetStore(dialogId).getState()),
+      )
     }
-    if (!open) refreshInlineHeightLock(inlineEl)
-  }, [open, inlineEl, dialogEl, portalDiv])
+    wasOpen.current = open
+  }, [id, open])
 
   const titleId = `widget-fullscreen-title-${id}`
-  const rendered = children(open)
+  const render = (inDialog: boolean) =>
+    typeof children === 'function' ? children(inDialog) : children
 
   return (
     <>
-      <Box ref={setInlineEl} sx={styles.inlineSlot} />
-      {portalDiv ? createPortal(rendered, portalDiv) : null}
+      <Box sx={styles.inlineSlot}>{render(false)}</Box>
       <Dialog
         open={open}
         onClose={handleClose}
@@ -214,41 +236,133 @@ function FullScreenSlot({
         // default modal layer the menu portals after the dialog and wins on
         // DOM order, and the tooltip wins on z-index.
         //
-        // This used to sit at `tooltip + 1` to cover a Toolbox popper left
-        // open when fullscreen opened. That's the Toolbox's own job and it
-        // already does it: `visibleCount` flips to `undefined` in fullscreen,
-        // overflow disappears and the popper unmounts. A consumer who keeps a
-        // numeric `visibleCount` in fullscreen keeps its popper above the
-        // dialog — which is the correct layer for a popover opened from
-        // inside it anyway.
+        // A Toolbox popover opened from inside the dialog portals after it
+        // too, so it stays above the dialog — the right layer for it.
       >
-        <DialogTitle id={titleId} component='div' sx={styles.dialogTitle}>
-          <Typography
-            variant='subtitle1'
-            component='span'
-            sx={styles.titleText}
-          >
-            {title}
-          </Typography>
-          <Box sx={styles.dialogActions}>
-            {actions}
-            <Tooltip title={_labels.close}>
-              <IconButton
-                size='small'
-                aria-label={_labels.close}
-                onClick={handleClose}
-              >
-                <CloseSvg fontSize='small' {...iconProps} />
-              </IconButton>
-            </Tooltip>
-          </Box>
-        </DialogTitle>
-        <DialogContent ref={setDialogEl} sx={styles.dialogContent} />
+        <DialogStore sourceId={id}>
+          <DialogTitle id={titleId} component='div' sx={styles.dialogTitle}>
+            <Typography
+              variant='subtitle1'
+              component='span'
+              sx={styles.titleText}
+            >
+              {title}
+            </Typography>
+            <Box sx={styles.dialogActions}>
+              {actions}
+              <Tooltip title={_labels.close}>
+                <IconButton
+                  size='small'
+                  aria-label={_labels.close}
+                  onClick={handleClose}
+                >
+                  <CloseSvg fontSize='small' {...iconProps} />
+                </IconButton>
+              </Tooltip>
+            </Box>
+          </DialogTitle>
+          <DialogContent sx={styles.dialogContent}>
+            {render(true)}
+          </DialogContent>
+        </DialogStore>
       </Dialog>
     </>
   )
 }
 
+/**
+ * Gives the dialog copy (header actions included) its own widget store,
+ * seeded from the card's when the dialog mounts, and keeps the consumer's
+ * props (data, loading, error, formatters) flowing into it from the card
+ * while it's open. Does the same for the chart, if the widget has one: the
+ * dialog's starts from the card's and hands its state back on close.
+ */
+function DialogStore({
+  sourceId,
+  children,
+}: {
+  sourceId: string
+  children: ReactNode
+}) {
+  const dialogId = fullScreenStoreId(sourceId)
+  // What the consumer feeds the card through its Provider props, in the
+  // same shape, so the dialog's Provider gets exactly the same.
+  const live = useWidgetShallow(sourceId, (s) => ({
+    data: s.rawData,
+    isLoading: s.isLoading,
+    isFetching: s.isFetching,
+    error: s.error,
+    formatter: s.rawFormatter,
+    labelFormatter: s.labelFormatter,
+  }))
+  // Runs before the Provider below looks the id up, so it adopts this
+  // store instead of creating an empty one.
+  useState(() => {
+    const store = createWidgetStore(dialogId, live)
+    store.setState(copiedState(getWidgetStore(sourceId).getState()))
+    setWidgetStoreEntry(dialogId, store)
+    return store
+  })
+
+  // A layout effect on purpose. It subscribes before the dialog chart's
+  // (passive) init effect publishes it, and its cleanup runs before that
+  // chart's (passive) dispose — so the chart is still alive to copy from.
+  useLayoutEffect(() => {
+    let dialogChart: ECharts | null = null
+    const unsubscribe = subscribeEchartInstance(dialogId, (chart) => {
+      // Published from inside the chart's init, before its first
+      // setOption, so the dialog's own option merges on top of the copy.
+      const card = liveChart(sourceId)
+      if (chart && card) copyChartState(card, chart)
+      dialogChart = chart
+    })
+    return () => {
+      unsubscribe()
+      const card = liveChart(sourceId)
+      if (card && dialogChart && !dialogChart.isDisposed()) {
+        copyChartState(dialogChart, card)
+      }
+    }
+  }, [dialogId, sourceId])
+
+  return (
+    <Provider id={dialogId} {...live}>
+      {children}
+    </Provider>
+  )
+}
+
+function liveChart(id: string): ECharts | null {
+  const chart = getEchartInstance(id)
+  return chart && !chart.isDisposed() ? chart : null
+}
+
+/**
+ * Put on `chart` what `peer` is showing: the legend selection, the dataZoom
+ * window and any drawn brush areas, which live in the ECharts instance
+ * rather than the widget store.
+ */
+function copyChartState(peer: ECharts, chart: ECharts): void {
+  chart.setOption(peer.getOption())
+  // The pointer was over `peer`, not `chart`: drop the tooltip and axis
+  // pointer that came along, or they'd stay drawn until the next hover.
+  chart.dispatchAction({ type: 'hideTip' })
+  chart.dispatchAction({ type: 'updateAxisPointer', currTrigger: 'leave' })
+  // Brush areas sit on the brush model, not in `getOption()`. `getModel` is
+  // private in the typings but stable across 5.x.
+  // ponytail: private API; if it goes away, track areas from the `brush` event instead.
+  const areas = (
+    peer as unknown as {
+      getModel?: () => {
+        getComponent: (type: string) => { areas?: unknown[] } | undefined
+      }
+    }
+  )
+    .getModel?.()
+    .getComponent('brush')?.areas
+  if (areas?.length) chart.dispatchAction({ type: 'brush', areas })
+}
+
 /**
  * Merge a caller's `paperSx` over the default paper.
  *
@@ -271,18 +385,6 @@ function resolvePaperSx(paperSx: SxProps<Theme> | undefined): SxProps<Theme> {
   }
 }
 
-/**
- * Briefly clear the inline shell's `min-height`, measure its natural
- * height, then re-pin. Lives outside the component so the React Compiler
- * doesn't see the DOM mutation as an attempt to modify a `useState` value
- * — `el` here is just a parameter, not a tracked store value.
- */
-function refreshInlineHeightLock(el: HTMLElement): void {
-  el.style.minHeight = ''
-  const h = el.getBoundingClientRect().height
-  if (h > 0) el.style.minHeight = `${h}px`
-}
-
 /**
  * Namespace export. Consumers compose with:
  *
@@ -292,7 +394,7 @@ function refreshInlineHeightLock(el: HTMLElement): void {
  * </Widget.Actions>
  * <Widget.Content>
  *   <Widget.FullScreen.Slot title={title} actions={<Widget.Download items={items} />}>
- *     {(isFullScreen) => <Body visibleCount={isFullScreen ? undefined : 2} />}
+ *     <Body />
  *   </Widget.FullScreen.Slot>
  * </Widget.Content>
  * ```

package/src/widgets/actions/index.ts

@@ -55,6 +55,7 @@ export {
   triggerLinkDownload,
   buildPngDownloadItem,
   buildCsvDownloadItem,
+  withPngItem,
   CSVIcon,
   PNGIcon,
   MarkdownIcon,
@@ -62,11 +63,13 @@ export {
   DOWNLOAD_ITEM_IDS,
   type DownloadProps,
   type DownloadItem,
+  type DownloadContext,
   type DownloadItemId,
   type DownloadHandle,
   type DownloadDOMToPNGOptions,
   type BuildPngDownloadItemArgs,
   type BuildCsvDownloadItemArgs,
+  type WidgetDownloadArgs,
   type DownloadLabels,
 } from './download'
 export {

package/src/widgets/actions/searcher/filter.test.ts

@@ -0,0 +1,28 @@
+import { describe, it, expect } from 'vitest'
+import { filterBySearchText } from './filter'
+
+const DATA = [
+  [
+    { name: 'ES', value: 1 },
+    { name: 'FR', value: 2 },
+  ],
+]
+const COUNTRIES: Record<string, string> = { ES: 'Spain', FR: 'France' }
+const label = (v: string | number) => COUNTRIES[v] ?? v
+
+describe('filterBySearchText', () => {
+  it('matches the raw name when there is no label formatter', () => {
+    expect(filterBySearchText(DATA, 'es')).toEqual([[{ name: 'ES', value: 1 }]])
+  })
+
+  it('matches the formatted label, which is what the user sees', () => {
+    expect(filterBySearchText(DATA, 'spa', label)).toEqual([
+      [{ name: 'ES', value: 1 }],
+    ])
+  })
+
+  it('no longer matches a raw name the label does not show', () => {
+    // "es" is in the raw code "ES" but in neither "Spain" nor "France".
+    expect(filterBySearchText(DATA, 'es', label)).toEqual([[]])
+  })
+})

package/src/widgets/actions/searcher/filter.ts

@@ -1,9 +1,14 @@
 /**
  * Filters a 2D series of `{name, ...}` records by case-insensitive substring on
- * the `name` field. Keeps the dataset shape (one inner array per series).
+ * the label the user sees: `labelFormatter(name)` when a formatter is given,
+ * `name` otherwise. Keeps the dataset shape (one inner array per series).
  * Used by the Searcher action's data transform.
  */
-export function filterBySearchText(input: unknown, search: string): unknown {
+export function filterBySearchText(
+  input: unknown,
+  search: string,
+  labelFormatter?: (value: string | number) => string | number,
+): unknown {
   if (!search) return input
   const needle = search.toLowerCase()
   if (!Array.isArray(input)) return input
@@ -13,14 +18,27 @@ export function filterBySearchText(input: unknown, search: string): unknown {
       if (item == null) return false
       if (typeof item === 'object' && 'name' in item) {
         const rawName = (item as { name: unknown }).name
-        const name = rawName == null ? '' : stringifyPrimitive(rawName)
-        return name.toLowerCase().includes(needle)
+        return labelOf(rawName, labelFormatter).toLowerCase().includes(needle)
       }
       return stringifyPrimitive(item).toLowerCase().includes(needle)
     })
   })
 }
 
+function labelOf(
+  name: unknown,
+  labelFormatter?: (value: string | number) => string | number,
+): string {
+  if (name == null) return ''
+  if (
+    labelFormatter &&
+    (typeof name === 'string' || typeof name === 'number')
+  ) {
+    return stringifyPrimitive(labelFormatter(name))
+  }
+  return stringifyPrimitive(name)
+}
+
 function stringifyPrimitive(v: unknown): string {
   if (typeof v === 'string') return v
   if (typeof v === 'number' || typeof v === 'boolean') return String(v)

package/src/widgets/actions/searcher/searcher-toggle.tsx

@@ -7,6 +7,7 @@ import {
   useSingleTransform,
   useWidget,
   useWidgetId,
+  type WidgetState,
 } from '../../stores'
 import { filterBySearchText } from './filter'
 import { DEFAULT_SEARCHER_LABELS, type SearcherLabels } from './labels'
@@ -41,16 +42,18 @@ export function SearcherToggle({
 }: SearcherToggleProps) {
   const id = useWidgetId()
   const resolved = { ...DEFAULT_SEARCHER_LABELS, ...labels }
-  const text = useWidget(
-    id,
-    (s) => (s.transformStates.searcher?.searchText as string | undefined) ?? '',
-  )
+  const text = useWidget(id, selectSearchText)
+
+  // Matched against the label the user sees, so a formatted name is found
+  // by what's on screen rather than by its raw value.
+  const labelFormatter = useWidget(id, (s) => s.labelFormatter)
 
-  // The transform fn closes over `text`. Memoize via useCallback so identity
-  // only changes when text changes, allowing useTransform to re-register.
+  // The transform fn closes over `text` and `labelFormatter`. Memoize via
+  // useCallback so identity only changes when either does, allowing
+  // useTransform to re-register.
   const fn = useCallback(
-    (data: unknown) => filterBySearchText(data, text),
-    [text],
+    (data: unknown) => filterBySearchText(data, text, labelFormatter),
+    [text, labelFormatter],
   )
 
   const { enabled, toggle } = useSingleTransform(id, SEARCHER_DESCRIPTOR, fn, {
@@ -72,6 +75,11 @@ export function SearcherToggle({
   )
 }
 
+/** The widget's current search text; empty until someone types. */
+export function selectSearchText(s: WidgetState): string {
+  return (s.transformStates.searcher?.searchText as string | undefined) ?? ''
+}
+
 /**
  * Imperatively writes the search text into the widget store. Used by the
  * Searcher input to update text inside transformStates without going through

package/src/widgets/actions/searcher/searcher.test.tsx

@@ -89,4 +89,26 @@ describe('<Searcher> + <SearcherToggle>', () => {
       vi.useRealTimers()
     }
   })
+
+  it('filters by the formatted label the widget shows', () => {
+    const labelFormatter = (v: string | number) =>
+      ({ apple: 'Manzana', banana: 'Plátano' })[String(v)] ?? v
+    render(
+      <Provider id='sr-label' data={DATA} labelFormatter={labelFormatter}>
+        <SearcherToggle initialEnabled />
+        <Searcher />
+      </Provider>,
+    )
+    act(() =>
+      getWidgetStore('sr-label').setState((s) => ({
+        transformStates: {
+          ...s.transformStates,
+          searcher: { ...s.transformStates.searcher!, searchText: 'manz' },
+        },
+      })),
+    )
+    expect(getWidgetStore('sr-label').getState().data).toEqual([
+      [{ name: 'apple', value: 1 }],
+    ])
+  })
 })

package/src/widgets/actions/searcher/searcher.tsx

@@ -3,8 +3,8 @@ import { IconButton, InputAdornment, TextField } from '@mui/material'
 import { Search as SearchIcon } from '@mui/icons-material'
 import { Clear as ClearIcon } from '@mui/icons-material'
 import { debounce } from '@carto/ps-utils'
-import { getWidgetStore, useWidget, useWidgetId } from '../../stores'
-import { setSearcherText } from './searcher-toggle'
+import { useWidget, useWidgetId } from '../../stores'
+import { selectSearchText, setSearcherText } from './searcher-toggle'
 import { DEFAULT_SEARCHER_LABELS, type SearcherLabels } from './labels'
 import { styles } from './style'
 
@@ -33,12 +33,20 @@ export function Searcher({
 
   const inputRef = useRef<HTMLInputElement | null>(null)
 
+  const stored = useWidget(id, selectSearchText)
   // Hydrate from the store so re-toggling the input preserves any prior text.
-  const [local, setLocal] = useState<string>(
-    () =>
-      (getWidgetStore(id).getState().transformStates.searcher?.searchText as
-        string | undefined) ?? '',
-  )
+  const [local, setLocal] = useState(stored)
+
+  // Follow text written by another Searcher of the same widget (the card
+  // and the fullscreen copy each render one). Skipped while this input has
+  // focus: its own debounced write lands late, and adopting it would drop
+  // whatever was typed since.
+  const [focused, setFocused] = useState(false)
+  const [prevStored, setPrevStored] = useState(stored)
+  if (stored !== prevStored) {
+    setPrevStored(stored)
+    if (!focused) setLocal(stored)
+  }
 
   const debouncedWrite = useMemo(
     () =>
@@ -78,6 +86,8 @@ export function Searcher({
       placeholder={resolved.placeholder}
       value={local}
       onChange={handleSearchTextChange}
+      onFocus={() => setFocused(true)}
+      onBlur={() => setFocused(false)}
       // The Searcher only mounts when the user explicitly toggles the
       // SearcherToggle action — focusing the input on mount matches user
       // intent, so the jsx-a11y/no-autofocus warning is the false-positive

package/src/widgets/bar/download.test.tsx

@@ -50,7 +50,9 @@ describe('createBarDownloadConfig', () => {
     })
     const png = items.find((i) => i.id === 'png')
     expect(png).toBeTruthy()
-    await expect(png!.resolve()).rejects.toThrow(/No PNG capture element/)
+    await expect(png!.resolve({ id: null })).rejects.toThrow(
+      /No PNG capture element/,
+    )
   })
 
   it('CSV resolve returns a download handle with the filename + revoke fn (single series)', async () => {
@@ -59,7 +61,7 @@ describe('createBarDownloadConfig', () => {
       getData: () => sample,
     })
     const csv = items.find((i) => i.id === 'csv')!
-    const handle = await csv.resolve()
+    const handle = await csv.resolve({ id: null })
     expect(handle.url).toBe('blob:mock')
     expect(handle.filename).toBe('sales.csv')
     expect(typeof handle.revoke).toBe('function')
@@ -84,7 +86,7 @@ describe('createBarDownloadConfig', () => {
       filename: 'multi',
       getData: () => multi,
     })
-    await items.find((i) => i.id === 'csv')!.resolve()
+    await items.find((i) => i.id === 'csv')!.resolve({ id: null })
     expect(csvText).toBe('name,value\na,1\nb,2\n\nname,value\nc,3')
     vi.unstubAllGlobals()
   })