mypgs 1.6.0 → 2.0.0

package/templates/html/components/accordion.html

@@ -1,5 +1,34 @@
-<ul pgs="grid-1 gapTexts">
-    <li pgs="accordion" >
+<!--
+/**
+* @title Accordion
+* @description Componente interattivo che espande un pannello alla volta, sincronizzando visibilità, attributi ARIA e navigazione da tastiera.
+*
+* @pgs
+* - accordion: identifica ogni elemento espandibile inizializzato dal modulo JavaScript.
+* - accordion-button: identifica il controllo che apre o chiude il pannello associato.
+* - accordion-content: identifica il pannello di contenuto gestito tramite l'attributo hidden.
+*
+* @pgs-state
+* - open: indica l'elemento accordion attualmente aperto e visibile.
+*
+* @api
+* - pgs.accordion.init(root): inizializza gli accordion non ancora registrati dentro Document o Element indicato.
+* - pgs.accordion.api(element): restituisce l'istanza associata a un root accordion inizializzato.
+* - instance.open(): apre il pannello e chiude gli altri accordion presenti nella pagina.
+* - instance.close(): chiude il pannello corrente.
+* - instance.toggle(): inverte lo stato aperto o chiuso del pannello.
+* - instance.refresh(): riesegue l'inizializzazione nel contenitore dell'accordion e restituisce l'istanza.
+* - instance.isOpen(): restituisce true quando lo stato open è attivo.
+*
+* @related
+* - flexColumnTexts: applica la spaziatura testuale tra gli elementi della lista.
+*
+* @return Lista HTML di elementi accordion accessibili con pulsante e pannello associato.
+*/
+-->
+
+<ul pgs="flexColumnTexts">
+    <li pgs="accordion">
         <button pgs="accordion-button" type="button">
             <i class="fa-solid fa-circle-question" aria-hidden="true"></i>
             <span>Domanda frequente</span>
@@ -10,7 +39,7 @@
         </div>
     </li>
 
-    <li pgs="accordion" >
+    <li pgs="accordion">
         <button pgs="accordion-button" type="button">
             <i class="fa-solid fa-circle-info" aria-hidden="true"></i>
             <span>Seconda sezione</span>
@@ -20,4 +49,4 @@
             <p>Altro contenuto del pannello accordion.</p>
         </div>
     </li>
-</ul>
+</ul>

package/templates/html/components/badges.html

@@ -1,3 +1,26 @@
+<!--
+/**
+ * @title Badge
+ * @description Raccolta di indicatori compatti per mostrare categorie, priorità e stati visivi con varianti cromatiche coerenti.
+ *
+ * @pgs
+ * - badge: identifica la variante base del badge.
+ * - badgePrimary: applica la variante con colore primario.
+ * - badgeStrong: applica la variante ad alto contrasto.
+ * - badgeSuccess: rappresenta un esito positivo.
+ * - badgeDot: aggiunge un indicatore puntiforme al badge.
+ * - badgeWarning: rappresenta un avviso.
+ * - badgeError: rappresenta un errore.
+ * - badgeInfo: rappresenta un'informazione.
+ * - badgeNeutral: applica la variante neutra.
+ *
+ * @related
+ * - flexRow: dispone i badge orizzontalmente consentendo il ritorno a capo.
+ *
+ * @return Esempi HTML delle varianti badge disponibili.
+ */
+-->
+
 <div pgs="flexRow">
     <span pgs="badge">
         Base

package/templates/html/components/breadcumbs.html

@@ -1,3 +1,17 @@
+<!--
+/**
+ * @title Breadcrumb
+ * @description Navigazione gerarchica che mostra il percorso della pagina corrente con collegamenti, separatori e indicazione semantica dell'elemento attivo.
+ *
+ * @pgs
+ * - breadcrumb: identifica la lista principale del percorso di navigazione.
+ * - breadcrumb-item: identifica ogni livello del percorso.
+ * - breadcrumb-item-separator: identifica il separatore decorativo nascosto alle tecnologie assistive.
+ *
+ * @return Struttura HTML semantica di una breadcrumb racchiusa in un elemento nav.
+ */
+-->
+
 <nav aria-label="Breadcrumb">
     <ul pgs="breadcrumb">
         <li pgs="breadcrumb-item">

