@madj2k/fe-frontend-kit 2.0.31 → 2.0.33

package/index.js

@@ -6,6 +6,7 @@ export { Madj2kResizeEnd } from './tools/resize-end';
 export { Madj2kScrolling } from './tools/scrolling';
 export { Madj2kSimpleFadeSlider } from './tools/simple-fade-slider';
 export { Madj2kToggledOverlay } from './tools/toggled-overlay';
+export { Madj2kElementInViewport } from './tools/element-in-viewport';
 
 // Menus
 export { Madj2kFlyoutMenu } from './menus/flyout-menu';

package/index.scss

@@ -12,3 +12,4 @@
 @forward 'tools/scrolling/index';
 @forward 'tools/simple-fade-slider/index';
 @forward 'tools/toggled-overlay/index';
+@forward 'tools/element-in-viewport/index';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@madj2k/fe-frontend-kit",
-  "version": "2.0.31",
+  "version": "2.0.33",
   "description": "Shared frontend utilities, menus and mixins for projects",
 	"main": "index.js",
 	"style": "index.scss",

package/readme.md

@@ -366,6 +366,52 @@ Usage with Appear-On-Scroll (HTML):
 </div>
 ```
 
+# JS: Element In Viewport
+A lightweight helper class that adds a configurable class to any DOM element once it becomes visible in the viewport.
+Perfect for triggering CSS-based animations (e.g., quote reveals, fade-ins, transitions) when an element enters view.
+* Works with IntersectionObserver API
+* Purely DOM-based (no keyframes required)
+* Fully configurable (threshold, delay, class)
+* Ideal for CMS-driven content (dynamic DOM)
+* Designed for performance and flexibility
+
+Init:
+```
+document.querySelectorAll('.js-inview').forEach((el) => {
+    new Madj2kElementInViewport(el, {
+        visibleClass: 'is-in-viewport',
+        threshold: 0.5,
+        debug: false
+    });
+});
+```
+
+HTML-Example
+```
+<section class="my-element js-inview">
+    <div class="my-element-content">Lorem ipsum dolor sit amet.</div>
+</section>
+```
+
+SCSS-Example
+```
+.my-element {
+    .my-element-content {
+        opacity: 0;
+        transform: translateY(20%);
+        transition: opacity 0.6s ease, transform 0.6s ease;
+    }
+
+    &.is-in-viewport {
+        .my-element-content {
+            opacity: 1;
+            transform: translateY(0);
+        }
+    }
+}
+```
+
+
 # JS: Toggled Overlay
 This class toggles the visibility of any target element referenced by the `aria-controls`
 attribute of a trigger element (button, link, etc.). It manages ARIA attributes for accessibility

package/sass/bootstrap-5.3/10_mixins/_icons.scss

@@ -91,8 +91,12 @@
 ///
 /// @license
 /// GNU General Public License v3.0 https://www.gnu.org/licenses/gpl-3.0.en.html
+/// @deprecated
 ///
 @mixin toggle-icon($selector: '.toggle') {
+
+    @warn "toggle-icon() is deprecated. Use toggle() instead.";
+
     #{$selector}:has(.icon:first-child) {
         line-height: 1; // icon-only toggle buttons
     }

package/sass/bootstrap-5.3/10_mixins/_nav.scss

@@ -250,6 +250,12 @@
     align-items: center;
     gap: rem-calc($gap);
     height: 100%;
+
+    @warn "nav-toggle-group() is deprecated. Use toggle-group() instead.";
+
+    @include toggle-group(
+        $gap: $gap,
+    );
 }
 
 
@@ -309,49 +315,13 @@
         "icon-plus": unquote('"\\e908"')
     )
 ) {
-    background-color: transparent;
-    border: 0;
-    margin: 0;
-    padding: 0;
-
-    &:has(.nav-toggle-icon) {
-        display: flex;
-        align-items: center;
-
-        // variant with icons as font
-        &[aria-expanded="true"] {
-            @each $icon-class, $content in $icon-mappings {
-                .#{$icon-class} {
-                    &:before {
-                        content: $content;
-                    }
-                }
-            }
-        }
-
-        // variant with icons in a sprite
-        .nav-toggle-icon-opened {
-            display: none;
-        }
-
-        &[aria-expanded="true"] {
-            .nav-toggle-icon-opened {
-                display: inline-block;
-            }
-            .nav-toggle-icon-closed {
-                display: none;
-            }
-        }
-    }
 
-    &-icon:not(:has(svg)),
-    &-icon svg {
-        font-size: rem-calc($icon-size);
-        width: rem-calc($icon-size);
-        color: $icon-color;
-    }
+    @warn "nav-toggle() is deprecated. Use toggle() instead.";
 
-    &-icon svg {
-        height: 100%;
-    }
+    @include toggle(
+        $icon-size: $icon-size,
+        $icon-color: $icon-color,
+        $icon-mappings: $icon-mappings,
+        $icon-selector: '.nav-toggle-icon'
+    );
 }

package/sass/bootstrap-5.3/10_mixins/_section.scss

@@ -43,6 +43,15 @@
 ///     [...]
 ///   </div>
 ///
+/// @example html
+///   <div class="csp-section">
+///     [...]
+///   </div>
+///   <!-- With vertical padding instead of margin -->
+///   <div class="csp-section csp-section-padding">
+///     [...]
+///   </div>
+///
 /// @example scss
 ///   .layout-default {
 ///     @include section-spacing();
@@ -56,6 +65,7 @@
     $block-class: 'csp-block',
     $not-last-class: 'csp-not-last',
     $utility-append-class: 'sp',
+    $padding-append-class: 'padding',
     $csp-blocks: (
         'text',
         'text-image',
@@ -101,9 +111,17 @@
             }
 
             .#{$section-class}.#{$not-last-class}:not(:has(+ .#{$section-class})),
+            .#{$section-class}.#{$section-class}-#{$padding-append-class},
+            .#{$section-class}:has(+ .#{$section-class}-#{$padding-append-class}),
             .#{$section-class}-#{$utility-append-class}.#{$not-last-class}:not(:has(+ .#{$section-class})) {
                 margin-bottom: 0;
             }
+
+            .#{$section-class}-#{$padding-append-class},
+            .#{$section-class}-#{$padding-append-class}-#{$utility-append-class} {
+                padding-top: rem-calc($spacer-section);
+                padding-bottom: rem-calc($spacer-section);
+            }
         }
 
         // block-spacing

package/sass/bootstrap-5.3/10_mixins/_toggle.scss

@@ -0,0 +1,141 @@
+
+/* ==================================================
+* Toggle
+* ==================================================*/
+/// Creates a button group container for toggles.
+///
+/// Used to align toggle buttons and icons horizontally with spacing.
+/// Useful in responsive navigation headers.
+///
+/// @group Toggle
+///
+/// @param {Length} $gap - The spacing between toggle elements. Defaults to `$spacer`.
+///
+/// @example html
+///   <div class="toggle-group">
+///     <button class="toggle" aria-expanded="false">
+///       <i class="toggle-icon icon-hamburger"></i>
+///     </button>
+///   </div>
+///
+/// @example scss
+///   .toggle-group {
+///     @include toggle-group($gap: 1rem);
+///   }
+///
+/// @author Steffen Kroggel <developer@steffenkroggel>
+/// @license GNU General Public License v3.0 https://www.gnu.org/licenses/gpl-3.0.en.html
+///
+@mixin toggle-group(
+    $gap: 16px
+) {
+    display: flex;
+    align-items: center;
+    gap: rem-calc($gap);
+    height: 100%;
+}
+
+
+/// Creates a button element for toggling.
+///
+/// Features:
+/// - Accessible button with `aria-expanded` state
+/// - Icon switching based on toggle state (e.g., hamburger to close)
+/// - Configurable icon size and colors
+/// - No default background or borders for flexible styling
+/// - Built-in accessibility outline
+///
+/// @group Toggle
+///
+/// @param {Length} $icon-size - Size of the icon (width/height). Defaults to `$spacer`.
+/// @param {Color} $icon-color - Icon color (e.g., fill or text color). Defaults to `$color-primary`.
+/// @param {Map} $icon-mappings - Map of icon toggle states (e.g., hamburger → close). Defaults to a predefined map.
+///
+/// @example html with icon font
+///   <button class="toggle" aria-expanded="false">
+///     <i class="toggle-icon icon-hamburger icon"></i>
+///   </button>
+///
+/// @example html with icon sprite
+///   <button class="toggle" aria-expanded="false">
+///     <i class="toggle-icon">
+///         <svg class="toggle-icon-opened" aria-hidden="true" focusable="false">
+///             <use href="sprite.svg#search"></use>
+///         </svg>
+///         <svg class="toggle-icon-closed" aria-hidden="true" focusable="false">
+///             <use href="sprite.svg#close"></use>
+///         </svg>
+///     </i>
+///   </button>
+///
+///
+/// @example scss
+///   .toggle {
+///     @include toggle(
+///       $icon-size: 1.5rem,
+///       $icon-color: #333,
+///       $icon-mappings: (
+///         "icon-hamburger": "icon-close",
+///         "icon-plus": "icon-minus"
+///       )
+///     );
+///   }
+///
+/// @author Steffen Kroggel <developer@steffenkroggel>
+/// @license GNU General Public License v3.0 https://www.gnu.org/licenses/gpl-3.0.en.html
+///
+@mixin toggle(
+    $icon-size: 16px,
+    $icon-color: var(--bs-primary),
+    $icon-mappings: (
+        "icon-hamburger": unquote('"\\e905"'),
+        "icon-plus": unquote('"\\e908"')
+    ),
+    $icon-selector: '.toggle-icon'
+) {
+    background-color: transparent;
+    border: 0;
+    margin: 0;
+    padding: 0;
+
+    &:has(#{$icon-selector}) {
+        display: flex;
+        align-items: center;
+
+        // variant with icons as font
+        &[aria-expanded="true"] {
+            @each $icon-class, $content in $icon-mappings {
+                .#{$icon-class} {
+                    &:before {
+                        content: $content;
+                    }
+                }
+            }
+        }
+
+        // variant with icons in a sprite
+        #{$icon-selector}-opened {
+            display: none;
+        }
+
+        &[aria-expanded="true"] {
+            #{$icon-selector}-opened {
+                display: inline-block;
+            }
+            #{$icon-selector}-closed {
+                display: none;
+            }
+        }
+    }
+
+    #{$icon-selector}:not(:has(svg)),
+    #{$icon-selector} svg {
+        font-size: rem-calc($icon-size);
+        width: rem-calc($icon-size);
+        color: $icon-color;
+    }
+
+    #{$icon-selector} svg {
+        height: 100%;
+    }
+}

package/sass/bootstrap-5.3/10_mixins/index.scss

@@ -7,5 +7,6 @@
 @import './nav';
 @import './page';
 @import './section';
+@import './toggle';
 @import './toggle-list';
 @import './unit';

package/tools/element-in-viewport/element-in-viewport-2.0.js

@@ -0,0 +1,117 @@
+/**
+ * Madj2kElementInViewport
+ *
+ * Adds a CSS class to any DOM element once it becomes fully (or partially) visible
+ * in the viewport using the IntersectionObserver API.
+ *
+ * - Purely CSS-triggered transitions via class
+ * - Reusable for any type of element (quotes, sections, etc.)
+ * - Fully configurable: class name, threshold, delay
+ * - Designed for CMS contexts with dynamically loaded content
+ *
+ * @author Steffen Kroggel <developer@steffenkroggel.de>
+ * @copyright 2025 Steffen Kroggel
+ * @version 1.0.0
+ * @license GNU General Public License v3.0
+ * @see https://www.gnu.org/licenses/gpl-3.0.en.html
+ *
+ * @example
+ * // Single element with defaults
+ * const el = document.querySelector('.js-animate-in');
+ * new Madj2kElementInViewport(el);
+ *
+ * @example
+ * // Single element with custom config
+ * new Madj2kElementInViewport(el, {
+ *   visibleClass: 'is-visible',
+ *   threshold: 0.75,
+ *   delay: 200,
+ *   debug: true
+ * });
+ *
+ * @example
+ * // Multiple elements
+ * document.querySelectorAll('.js-element-in-viewport').forEach((el) => {
+ *   new Madj2kElementInViewport(el, {
+ *     visibleClass: 'is-in-viewport',
+ *     threshold: 1
+ *   });
+ * });
+ */
+
+class Madj2kElementInViewport {
+  config = {
+    visibleClass: 'is-in-viewport',
+    threshold: 0.5,
+    delay: 0,
+    debug: false
+  };
+
+  /**
+   * @param {HTMLElement} element - DOM element to observe
+   * @param {Object} config - configuration options
+   * @param {string} [config.visibleClass='in-viewport'] - class to apply when element is in view
+   * @param {number} [config.threshold=1.0] - how much of the element must be visible (0–1)
+   * @param {number} [config.delay=0] - optional delay before applying class (in ms)
+   * @param {boolean} [config.debug=false] - enable debug logs
+   */
+  constructor(element, config = {}) {
+    if (!(element instanceof HTMLElement)) {
+      console.warn('[Madj2kElementInViewport] No valid element provided.');
+      return;
+    }
+
+    this.element = element;
+    this.config = { ...this.config, ...config };
+
+    this._log('Initialized with config:', this.config);
+    this._observe();
+  }
+
+  /**
+   * Initializes the IntersectionObserver
+   * @private
+   */
+  _observe() {
+    const observer = new IntersectionObserver(
+      ([entry], observerInstance) => {
+        if (entry.isIntersecting && entry.intersectionRatio >= this.config.threshold) {
+          this._log('Element in viewport:', this.element);
+
+          if (this.config.delay > 0) {
+            setTimeout(() => this._activate(observerInstance), this.config.delay);
+          } else {
+            this._activate(observerInstance);
+          }
+        }
+      },
+      {
+        threshold: this.config.threshold
+      }
+    );
+
+    observer.observe(this.element);
+  }
+
+  /**
+   * Applies the visible class and stops observing
+   * @param {IntersectionObserver} observer
+   * @private
+   */
+  _activate(observer) {
+    this.element.classList.add(this.config.visibleClass);
+    observer.unobserve(this.element);
+    this._log(`Class "${this.config.visibleClass}" added.`);
+  }
+
+  /**
+   * Logs debug messages
+   * @param  {...any} args
+   * @private
+   */
+  _log(...args) {
+    if (this.config.debug) {
+      console.log('[Madj2kElementInViewport]', ...args);
+    }
+  }
+}

package/tools/element-in-viewport/index.js

@@ -0,0 +1,2 @@
+import Madj2kElementInViewport from './element-in-viewport-2.0';
+export { Madj2kElementInViewport };

package/tools/element-in-viewport/index.scss

@@ -0,0 +1 @@
+@forward './element-in-viewport-2.0';