Add Back to top block

docs/reference-guides/core-blocks.md

@@ -35,6 +35,15 @@ Add a user’s avatar. ([Source](https://github.com/WordPress/gutenberg/tree/tru
 -	**Supports:** align, color (~~background~~, ~~text~~), interactivity (clientNavigation), spacing (margin, padding), ~~alignWide~~, ~~html~~
 -	**Attributes:** isLink, linkTarget, size, userId
 
+## Back to top
+
+A link that takes you back to the top. ([Source](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/back-to-top))
+
+-	**Name:** core/back-to-top
+-	**Category:** design
+-	**Supports:** ~~html~~
+-	**Attributes:** text
+
 ## Pattern
 
 Reuse this design across your site. ([Source](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/block))

lib/blocks.php

@@ -15,6 +15,7 @@ function gutenberg_reregister_core_block_types() {
 		__DIR__ . '/../build/block-library/blocks/' => array(
 			'block_folders' => array(
 				'audio',
+				'back-to-top',
 				'button',
 				'buttons',
 				'freeform',
@@ -49,6 +50,7 @@ function gutenberg_reregister_core_block_types() {
 			'block_names'   => array(
 				'archives.php'                     => 'core/archives',
 				'avatar.php'                       => 'core/avatar',
+				'back-to-top.php'                  => 'core/back-to-top',
 				'block.php'                        => 'core/block',
 				'calendar.php'                     => 'core/calendar',
 				'categories.php'                   => 'core/categories',

packages/block-library/src/back-to-top/block.json

@@ -0,0 +1,18 @@
+{
+	"$schema": "https://schemas.wp.org/trunk/block.json",
+	"apiVersion": 3,
+	"name": "core/back-to-top",
+	"title": "Back to top",
+	"category": "design",
+	"description": "A link that takes you back to the top.",
+	"keywords": [ "top", "skip link" ],
+	"textdomain": "default",
+	"attributes": {
+		"text": {
+			"type": "string"
+		}
+	},
+	"supports": {
+		"html": false
+	}
+}

packages/block-library/src/back-to-top/edit.js

@@ -0,0 +1,23 @@
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import { useBlockProps, RichText } from '@wordpress/block-editor';
+
+export default function BackToTopEdit( { attributes, setAttributes } ) {
+	const { text } = attributes;
+	return (
+		<p { ...useBlockProps() }>
+			<RichText
+				tagName="a"
+				href="#wp-back-to-top"
+				aria-label={ __( 'Back to top link text' ) }
+				value={ text ? text : __( 'Back to top' ) }
+				withoutInteractiveFormatting={ true }
+				onChange={ ( newLinkText ) =>
+					setAttributes( { text: newLinkText } )
+				}
+			/>
+		</p>
+	);
+}

packages/block-library/src/back-to-top/index.js

@@ -0,0 +1,20 @@
+/**
+ * WordPress dependencies
+ */
+import { arrowUp as icon } from '@wordpress/icons';
+
+/**
+ * Internal dependencies
+ */
+import initBlock from '../utils/init-block';
+import edit from './edit';
+import metadata from './block.json';
+
+const { name } = metadata;
+export { metadata, name };
+export const settings = {
+	icon,
+	edit,
+};
+
+export const init = () => initBlock( { name, metadata, settings } );

packages/block-library/src/back-to-top/index.php

@@ -0,0 +1,89 @@
+<?php
+/**
+ * Server-side rendering of the `core/back-to-top` block.
+ *
+ * @package WordPress
+ */
+
+/**
+ * Renders the `core/back-to-top` block on the server.
+ *
+ * @param array $attributes Block attributes.
+ * @return string Return the back to top link.
+ */
+function render_block_core_back_to_top( $attributes ) {
+	$link_text          = isset( $attributes['text'] ) ? $attributes['text'] : __( 'Back to top' );
+	$wrapper_attributes = get_block_wrapper_attributes();
+
+	block_core_back_to_top_classic_fallback();
+
+	return sprintf(
+		'<p %1$s><a href="#wp-back-to-top">%2$s</a></p>',
+		$wrapper_attributes,
+		wp_kses_post( $link_text )
+	);
+}
+
+/**
+ * Registers the `core/back_to_top` block on the server.
+ */
+function register_block_core_back_to_top() {
+	register_block_type_from_metadata(
+		__DIR__ . '/back-to-top',
+		array(
+			'render_callback' => 'render_block_core_back_to_top',
+		)
+	);
+}
+add_action( 'init', 'register_block_core_back_to_top' );
+
+/**
+ * Adds the target id 'wp-back-to-top' to the top of the page, so that focus can be moved.
+ * Block themes: Add the target id if the back to top block exists on the page.
+ * Classic themes with 'wp_body_open()': Always add the target id.
+ */
+function block_core_back_to_top_target() {
+	echo '<div id="wp-back-to-top"></div>';
+}
+if ( wp_is_block_theme() ) {
+	add_filter(
+		'render_block',
+		function ( $html, $block ) {
+			if ( 'core/back-to-top' === $block['blockName'] ) {
+				add_action( 'wp_body_open', 'block_core_back_to_top_target' );
+			}
+			return $html;
+		},
+		10,
+		2
+	);
+} else {
+	add_action( 'wp_body_open', 'block_core_back_to_top_target' );
+}
+
+/**
+ * For classic themes that do not use `wp_body_open()`,
+ * view.js is needed to move focus to the first focusable element on the top of the page.
+ */
+function block_core_back_to_top_classic_fallback() {
+	if ( ! wp_is_block_theme() && 0 === did_action( 'wp_body_open' ) ) {
+		// If the Gutenberg plugin is active, use the script from the plugin.
+		if ( defined( 'IS_GUTENBERG_PLUGIN' ) && IS_GUTENBERG_PLUGIN ) {
+			wp_enqueue_script(
+				'wp-block-library-back-to-top-fallback',
+				plugins_url( 'back-to-top/view.min.js', __FILE__ ),
+				array(),
+				filemtime( plugin_dir_path( __FILE__ ) . 'back-to-top/view.min.js' ),
+				true
+			);
+		} else {
+			wp_enqueue_script(
+				'wp-block-library-back-to-top-fallback',
+				includes_url( 'blocks/back-to-top/view.min.js', __DIR__ ),
+				array(),
+				'',
+				true
+			);
+		}
+	}
+}

packages/block-library/src/back-to-top/init.js

@@ -0,0 +1,6 @@
+/**
+ * Internal dependencies
+ */
+import { init } from './';
+
+export default init();

packages/block-library/src/back-to-top/view.js

@@ -0,0 +1,40 @@
+/**
+ * This script is needed to move the focus to the first focusable element on the page.
+ * It is only intended to be loaded on the front of classic themes that does not include wp_body_open().
+ */
+window.addEventListener( 'load', () => {
+	const backToTopBlocks = document.querySelectorAll(
+		'.wp-block-back-to-top'
+	);
+	function moveFocusToTop() {
+		const topAnchor = document.getElementById( '#wp-back-to-top' );
+		if ( topAnchor ) {
+			topAnchor.querySelector( 'a' ).focus();
+			return;
+		}
+		// This list is not exhaustive, but covers common elements that can recieve focus.
+		const focusable = [
+			'a[href]',
+			'audio',
+			'button:not([disabled])',
+			'[contenteditable]',
+			'details',
+			'embed',
+			'iframe',
+			'input:not([disabled]):not([type="hidden"])',
+			'object',
+			'[role="button"][tabindex="0"]',
+			'[role="link"][tabindex="0"]',
+			'select:not([disabled])',
+			'summary',
+			'textarea:not([disabled])',
+			'video',
+			'[tabindex]:not([tabindex="-1"])',
+		];
+		document.querySelector( focusable.join( ', ' ) ).focus();
+	}
+
+	backToTopBlocks.forEach( ( backToTop ) => {
+		backToTop.addEventListener( 'click', moveFocusToTop );
+	} );
+} );

packages/block-library/src/index.js

@@ -23,6 +23,7 @@ import {
 import * as archives from './archives';
 import * as avatar from './avatar';
 import * as audio from './audio';
+import * as backToTop from './back-to-top';
 import * as button from './button';
 import * as buttons from './buttons';
 import * as calendar from './calendar';
@@ -142,6 +143,7 @@ const getAllBlocks = () => {
 		// Register all remaining core blocks.
 		archives,
 		audio,
+		backToTop,
 		button,
 		buttons,
 		calendar,

test/integration/fixtures/blocks/core__back-to-top.html

@@ -0,0 +1 @@
+<!-- wp:back-to-top /-->

test/integration/fixtures/blocks/core__back-to-top.json

@@ -0,0 +1,8 @@
+[
+	{
+		"name": "core/back-to-top",
+		"isValid": true,
+		"attributes": {},
+		"innerBlocks": []
+	}
+]

test/integration/fixtures/blocks/core__back-to-top.parsed.json

@@ -0,0 +1,9 @@
+[
+	{
+		"blockName": "core/back-to-top",
+		"attrs": {},
+		"innerBlocks": [],
+		"innerHTML": "",
+		"innerContent": []
+	}
+]

test/integration/fixtures/blocks/core__back-to-top.serialized.html

@@ -0,0 +1 @@
+<!-- wp:back-to-top /-->