mypgs 2.0.0 → 2.1.0

package/docs/components/form.md

@@ -1,79 +1,102 @@
-<!-- File generato automaticamente da templates/html/components/form.html. Modificare templates/html/components/form.html e rieseguire npm run docs:generate. -->
+<!-- Automatically generated from templates/html/components/form.html. Edit templates/html/components/form.html and run npm run docs:generate again. -->
 
 # Form
 
-Struttura di modulo con etichette, campi testuali, textarea e controllo toggle compatibile con i vincoli HTML e con regole personalizzate di PGS_formValidate.
+Form structure with labels, text fields, a textarea, a checkbox, and a radio group compatible with HTML constraints and custom PGS_formValidate rules.
 
 ## 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.
+- `form`: identifies the form container and applies the field layout.
+- `formValidate`: enables styles associated with validation states managed by the JavaScript utility.
+- `label`: identifies labels associated with controls.
+- `input`: applies shared styling to text inputs.
+- `textarea`: applies shared styling to the text area.
+- `radio`: styles a group of native radio inputs while preserving their shared name and selection behavior.
 
 ## 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.
+- `message`: defines a field-specific message with the syntax message[Message text].
+- `error`: is applied at runtime to the form and fields that fail validation.
+- `success`: is applied at runtime to the form after successful validation.
 
-## API JavaScript
+## JavaScript 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.
+- `new pgs.formValidate(form, options)`: creates a utility associated directly with the form, automatically adds novalidate, and accepts fieldError, fieldsError, and success in options.message; messages remain editable through instance.message.
+- `instance.validator(callback, eventName)`: intercepts the specified event, prevents its default behavior, validates the form, shows the success message, and invokes callback only when valid; eventName defaults to submit.
+- `instance.validate()`: validates required fields, updates state attributes, and returns true or false.
+- `instance.success(text)`: validates the form and shows a success toast when there are no errors.
+- `instance.addNewRule(rule)`: adds a function that returns one or more invalid fields; validate automatically applies addFieldError to each field.
+- `instance.addFieldError(field, index, total)`: marks a field as invalid; shows the specific message for one error or a summary message for multiple errors.
+- `instance.removeFieldError(field)`: removes the error state from the specified field.
 
-## Elementi correlati
+## Related elements
 
-- `buttonStrong`: presenta l'invio del modulo come azione primaria.
+- `buttonStrong`: presents form submission as the primary action.
+- `flexColumnTexts`: spaces text elements in the radio group.
 
 ## Output
 
-Modulo HTML completo con campi required e script di esempio per una regola personalizzata, la validazione e il messaggio di successo.
+Complete HTML form with required fields and an example script for a custom rule, validation, and a success message.
 
