mypgs 1.6.0 → 2.1.0

package/templates/html/components/notification.html

@@ -1,35 +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.
+ *
+ * @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.
+ * - buttonClose: uses the related buttonClose component or utility in this example.
+ *
+ * @return Complete HTML markup and usage example for Notification.
+ */
+-->
+
 <div pgs="notification" aria-live="polite"></div>
-<div pgs="toast" aria-live="polite"></div>
+<div pgs="notification" pgs-option="toast" aria-live="polite"></div>
 
-<div pgs="hidden notificationTrigger" data-notification='{
-        "title":"Titolo",
-        "message":"Messaggio",
-        "element":"notification",
-        "type":"info",
-        "icon":null,
-        "duration":"-1",
-        "link":null
-    }'>
-</div>
-<div pgs="hidden notificationTrigger" data-notification='{
-        "title":"Benvetuto",
-        "message":"Messaggio",
-        "element":"toast",
-        "type":"info",
-        "icon":null,
-        "duration":"3000",
-        "link":null
-    }'>
-</div>
+<div pgs="hidden notificationTrigger" pgs-option='notification[{
+            "title": "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" data-notification='{
-        "title":"Titolo",
-        "message":"Messaggio",
-        "element":"notification | toast",
-        "type":"info | success | warning | error",
-        "icon":"null | <i class=\"fa-solid fa-rocket\"></i>",
-        "duration":"-1 | 0 | 4000 | 5000",
-        "link":"null | /pagina/"
-    }'>
-</div>
--->
+    <div
+        pgs="hidden notificationTrigger"
+        pgs-option='notification[{"title":"Title","message":"Message","element":"notification","type":"info","icon":"<i class=\"fa-solid fa-rocket\"></i>","duration":"4000","link":"/page/"}]'>
+    </div>
+-->

package/templates/html/components/search.html

@@ -1,12 +1,64 @@
+<!--
+/**
+ * @title Search
+ * @description Search markup, configuration, behavior, and usage example.
+ *
+ * @pgs
+ * - search: identifies the search element used by Search.
+ * - search-suggestions: identifies the search-suggestions element used by Search.
+ * - search-suggestions-item: identifies the search-suggestions-item element used by Search.
+ * - search-modal: identifies the search-modal element used by Search.
+ * - search-mobile: identifies the search-mobile element used by Search.
+ *
+ * @pgs-option
+ * - containerPGS: identifies the containerPGS element used by Search.
+ *
+ * @pgs-state
+ * - open: identifies the open element used by Search.
+ * - loading: identifies the loading element used by Search.
+ * - error: identifies the error element used by Search.
+ * - selected: identifies the selected element used by Search.
+ *
+ * @api
+ * - pgs.search.init(root): initializes matching elements within the specified root.
+ * - pgs.search.api(element): returns the instance associated with the specified initialized element.
+ * - instance.configure(options): provides the documented operation through the component public API.
+ * - instance.setSource(source): provides the documented operation through the component public API.
+ * - instance.search(query): provides the documented operation through the component public API.
+ * - instance.open(): opens the component.
+ * - instance.close(): closes the component.
+ * - instance.clear(): provides the documented operation through the component public API.
+ * - instance.cancel(): annulla debounce e richiesta attiva.
+ * - instance.select(index, submit): provides the documented operation through the component public API.
+ * - instance.refresh(): refreshes the component and returns its updated instance.
+ * - instance.destroy(): removes listeners and releases the component instance.
+ * - instance.items(): provides the documented operation through the component public API.
+ * - instance.isOpen(): returns true when the component is open.
+ * - instance.isLoading(): returns true while the component is loading.
+ * - instance.setActiveIndex(index): provides the documented operation through the component public API.
+ *
+ * @related
+ * - buttonNohover: uses the related buttonNohover component or utility in this example.
+ * - modal: uses the related modal component or utility in this example.
+ * - modal-button: uses the related modal-button component or utility in this example.
+ * - modal-close: uses the related modal-close component or utility in this example.
+ * - buttonIcon: uses the related buttonIcon component or utility in this example.
+ * - flexRow: uses the related flexRow component or utility in this example.
+ * - section: uses the related section component or utility in this example.
+ *
+ * @return Complete HTML markup and usage example for Search.
+ */
+-->
+
 <form pgs="buttonNohover search" autocomplete="off" action="" method="get">
