Popover

Componente non-modal che mostra contenuto ricco (testo, link, markup HTML) in un pannello sovrapposto, attivato da un click esplicito dell’utente. Diverso dal tooltip, che si apre su hover e contiene solo testo descrittivo.

Comportamento

Il componente produce due elementi indipendenti nel markup — collegati tramite ID, non da un wrapper comune:

• <button> — trigger che apre/chiude il pannello; usa l’attributo nativo popovertarget
• <div popover> — pannello flottante che contiene il contenuto ricco

Il posizionamento del pannello è gestito tramite progressive enhancement a 3 livelli (vedi Note).

Varianti

• popover (default): trigger testuale, pannello con titolo visibile
• no-title: pannello senza titolo visibile; richiede ariaLabel obbligatorio
• with-close: aggiunge un pulsante di chiusura esplicito in fondo al pannello
• icon-trigger: trigger a icona con label sr-only

Parametri di configurazione

Contesto di sviluppo Fractal/Nunjucks — parametri del context .config.yml usati nella libreria.

Parametri Base

• popoverId (stringa, opzionale, default: "popover"): ID condiviso tra trigger e pannello. Deve essere univoco per pagina se il componente appare più volte.
• triggerLabel (stringa, obbligatorio): Testo del trigger. Diventa sr-only se triggerIconOnly: true.
• title (stringa, opzionale): Titolo visibile nel pannello. Se presente, genera aria-labelledby sul pannello.
• headingTag (stringa, opzionale, default: h3): Tag HTML del titolo visibile. Valori: h2–h6.
• ariaLabel (stringa, opzionale): Nome accessibile del pannello quando title è assente. Obbligatorio se title non viene fornito.
• body (stringa, obbligatorio): Contenuto HTML del pannello — renderizzato con | safe.
• dismissible (booleano, opzionale, default: false): Se true, mostra il pulsante di chiusura dopo il body.
• dismissLabel (stringa, opzionale, default: "Chiudi"): Label sr-only del pulsante di chiusura.
• placement (stringa, opzionale, default: "bottom"): Placement preferito del panel: bottom | top | left | right. Il JS usa questo come preferenza e fa flip automatico se non c’è spazio.

Parametri per Trigger Icona

• triggerIconOnly (booleano, opzionale, default: false): Se true, la label del trigger è sr-only e l’icona è visibile.
• triggerIcon (stringa, opzionale, default: "mini--information-circle"): ID dell’icona dallo sprite SVG. Attivo solo con triggerIconOnly: true.

Accessibilità

WCAG 2.1

Livello AA — criteri pertinenti:

• 1.3.1 Informazioni e correlazioni — struttura semantica del pannello
• 2.1.1 Tastiera — apertura, chiusura e navigazione senza mouse
• 2.4.3 Ordine del focus — focus coerente all’apertura e alla chiusura
• 4.1.2 Nome, Ruolo, Valore — trigger con aria-expanded, pannello con nome accessibile

Struttura e semantica

• <button> — ruolo implicito button; attivabile con Enter e Space; trigger del pannello
• <div popover> — contenitore del pannello; agisce come dialog nel Livello 3 (attributo role="dialog" aggiunto via JS)

Attributi ARIA

Regola nome accessibile: almeno uno tra title e ariaLabel deve essere sempre fornito.

Navigazione da tastiera

Gestione del focus

• Focus all’apertura: rimane sul trigger; il pannello non cattura focus automaticamente
• Focus restoration: alla chiusura (ESC o pulsante close) il focus torna al trigger
• Focus visibile: stile :focus-visible applicato su .rtds-popover__body per scroll da tastiera

Screen reader

• aria-expanded — sul trigger; aggiornato via JS; comunica lo stato aperto/chiuso
• aria-labelledby o aria-label — sul pannello; fornisce il nome accessibile annunciato all’apertura
• <span class="rtds-sr-only"> — nel trigger icona-only; contiene triggerLabel; l’icona SVG ha aria-hidden="true" implicitamente via @icon
• tabindex="0" sul body — consente lo scroll da tastiera su contenuto lungo

Stili CSS

Classi Elementi (BEM)

