mypgs 1.3.6 → 1.3.7

package/{AI_GUIDELINES.md → AGENTS.md}

@@ -62,16 +62,16 @@ Files analyzed:
 - `assets/scss/components/*`
 - `assets/scss/patterns/*`
 - `assets/scss/mixin/*`
-- `templates/components/*`
-- `templates/layout/*`
-- `templates/patterns/*`
+- `templates/html/components/*`
+- `templates/html/layout/*`
+- `templates/html/patterns/*`
 
 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/layout/body.html` as the canonical references.
-- Components use a root token and child tokens with a consistent prefix. Use `templates/components/` as the canonical markup source.
+- 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.
+- 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`.
 - 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.
@@ -84,14 +84,15 @@ Patterns found:
 Recommended imports in a project that consumes the library:
 
 ```scss
-@import "../../node_modules/mypgs/assets/scss/mixin/mixin.scss";
-@import "../../node_modules/mypgs/assets/scss/index.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");
 ```
 
 If you only need the mixins:
 
 ```scss
-@import "../../node_modules/mypgs/assets/scss/mixin/mixin.scss";
+@use "../../node_modules/mypgs/assets/scss/mixin/mixin.scss" as * ;
 ```
 
 Direct usage of the compiled CSS:
@@ -222,9 +223,9 @@ Use the templates as the single source of truth for component and layout markup.
 
 Canonical template references:
 
-- Layouts: `templates/layout/body.html`, `templates/layout/flex.html`, `templates/layout/grid.html`, `templates/layout/pageShell.html`, `templates/layout/section.html`
-- Components: `templates/components/accordion.html`, `templates/components/breadcumbs.html`, `templates/components/button.html`, `templates/components/card.html`, `templates/components/dropdown.html`, `templates/components/form.html`, `templates/components/logo.html`, `templates/components/menu.html`, `templates/components/modal.html`, `templates/components/notification.html`, `templates/components/searchbar.html`, `templates/components/slides.html`, `templates/components/stepTabs.html`, `templates/components/steps.html`, `templates/components/table.html`, `templates/components/tooltip.html`
-- Patterns: `templates/patterns/cookieConsent.html`, `templates/patterns/footer.html`, `templates/patterns/header.html`
+- 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`
+- 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`
 
 Before creating markup, open the relevant template and reuse its current structure, tokens, ARIA attributes, and `pgs-option` syntax.
@@ -257,11 +258,12 @@ import "mypgs/style.css";
 Source SCSS import:
 
 ```scss
-@import "../../node_modules/mypgs/assets/scss/mixin/mixin.scss";
-@import "../../node_modules/mypgs/assets/scss/index.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");
 ```
 
-Recommended: use PGS layout tokens from `templates/layout/`.
+Recommended: use PGS layout tokens from `templates/html/layout/`.
 
 Avoid: equivalent custom layout with ad hoc classes when a PGS layout token already exists.
 
@@ -326,7 +328,7 @@ For a new reusable component:
 - create JS in `assets/javascript/components/` or `assets/javascript/patterns/` only if behavior is needed;
 - export an object with `init` and/or `api` when the module needs a public API;
 - register it in `assets/javascript/_imports.js` with `pgs.registerModules` if it must be available as `pgs.moduleName`;
-- add a template in `templates/components/` or `templates/layout/`;
+- add a template in `templates/html/components/` or `templates/html/layout/`;
 - update `README.md` and this guide if the usage changes.
 
 Example for a new module:

package/README.md

@@ -56,14 +56,15 @@ Markup minimo consigliato:
 Se il progetto vuole compilare un CSS unico, importa gli SCSS sorgenti:
 
 ```scss
-@import "../../node_modules/mypgs/assets/scss/mixin/mixin.scss";
-@import "../../node_modules/mypgs/assets/scss/index.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");
 ```
 
 Se servono solo i mixin:
 
 ```scss
-@import "../../node_modules/mypgs/assets/scss/mixin/mixin.scss";
+@use "../../node_modules/mypgs/assets/scss/mixin/mixin.scss" as * ;
 ```
 
 La libreria espone molte custom properties da preferire agli hardcode, per esempio:
