@lion/ui 0.24.0 → 0.26.0

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

@@ -1,212 +0,0 @@
----
-parts:
-  - How To
-  - Create a custom field
-title: 'Create a custom field'
-eleventyNavigation:
-  key: 'How To: Create a custom field'
-  order: 20
-  parent: How To
-  title: Create a custom field
----
-
-# Create a custom field
-
-```js script
-import { html, css, LitElement } from '@mdjs/mdjs-preview';
-import { LionField } from '@lion/ui/form-core.js';
-import '@lion/ui/define/lion-field.js';
-import '@lion/ui/define/lion-validation-feedback.js';
-
-import '../../fundamentals/systems/form/assets/h-output.js';
-
-// A) the custom [slot=input] or 'HTMLElementWithValue'
-class DummySlider extends LitElement {
-  // A1) it should have a .value property of type 'string'
-  static properties = { value: String, reflect: true };
-
-  static styles = [
-    css`
-      :host {
-        display: block;
-        padding-top: 16px;
-        padding-bottom: 16px;
-      }
-
-      [part='rail'] {
-        position: relative;
-        display: block;
-        background: #eee;
-        height: 8px;
-        border-radius: 8px;
-      }
-
-      [part='thumb'] {
-        position: absolute;
-        display: flex;
-        align-items: center;
-        justify-content: center;
-        font-size: 10px;
-        background: black;
-        color: white;
-        border-radius: 50%;
-        height: 24px;
-        width: 24px;
-        top: 50%;
-        transform: translateY(-50%) translateX(-50%);
-        transition: left 0.5s ease 0s;
-      }
-    `,
-  ];
-
-  constructor() {
-    super();
-    this.value = '0';
-    this.addEventListener('click', ev => {
-      this.value = `${Math.round(
-        ((ev.clientX - this.getClientRects()[0].x) / this.offsetWidth) * 5,
-      )}`;
-      // A2) it should have a way to tell LionField its value changed
-      this.dispatchEvent(new Event('dummy-slider-changed', { bubbles: true }));
-    });
-  }
-
-  connectedCallback() {
-    super.connectedCallback();
-    this.setAttribute('tabindex', 0);
-  }
-
-  render() {
-    return html` <div part="rail">
-      <span part="thumb" style="left:${Number(this.value) * 20}%;">${this.value}</span>
-    </div>`;
-  }
-}
-if (!customElements.get('dummy-slider')) {
-  customElements.define('dummy-slider', DummySlider);
-}
-```
-
-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/bc7530702f41df90a4ca3059cfb9edb08e27f742/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/bc7530702f41df90a4ca3059cfb9edb08e27f742/docs/guides/how-to/extend-a-native-input.md).
-
-## A) an interaction element
-
-An interaction element (.\_inputNode) provides the means for the end user to enter a certain value,
-just like native elements provide in this (think of input, textarea and select).
-An example of a non native element is the [slider design pattern](https://www.w3.org/TR/wai-aria-practices-1.1/#slider) described here.
-
-For this tutorial, we create a dummy component 'dummy-slider' that exposes its value via
-property `.value` and sends an event `dummy-slider-changed` on every value change.
-To make it focusable, it has a tabindex=“0” applied.
-
-```js preview-story
-export const createAnInteractiveElement = () => {
-  // A) the custom [slot=input] or 'HTMLElementWithValue'
-  class DummySlider extends LitElement {
-    // A1) it should have a .value property of type 'string'
-    static properties = { value: String };
-
-    constructor() {
-      super();
-      this.value = 0;
-      this.addEventListener('click', ev => {
-        this.value = `${Math.round(
-          ((ev.clientX - this.getClientRects()[0].x) / this.offsetWidth) * 5,
-        )}`;
-        // A2) it should have a way to tell LionField its value changed
-        this.dispatchEvent(new Event('dummy-slider-changed', { bubbles: true }));
-      });
-    }
-
-    connectedCallback() {
-      super.connectedCallback();
-      this.setAttribute('tabindex', 0);
-    }
-
-    render() {
-      return html` <div part="rail">
-        <span part="thumb" style="left:${Number(this.value) * 20}%;">${this.value}</span>
-      </div>`;
-    }
-  }
-  return html`<dummy-slider></dummy-slider>`;
-};
-```
-
-## 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/bc7530702f41df90a4ca3059cfb9edb08e27f742/docs/components/input/overview.md).
-We start by creating a component `<slider-field>` that extends from `LionField`.
-Then we follow the steps below:
-
-- **Add your interaction element**
-
-  Here you return the element the user interacts with. By configuring it as a slot, it will end up in
-  light DOM, ensuring the best accessibility for the end user.
-
-- **Connect modelValue**
-
-  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/bc7530702f41df90a4ca3059cfb9edb08e27f742/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.
-
-> N.B. Make sure you never override other property getters than the one mentioned in this tutorial,
-> because those properties will lose 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/bc7530702f41df90a4ca3059cfb9edb08e27f742/docs/fundamentals/systems/form/formatting-and-parsing.md)
-
-Implement with the following code:
-
-```js preview-story
-export const createAField = () => {
-  // B) your extension with all the Field goodness...
-  class SliderField extends LionField {
-    // B1) Add your interaction element as ‘input slot'
-    get slots() {
-      return {
-        ...super.slots,
-        input: () => document.createElement('dummy-slider'),
-      };
-    }
-
-    // B2) Connect modelValue
-    constructor() {
-      super();
-      this.addEventListener('dummy-slider-changed', ev => {
-        ev.stopPropagation();
-        this.dispatchEvent(new Event('user-input-changed'));
-      });
-    }
-
-    get value() {
-      // Remember we should always return type 'string' here
-      return this._inputNode.value;
-    }
-
-    set value(newV) {
-      this._inputNode.value = newV;
-    }
-  }
-  customElements.define('slider-field', SliderField);
-
-  return html`<slider-field
-      label="SliderField"
-      help-text="Press to see how modelValue is synchronized"
-    ></slider-field>
-    <h-output .show="${['modelValue', 'touched', 'dirty', 'focused']}"></h-output>`;
-};
-```
-
-That was all!
-Now that your .modelValue is connected your component is fully compatible with our form system
-
-> Is your `.modelValue` still undefined? Please make sure your `.value` is of type 'string'.
-
-Now you can enhance your slider by writing custom Validators for it or by
-writing a parser to get a custom modelValue type.

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

