umberto 6.0.0 → 6.1.0

package/themes/umberto/src/umberto/js/_pagenavigation.js

@@ -0,0 +1,93 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+export default function pageNavigation() {
+	const CLASS_NAMES = {
+		huge: 'api-subheader__navigation-dropdown--huge',
+		big: 'api-subheader__navigation-dropdown--big',
+		small: 'api-subheader__navigation-dropdown--small',
+		empty: 'api-subheader__navigation-dropdown--empty',
+		hidden: 'api-subheader__navigation-dropdown--hidden'
+	};
+	const mainNavigationElements = document.querySelectorAll( '.api-subheader__navigation > ul > li' );
+	for ( const element of mainNavigationElements ) {
+		const ul = createListFor( element );
+
+		element.appendChild( ul );
+	}
+
+	if ( !window.umberto ) {
+		window.umberto = {};
+	}
+
+	window.umberto.updateDropdowns = function updateDropdowns() {
+		for ( const element of mainNavigationElements ) {
+			const ul = element.querySelector( 'ul' );
+			const visibleItemsLength = ul.querySelectorAll( 'li:not(.api-subheader__navigation-dropdown--hidden)' ).length;
+			if ( !visibleItemsLength ) {
+				element.classList.add( CLASS_NAMES.hidden );
+			} else {
+				element.classList.remove( CLASS_NAMES.hidden );
+				setClass( ul, dropdownLengthType( visibleItemsLength ) );
+			}
+		}
+	};
+
+	function createListFor( element ) {
+		const links = getLinksFor( element );
+		const ul = document.createElement( 'ul' );
+
+		ul.classList.add( 'api-subheader__navigation-dropdown' );
+		ul.classList.add( dropdownLengthType( links.length ) );
+
+		for ( const link of links ) {
+			ul.appendChild( link );
+		}
+
+		return ul;
+	}
+
+	function getLinksFor( element ) {
+		const outputList = [];
+		const lists = document.querySelectorAll( 'ul[data-type=' + element.dataset.type + ']' );
+		for ( const list of lists ) {
+			const links = list.querySelectorAll( 'li.collapsing-list__item' );
+			for ( const link of links ) {
+				const listItem = document.createElement( 'li' );
+				const clonedLink = link.querySelector( 'h3 a.member-name' ).cloneNode( true );
+				clonedLink.classList.add( 'api-subheader__navigation-link' );
+				listItem.appendChild( clonedLink );
+				Object.assign( listItem.dataset, link.dataset );
+				outputList.push( listItem );
+			}
+		}
+		return outputList;
+	}
+
+	function dropdownLengthType( elements ) {
+		if ( elements > 60 ) {
+			return CLASS_NAMES.huge;
+		} else if ( elements > 20 ) {
+			return CLASS_NAMES.big;
+		} else if ( elements > 0 ) {
+			return CLASS_NAMES.small;
+		} else {
+			return CLASS_NAMES.empty;
+		}
+	}
+
+	function setClass( element, className ) {
+		if ( !element.classList.contains( className ) ) {
+			element.classList.add( className );
+		}
+
+		for ( const cls in CLASS_NAMES ) {
+			if ( CLASS_NAMES[ cls ] !== className ) {
+				element.classList.remove( CLASS_NAMES[ cls ] );
+			}
+		}
+	}
+}
+

package/themes/umberto/src/umberto/js/_prism.js

