import { HideElementState } from '../api/HideElement';
import { DisplayCondition, ImmutableCssNode, ImmutableHtmlNode } from './ImmutableNode';
import { TemplateModifier } from './TemplateModifier';
/**
* Represents a content container in a structure layout as a width percentage string.
*
* @description
* This type defines containers that will hold actual content (text, images, buttons, etc.).
* The string value represents the width percentage of the container within the structure.
*
* @example
* ```typescript
* // Create a content container that takes 50% of the structure width
* const contentContainer: CreateStructureContentContainer = '50%';
*
* // Use in layout array
* const layout = ['25%', '50%', '25%']; // Three content containers
* ```
*/
type CreateStructureContentContainer = string;
/**
* Configuration for empty containers and spacers in email structure layouts.
*
* @description
* This interface defines containers that don't hold content but serve layout purposes.
* EMPTY containers are placeholders that can be converted to content containers later.
* SPACER containers maintain spacing and alignment in the email layout.
*
* @example
* ```typescript
* // Create an empty container placeholder
* const emptyContainer: CreateStructureEmptyContainer = {
* width: '25%',
* contentType: 'EMPTY'
* };
*
* // Create a spacer for layout alignment
* const spacer: CreateStructureEmptyContainer = {
* width: '10%',
* contentType: 'SPACER'
* };
* ```
*/
interface CreateStructureEmptyContainer {
/** The width percentage of the container (e.g., '25%', '50%') */
width: string;
/** Type of empty container - EMPTY for placeholders, SPACER for layout spacing */
contentType: 'EMPTY' | 'SPACER';
}
/**
* Union type representing any container in a structure layout.
*
* @description
* This type allows for flexible container definitions in email structure layouts.
* Content containers are defined as width percentage strings, while empty containers
* and spacers use the more detailed object interface with contentType specification.
*
* @example
* ```typescript
* // Mixed layout with content containers and empty containers
* const layout: StructureLayout[] = [
* '30%', // Content container
* {width: '20%', contentType: 'EMPTY'}, // Empty placeholder
* '30%', // Content container
* {width: '20%', contentType: 'SPACER'} // Layout spacer
* ];
* ```
*/
export type StructureLayout = CreateStructureEmptyContainer | CreateStructureContentContainer;
/**
* Interface for modifying email structure layouts and container arrangements.
*
* @description
* This interface provides methods to create new structures or modify existing ones
* by defining container layouts and distributing content among them. It handles
* the complex logic of email structure generation, including responsive design,
* MSO compatibility, and proper content distribution across multiple containers.
*
* @example
* ```typescript
* // Create a two-column structure with content
* modifier.structureModifier()
* .updateLayoutWithContent(
* ['60%', '40%'],
* ['Main Content
', 'Sidebar
']
* );
*
* // Modify existing structure layout while preserving content
* modifier.structureModifier()
* .updateLayout([
* {width: '25%', contentType: 'EMPTY'},
* '50%',
* '25%'
* ]);
* ```
*/
export interface MultiRowStructureModifier {
/**
* Creates a new structure by replacing the current one with specified containers and content.
*
* @description
* This method completely replaces the existing structure with a new layout defined by
* the container configuration and content distribution. It handles responsive design,
* MSO compatibility, image resizing, and proper DOM positioning.
*
* @param layout - Array of container configurations defining the structure layout
* @param containerContent - Array of HTML content strings to distribute among content containers
* @returns HtmlNodeModifier for method chaining
*
* @example
* ```typescript
* // Create three-column layout with mixed containers
* structureModifier.updateLayoutWithContent(
* [
* {width: '25%', contentType: 'EMPTY'}, // Empty placeholder
* '50%', // Main content area
* '25%' // Sidebar area
* ],
* [
* 'Main Article
Content...
',
* 'Sidebar Widget
'
* ]
* );
* ```
*/
updateLayoutWithContent: (layout: StructureLayout[], containerContent: string[]) => HtmlNodeModifier;
/**
* Modifies the container layout of an existing structure while preserving existing content.
*
* @description
* This method changes the container arrangement of the current multi fow structure without losing
* existing content. Content is redistributed among the new container layout, with excess
* content truncated or empty containers added as needed.
*
* @param layout - New container layout configuration for the structure
* @returns HtmlNodeModifier for method chaining
*
* @example
* ```typescript
* // Change from two columns to three columns
* structureModifier.updateLayout([
* '33%', // First content column
* '33%', // Second content column
* '34%' // Third content column
* ]);
*
* // Add empty containers for spacing
* structureModifier.updateLayout([
* {width: '20%', contentType: 'EMPTY'},
* '60%',
* {width: '20%', contentType: 'EMPTY'}
* ]);
* ```
*/
updateLayout: (layout: StructureLayout[]) => HtmlNodeModifier;
}
export interface HtmlNodeModifier extends TemplateModifier {
/**
* Sets an attribute with the given name and value on the current HTML node.
*
* @description
* This method modifies the current HTML node by adding or updating an attribute
* with the specified name and value. It creates an action to record this modification
* and stores it for later execution.
*
* @summary Adds or updates an attribute on the current HTML node.
*
* @param name - The name of the attribute to set.
* @param value - The value of the attribute to set.
* @returns The current HtmlNodeModifier instance for method chaining.
*/
setAttribute(name: string, value: string): HtmlNodeModifier;
/**
* Removes an attribute with the given name from the current HTML node.
*
* @description
* This method modifies the current HTML node by removing an attribute with the specified name.
* It creates an action to record this modification and stores it for later execution.
*
* @summary Removes an attribute from the current HTML node.
*
* @param name - The name of the attribute to remove.
* @returns The current HtmlNodeModifier instance for method chaining.
*/
removeAttribute(name: string): HtmlNodeModifier;
/**
* Adds a class to the current HTML node.
*
* @description
* This method modifies the current HTML node by appending a CSS class with the specified name.
* It creates an action to record this modification and stores it for future execution.
*
* @summary Appends a CSS class to the current HTML node.
*
* @param name - The name of the CSS class to add.
* @returns The current HtmlNodeModifier instance for method chaining.
*/
setClass(name: string): HtmlNodeModifier;
/**
* Removes a CSS class from the current HTML node.
*
* @description
* This method modifies the current HTML node by removing a specified CSS class.
* It creates an action to record this modification and stores it for later execution.
*
* @summary Removes a CSS class from the current HTML node.
*
* @param name - The name of the CSS class to remove.
* @returns The current HtmlNodeModifier instance for method chaining.
*/
removeClass(name: string): HtmlNodeModifier;
/**
* Sets device-specific hidden state for the current HTML node.
*
* @description
* The editor resolves the canonical target node for the current HTML node
* and applies hidden config directly to that target.
*
* @param state - The hidden state to apply.
* @returns The current HtmlNodeModifier instance for method chaining.
*/
setHiddenElementState(state: HideElementState): HtmlNodeModifier;
/**
* Sets the value attribute for the current HTML node.
*
* @description
* This method modifies the current HTML node by updating the value attribute.
* It creates an action to record this modification and stores it for later execution.
*
* @summary Updates the value attribute of the current HTML node.
*
* @param value - The value to set for the value attribute.
* @returns The current HtmlNodeModifier instance for method chaining.
*/
setValue(value: string): HtmlNodeModifier;
/**
* Updates the inner HTML of the current HTML node.
*
* @description
* This method replaces the current inner HTML of the node with the provided HTML string.
* It removes the existing children and creates new nodes based on the provided HTML.
*
* @summary Replaces the inner HTML of the current HTML node.
*
* @param html - The HTML string to set as the new inner content.
* @returns The current HtmlNodeModifier instance for method chaining.
*/
setInnerHtml(html: string): HtmlNodeModifier;
/**
* @description
* Updates the text content of the HTML text node (ImmutableHtmlTextNode).
*
* @param {string} newValue - The new text value to be set for the current node.
* @returns {HtmlNodeModifier} Returns the current HtmlNodeModifier instance for chaining.
*/
setText(newValue: string): HtmlNodeModifier;
/**
* Appends new HTML content to the current HTML node.
*
* @description
* This method adds the provided HTML as children to the current node, placing it at the end of the node's child elements.
* It utilizes the parsed HTML content to generate new nodes.
*
* @summary Appends new HTML content as children of the current HTML node.
*
* @param html - The HTML string to append.
* @returns The current HtmlNodeModifier instance for method chaining.
*/
append(html: string): HtmlNodeModifier;
/**
* Prepends new HTML content to the current HTML node.
*
* @description
* This method adds the provided HTML as the first child of the current node.
* It parses the given HTML and calculates its position to ensure it is placed before any existing child nodes.
*
* @summary Prepends new HTML content as the first child of the current HTML node.
*
* @param html - The HTML string to prepend.
* @returns The current HtmlNodeModifier instance for method chaining.
*/
prepend(html: string): HtmlNodeModifier;
/**
* Replaces the current HTML node with the provided HTML content.
*
* @description
* This method removes the current HTML node and inserts the provided HTML content in its place.
* The new content is parsed and positioned correctly in the DOM tree.
*
* @summary Replaces the current HTML node with new HTML content.
*
* @param html - The HTML string to replace the current node with.
* @returns The current HtmlNodeModifier instance for method chaining.
*/
replaceWith(html: string): HtmlNodeModifier;
/**
* Sets a CSS style property on the current HTML node.
*
* @description
* This method modifies the current HTML node by adding or updating a specified CSS style property.
*
* @summary Adds or updates a CSS style property on the current HTML node.
*
* @param property - The name of the CSS property to set.
* @param value - The value of the CSS property to set.
* @returns The current HtmlNodeModifier instance for method chaining.
*/
setStyle(property: string, value: string): HtmlNodeModifier;
/**
* Removes a CSS style property from the current HTML node.
*
* @description
* This method modifies the current HTML node by removing a specified CSS style property.
*
* @summary Removes a CSS style property from the current HTML node.
*
* @param property - The name of the CSS property to remove.
* @returns The current HtmlNodeModifier instance for method chaining.
*/
removeStyle(property: string): HtmlNodeModifier;
/**
* Deletes the current HTML node.
*
* @description
* This method removes the current HTML node from the DOM tree by generating the appropriate actions.
*
* @summary Removes the current HTML node from the DOM tree.
*
* @returns The current HtmlNodeModifier instance for method chaining.
*/
delete(): HtmlNodeModifier;
/**
* Sets a display condition for the current HTML node.
*
* @description
* This method associates a display condition with the current HTML node, which determines
* whether the node should be rendered based on the specified condition's logic.
* The display condition includes details such as an ID, name, description, and associated scripts
* that are executed before and after evaluating the condition.
*
* @summary Configures a display condition for the current HTML node.
*
* @param condition - An object representing the display condition to apply,
* including its ID, name, description, and associated scripts.
* @returns The current HtmlNodeModifier instance for method chaining.
*/
setDisplayCondition(condition: DisplayCondition): HtmlNodeModifier;
/**
* Sets a custom configuration object for the current HTML node.
*
* @description
* This method allows users to define a configuration object for the current HTML node.
* The configuration can serve as a replacement for traditional HTML attributes, enabling
* the attachment of custom data or settings to the node without altering its attributes.
*
* @summary Assigns a configuration object to the current HTML node.
*
* @param config - The configuration object to associate with the current node.
* @returns The current HtmlNodeModifier instance for method chaining.
*/
setNodeConfig(config: Record): HtmlNodeModifier;
/**
* Returns a modifier for creating and modifying email template structures with containers.
*
* @description
* This method provides access to the StructureModifier, which allows creating new structures
* or modifying existing ones using containers with different widths. The structure modifier
* handles complex email structure generation logic, including responsive design,
* MSO/Outlook compatibility, proper content distribution between containers,
* automatic image scaling, and indentation handling.
*
* @summary Provides access to the interface for modifying email template structures.
*
* @returns StructureModifier for creating and modifying email structures
*
* @example
* ```typescript
* // Create a two-column structure
* htmlModifier.structureModifier()
* .updateLayoutWithContent(
* ['60%', '40%'],
* ['Main Content
', 'Sidebar
']
* );
*
* // Modify existing structure
* htmlModifier.structureModifier()
* .updateLayout([
* {width: '25%', contentType: 'EMPTY'},
* '50%',
* '25%'
* ]);
* ```
*/
multiRowStructureModifier(): MultiRowStructureModifier;
/**
* Returns the target Html node being modified.
*/
getTargetNode(): ImmutableHtmlNode;
}
export interface CssNodeModifier extends TemplateModifier {
/**
* Inserts a CSS rule before a specified CSS node.
*
* @description
* This method parses the provided CSS string and inserts the resulting rule or media
* node before the specified CSS node in the tree. Throws an error if the serialized node
* is not a rule or media type.
*
* @summary Inserts a CSS rule or media before a specified node.
*
* @param css - The CSS rule string to insert.
* @param beforeNode - The CSS node before which the rule is to be inserted.
* @returns The current CssNodeModifier instance for chaining.
*/
insertRuleBefore(css: string, beforeNode: ImmutableCssNode): CssNodeModifier;
/**
* Inserts a CSS rule after a specified CSS node.
*
* @description
* This method parses the provided CSS string and inserts the resulting rule or media
* node after the specified CSS node in the tree. Throws an error if the serialized node
* is not a rule or media type.
*
* @summary Inserts a CSS rule or media after a specified node.
*
* @param css - The CSS rule string to insert.
* @param afterNode - The CSS node after which the rule is to be inserted.
* @returns The current CssNodeModifier instance for chaining.
*/
insertRuleAfter(css: string, afterNode: ImmutableCssNode): CssNodeModifier;
/**
* Appends a CSS rule to the current CSS node.
*
* @description
* This method adds the provided CSS rule or media node as the last child of the current
* CSS node. Throws an error if the serialized node is not a rule or media type.
*
* @summary Appends a CSS rule or media as the last child.
*
* @param css - The CSS rule string to append.
* @returns The current CssNodeModifier instance for chaining.
*/
appendRule(css: string): CssNodeModifier;
/**
* Prepends a CSS rule to the current CSS node.
*
* @description
* This method adds the provided CSS rule or media node as the first child of the current
* CSS node. Throws an error if the serialized node is not a rule or media type.
*
* @summary Prepends a CSS rule or media as the first child.
*
* @param css - The CSS rule string to prepend.
* @returns The current CssNodeModifier instance for chaining.
*/
prependRule(css: string): CssNodeModifier;
/**
* Removes the current CSS rule from the CSS node.
*
* @description
* This method deletes the current node, provided it is a rule or media type.
* An error is thrown if the node is not of these supported types.
*
* @summary Removes the current CSS rule or media node.
*
* @returns The current CssNodeModifier instance for chaining.
*/
removeRule(): CssNodeModifier;
/**
* Sets a CSS property on the current CSS node.
*
* @description
* This method updates or adds a CSS property with the specified name and value
* in the corresponding CSS rule. If multiple properties with the same name are found,
* an error will be thrown.
*
* @summary Adds or updates a CSS property in the current CSS node.
*
* @param name - The name of the CSS property to set.
* @param value - The value of the CSS property to set.
* @returns The current CssNodeModifier instance for chaining.
*/
setProperty(name: string, value: string): CssNodeModifier;
/**
* Removes a CSS property from the current CSS node.
*
* @description
* This method deletes a CSS property with the specified name from the corresponding
* CSS rule. If multiple properties with the same name are found, an error will be thrown.
*
* @summary Deletes a CSS property from the current CSS node.
*
* @param name - The name of the CSS property to remove.
* @returns The current CssNodeModifier instance for chaining.
*/
removeProperty(name: string): CssNodeModifier;
/**
* Returns the target CSS node being modified.
*/
getTargetNode(): ImmutableCssNode;
}
export {};