Literal 0.8.3

clock(interval)

If interval is a number, returns a stream of DOM timestamps at interval seconds apart.

${ clock(1).map(floor) }

If duration is "frame", returns a stream of DOM timestamps of animation frames.

${ clock('frame').map((time) => time.toFixed(2)) }

events(type, element)

Returns a mappable stream of events heard on element.

${ events('click', element).map((e) => e.target.id) }

The first parameter may alternatively be a select object. It must have a .type property.

${ events({ type: 'click' }, element).map((e) => e.target.id) }

The object may contain a number of other properties that select the events received. It supports the standard addEventListener options, for passive and capture phase event binding.

${ events({ type: 'scroll', passive: true, capture true }, window)
   .map((e) => window.scrollTop) }

And a .select property, a CSS selector, that filters events to those with targets that match or have a closest() ancestor that matches the selector.

${ events({ type: 'click', select: '[name="button"]' }, element)
   .map((e) => e.target.id) }

However, if you need to delegate events it is recommended to use the delegate() function, which has the added benefit of direct access to the delegated target.

${ events('click', element).each(delegate({
    '[name="button"]': (target, e) => console.log(target.id),
    '[name="remove"]': (target, e) => document.getElementById(target.value).remove(),
    ...
})) }

Stopping an event stream removes event listeners.

${ events('click', element).stop() }

But streams returned from template expressions, like this one, are stopped automatically when the renderer is stopped, so normally there is no need to worry about managing them.

observe(path, object)

Returns a stream of values at path in object. Values are sent whenever the Data() proxy of object is mutated.

${ observe('path.to.value', data).each(() => {...}) }

TODO: warning, this function is probably going to be renamed as mutations(), updates() or changes().

assign(a, b, …)

Alias of Object.assign().

by(fn, a, b)

For sorting arrays. Compares fn(a) against fn(b) and returns -1, 0 or 1. Partially applicable. To sort an array of objects by their ids:

array.sort(by(get('id')))

ceil(n)

Alias of Math.ceil().

clamp(min, max, n)

Clamps number n to the limits min to max. Values of n lower than min return min, and those higher than max return max.

delegate(map)

Takes an object map of functions keyed to selectors, and returns a function that handles event objects, delegating them to the first function whose selector matches the event target. Functions are passed the target node and the event object, plus any other arguments passed to the handler.

delegate({
    'button': (button, event) => {}
})

denormalise(min, max, value)

entries(object)

Alias of Object.entries().

equals(a, b)

Compares a and b for deep equality and returns true where they are equal, otherwise false.

floor(n)

Alias of Math.floor().

frame(fn)

Alias of window.requestAnimationFrame(fn). Aliased for brevity inside templates.

get(path, object)

Gets the value of path in object, where path is a string in JS dot-notation. Where a path does not lead to a value, returns undefined:

${ get('path.to.value', data) }

Numbers are accepted as path components:

${ get('array.0', data) }

getValue(element)

TODO

id(value)

Returns value.

include(src, data)

Includes a template identified by src, passing in an object to render in that template as data. In production it is recommended that src is a fragment identifier referring to the id of a template already in the DOM:

${ include('#another-template', data) }

The include function is partially applicable, making it easy to use for looping over an array to return an array of rendered templates:

${ data.array.map(include('#list-item')) }

isDefined(value)

Check for defined value. where value is undefined, NaN or null, returns false, otherwise true.

keys(object)

Alias of Object.keys().

last(array)

Returns the last value in an array.

matches(selector, object)

For filtering and pattern matching. Returns true where all the properties of selector object are strictly equal to the same properties of object. Note that object may have more properties than selector.

const vegetarian = menu.filter(matches({ vegetable: true }));

navigate(url)

Navigate to a url, alerting the history API where pertinent. Takes optional parameters:

navigate(url, state, scroll)

TODO: better description!

noop()

Does nothing, returns undefined.

normalise(min, max, value)

overload(fn, object)

Returns an overloaded.

Takes a fn that returns a string key, and an object of key:function pairs. The returned function calls fn with all arguments to get a key, then calls the function at object[key] with all arguments.

Where fn returns undefined, object.default is called if it is defined in object, otherwise overload throws a ‘no function defined for key’ error.

var handleEvent = overload(get('type'), {
    click:   (e) => {...},
    input:   (e) => {...},
    default: (e) => {...}
});

paramify(object)

Turns an object with enumerable properties into a native URL search parameters object. Rejects undefined properties and flattens out array values.

print(data)

Prints an object or objects to the DOM as a debug message.

<template is="literal-html" data="../../package.json">
    ${ print(data) }
</template>

Renders as:

rect(element)

A shortcut for element.getBoundingClientRectangle(). Returns a DOMRect object with left, top, width and height properties.

remove(array, value)

Remove value from array. Where value is not in array, does nothing.

request(method, url)

Uses fetch() to send a request to url. Returns a promise.

${ request('get', '../documentation/modules/package.json').then(get('author')) }

To send data with the request:

${ request('post', url, data).then(...) }

(Where type is "GET", data is serialised and appended to the URL, otherwise it is sent as a request body.)

A 4th parameter may be a content type string or a headers object (in which case it must have a 'Content-Type' property).

${ request('post', url, data, {...}).then(...) }

round(value)

Round value to the nearest integer.

round(value, n)

Round value to the nearest multiple of n.

slugify(string)

Replaces any series of non-word characters with a '-' and lowercases the rest.

    slugify('Party on #mydudes!') // 'party-on-mydudes'

sum(a, b)

Returns the sum of b + a.

translate(key)

Looks up an alternative value stored by key in a window.translations object, if it exists. A super simple translation mechanism that requires window.translations to be an object.

${ translate('Go to homepage') }

trigger(type, node)

Triggers event of type on node. Returns false if the event default was prevented, otherwise true.

trigger('activate', node);

Alternatively the first argument may be an object with a type property, and optionally detail, which must be an object, and bubbles, cancelable and composed options, which determine the behaviour of the event.

trigger({
    type:       'activate',
    detail:     {...},
    bubbles:    true,
    cancelable: true,
    composed:   false
}, node);

px(value)

Takes a number in pixels or a string of the form '10px', '10em', '10rem', '100vw', '100vh', '100vmin' or '100vmax', and returns a numeric value in pixels.

em(value)

Takes numeric value in px, or CSS length of the form '10px', and returns a numeric value in em, eg. 0.625. Depends on the user defined browser font-size.

rem(value)

Takes numeric value in px, or CSS length of the form '10px', and returns a numeric value in rem, eg. 0.625. Depends on the font-size of the documentElement.

vw(value)

Takes number in pixels or CSS length of the form '10em' and returns a numeric value in vw, eg. 120. Depends on the width of the viewport at render time.

vh(value)

Takes number in pixels or CSS length of the form '10em' and returns a numeric value in vh, eg. 120. Depends on the height of the viewport at render time.