@lion/ui 0.2.2 → 0.3.1

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

@@ -16,9 +16,9 @@ export const main = () => {
 
 ## Features
 
-- Based on our [input](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/input/overview.md)
+- Based on our [input](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/input/overview.md)
 - Default label in different languages
-- Makes use of IBAN specific [validate](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/form/validate.md) with corresponding error messages in different languages
+- Makes use of IBAN specific [validate](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/systems/form/validate.md) with corresponding error messages in different languages
   - IsIBAN (default)
   - IsCountryIBAN
 - Parses IBANs automatically

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

@@ -15,11 +15,11 @@ export const main = () => html`
 
 ## Features
 
-- Based on our [input](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/input/overview.md).
+- Based on our [input](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/input/overview.md).
 - Shows `modelValue` and `unit` above the range input.
 - Shows `min` and `max` value after the range input.
 - Can hide the `min` and `max` value via `no-min-max-labels`.
-- Makes use of [formatNumber](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/localize/numbers.md) for formatting and parsing.
+- Makes use of [formatNumber](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/systems/localize/numbers.md) for formatting and parsing.
 
 ## Installation
 

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

@@ -18,7 +18,7 @@ export const main = () => html`
 
 ## Features
 
-- Based on our [input](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/input/overview.md).
+- Based on our [input](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/input/overview.md).
 - Set `min` and `max` value to define the range.
 - Set `step` value in integer or decimal to increase and decrease the value.
 - Use `ArrowUp` or `ArrowDown` to update the value.

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

@@ -39,7 +39,7 @@ export const main = () => {
 
 ## Features
 
-- Extends our [input](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/input/overview.md)
+- Extends our [input](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/input/overview.md)
 - Shows a mobile telephone keypad on mobile (by having a native `<input inputmode="tel">` inside)
 - Can be configured with a list of allowed region codes
 - Will be preconfigured with region derived from locale

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

@@ -22,7 +22,7 @@ Say we have the following telephone number from Madrid, Spain: `+34919930432`.
 It contains a [country code](https://en.wikipedia.org/wiki/Country_code) (34), an [area code](https://en.wikipedia.org/wiki/Telephone_numbering_plan#Area_code) (91) and a [dial code](https://en.wikipedia.org/wiki/Mobile_dial_code) (+34 91).
 Input Tel interprets phone numbers based on their [region code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2): a two character long region representation('ES' in the telephone number above).
 
-The table below lists all possible regions worldwide. When [allowed regions](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/input-tel/#allowed-regions) are not configured,
+The table below lists all possible regions worldwide. When [allowed regions](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/input-tel/#allowed-regions) are not configured,
 all of them will be supported as values of Input Tel.
 
 ```js story
@@ -37,11 +37,11 @@ export const regionCodesTable = () => {
 The active region (accessible via readonly accessor `.activeRegion`) determines how validation and formatting
 should be applied. It is dependent on the following factors:
 
-- [allowed regions](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/input-tel/#allowed-regions): a list that determines what is allowed to become .activeRegion. If
-  [.allowedRegions has only one entry](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/input-tel/#restrict-to-one-region), .activeRegion will always be this value.
+- [allowed regions](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/input-tel/#allowed-regions): a list that determines what is allowed to become .activeRegion. If
+  [.allowedRegions has only one entry](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/input-tel/#restrict-to-one-region), .activeRegion will always be this value.
 - the modelValue or viewValue: once it contains sufficient info to derive its region code (and
-  the derived code is inside [allowed regions](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/input-tel/#allowed-regions) if configured)
-- active locale (and the derived locale is inside [allowed regions](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/input-tel/#allowed-regions) if configured)
+  the derived code is inside [allowed regions](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/input-tel/#allowed-regions) if configured)
+- active locale (and the derived locale is inside [allowed regions](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/input-tel/#allowed-regions) if configured)
 
 What follows from the list above is that .activeRegion can change dynamically, after a value
 change in the text box by the user (or when locales or allowed regions would be changed by the
@@ -130,7 +130,7 @@ export const heuristic = () => {
 Once it is configured, validation and formatting will be restricted to those
 values that are present in this list.
 
-> Note that for [InputTelDropdown](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/input-tel-dropdown/index.md), only allowed regions will
+> Note that for [InputTelDropdown](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/input-tel-dropdown/index.md), only allowed regions will
 > be shown in the dropdown list.
 
 ```js preview-story

package/docs/components/input-tel-dropdown/{examples.md → extensions.md}

@@ -1,4 +1,4 @@
-# Input Tel Dropdown >> Examples ||30
+# Input Tel Dropdown >> Extensions ||30
 
 ```js script
 import { html } from '@mdjs/mdjs-preview';

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

@@ -19,7 +19,7 @@ export const main = () => {
 
 ## Features
 
-- Extends our [input-tel](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/input-tel/overview.md)
+- Extends our [input-tel](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/input-tel/overview.md)
 - Shows dropdown list with all possible regions
 - Shows only allowed regions in dropdown list when .allowedRegions is configured
 - Highlights regions on top of dropdown list when .preferredRegions is configured

package/docs/components/radio-group/overview.md

@@ -20,12 +20,12 @@ export const main = () => html`
 `;
 ```
 
-- Make sure that to use a name attribute as it is necessary for our [form](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/form/overview.md)'s serialization result.
-- If you have many options for a user to pick from, consider using our [select](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/select/overview.md) instead.
+- Make sure that to use a name attribute as it is necessary for our [form](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/form/overview.md)'s serialization result.
+- If you have many options for a user to pick from, consider using our [select](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/select/overview.md) instead.
 
 ## Features
 
-Since it extends from our [fieldset](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/fieldset/overview.md), it has all the features a fieldset has.
+Since it extends from our [fieldset](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/fieldset/overview.md), it has all the features a fieldset has.
 
 - Get or set the checked value of the group:
   - modelValue (default) - `checkedValue()`

package/docs/components/select-rich/use-cases.md

@@ -302,7 +302,7 @@ LionSelectRich will give it acces to:
 - LionSelectRich itself, via `.hostElement`
 
 Code of an advanced custom invoker is shown below (this is the code for the
-invoker used in [IntlSelectRich](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/select-rich/examples.md)).
+invoker used in [IntlSelectRich](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/select-rich/examples.md)).
 The invoker is usually added in the invoker slot of the LionSelectRich subclass.
 However, it would also be possible for an application developer to provide the invoker
 by putting it in light dom:

package/docs/components/tabs/examples.md

@@ -9,7 +9,7 @@ import './src/lea-tab-panel.js';
 
 ## Lea Tabs
 
-Learn how to create the `lea tabs` in our ["introducing lion" blogpost](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/blog/ing-open-sources-lion.md).
+Learn how to create the `lea tabs` in our ["introducing lion" blogpost](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/blog/ing-open-sources-lion.md).
 
 ```js preview-story
 export const main = () => html`

package/docs/fundamentals/index.md

@@ -9,11 +9,11 @@ Here you find more details about what we offer.
 
 Let's see what each section describes.
 
-1. [Systems](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/core/overview.md) <br>
+1. [Systems](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/systems/core/overview.md) <br>
    These are the fundamental systems that power all of our components.
-2. [Tools](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/tools/helpers/overview.md) <br>
+2. [Tools](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/tools/helpers/overview.md) <br>
    Frontend Tools useful for web development but are not visual and therefore are not components.
-3. [Node Tools](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/node-tools/babel-plugin-extend-docs/overview.md) <br>
+3. [Node Tools](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/node-tools/babel-plugin-extend-docs/overview.md) <br>
    Node tools to analyse the code and for extending the documentation.
-4. [Rationales](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/rationales/side-effects.md) <br>
+4. [Rationales](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/rationales/side-effects.md) <br>
    The reasoning behind some of our decisions.

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

@@ -45,7 +45,7 @@ export default {
 ### referenceCollections
 
 A list of file system paths. They can be defined relative from the current project root or they can be full paths.
-When a [MatchAnalyzer](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/node-tools/providence-analytics/analyzer.md) like `match-imports` or `match-subclasses` is used, the default reference(s) can be configured here. For instance: ['/path/to/@lion/ui/form.js']
+When a [MatchAnalyzer](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/node-tools/providence-analytics/analyzer.md) like `match-imports` or `match-subclasses` is used, the default reference(s) can be configured here. For instance: ['/path/to/@lion/ui/form.js']
 
 An example:
 

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

@@ -108,4 +108,4 @@ QueryOutput structure could be simplified in the future.
 
 The output files stored in the file system always need to be machine independent:
 this means that all machine specific information, like a complete filepath, needs to be removed from a QueryOutput (paths relative from project root are still allowed).
-In that way, the caching mechanism (based on hash comparisons) as described in [Analyzer](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/node-tools/providence-analytics/analyzer.md) is guaranteed to work across different machines.
+In that way, the caching mechanism (based on hash comparisons) as described in [Analyzer](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/node-tools/providence-analytics/analyzer.md) is guaranteed to work across different machines.

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

@@ -7,7 +7,7 @@ A few examples are:
 - find-exports
 - match-imports
 
-An analyzer will give back a [QueryResult](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/node-tools/providence-analytics/QueryResult.md) that will be written to the file system by Providence.
+An analyzer will give back a [QueryResult](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/node-tools/providence-analytics/QueryResult.md) that will be written to the file system by Providence.
 All analyzers need to extend from the `Analyzer` base class, found in `src/program/analyzers/helpers`.
 
 ## Public api

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

@@ -1,6 +1,6 @@
 # Node Tools >> Providence Analytics >> Dashboard ||30
 
-An interactive overview of all aggregated [QueryResults](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/node-tools/providence-analytics/QueryResult.md) can be found in the dashboard.
+An interactive overview of all aggregated [QueryResults](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/node-tools/providence-analytics/QueryResult.md) can be found in the dashboard.
 The dashboard is a small nodejs server (based on es-dev-server + middleware) and a frontend
 application.
 

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/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/node-tools/providence-analytics/assets/provicli.gif 'CLI')
+![CLI](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/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/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/node-tools/providence-analytics/assets/providash.gif 'dashboard')
+![dashboard](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/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/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/node-tools/providence-analytics/assets/analyzer-query.gif 'Analyzer query')
+![Analyzer query](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/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/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/docs/deep/dir/overview.md)
+   [=> See Source <=](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/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/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/docs/deep/dir/overview.md)
+[=> See Source <=](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/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/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/docs/deep/dir/use-cases.md)
+[=> See Source <=](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/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/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/node-tools/remark-extend/overview.md)
+- Import lion documentation and adjust it using [remark-extend](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/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/ede8412cbca3f6dd025797336745330f31706ad3/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/a19e02c443e21d4e6c62bb08bbe6db64f7446010/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/a19e02c443e21d4e6c62bb08bbe6db64f7446010/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/a19e02c443e21d4e6c62bb08bbe6db64f7446010/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/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/core/#deduping-of-mixins)
+- [function to deduplicate mixins (dedupeMixin)](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/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/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/input-amount/overview.md).
+> For an actual amount input, check out [lion-input-amount](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/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/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/form/assets/FormatMixinDiagram-1.svg 'Standard flow')
+![Standard flow](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/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/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/form/assets/FormatMixinDiagram-2.svg 'Unparseable flow')
+![Unparseable flow](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/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/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/form/assets/FormatMixinDiagram-3.svg 'Imperative flow')
+![Imperative flow](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/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/ede8412cbca3f6dd025797336745330f31706ad3/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/a19e02c443e21d4e6c62bb08bbe6db64f7446010/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/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/form/formatting-and-parsing.md) of view values.
-- Advanced [validation](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/form/validate.md) possibilities.
-- Creation of advanced user interaction scenarios via [interaction states](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/form/interaction-states.md).
+- [formatting/parsing/serializing](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/systems/form/formatting-and-parsing.md) of view values.
+- Advanced [validation](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/systems/form/validate.md) possibilities.
+- Creation of advanced user interaction scenarios via [interaction states](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/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/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/input/overview.md), a wrapper for `<input>`.
-- [LionTextarea](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/textarea/overview.md), a wrapper for `<textarea>`.
-- [LionSelect](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/select/overview.md), a wrapper for `<select>`.
+- [LionInput](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/input/overview.md), a wrapper for `<input>`.
+- [LionTextarea](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/textarea/overview.md), a wrapper for `<textarea>`.
+- [LionSelect](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/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/ede8412cbca3f6dd025797336745330f31706ad3/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/a19e02c443e21d4e6c62bb08bbe6db64f7446010/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/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/combobox/overview.md), a custom implementation of a combobox.
-- [LionDate](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/input-date/overview.md), an alternative for `<input type="date">`.
-- [LionDatepicker](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/input-datepicker/overview.md), an alternative for `<input type="date">` including a calendar dropdown.
-- [LionListbox](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/listbox/overview.md), a custom implementation of a listbox.
-- [LionInputAmount](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/input-amount/overview.md), an alternative for `<input type="number">` special for amounts.
-- [LionInputEmail](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/input-email/overview.md), an alternative for `<input type="email">`.
-- [LionInputIban](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/input-iban/overview.md), an ING specific for an input with IBAN numbers.
-- [LionInputRange](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/input-range/overview.md), an alternative for `<input type="range">`.
-- [LionInputStepper](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/input-stepper/overview.md), an alternative for `<input type="number">`.
-- [LionSelectRich](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/select-rich/overview.md), an alternative for `<select>` with multiline options.
+- [LionCombobox](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/combobox/overview.md), a custom implementation of a combobox.
+- [LionDate](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/input-date/overview.md), an alternative for `<input type="date">`.
+- [LionDatepicker](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/input-datepicker/overview.md), an alternative for `<input type="date">` including a calendar dropdown.
+- [LionListbox](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/listbox/overview.md), a custom implementation of a listbox.
+- [LionInputAmount](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/input-amount/overview.md), an alternative for `<input type="number">` special for amounts.
+- [LionInputEmail](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/input-email/overview.md), an alternative for `<input type="email">`.
+- [LionInputIban](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/input-iban/overview.md), an ING specific for an input with IBAN numbers.
+- [LionInputRange](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/input-range/overview.md), an alternative for `<input type="range">`.
+- [LionInputStepper](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/input-stepper/overview.md), an alternative for `<input type="number">`.
+- [LionSelectRich](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/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/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/checkbox-group/overview.md), a wrapper for `<input type="checkbox">`.
+- [LionCheckbox](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/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/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/radio-group/overview.md), a wrapper for `<input type="radio">`.
-- [LionSwitch](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/switch/overview.md), a custom implementation of a switch.
+- [LionRadio](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/radio-group/overview.md), a wrapper for `<input type="radio">`.
+- [LionSwitch](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/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/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/fieldset/overview.md), a wrapper around multiple input fields or other fieldsets.
-- [LionForm](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/form/overview.md), enhances the functionality of the native `<form>` component.
-- [LionCheckboxGroup](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/checkbox-group/overview.md), a wrapper component for multiple checkboxes.
-- [LionRadioGroup](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/radio-group/overview.md), a wrapper component for multiple radio inputs.
+- [LionFieldset](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/fieldset/overview.md), a wrapper around multiple input fields or other fieldsets.
+- [LionForm](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/form/overview.md), enhances the functionality of the native `<form>` component.
+- [LionCheckboxGroup](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/checkbox-group/overview.md), a wrapper component for multiple checkboxes.
+- [LionRadioGroup](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/radio-group/overview.md), a wrapper component for multiple radio inputs.
 
 ## Other Resources
 
-- [Model Value](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/form/model-value.md)
-- [Formatting and parsing](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/form/formatting-and-parsing.md)
-- [Interaction states](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/form/interaction-states.md)
-- [Validation System](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/form/validate.md)
+- [Model Value](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/systems/form/model-value.md)
+- [Formatting and parsing](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/systems/form/formatting-and-parsing.md)
+- [Interaction states](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/systems/form/interaction-states.md)
+- [Validation System](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/systems/form/validate.md)