mypgs 1.6.0 → 2.0.0

package/docs/components/dropdown.md

@@ -0,0 +1,135 @@
+<!-- File generato automaticamente da templates/html/components/dropdown.html. Modificare templates/html/components/dropdown.html e rieseguire npm run docs:generate. -->
+
+# Dropdown
+
+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 Options
+
+- `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 States
+
+- `open`: indica che il dropdown è aperto e che il contenuto è visibile.
+
+## API JavaScript
+
+- `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.
+
+## Elementi correlati
+
+- `flexRow`: dispone i diversi esempi di posizionamento sulla stessa riga flessibile.
+- `button`: applica lo stile standard ai controlli del dropdown.
+
+## Output
+
+Serie di dropdown HTML che dimostra le direzioni di posizionamento supportate.
+
+## Esempio
+
+```html
+<div pgs="flexRow">
+
+    <span pgs="dropdown">
+        <button pgs="dropdown-button button" pgs-option="buttonReverse" type="button">
+            Bottom center
+            <i class="fa-solid fa-chevron-down" aria-hidden="true"></i>
+        </button>
+
+        <div pgs="dropdown-content">
+            Contenuto bottom center
+        </div>
+    </span>
+
+    <span pgs="dropdown" pgs-option="position[top left]">
+        <button pgs="dropdown-button button" pgs-option="buttonReverse" type="button">
+            Top left
+            <i class="fa-solid fa-chevron-down" aria-hidden="true"></i>
+        </button>
+
+        <div pgs="dropdown-content">
+            Contenuto top left
+        </div>
+    </span>
+
+    <span pgs="dropdown" pgs-option="position[top center]">
+        <button pgs="dropdown-button button" pgs-option="buttonReverse" type="button">
+            Top center
+            <i class="fa-solid fa-chevron-down" aria-hidden="true"></i>
+        </button>
+
+        <div pgs="dropdown-content">
+            Contenuto top center
+        </div>
+    </span>
+
+    <span pgs="dropdown" pgs-option="position[top right]">
+        <button pgs="dropdown-button button" pgs-option="buttonReverse" type="button">
+            Top right
+            <i class="fa-solid fa-chevron-down" aria-hidden="true"></i>
+        </button>
+
+        <div pgs="dropdown-content">
+            Contenuto top right
+        </div>
+    </span>
+
+    <span pgs="dropdown" pgs-option="position[bottom left]">
+        <button pgs="dropdown-button button" pgs-option="buttonReverse" type="button">
+            Bottom left
+            <i class="fa-solid fa-chevron-down" aria-hidden="true"></i>
+        </button>
+
+        <div pgs="dropdown-content">
+            Contenuto bottom left
+        </div>
+    </span>
+
+    <span pgs="dropdown" pgs-option="position[bottom right]">
+        <button pgs="dropdown-button button" pgs-option="buttonReverse" type="button">
+            Bottom right
+            <i class="fa-solid fa-chevron-down" aria-hidden="true"></i>
+        </button>
+
+        <div pgs="dropdown-content">
+            Contenuto bottom right
+        </div>
+    </span>
+
+    <span pgs="dropdown" pgs-option="position[left center]">
+        <button pgs="dropdown-button button" pgs-option="buttonReverse" type="button">
+            Left center
+            <i class="fa-solid fa-chevron-down" aria-hidden="true"></i>
+        </button>
+
+        <div pgs="dropdown-content">
+            Contenuto left center
+        </div>
+    </span>
+
+    <span pgs="dropdown" pgs-option="position[right center]">
+        <button pgs="dropdown-button button" pgs-option="buttonReverse" type="button">
+            Right center
+            <i class="fa-solid fa-chevron-down" aria-hidden="true"></i>
+        </button>
+
+        <div pgs="dropdown-content">
+            Contenuto right center
+        </div>
+    </span>
+
+</div>
+```

package/docs/components/form.md

