@markup-canvas/core 1.0.0

package/src/lib/MarkupCanvas.ts

@@ -0,0 +1,434 @@
+import { createCanvas } from "@/lib/canvas/index.js";
+import { createMarkupCanvasConfig } from "@/lib/config/createMarkupCanvasConfig.js";
+import { EventEmitter } from "@/lib/events/EventEmitter.js";
+import { setupKeyboardEvents, setupMouseEvents, setupTouchEvents, setupWheelEvents } from "@/lib/events/index.js";
+import { withClampedZoom, withFeatureEnabled } from "@/lib/helpers/index.js";
+import { createRulers } from "@/lib/rulers/index.js";
+import { withTransition } from "@/lib/transition/withTransition.js";
+import type {
+  BaseCanvas,
+  Canvas,
+  CanvasBounds,
+  MarkupCanvasConfig,
+  MarkupCanvasEvents,
+  MouseDragControls,
+  Transform,
+} from "@/types/index.js";
+
+declare global {
+  interface Window {
+    __markupCanvasTransitionTimeout?: number;
+  }
+}
+
+export class MarkupCanvas implements Canvas {
+  private baseCanvas: BaseCanvas;
+  private cleanupFunctions: (() => void)[] = [];
+  private rulers: ReturnType<typeof createRulers> | null = null;
+  private dragSetup: MouseDragControls | null = null;
+  public config: Required<MarkupCanvasConfig>;
+  private _isReady = false;
+  private listen = new EventEmitter<MarkupCanvasEvents>();
+
+  constructor(container: HTMLElement, options: MarkupCanvasConfig = {}) {
+    if (!container) {
+      throw new Error("Container element is required");
+    }
+
+    this.config = createMarkupCanvasConfig(options);
+
+    const canvas = createCanvas(container, this.config);
+    if (!canvas) {
+      throw new Error("Failed to create canvas");
+    }
+
+    this.baseCanvas = canvas;
+    this.setupEventHandlers();
+    this._isReady = true;
+
+    // Emit ready event
+    this.listen.emit("ready", this);
+  }
+
+  private setupEventHandlers(): void {
+    try {
+      // Wheel zoom
+      withFeatureEnabled(this.config, "enableZoom", () => {
+        const wheelCleanup = setupWheelEvents(this, this.config);
+        this.cleanupFunctions.push(wheelCleanup);
+      });
+
+      // Mouse events (drag and click-to-zoom)
+      // Set up mouse events if either pan or click-to-zoom is enabled
+      if (this.config.enablePan || this.config.enableClickToZoom) {
+        this.dragSetup = setupMouseEvents(this, this.config, true);
+        this.cleanupFunctions.push(this.dragSetup.cleanup);
+      }
+
+      // Keyboard navigation
+      withFeatureEnabled(this.config, "enableKeyboard", () => {
+        const keyboardCleanup = setupKeyboardEvents(this, this.config);
+        this.cleanupFunctions.push(keyboardCleanup);
+      });
+
+      // Touch events (if enabled)
+      withFeatureEnabled(this.config, "enableTouch", () => {
+        const touchCleanup = setupTouchEvents(this);
+        this.cleanupFunctions.push(touchCleanup);
+      });
+
+      // Set up rulers and grid
+      withFeatureEnabled(this.config, "enableRulers", () => {
+        this.rulers = createRulers(this.baseCanvas, this.config);
+        this.cleanupFunctions.push(() => {
+          if (this.rulers) {
+            this.rulers.destroy();
+          }
+        });
+      });
+    } catch (error) {
+      console.error("Failed to set up event handlers:", error);
+      this.cleanup();
+      throw error;
+    }
+  }
+
+  // Base canvas properties and methods
+  get container(): HTMLElement {
+    return this.baseCanvas.container;
+  }
+
+  get transformLayer(): HTMLElement {
+    return this.baseCanvas.transformLayer;
+  }
+
+  get contentLayer(): HTMLElement {
+    return this.baseCanvas.contentLayer;
+  }
+
+  get transform(): Transform {
+    return this.baseCanvas.transform;
+  }
+
+  // State management getters for React integration
+  get isReady(): boolean {
+    return this._isReady;
+  }
+
+  get isTransforming(): boolean {
+    return this.dragSetup?.isEnabled() || false;
+  }
+
+  get visibleBounds(): { x: number; y: number; width: number; height: number } {
+    return this.getVisibleArea();
+  }
+
+  getBounds(): CanvasBounds {
+    return this.baseCanvas.getBounds();
+  }
+
+  updateTransform(newTransform: Partial<Transform>): boolean {
+    const result = this.baseCanvas.updateTransform(newTransform);
+    if (result) {
+      this.emitTransformEvents();
+    }
+    return result;
+  }
+
+  private emitTransformEvents(): void {
+    const transform = this.baseCanvas.transform;
+    this.listen.emit("transform", transform);
+    this.listen.emit("zoom", transform.scale);
+    this.listen.emit("pan", { x: transform.translateX, y: transform.translateY });
+  }
+
+  reset(): boolean {
+    return this.baseCanvas.reset();
+  }
+
+  handleResize(): boolean {
+    return this.baseCanvas.handleResize();
+  }
+
+  setZoom(zoomLevel: number): boolean {
+    return this.baseCanvas.setZoom(zoomLevel);
+  }
+
+  canvasToContent(x: number, y: number): { x: number; y: number } {
+    return this.baseCanvas.canvasToContent(x, y);
+  }
+
+  zoomToPoint(x: number, y: number, targetScale: number): boolean {
+    return withTransition(this.transformLayer, this.config, () => {
+      const result = this.baseCanvas.zoomToPoint(x, y, targetScale);
+      if (result) {
+        this.emitTransformEvents();
+      }
+      return result;
+    });
+  }
+
+  resetView(): boolean {
+    return withTransition(this.transformLayer, this.config, () => {
+      const result = this.baseCanvas.resetView ? this.baseCanvas.resetView() : false;
+      if (result) {
+        this.emitTransformEvents();
+      }
+      return result;
+    });
+  }
+
+  zoomToFitContent(): boolean {
+    return withTransition(this.transformLayer, this.config, () => {
+      const result = this.baseCanvas.zoomToFitContent();
+      if (result) {
+        this.emitTransformEvents();
+      }
+      return result;
+    });
+  }
+
+  // Pan methods
+  panLeft(distance?: number): boolean {
+    const panDistance = distance ?? this.config.keyboardPanStep;
+    const newTransform: Partial<Transform> = {
+      translateX: this.baseCanvas.transform.translateX + panDistance,
+    };
+    return this.updateTransform(newTransform);
+  }
+
+  panRight(distance?: number): boolean {
+    const panDistance = distance ?? this.config.keyboardPanStep;
+    const newTransform: Partial<Transform> = {
+      translateX: this.baseCanvas.transform.translateX - panDistance,
+    };
+    return this.updateTransform(newTransform);
+  }
+
+  panUp(distance?: number): boolean {
+    const panDistance = distance ?? this.config.keyboardPanStep;
+    const newTransform: Partial<Transform> = {
+      translateY: this.baseCanvas.transform.translateY + panDistance,
+    };
+    return this.updateTransform(newTransform);
+  }
+
+  panDown(distance?: number): boolean {
+    const panDistance = distance ?? this.config.keyboardPanStep;
+    const newTransform: Partial<Transform> = {
+      translateY: this.baseCanvas.transform.translateY - panDistance,
+    };
+    return this.updateTransform(newTransform);
+  }
+
+  // Zoom methods
+  zoomIn(factor: number = 0.1): boolean {
+    return withTransition(this.transformLayer, this.config, () => {
+      return withClampedZoom(this.config, (clamp) => {
+        const newScale = clamp(this.baseCanvas.transform.scale * (1 + factor));
+        const newTransform: Partial<Transform> = {
+          scale: newScale,
+        };
+        return this.updateTransform(newTransform);
+      });
+    });
+  }
+
+  zoomOut(factor: number = 0.1): boolean {
+    return withTransition(this.transformLayer, this.config, () => {
+      return withClampedZoom(this.config, (clamp) => {
+        const newScale = clamp(this.baseCanvas.transform.scale * (1 - factor));
+        const newTransform: Partial<Transform> = {
+          scale: newScale,
+        };
+        return this.updateTransform(newTransform);
+      });
+    });
+  }
+
+  resetZoom(): boolean {
+    return this.resetView();
+  }
+
+  // Mouse drag control methods
+  enableMouseDrag(): boolean {
+    return this.dragSetup?.enable() ?? false;
+  }
+
+  disableMouseDrag(): boolean {
+    return this.dragSetup?.disable() ?? false;
+  }
+
+  isMouseDragEnabled(): boolean {
+    return this.dragSetup?.isEnabled() ?? false;
+  }
+
+  // Grid control methods
+  toggleGrid(): boolean {
+    if (this.rulers?.toggleGrid) {
+      this.rulers.toggleGrid();
+      return true;
+    }
+    return false;
+  }
+
+  showGrid(): boolean {
+    if (this.rulers?.gridOverlay) {
+      this.rulers.gridOverlay.style.display = "block";
+      return true;
+    }
+    return false;
+  }
+
+  hideGrid(): boolean {
+    if (this.rulers?.gridOverlay) {
+      this.rulers.gridOverlay.style.display = "none";
+      return true;
+    }
+    return false;
+  }
+
+  isGridVisible(): boolean {
+    if (this.rulers?.gridOverlay) {
+      return this.rulers.gridOverlay.style.display !== "none";
+    }
+    return false;
+  }
+
+  // Ruler control methods
+  toggleRulers(): boolean {
+    if (this.rulers) {
+      const areVisible = this.areRulersVisible();
+      if (areVisible) {
+        this.rulers.hide();
+      } else {
+        this.rulers.show();
+      }
+      return true;
+    }
+    return false;
+  }
+
+  showRulers(): boolean {
+    if (this.rulers) {
+      this.rulers.show();
+      return true;
+    }
+    return false;
+  }
+
+  hideRulers(): boolean {
+    if (this.rulers) {
+      this.rulers.hide();
+      return true;
+    }
+    return false;
+  }
+
+  areRulersVisible(): boolean {
+    if (this.rulers?.horizontalRuler) {
+      return this.rulers.horizontalRuler.style.display !== "none";
+    }
+    return false;
+  }
+
+  // Utility methods
+  centerContent(): boolean {
+    return withTransition(this.transformLayer, this.config, () => {
+      const bounds = this.baseCanvas.getBounds();
+      const centerX = (bounds.width - bounds.contentWidth * this.baseCanvas.transform.scale) / 2;
+      const centerY = (bounds.height - bounds.contentHeight * this.baseCanvas.transform.scale) / 2;
+
+      return this.updateTransform({
+        translateX: centerX,
+        translateY: centerY,
+      });
+    });
+  }
+
+  fitToScreen(): boolean {
+    return withTransition(this.transformLayer, this.config, () => {
+      const result = this.baseCanvas.zoomToFitContent();
+      if (result) {
+        this.emitTransformEvents();
+      }
+      return result;
+    });
+  }
+
+  getVisibleArea(): { x: number; y: number; width: number; height: number } {
+    const bounds = this.baseCanvas.getBounds();
+    return bounds.visibleArea;
+  }
+
+  isPointVisible(x: number, y: number): boolean {
+    const visibleArea = this.getVisibleArea();
+    return x >= visibleArea.x && x <= visibleArea.x + visibleArea.width && y >= visibleArea.y && y <= visibleArea.y + visibleArea.height;
+  }
+
+  scrollToPoint(x: number, y: number): boolean {
+    return withTransition(this.transformLayer, this.config, () => {
+      const bounds = this.baseCanvas.getBounds();
+      const centerX = bounds.width / 2;
+      const centerY = bounds.height / 2;
+
+      // Calculate new translation to center the point
+      const newTranslateX = centerX - x * this.baseCanvas.transform.scale;
+      const newTranslateY = centerY - y * this.baseCanvas.transform.scale;
+
+      return this.updateTransform({
+        translateX: newTranslateX,
+        translateY: newTranslateY,
+      });
+    });
+  }
+
+  // Configuration access
+  getConfig(): Required<MarkupCanvasConfig> {
+    return { ...this.config };
+  }
+
+  updateConfig(newConfig: Partial<MarkupCanvasConfig>): void {
+    this.config = createMarkupCanvasConfig({ ...this.config, ...newConfig });
+  }
+
+  // Cleanup method
+  cleanup(): void {
+    this.cleanupFunctions.forEach((cleanup) => {
+      try {
+        cleanup();
+      } catch (cleanupError) {
+        console.warn("Error during cleanup:", cleanupError);
+      }
+    });
+    this.cleanupFunctions = [];
+
+    // Remove all event listeners
+    this.removeAllListeners();
+  }
+
+  // Event emitter delegation methods
+  on<K extends keyof MarkupCanvasEvents>(event: K, handler: (data: MarkupCanvasEvents[K]) => void): void {
+    this.listen.on(event, handler);
+  }
+
+  off<K extends keyof MarkupCanvasEvents>(event: K, handler: (data: MarkupCanvasEvents[K]) => void): void {
+    this.listen.off(event, handler);
+  }
+
+  emit<K extends keyof MarkupCanvasEvents>(event: K, data: MarkupCanvasEvents[K]): void {
+    this.listen.emit(event, data);
+  }
+
+  removeAllListeners(): void {
+    this.listen.removeAllListeners();
+  }
+
+  destroy(): void {
+    this.cleanup();
+
+    if (window.__markupCanvasTransitionTimeout) {
+      clearTimeout(window.__markupCanvasTransitionTimeout);
+    }
+  }
+}

