@graph-knowledge/api 0.1.0

package/src/lib/types/element-input-types.d.ts

@@ -0,0 +1,237 @@
+/**
+ * Common properties for all element inputs.
+ */
+export interface BaseElementInput {
+    /** X position on canvas */
+    x: number;
+    /** Y position on canvas */
+    y: number;
+    /** Element width (uses default if not specified) */
+    width?: number;
+    /** Element height (uses default if not specified) */
+    height?: number;
+    /** Rotation in degrees [0, 360) */
+    rotation?: number;
+    /** Whether this element links to another node */
+    isLink?: boolean;
+    /** Target node ID when isLink is true */
+    linkTarget?: string;
+}
+/**
+ * Input for creating a rectangle element.
+ */
+export interface RectangleInput extends BaseElementInput {
+    type: "rectangle";
+    /** Fill color (hex, e.g., "#FF5733") */
+    fillColor?: string;
+    /** Stroke color (hex) */
+    strokeColor?: string;
+    /** Stroke width in pixels */
+    strokeWidth?: number;
+    /** Corner radius for rounded rectangles */
+    cornerRadius?: number;
+}
+/**
+ * Input for creating a text element.
+ */
+export interface TextInput extends BaseElementInput {
+    type: "text";
+    /** Text content (required for text elements) */
+    text: string;
+    /** Font family */
+    fontFamily?: string;
+    /** Font size in pixels */
+    fontSize?: number;
+    /** Font weight (100-900) */
+    fontWeight?: number;
+    /** Text color (hex) */
+    fillColor?: string;
+    /** Text alignment */
+    textAlign?: "left" | "center" | "right";
+    /** Line height multiplier */
+    lineHeight?: number;
+}
+/**
+ * Anchor points for connectors.
+ * These match the snap geometry labels used by the graph editor.
+ */
+export type ConnectorAnchor = "edge-top" | "edge-right" | "edge-bottom" | "edge-left" | "center";
+/**
+ * Line styles for connectors.
+ */
+export type LineStyle = "solid" | "dashed" | "dotted";
+/**
+ * Marker types for connector ends.
+ */
+export type MarkerType = "none" | "arrow" | "diamond" | "circle";
+/**
+ * Input for creating a connector element.
+ * Note: Connectors don't use x/y/width/height - their position is determined by connected elements.
+ */
+export interface ConnectorInput {
+    type: "connector";
+    /** X position (ignored for connectors, defaults to 0) */
+    x?: number;
+    /** Y position (ignored for connectors, defaults to 0) */
+    y?: number;
+    /** Width (ignored for connectors, defaults to 0) */
+    width?: number;
+    /** Height (ignored for connectors, defaults to 0) */
+    height?: number;
+    /** Rotation (ignored for connectors) */
+    rotation?: number;
+    /** Source element ID (required) */
+    startElementId: string;
+    /** Anchor point on source element */
+    startAnchor?: ConnectorAnchor;
+    /** Target element ID (required) */
+    endElementId: string;
+    /** Anchor point on target element */
+    endAnchor?: ConnectorAnchor;
+    /** Line color (hex) */
+    strokeColor?: string;
+    /** Line width in pixels */
+    strokeWidth?: number;
+    /** Line style */
+    lineStyle?: LineStyle;
+    /** Marker at start of line */
+    startMarker?: MarkerType;
+    /** Marker at end of line */
+    endMarker?: MarkerType;
+    /** Optional label on connector */
+    label?: string;
+    /** Whether this element links to another node */
+    isLink?: boolean;
+    /** Target node ID when isLink is true */
+    linkTarget?: string;
+}
+/**
+ * Input for creating a UML class element.
+ */
+export interface UmlClassInput extends BaseElementInput {
+    type: "uml-class";
+    /** Class name */
+    name?: string;
+    /** Attributes (one per line, e.g., "+ attribute: Type") */
+    attributes?: string;
+    /** Methods (one per line, e.g., "+ method(): void") */
+    methods?: string;
+    /** Stereotype (e.g., "entity", "service") */
+    stereotype?: string;
+    /** Fill color (hex) */
+    fillColor?: string;
+    /** Stroke color (hex) */
+    strokeColor?: string;
+    /** Stroke width in pixels */
+    strokeWidth?: number;
+}
+/**
+ * Input for creating a UML interface element.
+ */
+export interface UmlInterfaceInput extends BaseElementInput {
+    type: "uml-interface";
+    /** Interface name */
+    name?: string;
+    /** Methods (one per line) */
+    methods?: string;
+    /** Fill color (hex) */
+    fillColor?: string;
+    /** Stroke color (hex) */
+    strokeColor?: string;
+    /** Stroke width in pixels */
+    strokeWidth?: number;
+}
+/**
+ * Input for creating a UML component element.
+ */
+export interface UmlComponentInput extends BaseElementInput {
+    type: "uml-component";
+    /** Component name */
+    name?: string;
+    /** Stereotype (e.g., "service", "middleware") */
+    stereotype?: string;
+    /** Fill color (hex) */
+    fillColor?: string;
+    /** Stroke color (hex) */
+    strokeColor?: string;
+    /** Stroke width in pixels */
+    strokeWidth?: number;
+}
+/**
+ * Input for creating a UML package element.
+ */
+export interface UmlPackageInput extends BaseElementInput {
+    type: "uml-package";
+    /** Package name */
+    name?: string;
+    /** Fill color (hex) */
+    fillColor?: string;
+    /** Stroke color (hex) */
+    strokeColor?: string;
+    /** Stroke width in pixels */
+    strokeWidth?: number;
+}
+/**
+ * Input for creating a UML artifact element.
+ */
+export interface UmlArtifactInput extends BaseElementInput {
+    type: "uml-artifact";
+    /** Artifact name */
+    name?: string;
+    /** Stereotype (e.g., "document", "source") */
+    stereotype?: string;
+    /** Fill color (hex) */
+    fillColor?: string;
+    /** Stroke color (hex) */
+    strokeColor?: string;
+    /** Stroke width in pixels */
+    strokeWidth?: number;
+}
+/**
+ * Input for creating a UML note element.
+ */
+export interface UmlNoteInput extends BaseElementInput {
+    type: "uml-note";
+    /** Note text */
+    text?: string;
+    /** Fill color (hex) */
+    fillColor?: string;
+    /** Stroke color (hex) */
+    strokeColor?: string;
+    /** Stroke width in pixels */
+    strokeWidth?: number;
+}
+/**
+ * Input for creating a custom shape element.
+ */
+export interface CustomShapeInput extends BaseElementInput {
+    type: `custom:${string}`;
+    /** Custom shape definition ID (required) */
+    customShapeId: string;
+    /** Fill color (hex) */
+    fillColor?: string;
+    /** Stroke color (hex) */
+    strokeColor?: string;
+    /** Stroke width in pixels */
+    strokeWidth?: number;
+    /** Additional custom properties */
+    [key: string]: unknown;
+}
+/**
+ * Union of all element input types.
+ */
+export type AnyElementInput = RectangleInput | TextInput | ConnectorInput | UmlClassInput | UmlInterfaceInput | UmlComponentInput | UmlPackageInput | UmlArtifactInput | UmlNoteInput | CustomShapeInput;
+/**
+ * Input for updating an existing element.
+ */
+export interface UpdateElementInput {
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    rotation?: number;
+    /** Shape-specific properties to update */
+    properties?: Record<string, unknown>;
+    isLink?: boolean;
+    linkTarget?: string;
+}

