gerillass 2.0.1 → 2.1.0

package/SKILL.md

@@ -5,7 +5,7 @@ description: Use the Gerillass Sass mixin library — loading it, the mixin cata
 
 # Gerillass
 
-A Sass mixin library: 50 mixins and 22 functions that emit CSS from
+A Sass mixin library: 53 mixins and 23 functions that emit CSS from
 semantic declarations. It is Sass source only — there is no runtime and no
 utility classes, so styles live in your stylesheet and your markup stays clean.
 
@@ -79,10 +79,13 @@ a dropped declaration rather than an error.
 | `breakpointer` | `.a { @include breakpointer(42); }` |
 | `center` | `.modal { @include center(diagonal); }` |
 | `columnizer` | `.grid { @include columnizer(3, 20px, true, 9); }` |
+| `container-query` | `.title { @include container-query("min", 400px, 800px) { color: red; } }` |
+| `container` | `.card { @include container("card", sideways); }` |
 | `escape-to-parent` | `.a { @include escape-to-parent(42) { color: red; } }` |
 | `except` | `.a { @include except(#ff0000) { margin: 0; } }` |
 | `font-face` | `.a { @include font-face("Inter", "/fonts/inter"); }` |
 | `hide` | `.a { @include hide(nonsense); }` |
+| `line-clamp` | `.a { @include line-clamp(0); }` |
 | `linear-gradient` | `.a { @include linear-gradient(sideways, (red, blue)); }` |
 | `loadify` | `@include loadify(nonsense);` |
 | `only` | `.a { @include only(#ff0000) { margin: 0; } }` |
@@ -122,14 +125,17 @@ a dropped declaration rather than an error.
 | `circle($size)` | Square element with a fully rounded border, i.e. a circle. |
 | `clearfix` | Clears floated children using an ::after pseudo-element. |
 | `columnizer($params...)` | Flexbox grid of equal columns, with an optional gutter and fill behaviour. |
+| `container-query($params...)` | A @container rule, taking the same argument shapes as breakpoint so the two read alike. Sizes may be a key from $map-for-breakpoints or a raw length, and a length is the common case because a container is usually narrower than the viewport. Nothing matches at all unless an ancestor was declared with the container mixin. |
+| `container($name: null, $type: inline-size)` | Marks an element as a query container, so container-query can ask about its width instead of the viewport's. The rule that asks has to sit on a descendant: an element is never matched by a @container rule reading its own container, and nothing warns you when it is not. |
 | `counter($params...)` | CSS counter for a list, with optional text before and after the number. |
 | `ellipsis($width: 100%, $display: inline-block)` | Truncates a single line of text with an ellipsis. |
 | `escape-to-parent($selector: null)` | Re-roots the current selector under another one using @at-root. |
 | `except($params...)` | Selects every sibling except the ones named. |
 | `font-face($font-family, $file-path, $font-style: normal, $font-weight: 400, $file-formats: eot woff2 woff ttf svg)` | Emits an @font-face rule for one family across several file formats. Must be called at the root. |
 | `hide($toggle: "hide")` | Visually hides an element while keeping it available to screen readers, or reverses that. |
+| `line-clamp($lines: 3)` | Truncates text after a number of lines, where ellipsis truncates one. It emits five declarations rather than one because -webkit-line-clamp does nothing on its own: without display: -webkit-box or without -webkit-box-orient: vertical the text is not clamped at all and nothing warns you, and without overflow: hidden the clamped text spills out below the box. The unprefixed line-clamp is emitted too, for when it becomes Baseline. |
 | `linear-gradient($direction, $colors)` | Linear gradient background from a direction name or an angle. |
-| `loadify($params...)` | Fades elements in on page load. Call once at the root to set up, then on each element. |
+| `loadify($params...)` | Fades elements in on page load. Call once at the root to set up, then on each element. Under prefers-reduced-motion: reduce the end state is applied directly and no animation runs. Switching the animation off alone would not do, because the element starts invisible and the animation is what reveals it, so the content would stay hidden for good. |
 | `only($params...)` | Selects only the siblings named. |
 | `placeholder-shown` | Styles an input while its placeholder is visible. |
 | `placeholder` | Styles the placeholder text of an input across vendor prefixes. |
