mypgs 1.6.0 → 2.1.0

package/templates/html/components/breadcumbs.html

@@ -1,3 +1,17 @@
+<!--
+/**
+ * @title Breadcrumb
+ * @description Hierarchical navigation that shows the current page path with links, separators, and a semantic indication of the active item.
+ *
+ * @pgs
+ * - breadcrumb: identifies the main navigation path list.
+ * - breadcrumb-item: identifies each level in the path.
+ * - breadcrumb-item-separator: identifies the decorative separator hidden from assistive technologies.
+ *
+ * @return Semantic breadcrumb HTML structure wrapped in a nav element.
+ */
+-->
+
 <nav aria-label="Breadcrumb">
     <ul pgs="breadcrumb">
         <li pgs="breadcrumb-item">
@@ -16,7 +30,7 @@
 
         <li pgs="breadcrumb-item">
             <span aria-current="page">
-                Articolo di prova
+                Sample article
             </span>
         </li>
     </ul>

package/templates/html/components/button.html

@@ -1,3 +1,25 @@
+<!--
+/**
+ * @title Button
+ * @description Button and action-link variants with sizes, emphasis, and icon-text composition defined by the design system.
+ *
+ * @pgs
+ * - button: identifies the standard button, which can also be used on anchor elements.
+ * - buttonStrong: applies the variant with stronger visual emphasis.
+ * - buttonIcon: identifies a compact button composed primarily of an icon.
+ * - buttonMini: applies the smallest size variant.
+ * - buttonBig: applies the large size variant.
+ *
+ * @pgs-option
+ * - buttonReverse: reverses the visual order of the text and icon on the button.
+ *
+ * @related
+ * - flexRow: arranges the button examples in a flexible row.
+ *
+ * @return HTML collection of the main button variants.
+ */
+-->
+
 <div pgs="flexRow">
     <a pgs="button" href="#">
         <i class="fa-duotone fa-solid fa-store"></i>
@@ -5,7 +27,7 @@
     </a>
 
     <button pgs="button" type="button" pgs-option="buttonReverse">
-        Avanti
+        Next
         <i class="fa-solid fa-arrow-right" aria-hidden="true"></i>
     </button>
 
@@ -14,16 +36,16 @@
         Submit
     </button>
 
-    <button pgs="buttonIcon" type="button" aria-label="Impostazioni">
+    <button pgs="buttonIcon" type="button" aria-label="Settings">
         <i class="fa-solid fa-gear" aria-hidden="true"></i>
     </button>
 
-    <button pgs="buttonMini" type="button" aria-label="Informazioni">
+    <button pgs="buttonMini" type="button" aria-label="Information">
         <i class="fa-solid fa-info" aria-hidden="true"></i>
     </button>
 
-    <button pgs="buttonBig" type="button" aria-label="Bottone grande">
+    <button pgs="buttonBig" type="button" aria-label="Large button">
         <i class="fa-solid fa-rocket" aria-hidden="true"></i>
-        Bottone grande
+        Large button
     </button>
-</div>
+</div>

package/templates/html/components/card.html

@@ -1,23 +1,43 @@
+<!--
+/**
+ * @title Card
+ * @description Reusable container for grouping an image, title, text, and actions in responsive previews or collections.
+ *
+ * @pgs
+ * - card: identifies the main card container.
+ * - card-img: identifies the main card image.
+ *
+ * @related
+ * - flex-2: arranges the cards in a responsive two-item layout.
+ * - flexColumn: organizes the card or link content vertically.
+ * - imgCover: scales the image to fill the available area.
+ * - flexColumnTexts: applies vertical spacing to text content.
+ * - button: presents the final link as a standard button.
+ *
+ * @return Two card HTML structures, one with a separate action and one that is fully clickable.
+ */
+-->
+
 <div pgs="flex-2">
 
     <article pgs="card flexColumn">
-        <img pgs="card-img imgCover" src="https://placehold.co/800x500" alt="Immagine segnaposto">
+        <img pgs="card-img imgCover" src="https://placehold.co/800x500" alt="Placeholder image">
         
         <div pgs="flexColumnTexts">
