@lion/ui 0.0.2 → 0.0.3

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

@@ -0,0 +1,370 @@
+# Select Rich >> Use Cases ||20
+
+```js script
+import { LitElement, html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-select-rich.js';
+import '@lion/ui/define/lion-option.js';
+```
+
+## Model value
+
+You can set the full `modelValue` for each option, which includes the checked property for whether it is checked or not.
+
+```html
+<lion-option .modelValue="${{ value: 'red', checked: false }}">Red</lion-option>
+```
+
+## Options with HTML
+
+The main feature of this rich select that makes it rich, is that your options can contain HTML.
+
+```js preview-story
+export const optionsWithHTML = () => html`
+  <lion-select-rich label="Favorite color" name="color">
+    <lion-option .choiceValue="${'red'}">
+      <p style="color: red;">I am red</p>
+      <p>and multi Line</p>
+    </lion-option>
+    <lion-option .choiceValue="${'hotpink'}" checked>
+      <p style="color: hotpink;">I am hotpink</p>
+      <p>and multi Line</p>
+    </lion-option>
+    <lion-option .choiceValue="${'teal'}">
+      <p style="color: teal;">I am teal</p>
+      <p>and multi Line</p>
+    </lion-option>
+  </lion-select-rich>
+`;
+```
+
+## Many Options with Scrolling
+
+```js preview-story
+export const manyOptionsWithScrolling = () => html`
+  <style>
+    #scrollSelectRich lion-options {
+      max-height: 200px;
+      overflow-y: auto;
+      display: block;
+    }
+  </style>
+  <lion-select-rich id="scrollSelectRich" label="Favorite color" name="color">
+    <lion-option .modelValue="${{ value: 'red', checked: false }}">
+      <p style="color: red;">I am red</p>
+    </lion-option>
+    <lion-option .modelValue="${{ value: 'hotpink', checked: true }}">
+      <p style="color: hotpink;">I am hotpink</p>
+    </lion-option>
+    <lion-option .modelValue="${{ value: 'teal', checked: false }}">
+      <p style="color: teal;">I am teal</p>
+    </lion-option>
+    <lion-option .modelValue="${{ value: 'green', checked: false }}">
+      <p style="color: green;">I am green</p>
+    </lion-option>
+    <lion-option .modelValue"=${{ value: 'blue', checked: false }}">
+      <p style="color: blue;">I am blue</p>
+    </lion-option>
+  </lion-select-rich>
+`;
+```
+
+## Read only prefilled
+
+You can set the rich select as read only.
+This will block the user from opening the select.
+
+The readonly attribute is delegated to the invoker for disabling opening the overlay, and for styling purposes.
+
+```js preview-story
+export const readOnlyPrefilled = () => html`
+  <lion-select-rich label="Read-only select" readonly name="color">
+    <lion-option .modelValue=${{ value: 'red', checked: false }}>Red</lion-option>
+    <lion-option .modelValue=${{ value: 'hotpink', checked: true }}>Hotpink</lion-option>
+    <lion-option .modelValue=${{ value: 'teal', checked: false }}>Teal</lion-option>
+  </lion-select-rich>
+`;
+```
+
+## Disabled Select
+
+You can set the `disabled` attribute to disable either specific options or the entire select.
+
+If you disable the entire select, the disabled attribute is also delegated to the invoker, similar to readonly.
+
+```js preview-story
+export const disabledSelect = () => html`
+  <lion-select-rich label="Disabled select" disabled name="color">
+    <lion-option .modelValue=${{ value: 'red', checked: false }}>Red</lion-option>
+    <lion-option .modelValue=${{ value: 'hotpink', checked: true }}>Hotpink</lion-option>
+    <lion-option .modelValue=${{ value: 'teal', checked: false }}>Teal</lion-option>
+  </lion-select-rich>
+`;
+```
+
+```js preview-story
+export const disabledOption = () => html`
+  <lion-select-rich label="Disabled options" name="color">
+    <lion-option .choiceValue=${'red'} disabled>Red</lion-option>
+    <lion-option .choiceValue=${'blue'}>Blue</lion-option>
+    <lion-option .choiceValue=${'hotpink'} disabled>Hotpink</lion-option>
+    <lion-option .choiceValue=${'green'}>Green</lion-option>
+    <lion-option .choiceValue=${'teal'} disabled>Teal</lion-option>
+  </lion-select-rich>
+`;
+```
+
+## Render options
+
+The choiceValue can also be a complex value like an Object.
+
+It is up to you how to render this Object in the DOM.
+
+```js preview-story
+export const renderOptions = ({ shadowRoot }) => {
+  const objs = [
+    { type: 'mastercard', label: 'Master Card', amount: 12000, active: true },
+    { type: 'visacard', label: 'Visa Card', amount: 0, active: false },
+  ];
+  function showOutput(ev) {
+    shadowRoot.querySelector('#demoRenderOutput').innerHTML = JSON.stringify(
+      ev.target.modelValue,
+      null,
+      2,
+    );
+  }
+  return html`
+    <lion-select-rich label="Credit Card" name="color" @model-value-changed=${showOutput}>
+      ${objs.map(
+        obj => html`
+          <lion-option .modelValue=${{ value: obj, checked: false }}>${obj.label}</lion-option>
+        `,
+      )}
+    </lion-select-rich>
+    <p>Full value:</p>
+    <pre id="demoRenderOutput"></pre>
+  `;
+};
+```
+
+## Interaction Mode
+
+You can set the interaction mode to either `mac` or `windows/linux`.
+By default, it will choose based on the user Operating System, but it can be forced.
+
+This changes the keyboard interaction.
+
+```js preview-story
+export const interactionMode = () => html`
+  <lion-select-rich label="Mac mode" name="color" interaction-mode="mac">
+    <lion-option .modelValue=${{ value: 'red', checked: false }}>Red</lion-option>
+    <lion-option .modelValue=${{ value: 'hotpink', checked: true }}>Hotpink</lion-option>
+    <lion-option .modelValue=${{ value: 'teal', checked: false }}>Teal</lion-option>
+  </lion-select-rich>
+  <lion-select-rich label="Windows/Linux mode" name="color" interaction-mode="windows/linux">
+    <lion-option .modelValue=${{ value: 'red', checked: false }}>Red</lion-option>
+    <lion-option .modelValue=${{ value: 'hotpink', checked: true }}>Hotpink</lion-option>
+    <lion-option .modelValue=${{ value: 'teal', checked: false }}>Teal</lion-option>
+  </lion-select-rich>
+`;
+```
+
+## Checked index & value
+
+You can get/set the checkedIndex and checkedValue.
+
+```js preview-story
+export const checkedIndexAndValue = ({ shadowRoot }) => html`
+  <style>
+    .log-button {
+      margin: 10px 0;
+    }
+  </style>
+  <div>
+    <label id="label-richSelectCheckedInput" for="richSelectCheckedInput">
+      Set the checkedIndex
+    </label>
+    <input
+      id="richSelectCheckedInput"
+      aria-labelledby="label-richSelectCheckedInput"
+      type="number"
+      @change=${e => {
+        const selectEl = shadowRoot.querySelector('#checkedRichSelect');
+        selectEl.checkedIndex = e.target.value;
+      }}
+    />
+  </div>
+  <button
+    class="log-button"
+    @click=${() => {
+      const selectEl = shadowRoot.querySelector('#checkedRichSelect');
+      console.log(`checkedIndex: ${selectEl.checkedIndex}`);
+      console.log(`modelValue: ${selectEl.modelValue}`);
+    }}
+  >
+    Console log checked index and value
+  </button>
+  <lion-select-rich id="checkedRichSelect" name="favoriteColor" label="Favorite color">
+    <lion-option .choiceValue=${'red'}>Red</lion-option>
+    <lion-option .choiceValue=${'hotpink'} checked>Hotpink</lion-option>
+    <lion-option .choiceValue=${'teal'}>Teal</lion-option>
+  </lion-select-rich>
+`;
+```
+
+## No default selection
+
+If you want to set a placeholder option with something like 'Please select', you can of course do this, the same way you would do it in a native select.
+
+Simply put an option with a modelValue that is `null`.
+
+```html
+<lion-option .choiceValue="${null}">select a color</lion-option>
+```
+
+However, this allows the user to explicitly select this option.
+
+Often, you may want a placeholder that appears initially, but cannot be selected explicitly by the user.
+For this you can use `has-no-default-selected` attribute.
+
+```js preview-story
+export const noDefaultSelection = () => html`
+  <lion-select-rich name="favoriteColor" label="Favorite color" has-no-default-selected>
+    <lion-option .choiceValue=${'red'}>Red</lion-option>
+    <lion-option .choiceValue=${'hotpink'}>Hotpink</lion-option>
+    <lion-option .choiceValue=${'teal'}>Teal</lion-option>
+  </lion-select-rich>
+`;
+```
+
+> By default, the placeholder is completely empty in the `LionSelectInvoker`,
+> but subclassers can easily override this in their extension, by the overriding `_noSelectionTemplate()` method.
+
+## Single Option
+
+If there is a single option rendered, then `singleOption` property is set to `true` on `lion-select-rich` and invoker as well. Invoker also gets `single-option` which can be used to having desired templating and styling. As in here the arrow is not displayed for single option
+
+```js preview-story
+export const singleOption = () => html`
+  <lion-select-rich label="Single Option" name="color">
+    <lion-option .choiceValue=${'red'}>Red</lion-option>
+  </lion-select-rich>
+`;
+```
+
+When adding/removing options the `singleOption` will only be `true` when there is exactly one option.
+
+```js preview-story
+class SingleOptionRemoveAdd extends LitElement {
+  static get properties() {
+    return {
+      options: { type: Array },
+    };
+  }
+
+  constructor() {
+    super();
+    this.options = ['Option 1', 'Option 2'];
+  }
+
+  render() {
+    return html`
+      <button @click=${this.addOption}>Add an option</button>
+      <button @click=${this.removeOption}>Remove last option</button>
+      <lion-select-rich name="favoriteColor" label="Favorite color">
+        <lion-options slot="input">
+          ${this.options.map(
+            option => html` <lion-option .choiceValue=${option}>${option}</lion-option> `,
+          )}
+        </lion-options>
+      </lion-select-rich>
+    `;
+  }
+
+  addOption() {
+    this.options.push(`Option ${this.options.length + 1} with a long title`);
+    this.options = [...this.options];
+    this.requestUpdate();
+  }
+
+  removeOption() {
+    if (this.options.length >= 2) {
+      this.options.pop();
+      this.options = [...this.options];
+      this.requestUpdate();
+    }
+  }
+}
+
+customElements.define('single-option-remove-add', SingleOptionRemoveAdd);
+
+export const singleOptionRemoveAdd = () => {
+  return html`<single-option-remove-add></single-option-remove-add>`;
+};
+```
+
+## Custom Invoker
+
+You can provide a custom invoker using the invoker slot.
+LionSelectRich will give it acces to:
+
+- the currently selected option via `.selectedElement`
+- 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/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/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:
+
+```html
+<lion-select-rich>
+  <intl-select-invoker slot="invoker"></intl-select-invoker>
+  ...
+</lion-select-rich>
+```
+
+```js
+import { LionSelectInvoker } from '@lion/ui/select-rich.js';
+
+class IntlSelectInvoker extends LionSelectInvoker {
+  /**
+   * 1. Add your own styles
+   * @configure LitElement
+   * @enhance LionSelectInvoker
+   */
+  static styles = [
+    /** <your custom styles> see IntlSelectRich listed above */
+  ];
+
+  /**
+   * 2. Take back control of slots (LionSelectInvoker adds slots you most likely don't want)
+   * @configure SlotMixin
+   * @override LionSelectInvoker
+   */
+  get slots() {
+    return {};
+  }
+
+  /**
+   * 3. Add you custom render function
+   * @override LionSelectInvoker
+   */
+  render() {
+    const ctor = /** @type {typeof LionSelectInvoker} */ (this.constructor);
+    return ctor._mainTemplate(this._templateData);
+  }
+
+  get _templateData() {
+    return {
+      data: { selectedElement: this.selectedElement, hostElement: this.hostElement },
+    };
+  }
+
+  static _mainTemplate(templateData) {
+    /** <your custom template> see IntlSelectRich listed above */
+  }
+}
+```
+
+> This example only works if your option elements don't have ShadowDOM boundaries themselves.
+> Cloning deeply only works up until the first shadow boundary.

