gerillass 2.3.0 → 3.0.0

package/README.md

@@ -32,6 +32,7 @@ Hope you’ll enjoy using it!
   - [Using with Angular](#using-with-angular)
   - [Using with Gulp](#using-with-gulp)
   - [Using with Grunt](#using-with-grunt)
+  - [Using with Ruby: Rails, Jekyll, or plain Sass](#using-with-ruby-rails-jekyll-or-plain-sass)
   - [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)
@@ -184,6 +185,35 @@ Then:
 
     @use 'gerillass' as *;
 
+### Using with Ruby: Rails, Jekyll, or plain Sass
+
+Gerillass is also a gem. It installs the same Sass files and nothing else: no runtime dependencies, because each kind of project already brings its own Dart Sass. It needs Dart Sass; the LibSass-based `sass-rails` and `sassc-rails` cannot compile it.
+
+    bundle add gerillass
+
+**Rails.** With `dartsass-rails` on Propshaft, the Rails 8 default, or `dartsass-sprockets` on Sprockets, there is nothing to configure: the gem hands the library's folder to Sass, and none of its files end up in `public/assets`. Then, in `app/assets/stylesheets/application.scss`:
+
+    @use 'gerillass' as *;
+
+**Jekyll.** Put the gem in the plugins group of your `Gemfile`:
+
+    group :jekyll_plugins do
+      gem "gerillass"
+    end
+
+Then, in a stylesheet with front matter such as `assets/css/main.scss`:
+
+    ---
+    ---
+    @use 'gerillass' as *;
+
+**Plain Ruby.** Pass the library's folder to `sass-embedded` yourself:
+
+    require "sass-embedded"
+    require "gerillass"
+
+    Sass.compile("style.scss", load_paths: [Gerillass.load_path])
+
 ### Cloning the repository from Github
 
 You can clone the repository into your local computer from Github.
@@ -210,10 +240,15 @@ Including to the project:
 | Gulp / gulp-sass | 5.0.1 / 6.0.1 |
 | Grunt / grunt-sass | 1.6.3 / 4.1.0 |
 | Parcel / @parcel/transformer-sass | 2.16.4 / 2.16.4, with Dart Sass 1.104.1 and Gerillass 2.1.0 |
+| Ruby / Rails | 4.0.1 / 8.1.3.1 |
+| Propshaft / dartsass-rails | 1.3.2 / 0.5.1 |
+| sprockets-rails / dartsass-sprockets | 3.5.2 / 3.2.1 |
+| Jekyll / jekyll-sass-converter | 4.4.1 / 3.1.0 |
+| sass-embedded (Ruby) | 1.104.1 |
 
 ## Using Gerillass with an AI coding agent
 
-A library this size has no training data behind it, so an agent asked to use Gerillass will guess at the argument forms and get them wrong. Two files ship with the package to stop that. Both live inside the installed package, so an agent working in your project can read them straight out of `node_modules/gerillass/`.
+A library this size has no training data behind it, so an agent asked to use Gerillass will guess at the argument forms and get them wrong. Two files ship with the package to stop that. Both live inside the installed package, so an agent working in your project can read them straight out of `node_modules/gerillass/`, or, in a Ruby project, out of the gem's folder, which `bundle info gerillass --path` prints.
 
 **`gerillass.json`** describes every mixin and function: its signature, what each argument accepts, examples that compile, and inputs that are refused.
 
@@ -224,6 +259,10 @@ A library this size has no training data behind it, so an agent asked to use Ger
     mkdir -p .claude/skills/gerillass
     cp node_modules/gerillass/SKILL.md .claude/skills/gerillass/
 
+In a Ruby project, copy it from the gem instead:
+
+    cp "$(bundle info gerillass --path)/SKILL.md" .claude/skills/gerillass/
+
 Otherwise, point your agent at the file and it will read it as plain Markdown.
 
 ### Why you can trust what they say
@@ -264,21 +303,21 @@ So, feel free to use any tool to support that. My suggestion is Autoprefixer. If
 
 ## Experimenting
 
-Experimentation with Gerillass is easy: If you're processing Sass files on your computer already, [download the Gerillass Sass library](https://github.com/selfishprimate/gerillass/archive/main.zip), include it in your project, and start using it. If not, use [Gerillass Play](https://github.com/selfishprimate/gerillass-play)! Gerillass Play is a Gulp based playground, built for you to get started with [Sass](https://sass-lang.com/) and [Gerillass](https://gerillass.com/) quickly.
+The quickest way to try Gerillass is the [playground](https://gerillass.com/playground). It runs in your browser, so there is nothing to install: write Sass on one side and read the CSS it compiles to on the other. Pick a mixin to start from an example, and pick any published Gerillass version to compile against, which makes it easy to see how a call behaves before and after an upgrade.
 
-**Important Note**: Don't forget that you must have [Node.js](https://nodejs.org/en/) and [Gulp CLI](https://gulpjs.com/docs/en/getting-started/quick-start) installed on your machine to work with Gerillass Play.
+When you are ready to use it in a project, follow the [installation](#installation) steps for your build tool.
 
 ## Testing
 
-Gerillass comes with a unit-testing module named [True](https://github.com/oddbird/true), which makes Sass unit tests possible (endless thanks to the [OddBird Team](https://github.com/oddbird)).
-
-You can find two test examples under the `test` folder, take your time, examine the codes, and then write your unit tests. After that, run the following command to see if the tests pass.
+The test suite runs with [Jest](https://jestjs.io/) and [True](https://github.com/oddbird/true), which makes Sass unit tests possible (endless thanks to the [OddBird Team](https://github.com/oddbird)).
 
     npm test
 
+It checks more than hand-written assertions: every mixin is called at least once, every documented example is compiled and compared with a snapshot, and every input a mixin should refuse must stop the build with the library's own error message. [CONTRIBUTING.md](CONTRIBUTING.md#testing) explains which of these a change needs.
+
 ## Contribution
 
-Please read the [contribution details](CONTRIBUTING.md) and feel free to contribute to the library.
+Please read the [contribution details](CONTRIBUTING.md) and feel free to contribute to the library. If you are working on a mixin, the site's dev server has a lab that renders your working copy of the library as you edit it; [CONTRIBUTING.md](CONTRIBUTING.md#seeing-what-it-renders) shows how to use it.
 
 ## License
 

package/SKILL.md

@@ -5,7 +5,7 @@ description: Use the Gerillass Sass mixin library — loading it, the mixin cata
 
 # Gerillass
 
-A Sass mixin library: 56 mixins and 23 functions that emit CSS from
+A Sass mixin library: 55 mixins and 24 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.
 
@@ -33,7 +33,17 @@ Anything else, by pointing a load path at `node_modules/gerillass/scss`:
 @use "gerillass" as *;
 ```
 
-Dart Sass only. LibSass and node-sass are not supported.
+In a Ruby project, from the `gerillass` gem. Rails with `dartsass-rails` or
+`dartsass-sprockets`, and Jekyll with the gem in its `:jekyll_plugins` group,
+need no configuration. Plain Ruby passes the folder to `sass-embedded` with
+`load_paths: [Gerillass.load_path]`. Then:
+
+```scss
+@use "gerillass" as *;  // the gerillass gem: Rails and Jekyll need no setup; plain Ruby passes Gerillass.load_path
+```
+
+Dart Sass only. LibSass and node-sass are not supported, which rules out
+`sass-rails` and `sassc-rails` in Ruby.
 
 ## Two names for every mixin
 
@@ -65,6 +75,7 @@ a dropped declaration rather than an error.
 
 | Mixin | Rejects, for example |
 |---|---|
+| `adaptive` | `.wrap { @include adaptive(auto); }` |
 | `after` | `.a { @include after(42) { color: red; } }` |
 | `all-buttons` | `@include all-buttons(nonsense) { color: red; }` |
 | `all-text-inputs` | `@include all-text-inputs(nonsense) { color: red; }` |
@@ -76,35 +87,41 @@ a dropped declaration rather than an error.
 | `before` | `.a { @include before(42) { color: red; } }` |
 | `border-box` | `@include border-box(only);` |
 | `border-radius` | `.a { @include border-radius(1px, 2px, 3px); }` |
+| `brand-logo` | `.logo { @include brand-logo(120px, 40px, "/img/a.svg" "/img/b.svg"); }` |
 | `breakpoint` | `.a { @include breakpoint("between", "medium", "large") { color: red; } }` |
 | `breakpointer` | `.a { @include breakpointer(42); }` |
 | `center` | `.modal { @include center(diagonal); }` |
+| `circle` | `.dot { @include circle(huge); }` |
 | `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); }` |
+| `ellipsis` | `.a { @include ellipsis(100%, huge); }` |
 | `escape-to-parent` | `.a { @include escape-to-parent(42) { color: red; } }` |
 | `except` | `.a { @include except(#ff0000) { margin: 0; } }` |
 | `focus-ring` | `@include focus-ring;` |
 | `font-face` | `.a { @include font-face("Inter", "/fonts/inter"); }` |
+| `gradient` | `.a { @include gradient((red, blue), sideways); }` |
 | `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);` |
 | `motion-safe` | `.card { @include motion-safe; }` |
 | `only` | `.a { @include only(#ff0000) { margin: 0; } }` |
 | `position` | `.badge { @include position(absolute, 0, $logical: yes); }` |
-| `radial-gradient` | `.a { @include radial-gradient(42, "center", (red, blue)); }` |
 | `remove` | `.a { @include remove(a, b, c); }` |
 | `reset-css` | `.a { @include reset-css; }` |
+| `resizable` | `.a { @include resizable(huge); }` |
 | `scissors` | `.a { @include scissors(5px 10px); }` |
 | `screen-agent` | `.a { @include screen-agent(var(--density)) { color: red; } }` |
+| `sizer` | `.a { @include sizer(huge); }` |
 | `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-gradient` | `.a { @include text-gradient(sideways, (red, blue)); }` |
+| `text-gradient` | `.a { @include text-gradient("top", (red, blue)); }` |
+| `text-image` | `.a { @include text-image(16 9); }` |
 | `text-selection` | `.a { @include text-selection(bogus) { background: yellow; } }` |
 | `text-shadow` | `.a { @include text-shadow(42); }` |
+| `text-stroke` | `.a { @include text-stroke(huge); }` |
 | `tokens` | `:root { @include tokens(#fff); }` |
 | `triangle` | `.caret { @include triangle(sideways); }` |
 
@@ -124,12 +141,12 @@ a dropped declaration rather than an error.
 
 **`breakpoint`**
 
-- With one argument the query matches exactly that width, `(width: 768px)`, which is a single pixel, and the mixin prints a warning. Write `only` for that width, or `min`, `max` or a range for anything wider. 3.0.0 will refuse the one-argument form.
+- With one argument the query matches exactly that width, `(width: 768px)`, which is a single pixel, and the mixin prints a warning. Write `only` for that width, or `min`, `max` or a range for anything wider.
 - Declarations written after the include, in the same rule, are emitted after the `@media` block and win over it. Write them before the include.
 
 **`container-query`**
 
-- A size on its own matches exactly that width, `(width: 400px)`, which is a single pixel, and the mixin prints a warning. Write `only` for that width, or `min`, `max` or a range for anything wider. 3.0.0 will refuse the one-argument form.
+- A size on its own matches exactly that width, `(width: 400px)`, which is a single pixel, and the mixin prints a warning. Write `only` for that width, or `min`, `max` or a range for anything wider.
 
 **`container`**
 
@@ -139,6 +156,10 @@ a dropped declaration rather than an error.
 
 - Numbering restarts on every item, each showing the first number, when the items are size containers (`container-type: inline-size`): containment scopes counters to each item.
 
+**`except`**
+
+- An+B with an offset cannot be passed as a number: Sass does the arithmetic, so `except(2n+1)` becomes `3n` and excludes every third element, not the odd ones. Use `odd` or `even`, or a coefficient alone such as `3n`.
+
 **`loadify`**
 
 - `init` and every call must be in the same module, or the module with the call must `@use` the one that calls `init`. Otherwise Sass fails with "The target selector was not found".
@@ -147,9 +168,13 @@ a dropped declaration rather than an error.
 
 - Keep the resting state outside the block. An element hidden in its base rule and revealed by an animation inside the block stays hidden for a user who asked for less motion; put the start state in the keyframes instead.
 
+**`only`**
+
+- An+B with an offset cannot be passed as a number: Sass does the arithmetic, so `only(2n+1)` becomes `3n` and selects every third element, not the odd ones. Use `odd` or `even`, or a coefficient alone such as `3n`.
+
 **`remove`**
 
-- With one argument the element is hidden at exactly that width, `(width: 768px)`, which is a single pixel, and the mixin prints a warning. Write `only` for that width, or `min`, `max` or a range for anything wider. 3.0.0 will refuse the one-argument form.
+- With one argument the element is hidden at exactly that width, `(width: 768px)`, which is a single pixel, and the mixin prints a warning. Write `only` for that width, or `min`, `max` or a range for anything wider.
 - A `display` written after the include, in the same rule, is emitted after the `@media` block and wins over it. Write it before the include.
 
 ## Mixins
@@ -183,16 +208,15 @@ a dropped declaration rather than an error.
 | `except($params...)` | Selects every sibling except the ones named. |
 | `focus-ring($width: 2px, $offset: 2px, $color: currentColor)` | Draws a keyboard focus ring with outline on :focus-visible, which survives forced-colors mode where a box-shadow ring disappears. |
 | `font-face($font-family, $file-path, $font-style: normal, $font-weight: 400, $file-formats: eot woff2 woff ttf svg, $font-display: null)` | Emits an @font-face rule for one family across several file formats. Must be called at the root. |
+| `gradient($colors, $type: linear, $direction: null, $shape: null, $position: null, $from: null, $in: null, $repeating: false)` | A linear, radial or conic gradient as background-image, plain or repeating, with an optional colour interpolation space. Replaced linear-gradient and radial-gradient in 3.0.0. |
 | `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. 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. |
 | `motion-safe` | Wraps its content in @media (prefers-reduced-motion: no-preference), so motion is opt-in: a user who asked their system for less motion gets none of it. |
 | `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, $logical: false)` | Sets position and offsets in one call, using shorthand order. |
-| `radial-gradient($shape, $position, $colors)` | Radial gradient background from a shape and a position. |
 | `remove($params...)` | Hides an element outright, or within a media query: from a breakpoint up with min, up to it with max, or between two breakpoints. One breakpoint on its own hides the element at exactly that width, a single pixel, and prints a warning: pass only for that. |
 | `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. |
@@ -205,7 +229,7 @@ a dropped declaration rather than an error.
 | `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-gradient($colors, $type: linear, $direction: null, $shape: null, $position: null, $from: null, $in: null, $repeating: false)` | Fills the text with a gradient through background-clip: text. It takes the gradient mixin's arguments, colours first: a linear, radial or conic gradient, plain or repeating, with an optional colour space. |
 | `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. |
@@ -228,6 +252,7 @@ and camelCase is what tells them apart from the kebab-case mixins above.
 | `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. |
+| `gradientValue($colors, $type: linear, $direction: null, $shape: null, $position: null, $from: null, $in: null, $repeating: false)` | The gradient mixin's gradient as a value, for layering it with an image in one background-image, or using it as a mask-image or border-image. It takes the same arguments and refuses the same input, but cannot write the fallback the mixin writes before a gradient with $in. |
 | `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. |
@@ -239,7 +264,7 @@ and camelCase is what tells them apart from the kebab-case mixins above.
 | `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. |
+| `validateBreakpoint($value)` | Resolves a breakpoint name to its width, passing a length, a percentage or a CSS function through, and refusing a word that is not a key. |
 | `validateLength($value)` | Returns the value if it is a length or one of auto, inherit, initial, 0. Returns null quietly for null, so a caller can skip a value. |
 | `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. |