-    <button type="submit" title="Cerca"><i class="fa-solid fa-search"></i></button>
-    <input type="search" name="s" placeholder="Cerca" value="">
+    <button type="submit" title="Search"><i class="fa-solid fa-search"></i></button>
+    <input type="search" name="s" placeholder="Search" value="">
     <ul pgs="search-suggestions"></ul>
 </form>
 
 <div pgs="modal search-modal" pgs-option="containerPGS[header]">
 
-    <button type="button" pgs="modal-button buttonIcon" title="Cerca">
+    <button type="button" pgs="modal-button buttonIcon" title="Search">
         <i class="fa-solid fa-search"></i>
     </button>
 
@@ -14,18 +66,43 @@
         <div pgs="flexRow section search-mobile">
 
             <form pgs="buttonNohover search" autocomplete="off" action="/" method="get">
-                <button type="submit" title="Cerca">
+                <button type="submit" title="Search">
                     <i class="fa-solid fa-search"></i>
                 </button>
 
-                <input type="search" name="s" placeholder="Cerca" value="">
+                <input type="search" name="s" placeholder="Search" value="">
                 <ul pgs="search-suggestions"></ul>
+
+                <button type="button" pgs="modal-close buttonIcon">
+                    <i class="fa-solid fa-close"></i>
+                </button>
             </form>
 
-            <button type="button" pgs="modal-close buttonIcon">
-                <i class="fa-solid fa-close"></i>
-            </button>
 
         </div>
     </dialog>
 </div>
+
+<script type="module">
+    import { pgs } from "mypgs";
+
+    const components = [
+        { label: "Accordion", value: "/componenti/accordion", data: { category: "component" } },
+        { label: "Dropdown", value: "/componenti/dropdown", data: { category: "component" } },
+        { label: "Modal", value: "/componenti/modal", data: { category: "component" } },
+        { label: "Search", value: "/componenti/search", data: { category: "component" } },
+        { label: "Page Shell", value: "/layout/page-shell", data: { category: "layout" } },
+    ];
+
+    pgs(document).querySelectorAll("search").forEach(search => {
+        pgs.search.api(search)?.configure({
+            minLength: 1,
+            debounce: 150,
+            limit: 5,
+            source: components,
+            onSelect: ({ item, value }) => {
+                console.log(`Selezionato ${item.label}: ${value}`);
+            },
+        });
+    });
+</script>

package/templates/html/components/slides.html

@@ -1,3 +1,46 @@
+<!--
+/**
+ * @title Slides
+ * @description Slides markup, configuration, behavior, and usage example.
+ *
+ * @pgs
+ * - slides: identifies the slides element used by Slides.
+ * - slides-container: identifies the slides-container element used by Slides.
+ * - slides-prec: identifies the slides-prec element used by Slides.
+ * - slides-next: identifies the slides-next element used by Slides.
+ * - slides-dots: identifies the slides-dots element used by Slides.
+ *
+ * @pgs-option
+ * - singleScroll: identifies the singleScroll element used by Slides.
+ * - shadowDesktop: identifies the shadowDesktop element used by Slides.
+ * - notScrollAnimation: identifies the notScrollAnimation element used by Slides.
+ * - notScrollWithMouse: identifies the notScrollWithMouse element used by Slides.
+ *
+ * @api
+ * - pgs.slides.init(root): initializes matching elements within the specified root.
+ * - pgs.slides.api(element): returns the instance associated with the specified initialized element.
+ * - instance.previous(): moves to the previous item.
+ * - instance.next(): moves to the next item.
+ * - instance.goTo(index): provides the documented operation through the component public API.
+ * - instance.getCurrentIndexes(): provides the documented operation through the component public API.
+ * - instance.getCurrentElements(): provides the documented operation through the component public API.
+ * - instance.getTotal(): returns the total number of items.
+ * - instance.isAtStart(): provides the documented operation through the component public API.
+ * - instance.isAtEnd(): provides the documented operation through the component public API.
+ * - instance.refresh(): refreshes the component and returns its updated instance.
+ *
+ * @related
+ * - card: uses the related card component or utility in this example.
+ * - card-img: uses the related card-img component or utility in this example.
+ * - imgCover: uses the related imgCover component or utility in this example.
+ * - flexColumn: uses the related flexColumn component or utility in this example.
+ * - flexColumnTexts: uses the related flexColumnTexts component or utility in this example.
+ * - buttonIcon: uses the related buttonIcon component or utility in this example.
+ *
+ * @return Complete HTML markup and usage example for Slides.
+ */
+-->
+
 <div pgs="slides" pgs-option="singleScroll shadowDesktop">
     <ul pgs="slides-container">
         <li>
