@lion/ui 0.0.1 → 0.0.3

package/docs/fundamentals/systems/localize/dates.md

@@ -0,0 +1,195 @@
+# Systems >> Localize >> Format Dates ||40
+
+## Features
+
+- Small file size
+- Uses `Intl.DateFormat` but patches browser inconsistencies
+
+## Formatting
+
+With the `formatDate` you can safely display dates for all languages.
+
+The input value is `new Date('1987/05/12')`.
+
+```js script
+import { css, html } from '@mdjs/mdjs-preview';
+import { formatNumber, formatNumberToParts, formatDate } from '@lion/ui/localize.js';
+import allLocales from './assets/all-locales.js';
+
+const formatDateDemoStyle = css`
+  .demo-table {
+    border-collapse: collapse;
+    text-align: right;
+  }
+  .demo-table thead > tr {
+    border-bottom: 1px solid grey;
+  }
+  .demo-table thead > tr > :first-child,
+  .demo-table tbody > tr > :first-child,
+  .demo-table tfoot > tr > :first-child {
+    text-align: left;
+  }
+  .demo-table th,
+  .demo-table td {
+    padding: 8px;
+  }
+`;
+```
+
+```js preview-story
+export const formatting = () => html`
+  <style>
+    ${formatDateDemoStyle}
+  </style>
+  <table class="demo-table">
+    <thead>
+      <tr>
+        <th>Output</th>
+        <th>Options</th>
+        <th>Code</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>${formatDate(new Date('1987/05/12'))}</td>
+        <td>Default</td>
+        <td><code>formatDate(new Date('1987/05/12'))</code></td>
+      </tr>
+      <tr>
+        <td>
+          ${formatDate(new Date('1987/05/12'), {
+            weekday: 'long',
+            year: 'numeric',
+            month: 'long',
+            day: '2-digit',
+          })}
+        </td>
+        <td>Date display</td>
+        <td>
+          <code
+            >formatDate(new Date(){weekday:'long',year:'numeric',month:'long',day:'2-digit'})</code
+          >
+        </td>
+      </tr>
+      <tr>
+        <td>
+          ${formatDate(new Date('1987/05/12'), {
+            weekday: 'long',
+            month: 'long',
+            day: '2-digit',
+          })}
+        </td>
+        <td>Date without year</td>
+        <td>
+          <code>
+            formatDate(new Date('1987/05/12'), {weekday:'long',month:'long',day:'2-digit'})
+          </code>
+        </td>
+      </tr>
+      <tr>
+        <td>
+          ${formatDate(new Date('1987/05/12'), {
+            weekday: 'long',
+            year: 'numeric',
+            day: '2-digit',
+          })}
+        </td>
+        <td>Date without month</td>
+        <td>
+          <code>
+            formatDate(new Date('1987/05/12'), {weekday:'long',year:'numeric',day:'2-digit'})
+          </code>
+        </td>
+      </tr>
+      <tr>
+        <td>
+          ${formatDate(new Date('1987/05/12'), {
+            weekday: 'long',
+            month: 'long',
+            year: 'numeric',
+          })}
+        </td>
+        <td>Date without day</td>
+        <td>
+          <code>
+            formatDate(new Date('1987/05/12'), { weekday:'long',year:'numeric',month:'long' })
+          </code>
+        </td>
+      </tr>
+      <tr>
+        <td>${formatDate(new Date('1987/05/12'), { locale: 'nl-NL' })}</td>
+        <td>Locale</td>
+        <td><code>formatDate(new Date('1987/05/12'){ locale:'nl-NL' })</code></td>
+      </tr>
+    </tbody>
+  </table>
+`;
+```
+
+## List common locales
+
+The input value is `new Date('1987/05/12')`.
+Formatting happens via
+
+```js
+formatDate(new Date('1987/05/12'), { locale });
+```
+
+```js preview-story
+export const listCommonLocales = () => html`
+  <style>
+    ${formatDateDemoStyle}
+  </style>
+  <table class="demo-table">
+    <thead>
+      <tr>
+        <th>Locale</th>
+        <th>Output</th>
+      </tr>
+    </thead>
+    <tbody>
+      ${['en-GB', 'en-US', 'nl-NL', 'nl-BE', 'fr-FR', 'de-DE'].map(
+        locale => html`
+          <tr>
+            <td>${locale}</td>
+            <td>${formatDate(new Date('1987/05/12'), { locale })}</td>
+          </tr>
+        `,
+      )}
+    </tbody>
+  </table>
+`;
+```
+
+## List all locales
+
+The following list shows date formatting for all known locales.
+
+The input value is `new Date('1987/05/12')`.
+Formatting happens via
+
+```js
+formatDate(new Date('1987/05/12'), { locale });
+```
+
+```js preview-story
+export const listAllLocales = () => html`
+  <style>
+    ${formatDateDemoStyle}
+  </style>
+  <table class="demo-table">
+    <tr>
+      <th>Locale</th>
+      <th>Output</th>
+    </tr>
+    ${Object.keys(allLocales).map(
+      locale => html`
+        <tr>
+          <td>${locale}</td>
+          <td>${formatDate(new Date('1987/05/12'), { locale })}</td>
+        </tr>
+      `,
+    )}
+  </table>
+`;
+```

