The Observable notebook standard library.

If you use NPM, npm install @observablehq/notebook-stdlib.

# runtimeLibrary([resolve])

Returns a new standard library object, defining the following properties:

• DOM - create HTML and SVG elements.
• Files - read local files into memory.
• Generators - utilities for generators and iterators.
• Promises - utilities for promises.
• require - load third-party libraries.
• html - render HTML.
• md - render Markdown.
• tex - render TeX.
• now - the current value of Date.now.
• width - the current page width.

If resolve is specified, it is a function that returns the URL of the module with the specified name; this is used internally by require.

# DOM.canvas(width, height)

Returns a new canvas element with the specified width and height. For example, to create a 960×500 canvas:

var canvas = DOM.canvas(960, 500);

This is equivalent to:

var canvas = document.createElement("canvas");
canvas.width = 960;
canvas.height = 500;

# DOM.context2d(width, height[, dpi])

Returns a new canvas context with the specified width and height and the specified device pixel ratio dpi. If dpi is not specified, it defaults to window.devicePixelRatio. For example, to create a 960×500 canvas:

var context = DOM.context2d(960, 500);

If the device pixel ratio is two, this is equivalent to:

var canvas = document.createElement("canvas");
canvas.width = 1920;
canvas.height = 1000;
canvas.style.width = "960px";
var context = canvas.getContext("2d");
context.scale(2, 2);

To access the context’s canvas, use context.canvas.

# DOM.download(object[, name][, value])

Returns an anchor element containing a button that when clicked will download a file representing the specified object. The object should be anything supported by URL.createObjectURL such as a file or a blob.

# DOM.element(name[, attributes])

Returns a new element with the specified name. For example, to create an empty H1 element:

var h1 = DOM.element("h1");

This is equivalent to:

var h1 = document.createElement("h1");

If the name has the prefix svg:, math: or xhtml:, uses document.createElementNS instead of document.createElement. For example, to create an empty SVG element (see also DOM.svg):

var svg = DOM.element("svg:svg");

This is equivalent to:

var svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");

If attributes is specified, sets any attributes in the specified object before returning the new element.

# DOM.input([type])

Returns a new input element with the specified type. If type is not specified or null, a text input is created. For example, to create a new file input:

var input = DOM.input("file");

This is equivalent to:

var input = document.createElement("input");
input.type = "file";

# DOM.range([min, ][max][, step])

Returns a new range input element. (See also DOM.input.) If max is specified, sets the maximum value of the range to the specified number; if max is not specified or null, sets the maximum value of the range to 1. If min is specified, sets the minimum value of the range to the specified number; if min is not specified or null, sets the minimum value of the range to 0. If step is specified, sets the step value of the range to the specified number; if step is not specified or null, sets the step value of the range to any. For example, to create a slider that ranges the integers from -180 to +180, inclusive:

var input = DOM.range(-180, 180, 1);

This is equivalent to:

var input = document.createElement("input");
input.min = -180;
input.max = 180;
input.step = 1;
input.type = "range";

# DOM.select(values)

Returns a new select element with an option for each string in the specified values array. For example, to create a drop-down menu of three colors:

var select = DOM.select(["red", "green", "blue"]);

This is equivalent to:

var select = document.createElement("select");
var optionRed = select.appendChild(document.createElement("option"));
optionRed.value = optionRed.textContent = "red";
var optionGreen = select.appendChild(document.createElement("option"));
optionGreen.value = optionGreen.textContent = "green";
var optionBlue = select.appendChild(document.createElement("option"));
optionBlue.value = optionBlue.textContent = "blue";

For greater control, consider using html instead. For example, here is an equivalent way to define the above drop-down menu:

var select = html`<select>
  <option value="red">red</option>
  <option value="green">green</option>
  <option value="blue">blue</option>
</select>`;

# DOM.svg(width, height)

Returns a new SVG element with the specified width and height. For example, to create a 960×500 blank SVG:

var svg = DOM.svg(960, 500);

This is equivalent to:

var svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
set.setAttribute("viewBox", "0,0,960,500")
svg.setAttribute("width", "960");
svg.setAttribute("height", "500");

# DOM.text(string)

Returns a new text node with the specified string value. For example, to say hello:

var hello = DOM.text("Hello, world!");

This is equivalent to:

var hello = document.createTextNode("Hello, world!");

# Files.buffer(file)

Reads the specified file, returning a promise of the ArrayBuffer yielded by fileReader.readAsArrayBuffer. This is useful for reading binary files, such as shapefiles and ZIP archives.

# Files.text(file)

Reads the specified file, returning a promise of the string yielded by fileReader.readAsText. This is useful for reading text files, such as plain text, CSV, Markdown and HTML.

# Files.url(file)

Reads the specified file, returning a promise of the data URL yielded by fileReader.readAsDataURL. This is useful for reading a file into memory, represented as a data URL. For example, to display a local file as an image:

Files.url(file).then(url => {
  var image = new Image;
  image.src = url;
  return image;
})

However, note that it may be more efficient to use the synchronous URL.createObjectURL method instead, such as:

var image = new Image;
image.src = URL.createObjectURL(file);
return image;

# Generators.filter(iterator, test)

…

# Generators.input(input)

…

# Generators.map(iterator, transform)

…

# Generators.observe(initialize)

…

# Generators.queue(initialize)

…

# Generators.range([start, ]stop[, step])

…

# Generators.valueAt(iterator, index)

…

# Promises.delay(duration[, value])

…

# Promises.never

A promise that never resolves. Equivalent to new Promise(() => {}).

# Promises.tick(duration[, value])

Returns a promise that resolves with the specified value at the next integer multiple of milliseconds since the UNIX epoch. This is much like Promises.delay, except it allows promises to be synchronized.

# Promises.when(date[, value])

… Note: the current implementation relies on setTimeout, and thus the specified date must be no longer than 2,147,483,647 milliseconds (24.9 days) from now.

# now

The current value of Date.now.

# width

The current width of cells.

# html(strings, values…)

Returns the HTML element or node represented by the specified strings and values. This function is intended to be used as a tagged template literal. For example, to create an H1 element whose content is “Hello, world!”:

var hello = html`<h1>Hello, world!</h1>`;

If the resulting HTML fragment is not a single HTML element or node, is it wrapped in a DIV element. For example, this expression:

var hello = html`Hello, <b>world</b>!`;

Is equivalent to this expression:

var hello = html`<div>Hello, <b>world</b>!</div>`;

# md(strings, values…)

var hello = md`Hello, *world*!`;

# tex(strings, values…)

tex`E = mc^2`

# tex.block(strings, values…)

Equivalent to tex, but uses KaTeX’s display mode to produce a bigger block element rather than a smaller inline element.

tex.block`E = mc^2`

# require(names…)

Returns a promise of the asynchronous module definition (AMD) with the specified names, loaded from unpkg. Each module name can be a package (or scoped package) name optionally followed by the at sign (@) and a semver range. For example, to load d3-array:

require("d3-array").then(d3 => {
  console.log(d3.range(100));
});

Or, to load d3-array and d3-color and merge them into a single object:

require("d3-array", "d3-color").then(d3 => {
  console.log(d3.range(360).map(h => d3.hsl(h, 1, 0.5)));
});

Or, to load d3-array 1.1.x:

require("[email protected]").then(d3 => {
  console.log(d3.range(100));
});

See d3-require for more information.

# resolve(name)

Returns the resolved URL to require the module with the specified name.