umberto 7.0.2 → 8.0.0

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

@@ -3,63 +3,101 @@
  * For licensing, see LICENSE.md.
  */
 
-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
+import { afterDomReady } from './helpers/after-dom-ready';
+
+import { Dropdown } from './components/dropdown';
+import { MobileOverlay } from './components/mobile-overlay';
+import { TableOfContents } from './modules/table-of-contents';
+import { ApiTableOfContents } from './modules/table-of-contents-api';
+import { ApiFilter } from './modules/api-filter';
+import { MobileNav } from './modules/mobile-nav';
+import { LinksPrefetch } from './modules/links-prefetch';
+import { Header } from './modules/header';
+import { HeaderBar } from './modules/header-bar';
+import { HashLink } from './components/hash-link';
+import { Sidebar } from './modules/sidebar';
+import { NavTree } from './components/nav-tree';
+import { ApiNavTree } from './components/api-nav-tree';
+import { ApiToggle } from './components/api-toggle';
+import { Tabs } from './components/tabs';
+import { Breadcrumbs } from './components/breadcrumbs';
+import { AlgoliaSearch } from './modules/algolia-search';
+import { HeadingLink } from './components/heading-link';
+import { TooltipPopover } from './components/tooltip-popover';
+import { imageZoom } from './components/image-zoom';
+import { Expandable } from './components/expandable';
+import { CodeSwitcher } from './components/code-switcher';
+import { CodeBlock } from './components/code-block';
+import { FakeDevtools } from './components/fake-devtools';
+import { IFrame } from './components/iframe';
+
+import { isMobile } from './helpers/is-mobile';
+
+import './web-components/svg-icon';
+import './public-api';
+
+const safeAttach = ( component, name ) => {
+	try {
+		return component.attach();
+	} catch ( error ) {
+		console.error( `Failed to initialize ${ name } component:`, error );
+	}
 };
 
 // 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();
+afterDomReady( () => {
+	// Initialize it faster to avoid CLS flashing when header is closed.
+	safeAttach( HeaderBar, 'HeaderBar' );
+
+	// It MUST be synchronous to avoid race conditions between snippets that use rendered components.
+	safeAttach( Header, 'Header' );
+	safeAttach( Dropdown, 'Dropdown' );
+	safeAttach( TableOfContents, 'TableOfContents' );
+	safeAttach( ApiTableOfContents, 'ApiTableOfContents' );
+	safeAttach( Sidebar, 'Sidebar' );
+	safeAttach( NavTree, 'NavTree' );
+	safeAttach( ApiToggle, 'ApiToggle' );
+	safeAttach( ApiFilter, 'ApiFilter' );
+	safeAttach( MobileOverlay, 'MobileOverlay' );
+	safeAttach( MobileNav, 'MobileNav' );
+	safeAttach( HashLink, 'HashLink' );
+	safeAttach( Tabs, 'Tabs' );
+	safeAttach( AlgoliaSearch, 'AlgoliaSearch' );
+	safeAttach( Breadcrumbs, 'Breadcrumbs' );
+	safeAttach( HeadingLink, 'HeadingLink' );
+	safeAttach( TooltipPopover, 'TooltipPopover' );
+	safeAttach( Expandable, 'Expandable' );
+	safeAttach( IFrame, 'IFrame' );
+
+	// Make sure that code blocks are initialized before code switcher.
+	safeAttach( CodeBlock, 'CodeBlock' );
+	safeAttach( CodeSwitcher, 'CodeSwitcher' );
+	safeAttach( FakeDevtools, 'FakeDevtools' );
+
+	imageZoom();
+
+	if ( !isMobile() ) {
+		LinksPrefetch.the.init();
+	}
+
+	// Attach the ApiNavTree component when the document is fully loaded. (Safari case)
+	safeAttach( ApiNavTree, 'ApiNavTree' );
+
+	// Make sure all components related to header size are initialized.
+	Header.the.dispatchHeaderResizeEvent();
+
+	// Flush the callbacks queue that will be executed after mounting all umberto components.
+	if ( window.umberto._afterReadyCallbacks ) {
+		window.umberto._afterReadyCallbacks.forEach( callback => {
+			callback();
+		} );
+
+		delete window.umberto._afterReadyCallbacks;
+	}
+
+	window.umberto.afterReady = callback => {
+		callback();
+	};
 } );

