mypgs 1.5.1 → 2.0.0

package/AGENTS.md

@@ -8,7 +8,7 @@ This guide is for any AI/Codex agent that initializes or modifies a project base
 
 - HTML `pgs` attributes as the contract between markup, SCSS, and JavaScript;
 - SCSS sources with base styles, layouts, components, patterns, CSS variables, and mixins;
-- JavaScript modules for recurring behaviors such as accordions, dropdowns, menus, modals, slides, steps, step tabs, notifications, header, cookie consent, and dark mode;
+- JavaScript modules for recurring behaviors such as accordions, dropdowns, menus, modals, search suggestions, slides, steps, step tabs, notifications, header, cookie consent, and dark mode;
 - example HTML templates in `templates/`;
 - compiled assets in `dist/`.
 
@@ -26,7 +26,7 @@ Write custom code only when the pattern does not exist, or when you are adding a
 ## 2. General Usage Rules
 
 - Use `mypgs` as the first choice for layouts, components, helpers, variables, utilities, and available patterns.
-- Do not recreate existing components from scratch: buttons, forms, dropdowns, modals, menus, slides, accordions, steps, stepTabs, notifications, tooltips, tables, searchbars, logos, headers, footers, and cookie consent.
+- Do not recreate existing components from scratch: buttons, forms, dropdowns, modals, menus, slides, accordions, steps, stepTabs, notifications, tooltips, tables, search, logos, headers, footers, and cookie consent.
 - Do not duplicate logic already handled by the `mypgs` JS modules, such as modal open/close, accordion state, Popover API dropdowns, step tabs, notifications, or form validation.
 - Keep `pgs` tokens in markup, SCSS selectors, and JS queries consistent.
 - Prefer composing `pgs` tokens over adding new CSS classes.
@@ -52,6 +52,7 @@ Files analyzed:
 - `assets/javascript/components/_steps.js`
 - `assets/javascript/components/_stepTabs.js`
 - `assets/javascript/components/_notifications.js`
+- `assets/javascript/components/_search.js`
 - `assets/javascript/functions/_formValidate.js`
 - `assets/javascript/functions/_scrollY.js`
 - `assets/javascript/patterns/_header.js`
@@ -70,10 +71,11 @@ 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`.
+- La ricerca componibile usa esclusivamente `pgs="search"` come root grafico e comportamentale e il figlio opzionale `pgs="search-suggestions"`. La sorgente dati si configura tramite `pgs.search.api(element)?.configure({ source })` e deve restare indipendente dal backend.
 - Configurable options use `pgs-option`, with simple tokens or values inside square brackets. Prefer copying the current option syntax from the relevant template rather than duplicating examples in this guide.
 
 - Naming is mostly camelCase for compound tokens (`menuHorizontal`, `buttonStrong`, `flexColumnElements`) and kebab-like for component sub-elements (`accordion-button`, `modal-dialog-content`, `cookieConsent-actionAccept`).
@@ -186,6 +188,7 @@ Recommended direct access:
 ```js
 pgs.notification.toast.success("Saved");
 pgs.modal.api(modalEl)?.open();
+pgs.search.api(searchEl)?.setSource(async ({ query, signal }) => []);
 ```
 
 `assets/javascript/_imports.js` registers modules with `pgs.registerModules`:
@@ -224,9 +227,9 @@ Use the templates as the single source of truth for component and layout markup.
 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/searchbar.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`
+- 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

@@ -2,7 +2,7 @@
 
 `mypgs` e' una libreria frontend condivisa per costruire interfacce coerenti tramite attributi `pgs`, SCSS sorgenti, componenti UI e comportamenti JavaScript riutilizzabili.
 
-La libreria nasce come base di design system: layout, spacing, colori, bottoni, form, menu, modali, dropdown, slides, notifiche e pattern ricorrenti vengono definiti una volta sola e riusati nei progetti.
+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.
 
 ## Cosa contiene
 

package/assets/javascript/_imports.js

@@ -1,10 +1,12 @@
 import { pgs } from "./_pgs.js";
 
+import { PGS_svg } from "./base/_svg.js";
 import { PGS_accordion } from "./components/_accordion.js";
 import { PGS_dropdown } from "./components/_dropdown.js";
 import { PGS_menu } from "./components/_menu.js";
 import { PGS_modal } from "./components/_modals.js";
 import { PGS_notification } from "./components/_notifications.js";
+import { PGS_search } from "./components/_search.js";
 import { PGS_slides } from "./components/_slides.js";
 import { PGS_stepTabs } from "./components/_stepTabs.js";
 import { PGS_steps } from "./components/_steps.js";
