mypgs 1.6.0 → 2.1.0

package/docs/layout/pageShell.md

@@ -0,0 +1,94 @@
+<!-- Automatically generated from templates/html/layout/pageShell.html. Edit templates/html/layout/pageShell.html and run npm run docs:generate again. -->
+
+# Page Shell
+
+Responsive page layout that combines main content with zero, one, or two scrollable sidebars and adapts their width and position.
+
+## PGS
+
+- `pageShell`: identifies the container that calculates the main and aside composition.
+- `pageShell-aside`: identifies a sidebar that can be placed before or after the content.
+- `pageShell-aside-scroll`: identifies the inner area that can remain visible while scrolling.
+- `pageShell-content`: identifies the main page content.
+
+## Related elements
+
+- `flexColumnTexts`: organizes text contained in the sidebars.
+- `flexColumnElements`: vertically organizes elements in the main sections.
+
+## Output
+
+Four page-shell HTML configurations with two, one, or no sidebars.
+
+## Example
+
+```html
+<div pgs="pageShell">
+    <aside pgs="pageShell-aside">
+        <div pgs="pageShell-aside-scroll">
+            <div pgs="flexColumnTexts">
+                <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Ab modi ut sunt est illum accusantium dolores eum aut cum itaque.</p>
+            </div>
+        </div>
+    </aside>
+
+    <main pgs="pageShell-content">
+        <section pgs="flexColumnElements" id="sezione-uno">
+            <strong>Lorem ipsum</strong>
+            <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Quidem dolore veniam nulla hic voluptatum harum illo voluptatem quos. Id quibusdam nemo, mollitia iusto quisquam tenetur doloremque corrupti natus nisi est sed consectetur deserunt? Fugiat consectetur iure aut id voluptate unde autem eius facilis dolorum? Eveniet, sit, excepturi iusto porro eos temporibus illum non ut sunt ex aut earum neque. Iure harum similique autem commodi ratione enim quisquam soluta rem, eius dolor officiis necessitatibus voluptatibus obcaecati vel sint iusto. Eligendi reiciendis aut error rem? Hic aliquid tenetur porro itaque quaerat excepturi consequatur veniam, et alias molestiae, eius odio quae maiores suscipit iure voluptatibus sed dolor facere ipsa quod libero necessitatibus, placeat natus. Doloribus esse nobis culpa ab ut dolorem id expedita nesciunt necessitatibus ipsam natus accusantium eius eveniet eum, distinctio quos modi perspiciatis earum sequi nostrum consequatur quibusdam? Blanditiis iusto possimus officia odio animi repudiandae? Repellendus autem ut soluta facere accusamus magni aut architecto cumque cupiditate. Nostrum officiis, tenetur consequuntur quaerat alias animi debitis? Quae quas placeat iure alias totam quaerat fugit recusandae sed, earum ipsa nihil molestiae quam odit itaque, odio asperiores, mollitia porro ratione tempora laboriosam. Incidunt aliquam nobis sunt ut molestiae nam animi placeat neque vero ratione? Eaque?</p>
+        </section>
+    </main>
+
+    <aside pgs="pageShell-aside">
+        <div pgs="pageShell-aside-scroll">
+            <div pgs="flexColumnTexts">
+                <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Ab modi ut sunt est illum accusantium dolores eum aut cum itaque.</p>
+            </div>
+        </div>
+    </aside>
+</div>
+<div pgs="pageShell">
+    <aside pgs="pageShell-aside">
+        <div pgs="pageShell-aside-scroll">
+            <div pgs="flexColumnTexts">
+                <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Ab modi ut sunt est illum accusantium dolores eum aut cum itaque.</p>
+            </div>
+        </div>
+    </aside>
+
+    <main pgs="pageShell-content">
+        <section pgs="flexColumnElements" id="sezione-uno">
+            <strong>Lorem ipsum</strong>
+            <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Quidem dolore veniam nulla hic voluptatum harum illo voluptatem quos. Id quibusdam nemo, mollitia iusto quisquam tenetur doloremque corrupti natus nisi est sed consectetur deserunt? Fugiat consectetur iure aut id voluptate unde autem eius facilis dolorum? Eveniet, sit, excepturi iusto porro eos temporibus illum non ut sunt ex aut earum neque. Iure harum similique autem commodi ratione enim quisquam soluta rem, eius dolor officiis necessitatibus voluptatibus obcaecati vel sint iusto. Eligendi reiciendis aut error rem? Hic aliquid tenetur porro itaque quaerat excepturi consequatur veniam, et alias molestiae, eius odio quae maiores suscipit iure voluptatibus sed dolor facere ipsa quod libero necessitatibus, placeat natus. Doloribus esse nobis culpa ab ut dolorem id expedita nesciunt necessitatibus ipsam natus accusantium eius eveniet eum, distinctio quos modi perspiciatis earum sequi nostrum consequatur quibusdam? Blanditiis iusto possimus officia odio animi repudiandae? Repellendus autem ut soluta facere accusamus magni aut architecto cumque cupiditate. Nostrum officiis, tenetur consequuntur quaerat alias animi debitis? Quae quas placeat iure alias totam quaerat fugit recusandae sed, earum ipsa nihil molestiae quam odit itaque, odio asperiores, mollitia porro ratione tempora laboriosam. Incidunt aliquam nobis sunt ut molestiae nam animi placeat neque vero ratione? Eaque?</p>
+        </section>
+    </main>
+</div>
+
+<div pgs="pageShell">
+
+    <main pgs="pageShell-content">
+        <section pgs="flexColumnElements" id="sezione-uno">
+            <strong>Lorem ipsum</strong>
+            <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Quidem dolore veniam nulla hic voluptatum harum illo voluptatem quos. Id quibusdam nemo, mollitia iusto quisquam tenetur doloremque corrupti natus nisi est sed consectetur deserunt? Fugiat consectetur iure aut id voluptate unde autem eius facilis dolorum? Eveniet, sit, excepturi iusto porro eos temporibus illum non ut sunt ex aut earum neque. Iure harum similique autem commodi ratione enim quisquam soluta rem, eius dolor officiis necessitatibus voluptatibus obcaecati vel sint iusto. Eligendi reiciendis aut error rem? Hic aliquid tenetur porro itaque quaerat excepturi consequatur veniam, et alias molestiae, eius odio quae maiores suscipit iure voluptatibus sed dolor facere ipsa quod libero necessitatibus, placeat natus. Doloribus esse nobis culpa ab ut dolorem id expedita nesciunt necessitatibus ipsam natus accusantium eius eveniet eum, distinctio quos modi perspiciatis earum sequi nostrum consequatur quibusdam? Blanditiis iusto possimus officia odio animi repudiandae? Repellendus autem ut soluta facere accusamus magni aut architecto cumque cupiditate. Nostrum officiis, tenetur consequuntur quaerat alias animi debitis? Quae quas placeat iure alias totam quaerat fugit recusandae sed, earum ipsa nihil molestiae quam odit itaque, odio asperiores, mollitia porro ratione tempora laboriosam. Incidunt aliquam nobis sunt ut molestiae nam animi placeat neque vero ratione? Eaque?</p>
+        </section>
+    </main>
+
+    <aside pgs="pageShell-aside">
+        <div pgs="pageShell-aside-scroll">
+            <div pgs="flexColumnTexts">
+                <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Ab modi ut sunt est illum accusantium dolores eum aut cum itaque.</p>
+            </div>
+        </div>
+    </aside>
+</div>
+
+<div pgs="pageShell">
+
+    <main pgs="pageShell-content">
+        <section pgs="flexColumnElements" id="sezione-uno">
+            <strong>Lorem ipsum</strong>
+            <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Quidem dolore veniam nulla hic voluptatum harum illo voluptatem quos. Id quibusdam nemo, mollitia iusto quisquam tenetur doloremque corrupti natus nisi est sed consectetur deserunt? Fugiat consectetur iure aut id voluptate unde autem eius facilis dolorum? Eveniet, sit, excepturi iusto porro eos temporibus illum non ut sunt ex aut earum neque. Iure harum similique autem commodi ratione enim quisquam soluta rem, eius dolor officiis necessitatibus voluptatibus obcaecati vel sint iusto. Eligendi reiciendis aut error rem? Hic aliquid tenetur porro itaque quaerat excepturi consequatur veniam, et alias molestiae, eius odio quae maiores suscipit iure voluptatibus sed dolor facere ipsa quod libero necessitatibus, placeat natus. Doloribus esse nobis culpa ab ut dolorem id expedita nesciunt necessitatibus ipsam natus accusantium eius eveniet eum, distinctio quos modi perspiciatis earum sequi nostrum consequatur quibusdam? Blanditiis iusto possimus officia odio animi repudiandae? Repellendus autem ut soluta facere accusamus magni aut architecto cumque cupiditate. Nostrum officiis, tenetur consequuntur quaerat alias animi debitis? Quae quas placeat iure alias totam quaerat fugit recusandae sed, earum ipsa nihil molestiae quam odit itaque, odio asperiores, mollitia porro ratione tempora laboriosam. Incidunt aliquam nobis sunt ut molestiae nam animi placeat neque vero ratione? Eaque?</p>
+        </section>
+    </main>
+</div>
+```

