omdEquationSequenceNode

Represents a sequence of equations or mathematical expressions, designed for step-by-step calculations and visual problem-solving. This node manages the vertical layout of multiple steps, ensuring elements like equals signs are vertically aligned for readability. It also provides robust provenance tracking, simplification capabilities, and filtering options for displaying different levels of detail.

Class Definition

export class omdEquationSequenceNode extends omdNode

Constructor

new omdEquationSequenceNode(steps)

Creates a new omdEquationSequenceNode instance.

• steps (Array<omdNode>): An initial array of omdNode objects (typically omdEquationNode or omdOperationDisplayNode) representing the sequence of steps.

Upon construction, the sequence initializes its internal state, sets up layout helpers, and builds a comprehensive node map for provenance tracking across all steps.

Static Properties

OPERATION_MAP

A static map that links common operation names (e.g., 'add') to the corresponding method names on omdEquationNode (e.g., 'addToBothSides').

{
    'add': 'addToBothSides',
    'subtract': 'subtractFromBothSides',
    'multiply': 'multiplyBothSides',
    'divide': 'divideBothSides',
}

Static Methods

fromStringArray(stepStrings)

Creates an omdEquationSequenceNode instance from an array of equation strings. Each string must contain an equals sign (=).

• stepStrings (Array<string>): An array of strings, each representing an equation step.
• Returns: omdEquationSequenceNode - A new instance.
• Throws: Error if any string is not a valid equation (e.g., missing = or invalid format).

fromSteps(stepsArray)

Creates an omdEquationSequenceNode instance from an array of expression strings. This method is more flexible than fromStringArray as it can parse both full equations (containing =) and general mathematical expressions.

• stepsArray (Array<string>): An array of expression strings.
• Returns: omdEquationSequenceNode - A new sequence node.

Public Properties

• steps (Array<omdNode>): An array of omdNode objects representing each step in the sequence.
• currentStepIndex (number): The 0-based index of the currently active step. Default: 0.
• stepDescriptions (Array<string>): An array storing optional human-readable descriptions for each step.
• importanceLevels (Array<number>): An array storing the importance level (0, 1, or 2) for each step, used for filtering.
• currentFilterLevels (Array<number>): An array of numbers representing the currently active importance levels for step visibility. Default: [0].
• defaultEquationBackground (object | null): An object defining a default background style to be applied to all omdEquationNode steps added to the sequence.

Public Methods

getCurrentEquation()

Retrieves the last omdEquationNode in the sequence, which typically represents the current working equation.

• Returns: omdEquationNode | null - The last equation, or null if no equations exist.

getCurrentStep()

Retrieves the currently active step node based on currentStepIndex and visibility. It prioritizes visible equation nodes.

• Returns: omdNode | null - The current step node.

addStep(step, descriptionOrOptions, importance)

Adds a new step to the sequence. This method supports multiple signatures:

• addStep(omdNode, optionsObject)

• addStep(omdNode, descriptionString, importanceNumber)

• addStep(expressionString, optionsObject)

• addStep(expressionString, descriptionString, importanceNumber)

• step (omdNode | string): The omdNode object or an expression string for the step.

• descriptionOrOptions (object | string, optional): An options object (e.g., { description: '...', stepMark: 0 }) or a description string.

• importance (number, optional): The importance level (0, 1, or 2) if descriptionOrOptions is a string.

• Returns: number - The index of the added step.

setDefaultEquationBackground(style)

Sets a default background style that will be applied to all new omdEquationNode steps added to the sequence. It also applies the style to existing omdEquationNode steps immediately.

• style (object): An object defining the background style (e.g., { backgroundColor: '#f0f0f0', cornerRadius: 8, pill: true }).

rebuildNodeMap()

Rebuilds the internal nodeMap, which is a comprehensive map of all omdNode instances within the entire sequence, including historical nodes referenced in provenance chains. This is crucial for accurate highlighting and provenance tracking.

recordSimplificationHistory(name, affectedNodes, message, metadata)

Records a simplification step in the sequence's history.

• name (string): The name of the simplification rule applied.
• affectedNodes (Array<string>): An array of node IDs that were affected by the simplification.
• message (string): A human-readable description of the simplification.
• metadata (object, optional): Additional metadata about the simplification.

getSimplificationHistory()

Retrieves the complete simplification history for this sequence.

• Returns: Array<object> - An array of simplification history entries.

clearSimplificationHistory()

Clears all recorded simplification history entries.

setFontSize(fontSize)

Sets the font size for the entire sequence and propagates this setting to all individual steps. This triggers a re-computation of dimensions and layout.

• fontSize (number): The new font size in pixels.

applyEquationOperation(value, operation)

Applies a specified arithmetic operation to the current equation in the sequence and adds the result as a new step. This method also adds an omdOperationDisplayNode to visually represent the operation.

• value (number | string): The constant value or expression string to apply.
• operation (string): The operation name ('add', 'subtract', 'multiply', 'divide').
• Returns: omdEquationSequenceNode - Returns this sequence instance for chaining.

applyEquationFunction(functionName)

Applies a mathematical function (e.g., 'sqrt', 'log') to both sides of the current equation in the sequence and adds the result as a new step.

