@carto/ps-react-ui 6.1.0 → 6.2.0

package/src/widgets/category/components/category-bar.tsx

@@ -1,4 +1,5 @@
 import type { CssColor } from '../../../components/types'
+import type { ReactNode } from 'react'
 import { Box } from '@mui/material'
 import type { CategorySize } from '../types'
 import { styles } from '../style'
@@ -6,8 +7,15 @@ import { styles } from '../style'
 export interface CategoryBarProps {
   /** Numeric value driving the fill width. */
   value: number
-  /** Denominator for the percentage fill. `0` → empty bar (no division by zero). */
+  /** Upper end of the domain. `maxValue === minValue` → empty bar (no division by zero). */
   maxValue: number
+  /**
+   * Lower end of the domain. `0` (default) keeps the positive-only bar
+   * anchored at the left edge; a negative value moves the zero to
+   * `-minValue / (maxValue - minValue)` and bars grow from there in either
+   * direction, keeping the fill `color` whatever the sign.
+   */
+  minValue?: number
   /** Fill color, already resolved by `CategoryUI.colorAt`. */
   color: CssColor
   /**
@@ -17,6 +25,11 @@ export interface CategoryBarProps {
    * size-invariant.
    */
   size?: CategorySize
+  /**
+   * Draw the zero tick when the domain is signed. `false` when the parent
+   * draws its own zero line (multi-series rows span it across every bar).
+   */
+  zeroTick?: boolean
 }
 
 /**
@@ -28,23 +41,66 @@ export interface CategoryBarProps {
 export function CategoryBar({
   value,
   maxValue,
+  minValue = 0,
   color,
   size = 'small',
+  zeroTick = true,
 }: CategoryBarProps) {
-  const pct = maxValue > 0 ? (value / maxValue) * 100 : 0
+  const range = maxValue - minValue
+  const leftPct =
+    range > 0 ? ((Math.min(0, value) - minValue) / range) * 100 : 0
+  const pct = range > 0 ? (Math.abs(value) / range) * 100 : 0
+  const hasZeroTick = zeroTick && minValue < 0 && maxValue > 0
   // Width + color rendered as inline `style` (not `sx`) to avoid
   // generating a new emotion class for every distinct value/color pair
   // — also makes the rendered DOM testable without computed-style math.
   return (
-    <Box sx={styles.bar[size]} data-size={size}>
+    <ZeroTickWrap zeroPct={hasZeroTick ? (-minValue / range) * 100 : undefined}>
+      <Box sx={styles.bar[size]} data-size={size}>
+        <Box
+          sx={styles.barFill[size]}
+          style={{
+            left: `${leftPct}%`,
+            width: `${pct}%`,
+            backgroundColor: color,
+            // The end that grows out of the zero is square; only the far
+            // end keeps the rounded corners.
+            ...(value < 0
+              ? { borderTopRightRadius: 0, borderBottomRightRadius: 0 }
+              : { borderTopLeftRadius: 0, borderBottomLeftRadius: 0 }),
+          }}
+          // Tag the fill so an ancestor row's `:hover` selector can target
+          // it (`&:hover [data-bar-fill]`) — the brightening affordance now
+          // fires from anywhere in the row, not only the bar track.
+          data-bar-fill='true'
+        />
+      </Box>
+    </ZeroTickWrap>
+  )
+}
+
+/**
+ * Wraps a bar track and, when `zeroPct` is set, marks the zero with a tick
+ * that overhangs the track. Positive-only, negative-only and all-zero bars
+ * pass `undefined` and get no tick.
+ */
+export function ZeroTickWrap({
+  zeroPct,
+  children,
+}: {
+  zeroPct: number | undefined
+  children: ReactNode
+}) {
+  if (zeroPct === undefined) return children
+  return (
+    <Box sx={styles.barWrap}>
       <Box
-        sx={styles.barFill[size]}
-        style={{ width: `${pct}%`, backgroundColor: color }}
-        // Tag the fill so an ancestor row's `:hover` selector can target
-        // it (`&:hover [data-bar-fill]`) — the brightening affordance now
-        // fires from anywhere in the row, not only the bar track.
-        data-bar-fill='true'
+        aria-hidden
+        data-zero-tick='true'
+        sx={styles.zeroTick}
+        style={{ left: `${zeroPct}%` }}
       />
+      {children}
     </Box>
   )
 }

