@carto/ps-react-ui 4.7.0 → 4.8.0

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

@@ -0,0 +1,150 @@
+import { useEffect, useRef } from 'react'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { Provider } from '../../provider/widget-provider'
+import { clearAllWidgetStores, getWidgetStore } from '../../stores'
+import { FullScreen } from './fullscreen'
+import type { FullScreenWidgetState } from './types'
+
+beforeEach(() => clearAllWidgetStores())
+afterEach(() => clearAllWidgetStores())
+
+describe('<FullScreen.Trigger> — store toggle', () => {
+  it('does not surface isFullScreen on the base WidgetState until the trigger fires', () => {
+    render(
+      <Provider id='fs1' data={[]}>
+        <FullScreen.Trigger />
+      </Provider>,
+    )
+    const state = getWidgetStore('fs1').getState()
+    expect((state as FullScreenWidgetState).isFullScreen).toBeUndefined()
+  })
+
+  it('toggles state on click and swaps the trigger label', () => {
+    render(
+      <Provider id='fs2' data={[]}>
+        <FullScreen.Trigger labels={{ open: 'Expand', close: 'Shrink' }} />
+      </Provider>,
+    )
+    fireEvent.click(screen.getByLabelText('Expand'))
+    expect(screen.getByLabelText('Shrink')).toBeTruthy()
+    expect(
+      (getWidgetStore('fs2').getState() as FullScreenWidgetState).isFullScreen,
+    ).toBe(true)
+    fireEvent.click(screen.getByLabelText('Shrink'))
+    expect(screen.getByLabelText('Expand')).toBeTruthy()
+    expect(
+      (getWidgetStore('fs2').getState() as FullScreenWidgetState).isFullScreen,
+    ).toBe(false)
+  })
+
+  it('keepAlive remount restores isFullScreen', () => {
+    const { unmount } = render(
+      <Provider id='fs3' data={[]} keepAlive>
+        <FullScreen.Trigger labels={{ open: 'Maximise' }} />
+      </Provider>,
+    )
+    fireEvent.click(screen.getByLabelText('Maximise'))
+    expect(
+      (getWidgetStore('fs3').getState() as FullScreenWidgetState).isFullScreen,
+    ).toBe(true)
+    unmount()
+    render(
+      <Provider id='fs3' data={[]} keepAlive>
+        <FullScreen.Trigger labels={{ open: 'Maximise' }} />
+      </Provider>,
+    )
+    expect(
+      (getWidgetStore('fs3').getState() as FullScreenWidgetState).isFullScreen,
+    ).toBe(true)
+  })
+})
+
+describe('<FullScreen.Slot> — render-prop body + portal', () => {
+  it('passes the live isFullScreen flag to the render prop', () => {
+    let received: boolean | undefined
+    render(
+      <Provider id='fs-rp' data={[]}>
+        <FullScreen.Trigger />
+        <FullScreen.Slot>
+          {(isFullScreen) => {
+            received = isFullScreen
+            return <span data-testid='body'>body</span>
+          }}
+        </FullScreen.Slot>
+      </Provider>,
+    )
+    expect(received).toBe(false)
+    fireEvent.click(screen.getByLabelText('Open in full screen'))
+    expect(received).toBe(true)
+  })
+
+  it('renders the title above the body when open', async () => {
+    render(
+      <Provider id='fs-title' data={[]}>
+        <FullScreen.Trigger />
+        <FullScreen.Slot title='Sales by region'>
+          {() => <div>body</div>}
+        </FullScreen.Slot>
+      </Provider>,
+    )
+    fireEvent.click(screen.getByLabelText('Open in full screen'))
+    expect(await screen.findByText('Sales by region')).toBeTruthy()
+  })
+
+  it('still renders the close button when no title is given', async () => {
+    render(
+      <Provider id='fs-no-title' data={[]}>
+        <FullScreen.Trigger />
+        <FullScreen.Slot>{() => <div>body</div>}</FullScreen.Slot>
+      </Provider>,
+    )
+    fireEvent.click(screen.getByLabelText('Open in full screen'))
+    const closes = await screen.findAllByLabelText('Exit full screen')
+    expect(closes.length).toBeGreaterThan(0)
+  })
+
+  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
+    function CountingChild() {
+      const counted = useRef(false)
+      useEffect(() => {
+        if (counted.current) return
+        counted.current = true
+        mountCount += 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={[]}>
+        <FullScreen.Trigger labels={{ open: 'OpenT', close: 'CloseT' }} />
+        <FullScreen.Slot title='Z'>{() => <CountingChild />}</FullScreen.Slot>
+      </Provider>,
+    )
+    expect(mountCount).toBe(1)
+    fireEvent.click(screen.getByLabelText('OpenT'))
+    expect(mountCount).toBe(1)
+    fireEvent.click(screen.getByLabelText('CloseT'))
+    expect(mountCount).toBe(1)
+    fireEvent.click(screen.getByLabelText('OpenT'))
+    expect(mountCount).toBe(1)
+  })
+})

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

