From 64e83fb9e2f1fc0e3d87f04a86999a0defb84874 Mon Sep 17 00:00:00 2001
From: WieszczY <wieszczy85@gmail.com>
Date: Fri, 25 Sep 2026 09:40:28 +0200
Subject: [PATCH 1/3] feat(ui): add stable table row identity

---
 src/UI/Component/DataTable.php                | 37 +++++++++++++---
 src/UI/Model/TableRow.php                     | 42 +++++++++++++++++++
 .../Theme/Base/Renderer/DataTableRenderer.php |  9 ++--
 tests/UI/UiDataStateTest.php                  | 27 ++++++++++++
 4 files changed, 105 insertions(+), 10 deletions(-)
 create mode 100644 src/UI/Model/TableRow.php

diff --git a/src/UI/Component/DataTable.php b/src/UI/Component/DataTable.php
index 4cffaef..98f33f5 100644
--- a/src/UI/Component/DataTable.php
+++ b/src/UI/Component/DataTable.php
@@ -7,16 +7,20 @@
 use SyntaxDevTeam\MiniPortal\UI\Contract\Component;
 use SyntaxDevTeam\MiniPortal\UI\Model\ComponentIdentity;
 use SyntaxDevTeam\MiniPortal\UI\Model\TableColumn;
+use SyntaxDevTeam\MiniPortal\UI\Model\TableRow;
 
 final readonly class DataTable implements Component
 {
+    /** @var list<TableRow> */
+    private array $tableRows;
+
     /**
      * @param list<TableColumn> $columns
-     * @param list<array<string, string|int|float|null>> $rows
+     * @param list<TableRow|array<string, string|int|float|null>> $rows
      */
     public function __construct(
         private array $columns,
-        private array $rows,
+        array $rows,
         public ?string $caption = null,
         public ?EmptyState $emptyState = null,
         private ?ComponentIdentity $componentIdentity = null,
@@ -39,9 +43,13 @@ public function __construct(
             $columnIds[$column->id] = true;
         }
 
+        $normalizedRows = [];
         foreach ($rows as $rowIndex => $row) {
+            $tableRow = $row instanceof TableRow ? $row : TableRow::anonymous($row);
+            $cells = $tableRow->cells();
+
             foreach ($columnIds as $columnId => $_present) {
-                if (!array_key_exists($columnId, $row)) {
+                if (!array_key_exists($columnId, $cells)) {
                     throw new \InvalidArgumentException(sprintf(
                         'Table row %d is missing column "%s".',
                         $rowIndex,
@@ -49,7 +57,7 @@ public function __construct(
                     ));
                 }
             }
-            foreach (array_keys($row) as $cellId) {
+            foreach (array_keys($cells) as $cellId) {
                 if (!isset($columnIds[$cellId])) {
                     throw new \InvalidArgumentException(sprintf(
                         'Table row %d contains unknown column "%s".',
@@ -58,7 +66,11 @@ public function __construct(
                     ));
                 }
             }
+
+            $normalizedRows[] = $tableRow;
         }
+
+        $this->tableRows = $normalizedRows;
     }
 
     public static function componentType(): string
@@ -82,9 +94,22 @@ public function columns(): array
         return $this->columns;
     }
 
-    /** @return list<array<string, string|int|float|null>> */
+    /**
+     * Backward-compatible scalar row view.
+     *
+     * @return list<array<string, string|int|float|null>>
+     */
     public function rows(): array
     {
-        return $this->rows;
+        return array_map(
+            static fn (TableRow $row): array => $row->cells(),
+            $this->tableRows,
+        );
+    }
+
+    /** @return list<TableRow> */
+    public function tableRows(): array
+    {
+        return $this->tableRows;
     }
 }
diff --git a/src/UI/Model/TableRow.php b/src/UI/Model/TableRow.php
new file mode 100644
index 0000000..ed1ea26
--- /dev/null
+++ b/src/UI/Model/TableRow.php
@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SyntaxDevTeam\MiniPortal\UI\Model;
+
+final readonly class TableRow
+{
+    /** @param array<string, string|int|float|null> $cells */
+    public function __construct(
+        public ?string $id,
+        private array $cells,
+    ) {
+        if ($id !== null && preg_match('/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/D', $id) !== 1) {
+            throw new \InvalidArgumentException('Table row ID must be a safe stable identifier.');
+        }
+        if ($cells === []) {
+            throw new \InvalidArgumentException('Table row requires at least one cell.');
+        }
+    }
+
+    /** @param array<string, string|int|float|null> $cells */
+    public static function anonymous(array $cells): self
+    {
+        return new self(null, $cells);
+    }
+
+    /** @return array<string, string|int|float|null> */
+    public function cells(): array
+    {
+        return $this->cells;
+    }
+
+    public function cell(string $columnId): string|int|float|null
+    {
+        if (!array_key_exists($columnId, $this->cells)) {
+            throw new \OutOfBoundsException(sprintf('Table row has no cell for column "%s".', $columnId));
+        }
+
+        return $this->cells[$columnId];
+    }
+}
diff --git a/src/UI/Theme/Base/Renderer/DataTableRenderer.php b/src/UI/Theme/Base/Renderer/DataTableRenderer.php
index df605bb..9f1b26e 100644
--- a/src/UI/Theme/Base/Renderer/DataTableRenderer.php
+++ b/src/UI/Theme/Base/Renderer/DataTableRenderer.php
@@ -20,7 +20,7 @@ public function render(Component $component, RendererRegistry $registry): string
         }
 
         $identity = Html::identityAttribute(new ComponentRendererIdentity($component));
-        if ($component->rows() === []) {
+        if ($component->tableRows() === []) {
             if ($component->emptyState === null) {
                 throw new \LogicException('Empty data table has no empty state.');
             }
@@ -40,17 +40,18 @@ public function render(Component $component, RendererRegistry $registry): string
         }
 
         $body = '';
-        foreach ($component->rows() as $row) {
+        foreach ($component->tableRows() as $row) {
             $cells = '';
             foreach ($component->columns() as $column) {
-                $value = $row[$column->id];
+                $value = $row->cell($column->id);
                 $class = $column->numeric ? ' class="mp-data-table__numeric"' : '';
                 $content = $value === null
                     ? '<span class="mp-data-table__missing" aria-label="Brak danych">—</span>'
                     : Html::escape((string) $value);
                 $cells .= '<td' . $class . '>' . $content . '</td>';
             }
-            $body .= '<tr>' . $cells . '</tr>';
+            $rowIdentity = $row->id === null ? '' : ' data-row-id="' . Html::escape($row->id) . '"';
+            $body .= '<tr' . $rowIdentity . '>' . $cells . '</tr>';
         }
 
         return '<div class="mp-data-table"' . $identity . '><table>'
diff --git a/tests/UI/UiDataStateTest.php b/tests/UI/UiDataStateTest.php
index 4c1b277..da45e0e 100644
--- a/tests/UI/UiDataStateTest.php
+++ b/tests/UI/UiDataStateTest.php
@@ -12,6 +12,7 @@
 use SyntaxDevTeam\MiniPortal\UI\Component\Pagination;
 use SyntaxDevTeam\MiniPortal\UI\Model\ComponentIdentity;
 use SyntaxDevTeam\MiniPortal\UI\Model\TableColumn;
+use SyntaxDevTeam\MiniPortal\UI\Model\TableRow;
 use SyntaxDevTeam\MiniPortal\UI\Theme\Base\BaseTheme;
 
 final class UiDataStateTest extends TestCase
@@ -42,6 +43,32 @@ public function testDataTableEscapesHeadersCaptionAndCells(): void
         self::assertStringNotContainsString('<script>', $html);
     }
 
+    public function testStableTableRowIdentityIsRenderedWithoutBreakingLegacyRows(): void
+    {
+        $table = new DataTable(
+            [new TableColumn('name', 'Nazwa')],
+            [
+                new TableRow('server:alpha', ['name' => 'Alpha']),
+                ['name' => 'Legacy'],
+            ],
+        );
+
+        $html = (new BaseTheme())->renderers()->render($table);
+
+        self::assertStringContainsString('data-row-id="server:alpha"', $html);
+        self::assertSame(
+            [['name' => 'Alpha'], ['name' => 'Legacy']],
+            $table->rows(),
+        );
+        self::assertNull($table->tableRows()[1]->id);
+    }
+
+    public function testTableRowRejectsUnsafeIdentity(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        new TableRow('<unsafe>', ['name' => 'Alpha']);
+    }
+
     public function testEmptyDataTableRequiresAndRendersExplicitEmptyState(): void
     {
         $table = new DataTable(

From dc4c82786b8721fe15c615a98bae73142d7d7775 Mon Sep 17 00:00:00 2001
From: WieszczY <wieszczy85@gmail.com>
Date: Fri, 25 Sep 2026 09:44:14 +0200
Subject: [PATCH 2/3] feat(ui): add server-driven table query controls

---
 src/UI/Catalog/BaseUiCatalog.php              | 20 ++--
 src/UI/Component/DataTable.php                | 15 ++-
 src/UI/Component/TableQueryControls.php       | 92 +++++++++++++++++++
 src/UI/Model/SortDirection.php                | 11 +++
 src/UI/Model/TableColumn.php                  |  9 ++
 src/UI/Model/TableFilter.php                  | 28 ++++++
 src/UI/Theme/Base/BaseTheme.php               |  3 +
 .../Theme/Base/Renderer/DataTableRenderer.php | 20 +++-
 .../Renderer/TableQueryControlsRenderer.php   | 48 ++++++++++
 tests/UI/BaseThemeTest.php                    |  5 +
 tests/UI/UiDataStateTest.php                  | 47 ++++++++++
 11 files changed, 287 insertions(+), 11 deletions(-)
 create mode 100644 src/UI/Component/TableQueryControls.php
 create mode 100644 src/UI/Model/SortDirection.php
 create mode 100644 src/UI/Model/TableFilter.php
 create mode 100644 src/UI/Theme/Base/Renderer/TableQueryControlsRenderer.php

diff --git a/src/UI/Catalog/BaseUiCatalog.php b/src/UI/Catalog/BaseUiCatalog.php
index 13f0e4e..a185483 100644
--- a/src/UI/Catalog/BaseUiCatalog.php
+++ b/src/UI/Catalog/BaseUiCatalog.php
@@ -20,6 +20,7 @@
 use SyntaxDevTeam\MiniPortal\UI\Component\Pagination;
 use SyntaxDevTeam\MiniPortal\UI\Component\PermissionDeniedState;
 use SyntaxDevTeam\MiniPortal\UI\Component\DegradedState;
+use SyntaxDevTeam\MiniPortal\UI\Component\TableQueryControls;
 use SyntaxDevTeam\MiniPortal\UI\Model\AlertSeverity;
 use SyntaxDevTeam\MiniPortal\UI\Model\ComponentIdentity;
 use SyntaxDevTeam\MiniPortal\UI\Model\PageRegion;
@@ -27,6 +28,9 @@
 use SyntaxDevTeam\MiniPortal\UI\Model\FormMethod;
 use SyntaxDevTeam\MiniPortal\UI\Model\InputType;
 use SyntaxDevTeam\MiniPortal\UI\Model\TableColumn;
+use SyntaxDevTeam\MiniPortal\UI\Model\TableFilter;
+use SyntaxDevTeam\MiniPortal\UI\Model\TableRow;
+use SyntaxDevTeam\MiniPortal\UI\Model\SortDirection;
 use SyntaxDevTeam\MiniPortal\UI\PageDefinition;
 
 final class BaseUiCatalog
@@ -53,14 +57,18 @@ public function page(): PageDefinition
                 new EmptyState('Brak wyników', 'Zmień filtry lub wyszukiwaną frazę.'),
                 new ErrorState('Nie udało się pobrać danych', 'Spróbuj ponownie później.', 'catalog-error-01'),
                 new DataTable([
-                    new TableColumn('name', 'Nazwa'),
-                    new TableColumn('status', 'Status'),
+                    new TableColumn('name', 'Nazwa', sortUrl: '/catalog?sort=name&direction=desc', sortDirection: SortDirection::Ascending),
+                    new TableColumn('status', 'Status', sortUrl: '/catalog?sort=status&direction=asc'),
                     new TableColumn('jobs', 'Zadania', true),
                 ], [
-                    ['name' => 'Core', 'status' => 'online', 'jobs' => 4],
-                    ['name' => 'Worker', 'status' => 'idle', 'jobs' => 0],
-                ], 'Usługi platformy'),
-                new Pagination(2, 3, '/catalog?page=1', '/catalog?page=3'),
+                    new TableRow('service:core', ['name' => 'Core', 'status' => 'online', 'jobs' => 4]),
+                    new TableRow('service:worker', ['name' => 'Worker', 'status' => 'idle', 'jobs' => 0]),
+                ], 'Usługi platformy', componentIdentity: new ComponentIdentity('catalog.services'), queryControls: new TableQueryControls(
+                    '/catalog',
+                    'core',
+                    filters: [new TableFilter('status', 'Status', ['' => 'Wszystkie', 'online' => 'Online', 'idle' => 'Idle'], '')],
+                    preservedParameters: ['sort' => 'name'],
+                ), pagination: new Pagination(2, 3, '/catalog?page=1', '/catalog?page=3')),
                 new PermissionDeniedState('Brak dostępu', 'Nie masz uprawnienia do tej sekcji.', 'admin.system.read'),
                 new DegradedState('Dane częściowe', 'Jedno ze źródeł jest chwilowo niedostępne.', [
                     new Text('Pozostałe dane pozostają dostępne.', TextTone::Muted),
diff --git a/src/UI/Component/DataTable.php b/src/UI/Component/DataTable.php
index 98f33f5..b12c1ca 100644
--- a/src/UI/Component/DataTable.php
+++ b/src/UI/Component/DataTable.php
@@ -24,6 +24,8 @@ public function __construct(
         public ?string $caption = null,
         public ?EmptyState $emptyState = null,
         private ?ComponentIdentity $componentIdentity = null,
+        public ?TableQueryControls $queryControls = null,
+        public ?Pagination $pagination = null,
     ) {
         if ($columns === []) {
             throw new \InvalidArgumentException('Data table requires at least one column.');
@@ -85,7 +87,18 @@ public function identity(): ?ComponentIdentity
 
     public function children(): array
     {
-        return $this->emptyState === null ? [] : [$this->emptyState];
+        $children = [];
+        if ($this->queryControls !== null) {
+            $children[] = $this->queryControls;
+        }
+        if ($this->emptyState !== null) {
+            $children[] = $this->emptyState;
+        }
+        if ($this->pagination !== null) {
+            $children[] = $this->pagination;
+        }
+
+        return $children;
     }
 
     /** @return list<TableColumn> */
diff --git a/src/UI/Component/TableQueryControls.php b/src/UI/Component/TableQueryControls.php
new file mode 100644
index 0000000..3707122
--- /dev/null
+++ b/src/UI/Component/TableQueryControls.php
@@ -0,0 +1,92 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SyntaxDevTeam\MiniPortal\UI\Component;
+
+use SyntaxDevTeam\MiniPortal\UI\Contract\Component;
+use SyntaxDevTeam\MiniPortal\UI\Model\ComponentIdentity;
+use SyntaxDevTeam\MiniPortal\UI\Model\TableFilter;
+
+final readonly class TableQueryControls implements Component
+{
+    /**
+     * @param list<TableFilter> $filters
+     * @param array<string, string> $preservedParameters
+     */
+    public function __construct(
+        public string $action,
+        public ?string $searchValue = null,
+        public ?string $searchParameter = 'q',
+        public string $searchLabel = 'Szukaj',
+        private array $filters = [],
+        private array $preservedParameters = [],
+        private ?ComponentIdentity $componentIdentity = null,
+    ) {
+        if (!self::isSafeUrl($action)) {
+            throw new \InvalidArgumentException('Table query action must be relative or HTTPS.');
+        }
+        if ($searchParameter !== null && preg_match('/^[a-z][a-z0-9_-]{0,63}$/D', $searchParameter) !== 1) {
+            throw new \InvalidArgumentException('Table search parameter must be a safe query parameter name.');
+        }
+        if ($searchParameter === null && $searchValue !== null) {
+            throw new \InvalidArgumentException('Search value requires an enabled search parameter.');
+        }
+        if ($searchParameter !== null && trim($searchLabel) === '') {
+            throw new \InvalidArgumentException('Enabled table search requires a label.');
+        }
+
+        $names = [];
+        if ($searchParameter !== null) {
+            $names[$searchParameter] = true;
+        }
+        foreach ($filters as $filter) {
+            if (isset($names[$filter->name])) {
+                throw new \InvalidArgumentException(sprintf('Duplicate table query parameter "%s".', $filter->name));
+            }
+            $names[$filter->name] = true;
+        }
+        foreach ($preservedParameters as $name => $_value) {
+            if (preg_match('/^[a-z][a-z0-9_-]{0,63}$/D', $name) !== 1 || isset($names[$name])) {
+                throw new \InvalidArgumentException(sprintf('Invalid or duplicate preserved query parameter "%s".', $name));
+            }
+            $names[$name] = true;
+        }
+        if ($searchParameter === null && $filters === [] && $preservedParameters === []) {
+            throw new \InvalidArgumentException('Table query controls require search, filters or preserved parameters.');
+        }
+    }
+
+    public static function componentType(): string
+    {
+        return 'table_query_controls';
+    }
+
+    public function identity(): ?ComponentIdentity
+    {
+        return $this->componentIdentity;
+    }
+
+    public function children(): array
+    {
+        return [];
+    }
+
+    /** @return list<TableFilter> */
+    public function filters(): array
+    {
+        return $this->filters;
+    }
+
+    /** @return array<string, string> */
+    public function preservedParameters(): array
+    {
+        return $this->preservedParameters;
+    }
+
+    private static function isSafeUrl(string $url): bool
+    {
+        return str_starts_with($url, '/')
+            || preg_match('/^https:\/\/[A-Za-z0-9.-]+(?::[0-9]+)?(?:\/|$)/D', $url) === 1;
+    }
+}
diff --git a/src/UI/Model/SortDirection.php b/src/UI/Model/SortDirection.php
new file mode 100644
index 0000000..d0f7d71
--- /dev/null
+++ b/src/UI/Model/SortDirection.php
@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SyntaxDevTeam\MiniPortal\UI\Model;
+
+enum SortDirection: string
+{
+    case Ascending = 'ascending';
+    case Descending = 'descending';
+}
diff --git a/src/UI/Model/TableColumn.php b/src/UI/Model/TableColumn.php
index fb811f4..a1cfb0a 100644
--- a/src/UI/Model/TableColumn.php
+++ b/src/UI/Model/TableColumn.php
@@ -10,9 +10,18 @@ public function __construct(
         public string $id,
         public string $label,
         public bool $numeric = false,
+        public ?string $sortUrl = null,
+        public ?SortDirection $sortDirection = null,
     ) {
         if (preg_match('/^[a-z][a-z0-9_.-]{0,63}$/D', $id) !== 1 || trim($label) === '') {
             throw new \InvalidArgumentException('Table column requires a valid ID and label.');
         }
+        if ($sortUrl !== null && !str_starts_with($sortUrl, '/')
+            && preg_match('/^https:\/\/[A-Za-z0-9.-]+(?::[0-9]+)?(?:\/|$)/D', $sortUrl) !== 1) {
+            throw new \InvalidArgumentException('Table sort URL must be relative or HTTPS.');
+        }
+        if ($sortDirection !== null && $sortUrl === null) {
+            throw new \InvalidArgumentException('Active table sort direction requires a sort URL.');
+        }
     }
 }
diff --git a/src/UI/Model/TableFilter.php b/src/UI/Model/TableFilter.php
new file mode 100644
index 0000000..54aa808
--- /dev/null
+++ b/src/UI/Model/TableFilter.php
@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SyntaxDevTeam\MiniPortal\UI\Model;
+
+final readonly class TableFilter
+{
+    /** @param array<string, string> $options */
+    public function __construct(
+        public string $name,
+        public string $label,
+        public array $options,
+        public ?string $selected = null,
+    ) {
+        if (preg_match('/^[a-z][a-z0-9_-]{0,63}$/D', $name) !== 1 || trim($label) === '' || $options === []) {
+            throw new \InvalidArgumentException('Table filter requires a valid name, label and options.');
+        }
+        foreach ($options as $optionLabel) {
+            if (trim($optionLabel) === '') {
+                throw new \InvalidArgumentException('Table filter option labels cannot be empty.');
+            }
+        }
+        if ($selected !== null && !array_key_exists($selected, $options)) {
+            throw new \InvalidArgumentException('Selected table filter value must exist in options.');
+        }
+    }
+}
diff --git a/src/UI/Theme/Base/BaseTheme.php b/src/UI/Theme/Base/BaseTheme.php
index 2577fa5..ecbada3 100644
--- a/src/UI/Theme/Base/BaseTheme.php
+++ b/src/UI/Theme/Base/BaseTheme.php
@@ -21,6 +21,7 @@
 use SyntaxDevTeam\MiniPortal\UI\Component\Pagination;
 use SyntaxDevTeam\MiniPortal\UI\Component\PermissionDeniedState;
 use SyntaxDevTeam\MiniPortal\UI\Component\DegradedState;
+use SyntaxDevTeam\MiniPortal\UI\Component\TableQueryControls;
 use SyntaxDevTeam\MiniPortal\UI\Rendering\RendererRegistry;
 use SyntaxDevTeam\MiniPortal\UI\PageDefinition;
 use SyntaxDevTeam\MiniPortal\UI\Theme\Base\Renderer\AlertRenderer;
@@ -39,6 +40,7 @@
 use SyntaxDevTeam\MiniPortal\UI\Theme\Base\Renderer\PaginationRenderer;
 use SyntaxDevTeam\MiniPortal\UI\Theme\Base\Renderer\PermissionDeniedStateRenderer;
 use SyntaxDevTeam\MiniPortal\UI\Theme\Base\Renderer\DegradedStateRenderer;
+use SyntaxDevTeam\MiniPortal\UI\Theme\Base\Renderer\TableQueryControlsRenderer;
 
 final class BaseTheme implements Theme
 {
@@ -76,6 +78,7 @@ public function renderers(): RendererRegistry
         $registry->register(Pagination::class, new PaginationRenderer());
         $registry->register(PermissionDeniedState::class, new PermissionDeniedStateRenderer());
         $registry->register(DegradedState::class, new DegradedStateRenderer());
+        $registry->register(TableQueryControls::class, new TableQueryControlsRenderer());
         return $registry;
     }
 
diff --git a/src/UI/Theme/Base/Renderer/DataTableRenderer.php b/src/UI/Theme/Base/Renderer/DataTableRenderer.php
index 9f1b26e..e2c4029 100644
--- a/src/UI/Theme/Base/Renderer/DataTableRenderer.php
+++ b/src/UI/Theme/Base/Renderer/DataTableRenderer.php
@@ -20,13 +20,15 @@ public function render(Component $component, RendererRegistry $registry): string
         }
 
         $identity = Html::identityAttribute(new ComponentRendererIdentity($component));
+        $controls = $component->queryControls === null ? '' : $registry->render($component->queryControls);
+        $pagination = $component->pagination === null ? '' : $registry->render($component->pagination);
         if ($component->tableRows() === []) {
             if ($component->emptyState === null) {
                 throw new \LogicException('Empty data table has no empty state.');
             }
 
             return '<div class="mp-data-table mp-data-table--empty"' . $identity . '>'
-                . $registry->render($component->emptyState) . '</div>';
+                . $controls . $registry->render($component->emptyState) . $pagination . '</div>';
         }
 
         $caption = $component->caption === null
@@ -36,7 +38,17 @@ public function render(Component $component, RendererRegistry $registry): string
         $head = '';
         foreach ($component->columns() as $column) {
             $class = $column->numeric ? ' class="mp-data-table__numeric"' : '';
-            $head .= '<th scope="col"' . $class . '>' . Html::escape($column->label) . '</th>';
+            $ariaSort = $column->sortDirection === null ? '' : ' aria-sort="' . $column->sortDirection->value . '"';
+            $label = Html::escape($column->label);
+            if ($column->sortUrl !== null) {
+                $indicator = match ($column->sortDirection) {
+                    \SyntaxDevTeam\MiniPortal\UI\Model\SortDirection::Ascending => ' <span aria-hidden="true">↑</span>',
+                    \SyntaxDevTeam\MiniPortal\UI\Model\SortDirection::Descending => ' <span aria-hidden="true">↓</span>',
+                    null => '',
+                };
+                $label = '<a class="mp-data-table__sort" href="' . Html::escape($column->sortUrl) . '">' . $label . $indicator . '</a>';
+            }
+            $head .= '<th scope="col"' . $class . $ariaSort . '>' . $label . '</th>';
         }
 
         $body = '';
@@ -54,7 +66,7 @@ public function render(Component $component, RendererRegistry $registry): string
             $body .= '<tr' . $rowIdentity . '>' . $cells . '</tr>';
         }
 
-        return '<div class="mp-data-table"' . $identity . '><table>'
-            . $caption . '<thead><tr>' . $head . '</tr></thead><tbody>' . $body . '</tbody></table></div>';
+        return '<div class="mp-data-table"' . $identity . '>' . $controls . '<table>'
+            . $caption . '<thead><tr>' . $head . '</tr></thead><tbody>' . $body . '</tbody></table>' . $pagination . '</div>';
     }
 }
diff --git a/src/UI/Theme/Base/Renderer/TableQueryControlsRenderer.php b/src/UI/Theme/Base/Renderer/TableQueryControlsRenderer.php
new file mode 100644
index 0000000..f8872f5
--- /dev/null
+++ b/src/UI/Theme/Base/Renderer/TableQueryControlsRenderer.php
@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SyntaxDevTeam\MiniPortal\UI\Theme\Base\Renderer;
+
+use SyntaxDevTeam\MiniPortal\UI\Component\TableQueryControls;
+use SyntaxDevTeam\MiniPortal\UI\Contract\Component;
+use SyntaxDevTeam\MiniPortal\UI\Rendering\ComponentRenderer;
+use SyntaxDevTeam\MiniPortal\UI\Rendering\ComponentRendererIdentity;
+use SyntaxDevTeam\MiniPortal\UI\Rendering\Html;
+use SyntaxDevTeam\MiniPortal\UI\Rendering\RendererRegistry;
+
+final class TableQueryControlsRenderer implements ComponentRenderer
+{
+    public function render(Component $component, RendererRegistry $_registry): string
+    {
+        if (!$component instanceof TableQueryControls) {
+            throw new \LogicException('TableQueryControlsRenderer received an unsupported component.');
+        }
+
+        $fields = '';
+        if ($component->searchParameter !== null) {
+            $value = $component->searchValue === null ? '' : ' value="' . Html::escape($component->searchValue) . '"';
+            $fields .= '<label class="mp-table-query__search"><span>' . Html::escape($component->searchLabel)
+                . '</span><input type="search" name="' . Html::escape($component->searchParameter) . '"' . $value . '></label>';
+        }
+
+        foreach ($component->filters() as $filter) {
+            $options = '';
+            foreach ($filter->options as $value => $label) {
+                $selected = $filter->selected === $value ? ' selected' : '';
+                $options .= '<option value="' . Html::escape($value) . '"' . $selected . '>'
+                    . Html::escape($label) . '</option>';
+            }
+            $fields .= '<label class="mp-table-query__filter"><span>' . Html::escape($filter->label)
+                . '</span><select name="' . Html::escape($filter->name) . '">' . $options . '</select></label>';
+        }
+
+        foreach ($component->preservedParameters() as $name => $value) {
+            $fields .= '<input type="hidden" name="' . Html::escape($name) . '" value="' . Html::escape($value) . '">';
+        }
+
+        return '<form class="mp-table-query" method="get" action="' . Html::escape($component->action) . '" role="search"'
+            . Html::identityAttribute(new ComponentRendererIdentity($component)) . '>'
+            . $fields . '<button type="submit">Zastosuj</button></form>';
+    }
+}
diff --git a/tests/UI/BaseThemeTest.php b/tests/UI/BaseThemeTest.php
index 791484d..eeec77e 100644
--- a/tests/UI/BaseThemeTest.php
+++ b/tests/UI/BaseThemeTest.php
@@ -23,6 +23,7 @@
 use SyntaxDevTeam\MiniPortal\UI\Component\Pagination;
 use SyntaxDevTeam\MiniPortal\UI\Component\PermissionDeniedState;
 use SyntaxDevTeam\MiniPortal\UI\Component\DegradedState;
+use SyntaxDevTeam\MiniPortal\UI\Component\TableQueryControls;
 use SyntaxDevTeam\MiniPortal\UI\Model\AlertSeverity;
 use SyntaxDevTeam\MiniPortal\UI\Model\ComponentIdentity;
 use SyntaxDevTeam\MiniPortal\UI\Model\PageRegion;
@@ -57,6 +58,7 @@ public function testEveryCurrentPublicComponentHasBaseRenderer(): void
             Pagination::class,
             PermissionDeniedState::class,
             DegradedState::class,
+            TableQueryControls::class,
         ], $registered);
     }
 