package/templates/html/components/button.html

@@ -1,3 +1,25 @@
+<!--
+/**
+ * @title Button
+ * @description Varianti di pulsante e collegamento d'azione con dimensioni, enfasi e composizione icona-testo definite dal design system.
+ *
+ * @pgs
+ * - button: identifica il pulsante standard utilizzabile anche su elementi a.
+ * - buttonStrong: applica la variante con maggiore enfasi visiva.
+ * - buttonIcon: identifica un pulsante compatto composto principalmente da un'icona.
+ * - buttonMini: applica la variante di dimensione minima.
+ * - buttonBig: applica la variante di dimensione ampia.
+ *
+ * @pgs-option
+ * - buttonReverse: inverte l'ordine visivo di testo e icona sul pulsante a cui è applicata.
+ *
+ * @related
+ * - flexRow: dispone gli esempi di pulsante su una riga flessibile.
+ *
+ * @return Raccolta HTML delle principali varianti di button.
+ */
+-->
+
 <div pgs="flexRow">
     <a pgs="button" href="#">
         <i class="fa-duotone fa-solid fa-store"></i>

package/templates/html/components/card.html

@@ -1,3 +1,23 @@
+<!--
+/**
+ * @title Card
+ * @description Contenitore riutilizzabile per raggruppare immagine, titolo, testo e azioni in anteprime o raccolte responsive.
+ *
+ * @pgs
+ * - card: identifica il contenitore principale della scheda.
+ * - card-img: identifica l'immagine principale della card.
+ *
+ * @related
+ * - flex-2: dispone le card in un layout responsive a due elementi.
+ * - flexColumn: organizza verticalmente il contenuto della card o del relativo link.
+ * - imgCover: adatta l'immagine riempiendo l'area disponibile.
+ * - flexColumnTexts: applica la spaziatura verticale ai contenuti testuali.
+ * - button: presenta il collegamento finale come pulsante standard.
+ *
+ * @return Due strutture HTML di card, una con azione separata e una interamente cliccabile.
+ */
+-->
+
 <div pgs="flex-2">
 
     <article pgs="card flexColumn">

package/templates/html/components/dropdown.html

@@ -1,3 +1,37 @@
+<!--
+/**
+ * @title Dropdown
+ * @description Componente a comparsa che associa un controllo a un contenuto posizionato rispetto al trigger e gestisce apertura, chiusura, click esterno ed Escape.
+ *
+ * @pgs
+ * - dropdown: identifica il contenitore inizializzato dal modulo dropdown.
+ * - dropdown-button: identifica il controllo che apre o chiude il contenuto.
+ * - dropdown-content: identifica il pannello posizionato rispetto al controllo.
+ *
+ * @pgs-option
+ * - position: configura il root come position[lato allineamento]; lato accetta top, right, bottom o left e l'allineamento compatibile accetta top, right, bottom, left o center. Il valore predefinito è bottom center.
+ * - buttonReverse: inverte testo e icona sui pulsanti di esempio e appartiene al componente button.
+ *
+ * @pgs-state
+ * - open: indica che il dropdown è aperto e che il contenuto è visibile.
+ *
+ * @api
+ * - pgs.dropdown.init(root): inizializza i dropdown non ancora registrati dentro Document o Element indicato.
+ * - pgs.dropdown.api(element): restituisce l'istanza associata a un root dropdown inizializzato.
+ * - instance.open(): apre il dropdown, chiudendo eventuali altri dropdown aperti.
+ * - instance.close(): chiude il dropdown corrente.
+ * - instance.toggle(): inverte lo stato aperto o chiuso.
+ * - instance.refresh(): reinizializza il contesto e ricalcola il posizionamento del contenuto.
+ * - instance.isOpen(): restituisce true quando il dropdown è aperto.
+ *
+ * @related
+ * - flexRow: dispone i diversi esempi di posizionamento sulla stessa riga flessibile.
+ * - button: applica lo stile standard ai controlli del dropdown.
+ *
+ * @return Serie di dropdown HTML che dimostra le direzioni di posizionamento supportate.
+ */
+-->
+
 <div pgs="flexRow">
 
     <span pgs="dropdown">

