panelui-native 0.66.1 → 0.71.0

package/src/components/heatmap-chart/index.tsx

@@ -61,6 +61,7 @@ import Animated, {
 import Svg, { ClipPath, Defs, G, Line as SvgLine, Rect } from 'react-native-svg';
 import { useCSSVariable } from 'uniwind';
 import { Text } from '../../primitives/text';
+import { ChartAccessibilityData, type ChartAccessibilityProps } from '../../primitives/chart-accessibility';
 import { cn } from '../../utils/cn';
 import { normalizeWeekStart, startOfDay } from '../../utils/date';
 
@@ -309,7 +310,7 @@ function deriveLevels(data: HeatmapColumn[]): number[] {
 /* Root                                                                       */
 /* -------------------------------------------------------------------------- */
 
-export interface HeatmapChartProps extends ViewProps {
+export interface HeatmapChartProps extends ViewProps, ChartAccessibilityProps<HeatmapCell> {
   className?: string;
   /** One column per period, with its row bins inside. */
   data: HeatmapColumn[];
@@ -396,6 +397,11 @@ const HeatmapChartRoot = forwardRef<View, HeatmapChartProps>(function HeatmapCha
     animationDuration = 900,
     inactiveOpacity = 1,
     onActiveCellChange,
+    accessible,
+    accessibilityLabel,
+    accessibilityHint,
+    accessibilityLabelForDatum,
+    onAccessibilityDatumPress,
     children,
     ...props
   },
@@ -491,6 +497,20 @@ const HeatmapChartRoot = forwardRef<View, HeatmapChartProps>(function HeatmapCha
     [data, levelOf]
   );
 
+  const accessibilityCells = useMemo(
+    () =>
+      data.flatMap((column) =>
+        column.bins.map((bin) => ({
+          column: column.bin,
+          row: bin.bin,
+          count: bin.count,
+          level: levelOf(bin.count),
+          date: bin.date,
+        }))
+      ),
+    [data, levelOf]
+  );
+
   const setActiveCell = useMemo(
     () => (cell: HeatmapCell | null) => {
       setActiveCellState(cell);
@@ -570,11 +590,37 @@ const HeatmapChartRoot = forwardRef<View, HeatmapChartProps>(function HeatmapCha
             whole chart, so it starts at the chart's edge, not the grid's. */}
         {parts.header}
 
+        <ChartAccessibilityData
+          chart="Heatmap chart"
+          data={accessibilityCells}
+          disabled={accessible === false}
+          accessibilityLabel={accessibilityLabel}
+          accessibilityHint={accessibilityHint}
+          accessibilityLabelForDatum={accessibilityLabelForDatum}
+          onAccessibilityDatumPress={onAccessibilityDatumPress}
+          valueOf={(cell) => [
+            ['date', cell.date],
+            ['column', cell.column],
+            ['row', cell.row],
+            ['count', cell.count],
+          ]}
+        />
+
         {parts.x ? (
-          <View style={{ paddingLeft: axisWidth }}>{parts.x}</View>
+          <View
+            style={{ paddingLeft: axisWidth }}
+            accessibilityElementsHidden
+            importantForAccessibility="no-hide-descendants"
+          >
+            {parts.x}
+          </View>
         ) : null}
 
-        <View className="flex-row">
+        <View
+          className="flex-row"
+          accessibilityElementsHidden
+          importantForAccessibility="no-hide-descendants"
+        >
           {parts.y}
           <View style={{ width: grid.width, height: grid.height }}>
             {grid.width > 0 ? (

package/src/components/line-chart/index.tsx

@@ -82,6 +82,7 @@ import Svg, {
 } from 'react-native-svg';
 import { useCSSVariable } from 'uniwind';
 import { Text } from '../../primitives/text';
+import { ChartAccessibilityData, type ChartAccessibilityProps } from '../../primitives/chart-accessibility';
 import {
   areaPath,
   columnValues,
@@ -172,7 +173,7 @@ export function useLineChart() {
   };
 }
 
-export interface LineChartProps extends ViewProps {
+export interface LineChartProps extends ViewProps, ChartAccessibilityProps<LineChartDatum> {
   className?: string;
   /** The rows. Each one is a point along the x-axis. */
   data: LineChartDatum[];
@@ -227,6 +228,11 @@ const LineChartRoot = forwardRef<LineChartHandle, LineChartProps>(function LineC
     yDomain,
     curve = 'monotone',
     onActiveIndexChange,
+    accessible,
+    accessibilityLabel,
+    accessibilityHint,
+    accessibilityLabelForDatum,
+    onAccessibilityDatumPress,
     compact = false,
     children,
     ...props
@@ -443,7 +449,26 @@ const LineChartRoot = forwardRef<LineChartHandle, LineChartProps>(function LineC
     <LineChartContext.Provider value={context}>
       <View {...props} style={props.style} className={cn('w-full', className)}>
         {header}
-        <View onLayout={onLayout} style={{ aspectRatio }} className="w-full">
+        <ChartAccessibilityData
+          chart="Line chart"
+          data={data}
+          disabled={accessible === false || loading}
+          accessibilityLabel={accessibilityLabel}
+          accessibilityHint={accessibilityHint}
+          accessibilityLabelForDatum={accessibilityLabelForDatum}
+          onAccessibilityDatumPress={onAccessibilityDatumPress}
+          valueOf={(datum) => [
+            [xDataKey, datum[xDataKey]],
+            ...series.map(([key]) => [key, datum[key]] as [string, unknown]),
+          ]}
+        />
+        <View
+          onLayout={onLayout}
+          style={{ aspectRatio }}
+          className="w-full"
+          accessibilityElementsHidden
+          importantForAccessibility="no-hide-descendants"
+        >
           {plot.width > 0 ? (
             <>
               <Svg width="100%" height="100%" style={StyleSheet.absoluteFill}>

package/src/components/live-line-chart/index.tsx

@@ -30,10 +30,17 @@
  * they mean opposite things.
  *
  * The cost is a frame callback for as long as the chart is mounted. It is
- * stopped by `paused`, by `status="loading"` and on unmount, and it is never
- * started when the platform asks for reduced motion — in that case the window
- * advances as each point arrives instead, which is the same picture sampled
- * less often.
+ * stopped by `paused`, by `status="loading"`, while the app is backgrounded
+ * and on unmount, and it is never started when the platform asks for reduced
+ * motion — in that case the window advances as each point arrives instead,
+ * which is the same picture sampled less often.
+ *
+ * Screen readers receive one image-role snapshot: its name, current or
+ * selected value, direction, time window and paused state. It changes when the
+ * React data changes, never on the UI-thread clock frame, and requests no live
+ * announcement. The visual axes, badges and tooltip repeat that snapshot and
+ * stay out of the accessibility tree; controls placed in Header remain normal
+ * controls.
  *
  * ## Colour follows the recent direction
  *
@@ -56,7 +63,13 @@ import {
   useState,
   type ReactNode,
 } from 'react';
-import { StyleSheet, View, type LayoutChangeEvent, type ViewProps } from 'react-native';
+import {
+  AppState,
+  StyleSheet,
+  View,
+  type LayoutChangeEvent,
+  type ViewProps,
+} from 'react-native';
 import { Gesture, GestureDetector } from 'react-native-gesture-handler';
 import Animated, {
   runOnJS,
@@ -92,6 +105,13 @@ import {
   type Plot,
 } from '../../utils/chart';
 import { cn } from '../../utils/cn';
+import { liveLineAccessibility } from './live-line-accessibility';
+import {
+  liveLineClockRuns,
+  normalizeLiveLinePoints,
+  normalizeLiveLineWindow,
+  reconcileLiveLineActivePoint,
+} from './live-line-lifecycle';
 
 const AnimatedPath = Animated.createAnimatedComponent(Path);
 
@@ -224,9 +244,16 @@ function runOf(
 
 export interface LiveLineChartProps extends ViewProps {
   className?: string;
-  /** The readings so far, oldest first. Append to it as they arrive. */
+  /**
+   * Names the chart's single screen-reader snapshot. Falls back to the Header
+   * title, then to "Live line chart".
+   */
+  accessibilityLabel?: string;
+  /** Additional guidance after the snapshot. No gesture is invented for it. */
+  accessibilityHint?: string;
+  /** The readings so far. Invalid values are dropped and timestamps are ordered. */
   data: LiveLinePoint[];
-  /** How much time the plot spans, in seconds. */
+  /** How much time the plot spans, in seconds. Invalid values use 30. */
   window?: number;
   /** Freeze the window where it is. The readings still arrive; the clock stops. */
   paused?: boolean;
@@ -239,7 +266,7 @@ export interface LiveLineChartProps extends ViewProps {
   /**
    * The most readings kept. Older ones are dropped, since they are off the
    * window and cannot come back — an unbounded feed otherwise grows an array
-   * for as long as the screen is open.
+   * for as long as the screen is open. Must be positive and finite.
    */
   maxPoints?: number;
   /** Width ÷ height of the plot. */
@@ -276,6 +303,8 @@ const LiveLineChartRoot = forwardRef<LiveLineChartHandle, LiveLineChartProps>(
       momentumColors,
       color,
       onActivePointChange,
+      accessibilityLabel,
+      accessibilityHint,
       children,
       ...props
     },
@@ -290,12 +319,13 @@ const LiveLineChartRoot = forwardRef<LiveLineChartHandle, LiveLineChartProps>(
     const domainMax = useSharedValue(0);
     const activeTime = useSharedValue(-1);
     const reducedMotion = useReducedMotion();
+    const [appState, setAppState] = useState(AppState.currentState ?? 'active');
     // Stripped of punctuation: `useId` returns something like `:r1:`, and a
     // colon inside a `url(#…)` reference does not resolve — which in RN SVG is
     // a clip that silently does nothing rather than an error.
     const clipId = `panelui-live-clip-${useId().replace(/[^a-zA-Z0-9]/g, '')}`;
 
-    const windowMs = Math.max(windowSeconds, 1) * 1000;
+    const windowMs = normalizeLiveLineWindow(windowSeconds) * 1000;
     const loading = status === 'loading';
 
     const hasYAxis = useMemo(() => {
@@ -308,6 +338,34 @@ const LiveLineChartRoot = forwardRef<LiveLineChartHandle, LiveLineChartProps>(
       return found;
     }, [children]);
 
+    const semanticParts = useMemo(() => {
+      let title: string | undefined;
+      let value: string | undefined;
+      let headerFormat: ((reading: number) => string) | undefined;
+      let tipFormat: ((reading: number) => string) | undefined;
+      let tooltipFormat: ((reading: number) => string) | undefined;
+      Children.forEach(children, (child) => {
+        if (!isValidElement(child)) return;
+        const part = (child.type as { displayName?: string }).displayName;
+        if (part === 'LiveLineChart.Header') {
+          const header = child.props as LiveLineChartHeaderProps;
+          title ??= header.title;
+          value ??= header.value;
+          headerFormat ??= header.formatValue;
+        } else if (part === 'LiveLineChart.Tip') {
+          tipFormat ??= (child.props as LiveLineChartTipProps).formatValue;
+        } else if (part === 'LiveLineChart.Tooltip') {
+          tooltipFormat ??= (child.props as LiveLineChartTooltipProps).formatValue;
+        }
+      });
+      return {
+        title,
+        value,
+        formatLatest: headerFormat ?? tipFormat,
+        formatActive: tooltipFormat ?? headerFormat ?? tipFormat,
+      };
+    }, [children]);
+
     const pad = { ...PADDING, left: hasYAxis ? Y_AXIS_WIDTH : PADDING.left };
     const plot: Plot = {
       left: pad.left,
@@ -322,7 +380,7 @@ const LiveLineChartRoot = forwardRef<LiveLineChartHandle, LiveLineChartProps>(
      * the one chart nobody bounded to be the one left running overnight.
      */
     const points = useMemo(
-      () => (data.length > maxPoints ? data.slice(data.length - maxPoints) : data),
+      () => normalizeLiveLinePoints(data, maxPoints),
       [data, maxPoints]
     );
 
@@ -331,6 +389,11 @@ const LiveLineChartRoot = forwardRef<LiveLineChartHandle, LiveLineChartProps>(
       values.value = points.map((point) => point.value);
     }, [points, times, values]);
 
+    useEffect(() => {
+      const subscription = AppState.addEventListener('change', setAppState);
+      return () => subscription.remove();
+    }, []);
+
     const liveLatest = points.length ? points[points.length - 1]! : null;
 
     /*
@@ -393,7 +456,7 @@ const LiveLineChartRoot = forwardRef<LiveLineChartHandle, LiveLineChartProps>(
       now.value = Date.now();
     }, false);
 
-    const running = !paused && !loading && !reducedMotion;
+    const running = liveLineClockRuns({ paused, loading, reducedMotion, appState });
 
     useEffect(() => {
       frame.setActive(running);
@@ -411,6 +474,13 @@ const LiveLineChartRoot = forwardRef<LiveLineChartHandle, LiveLineChartProps>(
       now.value = Date.now();
     }, [running, paused, points, now]);
 
+    // A frame callback is suspended with the app. Land on the wall clock as
+    // soon as it becomes active instead of showing the backgrounded window for
+    // one frame and relying on the platform to schedule a callback promptly.
+    useEffect(() => {
+      if (appState === 'active' && !paused) now.value = Date.now();
+    }, [appState, paused, now]);
+
     useImperativeHandle(
       ref,
       () => ({
@@ -434,6 +504,21 @@ const LiveLineChartRoot = forwardRef<LiveLineChartHandle, LiveLineChartProps>(
     if (!paused) heldMomentum.current = liveMomentum;
     const momentum = paused ? heldMomentum.current : liveMomentum;
 
+    const defaultFormat = (reading: number) => compactNumber(reading);
+    const semantic = liveLineAccessibility({
+      name: accessibilityLabel ?? semanticParts.title,
+      status,
+      latest,
+      activePoint,
+      momentum,
+      windowSeconds: windowMs / 1000,
+      paused,
+      now: Date.now(),
+      valueOverride: semanticParts.value,
+      formatLatest: semanticParts.formatLatest ?? defaultFormat,
+      formatActive: semanticParts.formatActive ?? defaultFormat,
+    });
+
     const base = useSeriesColor(color, 1);
     const successToken = useCSSVariable('--color-success');
     const destructiveToken = useCSSVariable('--color-destructive');
@@ -458,6 +543,13 @@ const LiveLineChartRoot = forwardRef<LiveLineChartHandle, LiveLineChartProps>(
       [onActivePointChange]
     );
 
+    useEffect(() => {
+      const next = reconcileLiveLineActivePoint(activePoint, points);
+      if (next === activePoint) return;
+      if (!next) activeTime.value = -1;
+      setActivePoint(next);
+    }, [activePoint, points, activeTime, setActivePoint]);
+
     const onLayout = (event: LayoutChangeEvent) => {
       const { width, height } = event.nativeEvent.layout;
       setSize((current) =>
@@ -519,8 +611,21 @@ const LiveLineChartRoot = forwardRef<LiveLineChartHandle, LiveLineChartProps>(
     return (
       <LiveLineChartContext.Provider value={context}>
         <View {...props} style={props.style} className={cn('w-full', className)}>
+          <View
+            accessible
+            accessibilityRole="image"
+            accessibilityLabel={semantic.label}
+            accessibilityHint={accessibilityHint}
+            style={{ position: 'absolute', left: -10_000, width: 1, height: 1 }}
+          />
           {header}
-          <View onLayout={onLayout} style={{ aspectRatio }} className="w-full">
+          <View
+            onLayout={onLayout}
+            style={{ aspectRatio }}
+            className="w-full"
+            accessibilityElementsHidden
+            importantForAccessibility="no-hide-descendants"
+          >
             {plot.width > 0 ? (
               <>
                 <Svg width="100%" height="100%" style={StyleSheet.absoluteFill}>
@@ -1026,6 +1131,14 @@ function LiveLineChartTooltip({ formatValue, className }: LiveLineChartTooltipPr
     [setActivePoint]
   );
 
+  useEffect(
+    () => () => {
+      activeTime.value = -1;
+      setActivePoint(null);
+    },
+    [activeTime, setActivePoint]
+  );
+
   const pan = useMemo(() => {
     const resolve = (x: number) => {
       'worklet';
@@ -1259,7 +1372,11 @@ function LiveLineChartHeader({
       {...props}
       className={cn('flex-row items-start justify-between gap-3 pb-3', className)}
     >
-      <View className="flex-1 gap-0.5">
+      <View
+        className="flex-1 gap-0.5"
+        accessibilityElementsHidden
+        importantForAccessibility="no-hide-descendants"
+      >
         {title ? (
           <Text size="xs" muted>
             {title}

package/src/components/live-line-chart/live-line-accessibility.ts

@@ -0,0 +1,61 @@
+export interface LiveLineAccessiblePoint {
+  time: number;
+  value: number;
+}
+
+export interface LiveLineAccessibilityInput {
+  name?: string;
+  status: 'loading' | 'ready';
+  latest: LiveLineAccessiblePoint | null;
+  activePoint: LiveLineAccessiblePoint | null;
+  momentum: 'up' | 'down' | 'flat';
+  windowSeconds: number;
+  paused: boolean;
+  now: number;
+  valueOverride?: string;
+  formatLatest: (value: number) => string;
+  formatActive: (value: number) => string;
+}
+
+/** One bounded snapshot for a stream, rather than one node per arriving point. */
+export function liveLineAccessibility({
+  name,
+  status,
+  latest,
+  activePoint,
+  momentum,
+  windowSeconds,
+  paused,
+  now,
+  valueOverride,
+  formatLatest,
+  formatActive,
+}: LiveLineAccessibilityInput) {
+  const parts = [name?.trim() || 'Live line chart'];
+
+  if (status === 'loading') {
+    parts.push('Loading');
+    if (paused) parts.push('Paused');
+    return { label: parts.join('. ') };
+  }
+
+  if (!latest) {
+    parts.push('No readings');
+    if (paused) parts.push('Paused');
+    return { label: parts.join('. ') };
+  }
+
+  if (activePoint) {
+    const secondsAgo = Math.max(0, Math.round((now - activePoint.time) / 1000));
+    parts.push(`Selected value, ${formatActive(activePoint.value)}`);
+    parts.push(secondsAgo === 0 ? 'Just now' : `${secondsAgo} seconds ago`);
+  } else {
+    parts.push(`Current value, ${valueOverride ?? formatLatest(latest.value)}`);
+    const direction = momentum === 'up' ? 'rising' : momentum === 'down' ? 'falling' : 'steady';
+    parts.push(`Trend, ${direction}`);
+  }
+
+  parts.push(`${windowSeconds}-second window`);
+  if (paused) parts.push('Paused');
+  return { label: parts.join('. ') };
+}

package/src/components/live-line-chart/live-line-lifecycle.ts

@@ -0,0 +1,63 @@
+import type { AppStateStatus } from 'react-native';
+
+export interface LiveLineReading {
+  time: number;
+  value: number;
+}
+
+export const DEFAULT_LIVE_LINE_WINDOW = 30;
+export const DEFAULT_LIVE_LINE_MAX_POINTS = 500;
+
+export function normalizeLiveLineWindow(seconds: number): number {
+  return Number.isFinite(seconds) && seconds > 0
+    ? Math.max(seconds, 1)
+    : DEFAULT_LIVE_LINE_WINDOW;
+}
+
+export function normalizeLiveLineMaxPoints(maxPoints: number): number {
+  return Number.isFinite(maxPoints) && maxPoints > 0
+    ? Math.max(1, Math.floor(maxPoints))
+    : DEFAULT_LIVE_LINE_MAX_POINTS;
+}
+
+/**
+ * Builds the one ordered, finite buffer every renderer and interaction reads.
+ * For duplicate timestamps the last input wins, matching a corrected reading
+ * arriving with the same identity as the one it replaces.
+ */
+export function normalizeLiveLinePoints<T extends LiveLineReading>(
+  data: readonly T[],
+  maxPoints: number,
+): T[] {
+  const byTime = new Map<number, T>();
+  for (const point of data) {
+    if (Number.isFinite(point.time) && Number.isFinite(point.value)) {
+      byTime.set(point.time, point);
+    }
+  }
+  return [...byTime.values()]
+    .sort((left, right) => left.time - right.time)
+    .slice(-normalizeLiveLineMaxPoints(maxPoints));
+}
+
+export function liveLineClockRuns(options: {
+  paused: boolean;
+  loading: boolean;
+  reducedMotion: boolean;
+  appState: AppStateStatus;
+}): boolean {
+  return (
+    !options.paused &&
+    !options.loading &&
+    !options.reducedMotion &&
+    options.appState === 'active'
+  );
+}
+
+export function reconcileLiveLineActivePoint<T extends LiveLineReading>(
+  active: T | null,
+  points: readonly T[],
+): T | null {
+  if (!active) return null;
+  return points.find((point) => point.time === active.time) ?? null;
+}