@wordpress/block-library 9.48.0 → 10.0.1-next.v.202606191442.0

package/src/utils/test/style-state.js

@@ -0,0 +1,307 @@
+/**
+ * Internal dependencies
+ */
+import {
+	getActiveDimensionValue,
+	getDimensionResetAttributes,
+	getDimensionUpdateAttributes,
+	getStyleStateKey,
+	resetDimensions,
+	resetStateDimensions,
+	setStateDimensions,
+} from '../style-state';
+
+describe( 'style state dimension utilities', () => {
+	it( 'resets root dimensions without changing viewport dimensions', () => {
+		const style = {
+			dimensions: {
+				aspectRatio: '1',
+				minHeight: '40px',
+			},
+			mobile: {
+				dimensions: {
+					aspectRatio: '2',
+				},
+			},
+		};
+
+		expect( resetDimensions( style, [ 'aspectRatio' ] ) ).toEqual( {
+			dimensions: {
+				minHeight: '40px',
+			},
+			mobile: {
+				dimensions: {
+					aspectRatio: '2',
+				},
+			},
+		} );
+	} );
+
+	it( 'resets dimensions only for the selected viewport state', () => {
+		const style = {
+			dimensions: {
+				aspectRatio: '1',
+			},
+			mobile: {
+				dimensions: {
+					aspectRatio: '2',
+					width: '200px',
+				},
+			},
+			tablet: {
+				dimensions: {
+					aspectRatio: '3',
+				},
+			},
+		};
+
+		expect(
+			resetStateDimensions(
+				style,
+				{ viewport: 'mobile', pseudo: 'default' },
+				[ 'aspectRatio' ]
+			)
+		).toEqual( {
+			dimensions: {
+				aspectRatio: '1',
+			},
+			mobile: {
+				dimensions: {
+					width: '200px',
+				},
+			},
+			tablet: {
+				dimensions: {
+					aspectRatio: '3',
+				},
+			},
+		} );
+	} );
+
+	it( 'sets dimensions only for the selected viewport state', () => {
+		const style = {
+			mobile: {
+				dimensions: {
+					width: '200px',
+				},
+			},
+			tablet: {
+				dimensions: {
+					width: '300px',
+				},
+			},
+		};
+
+		expect(
+			setStateDimensions(
+				style,
+				{ viewport: 'mobile', pseudo: 'default' },
+				{ height: '100px' }
+			)
+		).toEqual( {
+			mobile: {
+				dimensions: {
+					height: '100px',
+					width: '200px',
+				},
+			},
+			tablet: {
+				dimensions: {
+					width: '300px',
+				},
+			},
+		} );
+	} );
+
+	it( 'generates a stable key for selected style states', () => {
+		expect(
+			getStyleStateKey( { viewport: 'mobile', pseudo: ':hover' } )
+		).toBe( 'mobile::hover' );
+		expect( getStyleStateKey( undefined ) ).toBe( 'default:default' );
+	} );
+
+	it( 'reads root attribute dimensions for the default state', () => {
+		expect(
+			getActiveDimensionValue( {
+				attributes: {
+					width: '200px',
+				},
+				attributeKey: 'width',
+				hasSelectedStyleState: false,
+			} )
+		).toBe( '200px' );
+	} );
+
+	it( 'reads mapped dimensions for selected style states', () => {
+		expect(
+			getActiveDimensionValue( {
+				attributes: {
+					scale: 'cover',
+					style: {
+						mobile: {
+							dimensions: {
+								objectFit: 'contain',
+							},
+						},
+					},
+				},
+				selectedState: { viewport: 'mobile', pseudo: 'default' },
+				hasSelectedStyleState: true,
+				attributeKey: 'scale',
+				styleKey: 'objectFit',
+			} )
+		).toBe( 'contain' );
+	} );
+
+	it( 'maps root dimension attributes to selected style state dimensions', () => {
+		expect(
+			getDimensionUpdateAttributes( {
+				style: {
+					mobile: {
+						dimensions: {
+							width: '200px',
+						},
+					},
+				},
+				selectedState: { viewport: 'mobile', pseudo: 'default' },
+				hasSelectedStyleState: true,
+				nextDimensions: {
+					scale: 'contain',
+				},
+				dimensionKeyMap: {
+					scale: 'objectFit',
+				},
+			} )
+		).toEqual( {
+			style: {
+				mobile: {
+					dimensions: {
+						objectFit: 'contain',
+						width: '200px',
+					},
+				},
+			},
+		} );
+	} );
+
+	it( 'clears omitted controlled root dimension attributes', () => {
+		expect(
+			getDimensionUpdateAttributes( {
+				hasSelectedStyleState: false,
+				nextDimensions: {
+					aspectRatio: '16/9',
+					width: '200px',
+					scale: 'cover',
+				},
+				dimensionKeys: [ 'aspectRatio', 'width', 'height', 'scale' ],
+			} )
+		).toEqual( {
+			aspectRatio: '16/9',
+			width: '200px',
+			height: undefined,
+			scale: 'cover',
+		} );
+	} );
+
+	it( 'clears omitted controlled selected style state dimensions', () => {
+		expect(
+			getDimensionUpdateAttributes( {
+				style: {
+					mobile: {
+						dimensions: {
+							height: '100px',
+							width: '200px',
+						},
+					},
+				},
+				selectedState: { viewport: 'mobile', pseudo: 'default' },
+				hasSelectedStyleState: true,
+				nextDimensions: {
+					aspectRatio: '16/9',
+					width: '200px',
+					scale: 'cover',
+				},
+				dimensionKeyMap: {
+					scale: 'objectFit',
+				},
+				dimensionKeys: [ 'aspectRatio', 'width', 'height', 'scale' ],
+			} )
+		).toEqual( {
+			style: {
+				mobile: {
+					dimensions: {
+						aspectRatio: '16/9',
+						objectFit: 'cover',
+						width: '200px',
+					},
+				},
+			},
+		} );
+	} );
+
+	it( 'resets selected style state dimensions without root attributes', () => {
+		expect(
+			getDimensionResetAttributes( {
+				attributes: {
+					width: '200px',
+					style: {
+						dimensions: {
+							width: '300px',
+						},
+						mobile: {
+							dimensions: {
+								width: '400px',
+							},
+						},
+					},
+				},
+				selectedState: { viewport: 'mobile', pseudo: 'default' },
+				hasSelectedStyleState: true,
+				keys: [ 'width' ],
+				defaultAttributes: {
+					width: undefined,
+				},
+			} )
+		).toEqual( {
+			style: {
+				dimensions: {
+					width: '300px',
+				},
+			},
+		} );
+	} );
+
+	it( 'resets default dimensions and root attributes', () => {
+		expect(
+			getDimensionResetAttributes( {
+				attributes: {
+					width: '200px',
+					style: {
+						dimensions: {
+							width: '300px',
+						},
+						mobile: {
+							dimensions: {
+								width: '400px',
+							},
+						},
+					},
+				},
+				hasSelectedStyleState: false,
+				keys: [ 'width' ],
+				defaultAttributes: {
+					width: undefined,
+				},
+			} )
+		).toEqual( {
+			width: undefined,
+			style: {
+				mobile: {
+					dimensions: {
+						width: '400px',
+					},
+				},
+			},
+		} );
+	} );
+} );

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