package/templates/html/components/form.html

@@ -1,18 +1,62 @@
-<form pgs="form" action="#" method="post">
+<!--
+/**
+ * @title Form
+ * @description Struttura di modulo con etichette, campi testuali, textarea e controllo toggle compatibile con i vincoli HTML e con regole personalizzate di PGS_formValidate.
+ *
+ * @pgs
+ * - form: identifica il contenitore del modulo e applica il layout dei campi.
+ * - formValidate: abilita gli stili associati agli stati di validazione gestiti dalla utility JavaScript.
+ * - label: identifica le etichette associate ai controlli.
+ * - input: applica lo stile condiviso agli input testuali.
+ * - textarea: applica lo stile condiviso all'area di testo.
+ * - toggle: presenta una checkbox come controllo a due stati.
+ *
+ * @pgs-option
+ * - message: definisce il messaggio specifico del campo con la sintassi message[Testo del messaggio].
+ * - error: viene applicata a runtime al form e ai campi che non superano la validazione.
+ * - success: viene applicata a runtime al form quando la validazione ha esito positivo.
+ *
+ * @api
+ * - new pgs.formValidate(form, options): crea una utility associata direttamente al form, aggiunge automaticamente novalidate e accetta fieldError, fieldsError e success in options.message; i messaggi restano modificabili tramite instance.message.
+ * - instance.validator(callback, eventName): intercetta l'evento indicato, previene il comportamento predefinito, valida il form, mostra il messaggio di successo e richiama callback solo quando è valido; eventName usa submit come valore predefinito.
+ * - instance.validate(): valida i campi required, aggiorna gli attributi di stato e restituisce true o false.
+ * - instance.success(text): valida il form e mostra un toast positivo quando non sono presenti errori.
+ * - instance.addNewRule(rule): aggiunge una funzione che restituisce uno o più campi non validi; validate applica automaticamente addFieldError a ciascun campo.
+ * - instance.addFieldError(field, index, total): marca un campo come non valido; mostra il messaggio specifico per un solo errore o un messaggio riepilogativo per più errori.
+ * - instance.removeFieldError(field): rimuove lo stato di errore dal campo indicato.
+ *
+ * @related
+ * - buttonStrong: presenta l'invio del modulo come azione primaria.
+ *
+ * @return Modulo HTML completo con campi required e script di esempio per una regola personalizzata, la validazione e il messaggio di successo.
+ */
+-->
+
+<form pgs="form formValidate" action="#" method="post">
     <label pgs="label" for="form-name">
         Nome
     </label>
-    <input id="form-name" pgs="input" type="text" name="name" placeholder="Mario Rossi" required data-form-field-message="Inserisci il nome">
+    <input id="form-name" pgs="input" pgs-option="message[Inserisci il nome]" type="text" name="name" placeholder="Mario Rossi" required>
 
     <label pgs="label" for="form-email">
         Email
     </label>
-    <input id="form-email" pgs="input" type="email" name="email" placeholder="nome@example.com" required data-form-field-message="Inserisci una email valida">
+    <input id="form-email" pgs="input" pgs-option="message[Inserisci una email valida]" type="email" name="email" placeholder="nome@example.com" required>
+
+    <label pgs="label" for="form-password">
+        Password
+    </label>
+    <input id="form-password" pgs="input" pgs-option="message[Inserisci una password]" type="password" name="password" autocomplete="new-password" required>
+
+    <label pgs="label" for="form-confirm-password">
+        Conferma password
+    </label>
+    <input id="form-confirm-password" pgs="input" pgs-option="message[Conferma la password]" type="password" name="confirmPassword" autocomplete="new-password" required>
 
     <label pgs="label" for="form-message">
         Messaggio
     </label>
