@stephen-netu/design-system 0.1.0 → 0.2.1

package/src/n0-node-graph/validate.ts

@@ -1,371 +0,0 @@
-// N0 Node Graph — Validation
-// Pure TypeScript — no side effects, no mutations
-
-import type {
-  GraphSchema,
-  NodeInstance,
-  EdgeDefinition,
-  PortDefinition,
-  NodeDefinition,
-  ValidationError,
-  ValidationResult,
-} from './types';
-
-// Helper: Get a node definition by kind
-function getNodeDefinition(
-  nodeDefinitions: NodeDefinition[],
-  kind: string
-): NodeDefinition | undefined {
-  return nodeDefinitions.find((def) => def.kind === kind);
-}
-
-// Helper: Get a node instance by id
-function getNodeInstance(
-  nodes: NodeInstance[],
-  id: string
-): NodeInstance | undefined {
-  return nodes.find((node) => node.id === id);
-}
-
-// Helper: Get a port definition from a node definition
-function getPortDefinition(
-  nodeDefinition: NodeDefinition,
-  portId: string
-): PortDefinition | undefined {
-  return nodeDefinition.ports.find((port) => port.id === portId);
-}
-
-// Helper: Count connections to a specific port
-function countConnectionsToPort(
-  edges: EdgeDefinition[],
-  nodeId: string,
-  portId: string,
-  direction: 'source' | 'target'
-): number {
-  return edges.filter((edge) => {
-    if (direction === 'source') {
-      return edge.sourceNodeId === nodeId && edge.sourcePortId === portId;
-    }
-    return edge.targetNodeId === nodeId && edge.targetPortId === portId;
-  }).length;
-}
-
-// Helper: Check if an edge is a duplicate
-function isDuplicateEdge(
-  edges: EdgeDefinition[],
-  edge: EdgeDefinition
-): boolean {
-  return edges.some((existing) =>
-    existing.id !== edge.id &&
-    existing.sourceNodeId === edge.sourceNodeId &&
-    existing.sourcePortId === edge.sourcePortId &&
-    existing.targetNodeId === edge.targetNodeId &&
-    existing.targetPortId === edge.targetPortId
-  );
-}
-
-// Validation Rule 1: NodeInstance.kind must reference a registered NodeDefinition.kind
-function validateNodeKindReferences(
-  schema: GraphSchema
-): ValidationError[] {
-  const errors: ValidationError[] = [];
-  
-  for (const node of schema.nodes) {
-    const definition = getNodeDefinition(schema.nodeDefinitions, node.kind);
-    if (!definition) {
-      errors.push({
-        code: 'INVALID_NODE_KIND',
-        message: `Node instance "${node.id}" references undefined kind "${node.kind}"`,
-        nodeId: node.id,
-      });
-    }
-  }
-  
-  return errors;
-}
-
-// Validation Rule 2: Every edge must connect existing nodes and existing ports
-function validateEdgeConnections(
-  schema: GraphSchema
-): ValidationError[] {
-  const errors: ValidationError[] = [];
-  
-  for (const edge of schema.edges) {
-    // Check source node exists
-    const sourceNode = getNodeInstance(schema.nodes, edge.sourceNodeId);
-    if (!sourceNode) {
-      errors.push({
-        code: 'INVALID_SOURCE_NODE',
-        message: `Edge "${edge.id}" references non-existent source node "${edge.sourceNodeId}"`,
-        edgeId: edge.id,
-      });
-      continue;
-    }
-    
-    // Check target node exists
-    const targetNode = getNodeInstance(schema.nodes, edge.targetNodeId);
-    if (!targetNode) {
-      errors.push({
-        code: 'INVALID_TARGET_NODE',
-        message: `Edge "${edge.id}" references non-existent target node "${edge.targetNodeId}"`,
-        edgeId: edge.id,
-      });
-      continue;
-    }
-    
-    // Get node definitions
-    const sourceDef = getNodeDefinition(schema.nodeDefinitions, sourceNode.kind);
-    const targetDef = getNodeDefinition(schema.nodeDefinitions, targetNode.kind);
-    
-    if (!sourceDef) {
-      errors.push({
-        code: 'INVALID_SOURCE_NODE_KIND',
-        message: `Source node "${sourceNode.id}" has no registered definition`,
-        edgeId: edge.id,
-        nodeId: sourceNode.id,
-      });
-      continue;
-    }
-    
-    if (!targetDef) {
-      errors.push({
-        code: 'INVALID_TARGET_NODE_KIND',
-        message: `Target node "${targetNode.id}" has no registered definition`,
-        edgeId: edge.id,
-        nodeId: targetNode.id,
-      });
-      continue;
-    }
-    
-    // Check source port exists
-    const sourcePort = getPortDefinition(sourceDef, edge.sourcePortId);
-    if (!sourcePort) {
-      errors.push({
-        code: 'INVALID_SOURCE_PORT',
-        message: `Edge "${edge.id}" references non-existent source port "${edge.sourcePortId}" on node "${sourceNode.id}"`,
-        edgeId: edge.id,
-        portId: edge.sourcePortId,
-      });
-    }
-    
-    // Check target port exists
-    const targetPort = getPortDefinition(targetDef, edge.targetPortId);
-    if (!targetPort) {
-      errors.push({
-        code: 'INVALID_TARGET_PORT',
-        message: `Edge "${edge.id}" references non-existent target port "${edge.targetPortId}" on node "${targetNode.id}"`,
-        edgeId: edge.id,
-        portId: edge.targetPortId,
-      });
-    }
-  }
-  
-  return errors;
-}
-
-// Validation Rule 3: Port direction — edges go from output port to input port only
-function validatePortDirection(
-  schema: GraphSchema
-): ValidationError[] {
-  const errors: ValidationError[] = [];
-  
-  for (const edge of schema.edges) {
-    const sourceNode = getNodeInstance(schema.nodes, edge.sourceNodeId);
-    const targetNode = getNodeInstance(schema.nodes, edge.targetNodeId);
-    
-    if (!sourceNode || !targetNode) continue;
-    
-    const sourceDef = getNodeDefinition(schema.nodeDefinitions, sourceNode.kind);
-    const targetDef = getNodeDefinition(schema.nodeDefinitions, targetNode.kind);
-    
-    if (!sourceDef || !targetDef) continue;
-    
-    const sourcePort = getPortDefinition(sourceDef, edge.sourcePortId);
-    const targetPort = getPortDefinition(targetDef, edge.targetPortId);
-    
-    if (sourcePort && targetPort) {
-      if (sourcePort.direction !== 'output') {
-        errors.push({
-          code: 'INVALID_PORT_DIRECTION',
-          message: `Edge "${edge.id}" must start from an output port, but port "${edge.sourcePortId}" on node "${sourceNode.id}" is "${sourcePort.direction}"`,
-          edgeId: edge.id,
-          portId: edge.sourcePortId,
-        });
-      }
-      
-      if (targetPort.direction !== 'input') {
-        errors.push({
-          code: 'INVALID_PORT_DIRECTION',
-          message: `Edge "${edge.id}" must end at an input port, but port "${edge.targetPortId}" on node "${targetNode.id}" is "${targetPort.direction}"`,
-          edgeId: edge.id,
-          portId: edge.targetPortId,
-        });
-      }
-    }
-  }
-  
-  return errors;
-}
-
-// Validation Rule 4: Port type compatibility — exact match required
-function validateTypeCompatibility(
-  schema: GraphSchema
-): ValidationError[] {
-  const errors: ValidationError[] = [];
-  
-  for (const edge of schema.edges) {
-    const sourceNode = getNodeInstance(schema.nodes, edge.sourceNodeId);
-    const targetNode = getNodeInstance(schema.nodes, edge.targetNodeId);
-    
-    if (!sourceNode || !targetNode) continue;
-    
-    const sourceDef = getNodeDefinition(schema.nodeDefinitions, sourceNode.kind);
-    const targetDef = getNodeDefinition(schema.nodeDefinitions, targetNode.kind);
-    
-    if (!sourceDef || !targetDef) continue;
-    
-    const sourcePort = getPortDefinition(sourceDef, edge.sourcePortId);
-    const targetPort = getPortDefinition(targetDef, edge.targetPortId);
-    
-    if (sourcePort && targetPort && sourcePort.type !== targetPort.type) {
-      errors.push({
-        code: 'TYPE_MISMATCH',
-        message: `Edge "${edge.id}" connects incompatible types: source port "${edge.sourcePortId}" has type "${sourcePort.type}" but target port "${edge.targetPortId}" has type "${targetPort.type}"`,
-        edgeId: edge.id,
-      });
-    }
-  }
-  
-  return errors;
-}
-
-// Validation Rule 5: Connection limits — port.maxConnections not exceeded
-function validateConnectionLimits(
-  schema: GraphSchema
-): ValidationError[] {
-  const errors: ValidationError[] = [];
-  
-  for (const node of schema.nodes) {
-    const definition = getNodeDefinition(schema.nodeDefinitions, node.kind);
-    if (!definition) continue;
-    
-    for (const port of definition.ports) {
-      const connectionCount = countConnectionsToPort(
-        schema.edges,
-        node.id,
-        port.id,
-        port.direction === 'output' ? 'source' : 'target'
-      );
-      
-      if (connectionCount > port.maxConnections) {
-        errors.push({
-          code: 'MAX_CONNECTIONS_EXCEEDED',
-          message: `Port "${port.id}" on node "${node.id}" has ${connectionCount} connections but maximum allowed is ${port.maxConnections}`,
-          nodeId: node.id,
-          portId: port.id,
-        });
-      }
-    }
-  }
-  
-  return errors;
-}
-
-// Validation Rule 6: Required ports — all required:true ports must have at least one connection
-function validateRequiredPorts(
-  schema: GraphSchema
-): ValidationError[] {
-  const errors: ValidationError[] = [];
-  
-  for (const node of schema.nodes) {
-    const definition = getNodeDefinition(schema.nodeDefinitions, node.kind);
-    if (!definition) continue;
-    
-    for (const port of definition.ports) {
-      if (!port.required) continue;
-      
-      const connectionCount = countConnectionsToPort(
-        schema.edges,
-        node.id,
-        port.id,
-        port.direction === 'output' ? 'source' : 'target'
-      );
-      
-      if (connectionCount === 0) {
-        errors.push({
-          code: 'REQUIRED_PORT_UNCONNECTED',
-          message: `Required port "${port.id}" on node "${node.id}" has no connections`,
-          nodeId: node.id,
-          portId: port.id,
-        });
-      }
-    }
-  }
-  
-  return errors;
-}
-
-// Validation Rule 7: No self-loops (edge source === edge target on same node)
-function validateNoSelfLoops(
-  schema: GraphSchema
-): ValidationError[] {
-  const errors: ValidationError[] = [];
-  
-  for (const edge of schema.edges) {
-    if (edge.sourceNodeId === edge.targetNodeId) {
-      errors.push({
-        code: 'SELF_LOOP',
-        message: `Edge "${edge.id}" creates a self-loop on node "${edge.sourceNodeId}"`,
-        edgeId: edge.id,
-      });
-    }
-  }
-  
-  return errors;
-}
-
-// Validation Rule 8: No duplicate edges (same source port → same target port)
-function validateNoDuplicateEdges(
-  schema: GraphSchema
-): ValidationError[] {
-  const errors: ValidationError[] = [];
-  
-  for (const edge of schema.edges) {
-    if (isDuplicateEdge(schema.edges, edge)) {
-      errors.push({
-        code: 'DUPLICATE_EDGE',
-        message: `Edge "${edge.id}" is a duplicate: same source "${edge.sourceNodeId}:${edge.sourcePortId}" to target "${edge.targetNodeId}:${edge.targetPortId}"`,
-        edgeId: edge.id,
-      });
-    }
-  }
-  
-  return errors;
-}
-
-/**
- * Validates a graph schema against all 8 validation rules.
- * 
- * Pure function — no side effects, no mutation of input.
- * 
- * @param schema - The graph schema to validate
- * @returns ValidationResult with valid flag and array of errors
- */
-export function validateGraph(schema: GraphSchema): ValidationResult {
-  // Collect all errors from all validation rules
-  const allErrors: ValidationError[] = [
-    ...validateNodeKindReferences(schema),
-    ...validateEdgeConnections(schema),
-    ...validatePortDirection(schema),
-    ...validateTypeCompatibility(schema),
-    ...validateConnectionLimits(schema),
-    ...validateRequiredPorts(schema),
-    ...validateNoSelfLoops(schema),
-    ...validateNoDuplicateEdges(schema),
-  ];
-  
-  return {
-    valid: allErrors.length === 0,
-    errors: allErrors,
-  };
-}

