@carto/ps-react-ui 5.0.0 → 5.2.0

package/src/widgets-v2/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,
@@ -13,13 +14,30 @@ import {
   DialogTitle,
   IconButton,
   Typography,
+  useMediaQuery,
+  useTheme,
   type SvgIconProps,
+  type CSSObject,
+  type SxProps,
+  type Theme,
 } from '@mui/material'
 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'
@@ -33,13 +51,39 @@ 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
+  /**
+   * Buttons rendered in the modal header, to the left of the close icon —
+   * the fullscreen counterpart of `<Widget.Actions>`, which lives in the
+   * wrapper's summary row and is covered by the dialog. Pass the same
+   * elements you compose there (typically `<Widget.Download>`); the
+   * fullscreen trigger is intentionally not among them, since the close
+   * icon already exits.
+   */
+  actions?: ReactNode
+  /**
+   * Per-widget override merged over the default `90vw x 90vh` dialog paper.
+   * Charts want the default (their canvas grows to fill it); content-sized
+   * widgets (Range, Markdown) pass their own width / `height: 'auto'` so the
+   * modal doesn't leave a large empty box around them.
+   *
+   * Shallow-merged over the default, same as `Widget.Actions`' `sx`: pass a
+   * plain style object, not the array or theme-callback form.
+   */
+  paperSx?: SxProps<Theme>
   labels?: Partial<FullScreenLabels>
   closeIcon?: ComponentType<SvgIconProps>
   iconProps?: SvgIconProps
@@ -89,19 +133,48 @@ 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,
   title,
+  actions,
+  paperSx,
   labels,
   closeIcon: CloseSvg = CloseIcon,
   iconProps,
@@ -112,102 +185,215 @@ function FullScreenSlot({
     id,
     (s) => s.isFullScreen ?? false,
   )
-  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
-  })
-
+  // Below `sm` the dialog goes edge-to-edge (MUI's own answer for phones).
+  // A paper sized as a fraction of a 390px viewport is narrower than the
+  // card the widget sits in, and forcing it wider just eats the dialog's
+  // margins — on a screen that small, fullscreen should mean fullscreen.
+  const theme = useTheme()
+  const fullBleed = useMediaQuery(theme.breakpoints.down('sm'))
   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}
-        PaperProps={{ sx: styles.dialogPaper }}
+        fullScreen={fullBleed}
+        // Edge-to-edge owns the sizing; the floor and cap would fight it.
+        PaperProps={fullBleed ? undefined : { sx: resolvePaperSx(paperSx) }}
         aria-labelledby={titleId}
-        // Sits above the Toolbox overflow Paper (zIndex.tooltip = 1500),
-        // so opening fullscreen never leaves a stray popover floating on top.
-        sx={{ zIndex: (theme) => theme.zIndex.tooltip + 1 }}
+        // Deliberately no z-index override. Raising the dialog above the
+        // tooltip layer also raises it above everything its own body opens —
+        // MUI portals menus and tooltips to `document.body`, so a Download
+        // menu (`zIndex.modal`, 1300) or a Tooltip (1500) ends up painted
+        // under a dialog at 1501 and its items can't be clicked. At the
+        // default modal layer the menu portals after the dialog and wins on
+        // DOM order, and the tooltip wins on z-index.
+        //
+        // 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>
-          <Tooltip title={_labels.close}>
-            <IconButton
-              size='medium'
-              aria-label={_labels.close}
-              onClick={handleClose}
+        <DialogStore sourceId={id}>
+          <DialogTitle id={titleId} component='div' sx={styles.dialogTitle}>
+            <Typography
+              variant='subtitle1'
+              component='span'
+              sx={styles.titleText}
             >
-              <CloseSvg fontSize='small' {...iconProps} />
-            </IconButton>
-          </Tooltip>
-        </DialogTitle>
-        <DialogContent ref={setDialogEl} sx={styles.dialogContent} />
+              {title}
+            </Typography>
+            <Box sx={styles.dialogActions}>
+              {actions}
+              <Tooltip title={_labels.close}>
+                <IconButton
+                  size='medium'
+                  aria-label={_labels.close}
+                  onClick={handleClose}
+                >
+                  <CloseSvg fontSize='small' {...iconProps} />
+                </IconButton>
+              </Tooltip>
+            </Box>
+          </DialogTitle>
+          <DialogContent sx={styles.dialogContent}>
+            {render(true)}
+          </DialogContent>
+        </DialogStore>
       </Dialog>
     </>
   )
 }
 
 /**
- * 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.
+ * 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)
+  const live = useWidgetShallow(sourceId, (s) => ({
+    rawData: 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, {
+      data: live.rawData,
+      isLoading: live.isLoading,
+      isFetching: live.isFetching,
+      error: live.error,
+      formatter: live.formatter,
+      labelFormatter: live.labelFormatter,
+    })
+    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}
+      data={live.rawData}
+      isLoading={live.isLoading}
+      isFetching={live.isFetching}
+      error={live.error}
+      formatter={live.formatter}
+      labelFormatter={live.labelFormatter}
+    >
+      {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.
+ *
+ * An explicit `width` / `height` also clears the default's floor on that
+ * axis: `minWidth: 70vw` is 1008px on a 1440px screen, so a caller asking
+ * for `width: 960` would silently get 1008 and the escape hatch wouldn't
+ * escape. The viewport cap stays — a size larger than the screen helps
+ * nobody — and a caller who wants their own floor or cap can still set
+ * `minWidth` / `maxWidth` directly, since their values are spread last.
  */