package/docs/fundamentals/systems/localize/index.md

@@ -0,0 +1,3 @@
+# Systems >> Localize ||30
+
+-> go to Overview

package/docs/fundamentals/systems/localize/numbers.md

@@ -0,0 +1,217 @@
+# Systems >> Localize >> Format Numbers ||30
+
+## Features
+
+- Small file size
+- Uses `Intl.NumberFormat` but patches browser inconsistencies
+
+## Formatting
+
+With the `formatNumber` you can safely display a number for all languages.
+
+The input value is `1234.56`.
+
+```js script
+import { html, css } from '@mdjs/mdjs-preview';
+import { formatNumber, formatNumberToParts } from '@lion/ui/localize.js';
+import allLocales from './assets/all-locales.js';
+
+const formatNumberDemoStyle = css`
+  .demo-table {
+    border-collapse: collapse;
+    text-align: right;
+  }
+  .demo-table thead > tr {
+    border-bottom: 1px solid grey;
+  }
+  .demo-table thead > tr > :first-child,
+  .demo-table tbody > tr > :first-child,
+  .demo-table tfoot > tr > :first-child {
+    text-align: left;
+  }
+  .demo-table th,
+  .demo-table td {
+    padding: 8px;
+  }
+`;
+const value = 1234.56;
+```
+
+```js preview-story
+export const formatting = () => html`
+  <style>
+    ${formatNumberDemoStyle}
+  </style>
+  <table class="demo-table">
+    <thead>
+      <tr>
+        <th>Options</th>
+        <th>Output</th>
+        <th>Code</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>Default</td>
+        <td>${formatNumber(value)}</td>
+        <td></td>
+      </tr>
+      <tr>
+        <td>Currency symbol</td>
+        <td>
+          ${formatNumber(value, {
+            style: 'currency',
+            currencyDisplay: 'symbol',
+            currency: 'EUR',
+          })}
+        </td>
+        <td>
+          <code
+            >formatNumber({ style: 'currency', currencyDisplay: 'symbol', currency: 'EUR' })</code
+          >
+        </td>
+      </tr>
+      <tr>
+        <td>Currency code</td>
+        <td>
+          ${formatNumber(value, {
+            style: 'currency',
+            currencyDisplay: 'code',
+            currency: 'EUR',
+          })}
+        </td>
+        <td>
+          <code>formatNumber({ style: 'currency', currencyDisplay: 'code', currency: 'EUR' })</code>
+        </td>
+      </tr>
+      <tr>
+        <td>Locale</td>
+        <td>${formatNumber(value, { locale: 'nl-NL' })}</td>
+        <td><code>formatNumber({ locale: 'nl-NL' })</code></td>
+      </tr>
+      <tr>
+        <td>No decimals</td>
+        <td>
+          ${formatNumber(value, {
+            minimumFractionDigits: 0,
+            maximumFractionDigits: 0,
+          })}
+        </td>
+        <td>
+          <code>formatNumber({ minimumFractionDigits: 0, maximumFractionDigits: 0, })</code>
+        </td>
+      </tr>
+    </tbody>
+  </table>
+`;
+```
+
+## Formatting parts
+
+`formatNumberToParts` allows to get individual parts of a number on all browsers.
+
+The input value `1234.56` gets formatted via
+
+```js
+formatNumberToParts(value, { style: 'currency', currency: 'EUR' });
+```
+
+```js preview-story
+export const formattingParts = () => html`
+  <style>
+    ${formatNumberDemoStyle}
+  </style>
+  <table class="demo-table">
+    <thead>
+      <tr>
+        <th>Part</th>
+        <th>Output</th>
+      </tr>
+    </thead>
+    <tbody>
+      ${formatNumberToParts(1234.56, { style: 'currency', currency: 'EUR' }).map(
+        part => html`
+          <tr>
+            <td>${part.type}</td>
+            <td>${part.value}</td>
+          </tr>
+        `,
+      )}
+    </tbody>
+  </table>
+`;
+```
+
+## List common locales
+
+The input value is `1234.56`.
+Formatting happens via
+
+```js
+formatNumber(1234.56, { locale, style: 'currency', currency: 'EUR' });
+formatNumber(1234.56, { locale, style: 'currency', currency: 'USD' });
+```
+
+```js preview-story
+export const listCommonLocales = () => html`
+  <style>
+    ${formatNumberDemoStyle}
+  </style>
+  <table class="demo-table">
+    <thead>
+      <tr>
+        <th>Locale</th>
+        <th>Output Euro</th>
+        <th>Output US Dollar</th>
+      </tr>
+    </thead>
+    <tbody>
+      ${['en-GB', 'en-US', 'nl-NL', 'nl-BE', 'fr-FR', 'de-DE'].map(
+        locale => html`
+          <tr>
+            <td>${locale}</td>
+            <td>${formatNumber(1234.56, { locale, style: 'currency', currency: 'EUR' })}</td>
+            <td>${formatNumber(1234.56, { locale, style: 'currency', currency: 'USD' })}</td>
+          </tr>
+        `,
+      )}
+    </tbody>
+  </table>
+`;
+```
+
+## List all locales
+
+The following list show number formatting for all known locales.
+
+The input value is `1234.56`.
+Formatting happens via
+
+```js
+formatNumber(1234.56, { locale, style: 'currency', currency: 'EUR' });
+formatNumber(1234.56, { locale, style: 'currency', currency: 'USD' });
+```
+
+```js preview-story
+export const listAllLocales = () => html`
+  <style>
+    ${formatNumberDemoStyle}
+  </style>
+  <table class="demo-table">
+    <tr>
+      <th>Locale</th>
+      <th>Output Euro</th>
+      <th>Output US Dollar</th>
+    </tr>
+    ${Object.keys(allLocales).map(
+      locale => html`
+        <tr>
+          <td>${locale}</td>
+          <td>${formatNumber(1234.56, { locale, style: 'currency', currency: 'EUR' })}</td>
+          <td>${formatNumber(1234.56, { locale, style: 'currency', currency: 'USD' })}</td>
+        </tr>
+      `,
+    )}
+  </table>
+`;
+```