package/src/n1-flow-canvas/graph-state.svelte.ts

@@ -1,95 +0,0 @@
-// N1 GraphState — Svelte 5 runes, Spring-animated node positions
-// S-02: positions lerped deterministically via rAF loop (no Math.random)
-// S-05: animation loop bounded by convergence threshold
-
-import type { NodeLayout, LayoutResult, GraphStateApi } from './types.js';
-
-const LERP_FACTOR   = 0.12;   // per frame (bounded, S-05)
-const SETTLE_THRESH = 0.5;    // pixels — stop animating below this delta
-const MAX_FRAMES    = 240;    // ~4s at 60fps hard cap (S-05 killability)
-
-export class GraphState implements GraphStateApi {
-  positions = $state<Map<string, NodeLayout>>(new Map());
-  bfsOrder  = $state<ReadonlyArray<string>>([]);
-
-  // Focus semantics
-  focusCenterId  = $state<string | null>(null);
-  layoutRootId   = $state<string | null>(null);
-
-  private _targets  = new Map<string, NodeLayout>();
-  private _rafId: number | null = null;
-  private _frameCount = 0;
-
-  // Callback invoked by FlowCanvas when layoutRootId changes
-  onLayoutRootChange: ((nodeId: string) => void) | null = null;
-
-  applyLayout(result: LayoutResult): void {
-    this._targets = new Map(result.positions);
-    this.bfsOrder = result.bfsOrder;
-    this._frameCount = 0;
-    this._startAnimation();
-  }
-
-  setFocusCenter(nodeId: string): void {
-    // Re-centers Poincaré disk — does NOT trigger re-layout
-    this.focusCenterId = nodeId;
-  }
-
-  setLayoutRoot(nodeId: string): void {
-    this.layoutRootId = nodeId;
-    this.onLayoutRootChange?.(nodeId);
-  }
-
-  // ── Animation ──────────────────────────────────────────────────────────────
-
-  private _startAnimation(): void {
-    if (this._rafId !== null) cancelAnimationFrame(this._rafId);
-    this._tick();
-  }
-
-  private _tick = (): void => {
-    if (this._frameCount >= MAX_FRAMES) {
-      // Force-snap to targets on hard cap (S-05)
-      this.positions = new Map(this._targets);
-      this._rafId = null;
-      return;
-    }
-
-    let maxDelta = 0;
-    const next = new Map<string, NodeLayout>();
-
-    for (const [id, target] of this._targets) {
-      const current = this.positions.get(id);
-      if (!current) {
-        // First appearance — snap directly, no lerp
-        next.set(id, { ...target });
-        continue;
-      }
-      const nx = current.x + (target.x - current.x) * LERP_FACTOR;
-      const ny = current.y + (target.y - current.y) * LERP_FACTOR;
-      const dx = Math.abs(target.x - nx);
-      const dy = Math.abs(target.y - ny);
-      if (dx > maxDelta) maxDelta = dx;
-      if (dy > maxDelta) maxDelta = dy;
-      next.set(id, { id, x: nx, y: ny, width: target.width, height: target.height });
-    }
-
-    this.positions = next;
-    this._frameCount++;
-
-    if (maxDelta > SETTLE_THRESH) {
-      this._rafId = requestAnimationFrame(this._tick);
-    } else {
-      // Settled — snap to exact targets
-      this.positions = new Map(this._targets);
-      this._rafId = null;
-    }
-  };
-
-  destroy(): void {
-    if (this._rafId !== null) {
-      cancelAnimationFrame(this._rafId);
-      this._rafId = null;
-    }
-  }
-}