package/src/lib/canvas/calcVisibleArea.ts

@@ -0,0 +1,20 @@
+import { canvasToContent, createMatrix } from "@/lib/matrix";
+
+export function calculateVisibleArea(
+  canvasWidth: number,
+  canvasHeight: number,
+  contentWidth: number,
+  contentHeight: number,
+  transform: { scale: number; translateX: number; translateY: number }
+) {
+  const topLeft = canvasToContent(0, 0, createMatrix(transform.scale, transform.translateX, transform.translateY));
+
+  const bottomRight = canvasToContent(canvasWidth, canvasHeight, createMatrix(transform.scale, transform.translateX, transform.translateY));
+
+  return {
+    x: Math.max(0, Math.min(contentWidth, topLeft.x)),
+    y: Math.max(0, Math.min(contentHeight, topLeft.y)),
+    width: Math.max(0, Math.min(contentWidth - topLeft.x, bottomRight.x - topLeft.x)),
+    height: Math.max(0, Math.min(contentHeight - topLeft.y, bottomRight.y - topLeft.y)),
+  };
+}

package/src/lib/canvas/checkContainerDimensions.ts

@@ -0,0 +1,20 @@
+export function checkContainerDimensions(container: HTMLElement): void {
+  const containerRect = container.getBoundingClientRect();
+  const computedStyle = getComputedStyle(container);
+
+  if (containerRect.height === 0 && computedStyle.height === "auto") {
+    console.error(
+      "MarkupCanvas: Container height is 0. Please set a height on your container element using CSS.",
+      "Examples: height: 100vh, height: 500px, or use flexbox/grid layout.",
+      container,
+    );
+  }
+
+  if (containerRect.width === 0 && computedStyle.width === "auto") {
+    console.error(
+      "MarkupCanvas: Container width is 0. Please set a width on your container element using CSS.",
+      "Examples: width: 100vw, width: 800px, or use flexbox/grid layout.",
+      container,
+    );
+  }
+}