package/docs/layout/section.md

@@ -0,0 +1,69 @@
+<!-- Automatically generated from templates/html/layout/section.html. Edit templates/html/layout/section.html and run npm run docs:generate again. -->
+
+# Section
+
+Section variants that control width, padding, and specific content treatment while preserving shared vertical spacing.
+
+## PGS
+
+- `section`: identifies the standard section with centered content.
+- `sectionFull`: identifies a section that spans the full available width.
+- `sectionSpecificity`: identifies a section that applies a specific structure to its child.
+- `sectionSpecificity-child`: identifies child content managed by the sectionSpecificity variant.
+- `sectionMax`: identifies a section with an extended maximum width.
+- `sectionNoPadding`: identifies a section without standard padding.
+
+## Related elements
+
+- `flexColumnSections`: vertically spaces all sections in the example.
+- `flexColumnElements`: vertically organizes the main elements of each section.
+- `flexColumnTexts`: organizes and spaces inner content.
+- `card-img`: reuses card image treatment in the demonstration sections.
+- `imgCover`: scales images to the section width.
+
+## Output
+
+HTML collection of the available section variants.
+
+## Example
+
+```html
+<div pgs="flexColumnSections">
+    <section pgs="section flexColumnElements">
+        <div pgs="flexColumnTexts">
+            <strong>Standard section</strong>
+            <p>Centered content inside a MyPGS section.</p>
+        </div>
+    </section>
+
+    <section pgs="sectionFull flexColumnElements">
+        <div pgs="flexColumnTexts">
+            <strong>Full-width section</strong>
+            <p>Centered content inside a MyPGS section.</p>
+        </div>
+    </section>
+
+    <section pgs="sectionSpecificity flexColumnElements">
+        <div pgs="flexColumnTexts">
+            <img pgs="card-img imgCover" src="https://placehold.co/800x200?text=Hero" alt="Placeholder image">
+        </div>
+        <div pgs="sectionSpecificity-child flexColumnTexts">
+            <strong>Specificity-child section</strong>
+            <p>Centered content inside a MyPGS section.</p>
+        </div>
+    </section>
+
+    <section pgs="sectionMax flexColumnElements" style="background-color: var(--color-primary-soft)">
+        <div pgs="flexColumnTexts">
+            <strong>Max-width section</strong>
+            <p>Centered content inside a MyPGS section.</p>
+        </div>
+    </section>
+
+    <section pgs="sectionNoPadding flexColumnElements">
+        <div pgs="flexColumnTexts">
+            <img pgs="card-img imgCover" src="https://placehold.co/800x500?text=HI!" alt="Placeholder image">
+        </div>
+    </section>
+</div>
+```

