From 0069ae2265bfd62614a70755737fdc278d36883c Mon Sep 17 00:00:00 2001
From: Tom Willmot <tom@humanmade.com>
Date: Fri, 30 Oct 2026 09:47:18 +0100
Subject: [PATCH 1/2] Fix process navigation, completion focus and authored
 colours

---
 src/process/render.php | 38 +++++++++++++++++++++++++++++++--
 src/process/style.scss | 10 +++++++++
 src/process/view.js    | 48 +++++++++++++++++++++++++++++++++++-------
 src/step/render.php    |  2 ++
 4 files changed, 88 insertions(+), 10 deletions(-)

diff --git a/src/process/render.php b/src/process/render.php
index e026881..4845528 100644
--- a/src/process/render.php
+++ b/src/process/render.php
@@ -79,20 +79,50 @@ class="wp-block-process-blocks-process__item"
 	<?php
 };
 
-$wrapper_attributes = get_block_wrapper_attributes( [
+$wrapper_options = [
 	'id' => $attributes['anchor'] ?? $process['id'],
 	'data-wp-interactive' => Process_Blocks\STORE_NAMESPACE,
 	'data-wp-context' => wp_json_encode( $context, JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP ),
 	'data-wp-init' => 'callbacks.load',
 	'data-wp-watch' => 'callbacks.save',
 	'data-wp-class--is-all-complete' => 'state.isAllComplete',
-] );
+];
+
+// Completion icons need both authored colours, including when their number is
+// made transparent. Resolve presets through the native block colour style engine.
+$background = isset( $attributes['backgroundColor'] )
+	? 'var:preset|color|' . $attributes['backgroundColor']
+	: ( $attributes['style']['color']['background'] ?? null );
+$text = isset( $attributes['textColor'] )
+	? 'var:preset|color|' . $attributes['textColor']
+	: ( $attributes['style']['color']['text'] ?? null );
+if ( $background || $text ) {
+	$styles = wp_style_engine_get_styles( [
+		'color' => [
+			'background' => $background,
+			'text' => $text,
+		],
+	] );
+	$colours = [];
+	if ( ! empty( $styles['declarations']['background-color'] ) ) {
+		$colours[] = '--process-blocks--surface:' . $styles['declarations']['background-color'];
+	}
+	if ( ! empty( $styles['declarations']['color'] ) ) {
+		$colours[] = '--process-blocks--accent:' . $styles['declarations']['color'];
+	}
+	$wrapper_options['style'] = implode( ';', $colours );
+}
+$wrapper_attributes = get_block_wrapper_attributes( $wrapper_options );
 ?>
 <div <?php echo $wrapper_attributes; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped ?>>
+	<noscript>
+		<p><?php esc_html_e( 'JavaScript is required to use the checklist controls. You can still read all steps below.', 'process-blocks' ); ?></p>
+	</noscript>
 	<?php if ( $show_summary ) : ?>
 		<nav
 			class="wp-block-process-blocks-process__summary"
 			aria-label="<?php esc_attr_e( 'Process steps', 'process-blocks' ); ?>"
+			tabindex="-1"
 		>
 			<div class="wp-block-process-blocks-process__summary-header">
 				<p class="wp-block-process-blocks-process__count">
@@ -163,6 +193,8 @@ class="wp-block-process-blocks-process__status-section"
 				<button
 					type="button"
 					class="wp-block-process-blocks-process__complete wp-element-button"
+					disabled
+					data-wp-bind--disabled="!context.isLoaded"
 					data-wp-on--click="actions.completeActive"
 					data-wp-class--is-hidden="!state.canCompleteActive"
 				>
@@ -178,6 +210,8 @@ class="wp-block-process-blocks-process__completed"
 					<button
 						type="button"
 						class="wp-block-process-blocks-process__undo"
+						disabled
+						data-wp-bind--disabled="!context.isLoaded"
 						data-wp-on--click="actions.uncompleteActive"
 						data-wp-bind--aria-label="state.undoLabel"
 					>
diff --git a/src/process/style.scss b/src/process/style.scss
index d3a46db..779894b 100644
--- a/src/process/style.scss
+++ b/src/process/style.scss
@@ -247,6 +247,10 @@
 
 .wp-block-process-blocks-process__complete {
 	margin: 0;
+
+	&:disabled {
+		cursor: default;
+	}
 }
 
 // Compact button on small screens, overriding the theme's button styles.
