@node-edit-utils/core

Core utilities for selecting, highlighting, and editing DOM nodes. This package provides framework-agnostic tools for building interactive node editing experiences.

✨ Features

• Node Selection - Select DOM nodes and highlight them with visual frames
• Highlight Management - Create and update visual highlight frames around selected nodes
• Text Editing - Enable inline text editing for node content
• Canvas Observer - Monitor canvas state and interactions
• Viewport Management - Create resizable viewports for content viewing
• Event Handling - Comprehensive keyboard and mouse event support
• Post Message API - Cross-frame communication support

📦 Installation

npm install @node-edit-utils/core
# or
pnpm add @node-edit-utils/core
# or
yarn add @node-edit-utils/core

🚀 Quick Start

Basic Node Selection and Highlighting

import { createNodeTools } from '@node-edit-utils/core';
import '@node-edit-utils/core/styles.css';

// Get the container element
const container = document.getElementById('content');

// Create node tools
const nodeTools = createNodeTools(container);

// Select a node to highlight it
const targetNode = document.querySelector('.editable-element');
nodeTools.selectNode(targetNode);

// Get the currently selected node
const selected = nodeTools.getSelectedNode();

// Clear the selection
nodeTools.clearSelectedNode();

// Clean up when done
nodeTools.cleanup();

Working with Text Editing

The text editing functionality is built into the node selection system. When you select a node, it automatically becomes editable:

const nodeTools = createNodeTools(container);

// Select a node - it becomes editable
const node = document.querySelector('h1');
nodeTools.selectNode(node);

// The node is now in edit mode - users can edit the text
// Press Escape to exit edit mode
// Get the currently edited node
const editableNode = nodeTools.getEditableNode();

Canvas Observer

Monitor canvas state changes and interactions:

import { createCanvasObserver } from '@node-edit-utils/core';

// Create observer to monitor canvas events
const observer = createCanvasObserver();

// The observer tracks canvas interactions automatically
// You can integrate it with your canvas library

Viewport Management

Create a resizable viewport for content viewing:

import { createViewport } from '@node-edit-utils/core';

// Get your viewport container
const viewportContainer = document.getElementById('viewport');

// Create the viewport
const viewport = createViewport(viewportContainer);

// Programmatically set viewport width
viewport.setWidth(800);

// Clean up
viewport.cleanup();

📖 API Reference

createNodeTools(element: HTMLElement | null): NodeTools

Creates a node tools manager for a given container element.

Parameters:

• element - The container element that holds the nodes to edit

Returns: NodeTools object with the following methods:

NodeTools Methods

• selectNode(node: HTMLElement | null): void - Select and highlight a node
• getSelectedNode(): HTMLElement | null - Get the currently selected node
• getEditableNode(): HTMLElement | null - Get the node currently in edit mode
• clearSelectedNode(): void - Clear the selection and remove highlight
• refreshHighlightFrame(): void - Refresh the highlight frame (useful after DOM changes)
• cleanup(): void - Clean up and remove all listeners

createCanvasObserver(): CanvasObserver

Creates a canvas observer for monitoring canvas interactions.

Returns: CanvasObserver object

createViewport(container: HTMLElement): Viewport

Creates a viewport with resize handles.

Parameters:

• container - The viewport container element

Returns: Viewport object with methods:

• setWidth(width: number): void - Set the viewport width
• cleanup(): void - Clean up the viewport

🎨 Styling

The package includes default styles that can be imported:

import '@node-edit-utils/core/styles.css';

You can customize the appearance by overriding CSS variables:

/* Override highlight colors */
:root {
  --highlight-color: #3b82f6;
  --highlight-border-width: 2px;
}

💡 Examples

Example 1: Full Node Editor Setup

import { createNodeTools, createViewport, createCanvasObserver } from '@node-edit-utils/core';
import '@node-edit-utils/core/styles.css';

// Setup
const container = document.getElementById('editor-container');
const viewportEl = document.getElementById('viewport');

// Create tools
const nodeTools = createNodeTools(container);
const viewport = createViewport(viewportEl);
const canvasObserver = createCanvasObserver();

// Handle node selection from UI
document.addEventListener('click', (e) => {
  if (e.target.classList.contains('editable')) {
    nodeTools.selectNode(e.target);
  }
});

// Handle exit
document.addEventListener('keydown', (e) => {
  if (e.key === 'Escape') {
    nodeTools.clearSelectedNode();
  }
});

// Cleanup on page unload
window.addEventListener('beforeunload', () => {
  nodeTools.cleanup();
  viewport.cleanup();
});

Example 2: Programmatic Node Selection

const nodeTools = createNodeTools(container);

// Select different nodes
const nodes = container.querySelectorAll('[data-selectable]');
nodes.forEach((node, index) => {
  setTimeout(() => {
    nodeTools.selectNode(node);
  }, index * 1000);
});

Example 3: Edit Mode with Custom Handling

const nodeTools = createNodeTools(container);

// Listen for when a node is selected
container.addEventListener('click', (e) => {
  const target = e.target;
  nodeTools.selectNode(target);
  
  // Check if it's in edit mode
  if (nodeTools.getEditableNode()) {
    console.log('Node is now editable:', nodeTools.getEditableNode());
  }
});

🔄 Event Handling

The node tools automatically handle:

• Click events - Select nodes on click
• Keyboard events - Exit edit mode with Escape key
• Resize events - Update highlight on viewport resize
• Mutation events - Refresh highlight on DOM changes

🧹 Cleanup

Always clean up when you're done to prevent memory leaks:

// When component unmounts or feature is disabled
nodeTools.cleanup();
viewport.cleanup();

🤝 Integration with Other Libraries

This package works well with:

• @markup-canvas/core and @markup-canvas/react - Canvas manipulation
• React - Via the @node-edit-utils/react package
• Any custom canvas or DOM manipulation library

⚠️ Notes

• The package modifies the DOM by adding highlight frames and edit mode elements
• Always import the CSS file for proper styling
• The package uses ResizeObserver and MutationObserver for monitoring
• Browser support requires a modern browser with ES2020+ support

📝 License

CC-BY-NC-4.0

👤 Author

Fritz Benning [email protected]