docs: Update metadata documentation to clarify key ordering in JSON:API responses.

Author: gustavofreze

src/Cursor/Page.php

@@ -127,7 +127,8 @@ public function hasNext(): bool
     /**
      * Returns the cursor page as the JSON:API meta contents.
      *
-     * @return array<string, int|bool> The meta contents keyed in length-ascending order.
+     * @return array<string, int|bool> The meta contents, counts and sizes first, then the boolean
+     * flags, each by ascending key-name length.
      */
     public function metadata(): array
     {

src/Offset/Page.php

@@ -149,7 +149,8 @@ public function hasNext(): bool
     /**
      * Returns the page as the JSON:API meta contents.
      *
-     * @return array<string, int|bool> The meta contents keyed in length-ascending order.
+     * @return array<string, int|bool> The meta contents, counts and sizes first, then the boolean
+     * flags, each by ascending key-name length.
      */
     public function metadata(): array
     {

src/Offset/Slice.php

@@ -117,7 +117,8 @@ public function hasNext(): bool
     /**
      * Returns the slice as the JSON:API meta contents.
      *
-     * @return array<string, int|bool> The meta contents keyed in length-ascending order.
+     * @return array<string, int|bool> The meta contents, counts and sizes first, then the boolean
+     * flags, each by ascending key-name length.
      */
     public function metadata(): array
     {

tests/Unit/Cursor/PageTest.php

@@ -49,7 +49,7 @@ public function testNavigationWhenNoExtraElementThenHasNoNextPage(): void
         /** @And the navigation lists no target */
         self::assertCount(0, $page->navigation()->targets()->toArray());
 
-        /** @And the metadata reports no next page in length-ascending key order */
+        /** @And the metadata reports no next page in grouped key order (counts and sizes, then the boolean flags) */
         self::assertSame(['per_page' => 2, 'has_next' => false], $page->metadata());
     }
 
@@ -168,7 +168,7 @@ public function testMapWhenTransformationGivenThenProjectsItemsAndPreservesTheCu
         /** @And the next pagination still anchors on the source keys */
         self::assertEquals(Pagination::from(cursor: Token::fromKeys(keys: [20]), perPage: 2), $mapped->next());
 
-        /** @And the metadata is preserved in length-ascending key order */
+        /** @And the metadata is preserved in grouped key order (counts and sizes, then the boolean flags) */
         self::assertSame(['per_page' => 2, 'has_next' => true], $mapped->metadata());
     }
 
@@ -226,7 +226,7 @@ public function testNavigationWhenExtraElementFetchedThenHasNextAndNextCursorAnc
         /** @And the next pagination anchors on the last retained element with the page size */
         self::assertEquals(Pagination::from(cursor: Token::fromKeys(keys: [20]), perPage: 2), $page->next());
 
-        /** @And the metadata carries the navigation flags in length-ascending key order */
+        /** @And the metadata carries every entry in grouped key order (counts and sizes, then the boolean flags) */
         self::assertSame(['per_page' => 2, 'has_next' => true], $page->metadata());
     }
 }

tests/Unit/Offset/PageTest.php

@@ -167,7 +167,7 @@ public function testMetadataWhenMiddlePageGivenThenCarriesEveryFlagAndCount(): v
         /** @When building the page from the total element count */
         $page = $criteria->page(total: 480, items: ['a', 'b']);
 
-        /** @Then the metadata carries every navigation flag and count in length-ascending key order */
+        /** @Then the metadata carries every entry in grouped key order (counts and sizes, then the boolean flags) */
         self::assertSame([
             'total'        => 480,
             'per_page'     => 20,

tests/Unit/Offset/SliceTest.php

@@ -92,7 +92,7 @@ public function testNavigationWhenExtraElementFetchedThenHasNextAndTrimsItems():
         /** @And the previous pagination points at the first page */
         self::assertSame(1, $slice->previous()?->page());
 
-        /** @And the metadata carries every navigation flag and count in length-ascending key order */
+        /** @And the metadata carries every entry in grouped key order (counts and sizes, then the boolean flags) */
         self::assertSame([
             'per_page'     => 3,
             'current_page' => 2,