@carto/ps-react-ui 5.0.0-widgets.9 → 5.0.0

package/src/widgets-v2/bar/skeleton.test.tsx

@@ -0,0 +1,19 @@
+import { describe, it, expect } from 'vitest'
+import { render } from '@testing-library/react'
+import { BarSkeleton } from './skeleton'
+
+describe('<BarSkeleton>', () => {
+  it('renders without crashing', () => {
+    const { container } = render(<BarSkeleton />)
+    expect(container.firstChild).not.toBeNull()
+  })
+
+  it('renders MUI Skeleton placeholders for the bars + axis', () => {
+    const { container } = render(<BarSkeleton />)
+    // MuiSkeleton applies the .MuiSkeleton-root class — count > 1 confirms
+    // both the bar grid AND the axis row are emitted.
+    expect(
+      container.querySelectorAll('.MuiSkeleton-root').length,
+    ).toBeGreaterThan(1)
+  })
+})

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

@@ -0,0 +1,69 @@
+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',
+    justifyContent: 'space-between',
+    flex: '1 1 auto',
+    alignItems: 'flex-end',
+    width: '100%',
+  },
+  bar: {
+    flex: 1,
+    maxWidth: ({ spacing }) => spacing(12),
+    '& + &': {
+      marginLeft: ({ spacing }) => spacing(1),
+    },
+  },
+  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 BAR_HEIGHTS = ['20%', '40%', '60%', '20%', '80%'] as const
+
+/**
+ * Loading state for the Bar widget. Mirrors a bar chart's silhouette — five
+ * vertical bars at staggered heights anchored to the bottom, plus a legend
+ * stub — so the skeleton reads as "a bar chart" rather than a generic list.
+ */
+export function BarSkeleton() {
+  return (
+    <Box sx={styles.container}>
+      <Box sx={styles.grid}>
+        {BAR_HEIGHTS.map((height, i) => (
+          <Skeleton
+            key={`bar-${i}`}
+            sx={styles.bar}
+            variant='rectangular'
+            height={height}
+          />
+        ))}
+      </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/bar/types.ts

@@ -0,0 +1,51 @@
+import type { Theme } from '@mui/material'
+import type { EChartsOption } from 'echarts'
+import type { WidgetSeries } from '../types'
+
+/** A single category entry in a bar series. */
+export interface BarDatum {
+  name: string | number
+  value: number
+}
+
+/** v2 bar widget data shape: array of series, each a flat list of `{name, value}`. */
+export type BarWidgetData = readonly (readonly BarDatum[])[]
+
+/** Inputs to the structural-only {@link barOptions} builder. */
+export interface BarOptionsInput {
+  theme: Theme
+  formatter?: (value: number) => string
+  labelFormatter?: (value: string | number) => string | number
+}
+
+/**
+ * Combined inputs for the option factory creator. Carries everything the
+ * widget needs across BOTH phases — the structural-build (`theme`,
+ * `formatter`, `labelFormatter`, `optionsOverride`) AND the data merge
+ * (`series`, `selection`).
+ */
+export interface BarOptionFactoryInput {
+  theme: Theme
+  formatter?: (value: number) => string
+  labelFormatter?: (value: string | number) => string | number
+  /**
+   * Per-series metadata — drives the legend, `series[i].name`, and
+   * (when `color` is set) per-series `itemStyle.color`. Paired with the
+   * data series by index.
+   */
+  series?: readonly WidgetSeries[]
+  /**
+   * When set, every datum whose `name` is **not** in this list renders dimmed
+   * (`itemStyle.opacity: 0.15`, matching `outOfBrush` styling). `null`/empty
+   * means "no selection active" — every bar is fully opaque.
+   */
+  selection?: readonly (string | number)[] | null
+  /**
+   * Consumer-supplied partial option merged into the structural option at
+   * structural-build time (via `mergeOptions`). Lets stories override pieces
+   * of the theme-aware base without forking the structural builder.
+   */
+  optionsOverride?: Partial<EChartsOption>
+}
+
+export type BarEChartsOption = EChartsOption