mypgs 1.6.0 → 2.1.0

package/docs/helper-javascript.md

@@ -1,4 +1,4 @@
-# Helper JavaScript
+# JavaScript helper
 
 `pgs(root)` permette di cercare e modificare token PGS senza scrivere selettori manuali:
 
@@ -11,6 +11,21 @@ pgs(modal).remove("custom-token");
 pgs(modal).toggle("custom-token", true);
 ```
 
+## API dell'helper `pgs`
+
+Ricerca disponibile su `Document` ed `Element`:
+
+- `pgs(root).querySelector(token)`: restituisce il primo discendente che contiene il token `pgs` richiesto.
+- `pgs(root).querySelectorAll(token)`: restituisce tutti i discendenti corrispondenti; accetta anche un array o token separati da virgola.
+
+Manipulation available when `root` è un `Element`:
+
+- `pgs(element).add(...tokens)`: aggiunge token evitando duplicati e restituisce l'helper.
+- `pgs(element).remove(...tokens)`: rimuove i token indicati e restituisce l'helper.
+- `pgs(element).toggle(token, force)`: inverte o forza la presenza del token e restituisce lo stato risultante.
+- `pgs(element).contains(token)`: verifica la presenza esatta del token.
+- `pgs(element).value`: legge o sostituisce il valore completo dell'attributo `pgs`.
+
 Stati runtime:
 
 ```js
@@ -19,6 +34,12 @@ pgs(modal).state.toggle("open", false);
 pgs(modal).state.contains("open");
 ```
 
+- `state.add(...states)` oppure `state(...states)`: aggiunge uno o più stati.
+- `state.remove(...states)`: rimuove gli stati indicati.
+- `state.toggle(state, force)`: inverte o forza uno stato e restituisce il risultato.
+- `state.contains(state)`: verifica se lo stato è presente.
+- `state.value`: legge o sostituisce l'intero attributo `pgs-state`.
+
 Opzioni:
 
 ```js
