npm package: @oframe/dom
Description: ## Install
Latest version: 1.1.3

# @oframe/dom

## Install

```
npm i @oframe/dom
```

```
yarn add @oframe/dom
```

```js
import { DOM } from './DOM.mjs';
```

## Documentation

`@oframe/dom` is a singleton factory class used to add js animation functionality to `HTMLElements`.

---
# `DOM.setup()`

`DOM.setup()` will attach several properties and methods to the `HTMLElement` passed in to facilitate animation.

## Syntax

> `node = DOM.setup(node)`

## Params

> ### `node`

A `HTMLElement` object.

## Return value

The same `HTMLElement` object passed in as the `node` parameter, with added properties and methods. 

The added methods include:

> `node.css(styles)`

> `node.animate(duration, values)`

Both methods are aliases to:

> `DOM.css(node, styles)`

> `DOM.animate(node, duration, values)`

*See documentation of the above methods later in this page for more info.*

The added properties include:

`opacity,
perspective,
x, y, z,
scale, scaleX, scaleY,
rotate, rotateX, rotateY, rotateZ, 
skewX, skewY`

These include transform properties, and opacity. These are the only recommended properties for javascript animation as they are the only editable properties that do not cause a re-paint - merely a composite. 

Animations on `color`, `background-color`, etc are recommended to use CSS-Transitions, and even-so should be used infrequently.

***Note: added properties will not inherit from css values. The performance hit to check computed styles isn't worth it.***

---

# `DOM.create()`

`DOM.create()` is an alternative to `document.createElement()` with the addition that the created `HTMLElement` object is passed through `DOM.setup()` to receive the added properties and methods.

## Syntax

> `node = DOM.create(tagName, [className])`

## Params

> ### `tagName` *optional*

A `String` that specifies the type of element to be created. Used internally with `document.createElement()`. If not specified, `tagName` defaults to `'div'`.

> ### `className` *optional*

A `String` of the intended `ClassName` to add to the created `HTMLElement`.

## Return value

An `HTMLElement` object with added properties and methods.

---

# `DOM.query()`

`DOM.query()` is an alternative to `document.querySelectorAll()`, with the addition that the returned `NodeList` is passed through `DOM.setup()` to receive the added properties and methods.

## Syntax

> `node = DOM.query(selector, [root])`

## Params

> ### `selectors`

A `DOMString` containing one or more selectors to match against. Used internally with `Document.querySelectorAll()`.

> ### `root` *optional*

An `HTMLElement` object within which to perform the search query. If not specified, `root` defaults to `document`.

## Return value

A `NodeList` of `HTMLElement` objects with added properties and methods. If query was unsuccessful, the return value will be an empty `NodeList`.

---

# `DOM.css()`

`DOM.css()` updates the styling of an `HTMLElement`. It also checks if any of the animatable properties were included, storing them on the object itself for animation tracking.

## Syntax

> `node = DOM.css(node, styles)`

## Params

> ### `node`

An extended `HTMLElement` object.

> ### `styles`

An `Object` containing the desired styling. If the value of a property is not a `String`, nor one of `opacity`, `zIndex`, `fontWeight`, or `strokeDashoffset`, then the `'px'` suffix will automatically be added. Style property names in javascript use camel case, eg `backgroundColor`, rather than `background-color`.

## Return value

The same `HTMLElement` object passed in as the `node` parameter.

---

# `DOM.transform()`

`DOM.transform()` updates the styles of the animatable properties. It combines the individual transform properties of an extended `HTMLElement`, and combines it to a single `transform` style value.

## Syntax

> `node = DOM.transform(node)`

## Params

> ### `node`

An `HTMLElement` object that has had the additional properties added from `DOM.setup()`.

## Return value

The same `HTMLElement` object passed in as the `node` parameter.

---

# `DOM.animate()`

`DOM.animate()` is an alias for the `@oframe/animate` library, see inside for more documentation.

## Syntax

> `animation = DOM.animate(node, duration, values)`

## Params

> ### `node`

An `HTMLElement` object that has had the additional properties added from `DOM.setup()`.

> ### `duration`

A `Number` designating the duration of the animation in milliseconds.

> ### `values`

An `Object` containing the final values of animated properties, along with other optional properties used by the `@oframe/animate` library.

## Return value

An `Animate` object returned from the `@oframe/animate` library.

---