@wordpress/block-library 9.40.2-next.v.202602271551.0 → 9.41.0

package/src/utils/test/waveform-utils.js

@@ -0,0 +1,328 @@
+/**
+ * @jest-environment jsdom
+ */
+
+/**
+ * External dependencies
+ */
+import '@testing-library/jest-dom';
+
+/**
+ * Internal dependencies
+ */
+import {
+	createWaveformContainer,
+	styleSvgIcons,
+	setupPlayButtonAccessibility,
+	logPlayError,
+} from '../waveform-utils';
+
+// Base player data used across tests
+const basePlayerData = {
+	url: 'https://example.com/song.mp3',
+	waveformColor: 'rgba(0, 0, 0, 0.3)',
+	progressColor: 'rgba(0, 0, 0, 0.6)',
+	buttonColor: '#000000',
+};
+
+describe( 'Waveform utilities', () => {
+	describe( 'createWaveformContainer', () => {
+		it( 'should create a container with required data attributes', () => {
+			const container = createWaveformContainer( basePlayerData );
+
+			expect( container.tagName ).toBe( 'DIV' );
+			expect( container ).toHaveAttribute( 'data-waveform-player', '' );
+			expect( container ).toHaveAttribute(
+				'data-url',
+				'https://example.com/song.mp3'
+			);
+			expect( container ).toHaveAttribute( 'data-height', '100' );
+			expect( container ).toHaveAttribute(
+				'data-waveform-style',
+				'bars'
+			);
+			expect( container ).toHaveAttribute(
+				'data-waveform-color',
+				'rgba(0, 0, 0, 0.3)'
+			);
+			expect( container ).toHaveAttribute(
+				'data-progress-color',
+				'rgba(0, 0, 0, 0.6)'
+			);
+			expect( container ).toHaveAttribute(
+				'data-button-color',
+				'#000000'
+			);
+		} );
+
+		it( 'should set optional attributes when provided', () => {
+			const container = createWaveformContainer( {
+				...basePlayerData,
+				title: 'My Song',
+				artist: 'The Artist',
+				artwork: 'https://example.com/cover.jpg',
+			} );
+
+			expect( container ).toHaveAttribute( 'data-title', 'My Song' );
+			expect( container ).toHaveAttribute(
+				'data-subtitle',
+				'The Artist'
+			);
+			expect( container ).toHaveAttribute(
+				'data-artwork',
+				'https://example.com/cover.jpg'
+			);
+		} );
+
+		it( 'should not set optional attributes when not provided', () => {
+			const container = createWaveformContainer( basePlayerData );
+
+			expect( container ).not.toHaveAttribute( 'data-title' );
+			expect( container ).not.toHaveAttribute( 'data-subtitle' );
+			expect( container ).not.toHaveAttribute( 'data-artwork' );
+		} );
+
+		it( 'should use custom height when provided', () => {
+			const container = createWaveformContainer( {
+				...basePlayerData,
+				height: 150,
+			} );
+
+			expect( container ).toHaveAttribute( 'data-height', '150' );
+		} );
+	} );
+
+	describe( 'styleSvgIcons', () => {
+		it( 'should set white fill for dark button colors', () => {
+			const container = document.createElement( 'div' );
+			const svg = document.createElementNS(
+				'http://www.w3.org/2000/svg',
+				'svg'
+			);
+			const path = document.createElementNS(
+				'http://www.w3.org/2000/svg',
+				'path'
+			);
+			svg.appendChild( path );
+			container.appendChild( svg );
+
+			styleSvgIcons( container, '#000000' );
+
+			expect( path ).toHaveStyle( { fill: '#ffffff' } );
+		} );
+
+		it( 'should set black fill for light button colors', () => {
+			const container = document.createElement( 'div' );
+			const svg = document.createElementNS(
+				'http://www.w3.org/2000/svg',
+				'svg'
+			);
+			const path = document.createElementNS(
+				'http://www.w3.org/2000/svg',
+				'path'
+			);
+			svg.appendChild( path );
+			container.appendChild( svg );
+
+			styleSvgIcons( container, '#ffffff' );
+
+			expect( path ).toHaveStyle( { fill: '#000000' } );
+		} );
+
+		it( 'should style multiple SVG paths', () => {
+			const container = document.createElement( 'div' );
+			const svg = document.createElementNS(
+				'http://www.w3.org/2000/svg',
+				'svg'
+			);
+			const path1 = document.createElementNS(
+				'http://www.w3.org/2000/svg',
+				'path'
+			);
+			const path2 = document.createElementNS(
+				'http://www.w3.org/2000/svg',
+				'path'
+			);
+			svg.appendChild( path1 );
+			svg.appendChild( path2 );
+			container.appendChild( svg );
+
+			styleSvgIcons( container, '#000000' );
+
+			expect( path1 ).toHaveStyle( { fill: '#ffffff' } );
+			expect( path2 ).toHaveStyle( { fill: '#ffffff' } );
+		} );
+
+		it( 'should handle container with no SVG paths', () => {
+			const container = document.createElement( 'div' );
+
+			// Should not throw.
+			expect( () => {
+				styleSvgIcons( container, '#000000' );
+			} ).not.toThrow();
+		} );
+
+		it( 'should use white for dark colors', () => {
+			const container = document.createElement( 'div' );
+			const svg = document.createElementNS(
+				'http://www.w3.org/2000/svg',
+				'svg'
+			);
+			const path = document.createElementNS(
+				'http://www.w3.org/2000/svg',
+				'path'
+			);
+			svg.appendChild( path );
+			container.appendChild( svg );
+
+			// A dark blue color.
+			styleSvgIcons( container, '#000080' );
+
+			expect( path ).toHaveStyle( { fill: '#ffffff' } );
+		} );
+
+		it( 'should use black for mid-light colors', () => {
+			const container = document.createElement( 'div' );
+			const svg = document.createElementNS(
+				'http://www.w3.org/2000/svg',
+				'svg'
+			);
+			const path = document.createElementNS(
+				'http://www.w3.org/2000/svg',
+				'path'
+			);
+			svg.appendChild( path );
+			container.appendChild( svg );
+
+			// A light yellow color.
+			styleSvgIcons( container, '#ffff00' );
+
+			expect( path ).toHaveStyle( { fill: '#000000' } );
+		} );
+	} );
+
+	describe( 'setupPlayButtonAccessibility', () => {
+		it( 'should set aria-label to Play initially', () => {
+			const container = document.createElement( 'div' );
+			const playBtn = document.createElement( 'button' );
+			playBtn.className = 'waveform-btn';
+			container.appendChild( playBtn );
+
+			setupPlayButtonAccessibility( container );
+
+			expect( playBtn ).toHaveAttribute( 'aria-label', 'Play' );
+		} );
+
+		it( 'should change aria-label to Pause on play event', () => {
+			const container = document.createElement( 'div' );
+			const playBtn = document.createElement( 'button' );
+			playBtn.className = 'waveform-btn';
+			container.appendChild( playBtn );
+
+			setupPlayButtonAccessibility( container );
+			container.dispatchEvent( new CustomEvent( 'waveformplayer:play' ) );
+
+			expect( playBtn ).toHaveAttribute( 'aria-label', 'Pause' );
+		} );
+
+		it( 'should change aria-label back to Play on pause event', () => {
+			const container = document.createElement( 'div' );
+			const playBtn = document.createElement( 'button' );
+			playBtn.className = 'waveform-btn';
+			container.appendChild( playBtn );
+
+			setupPlayButtonAccessibility( container );
+			container.dispatchEvent( new CustomEvent( 'waveformplayer:play' ) );
+			container.dispatchEvent(
+				new CustomEvent( 'waveformplayer:pause' )
+			);
+
+			expect( playBtn ).toHaveAttribute( 'aria-label', 'Play' );
+		} );
+
+		it( 'should change aria-label back to Play on ended event', () => {
+			const container = document.createElement( 'div' );
+			const playBtn = document.createElement( 'button' );
+			playBtn.className = 'waveform-btn';
+			container.appendChild( playBtn );
+
+			setupPlayButtonAccessibility( container );
+			container.dispatchEvent( new CustomEvent( 'waveformplayer:play' ) );
+			container.dispatchEvent(
+				new CustomEvent( 'waveformplayer:ended' )
+			);
+
+			expect( playBtn ).toHaveAttribute( 'aria-label', 'Play' );
+		} );
+
+		it( 'should return cleanup function that removes listeners', () => {
+			const container = document.createElement( 'div' );
+			const playBtn = document.createElement( 'button' );
+			playBtn.className = 'waveform-btn';
+			container.appendChild( playBtn );
+
+			const cleanup = setupPlayButtonAccessibility( container );
+			cleanup();
+
+			// After cleanup, events should not change the label.
+			container.dispatchEvent( new CustomEvent( 'waveformplayer:play' ) );
+			expect( playBtn ).toHaveAttribute( 'aria-label', 'Play' );
+		} );
+
+		it( 'should do nothing when play button not found', () => {
+			const container = document.createElement( 'div' );
+
+			// Should not throw.
+			expect( () =>
+				setupPlayButtonAccessibility( container )
+			).not.toThrow();
+		} );
+	} );
+
+	describe( 'logPlayError', () => {
+		let consoleErrorSpy;
+
+		beforeEach( () => {
+			consoleErrorSpy = jest
+				.spyOn( console, 'error' )
+				.mockImplementation( () => {} );
+		} );
+
+		afterEach( () => {
+			consoleErrorSpy.mockRestore();
+		} );
+
+		it( 'should not log AbortError', () => {
+			const abortError = new DOMException( 'Aborted', 'AbortError' );
+
+			logPlayError( abortError );
+
+			expect( consoleErrorSpy ).not.toHaveBeenCalled();
+		} );
+
+		it( 'should log other errors', () => {
+			const otherError = new Error( 'Some other error' );
+
+			logPlayError( otherError );
+
+			expect( consoleErrorSpy ).toHaveBeenCalledWith(
+				'Playlist play error:',
+				otherError
+			);
+		} );
+
+		it( 'should log NotAllowedError', () => {
+			const notAllowedError = new DOMException(
+				'Not allowed',
+				'NotAllowedError'
+			);
+
+			logPlayError( notAllowedError );
+
+			expect( consoleErrorSpy ).toHaveBeenCalledWith(
+				'Playlist play error:',
+				notAllowedError
+			);
+		} );
+	} );
+} );

