umberto 7.0.2 → 8.0.1

package/scripts/utils/pug-to-xml-binding/render-xml-pug-components-in-markdown.js

@@ -0,0 +1,193 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const transformXMLTreeToPug = require( './transform-xml-tree-to-pug.js' );
+const XMLComponentsParser = require( './parser/xml-components-parser.js' );
+const { walkXMLTree, TreeWalkActions } = require( './parser/walk-xml-tree.js' );
+
+/**
+ * Slices XML components from Markdown content and transforms them to Pug format.
+ *
+ * This function takes text containing XML-like components mixed with regular content,
+ * parses it into a tree structure, and then walks through the tree to transform
+ * XML elements into Pug mixin calls while preserving text content.
+ *
+ * @param xml - The input text containing XML components and regular content
+ * @param options - Configuration options for parsing and transformation
+ * @param options.hexo - The Hexo instance for context (required)
+ * @param options.sourceName - The name of the source file (for error reporting)
+ * @param options.mixinContextVars - Additional attributes to pass to the Pug mixin
+ * @param [options.parserConfig={}] - Configuration passed to XMLComponentsParser
+ * @param [options.pugTransformerConfig={}] - Configuration passed to transformXMLTreeToPug
+ * @returns The transformed content with XML components converted to Pug syntax
+ */
+function renderXMLPugComponentsInMarkdown( xml, options ) {
+	const {
+		sourceName,
+		mixinContextVars,
+		hexo,
+		basePath,
+		patternElements = [],
+		replaceFn = createReplacementBase64Tag
+	} = options;
+
+	const parser = XMLComponentsParser.parseText( xml, {
+		trimRootText: false,
+		patternElements
+	} );
+
+	const markdown = walkXMLTree( parser.tree, {
+		enter( node, depth ) {
+			switch ( node.type ) {
+				case 'text':
+					return TreeWalkActions.replace( node.content );
+
+				case 'element': {
+					const { patternElement } = node;
+
+					if ( patternElement.renderer ) {
+						return TreeWalkActions.replace(
+							patternElement.renderer( node )
+						);
+					}
+
+					// Hexo rendering engine is a little bit clumsy and rendered markdown within
+					// pug mixins often results in broken HTML. It's easier to do it manually, after
+					// the whole tree is rendered.
+					const postfixTexts = [];
+					const content = transformXMLTreeToPug( node, depth, {
+						fallbackGlobalRequire: '_components/index',
+						parseText: ( node, str ) => {
+							if ( !str.trim().length ) {
+								return '';
+							}
+
+							// Handle the text inside the pug.
+							if ( !node.patternElement?.allowMarkdownContent ) {
+								return str;
+							}
+
+							// If the content is a markdown text, we'll postprocess it after rendering whole tree.
+							postfixTexts.push( str );
+							return `__MARKDOWN_TEXT_${ postfixTexts.length - 1 }__`;
+						}
+					} );
+
+					// Let's render the mixin.
+					const locals = Object.assign(
+						{},
+						hexo.locals.toObject(),
+						hexo.extend.helper.list(),
+						{
+							...mixinContextVars,
+							config: hexo.config,
+							mixinContextVars: patternElement.mixinContextVars
+						}
+					);
+
+					// Render component wrapper
+					let finalReplacement = null;
+
+					try {
+						finalReplacement = hexo.render.renderSync(
+							{
+								engine: 'pug',
+								text: content,
+								path: basePath
+							},
+							locals
+						).trim();
+					} catch ( error ) {
+						console.error( error );
+						console.error( `Error rendering component "${ node.name }" in file ${ sourceName }` );
+						console.error( content );
+
+						throw error;
+					}
+
+					// Render markdown content inside the mixin, if present.
+					for ( let i = 0; i < postfixTexts.length; i++ ) {
+						const renderedInnerText = hexo.render.renderSync(
+							{
+								text: postfixTexts[ i ],
+								engine: 'markdown'
+							}
+						).trim();
+
+						finalReplacement = finalReplacement.replace(
+							`__MARKDOWN_TEXT_${ i }__`,
+							renderedInnerText
+						);
+					}
+
+					// Leave magic base64 tag that will be replaced AFTER processing the whole markdown document.
+					return TreeWalkActions.replace(
+						replaceFn( finalReplacement )
+					);
+				}
+			}
+		}
+	} ).join( '' );
+
+	return markdown;
+}
+
+/**
+ * Creates a Base64-encoded replacement tag for component content.
+ *
+ * This function encodes the provided content into a Base64 string and wraps it
+ * in an HTML comment marker that can be later extracted and replaced with the
+ * original content.
+ *
+ * @param content - The HTML/text content to be encoded and wrapped
+ * @returns A comment tag containing the Base64-encoded content
+ */
+function createReplacementBase64Tag( content ) {
+	const encodedContent = Buffer.from( content ).toString( 'base64' );
+
+	return `<!-- COMPONENT:${ encodedContent } -->`;
+}
+
+/**
+ * Extracts and decodes Base64-encoded component markers from page content.
+ *
+ * This function finds HTML comment markers containing Base64-encoded content,
+ * decodes them back to their original form, and replaces the markers with the
+ * decoded content. It processes the content iteratively to handle nested
+ * components and includes a maximum iteration limit to prevent infinite loops.
+ *
+ * @param options - Configuration object
+ * @param options.page - The page object containing the content to process
+ * @param options.maxIterations - Maximum number of processing iterations to prevent infinite loops
+ * @returns The processed content with all component markers replaced
+ */
+function extractReplacementBase64Tag( { page, maxIterations = 5 } ) {
+	let content = page.content;
+	let previousContent;
+
+	const markerRegex = /<!-- COMPONENT:(.*?) -->/g;
+
+	do {
+		previousContent = content;
+		content = content.replace(
+			/<!-- COMPONENT:([a-zA-Z0-9+/=]+) -->/g,
+			( match, encodedContent ) => {
+				try {
+					return Buffer.from( encodedContent, 'base64' ).toString();
+				} catch ( error ) {
+					console.error( `Error decoding component marker in file ${ page.source }`, error );
+					return match;
+				}
+			}
+		);
+	} while ( content !== previousContent && markerRegex.test( content ) && maxIterations-- > 0 );
+
+	return content;
+}
+
+exports.renderXMLPugComponentsInMarkdown = renderXMLPugComponentsInMarkdown;
+exports.extractReplacementBase64Tag = extractReplacementBase64Tag;

