feat: Add style-of helper for glimmer.

There is a new synthetic helper for css-blocks in glimmer and ember applications called "style-of".

Original Specification is at: linkedin#383

The parameters and hash arguments to a style-of helper invocation are
analyzed as if the helper invocation is an element or component
invocation. The arguments to style-of can be dynamic in the same way
that attributes can be dynamic.

The return value of the style-of helper is a string that can be set to
an html class attribute. This value should be considered opaque. Do
not try to manipulate it or depend on the value inside it.

Merging the classnames from CSS Blocks with classnames from styles not
managed by CSS Blocks may result in unexpected behavior, especially with
opticss enabled.

Closes linkedin#383.

Author: chriseppstein

packages/@css-blocks/glimmer/.vscode/launch.json

@@ -10,9 +10,9 @@
       "request": "launch",
       "name": "Launch Program",
       "preLaunchTask": "compile",
-      "program": "${workspaceRoot}/node_modules/.bin/_mocha",
+      "program": "${workspaceRoot}/../../../node_modules/.bin/_mocha",
       "args": [
-        "dist/test",
+        "dist/cjs/test",
         "--opts",
         "test/mocha.opts"
       ],

packages/@css-blocks/glimmer/src/Analyzer.ts

@@ -13,8 +13,7 @@ import { TemplateIntegrationOptions } from "@opticss/template-api";
 import * as debugGenerator from "debug";
 import * as fs from "fs";
 
-import { ElementAnalyzer } from "./ElementAnalyzer";
-import { isEmberBuiltIn } from "./EmberBuiltins";
+import { ElementAnalyzer, isAnalyzedHelper } from "./ElementAnalyzer";
 import { Resolver } from "./Resolver";
 import { TEMPLATE_TYPE } from "./Template";
 
