@lion/ui 0.0.2 → 0.0.4

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

@@ -0,0 +1,245 @@
+# Systems >> Form >> Formatting and Parsing ||21
+
+```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/edc6920a90aa7658358819e7c324daf6badf7d30/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/edc6920a90aa7658358819e7c324daf6badf7d30/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/edc6920a90aa7658358819e7c324daf6badf7d30/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/edc6920a90aa7658358819e7c324daf6badf7d30/docs/fundamentals/systems/form/assets/FormatMixinDiagram-3.svg 'Imperative flow')

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

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

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

@@ -0,0 +1,177 @@
+# Systems >> Form >> Interaction States ||22
+
+```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>
+`;
+```

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

@@ -0,0 +1,35 @@
+# Systems >> Form >> ModelValue ||20
+
+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/edc6920a90aa7658358819e7c324daf6badf7d30/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)

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

@@ -0,0 +1,82 @@
+# Systems >> Form >> Overview ||10
+
+This page should be used as a starting point when first using the Form System.
+It provides an overview of its essential building blocks and provides links to detailed explanations of most of its core concepts.
+
+## Building Blocks
+
+Our Form System is built from a set of very fundamental building blocks: `form control`s, `field`s and `fieldset`s.
+
+### Form Controls
+
+`Form control`s are the most fundamental building blocks of our Form System.
+They are the fundament of both `field`s, and `fieldset`s and provide a normalized, predictable API throughout the whole form. Every form element inherits from `FormControlMixin`.
+
+`FormControlMixin` creates the default html structure and accessibility is designed to be used in conjunction with the ValidateMixin and the FormatMixin.
+
+## Fields
+
+Fields (think of an input, textarea, select) are the actual form controls the end user interacts with. They extend `LionField`, which in turn uses the `FormControlMixin`. Fields provide a normalized API for both platform components and custom made form controls.
+
+On top of this, they feature:
+
+- [formatting/parsing/serializing](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/fundamentals/systems/form/formatting-and-parsing.md) of view values.
+- Advanced [validation](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/fundamentals/systems/form/validate.md) possibilities.
+- Creation of advanced user interaction scenarios via [interaction states](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/fundamentals/systems/form/interaction-states.md).
+- Provision of labels and help texts in an easy, declarative manner.
+- Accessibility out of the box.
+- Advanced styling possibilities: map your own Design System to the internal HTML structure.
+  `Form control`s are the most fundamental building block of the Forms. They are the basis of
+  both `field`s and `fieldset`s, and the `form` itself.
+
+### Platform fields (wrappers)
+
+- [LionInput](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/components/input/overview.md), a wrapper for `<input>`.
+- [LionTextarea](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/components/textarea/overview.md), a wrapper for `<textarea>`.
+- [LionSelect](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/components/select/overview.md), a wrapper for `<select>`.
+
+### Custom fields (wrappers)
+
+Whenever a native form control doesn't exist or is not sufficient, a [custom form field](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/guides/how-to/create-a-custom-field.md) should be created. One could think of components like:
+
+- [LionCombobox](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/components/combobox/overview.md), a custom implementation of a combobox.
+- [LionDate](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/components/input-date/overview.md), an alternative for `<input type="date">`.
+- [LionDatepicker](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/components/input-datepicker/overview.md), an alternative for `<input type="date">` including a calendar dropdown.
+- [LionListbox](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/components/listbox/overview.md), a custom implementation of a listbox.
+- [LionInputAmount](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/components/input-amount/overview.md), an alternative for `<input type="number">` special for amounts.
+- [LionInputEmail](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/components/input-email/overview.md), an alternative for `<input type="email">`.
+- [LionInputIban](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/components/input-iban/overview.md), an ING specific for an input with IBAN numbers.
+- [LionInputRange](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/components/input-range/overview.md), an alternative for `<input type="range">`.
+- [LionInputStepper](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/components/input-stepper/overview.md), an alternative for `<input type="number">`.
+- [LionSelectRich](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/components/select-rich/overview.md), an alternative for `<select>` with multiline options.
+
+### Choice Input Fields
+
+For form controls which return a `checked-state` you can use the `lion-choice-input` mixin. It is used in:
+
+- [LionCheckbox](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/components/checkbox-group/overview.md), a wrapper for `<input type="checkbox">`.
+- LionOption, an alternative for `<option>`.
+- [LionRadio](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/components/radio-group/overview.md), a wrapper for `<input type="radio">`.
+- [LionSwitch](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/components/switch/overview.md), a custom implementation of a switch.
+
+Which contains the following features:
+
+- Get or set the value of the choice - `choiceValue()`.
+- Get or set the modelValue (value and checked-state) of the choice - `.modelValue`.
+- Pre-select an option by setting the `checked` boolean attribute.
+
+## Fieldsets
+
+Fieldsets are groups of fields. They can be considered fields on their own as well, since they partly share the normalized API via `FormControlMixin`. Fieldsets are the basis for:
+
+- [LionFieldset](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/components/fieldset/overview.md), a wrapper around multiple input fields or other fieldsets.
+- [LionForm](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/components/form/overview.md), enhances the functionality of the native `<form>` component.
+- [LionCheckboxGroup](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/components/checkbox-group/overview.md), a wrapper component for multiple checkboxes.
+- [LionRadioGroup](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/components/radio-group/overview.md), a wrapper component for multiple radio inputs.
+
+## Other Resources
+
+- [Model Value](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/fundamentals/systems/form/model-value.md)
+- [Formatting and parsing](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/fundamentals/systems/form/formatting-and-parsing.md)
+- [Interaction states](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/fundamentals/systems/form/interaction-states.md)
+- [Validation System](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/fundamentals/systems/form/validate.md)

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

