inkable

A library for creating inking apps.

Installation

npm install inkable
npm install --save-dev inkable

Usage

<script type="module">
  import 'inkable';
</script>

<ink-stroke></ink-stroke>

inkable attribute

Allow users to ink on any element. It listens for pointer events and generates strokes, firing events.

Note: in order to render with low latency on Chromebooks, it creates a transparent overlay. In certain situations, strokes may appear on top of objects while writing and then snap below them when finished.

<div inkable tool="pen" inkable-color="#ff0000" inkable-weight="1"></div>

Import

import 'inkable';

Attributes

• inkable-tool (default: pen) - pen, eraser, none
• inkable-color [pen-only] (default: #000000) - a hex string
• inkable-opacity [pen-only] (default: 1) - a number 0-1
• inkable-weight [pen-only] (default: 2) - number of pixels wide the stroke should be at maximum

Events

• stroke-start - Fired during pointerdown to indicate the inkable will start interpreting the input as a stroke. e.preventDefault() will cancel rendering. Event.detail contains the pointerId and pointerType from the corresponding PointerEvent.
• stroke - Fired when a stroke is completed. Event.detail.stroke is an <ink-stroke>. By default, it will append the stroke to the inkable element. e.preventDefault() will stop it from being automatically added.
• erase (bubbles) - Fired on an element that has been hit be the eraser tool and is about to be removed from the DOM. By default, only InkStroke may be erased. Add eraseable="true" to other elements to allow them to be erased. If eraseable is not set on an element, it defaults to its nearest ancestor's value (if one exists). e.preventDefault() will stop the element from being removed from the DOM.

<ink-stroke>

A single stroke as an HTML Element. Implements FreeformMixin for transforming.

Import

import 'inkable/dist/src/ink-stroke.js';

Attributes

• points - an array of {x,y,p?,t?} objects. p is an optional pressure 0-1.0, and t is an optional timestamp.
• color - a hex string or valid CSS color.
• weight - number of pixels wide the stroke should be at maximum.

<ink-canvas>

A canvas for absolutely positioned elements, including <ink-stroke>. Handles pan/zoom events. Implements FreeformMixin for transforming.

Import

import 'inkable/dist/src/ink-canvas.js';

Attributes

• contain - by default, the InkCanvas itself will move as the user pans/zooms it. Set contain="true" to instead pan/zoom the InkCanvas's contents. (Note: just adding contain will have no effect, must set contain="true")
• width - if not contained, the width of the InkCanvas
• height - if not contained, the height of the InkCanvas

Methods

• animateProps({transform?, width?, height?}, options) - similar to HTMLElement.animate(), but animates the properties of the InkCanvas. Returns a promise that resolves when the animation is complete.

Events

• transform-start - Fired at the start of a transform. Event.detail includes information about the transform (initial matrix, transform matrix, center point, and final matrix), pointerType (same as PointerEvent: mouse, touch, pen), and transformType (idle, pan, pinch-zoom). e.preventDefault() will skip the transform. (Note: expect transformType states to change)
• transform-change - Fired before setting this element's transform to the event's final transform. Same properties as transform-start. e.preventDefault() will skip setting final, or final can be modified. See canvas-plugins/ for examples of ways to modify the event.
• transform-end - Fired at the start of a transform. Same properties as transform-start.

FreeformMixin

Properties

• transform - a Transform object representing a transform on the stroke (see ml-matrix on npm).
• rotation - rotation in degrees (default 0)
• scaleFactor - scale factor (default 1.0)
• translation - translation in pixels (default {x:0,y: 0})

Methods

• transform(Transform) - apply a transform to the element
• rotateBy(degrees) - rotate the element by degrees (clockwise in screen-space)
• scaleBy(factor) - scale the element by factor
• translateBy({x,y}) - translate the element by x and y

Demoing with Storybook

To run a local instance of Storybook for your component, run

npm run storybook

To build a production version of Storybook, run

npm run storybook:build

Linting and formatting

To scan the project for linting and formatting errors, run

npm run lint

To automatically fix linting and formatting errors, run

npm run format

Ensure all imports have .js by searching & replacing:

• Search: ^import (.*) from '(\.(?:(?!js).)+)';$
• Replace: import $1 from '$2.js';

Testing with Web Test Runner

To execute a single test run:

npm run test

To run the tests in interactive watch mode run:

npm run test:watch