CSS Blocks Integration for Glimmer Applications

The css-blocks Rewriter and Analyzer for Glimmer templates.

Installation

yarn add @css-blocks/glimmer

or

npm install --save-dev @css-blocks/glimmer

Usage

This integration for css-blocks with Glimmer creates a convention where every component has an associated css-block. The classes and states of that block are exposed by default to the template. Other blocks are exposed to the template using the @block at-rule from within the stylesheet.

Template Syntax

Given the following CSS Block definition:

@block grid from "./grid.block.css";
:scope {
  block-name: my-component;
  /* ... */
}
:scope[loading] { /* ... */ }
.sidebar { /* ... */ }
.sidebar[collapsed] { /* ... */ }
.main { /* ... */ }
.recommended { /* ... */ }

.one-fifth { /* ... */ }
.one-fifth[gutter-right] { /* ... */ }
.four-fifths { /* ... */ }

We can style a glimmer template like so:

<div block:scope block:loading={{isLoading}}>
  <aside block:class="sidebar" grid:class="one-fifth" block:collapsed grid:gutter="right">
  </aside>
  <article class="{{style-if isRecommended 'recommended' 'main'}}" grid:class="four-fifths">
  </article>
</div>

Of note here:

• Templates with a corresponding Block file must have a root single DOM node as the base of its template.
• The styles for the :scope class are automatically applied to the root element of the component (in this case: div).
• Classes and states from referenced blocks are prefixed with the name of the block (in this case: grid)
• The only expressions allowed in class attributes are the CSS Blocks specific {{style-if}} and {{style-unless}} helpers. Otherwise, a build time error is thrown.

Creating an Analyzer

The default Analyzer performs a transitive analysis by traversing the component hierarchy as well as the block's dependencies on other blocks. This analysis can be provided to the css-blocks compiler and optimizer to remove dead css and enable powerful optimizations.

import * as path from "path";
import {
  Project,
  Rewriter,
  HandlebarsTransitiveStyleAnalyzer as Analyzer
} from "@css-blocks/glimmer";
import projectConfig from "./projectConfig";
let projectDir = path.resolve(__dirname, "..");
let project = new Project(projectDir, projectConfig);
let analyzer = new Analyzer(project, "my-app-component");
analyzer.analyze().then((analysis) => {
  console.log(analysis.serialize(projectDir));
});

Glimmer Project Layout for CSS Blocks

You must add a new stylesheet type to your project so that every component has an associated CSS block. This means you must declare a new type in the types section and add "stylesheet" to the component types.

Example:

const glimmerProjectConfiguration = {
  types: {
    application: { definitiveCollection: 'main' },
    component: { definitiveCollection: 'components' },
    helper: { definitiveCollection: 'components' },
    renderer: { definitiveCollection: 'main' },
    template: { definitiveCollection: 'components' },
    stylesheet: { definitiveCollection: 'components' }
  },
  collections: {
    main: {
      types: ['application', 'renderer']
    },
    components: {
      group: 'ui',
      types: ['component', 'template', 'helper', 'stylesheet'],
      defaultType: 'component',
      privateCollections: ['utils']
    }
  }
}

Note: at this time the default block file for a component must be named stylesheet.css -- the standard naming convention of *.block.css does not work.

Rewriting Templates

After analyzing templates and compiling & optimizing the CSS blocks that are used, the glimmer template must be rewritten to use the right classnames. Glimmer accepts AST plugins during the precompilation step.

Here's an example script for how to analyze and rewrite a single template. Integration with your specific build system will be required.

import * as path from "path";
import {
  StyleMapping
} from "@css-blocks/core";
import {
  Project,
  Rewriter,
  RewriterOptions,
  HandlebarsStyleAnalyzer as Analyzer,
} from "@css-blocks/glimmer";
import {
  precompile
} from "@glimmer/compiler";
import projectConfig from "./projectConfig";
let projectDir = path.resolve(__dirname, "..");
let project = new Project(projectDir, projectConfig);
let analyzer = new Analyzer(project, "my-app-component");
analyzer.analyze().then((analysis) => {
  let template = project.templateFor("my-app-component");
  let options = {
    meta: {},
    plugins: {
      ast: [Rewriter]
    },
    cssBlocks: {
      styleMapping: StyleMapping.fromAnalysis(analysis)
    }
  };
  let compiledFile = precompile(template.string, options);
});

To Do

• Default the name for a component's main block stylesheet to the name of the component so that :scope { block-name: name-of-component; } is not required.