mypgs 2.0.0 → 3.0.0

package/{templates → reference}/html/components/dropdown.html

@@ -1,34 +1,34 @@
 <!--
 /**
  * @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.
+ * @description Popup component that connects a control to content positioned relative to its trigger and handles opening, closing, outside clicks, and 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.
+ * - 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: 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.
+ * - 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: indica che il dropdown è aperto e che il contenuto è visibile.
+ * - open: indicates that the dropdown is open and its content is visible.
  *
  * @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.
+ * - 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: dispone i diversi esempi di posizionamento sulla stessa riga flessibile.
- * - button: applica lo stile standard ai controlli del dropdown.
+ * - flexRow: arranges the placement examples on the same flexible row.
+ * - button: applies standard styling to dropdown controls.
  *
- * @return Serie di dropdown HTML che dimostra le direzioni di posizionamento supportate.
+ * @return Series of HTML dropdowns demonstrating the supported placement directions.
  */
 -->
 
@@ -41,7 +41,7 @@
         </button>
 
         <div pgs="dropdown-content">
-            Contenuto bottom center
+            bottom center content
         </div>
     </span>
 
@@ -52,7 +52,7 @@
         </button>
 
         <div pgs="dropdown-content">
-            Contenuto top left
+            top left content
         </div>
     </span>
 
@@ -63,7 +63,7 @@
         </button>
 
         <div pgs="dropdown-content">
-            Contenuto top center
+            top center content
         </div>
     </span>
 
@@ -74,7 +74,7 @@
         </button>
 
         <div pgs="dropdown-content">
-            Contenuto top right
+            top right content
         </div>
     </span>
 
@@ -85,7 +85,7 @@
         </button>
 
         <div pgs="dropdown-content">
-            Contenuto bottom left
+            bottom left content
         </div>
     </span>
 
@@ -96,7 +96,7 @@
         </button>
 
         <div pgs="dropdown-content">
-            Contenuto bottom right
+            bottom right content
         </div>
     </span>
 
@@ -107,7 +107,7 @@
         </button>
 
         <div pgs="dropdown-content">
-            Contenuto left center
+            left center content
         </div>
     </span>
 
@@ -118,7 +118,7 @@
         </button>
 
         <div pgs="dropdown-content">
-            Contenuto right center
+            right center content
         </div>
     </span>
 

package/reference/html/components/form.html

