@lion/ui 0.0.2 → 0.0.3

package/docs/components/input-tel/src/h-region-code-table.js

@@ -0,0 +1,109 @@
+import { LitElement, css, html } from 'lit';
+import { repeat } from 'lit/directives/repeat.js';
+import { ScopedStylesController } from '@lion/ui/core.js';
+import { regionMetaList } from '../../select-rich/src/regionMetaList.js';
+
+export class HRegionCodeTable extends LitElement {
+  static properties = {
+    regionMeta: Object,
+  };
+
+  constructor() {
+    super();
+    /** @type {ScopedStylesController} */
+    this.scopedStylesController = new ScopedStylesController(this);
+  }
+
+  /**
+   * @param {CSSResult} scope
+   */
+  static scopedStyles(scope) {
+    return css`
+      /* Custom input range styling comes here, be aware that this won't work for polyfilled browsers */
+      .${scope} .sr-only {
+        position: absolute;
+        top: 0;
+        width: 1px;
+        height: 1px;
+        overflow: hidden;
+        clip-path: inset(100%);
+        clip: rect(1px, 1px, 1px, 1px);
+        white-space: nowrap;
+        border: 0;
+        margin: 0;
+        padding: 0;
+      }
+
+      .${scope} table {
+        position: relative;
+        height: 300px;
+      }
+
+      .${scope} th {
+        border-left: none;
+        border-right: none;
+        position: sticky;
+        top: -1px;
+      }
+
+      .${scope} th .backdrop {
+        background-color: white;
+        opacity: 0.95;
+        filter: blur(4px);
+        position: absolute;
+        inset: -5px;
+      }
+
+      .${scope} th .content {
+        position: relative;
+      }
+
+      .${scope} td {
+        border-left: none;
+        border-right: none;
+      }
+    `;
+  }
+
+  // Render to light dom, so global table styling will be applied
+  createRenderRoot() {
+    return this;
+  }
+
+  render() {
+    const finalRegionMetaList = this.regionMetaList || regionMetaList;
+    return html`
+      <table role="table">
+        <caption class="sr-only">
+          Region codes
+        </caption>
+        <thead>
+          <tr>
+            <th align="left">
+              <span class="backdrop"></span><span class="content">country name</span>
+            </th>
+            <th align="right">
+              <span class="backdrop"></span><span class="content">region code</span>
+            </th>
+            <th align="right">
+              <span class="backdrop"></span><span class="content">country code</span>
+            </th>
+          </tr>
+        </thead>
+        <tbody>
+          ${repeat(
+            finalRegionMetaList,
+            regionMeta => regionMeta.regionCode,
+            ({ regionCode, countryCode, flagSymbol, nameForLocale }) =>
+              html` <tr>
+                <td align="left"><span aria-hidden="true">${flagSymbol}</span> ${nameForLocale}</td>
+                <td align="right">${regionCode}</td>
+                <td align="right">${countryCode}</td>
+              </tr>`,
+          )}
+        </tbody>
+      </table>
+    `;
+  }
+}
+customElements.define('h-region-code-table', HRegionCodeTable);

package/docs/components/input-tel/use-cases.md

