feat(ui): share database EXPLAIN markup across debugger adapters.

CHANGELOG.md

@@ -17,3 +17,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - fix(toolbar): follow debug tags through adapter query URLs and enforce complete JavaScript mutation coverage.
 - feat(panel): add `UserRbacRow` typed view-model so adapters render RBAC role and permission rows from a single normalized shape.
 - feat: add shared UI parity contracts, Asset composition, and cross-adapter acceptance documentation.
+- feat(ui): share database EXPLAIN markup across debugger adapters.

src/Panel/Db/DbExplainRenderer.php

@@ -0,0 +1,109 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Debug\Panel\Db;
+
+use PHPForge\Debug\Helper\Dump;
+use UIAwesome\Html\Flow\{Div, P, Pre};
+use UIAwesome\Html\Heading\H1;
+use UIAwesome\Html\Phrasing\Em;
+use UIAwesome\Html\Table\{Table, Tbody, Td, Th, Thead, Tr};
+
+use function array_keys;
+use function array_values;
+use function is_scalar;
+
+/**
+ * Renders a database EXPLAIN plan with the shared debugger table contract.
+ */
+final class DbExplainRenderer
+{
+    /**
+     * Renders the explained SQL statement and its driver-specific result rows.
+     *
+     * @param string $query SQL statement passed to EXPLAIN.
+     * @param array<array-key, array<array-key, mixed>> $results Driver result rows.
+     */
+    public static function render(string $query, array $results): string
+    {
+        return self::renderPlan($query, $results, null);
+    }
+
+    /**
+     * Renders a failed EXPLAIN attempt without escaping the shared panel contract.
+     */
+    public static function renderError(string $query, string $message): string
+    {
+        return self::renderPlan($query, [], $message);
+    }
+
+    /**
+     * @param array<array-key, array<array-key, mixed>> $results Driver result rows.
+     */
+    private static function renderPlan(string $query, array $results, string|null $error): string
+    {
+        $resultList = array_values($results);
+
+        $columns = $resultList === [] ? [] : array_keys($resultList[0]);
+
+        $children = [
+            H1::tag()
+                ->class('yii-debug-explain-title')
+                ->content('EXPLAIN'),
+        ];
+
+        if ($query !== '') {
+            $children[] = Pre::tag()
+                ->class('yii-debug-explain-query')
+                ->html(SqlHighlighter::highlight($query));
+        }
+
+        if ($error !== null) {
+            $children[] = P::tag()
+                ->class('yii-debug-explain-empty')
+                ->content("EXPLAIN failed: {$error}");
+        } elseif ($results === []) {
+            $children[] = P::tag()
+                ->class('yii-debug-explain-empty')
+                ->content('EXPLAIN returned no rows.');
+        } else {
+            $headerCells = [];
+
+            foreach ($columns as $column) {
+                $headerCells[] = Th::tag()->scope('col')->content((string) $column);
+            }
+
+            $bodyRows = [];
+
+            foreach ($results as $row) {
+                $cells = [];
+
+                foreach ($columns as $column) {
+                    $value = $row[$column] ?? null;
+                    $cells[] = $value === null
+                        ? Td::tag()->html(Em::tag()->content('NULL'))
+                        : Td::tag()->content(is_scalar($value) ? (string) $value : Dump::export($value));
+                }
+
+                $bodyRows[] = Tr::tag()->html(...$cells);
+            }
+
+            $children[] = Div::tag()
+                ->class('yii-debug-explain-scroll')
+                ->html(
+                    Table::tag()
+                        ->class('yii-debug-table yii-debug-explain-table')
+                        ->html(
+                            Thead::tag()->html(Tr::tag()->html(...$headerCells)),
+                            Tbody::tag()->html(...$bodyRows),
+                        ),
+                );
+        }
+
+        return Div::tag()
+            ->class('yii-debug-explain')
+            ->html(...$children)
+            ->render();
+    }
+}

tests/Panel/Db/DbExplainRendererTest.php

@@ -0,0 +1,111 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Debug\Tests\Panel\Db;
+
+use PHPForge\Debug\Panel\Db\DbExplainRenderer;
+use PHPUnit\Framework\Attributes\Group;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Unit tests for {@see DbExplainRenderer} covering empty, failed, and tabular EXPLAIN result markup.
+ */
+#[Group('panel')]
+#[Group('db')]
+final class DbExplainRendererTest extends TestCase
+{
+    public function testRenderEmptyPlan(): void
+    {
+        self::assertSame(
+            <<<'HTML'
+            <div class="yii-debug-explain">
+            <h1 class="yii-debug-explain-title">
+            EXPLAIN
+            </h1><p class="yii-debug-explain-empty">
+            EXPLAIN returned no rows.
+            </p>
+            </div>
+            HTML,
+            DbExplainRenderer::render('', []),
+            'Empty plans must keep the shared title and empty-state contract.',
+        );
+    }
+
+    public function testRenderError(): void
+    {
+        self::assertSame(
+            <<<'HTML'
+            <div class="yii-debug-explain">
+            <h1 class="yii-debug-explain-title">
+            EXPLAIN
+            </h1><pre class="yii-debug-explain-query">
+            <span class="yii-debug-sql-kw">SELECT</span> <span class="yii-debug-sql-num">1</span>
+            </pre><p class="yii-debug-explain-empty">
+            EXPLAIN failed: database &lt;unavailable&gt;
+            </p>
+            </div>
+            HTML,
+            DbExplainRenderer::renderError('SELECT 1', 'database <unavailable>'),
+            'Failed plans must preserve the query and escape the driver error exactly.',
+        );
+    }
+
+    public function testRenderQueryAndResultTable(): void
+    {
+        self::assertSame(
+            <<<'HTML'
+            <div class="yii-debug-explain">
+            <h1 class="yii-debug-explain-title">
+            EXPLAIN
+            </h1><pre class="yii-debug-explain-query">
+            <span class="yii-debug-sql-kw">SELECT</span> * <span class="yii-debug-sql-kw">FROM</span> users
+            </pre><div class="yii-debug-explain-scroll">
+            <table class="yii-debug-table yii-debug-explain-table">
+            <thead>
+            <tr>
+            <th scope="col">
+            id
+            </th><th scope="col">
+            detail
+            </th>
+            </tr>
+            </thead><tbody>
+            <tr>
+            <td>
+            1
+            </td><td>
+            SCAN users
+            </td>
+            </tr><tr>
+            <td>
+            <em>NULL</em>
+            </td><td>
+            SEARCH users
+            </td>
+            </tr><tr>
+            <td>
+            2
+            </td><td>
+            [
+                'operator' =&gt; '&lt;scan&gt;',
+            ]
+            </td>
+            </tr>
+            </tbody>
+            </table>
+            </div>
+            </div>
+            HTML,
+            DbExplainRenderer::render(
+                'SELECT * FROM users',
+                [
+                    ['id' => 1, 'detail' => 'SCAN users'],
+                    ['id' => null, 'detail' => 'SEARCH users'],
+                    ['id' => 2, 'detail' => ['operator' => '<scan>']],
+                ],
+            ),
+            'A populated plan must render scalar, null, and escaped non-scalar cells exactly.',
+        );
+    }
+}