@@ -5,7 +48,7 @@
                 <img pgs="card-img imgCover" src="https://placehold.co/800x500?text=Slide+1" alt="Slide 1">
                 <div pgs="flexColumnTexts">
                     <h3>Slide uno</h3>
-                    <p>Contenuto della prima slide.</p>
+                    <p>First slide content.</p>
                 </div>
             </article>
         </li>
@@ -15,7 +58,7 @@
                 <img pgs="card-img imgCover" src="https://placehold.co/800x500?text=Slide+2" alt="Slide 2">
                 <div pgs="flexColumnTexts">
                     <h3>Slide due</h3>
-                    <p>Contenuto della seconda slide.</p>
+                    <p>Second slide content.</p>
                 </div>
             </article>
         </li>
@@ -25,7 +68,7 @@
                 <img pgs="card-img imgCover" src="https://placehold.co/800x500?text=Slide+3" alt="Slide 3">
                 <div pgs="flexColumnTexts">
                     <h3>Slide tre</h3>
-                    <p>Contenuto della terza slide.</p>
+                    <p>Third slide content.</p>
                 </div>
             </article>
         </li>

package/templates/html/components/stepTabs.html

@@ -1,27 +1,74 @@
+<!--
+/**
+ * @title Step Tabs
+ * @description Step Tabs markup, configuration, behavior, and usage example.
+ *
+ * @pgs
+ * - stepTabs: identifies the stepTabs element used by Step Tabs.
+ * - stepTabs-dots: identifies the stepTabs-dots element used by Step Tabs.
+ * - stepTabs-dots-dot: identifies the stepTabs-dots-dot element used by Step Tabs.
+ * - stepTabs-container: identifies the stepTabs-container element used by Step Tabs.
+ * - tab: identifies the tab element used by Step Tabs.
+ * - stepTabs-prev: identifies the stepTabs-prev element used by Step Tabs.
+ * - stepTabs-restart: identifies the stepTabs-restart element used by Step Tabs.
+ * - stepTabs-next: identifies the stepTabs-next element used by Step Tabs.
+ *
+ * @pgs-option
+ * - tabIcon: identifies the tabIcon element used by Step Tabs.
+ * - step: identifies the step element used by Step Tabs.
+ * - buttonReverse: identifies the buttonReverse element used by Step Tabs.
+ *
+ * @pgs-state
+ * - is-active: identifies the is-active element used by Step Tabs.
+ * - is-completed: identifies the is-completed element used by Step Tabs.
+ * - is-locked: identifies the is-locked element used by Step Tabs.
+ *
+ * @api
+ * - pgs.stepTabs.init(root): initializes matching elements within the specified root.
+ * - pgs.stepTabs.api(element): returns the instance associated with the specified initialized element.
+ * - instance.restart(): torna al primo tab e ripristina i blocchi dichiarati inizialmente.
+ * - instance.goTo(index, scroll): provides the documented operation through the component public API.
+ * - instance.next(): moves to the next item.
+ * - instance.prev(): moves to the previous item.
+ * - instance.toggleLock(index, lock): provides the documented operation through the component public API.
+ * - instance.refresh(): refreshes the component and returns its updated instance.
+ * - instance.getCurrent(): provides the documented operation through the component public API.
+ * - instance.getState(): provides the documented operation through the component public API.
+ *
+ * @related
+ * - flexColumnElements: uses the related flexColumnElements component or utility in this example.
+ * - flexColumnTexts: uses the related flexColumnTexts component or utility in this example.
+ * - flexRow: uses the related flexRow component or utility in this example.
+ * - button: uses the related button component or utility in this example.
+ *
+ * @return Complete HTML markup and usage example for Step Tabs.
+ */
+-->
+
 <div pgs="stepTabs flexColumnElements">
     <div pgs="stepTabs-dots" aria-label="Avanzamento"></div>
 
     <div pgs="stepTabs-container">
         <section pgs="tab flexColumnTexts" tabindex="-1" pgs-option="tabIcon[fa-user]">
