@carto/ps-react-ui 5.1.0 → 6.0.0

package/src/widgets/formula/skeleton.tsx

@@ -1,10 +1,27 @@
 import { Box, Skeleton } from '@mui/material'
-import { styles } from './style'
+import type { SxProps, Theme } from '@mui/material'
 
-export function FormulaSkeleton() {
+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.row} aria-label='Formula skeleton'>
-      <Skeleton width={120} height={32} />
+    <Box sx={styles.root}>
+      {Array.from({ length: count }).map((_, i) => (
+        <Skeleton key={`row-${i}`} variant='rectangular' sx={styles.block} />
+      ))}
     </Box>
   )
 }

package/src/widgets/formula/style.ts

@@ -4,20 +4,28 @@ export const styles = {
   root: {
     display: 'flex',
     flexDirection: 'column',
-    gap: (theme: Theme) => theme.spacing(2),
-  },
-  item: {
-    '&[data-disabled="true"]': {
-      color: (theme: Theme) => theme.palette.text.disabled,
-    },
+    gap: 2,
+    alignItems: 'stretch',
   },
   row: {
     display: 'flex',
-    alignItems: 'center',
-    gap: (theme: Theme) => theme.spacing(1),
-
-    '& + &': {
-      marginTop: (theme: Theme) => theme.spacing(1),
-    },
+    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/formula/types.ts

@@ -1,50 +1,49 @@
-import type { TypographyProps } from '@mui/material'
-import type { ReactNode } from 'react'
-import type { BaseWidgetState, WidgetsStoreProps } from '../stores/types'
-import type { WrapperState } from '../wrapper/types'
-import type { DownloadItem } from '../actions/download/types'
-
-export interface FormulaUIProps {
-  id: WidgetsStoreProps['id']
-}
-
-export interface DataItem {
+import type { PaletteColor } from '../../components/types'
+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
-  prefix?: string | ReactNode
-  suffix?: string | ReactNode
-  color?: string
-}
-
-export interface RowProps {
-  id: WidgetsStoreProps['id']
-  children: ReactNode | ((props: { index: number }) => ReactNode)
-}
-
-export interface ValueProps extends Omit<ItemProps, 'children'> {
-  id: WidgetsStoreProps['id']
-  index?: 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
 }
 
-export interface ItemProps {
-  children: ReactNode
-  disabled?: boolean
-  TypographyProps?: TypographyProps
-}
-
-export type FormulaWidgetData = DataItem[]
-
-export interface SeriesConfig {
-  name: string
-  color?: string
-}
-
-export type FormulaWidgetState = BaseWidgetState<
-  WrapperState<FormulaWidgetConfig> & { data: FormulaWidgetData }
->
-
-export interface FormulaWidgetConfig {
-  formatter?: (value: number) => string
-  series?: SeriesConfig[]
+/** 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?: PaletteColor
+  /** 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
 }
 
-export type FormulaDownloadConfig = DownloadItem<FormulaWidgetData>[]
+/**
+ * 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 → widgets}/formula/value.tsx

@@ -1,10 +1,11 @@
 import { Typography, type TypographyProps } from '@mui/material'
 import type { ReactNode } from 'react'
+import type { PaletteColor } from '../../components/types'
 
 export interface ValueProps {
   children: ReactNode
   /** Override the default `text.primary` color — useful for sparkline tints. */
-  color?: string
+  color?: PaletteColor
   TypographyProps?: TypographyProps
 }
 

package/src/widgets/histogram/index.ts

@@ -1,13 +1,13 @@
+export { histogramOptions, createHistogramOptionFactory } from './options'
+export { HistogramSkeleton, type HistogramSkeletonProps } from './skeleton'
+export { createHistogramDownloadConfig } from './download'
+export {
+  toRelativeHistogramData,
+  filterHistogramByLockedBins,
+} from './transforms'
 export type {
-  HistogramConfig,
-  HistogramWidgetConfig,
   HistogramWidgetData,
-  HistogramWidgetState,
+  HistogramOptionsInput,
+  HistogramOptionFactoryInput,
+  HistogramEChartsOption,
 } from './types'
-export type { HistogramDownloadConfigProps } from './config'
-export {
-  histogramConfig,
-  histogramDataToCSV,
-  histogramDownloadConfig,
-} from './config'
-export { HistogramSkeleton } from './skeleton'

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

@@ -8,7 +8,7 @@ import {
   createTooltipFormatter,
   createTooltipPositioner,
   niceNum,
-} from '../../widgets/utils/chart-config'
+} from '../utils/option-builders'
 import { ZOOM_LAYOUT } from '../actions/zoom-toggle'
 import type { OptionFactory } from '../echart'
 import { mergeOptions, resolveThemeColor } from '../utils'

package/src/widgets/histogram/skeleton.tsx

@@ -1,51 +1,69 @@
-import { Box, Skeleton } from '@mui/material'
-import { styles } from './style'
+import { Box, Skeleton, type SxProps, type Theme } from '@mui/material'
 
-export function HistogramSkeleton() {
+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.skeleton.graph.container}>
-      <Box
-        sx={{
-          display: 'flex',
-          alignItems: 'flex-end',
-          justifyContent: 'space-between',
-          gap: ({ spacing }) => spacing(0.5),
-          height: ({ spacing }) => spacing(30),
-          width: '100%',
-        }}
-      >
-        {Array(8)
-          .fill(0)
-          .map((_, i) => {
-            // Create varying heights for histogram bars
-            const heights = [60, 80, 95, 85, 70, 55, 40, 30]
-            const height = `${heights[i]}%`
-            return (
-              <Skeleton
-                key={`skeleton-bar-${i}`}
-                variant='rectangular'
-                sx={{
-                  flex: 1,
-                  height,
-                }}
-              />
-            )
-          })}
+    <Box sx={styles.container}>
+      <Box sx={styles.grid}>
+        {heights.map((h, i) => (
+          <Skeleton key={`bar-${i}`} variant='rectangular' sx={barSx(h)} />
+        ))}
       </Box>
-      <Box
-        sx={{
-          display: 'flex',
-          alignItems: 'center',
-          justifyContent: 'space-between',
-          width: '100%',
-          mt: ({ spacing }) => spacing(1),
-        }}
-      >
-        {Array(4)
-          .fill(0)
-          .map((_, i) => (
-            <Skeleton key={`skeleton-label-${i}`} width={32} height={8} />
-          ))}
+      <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/histogram/types.ts

@@ -1,23 +1,64 @@
-import type { 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 HistogramWidgetData = number[][]
+/**
+ * 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[])[]
 
-export type HistogramWidgetState = EchartWidgetState
+/** Inputs to the structural-only {@link histogramOptions} builder. */
+export interface HistogramOptionsInput {
+  theme: Theme
+  formatter?: (value: number) => string
+}
 
-export type HistogramWidgetConfig = EchartWidgetProps & {
-  type: 'histogram'
+/**
+ * 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 HistogramConfig = ConfigProps &
-  Pick<
-    EchartWidgetOptionProps<unknown>,
-    'theme' | 'formatter' | 'labelFormatter'
-  > & {
-    data?: number[][]
-    ticks: number[]
-  }
+export type HistogramEChartsOption = EChartsOption

package/src/{widgets-v2 → widgets}/index.ts

@@ -43,7 +43,7 @@ import { Table, TableUI } from './table'
  * Consumers import the const and access components via property access:
  *
  * ```tsx
- * import { Widget } from '@carto/ps-react-ui/widgets-v2'
+ * import { Widget } from '@carto/ps-react-ui/widgets'
  *
  * <Widget.Provider id={id} data={data}>
  *   <Widget.Wrapper title='Sales'>
@@ -58,7 +58,7 @@ import { Table, TableUI } from './table'
  *
  * 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`,
+ * subpath entries (`@carto/ps-react-ui/widgets/bar`, `…/category`,
  * `…/table`, `…/actions`, `…/stores`, `…/utils`, etc.) remain available for
  * direct import where needed.
  */
@@ -208,5 +208,5 @@ export type {
   TableSortState,
 } from './table'
 
-// Canonical cross-widget series shape — see `widgets-v2/types.ts`.
+// Canonical cross-widget series shape — see `widgets/types.ts`.
 export type { WidgetSeries } from './types'

package/src/widgets/markdown/index.ts

@@ -1,14 +1,6 @@
 export { Markdown } from './markdown'
-export { MarkdownUI } from './markdown-ui'
-export { MarkdownSkeleton } from './skeleton'
-export { markdownConfig, markdownDownloadConfig } from './config'
-
-export type {
-  MarkdownComponentProps,
-  MarkdownUIProps,
-  MarkdownWidgetData,
-  MarkdownWidgetState,
-  MarkdownWidgetConfig,
-  MarkdownDownloadConfig,
-  MarkdownDataItem,
-} from './types'
+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'