@@ -0,0 +1,101 @@
+# Systems >> Form >> Styling ||40
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-input.js';
+import '@lion/ui/define/lion-button.js';
+```
+
+## Label
+
+Can 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 (partially) visually hidden.
+A label is always needed for accessibility reasons.
+
+```js preview-story
+export const label = () => html`
+  <style>
+    .u-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;
+    }
+  </style>
+  <lion-input>
+    <label slot="label"
+      >Label <span class="u-sr-only">partially only visible for screen-readers</span></label
+    >
+  </lion-input>
+`;
+```
+
+## Prefix
+
+The prefix is used for addons to the input like a minus button in the `input-stepper`.
+
+```js preview-story
+export const prefix = () => html`
+  <lion-input label="Prefix">
+    <div slot="prefix">[prefix]</div>
+  </lion-input>
+`;
+```
+
+## Suffix
+
+The 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.
+
+```js preview-story
+export const suffix = () => html`
+  <lion-input label="Suffix">
+    <div slot="suffix">[suffix]</div>
+  </lion-input>
+`;
+```
+
+## Before
+
+> Before slot does not have an active use case yet.
+
+```js preview-story
+export const before = () => html`
+  <lion-input label="Before">
+    <div slot="before">[before]</div>
+  </lion-input>
+`;
+```
+
+## After
+
+```js preview-story
+export const after = () => html`
+  <lion-input label="Amount">
+    <div slot="after">EUR</div>
+  </lion-input>
+  <lion-input label="Percentage">
+    <div slot="after">%</div>
+  </lion-input>
+`;
+```
+
+### Examples
+
+Due to our custom inputs being Web Components, it is possible to put HTML content inside an input. For example if you want to add a button as a prefix or suffix.
+
+```js preview-story
+export const ButtonsWithFields = () => html`
+  <lion-input label="Prefix and suffix">
+    <lion-button slot="prefix">prefix</lion-button>
+    <lion-button slot="suffix">suffix</lion-button>
+  </lion-input>
+`;
+```