gerillass 1.6.1 → 2.0.0

package/gerillass.json

@@ -1,6 +1,6 @@
 {
   "name": "gerillass",
-  "version": "1.6.1",
+  "version": "2.0.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",
@@ -140,6 +140,49 @@
         ".a { @include antialias(bogus); }"
       ]
     },
+    {
+      "name": "aspect-ratio",
+      "kind": "mixin",
+      "arguments": [
+        {
+          "name": "$ratio",
+          "default": "null",
+          "accepts": [
+            "a slash separated string, such as \"16/9\"",
+            "a colon separated string, such as \"16:9\"",
+            "a number, where 1.5 means 1.5 / 1",
+            "null for the 16/9 default"
+          ]
+        },
+        {
+          "name": "$fit",
+          "default": "cover",
+          "accepts": [
+            "fill",
+            "contain",
+            "cover",
+            "none",
+            "scale-down",
+            "null to leave object-fit alone"
+          ]
+        }
+      ],
+      "file": "scss/library/_aspect-ratio.scss",
+      "signature": "aspect-ratio($ratio: null, $fit: cover)",
+      "summary": "Holds an element to a ratio and adds what CSS aspect-ratio alone leaves out: object-fit so an image is cropped rather than stretched, and border: 0 so an iframe does not overflow its container by 4px. Apply it to the element itself, not to a wrapper.",
+      "examples": [
+        ".thumb { @include aspect-ratio(\"16:9\"); }",
+        ".video { @include aspect-ratio(\"16/9\"); }",
+        ".tile { @include aspect-ratio(\"1:1\", contain); }",
+        ".plain { @include aspect-ratio(1.5, null); }",
+        ".default { @include aspect-ratio; }"
+      ],
+      "rejects": [
+        ".thumb { @include aspect-ratio(\"16:9\", nonsense); }",
+        ".thumb { @include aspect-ratio(16 9); }",
+        ".thumb { @include aspect-ratio(\"sixteen/nine\"); }"
+      ]
+    },
     {
       "name": "background-dots",
       "kind": "mixin",
@@ -506,8 +549,8 @@
           "name": "$params",
           "variadic": true,
           "accepts": [
-            "a column count",
-            "a column count plus a gutter length",
+            "a column count, which may be a CSS function such as var(--cols)",
+            "a column count plus a gutter length, which may also be a CSS function",
             "a column count plus a boolean fill flag",
             "a column count, a gutter and a fill flag"
           ]
@@ -519,10 +562,13 @@
       "examples": [
         ".grid { @include columnizer(3); }",
         ".grid { @include columnizer(3, 20px); }",
-        ".grid { @include columnizer(3, 20px, true); }"
+        ".grid { @include columnizer(3, 20px, true); }",
+        ".grid { @include columnizer(3, var(--gap)); }",
+        ".grid { @include columnizer(var(--cols)); }"
       ],
       "rejects": [
-        ".grid { @include columnizer(3, 20px, true, 9); }"
+        ".grid { @include columnizer(3, 20px, true, 9); }",
+        ".grid { @include columnizer(3, nonsense); }"
       ]
     },
     {
@@ -876,33 +922,6 @@
         ".a { @include radial-gradient(circle, 42, (red, blue)); }"
       ]
     },
-    {
-      "name": "ratio-box",
-      "kind": "mixin",
-      "arguments": [
-        {
-          "name": "$ratio",
-          "default": "null",
-          "accepts": [
-            "a string such as \"16/9\" or \"16:9\"",
-            "a unitless number such as 1.77",
-            "null for the 16/9 default"
-          ]
-        }
-      ],
-      "file": "scss/library/_ratio-box.scss",
-      "signature": "ratio-box($ratio: null)",
-      "summary": "Container that holds a fixed aspect ratio. Its single direct child is stretched to fill it.",
-      "examples": [
-        ".hero { @include ratio-box(\"16/9\"); }",
-        ".square { @include ratio-box(\"1/1\"); }",
-        ".default { @include ratio-box; }"
-      ],
-      "rejects": [
-        ".hero { @include ratio-box(16 9); }",
-        ".hero { @include ratio-box(16px); }"
-      ]
-    },
     {
       "name": "remove",
       "kind": "mixin",
@@ -996,31 +1015,6 @@
       ],
       "rejects": []
     },
