umberto 9.1.1 → 9.1.2

package/CHANGELOG.md

@@ -1,6 +1,15 @@
 Changelog
 =========
 
+## [9.1.2](https://github.com/cksource/umberto/compare/v9.1.1...v9.1.2) (December 8, 2025)
+
+### Bug fixes
+
+* Fix a race condition in the Tooltip/Popover component between `createTooltipPopover` and `TooltipPopover.attach` that could cause duplicate initialization. Tooltips now initialize only once per element and more reliably detect when trigger elements have been detached.
+* Minification should preserve closing tags and output spec-compliant HTML.
+* Fix encoding of SDK sources.
+
+
 ## [9.1.1](https://github.com/cksource/umberto/compare/v9.1.0...v9.1.1) (November 25, 2025)
 
 ### Other changes
@@ -43,13 +52,6 @@ Changelog
 
 * Umberto reads a project configuration once and passes it through the pipeline. Thanks to that, hooks can modify it, which affects a project's build.
 
-
-## [8.3.5](https://github.com/cksource/umberto/compare/v8.3.4...v8.3.5) (October 29, 2025)
-
-### Other changes
-
-* Hook scripts now receive the full project configuration object when executed.
-
 ---
 
 To see all releases, visit the [release page](https://github.com/cksource/umberto/releases).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umberto",
-  "version": "9.1.1",
+  "version": "9.1.2",
   "description": "CKSource Documentation builder",
   "main": "src/index.js",
   "files": [

package/src/helpers/log-with-time.js

@@ -0,0 +1,31 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const { styleText } = require( 'util' );
+
+module.exports = function logWithTime( message ) {
+	const lowercase = message.charAt( 0 ).toLowerCase() + message.slice( 1 );
+	const getTime = measureSeconds();
+
+	console.log( `Started ${ lowercase }.` );
+
+	return () => console.log( `Finished ${ lowercase } in ${ styleText( 'bold', getTime() ) }.` );
+};
+
+function measureSeconds() {
+	const start = process.hrtime();
+
+	return () => {
+		const [ totalSeconds ] = process.hrtime( start );
+		const minutes = Math.floor( totalSeconds / 60 );
+		const seconds = totalSeconds % 60;
+
+		return minutes ?
+			minutes + 'm ' + String( seconds ).padStart( 2, '0' ) + 's' :
+			seconds + 's';
+	};
+}

package/src/index.js

@@ -17,6 +17,7 @@ const getProjectConfig = require( './tasks/get-project-config' );
 const watcher = require( './tasks/watcher' );
 const validateHtml = require( './tasks/validate-html-w3c' );
 const { version } = require( '../package.json' );
+const logWithTime = require( './helpers/log-with-time' );
 
 module.exports = {
 	/**
@@ -68,9 +69,8 @@ module.exports = {
  * @returns {Promise}
  */
 async function buildAndWatch( options ) {
-	const timer = process.hrtime();
+	const logTime = logWithTime( 'Building documentation' );
 	const outputDir = path.join( process.cwd(), 'build', 'docs' );
-
 	const hexoManager = await buildDocumentation( options );
 
 	if ( !options.skipThemes ) {
@@ -91,9 +91,7 @@ async function buildAndWatch( options ) {
 		} );
 	}
 
-	const [ time ] = process.hrtime( timer );
-
-	console.log( styleText( 'greenBright', `Building documentation complete in ${ Math.floor( time / 60 ) }m ${ time % 60 }s.` ) );
+	logTime();
 
 	if ( options.watch ) {
 		return watcher( hexoManager );

package/src/sdk-builder/get-sdk-sources.js

@@ -18,6 +18,7 @@ const {
 	textContent,
 	getName
 } = require( 'domutils' );
+const decodeHtmlEntities = require( '../../scripts/utils/decode-html-entities' );
 
 const SDK_SELECTOR = 'meta[name="sdk-samples"]';
 
@@ -27,7 +28,7 @@ module.exports = sourcePath => {
 
 	for ( const filePath of filePaths ) {
 		const content = fs.readFileSync( filePath, { encoding: 'utf8' } );
-		const doc = parseDocument( content );
+		const doc = parseDocument( content, { decodeEntities: false } );
 		const sdkMeta = selectOne( SDK_SELECTOR, doc );
 		const samplesNames = sdkMeta && getAttributeValue( sdkMeta, 'content' ) ?
 			getAttributeValue( sdkMeta, 'content' ).split( '|' ) :
@@ -77,9 +78,16 @@ module.exports = sourcePath => {
 					}
 
 					if ( hasAttrib( element, 'data-sample-strip-outer-tag' ) ) {
-						ret.source = render( element.children || [] ).replace( /^\n|\n$/g, '' );
+						ret.source = render( element.children || [], { encodeEntities: false } ).replace( /^\n|\n$/g, '' );
 					} else {
-						ret.source = render( element ).replace( /\s?data-sample(-[\w-]+)?="[^"]*?"/g, '' );
+						// Delete all data-sample* attributes.
+						for ( const attrib of Object.keys( element.attribs ) ) {
+							if ( attrib.startsWith( 'data-sample' ) ) {
+								delete element.attribs[ attrib ];
+							}
+						}
+
+						ret.source = render( element, { encodeEntities: false } );
 					}
 
 					outputArray.push( ret );
@@ -101,15 +109,15 @@ module.exports = sourcePath => {
 		}
 
 		const sdkContents = selectOne( '.sdk-contents', doc );
-		const contentHtml = render( sdkContents.children || [] );
+		const contentHtml = render( sdkContents.children || [], { encodeEntities: false } );
 		const presetVersion = getAttributeValue( sdkContents, 'data-cke-preset' );
 
 		files.push( {
 			name: upath.basename( filePath, '.html' ),
-			description: getAttributeValue( selectOne( 'meta[name="description"]', doc ), 'content' ),
-			title: textContent( selectOne( 'title', doc ) ),
+			description: decodeHtmlEntities( getAttributeValue( selectOne( 'meta[name="description"]', doc ), 'content' ) ),
+			title: decodeHtmlEntities( textContent( selectOne( 'title', doc ) ) ),
 			content: contentHtml,
-			source: render( doc ),
+			source: render( doc, { encodeEntities: false } ),
 			path: upath.relative( sourcePath, filePath ),
 			presetVersion,
 			sdkSamples: samples,

package/src/tasks/build-api-docs.js

@@ -10,6 +10,7 @@ const readDocSources = require( './read-doc-sources' );
 const DataProvider = require( '../data-converter/data-provider' );
 const ApiBuilder = require( '../api-builder/api-builder' );
 const TemplateCollection = require( '../template/template-collection' );
+const logWithTime = require( '../helpers/log-with-time' );
 
 /**
  * Builds API docs.
@@ -64,10 +65,10 @@ module.exports = async config => {
 		}
 	);
 
-	console.log( `Building API docs of ${ projectConfig.name } ...` );
-	console.time( `Built API docs of ${ projectConfig.name } in` );
+	const logTime = logWithTime( `Building API docs for ${ projectConfig.name }` );
 	const buildInfo = await apiBuilder.buildApi();
-	console.timeEnd( `Built API docs of ${ projectConfig.name } in` );
+
+	logTime();
 
 	if ( process.argv.includes( '--strict' ) && buildInfo.warningCount > 0 ) {
 		console.log( `There were ${ buildInfo.warningCount } warnings reported in strict mode. Aborting.` );

package/src/tasks/build-documentation.js

@@ -31,6 +31,7 @@ const umbertoVersion = require( '../../package.json' ).version;
 
 const { parseLinks } = require( '../../scripts/utils/parselinks' );
 const getFilePatternsToProcess = require( '../helpers/get-file-patterns-to-process' );
+const logWithTime = require( '../helpers/log-with-time' );
 
 /**
  * Main function building the documentation.
@@ -166,10 +167,18 @@ module.exports = options => {
 				skipGuides
 			} );
 		} )
-		.then( () => hexoManager.generate( {
-			watch,
-			concurrency: 80
-		} ) )
+		.then( async () => {
+			const logTime = logWithTime( 'Generating pages with Hexo' );
+
+			const result = await hexoManager.generate( {
+				watch,
+				concurrency: 80
+			} );
+
+			logTime();
+
+			return result;
+		} )
 		.then( () => buildSnippets( hexoManager.hexo.projectGlobals ) )
 		.then( () => copyProjectIcons( hexoManager.hexo.projectGlobals, hexoManager.getPublicDir() ) )
 		// A workaround for API guides when API generation is skipped.

package/src/tasks/minify-html-worker.js

@@ -18,7 +18,13 @@ module.exports = function( file ) {
 	const html = readFileSync( file );
 
 	const minified = minifier.minify( html, {
+		allow_noncompliant_unquoted_attribute_values: false,
+		allow_optimal_entities: false,
+		allow_removing_spaces_between_attributes: false,
+		keep_closing_tags: true,
 		keep_comments: true,
+		keep_html_and_head_opening_tags: true,
+		keep_input_type_text_attr: true,
 		minify_css: true,
 		minify_js: true
 	} );

package/src/tasks/minify-html.js

@@ -9,6 +9,7 @@ const { join } = require( 'path' );
 const { globSync } = require( 'fs' );
 const { styleText } = require( 'util' );
 const { default: TinyPool } = require( 'tinypool' );
+const logWithTime = require( '../helpers/log-with-time' );
 
 /**
  * Minifies all HTML files under outputDir in parallel using tinypool.
@@ -16,6 +17,7 @@ const { default: TinyPool } = require( 'tinypool' );
  * @param {string} outputDir - base directory to search for *.html files
  */
 module.exports = async function minifyHtml( outputDir ) {
+	const logTime = logWithTime( 'Minifying HTML' );
 	const files = globSync( join( outputDir, '**', 'api', '**', '*.html' ) );
 
 	const pool = new TinyPool( {
@@ -24,8 +26,6 @@ module.exports = async function minifyHtml( outputDir ) {
 	} );
 
 	try {
-		console.log( 'Started HTML minification.' );
-
 		const results = await Promise.allSettled(
 			files.map( async file => {
 				try {
@@ -49,6 +49,6 @@ module.exports = async function minifyHtml( outputDir ) {
 	} finally {
 		await pool.destroy();
 
-		console.log( 'Finished HTML minification.' );
+		logTime();
 	}
 };

package/src/tasks/validate-links.js

@@ -16,6 +16,7 @@ const fs = require( 'fs-extra' );
 const upath = require( 'upath' );
 const { globSync } = require( 'glob' );
 const { default: TinyPool } = require( 'tinypool' );
+const logWithTime = require( '../helpers/log-with-time' );
 
 /**
  * Collects all links from the provided HTML files.
@@ -81,16 +82,17 @@ async function collectLinks( pattern, options ) {
  * @param {Object} [options={}] Validation options.
  */
 module.exports = async function validateLinks( buildPath, options = {} ) {
-	console.info( `Gathering links in ${ styleText( 'magenta', buildPath ) } to validate...` );
+	const logGatheringTime = logWithTime( 'Gathering links to validate' );
 
-	const start = Date.now();
 	const { links, pathsToFiles } = await collectLinks( upath.join( buildPath, '**', '*' ), options );
 	const pool = new TinyPool( {
 		filename: require.resolve( './validate-links-worker.js' )
 	} );
 
+	logGatheringTime();
+
 	try {
-		console.info( `Validating links in ${ styleText( 'magenta', buildPath ) }...` );
+		const logValidatingTime = logWithTime( 'Validating links' );
 
 		const tasks = splitArrayBalanced( pathsToFiles, pool.options.maxThreads ).map( chunk => pool.run( { chunk, links, options } ) );
 		const results = await Promise.all( tasks );
@@ -101,7 +103,7 @@ module.exports = async function validateLinks( buildPath, options = {} ) {
 			throw new Error( `Found ${ errors.length } invalid links.` );
 		}
 
-		console.info( `Links validation finished in ${ styleText( 'green', ( Date.now() - start ) + 'ms' ) }.` );
+		logValidatingTime();
 	} finally {
 		await pool.destroy();
 	}

package/themes/umberto/layout/gloria/_modules/sentry/index.pug

@@ -16,8 +16,8 @@ mixin load-sentry-script( sentry )
 						'https://ckeditor.com/docs',
 						'https://ckeditor5.github.io/docs/nightly'
 					],
-					replaysSessionSampleRate: 1.0,
-					replaysOnErrorSampleRate: 1.0
+					replaysSessionSampleRate: 0,
+					replaysOnErrorSampleRate: 0
 				} );
 			};
 

package/themes/umberto/src/gloria/js/components/tooltip-popover.js

@@ -13,8 +13,9 @@ import { randomId } from '../helpers/random-id';
 import { createAnchorPositioningWatcher } from '../helpers/create-anchor-positioning-watcher';
 import { createMutationObserver } from '../helpers/create-mutation-observer';
 import { createCleanupRegistry } from '../helpers/create-cleanup-registry';
-import { isElementAttached } from '../helpers/is-element-attached';
+import { isElementDetached } from '../helpers/is-element-detached';
 import { afterDomReady } from '../helpers/after-dom-ready';
+import { timeout } from '../helpers/timeout';
 
 /**
  * Tooltip component.
@@ -71,7 +72,7 @@ export class TooltipPopover extends BaseComponent {
 		const tooltips = document.querySelectorAll( '.js-tooltip-popover' );
 
 		for ( const tooltip of tooltips ) {
-			new TooltipPopover( tooltip ).init();
+			tooltip.tooltipPopover ||= new TooltipPopover( tooltip ).init();
 		}
 	}
 
@@ -123,14 +124,14 @@ export class TooltipPopover extends BaseComponent {
 				// If so, and the tooltip is visible, hide it.
 				// Sometimes, framework might remove the trigger element after the click event.
 				// It handles such cases gracefully.
-				this.triggerCleanup.addEventListener( window, 'mousedown', () => {
-					setTimeout( () => {
-						isElementAttached( trigger ).then( isDetached => {
-							if ( isDetached && this.state.isVisible ) {
-								this.hide();
-							}
-						} );
-					}, 300 );
+				this.triggerCleanup.addEventListener( window, 'mousedown', async () => {
+					await timeout( 300 );
+
+					const isDetached = await isElementDetached( trigger );
+
+					if ( isDetached && this.state.isVisible ) {
+						this.hide();
+					}
 				} );
 				break;
 
@@ -397,6 +398,7 @@ export class TooltipPopover extends BaseComponent {
 				arrow.style.left = `calc(50% - ${ offset }px)`;
 			} else if ( position.endsWith( '-end' ) ) {
 				const currentRight = parseFloat( arrow.style.right || 0 );
+
 				arrow.style.right = `${ currentRight + offset }px`;
 			}
 		} else if ( left + tooltipRect.width > window.innerWidth ) {
@@ -407,9 +409,11 @@ export class TooltipPopover extends BaseComponent {
 
 			if ( !position.endsWith( '-start' ) && !position.endsWith( '-end' ) ) {
 				const offset = origLeft - left;
+
 				arrow.style.left = `calc(50% + ${ offset }px)`;
 			} else if ( position.endsWith( '-start' ) ) {
 				const currentLeft = parseFloat( arrow.style.left || 0 );
+
 				arrow.style.left = `${ currentLeft - overflowAmount }px`;
 			}
 		}
@@ -560,6 +564,8 @@ export function createTooltipPopover( config = {} ) {
 		...rest
 	} );
 
+	tooltip.tooltipPopover = popover;
+
 	afterDomReady( () => {
 		// Add to document
 		document.body.appendChild( tooltip );

package/themes/umberto/src/gloria/js/helpers/create-cleanup-registry.js

@@ -32,6 +32,7 @@ export function createCleanupRegistry() {
 		destroy() {
 			while ( callbacks.length ) {
 				const callback = callbacks.pop();
+
 				if ( typeof callback === 'function' ) {
 					callback();
 				}

package/themes/umberto/src/gloria/js/helpers/{is-element-attached.js → is-element-detached.js}

@@ -6,23 +6,32 @@
 /**
  * Asynchronously checks if the given element or any of its parents are detached from the document body.
  *
+ * This function intentionally does not use `isConnected` to ensure compatibility with environments like Shadow DOM.
+ * It only checks the connection to `document.body` not to any other root nodes.
+ *
  * @param element The element to check.
  * @returns A promise that resolves to true if the element or any parent is detached, false otherwise.
  */
-export async function isElementAttached( element ) {
+export async function isElementDetached( element ) {
 	return new Promise( resolve => {
 		// Use requestAnimationFrame to ensure the check happens after any potential DOM manipulations in the same tick.
 		requestAnimationFrame( () => {
 			let currentElement = element;
-			while ( currentElement ) {
+
+			for (
+				let watchdog = 0;
+				currentElement && currentElement !== document.body && watchdog < 100;
+				watchdog++
+			) {
 				if ( !document.body.contains( currentElement ) ) {
-					resolve( true ); // Detached
+					resolve( true );
 					return;
 				}
+
 				currentElement = currentElement.parentElement;
 			}
 
-			resolve( false ); // Attached
+			resolve( false );
 		} );
 	} );
 }