-    <textarea id="form-message" pgs="textarea" name="message" rows="5" placeholder="Scrivi il messaggio"></textarea>
+    <textarea id="form-message" pgs="textarea" name="message" rows="5" placeholder="Scrivi il messaggio" required></textarea>
 
     <label pgs="toggle">
         <span>Accetto la privacy policy</span>
@@ -24,3 +68,37 @@
         Invia
     </button>
 </form>
+
+<script type="module">
+    import { pgs } from "mypgs";
+
+    const form = pgs(document).querySelector("form");
+
+    const password = form.querySelector('input[name="password"]');
+    const confirmPassword = form.querySelector('input[name="confirmPassword"]');
+    if (!password || !confirmPassword) return;
+
+    const formValidate = new pgs.formValidate(form, {
+        message: {
+            fieldError: "Completa questo campo",
+            fieldsError: "Completa tutti i campi obbligatori",
+            success: "Inviato con successo"
+        }
+    });
+
+    //== new roules
+    formValidate.addNewRule(() => {
+        if (password.value && confirmPassword.value && password.value !== confirmPassword.value) {
+            pgs(confirmPassword).option.setValueBrackets("message", "Le password non coincidono");
+            return [confirmPassword, password];
+        }
+    });
+
+    //== validate
+    formValidate.validator(event => {
+        const values = Object.fromEntries(new FormData(form));
+
+        // Sostituisci questo log con l'invio dei dati al tuo backend.
+        console.log(values);
+    }, "submit");
+</script>

package/templates/html/components/logo.html

@@ -1,3 +1,24 @@
+<!--
+/**
+ * @title Logo
+ * @description Componente per mostrare un logo grafico o testuale, con supporto alle varianti dell'immagine legate al tema scuro.
+ *
+ * @pgs
+ * - logo: identifica il collegamento contenitore del marchio.
+ * - logo-image: identifica l'immagine grafica del logo.
+ * - logo-text: identifica la variante testuale del marchio.
+ *
+ * @pgs-option
+ * - logoDarkmode: inverte l'immagine del logo quando lo stato globale darkmode è attivo.
+ * - logoDarkmodeFixed: mantiene applicata l'inversione dell'immagine indipendentemente dal tema corrente.
+ *
+ * @pgs-state
+ * - darkmode: stato globale applicato al documento che attiva la variante logoDarkmode.
+ *
+ * @return Esempi HTML del logo grafico sensibile al tema e del logo testuale.
+ */
+-->
+
 <a aria-label="Logo" pgs="logo" pgs-option="logoDarkmode" href="/">
     <img pgs="logo-image" src="https://placehold.co/240x80?text=MyPGS" alt="MyPGS">
 </a>

package/templates/html/components/menu.html

@@ -1,3 +1,36 @@
+<!--
+/**
+ * @title Menu
+ * @description Navigazione orizzontale o verticale che trasforma le voci con sottomenu in dropdown accessibili e inizializzati automaticamente.
+ *
+ * @pgs
+ * - menu: identifica il contenitore di navigazione elaborato dal modulo menu.
+ * - menu-buttonIcon: identifica il controllo creato dinamicamente accanto alle voci con sottomenu.
+ *
+ * @pgs-option
+ * - horizontal: dispone il menu e i suoi elementi in orizzontale.
+ * - vertical: dispone il menu e i suoi elementi in verticale.
+ * - menuHeader: adatta spaziature e comportamento del menu quando è inserito nell'header.
+ * - position: viene impostata come position[bottom right] sui dropdown creati per i sottomenu.
+ *
+ * @pgs-state
+ * - open: indica il sottomenu trasformato in dropdown attualmente aperto.
+ *
+ * @api
+ * - pgs.menu.init(root): inizializza i menu non ancora registrati dentro Document o Element indicato e prepara i sottomenu.
+ * - pgs.menu.api(element): restituisce l'istanza associata a un root menu inizializzato.
+ * - instance.refresh(): riesegue l'inizializzazione nel contenitore del menu e restituisce l'istanza.
+ *
+ * @related
+ * - dropdown: viene aggiunto dinamicamente alle voci che contengono una lista annidata.
+ * - dropdown-button: identifica il controllo dinamico del sottomenu.
+ * - buttonNohover: neutralizza lo stile hover del controllo dinamico.
+ * - dropdown-content: identifica la lista annidata mostrata come pannello dropdown.
+ *
+ * @return Due strutture nav complete per le varianti orizzontale e verticale del menu.
+ */
+-->
+
 <nav pgs="menu" pgs-option="horizontal" aria-label="Menu orizzontale">
     <ul>
         <li>