@@ -228,173 +229,7 @@ pgs.modal.api(modalEl)?.open();
 
 ## Componenti e markup
 
-I template completi sono in `templates/components/` e `templates/layout/`. Usa quei file come sorgente di riferimento prima di creare markup nuovo.
-
-### Layout
-
-```html
-<main pgs="main">
-  <section pgs="section flexColumnElements">
-    <div pgs="flexColumnTexts">
-      <h2>Titolo</h2>
-      <p>Contenuto.</p>
-    </div>
-  </section>
-</main>
-```
-
-```html
-<section pgs="sectionFull flexColumnElements">
-  <div pgs="grid-3">
-    <article pgs="card flexColumnTexts">
-      <h3>Colonna uno</h3>
-      <p>Contenuto.</p>
-    </article>
-  </div>
-</section>
-```
-
-### Bottoni
-
-```html
-<button pgs="button" type="button">Base</button>
-<button pgs="buttonStrong" type="button">Primario</button>
-<button pgs="buttonIcon" type="button" aria-label="Impostazioni">
-  <i class="fa-solid fa-gear" aria-hidden="true"></i>
-</button>
-```
-
-### Accordion
-
-```html
-<div pgs="accordion">
-  <button pgs="accordion-button" type="button">Domanda</button>
-  <div pgs="accordion-content">Risposta</div>
-</div>
-```
-
-### Dropdown
-
-```html
-<span pgs="dropdown">
-  <button pgs="dropdown-button button" type="button">Apri menu</button>
-  <div pgs="dropdown-content">
-    <nav aria-label="Menu dropdown"></nav>
-  </div>
-</span>
-```
-
-### Modal
-
-```html
-<div pgs="modal" pgs-option="containerID[modal-container]">
-  <button pgs="modal-button button" type="button">Apri modale</button>
-  <dialog>
-    <div pgs="modal-dialog-content">
-      <div pgs="modal-dialog-content-header">
-        <h3>Modale</h3>
-      </div>
-      <div pgs="modal-dialog-content-scroll">
-        <p>Contenuto della modale.</p>
-      </div>
-    </div>
-  </dialog>
-</div>
-<div id="modal-container"></div>
-```
-
-### Slides
-
-```html
-<div pgs="slides" pgs-option="singleScroll shadowDesktop">
-  <ul pgs="slides-container">
-    <li>
-      <article pgs="card flexColumn">
-        <img pgs="card-img imgCover" src="image.jpg" alt="">
-        <div pgs="flexColumnTexts">
-          <h3>Slide uno</h3>
-        </div>
-      </article>
-    </li>
-  </ul>
-</div>
-```
-
-### Step tabs
-
-```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]"></section>
-  </div>
-  <div pgs="flexRow">
-    <button pgs="stepTabs-prev button" type="button">Indietro</button>
-    <button pgs="stepTabs-next button" pgs-option="buttonReverse" type="button">Avanti</button>
-  </div>
-</div>
-```
-
-### Form
-
-```html
-<form pgs="form" action="#" method="post">
-  <label pgs="label" for="form-email">Email</label>
-  <input id="form-email" pgs="input" type="email" name="email" required data-form-field-message="Inserisci una email valida">
-  <button pgs="buttonStrong" type="submit">Invia</button>
-</form>
-```
-
-Validazione programmatica:
-
-```js
-const form = document.querySelector("form");
-const validator = new pgs.formValidate({ form });
-
-if (validator.validate()) {
-  pgs.notification.toast.success("Inviato con successo");
-}
-```
-
-### Notifiche
-
-```html
-<div pgs="notification" aria-live="polite"></div>
-<div pgs="toast" aria-live="polite"></div>
-```
-
-```js
-pgs.notification.toast.success("Salvato");
-pgs.notification.alert.error("Errore", null, 0);
-```
-
-Trigger da markup:
-
-```html
-<div pgs="hidden notificationTrigger" data-notification='{
-  "title":"Titolo",
-  "message":"Messaggio",
-  "element":"notification",
-  "type":"info",
-  "duration":"-1"
-}'></div>
-```
-
-### Menu
-
-```html
-<nav pgs="menuHorizontal" aria-label="Menu principale">
-  <ul>
-    <li class="menu-item"><a href="/">Home</a></li>
-    <li class="menu-item menu-item-has-children">
-      <a href="/servizi">Servizi</a>
-      <ul class="sub-menu">
-        <li class="menu-item"><a href="/servizi/uno">Servizio uno</a></li>
-      </ul>
-    </li>
-  </ul>
-</nav>
-```
+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
 
