@wordpress/block-library 10.1.1-next.v.202607070741.0 → 10.2.0

package/src/playlist/index.php

@@ -17,9 +17,10 @@
  * @return string Returns the Playlist.
  */
 function render_block_core_playlist( $attributes, $content, $block ) {
-	$playlist_id     = wp_unique_id( 'playlist-' );
-	$playlist_tracks = array();
-	$tracks_data     = array();
+	$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.
@@ -40,12 +41,13 @@ function render_block_core_playlist( $attributes, $content, $block ) {
 				$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,
@@ -62,6 +64,7 @@ function render_block_core_playlist( $attributes, $content, $block ) {
 					'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 ),
 				);
 			}
@@ -90,10 +93,50 @@ 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 waveform player container inside the figure.
@@ -106,20 +149,21 @@ 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',
 		wp_json_encode(
 			array(
-				'playlistId'    => $playlist_id,
-				'currentId'     => $playlist_tracks[0],
-				'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' ),
 			)
 		)
 	);

package/src/playlist/style.scss

@@ -9,6 +9,11 @@ $waveform-player-height: 100px;
 		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.
@@ -19,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;
@@ -31,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

@@ -13,7 +13,10 @@ 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 );
@@ -26,6 +29,7 @@ describe( 'Playlist block edit utilities', () => {
 				album: 'Great Album',
 				length: '3:45',
 				image: 'https://example.com/cover.jpg',
+				imageAlt: 'A bright abstract track image',
 			} );
 		} );
 
@@ -38,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', () => {
@@ -110,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

@@ -3,6 +3,30 @@
  */
 import { __ } from '@wordpress/i18n';
 
+/**
+ * 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.
+ */
+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.
  *
@@ -25,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',
@@ -22,10 +28,34 @@ const { state } = store(
 				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();
+				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;
 			},
 		},
@@ -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,9 +161,15 @@ 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(
@@ -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`
@@ -29,6 +27,7 @@ _Defined via the [`attributes`](https://developer.wordpress.org/block-editor/ref
 | `album` | `string` | — | — |
 | `artist` | `string` | — | — |
 | `image` | `string` | — | — |
+| `imageAlt` | `string` | — | — |
 | `length` | `string` | — | — |
 | `title` | `string` | — | — |
 
@@ -48,6 +47,7 @@ _Defined via the [`usesContext` and `providesContext`](https://developer.wordpre
 **Uses context:**
 
 - `showArtists`
+- `showImages`
 
 ## Block Markup
 
@@ -56,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" ],
+	"usesContext": [ "showArtists", "showImages" ],
 	"attributes": {
 		"blob": {
 			"type": "string",
@@ -34,6 +33,9 @@
 		"image": {
 			"type": "string"
 		},
+		"imageAlt": {
+			"type": "string"
+		},
 		"length": {
 			"type": "string"
 		},