feat(panel-view)!: make card() a static CardEntry factory; add cards() for CardsBlock; update renderers and README.md.

Author: terabytesoftw

CHANGELOG.md

@@ -5,7 +5,9 @@ All notable changes to this project will be documented in this file.
 The format is based on [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## 0.3.1 Under development
+## 0.4.0 Under development
+
+- feat(panel-view)!: make `card()` a static `CardEntry` factory; add `cards()` for `CardsBlock`; update renderers and `README.md`.
 
 ## 0.3.0 September 17, 2026
 

README.md

@@ -173,6 +173,11 @@ Five types are published for panel authors: `CollectorInterface`, `Panel`, `Pane
 Everything a panel can display is a `PanelView` method, so an extension imports no value class and builds nothing by
 hand.
 
+### Everyday vocabulary
+
+Most panels need only these methods: metrics, headings, prose, a label and value overview, tables, groups, empty
+states, and raw payloads.
+
 ```php
 use PHPForge\Debug\{ColumnStyle, PanelView, Tone};
 
@@ -181,19 +186,62 @@ PanelView::create()
     ->toolbar('Props', 2)
     ->heading('Props', section: true)
     ->overview(['Component' => 'Site', 'State' => PanelView::badge('shared', Tone::INFO)])
-    ->paragraph('Rendered by ', PanelView::code('Inertia::render()'))
-    ->callout(Tone::WARNING, 'Runtime inspection is unavailable.')
+    ->paragraph('Rendered by ', PanelView::code('Inertia::render()'), ' in ', PanelView::strong('SiteController'))
+    ->callout(Tone::WARNING, 'Runtime inspection is unavailable. ', PanelView::link('Read more', '/docs/inertia'))
     ->table(['Prop', 'Value'], [['auth', PanelView::value(['id' => 1])]], styles: [0 => ColumnStyle::IDENTIFIER])
-    ->group('Component', PanelView::create()->paragraph('Nested content'))
+    ->group('Component', PanelView::create()->paragraph(PanelView::text('Nested content')))
     ->emptyState('No operations', 'The cache was observed, but nothing happened.')
     ->disclosure('Raw payload', $json);
 ```
 
-Plain scalars and `null` become text. `PanelView::text()`, `::strong()`, `::code()`, `::preview()`, `::badge()`, and
-`::value()` produce validated inline values accepted wherever a scalar is accepted. Methods with explicit value
+Plain scalars and `null` become text. `PanelView::text()`, `::strong()`, `::code()`, `::badge()`, `::value()`, and
+`::link()` produce validated inline values accepted wherever a scalar is accepted. Methods with explicit value
 validation reject invalid input with an `InvalidArgumentException`; arguments with incompatible declared types raise
 PHP's native `TypeError`.
 
+### Extended vocabulary
+
+Denser layouts for inventories and dashboards. Each collection pairs a static factory that creates one entry with a
+method that appends the block laying those entries out, so a panel builds the entries first and appends them once.
+
+```php
+use PHPForge\Debug\{PanelView, Tone};
+
+PanelView::create()
+    ->stats(PanelView::stat('asset', 'bundles', '2'), PanelView::stat('link', 'links', '1', Tone::SUCCESS))
+    ->cards(
+        PanelView::card(
+            'app-asset',
+            'asset',
+            'AppAsset',
+            'App\\Asset\\',
+            [PanelView::badge('1 css', Tone::INFO)],
+            PanelView::column('Files', PanelView::create()->files(PanelView::file('.css', 'site.css', Tone::INFO))),
+            PanelView::column('Wiring', PanelView::create()->links('Depends on', PanelView::link('YiiAsset', '#yii'))),
+        ),
+    );
+```
+
+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 |
+| `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 |
+| `pills()` / `pill()` | A strip of on/off status pills. | Config |
+| `files()` / `file()` | A list of typed file names. | Asset |
+| `manifest()` / `package()` | A vendor-grouped package roster. | Config |
+| `links()` | A labeled strip of `link()` targets. | Asset |
+| `cards()` / `card()` / `column()` | A grid of entity cards, each split into titled columns. | Asset |
+| `preview()` | Inline text the host clamps behind its expand control. | User |
+| `sql()` | Inline text the host highlights as an SQL statement. | No built-in emits it yet. |
+| `trace()` | Captured call-site frames the host renders as source links. | No built-in emits it yet. |
+
+### Reading a description
+
 The host reads the finished description through `summaryMetrics()`, `toolbarMetrics()`, and `blocks()`.
 Those accessors return `PHPForge\Debug\Presenter` value objects: `SummaryMetric`, `ToolbarMetric`, and the blocks,
 entries, and inline values behind them. A renderer narrows each value with `instanceof` over the sealed `Block` and

src/PanelView.php

@@ -77,7 +77,7 @@ public function callout(Tone $tone, mixed ...$content): self
     }
 
     /**
-     * Appends a card describing one entity, optionally split into titled columns of its own content.
+     * Creates one card describing an entity, optionally split into titled columns of its own content.
      *
      * @param string $id Anchor the host emits so other blocks can link to the card, or `''` to omit it.
      * @param string $icon Host icon key shown before the title, or `''` to omit it.
@@ -88,34 +88,44 @@ public function callout(Tone $tone, mixed ...$content): self
      *
      * @throws InvalidArgumentException if a meta value is not an accepted inline value.
      *
-     * @return self New view with the card appended.
+     * @return Presenter\CardEntry Card entry accepted by {@see self::cards()}.
      */
