@carto/ps-react-ui 4.7.0 → 4.8.0

package/src/widgets-v2/index.ts

@@ -0,0 +1,201 @@
+// ─── Internal imports (used to assemble the curated `Widget` const) ─────────
+import { Provider } from './provider/widget-provider'
+import {
+  Wrapper,
+  Actions,
+  Options,
+  Content,
+  Footer,
+  DEFAULT_WRAPPER_LABELS,
+} from './wrapper'
+import { Subheader } from './subheader/subheader'
+import { State } from './state/widget-state'
+import { DEFAULT_STATE_LABELS } from './state/labels'
+import { SelectionSummary } from './selection-summary/selection-summary'
+import { DEFAULT_SELECTION_SUMMARY_LABELS } from './selection-summary/labels'
+import { Toolbox } from './toolbox/toolbox'
+import { DEFAULT_TOOLBOX_LABELS } from './toolbox/labels'
+import { Echart, EchartUI, DEFAULT_INIT_OPTS } from './echart'
+import { Note } from './note/widget-note'
+import { DEFAULT_NOTE_LABELS } from './note/labels'
+import {
+  Searcher,
+  SearcherToggle,
+  StackToggle,
+  ZoomToggle,
+  BrushToggle,
+  RelativeData,
+  Download,
+  FullScreen,
+  LockSelection,
+  ChangeColumn,
+} from './actions'
+import { Formula, FormulaUI } from './formula'
+import { Markdown, MarkdownUI } from './markdown'
+import { Spread, SpreadUI } from './spread'
+import { Range, RangeUI } from './range'
+import { Category, CategoryUI } from './category'
+import { Table, TableUI } from './table'
+
+/**
+ * Curated namespace export — the only way to reach v2 widget components.
+ * Consumers import the const and access components via property access:
+ *
+ * ```tsx
+ * import { Widget } from '@carto/ps-react-ui/widgets-v2'
+ *
+ * <Widget.Provider id={id} data={data}>
+ *   <Widget.Wrapper title='Sales'>
+ *     <Widget.Content>
+ *       <Widget.State skeleton={<BarSkeleton />}>
+ *         <Widget.Echart optionFactory={optionFactory} />
+ *       </Widget.State>
+ *     </Widget.Content>
+ *   </Widget.Wrapper>
+ * </Widget.Provider>
+ * ```
+ *
+ * Component identifiers are not surfaced as separate named exports — Types
+ * (props, data shapes, label types, default-label consts) and per-widget
+ * subpath entries (`@carto/ps-react-ui/widgets-v2/bar`, `…/category`,
+ * `…/table`, `…/actions`, `…/stores`, `…/utils`, etc.) remain available for
+ * direct import where needed.
+ */
+export const Widget = {
+  // Composition shell
+  Provider,
+  Wrapper,
+  Actions,
+  Options,
+  Content,
+  Footer,
+  Subheader,
+  State,
+  SelectionSummary,
+  Toolbox,
+  Note,
+
+  // ECharts bridge
+  Echart,
+  EchartUI,
+
+  // Actions
+  Searcher,
+  SearcherToggle,
+  StackToggle,
+  ZoomToggle,
+  BrushToggle,
+  RelativeData,
+  Download,
+  FullScreen,
+  LockSelection,
+  ChangeColumn,
+
+  // Widget primitives (renderer bridges + pure UI). Pre-composed widget
+  // modules (Bar, FormulaWidget, TableWidget, etc.) are application-level
+  // compositions of these primitives and live outside the library —
+  // see `apps/storybook/stories/modules/widgets/` for canonical examples.
+  Formula,
+  FormulaUI,
+  Markdown,
+  MarkdownUI,
+  Spread,
+  SpreadUI,
+  Range,
+  RangeUI,
+  Category,
+  CategoryUI,
+  Table,
+  TableUI,
+} as const
+
+// ─── Default-label consts ──────────────────────────────────────────────────
+// Exported separately so consumers can build customized label sets via spread.
+export {
+  DEFAULT_WRAPPER_LABELS,
+  DEFAULT_STATE_LABELS,
+  DEFAULT_SELECTION_SUMMARY_LABELS,
+  DEFAULT_TOOLBOX_LABELS,
+  DEFAULT_NOTE_LABELS,
+  DEFAULT_INIT_OPTS,
+}
+
+// ─── Types ─────────────────────────────────────────────────────────────────
+// Types are erased at runtime so they can't live on the `Widget` const.
+// They are re-exported here for direct import by consumers.
+
+export type { ProviderProps } from './provider/widget-provider'
+export type {
+  WrapperProps,
+  ActionsProps,
+  OptionsProps,
+  ContentProps,
+  FooterProps,
+  WrapperLabels,
+} from './wrapper'
+export type { SubheaderProps } from './subheader/subheader'
+export type { StateProps } from './state/widget-state'
+export type { StateLabels } from './state/labels'
+export type { SelectionSummaryProps } from './selection-summary/selection-summary'
+export type { SelectionSummaryLabels } from './selection-summary/labels'
+export type { ToolboxProps } from './toolbox/toolbox'
+export type { ToolboxLabels } from './toolbox/labels'
+export type { EchartProps, EchartUIProps, EchartsEventHandler } from './echart'
+export type { NoteProps, NoteMarkdownProps } from './note/widget-note'
+export type { NoteLabels } from './note/labels'
+
+// Action types
+export type {
+  SearcherProps,
+  SearcherToggleProps,
+  StackToggleProps,
+  ZoomToggleProps,
+  BrushToggleProps,
+  RelativeDataProps,
+  DownloadProps,
+  DownloadItem,
+  FullScreenTriggerProps,
+  FullScreenSlotProps,
+  LockSelectionProps,
+  LockSelectionKey,
+  ChangeColumnProps,
+  ChangeColumnItem,
+} from './actions'
+
+// Widget primitive types
+export type {
+  FormulaUIProps,
+  FormulaDataItem,
+  FormulaWidgetData,
+} from './formula'
+export type { MarkdownUIProps, MarkdownWidgetData } from './markdown'
+export type { PieDatum, PieWidgetData } from './pie'
+export type { TimeseriesDatum, TimeseriesWidgetData } from './timeseries'
+export type { ScatterplotDatum, ScatterplotWidgetData } from './scatterplot'
+export type { SpreadUIProps, SpreadDataItem, SpreadWidgetData } from './spread'
+export type {
+  RangeProps,
+  RangeUIProps,
+  RangeDataItem,
+  RangeWidgetData,
+  RangeItemValue,
+} from './range'
+export type {
+  CategoryProps,
+  CategoryUIProps,
+  CategoryDataItem,
+  CategoryWidgetData,
+  CategoryKey,
+  CategorySeriesConfig,
+  CategoryLabels,
+} from './category'
+export type {
+  TableProps,
+  TableUIProps,
+  TableColumn,
+  TableRow,
+  TableWidgetData,
+  TableWidgetState,
+  TableSortDirection,
+  TableSortState,
+} from './table'

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

