@carto/ps-react-ui 4.7.0 → 4.8.0

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

@@ -0,0 +1,99 @@
+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. Missing entries fall back to `Series N`. */
+  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] ?? `series-${i}`}`}
+            variant='body2'
+            sx={styles.stackedBreakdownItem}
+          >
+            {`${seriesNames[i] ?? `Series ${i + 1}`}: ${formatter(v)}`}
+          </Typography>
+        ))}
+      </Box>
+    </Box>
+  )
+}

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

@@ -0,0 +1,71 @@
+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('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,54 @@
+import {
+  buildPngDownloadItem,
+  downloadToCSV,
+  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({
+    id: 'csv',
+    label: 'Download as CSV',
+    resolve: () => {
+      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])
+        }
+      }
+      const handle = downloadToCSV(rows)
+      return Promise.resolve({
+        url: handle.url,
+        filename: `${args.filename}.csv`,
+        revoke: handle.revoke,
+      })
+    },
+  })
+  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>
+  )
+}

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

@@ -0,0 +1,290 @@
+import type { SxProps, Theme } from '@mui/material'
+import type { CategorySize } from './types'
+
+// Size-keyed bar styles — scoped strictly to the bar primitive
+// (track + fill height & corner radius). `small` preserves the
+// historical look (4px-tall pill); `medium` renders a 12px-tall track
+// with a 2px corner radius. Every other token (gap, padding, hover,
+// transitions, label/value typography) is size-invariant.
+const bar: Record<CategorySize, SxProps<Theme>> = {
+  small: {
+    position: 'relative',
+    height: 4,
+    bgcolor: 'action.hover',
+    borderRadius: 1,
+    overflow: 'hidden',
+    transition: 'background-color 150ms ease',
+  },
+  medium: {
+    position: 'relative',
+    height: 12,
+    bgcolor: 'action.hover',
+    borderRadius: 0.25,
+    overflow: 'hidden',
+    transition: 'background-color 150ms ease',
+  },
+}
+
+const barFill: Record<CategorySize, SxProps<Theme>> = {
+  small: {
+    position: 'absolute',
+    inset: '0 auto 0 0',
+    borderRadius: 1,
+    transition:
+      'width 300ms ease-in-out, background-color 150ms ease, filter 150ms ease',
+  },
+  medium: {
+    position: 'absolute',
+    inset: '0 auto 0 0',
+    borderRadius: 0.25,
+    transition:
+      'width 300ms ease-in-out, background-color 150ms ease, filter 150ms ease',
+  },
+}
+
+// Square-cornered segment for the stacked bar. Adjacent segments meet
+// cleanly; the parent `bar[size]` track clips the outer ends via its
+// own borderRadius + overflow:hidden, so the stacked bar still has the
+// same rounded silhouette as a single `CategoryBar`.
+const stackedSegment: Record<CategorySize, SxProps<Theme>> = {
+  small: {
+    position: 'absolute',
+    top: 0,
+    bottom: 0,
+    transition:
+      'left 300ms ease-in-out, width 300ms ease-in-out, background-color 150ms ease, filter 150ms ease',
+  },
+  medium: {
+    position: 'absolute',
+    top: 0,
+    bottom: 0,
+    transition:
+      'left 300ms ease-in-out, width 300ms ease-in-out, background-color 150ms ease, filter 150ms ease',
+  },
+}
+
+export const styles = {
+  // ── Top-level container ────────────────────────────────────────────
+  root: {
+    display: 'flex',
+    flexDirection: 'column',
+    position: 'relative',
+    width: '100%',
+  },
+  // Flat list of category rows. Holds both single + multi rows.
+  list: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 1,
+    py: 0.5,
+  },
+
+  // ── Single-series row ─────────────────────────────────────────────
+  // v1 layout: label + value share a top flex row (justify-between); the
+  // bar fills the row width below. Mirrors `rowMulti` for visual
+  // consistency.
+  rowSingle: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 0.5,
+    // py: 0.5,
+    // px: 0.5,
+    cursor: 'pointer',
+    userSelect: 'none',
+    transition: 'background-color 80ms ease',
+    // Hovering anywhere in the row also brightens the bar fill, matching
+    // what the bar got from `bar:hover` before. `data-bar-fill` is set
+    // on `barFill` by <CategoryBar>; descendant selector reaches it
+    // through `bar` in single rows and through `multiBarRow > bar` in
+    // multi rows.
+    '&:hover [data-bar-fill="true"]': {
+      filter: 'brightness(1.2)',
+    },
+    '&:focus-visible': {
+      outline: '2px solid',
+      outlineColor: 'primary.main',
+      outlineOffset: -2,
+    },
+  },
+  // Top row of `rowSingle`: label on the left, value on the right.
+  rowHeader: {
+    display: 'flex',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    gap: 1,
+  },
+  // ── Multi-series row ──────────────────────────────────────────────
+  // Flex column: label fills the top row; bar+value pairs stack below.
+  // Bars get full track width — better legibility for N>=2 series than a
+  // shared grid would give.
+  rowMulti: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 0.5,
+    // py: 0.5,
+    // px: 0.5,
+    cursor: 'pointer',
+    userSelect: 'none',
+    transition: 'background-color 80ms ease',
+    // Row-hover brightens every bar fill inside the multi-row.
+    '&:hover [data-bar-fill="true"]': {
+      filter: 'brightness(1.2)',
+    },
+    '&:focus-visible': {
+      outline: '2px solid',
+      outlineColor: 'primary.main',
+      outlineOffset: -2,
+    },
+  },
+  // ── Row labels / values ───────────────────────────────────────────
+  // Matches v1: name uses medium-weight body2 in primary text color,
+  // value uses regular body2 in secondary text color. Same font size,
+  // visual hierarchy via weight + color.
+  name: {
+    overflow: 'hidden',
+    whiteSpace: 'nowrap',
+    textOverflow: 'ellipsis',
+    color: 'text.primary',
+    fontWeight: 'medium',
+  },
+  multiName: {
+    overflow: 'hidden',
+    whiteSpace: 'nowrap',
+    textOverflow: 'ellipsis',
+    color: 'text.primary',
+    fontWeight: 'medium',
+  },
+  value: {
+    color: 'text.secondary',
+    fontVariantNumeric: 'tabular-nums',
+    // Right-align + minWidth keeps `rowMulti`'s per-bar value column
+    // tidy (where the bar grows on the left and the number sits at a
+    // fixed right edge). `rowSingle` uses `rowHeader`'s flex
+    // justify-between to push the value to the trailing edge, so the
+    // minWidth here is also harmless in that context.
+    minWidth: 48,
+    textAlign: 'right',
+  },
+
+  // ── Bar (track + fill) ────────────────────────────────────────────
+  // Size-keyed maps live above the `styles` object; `<CategoryBar>` picks
+  // the variant via its `size` prop. Hover brightening still fires from
+  // the parent row (`&:hover [data-bar-fill]`), so it works regardless
+  // of which size variant the bar uses.
+  bar,
+  barFill,
+  stackedSegment,
+
+  // ── Multi-series internals ────────────────────────────────────────
+  // One [bar | value] flex row per series, inside `rowMulti`'s column.
+  multiBarRow: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 1,
+  },
+  multiBarContainer: {
+    flex: 1,
+  },
+
+  // ── Stacked-mode row ──────────────────────────────────────────────
+  // Mirror `rowMulti`'s outer shape (click target + hover brightening +
+  // focus ring) but stack three children vertically: header line, bar,
+  // breakdown line.
+  rowStacked: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 0.5,
+    cursor: 'pointer',
+    userSelect: 'none',
+    transition: 'background-color 80ms ease',
+    '&:hover [data-bar-fill="true"]': {
+      filter: 'brightness(1.2)',
+    },
+    '&:focus-visible': {
+      outline: '2px solid',
+      outlineColor: 'primary.main',
+      outlineOffset: -2,
+    },
+  },
+  stackedHeader: {
+    display: 'flex',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    gap: 1,
+  },
+  // Right-aligned total in the header. Tabular-nums keeps totals lined
+  // up vertically across rows; minWidth reuses the per-series-value
+  // column width so the right edge sits at the same spot as `rowMulti`'s
+  // value column when both modes co-exist in the same widget card.
+  stackedTotal: {
+    color: 'text.primary',
+    fontWeight: 'medium',
+    fontVariantNumeric: 'tabular-nums',
+    minWidth: 48,
+    textAlign: 'right',
+  },
+  // Flex row of "{seriesName}: {value}" pairs. Wraps gracefully when
+  // series names are long or there are many series.
+  stackedBreakdown: {
+    display: 'flex',
+    flexWrap: 'wrap',
+    columnGap: 2,
+    rowGap: 0.25,
+  },
+  stackedBreakdownItem: {
+    color: 'text.secondary',
+    fontVariantNumeric: 'tabular-nums',
+  },
+
+  // ── Legend (sticky bottom) ────────────────────────────────────────
+  legend: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 2,
+    flexWrap: 'wrap',
+    pt: 2,
+    mt: 2,
+    position: 'sticky',
+    bottom: 0,
+    bgcolor: 'background.paper',
+    borderTop: (theme: Theme) => `1px solid ${theme.palette.divider}`,
+  },
+  legendItem: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 1,
+  },
+  legendDot: {
+    width: 8,
+    height: 8,
+    borderRadius: '50%',
+  },
+  legendLabel: {
+    color: 'text.secondary',
+    textTransform: 'uppercase',
+    fontWeight: 'medium',
+  },
+
+  // ── "Other" overflow row ──────────────────────────────────────────
+  otherRow: {
+    display: 'flex',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    py: 0.5,
+    px: 0.5,
+  },
+  otherLabel: {
+    fontStyle: 'italic',
+    color: 'text.secondary',
+    fontWeight: 'medium',
+  },
+  otherCount: {
+    color: 'text.disabled',
+  },
+  // `bar` / `barFill` are size-keyed (`Record<CategorySize, SxProps>`);
+  // every other entry is a single `SxProps<Theme>`. The mixed shape means
+  // we can't apply the file-wide `satisfies Record<string, SxProps<Theme>>`
+  // constraint that the other widget style files use — consumers of
+  // individual tokens still get full type-checking at the call site via
+  // the typed `Box`/`Typography` `sx` prop.
+}