@carto/ps-react-ui 5.3.0 → 6.1.0

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

@@ -1,98 +1,405 @@
+import type { ECharts } from 'echarts'
 import {
+  useCallback,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ComponentType,
+  type ReactNode,
+} from 'react'
+import {
+  Box,
   Dialog,
   DialogContent,
   DialogTitle,
   IconButton,
   Typography,
+  useMediaQuery,
+  useTheme,
+  type SvgIconProps,
+  type CSSObject,
+  type SxProps,
+  type Theme,
 } from '@mui/material'
-import { widgetStoreActions } from '../../stores/widget-store'
-import { useWidgetSelector } from '../../stores/use-widget-selector'
-import { Close, FullscreenOutlined } from '@mui/icons-material'
-import type {
-  FullScreenConfig,
-  FullScreenProps,
-  FullScreenState,
-} from './types'
-import { styles } from './styles'
-
-const EMPTY_DIALOG_CONTENT_PROPS: NonNullable<
-  FullScreenProps['DialogContentProps']
-> = {}
+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 { 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'
+
+export interface FullScreenTriggerProps {
+  labels?: Partial<FullScreenLabels>
+  enterIcon?: ComponentType<SvgIconProps>
+  exitIcon?: ComponentType<SvgIconProps>
+  iconProps?: SvgIconProps
+}
+
+export interface FullScreenSlotProps {
+  /**
+   * 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: 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
+}
 
 /**
- * Displays widget content in a fullscreen modal dialog.
- *
- * Manages fullscreen state via the widget store and renders a MUI Dialog
- * with the widget title and a close button.
- *
- * @example
- * ```tsx
- * <FullScreen id="my-widget" labels={{ ariaLabel: 'Expand chart' }}>
- *   <ChartContent id="my-widget" />
- * </FullScreen>
- * ```
+ * Toggle button placed inside `<Widget.Actions>`. Reads / writes
+ * {@link FullScreenWidgetState.isFullScreen} on the per-widget store. The
+ * matching modal is rendered by {@link FullScreenSlot} (typically inside
+ * `<Widget.Content>`).
  */
-export function FullScreen({
-  id,
+function FullScreenTrigger({
   labels,
-  children,
-  Icon,
-  IconButtonProps,
-  DialogContentProps: {
-    sx,
-    ...DialogContentProps
-  } = EMPTY_DIALOG_CONTENT_PROPS,
-  DialogProps,
-}: FullScreenProps) {
-  const { isFullScreen, title } = useWidgetSelector(id, (w) => ({
-    isFullScreen: (w as FullScreenState | undefined)?.isFullScreen,
-    title: (w as FullScreenState | undefined)?.title,
-  }))
-  const updateFullScreenConfig = (updates: Partial<FullScreenConfig>) => {
-    widgetStoreActions.setWidget<FullScreenState>(id, {
-      isFullScreen: updates.isFullScreen,
-    })
-  }
+  enterIcon: EnterIcon = FullscreenIcon,
+  exitIcon: ExitIcon = FullscreenExitIcon,
+  iconProps,
+}: FullScreenTriggerProps) {
+  const id = useWidgetId()
+  const _labels = { ...DEFAULT_FULLSCREEN_LABELS, ...labels }
+  const open = useWidget<boolean, FullScreenWidgetState>(
+    id,
+    (s) => s.isFullScreen ?? false,
+  )
+
+  const handleToggle = useCallback(() => {
+    getWidgetStore(id).setState({
+      isFullScreen: !open,
+    } as Partial<FullScreenWidgetState>)
+  }, [id, open])
+
+  const triggerLabel = open ? _labels.close : _labels.open
+  const TriggerIcon = open ? ExitIcon : EnterIcon
 
   return (
-    <>
+    <Tooltip title={triggerLabel}>
       <IconButton
-        {...IconButtonProps}
-        onClick={() => updateFullScreenConfig({ isFullScreen: true })}
+        size='small'
+        aria-label={triggerLabel}
+        aria-pressed={open}
+        onClick={handleToggle}
+        className={open ? 'active' : undefined}
+        sx={{ ...styles.trigger, ...(open && styles.triggerActive) }}
       >
-        {Icon ?? <FullscreenOutlined />}
+        <TriggerIcon fontSize='small' {...iconProps} />
       </IconButton>
+    </Tooltip>
+  )
+}
+
+/** 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. 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,
+}: FullScreenSlotProps) {
+  const id = useWidgetId()
+  const _labels = { ...DEFAULT_FULLSCREEN_LABELS, ...labels }
+  const open = useWidget<boolean, FullScreenWidgetState>(
+    id,
+    (s) => s.isFullScreen ?? false,
+  )
+  // 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])
+
+  // 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(() => {
+    const dialogId = fullScreenStoreId(id)
+    if (wasOpen.current && !open && hasWidgetStore(dialogId)) {
+      getWidgetStore(id).setState(
+        copiedState(getWidgetStore(dialogId).getState()),
+      )
+    }
+    wasOpen.current = open
+  }, [id, open])
+
+  const titleId = `widget-fullscreen-title-${id}`
+  const render = (inDialog: boolean) =>
+    typeof children === 'function' ? children(inDialog) : children
+
+  return (
+    <>
+      <Box sx={styles.inlineSlot}>{render(false)}</Box>
       <Dialog
-        maxWidth={false}
-        open={!!isFullScreen}
-        keepMounted
-        aria-labelledby={labels?.ariaLabel ?? `fullscreen-dialog-title-${id}`}
-        {...DialogProps}
-        onClose={() => updateFullScreenConfig({ isFullScreen: false })}
+        open={open}
+        onClose={handleClose}
+        fullScreen={fullBleed}
+        // Edge-to-edge owns the sizing; the floor and cap would fight it.
+        slotProps={
+          fullBleed ? undefined : { paper: { sx: resolvePaperSx(paperSx) } }
+        }
+        aria-labelledby={titleId}
+        // 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={`fullscreen-dialog-title-${id}`}
-          sx={styles.title.container}
-        >
-          <Typography variant='subtitle1' component='span'>
-            {title}
-          </Typography>
-          <IconButton
-            onClick={() => updateFullScreenConfig({ isFullScreen: false })}
-          >
-            <Close />
-          </IconButton>
-        </DialogTitle>
-        <DialogContent
-          sx={{
-            ...styles.content,
-            ...sx,
-          }}
-          {...DialogContentProps}
-        >
-          {children}
-        </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.
+ *
+ * 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 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,
+  }
+}
+
+/**
+ * Namespace export. Consumers compose with:
+ *
+ * ```tsx
+ * <Widget.Actions>
+ *   <Widget.FullScreen.Trigger />
+ * </Widget.Actions>
+ * <Widget.Content>
+ *   <Widget.FullScreen.Slot title={title} actions={<Widget.Download items={items} />}>
+ *     <Body />
+ *   </Widget.FullScreen.Slot>
+ * </Widget.Content>
+ * ```
+ */
+export const FullScreen = {
+  Trigger: FullScreenTrigger,
+  Slot: FullScreenSlot,
+}

package/src/widgets/actions/fullscreen/types.ts

@@ -1,32 +1,15 @@
-import type {
-  DialogContentProps,
-  IconButtonProps,
-  DialogProps,
-} from '@mui/material'
-import type { ReactNode } from 'react'
-import type { BaseWidgetState } from '../../../widgets/stores/types'
-
-export type FullScreenState<T = unknown> = BaseWidgetState<
-  T &
-    FullScreenConfigProps & {
-      title: string
-    }
->
-
-export interface FullScreenConfig {
-  isFullScreen?: boolean
-}
-
-export type FullScreenConfigProps = FullScreenConfig
-
-export interface FullScreenProps {
-  id: FullScreenState['id']
-  labels?: {
-    ariaLabel?: string
-  }
-  children: ReactNode
-  DialogContentProps?: DialogContentProps
-  DialogProps?: DialogProps
-  IconButtonProps?: IconButtonProps
-  Icon?: ReactNode
+import type { WidgetState } from '../../stores'
+
+/**
+ * State extension owned by FullScreen. The base `WidgetState` deliberately
+ * stays free of widget-specific UI flags (R12 from the round-5 amendment);
+ * actions that need persistent UI state declare it here and read it via the
+ * generic `useWidget<T, S>(id, sel)` form.
+ *
+ * `isFullScreen` survives `keepAlive` remounts because it lives on the same
+ * store the rest of `WidgetState` does — a kept-alive widget that was
+ * fullscreen reopens fullscreen automatically.
+ */
+export interface FullScreenWidgetState extends WidgetState {
+  isFullScreen: boolean
 }