-    public function card(
+    public static function card(
         string $id,
         string $icon,
         string $title,
         string $subtitle,
         array $meta,
         Presenter\ColumnEntry ...$columns
-    ): self {
+    ): Presenter\CardEntry {
         $inline = [];
 
         foreach ($meta as $value) {
             $inline[] = self::inline($value);
         }
 
-        return $this->append(
-            new Presenter\CardBlock(
-                $id,
-                $icon,
-                $title,
-                $subtitle,
-                $inline,
-                array_values($columns),
-            ),
+        return new Presenter\CardEntry(
+            $id,
+            $icon,
+            $title,
+            $subtitle,
+            $inline,
+            array_values($columns),
         );
     }
 
+    /**
+     * Appends a set of entity cards the host lays out together.
+     *
+     * @param Presenter\CardEntry ...$cards Entries produced by {@see self::card()}.
+     *
+     * @return self New view with the card set appended.
+     */
+    public function cards(Presenter\CardEntry ...$cards): self
+    {
+        return $this->append(new Presenter\CardsBlock(array_values($cards)));
+    }
+
     /**
      * Creates inline text presented as source code.
      *

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 CardBlock|DisclosureBlock|EmptyStateBlock|FactsBlock|FilesBlock|GroupBlock|HeadingBlock|LinksBlock
+ * @phpstan-sealed CardsBlock|DisclosureBlock|EmptyStateBlock|FactsBlock|FilesBlock|GroupBlock|HeadingBlock|LinksBlock
  *   |ManifestBlock|OverviewBlock|ParagraphBlock|PillsBlock|ReadoutsBlock|SectionBlock|StatsBlock|TableBlock
  */
 interface Block {}

src/Presenter/CardBlock.php src/Presenter/CardEntry.phpsrc/Presenter/CardBlock.php renamed to src/Presenter/CardEntry.php

@@ -5,9 +5,9 @@
 namespace PHPForge\Debug\Presenter;
 
 /**
- * Represents a card describing one entity, optionally split into titled columns of its own content.
+ * Represents one card describing an entity, optionally split into titled columns of its own content.
  */
-final readonly class CardBlock implements Block
+final readonly class CardEntry
 {
     /**
      * @param string $id Anchor the host emits so other blocks can link to the card, or `''` to omit it.

src/Presenter/CardsBlock.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Debug\Presenter;
+
+/**
+ * Represents a set of entity cards the host lays out together.
+ */
+final readonly class CardsBlock implements Block
+{
+    /**
+     * @param list<CardEntry> $cards Entity cards in display order.
+     */
+    public function __construct(public array $cards) {}
+}

src/Presenter/TraceInline.php

@@ -40,6 +40,7 @@ public function __construct(array $frames)
             $fields = [];
 
             foreach ($frame as $key => $value) {
+                // @infection-ignore-all: numeric keys are stored as ints anyway; the cast only narrows the static type.
                 $fields[(string) $key] = $value;
             }
 

tests/CompositeBlockTest.php

@@ -8,7 +8,8 @@
 use PHPForge\Debug\Exception\PanelViewMessage;
 use PHPForge\Debug\{PanelView, Tone};
 use PHPForge\Debug\Presenter\{
-    CardBlock,
+    CardEntry,
+    CardsBlock,
     ColumnEntry,
     FactEntry,
     FactsBlock,
@@ -45,38 +46,64 @@ public function testCardKeepsItsMetaAndTitledColumnsInDeclarationOrder(): void
 
         $files = PanelView::create()->files(PanelView::file('.css', 'site.css', Tone::INFO));
         $wiring = PanelView::create()->facts(PanelView::fact('SOURCE', '@app/assets'));
-        $view = PanelView::create()
-            ->card(
+
+        self::assertEquals(
+            new CardEntry(
+                'app-asset',
+                'asset',
+                'AppAsset',
+                'App\\Asset\\',
+                [$badge, new TextInline('1 js', TextStyle::PLAIN)],
+                [new ColumnEntry('FILES', $files), new ColumnEntry('WIRING', $wiring)],
+            ),
+            PanelView::card(
                 'app-asset',
                 'asset',
                 'AppAsset',
                 'App\\Asset\\',
                 [$badge, '1 js'],
                 PanelView::column('FILES', $files),
                 PanelView::column('WIRING', $wiring),
-            );
+            ),
+            'A card keeps its meta and columns in declaration order.',
+        );
+
+        $columns = ['files' => PanelView::column('FILES', $files), 'wiring' => PanelView::column('WIRING', $wiring)];
 
         self::assertEquals(
-            [
-                new CardBlock(
-                    'app-asset',
-                    'asset',
-                    'AppAsset',
-                    'App\\Asset\\',
-                    [$badge, new TextInline('1 js', TextStyle::PLAIN)],
-                    [new ColumnEntry('FILES', $files), new ColumnEntry('WIRING', $wiring)],
-                ),
-            ],
-            $view->blocks(),
-            'A card keeps its meta and columns in declaration order.',
+            [new ColumnEntry('FILES', $files), new ColumnEntry('WIRING', $wiring)],
+            PanelView::card('app-asset', 'asset', 'AppAsset', '', [], ...$columns)->columns,
+            'String keys must not reach the column list.',
+        );
+    }
+
+    public function testCardsKeepTheirEntriesInDeclarationOrder(): void
+    {
+        $app = PanelView::card('app-asset', 'asset', 'AppAsset', '', []);
+        $yii = PanelView::card('yii-asset', 'asset', 'YiiAsset', '', []);
+
+        $cards = ['app' => $app, 'yii' => $yii];
+
+        self::assertEquals(
+            [new CardsBlock([$app, $yii]), new CardsBlock([])],
+            PanelView::create()
+                ->cards($app, $yii)
+                ->cards()
+                ->blocks(),
+            'A card set keeps its cards in declaration order.',
+        );
+        self::assertEquals(
+            [new CardsBlock([$app, $yii])],
+            PanelView::create()->cards(...$cards)->blocks(),
+            'String keys must not reach the card list.',
         );
     }
 
     public function testCardWithoutMetaOrColumnsCarriesEmptyLists(): void
     {
         self::assertEquals(
-            [new CardBlock('', '', 'AppAsset', '', [], [])],
-            PanelView::create()->card('', '', 'AppAsset', '', [])->blocks(),
+            new CardEntry('', '', 'AppAsset', '', [], []),
+            PanelView::card('', '', 'AppAsset', '', []),
             'An unadorned card keeps its optional parts empty.',
         );
     }
@@ -90,6 +117,14 @@ public function testFactsKeepTheirLabelAndValuePairs(): void
                 ->blocks(),
             'A fact strip keeps every pair in declaration order.',
         );
+
+        $facts = ['charset' => PanelView::fact('Charset', 'UTF-8')];
+
+        self::assertEquals(
+            [new FactsBlock([new FactEntry('Charset', 'UTF-8')])],
+            PanelView::create()->facts(...$facts)->blocks(),
+            'String keys must not reach the fact list.',
+        );
     }
 
     public function testFilesKeepTheirTypeToneAndOrder(): void
@@ -118,6 +153,14 @@ public function testFilesKeepTheirTypeToneAndOrder(): void
                 ->blocks(),
             'A file list keeps every entry in declaration order.',
         );
