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

package/src/widgets-v2/category/components/category-row-stacked.test.tsx

@@ -0,0 +1,248 @@
+import { describe, it, expect, vi } from 'vitest'
+import { fireEvent, render, screen, within } from '@testing-library/react'
+import { CategoryRowStacked } from './category-row-stacked'
+
+const COLORS = ['rgb(0, 200, 0)', 'rgb(0, 100, 0)']
+
+describe('<CategoryRowStacked>', () => {
+  it('renders displayName ?? name on the left of the header', () => {
+    render(
+      <CategoryRowStacked
+        name='cat-key'
+        displayName='Cat'
+        values={[45, 32]}
+        colors={COLORS}
+        seriesNames={['Women', 'Men']}
+        formatter={(n) => String(n)}
+        selected={false}
+        onToggle={vi.fn()}
+      />,
+    )
+    expect(screen.getByText('Cat')).toBeTruthy()
+    expect(screen.queryByText('cat-key')).toBeNull()
+  })
+
+  it('falls back to the raw name when displayName is omitted', () => {
+    render(
+      <CategoryRowStacked
+        name='Plain'
+        values={[1]}
+        colors={['rgb(0, 0, 0)']}
+        seriesNames={['S']}
+        formatter={(n) => String(n)}
+        selected={false}
+        onToggle={vi.fn()}
+      />,
+    )
+    expect(screen.getByText('Plain')).toBeTruthy()
+  })
+
+  it('renders formatter(sum) on the right of the header', () => {
+    render(
+      <CategoryRowStacked
+        name='Cat'
+        values={[45, 32]}
+        colors={COLORS}
+        seriesNames={['Women', 'Men']}
+        formatter={(n) => `${n}K`}
+        selected={false}
+        onToggle={vi.fn()}
+      />,
+    )
+    expect(screen.getByText('77K')).toBeTruthy()
+  })
+
+  it('renders one breakdown entry per series, including zero values', () => {
+    render(
+      <CategoryRowStacked
+        name='Cat'
+        values={[45, 0, 32]}
+        colors={[...COLORS, 'rgb(0, 50, 0)']}
+        seriesNames={['Women', 'Other', 'Men']}
+        formatter={(n) => String(n)}
+        selected={false}
+        onToggle={vi.fn()}
+      />,
+    )
+    expect(screen.getByText('Women: 45')).toBeTruthy()
+    expect(screen.getByText('Other: 0')).toBeTruthy()
+    expect(screen.getByText('Men: 32')).toBeTruthy()
+  })
+
+  it("renders whatever seriesNames it is given — fallback resolution is the caller's responsibility", () => {
+    // The component has no notion of which series were hidden upstream, so
+    // it must not recompute a positional "Series N" fallback itself — the
+    // caller (category-ui.tsx) resolves names, including fallbacks, using
+    // each series' ORIGINAL index before this component ever sees them.
+    render(
+      <CategoryRowStacked
+        name='Cat'
+        values={[45, 32]}
+        colors={COLORS}
+        seriesNames={['Series 1', 'Series 3']}
+        formatter={(n) => String(n)}
+        selected={false}
+        onToggle={vi.fn()}
+      />,
+    )
+    expect(screen.getByText('Series 1: 45')).toBeTruthy()
+    expect(screen.getByText('Series 3: 32')).toBeTruthy()
+  })
+
+  it('per-row normalization: bar fills 100% with segments proportional to the row sum', () => {
+    // values [30, 70] sum to 100 → segments at 30% and 70%, cumulative
+    // offsets 0% and 30%. The bar saturates regardless of any
+    // hypothetical global max — that's the point of stacked mode.
+    const { container } = render(
+      <CategoryRowStacked
+        name='Cat'
+        values={[30, 70]}
+        colors={COLORS}
+        seriesNames={['A', 'B']}
+        formatter={(n) => String(n)}
+        selected={false}
+        onToggle={vi.fn()}
+      />,
+    )
+    const fills = container.querySelectorAll<HTMLElement>(
+      '[data-bar-fill="true"]',
+    )
+    expect(fills.length).toBe(2)
+    expect(fills[0]!.style.left).toBe('0%')
+    expect(fills[0]!.style.width).toBe('30%')
+    expect(fills[1]!.style.left).toBe('30%')
+    expect(fills[1]!.style.width).toBe('70%')
+  })
+
+  it('per-row normalization: bar still fills 100% for an arbitrary row total (45 + 32 → 77)', () => {
+    const { container } = render(
+      <CategoryRowStacked
+        name='Cat'
+        values={[45, 32]}
+        colors={COLORS}
+        seriesNames={['Women', 'Men']}
+        formatter={(n) => String(n)}
+        selected={false}
+        onToggle={vi.fn()}
+      />,
+    )
+    const fills = container.querySelectorAll<HTMLElement>(
+      '[data-bar-fill="true"]',
+    )
+    // 45/77 ≈ 58.44…, 32/77 ≈ 41.56…
+    const w0 = parseFloat(fills[0]!.style.width)
+    const w1 = parseFloat(fills[1]!.style.width)
+    expect(w0 + w1).toBeCloseTo(100, 1)
+    expect(w0).toBeGreaterThan(58)
+    expect(w0).toBeLessThan(59)
+    expect(w1).toBeGreaterThan(41)
+    expect(w1).toBeLessThan(42)
+  })
+
+  it('renders the stacked bar with one data-bar-fill per non-zero series', () => {
+    const { container } = render(
+      <CategoryRowStacked
+        name='Cat'
+        values={[45, 0, 32]}
+        colors={[...COLORS, 'rgb(0, 50, 0)']}
+        seriesNames={['Women', 'Other', 'Men']}
+        formatter={(n) => String(n)}
+        selected={false}
+        onToggle={vi.fn()}
+      />,
+    )
+    const fills = container.querySelectorAll('[data-bar-fill="true"]')
+    // Zero series is skipped in the bar, present in the breakdown.
+    expect(fills).toHaveLength(2)
+  })
+
+  it('clicking anywhere in the row toggles by raw name', () => {
+    const onToggle = vi.fn()
+    render(
+      <CategoryRowStacked
+        name='raw-key'
+        displayName='Pretty'
+        values={[45, 32]}
+        colors={COLORS}
+        seriesNames={['Women', 'Men']}
+        formatter={(n) => String(n)}
+        selected={false}
+        onToggle={onToggle}
+      />,
+    )
+    fireEvent.click(screen.getByRole('button'))
+    expect(onToggle).toHaveBeenCalledWith('raw-key')
+  })
+
+  it('toggles via keyboard Enter and Space, preventing default on space', () => {
+    const onToggle = vi.fn()
+    render(
+      <CategoryRowStacked
+        name='K'
+        values={[1]}
+        colors={['rgb(0, 0, 0)']}
+        seriesNames={['S']}
+        formatter={(n) => String(n)}
+        selected={false}
+        onToggle={onToggle}
+      />,
+    )
+    const row = screen.getByRole('button')
+    fireEvent.keyDown(row, { key: 'Enter' })
+    expect(onToggle).toHaveBeenCalledWith('K')
+    onToggle.mockClear()
+    fireEvent.keyDown(row, { key: ' ' })
+    expect(onToggle).toHaveBeenCalledWith('K')
+  })
+
+  it('reflects selection via aria-pressed', () => {
+    const { rerender } = render(
+      <CategoryRowStacked
+        name='K'
+        values={[1]}
+        colors={['rgb(0, 0, 0)']}
+        seriesNames={['S']}
+        formatter={(n) => String(n)}
+        selected={false}
+        onToggle={vi.fn()}
+      />,
+    )
+    expect(screen.getByRole('button').getAttribute('aria-pressed')).toBe(
+      'false',
+    )
+    rerender(
+      <CategoryRowStacked
+        name='K'
+        values={[1]}
+        colors={['rgb(0, 0, 0)']}
+        seriesNames={['S']}
+        formatter={(n) => String(n)}
+        selected={true}
+        onToggle={vi.fn()}
+      />,
+    )
+    expect(screen.getByRole('button').getAttribute('aria-pressed')).toBe('true')
+  })
+
+  it('when dim colors are passed in, every segment paints with the dim color (breakdown text unchanged)', () => {
+    const DIM = 'rgba(0, 0, 0, 0.26)'
+    render(
+      <CategoryRowStacked
+        name='Cat'
+        values={[45, 32]}
+        colors={[DIM, DIM]}
+        seriesNames={['Women', 'Men']}
+        formatter={(n) => String(n)}
+        selected={false}
+        onToggle={vi.fn()}
+      />,
+    )
+    const row = screen.getByRole('button')
+    const fills = row.querySelectorAll<HTMLElement>('[data-bar-fill="true"]')
+    expect(fills.length).toBe(2)
+    fills.forEach((f) => expect(f.style.backgroundColor).toBe(DIM))
+    // Breakdown text remains visible and unchanged.
+    expect(within(row).getByText('Women: 45')).toBeTruthy()
+    expect(within(row).getByText('Men: 32')).toBeTruthy()
+  })
+})