package/themes/umberto/src/gloria/js/components/api-nav-tree.js

@@ -0,0 +1,171 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+import { BaseComponent } from '../components/base-component';
+import { toggleHeight } from '../helpers/toggle-height';
+import { getParentsUntil } from '../helpers/get-parents-until';
+import { onMobileOverlayStateChange } from '../components/mobile-overlay';
+
+export class ApiNavTree extends BaseComponent {
+	/**
+	 * Creates an API navigation tree component.
+	 *
+	 * @param element - The navigation tree element.
+	 */
+	constructor( element ) {
+		super( {
+			isMobileApiNavInitialized: false
+		} );
+
+		this.elements = {
+			navTree: element,
+			sidebarNav: element.parentElement
+		};
+	}
+
+	/**
+	 * Initializes navigation tree component on the page.
+	 */
+	static attach() {
+		const navTrees = document.querySelectorAll( '.js-api-tree' );
+
+		navTrees.forEach( navTree => {
+			new ApiNavTree( navTree ).init();
+		} );
+	}
+
+	/**
+	 * Initializes the navigation tree component with event listeners.
+	 */
+	init() {
+		const { navTree, sidebarNav } = this.elements;
+
+		navTree?.addEventListener( 'click', async event => {
+			const button = event.target.closest( 'button' ) || event.target.closest( 'span' );
+
+			sessionStorage.setItem( 'ckApiSidebarScroll', sidebarNav.scrollTop );
+
+			if ( !button || button.tagName === 'A' ) {
+				return;
+			}
+
+			const toggleButton = button.tagName === 'BUTTON' ? button : button.previousElementSibling;
+
+			if ( !toggleButton ) {
+				return;
+			}
+
+			toggleButton.classList.toggle( 'api-tree__button--open' );
+
+			const nestedList = button.parentElement.parentElement.querySelector( '.api-tree__list' );
+
+			if ( !nestedList ) {
+				return;
+			}
+
+			const toggleResult = await toggleHeight( nestedList, 'api-tree__list--hidden' );
+
+			if ( toggleResult === 'visible' ) {
+				nestedList.style.display = 'block';
+			} else {
+				nestedList.style.display = 'none';
+			}
+		} );
+
+		this.expandWhereYouAre();
+		this.render();
+
+		if ( this.state.isMobileApiNavInitialized ) {
+			return;
+		}
+
+		// Add listener for mobile overlay opening - to copy API sidebar to mobile view.
+		onMobileOverlayStateChange( {
+			eventName: 'opening',
+			callback: () => {
+				const desktopApiNav = document.querySelector( '#js-api-tree-desktop' );
+				const desktopApiNavClone = desktopApiNav.cloneNode( true );
+				const mobileApiNav = document.querySelector( '#js-api-tree-mobile' );
+
+				mobileApiNav.appendChild( desktopApiNavClone );
+
+				this.setState( {
+					isMobileApiNavInitialized: true
+				} );
+
+				new ApiNavTree( mobileApiNav.querySelector( '.js-api-tree' ) ).init();
+			}
+		} );
+	}
+
+	render() {
+		this.retrieveScrollbarPosition();
+	}
+
+	/**
+	 * Expands the navigation tree to show the current page's location.
+	 */
+	expandWhereYouAre() {
+		const { navTree } = this.elements;
+
+		if ( !document.querySelector( '.js-api-h1' ) ) {
+			return;
+		}
+
+		const activeTreeItemClass = 'active';
+		const togglerCollapsedClass = 'api-tree__list--hidden';
+		const pageIdentifier = document.querySelector( '.js-api-h1' ).dataset.ln;
+
+		if ( !pageIdentifier || pageIdentifier === 'index' ) {
+			return;
+		}
+
+		const currentTreeItem = navTree.querySelector( `div[data-ln='${ pageIdentifier }']` );
+		const closestParent = currentTreeItem.closest( '.api-tree__item-wrapper' );
+
+		closestParent?.classList.add( activeTreeItemClass );
+
+		const ancestors = getParentsUntil( currentTreeItem, '.js-api-tree' )
+			.filter( element => element.classList.contains( 'api-tree__list--hidden' ) );
+		const siblingsLists = navTree.querySelectorAll( '.api-tree__item-wrapper.active ~ .api-tree__list' );
+
+		[ ...ancestors, ...siblingsLists ].forEach( listItem => {
+			listItem.classList.remove( togglerCollapsedClass );
+			listItem.style.height = '';
+			listItem.style.display = 'block';
+		} );
+
+		closestParent?.firstElementChild.classList.add( 'api-tree__button--open' );
+	}
+
+	retrieveScrollbarPosition() {
+		const { navTree, sidebarNav } = this.elements;
+
+		if ( !sidebarNav.classList.contains( 'c-sidebar__nav' ) ) {
+			return;
+		}
+
+		// Retrieve the stored scroll position from sessionStorage.
+		const storedScrollPosition = sessionStorage.getItem( 'ckApiSidebarScroll' );
+
+		// If a stored scroll position exists, scroll the sidebar to that position.
+		if ( storedScrollPosition !== null ) {
+			sidebarNav.scrollTop = Number( storedScrollPosition );
+		}
+
+		const activeElement = navTree.querySelector( '.api-tree__item-wrapper.active' );
+
+		setTimeout( () => {
+			// Ensure the sidebar is scrolled to the active element after a short delay.
+			activeElement?.scrollIntoView( {
+				behavior: 'instant',
+				block: 'nearest',
+				inline: 'nearest'
+			} );
+
+			sessionStorage.setItem( 'ckApiSidebarScroll', sidebarNav.scrollTop );
+		}, 100 );
+	}
+}

