@dr2rai/raid-canvas 0.1.0

package/src/styles/aoaim-theme.css

@@ -0,0 +1,205 @@
+/**
+ * aoaim-theme.css
+ * Semantic CSS design tokens and component styling for the RaidCanvas AOAIM visual modeler.
+ * Adheres to the Cascais Heraldry palette and the aim-* ontological contract.
+ */
+
+:root {
+  /* Cascais Heraldry Design Tokens */
+  --aim-net-gold: #F59E0B;
+  --aim-heraldic-green: #10B981;
+  --aim-warm-graphite: #1F2937;
+  --aim-graphite-muted: #4B5563;
+  --aim-silver-line: #E5E7EB;
+  --aim-silver-line-dark: #D1D5DB;
+  --aim-chalk-white: #FFFFFF;
+  --aim-canvas-cream: #F8FAFC;
+  --aim-accent-blue: #3B82F6;
+  --aim-danger-crimson: #EF4444;
+
+  /* Typography */
+  --aim-font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  --aim-font-mono: 'JetBrains Mono', 'Menlo', 'Courier New', monospace;
+
+  /* Node Dimensions & Radii */
+  --aim-radius-act: 12px;
+  --aim-radius-card: 6px;
+  --aim-radius-round: 9999px;
+
+  /* Shadows */
+  --aim-shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
+  --aim-shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06);
+  --aim-shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05);
+  --aim-shadow-glow-gold: 0 0 0 3px rgba(245, 158, 11, 0.35);
+  --aim-shadow-glow-green: 0 0 0 3px rgba(16, 185, 129, 0.35);
+  --aim-shadow-glow-blue: 0 0 0 3px rgba(59, 130, 246, 0.35);
+}
+
+/* Canvas Container */
+.aim-canvas {
+  background-color: var(--aim-canvas-cream);
+  font-family: var(--aim-font-family);
+  user-select: none;
+  -webkit-user-select: none;
+}
+
+/* Base Ontological Node */
+.aim-node {
+  cursor: pointer;
+  transition: transform 0.1s ease, filter 0.15s ease;
+}
+
+.aim-node:hover {
+  filter: drop-shadow(0 4px 6px rgba(0, 0, 0, 0.08));
+}
+
+.aim-node.aim-selected {
+  outline: none;
+  filter: drop-shadow(0 0 8px rgba(59, 130, 246, 0.4));
+}
+
+/* 1. UseCase Nodes ('uc') */
+.aim-node[aim-uc],
+.aim-node[aim-kind="uc"],
+.aim-uc {
+  fill: var(--aim-chalk-white);
+  stroke: var(--aim-net-gold);
+  stroke-width: 2px;
+}
+
+.aim-node[aim-uc]:hover,
+.aim-node[aim-kind="uc"]:hover {
+  filter: drop-shadow(0 0 6px rgba(245, 158, 11, 0.4));
+}
+
+/* 2. Activity Nodes ('act') */
+.aim-node[aim-act],
+.aim-node[aim-kind="act"],
+.aim-act {
+  fill: var(--aim-canvas-cream);
+  stroke: var(--aim-heraldic-green);
+  stroke-width: 2px;
+  rx: var(--aim-radius-act);
+  ry: var(--aim-radius-act);
+}
+
+.aim-node[aim-act]:hover,
+.aim-node[aim-kind="act"]:hover {
+  filter: drop-shadow(0 0 6px rgba(16, 185, 129, 0.4));
+}
+
+/* 3. Class Specification Nodes ('cls') */
+.aim-node[aim-cls],
+.aim-node[aim-kind="cls"],
+.aim-cls {
+  fill: var(--aim-chalk-white);
+  stroke: var(--aim-warm-graphite);
+  stroke-width: 1.5px;
+}
+
+.aim-node[aim-cls] .aim-cls-header {
+  fill: var(--aim-canvas-cream);
+}
+
+.aim-node[aim-cls] .aim-cls-divider {
+  stroke: var(--aim-silver-line);
+  stroke-width: 1px;
+}
+
+/* 4. Object Instance Nodes ('obj') */
+.aim-node[aim-obj],
+.aim-node[aim-kind="obj"],
+.aim-obj {
+  fill: var(--aim-chalk-white);
+  stroke: var(--aim-silver-line-dark);
+  stroke-width: 1.5px;
+}
+
+/* 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);
+}
+
+.aim-node[aim-per][aim-role="initiating"] {
+  stroke: var(--aim-net-gold);
+  stroke-width: 2px;
+}
+
+/* Relationship Edges */
+.aim-edge {
+  fill: none;
+  stroke: var(--aim-warm-graphite);
+  stroke-width: 1.5px;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+  transition: stroke 0.15s ease, stroke-width 0.15s ease;
+}
+
+.aim-edge:hover {
+  stroke: var(--aim-accent-blue);
+  stroke-width: 2.5px;
+  cursor: pointer;
+}
+
+.aim-edge[aim-edge-kind="dependency"] {
+  stroke-dasharray: 5, 5;
+}
+
+.aim-edge[aim-edge-kind="realization"] {
+  stroke-dasharray: 6, 4;
+}
+
+/* Orthogonal Port Docking Magnets */
+.aim-port-body {
+  fill: var(--aim-chalk-white);
+  stroke: var(--aim-warm-graphite);
+  stroke-width: 1.5px;
+  transition: transform 0.1s ease, fill 0.1s ease;
+}
+
+.aim-port-body:hover {
+  fill: var(--aim-net-gold);
+  stroke: var(--aim-warm-graphite);
+  transform: scale(1.4);
+  cursor: crosshair;
+}
+
+/* User-Editable Edge Bend Point Vertices */
+.x6-edge-tool-vertex {
+  fill: var(--aim-chalk-white);
+  stroke: var(--aim-accent-blue);
+  stroke-width: 2px;
+  cursor: move;
+}
+
+.x6-edge-tool-vertex:hover {
+  fill: var(--aim-accent-blue);
+  transform: scale(1.3);
+}
+
+/* Dark Mode Overrides */
+@media (prefers-color-scheme: dark) {
+  :root {
+    --aim-canvas-cream: #0F172A;
+    --aim-chalk-white: #1E293B;
+    --aim-warm-graphite: #94A3B8;
+    --aim-silver-line: #334155;
+    --aim-silver-line-dark: #475569;
+    --aim-text-primary: #F8FAFC;
+    --aim-text-secondary: #94A3B8;
+  }
+
+  .aim-canvas {
+    background-color: var(--aim-canvas-cream);
+  }
+
+  .aim-edge {
+    stroke: var(--aim-warm-graphite);
+  }
+}