-    {
-      "name": "responsive-video",
-      "kind": "mixin",
-      "arguments": [
-        {
-          "name": "$ratio",
-          "default": "null",
-          "accepts": [
-            "a string such as \"16/9\" or \"16:9\"",
-            "a unitless number",
-            "null for the 16/9 default"
-          ]
-        }
-      ],
-      "file": "scss/library/_responsive-video.scss",
-      "signature": "responsive-video($ratio: null)",
-      "summary": "Wrapper that keeps an embedded video at a fixed aspect ratio.",
-      "examples": [
-        ".video { @include responsive-video(\"16/9\"); }",
-        ".video { @include responsive-video; }"
-      ],
-      "rejects": [
-        ".video { @include responsive-video(16 9); }"
-      ]
-    },
     {
       "name": "scissors",
       "kind": "mixin",
@@ -1395,7 +1389,7 @@
       ]
     },
     {
-      "name": "__clearUnit",
+      "name": "clearUnit",
       "kind": "function",
       "arguments": [
         {
@@ -1407,15 +1401,15 @@
         }
       ],
       "file": "scss/utilities/_clear-unit.scss",
-      "signature": "__clearUnit($value)",
+      "signature": "clearUnit($value)",
       "summary": "Strips the unit off a number, returning it unitless.",
       "examples": [
-        ".a { line-height: __clearUnit(24px); }"
+        ".a { line-height: clearUnit(24px); }"
       ],
       "rejects": []
     },
     {
-      "name": "__clearWhitespace",
+      "name": "clearWhitespace",
       "kind": "function",
       "arguments": [
         {
@@ -1427,17 +1421,17 @@
         }
       ],
       "file": "scss/utilities/_clear-whitespace.scss",
-      "signature": "__clearWhitespace($string)",
+      "signature": "clearWhitespace($string)",
       "summary": "Removes every space from a string.",
       "examples": [
-        ".a { content: __clearWhitespace(\"a b c\"); }"
+        ".a { content: clearWhitespace(\"a b c\"); }"
       ],
       "rejects": [
-        ".a { --x: #{__clearWhitespace(42)}; }"
+        ".a { --x: #{clearWhitespace(42)}; }"
       ]
     },
     {
-      "name": "__convertToEm",
+      "name": "convertToEm",
       "kind": "function",
       "arguments": [
         {
@@ -1449,15 +1443,15 @@
         }
       ],
       "file": "scss/utilities/_convert-to-em.scss",
-      "signature": "__convertToEm($value)",
+      "signature": "convertToEm($value)",
       "summary": "Converts a pixel length to em, against a 16px base.",
       "examples": [
-        ".a { margin: __convertToEm(24px); }"
+        ".a { margin: convertToEm(24px); }"
       ],
       "rejects": []
     },
     {
-      "name": "__convertToNumber",
+      "name": "convertToNumber",
       "kind": "function",
       "arguments": [
         {
@@ -1469,46 +1463,54 @@
         }
       ],
       "file": "scss/utilities/_convert-to-number.scss",
-      "signature": "__convertToNumber($value)",
+      "signature": "convertToNumber($value)",
       "summary": "Parses a string of digits into a number.",
       "examples": [
-        ".a { z-index: __convertToNumber(\"42\"); }"
+        ".a { z-index: convertToNumber(\"42\"); }"
       ],
       "rejects": [
-        ".a { --x: #{__convertToNumber(42)}; }"
+        ".a { --x: #{convertToNumber(42)}; }"
       ]
     },
     {
-      "name": "__darken",
+      "name": "fillNulls",
       "kind": "function",
       "arguments": [
         {
-          "name": "$color",
+          "name": "$value",
           "required": true,
           "accepts": [
-            "a colour"
+            "a list that may contain nulls"
           ]
         },
         {
-          "name": "$percentage",
-          "required": true,
+          "name": "$seperation",
+          "default": "comma",
           "accepts": [
-            "a percentage"
+            "comma",
+            "space"
+          ]
+        },
+        {
+          "name": "$skip",
+          "default": "false",
+          "accepts": [
+            "true to leave nulls in place instead of using 0"
           ]
         }
       ],
-      "file": "scss/utilities/_darken.scss",
-      "signature": "__darken($color, $percentage)",
-      "summary": "Mixes a colour towards black by a percentage.",
+      "file": "scss/utilities/_fill-nulls.scss",
+      "signature": "fillNulls($value, $seperation: comma, $skip: false)",
+      "summary": "Replaces null entries in a list with 0, or drops them.",
       "examples": [
-        ".a { color: __darken(red, 20%); }"
+        ".a { margin: fillNulls(1px null 3px null, space); }"
       ],
       "rejects": [
-        ".a { color: __darken(notacolor, 20%); }"
+        ".a { --x: #{fillNulls(1px null, nonsense)}; }"
       ]
     },
     {
-      "name": "__fontSizer",
+      "name": "fontSizer",
       "kind": "function",
       "arguments": [
         {
@@ -1527,15 +1529,15 @@
         }
       ],
       "file": "scss/utilities/_font-sizer.scss",
-      "signature": "__fontSizer($size, $time)",
+      "signature": "fontSizer($size, $time)",
       "summary": "Multiplies a size by a factor. Handy for a modular scale.",
       "examples": [
-        ".a { font-size: __fontSizer(16px, 1.5); }"
+        ".a { font-size: fontSizer(16px, 1.5); }"
       ],
       "rejects": []
     },
     {
-      "name": "__fontSource",
+      "name": "fontSource",
       "kind": "function",
       "arguments": [
         {
@@ -1561,15 +1563,15 @@
         }
       ],
       "file": "scss/utilities/_font-source.scss",
-      "signature": "__fontSource($font-family, $file-path, $file-formats)",
+      "signature": "fontSource($font-family, $file-path, $file-formats)",
       "summary": "Builds one src entry for an @font-face rule.",
       "examples": [
-        ".a { content: \"#{__fontSource(\"Inter\", \"/fonts/inter\", woff2)}\"; }"
+        ".a { content: \"#{fontSource(\"Inter\", \"/fonts/inter\", woff2)}\"; }"
       ],
       "rejects": []
     },
     {
-      "name": "__isColor",
+      "name": "isColor",
       "kind": "function",
       "arguments": [
         {
@@ -1581,17 +1583,17 @@
         }
       ],
       "file": "scss/utilities/_is-color.scss",
-      "signature": "__isColor($value)",
+      "signature": "isColor($value)",
       "summary": "Returns the value if every item in it is a colour, and errors otherwise.",
       "examples": [
-        ".a { color: __isColor(red); }"
+        ".a { color: isColor(red); }"
       ],
       "rejects": [
-        ".a { color: __isColor(nonsense); }"
+        ".a { color: isColor(nonsense); }"
       ]
     },
     {
-      "name": "__isNumber",
+      "name": "isGutter",
       "kind": "function",
       "arguments": [
         {
@@ -1602,67 +1604,59 @@
           ]
         }
       ],
