@evolv/mutate/README.md

A library of standard DOM mutations by Evolv AI.

# Mutate

Mutate is a library of helpers to maintain persistent
modifications to the rendered DOM of a web page for
implementation of temporary, experimental changes and
features for rapid experimentation.

It is intended to be framework independent and equally
effective for SPAs and traditionally rendered webpages.

## Getting Set Up

### Installation

```shell
$ npm install @evolv/mutate
```

### Building From Source

Clone the repository and run the following commands.
```shell
$ npm install
$ npm run build
```

### Run Demo Website

There is a demo site included.

*Content warning: flashing lights*

```shell
$ npm run demo
```

## Getting Started

The API for Mutate is similar in a lot of ways to the API of jQuery
with a significant difference, that is selectors (`Collectors`) refer
to all current and future matching `Element`s, and the functions to modify
the DOM (`Mutations`) are persistent.

This means that you don't need to worry about timing, or dynamic areas
of the rendered page.

Mutate also provides the ability to "project" `Element`s of the DOM into
other `Element`s of the DOM, binding all interactions with the "projection"
back to the original `Element`s.

As everyone building variants have learned the hard way, most `Element`s
are dependent on their location in the DOM for both style and functionality.
Projection allows the implementer to "move" and restyle `Element`s without
losing the position dependent functionality of the original `Element`s.

### Importing

```javascript
import {collect, mutate} from '@evolv/mutate';
```

### Basic Usage
The basic flow when using Mutate is to first define a Collector.

```javascript
collect('<selector>', '<collector name>');
```

Then to define a Mutator for the Collector.

```javascript
mutate('<collector name>').hide();
```

Mutators allow for Mutations to be chained together, similar to jQuery which
will be evaluated in order of invocation.

```javascript
mutate('<collector name>').text('<new text value>').classes({'<new class>': true});
```

#### How to test your changes

1. Run npm start
2. Create a simple website or use codesandbox
3. Add a snippet to head `<script src="http://localhost:8080/index.js"></script>` (make sure that your local is running on 8080, otherwise update src)
4. Apply changes to the website in the console

```javascript
evolv.collect('h1', 'heading')
evolv.mutate('heading').html('Test');
```

## Documentation

[Mutate Documentation](https://evolv-ai.github.io/mutate)