@dr2rai/raid-canvas 0.2.0 → 0.3.1

package/src/X6Shapes.ts

@@ -13,6 +13,7 @@ import { Graph, Shape, Node, Edge } from '@antv/x6';
 import type {
   AimOntologyKind,
   AimEdgeKind,
+  AimRoutingMode,
   RaidNodeData,
   RaidEdgeData,
   OrthogonalPortId,
@@ -36,6 +37,74 @@ export const CascaisPalette = {
   TextSecondary: '#4B5563',
 } as const;
 
+/**
+ * Formats and wraps node label text for AOAIM entities.
+ * Automatically wraps on whitespace when exceeding target length,
+ * and treats `<wbr>` / `<wbr/>` tags and hyphens as soft word-break opportunities
+ * within long unbroken words or strings.
+ */
+export function wrapAimText(rawText: string, maxLineLength: number = 18): string {
+  if (!rawText) return '';
+
+  const lines = rawText.split('\n');
+  const resultLines: string[] = [];
+
+  for (const line of lines) {
+    if (!line) {
+      resultLines.push('');
+      continue;
+    }
+
+    // Replace <wbr> / <wbr/> with zero-width break marker \u200B,
+    // and allow breaking after hyphens within words
+    const normalized = line
+      .replace(/<wbr\s*\/?>/gi, '\u200B')
+      .replace(/-(?=[a-zA-Z0-9])/g, '-\u200B');
+
+    const spaceWords = normalized.split(/\s+/).filter(Boolean);
+    if (spaceWords.length === 0) continue;
+
+    let currentLine = '';
+
+    for (let wordIdx = 0; wordIdx < spaceWords.length; wordIdx++) {
+      const spaceWord = spaceWords[wordIdx]!;
+      const chunks = spaceWord.split('\u200B').filter(Boolean);
+
+      for (let chunkIdx = 0; chunkIdx < chunks.length; chunkIdx++) {
+        const chunk = chunks[chunkIdx]!;
+        const isFirstChunkOfWord = chunkIdx === 0;
+
+        if (!currentLine) {
+          currentLine = chunk;
+        } else if (isFirstChunkOfWord) {
+          // Break or space before a new whitespace-separated word
+          if (currentLine.length + 1 + chunk.length <= maxLineLength) {
+            currentLine += ' ' + chunk;
+          } else {
+            resultLines.push(currentLine);
+            currentLine = chunk;
+          }
+        } else {
+          // Soft-break opportunity within a word (<wbr> or hyphen):
+          // Glues together without space if it fits; breaks without space if it overflows
+          if (currentLine.length + chunk.length <= maxLineLength) {
+            currentLine += chunk;
+          } else {
+            resultLines.push(currentLine);
+            currentLine = chunk;
+          }
+        }
+      }
+    }
+
+    if (currentLine) {
+      resultLines.push(currentLine);
+    }
+  }
+
+  return resultLines.join('\n');
+}
+
 /**
  * Port configuration generating 4 orthogonal snap anchors.
  */
@@ -132,7 +201,7 @@ export function registerAimShapes(): void {
     ports: createOrthogonalPorts(),
   });
 
-  // 2. AimActivityNode ('act') — Rounded rectangle with Heraldic Green border
+  // 2. AimActivityNode ('act') — Rounded rectangle with Heraldic Green border & underlined label
   Shape.Rect.define({
     shape: 'aim-act',
     overwrite: true,
@@ -155,6 +224,11 @@ export function registerAimShapes(): void {
         fontFamily: 'Inter, system-ui, -apple-system, sans-serif',
         textAnchor: 'middle',
         textVerticalAnchor: 'middle',
+        textDecoration: 'underline',
+        textWrap: {
+          width: -16,
+          breakWord: true,
+        },
       },
     },
     ports: createOrthogonalPorts(),
@@ -277,34 +351,77 @@ export function registerAimShapes(): void {
         fontFamily: 'Inter, system-ui, -apple-system, sans-serif',
         textAnchor: 'middle',
         textVerticalAnchor: 'middle',
+        textDecoration: 'underline',
+        textWrap: {
+          width: -16,
+          breakWord: true,
+        },
       },
     },
     ports: createOrthogonalPorts(),
   });
 