package/scripts/utils/pug-to-xml-binding/transform-xml-tree-to-pug.js

@@ -0,0 +1,144 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/**
+ * Transforms XML tree structure to Pug mixin format.
+ * This module converts parsed XML nodes into Pug template syntax with proper indentation and attribute handling.
+ */
+
+'use strict';
+
+const { TreeWalkActions, walkXMLTree } = require( './parser/walk-xml-tree' );
+
+/**
+ * Transforms an XML tree structure into Pug mixin syntax.
+ *
+ * @param tree - The XML tree object to transform
+ * @param nesting - Base nesting level for indentation
+ * @param options - Configuration options
+ * @param options.nestingCharacter - Character used for indentation (default: '\t')
+ * @returns The transformed Pug mixin string
+ */
+function transformXMLTreeToPug( tree, nesting, options = {} ) {
+	const {
+		nestingCharacter = '\t',
+		parseText = str => str,
+		fallbackGlobalRequire
+	} = options;
+
+	let hasMissingImports = false;
+
+	// Walk through the XML tree and transform each node
+	const requireTags = new Set( [] );
+	const result = walkXMLTree( tree, {
+		leave( node, depth, parents ) {
+			// Calculate indentation based on nesting level and current depth
+			const indent = nestingCharacter.repeat( nesting + depth );
+
+			switch ( node.type ) {
+				case 'text': {
+					const parent = parents[ parents.length - 1 ];
+					let mappedContent = node.content;
+
+					if ( parent && parent.type === 'element' ) {
+						mappedContent = parseText( parent, mappedContent );
+					}
+
+					if ( !mappedContent ) {
+						return TreeWalkActions.remove();
+					}
+
+					return TreeWalkActions.replace( `${ indent }| ${ mappedContent }\n` );
+				}
+
+				case 'element': {
+					if ( !node.patternElement?.requires?.length ) {
+						hasMissingImports = true;
+					} else if ( !hasMissingImports ) {
+						for ( const requirePath of node.patternElement.requires ) {
+							requireTags.add( requirePath );
+						}
+					}
+
+					const mappedAttributes = (
+						node.patternElement?.attributesMapper ?
+							node.patternElement.attributesMapper( node ) :
+							node.attributes
+					);
+
+					return TreeWalkActions.replace( [
+						`${ indent }+${ node.patternElement.mixinName || node.name }(${ serializeMixinAttributes( mappedAttributes ) })`,
+						...( node.children || [] )
+					].join( '\n' ) );
+				}
+			}
+		}
+	} );
+
+	// There is no need to duplicate requires if the fallback global require is already included.
+	if ( hasMissingImports ) {
+		requireTags.clear();
+		requireTags.add( fallbackGlobalRequire );
+	}
+
+	return [
+		...Array.from( requireTags ).map( requirePath => `include ${ requirePath }` ),
+		result
+	].join( '\n' );
+}
+
+/**
+ * Serializes XML attributes into JSON format for Pug mixin parameters.
+ * Normalizes attribute names and values according to Pug conventions.
+ *
+ * @param attributes - Object containing XML attributes
+ * @returns JSON string representation of normalized attributes
+ */
+function serializeMixinAttributes( attributes ) {
+	const entries = Object.fromEntries(
+		Object
+			.entries( attributes )
+			.map( ( [ key, value ] ) => {
+				const normalizedKey = normalizeMixinAttributeName( key );
+				const normalizedValue = normalizeMixinAttributeValue( value );
+
+				return [ normalizedKey, normalizedValue ];
+			} )
+	);
+
+	return JSON.stringify( entries );
+}
+
+/**
+ * Normalizes XML attribute values to appropriate JavaScript types.
+ * Converts string representations of booleans to actual boolean values.
+ *
+ * @param value - The XML attribute value to normalize
+ * @returns Normalized value (boolean for 'true'/'false', string otherwise)
+ */
+function normalizeMixinAttributeValue( value ) {
+	if ( value === 'true' || value === '' ) {
+		return true;
+	}
+
+	if ( value === 'false' ) {
+		return false;
+	}
+
+	return value;
+}
+
+/**
+ * Normalizes attribute names from kebab-case to camelCase.
+ * e.g., data-foo-bar -> dataFooBar
+ *
+ * @param name - The kebab-case attribute name
+ * @returns The camelCase attribute name
+ */
+function normalizeMixinAttributeName( name ) {
+	return name.replace( /-([a-z])/g, g => g[ 1 ].toUpperCase() );
+}
+
+module.exports = transformXMLTreeToPug;

