Utils

Core utility functions used throughout Formstone.

Methods

Methods

Utils is a module of functions, available as the Utils export (import { Utils } from 'formstone') or individually (import { select, on } from 'formstone/utils'). Most functions that take a target accept an element, a NodeList, an HTMLCollection, an array, a Set or any other iterable collection.

Name	Description
`.addClass()`	Adds class(es) to target(s)
`.after()`	Inserts HTML after a target
`.afterTransition()`	Executes callback once an element's transition completes
`.append()`	Inserts HTML at the end of a target
`.before()`	Inserts HTML before a target
`.camelCase()`	Converts a string to camelCase
`.element()`	Creates a new element
`.extend()`	Deep or shallow merge of objects
`.falsey()`	Checks if a value is "falsey"
`.getAttr()`	Returns an attribute value from an element
`.hasAttr()`	Checks if an element has an attribute
`.hasClass()`	Checks if an element has a class
`.isFn()`	Checks if a value is a function
`.isObj()`	Checks if a value is an object
`.isU()`	Checks if a value is undefined
`.iterable()`	Normalizes an item into an array for iteration
`.iterate()`	Iterates over items
`.normalizeAttrs()`	Normalizes attribute arguments into name/value pairs
`.normalizeClasses()`	Normalizes class name arguments into an array
`.off()`	Removes event listener(s)
`.on()`	Adds event listener(s)
`.once()`	Adds a one-time event listener
`.prepend()`	Inserts HTML at the beginning of a target
`.proto()`	Returns the internal type tag of a value
`.ready()`	Executes callback when DOM is ready
`.removeAttr()`	Removes attribute(s)
`.removeClass()`	Removes class(es) from target(s)
`.restoreAttr()`	Restores an attribute's value
`.select()`	Selects elements via query selector
`.setAttr()`	Sets attribute(s)
`.siblings()`	Returns siblings of an element
`.transitionTime()`	Returns an element's longest transition time
`.trigger()`	Triggers a custom event
`.type()`	Returns the native typeof of an item
`.updateAttr()`	Preserves and updates an attribute

Core

.ready()

Executes a callback when the DOM is ready, or immediately if already loaded.

Parameters

Name	Type	Description
`cb`	`function`	Callback function to execute

Examples

Utils.ready(() =&gt; {
  console.log('DOM is ready');
});

Checks

.type()

Returns the JavaScript type of an item.

Parameters

Name	Type	Description
`item`	`any`	The item to check

Returns

Type	Description
`string`	The type of the item ('string', 'number', 'boolean', 'object', 'function', 'undefined', 'symbol', 'bigint')

.proto()

Returns the internal type tag of a value, from Object.prototype.toString. Useful where typeof isn't specific enough.

Parameters

Name	Type	Description
`item`	`any`	The item to check

Returns

Type	Description
`string`	The type tag (e.g. `'[object Array]'`, `'[object Object]'`, `'[object NodeList]'`)

Examples

Utils.proto([]); // '[object Array]'
Utils.proto(null); // '[object Null]'

.falsey()

Checks if a value is falsey (undefined, false, or null).

Parameters

Name	Type	Description
`v`	`any`	The value to check

Returns

Type	Description
`boolean`	True if the value is undefined, false, or null

.isFn()

Checks if a value is a function.

Parameters

Name	Type	Description
`v`	`any`	Value to check

Returns

Type	Description
`boolean`	True if a function

.isObj()

Checks if a value is an object. Returns false for null.

Parameters

Name	Type	Description
`v`	`any`	Value to check

Returns

Type	Description
`boolean`	True if an object

.isU()

Checks if a value is undefined.

Parameters

Name	Type	Description
`v`	`any`	Value to check

Returns

Type	Description
`boolean`	True if undefined

Objects

.extend()

Extends objects by merging properties from one or more source objects into a new object; the arguments are never modified. A deep merge recurses into plain objects at any depth. Arrays, functions, regular expressions and other non-plain values are copied by reference, not merged. __proto__ keys are ignored.

Parameters

Name	Type	Description
`deep`	`boolean` (optional)	If first argument is boolean, enables deep merge
`...args`	`object`	Objects to merge

Returns

Type	Description
`object`	The extended object

Examples

// Shallow merge
Utils.extend({a: 1}, {b: 2}); // {a: 1, b: 2}

// Deep merge
Utils.extend(true, {a: {x: 1}}, {a: {y: 2}}); // {a: {x: 1, y: 2}}
Utils.extend(true, {a: {b: {x: 1}}}, {a: {b: {y: 2}}}); // {a: {b: {x: 1, y: 2}}}