package/themes/umberto/src/gloria/js/components/api-toggle.js

@@ -0,0 +1,92 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+import { BaseComponent } from './base-component';
+import { toggleHeight } from '../helpers/toggle-height';
+
+// .js-api-collapsing-button
+
+export class ApiToggle extends BaseComponent {
+	/**
+	 * Creates a API toggle component.
+	 *
+	 * @param element - The toggle button.
+	 */
+	constructor( element ) {
+		super();
+
+		this.elements = {
+			toggleButton: element
+		};
+	}
+
+	/**
+	 * Initializes API toggle component on the page.
+	 */
+	static attach() {
+		const toggleButtons = document.querySelectorAll( '.js-api-collapsing-button' );
+
+		toggleButtons.forEach( button => {
+			new ApiToggle( button ).init();
+		} );
+
+		ApiToggle.expandWhereYouAre();
+	}
+
+	/**
+	 * Expands the error item if the hash in the URL matches an error id.
+	 * This is a static utility for the whole API/error list, not for a single instance.
+	 */
+	static expandWhereYouAre() {
+		if ( window.location.hash ) {
+			const hash = window.location.hash.slice( 1 );
+			const target = document.getElementById( hash );
+
+			if ( target && target.classList.contains( 'js-api-collapsing-button' ) ) {
+				const parent = target.parentElement;
+				const descriptionElement = parent.querySelector( '.collapsing-list__description' );
+
+				if ( descriptionElement && !parent.classList.contains( 'collapsing-list__item--open' ) ) {
+					toggleHeight( descriptionElement, 'collapsing-list__description--open' ).then( () => {
+						descriptionElement.setAttribute( 'aria-hidden', 'false' );
+						target.setAttribute( 'aria-expanded', 'true' );
+						parent.classList.add( 'collapsing-list__item--open' );
+					} );
+				}
+			}
+		}
+	}
+
+	/**
+	 * Initializes the API toggle component with event listeners.
+	 */
+	init() {
+		const { toggleButton } = this.elements;
+
+		toggleButton?.addEventListener( 'click', async () => {
+			const parent = toggleButton.parentElement;
+			const descriptionElement = parent.querySelector( '.collapsing-list__description' );
+
+			if ( !descriptionElement ) {
+				return;
+			}
+
+			const toggleState = await toggleHeight( descriptionElement, 'collapsing-list__description--open' );
+			const isExpanded = toggleState === 'visible';
+
+			// Update ARIA attributes for accessibility
+			descriptionElement.setAttribute( 'aria-hidden', !isExpanded );
+			toggleButton.setAttribute( 'aria-expanded', isExpanded );
+
+			parent.classList.toggle( 'collapsing-list__item--open' );
+		} );
+
+		this.render();
+	}
+
+	render() {
+		// No specific rendering logic for the navigation tree component.
+	}
+}

package/themes/umberto/src/gloria/js/components/base-component.js

