@dr2rai/raid-canvas 0.1.0 → 0.3.0

package/src/X6Shapes.ts

@@ -9,12 +9,15 @@
  * - Cascais Heraldry design tokens.
  */
 
-import { Graph, Node, Edge } from '@antv/x6';
+import { Graph, Shape, Node, Edge } from '@antv/x6';
 import type {
+  AimOntologyKind,
   AimEdgeKind,
+  AimRoutingMode,
   RaidNodeData,
   RaidEdgeData,
   OrthogonalPortId,
+  Bounds,
 } from './types.js';
 
 /**
@@ -105,9 +108,9 @@ export function registerAimShapes(): void {
   }
 
   // 1. AimUseCaseNode ('uc') — Ellipse with Net Gold border
-  Node.define({
+  Shape.Ellipse.define({
     shape: 'aim-uc',
-    inherit: 'ellipse',
+    overwrite: true,
     width: 140,
     height: 70,
     attrs: {
@@ -115,8 +118,6 @@ export function registerAimShapes(): void {
         fill: CascaisPalette.ChalkWhite,
         stroke: CascaisPalette.NetGold,
         strokeWidth: 2,
-        rx: 70,
-        ry: 35,
         class: 'aim-node aim-uc',
       },
       label: {
@@ -133,9 +134,9 @@ export function registerAimShapes(): void {
   });
 
   // 2. AimActivityNode ('act') — Rounded rectangle with Heraldic Green border
-  Node.define({
+  Shape.Rect.define({
     shape: 'aim-act',
-    inherit: 'rect',
+    overwrite: true,
     width: 150,
     height: 60,
     attrs: {
@@ -161,9 +162,9 @@ export function registerAimShapes(): void {
   });
 
   // 3. AimClassNode ('cls') — Compartmentalized class card
-  Node.define({
+  Shape.Rect.define({
     shape: 'aim-cls',
-    inherit: 'rect',
+    overwrite: true,
     width: 180,
     height: 100,
     markup: [
@@ -258,9 +259,9 @@ export function registerAimShapes(): void {
   });
 
   // 4. AimObjectNode ('obj') — Instance card with underlined title
-  Node.define({
+  Shape.Rect.define({
     shape: 'aim-obj',
-    inherit: 'rect',
+    overwrite: true,
     width: 160,
     height: 80,
     attrs: {
@@ -271,7 +272,7 @@ export function registerAimShapes(): void {
         class: 'aim-node aim-obj',
       },
       label: {
-        text: '<u>instance: Type</u>',
+        text: 'instance: Type',
         fill: CascaisPalette.TextPrimary,
         fontSize: 12,
         fontFamily: 'Inter, system-ui, -apple-system, sans-serif',
@@ -283,9 +284,9 @@ export function registerAimShapes(): void {
   });
 
   // 5. AimPersonNode ('per') — Person / Actor role card
-  Node.define({
+  Shape.Rect.define({
     shape: 'aim-per',
-    inherit: 'rect',
+    overwrite: true,
     width: 120,
     height: 70,
     attrs: {
@@ -311,9 +312,9 @@ export function registerAimShapes(): void {
   });
 
   // 6. AimEdge — Orthogonal Manhattan edge with rounded corners
-  Edge.define({
+  Shape.Edge.define({
     shape: 'aim-edge',
-    inherit: 'edge',
+    overwrite: true,
     router: {
       name: 'manhattan',
       args: {
@@ -457,6 +458,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 +493,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 } : {}),
@@ -509,8 +562,11 @@ function getEdgeStyling(kind: AimEdgeKind): Record<string, unknown> {
         strokeWidth: 1.5,
         strokeDasharray: '5,5',
         targetMarker: {
-          name: 'open',
-          size: 8,
+          name: 'block',
+          args: {
+            size: 8,
+            open: true,
+          },
         },
       };
 
@@ -573,3 +629,48 @@ function getEdgeStyling(kind: AimEdgeKind): Record<string, unknown> {
       };
   }
 }
+
+/**
+ * Returns default Cartesian bounds for an instantiated AOAIM archetype.
+ */
+export function getDefaultNodeBounds(
+  kind: AimOntologyKind | string,
+  x: number = 100,
+  y: number = 100,
+): Bounds {
+  switch (kind) {
+    case 'uc':
+      return { x, y, width: 140, height: 70 };
+    case 'act':
+      return { x, y, width: 150, height: 60 };
+    case 'cls':
+      return { x, y, width: 180, height: 110 };
+    case 'obj':
+      return { x, y, width: 160, height: 80 };
+    case 'per':
+      return { x, y, width: 120, height: 70 };
+    default:
+      return { x, y, width: 140, height: 60 };
+  }
+}
+
+/**
+ * Returns a canonical default display name for an instantiated AOAIM archetype.
+ */
+export function getDefaultNodeName(kind: AimOntologyKind | string): string {
+  switch (kind) {
+    case 'uc':
+      return 'New UseCase';
+    case 'act':
+      return 'New Activity';
+    case 'cls':
+      return 'NewClass';
+    case 'obj':
+      return 'new Object';
+    case 'per':
+      return 'Actor';
+    default:
+      return 'Entity';
+  }
+}
+

