umberto 7.0.2 → 8.0.1

package/themes/umberto/src/gloria/js/helpers/throttle.js

@@ -0,0 +1,46 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/**
+ * Creates a throttled version of a function that only executes at most once
+ * every specified delay period.
+ *
+ * @param {Function} callback - The function to throttle.
+ * @param {number} delay - The delay in milliseconds.
+ * @returns {Function} - The throttled function.
+ */
+export function throttle( callback, delay ) {
+	if ( typeof callback !== 'function' ) {
+		throw new Error( 'Callback must be a function' );
+	}
+
+	let isThrottled = false;
+	let savedArgs = null;
+	let savedThis = null;
+
+	function wrapper( ...args ) {
+		if ( isThrottled ) {
+			savedArgs = args;
+			// eslint-disable-next-line consistent-this
+			savedThis = this;
+			return;
+		}
+
+		callback.apply( this, args );
+		isThrottled = true;
+
+		setTimeout( () => {
+			isThrottled = false;
+
+			if ( savedArgs ) {
+				wrapper.apply( savedThis, savedArgs );
+				savedArgs = null;
+				savedThis = null;
+			}
+		}, delay );
+	}
+
+	return wrapper;
+}

package/themes/umberto/src/gloria/js/helpers/timeout.js

@@ -0,0 +1,14 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/**
+ * Creates a promise that resolves after the specified timeout.
+ *
+ * @param ms - The timeout in milliseconds
+ * @returns A promise that resolves after the specified timeout
+ */
+export function timeout( ms ) {
+	return new Promise( resolve => setTimeout( resolve, ms ) );
+}

package/themes/umberto/src/gloria/js/helpers/toggle-height.js

@@ -0,0 +1,46 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/**
+ * Toggles the height of an element between 0 and its scrollHeight.
+ * This is useful for creating collapsible sections.
+ * @param {HTMLElement} element - The element to toggle.
+ * @param {string} toggleClass - CSS class to add when the element is collapsed.
+ * @returns {Promise} - A promise that resolves when setting properties is complete.
+ */
+export function toggleHeight( element, toggleClass ) {
+	return new Promise( resolve => {
+		// If no height is present, set it to the scrollHeight.
+		if ( element.style.height === '' ) {
+			element.style.height = element.scrollHeight + 'px';
+		}
+
+		setTimeout( () => {
+			if ( element.style.height === '0px' ) {
+				element.style.display = 'block';
+				element.style.height = element.scrollHeight + 'px';
+				element.classList.remove( toggleClass );
+
+				// Remove the height property after the transition ends to allow for reflow.
+				element.addEventListener( 'transitionend', () => {
+					element.style.height = '';
+					resolve( 'visible' );
+				}, {
+					once: true
+				} );
+			} else {
+				element.style.height = '0px';
+				element.classList.add( toggleClass );
+
+				// Remove the height property after the transition ends to allow for reflow.
+				element.addEventListener( 'transitionend', () => {
+					resolve( 'hidden' );
+				}, {
+					once: true
+				} );
+			}
+		}, 10 );
+	} );
+}

package/themes/umberto/src/gloria/js/helpers/tween.js

@@ -0,0 +1,100 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+import { clamp } from './clamp';
+import { prefersReducedMotion } from './prefers-reduced-motion';
+
+/**
+ * Creates a tween animation that runs from 0 to 1 over a specified duration.
+ * The provided interpolation function is called on each animation frame with the current progress value.
+ *
+ * @param config - Configuration object
+ * @param config.onUpdate - Function called on each frame with current progress (0-1)
+ * @param [config.duration=300] - Animation duration in milliseconds
+ * @param [config.respectReducedMotion=true] - Whether to respect user's reduced motion preference
+ * @returns Animation control object with start and stop methods that return promises
+ */
+export function tween( { onUpdate, duration = 300, respectReducedMotion = true } ) {
+	let animationId = null;
+	let startTime = null;
+	let resolvePromise = null;
+	let rejectPromise = null;
+
+	// Check if reduced motion is preferred
+	const shouldSkipAnimation = respectReducedMotion && prefersReducedMotion();
+
+	// Animation frame handler
+	const animate = timestamp => {
+		// Set start time on first frame
+		if ( !startTime ) {
+			startTime = timestamp;
+		}
+
+		// Calculate progress (0 to 1)
+		const elapsed = timestamp - startTime;
+		let progress = elapsed / duration;
+
+		// Ensure progress is exactly between 0 and 1
+		progress = clamp( 0, 1, progress );
+
+		// Call update function with current progress
+		onUpdate( progress );
+
+		// Continue animation if not complete
+		if ( progress < 1 ) {
+			animationId = requestAnimationFrame( animate );
+		} else {
+			// Animation complete
+			if ( resolvePromise ) {
+				resolvePromise();
+			}
+		}
+	};
+
+	// Stop animation
+	const stop = () => {
+		if ( animationId !== null ) {
+			cancelAnimationFrame( animationId );
+			animationId = null;
+
+			if ( rejectPromise ) {
+				rejectPromise( new Error( 'Animation stopped' ) );
+			}
+		}
+	};
+
+	// Start animation
+	const start = () => {
+		// Cancel any existing animation
+		stop();
+
+		// Reset start time
+		startTime = null;
+
+		// Create new promise
+		const promise = new Promise( ( resolve, reject ) => {
+			resolvePromise = resolve;
+			rejectPromise = reject;
+		} );
+
+		// If reduced motion is preferred, skip animation and complete immediately
+		if ( shouldSkipAnimation ) {
+			// Call update function with final value (1.0)
+			onUpdate( 1.0 );
+			// Resolve the promise immediately
+			setTimeout( () => resolvePromise(), 0 );
+		} else {
+			// Begin normal animation
+			animationId = requestAnimationFrame( animate );
+		}
+
+		return promise;
+	};
+
+	return {
+		start,
+		stop
+	};
+}

