mypgs 1.6.0 → 2.1.0

package/docs/components/dropdown.md

@@ -0,0 +1,135 @@
+<!-- Automatically generated from templates/html/components/dropdown.html. Edit templates/html/components/dropdown.html and run npm run docs:generate again. -->
+
+# Dropdown
+
+Popup component that connects a control to content positioned relative to its trigger and handles opening, closing, outside clicks, and Escape.
+
+## PGS
+
+- `dropdown`: identifies the container initialized by the dropdown module.
+- `dropdown-button`: identifies the control that opens or closes the content.
+- `dropdown-content`: identifies the panel positioned relative to the control.
+
+## PGS Options
+
+- `position`: configures the root as position[side alignment]; side accepts top, right, bottom, or left, while compatible alignment values are top, right, bottom, left, or center. The default is bottom center.
+- `buttonReverse`: reverses text and icon on the example buttons and belongs to the button component.
+
+## PGS States
+
+- `open`: indicates that the dropdown is open and its content is visible.
+
+## JavaScript API
+
+- `pgs.dropdown.init(root)`: initializes unregistered dropdowns within the specified Document or Element.
+- `pgs.dropdown.api(element)`: returns the instance associated with an initialized dropdown root.
+- `instance.open()`: opens the dropdown and closes any other open dropdowns.
+- `instance.close()`: closes the current dropdown.
+- `instance.toggle()`: toggles between the open and closed states.
+- `instance.refresh()`: reinitializes the context and recalculates content positioning.
+- `instance.isOpen()`: returns true when the dropdown is open.
+
+## Related elements
+
+- `flexRow`: arranges the placement examples on the same flexible row.
+- `button`: applies standard styling to dropdown controls.
+
+## Output
+
+Series of HTML dropdowns demonstrating the supported placement directions.
+
+## Example
+
+```html
+<div pgs="flexRow">
+
+    <span pgs="dropdown">
+        <button pgs="dropdown-button button" pgs-option="buttonReverse" type="button">
+            Bottom center
+            <i class="fa-solid fa-chevron-down" aria-hidden="true"></i>
+        </button>
+
+        <div pgs="dropdown-content">
+            bottom center content
+        </div>
+    </span>
+
+    <span pgs="dropdown" pgs-option="position[top left]">
+        <button pgs="dropdown-button button" pgs-option="buttonReverse" type="button">
+            Top left
+            <i class="fa-solid fa-chevron-down" aria-hidden="true"></i>
+        </button>
+
+        <div pgs="dropdown-content">
+            top left content
+        </div>
+    </span>
+
+    <span pgs="dropdown" pgs-option="position[top center]">
+        <button pgs="dropdown-button button" pgs-option="buttonReverse" type="button">
+            Top center
+            <i class="fa-solid fa-chevron-down" aria-hidden="true"></i>
+        </button>
+
+        <div pgs="dropdown-content">
+            top center content
+        </div>
+    </span>
+
+    <span pgs="dropdown" pgs-option="position[top right]">
+        <button pgs="dropdown-button button" pgs-option="buttonReverse" type="button">
+            Top right
+            <i class="fa-solid fa-chevron-down" aria-hidden="true"></i>
+        </button>
+
+        <div pgs="dropdown-content">
+            top right content
+        </div>
+    </span>
+
+    <span pgs="dropdown" pgs-option="position[bottom left]">
+        <button pgs="dropdown-button button" pgs-option="buttonReverse" type="button">
+            Bottom left
+            <i class="fa-solid fa-chevron-down" aria-hidden="true"></i>
+        </button>
+
+        <div pgs="dropdown-content">
+            bottom left content
+        </div>
+    </span>
+
+    <span pgs="dropdown" pgs-option="position[bottom right]">
+        <button pgs="dropdown-button button" pgs-option="buttonReverse" type="button">
+            Bottom right
+            <i class="fa-solid fa-chevron-down" aria-hidden="true"></i>
+        </button>
+
+        <div pgs="dropdown-content">
+            bottom right content
+        </div>
+    </span>
+
+    <span pgs="dropdown" pgs-option="position[left center]">
+        <button pgs="dropdown-button button" pgs-option="buttonReverse" type="button">
+            Left center
+            <i class="fa-solid fa-chevron-down" aria-hidden="true"></i>
+        </button>
+
+        <div pgs="dropdown-content">
+            left center content
+        </div>
+    </span>
+
+    <span pgs="dropdown" pgs-option="position[right center]">
+        <button pgs="dropdown-button button" pgs-option="buttonReverse" type="button">
+            Right center
+            <i class="fa-solid fa-chevron-down" aria-hidden="true"></i>
+        </button>
+
+        <div pgs="dropdown-content">
+            right center content
+        </div>
+    </span>
+
+</div>
+```