@@ -0,0 +1,41 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/**
+ * Base class for all components implementing state management functionality.
+ */
+export class BaseComponent {
+	/**
+	 * Creates a base component with the given initial state.
+	 *
+	 * @param initialState - Initial state object for the component,
+	 */
+	constructor( initialState = {} ) {
+		this.state = initialState;
+	}
+
+	/**
+	 * Updates the component state and triggers a render.
+	 *
+	 * @param newState - Object containing state properties to update,
+	 */
+	setState( newState ) {
+		const prevState = this.state;
+
+		this.state = { ...this.state, ...newState };
+		this.render( prevState, this.state );
+	}
+
+	/**
+	 * Renders the component based on current state.
+	 * This method should be overridden by child classes.
+	 *
+	 * @param prevState - Previous component state,
+	 * @param state - Current component state,
+	 */
+	render() {
+		throw new Error( 'Render method not implemented' );
+	}
+}

package/themes/umberto/src/gloria/js/components/breadcrumbs.js

@@ -0,0 +1,115 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+import { BaseComponent } from './base-component';
+
+/**
+ * Component responsible for handling breadcrumbs overflow and scroll behavior.
+ */
+export class Breadcrumbs extends BaseComponent {
+	/**
+	 * Creates a breadcrumbs component.
+	 *
+	 * @param element - The breadcrumbs DOM element
+	 */
+	constructor( element ) {
+		super( {
+			isOverflowing: false,
+			hasLeftShadow: false
+		} );
+
+		this.elements = {
+			container: element,
+			wrapper: element.querySelector( '.c-breadcrumbs__wrapper' ),
+			list: element.querySelector( '.c-breadcrumbs__list' )
+		};
+
+		// The threshold in pixels to determine when to show shadow
+		this.threshold = 20;
+	}
+
+	/**
+	 * Creates breadcrumbs component.
+	 */
+	static attach() {
+		const breadcrumbsElement = document.querySelector( '.js-breadcrumbs' );
+
+		if ( !breadcrumbsElement ) {
+			return;
+		}
+
+		new Breadcrumbs( breadcrumbsElement ).init();
+	}
+
+	/**
+	 * Initializes the breadcrumbs component.
+	 */
+	init() {
+		window.addEventListener( 'resize', this.checkOverflow.bind( this ) );
+		this.elements.wrapper.addEventListener( 'scroll', this.checkShadow.bind( this ) );
+
+		this.checkOverflow();
+		this.checkShadow();
+	}
+
+	/**
+	 * Renders the breadcrumbs component.
+	 * Checks if breadcrumbs are wider than their container and adds necessary styling.
+	 */
+	render( prevState, state = this.state ) {
+		const { wrapper, list, container } = this.elements;
+
+		if ( !!prevState.isOverflowing !== !!state.isOverflowing ) {
+			if ( state.isOverflowing ) {
+				const scroll = () => {
+					wrapper.style.overflowX = 'auto';
+					wrapper.scrollLeft = list.scrollWidth - wrapper.clientWidth + 10;
+				};
+
+				scroll();
+
+				if ( document.readyState === 'loading' ) {
+					window.addEventListener( 'load', scroll );
+				}
+			} else {
+				// Reset styles if breadcrumbs fit in container
+				wrapper.style.overflowX = 'visible';
+			}
+		}
+
+		// Handle shadow class based on state change
+		container.classList.toggle( 'c-breadcrumbs--shadow-left', state.hasLeftShadow );
+	}
+
+	/**
+	 * Checks if the breadcrumbs overflow their container and updates state accordingly.
+	 */
+	checkOverflow() {
+		const { wrapper, list } = this.elements;
+
+		const wrapperWidth = wrapper.clientWidth;
+		const listWidth = list.scrollWidth;
+
+		// Update overflow state
+		const isOverflowing = listWidth > wrapperWidth + this.threshold;
+
+		if ( isOverflowing !== this.state.isOverflowing ) {
+			this.setState( { isOverflowing } );
+		}
+	}
+
+	/**
+	 * Checks if shadow should be displayed and updates state accordingly.
+	 */
+	checkShadow() {
+		const hasLeftShadow = this.elements.wrapper.scrollLeft > 0;
+
+		if ( this.state.hasLeftShadow !== hasLeftShadow ) {
+			this.setState( {
+				hasLeftShadow
+			} );
+		}
+	}
+}