+
+        $files = ['site' => PanelView::file('.css', 'site.css', Tone::INFO)];
+
+        self::assertEquals(
+            [new FilesBlock([new FileEntry('.css', 'site.css', Tone::INFO)])],
+            PanelView::create()->files(...$files)->blocks(),
+            'String keys must not reach the file list.',
+        );
     }
 
     public function testLinksKeepTheirLabelAndOrder(): void
@@ -143,6 +186,14 @@ public function testLinksKeepTheirLabelAndOrder(): void
                 ->blocks(),
             'A link strip keeps every target in declaration order.',
         );
+
+        $links = ['yii' => PanelView::link('YiiAsset', '#yii-asset')];
+
+        self::assertEquals(
+            [new LinksBlock('Depends on 1', [new LinkInline('YiiAsset', '#yii-asset', false)])],
+            PanelView::create()->links('Depends on 1', ...$links)->blocks(),
+            'String keys must not reach the link list.',
+        );
     }
 
     public function testManifestGroupsPackagesUnderOneVendorLabel(): void
@@ -163,6 +214,14 @@ public function testManifestGroupsPackagesUnderOneVendorLabel(): void
             $view->blocks(),
             'A manifest keeps its packages in declaration order under the vendor label.',
         );
+
+        $packages = ['aliases' => PanelView::package('aliases', 'v3.1.1')];
+
+        self::assertEquals(
+            [new ManifestBlock('yiisoft/', [new PackageEntry('aliases', 'v3.1.1')])],
+            PanelView::create()->manifest('yiisoft/', ...$packages)->blocks(),
+            'String keys must not reach the package list.',
+        );
     }
 
     public function testPillsKeepTheirStateAndOrder(): void