package/src/utils/waveform-player.js

@@ -0,0 +1,77 @@
+/**
+ * WordPress dependencies
+ */
+import { useRef } from '@wordpress/element';
+import { useRefEffect } from '@wordpress/compose';
+
+/**
+ * Internal dependencies
+ */
+import { initWaveformPlayer } from './waveform-utils';
+
+/**
+ * A reusable WaveformPlayer component for the block editor.
+ *
+ * Renders an audio waveform visualization with play/pause controls.
+ * Automatically inherits colors from the parent block's text color.
+ *
+ * @param {Object}   props         - Component props.
+ * @param {string}   props.src     - The audio file URL.
+ * @param {string}   props.title   - The track title.
+ * @param {string}   props.artist  - The artist name.
+ * @param {string}   props.image   - The artwork image URL.
+ * @param {Function} props.onEnded - Callback when the track finishes playing.
+ * @return {Element} The WaveformPlayer element.
+ */
+export function WaveformPlayer( { src, title, artist, image, onEnded } ) {
+	// Store onEnded in a ref so it doesn't need to be a useRefEffect dependency.
+	// The callback changes reference on every render (its dependency chain
+	// includes an unstable array), which would cause useRefEffect to destroy
+	// and recreate the entire player on every re-render, making it disappear
+	// during editor resizes.
+	const onEndedRef = useRef( onEnded );
+	onEndedRef.current = onEnded;
+
+	const ref = useRefEffect(
+		( element ) => {
+			if ( ! src ) {
+				return;
+			}
+
+			let cancelled = false;
+			let playerDestroy;
+
+			function init() {
+				if ( cancelled ) {
+					return;
+				}
+				const { destroy } = initWaveformPlayer( element, {
+					src,
+					title,
+					artist,
+					image,
+					onEnded: () => onEndedRef.current?.(),
+				} );
+				playerDestroy = destroy;
+			}
+
+			// Defer initialization so the element inherits the correct
+			// text color, which is used to derive waveform colors. In the
+			// editor iframe, theme styles (CSS custom properties) are
+			// injected dynamically, so getComputedStyle may return the
+			// default black on first render.
+			// Using a requestAnimationFrame loop isn't sufficient to solve the issue.
+			// TODO - find a better option than a setTimeout, so we're not relying on an arbitrary number.
+			const timeoutId = setTimeout( init, 100 );
+
+			return () => {
+				cancelled = true;
+				clearTimeout( timeoutId );
+				playerDestroy?.();
+			};
+		},
+		[ src, title, artist, image ]
+	);
+
+	return <div ref={ ref } className="wp-block-playlist__waveform-player" />;
+}

