@carto/ps-react-ui 4.11.3 → 4.12.1

package/src/chat/containers/chat-footer.tsx

@@ -1,16 +1,25 @@
+import { useState } from 'react'
 import {
   Box,
-  FilledInput,
+  Button,
   FormControl,
   FormHelperText,
   IconButton,
+  InputBase,
+  Menu,
+  MenuItem,
+  Typography,
 } from '@mui/material'
-import { ArrowUpwardOutlined, StopCircleOutlined } from '@mui/icons-material'
+import {
+  ArrowUpwardOutlined,
+  StopCircleOutlined,
+  KeyboardArrowDown,
+} from '@mui/icons-material'
 import type { ChatFooterProps } from '../types'
 import { styles } from './styles'
 
 const DEFAULT_CAPTION =
-  'Responses are AI generated. Please verify key information.'
+  'Responses are AI-generated. Please verify key information.'
 
 export function ChatFooter({
   value,
@@ -22,9 +31,29 @@ export function ChatFooter({
   placeholder = 'Type a message...',
   labels = {},
   caption = DEFAULT_CAPTION,
+  models,
+  selectedModel,
+  onModelChange,
+  startToolbarSlot,
+  endToolbarSlot,
   sx,
 }: ChatFooterProps) {
+  const [modelAnchor, setModelAnchor] = useState<HTMLElement | null>(null)
   const canSend = value.trim() && !disabled && !isGenerating
+  // Only worth showing when there's an actual choice — a single option is dead UI.
+  const showModelSelector = (models?.length ?? 0) > 1
+  const modelLabel = labels.model ?? 'Select model'
+  // Visible trigger text: the matched option's label, the raw value as a
+  // fallback, or the placeholder when nothing is selected yet.
+  const selectedLabel =
+    models?.find((m) => m.value === selectedModel)?.label ??
+    (selectedModel && selectedModel.length > 0 ? selectedModel : modelLabel)
+
+  // The slots row (start slot + model selector + end slot) renders under the input
+  // only when there's something to show; otherwise the grid is just input | send.
+  const hasSlots =
+    showModelSelector || Boolean(startToolbarSlot) || Boolean(endToolbarSlot)
+
   const handleKeyDown = (e: React.KeyboardEvent) => {
     if (e.key === 'Enter' && !e.shiftKey) {
       e.preventDefault()
@@ -34,41 +63,100 @@ export function ChatFooter({
     }
   }
 
+  const sendButton =
+    isGenerating && onStop ? (
+      <IconButton
+        size='small'
+        onClick={onStop}
+        disabled={disabled}
+        aria-label={labels.stop ?? 'Stop'}
+      >
+        <StopCircleOutlined />
+      </IconButton>
+    ) : (
+      <IconButton
+        size='small'
+        variant='contained'
+        color='primary'
+        onClick={onSend}
+        disabled={!canSend}
+        aria-label={labels.send ?? 'Send'}
+      >
+        <ArrowUpwardOutlined />
+      </IconButton>
+    )
+
   return (
     <FormControl fullWidth sx={{ ...styles.footerWrapper, ...sx }}>
-      <FilledInput
-        multiline
-        value={value}
-        onChange={(e) => onChange(e.target.value)}
-        onKeyDown={handleKeyDown}
-        placeholder={placeholder}
-        disabled={disabled || isGenerating}
-        sx={styles.footer}
-        style={{ minHeight: 0 }}
-        fullWidth
-        size='small'
-      />
-      <Box sx={styles.footerCorner}>
-        {isGenerating && onStop ? (
-          <IconButton
-            size='small'
-            onClick={onStop}
-            disabled={disabled}
-            aria-label={labels.stop ?? 'Stop'}
-          >
-            <StopCircleOutlined />
-          </IconButton>
-        ) : (
-          <IconButton
-            size='small'
-            variant='contained'
-            onClick={onSend}
-            disabled={!canSend}
-            aria-label={labels.send ?? 'Send'}
-          >
-            <ArrowUpwardOutlined />
-          </IconButton>
-        )}
+      {/* Two grid areas: [input + slots] | [send button, aligned to the end]. */}
+      <Box sx={styles.footerBox}>
+        <Box sx={styles.footerMain}>
+          <InputBase
+            multiline
+            minRows={1}
+            maxRows={8}
+            value={value}
+            onChange={(e) => onChange(e.target.value)}
+            onKeyDown={handleKeyDown}
+            placeholder={placeholder}
+            disabled={disabled || isGenerating}
+            sx={styles.footerInput}
+          />
+          {hasSlots && (
+            <Box sx={styles.footerSlots}>
+              {startToolbarSlot}
+              {showModelSelector && (
+                <>
+                  <Button
+                    size='small'
+                    variant='text'
+                    color='inherit'
+                    disabled={disabled || isGenerating}
+                    onClick={(e) => setModelAnchor(e.currentTarget)}
+                    aria-label={modelLabel}
+                    aria-haspopup='menu'
+                    aria-expanded={modelAnchor ? 'true' : undefined}
+                    endIcon={<KeyboardArrowDown />}
+                    sx={styles.modelSelector}
+                  >
+                    <Typography
+                      variant='caption'
+                      component='span'
+                      color='inherit'
+                      sx={styles.modelSelectorLabel}
+                    >
+                      {selectedLabel}
+                    </Typography>
+                  </Button>
+                  <Menu
+                    anchorEl={modelAnchor}
+                    open={Boolean(modelAnchor)}
+                    onClose={() => setModelAnchor(null)}
+                    variant='menu'
+                    elevation={8}
+                    anchorOrigin={{ vertical: 'top', horizontal: 'left' }}
+                    transformOrigin={{ vertical: 'bottom', horizontal: 'left' }}
+                  >
+                    {models?.map((m) => (
+                      <MenuItem
+                        key={m.value}
+                        selected={m.value === selectedModel}
+                        onClick={() => {
+                          onModelChange?.(m.value)
+                          setModelAnchor(null)
+                        }}
+                      >
+                        {m.label}
+                      </MenuItem>
+                    ))}
+                  </Menu>
+                </>
+              )}
+              {endToolbarSlot}
+            </Box>
+          )}
+        </Box>
+        <Box sx={styles.footerSend}>{sendButton}</Box>
       </Box>
       {caption ? (
         <FormHelperText sx={styles.footerCaption}>{caption}</FormHelperText>

package/src/chat/containers/styles.ts

@@ -20,24 +20,115 @@ export const styles = {
   },
   footerWrapper: {
     padding: ({ spacing }) => spacing(1),
-    position: 'relative',
-  },
-  footerCorner: {
-    position: 'absolute',
-    bottom: '38px',
-    right: `max(16px, calc(50% - ${CHAT_MAX_WIDTH / 2}px + 6px))`,
-    margin: '0 auto',
   },
-  footer: {
+  /**
+   * Rounded input box, matching the reference ChatFooter. A two-column grid:
+   * main column (input + optional slots) | send button, bottom-aligned so it
+   * stays at the end as the input grows. NO vertical padding — the textarea's own
+   * padding sets the ~32px single-line height, so the box hugs the input.
+   */
+  footerBox: {
     maxWidth: CHAT_MAX_WIDTH,
+    width: '100%',
     margin: '0 auto',
-    '&.MuiFilledInput-root.MuiInputBase-multiline.MuiInputBase-sizeSmall textarea':
-      {
-        resize: 'none',
-        maxHeight: '10em',
-        overflowY: 'auto !important',
-        paddingRight: ({ spacing }) => spacing(5),
-      },
+    display: 'grid',
+    gridTemplateColumns: '1fr auto',
+    alignItems: 'end',
+    columnGap: ({ spacing }) => spacing(0.5),
+    backgroundColor: ({ palette }) =>
+      palette.default?.background ?? 'rgba(44, 48, 50, 0.04)',
+    borderRadius: ({ spacing }) => spacing(0.5),
+    paddingInline: ({ spacing }) => spacing(0.5),
+  },
+  /** Main grid area: input stacked above the (optional) slots row. */
+  footerMain: {
+    minWidth: 0,
+    display: 'flex',
+    flexDirection: 'column',
+    gap: ({ spacing }) => spacing(0.5),
+  },
+  /**
+   * Send-button grid area, bottom-aligned (matches the reference flex-end row) so
+   * the button stays at the bottom as the input grows. The small bottom padding
+   * keeps it off the box edge — in the single-line state it reads as vertically
+   * centered (4px top / 4px bottom around the 24px button in the 32px row).
+   */
+  footerSend: {
+    alignSelf: 'end',
+    paddingBottom: ({ spacing }) => spacing(0.5),
+    '& .MuiIconButton-root': {
+      padding: ({ spacing }) => spacing(0.5),
+    },
+  },
+  /** The chrome-less multiline input (no underline / no filled affordance). */
+  footerInput: {
+    width: '100%',
+    typography: 'body2',
+    // The Meridian theme styles multiline InputBase as a tall "comment field"
+    // (min-height: 96px on the root, 12px/14px textarea padding). Override both to
+    // get the compact chat field: kill the root min-height and use the reference's
+    // 6px/10px padding — both need !important to beat the theme override. Height
+    // then comes from MUI's TextareaAutosize (minRows=1/maxRows=8): one line
+    // (~32px) → grows → scrolls.
+    //
+    // TextareaAutosize renders a hidden shadow <textarea> (it carries
+    // `aria-hidden="true"`, the same class, and an inline `padding: 0`) to measure
+    // the content height; MUI then applies that height to the visible input. Getting
+    // the compact ~32px single line right needs the two rules below split apart:
+    //
+    //  • Font metrics (size/line-height/letter-spacing) go on BOTH textareas. The
+    //    shadow measures with its own CSS, so if it isn't pinned to body2 it
+    //    measures at the default ~24px line-height and the box ends up too tall.
+    //  • Padding goes on the VISIBLE input ONLY (`:not([aria-hidden])`). A
+    //    `!important` padding that also hit the shadow would clobber its measurement
+    //    `padding: 0`, double-counting the padding (~44px instead of 32px).
+    //
+    // `!important` is required on both to beat the Meridian theme's tall
+    // "comment field" multiline overrides (12px/14px padding, larger metrics); the
+    // root `min-height: 0` kills that theme's 96px min-height.
+    minHeight: '0 !important',
+    '& textarea': {
+      fontSize: ({ typography }) => `${typography.body2.fontSize} !important`,
+      lineHeight: ({ typography }) =>
+        `${typography.body2.lineHeight} !important`,
+      letterSpacing: ({ typography }) =>
+        `${typography.body2.letterSpacing} !important`,
+    },
+    '& textarea:not([aria-hidden])': {
+      resize: 'none',
+      padding: ({ spacing }) => `${spacing(0.75, 1.25)} !important`,
+    },
+  },
+  /**
+   * Slots row under the input: start slot + model selector + end slot. The left
+   * padding lines the row's content up with the input text above it: the input
+   * text is inset ~12px from the box edge (InputBase root padding + the textarea's
+   * 10px left padding) while the model-selector text button only insets ~8px, so a
+   * 4px indent here makes the slot label share the placeholder's left edge instead
+   * of sitting further out.
+   */
+  footerSlots: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: ({ spacing }) => spacing(0.5),
+    minWidth: 0,
+    flexWrap: 'wrap',
+    paddingLeft: ({ spacing }) => spacing(0.5),
+    paddingBottom: ({ spacing }) => spacing(0.5),
+  },
+  modelSelector: {
+    textTransform: 'none',
+    color: ({ palette }) => palette.text.secondary,
+    maxWidth: '100%',
+    minWidth: 0,
+    '& .MuiButton-endIcon': {
+      marginLeft: ({ spacing }) => spacing(0.25),
+    },
+  },
+  modelSelectorLabel: {
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
   },
   footerCaption: {
     textAlign: 'center',
@@ -51,7 +142,7 @@ export const styles = {
     width: '100%',
     maxHeight: '100%',
     pt: 1,
-    pb: 2,
+    pb: 3,
     px: 2,
     display: 'flex',
     flexDirection: 'column',

package/src/chat/feedback/styles.ts

@@ -121,8 +121,12 @@ export const styles = {
     padding: ({ spacing }) => spacing(1),
     borderRadius: ({ spacing }) => spacing(0.5),
     backgroundColor: ({ palette }) => palette.background.default,
-    fontSize: '0.75rem',
-    fontFamily: 'monospace',
+    fontFamily: ({ typography }) =>
+      typography.code3?.fontFamily ??
+      typography.code1?.fontFamily ??
+      'monospace',
+    fontSize: ({ typography }) => typography.code3?.fontSize ?? '0.75rem',
+    lineHeight: ({ typography }) => typography.code3?.lineHeight ?? 1.333,
     whiteSpace: 'pre-wrap',
     wordBreak: 'break-word',
     overflowY: 'auto',
@@ -160,8 +164,11 @@ export const styles = {
     padding: ({ spacing }) => spacing(1),
     background: ({ palette, spacing }) =>
       `linear-gradient(to right, ${palette.action.hover} calc(${spacing(1)} + 3em), ${palette.background.default} calc(${spacing(1)} + 3em))`,
-    fontFamily: 'monospace',
-    fontSize: '0.8125rem',
+    fontFamily: ({ typography }) =>
+      typography.code3?.fontFamily ??
+      typography.code1?.fontFamily ??
+      'monospace',
+    fontSize: ({ typography }) => typography.code3?.fontSize ?? '0.75rem',
     whiteSpace: 'pre-wrap',
     wordBreak: 'break-word',
     lineHeight: 1.6,

package/src/chat/index.ts

@@ -12,6 +12,7 @@ export type {
   ChatContentRef,
   ChatHeaderProps,
   ChatFooterProps,
+  ChatModelOption,
   ChatStarterItem,
   ChatStarterProps,
   ChatRatingActionProps,

package/src/chat/types.ts

@@ -110,9 +110,31 @@ export interface ChatFooterProps extends ChatSxProps {
     send?: string
     /** Defaults to `'Stop'`. */
     stop?: string
+    /** `aria-label` for the model-selector trigger. Defaults to `'Select model'`. */
+    model?: string
   }
   /** Helper text rendered under the input. Defaults to an AI disclaimer; pass `null` to hide. */
   caption?: ReactNode
+  /**
+   * Selectable models for the in-toolbar model selector. The selector is only
+   * rendered when this is a non-empty array; the component is otherwise
+   * model-agnostic (the host owns the list, selection, and default).
+   */
+  models?: ChatModelOption[]
+  /** Currently selected model `value`. Controlled — the host owns the state. */
+  selectedModel?: string
+  /** Called with the picked model `value` when the user selects one. */
+  onModelChange?: (value: string) => void
+  /** Extra controls rendered at the start (left) of the toolbar, before the model selector. */
+  startToolbarSlot?: ReactNode
+  /** Extra controls rendered at the end (right) of the toolbar, before the send/stop button. */
+  endToolbarSlot?: ReactNode
+}
+
+/** An option for the `ChatFooter` model selector. */
+export interface ChatModelOption {
+  value: string
+  label: string
 }
 
 // === Extras props ===

package/src/chat/use-typewriter.ts

@@ -3,7 +3,7 @@ import { useEffect, useRef, useState } from 'react'
 interface UseTypewriterOptions {
   /** Characters revealed per second (default: `500`). */
   speed?: number
-  /** When true on mount, skip the animation and reveal the full text immediately. */
+  /** When true, reveal the full text immediately (and snap to it if it grows). */
   skipAnimation?: boolean
 }
 
@@ -16,8 +16,10 @@ interface UseTypewriterResult {
 
 /**
  * Reveals a string character-by-character at a steady rate via
- * `requestAnimationFrame`. Useful for smoothing out bursty WebSocket-streamed
- * agent message text — pair it with `ChatAgentMessage`.
+ * `requestAnimationFrame`. Designed for bursty, streamed agent text: as
+ * `fullText` grows the reveal keeps chasing the new end, and flipping
+ * `skipAnimation` to `true` (e.g. once generation finishes) snaps to the full
+ * text. Pair it with `ChatAgentMessage`.
  *
  * @example
  * ```tsx
@@ -36,47 +38,53 @@ export function useTypewriter(
 ): UseTypewriterResult {
   const { speed = 500, skipAnimation = false } = options
 
-  const skipRef = useRef(skipAnimation)
-
   const [charIndex, setCharIndex] = useState(() =>
-    skipRef.current ? fullText.length : 0,
+    skipAnimation ? fullText.length : 0,
   )
 
+  // Mirror of the revealed count, read/written ONLY inside the rAF loop (never
+  // during render). This lets the animation effect omit `charIndex` from its
+  // deps: were it a dep, the loop would tear down and restart on every revealed
+  // frame — resetting its frame timer — and never accumulate the elapsed time
+  // needed to advance, which stalls completely while `fullText` is also growing
+  // (the streaming case).
+  const charRef = useRef(charIndex)
+
   useEffect(() => {
-    if (skipRef.current) {
-      setCharIndex(fullText.length)
-      return
-    }
+    // When `skipAnimation` is set there's nothing to animate — the full text is
+    // shown directly via the derived `displayedText` below (no setState here, so
+    // a streamed message snaps to its full text the moment generation finishes,
+    // without an extra render or a `set-state-in-effect` cascade).
+    if (skipAnimation) return
 
-    if (charIndex >= fullText.length) {
-      return
-    }
+    // Already fully revealed (e.g. text hasn't grown since the last frame).
+    if (charRef.current >= fullText.length) return
 
     const msPerChar = 1000 / speed
     let rafId: number
     let lastTime: number | null = null
 
     function tick(timestamp: number) {
-      lastTime ??= timestamp
-
-      const elapsed = timestamp - lastTime
-      const charsToAdd = Math.floor(elapsed / msPerChar)
-
+      // Plain `?? =` not `??=`: the React Compiler can't lower logical-assignment
+      // operators and would bail this hook out of optimization.
+      lastTime = lastTime ?? timestamp
+      const charsToAdd = Math.floor((timestamp - lastTime) / msPerChar)
       if (charsToAdd > 0) {
         lastTime = timestamp
-        setCharIndex((prev) => Math.min(prev + charsToAdd, fullText.length))
+        const next = Math.min(charRef.current + charsToAdd, fullText.length)
+        charRef.current = next
+        setCharIndex(next)
+        if (next >= fullText.length) return // fully revealed — stop the loop
       }
-
       rafId = requestAnimationFrame(tick)
     }
 
     rafId = requestAnimationFrame(tick)
-
     return () => cancelAnimationFrame(rafId)
-  }, [fullText, charIndex, speed])
+  }, [fullText, speed, skipAnimation])
 
   return {
-    displayedText: fullText.slice(0, charIndex),
-    isTyping: charIndex < fullText.length,
+    displayedText: skipAnimation ? fullText : fullText.slice(0, charIndex),
+    isTyping: !skipAnimation && charIndex < fullText.length,
   }
 }

package/src/widgets/utils/chart-config/index.ts

@@ -15,6 +15,7 @@ export { flattenObjectArrayToCSV, scatterplotDataToCSV } from './csv-modifiers'
 export {
   buildLegendConfig,
   buildGridConfig,
+  buildAxisLabelStyle,
   createTooltipPositioner,
   createAxisLabelFormatter,
   createTooltipFormatter,

package/src/widgets/utils/chart-config/option-builders.test.ts

@@ -7,6 +7,7 @@ import {
   buildHistogramSeriesLabelConfig,
   buildLegendConfig,
   buildGridConfig,
+  buildAxisLabelStyle,
   createTooltipPositioner,
   createAxisLabelFormatter,
   applyXAxisFormatter,
@@ -195,6 +196,39 @@ describe('buildGridConfig', () => {
   })
 })
 
+describe('buildAxisLabelStyle', () => {
+  const themeWithTokens = {
+    typography: {
+      overlineDelicate: {
+        fontSize: '0.625rem',
+        fontFamily: 'Inter, sans-serif',
+      },
+    },
+    palette: {
+      black: { 60: 'rgba(44,48,50,0.6)' },
+      text: { secondary: 'rgba(0,0,0,0.6)' },
+    },
+  } as unknown as Theme
+
+  it('returns the overlineDelicate font + black[60] colour', () => {
+    expect(buildAxisLabelStyle(themeWithTokens)).toEqual({
+      fontSize: '0.625rem',
+      fontFamily: 'Inter, sans-serif',
+      color: 'rgba(44,48,50,0.6)',
+    })
+  })
+
+  it('falls back to text.secondary when black[60] is absent', () => {
+    const themeNoBlack = {
+      typography: {
+        overlineDelicate: { fontSize: '0.625rem', fontFamily: 'Inter' },
+      },
+      palette: { text: { secondary: 'rgba(0,0,0,0.6)' } },
+    } as unknown as Theme
+    expect(buildAxisLabelStyle(themeNoBlack).color).toBe('rgba(0,0,0,0.6)')
+  })
+})
+
 describe('createTooltipPositioner', () => {
   it('returns a positioner that places tooltip on the left when there is room', () => {
     const positioner = createTooltipPositioner(fakeTheme)

package/src/widgets/utils/chart-config/option-builders.ts

@@ -66,6 +66,27 @@ export function buildGridConfig(hasLegend: boolean, theme: Theme) {
   }
 }
 
+/**
+ * Builds the shared axis-label text style for chart widgets, matching the
+ * design's "Overline (Delicate)" token (Inter, 10px) in the secondary text
+ * colour (`rgba(44,48,50,0.6)`). Spread into an ECharts `axisLabel` for both
+ * x and y axes so every chart's labels stay consistent.
+ *
+ * Note: the token's `letterSpacing` and `textTransform: uppercase` are not
+ * representable in ECharts canvas text, so only font size/family/colour are
+ * applied.
+ *
+ * @param theme - MUI theme providing the typography token and palette
+ * @returns `{ fontSize, fontFamily, color }` for an ECharts `axisLabel`
+ */
+export function buildAxisLabelStyle(theme: Theme) {
+  return {
+    fontSize: theme.typography.overlineDelicate?.fontSize,
+    fontFamily: theme.typography.overlineDelicate?.fontFamily,
+    color: theme.palette.black?.[60] ?? theme.palette.text.secondary,
+  }
+}
+
 /**
  * Creates a tooltip position calculator that handles overflow
  * Used by bar, histogram, and scatterplot widgets

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

@@ -0,0 +1,14 @@
+/**
+ * Canonical `DownloadItem.id`s for the built-in download formats. Centralised
+ * so the per-format builders — and anything that keys off the id (menu logic,
+ * tests) — reference one source of truth instead of re-typing string literals.
+ * The Markdown format keeps the short `'md'` id to match its `.md` extension.
+ */
+export const DOWNLOAD_ITEM_IDS = {
+  png: 'png',
+  csv: 'csv',
+  markdown: 'md',
+} as const
+
+export type DownloadItemId =
+  (typeof DOWNLOAD_ITEM_IDS)[keyof typeof DOWNLOAD_ITEM_IDS]

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

@@ -0,0 +1,77 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { buildCsvDownloadItem } from './csv-item'
+
+let csvText = ''
+let revokeSpy: ReturnType<typeof vi.spyOn>
+
+beforeEach(() => {
+  csvText = ''
+  vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:csv')
+  revokeSpy = vi
+    .spyOn(URL, 'revokeObjectURL')
+    .mockImplementation(() => undefined)
+  const RealBlob = global.Blob
+  vi.stubGlobal(
+    'Blob',
+    class extends RealBlob {
+      constructor(parts: BlobPart[], opts?: BlobPropertyBag) {
+        csvText = typeof parts[0] === 'string' ? parts[0] : ''
+        super(parts, opts)
+      }
+    },
+  )
+})
+
+describe('buildCsvDownloadItem', () => {
+  it('returns an item with the canonical CSV shape (id, label, icon)', () => {
+    const item = buildCsvDownloadItem({ filename: 'demo', getRows: () => [] })
+    expect(item.id).toBe('csv')
+    expect(item.label).toBe('CSV')
+    expect(item.icon).toBeTruthy()
+  })
+
+  it('honours a label override', () => {
+    const item = buildCsvDownloadItem({
+      filename: 'demo',
+      getRows: () => [],
+      label: 'Export data',
+    })
+    expect(item.label).toBe('Export data')
+  })
+
+  it('getRows path serialises rows via toCsvString and returns a .csv handle', async () => {
+    const item = buildCsvDownloadItem({
+      filename: 'sales',
+      getRows: () => [
+        ['name', 'value'],
+        ['a', 1],
+      ],
+    })
+    const handle = await item.resolve()
+    expect(handle.url).toBe('blob:csv')
+    expect(handle.filename).toBe('sales.csv')
+    expect(csvText).toBe('name,value\na,1')
+    handle.revoke?.()
+    expect(revokeSpy).toHaveBeenCalledWith('blob:csv')
+  })
+
+  it('getRows path applies the formula-injection guard', async () => {
+    const item = buildCsvDownloadItem({
+      filename: 'sales',
+      getRows: () => [['=SUM(A1)']],
+    })
+    await item.resolve()
+    expect(csvText).toBe("'=SUM(A1)")
+  })
+
+  it('getCsv path passes the pre-built CSV through verbatim', async () => {
+    const item = buildCsvDownloadItem({
+      filename: 'table',
+      getCsv: () => 'col\n=raw',
+    })
+    const handle = await item.resolve()
+    expect(handle.filename).toBe('table.csv')
+    // getCsv is an escape hatch — content is used as-is, no extra escaping.
+    expect(csvText).toBe('col\n=raw')
+  })
+})