@cdx-ui/components 0.3.4 → 0.3.6

package/src/components/chart/ChartInspector.tsx

@@ -0,0 +1,726 @@
+import { useEffect, useRef, useState } from 'react';
+import { PanResponder, Platform, Pressable, Text, View } from 'react-native';
+import { dataAttributes } from '@cdx-ui/primitives';
+import type { ChartTooltipContent, ChartTooltipItem } from './types';
+
+export interface ChartInspectorTarget {
+  readonly key: string;
+  /** Hit box in overlay coordinates. */
+  readonly left: number;
+  readonly top: number;
+  readonly width: number;
+  readonly height: number;
+  /** Point the tooltip sits beside. */
+  readonly anchorX: number;
+  readonly anchorY: number;
+  /** Half-width of the mark at the anchor, so the tooltip clears it. */
+  readonly anchorRadius?: number;
+  readonly tooltip: ChartTooltipContent;
+  readonly accessibilityLabel: string;
+  readonly selected: boolean;
+  /** Keyboard focus ring. Defaults to the hit box. */
+  readonly outline?: {
+    readonly left: number;
+    readonly top: number;
+    readonly width: number;
+    readonly height: number;
+  };
+}
+
+interface InspectorKeyEvent {
+  readonly nativeEvent: { readonly key: string; readonly shiftKey?: boolean };
+  readonly key?: string;
+  readonly shiftKey?: boolean;
+  readonly preventDefault?: () => void;
+}
+
+interface InspectorBlurEvent {
+  nativeEvent: { relatedTarget?: unknown };
+  relatedTarget?: unknown;
+}
+
+const TOOLTIP_GAP = 8;
+const TOOLTIP_MAX_WIDTH = 192;
+/** WCAG 2.5.8 (AA) is 24px; 44px matches Apple HIG / WCAG 2.5.5 for touch. */
+export const MIN_POINTER_TARGET_PX = 44;
+/** Hold before scrubbing a scrollable plot, so a flick can still scroll (Apple Health). */
+export const CHART_SCRUB_HOLD_MS = 250;
+const SCRUB_MOVE_SLOP_PX = 10;
+
+interface InspectorTouchEvent {
+  nativeEvent: {
+    locationX?: number;
+    locationY?: number;
+    pageX?: number;
+    pageY?: number;
+    touches?: readonly {
+      locationX?: number;
+      locationY?: number;
+      pageX?: number;
+      pageY?: number;
+    }[];
+  };
+}
+
+function touchPoint(event: InspectorTouchEvent): {
+  locationX: number;
+  locationY: number;
+  pageX: number;
+  pageY: number;
+} {
+  const touch = event.nativeEvent.touches?.[0];
+  const locationX = touch?.locationX ?? event.nativeEvent.locationX ?? 0;
+  const locationY = touch?.locationY ?? event.nativeEvent.locationY ?? 0;
+  return {
+    locationX,
+    locationY,
+    pageX: touch?.pageX ?? event.nativeEvent.pageX ?? locationX,
+    pageY: touch?.pageY ?? event.nativeEvent.pageY ?? locationY,
+  };
+}
+
+export function expandHitBox(
+  left: number,
+  top: number,
+  width: number,
+  height: number,
+  minSize: number = MIN_POINTER_TARGET_PX,
+): { left: number; top: number; width: number; height: number } {
+  const nextWidth = Math.max(width, minSize);
+  const nextHeight = Math.max(height, minSize);
+  return {
+    left: left - (nextWidth - width) / 2,
+    top: top - (nextHeight - height) / 2,
+    width: nextWidth,
+    height: nextHeight,
+  };
+}
+
+function targetIndexAt(
+  targets: readonly ChartInspectorTarget[],
+  x: number,
+  y: number,
+): number | null {
+  const hit = targets.findIndex(
+    (target) =>
+      x >= target.left &&
+      x <= target.left + target.width &&
+      y >= target.top &&
+      y <= target.top + target.height,
+  );
+  return hit >= 0 ? hit : null;
+}
+
+export function chartValueText(item: ChartTooltipItem): string {
+  return item.label.length > 0 ? `${item.label} ${item.formattedValue}` : item.formattedValue;
+}
+
+interface ChartTooltipSize {
+  readonly width: number;
+  readonly height: number;
+}
+
+function clampInto(value: number, min: number, max: number): number {
+  // Wider than the frame: center it so it overflows both edges equally.
+  if (max < min) {
+    return (min + max) / 2;
+  }
+  return Math.min(Math.max(value, min), max);
+}
+
+/**
+ * Top-left of a tooltip in frame coordinates. Beside the anchor on the roomier side when it
+ * fits, otherwise above or below it; always clamped inside the frame so a clipping ancestor
+ * (a `Card`, a `ScrollView`) cannot cut it off.
+ */
+export function placeChartTooltip(
+  anchor: { readonly x: number; readonly y: number; readonly radius?: number },
+  tip: ChartTooltipSize,
+  frame: ChartTooltipSize,
+): { left: number; top: number } {
+  const gap = TOOLTIP_GAP + (anchor.radius ?? 0);
+  const rightOf = anchor.x + gap;
+  const leftOf = anchor.x - gap - tip.width;
+  const fitsRight = rightOf + tip.width <= frame.width;
+  const fitsLeft = leftOf >= 0;
+  const maxLeft = frame.width - tip.width;
+  const maxTop = frame.height - tip.height;
+  if (fitsLeft || fitsRight) {
+    const useLeft = anchor.x > frame.width / 2 ? fitsLeft : !fitsRight;
+    const top = anchor.y > frame.height / 2 ? anchor.y - tip.height : anchor.y;
+    return { left: useLeft ? leftOf : rightOf, top: clampInto(top, 0, maxTop) };
+  }
+  const above = anchor.y - TOOLTIP_GAP - tip.height;
+  const top = above >= 0 ? above : anchor.y + TOOLTIP_GAP;
+  return {
+    left: clampInto(anchor.x - tip.width / 2, 0, maxLeft),
+    top: clampInto(top, 0, maxTop),
+  };
+}
+
+/** Renders only from `content`, so a consumer tooltip slot can replace it later. */
+function ChartTooltip({
+  content,
+  noValueText,
+  slot,
+  onSize,
+}: {
+  content: ChartTooltipContent;
+  noValueText: string;
+  slot: string;
+  onSize: (size: ChartTooltipSize) => void;
+}) {
+  return (
+    <View
+      className="gap-1 rounded-md bg-surface-neutral-strong px-3 py-2 shadow-lg"
+      onLayout={(event) => {
+        const { width, height } = event.nativeEvent.layout;
+        onSize({ width, height });
+      }}
+      aria-hidden
+      accessibilityElementsHidden
+      importantForAccessibility="no-hide-descendants"
+      {...dataAttributes({ slot: `${slot}-tooltip` })}
+    >
+      <Text className="body-sm font-medium text-content-neutral-on-strong">{content.title}</Text>
+      {content.items.length === 0 ? (
+        <Text className="body-sm text-content-neutral-on-strong">{noValueText}</Text>
+      ) : (
+        content.items.map((item) => (
+          <View key={item.seriesId} className="flex-row items-center gap-1.5">
+            <View className="size-2 rounded-full" style={{ backgroundColor: item.color }} />
+            <Text className="body-sm text-content-neutral-on-strong">{chartValueText(item)}</Text>
+          </View>
+        ))
+      )}
+    </View>
+  );
+}
+
+/**
+ * Chart tooltip, measured and clamped inside `width` × `height`. Mount it in the chart's
+ * outer plot frame, never inside the plot `ScrollView`, which clips its content.
+ */
+export function ChartTooltipLayer({
+  content,
+  noValueText,
+  slot,
+  anchorX,
+  anchorY,
+  anchorRadius,
+  width,
+  height,
+}: {
+  content: ChartTooltipContent;
+  noValueText: string;
+  slot: string;
+  /** Anchor in frame coordinates. */
+  anchorX: number;
+  anchorY: number;
+  anchorRadius?: number;
+  width: number;
+  height: number;
+}) {
+  const [size, setSize] = useState<ChartTooltipSize | null>(null);
+  const position =
+    size === null
+      ? { left: 0, top: 0 }
+      : placeChartTooltip({ x: anchorX, y: anchorY, radius: anchorRadius }, size, {
+          width,
+          height,
+        });
+  // A fixed-width box at the frame origin lets the tooltip take its natural width wherever it
+  // lands; `left`/`right` offsets shrink it to the space left before the frame edge.
+  return (
+    <View
+      pointerEvents="none"
+      className="absolute left-0 top-0 z-20 items-start"
+      style={{
+        width: TOOLTIP_MAX_WIDTH,
+        opacity: size === null ? 0 : 1,
+        transform: [{ translateX: position.left }, { translateY: position.top }],
+      }}
+    >
+      <ChartTooltip
+        content={content}
+        noValueText={noValueText}
+        slot={slot}
+        onSize={(next) => {
+          setSize((prev) =>
+            prev?.width === next.width && prev.height === next.height ? prev : next,
+          );
+        }}
+      />
+    </View>
+  );
+}
+
+/**
+ * Host-element hit targets over an SVG plot. SVG nodes are poor focus and hover targets under
+ * React Native Web, so each target is a `Pressable` with roving focus: one tab stop per chart.
+ * Web: native `mousemove` (RN Web `Pressable` has no hover). Native: press-and-drag on the
+ * overlay; the tooltip tracks the finger and clears on lift. When the plot itself scrolls,
+ * scrubbing waits for a short hold so a flick can still pan. Keyboard and VoiceOver still use
+ * the buttons (Escape / two-finger Z).
+ */
+export function ChartInspector({
+  targets,
+  summary,
+  selectable,
+  activeIndex,
+  selectedIndex,
+  slot,
+  holdToScrub = false,
+  onActivate,
+  onDeactivate,
+  onDismiss,
+  onSelectIndex,
+  hitTest,
+  neighborIndex,
+  onScrubLockChange,
+}: {
+  targets: readonly ChartInspectorTarget[];
+  summary: string;
+  selectable: boolean;
+  activeIndex: number | null;
+  selectedIndex: number | null;
+  slot: string;
+  /** Wait for a hold before capturing the pan, so a scrollable plot can still flick-scroll. */
+  holdToScrub?: boolean;
+  onActivate: (index: number) => void;
+  /** Called with the target that lost hover or focus. Ignore it if another target is already active. */
+  onDeactivate: (index: number) => void;
+  onDismiss: () => void;
+  onSelectIndex: (index: number) => void;
+  /** When set, pointer hits use this instead of the rectangular target boxes (line charts). */
+  hitTest?: (x: number, y: number) => number | null;
+  /** Override linear arrow-key movement (grouped / stacked bar charts). */
+  neighborIndex?: (index: number, key: string) => number | null;
+  /**
+   * Fires when a hold locks the finger to scrubbing (`true`) and when it lifts (`false`).
+   * The parent must disable its `ScrollView` while locked, or the native pan steals the drag.
+   */
+  onScrubLockChange?: (locked: boolean) => void;
+}) {
+  const refs = useRef<(View | null)[]>([]);
+  const overlayRef = useRef<View>(null);
+  const [keyboardFocus, setKeyboardFocus] = useState(false);
+  const pointerRef = useRef({
+    targets,
+    hitTest,
+    selectable,
+    holdToScrub,
+    onActivate,
+    onDeactivate,
+    onDismiss,
+    onSelectIndex,
+    activeIndex,
+    neighborIndex,
+    onScrubLockChange,
+  });
+  pointerRef.current = {
+    targets,
+    hitTest,
+    selectable,
+    holdToScrub,
+    onActivate,
+    onDeactivate,
+    onDismiss,
+    onSelectIndex,
+    activeIndex,
+    neighborIndex,
+    onScrubLockChange,
+  };
+  const scrubRef = useRef({
+    locked: false,
+    holdTimer: null as ReturnType<typeof setTimeout> | null,
+    startPageX: 0,
+    startPageY: 0,
+    lastX: 0,
+    lastY: 0,
+  });
+
+  const hitAtPoint = (x: number, y: number) => {
+    const { targets: nextTargets, hitTest: test } = pointerRef.current;
+    return test ? test(x, y) : targetIndexAt(nextTargets, x, y);
+  };
+  const activateAtPoint = (x: number, y: number) => {
+    const next = hitAtPoint(x, y);
+    const {
+      onActivate: activate,
+      activeIndex: index,
+      onDeactivate: deactivate,
+    } = pointerRef.current;
+    if (next === null) {
+      if (index !== null) {
+        deactivate(index);
+      }
+      return;
+    }
+    activate(next);
+  };
+  const clearHoldTimer = () => {
+    if (scrubRef.current.holdTimer != null) {
+      clearTimeout(scrubRef.current.holdTimer);
+      scrubRef.current.holdTimer = null;
+    }
+  };
+  const clearPointer = () => {
+    const { activeIndex: index, onDeactivate: deactivate, onDismiss: dismiss } = pointerRef.current;
+    dismiss();
+    if (index !== null) {
+      deactivate(index);
+    }
+  };
+  const finishScrub = () => {
+    const wasLocked = scrubRef.current.locked;
+    // A tap that never passed the scroll slop still selects. A move that cancelled the
+    // hold is a scroll and leaves the chart alone.
+    const wasTap =
+      pointerRef.current.holdToScrub && !wasLocked && scrubRef.current.holdTimer != null;
+    clearHoldTimer();
+    const shouldFinish = wasLocked || wasTap || !pointerRef.current.holdToScrub;
+    scrubRef.current.locked = false;
+    if (wasLocked) {
+      pointerRef.current.onScrubLockChange?.(false);
+    }
+    if (!shouldFinish) {
+      return;
+    }
+    const {
+      activeIndex: index,
+      selectable: canSelect,
+      onSelectIndex: select,
+      onActivate: activate,
+    } = pointerRef.current;
+    const hit = wasTap ? hitAtPoint(scrubRef.current.lastX, scrubRef.current.lastY) : index;
+    if (wasTap && hit !== null) {
+      activate(hit);
+    }
+    if (canSelect && hit !== null) {
+      select(hit);
+    }
+    clearPointer();
+  };
+  const beginHold = (event: InspectorTouchEvent) => {
+    if (Platform.OS === 'web') {
+      return;
+    }
+    const point = touchPoint(event);
+    clearHoldTimer();
+    scrubRef.current.locked = false;
+    scrubRef.current.startPageX = point.pageX;
+    scrubRef.current.startPageY = point.pageY;
+    scrubRef.current.lastX = point.locationX;
+    scrubRef.current.lastY = point.locationY;
+    if (!pointerRef.current.holdToScrub) {
+      activateAtPoint(point.locationX, point.locationY);
+      return;
+    }
+    scrubRef.current.holdTimer = setTimeout(() => {
+      scrubRef.current.holdTimer = null;
+      scrubRef.current.locked = true;
+      pointerRef.current.onScrubLockChange?.(true);
+      activateAtPoint(scrubRef.current.lastX, scrubRef.current.lastY);
+    }, CHART_SCRUB_HOLD_MS);
+  };
+  const noteHoldMove = (event: InspectorTouchEvent) => {
+    const point = touchPoint(event);
+    scrubRef.current.lastX = point.locationX;
+    scrubRef.current.lastY = point.locationY;
+    if (!pointerRef.current.holdToScrub) {
+      activateAtPoint(point.locationX, point.locationY);
+      return;
+    }
+    if (scrubRef.current.locked || scrubRef.current.holdTimer == null) {
+      return;
+    }
+    const dist = Math.hypot(
+      point.pageX - scrubRef.current.startPageX,
+      point.pageY - scrubRef.current.startPageY,
+    );
+    if (dist > SCRUB_MOVE_SLOP_PX) {
+      clearHoldTimer();
+    }
+  };
+
+  const panResponder = useRef(
+    PanResponder.create({
+      onStartShouldSetPanResponder: () => false,
+      onMoveShouldSetPanResponder: () => {
+        if (Platform.OS === 'web') {
+          return false;
+        }
+        return pointerRef.current.holdToScrub && scrubRef.current.locked;
+      },
+      onPanResponderTerminationRequest: () => !scrubRef.current.locked,
+      onPanResponderGrant: (event) => {
+        activateAtPoint(event.nativeEvent.locationX, event.nativeEvent.locationY);
+      },
+      onPanResponderMove: (event) => {
+        activateAtPoint(event.nativeEvent.locationX, event.nativeEvent.locationY);
+      },
+      onPanResponderRelease: finishScrub,
+      onPanResponderTerminate: finishScrub,
+    }),
+  ).current;
+
+  const count = targets.length;
+  const rovingIndex = Math.min(activeIndex ?? selectedIndex ?? 0, Math.max(count - 1, 0));
+
+  // RN Web Pressable does not emit hover. Bind the DOM node directly so mousemove
+  // along the line (and across category bands) opens the tooltip.
+  useEffect(() => {
+    const node = overlayRef.current as unknown as HTMLElement | null;
+    if (node == null || typeof node.addEventListener !== 'function') {
+      return;
+    }
+    const hitAt = (event: MouseEvent) => {
+      const { targets: nextTargets, hitTest: test } = pointerRef.current;
+      const rect = node.getBoundingClientRect();
+      const x = event.clientX - rect.left;
+      const y = event.clientY - rect.top;
+      return test ? test(x, y) : targetIndexAt(nextTargets, x, y);
+    };
+    const clearActive = () => {
+      const {
+        activeIndex: index,
+        onDeactivate: deactivate,
+        onDismiss: dismiss,
+      } = pointerRef.current;
+      dismiss();
+      if (index !== null) {
+        deactivate(index);
+      }
+    };
+    const move = (event: MouseEvent) => {
+      setKeyboardFocus(false);
+      const next = hitAt(event);
+      const {
+        onActivate: activate,
+        activeIndex: index,
+        onDeactivate: deactivate,
+      } = pointerRef.current;
+      if (next === null) {
+        if (index !== null) {
+          deactivate(index);
+        }
+        return;
+      }
+      activate(next);
+    };
+    const down = (event: MouseEvent) => {
+      if (event.button !== 0) {
+        return;
+      }
+      setKeyboardFocus(false);
+      const next = hitAt(event);
+      const {
+        onActivate: activate,
+        selectable: canSelect,
+        onSelectIndex: select,
+      } = pointerRef.current;
+      if (next === null) {
+        clearActive();
+        return;
+      }
+      activate(next);
+      if (canSelect) {
+        select(next);
+      }
+    };
+    const leave = (event: MouseEvent) => {
+      if (node.contains(event.relatedTarget as Node | null)) {
+        return;
+      }
+      const { activeIndex: index, onDeactivate: deactivate } = pointerRef.current;
+      if (index !== null) {
+        deactivate(index);
+      }
+    };
+    const docDown = (event: MouseEvent) => {
+      if (node.contains(event.target as Node | null)) {
+        return;
+      }
+      clearActive();
+    };
+    node.addEventListener('mousemove', move);
+    node.addEventListener('mousedown', down);
+    node.addEventListener('mouseleave', leave);
+    document.addEventListener('mousedown', docDown);
+    return () => {
+      node.removeEventListener('mousemove', move);
+      node.removeEventListener('mousedown', down);
+      node.removeEventListener('mouseleave', leave);
+      document.removeEventListener('mousedown', docDown);
+      if (scrubRef.current.holdTimer != null) {
+        clearTimeout(scrubRef.current.holdTimer);
+        scrubRef.current.holdTimer = null;
+      }
+    };
+  }, []);
+
+  const handleKeyDown = (index: number, event: InspectorKeyEvent) => {
+    const key = event.nativeEvent.key ?? event.key ?? '';
+    const shiftKey = event.shiftKey === true || event.nativeEvent.shiftKey === true;
+    if (
+      key === 'Escape' ||
+      key === 'Enter' ||
+      key === ' ' ||
+      key === 'Tab' ||
+      key === 'ArrowRight' ||
+      key === 'ArrowLeft' ||
+      key === 'ArrowUp' ||
+      key === 'ArrowDown' ||
+      key === 'Home' ||
+      key === 'End'
+    ) {
+      setKeyboardFocus(true);
+    }
+    if (key === 'Escape') {
+      event.preventDefault?.();
+      onDismiss();
+      return;
+    }
+    if (key === 'Enter' || key === ' ') {
+      event.preventDefault?.();
+      onActivate(index);
+      if (selectable) {
+        onSelectIndex(index);
+      }
+      return;
+    }
+    if (key === 'Tab') {
+      const next = neighborIndex?.(index, shiftKey ? 'Shift+Tab' : 'Tab');
+      if (next === undefined || next === null || next === index) {
+        return;
+      }
+      event.preventDefault?.();
+      onActivate(next);
+      refs.current[next]?.focus();
+      return;
+    }
+    let next: number | null = neighborIndex?.(index, key) ?? null;
+    if (next === null) {
+      if (key === 'ArrowRight' || key === 'ArrowDown') {
+        next = Math.min(index + 1, count - 1);
+      } else if (key === 'ArrowLeft' || key === 'ArrowUp') {
+        next = Math.max(index - 1, 0);
+      } else if (key === 'Home') {
+        next = 0;
+      } else if (key === 'End') {
+        next = count - 1;
+      }
+    }
+    if (next === null) {
+      return;
+    }
+    event.preventDefault?.();
+    onActivate(next);
+    refs.current[next]?.focus();
+  };
+
+  const blurInspector = (event: InspectorBlurEvent | undefined) => {
+    const related = event?.nativeEvent?.relatedTarget ?? event?.relatedTarget;
+    const node = overlayRef.current as unknown as {
+      contains?: (target: unknown) => boolean;
+    } | null;
+    if (node?.contains?.(related) === true) {
+      return;
+    }
+    setKeyboardFocus(false);
+    if (activeIndex !== null) {
+      onDeactivate(activeIndex);
+    }
+  };
+
+  const outline =
+    keyboardFocus && activeIndex !== null
+      ? (targets.at(activeIndex)?.outline ?? targets.at(activeIndex))
+      : undefined;
+
+  return (
+    <View
+      ref={overlayRef}
+      className="absolute inset-0 z-10"
+      role="group"
+      aria-label={summary}
+      accessibilityLabel={summary}
+      onAccessibilityEscape={onDismiss}
+      {...(Platform.OS === 'web'
+        ? {}
+        : {
+            ...panResponder.panHandlers,
+            onTouchStart: beginHold,
+            onTouchMove: noteHoldMove,
+            onTouchEnd: finishScrub,
+            onTouchCancel: finishScrub,
+          })}
+      {...dataAttributes({ slot: `${slot}-inspector` })}
+    >
+      {outline !== undefined ? (
+        <View
+          pointerEvents="none"
+          className="absolute rounded-sm border-2 border-[var(--color-stroke-ring)]"
+          style={{
+            left: outline.left,
+            top: outline.top,
+            width: outline.width,
+            height: outline.height,
+          }}
+          accessibilityElementsHidden
+          importantForAccessibility="no-hide-descendants"
+          {...dataAttributes({ slot: `${slot}-focus` })}
+        />
+      ) : null}
+      {targets.map((target, index) => (
+        <Pressable
+          key={target.key}
+          ref={(node) => {
+            refs.current[index] = node;
+          }}
+          className="absolute rounded-sm web:outline-none"
+          style={{
+            left: target.left,
+            top: target.top,
+            width: target.width,
+            height: target.height,
+          }}
+          accessibilityRole="button"
+          accessibilityLabel={target.accessibilityLabel}
+          accessibilityState={
+            selectable && Platform.OS !== 'web' ? { selected: target.selected } : undefined
+          }
+          aria-pressed={selectable && Platform.OS === 'web' ? target.selected : undefined}
+          pointerEvents="none"
+          focusable={Platform.OS !== 'web' || index === rovingIndex}
+          tabIndex={index === rovingIndex ? 0 : -1}
+          onHoverIn={() => {
+            onActivate(index);
+          }}
+          onHoverOut={() => {
+            onDeactivate(index);
+          }}
+          onFocus={() => {
+            setKeyboardFocus(true);
+            onActivate(index);
+          }}
+          onBlur={(event: unknown) => blurInspector(event as InspectorBlurEvent)}
+          onPress={() => {
+            onActivate(index);
+            if (selectable) {
+              onSelectIndex(index);
+            }
+          }}
+          onAccessibilityEscape={onDismiss}
+          {...{
+            onKeyDown: (event: InspectorKeyEvent) => {
+              handleKeyDown(index, event);
+            },
+          }}
+          {...dataAttributes({ slot: `${slot}-point`, selected: target.selected })}
+        />
+      ))}
+    </View>
+  );
+}