Pagination

Pagination (UI) — Design System (Symfony UX Toolkit / shadcn)

BASE CONGELADA (não mude por instância): Congelados: o nav centralizado (role=navigation, aria-label "pagination"); os botões de página como icon-buttons (ghost quando inativo, outline + aria-current="page" quando ativo); Anterior/Próxima com chevron + rótulo responsivo e aria-label "Go to previous/next page"; a Elipse (aria-hidden, sr-only "More pages"); o suporte a RTL; e tipografia, cantos, cores dos botões e o espaçamento gap-0.5 do Content. Nada disso muda ao ligar/desligar capacidades.

USO: <twig:Pagination />

CAPACIDADES OPT-IN (ligue sem alterar o visual):
- Saltos de extremidade (Primeira/Última): Adiciona botões « e » para pular direto à primeira e à última página, além do anterior/próxima. [toggle]- Janela de páginas: Controla quantos números aparecem ao redor da página atual antes de colapsar em elipse. [select → Compacta (1 vizinha) / Equilibrada (2 vizinhas) / Ampla (3 vizinhas) / Todas as páginas]- Ir para página: Campo para digitar o número da página e saltar direto a ela; útil em conjuntos com muitas páginas. [toggle]- Contador de resultados: Texto aditivo informando o intervalo/total exibido, derivado da página atual e do total. [select → Mostrando X–Y de N / Página X de Y / N resultados / X–Y]- Itens por página: Seletor de quantos itens carregar por página; a capacidade define quais tamanhos são oferecidos. [multi → 10 / 20 / 50 / 100]- Sincronizar com a URL: Reflete a página atual na URL para deep-link, favoritos e o botão Voltar do navegador. [select → Query (?page=N) / Hash (#page-N) / Caminho (/pagina/N)]- Navegação por teclado: Setas ←/→ mudam de página e Home/End vão à primeira/última quando a navegação tem foco. [toggle]- Auto-ocultar: Esconde toda a navegação quando há apenas uma página (ou nenhum resultado). [toggle]- Estilo do Anterior/Próxima: Escolhe a composição de conteúdo do anterior/próxima sem mexer no botão-base. [select → Ícone + rótulo / Só ícone (tooltip) / Só rótulo]FAÇA:
- Use <twig:Nome> — a base é congelada, você é dono do template em templates/components/.
- Ligue apenas capacidades opt-in listadas (e_funcao=true); a aparência não muda ao ligá-las.
- Passe atributos extras (id, aria-*, name, data-*) via {{ attributes }}.
NÃO FAÇA:
- Não mude cor/fonte/cantos/espaçamento por instância — é decisão de BASE, na fonte única assets/styles/app.css.
- Não crie variante/fork para a mesma coisa — existe UMA base por componente.
- Não reimplemente o componente nem adicione toolchain Node.
TESTE ANTES DE MUDAR: "é função ou é base?" — função = capacidade opt-in; base = mude o token na fonte única (assets/styles/app.css), para todos.

A11Y (herdada da base): Congelados: o nav centralizado (role=navigation, aria-label "pagination"). os botões de página como icon-buttons (ghost quando inativo, outline + aria-current="page" quando ativo). Anterior/Próxima com chevron + rótulo responsivo e aria-label "Go to previous/next page"

{
    "$schema_version": "1.0",
    "id": "pagination",
    "component": "Pagination",
    "eixo": "ui",
    "particularidade": "Pagination é o único componente cuja função é mover-se por um índice finito de páginas: sua essência é a relação entre \"página atual\", \"total de páginas/itens\" e a janela de números visíveis (anterior, próxima, números e a elipse de colapso). Todos os enriquecedores giram em torno de navegar esse índice com mais controle, sem tocar na aparência dos botões.",
    "base_congelada": "Congelados: o nav centralizado (role=navigation, aria-label \"pagination\"); os botões de página como icon-buttons (ghost quando inativo, outline + aria-current=\"page\" quando ativo); Anterior/Próxima com chevron + rótulo responsivo e aria-label \"Go to previous/next page\"; a Elipse (aria-hidden, sr-only \"More pages\"); o suporte a RTL; e tipografia, cantos, cores dos botões e o espaçamento gap-0.5 do Content. Nada disso muda ao ligar/desligar capacidades.",
    "props": [],
    "capacidades": [
        {
            "id": "saltos-de-extremidade-primeira-ltima",
            "nome": "Saltos de extremidade (Primeira/Última)",
            "descricao": "Adiciona botões « e » para pular direto à primeira e à última página, além do anterior/próxima.",
            "controle": "toggle",
            "opcoes": [],
            "posicionavel": false,
            "e_funcao": true,
            "como_plugar": "Capacidade opt-in (toggle). Ligue no configurador em /vitrine/ui/pagination; comportamento via controller Stimulus. Não altera a base."
        },
        {
            "id": "janela-de-p-ginas",
            "nome": "Janela de páginas",
            "descricao": "Controla quantos números aparecem ao redor da página atual antes de colapsar em elipse.",
            "controle": "select",
            "opcoes": [
                "Compacta (1 vizinha)",
                "Equilibrada (2 vizinhas)",
                "Ampla (3 vizinhas)",
                "Todas as páginas"
            ],
            "posicionavel": false,
            "e_funcao": true,
            "como_plugar": "Capacidade opt-in (select). Ligue no configurador em /vitrine/ui/pagination; comportamento via controller Stimulus. Não altera a base."
        },
        {
            "id": "ir-para-p-gina",
            "nome": "Ir para página",
            "descricao": "Campo para digitar o número da página e saltar direto a ela; útil em conjuntos com muitas páginas.",
            "controle": "toggle",
            "opcoes": [],
            "posicionavel": true,
            "e_funcao": true,
            "como_plugar": "Capacidade opt-in (toggle). Ligue no configurador em /vitrine/ui/pagination; comportamento via controller Stimulus. Não altera a base."
        },
        {
            "id": "contador-de-resultados",
            "nome": "Contador de resultados",
            "descricao": "Texto aditivo informando o intervalo/total exibido, derivado da página atual e do total.",
            "controle": "select",
            "opcoes": [
                "Mostrando X–Y de N",
                "Página X de Y",
                "N resultados",
                "X–Y"
            ],
            "posicionavel": true,
            "e_funcao": true,
            "como_plugar": "Capacidade opt-in (select). Ligue no configurador em /vitrine/ui/pagination; comportamento via controller Stimulus. Não altera a base."
        },
        {
            "id": "itens-por-p-gina",
            "nome": "Itens por página",
            "descricao": "Seletor de quantos itens carregar por página; a capacidade define quais tamanhos são oferecidos.",
            "controle": "multi",
            "opcoes": [
                "10",
                "20",
                "50",
                "100"
            ],
            "posicionavel": true,
            "e_funcao": true,
            "como_plugar": "Capacidade opt-in (multi). Ligue no configurador em /vitrine/ui/pagination; comportamento via controller Stimulus. Não altera a base."
        },
        {
            "id": "sincronizar-com-a-url",
            "nome": "Sincronizar com a URL",
            "descricao": "Reflete a página atual na URL para deep-link, favoritos e o botão Voltar do navegador.",
            "controle": "select",
            "opcoes": [
                "Query (?page=N)",
                "Hash (#page-N)",
                "Caminho (/pagina/N)"
            ],
            "posicionavel": false,
            "e_funcao": true,
            "como_plugar": "Capacidade opt-in (select). Ligue no configurador em /vitrine/ui/pagination; comportamento via controller Stimulus. Não altera a base."
        },
        {
            "id": "navega-o-por-teclado",
            "nome": "Navegação por teclado",
            "descricao": "Setas ←/→ mudam de página e Home/End vão à primeira/última quando a navegação tem foco.",
            "controle": "toggle",
            "opcoes": [],
            "posicionavel": false,
            "e_funcao": true,
            "como_plugar": "Capacidade opt-in (toggle). Ligue no configurador em /vitrine/ui/pagination; comportamento via controller Stimulus. Não altera a base."
        },
        {
            "id": "auto-ocultar",
            "nome": "Auto-ocultar",
            "descricao": "Esconde toda a navegação quando há apenas uma página (ou nenhum resultado).",
            "controle": "toggle",
            "opcoes": [],
            "posicionavel": false,
            "e_funcao": true,
            "como_plugar": "Capacidade opt-in (toggle). Ligue no configurador em /vitrine/ui/pagination; comportamento via controller Stimulus. Não altera a base."
        },
        {
            "id": "estilo-do-anterior-pr-xima",
            "nome": "Estilo do Anterior/Próxima",
            "descricao": "Escolhe a composição de conteúdo do anterior/próxima sem mexer no botão-base.",
            "controle": "select",
            "opcoes": [
                "Ícone + rótulo",
                "Só ícone (tooltip)",
                "Só rótulo"
            ],
            "posicionavel": false,
            "e_funcao": true,
            "como_plugar": "Capacidade opt-in (select). Ligue no configurador em /vitrine/ui/pagination; comportamento via controller Stimulus. Não altera a base."
        }
    ],
    "snippet_uso": "<twig:Pagination />",
    "exemplo_demo": "<twig:Pagination>\n    <twig:Pagination:Content>\n        <twig:Pagination:Item>\n            <twig:Pagination:Previous href=\"#\" />\n        </twig:Pagination:Item>\n        <twig:Pagination:Item>\n            <twig:Pagination:Link href=\"#\">1</twig:Pagination:Link>\n        </twig:Pagination:Item>\n        <twig:Pagination:Item>\n            <twig:Pagination:Link href=\"#\" active>2</twig:Pagination:Link>\n        </twig:Pagination:Item>\n        <twig:Pagination:Item>\n            <twig:Pagination:Link href=\"#\">3</twig:Pagination:Link>\n        </twig:Pagination:Item>\n        <twig:Pagination:Item>\n            <twig:Pagination:Ellipsis />\n        </twig:Pagination:Item>\n        <twig:Pagination:Item>\n            <twig:Pagination:Next href=\"#\" />\n        </twig:Pagination:Item>\n    </twig:Pagination:Content>\n</twig:Pagination>",
    "regras": {
        "faca": [
            "Use <twig:Nome> — a base é congelada, você é dono do template em templates/components/.",
            "Ligue apenas capacidades opt-in listadas (e_funcao=true); a aparência não muda ao ligá-las.",
            "Passe atributos extras (id, aria-*, name, data-*) via {{ attributes }}."
        ],
        "nao_faca": [
            "Não mude cor/fonte/cantos/espaçamento por instância — é decisão de BASE, na fonte única assets/styles/app.css.",
            "Não crie variante/fork para a mesma coisa — existe UMA base por componente.",
            "Não reimplemente o componente nem adicione toolchain Node."
        ]
    },
    "a11y": "Congelados: o nav centralizado (role=navigation, aria-label \"pagination\"). os botões de página como icon-buttons (ghost quando inativo, outline + aria-current=\"page\" quando ativo). Anterior/Próxima com chevron + rótulo responsivo e aria-label \"Go to previous/next page\"",
    "mcp": {
        "tool": "get_component",
        "args": {
            "id": "pagination"
        }
    },
    "props_nota": "Sem props próprias declaradas: a base repassa atributos nativos via {{ attributes }} (id, name, type, value, aria-*, data-*). Props específicas, quando existem, ficam nos subcomponentes."
}