-            <h3>Card riutilizzabile</h3>
-            <p>Contenuto descrittivo della card, adatto a liste, anteprime e griglie.</p>
-            <a pgs="button" href="#">Leggi di piu</a>
+            <h3>Reusable card</h3>
+            <p>Descriptive card content suitable for lists, previews, and grids.</p>
+            <a pgs="button" href="#">Read more</a>
         </div>
     </article>
     
     <article pgs="card">
         <a pgs="flexColumn" href="">
-            <img pgs="card-img imgCover" src="https://placehold.co/800x500" alt="Immagine segnaposto">
+            <img pgs="card-img imgCover" src="https://placehold.co/800x500" alt="Placeholder image">
             
             <div pgs="flexColumnTexts">
-                <h3>Card riutilizzabile</h3>
-                <p>Contenuto descrittivo della card, adatto a liste, anteprime e griglie.</p>
+                <h3>Reusable card</h3>
+                <p>Descriptive card content suitable for lists, previews, and grids.</p>
             </div>
         </a>
     </article>
-</div>
+</div>

package/templates/html/components/dropdown.html

@@ -1,3 +1,37 @@
+<!--
+/**
+ * @title Dropdown
+ * @description Popup component that connects a control to content positioned relative to its trigger and handles opening, closing, outside clicks, and Escape.
+ *
+ * @pgs
+ * - dropdown: identifies the container initialized by the dropdown module.
+ * - dropdown-button: identifies the control that opens or closes the content.
+ * - dropdown-content: identifies the panel positioned relative to the control.
+ *
+ * @pgs-option
+ * - position: configures the root as position[side alignment]; side accepts top, right, bottom, or left, while compatible alignment values are top, right, bottom, left, or center. The default is bottom center.
+ * - buttonReverse: reverses text and icon on the example buttons and belongs to the button component.
+ *
+ * @pgs-state
+ * - open: indicates that the dropdown is open and its content is visible.
+ *
+ * @api
+ * - pgs.dropdown.init(root): initializes unregistered dropdowns within the specified Document or Element.
+ * - pgs.dropdown.api(element): returns the instance associated with an initialized dropdown root.
+ * - instance.open(): opens the dropdown and closes any other open dropdowns.
+ * - instance.close(): closes the current dropdown.
+ * - instance.toggle(): toggles between the open and closed states.
+ * - instance.refresh(): reinitializes the context and recalculates content positioning.
+ * - instance.isOpen(): returns true when the dropdown is open.
+ *
+ * @related
+ * - flexRow: arranges the placement examples on the same flexible row.
+ * - button: applies standard styling to dropdown controls.
+ *
+ * @return Series of HTML dropdowns demonstrating the supported placement directions.
+ */
+-->
+
 <div pgs="flexRow">
 
     <span pgs="dropdown">
@@ -7,7 +41,7 @@
         </button>
 
         <div pgs="dropdown-content">
-            Contenuto bottom center
+            bottom center content
         </div>
     </span>
 
@@ -18,7 +52,7 @@
         </button>
 
         <div pgs="dropdown-content">
-            Contenuto top left
+            top left content
         </div>
     </span>
 
@@ -29,7 +63,7 @@
         </button>
 
         <div pgs="dropdown-content">
-            Contenuto top center
+            top center content
         </div>
     </span>
 
@@ -40,7 +74,7 @@
         </button>
 
         <div pgs="dropdown-content">
-            Contenuto top right
+            top right content
         </div>
     </span>
 
@@ -51,7 +85,7 @@
         </button>
 
         <div pgs="dropdown-content">
-            Contenuto bottom left
+            bottom left content
         </div>
     </span>
 
@@ -62,7 +96,7 @@
         </button>
 
         <div pgs="dropdown-content">
-            Contenuto bottom right
+            bottom right content
         </div>
     </span>
 
