@dtour/viewer 0.1.0

package/src/components/AxisOverlay.tsx

@@ -0,0 +1,224 @@
+import type { ScatterInstance } from '@dtour/scatter';
+import { useAtomValue, useSetAtom, useStore } from 'jotai';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { gramSchmidt } from '../lib/gram-schmidt.ts';
+import {
+  activeIndicesAtom,
+  cameraPanXAtom,
+  cameraPanYAtom,
+  cameraZoomAtom,
+  currentBasisAtom,
+  metadataAtom,
+} from '../state/atoms.ts';
+
+type AxisOverlayProps = {
+  scatter: ScatterInstance | null;
+  width: number;
+  height: number;
+};
+
+/** Convert SVG pixel delta to NDC delta (inverse camera). */
+const svgDeltaToNdc = (
+  dx: number,
+  dy: number,
+  width: number,
+  height: number,
+  zoom: number,
+): [number, number] => {
+  const aspect = width / height || 1;
+  const ndcDx = ((dx / width) * 2 * aspect) / zoom;
+  const ndcDy = (-(dy / height) * 2) / zoom;
+  return [ndcDx, ndcDy];
+};
+
+const HANDLE_RADIUS = 6;
+const AXIS_COLORS = ['#e06060', '#60a0e0', '#60c060', '#c080e0', '#e0a040', '#40c0c0'];
+
+export const AxisOverlay = ({ scatter, width, height }: AxisOverlayProps) => {
+  const metadata = useAtomValue(metadataAtom);
+  const panX = useAtomValue(cameraPanXAtom);
+  const panY = useAtomValue(cameraPanYAtom);
+  const zoom = useAtomValue(cameraZoomAtom);
+  const activeIndices = useAtomValue(activeIndicesAtom);
+  const store = useStore();
+  const setCurrentBasis = useSetAtom(currentBasisAtom);
+
+  const basisRef = useRef<Float32Array | null>(null);
+  const [, forceRender] = useState(0);
+  const draggingRef = useRef<number | null>(null);
+
+  const dims = metadata?.dimCount ?? 0;
+  const columnNames = metadata?.columnNames ?? [];
+
+  const activeSet = useMemo(() => new Set(activeIndices), [activeIndices]);
+
+  // Initialize basis from the current projection (read imperatively to avoid
+  // subscribing). This preserves the view when switching into manual mode.
+  // Re-runs when activeIndices change to zero out inactive dimensions.
+  useEffect(() => {
+    if (dims < 2 || activeIndices.length < 2) return;
+    const current = store.get(currentBasisAtom);
+    let basis: Float32Array;
+    if (current && current.length === dims * 2) {
+      basis = new Float32Array(current);
+    } else {
+      basis = new Float32Array(dims * 2);
+      basis[activeIndices[0]!] = 1;
+      basis[dims + activeIndices[1]!] = 1;
+    }
+    // Zero out inactive dimensions and re-orthonormalize
+    for (let d = 0; d < dims; d++) {
+      if (!activeSet.has(d)) {
+        basis[d] = 0;
+        basis[dims + d] = 0;
+      }
+    }
+    gramSchmidt(basis, dims);
+    basisRef.current = basis;
+    forceRender((n) => n + 1);
+    // No setDirectBasis here — the GPU already shows this projection
+  }, [dims, activeIndices, activeSet, store]);
+
+  const sendBasis = useCallback(() => {
+    if (!scatter || !basisRef.current) return;
+    const copy = basisRef.current.slice();
+    scatter.setDirectBasis(copy);
+    setCurrentBasis(new Float32Array(copy));
+  }, [scatter, setCurrentBasis]);
+
+  const handlePointerDown = useCallback((dimIndex: number, e: React.PointerEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+    (e.target as Element).setPointerCapture(e.pointerId);
+    draggingRef.current = dimIndex;
+  }, []);
+
+  const handlePointerMove = useCallback(
+    (e: React.PointerEvent) => {
+      const d = draggingRef.current;
+      if (d === null || !basisRef.current) return;
+      e.preventDefault();
+
+      const [ndcDx, ndcDy] = svgDeltaToNdc(e.movementX, e.movementY, width, height, zoom);
+      const basis = basisRef.current;
+
+      // Update basis row d: column 0 (x projection) and column 1 (y projection)
+      basis[d]! += ndcDx;
+      basis[dims + d]! += ndcDy;
+
+      // Re-orthonormalize
+      gramSchmidt(basis, dims);
+
+      forceRender((n) => n + 1);
+      sendBasis();
+    },
+    [width, height, zoom, dims, sendBasis],
+  );
+
+  const handlePointerUp = useCallback(() => {
+    draggingRef.current = null;
+  }, []);
+
+  const handleAltClick = useCallback(
+    (dimIndex: number, e: React.MouseEvent) => {
+      if (!e.altKey || !basisRef.current) return;
+      e.preventDefault();
+      const basis = basisRef.current;
+      // Negate basis row d (flip axis direction)
+      basis[dimIndex]! = -basis[dimIndex]!;
+      basis[dims + dimIndex]! = -basis[dims + dimIndex]!;
+      forceRender((n) => n + 1);
+      sendBasis();
+    },
+    [dims, sendBasis],
+  );
+
+  if (!metadata || dims < 2 || !basisRef.current || width === 0) return null;
+
+  const basis = basisRef.current;
+  const cx = width / 2;
+  const cy = height / 2;
+
+  // Scale factor for axis lines (proportion of view)
+  const scale = Math.min(width, height) * 0.35;
+
+  return (
+    <svg
+      width={width}
+      height={height}
+      role="img"
+      aria-label="Axis overlay for manual projection control"
+      className="absolute top-0 left-0 pointer-events-none"
+      onPointerMove={handlePointerMove}
+      onPointerUp={handlePointerUp}
+    >
+      {activeIndices.map((d) => {
+        // Basis row d gives (x, y) projection weights
+        const bx = basis[d]!;
+        const by = basis[dims + d]!;
+
+        // Use scale to determine line endpoint from center
+        const lineEndX = cx + bx * scale;
+        const lineEndY = cy - by * scale; // flip Y
+
+        const color = AXIS_COLORS[d % AXIS_COLORS.length]!;
+        const label = columnNames[d] ?? `dim${d}`;
+
+        return (
+          <g key={label}>
+            {/* Axis line outline */}
+            <line
+              x1={cx}
+              y1={cy}
+              x2={lineEndX}
+              y2={lineEndY}
+              stroke="var(--color-dtour-bg)"
+              strokeWidth={3}
+              strokeOpacity={0.6}
+            />
+            {/* Axis line */}
+            <line
+              x1={cx}
+              y1={cy}
+              x2={lineEndX}
+              y2={lineEndY}
+              stroke={color}
+              strokeWidth={1}
+              strokeOpacity={0.6}
+            />
+            {/* Draggable handle */}
+            <circle
+              cx={lineEndX}
+              cy={lineEndY}
+              r={HANDLE_RADIUS}
+              fill={color}
+              stroke="var(--color-dtour-bg)"
+              strokeWidth={1}
+              className="cursor-grab pointer-events-auto"
+              onPointerDown={(e) => handlePointerDown(d, e)}
+              onKeyDown={(e) =>
+                e.key === 'Enter' && handleAltClick(d, e as unknown as React.MouseEvent)
+              }
+              onClick={(e) => handleAltClick(d, e)}
+            />
+            {/* Label */}
+            <text
+              x={lineEndX + (bx >= 0 ? 10 : -10)}
+              y={lineEndY + 4}
+              fill={color}
+              fontSize={11}
+              fontFamily="monospace"
+              textAnchor={bx >= 0 ? 'start' : 'end'}
+              className="pointer-events-none select-none"
+              stroke="var(--color-dtour-bg)"
+              strokeWidth={2}
+              paintOrder="stroke"
+            >
+              {label}
+            </text>
+          </g>
+        );
+      })}
+    </svg>
+  );
+};

