@carto/ps-react-ui 5.1.0 → 6.0.0

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

@@ -1,27 +0,0 @@
-import { Box, Skeleton } from '@mui/material'
-import type { SxProps, Theme } from '@mui/material'
-
-const styles = {
-  root: {
-    display: 'flex',
-    gap: 3,
-    alignItems: 'baseline',
-    minHeight: 64,
-    py: 1,
-  },
-  block: { width: 120, height: 36 },
-} satisfies Record<string, SxProps<Theme>>
-
-export interface FormulaSkeletonProps {
-  count?: number
-}
-
-export function FormulaSkeleton({ count = 1 }: FormulaSkeletonProps) {
-  return (
-    <Box sx={styles.root}>
-      {Array.from({ length: count }).map((_, i) => (
-        <Skeleton key={`row-${i}`} variant='rectangular' sx={styles.block} />
-      ))}
-    </Box>
-  )
-}

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

@@ -1,31 +0,0 @@
-import type { SxProps, Theme } from '@mui/material'
-
-export const styles = {
-  root: {
-    display: 'flex',
-    flexDirection: 'column',
-    gap: 2,
-    alignItems: 'stretch',
-  },
-  row: {
-    display: 'flex',
-    alignItems: 'flex-start',
-    gap: 1.5,
-  },
-  body: {
-    flex: 1,
-    minWidth: 0,
-    display: 'flex',
-    flexDirection: 'column',
-    gap: 0.25,
-  },
-  valueRow: {
-    display: 'inline-flex',
-    alignItems: 'baseline',
-    gap: 0.25,
-  },
-  delta: {
-    alignSelf: 'center',
-    flexShrink: 0,
-  },
-} satisfies Record<string, SxProps<Theme>>

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

@@ -1,48 +0,0 @@
-import type { WidgetSeries } from '../types'
-
-/**
- * Series metadata rendered as a coloured avatar at the start of a row.
- *
- * Type alias of the cross-widget {@link WidgetSeries} shape so the same
- * `{ name, color? }` object can drive Formula avatars, Spread avatars,
- * Category legends, and echart-widget legends with no per-widget shape
- * gymnastics. Kept as a named export for backwards compatibility.
- */
-export type FormulaSeries = WidgetSeries
-
-export type DeltaSeverity = 'positive' | 'negative' | 'neutral'
-
-/** Comparative delta rendered as a coloured chip on the right of a row. */
-export interface FormulaDelta {
-  /** Numeric magnitude. Default formatting renders as a percent (e.g. `-12,3 %`). */
-  value: number
-  /** Pre-formatted label override (skips the default percent formatter). */
-  label?: string
-  /**
-   * Visual treatment override. When omitted it's derived from `value`'s sign:
-   * `>0 → 'positive'`, `<0 → 'negative'`, `=0 → 'neutral'`.
-   */
-  severity?: DeltaSeverity
-}
-
-/** A single KPI value rendered by the Formula widget. */
-export interface FormulaDataItem {
-  value: number
-  prefix?: string
-  suffix?: string
-  /** Override the value's text colour (e.g. `'success.main'`). */
-  color?: string
-  /** Optional series indicator — coloured avatar with first letter of `name`. */
-  series?: FormulaSeries
-  /** Optional caption rendered below the value. */
-  note?: string
-  /** Optional comparative delta chip rendered to the right of the row. */
-  delta?: FormulaDelta
-}
-
-/**
- * Formula widget data — an array of KPI items rendered top-to-bottom. A common
- * "single big number" widget is just `[{ value: 123 }]`. Multi-series usage
- * sets `series`, `note`, and/or `delta` per item.
- */
-export type FormulaWidgetData = readonly FormulaDataItem[]

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

@@ -1,13 +0,0 @@
-export { histogramOptions, createHistogramOptionFactory } from './options'
-export { HistogramSkeleton, type HistogramSkeletonProps } from './skeleton'
-export { createHistogramDownloadConfig } from './download'
-export {
-  toRelativeHistogramData,
-  filterHistogramByLockedBins,
-} from './transforms'
-export type {
-  HistogramWidgetData,
-  HistogramOptionsInput,
-  HistogramOptionFactoryInput,
-  HistogramEChartsOption,
-} from './types'

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