package/themes/umberto/src/gloria/js/helpers/wrap-around.js

@@ -0,0 +1,39 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/**
+ * Wraps a value around the specified range boundaries.
+ * When value exceeds max, it wraps around to min.
+ * When value is below min, it wraps around to max.
+ *
+ * @param min - Minimum boundary
+ * @param max - Maximum boundary
+ * @param value - The value to wrap around
+ * @returns The wrapped value
+ *
+ * @example
+ * // Returns 0 (6 exceeds max by 1, wraps to min)
+ * wrapAround(0, 5, 6);
+ *
+ * @example
+ * // Returns 2 (7 exceeds max by 2, wraps to min+1)
+ * wrapAround(0, 5, 7);
+ *
+ * @example
+ * // Returns 5 (-1 is below min by 1, wraps to max)
+ * wrapAround(0, 5, -1);
+ */
+export function wrapAround( min, max, value ) {
+	const range = max - min + 1;
+
+	// Adjust the value to be relative to min
+	const relativeValue = value - min;
+
+	// Use modulo to wrap around, adding range to handle negative values
+	const wrappedValue = ( ( relativeValue % range ) + range ) % range;
+
+	// Add min back to get the result in the original range
+	return wrappedValue + min;
+}

package/themes/umberto/src/gloria/js/modules/algolia-search.js

