@lion/ui 0.25.0 → 0.26.0

package/docs/fundamentals/systems/form/assets/h-output.js

@@ -1,156 +0,0 @@
-import { css, html, LitElement } from 'lit';
-import { LionField } from '@lion/ui/form-core.js';
-import { LionFieldset } from '@lion/ui/fieldset.js';
-
-export class HelperOutput extends LitElement {
-  static properties = {
-    field: Object,
-    show: Array,
-    title: String,
-    readyPromise: Object,
-  };
-
-  static styles = [
-    css`
-      :host {
-        display: block;
-        margin-top: 8px;
-      }
-
-      code {
-        font-size: 8px;
-        background-color: #eee;
-      }
-
-      caption {
-        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;
-      }
-
-      table,
-      th,
-      td {
-        border-bottom: 1px solid rgb(204, 204, 204);
-        border-image: initial;
-        padding: 4px;
-        font-size: 12px;
-        border-left: none;
-        border-right: none;
-        text-align: left;
-      }
-
-      td {
-        max-width: 200px;
-        white-space: nowrap;
-        overflow: hidden;
-        text-overflow: ellipsis;
-      }
-
-      table {
-        border-collapse: collapse;
-      }
-
-      caption {
-        text-align: left;
-      }
-    `,
-  ];
-
-  firstUpdated(changedProperties) {
-    super.firstUpdated(changedProperties);
-    if (!this.field) {
-      // Fuzzy logic, but... practical
-      const prev = this.previousElementSibling;
-      if (prev instanceof LionField || prev instanceof LionFieldset) {
-        this.field = prev;
-      }
-    }
-    this.__rerender = this.__rerender.bind(this);
-
-    const storyRoot = this.closest('[mdjs-story-name]') || this.parentElement;
-
-    storyRoot.addEventListener('model-value-changed', this.__rerender);
-    storyRoot.addEventListener('mousemove', this.__rerender);
-    // this.field.addEventListener('blur', this.__rerender);
-    storyRoot.addEventListener('focusin', this.__rerender);
-    storyRoot.addEventListener('focusout', this.__rerender);
-    storyRoot.addEventListener('change', this.__rerender);
-
-    if (this.field._inputNode.form) {
-      this.field._inputNode.form.addEventListener('submit', this.__rerender);
-    }
-
-    if (this.readyPromise) {
-      this.readyPromise.then(() => {
-        this.__rerender();
-      });
-    }
-  }
-
-  __rerender() {
-    setTimeout(() => {
-      const f = this.field;
-      this.field = null;
-      this.field = f;
-    });
-  }
-
-  // eslint-disable-next-line class-methods-use-this
-  __renderProp(prop) {
-    const field = this.field || {};
-    let resultText = '';
-
-    if (typeof prop === 'string') {
-      const p = field[prop];
-      if (typeof p === 'boolean') {
-        return p === true ? '✓' : '';
-      }
-      if (typeof p === 'undefined') {
-        return html`<code>undefined</code>`;
-      }
-      if (typeof p === 'object' && p !== null) {
-        return JSON.stringify(p);
-      }
-      resultText = p;
-    } else {
-      resultText = prop.processor(field);
-    }
-
-    return html`<span title="${resultText}">${resultText}</span>`;
-  }
-
-  constructor() {
-    super();
-    // eslint-disable-next-line wc/no-constructor-attributes
-    this.title = 'States';
-  }
-
-  render() {
-    const computePropName = prop => (typeof prop === 'string' ? prop : prop.name);
-    return html`
-      <table>
-        <caption>
-          ${this.title}
-        </caption>
-        <tr>
-          ${this.show.map(prop => html`<th>${computePropName(prop)}</th>`)}
-        </tr>
-        <tr></tr>
-        <tr>
-          ${this.show.map(prop => html`<td>${this.__renderProp(prop)}</td>`)}
-        </tr>
-      </table>
-    `;
-  }
-}
-
-customElements.define('h-output', HelperOutput);

