BaseImmutableNode

Foundational interface for all immutable nodes in the Stripo Email Editor Extensions SDK.

interface BaseImmutableNode<T extends ImmutableHtmlNode | ImmutableCssNode>

Description

BaseImmutableNode is the foundational interface that provides common querying and traversal methods for both HTML and CSS nodes. It enables navigation through the document tree, searching for elements, and accessing node relationships.

Import

import { BaseImmutableNode } from '@stripoinc/ui-editor-extensions';

Type Parameters

Parameter	Constraint	Description
T	ImmutableHtmlNode | ImmutableCssNode	The specific node type (HTML or CSS)

Methods

Query Methods

querySelector()

Finds a single matching child element within the node's subtree.

querySelector(selector: string): T

Parameter	Type	Description
selector	string	CSS selector for HTML nodes, special syntax for CSS nodes

Returns: T - First matching node, or undefined if no match

HTML Selector Syntax:

• Standard CSS selectors: .class, #id, tag, [attribute]

CSS Node Selector Syntax:

• @{max-width:100px} - Media query, exact match
• @*{max-width} - Media query, partial match
• #test.class-2 - Selector, exact match
• *#test - Selector, partial match
• {display} - Attribute, exact match
• &{comment text} - Comment, exact match
• &*{comment} - Comment, partial match

Example:

// HTML node
const button = htmlNode.querySelector('.btn-primary');

// CSS node
const mediaQuery = cssNode.querySelector('@{media only screen and (max-width: 600px)}');

---

querySelectorAll()

Returns all matching elements within the current node's subtree.

querySelectorAll(selector: string): T[]

Parameter	Type	Description
selector	string	CSS selector for HTML nodes, special syntax for CSS nodes

Returns: T[] - Array of matching nodes, empty array if no matches

Example:

// Find all buttons
const buttons = htmlNode.querySelectorAll('button');

// Find all CSS rules with display property
const displayRules = cssNode.querySelectorAll('{display}');

---

closest()

Finds the closest ancestor matching the selector.

closest(selector: string): T

Parameter	Type	Description
selector	string	Selector to match parent nodes

Returns: T - Closest matching parent, or undefined if not found

Example:

// Find closest container
const container = element.closest('.container');

// Find parent media query
const mediaParent = cssRule.closest('@*{max-width}');

---

Navigation Methods

parent()

Retrieves the parent node.

parent(): T

Returns: T - Parent node, or undefined if no parent

Example:

const parentElement = node.parent();
if (parentElement) {
    console.log('Parent found');
}

---

children()

Retrieves direct child element nodes (excludes text nodes).

children(): T[]

Returns: T[] - Array of child element nodes

Example:

const childElements = container.children();
console.log(`Container has ${childElements.length} child elements`);

---

childNodes()

Retrieves all child nodes including text nodes.

childNodes(): T[]

Returns: T[] - Array of all child nodes

Example:

const allChildren = element.childNodes();
// Includes both element and text nodes

---

siblings()

Retrieves sibling nodes of the current node.

siblings(): T[]

Returns: T[] - Array of sibling nodes (excludes current node)

Example:

const siblings = node.siblings();
siblings.forEach(sibling => {
    // Process each sibling
});

---

nextSibling()

Retrieves the next sibling node.

nextSibling(): T

Returns: T - Next sibling, or undefined if none

Example:

let current = firstNode;
while (current) {
    // Process node
    current = current.nextSibling();
}

---

nextElementSibling()

Retrieves the next sibling that is an element node.

nextElementSibling(): T

Returns: T - Next element sibling, or undefined if none

Example:

const nextElement = node.nextElementSibling();
// Skips text nodes

---

previousSibling()

Retrieves the previous sibling node.

previousSibling(): T

Returns: T - Previous sibling, or undefined if none

---

previousElementSibling()

Retrieves the previous sibling that is an element node.

previousElementSibling(): T

Returns: T - Previous element sibling, or undefined if none

---

Node Information Methods

getType()

Retrieves the type of the node.

getType(): string

Returns: string - Node type

HTML Node Types:

• 'element' - HTML element
• 'text' - Text node
• 'comment' - Comment node
• 'document' - Document node
• 'doctype' - DOCTYPE declaration
• 'documentFragment' - Document fragment

CSS Node Types:

• 'attr' - CSS attribute/property
• 'comment' - CSS comment
• 'rule' - CSS rule
• 'media' - Media query
• 'document' - CSS document

Example:

if (node.getType() === 'element') {
    // Handle element node
}

---

getNodeConfig()

Retrieves the configuration object of the node.

getNodeConfig(): Record<string, any>

Returns: Record<string, any> - Node configuration object

Example:

const config = node.getNodeConfig();
if (config.customProperty) {
    // Use custom configuration
}

Best Practices

1. Check for undefined: Many methods return undefined when no match is found
2. Use appropriate selectors: HTML and CSS nodes have different selector syntaxes
3. Type checking: Use getType() to determine node type before operations
4. Efficient traversal: Use specific methods like children() vs childNodes() based on needs
5. Cache results: Store frequently accessed nodes to avoid repeated queries