API

Everything is exported from index.js, plus the modules below for finer use. There are no classes to construct.

mount(element, spec, { p5 })

Validates the spec, builds the plan, and draws it into a new figure appended to element. Returns a handle.

Argument	Meaning
`element`	A DOM element to append the picture to.
`spec`	A spec object. Refused with a list of problems if invalid.
`{ p5 }`	The p5 constructor. Required; there is no global lookup.

The handle has three properties:

plan: the drawing plan, see buildPlan.
description: the text alternative.
destroy(): removes the picture and its caption.

It throws a TypeError with a message that lists every problem when the spec is invalid. Call it from the browser: it needs a document.

validateSpec(spec)

Returns an array of problem strings. Empty means valid. It never throws, even for junk input, so it is safe to call on untrusted data.

validateSpec({ version: 1, seed: -1, canvas: { width: 8, height: 8 }, elements: [] });
// [ "seed: must be an integer from 0 to 4294967295",
//   "canvas.width: integer from 16 to 4096",
//   "canvas.height: integer from 16 to 4096" ]

assertValidSpec(spec)

Returns the spec if valid, otherwise throws a TypeError. The error has a problems array.

buildPlan(spec)

Pure. Validates the spec and returns { width, height, themeName, theme, ops }, where ops is the ordered list of drawing operations in pixels. The same spec always gives the same plan, so you can test a picture without a browser.

buildPlan(spec).ops[0];
// { op: "background", colour: "#fbfaf7" }

describePlan(plan, spec)

Returns the sentence used as the text alternative. It counts elements by type and adds the number of generated dots.

createRng(seed)

The seeded generator the library uses. Returns next() (a number from 0 up to but not including 1), range(min, max) and int(min, max). Exposed so your own code can draw the same random numbers as a spec.

Themes

THEMES: the two theme tables, keyed light and dark.
TOKENS: the five token names.
resolveTheme(name): a copy of a theme table. Throws for an unknown name.
contrast(a, b), luminance(hex), parseHex(hex): WCAG helpers.

Policy

MAX_SPEC_BYTES, MAX_ELEMENTS, MAX_POINTS: the limits in the spec reference.
sandboxCsp(scriptSrc): the Content-Security-Policy string for a sandboxed frame. Reserved for a future code mode. Not used by the spec renderer.

Import paths

import { mount, validateSpec, buildPlan, describePlan } from "p5loom";
import { createRng } from "p5loom/rng";
import { THEMES, contrast } from "p5loom/theme";

Subpath imports are spec, plan, theme, rng and policy. Until the package is on npm, import from the src/ files directly.