@@ -166,6 +172,7 @@ and camelCase is what tells them apart from the kebab-case mixins above.
 | `convertToEm($value)` | Converts a pixel length to em, against a 16px base. |
 | `convertToNumber($value)` | Parses a string of digits into a number. |
 | `fillNulls($value, $seperation: comma, $skip: false)` | Replaces null entries in a list with 0, or drops them. |
+| `fluid($min, $max, $min-viewport: 320px, $max-viewport: 1280px)` | A clamp() value that grows with the viewport between two widths, then stops. The preferred value keeps a rem term rather than being pure vw, because a vw-only value ignores browser text zoom and fails WCAG 1.4.4. It is a function rather than a mixin because the value is the hard part and belongs to any property, not only font-size. |
 | `fontSizer($size, $time)` | Multiplies a size by a factor. Handy for a modular scale. |
 | `fontSource($font-family, $file-path, $file-formats)` | Builds one src entry for an @font-face rule. |
 | `isColor($value)` | Returns the value if every item in it is a colour, and errors otherwise. |

package/gerillass.json

@@ -1,6 +1,6 @@
 {
   "name": "gerillass",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Gerillass is an open-source toolkit that contains a set of Sass mixins to help designers and developers to create better, faster and consistent user interfaces.",
   "homepage": "https://gerillass.com",
   "documentation": "https://docs.gerillass.com",
@@ -571,6 +571,72 @@
         ".grid { @include columnizer(3, nonsense); }"
       ]
     },
+    {
+      "name": "container-query",
+      "kind": "mixin",
+      "arguments": [
+        {
+          "name": "$params",
+          "variadic": true,
+          "accepts": [
+            "a size",
+            "two sizes for a range",
+            "one of min, max, only or between followed by a size",
+            "$name as a keyword, to query one named container"
+          ]
+        }
+      ],
+      "file": "scss/library/_container-query.scss",
+      "signature": "container-query($params...)",
+      "summary": "A @container rule, taking the same argument shapes as breakpoint so the two read alike. Sizes may be a key from $map-for-breakpoints or a raw length, and a length is the common case because a container is usually narrower than the viewport. Nothing matches at all unless an ancestor was declared with the container mixin.",
+      "examples": [
+        ".title { @include container-query(\"min\", 400px) { font-size: 2rem; } }",
+        ".title { @include container-query(\"max\", 399px) { font-size: 1rem; } }",
+        ".title { @include container-query(\"between\", 300px 500px) { color: red; } }",
+        ".title { @include container-query(300px, 500px) { color: red; } }",
+        ".title { @include container-query(\"min\", \"medium\") { color: red; } }",
+        ".title { @include container-query(\"min\", 400px, $name: \"card\") { color: red; } }"
+      ],
+      "rejects": [
+        ".title { @include container-query(\"min\", 400px, 800px) { color: red; } }",
+        ".title { @include container-query(\"min\", 400px, $name: 42) { color: red; } }"
+      ]
+    },
+    {
+      "name": "container",
+      "kind": "mixin",
+      "arguments": [
+        {
+          "name": "$name",
+          "default": "null",
+          "accepts": [
+            "a container name as a string, such as \"card\"",
+            "null for an unnamed container"
+          ]
+        },
+        {
+          "name": "$type",
+          "default": "inline-size",
+          "accepts": [
+            "inline-size",
+            "size",
+            "normal"
+          ]
+        }
+      ],
+      "file": "scss/library/_container.scss",
+      "signature": "container($name: null, $type: inline-size)",
+      "summary": "Marks an element as a query container, so container-query can ask about its width instead of the viewport's. The rule that asks has to sit on a descendant: an element is never matched by a @container rule reading its own container, and nothing warns you when it is not.",
+      "examples": [
+        ".card { @include container(\"card\"); }",
+        ".panel { @include container; }",
+        ".panel { @include container(null, size); }"
+      ],
+      "rejects": [
+        ".card { @include container(\"card\", sideways); }",
+        ".card { @include container(42); }"
+      ]
+    },
     {
       "name": "counter",
       "kind": "mixin",
@@ -749,6 +815,35 @@
         ".a { @include hide(nonsense); }"
       ]
     },
