@carto/ps-react-ui 5.0.0 → 6.0.0

package/src/{widgets-v2 → widgets}/actions/download/exports.ts

@@ -105,7 +105,7 @@ export async function downloadDOMToPNG(
   return new Promise<DownloadHandle>((resolve, reject) => {
     canvas.toBlob((blob) => {
       if (!blob) {
-        reject(new Error('[widgets-v2] toBlob() returned null'))
+        reject(new Error('[widgets] toBlob() returned null'))
         return
       }
       const url = URL.createObjectURL(blob)

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

@@ -9,7 +9,7 @@ export interface BuildPngDownloadItemArgs {
   /**
    * 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(id)` from `widgets/stores`.
    */
   getCaptureEl: () => HTMLElement | null
   /** html2canvas `scale`. Default 2. */
@@ -36,7 +36,7 @@ export function buildPngDownloadItem(
     resolve: async () => {
       const el = args.getCaptureEl()
       if (!el) {
-        throw new Error('[widgets-v2] No PNG capture element available')
+        throw new Error('[widgets] No PNG capture element available')
       }
       const handle = await downloadDOMToPNG({
         element: el,

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

@@ -1,21 +1,32 @@
-import type { JSX, ReactNode } from 'react'
-import type { IconButtonProps } from '@mui/material'
-import type { WidgetState } from '../../stores/types'
+import type { ReactElement } from 'react'
 
-export interface DownloadItem<D = unknown> {
+export interface DownloadItem {
+  /** Unique key (also used as menu label key). */
   id: string
+  /** Display label in the menu. */
   label: string
-  icon?: JSX.Element
+  /**
+   * 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
-  modifier: (data: D) => Promise<string | undefined>
-  callback?: (data: string) => void
-}
-
-export interface DownloadProps {
-  id: WidgetState['id']
-  items: DownloadItem[]
-  labels?: { ariaLabel?: string }
-  IconButtonProps?: IconButtonProps
-  Icon?: ReactNode
+  /**
+   * 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/actions/fullscreen/fullscreen.test.tsx

@@ -1,269 +1,212 @@
-import { describe, test, expect, beforeEach } from 'vitest'
-import { render, screen, fireEvent, within } from '@testing-library/react'
+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 { useWidgetStore } from '../../stores/widget-store'
-import type { FullScreenState } from './types'
+import type { FullScreenWidgetState } from './types'
 
-describe('FullScreen', () => {
-  const widgetId = 'test-widget'
+beforeEach(() => clearAllWidgetStores())
+afterEach(() => clearAllWidgetStores())
 
-  beforeEach(() => {
-    // Clear store before each test
-    useWidgetStore.getState().clearWidgets()
-    // Initialize widget with title
-    useWidgetStore.getState().setWidget<FullScreenState>(widgetId, {
-      title: 'Test Widget',
-    })
-  })
-
-  test('renders fullscreen button', () => {
+describe('<FullScreen.Trigger> — store toggle', () => {
+  it('does not surface isFullScreen on the base WidgetState until the trigger fires', () => {
     render(
-      <FullScreen id={widgetId}>
-        <div>Widget Content</div>
-      </FullScreen>,
+      <Provider id='fs1' data={[]}>
+        <FullScreen.Trigger />
+      </Provider>,
     )
-
-    const button = screen.getByRole('button')
-    expect(button).toBeTruthy()
+    const state = getWidgetStore('fs1').getState()
+    expect((state as FullScreenWidgetState).isFullScreen).toBeUndefined()
   })
 
-  test('opens dialog when fullscreen button is clicked', () => {
+  it('toggles state on click and swaps the trigger label', () => {
     render(
-      <FullScreen id={widgetId}>
-        <div>Widget Content</div>
-      </FullScreen>,
+      <Provider id='fs2' data={[]}>
+        <FullScreen.Trigger labels={{ open: 'Expand', close: 'Shrink' }} />
+      </Provider>,
     )
-
-    const button = screen.getByRole('button')
-    fireEvent.click(button)
-
-    // Check if dialog is opened
-    expect(screen.getByText('Test Widget')).toBeTruthy()
-    expect(screen.getByText('Widget Content')).toBeTruthy()
+    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)
   })
 
-  test('closes dialog when close button is clicked', () => {
-    render(
-      <FullScreen id={widgetId}>
-        <div>Widget Content</div>
-      </FullScreen>,
+  it('keepAlive remount restores isFullScreen', () => {
+    const { unmount } = render(
+      <Provider id='fs3' data={[]} keepAlive>
+        <FullScreen.Trigger labels={{ open: 'Maximise' }} />
+      </Provider>,
     )
-
-    // Open dialog
-    const openButton = screen.getByRole('button')
-    fireEvent.click(openButton)
-
-    // Find and click close button (inside the dialog)
-    const dialog = screen.getByRole('dialog')
-    const closeButton = within(dialog).getAllByRole('button')[0]
-
-    fireEvent.click(closeButton!)
-
-    // Store should be updated
-    const widget = useWidgetStore
-      .getState()
-      .getWidget<FullScreenState>(widgetId)
-    expect(widget?.isFullScreen).toBe(false)
-  })
-
-  test('uses custom aria label when provided', () => {
-    const customLabels = {
-      ariaLabel: 'custom-fullscreen-dialog',
-    }
-
+    fireEvent.click(screen.getByLabelText('Maximise'))
+    expect(
+      (getWidgetStore('fs3').getState() as FullScreenWidgetState).isFullScreen,
+    ).toBe(true)
+    unmount()
     render(
-      <FullScreen id={widgetId} labels={customLabels}>
-        <div>Widget Content</div>
-      </FullScreen>,
-    )
-
-    const button = screen.getByRole('button')
-    fireEvent.click(button)
-
-    const dialog = screen.getByRole('dialog')
-    expect(dialog.getAttribute('aria-labelledby')).toBe(
-      'custom-fullscreen-dialog',
+      <Provider id='fs3' data={[]} keepAlive>
+        <FullScreen.Trigger labels={{ open: 'Maximise' }} />
+      </Provider>,
     )
+    expect(
+      (getWidgetStore('fs3').getState() as FullScreenWidgetState).isFullScreen,
+    ).toBe(true)
   })
+})
 
-  test('uses default aria label when not provided', () => {
+describe('<FullScreen.Slot> — render-prop body + portal', () => {
+  it('passes the live isFullScreen flag to the render prop', () => {
+    let received: boolean | undefined
     render(
-      <FullScreen id={widgetId}>
-        <div>Widget Content</div>
-      </FullScreen>,
-    )
-
-    const button = screen.getByRole('button')
-    fireEvent.click(button)
-
-    const dialog = screen.getByRole('dialog')
-    expect(dialog.getAttribute('aria-labelledby')).toBe(
-      `fullscreen-dialog-title-${widgetId}`,
+      <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)
   })
 
-  test('renders children inside dialog content', () => {
-    const TestChild = () => (
-      <div>
-        <p>First paragraph</p>
-        <p>Second paragraph</p>
-      </div>
-    )
-
+  it('renders the title above the body when open', async () => {
     render(
-      <FullScreen id={widgetId}>
-        <TestChild />
-      </FullScreen>,
+      <Provider id='fs-title' data={[]}>
+        <FullScreen.Trigger />
+        <FullScreen.Slot title='Sales by region'>
+          {() => <div>body</div>}
+        </FullScreen.Slot>
+      </Provider>,
     )
-
-    const button = screen.getByRole('button')
-    fireEvent.click(button)
-
-    expect(screen.getByText('First paragraph')).toBeTruthy()
-    expect(screen.getByText('Second paragraph')).toBeTruthy()
+    fireEvent.click(screen.getByLabelText('Open in full screen'))
+    expect(await screen.findByText('Sales by region')).toBeTruthy()
   })
 
-  test('dialog is not visible initially', () => {
+  it('still renders the close button when no title is given', async () => {
     render(
-      <FullScreen id={widgetId}>
-        <div>Widget Content</div>
-      </FullScreen>,
+      <Provider id='fs-no-title' data={[]}>
+        <FullScreen.Trigger />
+        <FullScreen.Slot>{() => <div>body</div>}</FullScreen.Slot>
+      </Provider>,
     )
-
-    // Dialog should not be rendered until button is clicked
-    expect(screen.queryByRole('dialog')).toBeNull()
+    fireEvent.click(screen.getByLabelText('Open in full screen'))
+    const closes = await screen.findAllByLabelText('Exit full screen')
+    expect(closes.length).toBeGreaterThan(0)
   })
 
-  test('updates widget store when opening fullscreen', () => {
+  it('renders `actions` in the modal header, next to the close button', async () => {
     render(
-      <FullScreen id={widgetId}>
-        <div>Widget Content</div>
-      </FullScreen>,
+      <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>,
     )
-
-    const button = screen.getByRole('button')
-    fireEvent.click(button)
-
-    const widget = useWidgetStore
-      .getState()
-      .getWidget<FullScreenState>(widgetId)
-    expect(widget?.isFullScreen).toBe(true)
+    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()
   })
 
-  test('updates widget store when closing fullscreen', () => {
-    // Pre-set the widget to fullscreen
-    useWidgetStore.getState().setWidget<FullScreenState>(widgetId, {
-      title: 'Test Widget',
-      isFullScreen: true,
-    })
-
+  it('keeps `actions` mounted across a fullscreen toggle', () => {
     render(
-      <FullScreen id={widgetId}>
-        <div>Widget Content</div>
-      </FullScreen>,
+      <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>,
     )
-
-    // Find and click close button
-    const dialog = screen.getByRole('dialog')
-    const closeButton = within(dialog).getAllByRole('button')[0]
-
-    fireEvent.click(closeButton!)
-
-    const widget = useWidgetStore
-      .getState()
-      .getWidget<FullScreenState>(widgetId)
-    expect(widget?.isFullScreen).toBe(false)
+    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)
   })
 
-  test('handles multiple fullscreen widgets independently', () => {
-    const widget1Id = 'widget-1'
-    const widget2Id = 'widget-2'
-
-    // Initialize both widgets with titles
-    useWidgetStore.getState().setWidget<FullScreenState>(widget1Id, {
-      title: 'Widget 1',
-    })
-    useWidgetStore.getState().setWidget<FullScreenState>(widget2Id, {
-      title: 'Widget 2',
-    })
-
+  it('merges `paperSx` over the default dialog paper size', () => {
     render(
-      <>
-        <FullScreen id={widget1Id}>
-          <div>Content 1</div>
-        </FullScreen>
-        <FullScreen id={widget2Id}>
-          <div>Content 2</div>
-        </FullScreen>
-      </>,
+      <Provider id='fs-paper' data={[]}>
+        <FullScreen.Trigger />
+        <FullScreen.Slot title='P' paperSx={{ width: 560, height: 'auto' }}>
+          {() => <div>body</div>}
+        </FullScreen.Slot>
+      </Provider>,
     )
-
-    const buttons = screen.getAllByRole('button')
-
-    // Open first widget
-    fireEvent.click(buttons[0]!)
-    let widget1 = useWidgetStore
-      .getState()
-      .getWidget<FullScreenState>(widget1Id)
-    let widget2 = useWidgetStore
-      .getState()
-      .getWidget<FullScreenState>(widget2Id)
-
-    expect(widget1?.isFullScreen).toBe(true)
-    expect(widget2?.isFullScreen).toBeUndefined()
-
-    // Verify widget 1 content is displayed
-    expect(screen.getByText('Content 1')).toBeTruthy()
-
-    // Close first widget via store (simpler than clicking)
-    useWidgetStore.getState().setWidget<FullScreenState>(widget1Id, {
-      title: 'Widget 1',
-      isFullScreen: false,
-    })
-
-    // Open second widget
-    fireEvent.click(buttons[1]!)
-
-    widget1 = useWidgetStore.getState().getWidget<FullScreenState>(widget1Id)
-    widget2 = useWidgetStore.getState().getWidget<FullScreenState>(widget2Id)
-
-    expect(widget1?.isFullScreen).toBe(false)
-    expect(widget2?.isFullScreen).toBe(true)
-
-    // Verify widget 2 content is displayed
-    expect(screen.getByText('Content 2')).toBeTruthy()
+    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')
   })
 
-  test('renders dialog title with correct typography', () => {
+  it('keeps the same DOM node across the fullscreen toggle (portal reparent)', () => {
     render(
-      <FullScreen id={widgetId}>
-        <div>Widget Content</div>
-      </FullScreen>,
+      <Provider id='fs-reparent' data={[]}>
+        <FullScreen.Trigger />
+        <FullScreen.Slot title='X'>
+          {() => <span data-testid='inner'>inner</span>}
+        </FullScreen.Slot>
+      </Provider>,
     )
-
-    const button = screen.getByRole('button')
-    fireEvent.click(button)
-
-    const title = screen.getByText('Test Widget')
-    expect(title).toBeTruthy()
-    expect(title.tagName).toBe('SPAN')
+    const before = screen.getByTestId('inner')
+    fireEvent.click(screen.getByLabelText('Open in full screen'))
+    const after = screen.getByTestId('inner')
+    expect(after).toBe(before)
   })
 
-  test('dialog respects isFullScreen state from store', () => {
-    // Set initial state to fullscreen
-    useWidgetStore.getState().setWidget<FullScreenState>(widgetId, {
-      title: 'Test Widget',
-      isFullScreen: true,
-    })
-
+  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(
-      <FullScreen id={widgetId}>
-        <div>Widget Content</div>
-      </FullScreen>,
+      <Provider id='fs-mount-once' data={[]}>
+        <FullScreen.Trigger labels={{ open: 'OpenT', close: 'CloseT' }} />
+        <FullScreen.Slot title='Z'>{() => <CountingChild />}</FullScreen.Slot>
+      </Provider>,
     )
-
-    // Dialog should be visible immediately
-    expect(screen.getByRole('dialog')).toBeTruthy()
-    expect(screen.getByText('Widget Content')).toBeTruthy()
+    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)
   })
 })