@wordpress/block-editor 15.21.1 → 15.22.0

package/src/utils/{math.js → math.ts}

@@ -1,14 +1,14 @@
 /**
  * A string representing the name of an edge.
- *
- * @typedef {'top'|'right'|'bottom'|'left'} WPEdgeName
  */
+type EdgeName = 'top' | 'right' | 'bottom' | 'left';
 
-/**
- * @typedef  {Object} WPPoint
- * @property {number} x The horizontal position.
- * @property {number} y The vertical position.
- */
+interface Point {
+	/** The horizontal position. */
+	x: number;
+	/** The vertical position. */
+	y: number;
+}
 
 /**
  * Given a point, a DOMRect and the name of an edge, returns the distance to
@@ -23,11 +23,15 @@
  * - Lateral, meaning the axis running vertically when an edge is vertical
  *   and horizontally when an edge is horizontal.
  *
- * @param {WPPoint}    point The point to measure distance from.
- * @param {DOMRect}    rect  A DOM Rect containing edge positions.
- * @param {WPEdgeName} edge  The edge to measure to.
+ * @param point The point to measure distance from.
+ * @param rect  A DOM Rect containing edge positions.
+ * @param edge  The edge to measure to.
  */
-export function getDistanceFromPointToEdge( point, rect, edge ) {
+export function getDistanceFromPointToEdge(
+	point: Point,
+	rect: DOMRect,
+	edge: EdgeName
+) {
 	const isHorizontal = edge === 'top' || edge === 'bottom';
 	const { x, y } = point;
 	const pointLateralPosition = isHorizontal ? x : y;
@@ -62,21 +66,21 @@ export function getDistanceFromPointToEdge( point, rect, edge ) {
  * Given a point, a DOMRect and a list of allowed edges returns the name of and
  * distance to the nearest edge.
  *
- * @param {WPPoint}      point        The point to measure distance from.
- * @param {DOMRect}      rect         A DOM Rect containing edge positions.
- * @param {WPEdgeName[]} allowedEdges A list of the edges included in the
- *                                    calculation. Defaults to all edges.
+ * @param point        The point to measure distance from.
+ * @param rect         A DOM Rect containing edge positions.
+ * @param allowedEdges A list of the edges included in the
+ *                     calculation. Defaults to all edges.
  *
- * @return {[number, string]} An array where the first value is the distance
- *                              and a second is the edge name.
+ * @return An array where the first value is the distance
+ *         and a second is the edge name.
  */
 export function getDistanceToNearestEdge(
-	point,
-	rect,
-	allowedEdges = [ 'top', 'bottom', 'left', 'right' ]
+	point: Point,
+	rect: DOMRect,
+	allowedEdges: EdgeName[] = [ 'top', 'bottom', 'left', 'right' ]
 ) {
-	let candidateDistance;
-	let candidateEdge;
+	let candidateDistance: number | undefined;
+	let candidateEdge: EdgeName | undefined;
 
 	allowedEdges.forEach( ( edge ) => {
 		const distance = getDistanceFromPointToEdge( point, rect, edge );
@@ -93,12 +97,12 @@ export function getDistanceToNearestEdge(
 /**
  * Is the point contained by the rectangle.
  *
- * @param {WPPoint} point The point.
- * @param {DOMRect} rect  The rectangle.
+ * @param point The point.
+ * @param rect  The rectangle.
  *
- * @return {boolean} True if the point is contained by the rectangle, false otherwise.
+ * @return True if the point is contained by the rectangle, false otherwise.
  */
-export function isPointContainedByRect( point, rect ) {
+export function isPointContainedByRect( point: Point, rect: DOMRect ) {
 	return (
 		rect.left <= point.x &&
 		rect.right >= point.x &&
@@ -110,11 +114,14 @@ export function isPointContainedByRect( point, rect ) {
 /**
  * Is the point within the top and bottom boundaries of the rectangle.
  *
- * @param {WPPoint} point The point.
- * @param {DOMRect} rect  The rectangle.
+ * @param point The point.
+ * @param rect  The rectangle.
  *
- * @return {boolean} True if the point is within top and bottom of rectangle, false otherwise.
+ * @return True if the point is within top and bottom of rectangle, false otherwise.
  */
-export function isPointWithinTopAndBottomBoundariesOfRect( point, rect ) {
+export function isPointWithinTopAndBottomBoundariesOfRect(
+	point: Point,
+	rect: DOMRect
+) {
 	return rect.top <= point.y && rect.bottom >= point.y;
 }

package/src/utils/object.ts

@@ -0,0 +1,89 @@
+type AnyObject = Record< string, unknown >;
+type ObjectOrArray = AnyObject | unknown[];
+type ObjectPathKey = number | string;
+type ObjectPath = ObjectPathKey | ObjectPathKey[];
+
+/**
+ * Immutably sets a value inside an object. Like `lodash#set`, but returning a
+ * new object. Treats nullish initial values as empty objects. Clones any
+ * nested objects. Supports arrays, too.
+ *
+ * @param object Object to set a value in.
+ * @param path   Path in the object to modify.
+ * @param value  New value to set.
+ * @return Cloned object with the new value set.
+ */
+export function setImmutably(
+	object: ObjectOrArray | null | undefined,
+	path: ObjectPath,
+	value: unknown
+): ObjectOrArray {
+	// Normalize path
+	const pathArray: ObjectPathKey[] = Array.isArray( path )
+		? [ ...path ]
+		: [ path ];
+
+	// Shallowly clone the base of the object
+	const result: ObjectOrArray = Array.isArray( object )
+		? [ ...object ]
+		: { ...object };
+
+	const leaf = pathArray.pop() as ObjectPathKey;
+
+	// Traverse object from root to leaf, shallowly cloning at each level
+	let prev: ObjectOrArray = result;
+	for ( const key of pathArray ) {
+		const lvl = ( prev as AnyObject )[ key ];
+		( prev as AnyObject )[ key ] = prev = Array.isArray( lvl )
+			? [ ...lvl ]
+			: { ...( lvl as AnyObject ) };
+	}
+
+	( prev as AnyObject )[ leaf ] = value;
+
+	return result;
+}
+
+/**
+ * Helper util to return a value from a certain path of the object.
+ * Path is specified as either:
+ * - a string of properties, separated by dots, for example: "x.y".
+ * - an array of properties, for example `[ 'x', 'y' ]`.
+ * You can also specify a default value in case the result is nullish.
+ *
+ * @param object       Input object.
+ * @param path         Path to the object property.
+ * @param defaultValue Default value if the value at the specified path is nullish.
+ * @return Value of the object property at the specified path.
+ */
+export const getValueFromObjectPath = (
+	object: AnyObject | undefined | null,
+	path: string | string[],
+	defaultValue?: unknown
+) => {
+	const arrayPath = Array.isArray( path ) ? path : path.split( '.' );
+	let value: unknown = object;
+	arrayPath.forEach( ( fieldName ) => {
+		value = ( value as AnyObject | undefined | null )?.[ fieldName ];
+	} );
+	return value ?? defaultValue;
+};
+
+/**
+ * Helper util to filter out objects with duplicate values for a given property.
+ *
+ * @param array    Array of objects to filter.
+ * @param property Property to filter unique values by.
+ *
+ * @return Array of objects with unique values for the specified property.
+ */
+export function uniqByProperty< T extends AnyObject >(
+	array: T[],
+	property: string
+) {
+	const seen = new Set();
+	return array.filter( ( item ) => {
+		const value = item[ property ];
+		return seen.has( value ) ? false : seen.add( value );
+	} );
+}

package/src/utils/{order-inserter-block-items.js → order-inserter-block-items.ts}

@@ -1,13 +1,16 @@
-/** @typedef {import('../store/selectors').WPEditorInserterItem} WPEditorInserterItem */
+type EditorInserterItem = { id: string };
 
 /**
  * Helper function to order inserter block items according to a provided array of prioritized blocks.
  *
- * @param {WPEditorInserterItem[]} items    The array of editor inserter block items to be sorted.
- * @param {string[]}               priority The array of block names to be prioritized.
- * @return {WPEditorInserterItem[]} The sorted array of editor inserter block items.
+ * @param items    The array of editor inserter block items to be sorted.
+ * @param priority The array of block names to be prioritized.
+ * @return The sorted array of editor inserter block items.
  */
-export const orderInserterBlockItems = ( items, priority ) => {
+export const orderInserterBlockItems = (
+	items: EditorInserterItem[],
+	priority: string[] | undefined
+) => {
 	if ( ! priority ) {
 		return items;
 	}

package/src/utils/{pasting.js → pasting.ts}

@@ -7,10 +7,10 @@ import { getFilesFromDataTransfer } from '@wordpress/dom';
  * Normalizes a given string of HTML to remove the Windows-specific "Fragment"
  * comments and any preceding and trailing content.
  *
- * @param {string} html the html to be normalized
- * @return {string} the normalized html
+ * @param html the html to be normalized
+ * @return the normalized html
  */
-function removeWindowsFragments( html ) {
+function removeWindowsFragments( html: string ) {
 	const startStr = '<!--StartFragment-->';
 	const startIdx = html.indexOf( startStr );
 	if ( startIdx > -1 ) {
@@ -35,10 +35,10 @@ function removeWindowsFragments( html ) {
  * - https://github.com/WordPress/gutenberg/issues/33585
  * - https://bugs.chromium.org/p/chromium/issues/detail?id=1264616#c4
  *
- * @param {string} html the html to be stripped of the meta tag.
- * @return {string} the cleaned html
+ * @param html the html to be stripped of the meta tag.
+ * @return the cleaned html
  */
-function removeCharsetMetaTag( html ) {
+function removeCharsetMetaTag( html: string ) {
 	const metaTag = `<meta charset='utf-8'>`;
 
 	if ( html.startsWith( metaTag ) ) {
@@ -48,7 +48,11 @@ function removeCharsetMetaTag( html ) {
 	return html;
 }
 
-export function getPasteEventData( { clipboardData } ) {
+export function getPasteEventData( {
+	clipboardData,
+}: {
+	clipboardData: DataTransfer;
+} ) {
 	let plainText = '';
 	let html = '';
 
@@ -88,11 +92,14 @@ export function getPasteEventData( { clipboardData } ) {
  * content and not the screenshot, since this allows Gutenberg to insert
  * meaningful blocks, like paragraphs, lists or even tables.
  *
- * @param {File[]} files File objects obtained from a paste event
- * @param {string} html  HTML content obtained from a paste event
- * @return {boolean}     True if the files should be dismissed
+ * @param files File objects obtained from a paste event
+ * @param html  HTML content obtained from a paste event
+ * @return      True if the files should be dismissed
  */
-export function shouldDismissPastedFiles( files, html /*, plainText */ ) {
+export function shouldDismissPastedFiles(
+	files: File[],
+	html: string /*, plainText */
+) {
 	// The question is only relevant when there is actual HTML content and when
 	// there is exactly one image file.
 	if (

package/src/utils/{selection.js → selection.ts}

@@ -13,10 +13,12 @@ export const START_OF_SELECTED_AREA = '\u0086';
 /**
  * Retrieve the block attribute that contains the selection position.
  *
- * @param {Object} blockAttributes Block attributes.
- * @return {string|void} The name of the block attribute that was previously selected.
+ * @param blockAttributes Block attributes.
+ * @return The name of the block attribute that was previously selected.
  */
-export function retrieveSelectedAttribute( blockAttributes ) {
+export function retrieveSelectedAttribute(
+	blockAttributes: Record< string, unknown > | undefined
+) {
 	if ( ! blockAttributes ) {
 		return;
 	}
@@ -32,10 +34,15 @@ export function retrieveSelectedAttribute( blockAttributes ) {
 	} );
 }
 
-export function findRichTextAttributeKey( blockType ) {
+type BlockTypeWithAttributes = {
+	attributes: Record< string, { source?: string } >;
+};
+
+export function findRichTextAttributeKey( blockType: BlockTypeWithAttributes ) {
 	for ( const [ key, value ] of Object.entries( blockType.attributes ) ) {
 		if ( value.source === 'rich-text' || value.source === 'html' ) {
 			return key;
 		}
 	}
+	return undefined;
 }

package/src/utils/sorting.ts

@@ -0,0 +1,81 @@
+type Comparable = string | number | undefined;
+type SortItem = Record< string, Comparable >;
+type SortField< T > = string | ( ( item: T ) => Comparable );
+
+/**
+ * Mirrors the `>` operator for `Comparable` values: lexicographic when both
+ * are strings, numeric otherwise (an `undefined` operand is never greater).
+ *
+ * @param a Left-hand value.
+ * @param b Right-hand value.
+ * @return Whether `a` is greater than `b`.
+ */
+function isGreater( a: Comparable, b: Comparable ): boolean {
+	if ( typeof a === 'string' && typeof b === 'string' ) {
+		return a > b;
+	}
+	return Number( a ) > Number( b );
+}
+
+/**
+ * Recursive stable sorting comparator function.
+ *
+ * @param field Field to sort by.
+ * @param items Items to sort.
+ * @param order Order, 'asc' or 'desc'.
+ * @return Comparison function to be used in a `.sort()`.
+ */
+const comparator = < T extends SortItem >(
+	field: SortField< T >,
+	items: T[],
+	order: string
+) => {
+	return ( a: T, b: T ) => {
+		let cmpA: Comparable, cmpB: Comparable;
+
+		if ( typeof field === 'function' ) {
+			cmpA = field( a );
+			cmpB = field( b );
+		} else {
+			cmpA = a[ field ];
+			cmpB = b[ field ];
+		}
+
+		if ( isGreater( cmpA, cmpB ) ) {
+			return order === 'asc' ? 1 : -1;
+		} else if ( isGreater( cmpB, cmpA ) ) {
+			return order === 'asc' ? -1 : 1;
+		}
+
+		const orderA = items.findIndex( ( item ) => item === a );
+		const orderB = items.findIndex( ( item ) => item === b );
+
+		// Stable sort: maintaining original array order
+		if ( orderA > orderB ) {
+			return 1;
+		} else if ( orderB > orderA ) {
+			return -1;
+		}
+
+		return 0;
+	};
+};
+
+/**
+ * Order items by a certain key.
+ * Supports decorator functions that allow complex picking of a comparison field.
+ * Sorts in ascending order by default, but supports descending as well.
+ * Stable sort - maintains original order of equal items.
+ *
+ * @param items Items to order.
+ * @param field Field to order by.
+ * @param order Sorting order, `asc` or `desc`.
+ * @return Sorted items.
+ */
+export function orderBy< T extends SortItem >(
+	items: T[],
+	field: SortField< T >,
+	order = 'asc'
+) {
+	return items.concat().sort( comparator( field, items, order ) );
+}

package/src/utils/test/color-values.js

@@ -1,7 +1,10 @@
 /**
  * Internal dependencies
  */
-import { extractPresetSlug } from '../color-values';
+import {
+	extractPresetSlug,
+	encodeColorValueWithPalette,
+} from '../color-values';
 
 describe( 'extractPresetSlug', () => {
 	it( 'extracts the slug for a color from the user preset format', () => {
@@ -76,3 +79,43 @@ describe( 'extractPresetSlug', () => {
 		).toBeUndefined();
 	} );
 } );
+
+describe( 'encodeColorValueWithPalette', () => {
+	const palette = [
+		{ slug: 'brand-a', color: '#e10000' },
+		{ slug: 'brand-b', color: '#e10000' },
+		{ slug: 'accent', color: '#0000ff' },
+	];
+
+	it( 'encodes the provided slug directly, ignoring the hex value', () => {
+		expect(
+			encodeColorValueWithPalette( palette, '#e10000', 'brand-b' )
+		).toBe( 'var:preset|color|brand-b' );
+	} );
+
+	it( 'preserves the user choice when two presets share the same hex', () => {
+		// Selecting `brand-b` must not collapse onto `brand-a` (the first
+		// palette entry with the same hex). This is the regression guard.
+		expect(
+			encodeColorValueWithPalette( palette, '#e10000', 'brand-b' )
+		).not.toBe( 'var:preset|color|brand-a' );
+	} );
+
+	it( 'falls back to matching the hex against the palette when no slug is supplied', () => {
+		expect( encodeColorValueWithPalette( palette, '#0000ff' ) ).toBe(
+			'var:preset|color|accent'
+		);
+	} );
+
+	it( 'matches the first entry on hex collision only when no slug is supplied', () => {
+		expect( encodeColorValueWithPalette( palette, '#e10000' ) ).toBe(
+			'var:preset|color|brand-a'
+		);
+	} );
+
+	it( 'stores the raw value when the hex is not in the palette and no slug is supplied', () => {
+		expect( encodeColorValueWithPalette( palette, '#abcabc' ) ).toBe(
+			'#abcabc'
+		);
+	} );
+} );

package/src/utils/transform-styles/{index.js → index.ts}

@@ -1,3 +1,5 @@
+/// <reference path="./postcss-urlrebase.d.ts" />
+
 /**
  * External dependencies
  */
@@ -7,6 +9,11 @@ import CssSyntaxError from 'postcss/lib/css-syntax-error';
 import prefixSelector from 'postcss-prefix-selector';
 import rebaseUrl from 'postcss-urlrebase';
 
+/**
+ * Internal dependencies
+ */
+import type { EditorStyle, TransformOptions } from './types';
+
 const cacheByWrapperSelector = new Map();
 
 const ROOT_SELECTOR_TOKENS = [
@@ -33,12 +40,12 @@ const ROOT_SELECTOR_TOKENS = [
  * - If a classname, id, or something else is used as the prefix, all selectors
  *   will have the same specificity bump when transformed.
  *
- * @param {string} prefix   The prefix.
- * @param {string} selector The selector.
+ * @param prefix   The prefix.
+ * @param selector The selector.
  *
- * @return {string} The prefixed root selector.
+ * @return The prefixed root selector.
  */
-function prefixRootSelector( prefix, selector ) {
+function prefixRootSelector( prefix: string, selector: string ) {
 	// Use a tokenizer, since regular expressions are unreliable.
 	const tokenized = parsel.tokenize( selector );
 
@@ -74,7 +81,8 @@ function prefixRootSelector( prefix, selector ) {
 		{
 			type: 'combinator',
 			content: ' ',
-		},
+			pos: [ 0, 0 ],
+		} as parsel.Token,
 		...tokenizedPrefix
 	);
 
@@ -82,9 +90,9 @@ function prefixRootSelector( prefix, selector ) {
 }
 
 function transformStyle(
-	{ css, ignoredSelectors = [], baseURL },
+	{ css, ignoredSelectors = [], baseURL }: EditorStyle,
 	wrapperSelector = '',
-	transformOptions
+	transformOptions?: TransformOptions
 ) {
 	// When there is no wrapper selector and no base URL, there is no need
 	// to transform the CSS. This is most cases because in the default
@@ -136,7 +144,7 @@ function transformStyle(
 						},
 					} ),
 				baseURL && rebaseUrl( { rootUrl: baseURL } ),
-			].filter( Boolean )
+			].filter( Boolean ) as import('postcss').AcceptedPlugin[]
 		).process( css, {} ).css; // use sync PostCSS API
 	} catch ( error ) {
 		if ( error instanceof CssSyntaxError ) {
@@ -157,27 +165,19 @@ function transformStyle(
 	}
 }
 
-/**
- * @typedef {Object} EditorStyle
- * @property {string}    css              the CSS block(s), as a single string.
- * @property {?string}   baseURL          the base URL to be used as the reference when rewriting urls.
- * @property {?string[]} ignoredSelectors the selectors not to wrap.
- */
-
-/**
- * @typedef {Object} TransformOptions
- * @property {?string[]} ignoredSelectors the selectors not to wrap.
- */
-
 /**
  * Applies a series of CSS rule transforms to wrap selectors inside a given class and/or rewrite URLs depending on the parameters passed.
  *
- * @param {EditorStyle[]}    styles           CSS rules.
- * @param {string}           wrapperSelector  Wrapper selector.
- * @param {TransformOptions} transformOptions Additional options for style transformation.
- * @return {Array} converted rules.
+ * @param styles           CSS rules.
+ * @param wrapperSelector  Wrapper selector.
+ * @param transformOptions Additional options for style transformation.
+ * @return converted rules.
  */
-const transformStyles = ( styles, wrapperSelector = '', transformOptions ) => {
+const transformStyles = (
+	styles: EditorStyle[],
+	wrapperSelector = '',
+	transformOptions?: TransformOptions
+) => {
 	let cache = cacheByWrapperSelector.get( wrapperSelector );
 	if ( ! cache ) {
 		cache = new WeakMap();

package/src/utils/transform-styles/postcss-urlrebase.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `postcss-urlrebase` ships an `index.d.ts` that incorrectly declares the module as `rebaseUrl` instead of `postcss-urlrebase`.
+ * Until that's fixed upstream, redeclare the module here so its types resolve correctly.
+ */
+declare module 'postcss-urlrebase' {
+	import type { PluginCreator } from 'postcss';
+
+	interface RebaseUrlOptions {
+		skipHostRelativeUrls?: boolean;
+		rootUrl: string | URL;
+	}
+
+	const rebaseUrl: PluginCreator< RebaseUrlOptions >;
+	export default rebaseUrl;
+}

package/src/utils/transform-styles/types.ts

@@ -0,0 +1,13 @@
+export interface EditorStyle {
+	/** The CSS block(s), as a single string. */
+	css: string;
+	/** The base URL to be used as the reference when rewriting urls. */
+	baseURL?: string;
+	/** The selectors not to wrap. */
+	ignoredSelectors?: ( string | RegExp )[];
+}
+
+export interface TransformOptions {
+	/** The selectors not to wrap. */
+	ignoredSelectors?: ( string | RegExp )[];
+}

package/src/utils/types.ts

@@ -0,0 +1,29 @@
+/**
+ * Result of formatting a font style or weight.
+ */
+export interface FormattedFont {
+	/** Human readable name. */
+	name?: string;
+	/** Original CSS value. */
+	value?: string;
+}
+
+/**
+ * A font family face from theme.json.
+ */
+export interface FontFamilyFace {
+	fontStyle?: string;
+	fontWeight?: string | number;
+}
+
+/**
+ * Combined font style and weight option for a font picker.
+ */
+export interface CombinedStyleAndWeightOption {
+	key: string;
+	name: string;
+	style: {
+		fontStyle?: string;
+		fontWeight?: string;
+	};
+}

package/src/utils/block-bindings.js

@@ -1,46 +0,0 @@
-const DEFAULT_ATTRIBUTE = '__default';
-const PATTERN_OVERRIDES_SOURCE = 'core/pattern-overrides';
-
-/**
- * Checks if the block has the `__default` binding for pattern overrides.
- *
- * @param {?Record<string, object>} bindings A block's bindings from the metadata attribute.
- *
- * @return {boolean} Whether the block has the `__default` binding for pattern overrides.
- */
-export function hasPatternOverridesDefaultBinding( bindings ) {
-	return bindings?.[ DEFAULT_ATTRIBUTE ]?.source === PATTERN_OVERRIDES_SOURCE;
-}
-
-/**
- * Returns the bindings with the `__default` binding for pattern overrides
- * replaced with the full-set of supported attributes. e.g.:
- *
- * - bindings passed in: `{ __default: { source: 'core/pattern-overrides' } }`
- * - bindings returned: `{ content: { source: 'core/pattern-overrides' } }`
- *
- * @param {?Record<string, object>} bindings            A block's bindings from the metadata attribute.
- * @param {string[]}                supportedAttributes The block's attributes which are supported by block bindings.
- *
- * @return {Object} The bindings with default replaced for pattern overrides.
- */
-export function replacePatternOverridesDefaultBinding(
-	bindings,
-	supportedAttributes
-) {
-	// The `__default` binding currently only works for pattern overrides.
-	if ( hasPatternOverridesDefaultBinding( bindings ) ) {
-		const bindingsWithDefaults = {};
-		for ( const attributeName of supportedAttributes ) {
-			// If the block has mixed binding sources, retain any non pattern override bindings.
-			const bindingSource = bindings[ attributeName ]
-				? bindings[ attributeName ]
-				: { source: PATTERN_OVERRIDES_SOURCE };
-			bindingsWithDefaults[ attributeName ] = bindingSource;
-		}
-
-		return bindingsWithDefaults;
-	}
-
-	return bindings;
-}