package/docs/components/form.md

@@ -0,0 +1,136 @@
+<!-- Automatically generated from templates/html/components/form.html. Edit templates/html/components/form.html and run npm run docs:generate again. -->
+
+# Form
+
+Form structure with labels, text fields, a textarea, a checkbox, and a radio group compatible with HTML constraints and custom PGS_formValidate rules.
+
+## PGS
+
+- `form`: identifies the form container and applies the field layout.
+- `formValidate`: enables styles associated with validation states managed by the JavaScript utility.
+- `label`: identifies labels associated with controls.
+- `input`: applies shared styling to text inputs.
+- `textarea`: applies shared styling to the text area.
+- `radio`: styles a group of native radio inputs while preserving their shared name and selection behavior.
+
+## PGS Options
+
+- `message`: defines a field-specific message with the syntax message[Message text].
+- `error`: is applied at runtime to the form and fields that fail validation.
+- `success`: is applied at runtime to the form after successful validation.
+
+## JavaScript API
+
+- `new pgs.formValidate(form, options)`: creates a utility associated directly with the form, automatically adds novalidate, and accepts fieldError, fieldsError, and success in options.message; messages remain editable through instance.message.
+- `instance.validator(callback, eventName)`: intercepts the specified event, prevents its default behavior, validates the form, shows the success message, and invokes callback only when valid; eventName defaults to submit.
+- `instance.validate()`: validates required fields, updates state attributes, and returns true or false.
+- `instance.success(text)`: validates the form and shows a success toast when there are no errors.
+- `instance.addNewRule(rule)`: adds a function that returns one or more invalid fields; validate automatically applies addFieldError to each field.
+- `instance.addFieldError(field, index, total)`: marks a field as invalid; shows the specific message for one error or a summary message for multiple errors.
+- `instance.removeFieldError(field)`: removes the error state from the specified field.
+
+## Related elements
+
+- `buttonStrong`: presents form submission as the primary action.
+- `flexColumnTexts`: spaces text elements in the radio group.
+
+## Output
+
+Complete HTML form with required fields and an example script for a custom rule, validation, and a success message.
+
+## Example
+
+```html
+<form pgs="form formValidate" action="#" method="post">
+    <label pgs="label" for="form-name">
+        Name
+    </label>
+    <input id="form-name" pgs="input" pgs-option="message[Enter your name]" type="text" name="name" placeholder="John Smith" required>
+
+    <label pgs="label" for="form-email">
+        Email
+    </label>
+    <input id="form-email" pgs="input" pgs-option="message[Enter a valid email address]" type="email" name="email" placeholder="name@example.com" required>
+
+    <label pgs="label" for="form-password">
+        Password
+    </label>
+    <input id="form-password" pgs="input" pgs-option="message[Enter a password]" type="password" name="password" autocomplete="new-password" required>
+
+    <label pgs="label" for="form-confirm-password">
+        Confirm password
+    </label>
+    <input id="form-confirm-password" pgs="input" pgs-option="message[Confirm your password]" type="password" name="confirmPassword" autocomplete="new-password" required>
+
+    <label pgs="label" for="form-message">
+        Message
+    </label>
+    <textarea id="form-message" pgs="textarea" name="message" rows="5" placeholder="Write your message" required></textarea>
+
+    <br>
+    <fieldset pgs="radio flexColumnTexts">
+        <legend>Preferred contact method</legend>
+
+        <label>
+            <input type="radio" name="contactMethod" value="email" pgs-option="message[Choose a contact method]" required>
+            <span>Email</span>
+        </label>
+
+        <label>
+            <input type="radio" name="contactMethod" value="phone">
+            <span>Phone</span>
+        </label>
+
+        <label>
+            <input type="radio" name="contactMethod" value="message">
+            <span>Direct message</span>
+        </label>
+    </fieldset>
+    <br>
+
+    <label>
+        <input type="checkbox" name="privacy" required>
+        <span>I accept the privacy policy</span>
+    </label>
+    <br>
+
+    <button pgs="buttonStrong" type="submit">
+        <i class="fa-solid fa-paper-plane" aria-hidden="true"></i>
+        Submit
+    </button>
+</form>
+
+<script type="module">
+    import { pgs } from "mypgs";
+
+    const form = pgs(document).querySelector("form");
+
+    const password = form.querySelector('input[name="password"]');
+    const confirmPassword = form.querySelector('input[name="confirmPassword"]');
+    if (!password || !confirmPassword) return;
+
+    const formValidate = new pgs.formValidate(form, {
+        message: {
+            fieldError: "Please complete this field",
+            fieldsError: "Please complete all required fields",
+            success: "Submitted successfully"
+        }
+    });
+
+    //== new roules
+    formValidate.addNewRule(() => {
+        if (password.value && confirmPassword.value && password.value !== confirmPassword.value) {
+            pgs(confirmPassword).option.setValueBrackets("message", "Passwords do not match");
+            return [confirmPassword, password];
+        }
+    });
+
+    //== validate
+    formValidate.validator(event => {
+        const values = Object.fromEntries(new FormData(form));
+
+        // Replace this log with a request to your backend.
+        console.log(values);
+    }, "submit");
+</script>
+```