package/scripts/utils/random-id.js

@@ -0,0 +1,75 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const crypto = require( 'crypto' );
+
+/**
+ * Generates a random ID with a single segment. If a prefix is provided, it will be prepended to the ID.
+ *
+ * The `gen-` prefix is always used to easier extract the generated IDs from the output.
+ *
+ * @param [prefix] Optional prefix to add to the ID
+ * @param [maskable=true] Whether the ID should be replaceable by regenerateRandomIds.
+ * @return The generated ID with optional prefix
+ */
+function randomId( prefix, maskable = true ) {
+	const shortId = crypto.randomBytes( 3 ).toString( 'hex' ).substring( 0, 5 );
+
+	let id = prefix ? `${ prefix }-${ shortId }` : shortId;
+
+	if ( maskable ) {
+		id = `gen-${ id }`;
+	}
+
+	return id;
+};
+
+/**
+ * Checks if the given ID is a masked ID.
+ */
+function isMaskedID( id ) {
+	return id.startsWith( 'gen-' );
+}
+
+/**
+ * Regenerates random IDs in a string.
+ *
+ * It finds all occurrences of IDs generated by `randomId()` and replaces them with new random IDs.
+ * If an ID is repeated in the input string, it will be replaced with the same new ID.
+ * It preserves the prefix of the original ID.
+ *
+ * @param str The string to process.
+ * @returns The string with regenerated IDs.
+ */
+function regenerateRandomIds( str ) {
+	const idCache = new Map();
+	const idRegex = /(gen-(?:[a-zA-Z0-9]+-)*[a-f0-9]{5})/g;
+
+	return str.replace( idRegex, oldId => {
+		if ( idCache.has( oldId ) ) {
+			return idCache.get( oldId );
+		}
+
+		// Everything after 'gen-'.
+		const idContent = oldId.substring( 4 );
+		const parts = idContent.split( '-' );
+
+		// The ID has 1 segment at the end. If there are more parts, it means a prefix is present.
+		const prefix = parts.length > 1 ? parts.slice( 0, -1 ).join( '-' ) : undefined;
+		const newId = randomId( prefix );
+
+		idCache.set( oldId, newId );
+
+		return newId;
+	} );
+}
+
+module.exports = {
+	isMaskedID,
+	randomId,
+	regenerateRandomIds
+};