Selection

.select()

Selects all elements matching a CSS selector.

Parameters

Name	Type	Description
`selector`	`string`	CSS selector string
`context`	`element\|Document` (optional)	Context element or document to search within (defaults to document)

Returns

Type	Description
`NodeList`	NodeList of matching elements

Examples

let buttons = Utils.select('.btn');
let inputs = Utils.select('input', form);

.element()

Creates a new DOM element.

Parameters

Name	Type	Description
`tag`	`string`	The HTML tag name to create

Returns

Type	Description
`element`	The created element

Examples

let div = Utils.element('div');

.siblings()

Gets all sibling elements of a node.

Parameters

Name	Type	Description
`node`	`element`	The element to get siblings for

Returns

Type	Description
`array`	Array of sibling elements

Insertion

.prepend()

Inserts HTML at the beginning of a node.

Parameters

Name	Type	Description
`node`	`element`	The element to insert into
`string`	`string`	The HTML content to insert

Examples

Utils.prepend(container, '<span class="first">First</span>');

.append()

Inserts HTML at the end of a node.

Parameters

Name	Type	Description
`node`	`element`	The element to insert into
`string`	`string`	The HTML content to insert

Examples

Utils.append(container, '<span class="last">Last</span>');

.before()

Inserts HTML before a node.

Parameters

Name	Type	Description
`node`	`element`	The element to insert before
`string`	`string`	The HTML content to insert

Examples

Utils.before(item, '<li class="label">Start</li>');

.after()

Inserts HTML after a node.

Parameters

Name	Type	Description
`node`	`element`	The element to insert after
`string`	`string`	The HTML content to insert

Examples

Utils.after(item, '<li class="label">End</li>');

Iteration

.iterate()

Iterates over a target and executes a callback for each item. Collections (NodeList, HTMLCollection, array, Set and other iterables) are iterated; a single value, string or DOM node is treated as one item; null, undefined and false items are skipped.

Parameters

Name	Type	Description
`target`	`element\|NodeList\|HTMLCollection\|array\|Set\|any`	The target to iterate over
`cb`	`function`	Callback function to execute for each item

.iterable()

Converts a value to an array for iteration. Collections (NodeList, HTMLCollection, array, Set and other iterables) are expanded; a single value, string or DOM node becomes a one-item array (<form> and <select> elements are not expanded into their controls). null, undefined and false items are removed.

Parameters

Name	Type	Description
`target`	`any`	The target to convert (element, collection, or any value)

Returns

Type	Description
`array`	Array of non-falsey items

Events

.on()

Adds event listener(s) to element(s).

Parameters

Name	Type	Description
`target`	`element\|NodeList\|array`	The target element(s)
`event`	`string`	The event name
`cb`	`function`	The event handler callback
`options`	`object\|boolean` (optional)	Event listener options

Examples

Utils.on(button, 'click', handleClick);
Utils.on(Utils.select('.item'), 'mouseenter', handleHover);

.once()

Adds a one-time event listener to element(s).

Parameters

Name	Type	Description
`target`	`element\|NodeList\|array`	The target element(s)
`event`	`string`	The event name
`cb`	`function`	The event handler callback
`options`	`object\|boolean` (optional)	Event listener options

.off()

Removes event listener(s) from element(s).

Parameters

Name	Type	Description
`target`	`element\|NodeList\|array`	The target element(s)
`event`	`string`	The event name
`cb`	`function`	The event handler callback to remove
`options`	`object\|boolean` (optional)	Listener options; `capture` must match the value used with `.on()`

.trigger()

Dispatches a custom event on element(s). detail is passed through as-is, including falsy values like 0, false and ''; it defaults to null.

Parameters

Name	Type	Description
`target`	`element\|NodeList\|array`	The target element(s)
`event`	`string`	The event name
`detail`	`any` (optional)	Optional detail data to pass with the event

Examples

Utils.trigger(element, 'customEvent', {data: 'value'});

.transitionTime()

Returns the longest transition (duration + delay) of an element in milliseconds.

Parameters

Name	Type	Description
`el`	`element`	The target element

Returns

Type	Description
`number`	Transition time in milliseconds

.afterTransition()

Executes a callback once an element's transition completes. Runs immediately when the element has no transition (for example with prefers-reduced-motion), and falls back to a timeout because transitionend never fires for 0s, interrupted, or non-rendered transitions. Only transitions on the element itself count; bubbled child transitions are ignored.

