@codemcp/workflows 5.3.0 → 6.0.2

package/packages/visualizer/dist/types/ui-types.ts

@@ -0,0 +1,84 @@
+/**
+ * UI-specific type definitions for the workflow visualizer
+ */
+
+// Import existing types from the main project
+import type {
+  YamlStateMachine,
+  YamlState,
+  YamlTransition,
+} from '@codemcp/workflows-core';
+
+// Re-export for convenience
+export type { YamlStateMachine, YamlState, YamlTransition };
+
+/**
+ * Interaction event for diagram elements
+ */
+export interface InteractionEvent {
+  elementType: 'node' | 'edge' | 'transition';
+  elementId?: string;
+  data?: YamlState | TransitionData;
+  originalEvent?: Event;
+}
+
+/**
+ * Application state interface
+ */
+export interface AppState {
+  currentWorkflow: YamlStateMachine | null;
+  selectedElement: SelectedElement | null;
+  highlightedPath: string[] | null;
+  isLoading: boolean;
+  error: string | null;
+  parentState: { id: string; data: YamlState } | null;
+}
+
+/**
+ * Selected element in the diagram
+ */
+export interface SelectedElement {
+  type: 'state' | 'transition';
+  id: string;
+  data: YamlState | TransitionData;
+}
+
+/**
+ * Transition data with additional metadata
+ */
+export interface TransitionData {
+  trigger: string;
+  from: string;
+  to: string;
+  instructions?: string;
+  additional_instructions?: string;
+  transition_reason: string;
+  review_perspectives?: Array<{
+    perspective: string;
+    prompt: string;
+  }>;
+}
+
+/**
+ * Workflow metadata for the selector
+ */
+export interface WorkflowMetadata {
+  name: string;
+  displayName: string;
+  source: 'builtin' | 'uploaded';
+  domain?: string;
+}
+
+/**
+ * Error types for user feedback
+ */
+export interface AppError {
+  type: 'validation' | 'network' | 'parsing' | 'unknown';
+  message: string;
+  details?: string;
+}
+
+/**
+ * Loading states
+ */
+export type LoadingState = 'idle' | 'loading' | 'success' | 'error';

package/packages/visualizer/dist/types/visualization-types.ts

@@ -0,0 +1,95 @@
+/**
+ * D3.js and visualization-specific type definitions
+ */
+
+import * as d3 from 'd3';
+import { YamlState, YamlTransition } from './ui-types';
+
+/**
+ * Node data for D3.js force simulation
+ */
+export interface DiagramNode extends d3.SimulationNodeDatum {
+  id: string;
+  label: string;
+  state: YamlState;
+  isInitial: boolean;
+  x?: number;
+  y?: number;
+  fx?: number | null;
+  fy?: number | null;
+}
+
+/**
+ * Link data for D3.js force simulation
+ */
+export interface DiagramLink extends d3.SimulationLinkDatum<DiagramNode> {
+  id: string;
+  source: string | DiagramNode;
+  target: string | DiagramNode;
+  transition: YamlTransition;
+  label: string;
+  isSelfLoop: boolean;
+}
+
+/**
+ * Diagram dimensions and layout configuration
+ */
+export interface DiagramConfig {
+  width: number;
+  height: number;
+  nodeRadius: number;
+  linkDistance: number;
+  chargeStrength: number;
+  padding: {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+  };
+}
+
+/**
+ * Visual styling configuration
+ */
+export interface DiagramStyle {
+  node: {
+    fill: string;
+    stroke: string;
+    strokeWidth: number;
+    selectedFill: string;
+    selectedStroke: string;
+    initialFill: string;
+  };
+  link: {
+    stroke: string;
+    strokeWidth: number;
+    selectedStroke: string;
+    selectedStrokeWidth: number;
+    arrowSize: number;
+  };
+  text: {
+    fontSize: string;
+    fontFamily: string;
+    fill: string;
+  };
+}
+
+/**
+ * Interaction event data
+ */
+export interface InteractionEvent {
+  type: 'click' | 'hover' | 'unhover';
+  elementType: 'node' | 'link' | 'background';
+  elementId?: string;
+  data?: DiagramNode | DiagramLink;
+  originalEvent: Event;
+}
+
+/**
+ * Layout algorithm options
+ */
+export interface LayoutOptions {
+  algorithm: 'force' | 'hierarchical' | 'circular';
+  iterations: number;
+  stabilizationThreshold: number;
+}

package/packages/visualizer/dist/types/vite-env.d.ts

