feat: Change '.root' selector to ':scope'.

Author: amiller-gh

packages/css-blocks/README.md

@@ -246,14 +246,14 @@ A state is attached to a single class in the block and describes how that
 class changes when the element is in that state. The names of states are
 scoped to their class and the styles they provide can target only elements
 assigned to that classname. The exception to this is for states that belong
-to the block `.root` class. In general, CSS Blocks restricts the use of
+to the block `:scope` class. In general, CSS Blocks restricts the use of
 combinators in selectors with a preference for unscoped selectors that are
 fast and optimization friendly (See Rules & Constraints below). One of the
 primary exceptions to this is that root states can be used in selectors as a
 scope for classes and other states within the block. So when you find
 yourself thinking that you absolutely need to use a descendant or child
 combinator then you should imagine that use case as a state for a block's
- `.root` class.
+ `:scope` class.
 
 It is important to think of States as part of the public API that describe
 how a block and the classes within it can vary. By keeping all the
@@ -371,10 +371,10 @@ Syntax
 
 ### The root element
 
-Styles can be attached to a block's root element with the class `.root`. The
-`.root` class can be used in selectors in combination with itself as well as
+Styles can be attached to a block's root element with the class `:scope`. The
+`:scope` class can be used in selectors in combination with itself as well as
 in media queries and other @-rules. However, some block-specific syntax may
-only be put into a simple ruleset where the selector is exactly `.root`; it
+only be put into a simple ruleset where the selector is exactly `:scope`; it
 is convention to have only one such ruleset near the top of your block's
 file.
 
@@ -458,7 +458,7 @@ automatically generate a unique name for BEM output mode.
 `shared.block.css`
 
 ```css
-.root {
+:scope {
   block-name: my-block;
   color: blue;
 }
@@ -472,7 +472,7 @@ automatically generate a unique name for BEM output mode.
 ```css
 @block-reference shared from "../shared.block.css";
 