package/docs/fundamentals/systems/localize/overview.md

@@ -0,0 +1,48 @@
+# Systems >> Localize >> Overview ||10
+
+Is meant to translate text into multiple languages.
+In it's simplest form it is a function that returns the translated text for a namespace + key.
+
+## Features
+
+- Uses es modules
+- Formatting of numbers, amounts
+- Formatting of dates
+
+Further examples and a more in depth description can be found at the [Use Cases Page](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/systems/localize/use-cases.md).
+
+## Content
+
+| Feature                                  | Description                                   |
+| ---------------------------------------- | --------------------------------------------- |
+| [Translate Text](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/systems/localize/text.md)    | Load and translate text in multiple languages |
+| [Format Numbers](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/systems/localize/numbers.md) | Format numbers in multiple languages          |
+| [Format Dates](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/systems/localize/dates.md)     | Format dates in multiple languages            |
+
+## Installation
+
+```bash
+npm i --save @lion/ui
+```
+
+```js
+import { localize } from '@lion/ui/localize.js';
+```
+
+### Example
+
+The locale which will be loaded by default is accessed via the `localize.locale`.
+
+The single source of truth for page's locale is `<html lang="my-LOCALE">`.
+At the same time the interaction should happen via `localize.locale` getter/setter to be able to notify and react to the change.
+
+```js
+import { localize } from '@lion/ui/localize.js';
+
+localize.addEventListener('localeChanged', () => {
+  // do smth when data is loaded for a new locale
+});
+
+// changes locale, syncs to `<html lang="es-ES">` and fires the event above
+localize.locale = 'es-ES';
+```

package/docs/fundamentals/systems/localize/rationale.md

