npm - mypgs - Versions diffs - 1.3.2 → 1.3.4 - Mend

mypgs 1.3.2 → 1.3.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (73) hide show

package/AI_GUIDELINES.md +353 -0
package/README.md +483 -53
package/assets/javascript/_imports.js +12 -11
package/assets/javascript/_pgs.js +16 -1
package/assets/javascript/components/_accordion.js +18 -9
package/assets/javascript/components/_dropdown.js +176 -120
package/assets/javascript/components/_menu.js +15 -116
package/assets/javascript/components/_modals.js +0 -1
package/assets/javascript/components/_notifications.js +2 -3
package/assets/javascript/components/_slides.js +0 -1
package/assets/javascript/components/_stepTabs.js +0 -1
package/assets/javascript/components/_steps.js +0 -1
package/assets/javascript/patterns/_cookieConsent.js +8 -2
package/assets/javascript/pgs.d.ts +12 -1
package/assets/scss/base/_html.scss +23 -1
package/assets/scss/components/_dropdown.scss +24 -88
package/assets/scss/components/_menu.scss +129 -15
package/assets/scss/components/_modals.scss +15 -3
package/assets/scss/components/_notification.scss +11 -14
package/assets/scss/components/_tooltip.scss +2 -9
package/assets/scss/index.scss +0 -1
package/assets/scss/layout/_gap.scss +7 -1
package/assets/scss/layout/_layout.scss +0 -12
package/assets/scss/layout/_pageShell.scss +104 -105
package/assets/scss/mixin/_mx-form.scss +16 -6
package/assets/scss/mixin/_mx-responsive.scss +2 -2
package/assets/scss/mixin/_mx-semantic.scss +0 -60
package/assets/scss/mixin/mixin.scss +0 -1
package/assets/scss/patterns/_footer.scss +1 -0
package/assets/scss/patterns/_header.scss +20 -18
package/dist/css/index.css +264 -1179
package/dist/css/index.css.map +1 -1
package/dist/css/index.min.css +1 -1
package/dist/index.d.ts +12 -1
package/dist/javascript/index.js +264 -272
package/dist/javascript/index.js.map +1 -1
package/dist/javascript/index.min.js +1 -1
package/package.json +1 -1
package/templates/components/{md-accordion.html → accordion.html} +2 -2
package/templates/components/dropdown.html +91 -0
package/templates/components/menu.html +41 -0
package/templates/components/modal.html +78 -0
package/templates/components/notification.html +35 -0
package/templates/components/{md-slides.html → slides.html} +5 -5
package/templates/components/{md-steps.html → steps.html} +7 -7
package/templates/components/{md-tooltip.html → tooltip.html} +4 -2
package/templates/demo.css +18 -0
package/templates/demo.html +4 -5
package/templates/demo.js +53 -52
package/templates/layout/flex.html +89 -0
package/templates/layout/grid.html +89 -0
package/templates/layout/pageShell.html +59 -0
package/templates/layout/section.html +40 -0
package/templates/{layout/md-footer.html → patterns/footer.html} +1 -0
package/templates/{layout/md-header.html → patterns/header.html} +6 -9
package/assets/scss/base/_reset.scss +0 -15
package/assets/scss/mixin/_mx-menu.scss +0 -154
package/templates/components/md-dropdown.html +0 -16
package/templates/components/md-menu.html +0 -40
package/templates/components/md-modal.html +0 -19
package/templates/components/md-notification.html +0 -13
package/templates/layout/md-pageShell.html +0 -22
package/templates/layout/md-section.html +0 -25
/package/templates/components/{md-breadcumbs.html → breadcumbs.html} +0 -0
/package/templates/components/{md-button.html → button.html} +0 -0
/package/templates/components/{md-card.html → card.html} +0 -0
/package/templates/components/{md-form.html → form.html} +0 -0
/package/templates/components/{md-logo.html → logo.html} +0 -0
/package/templates/components/{md-searchbar.html → searchbar.html} +0 -0
/package/templates/components/{md-stepTabs.html → stepTabs.html} +0 -0
/package/templates/components/{md-table.html → table.html} +0 -0
/package/templates/layout/{md-body.html → body.html} +0 -0
/package/templates/{layout/md-cookieConsent.html → patterns/cookieConsent.html} +0 -0

