dom-observer
Fire an event whenever a configured element mutates.
Features
- Mutation events Fires
dom-observer-changeon target changes - Selector-based
target-refresolves any element, anywhere - Waits for its target No matching element yet? It watches for one
- Fires once immediately An empty-
mutationsfire on resolve lets listeners seed from current state <template>-aware Also observes a template's.contentfragment
Installation
This package is available in the
<script src="https://unpkg.com/@excom/kit-utils@0.3.0/dist/index.umd.min.js"></script>
<script src="https://unpkg.com/@excom/neutron@0.2.0/dist/index.umd.min.js"></script>
<script src="https://unpkg.com/@excom/dom-observer@0.1.4/dist/index.umd.min.js"></script>npm install @excom/dom-observer<!-- import path to `node_modules` will depend on your build setup -->
<script type="module" src="/node_modules/@excom/dom-observer"></script>
<link rel="stylesheet" href="/node_modules/@excom/dom-observer">import "@excom/dom-observer";Peer dependencies (0)
Packages a consumer must install alongside this one. Workspace deps are bundled.
| Package | Version |
|---|---|
|
Usage
Point target-ref at any selector, then react to dom-observer-change
with <event-handler> (or Quark).
<event-handler listen-for="dom-observer-change" fire-event="watched-changed">
<dom-observer target-ref="#watched"></dom-observer>
</event-handler><event-handler listen-for="dom-observer-change" fire-event="watched-changed">
<dom-observer target-ref="#watched"></dom-observer>
</event-handler>API Reference
Attributes
Role —option is configurable, state
is managed by the element (read-only), or hybrid which is both.
Provision
Thisprovision property lives on the DOM node.
Read / watch it with Quark’s prop("provision"), or listen
for the neutron-provision event from app JS.
Events
Type
command event (HTML Command API): from a
<button command commandfor>, an <event-handler
command-name>, or a CommandEvent.
Recognized Elements
Child or descendant elements are recognized by and relevant to its functionality.Styles
@custom-selector synonyms so custom elements can share
semantic styles. Element aliases match the host tag / .tag-* class; state
aliases match attributes (nested under the element alias).
dom-observer
Attributes (4)
Role —option is configurable, state
is managed by the element (read-only), or hybrid which is both.
target-ref
CSS selector used to resolve the element to observe. Resolved against
document. If no element matches at connect time, the element waits for one to appear.
targetRef
string
nulltarget-change-observer
Observer attached to the resolved
targetElement (and to its .content fragment when the target is a <template>).
targetChangeObserver
MutationObserver
nulltarget-element
The currently observed target element (if any).
targetElement
HTMLElement
nulltarget-finding-observer
Document-level observer used to wait for a target matching
target-ref to appear. Disconnected as soon as the target is found.
targetFindingObserver
MutationObserver
nullProvision (0)
Thisprovision property lives on the DOM node.
Read / watch it with Quark’s prop("provision"), or listen
for the neutron-provision event from app JS.
Events (1)
A "default action" is subsequent logic executed by the element if
e.preventDefault() is not
synchronously called on the event.
Type
dom-observer-change
Fires whenever the resolved target mutates, and once immediately (with
mutations: []) as soon as the target is resolved so listeners can seed from current state. mutations is the MutationRecord[] from the underlying MutationObserver callback (empty on that first fire).
Type
DomObserverChangeEvent
command event (HTML Command API): from a
<button command commandfor>, an <event-handler
command-name>, or a CommandEvent.
Recognized Elements (0)
Child or descendant elements are recognized by dom-observer and relevant to its functionality.Styles (0)
If you wish to opt-out of these styles on a case-to-case basis, use property
all: revert-layer.
Valence.css ships this as .unstyled and .unstyled-all for the entire tree.
@custom-selector synonyms so custom elements can share
semantic styles. Element aliases match the host tag / .tag-* class; state
aliases match attributes (nested under the element alias).
Release notes (1)
0.1.1
- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources
Release notes
A "default action" is subsequent logic executed by the element if
e.preventDefault() is not
synchronously called on the event.
If you wish to opt-out of these styles on a case-to-case basis, use property
all: revert-layer.
Valence.css ships this as .unstyled and .unstyled-all for the entire tree.
Examples
Waiting for the target to exist
If nothing matches target-ref at connect time, <dom-observer> watches
the document for a match and switches over automatically — no glue code:
<dom-observer target-ref="article#late"></dom-observer><dom-observer target-ref="article#late"></dom-observer>Observing a <template>
A <template>'s authored content lives on its .content
DocumentFragment, not as DOM descendants of the <template> itself.
<dom-observer> observes both, so mutations to either surface through the
same event stream:
<template id="rows">
<li>seed</li>
</template>
<dom-observer target-ref="#rows"></dom-observer><template id="rows">
<li>seed</li>
</template>
<dom-observer target-ref="#rows"></dom-observer>