Top Bar

Barra superiore del sito — contiene navigazione secondaria, social link, link con logo, selezione lingua, user dropdown e pulsante di ricerca. Non è un landmark autonomo: viene incluso all’interno del componente @header.

Comportamento

Il componente viene renderizzato come <div class="rtds-top-bar">, non come elemento semantico <header> — il landmark è gestito dal componente padre @header.

La visibilità su mobile è controllata dal parametro mobileHidden: se true, aggiunge rtds-hidden lg:rtds-flex per nascondere la top bar sugli schermi piccoli.

Il template espone blocchi Nunjucks (leftArea, TopBarLinkLeft, secondaryNav, rightArea, TopBarLinkRight, userDropdown) per la personalizzazione nelle varianti.

La variante with-nav sostituisce il contenuto dell’area sinistra con un componente @primary-navigation tramite override del blocco leftArea.

Varianti

Varianti di configurazione

• default: Top bar completa con navigazione secondaria, social link, divisore verticale e pulsante di ricerca (modale semplice)
• with-nav: Area sinistra sostituita dalla navigazione primaria (@primary-navigation); visibile anche su mobile (mobileHidden: false)
• has-image-link-left: Senza navigazione secondaria; area sinistra con uno o più loghi/immagini linkati
• has-image-link-right: Area destra con uno o più loghi/immagini linkati
• user-dropdown / Utente loggato: Area destra con componente @user-dropdown in stato loggato (mostra menu a tendina profilo)
• utente-non-loggato: Area destra con componente @user-dropdown in stato non loggato (mostra pulsante “Login”)
• with-search-bar-modal: Modale di ricerca desktop con componente @search-bar completo (autocomplete, pulsante clear, link “Tutti i risultati”)

Parametri di configurazione

Contesto di sviluppo Fractal/Nunjucks — Questa sezione riguarda esclusivamente i parametri del context .config.yml usati durante lo sviluppo nella libreria.

Parametri Base

• classes (stringa, opzionale): Classi CSS aggiuntive sull’elemento radice .rtds-top-bar
• bgColor (stringa, opzionale): Classe Tailwind per il colore di sfondo (sovrascrive il default rtds-background-01)
• spacing (stringa, opzionale): Classi Tailwind per il padding (es. rtds-py-1 md:rtds-py-2 rtds-px-4)
• mobileHidden (booleano, opzionale): Se true, nasconde la top bar su mobile aggiungendo rtds-hidden lg:rtds-flex

Parametri Area Sinistra — Link con immagine

• topBarLinkLeft (array, opzionale): Elenco di loghi/immagini linkati nell’area sinistra. Ogni elemento accetta:
  • alt (stringa): Testo alternativo dell’immagine
  • link (stringa): URL del link
  • image (stringa): Percorso dell’immagine
  • width (numero): Attributo width dell’immagine
  • height (numero): Attributo height dell’immagine
  • imageSrcset (stringa, opzionale): Attributo srcset per immagini retina

Parametri Area Destra — Link con immagine

• topBarLinkRight (array, opzionale): Elenco di loghi/immagini linkati nell’area destra. Accetta le stesse proprietà di topBarLinkLeft

Parametri Componenti Integrati

• hasSecondaryNav (booleano, opzionale): Se true, renderizza il componente @secondary-navigation nell’area sinistra
• hasTopBarSocial (booleano, opzionale): Se true, renderizza il componente @social-links nell’area destra
• hasUserDropdown (booleano, opzionale): Se true, renderizza il componente @user-dropdown nell’area destra
• userDropdown (oggetto, opzionale): Contesto passato al componente @user-dropdown. Chiavi supportate:
  • isUserLoggedIn (booleano): Se true, mostra il menu a tendina del profilo; se false, mostra il pulsante “Login”
  • userDropdownId (stringa, opzionale): ID per l’elemento <ul> del menu a tendina (default: "userDropdown")
  • buttonClasses (stringa, opzionale): Classi CSS aggiuntive sul trigger button (default: "rtds-btn--only-text")
