@lion/ui 0.0.2 → 0.0.3

package/docs/components/icon/overview.md

@@ -0,0 +1,40 @@
+# Icon >> Overview ||10
+
+A web component for displaying icons.
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import { icons } from '@lion/ui/icon.js';
+import '@lion/ui/define/lion-icon.js';
+
+icons.addIconResolver('lion', (iconset, name) => {
+  switch (iconset) {
+    case 'bugs':
+      return import('./assets/iconset-bugs.js').then(module => module[name]);
+    case 'space':
+      return import('./assets/iconset-space.js').then(module => module[name]);
+    case 'misc':
+      return import('./assets/iconset-misc.js').then(module => module[name]);
+    default:
+      throw new Error(`Unknown iconset ${iconset}`);
+  }
+});
+```
+
+```js preview-story
+export const main = () => html`
+  <lion-icon icon-id="lion:space:alienSpaceship" style="width: 50px; height: 50px;"></lion-icon>
+`;
+```
+
+## Installation
+
+```bash
+npm i --save @lion/ui
+```
+
+```js
+import { LionIcon } from '@lion/ui/icon.js';
+// or
+import '@lion/ui/define/lion-icon.js';
+```

package/docs/components/icon/use-cases.md

@@ -0,0 +1,93 @@
+# Icon >> Use Cases ||20
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import { icons } from '@lion/ui/icon.js';
+import './assets/iconset-bugs.js';
+import './assets/iconset-misc.js';
+import * as spaceSet from './assets/iconset-space.js';
+
+import '@lion/ui/define/lion-icon.js';
+
+icons.addIconResolver('lion', (iconset, name) => {
+  switch (iconset) {
+    case 'bugs':
+      return import('./assets/iconset-bugs.js').then(module => module[name]);
+    case 'space':
+      return import('./assets/iconset-space.js').then(module => module[name]);
+    case 'misc':
+      return import('./assets/iconset-misc.js').then(module => module[name]);
+    default:
+      throw new Error(`Unknown iconset ${iconset}`);
+  }
+});
+```
+
+## Icon sets
+
+Icons are displayed using icon sets. These are collections of icons, lazily loaded on demand for performance.
+See the [system documentation](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/systems/icon/overview.md) to learn more about icon sets.
+
+```js preview-story
+export const iconSets = () => html`
+  ${Object.keys(spaceSet).map(
+    name => html`
+      <style>
+        .demo-icon__container {
+          display: inline-flex;
+          position: relative;
+          flex-grow: 1;
+          flex-direction: column;
+          align-items: center;
+          width: 80px;
+          height: 80px;
+          padding: 4px;
+        }
+        .demo-icon__name {
+          font-size: 10px;
+        }
+      </style>
+      <div class="demo-icon__container">
+        <lion-icon icon-id="lion:space:${name}" aria-label="${name}"></lion-icon>
+        <span class="demo-icon__name">${name}</span>
+      </div>
+    `,
+  )}
+`;
+```
+
+If for some reason you don't want to lazy load icons, you can still import and use them
+synchronously.
+
+## Accessibility
+
+It is recommended to add an `aria-label` to provide information to visually impaired users:
+
+A `lion-icon` without an `aria-label` attribute will be automatically given an `aria-hidden` attribute.
+
+```js preview-story
+export const accessibleLabel = () => html`
+  <lion-icon icon-id="lion:misc:arrowLeft" aria-label="Pointing left"></lion-icon>
+`;
+```
+
+## Styling
+
+By default, a `lion-icon` will be `1em` × `1em` (the current line-height).
+
+`lion-icon` uses SVGs and may be styled with CSS, including using CSS properties such as `fill`:
+
+```js preview-story
+export const Styling = () => html`
+  <style>
+    .demo-icon {
+      width: 160px;
+      height: 160px;
+      fill: blue;
+    }
+  </style>
+  <lion-icon icon-id="lion:bugs:bug02" aria-label="Bug" class="demo-icon"></lion-icon>
+`;
+```
+
+See [SVG and CSS](https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/SVG_and_CSS) on MDN web docs for more information.

package/docs/components/index.md

