Module: lib/core/trace/dom

Stable, replayable descriptions of DOM nodes.

A trace refers to elements in two very different situations: when a human reads avenx trace view and wants to recognise the button they clicked, and when replay has to find that same button again in a freshly mounted application. The second requirement is the strict one — a description that reads well but cannot be resolved makes a trace unreplayable.

So every reference carries both a selector and the node's index among that selector's matches. Replay can then resolve button.qty-inc unambiguously even when the page has twelve of them, without depending on ids the application does not have.

Source:

Members

(inner, constant) INTERNAL_ATTR :RegExp

Attributes Avenx adds for its own bookkeeping, which must never end up in a selector: they are re-derived on every render and would not survive replay.

Type:
  • RegExp
Source:

(inner, constant) MAX_DOM_VALUE :number

How much of a changed attribute or text value a trace keeps.

Type:
  • number
Source:

(inner, constant) MAX_SELECTOR_CLASSES :number

How many class names are folded into a selector.

Scoped-CSS class hashes make Avenx elements class-heavy; taking every class would produce selectors that are long to read and brittle against an unrelated style change.

Type:
  • number
Source:

Methods

(static) clampDomValue(value) → {string|null}

Clamps a DOM value so a trace records the change rather than the document.

Parameters:
Name Type Description
value any

The raw attribute or text value.
Source:
Returns:

A bounded string, or null for an absent value.

Type
string | null

(static) describeNode(node) → {Object|null}

Describes a DOM node well enough to display it and to find it again.

Parameters:
Name Type Description
node Node | null

The node to describe.
Source:
Returns:

A reference, or null when there is no element to describe.

Type
Object | null

(static) formatNodeRef(ref) → {string}

Renders a node reference for display in avenx trace view.

Parameters:
Name Type Description
ref object | null

The reference.
Source:
Returns:

A short human-readable form.

Type
string

(static) ownerComponent(node) → {object|null}

Finds the Avenx component instance an element belongs to.

Parameters:
Name Type Description
node Node | null

The starting node.
Source:
Returns:

The owning component instance, if any.

Type
object | null

(static) resolveNode(ref, rootopt) → {Element|null}

Resolves a reference produced by describeNode back to an element.

Parameters:
Name Type Attributes Description
ref object | null

The reference.
root Document | Element <optional>

Where to search. Defaults to the document.
Source:
Returns:

The element, or null when it cannot be found.

Type
Element | null

(static) traceDomOp(op, node, fieldsopt)

Records a DOM mutation the patcher applied, attributed to whatever caused it.

Called from the existing patch operations rather than from a second diffing pass or a MutationObserver: the point of the trace is to say which state change produced a DOM change, and only the patcher knows both halves.

Values are truncated. A trace records that .total went from "$24.00" to "$36.00", not the innerHTML of the subtree around it.

Parameters:
Name Type Attributes Description
op string

The operation: text, attr, remove-attr, insert, remove, replace.
node Node

The node that changed, or its parent for structural ops.
fields object <optional>

Operation-specific detail (name, from, to).
Source:

(inner) selectorFor(el) → {string}

Builds a CSS selector for an element.

Parameters:
Name Type Description
el Element

The element.
Source:
Returns:

A selector, or the tag name when nothing else is available.

Type
string