@carto/ps-react-ui 4.7.0 → 4.8.0

package/src/widgets-v2/markdown/markdown.test.tsx

@@ -0,0 +1,39 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render } from '@testing-library/react'
+import { Markdown } from './markdown'
+import { Provider } from '../provider/widget-provider'
+
+vi.mock('./markdown-ui', () => ({
+  MarkdownUI: ({ content }: { content: string }) => (
+    <div data-testid='md-ui'>{content}</div>
+  ),
+}))
+
+describe('<Markdown> bridge', () => {
+  it('forwards data.content from the store to MarkdownUI', () => {
+    const { getByTestId } = render(
+      <Provider id='md-1' data={{ content: '# hi\n\nbody' }}>
+        <Markdown />
+      </Provider>,
+    )
+    expect(getByTestId('md-ui').textContent).toBe('# hi\n\nbody')
+  })
+
+  it('falls back to empty string when data is undefined', () => {
+    const { getByTestId } = render(
+      <Provider id='md-2' data={undefined}>
+        <Markdown />
+      </Provider>,
+    )
+    expect(getByTestId('md-ui').textContent).toBe('')
+  })
+
+  it('falls back to empty string when data.content is missing', () => {
+    const { getByTestId } = render(
+      <Provider id='md-3' data={{} as { content: string }}>
+        <Markdown />
+      </Provider>,
+    )
+    expect(getByTestId('md-ui').textContent).toBe('')
+  })
+})

package/src/widgets-v2/markdown/markdown.tsx

@@ -0,0 +1,17 @@
+import { useWidgetId, useWidget } from '../stores'
+import { MarkdownUI } from './markdown-ui'
+import type { MarkdownWidgetData } from './types'
+
+/**
+ * Stateful Markdown bridge — reads `data.content` (post-pipeline) from the
+ * per-widget store and forwards it to the pure {@link MarkdownUI}. Sits
+ * inside `<Widget.Provider>`.
+ */
+export function Markdown() {
+  const id = useWidgetId()
+  const content = useWidget(id, (s) => {
+    const data = s.data as MarkdownWidgetData | undefined
+    return data?.content ?? ''
+  })
+  return <MarkdownUI content={content} />
+}

package/src/widgets-v2/markdown/skeleton.test.tsx

@@ -0,0 +1,15 @@
+import { describe, it, expect } from 'vitest'
+import { render } from '@testing-library/react'
+import { MarkdownSkeleton } from './skeleton'
+
+describe('<MarkdownSkeleton>', () => {
+  it('renders the default 5 line stubs', () => {
+    const { container } = render(<MarkdownSkeleton />)
+    expect(container.querySelectorAll('.MuiSkeleton-root').length).toBe(5)
+  })
+
+  it('honours custom line count', () => {
+    const { container } = render(<MarkdownSkeleton lines={2} />)
+    expect(container.querySelectorAll('.MuiSkeleton-root').length).toBe(2)
+  })
+})

package/src/widgets-v2/markdown/skeleton.tsx

@@ -0,0 +1,32 @@
+import { Box, Skeleton } from '@mui/material'
+import type { SxProps, Theme } from '@mui/material'
+
+const styles = {
+  root: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 1,
+    py: 1,
+  },
+  line: (width: string): SxProps<Theme> => ({ width, height: 18 }),
+} as const
+
+export interface MarkdownSkeletonProps {
+  lines?: number
+}
+
+export function MarkdownSkeleton({ lines = 5 }: MarkdownSkeletonProps) {
+  // Vary widths to mimic prose.
+  const widths = ['100%', '95%', '90%', '85%', '70%']
+  return (
+    <Box sx={styles.root}>
+      {Array.from({ length: lines }).map((_, i) => (
+        <Skeleton
+          key={`line-${i}`}
+          variant='rectangular'
+          sx={styles.line(widths[i % widths.length] ?? '85%')}
+        />
+      ))}
+    </Box>
+  )
+}

