gerillass 2.0.1 → 2.1.1

package/scss/library/_line-clamp.scss

@@ -0,0 +1,49 @@
+@charset "UTF-8";
+
+@use "sass:list";
+@use "sass:math";
+@use "sass:meta";
+@use "sass:string";
+
+// True for an unquoted call to one of $names, such as var(--x). A quoted string
+// stays text, so `"var(--x)"` is not a call.
+@function -is-css-function($value, $names) {
+  @if meta.type-of($value) != "string" or string.slice(meta.inspect($value), 1, 1) == "\"" {
+    @return false;
+  }
+  $open: string.index($value, "(");
+  @return $open != null and list.index($names, string.to-lower-case(string.slice($value, 1, $open - 1))) != null;
+}
+
+// Truncates text after a number of lines. `ellipsis` does one line; this does
+// several, and needs five declarations rather than one because -webkit-line-clamp
+// only works alongside two other properties.
+//
+// All five were measured in a browser, on a paragraph that runs to five lines
+// with a clamp of three:
+//
+//   the three together        3 lines, with an ellipsis
+//   without -webkit-box-orient    5 lines, no clamping and no warning
+//   without display: -webkit-box  5 lines, likewise
+//   the standard line-clamp alone 5 lines; it is not Baseline yet
+//   without overflow: hidden      the box is 3 lines, but the rest of the text
+//                                 spills out below it
+//
+// So the standard property is emitted for the future and the prefixed trio is
+// what actually does the work today.
+@mixin line-clamp($lines: 3) {
+  // var() is resolved by the browser, so only a literal count is checked.
+  @if $lines != none and not -is-css-function($lines, "var" "env") {
+    @if meta.type-of($lines) != "number" or not math.is-unitless($lines) {
+      @error "`#{$lines}` is not a valid $lines for `line-clamp`. Pass a whole number of lines, or `none` to undo a clamp.";
+    }
+    @if $lines < 1 or $lines != math.round($lines) {
+      @error "`#{$lines}` is not a valid $lines for `line-clamp`. Pass a whole number of lines that is at least 1, or `none` to undo a clamp.";
+    }
+  }
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: $lines;
+  line-clamp: $lines;
+  overflow: hidden;
+}

package/scss/library/_loadify.scss

@@ -4,6 +4,13 @@
 @use "sass:meta";
 @use "../utilities/is-time" as *;
 
