@carto/ps-react-ui 5.3.0 → 6.1.0

package/src/widgets/actions/download/download.tsx

@@ -1,3 +1,4 @@
+import { useCallback, useContext, useState, type ComponentType } from 'react'
 import {
   CircularProgress,
   IconButton,
@@ -5,94 +6,115 @@ import {
   ListItemText,
   Menu,
   MenuItem,
+  type SvgIconProps,
 } from '@mui/material'
-import type { DownloadItem, DownloadProps } from './types'
-import { FileDownloadOutlined } from '@mui/icons-material'
-import { useState, type MouseEvent } from 'react'
-import { useWidgetSelector } from '../../stores/use-widget-selector'
+import { FileDownload as DownloadIcon } from '@mui/icons-material'
+import { Tooltip } from '../../../components'
+import { WidgetContext } from '../../stores'
+import { triggerLinkDownload } from './exports'
+import type { DownloadItem } from './types'
+import { DEFAULT_DOWNLOAD_LABELS, type DownloadLabels } from './labels'
 
-const EMPTY_LABELS: NonNullable<DownloadProps['labels']> = {}
+export interface DownloadProps {
+  items: readonly DownloadItem[]
+  labels?: Partial<DownloadLabels>
+  icon?: ComponentType<SvgIconProps>
+  iconProps?: SvgIconProps
+  /**
+   * Fires when an item's `resolve()` rejects (or any step in the click-through
+   * path throws). The error is normalised to a real `Error` first. Surface
+   * to your telemetry / toast layer here; the trigger already shows a visual
+   * error indicator independently.
+   */
+  onError?: (err: Error) => void
+}
 
-/**
- * Dropdown menu action for exporting widget data in various formats (CSV, PNG, etc.).
- *
- * Reads widget data from the store and triggers downloads using the modifier
- * function defined in each `DownloadItem`.
- *
- * @example
- * ```tsx
- * <Download id={widgetId} items={barDownloadConfig({ refUI })} />
- * ```
- */
 export function Download({
-  id,
   items,
-  labels = EMPTY_LABELS,
-  Icon,
-  IconButtonProps,
+  labels,
+  icon: Icon = DownloadIcon,
+  iconProps,
+  onError,
 }: DownloadProps) {
-  const { data } = useWidgetSelector(id, (w) => ({
-    data: w?.data,
-  }))
-
+  const _labels = { ...DEFAULT_DOWNLOAD_LABELS, ...labels }
+  const [anchorEl, setAnchorEl] = useState<HTMLElement | null>(null)
+  const id = useContext(WidgetContext)
   const [isDownloading, setIsDownloading] = useState(false)
-  const [anchorEl, setAnchorEl] = useState<null | HTMLElement>(null)
-
-  const handleToggle = (event: MouseEvent<HTMLElement>) => {
-    event.stopPropagation()
-    setAnchorEl(event.currentTarget)
-  }
-
-  const handleDownload = (data: string, option: DownloadItem) => {
-    const link = document.createElement('a')
-    link.href = data
-    link.download = option.filename ?? id
-    link.style.display = 'none'
-    document.body.appendChild(link)
-    link.click()
-    document.body.removeChild(link)
-    option.callback?.(link.href)
-  }
+  const [error, setError] = useState<Error | null>(null)
 
-  const handleClick = async (
-    event: MouseEvent<HTMLElement>,
-    option: DownloadItem,
-  ) => {
-    event.stopPropagation()
+  const open = useCallback((e: React.MouseEvent<HTMLButtonElement>) => {
+    // Clear any prior error when the user re-engages the menu — the next
+    // attempt is a fresh interaction, not a continuation of the failed one.
+    setError(null)
+    setAnchorEl(e.currentTarget)
+  }, [])
+  const close = useCallback(() => setAnchorEl(null), [])
 
-    setIsDownloading(true)
-    setAnchorEl(null)
-
-    const result = await option.modifier(data)
-
-    if (!result) {
-      setIsDownloading(false)
-      return
-    }
+  const onSelect = useCallback(
+    (item: DownloadItem) => {
+      // Single-flight: ignore re-entry while a download is already in flight.
+      // The trigger is `disabled` and the menu is closed during that window,
+      // so this guard mostly defends against future call sites that bypass
+      // the menu (e.g. keyboard shortcuts).
+      if (item.disabled || isDownloading) return
+      close()
+      setIsDownloading(true)
+      setError(null)
+      item
+        .resolve({ id })
+        .then(({ url, filename, revoke }) => {
+          // `item.filename` overrides what `resolve()` returns — lets consumers
+          // template the filename with widget metadata declaratively.
+          triggerLinkDownload({ url, filename: item.filename ?? filename })
+          // Defer revoke past the current task so Safari / Firefox-on-slow-disk
+          // can dispatch the download before the blob URL is invalidated.
+          // Synchronous revoke here can silently cancel the download.
+          if (revoke) setTimeout(revoke, 0)
+        })
+        .catch((err: unknown) => {
+          const e = err instanceof Error ? err : new Error(String(err))
+          setError(e)
+          onError?.(e)
+        })
+        .finally(() => {
+          setIsDownloading(false)
+        })
+    },
+    [close, id, isDownloading, onError],
+  )
 
-    handleDownload(result, option)
-    setIsDownloading(false)
-  }
+  const triggerLabel = isDownloading
+    ? _labels.loading
+    : error
+      ? _labels.error
+      : _labels.trigger
+  const triggerActive = Boolean(anchorEl) || isDownloading
 
   return (
     <>
-      <IconButton
-        size='small'
-        aria-label={labels.ariaLabel ?? 'download options'}
-        aria-controls='options-menu'
-        aria-haspopup='true'
-        onClick={handleToggle}
-        {...IconButtonProps}
-        disabled={isDownloading || items.length === 0}
-        className={isDownloading || anchorEl ? 'active' : ''}
-      >
-        {isDownloading ? (
-          <CircularProgress size={18} color='inherit' />
-        ) : (
-          (Icon ?? <FileDownloadOutlined />)
-        )}
-      </IconButton>
+      <Tooltip title={triggerLabel}>
+        <IconButton
+          size='small'
+          aria-label={triggerLabel}
+          aria-haspopup='true'
+          aria-expanded={anchorEl ? 'true' : undefined}
+          aria-busy={isDownloading || undefined}
+          data-error={error ? 'true' : undefined}
+          disabled={isDownloading || items.length === 0}
+          onClick={open}
+          className={triggerActive ? 'active' : undefined}
+        >
+          {isDownloading ? (
+            <CircularProgress size={18} color='inherit' />
+          ) : (
+            <Icon fontSize='small' {...iconProps} />
+          )}
+        </IconButton>
+      </Tooltip>
       <Menu
+        anchorEl={anchorEl}
+        open={Boolean(anchorEl)}
+        onClose={close}
         variant='menu'
         elevation={8}
         anchorOrigin={{
@@ -103,27 +125,19 @@ export function Download({
           vertical: 'top',
           horizontal: 'right',
         }}
-        anchorEl={anchorEl}
-        open={Boolean(anchorEl)}
-        onClose={() => setAnchorEl(null)}
-        MenuListProps={{
-          sx: {
-            paddingBottom: 0,
-          },
-        }}
       >
-        {items.map((option) => (
+        {items.map((item) => (
           <MenuItem
-            key={option.id}
-            disabled={option.disabled}
-            onClick={(e) => void handleClick(e, option)}
+            key={item.id}
+            disabled={item.disabled}
+            onClick={() => void onSelect(item)}
           >
-            {option.icon && (
+            {item.icon && (
               <ListItemIcon sx={{ color: 'text.primary' }}>
-                {option.icon}
+                {item.icon}
               </ListItemIcon>
             )}
-            <ListItemText>{option.label}</ListItemText>
+            <ListItemText>{item.label}</ListItemText>
           </MenuItem>
         ))}
       </Menu>