@@ -13,11 +15,13 @@ import { PGS_formValidate } from "./functions/_formValidate.js";
 import { PGS_scrollHorizontal } from "./functions/_scrollY.js";
 
 pgs.registerModules({
+    svg: PGS_svg,
     accordion: PGS_accordion,
     dropdown: PGS_dropdown,
     menu: PGS_menu,
     modal: PGS_modal,
     notification: PGS_notification,
+    search: PGS_search,
     slides: PGS_slides,
     stepTabs: PGS_stepTabs,
     steps: PGS_steps,

package/assets/javascript/_pgs.js

@@ -185,10 +185,56 @@ export function pgs(root) {
     function createOption(attribute) {
         if (!canAttr) return undefined;
 
+        const read = () => (root.getAttribute(attribute) || "").match(/[^\s[\]]+(?:\[[^\]]*\])?/g) || [];
+        const write = values => root.setAttribute(attribute, values.join(" "));
+        const getKey = value => String(value).trim().match(/^[^\s[\]]+/)?.[0] || "";
+        const getValues = values => values
+            .flat()
+            .flatMap(value => String(value).match(/[^\s[\]]+(?:\[[^\]]*\])?/g) || [])
+            .filter(Boolean);
+
         function api() {
             return api;
         }
 
+        api.add = function (...values) {
+            const current = read();
+
+            getValues(values).forEach(value => {
+                if (!current.includes(value)) current.push(value);
+            });
+
+            write(current);
+            return api;
+        };
+
+        api.remove = function (...values) {
+            const keys = getValues(values).map(getKey).filter(Boolean);
+            write(read().filter(value => !keys.includes(getKey(value))));
+            return api;
+        };
+
+        api.toggle = function (value, force) {
+            const key = getKey(value);
+            if (!key) return false;
+
+            const exists = api.contains(key);
+
+            if (force !== undefined) {
+                if (force && !exists) api.add(value);
+                if (!force && exists) api.remove(key);
+                return !!force;
+            }
+
+            if (exists) {
+                api.remove(key);
+                return false;
+            }
+
+            api.add(value);
+            return true;
+        };
+
         api.contains = function (key) {
             const source = root.getAttribute(attribute) || "";
             const safeKey = String(key).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -208,6 +254,18 @@ export function pgs(root) {
             return match ? match[1] : undefined;
         };
 
+        api.setValueBrackets = function (key, value = "") {
+            const optionKey = getKey(key);
+            if (!optionKey) return api;
+
+            const option = `${optionKey}[${String(value).trim()}]`;
+            const options = read().filter(item => getKey(item) !== optionKey);
+
+            options.push(option);
+            write(options);
+            return api;
+        };
+
         Object.defineProperty(api, "value", {
             get() { return root.getAttribute(attribute); },
             set(v) { root.setAttribute(attribute, v); }

package/assets/javascript/base/_darkmode.js

@@ -1,121 +1,43 @@
 //# DARKMODE
 
+const EVENT_SVG_CHANGE_COLOR = "pgs:svg:changeColor";
 
-//= CHANGE COLOR SVG & LOTTIE
-//+ SEARCH COLOR 
-function searchColor(type = "svg") {
-    const ROOT = getComputedStyle(document.documentElement);
-    const colors = []
-    for (let I = 0; I < 20; I++) {
-        const color = ROOT.getPropertyValue('--' + type + '-color-' + I).toLocaleLowerCase().split("&");
-        if (!color[0] == "" && !color[1] == "") {
-            let lightDark = [color[0], color[1]]
-            colors.push(lightDark)
-        }
-    }
-    return colors;
-}
-const colors_svg_lottie = [searchColor("svg"), searchColor("lottie")];
-
-
-//+ change COLORS
-function darkmodeColorSVG() {
-    function changecolor(svgDoc, type = "svg") {
-        let isDarkMode = (document.documentElement.getAttribute("data-darkmode") === "true") ? false : true;
-
-        svgDoc.querySelectorAll('[fill], [stroke]').forEach(fillStroke => {
-
-            for (const colors of colors_svg_lottie) {
-                for (const color of colors) {
-                    let OLD = (color[0] || '').replace(/\s/g, '');
-                    let NEW = (color[1] || '').replace(/\s/g, '');
-
-                    ["fill", "stroke"].forEach(attr => {
-                        const current = fillStroke.getAttribute(attr);
-
-                        fillStroke.style.transition = "fill 0.5s ease, stroke 0.5s ease";
-
-                        if (!isDarkMode) {
-                            if (current == OLD) fillStroke.setAttribute(attr, NEW)
-                        } else {
-                            if (current == NEW) fillStroke.setAttribute(attr, OLD)
-                        }
-                    });
-                }
-            }
-        });
-    }
-
-    //== OBJECTS
-    const objects = document.querySelectorAll('object[type="image/svg+xml"]');
-    objects.forEach(obj => {
-
-        //=== ALL FILL / STROKE
-        obj.addEventListener("load", () => {
-            const svgDoc = obj.contentDocument;
-            if (svgDoc) changecolor(svgDoc, "svg")
-        });
-
-        //=== In caso l'object sia già caricato
-        if (obj.contentDocument) {
-            const event = new Event("load");
-            obj.dispatchEvent(event);
-        }
-    });
-
-    //== LOTTIE
-    const lottiePlayers = document.querySelectorAll('lottie-player');
-    lottiePlayers.forEach(lottiePlayer => {
-
-        //=== ALL FILL / STROKE
-        lottiePlayer.addEventListener("load", () => {
-            const svg = lottiePlayer.shadowRoot.querySelector('svg');
-            if (svg) changecolor(svg, "lottie")
-        });
+//+ CHANGE ICON
+function changeIcon(selector, isDarkMode) {
+    selector.forEach(button => {
+        const ICON = button.querySelector("i");
+        if (!ICON) return;
 
-        //=== In caso lottie sia già caricato
-        if (lottiePlayer.shadowRoot) {
-            const event = new Event("load");
-            lottiePlayer.dispatchEvent(event);
-        }
+        ICON.classList.toggle("fa-moon", !isDarkMode);
+        ICON.classList.toggle("fa-sun", isDarkMode);
     });
 }
 
+//+ SET STATUS
+function setDarkmodeStatus(toggle = false, button) {
+    let isDarkMode = localStorage.getItem("screenIsDarkMode") === "true";
 
+    if (toggle) {
+        isDarkMode = !isDarkMode;
+        localStorage.setItem("screenIsDarkMode", isDarkMode);
+    }
 
-//= BUTTON DARKMODE 
-//+ CHANGE ICON AND SVG 
-let toggleDarkmode = pgs(document).querySelectorAll("toggleDarkmode");
-if (localStorage.getItem("screenIsDarkMode") === "true") {
-    document.body.classList.add("darkmode");
-    document.querySelector(":root").setAttribute("data-darkmode", "true");
-    document.body.setAttribute("data-darkmode", "true");
-}
+    // SET
+    pgs(document.documentElement).state.toggle("darkmode", isDarkMode);
+    pgs(document.body).state.toggle("darkmode", isDarkMode);
+    // END SET
 
-function change(selector, isDarkMode) {
-    selector.forEach(button => {
-        const ICON = button.querySelector("i");
-        if (!ICON) return;
-        ICON.classList.toggle("fa-moon", !isDarkMode);
-        ICON.classList.toggle("fa-sun", isDarkMode);
-    });
-    darkmodeColorSVG();
+    changeIcon(button, isDarkMode);
+    document.dispatchEvent(new CustomEvent(EVENT_SVG_CHANGE_COLOR, { detail: { isDarkMode } }));
 }
 
-toggleDarkmode.forEach(button => {
 
-    //== EXECUTE IMMEDIATELY
-    let isDarkMode = document.documentElement.getAttribute("data-darkmode") === "true";
-    change(toggleDarkmode, isDarkMode);
 
-    //== CLICK BUTTON 
-    button.addEventListener("click", () => {
-        let isDarkMode = (document.documentElement.getAttribute("data-darkmode") === "true") ? false : true;
-        localStorage.setItem("screenIsDarkMode", isDarkMode);
+//= INIT
+const toggleDarkmode = pgs(document).querySelectorAll("toggleDarkmode");
+setDarkmodeStatus(false, toggleDarkmode);
 
-        document.body.classList.toggle("darkmode", isDarkMode);
-        document.body.setAttribute("data-darkmode", isDarkMode);
-        document.querySelector(":root").setAttribute("data-darkmode", isDarkMode);
-        change(toggleDarkmode, isDarkMode);
-    });
+//= BUTTON DARKMODE
+toggleDarkmode.forEach(button => {
+    button.addEventListener("click", () => setDarkmodeStatus(true, toggleDarkmode));
 });

package/assets/javascript/base/_svg.js

@@ -0,0 +1,103 @@
+//# SVG & LOTTIE COLORS
+
+const svgColors = {
+    eventChangeColor: "pgs:svg:changeColor",
+    watchedObjects: new WeakSet(),
+    watchedLotties: new WeakSet(),
+
+    _normalizeColor: (color = "") => {
+        return color.replace(/\s/g, "").toLocaleLowerCase();
+    },
+
+    _getCurrentDarkmode: () => {
+        return pgs(document.documentElement).state.contains("darkmode");
+    },
+
+    searchColor(type = "svg") {
+        const ROOT = getComputedStyle(document.documentElement);
+        const colors = [];
+
+        for (let I = 0; I < 20; I++) {
+            const color = ROOT.getPropertyValue("--" + type + "-color-" + I).toLocaleLowerCase().split("&").map(value => value.trim());
+            if (color[0] && color[1]) colors.push([color[0], color[1]]);
+        }
+
+        return colors;
+    },
+
+    _changeColor(svgDoc, isDarkMode, colors) {
+        if (!svgDoc) return;
+
+        svgDoc.querySelectorAll("[fill], [stroke]").forEach(fillStroke => {
+            for (const color of colors) {
+                const OLD = svgColors._normalizeColor(color[0]);
+                const NEW = svgColors._normalizeColor(color[1]);
+
+                ["fill", "stroke"].forEach(attr => {
+                    const current = svgColors._normalizeColor(fillStroke.getAttribute(attr) || "");
+                    if (!current) return;
+
+                    fillStroke.style.transition = "fill 0.5s ease, stroke 0.5s ease";
+
+                    if (isDarkMode && current === OLD) fillStroke.setAttribute(attr, NEW);
+                    if (!isDarkMode && current === NEW) fillStroke.setAttribute(attr, OLD);
+                });
+            }
+        });
+    },
+
+    _getLottieSvg(lottiePlayer) {
+        return lottiePlayer.shadowRoot?.querySelector("svg") || null;
+    },
+
+    init() {
+        document.addEventListener(svgColors.eventChangeColor, event => {
+            svgColors.applyColorsSVG(event.detail?.isDarkMode ?? svgColors._getCurrentDarkmode());
+            svgColors.applyColorsLottie(event.detail?.isDarkMode ?? svgColors._getCurrentDarkmode());
+        });
+
+        document.addEventListener("DOMContentLoaded", () => {
+            svgColors.applyColorsSVG();
+            svgColors.applyColorsLottie();
+        });
+    },
+
+    applyColorsSVG(isDarkMode = svgColors._getCurrentDarkmode()) {
+        const colorsSvg = svgColors.searchColor("svg");
+
+        if (!pgs(document).querySelector("svgChangeColor")) return;
+
+        document.querySelectorAll('object[type="image/svg+xml"]').forEach(obj => {
+            if (!svgColors.watchedObjects.has(obj)) {
+                obj.addEventListener("load", () => svgColors._changeColor(obj.contentDocument, svgColors._getCurrentDarkmode(), svgColors.searchColor("svg")));
+                svgColors.watchedObjects.add(obj);
+            }
+
+            if (obj.contentDocument) svgColors._changeColor(obj.contentDocument, isDarkMode, colorsSvg);
+        });
+
+    },
+
+    applyColorsLottie(isDarkMode = svgColors._getCurrentDarkmode()) {
+        const colorsLottie = svgColors.searchColor("svg");
+
+        if (!pgs(document).querySelector("lottieChangeColor")) return;
+
+        document.querySelectorAll("lottie-player").forEach(lottiePlayer => {
+            if (!svgColors.watchedLotties.has(lottiePlayer)) {
+                lottiePlayer.addEventListener("load", () => svgColors._changeColor(svgColors._getLottieSvg(lottiePlayer), svgColors._getCurrentDarkmode(), svgColors.searchColor("svg")));
+                svgColors.watchedLotties.add(lottiePlayer);
+            }
+
+            if (lottiePlayer.shadowRoot) svgColors._changeColor(svgColors._getLottieSvg(lottiePlayer), isDarkMode, colorsLottie);
+        });
+    },
+};
+
+svgColors.init();
+
+export const PGS_svg = {
+    eventChangeColor: svgColors.eventChangeColor,
+    applyColorsSVG: isDarkMode => svgColors.applyColorsSVG(isDarkMode),
+    applyColorsLottie: isDarkMode => svgColors.applyColorsLottie(isDarkMode),
+};

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/_menu.js

@@ -20,6 +20,7 @@ function PGS_menu_init(root = document) {
                 li.querySelector("a").insertAdjacentElement("afterend", button);
 
                 pgs(li).add("dropdown")
+                pgs(li).option.setValueBrackets("position", "bottom right")
                 pgs(button).add("dropdown-button")
                 pgs(button).add("buttonNohover")
                 pgs(ul).add("dropdown-content")
@@ -30,9 +31,6 @@ function PGS_menu_init(root = document) {
         API.set(MENU, {
             element: MENU,
             type: "horizontal",
-            // items: () => Array.from(MENU.querySelectorAll('nav > ul > li')),
-            // submenus: () => Array.from(MENU.querySelectorAll('.menu-item-has-children > ul')),
-            // dropdowns: () => Array.from(MENU.querySelectorAll('.menu-item-has-children')).map(PGS_dropdown_api).filter(Boolean),
             refresh: () => {
                 PGS_menu_init(MENU.parentNode || document);
                 return API.get(MENU);