@madj2k/fe-frontend-kit 2.0.0

package/readme.md

@@ -0,0 +1,218 @@
+#  @madj2k/frontend-kit
+Reusable frontend toolkit including SCSS mixins and menu components (JS/SCSS).
+
+# #  Installation
+```
+npm install @madj2k/frontend-kit
+```
+Requirements:
+For SCSS mixins: Bootstrap SCSS (your project needs to install bootstrap and include it in the build)
+For menu components: none
+
+## Contains
+* SASS mixins (using Bootstrap 5.3 functions/mixins)
+* Menu components (JS + SCSS), Bootstrap-independent
+* Several JS-Tools
+
+##  Usage in your project
+###  SCSS Mixins
+```
+@use '@madj2k/frontend-kit' as *;
+```
+Or import individual mixins:
+```
+@use '@madj2k/frontend-kit/sass/00_mixins/colors' as *;
+```
+###  Menu components (JS and SCSS):
+Each menu component can be used separately.
+
+# JS: Resize-End
+A lightweight helper class that triggers a debounced 'madj2k-resize-end' event
+when the user finishes resizing the browser window.
+
+It also manages a scrolling detection state (via body attribute) to avoid triggering
+resize-end during user scrolling, and respects active input fields (useful on mobile).
+
+# JS: Scrolling
+A lightweight scrolling helper class that enables:
+1. Body classes based on scroll direction (scroll-up / scroll-down)
+2. Smooth anchor scrolling with optional offset
+3. Automatic scrolling when collapsible elements (like Bootstrap .collapse) open
+4. Appear-on-scroll animations for elements
+
+The class is fully configurable via options and is designed to be used in CMS contexts
+where elements can be added, removed or re-ordered dynamically.
+
+# JS: OWL-Thumbnails
+A JavaScript helper class to create a main OWL carousel with a synchronized thumbnail navigation carousel.
+
+Supports flexible configurations for both the main and the thumbnail carousels,
+including:
+- Custom navigation
+- Syncing main carousel to clicked thumbnails
+- Syncing thumbnails to main carousel changes
+- Optionally equalizing thumbnail heights
+- Optionally preventing the centered thumbnail stage shift (for designs where thumbs should stay left aligned)
+- Responsive and CMS-friendly (works with dynamic content)
+
+This is especially useful for image galleries or product carousels in CMS setups (e.g. TYPO3, WordPress, etc.)
+where content may change dynamically.
+
+# Flyout-Navigation
+## Usage
+Integrate the CSS- and JS-file into your project. Make sure jQuery is included.
+Then init the menu with
+```
+import { Madj2kFlyoutMenu } from '@madj2k/frontend-kit/menus/flyout-menu';
+document.querySelectorAll('.js-flyout-toggle').forEach((el) => {
+  new Madj2kFlyoutMenu(el, { animationDuration: 800 });
+});
+```
+CSS:
+```
+@use '@madj2k/frontend-kit/menus/flyout-menu' as *;
+```
+
+## Basic HTML
+```
+<div class="siteheader" id="siteheader">
+
+    [...]
+
+    <nav>
+        <button class="js-flyout-toggle"
+            aria-label="Open menu"
+            aria-controls="nav-mobile"
+            aria-haspopup="true"
+            aria-expanded="false">
+            <span class="icon-bars"></span>
+        </button>
+        <div class="flyout js-flyout"
+             id="nav-mobile"
+             data-position-ref="siteheader">
+            <div class="flyout-container js-flyout-container">
+                <div class="nav-mobile-inner js-flyout-inner">
+                    CONTENT HERE
+                </div>
+            </div>
+        </div>
+    </nav>
+</div>
+```
+IMPORTANT: If the siteheader is positioned with ```position:fixed```, you have to switch that to ```position:absolute``` when the menu is opened.
+Otherwise in the opened menu the scrolling won't work.
+```
+.flyout-open {
+    .siteheader {
+        position:absolute;
+    }
+}
+```
+## Special: blur/gray effect for background
+* In order to achieve a blur/gray-effect for the background we add the following DIV to the main-content section:
+```
+<div class="background-blur"></div>
+```
+Then we deactivate the fullHeight of the flyout menu and make the blurry background clickable
+```
+import { Madj2kFlyoutdownMenu } from '@madj2k/frontend-kit/menus/flyout-menu';
+document.querySelectorAll('.js-flyout-toggle').forEach((el) => {
+  new Madj2kFlyoutMenu(el, { fullHeight: false });
+});
+document.querySelector('.js-background-blur').addEventListener('click', function() {
+    document.dispatchEvent(new CustomEvent('madj2k-flyoutmenu-close'));
+});
+```
+* And we need this additional CSS:
+```
+/**
+ * Prevent jumping because of scrollbar
+ */
+html,body {
+    min-height: 100.1%;
+}
+
+/**
+ * background-blur for opened flyout
+ */
+.background-blur {
+    position:fixed;
+    top:0;
+    left:0;
+    width: 100%;
+    height: 100%;
+    backdrop-filter: blur(1px) grayscale(100%);
+    background-color: rgba(255, 255, 255, 0.7);
+    transition: opacity 0.3s ease-in-out;
+    opacity:0;
+    z-index:-1;
+}
+
+.flyout-open,
+.flyout-closing {
+    .background-blur {
+        z-index:90;
+    }
+}
+
+.flyout-open{
+    .background-blur {
+        opacity:1;
+    }
+ }
+
+
+```
+
+# Pulldown-Navigation
+## Usage
+Integrate the CSS- and JS-file into your project. Make sure jQuery is included.
+Then init the menu with
+```
+import { Madj2kPulldownMenu } from '@madj2k/frontend-kit/menus/pulldown-menu';
+document.querySelectorAll('.js-pulldown-toggle').forEach((el) => {
+  new Madj2kPulldownMenu(el);
+});
+```
+CSS:
+```
+@use '@madj2k/frontend-kit/menus/pulldown-menu' as *;
+```
+
+## Basic HTML
+```
+<div class="siteheader">
+
+    [...]
+
+    <nav class="pulldown-wrap js-pulldown-wrap">
+        <button class="pulldown-toggle js-pulldown-toggle"
+           aria-label="Open Menu"
+           aria-controls="nav-language"
+           aria-haspopup="true"
+           aria-expanded="false">
+            <span>Menu-Item Level 1</span>
+        </button>
+
+        <div class="pulldown js-pulldown" id="nav-language">
+            <div class="pulldown-inner">
+                <ul>
+                    <!-- used to have the right padding-top of the pulldown -->
+                    <li class="pulldown-hide">
+                        <a href="#" tabIndex="-1"><span>Menu-Item Level 1</span></a>
+                    </li>
+                    <li>
+                        <a href="#"><span>Menu-Item I Level 2</span></a>
+                    </li>
+                    <li>
+                        <a href="#"><span>Menu-Item II Level 2</span></a>
+                    </li>
+                    <li>
+                        ...
+                    </li>
+                </ul>
+            </div>
+        </div>
+    </nav>
+</div>
+```