+    {
+      "name": "line-clamp",
+      "kind": "mixin",
+      "arguments": [
+        {
+          "name": "$lines",
+          "default": "3",
+          "accepts": [
+            "a whole number of lines, at least 1",
+            "none, to undo a clamp"
+          ]
+        }
+      ],
+      "file": "scss/library/_line-clamp.scss",
+      "signature": "line-clamp($lines: 3)",
+      "summary": "Truncates text after a number of lines, where ellipsis truncates one. It emits five declarations rather than one because -webkit-line-clamp does nothing on its own: without display: -webkit-box or without -webkit-box-orient: vertical the text is not clamped at all and nothing warns you, and without overflow: hidden the clamped text spills out below the box. The unprefixed line-clamp is emitted too, for when it becomes Baseline.",
+      "examples": [
+        ".excerpt { @include line-clamp(3); }",
+        ".title { @include line-clamp(2); }",
+        ".full { @include line-clamp(none); }",
+        ".default { @include line-clamp; }"
+      ],
+      "rejects": [
+        ".a { @include line-clamp(0); }",
+        ".a { @include line-clamp(2.5); }",
+        ".a { @include line-clamp(3px); }",
+        ".a { @include line-clamp(\"three\"); }"
+      ]
+    },
     {
       "name": "linear-gradient",
       "kind": "mixin",
@@ -796,7 +891,7 @@
       ],
       "file": "scss/library/_loadify.scss",
       "signature": "loadify($params...)",
-      "summary": "Fades elements in on page load. Call once at the root to set up, then on each element.",
+      "summary": "Fades elements in on page load. Call once at the root to set up, then on each element. Under prefers-reduced-motion: reduce the end state is applied directly and no animation runs. Switching the animation off alone would not do, because the element starts invisible and the animation is what reveals it, so the content would stay hidden for good.",
       "examples": [
         "@include loadify(init);\n.a { @include loadify; }",
         "@include loadify;\n.a { @include loadify(0.4s, 1s); }"
@@ -1509,6 +1604,55 @@
         ".a { --x: #{fillNulls(1px null, nonsense)}; }"
       ]
     },
+    {
+      "name": "fluid",
+      "kind": "function",
+      "arguments": [
+        {
+          "name": "$min",
+          "required": true,
+          "accepts": [
+            "a length in px or rem, the value at $min-viewport"
+          ]
+        },
+        {
+          "name": "$max",
+          "required": true,
+          "accepts": [
+            "a length in px or rem, the value at $max-viewport, no smaller than $min"
+          ]
+        },
+        {
+          "name": "$min-viewport",
+          "default": "320px",
+          "accepts": [
+            "a length in px or rem, the width below which the value stops shrinking"
+          ]
+        },
+        {
+          "name": "$max-viewport",
+          "default": "1280px",
+          "accepts": [
+            "a length in px or rem, larger than $min-viewport"
+          ]
+        }
+      ],
+      "file": "scss/utilities/_fluid.scss",
+      "signature": "fluid($min, $max, $min-viewport: 320px, $max-viewport: 1280px)",
+      "summary": "A clamp() value that grows with the viewport between two widths, then stops. The preferred value keeps a rem term rather than being pure vw, because a vw-only value ignores browser text zoom and fails WCAG 1.4.4. It is a function rather than a mixin because the value is the hard part and belongs to any property, not only font-size.",
+      "examples": [
+        ".title { font-size: fluid(24px, 48px); }",
+        ".title { font-size: fluid(1rem, 3rem, 320px, 1200px); }",
+        ".section { padding: fluid(16px, 64px) fluid(8px, 40px); }",
+        ".stack { gap: fluid(0.5rem, 2rem); }"
+      ],
+      "rejects": [
+        ".title { font-size: fluid(16px, 24px, 1280px, 320px); }",
+        ".title { font-size: fluid(40px, 20px); }",
+        ".title { font-size: fluid(16, 24); }",
+        ".title { font-size: fluid(1em, 2em); }"
+      ]
+    },
     {
       "name": "fontSizer",
       "kind": "function",

package/package.json

@@ -16,7 +16,7 @@
     }
   },
   "license": "Apache-2.0",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/selfishprimate/gerillass.git"

package/scss/library/_container-query.scss

