@visualli/core 0.1.1

package/src/utils/navigation.ts

@@ -0,0 +1,161 @@
+import type { VisualliDocument, VisualliLayer, FlatNode, MindMapConnection } from '../types/index.js';
+import { ZOOM_MAX, ZOOM_NAV_OUT_THRESHOLD } from '../constants/performanceConstants.js';
+
+// ── Connection helpers ────────────────────────────────────────────────────────
+
+/**
+ * Returns all top-level connections that originate from the given layer.
+ * A "top-level connection" links two nodes that both live in `layerId`.
+ */
+export function getConnectionsForLayer(
+  doc: VisualliDocument,
+  layerId: string,
+): MindMapConnection[] {
+  const layer = doc.layers.get(layerId);
+  if (!layer) return [];
+  // Convert schema LayerConnection to simplified mindmap MindMapConnection
+  return layer.connections.map(c => ({
+    from: c.from,
+    to: c.to,
+    level: layer.level,
+    label: c.data?.label,
+  } satisfies MindMapConnection));
+}
+
+/**
+ * Given a node in the current layer, returns the child layer (if any) that the
+ * node "owns" — i.e. the node is the entry-point into that child layer.
+ */
+export function getChildLayerForNode(
+  doc: VisualliDocument,
+  nodeId: string,
+  currentLayerId: string,
+): VisualliLayer | null {
+  // Walk all layers looking for one whose `parentNodeId` matches
+  for (const [, layer] of doc.layers) {
+    if (layer.parentLayerId === currentLayerId && layer.parentNodeId === nodeId) {
+      return layer;
+    }
+  }
+  return null;
+}
+
+/**
+ * Returns the layer to navigate INTO when double-clicking `nodeId` in `currentLayerId`.
+ * Returns null when the node has no child layer.
+ */
+export function getLayerForNavigation(
+  doc: VisualliDocument,
+  nodeId: string,
+  currentLayerId: string,
+): VisualliLayer | null {
+  return getChildLayerForNode(doc, nodeId, currentLayerId);
+}
+
+// ── Viewport fitting math ─────────────────────────────────────────────────────
+
+export interface FitResult {
+  centerX: number;
+  centerY: number;
+  zoomLevel: number;
+}
+
+/**
+ * Calculates the zoom level needed to fit all `nodes` inside a canvas of
+ * `(canvasWidth, canvasHeight)`.
+ *
+ * @param paddingFraction - Fractional padding on each side (0.15 = 15%).
+ *   Pixel-padding variant still available when a value >=1 is passed.
+ */
+export function calculateFitZoom(
+  nodes: FlatNode[],
+  canvasWidth: number,
+  canvasHeight: number,
+  padding = 0.15,
+): number {
+  if (nodes.length === 0) return 1;
+
+  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+  for (const n of nodes) {
+    // Use the actual node boundaries (center +/- half-width/height)
+    minX = Math.min(minX, n.x - n.width / 2);
+    minY = Math.min(minY, n.y - n.height / 2);
+    maxX = Math.max(maxX, n.x + n.width / 2);
+    maxY = Math.max(maxY, n.y + n.height / 2);
+  }
+
+  const rawW = maxX - minX;
+  const rawH = maxY - minY;
+
+  // Minimum spread — single isolated node should appear comfortably
+  // Matches visualli.ai's spread logic for single nodes
+  const spreadW = nodes.length === 1 ? Math.max(rawW, 600) : rawW;
+  const spreadH = nodes.length === 1 ? Math.max(rawH, 400) : rawH;
+
+  const zoomX = (canvasWidth * (1 - padding)) / spreadW;
+  const zoomY = (canvasHeight * (1 - padding)) / spreadH;
+
+  const z = Math.min(zoomX, zoomY);
+
+  // Scale back 20% so nodes aren't edge-to-edge, clamp to at least
+  // ZOOM_NAV_OUT_THRESHOLD so arriving at the layer never immediately
+  // re-triggers the zoom-out transition.
+  return Math.max(z * 0.80, ZOOM_NAV_OUT_THRESHOLD);
+}
+
+/**
+ * Calculates the world-space center point that puts all `nodes` in the middle
+ * of the viewport. Matches the visualli.ai `calculateFitCenter` approach:
+ * uses bounding-box midpoint rather than centroid so the layout is always
+ * geometrically centred.
+ */
+export function calculateFitCenter(nodes: FlatNode[]): { x: number; y: number } {
+  if (nodes.length === 0) return { x: 0, y: 0 };
+  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+  for (const n of nodes) {
+    minX = Math.min(minX, n.x - n.width / 2);
+    minY = Math.min(minY, n.y - n.height / 2);
+    maxX = Math.max(maxX, n.x + n.width / 2);
+    maxY = Math.max(maxY, n.y + n.height / 2);
+  }
+  return { x: (minX + maxX) / 2, y: (minY + maxY) / 2 };
+}
+
+// ── Container helpers ────────────────────────────────────────────────────────
+
+// Inline the container shape here to avoid a circular import with KonvaContainerLayer.
+export interface ContainerGroupInfo {
+  id: string;
+  label?: string;
+  nodeIds: string[];
+  level: number;
+}
+
+/**
+ * Returns the container groups for the given layer, normalising both the
+ * nested-data format `{data:{label,formation}}` and the flat format `{label}`.
+ */
+export function getContainersForLayer(
+  doc: VisualliDocument,
+  layerId: string,
+): ContainerGroupInfo[] {
+  const layer = doc.layers.get(layerId);
+  if (!layer) return [];
+  return layer.containers.map(c => {
+    // Schema Container has nested data.label structure
+    const label = c.data?.label ?? c.id;
+    return { id: c.id, label, nodeIds: c.nodes, level: layer.level };
+  });
+}
+
+/** Convenience: returns both center and zoom for a single `fitView` call. */
+export function calculateFitView(
+  nodes: FlatNode[],
+  canvasWidth: number,
+  canvasHeight: number,
+): FitResult {
+  const center = calculateFitCenter(nodes);
+  const zoom   = calculateFitZoom(nodes, canvasWidth, canvasHeight);
+  return { centerX: center.x, centerY: center.y, zoomLevel: zoom };
+}
+