package/sass/bootstrap-5.3.0/00_mixins/_accessibility.scss

@@ -0,0 +1,42 @@
+/* ==================================================
+* Accessibility
+* ================================================== */
+/// Adds a visible and accessible focus outline for interactive elements.
+///
+/// Ensures that keyboard users can visually identify focused elements
+/// (e.g., buttons, links, inputs) with a strong outline for accessibility.
+/// This mixin is meant to be used on elements that need clear focus styles
+/// without relying on default browser outlines.
+///
+/// @group Accessibility
+///
+/// @param {Color} $color - Outline color for focused state. Defaults to `$color-outline`.
+/// @param {Length} $width - Outline width. Defaults to `3px`.
+///
+/// @example scss
+///   button,
+///   a {
+///     @include accessibility-outline();
+///   }
+///
+/// @example scss
+///   .custom-button {
+///     @include accessibility-outline($color: #005fcc, $width: 2px);
+///   }
+///
+/// @author Steffen Kroggel <developer@steffenkroggel>
+/// @license GNU General Public License v3.0 https://www.gnu.org/licenses/gpl-3.0.en.html
+///
+@mixin accessibility-outline ($color: $color-outline, $width: 3px) {
+
+    &:focus,
+    &:focus-within {
+        outline: 0;
+    }
+
+    &:has(input:focus-visible),
+    &:focus-visible {
+        outline: rem-calc($width) solid $color;
+    }
+
+}

package/sass/bootstrap-5.3.0/00_mixins/_colors.scss

