@dtour/viewer 0.1.0

package/src/radial-chart/RadialChart.tsx

@@ -0,0 +1,184 @@
+import { useCallback, useMemo, useState } from 'react';
+import { arcPath, keyframeAngle, rectBarPath } from './arc-path.ts';
+import type { ParsedTrack } from './types.ts';
+
+export type RadialChartProps = {
+  tracks: ParsedTrack[];
+  keyframeCount: number;
+  /** Current tour position [0, 1] for flanking highlight. */
+  position: number;
+  /** SVG viewport size (same as selectorSize). */
+  size: number;
+  /** Inner radius = selector ring radius (selectorSize * 0.4). */
+  innerRadius: number;
+};
+
+const TRACK_GAP = 2;
+const STACK_GAP = 1;
+const BAR_PAD_RAD = 0.02; // angular padding between bars in radians
+
+type HoverInfo = { label: string; value: number; x: number; y: number };
+
+export const RadialChart = ({
+  tracks,
+  keyframeCount,
+  position,
+  size,
+  innerRadius,
+}: RadialChartProps) => {
+  const center = size / 2;
+  const [hover, setHover] = useState<HoverInfo | null>(null);
+
+  const handleEnter = useCallback((label: string, value: number, x: number, y: number) => {
+    setHover({ label, value, x, y });
+  }, []);
+
+  const handleLeave = useCallback(() => {
+    setHover(null);
+  }, []);
+
+  const stacked = tracks.length > 0 && tracks.every((t) => t.barWidth !== 'full');
+
+  // Track-based layout: each track gets its own radial band
+  const trackLayout = useMemo(() => {
+    if (stacked) return [];
+    let offset = innerRadius + TRACK_GAP;
+    return tracks.map((t) => {
+      const rInner = offset;
+      const rOuter = offset + t.height;
+      offset = rOuter + TRACK_GAP;
+      return { rInner, rOuter };
+    });
+  }, [tracks, innerRadius, stacked]);
+
+  // Flanking keyframes based on current position
+  const fractionalIndex = position * keyframeCount;
+  const leftKf = Math.floor(fractionalIndex) % keyframeCount;
+  const rightKf = (leftKf + 1) % keyframeCount;
+
+  const segmentAngle = (2 * Math.PI) / keyframeCount;
+  const baseR = innerRadius + STACK_GAP;
+
+  if (import.meta.env.DEV) {
+    for (const track of tracks) {
+      if (track.normalizedValues.length !== keyframeCount) {
+        console.warn(
+          `[dtour] RadialChart track "${track.label}" has ${track.normalizedValues.length} values but keyframeCount is ${keyframeCount}. Bars will be clamped to the smaller count.`,
+        );
+      }
+    }
+  }
+
+  // Stacked mode: bars share a common baseline per keyframe, stacked outward
+  const stackedBars = useMemo(() => {
+    if (!stacked) return [];
+    const bars: {
+      key: string;
+      d: string;
+      color: string;
+      label: string;
+      rawValue: number;
+      tipX: number;
+      tipY: number;
+    }[] = [];
+
+    const barWidthPx = (tracks[0]?.barWidth as number) ?? 0;
+
+    for (let kfIdx = 0; kfIdx < keyframeCount; kfIdx++) {
+      const centerAngle = keyframeAngle(kfIdx, keyframeCount);
+
+      let stackBase = baseR;
+      for (let trackIdx = 0; trackIdx < tracks.length; trackIdx++) {
+        const track = tracks[trackIdx]!;
+        if (kfIdx >= track.normalizedValues.length) continue;
+
+        const normVal = track.normalizedValues[kfIdx]!;
+        const barHeight = normVal * track.height;
+        const barOuter = stackBase + barHeight;
+        const rawValue = track.rawValues[kfIdx] as number;
+
+        const midR = (stackBase + barOuter) / 2;
+        const tipX = center + midR * Math.cos(centerAngle);
+        const tipY = center + midR * Math.sin(centerAngle);
+
+        bars.push({
+          key: `${track.label}-${kfIdx}`,
+          d: rectBarPath(stackBase, barOuter, centerAngle, barWidthPx),
+          color: track.color,
+          label: track.label,
+          rawValue,
+          tipX,
+          tipY,
+        });
+
+        stackBase = barOuter + STACK_GAP;
+      }
+    }
+    return bars;
+  }, [stacked, tracks, keyframeCount, baseR, center]);
+
+  return (
+    <div className="relative" style={{ width: size, height: size }}>
+      {/* biome-ignore lint/a11y/noSvgWithoutTitle: decorative chart, no screen reader title needed */}
+      <svg width={size} height={size} className="overflow-visible pointer-events-none">
+        <g transform={`translate(${center}, ${center})`}>
+          {stacked
+            ? stackedBars.map((bar) => (
+                <path
+                  key={bar.key}
+                  d={bar.d}
+                  fill={bar.color}
+                  className="pointer-events-auto cursor-default opacity-60 hover:opacity-100 transition-[fill-opacity] duration-150 ease-out"
+                  onMouseEnter={() => handleEnter(bar.label, bar.rawValue, bar.tipX, bar.tipY)}
+                  onMouseLeave={handleLeave}
+                />
+              ))
+            : tracks.map((track, trackIdx) => {
+                const { rInner } = trackLayout[trackIdx]!;
+                return (
+                  <g key={track.label}>
+                    {track.normalizedValues.map((normVal, kfIdx) => {
+                      if (kfIdx >= keyframeCount) return null;
+
+                      const centerAngle = keyframeAngle(kfIdx, keyframeCount);
+                      const angleStart = centerAngle - segmentAngle / 2 + BAR_PAD_RAD;
+                      const angleEnd = centerAngle + segmentAngle / 2 - BAR_PAD_RAD;
+
+                      const barOuter = rInner + normVal * track.height;
+                      const rawValue = track.rawValues[kfIdx] as number;
+
+                      const midR = (rInner + barOuter) / 2;
+                      const tipX = center + midR * Math.cos(centerAngle);
+                      const tipY = center + midR * Math.sin(centerAngle);
+
+                      return (
+                        <path
+                          key={`${track.label}-${kfIdx}`}
+                          d={arcPath(rInner, barOuter, angleStart, angleEnd)}
+                          fill={track.color}
+                          className="pointer-events-auto cursor-default opacity-60 hover:opacity-100 transition-[fill-opacity] duration-150 ease-out"
+                          onMouseEnter={() => handleEnter(track.label, rawValue, tipX, tipY)}
+                          onMouseLeave={handleLeave}
+                        />
+                      );
+                    })}
+                  </g>
+                );
+              })}
+        </g>
+      </svg>
+
+      {/* Tooltip at bar center */}
+      {hover && (
+        <div
+          className="absolute pointer-events-none z-50"
+          style={{ left: hover.x, top: hover.y, transform: 'translate(-50%, -50%)' }}
+        >
+          <div className="rounded bg-dtour-highlight px-3 py-1.5 text-xs text-dtour-bg shadow-[0_1px_4px_rgba(0,0,0,0.6)] whitespace-nowrap">
+            {hover.label}: {hover.value.toFixed(3)}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+};

package/src/radial-chart/arc-path.ts

@@ -0,0 +1,80 @@
+/** Angular start offset: 10:30 o'clock position (-135 degrees from +x axis). */
+const START_DEG = -135;
+
+/**
+ * Center angle in radians for keyframe `index` out of `count` total keyframes.
+ * Uses the same angular convention as CircularSlider (10:30 start, clockwise).
+ */
+export const keyframeAngle = (index: number, count: number): number =>
+  (((index / count) * 360 + START_DEG) * Math.PI) / 180;
+
+/**
+ * SVG `d` attribute for an annular sector (arc segment between two radii).
+ *
+ * Draws: outer arc forward -> line to inner -> inner arc backward -> close.
+ *
+ * All angles in radians. Center is at (0, 0) — use a `<g transform>` to position.
+ */
+/**
+ * SVG `d` for a constant-width rectangular bar along a radial direction.
+ *
+ * Unlike arcPath (which widens with radius), this produces truly parallel
+ * sides so stacked segments align perfectly.
+ *
+ * Center is at (0, 0). `angle` is the bar's center direction in radians.
+ */
+export const rectBarPath = (
+  rInner: number,
+  rOuter: number,
+  angle: number,
+  width: number,
+): string => {
+  const hw = width / 2;
+  const cos = Math.cos(angle);
+  const sin = Math.sin(angle);
+  // perpendicular to radial direction: (-sin, cos)
+  const px = -sin;
+  const py = cos;
+
+  // four corners: inner-left, outer-left, outer-right, inner-right
+  const ilx = rInner * cos + hw * px;
+  const ily = rInner * sin + hw * py;
+  const olx = rOuter * cos + hw * px;
+  const oly = rOuter * sin + hw * py;
+  const orx = rOuter * cos - hw * px;
+  const ory = rOuter * sin - hw * py;
+  const irx = rInner * cos - hw * px;
+  const iry = rInner * sin - hw * py;
+
+  return `M ${ilx} ${ily} L ${olx} ${oly} L ${orx} ${ory} L ${irx} ${iry} Z`;
+};
+
+export const arcPath = (
+  rInner: number,
+  rOuter: number,
+  angleStart: number,
+  angleEnd: number,
+): string => {
+  const outerX1 = rOuter * Math.cos(angleStart);
+  const outerY1 = rOuter * Math.sin(angleStart);
+  const outerX2 = rOuter * Math.cos(angleEnd);
+  const outerY2 = rOuter * Math.sin(angleEnd);
+
+  const innerX1 = rInner * Math.cos(angleEnd);
+  const innerY1 = rInner * Math.sin(angleEnd);
+  const innerX2 = rInner * Math.cos(angleStart);
+  const innerY2 = rInner * Math.sin(angleStart);
+
+  // Determine if the arc spans more than 180 degrees
+  let sweep = angleEnd - angleStart;
+  if (sweep < 0) sweep += 2 * Math.PI;
+  const largeArc = sweep > Math.PI ? 1 : 0;
+
+  return [
+    `M ${outerX1} ${outerY1}`,
+    `A ${rOuter} ${rOuter} 0 ${largeArc} 1 ${outerX2} ${outerY2}`,
+    `L ${innerX1} ${innerY1}`,
+    `A ${rInner} ${rInner} 0 ${largeArc} 0 ${innerX2} ${innerY2}`,
+    'Z',
+  ].join(' ');
+};

package/src/radial-chart/index.ts

@@ -0,0 +1,4 @@
+export { RadialChart } from './RadialChart.tsx';
+export type { RadialChartProps } from './RadialChart.tsx';
+export type { ParsedTrack, RadialTrackConfig } from './types.ts';
+export { parseMetrics } from './parse-metrics.ts';

package/src/radial-chart/parse-metrics.ts

@@ -0,0 +1,99 @@
+import { tableFromIPC } from '@uwdata/flechette';
+import type { ParsedTrack, RadialTrackConfig } from './types.ts';
+
+/** Default color palette for auto-assigned track colors. */
+const PALETTE = [
+  '#4080e8', // accent blue
+  '#e8a040', // warm orange
+  '#50c878', // green
+  '#e05070', // rose
+  '#9070e0', // purple
+  '#40b8d0', // teal
+  '#d0a040', // gold
+  '#70a0c0', // steel blue
+];
+
+const DEFAULT_HEIGHT = 16;
+const DEFAULT_BAR_WIDTH: 'full' | number = 'full';
+
+const NUMERIC_TYPED_ARRAYS = new Set([
+  'Float32Array',
+  'Float64Array',
+  'Int8Array',
+  'Int16Array',
+  'Int32Array',
+  'Uint8Array',
+  'Uint16Array',
+  'Uint32Array',
+]);
+
+/**
+ * Parse an Arrow IPC buffer into per-track normalized data ready for rendering.
+ *
+ * Each column in the Arrow table represents a metric; rows are per-view values.
+ * When `configs` is provided, only the listed metrics are shown in that order.
+ * When omitted, all numeric columns are shown with auto-assigned colors.
+ */
+export const parseMetrics = (
+  buffer: ArrayBuffer,
+  configs?: RadialTrackConfig[],
+  defaultBarWidth?: 'full' | number,
+): ParsedTrack[] => {
+  const table = tableFromIPC(new Uint8Array(buffer));
+  const columns = table.toColumns() as Record<string, unknown>;
+
+  // Collect numeric columns
+  const numericColumns = new Map<string, Float32Array | Float64Array>();
+  for (const [name, arr] of Object.entries(columns)) {
+    if (!ArrayBuffer.isView(arr)) continue;
+    const tag = Object.prototype.toString.call(arr).slice(8, -1);
+    if (!NUMERIC_TYPED_ARRAYS.has(tag)) continue;
+    numericColumns.set(
+      name,
+      arr instanceof Float32Array || arr instanceof Float64Array
+        ? arr
+        : new Float32Array(arr as unknown as ArrayLike<number>),
+    );
+  }
+
+  // Determine which tracks to show
+  const trackDefs: { metric: string; config?: RadialTrackConfig }[] = configs
+    ? configs
+        .filter((c) => numericColumns.has(c.metric))
+        .map((c) => ({ metric: c.metric, config: c }))
+    : [...numericColumns.keys()].map((m) => ({ metric: m }));
+
+  return trackDefs.map(({ metric, config }, i): ParsedTrack => {
+    const raw = numericColumns.get(metric)!;
+
+    // Normalize
+    let min: number;
+    let max: number;
+    if (config?.domain) {
+      [min, max] = config.domain;
+    } else {
+      min = Number.POSITIVE_INFINITY;
+      max = Number.NEGATIVE_INFINITY;
+      for (let j = 0; j < raw.length; j++) {
+        const v = raw[j] as number;
+        if (v < min) min = v;
+        if (v > max) max = v;
+      }
+    }
+    // When all values are non-negative, normalize to [0, max] so bars have
+    // proportional heights (the smallest bar is still visible).
+    // When values span negative to positive (e.g. silhouette), use [min, max].
+    const base = min >= 0 ? 0 : min;
+    const range = max - base || 1;
+    const normalizedValues = Array.from(raw, (v) => Math.max(0, Math.min(1, (v - base) / range)));
+
+    return {
+      label: config?.label ?? metric,
+      rawValues: raw,
+      normalizedValues,
+      height: config?.height ?? DEFAULT_HEIGHT,
+      color: config?.color ?? (PALETTE[i % PALETTE.length] as string),
+      barWidth: config?.barWidth ?? defaultBarWidth ?? DEFAULT_BAR_WIDTH,
+    };
+  });
+};

package/src/radial-chart/types.ts

@@ -0,0 +1,23 @@
+export type RadialTrackConfig = {
+  /** Column name in the Arrow IPC table. */
+  metric: string;
+  /** Track height in px. Default 16. */
+  height?: number;
+  /** Bar fill color. Default auto-assigned from palette. */
+  color?: string;
+  /** 'full' = span the segment, number = fixed px width. Default 'full'. */
+  barWidth?: 'full' | number;
+  /** Explicit [min, max] domain. Default: per-track normalize. */
+  domain?: [number, number];
+  /** Tooltip label override. Default: column name. */
+  label?: string;
+};
+
+export type ParsedTrack = {
+  label: string;
+  rawValues: Float64Array | Float32Array;
+  normalizedValues: number[];
+  height: number;
+  color: string;
+  barWidth: 'full' | number;
+};

package/src/spec.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+
+/**
+ * JSON-serializable spec for the Dtour component.
+ * All fields optional — omitted fields use defaults.
+ * The Zod schema is the single source of truth; the TS type is inferred.
+ */
+export const dtourSpecSchema = z.object({
+  tourBy: z.enum(['dimensions', 'pca']).optional(),
+  tourPosition: z.number().min(0).max(1).optional(),
+  tourPlaying: z.boolean().optional(),
+  tourSpeed: z.number().min(0.1).max(5).optional(),
+  tourDirection: z.enum(['forward', 'backward']).optional(),
+  previewCount: z.union([z.literal(4), z.literal(8), z.literal(12), z.literal(16)]).optional(),
+  previewScale: z.union([z.literal(1), z.literal(0.75), z.literal(0.5)]).optional(),
+  previewPadding: z.number().nonnegative().optional(),
+  pointSize: z.union([z.number().positive(), z.literal('auto')]).optional(),
+  pointOpacity: z.union([z.number().min(0).max(1), z.literal('auto')]).optional(),
+  pointColor: z.union([z.tuple([z.number(), z.number(), z.number()]), z.string()]).optional(),
+  cameraPanX: z.number().optional(),
+  cameraPanY: z.number().optional(),
+  cameraZoom: z.number().positive().optional(),
+  viewMode: z.enum(['guided', 'manual', 'grand']).optional(),
+  showLegend: z.boolean().optional(),
+  themeMode: z.enum(['light', 'dark', 'system']).optional(),
+});
+
+export type DtourSpec = z.infer<typeof dtourSpecSchema>;
+
+export const DTOUR_DEFAULTS: Required<DtourSpec> = {
+  tourBy: 'dimensions',
+  tourPosition: 0,
+  tourPlaying: false,
+  tourSpeed: 1,
+  tourDirection: 'forward',
+  previewCount: 4,
+  previewScale: 1,
+  previewPadding: 12,
+  pointSize: 'auto',
+  pointOpacity: 'auto',
+  pointColor: [0.25, 0.5, 0.9],
+  cameraPanX: 0,
+  cameraPanY: 0,
+  cameraZoom: 1 / 1.5,
+  viewMode: 'guided',
+  showLegend: true,
+  themeMode: 'dark',
+};

package/src/state/atoms.ts

@@ -0,0 +1,169 @@
+import type { Metadata } from '@dtour/scatter';
+import { atom } from 'jotai';
+
+// ---------------------------------------------------------------------------
+// Tour state — controls position and playback along the tour path
+// ---------------------------------------------------------------------------
+
+/** Controls how tour keyframes are derived: raw dimension pairs or PCA eigenvectors. */
+export const tourByAtom = atom<'dimensions' | 'pca'>('dimensions');
+
+export const tourPositionAtom = atom(0);
+export const tourPlayingAtom = atom(false);
+export const tourSpeedAtom = atom(1);
+export const tourDirectionAtom = atom<1 | -1>(1);
+
+// ---------------------------------------------------------------------------
+// View state — controls preview layout and keyframe selection
+// ---------------------------------------------------------------------------
+
+export const previewCountAtom = atom<4 | 8 | 12 | 16>(4);
+export const previewScaleAtom = atom<1 | 0.75 | 0.5>(1);
+export const previewPaddingAtom = atom(12);
+export const selectedKeyframeAtom = atom<number | null>(null);
+
+// ---------------------------------------------------------------------------
+// Point style — visual appearance of scatter points
+// ---------------------------------------------------------------------------
+
+export const pointSizeAtom = atom<number | 'auto'>('auto');
+export const pointOpacityAtom = atom<number | 'auto'>('auto');
+export const pointColorAtom = atom<[number, number, number] | string>([0.25, 0.5, 0.9]);
+export const paletteAtom = atom<'viridis' | 'magma'>('viridis');
+
+/** Per-label color overrides. Values are hex strings or theme-aware {light, dark} objects. */
+export const colorMapAtom = atom<Record<string, string | { light: string; dark: string }> | null>(
+  null,
+);
+
+// ---------------------------------------------------------------------------
+// Background color — WebGPU clear color (RGB 0–1)
+// ---------------------------------------------------------------------------
+
+export const backgroundColorAtom = atom<[number, number, number]>([0, 0, 0]);
+
+// ---------------------------------------------------------------------------
+// Camera state — 2D pan and zoom
+// ---------------------------------------------------------------------------
+
+export const cameraPanXAtom = atom(0);
+export const cameraPanYAtom = atom(0);
+export const cameraZoomAtom = atom(1 / 1.5);
+
+// ---------------------------------------------------------------------------
+// View mode — controls which UI is shown (guided, manual, grand)
+// ---------------------------------------------------------------------------
+
+export const viewModeAtom = atom<'guided' | 'manual' | 'grand'>('guided');
+
+/**
+ * When true, `useScatter` skips `setTourPosition` messages.
+ * Set on returning to guided mode from manual/grand so the current
+ * projection is preserved until the user clicks the circular slider
+ * or presses play.
+ */
+export const guidedSuspendedAtom = atom(false);
+
+/** Target mode after grand ease-out completes. null = not exiting. */
+export const grandExitTargetAtom = atom<'guided' | 'manual' | null>(null);
+
+/**
+ * Tracks the currently-displayed projection basis (p×2 column-major).
+ * Updated by tour interpolation, manual axis dragging, and zen animation.
+ * Read imperatively (via store.get) on mode switch so the new mode
+ * can initialize from the current view without jumping.
+ */
+export const currentBasisAtom = atom<Float32Array | null>(null);
+
+// ---------------------------------------------------------------------------
+// Animation coordination — generation counter for cancellation
+// ---------------------------------------------------------------------------
+
+/**
+ * Incremented each time a position animation starts or is cancelled.
+ * Running animations bail out when their captured generation doesn't
+ * match the current value, ensuring only one animation drives the
+ * position at a time — even across different components.
+ */
+export const animationGenAtom = atom(0);
+
+// ---------------------------------------------------------------------------
+// Canvas size — tracked for auto opacity/size computation
+// ---------------------------------------------------------------------------
+
+export const canvasSizeAtom = atom({ width: 0, height: 0 });
+
+// ---------------------------------------------------------------------------
+// Read-only / derived — not exposed to AI setters
+// ---------------------------------------------------------------------------
+
+export const metadataAtom = atom<Metadata | null>(null);
+
+// ---------------------------------------------------------------------------
+// Column visibility — which numeric dimensions participate in the tour
+// ---------------------------------------------------------------------------
+
+/**
+ * Set of active dimension indices. `null` means all columns are active
+ * (initial state before metadata loads or when all are enabled).
+ */
+export const activeColumnsAtom = atom<Set<number> | null>(null);
+
+/**
+ * Resolved active dimension indices — never null after metadata loads.
+ * Returns sorted array for deterministic iteration in basis generation,
+ * grand tour, and manual mode.
+ */
+export const activeIndicesAtom = atom<number[]>((get) => {
+  const active = get(activeColumnsAtom);
+  const meta = get(metadataAtom);
+  if (!meta) return [];
+  if (active === null) return Array.from({ length: meta.dimCount }, (_, i) => i);
+  return Array.from(active).sort((a, b) => a - b);
+});
+
+// ---------------------------------------------------------------------------
+// Legend — collapsible color legend panel
+// ---------------------------------------------------------------------------
+
+/** User preference for showing the legend panel. */
+export const showLegendAtom = atom(true);
+
+/**
+ * Derived: legend is visible only when showLegend is true, metadata is loaded,
+ * AND points are colored by a known data column (numeric or categorical).
+ */
+export const legendVisibleAtom = atom((get) => {
+  if (!get(showLegendAtom)) return false;
+  const meta = get(metadataAtom);
+  if (!meta) return false;
+  const color = get(pointColorAtom);
+  if (typeof color !== 'string') return false;
+  return meta.columnNames.includes(color) || meta.categoricalColumnNames.includes(color);
+});
+
+// ---------------------------------------------------------------------------
+// Legend selection — which legend entries are actively selected
+// ---------------------------------------------------------------------------
+
+/** Which legend entries are selected, or null when no legend selection is active. */
+export const legendSelectionAtom = atom<Set<number> | null>(null);
+
+/** Bumped when ColorLegend explicitly deselects — triggers scatter.clearSelection(). */
+export const legendClearGenAtom = atom(0);
+
+// ---------------------------------------------------------------------------
+// Theme — light/dark mode with system preference support
+// ---------------------------------------------------------------------------
+
+/** User preference: explicit light/dark or follow system. */
+export const themeModeAtom = atom<'light' | 'dark' | 'system'>('dark');
+
+/** Tracks the OS-level color scheme. Updated by useSystemTheme hook. */
+export const systemThemeAtom = atom<'light' | 'dark'>('dark');
+
+/** Resolved theme after applying system preference. */
+export const resolvedThemeAtom = atom<'light' | 'dark'>((get) => {
+  const mode = get(themeModeAtom);
+  return mode === 'system' ? get(systemThemeAtom) : mode;
+});