feat: Parse and set block-interface-index

- When processing definition files, recognize and set the interface
index on style nodes in the Block. As with block-class, if each style
node found has not declared an interface-index by the end of processing,
it's an error.
- Test coverage for ensuring block-interface-index is declared.

Author: Timothy Lindvall

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

@@ -6,6 +6,7 @@ import { Options, ResolvedConfiguration, resolveConfiguration } from "../configu
 import { CssBlockError } from "../errors";
 import { FileIdentifier } from "../importing";
 
+import { addInterfaceIndexes } from "./features/add-interface-indexes";
 import { addPresetSelectors } from "./features/add-preset-selectors";
 import { assertForeignGlobalAttribute } from "./features/assert-foreign-global-attribute";
 import { composeBlock } from "./features/composes-block";
@@ -152,7 +153,9 @@ export class BlockParser {
       // Find any block-class rules and override the class name of the block with its value.
       debug(" - Process Preset Block Classes");
       await addPresetSelectors(configuration, root, block, debugIdent);
-      // TODO: Process block-interface-index declarations. (And inherited-styles???)
+      debug(" - Process Preset Interface Indexes");
+      await addInterfaceIndexes(configuration, root, block, debugIdent);
+      // TODO: Process inherited-styles?
     }
 
     // Return our fully constructed block.

packages/@css-blocks/core/src/BlockParser/features/add-interface-indexes.ts

@@ -0,0 +1,73 @@
+import { postcss } from "opticss";
+
+import { Block } from "../../BlockTree";
+import { Configuration } from "../../configuration";
+import { CssBlockError } from "../../errors";
+import { sourceRange } from "../../SourceLocation";
+import { getStyleTargets } from "../block-intermediates";
+import { stripQuotes } from "../utils";
+
+/**
+ * Traverse a definition file's rules and define a preset block-class for each
+ * rule present. This ensures the block uses the same CSS class as defined in
+ * the linked Compiled CSS file associated with this definition file.
+ *
+ * If a given rule does not have a block-class declared, an error is added to
+ * the block for the user to correct.
+ *
+ * This should only be run on definition files! Standard block files aren't
+ * allowed to define block-class rules.
+ *
+ * @param configuration - The current CSS Blocks configuration.
+ * @param root - The root of the AST that this block was generated from.
+ * @param block - The block that's being generated.
+ * @param file - The definition file this block was generated from.
+ */
+export function addInterfaceIndexes(configuration: Configuration, root: postcss.Root, block: Block, file: string) {
+  // For each rule declared in the file...
+  root.walkRules(rule => {
+
+    // Find the block-class declaration...
+    rule.walkDecls("block-interface-index", decl => {
+      const val = stripQuotes(decl.value);
+
+      // The value of block-interface-index should be numeric.
+      const parsedIndex = parseInt(val, 10);
+      if (isNaN(parsedIndex)) {
+        block.addError(
+          new CssBlockError(
+            "block-interface-index must be a number.",
+            sourceRange(configuration, root, file, decl),
+          ),
+        );
+      }
+
+      // Set the index on the related style node.
+      const parsedSelectors = block.getParsedSelectors(rule);
+      parsedSelectors.forEach(sel => {
+        const styleTarget = getStyleTargets(block, sel.key);
+        if (styleTarget.blockAttrs.length > 0) {
+          styleTarget.blockAttrs[0].index = parsedIndex;
+        } else if (styleTarget.blockClasses.length > 0) {
+          styleTarget.blockClasses[0].index = parsedIndex;
+        } else {
+          throw new Error(`Couldn\'t find style node corresponding to selector ${sel}. This shouldn't happen.`);
+        }
+      });
+    });
+  });
+
+  // At this point, every style node should have a fixed block-class.
+  block.all(true).forEach(styleNode => {
+    if (!styleNode.wasIndexReset) {
+      block.addError(
+        new CssBlockError(
+          `Style node ${styleNode.asSource()} doesn't have a preset interface index after parsing definition file. You may need to declare this style node in the definition file.`,
+          {
+            filename: file,
+          },
+        ),
+      );
+    }
+  });
+}

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

@@ -31,7 +31,45 @@ export abstract class Style<
 
   // tslint:disable-next-line:prefer-unknown-to-any
   public abstract readonly rulesets: RulesetContainer<any>;