package/src/widgets-v2/markdown/style.ts

@@ -0,0 +1,53 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  root: {
+    color: 'text.primary',
+    '& a': { color: 'primary.main' },
+    '& code': {
+      bgcolor: 'action.hover',
+      px: 0.5,
+      borderRadius: 0.5,
+      fontFamily: 'monospace',
+      fontSize: '0.875em',
+    },
+    '& pre': {
+      bgcolor: 'action.hover',
+      p: 1.5,
+      borderRadius: 1,
+      overflowX: 'auto',
+    },
+    '& blockquote': {
+      borderLeft: '3px solid',
+      borderColor: 'divider',
+      pl: 1.5,
+      ml: 0,
+      color: 'text.secondary',
+      fontStyle: 'italic',
+    },
+    '& ul, & ol': { pl: 3, my: 1 },
+    '& li': { my: 0.25 },
+    '& hr': {
+      border: 'none',
+      borderTop: '1px solid',
+      borderColor: 'divider',
+      my: 1.5,
+    },
+    '& table': { borderCollapse: 'collapse', width: '100%' },
+    '& th, & td': {
+      border: '1px solid',
+      borderColor: 'divider',
+      px: 1,
+      py: 0.5,
+      textAlign: 'left',
+    },
+  },
+  paragraph: {
+    my: 1,
+  },
+  heading: {
+    mt: 2,
+    mb: 1,
+    fontWeight: 600,
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/widgets-v2/markdown/types.ts

@@ -0,0 +1,4 @@
+/** Markdown widget data — a single markdown source string. */
+export interface MarkdownWidgetData {
+  content: string
+}

package/src/widgets-v2/note/labels.ts

@@ -0,0 +1,9 @@
+export interface NoteLabels {
+  showMore: string
+  showLess: string
+}
+
+export const DEFAULT_NOTE_LABELS: NoteLabels = {
+  showMore: 'Show more',
+  showLess: 'Show less',
+}

package/src/widgets-v2/note/style.ts

@@ -0,0 +1,26 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  root: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 0.5,
+  },
+  text: {
+    color: 'text.secondary',
+    overflow: 'hidden',
+    overflowWrap: 'anywhere',
+  },
+  clamped: {
+    display: '-webkit-box',
+    WebkitBoxOrient: 'vertical',
+    WebkitLineClamp: 3,
+  },
+  toggle: {
+    alignSelf: 'flex-start',
+    color: 'primary.main',
+    fontWeight: 500,
+    cursor: 'pointer',
+    '&:hover': { textDecoration: 'underline' },
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/widgets-v2/note/widget-note.test.tsx

@@ -0,0 +1,158 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { Note } from './widget-note'
+
+beforeEach(() => {
+  // jsdom doesn't lay anything out, so scrollHeight / clientHeight default to
+  // 0 / 0 and the overflow detector won't fire by default. Each test that
+  // wants to exercise the overflow branch stubs these getters explicitly.
+})
+
+describe('<Note>', () => {
+  it('renders the children unclamped when no overflow is detected', () => {
+    render(<Note>Short text</Note>)
+    expect(screen.getByText('Short text')).toBeTruthy()
+    expect(screen.queryByText('Show more')).toBeNull()
+  })
+
+  it('shows the Show more toggle when content overflows', () => {
+    // Force scrollHeight > clientHeight on the typography element.
+    Object.defineProperty(HTMLElement.prototype, 'scrollHeight', {
+      configurable: true,
+      get: () => 200,
+    })
+    Object.defineProperty(HTMLElement.prototype, 'clientHeight', {
+      configurable: true,
+      get: () => 60,
+    })
+    render(<Note>{'a '.repeat(400)}</Note>)
+    expect(screen.getByText('Show more')).toBeTruthy()
+    fireEvent.click(screen.getByText('Show more'))
+    expect(screen.getByText('Show less')).toBeTruthy()
+  })
+
+  it('honors custom labels', () => {
+    Object.defineProperty(HTMLElement.prototype, 'scrollHeight', {
+      configurable: true,
+      get: () => 200,
+    })
+    Object.defineProperty(HTMLElement.prototype, 'clientHeight', {
+      configurable: true,
+      get: () => 60,
+    })
+    render(
+      <Note labels={{ showMore: 'Reveal', showLess: 'Hide' }}>long text</Note>,
+    )
+    expect(screen.getByText('Reveal')).toBeTruthy()
+    fireEvent.click(screen.getByText('Reveal'))
+    expect(screen.getByText('Hide')).toBeTruthy()
+  })
+
+  it('renders string children verbatim (no markdown parsing on base Note)', () => {
+    const { container } = render(<Note>{'This is **literal** text'}</Note>)
+    // Base Note no longer parses markdown — asterisks render verbatim.
+    expect(container.querySelector('strong')).toBeNull()
+    expect(screen.getByText('This is **literal** text')).toBeTruthy()
+  })
+
+  it('passes through JSX children verbatim', () => {
+    render(
+      <Note>
+        <span data-testid='raw'>**not parsed**</span>
+      </Note>,
+    )
+    // Asterisks should remain literal because the children are JSX.
+    expect(screen.getByTestId('raw').textContent).toBe('**not parsed**')
+  })
+
+  describe('lineClamp={0}', () => {
+    it('does not render the Show more toggle when content overflows', () => {
+      Object.defineProperty(HTMLElement.prototype, 'scrollHeight', {
+        configurable: true,
+        get: () => 200,
+      })
+      Object.defineProperty(HTMLElement.prototype, 'clientHeight', {
+        configurable: true,
+        get: () => 60,
+      })
+      render(<Note lineClamp={0}>{'a '.repeat(400)}</Note>)
+      expect(screen.queryByText('Show more')).toBeNull()
+      expect(screen.queryByText('Show less')).toBeNull()
+    })
+
+    it('does not apply line clamping styles', () => {
+      const { container } = render(
+        <Note lineClamp={0}>{'a '.repeat(400)}</Note>,
+      )
+      const textBox = container.querySelector('p')?.parentElement
+      const style = textBox ? window.getComputedStyle(textBox) : null
+      expect(style?.getPropertyValue('-webkit-line-clamp')).toBeFalsy()
+    })
+
+    it('default behavior (lineClamp omitted) still clamps and shows toggle on overflow', () => {
+      Object.defineProperty(HTMLElement.prototype, 'scrollHeight', {
+        configurable: true,
+        get: () => 200,
+      })
+      Object.defineProperty(HTMLElement.prototype, 'clientHeight', {
+        configurable: true,
+        get: () => 60,
+      })
+      render(<Note>{'a '.repeat(400)}</Note>)
+      expect(screen.getByText('Show more')).toBeTruthy()
+    })
+  })
+
+  it('does not throw when ResizeObserver is missing', () => {
+    const original = globalThis.ResizeObserver
+    // @ts-expect-error force-undefined for the duration of the test
+    delete globalThis.ResizeObserver
+    try {
+      // We don't expect anything specific to render — just that this doesn't crash.
+      expect(() => render(<Note>x</Note>)).not.toThrow()
+    } finally {
+      globalThis.ResizeObserver = original
+    }
+    void vi
+  })
+})
+
+describe('<Note.Markdown>', () => {
+  it('renders bold markdown from a content string', () => {
+    const { container } = render(
+      <Note.Markdown content='This is **important** info' />,
+    )
+    expect(container.querySelector('strong')?.textContent).toBe('important')
+  })
+
+  it('renders markdown links with secure target/rel defaults', () => {
+    const { container } = render(
+      <Note.Markdown content='See [docs](https://example.com)' />,
+    )
+    const link = container.querySelector('a')
+    expect(link?.getAttribute('href')).toBe('https://example.com')
+    expect(link?.getAttribute('target')).toBe('_blank')
+    expect(link?.getAttribute('rel')).toBe('noopener noreferrer')
+  })
+
+  it('strips images from markdown', () => {
+    const { container } = render(
+      <Note.Markdown content='caption text ![alt](https://example.com/x.png)' />,
+    )
+    expect(container.querySelector('img')).toBeNull()
+    expect(screen.getByText(/caption text/)).toBeTruthy()
+  })
+
+  it('clamps and shows the Show more toggle on overflow (same shell as base)', () => {
+    Object.defineProperty(HTMLElement.prototype, 'scrollHeight', {
+      configurable: true,
+      get: () => 200,
+    })
+    Object.defineProperty(HTMLElement.prototype, 'clientHeight', {
+      configurable: true,
+      get: () => 60,
+    })
+    render(<Note.Markdown content={'long content '.repeat(80)} />)
+    expect(screen.getByText('Show more')).toBeTruthy()
+  })
+})

package/src/widgets-v2/note/widget-note.tsx

@@ -0,0 +1,172 @@
+import { useCallback, useEffect, useRef, useState, type ReactNode } from 'react'
+import { Box, Link, Typography } from '@mui/material'
+import type { Components } from 'react-markdown'
+import { MarkdownContent } from '../markdown/markdown-content'
+import { observeResize } from '../echart/shared-resize-observer'
+import { DEFAULT_NOTE_LABELS, type NoteLabels } from './labels'
+import { styles } from './style'
+
+export interface NoteProps {
+  /**
+   * Maximum visible lines before clamping. Defaults to 3. Set to `0` to
+   * disable clamping entirely — full content renders and the Show More/Less
+   * toggle is never shown.
+   */
+  lineClamp?: number
+  labels?: Partial<NoteLabels>
+  /**
+   * Renders verbatim inside the caption shell. For markdown source (a
+   * string with `**bold**`, lists, links, etc.) reach for the
+   * `<Note.Markdown>` subcomponent instead — it pipes the string through
+   * the shared {@link MarkdownContent} engine with caption-safe element
+   * mapping.
+   */
+  children: ReactNode
+}
+
+export interface NoteMarkdownProps {
+  /** Markdown source. Rendered with caption typography via {@link MarkdownContent}. */
+  content: string
+  /** Maximum visible lines before clamping. Defaults to 3. */
+  lineClamp?: number
+  labels?: Partial<NoteLabels>
+}
+
+/** Block element used for every Markdown paragraph and demoted heading so
+ *  Notes share a single caption look and never inject heading levels into
+ *  the document outline. */
+function CaptionBlock({ children }: { children?: ReactNode }) {
+  return (
+    <Typography variant='caption' component='p' color='inherit' sx={{ m: 0 }}>
+      {children}
+    </Typography>
+  )
+}
+
+const NOTE_COMPONENTS: Components = {
+  // Headings demoted to caption typography — a Note can't introduce a
+  // heading into the page outline.
+  h1: CaptionBlock,
+  h2: CaptionBlock,
+  h3: CaptionBlock,
+  h4: CaptionBlock,
+  h5: CaptionBlock,
+  h6: CaptionBlock,
+  p: CaptionBlock,
+  // External-safe link defaults; inherit colour from the muted caption.
+  a: ({ children, href }) => (
+    <Link
+      href={href}
+      target='_blank'
+      rel='noopener noreferrer'
+      color='inherit'
+      underline='always'
+    >
+      {children}
+    </Link>
+  ),
+}
+
+/**
+ * Auxiliary slot for an optional explanatory note below a widget. Clamps to
+ * `lineClamp` lines (default 3) and reveals a Show More/Less toggle when the
+ * content overflows. Overflow detection re-runs on container resize via the
+ * shared singleton ResizeObserver.
+ *
+ * Renders `children` verbatim through caption typography. For markdown
+ * source, use the {@link NoteMarkdown} (`Note.Markdown`) subcomponent.
+ */
+function NoteBase({ lineClamp = 3, labels, children }: NoteProps) {
+  return (
+    <NoteShell lineClamp={lineClamp} labels={labels} dependency={children}>
+      <Typography variant='caption' component='div' color='inherit'>
+        {children}
+      </Typography>
+    </NoteShell>
+  )
+}
+
+/**
+ * Markdown variant of {@link Note}. Pipes the `content` string through the
+ * shared {@link MarkdownContent} engine with caption-safe element mapping
+ * (headings demoted, links open in new tabs, images/HTML stripped).
+ */
+function NoteMarkdown({ content, lineClamp = 3, labels }: NoteMarkdownProps) {
+  return (
+    <NoteShell lineClamp={lineClamp} labels={labels} dependency={content}>
+      <MarkdownContent content={content} components={NOTE_COMPONENTS} />
+    </NoteShell>
+  )
+}
+
+// Public namespace export. Consumers reach the markdown variant via
+// `<Widget.Note.Markdown>{content}</Widget.Note.Markdown>`.
+export const Note = Object.assign(NoteBase, { Markdown: NoteMarkdown })
+
+interface NoteShellProps {
+  lineClamp: number
+  labels: Partial<NoteLabels> | undefined
+  /** Used to re-measure overflow when the underlying content changes. */
+  dependency: unknown
+  children: ReactNode
+}
+
+/**
+ * Shared shell: caption box + clamping + Show More/Less toggle. Both the
+ * verbatim `Note` and the markdown `Note.Markdown` reach for this so the
+ * overflow + measurement behaviour stays identical across variants.
+ */
+function NoteShell({
+  lineClamp,
+  labels,
+  dependency,
+  children,
+}: NoteShellProps) {
+  const _labels = { ...DEFAULT_NOTE_LABELS, ...labels }
+  const textRef = useRef<HTMLDivElement | null>(null)
+  const [isOverflowing, setIsOverflowing] = useState(false)
+  const [expanded, setExpanded] = useState(false)
+  const clampingDisabled = lineClamp <= 0
+
+  const measure = useCallback(() => {
+    const node = textRef.current
+    if (!node) return
+    setIsOverflowing(node.scrollHeight > node.clientHeight + 1)
+  }, [])
+
+  useEffect(() => {
+    if (clampingDisabled) return undefined
+    const node = textRef.current
+    if (!node) return undefined
+    measure()
+    return observeResize(node, measure)
+  }, [measure, dependency, clampingDisabled])
+
+  const toggle = useCallback(() => setExpanded((v) => !v), [])
+  const clamped = !expanded && !clampingDisabled
+  const lineClampSx = clamped
+    ? { ...styles.clamped, WebkitLineClamp: lineClamp }
+    : null
+
+  return (
+    <Box sx={styles.root}>
+      <Box ref={textRef} sx={{ ...styles.text, ...(lineClampSx ?? {}) }}>
+        {children}
+      </Box>
+      {/* Stay visible while the user is in the expanded state so they always
+          have a way back. Without `|| expanded` the toggle would vanish the
+          moment content unclamps (scrollHeight === clientHeight). Matches v1. */}
+      {!clampingDisabled && (isOverflowing || expanded) && (
+        <Link
+          component='button'
+          variant='caption'
+          underline='none'
+          onClick={toggle}
+          sx={styles.toggle}
+        >
+          {expanded ? _labels.showLess : _labels.showMore}
+        </Link>
+      )}
+    </Box>
+  )
+}

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

@@ -0,0 +1,78 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { createPieDownloadConfig } from './download'
+import type { PieWidgetData } from './types'
+
+const single: PieWidgetData = [
+  [
+    { name: 'a', value: 1 },
+    { name: 'b', value: 2 },
+  ],
+]
+const multi: PieWidgetData = [
+  [{ name: 'a', value: 1 }],
+  [{ name: 'c', value: 3 }],
+]
+
+let csvText = ''
+
+let revokeSpy: ReturnType<typeof vi.spyOn>
+
+beforeEach(() => {
+  csvText = ''
+  vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:mock')
+  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('createPieDownloadConfig', () => {
+  it('returns CSV-only items by default', () => {
+    const items = createPieDownloadConfig({
+      filename: 'p',
+      getData: () => single,
+    })
+    expect(items.map((i) => i.id)).toEqual(['csv'])
+  })
+
+  it('prepends PNG when getCaptureEl provided and rejects when null', async () => {
+    const items = createPieDownloadConfig({
+      filename: 'p',
+      getData: () => single,
+      getCaptureEl: () => null,
+    })
+    expect(items.map((i) => i.id)).toEqual(['png', 'csv'])
+    await expect(items[0]!.resolve()).rejects.toThrow(/No PNG capture element/)
+  })
+
+  it('CSV resolve uses default series_<n> when seriesNames is absent', async () => {
+    const items = createPieDownloadConfig({
+      filename: 'p',
+      getData: () => multi,
+    })
+    const handle = await items.find((i) => i.id === 'csv')!.resolve()
+    expect(handle.filename).toBe('p.csv')
+    expect(csvText).toBe('series,name,value\nseries_1,a,1\nseries_2,c,3')
+    handle.revoke?.()
+    expect(revokeSpy).toHaveBeenCalled()
+  })
+
+  it('CSV resolve uses provided seriesNames when supplied', async () => {
+    const items = createPieDownloadConfig({
+      filename: 'p',
+      getData: () => multi,
+      seriesNames: ['alpha', 'beta'],
+    })
+    await items.find((i) => i.id === 'csv')!.resolve()
+    expect(csvText).toBe('series,name,value\nalpha,a,1\nbeta,c,3')
+  })
+})

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

@@ -0,0 +1,55 @@
+import {
+  buildPngDownloadItem,
+  downloadToCSV,
+  type DownloadItem,
+} from '../actions/download'
+import type { PieWidgetData } from './types'
+
+/**
+ * Download menu items for the Pie widget. Always includes a CSV item with
+ * `series, name, value` columns (one row per slice; series labels come from
+ * `seriesNames` if provided, else `series_<n>`). When `getCaptureEl` is
+ * supplied, prepends a PNG item that rasterises the captured element via
+ * `html2canvas`.
+ */
+export function createPieDownloadConfig(args: {
+  filename: string
+  getData: () => PieWidgetData
+  seriesNames?: readonly string[]
+  getCaptureEl?: () => HTMLElement | null
+  pngPixelRatio?: number
+  pngBackgroundColor?: string | null
+}): DownloadItem[] {
+  const items: DownloadItem[] = []
+  if (args.getCaptureEl) {
+    items.push(
+      buildPngDownloadItem({
+        filename: args.filename,
+        getCaptureEl: args.getCaptureEl,
+        pixelRatio: args.pngPixelRatio,
+        backgroundColor: args.pngBackgroundColor,
+      }),
+    )
+  }
+  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 slice of series) {
+          rows.push([seriesName, slice.name, slice.value])
+        }
+      }
+      const handle = downloadToCSV(rows)
+      return Promise.resolve({
+        url: handle.url,
+        filename: `${args.filename}.csv`,
+        revoke: handle.revoke,
+      })
+    },
+  })
+  return items
+}

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

@@ -0,0 +1,10 @@
+export { pieOptions, createPieOptionFactory } from './options'
+export { PieSkeleton, type PieSkeletonProps } from './skeleton'
+export { createPieDownloadConfig } from './download'
+export type {
+  PieDatum,
+  PieWidgetData,
+  PieOptionsInput,
+  PieOptionFactoryInput,
+  PieEChartsOption,
+} from './types'