Block delimiter: revert changes to parsed attributes, and update documentation (#44365)

* Scanner: revert change from #44158

See Automattic/jetpack#44158 (comment)

* Update docs

Automattic/jetpack#44158 (comment)

* Have the counting example actually count

See Automattic/jetpack#44158 (comment)

* Add changelog

---------

Co-authored-by: Dennis Snell <[email protected]>

Committed via a GitHub action: https://github.com/Automattic/jetpack/actions/runs/16374699829

Upstream-Ref: Automattic/jetpack@d44540d

Author: jeherve

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.1-alpha] - unreleased
+
+This is an alpha version! The changes listed here are not final.
+
+### Changed
+- Scanner: revert changes to returned parsed attributes.
+
 ## [0.3.0] - 2025-07-14
 ### Added
 - Add Block_Scanner class as a replacement to Block_Delimiter. [#44158]
@@ -21,6 +28,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Initial release.
 
+[0.3.1-alpha]: https://github.com/Automattic/block-delimiter/compare/v0.3.0...v0.3.1-alpha
 [0.3.0]: https://github.com/Automattic/block-delimiter/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/Automattic/block-delimiter/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/Automattic/block-delimiter/compare/v0.1.0...v0.2.0

README.md

@@ -74,16 +74,14 @@ $scanner = Block_Scanner::create( $post_content );
 
 // Find the first image block
 while ( $scanner->next_delimiter() ) {
-    if ( ! $scanner->is_block_type( 'image' ) ) {
+    if ( ! $scanner->opens_block( 'image' ) ) {
         continue;
     }
 
-    if ( $scanner->opens_block() ) {
-        $attributes = $scanner->allocate_and_return_parsed_attributes();
-        if ( isset( $attributes['id'] ) ) {
-            echo "Found image with ID: " . $attributes['id'];
-            break;
-        }
+    $attributes = $scanner->allocate_and_return_parsed_attributes();
+    if ( isset( $attributes['id'] ) ) {
+        echo "Found image with ID: " . $attributes['id'];
+        break;
     }
 }
 ```
@@ -130,7 +128,7 @@ Paragraph with font size: small
 
 ### Counting Block Types
 
-Get a summary of all block types in a document:
+Get a count of all block types in a document:
 
 ```php
 use Automattic\Block_Scanner;
@@ -151,33 +149,33 @@ $post_content = '<!-- wp:heading {"level":2} -->
 <ul><li>Item 1</li><li>Item 2</li></ul>
 <!-- /wp:list -->';
 
-function get_block_types_in( string $html ): array {
-    $block_types = [];
+function count_block_types_in( string $html ): array {
+    $block_counts = [];
     $scanner = Block_Scanner::create( $html );
 
     while ( $scanner->next_delimiter() ) {
         if ( $scanner->opens_block() ) {
-            $block_types[ $scanner->get_block_type() ] = true;
+            $block_type = $scanner->get_block_type();
+            $block_counts[ $block_type ] = ( $block_counts[ $block_type ] ?? 0 ) + 1;
         }
     }
 
-    $block_types = array_keys( $block_types );
-    sort( $block_types );
-    return $block_types;
+    ksort( $block_counts );
+    return $block_counts;
 }
 
-$block_types = get_block_types_in( $post_content );
-print_r( $block_types );
+$block_counts = count_block_types_in( $post_content );
+print_r( $block_counts );
 ```
 
 **Output:**
 ```
 Array
 (
-    [0] => core/heading
-    [1] => core/image
-    [2] => core/list
-    [3] => core/paragraph
+    [core/heading] => 1
+    [core/image] => 1
+    [core/list] => 1
+    [core/paragraph] => 2
 )
 ```
 
@@ -343,7 +341,7 @@ Paragraph with font size: small
 
 ### Counting Block Types
 
-Get a summary of all block types in a document:
+Get a count of all block types in a document:
 
 ```php
 use Automattic\Block_Delimiter;
@@ -364,32 +362,32 @@ $post_content = '<!-- wp:heading {"level":2} -->
 <ul><li>Item 1</li><li>Item 2</li></ul>
 <!-- /wp:list -->';
 
-function get_block_types_in( string $html ): array {
-    $block_types = [];
+function count_block_types_in( string $html ): array {
+    $block_counts = [];
 
     foreach ( Block_Delimiter::scan_delimiters( $html ) as $delimiter ) {
         if ( Block_Delimiter::OPENER === $delimiter->get_delimiter_type() ) {
-            $block_types[ $delimiter->allocate_and_return_block_type() ] = true;
+            $block_type = $delimiter->allocate_and_return_block_type();
+            $block_counts[ $block_type ] = ( $block_counts[ $block_type ] ?? 0 ) + 1;
         }
     }
 
-    $block_types = array_keys( $block_types );
-    sort( $block_types );
-    return $block_types;
+    ksort( $block_counts );
+    return $block_counts;
 }
 
-$block_types = get_block_types_in( $post_content );
-print_r( $block_types );
+$block_counts = count_block_types_in( $post_content );
+print_r( $block_counts );
 ```
 
 **Output:**
 ```
 Array
 (
-    [0] => core/heading
-    [1] => core/image
-    [2] => core/list
-    [3] => core/paragraph
+    [core/heading] => 1
+    [core/image] => 1
+    [core/list] => 1
+    [core/paragraph] => 2
 )
 ```
 

package.json

@@ -1,7 +1,7 @@
 {
 	"private": true,
 	"name": "@automattic/block-delimiter",
-	"version": "0.3.0",
+	"version": "0.3.1-alpha",
 	"description": "Efficiently work with block structure",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/packages/block-delimiter/#readme",
 	"bugs": {

src/class-block-scanner.php

@@ -808,7 +808,7 @@ public function allocate_and_return_parsed_attributes(): ?array {
 		}
 
 		$json_span = substr( $this->source_text, $this->json_at, $this->json_length );
-		$parsed    = json_decode( $json_span, true, 512, JSON_OBJECT_AS_ARRAY | JSON_INVALID_UTF8_SUBSTITUTE );
+		$parsed    = json_decode( $json_span, null, 512, JSON_OBJECT_AS_ARRAY | JSON_INVALID_UTF8_SUBSTITUTE );
 
 		$last_error            = json_last_error();
 		$this->last_json_error = $last_error;