• hasVerticalDivider (booleano, opzionale): Se true, renderizza il componente @vertical-divider tra i controlli dell’area destra
• hasLanguageSelector (booleano, opzionale): Se true, mostra un segnaposto per il selettore di lingua

Parametri Ricerca

• hasSearchButton (booleano, opzionale): Se true, mostra il pulsante/trigger per la modale di ricerca desktop
• searchModalVariant (stringa, opzionale): Variante della modale di ricerca desktop:
  • null o non specificato: modale semplice con @input-field--search e @button--icon-right
  • "with-search-bar": modale con componente @search-bar completo (autocomplete, pulsante clear, dropdown risultati)
• searchButtonBorderColor (stringa, opzionale): Classe CSS per il colore del bordo del trigger button (default: "rtds-border-gray-03")
• searchButtonTextColor (stringa, opzionale): Classe CSS per il colore del testo del trigger button

Parametri aggiuntivi per searchModalVariant: "with-search-bar"

• searchId (stringa, opzionale): ID del campo di ricerca (default: "desktopSearchBar")
• searchLabel (stringa, opzionale): Label del campo di ricerca (default: "Cerca")
• searchSubmitLabel (stringa, opzionale): Testo del pulsante submit (default: "Cerca")
• showClearButton (booleano, opzionale): Mostra il pulsante per cancellare il testo (default: true)
• searchPlaceholder (stringa, opzionale): Placeholder del campo di ricerca (default: "Search")
• searchFormAction (stringa, opzionale): Attributo action del form di ricerca (default: "/search")
• searchFormMethod (stringa, opzionale): Attributo method del form di ricerca (default: "get")
• allResultsHref (stringa, opzionale): URL del link “Tutti i risultati” nel dropdown (default: "/search?q=")
• allResultsLabel (stringa, opzionale): Testo del link “Tutti i risultati” (default: "Tutti i risultati")

Accessibilità

WCAG 2.1

Livello AA — criteri pertinenti:

• 1.3.1 Informazioni e correlazioni — struttura con navigazione secondaria <nav> e social links con label descrittive
• 4.1.2 Nome, Ruolo, Valore — il trigger della modale di ricerca usa aria-haspopup, aria-controls e aria-expanded
• 2.4.1 Salto di blocchi — la top bar è inclusa nel landmark <header> tramite il componente @header

Struttura e semantica

• <div class="rtds-top-bar"> — non è un landmark autonomo; è parte del <header> del componente padre
• La navigazione secondaria è delegata al componente @secondary-navigation con il proprio <nav aria-label="..."> interno
• I social link sono delegati al componente @social-links con label descrittive per ogni link
• I link con immagine nell’area sinistra/destra sono renderizzati come <a href="..."><img alt="..."></a> — il testo alternativo dell’immagine fornisce il nome accessibile del link

Attributi ARIA

Navigazione da tastiera

Gestione del focus

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

Screen reader

• Il trigger del pulsante di ricerca include aria-haspopup="dialog" (annuncia l’apertura di una finestra modale), aria-controls="searchModal" e aria-expanded aggiornato dinamicamente da JavaScript
• I loghi nell’area sinistra/destra devono avere alt descrittivo (es. “Regione Toscana”, “Toscana Notizie”) per identificare la destinazione del link
• La gestione dell’attributo aria-expanded sul trigger di ricerca è implementata in search-modal-desktop.js

Stili CSS

Classi Base

• .rtds-top-bar: Elemento radice del componente; flex, items-center, sfondo rtds-background-01

Classi Elementi (BEM)