package/docs/components/steps/index.md

@@ -0,0 +1,3 @@
+# Steps ||50
+
+-> go to Overview

package/docs/components/steps/overview.md

@@ -0,0 +1,63 @@
+# Steps >> Overview ||10
+
+A web component that can be used to break a single goal down into dependable sub-tasks.
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-steps.js';
+import '@lion/ui/define/lion-step.js';
+```
+
+```js preview-story
+export const main = () => html`
+  <lion-steps>
+    <lion-step initial-step>
+      Step 1
+      <button type="button" @click=${ev => ev.target.parentElement.controller.next()}>Next</button>
+    </lion-step>
+    <lion-step>
+      <button type="button" @click=${ev => ev.target.parentElement.controller.previous()}>
+        Previous
+      </button>
+      Step 2
+      <button type="button" @click=${ev => ev.target.parentElement.controller.next()}>
+        Next
+      </button></lion-step
+    >
+    <lion-step>
+      <button type="button" @click=${ev => ev.target.parentElement.controller.previous()}>
+        Previous
+      </button>
+      Step 3
+    </lion-step>
+  </lion-steps>
+`;
+```
+
+## Features
+
+- navigate between different steps with 'previous' and 'next' functions.
+- keeps status of each step
+  - untouched
+  - entered
+  - left
+  - skipped
+- options
+  - **initial-step**: Set to the first step of the flow, blocks calling `previous` function.
+  - **condition**: Dynamic condition, when true the step is added to the flow.
+  - **invert-condition**: Inverts the condition set.
+
+In many application you build multi-step workflows like multi-step forms where you want to split a long process into smaller steps making the user's perception of it and filling in data easier. The idea of this component is to provide a simple way to define such steps and transition from one step to another while saving data between them and to conditionally skip some steps based on the data.
+
+## Installation
+
+```bash
+npm i --save @lion/ui
+```
+
+```js
+import { LionSteps, LionStep } from '@lion/ui/steps.js';
+// or
+import '@lion/ui/define/lion-steps.js';
+import '@lion/ui/define/lion-step.js';
+```

package/docs/components/steps/use-cases.md

@@ -0,0 +1,163 @@
+# Steps >> Use Cases ||20
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-steps.js';
+import '@lion/ui/define/lion-step.js';
+```
+
+```js preview-story
+export const main = () => html`
+  <lion-steps>
+    <lion-step initial-step>
+      <p>Welcome</p>
+      <button disabled>previous</button> &nbsp;
+      <button type="button" @click=${ev => ev.target.parentElement.controller.next()}>Next</button>
+    </lion-step>
+    <lion-step>
+      <p>Are you single?</p>
+      <button
+        type="button"
+        @click=${ev => {
+          ev.target.parentElement.controller.data.isSingle = true;
+          ev.target.parentElement.controller.next();
+        }}
+      >
+        Yes
+      </button>
+      &nbsp;
+      <button
+        type="button"
+        @click=${ev => {
+          ev.target.parentElement.controller.data.isSingle = false;
+          ev.target.parentElement.controller.next();
+        }}
+      >
+        No
+      </button>
+      <br /><br />
+      <button type="button" @click=${ev => ev.target.parentElement.controller.previous()}>
+        Previous
+      </button>
+    </lion-step>
+    <lion-step id="is-single" .condition="${data => data.isSingle}">
+      <p>You are single</p>
+      <button type="button" @click=${ev => ev.target.parentElement.controller.previous()}>
+        Previous
+      </button>
+      &nbsp;
+      <button type="button" @click=${ev => ev.target.parentElement.controller.next()}>Next</button>
+    </lion-step>
+    <lion-step id="is-not-single" .condition="${data => data.isSingle}" invert-condition>
+      <p>You are NOT single.</p>
+      <button type="button" @click=${ev => ev.target.parentElement.controller.previous()}>
+        Previous
+      </button>
+      &nbsp;
+      <button type="button" @click=${ev => ev.target.parentElement.controller.next()}>Next</button>
+    </lion-step>
+    <lion-step>
+      <p>Finish</p>
+      <button type="button" @click=${ev => ev.target.parentElement.controller.previous()}>
+        Previous
+      </button>
+    </lion-step>
+  </lion-steps>
+`;
+```
+
+## Define steps
+
+We provide two components: `lion-steps` and `lion-step`. Steps need to be direct children of `lion-steps`.
+
+```html
+<lion-steps>
+  <lion-step initial-step>Step 1</lion-step>
+  <lion-step>Step 2</lion-step>
+  <lion-step>......</lion-step>
+  <lion-step>Step N</lion-step>
+</lion-steps>
+```
+
+The first step needs to be explicitly set via `initial-step` so that it get status `entered`, while others are `untouched` by default. You can navigate between steps using `next()` and `previous()` methods, so that next step gets `entered` status, while previous one becomes `left`:
+
+```js
+next() {
+  return this.shadowRoot.getElementById('steps').next();
+}
+
+previous() {
+  return this.shadowRoot.getElementById('steps').previous();
+}
+```
+
+## Conditions
+
+You can provide a condition to a step (with or without `invert-condition` emulating if-else flow):
+
+```html
+<lion-steps data="[[data]]">
+  <lion-step>...</lion-step>
+  <lion-step>step where `data.smth` is set</lion-step>
+  <lion-step condition="myConditionFunc">if</lion-step>
+  <lion-step condition="myConditionFunc" invert-condition>else</lion-step>
+  <lion-step>...</lion-step>
+</lion-steps>
+
+<script>
+  // you have `data` property defined in the scope
+  ...
+  myConditionFunc(data) {
+    return data.smth === "what-you-need";
+  }
+  ...
+</script>
+```
+
+If a condition was not met a step gets a status `skipped`.
+
+## Forward only steps
+
+If you have an intermediate step loading data via AJAX request and then automatically calling `next()`, you can flag it as `forward-only`. This will ensure that navigation to the previous step is possible and does not lead to another AJAX request which leads to next step again, breaking the flow for a user.
+
+```html
+<lion-steps>
+  <lion-step>preliminary step</lion-step>
+  <lion-step forward-only>data is loaded and next() is called automatically afterwards</lion-step>
+  <!-- user decides to go to previous step here -->
+  <lion-step>do smth with data</lion-step>
+</lion-steps>
+```
+
+## Events
+
+If you need to be notified when transition between steps occurs use the `transition` event by providing steps data:
+
+```html
+<lion-steps @transition="${onTransition}">
+  <lion-step>Step 1</lion-step>
+  <lion-step>Step 2</lion-step>
+  <lion-step>Step 3</lion-step>
+</lion-steps>
+
+<script>
+  ...
+  onTransition(event) {
+    console.log(event.detail.fromStep.number); // Number
+    console.log(event.detail.fromStep.element); // <lion-step>
+    console.log(event.detail.toStep.number); // Number
+    console.log(event.detail.toStep.element); // <lion-step>
+  }
+  ...
+</script>
+```
+
+For notifications about specific step status change you can use individual events like this:
+
+```html
+<lion-steps>
+  <lion-step @leave="${onLeave}">Step 1</lion-step>
+  <lion-step @skip="${onSkip}">Step 2</lion-step>
+  <lion-step @enter="${onEnter}">Step 3</lion-step>
+</lion-steps>
+```