-.root {
+:scope {
   block-name: my-block;
   background-color: blue;
 }
@@ -541,10 +541,10 @@ with a specific selector in the block. In fact, it is an abstraction that can ca
 the CSS blocks compiler to consider many selectors in a block that involve the specific
 block object.
 
-  - `.root` represents the block root for the current block.
+  - `:scope` represents the block root for the current block.
   - `a-block-reference.root` represents the block root for the
     block that has a `@block-reference` as `a-block-reference` from the current
-    block. In many cases, the `.root` can be safely omitted.
+    block. In many cases, the `:scope` can be safely omitted.
   - `[state|foo]` or `[state|foo=bar]` represent the
     root state named `foo` or the state named `foo` with the substate of `bar`.
   - `a-block-reference[state|foo]` or `a-block-reference[state|foo=bar]`
@@ -602,7 +602,7 @@ Rather than having to specify the block root, a block class can declare itself t
 
 ```css
 // tab.block.css
-.root {
+:scope {
   background-color: gray;
   color: black;
   flex: 1 1 content;
@@ -631,7 +631,7 @@ Rather than having to specify the block root, a block class can declare itself t
 
 // tabs.block.css
 @block-reference tab from "tab.block.css";
-.root {
+:scope {
   display: flex;
 }
 
@@ -693,13 +693,13 @@ other block:
 And now that block can be referenced within this file by the name
 `another`.
 
-To inherit, you must set the property `extends` inside the block's `.root`
+To inherit, you must set the property `extends` inside the block's `:scope`
 class to the name of the block you wish to inherit.
 
 ```css
 @block-refererence another from "./another-block.block.css";
 
-.root {
+:scope {
   extends: another;
 }
 ```
@@ -727,7 +727,7 @@ a block `implements` one or more blocks.
 ```css
 @block-reference base from "./base.block.css";
 @block-reference other from "./other.block.css";
-.root { implements: base, other; color: red; }
+:scope { implements: base, other; color: red; }
 ```
 
 Now if there are any states, classes or substates in those other blocks
@@ -1231,7 +1231,7 @@ of the same value in the key selector the following resolution is created:
 
 ```css
 @block-reference base from "./base.block.css";
-.root { extends: base; }
+:scope { extends: base; }
 .foo {
   color: resolve("base.foo");
   color: blue; // conflicts with color value(s) in a selector targeting base.foo
@@ -1340,7 +1340,7 @@ change the source authoring. Here's our form example from above written with Sas
 
 ```scss
 $base-size: 1em;
-.root {
+:scope {
   block-name: my-form;
   margin: 2 * $base-size 0;
   padding: $base-size $base-size / 2;
@@ -1438,7 +1438,7 @@ the current component's styles:
 ```css
 @block-reference icons from "../../shared/styles/icons/dark.block.css";
 
-.root {
+:scope {
   border: 1px solid black;
   overflow: auto;
 }
@@ -1453,7 +1453,7 @@ the current component's styles:
 `my-component/template.hbs`
 
 ```hbs
-<div class="icons.root" state:icons.hoverable state:icons.dark>
+<div class="icons:scope" state:icons.hoverable state:icons.dark>
   <div class="icon icons.new">New File</div>
   <div class="icon icons.save">Save File</div>
   <div class="icon icons.undo">Undo</div>

packages/css-blocks/src/Block/Block.ts

@@ -14,7 +14,7 @@ import {
   isStateNode,
   NodeAndType,
 } from "../BlockParser";
-import { stateName, stateValue } from "../BlockParser/block-intermediates";
+import { isRootNode, stateName, stateValue } from "../BlockParser/block-intermediates";
 import { BlockPath, CLASS_NAME_IDENT, ROOT_CLASS } from "../BlockSyntax";
 import { OptionsReader } from "../OptionsReader";
 import { SourceLocation } from "../SourceLocation";
@@ -301,7 +301,7 @@ export class Block
   }
 
   nodeAsStyle(node: selectorParser.Node): [Styles, number] | null {
-    if (node.type === selectorParser.CLASS && node.value === ROOT_CLASS) {
+    if (isRootNode(node)) {
       return [this.rootClass, 0];
     } else if (node.type === selectorParser.TAG) {
       let otherBlock = this.getReferencedBlock(node.value);
@@ -412,7 +412,7 @@ export class Block
     let sourceNames = new Set<string>(this.all().map(s => s.asSource()));
     let sortedNames = [...sourceNames].sort();
     for (let n of sortedNames) {
-      if (n !== `.${ROOT_CLASS}`) {
+      if (n !== ROOT_CLASS) {
         let o = this.find(n) as Styles;
         result.push(o.asDebug(opts));
       }

packages/css-blocks/src/Block/BlockClass.ts

@@ -1,6 +1,6 @@
 import { Attribute, AttributeValue, attrValues } from "@opticss/element-analysis";
 
-import { UNIVERSAL_STATE } from "../BlockSyntax";
+import { ROOT_CLASS, UNIVERSAL_STATE } from "../BlockSyntax";
 import { OptionsReader } from "../OptionsReader";
 import { OutputMode } from "../OutputMode";
 
@@ -33,7 +33,7 @@ export class BlockClass extends Style<BlockClass, Block, Block, StateGroup> {
 
   protected newChild(name: string): StateGroup { return new StateGroup(name, this); }
 
-  get isRoot(): boolean { return this.name === "root"; }
+  get isRoot(): boolean { return this.name === ROOT_CLASS; }
 
   public getGroups(): StateGroup[] { return this.children(); }
   public getGroup(name: string): StateGroup | null { return this.getChild(name); }
@@ -48,7 +48,7 @@ export class BlockClass extends Style<BlockClass, Block, Block, StateGroup> {
    * Ensure that a `StateGroup` with the given name exists. If the `StateGroup`
    * does not exist, it is created.
    * @param name The State group to ensure exists.
-   * @param vallue The State's value to ensure exists.
+   * @param value The State's value to ensure exists.
    * @returns The State object.
    */
   public ensureGroup(name: string): StateGroup { return this.ensureChild(name); }
@@ -108,7 +108,7 @@ export class BlockClass extends Style<BlockClass, Block, Block, StateGroup> {
    * Export as original class name.
    * @returns String representing original class.
    */
-  public asSource(): string { return `.${this.name}`; }
+  public asSource(): string { return this.isRoot ? ROOT_CLASS : `.${this.name}`; }
 
   /**
    * Emit analysis attributes for the class value this

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

@@ -1,6 +1,7 @@
 import * as postcss from "postcss";
 
 import { Block } from "../Block";
+import { ROOT_CLASS } from "../BlockSyntax";
 import { OptionsReader } from "../OptionsReader";
 import { StyleAnalysis } from "../TemplateAnalysis/StyleAnalysis";
 import { PluginOptions } from "../options";
@@ -33,7 +34,7 @@ export class BlockCompiler {
       root.walkAtRules("block-reference", (atRule) => {
         atRule.remove();
       });
-      root.walkRules(/\.root/, (rule) => {
+      root.walkRules(ROOT_CLASS, (rule) => {
         rule.walkDecls(/^(extends|implements|block-name)$/, (decl) => {
           decl.remove();
         });

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

@@ -2,6 +2,8 @@ import { assertNever, firstOfType } from "@opticss/util";
 import { CompoundSelector } from "opticss";
 import selectorParser = require("postcss-selector-parser");
 
+import { ROOT_CLASS } from "../BlockSyntax";
+
 export enum BlockType {
   root = 1,
   state,
@@ -14,7 +16,7 @@ export type NodeAndType = {
   node: selectorParser.Attribute;
 } | {
   blockType: BlockType.root | BlockType.class;
-  node: selectorParser.ClassName;
+  node: selectorParser.ClassName | selectorParser.Pseudo;
 };
 
 export type BlockNodeAndType = NodeAndType & {
@@ -73,8 +75,8 @@ export function isClassLevelObject(object: NodeAndType): boolean {
 /**
  * Check if given selector node is targeting the root block node
  */
-export function isRootNode(node: selectorParser.Node): node is selectorParser.ClassName {
-  return node.type === selectorParser.CLASS && node.value === "root";
+export function isRootNode(node: selectorParser.Node): node is selectorParser.Pseudo {
+  return node.type === selectorParser.PSEUDO && node.value === ROOT_CLASS;
 }
 
 /**

packages/css-blocks/src/BlockParser/features/discover-name.ts

@@ -7,7 +7,7 @@ import * as errors from "../../errors";
 export async function discoverName(root: postcss.Root, defaultName: string, file: string): Promise<string> {
 
   // Eagerly fetch custom `block-name` from the root block rule.
-  root.walkRules(".root", (rule) => {
+  root.walkRules(":scope", (rule) => {
     rule.walkDecls(BLOCK_NAME, (decl) => {
       if (!CLASS_NAME_IDENT.test(decl.value)) {
         throw new errors.InvalidBlockSyntax(

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

@@ -89,7 +89,7 @@ export class BlockParser {
     await constructBlock(root, block, debugIdent);
     // Verify that external blocks referenced have been imported, have defined the state being selected, and have marked it as a global state.
     await assertForeignGlobalState(root, block, debugIdent);
-    // Construct block extentions and validate.
+    // Construct block extensions and validate.
     await extendBlock(root, block, debugIdent);
     // Validate that all required Styles are implemented.
     await implementBlock(root, block, debugIdent);

packages/css-blocks/src/BlockSyntax/BlockPath.ts

@@ -1,6 +1,9 @@
 import { BlockPathError, ErrorLocation } from "../errors";
 
-import { CLASS_NAME_IDENT as CSS_IDENT } from "./BlockSyntax";
+import {
+  CLASS_NAME_IDENT as CSS_IDENT,
+  ROOT_CLASS,
+} from "./BlockSyntax";
 
 interface BlockToken {
   type: "block";
@@ -42,8 +45,9 @@ const NAMESPACE_END = "|";
 const VALUE_START = "=";
 const SINGLE_QUOTE = `'`;
 const DOUBLE_QUOTE = `"`;
+const PSEUDO_BEGIN = ":";
 const WHITESPACE_REGEXP = /\s/g;
-const SEPARATORS = new Set([CLASS_BEGIN, STATE_BEGIN]);
+const SEPARATORS = new Set([CLASS_BEGIN, STATE_BEGIN, PSEUDO_BEGIN]);
 
 export const ERRORS = {
   whitespace: "Whitespace is only allowed in quoted state values",
@@ -62,7 +66,7 @@ function stringify(tokens: Token[]): string {
   let out = "";
   for (let token of tokens) {
          if (isBlock(token)) { out += token.name; }
-    else if (isClass(token)) { out += `.${token.name}`; }
+    else if (isClass(token)) { out += token.name === ROOT_CLASS ? token.name : `.${token.name}`; }
     else if (isState(token)) { out += `[${token.namespace}|${token.name}${token.value ? `="${token.value}"` : ""}]`; }
   }
   return out;
@@ -115,6 +119,8 @@ export class BlockPath {
   private _tokens: Token[] = [];
   private parts: Token[] = [];
 
+  public readonly original: string;
+
   /**
    * Throw a new BlockPathError with the given message.
    * @param msg The error message.
@@ -152,7 +158,7 @@ export class BlockPath {
     if (isState(token)) {
       this._state = this._state ? this.throw(ERRORS.multipleOfType(token.type)) : token;
       // If no class has been added yet, automatically inject the root class.
-      if (!this._class) { this.addToken({ type: "class", name: "root" }, false); }
+      if (!this._class) { this.addToken({ type: "class", name: ROOT_CLASS }, false); }
     }
 
     // Add the token.
@@ -175,6 +181,20 @@ export class BlockPath {
 
       switch (true) {
 
+        case char === PSEUDO_BEGIN:
+          if (!isBlock(token)) { return this.throw(ERRORS.invalidIdent(PSEUDO_BEGIN), working.length); }
+          token.name = working;
+          this.addToken(token, true);
+          working = `${PSEUDO_BEGIN}${walker.consume(SEPARATORS)}`;
+          if (working === ROOT_CLASS) {
+            this.addToken({ type: "class", name: ROOT_CLASS }, true);
+            working = "";
+            break;
+          }
+          else {
+            return this.throw(ERRORS.invalidIdent(working), working.length);
+          }
+
         // If a period, we've finished the previous token and are now building a class name.
         case char === CLASS_BEGIN:
           if (isState(token)) { this.throw(ERRORS.illegalCharInState(char)); }
@@ -265,7 +285,7 @@ export class BlockPath {
       token.name = working;
       this.addToken(token, true);
     }
-    if (!this._class) { this.addToken({ type: "class", name: "root" }, false); }
+    if (!this._class) { this.addToken({ type: "class", name: ROOT_CLASS }, false); }
   }
 
   /**
@@ -275,6 +295,7 @@ export class BlockPath {
    */
   constructor(path: string | BlockPath, location?: ErrorLocation) {
     this._location = location;
+    this.original = path.toString();
     if (path instanceof BlockPath) {
       this.parts = path.parts;
     }
@@ -308,7 +329,7 @@ export class BlockPath {
    * Get the parsed class name of this Block Path
    */
   get class(): string {
-    return this._class && this._class.name || "root";
+    return this._class && this._class.name || ROOT_CLASS;
   }
 
   /**

packages/css-blocks/src/BlockSyntax/BlockSyntax.ts

@@ -53,4 +53,4 @@ export const UNIVERSAL_STATE = "::universal";
 
 // Internally use the invented `root` class represents the root element styling for a block. By interpreting the
 // root selector as just another class we no longer have to store styling information it on the `Block` object..
-export const ROOT_CLASS = "root";
+export const ROOT_CLASS = ":scope";

packages/css-blocks/test/Block/lookup-test.ts

@@ -7,7 +7,7 @@ import { Block } from "../../src/Block";
 export class LookupTests {
   @test "finds the block"() {
     let block = new Block("test", "test.block.css");
-    let found = block.lookup(".root");
+    let found = block.lookup(":scope");
     assert.deepEqual(block.rootClass, found);
   }
   @test "finds a state"() {
@@ -48,7 +48,7 @@ export class LookupTests {
     block.addBlockReference("asdf", otherBlock);
     let found = block.lookup("asdf");
     assert.deepEqual(otherBlock.rootClass, found);
-    found = block.lookup("asdf.root");
+    found = block.lookup("asdf:scope");
     assert.deepEqual(otherBlock.rootClass, found);
   }
   @test "finds referenced block class"() {