package/src/widgets-v2/category/components/category-row-stacked.tsx

@@ -0,0 +1,104 @@
+import type { KeyboardEvent } from 'react'
+import { Box, Typography } from '@mui/material'
+import { CategoryBarStacked } from './category-bar-stacked'
+import type { CategoryKey, CategorySize } from '../types'
+import { styles } from '../style'
+
+export interface CategoryRowStackedProps {
+  /** Raw category key — what gets emitted to `onToggle`. */
+  name: CategoryKey
+  /** Display label (post-`labelFormatter`). Falls back to `name`. */
+  displayName?: string | number
+  /** One value per series. Zero values still appear in the breakdown row. */
+  values: readonly number[]
+  /** One color per series (palette + per-series overrides resolved upstream). */
+  colors: readonly string[]
+  /**
+   * Series names for the breakdown row, one per visible series, already
+   * resolved by the caller (unnamed series fall back to `Series N` using
+   * their ORIGINAL series index — this component has no notion of which
+   * series were hidden, so it must not recompute a positional fallback).
+   */
+  seriesNames: readonly string[]
+  formatter: (n: number) => string
+  selected: boolean
+  onToggle: (name: CategoryKey) => void
+  /** Bar visual density. Forwarded to the inner {@link CategoryBarStacked}. */
+  size?: CategorySize
+}
+
+/**
+ * Stacked-mode category row: label + total share a header line; a single
+ * segmented bar sits below; an inline breakdown lists each series with its
+ * formatted value. Click anywhere in the row toggles selection by `name`.
+ *
+ * Per-row normalization: the stacked bar always fills 100% of the track,
+ * with each segment sized as `value_i / sum(values)`. This is intentionally
+ * different from `CategoryRowMulti` (which scales bars against the global
+ * `maxValue` for cross-row comparison) — in stacked mode the comparable
+ * axis is the proportion of each series within the row, not the row's
+ * total relative to other rows. The total numeric value is still shown in
+ * the header so the per-row magnitude isn't lost.
+ *
+ * Visual selection / dim signal lives entirely in the segment colors
+ * (`colors` prop) — every series in a dimmed row receives
+ * `theme.palette.action.disabled`. The bar visually collapses to a single
+ * grey shape when dimmed, but the breakdown text stays at full color so the
+ * per-series values remain legible.
+ */
+export function CategoryRowStacked({
+  name,
+  displayName,
+  values,
+  colors,
+  seriesNames,
+  formatter,
+  selected,
+  onToggle,
+  size,
+}: CategoryRowStackedProps) {
+  const handleKey = (e: KeyboardEvent<HTMLDivElement>): void => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault()
+      onToggle(name)
+    }
+  }
+  const total = values.reduce((a, b) => a + b, 0)
+  return (
+    <Box
+      role='button'
+      aria-pressed={selected}
+      tabIndex={0}
+      onClick={() => onToggle(name)}
+      onKeyDown={handleKey}
+      sx={styles.rowStacked}
+    >
+      <Box sx={styles.stackedHeader}>
+        <Typography variant='body2' sx={styles.multiName}>
+          {displayName ?? name}
+        </Typography>
+        <Typography variant='body2' sx={styles.stackedTotal}>
+          {formatter(total)}
+        </Typography>
+      </Box>
+      <CategoryBarStacked
+        values={values}
+        colors={colors}
+        maxValue={total}
+        size={size}
+      />
+      <Box sx={styles.stackedBreakdown}>
+        {values.map((v, i) => (
+          // Series name is the stable identity for the breakdown line.
+          <Typography
+            key={`breakdown-${seriesNames[i]}`}
+            variant='body2'
+            sx={styles.stackedBreakdownItem}
+          >
+            {`${seriesNames[i]}: ${formatter(v)}`}
+          </Typography>
+        ))}
+      </Box>
+    </Box>
+  )
+}

