npm - mypgs - Versions diffs - 1.4.1 → 1.5.1 - Mend

mypgs 1.4.1 → 1.5.1

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 (22) hide show

package/README.md +29 -355
package/assets/scss/base/_color.scss +3 -10
package/assets/scss/base/_general.scss +36 -48
package/assets/scss/base/_heading.scss +14 -16
package/assets/scss/components/_card.scss +10 -0
package/assets/scss/index.scss +6 -2
package/dist/css/index.css +2888 -2919
package/dist/css/index.css.map +1 -1
package/dist/css/index.min.css +1 -1
package/dist/index.d.ts +2 -0
package/dist/javascript/index.js +146 -144
package/dist/javascript/index.js.map +1 -1
package/dist/javascript/index.min.js +1 -1
package/docs/componenti-e-markup.md +54 -0
package/docs/convenzioni.md +12 -0
package/docs/export-e-sviluppo.md +109 -0
package/docs/helper-javascript.md +124 -0
package/docs/utilizzo-css-scss.md +36 -0
package/package.json +6 -2
package/plugins/vite-plugin-pgs.d.ts +13 -0
package/plugins/vite-plugin-pgs.js +7 -2
package/assets/javascript/pgs.d.ts +0 -76

package/README.md CHANGED Viewed

@@ -12,46 +12,44 @@ 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";
 ```
-Markup minimo consigliato:
+**React/TSX con Vite:**
-```html
-<html lang="it" pgs="htmlBase initP">
-  <body pgs="bodyBase bodyImg bodyText bodyHeading">
-    <main pgs="main"></main>
-  </body>
-</html>
-```
+Configura il plugin che converte `pgsHtml` in `pgs`:
-`initP` e' importante: molti layout, componenti e pattern SCSS sono definiti sotto `[pgs~=initP]`.
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from "@vitejs/plugin-react";
+import pgsVite from "mypgs/vite-plugin-pgs";
-## Uso SCSS sorgente
+export default {
+  plugins: [pgsVite(), react()],
+};
+```
+### SCSS
 Se il progetto vuole compilare un CSS unico, importa gli SCSS sorgenti:
@@ -67,346 +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:
-```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:
+### Markup
-```js
-pgs(modal).option.contains("history");
-pgs(modal).option.getValueBrackets("containerID");
-```
-Esempio markup con opzioni:
+`initP` e' importante: tutti i layout, componenti e pattern SCSS sono definiti sotto `[pgs~=initP]`.
 ```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"
