Use a window event instead of custom callback registry for locale changes

Author: aomarks

README.md

@@ -40,7 +40,7 @@ configureLocalization({
 In transform mode, this function is not required, and calls to it will be
 replaced with `undefined`.
 
-### `getLocale(): string`
+### `getLocale() => string`
 
 Return the active locale code.
 
@@ -54,15 +54,15 @@ the `loadLocale` function that was passed to `configureLocalization`.
 
 In transform mode, calls to this function are replaced with `undefined`.
 
-### `localeReady(): Promise`
+### `localeReady() => Promise`
 
 Return a promise that is resolved when the next set of templates are loaded and
 available for rendering. Applications in runtime mode should always `await localeReady()` before rendering.
 
 In transform mode, calls to this function are replaced with
 `Promise.resolve(undefined)`.
 
-### `msg(id: string, template, ...args): string|TemplateResult`
+### `msg(id: string, template, ...args) => string|TemplateResult`
 
 Make a string or lit-html template localizable.
 
@@ -111,27 +111,25 @@ template for each emitted locale. For example:
 html`Hola <b>${getUsername()}!</b>`;
 ```
 
-### `addLocaleChangeCallback(callback: () => void)`
+### `LOCALE_CHANGED_EVENT: string`
 
-Add the given function to the set of callbacks that will be invoked whenever the
-locale changes and its localized messages are ready.
+Whenever the locale changes and templates have finished loading, an event by
+this name (`"lit-localize-locale-changed"`) is dispatched to `window`.
 
-Use this function to re-render your application whenever the locale is changed.
+You can listen for this event to know when your application should be
+re-rendered following a locale change. See also the
+[`Localized`](#localized-mixin) mixin, which automatically re-renders
+`LitElement` classes using this event.
 
-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.
+```typescript
+import {LOCALE_CHANGED_EVENT} from 'lit-localize';
 
-In transform mode, calls to this function are replaced with `undefined`.
+window.addEventListener(LOCALE_CHANGED_EVENT, () => {
+  renderApplication();
+});
+```
 
-## `LocalizedLitElement`
+## `Localized` mixin
 
 If you are using [LitElement](https://lit-element.polymer-project.org/), then
 you can use the `Localized`

src/outputters/transform.ts

@@ -118,62 +118,62 @@ class Transformer {
       return undefined;
     }
 
-    // configureLocalization(...) -> undefined
-    if (
-      this.isCallToTaggedFunction(node, '_LIT_LOCALIZE_CONFIGURE_LOCALIZATION_')
-    ) {
-      return ts.createIdentifier('undefined');
-    }
+    if (ts.isCallExpression(node)) {
+      // configureLocalization(...) -> undefined
+      if (
+        this.typeHasProperty(
+          node.expression,
+          '_LIT_LOCALIZE_CONFIGURE_LOCALIZATION_'
+        )
+      ) {
+        return ts.createIdentifier('undefined');
+      }
 
-    // getLocale() -> "es-419"
-    if (this.isCallToTaggedFunction(node, '_LIT_LOCALIZE_GET_LOCALE_')) {
-      return ts.createStringLiteral(this.locale);
-    }
+      // getLocale() -> "es-419"
+      if (this.typeHasProperty(node.expression, '_LIT_LOCALIZE_GET_LOCALE_')) {
+        return ts.createStringLiteral(this.locale);
+      }
 
-    // setLocale("es-419") -> undefined
-    if (this.isCallToTaggedFunction(node, '_LIT_LOCALIZE_SET_LOCALE_')) {
-      return ts.createIdentifier('undefined');
-    }
+      // setLocale("es-419") -> undefined
+      if (this.typeHasProperty(node.expression, '_LIT_LOCALIZE_SET_LOCALE_')) {
+        return ts.createIdentifier('undefined');
+      }
 
-    // localeReady() -> Promise.resolve(undefined)
-    if (this.isCallToTaggedFunction(node, '_LIT_LOCALIZE_LOCALE_READY_')) {
-      return ts.createCall(
-        ts.createPropertyAccess(ts.createIdentifier('Promise'), 'resolve'),
-        [],
-        [ts.createIdentifier('undefined')]
-      );
-    }
+      // localeReady() -> Promise.resolve(undefined)
+      if (
+        this.typeHasProperty(node.expression, '_LIT_LOCALIZE_LOCALE_READY_')
+      ) {
+        return ts.createCall(
+          ts.createPropertyAccess(ts.createIdentifier('Promise'), 'resolve'),
+          [],
+          [ts.createIdentifier('undefined')]
+        );
+      }
 
-    // addLocaleChangeCallback(...) -> undefined
-    if (
-      this.isCallToTaggedFunction(
-        node,
-        '_LIT_LOCALIZE_ADD_LOCALE_CHANGE_CALLBACK_'
-      )
-    ) {
-      return ts.createIdentifier('undefined');
+      // Localized(LitElement) -> LitElement
+      if (this.typeHasProperty(node.expression, '_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];
+      }
     }
 
-    // removeLocaleChangeCallback(...) -> undefined
+    // LOCALE_CHANGED_EVENT -> "lit-localize-locale-changed"
+    //
+    // This is slightly odd, but by replacing the LOCALE_CHANGED_EVENT const
+    // with its static string value, we don't have to be smart about deciding
+    // when to remove the 'lit-localize' module import, since we can assume that
+    // everything it exports will be transformed out.
     if (
-      this.isCallToTaggedFunction(
-        node,
-        '_LIT_LOCALIZE_REMOVE_LOCALE_CHANGE_CALLBACK_'
-      )
+      ts.isIdentifier(node) &&
+      this.typeHasProperty(node, '_LIT_LOCALIZE_LOCALE_CHANGED_EVENT_')
     ) {
-      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.createStringLiteral('lit-localize-locale-changed');
     }
 
     return ts.visitEachChild(node, this.boundVisitNode, this.context);
@@ -429,19 +429,16 @@ class Transformer {
   }
 
   /**
-   * Return whether the given node is call to a function which is is "tagged"
-   * with the given special identifying property (e.g. "_LIT_LOCALIZE_MSG_").
+   * Return whether the tpe of the given node is "tagged" with the given special
+   * identifying property (e.g. "_LIT_LOCALIZE_MSG_").
    */
-  isCallToTaggedFunction(
+  typeHasProperty(
     node: ts.Node,
-    tagProperty: string
+    propertyName: string
   ): node is ts.CallExpression {
-    if (!ts.isCallExpression(node)) {
-      return false;
-    }
-    const type = this.typeChecker.getTypeAtLocation(node.expression);
+    const type = this.typeChecker.getTypeAtLocation(node);
     const props = this.typeChecker.getPropertiesOfType(type);
-    return props.some((prop) => prop.escapedName === tagProperty);
+    return props.some((prop) => prop.escapedName === propertyName);
   }
 }
 

src/tests/transform.unit.test.ts

@@ -382,23 +382,12 @@ test('localeReady() -> Promise.resolve(undefined)', (t) => {
   );
 });
 
-test('addLocaleChangeCallback -> undefined', (t) => {
+test('LOCALE_CHANGED_EVENT => "lit-localize-locale-changed"', (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`,
+    `import {LOCALE_CHANGED_EVENT} from './lib_client/index.js';
+     window.addEventListener(LOCALE_CHANGED_EVENT, () => console.log('ok'));`,
+    `window.addEventListener('lit-localize-locale-changed', () => console.log('ok'));`,
     [],
     false
   );

src_client/index.ts

@@ -88,7 +88,18 @@ 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>();
+
+/**
+ * Whenever the locale changes and templates have finished loading, an event by
+ * this name ("lit-localize-locale-changed") is dispatched to window.
+ *
+ * You can listen for this event to know when your application should be
+ * re-rendered following a locale change. See also the Localized mixin, which
+ * automatically re-renders LitElement classes using this event.
+ */
+export const LOCALE_CHANGED_EVENT: string & {
+  _LIT_LOCALIZE_LOCALE_CHANGED_EVENT_?: never;
+} = 'lit-localize-locale-changed';
 
 /**
  * Set runtime configuration parameters for lit-localize. This function must be
@@ -135,14 +146,14 @@ export const setLocale: ((newLocale: string) => void) & {
   }
   if (newLocale === sourceLocale) {
     loading.resolve();
-    fireChangeLocaleCallbacks();
+    window.dispatchEvent(new Event(LOCALE_CHANGED_EVENT));
   } else {
     loadLocale(newLocale).then(
       (mod) => {
         if (newLocale === activeLocale) {
           templates = mod.templates;
           loading.resolve();
-          fireChangeLocaleCallbacks();
+          window.dispatchEvent(new Event(LOCALE_CHANGED_EVENT));
         }
         // 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.
@@ -166,40 +177,6 @@ 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/localized-element.ts

@@ -10,11 +10,7 @@
  */
 
 import {LitElement} from 'lit-element';
-import {
-  addLocaleChangeCallback,
-  removeLocaleChangeCallback,
-  localeReady,
-} from './index.js';
+import {localeReady, LOCALE_CHANGED_EVENT} from './index.js';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type Constructor<T> = new (...args: any[]) => T;
@@ -42,17 +38,20 @@ type Constructor<T> = new (...args: any[]) => T;
  *   }
  */
 function _Localized<T extends Constructor<LitElement>>(Base: T): T {
-  class LocalizedLitElement extends Base {
-    private __boundRequestUpdate = this.requestUpdate.bind(this);
+  class Localized extends Base {
+    private __boundRequestUpdate = () => this.requestUpdate();
 
     connectedCallback() {
       super.connectedCallback();
-      addLocaleChangeCallback(this.__boundRequestUpdate);
+      window.addEventListener(LOCALE_CHANGED_EVENT, this.__boundRequestUpdate);
     }
 
     disconnectedCallback() {
       super.disconnectedCallback();
-      removeLocaleChangeCallback(this.__boundRequestUpdate);
+      window.removeEventListener(
+        LOCALE_CHANGED_EVENT,
+        this.__boundRequestUpdate
+      );
     }
 
     protected async performUpdate(): Promise<unknown> {
@@ -61,7 +60,7 @@ function _Localized<T extends Constructor<LitElement>>(Base: T): T {
     }
   }
 
-  return LocalizedLitElement;
+  return Localized;
 }
 
 export const Localized: typeof _Localized & {