Version: 8.14.0 - 1 September 2024
Scrawl-canvas website: scrawl-v8.rikweb.org.uk.
Scrawl-canvas on CodePen: codepen.io/collection/RzzMjw.
Scrawl-canvas on Discord: discord.com/channels/...
Do you want to contribute? Don't be afraid - reach out and let's see what website magic we can create together!
Scrawl-canvas is a Javascript library for working with the HTML5 <canvas> element. The library:
responsive
, adapting their size to their surrounding environment while remaining fully interactive
.accessible
for both keyboard and AT users.https://user-images.githubusercontent.com/5357530/141673995-df239c38-2ba1-43f3-831c-b655524f2f40.mp4
Working with the native Canvas API is hard work - particularly when the desired result is more complex than a couple of coloured boxes in a static display.
But the benefits of using canvases for graphical displays and animations are also great:
Sadly these advantages are also significant barriers:
Scrawl-canvas is fast, and developer-friendly. It's suitable for building infographics, games, interactive videos - whatever we can imagine for a 2D graphical presentation. And it is modular - we can break the code for a particular effect into its own module file which can be reused in other projects.
Scrawl-canvas offers all of this while never losing its hard focus on making the <canvas> element accessible, responsive and fully interactive
while at the same time offering a pleasant developer experience
.
Also, Scrawl-canvas supports developers coding in TypeScript by means of a TS definitions file included in the repository.
There are three main ways to include Scrawl-canvas in your project:
Alternatively, a zip package of the v8.14.0 files can be downloaded from this link: scrawl.rikweb.org.uk/downloads/scrawl-canvas_8-14-0.zip - that package only includes the minified file.
<!-- Hello world -->
<!DOCTYPE html>
<html>
<head>
<title>Scrawl-canvas Hello World</title>
</head>
<body>
<canvas id="my-canvas" data-scrawl-canvas></canvas>
<!-- The library is entirely modular and needs to be imported into a module script -->
<script type="module">
import * as scrawl from './relative-or-absolute/path/to/scrawl-canvas/min/scrawl.js';
// Get a handle to the canvas element
let canvas = scrawl.findCanvas('my-canvas');
// Setup the scene to be displayed in the canvas
scrawl.makeLabel({
name: 'hello',
start: [20, 20],
text: 'Hello, World!',
fontString: 'bold 40px Garamond, serif',
});
// Render the canvas scene once
canvas.render();
</script>
</body>
</html>
This will pull the requested npm package directly into your web page:
<script type="module">
import * as scrawl from 'https://unpkg.com/scrawl-canvas@8.14.0';
[...]
</script>
// either
$> npm install scrawl-canvas
// or
$> yarn add scrawl-canvas
// then in your script file
import * as scrawl from 'scrawl-canvas';
// Scrawl-canvas has no dependencies
// - it can be used as-is, with no further installation steps required
After forking this repo down to your local machine, cd
into the scrawl-canvas folder, run yarn install
or npm install
(for the local build toolchain - the library itself has no external dependencies) and start a local server.
$> cd ./path/to/Scrawl-canvas/folder
$> yarn install
$> yarn dev
The code base does not include any unit testing frameworks. Instead, we rely on a set of Demo tests which allow us to perform integration testing and user interface testing.
Why this approach? Because most of the Scrawl-canvas functionality revolves around various forms of user interaction and animation, which requires visual inspection of the Demo tests to check that the canvas display - and thus, by inference, the underlying code - performs as expected.
Demos that include user interaction allow us to test specific aspects of the code base.
The tool chain includes the ESLint package to impose some basic checks on code. We use the default checks supplied by the package (as indicated in the rules documentation page). To run the linter:
$> yarn lint
The tool chain also includes the Knip package to check for unused files and exports in the source Javascript. To run Knip:
$> yarn knip
Scrawl-canvas supports TypeScript through a TypeScript Definitions (d.ts) file. The definitions file aims to be as accurate, comprehensive and informative as possible, but specifically excludes support for internal (private) SC object attributes and functions.
To view the library's API types, try the tsdocs.dev website.
To aid development, we test the definitions file against the entire suite of Demo code .js files supplied as part of the library. From the root of the project, run the following command:
$> yarn test
The source code has been extensively commented. We generate documentation from that code using Docco. Documentation is regenerated each time the library is rebuilt.
We minify the source code using rollup and its terser plugin.
Running the following command on the command line will recreate the minified file, and regenerate the documentation:
$> yarn build
Developed by Rik Roots: rik.roots@rikworks.co.uk