@dtour/viewer 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtour/viewer",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "./dist/viewer.js",
   "exports": {
@@ -10,6 +10,11 @@
     },
     "./dist/viewer.css": "./dist/viewer.css"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flekschas/dtour",
+    "directory": "packages/viewer"
+  },
   "scripts": {
     "build": "vite build && tsc --emitDeclarationOnly --declaration --outDir dist",
     "dev": "vite build --watch"

package/src/Dtour.tsx

@@ -1,6 +1,6 @@
 import type { ScatterInstance, ScatterStatus } from '@dtour/scatter';
 import { bitPackIndices } from '@dtour/scatter';
-import { Provider, createStore, useAtomValue, useSetAtom } from 'jotai';
+import { Provider, createStore, useAtomValue, useSetAtom, useStore } from 'jotai';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { DtourViewer } from './DtourViewer.tsx';
 import { ColorLegend } from './components/ColorLegend.tsx';
@@ -13,14 +13,20 @@ import type { DtourSpec } from './spec.ts';
 import {
   backgroundColorAtom,
   colorMapAtom,
+  embeddedConfigAtom,
+  frameLoadingsAtom,
   legendSelectionAtom,
   legendVisibleAtom,
   metadataAtom,
   pointColorAtom,
   resolvedThemeAtom,
+  showTourDescriptionAtom,
+  tourDescriptionAtom,
+  tourFrameDescriptionAtom,
+  tourModeAtom,
   viewModeAtom,
 } from './state/atoms.ts';
-import { initStoreFromSpec, useSpecSync } from './state/spec-sync.ts';
+import { applySpecToStore, initStoreFromSpec, useSpecSync } from './state/spec-sync.ts';
 
 export type DtourHandle = {
   /** Select points by index array or bit-packed mask. */
@@ -53,6 +59,8 @@ export type DtourProps = {
   hideToolbar?: boolean;
   /** Called when the user requests loading new data via the toolbar file picker. */
   onLoadData?: (data: ArrayBuffer, fileName: string) => void;
+  /** Called when the user clicks the toolbar logo. */
+  onLogoClick?: () => 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. */
@@ -61,6 +69,8 @@ export type DtourProps = {
   portalContainer?: HTMLElement;
   /** Called when the viewer is ready with an API handle for programmatic control. */
   onReady?: (api: DtourHandle) => void;
+  /** Rendering backend. Default 'webgpu'. */
+  backend?: 'webgpu' | 'webgl';
 };
 
 export const Dtour = ({
@@ -74,10 +84,12 @@ export const Dtour = ({
   onStatus,
   hideToolbar = false,
   onLoadData,
+  onLogoClick,
   onSelectionChange,
   colorMap,
   portalContainer,
   onReady,
+  backend,
 }: DtourProps) => {
   // Each Dtour instance gets its own isolated jotai store.
   // Eagerly apply initial spec values so there's no flash of defaults.
@@ -102,9 +114,11 @@ export const Dtour = ({
           onStatus={onStatus}
           hideToolbar={hideToolbar}
           onLoadData={onLoadData}
+          onLogoClick={onLogoClick}
           onSelectionChange={onSelectionChange}
           colorMap={colorMap}
           onReady={onReady}
+          backend={backend}
         />
       </Provider>
     </PortalContainerContext.Provider>
@@ -123,9 +137,11 @@ const DtourInner = ({
   onStatus,
   hideToolbar,
   onLoadData,
+  onLogoClick,
   onSelectionChange,
   colorMap,
   onReady,
+  backend,
 }: {
   data: ArrayBuffer | undefined;
   views: Float32Array[] | undefined;
@@ -137,24 +153,64 @@ const DtourInner = ({
   onStatus: ((status: ScatterStatus) => void) | undefined;
   hideToolbar: boolean;
   onLoadData: ((data: ArrayBuffer, fileName: string) => void) | undefined;
+  onLogoClick: (() => void) | undefined;
   onSelectionChange: ((labels: string[]) => void) | undefined;
   colorMap: Record<string, string | { light: string; dark: string }> | undefined;
   onReady: ((api: DtourHandle) => void) | undefined;
+  backend: 'webgpu' | 'webgl' | undefined;
 }) => {
   useSpecSync(spec, onSpecChange);
   useModeCycling();
   useSystemTheme();
 
-  // Sync colorMap prop → atom
+  // ── Apply embedded config from Parquet metadata ──────────────────────
+  const embeddedConfig = useAtomValue(embeddedConfigAtom);
+  const store = useStore();
+  const embeddedAppliedRef = useRef(false);
+
+  // Reset when data changes so the next file's embedded config can apply
+  // biome-ignore lint/correctness/useExhaustiveDependencies: data triggers reset
+  useEffect(() => {
+    embeddedAppliedRef.current = false;
+  }, [data]);
+
+  // Apply embedded spec fields that are NOT overridden by the prop spec
+  useEffect(() => {
+    if (!embeddedConfig || embeddedAppliedRef.current) return;
+    embeddedAppliedRef.current = true;
+
+    const fieldsToApply: DtourSpec = {};
+    for (const [key, value] of Object.entries(embeddedConfig.spec)) {
+      if (spec?.[key as keyof DtourSpec] === undefined) {
+        (fieldsToApply as Record<string, unknown>)[key] = value;
+      }
+    }
+    applySpecToStore(store, fieldsToApply);
+  }, [embeddedConfig, spec, store]);
+
+  // Sync colorMap prop → atom (embedded colorMap used as fallback)
   const setColorMap = useSetAtom(colorMapAtom);
   useEffect(() => {
-    setColorMap(colorMap ?? null);
-  }, [colorMap, setColorMap]);
+    setColorMap(colorMap ?? embeddedConfig?.colorMap ?? null);
+  }, [colorMap, embeddedConfig, setColorMap]);
+
+  // Sync tour frame loadings, tour mode, and description strings from embedded config
+  const setFrameLoadings = useSetAtom(frameLoadingsAtom);
+  const setTourMode = useSetAtom(tourModeAtom);
+  const setTourDescription = useSetAtom(tourDescriptionAtom);
+  const setTourFrameDescription = useSetAtom(tourFrameDescriptionAtom);
+  useEffect(() => {
+    setFrameLoadings(embeddedConfig?.tour?.frameLoadings ?? null);
+    setTourMode(embeddedConfig?.tour?.tourMode ?? null);
+    setTourDescription(embeddedConfig?.tour?.tourDescription ?? null);
+    setTourFrameDescription(embeddedConfig?.tour?.tourFrameDescription ?? null);
+  }, [embeddedConfig, setFrameLoadings, setTourMode, setTourDescription, setTourFrameDescription]);
 
   // Sync resolved theme → background color + CSS class
   const resolvedTheme = useAtomValue(resolvedThemeAtom);
   const setBackgroundColor = useSetAtom(backgroundColorAtom);
   useEffect(() => {
+    // sRGB values matching --color-dtour-bg: dark=#000000, light=#ffffff
     setBackgroundColor(resolvedTheme === 'light' ? [1, 1, 1] : [0, 0, 0]);
   }, [resolvedTheme, setBackgroundColor]);
 
@@ -211,6 +267,13 @@ const DtourInner = ({
   const isGrand = viewMode === 'grand';
   const legendVisible = useAtomValue(legendVisibleAtom);
 
+  // Tour description sub-bar
+  const showTourDescription = useAtomValue(showTourDescriptionAtom);
+  const tourDescription = useAtomValue(tourDescriptionAtom);
+  const descriptionVisible =
+    showTourDescription && viewMode === 'guided' && tourDescription !== null;
+  const effectiveToolbarHeight = hideToolbar ? 0 : descriptionVisible ? 72 : 40;
+
   // Sidebar width state — remembered across open/close cycles
   const [sidebarWidth, setSidebarWidth] = useState(200);
   const [dragging, setDragging] = useState(false);
@@ -253,13 +316,22 @@ const DtourInner = ({
     >
       {/* 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 */}
+        {/* Toolbar + optional description sub-bar */}
         <div
-          className={`absolute inset-x-0 top-0 z-10 h-10 transition-[transform,opacity] duration-300 ease-out ${
+          className={`absolute inset-x-0 top-0 z-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 className="h-10">
+            <DtourToolbar onLoadData={onLoadData} onLogoClick={onLogoClick} />
+          </div>
+          {descriptionVisible && (
+            <div className="h-8 flex items-center justify-center border-b border-dtour-surface bg-dtour-bg px-3">
+              <span className="text-[11px] text-dtour-text-muted italic">
+                <strong>Tour:</strong> {tourDescription}
+              </span>
+            </div>
+          )}
         </div>
         <div className="absolute inset-0 overflow-hidden">
           <DtourViewer
@@ -269,8 +341,9 @@ const DtourInner = ({
             metricTracks={metricTracks}
             metricBarWidth={metricBarWidth}
             onStatus={onStatus}
-            toolbarHeight={hideToolbar ? 0 : 40}
+            toolbarHeight={effectiveToolbarHeight}
             onScatterReady={setScatterInstance}
+            backend={backend}
           />
         </div>
       </div>