@@ -0,0 +1,66 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { createMarkdownDownloadConfig } from './download'
+
+let mdText = ''
+
+let revokeSpy: ReturnType<typeof vi.spyOn>
+
+beforeEach(() => {
+  mdText = ''
+  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) {
+        mdText = typeof parts[0] === 'string' ? parts[0] : ''
+        super(parts, opts)
+      }
+    },
+  )
+})
+
+describe('createMarkdownDownloadConfig', () => {
+  it('returns a single .md item by default', () => {
+    const items = createMarkdownDownloadConfig({
+      filename: 'doc',
+      getData: () => ({ content: '# hi' }),
+    })
+    expect(items.map((i) => i.id)).toEqual(['md'])
+  })
+
+  it('prepends PNG when getCaptureEl is provided', () => {
+    const items = createMarkdownDownloadConfig({
+      filename: 'doc',
+      getData: () => ({ content: '' }),
+      getCaptureEl: () => document.createElement('div'),
+    })
+    expect(items.map((i) => i.id)).toEqual(['png', 'md'])
+  })
+
+  it('md resolve writes the source verbatim with a .md filename', async () => {
+    const items = createMarkdownDownloadConfig({
+      filename: 'doc',
+      getData: () => ({ content: '# title\n\nbody' }),
+    })
+    const handle = await items.find((i) => i.id === 'md')!.resolve()
+    expect(handle.url).toBe('blob:mock')
+    expect(handle.filename).toBe('doc.md')
+    expect(mdText).toBe('# title\n\nbody')
+    handle.revoke?.()
+    expect(revokeSpy).toHaveBeenCalledWith('blob:mock')
+  })
+
+  it('md resolve falls back to empty content when data.content is missing', async () => {
+    const items = createMarkdownDownloadConfig({
+      filename: 'doc',
+      // missing content field — exercise the `?? ''` branch
+      getData: () => ({}) as { content: string },
+    })
+    await items.find((i) => i.id === 'md')!.resolve()
+    expect(mdText).toBe('')
+  })
+})

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