• .rtds-top-bar__container: Contenitore interno con larghezza controllata da .rtds-container; flex, items-center, lg:flex-1
• .rtds-top-bar__navigation: Area sinistra; grid su mobile, flex da lg; allinea logo e navigazione secondaria
• .rtds-top-bar__utilities-area: Area destra; flex, ml-auto; contiene social, user dropdown, link destra, selettore lingua, ricerca

Esempi di utilizzo

<!-- Top bar base con navigazione secondaria e ricerca -->
<div class="rtds-top-bar rtds-py-1 md:rtds-py-2 rtds-px-4 rtds-hidden lg:rtds-flex">
    <div class="rtds-top-bar__container rtds-container">
        <div class="rtds-top-bar__navigation rtds-grid lg:rtds-flex rtds-items-center rtds-gap-2 lg:rtds-gap-8">
            <!-- @secondary-navigation -->
        </div>
        <div class="rtds-top-bar__utilities-area rtds-flex lg:rtds-gap-4 rtds-ml-auto">
            <!-- @social-links -->
            <!-- @search-modal-desktop -->
        </div>
    </div>
</div>

<!-- Top bar con loghi a sinistra -->
<div class="rtds-top-bar">
    <div class="rtds-top-bar__container rtds-container">
        <div class="rtds-top-bar__navigation rtds-grid lg:rtds-flex rtds-items-center">
            <div class="rtds-flex rtds-gap-4 rtds-items-center">
                <a href="#" class="rtds-link">
                    <img src="/images/regione-toscana-min.png" alt="Regione Toscana" width="34" height="34">
                </a>
                <a href="#" class="rtds-link">
                    <img src="/images/toscana-notizie.png" alt="Toscana Notizie" width="147" height="28"
                         srcset="/images/toscana-notizie.png 1x, /images/toscana-notizie@2x.png 2x">
                </a>
            </div>
        </div>
        <div class="rtds-top-bar__utilities-area rtds-flex rtds-ml-auto">
            <!-- @search-modal-desktop -->
        </div>
    </div>
</div>

Scenari d’uso

Utente loggato — top bar con menu profilo

Imposta hasUserDropdown: true e userDropdown.isUserLoggedIn: true. Il componente @user-dropdown renderizza il menu a tendina con le voci di navigazione del profilo. Abbina hasTopBarSocial: false per eliminare i social link quando è presente l’area utente.

Utente non loggato — top bar con pulsante accesso

Imposta hasUserDropdown: true e userDropdown.isUserLoggedIn: false. Il componente @user-dropdown renderizza un pulsante “Login” con icona. Abbina hasTopBarSocial: false per coerenza visiva con il caso loggato.

Top bar senza area utente

Imposta hasUserDropdown: false (o ometti il parametro). La top bar non renderizza nessuna area utente — utile per siti istituzionali senza autenticazione.

Note

• Il componente non è un landmark autonomo: va sempre incluso all’interno di un elemento <header> (gestito dal componente @header)
• La variante with-nav sovrascrive il blocco leftArea tramite Nunjucks {% extends '@top-bar' %} — non usa i parametri topBarLinkLeft o hasSecondaryNav
• I blocchi Nunjucks disponibili per l’override sono: leftArea, TopBarLinkLeft, secondaryNav, rightArea, TopBarLinkRight, userDropdown
• La variante with-search-bar-modal richiede il componente @search-modal-desktop--with-search-bar e i relativi script JavaScript per l’autocomplete
• Limite noto della documentazione (non del componente): nella preview isolata di Fractal, aprire il dropdown della variante with-nav (@primary-navigation con voce “Dropdown”) può mostrare scrollbar orizzontale/verticale all’interno del riquadro di anteprima. Causa: il pannello di preview del tema Fractal (@frctl/mandelbrot) ha altezza fissa e ricalcola le dimensioni dell’iframe solo al load/resize, non quando un’interazione JS interna (apertura dropdown) fa crescere il contenuto. Non si verifica in una pagina reale, dove non c’è alcun wrapper ad altezza fissa attorno all’header (issue GitLab #29)