@@ -0,0 +1,113 @@
+<!-- File generato automaticamente da templates/html/components/form.html. Modificare templates/html/components/form.html e rieseguire npm run docs:generate. -->
+
+# Form
+
+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 Options
+
+- `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 JavaScript
+
+- `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.
+
+## Elementi correlati
+
+- `buttonStrong`: presenta l'invio del modulo come azione primaria.
+
+## Output
+
+Modulo HTML completo con campi required e script di esempio per una regola personalizzata, la validazione e il messaggio di successo.
+
+## Esempio
+
+```html
+<form pgs="form formValidate" action="#" method="post">
+    <label pgs="label" for="form-name">
+        Nome
+    </label>
+    <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" 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" required></textarea>
+
+    <label pgs="toggle">
+        <span>Accetto la privacy policy</span>
+        <input type="checkbox" name="privacy" required>
+    </label>
+
+    <button pgs="buttonStrong" type="submit">
+        <i class="fa-solid fa-paper-plane" aria-hidden="true"></i>
+        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/docs/components/logo.md

@@ -0,0 +1,36 @@
+<!-- File generato automaticamente da templates/html/components/logo.html. Modificare templates/html/components/logo.html e rieseguire npm run docs:generate. -->
+
+# Logo
+
+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 Options
+
+- `logoDarkmode`: inverte l'immagine del logo quando lo stato globale darkmode è attivo.
+- `logoDarkmodeFixed`: mantiene applicata l'inversione dell'immagine indipendentemente dal tema corrente.
+
+## PGS States
+
+- `darkmode`: stato globale applicato al documento che attiva la variante logoDarkmode.
+
+## Output
+
+Esempi HTML del logo grafico sensibile al tema e del logo testuale.
+
+## Esempio
+
+```html
+<a aria-label="Logo" pgs="logo" pgs-option="logoDarkmode" href="/">
+    <img pgs="logo-image" src="https://placehold.co/240x80?text=MyPGS" alt="MyPGS">
+</a>
+
+<a aria-label="Logo testuale" pgs="logo" href="/">
+    <span pgs="logo-text">MyPGS</span>
+</a>
+```

package/docs/components/menu.md

@@ -0,0 +1,90 @@
+<!-- File generato automaticamente da templates/html/components/menu.html. Modificare templates/html/components/menu.html e rieseguire npm run docs:generate. -->
+
+# Menu
+
+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 Options
+
+- `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 States
+
+- `open`: indica il sottomenu trasformato in dropdown attualmente aperto.
+
+## API JavaScript
+
+- `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.
+
+## Elementi correlati
+
+- `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.
+
+## Output
+
+Due strutture nav complete per le varianti orizzontale e verticale del menu.
+
+## Esempio
+
+```html
+<nav pgs="menu" pgs-option="horizontal" aria-label="Menu orizzontale">
+    <ul>
+        <li>
+            <a href="/" aria-current="page">
+                <i class="fa-solid fa-house" aria-hidden="true"></i>
+                <span>Home</span>
+            </a>
+        </li>
+        <li>
+            <a href="/servizi">
+                <i class="fa-solid fa-layer-group" aria-hidden="true"></i>
+                <span>Servizi</span>
+            </a>
+            <ul>
+                <li><a href="/servizi/uno">Servizio uno</a></li>
+                <li><a href="/servizi/due">Servizio due</a></li>
+            </ul>
+        </li>
+    </ul>
+</nav>
+
+<nav pgs="menu" pgs-option="vertical" aria-label="Menu verticale">
+    <ul>
+        <li>
+            <a href="/" aria-current="page">
+                <i class="fa-solid fa-house" aria-hidden="true"></i>
+                <span>Home</span>
+            </a>
+        </li>
+        <li>
+            <a href="/servizi">
+                <i class="fa-solid fa-layer-group" aria-hidden="true"></i>
+                <span>Servizi</span>
+            </a>
+            <ul>
+                <li><a href="/servizi/uno">Servizio uno</a></li>
+                <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/docs/components/modal.md

@@ -0,0 +1,131 @@
+<!-- File generato automaticamente da templates/html/components/modal.html. Modificare templates/html/components/modal.html e rieseguire npm run docs:generate. -->
+
+# Modal
+
+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 Options
+
+- `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 JavaScript
+
+- `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.
+
+## Elementi correlati
+
+- `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.
+
+## Output
+
+Quattro esempi basati su dialog nativo e un contenitore opzionale usato da containerID.
+
+## Esempio
+
+```html
+<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
+    </button>
+
+    <dialog>
+        <div pgs="modal-dialog-content">
+            <div pgs="modal-dialog-content-header">
+                <h3>Modale di esempio</h3>
+            </div>
+
+            <div pgs="modal-dialog-content-scroll">
+                <p>Contenuto della modale. Il bottone di chiusura viene aggiunto automaticamente se non presente.</p>
+            </div>
+        </div>
+    </dialog>
+</div>
+
+<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 right
+    </button>
+
+    <dialog pgs-option="right">
+        <div pgs="modal-dialog-content">
+            <div pgs="modal-dialog-content-header">
+                <h3>Modale laterale</h3>
+            </div>
+
+            <div pgs="modal-dialog-content-scroll">
+                <p>Contenuto della modale con <code>pgs-option="right"</code>.</p>
+            </div>
+        </div>
+    </dialog>
+</div>
+
+<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 left
+    </button>
+
+    <dialog pgs-option="left">
+        <div pgs="modal-dialog-content">
+            <div pgs="modal-dialog-content-header">
+                <h3>Modale laterale sinistra</h3>
+            </div>
+
+            <div pgs="modal-dialog-content-scroll">
+                <p>Contenuto della modale con <code>pgs-option="left"</code>.</p>
+            </div>
+        </div>
+    </dialog>
+</div>
+
+<div pgs="modal">
+    <button pgs="modal-button button" type="button">
+        <i class="fa-solid fa-floppy-disk"></i> Conferma salvataggio
+    </button>
+
+    <dialog pgs-option="topLevel">
+        <div pgs="modal-dialog-content">
+            <div pgs="modal-dialog-content-header">
+                <h3>Salvare le modifiche?</h3>
+            </div>
+
+            <div pgs="modal-dialog-content-scroll flexColumnElements">
+                <p>Hai modifiche non salvate. Conferma per applicarle oppure annulla per tornare alla pagina.</p>
+
+                <div pgs="flexRow">
+                    <button pgs="button modal-close" type="button">Annulla</button>
+                    <button pgs="buttonStrong" type="button">Salva modifiche</button>
+                </div>
+            </div>
+        </div>
+    </dialog>
+</div>
+
+<div id="modal-container"></div>
+```

package/docs/components/notification.md

@@ -0,0 +1,81 @@
+<!-- File generato automaticamente da templates/html/components/notification.html. Modificare templates/html/components/notification.html e rieseguire npm run docs:generate. -->
+
+# Notification
+
+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 Options
+
+- `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 States
+
+- `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 JavaScript
+
+- `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.
+
+## Elementi correlati
+
+- `hidden`: nasconde i trigger dichiarativi prima che vengano elaborati.
+- `buttonClose`: identifica il pulsante di rimozione aggiunto a ogni messaggio.
+
+## Output
+
+Due contenitori notification, uno persistente e uno configurato con l'opzione toast, con trigger dichiarativi configurati tramite pgs-option.
+
+## Esempio
+
+```html
+<div pgs="notification" aria-live="polite"></div>
+<div pgs="notification" pgs-option="toast" aria-live="polite"></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"
+        pgs-option='notification[{"title":"Titolo","message":"Messaggio","element":"notification","type":"info","icon":"<i class=\"fa-solid fa-rocket\"></i>","duration":"4000","link":"/pagina/"}]'>
+    </div>
+-->
+```