scratchblocks-ts

A small TypeScript wrapper around scratchblocks. It renders scratchblocks as SVG or PNG and additionally includes helpers for reading them from Markdown.

Installation

npm install scratchblocks-ts

scratchblocks-ts on npm

Rendering

import {
  ScratchblocksRenderer,
  type RenderOptions,
} from "scratchblocks-ts";

const renderer = ScratchblocksRenderer.getInstance();
const options: RenderOptions = {
  languages: ["en"],
  style: "scratch3", // additional options: scratch2, scratch3-high-contrast
  scale: 1.4, // optional, default is 1.0
};

const svg = renderer.toSVG(
  `when green flag clicked
move (10) steps`,
  options
);

document.body.append(svg);

The renderer needs a browser DOM. It keeps rendered SVGs in a cache, so the same instance is used throughout the page.

Inline rendering

Use

const svg = renderer.toInlineSVG("move (10) steps", options);

for a block inside a line of text.

SVG source, raw PNG and <img> output

The other output formats work in the same way:

// returns svg-markup as a string
const svgSource = renderer.toSVGString("move (10) steps", options);

// returns png as a blob
const pngBlob = await renderer.toPNGBlob("move (10) steps", options);

// returns a loaded `<img>` Element with the scratchblock image
const image = await renderer.toPNGImage("move (10) steps", options);

The available styles are scratch2, scratch3, and scratch3-high-contrast.

Markdown

The Markdown helpers do not need a DOM. Fenced blocks can use scratchblock, scratchblocks, or sb:

```scratchblocks
when green flag clicked
move (10) steps
```

import {
  getAllScratchblocksSourcesFromText,
  getInlineScratchblocksSource,
  getScratchblocksSourceAtLine,
} from "scratchblocks-ts/markdown";

const sources = getAllScratchblocksSourcesFromText(markdown);
const sourceAtLine = getScratchblocksSourceAtLine(markdown, 4);
const inlineSource = getInlineScratchblocksSource("sb move (10) steps");

Line numbers are zero-based. The single-source helpers return null if there is no source.

Development

npm install
npm test
npm run build

License

MIT