@node-edit-utils/core 1.2.2

package/README.md

@@ -0,0 +1,268 @@
+# @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
+
+```bash
+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
+
+```javascript
+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:
+
+```javascript
+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:
+
+```javascript
+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:
+
+```javascript
+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:
+
+```javascript
+import '@node-edit-utils/core/styles.css';
+```
+
+You can customize the appearance by overriding CSS variables:
+
+```css
+/* Override highlight colors */
+:root {
+  --highlight-color: #3b82f6;
+  --highlight-border-width: 2px;
+}
+```
+
+## 💡 Examples
+
+### Example 1: Full Node Editor Setup
+
+```javascript
+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
+
+```javascript
+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
+
+```javascript
+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:
+
+```javascript
+// 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 <mail@fritzbenning.de>

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import "@/lib/styles/styles.css";
+export { createCanvasObserver } from "@/lib/canvas/createCanvasObserver";
+export { createNodeTools } from "@/lib/node-tools/createNodeTools";
+export type { NodeTools, NodeToolsRef } from "@/lib/node-tools/types";
+export { createViewport } from "@/lib/viewport/createViewport";
+export type { Viewport, ViewportRef } from "@/lib/viewport/types";

package/dist/lib/canvas/createCanvasObserver.d.ts

@@ -0,0 +1,2 @@
+import type { CanvasObserver } from "./types";
+export declare function createCanvasObserver(): CanvasObserver;

package/dist/lib/canvas/disableCanvasKeyboard.d.ts

@@ -0,0 +1 @@
+export declare const disableCanvasKeyboard: () => void;

package/dist/lib/canvas/enableCanvasKeyboard.d.ts

@@ -0,0 +1 @@
+export declare const enableCanvasKeyboard: () => void;

package/dist/lib/canvas/helpers/applyCanvasState.d.ts

@@ -0,0 +1 @@
+export declare const applyCanvasState: () => void;

package/dist/lib/canvas/helpers/getCanvasContainer.d.ts

@@ -0,0 +1 @@
+export declare const getCanvasContainer: () => HTMLElement | null;

package/dist/lib/canvas/helpers/getCanvasWindowValue.d.ts

@@ -0,0 +1 @@
+export declare const getCanvasWindowValue: (path: string[]) => any;

package/dist/lib/helpers/index.d.ts

@@ -0,0 +1 @@
+export { withRAF, withRAFThrottle } from "./withRAF";

package/dist/lib/helpers/observer/connectMutationObserver.d.ts

@@ -0,0 +1 @@
+export declare const connectMutationObserver: (element: HTMLElement, handler: (mutations: MutationRecord[]) => void) => MutationObserver;

package/dist/lib/helpers/observer/connectResizeObserver.d.ts

@@ -0,0 +1 @@
+export declare const connectResizeObserver: (element: HTMLElement, handler: (entries: ResizeObserverEntry[]) => void) => ResizeObserver;

package/dist/lib/helpers/withRAF.d.ts

@@ -0,0 +1,4 @@
+export declare function withRAF(operation: () => void): () => void;
+export declare function withRAFThrottle<T extends (...args: any[]) => void>(func: T): T & {
+    cleanup: () => void;
+};

package/dist/lib/node-tools/createNodeTools.d.ts

@@ -0,0 +1,2 @@
+import type { NodeTools } from "./types";
+export declare const createNodeTools: (element: HTMLElement | null) => NodeTools;

package/dist/lib/node-tools/events/click/handleNodeClick.d.ts

@@ -0,0 +1 @@
+export declare const handleNodeClick: (event: MouseEvent, nodeProvider: HTMLElement | null, editableNode: HTMLElement | null, onNodeSelected: (node: HTMLElement | null) => void) => void;

package/dist/lib/node-tools/events/setupEventListener.d.ts

@@ -0,0 +1 @@
+export declare const setupEventListener: (nodeProvider: HTMLElement | null, onNodeSelected: (node: HTMLElement | null) => void, onEscapePressed: () => void, getEditableNode: () => HTMLElement | null) => (() => void);

package/dist/lib/node-tools/highlight/clearHighlightFrame.d.ts

@@ -0,0 +1 @@
+export declare const clearHighlightFrame: (nodeProvider: HTMLElement | null) => void;

package/dist/lib/node-tools/highlight/createHighlightFrame.d.ts

@@ -0,0 +1 @@
+export declare const createHighlightFrame: (node: HTMLElement, nodeProvider: HTMLElement) => HTMLElement;

package/dist/lib/node-tools/highlight/createTagLabel.d.ts

@@ -0,0 +1 @@
+export declare const createTagLabel: (node: HTMLElement, nodeTools: HTMLElement) => void;

package/dist/lib/node-tools/highlight/createToolsContainer.d.ts

@@ -0,0 +1 @@
+export declare const createToolsContainer: (node: HTMLElement, highlightFrame: HTMLElement) => void;

package/dist/lib/node-tools/highlight/helpers/getElementBounds.d.ts

@@ -0,0 +1,6 @@
+export declare function getElementBounds(element: Element, nodeProvider: HTMLElement): {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+};

package/dist/lib/node-tools/highlight/helpers/getHighlightFrameElement.d.ts

@@ -0,0 +1 @@
+export declare function getHighlightFrameElement(nodeProvider: HTMLElement): HTMLElement | null;

package/dist/lib/node-tools/highlight/highlightNode.d.ts

@@ -0,0 +1 @@
+export declare const highlightNode: (node: HTMLElement | null, nodeProvider: HTMLElement) => void;

package/dist/lib/node-tools/highlight/refreshHighlightFrame.d.ts

@@ -0,0 +1 @@
+export declare const refreshHighlightFrame: (node: HTMLElement, nodeProvider: HTMLElement) => void;

package/dist/lib/node-tools/select/constants.d.ts

@@ -0,0 +1 @@
+export declare const IGNORED_DOM_ELEMENTS: string[];

package/dist/lib/node-tools/select/helpers/getElementsFromPoint.d.ts

@@ -0,0 +1 @@
+export declare const getElementsFromPoint: (clickX: number, clickY: number) => Element[];

package/dist/lib/node-tools/select/helpers/targetSameCandidates.d.ts

@@ -0,0 +1 @@
+export declare const targetSameCandidates: (cache: Element[], current: Element[]) => boolean;

package/dist/lib/node-tools/select/selectNode.d.ts

@@ -0,0 +1 @@
+export declare const selectNode: (event: MouseEvent, editableNode: HTMLElement | null) => HTMLElement | null;

package/dist/lib/node-tools/text/events/setupKeydownHandler.d.ts

@@ -0,0 +1 @@
+export declare const setupKeydownHandler: (node: HTMLElement) => (() => void);

package/dist/lib/node-tools/text/events/setupMutationObserver.d.ts

@@ -0,0 +1 @@
+export declare const setupMutationObserver: (node: HTMLElement, nodeProvider: HTMLElement) => (() => void) | undefined;

package/dist/lib/node-tools/text/events/setupNodeListeners.d.ts

@@ -0,0 +1 @@
+export declare const setupNodeListeners: (node: HTMLElement, nodeProvider: HTMLElement | null, blur: () => void) => (() => void);

package/dist/lib/node-tools/text/helpers/hasTextContent.d.ts

@@ -0,0 +1 @@
+export declare const hasTextContent: (node: HTMLElement) => boolean;

package/dist/lib/node-tools/text/helpers/insertLineBreak.d.ts

@@ -0,0 +1 @@
+export declare const insertLineBreak: () => void;

package/dist/lib/node-tools/text/helpers/makeNodeEditable.d.ts

@@ -0,0 +1 @@
+export declare const makeNodeEditable: (node: HTMLElement) => void;

package/dist/lib/node-tools/text/helpers/makeNodeNonEditable.d.ts

@@ -0,0 +1 @@
+export declare const makeNodeNonEditable: (node: HTMLElement) => void;

package/dist/lib/node-tools/text/nodeText.d.ts

@@ -0,0 +1,2 @@
+import type { NodeText } from "./types";
+export declare const nodeText: () => NodeText;

package/dist/lib/post-message/handlePostMessage.d.ts

@@ -0,0 +1 @@
+export declare const handlePostMessage: (event: MessageEvent) => void;

package/dist/lib/post-message/sendPostMessage.d.ts

@@ -0,0 +1 @@
+export declare function sendPostMessage(action: string, data: unknown): void;

package/dist/lib/viewport/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const DEFAULT_WIDTH = 400;
+export declare const RESIZE_CONFIG: {
+    readonly minWidth: 320;
+    readonly maxWidth: 1680;
+};

package/dist/lib/viewport/createViewport.d.ts

@@ -0,0 +1,2 @@
+import type { Viewport } from "./types";
+export declare const createViewport: (container: HTMLElement) => Viewport;

package/dist/lib/viewport/events/setupEventListener.d.ts

@@ -0,0 +1 @@
+export declare const setupEventListener: (resizeHandle: HTMLElement, startResize: (event: MouseEvent) => void, handleResize: (event: MouseEvent) => void, stopResize: (event: MouseEvent) => void, blurResize: () => void) => (() => void);

package/dist/lib/viewport/resize/createResizeHandle.d.ts

@@ -0,0 +1 @@
+export declare const createResizeHandle: (container: HTMLElement) => HTMLElement;

package/dist/lib/viewport/width/calcConstrainedWidth.d.ts

@@ -0,0 +1 @@
+export declare const calcConstrainedWidth: (startWidth: number, deltaX: number) => number;

package/dist/lib/viewport/width/calcWidth.d.ts

@@ -0,0 +1 @@
+export declare const calcWidth: (event: MouseEvent, startX: number, startWidth: number) => number;

package/dist/lib/viewport/width/updateWidth.d.ts

@@ -0,0 +1 @@
+export declare const updateWidth: (container: HTMLElement, width: number) => void;

package/dist/lib/window/bindToWindow.d.ts

@@ -0,0 +1 @@
+export declare const bindToWindow: <T>(key: string, value: T) => void;