+// `init` defines the %loadify placeholder, and every call extends it. Under the
+// module system a selector can only extend a placeholder from a module it
+// loads, so the file with the call must be the file that calls `init`, or must
+// `@use` it. Anything else fails with "The target selector was not found".
+// An entry file calling `init` does not help a partial it loads, since the
+// partial does not load the entry file. Stylesheets using @import share one
+// scope and are unaffected.
 @mixin loadify($params...) {
   @if not & {
     @if list.length($params) == 0 or (list.length($params) == 1 and list.nth($params, 1) == "init") {
@@ -20,6 +27,17 @@
         backface-visibility: hidden;
         animation-name: loadify;
         animation-fill-mode: forwards;
+
+        // The element starts invisible and the animation is what reveals it,
+        // so switching the animation off is not enough on its own: it would
+        // leave the content hidden for good. Under reduced motion the end
+        // state is applied directly instead, and nothing moves.
+        @media (prefers-reduced-motion: reduce) {
+          opacity: 1;
+          visibility: visible;
+          backface-visibility: visible;
+          animation: none;
+        }
       }
     } @else if (list.length($params) == 1 and list.nth($params, 1) != "init") or (list.length($params) == 1 and meta.type-of(list.nth($params, 1)) != "string") {
       @error "#{list.nth($params, 1)} is not a valid argument. Please pass `init` as an argument to initialize the effect or do not pass any argument at all.";

package/scss/library/_reset-css.scss

@@ -4,10 +4,12 @@
     @if & {
         @error "Please call the mixin at the root of your style sheet.";
     } @else {
-    /* http://meyerweb.com/eric/tools/css/reset/ 
-    v2.0 | 20110126
-    License: none (public domain)
-    */
+    // http://meyerweb.com/eric/tools/css/reset/
+    // v2.0 | 20110126
+    // License: none (public domain)
+    //
+    // Comments in this file are `//`: a /* */ comment inside a mixin is emitted
+    // into the stylesheet of everyone who includes it.
     html, body, div, span, applet, object, iframe,
     h1, h2, h3, h4, h5, h6, p, blockquote, pre,
     a, abbr, acronym, address, big, cite, code,
@@ -28,7 +30,7 @@
       font: inherit;
       vertical-align: baseline;
     }
-    /* HTML5 display-role reset for older browsers */
+    // HTML5 display-role reset for older browsers
     article, aside, details, figcaption, figure, 
     footer, header, hgroup, menu, main, nav, section {
       display: block;

package/scss/library/_screen-agent.scss

@@ -1,6 +1,33 @@
 @charset "UTF-8";
 
+@use "sass:list";
+@use "sass:meta";
+@use "sass:string";
+
+// Returns the first value in $value that holds var(), looking inside lists and
+// calculations, or null. Custom properties are not evaluated in a @media or
+// @container condition, so a rule built from one never applies, and nothing
+// warns. Measured in Chrome 152: `(min-width: var(--wide))` did not match with
+// `--wide: 200px`, while `(min-width: 200px)` did.
+@function -custom-property-in($value) {
+  @each $item in $value {
+    @if meta.type-of($item) == "list" or meta.type-of($item) == "arglist" {
+      $found: -custom-property-in($item);
+      @if $found {
+        @return $found;
+      }
+    } @else if string.index(meta.inspect($item), "var(") {
+      @return $item;
+    }
+  }
+  @return null;
+}
+
 @mixin screen-agent($resolution) {
+  $custom-property: -custom-property-in($resolution);
+  @if $custom-property {
+    @error "`#{$custom-property}` cannot be used as a resolution: custom properties are not evaluated in a @media condition, so the rule would never apply. Pass `1x`, `2x`, `3x` or a resolution such as `2dppx`.";
+  }
   @if $resolution == "1x" {
     @media (min-resolution: 96dpi) {
       @content;

package/scss/library/_text-image.scss

@@ -1,8 +1,31 @@
 @charset "UTF-8";
 
+@use "sass:list";
+@use "sass:meta";
+@use "sass:string";
+
+// An image path goes into url(). A var(), url(), image-set() or gradient is
+// already an image, and wrapping it produced url(var(--x)), which loads nothing.
+@function -image($value) {
+  @if -is-css-function($value, "var" "url" "image-set" "linear-gradient" "radial-gradient" "conic-gradient" "repeating-linear-gradient" "repeating-radial-gradient" "repeating-conic-gradient") {
+    @return $value;
+  }
+  @return url($value);
+}
+
+// True for an unquoted call to one of $names, such as var(--x). A quoted string
+// stays text, so `"var(--x)"` is not a call.
+@function -is-css-function($value, $names) {
+  @if meta.type-of($value) != "string" or string.slice(meta.inspect($value), 1, 1) == "\"" {
+    @return false;
+  }
+  $open: string.index($value, "(");
+  @return $open != null and list.index($names, string.to-lower-case(string.slice($value, 1, $open - 1))) != null;
+}
+
 @mixin text-image($image: null) {
   @if $image {
-    background-image: url($image);
+    background-image: -image($image);
   }
   background-size: cover;
   background-position: center;

package/scss/library/_triangle.scss

@@ -1,13 +1,75 @@
 @charset "UTF-8";
 
 @use "sass:list";
-@use "sass:math";
+@use "sass:meta";
+@use "sass:string";
 @use "../lists/list-of-directions" as *;
-@use "../utilities/is-color" as *;
+
+// A size Sass can use inside calc(): a number, a calculation such as calc(),
+// min() or clamp(), or var() and env(), which only the browser can resolve.
+// Anything else would pass silently through calc(): `calc(nonsense * 5)`
+// compiles.
+@function -is-size($value) {
+  @if meta.type-of($value) == "number" or meta.type-of($value) == "calculation" {
+    @return true;
+  }
+  @if meta.type-of($value) == "string" and string.slice(meta.inspect($value), 1, 1) != "\"" {
+    $open: string.index($value, "(");
+    @return $open != null and list.index("var" "env", string.to-lower-case(string.slice($value, 1, $open - 1))) != null;
+  }
+  @return false;
+}
+
+// A value CSS will take as a colour: a Sass colour, currentColor, or a function
+// that returns a colour when the browser resolves it. A list passes when every
+// item does, as it did through isColor.
+//
+// inherit, initial, unset and revert are left out on purpose. The mixin writes
+// the colour into a border-color shorthand beside `transparent`, and a CSS-wide
+// keyword is only valid as the whole value: `transparent transparent inherit`
+// is rejected by the browser. Checked with CSS.supports in Chrome 152.
+//
+// Deliberately looser than isColor, which stays strict because tint and shade
+// pass its result to color.mix, and that needs a real Sass colour. A border
+// colour does not. The functions are named rather than "anything with a
+// parenthesis", which would let url() through as a colour.
+@function -is-css-color($value) {
+  @if list.length($value) > 1 {
+    @each $item in $value {
+      @if not -is-css-color($item) {
+        @return false;
+      }
+    }
+    @return true;
+  }
+  @if meta.type-of($value) == "color" {
+    @return true;
+  }
+  @if meta.type-of($value) == "string" and string.slice(meta.inspect($value), 1, 1) != "\"" {
+    $text: string.to-lower-case($value);
+    @if $text == "currentcolor" {
+      @return true;
+    }
+    $open: string.index($text, "(");
+    @if $open and list.index("var" "color-mix" "light-dark" "env", string.slice($text, 1, $open - 1)) {
+      @return true;
+    }
+  }
+  @return false;
+}
 
 @mixin triangle($direction: "bottom", $color: black, $size: 10px 8px) {
   @if list.index($list-of-directions, $direction) {
-    @if isColor($color){
+    // Halving a size in calc() rather than math.div() keeps var() and clamp()
+    // working instead of emitting `var(--w)/2`, which is not valid CSS.
+    @each $item in $size {
+      @if not -is-size($item) {
+        @error "`#{meta.inspect($size)}` is not a valid $size for `triangle`. Pass one or two lengths, or var(), env() or a calculation in place of either.";
+      }
+    }
+    @if not -is-css-color($color) {
+      @error "`#{meta.inspect($color)}` is not a valid $color for `triangle`. Pass a colour, `currentColor`, or a CSS function such as `var(--accent)`, `color-mix(...)` or `light-dark(...)`.";
+    } @else {
       content: "";
       height: 0;
       width: 0;
@@ -15,25 +77,25 @@
       border-style: solid;
       @if $direction == "top"{
         border-color: transparent transparent $color;
-        border-width: 0 math.div(list.nth($size, 1), 2) if(list.length($size) == 2, list.nth($size, 2), list.nth($size, 1));
+        border-width: 0 calc(list.nth($size, 1) / 2) if(list.length($size) == 2, list.nth($size, 2), list.nth($size, 1));
       } @else if $direction == "top-right" {
         border-color: transparent $color transparent transparent;
         border-width: 0 list.nth($size, 1) list.nth($size, 1) 0;
       } @else if $direction == "right" {
         border-color: transparent transparent transparent $color;
-        border-width: math.div(if(list.length($size) == 2, list.nth($size, 2), list.nth($size, 1)),  2) 0 math.div(if(list.length($size) == 2, list.nth($size, 2), list.nth($size, 1)), 2) list.nth($size, 1);
+        border-width: calc(if(list.length($size) == 2, list.nth($size, 2), list.nth($size, 1)) / 2) 0 calc(if(list.length($size) == 2, list.nth($size, 2), list.nth($size, 1)) / 2) list.nth($size, 1);
       } @else if $direction == "bottom-right" {
         border-color: transparent transparent $color;
         border-width: 0 0 list.nth($size, 1) list.nth($size, 1);
       } @else if $direction == "bottom" {
         border-color: $color transparent transparent;
-        border-width: if(list.length($size) == 2, list.nth($size, 2), list.nth($size, 1)) math.div(list.nth($size, 1), 2) 0;
+        border-width: if(list.length($size) == 2, list.nth($size, 2), list.nth($size, 1)) calc(list.nth($size, 1) / 2) 0;
       } @else if $direction == "bottom-left" {
         border-color: transparent transparent transparent $color;
         border-width: list.nth($size, 1) 0 0 list.nth($size, 1);
       } @else if $direction == "left" {
         border-color: transparent $color transparent transparent;
-        border-width: math.div(if(list.length($size) == 2, list.nth($size, 2), list.nth($size, 1)), 2) list.nth($size, 1) math.div(if(list.length($size) == 2, list.nth($size, 2), list.nth($size, 1)), 2) 0;
+        border-width: calc(if(list.length($size) == 2, list.nth($size, 2), list.nth($size, 1)) / 2) list.nth($size, 1) calc(if(list.length($size) == 2, list.nth($size, 2), list.nth($size, 1)) / 2) 0;
       } @else if $direction == "top-left" {
         border-color: $color transparent transparent;
         border-width: list.nth($size, 1) list.nth($size, 1) 0 0;

package/scss/utilities/_clear-unit.scss

@@ -1,7 +1,11 @@
 @charset "UTF-8";
 
 @use "sass:math";
+@use "sass:meta";
 
 @function clearUnit($value) {
+  @if meta.type-of($value) != "number" {
+    @error "`#{meta.inspect($value)}` is not a valid $value for `clearUnit`. Pass a number, such as `24px`.";
+  }
   @return math.div($value, ($value * 0 + 1));
 }

package/scss/utilities/_convert-to-em.scss

@@ -2,8 +2,14 @@
 
 @use "sass:string";
 @use "sass:math";
+@use "sass:meta";
 
 @function convertToEm($value) {
+  // Only a pixel length converts cleanly. A unitless number or another unit
+  // compiled to `calc(1.5 / 1px)em`, and a word or var() to `var(--x)/16pxem`.
+  @if meta.type-of($value) != "number" or math.unit($value) != "px" {
+    @error "`#{meta.inspect($value)}` is not a valid $value for `convertToEm`. Pass a pixel length, such as `24px`.";
+  }
   $base-value: 16px;
   $rem-value: math.div($value, $base-value);
   @return $rem-value + string.unquote("em");

package/scss/utilities/_convert-to-number.scss

@@ -11,6 +11,21 @@
   }
 
   $string-numerals: "0" "1" "2" "3" "4" "5" "6" "7" "8" "9";
+
+  // Every character has to be a digit before the parse runs. Otherwise an
+  // empty string or a sign failed with Sass's own "Undefined operation", and a
+  // letter or a space was folded into nonsense such as `40-1`. The empty case
+  // is checked first because `@for $i from 1 through 0` counts down, not zero
+  // times.
+  @if string.length($value) == 0 {
+    @error "`\"\"` is not a valid $value for `convertToNumber`. Pass a string made only of digits, such as `\"42\"`.";
+  }
+  @for $i from 1 through string.length($value) {
+    @if not list.index($string-numerals, string.slice($value, $i, $i)) {
+      @error "`#{meta.inspect($value)}` is not a valid $value for `convertToNumber`. Pass a string made only of digits, such as `\"42\"`.";
+    }
+  }
+
   $calc: 0;
 
   @for $i from 1 through string.length($value) {

package/scss/utilities/_fluid.scss

@@ -0,0 +1,76 @@
+@charset "UTF-8";
+
+@use "sass:list";
+@use "sass:math";
+@use "sass:meta";
+@use "sass:string";
+@use "../utilities/clear-unit" as *;
+@use "../utilities/remify" as *;
+
+// A value that grows with the viewport between two widths, then stops.
+//
+// clamp() takes a floor, a preferred value and a ceiling. The preferred value
+// is the straight line through (min-viewport, min) and (max-viewport, max):
+//
+//   slope     = (max - min) / (max-viewport - min-viewport)
+//   intercept = min - slope * min-viewport
+//   preferred = intercept + slope * 100vw
+//
+// The intercept is emitted in rem rather than px deliberately. A preferred
+// value made only of vw ignores browser zoom, which fails WCAG 1.4.4, and
+// keeping a rem term in the sum is what restores it. This is the part that is
+// easy to get wrong by hand, and the reason this is a function rather than a
+// mixin: the value is the hard part, and it belongs to any property, not just
+// font-size.
+//
+// Sass cannot add rem to vw, so the sum is assembled as a string. CSS evaluates
+// it; Sass only writes it.
+
+$_fluid-root-size: 16px;
+
+@function fluid($min, $max, $min-viewport: 320px, $max-viewport: 1280px) {
+  // Pairs rather than a map: two arguments can legitimately hold the same
+  // length, and a map would reject that as a duplicate key.
+  $given: (($min, "$min"), ($max, "$max"), ($min-viewport, "$min-viewport"), ($max-viewport, "$max-viewport"));
+  @each $pair in $given {
+    $value: list.nth($pair, 1);
+    $label: list.nth($pair, 2);
+    @if meta.type-of($value) != "number" or math.is-unitless($value) {
+      @error "`#{$value}` is not a valid #{$label} for `fluid`. Pass a length in px or rem.";
+    }
+    @if math.unit($value) != "px" and math.unit($value) != "rem" {
+      @error "`#{$value}` is not a valid #{$label} for `fluid`. Pass a length in px or rem, not #{math.unit($value)}.";
+    }
+  }
+
+  // Everything is compared in px, because Sass cannot convert rem to px on its
+  // own: it has no way to know the root font size, so the assumption is stated
+  // here rather than hidden.
+  $min-px: $min;
+  $max-px: $max;
+  $from-px: $min-viewport;
+  $to-px: $max-viewport;
+  @if math.unit($min) == "rem" { $min-px: clearUnit($min) * $_fluid-root-size; }
+  @if math.unit($max) == "rem" { $max-px: clearUnit($max) * $_fluid-root-size; }
+  @if math.unit($min-viewport) == "rem" { $from-px: clearUnit($min-viewport) * $_fluid-root-size; }
+  @if math.unit($max-viewport) == "rem" { $to-px: clearUnit($max-viewport) * $_fluid-root-size; }
+
+  @if $from-px >= $to-px {
+    @error "`fluid` needs $min-viewport to be smaller than $max-viewport, and was given #{$min-viewport} and #{$max-viewport}.";
+  }
+  @if $min-px > $max-px {
+    @error "`fluid` needs $min to be no larger than $max, and was given #{$min} and #{$max}. clamp() would return the floor at every width, so the value would never grow.";
+  }
+
+  $slope: math.div($max-px - $min-px, $to-px - $from-px);
+  $intercept: $min-px - $slope * $from-px;
+
+  // Four decimals is past the point any browser renders differently, and keeps
+  // the output readable.
+  $vw: math.div(math.round($slope * 100 * 10000), 10000);
+  $floor: math.div(math.round(clearUnit(remify($min-px)) * 10000), 10000);
+  $base: math.div(math.round(clearUnit(remify($intercept)) * 10000), 10000);
+  $ceiling: math.div(math.round(clearUnit(remify($max-px)) * 10000), 10000);
+
+  @return string.unquote("clamp(#{$floor}rem, #{$base}rem + #{$vw}vw, #{$ceiling}rem)");
+}

package/scss/utilities/_font-sizer.scss

@@ -1,5 +1,19 @@
 @charset "UTF-8";
 
+@use "sass:math";
+@use "sass:meta";
+
 @function fontSizer($size, $time) {
+  @if meta.type-of($size) != "number" {
+    @error "`#{meta.inspect($size)}` is not a valid $size for `fontSizer`. Pass a length, such as `16px`.";
+  }
+  @if meta.type-of($time) != "number" {
+    @error "`#{meta.inspect($time)}` is not a valid $time for `fontSizer`. Pass a multiplier, such as `1.5`.";
+  }
+  // Two units multiply into a unit squared, which Sass writes as
+  // `calc(16px * 1px)`: not a length anywhere in CSS.
+  @if not math.is-unitless($size) and not math.is-unitless($time) {
+    @error "`fontSizer(#{$size}, #{$time})` multiplies two units, which is not a length. Pass the multiplier without a unit, such as `1.5`.";
+  }
   @return $size * $time;
 }

package/scss/utilities/_index.scss

@@ -5,6 +5,7 @@
 @forward "convert-to-em";
 @forward "convert-to-number";
 @forward "fill-nulls";
+@forward "fluid";
 @forward "font-sizer";
 @forward "font-source";
 @forward "is-color";

package/scss/utilities/_remify.scss

@@ -1,8 +1,15 @@
 @charset "UTF-8";
 
 @use "sass:math";
+@use "sass:meta";
 
 @function remify($value) {
+  // Only a pixel length converts cleanly. Anything else used to reach the
+  // arithmetic unchecked: a word failed with Sass's own "Undefined operation",
+  // and a unitless number or another unit compiled to `calc(1.5rem / 1px)`.
+  @if meta.type-of($value) != "number" or math.unit($value) != "px" {
+    @error "`#{meta.inspect($value)}` is not a valid $value for `remify`. Pass a pixel length, such as `24px`.";
+  }
   $base-value: 16px;
   $rem-value: math.div($value, $base-value);
   @return $rem-value * 1rem;

package/scss/utilities/_validate-length.scss

@@ -6,6 +6,13 @@
 @use "sass:string";
 
 @function validateLength($value) {
+  // null means "leave this out": `position` skips an edge given null, as its
+  // documentation shows. It is not a mistake to warn about, and the warning
+  // printed empty backticks, because null interpolates to nothing.
+  @if $value == null {
+    @return null;
+  }
+
   $keywords: ("auto", "inherit", "initial", "unset", "revert", 0);
 
   @if list.index($keywords, $value) {

package/scss/utilities/_validate-ratio.scss

@@ -28,6 +28,13 @@
     @return $ratio;
   }
 
+  // var() is resolved by the browser. Checked inline rather than through a
+  // helper function, which tools/build-manifest.js would take for this file's
+  // member in place of validateRatio.
+  @if meta.type-of($ratio) == "string" and string.slice(meta.inspect($ratio), 1, 1) != "\"" and string.index(string.to-lower-case($ratio), "var(") == 1 {
+    @return $ratio;
+  }
+
   @if meta.type-of($ratio) == "string" {
     $separator: null;
     @if string.index($ratio, "/") {
@@ -38,8 +45,24 @@
       @error "`#{$ratio}` is not a valid ratio. A string ratio must separate width and height with `/` or `:`, like `\"16/9\"` or `\"16:9\"`.";
     }
 
-    $width: convertToNumber(string.slice($ratio, 1, $separator - 1));
-    $height: convertToNumber(string.slice($ratio, $separator + 1));
+    $width-text: string.slice($ratio, 1, $separator - 1);
+    $height-text: string.slice($ratio, $separator + 1);
+
+    // Checked here so a malformed ratio is reported as a ratio, rather than as
+    // a bad argument to convertToNumber, which the caller never called.
+    @each $part in ($width-text, $height-text) {
+      @if string.length($part) == 0 {
+        @error "`#{$ratio}` is not a valid ratio. Width and height must both be whole numbers, like `\"16/9\"` or `\"16:9\"`.";
+      }
+      @for $i from 1 through string.length($part) {
+        @if not list.index("0" "1" "2" "3" "4" "5" "6" "7" "8" "9", string.slice($part, $i, $i)) {
+          @error "`#{$ratio}` is not a valid ratio. Width and height must both be whole numbers, like `\"16/9\"` or `\"16:9\"`.";
+        }
+      }
+    }
+
+    $width: convertToNumber($width-text);
+    $height: convertToNumber($height-text);
 
     @if $width == 0 {
       @error "`#{$ratio}` is not a valid ratio. The width must be greater than zero.";