package/src/lib/types/element-input-types.js

@@ -0,0 +1,3 @@
+// ============================================================================
+// Base Element Input
+// ============================================================================

package/src/lib/utils/link-level-manager.d.ts

@@ -0,0 +1,66 @@
+import { GraphNode } from "@graph-knowledge/domain";
+/**
+ * Represents a change to a node's level.
+ */
+export interface LevelChange {
+    nodeId: string;
+    level: number | undefined;
+}
+/**
+ * Link state for calculating level changes.
+ */
+export interface LinkState {
+    isLink?: boolean;
+    linkTarget?: string;
+}
+/**
+ * Pure utility for managing node level calculations.
+ * Levels represent distance from root node in the graph.
+ * - Root node: level = 0
+ * - Linked nodes: level = source.level + 1 (minimum if multiple incoming links)
+ * - Orphan nodes: level = undefined
+ *
+ * Extracted from web app's LinkManagerService for use in headless API.
+ */
+export declare class LinkLevelManager {
+    /**
+     * Called when a link is created (element.isLink set to true with linkTarget).
+     * @param sourceNodeId The node containing the linking element
+     * @param targetNodeId The node being linked to
+     * @param nodes Current state of all nodes
+     * @returns Array of level changes to apply
+     */
+    onLinkCreated(sourceNodeId: string, targetNodeId: string, nodes: GraphNode[]): LevelChange[];
+    /**
+     * Called when a link is removed (element.isLink set to false or linkTarget cleared).
+     * @param targetNodeId The node that was being linked to
+     * @param nodes Current state of all nodes (should already have the link removed)
+     * @returns Array of level changes to apply
+     */
+    onLinkRemoved(targetNodeId: string, nodes: GraphNode[]): LevelChange[];
+    /**
+     * Calculates level changes based on before/after link state.
+     * This is a convenience method that determines the appropriate action.
+     * @param sourceNodeId The node containing the element
+     * @param elementId The element being modified
+     * @param before Previous link state
+     * @param after New link state
+     * @param nodes Current state of all nodes (with the change already applied)
+     * @returns Array of level changes to apply
+     */
+    calculateLevelChanges(sourceNodeId: string, elementId: string, before: LinkState, after: LinkState, nodes: GraphNode[]): LevelChange[];
+    /**
+     * Find all elements across all nodes that link to the target node.
+     */
+    private findIncomingLinks;
+    /**
+     * Calculate the minimum level from a set of incoming links.
+     * @param incomingLinks The incoming links with their source levels
+     * @param pendingChanges Pending level changes to consider
+     */
+    private calculateMinLevel;
+    /**
+     * Recursively update levels for nodes that the changed node links to.
+     */
+    private cascadeUpdates;
+}

