@wordpress/block-library 9.48.0 → 10.0.0

package/src/cover/edit/inspector-controls.js

@@ -34,12 +34,21 @@ import { Link } from '@wordpress/ui';
 import { COVER_MIN_HEIGHT, mediaPosition } from '../shared';
 import { unlock } from '../../lock-unlock';
 import { useToolsPanelDropdownMenuProps } from '../../utils/hooks';
+import {
+	getActiveDimensionValue,
+	getDimensionResetAttributes,
+	getDimensionUpdateAttributes,
+	getStyleStateKey,
+} from '../../utils/style-state';
 import { DEFAULT_MEDIA_SIZE_SLUG } from '../constants';
 import PosterImage from '../../utils/poster-image';
 
-const { cleanEmptyObject, ResolutionTool, HTMLElementControl } = unlock(
-	blockEditorPrivateApis
-);
+const {
+	cleanEmptyObject,
+	isDefaultBlockStyleState,
+	ResolutionTool,
+	HTMLElementControl,
+} = unlock( blockEditorPrivateApis );
 
 function CoverHeightInput( {
 	onChange,
@@ -124,20 +133,45 @@ export default function CoverInspectorControls( {
 	const sizeSlug = attributes.sizeSlug || DEFAULT_MEDIA_SIZE_SLUG;
 
 	const { gradientValue, setGradient } = __experimentalUseGradient();
-	const { imageSizes, hasSelectedStyleState } = useSelect(
+	const { imageSizes, selectedStyleState } = useSelect(
 		( select ) => {
-			const {
-				getSettings,
-				hasSelectedStyleState: hasSelectedBlockStyleState,
-			} = unlock( select( blockEditorStore ) );
+			const { getSettings, getSelectedBlockStyleState } = unlock(
+				select( blockEditorStore )
+			);
 
 			return {
 				imageSizes: getSettings()?.imageSizes,
-				hasSelectedStyleState: hasSelectedBlockStyleState( clientId ),
+				selectedStyleState: getSelectedBlockStyleState( clientId ),
 			};
 		},
 		[ clientId ]
 	);
+	const hasSelectedStyleState =
+		! isDefaultBlockStyleState( selectedStyleState );
+	const selectedStyleStateKey = getStyleStateKey( selectedStyleState );
+	const stateMinHeight = getActiveDimensionValue( {
+		attributes,
+		selectedState: selectedStyleState,
+		hasSelectedStyleState,
+		attributeKey: 'minHeight',
+		styleKey: 'minHeight',
+		rootValue: undefined,
+	} );
+	const [ stateMinHeightValue, stateMinHeightUnit ] =
+		parseQuantityAndUnitFromRawValue( stateMinHeight || '' );
+	const activeMinHeight = hasSelectedStyleState
+		? stateMinHeightValue
+		: minHeight;
+	const activeMinHeightUnit = hasSelectedStyleState
+		? stateMinHeightUnit || minHeightUnit
+		: minHeightUnit;
+	const activeAspectRatio = getActiveDimensionValue( {
+		attributes,
+		selectedState: selectedStyleState,
+		hasSelectedStyleState,
+		attributeKey: 'aspectRatio',
+		rootValue: attributes?.style?.dimensions?.aspectRatio,
+	} );
 
 	const image = useSelect(
 		( select ) =>
@@ -203,6 +237,52 @@ export default function CoverInspectorControls( {
 	const showOverlayControls =
 		colorGradientSettings.hasColorsOrGradients && ! hasSelectedStyleState;
 
+	const setMinHeightAttributes = ( nextMinHeight, nextUnit ) => {
+		if ( hasSelectedStyleState ) {
+			setAttributes(
+				getDimensionUpdateAttributes( {
+					style: attributes.style,
+					selectedState: selectedStyleState,
+					hasSelectedStyleState,
+					nextDimensions: {
+						minHeight:
+							nextMinHeight === undefined
+								? undefined
+								: `${ nextMinHeight }${
+										nextUnit || activeMinHeightUnit || 'px'
+								  }`,
+						aspectRatio: undefined,
+					},
+				} )
+			);
+			return;
+		}
+
+		setAttributes( {
+			minHeight: nextMinHeight,
+			style: cleanEmptyObject( {
+				...attributes?.style,
+				dimensions: {
+					...attributes?.style?.dimensions,
+					aspectRatio: undefined, // Reset aspect ratio when minHeight is set.
+				},
+			} ),
+		} );
+	};
+
+	const getResetMinHeightAttributes = ( attrs = attributes ) => {
+		return getDimensionResetAttributes( {
+			style: attrs.style,
+			selectedState: selectedStyleState,
+			hasSelectedStyleState,
+			keys: [ 'minHeight' ],
+			defaultAttributes: {
+				minHeight: undefined,
+				minHeightUnit: undefined,
+			},
+		} );
+	};
+
 	const dropdownMenuProps = useToolsPanelDropdownMenuProps();
 
 	return (
@@ -401,53 +481,43 @@ export default function CoverInspectorControls( {
 					</ToolsPanelItem>
 				</InspectorControls>
 			) }
-			{ ! hasSelectedStyleState && (
-				<InspectorControls group="dimensions">
-					<ToolsPanelItem
-						className="single-column"
-						hasValue={ () => !! minHeight }
-						label={ __( 'Minimum height' ) }
-						onDeselect={ () =>
-							setAttributes( {
-								minHeight: undefined,
-								minHeightUnit: undefined,
-							} )
+			<InspectorControls group="dimensions">
+				<ToolsPanelItem
+					key={ selectedStyleStateKey }
+					className="single-column"
+					hasValue={ () => !! activeMinHeight }
+					label={ __( 'Minimum height' ) }
+					onDeselect={ () =>
+						setAttributes( getResetMinHeightAttributes() )
+					}
+					resetAllFilter={ getResetMinHeightAttributes }
+					isShownByDefault
+					panelId={ clientId }
+				>
+					<CoverHeightInput
+						value={ activeAspectRatio ? '' : activeMinHeight }
+						unit={ activeMinHeightUnit }
+						onChange={ ( newMinHeight ) =>
+							setMinHeightAttributes( newMinHeight )
 						}
-						resetAllFilter={ () => ( {
-							minHeight: undefined,
-							minHeightUnit: undefined,
-						} ) }
-						isShownByDefault
-						panelId={ clientId }
-					>
-						<CoverHeightInput
-							value={
-								attributes?.style?.dimensions?.aspectRatio
-									? ''
-									: minHeight
-							}
-							unit={ minHeightUnit }
-							onChange={ ( newMinHeight ) =>
-								setAttributes( {
-									minHeight: newMinHeight,
-									style: cleanEmptyObject( {
-										...attributes?.style,
-										dimensions: {
-											...attributes?.style?.dimensions,
-											aspectRatio: undefined, // Reset aspect ratio when minHeight is set.
-										},
-									} ),
-								} )
-							}
-							onUnitChange={ ( nextUnit ) =>
-								setAttributes( {
-									minHeightUnit: nextUnit,
-								} )
+						onUnitChange={ ( nextUnit ) => {
+							if ( hasSelectedStyleState ) {
+								if ( activeMinHeight !== undefined ) {
+									setMinHeightAttributes(
+										activeMinHeight,
+										nextUnit
+									);
+								}
+								return;
 							}
-						/>
-					</ToolsPanelItem>
-				</InspectorControls>
-			) }
+
+							setAttributes( {
+								minHeightUnit: nextUnit,
+							} );
+						} }
+					/>
+				</ToolsPanelItem>
+			</InspectorControls>
 			<InspectorControls group="advanced">
 				<HTMLElementControl
 					tagName={ tagName }

package/src/cover/test/edit.js

@@ -39,6 +39,50 @@ const disabledColorSettings = {
 	disableCustomGradients: true,
 };
 
+/**
+ * Runs `callback` with `requestAnimationFrame` callbacks flushed on a microtask
+ * ahead of any pending `setTimeout( 0 )` timers, then restores the original.
+ *
+ * In a browser, Ariakit normalizes the matrix's roving tabindex in a
+ * `requestAnimationFrame` before `useFocusOnMount`'s `setTimeout( 0 )` focuses
+ * the active (center) cell, so opening the dropdown leaves the content position
+ * untouched. JSDOM implements `requestAnimationFrame` as a ~16ms timer, which
+ * inverts the ordering and would otherwise focus and select the first DOM cell.
+ *
+ * @param {() => ( Promise< unknown > | unknown )} callback
+ * @return {Promise< unknown >} Resolves with the callback's return value.
+ */
+async function withAnimationFramesBeforeTimers( callback ) {
+	const originalRequestAnimationFrame = global.requestAnimationFrame;
+
+	let flushing = false;
+	global.requestAnimationFrame = ( frameCallback ) => {
+		// Frames scheduled while flushing fall back to the real implementation
+		// so self-rescheduling loops (e.g. Popover's Floating UI `autoUpdate`)
+		// don't spin forever on the microtask queue.
+		if ( flushing ) {
+			return originalRequestAnimationFrame( frameCallback );
+		}
+
+		queueMicrotask( () => {
+			flushing = true;
+			try {
+				frameCallback( performance.now() );
+			} finally {
+				flushing = false;
+			}
+		} );
+
+		return 0;
+	};
+
+	try {
+		return await callback();
+	} finally {
+		global.requestAnimationFrame = originalRequestAnimationFrame;
+	}
+}
+
 async function setup( attributes, useCoreBlocks, customSettings ) {
 	const testBlock = { name: 'core/cover', attributes };
 	const settings = customSettings || defaultSettings;
@@ -149,8 +193,13 @@ describe( 'Cover block', () => {
 			await setup();
 			await createAndSelectBlock();
 
-			await userEvent.click(
-				screen.getByLabelText( 'Change content position' )
+			// Open the matrix dropdown with browser-like frame ordering so
+			// focus-on-mount lands on the active cell instead of dirtying the
+			// content position.
+			await withAnimationFramesBeforeTimers( () =>
+				userEvent.click(
+					screen.getByLabelText( 'Change content position' )
+				)
 			);
 
 			expect( screen.getByLabelText( 'Block: Cover' ) ).not.toHaveClass(

package/src/details/README.md

@@ -0,0 +1,65 @@
+# Details
+
+<!-- START TOKEN(Autogenerated block API docs) -->
+Hide and show additional content.
+
+- **Name:** `core/details`
+- **Category:** [text](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/)
+- **API Version:** [3](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-api-versions/)
+- **Block Type:** [Hybrid](https://developer.wordpress.org/block-editor/getting-started/fundamentals/static-dynamic-rendering/) (static save + server enhancements)
+- **Keywords:** `summary`, `toggle`, `disclosure`
+
+## 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 |
+|-----------|------|---------|-------------|
+| `showContent` | `boolean` | `false` | — |
+| `summary` | `rich-text` | — | [Source](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#value-source): `rich-text`. [Selector](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#value-source): `summary`. [Role](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#role): `content` |
+| `name` | `string` | — | [Source](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#value-source): `attribute`. [Selector](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#value-source): `.wp-block-details`. [HTML attr](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#attribute-source): `name` |
+| `placeholder` | `string` | — | — |
+
+## Supports
+
+_Defined via the [`supports`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/) property in block.json._
+
+- [`align`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#align): `"wide"`, `"full"`
+- [`anchor`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#anchor): `true`
+- [`color`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#color):
+  - [`gradients`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#color-gradients): `true`
+  - [`link`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#color-link): `true`
+- [`html`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#html): `false`
+- [`spacing`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#spacing):
+  - `margin`: `true`
+  - `padding`: `true`
+  - `blockGap`: `true`
+- [`typography`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#typography):
+  - [`fontSize`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#typography-fontsize): `true`
+  - [`lineHeight`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#typography-lineheight): `true`
+- [`layout`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#layout):
+  - [`allowEditing`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#layout-allowediting): `false`
+- [`interactivity`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#interactivity):
+  - `clientNavigation`: `true`
+- [`allowedBlocks`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#allowedblocks): `true`
+
+## Block Markup
+
+This is a [**hybrid block**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/static-dynamic-rendering/). It saves static markup that the server may enhance during rendering.
+
+```html
+<!-- wp:details {"summary":"Details Summary"} -->
+<details class="wp-block-details"><summary>Details Summary</summary>
+	<!-- wp:paragraph {"placeholder":"Type / to add a hidden block"} -->
+	<p>Details Content</p>
+	<!-- /wp:paragraph -->
+</details>
+<!-- /wp:details -->
+```
+
+## Source
+
+- [block.json](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/details/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/details/) — browse `edit.js`, `save.js`, `index.php`, and more.
+
+<!-- END TOKEN(Autogenerated block API docs) -->

package/src/details/edit.js

@@ -105,7 +105,6 @@ function DetailsEdit( { attributes, setAttributes, clientId } ) {
 			</InspectorControls>
 			<InspectorControls group="advanced">
 				<TextControl
-					__next40pxDefaultSize
 					label={ __( 'Name attribute' ) }
 					value={ name || '' }
 					onChange={ ( newName ) =>

package/src/editor.scss

@@ -49,8 +49,6 @@
 @use "./social-links/editor.scss" as *;
 @use "./spacer/editor.scss" as *;
 @use "./table/editor.scss" as *;
-@use "./tab-list/editor.scss" as *;
-@use "./tab/editor.scss" as *;
 @use "./template-part/editor.scss" as *;
 @use "./term-template/editor.scss" as *;
 @use "./text-columns/editor.scss" as *;

package/src/embed/README.md

@@ -0,0 +1,56 @@
+# Embed
+
+<!-- START TOKEN(Autogenerated block API docs) -->
+Add a block that displays content pulled from other sites, like Twitter or YouTube.
+
+- **Name:** `core/embed`
+- **Category:** [embed](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-embed/)
+- **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 |
+|-----------|------|---------|-------------|
+| `url` | `string` | — | [Role](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#role): `content` |
+| `caption` | `rich-text` | — | [Source](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#value-source): `rich-text`. [Selector](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#value-source): `figcaption`. [Role](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#role): `content` |
+| `type` | `string` | — | [Role](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#role): `content` |
+| `providerNameSlug` | `string` | — | [Role](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#role): `content` |
+| `allowResponsive` | `boolean` | `true` | — |
+| `responsive` | `boolean` | `false` | [Role](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#role): `content` |
+| `previewable` | `boolean` | `true` | [Role](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#role): `content` |
+
+## 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): `true`
+- [`spacing`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#spacing):
+  - `margin`: `true`
+- [`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:embed {"url":"https://example.com/"} -->
+<figure class="wp-block-embed">
+    <div class="wp-block-embed__wrapper">
+        https://example.com/
+    </div>
+    <figcaption class="wp-element-caption">Embedded content from an example URL</figcaption>
+</figure>
+<!-- /wp:embed -->
+```
+
+## Source
+
+- [block.json](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/embed/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/embed/) — browse `edit.js`, `save.js`, `index.php`, and more.
+
+<!-- END TOKEN(Autogenerated block API docs) -->

package/src/file/README.md

@@ -0,0 +1,60 @@
+# File
+
+<!-- START TOKEN(Autogenerated block API docs) -->
+Add a link to a downloadable file.
+
+- **Name:** `core/file`
+- **Category:** [media](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-media/)
+- **API Version:** [3](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-api-versions/)
+- **Block Type:** [Hybrid](https://developer.wordpress.org/block-editor/getting-started/fundamentals/static-dynamic-rendering/) (static save + server enhancements)
+- **Keywords:** `document`, `pdf`, `download`
+
+## 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 |
+|-----------|------|---------|-------------|
+| `id` | `number` | — | — |
+| `blob` | `string` | — | [Role](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#role): `local` |
+| `href` | `string` | — | [Role](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#role): `content` |
+| `fileId` | `string` | — | [Source](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#value-source): `attribute`. [Selector](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#value-source): `a:not([download])`. [HTML attr](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#attribute-source): `id` |
+| `fileName` | `rich-text` | — | [Source](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#value-source): `rich-text`. [Selector](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#value-source): `a:not([download])`. [Role](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#role): `content` |
+| `textLinkHref` | `string` | — | [Source](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#value-source): `attribute`. [Selector](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#value-source): `a:not([download])`. [HTML attr](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#attribute-source): `href`. [Role](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#role): `content` |
+| `textLinkTarget` | `string` | — | [Source](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#value-source): `attribute`. [Selector](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#value-source): `a:not([download])`. [HTML attr](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#attribute-source): `target` |
+| `showDownloadButton` | `boolean` | `true` | — |
+| `downloadButtonText` | `rich-text` | — | [Source](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#value-source): `rich-text`. [Selector](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#value-source): `a[download]`. [Role](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#role): `content` |
+| `displayPreview` | `boolean` | — | — |
+| `previewHeight` | `number` | `600` | — |
+
+## 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): `true`
+- [`spacing`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#spacing):
+  - `margin`: `true`
+  - `padding`: `true`
+- [`color`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#color):
+  - [`gradients`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#color-gradients): `true`
+  - [`link`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#color-link): `true`
+  - [`text`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#color-text): `false`
+- [`interactivity`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#interactivity): `true`
+
+## Block Markup
+
+This is a [**hybrid block**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/static-dynamic-rendering/). It saves static markup that the server may enhance during rendering.
+
+```html
+<!-- wp:file {"showDownloadButton":true,"previewHeight":600} -->
+<!-- Content... -->
+<!-- /wp:file -->
+```
+
+## Source
+
+- [block.json](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/file/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/file/) — browse `edit.js`, `save.js`, `index.php`, and more.
+
+<!-- END TOKEN(Autogenerated block API docs) -->

package/src/file/edit.js

@@ -23,9 +23,9 @@ import {
 	store as blockEditorStore,
 	__experimentalGetElementClassName,
 } from '@wordpress/block-editor';
-import { useEffect, useState } from '@wordpress/element';
+import { useState } from '@wordpress/element';
 import { useCopyToClipboard } from '@wordpress/compose';
-import { __, _x } from '@wordpress/i18n';
+import { __ } from '@wordpress/i18n';
 import { file as icon } from '@wordpress/icons';
 import { store as coreStore } from '@wordpress/core-data';
 import { store as noticesStore } from '@wordpress/notices';
@@ -90,8 +90,7 @@ function FileEdit( { attributes, isSelected, setAttributes, clientId } ) {
 	);
 
 	const { createErrorNotice } = useDispatch( noticesStore );
-	const { toggleSelection, __unstableMarkNextChangeAsNotPersistent } =
-		useDispatch( blockEditorStore );
+	const { toggleSelection } = useDispatch( blockEditorStore );
 
 	useUploadMediaFromBlobURL( {
 		url: temporaryURL,
@@ -99,18 +98,6 @@ function FileEdit( { attributes, isSelected, setAttributes, clientId } ) {
 		onError: onUploadError,
 	} );
 
-	// Note: Handle setting a default value for `downloadButtonText` via HTML API
-	// when it supports replacing text content for HTML tags.
-	useEffect( () => {
-		if ( RichText.isEmpty( downloadButtonText ) ) {
-			__unstableMarkNextChangeAsNotPersistent();
-			setAttributes( {
-				downloadButtonText: _x( 'Download', 'button label' ),
-			} );
-		}
-		// This effect should only run on mount.
-	}, [] );
-
 	function onSelectFile( newMedia ) {
 		if ( ! newMedia || ! newMedia.url ) {
 			// Reset attributes.

package/src/file/index.js

@@ -14,6 +14,7 @@ import edit from './edit';
 import metadata from './block.json';
 import save from './save';
 import transforms from './transforms';
+import variations from './variations';
 import { unlock } from '../lock-unlock';
 
 const { fieldsKey, formKey } = unlock( blocksPrivateApis );
@@ -34,6 +35,7 @@ export const settings = {
 	deprecated,
 	edit,
 	save,
+	variations,
 };
 
 if ( window.__experimentalContentOnlyInspectorFields ) {

package/src/file/transforms.js

@@ -5,8 +5,12 @@ import { createBlobURL } from '@wordpress/blob';
 import { createBlock } from '@wordpress/blocks';
 import { select } from '@wordpress/data';
 import { store as coreStore } from '@wordpress/core-data';
+import { _x } from '@wordpress/i18n';
 import { getFilename } from '@wordpress/url';
 
+// Transforms bypass the default variation, so set the localized default here.
+const downloadButtonText = _x( 'Download', 'button label' );
+
 const transforms = {
 	from: [
 		{
@@ -47,6 +51,7 @@ const transforms = {
 							createBlock( 'core/file', {
 								blob: blobURL,
 								fileName: file.name,
+								downloadButtonText,
 							} )
 						);
 					}
@@ -57,41 +62,17 @@ const transforms = {
 		},
 		{
 			type: 'block',
-			blocks: [ 'core/audio' ],
-			transform: ( attributes ) => {
-				return createBlock( 'core/file', {
-					href: attributes.src,
-					fileName: attributes.caption,
-					textLinkHref: attributes.src,
-					id: attributes.id,
-					anchor: attributes.anchor,
-				} );
-			},
-		},
-		{
-			type: 'block',
-			blocks: [ 'core/video' ],
-			transform: ( attributes ) => {
-				return createBlock( 'core/file', {
-					href: attributes.src,
-					fileName: attributes.caption,
-					textLinkHref: attributes.src,
-					id: attributes.id,
-					anchor: attributes.anchor,
-				} );
-			},
-		},
-		{
-			type: 'block',
-			blocks: [ 'core/image' ],
+			blocks: [ 'core/audio', 'core/video', 'core/image' ],
 			transform: ( attributes ) => {
+				// Audio/Video use `src`, Image uses `url`.
+				const href = attributes.src ?? attributes.url;
 				return createBlock( 'core/file', {
-					href: attributes.url,
-					fileName:
-						attributes.caption || getFilename( attributes.url ),
-					textLinkHref: attributes.url,
+					href,
+					fileName: attributes.caption || getFilename( href ),
+					textLinkHref: href,
 					id: attributes.id,
 					anchor: attributes.anchor,
+					downloadButtonText,
 				} );
 			},
 		},

package/src/file/variations.js

@@ -0,0 +1,17 @@
+/**
+ * WordPress dependencies
+ */
+import { _x } from '@wordpress/i18n';
+
+const variations = [
+	{
+		name: 'default',
+		isDefault: true,
+		// Translatable defaults can't live in `block.json`, so set it here.
+		attributes: {
+			downloadButtonText: _x( 'Download', 'button label' ),
+		},
+	},
+];
+
+export default variations;