package/src/widgets-v2/category/download.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { createCategoryDownloadConfig } from './download'
+import type { CategoryWidgetData } from './types'
+
+const data: CategoryWidgetData = [
+  [
+    { name: 'a', value: 1 },
+    { name: 'b', value: 2 },
+  ],
+  [{ name: 'a', value: 10 }],
+]
+
+let csvText = ''
+
+beforeEach(() => {
+  csvText = ''
+  vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:mock')
+  vi.spyOn(URL, 'revokeObjectURL').mockImplementation(() => undefined)
+  const RealBlob = global.Blob
+  vi.stubGlobal(
+    'Blob',
+    class extends RealBlob {
+      constructor(parts: BlobPart[], opts?: BlobPropertyBag) {
+        csvText = typeof parts[0] === 'string' ? parts[0] : ''
+        super(parts, opts)
+      }
+    },
+  )
+})
+
+describe('createCategoryDownloadConfig', () => {
+  it('CSV-only by default', () => {
+    expect(
+      createCategoryDownloadConfig({ filename: 'c', getData: () => data }).map(
+        (i) => i.id,
+      ),
+    ).toEqual(['csv'])
+  })
+
+  it('CSV item carries the canonical icon and short label', () => {
+    const item = createCategoryDownloadConfig({
+      filename: 'c',
+      getData: () => data,
+    }).find((i) => i.id === 'csv')!
+    expect(item.label).toBe('CSV')
+    expect(item.icon).toBeTruthy()
+  })
+
+  it('prepends PNG when getCaptureEl is provided', () => {
+    const items = createCategoryDownloadConfig({
+      filename: 'c',
+      getData: () => data,
+      getCaptureEl: () => document.createElement('div'),
+    })
+    expect(items.map((i) => i.id)).toEqual(['png', 'csv'])
+  })
+
+  it('CSV resolve emits series × items with default names', async () => {
+    const items = createCategoryDownloadConfig({
+      filename: 'c',
+      getData: () => data,
+    })
+    const handle = await items.find((i) => i.id === 'csv')!.resolve()
+    expect(handle.filename).toBe('c.csv')
+    expect(csvText).toBe(
+      'series,name,value\nseries_1,a,1\nseries_1,b,2\nseries_2,a,10',
+    )
+  })
+
+  it('CSV honours supplied seriesNames', async () => {
+    const items = createCategoryDownloadConfig({
+      filename: 'c',
+      getData: () => data,
+      seriesNames: ['baseline', 'override'],
+    })
+    await items.find((i) => i.id === 'csv')!.resolve()
+    expect(csvText.split('\n')[1]).toBe('baseline,a,1')
+    expect(csvText.split('\n')[3]).toBe('override,a,10')
+  })
+})