-            <h3>Dati personali</h3>
-            <p>Contenuto del primo tab.</p>
+            <h3>Personal details</h3>
+            <p>First tab content.</p>
         </section>
 
         <section pgs="tab flexColumnTexts" tabindex="-1" pgs-option="tabIcon[fa-list-check]">
-            <h3>Preferenze</h3>
-            <p>Contenuto del secondo tab.</p>
+            <h3>Preferences</h3>
+            <p>Second tab content.</p>
         </section>
 
         <section pgs="tab flexColumnTexts" tabindex="-1" pgs-option="tabIcon[fa-check]">
-            <h3>Conferma</h3>
-            <p>Contenuto del terzo tab.</p>
+            <h3>Confirmation</h3>
+            <p>Third tab content.</p>
         </section>
     </div>
 
     <div pgs="flexRow">
         <button pgs="stepTabs-prev button" type="button">
             <i class="fa-solid fa-arrow-left" aria-hidden="true"></i>
-            Indietro
+            Back
         </button>
 
         <button pgs="stepTabs-restart button" type="button">
@@ -29,7 +76,7 @@
         </button>
 
         <button pgs="stepTabs-next button" pgs-option="buttonReverse" type="button">
-            Avanti
+            Next
             <i class="fa-solid fa-arrow-right" aria-hidden="true"></i>
         </button>
     </div>

package/templates/html/components/steps.html

@@ -1,3 +1,27 @@
+<!--
+/**
+ * @title Steps
+ * @description Ordered list of steps showing a number, content, and connecting line, with missing structural elements added at runtime.
+ *
+ * @pgs
+ * - steps: identifies the ordered list initialized by the steps module.
+ * - steps-step: identifies each step in the sequence.
+ * - steps-step-circle: identifies the numeric indicator, which is created automatically when missing.
+ * - steps-step-content: identifies the text content of the step.
+ * - steps-step-line: identifies the connecting line dynamically added to each step.
+ *
+ * @api
+ * - pgs.steps.init(root): initializes unregistered step lists within the specified Document or Element.
+ * - pgs.steps.api(element): returns the instance associated with an initialized steps root.
+ * - instance.steps(): returns an array containing every steps-step element.
+ * - instance.getStep(index): returns the step at the specified index.
+ * - instance.getTotal(): returns the total number of steps.
+ * - instance.refresh(): reinitializes the list, recreates missing elements, and returns the new instance.
+ *
+ * @return Ordered HTML list of numbered steps completed by the JavaScript module.
+ */
+-->
+
 <ol pgs="steps">
     <li pgs="steps-step">
         <span pgs="steps-step-circle">1</span>

package/templates/html/components/summary.html

@@ -1,14 +1,41 @@
+<!--
+/**
+ * @title Summary
+ * @description Summary markup, configuration, behavior, and usage example.
+ *
+ * @pgs
+ * - summary: identifies the summary element used by Summary.
+ * - summary-content: identifies the summary-content element used by Summary.
+ * - summary-button: identifies the summary-button element used by Summary.
+ *
+ * @pgs-state
+ * - overflow: identifies the overflow element used by Summary.
+ * - open: identifies the open element used by Summary.
+ *
+ * @api
+ * - pgs.summary.init(root): initializes matching elements within the specified root.
+ * - pgs.summary.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.
+ *
+ * @return Complete HTML markup and usage example for Summary.
+ */
+-->
+
 <div pgs="summary">
     <div pgs="summary-content">
         <p>