package/docs/components/formAddon.md

@@ -0,0 +1,79 @@
+<!-- Automatically generated from templates/html/components/formAddon.html. Edit templates/html/components/formAddon.html and run npm run docs:generate again. -->
+
+# Form Add-ons
+
+Additional form controls for selectable cards, two-state buttons, switches, and compact chip groups.
+
+## PGS
+
+- `checkboxBackground`: presents a checkbox as a selectable container with a highlighted checked state.
+- `twoState`: presents checkbox or radio labels as buttons whose appearance changes when selected.
+- `toggle`: presents a checkbox as a switch with a rail and movable thumb.
+- `chips`: groups twoState controls into a compact segmented selector.
+
+## Related elements
+
+- `flexColumnElements`: vertically arranges the form add-on examples.
+- `flexColumnTexts`: groups each example with its heading and control.
+
+## Output
+
+HTML examples of the checkboxBackground, twoState, toggle, and chips form controls using native checkbox and radio inputs.
+
+## Example
+
+```html
+<div pgs="flexColumnElements">
+    <section pgs="flexColumnTexts">
+        <strong>Checkbox with background</strong>
+
+        <label pgs="checkboxBackground">
+            <input type="checkbox" name="notifications" value="enabled">
+            <span>
+                <strong>Enable notifications</strong><br>
+                Receive important account updates.
+            </span>
+        </label>
+    </section>
+
+    <section pgs="flexColumnTexts">
+        <strong>Two-state controls</strong>
+
+        <label pgs="twoState">
+            <input type="checkbox" name="favorite" value="yes">
+            <i class="fa-solid fa-star" aria-hidden="true"></i>
+            Add to favorites
+        </label>
+    </section>
+
+    <section pgs="flexColumnTexts">
+        <strong>Toggle</strong>
+
+        <label pgs="toggle">
+            <span>Enable dark mode</span>
+            <input type="checkbox" name="darkMode" value="enabled">
+        </label>
+    </section>
+
+    <section pgs="flexColumnTexts">
+        <strong>Chips</strong>
+
+        <div pgs="chips" role="group" aria-label="Select a plan">
+            <label pgs="twoState">
+                <input type="radio" name="plan" value="basic" checked>
+                Basic
+            </label>
+
+            <label pgs="twoState">
+                <input type="radio" name="plan" value="pro">
+                Pro
+            </label>
+
+            <label pgs="twoState">
+                <input type="radio" name="plan" value="enterprise">
+                Enterprise
+            </label>
+        </div>
+    </section>
+</div>
+```

package/docs/components/logo.md

