[lit-html] Add dev mode warning when static values are detected in no…

…n static templates (#4345)

Co-authored-by: Augustine Kim <augustinekim@google.com>

.changeset/six-planets-notice.md

@@ -0,0 +1,6 @@
+---
+'lit': patch
+'lit-html': patch
+---
+
+Add a dev mode warning if a static value such as `literal` or `unsafeStatic` is detected within the non-static `html` tag function. These should only be used with the static `html` tag function imported from `lit-html/static.js` or `lit/static-html.js`.

packages/lit-html/src/lit-html.ts

@@ -511,6 +511,20 @@ const tag =
           'This is probably caused by illegal octal escape sequences.'
       );
     }
+    if (DEV_MODE) {
+      // Import static-html.js results in a circular dependency which g3 doesn't
+      // handle. Instead we know that static values must have the field
+      // `_$litStatic$`.
+      if (
+        values.some((val) => (val as {_$litStatic$: unknown})?.['_$litStatic$'])
+      ) {
+        issueWarning(
+          '',
+          `Static values 'literal' or 'unsafeStatic' cannot be used as values to non-static templates.\n` +
+            `Please use the static 'html' tag function. See https://lit.dev/docs/templates/expressions/#static-expressions`
+        );
+      }
+    }
     return {
       // This property needs to remain unminified.
       ['_$litType$']: type,

packages/lit-html/src/test/lit-html_test.ts

@@ -26,6 +26,7 @@ import {
   PartInfo,
   DirectiveParameters,
 } from 'lit-html/directive.js';
+import {isCompiledTemplateResult} from 'lit-html/directive-helpers.js';
 import {assert} from '@esm-bundle/chai';
 import {
   stripExpressionComments,
@@ -35,6 +36,7 @@ import {repeat} from 'lit-html/directives/repeat.js';
 import {AsyncDirective} from 'lit-html/async-directive.js';
 
 import {createRef, ref} from 'lit-html/directives/ref.js';
+import {literal, unsafeStatic} from 'lit-html/static.js';
 
 // For compiled template tests
 import {_$LH} from 'lit-html/private-ssr-support.js';
@@ -48,6 +50,10 @@ const isIe = ua.indexOf('Trident/') > 0;
 // We don't have direct access to DEV_MODE, but this is a good enough
 // proxy.
 const DEV_MODE = render.setSanitizer != null;
+// Tests are compiled if the passed in runtime template has been
+// compiled.
+const testAreCompiled = isCompiledTemplateResult(html``);
+const skipTestIfCompiled = testAreCompiled ? test.skip : test;
 
 class FireEventDirective extends Directive {
   render() {
@@ -3246,5 +3252,19 @@ suite('lit-html', () => {
       );
       assertNoWarning();
     });
+
+    skipTestIfCompiled(
+      'Static values warn if detected without static html tag',
+      () => {
+        html`${literal`<p>Hello</p>`}`;
+        assertWarning('static');
+
+        html`<div>${unsafeStatic('<p>Hello</p>')}</div>`;
+        assertWarning('static');
+
+        html`<h1 attribute="${unsafeStatic('test')}"></h1>`;
+        assertWarning('static');
+      }
+    );
   });
 });