-## Esempio
+## Example
 
 ```html
 <form pgs="form formValidate" action="#" method="post">
     <label pgs="label" for="form-name">
-        Nome
+        Name
     </label>
-    <input id="form-name" pgs="input" pgs-option="message[Inserisci il nome]" type="text" name="name" placeholder="Mario Rossi" required>
+    <input id="form-name" pgs="input" pgs-option="message[Enter your name]" type="text" name="name" placeholder="John Smith" 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>
+    <input id="form-email" pgs="input" pgs-option="message[Enter a valid email address]" type="email" name="email" placeholder="name@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>
+    <input id="form-password" pgs="input" pgs-option="message[Enter a password]" type="password" name="password" autocomplete="new-password" required>
 
     <label pgs="label" for="form-confirm-password">
-        Conferma password
+        Confirm password
     </label>
-    <input id="form-confirm-password" pgs="input" pgs-option="message[Conferma la password]" type="password" name="confirmPassword" autocomplete="new-password" required>
+    <input id="form-confirm-password" pgs="input" pgs-option="message[Confirm your password]" type="password" name="confirmPassword" autocomplete="new-password" required>
 
     <label pgs="label" for="form-message">
-        Messaggio
+        Message
     </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>
+    <textarea id="form-message" pgs="textarea" name="message" rows="5" placeholder="Write your message" required></textarea>
+
+    <br>
+    <fieldset pgs="radio flexColumnTexts">
+        <legend>Preferred contact method</legend>
+
+        <label>
+            <input type="radio" name="contactMethod" value="email" pgs-option="message[Choose a contact method]" required>
+            <span>Email</span>
+        </label>
+
+        <label>
+            <input type="radio" name="contactMethod" value="phone">
+            <span>Phone</span>
+        </label>
+
+        <label>
+            <input type="radio" name="contactMethod" value="message">
+            <span>Direct message</span>
+        </label>
+    </fieldset>
+    <br>
+
+    <label>
         <input type="checkbox" name="privacy" required>
+        <span>I accept the privacy policy</span>
     </label>
+    <br>
 
     <button pgs="buttonStrong" type="submit">
         <i class="fa-solid fa-paper-plane" aria-hidden="true"></i>
-        Invia
+        Submit
     </button>
 </form>
 
@@ -88,16 +111,16 @@ Modulo HTML completo con campi required e script di esempio per una regola perso
 
     const formValidate = new pgs.formValidate(form, {
         message: {
-            fieldError: "Completa questo campo",
-            fieldsError: "Completa tutti i campi obbligatori",
-            success: "Inviato con successo"
+            fieldError: "Please complete this field",
+            fieldsError: "Please complete all required fields",
+            success: "Submitted successfully"
         }
     });
 
     //== new roules
     formValidate.addNewRule(() => {
         if (password.value && confirmPassword.value && password.value !== confirmPassword.value) {
-            pgs(confirmPassword).option.setValueBrackets("message", "Le password non coincidono");
+            pgs(confirmPassword).option.setValueBrackets("message", "Passwords do not match");
             return [confirmPassword, password];
         }
     });
@@ -106,7 +129,7 @@ Modulo HTML completo con campi required e script di esempio per una regola perso
     formValidate.validator(event => {
         const values = Object.fromEntries(new FormData(form));
 
-        // Sostituisci questo log con l'invio dei dati al tuo backend.
+        // Replace this log with a request to your backend.
         console.log(values);
     }, "submit");
 </script>

package/docs/components/formAddon.md

@@ -0,0 +1,79 @@
+<!-- Automatically generated from templates/html/components/formAddon.html. Edit templates/html/components/formAddon.html and run npm run docs:generate again. -->
+
+# Form Add-ons
+
+Additional form controls for selectable cards, two-state buttons, switches, and compact chip groups.
+
+## PGS
+
+- `checkboxBackground`: presents a checkbox as a selectable container with a highlighted checked state.
+- `twoState`: presents checkbox or radio labels as buttons whose appearance changes when selected.
+- `toggle`: presents a checkbox as a switch with a rail and movable thumb.
+- `chips`: groups twoState controls into a compact segmented selector.
+
+## Related elements
+
+- `flexColumnElements`: vertically arranges the form add-on examples.
+- `flexColumnTexts`: groups each example with its heading and control.
+
+## Output
+
+HTML examples of the checkboxBackground, twoState, toggle, and chips form controls using native checkbox and radio inputs.
+
+## Example
+
+```html
+<div pgs="flexColumnElements">
+    <section pgs="flexColumnTexts">
+        <strong>Checkbox with background</strong>
+
+        <label pgs="checkboxBackground">
+            <input type="checkbox" name="notifications" value="enabled">
+            <span>
+                <strong>Enable notifications</strong><br>
+                Receive important account updates.
+            </span>
+        </label>
+    </section>
+
+    <section pgs="flexColumnTexts">
+        <strong>Two-state controls</strong>
+
+        <label pgs="twoState">
+            <input type="checkbox" name="favorite" value="yes">
+            <i class="fa-solid fa-star" aria-hidden="true"></i>
+            Add to favorites
+        </label>
+    </section>
+
+    <section pgs="flexColumnTexts">
+        <strong>Toggle</strong>
+
+        <label pgs="toggle">
+            <span>Enable dark mode</span>
+            <input type="checkbox" name="darkMode" value="enabled">
+        </label>
+    </section>
+
+    <section pgs="flexColumnTexts">
+        <strong>Chips</strong>
+
+        <div pgs="chips" role="group" aria-label="Select a plan">
+            <label pgs="twoState">
+                <input type="radio" name="plan" value="basic" checked>
+                Basic
+            </label>
+
+            <label pgs="twoState">
+                <input type="radio" name="plan" value="pro">
+                Pro
+            </label>
+
+            <label pgs="twoState">
+                <input type="radio" name="plan" value="enterprise">
+                Enterprise
+            </label>
+        </div>
+    </section>
+</div>
+```

package/docs/components/logo.md

@@ -1,36 +1,36 @@
-<!-- File generato automaticamente da templates/html/components/logo.html. Modificare templates/html/components/logo.html e rieseguire npm run docs:generate. -->
+<!-- Automatically generated from templates/html/components/logo.html. Edit templates/html/components/logo.html and run npm run docs:generate again. -->
 
 # Logo
 
-Componente per mostrare un logo grafico o testuale, con supporto alle varianti dell'immagine legate al tema scuro.
+Component for displaying a graphical or text logo, with image variants that support dark mode.
 
 ## PGS
 
-- `logo`: identifica il collegamento contenitore del marchio.
-- `logo-image`: identifica l'immagine grafica del logo.
-- `logo-text`: identifica la variante testuale del marchio.
+- `logo`: identifies the brand link container.
+- `logo-image`: identifies the graphical logo image.
+- `logo-text`: identifies the text-based brand variant.
 
 ## 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.
+- `logoDarkmode`: inverts the logo image when the global darkmode state is active.
+- `logoDarkmodeFixed`: keeps the image inversion enabled regardless of the current theme.
 
 ## PGS States
 
-- `darkmode`: stato globale applicato al documento che attiva la variante logoDarkmode.
+- `darkmode`: global document state that activates the logoDarkmode variant.
 
 ## Output
 
-Esempi HTML del logo grafico sensibile al tema e del logo testuale.
+HTML examples of the theme-aware graphical logo and the text logo.
 
-## Esempio
+## Example
 
 ```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="/">