@@ -0,0 +1,99 @@
+/// Generates utility classes for background colors based on a Sass map.
+///
+/// For each key–value pair in the provided map, a class with a suffix of `-<key>`
+/// is created, setting `background-color` to the mapped value.
+///
+/// Typically used in component systems or design tokens to expose theme colors.
+///
+/// @group Utilities
+///
+/// @param {Map} $map - A Sass map of color names and values (e.g. `("primary": #005fcc, "secondary": #999)`). Defaults to `$color-map`.
+///
+/// @example scss
+///   @include background-color-classes((
+///     "primary": #005fcc,
+///     "secondary": #999,
+///     "light": #f5f5f5
+///   ));
+///
+/// @example css
+///   .bg-primary { background-color: #005fcc; }
+///   .bg-secondary { background-color: #999; }
+///
+/// @author Steffen Kroggel <developer@steffenkroggel>
+/// @license GNU General Public License v3.0 https://www.gnu.org/licenses/gpl-3.0.en.html
+///
+@mixin background-color-classes($map: $color-map) {
+    @each $key, $value in $map {
+        &-#{$key} {
+            background-color: $value;
+        }
+
+        @each $breakpoint, $size in $grid-breakpoints {
+            @media (min-width: $size) {
+                &-#{$breakpoint}-#{$key} {
+                    background-color: $value;
+                }
+
+                &-#{$breakpoint}-none {
+                    background-color: transparent;
+                }
+            }
+        }
+    }
+}
+
+/// Generates utility classes for text color based on a Sass map.
+///
+/// For each key–value pair in the provided map, a class with a suffix of `-<key>`
+/// is created, setting the `color` of the element and its immediate children to the mapped value.
+///
+/// Adds `!important` to ensure style application even when overridden.
+///
+/// @group Utilities
+///
+/// @param {Map} $map - A Sass map of color names and values. Defaults to `$color-map`.
+///
+/// @example scss
+///   @include font-color-classes((
+///     "danger": #e00,
+///     "success": #0a0
+///   ));
+///
+/// @example css
+///   .text-danger { color: #e00 !important; }
+///   .text-danger > * { color: #e00 !important; }
+///
+/// @author Steffen Kroggel <developer@steffenkroggel>
+/// @license GNU General Public License v3.0 https://www.gnu.org/licenses/gpl-3.0.en.html
+///
+@mixin font-color-classes($map: $color-map) {
+    @each $key, $value in $map {
+        &-#{$key} {
+            color: $value !important;
+
+            & > * {
+                color: $value !important;
+            }
+        }
+        @each $breakpoint, $size in $grid-breakpoints {
+            @media (min-width: $size) {
+                &-#{$breakpoint}-#{$key} {
+                    color: $value !important;
+
+                    & > * {
+                        color: $value !important;
+                    }
+                }
+
+                &-#{$breakpoint}-none {
+                    color: inherit !important;
+
+                    & > * {
+                        color: inherit !important;
+                    }
+                }
+            }
+        }
+    }
+}

package/sass/bootstrap-5.3.0/00_mixins/_effects.scss

@@ -0,0 +1,45 @@
+/// Adds a custom underline to text elements using a pseudo-element.
+///
+/// This mixin creates a visual underline using `::after`, which allows
+/// for more control than `text-decoration`. It supports customizable
+/// color and thickness, and adjusts vertical spacing responsively.
+///
+/// Useful for link-like text styling or emphasis elements.
+///
+/// @group Effects
+///
+/// @param {Color} $color - The underline color. Default: `$color-primary`.
+/// @param {Length} $width - Thickness of the underline (in px, converted to `rem`). Default: `2px`.
+///
+/// @example scss
+///   .highlighted-text {
+///     @include underline($color-tertiary, 3px);
+///   }
+///
+/// @example css
+///   .highlighted-text::after {
+///     border-bottom: 0.1875rem solid #cc0000;
+///     bottom: -0.09em;
+///   }
+///
+/// @author Steffen Kroggel <developer@steffenkroggel>
+/// @license GNU General Public License v3.0 https://www.gnu.org/licenses/gpl-3.0.en.html
+///
+@mixin underline ($color: $color-primary, $width: 2px) {
+
+    position: relative;
+    display: inline-block;
+
+    &::after {
+        content: '';
+        position: absolute;
+        left: 0;
+        right: 0;
+        bottom: -0.09em;
+        border-bottom: rem-calc($width) solid $color;
+
+        @include media-breakpoint-up(xl) {
+            bottom: -0.15em;
+        }
+    }
+}

package/sass/bootstrap-5.3.0/00_mixins/_flex-box.scss

