@lion/ui 0.2.1 → 0.3.0

package/docs/fundamentals/node-tools/providence-analytics/overview.md

@@ -47,7 +47,7 @@ npm i --save-dev providence-analytics
 You are now ready to use providence in your project. All
 data will be stored in json files in the folder `./providence-output`
 
-![CLI](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/fundamentals/node-tools/providence-analytics/assets/provicli.gif 'CLI')
+![CLI](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/fundamentals/node-tools/providence-analytics/assets/provicli.gif 'CLI')
 
 ## Setup: Dashboard
 
@@ -76,7 +76,7 @@ export default {
 
 Run `npm run providence:dashboard`
 
-![dashboard](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/fundamentals/node-tools/providence-analytics/assets/providash.gif 'dashboard')
+![dashboard](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/fundamentals/node-tools/providence-analytics/assets/providash.gif 'dashboard')
 
 ## Setup: about result output
 
@@ -153,7 +153,7 @@ Now you will get a list of all predefined analyzers:
 - match-subclasses
 - etc...
 
-![Analyzer query](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/fundamentals/node-tools/providence-analytics/assets/analyzer-query.gif 'Analyzer query')
+![Analyzer query](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/fundamentals/node-tools/providence-analytics/assets/analyzer-query.gif 'Analyzer query')
 
 <!--
 ## Running providence from its own repo

package/docs/fundamentals/node-tools/publish-docs/overview.md

@@ -31,7 +31,7 @@ For a Mono Repository
    ```md
    # My Pkg
 
-   [=> See Source <=](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/fundamentals/docs/deep/dir/overview.md)
+   [=> See Source <=](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/fundamentals/docs/deep/dir/overview.md)
    ```
 
 ## CLI flags
@@ -61,7 +61,7 @@ Bring the `overview.md` in a docs folder along.
 👉 `packages/[my-package]/docs/overview.md`
 
 ```md
-[=> See Source <=](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/fundamentals/docs/deep/dir/overview.md)
+[=> See Source <=](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/fundamentals/docs/deep/dir/overview.md)
 ```
 
 Add a `use-cases.md`
@@ -69,7 +69,7 @@ Add a `use-cases.md`
 👉 `packages/[my-package]/docs/use-cases.md`
 
 ```md
-[=> See Source <=](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/fundamentals/docs/deep/dir/use-cases.md)
+[=> See Source <=](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/fundamentals/docs/deep/dir/use-cases.md)
 ```
 
 So you will end up with something like this in your package.

package/docs/fundamentals/node-tools/rocket-preset-extend-lion-docs/overview.md

@@ -7,7 +7,7 @@ To do this automatically you can use this preset for [rocket](https://rocket.mod
 
 ## Features
 
-- Import lion documentation and adjust it using [remark-extend](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/fundamentals/node-tools/remark-extend/overview.md)
+- Import lion documentation and adjust it using [remark-extend](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/fundamentals/node-tools/remark-extend/overview.md)
 - Renames named imports and all it's usage
 - Adjusts import paths
 - Replace tags in template literals
@@ -38,7 +38,7 @@ export default {
 
 ## Reusing documentation
 
-To take an existing documentation you can "import" it using [remark-extend](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/fundamentals/node-tools/remark-extend/overview.md).
+To take an existing documentation you can "import" it using [remark-extend](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/fundamentals/node-tools/remark-extend/overview.md).
 
 As an example you can create `docs/components/tabs/overview.md`.
 

package/docs/fundamentals/rationales/accessibility.md

@@ -0,0 +1,28 @@
+# Rationales >> Accessibility ||5
+
+In Lion accessibility is a first class citizen. That means accessibility is never an afterthought.
+
+Whenever we create a component, we do some thorough research first. Experience from past web component libraries learned us that when accessibility was dealt with in hindsight, a lot of concessions needed to be made. It made us want to go back to the drawing board. Lion was started with this 'fresh drawing board'.
+In general, we try to leverage out of the box accessible platform solutions as much as possible. When no platform solutions are available, we try to map our components to [aria patterns and widgets as defined by W3C](https://www.w3.org/WAI/ARIA/apg/) where possible.
+Building accessible components takes a lot of time, practice and knowledge about screen reader and browser implementations. Then, it takes many testing iterations to finetune a component.
+
+More on this topic can be found in the online panel discussion [Web Components, Design Systems and Accessibility](https://www.youtube.com/watch?v=xz8yRVJMP2k&t=1190s). The discussion also contains a [dedicated section about accessible form components](https://www.youtube.com/watch?v=xz8yRVJMP2k&t=1917s)
+
+## Shadow roots and accessibility
+
+Since our components and applications consist of multiple shadow roots that need to be able to reference each other, designing accessible components takes extra strategy and planning.
+A practical example: all form components inside a form need to be able to lay accessible relations for presenting feedback messages via the screen reader. For this, they need consistent designs so that all form components are interoperable. So, light dom needs to be leveraged until the [AOM specification](https://wicg.github.io/aom/explainer.html) is implemented.
+
+## Some details about the form system
+
+A huge part of Lion consists of its form system and components.
+
+This [presentation about accessible form components](https://github.com/home/runner/work/lion/lion/_merged_assets/_static/theoryOfFormsLion.pdf) explains how accesibility is built-in in all form components.
+
+## SlotMixin
+
+Internally, we delegate all intricacies involved in managing light dom to SlotMixin.
+SlotMixin automatically mediates between light dom provided by the user ('public slots') and light dom provided by the component author ('private slots').
+Also, SlotMixin allows to hook into the reactive update loop of LitElement (automatically rerendering on property changes) and it automatically respects
+the scoped registry belonging to the shadow root.
+More details about SlotMixin can be found in the [SlotMixin documentation](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/fundamentals/systems/core/SlotMixin.md)

package/docs/fundamentals/systems/core/SlotMixin.md

@@ -0,0 +1,148 @@
+# Systems >> Core >> SlotMixin ||20
+
+The SlotMixin is made for solving accessibility challenges that inherently come with the usage of shadow dom.
+Until [AOM](https://wicg.github.io/aom/explainer.html) is in place, it is not possible to create relations between different shadow doms.
+The need for this can occur in the following situations:
+
+- A user-defined slot. For instance:
+
+```html
+<my-input>
+  <div slot="help-text">Input description</div>
+</my-input>
+```
+
+The help text here needs to be connected to the input element that may live in shadow dom. The input needs to have `aria-describedby="help-text-id".`
+
+- An interplay of multiple nested web components. For instance:
+
+```html
+<my-fieldset>
+  <my-input><input aria-describedby="parent-msg" /></my-input>
+  <my-input><input aria-describedby="parent-msg" /></my-input>
+  <div id="parent-msg">Group errror message</div>
+</my-fieldset>
+```
+
+In the case above, all inputs need to be able to refer the error message of their parent.
+
+**In a nutshell**: SlotMixin helps you with everything related to rendering light dom (i.e. rendering to slots).
+You can build accessible ui components with ease, while delegating all edge cases to SlotMixin.
+
+Edge cases that SlotMixin solves:
+
+- **mediates** between light dom provided by the user ('public slots') and light dom provided by the component author ('private slots').
+- allows to hook into the reactive update loop of LitElement (**rerendering** on property changes)
+- respects the **scoped registry** belonging to the shadow root.
+
+## The api
+
+So, what does the api look like? SlotMixin can be used like this:
+
+```js
+class MyAccessibleControl extends SlotMixin(LitElement) {
+  get slots() {
+    return {
+      ...super.slots,
+      'public-element-slot': () => document.createElement('input'),
+      '_private-template-slot': () => html`<wc-rendered-to-light-dom></wc-rendered-to-light-dom>`,
+    };
+  }
+}
+```
+
+## SlotFunctionResults
+
+The `SlotFunctionResult` is the output of the functions provided in `get slots()`. It can output these four types, which are explained in detail below:
+
+```ts
+Element | TemplateResult | SlotRerenderObject | undefined;
+```
+
+Below configuration gives an example of all of them, after which we explain when each type should be used
+
+```js
+class MyAccessibleControl extends SlotMixin(LitElement) {
+ get slots() {
+   return {
+     ...super.slots,
+     // Element
+     'public-element-slot': () => document.createElement('input'),
+     // TemplateResult
+     '_private-template-slot': () => html`<wc-rendered-to-light-dom></wc-rendered-to-light-dom>`,
+     // SlotRerenderObject
+     'rerenderable-slot': () => {
+       return {
+         template: html`<w-c>${this.litProperty}</w-c>`,
+       }
+     },
+     // undefined (conditional slot)
+     '' => () => {
+        if (conditionApplies) {
+          return html`<div>default slot</div>`;
+        }
+        return undefined;
+      },
+   };
+ }
+}
+```
+
+### Element
+
+For simple cases, an element can be returned. Use this when no web component is needed.
+
+### TemplateResult
+
+Return a TemplateResult when you need web components in your light dom. They will be automatically scoped correctly (to the scoped registry belonging to your shadowRoot)
+If your template needs to rerender as well, use a `SlotRerenderObject`.
+
+### SlotRerenderObject
+
+A `SlotRerenderObject` looks like this:
+
+```ts
+{
+  template: TemplateResult;
+}
+```
+
+It is meant for complex templates that need rerenders and are bound to the [reactive update cycle](https://lit.dev/docs/components/lifecycle/#reactive-update-cycle). The same lifecycle hooks (for instance `updated`) can be used as with templates rendered to the shadow root (via the regular render function).
+For rerendering to work predictably (no focus and other interaction issues), the slot will be created within a wrapper div.
+
+### Undefined
+
+Whether the slot should be rendered can be dependent on a global or instance configuration.
+When `undefined` or nothing (implicitly `undefined`) is returned, SlotMixin will not render the slot
+
+```js
+if (this.conditionApplies) {
+  // Here we can return `Element | TemplateResult | SlotRerenderObject`
+  return html`<div>default slot</div>`;
+}
+return undefined;
+```
+
+## Private and public slots
+
+Some elements provide a property/attribute api with a fallback to content projection as a means to provide more advanced html.
+For instance, a simple text label is provided like this:
+
+```html
+<my-input label="My label"></my-input>
+```
+
+A more advanced label (using html that can't be provided via a string) can be provided like this:
+
+```html
+<my-input>
+  <label slot="label"><my-icon aria-hidden="true"></my-icon>My label</label>
+</my-input>
+```
+
+In the property/attribute case, SlotMixin adds the `<label slot="label">` under the hood, **unless** the developer already provided the slot.
+This will make sure that the slot provided by the user always takes precedence and only one slot instance will be available in light dom per slot.
+
+### Default slot
+
+As can be seen in the example of [SlotFunctionResults](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/fundamentals/systems/core/#slotfunctionresults), '' can be used to add content to the default slot

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

@@ -15,7 +15,7 @@ import { LitElement, html, render } from 'lit-element';
 
 ## Features
 
-- [function to deduplicate mixins (dedupeMixin)](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/fundamentals/systems/core/#deduping-of-mixins)
+- [function to deduplicate mixins (dedupeMixin)](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/fundamentals/systems/core/#deduping-of-mixins)
 - Mixin to handle disabled (DisabledMixin)
 - Mixin to handle disabled AND tabIndex (DisabledWithTabIndexMixin)
 - Mixin to manage auto-generated needed slot elements in light dom (SlotMixin)

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

@@ -23,7 +23,7 @@ Our fields can automatically format/parse/serialize user input or an input set i
 
 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/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/components/input-amount/overview.md).
+> For an actual amount input, check out [lion-input-amount](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/components/input-amount/overview.md).
 > This comes with its own formatter, parser, serializer.
 
 ### Parsers & modelValue
@@ -230,16 +230,16 @@ Below we show three flow diagrams to show the flow of formatting, serializing an
 
 Where a user changes the input with their keyboard:
 
-![Standard flow](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/fundamentals/systems/form/assets/FormatMixinDiagram-1.svg 'Standard flow')
+![Standard flow](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/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/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/fundamentals/systems/form/assets/FormatMixinDiagram-2.svg 'Unparseable flow')
+![Unparseable flow](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/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/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/fundamentals/systems/form/assets/FormatMixinDiagram-3.svg 'Imperative flow')
+![Imperative flow](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/fundamentals/systems/form/assets/FormatMixinDiagram-3.svg 'Imperative flow')

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

@@ -21,7 +21,7 @@ level, via:
 > 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/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/fundamentals/systems/form/formatting-and-parsing.md)
+For more information about parsing and the Unparseable type, see [Formatting and Parsing](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/fundamentals/systems/form/formatting-and-parsing.md)
 
 ### Event meta
 

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

@@ -20,9 +20,9 @@ Fields (think of an input, textarea, select) are the actual form controls the en
 
 On top of this, they feature:
 
-- [formatting/parsing/serializing](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/fundamentals/systems/form/formatting-and-parsing.md) of view values.
-- Advanced [validation](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/fundamentals/systems/form/validate.md) possibilities.
-- Creation of advanced user interaction scenarios via [interaction states](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/fundamentals/systems/form/interaction-states.md).
+- [formatting/parsing/serializing](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/fundamentals/systems/form/formatting-and-parsing.md) of view values.
+- Advanced [validation](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/fundamentals/systems/form/validate.md) possibilities.
+- Creation of advanced user interaction scenarios via [interaction states](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/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.
@@ -31,33 +31,33 @@ On top of this, they feature:
 
 ### Platform fields (wrappers)
 
-- [LionInput](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/components/input/overview.md), a wrapper for `<input>`.
-- [LionTextarea](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/components/textarea/overview.md), a wrapper for `<textarea>`.
-- [LionSelect](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/components/select/overview.md), a wrapper for `<select>`.
+- [LionInput](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/components/input/overview.md), a wrapper for `<input>`.
+- [LionTextarea](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/components/textarea/overview.md), a wrapper for `<textarea>`.
+- [LionSelect](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/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/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/guides/how-to/create-a-custom-field.md) should be created. One could think of components like:
+Whenever a native form control doesn't exist or is not sufficient, a [custom form field](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/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/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/components/combobox/overview.md), a custom implementation of a combobox.
-- [LionDate](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/components/input-date/overview.md), an alternative for `<input type="date">`.
-- [LionDatepicker](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/components/input-datepicker/overview.md), an alternative for `<input type="date">` including a calendar dropdown.
-- [LionListbox](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/components/listbox/overview.md), a custom implementation of a listbox.
-- [LionInputAmount](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/components/input-amount/overview.md), an alternative for `<input type="number">` special for amounts.
-- [LionInputEmail](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/components/input-email/overview.md), an alternative for `<input type="email">`.
-- [LionInputIban](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/components/input-iban/overview.md), an ING specific for an input with IBAN numbers.
-- [LionInputRange](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/components/input-range/overview.md), an alternative for `<input type="range">`.
-- [LionInputStepper](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/components/input-stepper/overview.md), an alternative for `<input type="number">`.
-- [LionSelectRich](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/components/select-rich/overview.md), an alternative for `<select>` with multiline options.
+- [LionCombobox](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/components/combobox/overview.md), a custom implementation of a combobox.
+- [LionDate](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/components/input-date/overview.md), an alternative for `<input type="date">`.
+- [LionDatepicker](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/components/input-datepicker/overview.md), an alternative for `<input type="date">` including a calendar dropdown.
+- [LionListbox](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/components/listbox/overview.md), a custom implementation of a listbox.
+- [LionInputAmount](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/components/input-amount/overview.md), an alternative for `<input type="number">` special for amounts.
+- [LionInputEmail](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/components/input-email/overview.md), an alternative for `<input type="email">`.
+- [LionInputIban](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/components/input-iban/overview.md), an ING specific for an input with IBAN numbers.
+- [LionInputRange](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/components/input-range/overview.md), an alternative for `<input type="range">`.
+- [LionInputStepper](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/components/input-stepper/overview.md), an alternative for `<input type="number">`.
+- [LionSelectRich](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/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/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/components/checkbox-group/overview.md), a wrapper for `<input type="checkbox">`.
+- [LionCheckbox](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/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/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/components/radio-group/overview.md), a wrapper for `<input type="radio">`.
-- [LionSwitch](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/components/switch/overview.md), a custom implementation of a switch.
+- [LionRadio](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/components/radio-group/overview.md), a wrapper for `<input type="radio">`.
+- [LionSwitch](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/components/switch/overview.md), a custom implementation of a switch.
 
 Which contains the following features:
 
@@ -69,14 +69,14 @@ Which contains the following features:
 
 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/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/components/fieldset/overview.md), a wrapper around multiple input fields or other fieldsets.
-- [LionForm](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/components/form/overview.md), enhances the functionality of the native `<form>` component.
-- [LionCheckboxGroup](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/components/checkbox-group/overview.md), a wrapper component for multiple checkboxes.
-- [LionRadioGroup](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/components/radio-group/overview.md), a wrapper component for multiple radio inputs.
+- [LionFieldset](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/components/fieldset/overview.md), a wrapper around multiple input fields or other fieldsets.
+- [LionForm](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/components/form/overview.md), enhances the functionality of the native `<form>` component.
+- [LionCheckboxGroup](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/components/checkbox-group/overview.md), a wrapper component for multiple checkboxes.
+- [LionRadioGroup](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/components/radio-group/overview.md), a wrapper component for multiple radio inputs.
 
 ## Other Resources
 
-- [Model Value](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/fundamentals/systems/form/model-value.md)
-- [Formatting and parsing](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/fundamentals/systems/form/formatting-and-parsing.md)
-- [Interaction states](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/fundamentals/systems/form/interaction-states.md)
-- [Validation System](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/fundamentals/systems/form/validate.md)
+- [Model Value](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/fundamentals/systems/form/model-value.md)
+- [Formatting and parsing](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/fundamentals/systems/form/formatting-and-parsing.md)
+- [Interaction states](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/fundamentals/systems/form/interaction-states.md)
+- [Validation System](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/fundamentals/systems/form/validate.md)

package/docs/fundamentals/systems/form/use-cases.md

@@ -16,6 +16,7 @@ import '@lion/ui/define/lion-input-amount.js';
 import '@lion/ui/define/lion-input-date.js';
 import '@lion/ui/define/lion-input-datepicker.js';
 import '@lion/ui/define/lion-input-email.js';
+import '@lion/ui/define/lion-input-file.js';
 import '@lion/ui/define/lion-input-tel.js';
 import '@lion/ui/define/lion-input-tel-dropdown.js';
 import '@lion/ui/define/lion-input-iban.js';
@@ -75,6 +76,7 @@ export const main = () => {
         <lion-input-amount name="money" label="Money"></lion-input-amount>
         <lion-input-iban name="iban" label="Iban"></lion-input-iban>
         <lion-input-email name="email" label="Email"></lion-input-email>
+        <lion-input-file name="file" label="File"></lion-input-file>
         <lion-input-tel name="tel" label="Telephone number"></lion-input-tel>
         <lion-checkbox-group
           label="What do you like?"

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

@@ -58,7 +58,7 @@ Validation happens on every change of `modelValue`. A change in modelValue can b
 
 ## When validation feedback will be shown
 
-Although validation happens realtime under the hood, displaying validity feedback in realtime may not always lead to the desired User Experience. Together with [interaction states](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/fundamentals/systems/form/interaction-states.md),
+Although validation happens realtime under the hood, displaying validity feedback in realtime may not always lead to the desired User Experience. Together with [interaction states](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/fundamentals/systems/form/interaction-states.md),
 validity states can determine whether a validation message should be shown along the input field.
 
 ## Assessing field validation state programmatically

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

@@ -9,15 +9,15 @@ In it's simplest form it is a function that returns the translated text for a na
 - Formatting of numbers, amounts
 - Formatting of dates
 
-Further examples and a more in depth description can be found at the [Use Cases Page](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/fundamentals/systems/localize/use-cases.md).
+Further examples and a more in depth description can be found at the [Use Cases Page](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/fundamentals/systems/localize/use-cases.md).
 
 ## Content
 
 | Feature                                  | Description                                   |
 | ---------------------------------------- | --------------------------------------------- |
-| [Translate Text](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/fundamentals/systems/localize/text.md)    | Load and translate text in multiple languages |
-| [Format Numbers](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/fundamentals/systems/localize/numbers.md) | Format numbers in multiple languages          |
-| [Format Dates](https://github.com/ing-bank/lion/blob/7b2a234c6c05397bc2e2e944c5efbdea08d09d2b/docs/fundamentals/systems/localize/dates.md)     | Format dates in multiple languages            |
+| [Translate Text](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/fundamentals/systems/localize/text.md)    | Load and translate text in multiple languages |
+| [Format Numbers](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/fundamentals/systems/localize/numbers.md) | Format numbers in multiple languages          |
+| [Format Dates](https://github.com/ing-bank/lion/blob/951de3e9b282ce8b8797f9aae890f125f96ee5ce/docs/fundamentals/systems/localize/dates.md)     | Format dates in multiple languages            |
 
 ## Installation
 

package/docs/fundamentals/systems/overlays/_configuration-positioning.md

@@ -0,0 +1,116 @@
+---
+eleventyExcludeFromCollections: true
+---
+
+# Systems >> Overlays >> Configuration >> Positioning ||40
+
+```js script
+import { html, render, LitElement } from '@mdjs/mdjs-preview';
+import { ref, createRef } from 'lit/directives/ref.js';
+import './assets/demo-el-using-overlaymixin.mjs';
+import './assets/applyDemoOverlayStyles.mjs';
+import './assets/demo-overlay-positioning.mjs';
+```
+
+Overlays can have two different placement modes: relative to their anchor element and relative to the viewport.
+Depending on screen size and viewing device, one placement mode might be suited better than the other.
+
+> Note that, the placementMode option has the values 'local' (anchor) and 'global' (viewport). These refer to their
+> legacy position in dom (global overlays were put in the body of the page). Since overlays are built with the native `<dialog>` element,
+> no content is moved around anymore, so their names are a bit less intuitive.
+
+## Relative to anchor
+
+An anchor is usually the invoker button, it can also be a non interactive reference element.
+Anchor placement uses Popper under the hood. It supports 9 positions:
+`top-start`, `top`, `top-end`, `right-start`, `right`, `right-end`, `bottom-start`, `bottom`, `bottom-end`, `left-start`,`left`,`left-end`
+
+```js story
+export const localPositioning = () => html`<demo-overlay-positioning></demo-overlay-positioning>`;
+```
+
+## Relative to viewport
+
+Viewport placement uses the flexbox layout mode, leveraging the best browser capabilities when
+the content or screen size updates.
+Supported modes:
+`center`, `top-left`, `top`, `top-right`, `right`, `bottom-right`, `bottom`, `bottom-left`, `left`
+
+```js story
+export const globalPositioning = () =>
+  html`<demo-overlay-positioning
+    placement-mode="global"
+    simulate-viewport
+  ></demo-overlay-positioning>`;
+```
+
+## placementMode
+
+The `placementMode` property determines the positioning of the `contentNode`:
+
+- next to its reference node: `local`
+- relative to the viewport: `global`
+
+### Local
+
+<!-- By default, the [`referenceNode`](./configuration-elements#referencenode) is the [invokerNode](https://github.com/home/runner/work/lion/lion/configuration-elements#invokernode). -->
+
+```js story
+export const placementLocal = () => {
+  const placementModeLocalConfig = { placementMode: 'local' };
+  return html`
+    <demo-el-using-overlaymixin .config=${placementModeLocalConfig}>
+      <button slot="invoker">Click me to open the local overlay!</button>
+      <div slot="content" class="demo-overlay">
+        Hello! You can close this notification here:
+        <button
+          class="close-button"
+          @click=${e => e.target.dispatchEvent(new Event('close-overlay', { bubbles: true }))}
+        >
+          ⨯
+        </button>
+      </div>
+    </demo-el-using-overlaymixin>
+  `;
+};
+```
+
+### Global
+
+```js story
+export const placementGlobal = () => {
+  const placementModeGlobalConfig = { placementMode: 'global' };
+  return html`
+    <demo-el-using-overlaymixin .config=${placementModeGlobalConfig}>
+      <button slot="invoker">Click me to open the global overlay!</button>
+      <div slot="content" class="demo-overlay">
+        Hello! You can close this notification here:
+        <button
+          class="close-button"
+          @click=${e => e.target.dispatchEvent(new Event('close-overlay', { bubbles: true }))}
+        >
+          ⨯
+        </button>
+      </div>
+    </demo-el-using-overlaymixin>
+  `;
+};
+```
+
+## popperConfig
+
+/** Viewport configuration. Will be used when placementMode is 'global' \*/
+viewportConfig?: ViewportConfig;
+/** Hides other overlays when multiple are opened (currently exclusive to globalOverlayController) _/
+isBlocking?: boolean;
+/\*\* Will align contentNode with referenceNode (invokerNode by default) for local overlays. Usually needed for dropdowns. 'max' will prevent contentNode from exceeding width of referenceNode, 'min' guarantees that contentNode will be at least as wide as referenceNode. 'full' will make sure that the invoker width always is the same. _/
+inheritsReferenceWidth?: 'max' | 'full' | 'min' | 'none';
+/\*_ Change the default of 9999 _/
+zIndex?: number;
+
+| Prop                   | Description                                                                                                                                                                                                                                                                                                     | Type                               |     |     |     |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | --- | --- | --- |
+| placementMode          | Determines the positioning anchor (viewport vs invokerNode/referenceNode)                                                                                                                                                                                                                                       | 'global'\|'local'                  |     |     |     |
+| viewportConfig         | Viewport positioning configuration. Will be used when placementMode is 'global'                                                                                                                                                                                                                                 | {placement: ViewportPlacement}     |     |     |     |
+| popperConfig           | Anchor positioning configuration. Will be used when placementMode is 'local'                                                                                                                                                                                                                                    |                                    |     |     |     |
+| inheritsReferenceWidth | Will align contentNode with referenceNode for local overlays. Usually needed for dropdowns. 'max' will prevent contentNode from exceeding width of referenceNode, 'min' guarantees that contentNode will be at least as wide as referenceNode. 'full' will make sure that the invoker width always is the same. | 'max' \| 'full' \| 'min' \| 'none' |     |     |     |