+<a aria-label="Text logo" pgs="logo" href="/">
     <span pgs="logo-text">MyPGS</span>
 </a>
 ```

package/docs/components/menu.md

@@ -1,43 +1,43 @@
-<!-- File generato automaticamente da templates/html/components/menu.html. Modificare templates/html/components/menu.html e rieseguire npm run docs:generate. -->
+<!-- Automatically generated from templates/html/components/menu.html. Edit templates/html/components/menu.html and run npm run docs:generate again. -->
 
 # Menu
 
-Navigazione orizzontale o verticale che trasforma le voci con sottomenu in dropdown accessibili e inizializzati automaticamente.
+Menu markup, configuration, behavior, and usage example.
 
 ## PGS
 
-- `menu`: identifica il contenitore di navigazione elaborato dal modulo menu.
-- `menu-buttonIcon`: identifica il controllo creato dinamicamente accanto alle voci con sottomenu.
+- `menu`: identifies the menu element used by Menu.
+- `menu-buttonIcon`: identifies the menu-buttonIcon element used by Menu.
 
 ## 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.
+- `horizontal`: identifies the horizontal element used by Menu.
+- `vertical`: identifies the vertical element used by Menu.
+- `menuHeader`: identifies the menuHeader element used by Menu.
+- `position`: identifies the position element used by Menu.
 
 ## PGS States
 
-- `open`: indica il sottomenu trasformato in dropdown attualmente aperto.
+- `open`: identifies the open element used by Menu.
 
-## API JavaScript
+## JavaScript 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.
+- `pgs.menu.init(root)`: initializes matching elements within the specified root.
+- `pgs.menu.api(element)`: returns the instance associated with the specified initialized element.
+- `instance.refresh()`: refreshes the component and returns its updated instance.
 
-## Elementi correlati
+## Related elements
 
-- `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.
+- `dropdown`: uses the related dropdown component or utility in this example.
+- `dropdown-button`: uses the related dropdown-button component or utility in this example.
+- `buttonNohover`: uses the related buttonNohover component or utility in this example.
+- `dropdown-content`: uses the related dropdown-content component or utility in this example.
 
 ## Output
 
-Due strutture nav complete per le varianti orizzontale e verticale del menu.
+Complete HTML markup and usage example for Menu.
 
-## Esempio
+## Example
 
 ```html
 <nav pgs="menu" pgs-option="horizontal" aria-label="Menu orizzontale">

package/docs/components/modal.md

@@ -1,68 +1,68 @@
-<!-- File generato automaticamente da templates/html/components/modal.html. Modificare templates/html/components/modal.html e rieseguire npm run docs:generate. -->
+<!-- Automatically generated from templates/html/components/modal.html. Edit templates/html/components/modal.html and run npm run docs:generate again. -->
 
 # Modal
 
-Componente che collega un pulsante a un dialog nativo, ne gestisce apertura e chiusura e può spostarlo in un contenitore configurato.
+Modal markup, configuration, behavior, and usage example.
 
 ## PGS
 
-- `modal`: identifica il contenitore logico inizializzato dal modulo modal.
-- `modal-button`: identifica il controllo di apertura della finestra.
+- `modal`: identifies the modal element used by Modal.
+- `modal-button`: identifies the modal-button element used by Modal.
 - `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.
+- `modal-dialog`: identifies the modal-dialog element used by Modal.
+- `modal-dialog-content`: identifies the modal-dialog-content element used by Modal.
+- `modal-dialog-content-header`: identifies the modal-dialog-content-header element used by Modal.
+- `modal-dialog-content-scroll`: identifies the modal-dialog-content-scroll element used by Modal.
+- `modal-close`: identifies the modal-close element used by Modal.
 
 ## 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.