package/src/lib/canvas/config.ts

@@ -0,0 +1,29 @@
+import type { CanvasOptions } from "@/types/index.js";
+
+const DEFAULT_CANVAS_WIDTH = 8000;
+const DEFAULT_CANVAS_HEIGHT = 8000;
+
+// Creates a validated configuration object with defaults
+export function createCanvasConfig(options: CanvasOptions = {}): Required<CanvasOptions> {
+  const config: Required<CanvasOptions> = {
+    width: DEFAULT_CANVAS_WIDTH,
+    height: DEFAULT_CANVAS_HEIGHT,
+    enableAcceleration: true,
+    enableEventHandling: true,
+    onTransformUpdate: () => {},
+    ...options,
+  };
+
+  // Validate and fix configuration values
+  if (typeof config.width !== "number" || config.width <= 0) {
+    console.warn("Invalid width, using default 8000px");
+    config.width = DEFAULT_CANVAS_WIDTH;
+  }
+
+  if (typeof config.height !== "number" || config.height <= 0) {
+    console.warn("Invalid height, using default 8000px");
+    config.height = DEFAULT_CANVAS_HEIGHT;
+  }
+
+  return config;
+}

package/src/lib/canvas/createCanvas.ts

@@ -0,0 +1,61 @@
+import { createCanvasLayers } from "@/lib/canvas/createCanvasLayers.js";
+import { getCanvasMethods } from "@/lib/canvas/getCanvasMethods.js";
+import { setupCanvasContainer } from "@/lib/canvas/setupCanvasContainer.js";
+import { DEFAULT_ZOOM } from "@/lib/constants.js";
+import { createMatrix } from "@/lib/matrix/createMatrix.js";
+import { applyTransform, enableHardwareAcceleration } from "@/lib/transform/index.js";
+import type { BaseCanvas, MarkupCanvasConfig, Transform } from "@/types/index.js";
+import { RULER_SIZE } from "../rulers/constants";
+
+// Creates and initializes a canvas with the required DOM structure
+export function createCanvas(container: HTMLElement, config: Required<MarkupCanvasConfig>): BaseCanvas | null {
+  if (!container?.appendChild) {
+    console.error("Invalid container element provided to createCanvas");
+    return null;
+  }
+
+  try {
+    setupCanvasContainer(container);
+
+    const { transformLayer, contentLayer } = createCanvasLayers(container, config);
+
+    // Enable hardware acceleration if requested
+    if (config.enableAcceleration) {
+      enableHardwareAcceleration(transformLayer);
+    }
+
+    const rulerOffset = config.enableRulers ? -RULER_SIZE : 0;
+
+    const initialTransform: Transform = {
+      scale: DEFAULT_ZOOM,
+      translateX: rulerOffset,
+      translateY: rulerOffset,
+    };
+
+    // Apply initial transform
+    const initialMatrix = createMatrix(initialTransform.scale, initialTransform.translateX, initialTransform.translateY);
+
+    applyTransform(transformLayer, initialMatrix);
+
+    const canvas: BaseCanvas = {
+      // DOM references
+      container,
+      transformLayer,
+      contentLayer,
+
+      // Configuration
+      config: config,
+
+      // Current state
+      transform: initialTransform,
+
+      // Add all canvas methods
+      ...getCanvasMethods(),
+    };
+
+    return canvas;
+  } catch (error) {
+    console.error("Failed to create canvas:", error);
+    return null;
+  }
+}