• .rtds-popover__trigger: Pulsante trigger; nessuno stile base imposto, il consumer applica le classi rtds-btn--* desiderate
• .rtds-popover__panel: Pannello flottante con sfondo, bordo, ombra e posizionamento assoluto
• .rtds-popover__header: Intestazione del pannello; contiene il titolo
• .rtds-popover__title: Titolo visibile nel pannello
• .rtds-popover__body: Area del contenuto ricco; con tabindex="0" per scroll da tastiera
• .rtds-popover__close: Pulsante di chiusura esplicito; posizionato in basso a destra del pannello — classi: rtds-btn rtds-btn--icon rtds-btn--outlined rtds-border-none rtds-content-01 hover:rtds-bg-black focus:rtds-content-03 rtds-w-8 rtds-h-8

Tematizzazione

Il componente espone variabili CSS per la personalizzazione dal CMS ospitante. Il CMS può sovrascrivere le variabili Tier 1; se non sovrascritte, usano i token semantici del DS.

Override pubblici (Tier 1)

Token semantici DS (Tier 2)

Esempi di utilizzo

<!-- Popover con titolo (default) -->
<button type="button"
  class="rtds-popover__trigger rtds-btn rtds-btn--secondary"
  popovertarget="esempio-1"
  aria-expanded="false">
  Maggiori informazioni
</button>

<div popover id="esempio-1"
  class="rtds-popover__panel"
  data-preferred-placement="bottom"
  aria-labelledby="esempio-1-title">
  <div class="rtds-popover__arrow" aria-hidden="true"></div>
  <div data-popover>
    <div id="esempio-1-title" class="rtds-popover__header">
      <h3 class="rtds-popover__title">Titolo pannello</h3>
    </div>
    <div class="rtds-popover__body" tabindex="0">
      <p>Contenuto ricco con eventuale <a href="#">link</a>.</p>
    </div>
  </div>
</div>

<!-- Senza titolo (ariaLabel obbligatorio) -->
<button type="button"
  class="rtds-popover__trigger rtds-btn rtds-btn--text"
  popovertarget="esempio-2"
  aria-expanded="false">
  Informazioni aggiuntive
</button>

<div popover id="esempio-2"
  class="rtds-popover__panel"
  data-preferred-placement="bottom"
  aria-label="Informazioni aggiuntive">
  <div class="rtds-popover__arrow" aria-hidden="true"></div>
  <div data-popover>
    <div class="rtds-popover__body" tabindex="0">
      <p>Contenuto senza heading visibile.</p>
    </div>
  </div>
</div>

<!-- Con pulsante di chiusura esplicito -->
<div popover id="esempio-3"
  class="rtds-popover__panel"
  data-preferred-placement="bottom"
  aria-labelledby="esempio-3-title">
  <div class="rtds-popover__arrow" aria-hidden="true"></div>
  <div data-popover>
    <div id="esempio-3-title" class="rtds-popover__header">
      <h3 class="rtds-popover__title">Titolo pannello</h3>
    </div>
    <div class="rtds-popover__body" tabindex="0">
      <p>Contenuto ricco.</p>
    </div>
    <button type="button"
      class="rtds-btn rtds-btn--icon rtds-btn--outlined rtds-border-none rtds-content-01 hover:rtds-bg-black focus:rtds-content-03 rtds-w-8 rtds-h-8 rtds-popover__close">
      <!-- icona mini--x-mark -->
      <span class="rtds-sr-only">Chiudi</span>
    </button>
  </div>
</div>

Note

• Tooltip vs Popover: usa il tooltip (@tooltip) per testo descrittivo su hover; usa il popover per contenuto ricco (link, markup) aperto su click esplicito.
• Nome accessibile obbligatorio: almeno uno tra i parametri title (rtds-popover__title, heading del popover) e ariaLabel (aria-label su elemento popover) deve essere sempre fornito — il pannello senza nome accessibile non è conforme WCAG 4.1.2.
• ID univoci: se il componente appare più volte nella stessa pagina, ogni istanza deve avere un popoverId diverso.
• Body con link: i link nel parametro body devono avere testo descrittivo (non “clicca qui”).
• Progressive enhancement JS: il componente richiede popover.js. Browser con supporto nativo alla Popover API usano il Level 1/2; browser senza supporto usano il Level 3 con toggle manuale hidden.
• Non usare role="alert": il popover è contenuto non urgente aperto su azione utente; non usare live region.
• Dipende da: @icon (variante icon-trigger e pulsante with-close)