@lion/ui 0.0.1 → 0.0.3

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

@@ -0,0 +1,377 @@
+# Combobox >> Use Cases ||20
+
+A combobox is a widget made up of the combination of two distinct elements:
+
+- a single-line textbox
+- an associated listbox overlay
+
+Based on the combobox configuration and entered textbox value, options in the listbox will be
+filtered, checked, focused and the textbox value may be autocompleted.
+Optionally the combobox contains a graphical button adjacent to the textbox, indicating the
+availability of the popup.
+
+> Fore more information, consult [Combobox wai-aria design pattern](https://www.w3.org/TR/wai-aria-practices/#combobox)
+
+```js script
+import { LitElement, html, repeat } from '@mdjs/mdjs-preview';
+import { listboxData } from '../listbox/src/listboxData.js';
+import { LionCombobox } from '@lion/ui/combobox.js';
+import '@lion/ui/define/lion-combobox.js';
+import '@lion/ui/define/lion-option.js';
+import './src/demo-selection-display.js';
+import { lazyRender } from './src/lazyRender.js';
+import levenshtein from './src/levenshtein.js';
+```
+
+## Autocomplete
+
+Below you will find an overview of all possible `autocomplete` behaviors and how they correspond
+to the configurable values `none`, `list`, `inline` and `both`.
+
+|        | list | filter | focus | check | complete |
+| -----: | :--: | :----: | :---: | :---: | :------: |
+|   none |  ✓   |        |       |       |          |
+|   list |  ✓   |   ✓    |   ✓   |   ✓   |          |
+| inline |  ✓   |        |   ✓   |   ✓   |    ✓     |
+|   both |  ✓   |   ✓    |   ✓   |   ✓   |    ✓     |
+
+- **list** shows a list on keydown character press
+- **filter** filters list of potential matches according to `matchmode` or provided `matchCondition`
+- **focus** automatically focuses closest match (makes it the activedescendant)
+- **check** automatically checks/selects closest match when `selection-follows-focus` is enabled (this is the default configuration)
+- **complete** completes the textbox value inline (the 'missing characters' will be added as selected text)
+
+When `autocomplete="none"` is configured, the suggested options in the overlay are not filtered
+based on the characters typed in the textbox.
+Selection will happen manually by the user.
+
+```js preview-story
+export const autocompleteNone = () => html`
+  <lion-combobox name="combo" label="Autocomplete 'none'" autocomplete="none">
+    ${lazyRender(
+      listboxData.map(entry => html` <lion-option .choiceValue="${entry}">${entry}</lion-option> `),
+    )}
+  </lion-combobox>
+`;
+```
+
+When `autocomplete="list"` is configured, it will filter listbox suggestions based on textbox value.
+
+```js preview-story
+export const autocompleteList = () => html`
+  <lion-combobox name="combo" label="Autocomplete 'list'" autocomplete="list">
+    ${lazyRender(
+      listboxData.map(entry => html` <lion-option .choiceValue="${entry}">${entry}</lion-option> `),
+    )}
+  </lion-combobox>
+`;
+```
+
+When `autocomplete="inline"` is configured, it will present a value completion prediction inside the text input itself.
+It does NOT filter list of potential matches.
+
+```js preview-story
+export const autocompleteInline = () => html`
+  <lion-combobox name="combo" label="Autocomplete 'inline'" autocomplete="inline">
+    ${lazyRender(
+      listboxData.map(entry => html` <lion-option .choiceValue="${entry}">${entry}</lion-option> `),
+    )}
+  </lion-combobox>
+`;
+```
+
+When `autocomplete="both"` is configured, it combines the filtered list from `'list'` with the text input value completion prediction from `'inline'`.
+This is the default value for `autocomplete`.
+
+```js preview-story
+export const autocompleteBoth = () => html`
+  <lion-combobox name="combo" label="Autocomplete 'both'" autocomplete="both">
+    ${lazyRender(
+      listboxData.map(entry => html` <lion-option .choiceValue="${entry}">${entry}</lion-option> `),
+    )}
+  </lion-combobox>
+`;
+```
+
+## Match Mode
+
+When `match-mode="begin"` is applied, the entered text in the textbox only filters
+options whose values begin with the entered text. For instance, the entered text 'ch' will match
+with value 'Chard', but not with 'Artichoke'.
+By default `match-mode="all"` is applied. This will also match parts of a word.
+So 'ch' will both match 'Chard' and 'Artichoke'.
+
+```js preview-story
+export const matchModeBegin = () => html`
+  <lion-combobox name="combo" label="Match Mode 'begin'" match-mode="begin">
+    ${lazyRender(
+      listboxData.map(entry => html` <lion-option .choiceValue="${entry}">${entry}</lion-option> `),
+    )}
+  </lion-combobox>
+`;
+```
+
+```js preview-story
+export const matchModeAll = () => html`
+  <lion-combobox name="combo" label="Match Mode 'all'" match-mode="all">
+    ${lazyRender(
+      listboxData.map(entry => html` <lion-option .choiceValue="${entry}">${entry}</lion-option> `),
+    )}
+  </lion-combobox>
+`;
+```
+
+When the preconfigurable `match-mode` conditions are not sufficient,
+one can define a custom matching function.
+The example below matches when the Levenshtein distance is below 3 (including some other conditions).
+
+```js preview-story
+export const customMatchCondition = () => html`
+  <lion-combobox
+    name="combo"
+    label="Custom Match Mode 'levenshtein'"
+    help-text="Spelling mistakes will be forgiven. Try typing 'Aple' instead of 'Apple'"
+    .matchCondition="${({ choiceValue }, textboxValue) => {
+      const oVal = choiceValue.toLowerCase();
+      const tVal = textboxValue.toLowerCase();
+      const t = 1; // treshold
+      return oVal.slice(0, t) === tVal.slice(0, t) && levenshtein(oVal, tVal) < 3;
+    }}"
+  >
+    ${lazyRender(
+      listboxData.map(entry => html` <lion-option .choiceValue="${entry}">${entry}</lion-option> `),
+    )}
+  </lion-combobox>
+`;
+```
+
+## Options
+
+```js preview-story
+export const showAllOnEmpty = () => html`
+  <lion-combobox
+    name="combo"
+    label="Show all on empty"
+    help-text="Shows all (options) on empty (textbox has no value)"
+    show-all-on-empty
+  >
+    ${lazyRender(
+      listboxData.map(entry => html` <lion-option .choiceValue="${entry}">${entry}</lion-option> `),
+    )}
+  </lion-combobox>
+`;
+```
+
+### Changing defaults
+
+By default `selection-follows-focus` will be true (aligned with the
+wai-aria examples and the native `<datalist>`).
+It is possible to disable this behavior, so the active/focused and checked/selected values
+will be kept track of independently.
+
+> Note that, (just like in a listbox), selection-follows-focus will never be applicable for
+> multiselect comboboxes.
+
+```js preview-story
+export const noSelectionFollowsFocus = () => html`
+  <lion-combobox name="combo" label="No Selection Follows focus" .selectionFollowsFocus="${false}">
+    ${lazyRender(
+      listboxData.map(entry => html` <lion-option .choiceValue="${entry}">${entry}</lion-option> `),
+    )}
+  </lion-combobox>
+`;
+```
+
+By default `rotate-keyboard-navigation` will be true (aligned with the
+wai-aria examples and the natve `<datalist>`).
+It is possible to disable this behavior, see example below
+
+```js preview-story
+export const noRotateKeyboardNavigation = () => html`
+  <lion-combobox
+    name="combo"
+    label="No Rotate Keyboard Navigation"
+    .rotateKeyboardNavigation="${false}"
+  >
+    ${lazyRender(
+      listboxData.map(entry => html` <lion-option .choiceValue="${entry}">${entry}</lion-option> `),
+    )}
+  </lion-combobox>
+`;
+```
+
+## Multiple choice
+
+Add `multiple-choice` flag to allow multiple values to be selected.
+This will:
+
+- keep the listbox overlay open on click of an option
+- display a list of selected option representations next to the text box
+- make the value of type `Array` instead of `String`
+
+> Please note that the lion-combobox-selection-display below is not exposed and only serves
+> as an example. The selection part of a multiselect combobox is not yet accessible. Please keep
+> in mind that for now, as a Subclasser, you would have to take care of this part yourself.
+
+```js preview-story
+export const multipleChoice = () => html`
+  <lion-combobox name="combo" label="Multiple" multiple-choice>
+    <demo-selection-display
+      slot="selection-display"
+      style="display: contents;"
+    ></demo-selection-display>
+    ${lazyRender(
+      listboxData.map(
+        (entry, i) =>
+          html` <lion-option .choiceValue="${entry}" ?checked=${i === 0}>${entry}</lion-option> `,
+      ),
+    )}
+  </lion-combobox>
+`;
+```
+
+## Invoker button
+
+```js preview-story
+export const invokerButton = () => html`
+  <lion-combobox
+    .modelValue="${listboxData[1]}"
+    autocomplete="none"
+    name="combo"
+    label="Invoker Button"
+    @click="${({ currentTarget: el }) => {
+      el.opened = !el.opened;
+    }}"
+  >
+    <button slot="suffix" type="button" tabindex="-1">▼</button>
+    ${lazyRender(
+      listboxData.map(entry => html` <lion-option .choiceValue="${entry}">${entry}</lion-option> `),
+    )}
+  </lion-combobox>
+`;
+```
+
+## Server interaction
+
+It's possible to fetch data from server side. When options are rerendered into the combobox,
+the autocompletion (highlighting/selecting etc.) functionality of the combobox is triggered.
+
+```js preview-story
+const comboboxData = ['lorem', 'ipsum', 'dolor', 'sit', 'amet'];
+let rejectPrev;
+/**
+ * @param {string} val
+ */
+function fetchMyData(val) {
+  if (rejectPrev) {
+    rejectPrev();
+  }
+  const results = listboxData.filter(item => item.toLowerCase().includes(val.toLowerCase()));
+  return new Promise((resolve, reject) => {
+    rejectPrev = reject;
+    setTimeout(() => {
+      resolve(results);
+    }, 1000);
+  });
+}
+class DemoServerSide extends LitElement {
+  static get properties() {
+    return { options: { type: Array } };
+  }
+
+  constructor() {
+    super();
+    /** @type {string[]} */
+    this.options = [];
+  }
+
+  get combobox() {
+    return /** @type {LionCombobox} */ (this.shadowRoot?.querySelector('#combobox'));
+  }
+
+  /**
+   * @param {InputEvent & {target: HTMLInputElement}} e
+   */
+  async fetchMyDataAndRender(e) {
+    this.loading = true;
+    this.requestUpdate();
+    try {
+      this.options = await fetchMyData(e.target.value);
+      this.loading = false;
+      this.requestUpdate();
+    } catch (_) {}
+  }
+
+  render() {
+    return html`
+      <lion-combobox
+        .showAllOnEmpty="${true}"
+        id="combobox"
+        @input="${this.fetchMyDataAndRender}"
+        .helpText="Returned from server: [${this.options.join(', ')}]"
+      >
+        <label slot="label" aria-live="polite"
+          >Server side completion ${this.loading
+            ? html`<span style="font-style: italic;">(loading...)</span>`
+            : ''}</label
+        >
+        ${repeat(
+          this.options,
+          entry => entry,
+          entry => html` <lion-option .choiceValue="${entry}">${entry}</lion-option> `,
+        )}
+      </lion-combobox>
+    `;
+  }
+}
+customElements.define('demo-server-side', DemoServerSide);
+export const serverSideCompletion = () => html`<demo-server-side></demo-server-side>`;
+```
+
+## Set complex object in choiceValue
+
+A common use case is to set a complex object in the `choiceValue` property. By default, `LionCombobox` will display in the text input the `modelValue`. By overriding the `_getTextboxValueFromOption` method, you can choose which value will be used for the input value.
+
+```js preview-story
+class ComplexObjectCombobox extends LionCombobox {
+  /**
+   * Override how the input text is filled
+   * @param {LionOption} option
+   * @returns {string}
+   */
+  // eslint-disable-next-line class-methods-use-this
+  _getTextboxValueFromOption(option) {
+    return option.label;
+  }
+}
+
+customElements.define('complex-object-combobox', ComplexObjectCombobox);
+
+const onModelValueChanged = event => {
+  console.log(`event.target.modelValue: ${JSON.stringify(event.target.modelValue)}`);
+};
+
+const listboxDataObject = listboxData.map(e => {
+  return { label: e, name: e };
+});
+
+export const complexObjectChoiceValue = () => html` <complex-object-combobox
+  name="combo"
+  label="Display only the label once selected"
+  @model-value-changed="${onModelValueChanged}"
+>
+  ${lazyRender(
+    listboxDataObject.map(
+      entry =>
+        html`
+          <lion-option .choiceValue="${entry}" .label="${entry.label}">${entry.label}</lion-option>
+        `,
+    ),
+  )}
+</complex-object-combobox>`;
+```
+
+## Listbox compatibility
+
+All configurations that can be applied to `lion-listbox`, can be applied to `lion-combobox` as well.
+See the [listbox documentation](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/components/listbox/overview.md) for more information.