package/docs/patterns/cookieConsent.md

@@ -0,0 +1,89 @@
+<!-- Automatically generated from templates/html/patterns/cookieConsent.html. Edit templates/html/patterns/cookieConsent.html and run npm run docs:generate again. -->
+
+# Cookie Consent
+
+Accessible pattern for collecting and storing analytics cookie consent, applying preferences, and loading Google Analytics only when authorized.
+
+## PGS
+
+- `cookieConsent`: identifies the main panel initialized by the JavaScript pattern.
+- `cookieConsent-panel`: identifies the configurable preference group.
+- `cookieConsent-featureEssential`: identifies the row of always-active essential cookies.
+- `cookieConsent-panel-badge`: identifies the essential-cookie status indicator.
+- `cookieConsent-featureAnalytics`: identifies the optional analytics-cookie row.
+- `cookieConsent-toggleAnalytics`: identifies the control that enables analytics consent.
+- `cookieConsent-actionReject`: applies selected preferences without automatically accepting analytics.
+- `cookieConsent-actionAccept`: accepts all available cookies.
+- `cookieConsent-actionOpen`: identifies external controls that reopen the preference panel.
+- `cookieConsent-gaUnavailable`: runtime token applied to the root when no usable measurement ID is available.
+- `cookieConsent-accepted`: runtime token applied to the root when analytics is allowed.
+- `cookieConsent-declined`: runtime token applied to the root when analytics is not allowed.
+
+## Related elements
+
+- `flexColumn`: vertically organizes the preference panel.
+- `flexRow`: arranges panel rows and actions.
+- `nowrap`: prevents wrapping in the essential-cookie row.
+- `toggle`: presents analytics consent as a switch.
+- `button`: presents the selection action with standard styling.
+- `buttonStrong`: presents full acceptance as the primary action.
+
+## Output
+
+Consent panel HTML with essential and analytics preferences, actions, and accessible attributes.
+
+## Example
+
+```html
+<section id="pgs-cookieConsent" pgs="cookieConsent" role="dialog" aria-modal="true" data-ga-id="G-XXXXXXXXXX" hidden tabindex="-1">
+    <p><i class="fa-duotone fa-solid fa-cookie-bite"></i> Cookies and privacy <br></p>
+    <h2>Your privacy comes first</h2>
+
+    <p>
+        We use essential cookies to provide the service and, with your consent, analytics cookies from
+        <strong>Google Analytics</strong> to measure traffic anonymously and improve our content.
+        You can change your choice at any time.
+    </p>
+
+    <p>
+        <a href="/privacy-policy/" target="_blank" rel="noopener">Privacy Policy</a> -
+        <a href="/cookie-policy/" target="_blank" rel="noopener">Cookie Policy</a>
+    </p>
+
+    <div pgs="cookieConsent-panel flexColumn" role="group" aria-label="Cookie preferences">
+        <div pgs="flexRow nowrap cookieConsent-featureEssential">
+            <div>
+                <p>
+                    <strong>Essential cookies</strong>
+                    <br>
+                    <small>Always active to ensure the website works correctly.</small>
+                </p>
+            </div>
+
+            <span pgs="cookieConsent-panel-badge">Active</span>
+        </div>
+
+        <div pgs="flexRow cookieConsent-featureAnalytics">
+            <label pgs="toggle">
+                <p>
+                    <strong>Analytics</strong>
+                    <br>
+                    <small>Browsing data collected in aggregate form for anonymous statistics.</small>
+                </p>
+
+                <input type="checkbox" pgs="cookieConsent-toggleAnalytics" aria-label="Enable Google Analytics">
+            </label>
+        </div>
+    </div>
+
+    <div pgs="flexRow">
+        <button type="button" pgs="button cookieConsent-actionReject">
+            <i class="fa-solid fa-duotone fa-sliders"></i>Selected only
+        </button>
+
+        <button type="button" pgs="buttonStrong cookieConsent-actionAccept">
+            <i class="fa-solid fa-check"></i> Accept all
+        </button>
+    </div>
+</section>
+```

