feat(panel-view): add hero() for HeroBlock, the header naming the subject a panel describes with its status badge and metric row; update README.md.

Author: terabytesoftw

CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## 0.4.1 Under development
 
+- feat(panel-view): add `hero()` for `HeroBlock`, the header naming the subject a panel describes with its status badge and metric row; update `README.md`.
+
 ## 0.4.0 September 25, 2026
 
 - feat(panel-view)!: make `card()` a static `CardEntry` factory; add `cards()` for `CardsBlock`; update renderers and `README.md`.

README.md

@@ -225,12 +225,29 @@ PanelView::create()
     );
 ```
 
+A panel about one subject opens with `hero()`: the mark and title, a status badge whose tone also colors the header
+accent, and one row of `fact()` metrics.
+
+```php
+use PHPForge\Debug\{PanelView, Tone};
+
+PanelView::create()->hero(
+    'AD',
+    'admin',
+    'admin@example.com',
+    PanelView::badge('Active', Tone::SUCCESS),
+    PanelView::fact('User ID', '1'),
+    PanelView::fact('Roles', 'admin'),
+);
+```
+
 Every method below is exercised by a built-in panel of `php-forge/debug-core`, except the two reserved for portable
 query and trace panels:
 
 | Method                            | Presents                                                    | Used by                   |
 | --------------------------------- | ----------------------------------------------------------- | ------------------------- |
-| `section()`                       | A titled section wrapping its own content.                  | Config                    |
+| `hero()`                          | The header naming the subject, its status, and metrics.     | User                      |
+| `section()`                       | A titled section wrapping its own content.                  | Config, User              |
 | `stats()` / `stat()`              | A strip of headline stat tiles.                             | Asset                     |
 | `readouts()` / `readout()`        | A row of headline readout cards.                            | Config                    |
 | `facts()` / `fact()`              | A compact strip of label and value pairs.                   | Asset, Config             |

src/PanelView.php

@@ -273,6 +273,30 @@ public function heading(string $title, bool $section = false): self
         return $this->append(new Presenter\HeadingBlock($title, $section));
     }
 
+    /**
+     * Appends the header identifying the subject the panel describes.
+     *
+     * Use it once, first, when the panel is about one subject, such as the signed-in user; the status badge tone also
+     * colors the header accent.
+     *
+     * @param string $mark Short text drawn as an avatar before the title, such as initials, or `''` to omit it.
+     * @param string $title Subject name, also announced as the accessible name of the header; the host escapes it.
+     * @param string $subtitle Qualifier shown under the title, or `''` to omit it; the host escapes it.
+     * @param Presenter\BadgeInline|null $status Badge produced by {@see self::badge()}, or `null` for a neutral header.
+     * @param Presenter\FactEntry ...$metrics Entries produced by {@see self::fact()}, shown as one metric row.
+     *
+     * @return self New view with the header appended.
+     */
+    public function hero(
+        string $mark,
+        string $title,
+        string $subtitle,
+        Presenter\BadgeInline|null $status,
+        Presenter\FactEntry ...$metrics,
+    ): self {
+        return $this->append(new Presenter\HeroBlock($mark, $title, $subtitle, $status, array_values($metrics)));
+    }
+
     /**
      * Creates an inline navigation link the host renders as an anchor.
      *

src/Presenter/Block.php

@@ -10,7 +10,7 @@
  * The union is sealed, so a host narrows a block with `instanceof` and static analysis proves that no case is left
  * unhandled.
  *
- * @phpstan-sealed CardsBlock|DisclosureBlock|EmptyStateBlock|FactsBlock|FilesBlock|GroupBlock|HeadingBlock|LinksBlock
- *   |ManifestBlock|OverviewBlock|ParagraphBlock|PillsBlock|ReadoutsBlock|SectionBlock|StatsBlock|TableBlock
+ * @phpstan-sealed CardsBlock|DisclosureBlock|EmptyStateBlock|FactsBlock|FilesBlock|GroupBlock|HeadingBlock|HeroBlock
+ *   |LinksBlock|ManifestBlock|OverviewBlock|ParagraphBlock|PillsBlock|ReadoutsBlock|SectionBlock|StatsBlock|TableBlock
  */
 interface Block {}

src/Presenter/HeroBlock.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Debug\Presenter;
+
+/**
+ * Represents the header identifying the subject a panel describes, such as the signed-in user.
+ *
+ * The host draws it as the lead card of the panel: the mark and title with their subtitle, the status badge whose tone
+ * also colors the card accent, and one row of metrics under them.
+ */
+final readonly class HeroBlock implements Block
+{
+    /**
+     * @param string $mark Short text drawn as an avatar before the title, such as initials, or `''` to omit it.
+     * @param string $title Subject name, also announced as the accessible name of the header; the host escapes it.
+     * @param string $subtitle Qualifier shown under the title, or `''` to omit it; the host escapes it.
+     * @param BadgeInline|null $status Status shown opposite the title, or `null` for a neutral header without one.
+     * @param list<FactEntry> $metrics Label and value pairs of the metric row in display order.
+     */
+    public function __construct(
+        public string $mark,
+        public string $title,
+        public string $subtitle,
+        public BadgeInline|null $status,
+        public array $metrics,
+    ) {}
+}

tests/CompositeBlockTest.php

@@ -15,6 +15,7 @@
     FactsBlock,
     FileEntry,
     FilesBlock,
+    HeroBlock,
     LinkInline,
     LinksBlock,
     ManifestBlock,
@@ -34,8 +35,8 @@
 use stdClass;
 
 /**
- * Unit tests for the {@see PanelView} composite blocks describing cards, stats, files, links, facts, readouts, pills,
- * manifests, and sections.
+ * Unit tests for the {@see PanelView} composite blocks describing heroes, cards, stats, files, links, facts, readouts,
+ * pills, manifests, and sections.
  */
 #[Group('panel-view')]
 final class CompositeBlockTest extends TestCase
@@ -163,6 +164,32 @@ public function testFilesKeepTheirTypeToneAndOrder(): void
         );
     }
 
+    public function testHeroKeepsItsIdentityStatusAndMetricOrder(): void
+    {
+        $status = PanelView::badge('Active', Tone::SUCCESS);
+
+        $metrics = ['id' => PanelView::fact('User ID', '1'), 'roles' => PanelView::fact('Roles', 'admin')];
+
+        self::assertEquals(
+            [
+                new HeroBlock(
+                    'AD',
+                    'admin',
+                    'admin@example.com',
+                    $status,
+                    [new FactEntry('User ID', '1'), new FactEntry('Roles', 'admin')],
+                ),
+            ],
+            PanelView::create()->hero('AD', 'admin', 'admin@example.com', $status, ...$metrics)->blocks(),
+            'Metrics must keep declaration order without their string keys.',
+        );
+        self::assertEquals(
+            [new HeroBlock('', 'admin', '', null, [])],
+            PanelView::create()->hero('', 'admin', '', null)->blocks(),
+            'A neutral header keeps its optional parts empty.',
+        );
+    }
+
     public function testLinksKeepTheirLabelAndOrder(): void
     {
         self::assertEquals(