package/src/types.ts

@@ -0,0 +1,208 @@
+/**
+ * @file types.ts
+ * @description Core ontological types, metamodel contracts, and SVG attributes
+ * for the RaidCanvas AOAIM visual modeler.
+ *
+ * Honors Alan Kay's vision of living, reactive object systems and Rainer Burkhardt's
+ * C++ GrafObj graphical object hierarchies.
+ */
+
+/**
+ * Canonical AOAIM (Activity-Object-AI Model) entity archetypes.
+ *
+ * - 'uc'  : UseCase (elliptical boundary, Cascais Net Gold accent)
+ * - 'act' : Activity (rounded rectangle process step, Heraldic Green accent)
+ * - 'cls' : Class (compartmentalized class specification card)
+ * - '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';
+
+/**
+ * Ontological relationship classifications in AOAIM.
+ */
+export type AimEdgeKind =
+  | 'association'
+  | 'dependency'
+  | 'generalization'
+  | 'realization'
+  | 'aggregation'
+  | 'composition';
+
+/**
+ * 2D Cartesian coordinate pair for geometry and Manhattan orthogonal routing.
+ */
+export interface Point {
+  readonly x: number;
+  readonly y: number;
+}
+
+/**
+ * Single bend point (vertex) along an orthogonal Manhattan edge path.
+ */
+export interface SvgBendPoint {
+  readonly x: number;
+  readonly y: number;
+}
+
+/**
+ * 2D Bounding box for nodes and frames.
+ */
+export interface Bounds {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * Canonical port identifiers for 4-way orthogonal docking.
+ */
+export type OrthogonalPortId = 'port-top' | 'port-right' | 'port-bottom' | 'port-left';
+
+/**
+ * Metadata carried by an ontological node inside AntV X6.
+ */
+export interface RaidNodeData {
+  /** Unique entity identifier in the metamodel (e.g., 'SignContract_UC'). */
+  readonly id: string;
+
+  /** Ontological kind of the node. */
+  readonly kind: AimOntologyKind;
+
+  /** Display label presented on the canvas. */
+  readonly displayName: string;
+
+  /** Optional ontological stereotype (e.g., '«initiates»', '«executes»'). */
+  readonly stereotype?: string;
+
+  /** Subtitle, frame, or namespace tag. */
+  readonly namespace?: string;
+
+  /** For 'cls' / 'obj': list of attribute or field declarations. */
+  readonly attributes?: readonly string[];
+
+  /** For 'cls': list of method or operation declarations. */
+  readonly methods?: readonly string[];
+
+  /** Spatial bounds of the node. */
+  readonly bounds: Bounds;
+
+  /** Custom extension properties passed from or serialized to .raid manifests. */
+  readonly properties?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Metadata carried by an ontological edge inside AntV X6.
+ */
+export interface RaidEdgeData {
+  /** Unique edge identifier. */
+  readonly id: string;
+
+  /** Ontological relationship type. */
+  readonly kind: AimEdgeKind;
+
+  /** Identifier of the source node. */
+  readonly sourceId: string;
+
+  /** Identifier of the target node. */
+  readonly targetId: string;
+
+  /** Optional docking port on source node. */
+  readonly sourcePort?: OrthogonalPortId | string;
+
+  /** Optional docking port on target node. */
+  readonly targetPort?: OrthogonalPortId | string;
+
+  /** Optional edge label text. */
+  readonly label?: string;
+
+  /** Optional edge stereotype annotation (e.g., '«DependsOn»'). */
+  readonly stereotype?: string;
+
+  /** Multiplicity / Cardinality at the source end (e.g., '1', '0..*'). */
+  readonly sourceCardinality?: string;
+
+  /** Multiplicity / Cardinality at the target end (e.g., '0..1', '*'). */
+  readonly targetCardinality?: string;
+
+  /** User-editable or router-computed Manhattan bend points. */
+  readonly bendPoints: readonly SvgBendPoint[];
+}
+
+/**
+ * Full in-memory metamodel representation corresponding to a `.raid` manifest.
+ */
+export interface RaidMetamodel {
+  /** Diagram identifier (e.g., 'SignContract_UCD'). */
+  readonly diagramId: string;
+
+  /** Optional human-readable title. */
+  readonly title?: string;
+
+  /** Archetype classification (e.g., 'OneUseCaseDiagram', 'ClassDiagram', 'ActivityDiagram'). */
+  readonly archetype: string;
+
+  /** Entity nodes projected in the diagram. */
+  readonly nodes: readonly RaidNodeData[];
+
+  /** Relationships connecting projected nodes. */
+  readonly edges: readonly RaidEdgeData[];
+
+  /** Additional diagram-level metadata. */
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Contractual SVG attribute names adhering to the 'aim-*' standard.
+ */
+export const AimSvgContract = {
+  // Node marking & attributes
+  ATTR_NODE: 'aim-node',
+  ATTR_ID: 'aim-id',
+  ATTR_KIND: 'aim-kind',
+  ATTR_DISPLAY_NAME: 'aim-display-name',
+  ATTR_STEREOTYPE: 'aim-stereotype',
+  ATTR_NAMESPACE: 'aim-namespace',
+
+  // Edge marking & attributes
+  ATTR_EDGE: 'aim-edge',
+  ATTR_EDGE_KIND: 'aim-edge-kind',
+  ATTR_SOURCE: 'aim-source',
+  ATTR_TARGET: 'aim-target',
+  ATTR_SOURCE_PORT: 'aim-source-port',
+  ATTR_TARGET_PORT: 'aim-target-port',
+  ATTR_BENDS: 'aim-bends',
+
+  // Selectors for DOM queries
+  SELECTOR_NODE: '[aim-node], [data-node], g[aim-kind]',
+  SELECTOR_EDGE: '[aim-edge], path[aim-edge-kind]',
+} as const;
+
+/**
+ * Options for hydrating an AntV X6 graph from an SVG document.
+ */
+export interface HydrationOptions {
+  /** If true, clears any existing graph elements before populating. Default: true. */
+  readonly clearGraph?: boolean;
+
+  /** If true, automatically executes Manhattan routing if bend points are missing. Default: true. */
+  readonly autoRouteEdges?: boolean;
+
+  /** Default fallback dimensions when width/height are unspecified in SVG. */
+  readonly defaultNodeSize?: { readonly width: number; readonly height: number };
+}
+
+/**
+ * Options for serializing an AntV X6 graph to an SVG document.
+ */
+export interface SerializationOptions {
+  /** Base SVG template to inject updated coordinates and bend points into. */
+  readonly baseSvg?: string;
+
+  /** Pretty-print XML output with indentation. Default: true. */
+  readonly format?: boolean;
+
+  /** Inject Cascais design token CSS variables into `<defs><style>`. Default: true. */
+  readonly embedStyles?: boolean;
+}