@@ -484,8 +319,9 @@ import "mypgs/style.css";
 Uso sorgente SCSS:
 
 ```scss
-@import "../../node_modules/mypgs/assets/scss/mixin/mixin.scss";
-@import "../../node_modules/mypgs/assets/scss/index.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

package/assets/scss/mixin/_mx-responsive.scss

@@ -1,3 +1,4 @@
+@use "sass:math";
 @use "settings" as *;
 
 //= FLEX 
@@ -52,7 +53,7 @@
 
 //= FLEX
 @function _basis($ratio, $gap, $columns) {
-    $cols: ceil($columns * $ratio);
+    $cols: math.ceil($columns * $ratio);
     @return calc((100% - ($gap * ($cols - 1))) / $cols);
 }
 
@@ -196,17 +197,17 @@
 
         //-( laptop 
         @container (max-width: #{$laptop}) {
-            grid-template-columns: repeat(ceil($columns * 0.75), 1fr); // 75% delle colonne originali
+            grid-template-columns: repeat(math.ceil($columns * 0.75), 1fr); // 75% delle colonne originali
         }
 
         //-( big-tablet 
         @container (max-width: #{$big-tablet}) {
-            grid-template-columns: repeat(ceil($columns * 0.5), 1fr); // 50% delle colonne originali
+            grid-template-columns: repeat(math.ceil($columns * 0.5), 1fr); // 50% delle colonne originali
         }
 
         //-( tablet 
         @container (max-width: #{$tablet}) {
-            grid-template-columns: repeat(ceil($columns * 0.33), 1fr); // 33% delle colonne originali
+            grid-template-columns: repeat(math.ceil($columns * 0.33), 1fr); // 33% delle colonne originali
         }
     }
 
@@ -214,17 +215,17 @@
 
         //-( laptop 
         @container (max-width: #{$laptop}) {
-            grid-template-columns: repeat(ceil($columns * 0.75), 1fr); // 75% delle colonne originali
+            grid-template-columns: repeat(math.ceil($columns * 0.75), 1fr); // 75% delle colonne originali
         }
 
         //-( big-tablet 
         @container (max-width: #{$big-tablet}) {
-            grid-template-columns: repeat(ceil($columns * 0.5), 1fr); // 50% delle colonne originali
+            grid-template-columns: repeat(math.ceil($columns * 0.5), 1fr); // 50% delle colonne originali
         }
 
         //-( tablet 
         @container (max-width: #{$tablet}) {
-            grid-template-columns: repeat(ceil($columns * 0.33), 1fr); // 33% delle colonne originali
+            grid-template-columns: repeat(math.ceil($columns * 0.33), 1fr); // 33% delle colonne originali
         }
     }
 
@@ -261,17 +262,17 @@
 
     //-( da 1500px
     @container (max-width: #{$start}) {
-        grid-template-columns: repeat(ceil($columns * 0.75), 1fr);
+        grid-template-columns: repeat(math.ceil($columns * 0.75), 1fr);
     }
 
     //-( circa tablet landscape
     @container (max-width: #{calc($start * 0.75)}) {
-        grid-template-columns: repeat(ceil($columns * 0.5), 1fr);
+        grid-template-columns: repeat(math.ceil($columns * 0.5), 1fr);
     }
 
     //-( tablet
     @container (max-width: #{calc($start * 0.5)}) {
-        grid-template-columns: repeat(ceil($columns * 0.33), 1fr);
+        grid-template-columns: repeat(math.ceil($columns * 0.33), 1fr);
     }
 
     //-( mobile