package/docs/fundamentals/systems/form/formatting-and-parsing.md

@@ -1,258 +0,0 @@
----
-parts:
-  - Formatting and Parsing
-  - Form
-  - Systems
-title: 'Formatting and Parsing'
-eleventyNavigation:
-  key: Systems >> Form >> Formatting and Parsing
-  title: Formatting and Parsing
-  order: 21
-  parent: Systems >> Form
----
-
-# Formatting and Parsing
-
-```js script
-import { html } from '@mdjs/mdjs-preview';
-import '@lion/ui/define/lion-input.js';
-import { Unparseable } from '@lion/ui/form-core.js';
-import { liveFormatPhoneNumber } from '@lion/ui/input-tel.js';
-import './assets/h-output.js';
-```
-
-> For demo purposes, below we use `<lion-input>` which is a basic extension of `<lion-field>`.
-> Almost all fields share the same functionality as `<lion-input>`.
-
-## Different values
-
-The `FormatMixin` which is used in all lion fields automatically keeps track of:
-
-- `modelValue`, which is a result of parsing
-- `formattedValue`, which is a result of formatting
-- `serializedValue`, which is a result of serializing
-
-Our fields can automatically format/parse/serialize user input or an input set imperatively by an Application Developer.
-
-Below are some concrete examples of implementations of formatters and parsers mimicking a (basic) amount input.
-
-> For an actual amount input, check out [lion-input-amount](https://github.com/ing-bank/lion/blob/9575386e5fb419f7dbd3b893be4c4ce7925bcb2e/docs/components/input-amount/overview.md).
-> This comes with its own formatter, parser, serializer.
-
-### Parsers & modelValue
-
-A parser should return a `modelValue`.
-
-The `modelValue` is the result of the parser function.
-It should be considered as the **internal value used for validation and reasoning/logic**.
-The `modelValue` is 'ready for consumption' by the outside world (think of a Date object or a float).
-The `modelValue` can (and is recommended to) be used as both input value and output value of the `<lion-input>`.
-
-In essence, the `modelValue` acts as a Single Source of Truth in our form fields and therefore a single way of programmatical interaction.
-Formatted values, serialized values and reflected-back view values are derived from it.
-
-You can listen to `model-value-changed` event on all fields.
-Internally this is also used as the main trigger for re-evaluating validation, visibility and interaction states.
-
-Examples:
-
-- For a `date input`: a String '20/01/1999' will be converted to new Date('1999/01/20')
-- For an `amount input`: a formatted String '1.234,56' will be converted to a Number: 1234.56
-
-You can set a parser function on the `<lion-input>` to set parsing behavior.
-In this example, we parse the input and try to convert it to a `Number`.
-
-```js preview-story
-export const parser = () => html`
-  <lion-input
-    label="Number Example"
-    help-text="Uses .parser to create model values from view values"
-    .parser="${viewValue => Number(viewValue)}"
-    .modelValue="${1234567890}"
-    @model-value-changed="${({ target }) => console.log(target)}"
-  ></lion-input>
-  <h-output .show="${['modelValue']}"></h-output>
-`;
-```
-
-#### Unparseable
-
-If a parser tries to parse and it returns undefined, the `modelValue` will be an instance of
-`Unparseable`.
-
-This object contains a type `'unparseable'`, and a `viewValue` which contains the String value of
-what the user tried to input.
-
-The formatted result of this that is reflected to the user will be the `viewValue` of the
-`Unparseable` instance, so basically nothing happens for the user.
-
-```js preview-story
-export const unparseable = () => html`
-  <lion-input
-    label="Number Example"
-    help-text="Uses .parser and return undefined if Number() cannot parse"
-    .parser="${viewValue => Number(viewValue) || undefined}"
-    value="${'1234abc567890'}"
-  ></lion-input>
-  <h-output .show="${['modelValue']}"></h-output>
-`;
-```
-
-### Formatters
-
-A formatter should return a `formattedValue`. It accepts the current modelValue and an options object.
-
-Below is a very naive and limited parser that ignores non-digits. The formatter then uses `Intl.NumberFormat` to format it with group (thousand) separators.
-
-Formatted value is reflected back to the user `on-blur` of the field, but only if the field has no errors (validation).
-
-```js preview-story
-export const formatters = () => {
-  const formatDate = (modelValue, options) => {
-    if (!(typeof modelValue === 'number')) {
-      return options.formattedValue;
-    }
-    return new Intl.NumberFormat('en-GB').format(modelValue);
-  };
-  return html`
-    <lion-input
-      label="Number Example"
-      help-text="Uses .formatter to create view value"
-      .parser="${viewValue => Number(viewValue.replace(/[^0-9]/g, ''))}"
-      .formatter="${formatDate}"
-      .modelValue="${1234567890}"
-    >
-    </lion-input>
-    <h-output .show="${['modelValue', 'formattedValue']}"></h-output>
-  `;
-};
-```
-
-> The options object holds a fallback value that shows what should be presented on
-> screen when the user input resulted in an invalid `modelValue`.
-
-### Serializers and deserializers
-
-A serializer converts the `modelValue` to a `serializedValue`. In this example, we decide we want to store the user input to our hypothetical database, but by parsing it with radix 8 first.
-
-A deserializer converts a value, for example one received from an API, to a `modelValue`. This can be useful for prefilling forms with data from APIs.
-
-> There is no `.deserializedValue` property that stays in sync by default.
-> You need to call `el.deserializer(el.modelValue)` manually yourself.
-
-```js preview-story
-export const deserializers = () => {
-  const mySerializer = (modelValue, options) => {
-    return parseInt(modelValue, 8);
-  };
-  const myDeserializer = (myValue, options) => {
-    return new Number(myValue);
-  };
-  return html`
-    <lion-input
-      label="Date Example"
-      help-text="Uses .(de)serializer to restore serialized modelValues"
-      .parser="${viewValue => Number(viewValue.replace(/[^0-9]/g, ''))}"
-      .serializer="${mySerializer}"
-      .deserializer="${myDeserializer}"
-      .modelValue="${1234567890}"
-    ></lion-input>
-    <h-output .show="${['modelValue', 'serializedValue']}"></h-output>
-  `;
-};
-```
-
-### Preprocessors
-
-A preprocessor converts the user input immediately on input.
-This makes it useful for preventing invalid input or doing other processing tasks before the viewValue hits the parser.
-
-In the example below, we do not allow you to write digits.
-
-```js preview-story
-export const preprocessors = () => {
-  const preprocess = value => {
-    return value.replace(/[0-9]/g, '');
-  };
-  return html`
-    <lion-input
-      label="Date Example"
-      help-text="Uses .preprocessor to prevent digits"
-      .preprocessor="${preprocess}"
-    ></lion-input>
-    <h-output .show="${['modelValue']}"></h-output>
-  `;
-};
-```
-
-### Live formatters
-
-Live formatters are a specific type of preprocessor, that format a view value during typing.
-Examples:
-
-- a phone number that, during typing formats `+316` as `+31 6`
-- a date that follows a date mask and automatically inserts '-' characters
-
-Type '6' in the example below and see that a space will be added and the caret in the text box
-will be automatically moved along.
-
-```js preview-story
-export const liveFormatters = () => {
-  return html`
-    <lion-input
-      label="Live Format"
-      .modelValue="${new Unparseable('+31')}"
-      help-text="Uses .preprocessor to format during typing"
-      .preprocessor="${(viewValue, { currentCaretIndex, prevViewValue }) => {
-        return liveFormatPhoneNumber(viewValue, {
-          regionCode: 'NL',
-          formatStrategy: 'international',
-          currentCaretIndex,
-          prevViewValue,
-        });
-      }}"
-    ></lion-input>
-    <h-output .show="${['modelValue']}"></h-output>
-  `;
-};
-```
-
-Note that these live formatters need to make an educated guess based on the current (incomplete) view
-value what the users intentions are. When implemented correctly, they can create a huge improvement
-in user experience.
-Next to a changed viewValue, they are also responsible for taking care of the
-caretIndex. For instance, if `+316` is changed to `+31 6`, the caret needs to be moved one position
-to the right (to compensate for the extra inserted space).
-
-#### When to use a live formatter and when a regular formatter?
-
-Although it might feel more logical to configure live formatters inside the `.formatter` function,
-it should be configured inside the `.preprocessor` function. The table below shows differences
-between the two mentioned methods
-
-| Function      | Value type recieved | Reflected back to user on | Supports incomplete values | Supports caret index |
-| :------------ | :------------------ | :------------------------ | :------------------------- | :------------------- |
-| .formatter    | modelValue          | blur (leave)              | No                         | No                   |
-| .preprocessor | viewValue           | keyup (live)              | Yes                        | Yes                  |
-
-## Flow Diagrams
-
-Below we show three flow diagrams to show the flow of formatting, serializing and parsing user input, with the example of a date input:
-
-### Standard flow
-
-Where a user changes the input with their keyboard:
-
-![Standard flow](https://github.com/ing-bank/lion/blob/9575386e5fb419f7dbd3b893be4c4ce7925bcb2e/docs/fundamentals/systems/form/assets/FormatMixinDiagram-1.svg 'Standard flow')
-
-### Unparseable flow
-
-Where a user sets the input to something that is not parseable by the parser:
-
-![Unparseable flow](https://github.com/ing-bank/lion/blob/9575386e5fb419f7dbd3b893be4c4ce7925bcb2e/docs/fundamentals/systems/form/assets/FormatMixinDiagram-2.svg 'Unparseable flow')
-
-### Imperative / programmatic flow
-
-Where the developer sets the modelValue of the input programmatically:
-
-![Imperative flow](https://github.com/ing-bank/lion/blob/9575386e5fb419f7dbd3b893be4c4ce7925bcb2e/docs/fundamentals/systems/form/assets/FormatMixinDiagram-3.svg 'Imperative flow')

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

@@ -1,15 +0,0 @@
----
-parts:
-  - Form
-  - Systems
-title: 'Form'
-eleventyNavigation:
-  key: Systems >> Form
-  title: Form
-  order: 20
-  parent: Systems
----
-
-# Form
-
--> go to Overview

package/docs/fundamentals/systems/form/interaction-states.md

@@ -1,195 +0,0 @@
----
-parts:
-  - Interaction States
-  - Form
-  - Systems
-title: 'Interaction States'
-eleventyNavigation:
-  key: Systems >> Form >> Interaction States
-  title: Interaction States
-  order: 22
-  parent: Systems >> Form
----
-
-# Interaction States
-
-```js script
-import { html, render } from '@mdjs/mdjs-preview';
-import { renderLitAsNode } from '@lion/ui/helpers.js';
-import '@lion/ui/define/lion-input.js';
-import '@lion/ui/define/lion-input-date.js';
-import { Validator, Unparseable, MinDate, Required } from '@lion/ui/form-core.js';
-import './assets/h-output.js';
-```
-
-`InteractionStateMixin` saves meta information about interaction states.
-It allows for creating advanced UX scenarios.
-
-Examples of such scenarios already in our fields:
-
-- Show the validation message of an input only after the user has blurred the input field
-- Hide the validation message when an invalid value becomes valid
-
-Something our subclassers can implement:
-
-- Show a red border around the input right after the input became invalid
-
-The meta information that InteractionStateMixin collects, is stored in the Boolean properties on our fields:
-
-- `touched`, the user blurred the field.
-- `dirty`, the value in the field has changed.
-- `prefilled`, a prepopulated field is not empty.
-
-> You can listen to the events `touched-changed` and `dirty-changed`.
-
-```js preview-story
-export const interactionStates = () => html`
-  <lion-input
-    label="Interaction States"
-    help-text="Interact with this field to see how dirty, touched and prefilled change"
-    .modelValue="${'myValue'}"
-  ></lion-input>
-  <h-output .show="${['touched', 'dirty', 'prefilled', 'focused', 'submitted']}"></h-output>
-`;
-```
-
-## Advanced use cases
-
-### Overriding interaction states
-
-When creating an extension of LionField or LionInput, it can be needed to override the way prefilled values are 'computed'.
-
-The example below shows how this is done for checkboxes/radio-inputs.
-
-```js
-/**
- * @override
- */
-static _isPrefilled(modelValue) {
-  return modelValue.checked;
-}
-```
-
-## When is feedback shown to the user
-
-We show the validity feedback when one of the following conditions is met:
-
-- **prefilled**,
-  the user already filled in something, or the value is prefilled
-  when the form is initially rendered.
-
-- **touched** && **dirty**
-  - When a user starts typing for the first time in a field with for instance `required` validation,
-    error message should not be shown until a field becomes `touched` (a user leaves(blurs) a field).
-  - When a user enters a field without altering the value (making it `dirty` but not `touched`),
-    an error message shouldn't be shown either.
-
-- **submitted**,
-  if the form is submitted, always show the error message.
-
-### Changing the feedback show condition (Subclassers)
-
-You can change the condition upon which feedback gets shown.
-
-In order to override the feedback show conditions, you need to create a custom field and override `_showFeedbackConditionFor` method.
-This method accepts the a `type` parameter which is a String representing the type of feedback (e.g. 'error').
-Then, it returns true of false, depending on whether feedback for that type should be shown or not. That part, you can control.
-
-In the following example we will demonstrate this with interaction states, the most common use case for feedback visibility conditions.
-
-```js preview-story
-export const feedbackCondition = () => {
-  // 1. Initialize variables
-  // properties we want to check conditions for
-  const props = ['touched', 'dirty', 'prefilled', 'focused', 'filled', 'submitted'];
-
-  // 2. Create a validator
-  class OddValidator extends Validator {
-    static get validatorName() {
-      return 'OddValidator';
-    }
-    // eslint-disable-next-line class-methods-use-this
-    execute(value) {
-      let hasError = false;
-      if (!(value.length % 2 !== 0)) {
-        hasError = true;
-      }
-      return hasError;
-    }
-    _getMessage() {
-      return 'Add or remove one character';
-    }
-  }
-  // 3. Create field that applies the validator and store the node reference
-  const fieldElement = renderLitAsNode(html`
-    <lion-input
-      name="interactionField"
-      label="Only an odd amount of characters allowed"
-      help-text="Change feedback condition"
-      .modelValue="${'notodd'}"
-      .validators="${[new OddValidator()]}"
-    ></lion-input>
-  `);
-
-  // 4. When checkboxes change, set the feedbackCondition method to a new method that checks
-  // whether every condition that is checked, is true on the field. Otherwise, don't show the feedback.
-  const fetchConditionsAndReevaluate = ({ currentTarget: { modelValue } }) => {
-    fieldElement._showFeedbackConditionFor = type => {
-      return modelValue.every(condition => fieldElement[condition]);
-    };
-    fieldElement.validate();
-  };
-
-  return html`
-    <lion-form>
-      <form>
-        ${fieldElement}
-        <button>Submit</button>
-      </form>
-    </lion-form>
-    <h-output .field="${fieldElement}" .show="${[...props, 'hasFeedbackFor']}"> </h-output>
-    <h3>Set conditions for validation feedback visibility</h3>
-    <lion-checkbox-group name="props[]" @model-value-changed="${fetchConditionsAndReevaluate}">
-      ${props.map(p => html` <lion-checkbox .label="${p}" .choiceValue="${p}"> </lion-checkbox> `)}
-    </lion-checkbox-group>
-  `;
-};
-```
-
-### Changing the feedback show condition (Application Developers)
-
-In some situations, the default condition for showing feedback messages might not apply.
-The conditions as described in 'When is feedback shown to the user' can be overidden via
-the `feedbackCondition` method.
-In this example, we want to implement the following situation:
-
-- for an `input-date`, we have a MinDate condition
-- we want to send feedback as soon as we know the user intentionally typed a full Date
-  (we know if modelValue is not Unparseable)
-
-```js preview-story
-export const feedbackVisibility = () => html`
-  <lion-input-date
-    .validators="${[
-      new Required(),
-      new MinDate(new Date('2000/10/10'), {
-        getMessage: () => `You provided a correctly formatted date, but it's below MinData`,
-      }),
-    ]}"
-    .feedbackCondition="${(type, meta, originalCondition) => {
-      if (meta.modelValue && !(meta.modelValue instanceof Unparseable)) {
-        return true;
-      }
-      return originalCondition(type, meta);
-    }}"
-    help-text="Error appears as soon as a Parseable date before 10/10/2000 is typed"
-    label="Custom feedback visibility"
-  ></lion-input-date>
-`;
-```
-
-## Resetting
-
-In some situations, resetting the interaction state might be desired, e.g., to clear an entire form or a single input field from errors.
-
-In those cases, using the `resetInteractionState` on a field or a form resets its respective interaction state without resetting the modelValue.