@@ -0,0 +1,254 @@
+/**
+ * @jest-environment jsdom
+ */
+
+/**
+ * External dependencies
+ */
+import '@testing-library/jest-dom';
+import { act, render } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import { WaveformPlayer } from '../waveform-player';
+import { initWaveformPlayer } from '../waveform-utils';
+
+jest.mock( '../waveform-utils', () => ( {
+	initWaveformPlayer: jest.fn(),
+} ) );
+
+/**
+ * Create a fake player instance that mimics the parts of the waveform
+ * player instance the component manipulates.
+ *
+ * @param {Object}  options Options passed to initWaveformPlayer.
+ * @param {Element} element The element passed to initWaveformPlayer.
+ * @return {Object} The fake player.
+ */
+function createFakePlayer( options, element ) {
+	const titleEl = document.createElement( 'span' );
+	titleEl.textContent = options.title ?? '';
+	// The subtitle and artwork elements only exist when the track had an
+	// artist/image when the player was created, mirroring the library markup.
+	let subtitleEl = null;
+	if ( options.artist ) {
+		subtitleEl = document.createElement( 'span' );
+		subtitleEl.textContent = options.artist;
+	}
+	let artworkEl = null;
+	if ( options.image ) {
+		artworkEl = document.createElement( 'img' );
+		artworkEl.src = options.image;
+	}
+
+	element.append( titleEl );
+	if ( subtitleEl ) {
+		element.append( subtitleEl );
+	}
+	if ( artworkEl ) {
+		element.append( artworkEl );
+	}
+
+	return {
+		instance: { titleEl, subtitleEl, artworkEl },
+		destroy: jest.fn(),
+	};
+}
+
+describe( 'WaveformPlayer', () => {
+	beforeEach( () => {
+		jest.useFakeTimers();
+		initWaveformPlayer.mockImplementation( ( element, options ) =>
+			createFakePlayer( options, element )
+		);
+	} );
+
+	afterEach( () => {
+		jest.runOnlyPendingTimers();
+		jest.useRealTimers();
+		initWaveformPlayer.mockReset();
+	} );
+
+	const baseProps = {
+		src: 'https://example.com/song.mp3',
+		title: 'Original Title',
+		artist: 'Original Artist',
+		image: 'https://example.com/cover.jpg',
+		onEnded: () => {},
+	};
+
+	it( 'initializes the player once with the provided metadata', () => {
+		render( <WaveformPlayer { ...baseProps } /> );
+
+		act( () => {
+			jest.advanceTimersByTime( 100 );
+		} );
+
+		expect( initWaveformPlayer ).toHaveBeenCalledTimes( 1 );
+		expect( initWaveformPlayer ).toHaveBeenCalledWith(
+			expect.anything(),
+			expect.objectContaining( {
+				src: baseProps.src,
+				title: 'Original Title',
+				artist: 'Original Artist',
+				image: 'https://example.com/cover.jpg',
+			} )
+		);
+	} );
+
+	it( 'updates metadata on the live player without recreating it', () => {
+		const { rerender } = render( <WaveformPlayer { ...baseProps } /> );
+
+		act( () => {
+			jest.advanceTimersByTime( 100 );
+		} );
+
+		const player = initWaveformPlayer.mock.results[ 0 ].value;
+
+		rerender(
+			<WaveformPlayer
+				{ ...baseProps }
+				title="New Title"
+				artist="New Artist"
+				image="https://example.com/new.jpg"
+			/>
+		);
+
+		// The player is updated in place, not destroyed and recreated.
+		expect( initWaveformPlayer ).toHaveBeenCalledTimes( 1 );
+		expect( player.destroy ).not.toHaveBeenCalled();
+		expect( player.instance.titleEl ).toHaveTextContent( 'New Title' );
+		expect( player.instance.subtitleEl ).toHaveTextContent( 'New Artist' );
+		expect( player.instance.artworkEl ).toHaveAttribute(
+			'src',
+			'https://example.com/new.jpg'
+		);
+	} );
+
+	it( 'recreates the player when the src changes', () => {
+		const { rerender } = render( <WaveformPlayer { ...baseProps } /> );
+
+		act( () => {
+			jest.advanceTimersByTime( 100 );
+		} );
+
+		const player = initWaveformPlayer.mock.results[ 0 ].value;
+
+		rerender(
+			<WaveformPlayer
+				{ ...baseProps }
+				src="https://example.com/other.mp3"
+			/>
+		);
+
+		act( () => {
+			jest.advanceTimersByTime( 100 );
+		} );
+
+		expect( player.destroy ).toHaveBeenCalledTimes( 1 );
+		expect( initWaveformPlayer ).toHaveBeenCalledTimes( 2 );
+	} );
+
+	it( 'recreates the player to show an image added to a track that had none', () => {
+		const { rerender } = render(
+			<WaveformPlayer { ...baseProps } image="" />
+		);
+
+		act( () => {
+			jest.advanceTimersByTime( 100 );
+		} );
+
+		const firstPlayer = initWaveformPlayer.mock.results[ 0 ].value;
+		// No artwork element exists when the track started without an image.
+		expect( firstPlayer.instance.artworkEl ).toBeNull();
+
+		rerender(
+			<WaveformPlayer
+				{ ...baseProps }
+				image="https://example.com/added.jpg"
+			/>
+		);
+
+		act( () => {
+			jest.advanceTimersByTime( 100 );
+		} );
+
+		expect( firstPlayer.destroy ).toHaveBeenCalledTimes( 1 );
+		expect( initWaveformPlayer ).toHaveBeenCalledTimes( 2 );
+		const secondPlayer = initWaveformPlayer.mock.results[ 1 ].value;
+		expect( secondPlayer.instance.artworkEl ).toHaveAttribute(
+			'src',
+			'https://example.com/added.jpg'
+		);
+	} );
+
+	it( 'recreates the player when the image is removed', () => {
+		const { rerender } = render( <WaveformPlayer { ...baseProps } /> );
+
+		act( () => {
+			jest.advanceTimersByTime( 100 );
+		} );
+
+		const player = initWaveformPlayer.mock.results[ 0 ].value;
+
+		rerender( <WaveformPlayer { ...baseProps } image="" /> );
+
+		act( () => {
+			jest.advanceTimersByTime( 100 );
+		} );
+
+		expect( player.destroy ).toHaveBeenCalledTimes( 1 );
+		expect( initWaveformPlayer ).toHaveBeenCalledTimes( 2 );
+		const secondPlayer = initWaveformPlayer.mock.results[ 1 ].value;
+		expect( secondPlayer.instance.artworkEl ).toBeNull();
+	} );
+
+	it( 'updates the player in place to show an artist added to a track that had none', () => {
+		const { rerender } = render(
+			<WaveformPlayer { ...baseProps } artist="" />
+		);
+
+		act( () => {
+			jest.advanceTimersByTime( 100 );
+		} );
+
+		const firstPlayer = initWaveformPlayer.mock.results[ 0 ].value;
+		// The editor seeds a hidden subtitle element so artist edits can
+		// update in place.
+		expect( firstPlayer.instance.subtitleEl ).toHaveTextContent( '' );
+		expect( firstPlayer.instance.subtitleEl ).toHaveStyle( {
+			display: 'none',
+		} );
+
+		rerender( <WaveformPlayer { ...baseProps } artist="New Artist" /> );
+
+		expect( firstPlayer.destroy ).not.toHaveBeenCalled();
+		expect( initWaveformPlayer ).toHaveBeenCalledTimes( 1 );
+		expect( firstPlayer.instance.subtitleEl ).toHaveTextContent(
+			'New Artist'
+		);
+		expect( firstPlayer.instance.subtitleEl ).not.toHaveStyle( {
+			display: 'none',
+		} );
+	} );
+
+	it( 'updates the player in place when the artist is removed', () => {
+		const { rerender } = render( <WaveformPlayer { ...baseProps } /> );
+
+		act( () => {
+			jest.advanceTimersByTime( 100 );
+		} );
+
+		const player = initWaveformPlayer.mock.results[ 0 ].value;
+
+		rerender( <WaveformPlayer { ...baseProps } artist="" /> );
+
+		expect( player.destroy ).not.toHaveBeenCalled();
+		expect( initWaveformPlayer ).toHaveBeenCalledTimes( 1 );
+		expect( player.instance.subtitleEl ).toHaveTextContent( '' );
+		expect( player.instance.subtitleEl ).toHaveStyle( {
+			display: 'none',
+		} );
+	} );
+} );

