umberto 7.0.2 → 8.0.0

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

@@ -0,0 +1,64 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/**
+ * A simplified utility for conditionally joining class names together.
+ * Similar to clsx/classnames that accepts arrays and objects for convenience.
+ *
+ * @param args - Class names, arrays, objects, or conditional expressions
+ * @returns Filtered and joined class names
+ *
+ * @example
+ * // Basic usage with array
+ * cx(['foo', 'bar']); // => 'foo bar'
+ *
+ * @example
+ * // Multiple arguments
+ * cx('foo', 'bar'); // => 'foo bar'
+ *
+ * @example
+ * // Filtering out falsy values
+ * cx(['foo', null, 'bar', undefined, '', false, 0]); // => 'foo bar'
+ *
+ * @example
+ * // With conditional expressions
+ * cx(['base', isActive && 'active', hasError && 'error']); // => returns 'base active' or 'base error' depending on conditions
+ *
+ * @example
+ * // Object syntax
+ * cx({ foo: true, bar: false, baz: isCondition }); // => 'foo baz' if isCondition is true, otherwise just 'foo'
+ *
+ * @example
+ * // Mixed arguments
+ * cx('base', { active: isActive, disabled: isDisabled }, ['extra', condition && 'conditional']); // => combines all formats
+ */
+export function cx( ...args ) {
+	return args
+		.flatMap( arg => {
+			if ( !arg ) {
+				return [];
+			}
+
+			if ( typeof arg === 'string' ) {
+				return arg;
+			}
+
+			if ( Array.isArray( arg ) ) {
+				return cx( ...arg );
+			}
+
+			if ( typeof arg === 'object' ) {
+				return Object
+					.entries( arg )
+					.filter( ( [ , value ] ) => Boolean( value ) )
+					.map( ( [ key ] ) => key );
+			}
+
+			return [];
+		} )
+		.filter( Boolean )
+		.join( ' ' )
+		.trim();
+}

package/themes/umberto/src/gloria/js/helpers/copy-to-clipboard.js

@@ -0,0 +1,19 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/**
+ * Copies the provided text to clipboard.
+ *
+ * @param text - The text to copy to clipboard
+ * @returns Promise that resolves when text is copied or rejects on error
+ */
+export function copyToClipboard( text ) {
+	// Use the more modern navigator.clipboard API if available
+	if ( navigator.clipboard && navigator.clipboard.writeText ) {
+		return navigator.clipboard.writeText( text );
+	}
+
+	throw new Error( 'Clipboard API is not supported in this browser.' );
+}

package/themes/umberto/src/gloria/js/helpers/create-anchor-positioning-watcher.js

@@ -0,0 +1,46 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+import { getAllScrollableParents } from './get-all-scrollable-parents';
+
+/**
+ * Sets up positioning event listeners for an element.
+ *
+ * @param config - Configuration object
+ * @param config.element - The element to watch for positioning
+ * @param config.handler - The handler function to call when positioning events occur
+ * @returns A function that cleans up all event listeners when called
+ */
+export function createAnchorPositioningWatcher( { element, handler } ) {
+	const cleanupCallbacks = [];
+
+	// Get all scrollable parents of the element
+	const scrollableParents = getAllScrollableParents( element, true );
+
+	// Add event listeners to window for resize
+	window.addEventListener( 'resize', handler, { passive: true } );
+	cleanupCallbacks.push( () => {
+		window.removeEventListener( 'resize', handler );
+	} );
+
+	// Add wheel and scroll event listeners to all scrollable parents
+	for ( const parent of scrollableParents ) {
+		parent.addEventListener( 'wheel', handler, { passive: true } );
+		parent.addEventListener( 'scroll', handler, { passive: true } );
+
+		// Store cleanup callbacks
+		cleanupCallbacks.push( () => {
+			parent.removeEventListener( 'wheel', handler );
+			parent.removeEventListener( 'scroll', handler );
+		} );
+	}
+
+	// Return a single function that cleans up all event listeners
+	return () => {
+		for ( const cleanup of cleanupCallbacks ) {
+			cleanup();
+		}
+	};
+}

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