@@ -98,6 +100,9 @@ public function testCatalogExercisesEveryRegisteredComponent(): void
         self::assertStringContainsString('mp-pagination', $html);
         self::assertStringContainsString('mp-permission-denied-state', $html);
         self::assertStringContainsString('mp-degraded-state', $html);
+        self::assertStringContainsString('mp-table-query', $html);
+        self::assertStringContainsString('aria-sort="ascending"', $html);
+        self::assertStringContainsString('data-row-id="service:core"', $html);
     }
 
     public function testUnknownComponentFailsExplicitly(): void
diff --git a/tests/UI/UiDataStateTest.php b/tests/UI/UiDataStateTest.php
index da45e0e..1e20565 100644
--- a/tests/UI/UiDataStateTest.php
+++ b/tests/UI/UiDataStateTest.php
@@ -10,9 +10,12 @@
 use SyntaxDevTeam\MiniPortal\UI\Component\ErrorState;
 use SyntaxDevTeam\MiniPortal\UI\Component\LoadingState;
 use SyntaxDevTeam\MiniPortal\UI\Component\Pagination;
+use SyntaxDevTeam\MiniPortal\UI\Component\TableQueryControls;
 use SyntaxDevTeam\MiniPortal\UI\Model\ComponentIdentity;
 use SyntaxDevTeam\MiniPortal\UI\Model\TableColumn;
 use SyntaxDevTeam\MiniPortal\UI\Model\TableRow;
