feat: Optional Preprocessors & library/application API contract.

There is now a core data type for preprocessors that conditionally process
a stylesheet. The motivation for this is to allow libraries to expose a
preprocessor integration for their specific Sass + Eyeglass library.

This allows the library to maintain some semblance of control over how
the compilation is performed, in case that is important to that module
(E.g. the precision value for Sass or exposing assets via eyeglass).

There's a base class for libraries to use (`DirectoryScopedPreprocessor`),
and a helper function for applications that integrates all of the
preprocessor adaptors into a single processor that supplies sass,
eyeglass, and application default options.

If the `DirectoryScopedPreprocessor` isn't sufficient for a library's
needs, they can implement the `PreprocessorProvider` interface.

Applications can use the simpler, `OptionalAdaptor` function for
creating their own optional adaptors for preprocessing their own block
files in different ways.

The README for `@css-blocks/eyeglass` is updated to include boilerplate
code that libraries and applications can use to get started.

Author: chriseppstein

packages/@css-blocks/core/src/BlockParser/index.ts

@@ -11,6 +11,8 @@ export { BlockFactory } from "./BlockFactory";
 
 export {
   Syntax,
+  Preprocessor,
+  OptionalPreprocessor,
   Preprocessors,
   ProcessedFile,
 } from "./preprocessing";

packages/@css-blocks/core/src/BlockParser/preprocessing.ts

@@ -42,7 +42,8 @@ export interface ProcessedFile {
 }
 
 // export type ContentPreprocessor = (content: string) => Promise<ProcessedFile>;
