mypgs 1.6.0 → 2.1.0

package/AGENTS.md

@@ -71,7 +71,7 @@ Patterns found:
 
 - `pgs` is the main attribute: tokens are separated by spaces, for example `pgs="button modal-button"`.
 - `assets/scss/index.scss` imports base, layout, components, and patterns; layouts/components/patterns are almost all scoped under `[pgs~=initP]`.
-- The main markup must enable the library with `htmlBase initP`, and the body with base body tokens. Use `templates/demo.html` and `templates/html/layout/body.html` as the canonical references.
+- The main markup must enable the library with `htmlBase initP`, and the body with base body tokens. Use `demo/demo.html` and `templates/html/layout/body.html` as the canonical references.
 - Components use a root token and child tokens with a consistent prefix. Use `templates/html/components/` as the canonical markup source.
 
 - Runtime states use `pgs-state`, for example `open`, `is-active`, `is-completed`, `is-locked`, `success`, `error`, `warning`, and `info`.
@@ -229,7 +229,7 @@ Canonical template references:
 - Layouts: `templates/html/layout/body.html`, `templates/html/layout/flex.html`, `templates/html/layout/grid.html`, `templates/html/layout/pageShell.html`, `templates/html/layout/section.html`
 - Components: `templates/html/components/accordion.html`, `templates/html/components/breadcumbs.html`, `templates/html/components/button.html`, `templates/html/components/card.html`, `templates/html/components/dropdown.html`, `templates/html/components/form.html`, `templates/html/components/logo.html`, `templates/html/components/menu.html`, `templates/html/components/modal.html`, `templates/html/components/notification.html`, `templates/html/components/search.html`, `templates/html/components/slides.html`, `templates/html/components/stepTabs.html`, `templates/html/components/steps.html`, `templates/html/components/table.html`, `templates/html/components/tooltip.html`
 - Patterns: `templates/html/patterns/cookieConsent.html`, `templates/html/patterns/footer.html`, `templates/html/patterns/header.html`
-- Complete demo assembly. DO NOT use this for inspiration. It is only used to show all the modules: `templates/demo.html`
+- Complete demo assembly. DO NOT use this for inspiration. It is only used to show all the modules: `demo/demo.html`
 
 Before creating markup, open the relevant template and reuse its current structure, tokens, ARIA attributes, and `pgs-option` syntax.
 

package/README.md

@@ -1,22 +1,22 @@
 # MyPGS
 
-`mypgs` e' una libreria frontend condivisa per costruire interfacce coerenti tramite attributi `pgs`, SCSS sorgenti, componenti UI e comportamenti JavaScript riutilizzabili.
+`mypgs` is a shared frontend library for building consistent interfaces through `pgs` attributes, SCSS sources, UI components, and reusable JavaScript behaviors.
 
-La libreria nasce come base di design system: layout, spacing, colori, bottoni, form, menu, modali, dropdown, ricerca con suggerimenti, slides, notifiche e pattern ricorrenti vengono definiti una volta sola e riusati nei progetti.
+The library provides a design-system foundation: layouts, spacing, colors, buttons, forms, menus, modals, dropdowns, suggestion search, slides, notifications, and recurring patterns are defined once and reused across projects.
 
-## Cosa contiene
+## What it includes
 
-- `assets/scss/`: SCSS sorgenti divisi in base, layout, componenti, pattern e mixin.
-- `assets/javascript/`: helper `pgs`, componenti JS, funzioni e pattern.
-- `templates/`: esempi HTML pronti per componenti e layout.
-- `dist/css/`: CSS compilato.
-- `dist/javascript/`: bundle JavaScript compilato.
-- `dist/index.d.ts`: dichiarazioni TypeScript esportate dal pacchetto.
-- `AGENTS.md`: guida operativa per AI.
+- `assets/scss/`: SCSS sources divided into base, layouts, components, patterns, and mixins.
+- `assets/javascript/`: the `pgs` helper, JavaScript components, functions, and patterns.
+- `templates/`: ready-to-use HTML examples for components and layouts.
+- `dist/css/`: compiled CSS.
+- `dist/javascript/`: compiled JavaScript bundle.
+- `dist/index.d.ts`: TypeScript declarations exported by the package.
+- `AGENTS.md`: operating guide for AI agents.
 
