@dtour/viewer 0.1.0

package/src/state/spec-sync.ts

@@ -0,0 +1,190 @@
+import type { WritableAtom } from 'jotai';
+import { useStore } from 'jotai';
+import { useEffect, useRef } from 'react';
+import type { DtourSpec } from '../spec.ts';
+import {
+  cameraPanXAtom,
+  cameraPanYAtom,
+  cameraZoomAtom,
+  pointColorAtom,
+  pointOpacityAtom,
+  pointSizeAtom,
+  previewCountAtom,
+  previewPaddingAtom,
+  previewScaleAtom,
+  showLegendAtom,
+  themeModeAtom,
+  tourByAtom,
+  tourDirectionAtom,
+  tourPlayingAtom,
+  tourPositionAtom,
+  tourSpeedAtom,
+  viewModeAtom,
+} from './atoms.ts';
+
+// ---------------------------------------------------------------------------
+// Spec ↔ Atom mapping
+// ---------------------------------------------------------------------------
+
+type SpecEntry<S, A> = {
+  atom: WritableAtom<A, [A], void>;
+  toAtom: (v: S) => A;
+  fromAtom: (v: A) => S;
+};
+
+function identity<T>(v: T): T {
+  return v;
+}
+
+function entry<T>(atom: WritableAtom<T, [T], void>): SpecEntry<T, T> {
+  return { atom, toAtom: identity, fromAtom: identity };
+}
+
+const SPEC_ATOM_MAP = {
+  tourBy: entry(tourByAtom),
+  tourPosition: entry(tourPositionAtom),
+  tourPlaying: entry(tourPlayingAtom),
+  tourSpeed: entry(tourSpeedAtom),
+  tourDirection: {
+    atom: tourDirectionAtom,
+    toAtom: (v: 'forward' | 'backward') => (v === 'forward' ? 1 : -1) as 1 | -1,
+    fromAtom: (v: 1 | -1): 'forward' | 'backward' => (v === 1 ? 'forward' : 'backward'),
+  },
+  previewCount: entry(previewCountAtom),
+  previewScale: entry(previewScaleAtom),
+  previewPadding: entry(previewPaddingAtom),
+  pointSize: entry(pointSizeAtom),
+  pointOpacity: entry(pointOpacityAtom),
+  pointColor: entry(pointColorAtom),
+  cameraPanX: entry(cameraPanXAtom),
+  cameraPanY: entry(cameraPanYAtom),
+  cameraZoom: entry(cameraZoomAtom),
+  viewMode: entry(viewModeAtom),
+  showLegend: entry(showLegendAtom),
+  themeMode: entry(themeModeAtom),
+} as const;
+
+type SpecKey = keyof typeof SPEC_ATOM_MAP;
+const SPEC_KEYS = Object.keys(SPEC_ATOM_MAP) as SpecKey[];
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function shallowEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (a[i] !== b[i]) return false;
+    }
+    return true;
+  }
+  return false;
+}
+
+/** Read all atoms from the store and build a full resolved spec. */
+function readFullSpec(store: ReturnType<typeof useStore>): Required<DtourSpec> {
+  const spec = {} as Record<string, unknown>;
+  for (const key of SPEC_KEYS) {
+    const mapping = SPEC_ATOM_MAP[key];
+    // biome-ignore lint/suspicious/noExplicitAny: generic atom mapping
+    const raw = store.get(mapping.atom as any);
+    // biome-ignore lint/suspicious/noExplicitAny: generic transform
+    spec[key] = (mapping as any).fromAtom(raw);
+  }
+  return spec as Required<DtourSpec>;
+}
+
+// ---------------------------------------------------------------------------
+// Hook: initialize store from spec (called once before first render)
+// ---------------------------------------------------------------------------
+
+export function initStoreFromSpec(
+  store: ReturnType<typeof useStore>,
+  spec: DtourSpec | undefined,
+): void {
+  if (!spec) return;
+  for (const key of SPEC_KEYS) {
+    const value = spec[key];
+    if (value !== undefined) {
+      const mapping = SPEC_ATOM_MAP[key];
+      // biome-ignore lint/suspicious/noExplicitAny: generic atom mapping
+      store.set(mapping.atom as any, (mapping as any).toAtom(value));
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Hook: bidirectional spec ↔ atoms sync
+// ---------------------------------------------------------------------------
+
+const DEBOUNCE_MS = 250;
+
+export function useSpecSync(
+  spec: DtourSpec | undefined,
+  onSpecChange: ((spec: Required<DtourSpec>) => void) | undefined,
+): void {
+  const store = useStore();
+  const suppressRef = useRef(false);
+  const onSpecChangeRef = useRef(onSpecChange);
+  onSpecChangeRef.current = onSpecChange;
+
+  // Inbound: spec prop → atoms
+  useEffect(() => {
+    if (!spec) return;
+    suppressRef.current = true;
+
+    for (const key of SPEC_KEYS) {
+      const value = spec[key];
+      if (value === undefined) continue;
+      const mapping = SPEC_ATOM_MAP[key];
+      // biome-ignore lint/suspicious/noExplicitAny: generic atom mapping
+      const atomValue = (mapping as any).toAtom(value);
+      // biome-ignore lint/suspicious/noExplicitAny: generic atom mapping
+      const current = store.get(mapping.atom as any);
+      if (!shallowEqual(atomValue, current)) {
+        // biome-ignore lint/suspicious/noExplicitAny: generic atom mapping
+        store.set(mapping.atom as any, atomValue);
+      }
+    }
+
+    queueMicrotask(() => {
+      suppressRef.current = false;
+    });
+  }, [spec, store]);
+
+  // Outbound: atoms → onSpecChange (debounced)
+  useEffect(() => {
+    if (!onSpecChangeRef.current) return;
+
+    let dirty = false;
+    let timerId: ReturnType<typeof setTimeout> | null = null;
+
+    const flush = () => {
+      timerId = null;
+      if (suppressRef.current || !dirty) return;
+      dirty = false;
+      onSpecChangeRef.current?.(readFullSpec(store));
+    };
+
+    const scheduleFlush = () => {
+      dirty = true;
+      if (timerId === null) {
+        timerId = setTimeout(flush, DEBOUNCE_MS);
+      }
+    };
+
+    const unsubs: (() => void)[] = [];
+    for (const key of SPEC_KEYS) {
+      const mapping = SPEC_ATOM_MAP[key];
+      // biome-ignore lint/suspicious/noExplicitAny: generic atom mapping
+      unsubs.push(store.sub(mapping.atom as any, scheduleFlush));
+    }
+
+    return () => {
+      for (const unsub of unsubs) unsub();
+      if (timerId !== null) clearTimeout(timerId);
+    };
+  }, [store]);
+}

package/src/styles.css

@@ -0,0 +1,44 @@
+@import "tailwindcss/theme";
+@import "tailwindcss/utilities";
+@import "tw-animate-css";
+
+@theme {
+  --color-dtour-bg: #000000;
+  --color-dtour-surface: #222222;
+  --color-dtour-border: #333333;
+  --color-dtour-text: #bbbbbb;
+  --color-dtour-text-muted: #888888;
+  --color-dtour-accent: #4080e8;
+  --color-dtour-accent-hover: #5090f0;
+  --color-dtour-highlight: #ffffff;
+}
+
+/* --- Light theme overrides --- */
+
+:where(.dtour-light) {
+  --color-dtour-bg: #ffffff;
+  --color-dtour-surface: #f0f0f0;
+  --color-dtour-border: #d0d0d0;
+  --color-dtour-text: #333333;
+  --color-dtour-text-muted: #777777;
+  --color-dtour-accent: #2060c0;
+  --color-dtour-accent-hover: #1850a8;
+  --color-dtour-highlight: #000000;
+}
+
+/* --- Animation easing utility for tw-animate-css --- */
+
+@utility animate-ease-out {
+  animation-timing-function: ease-out;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms;
+    animation-delay: 0ms;
+    animation-iteration-count: 1;
+    transition-duration: 0.01ms;
+  }
+}

package/src/views.ts

@@ -0,0 +1,76 @@
+/**
+ * Create default "little tour" view matrices that cycle through consecutive
+ * dimension pairs: (d0,d1), (d1,d2), ..., wrapping back to the start.
+ *
+ * Each view is a p×2 column-major Float32Array:
+ *   [x0, x1, ..., xp-1, y0, y1, ..., yp-1]
+ *
+ * When `activeIndices` is provided, only those dimensions get non-zero
+ * basis weights — inactive dimensions contribute zero to the projection.
+ *
+ * @param dims          - total number of dimensions (p)
+ * @param count         - number of views to generate (defaults to active dim count)
+ * @param activeIndices - sorted array of active dimension indices (defaults to all)
+ * @returns array of view matrices
+ */
+export const createDefaultViews = (
+  dims: number,
+  count?: number,
+  activeIndices?: number[],
+): Float32Array[] => {
+  const indices = activeIndices ?? Array.from({ length: dims }, (_, i) => i);
+  const activeDims = indices.length;
+  const n = count ?? activeDims;
+  const views: Float32Array[] = [];
+  for (let i = 0; i < n; i++) {
+    const basis = new Float32Array(dims * 2);
+    const idx = Math.floor((i / n) * activeDims);
+    basis[indices[idx]!] = 1; // active dim → x
+    basis[dims + indices[(idx + 1) % activeDims]!] = 1; // next active dim → y
+    views.push(basis);
+  }
+  return views;
+};
+
+/**
+ * Create tour views from PCA eigenvectors.
+ * Cycles through consecutive PC pairs: [PC1,PC2], [PC2,PC3], ..., wrapping.
+ *
+ * Each eigenvector becomes a column of the p×2 basis matrix. Eigenvectors
+ * are assumed to be in the normalized space matching the projection shader.
+ *
+ * @param eigenvectors - sorted by descending eigenvalue, each of length pcaDims
+ * @param totalDims    - total number of dimensions in the dataset (p)
+ * @param pcaDims      - number of PCA dimensions (may be < totalDims if capped)
+ * @param count        - number of views to generate (defaults to number of PCs)
+ */
+export const createPCAViews = (
+  eigenvectors: Float32Array[],
+  totalDims: number,
+  pcaDims: number,
+  count?: number,
+): Float32Array[] => {
+  const numPCs = eigenvectors.length;
+  const n = count ?? numPCs;
+  const views: Float32Array[] = [];
+
+  for (let i = 0; i < n; i++) {
+    const basis = new Float32Array(totalDims * 2);
+    const pcX = i % numPCs;
+    const pcY = (i + 1) % numPCs;
+
+    const evX = eigenvectors[pcX]!;
+    for (let d = 0; d < pcaDims; d++) {
+      basis[d] = evX[d]!;
+    }
+
+    const evY = eigenvectors[pcY]!;
+    for (let d = 0; d < pcaDims; d++) {
+      basis[totalDims + d] = evY[d]!;
+    }
+
+    views.push(basis);
+  }
+
+  return views;
+};

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "declarationMap": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src"]
+}

package/vite.config.ts

@@ -0,0 +1,21 @@
+import { resolve } from 'node:path';
+import tailwindcss from '@tailwindcss/vite';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [tailwindcss(), react()],
+  build: {
+    lib: {
+      entry: resolve(__dirname, 'src/index.ts'),
+      name: 'DtourViewer',
+      fileName: 'viewer',
+      formats: ['es'],
+      cssFileName: 'viewer',
+    },
+    rolldownOptions: {
+      // Peer dependencies — consumers provide these
+      external: ['react', 'react-dom', 'react/jsx-runtime', 'jotai'],
+    },
+  },
+});