package/src/widgets/category/components/category-row-multi.tsx

@@ -16,6 +16,8 @@ export interface CategoryRowMultiProps {
   colors: readonly CssColor[]
   /** Shared max across all series + rows (or `maxOverride`). */
   maxValue: number
+  /** Lower end of the shared domain (`0` for positive-only data). */
+  minValue?: number
   formatter: (n: number) => string
   selected: boolean
   onToggle: (name: CategoryKey) => void
@@ -41,11 +43,13 @@ export function CategoryRowMulti({
   values,
   colors,
   maxValue,
+  minValue,
   formatter,
   selected,
   onToggle,
   size,
 }: CategoryRowMultiProps) {
+  const min = minValue ?? 0
   const handleKey = (e: KeyboardEvent<HTMLDivElement>): void => {
     if (e.key === 'Enter' || e.key === ' ') {
       e.preventDefault()
@@ -64,6 +68,21 @@ export function CategoryRowMulti({
       <Typography variant='body2' sx={styles.multiName}>
         {displayName ?? name}
       </Typography>
+      {min < 0 && maxValue > 0 && (
+        <Box
+          aria-hidden
+          sx={styles.multiZeroArea}
+          // Row 1 is the label; the bars fill the next `values.length` rows.
+          // Placed before the bars so their tracks paint over the line.
+          style={{ gridRow: `2 / span ${values.length}` }}
+        >
+          <Box
+            data-zero-tick='true'
+            sx={styles.zeroTick}
+            style={{ left: `${(-min / (maxValue - min)) * 100}%` }}
+          />
+        </Box>
+      )}
       {values.map((v, i) => (
         // Multi-bar rows iterate per series — the bar belongs to series `i`,
         // and the row is keyed on the parent's `name`, so a composite of
@@ -73,8 +92,10 @@ export function CategoryRowMulti({
             <CategoryBar
               value={v}
               maxValue={maxValue}
+              minValue={minValue}
               color={colors[i] ?? ''}
               size={size}
+              zeroTick={false}
             />
           </Box>
           <Typography variant='body2' sx={styles.value}>

package/src/widgets/category/components/category-row-single.tsx

@@ -12,6 +12,8 @@ export interface CategoryRowSingleProps {
   displayName?: string | number
   value: number
   maxValue: number
+  /** Lower end of the shared domain (`0` for positive-only data). */
+  minValue?: number
   color: CssColor
   formatter: (n: number) => string
   selected: boolean
@@ -37,6 +39,7 @@ export function CategoryRowSingle({
   displayName,
   value,
   maxValue,
+  minValue,
   color,
   formatter,
   selected,
@@ -69,6 +72,7 @@ export function CategoryRowSingle({
       <CategoryBar
         value={value}
         maxValue={maxValue}
+        minValue={minValue}
         color={color}
         size={size}
       />

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

@@ -26,6 +26,11 @@ export interface CategoryRowStackedProps {
   onToggle: (name: CategoryKey) => void
   /** Bar visual density. Forwarded to the inner {@link CategoryBarStacked}. */
   size?: CategorySize
+  /**
+   * Where the list's zero sits (% of the track), shared by every row so the
+   * zero lines up: `0` positive-only, `50` signed, `100` negative-only.
+   */
+  zeroPct?: number
 }
 
 /**
@@ -41,6 +46,10 @@ export interface CategoryRowStackedProps {
  * total relative to other rows. The total numeric value is still shown in
  * the header so the per-row magnitude isn't lost.
  *
+ * Signed data diverges from `zeroPct`: positives stack rightwards and
+ * negatives leftwards, and whichever side is longer reaches its edge of the
+ * track. The header total is the signed sum.
+ *
  * 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
@@ -57,6 +66,7 @@ export function CategoryRowStacked({
   selected,
   onToggle,
   size,
+  zeroPct = 0,
 }: CategoryRowStackedProps) {
   const handleKey = (e: KeyboardEvent<HTMLDivElement>): void => {
     if (e.key === 'Enter' || e.key === ' ') {
@@ -65,6 +75,18 @@ export function CategoryRowStacked({
     }
   }
   const total = values.reduce((a, b) => a + b, 0)
+  let pos = 0
+  let neg = 0
+  for (const v of values) {
+    if (v > 0) pos += v
+    else neg -= v
+  }
+  // Magnitude that would fill the whole track, picked so the longer side
+  // just reaches its edge: `pos` spans `100 - zeroPct`, `neg` spans `zeroPct`.
+  const scale = Math.max(
+    zeroPct < 100 ? (pos * 100) / (100 - zeroPct) : 0,
+    zeroPct > 0 ? (neg * 100) / zeroPct : 0,
+  )
   return (
     <Box
       role='button'
@@ -85,7 +107,8 @@ export function CategoryRowStacked({
       <CategoryBarStacked
         values={values}
         colors={colors}
-        maxValue={total}
+        maxValue={scale}
+        zeroPct={zeroPct}
         size={size}
       />
       <Box sx={styles.stackedBreakdown}>

package/src/widgets/category/style.ts

@@ -28,17 +28,19 @@ const bar: Record<CategorySize, SxProps<Theme>> = {
 const barFill: Record<CategorySize, SxProps<Theme>> = {
   small: {
     position: 'absolute',
-    inset: '0 auto 0 0',
+    top: 0,
+    bottom: 0,
     borderRadius: 1,
     transition:
-      'width 300ms ease-in-out, background-color 150ms ease, filter 150ms ease',
+      'left 300ms ease-in-out, width 300ms ease-in-out, background-color 150ms ease, filter 150ms ease',
   },
   medium: {
     position: 'absolute',
-    inset: '0 auto 0 0',
+    top: 0,
+    bottom: 0,
     borderRadius: 0.25,
     transition:
-      'width 300ms ease-in-out, background-color 150ms ease, filter 150ms ease',
+      'left 300ms ease-in-out, width 300ms ease-in-out, background-color 150ms ease, filter 150ms ease',
   },
 }
 
@@ -71,13 +73,47 @@ export const styles = {
     position: 'relative',
     width: '100%',
   },
-  // Flat list of category rows. Holds both single + multi rows.
+  // Flat list of category rows. A grid rather than a flex column so the
+  // multi-series rows can share one value column through `subgrid`: with
+  // every bar track the same width, the zero ticks line up across rows.
   list: {
-    display: 'flex',
-    flexDirection: 'column',
+    position: 'relative',
+    display: 'grid',
+    gridTemplateColumns: 'minmax(0, 1fr)',
     gap: 1,
     py: 0.5,
   },
+  // Layered on `list` for unstacked multi-series: bars | values.
+  listMulti: {
+    gridTemplateColumns: 'minmax(0, 1fr) max-content',
+  },
+  // Zero tick for signed data: one per bar track, drawn outside the track's
+  // `overflow: hidden` so it can stand 6px proud of it on both sides.
+  // Tracks share a width (see `listMulti`), so the ticks line up by rows.
+  barWrap: {
+    position: 'relative',
+  },
+  // Multi-series rows draw one zero line through every series bar instead
+  // of a tick per bar: this box is the row's bar column (grid area set
+  // inline) and holds a `zeroTick`, so the line stays out of the label.
+  multiZeroArea: {
+    position: 'absolute',
+    inset: 0,
+    gridColumn: '1 / 2',
+    pointerEvents: 'none',
+  },
+  zeroTick: {
+    position: 'absolute',
+    top: -6,
+    bottom: -6,
+    width: '1px',
+    // Centred on the zero so both halves of the bar meet it evenly. No
+    // z-index: it comes before the track in the DOM, so the bar paints over
+    // it and only the overhang shows.
+    transform: 'translateX(-50%)',
+    bgcolor: 'text.disabled',
+    pointerEvents: 'none',
+  },
   // Layered on `list` only in scroll mode (`maxItems === 0`): right padding
   // so the bars + right-aligned values clear the scrollbar. Right side only
   // — the left edge stays at 0 so content stays aligned with the capped
@@ -91,6 +127,7 @@ export const styles = {
   // bar fills the row width below. Mirrors `rowMulti` for visual
   // consistency.
   rowSingle: {
+    gridColumn: '1 / -1',
     display: 'flex',
     flexDirection: 'column',
     gap: 0.5,
@@ -124,10 +161,14 @@ export const styles = {
   // 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.
+  // Spans the list and adopts its columns, so every row's value column is
+  // as wide as the widest value in the list.
   rowMulti: {
-    display: 'flex',
-    flexDirection: 'column',
-    gap: 0.5,
+    position: 'relative',
+    gridColumn: '1 / -1',
+    display: 'grid',
+    gridTemplateColumns: 'subgrid',
+    rowGap: 0.5,
     // py: 0.5,
     // px: 0.5,
     cursor: 'pointer',
@@ -155,6 +196,7 @@ export const styles = {
     fontWeight: 'medium',
   },
   multiName: {
+    gridColumn: '1 / -1',
     overflow: 'hidden',
     whiteSpace: 'nowrap',
     textOverflow: 'ellipsis',
@@ -171,6 +213,7 @@ export const styles = {
     // minWidth here is also harmless in that context.
     minWidth: 48,
     textAlign: 'right',
+    alignSelf: 'center',
   },
 
   // ── Bar (track + fill) ────────────────────────────────────────────
@@ -184,13 +227,12 @@ export const styles = {
 
   // ── Multi-series internals ────────────────────────────────────────
   // One [bar | value] flex row per series, inside `rowMulti`'s column.
+  // `contents` hands the bar and the value to `rowMulti`'s subgrid cells.
   multiBarRow: {
-    display: 'flex',
-    alignItems: 'center',
-    gap: 1,
+    display: 'contents',
   },
   multiBarContainer: {
-    flex: 1,
+    alignSelf: 'center',
   },
 
   // ── Stacked-mode row ──────────────────────────────────────────────
@@ -198,6 +240,7 @@ export const styles = {
   // focus ring) but stack three children vertically: header line, bar,
   // breakdown line.
   rowStacked: {
+    gridColumn: '1 / -1',
     display: 'flex',
     flexDirection: 'column',
     gap: 0.5,
@@ -285,6 +328,7 @@ export const styles = {
   // (no parentheses). Only the label is the click target when interactive;
   // the count is always static text beside it.
   otherRow: {
+    gridColumn: '1 / -1',
     display: 'flex',
     alignItems: 'center',
     gap: 1,

package/src/widgets/wrapper/style.ts

@@ -57,14 +57,50 @@ export const styles = {
     height: ({ spacing }: Theme) => spacing(0.35),
     zIndex: 1,
   },
+  // Title button, then Actions / Options, then the chevron, as siblings.
+  // Same spacing as when they all sat inside the summary: its 16px end
+  // padding moves to the row, the content's 6px end padding sits before
+  // the chevron.
+  header: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: ({ spacing }: Theme) => spacing(0.5),
+    minHeight: ({ spacing }: Theme) => spacing(7),
+    paddingInlineEnd: ({ spacing }: Theme) => spacing(2),
+  },
   summary: {
+    flex: 1,
+    minWidth: 0,
     minHeight: ({ spacing }: Theme) => spacing(7),
+    paddingInlineEnd: 0,
     '& .MuiAccordionSummary-content': {
-      gap: ({ spacing }: Theme) => spacing(0.5),
-      paddingInlineEnd: ({ spacing }: Theme) => spacing(0.75),
       alignItems: 'center',
+      minWidth: 0,
+      marginInlineEnd: 0,
+      paddingInlineEnd: 0,
     },
   },
+  // No chevron (disabled): keep the actions where they sat when the
+  // chevron's slot was empty — 10px further from the edge.
+  headerNoIcon: {
+    paddingInlineEnd: ({ spacing }: Theme) => spacing(3.25),
+  },
+  // Looks like the icon the summary used to render in its
+  // `expandIconWrapper`: 18px, secondary text colour, rotated when open.
+  expandIcon: {
+    display: 'flex',
+    marginInlineStart: ({ spacing }: Theme) => spacing(0.75),
+    color: 'text.secondary',
+    cursor: 'pointer',
+    '& svg': { width: 18, height: 18, color: 'inherit' },
+    transition: ({ transitions }: Theme) =>
+      transitions.create('transform', {
+        duration: transitions.duration.shortest,
+      }),
+  },
+  expanded: {
+    transform: 'rotate(180deg)',
+  },
   // Disabled state — only the collapse toggle is inert (enforced by the
   // guarded `onChange` handler, not `pointer-events`). Actions and Options in
   // the summary row, and the details panel, all keep their events. We just

package/src/widgets/wrapper/widget-actions.tsx

@@ -14,8 +14,8 @@ export interface ActionsProps {
  * pointer devices), and stay full-opacity when a descendant is marked with
  * `.active` — typically applied by toggled actions.
  *
- * The container also stops click propagation so interacting with an action
- * doesn't toggle the wrapper's collapse.
+ * The container also stops click propagation, so a click on an action never
+ * reaches handlers further up the widget.
  */
 export function Actions({ sx, children }: ActionsProps) {
   return (

package/src/widgets/wrapper/widget-wrapper.test.tsx

@@ -112,11 +112,41 @@ describe('<Wrapper>', () => {
     )
     const actionBtn = screen.getByTestId('action-btn')
     const bodyContent = screen.getByTestId('body-content')
-    // The action lives inside the AccordionSummary, the body inside AccordionDetails.
-    expect(actionBtn.closest('.MuiAccordionSummary-root')).not.toBeNull()
+    // The action lives in the header row, beside the summary button rather
+    // than inside it (a <button> can't contain another); the body lives in
+    // AccordionDetails.
+    expect(actionBtn.closest('.widget-wrapper-header')).not.toBeNull()
+    expect(actionBtn.closest('.MuiAccordionSummary-root')).toBeNull()
     expect(bodyContent.closest('.MuiAccordionDetails-root')).not.toBeNull()
   })
 
+  it('never nests a button inside another', () => {
+    const { container } = render(
+      withProvider(
+        'wrap-6b',
+        <Wrapper title='t'>
+          <Actions>
+            <button type='button'>A</button>
+          </Actions>
+        </Wrapper>,
+      ),
+    )
+    expect(container.querySelector('button button')).toBeNull()
+  })
+
+  it('clicking the chevron toggles the wrapper', () => {
+    const { container } = render(
+      withProvider('wrap-6c', <Wrapper title='t'>body</Wrapper>),
+    )
+    const summary = screen.getByRole('button', { name: 'Collapse' })
+    expect(summary.getAttribute('aria-expanded')).toBe('true')
+    const chevron = container.querySelector(
+      '.widget-wrapper-header [aria-hidden]',
+    )
+    fireEvent.click(chevron!)
+    expect(summary.getAttribute('aria-expanded')).toBe('false')
+  })
+
   it('shows a LinearProgress at the top when the store reports isFetching', () => {
     render(
       withProvider(

package/src/widgets/wrapper/widget-wrapper.tsx

@@ -54,8 +54,8 @@ export interface WrapperProps {
   variant?: 'outlined' | 'elevation'
   labels?: Partial<WrapperLabels>
   /**
-   * Icon shown at the right edge of the summary row. Accordion rotates it
-   * 180° automatically when the wrapper expands. Default: `ExpandMoreIcon`.
+   * Icon shown at the right edge of the header row, rotated 180° while the
+   * wrapper is expanded. Default: `ExpandMoreIcon`.
    */
   expandIcon?: ComponentType<SvgIconProps>
   iconProps?: SvgIconProps
@@ -117,10 +117,23 @@ export function Wrapper({
 
   const ariaLabel = effectiveCollapsed ? _labels.expand : _labels.collapse
 
+  const expanded = !effectiveCollapsed
+  const toggle = useCallback(
+    () => handleAccordionToggle(null, !expanded),
+    [handleAccordionToggle, expanded],
+  )
+
+  // The header row is the Accordion's first child, which MUI treats as its
+  // summary slot. Only the title sits inside `<AccordionSummary>` — it
+  // renders as a `<button>`, and Actions / Options hold buttons of their
+  // own, which HTML doesn't allow inside another button. They sit next to
+  // it instead, followed by the chevron: a pointer shortcut for the same
+  // toggle, hidden from assistive tech since the summary button already
+  // carries it.
   return (
     <Accordion
       data-collapsed={effectiveCollapsed ? 'true' : undefined}
-      expanded={!effectiveCollapsed}
+      expanded={expanded}
       onChange={handleAccordionToggle}
       disableGutters
       elevation={0}
@@ -131,41 +144,54 @@ export function Wrapper({
         ...sx,
       }}
     >
-      {isFetching ? (
-        <LinearProgress sx={styles.loading} color='primary' />
-      ) : null}
-
-      <AccordionSummary
-        expandIcon={
-          disabled ? null : <ExpandIcon fontSize='small' {...iconProps} />
-        }
-        aria-label={ariaLabel}
-        aria-disabled={disabled || undefined}
-        sx={{
-          ...styles.summary,
-          ...(disabled ? styles.summaryDisabled : null),
-        }}
+      <Box
+        className='widget-wrapper-header'
+        sx={{ ...styles.header, ...(disabled && styles.headerNoIcon) }}
       >
-        <SmartTooltip title={title}>
-          {({ ref }) => (
-            <Box sx={styles.titleCell}>
-              <Typography
-                ref={ref}
-                variant='subtitle1'
-                sx={[
-                  {
-                    textTransform: 'none',
-                  },
-                  styles.titleText,
-                ]}
-              >
-                {title}
-              </Typography>
-            </Box>
-          )}
-        </SmartTooltip>
+        {isFetching ? (
+          <LinearProgress sx={styles.loading} color='primary' />
+        ) : null}
+        <AccordionSummary
+          // The chevron is rendered after Actions below; `null` also keeps
+          // a theme-level default icon out of the summary.
+          expandIcon={null}
+          aria-label={ariaLabel}
+          aria-disabled={disabled || undefined}
+          sx={{
+            ...styles.summary,
+            ...(disabled ? styles.summaryDisabled : null),
+          }}
+        >
+          <SmartTooltip title={title}>
+            {({ ref }) => (
+              <Box sx={styles.titleCell}>
+                <Typography
+                  ref={ref}
+                  variant='subtitle1'
+                  sx={[
+                    {
+                      textTransform: 'none',
+                    },
+                    styles.titleText,
+                  ]}
+                >
+                  {title}
+                </Typography>
+              </Box>
+            )}
+          </SmartTooltip>
+        </AccordionSummary>
         {summarySlots}
-      </AccordionSummary>
+        {disabled ? null : (
+          <Box
+            aria-hidden
+            onClick={toggle}
+            sx={{ ...styles.expandIcon, ...(expanded && styles.expanded) }}
+          >
+            <ExpandIcon fontSize='small' {...iconProps} />
+          </Box>
+        )}
+      </Box>
       <AccordionDetails sx={styles.detail}>{detailsSlots}</AccordionDetails>
     </Accordion>
   )