@wordpress/block-library 10.1.0 → 10.2.0

package/src/playlist/index.php

@@ -17,40 +17,37 @@
  * @return string Returns the Playlist.
  */
 function render_block_core_playlist( $attributes, $content, $block ) {
-	if ( empty( $attributes['currentTrack'] ) ) {
-		return '';
-	}
-
-	$current_media_id  = $attributes['currentTrack'];
-	$playlist_id       = wp_unique_id( 'playlist-' );
-	$playlist_tracks   = array();
-	$tracks_data       = array();
-	$current_unique_id = null;
+	$playlist_id              = wp_unique_id( 'playlist-' );
+	$playlist_tracks          = array();
+	$tracks_data              = array();
+	$show_play_button_artwork = ! empty( $attributes['showPlayButtonArtwork'] );
 
 	// Parse inner blocks to extract track data.
 	// This approach avoids duplicating track data in the HTML output.
 	if ( ! empty( $block->inner_blocks ) ) {
 		foreach ( $block->inner_blocks as $inner_block ) {
 			if ( 'core/playlist-track' === $inner_block->name ) {
-				$inner_block->context['playlistId'] = $playlist_id;
+				$track_attributes = $inner_block->attributes;
 
-				$track_attributes  = $inner_block->attributes;
-				$unique_id         = $track_attributes['uniqueId'] ?? wp_unique_id( 'playlist-track-' );
-				$playlist_tracks[] = $unique_id;
+				if ( empty( $track_attributes['id'] ) ) {
+					continue;
+				}
 
-				$inner_block->attributes['uniqueId'] = $unique_id;
+				$track_id          = 'track-' . count( $playlist_tracks );
+				$playlist_tracks[] = $track_id;
 
 				// Extract track metadata from block attributes.
 				$title      = isset( $track_attributes['title'] ) && ! empty( $track_attributes['title'] ) ? $track_attributes['title'] : __( 'Unknown title' );
 				$artist     = $track_attributes['artist'] ?? '';
 				$album      = $track_attributes['album'] ?? '';
 				$image      = $track_attributes['image'] ?? '';
+				$image_alt  = $track_attributes['imageAlt'] ?? '';
 				$url        = $track_attributes['src'] ?? '';
 				$aria_label = $title;
 
 				if ( $title && $artist && $album ) {
 					$aria_label = sprintf(
-						/* translators: %1$s: track title, %2$s artist name, %3$s: album name. */
+						/* translators: %1$s: track title, %2$s: artist name, %3$s: album name. */
 						_x( '%1$s by %2$s from the album %3$s', 'track title, artist name, album name' ),
 						$title,
 						$artist,
@@ -61,26 +58,20 @@ function render_block_core_playlist( $attributes, $content, $block ) {
 				// Data is passed to wp_interactivity_state() which JSON-encodes it,
 				// so we use wp_strip_all_tags() instead of esc_html() to prevent
 				// HTML injection without double-encoding. URLs still use esc_url().
-				$tracks_data[ $unique_id ] = array(
+				$tracks_data[ $track_id ] = array(
 					'url'       => esc_url( $url ),
 					'title'     => wp_strip_all_tags( $title ),
 					'artist'    => wp_strip_all_tags( $artist ),
 					'album'     => wp_strip_all_tags( $album ),
 					'image'     => esc_url( $image ),
+					'imageAlt'  => wp_strip_all_tags( $image_alt ),
 					'ariaLabel' => wp_strip_all_tags( $aria_label ),
 				);
-
-				if ( $unique_id === $current_media_id ) {
-					$current_unique_id = $unique_id;
-				}
 			}
 		}
 	}
 
-	// If there are no tracks but there is a currentTrack set, do not render the block.
-	// This can happen for example if the currentTrack was not deleted correctly
-	// or if the block is manually edited in the code editor mode.
-	if ( empty( $playlist_tracks ) || ! in_array( $current_media_id, $playlist_tracks, true ) ) {
+	if ( empty( $playlist_tracks ) ) {
 		return '';
 	}
 
@@ -102,13 +93,53 @@ function render_block_core_playlist( $attributes, $content, $block ) {
 	// Add waveform player container with translated button labels.
 	$label_play  = esc_attr__( 'Play' );
 	$label_pause = esc_attr__( 'Pause' );
-	$html        = '<div class="wp-block-playlist__waveform-player"
+	$label_seek  = esc_attr__( 'Seek' );
+	/* translators: %1$s: current audio time, %2$s: total audio duration. */
+	$label_seek_value                       = esc_attr_x(
+		'%1$s of %2$s',
+		'audio current time of total duration'
+	);
+	$waveform_color_attribute               = '';
+	$waveform_gradient_attribute            = '';
+	$waveform_background_color_attribute    = '';
+	$waveform_background_gradient_attribute = '';
+	if ( ! empty( $attributes['waveformColor'] ) ) {
+		$waveform_color_attribute = sprintf(
+			' data-waveform-player-color="%s"',
+			esc_attr( $attributes['waveformColor'] )
+		);
+	}
+	if ( ! empty( $attributes['waveformGradient'] ) ) {
+		$waveform_gradient_attribute = sprintf(
+			' data-waveform-player-gradient="%s"',
+			esc_attr( $attributes['waveformGradient'] )
+		);
+	}
+	if ( ! empty( $attributes['waveformBackgroundColor'] ) ) {
+		$waveform_background_color_attribute = sprintf(
+			' data-waveform-player-background-color="%s"',
+			esc_attr( $attributes['waveformBackgroundColor'] )
+		);
+	}
+	if ( ! empty( $attributes['waveformBackgroundGradient'] ) ) {
+		$waveform_background_gradient_attribute = sprintf(
+			' data-waveform-player-background-gradient="%s"',
+			esc_attr( $attributes['waveformBackgroundGradient'] )
+		);
+	}
+	$html = '<div class="wp-block-playlist__waveform-player"' .
+		$waveform_color_attribute .
+		$waveform_gradient_attribute .
+		$waveform_background_color_attribute .
+		$waveform_background_gradient_attribute . '
 		data-wp-watch="callbacks.initWaveformPlayer"
 		data-label-play="' . $label_play . '"
 		data-label-pause="' . $label_pause . '"
+		data-label-seek="' . $label_seek . '"
+		data-label-seek-value="' . $label_seek_value . '"
 	></div>';
 
-	// Add the HTML for the current track inside the figure.
+	// Add the waveform player container inside the figure.
 	$figure = null;
 	preg_match( '/<figure[^>]*>/', $content, $figure );
 	if ( ! empty( $figure[0] ) ) {
@@ -118,24 +149,48 @@ function render_block_core_playlist( $attributes, $content, $block ) {
 	$processor = new WP_HTML_Tag_Processor( $content );
 	$processor->next_tag( 'figure' );
 	$processor->set_attribute( 'data-wp-interactive', 'core/playlist' );
-	// Extract the waveform style from the block style variation class.
-	$waveform_style = 'bars';
-	if ( ! empty( $attributes['className'] ) && preg_match( '/is-style-([\w-]+)/', $attributes['className'], $matches ) ) {
-		$waveform_style = $matches[1];
-	}
+
+	$waveform_style = $attributes['waveformStyle'] ?? 'bars';
 
 	$processor->set_attribute(
 		'data-wp-context',
-		json_encode(
+		wp_json_encode(
 			array(
-				'playlistId'    => $playlist_id,
-				'currentId'     => $current_unique_id,
-				'tracks'        => $playlist_tracks,
-				'waveformStyle' => $waveform_style,
+				'playlistId'            => $playlist_id,
+				'currentId'             => $playlist_tracks[0],
+				'isPlaying'             => false,
+				'tracks'                => $playlist_tracks,
+				'waveformStyle'         => $waveform_style,
+				'showPlayButtonArtwork' => $show_play_button_artwork,
+				'labelPauseTrack'       => __( 'Pause' ),
+				'labelSelectTrack'      => __( 'Play' ),
 			)
 		)
 	);
 
+	// Track IDs are render-time only. Add them after inner blocks have rendered
+	// so track buttons can update the Interactivity API state without storing
+	// persistent unique IDs in post content.
+	$track_index = 0;
+	while ( $processor->next_tag( array( 'class_name' => 'wp-block-playlist-track__button' ) ) ) {
+		$track_id = $playlist_tracks[ $track_index ] ?? null;
+
+		if ( null === $track_id ) {
+			break;
+		}
+
+		$processor->set_attribute(
+			'data-wp-context',
+			wp_json_encode(
+				array(
+					'trackId' => $track_id,
+				)
+			)
+		);
+
+		++$track_index;
+	}
+
 	return $processor->get_updated_html();
 }
 

package/src/playlist/style.scss

@@ -4,16 +4,16 @@
 $waveform-player-height: 100px;
 
 .wp-block-playlist {
-	// Clip content to respect border-radius.
-	// `overflow: hidden` is a fallback for browsers that don't support `overflow: clip`.
-	overflow: hidden;
-	overflow: clip;
-
 	// Main waveform player container.
 	.wp-block-playlist__waveform-player {
 		width: 100%;
 		margin: var(--wp--preset--spacing--20, 0.625em) 0;
 		position: relative;
+
+		&:focus-visible {
+			outline: revert;
+			outline-offset: revert;
+		}
 	}
 
 	// Set the waveform track height and remove gap between button and waveform.
@@ -24,6 +24,7 @@ $waveform-player-height: 100px;
 
 	// WaveformPlayer button styling.
 	.waveform-btn {
+		border: none;
 		border-radius: 0;
 		border-end-start-radius: 0.125rem;
 		border-start-start-radius: 0.125rem;
@@ -36,16 +37,60 @@ $waveform-player-height: 100px;
 		&:hover:not(:disabled) {
 			transform: none;
 		}
+
+		svg {
+			width: 3rem;
+			height: 3rem;
+		}
+
+		.waveform-icon-pause svg {
+			// The pause icon's two full-height bars read larger than the
+			// play triangle at the same SVG box size, so optically scale it
+			// down to match the play icon's visual weight.
+			width: 2.625rem;
+			height: 2.625rem;
+		}
+	}
+
+	.waveform-player.has-play-button-artwork {
+		.waveform-btn {
+			background-image: var(--wp--playlist--play-button-artwork);
+			background-position: center;
+			background-size: cover;
+			color: #fff;
+
+			svg {
+				filter: drop-shadow(0 1px 2px rgba(0, 0, 0, 0.45));
+			}
+
+			svg path {
+				// Override inline fills applied before artwork is added.
+				fill: #fff !important;
+			}
+		}
 	}
 
 	.waveform-track.waveform-align-bottom .waveform-btn {
 		margin-bottom: 0;
 	}
 
-	.waveform-subtitle {
+	.waveform-btn:focus-visible,
+	.waveform-container:focus-visible {
+		outline: revert;
+		outline-offset: revert;
+	}
+
+	.waveform-artist {
 		opacity: 0.7;
 	}
 
+	.waveform-info,
+	.waveform-artist,
+	.waveform-title,
+	.waveform-time {
+		font-size: inherit;
+	}
+
 	.wp-block-playlist__tracklist {
 		margin: 0;
 		padding-left: 0;

package/src/playlist/test/edit.js

@@ -1,17 +1,8 @@
-/**
- * @jest-environment jsdom
- */
-
 /**
  * Internal dependencies
  */
 import { getTrackAttributes } from '../utils';
 
-// Mock uuid to return predictable values.
-jest.mock( 'uuid', () => ( {
-	v4: jest.fn( () => 'mock-uuid-1234' ),
-} ) );
-
 describe( 'Playlist block edit utilities', () => {
 	describe( 'getTrackAttributes', () => {
 		it( 'should transform media object to track attributes', () => {
@@ -22,20 +13,23 @@ describe( 'Playlist block edit utilities', () => {
 				artist: 'The Artist',
 				album: 'Great Album',
 				fileLength: '3:45',
-				image: { src: 'https://example.com/cover.jpg' },
+				image: {
+					src: 'https://example.com/cover.jpg',
+					alt: 'A bright abstract track image',
+				},
 			};
 
 			const result = getTrackAttributes( media );
 
 			expect( result ).toEqual( {
 				id: 123,
-				uniqueId: 'mock-uuid-1234',
 				src: 'https://example.com/song.mp3',
 				title: 'My Song',
 				artist: 'The Artist',
 				album: 'Great Album',
 				length: '3:45',
 				image: 'https://example.com/cover.jpg',
+				imageAlt: 'A bright abstract track image',
 			} );
 		} );
 
@@ -48,6 +42,8 @@ describe( 'Playlist block edit utilities', () => {
 			const result = getTrackAttributes( media );
 
 			expect( result.id ).toBe( 'https://example.com/song.mp3' );
+			expect( result.image ).toBeUndefined();
+			expect( result.imageAlt ).toBeUndefined();
 		} );
 
 		it( 'should fall back to meta.artist when artist is not available', () => {
@@ -120,18 +116,23 @@ describe( 'Playlist block edit utilities', () => {
 			const result = getTrackAttributes( media );
 
 			expect( result.image ).toBe( '' );
+			expect( result.imageAlt ).toBe( '' );
 		} );
 
 		it( 'should include image URLs', () => {
 			const media = {
 				url: 'https://example.com/song.mp3',
 				title: 'My Song',
-				image: { src: 'https://example.com/cover.jpg' },
+				image: {
+					src: 'https://example.com/cover.jpg',
+					alt_text: 'A black and white portrait',
+				},
 			};
 
 			const result = getTrackAttributes( media );
 
 			expect( result.image ).toBe( 'https://example.com/cover.jpg' );
+			expect( result.imageAlt ).toBe( 'A black and white portrait' );
 		} );
 	} );
 } );

package/src/playlist/utils.js

@@ -1,12 +1,31 @@
 /**
- * External dependencies
+ * WordPress dependencies
  */
-import { v4 as uuid } from 'uuid';
+import { __ } from '@wordpress/i18n';
 
 /**
- * WordPress dependencies
+ * Transform media library image data into track image attributes.
+ *
+ * @param {Object} image - Image object from the media library.
+ * @return {Object} Track image attributes for the playlist-track block.
  */
-import { __ } from '@wordpress/i18n';
+export function getTrackImageAttributes( image ) {
+	const imageSrc = image?.src ?? image?.url;
+
+	// Prevent using the default media attachment icon as the track image.
+	if ( imageSrc?.endsWith( '/images/media/audio.svg' ) ) {
+		return {
+			image: '',
+			imageAlt: '',
+		};
+	}
+
+	return {
+		// Note: Image is not available when a new track is uploaded.
+		image: imageSrc,
+		imageAlt: imageSrc ? image?.alt || image?.alt_text || '' : undefined,
+	};
+}
 
 /**
  * Transform media library data into track block attributes.
@@ -17,7 +36,6 @@ import { __ } from '@wordpress/i18n';
 export function getTrackAttributes( media ) {
 	return {
 		id: media.id || media.url, // Attachment ID or URL.
-		uniqueId: uuid(), // Unique ID for the track.
 		src: media.url,
 		title: media.title,
 		artist:
@@ -31,12 +49,6 @@ export function getTrackAttributes( media ) {
 			media?.media_details?.album ||
 			__( 'Unknown album' ),
 		length: media?.fileLength || media?.media_details?.length_formatted,
-		// Prevent using the default media attachment icon as the track image.
-		// Note: Image is not available when a new track is uploaded.
-		image:
-			media?.image?.src &&
-			media?.image?.src.endsWith( '/images/media/audio.svg' )
-				? ''
-				: media?.image?.src,
+		...getTrackImageAttributes( media?.image ),
 	};
 }

package/src/playlist/view.js

@@ -6,12 +6,18 @@ import { store, getContext, getElement } from '@wordpress/interactivity';
 /**
  * Internal dependencies
  */
-import { initWaveformPlayer, logPlayError } from '../utils/waveform-utils';
+import {
+	initWaveformPlayer,
+	logPlayError,
+	setupPlayButtonArtwork,
+	updateSeekControlLabel,
+} from '../utils/waveform-utils';
 
 /**
  * Store player state for each element.
  */
 const playerState = new WeakMap();
+const playlistPlayerState = new Map();
 
 const { state } = store(
 	'core/playlist',
@@ -19,14 +25,38 @@ const { state } = store(
 		state: {
 			playlists: {},
 			get isCurrentTrack() {
-				const { currentId, uniqueId } = getContext();
-				return currentId === uniqueId;
+				const { currentId, trackId } = getContext();
+				return currentId === trackId;
+			},
+			get isCurrentTrackPlaying() {
+				const { currentId, isPlaying, trackId } = getContext();
+				return currentId === trackId && !! isPlaying;
+			},
+			get trackButtonActionLabel() {
+				const { labelPauseTrack, labelSelectTrack } = getContext();
+				return state.isCurrentTrackPlaying
+					? labelPauseTrack
+					: labelSelectTrack;
 			},
 		},
 		actions: {
 			changeTrack() {
 				const context = getContext();
-				context.currentId = context.uniqueId;
+				if ( context.currentId === context.trackId ) {
+					const player = playlistPlayerState.get(
+						context.playlistId
+					)?.instance;
+					if ( player?.isPlaying ) {
+						context.isPlaying = false;
+						player.pause();
+					} else {
+						player?.play()?.catch( logPlayError );
+					}
+					return;
+				}
+
+				context.isPlaying = false;
+				context.currentId = context.trackId;
 			},
 		},
 		callbacks: {
@@ -74,27 +104,55 @@ const { state } = store(
  */
 function initPlayer( ref, track, shouldAutoPlay, context ) {
 	const existing = playerState.get( ref );
+	const showPlayButtonArtwork = context.showPlayButtonArtwork === true;
+	const playerArtwork = showPlayButtonArtwork ? '' : track.image;
 
 	// If a player already exists, load the new track without recreating.
 	if ( existing?.instance ) {
-		existing.instance
-			.loadTrack( track.url, track.title, track.artist, {
-				artwork: track.image,
-			} )
-			.then( () => {
-				existing.url = track.url;
-				if ( shouldAutoPlay ) {
-					existing.instance.play()?.catch( logPlayError );
-				}
-			} )
-			.catch( logPlayError );
-		return;
+		const shouldRecreatePlayer =
+			!! existing.instance.artworkEl !== !! playerArtwork;
+
+		if ( shouldRecreatePlayer ) {
+			existing.destroy?.();
+			playerState.delete( ref );
+		} else {
+			playlistPlayerState.set( context.playlistId, existing );
+			existing.instance
+				.loadTrack( track.url, track.title, track.artist, {
+					artwork: playerArtwork,
+					artworkAlt: playerArtwork ? track.imageAlt : '',
+				} )
+				.then( () => {
+					existing.url = track.url;
+					if ( existing.instance.artworkEl ) {
+						existing.instance.artworkEl.alt = track.imageAlt || '';
+					}
+					// loadTrack() preserves the previous explicit seekLabel option.
+					updateSeekControlLabel(
+						existing.instance,
+						track.title || ref.dataset.labelSeek
+					);
+					if ( showPlayButtonArtwork ) {
+						setupPlayButtonArtwork(
+							existing.container,
+							track.image
+						);
+					}
+					if ( shouldAutoPlay ) {
+						existing.instance.play()?.catch( logPlayError );
+					}
+				} )
+				.catch( logPlayError );
+			return;
+		}
 	}
 
 	// Read translated labels from server-rendered data attributes.
 	const labels = {
 		play: ref.dataset.labelPlay,
 		pause: ref.dataset.labelPause,
+		seek: ref.dataset.labelSeek,
+		seekValueText: ref.dataset.labelSeekValue,
 	};
 
 	// Initialize using the shared core.
@@ -103,13 +161,19 @@ function initPlayer( ref, track, shouldAutoPlay, context ) {
 		title: track.title,
 		artist: track.artist,
 		image: track.image,
+		imageAlt: track.imageAlt,
+		waveformColor: ref.dataset.waveformPlayerColor,
+		waveformGradient: ref.dataset.waveformPlayerGradient,
+		backgroundColor: ref.dataset.waveformPlayerBackgroundColor,
+		backgroundGradient: ref.dataset.waveformPlayerBackgroundGradient,
 		autoPlay: shouldAutoPlay,
 		labels,
 		waveformStyle: context.waveformStyle,
+		showPlayButtonArtwork,
 		onEnded: () => {
 			// Advance to next track (autoPlay handles playback).
 			const currentIndex = context.tracks.findIndex(
-				( uniqueId ) => uniqueId === context.currentId
+				( trackId ) => trackId === context.currentId
 			);
 			const nextTrack = context.tracks[ currentIndex + 1 ];
 			if ( nextTrack ) {
@@ -117,11 +181,28 @@ function initPlayer( ref, track, shouldAutoPlay, context ) {
 			}
 		},
 	} );
+	const setIsPlaying = ( isPlaying ) => {
+		context.isPlaying = isPlaying;
+	};
+	const onPlay = () => setIsPlaying( true );
+	const onPause = () => setIsPlaying( false );
+	player.container.addEventListener( 'waveformplayer:play', onPlay );
+	player.container.addEventListener( 'waveformplayer:pause', onPause );
+	player.container.addEventListener( 'waveformplayer:ended', onPause );
+	const destroy = () => {
+		player.container.removeEventListener( 'waveformplayer:play', onPlay );
+		player.container.removeEventListener( 'waveformplayer:pause', onPause );
+		player.container.removeEventListener( 'waveformplayer:ended', onPause );
+		player.destroy();
+	};
 
 	// Store state for cleanup, including instance for loadTrack reuse.
-	playerState.set( ref, {
+	const nextState = {
 		url: track.url,
 		instance: player.instance,
-		destroy: player.destroy,
-	} );
+		container: player.container,
+		destroy,
+	};
+	playerState.set( ref, nextState );
+	playlistPlayerState.set( context.playlistId, nextState );
 }

package/src/playlist-track/README.md

@@ -1,8 +1,6 @@
 # Playlist track
 
 <!-- START TOKEN(Autogenerated block API docs) -->
-<div class="callout callout-warning">This block is <strong>experimental</strong> and may change or be removed without notice.</div>
-
 Playlist track.
 
 - **Name:** `core/playlist-track`
@@ -24,12 +22,12 @@ _Defined via the [`attributes`](https://developer.wordpress.org/block-editor/ref
 |-----------|------|---------|-------------|
 | `blob` | `string` | — | [Role](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#role): `local` |
 | `id` | `number` | — | — |
-| `uniqueId` | `string` | — | — |
 | `src` | `string` | — | — |
 | `type` | `string` | `"audio"` | — |
 | `album` | `string` | — | — |
 | `artist` | `string` | — | — |
 | `image` | `string` | — | — |
+| `imageAlt` | `string` | — | — |
 | `length` | `string` | — | — |
 | `title` | `string` | — | — |
 
@@ -49,7 +47,7 @@ _Defined via the [`usesContext` and `providesContext`](https://developer.wordpre
 **Uses context:**
 
 - `showArtists`
-- `currentTrack`
+- `showImages`
 
 ## Block Markup
 
@@ -58,7 +56,7 @@ This is a [**dynamic block**](https://developer.wordpress.org/block-editor/getti
 In post content, it is stored as a block comment:
 
 ```html
-<!-- wp:playlist-track {"type":"audio"} /-->
+<!-- wp:core/playlist-track {"id":123,"src":"https://example.com/audio.mp3","album":"Example album","artist":"Example creator","image":"https://example.com/track-image.jpg","imageAlt":"Track image","length":"3:21","title":"Sample track"} /-->
 ```
 
 ## Source

package/src/playlist-track/block.json

@@ -1,7 +1,6 @@
 {
 	"$schema": "https://schemas.wp.org/trunk/block.json",
 	"apiVersion": 3,
-	"__experimental": true,
 	"name": "core/playlist-track",
 	"title": "Playlist track",
 	"category": "media",
@@ -9,7 +8,7 @@
 	"description": "Playlist track.",
 	"keywords": [ "music", "sound" ],
 	"textdomain": "default",
-	"usesContext": [ "showArtists", "currentTrack" ],
+	"usesContext": [ "showArtists", "showImages" ],
 	"attributes": {
 		"blob": {
 			"type": "string",
@@ -18,9 +17,6 @@
 		"id": {
 			"type": "number"
 		},
-		"uniqueId": {
-			"type": "string"
-		},
 		"src": {
 			"type": "string"
 		},
@@ -37,6 +33,9 @@
 		"image": {
 			"type": "string"
 		},
+		"imageAlt": {
+			"type": "string"
+		},
 		"length": {
 			"type": "string"
 		},