@@ -1,70 +0,0 @@
-import { Box, Skeleton, type SxProps, type Theme } from '@mui/material'
-
-const styles = {
-  container: {
-    display: 'flex',
-    alignItems: 'center',
-    justifyContent: 'space-between',
-    flexDirection: 'column',
-    gap: ({ spacing }) => spacing(1),
-    height: ({ spacing }) => spacing(38),
-  },
-  grid: {
-    display: 'flex',
-    alignItems: 'flex-end',
-    flex: '1 1 auto',
-    gap: 0.5,
-    width: '100%',
-  },
-  legend: {
-    display: 'flex',
-    alignItems: 'center',
-    gap: ({ spacing }) => spacing(2),
-    height: ({ spacing }) => spacing(5),
-  },
-  legendItem: {
-    display: 'flex',
-    alignItems: 'center',
-    gap: ({ spacing }) => spacing(1.5),
-  },
-} satisfies Record<string, SxProps<Theme>>
-
-const barSx = (height: number): SxProps<Theme> => ({
-  flex: 1,
-  height: `${height}%`,
-  minWidth: 8,
-})
-
-export interface HistogramSkeletonProps {
-  bins?: number
-}
-
-/**
- * Loading state for the Histogram widget. Mirrors Bar's skeleton structure
- * — a grid of bars (bin-shaped silhouette, anchored to the bottom) plus a
- * legend stub — so the placeholder reads consistently with Bar.
- */
-export function HistogramSkeleton({ bins = 12 }: HistogramSkeletonProps) {
-  // Sample heights mimicking a typical bell-shaped distribution.
-  const heights = Array.from({ length: bins }, (_, i) => {
-    const t = i / Math.max(1, bins - 1)
-    return Math.round(20 + 80 * Math.exp(-((t - 0.5) ** 2) * 8))
-  })
-  return (
-    <Box sx={styles.container}>
-      <Box sx={styles.grid}>
-        {heights.map((h, i) => (
-          <Skeleton key={`bar-${i}`} variant='rectangular' sx={barSx(h)} />
-        ))}
-      </Box>
-      <Box sx={styles.legend}>
-        {[0, 1].map((i) => (
-          <Box key={`legend-${i}`} sx={styles.legendItem}>
-            <Skeleton variant='circular' width={8} height={8} />
-            <Skeleton width={48} height={8} />
-          </Box>
-        ))}
-      </Box>
-    </Box>
-  )
-}

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

@@ -1,64 +0,0 @@
-import type { Theme } from '@mui/material'
-import type { EChartsOption } from 'echarts'
-import type { WidgetSeries } from '../types'
-
-/**
- * Histogram widget data — array of series, each a flat array of bin counts.
- * The option factory's merge phase (see {@link createHistogramOptionFactory})
- * combines this with `ticks` to produce a 2-column dataset (`[binLabel, count]`)
- * for ECharts.
- */
-export type HistogramWidgetData = readonly (readonly number[])[]
-
-/** Inputs to the structural-only {@link histogramOptions} builder. */
-export interface HistogramOptionsInput {
-  theme: Theme
-  formatter?: (value: number) => string
-}
-
-/**
- * Combined inputs for the histogram option factory creator. Carries
- * everything the widget needs across BOTH phases — the structural-build
- * (`theme`, `formatter`, `optionsOverride`) AND the data merge (`ticks`,
- * `series`, `labelFormatter`, `selection`).
- */
-export interface HistogramOptionFactoryInput {
-  theme: Theme
-  formatter?: (value: number) => string
-  /** Bin boundaries — length = bins + 1. */
-  ticks: readonly number[]
-  /**
-   * Per-series metadata — drives the legend, `series[i].name`, and
-   * (when `color` is set) a per-series colour override on the bars.
-   */
-  series?: readonly WidgetSeries[]
-  /**
-   * Bin-range label transform (e.g. `"0–10"` → `"[0–10)"`). Distinct from
-   * the standard `OptionFactoryContext.labelFormatter` (which operates on
-   * categories): this one is histogram-specific and runs only on the
-   * generated bin-range strings before they hit the x-axis.
-   */
-  labelFormatter?: (label: string) => string
-  /**
-   * Selected bin indices. Bins not in this list render dimmed
-   * (`itemStyle.opacity: 0.15`). `null`/empty means no selection.
-   */
-  selection?: readonly number[] | null
-  /**
-   * Locked bin indices (from `LockSelection`). The x-axis crops its visible
-   * window to `[min(lockedItems), max(lockedItems)]` so the chart actually
-   * zooms into the locked range instead of showing every bin label with
-   * zeroed-out bars outside it. `null`/empty means no crop. Histogram's
-   * selection is always a contiguous run (`use-widget-filters`'s BETWEEN
-   * envelope round-trip fills any gaps), so min/max fully describes it.
-   */
-  lockedItems?: readonly number[] | null
-  /**
-   * Consumer-supplied partial option merged into the structural option at
-   * structural-build time. Lets stories override pieces of the theme-aware
-   * base without forking the structural builder.
-   */
-  optionsOverride?: Partial<EChartsOption>
-}
-
-export type HistogramEChartsOption = EChartsOption

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

