gerillass 1.4.0 → 1.6.0

package/README.md

@@ -8,7 +8,7 @@
 
 [Gerillass](https://gerillass.com) is a library built on top of [Sass (Syntactically Awesome Style Sheets)](https://sass-lang.com/) to give you flexibility for your projects and accelerate your performance and creativity.
 
-Many of the utilities that come with Gerillass are the solutions I have come up with for the challenges I have faced as a frontend developer over the years. These solutions have been shaped by the inspiration of other popular libraries and frameworks like [Bourbon](https://www.bourbon.io/), [Susy](https://www.oddbird.net/), [Scut](https://davidtheclark.github.io/scut/), [Bootstrap](https://getbootstrap.com/), etc. over time and helped me create Gerillass.
+Many of the utilities that come with Gerillass are the solutions I have come up with for the challenges I have faced as a frontend developer over the years. These solutions have been shaped by the inspiration of other popular libraries and frameworks like [Bourbon](https://www.bourbon.io/), [Susy](https://www.oddbird.net/), [Scut](https://github.com/davidtheclark/scut), [Bootstrap](https://getbootstrap.com/), etc. over time and helped me create Gerillass.
 
 Hope you’ll enjoy using it!
 
@@ -23,11 +23,14 @@ Hope you’ll enjoy using it!
 
 - [Dart Sass Upgrade](#dart-sass-upgrade)
 - [Installation](#installation)
-  - [Node.js Installation](#nodejs-installation)
-  - [Using with React.js](#using-with-reactjs)
+  - [Using with Vite](#using-with-vite)
+  - [Using with webpack](#using-with-webpack)
+  - [Using with Next.js](#using-with-nextjs)
+  - [Using with Angular](#using-with-angular)
   - [Using with Gulp](#using-with-gulp)
   - [Using with Grunt](#using-with-grunt)
   - [Cloning the Repository from Github](#cloning-the-repository-from-github)
+  - [Versions these examples were tested with](#versions-these-examples-were-tested-with)
 - [Namespace Usage](#namespace-usage)
 - [Vendor Prefix Support](#vendor-prefix-support)
 - [Experimenting](#experimenting)
@@ -45,74 +48,118 @@ Because LibSass and the packages built on it, including Node Sass, are deprecate
 
     npm install gerillass --save-dev
 
-You can **import** Gerillass with **node_modules** path.
+Or with Yarn:
 
-    @import '{node_modules_path}/gerillass/scss/gerillass';
+    yarn add gerillass --dev
 
-**To add the library without using the {node_modules_path} see the examples below.**
+Then load it. If your setup resolves packages from **node_modules** — Vite, webpack, Next.js and most modern bundlers do — this is all you need:
 
-If you're working with an **eyeglass** setup, simply import it without providing the **node_modules** path.
+    @use 'gerillass' as *;
 
-    @import 'gerillass';
+If you call Dart Sass yourself rather than through a bundler, turn on its package importer and use a `pkg:` URL:
 
-### Node.js Installation
+    @use 'pkg:gerillass' as *;
 
-If you are working on a Node project you can add Gerillass as a dependency.
+```js
+// Dart Sass 1.71.0 or later
+import * as sass from 'sass';
+import { NodePackageImporter } from 'sass';
 
-#### npm installation
+sass.compile('style.scss', { importers: [new NodePackageImporter()] });
+```
 
-    npm install gerillass --save-dev
+Or from the command line:
+
+    sass --pkg-importer=node style.scss style.css
+
+Pointing straight at the file always works too:
+
+    @use '{node_modules_path}/gerillass/scss/gerillass' as *;
+
+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
+
+Vite resolves the package by name, so there is nothing to configure. This covers anything built on Vite, including React, Vue, Svelte, SvelteKit and Astro.
+
+    @use 'gerillass' as *;
+
+### Using with webpack
+
+`sass-loader` also resolves the package by name, with no extra options.
+
+    @use 'gerillass' as *;
+
+### Using with Next.js
+
+Next.js needs to be told where the library lives. In `next.config.mjs`:
+
+    export default {
+      sassOptions: {
+        loadPaths: ["node_modules/gerillass/scss"],
+      },
+    };
 
-#### Yarn installation
+Then, in any `.scss` file:
 
-    yarn add gerillass
+    @use 'gerillass' as *;
 
-### Using with React.js
+### Using with Angular
 
-Simply `@import` the library at the beginning of your App.scss file without using the **node_modules** path.
+Add the library folder to the build target's options in `angular.json`. Angular calls this option `includePaths`, not `loadPaths`:
 
-    @import 'gerillass';
+    "stylePreprocessorOptions": {
+      "includePaths": ["node_modules/gerillass/scss"]
+    }
+
+Then, in `src/styles.scss`:
+
+    @use 'gerillass' as *;
 
 ### Using with Gulp
 
-You can add a new Gulp task as in the below example or simply add `includePath: ['node_modules/gerillass/scss']` option to the task if you have one already.
-
-    function sassify(done) {
-      return (
-        src("assets/sass/**/*.scss")
-        .pipe(sass({
-          outputStyle: "expanded",
-          includePaths: ["node_modules/gerillass/scss"],
-        }).on('error', sass.logError))
-        .pipe(dest("assets/css"))
-      );
-      done()
+`gulp-sass` hands its options straight to Dart Sass, so the option is **`loadPaths`**. The old `includePaths` name came from Node Sass and no longer resolves.
+
+    const { src, dest } = require("gulp");
+    const sass = require("gulp-sass")(require("sass"));
+
+    function styles() {
+      return src("assets/sass/**/*.scss")
+        .pipe(sass({ loadPaths: ["node_modules/gerillass/scss"] }).on("error", sass.logError))
+        .pipe(dest("assets/css"));
     }
 
-Including to the project:
-  
-    @import 'gerillass';
+    exports.styles = styles;
 
-### Using with Grunt
+Then:
 
-You can add the Gerillass library by editing your Gruntfile.js at the root level of your project. Simply find the sass related rules and add `loadPath: ['node_modules/gerillass/scss']` inside the `options` object.
+    @use 'gerillass' as *;
 
-    sass: {
-      dist: {
-        options: {
-          style: "expanded",
-          loadPath: ['node_modules/gerillass/scss']
+### Using with Grunt
+
+Use `grunt-sass` with Dart Sass as the implementation. The option here is **`loadPaths`** as well — not `loadPath`, and not `includePaths`.
+
+    module.exports = function (grunt) {
+      grunt.loadNpmTasks("grunt-sass");
+      grunt.initConfig({
+        sass: {
+          dist: {
+            options: {
+              implementation: require("sass"),
+              loadPaths: ["node_modules/gerillass/scss"],
+            },
+            files: { "css/main.css": "src/main.scss" },
+          },
         },
-        files: {
-          "main.css": "main.scss"
-        }
-      }
-    }
+      });
+    };
+
+Then:
+
+    @use 'gerillass' as *;
 
-Including to the project:
-  
-    @import 'gerillass';
-    
 ### Cloning the repository from Github
 
 You can clone the repository into your local computer from Github.
@@ -125,7 +172,19 @@ Or you can add the library as a submodule into your Git based project ([What is
 
 Including to the project:
 
-    @import '{folder_path}/gerillass/scss/gerillass';
+    @use '{folder_path}/gerillass/scss/gerillass' as *;
+
+### Versions these examples were tested with
+
+| Tool | Version |
+|---|---|
+| Dart Sass | 1.103.1 |
+| Vite | 8.2.2 |
+| webpack / sass-loader | 5.110.3 / 17.0.1 |
+| Next.js | 16.3.4 |
+| Angular CLI | 20.3.36 |
+| Gulp / gulp-sass | 5.0.1 / 6.0.1 |
+| Grunt / grunt-sass | 1.6.3 / 4.1.0 |
 
 ## Namespace Usage
 
@@ -161,4 +220,4 @@ Gerillass is licensed under the Apache License, Version 2.0. For more [see the l
 
 ## Additional Info
 
-This project is created with the loving music of **Anna German** and dedicated to **James Williamson**: The best web educator ever. For more information about James, please check his legacy blog page at www.simpleprimate.com or watch his video lectures about **Web** and **Accessibility** on [LinkedIn Learning](https://www.linkedin.com/learning/instructors/james-williamson).
+This project is created with the loving music of **Anna German** and dedicated to **James Williamson**: The best web educator ever. For more information about James, please check his legacy blog page at [simpleprimate.netlify.app](https://simpleprimate.netlify.app) or watch his video lectures about **Web** and **Accessibility** on [LinkedIn Learning](https://www.linkedin.com/learning/instructors/james-williamson).

package/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: gerillass
+description: Use the Gerillass Sass mixin library — loading it, the mixin catalogue, and the argument forms that are easy to get wrong. Use when writing SCSS in a project that has gerillass installed.
+---
+
+# Gerillass
+
+A Sass mixin library: 51 mixins and 21 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.
+
+Full documentation: https://docs.gerillass.com
+Machine-readable API: `gerillass.json` in this package.
+
+## Loading it
+
+Through a bundler (Vite, webpack and most others resolve the package by name):
+
+```scss
+@use "gerillass" as *;
+```
+
+Calling Dart Sass yourself, with its package importer
+(`new NodePackageImporter()` or `sass --pkg-importer=node`):
+
+```scss
+@use "pkg:gerillass" as *;
+```
+
+Anything else, by pointing a load path at `node_modules/gerillass/scss`:
+
+```scss
+@use "gerillass" as *;
+```
+
+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`).
+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.
+
+With the module system you can namespace instead, which is usually cleaner:
+
+```scss
+@use "gerillass" as gls;
+.hero { @include gls.ratio-box("16/9"); }
+```
+
+## 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:
+
+```scss
+.hero { @include ratio-box(16 9); }    // wrong — errors
+.hero { @include ratio-box("16/9"); }  // right
+```
+
+Mixins that reject bad input do so with a message naming what they accept. If
+you get one, read it: it lists the valid values. Mixins not in the table below
+mostly pass their arguments through to CSS, so a wrong value there shows up as
+a dropped declaration rather than an error.
+
+| Mixin | Rejects, for example |
+|---|---|
+| `all-buttons` | `@include all-buttons(nonsense) { color: red; }` |
+| `all-text-inputs` | `@include all-text-inputs(nonsense) { color: red; }` |
+| `antialias` | `@include antialias(only);` |
+| `background-dots` | `.a { @include background-dots(red, 1em, 5em, maybe); }` |
+| `background-image` | `.a { @include background-image("/img/a.png", (red, blue), sideways); }` |
+| `border-box` | `@include border-box(only);` |
+| `border-radius` | `.a { @include border-radius(1px, 2px, 3px); }` |
+| `center` | `.modal { @include center(diagonal); }` |
+| `columnizer` | `.grid { @include columnizer(3, 20px, true, 9); }` |
+| `except` | `.a { @include except(#ff0000) { margin: 0; } }` |
+| `font-face` | `.a { @include font-face("Inter", "/fonts/inter"); }` |
+| `hide` | `.a { @include hide(nonsense); }` |
+| `loadify` | `@include loadify(nonsense);` |
+| `only` | `.a { @include only(#ff0000) { margin: 0; } }` |
+| `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"); }` |
+| `stretched-link` | `.card a { @include stretched-link(middle); }` |
+| `tablet` | `.a { @include tablet(Surface) { display: none; } }` |
+| `text-selection` | `.a { @include text-selection(bogus) { background: yellow; } }` |
+| `triangle` | `.caret { @include triangle(sideways); }` |
+
+## Mixins
+
+| Signature | What it does |
+|---|---|
+| `adaptive($gutter: 30px)` | Centred container whose max-width steps up at every breakpoint. |
+| `after($content: null)` | Styles the ::after pseudo-element. A `data-` argument becomes an attr() content value. |
+| `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. |
+| `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. |
+| `before($content: null)` | Styles the ::before pseudo-element. A `data-` argument becomes an attr() content value. |
+| `border-box($value: null)` | Applies box-sizing: border-box. |
+| `border-radius($args...)` | Rounds corners, either all of them, one named corner, or all four individually. |
+| `brand-logo($width, $height, $image-url: null)` | Logo box with an image and an accessible stretched link over it. |
+| `breakpoint($params...)` | Media query built from the breakpoint map, or from raw lengths. |
+| `breakpointer($selector: null)` | Debug helper that prints the active breakpoint name into a pseudo-element. |
+| `center($axis: "both")` | Absolutely centres an element inside its positioned parent. |
+| `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. |
+| `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. |
+| `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. |
+| `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. |
+| `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. |
+| `smartphone($device, $orientation: null)` | Media query targeting a known smartphone by device dimensions. |
+| `sprite($params...)` | Sets up an element as a sprite tile: an image, a background position, or both. |
+| `stretched-link($value: "before")` | Expands a link to cover its positioned parent, so the whole card is clickable. |
+| `tablet($device, $orientation: null)` | Media query targeting a known tablet by device dimensions. |
+| `text-gradient($direction, $colors)` | Applies a linear gradient to the text itself via background-clip. |
+| `text-image($image: null)` | Fills the text with an image via background-clip. |
+| `text-selection($value: null)` | Styles the ::selection pseudo-element. |
+| `text-shadow($params...)` | Layered text shadows built from a direction, a colour and an offset. |
+| `text-stroke($fallback-color: black, $color: transparent, $stroke-color: black, $stroke-width: 1px)` | Outlines text using the webkit text-stroke properties. |
+| `triangle($direction: "bottom", $color: black, $size: 10px 8px)` | Draws a CSS triangle out of borders, pointing in a given direction. |
+
+## Functions
+
+Called like normal Sass functions. The two leading underscores mark them as
+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. |
+| `__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. |
+
+## Checking your work
+
+Sass evaluates mixin bodies lazily, so a stylesheet that merely loads the
+library always compiles. Compile the file that actually calls the mixin:
+
+```bash
+sass --load-path=node_modules/gerillass/scss your.scss
+```
+
+An empty rule in the output means the mixin matched none of its branches —
+treat that as a bug, not as success.