-            Questo testo dimostrativo e' abbastanza lungo da occupare piu righe e mostrare il comportamento del componente summary. Il contenuto puo includere testo, link e altri elementi inline senza richiedere markup aggiuntivo.
+            This demonstration text is long enough to span multiple lines and show the summary component behavior. Content can include text, links, and other inline elements without requiring additional markup.
         </p>
         <p>
-            Quando il contenuto supera tre righe viene mostrato un pulsante per espandere o richiudere l'area visibile.
+            When content exceeds three lines, a button is shown to expand or collapse the visible area.
         </p>
     </div>
 
     <button pgs="summary-button" type="button">
-        Mostra di più
+        Show more
     </button>
 </div>

package/templates/html/components/table.html

@@ -1,8 +1,20 @@
+<!--
+/**
+ * @title Table
+ * @description Responsive container for a semantic table with headers and data rows consistent with the design system styles.
+ *
+ * @pgs
+ * - table: identifies the wrapper that manages presentation and scrolling for the native table.
+ *
+ * @return Complete HTML table wrapped in the dedicated PGS container.
+ */
+-->
+
 <div pgs="table">
     <table>
         <thead>
             <tr>
-                <th>Nome</th>
+                <th>Name</th>
                 <th>Stato</th>
                 <th>Data</th>
             </tr>
@@ -11,7 +23,7 @@
         <tbody>
             <tr>
                 <td>Elemento uno</td>
-                <td>Attivo</td>
+                <td>Active</td>
                 <td>2026-01-01</td>
             </tr>
             <tr>

package/templates/html/components/tooltip.html

@@ -1,3 +1,38 @@
+<!--
+/**
+ * @title Tooltip
+ * @description Tooltip markup, configuration, behavior, and usage example.
+ *
+ * @pgs
+ * - tooltip: identifies the tooltip element used by Tooltip.
+ * - tooltip-button: identifies the tooltip-button element used by Tooltip.
+ * - tooltip-content: identifies the tooltip-content element used by Tooltip.
+ *
+ * @pgs-option
+ * - position: identifies the position element used by Tooltip.
+ *
+ * @pgs-state
+ * - open: identifies the open element used by Tooltip.
+ *
+ * @api
+ * - pgs.dropdown.init(root): initializes matching elements within the specified root.
+ * - pgs.dropdown.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
+ * - 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.
+ * - buttonMini: uses the related buttonMini component or utility in this example.
+ *
+ * @return Complete HTML markup and usage example for Tooltip.
+ */
+-->
+
 <span pgs="dropdown tooltip">
     <button pgs="dropdown-button buttonMini tooltip-button" title="open-tooltip" type="button">
         <i class="fa-solid fa-info"></i>

package/templates/html/layout/body.html

@@ -1,3 +1,23 @@
+<!--
+/**
+ * @title Body
+ * @description Base HTML document that enables MyPGS, configures essential metadata, and applies shared background, text, and heading variants to the body.
+ *
+ * @pgs
+ * - htmlBase: applies the fundamental rules to the html element.
+ * - initP: enables layout, component, and pattern styles scoped to the MyPGS namespace.
+ * - bodyBase: applies the base structure and spacing to the body.
+ * - bodyImg: enables shared rules for images contained in the page.
+ * - bodyText: enables text typography and spacing.
+ * - bodyHeading: enables the typographic heading hierarchy.
+ *
+ * @pgs-state
+ * - darkmode: is applied dynamically to html and body to activate the dark theme.
+ *
+ * @return Complete HTML skeleton required to initialize the MyPGS library.
+ */
+-->
+
 <!DOCTYPE html>
 <html lang="it-IT" pgs="htmlBase initP">
 
@@ -9,12 +29,6 @@
 	<meta name="theme-color" content="">
 	<meta name="apple-mobile-web-app-status-bar-color" content="">
 
-    <!-- Fonts -->
-	<link rel="preconnect" href="https://fonts.googleapis.com">
-	<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-	<link href="https://fonts.googleapis.com/css2?family=Urbanist:ital,wght@0,100..900;1,100..900&display=swap" rel="stylesheet">
-
 </head>
 
 <body pgs="bodyBase bodyImg bodyText bodyHeading" >
-