@lion/ui 0.2.2 → 0.3.1

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/ede8412cbca3f6dd025797336745330f31706ad3/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/a19e02c443e21d4e6c62bb08bbe6db64f7446010/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/ede8412cbca3f6dd025797336745330f31706ad3/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/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/systems/localize/use-cases.md).
 
 ## Content
 
 | Feature                                  | Description                                   |
 | ---------------------------------------- | --------------------------------------------- |
-| [Translate Text](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/localize/text.md)    | Load and translate text in multiple languages |
-| [Format Numbers](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/localize/numbers.md) | Format numbers in multiple languages          |
-| [Format Dates](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/localize/dates.md)     | Format dates in multiple languages            |
+| [Translate Text](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/systems/localize/text.md)    | Load and translate text in multiple languages |
+| [Format Numbers](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/systems/localize/numbers.md) | Format numbers in multiple languages          |
+| [Format Dates](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/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' |     |     |     |

package/docs/fundamentals/systems/overlays/_edge-cases.md

@@ -0,0 +1,145 @@
+---
+eleventyExcludeFromCollections: true
+---
+
+# Systems >> Overlays >> Edge cases ||10
+
+```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';
+```
+
+## Notorious edge cases
+
+These edge cases are not so much related to the edges of the viewport or the anchor, but more with the difficulties involved with the dom context of the overlay.
+That is:
+
+- a parent that has `overflow: hidden` applied
+- a surrounding stacking context that does not allow to paint on top
+- a transform applied to a parent
+
+Note that our overlay uses the `<dialog>` element under the hood. It paints to the [top layer](https://github.com/whatwg/html/issues/4633) when it is configured as a modal overlay (that is, it uses `.showModal()` to open the dialog.)
+
+### Overflow
+
+A positioned parent with `overflow: hidden` can cause the overlay to be invisible. This can mainly occur in non-modal overlays being absolutely
+positioned relative to their anchor.
+
+See [css-tricks: popping-hidden-overflow](https://css-tricks.com/popping-hidden-overflow/#aa-the-solution)
+
+#### Overflow: the problem
+
+```js preview-story
+export const edgeCaseOverflowProblem = () =>
+  html`
+    <div style="padding: 54px 24px 36px;">
+      <div
+        style="overflow: hidden; border: 1px black dashed; padding-top: 44px; padding-bottom: 16px;"
+      >
+        <div style="display: flex; justify-content: space-evenly; position: relative;">
+          <demo-overlay-el opened use-absolute>
+            <button slot="invoker" aria-label="local, non modal"></button>
+            <div slot="content">absolute (for&nbsp;demo)</div>
+          </demo-overlay-el>
+        </div>
+      </div>
+    </div>
+  `;
+```
+
+#### Overflow: the solution
+
+Two solutions are thinkable:
+
+- use a modal overlay
+- use the fixed positioning strategy for the non-modal overlay
+
+Our overlay system makes sure that there's always a fixed layer that pops out of the hidden parent.
+
+```js preview-story
+export const edgeCaseOverflowSolution = () =>
+  html`
+    <div style="padding: 54px 24px 36px;">
+      <div
+        style="overflow: hidden; border: 1px black dashed; padding-top: 36px; padding-bottom: 16px;"
+      >
+        <div style="display: flex; justify-content: space-evenly; position: relative;">
+          <demo-overlay-el
+            opened
+            .config="${{ placementMode: 'local', trapsKeyboardFocus: false }}"
+          >
+            <button slot="invoker" aria-label="local, non modal"></button>
+            <div slot="content">no matter</div>
+          </demo-overlay-el>
+
+          <demo-overlay-el opened .config="${{ placementMode: 'local', trapsKeyboardFocus: true }}">
+            <button slot="invoker" aria-label="local, modal"></button>
+            <div slot="content">what configuration</div>
+          </demo-overlay-el>
+
+          <demo-overlay-el
+            opened
+            .config="${{ placementMode: 'local', popperConfig: { strategy: 'absolute' } }}"
+          >
+            <button slot="invoker" aria-label="local, absolute"></button>
+            <div slot="content">...it</div>
+          </demo-overlay-el>
+
+          <demo-overlay-el
+            opened
+            .config="${{ placementMode: 'local', popperConfig: { strategy: 'fixed' } }}"
+          >
+            <button slot="invoker" aria-label="local, fixed"></button>
+            <div slot="content">just</div>
+          </demo-overlay-el>
+
+          <demo-overlay-el opened .config="${{ placementMode: 'global' }}">
+            <button slot="invoker" aria-label="global"></button>
+            <div slot="content">works</div>
+          </demo-overlay-el>
+        </div>
+      </div>
+    </div>
+  `;
+```
+
+### Stacking context
+
+When using non modal overlays, always make sure that the surrounding [stacking context](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/The_stacking_context) does not paint on top of your overlay.  
+The example below shows the difference between a modal and non-modal overlay placed in a stacking context with a lower priority than its parent/sibling contexts.
+
+#### Stacking context: the problem
+
+```js preview-story
+export const edgeCaseStackProblem = () =>
+  html`
+    <div style="width: 300px; height: 300px; position: relative;">
+      <div
+        id="stacking-context-a"
+        style="position: absolute; z-index: 2; top: 0; width: 100px; height: 200px;"
+      >
+        I am on top and I don't care about your 9999
+      </div>
+
+      <div
+        id="stacking-context-b"
+        style="position: absolute; z-index: 1; top: 0; width: 200px; height: 200px;"
+      >
+        <demo-overlay-el no-dialog-el style="overflow:hidden; position: relative;">
+          <button slot="invoker">invoke</button>
+          <div slot="content">
+            The overlay can never be in front, since the parent stacking context has a lower
+            priority than its sibling.
+            <div id="stacking-context-b-inner" style="position: absolute; z-index: 9999;">
+              So, even if we add a new stacking context in our overlay with z-index 9999, it will
+              never be painted on top.
+            </div>
+          </div>
+        </demo-overlay-el>
+      </div>
+    </div>
+  `;
+```

package/docs/fundamentals/systems/overlays/configuration.md

@@ -68,7 +68,7 @@ export const placementGlobal = () => {
 
 ## isTooltip (placementMode: 'local')
 
-As specified in the [overlay rationale](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/overlays/rationale.md) there are only two official types of overlays: dialogs and tooltips. And their main differences are:
+As specified in the [overlay rationale](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/systems/overlays/rationale.md) there are only two official types of overlays: dialogs and tooltips. And their main differences are:
 
 - Dialogs have a modal option, tooltips don’t
 - Dialogs have interactive content, tooltips don’t
@@ -373,7 +373,7 @@ Features:
 
 > Popper strictly is scoped on positioning. **It does not change the dimensions of the content node nor the invoker node**.
 > This also means that if you use the arrow feature, you are in charge of styling it properly, use the data-popper-placement attribute for this.
-> An example implementation can be found in [lion-tooltip](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/tooltip/overview.md), where an arrow is set by default.
+> An example implementation can be found in [lion-tooltip](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/tooltip/overview.md), where an arrow is set by default.
 
 To override the default options we set for local mode, you add a `popperConfig` object to the config passed to the OverlayController.
 Here's a succinct overview of some often used popper properties:

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

@@ -6,7 +6,7 @@ Manages their position on the screen relative to other elements, including other
 
 Its purpose is to make it easy to use our Overlay System declaratively. It can be easily extended where needed, to override event listeners and more.
 
-See [lion-dialog](../../../components/dialog/overview.md) and [lion-tooltip](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/tooltip/overview.md) for example Web Component implementations using the Overlay System.
+See [lion-dialog](../../../components/dialog/overview.md) and [lion-tooltip](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/tooltip/overview.md) for example Web Component implementations using the Overlay System.
 
 ## Features
 
@@ -18,9 +18,9 @@ See [lion-dialog](../../../components/dialog/overview.md) and [lion-tooltip](htt
 - lion-overlay web component:
   - Show content when clicking the invoker
   - Have a `.config` object to set or update the OverlayController's configuration
-- [**OverlaysManager**](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/overlays/use-cases.md#overlaysmanager), a global repository keeping track of all different types of overlays
-- [**OverlayController**](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/overlays/use-cases.md#overlaycontroller), a single controller class for handling overlays
-- [**OverlayMixin**](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/overlays/use-cases.md#overlaymixin), a mixin that can be used to create webcomponents that use the OverlayController under the hood
+- [**OverlaysManager**](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/systems/overlays/use-cases.md#overlaysmanager), a global repository keeping track of all different types of overlays
+- [**OverlayController**](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/systems/overlays/use-cases.md#overlaycontroller), a single controller class for handling overlays
+- [**OverlayMixin**](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/systems/overlays/use-cases.md#overlaymixin), a mixin that can be used to create webcomponents that use the OverlayController under the hood
 
 Usually you will use `lion-dialog` (or `lion-tooltip` if this makes more sense).
 
@@ -110,4 +110,4 @@ class MyOverlayComponent extends OverlayMixin(LitElement) {
 
 ## Rationales
 
-Please check the [system rationals](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/overlays/rationale.md) folder, where we go more in-depth.
+Please check the [system rationals](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/systems/overlays/rationale.md) folder, where we go more in-depth.

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

@@ -21,7 +21,7 @@ The overlay system allows to create different types of overlays like dialogs, to
 It's designed to be highly flexible, while still delivering sensible defaults.
 On top of this, the system was built having accessibility in mind.
 
-For a detailed rationale, please consult [Rationale](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/overlays/rationale.md).
+For a detailed rationale, please consult [Rationale](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/systems/overlays/rationale.md).
 
 ```js preview-story
 export const main = () => html`
@@ -67,7 +67,7 @@ Global refers to overlays where the content is positioned in a global root node
 
 Overlays can be configured in many ways to suit your needs. We go in-depth into each option in the Overlay System - Configuration chapter.
 
-We also export a few [preset configuration objects](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/overlays/configuration.md).
+We also export a few [preset configuration objects](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/systems/overlays/configuration.md).
 
 - withModalDialogConfig
 - withDropdownConfig

package/docs/fundamentals/tools/helpers/overview.md

@@ -9,7 +9,7 @@ Therefore, they may not have the same quality standards as our other packages.
 
 | Package                                | Description             |
 | -------------------------------------- | ----------------------- |
-| [sb-action-logger](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/tools/helpers/action-logger.md) | Storybook action logger |
+| [sb-action-logger](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/tools/helpers/action-logger.md) | Storybook action logger |
 
 ## Installation
 

package/docs/fundamentals/tools/singleton-manager/example-complex/index.md

@@ -0,0 +1,21 @@
+# Tools >> Singleton Manager >> Example Complex ||40
+
+In this SPA (Single Page Application) demo you will be able to reproduce the solution.
+
+The outcome is the same but this time internally there are two instances of Overlay Managers.
+And both are kept in sync buy an mediator with which the user actually interacts.
+
+1. Click on Page A
+2. Click on `block`
+3. Click on Page B
+4. Click on `unblock` => state is unblocked globally as there is only a single instance
+
+With this solutions users can not break the app anymore.
+
+<demo-app>Loading App...</demo-app>
+
+<div id="overlay-target" style="margin-top: 50px;"></div>
+
+```js script
+import './demo-app.js';
+```

package/docs/fundamentals/tools/singleton-manager/example-fail/index.md

@@ -0,0 +1,19 @@
+# Tools >> Singleton Manager >> Example Fail ||20
+
+In this SPA (Single Page Application) demo you will be able to reproduce the issue.
+
+1. Click on Page A
+2. Click on `block`
+3. Click on Page B
+4. Click on `unblock` => nothing happens
+5. Click on `block` => both overlays are now blocked
+
+In an real application this would now mean that your users can no longer interact with your application.
+
+<demo-app>Loading App...</demo-app>
+
+<div id="overlay-target" style="margin-top: 50px;"></div>
+
+```js script
+import './demo-app.js';
+```

package/docs/fundamentals/tools/singleton-manager/example-success/index.md

@@ -0,0 +1,18 @@
+# Tools >> Singleton Manager >> Example Success ||30
+
+In this SPA (Single Page Application) demo you will be able to reproduce the solution.
+
+1. Click on Page A
+2. Click on `block`
+3. Click on Page B
+4. Click on `unblock` => state is unblocked globally as there is only a single instance
+
+With this solutions users can not break the app anymore.
+
+<demo-app>Loading App...</demo-app>
+
+<div id="overlay-target" style="margin-top: 50px;"></div>
+
+```js script
+import './demo-app.js';
+```

package/docs/fundamentals/tools/singleton-manager/overview.md

@@ -9,7 +9,7 @@ Primarily useful if two major version of a package with a singleton is used.
 npm i --save singleton-manager
 ```
 
-⚠️ You need to make SURE that only ONE version of `singleton-manager` is installed. For how see [Non Goals](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/tools/singleton-manager/#non-goals).
+⚠️ You need to make SURE that only ONE version of `singleton-manager` is installed. For how see [Non Goals](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/tools/singleton-manager/#non-goals).
 
 ### Example Singleton Users
 
@@ -159,7 +159,7 @@ Steps to reproduce:
 1. Page A click on block
 2. Page B => "Blocked: false" (even when hitting the refresh button)
 
-➡️ See [it on the example page](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/tools/singleton-manager/example-fail/index.md). <br>
+➡️ See [it on the example page](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/tools/singleton-manager/example-fail/index.md). <br>
 ➡️ See [the code](https://github.com/ing-bank/lion/tree/master/docs/fundamentals/tools/singleton-manager/example-fail/demo-app.js).
 
 ---
@@ -202,7 +202,7 @@ See it in action
 npm run start:singleton
 ```
 
-➡️ See [it on the example page](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/tools/singleton-manager/example-success/index.md). <br>
+➡️ See [it on the example page](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/tools/singleton-manager/example-success/index.md). <br>
 ➡️ See [the code](https://github.com/ing-bank/lion/tree/master/docs/fundamentals/tools/singleton-manager/example-success/demo-app.js).
 
 ---
@@ -243,7 +243,7 @@ See it in action
 npm run start:singleton-complex
 ```
 
-➡️ See [it on the example page](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/tools/singleton-manager/example-complex/index.md). <br>
+➡️ See [it on the example page](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/tools/singleton-manager/example-complex/index.md). <br>
 ➡️ See [the code](https://github.com/ing-bank/lion/tree/master/docs/fundamentals/tools/singleton-manager/example-complex/demo-app.js).
 
 ---

package/docs/guides/how-to/create-a-custom-field.md

@@ -75,9 +75,9 @@ if (!customElements.get('dummy-slider')) {
 }
 ```
 
-Custom Fields can be created in just a few steps. All you need is an interaction element (like for instance a slider, a listbox or a combobox) and connect it to the [LionField](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/input/overview.md).
+Custom Fields can be created in just a few steps. All you need is an interaction element (like for instance a slider, a listbox or a combobox) and connect it to the [LionField](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/input/overview.md).
 
-> In case you want to extend a native element, follow [Extend a native Input](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/guides/how-to/extend-a-native-input.md).
+> In case you want to extend a native element, follow [Extend a native Input](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/guides/how-to/extend-a-native-input.md).
 
 ## A) an interaction element
 
@@ -126,7 +126,7 @@ export const createAnInteractiveElement = () => {
 ## B) your LionField extension
 
 Now we want to integrate the slider in our form system to enrich the user interface, get
-validation support and all other [benefits of LionField](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/input/overview.md).
+validation support and all other [benefits of LionField](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/input/overview.md).
 We start by creating a component `<slider-field>` that extends from `LionField`.
 Then we follow the steps below:
 
@@ -139,7 +139,7 @@ Then we follow the steps below:
 
   The `user-input-changed` event is listened to by the FormatMixin: it should be regarded as the
   equivalent of the `input` event of the platform, but for custom built interaction elements.
-  You now synchronized [modelValue](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/form/model-value.md), which can be regarded as
+  You now synchronized [modelValue](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/systems/form/model-value.md), which can be regarded as
   the glue to integrate all other functionality like parsing/formatting/serializing, validating,
   tracking interaction states etc.
 
@@ -147,7 +147,7 @@ Then we follow the steps below:
 > because those properties will loose their reactivity (they won't be considered anymore in the
 > update loop of LitElement).
 > Whenever a .modelValue/.formattedValue/.serializedValue needs to be computed, use
-> [parser/formatter/serializer](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/fundamentals/systems/form/formatting-and-parsing.md)
+> [parser/formatter/serializer](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/systems/form/formatting-and-parsing.md)
 
 Implement with the following code:
 

package/docs/guides/how-to/create-a-form.md

@@ -0,0 +1,88 @@
+# How To >> Create a form ||15
+
+Creating your own forms as an Application Developer is really simple. Only two rules need to be followed.
+
+This guide is written for Application Developers that work with a fully styled and configured extension of Lion.
+Say for instance we have a 'Wolf' extension layer with a set of styled/configured Lion form components:
+
+- wolf-form
+- wolf-fieldset
+- wolf-input
+- wolf-textarea
+- ...and all other form components
+
+## Two simple rules
+
+When building a form, keep these things in mind:
+
+- avoid shadow roots inside your form
+- do not extend form components
+
+## Avoiding shadow roots
+
+Large or complex forms might need to be split up into multiple files. This composition could be achieved via:
+
+- shared templates
+- (web) components
+
+In the latter case: make sure that your components don't have a shadow root.
+This can be achieved in LitElement by providing the host as render root:
+
+```js
+class MySubForm extends LitElement {
+  // This will make sure the component does not have a shadow root
+  createRenderRoot() {
+    return this;
+  }
+
+  render() {
+    return html`
+      <wolf-fieldset name="my-fieldset">
+        <wolf-input name="my-input"></wolf-input>
+        <wolf-texarea name="my-texarea"></wolf-texarea>
+      </wolf-fieldset>
+    `;
+  }
+}
+customElements.define('my-sub-form', MySubForm);
+```
+
+Our component can be used in our form like this:
+
+```js
+class MyForm extends LitElement {
+  render() {
+    return html`
+      <wolf-form>
+        <form>
+          <my-sub-form></my-sub-form>
+        </form>
+      </wolf-form>
+    `;
+  }
+}
+```
+
+> Today, rendering to light dom is the only way to [stay accessible](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/fundamentals/rationales/accessibility.md#shadow-roots-and-accessibility).
+
+The registration mechanism relies on light dom by design: as soon as you do start to use shadow roots, you will notice that your form components won't register themselves anymore to their parents.
+
+## Extending form components
+
+Extending form components is not recommended for Application Developers: it should be left to the team that creates a Design System (Subclassers).
+This team will add the styling and default configuration needed to make it fit the particular Design System.
+
+With the toolbox provided by the team that creates your Design System, you should be able to build all your forms. Only if you have a really good reason, look into
+[exceptional cases](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/guides/how-to/#exceptional-cases) below.
+
+### Exceptional cases
+
+If the form component you need is still missing, you have two options:
+
+- is it a generic primitive that should be part of Lion? Request it in [Lion discussions](https://github.com/ing-bank/lion/discussions)
+- is it a non generic component that is unique to your app?
+  - follow [create a custom field](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/guides/how-to/create-a-custom-field.md)
+  - follow [extend a native input](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/guides/how-to/extend-a-native-input.md)
+
+It's also possible to extend other components, like LionListbox or LionCombobox. You need to be aware that you're building on top of protected apis.
+Changing/overriding functionality is only recommended if the source code in `form-core` is fully understood.

package/docs/guides/how-to/extend-a-native-input.md

@@ -11,9 +11,9 @@ import '../../fundamentals/systems/form/assets/h-output.js';
 loadDefaultFeedbackMessages();
 ```
 
-Input fields can be created by extending [LionInput](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/components/input/overview.md).
+Input fields can be created by extending [LionInput](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/components/input/overview.md).
 
-> In case you want to wrap a custom form element, follow [Create a custom Field](https://github.com/ing-bank/lion/blob/ede8412cbca3f6dd025797336745330f31706ad3/docs/guides/how-to/create-a-custom-field.md).
+> In case you want to wrap a custom form element, follow [Create a custom Field](https://github.com/ing-bank/lion/blob/a19e02c443e21d4e6c62bb08bbe6db64f7446010/docs/guides/how-to/create-a-custom-field.md).
 
 For this tutorial, we create an input that wraps native `input[type=datetime-local]`.
 This is as simple as adding a type: