@multiplatform.one/components 7.7.6 → 7.8.0

package/src/charts/PieChart.tsx

@@ -2,11 +2,13 @@ import { useResolvedKnobs } from "@multiplatform.one/theme";
 import { useTranslation } from "../shared/i18n";
 import { Text, XStack, YStack, type YStackProps } from "tamagui";
 import { componentColors } from "../componentColors";
+import { ChartDataFrame } from "./ChartDataView";
 import { ChartSurface } from "./ChartSurface";
-import { describeChart, describeDatum } from "./accessibility";
+import { chartDatumText, describeChart, describeDatum } from "./accessibility";
 import { resolveSeriesFills } from "./composeChart";
-import { formatChartValue } from "./math";
+import { formatChartValue, pieSlices, canMaskPieSlices } from "./math";
 import { PieSeries } from "./series";
+import { chartDatumTextProps, chartWebProps } from "./svg";
 import type { ChartDatum, ChartDatumEvents } from "./types";
 import { useChartTheme } from "./useChartTheme";
 
@@ -21,7 +23,7 @@ export interface PieChartProps
    * innerRadius) — the card surface shows through on every platform.
    */
   donut?: boolean | number;
-  /** Radians between slices (default 0). */
+  /** Explicit radians between slices. Omit for the default boundary mask. */
   padAngle?: number;
   /** Explicit slice colors (data values — pass through untouched). */
   colors?: string[];