@@ -0,0 +1,104 @@
+/// Calculates `flex-basis` for a given number of columns while accounting for CSS `gap`.
+///
+/// This mixin ensures that items within a flex container evenly divide available width,
+/// **including** the horizontal `gap` spacing between them.
+/// Ideal for grid-like layouts using `display: flex` and `gap`.
+///
+/// Based on: https://stackoverflow.com/questions/72116170/account-for-gap-when-calculating-flex-basis
+///
+/// @group Layout
+///
+/// @param {Number} $cols - Number of columns (flex items per row). Default: `2`.
+/// @param {Length} $gap - Horizontal gap between items. Default: `16px`.
+/// @return {Declaration} - Sets `flex-basis` using a `calc()` formula.
+///
+/// @example scss
+///   .grid-item {
+///     @include flex-basis(3, 24px);
+///   }
+///
+/// @example css
+///   flex-basis: calc(100% / 3 - 24px / 3 * (3 - 1));
+///
+/// @author Steffen Kroggel <developer@steffenkroggel>
+/// @license GNU General Public License v3.0 https://www.gnu.org/licenses/gpl-3.0.en.html
+///
+@mixin flex-basis($cols: 2, $gap: 16px) {
+    flex-basis: calc(100% / #{$cols} - #{$gap} / #{$cols} * (#{$cols} - 1));
+}
+
+
+/// Flexbox Item Width Generator
+///
+/// Dynamically generates responsive flex item widths based on the number
+/// of items in a container and a column-count configuration map.
+///
+/// This mixin assumes that item widths are calculated using a helper mixin
+/// like `@include flex-basis($columns, $gap)` which distributes space based
+/// on a total column count per row, adjusted for a given gap.
+///
+/// @param {Map} $config - A map where:
+///   - Keys are the total number of items in a row (e.g., 4, 5, 6)
+///   - Values are either:
+///     - A single number: the number of columns for that layout
+///     - A map of item index ranges (e.g., `'1-3'`, `'4-5'`) where each
+///       range defines how many columns those items span in that row
+///
+/// @param {Length} $gap - Optional spacing between columns (default: `0`)
+///
+/// @param {String} $counterClassPrefix - The base class prefix for the container,
+///     e.g. '.items' or '.grid--cols' (default: '.items').
+///
+/// @param {String} $className - The selector for each item (default: '.item')
+///
+/// @example scss - Uniform layout
+///   $layout: (
+///     4: 2, // All 4 items arranged in 2 columns (2 per row)
+///     6: 3  // All 6 items in 3 columns
+///   );
+///
+/// @example scss - Mixed layout with row-specific splits
+///   $layout: (
+///     5: (
+///       '1-3': 3, // First row: 3 columns (items 1–3)
+///       '4-5': 2  // Second row: 2 columns (items 4–5)
+///     )
+///   );
+///
+/// @output
+///   Generates selectors like `.items-5 .item:nth-child(...)` with flex-basis
+///   calculated using the number of columns and the provided gap.
+///
+/// @note
+///   This mixin requires a `flex-basis($columns, $gap)` helper mixin or function
+///   that performs the actual width calculation (e.g., using `calc(...)`)
+///
+/// @author Steffen Kroggel <developer@steffenkroggel>
+/// @license GNU General Public License v3.0 https://www.gnu.org/licenses/gpl-3.0.en.html
+///
+@mixin flex-basis-dynamically($config, $gap: 0, $counterClassPrefix: '.count', $className: '.item') {
+    @each $count, $value in $config {
+        @if type-of($value) == "map" {
+            @each $range, $columns in $value {
+                $start: null;
+                $end: null;
+
+                @if str-index($range, '-') != null {
+                    $start: str-slice($range, 1, str-index($range, '-') - 1);
+                    $end: str-slice($range, str-index($range, '-') + 1);
+                } @else {
+                    $start: $range;
+                    $end: $range;
+                }
+
+                #{$counterClassPrefix}-#{$count} #{$className}:nth-child(n+#{$start}):nth-child(-n+#{$end}) {
+                    @include flex-basis($columns, $gap);
+                }
+            }
+        } @else {
+            #{$counterClassPrefix}-#{$count} #{$className} {
+                @include flex-basis($value, $gap);
+            }
+        }
+    }
+}

package/sass/bootstrap-5.3.0/00_mixins/_form.scss