package/README.md CHANGED Viewed

@@ -1,32 +1,148 @@
 # MyPGS
-Libreria frontend condivisa per componenti, layout e pattern basati sull'attributo `pgs`.
+`mypgs` e' una libreria frontend condivisa per costruire interfacce coerenti tramite attributi `pgs`, SCSS sorgenti, componenti UI e comportamenti JavaScript riutilizzabili.
-Contiene sorgenti SCSS, mixin, comportamenti JavaScript, template HTML di esempio e asset compilati pronti all'uso. Puo' essere usata sia importando direttamente CSS e JavaScript compilati, sia importando gli SCSS sorgenti dentro il build del progetto che la utilizza.
+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.
-## Installazione come dipendenza
+## Cosa contiene
-Da registry npm, se pubblicata:
+- `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.
+- `AI_GUIDELINES.md`: guida operativa per AI/Codex.
+- `AI_GUIDELINES_EN.md`: versione inglese della guida.
+## Installazione
+Da registry npm:
 ```bash
 npm install mypgs
 ```
-## Utilizzo
+## Uso rapido
+Importa JavaScript e CSS compilato nell'entrypoint del progetto:
-### JavaScript
+```js
+import "mypgs";
+import "mypgs/style.css";
+```
-Importa la libreria nell'entrypoint JavaScript del progetto:
+Se ti serve accedere direttamente all'helper:
 ```js
-import * as mypgs from "mypgs";
+import { pgs } from "mypgs";
+import "mypgs/style.css";
+```
+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
+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";
 ```
-L'entrypoint di MyPGS inizializza:
+Se servono solo i mixin:
+```scss
+@import "../../node_modules/mypgs/assets/scss/mixin/mixin.scss";
+```
+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:
+```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`:
+```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 oggetti PGS
+- gestione object SVG
 - accordion
 - dropdown
 - menu
@@ -38,55 +154,309 @@ L'entrypoint di MyPGS inizializza:
 - header
 - cookie consent
-Il bundle finale viene generato dal progetto che importa `mypgs`, in base alla propria configurazione Webpack o al proprio bundler.
+I componenti inizializzati usano `WeakMap` interne per esporre API di istanza.
-### SCSS
+## API dei moduli
-Per integrare MyPGS nel build SCSS del progetto, importa mixin e stili sorgenti da `node_modules`:
+I moduli principali sono registrati in `assets/javascript/_imports.js` in due modi.
-```scss
-@import "../../node_modules/mypgs/assets/scss/mixin/mixin.scss";
-@import "../../node_modules/mypgs/assets/scss/index.scss";
+### 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,
+});
 ```
-Se servono solo i mixin, importa solo il file dedicato:
+Uso consigliato:
-```scss
-@import "../../node_modules/mypgs/assets/scss/mixin/mixin.scss";
+```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();
 ```
-Molti layout, componenti e pattern sono inclusi sotto `[pgs~=initP]`, quindi il markup principale deve abilitare la libreria così:
+`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/components/` e `templates/layout/`. Usa quei file come sorgente di riferimento prima di creare markup nuovo.
+### Layout
 ```html
-<html pgs="htmlBase initP">
-<body pgs="bodyBase bodyImg bodyText bodyHeading">
+<main pgs="main">
+  <section pgs="section flexColumnElements">
+    <div pgs="flexColumnTexts">
+      <h2>Titolo</h2>
+      <p>Contenuto.</p>
+    </div>
+  </section>
+</main>
 ```
-## Markup PGS
+```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>
+```
-I componenti vengono attivati usando token nell'attributo `pgs`, per esempio:
+### Accordion
 ```html
-<nav pgs="menuHorizontal"></nav>
-<button pgs="button modal-button"></button>
 <div pgs="accordion">
-  <button pgs="accordion-button"></button>
-  <div pgs="accordion-content"></div>
+  <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>
 ```