package/src/index.ts

@@ -7,12 +7,15 @@
  * - 4-way orthogonal ports and Manhattan router integration.
  * - Cascais Heraldry design tokens and theme styling.
  * - Bidirectional RaiBridge for hydrating from and serializing to the aim-* SVG contract.
+ * - Anti-entropy semantic connection validation and wiring rules.
+ * - Reusable <RaidCanvas /> React component with Dnd and imperative control handle.
  */
 
 // Core Metamodel & SVG Contract Types
 export {
   AimSvgContract,
   type AimOntologyKind,
+  type AimRoutingMode,
   type AimEdgeKind,
   type Point,
   type SvgBendPoint,
@@ -33,7 +36,29 @@ export {
   configureAimGraph,
   createAimNode,
   createAimEdge,
+  applyEdgeRouting,
+  getDefaultNodeBounds,
+  getDefaultNodeName,
 } from './X6Shapes.js';
 
+// Anti-Entropy Semantic Connection Rules
+export {
+  SEMANTIC_RULES_MATRIX,
+  validateSemanticConnection,
+  getSemanticEdgeKind,
+  getSemanticEdgeStereotype,
+  getSemanticRuleDescription,
+  getAvailableStereotypes,
+  type SemanticRule,
+  type StereotypeOption,
+} from './semanticRules.js';
+
 // Bidirectional SVG <-> X6 Synchronization Bridge
 export { RaiBridge } from './RaiBridge.js';
+
+// Reusable React Canvas Component & Ref Handle
+export {
+  RaidCanvas,
+  type RaidCanvasProps,
+  type RaidCanvasHandle,
+} from './RaidCanvas.js';

package/src/semanticRules.ts

@@ -0,0 +1,237 @@
+/**
+ * @file semanticRules.ts
+ * @description Anti-entropy semantic connection validation and wiring rules
+ * for the AOAIM (Activity-Object-AI Model) graphical modeling contract.
+ *
+ * Enforces ontological integrity during edge creation:
+ * - 'per' -> 'uc'  : 'association' («initiates», «owns» [0..1], «participates» [0..*])
+ * - 'per' -> 'act' : 'association' («executes»)
+ * - 'uc'  -> 'uc'  : 'dependency'  («includes», «extends», «dependsOn»)
+ * - 'uc'  -> 'act' : 'dependency'  («includes»)
+ * - 'act' -> 'act' : 'association' («sequence» / process flow)
+ * - 'cls' -> 'cls' : 'association' («relatesTo»), 'generalization', 'composition', 'aggregation'
+ * - 'cls' -> 'obj' : 'dependency'  («instantiates»)
+ * - 'obj' -> 'obj' : 'association' («link»)
+ */
+
+import type { AimOntologyKind, AimEdgeKind } from './types.js';
+
+export interface StereotypeOption {
+  readonly stereotype: string;
+  readonly defaultCardinality?: string;
+  readonly description: string;
+}
+
+export interface SemanticRule {
+  readonly valid: boolean;
+  readonly defaultEdgeKind: AimEdgeKind;
+  readonly defaultStereotype: string;
+  readonly defaultCardinality?: string;
+  readonly availableStereotypes: readonly StereotypeOption[];
+  readonly description: string;
+}
+
+/**
+ * Ontological connection rules matrix.
+ * Key: `${sourceKind}->${targetKind}`
+ */
+export const SEMANTIC_RULES_MATRIX: Readonly<Record<string, SemanticRule>> = {
+  'per->uc': {
+    valid: true,
+    defaultEdgeKind: 'association',
+    defaultStereotype: '«initiates»',
+    description: 'Actor initiates, owns, or participates in UseCase',
+    availableStereotypes: [
+      {
+        stereotype: '«initiates»',
+        defaultCardinality: '1',
+        description: 'Initiating role triggering the UseCase flow',
+      },
+      {
+        stereotype: '«owns»',
+        defaultCardinality: '0..1',
+        description: 'Ownership relationship representing responsible party (cardinality 0..1)',
+      },
+      {
+        stereotype: '«participates»',
+        defaultCardinality: '0..*',
+        description: 'Participating role supporting the UseCase execution (cardinality 0..*)',
+      },
+    ],
+  },
+  'per->act': {
+    valid: true,
+    defaultEdgeKind: 'association',
+    defaultStereotype: '«executes»',
+    description: 'Actor directly performs or executes Activity',
+    availableStereotypes: [
+      {
+        stereotype: '«executes»',
+        description: 'Actor performs this process step',
+      },
+      {
+        stereotype: '«approves»',
+        description: 'Actor reviews or approves activity completion',
+      },
+    ],
+  },
+  'uc->uc': {
+    valid: true,
+    defaultEdgeKind: 'dependency',
+    defaultStereotype: '«includes»',
+    description: 'UseCase includes or extends sub-UseCase',
+    availableStereotypes: [
+      {
+        stereotype: '«includes»',
+        description: 'Mandatory sub-flow inclusion dependency',
+      },
+      {
+        stereotype: '«extends»',
+        description: 'Optional conditional extension point',
+      },
+      {
+        stereotype: '«dependsOn»',
+        description: 'Prerequisite functional dependency',
+      },
+    ],
+  },
+  'uc->act': {
+    valid: true,
+    defaultEdgeKind: 'dependency',
+    defaultStereotype: '«includes»',
+    description: 'UseCase elaborates downflow process Activity',
+    availableStereotypes: [
+      {
+        stereotype: '«includes»',
+        description: 'Process activity required by UseCase',
+      },
+      {
+        stereotype: '«triggers»',
+        description: 'UseCase execution triggers activity',
+      },
+    ],
+  },
+  'act->act': {
+    valid: true,
+    defaultEdgeKind: 'association',
+    defaultStereotype: '«sequence»',
+    description: 'Activity transitions to next process step',
+    availableStereotypes: [
+      {
+        stereotype: '«sequence»',
+        description: 'Sequential process transition',
+      },
+      {
+        stereotype: '«branch»',
+        description: 'Conditional decision branch',
+      },
+    ],
+  },
+  'cls->cls': {
+    valid: true,
+    defaultEdgeKind: 'association',
+    defaultStereotype: '«relatesTo»',
+    description: 'Domain structural relationship between Classes',
+    availableStereotypes: [
+      {
+        stereotype: '«relatesTo»',
+        defaultCardinality: '1..*',
+        description: 'General domain association',
+      },
+      {
+        stereotype: '«generalization»',
+        description: 'Inheritance classification (subclass is-a superclass)',
+      },
+      {
+        stereotype: '«composition»',
+        defaultCardinality: '1',
+        description: 'Composite whole-part lifecycle binding',
+      },
+      {
+        stereotype: '«aggregation»',
+        defaultCardinality: '0..*',
+        description: 'Shared aggregation relationship',
+      },
+    ],
+  },
+  'cls->obj': {
+    valid: true,
+    defaultEdgeKind: 'dependency',
+    defaultStereotype: '«instantiates»',
+    description: 'Class specifies runtime Object instance',
+    availableStereotypes: [
+      {
+        stereotype: '«instantiates»',
+        description: 'Class defines schema for runtime instance',
+      },
+    ],
+  },
+  'obj->obj': {
+    valid: true,
+    defaultEdgeKind: 'association',
+    defaultStereotype: '«link»',
+    description: 'Runtime communication link between Objects',
+    availableStereotypes: [
+      {
+        stereotype: '«link»',
+        description: 'Runtime object collaboration message link',
+      },
+    ],
+  },
+};
+
+/**
+ * Validates whether an edge connection between source and target archetypes is ontologically allowed.
+ */
+export function validateSemanticConnection(
+  sourceKind: AimOntologyKind | string,
+  targetKind: AimOntologyKind | string,
+): boolean {
+  if (!sourceKind || !targetKind) return false;
+  const key = `${sourceKind}->${targetKind}`;
+  return SEMANTIC_RULES_MATRIX[key]?.valid ?? false;
+}
+
+/**
+ * Determines the canonical default relationship edge kind for a connected pair.
+ */
+export function getSemanticEdgeKind(
+  sourceKind: AimOntologyKind | string,
+  targetKind: AimOntologyKind | string,
+): AimEdgeKind {
+  const key = `${sourceKind}->${targetKind}`;
+  return SEMANTIC_RULES_MATRIX[key]?.defaultEdgeKind ?? 'association';
+}
+
+/**
+ * Determines the canonical default stereotype annotation for a connected pair.
+ */
+export function getSemanticEdgeStereotype(
+  sourceKind: AimOntologyKind | string,
+  targetKind: AimOntologyKind | string,
+): string {
+  const key = `${sourceKind}->${targetKind}`;
+  return SEMANTIC_RULES_MATRIX[key]?.defaultStereotype ?? '';
+}
+
+/**
+ * Returns available ontological stereotypes and their default cardinalities for a pair.
+ */
+export function getAvailableStereotypes(
+  sourceKind: AimOntologyKind | string,
+  targetKind: AimOntologyKind | string,
+): readonly StereotypeOption[] {
+  const key = `${sourceKind}->${targetKind}`;
+  return SEMANTIC_RULES_MATRIX[key]?.availableStereotypes ?? [];
+}
+
+/**
+ * Returns a human-readable description explaining the ontological relationship.
+ */
+export function getSemanticRuleDescription(
+  sourceKind: AimOntologyKind | string,
+  targetKind: AimOntologyKind | string,
+): string {
+  const key = `${sourceKind}->${targetKind}`;
+  return SEMANTIC_RULES_MATRIX[key]?.description ?? 'Invalid ontological connection';
+}

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,6 +134,9 @@ 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[];
 }
@@ -172,6 +183,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