-## Installazione
+## Installation
 
-Da registry **npm**:
+From the **npm** registry:
 
 ```bash
 npm install mypgs
@@ -28,15 +28,15 @@ npm install mypgs
 import "mypgs";
 ```
 
-Se ti serve accedere direttamente all'helper:
+To access the helper directly:
 
 ```js
 import { pgs } from "mypgs";
 ```
 
-**React/TSX con Vite:**
+**React/TSX with Vite:**
 
-Configura il plugin che converte `pgsHtml` in `pgs`:
+Configure the plugin that converts `pgsHtml` into `pgs`:
 
 ```ts
 // vite.config.ts
@@ -51,7 +51,7 @@ export default {
 
 ### SCSS
 
-Se il progetto vuole compilare un CSS unico, importa gli SCSS sorgenti:
+To compile a single CSS file, import the SCSS sources:
 
 ```scss
 @use "sass:meta";
@@ -59,7 +59,7 @@ Se il progetto vuole compilare un CSS unico, importa gli SCSS sorgenti:
 @include meta.load-css("../../node_modules/mypgs/assets/scss/index.scss");
 ```
 
-Se servono solo i mixin:
+To import only the mixins:
 
 ```scss
 @use "../../node_modules/mypgs/assets/scss/mixin/mixin.scss" as * ;
@@ -67,20 +67,20 @@ Se servono solo i mixin:
 
 ### Markup
 
-`initP` e' importante: tutti i layout, componenti e pattern SCSS sono definiti sotto `[pgs~=initP]`.
+`initP` is required: every SCSS layout, component, and pattern is scoped under `[pgs~=initP]`.
 
 ```html
-<html lang="it" pgs="htmlBase initP">
+<html lang="en" pgs="htmlBase initP">
   <body pgs="bodyBase bodyImg bodyText bodyHeading">
     <main pgs="main"></main>
   </body>
 </html>
 ```
 
-## Documentazione
+## Documentation
 
-- [Utilizzo CSS/SCSS](docs/utilizzo-css-scss.md)
-- [Helper JavaScript](docs/helper-javascript.md)
-- [Componenti e markup](docs/componenti-e-markup.md)
-- [Export npm e sviluppo](docs/export-e-sviluppo.md)
-- [Convenzioni](docs/convenzioni.md)
+- [CSS/SCSS usage](docs/utilizzo-css-scss.md)
+- [JavaScript helper](docs/helper-javascript.md)
+- [Components and markup](docs/componenti-e-markup.md)
+- [npm exports and development](docs/export-e-sviluppo.md)
+- [Conventions](docs/convenzioni.md)

package/assets/javascript/components/_accordion.js

@@ -11,7 +11,7 @@ function directPgsChild(element, token) {
     return Array.from(element.children).find(child => pgs(child).contains(token));
 }
 
