gerillass 2.1.0 → 2.2.0

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: 53 mixins and 23 functions that emit CSS from
+A Sass mixin library: 56 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,6 +76,7 @@ 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); }` |
@@ -83,16 +84,19 @@ a dropped declaration rather than an error.
 | `container` | `.card { @include container("card", sideways); }` |
 | `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"); }` |
 | `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; } }` |
 | `radial-gradient` | `.a { @include radial-gradient(42, "center", (red, blue)); }` |
 | `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); }` |
@@ -100,8 +104,53 @@ a dropped declaration rather than an error.
 | `text-gradient` | `.a { @include text-gradient(sideways, (red, blue)); }` |
 | `text-selection` | `.a { @include text-selection(bogus) { background: yellow; } }` |
 | `text-shadow` | `.a { @include text-shadow(42); }` |
+| `tokens` | `:root { @include tokens(#fff); }` |
 | `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, 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.
+- 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.
+
+**`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".
+
+**`motion-safe`**
+
+- 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.
+
+**`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.
+- 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 |
@@ -112,7 +161,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. |
@@ -131,17 +180,19 @@ a dropped declaration rather than an error.
 | `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. |
+| `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. |
 | `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)` | 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, 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. |
 | `resizable($direction: both, $overflow: auto)` | Makes an element user-resizable. |
@@ -158,6 +209,7 @@ a dropped declaration rather than an error.
 | `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. |
+| `tokens($map, $prefix: null)` | Writes a Sass map out as CSS custom properties, for any kind of token: colours, spacing, sizes, radii, type, shadows, durations. With the prefix space, (4: 1rem) becomes --space-4: 1rem. A null value is skipped, and a quoted string keeps its quotes. |
 | `triangle($direction: "bottom", $color: black, $size: 10px 8px)` | Draws a CSS triangle out of borders, pointing in a given direction. |
 
 ## Functions
@@ -187,7 +239,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. |