@@ -51,7 +53,7 @@ export function PieChart({
   data,
   height = 200,
   donut = false,
-  padAngle = 0,
+  padAngle,
   colors,
   showLegend = true,
   valueFormatter,
@@ -81,7 +83,7 @@ export function PieChart({
   const innerRatio =
     donut === false ? 0 : donut === true ? DEFAULT_DONUT_RATIO : Math.min(Math.max(donut, 0), 0.9);
 
-  return (
+  const chart = (
     // LC-10: `flexShrink` + `minWidth 0` let a row parent (e.g. Card.Footer)
     // constrain the chart below its intrinsic width — the wrap then stacks
     // the legend under the pie instead of painting past the frame.
@@ -91,10 +93,25 @@ export function PieChart({
       flexShrink={1}
       minWidth={0}
       {...knobProps.gap}
+      {...chartWebProps({ "data-mpo-chart-owner": "true" })}
       {...stackProps}
     >
       <YStack width={height} height={height}>
-        <ChartSurface label={ariaLabel} height={height} width={height}>
+        <ChartSurface
+          label={ariaLabel}
+          proof={{
+            kind: innerRatio > 0 ? "donut" : "pie",
+            separated:
+              padAngle === undefined
+                ? canMaskPieSlices(pieSlices(data), (height / 2) * innerRatio, height / 2)
+                : padAngle > 0,
+            datumText: showLegend,
+            datumValues: chartDatumText(data, valueFormatter),
+            datumCount: data.length,
+          }}
+          height={height}
+          width={height}
+        >
           {(size) => {
             const outerRadius = Math.min(size.width, size.height) / 2;
             return (
@@ -129,7 +146,13 @@ export function PieChart({
           {...{ "data-pie-legend": "true" }}
         >
           {data.map((datum, index) => (
-            <XStack key={`${datum.label}-${index}`} gap="$2" alignItems="center" minWidth={0}>
+            <XStack
+              key={`${datum.label}-${index}`}
+              {...chartDatumTextProps(index)}
+              gap="$2"
+              alignItems="center"
+              minWidth={0}
+            >
               {/* Legend keys are chart CHROME, not marks: the swatch follows
                   the radius knob and goes square in the `none` world (Axiom 3
                   NULL). The pinned $2 arc was knob-dead (D-09 / LC-60). */}
@@ -142,10 +165,22 @@ export function PieChart({
               />
               {/* The label yields (truncates) before the value — values are
                   data and never truncate (Axiom 11). */}
-              <Text fontSize="$2" color={componentColors.text.muted} flex={1} numberOfLines={1}>
+              <Text
+                {...chartWebProps({ "data-mpo-chart-datum-label": "true" })}
+                {...knobProps.body}
+                fontSize="$2"
+                color={componentColors.text.muted}
+                flex={1}
+                numberOfLines={1}
+              >
                 {datum.label}
               </Text>
-              <Text fontSize="$2" fontWeight="500" flexShrink={0}>
+              <Text
+                {...chartWebProps({ "data-mpo-chart-datum-value": "true" })}
+                {...knobProps.body}
+                fontSize="$2"
+                flexShrink={0}
+              >
                 {format(datum.value)}
               </Text>
             </XStack>
@@ -154,4 +189,11 @@ export function PieChart({
       ) : null}
     </XStack>
   );
+  return showLegend ? (
+    chart
+  ) : (
+    <ChartDataFrame data={data} title={title} valueFormatter={valueFormatter}>
+      {chart}
+    </ChartDataFrame>
+  );
 }

package/src/charts/Sparkline.tsx

@@ -1,7 +1,7 @@
 import { useTranslation } from "../shared/i18n";
 import type { YStackProps } from "tamagui";
 import { ChartSurface } from "./ChartSurface";
-import { describeChart } from "./accessibility";
+import { chartDatumText, describeChart } from "./accessibility";
 import { createLinearScale, createPointScale, valueDomain } from "./math";
 import { AreaSeries, LineSeries } from "./series";
 import type { ChartCurve, ChartDatum } from "./types";
@@ -24,6 +24,8 @@ export interface SparklineProps extends Omit<YStackProps, "children" | "width" |
   title?: string;
   /** Override the generated accessible summary. */
   label?: string;
+  /** Format spoken and complete data-view values consistently. */
+  valueFormatter?: (value: number) => string;
 }
 
 /**
@@ -41,6 +43,7 @@ export function Sparkline({
   strokeWidth = 1.5,
   title,
   label,
+  valueFormatter,
   ...stackProps
 }: SparklineProps) {
   const { t } = useTranslation();
@@ -49,10 +52,29 @@ export function Sparkline({
   const normalized: ChartDatum[] = data.map((entry, index) =>
     typeof entry === "number" ? { label: String(index + 1), value: entry } : entry,
   );
-  const ariaLabel = label ?? describeChart({ typeLabel: t("Sparkline"), title, data: normalized });
+  const ariaLabel =
+    label ??
+    describeChart({
+      typeLabel: t("Sparkline"),
+      title,
+      data: normalized,
+      formatValue: valueFormatter,
+    });
 
   return (
-    <ChartSurface label={ariaLabel} height={height} width={width} {...stackProps}>
+    <ChartSurface
+      label={ariaLabel}
+      proof={{
+        kind: showArea ? "area" : "line",
+        separated: false,
+        datumText: false,
+        datumValues: chartDatumText(normalized, valueFormatter),
+        datumCount: normalized.length,
+      }}
+      height={height}
+      width={width}
+      {...stackProps}
+    >
       {(size) => {
         if (normalized.length === 0) return null;
         const inset = strokeWidth + 1;

package/src/charts/accessibility.ts

@@ -74,3 +74,11 @@ export function describeDatum(input: DescribeDatumInput): string {
   }
   return base;
 }
+
+/** Exact datum text for the independently opened data view, separate from the image name. */
+export function chartDatumText(
+  data: ChartDatum[],
+  formatValue = formatChartValue,
+): Array<[string, string]> {
+  return data.map((datum) => [datum.label.trim(), formatValue(datum.value).trim()]);
+}

package/src/charts/charts.spec.tsx

@@ -46,7 +46,26 @@ function targetRects(): Element[] {
 // In happy-dom onLayout never fires, so every chart passes an explicit width.
 const WIDTH = 400;
 
+it("routes stock Sparkline as a declared area or line with its complete data count", () => {
+  const { rerender } = renderWithProviders(<Sparkline data={[1, 2, 3]} width={WIDTH} />);
+  expect(document.querySelector("svg")?.getAttribute("data-mpo-chart")).toBe("area");
+  expect(document.querySelector("svg")?.getAttribute("data-mpo-chart-datum-count")).toBe("3");
+  expect(document.querySelector("svg")?.getAttribute("data-mpo-chart-datum-text")).toBe("false");
+  rerender(<Sparkline data={[1, 2, 3]} width={WIDTH} showArea={false} />);
+  expect(document.querySelector("svg")?.getAttribute("data-mpo-chart")).toBe("line");
+});
+
 describe("BarChart", () => {
+  it("declares chart kind and marks without claiming a complete datum alternative", () => {
+    renderWithProviders(<BarChart data={data} width={WIDTH} onDatumPress={vi.fn()} />);
+    const root = document.querySelector("svg")!;
+    expect(root.getAttribute("data-mpo-chart")).toBe("bar");
+    expect(root.getAttribute("data-mpo-chart-datum-count")).toBe(String(data.length));
+    expect(root.getAttribute("data-mpo-chart-datum-text")).toBe("false");
+    expect(root.querySelectorAll("[data-mpo-chart-mark]").length).toBe(data.length);
+    expect(targetRects().every((target) => !target.hasAttribute("data-mpo-chart-mark"))).toBe(true);
+  });
+
   it("renders one identity-colored bar per datum (single series, LC-27)", () => {
     const palette: { current?: ChartPalette } = {};
     renderWithProviders(
@@ -167,6 +186,12 @@ describe("BarChart", () => {
 });
 
 describe("LineChart / AreaChart", () => {
+  it("distinguishes area composition from a plain line", () => {
+    const { rerender } = renderWithProviders(<LineChart data={data} width={WIDTH} />);
+    expect(document.querySelector("svg")?.getAttribute("data-mpo-chart")).toBe("line");
+    rerender(<AreaChart data={data} width={WIDTH} />);
+    expect(document.querySelector("svg")?.getAttribute("data-mpo-chart")).toBe("area");
+  });
   it("strokes the line and dots with the palette identity", () => {
     const palette: { current?: ChartPalette } = {};
     renderWithProviders(
@@ -201,7 +226,7 @@ describe("LineChart / AreaChart", () => {
         <AreaChart data={data} width={WIDTH} />
       </>,
     );
-    const area = Array.from(document.querySelectorAll("svg path")).find(
+    const area = Array.from(document.querySelectorAll("svg [data-mpo-chart-mark]")).find(
       (p) => p.getAttribute("fill") !== "none" && p.getAttribute("opacity"),
     );
     expect(area).toBeDefined();
@@ -210,12 +235,61 @@ describe("LineChart / AreaChart", () => {
 });
 
 describe("PieChart", () => {
+  it("exposes every datum alternative without a twelve-item cap", () => {
+    const many = Array.from({ length: 13 }, (_, index) => ({
+      label: `Region ${index}`,
+      value: index + 1,
+    }));
+    renderWithProviders(<PieChart data={many} donut />);
+    const root = document.querySelector("svg")!;
+    expect(root.getAttribute("data-mpo-chart")).toBe("donut");
+    expect(root.getAttribute("data-mpo-chart-datum-count")).toBe("13");
+    expect(root.getAttribute("data-mpo-chart-separated")).toBe("true");
+    expect(document.querySelectorAll("[data-mpo-chart-datum-label]").length).toBe(13);
+    expect(document.querySelectorAll("[data-mpo-chart-datum-value]").length).toBe(13);
+    expect(root.querySelectorAll("[data-mpo-chart-mark]").length).toBe(13);
+  });
+
   const pieData: ChartDatum[] = [
     { label: "A", value: 4 },
     { label: "B", value: 3 },
     { label: "C", value: 2 },
   ];
 
+  it("keeps mask IDs unique across mounted charts and preserves the actual slice path", () => {
+    renderWithProviders(
+      <>
+        <PieChart data={pieData} />
+        <PieChart data={pieData} donut />
+      </>,
+    );
+    const masks = Array.from(document.querySelectorAll("mask"));
+    expect(masks).toHaveLength(6);
+    expect(new Set(masks.map((mask) => mask.id)).size).toBe(6);
+    for (const mark of document.querySelectorAll("[data-mpo-chart-mark]")) {
+      const id = mark.getAttribute("mask")!.slice(5, -1);
+      const mask = document.getElementById(id)!;
+      expect(mask.getAttribute("mask-type")).toBe("luminance");
+      expect(mask.children[0].getAttribute("d")).toBe(mark.getAttribute("d"));
+    }
+  });
+
+  it.each([
+    { data: pieData, padAngle: 0 },
+    {
+      data: [
+        { label: "Large", value: 9999 },
+        { label: "Small", value: 1 },
+      ],
+    },
+    { data: [{ label: "Only", value: 1 }] },
+  ])("preserves explicit zero, thin positives and single-datum geometry: %j", (props) => {
+    renderWithProviders(<PieChart {...props} />);
+    expect(document.querySelectorAll("mask")).toHaveLength(0);
+    expect(document.querySelectorAll("[data-mpo-chart-mark]")).toHaveLength(props.data.length);
+    expect(document.querySelector("svg")?.getAttribute("data-mpo-chart-separated")).toBe("false");
+  });
+
   it("slices take the categorical palette in data order", () => {
     const palette: { current?: ChartPalette } = {};
     renderWithProviders(
@@ -224,7 +298,7 @@ describe("PieChart", () => {
         <PieChart data={pieData} showLegend={false} />
       </>,
     );
-    const fills = Array.from(document.querySelectorAll("svg path")).map((p) =>
+    const fills = Array.from(document.querySelectorAll("svg [data-mpo-chart-mark]")).map((p) =>
       p.getAttribute("fill"),
     );
     expect(fills).toEqual(palette.current?.categorical.slice(0, pieData.length));
@@ -239,7 +313,7 @@ describe("PieChart", () => {
   it("per-slice press targets carry share-aware names", () => {
     const onDatumPress = vi.fn();
     renderWithProviders(<PieChart data={pieData} showLegend={false} onDatumPress={onDatumPress} />);
-    const slices = Array.from(document.querySelectorAll("svg path"));
+    const slices = Array.from(document.querySelectorAll("svg [data-mpo-chart-mark]"));
     expect(slices[0].getAttribute("aria-label")).toBe("A: 4 (44%)");
     fireEvent.click(slices[1]);
     expect(onDatumPress).toHaveBeenCalledWith(pieData[1], 1);

package/src/charts/index.ts

@@ -77,3 +77,5 @@ export { BarChart, type BarChartProps } from "./BarChart";
 export { AreaChart, LineChart, type AreaChartProps, type LineChartProps } from "./LineChart";
 export { PieChart, type PieChartProps } from "./PieChart";
 export { Sparkline, type SparklineProps } from "./Sparkline";
+
+export { ChartDataView, type ChartDataViewProps } from "./ChartDataView";

package/src/charts/math.spec.ts

@@ -13,10 +13,29 @@ import {
   getTimeTicks,
   linePath,
   pieSlices,
+  canMaskPieSlices,
   truncateLabel,
   valueDomain,
 } from "./math";
 
+describe("pie mask preserves a positive interior", () => {
+  const slices = (values: number[]) => pieSlices(values.map((value) => ({ value })));
+  it("accepts ordinary pie and donut slices including a wedge larger than pi", () => {
+    expect(canMaskPieSlices(slices([70, 20, 10]), 0, 100)).toBe(true);
+    expect(canMaskPieSlices(slices([70, 20, 10]), 55, 100)).toBe(true);
+  });
+  it("keeps the whole original chart when one positive slice is too thin", () => {
+    expect(canMaskPieSlices(slices([9999, 1]), 0, 100)).toBe(false);
+    expect(canMaskPieSlices(slices([9999, 1]), 55, 100)).toBe(false);
+    expect(canMaskPieSlices(slices([50, 50]), 99, 100)).toBe(false);
+  });
+  it("does not erode a single positive full circle or invalid geometry", () => {
+    expect(canMaskPieSlices(slices([100]), 0, 100)).toBe(false);
+    expect(canMaskPieSlices(slices([0, 100]), 55, 100)).toBe(false);
+    expect(canMaskPieSlices(slices([50, 50]), 0, NaN)).toBe(false);
+  });
+});
+
 describe("charts/math scales", () => {
   it("band scale maps categories into the pixel range with padding", () => {
     const scale = createBandScale({ domain: ["a", "b", "c"], range: [0, 300] });

package/src/charts/math.ts

@@ -234,6 +234,42 @@ export function pieSlices<T extends { value: number }>(
   }));
 }
 
+/**
+ * Sufficient interior witness for a two-unit boundary erosion. The bisector
+ * at the annulus midpoint must stay more than one unit from every boundary.
+ * Distance to a radial segment uses clamped projection, including its inner
+ * endpoint for wedges larger than pi. A small margin covers SVG's three-digit
+ * path rounding. One thin positive slice keeps the whole chart unmasked.
+ */
+export function canMaskPieSlices(
+  slices: ReadonlyArray<{ value: number; startAngle: number; endAngle: number }>,
+  innerRadius: number,
+  outerRadius: number,
+): boolean {
+  const positive = slices.filter((slice) => slice.value > 0);
+  if (
+    positive.length < 2 ||
+    !Number.isFinite(innerRadius) ||
+    !Number.isFinite(outerRadius) ||
+    innerRadius < 0 ||
+    outerRadius <= innerRadius
+  )
+    return false;
+  const radius = (innerRadius + outerRadius) / 2;
+  const clearance = 1.002;
+  if (outerRadius - radius <= clearance || radius - innerRadius <= clearance) return false;
+  return positive.every((slice) => {
+    const span = slice.endAngle - slice.startAngle;
+    if (!Number.isFinite(span) || span <= 0 || span >= Math.PI * 2) return false;
+    const cosine = Math.cos(span / 2);
+    const projection = Math.min(outerRadius, Math.max(innerRadius, radius * cosine));
+    const radialDistance = Math.sqrt(
+      Math.max(0, radius ** 2 + projection ** 2 - 2 * radius * projection * cosine),
+    );
+    return radialDistance > clearance;
+  });
+}
+
 export interface ArcPathInput {
   startAngle: number;
   endAngle: number;

package/src/charts/series.tsx

@@ -1,7 +1,19 @@
 import { MIN_PRESS_TARGET } from "@multiplatform.one/theme";
 import type { ScaleBand, ScaleLinear } from "d3-scale";
-import { areaPath, arcPath, linePath, pieSlices } from "./math";
-import { Circle, G, Path, Rect, datumTargetProps } from "./svg";
+import { useId } from "react";
+import { areaPath, arcPath, linePath, pieSlices, canMaskPieSlices } from "./math";
+import {
+  Circle,
+  Defs,
+  Mask,
+  G,
+  Path,
+  Rect,
+  datumTargetProps,
+  chartMarkProps,
+  chartWebProps,
+  luminanceMaskProps,
+} from "./svg";
 import type {
   ChartCurve,
   ChartDatum,
@@ -79,6 +91,7 @@ export function BarSeries({ data, xScale, yScale, plot, fills, ...callbacks }: B
         return (
           <G key={`${datum.label}-${index}`}>
             <Rect
+              {...chartMarkProps(datum.label)}
               x={x}
               y={y}
               width={bandwidth}
@@ -147,10 +160,23 @@ export function LineSeries({
   const targetRadius = MIN_PRESS_TARGET / 2;
   return (
     <G>
-      <Path d={linePath(points, { curve })} fill="none" stroke={color} strokeWidth={strokeWidth} />
+      <Path
+        {...chartMarkProps("series line")}
+        d={linePath(points, { curve })}
+        fill="none"
+        stroke={color}
+        strokeWidth={strokeWidth}
+      />
       {showPoints
         ? points.map((point, index) => (
-            <Circle key={`point-${index}`} cx={point.x} cy={point.y} r={pointRadius} fill={color} />
+            <Circle
+              key={`point-${index}`}
+              {...chartMarkProps(data[index]?.label ?? `point ${index + 1}`)}
+              cx={point.x}
+              cy={point.y}
+              r={pointRadius}
+              fill={color}
+            />
           ))
         : null}
       {interactive
@@ -187,7 +213,14 @@ export interface AreaSeriesProps {
  * LineSeries on top, which owns points and hit targets.
  */
 export function AreaSeries({ points, baseline, color, opacity = 0.18, curve }: AreaSeriesProps) {
-  return <Path d={areaPath(points, { baseline, curve })} fill={color} opacity={opacity} />;
+  return (
+    <Path
+      {...chartMarkProps("series area")}
+      d={areaPath(points, { baseline, curve })}
+      fill={color}
+      opacity={opacity}
+    />
+  );
 }
 
 // ── Pie / Donut ───────────────────────────────────────────────
@@ -200,7 +233,7 @@ export interface PieSeriesProps extends DatumTargetCallbacks {
   outerRadius: number;
   /** > 0 renders a donut with a true transparent hole. */
   innerRadius?: number;
-  /** Radians between slices (default 0). */
+  /** Explicit radians between slices. Omit for the default boundary mask. */
   padAngle?: number;
   /** Resolved fill per datum index. */
   fills: string[];
@@ -218,28 +251,75 @@ export function PieSeries({
   cy,
   outerRadius,
   innerRadius = 0,
-  padAngle = 0,
+  padAngle,
   fills,
   ...callbacks
 }: PieSeriesProps) {
+  const instanceId = useId().replace(/[^a-zA-Z0-9_-]/g, "_");
   const slices = pieSlices(data, { padAngle });
+  const maskGaps = padAngle === undefined && canMaskPieSlices(slices, innerRadius, outerRadius);
   const interactive = hasTargets(callbacks);
   return (
     <G transform={`translate(${cx}, ${cy})`}>
-      {slices.map((slice) => (
-        <Path
-          key={`${slice.datum.label}-${slice.index}`}
-          d={arcPath({
-            startAngle: slice.startAngle,
-            endAngle: slice.endAngle,
-            padAngle: slice.padAngle,
-            innerRadius,
-            outerRadius,
-          })}
-          fill={fills[slice.index]}
-          {...(interactive ? targetPropsFor(callbacks, slice.datum, slice.index) : {})}
-        />
-      ))}
+      {slices.map((slice) => {
+        const path = arcPath({
+          startAngle: slice.startAngle,
+          endAngle: slice.endAngle,
+          padAngle: slice.padAngle,
+          innerRadius,
+          outerRadius,
+        });
+        const masked = maskGaps && slice.value > 0;
+        const maskId = `mpo-pie-${instanceId}-${slice.index}`;
+        return (
+          <G key={`${slice.datum.label}-${slice.index}`}>
+            {masked ? (
+              <Defs>
+                <Mask
+                  id={maskId}
+                  x={-outerRadius - 2}
+                  y={-outerRadius - 2}
+                  width={(outerRadius + 2) * 2}
+                  height={(outerRadius + 2) * 2}
+                  maskUnits="userSpaceOnUse"
+                  maskContentUnits="userSpaceOnUse"
+                  {...luminanceMaskProps()}
+                >
+                  <Path
+                    d={path}
+                    fill="#ffffff"
+                    stroke="#000000"
+                    strokeWidth={2}
+                    strokeLinejoin="round"
+                    strokeLinecap="round"
+                    opacity={1}
+                    fillOpacity={1}
+                    strokeOpacity={1}
+                  />
+                </Mask>
+              </Defs>
+            ) : null}
+            <Path
+              {...chartMarkProps(slice.datum.label)}
+              {...(masked
+                ? chartWebProps({
+                    "data-mpo-chart-mask": "eroded-arc-v1",
+                    "data-mpo-chart-slice": [
+                      slice.startAngle,
+                      slice.endAngle,
+                      innerRadius,
+                      outerRadius,
+                    ].join(","),
+                  })
+                : {})}
+              d={path}
+              mask={masked ? `url(#${maskId})` : undefined}
+              fill={fills[slice.index]}
+              {...(interactive ? targetPropsFor(callbacks, slice.datum, slice.index) : {})}
+            />
+          </G>
+        );
+      })}
     </G>
   );
 }

package/src/charts/svg.spec.ts

@@ -0,0 +1,28 @@
+import { expect, it, vi } from "vitest";
+
+vi.mock("@multiplatform.one/platform", () => ({ isWeb: false }));
+
+import {
+  chartChromeProps,
+  chartDatumTextProps,
+  chartMarkProps,
+  chartRootA11yProps,
+  chartWebProps,
+  luminanceMaskProps,
+} from "./svg";
+
+it("keeps browser audit attributes off native SVG props", () => {
+  expect(
+    chartRootA11yProps("Revenue", {
+      kind: "bar",
+      separated: true,
+      datumText: false,
+      datumCount: 13,
+    }),
+  ).toEqual({ accessible: true, accessibilityRole: "image", accessibilityLabel: "Revenue" });
+  expect(luminanceMaskProps()).toEqual({ maskType: "luminance" });
+  expect(chartMarkProps("North")).toEqual({});
+  expect(chartChromeProps("grid")).toEqual({});
+  expect(chartDatumTextProps(12)).toEqual({});
+  expect(chartWebProps({ "data-mpo-chart-owner": "true" })).toEqual({});
+});