@carto/ps-react-ui 4.11.3 → 4.12.0

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

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

@@ -0,0 +1,71 @@
+import { DOWNLOAD_ITEM_IDS } from './constants'
+import { downloadToCSV } from './exports'
+import { CSVIcon } from './icons'
+import type { DownloadItem } from './types'
+
+interface BuildCsvDownloadItemBase {
+  /** Base filename (without extension). The item appends `.csv`. */
+  filename: string
+  /** Override the menu label. Default `'CSV'`. */
+  label?: string
+}
+
+/**
+ * Args for {@link buildCsvDownloadItem}. A discriminated union: a caller must
+ * supply exactly one content source — `getRows` (rows serialised through the
+ * shared `toCsvString`) or `getCsv` (a pre-built CSV string). The `?: never`
+ * arms make passing both — or neither — a compile-time error.
+ */
+export type BuildCsvDownloadItemArgs =
+  | (BuildCsvDownloadItemBase & {
+      /**
+       * Builds the CSV rows at click time. Used by most widgets — rows are run
+       * through `toCsvString` so escaping (incl. the spreadsheet
+       * formula-injection guard) stays consistent across widgets.
+       */
+      getRows: () => readonly (readonly unknown[])[]
+      getCsv?: never
+    })
+  | (BuildCsvDownloadItemBase & {
+      /**
+       * Returns a pre-built CSV string at click time. Escape hatch for widgets
+       * (e.g. Table) that already serialise their own CSV with bespoke
+       * header/cell handling.
+       */
+      getCsv: () => string
+      getRows?: never
+    })
+
+/**
+ * Builds the standard CSV `DownloadItem` used by every per-widget download
+ * config. Centralised so the menu label, icon, and `.csv` filename suffix stay
+ * consistent across widgets — mirrors {@link buildPngDownloadItem} so neither
+ * format can drift again.
+ */
+export function buildCsvDownloadItem(
+  args: BuildCsvDownloadItemArgs,
+): DownloadItem {
+  return {
+    id: DOWNLOAD_ITEM_IDS.csv,
+    label: args.label ?? 'CSV',
+    icon: <CSVIcon fontSize='small' />,
+    resolve: () => {
+      if (args.getCsv) {
+        const csv = args.getCsv()
+        const blob = new Blob([csv], { type: 'text/csv;charset=utf-8;' })
+        const url = URL.createObjectURL(blob)
+        return Promise.resolve({
+          url,
+          filename: `${args.filename}.csv`,
+          revoke: () => URL.revokeObjectURL(url),
+        })
+      }
+      const handle = downloadToCSV(args.getRows())
+      return Promise.resolve({
+        url: handle.url,
+        filename: `${args.filename}.csv`,
+        revoke: handle.revoke,
+      })
+    },
+  }
+}

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

@@ -1,5 +1,5 @@
 import { SvgIcon, type SvgIconProps } from '@mui/material'
