Scrawl-canvas — Demo tests
(For version 8.16.0)
- Documentation links
- Developer Runbook «
- Inline documentation «
The Scrawl-canvas library makes it easier to create and use <canvas> presentations and scenes in a web page. Canvases discovered on a page, or added to it, will be enhanced by the library to help make them more responsive and accessible, and easy to interact with.
These demos represent the library's testing suite. They have been designed to cover as much functionality as possible in sets of integration tests. Testing is (currently) conducted by hand: all demos must run as expected before changes can be pushed to the library's v8 branch on GitHub.
Additional (non-testing) demos can be found in this CodePen collection.
Core functionality tests:
Scrawl-canvas helps developers build graphical representations and scenes that are real-time responsive to their DOM environment, and easier to make accessible to non-visual technology. The coding paradigm encourages developers to split their code into ES6 modules: this makes code easier to maintain and easier to reuse.
In essence, Scrawl-canvas represents a system to define a set of graphical entitys and their associated styles (colors, gradients, patterns) and assets (images, spritesheets, video, media stream, noise, other canvas elements), then position (absolutely, relatively, by reference to other entitys) and animate them (by delta, by tween) across the canvas - often in response to user interaction. Animation can also be extended to styles and asset display.
Entitys include:
- Basic shapes such as rectangles (Block), circles (Wheel, Crescent) and text (Label).
- Wheel entitys also include part-circle shapes such as pie slices and truncated circles.
- CSS font strings are supported as far as possible, including font-sizes declared using suffixes such as 'em', 'rem', 'vw', 'pt', etc.
- Path-defined entitys (Shape), and a range of pre-defined, path-based entitys (Bezier, Cog, Line, LineSpiral, Oval, Polygon, Polyline, Quadratic, Rectangle, Spiral, Star, Tetragon).
- Line, Quadratic, and Bezier entitys can have their start, end and control coordinates positioned absolutely, relatively, or by reference to other entitys (including along paths).
- Images, video and related pixel-based image streams (Picture), both in whole and in part; the proportion of the image displayed can be controlled and animated.
- Compound entitys built on top of other entitys which can be used to combine the output of images in various ways (Grid) or distort image output (Loom, Mesh).
- Multi-line, styled text layout using the EnhancedLabel entity, which uses other artefacts as a template for defining how and where its text will display.
Entitys can be stamped onto the canvas in a variety of ways:
- They can be scaled, rotated and flipped as required.
- They can take Color, Gradient, RadialGradient, and ConicGradient styles for both their fill and stroke styling.
- All gradient styles can be bound to their containing cell, or to particular entitys.
- Entitys can accept all legitimate CSS color strings – rgb-key, rgb-hex, rgb(), rgba(), hsl(), hsla(), hwb(), lch(), lab(), oklch(), oklab(), color() – for their fillStyle, strokeStyle and shadowColor input.
- Wide-gamut color can be displayed on devices that support them.
- Color factories (and thus gradient styles) can work with RGB, HSL, HWB, LAB, LCH, OKLAB and OKLCH color spaces internally, and export CSS color strings for each of those spaces; Color factories support color ranges. This extends to gradients, which can spread colors defined in any supported color space.
- Color factories, and gradient styles, can have easing algorithms applied to them – eased linear gradients.
- They can also take Pattern styles which may contain a variety of image-based assets; patterns can be scaled, skewed and positioned as required.
- Entitys can also act as clipping zones for subsequent drawing activities.
- The visual assets used by Picture entitys and Pattern styles can include fully responsive <img> elements (with a srcset attribute), or image files.
- <video> and <canvas> element assets are also supported, as are spritesheet animations. Video can accept media streams (such as device cameras) and screen capture streams as input for displaying in a canvas.
- Scrawl-canvas includes a NoiseAsset asset (for Perlin, Simplex, Worley, etc, noise generation), alongside an RdAsset reaction-diffusion asset (for more organic patterns).
- Third-party image/video asset generators (for example MediaPipe, TensorFlow, Lottie) can be accommodated using the RawAsset asset.
Scrawl-canvas treats additional canvas Cells (layers) in the same way as it treats entitys:
- Cells can be positioned like entitys (absolutely, relatively, by reference); they can be scaled, rotated and flipped; they can be animated — including along paths.
- Like the base canvas, Cells can track mouse/touch interactions and movements, which allows users to interact with entitys displayed on the Cell.
Drag zones
Drag zones
Responsive canvas
Responsive canvas
Library purge
Label and EnhancedLabel entity tests
As of Scrawl-canvas v8.13.0, the Phrase entity has been deprecated and removed from the library. The new Label and EnhancedLabel entitys replace it. All demos that previously used Phrase entitys have been updated to use these new entitys.
Filters functionality tests
The Scrawl-canvas filters functionality is inspired by SVG filters. Filter operations can be ordered in ways to combine different sets of operations to achieve complex effects. The library comes with an extensive set of pre-built filters, including:
- color and alpha channel manipulations;
- matrix, pixellate, blur;
- compositing and blending operations;
- palette reduction and dithering;
- image and noise asset upload (for use with composites and blends); and
- gradient, and displacement, mapping.
Filters can be applied to individual entitys, to Groups of entitys, and also to Cell displays. Entitys can be used to filter the display behind them - stencil filters.
Filters can be animated using Scrawl-canvas tween functionality.
Compound filter tests
CSS/SVG filter String functionality tests
In addition to Scrawl-canvas's extensive filters functionality, the library also supports the CSS filter property. Be aware that CSS and SVG based filters are not currently supported by all browsers (specifically: Safari).
Particles and physics tests
Scrawl-canvas includes a particle-based physics engine. Particle systems (Emitter, Net, Tracer) are treated as entitys and can be positioned and rotated like any other entity.
DOM and Stack tests
Scrawl-canvas <canvas> elements do not live in splendid isolation; the library is aware of each canvas's wider environment:
- Scrawl-canvas treats accessibility as a First Class Issue:
- All canvases have appropriate ARIA tags added to them — including ARIA labels and descriptions.
- Graphical text is (by default) exposed to the DOM, to make it readable to assistive technology. The accessible text can differ from the graphical text, to make more sense to screen readers, and the order in which text is presented to the user can be controlled.
- Graphical navigation is automatically reflected into the DOM via <a> anchor elements which can be triggered using the keyboard. This extends to responding visually to keyboard-driven focus/blur events.
- Navigable actions can be assigned to graphical entitys by means of (hidden) <button> elements which, again, can be triggered using the keyboard (including associated focus/blur events).
- Canvases can adapt to user preferences, for instance prefers-reduced-motion and prefers-color-scheme.
- Scrawl-canvas treats responsiveness as a First Class Requirement:
- Scrawl-canvas <canvas> elements are aware of their size and shape, and include functionality to adapt to changes in their dimensions (approximating CSS container queries functionality). Canvases can be used safely within CSS grids.
- Canvases also emulate responsive behaviours associated with the CSS object-fit and background-size properties.
- Scrawl-canvas handles changes to asset files in real time — both for changes to the <img src=""> attribute, and browser-controlled actions related to <img srcset=""> when the user changes the browser's viewport size.
- Scrawl-canvas does everything it can to support CSS font and text attributes; this includes support for @font-face fonts loaded from the cloud.
- New <canvas> elements can be added to the web page in real time, and removed when required; Scrawl-canvas includes functionality to help component-based Javascript frameworks (eg: React, Svelte) use canvases more efficiently and safely.
- Functionality is included to easily add and/or remove event listeners to canvas elements, and also other elements which can be used to control the canvas display — for instance to help make the canvas scene/animation more accessible to assistive technology and keyboard users.
- Scrawl-canvas <canvas> elements can be made to respond to touch events; canvases can be made to remain static while dragging entitys, but follow browser-based touch actions (such as page scrolling) at other times.
- The Scrawl-canvas animation loop can also be stopped and restarted as required. In addition, <canvas> elements can be defined to only run their animations when they are visible in the browser viewport (via intersection observers) — canvases automatically track their position in, and movement through, the viewport.
Scrawl-canvas stacks extend the library's unique positioning, manipulation and animation functionality to DOM elements. This allows us to combine stacks and canvases so that DOM elements can be used to position canvas entitys, and give us the power to animate DOM elements along path-based entitys. It also gives users the power to interact with <canvas> elements rotated in 3D space.
Drag zones
Packet code tests
Many Scrawl-canvas objects can be saved to JSON strings known as packets, and restored from them. Scrawl-canvas clone functionality is built on top of its packet functionality; every demo that invokes a clone call on a Scrawl-canvas artefact or object is also testing that artefact/object's packet functionality. Similarly, many demos test object kill functionality, using packets to restore the objects after they have been killed.
Module code tests
Scrawl-canvas code is easy to use in ES6 modules.
Modular code, and the ability to kill and restore Scrawl-canvas objects, becomes important when using Scrawl-canvas in framework environments such as React or Svelte.
Responsive canvas
Keyboard zones
Snippet code tests
Scrawl-canvas snippets (warning: experimental!) are module-based functions which can be imported into any other code and applied to DOM elements. The functions add a canvas to the DOM element to act as its background, allowing complex displays and animations to be added to the element.
The results are similar to the Houdini CSS Paint API, though the path to achieving those results is different.
Snippet canvases are responsive: a well-written snippet will be able to adapt to changes in its host element's position, dimensions and styling attributes in real time, and should be able to tidy up after itself if its host element gets removed from the web page (for instance when it is part of a component).
The idea behind the snippets functionality is to allow third party developers to develop code Snippets which other developers can then import and apply in their own sites. Note that there are inherent dangers in this approach: it is always safer to host and review snippets code yourselves, to minimize the opportunities for third parties to inject malicious code into unsuspecting websites!
Responsive canvas
Keyboard zones
Third party library experiments
Scrawl-canvas can work with third party Javascript libraries as well as vanilla Javascript code. The demos below use the following libraries and technologies:
- Delaunator - An incredibly fast and robust JavaScript library for Delaunay (and Voronoi) triangulation of 2D points
- MediaPipe - cross-platform, customizable machine learning solutions for live and streaming media
- TensorFlow - an end-to-end open source platform for machine learning
In addition some of the other Demos, and CodePen examples, make use of third party libraries:
- Demos Canvas 009 and DOM 006 include examples of using Google Analytics with a canvas/stack animation.
- Demo Modules 004 dynamically imports the Adobe After Effects Bodymovin plugin, and uses it to play a Lottie animation.
- The CodePen cloth demo uses the Matter.js physics engine.