@@ -0,0 +1,164 @@
+/**! ==================================================
+ * Mixin form fields
+ * ================================================== */
+@use 'sass:math';
+
+/// Styles a custom checkbox input field with accessible markup and visual feedback.
+///
+/// Adds support for background and border color customization, as well as custom icons for
+/// default and active states.
+///
+/// @group Form Fields
+///
+/// @param {Length} $size - The visual size of the checkbox element. Default: `16px`.
+/// @param {Color} $default-bg-color - Background color for default state.
+/// @param {Color} $default-border-color - Border color for default state.
+/// @param {String} $default-icon - Icon shown in default state (optional).
+/// @param {Color} $active-bg-color - Background color for checked/active state.
+/// @param {Color} $active-border-color - Border color for checked/active state.
+/// @param {String} $active-icon - Icon shown when checkbox is checked.
+///
+/// @example scss
+///   .form-check-field:has(input[type="checkbox"]) {
+///     @include checkbox();
+///   }
+///
+/// @example html
+///   <label class="form-check-label" for="element-1">
+///     <span class="form-check-field">
+///       <input class="checkbox" id="element-1" type="checkbox" name="" value="1">
+///     </span>
+///     <span>Label</span>
+///   </label>
+///
+/// @author
+/// Steffen Kroggel <developer@steffenkroggel>
+///
+/// @license
+/// GNU General Public License v3.0 https://www.gnu.org/licenses/gpl-3.0.en.html
+///
+@mixin checkbox(
+    $size: 16px,
+    $default-bg-color: $color-white,
+    $default-border-color: $color-secondary,
+    $default-icon: null,
+    $active-bg-color: $color-primary,
+    $active-border-color: $color-primary,
+    $active-icon: '../Images/input-checkbox-active.svg'
+) {
+    position: relative;
+    display: inline;
+    padding-left: rem-calc(math.ceil(strip-unit($size) * 2 * 0.8));
+
+    input {
+        position: absolute;
+        width: 1em;
+        height: 1em;
+        left: 0;
+        opacity: 0;
+    }
+
+    @include accessibility-outline();
+
+    &::before {
+        content: "";
+        position: absolute;
+        left: rem-calc(0);
+        display: inline-block;
+        width: rem-calc($size);
+        height: rem-calc($size);
+        border: rem-calc(1) solid $default-border-color;
+        margin-top: rem-calc(-3);
+        margin-right: rem-calc(10);
+        background-color: $default-bg-color;
+        background-size: 100%;
+        transform: translateY(4px);
+        border-radius: rem-calc(4);
+
+        @if $default-icon != null {
+            background-image: url(#{$default-icon});
+            background-repeat: no-repeat;
+            background-position: center;
+            background-size: rem-calc(math.ceil(strip-unit($size) * 0.75));
+        }
+    }
+
+    &:has(input:checked),
+    &[aria-selected="true"] {
+        &::before {
+            background-color: $active-bg-color;
+            border-color: $active-border-color;
+            background-image: url(#{$active-icon});
+            background-repeat: no-repeat;
+            background-position: center;
+            background-size: rem-calc(math.ceil(strip-unit($size) * 0.75));
+        }
+    }
+}
+
+
+/// Styles a custom radio input field based on the checkbox mixin.
+///
+/// Builds on the `checkbox()` structure, but renders a circular selection element.
+/// Supports separate border/background/icon definitions for both default and checked state.
+///
+/// @group Form Fields
+///
+/// @param {Length} $size - The visual size of the radio element. Default: `16px`.
+/// @param {Color} $default-bg-color - Background color for default state.
+/// @param {Color} $default-border-color - Border color for default state.
+/// @param {String} $default-icon - Icon shown when radio is not selected (optional).
+/// @param {Color} $active-bg-color - Background color for selected state.
+/// @param {Color} $active-border-color - Border color for selected state.
+/// @param {String} $active-icon - Icon shown when radio is selected.
+///
+/// @example scss
+///   .form-check-field:has(input[type="radio"]) {
+///     @include radio();
+///   }
+///
+/// @example html
+///   <label class="form-check-label" for="element-2">
+///     <span class="form-check-field">
+///       <input class="radio" id="element-2" type="radio" name="options" value="2">
+///     </span>
+///     <span>Label</span>
+///   </label>
+///
+/// @author
+/// Steffen Kroggel <developer@steffenkroggel>
+///
+/// @license
+/// GNU General Public License v3.0 https://www.gnu.org/licenses/gpl-3.0.en.html
+///
+@mixin radio(
+    $size: 16px,
+    $default-bg-color: $color-white,
+    $default-border-color: $color-secondary,
+    $default-icon: null,
+    $active-bg-color: $color-primary,
+    $active-border-color: $color-primary,
+    $active-icon: '../Images/input-radio-active.svg'
+) {
+    @include checkbox(
+            $size,
+            $default-bg-color,
+            $default-border-color,
+            $default-icon,
+            $active-bg-color,
+            $active-border-color,
+            $active-icon
+    );
+
+    &::before {
+        border-radius: rem-calc($size); // circular shape
+    }
+
+    &:has(input:checked),
+    &[aria-selected="true"] {
+        &::before {
+            border: 0;
+            background-size: rem-calc(math.ceil(strip-unit($size) * 0.5));
+        }
+    }
+}