package/docs/components/dialog/index.md

@@ -0,0 +1,3 @@
+# Dialog ||20
+
+-> go to Overview

package/docs/components/dialog/overview.md

@@ -0,0 +1,63 @@
+# Dialog >> Overview ||10
+
+A web component that wraps a modal dialog controller.
+Its purpose is to make it easy to use our Overlay System declaratively.
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-dialog.js';
+
+import { demoStyle } from './src/demoStyle.js';
+```
+
+```js preview-story
+export const main = () => html`
+  <style>
+    ${demoStyle}
+  </style>
+  <lion-dialog>
+    <button slot="invoker">Click me to open dialog</button>
+    <div slot="content" class="dialog">
+      Hello! You can close this dialog here:
+      <button
+        class="close-button"
+        @click=${e => e.target.dispatchEvent(new Event('close-overlay', { bubbles: true }))}
+      >
+        ⨯
+      </button>
+    </div>
+  </lion-dialog>
+`;
+```
+
+## Features
+
+- Show content when clicking the invoker
+- Respond to close event in the slot="content" element, to close the content
+- Have a `.config` object to set or update the OverlayController's configuration
+
+## Installation
+
+```bash
+npm i --save @lion/ui
+```
+
+```js
+import { LionDialog } from '@lion/ui/dialog.js';
+// or
+import '@lion/ui/define/lion-dialog.js';
+```
+
+- Your `slot="content"` node will be moved to the global overlay container during initialization.
+  After, your content node is no longer a child of `lion-dialog`.
+  If you still need to access it from the `lion-dialog` you can do so by using the `._overlayContentNode` property.
+- To close the overlay from within the content node, you need to dispatch a `close-overlay` event that bubbles.
+  It has to be able to reach the content node.
+- If you need to traverse shadow boundaries, you will have to add `composed: true` as well, although this is discouraged as a practice.
+
+## Changing the configuration
+
+You can use the `config` property on the dialog to change the configuration.
+The documentation of the full config object can be found in the `lion/overlay` package or here in [Overlay System - Configuration](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/systems/overlays/configuration.md).
+
+The `config` property uses a setter to merge the passed configuration with the current, so you only **overwrite what you pass** when updating `config`.

package/docs/components/dialog/src/demo-dialog-style.js

@@ -0,0 +1,3 @@
+import { css } from 'lit';
+
+export default css``;

package/docs/components/dialog/src/demoStyle.js

@@ -0,0 +1,39 @@
+import { css } from 'lit';
+
+export const demoStyle = css`
+  .demo-box {
+    width: 200px;
+    background-color: white;
+    border-radius: 2px;
+    border: 1px solid grey;
+    padding: 8px;
+  }
+  .demo-box_placements {
+    display: flex;
+    flex-direction: column;
+    margin-top: 20px;
+  }
+  lion-dialog {
+    display: block;
+    padding: 10px;
+    margin-bottom: 10px;
+  }
+  .close-button {
+    color: black;
+    font-size: 28px;
+    line-height: 28px;
+  }
+  .demo-box__column {
+    display: flex;
+    flex-direction: column;
+  }
+  .demo-dialog--content {
+    display: block;
+    position: absolute;
+    font-size: 16px;
+    color: white;
+    background-color: black;
+    border-radius: 4px;
+    padding: 8px;
+  }
+`;

package/docs/components/dialog/src/slots-dialog-content.js

@@ -0,0 +1,32 @@
+import { LitElement, html, css } from 'lit';
+
+class SlotsDialogContent extends LitElement {
+  static get styles() {
+    return [
+      css`
+        :host {
+          background-color: #fff;
+        }
+        .actions {
+          border-top: 2px solid green;
+        }
+      `,
+    ];
+  }
+
+  _closeOverlay() {
+    this.dispatchEvent(new Event('close-overlay', { bubbles: true }));
+  }
+
+  render() {
+    return html`
+      <p>This content contains an actions slot</p>
+      <div class="actions">
+        <slot name="actions"></slot>
+      </div>
+      <button class="close-button" @click=${this._closeOverlay}>⨯</button>
+    `;
+  }
+}
+
+customElements.define('slots-dialog-content', SlotsDialogContent);

package/docs/components/dialog/src/styled-dialog-content.js

@@ -0,0 +1,38 @@
+import { LitElement, html, css } from 'lit';
+
+class StyledDialogContent extends LitElement {
+  static get styles() {
+    return [
+      css`
+        :host {
+          background-color: #fff;
+        }
+        .nice {
+          font-weight: bold;
+          color: green;
+        }
+        .close-button {
+          color: black;
+          font-size: 28px;
+          line-height: 28px;
+        }
+      `,
+    ];
+  }
+
+  _closeOverlay() {
+    this.dispatchEvent(new Event('close-overlay', { bubbles: true }));
+  }
+
+  render() {
+    return html`
+      <div><p>Hello person who opened the dialog!</p></div>
+      <div>
+        <p>Look how nice this <span class="nice">dialog</span> looks!</p>
+      </div>
+      <button class="close-button" @click=${this._closeOverlay}>⨯</button>
+    `;
+  }
+}
+
+customElements.define('styled-dialog-content', StyledDialogContent);