@wordpress/block-library 9.48.0 → 10.0.0

package/src/search/edit.js

@@ -35,6 +35,7 @@ import { useInstanceId } from '@wordpress/compose';
 import { Icon, search } from '@wordpress/icons';
 import { __, sprintf } from '@wordpress/i18n';
 import { __unstableStripHTML as stripHTML } from '@wordpress/dom';
+import { speak } from '@wordpress/a11y';
 
 /**
  * Internal dependencies
@@ -47,6 +48,20 @@ import {
 } from './utils.js';
 import { useToolsPanelDropdownMenuProps } from '../utils/hooks';
 
+// Help text describing each wrapper element option. Kept local to the block
+// because the choices and their guidance are specific to the Search block.
+const TAG_NAME_MESSAGES = {
+	'': __(
+		'Lets the theme decide. Uses the <search> landmark element if the theme opts in, otherwise a <form>.'
+	),
+	search: __(
+		'Wraps the block in a <search> landmark, announced as a search region by assistive technologies.'
+	),
+	form: __(
+		'Uses a <form role="search"> wrapper for backward compatibility with existing theme styles.'
+	),
+};
+
 // Used to calculate border radius adjustment to avoid "fat" corners when
 // button is placed inside wrapper.
 const DEFAULT_INNER_PADDING = '4px';
@@ -70,6 +85,7 @@ export default function SearchEdit( {
 		buttonText,
 		buttonPosition,
 		buttonUseIcon,
+		tagName,
 		style,
 	} = attributes;
 
@@ -477,6 +493,31 @@ export default function SearchEdit( {
 					</ToolsPanelItem>
 				</ToolsPanel>
 			</InspectorControls>
+			<InspectorControls group="advanced">
+				<SelectControl
+					__next40pxDefaultSize
+					label={ __( 'HTML element' ) }
+					value={ tagName ?? '' }
+					options={ [
+						{ label: __( 'Default' ), value: '' },
+						{ label: '<search>', value: 'search' },
+						{ label: '<form>', value: 'form' },
+					] }
+					onChange={ ( value ) => {
+						setAttributes( { tagName: value } );
+						// The help text is updated via aria-describedby, which
+						// is not re-announced while focus remains on the select.
+						// Announce the new description so it is not missed.
+						// speak() strips HTML-like tags, which would drop the
+						// element names (e.g. <search>) entirely. Remove only the
+						// angle brackets so the words are retained when spoken.
+						speak(
+							TAG_NAME_MESSAGES[ value ].replace( /[<>]/g, '' )
+						);
+					} }
+					help={ TAG_NAME_MESSAGES[ tagName ?? '' ] }
+				/>
+			</InspectorControls>
 		</>
 	);
 
@@ -559,64 +600,74 @@ export default function SearchEdit( {
 		typographyProps.className
 	);
 
+	// Reflect an explicit <search> choice in the editor markup so wrapper
+	// styles match the front end. The <form> and theme-deferred default keep
+	// the historical <div> to avoid nesting a live <form> in the editor.
+	const Wrapper = 'search' === tagName ? 'search' : 'div';
+
 	return (
-		<div { ...blockProps }>
+		<>
 			{ controls }
-
-			{ showLabel && (
-				<RichText
-					identifier="label"
-					className={ labelClassnames }
-					aria-label={ __( 'Label text' ) }
-					placeholder={ __( 'Add label…' ) }
-					withoutInteractiveFormatting
-					value={ label }
-					onChange={ ( html ) => setAttributes( { label: html } ) }
-					style={ typographyProps.style }
-				/>
-			) }
-
-			<ResizableBox
-				size={ {
-					width:
-						width === undefined
-							? 'auto'
-							: `${ width }${ widthUnit }`,
-					height: 'auto',
-				} }
-				className={ clsx(
-					'wp-block-search__inside-wrapper',
-					isButtonPositionInside ? borderProps.className : undefined
-				) }
-				style={ getWrapperStyles() }
-				minWidth={ MIN_WIDTH }
-				enable={ getResizableSides() }
-				onResizeStart={ ( event, direction, elt ) => {
-					setAttributes( {
-						width: parseInt( elt.offsetWidth, 10 ),
-						widthUnit: 'px',
-					} );
-					toggleSelection( false );
-				} }
-				onResizeStop={ ( event, direction, elt, delta ) => {
-					setAttributes( {
-						width: parseInt( width + delta.width, 10 ),
-					} );
-					toggleSelection( true );
-				} }
-				showHandle={ isSelected }
-			>
-				{ ( isButtonPositionInside ||
-					isButtonPositionOutside ||
-					hasOnlyButton ) && (
-					<>
-						{ renderTextField() }
-						{ renderButton() }
-					</>
+			<Wrapper { ...blockProps }>
+				{ showLabel && (
+					<RichText
+						identifier="label"
+						className={ labelClassnames }
+						aria-label={ __( 'Label text' ) }
+						placeholder={ __( 'Add label…' ) }
+						withoutInteractiveFormatting
+						value={ label }
+						onChange={ ( html ) =>
+							setAttributes( { label: html } )
+						}
+						style={ typographyProps.style }
+					/>
 				) }
 
-				{ hasNoButton && renderTextField() }
-			</ResizableBox>
-		</div>
+				<ResizableBox
+					size={ {
+						width:
+							width === undefined
+								? 'auto'
+								: `${ width }${ widthUnit }`,
+						height: 'auto',
+					} }
+					className={ clsx(
+						'wp-block-search__inside-wrapper',
+						isButtonPositionInside
+							? borderProps.className
+							: undefined
+					) }
+					style={ getWrapperStyles() }
+					minWidth={ MIN_WIDTH }
+					enable={ getResizableSides() }
+					onResizeStart={ ( event, direction, elt ) => {
+						setAttributes( {
+							width: parseInt( elt.offsetWidth, 10 ),
+							widthUnit: 'px',
+						} );
+						toggleSelection( false );
+					} }
+					onResizeStop={ ( event, direction, elt, delta ) => {
+						setAttributes( {
+							width: parseInt( width + delta.width, 10 ),
+						} );
+						toggleSelection( true );
+					} }
+					showHandle={ isSelected }
+				>
+					{ ( isButtonPositionInside ||
+						isButtonPositionOutside ||
+						hasOnlyButton ) && (
+						<>
+							{ renderTextField() }
+							{ renderButton() }
+						</>
+					) }
+
+					{ hasNoButton && renderTextField() }
+				</ResizableBox>
+			</Wrapper>
+		</>
 	);
 }

package/src/search/index.php

@@ -191,8 +191,32 @@ function render_block_core_search( $attributes ) {
 		';
 	}
 
+	/*
+	 * The semantic <search> landmark wrapper is opt-in to preserve back
+	 * compatibility with themes targeting <form role="search">. The block
+	 * exposes a per-instance HTML element selector with three values:
+	 *
+	 *   - 'search' forces the <search> wrapper
+	 *   - 'form'   forces the original <form role="search"> markup
+	 *   - empty    defers to the 'search-element' html5 sub-feature
+	 *              ( add_theme_support( 'html5', array( 'search-element' ) ) ),
+	 *              matching the opt-in added to get_search_form() in core
+	 */
+	$tag_name           = $attributes['tagName'] ?? '';
+	$use_search_element = 'search' === $tag_name || ( '' === $tag_name && current_theme_supports( 'html5', 'search-element' ) );
+
+	/*
+	 * Only the wrapper markup differs between the semantic <search> landmark
+	 * and the classic <form role="search">. Positional specifiers keep a
+	 * single argument list usable by both formats, since the action URL
+	 * precedes the wrapper attributes in the <search> variant.
+	 */
+	$format = $use_search_element
+		? '<search %2$s %3$s><form method="get" action="%1$s">%4$s</form></search>'
+		: '<form role="search" method="get" action="%1$s" %2$s %3$s>%4$s</form>';
+
 	return sprintf(
-		'<form role="search" method="get" action="%1s" %2s %3s>%4s</form>',
+		$format,
 		esc_url( home_url( '/' ) ),
 		$wrapper_attributes,
 		$form_directives,

package/src/separator/README.md

@@ -0,0 +1,62 @@
+# Separator
+
+<!-- START TOKEN(Autogenerated block API docs) -->
+Create a break between ideas or sections with a horizontal separator.
+
+- **Name:** `core/separator`
+- **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)
+- **Keywords:** `horizontal-line`, `hr`, `divider`
+
+## 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 |
+|-----------|------|---------|-------------|
+| `opacity` | `string` | `"alpha-channel"` | — |
+| `tagName` | `string` | `"hr"` | [Enum](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#enum-validation): `hr`, `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): `"center"`, `"wide"`, `"full"`
+- [`color`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#color):
+  - [`enableContrastChecker`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#color-enablecontrastchecker): `false`
+  - [`gradients`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#color-gradients): `true`
+  - [`background`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#color-background): `true`
+  - [`text`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#color-text): `false`
+- [`spacing`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#spacing):
+  - `margin`: `["top","bottom"]`
+- [`interactivity`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#interactivity):
+  - `clientNavigation`: `true`
+
+## Block Styles
+
+_Defined via the [`styles`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-styles/) property in block.json._
+
+| Style Name | Label | Default |
+|------------|-------|---------|
+| `default` | Default | Yes |
+| `wide` | Wide Line | No |
+| `dots` | Dots | No |
+
+## 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:separator -->
+<hr class="wp-block-separator has-alpha-channel-opacity"/>
+<!-- /wp:separator -->
+```
+
+## Source
+
+- [block.json](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/separator/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/separator/) — browse `edit.js`, `save.js`, `index.php`, and more.
+
+<!-- END TOKEN(Autogenerated block API docs) -->

package/src/shortcode/README.md

@@ -0,0 +1,44 @@
+# Shortcode
+
+<!-- START TOKEN(Autogenerated block API docs) -->
+Insert additional custom elements with a WordPress shortcode.
+
+- **Name:** `core/shortcode`
+- **Category:** [widgets](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/)
+- **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)
+
+## 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 |
+|-----------|------|---------|-------------|
+| `text` | `string` | — | [Source](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#value-source): `raw`. [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._
+
+- [`className`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#classname): `false`
+- [`customClassName`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#customclassname): `false`
+- [`html`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#html): `false`
+- `customCSS`: `false`
+- [`visibility`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#visibility): `false`
+
+## 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:core/shortcode -->
+[gallery ids="238,338"]
+<!-- /wp:core/shortcode -->
+```
+
+## Source
+
+- [block.json](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/shortcode/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/shortcode/) — browse `edit.js`, `save.js`, `index.php`, and more.
+
+<!-- END TOKEN(Autogenerated block API docs) -->

package/src/shortcode/transforms.js

@@ -53,12 +53,12 @@ const transforms = {
 		return getShortcodeFromTransforms().map( ( fromTransform ) => ( {
 			type: 'block',
 			blocks: [ fromTransform.blockName ],
-			isMatch: ( { text } ) => {
+			isMatch: ( { text = '' } ) => {
 				return []
 					.concat( fromTransform.tag )
 					.some( ( tag ) => isSingleShortcode( text, tag ) );
 			},
-			transform: ( { text } ) => {
+			transform: ( { text = '' } ) => {
 				return rawHandler( { HTML: `<p>${ text.trim() }</p>` } );
 			},
 		} ) );

package/src/site-logo/README.md

@@ -0,0 +1,72 @@
+# Site Logo
+
+<!-- START TOKEN(Autogenerated block API docs) -->
+Display an image to represent this site. Update this block and the changes apply everywhere.
+
+- **Name:** `core/site-logo`
+- **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:** [Dynamic](https://developer.wordpress.org/block-editor/getting-started/fundamentals/static-dynamic-rendering/) (server-rendered)
+
+## 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 |
+|-----------|------|---------|-------------|
+| `width` | `number` | — | — |
+| `isLink` | `boolean` | `true` | [Role](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#role): `content` |
+| `linkTarget` | `string` | `"_self"` | [Role](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#role): `content` |
+| `shouldSyncIcon` | `boolean` | — | — |
+
+## 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`
+- [`html`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#html): `false`
+- [`align`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#align): `true`
+- [`alignWide`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#alignwide): `false`
+- [`color`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#color):
+  - [`text`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#color-text): `false`
+  - [`background`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#color-background): `false`
+- [`spacing`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#spacing):
+  - `margin`: `true`
+  - `padding`: `true`
+- [`interactivity`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#interactivity):
+  - `clientNavigation`: `true`
+- [`filter`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#filter):
+  - [`duotone`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#filter-duotone): `true`
+
+## Block Styles
+
+_Defined via the [`styles`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-styles/) property in block.json._
+
+| Style Name | Label | Default |
+|------------|-------|---------|
+| `default` | Default | Yes |
+| `rounded` | Rounded | No |
+
+## CSS Selectors
+
+_Defined via the [`selectors`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-selectors/) property in block.json._
+
+- **filter**:
+  - duotone: `.wp-block-site-logo img, .wp-block-site-logo .components-placeholder__illustration, .wp-block-site-logo .components-placeholder::before`
+
+## Block Markup
+
+This is a [**dynamic block**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/static-dynamic-rendering/). It is rendered on the server and does not save HTML in post content.
+
+In post content, it is stored as a block comment:
+
+```html
+<!-- wp:site-logo /-->
+```
+
+## Source
+
+- [block.json](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/site-logo/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/site-logo/) — browse `edit.js`, `save.js`, `index.php`, and more.
+
+<!-- END TOKEN(Autogenerated block API docs) -->

package/src/site-logo/edit.js

@@ -75,7 +75,8 @@ const SiteLogo = ( {
 	const [ { naturalWidth, naturalHeight }, setNaturalSize ] = useState( {} );
 	const [ isEditingImage, setIsEditingImage ] = useState( false );
 	const cropButtonRef = useRef();
-	const { toggleSelection } = useDispatch( blockEditorStore );
+	const { toggleSelection, __unstableMarkNextChangeAsNotPersistent } =
+		useDispatch( blockEditorStore );
 	const dropdownMenuProps = useToolsPanelDropdownMenuProps();
 
 	// Check if we're in contentOnly mode
@@ -108,6 +109,7 @@ const SiteLogo = ( {
 		// fallen out of sync. This can happen if the toggle is saved in the `on` position,
 		// but changes are later made to the site icon in the Customizer.
 		if ( shouldSyncIcon && logoId !== iconId ) {
+			__unstableMarkNextChangeAsNotPersistent();
 			setAttributes( { shouldSyncIcon: false } );
 		}
 	}, [] );

package/src/site-tagline/README.md

@@ -0,0 +1,56 @@
+# Site Tagline
+
+<!-- START TOKEN(Autogenerated block API docs) -->
+Describe in a few words what this site is about. This is important for search results, sharing on social media, and gives overall clarity to visitors.
+
+- **Name:** `core/site-tagline`
+- **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:** [Dynamic](https://developer.wordpress.org/block-editor/getting-started/fundamentals/static-dynamic-rendering/) (server-rendered)
+- **Keywords:** `description`
+
+## 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 |
+|-----------|------|---------|-------------|
+| `level` | `number` | `0` | — |
+| `levelOptions` | `array` | `[0,1,2,3,4,5,6]` | — |
+
+## 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`
+- [`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`
+- [`contentRole`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#contentrole): `true`
+- [`spacing`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#spacing):
+  - `margin`: `true`
+  - `padding`: `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`
+  - [`textAlign`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#typography-textalign): `true`
+- [`interactivity`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#interactivity):
+  - `clientNavigation`: `true`
+
+## Block Markup
+
+This is a [**dynamic block**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/static-dynamic-rendering/). It is rendered on the server and does not save HTML in post content.
+
+In post content, it is stored as a block comment:
+
+```html
+<!-- wp:site-tagline /-->
+```
+
+## Source
+
+- [block.json](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/site-tagline/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/site-tagline/) — browse `edit.js`, `save.js`, `index.php`, and more.
+
+<!-- END TOKEN(Autogenerated block API docs) -->

package/src/site-title/README.md

@@ -0,0 +1,57 @@
+# Site Title
+
+<!-- START TOKEN(Autogenerated block API docs) -->
+Displays the name of this site. Update the block, and the changes apply everywhere it’s used. This will also appear in the browser title bar and in search results.
+
+- **Name:** `core/site-title`
+- **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:** [Dynamic](https://developer.wordpress.org/block-editor/getting-started/fundamentals/static-dynamic-rendering/) (server-rendered)
+
+## 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 |
+|-----------|------|---------|-------------|
+| `level` | `number` | `1` | — |
+| `levelOptions` | `array` | `[0,1,2,3,4,5,6]` | — |
+| `isLink` | `boolean` | `true` | [Role](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#role): `content` |
+| `linkTarget` | `string` | `"_self"` | [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): `"wide"`, `"full"`
+- [`html`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#html): `false`
+- [`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`
+- [`spacing`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#spacing):
+  - `padding`: `true`
+  - `margin`: `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`
+  - [`textAlign`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#typography-textalign): `true`
+- [`interactivity`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#interactivity):
+  - `clientNavigation`: `true`
+
+## Block Markup
+
+This is a [**dynamic block**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/static-dynamic-rendering/). It is rendered on the server and does not save HTML in post content.
+
+In post content, it is stored as a block comment:
+
+```html
+<!-- wp:site-title /-->
+```
+
+## Source
+
+- [block.json](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/site-title/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/site-title/) — browse `edit.js`, `save.js`, `index.php`, and more.
+
+<!-- END TOKEN(Autogenerated block API docs) -->

package/src/social-link/README.md

@@ -22,3 +22,67 @@ Starting from WordPress 6.9, it's possible to add custom social icons to your si
 
 * Pull Request that introduced custom social icons - [#70261](https://github.com/WordPress/gutenberg/pull/70261).
 * Developer Blog tutorial for custom social icons - [Registering custom social icons in WordPress 6.9](https://developer.wordpress.org/news/2025/08/registering-custom-social-icons-in-wordpress-6-9/).
+
+<!-- START TOKEN(Autogenerated block API docs) -->
+Display an icon linking to a social profile or site.
+
+- **Name:** `core/social-link`
+- **Category:** [widgets](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/)
+- **API Version:** [3](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-api-versions/)
+- **Block Type:** [Dynamic](https://developer.wordpress.org/block-editor/getting-started/fundamentals/static-dynamic-rendering/) (server-rendered)
+
+## Block Relationships
+
+**[Parent](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#parent) blocks (direct):**
+- [`core/social-links`](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/core-block-social-links/)
+
+## 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` |
+| `service` | `string` | — | — |
+| `label` | `string` | — | [Role](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/#role): `content` |
+| `rel` | `string` | — | — |
+
+## 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`
+- [`reusable`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#reusable): `false`
+- [`html`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#html): `false`
+- [`interactivity`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#interactivity):
+  - `clientNavigation`: `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:**
+
+- `openInNewTab`
+- `showLabels`
+- `iconColor`
+- `iconColorValue`
+- `iconBackgroundColor`
+- `iconBackgroundColorValue`
+
+## Block Markup
+
+This is a [**dynamic block**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/static-dynamic-rendering/). It is rendered on the server and does not save HTML in post content.
+
+In post content, it is stored as a block comment:
+
+```html
+<!-- wp:social-link {"service":"spotify","url":"https://example.com/"} /-->
+```
+
+## Source
+
+- [block.json](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/social-link/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/social-link/) — browse `edit.js`, `save.js`, `index.php`, and more.
+
+<!-- END TOKEN(Autogenerated block API docs) -->