@@ -73,7 +107,7 @@
         </button>
 
         <div pgs="dropdown-content">
-            Contenuto left center
+            left center content
         </div>
     </span>
 
@@ -84,7 +118,7 @@
         </button>
 
         <div pgs="dropdown-content">
-            Contenuto right center
+            right center content
         </div>
     </span>
 

package/templates/html/components/form.html

@@ -1,26 +1,127 @@
-<form pgs="form" action="#" method="post">
+<!--
+/**
+ * @title Form
+ * @description 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: 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-option
+ * - 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
+ * - 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.
+ *
+ * @related
+ * - buttonStrong: presents form submission as the primary action.
+ * - flexColumnTexts: spaces text elements in the radio group.
+ *
+ * @return Complete HTML form with required fields and an example script for a custom rule, validation, and a success message.
+ */
+-->
+
+<form pgs="form formValidate" action="#" method="post">
     <label pgs="label" for="form-name">
-        Nome
+        Name
     </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[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" 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[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[Enter a password]" type="password" name="password" autocomplete="new-password" required>
+
+    <label pgs="label" for="form-confirm-password">
+        Confirm password
+    </label>
+    <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"></textarea>
+    <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 pgs="toggle">
-        <span>Accetto la privacy policy</span>
+        <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>
+
+<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: "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", "Passwords do not match");
+            return [confirmPassword, password];
+        }
+    });
+
+    //== validate
+    formValidate.validator(event => {
+        const values = Object.fromEntries(new FormData(form));
+
+        // Replace this log with a request to your backend.
+        console.log(values);
+    }, "submit");
+</script>

package/templates/html/components/formAddon.html

@@ -0,0 +1,72 @@
+<!--
+/**
+ * @title Form Add-ons
+ * @description 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
+ * - flexColumnElements: vertically arranges the form add-on examples.
+ * - flexColumnTexts: groups each example with its heading and control.
+ *
+ * @return HTML examples of the checkboxBackground, twoState, toggle, and chips form controls using native checkbox and radio inputs.
+ */
+-->
+
+<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/templates/html/components/logo.html

@@ -1,7 +1,28 @@
+<!--
+/**
+ * @title Logo
+ * @description Component for displaying a graphical or text logo, with image variants that support dark mode.
+ *
+ * @pgs
+ * - logo: identifies the brand link container.
+ * - logo-image: identifies the graphical logo image.
+ * - logo-text: identifies the text-based brand variant.
+ *
+ * @pgs-option
+ * - logoDarkmode: inverts the logo image when the global darkmode state is active.
+ * - logoDarkmodeFixed: keeps the image inversion enabled regardless of the current theme.
+ *
+ * @pgs-state
+ * - darkmode: global document state that activates the logoDarkmode variant.
+ *
+ * @return HTML examples of the theme-aware graphical logo and the text logo.
+ */
+-->
+
 <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/templates/html/components/menu.html

@@ -1,3 +1,36 @@
+<!--
+/**
+ * @title Menu
+ * @description Menu markup, configuration, behavior, and usage example.
+ *
+ * @pgs
+ * - menu: identifies the menu element used by Menu.
+ * - menu-buttonIcon: identifies the menu-buttonIcon element used by Menu.
+ *
+ * @pgs-option
+ * - 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-state
+ * - open: identifies the open element used by Menu.
+ *
+ * @api
+ * - 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.
+ *
+ * @related
+ * - 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.
+ *
+ * @return Complete HTML markup and usage example for 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,16 +1,60 @@
+<!--
+/**
+ * @title Modal
+ * @description Modal markup, configuration, behavior, and usage example.
+ *
+ * @pgs
+ * - 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: 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-option
+ * - 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
+ * - 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.
+ *
+ * @related
+ * - 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.
+ *
+ * @return Complete HTML markup and usage example for Modal.
+ */
+-->
+
 <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>
@@ -18,17 +62,17 @@
 
 <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>
@@ -36,17 +80,17 @@
 
 <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>
@@ -54,21 +98,21 @@
 
 <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>