package/src/lib/canvas/createCanvasLayers.ts

@@ -0,0 +1,39 @@
+import { moveExistingContent } from "@/lib/canvas/moveExistingContent.js";
+import { setupContentLayer } from "@/lib/canvas/setupContentLayer.js";
+import { setupTransformLayer } from "@/lib/canvas/setupTransformLayer.js";
+import { CONTENT_LAYER_CLASS, TRANSFORM_LAYER_CLASS } from "@/lib/constants.js";
+import type { MarkupCanvasConfig } from "@/types/index.js";
+
+export interface CanvasLayers {
+  transformLayer: HTMLElement;
+  contentLayer: HTMLElement;
+}
+
+export function createCanvasLayers(container: HTMLElement, config: Required<MarkupCanvasConfig>): CanvasLayers {
+  const existingContent = Array.from(container.children);
+
+  // Create or find transform layer
+  let transformLayer = container.querySelector(`.${TRANSFORM_LAYER_CLASS}`) as HTMLElement;
+  if (!transformLayer) {
+    transformLayer = document.createElement("div");
+    transformLayer.className = TRANSFORM_LAYER_CLASS;
+    container.appendChild(transformLayer);
+  }
+
+  setupTransformLayer(transformLayer, config);
+
+  // Create or find content layer
+  let contentLayer = transformLayer.querySelector(`.${CONTENT_LAYER_CLASS}`) as HTMLElement;
+  if (!contentLayer) {
+    contentLayer = document.createElement("div");
+    contentLayer.className = CONTENT_LAYER_CLASS;
+    transformLayer.appendChild(contentLayer);
+
+    moveExistingContent(existingContent, contentLayer, transformLayer);
+  }
+
+  // Set content layer properties
+  setupContentLayer(contentLayer);
+
+  return { transformLayer, contentLayer };
+}