@@ -0,0 +1,53 @@
+import {
+  buildPngDownloadItem,
+  toCsvString,
+  triggerLinkDownload,
+  type DownloadItem,
+} from '../actions/download'
+import type { MarkdownWidgetData } from './types'
+
+/**
+ * Download menu items for the Markdown widget. Always includes a `.md`
+ * item that saves the markdown source verbatim. When `getCaptureEl` is
+ * supplied, prepends a PNG item that rasterises the captured element via
+ * `html2canvas`.
+ */
+export function createMarkdownDownloadConfig(args: {
+  filename: string
+  getData: () => MarkdownWidgetData
+  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: 'md',
+    label: 'Download as Markdown',
+    resolve: () => {
+      const data = args.getData()
+      const blob = new Blob([data.content ?? ''], {
+        type: 'text/markdown;charset=utf-8;',
+      })
+      const url = URL.createObjectURL(blob)
+      return Promise.resolve({
+        url,
+        filename: `${args.filename}.md`,
+        revoke: () => URL.revokeObjectURL(url),
+      })
+    },
+  })
+  return items
+}
+
+// Re-export pure helpers consumers may want when building a custom Download item.
+export { toCsvString, triggerLinkDownload }

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

@@ -0,0 +1,6 @@
+export { Markdown } from './markdown'
+export { MarkdownUI, type MarkdownUIProps } from './markdown-ui'
+export { MarkdownContent, type MarkdownContentProps } from './markdown-content'
+export { MarkdownSkeleton, type MarkdownSkeletonProps } from './skeleton'
+export { createMarkdownDownloadConfig } from './download'
+export type { MarkdownWidgetData } from './types'

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

