Merge branch 'master' into feature/22834-expose-polar-geometry-hook

Author: mustafajw07

.gitignore

@@ -5,7 +5,11 @@
 .cursor
 .claude/settings.local.json
 .claude/worktrees/
+.claude/agents/
+.claude/helpers/
+.claude/commands/
 .claude/scheduled_tasks.lock
+.claude-flow
 .junie
 
 __diff_output__

docs/data/charts/bars/StackTotalLabels.js

@@ -0,0 +1,79 @@
+import * as React from 'react';
+import { ChartsContainer } from '@mui/x-charts/ChartsContainer';
+import { BarPlot } from '@mui/x-charts/BarChart';
+import { ChartsXAxis } from '@mui/x-charts/ChartsXAxis';
+import { ChartsYAxis } from '@mui/x-charts/ChartsYAxis';
+import {
+  getValueToPositionMapper,
+  useBarSeries,
+  useXScale,
+  useYScale,
+} from '@mui/x-charts/hooks';
+import { styled } from '@mui/material/styles';
+
+export default function StackTotalLabels() {
+  return (
+    <ChartsContainer
+      xAxis={[{ scaleType: 'band', data: ['Q1', 'Q2', 'Q3'] }]}
+      series={[
+        {
+          type: 'bar',
+          id: 'a',
+          stack: 'total',
+          data: [5, 17, 11],
+          barLabel: 'value',
+        },
+        { type: 'bar', id: 'b', stack: 'total', data: [4, 8, 6], barLabel: 'value' },
+      ]}
+      height={400}
+      yAxis={[{ width: 30 }]}
+      margin={{ left: 0, right: 10, top: 30 }}
+    >
+      <BarPlot />
+      <StackTotals />
+      <ChartsXAxis />
+      <ChartsYAxis />
+    </ChartsContainer>
+  );
+}
+
+function StackTotals() {
+  const xScale = useXScale();
+  const yScale = useYScale();
+  const barSeries = useBarSeries();
+
+  const xMapper = getValueToPositionMapper(xScale);
+  const yMapper = getValueToPositionMapper(yScale);
+
+  return (
+    <React.Fragment>
+      {xScale.domain().map((category, dataIndex) => {
+        const total = barSeries.reduce(
+          (acc, series) =>
+            acc + (series.stack === 'total' ? (series.data[dataIndex] ?? 0) : 0),
+          0,
+        );
+
+        return (
+          <TotalLabel
+            key={String(category)}
+            x={xMapper(category)}
+            y={yMapper(total) - 8}
+          >
+            {total}
+          </TotalLabel>
+        );
+      })}
+    </React.Fragment>
+  );
+}
+
+const TotalLabel = styled('text')(({ theme }) => ({
+  ...theme?.typography?.body2,
+  fontWeight: 600,
+  stroke: 'none',
+  fill: (theme.vars || theme)?.palette?.text?.primary,
+  textAnchor: 'middle',
+  dominantBaseline: 'auto',
+  pointerEvents: 'none',
+}));

docs/data/charts/bars/StackTotalLabels.tsx

@@ -0,0 +1,79 @@
+import * as React from 'react';
+import { ChartsContainer } from '@mui/x-charts/ChartsContainer';
+import { BarPlot } from '@mui/x-charts/BarChart';
+import { ChartsXAxis } from '@mui/x-charts/ChartsXAxis';
+import { ChartsYAxis } from '@mui/x-charts/ChartsYAxis';
+import {
+  getValueToPositionMapper,
+  useBarSeries,
+  useXScale,
+  useYScale,
+} from '@mui/x-charts/hooks';
+import { styled } from '@mui/material/styles';
+
+export default function StackTotalLabels() {
+  return (
+    <ChartsContainer
+      xAxis={[{ scaleType: 'band', data: ['Q1', 'Q2', 'Q3'] }]}
+      series={[
+        {
+          type: 'bar',
+          id: 'a',
+          stack: 'total',
+          data: [5, 17, 11],
+          barLabel: 'value',
+        },
+        { type: 'bar', id: 'b', stack: 'total', data: [4, 8, 6], barLabel: 'value' },
+      ]}
+      height={400}
+      yAxis={[{ width: 30 }]}
+      margin={{ left: 0, right: 10, top: 30 }}
+    >
+      <BarPlot />
+      <StackTotals />
+      <ChartsXAxis />
+      <ChartsYAxis />
+    </ChartsContainer>
+  );
+}
+
+function StackTotals() {
+  const xScale = useXScale();
+  const yScale = useYScale();
+  const barSeries = useBarSeries();
+
+  const xMapper = getValueToPositionMapper(xScale);
+  const yMapper = getValueToPositionMapper(yScale);
+
+  return (
+    <React.Fragment>
+      {xScale.domain().map((category, dataIndex) => {
+        const total = barSeries.reduce(
+          (acc, series) =>
+            acc + (series.stack === 'total' ? (series.data[dataIndex] ?? 0) : 0),
+          0,
+        );
+
+        return (
+          <TotalLabel
+            key={String(category)}
+            x={xMapper(category)}
+            y={yMapper(total) - 8}
+          >
+            {total}
+          </TotalLabel>
+        );
+      })}
+    </React.Fragment>
+  );
+}
+
+const TotalLabel = styled('text')(({ theme }) => ({
+  ...theme?.typography?.body2,
+  fontWeight: 600,
+  stroke: 'none',
+  fill: (theme.vars || theme)?.palette?.text?.primary,
+  textAnchor: 'middle',
+  dominantBaseline: 'auto',
+  pointerEvents: 'none',
+}));