-}
-```
-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/scss/base/_color.scss CHANGED Viewed

@@ -8,30 +8,23 @@
     &[data-darkmode=true] {
         color-scheme: dark;
     }
-}
-// == Primary colors
-:root {
+    // == Primary colors
     --color-primary: #5c7d6f;
     --color-secondary: #3d5f4f;
     --color-tertiary: #8fb082;
     --color-quaternary: #10201c;
-}
-// == Base colors
-:root {
+    // == Base colors
     --color-white: light-dark(#FFFFFF, #000000);
     --color-black: light-dark(#000000, #FFFFFF);
     --color-white-transparent: color-mix(in srgb, var(--color-white) 50%, transparent 100%);
     --color-black-transparent: color-mix(in srgb, var(--color-black) 50%, transparent 100%);
     --color-text: light-dark(#4a4a4a, #e3e3e3);
     --color-box: light-dark(#F8F8F8, #3A3A3A);
     --color-boxDark: light-dark(#3A3A3A, #F8F8F8);
     --color-box-transparent: light-dark(color-mix(in srgb, #eeeeee 50%, transparent 50%), color-mix(in srgb, #3A3A3A 50%, transparent 50%));
     --color-boxDark-transparent: light-dark(color-mix(in srgb, #3A3A3A 50%, transparent 50%), color-mix(in srgb, #eeeeee 50%, transparent 50%));
     --color-linkBackgorud: light-dark(#a0dbff, #002a44);
     --color-background: light-dark(#ffffff, #080808);
     --color-whiteFixed: #FFFFFF;

package/assets/scss/base/_general.scss CHANGED Viewed

@@ -1,63 +1,51 @@
 @use "../mixin/mixin" as *;
 //# GENERAL
-[pgs~=initP] {
+[pgs~=boxtext] {
+    @include boxtext();
+}
-    [pgs~=card],
-    [pgs~=cardImg] {
-        @include card();
+[pgs~=darkmode] {
+    color-scheme: dark;
+}
-        [pgs~=card-img] {
-            @include card-insideImg();
-        }
-    }
+[pgs~=lightmode] {
+    color-scheme: light;
+}
-    [pgs~=boxtext] {
-        @include boxtext();
-    }
+[pgs~=imgCover] {
+    object-fit: cover;
+}
-    [pgs~=darkmode] {
-        color-scheme: dark;
-    }
+[pgs~=imgContain] {
+    object-fit: contain;
+}
-    [pgs~=lightmode] {
-        color-scheme: light;
-    }
+[pgs~=borderRadius] {
+    border-radius: var(--border-radius);
+}
-    [pgs~=imgCover] {
-        object-fit: cover;
-    }
+[pgs~=borderRadiusInput] {
+    border-radius: var(--border-radius-input);
+}
-    [pgs~=imgContain] {
-        object-fit: contain;
-    }
+[pgs~=borderRadiusExternal] {
+    border-radius: var(--border-radius-external);
+}
-    [pgs~=borderRadius] {
-        border-radius: var(--border-radius);
-    }
+[pgs~=blur] {
+    backdrop-filter: var(--blur);
+}
-    [pgs~=borderRadiusInput] {
-        border-radius: var(--border-radius-input);
-    }
+[pgs~=appearanceNone] {
+    all: unset;
+    appearance: none;
+}
-    [pgs~=borderRadiusExternal] {
-        border-radius: var(--border-radius-external);
-    }
+[pgs~=pointer] {
+    cursor: pointer;
+}
-    [pgs~=blur] {
-        backdrop-filter: var(--blur);
-    }
-    [pgs~=appearanceNone] {
-        all: unset;
-        appearance: none;
-    }
-    [pgs~=pointer] {
-        cursor: pointer;
-    }
-    [pgs~=hidden] {
-        display: none !important;
-    }
+[pgs~=hidden] {
+    display: none !important;
 }

package/assets/scss/base/_heading.scss CHANGED Viewed

@@ -1,24 +1,22 @@
 @use "../mixin/mixin" as *;
 //# HEADING
-[pgs~=initP] {
-    [pgs~=h1] {
-        @include h1();
-    }
+[pgs~=h1] {
+    @include h1();
+}
-    [pgs~=h2] {
-        @include h2();
-    }
+[pgs~=h2] {
+    @include h2();
+}
-    [pgs~=h3] {
-        @include h3();
-    }
+[pgs~=h3] {
+    @include h3();
+}
-    [pgs~=h4] {
-        @include h4();
-    }
+[pgs~=h4] {
+    @include h4();
+}
-    [pgs~=h5] {
-        @include h5();
-    }
+[pgs~=h5] {
+    @include h5();
 }

package/assets/scss/components/_card.scss ADDED Viewed

@@ -0,0 +1,10 @@
+@use "../mixin/mixin" as *;
+[pgs~=card],
+[pgs~=cardImg] {
+    @include card();
+    [pgs~=card-img] {
+        @include card-insideImg();
+    }
+}

package/assets/scss/index.scss CHANGED Viewed

@@ -9,8 +9,11 @@
 @include meta.load-css("base/color");
 @include meta.load-css("base/html");
 @include meta.load-css("base/body");
-@include meta.load-css("base/heading");
-@include meta.load-css("base/general");
+[pgs~=initP] {
+    @include meta.load-css("base/heading");
+    @include meta.load-css("base/general");
+}
 /*
 |--------------------------------------------------------------------------
@@ -33,6 +36,7 @@
 |--------------------------------------------------------------------------
 */
 [pgs~=initP] {
+    @include meta.load-css("components/card");
     @include meta.load-css("components/button");
     @include meta.load-css("components/form");
     @include meta.load-css("components/menu");