@@ -0,0 +1,155 @@
+import { describe, it, expect } from 'vitest'
+import { render } from '@testing-library/react'
+import { MarkdownContent } from './markdown-content'
+
+describe('<MarkdownContent>', () => {
+  it('renders markdown with the safe defaults (no html, no images)', () => {
+    const { container } = render(
+      <MarkdownContent
+        content={
+          '# Title\n\n![alt](https://example.com/img.png)\n\n<span>raw</span>'
+        }
+      />,
+    )
+    // Image must NOT render — disallowedElements blocks it.
+    expect(container.querySelector('img')).toBeNull()
+    // Raw HTML escapes to text — span never gets parsed as an element.
+    expect(container.querySelector('span')).toBeNull()
+    // Heading still renders normally.
+    expect(container.textContent).toContain('Title')
+  })
+
+  it('renders images when allowImages=true', () => {
+    const { container } = render(
+      <MarkdownContent
+        content={'![alt](https://example.com/img.png)'}
+        allowImages
+      />,
+    )
+    const img = container.querySelector('img')
+    expect(img).not.toBeNull()
+    expect(img?.getAttribute('alt')).toBe('alt')
+  })
+
+  it('parses raw HTML when allowHtml=true', () => {
+    const { container } = render(
+      <MarkdownContent content={'<span>raw <em>html</em></span>'} allowHtml />,
+    )
+    // Both inline tags survive sanitization; the text content is preserved.
+    expect(container.querySelector('span')).not.toBeNull()
+    expect(container.querySelector('em')?.textContent).toBe('html')
+    expect(container.textContent).toContain('raw html')
+  })
+
+  describe('XSS hardening', () => {
+    it('drops <script> tags when allowHtml=true', () => {
+      const { container } = render(
+        <MarkdownContent
+          content={'<script>window.__xss=true</script>safe'}
+          allowHtml
+          allowImages
+        />,
+      )
+      expect(container.querySelector('script')).toBeNull()
+      expect(container.textContent).toContain('safe')
+    })
+
+    it('strips event handlers from <img>', () => {
+      const { container } = render(
+        <MarkdownContent
+          content={'<img src="https://example.com/x.png" onerror="alert(1)">'}
+          allowHtml
+          allowImages
+        />,
+      )
+      const img = container.querySelector('img')
+      expect(img).not.toBeNull()
+      expect(img?.getAttribute('onerror')).toBeNull()
+    })
+
+    it('drops <iframe> with srcdoc', () => {
+      const { container } = render(
+        <MarkdownContent
+          content={'<iframe srcdoc="<script>alert(1)</script>"></iframe>'}
+          allowHtml
+          allowImages
+        />,
+      )
+      expect(container.querySelector('iframe')).toBeNull()
+    })
+
+    it('drops <svg> with onload', () => {
+      const { container } = render(
+        <MarkdownContent
+          content={'<svg onload="alert(1)"><circle cx="5" cy="5" r="4"/></svg>'}
+          allowHtml
+          allowImages
+        />,
+      )
+      const svg = container.querySelector('svg')
+      // defaultSchema doesn't allowlist <svg>, so the element should be gone.
+      // Even if a future schema variant allows it, `onload` must not survive.
+      expect(svg?.getAttribute('onload') ?? null).toBeNull()
+    })
+
+    it('drops <base> tags that could rewrite relative URLs', () => {
+      const { container } = render(
+        <MarkdownContent
+          content={'<base href="https://attacker.example/">link'}
+          allowHtml
+        />,
+      )
+      expect(container.querySelector('base')).toBeNull()
+    })
+
+    it('strips href for javascript: URLs in markdown links', () => {
+      const { container } = render(
+        <MarkdownContent content={'[click](javascript:alert(1))'} />,
+      )
+      const a = container.querySelector('a')
+      // Either the anchor renders without `href` or with empty `href` — both
+      // are safe (no navigation). Concretely we assert no `javascript:` value.
+      expect(a?.getAttribute('href') ?? '').not.toMatch(/^javascript:/i)
+    })
+
+    it('strips href for data: URLs in markdown links (Note path)', () => {
+      const { container } = render(
+        <MarkdownContent
+          content={'[click](data:text/html,<script>alert(1)</script>)'}
+        />,
+      )
+      const a = container.querySelector('a')
+      expect(a?.getAttribute('href') ?? '').not.toMatch(/^data:/i)
+    })
+
+    it('strips data: URLs from <img src> on the rich path', () => {
+      const { container } = render(
+        <MarkdownContent
+          content={'![alt](data:image/svg+xml,<svg onload=alert(1)/>)'}
+          allowImages
+        />,
+      )
+      const img = container.querySelector('img')
+      expect(img?.getAttribute('src') ?? '').not.toMatch(/^data:/i)
+    })
+
+    it('preserves safe URLs (https, mailto, relative)', () => {
+      const { container } = render(
+        <MarkdownContent
+          content={
+            '[ext](https://example.com) [mail](mailto:a@b.co) [rel](./page) [hash](#x)'
+          }
+        />,
+      )
+      const links = Array.from(container.querySelectorAll('a')).map((a) =>
+        a.getAttribute('href'),
+      )
+      expect(links).toEqual([
+        'https://example.com',
+        'mailto:a@b.co',
+        './page',
+        '#x',
+      ])
+    })
+  })
+})

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