@@ -16,12 +49,6 @@
                 <li><a href="/servizi/due">Servizio due</a></li>
             </ul>
         </li>
-        <li>
-            <a href="/about">
-                <i class="fa-solid fa-info-circle" aria-hidden="true"></i>
-                <span>about</span>
-            </a>
-        </li>
     </ul>
 </nav>
 

package/templates/html/components/modal.html

@@ -1,3 +1,47 @@
+<!--
+/**
+ * @title Modal
+ * @description Componente che collega un pulsante a un dialog nativo, ne gestisce apertura e chiusura e può spostarlo in un contenitore configurato.
+ *
+ * @pgs
+ * - modal: identifica il contenitore logico inizializzato dal modulo modal.
+ * - modal-button: identifica il controllo di apertura della finestra.
+ * - dialog: token aggiunto dinamicamente all'elemento dialog inizializzato.
+ * - modal-dialog: identifica il dialog nativo dopo l'inizializzazione JavaScript.
+ * - modal-dialog-content: identifica il contenitore visivo della finestra.
+ * - modal-dialog-content-header: identifica l'intestazione che può ricevere il pulsante di chiusura automatico.
+ * - modal-dialog-content-scroll: identifica l'area interna scorrevole.
+ * - modal-close: identifica un controllo che chiude la finestra.
+ *
+ * @pgs-option
+ * - containerID: sul root usa containerID[id] per spostare il dialog nell'elemento con l'id indicato.
+ * - containerPGS: sul root usa containerPGS[token] per spostare il dialog nel primo elemento con quel token pgs.
+ * - disableBackdropClose: sul root impedisce la chiusura tramite click sul backdrop.
+ * - history: sul root sincronizza l'apertura con il parametro modal nella cronologia del browser e richiede un id sul pulsante.
+ * - topLevel: sul dialog mantiene la finestra nel componente e usa showModal per una modale top-level.
+ * - left: sul dialog posiziona e anima il contenuto dal lato sinistro.
+ * - right: sul dialog posiziona e anima il contenuto dal lato destro.
+ *
+ * @api
+ * - pgs.modal.init(root): inizializza le modali presenti nel Document o Element indicato; il valore predefinito è document.
+ * - pgs.modal.api(element): restituisce l'istanza associata a un root modal inizializzato.
+ * - instance.open(): apre la finestra se non è già aperta.
+ * - instance.close(): chiude la finestra se è aperta.
+ * - instance.toggle(): apre la finestra oppure la chiude quando è già aperta.
+ * - instance.refresh(): rilegge opzioni e collegamenti della modale, sostituisce listener e observer precedenti e restituisce la nuova API.
+ * - instance.isOpen(): restituisce true quando l'elemento dialog possiede lo stato nativo open.
+ *
+ * @related
+ * - button: presenta i controlli di apertura, chiusura e annullamento come pulsanti standard.
+ * - buttonStrong: presenta l'azione di conferma con maggiore enfasi.
+ * - buttonClose: viene aggiunto automaticamente al controllo di chiusura quando manca nel markup.
+ * - flexColumnElements: organizza verticalmente il contenuto della modale di conferma.
+ * - flexRow: dispone affiancate le azioni della modale di conferma.
+ *
+ * @return Quattro esempi basati su dialog nativo e un contenitore opzionale usato da containerID.
+ */
+-->
+
 <div pgs="modal" pgs-option="containerID[modal-container]">
     <button pgs="modal-button button" type="button">
         <i class="fa-solid fa-window-maximize"></i> Apri modale

package/templates/html/components/notification.html