-import { ImageOutlined } from '@mui/icons-material'
+import { ArticleOutlined, ImageOutlined } from '@mui/icons-material'
 
 /**
  * Generic "image" glyph used for the PNG download item. Wraps MUI's
@@ -10,6 +10,15 @@ 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.

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

@@ -7,7 +7,9 @@ export {
   type DownloadHandle,
   type DownloadDOMToPNGOptions,
 } from './exports'
-export { CSVIcon, PNGIcon } from './icons'
+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/png-item.tsx

@@ -1,3 +1,4 @@
+import { DOWNLOAD_ITEM_IDS } from './constants'
 import { downloadDOMToPNG } from './exports'
 import { PNGIcon } from './icons'
 import type { DownloadItem } from './types'
@@ -29,7 +30,7 @@ export function buildPngDownloadItem(
   args: BuildPngDownloadItemArgs,
 ): DownloadItem {
   return {
-    id: 'png',
+    id: DOWNLOAD_ITEM_IDS.png,
     label: args.label ?? 'PNG',
     icon: <PNGIcon fontSize='small' />,
     resolve: async () => {

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

@@ -54,14 +54,19 @@ export {
   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 {

package/src/widgets-v2/bar/download.tsx

@@ -1,7 +1,6 @@
 import {
-  CSVIcon,
+  buildCsvDownloadItem,
   buildPngDownloadItem,
-  downloadToCSV,
   type DownloadItem,
 } from '../actions/download'
 import type { BarWidgetData } from './types'
@@ -42,25 +41,20 @@ export function createBarDownloadConfig(
       }),
     )
   }
-  items.push({
-    id: 'csv',
-    label: 'CSV',
-    icon: <CSVIcon fontSize='small' />,
-    resolve: () => {
-      const data = args.getData()
-      const rows: unknown[][] = []
-      for (const [i, series] of data.entries()) {
-        if (i > 0) rows.push([])
-        rows.push(['name', 'value'])
-        for (const d of series) rows.push([d.name, d.value])
-      }
-      const handle = downloadToCSV(rows)
-      return Promise.resolve({
-        url: handle.url,
-        filename: `${args.filename}.csv`,
-        revoke: handle.revoke,
-      })
-    },
-  })
+  items.push(
+    buildCsvDownloadItem({
+      filename: args.filename,
+      getRows: () => {
+        const data = args.getData()
+        const rows: unknown[][] = []
+        for (const [i, series] of data.entries()) {
+          if (i > 0) rows.push([])
+          rows.push(['name', 'value'])
+          for (const d of series) rows.push([d.name, d.value])
+        }
+        return rows
+      },
+    }),
+  )
   return items
 }

package/src/widgets-v2/category/download.test.ts

@@ -37,6 +37,15 @@ describe('createCategoryDownloadConfig', () => {
     ).toEqual(['csv'])
   })
 
+  it('CSV item carries the canonical icon and short label', () => {
+    const item = createCategoryDownloadConfig({
+      filename: 'c',
+      getData: () => data,
+    }).find((i) => i.id === 'csv')!
+    expect(item.label).toBe('CSV')
+    expect(item.icon).toBeTruthy()
+  })
+
   it('prepends PNG when getCaptureEl is provided', () => {
     const items = createCategoryDownloadConfig({
       filename: 'c',

package/src/widgets-v2/category/download.ts

@@ -1,6 +1,6 @@
 import {
+  buildCsvDownloadItem,
   buildPngDownloadItem,
-  downloadToCSV,
   type DownloadItem,
 } from '../actions/download'
 import type { CategoryWidgetData } from './types'
@@ -30,25 +30,21 @@ export function createCategoryDownloadConfig(args: {
       }),
     )
   }
-  items.push({
-    id: 'csv',
-    label: 'Download as CSV',
-    resolve: () => {
-      const data = args.getData()
-      const rows: unknown[][] = [['series', 'name', 'value']]
-      for (const [i, series] of data.entries()) {
-        const seriesName = args.seriesNames?.[i] ?? `series_${i + 1}`
-        for (const item of series) {
-          rows.push([seriesName, item.name, item.value])
+  items.push(
+    buildCsvDownloadItem({
+      filename: args.filename,
+      getRows: () => {
+        const data = args.getData()
+        const rows: unknown[][] = [['series', 'name', 'value']]
+        for (const [i, series] of data.entries()) {
+          const seriesName = args.seriesNames?.[i] ?? `series_${i + 1}`
+          for (const item of series) {
+            rows.push([seriesName, item.name, item.value])
+          }
         }
-      }
-      const handle = downloadToCSV(rows)
-      return Promise.resolve({
-        url: handle.url,
-        filename: `${args.filename}.csv`,
-        revoke: handle.revoke,
-      })
-    },
-  })
+        return rows
+      },
+    }),
+  )
   return items
 }

package/src/widgets-v2/formula/download.tsx

@@ -1,7 +1,6 @@
 import {
-  CSVIcon,
+  buildCsvDownloadItem,
   buildPngDownloadItem,
-  downloadToCSV,
   type DownloadItem,
 } from '../actions/download'
 import type { FormulaWidgetData } from './types'
@@ -38,32 +37,27 @@ export function createFormulaDownloadConfig(
       }),
     )
   }
-  items.push({
-    id: 'csv',
-    label: 'CSV',
-    icon: <CSVIcon fontSize='small' />,
-    resolve: () => {
-      const data = args.getData()
-      const rows: unknown[][] = [
-        ['series', 'prefix', 'value', 'suffix', 'note', 'delta'],
-      ]
-      for (const d of data) {
-        rows.push([
-          d.series?.name ?? '',
-          d.prefix ?? '',
-          d.value,
-          d.suffix ?? '',
-          d.note ?? '',
-          d.delta?.value ?? '',
-        ])
-      }
-      const handle = downloadToCSV(rows)
-      return Promise.resolve({
-        url: handle.url,
-        filename: `${args.filename}.csv`,
-        revoke: handle.revoke,
-      })
-    },
-  })
+  items.push(
+    buildCsvDownloadItem({
+      filename: args.filename,
+      getRows: () => {
+        const data = args.getData()
+        const rows: unknown[][] = [
+          ['series', 'prefix', 'value', 'suffix', 'note', 'delta'],
+        ]
+        for (const d of data) {
+          rows.push([
+            d.series?.name ?? '',
+            d.prefix ?? '',
+            d.value,
+            d.suffix ?? '',
+            d.note ?? '',
+            d.delta?.value ?? '',
+          ])
+        }
+        return rows
+      },
+    }),
+  )
   return items
 }

package/src/widgets-v2/histogram/download.ts

@@ -1,6 +1,6 @@
 import {
+  buildCsvDownloadItem,
   buildPngDownloadItem,
-  downloadToCSV,
   type DownloadItem,
 } from '../actions/download'
 import type { HistogramWidgetData } from './types'
@@ -31,30 +31,26 @@ export function createHistogramDownloadConfig(args: {
       }),
     )
   }
-  items.push({
-    id: 'csv',
-    label: 'Download as CSV',
-    resolve: () => {
-      const data = args.getData()
-      const ticks = args.getTicks()
-      const seriesCount = data.length
-      const header: unknown[] = ['bin_low', 'bin_high']
-      for (let i = 0; i < seriesCount; i++) {
-        header.push(args.seriesNames?.[i] ?? `series_${i + 1}`)
-      }
-      const rows: unknown[][] = [header]
-      for (let bin = 0; bin < Math.max(0, ticks.length - 1); bin++) {
-        const row: unknown[] = [ticks[bin], ticks[bin + 1]]
-        for (let s = 0; s < seriesCount; s++) row.push(data[s]?.[bin] ?? 0)
-        rows.push(row)
-      }
-      const handle = downloadToCSV(rows)
-      return Promise.resolve({
-        url: handle.url,
-        filename: `${args.filename}.csv`,
-        revoke: handle.revoke,
-      })
-    },
-  })
+  items.push(
+    buildCsvDownloadItem({
+      filename: args.filename,
+      getRows: () => {
+        const data = args.getData()
+        const ticks = args.getTicks()
+        const seriesCount = data.length
+        const header: unknown[] = ['bin_low', 'bin_high']
+        for (let i = 0; i < seriesCount; i++) {
+          header.push(args.seriesNames?.[i] ?? `series_${i + 1}`)
+        }
+        const rows: unknown[][] = [header]
+        for (let bin = 0; bin < Math.max(0, ticks.length - 1); bin++) {
+          const row: unknown[] = [ticks[bin], ticks[bin + 1]]
+          for (let s = 0; s < seriesCount; s++) row.push(data[s]?.[bin] ?? 0)
+          rows.push(row)
+        }
+        return rows
+      },
+    }),
+  )
   return items
 }

package/src/widgets-v2/markdown/{download.ts → download.tsx}

@@ -1,4 +1,6 @@
 import {
+  DOWNLOAD_ITEM_IDS,
+  MarkdownIcon,
   buildPngDownloadItem,
   toCsvString,
   triggerLinkDownload,
@@ -31,8 +33,9 @@ export function createMarkdownDownloadConfig(args: {
     )
   }
   items.push({
-    id: 'md',
-    label: 'Download as Markdown',
+    id: DOWNLOAD_ITEM_IDS.markdown,
+    label: 'Markdown',
+    icon: <MarkdownIcon fontSize='small' />,
     resolve: () => {
       const data = args.getData()
       const blob = new Blob([data.content ?? ''], {