-  public readonly index: number;
+
+  /**
+   * The interface index for this style node. A default one is provided
+   * when the style node is constructed, but may be reset to a specific
+   * value later (such as when reading the block-interface-index decl
+   * in definition files).
+   */
+  private _index: number;
+
+  /**
+   * Whether the interface index for this style node was set to a specific
+   * value after it was created. Used for error detection when parsing
+   * definition files.
+   */
+  private _wasIndexReset = false;
+
+  /**
+   * The interface index for this style node.
+   */
+  get index() {
+    return this._index;
+  }
+
+  /**
+   * Sets the interface index for this style node to a specific value.
+   */
+  set index(val: number) {
+    this._index = val;
+    this._wasIndexReset = true;
+  }
+
+  /**
+   * Whether the interface index for this style node has been reset from
+   * its original value (usually from a declared block-interface-index in
+   * a definition file).
+   */
+  get wasIndexReset() {
+    return this._wasIndexReset;
+  }
 
   /**
    * The preset selector for this particular class node.
@@ -44,7 +82,7 @@ export abstract class Style<
    */
   constructor(name: string, parent: Parent, index: number) {
     super(name, parent);
-    this.index = index;
+    this._index = index;
   }
 
   /**

packages/@css-blocks/core/test/BlockParser/definition-file-processing-test.ts

@@ -112,6 +112,27 @@ export class DefinitionFileProcessing extends BEMProcessor {
     );
   }
 
+  @test "It errors out if :scope selector doesn't declare a block-interface-index"() {
+    const registry = new MockImportRegistry();
+    registerReferencedSources(registry);
+
+    const filename = "foo/bar/nav.block.css";
+    const inputCss = `@block-syntax-version: 1;
+                      :scope { block-id: "7d97e"; block-name: nav; block-class: "nav-7d97e"; }`;
+    const parseConfig = {
+      importer: registry.importer(),
+    };
+    const mockConfigOpts = {
+      dfnFiles: [filename],
+    };
+
+    return assertError(
+      CssBlockError,
+      "Style node :scope doesn't have a preset interface index after parsing definition file. You may need to declare this style node in the definition file. (foo/bar/nav.block.css)",
+      this.process(filename, inputCss, parseConfig, mockConfigOpts),
+    );
+  }
+
   @test "It errors out if an element doesn't declare a block class"() {
     const registry = new MockImportRegistry();
     registerReferencedSources(registry);
@@ -135,6 +156,29 @@ export class DefinitionFileProcessing extends BEMProcessor {
     );
   }
 
+  @test "It errors out if an element doesn't declare an interface-index"() {
+    const registry = new MockImportRegistry();
+    registerReferencedSources(registry);
+
+    const filename = "foo/bar/nav.block.css";
+    const inputCss = `@block-syntax-version: 1;
+                      :scope { block-id: "7d97e"; block-class: nav-7d97e; block-name: nav; block-interface-index: 0; }
+                      .entry { block-class: nav-7d97e__entry; }
+                      .entry[active] { block-interface-index: 2; block-class: nav-7d97e__entry--active;}`;
+    const parseConfig = {
+      importer: registry.importer(),
+    };
+    const mockConfigOpts = {
+      dfnFiles: [filename],
+    };
+
+    return assertError(
+      CssBlockError,
+      "Style node .entry doesn't have a preset interface index after parsing definition file. You may need to declare this style node in the definition file. (foo/bar/nav.block.css)",
+      this.process(filename, inputCss, parseConfig, mockConfigOpts),
+    );
+  }
+
   @test "It errors out if a modifier doesn't declare a block class"() {
     const registry = new MockImportRegistry();
     registerReferencedSources(registry);
@@ -158,6 +202,29 @@ export class DefinitionFileProcessing extends BEMProcessor {
     );
   }
 
+  @test "It errors out if a modifier doesn't declare an interface index"() {
+    const registry = new MockImportRegistry();
+    registerReferencedSources(registry);
+
+    const filename = "foo/bar/nav.block.css";
+    const inputCss = `@block-syntax-version: 1;
+                      :scope { block-id: "7d97e"; block-class: nav-7d97e; block-name: nav; block-interface-index: 0; }
+                      .entry { block-interface-index: 1; block-class: nav-7d97e__entry; }
+                      .entry[active] { block-class: nav-7d97e__entry--active; }`;
+    const parseConfig = {
+      importer: registry.importer(),
+    };
+    const mockConfigOpts = {
+      dfnFiles: [filename],
+    };
+
+    return assertError(
+      CssBlockError,
+      "Style node .entry[active] doesn't have a preset interface index after parsing definition file. You may need to declare this style node in the definition file. (foo/bar/nav.block.css)",
+      this.process(filename, inputCss, parseConfig, mockConfigOpts),
+    );
+  }
+
   @test "It errors out if a declared block-class isn't a valid class name"() {
     const registry = new MockImportRegistry();
     registerReferencedSources(registry);
@@ -178,4 +245,25 @@ export class DefinitionFileProcessing extends BEMProcessor {
       this.process(filename, inputCss, parseConfig, mockConfigOpts),
     );
   }
+
+  @test "It errors out if a declared block-interface-index isn't a valid number"() {
+    const registry = new MockImportRegistry();
+    registerReferencedSources(registry);
+
+    const filename = "foo/bar/nav.block.css";
+    const inputCss = `@block-syntax-version: 1;
+                      :scope { block-id: "7d97e"; block-class: nav-7d97e; block-name: nav; block-interface-index: hello; }`;
+    const parseConfig = {
+      importer: registry.importer(),
+    };
+    const mockConfigOpts = {
+      dfnFiles: [filename],
+    };
+
+    return assertError(
+      CssBlockError,
+      "block-interface-index must be a number. (foo/bar/nav.block.css:2:92)",
+      this.process(filename, inputCss, parseConfig, mockConfigOpts),
+    );
+  }
 }