package/src/utils/waveform-player.js

@@ -1,36 +1,103 @@
 /**
  * WordPress dependencies
  */
-import { useRef } from '@wordpress/element';
-import { useRefEffect } from '@wordpress/compose';
+import { useEffect, useRef } from '@wordpress/element';
+import { useEvent, useRefEffect } from '@wordpress/compose';
 
 /**
  * Internal dependencies
  */
 import { initWaveformPlayer } from './waveform-utils';
 
+const EMPTY_ARTIST_PLACEHOLDER = '\u00a0';
+
+/**
+ * Update a live waveform player's metadata elements in place.
+ *
+ * The title element always exists, so the title is updated in place. The
+ * subtitle element is seeded during editor player creation, so it can be
+ * updated in place and hidden when the track has no artist. The artwork
+ * element only exists when the track had an image when the player was created,
+ * so its value is updated in place here; adding or removing an image (which
+ * creates or tears down that element) is instead handled by recreating the
+ * player, keyed on the `hasImage` dependency.
+ *
+ * The library's only metadata API is `loadTrack()`, which re-fetches and
+ * re-decodes the audio and regenerates the waveform (resetting playback), so
+ * it's unsuitable for live metadata edits. We instead write to the title,
+ * subtitle, and artwork elements directly, which is what `loadTrack()` itself
+ * does internally for these fields.
+ *
+ * @param {Object} instance        - The waveform player instance.
+ * @param {Object} metadata        - The track metadata.
+ * @param {string} metadata.title  - The track title.
+ * @param {string} metadata.artist - The artist name.
+ * @param {string} metadata.image  - The artwork image URL.
+ */
+function updatePlayerMetadata( instance, { title, artist, image } ) {
+	if ( instance.titleEl ) {
+		instance.titleEl.textContent = title ?? '';
+	}
+	if ( instance.subtitleEl ) {
+		instance.subtitleEl.textContent = artist ?? '';
+		instance.subtitleEl.style.display = artist ? '' : 'none';
+	}
+	if ( instance.artworkEl && image ) {
+		instance.artworkEl.src = image;
+	}
+}
+
 /**
  * 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.
+ * @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 {string}   props.waveformStyle - Waveform style (bars, mirror, line, blocks, dots, seekbar).
+ * @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.
+export function WaveformPlayer( {
+	src,
+	title,
+	artist,
+	image,
+	waveformStyle,
+	onEnded,
+} ) {
+	// Store onEnded in a stable callback 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 onEndedEvent = useEvent( onEnded );
+	const metadataRef = useRef( { title, artist, image } );
+	const playerRef = useRef();
+
+	// The artwork element only exists when an image was present when the
+	// player was created. Recreate the player when one is added or removed so
+	// that element is created or torn down; value changes to an existing
+	// element are applied in place below.
+	const hasImage = !! image;
+
+	// Keep the freshest metadata available to init() (which runs on a
+	// deferred timeout) and update the live player in place when metadata
+	// changes. Updating in place avoids destroying and recreating the
+	// player, which would flash it on every keystroke while editing a
+	// track's title or artist.
+	useEffect( () => {
+		metadataRef.current = { title, artist, image };
+
+		const instance = playerRef.current?.instance;
+		if ( instance ) {
+			updatePlayerMetadata( instance, { title, artist, image } );
+		}
+	}, [ title, artist, image ] );
 
 	const ref = useRefEffect(
 		( element ) => {
@@ -45,13 +112,17 @@ export function WaveformPlayer( { src, title, artist, image, onEnded } ) {
 				if ( cancelled ) {
 					return;
 				}
-				const { destroy } = initWaveformPlayer( element, {
+				const player = initWaveformPlayer( element, {
 					src,
-					title,
-					artist,
-					image,
-					onEnded: () => onEndedRef.current?.(),
+					...metadataRef.current,
+					waveformStyle,
+					artist:
+						metadataRef.current.artist || EMPTY_ARTIST_PLACEHOLDER,
+					onEnded: () => onEndedEvent?.(),
 				} );
+				playerRef.current = player;
+				updatePlayerMetadata( player.instance, metadataRef.current );
+				const { destroy } = player;
 				playerDestroy = destroy;
 			}
 
@@ -67,10 +138,11 @@ export function WaveformPlayer( { src, title, artist, image, onEnded } ) {
 			return () => {
 				cancelled = true;
 				clearTimeout( timeoutId );
+				playerRef.current = undefined;
 				playerDestroy?.();
 			};
 		},
-		[ src, title, artist, image ]
+		[ onEndedEvent, src, waveformStyle, hasImage ]
 	);
 
 	return <div ref={ ref } className="wp-block-playlist__waveform-player" />;