package/src/n1-flow-canvas/layout.ts

@@ -1,118 +0,0 @@
-// N1 layout — ELK-based graph layout + BFS order
-// Runs on the main thread (ELK is async/Promise-based; won't block UI).
-// Extracted from layout.worker.ts so FlowCanvas can call it directly,
-// avoiding nested Worker creation which fails in Tauri's WKWebView.
-
-import ELK from 'elkjs/lib/elk.bundled.js';
-import type { LayoutResult, NodeLayout } from './types.js';
-import type { GraphSnapshot, GraphNode, GraphEdge } from './types.js';
-
-const elk = new ELK();
-
-// ── BFS ───────────────────────────────────────────────────────────────────────
-
-function computeBfsOrder(
-  nodes: ReadonlyArray<GraphNode>,
-  edges: ReadonlyArray<GraphEdge>,
-  startId: string | null,
-): string[] {
-  const adj = new Map<string, string[]>();
-  for (const n of nodes) adj.set(n.id, []);
-  for (const e of edges) {
-    const neighbors = adj.get(e.sourceId);
-    if (neighbors) neighbors.push(e.targetId);
-  }
-
-  const rootId = startId ?? nodes[0]?.id;
-  if (!rootId) return [];
-
-  const visited = new Set<string>();
-  const queue: string[] = [rootId];
-  const order: string[] = [];
-  visited.add(rootId);
-
-  while (queue.length > 0) {
-    const current = queue.shift()!;
-    order.push(current);
-    const neighbors = (adj.get(current) ?? []).slice().sort(); // S-02: deterministic
-    for (const neighbor of neighbors) {
-      if (!visited.has(neighbor)) {
-        visited.add(neighbor);
-        queue.push(neighbor);
-      }
-    }
-  }
-
-  for (const n of nodes) {
-    if (!visited.has(n.id)) order.push(n.id);
-  }
-
-  return order;
-}
-
-// ── ELK layout ────────────────────────────────────────────────────────────────
-
-const NODE_WIDTH  = 120;
-const NODE_HEIGHT = 60;
-
-export async function runLayout(
-  snapshot: GraphSnapshot,
-  _canvasWidth: number,
-  _canvasHeight: number,
-): Promise<LayoutResult> {
-  const elkGraph = {
-    id: 'root',
-    layoutOptions: {
-      'elk.algorithm': 'layered',
-      'elk.direction': 'RIGHT',
-      'elk.spacing.nodeNode': '30',
-      'elk.layered.spacing.nodeNodeBetweenLayers': '80',
-      'elk.padding': '[top=40,left=40,bottom=40,right=40]',
-      'elk.layered.nodePlacement.strategy': 'BRANDES_KOEPF',
-    },
-    children: snapshot.nodes.map(n => ({
-      id: n.id,
-      width: NODE_WIDTH,
-      height: NODE_HEIGHT,
-    })),
-    edges: snapshot.edges.map(e => ({
-      id: e.id,
-      sources: [e.sourceId],
-      targets: [e.targetId],
-    })),
-  };
-
-  const result = await elk.layout(elkGraph);
-
-  const positions = new Map<string, NodeLayout>();
-  for (const child of result.children ?? []) {
-    if (child.x !== undefined && child.y !== undefined) {
-      positions.set(child.id, {
-        id: child.id,
-        x: child.x,
-        y: child.y,
-        width: child.width ?? NODE_WIDTH,
-        height: child.height ?? NODE_HEIGHT,
-      });
-    }
-  }
-
-  // Grid fallback for nodes ELK dropped (should not happen)
-  let col = 0;
-  for (const n of snapshot.nodes) {
-    if (!positions.has(n.id)) {
-      positions.set(n.id, {
-        id: n.id,
-        x: 40 + col * (NODE_WIDTH + 40),
-        y: 40,
-        width: NODE_WIDTH,
-        height: NODE_HEIGHT,
-      });
-      col++;
-    }
-  }
-
-  const bfsOrder = computeBfsOrder(snapshot.nodes, snapshot.edges, snapshot.focusNodeId);
-
-  return { positions, bfsOrder };
-}

