@diesdasdigital/js-canvas-library
v2.0.0
Published
This is a JS library to create canvas based applications using the Elm Architecture.
Downloads
9
Keywords
Readme
JS Canvas Library
This is a JS library to create canvas based applications using the Elm Architecture.
Installation
To install all dependencies run:
yarn add @diesdasdigital/js-canvas-library
Usage
Here is a basic example of rendering a rectangle using the library. Its color will change as soon as the user clicks the button.
An example highlighting subscriptions and fetching data can be found in example.js
.
import { canvas } from "@diesdasdigital/js-canvas-library";
function init(flags, meta) {
const model = {
color: "red",
viewport: meta.viewport,
};
const cmds = [];
return [model, cmds];
}
const msg = {
userClickedOnButton: () => ({
type: "userClickedOnButton",
}),
};
function update(_msg, model) {
switch (_msg.type) {
case "userClickedOnButton":
return [{ ...model, color: "green" }, [scheduleCustomSideEffect()]];
default:
return [model, []];
}
}
function view(context, model) {
const SIZE = 20;
const HALF = 0.5;
context.fillStyle = model.color;
context.fillRect(
model.viewport.width * HALF - SIZE * HALF,
model.viewport.height * HALF - SIZE * HALF,
SIZE,
SIZE
);
}
function subscriptions() {
return [];
}
const send = canvas(
document.querySelector(".canvas"),
{} // <- flags
)({
init,
view,
update,
subscriptions,
});
document.querySelector(".button").addEventListener("click", () => {
send(msg.userClickedOnButton());
});
Available commands and subscriptions
Commands
Commands can be returned as the second item in the array retured in each update case, eg
return [model, [command1, command2…]]
request
The request
command is a minimal wrapper of the browser’s fetch
function. The first two
arguments are the same as in fetch: url and request options. The additional third and fourth
arguments are message which are dispatched when the request succeeds or fails. request
will
throw an error if not all 4 arguments are passed to make sure success and error case are handled.
import { request } from "@diesdasdigital/js-canvas-library";
request(
"https://example.com/",
options,
successMessage,
errorMessage
),
Custom commands
In case one needs to send a custom message inside update
it is possible to do so by calling the
message function like a command:
return [model, [msg.doSomething]];
This is handy in case message should be dispatched after state has been updated or based on a state change without a user interaction.
It can also be used to handle side effects, for example to send a message which then is handled in update
and only performs a side effect without changing the model. Please talk to Max, if you need more than the request
side effect. There is a good chance it can be added to the library.
Subscriptions
Built-in subscriptions for some events can be imported from the library.
import { events } from "@diesdasdigital/js-canvas-library";
onMouseMove
The message passed to onMouseMove
will receive an object { x, y }
with the
mouse coordinates relative to the canvas element. x = 0; y = 0
is equivalent to
having the mouse on the top left corner of the canvas. The function receiving this
object in the example below is msg.updateMouse
.
function subscriptions() {
return [events.onMouseMove(msg.updateMouse)];
}
onAnimationFrame
The message passed to onAnimationFrame
will receive the timestamp of the animation
frame as an argument. (in the example code below that function is msg.tick
)
function subscriptions() {
return [events.onAnimationFrame(msg.tick)];
}
Contributing
Requirements
Note: all of the following commands should be run in the project’s folder.
Clone the repository and run:
yarn
To open the example page while development you can run:
yarn dev
Linting should run automatically when pushing. To lint your code manually run:
yarn lint
License
Allowed to be used by people at diesdas and its creator.
Publishing as a package
Login as diesdas using the credentials provided in 1Password and run:
yarn publish . --access=public