@carto/ps-react-ui 5.0.0-widgets.9 → 5.1.0

package/src/widgets-v2/actions/download/exports.ts

@@ -0,0 +1,115 @@
+/**
+ * Pure download helpers — no React, no DOM lifecycle outside the link click.
+ * Component layer in {@link ./download.tsx} orchestrates these.
+ */
+
+import html2canvas from 'html2canvas'
+
+export interface DownloadHandle {
+  url: string
+  revoke: () => void
+}
+
+// Leading characters that Excel / Sheets / Numbers interpret as a formula
+// when the CSV is opened. Prefixing the cell with a single quote forces the
+// spreadsheet app to render it as plain text. Tab and CR are included
+// because some tooling strips leading whitespace before formula evaluation.
+const CSV_FORMULA_PREFIX = /^[=+\-@\t\r]/
+
+export function toCsvString(rows: readonly (readonly unknown[])[]): string {
+  const escape = (cell: unknown): string => {
+    if (cell == null) return ''
+    let value =
+      typeof cell === 'string'
+        ? cell
+        : typeof cell === 'number' || typeof cell === 'boolean'
+          ? String(cell)
+          : JSON.stringify(cell)
+    if (CSV_FORMULA_PREFIX.test(value)) value = `'${value}`
+    if (/[",\n\r]/.test(value)) return `"${value.replace(/"/g, '""')}"`
+    return value
+  }
+  return rows.map((row) => row.map(escape).join(',')).join('\n')
+}
+
+export function downloadToCSV(
+  rows: readonly (readonly unknown[])[],
+): DownloadHandle {
+  const csv = toCsvString(rows)
+  const blob = new Blob([csv], { type: 'text/csv;charset=utf-8;' })
+  const url = URL.createObjectURL(blob)
+  return { url, revoke: () => URL.revokeObjectURL(url) }
+}
+
+// Path separators, NUL, and ASCII control chars. Filenames containing these
+// can confuse the browser download stack and historically enabled
+// Content-Disposition-style trickery.
+// eslint-disable-next-line no-control-regex
+const UNSAFE_FILENAME_CHARS = /[\\/\x00-\x1f\x7f]/g
+const MAX_FILENAME_LENGTH = 200
+
+export function sanitizeFilename(name: string): string {
+  return (
+    (name ?? '')
+      .replace(UNSAFE_FILENAME_CHARS, '_')
+      .slice(0, MAX_FILENAME_LENGTH) || 'download'
+  )
+}
+
+/**
+ * Triggers a browser download for the given URL by synthesizing an anchor,
+ * clicking it, and removing it. Pure DOM — no React. The filename is run
+ * through {@link sanitizeFilename} before being assigned to `a.download`.
+ */
+export function triggerLinkDownload(args: {
+  url: string
+  filename: string
+}): void {
+  const { url, filename } = args
+  const a = document.createElement('a')
+  a.href = url
+  a.download = sanitizeFilename(filename)
+  a.style.display = 'none'
+  document.body.appendChild(a)
+  a.click()
+  a.remove()
+}
+
+export interface DownloadDOMToPNGOptions {
+  element: HTMLElement
+  /** html2canvas `scale`. Default 2 — crisp on hi-DPI displays. */
+  pixelRatio?: number
+  /**
+   * html2canvas `backgroundColor`. Default `null` (transparent) so the PNG
+   * inherits whatever surface it lands on when the user pastes it.
+   */
+  backgroundColor?: string | null
+}
+
+/**
+ * Rasterise an HTMLElement to PNG via `html2canvas` and wrap the result in
+ * a `DownloadHandle`. The caller is responsible for calling `handle.revoke`
+ * after the link click is dispatched. Used by per-widget download configs
+ * to power the PNG menu item.
+ */
+export async function downloadDOMToPNG(
+  opts: DownloadDOMToPNGOptions,
+): Promise<DownloadHandle> {
+  const { element, pixelRatio = 2, backgroundColor = null } = opts
+  const canvas = await html2canvas(element, {
+    scale: pixelRatio,
+    backgroundColor,
+    useCORS: true,
+    logging: false,
+  })
+  return new Promise<DownloadHandle>((resolve, reject) => {
+    canvas.toBlob((blob) => {
+      if (!blob) {
+        reject(new Error('[widgets-v2] toBlob() returned null'))
+        return
+      }
+      const url = URL.createObjectURL(blob)
+      resolve({ url, revoke: () => URL.revokeObjectURL(url) })
+    }, 'image/png')
+  })
+}

package/src/widgets-v2/actions/download/icons.tsx

@@ -0,0 +1,35 @@
+import { SvgIcon, type SvgIconProps } from '@mui/material'
+import { ArticleOutlined, ImageOutlined } from '@mui/icons-material'
+
+/**
+ * Generic "image" glyph used for the PNG download item. Wraps MUI's
+ * `ImageOutlined` so callers can swap it via the per-widget download
+ * config's `icon` override without pulling MUI directly.
+ */
+export function PNGIcon(props: SvgIconProps) {
+  return <ImageOutlined {...props} />
+}
+
+/**
+ * Generic "document" glyph used for the Markdown download item. Wraps MUI's
+ * `ArticleOutlined`, mirroring {@link PNGIcon}, so the Markdown menu item
+ * carries an icon consistent with the other download formats.
+ */
+export function MarkdownIcon(props: SvgIconProps) {
+  return <ArticleOutlined {...props} />
+}
+
+/**
+ * "CSV" rectangle with the letters spelled inside — matches v1 visual and is
+ * easier to recognise in a download menu than a generic table glyph.
+ */
+export function CSVIcon(props: SvgIconProps) {
+  return (
+    <SvgIcon viewBox='0 0 18 18' {...props}>
+      <path
+        fill='currentColor'
+        d='M4.313 11.25h2.25v-1.125H4.688v-2.25h1.875V6.75h-2.25a.726.726 0 0 0-.535.216.726.726 0 0 0-.216.534v3c0 .213.072.39.216.534a.726.726 0 0 0 .534.216Zm2.925 0h2.25c.212 0 .39-.072.534-.216a.726.726 0 0 0 .216-.534V9.375a.931.931 0 0 0-.216-.59.658.658 0 0 0-.534-.273H8.363v-.637h1.875V6.75h-2.25a.726.726 0 0 0-.535.216.726.726 0 0 0-.216.534v1.125c0 .213.072.403.216.572a.675.675 0 0 0 .534.253h1.126v.675H7.238v1.125Zm4.95 0h1.124l1.313-4.5H13.5l-.75 2.588L12 6.75h-1.125l1.313 4.5ZM3 15c-.413 0-.766-.147-1.06-.44a1.445 1.445 0 0 1-.44-1.06v-9c0-.412.147-.766.44-1.06C2.235 3.148 2.588 3 3 3h12c.412 0 .766.147 1.06.44.293.294.44.648.44 1.06v9c0 .412-.147.766-.44 1.06-.294.293-.647.44-1.06.44H3Zm0-1.5h12v-9H3v9Z'
+      />
+    </SvgIcon>
+  )
+}

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

@@ -0,0 +1,15 @@
+export { Download, type DownloadProps } from './download'
+export {
+  downloadToCSV,
+  downloadDOMToPNG,
+  toCsvString,
+  triggerLinkDownload,
+  type DownloadHandle,
+  type DownloadDOMToPNGOptions,
+} from './exports'
+export { CSVIcon, PNGIcon, MarkdownIcon } from './icons'
+export { buildPngDownloadItem, type BuildPngDownloadItemArgs } from './png-item'
+export { buildCsvDownloadItem, type BuildCsvDownloadItemArgs } from './csv-item'
+export { DOWNLOAD_ITEM_IDS, type DownloadItemId } from './constants'
+export type { DownloadItem } from './types'
+export { DEFAULT_DOWNLOAD_LABELS, type DownloadLabels } from './labels'

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

@@ -0,0 +1,16 @@
+export interface DownloadLabels {
+  trigger: string
+  /** Tooltip / aria-label shown on the trigger while a download is in flight. */
+  loading: string
+  /**
+   * Tooltip / aria-label shown on the trigger after a download failed. Cleared
+   * the next time the menu opens.
+   */
+  error: string
+}
+
+export const DEFAULT_DOWNLOAD_LABELS: DownloadLabels = {
+  trigger: 'Download',
+  loading: 'Downloading…',
+  error: 'Download failed',
+}

package/src/widgets-v2/actions/download/png-item.test.tsx

@@ -0,0 +1,72 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { buildPngDownloadItem } from './png-item'
+
+type ToBlobCb = (blob: Blob | null) => void
+const mockToBlob = vi.fn((cb: ToBlobCb) => cb(new Blob(['png-bytes'])))
+
+vi.mock('html2canvas', () => ({
+  default: () => Promise.resolve({ toBlob: mockToBlob }),
+}))
+
+let revokeSpy: ReturnType<typeof vi.spyOn>
+
+beforeEach(() => {
+  mockToBlob.mockReset()
+  mockToBlob.mockImplementation((cb: ToBlobCb) => cb(new Blob(['png-bytes'])))
+  vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:png')
+  revokeSpy = vi
+    .spyOn(URL, 'revokeObjectURL')
+    .mockImplementation(() => undefined)
+})
+
+describe('buildPngDownloadItem', () => {
+  it('returns an item with the canonical PNG shape (id, label, icon)', () => {
+    const item = buildPngDownloadItem({
+      filename: 'demo',
+      getCaptureEl: () => document.createElement('div'),
+    })
+    expect(item.id).toBe('png')
+    expect(item.label).toBe('PNG')
+    expect(item.icon).toBeTruthy()
+  })
+
+  it('honours a label override', () => {
+    const item = buildPngDownloadItem({
+      filename: 'demo',
+      getCaptureEl: () => document.createElement('div'),
+      label: 'Export image',
+    })
+    expect(item.label).toBe('Export image')
+  })
+
+  it('resolve() rasterises the capture element and returns a handle with .png filename', async () => {
+    const item = buildPngDownloadItem({
+      filename: 'sales',
+      getCaptureEl: () => document.createElement('div'),
+    })
+    const handle = await item.resolve()
+    expect(handle.url).toBe('blob:png')
+    expect(handle.filename).toBe('sales.png')
+    handle.revoke?.()
+    expect(revokeSpy).toHaveBeenCalledWith('blob:png')
+  })
+
+  it('resolve() rejects when getCaptureEl returns null', async () => {
+    const item = buildPngDownloadItem({
+      filename: 'demo',
+      getCaptureEl: () => null,
+    })
+    await expect(item.resolve()).rejects.toThrow(/No PNG capture element/)
+  })
+
+  it('forwards pixelRatio and backgroundColor overrides', async () => {
+    const item = buildPngDownloadItem({
+      filename: 'sales',
+      getCaptureEl: () => document.createElement('div'),
+      pixelRatio: 4,
+      backgroundColor: '#fff',
+    })
+    const handle = await item.resolve()
+    expect(handle.filename).toBe('sales.png')
+  })
+})

package/src/widgets-v2/actions/download/png-item.tsx

@@ -0,0 +1,53 @@
+import { DOWNLOAD_ITEM_IDS } from './constants'
+import { downloadDOMToPNG } from './exports'
+import { PNGIcon } from './icons'
+import type { DownloadItem } from './types'
+
+export interface BuildPngDownloadItemArgs {
+  /** Base filename (without extension). The item appends `.png`. */
+  filename: string
+  /**
+   * Reads the capture element to rasterise. Called at click time so the
+   * download config doesn't capture a stale reference. Wire it to
+   * `() => getCaptureEl(id)` from `widgets-v2/stores`.
+   */
+  getCaptureEl: () => HTMLElement | null
+  /** html2canvas `scale`. Default 2. */
+  pixelRatio?: number
+  /** html2canvas `backgroundColor`. Default transparent (`null`). */
+  backgroundColor?: string | null
+  /** Override the menu label. Default `'PNG'`. */
+  label?: string
+}
+
+/**
+ * Builds the standard PNG `DownloadItem` used by every per-widget download
+ * config. Centralised so the menu label, icon, error message, and filename
+ * suffix stay consistent across widgets without each `create*DownloadConfig`
+ * re-deriving the same shape.
+ */
+export function buildPngDownloadItem(
+  args: BuildPngDownloadItemArgs,
+): DownloadItem {
+  return {
+    id: DOWNLOAD_ITEM_IDS.png,
+    label: args.label ?? 'PNG',
+    icon: <PNGIcon fontSize='small' />,
+    resolve: async () => {
+      const el = args.getCaptureEl()
+      if (!el) {
+        throw new Error('[widgets-v2] No PNG capture element available')
+      }
+      const handle = await downloadDOMToPNG({
+        element: el,
+        pixelRatio: args.pixelRatio,
+        backgroundColor: args.backgroundColor,
+      })
+      return {
+        url: handle.url,
+        filename: `${args.filename}.png`,
+        revoke: handle.revoke,
+      }
+    },
+  }
+}

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

@@ -0,0 +1,3 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {} satisfies Record<string, SxProps<Theme>>

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

@@ -0,0 +1,32 @@
+import type { ReactElement } from 'react'
+
+export interface DownloadItem {
+  /** Unique key (also used as menu label key). */
+  id: string
+  /** Display label in the menu. */
+  label: string
+  /**
+   * Optional leading icon shown next to the label. Pass a rendered element
+   * (e.g. `<DownloadIcon fontSize='small' />`) so consumers can fully
+   * control sizing / colour. Rendered inside an MUI `<ListItemIcon>`.
+   */
+  icon?: ReactElement
+  /**
+   * When `true`, the menu item is rendered but non-clickable (greyed out).
+   * Useful for items whose underlying export is unavailable in the current
+   * widget state (no rows, missing permission, etc.).
+   */
+  disabled?: boolean
+  /**
+   * Override for the resolved filename. When set, `resolve()`'s `filename`
+   * is ignored and this value is used instead — handy when the consumer
+   * wants to template the filename with widget metadata without having to
+   * close over it inside `resolve()`.
+   */
+  filename?: string
+  /**
+   * Resolves to a Blob URL the trigger will click. Optional `revoke` is
+   * called after the click is dispatched.
+   */
+  resolve: () => Promise<{ url: string; filename: string; revoke?: () => void }>
+}

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

@@ -0,0 +1,212 @@
+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)
+  })
+})