package/src/n1-flow-canvas/layout.worker.ts

@@ -1,128 +0,0 @@
-// N1 Layout Worker — ELK.js layout + BFS traversal order
-// Runs in a dedicated Web Worker (mandatory at mount, never on main thread)
-// S-02: BFS neighbors sorted before enqueue for deterministic order
-
-import ELK from 'elkjs/lib/elk.bundled.js';
-import type { WorkerIn, WorkerOut, LayoutResult, NodeLayout } from './types.js';
-import type { GraphSnapshot, GraphNode, GraphEdge } from './types.js';
-
-const elk = new ELK();
-
-// ── BFS ───────────────────────────────────────────────────────────────────────
-
-function computeBfsOrder(
-  nodes: ReadonlyArray<GraphNode>,
-  edges: ReadonlyArray<GraphEdge>,
-  startId: string | null,
-): string[] {
-  // Build adjacency with Map (S-02: no object spread iteration)
-  const adj = new Map<string, string[]>();
-  for (const n of nodes) adj.set(n.id, []);
-  for (const e of edges) {
-    const neighbors = adj.get(e.sourceId);
-    if (neighbors) neighbors.push(e.targetId);
-  }
-
-  // Root: prefer explicit startId, fall back to first node in declaration order
-  const rootId = startId ?? nodes[0]?.id;
-  if (!rootId) return [];
-
-  const visited = new Set<string>();
-  const queue: string[] = [rootId];
-  const order: string[] = [];
-  visited.add(rootId);
-
-  while (queue.length > 0) {
-    const current = queue.shift()!;
-    order.push(current);
-    // Sort neighbors for determinism (S-02)
-    const neighbors = (adj.get(current) ?? []).slice().sort();
-    for (const neighbor of neighbors) {
-      if (!visited.has(neighbor)) {
-        visited.add(neighbor);
-        queue.push(neighbor);
-      }
-    }
-  }
-
-  // Append any unreachable nodes in declaration order (disconnected subgraphs)
-  for (const n of nodes) {
-    if (!visited.has(n.id)) order.push(n.id);
-  }
-
-  return order;
-}
-
-// ── ELK layout ────────────────────────────────────────────────────────────────
-
-const NODE_WIDTH  = 120;
-const NODE_HEIGHT = 60;
-
-async function runLayout(snapshot: GraphSnapshot, canvasWidth: number, canvasHeight: number): Promise<LayoutResult> {
-  const elkGraph = {
-    id: 'root',
-    layoutOptions: {
-      'elk.algorithm': 'layered',
-      'elk.direction': 'DOWN',
-      'elk.spacing.nodeNode': '40',
-      'elk.layered.spacing.nodeNodeBetweenLayers': '60',
-      'elk.padding': '[top=40,left=40,bottom=40,right=40]',
-    },
-    children: snapshot.nodes.map(n => ({
-      id: n.id,
-      width: NODE_WIDTH,
-      height: NODE_HEIGHT,
-    })),
-    edges: snapshot.edges.map(e => ({
-      id: e.id,
-      sources: [e.sourceId],
-      targets: [e.targetId],
-    })),
-  };
-
-  const result = await elk.layout(elkGraph);
-
-  const positions = new Map<string, NodeLayout>();
-  for (const child of result.children ?? []) {
-    if (child.x !== undefined && child.y !== undefined) {
-      positions.set(child.id, {
-        id: child.id,
-        x: child.x,
-        y: child.y,
-        width: child.width ?? NODE_WIDTH,
-        height: child.height ?? NODE_HEIGHT,
-      });
-    }
-  }
-
-  // Fall back: place unmapped nodes in a grid (ELK dropped them — shouldn't happen)
-  let col = 0;
-  for (const n of snapshot.nodes) {
-    if (!positions.has(n.id)) {
-      positions.set(n.id, {
-        id: n.id,
-        x: 40 + col * (NODE_WIDTH + 40),
-        y: 40,
-        width: NODE_WIDTH,
-        height: NODE_HEIGHT,
-      });
-      col++;
-    }
-  }
-
-  const bfsOrder = computeBfsOrder(snapshot.nodes, snapshot.edges, snapshot.focusNodeId);
-
-  return { positions, bfsOrder };
-}
-
-// ── Worker message loop ───────────────────────────────────────────────────────
-
-self.onmessage = async (event: MessageEvent<WorkerIn>) => {
-  const msg = event.data;
-  if (msg.type !== 'layout') return;
-
-  const result = await runLayout(msg.snapshot, msg.canvasWidth, msg.canvasHeight);
-
-  const out: WorkerOut = { type: 'layout_result', result };
-  self.postMessage(out);
-};