@lion/ui 0.0.1 → 0.0.3

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

@@ -0,0 +1,78 @@
+# Input Datepicker >> Use Cases ||20
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import { MinMaxDate, IsDateDisabled } from '@lion/ui/form-core.js';
+import { loadDefaultFeedbackMessages } from '@lion/ui/validate-messages.js';
+import { formatDate } from '@lion/ui/localize.js';
+import '@lion/ui/define/lion-input-datepicker.js';
+```
+
+## Minimum and maximum date
+
+Below are examples of different validators for dates.
+
+```js preview-story
+export const minimumAndMaximumDate = () => html`
+  <lion-input-datepicker
+    label="MinMaxDate"
+    .modelValue=${new Date('2018/05/30')}
+    .validators=${[new MinMaxDate({ min: new Date('2018/05/24'), max: new Date('2018/06/24') })]}
+  >
+    <div slot="help-text">
+      Enter a date between ${formatDate(new Date('2018/05/24'))} and ${formatDate(
+        new Date('2018/06/24'),
+      )}.
+    </div>
+  </lion-input-datepicker>
+`;
+```
+
+## Disable specific dates
+
+```js preview-story
+export const disableSpecificDates = () => html`
+  <lion-input-datepicker
+    label="IsDateDisabled"
+    help-text="You're not allowed to choose any 15th."
+    .validators=${[new IsDateDisabled(d => d.getDate() === 15)]}
+  ></lion-input-datepicker>
+`;
+```
+
+## Calendar heading
+
+You can modify the heading of the calendar with the `.calendarHeading` property or `calendar-heading` attribute for simple values.
+
+By default, it will take the label value.
+
+```js preview-story
+export const calendarHeading = () => html`
+  <lion-input-datepicker
+    label="Date"
+    .calendarHeading="${'Custom heading'}"
+    .modelValue=${new Date()}
+  ></lion-input-datepicker>
+`;
+```
+
+## Disabled
+
+You can disable datepicker inputs.
+
+```js preview-story
+export const disabled = () => html`
+  <lion-input-datepicker label="Disabled" disabled></lion-input-datepicker>
+`;
+```
+
+## Read only
+
+You can set datepicker inputs to `readonly`, which will prevent the user from opening the calendar popup.
+
+```js preview-story
+export const readOnly = () => html`
+  <lion-input-datepicker label="Readonly" readonly .modelValue="${new Date()}">
+  </lion-input-datepicker>
+`;
+```

package/docs/components/input-email/index.md

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

package/docs/components/input-email/overview.md

@@ -0,0 +1,32 @@
+# Input Email >> Overview ||10
+
+A web component based on the generic text input field. Its purpose is to provide a way for users to fill in an email.
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-input-email.js';
+```
+
+```js preview-story
+export const main = () => {
+  return html` <lion-input-email label="Email" name="email"></lion-input-email> `;
+};
+```
+
+## Features
+
+- Based on our [input](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/components/input/overview.md)
+- Makes use of email [validators](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/systems/form/validate.md) with corresponding error messages in different languages
+  - IsEmail (default)
+
+## Installation
+
+```bash
+npm i --save @lion/ui
+```
+
+```js
+import { LionInputEmail } from '@lion/ui/input-email.js';
+// or
+import '@lion/ui/define/lion-input-email.js';
+```

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

