mypgs 1.5.0 → 1.6.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`
@@ -74,6 +75,7 @@ Patterns found:
 - 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,7 +227,7 @@ 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`
 

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
 
@@ -12,40 +12,35 @@ La libreria nasce come base di design system: layout, spacing, colori, bottoni,
 - `dist/css/`: CSS compilato.
 - `dist/javascript/`: bundle JavaScript compilato.
 - `dist/index.d.ts`: dichiarazioni TypeScript esportate dal pacchetto.
-- `AI_GUIDELINES.md`: guida operativa per AI/Codex.
-- `AI_GUIDELINES_EN.md`: versione inglese della guida.
+- `AGENTS.md`: guida operativa per AI.
 
 ## Installazione
 
-Da registry npm:
+Da registry **npm**:
 
 ```bash
 npm install mypgs
 ```
 
-## Uso rapido
-
-Importa JavaScript e CSS compilato nell'entrypoint del progetto:
+### JavaScript
 
 ```js
 import "mypgs";
-import "mypgs/style.css";
 ```
 
 Se ti serve accedere direttamente all'helper:
 
 ```js
 import { pgs } from "mypgs";
-import "mypgs/style.css";
 ```
 
-In progetti React/TSX con Vite, abilita i tipi JSX e il plugin che converte `pgsHtml` in `pgs`:
+**React/TSX con Vite:**
 
-```ts
-import "mypgs/react";
-```
+Configura il plugin che converte `pgsHtml` in `pgs`:
 
 ```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
 import react from "@vitejs/plugin-react";
 import pgsVite from "mypgs/vite-plugin-pgs";
 
@@ -54,19 +49,7 @@ export default {
 };
 ```
 
-Markup minimo consigliato:
-
-```html
-<html lang="it" pgs="htmlBase initP">
-  <body pgs="bodyBase bodyImg bodyText bodyHeading">
-    <main pgs="main"></main>
-  </body>
-</html>
-```
-
-`initP` e' importante: molti layout, componenti e pattern SCSS sono definiti sotto `[pgs~=initP]`.
-
-## Uso SCSS sorgente
+### SCSS
 
 Se il progetto vuole compilare un CSS unico, importa gli SCSS sorgenti:
 
@@ -82,356 +65,22 @@ Se servono solo i mixin:
 @use "../../node_modules/mypgs/assets/scss/mixin/mixin.scss" as * ;
 ```
 
-La libreria espone molte custom properties da preferire agli hardcode, per esempio:
-
-```scss
-:root {
-  --color-primary: #5c7d6f;
-  --padding: 30px;
-  --gap-texts: 1rem;
-  --gap-elements: 4rem;
-  --border-radius: 4.5rem;
-  --border-radius-input: 2.25rem;
-}
-```
-
-Override consigliato:
+### Markup
 
-```scss
-#danger-action {
-  --button-background: var(--color-error);
-  --button-color: var(--color-whiteFixed);
-}
-```
-
-Evita di riscrivere da zero padding, gap, border-radius o colori se esiste gia' una variabile o un token PGS adatto.
-
-## Il sistema `pgs`
-
-Il markup usa token separati da spazio dentro l'attributo `pgs`:
+`initP` e' importante: tutti i layout, componenti e pattern SCSS sono definiti sotto `[pgs~=initP]`.
 
 ```html