-  // 5. AimPersonNode ('per') — Person / Actor role card
+  // 5. AimPersonNode ('per') — Person / Actor glyph
   Shape.Rect.define({
     shape: 'aim-per',
     overwrite: true,
-    width: 120,
-    height: 70,
+    width: 90,
+    height: 90,
+    markup: [
+      {
+        tagName: 'rect',
+        selector: 'body',
+      },
+      {
+        tagName: 'path',
+        selector: 'torso',
+      },
+      {
+        tagName: 'circle',
+        selector: 'head',
+      },
+      {
+        tagName: 'text',
+        selector: 'label',
+      },
+    ],
     attrs: {
       body: {
-        fill: CascaisPalette.CanvasCream,
-        stroke: CascaisPalette.WarmGraphite,
-        strokeWidth: 1.5,
-        rx: 6,
-        ry: 6,
+        fill: 'transparent',
+        stroke: 'transparent',
+        strokeWidth: 0,
         class: 'aim-node aim-per',
       },
+      torso: {
+        d: 'M 61 50 v -4 a 8 8 0 0 0 -8 -8 H 37 a 8 8 0 0 0 -8 8 v 4',
+        fill: 'none',
+        stroke: CascaisPalette.WarmGraphite,
+        strokeWidth: 2,
+        strokeLinecap: 'round',
+        strokeLinejoin: 'round',
+      },
+      head: {
+        cx: 45,
+        cy: 22,
+        r: 8,
+        fill: CascaisPalette.ChalkWhite,
+        stroke: CascaisPalette.WarmGraphite,
+        strokeWidth: 2,
+      },
       label: {
-        text: '«actor»\nOperator',
+        text: 'Actor',
         fill: CascaisPalette.TextPrimary,
         fontSize: 12,
         fontWeight: '500',
         fontFamily: 'Inter, system-ui, -apple-system, sans-serif',
         textAnchor: 'middle',
-        textVerticalAnchor: 'middle',
+        textVerticalAnchor: 'top',
+        refX: 0.5,
+        refY: 62,
+        textWrap: {
+          width: -10,
+          breakWord: true,
+        },
       },
     },
     ports: createOrthogonalPorts(),
@@ -390,25 +507,30 @@ export function createAimNode(data: RaidNodeData): Node.Metadata {
 
   // Archetype-specific customization
   switch (data.kind) {
-    case 'uc':
+    case 'uc': {
+      const wrappedName = wrapAimText(data.displayName);
       return {
         ...baseMetadata,
         attrs: {
           label: {
-            text: data.stereotype ? `${data.stereotype}\n${data.displayName}` : data.displayName,
+            text: data.stereotype ? `${data.stereotype}\n${wrappedName}` : wrappedName,
           },
         },
       };
+    }
 
-    case 'act':
+    case 'act': {
+      const wrappedName = wrapAimText(data.displayName);
       return {
         ...baseMetadata,
         attrs: {
           label: {
-            text: data.stereotype ? `${data.stereotype}\n${data.displayName}` : data.displayName,
+            text: data.stereotype ? `${data.stereotype}\n${wrappedName}` : wrappedName,
+            textDecoration: 'underline',
           },
         },
       };
+    }
 
     case 'cls':
       return {
@@ -426,27 +548,35 @@ export function createAimNode(data: RaidNodeData): Node.Metadata {
         },
       };
 
-    case 'obj':
+    case 'obj': {
+      const wrappedName = wrapAimText(data.displayName);
       return {
         ...baseMetadata,
         attrs: {
           label: {
-            text: data.displayName,
+            text: data.stereotype ? `${data.stereotype}\n${wrappedName}` : wrappedName,
+            textDecoration: 'underline',
           },
         },
       };
+    }
 
     case 'per': {
       const isInitiating = data.stereotype?.toLowerCase().includes('initiates') ?? false;
+      const strokeColor = isInitiating ? CascaisPalette.NetGold : CascaisPalette.WarmGraphite;
+      const wrappedName = wrapAimText(data.displayName, 14);
+      const text = data.stereotype ? `${data.stereotype}\n${wrappedName}` : wrappedName;
       return {
         ...baseMetadata,
         attrs: {
-          body: {
-            stroke: isInitiating ? CascaisPalette.NetGold : CascaisPalette.WarmGraphite,
-            strokeWidth: isInitiating ? 2 : 1.5,
+          torso: {
+            stroke: strokeColor,
+          },
+          head: {
+            stroke: strokeColor,
           },
           label: {
-            text: data.stereotype ? `${data.stereotype}\n${data.displayName}` : data.displayName,
+            text,
           },
         },
       };
@@ -457,6 +587,34 @@ export function createAimNode(data: RaidNodeData): Node.Metadata {
   }
 }
 
+/**
+ * Configures the router and connector for an X6 Edge based on AimRoutingMode.
+ * - 'manhattan': Obstacle-avoiding 90° orthogonal router with rounded corners (radius: 8).
+ * - 'normal': Direct straight line point-to-point connection.
+ * - 'smooth': Curved cubic bezier spline between ports.
+ */
+export function applyEdgeRouting(edge: Edge, routing: AimRoutingMode = 'manhattan'): void {
+  switch (routing) {
+    case 'normal':
+      edge.setRouter('normal');
+      edge.setConnector('normal');
+      break;
+    case 'smooth':
+      edge.setRouter('normal');
+      edge.setConnector('smooth');
+      break;
+    case 'manhattan':
+    default:
+      edge.setRouter('manhattan', {
+        padding: 20,
+        startDirections: ['top', 'right', 'bottom', 'left'],
+        endDirections: ['top', 'right', 'bottom', 'left'],
+      });
+      edge.setConnector('rounded', { radius: 8 });
+      break;
+  }
+}
+
 /**
  * Factory creating an AntV X6 Edge model from a RaidEdgeData specification.
  */
@@ -464,10 +622,34 @@ export function createAimEdge(data: RaidEdgeData): Edge.Metadata {
   registerAimShapes();
 
   const edgeAttrs = getEdgeStyling(data.kind);
+  const routing = data.routing ?? 'manhattan';
+
+  let routerConfig: Edge.Metadata['router'] = {
+    name: 'manhattan',
+    args: {
+      padding: 20,
+      startDirections: ['top', 'right', 'bottom', 'left'],
+      endDirections: ['top', 'right', 'bottom', 'left'],
+    },
+  };
+  let connectorConfig: Edge.Metadata['connector'] = {
+    name: 'rounded',
+    args: { radius: 8 },
+  };
+
+  if (routing === 'normal') {
+    routerConfig = { name: 'normal' };
+    connectorConfig = { name: 'normal' };
+  } else if (routing === 'smooth') {
+    routerConfig = { name: 'normal' };
+    connectorConfig = { name: 'smooth' };
+  }
 
   return {
     id: data.id,
     shape: 'aim-edge',
+    router: routerConfig,
+    connector: connectorConfig,
     source: {
       cell: data.sourceId,
       ...(data.sourcePort !== undefined ? { port: data.sourcePort } : {}),
@@ -595,7 +777,7 @@ export function getDefaultNodeBounds(
     case 'obj':
       return { x, y, width: 160, height: 80 };
     case 'per':
-      return { x, y, width: 120, height: 70 };
+      return { x, y, width: 90, height: 90 };
     default:
       return { x, y, width: 140, height: 60 };
   }

package/src/index.ts

@@ -15,6 +15,7 @@
 export {
   AimSvgContract,
   type AimOntologyKind,
+  type AimRoutingMode,
   type AimEdgeKind,
   type Point,
   type SvgBendPoint,
@@ -35,8 +36,10 @@ export {
   configureAimGraph,
   createAimNode,
   createAimEdge,
+  applyEdgeRouting,
   getDefaultNodeBounds,
   getDefaultNodeName,
+  wrapAimText,
 } from './X6Shapes.js';
 
 // Anti-Entropy Semantic Connection Rules

package/src/styles/aoaim-theme.css

@@ -83,6 +83,12 @@
   ry: var(--aim-radius-act);
 }
 
+.aim-node[aim-act] text,
+.aim-node[aim-kind="act"] text,
+.aim-act text {
+  text-decoration: underline;
+}
+
 .aim-node[aim-act]:hover,
 .aim-node[aim-kind="act"]:hover {
   filter: drop-shadow(0 0 6px rgba(16, 185, 129, 0.4));
@@ -115,20 +121,28 @@
   stroke-width: 1.5px;
 }
 
+.aim-node[aim-obj] text,
+.aim-node[aim-kind="obj"] text,
+.aim-obj text {
+  text-decoration: underline;
+}
+
 /* 5. Person / Actor Nodes ('per') */
 .aim-node[aim-per],
 .aim-node[aim-kind="per"],
 .aim-per {
-  fill: var(--aim-canvas-cream);
-  stroke: var(--aim-warm-graphite);
-  stroke-width: 1.5px;
-  rx: var(--aim-radius-card);
-  ry: var(--aim-radius-card);
+  fill: transparent;
+  stroke: none;
 }
 
-.aim-node[aim-per][aim-role="initiating"] {
+.aim-node[aim-per] path,
+.aim-node[aim-per] circle {
+  transition: stroke 0.15s ease;
+}
+
+.aim-node[aim-per][aim-role="initiating"] path,
+.aim-node[aim-per][aim-role="initiating"] circle {
   stroke: var(--aim-net-gold);
-  stroke-width: 2px;
 }
 
 /* Relationship Edges */

package/src/types.ts

@@ -16,7 +16,15 @@
  * - 'obj' : Object / Instance (runtime instance card with underlined title)
  * - 'per' : Person / Actor (Initiating or Defined role stick-figure/card)
  */
-export type AimOntologyKind = 'uc' | 'act' | 'cls' | 'obj' | 'per';
+export type AimOntologyKind = 'act' | 'uc' | 'cls' | 'obj' | 'per';
+
+/**
+ * Routing strategy for diagram edges.
+ * - 'manhattan': Obstacle-avoiding 90° orthogonal routing with rounded corners (default).
+ * - 'normal': Direct straight line point-to-point connection.
+ * - 'smooth': Curved cubic bezier spline between ports.
+ */
+export type AimRoutingMode = 'manhattan' | 'normal' | 'smooth';
 
 /**
  * Ontological relationship classifications in AOAIM.
@@ -126,8 +134,14 @@ export interface RaidEdgeData {
   /** Multiplicity / Cardinality at the target end (e.g., '0..1', '*'). */
   readonly targetCardinality?: string;
 
+  /** Routing strategy for this edge ('manhattan', 'normal', 'smooth'). */
+  readonly routing?: AimRoutingMode;
+
   /** User-editable or router-computed Manhattan bend points. */
   readonly bendPoints: readonly SvgBendPoint[];
+
+  /** Precomputed or live SVG path data ('M ... L ...') for standalone vector rendering. */
+  readonly pathData?: string;
 }
 
 /**
@@ -149,6 +163,9 @@ export interface RaidMetamodel {
   /** Relationships connecting projected nodes. */
   readonly edges: readonly RaidEdgeData[];
 
+  /** Diagram-level edge routing mode ('manhattan', 'normal', 'smooth'). */
+  readonly routing?: AimRoutingMode;
+
   /** Additional diagram-level metadata. */
   readonly metadata?: Readonly<Record<string, unknown>>;
 }
@@ -172,6 +189,7 @@ export const AimSvgContract = {
   ATTR_TARGET: 'aim-target',
   ATTR_SOURCE_PORT: 'aim-source-port',
   ATTR_TARGET_PORT: 'aim-target-port',
+  ATTR_ROUTING: 'aim-routing',
   ATTR_BENDS: 'aim-bends',
 
   // Selectors for DOM queries
@@ -189,6 +207,13 @@ export interface HydrationOptions {
   /** If true, automatically executes Manhattan routing if bend points are missing. Default: true. */
   readonly autoRouteEdges?: boolean;
 
+  /**
+   * If true, infers docking ports (e.g. port-right, port-left) based on node geometry when ports
+   * are omitted in the SVG. When false (default), edges bind directly to node cells without ports,
+   * enabling dynamic Manhattan center-aiming routing. Default: false.
+   */
+  readonly inferPorts?: boolean;
+
   /** Default fallback dimensions when width/height are unspecified in SVG. */
   readonly defaultNodeSize?: { readonly width: number; readonly height: number };
 }
@@ -205,4 +230,7 @@ export interface SerializationOptions {
 
   /** Inject Cascais design token CSS variables into `<defs><style>`. Default: true. */
   readonly embedStyles?: boolean;
+
+  /** Optional diagram-level routing mode to serialize onto root `<svg>` tag. */
+  readonly routingMode?: AimRoutingMode;
 }