@@ -0,0 +1,104 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+import './vendor/prism';
+
+export function setupPrism() {
+	const locationHref = window.location.href;
+	const isApiPage = !!locationHref.match( /\/api\// );
+
+	// For CKEditor 4 snippets (SDK) attach the "Download" button.
+	if ( locationHref.match( /\/ckeditor4\// ) && locationHref.match( /\/examples\// ) ) {
+		createDownloadButton();
+	}
+
+	Array.from( document.querySelectorAll( 'pre code' ) )
+		.filter( element => {
+			// Don't highlight code block's inside editor's content. See: #838.
+			if ( element.closest( '.ck-content' ) ) {
+				return false;
+			}
+
+			// Don't highlight the element if it contains the `no-highlight` class.
+			if ( element.classList.contains( 'no-highlight' ) ) {
+				return false;
+			}
+
+			return true;
+		} )
+		.forEach( element => {
+			const classList = element.classList.values();
+			const preElement = element.parentElement;
+
+			// Don't highlight the element if it has no parent.
+			if ( !preElement ) {
+				return false;
+			}
+
+			for ( const className of classList ) {
+				preElement.classList.add( `language-${ className }` );
+			}
+
+			// Render as `javascript` on API pages and as `plaintext` for others if the language is not specified.
+			if ( !preElement.classList.length ) {
+				preElement.classList.add( isApiPage ? 'language-javascript' : 'language-plaintext' );
+			}
+
+			element.setAttribute( 'data-prismjs-copy-success', 'Ready!' );
+			preElement.classList.add( 'highlight' );
+
+			window.Prism.highlightElement( element );
+		} );
+
+	// Add the `[title]` attribute to "Copy" button.
+	[ ...document.querySelectorAll( '.copy-to-clipboard-button' ) ]
+		.forEach( button => {
+			button.title = 'Copy the code to the clipboard';
+		} );
+}
+
+/**
+ * Add the "Download" button to the code snippets.
+ */
+function createDownloadButton() {
+	window.Prism.plugins.toolbar.registerButton( 'download', env => {
+		const button = document.createElement( 'button' );
+		const span = document.createElement( 'span' );
+
+		span.innerHTML = 'Download';
+		button.appendChild( span );
+		button.classList.add( 'download-snippet-button' );
+		button.title = 'Download this snippet';
+
+		button.addEventListener( 'click', () => {
+			download( env.element.textContent, 'index.html', 'text/html' );
+		} );
+
+		return button;
+	} );
+
+	function download( data, filename, type ) {
+		const file = new Blob( [ data ], { type } );
+
+		if ( window.navigator.msSaveOrOpenBlob ) {
+			// IE10+
+			window.navigator.msSaveOrOpenBlob( file, filename );
+		} else {
+			// Others
+			const a = document.createElement( 'a' );
+			const url = URL.createObjectURL( file );
+
+			a.href = url;
+			a.download = filename;
+			document.body.appendChild( a );
+
+			a.click();
+			setTimeout( function() {
+				document.body.removeChild( a );
+				window.URL.revokeObjectURL( url );
+			} );
+		}
+	}
+}

package/themes/umberto/src/umberto/js/_rwdmenu.js

@@ -0,0 +1,15 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+export function rwdButton() {
+	// Handle the mobile menu button.
+	const rwdButton = document.querySelector( '.header__main-rwd-button a' );
+	const rwdTop = document.querySelector( '.top' );
+
+	rwdButton.addEventListener( 'click', e => {
+		e.preventDefault();
+		rwdTop.classList.toggle( 'rwd-menu-active' );
+	} );
+}

package/themes/umberto/src/umberto/js/_samplecode.js

@@ -0,0 +1,23 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+import $ from 'jquery';
+
+export default function sampleCode() {
+	const headerHeight = document.querySelector( 'header.top' ).offsetHeight;
+
+	// Accordion toggling button.
+	$( '.sdk-sample-source-code__button' ).on( 'click', function( e ) {
+		e.preventDefault();
+
+		$( this ).toggleClass( 'active' );
+		$( this ).parent().find( '.sdk-sample-source-code__code-block' ).toggleClass( 'active' );
+
+		// scroll smoothly to the clicked content
+		$( 'html, body' ).animate( {
+			scrollTop: $( this ).offset().top - headerHeight - 20
+		}, 400 );
+	} );
+}

package/themes/umberto/src/umberto/js/_sidenavigation.js

@@ -0,0 +1,59 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+export default function sideNavigation() {
+	const folderButtons = Array.from( document.querySelectorAll( '.tree:not(.api-tree) .tree__item--folder' ) );
+	const guideTreeElement = document.getElementById( 'guidetree' );
+	const foldedClassName = 'tree__item-nested-list--hidden';
+	const activeClassName = '.tree__item__wrapper--active';
+	const localStorageKey = 'foldersState';
+
+	let foldersState = JSON.parse( window.localStorage.getItem( localStorageKey ) );
+	if ( foldersState === null ) {
+		foldersState = {};
+	}
+
+	folderButtons.forEach( btn => {
+		const element = btn.parentNode.nextElementSibling; // Get <ul> element
+		const id = element.getAttribute( 'data-id' );
+
+		applyFolderState( element, foldersState[ id ] );
+		checkForActiveChildren( element, id );
+
+		btn.addEventListener( 'click', function() {
+			element.classList.toggle( foldedClassName );
+			saveFolderState( id, isFolded( element ) );
+		} );
+	} );
+
+	if ( guideTreeElement ) {
+		guideTreeElement.classList.add( 'state-applied' );
+	}
+
+	function applyFolderState( element, folded ) {
+		if ( folded === false ) {
+			element.classList.remove( foldedClassName );
+		}
+		if ( folded === true ) {
+			element.classList.add( foldedClassName );
+		}
+	}
+
+	function saveFolderState( id, state ) {
+		foldersState[ id ] = state;
+		window.localStorage.setItem( localStorageKey, JSON.stringify( foldersState ) );
+	}
+
+	function checkForActiveChildren( element, id ) {
+		if ( element.querySelectorAll( activeClassName ).length > 0 ) {
+			element.classList.remove( foldedClassName );
+			saveFolderState( id, isFolded( element ) );
+		}
+	}
+
+	function isFolded( element ) {
+		return element.classList.contains( foldedClassName );
+	}
+}

package/themes/umberto/src/umberto/js/_toc.js

@@ -0,0 +1,93 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+import $ from 'jquery';
+import throttle from 'lodash/throttle';
+
+export function trackArticlePosition() {
+	let headingsData = [];
+	const toc = $( '.secondary-navigation' );
+	const tocLinks = $( '.secondary-navigation a' );
+	const currentItemClass = 'secondary-navigation__current-position';
+	let tocItemClicked = false;
+
+	function getHeadingsData() {
+		headingsData = [];
+
+		$( ':header' ).each( function() {
+			const currentHeading = $( this );
+			const currentHeadingId = currentHeading.attr( 'id' );
+
+			if ( !currentHeadingId ) {
+				return true;
+			}
+
+			headingsData.unshift( {
+				top: currentHeading.offset().top,
+				tocItem: toc.find( `a[href$="#${ currentHeadingId }"]` )
+			} );
+		} );
+	}
+
+	function updateToc() {
+		// Prevent updating when ToC item was clicked and page scrolled.
+		if ( tocItemClicked ) {
+			return;
+		}
+
+		// When ToC is not fixed to the right, there is no need for marking current position.
+		if ( toc.css( 'position' ) !== 'fixed' ) {
+			if ( tocLinks.hasClass( currentItemClass ) ) {
+				tocLinks.removeClass( currentItemClass );
+			}
+
+			return;
+		}
+
+		const scrollTop = $( window ).scrollTop();
+		const offsetAboveHeading = $( window ).height() / 3;
+
+		for ( const hd of headingsData ) {
+			if ( scrollTop > hd.top - offsetAboveHeading ) {
+				if ( !hd.tocItem.hasClass( currentItemClass ) ) {
+					tocLinks.removeClass( currentItemClass );
+					hd.tocItem.addClass( currentItemClass );
+				}
+
+				return;
+			}
+		}
+
+		if ( tocLinks.hasClass( currentItemClass ) ) {
+			tocLinks.removeClass( currentItemClass );
+		}
+	}
+
+	tocLinks.click( function() {
+		tocItemClicked = true;
+
+		if ( tocLinks.hasClass( currentItemClass ) ) {
+			tocLinks.removeClass( currentItemClass );
+		}
+
+		$( this ).addClass( currentItemClass );
+		setTimeout( () => {
+			tocItemClicked = false;
+		}, 200 );
+	} );
+
+	$( window ).resize( () => {
+		getHeadingsData();
+		updateToc();
+	} );
+
+	$( window ).scroll( throttle( updateToc, 100 ) );
+
+	// Timeout because highlight.js takes time to run and it changes headings position.
+	setTimeout( function() {
+		getHeadingsData();
+		updateToc();
+	}, 200 );
+}

package/themes/umberto/src/umberto/js/_tooltips.js

@@ -0,0 +1,39 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+import $ from 'jquery';
+import tippy from 'tippy.js';
+
+export function enableBadgeTooltips() {
+	$( '[data-badge-tooltip]' ).each( ( index, element ) => {
+		tippy( element, {
+			content: element.dataset.badgeTooltip,
+			placement: 'right',
+			duration: 150,
+			animation: 'scale',
+			theme: 'light-border',
+			zIndex: 1
+		} );
+	} );
+}
+
+export function createTooltip( target, content, options ) {
+	const tooltip = tippy( target, {
+		content,
+		...options
+	} );
+
+	const closeButton = tooltip.popper.querySelector( '.tippy-content__close-button' );
+
+	closeButton.addEventListener( 'click', () => {
+		tooltip.hide();
+	} );
+
+	target.addEventListener( 'click', () => {
+		tooltip.hide();
+	} );
+
+	return tooltip;
+}

package/themes/umberto/src/umberto/js/_warningbanner.js

@@ -0,0 +1,18 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+import $ from 'jquery';
+
+/**
+ * Displays a warning banner on top of the page with a pre-defined message.
+ *
+ * @param {String} message
+ */
+export default function showWarningBanner( message ) {
+	const warningElement = $( '<div class="warning-banner"></div>' );
+
+	warningElement.append( `<span>⚠️ Warning</span><span>${ message }</span>` );
+	warningElement.appendTo( 'header.top' );
+}

package/themes/umberto/src/umberto/js/app.js

@@ -0,0 +1,70 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+// Polyfill for `window.Symbol`.
+import '@babel/polyfill';
+// Polyfill for `Element.closest()`.
+import 'element-closest/browser';
+
+import $ from 'jquery';
+import { setupPrism } from './_prism';
+import { enableCollapsables, hideTogglers } from './_collapsables';
+import { enableAnchors } from './_anchors';
+import { enableDropdowns } from './_dropdowns';
+import { enableFiltering } from './_filtering';
+import { trackArticlePosition } from './_toc';
+import { expandApiTree, scrollApiTree } from './_apitree';
+import { setUpFuse } from './_apisearch';
+import pageNavigation from './_pagenavigation';
+import { activateDevNames } from './_devnames';
+import sideNavigation from './_sidenavigation';
+import sampleCode from './_samplecode';
+import copyMobileApiNavigation from './_copymobileapinavigation';
+import { rwdButton } from './_rwdmenu';
+import imageModal from './_imageModal';
+import showWarningBanner from './_warningbanner';
+import { enableBadgeTooltips, createTooltip } from './_tooltips';
+import attachPermalinkListener from './_attachpermalinklistener';
+import { createCodeSwitcherButtons } from './_codeswitcherbuttons';
+
+// Changing documentation theme. To enable, type in the console: `localStorage.setItem( 'theme', 'theme-dark' )`.
+if ( localStorage.getItem( 'theme' ) === 'theme-dark' ) {
+	document.getElementsByTagName( 'html' )[ 0 ].classList.add( 'theme-dark' );
+}
+
+// Set up the global variable.
+window.umberto = {
+	// The `VERSION` value will be replaced by the `DefinePlugin` webpack plugin.
+	version: VERSION, // eslint-disable-line no-undef
+	showWarningBanner,
+	createTooltip
+};
+
+// Ask the SOS team before touching this 😛
+window.open.closed = 1;
+
+$( document ).ready( () => {
+	pageNavigation(); // pageNavigation - needs to be run before filtering initialization.
+	copyMobileApiNavigation(); // copy API Tree into mobile navigation
+	sideNavigation();
+	expandApiTree();
+	scrollApiTree();
+	enableFiltering();
+	setupPrism();
+	enableCollapsables();
+	hideTogglers();
+	enableAnchors();
+	enableDropdowns();
+	trackArticlePosition();
+	setUpFuse();
+	activateDevNames();
+	attachPermalinkListener();
+	rwdButton();
+	imageModal(); // lightbox for { @img } elements
+	// `sampleCode()` must be called after the `setupPrism()` function.
+	sampleCode(); // control accordion of sample code and buttons(copy/download)
+	enableBadgeTooltips(); // attaches tippy.js tooltip for all elements with data-badge-tooltip
+	createCodeSwitcherButtons();
+} );