feat: add uiLang parameter

packages/x-components/src/x-installer/api/api.types.ts

@@ -1,3 +1,4 @@
+import { RequiredProperties } from '@empathyco/x-utils';
 import { XBus } from '../../plugins/x-bus.types';
 import { DocumentDirection } from '../../plugins/x-plugin.types';
 import { XEvent, XEventPayload } from '../../wiring/events.types';
@@ -94,13 +95,13 @@ export interface SnippetConfig {
   /** Customer instance. */
   instance: string;
   /** Backend services environment. */
-  env?: 'live' | 'staging';
+  env?: 'staging';
   /** Execution scope (desktop, mobile, app, ...). */
   scope: string;
-  /** Language to display. */
+  /** Language for the API request, and default value for {@link SnippetConfig.uiLang}. */
   lang: string;
-  /** Language to send to backend services. */
-  searchLang?: string;
+  /** Language to use for the messages. Defaults to {@link SnippetConfig.lang}. */
+  uiLang?: string;
   /** User GDPR consent. */
   consent?: boolean;
   /** Document direction. */
@@ -121,6 +122,13 @@ export interface SnippetConfig {
   [extra: string]: unknown;
 }
 
+/**
+ * A normalised version of the snippet config.
+ *
+ * @public
+ */
+export type NormalisedSnippetConfig = RequiredProperties<SnippetConfig, 'uiLang'>;
+
 /**
  * Information to render a query preview with.
  *

packages/x-components/src/x-installer/x-installer/__tests__/x-installer.spec.ts

@@ -8,6 +8,7 @@ import { XComponentsAdapterDummy } from '../../../__tests__/adapter.dummy';
 import { AnyXModule } from '../../../x-modules/x-modules.types';
 import { InitWrapper, InstallXOptions } from '../types';
 import { XInstaller } from '../x-installer';
+import { SnippetConfig } from '../../api/index';
 
 describe('testing `XInstaller` utility', () => {
   const adapter = XComponentsAdapterDummy;
@@ -25,11 +26,30 @@ describe('testing `XInstaller` utility', () => {
     mounted: jest.fn()
   };
 
-  const snippetConfig = {
+  const getMinimumSnippetConfig = (): SnippetConfig => ({
     instance: 'test',
     lang: 'test',
     scope: 'test'
-  };
+  });
+
+  /**
+   * Creates a Vue component injecting the snippet config.
+   *
+   * @param snippetProperty
+   * @returns A Vue component with the injected snippet config.
+   *
+   * @internal
+   */
+  function createSnippetConfigComponent(
+    snippetProperty: keyof SnippetConfig = 'instance'
+  ): VueConstructor {
+    return Vue.extend({
+      inject: ['snippetConfig'],
+      render(h) {
+        return h('h1', [(this as any).snippetConfig[snippetProperty]]);
+      }
+    });
+  }
 
   beforeEach(() => {
     delete window.initX;
@@ -45,7 +65,7 @@ describe('testing `XInstaller` utility', () => {
       __PRIVATE__xModules,
       initialXModules: [initialXModule],
       vue: createLocalVue()
-    }).init(snippetConfig);
+    }).init(getMinimumSnippetConfig());
     const params = xPluginMock.install.mock.calls[0][1];
 
     expect(xPluginMock.install).toHaveBeenCalledTimes(1);
@@ -59,21 +79,23 @@ describe('testing `XInstaller` utility', () => {
 
   it('creates the public API in global scope by default', () => {
     delete window.InterfaceX;
-    new XInstaller({ adapter, plugin, vue: createLocalVue() }).init(snippetConfig);
+    new XInstaller({ adapter, plugin, vue: createLocalVue() }).init(getMinimumSnippetConfig());
 
     expect(window.InterfaceX).toBeDefined();
     delete window.InterfaceX;
   });
 
   it('does not create the public API passing the api parameter to false', () => {
-    new XInstaller({ adapter, plugin, api: false, vue: createLocalVue() }).init(snippetConfig);
+    new XInstaller({ adapter, plugin, api: false, vue: createLocalVue() }).init(
+      getMinimumSnippetConfig()
+    );
 
     expect(window.InterfaceX).not.toBeDefined();
   });
 
   it('installs the XPlugin using the passed vue', () => {
     const localVue = createLocalVue();
-    new XInstaller({ adapter, plugin, vue: localVue }).init(snippetConfig);
+    new XInstaller({ adapter, plugin, vue: localVue }).init(getMinimumSnippetConfig());
     const vueParam = xPluginMock.install.mock.calls[0][0];
 
     expect(xPluginMock.install).toHaveBeenCalledTimes(1);
@@ -82,7 +104,7 @@ describe('testing `XInstaller` utility', () => {
 
   it('creates a Vue application using the component passed in the app option', async () => {
     await new XInstaller({ adapter, plugin, app: component, vue: createLocalVue() }).init(
-      snippetConfig
+      getMinimumSnippetConfig()
     );
 
     // eslint-disable-next-line  @typescript-eslint/unbound-method
@@ -102,7 +124,7 @@ describe('testing `XInstaller` utility', () => {
       vue,
       vueOptions,
       app: component
-    }).init(snippetConfig);
+    }).init(getMinimumSnippetConfig());
 
     expect(app).toHaveProperty('testMethod');
     expect(app).toHaveProperty('$router');
@@ -128,57 +150,57 @@ describe('testing `XInstaller` utility', () => {
         };
       },
       app: component
-    }).init(snippetConfig);
+    }).init(getMinimumSnippetConfig());
 
     expect(app).toHaveProperty('$router');
     expect(app).toHaveProperty('bus');
-    expect(app).toHaveProperty('snippet', snippetConfig);
+    expect(app).toHaveProperty('snippet', { ...getMinimumSnippetConfig(), uiLang: 'test' });
   });
 
   it('initializes the app with the provided snippet config', async () => {
     const vue = createLocalVue();
-    const { app } = await new XInstaller({
+    const { app, api } = await new XInstaller({
       adapter,
       vue,
-      app: injectSnippetConfigComponent()
-    }).init(snippetConfig);
+      app: createSnippetConfigComponent()
+    }).init(getMinimumSnippetConfig());
 
-    expect(app?.$el).toHaveTextContent(snippetConfig.instance);
+    expect(app?.$el).toHaveTextContent(getMinimumSnippetConfig().instance);
 
-    snippetConfig.instance = 'test-2';
+    api?.setSnippetConfig({ instance: 'test-2' });
     await vue.nextTick();
     expect(app?.$el).toHaveTextContent('test-2');
   });
 
   it('initializes the app when window.initX has the snippet config object', async () => {
     const vue = createLocalVue();
-    window.initX = snippetConfig;
-    const { app } = (await new XInstaller({
+    window.initX = getMinimumSnippetConfig();
+    const { app, api } = (await new XInstaller({
       adapter,
       vue,
-      app: injectSnippetConfigComponent()
+      app: createSnippetConfigComponent()
     }).init()) as InitWrapper;
 
-    expect(app?.$el).toHaveTextContent(snippetConfig.instance);
+    expect(app?.$el).toHaveTextContent(getMinimumSnippetConfig().instance);
 
-    snippetConfig.instance = 'test-2';
+    api?.setSnippetConfig({ instance: 'test-2' });
     await vue.nextTick();
     expect(app?.$el).toHaveTextContent('test-2');
   });
 
   // eslint-disable-next-line max-len
   it('initializes the app when window.initX is a function retrieving the snippet config', async () => {
     const vue = createLocalVue();
-    window.initX = () => snippetConfig;
-    const { app } = (await new XInstaller({
+    window.initX = () => getMinimumSnippetConfig();
+    const { app, api } = (await new XInstaller({
       adapter,
       vue,
-      app: injectSnippetConfigComponent()
+      app: createSnippetConfigComponent()
     }).init()) as InitWrapper;
 
-    expect(app?.$el).toHaveTextContent(snippetConfig.instance);
+    expect(app?.$el).toHaveTextContent(getMinimumSnippetConfig().instance);
 
-    snippetConfig.instance = 'test-2';
+    api?.setSnippetConfig({ instance: 'test-2' });
     await vue.nextTick();
     expect(app?.$el).toHaveTextContent('test-2');
   });
@@ -187,22 +209,50 @@ describe('testing `XInstaller` utility', () => {
   it('does not initialize XComponents when no snippet config is passed and no window.initX is not defined', async () => {
     expect(await new XInstaller({ adapter, plugin, vue: createLocalVue() }).init()).toBeUndefined();
   });
-});
 
-/**
- * Creates a Vue component injecting the snippet config.
- *
- * @returns A Vue component with the injected snippet config.
- *
- * @internal
- */
-function injectSnippetConfigComponent(): VueConstructor {
-  return Vue.extend({
-    inject: ['snippetConfig'],
-    render(h) {
-      // Vue does not provide type safety for inject
-      const instance = (this as any).snippetConfig.instance;
-      return h('h1', [instance]);
-    }
+  describe('`lang` & `uiLang`', () => {
+    it('provides a `uiLang` by default', async () => {
+      const { app } = await new XInstaller({
+        adapter,
+        plugin,
+        vue: createLocalVue(),
+        app: createSnippetConfigComponent('uiLang')
+      }).init({ ...getMinimumSnippetConfig(), lang: 'en' });
+
+      expect(app?.$el).toHaveTextContent('en');
+    });
+
+    it('respects user `uiLang` value', async () => {
+      const { app } = await new XInstaller({
+        adapter,
+        plugin,
+        vue: createLocalVue(),
+        app: createSnippetConfigComponent('uiLang')
+      }).init({ ...getMinimumSnippetConfig(), lang: 'en', uiLang: 'it' });
+      expect(app?.$el).toHaveTextContent('it');
+    });
+
+    it('updates `uiLang` when `lang` is changed', async () => {
+      const vue = createLocalVue();
+      const { app, api } = await new XInstaller({
+        adapter,
+        plugin,
+        vue,
+        app: createSnippetConfigComponent('uiLang')
+      }).init({ ...getMinimumSnippetConfig(), lang: 'en', uiLang: 'it' });
+      expect(app?.$el).toHaveTextContent('it');
+
+      api!.setSnippetConfig({ lang: 'es' });
+      await vue.nextTick();
+      expect(app?.$el).toHaveTextContent('es');
+
+      api!.setSnippetConfig({ uiLang: 'en' });
+      await vue.nextTick();
+      expect(app?.$el).toHaveTextContent('en');
+
+      api!.setSnippetConfig({ lang: 'fr', uiLang: 'it' });
+      await vue.nextTick();
+      expect(app?.$el).toHaveTextContent('it');
+    });
   });
-}
+});

packages/x-components/src/x-installer/x-installer/types.ts

@@ -1,7 +1,7 @@
 import { ComponentOptions, PluginObject, VueConstructor } from 'vue';
 import { XBus } from '../../plugins/x-bus.types';
 import { XPluginOptions } from '../../plugins/x-plugin.types';
-import { SnippetConfig, XAPI } from '../api/api.types';
+import { NormalisedSnippetConfig, XAPI } from '../api/api.types';
 
 /**
  * Interface for the parameter of the constructor of {@link XInstaller} function. It is an extended
@@ -10,25 +10,37 @@ import { SnippetConfig, XAPI } from '../api/api.types';
  * @public
  */
 export interface InstallXOptions<API extends XAPI = XAPI> extends XPluginOptions {
-  /** The Vue component used as root of the application. If is not passed no Vue Application is
-   * initialized, only plugin installed. */
+  /**
+   * The Vue component used as root of the application. If it is not passed, no Vue Application is
+   * initialized, only plugin installed.
+   */
   app?: VueConstructor | ComponentOptions<Vue>;
-  /** The API to expose globally. If is not passed the default {@link BaseXAPI} will be used. If
-   * a `false` value is passed then the API is not created.*/
+  /**
+   * The API to expose globally. If is not passed the default {@link BaseXAPI} will be used. If
+   * a `false` value is passed then the API is not created.
+   */
   api?: API | false;
-  /** The {@link XBus} used in the {@link XPlugin}. If not passed an instance of {@link BaseXBus}
-   * will be used.*/
+  /**
+   * The {@link XBus} used in the {@link XPlugin}. If not passed an instance of {@link BaseXBus}
+   * will be used.
+   */
   bus?: XBus;
-  /** An Element | string to indicate the HTML element that will contain the Vue
+  /**
+   * An Element | string to indicate the HTML element that will contain the Vue
    * application. If string selector is passed and the element doesn't exits, the
-   * {@link XInstaller} will create it. */
+   * {@link XInstaller} will create it.
+   */
   domElement?: Element | string;
-  /** The XPlugin which will be installed. If not passed, an instance of {@link XPlugin} will be
-   * installed.*/
+  /**
+   * The XPlugin which will be installed. If not passed, an instance of {@link XPlugin} will be
+   * installed.
+   */
   plugin?: PluginObject<XPluginOptions>;
-  /** The Vue instance used to install the plugin and to create the Application. If not
+  /**
+   * The Vue instance used to install the plugin and to create the Application. If not
    * passed the default Vue instance is used. This can be useful to use the `localVue`
-   * in the unit tests.*/
+   * in the unit tests.
+   */
   vue?: VueConstructor;
   /**
    * This object can contain any option to pass to Vue instance at the moment of creating the App
@@ -45,6 +57,7 @@ export interface InstallXOptions<API extends XAPI = XAPI> extends XPluginOptions
    * ```
    */
   vueOptions?: VueConstructorPartialArgument;
+
   /**
    * Adds the option to install more Vue plugins, giving access to the {@link SnippetConfig} and
    * the {@link XBus}.
@@ -68,9 +81,11 @@ export interface ExtraPluginsOptions {
   vue: VueConstructor;
   /** The events bus instance used to communicate different part of the x-components. */
   bus: XBus;
-  /** Configuration coming from the client website with options like the lang, or the active
-   * currency. */
-  snippet: SnippetConfig;
+  /**
+   * Configuration coming from the client website with options like the lang, or the active
+   * currency.
+   */
+  snippet: NormalisedSnippetConfig;
 }
 
 /**