@@ -1,101 +0,0 @@
----
-parts:
-  - How To
-  - Create a form
-title: 'Create a form'
-eleventyNavigation:
-  key: 'How To: Create a form'
-  order: 15
-  parent: How To
-  title: Create a form
----
-
-# Create a form
-
-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 by rendering into Light DOM. The form 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.
-
-> Today, rendering to light dom is the only way to [stay accessible](https://github.com/ing-bank/lion/blob/bc7530702f41df90a4ca3059cfb9edb08e27f742/docs/fundamentals/rationales/accessibility.md#shadow-roots-and-accessibility).
-
-### Example of a component that renders into Light DOM
-
-Rendering into Light DOM 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>
-    `;
-  }
-}
-```
-
-## 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/bc7530702f41df90a4ca3059cfb9edb08e27f742/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/bc7530702f41df90a4ca3059cfb9edb08e27f742/docs/guides/how-to/create-a-custom-field.md)
-  - follow [extend a native input](https://github.com/ing-bank/lion/blob/bc7530702f41df90a4ca3059cfb9edb08e27f742/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

@@ -1,78 +0,0 @@
----
-parts:
-  - How To
-  - Extend a native input
-title: 'Extend a native input'
-eleventyNavigation:
-  key: 'How To: Extend a native input'
-  order: 20
-  parent: How To
-  title: Extend a native input
----
-
-# Extend a native input
-
-```js script
-import { html } from '@mdjs/mdjs-preview';
-import { LionInput } from '@lion/ui/input.js';
-import { LionInputDate } from '@lion/ui/input-date.js';
-import { loadDefaultFeedbackMessages } from '@lion/ui/validate-messages.js';
-import '@lion/ui/define/lion-input.js';
-import '../../fundamentals/systems/form/assets/h-output.js';
-
-loadDefaultFeedbackMessages();
-```
-
-Input fields can be created by extending [LionInput](https://github.com/ing-bank/lion/blob/bc7530702f41df90a4ca3059cfb9edb08e27f742/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/bc7530702f41df90a4ca3059cfb9edb08e27f742/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:
-
-```js preview-story
-export const extendLionInput = () => {
-  class LionInputDatetime extends LionInput {
-    constructor() {
-      super();
-      this.type = 'datetime-local';
-    }
-  }
-  customElements.define('lion-input-datetime', LionInputDatetime);
-
-  return html`<lion-input-datetime label="With Date string"></lion-input-datetime>
-    <h-output .show="${['modelValue', 'touched', 'dirty', 'focused']}"></h-output>`;
-};
-```
-
-However, we might want to have a more advanced modelValue. In the example above, our modelValue is
-a serialized datetime string.
-If we want our modelValue to be of type Date, we should do the following:
-
-```js preview-story
-export const extendLionInputDate = () => {
-  function toIsoDatetime(d) {
-    return d && new Date(d.getTime() - d.getTimezoneOffset() * 60000).toISOString().split('.')[0];
-  }
-  function fromIsoDatetime(value) {
-    return new Date(value);
-  }
-
-  class LionInputDatetimeWithObject extends LionInputDate {
-    constructor() {
-      super();
-      this.type = 'datetime-local';
-      this.parser = fromIsoDatetime;
-      this.deserializer = fromIsoDatetime;
-      this.serializer = toIsoDatetime;
-      this.formatter = toIsoDatetime;
-    }
-  }
-  customElements.define('lion-input-datetime-with-object', LionInputDatetimeWithObject);
-
-  return html`<lion-input-datetime-with-object
-      label="With Date object"
-    ></lion-input-datetime-with-object>
-    <h-output .show="${['modelValue', 'touched', 'dirty', 'focused']}"></h-output>`;
-};
-```

package/docs/guides/how-to/get-started.md

@@ -1,116 +0,0 @@
----
-parts:
-  - How To
-  - Get Started
-title: 'Get Started'
-eleventyNavigation:
-  key: 'How To: Get Started'
-  order: 10
-  parent: How To
-  title: Get Started
----
-
-# Get Started
-
-## Technologies Used
-
-Lion Web Components aims to be future proof and use well-supported proven technology. The stack we have chosen should reflect this.
-
-Checkout the documentation of our main stack.
-
-- [lit](https://lit.dev/) - Building on top of the Web Components standards, Lit adds just what you need to be happy and productive: reactivity, declarative templates and a handful of thoughtful features to reduce boilerplate and make your job easier.
-- [modern-web](https://modern-web.dev) - Guides, tools and libraries for modern web development.
-- [open-wc](https://open-wc.org) - Open Web Components provides guides, tools and libraries for developing web components.
-
-## How to get started
-
-Make sure you have `npm`, if you don't have it yet: [get npm](https://www.npmjs.com/get-npm).
-
-And create a repo, we suggest to use [the generator from open-wc](https://open-wc.org/docs/development/generator/):
-
-```bash
-npm init @open-wc
-```
-
-### Install lion packages
-
-To get started with consuming lion's UI components install package `@lion/ui` as follows:
-
-```bash
-npm i @lion/ui
-```
-
-You can install lion's ajax package with:
-
-```bash
-npm i @lion/ajax
-```
-
-You can install lion's singleton-manager package with:
-
-```bash
-npm i --save singleton-manager
-```
-
-### Extend a Web Component
-
-**This is the main use case for lion**. To import component classes, and extend them for your own design system's components.
-
-```js
-import { css } from 'lit';
-import { LionInput } from '@lion/ui/input.js';
-
-class MyInput extends LionInput {
-  static get styles() {
-    return [
-      ...super.styles,
-      css`
-        /* your styles here */
-      `,
-    ];
-  }
-}
-customElements.define('my-input', MyInput);
-```
-
-### Use a JavaScript system
-
-There's a couple of "systems" in lion which have a JavaScript API. Examples are `localize`, `overlays`, `ajax`, etc.
-
-```html
-<script type="module">
-  import { ajax } from '@lion/ajax';
-
-  ajax
-    .fetch('data.json')
-    .then(response => response.json())
-    .then(data => {
-      // do something with the data
-    });
-</script>
-```
-
-### Use a Web Component
-
-You can also use the lion elements directly, although this is likely not a common use case.
-
-```html
-<script type="module">
-  import '@lion/ui/define/lion-input.js';
-</script>
-
-<lion-input name="firstName" label="First name"></lion-input>
-```
-
-### Code Completion for VS Code
-
-The @lion/ui package includes a file named vscode.html-custom-data.json that allows you to define custom elements to be recognized by Visual Studio Code. This enables code completion for @lion/ui components. To activate this feature, follow these steps after having installed `@lion/ui`:
-
-1. Navigate to the root of your project
-2. Add the following to root level of object in file `.vscode/settings.json` (create file if it doesn't exist):
-
-```json
-  "html.customData": ["./node_modules/@lion/ui/vscode.html-custom-data.json"]
-```
-
-3. Restart your Visual Studio Code for the changes to take effect.

package/docs/guides/how-to/index.md

@@ -1,25 +0,0 @@
----
-parts:
-  - How To
-title: How To
-eleventyNavigation:
-  key: How To
-  order: 20
-  title: How To
----
-
-# How To
-
-Welcome to the How To section. Here you'll find practical, step-by-step guides for common tasks when working with Lion Web Components.
-
-Whether you're just getting started with Lion, building your first form, extending existing components, or creating custom fields, this section provides clear instructions and best practices to help you succeed. Each guide is designed to walk you through the process with real-world examples and code samples.
-
-**Browse the guides below to:**
-
-- Set up your development environment and get started with Lion
-- Learn how to create accessible and well-structured forms
-- Discover how to extend native input components
-- Build custom form fields tailored to your needs
-- Follow proven patterns and best practices used by the Lion community
-
-If you can't find what you're looking for, check out our [Fundamentals](../../fundamentals/) section for deeper conceptual knowledge, or visit our [Components](https://github.com/ing-bank/lion/blob/bc7530702f41df90a4ca3059cfb9edb08e27f742/docs/components) documentation for detailed API references.

package/docs/guides/index.md

@@ -1,44 +0,0 @@
----
-parts:
-  - Guides
-title: Guides
-eleventyNavigation:
-  key: Guides
-  order: 30
-  title: Guides
----
-
-# Guides
-
-Lion is a set of white label Web Components that can be extended to your own styled layer of components.
-
-We know from experience that making high quality, accessible UI components is hard and time consuming: it takes many iterations, a lot of development time and a lot of testing to get a generic component that works in every context, supports many edge cases and is accessible in all relevant screen readers.
-
-Lion aims to do the heavy lifting for you. This means you only have to apply your own Design System: by delivering styles, configuring components and adding a minimal set of custom logic on top.
-
-## Consuming Developer
-
-Developers consuming our web components inside an application (not extending them).
-`Application Developers` are only allowed to interact with `public` properties and methods.
-Can be abbreviated as `AD`. Sometimes also called `Consuming Developer`.
-
-- [Definitions and Terms](https://github.com/ing-bank/lion/blob/bc7530702f41df90a4ca3059cfb9edb08e27f742/docs/guides/principles/definitions-and-terms.md)
-- [Styling](https://github.com/ing-bank/lion/blob/bc7530702f41df90a4ca3059cfb9edb08e27f742/docs/guides/principles/styling.md)
-- [Scoped Elements](https://github.com/ing-bank/lion/blob/bc7530702f41df90a4ca3059cfb9edb08e27f742/docs/guides/principles/scoped-elements.md)
-
-## Extending Developer
-
-Developers extending our web components, for instance: `class MaterialInput extends LionInput` are called `subclassers`. Subclassers have access to protected methods (prefixed with an underscore or marked as protected), but not to private methods.
-
-Especially for subclassers we have some extra documentation:
-
-- [Subclasser APIs](https://github.com/ing-bank/lion/blob/bc7530702f41df90a4ca3059cfb9edb08e27f742/docs/guides/principles/subclasser-apis.md)
-- [Extend documentation](https://github.com/ing-bank/lion/blob/bc7530702f41df90a4ca3059cfb9edb08e27f742/docs/blog/extending-documentation.md)
-
-## How To
-
-Next to that we have some specific "How To" documentations.
-
-- [Get started](https://github.com/ing-bank/lion/blob/bc7530702f41df90a4ca3059cfb9edb08e27f742/docs/guides/how-to/get-started.md)
-- [Create a custom field](https://github.com/ing-bank/lion/blob/bc7530702f41df90a4ca3059cfb9edb08e27f742/docs/guides/how-to/create-a-custom-field.md)
-- [Extend a native input](https://github.com/ing-bank/lion/blob/bc7530702f41df90a4ca3059cfb9edb08e27f742/docs/guides/how-to/extend-a-native-input.md)

package/docs/guides/principles/definitions-and-terms.md

@@ -1,53 +0,0 @@
----
-parts:
-  - Principles
-  - Definitions and Terms
-title: 'Definitions and Terms'
-eleventyNavigation:
-  key: 'Principles: Definitions and Terms'
-  order: 20
-  parent: Principles
-  title: Definitions and Terms
----
-
-# Definitions and Terms
-
-Below you will find a list of definitions and terms that will be used throughout our code
-documentation.
-
-## Public
-
-Methods and properties are public when they are not prefixed by an underscore.
-They can be used by Application Developers.
-
-```js
-class SoccerPlayer {
-  kickBall() {
-    // Soccer player can kick a ball
-  }
-}
-```
-
-## Protected
-
-Methods and properties are protected when they contain one underscore or are explicitly marked as protected in the code. They can be used by Subclassers.
-
-```js
-class SoccerPlayer {
-  _catchBall() {
-    // Soccer player usually does not need to catch a ball (with their hands)
-  }
-}
-```
-
-## Private
-
-Methods and properties are private when they contain two underscores or are explicitly marked as private in the code. They can be only used within the class where they are defined (developers of Lion components).
-
-```js
-class SoccerPlayer {
-  __score() {
-    // internally save how many goals have been made
-  }
-}
-```

package/docs/guides/principles/index.md

@@ -1,36 +0,0 @@
----
-parts:
-  - Principles
-title: Principles
-eleventyNavigation:
-  key: Principles
-  order: 10
-  title: Principles
----
-
-# Principles
-
-Lion is a set of white label Web Components that can be extended to your own styled layer of components.
-
-We know from experience that making high quality, accessible UI components is hard and time consuming: it takes many iterations, a lot of development time and a lot of testing to get a generic component that works in every context, supports many edge cases and is accessible in all relevant screen readers.
-
-Lion aims to do the heavy lifting for you. This means you only have to apply your own Design System: by delivering styles, configuring components and adding a minimal set of custom logic on top.
-
-## Consuming Developer
-
-Developers consuming our web components inside an application (not extending them).
-`Application Developers` are only allowed to interact with `public` properties and methods.
-Can be abbreviated as `AD`. Sometimes also called `Consuming Developer`.
-
-- [Definitions and Terms](https://github.com/ing-bank/lion/blob/bc7530702f41df90a4ca3059cfb9edb08e27f742/docs/guides/principles/definitions-and-terms.md)
-- [Styling](https://github.com/ing-bank/lion/blob/bc7530702f41df90a4ca3059cfb9edb08e27f742/docs/guides/principles/styling.md)
-- [Scoped Elements](https://github.com/ing-bank/lion/blob/bc7530702f41df90a4ca3059cfb9edb08e27f742/docs/guides/principles/scoped-elements.md)
-
-## Extending Developer
-
-Developers extending our web components, for instance: `class MaterialInput extends LionInput` are called `subclassers`. Subclassers have access to protected methods (prefixed with an underscore or marked as protected), but not to private methods.
-
-Especially for subclassers we have some extra documentation:
-
-- [Subclasser APIs](https://github.com/ing-bank/lion/blob/bc7530702f41df90a4ca3059cfb9edb08e27f742/docs/guides/principles/subclasser-apis.md)
-- [Extend documentation](https://github.com/ing-bank/lion/blob/bc7530702f41df90a4ca3059cfb9edb08e27f742/docs/blog/extending-documentation.md)