+- `containerID`: identifies the containerID element used by Modal.
+- `containerPGS`: identifies the containerPGS element used by Modal.
+- `disableBackdropClose`: identifies the disableBackdropClose element used by Modal.
+- `history`: identifies the history element used by Modal.
+- `topLevel`: identifies the topLevel element used by Modal.
+- `left`: identifies the left element used by Modal.
+- `right`: identifies the right element used by Modal.
 
-## API JavaScript
+## JavaScript 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.
+- `pgs.modal.init(root)`: initializes matching elements within the specified root.
+- `pgs.modal.api(element)`: returns the instance associated with the specified initialized element.
+- `instance.open()`: opens the component.
+- `instance.close()`: closes the component.
+- `instance.toggle()`: toggles the component state.
+- `instance.refresh()`: refreshes the component and returns its updated instance.
+- `instance.isOpen()`: returns true when the component is open.
 
-## Elementi correlati
+## Related elements
 
-- `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.
+- `button`: uses the related button component or utility in this example.
+- `buttonStrong`: uses the related buttonStrong component or utility in this example.
+- `buttonClose`: uses the related buttonClose component or utility in this example.
+- `flexColumnElements`: uses the related flexColumnElements component or utility in this example.
+- `flexRow`: uses the related flexRow component or utility in this example.
 
 ## Output
 
-Quattro esempi basati su dialog nativo e un contenitore opzionale usato da containerID.
+Complete HTML markup and usage example for Modal.
 
-## Esempio
+## Example
 
 ```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
+        <i class="fa-solid fa-window-maximize"></i> Open modal
     </button>
 
     <dialog>
         <div pgs="modal-dialog-content">
             <div pgs="modal-dialog-content-header">
-                <h3>Modale di esempio</h3>
+                <h3>Example modal</h3>
             </div>
 
             <div pgs="modal-dialog-content-scroll">
-                <p>Contenuto della modale. Il bottone di chiusura viene aggiunto automaticamente se non presente.</p>
+                <p>Modal content. The close button is added automatically when missing.</p>
             </div>
         </div>
     </dialog>
@@ -70,17 +70,17 @@ Quattro esempi basati su dialog nativo e un contenitore opzionale usato da conta
 
 <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
+        <i class="fa-solid fa-window-maximize"></i> Open modal right
     </button>
 
     <dialog pgs-option="right">
         <div pgs="modal-dialog-content">
             <div pgs="modal-dialog-content-header">
-                <h3>Modale laterale</h3>
+                <h3>Side modal</h3>
             </div>
 
             <div pgs="modal-dialog-content-scroll">
-                <p>Contenuto della modale con <code>pgs-option="right"</code>.</p>
+                <p>Modal content with <code>pgs-option="right"</code>.</p>
             </div>
         </div>
     </dialog>
@@ -88,17 +88,17 @@ Quattro esempi basati su dialog nativo e un contenitore opzionale usato da conta
 
 <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
+        <i class="fa-solid fa-window-maximize"></i> Open modal left
     </button>
 
     <dialog pgs-option="left">
         <div pgs="modal-dialog-content">
             <div pgs="modal-dialog-content-header">
-                <h3>Modale laterale sinistra</h3>
+                <h3>Left-side modal</h3>
             </div>
 
             <div pgs="modal-dialog-content-scroll">
-                <p>Contenuto della modale con <code>pgs-option="left"</code>.</p>
+                <p>Modal content with <code>pgs-option="left"</code>.</p>
             </div>
         </div>
     </dialog>
@@ -106,21 +106,21 @@ Quattro esempi basati su dialog nativo e un contenitore opzionale usato da conta
 
 <div pgs="modal">
     <button pgs="modal-button button" type="button">
-        <i class="fa-solid fa-floppy-disk"></i> Conferma salvataggio
+        <i class="fa-solid fa-floppy-disk"></i> Confirmation salvataggio
     </button>
 
     <dialog pgs-option="topLevel">
         <div pgs="modal-dialog-content">
             <div pgs="modal-dialog-content-header">
-                <h3>Salvare le modifiche?</h3>
+                <h3>Save changes?</h3>
             </div>
 
             <div pgs="modal-dialog-content-scroll flexColumnElements">
-                <p>Hai modifiche non salvate. Conferma per applicarle oppure annulla per tornare alla pagina.</p>
+                <p>You have unsaved changes. Confirm to apply them or cancel to return to the page.</p>
 
                 <div pgs="flexRow">
-                    <button pgs="button modal-close" type="button">Annulla</button>
-                    <button pgs="buttonStrong" type="button">Salva modifiche</button>
+                    <button pgs="button modal-close" type="button">Cancel</button>
+                    <button pgs="buttonStrong" type="button">Save changes</button>
                 </div>
             </div>
         </div>