@@ -0,0 +1,12 @@
+/// <reference types="vite/client" />
+
+// Declare raw imports for YAML files
+declare module '*.yaml?raw' {
+  const content: string;
+  export default content;
+}
+
+declare module '*.yml?raw' {
+  const content: string;
+  export default content;
+}

package/packages/visualizer/dist/utils/DomHelpers.ts

@@ -0,0 +1,206 @@
+/**
+ * DOM manipulation utility functions
+ * Provides helper functions for common DOM operations
+ */
+
+/**
+ * Get a required DOM element with type safety
+ */
+export function getRequiredElement<T extends HTMLElement>(
+  selector: string,
+  context: Document | HTMLElement = document
+): T {
+  const element = context.querySelector(selector) as T;
+
+  if (!element) {
+    throw new Error(`Required element not found: ${selector}`);
+  }
+
+  return element;
+}
+
+/**
+ * Get an optional DOM element with type safety
+ */
+export function getOptionalElement<T extends HTMLElement>(
+  selector: string,
+  context: Document | HTMLElement = document
+): T | null {
+  return context.querySelector(selector) as T | null;
+}
+
+/**
+ * Get all elements matching a selector with type safety
+ */
+export function getAllElements<T extends HTMLElement>(
+  selector: string,
+  context: Document | HTMLElement = document
+): T[] {
+  return Array.from(context.querySelectorAll(selector)) as T[];
+}
+
+/**
+ * Create an element with attributes and content
+ */
+export function createElement<K extends keyof HTMLElementTagNameMap>(
+  tagName: K,
+  attributes: Record<string, string> = {},
+  textContent?: string
+): HTMLElementTagNameMap[K] {
+  const element = document.createElement(tagName);
+
+  // Set attributes
+  for (const [key, value] of Object.entries(attributes)) {
+    element.setAttribute(key, value);
+  }
+
+  // Set text content if provided
+  if (textContent !== undefined) {
+    element.textContent = textContent;
+  }
+
+  return element;
+}
+
+/**
+ * Add CSS classes to an element
+ */
+export function addClasses(
+  element: HTMLElement,
+  ...classNames: string[]
+): void {
+  element.classList.add(...classNames);
+}
+
+/**
+ * Remove CSS classes from an element
+ */
+export function removeClasses(
+  element: HTMLElement,
+  ...classNames: string[]
+): void {
+  element.classList.remove(...classNames);
+}
+
+/**
+ * Toggle CSS classes on an element
+ */
+export function toggleClasses(
+  element: HTMLElement,
+  ...classNames: string[]
+): void {
+  for (const className of classNames) {
+    element.classList.toggle(className);
+  }
+}
+
+/**
+ * Check if element has a CSS class
+ */
+export function hasClass(element: HTMLElement, className: string): boolean {
+  return element.classList.contains(className);
+}
+
+/**
+ * Set multiple CSS styles on an element
+ */
+export function setStyles(
+  element: HTMLElement,
+  styles: Record<string, string>
+): void {
+  for (const [property, value] of Object.entries(styles)) {
+    element.style.setProperty(property, value);
+  }
+}
+
+/**
+ * Clear all children from an element
+ */
+export function clearChildren(element: HTMLElement): void {
+  while (element.firstChild) {
+    element.removeChild(element.firstChild);
+  }
+}
+
+/**
+ * Append multiple children to an element
+ */
+export function appendChildren(
+  parent: HTMLElement,
+  ...children: HTMLElement[]
+): void {
+  for (const child of children) {
+    parent.appendChild(child);
+  }
+}
+
+/**
+ * Show an element by removing 'hidden' class
+ */
+export function showElement(element: HTMLElement): void {
+  element.classList.remove('hidden');
+  element.style.display = '';
+}
+
+/**
+ * Hide an element by adding 'hidden' class
+ */
+export function hideElement(element: HTMLElement): void {
+  element.classList.add('hidden');
+}
+
+/**
+ * Check if an element is visible
+ */
+export function isElementVisible(element: HTMLElement): boolean {
+  return (
+    !element.classList.contains('hidden') &&
+    element.style.display !== 'none' &&
+    element.offsetParent !== null
+  );
+}
+
+/**
+ * Safely set innerHTML with basic XSS protection
+ */
+export function setSafeInnerHTML(element: HTMLElement, html: string): void {
+  // Basic sanitization - remove script tags and event handlers
+  const sanitized = html
+    .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '')
+    .replace(/\son\w+\s*=\s*["'][^"']*["']/gi, '');
+
+  element.innerHTML = sanitized;
+}
+
+/**
+ * Debounce a function call
+ */
+export function debounce<T extends (...args: unknown[]) => unknown>(
+  func: T,
+  delay: number
+): (...args: Parameters<T>) => void {
+  let timeoutId: number;
+
+  return (...args: Parameters<T>) => {
+    clearTimeout(timeoutId);
+    timeoutId = window.setTimeout(() => func(...args), delay);
+  };
+}
+
+/**
+ * Throttle a function call
+ */
+export function throttle<T extends (...args: unknown[]) => unknown>(
+  func: T,
+  delay: number
+): (...args: Parameters<T>) => void {
+  let lastCall = 0;
+
+  return (...args: Parameters<T>) => {
+    const now = Date.now();
+    if (now - lastCall >= delay) {
+      lastCall = now;
+      func(...args);
+    }
+  };
+}