@@ -1,35 +1,71 @@
+<!--
+/**
+ * @title Notification
+ * @description Sistema di notifiche persistenti o toast temporanei, generati dall'API oppure da una configurazione JSON dichiarativa contenuta nell'opzione notification.
+ *
+ * @pgs
+ * - notification: identifica il contenitore delle notifiche, sia persistenti sia temporanee.
+ * - notificationTrigger: identifica una configurazione dichiarativa elaborata e rimossa all'inizializzazione.
+ * - notification-element: identifica ogni messaggio creato dinamicamente.
+ * - notification-element-title: identifica il titolo generato del messaggio.
+ * - notification-element-content: identifica il contenuto generato del messaggio.
+ *
+ * @pgs-option
+ * - toast: sul contenitore notification abilita il posizionamento centrale e la sostituzione del messaggio temporaneo corrente.
+ * - notification: contiene un oggetto JSON con title, message, element, type, icon, duration e link usando la sintassi notification[{...}].
+ *
+ * @pgs-state
+ * - success: applica la variante positiva al messaggio generato.
+ * - error: applica la variante di errore e il ruolo alert.
+ * - warning: applica la variante di avviso.
+ * - info: applica la variante informativa predefinita.
+ *
+ * @api
+ * - pgs.notification.trigger(root): elabora e rimuove i notificationTrigger dichiarativi presenti nel contesto indicato.
+ * - pgs.notification.alert.error(text, link, timeout, icon): crea una notifica persistente di errore, opzionalmente cliccabile e temporizzata.
+ * - pgs.notification.alert.success(text, link, timeout, icon): crea una notifica persistente di successo.
+ * - pgs.notification.alert.info(text, link, timeout, icon): crea una notifica persistente informativa.
+ * - pgs.notification.alert.warning(text, link, timeout, icon): crea una notifica persistente di avviso.
+ * - pgs.notification.alert.deleteAll(): rimuove tutte le notifiche persistenti.
+ * - pgs.notification.toast.error(text, timeout, icon): crea un toast di errore sostituendo quello eventualmente presente.
+ * - pgs.notification.toast.success(text, timeout, icon): crea un toast di successo.
+ * - pgs.notification.toast.info(text, timeout, icon): crea un toast informativo.
+ * - pgs.notification.toast.warning(text, timeout, icon): crea un toast di avviso.
+ * - pgs.notification.toast.deleteAll(): rimuove il toast corrente.
+ *
+ * @related
+ * - hidden: nasconde i trigger dichiarativi prima che vengano elaborati.
+ * - buttonClose: identifica il pulsante di rimozione aggiunto a ogni messaggio.
+ *
+ * @return Due contenitori notification, uno persistente e uno configurato con l'opzione toast, con trigger dichiarativi configurati tramite pgs-option.
+ */
+-->
+
 <div pgs="notification" aria-live="polite"></div>
-<div pgs="toast" aria-live="polite"></div>
+<div pgs="notification" pgs-option="toast" aria-live="polite"></div>
 
-<div pgs="hidden notificationTrigger" data-notification='{
-        "title":"Titolo",
-        "message":"Messaggio",
-        "element":"notification",
-        "type":"info",
-        "icon":null,
-        "duration":"-1",
-        "link":null
-    }'>
-</div>
-<div pgs="hidden notificationTrigger" data-notification='{
-        "title":"Benvetuto",
-        "message":"Messaggio",
-        "element":"toast",
-        "type":"info",
-        "icon":null,
-        "duration":"3000",
-        "link":null
-    }'>
-</div>
+<div pgs="hidden notificationTrigger" pgs-option='notification[{
+            "title": "Titolo",
+            "message": "Messaggio",
+            "element": "notification",
+            "type": "info",
+            "icon": null,
+            "duration": "-1",
+            "link": null
+        }]'></div>
+
+<div pgs="hidden notificationTrigger" pgs-option='notification[{
+            "title": "Benvenuto",
+            "message": "Messaggio",
+            "element": "toast",
+            "type": "info",
+            "icon": null,
+            "duration": "3000",
+            "link": null
+        }]'></div>
 <!-- 