@@ -0,0 +1,48 @@
+# Input Email >> Use Cases ||20
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import { Validator } from '@lion/ui/form-core.js';
+import '@lion/ui/define/lion-input-email.js';
+```
+
+## Faulty Prefilled
+
+When prefilling with a faulty input, an error feedback message will show.
+
+Use `loadDefaultFeedbackMessages` to get our default feedback messages displayed on it.
+
+```js preview-story
+export const faultyPrefilled = () => html`
+  <lion-input-email .modelValue=${'foo'} label="Email"></lion-input-email>
+`;
+```
+
+## Custom Validator
+
+```js preview-story
+export const customValidator = () => {
+  class GmailOnly extends Validator {
+    static get validatorName() {
+      return 'GmailOnly';
+    }
+    execute(value) {
+      let hasError = false;
+      if (!(value.indexOf('gmail.com') !== -1)) {
+        hasError = true;
+      }
+      return hasError;
+    }
+    static async getMessage() {
+      return 'You can only use gmail.com email addresses.';
+    }
+  }
+  return html`
+    <lion-input-email
+      .modelValue=${'foo@bar.com'}
+      .validators=${[new GmailOnly()]}
+      label="Email"
+    ></lion-input-email>
+  `;
+};
+```

package/docs/components/input-iban/index.md

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

package/docs/components/input-iban/overview.md

@@ -0,0 +1,37 @@
+# Input Iban >> Overview ||10
+
+A web component based on the generic text input field.
+Its purpose is to provide a way for users to fill in an IBAN (International Bank Account Number).
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-input-iban.js';
+```
+
+```js preview-story
+export const main = () => {
+  return html` <lion-input-iban label="Account" name="account"></lion-input-iban> `;
+};
+```
+
+## Features
+
+- Based on our [input](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/components/input/overview.md)
+- Default label in different languages
+- Makes use of IBAN specific [validate](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/systems/form/validate.md) with corresponding error messages in different languages
+  - IsIBAN (default)
+  - IsCountryIBAN
+- Parses IBANs automatically
+- Formats IBANs automatically
+
+## Installation
+
+```bash
+npm i --save @lion/ui
+```
+
+```js
+import { LionInputIban } from '@lion/ui/input-iban.js';
+// or
+import '@lion/ui/define/lion-input-amount.js';
+```

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

@@ -0,0 +1,102 @@
+# Input Iban >> Use Cases ||20
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import { loadDefaultFeedbackMessages } from '@lion/ui/validate-messages.js';
+import { IsCountryIBAN, IsNotCountryIBAN } from '@lion/ui/input-iban.js';
+import '@lion/ui/define/lion-input-iban.js';
+```
+
+## Prefilled
+
+```js preview-story
+export const prefilled = () => html`
+  <lion-input-iban .modelValue=${'NL20INGB0001234567'} name="iban" label="IBAN"></lion-input-iban>
+`;
+```
+
+## Faulty Prefilled
+
+```js preview-story
+export const faultyPrefilled = () => html`
+  <lion-input-iban
+    .modelValue=${'NL20INGB0001234567XXXX'}
+    name="iban"
+    label="IBAN"
+  ></lion-input-iban>
+`;
+```
+
+## Country Restrictions
+
+By default, we validate the input to ensure the IBAN is valid.
+To get the default feedback message for this default validator, use `loadDefaultFeedbackMessages` from `@lion/form-core`.
+
+In the example below, we show how to use an additional validator that restricts the `input-iban` to IBANs from only certain countries.
+
+```js preview-story
+export const countryRestrictions = () => {
+  loadDefaultFeedbackMessages();
+  return html`
+    <lion-input-iban
+      .modelValue=${'DE89370400440532013000'}
+      .validators=${[new IsCountryIBAN('NL')]}
+      name="iban"
+      label="IBAN"
+    ></lion-input-iban>
+    <br />
+    <small>Demo instructions: you can use NL20 INGB 0001 2345 67</small>
+  `;
+};
+```
+
+You can pass a single string value, or an array of strings.
+The latter may be useful, for example if you only want to allow BeNeLux IBANs.
+
+```js preview-story
+export const countryRestrictionsMultiple = () => {
+  loadDefaultFeedbackMessages();
+  return html`
+    <lion-input-iban
+      .modelValue=${'DE89370400440532013000'}
+      .validators=${[new IsCountryIBAN(['BE', 'NL', 'LU'])]}
+      name="iban"
+      label="IBAN"
+    ></lion-input-iban>
+    <br />
+    <small>Demo instructions: you can use:</small>
+    <ul>
+      <li><small>BE68 5390 0754 7034</small></li>
+      <li><small>NL20 INGB 0001 2345 67</small></li>
+      <li><small>LU28 0019 4006 4475 0000</small></li>
+    </ul>
+  `;
+};
+```
+
+## Blacklisted Country
+
+By default, we validate the input to ensure the IBAN is valid.
+To get the default feedback message for this default validator, use `loadDefaultFeedbackMessages` from `@lion/form-core`.
+
+In the example below, we show how to use an additional validator that blocks IBANs from certain countries.
+
+You can pass a single string value, or an array of strings.
+
+```js preview-story
+export const blacklistedCountry = () => {
+  loadDefaultFeedbackMessages();
+  return html`
+    <lion-input-iban
+      .modelValue=${'DE89370400440532013000'}
+      .validators=${[new IsNotCountryIBAN(['RO', 'NL'])]}
+      name="iban"
+      label="IBAN"
+    ></lion-input-iban>
+    <br />
+    <small>
+      Demo instructions: Try <code>RO 89 RZBR 6997 3728 4864 5577</code> and watch it fail
+    </small>
+  `;
+};
+```

package/docs/components/input-range/index.md

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

package/docs/components/input-range/overview.md

@@ -0,0 +1,34 @@
+# Input Range >> Overview ||10
+
+A web component based on the native range input. Its purpose is to provide a way for users to select one value from a range of values.
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-input-range.js';
+```
+
+```js preview-story
+export const main = () => html`
+  <lion-input-range min="200" max="500" .modelValue="${300}" label="Input range"></lion-input-range>
+`;
+```
+
+## Features
+
+- Based on our [input](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/components/input/overview.md).
+- Shows `modelValue` and `unit` above the range input.
+- Shows `min` and `max` value after the range input.
+- Can hide the `min` and `max` value via `no-min-max-labels`.
+- Makes use of [formatNumber](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/systems/localize/numbers.md) for formatting and parsing.
+
+## Installation
+
+```bash
+npm i --save @lion/ui
+```
+
+```js
+import { LionInputRange } from '@lion/ui/input-range.js';
+// or
+import '@lion/ui/define/lion-input-range.js';
+```

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