-export type Preprocessor = (fullPath: string, content: string, configuration: ResolvedConfiguration, sourceMap?: RawSourceMap | string) => Promise<ProcessedFile>;
+export type Preprocessor<R extends ProcessedFile | null = ProcessedFile> = (fullPath: string, content: string, configuration: ResolvedConfiguration, sourceMap?: RawSourceMap | string) => Promise<R>;
+export type OptionalPreprocessor = Preprocessor<ProcessedFile | null>;
 
 /**
  * A map of supported syntaxes to the preprocessor function for that syntax.

packages/@css-blocks/core/src/BlockTree/RulesetContainer.ts

@@ -100,6 +100,8 @@ export class RulesetContainer<S extends Styles> {
     let style = this.parent;
     let selectors: ParsedSelector[] = style.getParsedSelectors(rule);
 
+    // XXX I think this is wrong. if the selectors target different styles it
+    // will get confused. Need to add tests for that.
     selectors.forEach((selector) => {
       let ruleSet = new Ruleset(file, rule, style);
       let key = selector.key;

packages/@css-blocks/eyeglass/README.md

@@ -7,7 +7,7 @@ This package provides an easy way to integrate your CSS Blocks code with the Sas
 
 ## Usage
 
-Here's an example `css-blocks.config.js` file using this package. 
+Here's an example `css-blocks.config.js` file using this package.
 
 ```js
 import sass from "node-sass";
@@ -25,4 +25,69 @@ module.exports = {
 };
 ```
 
-An important thing to notice here is that this adapter _does not provide Eyeglass for you_. Instead we use the module instance you pass into the adaptor. This means you're not tied whatever version of Eyeglass (or Sass) this package would include!
+## Building npm libraries that provide css-blocks written in Sass
+
+If your addon provides CSS Block files that are written with Sass it will
+require the application that uses your addon to include Sass preprocessing in
+its configuration.
+
+In turn, so the addon can maintain control over the preprocessing configuration
+that is used we recommend that your addon ship an "optional adaptor" that
+looks like this:
+
+```ts
+import { DirectoryScopedPreprocessor } from "@css-blocks/eyeglass";
+
+// a path to where your block files live
+const ADDON_DIR = path.resolve(__dirname, "..", "..") + "/";
+class MyModulesPreprocessor extends DirectoryScopedPreprocessor {
+  setupOptions(options: EyeglassOptions): EyeglassOptions {
+    // Don't manipulate the options passed in.
+    return Object.assign({}, options, {precision: 20});
+  }
+}
+
+export const adaptor = new MyModulesPreprocessor(ADDON_DIR);
+```
+
+## Building applications that consume Sass-preprocessed css-blocks
+
+If your application consumes CSS Block files that are written with Sass
+you'll need to work with any adaptors provided by the extensions you're
+using. This css-blocks/eyeglass integration provides a helper function that
+will select the correct processor for the block file being processed or
+fall back to a default sass processor.
+
+This css-blocks configuration file is an example of how to consume the
+eyeglass adaptors from other libraries that use this integration.
+
+```ts
+// css-blocks.config.js
+
+const sass = require("node-sass");
+const Eyeglass = require("eyeglass");
+import { adaptAll } from "@css-blocks/eyeglass";
+
+// See the documentation for your module to know how to import
+// its adaptors.
+import { adaptor as fancyAdaptor } from "fancy-module";
+import { adaptor as anotherAdaptor } from "another-package";
+
+const sassOptions = {
+  // The default sass and eyeglass options for your application.
+  // Where important, these options might be overridden by the module itself.
+};
+
+// While it's probably irrelevant, the order of the adaptors here
+// does matter, the first one that wants to process a file will win.
+const eyeglassAdaptors = [
+  fancyAdaptor,
+  anotherAdaptor,
+];
+
+export default {
+  preprocesors: {
+    scss: adaptAll(eyeglassAdaptors, sass, eyeglass, sassOptions),
+  }
+};
+```

packages/@css-blocks/eyeglass/src/index.ts

@@ -1,18 +1,30 @@
-import { ProcessedFile } from "@css-blocks/core";
-import Eyeglass from "eyeglass"; // works, even tho a cjs export. huh.
-import { Options, Result, SassError } from "node-sass";
-import SassImplementation from "node-sass";
+import type { OptionalPreprocessor, Preprocessor, ProcessedFile, ResolvedConfiguration } from "@css-blocks/core";
+import type { EyeglassOptions, default as Eyeglass } from "eyeglass"; // works, even tho a cjs export. huh.
+import type { Result, SassError } from "node-sass";
+import type SassImplementation from "node-sass";
+import { sep as PATH_SEPARATOR } from "path";
 
-export function adaptor(sass: typeof SassImplementation, eyeglass: typeof Eyeglass, options: Options = {}) {
+export type Adaptor = (sass: typeof SassImplementation, eyeglass: typeof Eyeglass, options: EyeglassOptions) => Preprocessor;
+export type OptionalAdaptor = (sass: typeof SassImplementation, eyeglass: typeof Eyeglass, options: EyeglassOptions) => OptionalPreprocessor;
+
+/**
+ * Given a Sass compiler (either dart-sass or node-sass), an Eyeglass
+ * constructor, and common eyeglass/sass options. This function returns a
+ * preprocessor, which is a function that can be used preprocess a single file.
+ *
+ * This function ensures that Sass is properly configured using the common
+ * options for each file and that source map information is passed along to CSS
+ * Blocks for correct error reporting.
+ */
+export const adaptor: Adaptor = (sass: typeof SassImplementation, eyeglass: typeof Eyeglass, options: EyeglassOptions = {}) => {
     return (file: string, data: string) => {
         return new Promise<ProcessedFile>((resolve, reject) => {
-            const sassOptions = Object.assign(options, {
+            const sassOptions = Object.assign({}, options, {
                 file,
                 data,
                 sourceMap: true,
                 outFile: file.replace(/scss$/, "css"),
             });
-
             sass.render(eyeglass(sassOptions), (err: SassError, res: Result): void => {
                 if (err) {
                     reject(err);
@@ -26,4 +38,125 @@ export function adaptor(sass: typeof SassImplementation, eyeglass: typeof Eyegla
             });
         });
     };
-  }
+};
+
+/**
+ * This is the core interface that adaptAll depends on to use an object (as
+ * opposed to an OptionalAdaptor function) to create a preprocessor.
+ */
+export interface PreprocessorProvider {
+    init(sass: typeof SassImplementation, eyeglass: typeof Eyeglass, options: EyeglassOptions): void;
+    preprocessor(): Preprocessor | OptionalPreprocessor;
+}
+
+/**
+ * Type guard to check if an object fulfills the basic interface required by
+ * PreprocessorProvider.
+ */
+function isPreprocessorProvider(obj: unknown): obj is PreprocessorProvider {
+    if (typeof obj !== "object" || obj === null) return false;
+    let provider = <PreprocessorProvider>obj;
+    return typeof provider.init === "function" && typeof provider.preprocessor === "function";
+}
+
+/**
+ * Provides a preprocessor that only runs on files within a specific directory
+ * (or subdirectories of that directory, recursively).
+ */
+export class DirectoryScopedPreprocessor implements PreprocessorProvider {
+    protected filePrefix: string;
+    protected scssProcessor: Preprocessor | undefined;
+
+    /**
+     * Instantiates the preprocessor provider.
+     *
+     * In the case where a preprocessor provider is being provided by a an npm
+     * package that is being consumed by an application, this instantiation
+     * would be performed by the npm package.
+     *
+     * @param packageDirectory The absolute path to the directory that scopes
+     * this preprocessor.
+     */
+    constructor(packageDirectory: string) {
+        this.filePrefix = packageDirectory.endsWith(PATH_SEPARATOR) ? packageDirectory : packageDirectory + PATH_SEPARATOR;
+    }
+
+    /**
+     * Initializes the sass preprocessor that is used to only compile the files
+     * that are in scope. These parameters are provided by the application,
+     * usually via adaptAll().
+     *
+     * If you need to enforce a version constraint on the Sass or Eyeglass
+     * implementation being used, you can override this and check sass.info and
+     * eyeglass.VERSION.
+     */
+    init(sass: typeof SassImplementation, eyeglass: typeof Eyeglass, options: EyeglassOptions = {}) {
+        this.scssProcessor = adaptor(sass, eyeglass, this.setupOptions(options));
+    }
+
+    /**
+     * Subclasses can override this to manipulate/override the eyeglass options
+     * provided from the application that will be used for compiling this
+     * package's block files.
+     *
+     * Note: If this is being used from a library that is an eyeglass module,
+     * The module will be auto-discovered by eyeglass, you don't need to do
+     * anything here.
+     */
+    setupOptions(options: EyeglassOptions): EyeglassOptions {
+        return options;
+    }
+
+    /**
+     * Subclasses can override this to decide whether a file should be processed.
+     * By default it just checks that the file is within the directory for this
+     * Preprocessor provider.
+     */
+    shouldProcessFile(file: string) {
+        return file.startsWith(this.filePrefix);
+    }
+
+    /**
+     * Subclasses shouldn't need to override this.
+     * @returns the preprocessor expected by adaptAll.
+     */
+    preprocessor(): OptionalPreprocessor {
+        return (file: string, data: string, config: ResolvedConfiguration) => {
+            if (!this.scssProcessor) return Promise.reject(new Error("Adaptor was not initialized!"));
+            if (this.shouldProcessFile(file)) {
+                return this.scssProcessor(file, data, config);
+            } else {
+                return Promise.resolve(null);
+            }
+        };
+    }
+}
+
+/**
+ * Creates a unified preprocessor for an application to use when consuming
+ * css blocks that have Sass preprocessed.
+ *
+ * The application provides a list of preprocessor adaptors, as well as the
+ * desired versions of sass, eyeglass and common Sass/Eyeglass options for
+ * compiling the sass files with eyeglass support.
+ */
+export function adaptAll(adaptors: Array<OptionalAdaptor | PreprocessorProvider>, sass: typeof SassImplementation, eyeglass: typeof Eyeglass, options: EyeglassOptions): Preprocessor {
+    let processors = adaptors.map(adaptor => {
+        if (isPreprocessorProvider(adaptor)) {
+            adaptor.init(sass, eyeglass, options);
+            return adaptor.preprocessor();
+        } else {
+            return adaptor(sass, eyeglass, options);
+        }
+    });
+    let lastResortProcessor = adaptor(sass, eyeglass, options);
+    return async (file: string, data: string, config: ResolvedConfiguration) => {
+        for (let processor of processors) {
+            let result = await processor(file, data, config);
+            if (result) {
+                return result;
+            }
+        }
+        return lastResortProcessor(file, data, config);
+    };
+}

packages/@css-blocks/eyeglass/test/fixtures/package-1/one.block.scss

@@ -0,0 +1,7 @@
+@mixin block($name) {
+  :root {
+    name: $name;
+  }
+}
+
+@include block("uno");

packages/@css-blocks/eyeglass/test/fixtures/package-2/two.block.scss

@@ -0,0 +1,7 @@
+@mixin block($name) {
+  :root {
+    name: $name;
+  }
+}
+
+@include block("dos");