package/docs/fundamentals/systems/form/model-value.md

@@ -1,57 +0,0 @@
----
-parts:
-  - ModelValue
-  - Form
-  - Systems
-title: 'ModelValue'
-eleventyNavigation:
-  key: Systems >> Form >> ModelValue
-  title: ModelValue
-  order: 20
-  parent: Systems >> Form
----
-
-# ModelValue
-
-The modelValue or model can be considered as the ‘aorta’ of our form system.
-It is the single source of truth; not only for the current state
-of the form, also for all derived states: interaction, validation, visibility and other states are
-computed from a modelValue change.
-
-## Single source of truth
-
-ModelValues are designed to provide the Application Developer a single way of programmatical
-interaction with the form for an Application Developer.
-
-### One single concept for Application Developers
-
-Application Developers need to only care about interacting with the modelValue on a form control
-level, via:
-
-- `.modelValue`
-- `@model-value-changed`
-
-> Internal/private concepts like viewValue, formattedValue, serializedValue are therefore not
-> recommended as a means of interaction.
-
-For more information about parsing and the Unparseable type, see [Formatting and Parsing](https://github.com/ing-bank/lion/blob/9575386e5fb419f7dbd3b893be4c4ce7925bcb2e/docs/fundamentals/systems/form/formatting-and-parsing.md)
-
-### Event meta
-
-`model-value-changed` events have a `detail` object, containing the following meta data:
-
-- `isTriggeredByUser`: a boolean that determines whether a change originated
-  from a user or was triggered programmatically
-- `formPath`: an array of FormControls. It contains the path an event follows to go from a 'leaf
-  element' (for instance a lion-input) to a top element (for instance lion-form). An example path
-  could be [lionForm, lionFieldset, lionInput]
-- `initialize`: whether this is the first time the event is fired (on first render of the FormControl)
-
-### Resetting
-
-Resetting a form can be done by two different methods.
-
-- `resetGroup()`: resets every form field to its initial/prefilled value and interaction state
-- `clearGroup()`: clears every form field, disregarding its initial/prefilled value and interaction state
-
-Both methods do so by calling `reset|resetGroup` or `clear|clearGroup` on each `LionField` found in the form.