@@ -26,14 +47,22 @@ pgs(modal).option.contains("history");
 pgs(modal).option.getValueBrackets("containerID");
 ```
 
-Esempio markup con opzioni:
+- `option.add(...options)`: aggiunge opzioni semplici o parametrizzate.
+- `option.remove(...keys)`: rimuove le opzioni usando la relativa chiave.
+- `option.toggle(option, force)`: inverte o forza un'opzione.
+- `option.contains(key)`: verifica la presenza di una chiave anche quando possiede un payload.
+- `option.getValueBrackets(key)`: restituisce il contenuto tra parentesi quadre oppure `undefined`.
+- `option.setValueBrackets(key, value)`: imposta o sostituisce una singola opzione parametrizzata.
+- `option.value`: legge o sostituisce l'intero attributo `pgs-option`.
+
+Example markup with options:
 
 ```html
 <div pgs="modal" pgs-option="containerID[modal-container]"></div>
 <div pgs="slides" pgs-option="singleScroll shadowDesktop"></div>
 ```
 
-## JavaScript inizializzato automaticamente
+## Automatically initialized JavaScript
 
 Importando `mypgs`, l'entrypoint inizializza:
 
@@ -64,6 +93,7 @@ Serve per usare i moduli direttamente da `pgs`:
 
 ```js
 pgs.registerModules({
+  svg: PGS_svg,
   accordion: PGS_accordion,
   dropdown: PGS_dropdown,
   menu: PGS_menu,
@@ -73,6 +103,7 @@ pgs.registerModules({
   slides: PGS_slides,
   stepTabs: PGS_stepTabs,
   steps: PGS_steps,
+  summary: PGS_summary,
   formValidate: PGS_formValidate,
   scrollHorizontal: PGS_scrollHorizontal,
 });
@@ -87,8 +118,9 @@ pgs.dropdown.api(dropdownEl)?.close();
 pgs.slides.api(slidesEl)?.next();
 ```
 
-Shortcut disponibili dopo `import "mypgs"`:
+Shortcuts available after `import "mypgs"`:
 
+- `pgs.svg`
 - `pgs.accordion`
 - `pgs.dropdown`
 - `pgs.menu`
@@ -98,10 +130,37 @@ Shortcut disponibili dopo `import "mypgs"`:
 - `pgs.slides`
 - `pgs.stepTabs`
 - `pgs.steps`
+- `pgs.summary`
 - `pgs.formValidate`
 - `pgs.scrollHorizontal`
 
-## Struttura dei moduli componente
+## Component API reference
+
+Le firme, i parametri e la funzione di ogni metodo sono generati dai commenti nei template:
+
+- [Accordion](components/accordion.md#api-javascript)
+- [Dropdown](components/dropdown.md#api-javascript)
+- [Form validation](components/form.md#api-javascript)
+- [Menu](components/menu.md#api-javascript)
+- [Modal](components/modal.md#api-javascript)
+- [Notification](components/notification.md#api-javascript)
+- [Search](components/search.md#api-javascript)
+- [Slides](components/slides.md#api-javascript)
+- [Step Tabs](components/stepTabs.md#api-javascript)
+- [Steps](components/steps.md#api-javascript)
+- [Summary](components/summary.md#api-javascript)
+- [Tooltip tramite Dropdown](components/tooltip.md#api-javascript)
+
+I componenti non elencati non espongono attualmente un'API JavaScript specifica.
+
+## Utility JavaScript pubbliche
+
+- `pgs.scrollHorizontal(element, speed)`: converte lo scroll verticale della rotella in scorrimento orizzontale quando il contenitore può ancora muoversi nella direzione richiesta e restituisce una funzione che rimuove il listener.
+- `pgs.svg.applyColorsSVG(isDarkMode)`: aggiorna i colori degli SVG caricati tramite `object` e marcati con `svgChangeColor`.
+- `pgs.svg.applyColorsLottie(isDarkMode)`: aggiorna i colori degli SVG interni ai player Lottie marcati con `lottieChangeColor`.
+- `pgs.svg.eventChangeColor`: contiene il nome dell'evento `pgs:svg:changeColor` ascoltato dal modulo SVG.
+
+## Component module structure
 
 I componenti con istanze seguono questo schema:
 
@@ -112,16 +171,22 @@ export const PGS_modal = {
 };
 ```
 
-- `PGS_name`: nome ufficiale del modulo per il registro legacy.
-- `init`: inizializza o reinizializza markup, utile dopo contenuti dinamici.
+Le funzioni `PGS_modal_init` e `PGS_modal_api` restano interne al modulo: l'unico export del file è `PGS_modal`. Lo stesso criterio vale per gli altri componenti.
+
+- `init`: inizializza o reinizializza il markup nel `Document` o `Element` ricevuto; senza argomenti usa `document`.
 - `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`.
+
+## Registro ed estensione
+
+- `pgs.registerModules(modules)`: espone un oggetto di moduli direttamente come proprietà di `pgs` e impedisce sovrascritture incompatibili.
+- `pgs.registerImport(...modules)`: registra moduli nel registro nominato usato dalle integrazioni avanzate.
+- `pgs.import(...names)`: recupera dal registro i moduli richiesti e genera un errore per i nomi non registrati.

package/docs/layout/body.md

@@ -0,0 +1,41 @@
+<!-- Automatically generated from templates/html/layout/body.html. Edit templates/html/layout/body.html and run npm run docs:generate again. -->
+
+# Body
+
+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 States
+
+- `darkmode`: is applied dynamically to html and body to activate the dark theme.
+
+## Output
+
+Complete HTML skeleton required to initialize the MyPGS library.
+
+## Example
+
+```html
+<!DOCTYPE html>
+<html lang="it-IT" pgs="htmlBase initP">
+
+<head>
+	<meta charset="UTF-8">
+	<meta name="viewport" content="width=device-width, initial-scale=1.0">
+
+	<!-- Colori Browsers -->
+	<meta name="theme-color" content="">
+	<meta name="apple-mobile-web-app-status-bar-color" content="">
+
+</head>
+
+<body pgs="bodyBase bodyImg bodyText bodyHeading" >
+```

package/docs/layout/flex.md

@@ -0,0 +1,116 @@
+<!-- Automatically generated from templates/html/layout/flex.html. Edit templates/html/layout/flex.html and run npm run docs:generate again. -->
+
+# Flex
+
+Flex markup, configuration, behavior, and usage example.
+
+## PGS
+
+- `flex-2`: identifies the flex-2 element used by Flex.
+- `flex-3`: identifies the flex-3 element used by Flex.
+- `flex-4`: identifies the flex-4 element used by Flex.
+- `flex-6`: identifies the flex-6 element used by Flex.
+
+## Related elements
+
+- `container`: defines the container context for the introduction.
+- `flexColumnTexts`: vertically organizes and spaces card text and content.
+- `card`: makes the demonstration cells of the flex layout visible.
+
+## Output
+
+HTML collection of responsive flex layouts with two, three, four, and six items.
+
+## Example
+
+```html
+<div pgs="container flexColumnTexts">
+    <strong>Standard section</strong>
+    <p>Centered content inside a MyPGS section.</p>
+</div>
+
+
+<div pgs="flex-2">
+    <article pgs="card flexColumnTexts">
+        <strong>Column one</strong>
+        <p>First column content.</p>
+    </article>
+
+    <article pgs="card flexColumnTexts">
+        <strong>Column two</strong>
+        <p>Second column content.</p>
+    </article>
+</div>
+
+
+<div pgs="flex-3">
+    <article pgs="card flexColumnTexts">
+        <strong>Column one</strong>
+        <p>First column content.</p>
+    </article>
+
+    <article pgs="card flexColumnTexts">
+        <strong>Column two</strong>
+        <p>Second column content.</p>
+    </article>
+
+    <article pgs="card flexColumnTexts">
+        <strong>Column three</strong>
+        <p>Third column content.</p>
+    </article>
+</div>
+
+
+<div pgs="flex-4">
+    <article pgs="card flexColumnTexts">
+        <strong>Column one</strong>
+        <p>First column content.</p>
+    </article>
+
+    <article pgs="card flexColumnTexts">
+        <strong>Column two</strong>
+        <p>Second column content.</p>
+    </article>
+
+    <article pgs="card flexColumnTexts">
+        <strong>Column three</strong>
+        <p>Third column content.</p>
+    </article>
+    <article pgs="card flexColumnTexts">
+        <strong>Column four</strong>
+        <p>Fourth column content.</p>
+    </article>
+</div>
+
+<div pgs="flex-6">
+    <article pgs="card flexColumnTexts">
+        <strong>Column one</strong>
+        <p>First column content.</p>
+    </article>
+
+    <article pgs="card flexColumnTexts">
+        <strong>Column two</strong>
+        <p>Second column content.</p>
+    </article>
+
+    <article pgs="card flexColumnTexts">
+        <strong>Column three</strong>
+        <p>Third column content.</p>
+    </article>
+
+    <article pgs="card flexColumnTexts">
+        <strong>Column four</strong>
+        <p>Fourth column content.</p>
+    </article>
+
+    <article pgs="card flexColumnTexts">
+        <strong>Column five</strong>
+        <p>Fifth column content.</p>
+    </article>
+
+    <article pgs="card flexColumnTexts">
+        <strong>Column six</strong>
+        <p>Sixth column content.</p>
+    </article>
+</div
+```

package/docs/layout/footer.md

@@ -0,0 +1,71 @@
+<!-- Automatically generated from templates/html/layout/footer.html. Edit templates/html/layout/footer.html and run npm run docs:generate again. -->
+
+# Footer
+
+Complete footer with theme control, brand area, navigation, informational content, and a link to cookie preferences.
+
+## PGS
+
+- `footer`: identifies the main footer container.
+- `footer-top`: identifies the upper section containing the brand and content.
+- `footer-top-content`: identifies the responsive inner layout of the upper section.
+- `footer-brand`: identifies the group dedicated to the brand.
+- `footer-brand-motto`: identifies the descriptive text associated with the brand.
+- `footer-content`: identifies an informational footer column.
+- `footer-legal`: identifies the lower section dedicated to legal information.
+- `footer-legal-content`: identifies the content of the legal section.
+
+## Related elements
+
+- `button`: presents theme and cookie preference controls as buttons.
+- `toggleDarkmode`: connects the control to the global light or dark theme handler.
+- `section`: applies the shared section structure to the upper and legal areas.
+- `flex-3`: distributes the upper columns responsively.
+- `logo`: inserts the brand into the footer.
+- `logo-text`: uses the text variant of the logo.
+- `cookieConsent-actionOpen`: opens the Cookie Consent preference panel.
+
+## Output
+
+Complete footer HTML structure with brand, menu, and legal area.
+
+## Example
+
+```html
+<footer pgs="footer">
+    <button pgs="button toggleDarkmode" type="button" aria-label="Change theme">
+        <i class="fa-solid fa-moon"></i>
+    </button>
+
+    <section pgs="footer-top section">
+        <div pgs="footer-top-content flex-3">
+            <div pgs="footer-brand">
+                <a aria-label="Logo" pgs="logo" href="/">
+                    <span pgs="logo-text">MyPGS</span>
+                </a>
+                <p pgs="footer-brand-motto">Componenti frontend riutilizzabili.</p>
+            </div>
+
+            <div pgs="footer-content">
+                <h2>Menu</h2>
+                <nav aria-label="Menu footer">
+                    <ul>
+                        <li><a href="/">Home</a></li>
+                        <li><a href="/contatti">Contatti</a></li>
+                    </ul>
+                </nav>
+            </div>
+        </div>
+    </section>
+
+    <section pgs="footer-legal section">
+        <div pgs="footer-legal-content">
+            <button type="button" pgs="button cookieConsent-actionOpen">Cookie preferences</button>
+            <p><a href="">Privacy Policy</a></p>
+            <p><a href="">Cookie Policy</a></p>
+            <p><a href="">Termini e Condizioni</a></p>
+            <p>© 2026 MyPgs. No rights reserved.</p>
+        </div>
+    </section>
+</footer>
+```

package/docs/layout/grid.md

@@ -0,0 +1,116 @@
+<!-- Automatically generated from templates/html/layout/grid.html. Edit templates/html/layout/grid.html and run npm run docs:generate again. -->
+
+# Grid
+
+Responsive grid examples that distribute two to six columns while preserving design-system gaps and sizing.
+
+## PGS
+
+- `grid-2`: creates a responsive grid with up to two columns.
+- `grid-3`: creates a responsive grid with up to three columns.
+- `grid-4`: creates a responsive grid with up to four columns.
+- `grid-6`: creates a responsive grid with up to six columns.
+
+## Related elements
+
+- `container`: defines the container context for the introduction.
+- `flexColumnTexts`: organizes and spaces introductory and card text.
+- `card`: makes the demonstration grid cells visible.
+
+## Output
+
+HTML collection of responsive grids with two, three, four, and six columns.
+
+## Example
+
+```html
+<div pgs="container flexColumnTexts">
+    <strong>Standard section</strong>
+    <p>Centered content inside a MyPGS section.</p>
+</div>
+
+
+<div pgs="grid-2">
+    <article pgs="card flexColumnTexts">
+        <strong>Column one</strong>
+        <p>First column content.</p>
+    </article>
+
+    <article pgs="card flexColumnTexts">
+        <strong>Column two</strong>
+        <p>Second column content.</p>
+    </article>
+</div>
+
+
+<div pgs="grid-3">
+    <article pgs="card flexColumnTexts">
+        <strong>Column one</strong>
+        <p>First column content.</p>
+    </article>
+
+    <article pgs="card flexColumnTexts">
+        <strong>Column two</strong>
+        <p>Second column content.</p>
+    </article>
+
+    <article pgs="card flexColumnTexts">
+        <strong>Column three</strong>
+        <p>Third column content.</p>
+    </article>
+</div>
+
+
+<div pgs="grid-4">
+    <article pgs="card flexColumnTexts">
+        <strong>Column one</strong>
+        <p>First column content.</p>
+    </article>
+
+    <article pgs="card flexColumnTexts">
+        <strong>Column two</strong>
+        <p>Second column content.</p>
+    </article>
+
+    <article pgs="card flexColumnTexts">
+        <strong>Column three</strong>
+        <p>Third column content.</p>
+    </article>
+    <article pgs="card flexColumnTexts">
+        <strong>Column four</strong>
+        <p>Fourth column content.</p>
+    </article>
+</div>
+
+<div pgs="grid-6">
+    <article pgs="card flexColumnTexts">
+        <strong>Column one</strong>
+        <p>First column content.</p>
+    </article>
+
+    <article pgs="card flexColumnTexts">
+        <strong>Column two</strong>
+        <p>Second column content.</p>
+    </article>
+
+    <article pgs="card flexColumnTexts">
+        <strong>Column three</strong>
+        <p>Third column content.</p>
+    </article>
+
+    <article pgs="card flexColumnTexts">
+        <strong>Column four</strong>
+        <p>Fourth column content.</p>
+    </article>
+
+    <article pgs="card flexColumnTexts">
+        <strong>Column five</strong>
+        <p>Fifth column content.</p>
+    </article>
+
+    <article pgs="card flexColumnTexts">
+        <strong>Column six</strong>
+        <p>Sixth column content.</p>
+    </article>
+</div
+```

package/docs/layout/header.md

@@ -0,0 +1,116 @@
+<!-- Automatically generated from templates/html/layout/header.html. Edit templates/html/layout/header.html and run npm run docs:generate again. -->
+
+# Header
+
+Responsive header that measures available space, switches between desktop and mobile content, and integrates menus, dark mode, and modal navigation.
+
+## PGS
+
+- `header`: identifies the main header observed by the JavaScript module.
+- `header-element`: identifies the inner group measured to determine the switch to mobile mode.
+- `header-element-alwaysOn`: identifies the initial area that is always visible.
+- `header-element-onlyDesktop`: identifies content shown only while the desktop menu is active.
+- `header-element-onlyMobile`: identifies content shown only in mobile mode.
+- `header-element-alwaysOnLast`: identifies the final area that is always visible.
+- `header-element-hamburger`: identifies the mobile navigation group.
+- `header-element-hamburger-button`: identifies the header-specific hamburger control.
+
+## PGS Options
+
+- `horizontal`: arranges the related desktop menu horizontally.
+- `vertical`: arranges the related mobile menu vertically.
+- `menuHeader`: adapts both menus to the header context.
+- `containerPGS`: uses containerPGS[header] on the modal wrapper to move the dialog into the header.
+- `right`: presents the mobile navigation dialog content from the right side.
+
+## PGS States
+
+- `mobileActive`: is applied to header and header-element when their width or the viewport requires mobile navigation.
+
+## Related elements
+
+- `logo`: inserts the brand into the initial area.
+- `logo-text`: uses the text variant of the logo.
+- `menu`: provides desktop and mobile navigation.
+- `buttonIcon`: presents theme and hamburger controls as icon buttons.
+- `toggleDarkmode`: connects the control to the global theme handler.
+- `modal`: provides opening and closing behavior for mobile navigation.
+- `modal-button`: opens the mobile panel.
+- `modal-close`: closes the mobile panel and shares the hamburger control.
+- `modal-dialog`: identifies the mobile navigation dialog.
+- `modal-dialog-content`: identifies the inner mobile navigation panel.
+
+## Output
+
+Complete header HTML with desktop navigation and a side mobile panel.
+
+## Example
+
+```html
+<header pgs="header">
+	<div pgs="header-element">
+		<div pgs="header-element-alwaysOn">
+			<a aria-label="Logo" pgs="logo" href="/">
+				<span pgs="logo-text">MyPGS</span>
+			</a>
+		</div>
+
+		<div pgs="header-element-onlyDesktop">
+			<nav pgs="menu" pgs-option="horizontal menuHeader" aria-label="Main menu">
+				<ul>
+					<li><a href="/">Home</a></li>
+					<li><a href="#components">Components</a></li>
+					<li><a href="#layout">Layout</a></li>
+				</ul>
+			</nav>
+		</div>
+
+		<div pgs="header-element-onlyMobile">
+		</div>
+
+		<div pgs="header-element-alwaysOnLast">
+			<button pgs="buttonIcon toggleDarkmode" type="button" aria-label="Change theme">
+				<i class="fa-solid fa-moon"></i>
+			</button>
+		</div>
+
+		<div pgs="header-element-hamburger modal" pgs-option="containerPGS[header] ">
+
+			<button pgs="buttonIcon modal-button modal-close header-element-hamburger-button" type="button"></button>
+
+			<dialog pgs="modal-dialog" pgs-option="right">
+				<div pgs="modal-dialog-content">
+					<nav pgs="menu" pgs-option="vertical menuHeader" aria-label="Mobile menu">
+						<ul>
+							<li><a href="/">Home</a></li>
+							<li><a href="#components">Components</a></li>
+							<li><a href="#layout">Layout</a></li>
+						</ul>
+					</nav>
+				</div>
+			</dialog>
+		</div>
+	</div>
+
+	<!-- //# HEADER BOTTOM -->
+
+	<script>
+		const addPgsState = (element, state) => {
+			if (!element) return;
+
+			const states = element.getAttribute("pgs-state")?.split(/\s+/) ?? [];
+			element.setAttribute("pgs-state", [...new Set([...states, state])].join(" "));
+		};
+
+		if (localStorage.getItem("screenIsDarkMode") === "true") {
+			addPgsState(document.documentElement, "darkmode");
+			addPgsState(document.body, "darkmode");
+		}
+
+		if (window.innerWidth < 600) {
+			addPgsState(document.querySelector("header"), "mobileActive");
+			addPgsState(document.querySelector("[pgs~=header-element]"), "mobileActive");
+		}
+	</script>
+</header>
+```