@@ -1,6 +0,0 @@
-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-ui.test.tsx

@@ -1,75 +0,0 @@
-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

@@ -1,55 +0,0 @@
-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>
-  )
-}

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

@@ -1,17 +0,0 @@
-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.tsx

@@ -1,32 +0,0 @@
-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

@@ -1,53 +0,0 @@
-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

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

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

@@ -1,26 +0,0 @@
-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/pie/index.ts

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

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

@@ -1,94 +0,0 @@
-import { Box, Skeleton } from '@mui/material'
-import type { SxProps, Theme } from '@mui/material'
-
-const OUTER_SIZE = 160
-const HOLE_SIZE = 96
-
-const styles = {
-  root: {
-    display: 'flex',
-    flexDirection: 'column',
-    alignItems: 'center',
-    justifyContent: 'center',
-    minHeight: 200,
-    py: 1,
-    gap: ({ spacing }) => spacing(2),
-  },
-  donut: {
-    position: 'relative',
-    display: 'flex',
-    alignItems: 'center',
-    justifyContent: 'center',
-  },
-  ring: {
-    width: OUTER_SIZE,
-    height: OUTER_SIZE,
-  },
-  hole: {
-    position: 'absolute',
-    zIndex: 1,
-    width: HOLE_SIZE,
-    height: HOLE_SIZE,
-    borderRadius: '50%',
-    bgcolor: 'background.paper',
-  },
-  label: {
-    position: 'absolute',
-    zIndex: 2,
-    display: 'flex',
-    flexDirection: 'column',
-    alignItems: 'center',
-    justifyContent: 'center',
-    gap: ({ spacing }) => spacing(0.5),
-  },
-  legend: {
-    display: 'flex',
-    alignItems: 'center',
-    gap: ({ spacing }) => spacing(2),
-  },
-  legendItem: {
-    display: 'flex',
-    alignItems: 'center',
-    gap: ({ spacing }) => spacing(1.5),
-  },
-} satisfies Record<string, SxProps<Theme>>
-
-export interface PieSkeletonProps {
-  count?: number
-}
-
-/**
- * Loading state for the Pie widget. Mirrors the donut silhouette — a ring
- * (gray circle with a background-coloured hole punched out), a stacked
- * value/name stub in the centre, and a centered legend stub below — so the
- * skeleton reads as "a donut chart" rather than a solid disc.
- *
- * Single donut only: multi-series pie loads as a horizontal bar chart, so
- * rendering one ring stays honest regardless of `count`.
- */
-export function PieSkeleton({ count }: PieSkeletonProps) {
-  // `count` is accepted for API compatibility but intentionally unused: the
-  // skeleton always renders a single donut, since multi-series pie loads as a
-  // horizontal bar chart rather than multiple donuts.
-  void count
-  return (
-    <Box sx={styles.root}>
-      <Box sx={styles.donut}>
-        <Skeleton variant='circular' sx={styles.ring} />
-        <Box sx={styles.hole} />
-        <Box sx={styles.label}>
-          <Skeleton width={56} height={18} />
-          <Skeleton width={36} height={8} />
-        </Box>
-      </Box>
-      <Box sx={styles.legend}>
-        {[0, 1].map((i) => (
-          <Box key={`legend-${i}`} sx={styles.legendItem}>
-            <Skeleton variant='circular' width={8} height={8} />
-            <Skeleton width={48} height={8} />
-          </Box>
-        ))}
-      </Box>
-    </Box>
-  )
-}