@@ -177,6 +236,14 @@ public function testPillsKeepTheirStateAndOrder(): void
             $view->blocks(),
             'A pill strip keeps every subject with its own state.',
         );
+
+        $pills = ['apcu' => PanelView::pill('APCu', 'on', true)];
+
+        self::assertEquals(
+            [new PillsBlock([new PillEntry('APCu', 'on', true)])],
+            PanelView::create()->pills(...$pills)->blocks(),
+            'String keys must not reach the pill list.',
+        );
     }
 
     public function testReadoutCaptionIsOptional(): void
@@ -193,6 +260,14 @@ public function testReadoutCaptionIsOptional(): void
                 ->blocks(),
             'A readout row carries its cards in declaration order.',
         );
+
+        $readouts = ['php' => PanelView::readout('PHP', '8.5.9', 'runtime')];
+
+        self::assertEquals(
+            [new ReadoutsBlock([new ReadoutEntry('PHP', '8.5.9', 'runtime')])],
+            PanelView::create()->readouts(...$readouts)->blocks(),
+            'String keys must not reach the readout list.',
+        );
     }
 
     public function testSectionCountIsOptionalAndWrapsItsOwnBlocks(): void
@@ -248,6 +323,6 @@ public function testThrowInvalidArgumentExceptionForCardMetaNoInlineFactoryBuilt
             PanelViewMessage::INLINE_CONTENT_INVALID->getMessage('stdClass'),
         );
 
-        PanelView::create()->card('', '', 'AppAsset', '', [new stdClass()]);
+        PanelView::card('', '', 'AppAsset', '', [new stdClass()]);
     }
 }