gerillass 1.6.2 → 2.0.0

package/README.md

@@ -32,7 +32,7 @@ Hope you’ll enjoy using it!
   - [Cloning the Repository from Github](#cloning-the-repository-from-github)
   - [Versions these examples were tested with](#versions-these-examples-were-tested-with)
 - [Using Gerillass with an AI coding agent](#using-gerillass-with-an-ai-coding-agent)
-- [Namespace Usage](#namespace-usage)
+- [Three ways to call the same mixin](#three-ways-to-call-the-same-mixin)
 - [Vendor Prefix Support](#vendor-prefix-support)
 - [Experimenting](#experimenting)
 - [Testing](#testing)
@@ -79,7 +79,6 @@ Pointing straight at the file always works too:
 
 The per-tool recipes below were each verified against a real build of Gerillass v1.5.0. The versions used are listed at the end of this section.
 
-> **A note on eyeglass.** Gerillass still ships eyeglass module metadata, but eyeglass has not been released since June 2022 and its importer is broken with current Dart Sass — any `@import` fails with `doneImporting is not a function`, whether Gerillass is involved or not. It also relies on the legacy JS API, which Dart Sass removes in 2.0.0. Use the `pkg:` importer above instead; it is the built-in equivalent.
 
 ### Using with Vite
 
@@ -205,9 +204,26 @@ Otherwise, point your agent at the file and it will read it as plain Markdown.
 Neither file is generated by hand: signatures are parsed from the Sass sources, and every example and refusal in the manifest is executed by the test suite. What the manifest says the library does is what the library does.
 
 
-## Namespace Usage
+## Three ways to call the same mixin
 
-You can use Gerillass with or without `gls-` namespace. It is optional, but I strongly recommend you to use it to prevent having conflicts with other Sass libraries or frameworks like Bootstrap.
+None of them is required — pick whichever reads best in your project, and stay with it in a given file.
+
+**Bare.** The shortest, and fine unless another library defines the same name.
+
+    @use 'gerillass' as *;
+    .avatar { @include circle(50px); }
+
+**With the `gls-` prefix.** Every mixin also answers to a prefixed name, which avoids collisions with Bootstrap and friends.
+
+    @use 'gerillass' as *;
+    .avatar { @include gls-circle(50px); }
+
+**Through a namespace.** Sass's own mechanism, and the tidiest of the three: nothing enters your global scope at all, so a collision is impossible. The name after `as` is yours to choose.
+
+    @use 'gerillass' as gls;
+    .avatar { @include gls.circle(50px); }
+
+All three produce identical CSS. The prefix predates the Sass module system; if you are starting fresh, the namespace does the same job without the extra name.
 
 ## Vendor Prefix Support
 

package/SKILL.md

@@ -5,7 +5,7 @@ description: Use the Gerillass Sass mixin library — loading it, the mixin cata
 
 # Gerillass
 
-A Sass mixin library: 51 mixins and 22 functions that emit CSS from
+A Sass mixin library: 50 mixins and 22 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.
 
@@ -37,7 +37,7 @@ Dart Sass only. LibSass and node-sass are not supported.
 
 ## Two names for every mixin
 
-Every mixin exists twice: bare (`ratio-box`) and prefixed (`gls-ratio-box`).
+Every mixin exists twice: bare (`circle`) and prefixed (`gls-circle`).
 They are the same mixin. The prefix exists to avoid collisions with other
 libraries. Pick one and stay with it; do not mix them in a file.
 
@@ -45,17 +45,17 @@ With the module system you can namespace instead, which is usually cleaner:
 
 ```scss
 @use "gerillass" as gls;
-.hero { @include gls.ratio-box("16/9"); }
+.avatar { @include gls.circle(50px); }
 ```
 
 ## Getting arguments right
 
 The conventions are not uniform across the library, so check before guessing.
-The single most common mistake is passing a ratio as a list:
+A mixin that wants a string will not take a bare value:
 
 ```scss
-.hero { @include ratio-box(16 9); }    // wrong — errors
-.hero { @include ratio-box("16/9"); }  // right
+.a { @include after(42) { color: red; } }    // wrong — errors
+.a { @include after("→") { color: red; } }   // right
 ```
 
 Mixins that reject bad input do so with a message naming what they accept. If
@@ -69,6 +69,7 @@ a dropped declaration rather than an error.
 | `all-buttons` | `@include all-buttons(nonsense) { color: red; }` |
 | `all-text-inputs` | `@include all-text-inputs(nonsense) { color: red; }` |
 | `antialias` | `@include antialias(only);` |
+| `aspect-ratio` | `.thumb { @include aspect-ratio("16:9", nonsense); }` |
 | `background-dots` | `.a { @include background-dots(red, 1em, 5em, maybe); }` |
 | `background-image` | `.a { @include background-image("/img/a.png", (red, blue), sideways); }` |
 | `background-stripes` | `.a { @include background-stripes(red, 2em, nonsense); }` |
@@ -86,10 +87,8 @@ a dropped declaration rather than an error.
 | `loadify` | `@include loadify(nonsense);` |
 | `only` | `.a { @include only(#ff0000) { margin: 0; } }` |
 | `radial-gradient` | `.a { @include radial-gradient(42, "center", (red, blue)); }` |
-| `ratio-box` | `.hero { @include ratio-box(16 9); }` |
 | `remove` | `.a { @include remove(a, b, c); }` |
 | `reset-css` | `.a { @include reset-css; }` |
-| `responsive-video` | `.video { @include responsive-video(16 9); }` |
 | `scissors` | `.a { @include scissors(5px 10px); }` |
 | `smartphone` | `.a { @include smartphone(Nokia3310) { display: none; } }` |
 | `sprite` | `.icon { @include sprite("/img/sprite.txt"); }` |
@@ -109,6 +108,7 @@ a dropped declaration rather than an error.
 | `all-buttons($pseudo: null)` | Targets every button-like element at once, optionally in one pseudo-class state. |
 | `all-text-inputs($pseudo: null)` | Targets every text-like input at once, optionally in one pseudo-class state. |
 | `antialias($value: null)` | Turns on subpixel-antialiased text smoothing. |
+| `aspect-ratio($ratio: null, $fit: cover)` | 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. |
 | `background-dots($color: null, $size: 1em, $gutter: $size * 5, $diagonal: true, $image: null)` | Repeating dot pattern as a background, optionally over an image. |
 | `background-image($image-url: null, $filter-color: null, $filter-direction: null)` | Background image with an optional colour or gradient filter laid over it. |
 | `background-stripes($color: null, $thickness: 1em, $rotation: -45deg, $image: null)` | Repeating stripe pattern as a background, optionally over an image. |
@@ -135,13 +135,11 @@ a dropped declaration rather than an error.
 | `placeholder` | Styles the placeholder text of an input across vendor prefixes. |
 | `position($position: absolute, $offsets: 0)` | Sets position and offsets in one call, using shorthand order. |
 | `radial-gradient($shape, $position, $colors)` | Radial gradient background from a shape and a position. |
-| `ratio-box($ratio: null)` | Container that holds a fixed aspect ratio. Its single direct child is stretched to fill it. |
 | `remove($params...)` | Hides an element outright, or only within a breakpoint range. |
 | `reset-css` | Meyer reset. Must be called at the root of the stylesheet. |
 | `reset-figure` | Removes default figure margins and makes the image inside responsive. |
 | `resizable($direction: both, $overflow: auto)` | Makes an element user-resizable. |
 | `responsive-image` | Makes an image fill its container width. |
-| `responsive-video($ratio: null)` | Wrapper that keeps an embedded video at a fixed aspect ratio. |
 | `scissors($corners)` | Cuts the corners off an element with clip-path. |
 | `screen-agent($resolution)` | Media query targeting a screen pixel density. |
 | `sizer($width, $height: $width)` | Sets width and height together; one argument makes a square. |
@@ -163,28 +161,28 @@ functions rather than mixins; they are public API.
 
 | Signature | What it does |
 |---|---|
-| `__clearUnit($value)` | Strips the unit off a number, returning it unitless. |
-| `__clearWhitespace($string)` | Removes every space from a string. |
-| `__convertToEm($value)` | Converts a pixel length to em, against a 16px base. |
-| `__convertToNumber($value)` | Parses a string of digits into a number. |
-| `__darken($color, $percentage)` | Mixes a colour towards black by a percentage. |
-| `__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. |
-| `__isGutter($value)` | True for anything that can sit where a CSS length is expected: a number, a calculation, or a CSS function such as var(). |
-| `__isNumber($value)` | Returns the value if it is a number. |
-| `__isTime($value)` | Returns the value if it is a time in s or ms, and errors otherwise. |
-| `__lighten($color, $percentage)` | Mixes a colour towards white by a percentage. |
-| `__mapDeepGet($map, $keys...)` | Reads a value out of a nested map by following a chain of keys. |
-| `__null($value, $seperation: comma, $skip: false)` | Replaces null entries in a list with 0, or drops them. |
-| `__pixelify($value)` | Returns the value with a px unit, adding one if it is missing. |
-| `__pseudoSelector($elements, $pseudo: null)` | Appends a pseudo-class to every selector in a list. |
-| `__remify($value)` | Converts a pixel length to rem, against a 16px root. |
-| `__shorthandProperty($value)` | Expands one to four values into the four-value CSS shorthand order. |
-| `__validateBreakpoint($value)` | Resolves a breakpoint name to its width, passing other values through. |
-| `__validateLength($value)` | Returns the value if it is a length or one of auto, inherit, initial, 0. |
-| `__validateRatio($ratio)` | Turns an aspect ratio into the padding-top percentage that holds it. |
-| `__validateScissors($value)` | Normalises corner values for the scissors mixin, adding px where missing. |
+| `clearUnit($value)` | Strips the unit off a number, returning it unitless. |
+| `clearWhitespace($string)` | Removes every space from a string. |
+| `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. |
+| `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. |
+| `isGutter($value)` | True for anything that can sit where a CSS length is expected: a number, a calculation, or a CSS function such as var(). |
+| `isNumber($value)` | Returns the value if it is a number. |
+| `isTime($value)` | Returns the value if it is a time in s or ms, and errors otherwise. |
+| `mapDeepGet($map, $keys...)` | Reads a value out of a nested map by following a chain of keys. |
+| `pixelify($value)` | Returns the value with a px unit, adding one if it is missing. |
+| `pseudoSelector($elements, $pseudo: null)` | Appends a pseudo-class to every selector in a list. |
+| `remify($value)` | Converts a pixel length to rem, against a 16px root. |
+| `shade($color, $percentage)` | Mixes a colour towards black by a percentage. |
+| `shorthandProperty($value)` | Expands one to four values into the four-value CSS shorthand order. |
+| `tint($color, $percentage)` | Mixes a colour towards white by a percentage. |
+| `validateBreakpoint($value)` | Resolves a breakpoint name to its width, passing other values through. |
+| `validateLength($value)` | Returns the value if it is a length or one of auto, inherit, initial, 0. |
+| `validateRatio($ratio)` | Turns an aspect ratio into a value for the CSS aspect-ratio property. |
+| `validateScissors($value)` | Normalises corner values for the scissors mixin, adding px where missing. |
 
 ## Checking your work