package/src/components/CircularSlider.tsx

@@ -0,0 +1,202 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { cn } from '../lib/utils';
+
+export type CircularSliderProps = {
+  /** Current position [0, 1]. */
+  value: number;
+  /** Called on each drag move (immediate position update). */
+  onChange: (value: number) => void;
+  /** Called on initial click/tap (animated seek). Falls back to onChange if omitted. */
+  onSeek?: (value: number) => void;
+  /** Called on first drag move after mousedown (lets parent cancel animations). */
+  onDragStart?: () => void;
+  /** Number of tick marks around the ring (typically = number of tour views). */
+  tickCount?: number;
+  /** SVG diameter in px. Default 200. */
+  size?: number;
+};
+
+export const CircularSlider = ({
+  value,
+  onChange,
+  onSeek,
+  onDragStart,
+  tickCount = 8,
+  size = 200,
+}: CircularSliderProps) => {
+  const [isDragging, setIsDragging] = useState(false);
+  const hasDraggedRef = useRef(false);
+  const svgRef = useRef<SVGSVGElement>(null);
+  const prevValue = useRef(value);
+
+  // Detect wrap-around (e.g. 0.98 → 0.02) to suppress arc flicker
+  const isWrapping = Math.abs(value - prevValue.current) > 0.5;
+  prevValue.current = value;
+
+  const center = size / 2;
+  const radius = size * 0.4;
+
+  const angleFromPointer = useCallback(
+    (clientX: number, clientY: number): number => {
+      if (!svgRef.current) return 0;
+      const rect = svgRef.current.getBoundingClientRect();
+      const dx = clientX - (rect.left + center);
+      const dy = clientY - (rect.top + center);
+      // atan2 gives angle from +x axis; rotate so 0 is at 10:30 position, clockwise
+      // 10:30 = -135° from +x axis, so offset by +135°
+      let deg = (Math.atan2(dy, dx) * 180) / Math.PI + 135;
+      if (deg < 0) deg += 360;
+      if (deg >= 360) deg -= 360;
+      return deg / 360; // normalize to [0, 1]
+    },
+    [center],
+  );
+
+  const handlePointerDown = useCallback(
+    (e: React.MouseEvent | React.TouchEvent) => {
+      setIsDragging(true);
+      hasDraggedRef.current = false;
+      const pt = 'touches' in e ? e.touches[0] : e;
+      if (pt) {
+        const pos = angleFromPointer(pt.clientX, pt.clientY);
+        // Animated seek on click; falls back to immediate onChange
+        (onSeek ?? onChange)(pos);
+      }
+    },
+    [angleFromPointer, onChange, onSeek],
+  );
+
+  useEffect(() => {
+    if (!isDragging) return;
+
+    const onMove = (e: MouseEvent | TouchEvent) => {
+      if (!hasDraggedRef.current) {
+        hasDraggedRef.current = true;
+        onDragStart?.(); // let parent cancel any running animation
+      }
+      const pt = 'touches' in e ? e.touches[0] : e;
+      if (pt) onChange(angleFromPointer(pt.clientX, pt.clientY));
+      if ('touches' in e) e.preventDefault();
+    };
+    const onUp = () => setIsDragging(false);
+
+    document.addEventListener('mousemove', onMove);
+    document.addEventListener('mouseup', onUp);
+    document.addEventListener('touchmove', onMove, { passive: false });
+    document.addEventListener('touchend', onUp);
+
+    return () => {
+      document.removeEventListener('mousemove', onMove);
+      document.removeEventListener('mouseup', onUp);
+      document.removeEventListener('touchmove', onMove);
+      document.removeEventListener('touchend', onUp);
+    };
+  }, [isDragging, angleFromPointer, onChange, onDragStart]);
+
+  // Convert value [0,1] back to handle position
+  // 10:30 start = -135° from +x axis
+  const startDeg = -135;
+  const handleRad = ((value * 360 + startDeg) * Math.PI) / 180;
+  const handleX = center + radius * Math.cos(handleRad);
+  const handleY = center + radius * Math.sin(handleRad);
+
+  // Arc from 10:30 to handle
+  const startRad = (startDeg * Math.PI) / 180;
+  const startX = center + radius * Math.cos(startRad);
+  const startY = center + radius * Math.sin(startRad);
+  const largeArc = value > 0.5 ? 1 : 0;
+
+  // Tick marks
+  const ticks = Array.from({ length: tickCount }, (_, i) => {
+    const tickRad = (((i / tickCount) * 360 + startDeg) * Math.PI) / 180;
+    const r1 = radius - 8;
+    const r2 = radius - 3;
+    return (
+      <line
+        // biome-ignore lint/suspicious/noArrayIndexKey: tick key
+        key={i}
+        x1={center + r1 * Math.cos(tickRad)}
+        y1={center + r1 * Math.sin(tickRad)}
+        x2={center + r2 * Math.cos(tickRad)}
+        y2={center + r2 * Math.sin(tickRad)}
+        stroke="var(--color-dtour-text-muted)"
+        strokeWidth="2"
+      />
+    );
+  });
+
+  return (
+    <svg
+      ref={svgRef}
+      width={size}
+      height={size}
+      onMouseDown={handlePointerDown}
+      onTouchStart={handlePointerDown}
+      className="pointer-events-none select-none touch-none"
+    >
+      <title>Circular slider for Dtour</title>
+      {/* Transparent hit area for track ring — wider for easier clicking */}
+      <circle
+        cx={center}
+        cy={center}
+        r={radius}
+        fill="none"
+        stroke="transparent"
+        strokeWidth="20"
+        className="cursor-pointer pointer-events-auto"
+      />
+      {/* Track ring */}
+      <circle
+        cx={center}
+        cy={center}
+        r={radius}
+        fill="none"
+        stroke="var(--color-dtour-border)"
+        strokeWidth="3"
+        className="pointer-events-none"
+      />
+      {/* Ticks */}
+      {ticks}
+      {/* Arc showing position */}
+      {value > 0.001 && !isWrapping && (
+        <path
+          d={`M ${startX} ${startY} A ${radius} ${radius} 0 ${largeArc} 1 ${handleX} ${handleY}`}
+          fill="none"
+          stroke="var(--color-dtour-highlight)"
+          strokeWidth="4"
+          strokeLinecap="round"
+          className="pointer-events-none"
+        />
+      )}
+      {/* Center dot */}
+      <circle
+        cx={center}
+        cy={center}
+        r="3"
+        fill="var(--color-dtour-text-muted)"
+        className="pointer-events-none"
+      />
+      {/* Transparent hit area for handle — larger for easier grabbing */}
+      <circle
+        cx={handleX}
+        cy={handleY}
+        r="16"
+        fill="transparent"
+        className={cn(
+          'cursor-grab pointer-events-auto',
+          isDragging ? 'cursor-grabbing' : 'cursor-grab',
+        )}
+      />
+      {/* Handle */}
+      <circle
+        cx={handleX}
+        cy={handleY}
+        r="8"
+        fill="var(--color-dtour-highlight)"
+        stroke="var(--color-dtour-bg)"
+        strokeWidth="2"
+        className="pointer-events-none"
+      />
+    </svg>
+  );
+};

