@composy/cropper-core

Framework-neutral image cropper runtime for LDesign. It provides crop box editing, transforms, export helpers, toolbar UI, upload placeholder, filters, history, presets, touch/mobile helpers, accessibility helpers, selection tools, masks, and optional worker-based analysis.

Usage

import { Cropper } from '@composy/cropper-core'
import '@composy/cropper-core/style.css'

const container = document.getElementById('cropper')
if (!container) throw new Error('Cropper container is missing')

const cropper = new Cropper(container, {
  src: '/images/photo.jpg',
  aspectRatio: 16 / 9,
  cropBoxStyle: 'rounded',
  toolbar: {
    position: 'bottom',
    groups: ['file', 'transform', 'zoom', 'ratio', 'actions'],
  },
  styleVars: {
    'color-accent': 'var(--ld-primary-500)',
    'toolbar-button-size': 'var(--ld-px-16)',
  },
})

const canvas = cropper.getCroppedCanvas({
  maxWidth: 1920,
  maxHeight: 1080,
  maxPixels: 2_000_000,
  imageSmoothingQuality: 'high',
})
document.body.append(canvas)

// Persist and replay non-destructive edits.
const graph = cropper.getOperationGraph()
const snapshot = cropper.getSnapshot()
await cropper.applyOperationGraph(graph)
await cropper.restoreSnapshot(snapshot)

Load the global LDesign color and size token styles before the cropper stylesheet. The cropper CSS defaults reference generated --ld-* color and size tokens from packages/color and packages/size.

Public API

• new Cropper(element, options) creates a cropper in an existing container.
• await whenReady() waits for the initial image load and surfaces initialization errors; replace(src), reset(), clear(), destroy() manage lifecycle and image source.
• getData(), setData(), getCropBoxData(), setCropBoxData(), getCanvasData(), setCanvasData(), getContainerData(), getImageData(), setImageData() expose state.
• getSnapshot() and restoreSnapshot() persist the current source, image transform, canvas, crop box, and zoom state with a versioned format.
• getOperationGraph(), applyOperationGraph(), and clearOperationGraph() expose a validated, serializable edit log for replay, collaboration, and batch processing.
• rotate(), rotateLeft(), rotateRight(), scale(), scaleX(), scaleY(), move(), zoomBy(), zoomIn(), zoomOut(), setZoom(), getZoom() transform the image.
• setAspectRatio(), setCropBoxStyle(), setDragMode(), setOptions() update runtime configuration.
• getCroppedCanvas(), getCroppedBlob(), getCroppedDataURL(), download(), copyToClipboard(), getExportFormat() export results.
• getHistoryManager(), getPresetManager(), getWorkerManager(), getSelection(), getMaskManager() expose optional feature managers.

LayerSystem can be used as a standalone multi-layer renderer. Its exportLayers() output is JSON-friendly (the pixel buffer can be a Uint8ClampedArray or a number array), and importLayers() validates dimensions, pixel length, transforms, and layer metadata before applying the snapshot. undo() and redo() restore complete layer snapshots, including the active layer.

FilterEngine.exportConfig() and importConfig() expose the filter chain. Import rejects malformed entries or filters that have not been registered, leaving the current chain unchanged.

Class And Token Contract

All visible runtime classes use the ldesign-cropper namespace, for example ldesign-cropper, ldesign-cropper-container, ldesign-cropper-crop-box, ldesign-cropper-toolbar-button, and state classes such as ldesign-cropper--ready.

Component variables use the --ldesign-cropper-* prefix. Override them through CSS or the styleVars option without the prefix:

cropper.setOptions({
  styleVars: {
    'color-accent': 'var(--ld-primary-500)',
    radius: 'var(--ld-radius-md)',
    'point-size': 'var(--ld-px-4)',
  },
})

Canvas drawing APIs cannot consume unresolved CSS variables directly. The runtime resolves tokenized colors before assigning canvas colors.

maxPixels defaults to a 100 MP safety limit and rejects non-finite or oversized output dimensions. Pass a lower limit for mobile or memory-constrained workflows. Image loading is cancellable and uses the cropper container's ownerDocument, so rapid replace() calls cannot let an older request overwrite the newest image.

Build Outputs

The package uses @composy/builder and emits:

• dist/index.js, dist/index.min.js, dist/index.css, dist/style.css
• es/index.js
• esm/index.js
• lib/index.cjs

Run locally:

corepack pnpm --dir packages/core run type-check
corepack pnpm --dir packages/core run type-check:cjs
corepack pnpm --dir packages/core run build

Builder, TypeScript, and ESLint authority configs live in .ldesign/; the package-root config files remain compatibility entry points. The build script creates the dist/style.css alias from the generated dist/index.css so both existing CSS exports resolve.

Notes

• Placeholder custom SVG icons are sanitized before insertion.
• Toolbar, history, mobile, selection, and placeholder listeners are cleaned up during dynamic rebuilds and destroy().
• Uploaded object URLs are revoked on replacement or destroy.