package/packages/visualizer/dist/utils/ErrorHandler.ts

@@ -0,0 +1,170 @@
+/**
+ * Error handling and user feedback utility
+ * Manages error display and user notifications
+ */
+
+import { AppError } from '../types/ui-types';
+
+export class ErrorHandler {
+  private readonly errorContainer: HTMLElement;
+  private readonly errorText: HTMLElement;
+  private readonly errorClose: HTMLElement;
+  private currentTimeout: number | null = null;
+  private readonly boundHideError: (event: Event) => void;
+
+  constructor() {
+    this.errorContainer = this.getRequiredElement('#error-container');
+    this.errorText = this.getRequiredElement('.error-text');
+    this.errorClose = this.getRequiredElement('.error-close');
+    this.boundHideError = this.hideError.bind(this);
+
+    this.setupEventListeners();
+  }
+
+  /**
+   * Set up event listeners for error handling
+   */
+  private setupEventListeners(): void {
+    this.errorClose.addEventListener('click', this.boundHideError);
+
+    // Hide error when clicking outside
+    this.errorContainer.addEventListener('click', (event: Event) => {
+      if (event.target === this.errorContainer) {
+        this.hideError();
+      }
+    });
+  }
+
+  /**
+   * Display an error message to the user
+   */
+  public showError(error: AppError | string): void {
+    const errorMessage = typeof error === 'string' ? error : error.message;
+    const errorType = typeof error === 'string' ? 'unknown' : error.type;
+
+    // Clear any existing timeout
+    if (this.currentTimeout) {
+      clearTimeout(this.currentTimeout);
+      this.currentTimeout = null;
+    }
+
+    // Update error content
+    this.errorText.textContent = errorMessage;
+
+    // Add error type class for styling
+    this.errorContainer.className = `error-container error-${errorType}`;
+
+    // Show error container
+    this.errorContainer.classList.remove('hidden');
+
+    // Auto-hide after 10 seconds for non-critical errors
+    if (errorType !== 'validation') {
+      this.currentTimeout = window.setTimeout(() => {
+        this.hideError();
+      }, 10000);
+    }
+
+    // Log error for debugging
+    console.error('ErrorHandler:', error);
+  }
+
+  /**
+   * Hide the error message
+   */
+  public hideError(): void {
+    this.errorContainer.classList.add('hidden');
+
+    if (this.currentTimeout) {
+      clearTimeout(this.currentTimeout);
+      this.currentTimeout = null;
+    }
+  }
+
+  /**
+   * Show a success message
+   */
+  public showSuccess(message: string): void {
+    // For now, just log success messages
+    // Could be extended to show success notifications
+    console.log('Success:', message);
+  }
+
+  /**
+   * Show a loading message
+   */
+  public showLoading(message: string): void {
+    // For now, just log loading messages
+    // Could be extended to show loading indicators
+    console.log('Loading:', message);
+  }
+
+  /**
+   * Create a user-friendly error message based on error type
+   */
+  public createUserFriendlyError(error: unknown): AppError {
+    if (error instanceof Error) {
+      // Check for specific error patterns
+      if (error.message.includes('fetch')) {
+        return {
+          type: 'network',
+          message:
+            'Failed to load workflow. Please check your connection and try again.',
+          details: error.message,
+        };
+      }
+
+      if (error.message.includes('YAML') || error.message.includes('parsing')) {
+        return {
+          type: 'parsing',
+          message: 'Invalid YAML format. Please check your workflow file.',
+          details: error.message,
+        };
+      }
+
+      if (error.message.includes('validation')) {
+        return {
+          type: 'validation',
+          message: error.message,
+          details: error.message,
+        };
+      }
+
+      return {
+        type: 'unknown',
+        message: error.message || 'An unexpected error occurred.',
+        details: error.message,
+      };
+    }
+
+    return {
+      type: 'unknown',
+      message: 'An unexpected error occurred.',
+      details: String(error),
+    };
+  }
+
+  /**
+   * Get a required DOM element with error handling
+   */
+  private getRequiredElement(selector: string): HTMLElement {
+    const element = document.querySelector(selector) as HTMLElement;
+
+    if (!element) {
+      throw new Error(`Required element not found: ${selector}`);
+    }
+
+    return element;
+  }
+
+  /**
+   * Clean up event listeners
+   */
+  public destroy(): void {
+    this.errorClose.removeEventListener('click', this.boundHideError);
+
+    if (this.currentTimeout) {
+      clearTimeout(this.currentTimeout);
+      this.currentTimeout = null;
+    }
+  }
+}

