Adds unsafeCss for composing values into css

Fixes #451 and #471. Non-literal values can now be included in styling with `css` by using the `unsafeCss` function. This is named "unsafe" so users know this they must use this carefully to avoid security issues.

Author: Steven Orvell

CHANGELOG.md

@@ -15,6 +15,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 <!-- ### Fixed -->
 ## Unreleased
 
+### Added
+* Adds `unsafeCss` for composing "unsafe" values into `css`. Note, `CSSResult` is no longer constructable. ([#451](https://github.com/Polymer/lit-element/issues/451) and [#471](https://github.com/Polymer/lit-element/issues/471)).
+
 ### Fixed
 * Fixed a bug where we broke compatibility with closure compiler's property renaming optimizations. JSCompiler_renameProperty can't be a module export ([#465](https://github.com/Polymer/lit-element/pull/465)).
 * Fixed an issue with inheriting from `styles` property when extending a superclass that is never instanced. ([#470](https://github.com/Polymer/lit-element/pull/470)).

src/lib/css-tag.ts

@@ -12,13 +12,20 @@ found at http://polymer.github.io/PATENTS.txt
 export const supportsAdoptingStyleSheets =
     ('adoptedStyleSheets' in Document.prototype);
 
+const constructionToken = Symbol();
+
 export class CSSResult {
 
   _styleSheet?: CSSStyleSheet|null;
 
   readonly cssText: string;
 
-  constructor(cssText: string) { this.cssText = cssText; }
+  constructor(cssText: string, safeToken: symbol) {
+    if (safeToken !== constructionToken) {
+      throw new Error('CSSResult is not constructable. Use `unsafeCss` or `css` instead.');
+    }
+    this.cssText = cssText;
+  }
 
   // Note, this is a getter so that it's lazy. In practice, this means
   // stylesheets are not created until the first element instance is made.
@@ -37,6 +44,10 @@ export class CSSResult {
   }
 }
 
+export const unsafeCss = (value: any) => {
+  return new CSSResult(String(value), constructionToken);
+};
+
 const textFromCSSResult = (value: CSSResult) => {
   if (value instanceof CSSResult) {
     return value.cssText;
@@ -48,9 +59,9 @@ const textFromCSSResult = (value: CSSResult) => {
 };
 
 export const css =
-    (strings: TemplateStringsArray, ...values: CSSResult[]): CSSResult => {
+    (strings: TemplateStringsArray, ...values: CSSResult[]) => {
       const cssText = values.reduce(
           (acc, v, idx) => acc + textFromCSSResult(v) + strings[idx + 1],
           strings[0]);
-      return new CSSResult(cssText);
+      return new CSSResult(cssText, constructionToken);
     };

src/test/lit-element_styling_test.ts

@@ -16,6 +16,8 @@ import '@webcomponents/shadycss/apply-shim.min.js';
 
 import {
   css,
+  unsafeCss,
+  CSSResult,
   html as htmlWithStyles,
   LitElement,
 } from '../lit-element.js';
@@ -432,6 +434,33 @@ suite('Static get styles', () => {
     assert.throws(() => { css`div { border: ${`2px solid blue;` as any}}`; });
   });
 
+  test('`CSSResult` cannot be constructed', async () => {
+    // Note, this is done for security, instead use `css` or `unsafeCss`
+    assert.throws(() => { new CSSResult('throw', Symbol()); });
+  });
+
+  test('Any value can be used in `css` when included with `unsafeCss`', async () => {
+    const name = generateElementName();
+    const someVar = `2px solid blue`;
+    customElements.define(name, class extends LitElement {
+      static get styles() {
+        return css`div {
+          border: ${unsafeCss(someVar)};
+        }`;
+      }
+
+      render() {
+        return htmlWithStyles`
+        <div>Testing</div>`;
+      }
+    });
+    const el = document.createElement(name);
+    container.appendChild(el);
+    await (el as LitElement).updateComplete;
+    const div = el.shadowRoot!.querySelector('div');
+    assert.equal(getComputedStyleValue(div!, 'border-top-width').trim(), '2px');
+  });
+
   test('styles in render compose with `static get styles`', async () => {
     const name = generateElementName();
     customElements.define(name, class extends LitElement {