feat: enhance ConstellationTimeline with organic layout and improved interactions

- Refactored layout calculations to support a constellation-like organic positioning of nodes.
- Updated `computeIndexToOffset` to return 2D positions for nodes, enhancing visual representation.
- Adjusted baseline positioning from 80% to 70% for better layout aesthetics.
- Improved `clampTransform` to allow for dynamic horizontal centering during zoom interactions.
- Enhanced `useTimelineInteractions` to utilize new layout configurations for better user experience.
- Updated rendering logic to reflect changes in node positioning and interaction handling.

Author: jpfigueredo

web/src/components/timeline/ConstellationTimeline.tsx

@@ -6,7 +6,7 @@ import { ControlsBar } from './molecules/ControlsBar';
 import { DetailPanel } from './molecules/DetailPanel';
 import { Tooltip } from './molecules/Tooltip';
 import type { Transform, LayoutPoint } from './types';
-import { createLayoutConfig, computeIndexToOffset } from './engine/layout';
+import { createLayoutConfig, computeIndexToOffset, type LayoutConfig } from './engine/layout';
 import { easeInOutQuad, clampTransform } from './engine/transform';
 import { renderTimeline } from './engine/renderer';
 import { useTimelineInteractions } from './hooks/useTimelineInteractions';
@@ -47,6 +47,7 @@ export const ConstellationTimeline: React.FC<{ height?: number; query?: string;
     const animate = (ts:number)=>{
       const p = Math.min(1, (ts - startTime)/duration);
       const v = startOffsetX + (desiredOffsetX - startOffsetX) * easeInOutQuad(p);
+      // Temporarily set offsetX for animation, but allow clampTransform to handle centering during zoom
       transformRef.current = { ...transformRef.current, offsetX: v };
       setTick(vv=>vv+1);
       if (p < 1) animRafRef.current = requestAnimationFrame(animate);
@@ -110,17 +111,20 @@ export const ConstellationTimeline: React.FC<{ height?: number; query?: string;
     // Update animation time for meteorite
     animationTimeRef.current = performance.now();
 
-    // Horizontal time axis (baseline at 80% = 20% do fundo), vertical branches to avoid collisions per same year
+    // Constellation layout: organic 2D positioning
     const layoutConfig = createLayoutConfig(dataset.nodes, canvas.clientWidth, height, branchSpacing);
-    const indexToOffset = computeIndexToOffset(dataset.nodes, layoutConfig);
+    const indexToPosition = computeIndexToOffset(dataset.nodes, layoutConfig); // Returns Map<number, {x, y}>
+
+    // Don't force center on render - only during zoom interactions
+    // This allows centerOnYear animation to work smoothly
 
     renderTimeline({
       ctx,
       canvasWidth: canvas.clientWidth,
       height,
       transform: transformRef.current,
       layoutConfig,
-      indexToOffset,
+      indexToPosition,
       nodes: dataset.nodes,
       edges: dataset.edges,
       query,
@@ -174,15 +178,18 @@ export const ConstellationTimeline: React.FC<{ height?: number; query?: string;
 
         // Recompute layout with new dimensions
         const layoutConfig = createLayoutConfig(dataset.nodes, canvas.clientWidth, height, branchSpacing);
-        const indexToOffset = computeIndexToOffset(dataset.nodes, layoutConfig);
+        const indexToPosition = computeIndexToOffset(dataset.nodes, layoutConfig);
 
-        // Re-clamp transform to new bounds (baseline always at 80% = 20% do fundo)
+        // Re-clamp transform to new bounds (baseline always at 70% = 30% do fundo)
+        // Force center horizontally on resize to maintain view
         transformRef.current = clampTransform(
           transformRef.current,
           canvas,
           height,
           dataset.nodes,
-          branchSpacing
+          branchSpacing,
+          layoutConfig,
+          true // Force center on resize
         );
 
         renderTimeline({
@@ -191,7 +198,7 @@ export const ConstellationTimeline: React.FC<{ height?: number; query?: string;
           height,
           transform: transformRef.current,
           layoutConfig,
-          indexToOffset,
+          indexToPosition: indexToPosition,
           nodes: dataset.nodes,
           edges: dataset.edges,
           query,
@@ -212,7 +219,17 @@ export const ConstellationTimeline: React.FC<{ height?: number; query?: string;
     };
   }, [height, query, mode, selectedIndex, showConstellations, branchSpacing]);
 
-  // Use interactions hook
+  // Compute layout config for interactions (needs canvas width, computed in render)
+  const [currentLayoutConfig, setCurrentLayoutConfig] = useState<LayoutConfig | null>(null);
+  
+  // Update layout config when dimensions change
+  useEffect(() => {
+    if (ref.current) {
+      const config = createLayoutConfig(dataset.nodes, ref.current.clientWidth, height, branchSpacing);
+      setCurrentLayoutConfig(config);
+    }
+  }, [height, branchSpacing]);
+
   useTimelineInteractions({
     canvasRef: ref,
     containerRef,
@@ -232,6 +249,7 @@ export const ConstellationTimeline: React.FC<{ height?: number; query?: string;
     setDeepLink,
     centerOnYear,
     hover,
+    layoutConfig: currentLayoutConfig || createLayoutConfig(dataset.nodes, 800, height, branchSpacing), // Fallback
   });
 
   return (
@@ -242,7 +260,7 @@ export const ConstellationTimeline: React.FC<{ height?: number; query?: string;
       tabIndex={0}
       aria-label="Constellation timeline canvas"
     >
-      <canvas ref={ref} style={{ width: '100%', height }} />
+      <canvas ref={ref} style={{ width: '100%', height, cursor: 'grab' }} />
       <ControlsBar
         onPrevYear={() => window.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowLeft' }))}
         onNextYear={() => window.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight' }))}

web/src/components/timeline/engine/layout.ts

@@ -19,8 +19,8 @@ export function createLayoutConfig(
   const years = nodes.map(n => yearOf(n.date)).filter(Boolean);
   const minYear = Math.min(...years);
   const maxYear = Math.max(...years);
-  // Baseline em 80% da altura = 20% do fundo acima das barras de controle
-  const baselineY = height * 0.8;
+  // Baseline em 70% da altura = 30% do fundo acima das barras de controle (mais alto)
+  const baselineY = height * 0.7;
   return { canvasWidth, height, baselineY, branchSpacing, minYear, maxYear };
 }
 
@@ -29,22 +29,89 @@ export function xScaleYear(year: number, config: LayoutConfig): number {
   return 40 + t * (config.canvasWidth - 80);
 }
 
-export function computeIndexToOffset(nodes: Node[], config: LayoutConfig): Map<number, number> {
+// Constellation-like layout: organic positioning instead of linear stacking
+export function computeIndexToOffset(nodes: Node[], config: LayoutConfig): Map<number, { x: number; y: number }> {
+  const baselineY = config.baselineY;
+  const indexToPos = new Map<number, { x: number; y: number }>();
+  
+  // Group nodes by year for temporal clustering
   const yearToIndices = new Map<number, number[]>();
   nodes.forEach((n, i) => {
     const y = yearOf(n.date);
     if (!yearToIndices.has(y)) yearToIndices.set(y, []);
     yearToIndices.get(y)!.push(i);
   });
 
-  const indexToOffset = new Map<number, number>();
-  yearToIndices.forEach((indices) => {
-    indices.sort((a, b) => a - b);
-    indices.forEach((idx, k) => {
-      const level = k + 1;
-      indexToOffset.set(idx, -level * config.branchSpacing);
-    });
+  // Create tag-based clusters for thematic grouping
+  const tagClusters = new Map<string, number[]>();
+  nodes.forEach((n, i) => {
+    const tags = n.tags || [];
+    if (tags.length === 0) {
+      // Untagged nodes go to a default cluster
+      const defaultTag = 'untagged';
+      if (!tagClusters.has(defaultTag)) tagClusters.set(defaultTag, []);
+      tagClusters.get(defaultTag)!.push(i);
+    } else {
+      // Add to all relevant tag clusters
+      tags.forEach(tag => {
+        if (!tagClusters.has(tag)) tagClusters.set(tag, []);
+        tagClusters.get(tag)!.push(i);
+      });
+    }
+  });
+
+  // Calculate constellation positions (organic, non-linear distribution)
+  yearToIndices.forEach((indices, year) => {
+    const baseX = xScaleYear(year, config);
+    
+    if (indices.length === 1) {
+      // Single node: position with slight horizontal variation for organic feel
+      const idx = indices[0];
+      const seed = idx * 137.508;
+      const organicX = Math.sin(seed) * config.branchSpacing * 0.2;
+      indexToPos.set(idx, {
+        x: baseX + organicX,
+        y: baselineY - config.branchSpacing * 1.2
+      });
+    } else {
+      // Multiple nodes: create organic constellation pattern
+      // Use spiral/Fibonacci-like distribution for natural clustering
+      indices.forEach((idx, k) => {
+        // Golden angle spiral for organic distribution
+        const goldenAngle = 2.399963229728653; // ~137.508° in radians
+        const angle = k * goldenAngle;
+        const spiralFactor = Math.sqrt(k + 1); // Spiral expansion
+        const radius = config.branchSpacing * (1.0 + spiralFactor * 0.8);
+        
+        // More horizontal spread for constellation feel (not just vertical stacking)
+        const offsetX = Math.cos(angle) * radius * 0.8; // Wider horizontal spread
+        const offsetY = -radius * 1.1; // Always upward but varied
+        
+        // Add organic variation based on node properties (tags, index)
+        const node = nodes[idx];
+        const tagSeed = (node.tags?.join('') || '').split('').reduce((acc, char) => acc + char.charCodeAt(0), idx);
+        const organicX = offsetX + Math.sin(tagSeed * 0.01) * radius * 0.25;
+        const organicY = offsetY + Math.cos(tagSeed * 0.015) * radius * 0.2;
+        
+        indexToPos.set(idx, {
+          x: baseX + organicX,
+          y: baselineY + organicY
+        });
+      });
+    }
+  });
+
+  return indexToPos;
+}
+
+// Legacy function for backward compatibility (returns vertical offset only)
+export function computeIndexToVerticalOffset(nodes: Node[], config: LayoutConfig): Map<number, number> {
+  const posMap = computeIndexToOffset(nodes, config);
+  const offsetMap = new Map<number, number>();
+  posMap.forEach((pos, idx) => {
+    // Extract just the Y offset from baseline
+    offsetMap.set(idx, pos.y - config.baselineY);
   });
-  return indexToOffset;
+  return offsetMap;
 }