add CSS partial tagged template literal (#4711)

* add CSS partial tagged template literal to better leverage partial CSS fragments w/ CSS Directives

* Update packages/web-components/fast-element/docs/guide/leveraging-css.md

Co-authored-by: Rob Eisenberg <[email protected]>

* refactor to use style collection logic from css and to support all return types of CSSDirective

* open API to ComposableStyles

* add test for ElementStyles interpolation

* Change files

* update docs to reflect opening API

* update api-report

* Update packages/web-components/fast-element/docs/guide/leveraging-css.md

Co-authored-by: Jane Chu <[email protected]>

Co-authored-by: nicholasrice <[email protected]>
Co-authored-by: Rob Eisenberg <[email protected]>
Co-authored-by: Jane Chu <[email protected]>

Author: 3 people

change/@microsoft-fast-element-f844ce52-e9f5-49f8-ac42-482efaa64573.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Add cssPartial template function to facilitate partial CSS abstractions.",
+  "packageName": "@microsoft/fast-element",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/web-components/fast-element/docs/api-report.md

@@ -193,6 +193,9 @@ export class CSSDirective {
     createCSS(): ComposableStyles;
 }
 
+// @public
+export function cssPartial(strings: TemplateStringsArray, ...values: (ComposableStyles | CSSDirective)[]): CSSDirective;
+
 // @public
 export function customElement(nameOrDef: string | PartialFASTElementDefinition): (type: Function) => void;
 

packages/web-components/fast-element/docs/guide/leveraging-css.md

@@ -128,6 +128,71 @@ Rather than simply concatenating CSS strings, the `css` helper understands that
 You can also pass a CSS `string` or a [CSSStyleSheet](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet) instance directly to the element definition, or even a mixed array of `string`, `CSSStyleSheet`, or `ElementStyles`.
 :::
 
+### Partial CSS
+There are times when you may want to create reusable blocks of *partial* CSS, where the abstraction is not valid CSS in and of itself, such as groups of CSS properties or a complex value. To do that, you can use the `cssPartial` tagged template literal: 
+
+```ts
+import { css, cssPartial } from "@microsoft/fast-element";
+
+const partial = cssPartial`color: red;`;
+const styles = css`:host{ ${partial} }`;
+```
+
+`cssPartial` can also compose all structures that `css` can compose, providing even greater flexibility.
+
+## CSSDirective
+The `CSSDirective` allows binding behavior to an element via `ElementStyles`. To create a `CSSDirective`, import and extend `CSSDirective` from `@microsoft/fast-element`:
+
+```ts
+import { CSSDirective }  from "@microsoft/fast-element"
+
+class RandomWidth extends CSSDirective {}
+```
+
+A CSS directive has two key methods that you can leverage to add dynamic behavior via CSS:
+
+### createCSS
+`CSSDirective` has a `createCSS()` method that returns a string to be interpolated into an `ElementStyles`:
+
+```ts
+class RandomWidth extends CSSDirective {
+  createCSS() {
+    return "width: var(--random-width);"
+  }
+}
+```
+
+### createBehavior
+The `createBehavior()` method can be used to create a `Behavior` that is bound to the element using the `CSSDirective`:
+
+
+```ts
+class RandomWidth extends CSSDirective {
+  private property = "--random-width";
+  createCSS() {
+    return `width: var(${this.property});`
+  }
+
+  createBehavior() {
+    return {
+      bind(el) {
+        el.style.setProperty(this.property, Math.random() * 100)
+      }
+      unbind(el) {
+        el.style.removeProperty(this.property);
+      }
+    }
+  }
+}
+```
+
+### Usage in ElementStyles
+The `CSSDirective` can then be used in an `ElementStyles`, where the CSS string from `createCSS()` will be interpolated into the stylesheet, and the behavior returned from `createBehavior()` will get bound to the element using the stylesheet:
+
+```ts
+const styles = css`:host {${new RandomWidth()}}`;
+```
+
 ## Shadow DOM styling
 
 You may have noticed the `:host` selector we used in our `name-tag` styles. This selector allows us to apply styles directly to our custom element. Here are a few things to consider always configuring for your host element:

packages/web-components/fast-element/src/index.ts

@@ -15,7 +15,7 @@ export {
     ComposableStyles,
     StyleTarget,
 } from "./styles/element-styles";
-export { css } from "./styles/css";
+export { css, cssPartial } from "./styles/css";
 export { CSSDirective } from "./styles/css-directive";
 export * from "./templating/view";
 export * from "./observation/observable";

packages/web-components/fast-element/src/styles/css.ts

@@ -1,19 +1,12 @@
+import type { FASTElement } from "../components/fast-element";
 import type { Behavior } from "../observation/behavior";
 import { CSSDirective } from "./css-directive";
 import { ComposableStyles, ElementStyles } from "./element-styles";
 
-/**
- * Transforms a template literal string into styles.
- * @param strings - The string fragments that are interpolated with the values.
- * @param values - The values that are interpolated with the string fragments.
- * @remarks
- * The css helper supports interpolation of strings and ElementStyle instances.
- * @public
- */
-export function css(
+function collectStyles(
     strings: TemplateStringsArray,
-    ...values: (ComposableStyles | CSSDirective)[]
-): ElementStyles {
+    values: (ComposableStyles | CSSDirective)[]
+): { styles: ComposableStyles[]; behaviors: Behavior[] } {
     const styles: ComposableStyles[] = [];
     let cssString = "";
     const behaviors: Behavior[] = [];
@@ -49,6 +42,26 @@ export function css(
         styles.push(cssString);
     }
 
+    return {
+        styles,
+        behaviors,
+    };
+}
+
+/**
+ * Transforms a template literal string into styles.
+ * @param strings - The string fragments that are interpolated with the values.
+ * @param values - The values that are interpolated with the string fragments.
+ * @remarks
+ * The css helper supports interpolation of strings and ElementStyle instances.
+ * @public
+ */
+export function css(
+    strings: TemplateStringsArray,
+    ...values: (ComposableStyles | CSSDirective)[]
+): ElementStyles {
+    const { styles, behaviors } = collectStyles(strings, values);
+
     const elementStyles = ElementStyles.create(styles);
 
     if (behaviors.length) {
@@ -57,3 +70,76 @@ export function css(
 
     return elementStyles;
 }
+
+class CSSPartial extends CSSDirective implements Behavior {
+    private css: string = "";
+    private styles?: ElementStyles;
+    constructor(styles: ComposableStyles[], private behaviors: Behavior[]) {
+        super();
+
+        const stylesheets: ReadonlyArray<Exclude<
+            ComposableStyles,
+            string
+        >> = styles.reduce(
+            (
+                accumulated: Exclude<ComposableStyles, string>[],
+                current: ComposableStyles
+            ) => {
+                if (typeof current === "string") {
+                    this.css += current;
+                } else {
+                    accumulated.push(current);
+                }
+                return accumulated;
+            },
+            []
+        );
+
+        if (stylesheets.length) {
+            this.styles = ElementStyles.create(stylesheets);
+        }
+    }
+
+    createBehavior(): Behavior {
+        return this;
+    }
+
+    createCSS(): string {
+        return this.css;
+    }
+
+    bind(el: FASTElement): void {
+        if (this.styles) {
+            el.$fastController.addStyles(this.styles);
+        }
+
+        if (this.behaviors.length) {
+            el.$fastController.addBehaviors(this.behaviors);
+        }
+    }
+
+    unbind(el: FASTElement): void {
+        if (this.styles) {
+            el.$fastController.removeStyles(this.styles);
+        }
+
+        if (this.behaviors.length) {
+            el.$fastController.removeBehaviors(this.behaviors);
+        }
+    }
+}
+
+/**
+ * Transforms a template literal string into partial CSS.
+ * @param strings - The string fragments that are interpolated with the values.
+ * @param values - The values that are interpolated with the string fragments.
+ * @public
+ */
+export function cssPartial(
+    strings: TemplateStringsArray,
+    ...values: (ComposableStyles | CSSDirective)[]
+): CSSDirective {
+    const { styles, behaviors } = collectStyles(strings, values);
+
+    return new CSSPartial(styles, behaviors);
+}

packages/web-components/fast-element/src/styles/styles.spec.ts

@@ -7,7 +7,9 @@ import {
 } from "./element-styles";
 import { DOM } from "../dom";
 import { CSSDirective } from "./css-directive";
-import { css } from "./css";
+import { css, cssPartial } from "./css";
+import type { Behavior } from "../observation/behavior";
+import { defaultExecutionContext } from "../observation/observable";
 
 if (DOM.supportsAdoptedStyleSheets) {
     describe("AdoptedStyleSheetsStyles", () => {
@@ -244,4 +246,64 @@ describe("css", () => {
             expect(styles.behaviors?.includes(behavior)).to.equal(true)
         });
     })
+});
+
+describe("cssPartial", () => {
+    it("should have a createCSS method that is the CSS string interpolated with the createCSS product of any CSSDirectives", () => {
+        class myDirective extends CSSDirective {
+            createCSS() { return "red" };
+            createBehavior() { return undefined; }
+        }
+        
+        const partial = cssPartial`color: ${new myDirective}`;
+        expect (partial.createCSS()).to.equal("color: red");
+    });
+
+    it("Should add behaviors from interpolated CSS directives when bound to an element", () => {
+        const behavior = {
+            bind() {},
+            unbind() {},
+        }
+
+        const behavior2 = {...behavior};
+
+        class directive extends CSSDirective {
+            createCSS() { return "" };
+            createBehavior() { return behavior; }
+        }
+        class directive2 extends CSSDirective {
+            createCSS() { return "" };
+            createBehavior() { return behavior2; }
+        }
+
+        const partial = cssPartial`${new directive}${new directive2}`;
+        const el = {
+            $fastController: {
+                addBehaviors(behaviors: Behavior[]) {
+                    expect(behaviors[0]).to.equal(behavior);
+                    expect(behaviors[1]).to.equal(behavior2);
+                }
+            }
+        }
+
+        partial.createBehavior()?.bind(el, defaultExecutionContext)
+    });
+
+    it("should add any ElementStyles interpolated into the template function when bound to an element", () => {
+        const styles = css`:host {color: blue; }`;
+        const partial = cssPartial`${styles}`;
+        let called = false;
+        const el = {
+            $fastController: {
+                addStyles(style: ElementStyles) {
+                    expect(style.styles.includes(styles)).to.be.true;
+                    called = true;
+                }
+            }
+        }
+
+        partial.createBehavior()?.bind(el, defaultExecutionContext)
+
+        expect(called).to.be.true;
+    })
 })