package/scripts/utils/remove-indentation.js

@@ -0,0 +1,48 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+/**
+ * Removes indentation from content preserving the relative indentation within the content.
+ * @param content The content to remove indentation from
+ * @returns Content with common indentation removed
+ */
+module.exports = function removeIndentation( content ) {
+	// Remove unwanted indentation.
+	const lines = content.split( /\n/ );
+
+	// Skip empty lines when detecting indentation level
+	let indentationLine = 1;
+	while ( indentationLine < lines.length && !lines[ indentationLine ].trim() ) {
+		indentationLine++;
+	}
+
+	// Get the indentation of the first non-empty line, or empty string if no valid lines
+	const indentation = indentationLine < lines.length ? lines[ indentationLine ].match( /^\s*/ )[ 0 ] : '';
+
+	if ( !indentation ) {
+		return content.trim();
+	}
+
+	let pattern;
+
+	// When using spaces as indentation, some editors may mix them with tabs.
+	// In such case, let's try to remove tabs as well. 4 spaces are treat as a single tab character.
+	if ( indentation[ 0 ] === ' ' ) {
+		pattern = new RegExp( `^${ indentation }|${ '\\t'.repeat( Math.ceil( indentation.length / 4 ) ) }` );
+	} else {
+		pattern = new RegExp( `^${ indentation }` );
+	}
+
+	// Process each line to remove common indentation
+	content = lines.map( line => line.replace( pattern, '' ) ).join( '\n' );
+
+	// Remove first linebreak and last linebreak.
+	content = content.replace( /^\n/, '' );
+	content = content.replace( /\n$/, '' );
+
+	return content;
+};

package/scripts/utils/spritesheet-svg.js

