feat(breakpoints): media query mixin offset options

packages/dnb-design-system-portal/src/docs/uilib/helpers.mdx

@@ -3,16 +3,6 @@ title: 'Helpers'
 description: 'A couple of helper functions used inside of components and extensions.'
 icon: 'helper_classes'
 order: 4
-showTabs: true
-tabs:
-  - title: Info
-    key: /uilib/helpers/info
-  - title: CSS Classes
-    key: /uilib/helpers/classes
-  - title: Functions
-    key: /uilib/helpers/functions
-  - title: Tools
-    key: /uilib/helpers/tools
 redirect_from:
   - /uilib/helper-classes
 ---

packages/dnb-design-system-portal/src/docs/uilib/helpers/classes.mdx

@@ -1,11 +1,12 @@
 ---
-showTabs: true
+title: 'CSS classes'
+order: 1
 ---
 
 import * as Examples from 'Docs/uilib/helpers/Examples'
 import SkipLinkExample from 'Docs/uilib/usage/accessibility/examples/skip-link-example.tsx'
 
-## Description
+## CSS helper classes
 
 Reusing classes in the markup instead of using SCSS extends or _mixins_ will prevent duplication in the `@dnb/eufemia`. So also your application will have good benefits from reusing these helper classes.
 
@@ -145,77 +146,3 @@ text-shadow: none;
 ## HTML class naming
 
 To ensure a consistent class structure and to ensure that the class is owned by the DNB UI Library, all classes in the UI Library are prefixed with `dnb-`. Read more about that in the [Naming conventions](/contribute/naming).
-
-## SASS and mixins
-
-All CSS helper classes are to be found in `src/style/core/helper-classes/helper-classes.scss`
-Most helper classes are SCSS _mixins_ which are then applied to the class when invoked.
-
-You can import Eufemia _mixins_ directly into your SCSS styles:
-
-```scss
-@import '@dnb/eufemia/style/core/utilities.scss';
-
-/** State handling */
-@include hover {
-}
-@include focus {
-}
-@include active {
-}
-
-/** Media Queries and Breakpoints */
-@include allBelow(large) {
-}
-@include allAbove(small) {
-}
-
-/** Screen Reader Only */
-@include srOnly() {
-} // .dnb-sr-only
-
-/** Browser Checks */
-@include IS_EDGE {
-}
-@include IS_FF {
-}
-@include IS_CHROME {
-}
-@include IS_SAFARI_MOBILE {
-}
-@include IS_SAFARI_DESKTOP {
-}
-
-/** Eufemia DropShadow */
-@include defaultDropShadow();
-
-/** Eufemia Border helpers */
-@include focusRing(
-  /* $whatinput: 'keyboard', $color: var(--color-emerald-green), $inset: inset */
-);
-@include extendFocusRing(
-  /* $first-color: null, $second-color: null, width: 0.0625rem */
-);
-@include fakeBorder(
-  /* $color: var(--color-emerald-green), $width: 0.0625rem, $inset: inset */
-);
-
-/** Scroll behavior */
-@include scrollY(/* $mode: scroll */);
-@include scrollX(/* $mode: scroll */);
-@include hideScrollbar();
-@include scrollbarAppearance();
-
-/** Reset fieldset styles */
-@include fieldsetReset();
-```
-
-### Formset reset
-
-Removes default styling on a `fieldset` element.
-
-`@include fieldsetReset($checkSpaceProps: boolean)`
-
-If true is given, it will handle margin gracefully by checking for e.g. `dnb-space__top--` and not reset if this class exists.
-
-<Examples.FormsetReset />

packages/dnb-design-system-portal/src/docs/uilib/helpers/functions.mdx

@@ -1,5 +1,6 @@
 ---
-showTabs: true
+title: 'Functions'
+order: 3
 ---
 
 ## Component helpers

packages/dnb-design-system-portal/src/docs/uilib/helpers/sass.mdx