@@ -0,0 +1,62 @@
+# Systems >> Localize >> Rationale ||60
+
+## Requirements
+
+- loading translations per a web component or a module scope
+- loading translations lazily
+- loading translations from an API
+- bundling and injecting translations for improving the initial page load time
+- using variables in translations
+- formatting dates and numbers according to a user's locale
+- changing the language on the page without a full reload
+- using JavaScript standards
+- compatibility with modern tools like rollup and webpack
+- backwards compatibility with Polymer CLI
+- integration with lit-html and LitElement
+
+## Decision making
+
+### Building block of the localization system
+
+We chose ES modules as building blocks because:
+
+- this is a future proof standard
+- support for loading both statically and dynamically
+- good support in tools like rollup and webpack
+- reusability of same translations between dialects of the same language
+
+We decided to split all translation data into immutable namespaces because:
+
+- there is a need for scopes to have a fine control over data
+- namespaces can be loaded individually and bundled too (if needed)
+- it is possible to consistently load all translations for a new language without full page reload (immutability is a key prerequisite here)
+
+### Localization of numbers and dates
+
+We decided to use `<html lang>` as a source of truth for the locale value because:
+
+- this is a standard place in HTML
+- it allows to support different tools like Google Chrome translate
+
+We chose `Intl MessageFormat` as a format for translation parts because:
+
+- it is the most stable solution for the web
+- it is being standardized at the moment
+- it supports formatting dates and numbers out of the box
+
+### Fallbacks
+
+> Important: language-only locales are now removed, and cause an error if you try to use it. This is because language only locales cause bugs with date and number formatting. It also makes writing locale based tooling harder and more cumbersome.
+
+We decided to have a fallback mechanism in case a dialect (e.g. `nl-NL.js`) is not defined, but generic language (e.g. `nl.js`) is, because we wanted to support legacy applications which used
+
+[Polymer's AppLocalizeBehavior](https://polymer-library.polymer-project.org/3.0/docs/apps/localize) and could not instantly switch to using full dialects.
+
+We decided to have a fallback locale (`en-GB` by default):
+
+- so that an app can work (with English where the gaps are) until everything is translated to all supported languages
+- to allow Google Chrome translate feature to work and use a reliable source for translations when a user asks the page to be translated to an unsupported language
+
+### Switch statements in the loader functions
+
+We add switch statements to each of the loader functions to be backwards compatible with Polymer CLI.

package/docs/fundamentals/systems/localize/text.md

@@ -0,0 +1,125 @@
+# Systems >> Localize >> Translate Text ||20
+
+## As a function
+
+```js script
+import { html, render, LitElement } from '@mdjs/mdjs-preview';
+import { localize, formatNumber, formatDate, LocalizeMixin } from '@lion/ui/localize.js';
+import '@lion/ui/define-helpers/sb-locale-switcher.js';
+```
+
+```js preview-story
+export const asFunction = () => {
+  const wrapper = document.createElement('div');
+  let message = 'Loading...';
+  function update() {
+    message = localize.msg('lit-html-example:body');
+    render(
+      html`
+        <p>${message}</p>
+        <sb-locale-switcher></sb-locale-switcher>
+      `,
+      wrapper,
+    );
+  }
+  localize
+    .loadNamespace({
+      'lit-html-example': locale => import(`./assets/${locale}.js`),
+    })
+    .then(() => {
+      update();
+    });
+  localize.addEventListener('localeChanged', () => {
+    localize.loadingComplete.then(() => update());
+  });
+  return wrapper;
+};
+```
+
+```js
+localize.msg('lit-html-example:body'); // for en-GB: I am from England
+localize.msg('lit-html-example:body'); // for nl-NL: Ik kom uit Nederland
+// ...
+```
+
+## Web Component
+
+For use in a web component we have `LocalizeMixin` that lets you define namespaces and awaits loading of those translations.
+
+```js preview-story
+export const webComponent = () => {
+  class MessageExample extends LocalizeMixin(LitElement) {
+    static get localizeNamespaces() {
+      return [
+        { 'lit-html-example': locale => import(`./assets/translations/${locale}.js`) },
+        ...super.localizeNamespaces,
+      ];
+    }
+
+    render() {
+      return html`
+        <div aria-live="polite">
+          <p>${localize.msg('lit-html-example:body')}</p>
+        </div>
+      `;
+    }
+  }
+  if (!customElements.get('message-example')) {
+    customElements.define('message-example', MessageExample);
+  }
+  return html`
+    <message-example></message-example>
+    <sb-locale-switcher></sb-locale-switcher>
+  `;
+};
+```
+
+```js
+class MessageExample extends LocalizeMixin(LitElement) {
+  render() {
+    return html`
+      <div aria-live="polite">
+        <p>${localize.msg('lit-html-example:body')}</p>
+      </div>
+    `;
+  }
+}
+```
+
+## Google Translate integration
+
+When Google Translate is enabled, it takes control of the html[lang] attribute.
+Below, we find a simplified example that illustrates this.
+
+### The problem
+
+A developer initializes a page like this (and instructs localize to fetch data for `en-US` locale)
+
+```html
+<html lang="en-US"></html>
+```
+
+If Google Translate is enabled and set to French, it will change html[lang]:
+to `<html lang="fr">`
+
+Now `localize` will fetch data for locale `fr`. There are two problems here:
+
+- There might be no available data for locale `fr`
+- Let's imagine data were loaded for `fr`. If Google Translate is turned off again,
+  the page content will consist of a combination of different locales.
+
+### How to solve this
+
+To trigger support for Google Translate, we need to configure two attributes
+
+```html
+<html lang="en-US" data-localize-lang="en-US"></html>
+```
+
+- html[data-localize-lang] will be read by `localize` and used for fetching data
+- html[lang] will be configured for accessibility purposes (it will makes sure the
+  page is accessible if localize would be lazy loaded).
+
+When Google Translate is set to French, we get: `<html lang="fr" data-localize-lang="en-US">`
+
+The page is accessible and `localize` will fetch the right resources