@stephen-netu/design-system 0.1.0

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

@@ -0,0 +1,118 @@
+// 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

@@ -0,0 +1,128 @@
+// 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);
+};

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

@@ -0,0 +1,102 @@
+// N1 Flow Canvas — Shared Types
+// Pure TypeScript — no Svelte, no DOM dependencies
+// S-02: all collections use Map/Array with deterministic ordering (no Set/Object spread iteration)
+
+// === Graph Primitives ===
+
+export interface GraphNode {
+  id: string;
+  label: string;
+  /** Optional semantic data (task status, flow phase, etc.) */
+  data: Record<string, unknown>;
+}
+
+export interface GraphEdge {
+  id: string;
+  sourceId: string;
+  targetId: string;
+  /** Optional: task wt-NNN dependency references */
+  label?: string;
+}
+
+// === GraphSnapshot — readonly, fed to ELK worker, never mutated during layout ===
+
+export interface GraphSnapshot {
+  readonly nodes: ReadonlyArray<GraphNode>;
+  readonly edges: ReadonlyArray<GraphEdge>;
+  /** Node id used as layout/BFS root */
+  readonly focusNodeId: string | null;
+}
+
+// === Computed Layout ===
+
+export interface NodeLayout {
+  id: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface LayoutResult {
+  /** Euclidean positions from ELK, keyed by node id */
+  positions: Map<string, NodeLayout>;
+  /** BFS traversal order starting from focusNodeId (or arbitrary root if null) */
+  bfsOrder: ReadonlyArray<string>;
+}
+
+// === Worker Protocol ===
+
+export interface WorkerIn {
+  type: 'layout';
+  snapshot: GraphSnapshot;
+  /** Canvas dimensions for ELK bounds */
+  canvasWidth: number;
+  canvasHeight: number;
+}
+
+export interface WorkerOut {
+  type: 'layout_result';
+  result: LayoutResult;
+}
+
+export type WorkerMessage = WorkerIn | WorkerOut;
+
+// === GraphState — mutable, holds Spring-wrapped positions ===
+// Implemented in graph-state.svelte.ts (Svelte 5 runes required)
+// Defined here as an interface for type-checking without Svelte dependency
+
+export interface GraphStateApi {
+  /** Current node positions (Spring targets). Read these for rendering. */
+  readonly positions: Map<string, NodeLayout>;
+  /** Current BFS order for edge reveal animation */
+  readonly bfsOrder: ReadonlyArray<string>;
+  /** Update Spring targets from a completed layout. Does NOT reset current positions. */
+  applyLayout(result: LayoutResult): void;
+  /** Re-center Poincaré disk on this node. Does NOT trigger re-layout. */
+  setFocusCenter(nodeId: string): void;
+  /** Mark ELK layout root. Triggers worker re-compute. */
+  setLayoutRoot(nodeId: string): void;
+}
+
+// === Edge Reveal Animation ===
+
+export interface EdgeRevealState {
+  /** Edge id → current lineDashOffset (0.0 = fully drawn, 1.0 = hidden) */
+  offsets: Map<string, number>;
+}
+
+/** Stagger delay per BFS wave step (ms). Deterministic — no Math.random. */
+export const EDGE_REVEAL_STAGGER_MS = 30;
+
+// === Geometry (shared with n0, re-exported for convenience) ===
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+export interface Size {
+  width: number;
+  height: number;
+}

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

@@ -0,0 +1,146 @@
+// N1 Flow Canvas — Generic graph adapter utilities
+// These are the reusable algorithms; apps supply their own domain types + config.
+// S-02: all collections use Map/Array — no Set iteration order assumptions
+
+import type { GraphEdge, NodeLayout } from './types.js';
+
+// ── Hit testing ───────────────────────────────────────────────────────────────
+
+/**
+ * Returns the id of the first node whose layout rect contains (x, y), or null.
+ *
+ * When the canvas element is scaled (CSS width ≠ canvas pixel width), pass
+ * scaleX/scaleY to convert event coordinates before testing.
+ *
+ * @param x       - click x in canvas pixel space
+ * @param y       - click y in canvas pixel space
+ * @param positions - GraphState.positions map
+ */
+export function nodeHitTest(
+  x: number,
+  y: number,
+  positions: Map<string, NodeLayout>,
+): string | null {
+  for (const [id, layout] of positions) {
+    if (
+      x >= layout.x &&
+      x <= layout.x + layout.width &&
+      y >= layout.y &&
+      y <= layout.y + layout.height
+    ) {
+      return id;
+    }
+  }
+  return null;
+}
+
+/**
+ * Convert a DOM click event on a container element to canvas pixel coordinates,
+ * accounting for CSS scaling between container size and canvas resolution.
+ */
+export function domEventToCanvasCoords(
+  event: MouseEvent,
+  canvasWidth: number,
+  canvasHeight: number,
+): { x: number; y: number } {
+  const rect = (event.currentTarget as HTMLElement).getBoundingClientRect();
+  const scaleX = canvasWidth  / rect.width;
+  const scaleY = canvasHeight / rect.height;
+  return {
+    x: (event.clientX - rect.left) * scaleX,
+    y: (event.clientY - rect.top)  * scaleY,
+  };
+}
+
+// ── Edge inference ────────────────────────────────────────────────────────────
+
+/**
+ * Parse directed dependency edges by scanning each item's description for
+ * regex matches that reference another item's id.
+ *
+ * Generic — works for any item type. Apps supply:
+ * - `idFn`   — extract the item's own id
+ * - `descFn` — extract the text to scan (description, notes, etc.)
+ * - `mentionRegex` — must have one capture group yielding the referenced id
+ * - `mentionToId`  — convert regex capture to a canonical id (e.g. `m => 'wt-' + m`)
+ *
+ * @example KOS usage:
+ *   parseMentionEdges(tasks, t => t.id, t => t.description ?? '', /wt-(\d+)/g, m => `wt-${m}`)
+ */
+export function parseMentionEdges<T>(
+  items: T[],
+  idFn: (item: T) => string,
+  descFn: (item: T) => string,
+  mentionRegex: RegExp,
+  mentionToId: (capture: string) => string,
+  edgesMap: Map<string, GraphEdge> = new Map(),
+): Map<string, GraphEdge> {
+  const knownIds = new Set(items.map(idFn));
+
+  for (const item of items) {
+    const sourceId = idFn(item);
+    const text = descFn(item);
+    if (!text) continue;
+
+    for (const match of text.matchAll(mentionRegex)) {
+      const targetId = mentionToId(match[1]);
+      if (!knownIds.has(targetId)) continue;
+
+      const edgeId = `${sourceId}->${targetId}`;
+      if (edgesMap.has(edgeId)) continue;
+
+      edgesMap.set(edgeId, {
+        id:       edgeId,
+        sourceId,
+        targetId,
+        label:    'depends_on',
+      });
+    }
+  }
+
+  return edgesMap;
+}
+
+/**
+ * Create sequential "related" edges between items that share the same group key,
+ * ordered by a sort key. Produces a chain: group[0]→group[1]→group[2]…
+ *
+ * Generic — apps supply:
+ * - `idFn`       — extract item id
+ * - `groupKeyFn` — items with the same key become a chain (e.g. domain+workspace)
+ * - `sortKeyFn`  — ordering within each group (e.g. createdAt string, or id)
+ *
+ * @example KOS usage:
+ *   parseGroupedSequenceEdges(tasks, t => t.id,
+ *     t => `${t.domain ?? ''}:${t.workspace ?? ''}`,
+ *     t => t.createdAt ?? t.id)
+ */
+export function parseGroupedSequenceEdges<T>(
+  items: T[],
+  idFn: (item: T) => string,
+  groupKeyFn: (item: T) => string,
+  sortKeyFn: (item: T) => string,
+  edgesMap: Map<string, GraphEdge> = new Map(),
+): Map<string, GraphEdge> {
+  const sorted = [...items].sort((a, b) => sortKeyFn(a).localeCompare(sortKeyFn(b)));
+
+  const groups = new Map<string, T[]>();
+  for (const item of sorted) {
+    const key = groupKeyFn(item);
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key)!.push(item);
+  }
+
+  for (const groupItems of groups.values()) {
+    if (groupItems.length < 2) continue;
+    for (let i = 0; i < groupItems.length - 1; i++) {
+      const sourceId = idFn(groupItems[i]);
+      const targetId = idFn(groupItems[i + 1]);
+      const edgeId   = `${sourceId}->${targetId}`;
+      if (edgesMap.has(edgeId)) continue;
+      edgesMap.set(edgeId, { id: edgeId, sourceId, targetId, label: 'related' });
+    }
+  }
+
+  return edgesMap;
+}