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

$ npm install @evolv/mutate

Building From Source

Clone the repository and run the following commands.

$ npm install
$ npm run build

Run Demo Website

There is a demo site included.

Fair warning: It is hideous and may cause seizures :)

$ 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 Elements, 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" Elements of the DOM into other Elements of the DOM, binding all interactions with the "projection" back to the original Elements.

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

Importing

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

Basic Usage

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

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

Then to define a Mutator for the Collector.

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

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

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

Updating the Mutate library

For updating instructions refer to the Update Process

Reference

collect(selector: string, name: string, parent?: string): Collector

Create a new named Collector.

note If parent is not specified, the library will attempt to discover the closest non-volatile parents of any Element that match the selector.

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | selector | string | A CSS selector that the Collector should manage. | | name | string | The name of the collector of future reference from mutate. | | parent? | string | (Optional) An optional selector if the nearest non-volatile parent is known. |

Returns

Collector

The Collector instance created. This Collector can be retrieved by name as well.

mutate(collectorName: string, variantKey?: string): Mutator

Create a Mutator associated with an named Collector

Parameters

| Name | Type | | :------ | :------ | | collectorName | string | | variantKey? | string |

Returns

Mutator

Collector

The Collector provides all functionality for creating persistent select Elements currently present or that will be present on the page at a future time.

A Collector can have any number of Mutator associated with it.

destroyed: boolean

True if the Collector has been destroyed, otherwise False.

elements: Element[]

All Elements the Collector has collected.

id: string

The id of the Collector.

isValid: boolean

True if all validation has been satisfied, otherwise False.

name: undefined | string

The name of the Collector.

observedTargets: Element[]

All Elements the Collector is currently observing.

parentSelector: undefined | string

The current selector for parent Elements if set.

paused: boolean

True if the Collector is paused, otherwise False.

root: Element | Document

The outermost parent Element to observe.

selector: undefined | string

The current selector for Elements to be collected if set.

atLeast(count: number): Collector

Specify the minimum number of Elements the Collector must find before it is considered valid.

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | count | number | The minimum number of Elements the Collector must match to be considered value. |

Returns

Collector

atMost(count: number): Collector

Specify the maximum number of Elements the Collector should find to be considered valid.

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | count | number | The maximum number of Elements the Collector must match to be considered value. |

Returns

Collector

claim(): Promise<Element>

Permanently claim a collected Element for modification.

Returns

Promise<Element>

destroy(): void

Permanently destroy this Collector.

exactly(count): Collector

Specify the total number of Elements the Collector should find to be considered valid.

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | count | number | The total number of Elements the Collector must match to be considered value. |

Returns

Collector

filter(predicate: Predicate): Collector

Add a Predicate Elements must satisfy to be included in the Collector.

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | predicate | Predicate | A Predicate Elements must satisfy to be included in the in the Collector |

Returns

Collector

observeParent(parentSelector): Collector

Set a selector for the parent Elements to be observed for matching Elements.

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | parentSelector | string | The selector for parent Elements. |

Returns

Collector

pause(): Collector

Pause collection and Element related notifications for this Collector.

Returns

Collector

subscribe(listener: ElementListener): Collector

Subscribe to notifications about the changing of Elements within the Collector.

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | listener | ElementListener | A callback to be notified about changes in the Elements. |

Returns

Collector

subscribeState(listener: CollectorStateListener): Collector

Subscribe to notifications about the changing of state within the collector.

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | listener | CollectorStateListener | A callback to be notified when the state of the Collector changes. |

Returns

Collector

unpause

unpause(): Collector

Unpause collection and Element related notifications for this Collector.

Returns

Collector

validate(predicate: Predicate): Collector

Add a Predicate that the Collector must satisfy before it is considered valid and ready to apply Effects.

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | predicate | Predicate | A Predicate the collector must meet before applying Effects. |

Returns

Collector

within(`millis`: number): Collector

Specify the maximum amount of time in milliseconds that a Collector has to satisfy all validation criteria.

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | millis | number | The maximum amount of time the Collector has to satisfy validation criteria. |

Returns

Collector

Mutator

Mutator provides a collection of methods to persistently mutate the DOM.

with: Binder

Bind Effects to non-DOM related events or state changes.

The bound value will be available for use in Effects as well as triggering reapplication of Effects.

Type declaration

