@wordpress/block-library 11.1.0 → 11.2.0

package/src/gallery/edit.jsx

@@ -23,7 +23,7 @@ import {
 	MediaReplaceFlow,
 	useSettings,
 } from '@wordpress/block-editor';
-import { useEffect, useMemo, useRef } from '@wordpress/element';
+import { useEffect, useMemo, useRef, useState } from '@wordpress/element';
 import { __, _x, sprintf } from '@wordpress/i18n';
 import { useSelect, useDispatch } from '@wordpress/data';
 import { createBlock } from '@wordpress/blocks';
@@ -64,7 +64,14 @@ import useGetMedia from './use-get-media';
 import GalleryStyles from './gallery-styles';
 import useDynamicGallery from './use-dynamic-gallery';
 import { GallerySourcePanel, GalleryDynamicView } from './dynamic-gallery';
-import { getDynamicSource, ATTACHED_MEDIA } from './dynamic-source';
+import { SortImagesControl, SourceOrderControl } from './order-controls';
+import {
+	getDynamicSource,
+	ATTACHED_MEDIA,
+	DEFAULT_ORDERBY,
+	DEFAULT_ORDER,
+} from './dynamic-source';
+import { hasSortableImages, sortImageBlocks } from './order-images';
 import {
 	getViewportGalleryStyle,
 	getUpdatedGalleryStyle,
@@ -313,6 +320,22 @@ export default function GalleryEdit( props ) {
 	const hasImages = !! images.length;
 	const isDynamic = !! attributes.dynamicContent;
 
+	// The static "Order by" control shows the last sort applied from it, for as
+	// long as the images stay in the sequence that sort produced. Any other
+	// change to the images (a drag, an addition, a removal) drops it back to
+	// "Custom"; it never reports an order the user didn't choose. Nothing is
+	// stored, so this is local state rather than an attribute.
+	const [ appliedSort, setAppliedSort ] = useState( null );
+	const currentOrder =
+		appliedSort &&
+		appliedSort.clientIds.length === innerBlockImages.length &&
+		appliedSort.clientIds.every(
+			( id, index ) => innerBlockImages[ index ].clientId === id
+		)
+			? appliedSort.order
+			: null;
+	const canSortImages = hasSortableImages( innerBlockImages, imageData );
+
 	// Dynamic mode (resolving images from a source instead of inner blocks):
 	// source resolution, the editor-preview blocks, and the mode/ordering
 	// actions.
@@ -545,6 +568,49 @@ export default function GalleryEdit( props ) {
 		}
 	}
 
+	function selectRandomOrder() {
+		setAttributes( { randomOrder: true } );
+	}
+
+	// Choosing any other order turns "Random" off. Called straight after the
+	// edit that applies the order, and marked non-persistent so the two writes
+	// share one undo level: a single undo restores both the order and Random.
+	function clearRandomOrderAfterEdit() {
+		if ( randomOrder ) {
+			__unstableMarkNextChangeAsNotPersistent();
+			setAttributes( { randomOrder: false } );
+		}
+	}
+
+	// Reorders the inner image blocks in place. Left persistent on purpose so
+	// the sort is a single undoable step.
+	function sortImages( order ) {
+		const sortedBlocks = sortImageBlocks(
+			getBlock( clientId ).innerBlocks,
+			imageData,
+			order
+		);
+		replaceInnerBlocks( clientId, sortedBlocks );
+		clearRandomOrderAfterEdit();
+		setAppliedSort( {
+			order,
+			clientIds: sortedBlocks.map( ( block ) => block.clientId ),
+		} );
+	}
+
+	// "Custom" is the order arranged in the editor: it turns Random off and
+	// forgets any sort applied earlier, so the control reads "Custom" from
+	// here on rather than that sort.
+	function selectCustomOrder() {
+		setAttributes( { randomOrder: false } );
+		setAppliedSort( null );
+	}
+
+	function changeSourceOrder( { orderby, order } ) {
+		dynamic.setSourceOrder( orderby, order );
+		clearRandomOrderAfterEdit();
+	}
+
 	function onUploadError( message ) {
 		createErrorNotice( message, { type: 'snackbar' } );
 	}
@@ -615,10 +681,6 @@ export default function GalleryEdit( props ) {
 		setGallerySettings( { imageCrop: ! activeImageCrop } );
 	}
 
-	function toggleRandomOrder() {
-		setAttributes( { randomOrder: ! randomOrder } );
-	}
-
 	function toggleOpenInNewTab( openInNewTab ) {
 		const newLinkTarget = openInNewTab ? '_blank' : undefined;
 		setAttributes( { linkTarget: newLinkTarget } );
@@ -862,7 +924,6 @@ export default function GalleryEdit( props ) {
 				{ ! isViewportStyleState && (
 					<GallerySourcePanel
 						dynamic={ dynamic }
-						dropdownMenuProps={ dropdownMenuProps }
 						hasImages={ hasImages }
 					/>
 				) }
@@ -889,6 +950,10 @@ export default function GalleryEdit( props ) {
 
 						setAspectRatio( 'auto' );
 
+						if ( isDynamic ) {
+							dynamic.setSourceOrder( undefined, undefined );
+						}
+
 						if ( sizeSlug !== DEFAULT_MEDIA_SIZE_SLUG ) {
 							updateImagesSize( DEFAULT_MEDIA_SIZE_SLUG );
 						}
@@ -930,6 +995,56 @@ export default function GalleryEdit( props ) {
 							/>
 						</ToolsPanelItem>
 					) }
+					{ ! isViewportStyleState && (
+						// "Random" is stored in both modes. Beyond that, a
+						// dynamic gallery's order is a stored query setting,
+						// while a static gallery's orders are one-off actions.
+						<ToolsPanelItem
+							isShownByDefault
+							label={ __( 'Order by' ) }
+							hasValue={ () =>
+								!! randomOrder ||
+								( isDynamic &&
+									( dynamic.sourceOrderby !==
+										DEFAULT_ORDERBY ||
+										dynamic.sourceOrder !==
+											DEFAULT_ORDER ) )
+							}
+							onDeselect={ () => {
+								if ( isDynamic ) {
+									// Two writes, folded into one undo level.
+									dynamic.setSourceOrder(
+										undefined,
+										undefined
+									);
+									clearRandomOrderAfterEdit();
+								} else {
+									selectCustomOrder();
+								}
+							} }
+						>
+							{ isDynamic ? (
+								<SourceOrderControl
+									order={ {
+										orderby: dynamic.sourceOrderby,
+										order: dynamic.sourceOrder,
+									} }
+									isRandom={ !! randomOrder }
+									onChange={ changeSourceOrder }
+									onSelectRandom={ selectRandomOrder }
+								/>
+							) : (
+								<SortImagesControl
+									currentOrder={ currentOrder }
+									isRandom={ !! randomOrder }
+									canSort={ canSortImages }
+									onSort={ sortImages }
+									onSelectCustom={ selectCustomOrder }
+									onSelectRandom={ selectRandomOrder }
+								/>
+							) }
+						</ToolsPanelItem>
+					) }
 					{ ! isViewportStyleState &&
 						imageSizeOptions?.length > 0 && (
 							<ToolsPanelItem
@@ -954,46 +1069,6 @@ export default function GalleryEdit( props ) {
 								/>
 							</ToolsPanelItem>
 						) }
-					{ isFlexLayout && (
-						<ToolsPanelItem
-							isShownByDefault
-							label={ __( 'Crop images to fit' ) }
-							hasValue={ () =>
-								isViewportStyleState
-									? hasViewportImageCrop
-									: ! activeImageCrop
-							}
-							onDeselect={ () =>
-								setGallerySettings( {
-									imageCrop: isViewportStyleState
-										? undefined
-										: true,
-								} )
-							}
-						>
-							<ToggleControl
-								label={ __( 'Crop images to fit' ) }
-								checked={ activeImageCrop }
-								onChange={ toggleImageCrop }
-							/>
-						</ToolsPanelItem>
-					) }
-					{ ! isViewportStyleState && (
-						<ToolsPanelItem
-							isShownByDefault
-							label={ __( 'Randomize order' ) }
-							hasValue={ () => !! randomOrder }
-							onDeselect={ () =>
-								setAttributes( { randomOrder: false } )
-							}
-						>
-							<ToggleControl
-								label={ __( 'Randomize order' ) }
-								checked={ !! randomOrder }
-								onChange={ toggleRandomOrder }
-							/>
-						</ToolsPanelItem>
-					) }
 					{ ! isViewportStyleState && hasLinkTo && (
 						<ToolsPanelItem
 							isShownByDefault
@@ -1037,6 +1112,30 @@ export default function GalleryEdit( props ) {
 							/>
 						</ToolsPanelItem>
 					) }
+					{ isFlexLayout && (
+						<ToolsPanelItem
+							isShownByDefault
+							label={ __( 'Crop images to fit' ) }
+							hasValue={ () =>
+								isViewportStyleState
+									? hasViewportImageCrop
+									: ! activeImageCrop
+							}
+							onDeselect={ () =>
+								setGallerySettings( {
+									imageCrop: isViewportStyleState
+										? undefined
+										: true,
+								} )
+							}
+						>
+							<ToggleControl
+								label={ __( 'Crop images to fit' ) }
+								checked={ activeImageCrop }
+								onChange={ toggleImageCrop }
+							/>
+						</ToolsPanelItem>
+					) }
 					{ ! isViewportStyleState &&
 						lightboxSetting?.allowEditing &&
 						hasLightboxImages && (

package/src/gallery/editor.scss

@@ -125,12 +125,9 @@
 	gap: $grid-unit-15;
 }
 
-// The Source controls are a plain (non-ToolsPanelItem) child of the Source
-// ToolsPanel, so they span both grid columns. The description sits above the
-// button so the button is the last element, keeping the same vertical rhythm to
-// the next control (control -> grid row-gap -> next label) as the other rows.
+// The Source panel's controls: a description above a full-width action button,
+// stacked inside a PanelBody.
 .wp-block-gallery__source-settings {
-	grid-column: 1 / -1;
 	display: flex;
 	flex-direction: column;
 	gap: $grid-unit-10;
@@ -150,9 +147,8 @@
 	}
 }
 
-// The "showing the first N" notice is a plain (non-ToolsPanelItem) child of the
-// Source ToolsPanel, so span both grid columns rather than defaulting to one.
+// The "showing the first N" notice follows the Source controls in the same
+// PanelBody, which adds no spacing of its own between children.
 .wp-block-gallery__source-notice {
-	grid-column: 1 / -1;
-	margin: 0;
+	margin: $grid-unit-20 0 0;
 }

package/src/gallery/order-controls.tsx

@@ -0,0 +1,143 @@
+import { __ } from '@wordpress/i18n';
+import { SelectControl as WCSelectControl } from '@wordpress/components';
+import {
+	ORDER_OPTIONS,
+	RANDOM_OPTION,
+	RANDOM_ORDER,
+	parseOrderValue,
+	toOrderValue,
+} from './order-options';
+import type { Order } from './order-options';
+
+function getOrderHelp( isRandom: boolean ): string | undefined {
+	return isRandom
+		? __( 'Images are shown in a random order each time the page loads.' )
+		: undefined;
+}
+
+const SOURCE_ORDER_OPTIONS = [ ...ORDER_OPTIONS, RANDOM_OPTION ];
+
+type SourceOrderControlProps = {
+	/** The stored query order. */
+	order: Order;
+	/** Whether the gallery's `randomOrder` attribute is set. */
+	isRandom: boolean;
+	/**
+	 * Called with `{ orderby, order }` to update the query. Choosing an order
+	 * also turns "Random" off; the handler owns that so both writes land in one
+	 * undo level.
+	 */
+	onChange: ( order: Order ) => void;
+	/** Called when "Random" is chosen. */
+	onSelectRandom: () => void;
+};
+
+/**
+ * Ordering control for a dynamic gallery, shown in the Settings panel. The
+ * chosen order is a *setting*: it's stored in the source's query and re-applied
+ * every time the source resolves. "Random" is stored separately (the
+ * `randomOrder` attribute) and overrides the query order on the front end, so
+ * while it's set the control shows it instead of the query order.
+ */
+export function SourceOrderControl( {
+	order,
+	isRandom,
+	onChange,
+	onSelectRandom,
+}: SourceOrderControlProps ) {
+	return (
+		<WCSelectControl
+			label={ __( 'Order by' ) }
+			value={ isRandom ? RANDOM_ORDER : toOrderValue( order ) }
+			options={ SOURCE_ORDER_OPTIONS }
+			help={ getOrderHelp( isRandom ) }
+			onChange={ ( value ) => {
+				if ( value === RANDOM_ORDER ) {
+					onSelectRandom();
+					return;
+				}
+				onChange( parseOrderValue( value ) );
+			} }
+		/>
+	);
+}
+
+const CUSTOM_ORDER = 'custom';
+
+type SortImagesControlProps = {
+	/** The last sort applied, while it still holds, or `null` for a custom order. */
+	currentOrder: Order | null;
+	/** Whether the gallery's `randomOrder` attribute is set. */
+	isRandom: boolean;
+	/** Whether the sort orders can be applied (false while media resolves). */
+	canSort: boolean;
+	/**
+	 * Called with `{ orderby, order }` to sort the images. Sorting also turns
+	 * "Random" off; the handler owns that so both writes land in one undo level.
+	 */
+	onSort: ( order: Order ) => void;
+	/** Called when "Custom" is chosen, which turns "Random" off. */
+	onSelectCustom: () => void;
+	/** Called when "Random" is chosen. */
+	onSelectRandom: () => void;
+};
+
+/**
+ * Ordering control for a static gallery, shown in the Settings panel.
+ *
+ * The date and title orders are one-off *actions*: choosing one reorders the
+ * inner image blocks once, and the user can drag them into any other order
+ * afterwards. Nothing is stored for them, so the caller passes back the last
+ * sort it applied for as long as the images remain in that sequence, and
+ * `null` ("Custom") otherwise. "Custom" means the order arranged in the
+ * editor, and is choosable only while "Random" is on: picking it turns
+ * "Random" off without reordering anything.
+ *
+ * "Random" is the one stored value (the `randomOrder` attribute). It applies
+ * on the front end only, leaving the editor order as it is, and choosing any
+ * other option clears it.
+ */
+export function SortImagesControl( {
+	currentOrder,
+	isRandom,
+	canSort,
+	onSort,
+	onSelectCustom,
+	onSelectRandom,
+}: SortImagesControlProps ) {
+	const options = [
+		{ label: __( 'Custom' ), value: CUSTOM_ORDER, disabled: ! isRandom },
+		...ORDER_OPTIONS.map( ( option ) => ( {
+			...option,
+			disabled: ! canSort,
+		} ) ),
+		RANDOM_OPTION,
+	];
+
+	let value = CUSTOM_ORDER;
+	if ( isRandom ) {
+		value = RANDOM_ORDER;
+	} else if ( currentOrder ) {
+		value = toOrderValue( currentOrder );
+	}
+
+	return (
+		<WCSelectControl
+			label={ __( 'Order by' ) }
+			value={ value }
+			options={ options }
+			help={ getOrderHelp( isRandom ) }
+			onChange={ ( nextValue ) => {
+				if ( nextValue === RANDOM_ORDER ) {
+					onSelectRandom();
+					return;
+				}
+				if ( nextValue === CUSTOM_ORDER ) {
+					onSelectCustom();
+					return;
+				}
+				onSort( parseOrderValue( nextValue ) );
+			} }
+		/>
+	);
+}

package/src/gallery/order-images.js

@@ -0,0 +1,111 @@
+/**
+ * Returns the value an image block is ordered by, or `undefined` when it has no
+ * resolved attachment record to take it from.
+ *
+ * @param {Object} block   A `core/image` inner block.
+ * @param {Array}  media   Attachment records for the gallery's images.
+ * @param {string} orderby `date` or `title`.
+ * @return {?string} The sort key.
+ */
+function getSortKey( block, media, orderby ) {
+	const { id } = block.attributes;
+	if ( id === undefined ) {
+		return undefined;
+	}
+	const record = media.find( ( item ) => item.id === id );
+	if ( ! record ) {
+		return undefined;
+	}
+	if ( orderby === 'title' ) {
+		// The media is fetched in the default (view) context, so `rendered`
+		// is the usual source; `raw` is only present with the edit context.
+		return record.title?.raw ?? record.title?.rendered ?? '';
+	}
+	return record.date ?? '';
+}
+
+/**
+ * Whether there's anything to sort: at least two image blocks with a resolved
+ * attachment record. With fewer, sorting is a no-op, so the sort options are
+ * disabled.
+ *
+ * @param {Array} blocks The gallery's `core/image` inner blocks.
+ * @param {Array} media  Attachment records for the gallery's images.
+ * @return {boolean} Whether the images can be sorted.
+ */
+export function hasSortableImages( blocks, media ) {
+	// Runs on every render, so avoid scanning `media` once per block.
+	const mediaIds = new Set( media.map( ( item ) => item.id ) );
+	let sortableCount = 0;
+	for ( const block of blocks ) {
+		if ( ! mediaIds.has( block.attributes.id ) ) {
+			continue;
+		}
+		sortableCount++;
+		if ( sortableCount > 1 ) {
+			return true;
+		}
+	}
+	return false;
+}
+
+/**
+ * Compares two sort keys for the given field. Titles use a natural,
+ * case-insensitive comparison so `IMG_2` sorts before `IMG_10`; dates are ISO
+ * 8601 strings, so a plain string comparison orders them chronologically.
+ *
+ * @param {string} a       First key.
+ * @param {string} b       Second key.
+ * @param {string} orderby `date` or `title`.
+ * @return {number} Negative when `a` sorts first, positive when `b` does.
+ */
+function compareKeys( a, b, orderby ) {
+	if ( orderby === 'title' ) {
+		return a.localeCompare( b, undefined, {
+			numeric: true,
+			sensitivity: 'base',
+		} );
+	}
+	if ( a === b ) {
+		return 0;
+	}
+	return a < b ? -1 : 1;
+}
+
+/**
+ * Sorts a static gallery's image blocks by an attachment field.
+ *
+ * Blocks without an `id`, or whose attachment record isn't in `media` (still
+ * loading, or deleted from the library), can't be placed, so they keep their
+ * relative order and move to the end. Blocks with equal keys likewise keep
+ * their relative order (`Array.prototype.sort` is stable), so re-applying the
+ * current order is a no-op.
+ *
+ * @param {Array}  blocks        The gallery's `core/image` inner blocks.
+ * @param {Array}  media         Attachment records for the gallery's images.
+ * @param {Object} order         The order to apply.
+ * @param {string} order.orderby `date` or `title`.
+ * @param {string} order.order   `asc` or `desc`.
+ * @return {Array} A new array holding the same block objects, sorted.
+ */
+export function sortImageBlocks( blocks, media, { orderby, order } ) {
+	const direction = order === 'desc' ? -1 : 1;
+	const keys = new Map(
+		blocks.map( ( block ) => [
+			block,
+			getSortKey( block, media, orderby ),
+		] )
+	);
+
+	return [ ...blocks ].sort( ( a, b ) => {
+		const keyA = keys.get( a );
+		const keyB = keys.get( b );
+		if ( keyA === undefined || keyB === undefined ) {
+			if ( keyA === keyB ) {
+				return 0;
+			}
+			return keyA === undefined ? 1 : -1;
+		}
+		return compareKeys( keyA, keyB, orderby ) * direction;
+	} );
+}

package/src/gallery/order-options.ts

@@ -0,0 +1,75 @@
+import { __ } from '@wordpress/i18n';
+
+/**
+ * An ordering of gallery images: the field to order by and the direction.
+ */
+export type Order = {
+	orderby: string;
+	order: string;
+};
+
+/**
+ * The composite `"orderby/order"` select value for an order. A select needs one
+ * string per option, so this format exists only at the select boundary; the
+ * rest of the feature passes `Order` objects.
+ *
+ * @param order The order.
+ * @return The select value.
+ */
+export function toOrderValue( order: Order ): string {
+	return `${ order.orderby }/${ order.order }`;
+}
+
+/**
+ * Parses a composite `"orderby/order"` select value back into an order.
+ *
+ * @param value The select value.
+ * @return The order.
+ */
+export function parseOrderValue( value: string ): Order {
+	const [ orderby, order ] = value.split( '/' );
+	return { orderby, order };
+}
+
+/**
+ * Ordering options offered for gallery images. Each value is a composite
+ * `orderby/order` string. The two modes share values and labels but differ
+ * in their comparison logic:
+ *
+ * - A dynamic gallery passes `orderby/order` to the REST API in the editor (the
+ *   `/wp/v2/media` collection params; see `dynamic-source.js`) and to a
+ *   `WP_Query` on the front end (see `index.php`). Either way the database
+ *   orders by post date or post title.
+ * - A static gallery orders its inner image blocks client-side from the same
+ *   attachment fields (see `order-images.js`). Dates compare the same way.
+ *   Titles use a natural, case-insensitive compare, so `IMG_2` sorts before
+ *   `IMG_10` where the database would put it after. The two title orders can
+ *   therefore differ for numbered titles.
+ *
+ * `menu_order` is deliberately omitted — it isn't a valid REST `orderby`
+ * value, so the editor preview couldn't reproduce it (see `dynamic-source.js`).
+ */
+export const ORDER_OPTIONS = [
+	{ label: __( 'Newest to oldest' ), value: 'date/desc' },
+	{ label: __( 'Oldest to newest' ), value: 'date/asc' },
+	{
+		/* translators: Label for ordering images by title in ascending order. */
+		label: __( 'A → Z' ),
+		value: 'title/asc',
+	},
+	{
+		/* translators: Label for ordering images by title in descending order. */
+		label: __( 'Z → A' ),
+		value: 'title/desc',
+	},
+];
+
+/**
+ * The "Random" order. Unlike the orders above it isn't an `orderby`: it is the
+ * gallery's `randomOrder` attribute, applied only on the front end by shuffling
+ * the rendered images (see `index.php`), so the editor keeps showing the
+ * underlying order. Offered as the last option of both modes' "Order by"
+ * control, since it overrides whatever other order is in place.
+ */
+export const RANDOM_ORDER = 'random';
+export const RANDOM_OPTION = { label: __( 'Random' ), value: RANDOM_ORDER };