package/docs/utilizzo-css-scss.md

@@ -1,6 +1,6 @@
-# Utilizzo CSS/SCSS
+# CSS/SCSS usage
 
-La libreria espone molte custom properties da preferire agli hardcode, per esempio:
+The library exposes many custom properties that should be preferred to hardcoded values, for example:
 
 ```scss
 :root {
@@ -13,7 +13,7 @@ La libreria espone molte custom properties da preferire agli hardcode, per esemp
 }
 ```
 
-Override consigliato:
+Recommended override:
 
 ```scss
 #danger-action {
@@ -22,15 +22,15 @@ Override consigliato:
 }
 ```
 
-Evita di riscrivere da zero padding, gap, border-radius o colori se esiste gia' una variabile o un token PGS adatto.
+Avoid rewriting padding, gaps, border radii, or colors from scratch when a suitable variable or PGS token already exists.
 
-## Il sistema `pgs`
+## The `pgs` system
 
-Il markup usa token separati da spazio dentro l'attributo `pgs`:
+Markup uses space-separated tokens inside the `pgs` attribute:
 
 ```html
-<button pgs="button buttonStrong" type="button">Salva</button>
+<button pgs="button buttonStrong" type="button">Save</button>
 <section pgs="section flexColumnElements"></section>
 ```
 
-Gli stessi token collegano HTML, SCSS e JavaScript.
+The same tokens connect HTML, SCSS, and JavaScript.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mypgs",
-    "version": "1.6.0",
+    "version": "2.1.0",
     "description": "MyPGS frontend theme and UI behaviors, with bundled JavaScript and CSS assets.",
     "main": "./dist/javascript/index.js",
     "module": "./assets/javascript/index.js",
@@ -21,6 +21,7 @@
     },
     "style": "./dist/css/index.css",
     "scripts": {
+        "docs:generate": "node scripts/generate-component-docs.js",
         "start": "webpack",
         "start watch": "webpack --watch",
         "syncmaster-forzato": "git fetch origin && git checkout dev && git pull --rebase origin dev && git rebase origin/master && git push --force-with-lease origin dev && git checkout master && git pull --ff-only origin master && git merge --ff-only dev && git push origin master && git checkout dev",