package/src/lib/utils/link-level-manager.js

@@ -0,0 +1,200 @@
+/**
+ * Pure utility for managing node level calculations.
+ * Levels represent distance from root node in the graph.
+ * - Root node: level = 0
+ * - Linked nodes: level = source.level + 1 (minimum if multiple incoming links)
+ * - Orphan nodes: level = undefined
+ *
+ * Extracted from web app's LinkManagerService for use in headless API.
+ */
+export class LinkLevelManager {
+    /**
+     * Called when a link is created (element.isLink set to true with linkTarget).
+     * @param sourceNodeId The node containing the linking element
+     * @param targetNodeId The node being linked to
+     * @param nodes Current state of all nodes
+     * @returns Array of level changes to apply
+     */
+    onLinkCreated(sourceNodeId, targetNodeId, nodes) {
+        const changes = [];
+        const sourceNode = nodes.find((n) => n.id === sourceNodeId);
+        const targetNode = nodes.find((n) => n.id === targetNodeId);
+        if (!sourceNode || !targetNode) {
+            return changes;
+        }
+        // Source must have a defined level to propagate
+        if (sourceNode.level === undefined) {
+            return changes;
+        }
+        const proposedLevel = sourceNode.level + 1;
+        // Only update if target has no level or proposed is better (lower)
+        if (targetNode.level === undefined ||
+            proposedLevel < targetNode.level) {
+            changes.push({ nodeId: targetNodeId, level: proposedLevel });
+            // Cascade to nodes that targetNode links to
+            this.cascadeUpdates(targetNodeId, proposedLevel, nodes, changes);
+        }
+        return changes;
+    }
+    /**
+     * Called when a link is removed (element.isLink set to false or linkTarget cleared).
+     * @param targetNodeId The node that was being linked to
+     * @param nodes Current state of all nodes (should already have the link removed)
+     * @returns Array of level changes to apply
+     */
+    onLinkRemoved(targetNodeId, nodes) {
+        const changes = [];
+        const targetNode = nodes.find((n) => n.id === targetNodeId);
+        if (!targetNode) {
+            return changes;
+        }
+        // Don't modify root node level
+        if (targetNode.level === 0) {
+            return changes;
+        }
+        // If already undefined, nothing to do
+        if (targetNode.level === undefined) {
+            return changes;
+        }
+        // Find all remaining incoming links to this node
+        const incomingLinks = this.findIncomingLinks(targetNodeId, nodes);
+        if (incomingLinks.length === 0) {
+            // No incoming links - node becomes orphan
+            changes.push({ nodeId: targetNodeId, level: undefined });
+            // Cascade: downstream nodes may also become orphans
+            this.cascadeUpdates(targetNodeId, undefined, nodes, changes);
+        }
+        else {
+            // Recalculate from remaining incoming links
+            const newLevel = this.calculateMinLevel(incomingLinks);
+            if (newLevel !== targetNode.level) {
+                changes.push({ nodeId: targetNodeId, level: newLevel });
+                // Cascade the change
+                this.cascadeUpdates(targetNodeId, newLevel, nodes, changes);
+            }
+        }
+        return changes;
+    }
+    /**
+     * Calculates level changes based on before/after link state.
+     * This is a convenience method that determines the appropriate action.
+     * @param sourceNodeId The node containing the element
+     * @param elementId The element being modified
+     * @param before Previous link state
+     * @param after New link state
+     * @param nodes Current state of all nodes (with the change already applied)
+     * @returns Array of level changes to apply
+     */
+    calculateLevelChanges(sourceNodeId, elementId, before, after, nodes) {
+        const wasLink = before.isLink && before.linkTarget;
+        const isLink = after.isLink && after.linkTarget;
+        // Case 1: Link created
+        if (!wasLink && isLink) {
+            return this.onLinkCreated(sourceNodeId, after.linkTarget, nodes);
+        }
+        // Case 2: Link removed
+        if (wasLink && !isLink) {
+            return this.onLinkRemoved(before.linkTarget, nodes);
+        }
+        // Case 3: Link target changed
+        if (wasLink && isLink && before.linkTarget !== after.linkTarget) {
+            const removedChanges = this.onLinkRemoved(before.linkTarget, nodes);
+            const createdChanges = this.onLinkCreated(sourceNodeId, after.linkTarget, nodes);
+            // Merge changes, avoiding duplicates
+            const merged = new Map();
+            for (const change of [...removedChanges, ...createdChanges]) {
+                merged.set(change.nodeId, change);
+            }
+            return Array.from(merged.values());
+        }
+        // No link change
+        return [];
+    }
+    /**
+     * Find all elements across all nodes that link to the target node.
+     */
+    findIncomingLinks(targetNodeId, nodes) {
+        const incoming = [];
+        for (const node of nodes) {
+            if (!node.elements)
+                continue;
+            for (const element of node.elements) {
+                if (element.isLink && element.linkTarget === targetNodeId) {
+                    incoming.push({
+                        sourceNodeId: node.id,
+                        sourceLevel: node.level
+                    });
+                }
+            }
+        }
+        return incoming;
+    }
+    /**
+     * Calculate the minimum level from a set of incoming links.
+     * @param incomingLinks The incoming links with their source levels
+     * @param pendingChanges Pending level changes to consider
+     */
+    calculateMinLevel(incomingLinks, pendingChanges = []) {
+        let minLevel = undefined;
+        // Create a map of pending changes for quick lookup
+        const changeMap = new Map(pendingChanges.map((c) => [c.nodeId, c.level]));
+        for (const link of incomingLinks) {
+            // Use pending level if there's a change for this source
+            const effectiveLevel = changeMap.has(link.sourceNodeId)
+                ? changeMap.get(link.sourceNodeId)
+                : link.sourceLevel;
+            if (effectiveLevel !== undefined) {
+                const proposedLevel = effectiveLevel + 1;
+                if (minLevel === undefined || proposedLevel < minLevel) {
+                    minLevel = proposedLevel;
+                }
+            }
+        }
+        return minLevel;
+    }
+    /**
+     * Recursively update levels for nodes that the changed node links to.
+     */
+    cascadeUpdates(nodeId, newLevel, nodes, changes) {
+        const node = nodes.find((n) => n.id === nodeId);
+        if (!node?.elements)
+            return;
+        // Find all outgoing links from this node
+        const outgoingTargetIds = node.elements
+            .filter((el) => el.isLink && el.linkTarget)
+            .map((el) => el.linkTarget);
+        for (const targetId of outgoingTargetIds) {
+            // Skip if we've already queued a change for this node
+            if (changes.some((c) => c.nodeId === targetId))
+                continue;
+            const targetNode = nodes.find((n) => n.id === targetId);
+            if (!targetNode)
+                continue;
+            // Don't modify root node
+            if (targetNode.level === 0)
+                continue;
+            if (newLevel === undefined) {
+                // Source became orphan - recalculate target from all its incoming links
+                // Pass pending changes so we use updated levels, not stale ones
+                const targetIncoming = this.findIncomingLinks(targetId, nodes);
+                const recalculatedLevel = this.calculateMinLevel(targetIncoming, changes);
+                if (recalculatedLevel !== targetNode.level) {
+                    changes.push({
+                        nodeId: targetId,
+                        level: recalculatedLevel
+                    });
+                    this.cascadeUpdates(targetId, recalculatedLevel, nodes, changes);
+                }
+            }
+            else {
+                // Source has a level - propose level + 1
+                const proposedLevel = newLevel + 1;
+                if (targetNode.level === undefined ||
+                    proposedLevel < targetNode.level) {
+                    changes.push({ nodeId: targetId, level: proposedLevel });
+                    this.cascadeUpdates(targetId, proposedLevel, nodes, changes);
+                }
+            }
+        }
+    }
+}