@@ -0,0 +1,128 @@
+<!--
+/**
+ * @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.
+ * - buttonStrong: presents form submission as the primary action.
+ *
+ * @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
+ * - button: provides the base styling for the primary submit action.
+ * - flexColumn: 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">
+        Name
+    </label>
+    <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[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">
+        Message
+    </label>
+    <textarea id="form-message" pgs="textarea" name="message" rows="5" placeholder="Write your message" required></textarea>
+
+    <br>
+    <fieldset pgs="radio flexColumn">
+        <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="button" pgs-option="buttonStrong" type="submit">
+        <i class="fa-solid fa-paper-plane" aria-hidden="true"></i>
+        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/reference/html/components/formAddon.html

@@ -0,0 +1,109 @@
+<!--
+/**
+ * @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.
+ * - chip: presents an individual checkbox or radio option as a compact selectable button.
+ * - chips: groups twoState controls into a compact segmented selector.
+ *
+ * @related
+ * - form: applies the base form styles to the complete add-on example.
+ * - flexColumn: vertically arranges each example with its heading and control.
+ * - flexRow: horizontally arranges standalone chip controls.
+ * - gapElements: applies element spacing between the form add-on examples.
+ *
+ * @return HTML examples of the checkboxBackground, twoState, toggle, and chips form controls using native checkbox and radio inputs.
+ */
+-->
+
+<form pgs="form flexColumn gapElements">
+    <section pgs="flexColumn">
+        <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="flexColumn">
+        <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="flexColumn">
+        <strong>Toggle</strong>
+
+        <label pgs="toggle">
+            <span>Enable Wi-Fi</span>
+            <input type="checkbox" name="darkMode" value="enabled">
+        </label>
+    </section>
+
+    <section pgs="flexColumn">
+        <strong>Chips checkbox</strong>
+        <div pgs="flexRow" role="group" aria-label="Chip actions">
+            <label pgs="chip">
+                <input type="checkbox" name="like" value="basic">
+                <i class="fa-solid fa-heart"></i>
+                Like
+            </label>
+            <label pgs="chip">
+                <input type="checkbox" name="share" value="basic">
+                <i class="fa-solid fa-share"></i>
+                Share
+            </label>
+        </div>
+    </section>
+
+    <section pgs="flexColumn gapElements">
+        <fieldset pgs="chips">
+            <legend>Chip checkbox</legend>
+            <label>
+                <input type="checkbox" name="plan" value="basic" checked>
+                Basic
+            </label>
+
+            <label>
+                <input type="checkbox" name="plan" value="pro">
+                Pro
+            </label>
+
+            <label>
+                <input type="checkbox" name="plan" value="enterprise">
+                Enterprise
+            </label>
+        </fieldset>
+
+        <fieldset pgs="chips">
+            <legend>Chips radio</legend>
+            <label>
+                <input type="radio" name="characters" value="basic" checked>
+                <i class="fa-solid fa-crow"></i>
+                Crow
+            </label>
+
+            <label>
+                <i class="fa-solid fa-dove"></i> <input type="radio" name="characters" value="pro">
+                Dove
+            </label>
+
+            <label>
+                <i class="fa-solid fa-dragon"></i> <input type="radio" name="characters" value="enterprise">
+                dragon
+            </label>
+        </fieldset>
+    </section>
+</form>

package/reference/html/components/logo.html

@@ -0,0 +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="Text logo" pgs="logo" href="/">
+    <span pgs="logo-text">MyPGS</span>
+</a>

package/{templates → reference}/html/components/menu.html

@@ -1,33 +1,33 @@
 <!--
 /**
  * @title Menu
- * @description Navigazione orizzontale o verticale che trasforma le voci con sottomenu in dropdown accessibili e inizializzati automaticamente.
+ * @description 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-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.
+ * - 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.
+ * - buttonNohover: disables hover behavior on menu buttons generated at runtime.
  *
  * @pgs-state
- * - open: indica il sottomenu trasformato in dropdown attualmente aperto.
+ * - open: identifies the open element used by Menu.
  *
  * @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.
  *
  * @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.
+ * - dropdown: uses the related dropdown component or utility in this example.
+ * - dropdown-button: uses the related dropdown-button component or utility in this example.
+ * - dropdown-content: uses the related dropdown-content component or utility in this example.
  *
- * @return Due strutture nav complete per le varianti orizzontale e verticale del menu.
+ * @return Complete HTML markup and usage example for Menu.
  */
 -->
 
@@ -77,4 +77,4 @@
             </a>
         </li>
     </ul>
-</nav>
+</nav>

package/reference/html/components/modal.html