package/src/widgets-v2/category/download.ts

@@ -0,0 +1,50 @@
+import {
+  buildCsvDownloadItem,
+  buildPngDownloadItem,
+  type DownloadItem,
+} from '../actions/download'
+import type { CategoryWidgetData } from './types'
+
+/**
+ * Download menu items for the Category widget. Always includes a CSV item
+ * with `series, name, value` columns (one row per item). When
+ * `getCaptureEl` is supplied, prepends a PNG item that rasterises the
+ * captured element via `html2canvas`.
+ */
+export function createCategoryDownloadConfig(args: {
+  filename: string
+  getData: () => CategoryWidgetData
+  seriesNames?: readonly string[]
+  getCaptureEl?: () => 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(
+    buildCsvDownloadItem({
+      filename: args.filename,
+      getRows: () => {
+        const data = args.getData()
+        const rows: unknown[][] = [['series', 'name', 'value']]
+        for (const [i, series] of data.entries()) {
+          const seriesName = args.seriesNames?.[i] ?? `series_${i + 1}`
+          for (const item of series) {
+            rows.push([seriesName, item.name, item.value])
+          }
+        }
+        return rows
+      },
+    }),
+  )
+  return items
+}

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

@@ -0,0 +1,32 @@
+export { Category, type CategoryProps } from './category'
+export { CategoryUI, type CategoryUIProps } from './category-ui'
+export { CategorySkeleton, type CategorySkeletonProps } from './skeleton'
+export { createCategoryDownloadConfig } from './download'
+
+// Sub-components — subpath-only (not on the curated `Widget` namespace).
+export { CategoryBar, type CategoryBarProps } from './components/category-bar'
+export {
+  CategoryRowSingle,
+  type CategoryRowSingleProps,
+} from './components/category-row-single'
+export {
+  CategoryRowMulti,
+  type CategoryRowMultiProps,
+} from './components/category-row-multi'
+export {
+  CategoryRowOther,
+  type CategoryRowOtherProps,
+} from './components/category-row-other'
+export {
+  CategoryLegend,
+  type CategoryLegendProps,
+} from './components/category-legend'
+
+export type {
+  CategoryDataItem,
+  CategoryWidgetData,
+  CategoryKey,
+  CategorySeriesConfig,
+  CategoryLabels,
+  CategorySize,
+} from './types'

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

@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest'
+import { render } from '@testing-library/react'
+import { CategorySkeleton } from './skeleton'
+
+describe('<CategorySkeleton>', () => {
+  it('renders without crashing with defaults', () => {
+    const { container } = render(<CategorySkeleton />)
+    expect(container.firstChild).not.toBeNull()
+    expect(
+      container.querySelectorAll('.MuiSkeleton-root').length,
+    ).toBeGreaterThan(0)
+  })
+
+  it('renders the requested row count', () => {
+    const { container } = render(<CategorySkeleton rows={3} />)
+    // Each row emits a label + value + bar skeleton, so > rows.
+    expect(
+      container.querySelectorAll('.MuiSkeleton-root').length,
+    ).toBeGreaterThanOrEqual(3)
+  })
+
+  it('renders the medium size variant', () => {
+    const { container } = render(<CategorySkeleton size='medium' rows={2} />)
+    expect(container.firstChild).not.toBeNull()
+  })
+})

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

@@ -0,0 +1,74 @@
+import { Box, Skeleton } from '@mui/material'
+import type { SxProps, Theme } from '@mui/material'
+import type { CategorySize } from './types'
+
+const styles = {
+  root: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 1,
+    py: 0.5,
+  },
+  // Mirror the real row layout: label + value on top, bar below.
+  row: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 0.5,
+  },
+  rowHeader: {
+    display: 'flex',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    gap: 1,
+  },
+  // Small fixed-width shimmer pills — matches the visual density of the
+  // real label / value cells without claiming the full row width.
+  name: { height: 14, width: 80 },
+  value: { height: 14, width: 48 },
+} satisfies Record<string, SxProps<Theme>>
+
+// Bar shimmer height matches the live bar track for each size variant so
+// the skeleton doesn't visibly resize the row on data settle.
+const BAR_HEIGHT: Record<CategorySize, number> = {
+  small: 4,
+  medium: 12,
+}
+
+// Varied widths give the bar shimmer a more realistic, less uniform feel.
+// Cycles when `rows > WIDTH_PATTERNS.length`.
+const WIDTH_PATTERNS = ['95%', '80%', '55%', '75%', '60%']
+
+export interface CategorySkeletonProps {
+  rows?: number
+  /**
+   * Visual density. Mirrors the live widget's `size` prop so the loading
+   * shimmer's bar height matches what's about to render — no row jump
+   * on data settle.
+   */
+  size?: CategorySize
+}
+
+export function CategorySkeleton({
+  rows = 5,
+  size = 'small',
+}: CategorySkeletonProps) {
+  return (
+    <Box sx={styles.root}>
+      {Array.from({ length: rows }).map((_, i) => (
+        <Box key={`row-${i}`} sx={styles.row}>
+          <Box sx={styles.rowHeader}>
+            <Skeleton variant='rectangular' sx={styles.name} />
+            <Skeleton variant='rectangular' sx={styles.value} />
+          </Box>
+          <Skeleton
+            variant='rectangular'
+            sx={{
+              height: BAR_HEIGHT[size],
+              width: WIDTH_PATTERNS[i % WIDTH_PATTERNS.length],
+            }}
+          />
+        </Box>
+      ))}
+    </Box>
+  )
+}