@carto/ps-react-ui 5.1.0 → 6.0.0

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

@@ -1,212 +0,0 @@
-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('renders `actions` in the modal header, next to the close button', async () => {
-    render(
-      <Provider id='fs-actions' data={[]}>
-        <FullScreen.Trigger labels={{ open: 'OpenT', close: 'CloseT' }} />
-        <FullScreen.Slot
-          title='With actions'
-          actions={<button type='button'>Download</button>}
-        >
-          {() => <div>body</div>}
-        </FullScreen.Slot>
-      </Provider>,
-    )
-    fireEvent.click(screen.getByLabelText('OpenT'))
-    const action = await screen.findByText('Download')
-    // Same header row as the close button — the wrapper's action row is
-    // covered by the dialog, so the modal has to carry them itself.
-    const header = action.closest('.MuiDialogTitle-root')
-    expect(header).toBeTruthy()
-    expect(
-      header?.querySelector('[aria-label="Exit full screen"]'),
-    ).toBeTruthy()
-  })
-
-  it('keeps `actions` mounted across a fullscreen toggle', () => {
-    render(
-      <Provider id='fs-actions-keep' data={[]}>
-        <FullScreen.Trigger labels={{ open: 'OpenT', close: 'CloseT' }} />
-        <FullScreen.Slot
-          title='Y'
-          actions={<button type='button'>Download</button>}
-        >
-          {() => <div>body</div>}
-        </FullScreen.Slot>
-      </Provider>,
-    )
-    fireEvent.click(screen.getByLabelText('OpenT'))
-    const before = screen.getByText('Download')
-    fireEvent.click(screen.getByLabelText('CloseT'))
-    fireEvent.click(screen.getByLabelText('OpenT'))
-    expect(screen.getByText('Download')).toBe(before)
-  })
-
-  it('merges `paperSx` over the default dialog paper size', () => {
-    render(
-      <Provider id='fs-paper' data={[]}>
-        <FullScreen.Trigger />
-        <FullScreen.Slot title='P' paperSx={{ width: 560, height: 'auto' }}>
-          {() => <div>body</div>}
-        </FullScreen.Slot>
-      </Provider>,
-    )
-    fireEvent.click(screen.getByLabelText('Open in full screen'))
-    const paper = document.querySelector<HTMLElement>('.MuiDialog-paper')
-    expect(paper).toBeTruthy()
-    const css = getComputedStyle(paper!)
-    expect(css.width).toBe('560px')
-    expect(css.height).toBe('auto')
-    // Untouched keys still come from the default — `90vw`, resolved against
-    // the test viewport (1024px).
-    expect(css.maxWidth).toBe('921.6px')
-  })
-
-  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

@@ -1,301 +0,0 @@
-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 { 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
-}
-
-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
-}
-
-/**
- * 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,
-  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
-        open={open}
-        onClose={handleClose}
-        fullScreen={fullBleed}
-        // Edge-to-edge owns the sizing; the floor and cap would fight it.
-        PaperProps={fullBleed ? undefined : { 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={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='medium'
-                aria-label={_labels.close}
-                onClick={handleClose}
-              >
-                <CloseSvg fontSize='small' {...iconProps} />
-              </IconButton>
-            </Tooltip>
-          </Box>
-        </DialogTitle>
-        <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/actions/fullscreen/types.ts

@@ -1,15 +0,0 @@
-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

@@ -1,95 +0,0 @@
-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,
-  toRelativeData,
-  createPercentFormatter,
-  DEFAULT_RELATIVE_DATA_LABELS,
-  type RelativeDataProps,
-  type RelativeDataLabels,
-} from './relative-data'
-export {
-  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,
-  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'