package/docs/components/switch/index.md

@@ -0,0 +1,3 @@
+# Switch ||50
+
+-> go to Overview

package/docs/components/switch/overview.md

@@ -0,0 +1,75 @@
+# Switch >> Overview ||10
+
+<p class="lion-paragraph--emphasis">The Switch is used to toggle a property or feature on or off.</p>
+
+```js script
+import { html as previewHtml } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-switch.js';
+```
+
+```js preview-story
+import { html, LitElement } from 'lit';
+import { ScopedElementsMixin } from '@open-wc/scoped-elements';
+import { LionSwitch } from '@lion/ui/switch.js';
+
+class MyComponent extends ScopedElementsMixin(LitElement) {
+  static get scopedElements() {
+    return { 'lion-switch': LionSwitch };
+  }
+  render() {
+    return html`<lion-switch label="Label" help-text="Help text"></lion-switch>`;
+  }
+}
+customElements.define('my-component', MyComponent);
+
+export const main = () => previewHtml`<my-component></my-component>`;
+```
+
+## When to use
+
+- Toggling the component on or off has an immediate action (no confirmation by the user required).
+- The Switch is typically used in setting applications.
+- The Switch is not a Checkbox in disguise and can not be used as part of a form.
+
+## Features
+
+- Get or set the checked state (boolean) - `checked` boolean attribute
+- Pre-select an option by setting the `checked` boolean attribute
+- Get or set the value of the choice - `choiceValue()`
+
+## How to use
+
+### Code
+
+1. Install
+
+```bash
+npm i --save @lion/ui
+```
+
+2. Use scoped registry
+
+```js
+import { html, LitElement } from 'lit';
+import { ScopedElementsMixin } from '@open-wc/scoped-elements';
+import { LionSwitch } from '@lion/ui/switch.js';
+
+class MyComponent extends ScopedElementsMixin(LitElement) {
+  static get scopedElements() {
+    return { 'lion-switch': LionSwitch };
+  }
+  render() {
+    return html`<lion-switch></lion-switch>`;
+  }
+}
+```
+
+3. Use html
+
+```html
+<script type="module">
+  import '@lion/ui/define/lion-switch.js';
+</script>
+
+<lion-switch></lion-switch>
+```