@wordpress/block-library 9.48.0 → 10.0.0

package/src/terms-query/README.md

@@ -0,0 +1,58 @@
+# Terms Query
+
+<!-- START TOKEN(Autogenerated block API docs) -->
+An advanced block that allows displaying taxonomy terms based on different query parameters and visual configurations.
+
+- **Name:** `core/terms-query`
+- **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/)
+- **API Version:** [3](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-api-versions/)
+- **Block Type:** [Static](https://developer.wordpress.org/block-editor/getting-started/fundamentals/static-dynamic-rendering/) (saved in post content)
+- **Keywords:** `terms`, `taxonomy`, `categories`, `tags`, `list`
+
+## Attributes
+
+_Defined via the [`attributes`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/) property in block.json._
+
+| Attribute | [Type](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#type-validation) | [Default](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#default-value) | Description |
+|-----------|------|---------|-------------|
+| `termQuery` | `object` | `{"perPage":10,"taxonomy":"category","order":"asc","orderBy":"name","include":[],"hideEmpty":true,"showNested":false,"inherit":false}` | — |
+| `tagName` | `string` | `"div"` | — |
+
+## Supports
+
+_Defined via the [`supports`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/) property in block.json._
+
+- [`anchor`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#anchor): `true`
+- [`align`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#align): `"wide"`, `"full"`
+- [`html`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#html): `false`
+- [`layout`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#layout): `true`
+- [`interactivity`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#interactivity): `true`
+
+## Context
+
+_Defined via the [`usesContext` and `providesContext`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-context/) properties in block.json._
+
+**Uses context:**
+
+- `templateSlug`
+
+**Provides context:**
+
+- `termQuery` → attribute `termQuery`
+
+## Block Markup
+
+This is a [**static block**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/static-dynamic-rendering/). The markup is saved directly in the post content.
+
+```html
+<!-- wp:terms-query -->
+<div class="wp-block-terms-query"></div>
+<!-- /wp:terms-query -->
+```
+
+## Source
+
+- [block.json](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/terms-query/block.json) ([reference](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/))
+- [Source directory](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/terms-query/) — browse `edit.js`, `save.js`, `index.php`, and more.
+
+<!-- END TOKEN(Autogenerated block API docs) -->

package/src/text-columns/README.md

@@ -0,0 +1,51 @@
+# Text Columns (deprecated)
+
+<!-- START TOKEN(Autogenerated block API docs) -->
+<div class="callout callout-alert">This block is <strong>deprecated</strong> and should not be used in new content. Please use the Columns block instead.</div>
+
+- **Name:** `core/text-columns`
+- **Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/)
+- **API Version:** [3](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-api-versions/)
+- **Block Type:** [Static](https://developer.wordpress.org/block-editor/getting-started/fundamentals/static-dynamic-rendering/) (saved in post content)
+
+## Attributes
+
+_Defined via the [`attributes`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/) property in block.json._
+
+| Attribute | [Type](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#type-validation) | [Default](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#default-value) | Description |
+|-----------|------|---------|-------------|
+| `content` | `array` | `[{},{}]` | [Source](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#value-source): `query`. [Selector](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#value-source): `p` |
+| `columns` | `number` | `2` | — |
+| `width` | `string` | — | — |
+
+## Supports
+
+_Defined via the [`supports`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/) property in block.json._
+
+- [`inserter`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#inserter): `false`
+- [`interactivity`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#interactivity):
+  - `clientNavigation`: `true`
+
+## Block Markup
+
+This is a [**static block**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/static-dynamic-rendering/). The markup is saved directly in the post content.
+
+```html
+<!-- wp:core/text-columns {"width":"center"} -->
+<div class="wp-block-text-columns aligncenter columns-2">
+    <div class="wp-block-column">
+        <p>One</p>
+    </div>
+    <div class="wp-block-column">
+        <p>Two</p>
+    </div>
+</div>
+<!-- /wp:core/text-columns -->
+```
+
+## Source
+
+- [block.json](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/text-columns/block.json) ([reference](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/))
+- [Source directory](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/text-columns/) — browse `edit.js`, `save.js`, `index.php`, and more.
+
+<!-- END TOKEN(Autogenerated block API docs) -->

package/src/utils/style-state.js

@@ -0,0 +1,151 @@
+/**
+ * WordPress dependencies
+ */
+import { privateApis as blockEditorPrivateApis } from '@wordpress/block-editor';
+
+/**
+ * Internal dependencies
+ */
+import { unlock } from '../lock-unlock';
+
+const { cleanEmptyObject, getStyleForState, setStyleForState } = unlock(
+	blockEditorPrivateApis
+);
+
+function getStateStyle( style, selectedState ) {
+	return getStyleForState( style, selectedState ) || {};
+}
+
+function getMappedDimensions( dimensions, dimensionKeyMap = {} ) {
+	return Object.fromEntries(
+		Object.entries( dimensions ).map( ( [ key, value ] ) => [
+			dimensionKeyMap[ key ] || key,
+			value,
+		] )
+	);
+}
+
+function getControlledDimensions( dimensions, dimensionKeys ) {
+	if ( ! dimensionKeys ) {
+		return dimensions;
+	}
+
+	return Object.fromEntries(
+		dimensionKeys.map( ( key ) => [ key, dimensions[ key ] ] )
+	);
+}
+
+export function getStyleStateKey( selectedState ) {
+	return [
+		selectedState?.viewport || 'default',
+		selectedState?.pseudo || 'default',
+	].join( ':' );
+}
+
+export function getStateDimensions( style, selectedState ) {
+	return getStateStyle( style, selectedState )?.dimensions || {};
+}
+
+export function getActiveDimensionValue( options = {} ) {
+	const {
+		attributes = {},
+		style = attributes?.style,
+		selectedState,
+		hasSelectedStyleState,
+		attributeKey,
+		styleKey = attributeKey,
+		rootValue,
+	} = options;
+
+	if ( hasSelectedStyleState ) {
+		return getStateDimensions( style, selectedState )?.[ styleKey ];
+	}
+
+	if ( Object.hasOwn( options, 'rootValue' ) ) {
+		return rootValue;
+	}
+
+	return attributes?.[ attributeKey ];
+}
+
+export function setStateDimensions( style, selectedState, nextDimensions ) {
+	const stateStyle = getStateStyle( style, selectedState );
+
+	return setStyleForState(
+		style,
+		selectedState,
+		cleanEmptyObject( {
+			...stateStyle,
+			dimensions: cleanEmptyObject( {
+				...stateStyle?.dimensions,
+				...nextDimensions,
+			} ),
+		} )
+	);
+}
+
+export function getDimensionUpdateAttributes( {
+	style,
+	selectedState,
+	hasSelectedStyleState,
+	nextDimensions,
+	dimensionKeyMap,
+	dimensionKeys,
+} ) {
+	const controlledDimensions = getControlledDimensions(
+		nextDimensions,
+		dimensionKeys
+	);
+
+	if ( ! hasSelectedStyleState ) {
+		return controlledDimensions;
+	}
+
+	return {
+		style: setStateDimensions(
+			style,
+			selectedState,
+			getMappedDimensions( controlledDimensions, dimensionKeyMap )
+		),
+	};
+}
+
+export function resetDimensions( style, keys ) {
+	const dimensionsReset = Object.fromEntries(
+		keys.map( ( key ) => [ key, undefined ] )
+	);
+
+	return cleanEmptyObject( {
+		...style,
+		dimensions: cleanEmptyObject( {
+			...style?.dimensions,
+			...dimensionsReset,
+		} ),
+	} );
+}
+
+export function resetStateDimensions( style, selectedState, keys ) {
+	return setStyleForState(
+		style,
+		selectedState,
+		resetDimensions( getStateStyle( style, selectedState ), keys )
+	);
+}
+
+export function getDimensionResetAttributes( {
+	attributes = {},
+	style = attributes?.style,
+	selectedState,
+	hasSelectedStyleState,
+	keys,
+	defaultAttributes = {},
+} ) {
+	return {
+		...( hasSelectedStyleState
+			? {}
+			: { ...attributes, ...defaultAttributes } ),
+		style: hasSelectedStyleState
+			? resetStateDimensions( style, selectedState, keys )
+			: resetDimensions( style, keys ),
+	};
+}

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',
+					},
+				},
+			},
+		} );
+	} );
+} );