Paginazione

Il componente Paginazione gestisce la navigazione tra le pagine di un contenuto. Supporta diverse varianti di visualizzazione e offre una navigazione accessibile.

Comportamento

Il componente è sempre renderizzato come <nav role="navigation" aria-label="Paginazione"> contenente un <ul> con un <li> per ogni elemento. I link con sola icona (prima/ultima/precedente/successiva pagina) hanno aria-label descrittivo; i link con testo visibile (“Precedente”, “Successiva”) non usano aria-label — il testo è già il nome accessibile. La pagina corrente ha aria-current="page". Quando il componente si trova alla prima o ultima pagina, i link di navigazione corrispondenti ricevono aria-disabled="true".

Varianti

Varianti di Stile

• pagination--rounded: Versione con bordi arrotondati
• pagination--text: Versione con etichette testuali (“Precedente”/“Successiva”) invece di icone

Varianti di Stato

• first-page: Prima pagina attiva — link “Prima pagina” e “Pagina precedente” con aria-disabled="true"
• last-page: Ultima pagina attiva — link “Pagina successiva” e “Ultima pagina” con aria-disabled="true"

Varianti di Layout

• centered: Paginazione centrata orizzontalmente
• con-totale: Testo totale elementi inline nella nav (es. “100-110 di 300 elementi”)
• con-per-page: Selettore “Risultati per pagina” dentro il <nav>, allineato a destra tramite rtds-ml-auto
• con-totale-e-per-page: Combinazione totale elementi + selettore per-page, entrambi dentro il <nav>
• con-totale-e-per-page-centered: Come sopra, con paginazione centrata

Parametri di configurazione

Contesto di sviluppo Fractal/Nunjucks — Questa sezione riguarda esclusivamente i parametri del context .config.yml usati durante lo sviluppo nella libreria. Non descrive attributi HTML o proprietà da usare nei temi, CMS o ambienti di implementazione: per quello, fare riferimento alla sezione Esempi di utilizzo.

Parametri Base

• classes (stringa, opzionale): Classi CSS aggiuntive per il componente
• padding (stringa, opzionale): Classi per il padding
• centered (booleano, opzionale): Se true, centra la paginazione orizzontalmente
• hasLabels (booleano, opzionale): Se true, usa etichette testuali (“Precedente”/“Successiva”) invece di icone
• linkClasses (stringa, opzionale): Classi CSS aggiuntive per i link
• isFirstPage (booleano, opzionale, default false): Se true, aggiunge aria-disabled="true" sui link di navigazione verso le pagine precedenti
• isLastPage (booleano, opzionale, default false): Se true, aggiunge aria-disabled="true" sui link di navigazione verso le pagine successive
• totalText (stringa, opzionale): Testo totale elementi (es. "100-110 di 300 elementi") mostrato inline nella nav; se assente nessun elemento renderizzato
• items (array, obbligatorio): Elementi della paginazione
  • isCurrent (booleano, opzionale): Indica se l’elemento è la pagina corrente
  • label (stringa, obbligatorio): Etichetta dell’elemento

Parametri varianti con-per-page e con-totale-e-per-page

Tutti i parametri base, più:

• perPageId (stringa, obbligatorio): ID usato per <label for> e <select id> — deve essere univoco nella pagina
• perPageOptions (array, obbligatorio): Opzioni del selettore; ogni elemento ha:
  • value (stringa/numero): valore dell’<option>
  • label (stringa): testo visibile dell’<option>
• perPageSelected (stringa/numero, opzionale): Valore dell’opzione selezionata

Accessibilità

WCAG 2.1

Livello AA — criteri pertinenti:

• 1.3.1 Informazioni e correlazioni — la struttura è comunicata tramite <nav> e <ul> semanticamente corretti per la navigazione paginata
• 2.4.8 Posizione — aria-current="page" sulla pagina corrente comunica la posizione nella paginazione
• 4.1.2 Nome, ruolo, valore — ogni link icona ha un aria-label descrittivo; aria-current identifica la pagina corrente; aria-disabled comunica lo stato disabilitato

Struttura e semantica

• Il componente è renderizzato come <nav role="navigation" aria-label="Paginazione"> — identifica la regione di navigazione e la distingue da altri elementi <nav> nella pagina
• La lista è un <ul> con <li> per ogni elemento di paginazione
• I link icona-only (chevron) hanno aria-label descrittivi (“Prima pagina”, “Pagina precedente”, “Pagina successiva”, “Ultima pagina”)
• I link con testo visibile (“Precedente”, “Successiva”) non usano aria-label — il testo è già il nome accessibile

Attributi ARIA

Navigazione da tastiera

Stato disabilitato (aria-disabled)

aria-disabled="true" viene usato invece di disabled perché l’attributo disabled non è valido su elementi <a>. Il link rimane focusabile e annuncia lo stato “disabilitato” agli screen reader. Il consumer deve gestire lato JS il blocco della navigazione quando aria-disabled è presente (es. event.preventDefault() sul click).

Gestione del focus

• Focus visibile: lo stile :focus-visible è sempre visibile e non viene rimosso via CSS

Screen reader