-      "file": "scss/utilities/_is-number.scss",
-      "signature": "__isNumber($value)",
-      "summary": "Returns the value if it is a number.",
+      "file": "scss/utilities/_is-gutter.scss",
+      "signature": "isGutter($value)",
+      "summary": "True for anything that can sit where a CSS length is expected: a number, a calculation, or a CSS function such as var().",
       "examples": [
-        ".a { z-index: __isNumber(5); }"
+        ".a { --x: #{isGutter(20px)}; }",
+        ".a { --x: #{isGutter(var(--gap))}; }"
       ],
       "rejects": []
     },
     {
-      "name": "__isTime",
+      "name": "isNumber",
       "kind": "function",
       "arguments": [
         {
           "name": "$value",
           "required": true,
           "accepts": [
-            "a duration such as 0.2s or 300ms, or 0"
+            "any value"
           ]
         }
       ],
-      "file": "scss/utilities/_is-time.scss",
-      "signature": "__isTime($value)",
-      "summary": "Returns the value if it is a time in s or ms, and errors otherwise.",
+      "file": "scss/utilities/_is-number.scss",
+      "signature": "isNumber($value)",
+      "summary": "Returns the value if it is a number.",
       "examples": [
-        ".a { animation-duration: __isTime(0.4s); }"
+        ".a { z-index: isNumber(5); }"
       ],
-      "rejects": [
-        ".a { animation-duration: __isTime(400px); }"
-      ]
+      "rejects": []
     },
     {
-      "name": "__lighten",
+      "name": "isTime",
       "kind": "function",
       "arguments": [
         {
-          "name": "$color",
-          "required": true,
-          "accepts": [
-            "a colour"
-          ]
-        },
-        {
-          "name": "$percentage",
+          "name": "$value",
           "required": true,
           "accepts": [
-            "a percentage"
+            "a duration such as 0.2s or 300ms, or 0"
           ]
         }
       ],
-      "file": "scss/utilities/_lighten.scss",
-      "signature": "__lighten($color, $percentage)",
-      "summary": "Mixes a colour towards white by a percentage.",
+      "file": "scss/utilities/_is-time.scss",
+      "signature": "isTime($value)",
+      "summary": "Returns the value if it is a time in s or ms, and errors otherwise.",
       "examples": [
-        ".a { color: __lighten(red, 20%); }"
+        ".a { animation-duration: isTime(0.4s); }"
       ],
       "rejects": [
-        ".a { color: __lighten(notacolor, 20%); }"
+        ".a { animation-duration: isTime(400px); }"
       ]
     },
     {
-      "name": "__mapDeepGet",
+      "name": "mapDeepGet",
       "kind": "function",
       "arguments": [
         {
@@ -1681,52 +1675,15 @@
         }
       ],
       "file": "scss/utilities/_map-deep-get.scss",
-      "signature": "__mapDeepGet($map, $keys...)",
+      "signature": "mapDeepGet($map, $keys...)",
       "summary": "Reads a value out of a nested map by following a chain of keys.",
       "examples": [
-        ".a { height: __mapDeepGet($map-for-tablets, \"iPadPro\", \"height\"); }"
+        ".a { height: mapDeepGet($map-for-tablets, \"iPadPro\", \"height\"); }"
       ],
       "rejects": []
     },
     {
-      "name": "__null",
-      "kind": "function",
-      "arguments": [
-        {
-          "name": "$value",
-          "required": true,
-          "accepts": [
-            "a list that may contain nulls"
-          ]
-        },
-        {
-          "name": "$seperation",
-          "default": "comma",
-          "accepts": [
-            "comma",
-            "space"
-          ]
-        },
-        {
-          "name": "$skip",
-          "default": "false",
-          "accepts": [
-            "true to leave nulls in place instead of using 0"
-          ]
-        }
-      ],
-      "file": "scss/utilities/_null.scss",
-      "signature": "__null($value, $seperation: comma, $skip: false)",
-      "summary": "Replaces null entries in a list with 0, or drops them.",
-      "examples": [
-        ".a { margin: __null(1px null 3px null, space); }"
-      ],
-      "rejects": [
-        ".a { --x: #{__null(1px null, nonsense)}; }"
-      ]
-    },
-    {
-      "name": "__pixelify",
+      "name": "pixelify",
       "kind": "function",
       "arguments": [
         {
@@ -1738,17 +1695,17 @@
         }
       ],
       "file": "scss/utilities/_pixelify.scss",
-      "signature": "__pixelify($value)",
+      "signature": "pixelify($value)",
       "summary": "Returns the value with a px unit, adding one if it is missing.",
       "examples": [
-        ".a { width: __pixelify(24); }"
+        ".a { width: pixelify(24); }"
       ],
       "rejects": [
-        ".a { --x: #{__pixelify(nonsense)}; }"
+        ".a { --x: #{pixelify(nonsense)}; }"
       ]
     },
     {
-      "name": "__pseudoSelector",
+      "name": "pseudoSelector",
       "kind": "function",
       "arguments": [
         {
@@ -1767,15 +1724,15 @@
         }
       ],
       "file": "scss/utilities/_pseudo-selector.scss",
-      "signature": "__pseudoSelector($elements, $pseudo: null)",
+      "signature": "pseudoSelector($elements, $pseudo: null)",
       "summary": "Appends a pseudo-class to every selector in a list.",
       "examples": [
-        ".a { content: \"#{__pseudoSelector((\"button\", \"a\"), \"hover\")}\"; }"
+        ".a { content: \"#{pseudoSelector((\"button\", \"a\"), \"hover\")}\"; }"
       ],
       "rejects": []
     },
     {
-      "name": "__remify",
+      "name": "remify",
       "kind": "function",
       "arguments": [
         {
@@ -1787,15 +1744,44 @@
         }
       ],
       "file": "scss/utilities/_remify.scss",
-      "signature": "__remify($value)",
+      "signature": "remify($value)",
       "summary": "Converts a pixel length to rem, against a 16px root.",
       "examples": [
-        ".a { font-size: __remify(24px); }"
+        ".a { font-size: remify(24px); }"
       ],
       "rejects": []
     },
     {
-      "name": "__shorthandProperty",
+      "name": "shade",
+      "kind": "function",
+      "arguments": [
+        {
+          "name": "$color",
+          "required": true,
+          "accepts": [
+            "a colour"
+          ]
+        },
+        {
+          "name": "$percentage",
+          "required": true,
+          "accepts": [
+            "a percentage"
+          ]
+        }
+      ],
+      "file": "scss/utilities/_shade.scss",
+      "signature": "shade($color, $percentage)",
+      "summary": "Mixes a colour towards black by a percentage.",
+      "examples": [
+        ".a { color: shade(red, 20%); }"
+      ],
+      "rejects": [
+        ".a { color: shade(notacolor, 20%); }"
+      ]
+    },
+    {
+      "name": "shorthandProperty",
       "kind": "function",
       "arguments": [
         {
@@ -1807,17 +1793,46 @@
         }
       ],
       "file": "scss/utilities/_shorthand-property.scss",
-      "signature": "__shorthandProperty($value)",
+      "signature": "shorthandProperty($value)",
       "summary": "Expands one to four values into the four-value CSS shorthand order.",
       "examples": [
-        ".a { margin: __shorthandProperty(10px 20px); }"
+        ".a { margin: shorthandProperty(10px 20px); }"
+      ],
+      "rejects": [
+        ".a { margin: shorthandProperty(1px 2px 3px 4px 5px); }"
+      ]
+    },
+    {
+      "name": "tint",
+      "kind": "function",
+      "arguments": [
+        {
+          "name": "$color",
+          "required": true,
+          "accepts": [
+            "a colour"
+          ]
+        },
+        {
+          "name": "$percentage",
+          "required": true,
+          "accepts": [
+            "a percentage"
+          ]
+        }
+      ],
+      "file": "scss/utilities/_tint.scss",
+      "signature": "tint($color, $percentage)",
+      "summary": "Mixes a colour towards white by a percentage.",
+      "examples": [
+        ".a { color: tint(red, 20%); }"
       ],
       "rejects": [
-        ".a { margin: __shorthandProperty(1px 2px 3px 4px 5px); }"
+        ".a { color: tint(notacolor, 20%); }"
       ]
     },
     {
-      "name": "__validateBreakpoint",
+      "name": "validateBreakpoint",
       "kind": "function",
       "arguments": [
         {
@@ -1829,15 +1844,15 @@
         }
       ],
       "file": "scss/utilities/_validate-breakpoint.scss",
-      "signature": "__validateBreakpoint($value)",
+      "signature": "validateBreakpoint($value)",
       "summary": "Resolves a breakpoint name to its width, passing other values through.",
       "examples": [
-        ".a { width: __validateBreakpoint(\"medium\"); }"
+        ".a { width: validateBreakpoint(\"medium\"); }"
       ],
       "rejects": []
     },
     {
-      "name": "__validateLength",
+      "name": "validateLength",
       "kind": "function",
       "arguments": [
         {
@@ -1849,15 +1864,15 @@
         }
       ],
       "file": "scss/utilities/_validate-length.scss",
-      "signature": "__validateLength($value)",
+      "signature": "validateLength($value)",
       "summary": "Returns the value if it is a length or one of auto, inherit, initial, 0.",
       "examples": [
-        ".a { width: __validateLength(20px); }"
+        ".a { width: validateLength(20px); }"
       ],
       "rejects": []
     },
     {
-      "name": "__validateRatio",
+      "name": "validateRatio",
       "kind": "function",
       "arguments": [
         {
@@ -1871,17 +1886,18 @@
         }
       ],
       "file": "scss/utilities/_validate-ratio.scss",
-      "signature": "__validateRatio($ratio)",
-      "summary": "Turns an aspect ratio into the padding-top percentage that holds it.",
+      "signature": "validateRatio($ratio)",
+      "summary": "Turns an aspect ratio into a value for the CSS aspect-ratio property.",
       "examples": [
-        ".a { padding-top: __validateRatio(\"16/9\"); }"
+        ".a { aspect-ratio: validateRatio(\"16/9\"); }",
+        ".a { aspect-ratio: validateRatio(1.5); }"
       ],
       "rejects": [
-        ".a { padding-top: __validateRatio(16 9); }"
+        ".a { aspect-ratio: validateRatio(16 9); }"
       ]
     },
     {
-      "name": "__validateScissors",
+      "name": "validateScissors",
       "kind": "function",
       "arguments": [
         {
@@ -1893,10 +1909,10 @@
         }
       ],
       "file": "scss/utilities/_validate-scissors.scss",
-      "signature": "__validateScissors($value)",
+      "signature": "validateScissors($value)",
       "summary": "Normalises corner values for the scissors mixin, adding px where missing.",
       "examples": [
-        ".a { content: \"#{__validateScissors(12px)}\"; }"
+        ".a { content: \"#{validateScissors(12px)}\"; }"
       ],
       "rejects": []
     }