gerillass 2.0.1 → 2.1.1

package/README.md

@@ -27,6 +27,7 @@ Hope you’ll enjoy using it!
 - [Installation](#installation)
   - [Using with Vite](#using-with-vite)
   - [Using with webpack](#using-with-webpack)
+  - [Using with Parcel](#using-with-parcel)
   - [Using with Next.js](#using-with-nextjs)
   - [Using with Angular](#using-with-angular)
   - [Using with Gulp](#using-with-gulp)
@@ -94,6 +95,27 @@ Vite resolves the package by name, so there is nothing to configure. This covers
 
     @use 'gerillass' as *;
 
+### Using with Parcel
+
+Parcel resolves the package by name too, so the usual line needs no configuration:
+
+    @use 'gerillass' as *;
+
+**Remove `main` from your project's own `package.json`.** `npm init -y` writes `"main": "index.js"`, and Parcel reads that field as a library build target. With it present an app build fails, and the error names the stylesheet rather than the field: `Can't find stylesheet to import`. No Sass option gets around it. If you need to keep the field, turn that target off instead:
+
+    "targets": { "main": false }
+
+To use a `pkg:` URL, create the importer in a `.sassrc.js`. Setting `pkgImporter` in `.sassrc.json` does not work: Parcel switches Sass to its legacy API for that option, and the import is not found.
+
+    // .sassrc.js
+    const { NodePackageImporter } = require("sass");
+    module.exports = { importers: [new NodePackageImporter()] };
+
+Two more things worth knowing:
+
+- **Pass the font formats you actually have to `font-face`.** It lists five by default, and Parcel resolves every `url()` in the output, so a folder holding only `.woff2` fails with `Failed to resolve './fonts/inter.eot'`. `$file-formats: woff2` fixes it.
+- **`quietDeps` hides the library's own deprecation warnings.** Dart Sass reports its `if()` deprecation from inside the package on every build. A `.sassrc.json` of `{ "quietDeps": true }` silences those and still reports the ones in your own files.
+
 ### Using with Next.js
 
 Next.js needs to be told where the library lives. In `next.config.mjs`:
@@ -187,6 +209,7 @@ Including to the project:
 | Angular CLI | 20.3.36 |
 | 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 |
 
 ## Using Gerillass with an AI coding agent
 

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.
 
@@ -76,13 +76,17 @@ 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); }` |
+| `breakpoint` | `.a { @include breakpoint("between", "medium", "large") { color: red; } }` |
 | `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; } }` |
@@ -90,6 +94,7 @@ a dropped declaration rather than an error.
 | `remove` | `.a { @include remove(a, b, c); }` |
 | `reset-css` | `.a { @include reset-css; }` |
 | `scissors` | `.a { @include scissors(5px 10px); }` |
+| `screen-agent` | `.a { @include screen-agent(var(--density)) { color: red; } }` |
 | `smartphone` | `.a { @include smartphone(Nokia3310) { display: none; } }` |
 | `sprite` | `.icon { @include sprite("/img/sprite.txt"); }` |
 | `stretched-link` | `.card a { @include stretched-link(middle); }` |
@@ -99,6 +104,42 @@ a dropped declaration rather than an error.
 | `text-shadow` | `.a { @include text-shadow(42); }` |
 | `triangle` | `.caret { @include triangle(sideways); }` |
 
+## Traps a signature does not show
+
+**`after`**
+
+- With no argument no `content` is emitted, so the pseudo-element does not render unless the block sets `content`. Pass `""` for an empty one.
+
+**`aspect-ratio`**
+
+- On an element with a `height` attribute, such as `<img width="1600" height="900">` or an embed code's `<iframe>`, the attribute height wins and the ratio is ignored. Write `height: auto` after the include.
+
+**`before`**
+
+- With no argument no `content` is emitted, so the pseudo-element does not render unless the block sets `content`. Pass `""` for an empty one.
+
+**`breakpoint`**
+
+- With one argument the query matches exactly that width, `(width: 768px)`, which is a single pixel. Use `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`**
+
+- An element does not match a `@container` query that reads its own container, and nothing warns. Put the `container-query` on a descendant.
+
+**`counter`**
+
+- 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.
+
+**`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".
+
+**`remove`**
+
+- With one argument the element is hidden at exactly that width, `(width: 768px)`, which is a single pixel. Use `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
 
 | Signature | What it does |
@@ -109,7 +150,7 @@ a dropped declaration rather than an error.
 | `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-dots($color: null, $size: 1em, $gutter: null, $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. |
@@ -122,20 +163,23 @@ 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. |
 | `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. |
-| `remove($params...)` | Hides an element outright, or only within a breakpoint range. |
+| `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. |
 | `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. |
@@ -166,6 +210,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. |
@@ -180,7 +225,7 @@ and camelCase is what tells them apart from the kebab-case mixins above.
 | `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. |
+| `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. |