• Ogni link icona viene annunciato con il proprio aria-label (es. “Prima pagina”, “Pagina precedente”)
• I link con testo visibile (“Precedente”, “Successiva”) non hanno aria-label — il testo è già il nome accessibile; aggiungere un aria-label ridondante potrebbe divergere dal testo visibile
• La pagina corrente è identificata da aria-current="page", che gli screen reader annunciano come “pagina corrente”
• I link con aria-disabled="true" vengono annunciati come disabilitati ma rimangono nel tab order; il consumer è responsabile di prevenire la navigazione via JS o event.preventDefault()

Esempi di utilizzo

<!-- Esempio base -->
<nav class="rtds-pagination rtds-flex-wrap" role="navigation" aria-label="Paginazione">
  <ul class="rtds-pagination__list">
    <li>
      <a href="#" aria-label="Prima pagina" class="rtds-pagination__link rtds-pagination__link-button">
        <svg class="rtds-icon" aria-hidden="true" focusable="false"><use href="#mini--chevron-double-left"></use></svg>
      </a>
    </li>
    <li>
      <a href="#" aria-label="Pagina precedente" class="rtds-pagination__link rtds-pagination__link-button">
        <svg class="rtds-icon" aria-hidden="true" focusable="false"><use href="#mini--chevron-left"></use></svg>
      </a>
    </li>
    <li>
      <a href="#" aria-label="pagina 1" class="rtds-pagination__link rtds-pagination__link-button rtds-pagination__link-text">1</a>
    </li>
    <li>
      <a href="#" aria-label="Pagina corrente, pagina 2" aria-current="page" class="rtds-pagination__link rtds-pagination__link-button rtds-pagination__link-text rtds-background-primary rtds-border-primary rtds-text-white">2</a>
    </li>
    <li>
      <a href="#" aria-label="pagina 3" class="rtds-pagination__link rtds-pagination__link-button rtds-pagination__link-text">3</a>
    </li>
    <li>
      <a href="#" aria-label="Pagina successiva" class="rtds-pagination__link rtds-pagination__link-button">
        <svg class="rtds-icon" aria-hidden="true" focusable="false"><use href="#mini--chevron-right"></use></svg>
      </a>
    </li>
    <li>
      <a href="#" aria-label="Ultima pagina" class="rtds-pagination__link rtds-pagination__link-button">
        <svg class="rtds-icon" aria-hidden="true" focusable="false"><use href="#mini--chevron-double-right"></use></svg>
      </a>
    </li>
  </ul>
</nav>

<!-- Esempio: prima pagina (link prev/first disabilitati) -->
<nav class="rtds-pagination rtds-flex-wrap" role="navigation" aria-label="Paginazione">
  <ul class="rtds-pagination__list">
    <li>
      <a href="#" aria-label="Prima pagina" aria-disabled="true" class="rtds-pagination__link rtds-pagination__link-button">
        <svg class="rtds-icon" aria-hidden="true" focusable="false"><use href="#mini--chevron-double-left"></use></svg>
      </a>
    </li>
    <li>
      <a href="#" aria-label="Pagina precedente" aria-disabled="true" class="rtds-pagination__link rtds-pagination__link-button">
        <svg class="rtds-icon" aria-hidden="true" focusable="false"><use href="#mini--chevron-left"></use></svg>
      </a>
    </li>
    <li>
      <a href="#" aria-label="Pagina corrente, pagina 1" aria-current="page" class="rtds-pagination__link rtds-pagination__link-button rtds-pagination__link-text rtds-background-primary rtds-border-primary rtds-text-white">1</a>
    </li>
    <li>
      <a href="#" aria-label="pagina 2" class="rtds-pagination__link rtds-pagination__link-button rtds-pagination__link-text">2</a>
    </li>
    <!-- ... -->
  </ul>
</nav>

<!-- Esempio: variante con totale elementi -->
<nav class="rtds-pagination rtds-flex-wrap" role="navigation" aria-label="Paginazione">
  <ul class="rtds-pagination__list">
    <!-- ... -->
  </ul>
  <p class="rtds-pagination__total rtds-px-4">100-110 di 300 elementi</p>
</nav>

<!-- Esempio: variante con selettore per-page (per-page dentro nav, allineato a destra) -->
<nav class="rtds-pagination rtds-flex-wrap" role="navigation" aria-label="Paginazione">
  <ul class="rtds-pagination__list">
    <!-- ... -->
  </ul>
  <div class="rtds-pagination-per-page rtds-px-2 rtds-ml-auto">
    <label for="per-page-select">Risultati per pagina</label>
    <div class="rtds-select rtds-select--sm">
      <select id="per-page-select" name="per-page-select">
        <option value="10" selected>10</option>
        <option value="25">25</option>
        <option value="50">50</option>
      </select>
    </div>
  </div>
</nav>

<!-- Esempio: variante con totale + per-page -->
<nav class="rtds-pagination rtds-flex-wrap" role="navigation" aria-label="Paginazione">
  <ul class="rtds-pagination__list">
    <!-- ... -->
  </ul>
  <p class="rtds-pagination__total rtds-px-4">100-110 di 300 elementi</p>
  <div class="rtds-pagination-per-page rtds-px-2 rtds-ml-auto">
    <label for="per-page-select-totale">Risultati per pagina</label>
    <div class="rtds-select rtds-select--sm">
      <select id="per-page-select-totale" name="per-page-select-totale">
        <option value="10" selected>10</option>
        <option value="25">25</option>
        <option value="50">50</option>
      </select>
    </div>
  </div>
</nav>