-Gli stessi token devono restare coerenti tra markup, SCSS e JavaScript.
+### 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:
-## Contenuto del pacchetto
+```js
+const form = document.querySelector("form");
+const validator = new pgs.formValidate({ form });
-- `assets/scss/`: sorgenti SCSS, mixin, base, layout, componenti e pattern
-- `assets/javascript/`: sorgenti JavaScript dei comportamenti PGS
-- `templates/`: esempi HTML dei componenti e dei layout
-- `dist/javascript/index.js`: bundle JavaScript non minificato
-- `dist/javascript/index.min.js`: bundle JavaScript minificato
-- `dist/css/index.css`: CSS compilato non minificato
-- `dist/css/index.min.css`: CSS compilato minificato
-- `dist/index.d.ts`: dichiarazioni TypeScript esportate dal pacchetto
+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>
+```
+## 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
@@ -94,20 +464,29 @@ Il pacchetto espone:
 ```json
 {
-  ".": "./dist/javascript/index.js",
+  ".": {
+    "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"
 }
 ```
-Uso diretto degli asset compilati:
+Uso compilato:
 ```js
 import "mypgs";
 import "mypgs/style.css";
 ```
-In alternativa, puoi importare gli SCSS sorgenti direttamente nel build del progetto quando vuoi ottenere un unico CSS finale.
+Uso sorgente SCSS:
+```scss
+@import "../../node_modules/mypgs/assets/scss/mixin/mixin.scss";
+@import "../../node_modules/mypgs/assets/scss/index.scss";
+```
 ## Sviluppo
@@ -123,24 +502,75 @@ Build in watch mode:
 npm run "start watch"
 ```
-Per preparare un archivio locale installabile in un altro progetto:
+Creare un pacchetto locale:
 ```bash
 npm pack
 ```
-Quando modifichi MyPGS e vuoi provarlo in un progetto che la usa:
+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.
-1. ricompila MyPGS con `npm run start`
-2. crea un nuovo archivio con `npm pack`
-3. copia o aggiorna il `.tgz` usato dal progetto
-4. esegui `npm install` nel progetto
-5. ricompila il progetto
+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);
+```
 ## Convenzioni
-- Usa l'attributo `pgs` per collegare markup, CSS e JavaScript.
-- Mantieni i token PGS coerenti tra template HTML, componenti, moduli e script.
-- Metti in MyPGS solo stili e comportamenti riutilizzabili.
-- Mantieni nel progetto finale gli stili e le personalizzazioni specifiche.
-- Esporta in `dist/` prima di creare il pacchetto locale `.tgz`.
+- 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.

package/assets/javascript/_imports.js CHANGED Viewed

@@ -11,15 +11,16 @@ import { PGS_steps } from "./components/_steps.js";
 import { PGS_formValidate } from "./functions/_formValidate.js";
 import { PGS_scrollHorizontal } from "./functions/_scrollY.js";
-pgs.registerImport({
-    PGS_accordion,
-    PGS_dropdown,
-    PGS_menu,
-    PGS_modal,
-    PGS_notification,
-    PGS_slides,
-    PGS_stepTabs,
-    PGS_steps,
-    PGS_formValidate,
-    PGS_scrollHorizontal,
+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,
 });

package/assets/javascript/_pgs.js CHANGED Viewed

@@ -220,7 +220,6 @@ export function pgs(root) {
     const api = createBasePgs();
     api.state = createState("pgs-state");
     api.option = createOption("pgs-option");
-    api.modules = createOption("pgs-modules");
     return api;
 }
@@ -250,6 +249,22 @@ pgs.registerImport = function (...modules) {
     return pgs;
 };
+pgs.registerModules = function (modules = {}) {
+    Object.entries(modules).forEach(([name, module]) => {
+        const key = String(name || "").trim();
+        if (!key) return;
+        const hasOwn = Object.prototype.hasOwnProperty.call(pgs, key);
+        if (hasOwn && pgs[key] !== module) {
+            throw new Error(`pgs.registerModules(): "${key}" e' gia' definito su pgs`);
+        }
+        pgs[key] = module;
+    });
+    return pgs;
+};
 pgs.import = function (...names) {
     return names.flat().reduce((imports, name) => {
         const key = String(name || "").trim().replace(/^pgs[_-\s]*/i, "").toLowerCase();