@@ -0,0 +1,183 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const cheerio = require( 'cheerio' );
+const fs = require( 'fs' );
+const path = require( 'path' );
+
+const HexoManager = require( '../../src/hexo-manager' );
+
+/**
+ * Cache for parsed SVG elements.
+ */
+const SVG_CACHE = new Map();
+
+module.exports = function spritesheetSvg( str, isDocument = true ) {
+	const $ = cheerio.load( str, null, isDocument );
+	const elements = $( '[data-spritesheet-svg]' );
+
+	// Skip if there are no elements with data-spritesheet-svg
+	if ( elements.length === 0 ) {
+		return str;
+	}
+
+	// Collect all unique SVG files to include in the spritesheet
+	const svgFiles = new Map();
+
+	// Helper function to extract SVG file information
+	function collectSvgFileInfo( element ) {
+		const svgPath = element.attr( 'data-spritesheet-svg' );
+		const iconId = element.attr( 'data-spritesheet-id' );
+
+		if ( !svgFiles.has( iconId ) ) {
+			svgFiles.set( iconId, svgPath );
+		}
+	}
+
+	// Process normal SVG elements
+	elements.each( function() {
+		const $element = $( this );
+
+		collectSvgFileInfo( $element );
+	} );
+
+	// Process and remove preload elements
+	const preloadElements = $( '[data-spritesheet-preload="true"]' );
+	preloadElements.each( function() {
+		const $element = $( this );
+
+		collectSvgFileInfo( $element );
+		$element.remove();
+	} );
+
+	if ( svgFiles.size === 0 ) {
+		return str;
+	}
+
+	// Create spritesheet and get viewBox data
+	const { spritesheetElement, iconViewBoxes } = createSpritesheet( $, svgFiles );
+
+	// Add spritesheet to the beginning of the body
+	if ( $( 'body' ).length ) {
+		$( 'body' ).prepend( spritesheetElement );
+	}
+
+	// Set viewBox for original SVG elements
+	elements.each( function() {
+		const element = $( this );
+		const iconId = element.attr( 'data-spritesheet-id' );
+		const viewBox = iconViewBoxes.get( iconId );
+
+		if ( viewBox && this.tagName.toLowerCase() === 'svg' ) {
+			element.attr( 'viewBox', viewBox );
+		}
+	} );
+
+	$( '[data-spritesheet-svg]' ).removeAttr( 'data-spritesheet-svg' );
+	$( '[data-spritesheet-id]' ).removeAttr( 'data-spritesheet-id' );
+
+	return $.html();
+};
+
+/**
+ * Creates an SVG spritesheet from the provided SVG files.
+ * Returns an object containing the spritesheet element and a map of icon IDs to their viewBox strings.
+ */
+function createSpritesheet( $, svgFiles ) {
+	const symbols = [];
+	const iconViewBoxes = new Map();
+
+	for ( const [ iconId, svgPath ] of svgFiles.entries() ) {
+		const absolutePath = path.join( HexoManager.hexo.theme_dir, svgPath );
+
+		if ( !fs.existsSync( absolutePath ) ) {
+			console.warn( `SVG file not found: ${ absolutePath }` );
+			continue;
+		}
+
+		// Check if we have the SVG in cache
+		if ( !SVG_CACHE.has( absolutePath ) ) {
+			try {
+				const svgContent = fs.readFileSync( absolutePath, 'utf8' );
+				const $svg = cheerio.load( svgContent, { xmlMode: true } )( 'svg' );
+				SVG_CACHE.set( absolutePath, $svg );
+			} catch ( error ) {
+				console.error( `Error reading SVG file: ${ absolutePath }`, error );
+				continue;
+			}
+		}
+
+		const $svg = SVG_CACHE.get( absolutePath ).clone();
+
+		// Create symbol element from SVG
+		const $symbol = $( '<symbol></symbol>' );
+		$symbol.attr( 'id', iconId );
+
+		// Copy viewBox and other relevant attributes
+		let viewBoxValue;
+		if ( $svg.attr( 'viewBox' ) ) {
+			viewBoxValue = $svg.attr( 'viewBox' );
+		} else if ( $svg.attr( 'width' ) && $svg.attr( 'height' ) ) {
+			viewBoxValue = `0 0 ${ $svg.attr( 'width' ) } ${ $svg.attr( 'height' ) }`;
+		}
+
+		if ( viewBoxValue ) {
+			$symbol.attr( 'viewBox', viewBoxValue );
+			iconViewBoxes.set( iconId, viewBoxValue );
+		}
+
+		// Copy all child elements from SVG to symbol
+		$svg.children().each( function() {
+			const $child = $( this );
+			// Skip title elements as they'll be provided by the consuming SVG
+			if ( $child[ 0 ].tagName.toLowerCase() !== 'title' ) {
+				$symbol.append( $child.clone() );
+			}
+		} );
+
+		symbols.push(
+			resetFillColor( $, $symbol )
+		);
+	}
+
+	// Create the spritesheet container
+	const $spritesheet = $( '<svg></svg>' );
+	$spritesheet.attr( {
+		'class': 'svg-spritesheet',
+		'xmlns': 'http://www.w3.org/2000/svg',
+		'style': 'display: none;',
+		'aria-hidden': 'true'
+	} );
+
+	// Add all symbols to the spritesheet
+	symbols.forEach( $symbol => {
+		$spritesheet.append( $symbol );
+	} );
+
+	return {
+		spritesheetElement: $spritesheet,
+		iconViewBoxes
+	};
+}
+
+/**
+ * Resets the fill color of an SVG element to 'currentColor'.
+ * This is useful for ensuring that the SVG inherits the text color from its parent.
+ */
+function resetFillColor( $, $svg ) {
+	// Replace all fill attributes with the specified color.
+	$svg.find( '[fill]' ).each( function() {
+		$( this ).attr( 'fill', 'currentColor' );
+	} );
+
+	// Also check the root SVG for fill attribute.
+	if ( $svg.attr( 'fill' ) ) {
+		$svg.attr( 'fill', 'currentColor' );
+	}
+
+	return $svg;
+}