| Name | Type | | :------ | :------ | | attr | (attrName: string, transform?: (v: any) => any) => Binder | | content | (transform?: (v: any) => any) => Binder | | context | (propertyName: string, transform?: (v: any) => any) => Binder |

apply(transform): Mutator

WARNING! This function is experimental and should only be used in testing.

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | transform | (subject: Element) => Element | A function that modifies the DOM of subject. |

Returns

Mutator

attributes

attributes(attributes): Mutator

Set attributes on the Elements in the Collector.

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | attributes | object | Map<string, string | (state: Map<string, any>) => string> | A {@type Map} of attribute names to {@type string} or {@type (() => string)} representing their desired state. |

Returns

Mutator

classes

classes(classes): Mutator

Set or remove classes on the Elements in the Collector.

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | classes | object | Map<string, boolean | (state: Map<string, any>) => boolean> | A {@type Map} of class names to {@type boolean} or {@type (() => boolean)} representing their desired state. |

Returns

Mutator

customEffect(initialize, modify, revert): Mutator

Create a custom Effect that is persistently applied.

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | initialize | () => void | The function to be invoked to initialize the Effect. | | modify | () => void | The function to be invoked when an Element is modified. | | revert | () => void | The function to be invoked when the Effect should be reverted. |

Returns

Mutator

hide(): Mutator

Hide all Elements in the Collector.

Returns

Mutator

html(newHtml, clone?): Mutator

Replace the HTML content of the Elements matched by the Collector.

Parameters

| Name | Type | Default value | Description | | :------ | :------ | :------ | :------ | | newHtml | string | Node[] | undefined | The new HTML or Nodes to replace the content with. | | clone | boolean | true | Whether or not a the nodes should be cloned before insertion. (Default: True) |

Returns

Mutator

insert

insert(nodes, clone?): Mutator

Insert one or more Nodes into all elements in the Collector.

Parameters

| Name | Type | Default value | Description | | :------ | :------ | :------ | :------ | | nodes | string | Node | Node[] | undefined | The Nodes to insert, or a string containing the HTML to insert. | | clone | boolean | true | Whether or not a the nodes should be cloned before insertion. (Default: True) |

Returns

Mutator

once(): Mutator

Specify that the Effects be applied no more than once.

Returns

Mutator

pause(): Mutator

Pause all Effects that are applied through this Mutator.

Returns

Mutator

project(to): Mutator

Clone and hide an Element, mapping all events from the clone into the original elements. The clone is then inserted into the DOM element that matches the {@param to} selector.

The purpose of the functionality is to avoid disabling or otherwise negatively impacting existing event listeners.

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | to | string | The selector for an element into which the cloned Element should be projected. |

Returns

Mutator

reevaluate(): Mutator

Reinitialize all Effects on the Elements in the Collector.

Returns

Mutator

remove(nodes: Node[]): Mutator

Remove the specified Nodes from all elements in the Collector.

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | nodes | string | Node | Node[] | the Nodes or a selector for Nodes that should be removed. |

Returns

Mutator

revert(subject?): Mutator

Revert all Effects applied through this Mutator to all Elements in the Collector or the specified {@param subject}.

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | subject? | Element | (Optional) The Element to revert the Effects on. |

Returns

Mutator

show(): Mutator

Show all Elements in the Collector.

Returns

Mutator

styles(styles): Mutator

Set styles on the Elements in the Collector.

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | styles | object | Map<string, string | (state: Map<string, any>) => string> | A {@type Map} of style names to {@type string} or {@type (() => string)} representing their desired state. |

Returns

Mutator

text(newText: string): Mutator

Replace the text content of the Elements matched by the Collector.

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | newText | string | (state: default) => string | The new text content. |

Returns

Mutator

unpause(): Mutator

Unpause all Effects that are applied through this Mutator.

Returns

Mutator

interface CollectorStateListener

Type declaration

(collectorState, collector): void

Parameters

| Name | Type | | :------ | :------ | | collectorState | CollectorState | | collector | Collector |

interface ElementListener

Type declaration

(action, element, elementList): void

Parameters

| Name | Type | | :------ | :------ | | action | EventType | | element | Element | | elementList | Element[] |

interface Predicate

Type declaration

(element): boolean

Parameters

| Name | Type | | :------ | :------ | | element | HTMLElement |

Returns

boolean

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

evolv.collect('h1', 'l6aiigykj')
evolv.mutate("l6aiigykj").html("Test");