gerillass 1.3.3 → 1.5.0

package/README.md

@@ -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
 

package/package.json

@@ -5,8 +5,18 @@
   "homepage": "https://gerillass.com",
   "author": "Halil İbrahim Çakıroğlu",
   "main": "scss/_gerillass.scss",
+  "exports": {
+    ".": {
+      "sass": "./scss/_gerillass.scss",
+      "default": "./scss/_gerillass.scss"
+    },
+    "./*": {
+      "sass": "./*",
+      "default": "./*"
+    }
+  },
   "license": "Apache-2.0",
-  "version": "1.3.3",
+  "version": "1.5.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/selfishprimate/gerillass.git"

package/scss/_gerillass-prefix.scss

@@ -961,27 +961,7 @@
   &::before {
     content: "";
     display: block;
-    @if not $ratio {
-      padding-top: 56.25%;
-    } @else if $ratio {
-      @if type-of($ratio) == string {
-        $width: null;
-        $height: null;
-        @if str-index($ratio, "/") {
-          $fslash-index: str-index($ratio, "/");
-          $width: __convertToNumber(str-slice($ratio, 1, $fslash-index - 1));
-          $height: __convertToNumber(str-slice($ratio, $fslash-index + 1));
-        } @else if str-index($ratio, ":") {
-          $colon-index: str-index($ratio, ":");
-          $width: __convertToNumber(str-slice($ratio, 1, $colon-index - 1));
-          $height: __convertToNumber(str-slice($ratio, $colon-index + 1));
-        }
-        $calc: math.div($height, $width) * 100;
-        padding-top: #{$calc * 1%};
-      } @else if type-of($ratio) == number {
-        padding-top: math.div(1, $ratio) * 100%;
-      }
-    }
+    padding-top: __validateRatio($ratio);
   }
   & > * {
     width: 100%;
@@ -1115,27 +1095,7 @@
   &::before {
     content: "";
     display: block;
-    @if not $ratio {
-      padding-top: 56.25%;
-    } @else if $ratio {
-      @if type-of($ratio) == string {
-        $width: null;
-        $height: null;
-        @if str-index($ratio, "/") {
-          $fslash-index: str-index($ratio, "/");
-          $width: __convertToNumber(str-slice($ratio, 1, $fslash-index - 1));
-          $height: __convertToNumber(str-slice($ratio, $fslash-index + 1));
-        } @else if str-index($ratio, ":") {
-          $colon-index: str-index($ratio, ":");
-          $width: __convertToNumber(str-slice($ratio, 1, $colon-index - 1));
-          $height: __convertToNumber(str-slice($ratio, $colon-index + 1));
-        }
-        $calc: math.div($height, $width) * 100;
-        padding-top: #{$calc * 1%};
-      } @else if type-of($ratio) == number {
-        padding-top: math.div(1, $ratio) * 100%;
-      }
-    }
+    padding-top: __validateRatio($ratio);
   }
   & > * {
     width: 100%;

package/scss/_gerillass.scss

@@ -38,6 +38,7 @@
 @import "utilities/shorthand-property";
 @import "utilities/validate-breakpoint";
 @import "utilities/validate-length";
+@import "utilities/validate-ratio";
 @import "utilities/validate-scissors";
 
 @import "library/adaptive";

package/scss/library/_ratio-box.scss

@@ -5,27 +5,7 @@
   &::before {
     content: "";
     display: block;
-    @if not $ratio {
-      padding-top: 56.25%;
-    } @else if $ratio {
-      @if type-of($ratio) == string {
-        $width: null;
-        $height: null;
-        @if str-index($ratio, "/") {
-          $fslash-index: str-index($ratio, "/");
-          $width: __convertToNumber(str-slice($ratio, 1, $fslash-index - 1));
-          $height: __convertToNumber(str-slice($ratio, $fslash-index + 1));
-        } @else if str-index($ratio, ":") {
-          $colon-index: str-index($ratio, ":");
-          $width: __convertToNumber(str-slice($ratio, 1, $colon-index - 1));
-          $height: __convertToNumber(str-slice($ratio, $colon-index + 1));
-        }
-        $calc: math.div($height, $width) * 100;
-        padding-top: #{$calc * 1%};
-      } @else if type-of($ratio) == number {
-        padding-top: math.div(1, $ratio) * 100%;
-      }
-    }
+    padding-top: __validateRatio($ratio);
   }
   & > * {
     width: 100%;

package/scss/library/_responsive-video.scss

@@ -5,27 +5,7 @@
   &::before {
     content: "";
     display: block;
-    @if not $ratio {
-      padding-top: 56.25%;
-    } @else if $ratio {
-      @if type-of($ratio) == string {
-        $width: null;
-        $height: null;
-        @if str-index($ratio, "/") {
-          $fslash-index: str-index($ratio, "/");
-          $width: __convertToNumber(str-slice($ratio, 1, $fslash-index - 1));
-          $height: __convertToNumber(str-slice($ratio, $fslash-index + 1));
-        } @else if str-index($ratio, ":") {
-          $colon-index: str-index($ratio, ":");
-          $width: __convertToNumber(str-slice($ratio, 1, $colon-index - 1));
-          $height: __convertToNumber(str-slice($ratio, $colon-index + 1));
-        }
-        $calc: math.div($height, $width) * 100;
-        padding-top: #{$calc * 1%};
-      } @else if type-of($ratio) == number {
-        padding-top: math.div(1, $ratio) * 100%;
-      }
-    }
+    padding-top: __validateRatio($ratio);
   }
   & > * {
     width: 100%;

package/scss/utilities/_validate-ratio.scss

@@ -0,0 +1,42 @@
+@charset "UTF-8";
+
+@function __validateRatio($ratio) {
+  // No argument at all keeps the 16/9 default.
+  @if $ratio == null {
+    @return 56.25%;
+  }
+
+  @if type-of($ratio) == "number" {
+    @if not unitless($ratio) {
+      @error "`#{$ratio}` is not a valid ratio. A numeric ratio must be unitless, like `1.77`.";
+    }
+    @if $ratio <= 0 {
+      @error "`#{$ratio}` is not a valid ratio. A numeric ratio must be greater than zero.";
+    }
+    @return math.div(1, $ratio) * 100%;
+  }
+
+  @if type-of($ratio) == "string" {
+    $separator: null;
+    @if str-index($ratio, "/") {
+      $separator: str-index($ratio, "/");
+    } @else if str-index($ratio, ":") {
+      $separator: str-index($ratio, ":");
+    } @else {
+      @error "`#{$ratio}` is not a valid ratio. A string ratio must separate width and height with `/` or `:`, like `\"16/9\"` or `\"16:9\"`.";
+    }
+
+    $width: __convertToNumber(str-slice($ratio, 1, $separator - 1));
+    $height: __convertToNumber(str-slice($ratio, $separator + 1));
+
+    @if $width == 0 {
+      @error "`#{$ratio}` is not a valid ratio. The width must be greater than zero.";
+    }
+    @return math.div($height, $width) * 100%;
+  }
+
+  // Anything else -- most commonly a list, which is what `16/9` becomes once
+  // Dart Sass 2.0.0 removes slash division. Without this the mixin would emit
+  // no padding-top at all and silently produce a ratio box with no ratio.
+  @error "`#{$ratio}` is not a valid ratio. Pass a string like `\"16/9\"` or `\"16:9\"`, a unitless number like `1.77`, or no argument at all for the 16/9 default. You passed a #{type-of($ratio)}.";
+}