@@ -0,0 +1,7 @@
+# Components ||40
+
+Components are one of the key building blocks of the design system. Their systematic reuse helps to create visual and functional consistency across products.
+
+## Got feedback?
+
+We are always looking for ways on how to improve the our guidelines. If you have any specific need, idea or just want to tell us what you think - [please get in touch here](https://github.com/ing-bank/lion/blob/master/CONTRIBUTING.md).

package/docs/components/input/index.md

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

package/docs/components/input/overview.md

@@ -0,0 +1,36 @@
+# Input >> Overview ||10
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-input.js';
+```
+
+A web component that enhances the functionality of the native `<input>` element.
+
+```js preview-story
+export const main = () => html`<lion-input label="First Name"></lion-input>`;
+```
+
+## Features
+
+- Extra visual elements can be added via `slots`:
+  - **label**: can also be provided via the `label` attribute, but the slot can be used to change the `html` and `CSS` of the label.
+    For example add an `u-sr-only` class to the label to make it visually hidden.
+    A label is always needed for accessibility reasons.
+  - **help-text**: a helper text shown below the label to give extra clarification.
+  - **prefix**: does not have an active use case yet, but the option is in place.
+  - **suffix**: can be used for addons to the input like a calculator, datepicker or addressbook. In these cases a button with an icon is used.
+  - **before**: does not have an active use case yet, but the option is in place.
+  - **after**: can be used to show a currency or percentage.
+- Delegates attributes like `type`, `disabled`, `placeholder` and `readonly` to the native input.
+- Can make use of [validation](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/systems/form/validate.md).
+
+## Installation
+
+```bash
+npm i --save @lion/ui
+```
+
+```js
+import '@lion/ui/define/lion-input.js';
+```

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

@@ -0,0 +1,77 @@
+# Input >> Use Cases ||20
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-input.js';
+```
+
+## Label
+
+Can be provided via the `label` attribute or via the `slot="label"`.
+
+```js preview-story
+export const label = () => html` <lion-input label="Input" name="input"></lion-input> `;
+```
+
+## Label sr-only (a11y)
+
+Can be provided via the `label-sr-only` boolean attribute.
+
+The label will be hidden, but still readable by screen readers.
+
+```js preview-story
+export const labelSrOnly = () =>
+  html` <lion-input label-sr-only label="Input" name="input"></lion-input> `;
+```
+
+> Note: Once we support the ElementInternals API, the equivalent will be `<lion-input aria-label="Input" name="input"></lion-input>`
+
+## Help-text
+
+A helper text shown below the label to give extra clarification.
+
+Just like the `label`, a `help-text` can be provided via the `help-text` attribute, a slot can be used to change the `html` and `CSS` of the help-text.
+For example add an anchor with further explanation.
+
+```js preview-story
+export const helpText = () => html`
+  <lion-input>
+    <label slot="label">Label</label>
+    <div slot="help-text">
+      Help text using <a href="https://example.com/" target="_blank">html</a>
+    </div>
+  </lion-input>
+`;
+```
+
+## Prefilled
+
+```js preview-story
+export const prefilled = () => html`
+  <lion-input .modelValue=${'Prefilled value'} label="Prefilled"></lion-input>
+`;
+```
+
+## Read only
+
+`readonly` attribute will be delegated to the native `<input>` to make it read-only.
+
+This field **will still be included** in the parent fieldset or form's `serializedValue`.
+
+```js preview-story
+export const readOnly = () => html`
+  <lion-input readonly .modelValue=${'This is read only'} label="Read only"></lion-input>
+`;
+```
+
+## Disabled
+
+`disabled` attribute will be delegated to the native `<input>` to make it disabled.
+
+This field **will not be included** in the parent fieldset or form's `serializedValue`.
+
+```js preview-story
+export const disabled = () => html`
+  <lion-input disabled .modelValue=${'This is disabled'} label="Disabled"></lion-input>
+`;
+```

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

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

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

@@ -0,0 +1,49 @@
+# Input Amount >> 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 amount.
+
+For formatting, we use [Intl NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat) with some overrides.
+
+For parsing user input, we provide our own parser that takes into account a number of heuristics, locale and ignores invalid characters.
+Valid characters are digits and separators. Formatting happens on-blur.
+
+If there are no valid characters in the input whatsoever, it will provide an error feedback.
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-input-amount.js';
+```
+
+```js preview-story
+export const main = () => {
+  return html`
+    <lion-input-amount label="Amount" name="amount" currency="USD"></lion-input-amount>
+  `;
+};
+```
+
+## Features
+
+- Based on our [input](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/components/input/overview.md)
+- Makes use of [formatNumber](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/systems/localize/numbers.md) for formatting and parsing.
+- Option to show currency as a suffix
+- Option to override locale to change the formatting and parsing
+- Option to provide additional format options overrides
+- Default label in different languages
+- Can make use of number specific [validators](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/systems/form/validate.md) with corresponding error messages in different languages
+  - IsNumber (default)
+  - MinNumber
+  - MaxNumber
+  - MinMaxNumber
+
+## Installation
+
+```bash
+npm i --save @lion/ui
+```
+
+```js
+import { LionInputAmount } from '@lion/ui/input-amount.js';
+// or
+import '@lion/ui/define/lion-input-amount.js';
+```

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

@@ -0,0 +1,122 @@
+# Input Amount >> Use Cases ||20
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import { MaxLength } from '@lion/ui/form-core.js';
+import { loadDefaultFeedbackMessages } from '@lion/ui/validate-messages.js';
+
+import { localize } from '@lion/ui/localize.js';
+
+import '@lion/ui/define/lion-input-amount.js';
+```
+
+## Negative Number
+
+It will accept negative numbers with a minus symbol.
+
+```js preview-story
+export const negativeNumber = () => html`
+  <lion-input-amount label="Amount" .modelValue=${-123456.78}></lion-input-amount>
+`;
+```
+
+## Set currency suffix
+
+You can optionally set a currency suffix with the `currency` attribute.
+
+```js preview-story
+export const currencySuffix = () => html`
+  <lion-input-amount label="Price" currency="USD" .modelValue=${123456.78}></lion-input-amount>
+`;
+```
+
+## Force locale
+
+Locale can be forced for a specific `lion-input-amount`. It will format the amount according to this locale.
+
+```js preview-story
+export const forceLocale = () => {
+  return html`
+    <lion-input-amount
+      label="Price"
+      currency="JOD"
+      .locale="nl-NL"
+      .modelValue=${123456.78}
+    ></lion-input-amount>
+  `;
+};
+```
+
+> The separators are now flipped due to Dutch locale. On top of that, due to JOD currency, the minimum amount of decimals is 3 by default for this currency.
+
+## Force digits as input
+
+You can use the `preprocessAmount` preprocessor to disable users from inputting anything other than digits or separator characters.
+This is not added by default, but you can add it yourself.
+
+Separator characters include:
+
+- ' ' (space)
+- . (dot)
+- , (comma)
+
+```js preview-story
+import { preprocessAmount } from '@lion/ui/input-amount.js';
+
+export const forceDigits = () => html`
+  <lion-input-amount label="Amount" .preprocessor=${preprocessAmount}></lion-input-amount>
+`;
+```
+
+## Faulty prefilled
+
+This example will show the error message by prefilling it with a faulty `modelValue`.
+
+> If there is 1 or more digit in the input, it will ignore invalid characters instead of showing an error feedback message.
+
+```js preview-story
+export const faultyPrefilled = () => html`
+  <lion-input-amount
+    label="Amount"
+    help-text="Faulty prefilled input will cause error feedback"
+    .modelValue=${'foo'}
+  ></lion-input-amount>
+`;
+```
+
+## Modifying the amount of decimals
+
+You can override certain formatting options similar to how you would do this when using [Intl NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat).
+This example shows formatting to whole numbers.
+
+```js preview-story
+export const noDecimals = () => html`
+  <lion-input-amount
+    label="Amount"
+    help-text="Prefilled and formatted"
+    .formatOptions=${{
+      minimumFractionDigits: 0,
+      maximumFractionDigits: 0,
+    }}
+    .modelValue=${20}
+  >
+  </lion-input-amount>
+`;
+```
+
+## Paste behavior
+
+For copy pasting numbers into the input-amount, there is slightly different parsing behavior.
+
+Normally, when it receives an input with only 1 separator character, we check the locale to determine whether this character is a group (thousand) separator, or a decimal separator.
+When a user pastes the input from a different source, we find this approach (locale-based) quite unreliable, because it may have been copied from a 'mathematical context' (like an Excel sheet) or a context with a different locale.
+Therefore, we use the heuristics based method to parse the input when it is pasted by the user.
+
+### What this means
+
+If the user in an English locale types `400,0` it will become `4,000.00`
+because the locale determines that the comma is a group separator, not a decimal separator.
+
+If the user in an English locale pastes `400,0` instead, it will become `400.00` because we cannot rely on locale.
+Therefore, instead, we determine that the comma cannot be a group separator because it is not followed by 3 digits after.
+It is more likely to be a decimal separator.

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

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

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

@@ -0,0 +1,39 @@
+# Input Date >> Overview ||10
+
+A web component based on the generic text input field. Its purpose is to provide a way for users to fill in a date.
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import { MinDate, MinMaxDate, MaxDate } 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-date.js';
+```
+
+```js preview-story
+export const main = () => html` <lion-input-date label="Date"></lion-input-date> `;
+```
+
+## Features
+
+- Based on our [input](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/components/input/overview.md)
+- Makes use of [formatDate](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/systems/localize/dates.md) for formatting and parsing.
+- Option to override locale to change the formatting and parsing
+- Default label in different languages
+- Can make use of date specific [validators](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/systems/form/validate.md) with corresponding error messages in different languages
+  - IsDate (default)
+  - MinDate
+  - MaxDate
+  - MinMaxDate
+
+## Installation
+
+```bash
+npm i --save @lion/ui
+```
+
+```js
+import { LionInputDate } from '@lion/ui/input-date.js';
+// or
+import '@lion/ui/define/lion-input-date.js';
+```

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

@@ -0,0 +1,83 @@
+# Input Date >> Use Cases ||20
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import { MinDate, MinMaxDate, MaxDate } 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-date.js';
+```
+
+## Is a date
+
+```js preview-story
+export const isADate = () => html`
+  <lion-input-date label="IsDate" .modelValue=${new Date('foo')}> </lion-input-date>
+`;
+```
+
+## With minimum date
+
+```js preview-story
+export const withMinimumDate = () => {
+  loadDefaultFeedbackMessages();
+  return html`
+    <lion-input-date
+      label="MinDate"
+      help-text="Enter a date greater than or equal to today."
+      .modelValue=${new Date('2018/05/30')}
+      .validators=${[new MinDate(new Date())]}
+    >
+    </lion-input-date>
+  `;
+};
+```
+
+## With maximum date
+
+```js preview-story
+export const withMaximumDate = () => {
+  loadDefaultFeedbackMessages();
+  return html`
+    <lion-input-date
+      label="MaxDate"
+      help-text="Enter a date smaller than or equal to today."
+      .modelValue=${new Date('2100/05/30')}
+      .validators=${[new MaxDate(new Date())]}
+    ></lion-input-date>
+  `;
+};
+```
+
+## With minimum and maximum date
+
+```js preview-story
+export const withMinimumAndMaximumDate = () => {
+  loadDefaultFeedbackMessages();
+  return html`
+    <lion-input-date
+      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-date>
+  `;
+};
+```
+
+## Faulty prefilled
+
+```js preview-story
+export const faultyPrefilled = () => html`
+  <lion-input-date
+    label="Date"
+    help-text="Faulty prefilled input will be cleared"
+    .modelValue=${'foo'}
+  ></lion-input-date>
+`;
+```

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

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

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

@@ -0,0 +1,42 @@
+# Input Datepicker >> Overview ||10
+
+A web component based on the date text input field. Its purpose is to provide a way for users to fill in a date with a datepicker.
+For an input field with a big range, such as `birthday-input`, a datepicker is not the best choice due to the high variance between possible inputs.
+We encourage using our standard [input-date](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/components/input-date/overview.md) for this.
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-input-datepicker.js';
+```
+
+```js preview-story
+export const main = () => {
+  return html` <lion-input-datepicker label="Date" name="date"></lion-input-datepicker> `;
+};
+```
+
+## Features
+
+- Input field with a datepicker to help to choose a date
+- Based on our [input-date](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/components/input-date/overview.md)
+- Makes use of our [calendar](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/components/calendar/overview.md) inside the datepicker
+- Makes use of [formatDate](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/systems/localize/dates.md) for formatting and parsing.
+- Option to overwrite locale to change the formatting and parsing
+- Can make use of date specific [validators](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/systems/form/validate.md) with corresponding error messages in different languages
+  - IsDate (default)
+  - MinDate
+  - MaxDate
+  - MinMaxDate
+  - IsDateDisabled
+
+## Installation
+
+```bash
+npm i --save @lion/ui
+```
+
+```js
+import { LionInputDatepicker } from '@lion/ui/input-datepicker.js';
+// or
+import '@lion/ui/define/lion-input-datepicker.js';
+```