package/src/components/ColorLegend.tsx

@@ -0,0 +1,178 @@
+import { GLASBEY_DARK, GLASBEY_LIGHT, MAGMA_25, OKABE_ITO, VIRIDIS_25 } from '@dtour/scatter';
+import { useAtom, useAtomValue, useSetAtom } from 'jotai';
+import { useCallback } from 'react';
+import { hexToRgb255 } from '../lib/color-utils.ts';
+import {
+  colorMapAtom,
+  legendClearGenAtom,
+  legendSelectionAtom,
+  metadataAtom,
+  paletteAtom,
+  pointColorAtom,
+  resolvedThemeAtom,
+} from '../state/atoms.ts';
+
+const handleSwatchClick = (
+  index: number,
+  event: React.MouseEvent,
+  setSelection: (update: (prev: Set<number> | null) => Set<number> | null) => void,
+  setClearGen: (update: (prev: number) => number) => void,
+) => {
+  const isMeta = event.metaKey || event.ctrlKey;
+  const isAlt = event.altKey;
+
+  setSelection((prev) => {
+    if (isMeta) {
+      const next = new Set(prev ?? []);
+      if (next.has(index)) next.delete(index);
+      else next.add(index);
+      if (next.size === 0) {
+        setClearGen((g) => g + 1);
+        return null;
+      }
+      return next;
+    }
+
+    if (isAlt) {
+      if (!prev) return prev;
+      const next = new Set(prev);
+      next.delete(index);
+      if (next.size === 0) {
+        setClearGen((g) => g + 1);
+        return null;
+      }
+      return next;
+    }
+
+    // Plain click: select only this one, or toggle off if sole selection
+    if (prev && prev.size === 1 && prev.has(index)) {
+      setClearGen((g) => g + 1);
+      return null;
+    }
+    return new Set([index]);
+  });
+};
+
+export const ColorLegend = () => {
+  const metadata = useAtomValue(metadataAtom);
+  const pointColor = useAtomValue(pointColorAtom);
+  const palette = useAtomValue(paletteAtom);
+  const resolvedTheme = useAtomValue(resolvedThemeAtom);
+  const rawColorMap = useAtomValue(colorMapAtom);
+  const [legendSelection, setLegendSelection] = useAtom(legendSelectionAtom);
+  const setClearGen = useSetAtom(legendClearGenAtom);
+
+  const onSwatchClick = useCallback(
+    (index: number, event: React.MouseEvent) => {
+      handleSwatchClick(index, event, setLegendSelection, setClearGen);
+    },
+    [setLegendSelection, setClearGen],
+  );
+
+  if (typeof pointColor !== 'string' || !metadata) return null;
+  const column = pointColor;
+
+  const isCategorical = metadata.categoricalColumnNames.includes(column);
+  const hasSelection = legendSelection !== null;
+
+  if (isCategorical) {
+    const labels = metadata.categoricalLabels[column] ?? [];
+    let colors: [number, number, number][];
+    if (rawColorMap) {
+      colors = labels.map((label) => {
+        const v = rawColorMap[label];
+        if (!v) return [128, 128, 128] as [number, number, number];
+        const hex = typeof v === 'string' ? v : v[resolvedTheme];
+        return hexToRgb255(hex);
+      });
+    } else {
+      const glasbey = resolvedTheme === 'light' ? GLASBEY_LIGHT : GLASBEY_DARK;
+      colors =
+        labels.length <= OKABE_ITO.length
+          ? OKABE_ITO
+          : ([
+              ...OKABE_ITO,
+              ...Array(Math.ceil((labels.length - OKABE_ITO.length) / glasbey.length))
+                .fill(undefined)
+                .flatMap(() => glasbey),
+            ] as [number, number, number][]);
+    }
+    return (
+      <div className="flex h-full flex-col overflow-hidden bg-dtour-bg text-xs text-dtour-text">
+        <div className="flex h-10 shrink-0 items-center border-b border-dtour-surface px-3 font-semibold text-dtour-highlight truncate">
+          {column}
+        </div>
+        <div className="flex flex-col gap-1.5 overflow-y-auto px-3 pt-3 pb-3">
+          {labels.map((label, i) => {
+            const [r, g, b] = colors[i % colors.length]!;
+            const dimmed = hasSelection && !legendSelection.has(i);
+            return (
+              <button
+                key={label}
+                type="button"
+                className={`flex items-center gap-2 min-w-0 cursor-pointer rounded px-1 py-0.5 transition-opacity hover:bg-dtour-highlight/10 ${dimmed ? 'opacity-35' : 'opacity-100'}`}
+                onClick={(e) => onSwatchClick(i, e)}
+              >
+                <span
+                  className="shrink-0 w-3 h-3 rounded-sm"
+                  style={{ backgroundColor: `rgb(${r},${g},${b})` }}
+                />
+                <span className="truncate">{label}</span>
+              </button>
+            );
+          })}
+        </div>
+      </div>
+    );
+  }
+
+  // Continuous (numeric column)
+  const colIndex = metadata.columnNames.indexOf(column);
+  if (colIndex === -1) return null;
+  const min = metadata.mins[colIndex]!;
+  const max = metadata.maxes[colIndex]!;
+
+  // 13 stops from 25-entry cmap (step 2): labeled on even stopIdx, unlabeled in between
+  const step = 2;
+  const stops: { value: number; color: [number, number, number]; stopIdx: number }[] = [];
+  const baseCmap = palette === 'magma' ? MAGMA_25 : VIRIDIS_25;
+  const cmap =
+    resolvedTheme === 'light' ? ([...baseCmap].reverse() as [number, number, number][]) : baseCmap;
+  for (let i = 0; i < cmap.length; i += step) {
+    const t = i / (cmap.length - 1);
+    stops.push({ value: min + t * (max - min), color: cmap[i]!, stopIdx: i / step });
+  }
+
+  return (
+    <div className="flex h-full flex-col overflow-hidden bg-dtour-bg text-xs text-dtour-text">
+      <div className="flex h-10 shrink-0 items-center border-b border-dtour-surface px-3 font-semibold text-dtour-highlight truncate">
+        {column}
+      </div>
+      <div className="flex flex-col gap-0.5 overflow-y-auto px-3 pt-3 pb-3">
+        {stops.reverse().map(({ value, color: [r, g, b], stopIdx }) => {
+          const dimmed = hasSelection && !legendSelection.has(stopIdx);
+          const showLabel = stopIdx % 2 === 0;
+          return (
+            <button
+              key={value}
+              type="button"
+              className={`flex items-center gap-2 min-w-0 cursor-pointer rounded px-1 py-0.5 transition-opacity hover:bg-dtour-highlight/10 ${dimmed ? 'opacity-35' : 'opacity-100'}`}
+              onClick={(e) => onSwatchClick(stopIdx, e)}
+            >
+              <span
+                className="shrink-0 w-3 h-3 rounded-sm"
+                style={{ backgroundColor: `rgb(${r},${g},${b})` }}
+              />
+              {showLabel && <span className="truncate">{formatValue(value)}</span>}
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+};
+
+const formatValue = (v: number): string => {
+  if (Number.isInteger(v) && Math.abs(v) < 1e6) return String(v);
+  return v.toPrecision(3);
+};