mypgs 1.6.0 → 2.1.0

package/docs/components/notification.md

@@ -0,0 +1,81 @@
+<!-- Automatically generated from templates/html/components/notification.html. Edit templates/html/components/notification.html and run npm run docs:generate again. -->
+
+# Notification
+
+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 Options
+
+- `toast`: identifies the toast element used by Notification.
+- `notification`: identifies the notification element used by Notification.
+
+## PGS States
+
+- `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.
+
+## JavaScript 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 elements
+
+- `hidden`: uses the related hidden component or utility in this example.
+- `buttonClose`: uses the related buttonClose component or utility in this example.
+
+## Output
+
+Complete HTML markup and usage example for Notification.
+
+## Example
+
+```html
+<div pgs="notification" aria-live="polite"></div>
+<div pgs="notification" pgs-option="toast" aria-live="polite"></div>
+
+<div pgs="hidden notificationTrigger" pgs-option='notification[{
+            "title": "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>
+-->
+```

package/docs/components/search.md

@@ -0,0 +1,118 @@
+<!-- Automatically generated from templates/html/components/search.html. Edit templates/html/components/search.html and run npm run docs:generate again. -->
+
+# Search
+
+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 Options
+
+- `containerPGS`: identifies the containerPGS element used by Search.
+
+## PGS States
+
+- `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.
+
+## JavaScript 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 elements
+
+- `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.
+
+## Output
+
+Complete HTML markup and usage example for Search.
+
+## Example
+
+```html
+<form pgs="buttonNohover search" autocomplete="off" action="" method="get">
+    <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="Search">
+        <i class="fa-solid fa-search"></i>
+    </button>
+
+    <dialog>
+        <div pgs="flexRow section search-mobile">
+
+            <form pgs="buttonNohover search" autocomplete="off" action="/" method="get">
+                <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>
+
+                <button type="button" pgs="modal-close buttonIcon">
+                    <i class="fa-solid fa-close"></i>
+                </button>
+            </form>
+
+
+        </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/docs/components/slides.md

@@ -0,0 +1,85 @@
+<!-- Automatically generated from templates/html/components/slides.html. Edit templates/html/components/slides.html and run npm run docs:generate again. -->
+
+# Slides
+
+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 Options
+
+- `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.
+
+## JavaScript 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 elements
+
+- `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.
+
+## Output
+
+Complete HTML markup and usage example for Slides.
+
+## Example
+
+```html
+<div pgs="slides" pgs-option="singleScroll shadowDesktop">
+    <ul pgs="slides-container">
+        <li>
+            <article pgs="card flexColumn">
+                <img pgs="card-img imgCover" src="https://placehold.co/800x500?text=Slide+1" alt="Slide 1">
+                <div pgs="flexColumnTexts">
+                    <h3>Slide uno</h3>
+                    <p>First slide content.</p>
+                </div>
+            </article>
+        </li>
+
+        <li>
+            <article pgs="card flexColumn">
+                <img pgs="card-img imgCover" src="https://placehold.co/800x500?text=Slide+2" alt="Slide 2">
+                <div pgs="flexColumnTexts">
+                    <h3>Slide due</h3>
+                    <p>Second slide content.</p>
+                </div>
+            </article>
+        </li>
+
+        <li>
+            <article pgs="card flexColumn">
+                <img pgs="card-img imgCover" src="https://placehold.co/800x500?text=Slide+3" alt="Slide 3">
+                <div pgs="flexColumnTexts">
+                    <h3>Slide tre</h3>
+                    <p>Third slide content.</p>
+                </div>
+            </article>
+        </li>
+    </ul>
+</div>
+```

package/docs/components/stepTabs.md