-<button pgs="button buttonStrong" type="button">Salva</button>
-<section pgs="section flexColumnElements"></section>
-```
-
-Gli stessi token collegano HTML, SCSS e JavaScript.
-
-### Helper JavaScript
-
-`pgs(root)` permette di cercare e modificare token PGS senza scrivere selettori manuali:
-
-```js
-const modal = pgs(document).querySelector("modal");
-
-pgs(modal).contains("modal");
-pgs(modal).add("custom-token");
-pgs(modal).remove("custom-token");
-pgs(modal).toggle("custom-token", true);
-```
-
-Stati runtime:
-
-```js
-pgs(modal).state.add("open");
-pgs(modal).state.toggle("open", false);
-pgs(modal).state.contains("open");
-```
-
-Opzioni:
-
-```js
-pgs(modal).option.contains("history");
-pgs(modal).option.getValueBrackets("containerID");
-```
-
-Esempio markup con opzioni:
-
-```html
-<div pgs="modal" pgs-option="containerID[modal-container]"></div>
-<div pgs="slides" pgs-option="singleScroll shadowDesktop"></div>
-```
-
-## JavaScript inizializzato automaticamente
-
-Importando `mypgs`, l'entrypoint inizializza:
-
-- helper globale `pgs`
-- dark mode
-- gestione object SVG
-- accordion
-- dropdown
-- menu
-- modali
-- slides
-- steps
-- step tabs
-- notifiche
-- header
-- cookie consent
-
-I componenti inizializzati usano `WeakMap` interne per esporre API di istanza.
-
-## API dei moduli
-
-I moduli principali sono registrati in `assets/javascript/_imports.js` in due modi.
-
-### Registro diretto
-
-Serve per usare i moduli direttamente da `pgs`:
-
-```js
-pgs.registerModules({
-  accordion: PGS_accordion,
-  dropdown: PGS_dropdown,
-  menu: PGS_menu,
-  modal: PGS_modal,
-  notification: PGS_notification,
-  slides: PGS_slides,
-  stepTabs: PGS_stepTabs,
-  steps: PGS_steps,
-  formValidate: PGS_formValidate,
-  scrollHorizontal: PGS_scrollHorizontal,
-});
-```
-
-Uso consigliato:
-
-```js
-pgs.notification.toast.success("Salvato");
-pgs.modal.api(modalEl)?.open();
-pgs.dropdown.api(dropdownEl)?.close();
-pgs.slides.api(slidesEl)?.next();
-```
-
-Shortcut disponibili dopo `import "mypgs"`:
-
-- `pgs.accordion`
-- `pgs.dropdown`
-- `pgs.menu`
-- `pgs.modal`
-- `pgs.notification`
-- `pgs.slides`
-- `pgs.stepTabs`
-- `pgs.steps`
-- `pgs.formValidate`
-- `pgs.scrollHorizontal`
-
-## Struttura dei moduli componente
-
-I componenti con istanze seguono questo schema:
-
-```js
-export const PGS_modal = {
-  init: PGS_modal_init,
-  api: PGS_modal_api
-};
-```
-
-- `PGS_name`: nome ufficiale del modulo per il registro legacy.
-- `init`: inizializza o reinizializza markup, utile dopo contenuti dinamici.
-- `api`: recupera l'API di una singola istanza gia' inizializzata.
-
-Esempio:
-
-```js
-pgs.modal.init();
-pgs.modal.init(container);
-pgs.modal.api(modalEl)?.open();
-```
-
-`PGS_notification` e' un caso diverso: funziona piu' come service/helper e espone `alert`, `toast` e `trigger`.
-
-## Componenti e markup
-
-I template completi sono in `templates/html/components/`, `templates/html/patterns/` e `templates/html/layout/`. Usa quei file come sorgente di riferimento prima di creare markup nuovo.
-
-## Componenti disponibili
-
-Layout e utility:
-
-- `main`
-- `section`
-- `sectionFull`
-- `sectionMax`
-- `sectionNoPadding`
-- `container`
-- `pageShell`
-- `aside`
-- `flexColumn`
-- `flexColumnTexts`
-- `flexColumnElements`
-- `flexColumnSections`
-- `flexRow`
-- `grid-*`
-- `gapTexts`
-- `gapElements`
-- `gapSections`
-- `card`
-- `boxtext`
-
-Componenti:
-
-- `button`
-- `buttonStrong`
-- `buttonIcon`
-- `buttonMini`
-- `buttonBig`
-- `buttonClose`
-- `form`
-- `input`
-- `textarea`
-- `select`
-- `toggle`
-- `checkbox`
-- `radio`
-- `dropdown`
-- `tooltip`
-- `modal`
-- `accordion`
-- `slides`
-- `steps`
-- `stepTabs`
-- `notification`
-- `toast`
-- `table`
-- `breadcrumb`
-- `searchbar`
-- `logo`
-- `menuHorizontal`
-- `menuVertical`
-- `menuFooter`
-
-Pattern:
-
-- `header`
-- `footer`
-- `cookieConsent`
-
-## Export npm
-
-Il pacchetto espone:
-
-```json
-{
-  ".": {
-    "types": "./dist/index.d.ts",
-    "import": "./assets/javascript/index.js",
-    "default": "./dist/javascript/index.js"
-  },
-  "./style.css": "./dist/css/index.css",
-  "./style.min.css": "./dist/css/index.min.css",
-  "./react": {
-    "types": "./react.d.ts",
-    "import": "./react.js",
-    "default": "./react.js"
-  },
-  "./vite-plugin-pgs": {
-    "types": "./plugins/vite-plugin-pgs.d.ts",
-    "import": "./plugins/vite-plugin-pgs.js",
-    "default": "./plugins/vite-plugin-pgs.js"
-  }
-}
-```
-
-Uso compilato:
-
-```js
-import "mypgs";
-import "mypgs/style.css";
-```
-
-Uso sorgente SCSS:
-
-```scss
-@use "sass:meta";
-@use "../../node_modules/mypgs/assets/scss/mixin/mixin.scss" as * ;
-@include meta.load-css("../../node_modules/mypgs/assets/scss/index.scss");
-```
-
-## Sviluppo
-
-Build una tantum:
-
-```bash
-npm run start
-```
-
-Build in watch mode:
-
-```bash
-npm run "start watch"
-```
-
-Creare un pacchetto locale:
-
-```bash
-npm pack
-```
-
-Flusso consigliato quando modifichi la libreria:
-
-1. modifica i sorgenti in `assets/`;
-2. aggiorna template o documentazione se cambia il modo d'uso;
-3. ricompila con `npm run start`;
-4. verifica `dist/`;
-5. crea il pacchetto con `npm pack`;
-6. installa il `.tgz` nel progetto che consuma la libreria.
-
-Nota: se la build Webpack fallisce, non modificare manualmente `dist/javascript` come sorgente primaria. Sistema la toolchain e rigenera gli asset compilati.
-
-## Aggiungere un nuovo modulo
-
-Esempio componente:
-
-```js
-export function PGS_myComponent_init(root = document) {
-  pgs(root).querySelectorAll("myComponent").forEach((element) => {
-    // init
-  });
-}
-
-export function PGS_myComponent_api(element) {
-  // return instance API
-}
-
-export const PGS_myComponent = {
-  PGS_name: "PGS_myComponent",
-  init: PGS_myComponent_init,
-  api: PGS_myComponent_api
-};
-```
-
-Registrazione in `assets/javascript/_imports.js`:
-
-```js
-import { PGS_myComponent } from "./components/_myComponent.js";
-
-pgs.registerImport({
-  PGS_myComponent,
-});
-
-pgs.registerModules({
-  myComponent: PGS_myComponent,
-});
-```
-
-Uso:
-
-```js
-pgs.myComponent.init();
-pgs.myComponent.api(element);
+<html lang="it" pgs="htmlBase initP">
+  <body pgs="bodyBase bodyImg bodyText bodyHeading">
+    <main pgs="main"></main>
+  </body>
+</html>
 ```
 
-## Convenzioni
+## Documentazione
 
-- 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 `AI_GUIDELINES.md` quando introduci pattern importanti.
+- [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)

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); }