@carto/ps-react-ui 5.0.0 → 6.0.0

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

@@ -1,98 +1,303 @@
 import {
+  useCallback,
+  useLayoutEffect,
+  useState,
+  type ComponentType,
+  type ReactNode,
+} from 'react'
+import { createPortal } from 'react-dom'
+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'
+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 { 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
+}
 
-const EMPTY_DIALOG_CONTENT_PROPS: NonNullable<
-  FullScreenProps['DialogContentProps']
-> = {}
+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.
+   */
+  children: (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>
+  )
+}
+
+/**
+ * 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.
+ */
+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 [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.
+  useLayoutEffect(() => {
+    if (!portalDiv || !inlineEl) return
+    const host = open ? dialogEl : inlineEl
+    if (host && portalDiv.parentNode !== host) {
+      host.appendChild(portalDiv)
+    }
+    if (!open) refreshInlineHeightLock(inlineEl)
+  }, [open, inlineEl, dialogEl, portalDiv])
+
+  const titleId = `widget-fullscreen-title-${id}`
+  const rendered = children(open)
+
+  return (
+    <>
+      <Box ref={setInlineEl} sx={styles.inlineSlot} />
+      {portalDiv ? createPortal(rendered, portalDiv) : null}
       <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.
+        //
+        // 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.
       >
-        <DialogTitle
-          id={`fullscreen-dialog-title-${id}`}
-          sx={styles.title.container}
-        >
-          <Typography variant='subtitle1' component='span'>
+        <DialogTitle id={titleId} component='div' sx={styles.dialogTitle}>
+          <Typography
+            variant='subtitle1'
+            component='span'
+            sx={styles.titleText}
+          >
             {title}
           </Typography>
-          <IconButton
-            onClick={() => updateFullScreenConfig({ isFullScreen: false })}
-          >
-            <Close />
-          </IconButton>
+          <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.content,
-            ...sx,
-          }}
-          {...DialogContentProps}
-        >
-          {children}
-        </DialogContent>
+        <DialogContent ref={setDialogEl} sx={styles.dialogContent} />
       </Dialog>
     </>
   )
 }
+
+/**
+ * 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,
+  }
+}
+
+/**
+ * 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:
+ *
+ * ```tsx
+ * <Widget.Actions>
+ *   <Widget.FullScreen.Trigger />
+ * </Widget.Actions>
+ * <Widget.Content>
+ *   <Widget.FullScreen.Slot title={title} actions={<Widget.Download items={items} />}>
+ *     {(isFullScreen) => <Body visibleCount={isFullScreen ? undefined : 2} />}
+ *   </Widget.FullScreen.Slot>
+ * </Widget.Content>
+ * ```
+ */
+export const FullScreen = {
+  Trigger: FullScreenTrigger,
+  Slot: FullScreenSlot,
+}

package/src/{widgets-v2 → widgets}/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/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
 }

package/src/widgets/actions/index.ts