@@ -0,0 +1,93 @@
+<!-- Automatically generated from templates/html/components/stepTabs.html. Edit templates/html/components/stepTabs.html and run npm run docs:generate again. -->
+
+# Step Tabs
+
+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 Options
+
+- `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 States
+
+- `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.
+
+## JavaScript 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 elements
+
+- `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.
+
+## Output
+
+Complete HTML markup and usage example for Step Tabs.
+
+## Example
+
+```html
+<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>Personal details</h3>
+            <p>First tab content.</p>
+        </section>
+
+        <section pgs="tab flexColumnTexts" tabindex="-1" pgs-option="tabIcon[fa-list-check]">
+            <h3>Preferences</h3>
+            <p>Second tab content.</p>
+        </section>
+
+        <section pgs="tab flexColumnTexts" tabindex="-1" pgs-option="tabIcon[fa-check]">
+            <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>
+            Back
+        </button>
+
+        <button pgs="stepTabs-restart button" type="button">
+            Ricomincia
+        </button>
+
+        <button pgs="stepTabs-next button" pgs-option="buttonReverse" type="button">
+            Next
+            <i class="fa-solid fa-arrow-right" aria-hidden="true"></i>
+        </button>
+    </div>
+</div>
+```

package/docs/components/steps.md

@@ -0,0 +1,56 @@
+<!-- Automatically generated from templates/html/components/steps.html. Edit templates/html/components/steps.html and run npm run docs:generate again. -->
+
+# Steps
+
+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.
+
+## JavaScript 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.
+
+## Output
+
+Ordered HTML list of numbered steps completed by the JavaScript module.
+
+## Example
+
+```html
+<ol pgs="steps">
+    <li pgs="steps-step">
+        <span pgs="steps-step-circle">1</span>
+        <div pgs="steps-step-content">
+            <h3>Primo step</h3>
+            <p>Descrizione del primo passaggio.</p>
+        </div>
+    </li>
+
+    <li pgs="steps-step">
+        <span pgs="steps-step-circle">2</span>
+        <div pgs="steps-step-content">
+            <h3>Secondo step</h3>
+            <p>Descrizione del secondo passaggio.</p>
+        </div>
+    </li>
+
+    <li pgs="steps-step">
+        <span pgs="steps-step-circle">3</span>
+        <div pgs="steps-step-content">
+            <h3>Terzo step</h3>
+            <p>Descrizione del terzo passaggio.</p>
+        </div>
+    </li>
+</ol>
+```

package/docs/components/summary.md

@@ -0,0 +1,49 @@
+<!-- Automatically generated from templates/html/components/summary.html. Edit templates/html/components/summary.html and run npm run docs:generate again. -->
+
+# Summary
+
+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 States
+
+- `overflow`: identifies the overflow element used by Summary.
+- `open`: identifies the open element used by Summary.
+
+## JavaScript 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.
+
+## Output
+
+Complete HTML markup and usage example for Summary.
+
+## Example
+
+```html
+<div pgs="summary">
+    <div pgs="summary-content">
+        <p>
+            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>
+            When content exceeds three lines, a button is shown to expand or collapse the visible area.
+        </p>
+    </div>
+
+    <button pgs="summary-button" type="button">
+        Show more
+    </button>
+</div>
+```

package/docs/components/table.md

@@ -0,0 +1,42 @@
+<!-- Automatically generated from templates/html/components/table.html. Edit templates/html/components/table.html and run npm run docs:generate again. -->
+
+# Table
+
+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.
+
+## Output
+
+Complete HTML table wrapped in the dedicated PGS container.
+
+## Example
+
+```html
+<div pgs="table">
+    <table>
+        <thead>
+            <tr>
+                <th>Name</th>
+                <th>Stato</th>
+                <th>Data</th>
+            </tr>
+        </thead>
+
+        <tbody>
+            <tr>
+                <td>Elemento uno</td>
+                <td>Active</td>
+                <td>2026-01-01</td>
+            </tr>
+            <tr>
+                <td>Elemento due</td>
+                <td>Bozza</td>
+                <td>2026-02-01</td>
+            </tr>
+        </tbody>
+    </table>
+</div>
+```

package/docs/components/tooltip.md

@@ -0,0 +1,53 @@
+<!-- Automatically generated from templates/html/components/tooltip.html. Edit templates/html/components/tooltip.html and run npm run docs:generate again. -->
+
+# Tooltip
+
+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 Options
+
+- `position`: identifies the position element used by Tooltip.
+
+## PGS States
+
+- `open`: identifies the open element used by Tooltip.
+
+## JavaScript 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 elements
+
+- `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.
+
+## Output
+
+Complete HTML markup and usage example for Tooltip.
+
+## Example
+
+```html
+<span pgs="dropdown tooltip">
+    <button pgs="dropdown-button buttonMini tooltip-button" title="open-tooltip" type="button">
+        <i class="fa-solid fa-info"></i>
+    </button>
+    <div pgs="dropdown-content tooltip-content">
+        Lorem ipsum dolor sit amet consectetur adipisicing elit. Iusto hic, id consectetur facilis et, iste animi minima quidem praesentium omnis quod. Quidem provident ad cum aut reprehenderit laboriosam eum placeat.
+    </div>
+</span>
+```

package/docs/convenzioni.md

@@ -1,12 +1,12 @@
-# Convenzioni
+# Conventions
 
-- Usa `pgs` come prima scelta per markup, layout, componenti e comportamenti.
-- Mantieni coerenti i token tra template, SCSS e JS.
-- Usa `pgs-state` per stati runtime.
-- Usa `pgs-option` per opzioni dichiarative.
-- Preferisci custom properties e mixin a CSS hardcoded.
-- Non duplicare componenti gia' presenti nella libreria.
-- Non inventare API: verifica i sorgenti in `assets/javascript/`.
-- Mantieni in `mypgs` solo stili e comportamenti riutilizzabili.
-- Mantieni nel progetto finale le personalizzazioni specifiche del progetto.
-- Aggiorna `AGENTS.md` quando introduci pattern importanti.
+- Use `pgs` as the first choice for markup, layouts, components, and behaviors.
+- Keep tokens consistent across templates, SCSS, and JavaScript.
+- Use `pgs-state` for runtime states.
+- Use `pgs-option` for declarative options.
+- Prefer custom properties and mixins to hardcoded CSS.
+- Do not duplicate components that already exist in the library.
+- Do not invent APIs: verify the sources in `assets/javascript/`.
+- Keep only reusable styles and behaviors in `mypgs`.
+- Keep project-specific customizations in the consuming project.
+- Update `AGENTS.md` when introducing important patterns.

package/docs/export-e-sviluppo.md

@@ -36,7 +36,7 @@ Uso sorgente SCSS:
 
 ## Sviluppo
 
-Build una tantum:
+One-time build:
 
 ```bash
 npm run start
@@ -54,7 +54,7 @@ Creare un pacchetto locale:
 npm pack
 ```
 
-Flusso consigliato quando modifichi la libreria:
+Recommended workflow when modifying the library:
 
 1. modifica i sorgenti in `assets/`;
 2. aggiorna template o documentazione se cambia il modo d'uso;
@@ -67,7 +67,7 @@ Nota: se la build Webpack fallisce, non modificare manualmente `dist/javascript`
 
 ## Aggiungere un nuovo modulo
 
-Esempio componente:
+Component example:
 
 ```js
 export function PGS_myComponent_init(root = document) {