@yoyoo-ddr/core

Framework-agnostic core engine for DDR (Drag, Resize, Rotate). Zero dependencies, pure TypeScript. Works with vanilla JS, Angular, Svelte, Solid, or any framework capable of handing you a DOM element.

Install

npm i @yoyoo-ddr/core --save

Quick Start

import { DDRCore } from '@yoyoo-ddr/core'
import '@yoyoo-ddr/core/style.css'

const instance = new DDRCore({
  target: document.getElementById('my-element')!,
  value: { x: 100, y: 100, width: 100, height: 100, rotation: 0 },
  config: { draggable: true, resizable: true, rotatable: true, parent: true },
  onChange: (event, transform) => console.log(transform),
})

// Update configuration dynamically
instance.updateConfig({ minWidth: 50, maxWidth: 300 })

// Programmatically set position / size
instance.setValue({ x: 200, y: 100, width: 150, height: 150, rotation: 45 })

// Read current value
const current = instance.getValue()

// Clean up when done
instance.destroy()

Constructor

new DDRCore(options: DDRCoreConstructorOptions)

| Option | Type | Required | Description | |--------|------|----------|-------------| | target | HTMLElement | yes | The element to make draggable/resizable/rotatable | | value | TransformProps | no | Initial position, size and rotation (default: { x:0, y:0, width:100, height:100, rotation:0 }) | | config | Partial<DDRCoreConfig> | no | Configuration overrides (see Config table below) | | onChange | (event, transform) => void | no | Fires on every interaction tick | | onDragStart | (event, transform) => void | no | Drag started | | onDrag | (event, transform) => void | no | Dragging | | onDragEnd | (event, transform) => void | no | Drag ended | | onResizeStart | (event, transform) => void | no | Resize started | | onResize | (event, transform) => void | no | Resizing | | onResizeEnd | (event, transform) => void | no | Resize ended | | onRotateStart | (event, transform) => void | no | Rotate started | | onRotate | (event, transform) => void | no | Rotating | | onRotateEnd | (event, transform) => void | no | Rotate ended |

Public API

updateConfig(partial: Partial<DDRCoreConfig>): void

Update configuration at runtime. Handlers are rebuilt automatically when resizeHandler changes.

setValue(value: TransformProps): void

Programmatically set position, size and rotation.

getValue(): TransformProps

Return a copy of the current transform.

destroy(): void

Remove all event listeners, unwrap the DOM, and clean up.

TransformProps

interface TransformProps {
  x: number       // left offset (px)
  y: number       // top offset (px)
  width: number   // element width (px)
  height: number  // element height (px)
  rotation: number // rotation angle (degrees, 0–360)
}

Config Reference (DDRCoreConfig)

| Property | Type | Default | Description | |----------|------|---------|-------------| | active | boolean | true | Whether the component is active / interactive | | draggable | boolean | true | Enable drag | | resizable | boolean | true | Enable resize | | rotatable | boolean | true | Enable rotation | | resizeHandler | HanlderType[] | ['tl','tm','tr','r','br','bm','bl','l'] | Visible resize handles | | handlerSize | number | 11 | Resize handle size in px | | acceptRatio | boolean | false | Lock aspect ratio during resize (hold Shift to toggle) | | minWidth | number | 1 | Minimum width | | minHeight | number | 1 | Minimum height | | maxWidth | number | 1000000 | Maximum width | | maxHeight | number | 1000000 | Maximum height | | parent | boolean | false | Constrain to parent element bounds | | grid | [number, number] | [1, 1] | Grid snap for drag and resize [x, y] | | axis | 'x' 'y' 'xy' | 'xy' | Restrict drag axis | | zoom | number | 1 | Parent container scale factor (for transform: scale()) | | useCSSTransform | boolean | false | Use transform: translate() instead of left/top for sub-pixel smoothness | | transformOrigin | [number, number] | [0, 0] | Parent transform-origin in CSS pixels, used with zoom | | stop | boolean | true | Stop event propagation | | prevent | boolean | true | Prevent default event behavior | | beforeActive | () => boolean | () => false | Guard called before interaction starts; return true to allow |

Exported Utilities

The package also exports geometry helpers for advanced use:

import {
  getPoints,        // 8-point rotated rect matrix
  getBoundingRect,  // Axis-aligned bounding box of rotated rect
  getSize,          // Resize delta projection
  getHandler,       // Cursor style mapping by rotation
  pointMap,         // Fixed-point indices for resize handlers
  handlerPointMap,  // Handler position indices
} from '@yoyoo-ddr/core'

CSS Classes

| Class | Description | |-------|-------------| | yoyoo-ddr | Wrapper element (always present) | | active | Component is active and ready | | ddr-ready-drag | Hovering over draggable area, ready to drag | | ddr-dragging | Currently dragging | | ddr-ready-resize | Hovering over resize handle, ready to resize | | ddr-resizing | Currently resizing | | ddr-ready-rotate | Hovering over rotate handle, ready to rotate | | ddr-rotating | Currently rotating |

License

MIT