package/src/utils/waveform-utils.js

@@ -0,0 +1,232 @@
+/**
+ * Shared utilities for waveform audio player functionality.
+ * Used by both the WaveformPlayer component (editor) and view.js (frontend).
+ */
+
+/**
+ * External dependencies
+ */
+import { colord } from 'colord';
+import WaveformPlayerLib from '@arraypress/waveform-player';
+
+/**
+ * Configuration constants.
+ * Note: DEFAULT_WAVEFORM_HEIGHT should match $waveform-player-height in style.scss.
+ */
+const DEFAULT_WAVEFORM_HEIGHT = 100;
+
+/**
+ * Get computed style for an element, using ownerDocument for iframe compatibility.
+ *
+ * @param {Element} element - The element to get styles from.
+ * @return {CSSStyleDeclaration} The computed style.
+ */
+function getComputedStyle( element ) {
+	return element.ownerDocument.defaultView.getComputedStyle( element );
+}
+
+/**
+ * Get all colors needed for the waveform player based on the element's styles.
+ *
+ * @param {Element} element - The element to derive colors from.
+ * @return {Object} Object containing textColor, waveformColor, progressColor.
+ */
+export function getWaveformColors( element ) {
+	const textColor = getComputedStyle( element ).color;
+	const waveformColor = colord( textColor ).alpha( 0.3 ).toRgbString();
+	const progressColor = colord( textColor ).alpha( 0.6 ).toRgbString();
+
+	return { textColor, waveformColor, progressColor };
+}
+
+/**
+ * Create a waveform container element with the specified attributes.
+ *
+ * @param {Object} options               - The options for the container.
+ * @param {string} options.url           - The audio URL.
+ * @param {string} options.title         - The track title.
+ * @param {string} options.artist        - The track artist.
+ * @param {string} options.artwork       - The album artwork URL.
+ * @param {string} options.waveformColor - The waveform bar color.
+ * @param {string} options.progressColor - The progress indicator color.
+ * @param {string} options.buttonColor   - The play button color.
+ * @param {number} options.height        - The waveform height in pixels.
+ * @return {Element} The configured container element.
+ */
+export function createWaveformContainer( {
+	url,
+	title,
+	artist,
+	artwork,
+	waveformColor,
+	progressColor,
+	buttonColor,
+	height = DEFAULT_WAVEFORM_HEIGHT,
+} ) {
+	const container = document.createElement( 'div' );
+	container.setAttribute( 'data-waveform-player', '' );
+	container.setAttribute( 'data-url', url );
+	container.setAttribute( 'data-height', String( height ) );
+	container.setAttribute( 'data-waveform-style', 'bars' );
+	container.setAttribute( 'data-waveform-color', waveformColor );
+	container.setAttribute( 'data-progress-color', progressColor );
+	container.setAttribute( 'data-button-color', buttonColor );
+	container.setAttribute( 'data-text-color', buttonColor );
+	container.setAttribute( 'data-text-secondary-color', buttonColor );
+	if ( title ) {
+		container.setAttribute( 'data-title', title );
+	}
+	if ( artist ) {
+		container.setAttribute( 'data-subtitle', artist );
+	}
+	if ( artwork ) {
+		container.setAttribute( 'data-artwork', artwork );
+	}
+	return container;
+}
+
+/**
+ * Apply contrasting color to SVG icon paths for visibility.
+ * The icons should contrast with the button background (which uses textColor).
+ *
+ * @param {Element} container   - The waveform container element.
+ * @param {string}  buttonColor - The button background color (textColor).
+ */
+export function styleSvgIcons( container, buttonColor ) {
+	// Compute a contrasting color for the icons based on button brightness.
+	const isButtonDark = colord( buttonColor ).isDark();
+	const iconColor = isButtonDark ? '#ffffff' : '#000000';
+
+	const svgPaths = container.querySelectorAll( 'svg path' );
+	svgPaths.forEach( ( path ) => {
+		path.style.fill = iconColor;
+	} );
+}
+
+/**
+ * Set up play button accessibility: aria-label that toggles on play/pause.
+ *
+ * @param {Element} container    - The waveform container element.
+ * @param {Object}  labels       - Button labels.
+ * @param {string}  labels.play  - Label for the play state.
+ * @param {string}  labels.pause - Label for the pause state.
+ */
+export function setupPlayButtonAccessibility(
+	container,
+	{ play: playLabel = 'Play', pause: pauseLabel = 'Pause' } = {}
+) {
+	const playBtn = container.querySelector( '.waveform-btn' );
+	if ( ! playBtn ) {
+		return;
+	}
+
+	playBtn.setAttribute( 'aria-label', playLabel );
+
+	const onPlay = () => playBtn.setAttribute( 'aria-label', pauseLabel );
+	const onPause = () => playBtn.setAttribute( 'aria-label', playLabel );
+
+	container.addEventListener( 'waveformplayer:play', onPlay );
+	container.addEventListener( 'waveformplayer:pause', onPause );
+	container.addEventListener( 'waveformplayer:ended', onPause );
+
+	return () => {
+		container.removeEventListener( 'waveformplayer:play', onPlay );
+		container.removeEventListener( 'waveformplayer:pause', onPause );
+		container.removeEventListener( 'waveformplayer:ended', onPause );
+	};
+}
+
+/**
+ * Log play errors, filtering out expected AbortError.
+ *
+ * @param {Error} error - The error from play().
+ */
+export function logPlayError( error ) {
+	// The browser throws AbortError when a play() promise is interrupted
+	// by a subsequent pause() or a new audio source load (track change).
+	// This is normal during rapid user interaction and safe to ignore.
+	if ( error.name === 'AbortError' ) {
+		return;
+	}
+	// eslint-disable-next-line no-console
+	console.error( 'Playlist play error:', error );
+}
+
+/**
+ * Initialize a WaveformPlayer instance on an element.
+ *
+ * This is the shared core logic used by both the React component (editor)
+ * and the Interactivity API (frontend).
+ *
+ * @param {Element}  element          - The container element (must be in DOM).
+ * @param {Object}   options          - Configuration options.
+ * @param {string}   options.src      - The audio file URL.
+ * @param {string}   options.title    - The track title.
+ * @param {string}   options.artist   - The artist name.
+ * @param {string}   options.image    - The artwork image URL.
+ * @param {boolean}  options.autoPlay - Whether to auto-play when ready.
+ * @param {Function} options.onEnded  - Callback when track ends.
+ * @param {Object}   options.labels   - Translated button labels.
+ * @return {Object} Object with instance, container, and destroy function.
+ */
+export function initWaveformPlayer(
+	element,
+	{ src, title, artist, image, autoPlay, onEnded, labels }
+) {
+	// Get colors from computed styles.
+	const { textColor, waveformColor, progressColor } =
+		getWaveformColors( element );
+
+	// Create the waveform container.
+	const container = createWaveformContainer( {
+		url: src,
+		title,
+		artist,
+		artwork: image,
+		waveformColor,
+		progressColor,
+		buttonColor: textColor,
+	} );
+	element.appendChild( container );
+
+	// Initialize the WaveformPlayer library.
+	const instance = new WaveformPlayerLib( container );
+
+	// Set up event handlers.
+	let cleanupAccessibility;
+	const handlers = {
+		ready: () => {
+			styleSvgIcons( container, textColor );
+			cleanupAccessibility = setupPlayButtonAccessibility(
+				container,
+				labels
+			);
+			if ( autoPlay ) {
+				instance.play()?.catch( logPlayError );
+			}
+		},
+		ended: () => onEnded?.(),
+	};
+
+	container.addEventListener( 'waveformplayer:ready', handlers.ready );
+	container.addEventListener( 'waveformplayer:ended', handlers.ended );
+
+	// Return instance, container, and cleanup function.
+	return {
+		instance,
+		container,
+		destroy: () => {
+			cleanupAccessibility?.();
+			container.removeEventListener(
+				'waveformplayer:ready',
+				handlers.ready
+			);
+			container.removeEventListener(
+				'waveformplayer:ended',
+				handlers.ended
+			);
+			instance.destroy();
+			container.remove();
+		},
+	};
+}