Migrating to version 1

Version 1 of the js-draw library introduces many new features and several breaking changes. This guide summarizes the breaking API changes and major UI adjustments.

Breaking API change: CSS variables

The CSS variables used to customize js-draw's theme have changed.

Comparison between old and new CSS variables

Old CSS variables:

• --primary-background-color: Background color of the editor, toolbar, and menus
• --primary-foreground-color: Text/icon color of the content of the toolbar and menus
• --secondary-background-color: Background color of selected items
• --secondary-foreground-color: Text/icon color of selected items
• --primary-shadow-color: Color of shadows

New CSS variables:

• --background-color-1: Background color of the editor and some dialogs
• --foreground-color-1: Text/icon color of the editor and some dialogs
• --background-color-2: Background color of the main toolbar content
• --foreground-color-2: Text/icon color of the main toolbar content
• --background-color-3: Background color of action buttons in the toolbar and some toolbar widgets
• --foreground-color-3: Text/icon color of action buttons in the toolbar
• --selection-background-color: Background color of selected content
• --selection-foreground-color: Foreground color of selected content
• --shadow-color: Color used for shadows
• --background-color-transparent: A partially-transparent background color used for overlays
• --primary-action-foreground-color: Color used for inputs/action buttons in the toolbar (e.g. a submit button).

Try the different CSS variables below:

:root .imageEditorContainer {
    /* Used for unselected buttons and dialog text. */
	--background-color-1: white;
	--foreground-color-1: black;

	/* Used for some menu/toolbar backgrounds. */
	--background-color-2: #f5f5f5;
	--foreground-color-2: #2c303a;

	/* Used for other menu/toolbar backgrounds. */
	--background-color-3: #e5e5e5;
	--foreground-color-3: #1c202a;

	/* Used for selected buttons. */
	--selection-background-color: #cbdaf1;
	--selection-foreground-color: #2c303a;

	/* Used for dialog backgrounds */
	--background-color-transparent: rgba(105, 100, 100, 0.5);

	/* Used for shadows */
	--shadow-color: rgba(0, 0, 0, 0.5);

	/* Color used for some button/input foregrounds */
	--primary-action-foreground-color: #15b;
}

---ts---
import { Editor, makeEdgeToolbar, makeDropdownToolbar } from 'js-draw';
import 'js-draw/styles';
import { MaterialIconProvider } from '@js-draw/material-icons';



const makeToolbar = (newToolbar: boolean, editor: Editor) => {
	const toolbar = newToolbar ? makeEdgeToolbar(editor) : makeDropdownToolbar(editor);
	toolbar.addDefaults();

	toolbar.addExitButton(() => {
		alert('Not implemented for this editor!');
	});

	toolbar.addSaveButton(() => {
		const saveData = editor.toSVG().outerHTML;

		// Do something with saveData
		alert('Not implemented for this editor!');
	});

	return toolbar;
};

const makeEditor = async () => {
	const editor = new Editor(document.body, {
		iconProvider: new MaterialIconProvider(),
    	wheelEventsEnabled: 'only-if-focused',
	});

	// Loads from SVG data
	await editor.loadFromSVG(`
		<svg viewBox="0 0 500 500" width="500" height="500" version="1.1" baseProfile="full" xmlns="http://www.w3.org/2000/svg">
			<style id="js-draw-style-sheet">path{stroke-linecap:round;stroke-linejoin:round;}text{white-space:pre;}</style>
			<path d="M500,500L500,0L0,0L0,500L500,500" fill="#e3e3e3" class="js-draw-image-background"></path>
			<text style="transform: matrix(1, 0, 0, 1, 57, 192); font-family: sans-serif; font-size: 32px; fill: rgb(0, 0, 0);">Testing...</text>
		</svg>
	`);

	let isNewToolbar = true;
	let toolbar = makeToolbar(isNewToolbar, editor);



	const toolbarSelector = document.createElement('button');
	toolbarSelector.innerText = 'Change toolbar type';
	document.body.appendChild(toolbarSelector);

	toolbarSelector.onclick = () => {
		isNewToolbar = !isNewToolbar;
		toolbar.remove();

		toolbar = makeToolbar(isNewToolbar, editor);
	};
};

makeEditor();

Breaking UI change: New default toolbar

The toolbar added by .addToolbar() has changed. A version of the original toolbar is still available.

This runnable code block shows how to specify which toolbar should be used and how to switch between them:

import {
	Editor, makeEdgeToolbar, makeDropdownToolbar, AbstractToolbar
} from 'js-draw';
import 'js-draw/styles';

// Also use the new icon pack:
import { MaterialIconProvider } from '@js-draw/material-icons';

let toolbar: AbstractToolbar|null = null
let isDropdownToolbar: boolean = true;

const makeToolbar = (editor: Editor) => {
	// Remove the old toolbar (if any).
	if (toolbar) {
		toolbar.remove();
	}

	// Create the new toolbar
	if (isDropdownToolbar) {
		toolbar = makeDropdownToolbar(editor);
	} else {
		toolbar = makeEdgeToolbar(editor);
	}

	// Add the default action buttons to the toolbar
	toolbar.addDefaults();

	// Add a toggle button
	toolbar.addActionButton({
		// An icon that looks similar to an arrow:
		icon: editor.icons.makeDropdownIcon(),
		label: 'Change toolbar type'
	}, () => {
		isDropdownToolbar = !isDropdownToolbar;
		makeToolbar(editor);
	});

	// Optional: Add save/exit buttons:
	// toolbar.addExitButton(() => { });
	// toolbar.addSaveButton(() => { });

	return toolbar;
};

// Creates the edior and adds it to the document
const makeEditor = () => {
	const editor = new Editor(document.body, {
		iconProvider: new MaterialIconProvider(),
    	wheelEventsEnabled: 'only-if-focused',
	});

	makeToolbar(editor);
};

makeEditor();

In summary, the makeDropdownToolbar and makeEdgeToolbar functions can be imported from js-draw to create different types of toolbars.

Even in the dropdown toolbar, the behavior/appearance of many toolbar widgets are different.

Breaking API change: Different PenTool API

The constructor for the PenTool has changed — rather than accepting the pen's default stroke factory as a separate argument, the factory is a part of the style parameter.

The following demo shows how to create a pen tool:

import {
	Editor, PenTool, PenStyle, Color4,
	makeOutlinedCircleBuilder, makeFreehandLineBuilder
} from 'js-draw';
import 'js-draw/styles';

const editor = new Editor(document.body, {
    wheelEventsEnabled: 'only-if-focused',
});

const penStyle: PenStyle = {
	color: Color4.red,
	// Try changing this to makeFreehandLineBuilder
	factory: makeOutlinedCircleBuilder,
	thickness: 4,
};

editor.toolController.addPrimaryTool(
	new PenTool(editor, 'Some description here', penStyle),
);


// Add the toolbar **after** adding the new tool.
editor.addToolbar();

Breaking API change: Timestamps now use performance.now()

Timestamps attached to events internal to the editor now use performance.now() rather than Date.now(). As such, these timestamps

• are relative to performance.timeOrigin, not the UNIX epoch
• are not integers (but are still in milliseconds).