@stephen-netu/design-system 0.1.0

package/src/n3-force-graph/GraphTooltip.svelte

@@ -0,0 +1,99 @@
+<script lang="ts">
+  // N3 GraphTooltip — Floating tooltip positioned by graph hover events
+  // wt-800: Slot-based content, positioned near hovered node
+  // Zero domain knowledge — any content can be rendered inside
+  //
+  // S-05: visibility toggled by prop, no timers
+
+  import type { Snippet } from 'svelte';
+
+  interface Props {
+    /** Whether the tooltip is visible */
+    visible?: boolean;
+    /** Screen X position (from graph coordinate transform) */
+    x?: number;
+    /** Screen Y position */
+    y?: number;
+    /** Offset from anchor point. Default 12. */
+    offset?: number;
+    /** Max width in px. Default 280. */
+    maxWidth?: number;
+    /** Content slot */
+    children?: Snippet;
+  }
+
+  let {
+    visible = false,
+    x = 0,
+    y = 0,
+    offset = 12,
+    maxWidth = 280,
+    children,
+  }: Props = $props();
+
+  // Keep tooltip within viewport
+  let tooltipEl: HTMLDivElement | undefined = $state();
+
+  const style = $derived.by(() => {
+    // Position below and to the right of the anchor by default
+    let left = x + offset;
+    let top = y + offset;
+
+    // Viewport clamping (approximate — exact requires measuring after render)
+    if (typeof window !== 'undefined') {
+      if (left + maxWidth > window.innerWidth - 16) {
+        left = x - maxWidth - offset;
+      }
+      if (top + 120 > window.innerHeight - 16) {
+        top = y - 120 - offset;
+      }
+    }
+
+    return `left: ${left}px; top: ${top}px; max-width: ${maxWidth}px;`;
+  });
+</script>
+
+{#if visible && children}
+  <div
+    bind:this={tooltipEl}
+    class="n3-graph-tooltip"
+    style={style}
+    role="tooltip"
+  >
+    {@render children()}
+  </div>
+{/if}
+
+<style>
+  .n3-graph-tooltip {
+    position: fixed;
+    z-index: 1000;
+    pointer-events: none;
+
+    background: var(--bg-elevated, #2a2a2a);
+    border: 1px solid var(--border-subtle, rgba(255, 255, 255, 0.06));
+    border-radius: var(--radius-sm, 6px);
+    padding: var(--space-2, 0.5rem) var(--space-3, 0.75rem);
+
+    color: var(--text-primary, #f2efe9);
+    font-family: var(--font-mono, 'JetBrains Mono', monospace);
+    font-size: 0.75rem;
+    line-height: 1.4;
+
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.4);
+
+    /* Fade in */
+    animation: n3-tooltip-fade 120ms ease-out;
+  }
+
+  @keyframes n3-tooltip-fade {
+    from {
+      opacity: 0;
+      transform: translateY(4px);
+    }
+    to {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  }
+</style>

package/src/n3-force-graph/animated-edge.ts

@@ -0,0 +1,107 @@
+// N3 Animated Edge — linkCanvasObject callback for force-graph
+// wt-799: Three modes: marching-ants (active), dashed-static (stub), solid (wired)
+// Zero domain knowledge — pure visual primitive
+//
+// S-02: animation driven by tick counter, not wall clock
+// S-05: bounded by force-graph's own cooldown/frame budget
+
+import type { ForceGraphNode, ForceGraphLink, AnimatedEdgeConfig } from './types.js';
+import { getPulseTick } from './health-node.js';
+
+const DEFAULTS: Required<AnimatedEdgeConfig> = {
+  dashLength: 8,
+  gapLength: 4,
+  marchSpeed: 0.5,
+};
+
+/**
+ * Create a `linkCanvasObject` callback for force-graph.
+ *
+ * Modes:
+ * - `active`: marching-ants animation (data flowing)
+ * - `stub`: dashed static line (connection exists but not wired)
+ * - `wired`: solid line (fully connected)
+ *
+ * Usage:
+ * ```ts
+ * import { createAnimatedEdgeRenderer } from '@kos/design-system/n3-force-graph';
+ * graph.linkCanvasObject(createAnimatedEdgeRenderer());
+ * graph.linkCanvasObjectMode(() => 'replace');
+ * ```
+ */
+export function createAnimatedEdgeRenderer(
+  config?: AnimatedEdgeConfig,
+): (link: ForceGraphLink, ctx: CanvasRenderingContext2D, globalScale: number) => void {
+  const { dashLength, gapLength, marchSpeed } = { ...DEFAULTS, ...config };
+
+  return (link: ForceGraphLink, ctx: CanvasRenderingContext2D, globalScale: number) => {
+    // force-graph mutates source/target to resolved node objects at runtime
+    const source = link.source as unknown as ForceGraphNode;
+    const target = link.target as unknown as ForceGraphNode;
+
+    const sx = source.x ?? 0;
+    const sy = source.y ?? 0;
+    const tx = target.x ?? 0;
+    const ty = target.y ?? 0;
+
+    ctx.save();
+
+    const mode = link.mode ?? 'wired';
+
+    switch (mode) {
+      case 'active': {
+        // Marching-ants: animated dash offset driven by pulse tick
+        const offset = getPulseTick() * marchSpeed;
+        ctx.setLineDash([dashLength / globalScale, gapLength / globalScale]);
+        ctx.lineDashOffset = -offset / globalScale;
+        ctx.strokeStyle = '#b87333'; // brass — active flow
+        ctx.lineWidth = 2 / globalScale;
+        break;
+      }
+      case 'stub': {
+        // Dashed static: connection exists but unwired
+        ctx.setLineDash([4 / globalScale, 6 / globalScale]);
+        ctx.lineDashOffset = 0;
+        ctx.strokeStyle = '#5a4a30'; // muted brass
+        ctx.lineWidth = 1 / globalScale;
+        break;
+      }
+      case 'wired':
+      default: {
+        // Solid: fully connected
+        ctx.setLineDash([]);
+        ctx.strokeStyle = '#706858'; // tertiary text color
+        ctx.lineWidth = 1.5 / globalScale;
+        break;
+      }
+    }
+
+    // Draw line
+    ctx.beginPath();
+    ctx.moveTo(sx, sy);
+    ctx.lineTo(tx, ty);
+    ctx.stroke();
+
+    // Arrowhead for directed links (except stub)
+    if (mode !== 'stub') {
+      const angle = Math.atan2(ty - sy, tx - sx);
+      const arrowSize = 6 / globalScale;
+
+      ctx.fillStyle = ctx.strokeStyle;
+      ctx.beginPath();
+      ctx.moveTo(tx, ty);
+      ctx.lineTo(
+        tx - arrowSize * Math.cos(angle - Math.PI / 7),
+        ty - arrowSize * Math.sin(angle - Math.PI / 7),
+      );
+      ctx.lineTo(
+        tx - arrowSize * Math.cos(angle + Math.PI / 7),
+        ty - arrowSize * Math.sin(angle + Math.PI / 7),
+      );
+      ctx.closePath();
+      ctx.fill();
+    }
+
+    ctx.restore();
+  };
+}

package/src/n3-force-graph/health-node.ts

@@ -0,0 +1,128 @@
+// N3 Health Node — nodeCanvasObject callback for force-graph
+// wt-798: Renders nodes with health-derived color, pulse animation, size scaling
+// Zero domain knowledge — pure visual primitive
+//
+// S-02: health values are integer permille. No Math.random.
+// S-05: pulse uses rAF tick count (bounded by force-graph's own cooldown).
+
+import type { ForceGraphNode, HealthNodeConfig } from './types.js';
+import { healthToColor, healthToGlow } from './types.js';
+
+const DEFAULTS: Required<HealthNodeConfig> = {
+  baseRadius: 6,
+  pulseEnabled: true,
+  pulseAmplitude: 0.02,
+};
+
+// Global tick counter for deterministic pulse — incremented by the ForceGraph
+// component on each engine tick. Avoids Date.now() / performance.now() in render.
+let _pulseTick = 0;
+export function advancePulseTick(): void { _pulseTick++; }
+export function getPulseTick(): number { return _pulseTick; }
+
+/**
+ * Create a `nodeCanvasObject` callback for force-graph.
+ *
+ * Usage:
+ * ```ts
+ * import { createHealthNodeRenderer } from '@kos/design-system/n3-force-graph';
+ * graph.nodeCanvasObject(createHealthNodeRenderer({ baseRadius: 8 }));
+ * graph.nodeCanvasObjectMode(() => 'replace');
+ * ```
+ */
+export function createHealthNodeRenderer(
+  config?: HealthNodeConfig,
+): (node: ForceGraphNode, ctx: CanvasRenderingContext2D, globalScale: number) => void {
+  const { baseRadius, pulseEnabled, pulseAmplitude } = { ...DEFAULTS, ...config };
+
+  return (node: ForceGraphNode, ctx: CanvasRenderingContext2D, globalScale: number) => {
+    const x = node.x ?? 0;
+    const y = node.y ?? 0;
+    const weight = node.weight ?? 1;
+    const health = node.health ?? 0;
+
+    // Size: base * sqrt(weight) for area-proportional scaling
+    let radius = baseRadius * Math.sqrt(weight);
+
+    // Pulse: subtle scale oscillation on healthy nodes
+    if (pulseEnabled && health >= 500) {
+      // Deterministic sine wave from tick counter, not wall clock
+      const phase = (_pulseTick * 0.05) % (2 * Math.PI);
+      const pulse = 1.0 + pulseAmplitude * Math.sin(phase);
+      radius *= pulse;
+    }
+
+    const color = healthToColor(health);
+    const glowAlpha = healthToGlow(health);
+
+    // Glow (outer ring via shadow)
+    if (glowAlpha > 0) {
+      ctx.beginPath();
+      ctx.arc(x, y, radius + 3 / globalScale, 0, 2 * Math.PI);
+      // Parse hex → rgba for the fill
+      const r = parseInt(color.slice(1, 3), 16);
+      const g = parseInt(color.slice(3, 5), 16);
+      const b = parseInt(color.slice(5, 7), 16);
+      ctx.fillStyle = `rgba(${r}, ${g}, ${b}, ${glowAlpha})`;
+      ctx.shadowColor = color;
+      ctx.shadowBlur = 8 / globalScale;
+      ctx.fill();
+      ctx.shadowColor = 'transparent';
+      ctx.shadowBlur = 0;
+    }
+
+    // Node circle
+    ctx.beginPath();
+    ctx.arc(x, y, radius, 0, 2 * Math.PI);
+    ctx.fillStyle = color;
+    ctx.fill();
+
+    // Border
+    ctx.strokeStyle = 'rgba(255, 255, 255, 0.15)';
+    ctx.lineWidth = 1 / globalScale;
+    ctx.stroke();
+
+    // Label (below node, only when zoomed in enough)
+    if (globalScale >= 0.6) {
+      const fontSize = Math.max(10, 12 / globalScale);
+      ctx.font = `${fontSize}px var(--font-mono, 'JetBrains Mono', monospace)`;
+      ctx.textAlign = 'center';
+      ctx.textBaseline = 'top';
+      ctx.fillStyle = '#e8e0d0';
+
+      const label = node.label.length > 20 ? node.label.slice(0, 18) + '…' : node.label;
+      ctx.fillText(label, x, y + radius + 4 / globalScale);
+    }
+
+    // Type indicator: app nodes get a ring, ADR nodes get a diamond
+    if (node.type === 'app') {
+      ctx.beginPath();
+      ctx.arc(x, y, radius + 1.5 / globalScale, 0, 2 * Math.PI);
+      ctx.strokeStyle = '#b87333'; // brass
+      ctx.lineWidth = 2 / globalScale;
+      ctx.stroke();
+    }
+  };
+}
+
+/**
+ * Create a `nodePointerAreaPaint` callback for hit detection.
+ * Returns a circle matching the visual node size.
+ */
+export function createHealthNodeAreaPaint(
+  config?: HealthNodeConfig,
+): (node: ForceGraphNode, paintColor: string, ctx: CanvasRenderingContext2D, globalScale: number) => void {
+  const { baseRadius } = { ...DEFAULTS, ...config };
+
+  return (node: ForceGraphNode, paintColor: string, ctx: CanvasRenderingContext2D) => {
+    const x = node.x ?? 0;
+    const y = node.y ?? 0;
+    const weight = node.weight ?? 1;
+    const radius = baseRadius * Math.sqrt(weight) + 4; // generous hit area
+
+    ctx.beginPath();
+    ctx.arc(x, y, radius, 0, 2 * Math.PI);
+    ctx.fillStyle = paintColor;
+    ctx.fill();
+  };
+}

package/src/n3-force-graph/index.ts

@@ -0,0 +1,31 @@
+// N3 Force Graph — Force-directed graph with health-aware rendering
+// Depends on: force-graph (vasturiano)
+//
+// Components:
+//   ForceGraph.svelte  — Canvas 2D wrapper (wt-797)
+//   health-node.ts     — nodeCanvasObject callback (wt-798)
+//   animated-edge.ts   — linkCanvasObject callback (wt-799)
+//   GraphTooltip.svelte — Floating tooltip (wt-800)
+
+export type {
+  ForceGraphNode,
+  ForceGraphLink,
+  ForceGraphData,
+  HealthNodeConfig,
+  AnimatedEdgeConfig,
+  TooltipPosition,
+} from './types.js';
+
+export { healthToColor, healthToGlow } from './types.js';
+
+export { default as ForceGraph } from './ForceGraph.svelte';
+export { default as GraphTooltip } from './GraphTooltip.svelte';
+
+export {
+  createHealthNodeRenderer,
+  createHealthNodeAreaPaint,
+  advancePulseTick,
+  getPulseTick,
+} from './health-node.js';
+
+export { createAnimatedEdgeRenderer } from './animated-edge.js';

package/src/n3-force-graph/types.ts

@@ -0,0 +1,94 @@
+// N3 Force Graph — Types
+// Pure TypeScript — no Svelte, no DOM dependencies
+// S-02: all health values are integer permille (0–1000)
+
+// Re-export shared graph primitives from n1
+export type { GraphNode, GraphEdge, GraphSnapshot } from '../n1-flow-canvas/types.js';
+
+// === Force Graph Node (extends GraphNode with health/visual data) ===
+
+export interface ForceGraphNode {
+  id: string;
+  label: string;
+  /** Node category for visual differentiation */
+  type: 'app' | 'adr' | 'domain' | string;
+  /** Health score in permille (0–1000). 0 = critical, 1000 = healthy. */
+  health: number;
+  /** Node visual weight — controls circle radius. Default 1. */
+  weight?: number;
+  /** Optional: pinned position (drag-to-pin). Set fx/fy to pin. */
+  fx?: number;
+  fy?: number;
+  /** Arbitrary domain data for tooltip/detail rendering */
+  data?: Record<string, unknown>;
+  // d3-force internal (populated by simulation)
+  x?: number;
+  y?: number;
+  vx?: number;
+  vy?: number;
+  index?: number;
+}
+
+export interface ForceGraphLink {
+  id: string;
+  source: string;
+  target: string;
+  /** Edge rendering mode */
+  mode: 'active' | 'stub' | 'wired';
+  /** Optional label (e.g. dependency name) */
+  label?: string;
+}
+
+// === Health Node Config ===
+
+export interface HealthNodeConfig {
+  /** Base circle radius in px. Default 6. */
+  baseRadius?: number;
+  /** Whether to animate pulse on healthy nodes. Default true. */
+  pulseEnabled?: boolean;
+  /** Pulse amplitude (scale factor above 1.0). Default 0.02. */
+  pulseAmplitude?: number;
+}
+
+// === Animated Edge Config ===
+
+export interface AnimatedEdgeConfig {
+  /** Marching-ants dash length. Default 8. */
+  dashLength?: number;
+  /** Marching-ants gap length. Default 4. */
+  gapLength?: number;
+  /** Animation speed (px/frame). Default 0.5. */
+  marchSpeed?: number;
+}
+
+// === Graph Data (input to ForceGraph) ===
+
+export interface ForceGraphData {
+  nodes: ForceGraphNode[];
+  links: ForceGraphLink[];
+}
+
+// === Tooltip ===
+
+export interface TooltipPosition {
+  x: number;
+  y: number;
+  visible: boolean;
+}
+
+// === Health → Color mapping (integer permille thresholds) ===
+
+/** Map health permille to CSS color string. Pure function, no side effects. */
+export function healthToColor(permille: number): string {
+  if (permille >= 800) return '#27ae60'; // green — healthy
+  if (permille >= 500) return '#f39c12'; // amber — partial
+  if (permille >= 200) return '#c0392b'; // red — blocked/stub-heavy
+  return '#3a3a3a';                       // dark — no data / dead
+}
+
+/** Map health permille to glow opacity (0.0–0.4). Healthy = brighter glow. */
+export function healthToGlow(permille: number): number {
+  if (permille >= 800) return 0.3;
+  if (permille >= 500) return 0.15;
+  return 0.0; // No glow for unhealthy/dead
+}