@@ -0,0 +1,108 @@
+# Input Range >> Use Cases ||20
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-input-range.js';
+```
+
+## Units
+
+```js preview-story
+export const units = () => html`
+  <style>
+    lion-input-range {
+      max-width: 400px;
+    }
+  </style>
+  <lion-input-range
+    min="0"
+    max="100"
+    .modelValue="${50}"
+    unit="%"
+    label="Percentage"
+  ></lion-input-range>
+`;
+```
+
+## Steps
+
+```js preview-story
+export const steps = () => html`
+  <lion-input-range
+    style="max-width: 400px;"
+    min="200"
+    max="500"
+    step="50"
+    .modelValue="${300}"
+    label="Input range"
+    help-text="This slider uses increments of 50"
+  ></lion-input-range>
+`;
+```
+
+## Without Min Max Labels
+
+```js preview-story
+export const noMinMaxLabels = () => html`
+  <lion-input-range
+    style="max-width: 400px;"
+    no-min-max-labels
+    min="0"
+    max="100"
+    label="Input range"
+  ></lion-input-range>
+`;
+```
+
+## Disabled
+
+```js preview-story
+export const disabled = () => html`
+  <lion-input-range
+    style="max-width: 400px;"
+    disabled
+    min="200"
+    max="500"
+    .modelValue="${300}"
+    label="Input range"
+  ></lion-input-range>
+`;
+```
+
+## Range Styles
+
+Often, you will style your own range input by changing the pseudo-elements for the slider track and thumb.
+
+These pseudo-elements do not play nice with `::slotted`.
+
+As per [specification](https://drafts.csswg.org/css-scoping/#slotted-pseudo):
+
+> The ::slotted() pseudo-element can be followed by a tree-abiding pseudo-element,
+> like ::slotted()::before, representing the appropriate pseudo-element of the elements
+> represented by the ::slotted() pseudo-element.
+
+The pseudo-elements associated with the slider track/thumb are not tree-abiding, so you can't do:
+
+```css
+::slotted(.form-control)::-webkit-slider-runnable-track
+```
+
+This means you will need to style the slotted native input from the LightDOM,
+and for this we added added our ScopedStylesController as a controller to `LionInputRange`.
+This controller inserts a `<style>` element
+that emulates scoping by generating a uniquely generated class on the LionInputRange component.
+This prevents the styling from conflicting with other elements on the page.
+
+To use it when extending, override `static scopedStyles(scope)`:
+
+```js
+class MyInputRange extends LionInputRange {
+  static scopedStyles(scope) {
+    return css`
+      .${scope} .form-control::-webkit-slider-runnable-track {
+        background-color: lightgreen;
+      }
+    `;
+  }
+}
+```

package/docs/components/input-stepper/index.md

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

package/docs/components/input-stepper/overview.md

@@ -0,0 +1,36 @@
+# Input Stepper >> Overview ||10
+
+A web component that enables the user to increase and decrease a numeric value by predefined range. It is a combination of two buttons and a number input field with an optional slot `after` to suffix the extra information.
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-input-stepper.js';
+```
+
+```js preview-story
+export const main = () => html`
+  <lion-input-stepper max="5" min="0" name="count">
+    <label slot="label">RSVP</label>
+    <div slot="help-text">Max. 5 guests</div>
+  </lion-input-stepper>
+`;
+```
+
+## Features
+
+- Based on our [input](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/components/input/overview.md).
+- Set `min` and `max` value to define the range.
+- Set `step` value in integer or decimal to increase and decrease the value.
+- Use `ArrowUp` or `ArrowDown` to update the value.
+
+## Installation
+
+```bash
+npm i --save @lion/ui
+```
+
+```js
+import { LionInputStepper } from '@lion/ui/input-stepper.js';
+// or
+import '@lion/ui/define/lion-input-stepper.js';
+```

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

