@carto/ps-react-ui 5.3.0 → 6.1.0

package/src/widgets/markdown/types.ts

@@ -1,28 +1,4 @@
-import type { BaseWidgetState, WidgetsStoreProps } from '../stores/types'
-import type { WrapperState } from '../wrapper/types'
-import type { DownloadItem } from '../actions/download/types'
-import type { Components } from 'react-markdown'
-
-// Base Markdown component props (used by Markdown component)
-export interface MarkdownComponentProps {
-  children: string
-  overrides?: Components
-}
-
-export interface MarkdownUIProps {
-  id: WidgetsStoreProps['id']
-}
-
-export interface MarkdownDataItem {
+/** Markdown widget data — a single markdown source string. */
+export interface MarkdownWidgetData {
   content: string
 }
-
-export type MarkdownWidgetData = MarkdownDataItem
-
-export type MarkdownWidgetState = BaseWidgetState<
-  WrapperState<MarkdownWidgetConfig>
->
-
-export type MarkdownWidgetConfig = Record<string, unknown>
-
-export type MarkdownDownloadConfig = DownloadItem<MarkdownWidgetData>[]

package/src/widgets/note/style.ts

@@ -2,28 +2,25 @@ import type { SxProps, Theme } from '@mui/material'
 
 export const styles = {
   root: {
-    typography: 'caption',
-    color: (theme: Theme) => theme.palette.text.secondary,
-    marginBlockStart: ({ spacing }) => spacing(1),
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 0.5,
+  },
+  text: {
+    color: 'text.secondary',
+    overflow: 'hidden',
+    overflowWrap: 'anywhere',
   },
   clamped: {
     display: '-webkit-box',
-    WebkitLineClamp: 3,
     WebkitBoxOrient: 'vertical',
-    overflow: 'hidden',
-  },
-  expanded: {
-    display: 'block',
+    WebkitLineClamp: 3,
   },
-  linkButton: {
-    padding: 0,
-    minWidth: 'auto',
-    textTransform: 'none',
-    typography: 'caption',
+  toggle: {
+    alignSelf: 'flex-start',
+    color: 'primary.main',
     fontWeight: 500,
-    textDecoration: 'none',
-    '&:hover': {
-      backgroundColor: 'transparent',
-    },
+    cursor: 'pointer',
+    '&:hover': { textDecoration: 'underline' },
   },
 } satisfies Record<string, SxProps<Theme>>

package/src/{widgets-v2 → widgets}/note/widget-note.tsx

@@ -37,7 +37,14 @@ export interface NoteMarkdownProps {
  *  the document outline. */
 function CaptionBlock({ children }: { children?: ReactNode }) {
   return (
-    <Typography variant='caption' component='p' color='inherit' sx={{ m: 0 }}>
+    <Typography
+      variant='caption'
+      component='p'
+      sx={{
+        color: 'inherit',
+        m: 0,
+      }}
+    >
       {children}
     </Typography>
   )
@@ -79,7 +86,13 @@ const NOTE_COMPONENTS: Components = {
 function NoteBase({ lineClamp = 3, labels, children }: NoteProps) {
   return (
     <NoteShell lineClamp={lineClamp} labels={labels} dependency={children}>
-      <Typography variant='caption' component='div' color='inherit'>
+      <Typography
+        variant='caption'
+        component='div'
+        sx={{
+          color: 'inherit',
+        }}
+      >
         {children}
       </Typography>
     </NoteShell>

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

@@ -1,8 +1,8 @@
 import {
   buildCsvDownloadItem,
-  buildPngDownloadItem,
-  type DownloadContext,
+  withPngItem,
   type DownloadItem,
+  type WidgetDownloadArgs,
 } from '../actions/download'
 import type { PieWidgetData } from './types'
 
@@ -10,29 +10,16 @@ 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
+ * given, prepends a PNG item that rasterises the captured element via
  * `html2canvas`.
  */
-export function createPieDownloadConfig(args: {
-  filename: string
-  getData: (ctx: DownloadContext) => PieWidgetData
-  seriesNames?: readonly string[]
-  getCaptureEl?: (ctx: DownloadContext) => 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(
+export function createPieDownloadConfig(
+  args: WidgetDownloadArgs<PieWidgetData> & {
+    seriesNames?: readonly string[]
+  },
+): DownloadItem[] {
+  return withPngItem(
+    args,
     buildCsvDownloadItem({
       filename: args.filename,
       getRows: (ctx) => {
@@ -48,5 +35,4 @@ export function createPieDownloadConfig(args: {
       },
     }),
   )
-  return items
 }

package/src/widgets/pie/index.ts

@@ -1,8 +1,10 @@
+export { pieOptions, createPieOptionFactory } from './options'
+export { PieSkeleton, type PieSkeletonProps } from './skeleton'
+export { createPieDownloadConfig } from './download'
 export type {
+  PieDatum,
   PieWidgetData,
-  PieWidgetState,
-  PieWidgetConfig,
-  PieConfig,
+  PieOptionsInput,
+  PieOptionFactoryInput,
+  PieEChartsOption,
 } from './types'
-export { pieConfig, pieDownloadConfig } from './config'
-export { PieSkeleton } from './skeleton'

package/src/{widgets-v2 → widgets}/pie/options.ts

@@ -9,7 +9,7 @@ import {
   createTooltipFormatter,
   createTooltipPositioner,
   niceNum,
-} from '../../widgets/utils/chart-config'
+} from '../utils/option-builders'
 import type { OptionFactory, OptionFactoryContext } from '../echart'
 import { mergeOptions, resolveThemeColor } from '../utils'
 import type { WidgetSeries } from '../types'

package/src/widgets/pie/skeleton.tsx

@@ -1,69 +1,93 @@
 import { Box, Skeleton } from '@mui/material'
-import { styles } from './style'
+import type { SxProps, Theme } from '@mui/material'
 
-const GUTTER = 32
-const SIZE = 294 - GUTTER
-const INNER_SIZE = SIZE - GUTTER
+const OUTER_SIZE = 160
+const HOLE_SIZE = 96
 
-export function PieSkeleton() {
+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.skeleton.graph.container}>
-      <Box
-        sx={{
-          display: 'flex',
-          alignItems: 'center',
-          justifyContent: 'center',
-          position: 'relative',
-        }}
-      >
-        <Skeleton variant='circular' width={SIZE} height={SIZE} />
-        <Skeleton
-          sx={{
-            position: 'absolute',
-            zIndex: 1,
-          }}
-          variant='circular'
-          width={INNER_SIZE}
-          height={INNER_SIZE}
-        />
-        <Box
-          sx={{
-            position: 'absolute',
-            zIndex: 2,
-            display: 'flex',
-            flexDirection: 'column',
-            alignItems: 'center',
-            justifyContent: 'center',
-            gap: ({ spacing }) => spacing(1),
-          }}
-        >
-          <Skeleton height={24} width={72} />
-          <Skeleton height={8} width={48} />
+    <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={{
-          display: 'flex',
-          alignItems: 'center',
-          gap: ({ spacing }) => spacing(2),
-          height: ({ spacing }) => spacing(5),
-        }}
-      >
-        {Array(2)
-          .fill(0)
-          .map((_, i) => (
-            <Box
-              key={`skeleton-${i}`}
-              sx={{
-                display: 'flex',
-                alignItems: 'center',
-                gap: ({ spacing }) => spacing(1.5),
-              }}
-            >
-              <Skeleton variant='circular' width={8} height={8} />
-              <Skeleton width={48} height={8} />
-            </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/pie/types.ts

@@ -1,16 +1,62 @@
-import type { EchartWidgetData, EchartWidgetState } from '../echart'
-import type {
-  EchartWidgetOptionProps,
-  EchartWidgetProps,
-} from '../echart/types'
-import type { ConfigProps } from '../loader'
+import type { Theme } from '@mui/material'
+import type { EChartsOption } from 'echarts'
+import type { WidgetSeries } from '../types'
 
-export type PieWidgetData = EchartWidgetData
+/** A single slice of a pie series. */
+export interface PieDatum {
+  name: string | number
+  value: number
+}
+
+/** Pie widget data — one slice array per series (rendered as side-by-side donuts). */
+export type PieWidgetData = readonly (readonly PieDatum[])[]
 
-export type PieWidgetState = EchartWidgetState
+/** Inputs to the structural-only {@link pieOptions} builder. */
+export interface PieOptionsInput {
+  theme: Theme
+  /** Numeric value formatter — drives the tooltip value and center label. */
+  formatter?: (value: number) => string
+  /** Optional slice-name formatter — also forwarded to the legend. */
+  labelFormatter?: (value: string | number) => string | number
+}
 
-export type PieWidgetConfig = EchartWidgetProps & {
-  type: 'pie'
+/**
+ * Combined inputs for the pie option factory creator. Carries everything
+ * the widget needs across BOTH phases — the structural-build (`theme`,
+ * `formatter`, `labelFormatter`, `optionsOverride`) AND the data merge
+ * (`series`, `radius`, `selection`). The merger emits different
+ * chart shapes by series count: single → donut, multi → horizontal-bar
+ * fallback (mirrors v1 pie); both branches read `theme` for styling.
+ */
+export interface PieOptionFactoryInput {
+  theme: Theme
+  formatter?: (value: number) => string
+  labelFormatter?: (value: string | number) => string | number
+  /**
+   * Per-series metadata — drives the legend, `series[i].name`, and (in
+   * the multi-series bar fallback) per-series colour overrides.
+   * Single-series donuts always use the per-slice palette regardless of
+   * any `series[0].color`, since the donut palette is keyed by data
+   * index, not series index.
+   */
+  series?: readonly WidgetSeries[]
+  /**
+   * Inner/outer radius (percent). Default `['58%', '74%']` produces a
+   * donut sized to leave room for the wrappable bottom legend. Set
+   * inner to `'0%'` for a solid pie.
+   */
+  radius?: readonly [string, string]
+  /**
+   * Selected slice names. Slices not in this list render dimmed
+   * (`itemStyle.opacity: 0.15`). `null`/empty means no selection.
+   */
+  selection?: readonly (string | 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 PieConfig = ConfigProps & EchartWidgetOptionProps<PieWidgetData>
+export type PieEChartsOption = EChartsOption

package/src/widgets/range/index.ts

@@ -1,16 +1,4 @@
-export { RangeUI } from './range-ui'
-export { RangeSkeleton } from './skeleton'
-export { rangeConfig } from './config'
-export { RangeItem } from './components/range-item'
-
-export type {
-  RangeWidgetState,
-  RangeWidgetConfig,
-  RangeDownloadConfig,
-  RangeUIProps,
-  RangeDataItem,
-  RangeWidgetData,
-  RangeItemProps,
-} from './types'
-
-export { sanitizeRangeDataItem, sanitizeRangeDataItems } from './serializer'
+export { Range, type RangeProps } from './range'
+export { RangeUI, type RangeUIProps } from './range-ui'
+export { RangeSkeleton, type RangeSkeletonProps } from './skeleton'
+export type { RangeDataItem, RangeWidgetData, RangeItemValue } from './types'