• functionName (string): The name of the function to apply.
• Returns: omdEquationSequenceNode - Returns this sequence instance for chaining.

simplify()

Applies one round of simplification rules to the last step in the sequence. If simplifications are applied, a new step is added to the sequence.

• Returns: object - A result object containing success (boolean), foldedCount (number of operations applied), isFinalSimplification (boolean), and message (string).

simplifyAll(maxIterations)

Repeatedly calls simplify() until no more simplifications can be applied or maxIterations is reached. This adds multiple simplification steps to the sequence.

• maxIterations (number, optional): Maximum number of iterations to prevent infinite loops. Default: 50.
• Returns: object - A result object containing success, totalSteps, iterations, and message.

evaluate(variables)

Evaluates the current step in the sequence with the given variables and logs the result to the console.

• variables (object): A map of variable names to their numeric values.

validateSequenceProvenance()

Validates the integrity of provenance tracking across all steps in the sequence.

• Returns: Array<object> - An array of validation issues found.

select() / deselect() / highlight(color) / clearProvenanceHighlights()

These methods override the default omdNode behavior. The omdEquationSequenceNode itself does not highlight or respond to selection events directly. Instead, these methods propagate the calls to their child steps, allowing individual steps to be highlighted or selected.

computeDimensions()

Calculates the overall dimensions (width and height) of the entire sequence, determining the correct alignment point for all equals signs.

updateLayout()

Positions each step vertically and aligns their equals signs to the calculated alignment point, ensuring a clean, readable layout.

toMathJSNode()

Converts the sequence to a math.js-compatible AST node. Currently, this returns the AST of the last step in the sequence.

• Returns: object - A math.js AST node.

navigateToStep(index)

Navigates to a specific step in the sequence by setting currentStepIndex.

• index (number): The 0-based index of the step to navigate to.
• Returns: boolean - true if navigation was successful.

nextStep()

Navigates to the next step in the sequence.

• Returns: boolean - true if there was a next step.

previousStep()

Navigates to the previous step in the sequence.

• Returns: boolean - true if there was a previous step.

getFilteredSteps(maxImportance)

Retrieves steps filtered by their importance level.

• maxImportance (number): The maximum importance level to include (0, 1, or 2).
• Returns: Array<object> - An array of objects, each containing step, description, importance, and index.

renderCurrentStep()

Renders only the current step of the sequence.

• Returns: SVGElement - The SVG representation of the current step.

toString()

Converts the entire sequence to a multi-line string representation, including step descriptions.

• Returns: string - Multi-line string of all steps.

clear()

Removes all steps from the sequence, clears all associated data (descriptions, importance levels, history), and resets the sequence to its initial state.

show() / hide()

Overrides omdNode's show() and hide() to also update the visibility of the layout manager.

updateStepsVisibility(visibilityPredicate)

Updates the visibility of multiple steps at once based on a provided predicate function. Also applies font weights based on stepMark.

• visibilityPredicate (Function): A function that takes a step node and returns true if it should be visible, false otherwise.

Internal Methods

• _initializeState(): Initializes internal state variables like currentStepIndex, stepDescriptions, etc.
• _initializeLayout(): Sets up the jsvgLayoutGroup for vertical arrangement.
• _initializeNodeMap(): Initializes the nodeMap and calls rebuildNodeMap().
• _disableContainerInteractions(): Disables default mouse interactions on the sequence container.
• _markInitialSteps(): Marks the initial steps with a default stepMark of 0.
• _applyDefaultFilter(): Applies the default filter (showing only level 0 steps) upon initialization.
• _reapplyCurrentFilter(): Reapplies the currently set filter levels to ensure consistent visibility.
• _determineStepMark(step, options): Determines the appropriate stepMark for a new step.
• _isFullySimplified(step): Heuristic to check if an equation step appears fully simplified.
• _isSimpleExpression(node): Heuristic to check if an expression is simple (constant, variable, or simple operations).
• preserveProvenanceHistory(newNodeMap): Ensures historical nodes referenced in provenance chains are preserved in the nodeMap.
• _collectAllProvenanceIds(newNodeMap): Collects all provenance IDs from nodes in the newNodeMap.
• _collectNodeProvenanceIds(node, referencedIds, processedNodes): Recursively collects provenance IDs for a given node.
• _preserveReferencedNodes(referencedIds, newNodeMap): Preserves nodes referenced by referencedIds in the newNodeMap.
• _preserveNodeAndContext(id, newNodeMap, processedIds): Preserves a node and its parent/sibling context.
• _preserveParentContext(node, newNodeMap): Preserves the parent context of a node.
• _preserveSiblingContext(node, newNodeMap): Preserves the sibling context of a node.
• _handleSuccessfulSimplification(originalStep, simplificationResult): Handles the result of a successful simplification, adding a new step and recording history.
• _getOperationDescription(operation, value, isUnsimplified): Generates a human-readable description for an equation operation.
• _calculateAlignmentPoint(visibleSteps): Calculates the optimal X-coordinate for aligning equals signs across all visible steps.
• _calculateTotalDimensions(visibleSteps): Calculates the total width and height of the sequence.
• _computeStepXOffset(step): Computes the horizontal offset needed to align a step within the sequence.
• _stringToNode(str): Converts an expression string into an omdNode (either omdEquationNode or a general expression node).