@@ -0,0 +1,36 @@
+<!-- Automatically generated from templates/html/components/logo.html. Edit templates/html/components/logo.html and run npm run docs:generate again. -->
+
+# Logo
+
+Component for displaying a graphical or text logo, with image variants that support dark mode.
+
+## PGS
+
+- `logo`: identifies the brand link container.
+- `logo-image`: identifies the graphical logo image.
+- `logo-text`: identifies the text-based brand variant.
+
+## PGS Options
+
+- `logoDarkmode`: inverts the logo image when the global darkmode state is active.
+- `logoDarkmodeFixed`: keeps the image inversion enabled regardless of the current theme.
+
+## PGS States
+
+- `darkmode`: global document state that activates the logoDarkmode variant.
+
+## Output
+
+HTML examples of the theme-aware graphical logo and the text logo.
+
+## Example
+
+```html
+<a aria-label="Logo" pgs="logo" pgs-option="logoDarkmode" href="/">
+    <img pgs="logo-image" src="https://placehold.co/240x80?text=MyPGS" alt="MyPGS">
+</a>
+
+<a aria-label="Text logo" pgs="logo" href="/">
+    <span pgs="logo-text">MyPGS</span>
+</a>
+```

package/docs/components/menu.md

@@ -0,0 +1,90 @@
+<!-- Automatically generated from templates/html/components/menu.html. Edit templates/html/components/menu.html and run npm run docs:generate again. -->
+
+# Menu
+
+Menu markup, configuration, behavior, and usage example.
+
+## PGS
+
+- `menu`: identifies the menu element used by Menu.
+- `menu-buttonIcon`: identifies the menu-buttonIcon element used by Menu.
+
+## PGS Options
+
+- `horizontal`: identifies the horizontal element used by Menu.
+- `vertical`: identifies the vertical element used by Menu.
+- `menuHeader`: identifies the menuHeader element used by Menu.
+- `position`: identifies the position element used by Menu.
+
+## PGS States
+
+- `open`: identifies the open element used by Menu.
+
+## JavaScript API
+
+- `pgs.menu.init(root)`: initializes matching elements within the specified root.
+- `pgs.menu.api(element)`: returns the instance associated with the specified initialized element.
+- `instance.refresh()`: refreshes the component and returns its updated instance.
+
+## Related elements
+
+- `dropdown`: uses the related dropdown component or utility in this example.
+- `dropdown-button`: uses the related dropdown-button component or utility in this example.
+- `buttonNohover`: uses the related buttonNohover component or utility in this example.
+- `dropdown-content`: uses the related dropdown-content component or utility in this example.
+
+## Output
+
+Complete HTML markup and usage example for Menu.
+
+## Example
+
+```html
+<nav pgs="menu" pgs-option="horizontal" aria-label="Menu orizzontale">
+    <ul>
+        <li>
+            <a href="/" aria-current="page">
+                <i class="fa-solid fa-house" aria-hidden="true"></i>
+                <span>Home</span>
+            </a>
+        </li>
+        <li>
+            <a href="/servizi">
+                <i class="fa-solid fa-layer-group" aria-hidden="true"></i>
+                <span>Servizi</span>
+            </a>
+            <ul>
+                <li><a href="/servizi/uno">Servizio uno</a></li>
+                <li><a href="/servizi/due">Servizio due</a></li>
+            </ul>
+        </li>
+    </ul>
+</nav>
+
+<nav pgs="menu" pgs-option="vertical" aria-label="Menu verticale">
+    <ul>
+        <li>
+            <a href="/" aria-current="page">
+                <i class="fa-solid fa-house" aria-hidden="true"></i>
+                <span>Home</span>
+            </a>
+        </li>
+        <li>
+            <a href="/servizi">
+                <i class="fa-solid fa-layer-group" aria-hidden="true"></i>
+                <span>Servizi</span>
+            </a>
+            <ul>
+                <li><a href="/servizi/uno">Servizio uno</a></li>
+                <li><a href="/servizi/due">Servizio due</a></li>
+            </ul>
+        </li>
+        <li>
+            <a href="/about">
+                <i class="fa-solid fa-info-circle" aria-hidden="true"></i>
+                <span>about</span>
+            </a>
+        </li>
+    </ul>
+</nav>
+```

package/docs/components/modal.md