@@ -0,0 +1,168 @@
+/**
+ * @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 { identity } from '../helpers/identity';
+import { injectScript } from '../helpers/inject-script';
+import { pipe } from '../helpers/pipe';
+
+const DOCSEARCH_JS_URL = 'https://cdn.jsdelivr.net/npm/@docsearch/js@3.9.0/dist/umd/index.min.js';
+
+/**
+ * Component responsible for binding the algolia search component to the header.
+ */
+export class AlgoliaSearch extends BaseComponent {
+	/**
+	 * Creates a algolia search component.
+	 *
+	 * @param element - The algolia search DOM element
+	 */
+	constructor( element ) {
+		super();
+
+		this.config = JSON.parse( element.dataset.algoliaSearchConfig );
+		this.filters = JSON.parse( element.dataset.algoliaSearchFilters || '{}' );
+		this.boost = JSON.parse( element.dataset.algoliaSearchBoost || '{}' );
+
+		this.elements = {
+			wrapper: element
+		};
+	}
+
+	/**
+	 * Creates algolia search component.
+	 */
+	static async attach() {
+		const headerElements = [ ...document.querySelectorAll( '.js-algolia-search' ) ];
+
+		await Promise.all(
+			headerElements.map( headerElement => new AlgoliaSearch( headerElement ).init() )
+		);
+	}
+
+	/**
+	 * Initializes the algolia search component.
+	 */
+	async init() {
+		await injectScript( DOCSEARCH_JS_URL, {
+			attributes: {
+				crossorigin: 'anonymous'
+			}
+		} );
+
+		const { boost, filters } = this;
+		const { slug, tags } = filters;
+
+		window.docsearch( {
+			container: this.elements.wrapper,
+			...this.config,
+
+			// `transformItems` do not support sorting whole set of results at once.
+			// It's called individually for each result, or the result group.
+			// It's problematic when we want to reorder whole groups of results, e.g. move API below Features.
+			transformSearchClient: client => {
+				const originalSearch = client.search.bind( client );
+
+				client.search = async ( options, ...rest ) => {
+					const { results: [ firstResult ] } = await originalSearch( options, ...rest );
+					const mappedResults = pipe(
+						filterByTags( { slug, tags } ),
+						boostByTags( boost.tags )
+					)( firstResult.hits );
+
+					return {
+						results: [
+							{
+								...firstResult,
+								hits: mappedResults,
+								hitsPerPage: mappedResults.length,
+								nbHits: mappedResults.length
+							}
+						]
+					};
+				};
+
+				return client;
+			}
+		} );
+	}
+}
+
+/**
+ * Crates filters for Algolia that allow to filter out results from different projects.
+ * Algolia shares the same index for all projects, so we need to filter results
+ */
+function filterByTags( { slug, tags } ) {
+	return hits => hits.filter(
+		hit =>
+			( !slug || hit.tags.includes( slug ) ) &&
+			( !tags || hit.tags.some( tag => tags.includes( tag ) ) )
+	);
+}
+
+/**
+ * Boosts Algolia search results by tags. The `other` will be placed at the end of the results.
+ */
+function boostByTags( tags ) {
+	if ( !tags?.length ) {
+		return identity;
+	}
+
+	return pipe(
+		groupByTag,
+		sortObjectKeysByIndices( tags ),
+		Object.values,
+		array => array.flat()
+	);
+}
+
+/**
+ * Groups Algolia search results by tags.
+ */
+function groupByTag( hits ) {
+	return hits.reduce( ( acc, hit ) => {
+		if ( hit.tags.length === 0 ) {
+			( acc.other ??= [] ).push( hit );
+		} else {
+			hit.tags.forEach( tag => {
+				( acc[ tag ] ??= [] ).push( hit );
+			} );
+		}
+
+		return acc;
+	}, Object.create( {} ) );
+}
+
+/**
+ * Sorts object keys by the order defined in the `keysOrder` array.
+ * If a key is not present in `keysOrder`, it will be placed at the end.
+ */
+function sortObjectKeysByIndices( keysOrder ) {
+	return obj => {
+		const sortedKeys = Object.keys( obj ).sort( ( a, b ) => {
+			const indexA = keysOrder.indexOf( a );
+			const indexB = keysOrder.indexOf( b );
+
+			if ( indexA === -1 ) {
+				return 1;
+			}
+
+			if ( indexB === -1 ) {
+				return -1;
+			}
+
+			if ( indexA === -1 && indexB === -1 ) {
+				return -2;
+			}
+
+			return indexA - indexB;
+		} );
+
+		return sortedKeys.reduce( ( acc, key ) => {
+			acc[ key ] = obj[ key ];
+			return acc;
+		}, Object.create( {} ) );
+	};
+}

package/themes/umberto/src/gloria/js/modules/api-filter.js

