@carto/ps-react-ui 4.7.1 → 4.8.0

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',
+}

package/src/widgets-v2/actions/lock-selection/lock-selection.test.tsx

@@ -0,0 +1,187 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { Provider } from '../../provider/widget-provider'
+import { clearAllWidgetStores, getWidgetStore } from '../../stores'
+import { LockSelection } from './lock-selection'
+import { filterByLockedItems } from './transforms'
+
+beforeEach(() => clearAllWidgetStores())
+afterEach(() => clearAllWidgetStores())
+
+const DATA = [
+  [
+    { name: 'A', value: 10 },
+    { name: 'B', value: 20 },
+    { name: 'C', value: 30 },
+  ],
+]
+
+describe('<LockSelection>', () => {
+  it('disables the trigger when nothing is selected and nothing is locked', () => {
+    render(
+      <Provider id='ls1' data={DATA}>
+        <LockSelection
+          selection={[]}
+          lockedItems={[]}
+          onLockChange={() => undefined}
+          labels={{ disabled: 'Pick rows' }}
+        />
+      </Provider>,
+    )
+    const btn = screen.getByRole('button', { name: 'Pick rows' })
+    expect(btn.getAttribute('disabled')).not.toBeNull()
+  })
+
+  it('shows the lock label when selection is non-empty and not locked', () => {
+    render(
+      <Provider id='ls2' data={DATA}>
+        <LockSelection
+          selection={['A']}
+          lockedItems={[]}
+          onLockChange={() => undefined}
+          labels={{ lock: 'Lock these' }}
+        />
+      </Provider>,
+    )
+    const btn = screen.getByRole('button', { name: 'Lock these' })
+    expect(btn.getAttribute('aria-pressed')).toBe('false')
+    expect(btn.getAttribute('disabled')).toBeNull()
+  })
+
+  it('shows the unlock label when locked and aria-pressed=true', () => {
+    render(
+      <Provider id='ls3' data={DATA}>
+        <LockSelection
+          selection={['A']}
+          lockedItems={['A']}
+          onLockChange={() => undefined}
+          labels={{ unlock: 'Release' }}
+        />
+      </Provider>,
+    )
+    const btn = screen.getByRole('button', { name: 'Release' })
+    expect(btn.getAttribute('aria-pressed')).toBe('true')
+  })
+
+  it('snapshots selection on lock — onLockChange called with current selection', () => {
+    const onLockChange = vi.fn()
+    render(
+      <Provider id='ls4' data={DATA}>
+        <LockSelection
+          selection={['A', 'B']}
+          lockedItems={[]}
+          onLockChange={onLockChange}
+          labels={{ lock: 'Lock' }}
+        />
+      </Provider>,
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'Lock' }))
+    expect(onLockChange).toHaveBeenCalledTimes(1)
+    expect(onLockChange).toHaveBeenCalledWith(['A', 'B'])
+  })
+
+  it('clears the lock — onLockChange called with empty array', () => {
+    const onLockChange = vi.fn()
+    render(
+      <Provider id='ls5' data={DATA}>
+        <LockSelection
+          selection={['A']}
+          lockedItems={['A', 'B']}
+          onLockChange={onLockChange}
+          labels={{ unlock: 'Unlock' }}
+        />
+      </Provider>,
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'Unlock' }))
+    expect(onLockChange).toHaveBeenCalledWith([])
+  })
+
+  it('registers a data transform that filters when locked, restores when unlocked', () => {
+    const { rerender } = render(
+      <Provider id='ls6' data={DATA}>
+        <LockSelection
+          selection={['A']}
+          lockedItems={['A']}
+          onLockChange={() => undefined}
+        />
+      </Provider>,
+    )
+    const locked = getWidgetStore('ls6').getState().data as unknown[][]
+    expect(locked).toEqual([[{ name: 'A', value: 10 }]])
+
+    rerender(
+      <Provider id='ls6' data={DATA}>
+        <LockSelection
+          selection={['A']}
+          lockedItems={[]}
+          onLockChange={() => undefined}
+        />
+      </Provider>,
+    )
+    const unlocked = getWidgetStore('ls6').getState().data as unknown[][]
+    // With no lockedItems and the transform disabled, the pipeline returns
+    // raw data. All three rows should be present.
+    expect(unlocked.flat().length).toBe(3)
+  })
+
+  it('lets the destination feed a different lockedItems set later', () => {
+    const { rerender } = render(
+      <Provider id='ls7' data={DATA}>
+        <LockSelection
+          selection={['A']}
+          lockedItems={['A']}
+          onLockChange={() => undefined}
+        />
+      </Provider>,
+    )
+    expect(
+      (getWidgetStore('ls7').getState().data as unknown[][]).flat(),
+    ).toEqual([{ name: 'A', value: 10 }])
+
+    rerender(
+      <Provider id='ls7' data={DATA}>
+        <LockSelection
+          selection={['A', 'B', 'C']}
+          lockedItems={['B', 'C']}
+          onLockChange={() => undefined}
+        />
+      </Provider>,
+    )
+    expect(
+      (getWidgetStore('ls7').getState().data as unknown[][]).flat(),
+    ).toEqual([
+      { name: 'B', value: 20 },
+      { name: 'C', value: 30 },
+    ])
+  })
+})
+
+describe('filterByLockedItems', () => {
+  it('returns input unchanged when locked set is empty', () => {
+    expect(filterByLockedItems(DATA, [])).toBe(DATA)
+  })
+
+  it('keeps only items whose name is in the locked set, preserving series shape', () => {
+    const out = filterByLockedItems(DATA, ['A', 'C']) as unknown[][]
+    expect(out).toEqual([
+      [
+        { name: 'A', value: 10 },
+        { name: 'C', value: 30 },
+      ],
+    ])
+  })
+
+  it('handles numeric names', () => {
+    const data = [
+      [
+        { name: 1, value: 10 },
+        { name: 2, value: 20 },
+      ],
+    ]
+    expect(filterByLockedItems(data, [2])).toEqual([[{ name: 2, value: 20 }]])
+  })
+
+  it('returns input unchanged when input is not array-shaped', () => {
+    expect(filterByLockedItems('nope', ['A'])).toBe('nope')
+  })
+})