@@ -0,0 +1,88 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/**
+ * Creates a cleanup registry that manages a collection of cleanup callbacks.
+ *
+ * @returns An object with methods to register and destroy callbacks
+ */
+export function createCleanupRegistry() {
+	const callbacks = [];
+
+	return {
+		/**
+		 * Registers a cleanup callback and returns it.
+		 *
+		 * @param callback - The cleanup callback to register
+		 * @returns The registered callback
+		 */
+		register( callback ) {
+			if ( typeof callback === 'function' ) {
+				callbacks.push( callback );
+			}
+
+			return callback;
+		},
+
+		/**
+		 * Executes all registered callbacks and clears the registry.
+		 */
+		destroy() {
+			while ( callbacks.length ) {
+				const callback = callbacks.pop();
+				if ( typeof callback === 'function' ) {
+					callback();
+				}
+			}
+		},
+
+		/**
+		 * Attaches an event listener to an element and registers its cleanup.
+		 *
+		 * @param element - DOM element to attach the event to
+		 * @param type - Event type (e.g., 'click', 'focus')
+		 * @param handler - Event handler function
+		 * @param [options] - Optional addEventListener options
+		 * @returns The handler function for reference
+		 */
+		addEventListener( element, type, handler, options ) {
+			if ( !element || !type || typeof handler !== 'function' ) {
+				console.warn( 'Invalid parameters provided to addEventListener' );
+				return handler;
+			}
+
+			element.addEventListener( type, handler, options );
+
+			this.register( () => {
+				element.removeEventListener( type, handler, options );
+			} );
+
+			return handler;
+		},
+
+		/**
+		 * Attaches multiple event listeners to an element and registers their cleanup.
+		 *
+		 * @param element - DOM element to attach the events to
+		 * @param events - Map of event types to handler functions
+		 * @param [options] - Optional addEventListener options
+		 * @returns The provided element for chaining
+		 */
+		addEventListeners( element, events, options ) {
+			if ( !element || !events ) {
+				console.warn( 'Invalid parameters provided to addEventListeners' );
+				return element;
+			}
+
+			for ( const [ type, handler ] of Object.entries( events ) ) {
+				if ( typeof handler === 'function' ) {
+					this.addEventListener( element, type, handler, options );
+				}
+			}
+
+			return element;
+		}
+	};
+}

package/themes/umberto/src/gloria/js/helpers/create-hover-manager.js

@@ -0,0 +1,93 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/**
+ * Creates a hover manager that tracks hover state across multiple elements.
+ *
+ * @param options - The options for the hover manager.
+ * @param options.elements - The elements to track hover state for.
+ * @param options.onEnter - Callback function to call when an element is hovered.
+ * @param options.onLeave - Callback function to call when no elements are hovered.
+ * @param [options.debounceDelay=0] - Delay in milliseconds before triggering onEnter callback.
+ * @returns An object with destroy method to clean up event listeners
+ */
+export function createHoverManager( { elements, onEnter, onLeave, debounceDelay = 0 } ) {
+	const hoveredElements = new Set();
+	let leaveTimeoutId = null;
+	let enterTimeoutId = null;
+	const listenerPairs = [];
+
+	function handleMouseEnter( element ) {
+		clearTimeout( leaveTimeoutId );
+		leaveTimeoutId = null;
+
+		const isNewlyHovered = !hoveredElements.has( element );
+		hoveredElements.add( element );
+
+		if ( isNewlyHovered && onEnter ) {
+			clearTimeout( enterTimeoutId );
+
+			if ( debounceDelay > 0 ) {
+				// Use debounced enter if delay is specified
+				enterTimeoutId = setTimeout( () => {
+					onEnter?.( element );
+				}, debounceDelay );
+			} else {
+				// Call immediately if no debounce
+				onEnter?.( element );
+			}
+		}
+	}
+
+	function handleMouseLeave( element ) {
+		hoveredElements.delete( element );
+
+		// Clear any existing timeouts
+		clearTimeout( leaveTimeoutId );
+		clearTimeout( enterTimeoutId );
+
+		leaveTimeoutId = null;
+		enterTimeoutId = null;
+
+		if ( hoveredElements.size === 0 ) {
+			leaveTimeoutId = setTimeout( () => {
+				// Double check size, in case an element was entered again quickly
+				if ( hoveredElements.size === 0 && onLeave ) {
+					onLeave?.();
+				}
+			}, 50 );
+		}
+	}
+
+	// Attach event listeners
+	elements.forEach( element => {
+		const enterHandler = () => handleMouseEnter( element );
+		const leaveHandler = () => handleMouseLeave( element );
+
+		element.addEventListener( 'mouseenter', enterHandler );
+		element.addEventListener( 'mouseleave', leaveHandler );
+		element.addEventListener( 'focus', enterHandler );
+		element.addEventListener( 'blur', leaveHandler );
+
+		listenerPairs.push(
+			{ element, type: 'mouseenter', handler: enterHandler },
+			{ element, type: 'mouseleave', handler: leaveHandler },
+			{ element, type: 'focus', handler: enterHandler },
+			{ element, type: 'blur', handler: leaveHandler }
+		);
+	} );
+
+	// Return an object with a destroy method
+	return {
+		destroy() {
+			clearTimeout( leaveTimeoutId );
+			clearTimeout( enterTimeoutId );
+			listenerPairs.forEach( pair => {
+				pair.element.removeEventListener( pair.type, pair.handler );
+			} );
+			hoveredElements.clear();
+		}
+	};
+}