@@ -0,0 +1,131 @@
+<!-- Automatically generated from templates/html/components/modal.html. Edit templates/html/components/modal.html and run npm run docs:generate again. -->
+
+# Modal
+
+Modal markup, configuration, behavior, and usage example.
+
+## PGS
+
+- `modal`: identifies the modal element used by Modal.
+- `modal-button`: identifies the modal-button element used by Modal.
+- `dialog`: token aggiunto dinamicamente all'elemento dialog inizializzato.
+- `modal-dialog`: identifies the modal-dialog element used by Modal.
+- `modal-dialog-content`: identifies the modal-dialog-content element used by Modal.
+- `modal-dialog-content-header`: identifies the modal-dialog-content-header element used by Modal.
+- `modal-dialog-content-scroll`: identifies the modal-dialog-content-scroll element used by Modal.
+- `modal-close`: identifies the modal-close element used by Modal.
+
+## PGS Options
+
+- `containerID`: identifies the containerID element used by Modal.
+- `containerPGS`: identifies the containerPGS element used by Modal.
+- `disableBackdropClose`: identifies the disableBackdropClose element used by Modal.
+- `history`: identifies the history element used by Modal.
+- `topLevel`: identifies the topLevel element used by Modal.
+- `left`: identifies the left element used by Modal.
+- `right`: identifies the right element used by Modal.
+
+## JavaScript API
+
+- `pgs.modal.init(root)`: initializes matching elements within the specified root.
+- `pgs.modal.api(element)`: returns the instance associated with the specified initialized element.
+- `instance.open()`: opens the component.
+- `instance.close()`: closes the component.
+- `instance.toggle()`: toggles the component state.
+- `instance.refresh()`: refreshes the component and returns its updated instance.
+- `instance.isOpen()`: returns true when the component is open.
+
+## Related elements
+
+- `button`: uses the related button component or utility in this example.
+- `buttonStrong`: uses the related buttonStrong component or utility in this example.
+- `buttonClose`: uses the related buttonClose component or utility in this example.
+- `flexColumnElements`: uses the related flexColumnElements component or utility in this example.
+- `flexRow`: uses the related flexRow component or utility in this example.
+
+## Output
+
+Complete HTML markup and usage example for Modal.
+
+## Example
+
+```html
+<div pgs="modal" pgs-option="containerID[modal-container]">
+    <button pgs="modal-button button" type="button">
+        <i class="fa-solid fa-window-maximize"></i> Open modal
+    </button>
+
+    <dialog>
+        <div pgs="modal-dialog-content">
+            <div pgs="modal-dialog-content-header">
+                <h3>Example modal</h3>
+            </div>
+
+            <div pgs="modal-dialog-content-scroll">
+                <p>Modal content. The close button is added automatically when missing.</p>
+            </div>
+        </div>
+    </dialog>
+</div>
+
+<div pgs="modal" pgs-option="containerID[modal-container]">
+    <button pgs="modal-button button" type="button">
+        <i class="fa-solid fa-window-maximize"></i> Open modal right
+    </button>
+
+    <dialog pgs-option="right">
+        <div pgs="modal-dialog-content">
+            <div pgs="modal-dialog-content-header">
+                <h3>Side modal</h3>
+            </div>
+
+            <div pgs="modal-dialog-content-scroll">
+                <p>Modal content with <code>pgs-option="right"</code>.</p>
+            </div>
+        </div>
+    </dialog>
+</div>
+
+<div pgs="modal" pgs-option="containerID[modal-container]">
+    <button pgs="modal-button button" type="button">
+        <i class="fa-solid fa-window-maximize"></i> Open modal left
+    </button>
+
+    <dialog pgs-option="left">
+        <div pgs="modal-dialog-content">
+            <div pgs="modal-dialog-content-header">
+                <h3>Left-side modal</h3>
+            </div>
+
+            <div pgs="modal-dialog-content-scroll">
+                <p>Modal content with <code>pgs-option="left"</code>.</p>
+            </div>
+        </div>
+    </dialog>
+</div>
+
+<div pgs="modal">
+    <button pgs="modal-button button" type="button">
+        <i class="fa-solid fa-floppy-disk"></i> Confirmation salvataggio
+    </button>
+
+    <dialog pgs-option="topLevel">
+        <div pgs="modal-dialog-content">
+            <div pgs="modal-dialog-content-header">
+                <h3>Save changes?</h3>
+            </div>
+
+            <div pgs="modal-dialog-content-scroll flexColumnElements">
+                <p>You have unsaved changes. Confirm to apply them or cancel to return to the page.</p>
+
+                <div pgs="flexRow">
+                    <button pgs="button modal-close" type="button">Cancel</button>
+                    <button pgs="buttonStrong" type="button">Save changes</button>
+                </div>
+            </div>
+        </div>
+    </dialog>
+</div>
+
+<div id="modal-container"></div>
+```