@carto/ps-react-ui 5.0.0 → 6.0.0

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

@@ -1,341 +1,75 @@
-import { describe, test, expect } from 'vitest'
+import { describe, it, expect } from 'vitest'
 import { render, screen } from '@testing-library/react'
 import { MarkdownUI } from './markdown-ui'
 
-describe('MarkdownUI', () => {
-  test('renders plain text without markdown', () => {
-    render(<MarkdownUI>Plain text content</MarkdownUI>)
-    expect(screen.getByText('Plain text content')).toBeTruthy()
-  })
-
-  test('renders empty string', () => {
-    const { container } = render(<MarkdownUI>{''}</MarkdownUI>)
-    expect(container).toBeTruthy()
-  })
-
-  test('renders h1 as Typography variant h4', () => {
-    render(<MarkdownUI># Heading 1</MarkdownUI>)
-    const heading = screen.getByText('Heading 1')
-    expect(heading.tagName).toBe('H4')
-  })
-
-  test('renders h2 as Typography variant h5', () => {
-    render(<MarkdownUI>## Heading 2</MarkdownUI>)
-    const heading = screen.getByText('Heading 2')
-    expect(heading.tagName).toBe('H5')
-  })
-
-  test('renders h3 as Typography variant h6', () => {
-    render(<MarkdownUI>### Heading 3</MarkdownUI>)
-    const heading = screen.getByText('Heading 3')
-    expect(heading.tagName).toBe('H6')
-  })
-
-  test('renders multiple headings of different levels', () => {
+describe('<MarkdownUI>', () => {
+  it('renders headings, paragraphs, and inline emphasis', () => {
     render(
-      <MarkdownUI>
-        {`# H1 Heading
-## H2 Heading
-### H3 Heading`}
-      </MarkdownUI>,
+      <MarkdownUI
+        content={'# Title\n\nSome **bold** text and _italic_ text.'}
+      />,
     )
-    expect(screen.getByText('H1 Heading')).toBeTruthy()
-    expect(screen.getByText('H2 Heading')).toBeTruthy()
-    expect(screen.getByText('H3 Heading')).toBeTruthy()
-  })
-
-  test('renders paragraph as Typography', () => {
-    render(<MarkdownUI>This is a paragraph.</MarkdownUI>)
-    expect(screen.getByText('This is a paragraph.')).toBeTruthy()
-  })
-
-  test('renders multiple paragraphs', () => {
-    render(
-      <MarkdownUI>
-        {`First paragraph.
-
-Second paragraph.
-
-Third paragraph.`}
-      </MarkdownUI>,
-    )
-    expect(screen.getByText('First paragraph.')).toBeTruthy()
-    expect(screen.getByText('Second paragraph.')).toBeTruthy()
-    expect(screen.getByText('Third paragraph.')).toBeTruthy()
-  })
-
-  test('renders link with href attribute', () => {
-    render(<MarkdownUI>[Link text](https://example.com)</MarkdownUI>)
-    const link = screen.getByText('Link text')
-    expect(link.tagName).toBe('A')
-    expect(link.getAttribute('href')).toBe('https://example.com')
-  })
-
-  test('renders link with target="_blank" by default', () => {
-    render(<MarkdownUI>[External link](https://example.com)</MarkdownUI>)
-    const link = screen.getByText('External link')
-    expect(link.getAttribute('target')).toBe('_blank')
-  })
-
-  test('renders link with rel="noopener noreferrer" by default', () => {
-    render(<MarkdownUI>[Secure link](https://example.com)</MarkdownUI>)
-    const link = screen.getByText('Secure link')
-    expect(link.getAttribute('rel')).toBe('noopener noreferrer')
-  })
-
-  test('renders multiple links', () => {
-    render(
-      <MarkdownUI>
-        [Link 1](https://example1.com) and [Link 2](https://example2.com)
-      </MarkdownUI>,
-    )
-    expect(screen.getByText('Link 1')).toBeTruthy()
-    expect(screen.getByText('Link 2')).toBeTruthy()
-  })
-
-  test('renders unordered list', () => {
-    render(
-      <MarkdownUI>
-        {`- Item 1
-- Item 2
-- Item 3`}
-      </MarkdownUI>,
-    )
-    expect(screen.getByText('Item 1')).toBeTruthy()
-    expect(screen.getByText('Item 2')).toBeTruthy()
-    expect(screen.getByText('Item 3')).toBeTruthy()
-  })
-
-  test('renders ordered list', () => {
-    render(
-      <MarkdownUI>
-        {`1. First item
-2. Second item
-3. Third item`}
-      </MarkdownUI>,
-    )
-    expect(screen.getByText('First item')).toBeTruthy()
-    expect(screen.getByText('Second item')).toBeTruthy()
-    expect(screen.getByText('Third item')).toBeTruthy()
-  })
-
-  test('renders nested lists', () => {
-    render(
-      <MarkdownUI>
-        {`- Parent 1
-  - Child 1
-  - Child 2
-- Parent 2`}
-      </MarkdownUI>,
-    )
-    expect(screen.getByText('Parent 1')).toBeTruthy()
-    expect(screen.getByText('Child 1')).toBeTruthy()
-    expect(screen.getByText('Child 2')).toBeTruthy()
-    expect(screen.getByText('Parent 2')).toBeTruthy()
-  })
-
-  test('renders list items as MUI ListItem components', () => {
-    render(<MarkdownUI>{`- List item`}</MarkdownUI>)
-    const listItem = screen.getByText('List item')
-    expect(listItem.classList.contains('MuiListItem-root')).toBe(true)
-  })
-
-  test('renders complex markdown with mixed elements', () => {
-    render(
-      <MarkdownUI>
-        {`# Main Title
-
-This is a paragraph with [a link](https://example.com).
-
-## Subsection
-
-- Bullet point 1
-- Bullet point 2
-
-### Details
-
-Another paragraph.`}
-      </MarkdownUI>,
-    )
-    expect(screen.getByText('Main Title')).toBeTruthy()
-    expect(screen.getByText(/This is a paragraph/)).toBeTruthy()
-    expect(screen.getByText('a link')).toBeTruthy()
-    expect(screen.getByText('Subsection')).toBeTruthy()
-    expect(screen.getByText('Bullet point 1')).toBeTruthy()
-    expect(screen.getByText('Bullet point 2')).toBeTruthy()
-    expect(screen.getByText('Details')).toBeTruthy()
-    expect(screen.getByText('Another paragraph.')).toBeTruthy()
-  })
-
-  test('renders markdown with special characters', () => {
-    render(<MarkdownUI>Text with `code` and **bold** and *italic*</MarkdownUI>)
-    expect(screen.getByText('code')).toBeTruthy()
+    expect(screen.getByText('Title')).toBeTruthy()
     expect(screen.getByText('bold')).toBeTruthy()
     expect(screen.getByText('italic')).toBeTruthy()
   })
 
-  test('handles long markdown content', () => {
-    const longContent = `# Long Content
-
-${'Paragraph. '.repeat(100)}
-
-## Section 2
-
-${'- Item\n'.repeat(50)}`
-    render(<MarkdownUI>{longContent}</MarkdownUI>)
-    expect(screen.getByText('Long Content')).toBeTruthy()
-    expect(screen.getByText('Section 2')).toBeTruthy()
-  })
-
-  test('renders markdown with line breaks', () => {
-    render(
-      <MarkdownUI>
-        {`Line 1
-
-Line 2
-
-
-Line 3`}
-      </MarkdownUI>,
-    )
-    expect(screen.getByText('Line 1')).toBeTruthy()
-    expect(screen.getByText('Line 2')).toBeTruthy()
-    expect(screen.getByText('Line 3')).toBeTruthy()
-  })
-
-  test('renders markdown with inline code', () => {
-    render(<MarkdownUI>Use `npm install` to install dependencies.</MarkdownUI>)
-    expect(screen.getByText('npm install')).toBeTruthy()
-    expect(screen.getByText(/Use/)).toBeTruthy()
-    expect(screen.getByText(/to install dependencies/)).toBeTruthy()
-  })
-
-  test('renders markdown with emphasis', () => {
-    render(<MarkdownUI>This is *emphasized* text</MarkdownUI>)
-    expect(screen.getByText('emphasized')).toBeTruthy()
-  })
-
-  test('renders markdown with strong emphasis', () => {
-    render(<MarkdownUI>This is **strong** text</MarkdownUI>)
-    expect(screen.getByText('strong')).toBeTruthy()
-  })
-
-  test('renders only specified heading levels (h1-h3)', () => {
-    render(
-      <MarkdownUI>
-        {`# H1
-## H2
-### H3
-#### H4
-##### H5
-###### H6`}
-      </MarkdownUI>,
-    )
-    expect(screen.getByText('H1')).toBeTruthy()
-    expect(screen.getByText('H2')).toBeTruthy()
-    expect(screen.getByText('H3')).toBeTruthy()
-    expect(screen.getByText('H4')).toBeTruthy()
-    expect(screen.getByText('H5')).toBeTruthy()
-    expect(screen.getByText('H6')).toBeTruthy()
-  })
-
-  test('handles markdown with escaped characters', () => {
-    render(<MarkdownUI>Escaped \\* asterisk and \\# hash</MarkdownUI>)
-    expect(screen.getByText(/asterisk/)).toBeTruthy()
-    expect(screen.getByText(/hash/)).toBeTruthy()
-  })
-
-  test('renders markdown with numeric content', () => {
-    render(
-      <MarkdownUI>
-        {`1. First: 100
-2. Second: 200
-3. Third: 300`}
-      </MarkdownUI>,
-    )
-    expect(screen.getByText(/First: 100/)).toBeTruthy()
-    expect(screen.getByText(/Second: 200/)).toBeTruthy()
-    expect(screen.getByText(/Third: 300/)).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()
   })
 
-  test('preserves whitespace in code elements', () => {
-    render(<MarkdownUI>`code with spaces`</MarkdownUI>)
-    expect(screen.getByText(/code with.*spaces/)).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')
   })
 
-  test('renders multiple consecutive headings', () => {
-    render(
-      <MarkdownUI>
-        {`# Heading 1
-## Heading 2
-### Heading 3`}
-      </MarkdownUI>,
+  it('renders inline images', () => {
+    const { container } = render(
+      <MarkdownUI
+        content={'![alt text](https://example.com/img.png)\n\nplain text'}
+      />,
     )
-    expect(screen.getByText('Heading 1').tagName).toBe('H4')
-    expect(screen.getByText('Heading 2').tagName).toBe('H5')
-    expect(screen.getByText('Heading 3').tagName).toBe('H6')
-  })
-
-  test('renders links within paragraphs', () => {
-    render(
-      <MarkdownUI>
-        This paragraph contains [a link](https://example.com) in the middle.
-      </MarkdownUI>,
+    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'}
+      />,
     )
-    const link = screen.getByText('a link')
-    expect(link.tagName).toBe('A')
-    expect(screen.getByText(/This paragraph contains/)).toBeTruthy()
+    // 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()
   })
 
-  test('renders mixed list types', () => {
-    render(
-      <MarkdownUI>
-        {`Unordered:
-- Item A
-- Item B
-
-Ordered:
-1. First
-2. Second`}
-      </MarkdownUI>,
-    )
-    expect(screen.getByText('Item A')).toBeTruthy()
-    expect(screen.getByText('Item B')).toBeTruthy()
-    expect(screen.getByText('First')).toBeTruthy()
-    expect(screen.getByText('Second')).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()
   })
 
-  test('renders content with all supported markdown features', () => {
-    render(
-      <MarkdownUI>
-        {`# Title
-
-Paragraph with **bold**, *italic*, and \`code\`.
-
-## List Section
-
-- Item 1 with [link](https://example.com)
-- Item 2
-
-### Ordered
-
-1. First
-2. Second
-
-End paragraph.`}
-      </MarkdownUI>,
+  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(screen.getByText('Title')).toBeTruthy()
-    expect(screen.getByText('bold')).toBeTruthy()
-    expect(screen.getByText('italic')).toBeTruthy()
-    expect(screen.getByText('code')).toBeTruthy()
-    expect(screen.getByText('List Section')).toBeTruthy()
-    expect(screen.getByText(/Item 1/)).toBeTruthy()
-    expect(screen.getByText('link')).toBeTruthy()
-    expect(screen.getByText('Item 2')).toBeTruthy()
-    expect(screen.getByText('Ordered')).toBeTruthy()
-    expect(screen.getByText('First')).toBeTruthy()
-    expect(screen.getByText('Second')).toBeTruthy()
-    expect(screen.getByText('End paragraph.')).toBeTruthy()
+    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/markdown/markdown-ui.tsx

@@ -1,59 +1,55 @@
-import { Link, List, ListItem, Typography } from '@mui/material'
-import ReactMarkdown, { type Components } from 'react-markdown'
-import { styles } from '../markdown/style'
-import type { MarkdownComponentProps } from './types'
+import { Box, Typography, type TypographyProps } from '@mui/material'
+import type { Components } from 'react-markdown'
+import { MarkdownContent } from './markdown-content'
+import { styles } from './style'
 
-const COMPONENTS: Components = {
-  h1: ({ children }) => (
-    <Typography variant='h4' gutterBottom color='inherit'>
-      {children}
-    </Typography>
-  ),
-  h2: ({ children }) => (
-    <Typography variant='h5' gutterBottom color='inherit'>
-      {children}
-    </Typography>
-  ),
-  h3: ({ children }) => (
-    <Typography variant='h6' gutterBottom color='inherit'>
-      {children}
-    </Typography>
-  ),
+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 paragraph color='inherit'>
+    <Typography variant='body2' component='p' sx={styles.paragraph}>
       {children}
     </Typography>
   ),
-  a: ({ children, href, target = '_blank', rel = 'noopener noreferrer' }) => (
-    <Link href={href} target={target} rel={rel}>
-      {children}
-    </Link>
-  ),
-  ul: ({ children }) => <List sx={styles.ul}>{children}</List>,
-  ol: ({ children }) => (
-    <List component='ol' sx={styles.ol}>
-      {children}
-    </List>
-  ),
-  li: ({ children }) => <ListItem sx={styles.li}>{children}</ListItem>,
+}
+
+function mdHeading(
+  props: { children?: React.ReactNode },
+  variant: TypographyProps['variant'],
+) {
+  return (
+    <Typography variant={variant} component='div' sx={styles.heading}>
+      {props.children}
+    </Typography>
+  )
 }
 
 /**
- * Presentational component that renders a Markdown string as MUI-styled HTML using react-markdown.
- *
- * @remarks
- * Maps Markdown elements (headings, paragraphs, links, lists) to MUI Typography and Link components.
- * Custom component overrides can be passed via the `overrides` prop.
+ * 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({ children, overrides }: MarkdownComponentProps) {
+export function MarkdownUI({ content }: MarkdownUIProps) {
   return (
-    <ReactMarkdown
-      components={{
-        ...COMPONENTS,
-        ...overrides,
-      }}
-    >
-      {children}
-    </ReactMarkdown>
+    <Box sx={styles.root}>
+      <MarkdownContent
+        content={content}
+        components={components}
+        allowHtml
+        allowImages
+      />
+    </Box>
   )
 }

package/src/widgets/markdown/markdown.tsx

@@ -1,20 +1,17 @@
-import type { MarkdownUIProps } from './types'
+import { useWidgetId, useWidget } from '../stores'
+import { MarkdownUI } from './markdown-ui'
 import type { MarkdownWidgetData } from './types'
-import { MarkdownUI } from '.'
-import { useWidgetSelector } from '../stores/use-widget-selector'
 
 /**
- * Stateful markdown widget component that reads content from the widget store and renders it as formatted rich text.
+ * 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({ id }: MarkdownUIProps) {
-  const content = useWidgetSelector(
-    id,
-    (w) => (w?.data as MarkdownWidgetData | undefined)?.content,
-  )
-
-  if (!content) {
-    return null
-  }
-
-  return <MarkdownUI>{content}</MarkdownUI>
+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/markdown/skeleton.tsx

@@ -1,12 +1,32 @@
 import { Box, Skeleton } from '@mui/material'
+import type { SxProps, Theme } from '@mui/material'
 
-export function MarkdownSkeleton() {
+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 aria-label='Markdown skeleton'>
-      <Skeleton width='80%' height={24} sx={{ mb: 1 }} />
-      <Skeleton width='90%' height={20} sx={{ mb: 0.5 }} />
-      <Skeleton width='85%' height={20} sx={{ mb: 0.5 }} />
-      <Skeleton width='75%' height={20} />
+    <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/markdown/style.ts

@@ -1,28 +1,53 @@
 import type { SxProps, Theme } from '@mui/material'
 
-export const styles: Record<string, SxProps<Theme>> = {
-  container: {
-    display: 'flex',
-    flexDirection: 'column',
-    gap: ({ spacing }) => spacing(2),
+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',
+    },
   },
-  markdown: {
-    overflow: 'hidden',
-    typography: ({ typography }) => ({
-      ...typography.body1,
-    }),
+  paragraph: {
+    my: 1,
   },
-  li: {
-    display: 'list-item',
-    paddingTop: 0,
-    paddingBottom: 0,
+  heading: {
+    mt: 2,
+    mb: 1,
+    fontWeight: 600,
   },
-  ul: {
-    listStyleType: 'disc',
-    paddingLeft: ({ spacing }) => spacing(2),
-  },
-  ol: {
-    listStyleType: 'decimal',
-    paddingLeft: ({ spacing }) => spacing(2),
-  },
-}
+} satisfies Record<string, SxProps<Theme>>