@@ -0,0 +1,123 @@
+<!--
+/**
+ * @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.
+ * - buttonStrong: applies stronger emphasis to the save action.
+ * - buttonClose: styles the close action generated at runtime.
+ *
+ * @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.
+ * - flexColumn: vertically organizes modal content.
+ * - gapElements: applies element spacing to modal content.
+ * - 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> Open modal
+    </button>
+
+    <dialog>
+        <div pgs="modal-dialog-content">
+            <div pgs="modal-dialog-content-header">
+                <h3>Example modal</h3>
+            </div>
+
+            <div pgs="modal-dialog-content-scroll">
+                <p>Modal content. The close button is added automatically when missing.</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> Open modal right
+    </button>
+
+    <dialog pgs-option="right">
+        <div pgs="modal-dialog-content">
+            <div pgs="modal-dialog-content-header">
+                <h3>Side modal</h3>
+            </div>
+
+            <div pgs="modal-dialog-content-scroll">
+                <p>Modal content with <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> Open modal left
+    </button>
+
+    <dialog pgs-option="left">
+        <div pgs="modal-dialog-content">
+            <div pgs="modal-dialog-content-header">
+                <h3>Left-side modal</h3>
+            </div>
+
+            <div pgs="modal-dialog-content-scroll">
+                <p>Modal content with <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> Confirmation salvataggio
+    </button>
+
+    <dialog pgs-option="topLevel">
+        <div pgs="modal-dialog-content">
+            <div pgs="modal-dialog-content-header">
+                <h3>Save changes?</h3>
+            </div>
+
+            <div pgs="modal-dialog-content-scroll flexColumn gapElements">
+                <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">Cancel</button>
+                    <button pgs="button" pgs-option="buttonStrong" type="button">Save changes</button>
+                </div>
+            </div>
+        </div>
+    </dialog>
+</div>
+
+<div id="modal-container"></div>

package/reference/html/components/notification.html

@@ -0,0 +1,71 @@
+<!--
+/**
+ * @title Notification
+ * @description Notification markup, configuration, behavior, and usage example.
+ *
+ * @pgs
+ * - notification: identifies the notification element used by Notification.
+ * - notificationTrigger: identifies the notificationTrigger element used by Notification.
+ * - notification-element: identifies the notification-element element used by Notification.
+ * - notification-element-title: identifies the notification-element-title element used by Notification.
+ * - notification-element-content: identifies the notification-element-content element used by Notification.
+ *
+ * @pgs-option
+ * - toast: identifies the toast element used by Notification.
+ * - notification: identifies the notification element used by Notification.
+ * - buttonClose: styles the dismiss action generated at runtime.
+ *
+ * @pgs-state
+ * - success: identifies the success element used by Notification.
+ * - error: identifies the error element used by Notification.
+ * - warning: identifies the warning element used by Notification.
+ * - info: identifies the info element used by Notification.
+ *
+ * @api
+ * - pgs.notification.trigger(root): provides the documented operation through the component public API.
+ * - pgs.notification.alert.error(text, link, timeout, icon): provides the documented operation through the component public API.
+ * - pgs.notification.alert.success(text, link, timeout, icon): provides the documented operation through the component public API.
+ * - pgs.notification.alert.info(text, link, timeout, icon): provides the documented operation through the component public API.
+ * - pgs.notification.alert.warning(text, link, timeout, icon): provides the documented operation through the component public API.
+ * - pgs.notification.alert.deleteAll(): provides the documented operation through the component public API.
+ * - pgs.notification.toast.error(text, timeout, icon): provides the documented operation through the component public API.
+ * - pgs.notification.toast.success(text, timeout, icon): provides the documented operation through the component public API.
+ * - pgs.notification.toast.info(text, timeout, icon): provides the documented operation through the component public API.
+ * - pgs.notification.toast.warning(text, timeout, icon): provides the documented operation through the component public API.
+ * - pgs.notification.toast.deleteAll(): provides the documented operation through the component public API.
+ *
+ * @related
+ * - hidden: uses the related hidden component or utility in this example.
+ *
+ * @return Complete HTML markup and usage example for Notification.
+ */
+-->
+
+<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": "Title",
+            "message": "Message",
+            "element": "notification",
+            "type": "info",
+            "icon": null,
+            "duration": "-1",
+            "link": null
+        }]'></div>
+
+<div pgs="hidden notificationTrigger" pgs-option='notification[{
+            "title": "Benvenuto",
+            "message": "Message",
+            "element": "toast",
+            "type": "info",
+            "icon": null,
+            "duration": "3000",
+            "link": null
+        }]'></div>
+<!-- 
+    <div
+        pgs="hidden notificationTrigger"
+        pgs-option='notification[{"title":"Title","message":"Message","element":"notification","type":"info","icon":"<i class=\"fa-solid fa-rocket\"></i>","duration":"4000","link":"/page/"}]'>
+    </div>
+-->