Parameters

Name	Type	Description
`el`	`element`	The transitioning element
`cb`	`function`	Callback function, executed once

Examples

Utils.removeClass(dialog, 'open');
Utils.afterTransition(dialog, () =&gt; {
  dialog.remove();
});

Classes

.addClass()

Adds class(es) to element(s).

Parameters

Name	Type	Description
`target`	`element\|NodeList\|array`	The target element(s)
`...classes`	`string`	Class names to add

Examples

Utils.addClass(element, 'active');
Utils.addClass(Utils.select('.item'), 'highlight', 'selected');

.removeClass()

Removes class(es) from element(s).

Parameters

Name	Type	Description
`target`	`element\|NodeList\|array`	The target element(s)
`...classes`	`string`	Class names to remove

Examples

Utils.removeClass(element, 'active');
Utils.removeClass(Utils.select('.item'), 'highlight', 'selected');

.hasClass()

Checks if an element has a class.

Parameters

Name	Type	Description
`target`	`element`	The target element
`c`	`string`	The class name to check

Returns

Type	Description
`boolean`	True if the element has the class

.normalizeClasses()

Normalizes class name arguments into an array of single class names. Used by the class helpers, so addClass(), removeClass() and hasClass() accept the same forms.

Parameters

Name	Type	Description
`...classes`	`string\|array`	Class names: separate arguments, space-separated strings, or a single array

Returns

Type	Description
`array`	Class names, with empty entries removed

Examples

Utils.normalizeClasses('a b', 'c'); // ['a', 'b', 'c']
Utils.normalizeClasses(['a', 'b c', '']); // ['a', 'b', 'c']

Attributes

.setAttr()

Sets attribute(s) on element(s).

Parameters

Name	Type	Description
`target`	`element\|NodeList\|array`	The target element(s)
`attr`	`string\|object`	Attribute name or object of attribute key-value pairs
`value`	`string` (optional)	Attribute value (when attr is a string). If falsey, removes the attribute

Examples

Utils.setAttr(element, 'data-id', '123');
Utils.setAttr(element, {id: 'myId', 'data-type': 'primary'});

.getAttr()

Gets an attribute value from an element.

Parameters

Name	Type	Description
`target`	`element`	The target element
`attr`	`string`	The attribute name

Returns

Type	Description
`string\|null`	The attribute value or null if not present

.hasAttr()

Checks if an element has an attribute.

Parameters

Name	Type	Description
`target`	`element`	The target element
`attr`	`string`	The attribute name

Returns

Type	Description
`boolean`	True if the element has the attribute

.removeAttr()

Removes attribute(s) from element(s).

Parameters

Name	Type	Description
`target`	`element\|NodeList\|array`	The target element(s)
`attr`	`string\|array`	Attribute name(s) to remove

Examples

Utils.removeAttr(element, 'disabled');
Utils.removeAttr(element, ['disabled', 'hidden']);

.updateAttr()

Updates an attribute value and stores the original in a data attribute.

Parameters

Name	Type	Description
`els`	`element\|NodeList\|array`	The target element(s)
`attr`	`string`	The attribute name to update
`value`	`string`	The new attribute value
`handle`	`string`	A handle used to namespace the backup data attribute

.restoreAttr()

Restores an attribute to its original value from a data attribute.

Parameters

Name	Type	Description
`els`	`element\|NodeList\|array`	The target element(s)
`attr`	`string`	The attribute name to restore
`handle`	`string`	The handle used when the attribute was updated

.normalizeAttrs()

Normalizes attribute arguments into name/value pairs. Used by setAttr(), so it accepts either a name and value or an object.

Parameters

Name	Type	Description
`attr`	`string\|object`	Attribute name, or an object of attribute name/value pairs
`value`	`string` (optional)	Attribute value (when `attr` is a string)

Returns

Type	Description
`array`	Array of `[name, value]` pairs

Examples

Utils.normalizeAttrs('id', 'main'); // [['id', 'main']]
Utils.normalizeAttrs({ id: 'main', role: 'tab' }); // [['id', 'main'], ['role', 'tab']]

Strings

.camelCase()

Converts a hyphenated or space-separated string to camelCase.

Parameters

Name	Type	Description
`string`	`string`	The string to convert

Returns

Type	Description
`string`	The camelCased string

Examples

Utils.camelCase('my-data-attr'); // 'myDataAttr'
Utils.camelCase('background color'); // 'backgroundColor'