-    <div pgs="hidden notificationTrigger" data-notification='{
-        "title":"Titolo",
-        "message":"Messaggio",
-        "element":"notification | toast",
-        "type":"info | success | warning | error",
-        "icon":"null | <i class=\"fa-solid fa-rocket\"></i>",
-        "duration":"-1 | 0 | 4000 | 5000",
-        "link":"null | /pagina/"
-    }'>
-</div>
--->
+    <div
+        pgs="hidden notificationTrigger"
+        pgs-option='notification[{"title":"Titolo","message":"Messaggio","element":"notification","type":"info","icon":"<i class=\"fa-solid fa-rocket\"></i>","duration":"4000","link":"/pagina/"}]'>
+    </div>
+-->

package/templates/html/components/search.html

@@ -1,3 +1,55 @@
+<!--
+/**
+ * @title Search
+ * @description Ricerca componibile con suggerimenti asincroni o locali, navigazione da tastiera, selezione, annullamento richieste e attributi ARIA gestiti dal modulo search.
+ *
+ * @pgs
+ * - search: identifica il form inizializzato come ricerca con suggerimenti.
+ * - search-suggestions: identifica la lista opzionale che riceve i risultati.
+ * - search-suggestions-item: identifica ogni risultato creato dinamicamente nella lista.
+ * - search-modal: identifica la variante di ricerca inserita in una modale per dispositivi mobili.
+ * - search-mobile: identifica il contenitore interno della ricerca mobile.
+ *
+ * @pgs-option
+ * - containerPGS: sul wrapper modal usa containerPGS[header] per spostare il dialog nell'header.
+ *
+ * @pgs-state
+ * - open: sul root search indica che la lista dei suggerimenti è aperta.
+ * - loading: sul root search indica una sorgente dati in caricamento.
+ * - error: sul root search indica che il recupero dei suggerimenti è fallito.
+ * - selected: sul risultato generato indica l'elemento attivo durante la navigazione.
+ *
+ * @api
+ * - pgs.search.init(root): inizializza le ricerche non ancora registrate dentro Document o Element indicato.
+ * - pgs.search.api(element): restituisce l'istanza associata a un form search inizializzato.
+ * - instance.configure(options): aggiorna minLength, debounce, limit, submitOnSelect, searchOnFocus, source e onSelect e restituisce l'istanza.
+ * - instance.setSource(source): configura una sorgente array o funzione asincrona per i suggerimenti.
+ * - instance.search(query): esegue subito la ricerca e restituisce una Promise con i suggerimenti normalizzati.
+ * - instance.open(): apre la lista quando sono disponibili risultati.
+ * - instance.close(): chiude la lista e azzera la selezione attiva.
+ * - instance.clear(): rimuove risultati e selezione e chiude la lista.
+ * - instance.cancel(): annulla debounce e richiesta attiva.
+ * - instance.select(index, submit): seleziona un risultato, emette pgs:search:select e può inviare il form.
+ * - instance.refresh(): ripete la ricerca usando il valore corrente dell'input.
+ * - instance.destroy(): rimuove listener, annulla le operazioni e scollega l'istanza.
+ * - instance.items(): restituisce una copia dei suggerimenti correnti.
+ * - instance.isOpen(): restituisce true quando la lista dei suggerimenti è aperta.
+ * - instance.isLoading(): restituisce true durante il caricamento della sorgente.
+ * - instance.setActiveIndex(index): imposta il suggerimento attivo e aggiorna selezione e attributi ARIA.
+ *
+ * @related
+ * - buttonNohover: applica al form l'aspetto compatto condiviso con i controlli button.
+ * - modal: fornisce il contenitore e il comportamento della variante mobile.
+ * - modal-button: apre la ricerca mobile.
+ * - modal-close: chiude la ricerca mobile.
+ * - buttonIcon: presenta apertura e chiusura come pulsanti a icona.
+ * - flexRow: organizza il contenuto della variante mobile e gli elementi dei suggerimenti generati.
+ * - section: applica la spaziatura di sezione alla ricerca mobile.
+ *
+ * @return Form di ricerca autonomo, variante mobile integrata in una modal e script di esempio con sorgente locale.
+ */
+-->
+
 <form pgs="buttonNohover search" autocomplete="off" action="" method="get">
     <button type="submit" title="Cerca"><i class="fa-solid fa-search"></i></button>
     <input type="search" name="s" placeholder="Cerca" value="">
