Break out can-util/dom/mutate

[andrejewski]

I'd like to break out can-util/dom/mutate and can-util/dom/mutation-observer into their own package can-dom-mutate which will provide:

• an API for fulfilling dom/mutate's current DOM Node API (intercepted [verb]Child() calls)
• an API for low-level synthetic mutation the above API will use (dom/attr needs this too)
• (depending on concerns) the attributes, inserted, and removed custom events

By "depending on concerns" I mean to decide if logically these events do in fact belong inside the package instead of their own. Moving forward with implementation, this will become more clear.

As far as structure goes, I'm currently thinking:

• can-dom-mutate for replacing dom/mutation-observer
• can-dom-mutate/node for replacing the dom/mutate API
• can-dom-mutate/synthetic for the low-level API
  • This will include mutation batching and, potentially, constrained observation methods
    • "Constrained" meaning creating observers with much smaller contracts than the full MutationObserver API, as I'd like to not write a polyfill we don't need
• Maybe can-dom-mutate/events/{attributes,inserted,removed} for the custom events

Discussion is welcome and I'm happy to address concerns regarding my grand vision.

[andrejewski]

See can-dom-mutate for the API and implementation.

[andrejewski]

The API is:

can-dom-mutate

• dispatching mutations
  • dispatchNodeInsertion( node [, callback ])
  • dispatchNodeRemoval( node [, callback ])
  • dispatchNodeAttributeChange( node, attributeName, oldValue [, callback ])
• listening for a single node's mutations
  • onNodeInsertion( node, callback )
  • onNodeRemoval( node, callback )
  • onNodeAttributeChange( node, callback )
• listening for any node's mutations
  • onInsertion( callback )
  • onRemoval( callback )
  • onAttributeChange ( callback )

Note: the optional callback to the dispatch methods are called right after the mutation is actually broadcast (all mutations are batched). This eliminates the need for a hack like afterMutation() in our tests.

Note: all the listener events return remove functions which unbind the listener.

can-dom-mutate/observer

• get() observer
• getGlobalDefault([ global ]) observer
• set( observer )
• onChange( callback )

This API provides everything a can-global package would provide, but this is only for the one shared MutationObserver.

can-dom-mutate/node

• autoConfigure(): automatically optimizes for the current MutationObserver (leverages observer.onChange)
• appendChild(), insertBefore(), removeChild(), replaceChild(), setAttribute() methods

can-dom-mutate/events/{attributes|inserted|removed}

These are can-dom-events events; they did make sense to include in can-dom-mutate as they all can be derived from a single make-mutation-event generator.