@@ -1,73 +1,95 @@
-/* Fullscreen Widget */
-export { FullScreen } from './fullscreen/fullscreen'
-export type {
-  FullScreenState,
-  FullScreenConfig,
-  FullScreenProps,
-} from './fullscreen/types'
-
-/* Download Widget */
-export { Download } from './download/download'
-export type { DownloadItem, DownloadProps } from './download/types'
-export { downloadToCSV, downloadToPNG } from './download/exports'
-
-/* Relative Data Widget */
+export {
+  Searcher,
+  SearcherToggle,
+  setSearcherText,
+  filterBySearchText,
+  DEFAULT_SEARCHER_LABELS,
+  type SearcherProps,
+  type SearcherToggleProps,
+  type SearcherLabels,
+} from './searcher'
+export {
+  StackToggle,
+  addStack,
+  DEFAULT_STACK_TOGGLE_LABELS,
+  type StackToggleProps,
+  type StackToggleLabels,
+} from './stack-toggle'
+export {
+  ShowAllToggle,
+  setShowAll,
+  SHOW_ALL_ID,
+  DEFAULT_SHOW_ALL_LABELS,
+  type ShowAllToggleProps,
+  type ShowAllLabels,
+} from './show-all'
+export {
+  ZoomToggle,
+  addZoom,
+  createAddZoom,
+  ZOOM_LAYOUT,
+  DEFAULT_ZOOM_TOGGLE_LABELS,
+  type ZoomToggleProps,
+  type ZoomToggleLabels,
+} from './zoom-toggle'
+export {
+  BrushToggle,
+  addBrush,
+  DEFAULT_BRUSH_TOGGLE_LABELS,
+  type BrushToggleProps,
+  type BrushToggleLabels,
+} from './brush-toggle'
 export {
   RelativeData,
-  RELATIVE_DATA_TOOL_ID,
-  RELATIVE_DATA_CONFIG_TOOL_ID,
-} from './relative-data/relative-data'
-export type {
-  RelativeDataProps,
-  RelativeDataState,
-} from './relative-data/types'
-
-/* Zoom Toggle Widget */
-export { ZoomToggle, ZOOM_TOGGLE_TOOL_ID } from './zoom-toggle/zoom-toggle'
-export type {
-  ZoomToggleProps,
-  ZoomState,
-  ZoomConfig,
-} from './zoom-toggle/types'
-
-/* Stack Toggle Widget */
-export { StackToggle, STACK_TOGGLE_TOOL_ID } from './stack-toggle/stack-toggle'
-export type { StackToggleProps, StackToggleState } from './stack-toggle/types'
-
-/* Searcher Toggle Widget */
-export { Searcher, SEARCHER_TOOL_ID } from './searcher/searcher'
-export { SearcherToggle } from './searcher/searcher-toggle'
-export type {
-  SearcherToggleProps,
-  SearcherProps,
-  SearcherFilterFn,
-  SearcherState,
-  SearcherStateProps,
-} from './searcher/types'
-
-/* Change Column Widget */
+  toRelativeData,
+  createPercentFormatter,
+  DEFAULT_RELATIVE_DATA_LABELS,
+  type RelativeDataProps,
+  type RelativeDataLabels,
+} from './relative-data'
 export {
-  ChangeColumn,
-  CHANGE_COLUMN_TOOL_ID,
-} from './change-column/change-column'
-export type { ChangeColumnProps } from './change-column/types'
-
-/* Lock Selection Widget */
+  Download,
+  downloadToCSV,
+  downloadDOMToPNG,
+  toCsvString,
+  triggerLinkDownload,
+  buildPngDownloadItem,
+  buildCsvDownloadItem,
+  CSVIcon,
+  PNGIcon,
+  MarkdownIcon,
+  DEFAULT_DOWNLOAD_LABELS,
+  DOWNLOAD_ITEM_IDS,
+  type DownloadProps,
+  type DownloadItem,
+  type DownloadItemId,
+  type DownloadHandle,
+  type DownloadDOMToPNGOptions,
+  type BuildPngDownloadItemArgs,
+  type BuildCsvDownloadItemArgs,
+  type DownloadLabels,
+} from './download'
+export {
+  FullScreen,
+  DEFAULT_FULLSCREEN_LABELS,
+  type FullScreenTriggerProps,
+  type FullScreenSlotProps,
+  type FullScreenLabels,
+  type FullScreenWidgetState,
+} from './fullscreen'
 export {
   LockSelection,
-  LOCK_SELECTION_TOOL_ID,
-} from './lock-selection/lock-selection'
-export type {
-  LockSelectionProps,
-  LockSelectionState,
-  LockSelectionStateProps,
-} from './lock-selection/types'
-
-/* Brush Toggle Widget */
-export { BrushToggle, BRUSH_TOGGLE_TOOL_ID } from './brush-toggle/brush-toggle'
-export type {
-  BrushToggleProps,
-  BrushState,
-  BrushConfig,
-  BrushSelectedItems,
-} from './brush-toggle/types'
+  filterByLockedItems,
+  DEFAULT_LOCK_SELECTION_LABELS,
+  type LockSelectionProps,
+  type LockSelectionKey,
+  type LockSelectionLabels,
+} from './lock-selection'
+export {
+  ChangeColumn,
+  DEFAULT_CHANGE_COLUMN_LABELS,
+  type ChangeColumnProps,
+  type ChangeColumnItem,
+  type ChangeColumnLabels,
+  type ChangeColumnWidgetState,
+} from './change-column'