@@ -384,6 +388,8 @@
 }
 
 .wp-block-process-blocks-step {
+	// Let wide inner blocks scroll inside the step instead of widening its grid track.
+	min-width: 0;
 	padding: 1.25em 1.5em;
 	border: 1px solid var( --process-blocks--border );
 	border-radius: var( --process-blocks--radius );
@@ -454,6 +460,10 @@
 	color: inherit;
 	cursor: pointer;
 
+	&:disabled {
+		cursor: default;
+	}
+
 	&:hover {
 		border-color: var( --process-blocks--accent );
 	}
diff --git a/src/process/view.js b/src/process/view.js
index 23927ef..9ad3d85 100644
--- a/src/process/view.js
+++ b/src/process/view.js
@@ -25,12 +25,12 @@ import {
 } from '@wordpress/interactivity';
 
 /**
- * Sort step indexes numerically.
+ * Deduplicate and sort step indexes numerically.
  *
  * @param {number[]} indexes Step indexes.
  * @returns {number[]} Sorted indexes.
  */
-const sortIndexes = indexes => [ ...indexes ].sort( ( a, b ) => a - b );
+const sortIndexes = indexes => [ ...new Set( indexes ) ].sort( ( a, b ) => a - b );
 
 /**
  * Get the index of the current (first incomplete) step.
@@ -105,7 +105,9 @@ const goToStep = ( context, index ) => {
  * @returns {number} Step index, or -1 if no step has been reached.
  */
 const getViewingIndex = ( elements, bar ) => {
-	const barBottom = bar.getBoundingClientRect().bottom;
+	// On short screens the theme lets the bar scroll away. Track the viewport
+	// once it is off screen, rather than a line above the visible steps.
+	const barBottom = Math.max( 0, bar.getBoundingClientRect().bottom );
 	const line = barBottom + Math.min( 120, ( window.innerHeight - barBottom ) / 4 );
 	const tops = elements.map( element => element?.getBoundingClientRect().top ?? Infinity );
 
@@ -283,8 +285,9 @@ const { state } = store( 'process-blocks', {
 		/**
 		 * Mark the active step complete, and move on to the next incomplete step.
 		 */
-		completeActive() {
+		*completeActive() {
 			const context = getContext();
+			const { ref } = getElement();
 			const index = state.activeIndex;
 			if ( index === -1 || context.completed.includes( index ) ) {
 				return;
@@ -295,6 +298,10 @@ const { state } = store( 'process-blocks', {
 			const next = getNextIncomplete( context, index );
 			if ( next === -1 ) {
 				context.announcement = state.i18n.finished;
+				// The completion button disappears; focus its replacement after rendering.
+				yield new Promise( resolve => window.requestAnimationFrame( resolve ) );
+				ref.closest( '.wp-block-process-blocks-process' )
+					?.querySelector( '.wp-block-process-blocks-process__restart' )?.focus( { preventScroll: true } );
 				return;
 			}
 
@@ -305,11 +312,16 @@ const { state } = store( 'process-blocks', {
 		/**
 		 * Mark the active step as incomplete.
 		 */
-		uncompleteActive() {
+		*uncompleteActive() {
 			const context = getContext();
+			const { ref } = getElement();
 			const index = state.activeIndex;
 			context.completed = context.completed.filter( completed => completed !== index );
 			context.announcement = format( state.i18n.incomplete, index + 1 );
+			// Undo is hidden when the action is incomplete. Keep focus in the step bar.
+			yield new Promise( resolve => window.requestAnimationFrame( resolve ) );
+			ref.closest( '.wp-block-process-blocks-process__bar' )
+				?.querySelector( '.wp-block-process-blocks-process__complete' )?.focus( { preventScroll: true } );
 		},
 
 		/**
@@ -347,16 +359,21 @@ const { state } = store( 'process-blocks', {
 		/**
 		 * Clear all progress, and return to the start of the process.
 		 */
-		reset() {
+		*reset() {
 			const context = getContext();
+			const { ref } = getElement();
+			const process = ref.closest( '.wp-block-process-blocks-process' );
 			context.completed = [];
 			context.announcement = state.i18n.reset;
 
-			const { ref } = getElement();
-			ref.closest( '.wp-block-process-blocks-process' )?.scrollIntoView( {
+			process?.scrollIntoView( {
 				behavior: prefersReducedMotion() ? 'auto' : 'smooth',
 				block: 'start',
 			} );
+			// Reset becomes disabled and Start again disappears; return to the overview.
+			yield new Promise( resolve => window.requestAnimationFrame( resolve ) );
+			process?.querySelector( '.wp-block-process-blocks-process__summary, .wp-block-process-blocks-step' )
+				?.focus( { preventScroll: true } );
 		},
 	},
 	callbacks: {
@@ -385,11 +402,26 @@ const { state } = store( 'process-blocks', {
 				return;
 			}
 
+			// Native fragment navigation happens before the hydrated bar is measured.
+			// Align a linked step once the real clearance is available, without taking focus.
+			const linkedIndex = context.steps.findIndex( step => window.location.hash === `#${ step.id }` );
+			let linkedStep = linkedIndex === -1 ? null : document.getElementById( context.steps[ linkedIndex ].id );
+			if ( linkedStep ) {
+				context.viewing = linkedIndex;
+			}
+
 			// Track the sticky bar's height, so steps scroll clear of it (with
 			// a little breathing room).
 			const resizeObserver = new window.ResizeObserver( () => {
 				const offset = `calc( var( --process-blocks--sticky-top ) + ${ bar.offsetHeight + 16 }px )`;
 				ref.style.setProperty( '--process-blocks--scroll-offset', offset );
+				if ( linkedStep ) {
+					linkedStep.scrollIntoView( {
+						behavior: 'instant',
+						block: 'start',
+					} );
+					linkedStep = null;
+				}
 			} );
 			resizeObserver.observe( bar );
 
diff --git a/src/step/render.php b/src/step/render.php
index 851c996..d05f781 100644
--- a/src/step/render.php
+++ b/src/step/render.php
@@ -40,6 +40,8 @@
 		<button
 			type="button"
 			class="wp-block-process-blocks-step__toggle"
+			disabled
+			data-wp-bind--disabled="!context.isLoaded"
 			aria-pressed="false"
 			data-wp-bind--aria-pressed="state.isStepComplete"
 			data-wp-on--click="actions.toggleStep"

From ef2a3b7d954ab278c0dc44ad7d47ac7b8bc9623c Mon Sep 17 00:00:00 2001
From: Tom Willmot <tom@humanmade.com>
Date: Tue, 3 Nov 2026 11:55:23 +0100
Subject: [PATCH 2/2] Address checklist fallback and focus review

---
 src/process/render.php | 14 ++++----------
 src/process/style.scss | 15 +++++++--------
 src/process/view.js    | 21 +++++++++++----------
 src/step/render.php    |  4 ++--
 4 files changed, 24 insertions(+), 30 deletions(-)

diff --git a/src/process/render.php b/src/process/render.php
index 4845528..683de07 100644
--- a/src/process/render.php
+++ b/src/process/render.php
@@ -110,21 +110,19 @@ class="wp-block-process-blocks-process__item"
 	if ( ! empty( $styles['declarations']['color'] ) ) {
 		$colours[] = '--process-blocks--accent:' . $styles['declarations']['color'];
 	}
-	$wrapper_options['style'] = implode( ';', $colours );
+	// Filter raw declarations and terminate them before core appends its styles.
+	$wrapper_options['style'] = safecss_filter_attr( implode( ';', $colours ) ) . ';';
 }
 $wrapper_attributes = get_block_wrapper_attributes( $wrapper_options );
 ?>
 <div <?php echo $wrapper_attributes; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped ?>>
-	<noscript>
-		<p><?php esc_html_e( 'JavaScript is required to use the checklist controls. You can still read all steps below.', 'process-blocks' ); ?></p>
-	</noscript>
 	<?php if ( $show_summary ) : ?>
 		<nav
 			class="wp-block-process-blocks-process__summary"
 			aria-label="<?php esc_attr_e( 'Process steps', 'process-blocks' ); ?>"
 			tabindex="-1"
 		>
-			<div class="wp-block-process-blocks-process__summary-header">
+			<div class="wp-block-process-blocks-process__summary-header" hidden data-wp-bind--hidden="!context.isLoaded">
 				<p class="wp-block-process-blocks-process__count">
 					<?php echo $progress_count; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped ?>
 				</p>
@@ -176,7 +174,7 @@ class="wp-block-process-blocks-process__checklist-section"
 		</nav>
 	<?php endif ?>
 
-	<div class="wp-block-process-blocks-process__bar">
+	<div class="wp-block-process-blocks-process__bar" hidden data-wp-bind--hidden="!context.isLoaded">
 		<div class="wp-block-process-blocks-process__bar-inner">
 			<div class="wp-block-process-blocks-process__status">
 				<span class="wp-block-process-blocks-process__status-label">
@@ -193,8 +191,6 @@ class="wp-block-process-blocks-process__status-section"
 				<button
 					type="button"
 					class="wp-block-process-blocks-process__complete wp-element-button"
-					disabled
-					data-wp-bind--disabled="!context.isLoaded"
 					data-wp-on--click="actions.completeActive"
 					data-wp-class--is-hidden="!state.canCompleteActive"
 				>
@@ -210,8 +206,6 @@ class="wp-block-process-blocks-process__completed"
 					<button
 						type="button"
 						class="wp-block-process-blocks-process__undo"
-						disabled
-						data-wp-bind--disabled="!context.isLoaded"
 						data-wp-on--click="actions.uncompleteActive"
 						data-wp-bind--aria-label="state.undoLabel"
 					>
diff --git a/src/process/style.scss b/src/process/style.scss
index 779894b..e6375c1 100644
--- a/src/process/style.scss
+++ b/src/process/style.scss
@@ -22,6 +22,13 @@
 	--process-blocks--scroll-offset: calc( var( --process-blocks--sticky-top ) + 6rem );
 }
 
+// Keep JavaScript-only controls hidden until the process has loaded.
+.wp-block-process-blocks-process__summary-header[hidden],
+.wp-block-process-blocks-process__bar[hidden],
+.wp-block-process-blocks-step__toggle[hidden] {
+	display: none;
+}
+
 /*
  * Summary checklist.
  */
@@ -247,10 +254,6 @@
 
 .wp-block-process-blocks-process__complete {
 	margin: 0;
-
-	&:disabled {
-		cursor: default;
-	}
 }
 
 // Compact button on small screens, overriding the theme's button styles.
@@ -460,10 +463,6 @@
 	color: inherit;
 	cursor: pointer;
 
-	&:disabled {
-		cursor: default;
-	}
-
 	&:hover {
 		border-color: var( --process-blocks--accent );
 	}
diff --git a/src/process/view.js b/src/process/view.js
index 9ad3d85..880f97a 100644
--- a/src/process/view.js
+++ b/src/process/view.js
@@ -285,7 +285,7 @@ const { state } = store( 'process-blocks', {
 		/**
 		 * Mark the active step complete, and move on to the next incomplete step.
 		 */
-		*completeActive() {
+		completeActive() {
 			const context = getContext();
 			const { ref } = getElement();
 			const index = state.activeIndex;
@@ -299,9 +299,10 @@ const { state } = store( 'process-blocks', {
 			if ( next === -1 ) {
 				context.announcement = state.i18n.finished;
 				// The completion button disappears; focus its replacement after rendering.
-				yield new Promise( resolve => window.requestAnimationFrame( resolve ) );
-				ref.closest( '.wp-block-process-blocks-process' )
-					?.querySelector( '.wp-block-process-blocks-process__restart' )?.focus( { preventScroll: true } );
+				window.requestAnimationFrame( () => {
+					ref.closest( '.wp-block-process-blocks-process' )
+						?.querySelector( '.wp-block-process-blocks-process__restart' )?.focus( { preventScroll: true } );
+				} );
 				return;
 			}
 
@@ -312,16 +313,17 @@ const { state } = store( 'process-blocks', {
 		/**
 		 * Mark the active step as incomplete.
 		 */
-		*uncompleteActive() {
+		uncompleteActive() {
 			const context = getContext();
 			const { ref } = getElement();
 			const index = state.activeIndex;
 			context.completed = context.completed.filter( completed => completed !== index );
 			context.announcement = format( state.i18n.incomplete, index + 1 );
 			// Undo is hidden when the action is incomplete. Keep focus in the step bar.
-			yield new Promise( resolve => window.requestAnimationFrame( resolve ) );
-			ref.closest( '.wp-block-process-blocks-process__bar' )
-				?.querySelector( '.wp-block-process-blocks-process__complete' )?.focus( { preventScroll: true } );
+			window.requestAnimationFrame( () => {
+				ref.closest( '.wp-block-process-blocks-process__bar' )
+					?.querySelector( '.wp-block-process-blocks-process__complete' )?.focus( { preventScroll: true } );
+			} );
 		},
 
 		/**
@@ -359,7 +361,7 @@ const { state } = store( 'process-blocks', {
 		/**
 		 * Clear all progress, and return to the start of the process.
 		 */
-		*reset() {
+		reset() {
 			const context = getContext();
 			const { ref } = getElement();
 			const process = ref.closest( '.wp-block-process-blocks-process' );
@@ -371,7 +373,6 @@ const { state } = store( 'process-blocks', {
 				block: 'start',
 			} );
 			// Reset becomes disabled and Start again disappears; return to the overview.
-			yield new Promise( resolve => window.requestAnimationFrame( resolve ) );
 			process?.querySelector( '.wp-block-process-blocks-process__summary, .wp-block-process-blocks-step' )
 				?.focus( { preventScroll: true } );
 		},
diff --git a/src/step/render.php b/src/step/render.php
index d05f781..6216e54 100644
--- a/src/step/render.php
+++ b/src/step/render.php
@@ -40,8 +40,8 @@
 		<button
 			type="button"
 			class="wp-block-process-blocks-step__toggle"
-			disabled
-			data-wp-bind--disabled="!context.isLoaded"
+			hidden
+			data-wp-bind--hidden="!context.isLoaded"
 			aria-pressed="false"
 			data-wp-bind--aria-pressed="state.isStepComplete"
 			data-wp-on--click="actions.toggleStep"