package/packages/visualizer/dist/utils/PlantUMLEncoder.ts

@@ -0,0 +1,121 @@
+/**
+ * Browser-compatible PlantUML encoder
+ * Uses native JavaScript compression instead of pako
+ */
+
+/**
+ * Encode PlantUML code using native compression
+ */
+export async function encodePlantUML(plantUMLCode: string): Promise<string> {
+  try {
+    // Convert string to UTF-8 bytes
+    const utf8Bytes = new TextEncoder().encode(plantUMLCode);
+
+    // Use native compression if available
+    if ('CompressionStream' in window) {
+      const stream = new CompressionStream('deflate-raw');
+      const writer = stream.writable.getWriter();
+      const reader = stream.readable.getReader();
+
+      writer.write(utf8Bytes);
+      writer.close();
+
+      const chunks = [];
+      let done = false;
+      while (!done) {
+        const { value, done: readerDone } = await reader.read();
+        done = readerDone;
+        if (value) chunks.push(value);
+      }
+
+      const compressed = new Uint8Array(
+        chunks.reduce((acc, chunk) => acc + chunk.length, 0)
+      );
+      let offset = 0;
+      for (const chunk of chunks) {
+        compressed.set(chunk, offset);
+        offset += chunk.length;
+      }
+
+      return encode64(compressed);
+    } else {
+      // Fallback to base64 encoding
+      return encodePlantUMLFallback(plantUMLCode);
+    }
+  } catch (error) {
+    console.error('Failed to encode PlantUML:', error);
+    return encodePlantUMLFallback(plantUMLCode);
+  }
+}
+
+/**
+ * PlantUML's custom base64-like encoding
+ */
+function encode64(data: Uint8Array): string {
+  let r = '';
+  for (let i = 0; i < data.length; i += 3) {
+    if (i + 2 === data.length) {
+      r += append3bytes(data[i], data[i + 1], 0);
+    } else if (i + 1 === data.length) {
+      r += append3bytes(data[i], 0, 0);
+    } else {
+      r += append3bytes(data[i], data[i + 1], data[i + 2]);
+    }
+  }
+  return r;
+}
+
+/**
+ * Helper function for PlantUML's custom encoding
+ */
+function append3bytes(b1: number, b2: number, b3: number): string {
+  const c1 = b1 >> 2;
+  const c2 = ((b1 & 0x3) << 4) | (b2 >> 4);
+  const c3 = ((b2 & 0xf) << 2) | (b3 >> 6);
+  const c4 = b3 & 0x3f;
+  let r = '';
+  r += encode6bit(c1 & 0x3f);
+  r += encode6bit(c2 & 0x3f);
+  r += encode6bit(c3 & 0x3f);
+  r += encode6bit(c4 & 0x3f);
+  return r;
+}
+
+/**
+ * PlantUML's custom 6-bit encoding
+ */
+function encode6bit(b: number): string {
+  if (b < 10) {
+    return String.fromCharCode(48 + b);
+  }
+  b -= 10;
+  if (b < 26) {
+    return String.fromCharCode(65 + b);
+  }
+  b -= 26;
+  if (b < 26) {
+    return String.fromCharCode(97 + b);
+  }
+  b -= 26;
+  if (b === 0) {
+    return '-';
+  }
+  if (b === 1) {
+    return '_';
+  }
+  return '?';
+}
+
+/**
+ * Fallback encoder using base64 with ~1 header
+ */
+export function encodePlantUMLFallback(plantUMLCode: string): string {
+  try {
+    const utf8String = unescape(encodeURIComponent(plantUMLCode));
+    const base64 = btoa(utf8String);
+    return '~1' + base64;
+  } catch (error) {
+    console.error('Failed to encode PlantUML (fallback):', error);
+    throw new Error('PlantUML fallback encoding failed');
+  }
+}