Add new UX Pagination component

.github/workflows/code-quality.yaml

@@ -119,7 +119,7 @@ jobs:
                       if jq -e '.private == true' "$file" > /dev/null; then
                           continue
                       fi
-                      peerDependencies=$(jq -r '.peerDependencies | keys[]' "$file")
+                      peerDependencies=$(jq -r '.peerDependencies // {} | keys[]' "$file")
                       for peerDependency in $peerDependencies; do
                           peerDependencyVersion=$(jq -r --arg dep "$peerDependency" '.peerDependencies[$dep]' "$file")
                           importmapVersion=$(jq -r ".symfony.importmap.\"$peerDependency\" | if type == \"string\" then . else .version end" "$file")

splitsh.json

@@ -15,6 +15,7 @@
         "ux-leaflet-map": "src/Map/src/Bridge/Leaflet",
         "ux-native": "src/Native",
         "ux-notify": "src/Notify",
+        "ux-pagination": "src/Pagination",
         "ux-react": "src/React",
         "ux-toolkit": "src/Toolkit",
         "ux-translator": "src/Translator",

src/Pagination/.gitattributes

@@ -0,0 +1,7 @@
+/.git* export-ignore
+/.symfony.bundle.yaml export-ignore
+/phpstan.dist.neon export-ignore
+/phpunit.dist.xml export-ignore
+/assets/src export-ignore
+/doc export-ignore
+/tests export-ignore

src/Pagination/.gitignore

@@ -0,0 +1,7 @@
+/assets/node_modules/
+/config/reference.php
+/vendor/
+/composer.lock
+/phpunit.xml
+/.phpunit.cache
+.DS_Store

src/Pagination/.symfony.bundle.yaml

@@ -0,0 +1,3 @@
+branches: ['3.x']
+maintained_branches: ['3.x']
+doc_dir: 'doc'

src/Pagination/CHANGELOG.md

@@ -0,0 +1,5 @@
+# CHANGELOG
+
+## 3.5.0
+
+- Add the component.

src/Pagination/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026-present Fabien Potencier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src/Pagination/README.md