+use SyntaxDevTeam\MiniPortal\UI\Model\TableFilter;
+use SyntaxDevTeam\MiniPortal\UI\Model\SortDirection;
 use SyntaxDevTeam\MiniPortal\UI\Theme\Base\BaseTheme;
 
 final class UiDataStateTest extends TestCase
@@ -99,6 +102,50 @@ public function testRowsMustMatchDeclaredColumns(): void
         );
     }
 
+    public function testTableRendersServerDrivenQueryControlsSortAndPagination(): void
+    {
+        $table = new DataTable(
+            [
+                new TableColumn('name', 'Nazwa', sortUrl: '/items?sort=name&dir=desc', sortDirection: SortDirection::Ascending),
+                new TableColumn('status', 'Status'),
+            ],
+            [new TableRow('item:1', ['name' => 'A & B', 'status' => 'online'])],
+            queryControls: new TableQueryControls(
+                '/items',
+                '<query>',
+                filters: [new TableFilter('status', 'Status', ['' => 'Wszystkie', 'online' => 'Online'], 'online')],
+                preservedParameters: ['sort' => 'name'],
+            ),
+            pagination: new Pagination(1, 2, nextUrl: '/items?page=2'),
+        );
+
+        $html = (new BaseTheme())->renderers()->render($table);
+
+        self::assertStringContainsString('role="search"', $html);
+        self::assertStringContainsString('value="&lt;query&gt;"', $html);
+        self::assertStringContainsString('name="status"', $html);
+        self::assertStringContainsString('value="online" selected', $html);
+        self::assertStringContainsString('name="sort" value="name"', $html);
+        self::assertStringContainsString('aria-sort="ascending"', $html);
+        self::assertStringContainsString('href="/items?sort=name&amp;dir=desc"', $html);
+        self::assertStringContainsString('mp-pagination', $html);
+    }
+
+    public function testQueryControlsRejectDuplicateParameterNames(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        new TableQueryControls(
+            '/items',
+            filters: [new TableFilter('q', 'Status', ['' => 'Wszystkie'])],
+        );
+    }
+
+    public function testSortableColumnRejectsUnsafeUrl(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        new TableColumn('name', 'Nazwa', sortUrl: 'javascript:alert(1)');
+    }
+
     public function testPaginationRendersServerDrivenBoundaryLinks(): void
     {
         $pagination = new Pagination(2, 4, '/items?page=1&filter=a', '/items?page=3&filter=a');

From b15f84a86a7e0f140b50b6ff482fba4566416a41 Mon Sep 17 00:00:00 2001
From: WieszczY <wieszczy85@gmail.com>
Date: Fri, 25 Sep 2026 09:44:47 +0200
Subject: [PATCH 3/3] docs(ui): document table query contract

---
 docs/05-UI-COMPONENT-MODEL.md     | 25 +++++++++++++++++--------
 docs/16-IMPLEMENTATION-BACKLOG.md | 10 ++++++----
 2 files changed, 23 insertions(+), 12 deletions(-)

diff --git a/docs/05-UI-COMPONENT-MODEL.md b/docs/05-UI-COMPONENT-MODEL.md
index 3477095..63fa25f 100644
--- a/docs/05-UI-COMPONENT-MODEL.md
+++ b/docs/05-UI-COMPONENT-MODEL.md
@@ -205,14 +205,23 @@ Tabela jest częstym źródłem duplikacji. Publiczny Table contract powinien ws
 
 Na mobile Theme może zmienić tabelę w zestaw kart, jeśli zachowane są semantyka i dostęp do tych samych działań.
 
-Pierwszy baseline `DataTable` posiada jawny zestaw `TableColumn`, waliduje
-unikalność kolumn i zgodność każdego wiersza ze schematem, nie przyjmuje surowego
-HTML w komórkach oraz wymaga jawnego `EmptyState`, gdy wynik jest pusty. Renderer
-Base Theme używa semantycznego `<table>`, `scope="col"`, caption i bezpiecznego
-escape wartości. `Pagination` opisuje bieżącą/łączną liczbę stron oraz bezpieczne
-linki poprzednia/następna i sprawdza ich zgodność z granicami zbioru. Sort,
-filtry, search, row identifiers oraz row/bulk actions pozostają kolejnym etapem
-Table API.
+Baseline `DataTable` posiada jawny zestaw `TableColumn`, waliduje unikalność
+kolumn i zgodność każdego wiersza ze schematem, nie przyjmuje surowego HTML w
+komórkach oraz wymaga jawnego `EmptyState`, gdy wynik jest pusty. `TableRow`
+umożliwia nadanie stabilnego, bezpiecznego identyfikatora wiersza; dla zgodności
+proste tablice skalarów nadal są przyjmowane jako anonimowe wiersze.
+
+Server-driven query API obejmuje `TableQueryControls`: wyszukiwanie i filtry są
+zwykłym formularzem GET, mogą zachowywać jawnie wskazane parametry zapytania, a
+sortowanie jest deklarowane per `TableColumn` jako bezpieczny URL i opcjonalny
+`SortDirection`. Renderer Base Theme generuje semantyczny `<table>`,
+`scope="col"`, `aria-sort`, caption i centralny escape wartości. `Pagination`
+może być częścią `DataTable` i opisuje bieżącą/łączną liczbę stron oraz
+bezpieczne linki poprzednia/następna.
+
+Źródło danych jako osobny kontrakt oraz row/bulk actions pozostają kolejnym
+etapem. Mutujące akcje tabeli nie mogą być dodane jako przypadkowe linki;
+kontrakt musi uwzględnić metodę żądania, CSRF i confirmation semantics.
 
 ## 7. Actions i Intents
 
diff --git a/docs/16-IMPLEMENTATION-BACKLOG.md b/docs/16-IMPLEMENTATION-BACKLOG.md
index 073d2e6..4afc32e 100644
--- a/docs/16-IMPLEMENTATION-BACKLOG.md
+++ b/docs/16-IMPLEMENTATION-BACKLOG.md
@@ -213,10 +213,12 @@ mutujących providerów pozostają do wykonania.
 - pagination,
 - row/bulk actions.
 
-Baseline gotowy: `TableColumn`, ścisła walidacja schematu wierszy, bezpieczne
-renderowanie skalarów, jawny empty state oraz serwerowa paginacja poprzednia /
-następna. Następny slice obejmuje źródło danych, sort/filter/search,
-identyfikatory wierszy i akcje row/bulk.
+Baseline rozszerzony: `TableColumn`, `TableRow` ze stabilnym identity, ścisła
+walidacja schematu wierszy, bezpieczne renderowanie skalarów, jawny empty state,
+`TableQueryControls` dla server-driven search/filter, deklaratywne sortowanie z
+`aria-sort` oraz paginacja poprzednia/następna. Następny slice obejmuje osobny
+kontrakt źródła danych oraz row/bulk actions z poprawnym CSRF, metodą żądania i
+confirmation semantics.
 
 ### E5. States