@@ -0,0 +1,63 @@
+@charset "UTF-8";
+
+@use "sass:list";
+@use "sass:map";
+@use "sass:meta";
+@use "sass:string";
+@use "../maps/map-for-breakpoints" as *;
+@use "../utilities/validate-breakpoint" as *;
+
+// A @container rule, taking the same argument shapes as `breakpoint` so the two
+// read alike. Sizes may be a key from $map-for-breakpoints or a raw length; a
+// container is usually narrower than the viewport, so a length is the common
+// case.
+//
+// Pass $name to query one named container rather than the nearest ancestor.
+// The container itself is declared with the `container` mixin, on an ancestor
+// of whatever this styles.
+@mixin container-query($params...) {
+  $keywords: meta.keywords($params);
+  $name: map.get($keywords, name);
+  $count: list.length($params);
+
+  @if $name != null and meta.type-of($name) != "string" {
+    @error "`#{$name}` is not a valid $name for `container-query`. Pass a container name as a string, such as `\"card\"`.";
+  }
+
+  $condition: null;
+
+  @if $count == 1 {
+    $condition: "(width: #{validateBreakpoint(list.nth($params, 1))})";
+  } @else if $count == 2 {
+    $mode: list.nth($params, 1);
+    @if not list.index("only" "min" "max" "between", $mode) {
+      // Two bare sizes mean a range, as they do in `breakpoint`.
+      $condition: "(min-width: #{validateBreakpoint($mode)}) and (max-width: #{validateBreakpoint(list.nth($params, 2))})";
+    } @else {
+      $value: list.nth($params, 2);
+      @if $mode == "only" {
+        $condition: "(width: #{validateBreakpoint($value)})";
+      } @else if $mode == "min" {
+        $condition: "(min-width: #{validateBreakpoint($value)})";
+      } @else if $mode == "max" {
+        $condition: "(max-width: #{validateBreakpoint($value)})";
+      } @else {
+        $start: list.nth($value, 1);
+        $end: list.nth($value, 2);
+        $condition: "(min-width: #{validateBreakpoint($start)}) and (max-width: #{validateBreakpoint($end)})";
+      }
+    }
+  } @else {
+    @error "`container-query` takes one or two arguments, and was given #{$count}. Pass a size, two sizes for a range, or one of `min`, `max`, `only` or `between` followed by a size.";
+  }
+
+  @if $name {
+    @container #{string.unquote($name)} #{$condition} {
+      @content;
+    }
+  } @else {
+    @container #{$condition} {
+      @content;
+    }
+  }
+}

package/scss/library/_container.scss

@@ -0,0 +1,26 @@
+@charset "UTF-8";
+
+@use "sass:list";
+@use "sass:meta";
+@use "sass:string";
+
+// Marks an element as a query container, so `container-query` can ask about its
+// width instead of the viewport's.
+//
+// The rule that asks has to sit on a descendant. An element is not matched by a
+// @container rule that reads its own container, and nothing warns you: the rule
+// is simply never applied. Measured in a browser, a 600px element with
+// `container-type: inline-size` on itself did not match `@container (min-width:
+// 400px)`, while the same query did match a child of it.
+@mixin container($name: null, $type: inline-size) {
+  @if not list.index("inline-size" "size" "normal", $type) {
+    @error "`#{$type}` is not a valid $type for `container`. Pass one of: inline-size, size, normal.";
+  }
+  @if $name != null and meta.type-of($name) != "string" {
+    @error "`#{$name}` is not a valid $name for `container`. Pass a name as a string, such as `\"card\"`, or no name at all.";
+  }
+  container-type: $type;
+  @if $name {
+    container-name: string.unquote($name);
+  }
+}

package/scss/library/_index.scss

@@ -19,12 +19,15 @@
 @forward "circle";
 @forward "clearfix";
 @forward "columnizer";
+@forward "container";
+@forward "container-query";
 @forward "counter";
 @forward "ellipsis";
 @forward "escape-to-parent";
 @forward "except";
 @forward "font-face";
 @forward "hide";
+@forward "line-clamp";
 @forward "linear-gradient";
 @forward "loadify";
 @forward "only";

package/scss/library/_line-clamp.scss

@@ -0,0 +1,36 @@
+@charset "UTF-8";
+
+@use "sass:math";
+@use "sass:meta";
+
+// 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) {
+  @if $lines != none {
+    @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

@@ -20,6 +20,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/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/_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";