feat: In-Stylesheet Block Composition (linkedin#229)

* feat: Track composition metadata on BlockClass.
* feat: Improved @block-debug output.
* feat: Composition conflict validation.
* feat: In-stylesheet composition template rewrites.
* fix: Update tests to use new debug output.
* fix: Fix overzealous error throwing in Glimmer analyzer.
* docs: Update readme to reflect feature status.

Author: amiller-gh

README.md

@@ -119,7 +119,7 @@ CSS Blocks is under active development and there are a number of features that h
 | ✅ | `block-name: "custom-name";` | Provide custom Block names in `:scope` for a nicer debugging experience. |
 | ✅ | `implements: block-name;` | A Block can declare that it implements one or more other Block's interfaces in its `:scope` selector and the compiler will ensure that all of those states and classes are styled locally. |
 | ✅ | `extends: block-name;` | A Block may specify it extends another Block in its `:scope` selector to inherit and extend all the class and state implementations therein. |
-| 🖌 | `apply: "block.path";` | Mixin-Style class and state composition. Apply other Blocks' Styles to one of yours.  |
+| ✅ | `composes: "block.path";` | Mixin-Style class and state composition. Apply other Blocks' Styles to one of yours.  |
 | **Functions** ||
 | ✅ | `resolve("block.path");` | Provide an explicit resolution for a given property against another Block. |
 | ❌ | `constrain(val1, val2 ... valN);` | Constrain this property to a list of specific values that may be set when this Block is extended. |

packages/@css-blocks/core/src/Analyzer/ElementAnalysis.ts

@@ -28,20 +28,26 @@ function ensureUniqueAttributeGroup(discovered: Set<Attribute>, group: Attribute
 export const attributeGroupValidator: Validator = (analysis, _templateAnalysis, err) => {
   let discovered: Set<Attribute> = new Set();
   for (let o of analysis.static) {
-    if (isAttrValue(o)) {
+    if (isAttrValue(o) && !analysis.isFromComposition(o)) {
       ensureUniqueAttributeGroup(discovered, o.attribute, err, true);
     }
   }
   for (let stat of analysis.dynamicAttributes) {
     if (isBooleanAttr(stat)) {
-      ensureUniqueAttributeGroup(discovered, stat.value.attribute, err, true);
+      for (let val of stat.value) {
+        if (isAttrValue(val) && !analysis.isFromComposition(val)) {
+          ensureUniqueAttributeGroup(discovered, val.attribute, err, true);
+        }
+      }
     }
     if (isAttrGroup(stat)) {
       let tmp: Set<Attribute> = new Set();
       for (let key of Object.keys(stat.group)) {
         let attr = stat.group[key];
-        let values = ensureUniqueAttributeGroup(discovered, attr.attribute, err, false);
-        values.forEach((o) => tmp.add(o));
+        if (isAttrValue(attr) && !analysis.isFromComposition(attr)) {
+          let values = ensureUniqueAttributeGroup(discovered, attr.attribute, err, false);
+          values.forEach((o) => tmp.add(o));
+        }
       }
       unionInto(discovered, tmp);
     }

packages/@css-blocks/core/src/Analyzer/validations/attribute-group-validator.ts

@@ -8,7 +8,7 @@ import { Validator } from "./Validator";
 
 export const attributeParentValidator: Validator = (analysis, _templateAnalysis, err) => {
   for (let attr of analysis.attributesFound()) {
-    if (!analysis.hasClass(attr.blockClass)) {
+    if (!analysis.hasClass(attr.blockClass) && !analysis.isFromComposition(attr.blockClass)) {
       err(`Cannot use state "${attr.asSource()}" without parent ` +
           `${ attr.blockClass.isRoot ? "block" : "class" } also applied or implied by another style.`);
     }

packages/@css-blocks/core/src/Analyzer/validations/attribute-parent-validator.ts

@@ -9,10 +9,10 @@ import { ErrorCallback, Validator } from "./Validator";
  */
 
 export const classPairsValidator: Validator = (analysis, _templateAnalysis, err) => {
-  // TODO: this doesn't work for dynamic classes
   let classPerBlock: Map<Block, BlockClass> = new Map();
   for (let container of analysis.classesFound(false)) {
     if (isBlockClass(container)) {
+      if (analysis.isFromComposition(container)) { continue; }
       for (let block of checkExisting(classPerBlock, classPerBlock, container, err)) {
         classPerBlock.set(block, container);
       }
@@ -22,6 +22,7 @@ export const classPairsValidator: Validator = (analysis, _templateAnalysis, err)
     let trueBlocks = new Map<Block, BlockClass>();
     if (isTrueCondition(dyn)) {
       for (let container of dyn.whenTrue) {
+        if (analysis.isFromComposition(container)) { continue; }
         if (isBlockClass(container)) {
           let blocks = checkExisting(classPerBlock, trueBlocks, container, err);
           for (let block of blocks) { trueBlocks.set(block, container); }
@@ -32,6 +33,7 @@ export const classPairsValidator: Validator = (analysis, _templateAnalysis, err)
     if (isFalseCondition(dyn)) {
       for (let container of dyn.whenFalse) {
         if (isBlockClass(container)) {
+          if (analysis.isFromComposition(container)) { continue; }
           let blocks = checkExisting(classPerBlock, falseBlocks, container, err);
           for (let block of blocks) { trueBlocks.set(block, container); }
         }

packages/@css-blocks/core/src/Analyzer/validations/class-pairs-validator.ts

@@ -1,9 +1,10 @@
-import { MultiMap, TwoKeyMultiMap, objectValues } from "@opticss/util";
+import { MultiMap, TwoKeyMultiMap, objectValues, whatever } from "@opticss/util";
 import * as propParser from "css-property-parser";
 import { postcss } from "opticss";
 
-import { Ruleset, Style } from "../../BlockTree";
+import { AttrValue, BlockClass, Ruleset, Style, isBlockClass } from "../../BlockTree";
 import {
+  ElementAnalysis,
   isAttrGroup,
   isBooleanAttr,
   isFalseCondition,
@@ -122,6 +123,21 @@ function printRulesetConflict(prop: string, rule: Ruleset) {
   return out.join("\n");
 }
 
+function inStylesheetComposition(
+  blockClass: BlockClass,
+  analysis: ElementAnalysis<whatever, whatever, whatever>,
+  conflicts: ConflictMap,
+  allConditions: PropMap,
+) {
+  composed: for (let composed of blockClass.composedStyles()) {
+    for (let condition of composed.conditions) {
+      if (!analysis.hasAttribute(condition)) { break composed; }
+    }
+    evaluate(composed.style, allConditions, conflicts);
+    add(allConditions, composed.style);
+  }
+}
+
 /**
  * Prevent conflicting styles from being applied to the same element without an explicit resolution.
  * @param correlations The correlations object for a given element.
@@ -139,6 +155,10 @@ export const propertyConflictValidator: Validator = (elAnalysis, _templateAnalys
   elAnalysis.static.forEach((obj) => {
     evaluate(obj, allConditions, conflicts);
     add(allConditions, obj);
+
+    // TODO: When we unify Element Analysis and Stylesheet Composition concepts, this check
+    //       can happen in another location during the BlockParse instead of Template Validation.
+    if (isBlockClass(obj)) { inStylesheetComposition(obj, elAnalysis, conflicts, allConditions); }
   });
 
   // For each dynamic class, test it against the static classes,
@@ -182,8 +202,10 @@ export const propertyConflictValidator: Validator = (elAnalysis, _templateAnalys
     }
 
     else if (isBooleanAttr(condition)) {
-      evaluate(condition.value, allConditions, conflicts);
-      add(allConditions, condition.value);
+      for (let val of condition.value) {
+        evaluate(val as AttrValue, allConditions, conflicts);
+        add(allConditions, val as AttrValue);
+      }
     }
   });
 
@@ -194,7 +216,7 @@ export const propertyConflictValidator: Validator = (elAnalysis, _templateAnalys
 
   // For every set of conflicting properties, throw the error.
   if (conflicts.size) {
-    let msg = "The following property conflicts must be resolved for these co-located Styles:";
+    let msg = "The following property conflicts must be resolved for these composed Styles:";
     let details = "\n";
     for (let [prop, matches] of conflicts.entries()) {
       if (!prop || !matches.length) { return; }

packages/@css-blocks/core/src/Analyzer/validations/property-conflict-validator.ts

@@ -14,7 +14,7 @@ export const rootClassValidator: Validator = (analysis, templateAnalysis, err) =
       foundClass = foundClass || !container.isRoot;
     }
     if (foundRoot && foundClass) {
-      err(`Cannot put block classes on the block's root element`);
+      err(`Cannot put Block classes on the Block's root element.`);
     }
   }
 };

packages/@css-blocks/core/src/Analyzer/validations/root-class-validator.ts

@@ -75,8 +75,8 @@ export class BlockCompiler {
     root.walkAtRules(BLOCK_DEBUG, (atRule) => {
       let {block: ref, channel} = parseBlockDebug(atRule, sourceFile, block);
       if (channel === "comment") {
-        let debugStr = ref.debug(this.config);
-        atRule.replaceWith(this.postcss.comment({text: debugStr.join("\n   ")}));
+        let text = `${ref.debug(this.config).join("\n * ")}\n`;
+        atRule.replaceWith(this.postcss.comment({ text }));
       } else {
         // stderr/stdout are emitted during parse.
         atRule.remove();

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

@@ -7,6 +7,7 @@ import * as errors from "../errors";
 import { FileIdentifier } from "../importing";
 
 import { assertForeignGlobalAttribute } from "./features/assert-foreign-global-attribute";
+import { composeBlock } from "./features/composes-block";
 import { constructBlock } from "./features/construct-block";
 import { disallowImportant } from "./features/disallow-important";
 import { discoverName } from "./features/discover-name";
@@ -98,6 +99,8 @@ export class BlockParser {
     // Validate that all required Styles are implemented.
     debug(` - Implement Block`);
     await implementBlock(root, block, debugIdent);
+    // Register all block compositions.
+    await composeBlock(root, block, debugIdent);
     // Log any debug statements discovered.
     debug(` - Process Debugs`);
     await processDebugStatements(root, block, debugIdent, this.config);

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

@@ -1,7 +1,8 @@
 import { assertNever, whatever } from "@opticss/util";
-import { postcssSelectorParser as selectorParser } from "opticss";
+import { CompoundSelector, postcssSelectorParser as selectorParser } from "opticss";
 
 import { ATTR_PRESENT, AttrToken, ROOT_CLASS, STATE_NAMESPACE } from "../BlockSyntax";
+import { AttrValue, Block, BlockClass } from "../BlockTree";
 
 export enum BlockType {
   block = 1,
@@ -127,3 +128,44 @@ export const isClassNode = selectorParser.isClassName;
 export function isAttributeNode(node: selectorParser.Node): node is selectorParser.Attribute {
   return selectorParser.isAttribute(node) && node.namespace === STATE_NAMESPACE;
 }
+
+/**
+ * Describes all possible terminating styles in a CSS Blocks selector.
+ */
+export interface StyleTargets {
+  blockAttrs: AttrValue[];
+  blockClasses: BlockClass[];
+}
+
+/**
+ * Given a Block and ParsedSelector, return all terminating Style objects.
+ * These may be either a single `BlockClass` or 1 to many `AttrValue`s.
+ * @param block The Block to query against.
+ * @param sel The ParsedSelector
+ * @returns The array of discovered Style objects.
+ */
+export function getStyleTargets(block: Block, sel: CompoundSelector): StyleTargets {
+  let blockAttrs: AttrValue[] = [];
+  let blockClass: BlockClass | undefined = undefined;
+
+  for (let node of sel.nodes) {
+    if (isRootNode(node)) {
+      blockClass = block.rootClass;
+    }
+    else if (isClassNode(node)) {
+      blockClass = block.ensureClass(node.value);
+    }
+    else if (isAttributeNode(node)) {
+      // The fact that a base class exists for all state selectors is
+      // validated in `assertBlockObject`. BlockClass may be undefined
+      // here if parsing a global state.
+      if (!blockClass) { continue; }
+      blockAttrs.push(blockClass.ensureAttributeValue(toAttrToken(node)));
+    }
+  }
+
+  return {
+    blockAttrs,
+    blockClasses: blockClass ? [ blockClass ] : [],
+  };
+}

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

@@ -0,0 +1,47 @@
+import { postcss } from "opticss";
+import { isRule } from "opticss/dist/src/util/cssIntrospection";
+
+import { COMPOSES } from "../../BlockSyntax";
+import { Block } from "../../BlockTree";
+import * as errors from "../../errors";
+import { sourceLocation } from "../../SourceLocation";
+import { getStyleTargets } from "../block-intermediates";
+import { stripQuotes } from "../utils";
+
+/**
+ * For each `composes` property found in the passed ruleset, track the foreign
+ * block. If block is not found, throw.
+ * @param block  Block object being processed
+ * @param sourceFile  Source file name, used for error output.
+ * @param rule Ruleset to crawl
+ */
+export async function composeBlock(root: postcss.Root, block: Block, sourceFile: string) {
+  root.walkDecls(COMPOSES, (decl) => {
+    if (!isRule(decl.parent)) { throw new errors.InvalidBlockSyntax(`The "composes" property may only be used in a rule set.`, sourceLocation(sourceFile, decl)); }
+    let rule = decl.parent;
+
+    // TODO: Move to Block Syntax as parseBlockRefList().
+    let refNames = decl.value.split(/,\s*/).map(stripQuotes);
+    for (let refName of refNames) {
+      let refStyle = block.lookup(refName);
+      if (!refStyle) {
+        throw new errors.InvalidBlockSyntax(`No style "${refName}" found.`, sourceLocation(sourceFile, decl));
+      }
+      if (refStyle.block === block) {
+        throw new errors.InvalidBlockSyntax(`Styles from the same Block may not be composed together.`, sourceLocation(sourceFile, decl));
+      }
+
+      const parsedSel = block.getParsedSelectors(rule);
+      for (let sel of parsedSel) {
+        if (sel.selector.next) {
+          throw new errors.InvalidBlockSyntax(`Style composition is not allowed in rule sets with a scope selector.`, sourceLocation(sourceFile, decl));
+        }
+        let foundStyles = getStyleTargets(block, sel.selector);
+        for (let blockClass of foundStyles.blockClasses) {
+          blockClass.addComposedStyle(refStyle, foundStyles.blockAttrs);
+        }
+      }
+    }
+    decl.remove();
+  });
+}

packages/@css-blocks/core/src/BlockParser/features/composes-block.ts

@@ -1,19 +1,19 @@
 import { CompoundSelector, ParsedSelector, postcss, postcssSelectorParser as selectorParser } from "opticss";
 
-import { Block, BlockClass, Style } from "../../BlockTree";
+import { Block, Style } from "../../BlockTree";
 import * as errors from "../../errors";
 import { selectorSourceLocation as loc, sourceLocation } from "../../SourceLocation";
 import {
   BlockType,
   NodeAndType,
   blockTypeName,
+  getStyleTargets,
   isAttributeNode,
   isClassLevelObject,
   isClassNode,
   isExternalBlock,
   isRootLevelObject,
   isRootNode,
-  toAttrToken,
 } from "../block-intermediates";
 
 const SIBLING_COMBINATORS = new Set(["+", "~"]);
@@ -71,8 +71,7 @@ export async function constructBlock(root: postcss.Root, block: Block, file: str
       while (sel) {
 
         let isKey = (keySel === sel);
-        let blockClass: BlockClass | undefined = undefined;
-        let foundStyles: Style[] = [];
+        let foundStyles = getStyleTargets(block, sel);
 
         // If this is an external Style, move on. These are validated
         // in `assert-foreign-global-attribute`.
@@ -82,26 +81,13 @@ export async function constructBlock(root: postcss.Root, block: Block, file: str
           continue;
         }
 
-        for (let node of sel.nodes) {
-          if (isRootNode(node)) {
-            blockClass = block.rootClass;
-          }
-          else if (isClassNode(node)) {
-            blockClass = block.ensureClass(node.value);
-          }
-          else if (isAttributeNode(node)) {
-            // The fact that a base class exists for all state selectors is
-            // validated in `assertBlockObject`.
-            foundStyles.push(blockClass!.ensureAttributeValue(toAttrToken(node)));
-          }
-        }
-
-        // If we haven't found any terminating states, we're targeting the discovered Block class.
-        if (blockClass && !foundStyles.length) { foundStyles.push(blockClass); }
-
         // If this is the key selector, save this ruleset on the created style.
         if (isKey) {
-          foundStyles.map(s => styleRuleTuples.add([s, rule]));
+          if (foundStyles.blockAttrs.length) {
+            foundStyles.blockAttrs.map(s => styleRuleTuples.add([s, rule]));
+          } else {
+            foundStyles.blockClasses.map(s => styleRuleTuples.add([s, rule]));
+          }
         }
 
         sel = sel.next && sel.next.selector;
@@ -110,7 +96,7 @@ export async function constructBlock(root: postcss.Root, block: Block, file: str
   });
 
   // To allow self-referential block lookup when constructing ruleset concerns,
-  // we need to run `addRuleset()` only *after* all Style have been created.
+  // we need to run `addRuleset()` only *after* all Styles have been created.
   for (let [style, rule] of styleRuleTuples) {
     style.rulesets.addRuleset(file, rule);
   }

packages/@css-blocks/core/src/BlockParser/features/construct-block.ts

@@ -6,19 +6,10 @@ import * as errors from "../../errors";
 import { sourceLocation } from "../../SourceLocation";
 
 import { BlockFactory } from "../index";
-import { parseBlockNames } from "../utils/blockNamesParser";
+import { parseBlockNames, stripQuotes } from "../utils";
 
 const FROM_EXPR = /\s+from\s+/;
 
-/**
- * Strip matching quotes from the beginning and end of a string
- * @param str String to strip quotes from
- * @return Result
- */
-function stripQuotes(str: string): string {
-  return str.replace(/^(["'])(.+)\1$/, "$2");
-}
-
 /**
  * Resolve all block references for a given block.
  * @param block Block to resolve references for
@@ -69,7 +60,6 @@ export async function exportBlocks(block: Block, factory: BlockFactory, file: st
           );
         }
         let localName = blockNames[remoteName];
-        console.log(remoteName, localName, block.identifier);
         if (!CLASS_NAME_IDENT.test(localName)) {
           throw new errors.InvalidBlockSyntax(
             `Illegal block name in export. "${localName}" is not a legal CSS identifier.`,