@@ -29,3 +81,27 @@
         </div>
     </dialog>
 </div>
+
+<script type="module">
+    import { pgs } from "mypgs";
+
+    const components = [
+        { label: "Accordion", value: "/componenti/accordion", data: { category: "component" } },
+        { label: "Dropdown", value: "/componenti/dropdown", data: { category: "component" } },
+        { label: "Modal", value: "/componenti/modal", data: { category: "component" } },
+        { label: "Search", value: "/componenti/search", data: { category: "component" } },
+        { label: "Page Shell", value: "/layout/page-shell", data: { category: "layout" } },
+    ];
+
+    pgs(document).querySelectorAll("search").forEach(search => {
+        pgs.search.api(search)?.configure({
+            minLength: 1,
+            debounce: 150,
+            limit: 5,
+            source: components,
+            onSelect: ({ item, value }) => {
+                console.log(`Selezionato ${item.label}: ${value}`);
+            },
+        });
+    });
+</script>

package/templates/html/components/slides.html

@@ -1,3 +1,46 @@
+<!--
+/**
+ * @title Slides
+ * @description Carosello orizzontale che osserva gli elementi visibili e crea automaticamente controlli precedente, successivo e indicatori di posizione.
+ *
+ * @pgs
+ * - slides: identifica il root inizializzato dal modulo slides.
+ * - slides-container: identifica la lista orizzontale degli elementi scorrevoli.
+ * - slides-prec: identifica il pulsante precedente creato dinamicamente.
+ * - slides-next: identifica il pulsante successivo creato dinamicamente.
+ * - slides-dots: identifica il contenitore degli indicatori creato dinamicamente.
+ *
+ * @pgs-option
+ * - singleScroll: usa un solo elemento visibile come riferimento per la navigazione precedente e successiva.
+ * - shadowDesktop: abilita l'ombreggiatura laterale del carosello sui layout desktop.
+ * - notScrollAnimation: applicata a un elemento li disabilita l'animazione visiva basata sulla percentuale di visibilità.
+ * - notScrollWithMouse: sul root disabilita la gestione dello scorrimento orizzontale tramite mouse.
+ *
+ * @api
+ * - pgs.slides.init(root): inizializza il root stesso quando è un carosello e tutti i caroselli discendenti non ancora registrati; il valore predefinito è document.
+ * - pgs.slides.api(element): restituisce l'istanza associata a un root slides inizializzato.
+ * - instance.previous(): porta in vista la slide precedente.
+ * - instance.next(): porta in vista la slide successiva.
+ * - instance.goTo(index): porta in vista la slide con l'indice indicato.
+ * - instance.getCurrentIndexes(): restituisce gli indici delle slide attualmente visibili.
+ * - instance.getCurrentElements(): restituisce gli elementi slide attualmente visibili.
+ * - instance.getTotal(): restituisce il numero totale di slide.
+ * - instance.isAtStart(): restituisce true quando la prima slide è visibile.
+ * - instance.isAtEnd(): restituisce true quando l'ultima slide è visibile.
+ * - instance.refresh(): sincronizza controlli e dots, sostituisce listener e observer precedenti e restituisce la nuova API.
+ *
+ * @related
+ * - card: usa card come contenuto dimostrativo di ogni slide.
+ * - card-img: identifica l'immagine delle card dimostrative.
+ * - imgCover: adatta le immagini allo spazio disponibile.
+ * - flexColumn: organizza verticalmente ogni card.
+ * - flexColumnTexts: applica la spaziatura ai testi delle card.
+ * - buttonIcon: viene applicato ai controlli precedente e successivo generati.
+ *
+ * @return Lista di slide basate su card, completata a runtime con pulsanti e indicatori.
+ */
+-->
+
 <div pgs="slides" pgs-option="singleScroll shadowDesktop">
     <ul pgs="slides-container">
         <li>