@@ -0,0 +1,230 @@
+import {
+  useCallback,
+  useLayoutEffect,
+  useState,
+  type ComponentType,
+  type ReactNode,
+} from 'react'
+import { createPortal } from 'react-dom'
+import {
+  Box,
+  Dialog,
+  DialogContent,
+  DialogTitle,
+  IconButton,
+  Typography,
+  type SvgIconProps,
+} from '@mui/material'
+import FullscreenIcon from '@mui/icons-material/Fullscreen'
+import FullscreenExitIcon from '@mui/icons-material/FullscreenExit'
+import CloseIcon from '@mui/icons-material/Close'
+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
+}
+
+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
+  labels?: Partial<FullScreenLabels>
+  closeIcon?: ComponentType<SvgIconProps>
+  iconProps?: SvgIconProps
+}
+
+/**
+ * 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>`).
+ */
+function FullScreenTrigger({
+  labels,
+  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
+        size='small'
+        aria-label={triggerLabel}
+        aria-pressed={open}
+        onClick={handleToggle}
+        className={open ? 'active' : undefined}
+        sx={{ ...styles.trigger, ...(open && styles.triggerActive) }}
+      >
+        <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,
+  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,
+  )
+  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
+        open={open}
+        onClose={handleClose}
+        PaperProps={{ sx: styles.dialogPaper }}
+        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 }}
+      >
+        <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}
+            >
+              <CloseSvg fontSize='small' {...iconProps} />
+            </IconButton>
+          </Tooltip>
+        </DialogTitle>
+        <DialogContent ref={setDialogEl} sx={styles.dialogContent} />
+      </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.
+ */
+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}>
+ *     {(isFullScreen) => <Body visibleCount={isFullScreen ? undefined : 2} />}
+ *   </Widget.FullScreen.Slot>
+ * </Widget.Content>
+ * ```
+ */
+export const FullScreen = {
+  Trigger: FullScreenTrigger,
+  Slot: FullScreenSlot,
+}

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

@@ -0,0 +1,7 @@
+export {
+  FullScreen,
+  type FullScreenTriggerProps,
+  type FullScreenSlotProps,
+} from './fullscreen'
+export { DEFAULT_FULLSCREEN_LABELS, type FullScreenLabels } from './labels'
+export type { FullScreenWidgetState } from './types'

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

@@ -0,0 +1,9 @@
+export interface FullScreenLabels {
+  open: string
+  close: string
+}
+
+export const DEFAULT_FULLSCREEN_LABELS: FullScreenLabels = {
+  open: 'Open in full screen',
+  close: 'Exit full screen',
+}

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

@@ -0,0 +1,59 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  // Inline shell where the portaled body lives when fullscreen is closed.
+  // Real flex-column box (not `display: contents`) so that:
+  //   1. when the body is moved into the modal, we can pin a `min-height`
+  //      to keep the widget card from collapsing — the inline shell is
+  //      empty for that interval, and a layout-less wrapper would make
+  //      the card squish a frame before the modal covers it (visible
+  //      blink).
+  //   2. nested `flex: 1` (e.g. Widget.State's CaptureBox) still grows —
+  //      this shell preserves the column-flex inheritance it would have
+  //      had directly under `Widget.Content`.
+  // `gap: 1` mirrors `Widget.Content`'s gap so the body's siblings
+  // (Subheader / capture box / note) keep their spacing.
+  inlineSlot: {
+    display: 'flex',
+    flexDirection: 'column',
+    flex: 1,
+    minHeight: 0,
+    gap: 1,
+  },
+  trigger: {
+    p: 0.5,
+    '& .MuiSvgIcon-root': { fontSize: 20 },
+  },
+  triggerActive: {
+    background: (theme: Theme) => theme.palette.primary.relatedLight,
+  },
+  dialogPaper: {
+    width: '90vw',
+    height: '90vh',
+    maxWidth: 'none',
+    maxHeight: 'none',
+  },
+  dialogTitle: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    gap: 1,
+    py: 3,
+    pr: 3,
+    pb: 2,
+  },
+  titleText: {
+    minWidth: 0,
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+  },
+  dialogContent: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 1,
+    py: 3,
+    px: 2.5,
+    overflow: 'auto',
+  },
+} satisfies Record<string, SxProps<Theme>>

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

@@ -0,0 +1,15 @@
+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-v2/actions/index.ts

@@ -0,0 +1,82 @@
+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 {
+  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,
+  toRelativeData,
+  createPercentFormatter,
+  DEFAULT_RELATIVE_DATA_LABELS,
+  type RelativeDataProps,
+  type RelativeDataLabels,
+} from './relative-data'
+export {
+  Download,
+  downloadToCSV,
+  downloadDOMToPNG,
+  toCsvString,
+  triggerLinkDownload,
+  buildPngDownloadItem,
+  CSVIcon,
+  PNGIcon,
+  DEFAULT_DOWNLOAD_LABELS,
+  type DownloadProps,
+  type DownloadItem,
+  type DownloadHandle,
+  type DownloadDOMToPNGOptions,
+  type BuildPngDownloadItemArgs,
+  type DownloadLabels,
+} from './download'
+export {
+  FullScreen,
+  DEFAULT_FULLSCREEN_LABELS,
+  type FullScreenTriggerProps,
+  type FullScreenSlotProps,
+  type FullScreenLabels,
+  type FullScreenWidgetState,
+} from './fullscreen'
+export {
+  LockSelection,
+  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'

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

@@ -0,0 +1,10 @@
+export {
+  LockSelection,
+  type LockSelectionProps,
+  type LockSelectionKey,
+} from './lock-selection'
+export { filterByLockedItems } from './transforms'
+export {
+  DEFAULT_LOCK_SELECTION_LABELS,
+  type LockSelectionLabels,
+} from './labels'

package/src/widgets-v2/actions/lock-selection/labels.ts

@@ -0,0 +1,11 @@
+export interface LockSelectionLabels {
+  lock: string
+  unlock: string
+  disabled: string
+}
+
+export const DEFAULT_LOCK_SELECTION_LABELS: LockSelectionLabels = {
+  lock: 'Lock selection',
+  unlock: 'Unlock selection',
+  disabled: 'Select rows to lock',
+}