package/src/viewport/index.ts

@@ -0,0 +1 @@
+export * from './viewportUtils.js';

package/src/viewport/viewportUtils.ts

@@ -0,0 +1,195 @@
+// ─── Viewport Utilities ───────────────────────────────────────────────────────
+//
+// Pure functions for viewport bounds calculation, coordinate transforms,
+// pan/zoom operations, and node visibility queries.
+
+import type { ViewportState } from '../types/mindmap.js';
+import {
+  VIEWPORT_MARGIN,
+  DEFAULT_CANVAS_WIDTH,
+  DEFAULT_CANVAS_HEIGHT,
+  ZOOM_MIN,
+  ZOOM_MAX,
+} from '../constants/performanceConstants.js';
+
+// ── Viewport Bounds ───────────────────────────────────────────────────────────
+
+export interface WorldBounds {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+}
+
+/**
+ * Calculate the visible world-space bounding box including a margin buffer.
+ */
+export function calculateViewportBounds(
+  viewport: ViewportState,
+  canvasWidth  = DEFAULT_CANVAS_WIDTH,
+  canvasHeight = DEFAULT_CANVAS_HEIGHT,
+): WorldBounds {
+  const worldW = canvasWidth  / viewport.zoomLevel;
+  const worldH = canvasHeight / viewport.zoomLevel;
+  const mx = worldW * VIEWPORT_MARGIN;
+  const my = worldH * VIEWPORT_MARGIN;
+  return {
+    minX: viewport.centerX - worldW / 2 - mx,
+    minY: viewport.centerY - worldH / 2 - my,
+    maxX: viewport.centerX + worldW / 2 + mx,
+    maxY: viewport.centerY + worldH / 2 + my,
+  };
+}
+
+/**
+ * Return a new ViewportState with `visibleBounds` recalculated.
+ */
+export function recalculateViewportBounds(
+  viewport: ViewportState,
+  canvasWidth  = DEFAULT_CANVAS_WIDTH,
+  canvasHeight = DEFAULT_CANVAS_HEIGHT,
+): ViewportState {
+  return {
+    ...viewport,
+    visibleBounds: calculateViewportBounds(viewport, canvasWidth, canvasHeight),
+  };
+}
+
+// ── Coordinate Transforms ─────────────────────────────────────────────────────
+
+/**
+ * Convert world-space coordinates to screen-space pixel coordinates.
+ */
+export function worldToScreen(
+  worldX: number,
+  worldY: number,
+  viewport: ViewportState,
+  canvasWidth  = DEFAULT_CANVAS_WIDTH,
+  canvasHeight = DEFAULT_CANVAS_HEIGHT,
+): { x: number; y: number } {
+  return {
+    x: (worldX - viewport.centerX) * viewport.zoomLevel + canvasWidth  / 2,
+    y: (worldY - viewport.centerY) * viewport.zoomLevel + canvasHeight / 2,
+  };
+}
+
+/**
+ * Convert screen-space pixel coordinates to world-space coordinates.
+ */
+export function screenToWorld(
+  screenX: number,
+  screenY: number,
+  viewport: ViewportState,
+  canvasWidth  = DEFAULT_CANVAS_WIDTH,
+  canvasHeight = DEFAULT_CANVAS_HEIGHT,
+): { x: number; y: number } {
+  return {
+    x: (screenX - canvasWidth  / 2) / viewport.zoomLevel + viewport.centerX,
+    y: (screenY - canvasHeight / 2) / viewport.zoomLevel + viewport.centerY,
+  };
+}
+
+// ── Pan / Zoom ────────────────────────────────────────────────────────────────
+
+/** Clamp zoom to [ZOOM_MIN, ZOOM_MAX]. */
+export function clampZoom(zoom: number): number {
+  return Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, zoom));
+}
+
+/**
+ * Pan the viewport by a screen-space delta (positive = right/down).
+ */
+export function panViewport(
+  deltaX: number,
+  deltaY: number,
+  viewport: ViewportState,
+): ViewportState {
+  return {
+    ...viewport,
+    centerX: viewport.centerX - deltaX / viewport.zoomLevel,
+    centerY: viewport.centerY - deltaY / viewport.zoomLevel,
+  };
+}
+
+/** Teleport the viewport centre to the given world coordinates. */
+export function setViewportCenter(
+  x: number,
+  y: number,
+  viewport: ViewportState,
+): ViewportState {
+  return { ...viewport, centerX: x, centerY: y };
+}
+
+/**
+ * Zoom the viewport by a multiplicative delta, optionally around a pivot point.
+ *
+ * @param delta   - Multiplier delta, e.g. 0.1 for +10% zoom
+ * @param pivotX  - Optional screen-space X pivot
+ * @param pivotY  - Optional screen-space Y pivot
+ */
+export function zoomViewport(
+  delta: number,
+  viewport: ViewportState,
+  pivotX?: number,
+  pivotY?: number,
+  canvasWidth  = DEFAULT_CANVAS_WIDTH,
+  canvasHeight = DEFAULT_CANVAS_HEIGHT,
+): ViewportState {
+  const newZoom = clampZoom(viewport.zoomLevel * (1 + delta));
+
+  let cx = viewport.centerX;
+  let cy = viewport.centerY;
+
+  if (pivotX !== undefined && pivotY !== undefined) {
+    const worldPivot = screenToWorld(pivotX, pivotY, viewport, canvasWidth, canvasHeight);
+    cx = worldPivot.x - (pivotX - canvasWidth  / 2) / newZoom;
+    cy = worldPivot.y - (pivotY - canvasHeight / 2) / newZoom;
+  }
+
+  return { ...viewport, centerX: cx, centerY: cy, zoomLevel: newZoom };
+}
+
+/**
+ * Create a viewport centred on a node (world coordinates) at the given zoom level.
+ */
+export function focusOnNode(
+  nodeX: number,
+  nodeY: number,
+  zoom: number,
+): ViewportState {
+  const clamped = clampZoom(zoom);
+  return {
+    centerX:  nodeX,
+    centerY:  nodeY,
+    zoomLevel: clamped,
+    rotation: 0,
+    visibleBounds: calculateViewportBounds(
+      { centerX: nodeX, centerY: nodeY, zoomLevel: clamped, rotation: 0, visibleBounds: { minX: 0, minY: 0, maxX: 0, maxY: 0 } },
+    ),
+  };
+}
+
+// ── Visibility ────────────────────────────────────────────────────────────────
+
+/**
+ * Test whether a world-space AABB intersects the viewport's visible bounds.
+ */
+export function isNodeInViewport(
+  nodeX: number,
+  nodeY: number,
+  nodeWidth: number,
+  nodeHeight: number,
+  viewport: ViewportState,
+  canvasWidth  = DEFAULT_CANVAS_WIDTH,
+  canvasHeight = DEFAULT_CANVAS_HEIGHT,
+): boolean {
+  const bounds = calculateViewportBounds(viewport, canvasWidth, canvasHeight);
+  const hw = nodeWidth  / 2;
+  const hh = nodeHeight / 2;
+  return !(
+    nodeX + hw < bounds.minX ||
+    nodeX - hw > bounds.maxX ||
+    nodeY + hh < bounds.minY ||
+    nodeY - hh > bounds.maxY
+  );
+}