@@ -124,17 +123,15 @@ export class GlimmerAnalyzer extends Analyzer<TEMPLATE_TYPE> {
     let elementAnalyzer = new ElementAnalyzer(analysis, this.cssBlocksOptions);
     traverse(ast, {
       MustacheStatement(node: AST.MustacheStatement) {
-        const name = node.path.original;
-        if (!isEmberBuiltIn(name)) { return; }
+        if (!isAnalyzedHelper(node)) { return; }
         elementCount++;
         const atRootElement = (elementCount === 1);
         const element = elementAnalyzer.analyze(node, atRootElement);
         if (self.debug.enabled) self.debug(`{{${name}}} analyzed:`, element.class.forOptimizer(self.cssBlocksOptions).toString());
       },
 
       BlockStatement(node: AST.BlockStatement) {
-        const name = node.path.original;
-        if (!isEmberBuiltIn(name)) { return; }
+        if (!isAnalyzedHelper(node)) { return; }
         elementCount++;
         const atRootElement = (elementCount === 1);
         const element = elementAnalyzer.analyze(node, atRootElement);

packages/@css-blocks/glimmer/src/ClassnamesHelperGenerator.ts

@@ -41,7 +41,7 @@ import {
   TernaryExpression as TernaryAST,
 } from "./ElementAnalyzer";
 import { CLASSNAMES_HELPER_NAME, CONCAT_HELPER_NAME } from "./helpers";
-import { isMustacheStatement } from "./utils";
+import { isConcatStatement, isMustacheStatement, isPathExpression, isSubExpression } from "./utils";
 
 const enum SourceExpression {
   ternary,
@@ -228,7 +228,7 @@ function constructSwitch(builders: Builders, stateExpr: Switch<StringAST> & HasG
   } else {
     expr.push(builders.number(FalsySwitchBehavior.unset));
   }
-  expr.push(moustacheToStringExpression(builders, stateExpr.stringExpression));
+  expr.push(moustacheToStringExpression(builders, stateExpr.stringExpression!));
   for (let value of values) {
     let obj = stateExpr.group[value];
     expr.push(builders.string(value));
@@ -271,11 +271,11 @@ function moustacheToExpression(builders: Builders, expr: AST.MustacheStatement):
   }
 }
 
-function moustacheToStringExpression(builders: Builders, stringExpression: StringAST): AST.Expression {
-  if (stringExpression!.type === "ConcatStatement") {
+function moustacheToStringExpression(builders: Builders, stringExpression: Exclude<StringAST, null>): AST.Expression {
+  if (isConcatStatement(stringExpression)) {
     return builders.sexpr(
       builders.path(CONCAT_HELPER_NAME),
-      (stringExpression as AST.ConcatStatement).parts.reduce(
+      stringExpression.parts.reduce(
         (arr, val) => {
           if (val.type === "TextNode") {
             arr.push(builders.string(val.chars));
@@ -285,8 +285,14 @@ function moustacheToStringExpression(builders: Builders, stringExpression: Strin
           return arr;
         },
         new Array<AST.Expression>()));
+  } else if (isSubExpression(stringExpression)) {
+    return stringExpression;
+  } else if (isPathExpression(stringExpression)) {
+    return builders.sexpr(stringExpression);
+  } else if (isMustacheStatement(stringExpression)) {
+    return moustacheToExpression(builders, stringExpression);
   } else {
-    return moustacheToExpression(builders, stringExpression as AST.MustacheStatement);
+    return assertNever(stringExpression);
   }
 }
 

packages/@css-blocks/glimmer/src/ElementAnalyzer.ts

@@ -9,6 +9,7 @@ import {
 } from "@css-blocks/core";
 import { AST, print } from "@glimmer/syntax";
 import { SourceLocation, SourcePosition } from "@opticss/element-analysis";
+import { assertNever } from "@opticss/util";
 import * as debugGenerator from "debug";
 
 import { GlimmerAnalysis } from "./Analyzer";
@@ -20,15 +21,19 @@ import {
   isConcatStatement,
   isElementNode,
   isMustacheStatement,
+  isNullLiteral,
+  isNumberLiteral,
+  isPathExpression,
   isStringLiteral,
   isSubExpression,
   isTextNode,
+  isUndefinedLiteral,
 } from "./utils";
 
 // Expressions may be null when ElementAnalyzer is used in the second pass analysis
 // to re-acquire analysis data for rewrites without storing AST nodes.
 export type TernaryExpression = AST.Expression | AST.MustacheStatement | null;
-export type StringExpression = AST.MustacheStatement | AST.ConcatStatement | null;
+export type StringExpression = AST.MustacheStatement | AST.ConcatStatement | AST.SubExpression | AST.PathExpression | null;
 export type BooleanExpression = AST.Expression | AST.MustacheStatement;
 export type TemplateElement  = ElementAnalysis<BooleanExpression, StringExpression, TernaryExpression>;
 export type AttrRewriteMap = { [key: string]: TemplateElement };
@@ -41,7 +46,18 @@ const DEFAULT_BLOCK_NS = "block";
 
 const debug = debugGenerator("css-blocks:glimmer:element-analyzer");
 
-type AnalyzableNodes = AST.ElementNode | AST.BlockStatement | AST.MustacheStatement;
+type AnalyzableNode = AST.ElementNode | AST.BlockStatement | AST.MustacheStatement | AST.SubExpression;
+
+export function isStyleOfHelper(node: AnalyzableNode): node is AST.MustacheStatement | AST.SubExpression {
+  if (!isMustacheStatement(node)) return false;
+  let name = node.path.original;
+  return typeof name === "string" && name === "style-of";
+}
+
+export function isAnalyzedHelper(node: AnalyzableNode): node is AST.MustacheStatement | AST.BlockStatement {
+  if (isElementNode(node)) return false;
+  return isEmberBuiltIn(node.path.original) || isStyleOfHelper(node);
+}
 
 export class ElementAnalyzer {
   analysis: GlimmerAnalysis;
@@ -58,15 +74,15 @@ export class ElementAnalyzer {
     this.reservedClassNames = analysis.reservedClassNames();
   }
 
-  analyze(node: AnalyzableNodes, atRootElement: boolean): AttrRewriteMap {
+  analyze(node: AnalyzableNode, atRootElement: boolean): AttrRewriteMap {
     return this._analyze(node, atRootElement, false);
   }
 
-  analyzeForRewrite(node: AnalyzableNodes, atRootElement: boolean): AttrRewriteMap {
+  analyzeForRewrite(node: AnalyzableNode, atRootElement: boolean): AttrRewriteMap {
     return this._analyze(node, atRootElement, true);
   }
 
-  private debugAnalysis(node: AnalyzableNodes, atRootElement: boolean, element: TemplateElement) {
+  private debugAnalysis(node: AnalyzableNode, atRootElement: boolean, element: TemplateElement) {
     if (!debug.enabled) return;
     let startTag = "";
     if (isElementNode(node)) {
@@ -80,15 +96,15 @@ export class ElementAnalyzer {
     debug(`↳ Analyzed as: ${element.forOptimizer(this.cssBlocksOpts)[0].toString()}`);
   }
 
-  private debugTemplateLocation(node: AnalyzableNodes) {
+  private debugTemplateLocation(node: AnalyzableNode) {
     let templatePath = this.cssBlocksOpts.importer.debugIdentifier(this.template.identifier, this.cssBlocksOpts);
     return charInFile(templatePath, node.loc.start);
   }
   private debugBlockPath(block: Block | null = null) {
     return this.cssBlocksOpts.importer.debugIdentifier((block || this.block).identifier, this.cssBlocksOpts);
   }
 
-  private newElement(node: AnalyzableNodes, forRewrite: boolean): TemplateElement {
+  private newElement(node: AnalyzableNode, forRewrite: boolean): TemplateElement {
     let label = isElementNode(node) ? node.tag : node.path.original as string;
     if (forRewrite) {
       return new ElementAnalysis<BooleanExpression, StringExpression, TernaryExpression>(nodeLocation(node), this.reservedClassNames, label);
@@ -117,8 +133,26 @@ export class ElementAnalyzer {
     }
   }
 
+  *eachAnalyzedAttribute(node: AnalyzableNode): Iterable<[string, string, AST.AttrNode | AST.HashPair]> {
+    if (isElementNode(node)) {
+      for (let attribute of node.attributes) {
+        let [namespace, attrName] = this.isAttributeAnalyzed(attribute.name);
+        if (namespace && attrName) {
+          yield [namespace, attrName, attribute];
+        }
+      }
+    } else {
+      for (let pair of node.hash.pairs) {
+        let [namespace, attrName] = this.isAttributeAnalyzed(pair.key);
+        if (namespace && attrName) {
+          yield [namespace, attrName, pair];
+        }
+      }
+    }
+  }
+
   private _analyze(
-    node: AnalyzableNodes,
+    node: AnalyzableNode,
     atRootElement: boolean,
     forRewrite: boolean,
   ): AttrRewriteMap {
@@ -131,53 +165,34 @@ export class ElementAnalyzer {
       element.addStaticClass(this.block.rootClass);
     }
 
-    // Find the class attribute and process.
-    if (isElementNode(node)) {
-      for (let attribute of node.attributes) {
-        let [namespace, attrName] = this.isAttributeAnalyzed(attribute.name);
-        if (namespace && attrName) {
-          if (attrName === "class") {
-            this.processClass(namespace, attribute, element, forRewrite);
-          } else if (attrName === "scope") {
-            this.processScope(namespace, attribute, element, forRewrite);
-          }
-        }
-      }
-    }
-    else {
-      for (let pair of node.hash.pairs) {
-        if (pair.key === "class") {
-          throw cssBlockError(`The class attribute is forbidden. Did you mean block:class?`, node, this.template);
-        }
-        let [namespace, attrName] = this.isAttributeAnalyzed(pair.key);
-        if (namespace && attrName) {
-          if (attrName === "class") {
-            this.processClass(namespace, pair, element, forRewrite);
-          } else if (attrName === "scope") {
-            this.processScope(namespace, pair, element, forRewrite);
-          }
-        }
+    // Find the class or scope attribute and process it
+    for (let [namespace, attrName, attribute] of this.eachAnalyzedAttribute(node)) {
+      if (attrName === "class") {
+        this.processClass(namespace, attribute, element, forRewrite);
+      } else if (attrName === "scope") {
+        this.processScope(namespace, attribute, element, forRewrite);
       }
     }
 
-    // Only ElementNodes may use states right now.
+    // validate that html elements aren't using the class attribute.
     if (isElementNode(node)) {
       for (let attribute of node.attributes) {
         if (attribute.name === "class") {
           throw cssBlockError(`The class attribute is forbidden. Did you mean block:class?`, node, this.template);
         }
-        let [namespace, attrName] = this.isAttributeAnalyzed(attribute.name);
-        if (namespace && attrName) {
-          if (attrName !== "class" && attrName !== "scope") {
-            this.processState(namespace, attrName, attribute, element, forRewrite);
-          }
-        }
+      }
+    }
+
+    for (let [namespace, attrName, attribute] of this.eachAnalyzedAttribute(node)) {
+      if (namespace && attrName) {
+        if (attrName === "class" || attrName === "scope") continue;
+        this.processState(namespace, attrName, attribute, element, forRewrite);
       }
     }
 
     this.finishElement(element, forRewrite);
 
-    // If this is an Ember Build-In...
+    // If this is an Ember Built-In...
     if (!isElementNode(node) && isEmberBuiltIn(node.path.original)) {
       this.debugAnalysis(node, atRootElement, element);
 
@@ -335,7 +350,7 @@ export class ElementAnalyzer {
   private processState(
     blockName: string,
     stateName: string,
-    node: AST.AttrNode,
+    node: AST.AttrNode | AST.HashPair,
     element: TemplateElement,
     forRewrite: boolean,
   ): void {
@@ -345,17 +360,44 @@ export class ElementAnalyzer {
       throw cssBlockError(`No block or class from ${blockName || "the default block"} is assigned to the element so a state from that block cannot be used.`, node, this.template);
     }
     let staticSubStateName: string | undefined = undefined;
-    let dynamicSubState: AST.MustacheStatement | AST.ConcatStatement | undefined = undefined;
-    if (isTextNode(node.value)) {
-      staticSubStateName = node.value.chars;
+    let dynamicSubState: AST.MustacheStatement | AST.ConcatStatement | AST.SubExpression | AST.PathExpression | undefined = undefined;
+    let value = node.value;
+    if (isTextNode(value)) {
+      staticSubStateName = value.chars;
+      if (staticSubStateName === "") {
+        staticSubStateName = undefined;
+      }
+    } else if (isStringLiteral(value)) {
+      staticSubStateName = value.value;
       if (staticSubStateName === "") {
         staticSubStateName = undefined;
       }
+    } else if (isNumberLiteral(value)) {
+      staticSubStateName = value.value.toString();
+      if (staticSubStateName === "") {
+        staticSubStateName = undefined;
+      }
+    } else if (isBooleanLiteral(value)) {
+      if (!value.value) {
+        // Setting the state explicitly to false is the same as not having the state on the element.
+        // So we just skip analysis of it. In the future we might want to partially analyze it to validate
+        // that the state name exists
+        return;
+        // Setting it to true is the simplest way to set the state having no substates on an element when using the style-of helper.
+      }
+    } else if (isMustacheStatement(value) || isConcatStatement(value) || isSubExpression(value) || isPathExpression(value)) {
+      dynamicSubState = value;
+    } else if (isNullLiteral(value) || isUndefinedLiteral(value)) {
+      // Setting the state explicitly to null or undefined is the same as not having the state on the element.
+      // So we just skip analysis of it. In the future we might want to partially analyze it to validate
+      // that the state name exists
+      return;
     } else {
-      dynamicSubState = node.value;
+      assertNever(value);
     }
+
     let found = false;
-    const errors: [string, AST.AttrNode, ResolvedFile][] = [];
+    const errors: [string, AST.AttrNode | AST.HashPair, ResolvedFile][] = [];
     for (let container of containers) {
       let stateGroup = container.resolveAttribute({
         namespace: "state",

packages/@css-blocks/glimmer/src/EmberBuiltins.ts

@@ -1,3 +1,7 @@
+import { AST } from "@glimmer/syntax";
+
+import { isBlockStatement, isMustacheStatement } from "./utils";
+
 /**
  * Ember Built-Ins are components that should be analyzed like regular
  * elements. The Analyzer and Rewriter will process components defined
@@ -21,6 +25,15 @@ const BUILT_INS: IBuiltIns = {
 
 export type BuiltIns = keyof IBuiltIns;
 
+export function isEmberBuiltInNode(node: AST.Node): node is AST.BlockStatement | AST.MustacheStatement {
+  if (isBlockStatement(node) || isMustacheStatement(node)) {
+    let name = node.path.original;
+    if (typeof name === "string" && BUILT_INS[name]) {
+      return true;
+    }
+  }
+  return false;
+}
 export function isEmberBuiltIn(name: unknown): name is keyof IBuiltIns {
   if (typeof name === "string" && BUILT_INS[name]) { return true; }
   return false;