pixelize-native-library 1.0.7 → 1.2.0

package/lib/module/modules/charts/DonutChart.js

@@ -1,10 +1,11 @@
 "use strict";
 
-import { memo } from "react";
+import { memo, useMemo } from "react";
 import { StyleSheet, Text, View } from "react-native";
 import Svg, { Circle, G } from "react-native-svg";
-import { useTheme } from "../../theme/index.js";
-import { resolveDonutChartColors } from "./Charts.variants.js";
+import { useTheme } from "../../theme/hooks.js";
+import { ChartLegend } from "./ChartLegend.js";
+import { DONUT_SEGMENT_GAP_RATIO, resolveDonutChartColors } from "./Charts.variants.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 export const DonutChart = /*#__PURE__*/memo(function DonutChart({
   segments,
@@ -12,84 +13,118 @@ export const DonutChart = /*#__PURE__*/memo(function DonutChart({
   thickness = 20,
   centerLabel,
   centerSublabel,
+  showLegend = true,
   style,
   testID
 }) {
   const theme = useTheme();
-  const colors = resolveDonutChartColors(theme.colors);
+  const colors = useMemo(() => resolveDonutChartColors(theme.colors), [theme.colors]);
   const center = size / 2;
   const radius = Math.max((size - thickness) / 2, 0);
   const circumference = 2 * Math.PI * radius;
-  const valid = segments.filter(segment => Number.isFinite(segment.value) && segment.value > 0);
-  const total = valid.reduce((sum, segment) => sum + segment.value, 0);
-  const arcs = [];
-  let start = 0;
-  for (const segment of valid) {
-    const fraction = total > 0 ? segment.value / total : 0;
-    arcs.push({
-      color: segment.color,
-      fraction,
-      start
+  const arcs = useMemo(() => {
+    const valid = segments.filter(segment => Number.isFinite(segment.value) && segment.value > 0);
+    const total = valid.reduce((sum, segment) => sum + segment.value, 0);
+    const resolved = [];
+    let start = 0;
+    valid.forEach((segment, index) => {
+      const fraction = total > 0 ? segment.value / total : 0;
+      resolved.push({
+        color: segment.color,
+        label: segment.label ?? `Segment ${index + 1}`,
+        fraction,
+        start
+      });
+      start += fraction;
     });
-    start += fraction;
-  }
+    return resolved;
+  }, [segments]);
+
+  // Two ramp hues can sit under 1.1:1 contrast (measured, `Charts.test.ts`) — a bare arc-to-arc
+  // border at that separation reads as one uninterrupted ring. Shaving a sliver off each arc's
+  // fraction leaves a track-coloured gap that stays visible regardless of the two hues either
+  // side of it.
+  const dashes = useMemo(() => arcs.map(arc => {
+    const gap = circumference * DONUT_SEGMENT_GAP_RATIO;
+    const drawn = Math.max(0, arc.fraction * circumference - gap);
+    return {
+      color: arc.color,
+      dasharray: `${drawn} ${circumference}`,
+      dashoffset: -arc.start * circumference - gap / 2
+    };
+  }), [arcs, circumference]);
+  const legendEntries = useMemo(() => showLegend && arcs.length > 1 ? arcs.map(arc => ({
+    color: arc.color,
+    label: arc.label
+  })) : [], [arcs, showLegend]);
+  const ringSize = useMemo(() => ({
+    width: size,
+    height: size
+  }), [size]);
   return /*#__PURE__*/_jsxs(View, {
     testID: testID,
-    style: [{
-      width: size,
-      height: size
-    }, style],
-    children: [/*#__PURE__*/_jsx(View, {
-      accessibilityElementsHidden: true,
-      importantForAccessibility: "no-hide-descendants",
-      children: /*#__PURE__*/_jsx(Svg, {
-        width: size,
-        height: size,
-        children: /*#__PURE__*/_jsxs(G, {
-          transform: `rotate(-90 ${center} ${center})`,
-          children: [/*#__PURE__*/_jsx(Circle, {
-            testID: testID === undefined ? undefined : `${testID}-track`,
-            cx: center,
-            cy: center,
-            r: radius,
-            stroke: colors.track,
-            strokeWidth: thickness,
-            fill: "none"
-          }), arcs.map((arc, index) => /*#__PURE__*/_jsx(Circle, {
-            testID: testID === undefined ? undefined : `${testID}-segment-${index}`,
-            cx: center,
-            cy: center,
-            r: radius,
-            stroke: arc.color,
-            strokeWidth: thickness,
-            fill: "none",
-            strokeDasharray: `${arc.fraction * circumference} ${circumference}`,
-            strokeDashoffset: -arc.start * circumference
-          }, index))]
+    style: [styles.container, style],
+    children: [/*#__PURE__*/_jsxs(View, {
+      style: ringSize,
+      children: [/*#__PURE__*/_jsx(View, {
+        accessibilityElementsHidden: true,
+        importantForAccessibility: "no-hide-descendants",
+        children: /*#__PURE__*/_jsx(Svg, {
+          width: size,
+          height: size,
+          children: /*#__PURE__*/_jsxs(G, {
+            transform: `rotate(-90 ${center} ${center})`,
+            children: [/*#__PURE__*/_jsx(Circle, {
+              testID: testID === undefined ? undefined : `${testID}-track`,
+              cx: center,
+              cy: center,
+              r: radius,
+              stroke: colors.track,
+              strokeWidth: thickness,
+              fill: "none"
+            }), dashes.map((dash, index) => /*#__PURE__*/_jsx(Circle, {
+              testID: testID === undefined ? undefined : `${testID}-segment-${index}`,
+              cx: center,
+              cy: center,
+              r: radius,
+              stroke: dash.color,
+              strokeWidth: thickness,
+              fill: "none",
+              strokeDasharray: dash.dasharray,
+              strokeDashoffset: dash.dashoffset
+            }, index))]
+          })
         })
-      })
-    }), (centerLabel !== undefined || centerSublabel !== undefined) && /*#__PURE__*/_jsxs(View, {
-      pointerEvents: "none",
-      style: [StyleSheet.absoluteFill, styles.center],
-      children: [centerLabel !== undefined && /*#__PURE__*/_jsx(Text, {
-        numberOfLines: 1,
-        style: [theme.fontStyleForWeight(theme.fontWeights.semibold), {
-          fontSize: theme.fontSizes.xl,
-          color: colors.centerLabel
-        }],
-        children: centerLabel
-      }), centerSublabel !== undefined && /*#__PURE__*/_jsx(Text, {
-        numberOfLines: 1,
-        style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
-          fontSize: theme.fontSizes.xs,
-          color: colors.centerSublabel
-        }],
-        children: centerSublabel
+      }), (centerLabel !== undefined || centerSublabel !== undefined) && /*#__PURE__*/_jsxs(View, {
+        pointerEvents: "none",
+        style: [StyleSheet.absoluteFill, styles.center],
+        children: [centerLabel !== undefined && /*#__PURE__*/_jsx(Text, {
+          numberOfLines: 1,
+          style: [theme.fontStyleForWeight(theme.fontWeights.semibold), {
+            fontSize: theme.fontSizes.xl,
+            color: colors.centerLabel
+          }],
+          children: centerLabel
+        }), centerSublabel !== undefined && /*#__PURE__*/_jsx(Text, {
+          numberOfLines: 1,
+          style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
+            fontSize: theme.fontSizes.xs,
+            color: colors.centerSublabel
+          }],
+          children: centerSublabel
+        })]
       })]
+    }), /*#__PURE__*/_jsx(ChartLegend, {
+      entries: legendEntries,
+      glyph: "swatch",
+      testID: testID ? `${testID}-legend` : undefined
     })]
   });
 });
 const styles = StyleSheet.create({
+  container: {
+    alignItems: "flex-start"
+  },
   center: {
     alignItems: "center",
     justifyContent: "center"

package/lib/module/modules/charts/LineChart.js

@@ -0,0 +1,179 @@
+"use strict";
+
+import { memo, useMemo, useState } from "react";
+import { StyleSheet, View } from "react-native";
+import Svg, { Circle, Line, Path, Text as SvgText } from "react-native-svg";
+import { useTheme } from "../../theme/hooks.js";
+import { ChartLegend } from "./ChartLegend.js";
+import { buildAreaPath, buildLinePath, categoricalColorAt, decimateSeries, defaultNumberFormatter, describeMarker, niceScale, resolveChartAxisColors, resolveLineDomain, resolveSeriesPoints, scaleValue, seriesDashAt, seriesShapeAt, summarizeLineChart } from "./Charts.variants.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const Y_AXIS_WIDTH = 40;
+const X_AXIS_HEIGHT = 24;
+const PLOT_TOP = 12;
+const TICK_COUNT = 5;
+const AXIS_LABEL_SIZE = 11;
+const DOT_RADIUS = 3;
+const LINE_STROKE_WIDTH = 2;
+const AREA_OPACITY = 0.15;
+const defaultXAxisFormatter = value => String(value);
+const datumY = datum => datum.y;
+export const LineChart = /*#__PURE__*/memo(function LineChart({
+  series,
+  height = 200,
+  showGrid = true,
+  showDots = true,
+  showArea = false,
+  curved = false,
+  showLegend = true,
+  yAxisFormatter = defaultNumberFormatter,
+  xAxisFormatter = defaultXAxisFormatter,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const axisColors = useMemo(() => resolveChartAxisColors(theme.colors), [theme.colors]);
+  const [width, setWidth] = useState(0);
+  const onLayout = event => {
+    setWidth(event.nativeEvent.layout.width);
+  };
+  const plotWidth = Math.max(0, width - Y_AXIS_WIDTH);
+  const plotHeight = Math.max(0, height - X_AXIS_HEIGHT - PLOT_TOP);
+  const decimatedSeries = useMemo(() => series.map(s => ({
+    ...s,
+    data: decimateSeries(s.data, datumY)
+  })), [series]);
+  const {
+    plotted,
+    paths,
+    ticks,
+    xLabels,
+    summary
+  } = useMemo(() => {
+    const domain = resolveLineDomain(decimatedSeries);
+    const scale = niceScale(domain.min, domain.max, TICK_COUNT);
+    const resolvedPlotted = decimatedSeries.map((s, index) => {
+      const points = resolveSeriesPoints(s.data, scale.min, scale.max, plotWidth, plotHeight).map(point => ({
+        x: point.x + Y_AXIS_WIDTH,
+        y: point.y + PLOT_TOP
+      }));
+      return {
+        color: s.color ?? categoricalColorAt(theme.colors, index),
+        shape: s.shape ?? seriesShapeAt(index),
+        dash: seriesDashAt(index),
+        points
+      };
+    });
+    const longest = decimatedSeries.reduce((acc, current) => current.data.length > (acc?.data.length ?? 0) ? current : acc, undefined);
+    const labelCount = longest?.data.length ?? 0;
+    return {
+      plotted: resolvedPlotted,
+      // Series with no drawable points are filtered out BEFORE indexing, so path testIDs stay dense.
+      paths: resolvedPlotted.filter(s => s.points.length > 0).map(s => ({
+        color: s.color,
+        dash: s.dash,
+        line: buildLinePath(s.points, curved),
+        area: showArea ? buildAreaPath(s.points, PLOT_TOP + plotHeight, curved) : undefined
+      })),
+      ticks: scale.ticks.map(tick => ({
+        y: PLOT_TOP + scaleValue(tick, scale.min, scale.max, plotHeight, 0),
+        text: yAxisFormatter(tick)
+      })),
+      xLabels: (longest?.data ?? []).map((point, index) => ({
+        x: Y_AXIS_WIDTH + (labelCount <= 1 ? plotWidth / 2 : index * plotWidth / (labelCount - 1)),
+        text: xAxisFormatter(point.x)
+      })),
+      summary: summarizeLineChart(decimatedSeries)
+    };
+  }, [decimatedSeries, plotWidth, plotHeight, curved, showArea, theme.colors, yAxisFormatter, xAxisFormatter]);
+
+  // One series needs no key: its name is already the chart's own caption, and there is nothing to
+  // tell it apart from.
+  const legendEntries = useMemo(() => showLegend && series.length > 1 ? series.map((s, index) => ({
+    color: s.color ?? categoricalColorAt(theme.colors, index),
+    label: s.name,
+    shape: s.shape ?? seriesShapeAt(index),
+    dash: seriesDashAt(index)
+  })) : [], [series, showLegend, theme.colors]);
+  const plotStyle = useMemo(() => ({
+    height
+  }), [height]);
+  return /*#__PURE__*/_jsxs(View, {
+    testID: testID,
+    style: style,
+    onLayout: onLayout,
+    children: [/*#__PURE__*/_jsxs(View, {
+      style: plotStyle,
+      children: [/*#__PURE__*/_jsx(View, {
+        testID: testID ? `${testID}-summary` : undefined,
+        accessible: true,
+        accessibilityRole: "image",
+        accessibilityLabel: summary,
+        style: StyleSheet.absoluteFill,
+        pointerEvents: "none"
+      }), /*#__PURE__*/_jsx(View, {
+        accessibilityElementsHidden: true,
+        importantForAccessibility: "no-hide-descendants",
+        style: StyleSheet.absoluteFill,
+        children: /*#__PURE__*/_jsxs(Svg, {
+          width: width,
+          height: height,
+          children: [showGrid && ticks.map((tick, index) => /*#__PURE__*/_jsx(Line, {
+            testID: testID ? `${testID}-grid-${index}` : undefined,
+            x1: Y_AXIS_WIDTH,
+            x2: width,
+            y1: tick.y,
+            y2: tick.y,
+            stroke: axisColors.gridline,
+            strokeWidth: StyleSheet.hairlineWidth
+          }, `grid-${index}`)), ticks.map((tick, index) => /*#__PURE__*/_jsx(SvgText, {
+            testID: testID ? `${testID}-tick-${index}` : undefined,
+            x: Y_AXIS_WIDTH - 8,
+            y: tick.y + 4,
+            fontSize: AXIS_LABEL_SIZE,
+            fill: axisColors.label,
+            textAnchor: "end",
+            children: tick.text
+          }, `tick-${index}`)), xLabels.map((label, index) => /*#__PURE__*/_jsx(SvgText, {
+            testID: testID ? `${testID}-x-${index}` : undefined,
+            x: label.x,
+            y: height - X_AXIS_HEIGHT / 2 + 4,
+            fontSize: AXIS_LABEL_SIZE,
+            fill: axisColors.label,
+            textAnchor: "middle",
+            children: label.text
+          }, `x-${index}`)), showArea && paths.map((s, index) => /*#__PURE__*/_jsx(Path, {
+            testID: testID ? `${testID}-series-${index}-area` : undefined,
+            d: s.area,
+            fill: s.color,
+            fillOpacity: AREA_OPACITY,
+            stroke: "none"
+          }, `area-${index}`)), paths.map((s, index) => /*#__PURE__*/_jsx(Path, {
+            testID: testID ? `${testID}-series-${index}-line` : undefined,
+            d: s.line,
+            fill: "none",
+            stroke: s.color,
+            strokeWidth: LINE_STROKE_WIDTH,
+            strokeDasharray: s.dash,
+            strokeLinecap: "round",
+            strokeLinejoin: "round"
+          }, `line-${index}`)), showDots && plotted.map((s, index) => s.points.map((point, pointIndex) => s.shape === "circle" ? /*#__PURE__*/_jsx(Circle, {
+            testID: testID ? `${testID}-series-${index}-dot-${pointIndex}` : undefined,
+            cx: point.x,
+            cy: point.y,
+            r: DOT_RADIUS,
+            fill: s.color
+          }, `dot-${index}-${pointIndex}`) : /*#__PURE__*/_jsx(Path, {
+            testID: testID ? `${testID}-series-${index}-dot-${pointIndex}` : undefined,
+            d: describeMarker(s.shape, point.x, point.y, DOT_RADIUS),
+            fill: s.color
+          }, `dot-${index}-${pointIndex}`)))]
+        })
+      })]
+    }), /*#__PURE__*/_jsx(ChartLegend, {
+      entries: legendEntries,
+      glyph: "line",
+      testID: testID ? `${testID}-legend` : undefined
+    })]
+  });
+});
+//# sourceMappingURL=LineChart.js.map

package/lib/module/modules/charts/MODULE.md

@@ -1,9 +1,9 @@
-# charts/ — small data-display primitives (BarList, DonutChart, Sparkline)
+# charts/ — data-display primitives (BarList, DonutChart, Sparkline, BarChart, LineChart, PieChart)
 
-Three theme-aware chart primitives for dashboards and KPI screens. `DonutChart` and `Sparkline`
-render through `react-native-svg` (optional peer — a consumer using only `BarList` never pays for
-it at runtime, though the import is module-level: importing this subpath requires the peer
-installed).
+Six theme-aware chart primitives for dashboards and KPI screens. `DonutChart`, `Sparkline`,
+`BarChart`, `LineChart` and `PieChart` render through `react-native-svg` (optional peer — a
+consumer using only `BarList` never pays for it at runtime, though the import is module-level:
+importing this subpath requires the peer installed).
 
 ## Files
 
@@ -12,9 +12,13 @@ installed).
 | `BarList.tsx` | Horizontal labeled breakdown bars — plain Views, no svg. |
 | `DonutChart.tsx` | Svg donut: stacked `Circle` strokes via dasharray/dashoffset, optional center label. |
 | `Sparkline.tsx` | Svg line + area under it, tone-driven stroke. |
-| `Charts.variants.ts` | Pure resolvers (colors from role tokens, BarList structure). No React, no svg. |
-| `__tests__/Charts.test.ts` | Pure: WCAG contrast (all brands × modes) + role-mapping contract. |
-| `__tests__/Charts.render.test.tsx` | Render: rows/segments/paths, a11y, svg mocked. |
+| `BarChart.tsx` | Svg vertical bars with axes/gridlines — simple, grouped or stacked. |
+| `LineChart.tsx` | Svg multi-series line with axes/gridlines, optional area fill and curve smoothing. |
+| `PieChart.tsx` | Svg filled wedges + legend — the "with a legend" sibling to `DonutChart`'s ring. |
+| `ChartLegend.tsx` | Internal — the one text legend shared by `PieChart`/`DonutChart`/`LineChart`/`BarChart`. Not exported. |
+| `Charts.variants.ts` | Pure resolvers: colors, scales, geometry, arc/path maths, a11y summaries, non-colour series channels. No React, no svg. |
+| `__tests__/Charts.test.ts` | Pure: WCAG contrast (all brands × modes), geometry, scale, path and summary logic. |
+| `__tests__/Charts.render.test.tsx` | Render: rows/segments/paths/bars/lines, a11y, svg mocked. |
 
 ## Props
 
@@ -24,29 +28,151 @@ Bar fill defaults to `accent.solid`; per-item `color` exists for data-driven ser
 breakdowns have no closed-union role) — a deliberate, documented exception to the closed-union rule.
 
 **DonutChart** — `segments: { value, color, label? }[]`, `size?` (160), `thickness?` (20),
-`centerLabel?`, `centerSublabel?`, `style?`, `testID?`. Non-finite / ≤ 0 segment values are dropped;
-with no valid segments only the `bg.sunken` track ring renders.
+`centerLabel?`, `centerSublabel?`, `showLegend?` (true — **new**), `style?`, `testID?`. Non-finite /
+≤ 0 segment values are dropped; with no valid segments only the `bg.sunken` track ring renders.
+`segment.label` (previously accepted but silently dropped) now renders as a legend row, falling
+back to `"Segment N"` when omitted; the legend is skipped for 0–1 valid segments.
 
 **Sparkline** — `data: number[]`, `width?` (120), `height?` (32),
 `tone?: accent | neutral | success | warning | danger | info` (accent), `style?`, `testID?`.
 Non-finite samples are dropped; a single sample draws a flat line; empty data renders an empty box.
+Unchanged by the WCAG 1.4.1 pass below — see "Design decisions" for why.
 
-## Accessibility
+**BarChart** — `data: { label, values: number[] }[]` (`values.length === 1` = simple bars, `> 1` =
+grouped/stacked), `series?: { name, color? }[]`, `height?` (200), `showGrid?` (true), `showValues?`
+(false), `stacked?` (false), `showLegend?` (true — **new**), `yAxisFormatter?`,
+`onPressBar?(datum, seriesIndex)`, `style?`, `testID?`. Width is measured via `onLayout` (no `width`
+prop — the chart fills its container). Non-finite bar values render as height 0; the y-domain always
+includes 0. 2+ series get a legend (falling back to `"Series N"` with no `series[i].name`) and a
+knocked-out shape mark on each bar when it's ≥ 14dp on both axes (`BAR_MARKER_MIN_SPAN`).
 
-- Each BarList row is ONE accessible node announcing `"label, value"` (`text` role, or `button`
-  when `onPressItem` is set); the bar track is decorative and hidden from AT — the value text
-  already carries the information.
-- Donut/sparkline graphics are hidden from AT (decorative, same contract as Timeline's connector);
-  DonutChart's center labels stay in the normal accessibility tree.
-- BarList label (`fg.default`) and value (`fg.muted`) are measured ≥ 4.5:1 on the canvas for all
-  8 brands × both modes (`Charts.test.ts`).
+**LineChart** — `series: { name, data: { x, y }[], color?, shape? }[]`, `height?` (200), `showGrid?`
+(true), `showDots?` (true), `showArea?` (false), `curved?` (false — Catmull-Rom→bézier when true),
+`showLegend?` (true — **new**), `yAxisFormatter?`, `xAxisFormatter?`, `style?`, `testID?`. Non-finite
+`y` samples are dropped per series (same contract as `Sparkline`), then spaced evenly by index — x is
+plotted by position, not proportionally by numeric value, so unevenly-spaced categories still read as
+an even axis. Long series are decimated first (see Performance) — no prop, a module constant. 2+
+series get a legend naming each one; every series also gets a `strokeDasharray` and a marker shape
+(circle/square/triangle/diamond/cross) by index — `series[i].shape` (**new**, optional) overrides it.
+
+**PieChart** — `segments: { label, value, color? }[]`, `size?` (180), `showLegend?` (true),
+`showPercentages?` (true — controls the legend row text, not on-wedge labels: a label drawn on a
+consumer-picked wedge color can't have its contrast guaranteed), `onPressSegment?(segment, index)`,
+`style?`, `testID?`. `index` is into the rendered (filtered, positive-value) list, matching
+`DonutChart`'s own `arcs`-index convention — never the raw `segments` indices. This is the filled
+sibling of `DonutChart`; reach for `DonutChart` for a ring with a center label, `PieChart` for
+filled wedges with a legend. Wedges now carry a `bg.surface` separator stroke and the legend a
+knocked-out shape per row, on top of the pre-existing swatch+text (see "Design decisions").
+
+All four multi-series charts default series/segment colors from a shared 5-hue role-derived ramp
+(`resolveCategoricalRamp`) when no per-series/per-segment `color` is given; a 6th+ series wraps
+around it — pass explicit colors for more than 5 guaranteed-distinguishable hues. The matching
+shape/dash channels (`seriesShapeAt`/`seriesDashAt`) wrap the same way, by the same index.
+
+## Accessibility contract (WCAG)
+
+- **1.1.1 (Non-text Content)** — `BarChart`/`LineChart`/`PieChart` can't have their svg paths read
+  by a screen reader, so a dedicated sibling node (`accessible accessibilityRole="image"`) carries
+  an `accessibilityLabel` that summarizes the whole chart (e.g. `"Bar chart, 4 categories, highest
+  Revenue at 1,200"`) — the summary IS the text alternative; the drawing itself stays
+  `accessibilityElementsHidden`. Donut/sparkline graphics are hidden from AT the same way
+  (decorative, same contract as Timeline's connector) but skip the image summary — they pair with a
+  caller-owned label (`centerLabel`) or carry no standalone meaning (`Sparkline`).
+- **4.1.2 (Name, Role, Value)** — a pressable bar/segment is a SEPARATE sibling (never nested inside
+  the image node — nesting would trap focus and make it unreachable) with its own
+  `accessibilityRole="button"` + `"label, value"` label. BarList rows are `text` role, or `button`
+  when `onPressItem` is set.
+- **2.5.8 / 2.5.5 (Target Size)** — every pressable bar/segment gets a ≥ 44dp touch target via
+  `hitSlop` (`hitSlopFor`), computed from its own drawn size; pie wedges use an angular
+  bounding-box (`resolveWedgeBoundingBox`) since a wedge isn't rectangular.
+- **1.4.3 (Contrast Minimum, text)** — BarList label/value and axis labels (`fg.muted`) measure
+  ≥ 4.5:1 against their canvas, for all 9 brands × both modes (`Charts.test.ts`).
+- **1.4.11 (Non-text Contrast)** — gridlines (`border.interactive`) and every categorical-ramp hue
+  measure ≥ 3:1 against `bg.surface`, same brand × mode matrix.
+- **2.3.3 (Animation from Interactions)** — n/a; no animation in any of the six components, so
+  `useReducedMotion()` has nothing to gate.
+- **1.4.1 (Use of Color)** — measured (`Charts.test.ts`): the 5-hue ramp does NOT reliably separate
+  series from each other — only 1 of 180 hue-pairs (9 brands × 2 modes × 10 pairs) clears 3:1, worst
+  1.01:1, median 1.21:1. Every multi-series chart therefore carries a second, colour-independent
+  channel keyed on the same series index: `LineChart` — `strokeDasharray` (solid for series 0) + a
+  marker shape; `BarChart` — a knocked-out shape mark per bar (when it fits); `PieChart`/`DonutChart`
+  — a `bg.surface` separator between adjacent segments (wedge stroke / a shaved ring gap) so a
+  boundary reads regardless of hue; plus a shared text legend (`ChartLegend`) on all four, naming
+  each series directly and (on `BarChart`/`PieChart`/`DonutChart`) carrying the same shape per row.
+
+## Patterns copied from the reference modules
+
+- Structure vs colour split (`createThemedVariants` for `ChartLegend`'s spacing/swatch, role
+  colours resolved separately) — the same split `Select`/`BarList` use.
+- Width-via-`onLayout` for `BarChart`/`LineChart` mirrors `Slider`/`ProgressBar`'s own
+  `onLayout`-measured track, including the plain (non-`useCallback`) handler those two use.
+
+## Design decisions specific to BarChart/LineChart/PieChart
+
+- Stacked bars use a simple running cumulative sum — the y-domain (`resolveBarChartDomain`) and the
+  rendered geometry share the exact same running total, so they can never disagree about where a
+  stack reaches, including for mixed-sign data.
+- `niceScale` extends the classic 1/2/5/10 "nice number" ladder with 2.5, so a raw `/4` step of 25
+  lands on 25 rather than rounding down to 20 — this is what makes `0/25/50/75/100` come out exact.
+- Pie wedge colour/label/press payload all read from `PieWedge.source` — the caller's own segment
+  object, not a reconstruction — so `onPressSegment` always hands back exactly what was passed in.
+- `ChartLegend` is deliberately NOT exported: a consumer turns it on via each chart's own
+  `showLegend`, never by mounting the legend directly — one implementation, one place to fix an a11y
+  issue in it later.
+- `Sparkline` was audited and deliberately left unchanged. Its `tone` reinforces status the caller
+  has already conveyed elsewhere (a paired KPI value/label, or the line's own up/down shape), not the
+  sole channel — the pre-existing "carries no standalone meaning" position holds. A bare `Sparkline`
+  as a consumer's only data view is a misuse of a decorative primitive, not a defect here.
+- `PieChart`'s wedge separator is a `stroke` on the existing filled `Path` — `resolvePieWedges`'
+  angles (used by presses, the legend %, and `Charts.test.ts`) stay exact, only the drawn stroke
+  changes. `DonutChart`'s separator instead shaves a small gap out of each arc's own
+  `strokeDasharray`/`strokeDashoffset` (`DONUT_SEGMENT_GAP_RATIO`), since its ring segments are
+  strokes on one shared circle, not independent filled paths.
 
 ## Known gaps
 
-- Segment/bar `color` values come from the consumer — contrast of consumer-picked series colors
-  against the canvas is the consumer's to verify.
-- No animation, no labels-on-arc, no axes — these are primitives, not a charting library.
+- Segment/bar/series `color` values come from the consumer — contrast of consumer-picked colors
+  against the canvas is the consumer's to verify (documented exception to the closed-union rule).
+  `DonutChart.segments[].color` is required and consumer-supplied (unlike the other three charts'
+  ramp-defaulted `color`), so it has no index identity a shape channel could hook into — its
+  separator is a track-coloured gap instead of a shape.
+- LineChart's x-axis labels are taken from the longest (decimated) series and positioned by raw
+  index; a series with dropped non-finite points can drift slightly out of alignment with the
+  shared x-axis, and a decimated series labels only the samples it kept.
+- Pie wedge touch targets are an angular bounding-box approximation, not pixel-perfect wedge-shaped
+  hit testing — conservative (never smaller than the visual wedge), never exact.
+- No animation, no labels-on-arc for `PieChart` (see "showPercentages" above).
+- `BarChart`'s bar marker is dropped (not shrunk) below `BAR_MARKER_MIN_SPAN` (14dp) on either axis —
+  the legend and the bar's fixed group position are the fallback channel at small sizes.
 
 ## Performance
 
-All three components wrapped in `React.memo` (root `CLAUDE.md` performance rule).
+- All six components wrapped in `React.memo` (root `CLAUDE.md` performance rule).
+- **The memoization boundary is the component, never the resolver.** `Charts.variants.ts` stays
+  plain and hook-free; each chart resolves its whole geometry in ONE `useMemo` — domain, nice scale,
+  bar layout, points, line/area path strings, tick + axis-label arrays, wedge paths and press boxes,
+  donut dash arrays — keyed on data, measured width/height, `theme.colors` and the formatter/curve/
+  area props. Nothing geometric is recomputed when a parent re-renders with the same inputs.
+- **Row children are extracted and `React.memo`'d** — `BarListRow`, `BarPressTarget`,
+  `WedgePressTarget`, `ChartLegendRow`/`LegendGlyph`. Press-target rows take an **index-taking**
+  callback (`onPress(index)`) resolved back to the consumer's own object by the parent, plus themed
+  styles hoisted out of the row loop; a per-row inline closure or a per-row `variants(theme)` call
+  would defeat their memo. `ChartLegend`'s entry array is built inside each chart's own `useMemo`
+  (keyed on `series`/`segments`/`showLegend`/`theme.colors`), never a fresh literal per render.
+- **Found, not acted on:** decimation (`MAX_RENDERED_POINTS`) is a fixed constant regardless of
+  `useDeviceTier()` — a `'low'`-tier phone gets the same 200-point cap (and the same new bar-marker/
+  legend work) as `'high'`. Worth a future device-tier-scaled pass; out of scope for this WCAG change
+  (no animation exists here for a native-driver check, and every geometry `useMemo` already keys
+  correctly).
+- **Decimation** (`LineChart`, `Sparkline`): a series longer than `MAX_RENDERED_POINTS` (200) is
+  downsampled inside the same `useMemo`, before any geometry, so it costs nothing on re-render —
+  1,000 samples otherwise means 1,000 svg nodes. Min/max bucketing: both endpoints plus each
+  bucket's lowest and highest sample, in original order, so a one-sample spike survives (plain
+  stride sampling would drop it). Output is ≤ the threshold; below it the input array is returned
+  as-is. `BarChart` is deliberately NOT decimated — every bar is a labelled category, and dropping
+  categories would contradict the x-axis labels and the a11y summary.
+
+## Modernization (v1.0.7)
+
+- Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.
+- List-heavy surfaces use `VirtualList` with device-tier window sizing where applicable.