@carto/ps-react-ui 5.0.0-widgets.8 → 5.0.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 { 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
+  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,95 @@
+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'

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