-function refreshInlineHeightLock(el: HTMLElement): void {
-  el.style.minHeight = ''
-  const h = el.getBoundingClientRect().height
-  if (h > 0) el.style.minHeight = `${h}px`
+function resolvePaperSx(paperSx: SxProps<Theme> | undefined): SxProps<Theme> {
+  // Plain-object form only, as the prop documents — the array and
+  // theme-callback forms of `SxProps` wouldn't survive a shallow merge.
+  const plain = (paperSx ?? {}) as CSSObject
+  return {
+    ...styles.dialogPaper,
+    ...(plain.width !== undefined && { minWidth: 0 }),
+    ...(plain.height !== undefined && { minHeight: 0 }),
+    ...plain,
+  }
 }
 
 /**
@@ -218,8 +404,8 @@ function refreshInlineHeightLock(el: HTMLElement): void {
  *   <Widget.FullScreen.Trigger />
  * </Widget.Actions>
  * <Widget.Content>
- *   <Widget.FullScreen.Slot title={title}>
- *     {(isFullScreen) => <Body visibleCount={isFullScreen ? undefined : 2} />}
+ *   <Widget.FullScreen.Slot title={title} actions={<Widget.Download items={items} />}>
+ *     <Body />
  *   </Widget.FullScreen.Slot>
  * </Widget.Content>
  * ```

package/src/widgets-v2/actions/fullscreen/style.ts

@@ -27,11 +27,25 @@ export const styles = {
   triggerActive: {
     background: (theme: Theme) => theme.palette.primary.relatedLight,
   },
+  // Sized by its content, between a floor and the viewport. The floor is
+  // what makes this safe: every widget body in the library is `width: 100%`
+  // (they're built to fill their card) and an ECharts canvas has no
+  // intrinsic size at all, so asking the content how big it wants to be
+  // gets no answer — without a floor the modal collapses to a few hundred
+  // pixels. Content bigger than the floor grows, up to the viewport cap.
+  //
+  // Floor and cap are both viewport units so the modal scales with the
+  // device: a px floor would be wider than the screen on a phone.
+  //
+  // Only applies from `sm` up — below that the dialog goes edge-to-edge and
+  // sizes itself (see `fullScreen` in fullscreen.tsx).
   dialogPaper: {
-    width: '90vw',
-    height: '90vh',
-    maxWidth: 'none',
-    maxHeight: 'none',
+    width: 'auto',
+    height: 'auto',
+    minWidth: '70vw',
+    minHeight: '70vh',
+    maxWidth: '90vw',
+    maxHeight: '90vh',
   },
   dialogTitle: {
     display: 'flex',
@@ -42,6 +56,15 @@ export const styles = {
     pr: 3,
     pb: 2,
   },
+  // Header buttons + close icon. Mirrors `Widget.Actions`' row so the modal
+  // header reads like the wrapper's summary row — minus the hover-fade,
+  // which makes no sense once the widget owns the whole screen.
+  dialogActions: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 0.5,
+    flexShrink: 0,
+  },
   titleText: {
     minWidth: 0,
     overflow: 'hidden',
@@ -55,5 +78,9 @@ export const styles = {
     py: 3,
     px: 2.5,
     overflow: 'auto',
+    // Lets the flex children grow into the dialog's height (and shrink below
+    // their content size) instead of being floored by it — without this the
+    // chart can't use the space the modal gives it.
+    minHeight: 0,
   },
 } satisfies Record<string, SxProps<Theme>>

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

@@ -62,6 +62,7 @@ export {
   DOWNLOAD_ITEM_IDS,
   type DownloadProps,
   type DownloadItem,
+  type DownloadContext,
   type DownloadItemId,
   type DownloadHandle,
   type DownloadDOMToPNGOptions,

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

@@ -40,6 +40,20 @@ export function Searcher({
         string | undefined) ?? '',
   )
 
+  // 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 stored =
+    (useWidget(id, (s) => s.transformStates.searcher?.searchText) as
+      string | undefined) ?? ''
+  const [prevStored, setPrevStored] = useState(stored)
+  if (stored !== prevStored) {
+    setPrevStored(stored)
+    if (!focused) setLocal(stored)
+  }
+
   const debouncedWrite = useMemo(
     () =>
       debounce(
@@ -78,6 +92,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-v2/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()
   })

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

@@ -1,20 +1,21 @@
 import {
   buildCsvDownloadItem,
   buildPngDownloadItem,
+  type DownloadContext,
   type DownloadItem,
 } from '../actions/download'
 import type { BarWidgetData } from './types'
 
 export interface BarDownloadConfigArgs {
   filename: string
-  getData: () => BarWidgetData
+  getData: (ctx: DownloadContext) => BarWidgetData
   /**
    * Optional getter for the widget's capture element (registered by
    * `Widget.State` on its success path). When provided, a PNG item is
    * prepended to the returned list. Wire it to
    * `() => getCaptureEl(id)`.
    */
-  getCaptureEl?: () => HTMLElement | null
+  getCaptureEl?: (ctx: DownloadContext) => HTMLElement | null
   /** PNG `pixelRatio` (default 2). */
   pngPixelRatio?: number
   /** PNG `backgroundColor` (default transparent). */
@@ -44,8 +45,8 @@ export function createBarDownloadConfig(
   items.push(
     buildCsvDownloadItem({
       filename: args.filename,
-      getRows: () => {
-        const data = args.getData()
+      getRows: (ctx) => {
+        const data = args.getData(ctx)
         const rows: unknown[][] = []
         for (const [i, series] of data.entries()) {
           if (i > 0) rows.push([])