docs: add/update some doc about hidpi breakpoints

diff --git a/scss/util/_breakpoint.scss b/scss/util/_breakpoint.scss
index ecf159c2de1bd9e2cf2f6a37eafb96ef511e81e0..dff68f50a70b4044fa9b445fae6431f96494d4ff 100644 (file)
--- a/scss/util/_breakpoint.scss
+++ b/scss/util/_breakpoint.scss
@@ -17,6 +17,7 @@ $breakpoints: (
 ) !default;
 
 /// A list of named HiDPI breakpoints. You can use these with the `breakpoint()` mixin to quickly create media queries for resolutions.
+/// Values must represent the device pixels / web pixels ration and be unitless or in DPPX.
 /// @type Map
 $breakpoints-hidpi: (
   hidpi-1: 1,
@@ -74,7 +75,7 @@ $breakpoint-classes: (small medium large) !default;
     @return '(orientation: #{$bp})';
   }
 
-  // If a breakpoint name is given, get its value from the $breakpoints map.
+  // If a breakpoint name is given, get its value from the $breakpoints/$breakpoints-hidpi map.
   @if type-of($bp) == 'string' {
     @if map-has-key($breakpoints, $bp) {
       $name: $bp;
@@ -100,13 +101,13 @@ $breakpoint-classes: (small medium large) !default;
 
   // Only 'only' and 'up' have a min limit.
   @if $dir == 'only' or $dir == 'up' {
-    $bp-min: if($hidpi, $bp, -zf-bp-to-em($bp));
+    $bp-min: if($hidpi, unitless($bp), -zf-bp-to-em($bp));
   }
   // Only 'only' and 'down' have a max limit.
   @if $dir == 'only' or $dir == 'down' {
     // If the breakpoint is a value, use it as max limit.
     @if not $name {
-      $bp-max: if($hidpi, $bp, -zf-bp-to-em($bp));
+      $bp-max: if($hidpi, unitless($bp), -zf-bp-to-em($bp));
     }
     // If the breakpoint is named, the max limit is the following breakpoint - 1px.
     @else if $bp-next {
@@ -131,7 +132,7 @@ $breakpoint-classes: (small medium large) !default;
 }
 
 /// Wraps a media query around the content you put inside the mixin. This mixin accepts a number of values:
-///  - If a string is passed, the mixin will look for it in the `$breakpoints` map, and use a media query there.
+///  - If a string is passed, the mixin will look for it in the `$breakpoints` and `$breakpoints-hidpi` maps, and use a media query there.
 ///  - If a pixel value is passed, it will be converted to an em value using `$global-font-size` as the base.
 ///  - If a rem value is passed, the unit will be changed to em.
 ///  - If an em value is passed, the value will be used as-is.

diff --git a/test/sass/_breakpoint.scss b/test/sass/_breakpoint.scss
index 52480f30658bf50f41f454d1373ef4e7fb27f895..b0799f774327dcf387adeb18cb65db26875d4c4e 100755 (executable)
--- a/test/sass/_breakpoint.scss
+++ b/test/sass/_breakpoint.scss
@@ -59,6 +59,26 @@
 
   // --- Breakpoint: HiDPI/Retina ---
 
+  //
+  // Note for the following "magic numbers":
+  //
+  // We expect maximum values to have 1px less (px it is the most precise web unit we have).
+  // But sinces values are not in pixels, we have to calculate what 1px is in these units.
+  // See https://www.w3.org/TR/css-values-3/#absolute-lengths
+  //
+  // For a x2 resolution (device pixels per web pixels)
+  // 2dppx - 1px
+  // = 2 - (1 / 96)           = 1.98958(...)dppx
+  // = (2 - (1 / 96)) * 72    = 143.25(...)dpi
+  //
+  // For a x3 resolution (device pixels per web pixels)
+  // 3dppx - 1px
+  // = 3 - (1 / 96)           = 2.98958(...)dppx
+  // = (3 - (1 / 96)) * 72    = 215.25(...)dpi
+  //
+  // etc...
+  //
+
   @include test('Breakpoint (Retina) [function]') {
     $expect-2: '(-webkit-min-device-pixel-ratio: 2), (min-resolution: 144dpi)';