package/themes/umberto/src/gloria/js/helpers/create-keyboard-blur-watcher.js

@@ -0,0 +1,90 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/**
+ * Creates a watcher that detects when all elements lose focus via keyboard navigation.
+ * It differentiates between blur caused by mouse clicks and keyboard navigation.
+ * Additionally monitors keyboard events to detect navigation away from elements.
+ * Only triggers when focus moves outside ALL of the monitored elements.
+ *
+ * @param config - Configuration object.
+ * @param config.elements - Element or array of elements to monitor for keyboard-based blur.
+ * @param config.callback - Function to call when keyboard blur occurs outside of all elements.
+ * @param [config.checkDelay=50] - Delay in ms to check focus after keyboard event.
+ * @returns Cleanup function to remove the listeners.
+ */
+export function createKeyboardBlurWatcher( { elements, callback, checkDelay = 50 } ) {
+	let isMouseDown = false;
+
+	// Convert single element to array for consistent handling
+	if ( !Array.isArray( elements ) ) {
+		elements = [ elements ];
+	}
+
+	// Track if mouse is being used
+	const handleMouseDown = () => {
+		isMouseDown = true;
+	};
+
+	const handleMouseUp = () => {
+		isMouseDown = false;
+	};
+
+	// Check if current focus is inside any of our elements
+	const isFocusWithinElements = () => {
+		return elements.some( element =>
+			element === document.activeElement || element.contains( document.activeElement )
+		);
+	};
+
+	// Function to check focus state and call callback if needed
+	const checkFocusState = event => {
+		if ( !isFocusWithinElements() ) {
+			callback( event );
+		}
+	};
+
+	// When any element loses focus
+	const handleBlur = event => {
+		if ( isMouseDown ) {
+			return; // Ignore blur from mouse interactions
+		}
+
+		// Use setTimeout to allow the next element to receive focus first
+		setTimeout( () => checkFocusState( event ), 0 );
+	};
+
+	// Handle keyboard navigation that might move focus away
+	const handleKeyDown = event => {
+		// Primary focus navigation keys
+		const navigationKeys = [ 'Tab', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Escape' ];
+
+		if ( navigationKeys.includes( event.key ) ) {
+			// Wait a short time after key press to check where focus landed
+			setTimeout( () => checkFocusState( event ), checkDelay );
+		}
+	};
+
+	// Add event listeners
+	document.addEventListener( 'mousedown', handleMouseDown );
+	document.addEventListener( 'mouseup', handleMouseUp );
+
+	// Attach blur and keydown listeners to each element
+	elements.forEach( element => {
+		element.addEventListener( 'blur', handleBlur );
+		element.addEventListener( 'keydown', handleKeyDown );
+	} );
+
+	// Return cleanup function
+	return () => {
+		document.removeEventListener( 'mousedown', handleMouseDown );
+		document.removeEventListener( 'mouseup', handleMouseUp );
+
+		elements.forEach( element => {
+			element.removeEventListener( 'blur', handleBlur );
+			element.removeEventListener( 'keydown', handleKeyDown );
+		} );
+	};
+}

package/themes/umberto/src/gloria/js/helpers/create-keyboard-focus-cycler.js

@@ -0,0 +1,251 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+import { clamp } from './clamp';
+import { isFocusable } from './is-focusable';
+import { wrapAround } from './wrap-around';
+
+/**
+ * Creates a keyboard-based focus cycler for a list of elements.
+ *
+ * @param config - Configuration object
+ * @param config.items - Elements to cycle through
+ * @param config.keyMap - Key mappings for navigation
+ * @param [config.onFocusEnter] - Callback when focus enters an element (item, index) => {}
+ * @param [config.onFocusLeave] - Callback when focus leaves an element (item, index) => {}
+ * @param [config.focusElements=true] - Whether to automatically focus DOM elements
+ * @param [config.blurCheckDelay=15] - Delay in ms to check focus after blur events
+ * @returns Control object with activate, deactivate methods and unmount function
+ */
+export function createKeyboardFocusCycler( config ) {
+	return new KeyboardFocusCycler( config );
+}
+
+/**
+ * Class that handles keyboard-based focus cycling for a list of elements.
+ */
+class KeyboardFocusCycler {
+	/**
+	 * Creates a new instance of KeyboardFocusCycler.
+	 */
+	constructor( {
+		items,
+		keyMap = getVerticalKeysMap(),
+		onFocusEnter = () => {},
+		onFocusLeave = () => {},
+		focusElements = true,
+		blurCheckDelay = 15
+	} ) {
+		this.items = items;
+		this.keyMap = keyMap;
+		this.onFocusEnter = onFocusEnter;
+		this.onFocusLeave = onFocusLeave;
+		this.focusElements = focusElements;
+		this.blurCheckDelay = blurCheckDelay;
+
+		this.currentIndex = -1;
+		this.isActive = false;
+		this.blurTimeout = null;
+
+		// Bind methods to preserve 'this' context
+		this._handleKeyDown = this._handleKeyDown.bind( this );
+		this._handleItemFocus = this._handleItemFocus.bind( this );
+		this._handleItemBlur = this._handleItemBlur.bind( this );
+
+		// Attach event listeners
+		window.addEventListener( 'keydown', this._handleKeyDown );
+		this.items.forEach( item => {
+			if ( isFocusable( item ) ) {
+				item.addEventListener( 'focus', this._handleItemFocus );
+				item.addEventListener( 'blur', this._handleItemBlur );
+			}
+		} );
+	}
+
+	/**
+	 * Activate focus cycling starting at specified index
+	 *
+	 * @param [startIndex=0] - Index to start focus at
+	 */
+	activate( startIndex = 0 ) {
+		const clampedIndex = clamp( 0, this.items.length - 1, startIndex );
+
+		this.isActive = true;
+		this._changeFocus( clampedIndex );
+	}
+
+	/**
+	 * Activate focus cycling starting at the first item
+	 */
+	activateFirst() {
+		this.activate( 0 );
+	}
+
+	/**
+	 * Activate focus cycling starting at the last item
+	 */
+	activateLast() {
+		this.activate( this.items.length - 1 );
+	}
+
+	/**
+	 * Deactivate focus cycling
+	 */
+	deactivate() {
+		if ( this.currentIndex !== -1 ) {
+			this.onFocusLeave( this.items[ this.currentIndex ], this.currentIndex );
+		}
+
+		this.isActive = false;
+		this.currentIndex = -1;
+	}
+
+	/**
+	 * Remove all event listeners and clean up
+	 */
+	unmount() {
+		window.removeEventListener( 'keydown', this._handleKeyDown );
+
+		// Remove focus and blur listeners
+		this.items.forEach( item => {
+			if ( isFocusable( item ) ) {
+				item.removeEventListener( 'focus', this._handleItemFocus );
+				item.removeEventListener( 'blur', this._handleItemBlur );
+			}
+		} );
+
+		clearTimeout( this.blurTimeout );
+		this.deactivate();
+	}
+
+	/**
+	 * Change focus from one element to another
+	 * @param newIndex - Index of the element to focus
+	 * @private
+	 */
+	_changeFocus( newIndex ) {
+		const previousIndex = this.currentIndex;
+
+		// Call callbacks when focus changes
+		if ( previousIndex !== -1 ) {
+			this.onFocusLeave( this.items[ previousIndex ], previousIndex );
+		}
+
+		this.currentIndex = newIndex;
+		this.onFocusEnter( this.items[ this.currentIndex ], this.currentIndex );
+
+		// Focus the element if it's focusable and option is enabled
+		if ( this.focusElements && isFocusable( this.items[ this.currentIndex ] ) ) {
+			this.items[ this.currentIndex ].focus();
+		}
+	}
+
+	/**
+	 * Check if any item has focus
+	 * @returns True if any item has focus
+	 * @private
+	 */
+	_hasAnyItemFocus() {
+		return this.items.some( item => document.activeElement === item );
+	}
+
+	/**
+	 * Handle keyboard navigation
+	 * @param event - Keyboard event
+	 * @private
+	 */
+	_handleKeyDown( event ) {
+		if ( !this.isActive ) {
+			return;
+		}
+
+		// Destructure key mappings.
+		const { next, previous, first, last } = this.keyMap;
+		const pressedKey = event.key;
+
+		// Check if the pressed key is in our mapping.
+		if (
+			!next?.includes( pressedKey ) &&
+			!previous?.includes( pressedKey ) &&
+			!first?.includes( pressedKey ) &&
+			!last?.includes( pressedKey )
+		) {
+			return;
+		}
+
+		event.preventDefault();
+
+		let newIndex = this.currentIndex;
+
+		// Determine the new index based on key pressed.
+		if ( next?.includes( pressedKey ) ) {
+			newIndex = wrapAround( 0, this.items.length - 1, this.currentIndex + 1 );
+		} else if ( previous?.includes( pressedKey ) ) {
+			newIndex = wrapAround( 0, this.items.length - 1, this.currentIndex - 1 );
+		} else if ( first?.includes( pressedKey ) ) {
+			newIndex = 0;
+		} else if ( last?.includes( pressedKey ) ) {
+			newIndex = this.items.length - 1;
+		}
+
+		this._changeFocus( newIndex );
+	}
+
+	/**
+	 * Handle item focus
+	 * @param event - Focus event
+	 * @private
+	 */
+	_handleItemFocus( event ) {
+		clearTimeout( this.blurTimeout );
+
+		this.isActive = true;
+
+		// Find the index of the focused item
+		const index = this.items.indexOf( event.target );
+		if ( index !== -1 && index !== this.currentIndex ) {
+			this._changeFocus( index );
+		}
+	}
+
+	/**
+	 * Handle item blur
+	 * @private
+	 */
+	_handleItemBlur() {
+		// Clear any existing timeout
+		clearTimeout( this.blurTimeout );
+
+		// Set a new timeout to check focus after a small delay
+		this.blurTimeout = setTimeout( () => {
+			if ( !this._hasAnyItemFocus() ) {
+				this.isActive = false;
+
+				if ( this.currentIndex !== -1 ) {
+					this.onFocusLeave( this.items[ this.currentIndex ], this.currentIndex );
+					this.currentIndex = -1;
+				}
+			}
+		}, this.blurCheckDelay );
+	}
+}
+
+export function getVerticalKeysMap() {
+	return {
+		next: [ 'ArrowDown', 'Down' ],
+		previous: [ 'ArrowUp', 'Up' ],
+		first: [ 'Home' ],
+		last: [ 'End' ]
+	};
+}
+
+export function getHorizontalKeysMap() {
+	return {
+		next: [ 'ArrowRight', 'Right' ],
+		previous: [ 'ArrowLeft', 'Left' ],
+		first: [ 'Home' ],
+		last: [ 'End' ]
+	};
+}

package/themes/umberto/src/gloria/js/helpers/create-mutation-observer.js

@@ -0,0 +1,49 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/**
+ * Creates a mutation observer to detect content changes in the specified element.
+ *
+ * @param config - Configuration object
+ * @param config.element - The element to observe for changes
+ * @param config.callback - The function to call when mutations occur
+ * @param [config.attributeFilter] - Specific attributes to watch (optional)
+ * @param [config.options] - MutationObserver options (defaults to observing all changes)
+ * @returns A function that disconnects the observer when called
+ */
+export function createMutationObserver( { element, callback, attributeFilter, options = {} } ) {
+	// Create default options if none provided
+	const observerOptions = {
+		childList: options.childList ?? true,
+		characterData: options.characterData ?? true,
+		subtree: options.subtree ?? true,
+		attributes: options.attributes ?? true,
+		attributeFilter
+	};
+
+	// Create a new mutation observer
+	const mutationObserver = new MutationObserver( mutations => {
+		// Check if any mutations affected the content
+		const contentChanged = mutations.some( mutation =>
+			mutation.type === 'characterData' ||
+			mutation.type === 'childList' ||
+				( mutation.type === 'attributes' &&
+				( !attributeFilter || attributeFilter.includes( mutation.attributeName ) ) )
+		);
+
+		// If content changed, call the callback with mutation information
+		if ( contentChanged ) {
+			callback( mutations );
+		}
+	} );
+
+	// Start observing the element
+	mutationObserver.observe( element, observerOptions );
+
+	// Return a function to disconnect the observer
+	return () => {
+		mutationObserver.disconnect();
+	};
+}