@@ -0,0 +1,41 @@
+# Input Stepper >> Use Cases ||20
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-input-stepper.js';
+```
+
+## Default with no specification
+
+When no range or step is defined, it can go infinite with default step value as `1`. You can also specify prefix content using `after` slot.
+
+```js preview-story
+export const defaultMode = () => html`
+  <label>How old is the existence?</label>
+  <lion-input-stepper name="year">
+    <div slot="after">In Billion Years</div>
+  </lion-input-stepper>
+`;
+```
+
+## Step and Value
+
+Use `step` attribute to specify the incrementor or decrementor difference and `value` to set the default value.
+
+```js preview-story
+export const steps = () => html`
+  <p><strong>Min:</strong> 100, <strong>Value:</strong> 200, <strong>Step:</strong> 100</p>
+  <lion-input-stepper min="100" step="100" name="value" value="200"></lion-input-stepper>
+`;
+```
+
+## Range
+
+Use `min` and `max` attribute to specify range.
+
+```js preview-story
+export const range = () => html`
+  <p><strong>Min:</strong> 200, <strong>Max:</strong> 500, <strong>Step:</strong> 100</p>
+  <lion-input-stepper min="200" max="500" name="value" step="100" value="200"></lion-input-stepper>
+`;
+```

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

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

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

@@ -0,0 +1,62 @@
+# Input Tel >> Overview ||10
+
+Input field for entering phone numbers, including validation, formatting and mobile keyboard support.
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import { ref, createRef } from 'lit/directives/ref.js';
+
+import { PhoneUtilManager } from '@lion/ui/input-tel.js';
+import '@lion/ui/define/lion-input-tel.js';
+import { loadDefaultFeedbackMessages } from '@lion/ui/validate-messages.js';
+import '../../../docs/fundamentals/systems/form/assets/h-output.js';
+```
+
+```js preview-story
+export const main = () => {
+  loadDefaultFeedbackMessages();
+  return html`
+    <lion-input-tel
+      .modelValue="${'+639921343959'}"
+      live-format
+      label="Telephone number"
+      name="phoneNumber"
+    ></lion-input-tel>
+    <h-output
+      .show="${[
+        'activeRegion',
+        {
+          name: 'all or allowed regions',
+          processor: el => JSON.stringify(el._allowedOrAllRegions),
+        },
+        'modelValue',
+      ]}" 'modelValue']}"
+      .readyPromise="${PhoneUtilManager.loadComplete}"
+    ></h-output>
+  `;
+};
+```
+
+## Features
+
+- Extends our [input](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/components/input/overview.md)
+- Shows a mobile telephone keypad on mobile (by having a native `<input inputmode="tel">` inside)
+- Can be configured with a list of allowed region codes
+- Will be preconfigured with region derived from locale
+- Has the [e164 standard format](https://en.wikipedia.org/wiki/E.164) as modelValue
+- Uses [awesome-phonenumber](https://www.npmjs.com/package/awesome-phonenumber) (a performant, concise version of [google-lib-phonenumber](https://www.npmjs.com/package/google-libphonenumber)):
+  - Formats phone numbers, based on region code
+  - Validates phone numbers, based on region code
+- Lazy loads awesome-phonenumber, so that the first paint of this component will be brought to your screen as quick as possible
+
+## Installation
+
+```bash
+npm i --save @lion/ui
+```
+
+```js
+import { LionInputTel } from '@lion/ui/input-tel.js';
+// or
+import '@lion/ui/define/lion-input-tel.js';
+```