package/src/lib/canvas/getCanvasBounds.ts

@@ -0,0 +1,68 @@
+import { calculateVisibleArea } from "@/lib/canvas/calcVisibleArea.js";
+import { getEmptyBounds } from "@/lib/canvas/getEmptyBounds.js";
+import { withRulerSize } from "@/lib/helpers/index.js";
+import type { BaseCanvas, CanvasBounds } from "@/types/index.js";
+import { DEFAULT_CONFIG } from "../config/constants";
+
+export function getCanvasBounds(canvas: BaseCanvas): CanvasBounds {
+  try {
+    const container = canvas.container;
+    const config = canvas.config;
+    const transform = canvas.transform || {
+      scale: 1.0,
+      translateX: 0,
+      translateY: 0,
+    };
+
+    // Get canvas dimensions
+    const containerRect = container.getBoundingClientRect();
+    const totalWidth = containerRect.width || container.clientWidth || 0;
+    const totalHeight = containerRect.height || container.clientHeight || 0;
+
+    // Calculate canvas dimensions accounting for rulers
+    const canvasWidth = withRulerSize({ container }, (rulerSize) => Math.max(0, totalWidth - rulerSize));
+    const canvasHeight = withRulerSize({ container }, (rulerSize) => Math.max(0, totalHeight - rulerSize));
+
+    // Get content dimensions
+    const contentWidth = config.width || DEFAULT_CONFIG.width;
+    const contentHeight = config.height || DEFAULT_CONFIG.height;
+
+    // Calculate visible area in content coordinates
+    const visibleArea = calculateVisibleArea(canvasWidth, canvasHeight, contentWidth, contentHeight, transform);
+
+    return {
+      // Canvas dimensions
+      width: canvasWidth,
+      height: canvasHeight,
+
+      // Content dimensions
+      contentWidth,
+      contentHeight,
+
+      // Current transform
+      scale: transform.scale,
+      translateX: transform.translateX,
+      translateY: transform.translateY,
+
+      // Visible area in content coordinates
+      visibleArea,
+
+      // Calculated properties
+      scaledContentWidth: contentWidth * transform.scale,
+      scaledContentHeight: contentHeight * transform.scale,
+
+      // Bounds checking
+      canPanLeft: transform.translateX < 0,
+      canPanRight: transform.translateX + contentWidth * transform.scale > canvasWidth,
+      canPanUp: transform.translateY < 0,
+      canPanDown: transform.translateY + contentHeight * transform.scale > canvasHeight,
+
+      // Zoom bounds
+      canZoomIn: transform.scale < 3.5,
+      canZoomOut: transform.scale > 0.1,
+    };
+  } catch (error) {
+    console.error("Failed to calculate canvas bounds:", error);
+    return getEmptyBounds();
+  }
+}