Add Localize mixin for LitElement

Author: aomarks

README.md

@@ -110,3 +110,49 @@ template for each emitted locale. For example:
 ```typescript
 html`Hola <b>${getUsername()}!</b>`;
 ```
+
+### `addLocaleChangeCallback(callback: () => void)`
+
+Add the given function to the set of callbacks that will be invoked whenever the
+locale changes and its localized messages are ready.
+
+Use this function to re-render your application whenever the locale is changed.
+
+If you are using `LitElement`, consider using
+[`LocalizedLitElement`](#localizedlitelement), which performs this re-rendering
+automatically.
+
+In transform mode, calls to this function are replaced with `undefined`.
+
+### `removeLocaleChangeCallback(callback: () => void)`
+
+Remove the given function from the set of callbacks that will be invoked
+whenever the locale changes and its localized messages are ready.
+
+In transform mode, calls to this function are replaced with `undefined`.
+
+## `LocalizedLitElement`
+
+If you are using [LitElement](https://lit-element.polymer-project.org/), then
+you can use the `Localized`
+[mixin](https://justinfagnani.com/2015/12/21/real-mixins-with-javascript-classes/)
+from `lit-localize/localized-element.js` to ensure that your elements
+automatically re-render whenever the locale changes.
+
+```typescript
+import {Localized} from 'lit-localize/localized-element.js';
+import {msg} from 'lit-localize';
+import {LitElement, html} from 'lit-element';
+
+class MyElement extends Localized(LitElement) {
+  render() {
+    // Whenever setLocale() is called, and templates for that locale have
+    // finished loading, this render() function will be re-invoked.
+    return html`<p>
+      ${msg('greeting', html`Hello <b>World!</b>`)}
+    </p>`;
+  }
+}
+```
+
+In transform mode, applications of the `Localized` mixin are removed.

package-lock.json

@@ -32,6 +32,7 @@
     "fs-extra": "^9.0.0",
     "glob": "^7.1.6",
     "jsonschema": "^1.2.6",
+    "lit-element": "^2.3.1",
     "lit-html": "^1.2.1",
     "minimist": "^1.2.5",
     "parse5": "^6.0.0",

package.json

@@ -144,6 +144,38 @@ class Transformer {
       );
     }
 
+    // addLocaleChangeCallback(...) -> undefined
+    if (
+      this.isCallToTaggedFunction(
+        node,
+        '_LIT_LOCALIZE_ADD_LOCALE_CHANGE_CALLBACK_'
+      )
+    ) {
+      return ts.createIdentifier('undefined');
+    }
+
+    // removeLocaleChangeCallback(...) -> undefined
+    if (
+      this.isCallToTaggedFunction(
+        node,
+        '_LIT_LOCALIZE_REMOVE_LOCALE_CHANGE_CALLBACK_'
+      )
+    ) {
+      return ts.createIdentifier('undefined');
+    }
+
+    // Localized(LitElement) -> LitElement
+    if (this.isCallToTaggedFunction(node, '_LIT_LOCALIZE_LOCALIZED_')) {
+      if (node.arguments.length !== 1) {
+        // TODO(aomarks) Surface as diagnostic instead.
+        throw new KnownError(
+          `Expected Localized mixin call to have one argument, ` +
+            `got ${node.arguments.length}`
+        );
+      }
+      return node.arguments[0];
+    }
+
     return ts.visitEachChild(node, this.boundVisitNode, this.context);
   }
 
@@ -368,7 +400,8 @@ class Transformer {
   }
 
   /**
-   * Return whether the given node is an import for the lit-localize module.
+   * Return whether the given node is an import for the lit-localize main
+   * module, or the localized-element module.
    */
   isLitLocalizeImport(node: ts.Node): node is ts.ImportDeclaration {
     if (!ts.isImportDeclaration(node)) {
@@ -381,14 +414,14 @@ class Transformer {
       return false;
     }
     // TODO(aomarks) Is there a better way to reliably identify the lit-localize
-    // module that doesn't require this cast? We could export a const with a
+    // modules that don't require this cast? We could export a const with a
     // known name and then look through `exports`, but it doesn't seem good to
-    // polute the module like that.
+    // polute the modules like that.
     const file = (moduleSymbol.valueDeclaration as unknown) as {
       identifiers: Map<string, unknown>;
     };
     for (const id of file.identifiers.keys()) {
-      if (id === '_LIT_LOCALIZE_MSG_') {
+      if (id === '_LIT_LOCALIZE_MSG_' || id === '_LIT_LOCALIZE_LOCALIZED_') {
         return true;
       }
     }

src/outputters/transform.ts

@@ -334,7 +334,7 @@ test('configureLocalization() -> undefined', (t) => {
      });`,
     `undefined;`,
     [],
-    true
+    false
   );
 });
 
@@ -345,7 +345,7 @@ test('getLocale() -> "es-419"', (t) => {
      getLocale();`,
     `"en";`,
     [],
-    true,
+    false,
     'en'
   );
 
@@ -355,7 +355,7 @@ test('getLocale() -> "es-419"', (t) => {
      getLocale();`,
     `"es-419";`,
     [],
-    true,
+    false,
     'es-419'
   );
 });
@@ -367,17 +367,61 @@ test('setLocale() -> undefined', (t) => {
      setLocale("es-419");`,
     `undefined;`,
     [],
-    true
+    false
   );
 });
 
 test('localeReady() -> Promise.resolve(undefined)', (t) => {
   checkTransform(
     t,
     `import {localeReady} from './lib_client/index.js';
-     localeReady().then(() => console.log('ok'))`,
-    `Promise.resolve(undefined).then(() => console.log('ok'))`,
+     localeReady().then(() => console.log('ok'));`,
+    `Promise.resolve(undefined).then(() => console.log('ok'));`,
+    [],
+    false
+  );
+});
+
+test('addLocaleChangeCallback -> undefined', (t) => {
+  checkTransform(
+    t,
+    `import {addLocaleChangeCallback} from './lib_client/index.js';
+     addLocaleChangeCallback(() => console.log('ok'));`,
+    `undefined`,
+    [],
+    false
+  );
+});
+
+test('removeLocaleChangeCallback -> undefined', (t) => {
+  checkTransform(
+    t,
+    `import {removeLocaleChangeCallback} from './lib_client/index.js';
+     removeLocaleChangeCallback(() => console.log('ok'));`,
+    `undefined`,
+    [],
+    false
+  );
+});
+
+test('Localized(LitElement) -> LitElement', (t) => {
+  checkTransform(
+    t,
+    `import {LitElement, html} from 'lit-element';
+     import {msg} from './lib_client/index.js';
+     import {Localized} from './lib_client/localized-element.js';
+     class MyElement extends Localized(LitElement) {
+       render() {
+         return html\`<b>\${msg('greeting', 'Hello World!')}</b>\`;
+       }
+     }`,
+    `import {LitElement, html} from 'lit-element';
+     class MyElement extends LitElement {
+       render() {
+         return html\`<b>Hello World!</b>\`;
+       }
+     }`,
     [],
-    true
+    false
   );
 });

src/tests/transform.unit.test.ts

@@ -88,6 +88,7 @@ let validLocales: Set<string> | undefined;
 let loadLocale: ((locale: string) => Promise<LocaleModule>) | undefined;
 let templates: TemplateMap | undefined;
 let loading = new Deferred<void>();
+const changeLocaleCallbacks = new Set<() => void>();
 
 /**
  * Set runtime configuration parameters for lit-localize. This function must be
@@ -134,12 +135,14 @@ export const setLocale: ((newLocale: string) => void) & {
   }
   if (newLocale === sourceLocale) {
     loading.resolve();
+    fireChangeLocaleCallbacks();
   } else {
     loadLocale(newLocale).then(
       (mod) => {
         if (newLocale === activeLocale) {
           templates = mod.templates;
           loading.resolve();
+          fireChangeLocaleCallbacks();
         }
         // Else another locale was requested in the meantime. Don't resolve or
         // reject, because the newer load call is going to use the same promise.
@@ -163,6 +166,40 @@ export const localeReady: (() => Promise<void>) & {
   _LIT_LOCALIZE_LOCALE_READY_?: never;
 } = () => loading.promise;
 
+/**
+ * Add the given function to the set of callbacks that will be invoked whenever
+ * the locale changes and its localized messages are ready.
+ *
+ * Use this function to re-render your application whenever the locale is changed.
+ *
+ * If you are using LitElement, consider using LocalizedLitElement, which performs
+ * this re-rendering automatically.
+ */
+export const addLocaleChangeCallback: ((callback: () => void) => void) & {
+  _LIT_LOCALIZE_ADD_LOCALE_CHANGE_CALLBACK_?: never;
+} = (callback: () => void) => {
+  changeLocaleCallbacks.add(callback);
+};
+
+/**
+ * Remove the given function from the set of callbacks that will be invoked
+ * whenever the locale changes and its localized messages are ready.
+ */
+export const removeLocaleChangeCallback: ((callback: () => void) => void) & {
+  _LIT_LOCALIZE_REMOVE_LOCALE_CHANGE_CALLBACK_?: never;
+} = (callback: () => void) => {
+  changeLocaleCallbacks.delete(callback);
+};
+
+/**
+ * Fire all of the registered change locale callback functions.
+ */
+const fireChangeLocaleCallbacks = () => {
+  for (const callback of changeLocaleCallbacks) {
+    callback();
+  }
+};
+
 /**
  * Make a string or lit-html template localizable.
  *

src_client/index.ts

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright (c) 2020 The Polymer Project Authors. All rights reserved.
+ * This code may only be used under the BSD style license found at
+ * http://polymer.github.io/LICENSE.txt The complete set of authors may be found
+ * at http://polymer.github.io/AUTHORS.txt The complete set of contributors may
+ * be found at http://polymer.github.io/CONTRIBUTORS.txt Code distributed by
+ * Google as part of the polymer project is also subject to an additional IP
+ * rights grant found at http://polymer.github.io/PATENTS.txt
+ */
+
+import {LitElement} from 'lit-element';
+import {
+  addLocaleChangeCallback,
+  removeLocaleChangeCallback,
+  localeReady,
+} from './index.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Constructor<T> = new (...args: any[]) => T;
+
+/**
+ * Class mixin for LitElement-based custom elements that ensures rendering is
+ * aligned with the currently active locale.
+ *
+ * Defers rendering until messages for the active locale have loaded, and
+ * triggers re-rendering every time the active locale changes.
+ *
+ * When using lit-localize in transform mode, applications of this mixin are
+ * automatically removed.
+ *
+ * Usage:
+ *
+ *   import {Localized} from 'lit-localize/localized-element.js';
+ *   import {msg} from 'lit-localize';
+ *   import {LitElement, html} from 'lit-html';
+ *
+ *   class MyElement extends Localized(LitElement) {
+ *     render() {
+ *       return html`<b>${msg('greeting', 'Hello World')}</b>`;
+ *     }
+ *   }
+ */
+function _Localized<T extends Constructor<LitElement>>(Base: T): T {
+  class LocalizedLitElement extends Base {
+    private __boundRequestUpdate = this.requestUpdate.bind(this);
+
+    connectedCallback() {
+      super.connectedCallback();
+      addLocaleChangeCallback(this.__boundRequestUpdate);
+    }
+
+    disconnectedCallback() {
+      super.disconnectedCallback();
+      removeLocaleChangeCallback(this.__boundRequestUpdate);
+    }
+
+    protected async performUpdate(): Promise<unknown> {
+      await localeReady();
+      return super.performUpdate();
+    }
+  }
+
+  return LocalizedLitElement;
+}
+
+export const Localized: typeof _Localized & {
+  _LIT_LOCALIZE_LOCALIZED_?: never;
+} = _Localized;

src_client/localized-element.ts

@@ -1,5 +1,6 @@
-import {html} from 'lit-html';
-import {msg} from '../../../lib_client/index.js';
+import {LitElement, html} from 'lit-element';
+import {msg, getLocale} from '../../../lib_client/index.js';
+import {Localized} from '../../../lib_client/localized-element.js';
 
 msg('string', 'Hello World!');
 
@@ -14,3 +15,11 @@ msg(
   'https://www.example.com/',
   'World'
 );
+
+export class MyElement extends Localized(LitElement) {
+  render() {
+    return html`<p>
+      ${msg('lit', html`Hello <b><i>World!</i></b>`)} (${getLocale()})
+    </p>`;
+  }
+}