-export function PGS_accordion_init(root = document) {
+function PGS_accordion_init(root = document) {
     pgs(root).querySelectorAll("accordion").forEach((accordion) => {
         if (API.has(accordion)) return;
 
@@ -115,7 +115,7 @@ export function PGS_accordion_init(root = document) {
 PGS_accordion_init();
 
 //# API
-export function PGS_accordion_api(selector) {
+function PGS_accordion_api(selector) {
     return API.get(selector);
 }
 

package/assets/javascript/components/_modals.js

@@ -1,161 +1,184 @@
 //# MODAL
 const API = new WeakMap();
 
-export function PGS_modal_init(selector = "modal") {
-    pgs(document).querySelectorAll(selector).forEach(MODAL => {
-        if (API.has(MODAL)) return;
-
-        const BUTTON_OPEN = pgs(MODAL).querySelector("modal-button");        
-        const DIALOG = MODAL.querySelector("dialog");
-        if (!BUTTON_OPEN || !DIALOG) return;
-
-        //== SELECTOR
-        const DOMButtonClose = '<button pgs="buttonClose modal-close" type="button" tabindex="0" aria-label="Chiudi"><i class="fa-solid fa-close"></i></button>';
-        const modalContentHeader = pgs(MODAL)?.querySelector("modal-dialog-content-header")
-        
-        
-        //== OPTION ATTRIBUTES MODAL
-        const disableBackdropClose = pgs(MODAL).option.contains("disableBackdropClose")
-        const data_history = pgs(MODAL).option.contains("history");
-        const data_container = pgs(MODAL).option.getValueBrackets("containerID");
-        const data_containerPGS = pgs(MODAL).option.getValueBrackets("containerPGS");
-        
-        //== OPTION ATTRIBUTES DIALOG
-        const topLevel = pgs(DIALOG).option.contains("topLevel")
-
-        
-        //== BUTTON CLOSE
-        if (pgs(MODAL).querySelector("modal-close")) null
-        else if (modalContentHeader) modalContentHeader.insertAdjacentHTML("beforeend", DOMButtonClose)
-        else DIALOG.insertAdjacentHTML("beforeend", DOMButtonClose)
-        const BUTTON_CLOSE = pgs(MODAL).querySelector("modal-close")
-
-
-        //== SET
-        pgs(DIALOG).add("dialog modal-dialog");
-
-        //== BUTTON OPEN
-        BUTTON_OPEN.setAttribute("role", "button");
-        BUTTON_OPEN.setAttribute("aria-label", "apri modale");
-
-
-        //== POSITION
-        if(!topLevel){           
-            if (data_container) document.querySelector("#" + data_container)?.append(DIALOG);
-            else if (data_containerPGS) pgs(document).querySelector(data_containerPGS)?.append(DIALOG);
-            else document.body.append(DIALOG);
-        }
+function getModals(root) {
+    const modals = root instanceof Element && pgs(root).contains("modal") ? [root] : [];
+    modals.push(...pgs(root).querySelectorAll("modal"));
+    return modals;
+}
 
+function initializeModal(MODAL, existingDialog = null) {
+    if (API.has(MODAL)) return;
 
-        //+ FN STATUS 
-        function statusModal(status = true) {
-            BUTTON_OPEN?.setAttribute("aria-expanded", status);
-            DIALOG?.setAttribute("aria-expanded", status);
-        }
+    const BUTTON_OPEN = pgs(MODAL).querySelector("modal-button");
+    const DIALOG = existingDialog || MODAL.querySelector("dialog");
+    if (!BUTTON_OPEN || !DIALOG) return;
+    const eventController = new AbortController();
+    const { signal } = eventController;
+    let historyObserver = null;
+    let historyTimeout = null;
 
-        //+ FN OPEN 
-        function openModal(e) {
-            e?.stopImmediatePropagation();
-            if (DIALOG.open) {
-                closeModal(e);
-                return;
-            }
-
-            if (!DIALOG.open) document.querySelectorAll("dialog[open]").forEach((dlg) => dlg.close());
-            statusModal(true);
-            topLevel ? DIALOG.showModal() : DIALOG.show();
-            // modalCustomEvents('modal:open', { event: e });
-            MODAL.dispatchEvent(new CustomEvent('modal:open'));
-            DIALOG.dispatchEvent(new CustomEvent('modal:open'));
-        }
+    //== SELECTOR
+    const DOMButtonClose = '<button pgs="buttonClose modal-close" type="button" tabindex="0" aria-label="Chiudi"><i class="fa-solid fa-close"></i></button>';
+    const modalContentHeader = pgs(DIALOG).querySelector("modal-dialog-content-header");
 
-        //+ FN CLOSE 
-        function closeModal(e) {
-            e?.stopImmediatePropagation()
-            statusModal(false);
-            DIALOG.close();
-            // modalCustomEvents('modal:close', { event: e });
-            MODAL.dispatchEvent(new CustomEvent('modal:close'));
-            DIALOG.dispatchEvent(new CustomEvent('modal:close'));
-        }
 
-        function forceOpen(e) {
-            if (!DIALOG.open) openModal(e);
-        }
+    //== OPTION ATTRIBUTES MODAL
+    const disableBackdropClose = pgs(MODAL).option.contains("disableBackdropClose");
+    const data_history = pgs(MODAL).option.contains("history");
+    const data_container = pgs(MODAL).option.getValueBrackets("containerID");
+    const data_containerPGS = pgs(MODAL).option.getValueBrackets("containerPGS");
 
-        function forceClose(e) {
-            if (DIALOG.open) closeModal(e);
-        }
+    //== OPTION ATTRIBUTES DIALOG
+    const topLevel = pgs(DIALOG).option.contains("topLevel");
 
-        //+ fn OPEN ON HISTORY
-        function openModalOnHistory() {
-            const params = new URLSearchParams(window.location.search);
-            if (params.get('modal') !== BUTTON_OPEN.id) return;
-            document.getElementById(BUTTON_OPEN.id)?.scrollIntoView({ behavior: 'smooth' });
-            openModal();
-        }
+
+    //== BUTTON CLOSE
+    if (!pgs(DIALOG).querySelector("modal-close") && !pgs(MODAL).querySelector("modal-close")) {
+        if (modalContentHeader) modalContentHeader.insertAdjacentHTML("beforeend", DOMButtonClose);
+        else DIALOG.insertAdjacentHTML("beforeend", DOMButtonClose);
+    }
+    const BUTTON_CLOSE = pgs(DIALOG).querySelector("modal-close") || pgs(MODAL).querySelector("modal-close");
 
 
-        //= OPEN 
-        BUTTON_OPEN.addEventListener("click", (e) => openModal(e));
-        BUTTON_OPEN.addEventListener("keypress", (e) => !DIALOG.open && (e.key === "Enter" || e.key === " ") && openModal(e));
-        
-        //= CLOSE 
-        DIALOG.addEventListener("close", () => statusModal(false));
-        DIALOG.addEventListener("click", e => { if (e.target == DIALOG && !disableBackdropClose) closeModal(e) });
-        BUTTON_CLOSE?.addEventListener("click", e => closeModal(e));
-        
-        //= UPDATE HISTORY
-        if (data_history && BUTTON_OPEN.id) {
-            setTimeout(openModalOnHistory, 1);
-
-            //== Aggiorna URL quando cambia l'attributo "open" del dialog
-            const obs = new MutationObserver(() => {
-                let isOpen = DIALOG.hasAttribute("open");
-                try {
-                    const url = new URL(window.location.href);
-                    const params = new URLSearchParams(url.search);
-                    isOpen ? params.set('modal', BUTTON_OPEN.id) : params.delete('modal');
-                    url.search = params.toString() ? `?${params.toString()}` : "";
-                    window.history.pushState({ modal: BUTTON_OPEN.id, open: isOpen }, "", url);
-                } catch (_) { }
-            });
-            obs.observe(DIALOG, { attributes: true, attributeFilter: ["open"] });
-
-            //== Gestisce back/forward del browser per aprire/chiudere il dialog coerentemente
-            window.addEventListener("popstate", () => {
-                try {
-                    const params = new URLSearchParams(window.location.search);
-                    const shouldOpen = params.get('modal') === BUTTON_OPEN.id;
-                    if (shouldOpen && !DIALOG.open) DIALOG.showModal();
-                    if (!shouldOpen && DIALOG.open) closeModal()
-                } catch (_) { }
-            });
+    //== SET
+    pgs(DIALOG).add("dialog modal-dialog");
+
+    //== BUTTON OPEN
+    BUTTON_OPEN.setAttribute("role", "button");
+    BUTTON_OPEN.setAttribute("aria-label", "apri modale");
+
+
+    //== POSITION
+    if (topLevel && !MODAL.contains(DIALOG)) MODAL.append(DIALOG);
+    else if (!topLevel) {
+        if (data_container) document.querySelector("#" + data_container)?.append(DIALOG);
+        else if (data_containerPGS) pgs(document).querySelector(data_containerPGS)?.append(DIALOG);
+        else document.body.append(DIALOG);
+    }
+
+
+    //+ FN STATUS
+    function statusModal(status = true) {
+        BUTTON_OPEN?.setAttribute("aria-expanded", status);
+        DIALOG?.setAttribute("aria-expanded", status);
+    }
+
+    //+ FN OPEN
+    function openModal(e) {
+        e?.stopImmediatePropagation();
+        if (DIALOG.open) {
+            closeModal(e);
+            return;
         }
 
-        API.set(MODAL, {
-            element: MODAL,
-            button: BUTTON_OPEN,
-            dialog: DIALOG,
-            closeButton: BUTTON_CLOSE,
-            open: forceOpen,
-            close: forceClose,
-            toggle: openModal,
-            refresh: () => {
-                PGS_modal_init(selector);
-                return API.get(MODAL);
-            },
-            isOpen: () => DIALOG.open,
+        if (!DIALOG.open) document.querySelectorAll("dialog[open]").forEach((dlg) => dlg.close());
+        statusModal(true);
+        topLevel ? DIALOG.showModal() : DIALOG.show();
+        // modalCustomEvents('modal:open', { event: e });
+        MODAL.dispatchEvent(new CustomEvent('modal:open'));
+        DIALOG.dispatchEvent(new CustomEvent('modal:open'));
+    }
+
+    //+ FN CLOSE
+    function closeModal(e) {
+        e?.stopImmediatePropagation()
+        statusModal(false);
+        DIALOG.close();
+        // modalCustomEvents('modal:close', { event: e });
+        MODAL.dispatchEvent(new CustomEvent('modal:close'));
+        DIALOG.dispatchEvent(new CustomEvent('modal:close'));
+    }
+
+    function forceOpen(e) {
+        if (!DIALOG.open) openModal(e);
+    }
+
+    function forceClose(e) {
+        if (DIALOG.open) closeModal(e);
+    }
+
+    //+ fn OPEN ON HISTORY
+    function openModalOnHistory() {
+        const params = new URLSearchParams(window.location.search);
+        if (params.get('modal') !== BUTTON_OPEN.id) return;
+        document.getElementById(BUTTON_OPEN.id)?.scrollIntoView({ behavior: 'smooth' });
+        openModal();
+    }
+
+
+    //= OPEN
+    BUTTON_OPEN.addEventListener("click", (e) => openModal(e), { signal });
+    BUTTON_OPEN.addEventListener("keypress", (e) => !DIALOG.open && (e.key === "Enter" || e.key === " ") && openModal(e), { signal });
+
+    //= CLOSE
+    DIALOG.addEventListener("close", () => statusModal(false), { signal });
+    DIALOG.addEventListener("click", e => { if (e.target == DIALOG && !disableBackdropClose) closeModal(e) }, { signal });
+    BUTTON_CLOSE?.addEventListener("click", e => closeModal(e), { signal });
+
+    //= UPDATE HISTORY
+    if (data_history && BUTTON_OPEN.id) {
+        historyTimeout = window.setTimeout(openModalOnHistory, 1);
+
+        //== Aggiorna URL quando cambia l'attributo "open" del dialog
+        historyObserver = new MutationObserver(() => {
+            let isOpen = DIALOG.hasAttribute("open");
+            try {
+                const url = new URL(window.location.href);
+                const params = new URLSearchParams(url.search);
+                isOpen ? params.set('modal', BUTTON_OPEN.id) : params.delete('modal');
+                url.search = params.toString() ? `?${params.toString()}` : "";
+                window.history.pushState({ modal: BUTTON_OPEN.id, open: isOpen }, "", url);
+            } catch (_) { }
         });
+        historyObserver.observe(DIALOG, { attributes: true, attributeFilter: ["open"] });
+
+        //== Gestisce back/forward del browser per aprire/chiudere il dialog coerentemente
+        window.addEventListener("popstate", () => {
+            try {
+                const params = new URLSearchParams(window.location.search);
+                const shouldOpen = params.get('modal') === BUTTON_OPEN.id;
+                if (shouldOpen && !DIALOG.open) DIALOG.showModal();
+                if (!shouldOpen && DIALOG.open) closeModal()
+            } catch (_) { }
+        }, { signal });
+    }
+
+    function destroy() {
+        eventController.abort();
+        historyObserver?.disconnect();
+        if (historyTimeout !== null) window.clearTimeout(historyTimeout);
+        API.delete(MODAL);
+    }
+
+    API.set(MODAL, {
+        element: MODAL,
+        button: BUTTON_OPEN,
+        dialog: DIALOG,
+        closeButton: BUTTON_CLOSE,
+        open: forceOpen,
+        close: forceClose,
+        toggle: openModal,
+        refresh: () => {
+            const nextDialog = MODAL.querySelector("dialog") || DIALOG;
+            destroy();
+            initializeModal(MODAL, nextDialog);
+            return API.get(MODAL);
+        },
+        isOpen: () => DIALOG.open,
     });
 }
 
+function PGS_modal_init(root = document) {
+    getModals(root).forEach(MODAL => initializeModal(MODAL));
+}
+
 //# INIT PGS_modal
 PGS_modal_init()
 
 //# API
-export function PGS_modal_api(selector) {
-    return API.get(selector);
+function PGS_modal_api(element) {
+    return API.get(element);
 }
 
 export const PGS_modal = {

package/assets/javascript/components/_notifications.js

@@ -24,10 +24,12 @@ const fn_notification = {
     },
 
     _getData(root) {
+        const rawNotification = pgs(root).option.getValueBrackets("notification") || "{}";
+
         try {
-            return JSON.parse(root.dataset.notification || "{}");
+            return JSON.parse(rawNotification);
         } catch (error) {
-            console.warn("PGS notification: dati non validi", error);
+            console.warn("PGS notification: configurazione JSON non valida", error);
             return {};
         }
     },
@@ -46,13 +48,21 @@ const fn_notification = {
         `;
     },
 
-    initNotification(type, containerToken, icon, text, timeout, methodDelete = "replace", link = null) {
-        let containerNotification = pgs(document).querySelector(containerToken);
+    _getContainer(containerType) {
+        return Array.from(pgs(document).querySelectorAll("notification")).find(container => {
+            const isToast = pgs(container).option.contains("toast");
+            return containerType === "toast" ? isToast : !isToast;
+        });
+    },
+
+    initNotification(type, containerType, icon, text, timeout, methodDelete = "replace", link = null) {
+        let containerNotification = this._getContainer(containerType);
 
         //== Create Container
         if (!containerNotification) {
             const newContainer = document.createElement("div");
-            pgs(newContainer).add(containerToken);
+            pgs(newContainer).add("notification");
+            if (containerType === "toast") pgs(newContainer).option.add("toast");
             newContainer.setAttribute("aria-live", "polite");
             newContainer.setAttribute("aria-relevant", "additions");
             document.body.appendChild(newContainer);
@@ -98,8 +108,8 @@ const fn_notification = {
         });
     },
 
-    deleteAll(containerToken) {
-        let containerNotification = pgs(document).querySelector(containerToken);
+    deleteAll(containerType) {
+        let containerNotification = this._getContainer(containerType);
         if (containerNotification) containerNotification.innerHTML = "";
     },
 
@@ -133,8 +143,8 @@ const fn_notification = {
     }
 };
 
-//# EXPORT 
-export function PGS_notificationTrigger_init(root = document) {
+//# TRIGGER
+function PGS_notificationTrigger_init(root = document) {
     return fn_notification.trigger(root);
 }
 

package/assets/javascript/components/_search.js

@@ -5,7 +5,7 @@ let searchId = 0;
 const DEFAULT_OPTIONS = {
     minLength: 2,
     debounce: 200,
-    limit: 8,
+    limit: 6,
     submitOnSelect: false,
     searchOnFocus: true,
     source: null,
@@ -381,7 +381,7 @@ document.addEventListener("pointerdown", event => {
 
 PGS_search_init();
 
-export function PGS_search_api(selector) {
+function PGS_search_api(selector) {
     return API.get(selector);
 }