@@ -0,0 +1,72 @@
+import ReactMarkdown, { type Components } from 'react-markdown'
+import rehypeRaw from 'rehype-raw'
+import rehypeSanitize from 'rehype-sanitize'
+
+export interface MarkdownContentProps {
+  /** Markdown source. */
+  content: string
+  /**
+   * Element overrides. Consumers (`MarkdownUI`, `Note`, …) supply their own
+   * typography / link styling here; the engine itself stays opinion-free.
+   */
+  components?: Components
+  /**
+   * When `true`, raw HTML in the source is rendered. Defaults to `false` so
+   * caption slots like `Note` stay safe-by-default; the document-style
+   * Markdown widget opts in.
+   */
+  allowHtml?: boolean
+  /**
+   * When `true`, `<img>` / `![alt](url)` markdown produces an `<img>` tag.
+   * Defaults to `false` so caption slots stay text-only by default.
+   */
+  allowImages?: boolean
+}
+
+// Allowlist of URL schemes considered safe for `<a href>` and `<img src>`.
+// Anything outside this set (e.g. `data:`, `javascript:`, `vbscript:`) is
+// stripped by `safeUrlTransform`. Belt-and-braces with `rehype-sanitize`'s
+// `defaultSchema` (which already restricts protocols when raw HTML is parsed)
+// — this layer also covers the `allowHtml=false` path, where the sanitizer
+// doesn't run but `react-markdown`'s default `urlTransform` only blocks
+// `javascript:`.
+const SAFE_URL_PREFIX = /^(https?:|mailto:|tel:|#|\/|\.\/|\.\.\/)/i
+
+function safeUrlTransform(url: string): string {
+  const trimmed = (url ?? '').trim()
+  if (!trimmed) return ''
+  if (SAFE_URL_PREFIX.test(trimmed)) return url
+  return ''
+}
+
+/**
+ * Low-level Markdown rendering primitive. Wraps `react-markdown` with two
+ * opt-in capabilities (`allowHtml`, `allowImages`) and a consumer-supplied
+ * component map for typography. Both default OFF — Note-style consumers
+ * are safe-by-default; MarkdownUI opts both ON to render rich content.
+ *
+ * `allowHtml` plugs in `rehype-raw` so raw HTML nodes in the source are
+ * actually parsed, then `rehype-sanitize` with the default schema strips
+ * `<script>`, event handlers, and dangerous URL schemes from the parsed
+ * tree. `safeUrlTransform` is always applied as a second layer for markdown
+ * links/images on the `allowHtml=false` path.
+ */
+export function MarkdownContent({
+  content,
+  components,
+  allowHtml = false,
+  allowImages = false,
+}: MarkdownContentProps) {
+  const disallowed = allowImages ? undefined : ['img']
+  return (
+    <ReactMarkdown
+      components={components}
+      disallowedElements={disallowed}
+      skipHtml={!allowHtml}
+      rehypePlugins={allowHtml ? [rehypeRaw, rehypeSanitize] : undefined}
+      urlTransform={safeUrlTransform}
+    >
+      {content}
+    </ReactMarkdown>
+  )
+}

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

@@ -0,0 +1,75 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { MarkdownUI } from './markdown-ui'
+
+describe('<MarkdownUI>', () => {
+  it('renders headings, paragraphs, and inline emphasis', () => {
+    render(
+      <MarkdownUI
+        content={'# Title\n\nSome **bold** text and _italic_ text.'}
+      />,
+    )
+    expect(screen.getByText('Title')).toBeTruthy()
+    expect(screen.getByText('bold')).toBeTruthy()
+    expect(screen.getByText('italic')).toBeTruthy()
+  })
+
+  it('renders lists', () => {
+    render(<MarkdownUI content={'- one\n- two\n- three'} />)
+    expect(screen.getByText('one')).toBeTruthy()
+    expect(screen.getByText('two')).toBeTruthy()
+    expect(screen.getByText('three')).toBeTruthy()
+  })
+
+  it('renders links', () => {
+    render(<MarkdownUI content={'[CARTO](https://carto.com)'} />)
+    const link = screen.getByRole('link', { name: 'CARTO' })
+    expect(link.getAttribute('href')).toBe('https://carto.com')
+  })
+
+  it('renders inline images', () => {
+    const { container } = render(
+      <MarkdownUI
+        content={'![alt text](https://example.com/img.png)\n\nplain text'}
+      />,
+    )
+    const img = container.querySelector('img')
+    expect(img).not.toBeNull()
+    expect(img?.getAttribute('src')).toBe('https://example.com/img.png')
+    expect(img?.getAttribute('alt')).toBe('alt text')
+    expect(screen.getByText('plain text')).toBeTruthy()
+  })
+
+  it('renders raw HTML', () => {
+    const { container } = render(
+      <MarkdownUI
+        content={'<span>inline <em>html</em></span>\n\nplain text'}
+      />,
+    )
+    // Sanitizer keeps safe inline tags; only `data-*` attrs are stripped.
+    expect(container.querySelector('span')).not.toBeNull()
+    expect(container.querySelector('em')?.textContent).toBe('html')
+    expect(container.textContent).toContain('inline html')
+    expect(screen.getByText('plain text')).toBeTruthy()
+  })
+
+  it('renders empty content without errors', () => {
+    const { container } = render(<MarkdownUI content='' />)
+    // Root box exists, but no markdown elements inside.
+    expect(container.querySelector('p, h1, h2, h3')).toBeNull()
+  })
+
+  it('maps every heading level (h1–h6) through MUI Typography', () => {
+    const { getByText } = render(
+      <MarkdownUI
+        content={'# H1\n\n## H2\n\n### H3\n\n#### H4\n\n##### H5\n\n###### H6'}
+      />,
+    )
+    expect(getByText('H1')).toBeTruthy()
+    expect(getByText('H2')).toBeTruthy()
+    expect(getByText('H3')).toBeTruthy()
+    expect(getByText('H4')).toBeTruthy()
+    expect(getByText('H5')).toBeTruthy()
+    expect(getByText('H6')).toBeTruthy()
+  })
+})

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

@@ -0,0 +1,55 @@
+import { Box, Typography, type TypographyProps } from '@mui/material'
+import type { Components } from 'react-markdown'
+import { MarkdownContent } from './markdown-content'
+import { styles } from './style'
+
+export interface MarkdownUIProps {
+  content: string
+}
+
+/** MUI-styled element mapping for `react-markdown`. */
+const components: Components = {
+  h1: (props) => mdHeading(props, 'h4'),
+  h2: (props) => mdHeading(props, 'h5'),
+  h3: (props) => mdHeading(props, 'h6'),
+  h4: (props) => mdHeading(props, 'subtitle1'),
+  h5: (props) => mdHeading(props, 'subtitle2'),
+  h6: (props) => mdHeading(props, 'subtitle2'),
+  p: ({ children }) => (
+    <Typography variant='body2' component='p' sx={styles.paragraph}>
+      {children}
+    </Typography>
+  ),
+}
+
+function mdHeading(
+  props: { children?: React.ReactNode },
+  variant: TypographyProps['variant'],
+) {
+  return (
+    <Typography variant={variant} component='div' sx={styles.heading}>
+      {props.children}
+    </Typography>
+  )
+}
+
+/**
+ * Pure presentational component for the Markdown widget. Delegates the
+ * `react-markdown` engine to {@link MarkdownContent} and supplies a
+ * document-style MUI element mapping (body2 paragraphs, real heading
+ * typography). Opts INTO raw HTML and inline images — the Markdown widget is
+ * the one slot in the library where authors can ship rich content. Caption
+ * slots like `Note` keep the conservative defaults.
+ */
+export function MarkdownUI({ content }: MarkdownUIProps) {
+  return (
+    <Box sx={styles.root}>
+      <MarkdownContent
+        content={content}
+        components={components}
+        allowHtml
+        allowImages
+      />
+    </Box>
+  )
+}