@@ -0,0 +1,189 @@
+/**
+ * @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';
+
+const API_FILTER_LOCAL_STORAGE_KEY = 'ApiFilterState';
+
+export class ApiFilter extends BaseComponent {
+	/**
+	 * Creates an aPI filter management component.
+	 *
+	 * @param element - The filter dropdown element.
+	 */
+	constructor( element ) {
+		super( {
+			apiFilterState: JSON.parse( localStorage.getItem( API_FILTER_LOCAL_STORAGE_KEY ) ) || {},
+			activeFilters: Array.from( element.querySelectorAll( '.js-api-filter-checkbox input:checked' ) ).map( input => input.value ),
+			filterItems: Array.from( document.querySelectorAll( '.js-api-filter-item' ) ).map( item => {
+				return {
+					element: item,
+					tags: Object.keys( Object.assign( {}, item.dataset ) )
+				};
+			} ),
+			filterTocItems: Array.from( document.querySelectorAll( '.js-api-toc-filter-item' ) ).map( item => {
+				return {
+					element: item,
+					tags: Object.keys( Object.assign( {}, item.dataset ) )
+				};
+			} )
+		} );
+
+		this.elements = {
+			filterDropdown: element,
+			filterInputs: element.querySelectorAll( '.js-api-filter-checkbox input' ),
+			filterLists: document.querySelectorAll( '.js-api-filter-list' ),
+			tocFilterLists: document.querySelectorAll( '.js-api-toc-list' )
+		};
+	}
+
+	/**
+	 * Initializes navigation tree component on the page.
+	 */
+	static attach() {
+		const filter = document.querySelector( '.js-api-filter' );
+
+		if ( !filter ) {
+			return;
+		}
+
+		new ApiFilter( filter ).init();
+	}
+
+	/**
+	 * Initializes the navigation tree component with event listeners.
+	 */
+	init() {
+		const { filterInputs } = this.elements;
+
+		filterInputs.forEach( checkbox => {
+			checkbox.addEventListener( 'change', () => {
+				const isChecked = checkbox.checked;
+				const filterType = checkbox.value;
+
+				this.setState( {
+					activeFilters: this.state.activeFilters.includes( filterType ) ?
+						this.state.activeFilters.filter( el => el !== filterType ) :
+						[ ...this.state.activeFilters, filterType ]
+				} );
+
+				this.saveApiFilterState( filterType, isChecked );
+				this.filterItems();
+				this.checkIfAllItemsAreHidden();
+			} );
+		} );
+
+		this.setInitialApiFilterState();
+		this.initialApplyApiFilterState();
+		this.filterItems();
+		this.checkIfAllItemsAreHidden();
+		this.render();
+	}
+
+	render() {
+		// No specific rendering logic for the navigation tree component.
+	}
+
+	/**
+	 * Filters the items based on the active filters.
+	 */
+	filterItems() {
+		const { filterItems, filterTocItems, activeFilters } = this.state;
+		const { filterInputs } = this.elements;
+
+		// Get all possible tags from checkboxes (all available filters)
+		const allFilterTags = Array.from( filterInputs ).map( input => input.value );
+
+		[ ...filterItems, ...filterTocItems ].forEach( item => {
+			// Check if the element has any tag that is on the filter list but is not active
+			const hasInactiveTag = item.tags.some( tag => allFilterTags.includes( tag ) && !activeFilters.includes( tag ) );
+
+			if ( hasInactiveTag ) {
+				item.element.classList.add( 'is-hidden' );
+			} else {
+				item.element.classList.remove( 'is-hidden' );
+			}
+		} );
+	}
+
+	/**
+	 * Checks if all items in the filter lists are hidden and updates the list state accordingly.
+	 */
+	checkIfAllItemsAreHidden() {
+		const { filterLists, tocFilterLists } = this.elements;
+
+		filterLists.forEach( list => {
+			const isEmpty = list.querySelectorAll( '.js-api-filter-item:not(.is-hidden)' ).length === 0;
+
+			if ( isEmpty ) {
+				list.classList.add( 'is-empty' );
+			} else {
+				list.classList.remove( 'is-empty' );
+			}
+		} );
+
+		tocFilterLists.forEach( list => {
+			const isEmpty = list.querySelectorAll( '.js-api-toc-filter-item:not(.is-hidden)' ).length === 0;
+
+			if ( isEmpty ) {
+				list.classList.add( 'is-empty' );
+			} else {
+				list.classList.remove( 'is-empty' );
+			}
+		} );
+	}
+
+	/**
+	 * Sets the initial state of the API filter into local storage when there is no set yet.
+	 */
+	setInitialApiFilterState() {
+		const { apiFilterState } = this.state;
+		const { filterDropdown } = this.elements;
+
+		if ( Object.keys( apiFilterState ).length === 0 ) {
+			Array.from( filterDropdown.querySelectorAll( '.js-api-filter-checkbox input' ) ).forEach( input => {
+				const isChecked = input.checked;
+				const filterType = input.value;
+
+				this.saveApiFilterState( filterType, isChecked );
+			} );
+		}
+
+		this.setState( {
+			apiFilterState: JSON.parse( localStorage.getItem( API_FILTER_LOCAL_STORAGE_KEY ) ) || {},
+			activeFilters: Object.keys( this.state.apiFilterState ).filter( key => this.state.apiFilterState[ key ] )
+		} );
+	}
+
+	/**
+	 * Applies the initial API filter state to the checkboxes in the filter dropdown.
+	 */
+	initialApplyApiFilterState() {
+		const { apiFilterState } = this.state;
+		const { filterDropdown } = this.elements;
+
+		Array.from( filterDropdown.querySelectorAll( '.js-api-filter-checkbox input' ) ).forEach( input => {
+			const isChecked = input.checked;
+			const filterType = input.value;
+
+			input.checked = apiFilterState[ filterType ] !== undefined ? apiFilterState[ filterType ] : isChecked;
+		} );
+
+		// this.dispatchInitialFolderStateDoneEvent();
+	}
+
+	/**
+	 * Saves the state of the API filter checkbox in local storage.
+	 *
+	 * @param id - The ID of the filter checkbox.
+	 * @param state - The state of the API filter (true for show, false for hide).
+	 */
+	saveApiFilterState( id, state ) {
+		const { apiFilterState } = this.state;
+
+		apiFilterState[ id ] = state;
+		window.localStorage.setItem( API_FILTER_LOCAL_STORAGE_KEY, JSON.stringify( apiFilterState ) );
+	}
+}