package/src/lib/utils/uuid.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generates a UUID v4.
+ * Uses crypto.randomUUID() if available, otherwise falls back to a polyfill.
+ */
+export declare function generateUuid(): string;

package/src/lib/utils/uuid.js

@@ -0,0 +1,16 @@
+/**
+ * Generates a UUID v4.
+ * Uses crypto.randomUUID() if available, otherwise falls back to a polyfill.
+ */
+export function generateUuid() {
+    if (typeof crypto !== "undefined" &&
+        typeof crypto.randomUUID === "function") {
+        return crypto.randomUUID();
+    }
+    // Fallback for environments without crypto.randomUUID
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, function (c) {
+        const r = (Math.random() * 16) | 0;
+        const v = c === "x" ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}

package/src/lib/validators/document-validator.d.ts

@@ -0,0 +1,22 @@
+import { CreateDocumentInput, UpdateDocumentInput } from "../types/api-types";
+/**
+ * Validator for document operations.
+ */
+export declare class DocumentValidator {
+    /**
+     * Validates input for document creation.
+     * @param input The creation input to validate
+     * @throws ValidationError if validation fails
+     */
+    validateCreate(input: CreateDocumentInput): void;
+    /**
+     * Validates input for document update.
+     * @param input The update input to validate
+     * @throws ValidationError if validation fails
+     */
+    validateUpdate(input: UpdateDocumentInput): void;
+    /**
+     * Validates canvas dimensions.
+     */
+    private validateCanvasDimensions;
+}

package/src/lib/validators/document-validator.js

@@ -0,0 +1,68 @@
+import { ValidationError } from "../errors/api-errors";
+/**
+ * Validator for document operations.
+ */
+export class DocumentValidator {
+    /**
+     * Validates input for document creation.
+     * @param input The creation input to validate
+     * @throws ValidationError if validation fails
+     */
+    validateCreate(input) {
+        if (!input.title || typeof input.title !== "string") {
+            throw new ValidationError("title is required", "title");
+        }
+        if (input.title.trim().length === 0) {
+            throw new ValidationError("title cannot be empty", "title");
+        }
+        if (input.title.length > 200) {
+            throw new ValidationError("title must be 200 characters or less", "title");
+        }
+        if (input.content !== undefined && typeof input.content !== "string") {
+            throw new ValidationError("content must be a string", "content");
+        }
+        this.validateCanvasDimensions(input.canvasWidth, input.canvasHeight);
+    }
+    /**
+     * Validates input for document update.
+     * @param input The update input to validate
+     * @throws ValidationError if validation fails
+     */
+    validateUpdate(input) {
+        if (input.title !== undefined) {
+            if (typeof input.title !== "string") {
+                throw new ValidationError("title must be a string", "title");
+            }
+            if (input.title.trim().length === 0) {
+                throw new ValidationError("title cannot be empty", "title");
+            }
+            if (input.title.length > 200) {
+                throw new ValidationError("title must be 200 characters or less", "title");
+            }
+        }
+        if (input.content !== undefined && typeof input.content !== "string") {
+            throw new ValidationError("content must be a string", "content");
+        }
+    }
+    /**
+     * Validates canvas dimensions.
+     */
+    validateCanvasDimensions(width, height) {
+        if (width !== undefined) {
+            if (typeof width !== "number" || isNaN(width)) {
+                throw new ValidationError("canvasWidth must be a valid number", "canvasWidth");
+            }
+            if (width < 100 || width > 10000) {
+                throw new ValidationError("canvasWidth must be between 100 and 10000", "canvasWidth");
+            }
+        }
+        if (height !== undefined) {
+            if (typeof height !== "number" || isNaN(height)) {
+                throw new ValidationError("canvasHeight must be a valid number", "canvasHeight");
+            }
+            if (height < 100 || height > 10000) {
+                throw new ValidationError("canvasHeight must be between 100 and 10000", "canvasHeight");
+            }
+        }
+    }
+}

package/src/lib/validators/element-type-validators/base-element-validator.d.ts

@@ -0,0 +1,35 @@
+import { BaseElementInput } from "../../types/element-input-types";
+/**
+ * Base class for element type validators.
+ * Provides common validation logic for position, dimensions, and colors.
+ */
+export declare abstract class BaseElementValidator {
+    /**
+     * Validates common element properties (position, dimensions, rotation).
+     * @param input The element input to validate
+     * @throws ValidationError if validation fails
+     */
+    protected validateCommon(input: BaseElementInput): void;
+    /**
+     * Validates position properties (x, y).
+     */
+    protected validatePosition(input: BaseElementInput): void;
+    /**
+     * Validates dimension properties (width, height).
+     */
+    protected validateDimensions(input: BaseElementInput): void;
+    /**
+     * Validates rotation property.
+     */
+    protected validateRotation(input: BaseElementInput): void;
+    /**
+     * Validates a hex color string.
+     * @param value The color value to validate
+     * @param field The field name for error messages
+     */
+    protected validateColor(value: unknown, field: string): void;
+    /**
+     * Validates stroke width.
+     */
+    protected validateStrokeWidth(value: unknown, field: string): void;
+}