@@ -0,0 +1,307 @@
+# Input Tel >> Use Cases ||20
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import { ref, createRef } from 'lit/directives/ref.js';
+import { Unparseable } from '@lion/ui/form-core.js';
+import { localize } from '@lion/ui/localize.js';
+import { loadDefaultFeedbackMessages } from '@lion/ui/validate-messages.js';
+import { PhoneUtilManager } from '@lion/ui/input-tel.js';
+import '@lion/ui/define/lion-input-tel.js';
+import './src/h-region-code-table.js';
+import '../../../docs/fundamentals/systems/form/assets/h-output.js';
+
+// TODO: make each example load/use the dependencies by default
+// loadDefaultFeedbackMessages();
+```
+
+## Regions: some context
+
+Say we have the following telephone number from Madrid, Spain: `+34919930432`.
+
+It contains a [country code](https://en.wikipedia.org/wiki/Country_code) (34), an [area code](https://en.wikipedia.org/wiki/Telephone_numbering_plan#Area_code) (91) and a [dial code](https://en.wikipedia.org/wiki/Mobile_dial_code) (+34 91).
+Input Tel interprets phone numbers based on their [region code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2): a two character long region representation('ES' in the telephone number above).
+
+The table below lists all possible regions worldwide. When [allowed regions](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/components/input-tel/#allowed-regions) are not configured,
+all of them will be supported as values of Input Tel.
+
+```js story
+export const regionCodesTable = () => {
+  loadDefaultFeedbackMessages();
+  return html`<h-region-code-table></h-region-code-table>`;
+};
+```
+
+### Active region
+
+The active region (accessible via readonly accessor `.activeRegion`) determines how validation and formatting
+should be applied. It is dependent on the following factors:
+
+- [allowed regions](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/components/input-tel/#allowed-regions): a list that determines what is allowed to become .activeRegion. If
+  [.allowedRegions has only one entry](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/components/input-tel/#restrict-to-one-region), .activeRegion will always be this value.
+- the modelValue or viewValue: once it contains sufficient info to derive its region code (and
+  the derived code is inside [allowed regions](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/components/input-tel/#allowed-regions) if configured)
+- active locale (and the derived locale is inside [allowed regions](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/components/input-tel/#allowed-regions) if configured)
+
+What follows from the list above is that .activeRegion can change dynamically, after a value
+change in the text box by the user (or when locales or allowed regions would be changed by the
+Application Developer).
+
+### How active region is computed
+
+The following heuristic will be applied:
+
+1. check for **allowed regions**: if one region defined in .allowedRegions, use it.
+2. check for **user input**: try to derive active region from user input
+3. check for **locale**: try to get the region from locale (`html[lang]` attribute)
+
+```js preview-story
+export const heuristic = () => {
+  loadDefaultFeedbackMessages();
+
+  const initialAllowedRegions = ['CN', 'ES'];
+  const [inputTelRef, outputRef, selectRef] = [createRef(), createRef(), createRef()];
+
+  const setDerivedActiveRegionScenario = (
+    scenarioToSet,
+    inputTel = inputTelRef.value,
+    output = outputRef.value,
+  ) => {
+    if (scenarioToSet === 'only-allowed-region') {
+      // activeRegion will be the top allowed region, which is 'NL'
+      inputTel.modelValue = undefined;
+      inputTel.allowedRegions = ['NL']; // activeRegion will always be the only option
+      output.innerText = '.activeRegion (NL) is only allowed region';
+    } else if (scenarioToSet === 'user-input') {
+      // activeRegion will be based on phone number => 'BE'
+      inputTel.allowedRegions = ['NL', 'BE', 'DE'];
+      inputTel.modelValue = '+3261234567'; // BE number
+      output.innerText = '.activeRegion (BE) is derived (since within allowedRegions)';
+    } else if (scenarioToSet === 'locale') {
+      localize.locale = 'en-GB';
+      // activeRegion will be `html[lang]`
+      inputTel.modelValue = undefined;
+      inputTel.allowedRegions = undefined;
+      output.innerText = `.activeRegion (${inputTel._langIso}) set to locale when inside allowed or all regions`;
+    } else {
+      output.innerText = '';
+    }
+  };
+  return html`
+    <select
+      aria-label="Set scenario"
+      @change="${({ target }) => setDerivedActiveRegionScenario(target.value)}"
+    >
+      <option value="">--- select scenario ---</option>
+      <option value="only-allowed-region">1. only allowed region</option>
+      <option value="user-input">2. user input</option>
+      <option value="locale">3. locale</option>
+    </select>
+    <output style="display:block; min-height: 1.5em;" id="myOutput" ${ref(outputRef)}></output>
+    <lion-input-tel
+      ${ref(inputTelRef)}
+      @model-value-changed="${({ detail }) => {
+        if (detail.isTriggeredByUser && selectRef.value) {
+          selectRef.value.value = '';
+        }
+      }}"
+      name="phoneNumber"
+      label="Active region"
+      .allowedRegions="${initialAllowedRegions}"
+    ></lion-input-tel>
+    <h-output
+      .show="${[
+        'activeRegion',
+        {
+          name: 'all or allowed regions',
+          processor: el => JSON.stringify(el._allowedOrAllRegions),
+        },
+        'modelValue',
+      ]}"
+      .readyPromise="${PhoneUtilManager.loadComplete}"
+    ></h-output>
+  `;
+};
+```
+
+## Allowed regions
+
+`.allowedRegions` is an array of one or more region codes.
+Once it is configured, validation and formatting will be restricted to those
+values that are present in this list.
+
+> Note that for [InputTelDropdown](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/components/input-tel-dropdown/index.md), only allowed regions will
+> be shown in the dropdown list.
+
+```js preview-story
+export const allowedRegions = () => {
+  loadDefaultFeedbackMessages();
+  return html`
+    <lion-input-tel
+      label="Allowed regions 'NL', 'BE', 'DE'"
+      help-text="Type '+31'(NL), '+32'(BE) or '+49'(DE) and see how activeRegion changes"
+      .allowedRegions="${['NL', 'BE', 'DE']}"
+      .modelValue="${'+31612345678'}"
+      name="phoneNumber"
+    ></lion-input-tel>
+    <h-output
+      .show="${['modelValue', 'activeRegion']}"
+      .readyPromise="${PhoneUtilManager.loadComplete}"
+    ></h-output>
+  `;
+};
+```
+
+### Restrict to one region
+
+When one allowed region is configured, validation and formatting will be restricted to just that
+region (that means that changes of the region via viewValue won't have effect).
+
+```js preview-story
+export const oneAllowedRegion = () => {
+  loadDefaultFeedbackMessages();
+  return html`
+    <lion-input-tel
+      label="Only allowed region 'DE'"
+      help-text="Restricts validation / formatting to one region"
+      .allowedRegions="${['DE']}"
+      .modelValue="${'+31612345678'}"
+      name="phoneNumber"
+    ></lion-input-tel>
+    <h-output
+      .show="${['modelValue', 'activeRegion', 'validationStates']}"
+      .readyPromise="${PhoneUtilManager.loadComplete}"
+    ></h-output>
+  `;
+};
+```
+
+## Format
+
+### Format strategy
+
+Determines what the formatter output should look like.
+Formatting strategies as provided by awesome-phonenumber / google-libphonenumber.
+
+Possible values:
+
+| strategy      |                 output |
+| :------------ | ---------------------: |
+| e164          |         `+46707123456` |
+| international |     `+46 70 712 34 56` |
+| national      |        `070-712 34 56` |
+| significant   |            `707123456` |
+| rfc3966       | `tel:+46-70-712-34-56` |
+
+Also see:
+
+- [awesome-phonenumber documentation](https://www.npmjs.com/package/awesome-phonenumber)
+
+```js preview-story
+export const formatStrategy = () => {
+  loadDefaultFeedbackMessages();
+  const inputTel = createRef();
+  return html`
+    <select @change="${({ target }) => (inputTel.value.formatStrategy = target.value)}">
+      <option value="e164">e164</option>
+      <option value="international">international</option>
+      <option value="national">national</option>
+      <option value="significant">significant</option>
+      <option value="rfc3966">rfc3966</option>
+    </select>
+    <lion-input-tel
+      ${ref(inputTel)}
+      label="Format strategy"
+      help-text="Choose a strategy above"
+      .modelValue=${'+46707123456'}
+      format-strategy="national"
+      name="phoneNumber"
+    ></lion-input-tel>
+    <h-output
+      .show="${['modelValue', 'formatStrategy']}"
+      .readyPromise="${PhoneUtilManager.loadComplete}"
+    ></h-output>
+  `;
+};
+```
+
+### Format country code style
+
+You can also style the country code with parentheses.
+
+```js preview-story
+export const formatCountryCodeStyle = () => {
+  loadDefaultFeedbackMessages();
+  const inputTel = createRef();
+  return html`
+    <select @change="${({ target }) => (inputTel.value.formatStrategy = target.value)}">
+      <option value="e164">e164</option>
+      <option value="international">international</option>
+      <option value="rfc3966">rfc3966</option>
+    </select>
+    <lion-input-tel
+      ${ref(inputTel)}
+      label="Format strategy"
+      help-text="Choose a strategy above"
+      .modelValue=${'+46707123456'}
+      format-country-code-style="parentheses"
+      name="phoneNumber"
+    ></lion-input-tel>
+    <h-output
+      .show="${['modelValue', 'formatStrategy']}"
+      .readyPromise="${PhoneUtilManager.loadComplete}"
+    ></h-output>
+  `;
+};
+```
+
+### Live format
+
+Type '6' in the example below to see how the phone number is formatted during typing.
+
+See [awesome-phonenumber documentation](https://www.npmjs.com/package/awesome-phonenumber)
+
+```js preview-story
+export const liveFormat = () => {
+  loadDefaultFeedbackMessages();
+  return html`
+    <lion-input-tel
+      label="Realtime format on user input"
+      help-text="Partial numbers are also formatted"
+      .modelValue=${new Unparseable('+31')}
+      format-strategy="international"
+      live-format
+      name="phoneNumber"
+    ></lion-input-tel>
+  `;
+};
+```
+
+## Active phone number type
+
+The readonly acessor `.activePhoneNumberType` outputs the current phone number type, based on
+the textbox value.
+
+Possible types: `fixed-line`, `fixed-line-or-mobile`, `mobile`, `pager`, `personal-number`, `premium-rate`, `shared-cost`, `toll-free`, `uan`, `voip`, `unknown`
+
+Also see:
+
+- [awesome-phonenumber documentation](https://www.npmjs.com/package/awesome-phonenumber)
+
+```js preview-story
+export const activePhoneNumberType = () => {
+  loadDefaultFeedbackMessages();
+  return html`
+    <lion-input-tel
+      label="Active phone number type"
+      .modelValue="${'+31612345678'}"
+      format-strategy="international"
+      name="phoneNumber"
+    ></lion-input-tel>
+    <h-output
+      .show="${['activePhoneNumberType']}"
+      .readyPromise="${PhoneUtilManager.loadComplete}"
+    ></h-output>
+  `;
+};
+```

package/docs/components/input-tel-dropdown/examples.md

@@ -0,0 +1,32 @@
+# Input Tel Dropdown >> Examples ||30
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-select-rich.js';
+import './src/intl-input-tel-dropdown.js';
+import { loadDefaultFeedbackMessages } from '@lion/ui/validate-messages.js';
+```
+
+## Input Tel International
+
+A visually advanced Subclasser implementation of `LionInputTelDropdown`.
+
+Inspired by:
+
+- [intl-tel-input](https://intl-tel-input.com/)
+- [react-phone-input-2](https://github.com/bl00mber/react-phone-input-2)
+
+```js preview-story
+export const IntlInputTelDropdown = () => {
+  loadDefaultFeedbackMessages();
+  return html`
+    <intl-input-tel-dropdown
+      .preferredRegions="${['NL', 'PH']}"
+      .modelValue=${'+639608920056'}
+      label="Telephone number"
+      help-text="Advanced dropdown and styling"
+      name="phoneNumber"
+    ></intl-input-tel-dropdown>
+  `;
+};
+```

package/docs/components/input-tel-dropdown/index.md

@@ -0,0 +1,3 @@
+# Input Tel Dropdown ||20
+
+-> go to Overview

package/docs/components/input-tel-dropdown/overview.md

@@ -0,0 +1,38 @@
+# Input Tel Dropdown >> Overview ||10
+
+Extension of Input Tel that prefixes a dropdown list that shows all possible regions / countries.
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-input-tel-dropdown.js';
+import { loadDefaultFeedbackMessages } from '@lion/ui/validate-messages.js';
+```
+
+```js preview-story
+export const main = () => {
+  loadDefaultFeedbackMessages();
+  return html`
+    <lion-input-tel-dropdown label="Telephone number" name="phoneNumber"></lion-input-tel-dropdown>
+  `;
+};
+```
+
+## Features
+
+- Extends our [input-tel](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/components/input-tel/overview.md)
+- Shows dropdown list with all possible regions
+- Shows only allowed regions in dropdown list when .allowedRegions is configured
+- Highlights regions on top of dropdown list when .preferredRegions is configured
+- Generates template meta data for advanced
+
+## Installation
+
+```bash
+npm i --save @lion/ui
+```
+
+```js
+import { LionInputTelDropdown } from '@lion/ui/input-tel-dropdown.js';
+// or
+import '@lion/ui/define/lion-input-tel-dropdown.js';
+```

package/docs/components/input-tel-dropdown/src/intl-input-tel-dropdown.js

@@ -0,0 +1,127 @@
+import { ScopedElementsMixin } from '@open-wc/scoped-elements';
+import { html, css } from 'lit';
+import { ref } from 'lit/directives/ref.js';
+import { repeat } from 'lit/directives/repeat.js';
+import { LionInputTelDropdown } from '@lion/ui/input-tel-dropdown.js';
+import {
+  IntlSelectRich,
+  IntlOption,
+  IntlSeparator,
+} from '../../select-rich/src/intl-select-rich.js';
+
+/**
+ * @typedef {import('@lion/ui/input-tel-dropdown/types.js').TemplateDataForDropdownInputTel}TemplateDataForDropdownInputTel
+ */
+
+// Example implementation for https://intl-tel-input.com/
+export class IntlInputTelDropdown extends ScopedElementsMixin(LionInputTelDropdown) {
+  /**
+   * @configure LitElement
+   * @enhance LionInputTelDropdown
+   */
+  static styles = [
+    super.styles,
+    css`
+      :host,
+      ::slotted(*) {
+        font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif;
+        font-size: 14px;
+        line-height: 1.42857143;
+        color: #333;
+      }
+
+      :host {
+        max-width: 300px;
+      }
+
+      .input-group__container {
+        width: 100%;
+        height: 34px;
+        font-size: 14px;
+        line-height: 1.42857143;
+        color: #555;
+        background-color: #fff;
+        background-image: none;
+        border: 1px solid #ccc;
+        border-radius: 4px;
+        -webkit-box-shadow: inset 0 1px 1px rgb(0 0 0 / 8%);
+        box-shadow: inset 0 1px 1px rgb(0 0 0 / 8%);
+        -webkit-transition: border-color ease-in-out 0.15s, -webkit-box-shadow ease-in-out 0.15s;
+        -o-transition: border-color ease-in-out 0.15s, box-shadow ease-in-out 0.15s;
+        transition: border-color ease-in-out 0.15s, box-shadow ease-in-out 0.15s;
+      }
+
+      .input-group__input {
+        padding: 6px;
+        box-sizing: border-box;
+      }
+
+      .input-group__input ::slotted(input) {
+        border: none;
+        outline: none;
+      }
+
+      :host([focused]) .input-group__container {
+        border-color: #66afe9;
+        outline: 0;
+        -webkit-box-shadow: inset 0 1px 1px rgb(0 0 0 / 8%), 0 0 8px rgb(102 175 233 / 60%);
+        box-shadow: inset 0 1px 1px rgb(0 0 0 / 8%), 0 0 8px rgb(102 175 233 / 60%);
+      }
+    `,
+  ];
+
+  static templates = {
+    ...(super.templates || {}),
+    /**
+     * @param {TemplateDataForDropdownInputTel} templateDataForDropdown
+     */
+    dropdown: templateDataForDropdown => {
+      const { refs, data } = templateDataForDropdown;
+      // TODO: once spread directive available, use it per ref (like ref(refs?.dropdown?.ref))
+      return html`
+        <intl-select-rich
+          ${ref(refs?.dropdown?.ref)}
+          label="${refs?.dropdown?.labels?.country}"
+          label-sr-only
+          @model-value-changed="${refs?.dropdown?.listeners['model-value-changed']}"
+          style="${refs?.dropdown?.props?.style}"
+        >
+          ${data?.regionMetaListPreferred?.length
+            ? html` ${repeat(
+                  data.regionMetaListPreferred,
+                  regionMeta => regionMeta.regionCode,
+                  regionMeta =>
+                    html`${this.templates.dropdownOption(templateDataForDropdown, regionMeta)} `,
+                )}<intl-separator></intl-separator>`
+            : ''}
+          ${repeat(
+            data.regionMetaList,
+            regionMeta => regionMeta.regionCode,
+            regionMeta =>
+              html`${this.templates.dropdownOption(templateDataForDropdown, regionMeta)} `,
+          )}
+        </intl-select-rich>
+      `;
+    },
+    /**
+     * @param {TemplateDataForDropdownInputTel} templateDataForDropdown
+     * @param {RegionMeta} regionMeta
+     */
+    // eslint-disable-next-line class-methods-use-this
+    dropdownOption: (templateDataForDropdown, regionMeta) => html`
+      <intl-option .choiceValue="${regionMeta.regionCode}" .regionMeta="${regionMeta}">
+      </intl-option>
+    `,
+  };
+
+  /**
+   * @configure ScopedElementsMixin
+   */
+  static scopedElements = {
+    ...super.scopedElements,
+    'intl-select-rich': IntlSelectRich,
+    'intl-option': IntlOption,
+    'intl-separator': IntlSeparator,
+  };
+}
+customElements.define('intl-input-tel-dropdown', IntlInputTelDropdown);