docs/data/charts/bars/bars.md

@@ -219,6 +219,15 @@ The example below positions the labels above the bars they refer to.
 
 {{"demo": "LabelsAboveBars.js"}}
 
+### Stack total labels
+
+The `barLabel` property only has access to a single bar, so it can't display a stack's total.
+To show it, render a custom component as a child of the chart container.
+
+The example below sums the series with the [`useBarSeries`](/x/react-charts/hooks/use-series/) hook and positions each total with the [`useXScale`](/x/react-charts/hooks/use-scale/) and [`useYScale`](/x/react-charts/hooks/use-scale/) scales.
+
+{{"demo": "StackTotalLabels.js"}}
+
 ## Click events
 
 Bar charts provide two click handlers:

docs/data/charts/bubble/ScatterZAxis.js

@@ -0,0 +1,207 @@
+import * as React from 'react';
+import { ScatterChart } from '@mui/x-charts/ScatterChart';
+import { ChartsTooltipContainer, useItemTooltip } from '@mui/x-charts/ChartsTooltip';
+import Stack from '@mui/material/Stack';
+import Box from '@mui/material/Box';
+import Divider from '@mui/material/Divider';
+import Paper from '@mui/material/Paper';
+import Typography from '@mui/material/Typography';
+import { useZAxis } from '@mui/x-charts/hooks';
+import { irisData } from '../dataset/irisDataset';
+
+const species = ['Setosa', 'Versicolor', 'Virginica'];
+const speciesColors = ['#2e7d32', '#ed6c02', '#9c27b0'];
+const speciesPredictionColors = ['#5aa35e', '#be7f4b', '#ba68c9'];
+
+function IrisMarker(props) {
+  const { x, y, color, size, isHighlighted, isFaded, dataIndex, ...other } = props;
+
+  // Get and use color/size scale to determine stroke color and width based on prediction and confidence z-axes.
+  const predictionAxis = useZAxis('prediction');
+  const confidenceAxis = useZAxis('confidence');
+  const strokeWidth =
+    confidenceAxis?.sizeScale?.(confidenceAxis.data?.[dataIndex]) ?? 0;
+  const strokeColor =
+    predictionAxis?.colorScale?.(predictionAxis.data?.[dataIndex]) ?? 'gray';
+
+  const r = (isHighlighted ? 1.2 : 1) * size;
+  return (
+    <circle
+      cx={0}
+      cy={0}
+      r={r}
+      transform={`translate(${x}, ${y})`}
+      fill={color}
+      fillOpacity={isFaded ? 0.15 : 0.35}
+      stroke={strokeColor}
+      strokeWidth={strokeWidth}
+      strokeOpacity={isFaded ? 0.3 : 1}
+      cursor={other.onClick ? 'pointer' : 'unset'}
+      {...other}
+    />
+  );
+}
+
+/**
+ * Explains how the scatter plot encodes multiple dimensions of the dataset.
+ */
+function IrisAnnotation() {
+  return (
+    <Typography variant="caption" sx={{ textAlign: 'center' }}>
+      Fill color represents the actual species, stroke color represents the predicted
+      species, bubble size represents petal length, and stroke width represents
+      prediction confidence.
+    </Typography>
+  );
+}
+
+function IrisTooltip() {
+  return (
+    <ChartsTooltipContainer trigger="item">
+      <IrisTooltipContent />
+    </ChartsTooltipContainer>
+  );
+}
+
+function IrisTooltipContent() {
+  const item = useItemTooltip();
+
+  function numberFormatter(value) {
+    if (typeof value === 'number') {
+      return new Intl.NumberFormat('en-US').format(value);
+    }
+    return String(value);
+  }
+
+  // Get the full data item from irisData using dataIndex from identifier
+  const dataIndex = item?.identifier.dataIndex;
+  const dataItem = dataIndex !== undefined ? irisData[dataIndex] : null;
+
+  if (!item || !dataItem) {
+    return null;
+  }
+
+  return (
+    <Paper sx={{ p: 1.5 }} elevation={4}>
+      <Box
+        sx={{ display: 'flex', flexDirection: 'row', alignItems: 'center', mb: 1 }}
+      >
+        <Box
+          sx={{
+            width: 20,
+            height: 20,
+            backgroundColor: item?.color,
+            borderRadius: 1,
+            mr: 2,
+          }}
+        />
+        <Typography sx={{ fontWeight: 600 }}>{dataItem.species}</Typography>
+      </Box>
+      <Divider sx={{ my: 1 }} />
+      <Box sx={{ display: 'grid', gridTemplateColumns: '1fr', gap: 0.75 }}>
+        <Box sx={{ display: 'flex', justifyContent: 'space-between' }}>
+          <Typography variant="caption">Sepal Length:</Typography>
+          <Typography variant="caption" sx={{ fontWeight: 500 }}>
+            {numberFormatter(dataItem.sepalLength)} cm
+          </Typography>
+        </Box>
+        <Box sx={{ display: 'flex', justifyContent: 'space-between' }}>
+          <Typography variant="caption">Sepal Width:</Typography>
+          <Typography variant="caption" sx={{ fontWeight: 500 }}>
+            {numberFormatter(dataItem.sepalWidth)} cm
+          </Typography>
+        </Box>
+        <Box sx={{ display: 'flex', justifyContent: 'space-between' }}>
+          <Typography variant="caption">Petal Length:</Typography>
+          <Typography variant="caption" sx={{ fontWeight: 500 }}>
+            {numberFormatter(dataItem.petalLength)} cm
+          </Typography>
+        </Box>
+        <Box sx={{ display: 'flex', justifyContent: 'space-between' }}>
+          <Typography variant="caption">Petal Width:</Typography>
+          <Typography variant="caption" sx={{ fontWeight: 500 }}>
+            {numberFormatter(dataItem.petalWidth)} cm
+          </Typography>
+        </Box>
+        <Divider sx={{ my: 0.5 }} />
+        <Box sx={{ display: 'flex', justifyContent: 'space-between' }}>
+          <Typography variant="caption">Predicted:</Typography>
+          <Typography variant="caption" sx={{ fontWeight: 500 }}>
+            {dataItem.prediction}
+          </Typography>
+        </Box>
+        <Box sx={{ display: 'flex', justifyContent: 'space-between' }}>
+          <Typography variant="caption">Confidence:</Typography>
+          <Typography variant="caption" sx={{ fontWeight: 500 }}>
+            {numberFormatter(dataItem.confidence)}%
+          </Typography>
+        </Box>
+      </Box>
+    </Paper>
+  );
+}
+
+export default function ScatterZAxis() {
+  return (
+    <Stack sx={{ width: '100%' }}>
+      <ScatterChart
+        dataset={irisData}
+        height={300}
+        grid={{ horizontal: true, vertical: true }}
+        series={[
+          {
+            id: 'data',
+            colorAxisId: 'species',
+            sizeAxisId: 'petal',
+            datasetKeys: { x: 'sepalLength', y: 'sepalWidth' },
+            highlightScope: { highlight: 'item', fade: 'global' },
+          },
+        ]}
+        xAxis={[{ label: 'Sepal length (cm)' }]}
+        yAxis={[{ label: 'Sepal width (cm)' }]}
+        zAxis={[
+          {
+            id: 'species',
+            dataKey: 'species',
+            colorMap: {
+              type: 'ordinal',
+              values: species,
+              colors: speciesColors,
+            },
+          },
+          {
+            id: 'petal',
+            dataKey: 'petalLength',
+            sizeMap: {
+              type: 'continuous',
+              min: 1,
+              max: 7,
+              size: [3, 10],
+            },
+          },
+          {
+            id: 'prediction',
+            dataKey: 'prediction',
+            colorMap: {
+              type: 'ordinal',
+              values: species,
+              colors: speciesPredictionColors,
+            },
+          },
+          {
+            id: 'confidence',
+            dataKey: 'confidence',
+            sizeMap: {
+              type: 'continuous',
+              min: Math.min(...irisData.map((item) => item.confidence)),
+              max: 100,
+              size: [0.5, 3],
+            },
+          },
+        ]}
+        slots={{ marker: IrisMarker, tooltip: IrisTooltip }}
+      ></ScatterChart>
+      <IrisAnnotation />
+    </Stack>
+  );
+}