@dtour/viewer 0.1.0

package/dist/views.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 declare const createDefaultViews: (dims: number, count?: number, activeIndices?: number[]) => Float32Array[];
+/**
+ * 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 declare const createPCAViews: (eigenvectors: Float32Array[], totalDims: number, pcaDims: number, count?: number) => Float32Array[];
+//# sourceMappingURL=views.d.ts.map

package/dist/views.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"views.d.ts","sourceRoot":"","sources":["../src/views.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,kBAAkB,GAC7B,MAAM,MAAM,EACZ,QAAQ,MAAM,EACd,gBAAgB,MAAM,EAAE,KACvB,YAAY,EAad,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,GACzB,cAAc,YAAY,EAAE,EAC5B,WAAW,MAAM,EACjB,SAAS,MAAM,EACf,QAAQ,MAAM,KACb,YAAY,EAwBd,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@dtour/viewer",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/viewer.js",
+  "exports": {
+    ".": {
+      "import": "./dist/viewer.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./dist/viewer.css": "./dist/viewer.css"
+  },
+  "scripts": {
+    "build": "vite build && tsc --emitDeclarationOnly --declaration --outDir dist",
+    "dev": "vite build --watch"
+  },
+  "dependencies": {
+    "@dtour/scatter": "workspace:*",
+    "@phosphor-icons/react": "^2.1.10",
+    "@radix-ui/react-dropdown-menu": "^2.1.16",
+    "@radix-ui/react-popover": "^1.1.15",
+    "@radix-ui/react-select": "^2.2.6",
+    "@radix-ui/react-slider": "^1.3.6",
+    "@radix-ui/react-slot": "catalog:",
+    "@tailwindcss/vite": "catalog:",
+    "@uwdata/flechette": "catalog:",
+    "class-variance-authority": "catalog:",
+    "clsx": "catalog:",
+    "jotai": "catalog:",
+    "radix-ui": "^1.4.3",
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "tailwind-merge": "catalog:",
+    "tailwindcss": "catalog:",
+    "tw-animate-css": "^1.4.0",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
+    "@vitejs/plugin-react": "catalog:",
+    "vite": "catalog:"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  }
+}

package/src/Dtour.tsx

@@ -0,0 +1,300 @@
+import type { ScatterInstance, ScatterStatus } from '@dtour/scatter';
+import { bitPackIndices } from '@dtour/scatter';
+import { Provider, createStore, useAtomValue, useSetAtom } from 'jotai';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { DtourViewer } from './DtourViewer.tsx';
+import { ColorLegend } from './components/ColorLegend.tsx';
+import { DtourToolbar } from './components/DtourToolbar.tsx';
+import { useModeCycling } from './hooks/useModeCycling.ts';
+import { useSystemTheme } from './hooks/useSystemTheme.ts';
+import { PortalContainerContext } from './portal-container.tsx';
+import type { RadialTrackConfig } from './radial-chart/types.ts';
+import type { DtourSpec } from './spec.ts';
+import {
+  backgroundColorAtom,
+  colorMapAtom,
+  legendSelectionAtom,
+  legendVisibleAtom,
+  metadataAtom,
+  pointColorAtom,
+  resolvedThemeAtom,
+  viewModeAtom,
+} from './state/atoms.ts';
+import { initStoreFromSpec, useSpecSync } from './state/spec-sync.ts';
+
+export type DtourHandle = {
+  /** Select points by index array or bit-packed mask. */
+  select: (
+    indicesOrMask: number[] | Int32Array | Uint32Array,
+    opts?: { isBitPacked?: boolean },
+  ) => void;
+  /** Clear the current selection. */
+  clearSelection: () => void;
+};
+
+export type DtourProps = {
+  /** Arrow IPC or Parquet ArrayBuffer. Ownership is transferred on load. */
+  data?: ArrayBuffer;
+  /** Tour keyframe views (p×2 column-major). Auto-generated if omitted. */
+  views?: Float32Array[];
+  /** Arrow IPC ArrayBuffer with per-view quality metrics (columns = metrics, rows = views). */
+  metrics?: ArrayBuffer;
+  /** Track configuration for radial bar charts. When omitted, all metrics are shown with defaults. */
+  metricTracks?: RadialTrackConfig[];
+  /** Global bar width override for radial charts ('full' or px). */
+  metricBarWidth?: 'full' | number;
+  /** Partial spec controlling component state. Omitted fields use defaults. */
+  spec?: DtourSpec;
+  /** Fires when internal state changes (debounced ~250ms). Full resolved spec. */
+  onSpecChange?: (spec: Required<DtourSpec>) => void;
+  /** Called on every status event from the renderer. */
+  onStatus?: (status: ScatterStatus) => void;
+  /** Hide the toolbar. Default false. */
+  hideToolbar?: boolean;
+  /** Called when the user requests loading new data via the toolbar file picker. */
+  onLoadData?: (data: ArrayBuffer, fileName: string) => void;
+  /** Fires when legend selection changes for a categorical color column. Reports selected label names or empty array when cleared. */
+  onSelectionChange?: (labels: string[]) => void;
+  /** Per-label color map. Values are hex strings or theme-aware {light, dark} objects. */
+  colorMap?: Record<string, string | { light: string; dark: string }>;
+  /** Element to portal Radix popups into (for Shadow DOM isolation). When omitted, portals render into document.body as usual. */
+  portalContainer?: HTMLElement;
+  /** Called when the viewer is ready with an API handle for programmatic control. */
+  onReady?: (api: DtourHandle) => void;
+};
+
+export const Dtour = ({
+  data,
+  views,
+  metrics,
+  metricTracks,
+  metricBarWidth,
+  spec,
+  onSpecChange,
+  onStatus,
+  hideToolbar = false,
+  onLoadData,
+  onSelectionChange,
+  colorMap,
+  portalContainer,
+  onReady,
+}: DtourProps) => {
+  // Each Dtour instance gets its own isolated jotai store.
+  // Eagerly apply initial spec values so there's no flash of defaults.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: store created once on mount
+  const store = useMemo(() => {
+    const s = createStore();
+    initStoreFromSpec(s, spec);
+    return s;
+  }, []);
+
+  return (
+    <PortalContainerContext.Provider value={portalContainer}>
+      <Provider store={store}>
+        <DtourInner
+          data={data}
+          views={views}
+          metrics={metrics}
+          metricTracks={metricTracks}
+          metricBarWidth={metricBarWidth}
+          spec={spec}
+          onSpecChange={onSpecChange}
+          onStatus={onStatus}
+          hideToolbar={hideToolbar}
+          onLoadData={onLoadData}
+          onSelectionChange={onSelectionChange}
+          colorMap={colorMap}
+          onReady={onReady}
+        />
+      </Provider>
+    </PortalContainerContext.Provider>
+  );
+};
+
+/** Inner component that lives inside the Provider so hooks bind to the store. */
+const DtourInner = ({
+  data,
+  views,
+  metrics,
+  metricTracks,
+  metricBarWidth,
+  spec,
+  onSpecChange,
+  onStatus,
+  hideToolbar,
+  onLoadData,
+  onSelectionChange,
+  colorMap,
+  onReady,
+}: {
+  data: ArrayBuffer | undefined;
+  views: Float32Array[] | undefined;
+  metrics: ArrayBuffer | undefined;
+  metricTracks: RadialTrackConfig[] | undefined;
+  metricBarWidth: 'full' | number | undefined;
+  spec: DtourSpec | undefined;
+  onSpecChange: ((spec: Required<DtourSpec>) => void) | undefined;
+  onStatus: ((status: ScatterStatus) => void) | undefined;
+  hideToolbar: boolean;
+  onLoadData: ((data: ArrayBuffer, fileName: string) => void) | undefined;
+  onSelectionChange: ((labels: string[]) => void) | undefined;
+  colorMap: Record<string, string | { light: string; dark: string }> | undefined;
+  onReady: ((api: DtourHandle) => void) | undefined;
+}) => {
+  useSpecSync(spec, onSpecChange);
+  useModeCycling();
+  useSystemTheme();
+
+  // Sync colorMap prop → atom
+  const setColorMap = useSetAtom(colorMapAtom);
+  useEffect(() => {
+    setColorMap(colorMap ?? null);
+  }, [colorMap, setColorMap]);
+
+  // Sync resolved theme → background color + CSS class
+  const resolvedTheme = useAtomValue(resolvedThemeAtom);
+  const setBackgroundColor = useSetAtom(backgroundColorAtom);
+  useEffect(() => {
+    setBackgroundColor(resolvedTheme === 'light' ? [1, 1, 1] : [0, 0, 0]);
+  }, [resolvedTheme, setBackgroundColor]);
+
+  // Forward legend selection changes to the parent as label name strings
+  const legendSelection = useAtomValue(legendSelectionAtom);
+  const pointColor = useAtomValue(pointColorAtom);
+  const metadata = useAtomValue(metadataAtom);
+
+  useEffect(() => {
+    if (!onSelectionChange) return;
+
+    if (typeof pointColor !== 'string' || !metadata) return;
+    if (!metadata.categoricalColumnNames.includes(pointColor)) return;
+
+    if (!legendSelection || legendSelection.size === 0) {
+      onSelectionChange([]);
+      return;
+    }
+
+    const allLabels = metadata.categoricalLabels[pointColor] ?? [];
+    const selectedLabels = Array.from(legendSelection)
+      .map((i) => allLabels[i])
+      .filter((l): l is string => l !== undefined);
+
+    onSelectionChange(selectedLabels.length > 0 ? selectedLabels : []);
+  }, [legendSelection, pointColor, metadata, onSelectionChange]);
+
+  // Track scatter instance for programmatic select API
+  const [scatterInstance, setScatterInstance] = useState<ScatterInstance | null>(null);
+  const onReadyRef = useRef(onReady);
+  onReadyRef.current = onReady;
+
+  useEffect(() => {
+    if (!scatterInstance || !metadata) return;
+
+    const handle: DtourHandle = {
+      select: (indicesOrMask, opts) => {
+        if (opts?.isBitPacked && indicesOrMask instanceof Uint32Array) {
+          scatterInstance.setSelectionMask(new Uint32Array(indicesOrMask));
+        } else {
+          const packed = bitPackIndices(indicesOrMask, metadata.rowCount);
+          scatterInstance.setSelectionMask(packed);
+        }
+      },
+      clearSelection: () => {
+        scatterInstance.clearSelection();
+      },
+    };
+
+    onReadyRef.current?.(handle);
+  }, [scatterInstance, metadata]);
+
+  const viewMode = useAtomValue(viewModeAtom);
+  const isGrand = viewMode === 'grand';
+  const legendVisible = useAtomValue(legendVisibleAtom);
+
+  // Sidebar width state — remembered across open/close cycles
+  const [sidebarWidth, setSidebarWidth] = useState(200);
+  const [dragging, setDragging] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  // Drag-to-resize handler
+  const onHandleMouseDown = useCallback(
+    (e: React.MouseEvent) => {
+      if (!legendVisible) return;
+      e.preventDefault();
+      setDragging(true);
+
+      const onMouseMove = (me: MouseEvent) => {
+        const container = containerRef.current;
+        if (!container) return;
+        const rect = container.getBoundingClientRect();
+        const maxWidth = rect.width * 0.4;
+        const newWidth = Math.min(maxWidth, Math.max(64, rect.right - me.clientX));
+        setSidebarWidth(newWidth);
+      };
+
+      const onMouseUp = () => {
+        setDragging(false);
+        window.removeEventListener('mousemove', onMouseMove);
+        window.removeEventListener('mouseup', onMouseUp);
+      };
+
+      window.addEventListener('mousemove', onMouseMove);
+      window.addEventListener('mouseup', onMouseUp);
+    },
+    [legendVisible],
+  );
+
+  const displayWidth = legendVisible ? sidebarWidth : 0;
+
+  return (
+    <div
+      ref={containerRef}
+      className={`relative w-full h-full overflow-hidden flex ${resolvedTheme === 'light' ? 'dtour-light' : ''}`}
+    >
+      {/* Canvas panel — grows to fill remaining space */}
+      <div className="relative flex-1 min-w-0">
+        {/* Toolbar — inside left panel so it shrinks with the legend */}
+        <div
+          className={`absolute inset-x-0 top-0 z-10 h-10 transition-[transform,opacity] duration-300 ease-out ${
+            isGrand ? '-translate-y-full' : 'translate-y-0'
+          } ${hideToolbar ? 'opacity-0 pointer-events-none' : 'opacity-100'}`}
+        >
+          <DtourToolbar onLoadData={onLoadData} />
+        </div>
+        <div className="absolute inset-0 overflow-hidden">
+          <DtourViewer
+            data={data}
+            views={views}
+            metrics={metrics}
+            metricTracks={metricTracks}
+            metricBarWidth={metricBarWidth}
+            onStatus={onStatus}
+            toolbarHeight={hideToolbar ? 0 : 40}
+            onScatterReady={setScatterInstance}
+          />
+        </div>
+      </div>
+      {/* Drag handle */}
+      <div
+        className={`w-px shrink-0 transition-colors ${
+          legendVisible
+            ? 'cursor-col-resize bg-dtour-surface hover:bg-dtour-text-muted active:bg-dtour-highlight'
+            : 'pointer-events-none'
+        }`}
+        onMouseDown={onHandleMouseDown}
+      />
+      {/* Legend sidebar */}
+      <div
+        className="shrink-0 overflow-hidden"
+        style={{
+          width: displayWidth,
+          transition: dragging ? 'none' : 'width 300ms cubic-bezier(.1,.1,0,1)',
+        }}
+      >
+        <div className="h-full" style={{ width: sidebarWidth }}>
+          <ColorLegend />
+        </div>
+      </div>
+    </div>
+  );
+};