@@ -0,0 +1,96 @@
+# Symfony UX Pagination
+
+**EXPERIMENTAL** This bundle is currently experimental and is likely to change,
+possibly significantly, before its first stable release.
+
+Ship stable cursor feeds or classic numbered pages through one request-aware
+Symfony service. PHP owns the query, Twig renders accessible navigation, and
+the browser follows ordinary links without requiring JavaScript.
+
+## Installation
+
+```bash
+composer require symfony/ux-pagination
+```
+
+## Usage
+
+```php
+// src/Controller/EventController.php
+namespace App\Controller;
+
+use App\Repository\EventRepository;
+use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\Routing\Attribute\Route;
+use Symfony\UX\Pagination\PaginatorInterface;
+
+final class EventController extends AbstractController
+{
+    #[Route('/events', name: 'event_index')]
+    public function __invoke(
+        EventRepository $events,
+        PaginatorInterface $paginator,
+    ): Response {
+        $pagination = $paginator
+            ->cursor($events->createQueryBuilder('event'))
+            ->orderBy(['createdAt', 'id'], 'DESC')
+            ->perPage(20)
+            ->paginate();
+
+        return $this->render('event/index.html.twig', [
+            'pagination' => $pagination,
+        ]);
+    }
+}
+```
+
+```twig
+{# templates/event/index.html.twig #}
+{% for event in pagination %}
+    <article>{{ event.name }}</article>
+{% endfor %}
+
+{{ ux_pagination(pagination) }}
+```
+
+The paginator reads and validates `?cursor=`, preserves the current filters and
+generates previous/next URLs. Use `query($source)` for numbered pagination or
+`query($source)->lookahead()` when the UI needs only previous/next without an
+exact total. Use `total($counter)` when an aggregate query needs an
+application-provided total; invokable Symfony services work directly.
+
+## What it provides
+
+- First-class signed cursor pagination with forward and backward navigation
+- Offset pagination with lazy totals and numbered pages
+- Lookahead pagination without a count query
+- Doctrine ORM 3 and DBAL 4.4+ adapters
+- Callback builders and custom adapters for APIs, search engines and
+  application sources
+- Request-aware URLs generated through the Symfony Router
+- Accessible, translated Twig navigation with Bootstrap, Tailwind and custom
+  themes, plus validated attribute hooks
+- Named paginator policies with Symfony autowiring
+- PHP, Twig, JSON and LiveComponent integration
+- Real test helpers for page, URL and signed-cursor behavior
+
+| Need                                                  | Strategy  |
+| ----------------------------------------------------- | --------- |
+| Resist offset shifts while ordered values stay stable | Cursor    |
+| Page numbers and an exact total                       | Offset    |
+| Previous/next without a total                         | Lookahead |
+
+## Documentation
+
+- [Getting started](doc/getting-started.rst)
+- [Choosing a strategy](doc/strategies.rst)
+- [Cursor pagination](doc/cursor.rst)
+- [Rendering and customization](doc/rendering.rst)
+- [Configuration](doc/configuration.rst)
+- [Testing](doc/testing.rst) and [debugging](doc/debugging.rst)
+
+The complete documentation is published on
+[symfony.com](https://symfony.com/bundles/ux-pagination/current/index.html).
+
+**This repository is a READ-ONLY subtree split.**

src/Pagination/assets/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026-present Fabien Potencier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src/Pagination/assets/package.json

@@ -0,0 +1,28 @@
+{
+    "name": "@symfony/ux-pagination",
+    "description": "Pagination controls for Symfony applications",
+    "license": "MIT",
+    "version": "3.5.0",
+    "keywords": [
+        "symfony-ux",
+        "pagination",
+        "paginator"
+    ],
+    "homepage": "https://ux.symfony.com/pagination",
+    "repository": "https://github.com/symfony/ux",
+    "type": "module",
+    "files": [
+        "dist"
+    ],
+    "style": "dist/style.min.css",
+    "exports": {
+        "./style.min.css": "./dist/style.min.css"
+    },
+    "config": {
+        "css_source": "src/style.css"
+    },
+    "scripts": {
+        "build": "node ../../../bin/build_package.ts .",
+        "watch": "node ../../../bin/build_package.ts . --watch"
+    }
+}

src/Pagination/assets/src/style.css

@@ -0,0 +1,109 @@
+/**
+ * UX Pagination styles.
+ *
+ * The component selectors are intentionally scoped: importing this file must
+ * not change unrelated aria-current elements in the app.
+ */
+
+.ux-pagination {
+    --ux-pagination-color: #1f2937;
+    --ux-pagination-muted-color: #6b7280;
+    --ux-pagination-border-color: #d1d5db;
+    --ux-pagination-background: #fff;
+    --ux-pagination-active-background: #111827;
+    --ux-pagination-active-color: #fff;
+    --ux-pagination-focus-color: #2563eb;
+
+    color: var(--ux-pagination-color);
+}
+
+.ux-pagination__info {
+    margin-block: 0 0.75rem;
+    color: var(--ux-pagination-muted-color);
+    font-size: 0.875rem;
+}
+
+.ux-pagination__list {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 0.375rem;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+}
+
+.ux-pagination__item {
+    display: inline-flex;
+}
+
+.ux-pagination__link {
+    display: inline-flex;
+    min-width: 2.5rem;
+    min-height: 2.5rem;
+    align-items: center;
+    justify-content: center;
+    padding: 0.5rem 0.75rem;
+    border: 1px solid var(--ux-pagination-border-color);
+    border-radius: 0.375rem;
+    background: var(--ux-pagination-background);
+    color: inherit;
+    line-height: 1;
+    text-decoration: none;
+}
+
+a.ux-pagination__link:hover {
+    border-color: currentColor;
+}
+
+.ux-pagination__link--current {
+    border-color: var(--ux-pagination-active-background);
+    background: var(--ux-pagination-active-background);
+    color: var(--ux-pagination-active-color);
+    font-weight: 600;
+}
+
+.ux-pagination__link--disabled {
+    cursor: not-allowed;
+    opacity: 0.55;
+}
+
+.ux-pagination__ellipsis {
+    display: inline-flex;
+    min-width: 2rem;
+    min-height: 2.5rem;
+    align-items: center;
+    justify-content: center;
+    color: var(--ux-pagination-muted-color);
+}
+
+.ux-pagination__link:focus-visible {
+    outline: 3px solid var(--ux-pagination-focus-color, #2563eb);
+    outline-offset: 2px;
+}
+
+.ux-pagination [aria-current='page'] {
+    font-weight: 600;
+}
+
+@media (prefers-color-scheme: dark) {
+    .ux-pagination {
+        --ux-pagination-color: #f3f4f6;
+        --ux-pagination-muted-color: #9ca3af;
+        --ux-pagination-border-color: #4b5563;
+        --ux-pagination-background: #111827;
+        --ux-pagination-active-background: #f3f4f6;
+        --ux-pagination-active-color: #111827;
+        --ux-pagination-focus-color: #60a5fa;
+    }
+}
+
+@media (prefers-contrast: more) {
+    .ux-pagination__link {
+        border: 1px solid currentColor;
+    }
+
+    .ux-pagination :focus-visible {
+        outline-width: 4px;
+    }
+}

src/Pagination/assets/tsconfig.json

@@ -0,0 +1,3 @@
+{
+    "extends": "../../../tsconfig.package.json"
+}