@@ -0,0 +1,155 @@
+---
+title: 'SASS mixins'
+order: 2
+---
+
+import * as Examples from 'Docs/uilib/helpers/Examples'
+
+# SASS and mixins
+
+All CSS helper classes are to be found in `src/style/core/helper-classes/helper-classes.scss`
+Most helper classes are SCSS _mixins_ which are then applied to the class when invoked.
+
+You can import Eufemia _mixins_ directly into your SCSS styles:
+
+```scss
+@import '@dnb/eufemia/style/core/utilities.scss';
+
+/** State handling */
+@include hover {
+}
+@include focus {
+}
+@include active {
+}
+
+/** 
+ * Media Queries and Breakpoints 
+ * More info can be found in the sections below
+ */
+@include allBelow(large) {
+}
+@include allAbove(small) {
+}
+
+/** Screen Reader Only */
+@include srOnly() {
+} // .dnb-sr-only
+
+/** Browser Checks */
+@include IS_EDGE {
+}
+@include IS_FF {
+}
+@include IS_CHROME {
+}
+@include IS_SAFARI_MOBILE {
+}
+@include IS_SAFARI_DESKTOP {
+}
+
+/** Eufemia DropShadow */
+@include defaultDropShadow();
+
+/** Eufemia Border helpers */
+@include focusRing(
+  /* $whatinput: 'keyboard', $color: var(--color-emerald-green), $inset: inset */
+);
+@include extendFocusRing(
+  /* $first-color: null, $second-color: null, width: 0.0625rem */
+);
+@include fakeBorder(
+  /* $color: var(--color-emerald-green), $width: 0.0625rem, $inset: inset */
+);
+
+/** Scroll behavior */
+@include scrollY(/* $mode: scroll */);
+@include scrollX(/* $mode: scroll */);
+@include hideScrollbar();
+@include scrollbarAppearance();
+
+/** Reset fieldset styles */
+@include fieldsetReset();
+```
+
+## Media queries and Breakpoints
+
+Use the `allAbove` or `allBelow` mixins to add media queries to your css.
+
+```scss
+@import '@dnb/eufemia/style/core/utilities.scss';
+
+@include allBelow(large) {
+}
+
+@include allAbove(small) {
+}
+```
+
+`$breakpoints` is a key-value map containing all the available sizes for media queries
+
+```scss
+@import '@dnb/eufemia/style/core/utilities.scss';
+
+// getting a size from $breakpoints
+div {
+  max-width: map-get($breakpoints, medium);
+}
+```
+
+### Custom offset
+
+You can either change the default value `$breakpoint-offset` (default: 0) from `utilities.scss`, or send in a custom offset to the mixin.
+
+```scss
+@import '@dnb/eufemia/style/core/utilities.scss';
+
+// Change the default offset (default: 0)
+$breakpoint-offset: 10em;
+
+// Will use the new default offset, adding 10em to the size
+@include allBelow(large) {
+}
+
+// You can also simply send in a custom offset
+@include allBelow(large, -5em) {
+}
+```
+
+### Custom size
+
+You can either change the default values in the `$breakpoints` array from `utilities.scss`, or send in a custom size to the mixin.
+
+```scss
+@import '@dnb/eufemia/style/core/utilities.scss';
+
+// Change default sizes
+$breakpoints: map-merge(
+  $breakpints,
+  (
+    // redefine a size
+    'medium': 40em,
+
+    // add an offset to the original value
+    'large': map-get($breakpoints, large) + 5em
+  )
+);
+
+// Will use the new default 'large' size of 90em
+@include allBelow(large) {
+}
+
+// You can also simply send in a custom size
+@include allBelow(90em) {
+}
+```
+
+## `<fieldset>` CSS reset
+
+Removes default styling on a `fieldset` element.
+
+`@include fieldsetReset($checkSpaceProps: boolean)`
+
+If true is given, it will handle margin gracefully by checking for e.g. `dnb-space__top--` and not reset if this class exists.
+
+<Examples.FormsetReset />

packages/dnb-design-system-portal/src/docs/uilib/helpers/tools.mdx

@@ -1,5 +1,6 @@
 ---
-showTabs: true
+title: 'Tools'
+order: 4
 ---
 
 ## Code Editor Extensions

packages/dnb-eufemia/src/style/core/utilities.scss

@@ -286,16 +286,18 @@ $breakpoints: (
   'x-large': 80em /* not documented yet */,
   'xx-large': 90em /* not documented yet */,
 );
+$breakpoint-offset: 0;
 
 // Example usage:
 // @include allAbove(medium){ styles go here.. }
-@mixin allAbove($size) {
-  @media screen and (min-width: if(map-has-key($breakpoints, $size), map-get($breakpoints, $size), #{$size})) {
+// $offset and $list are needed to provide global customization options
+@mixin allAbove($size, $offset: $breakpoint-offset, $list: $breakpoints) {
+  @media screen and (min-width: (if(map-has-key($list, $size), map-get($list, $size), #{$size}) + $offset)) {
     @content;
   }
 }
-@mixin allBelow($size) {
-  @media screen and (max-width: if(map-has-key($breakpoints, $size), map-get($breakpoints, $size), #{$size})) {
+@mixin allBelow($size, $offset: $breakpoint-offset, $list: $breakpoints) {
+  @media screen and (max-width: (if(map-has-key($list, $size), map-get($list, $size), #{$size}) + $offset)) {
     @content;
   }
 }