@lion/ui 0.0.2 → 0.0.3

package/docs/components/collapsible/examples.md

@@ -0,0 +1,83 @@
+# Collapsible >> Examples ||30
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-collapsible.js';
+import '@lion/ui/define/lion-button.js';
+import './assets/CustomCollapsible.js';
+import './assets/applyDemoCollapsibleStyles.js';
+```
+
+## Custom Invoker Template
+
+A custom template can be specified to the `invoker` slot. It can be any button or custom component which mimics the button behavior for better accessibility support. In the below example, `lion-button` and native `button` with styling is used as a collapsible invoker.
+
+```js preview-story
+export const customInvokerTemplate = () => html`
+  <lion-collapsible style="margin-top:16px;">
+    <lion-button slot="invoker">More about cars</lion-button>
+    <div slot="content">
+      Most definitions of cars say that they run primarily on roads, seat one to eight people, have
+      four tires, and mainly transport people rather than goods.
+    </div>
+  </lion-collapsible>
+`;
+```
+
+## Extended collapsible with animation
+
+`LionCollapsible` can easily be extended to add more features in the component, like animation for example.
+
+```js preview-story
+export const customAnimation = () => html`
+  <div class="demo-custom-collapsible-container">
+    <div class="demo-custom-collapsible-body">
+      A motorcycle, often called a motorbike, bike, or cycle, is a two- or three-wheeled motor
+      vehicle.
+    </div>
+    <custom-collapsible>
+      <button class="demo-custom-collapsible-invoker" slot="invoker">MORE ABOUT MOTORCYCLES</button>
+      <div slot="content">
+        Motorcycle design varies greatly to suit a range of different purposes: long distance
+        travel, commuting, cruising, sport including racing, and off-road riding. Motorcycling is
+        riding a motorcycle and related social activity such as joining a motorcycle club and
+        attending motorcycle rallies.
+      </div>
+    </custom-collapsible>
+  </div>
+  <div class="demo-custom-collapsible-container">
+    <div class="demo-custom-collapsible-body">
+      A car (or automobile) is a wheeled motor vehicle used for transportation.
+    </div>
+    <custom-collapsible opened>
+      <button class="demo-custom-collapsible-invoker" slot="invoker">MORE ABOUT CARS</button>
+      <div slot="content">
+        Most definitions of cars say that they run primarily on roads, seat one to eight people,
+        have four tires, and mainly transport people rather than goods.
+      </div>
+    </custom-collapsible>
+  </div>
+`;
+```
+
+Use `_showAnimation()` and `_hideAnimation()` methods to customize open and close behavior. Check the code for a full example of a `custom-collapsible`.
+
+```js
+_showAnimation({ contentNode }) {
+    const expectedHeight = await this.__calculateHeight(contentNode);
+    contentNode.style.setProperty('opacity', '1');
+    contentNode.style.setProperty('padding', '12px 0');
+    contentNode.style.setProperty('max-height', '0px');
+    await new Promise(resolve => requestAnimationFrame(() => resolve()));
+    contentNode.style.setProperty('max-height', expectedHeight);
+    await this._waitForTransition({ contentNode });
+}
+
+_hideAnimation({ contentNode }) {
+    if (this._contentHeight === '0px') {
+      return;
+    }
+    ['opacity', 'padding', 'max-height'].map(prop => contentNode.style.setProperty(prop, 0));
+    await this._waitForTransition({ contentNode });
+}
+```

package/docs/components/collapsible/index.md

@@ -0,0 +1,3 @@
+# Collapsible ||10
+
+-> go to Overview

package/docs/components/collapsible/overview.md

@@ -0,0 +1,39 @@
+# Collapsible >> Overview ||10
+
+A combination of a button (the invoker) and a chunk of 'extra content'. This web component can be extended with an animation to disclose the extra content. There are two slots available respectively; `invoker` to specify the collapsible's invoker and `content` for the extra content of the collapsible.
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-collapsible.js';
+```
+
+```js preview-story
+export const main = () => html`
+  <lion-collapsible>
+    <button slot="invoker">More about cars</button>
+    <div slot="content">
+      Most definitions of cars say that they run primarily on roads, seat one to eight people, have
+      four tires, and mainly transport people rather than goods.
+    </div>
+  </lion-collapsible>
+`;
+```
+
+## Features
+
+- Use `opened` attribute or `toggle()` method to render default open.
+- `invoker` slot can be custom template e.g. our [button](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/components/button/overview.md) or native `button` with custom styling.
+- Observe the state with the help of `@opened-changed` event.
+- `show()` and `hide()` are helper methods to hide or show the content from outside.
+
+## Installation
+
+```bash
+npm i --save @lion/ui
+```
+
+```js
+import { LionCollapsible } from '@lion/ui/collapsible.js';
+// or
+import '@lion/ui/define/lion-collapsible.js';
+```

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

@@ -0,0 +1,79 @@
+# Collapsible >> Use Cases ||20
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-collapsible.js';
+```
+
+## Default open
+
+Add the `opened` attribute to keep the component default open.
+
+```js preview-story
+export const defaultOpen = () => html`
+  <lion-collapsible opened>
+    <button slot="invoker">More about cars</button>
+    <div slot="content">
+      Most definitions of cars say that they run primarily on roads, seat one to eight people, have
+      four tires, and mainly transport people rather than goods.
+    </div>
+  </lion-collapsible>
+`;
+```
+
+## Methods
+
+There are the following methods available to control the extra content for the collapsible.
+
+- `toggle()`: toggle the extra content
+- `show()`: show the extra content
+- `hide()`: hide the extra content
+
+```js preview-story
+export const methods = ({ shadowRoot }) => html`
+  <lion-collapsible id="car-collapsible">
+    <button slot="invoker">More about cars</button>
+    <div slot="content">
+      Most definitions of cars say that they run primarily on roads, seat one to eight people, have
+      four tires, and mainly transport people rather than goods.
+    </div>
+  </lion-collapsible>
+  <section style="margin-top:16px">
+    <button @click=${() => shadowRoot.querySelector('#car-collapsible').toggle()}>
+      Toggle content
+    </button>
+    <button @click=${() => shadowRoot.querySelector('#car-collapsible').show()}>
+      Show content
+    </button>
+    <button @click=${() => shadowRoot.querySelector('#car-collapsible').hide()}>
+      Hide content
+    </button>
+  </section>
+`;
+```
+
+## Events
+
+`lion-collapsible` fires an event on `invoker` click to notify the component's current state. It is useful for analytics purposes or to perform some actions while expanding and collapsing the component.
+
+- `@opened-changed`: triggers when collapsible either gets opened or closed
+
+```js preview-story
+export const events = ({ shadowRoot }) => html`
+  <div class="demo-custom-collapsible-state-container">
+    <strong id="collapsible-state"></strong>
+  </div>
+  <lion-collapsible
+    @opened-changed=${ev => {
+      const collapsibleState = shadowRoot.getElementById('collapsible-state');
+      collapsibleState.innerText = `Opened: ${ev.target.opened}`;
+    }}
+  >
+    <button slot="invoker">More about cars</button>
+    <div slot="content">
+      Most definitions of cars say that they run primarily on roads, seat one to eight people, have
+      four tires, and mainly transport people rather than goods.
+    </div>
+  </lion-collapsible>
+`;
+```

package/docs/components/combobox/examples.md

@@ -0,0 +1,153 @@
+# Combobox >> Examples ||30
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import './src/md-combobox/md-combobox.js';
+import './src/gh-combobox/gh-combobox.js';
+import './src/wa-combobox/wa-combobox.js';
+import './src/google-combobox/google-combobox.js';
+```
+
+Below several extensions can be found. They illustrate that complex UI components can be created
+easily from an extended Lion component, just by:
+
+- **configuring**: setting properties or providing conditions via methods
+- **enhancing**: adding extra html/styles/logic without changing behavior of the extended element
+- **overriding**: replace html/styles/logic of the extended element with your own
+
+## Material Design
+
+```js preview-story
+export const MaterialDesign = () => html`
+  <md-combobox name="combo" label="Default">
+    <md-option .choiceValue=${'Apple'}>Apple</md-option>
+    <md-option .choiceValue=${'Artichoke'}>Artichoke</md-option>
+    <md-option .choiceValue=${'Asparagus'}>Asparagus</md-option>
+    <md-option .choiceValue=${'Banana'}>Banana</md-option>
+    <md-option .choiceValue=${'Beets'}>Beets</md-option>
+  </md-combobox>
+`;
+```
+
+## Github
+
+```js preview-story
+export const Github = () => html`
+  <gh-combobox name="combo" label="Switch branches/tags">
+    <gh-option href="https://www.github.com" .choiceValue=${'master'} default>master</gh-option>
+    <gh-option .choiceValue=${'develop'}>develop</gh-option>
+    <gh-option .choiceValue=${'release'}>release</gh-option>
+    <gh-option .choiceValue=${'feat/abc'}>feat/abc</gh-option>
+    <gh-option .choiceValue=${'feat/xyz123'}>feat/xyz123</gh-option>
+  </gh-combobox>
+`;
+```
+
+## Whatsapp
+
+```js preview-story
+export const Whatsapp = () => html`
+  <wa-combobox name="combo" label="Filter chats">
+    <wa-option
+      title="Barack Obama"
+      text="Yup, let's try that for now👍"
+      time="15:02"
+      is-user-text
+      is-user-text-read
+      image="https://pbs.twimg.com/profile_images/822547732376207360/5g0FC8XX_400x400.jpg"
+      .choiceValue=${'Barack Obama'}
+    ></wa-option>
+    <wa-option
+      title="Donald Trump"
+      text="Take care!"
+      time="14:59"
+      is-user-text
+      image="https://pbs.twimg.com/profile_images/874276197357596672/kUuht00m_400x400.jpg"
+      .choiceValue=${'Donald Trump'}
+    ></wa-option>
+    <wa-option
+      title="Joe Biden"
+      text="Hehe😅. You too, man, you too..."
+      time="yesterday"
+      image="https://pbs.twimg.com/profile_images/1308769664240160770/AfgzWVE7_400x400.jpg"
+      .choiceValue=${'Joe Biden'}
+    ></wa-option>
+    <wa-option
+      title="George W. Bush"
+      time="friday"
+      text="You bet I will. Let's catch up soon!"
+      image="https://pbs.twimg.com/profile_images/828483922266877954/ljYUWUCu_400x400.jpg"
+      .choiceValue=${'George W. Bush'}
+    ></wa-option>
+    <wa-option
+      title="Bill Clinton"
+      time="thursday"
+      text="Dude...😂 😂 😂"
+      image="https://pbs.twimg.com/profile_images/1239440892664086529/iY0Z83Dr_400x400.jpg"
+      .choiceValue=${'Bill Clinton'}
+    ></wa-option>
+  </wa-combobox>
+`;
+```
+
+**Whatsapp example shows:**
+
+- advanced styling
+- how to match/highlight text on multiple rows of the option (not just choiceValue)
+- how to animate options
+
+## Google Search
+
+```js preview-story
+export const GoogleSearch = () => {
+  return html`
+    <google-combobox name="combo" label="Google Search">
+      <google-option
+        href="https://www.google.com/search?query=apple"
+        target="_blank"
+        rel="noopener noreferrer"
+        .choiceValue=${'Apple'}
+        >Apple</google-option
+      >
+      <google-option
+        href="https://www.google.com/search?query=Artichoke"
+        target="_blank"
+        rel="noopener noreferrer"
+        .choiceValue=${'Artichoke'}
+        >Artichoke</google-option
+      >
+      <google-option
+        href="https://www.google.com/search?query=Asparagus"
+        target="_blank"
+        rel="noopener noreferrer"
+        .choiceValue=${'Asparagus'}
+        >Asparagus</google-option
+      >
+      <google-option
+        href="https://www.google.com/search?query=Banana"
+        target="_blank"
+        rel="noopener noreferrer"
+        .choiceValue=${'Banana'}
+        >Banana</google-option
+      >
+      <google-option
+        href="https://www.google.com/search?query=Beets"
+        target="_blank"
+        rel="noopener noreferrer"
+        .choiceValue=${'Beets'}
+        >Beets</google-option
+      >
+    </google-combobox>
+    <div style="height:200px;"></div>
+  `;
+};
+```
+
+**Google Search example shows:**
+
+- advanced styling
+- how to use options that are links
+- create exact user experience of Google Search, by:
+  - using autocomplete 'list' as a fundament (we don't want inline completion in textbox)
+  - enhancing `_showOverlayCondition`: open on focus
+  - enhancing `_syncToTextboxCondition`: always sync to textbox when navigating by keyboard (this needs to be enabled, since it's not provided in the "autocomplete=list" preset)

package/docs/components/combobox/index.md

@@ -0,0 +1,3 @@
+# Combobox ||10
+
+-> go to Overview

package/docs/components/combobox/overview.md

@@ -0,0 +1,51 @@
+# Combobox >> Overview ||10
+
+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 pop-up.
+
+> Fore more information, consult [Combobox wai-aria design pattern](https://www.w3.org/TR/wai-aria-practices/#combobox)
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import { listboxData } from '../listbox/src/listboxData.js';
+import '@lion/ui/define/lion-combobox.js';
+import '@lion/ui/define/lion-option.js';
+import { lazyRender } from './src/lazyRender.js';
+```
+
+```js preview-story
+export const main = () => html`
+  <lion-combobox name="combo" label="Default">
+    ${lazyRender(
+      listboxData.map(
+        (entry, i) =>
+          html` <lion-option .checked="${i === 0}" .choiceValue="${entry}">${entry}</lion-option> `,
+      ),
+    )}
+  </lion-combobox>
+`;
+```
+
+[...show more](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/components/combobox/examples.md)
+
+## Features
+
+> tbd
+
+## Installation
+
+```bash
+npm i --save @lion/ui
+```
+
+```js
+import '@lion/ui/define/lion-combobox.js';
+import '@lion/ui/define/lion-option.js';
+```

package/docs/components/combobox/src/LinkMixin.js

@@ -0,0 +1,60 @@
+import { dedupeMixin } from '@open-wc/dedupe-mixin';
+
+/**
+ * @typedef {import('lit-element').PropertyValues } changedProperties
+ */
+
+/**
+ * Designed for webcomponents that need to behave like a link.
+ * For instance, comboboxes that have search result options opening a webpage on click.
+ * Using an <a> is not a viable alternative, because:
+ * - no shadow dom (and thus no style encapsulation possibilities)
+ * - we need to extend from LionOption (and we cannot put the anchor inside
+ * the focusable element (LionOption which has [role=option]))
+ */
+const LinkMixinImplementation = superclass =>
+  class extends superclass {
+    static get properties() {
+      return {
+        href: String,
+        target: String,
+      };
+    }
+
+    constructor() {
+      super();
+      this._nativeAnchor = document.createElement('a');
+    }
+
+    connectedCallback() {
+      super.connectedCallback();
+      if (!this.hasAttribute('role')) {
+        this.setAttribute('role', 'link');
+      }
+    }
+
+    firstUpdated(changedProperties) {
+      super.firstUpdated(changedProperties);
+      this.addEventListener('click', this.__navigate);
+      this.addEventListener('keydown', ({ key }) => {
+        if (key === ' ' || key === 'Enter') {
+          this.__navigate();
+        }
+      });
+    }
+
+    updated(changedProperties) {
+      super.updated(changedProperties);
+      if (changedProperties.has('href')) {
+        this._nativeAnchor.href = this.href;
+      }
+      if (changedProperties.has('target')) {
+        this._nativeAnchor.target = this.target;
+      }
+    }
+
+    __navigate() {
+      this._nativeAnchor.click();
+    }
+  };
+export const LinkMixin = dedupeMixin(LinkMixinImplementation);

package/docs/components/combobox/src/demo-selection-display.js

@@ -0,0 +1,191 @@
+// eslint-disable-next-line max-classes-per-file
+import { LitElement, html, css, nothing } from 'lit';
+
+/**
+ * Disclaimer: this is just an example component demoing the selection display of LionCombobox
+ * It needs an 'a11y plan' and tests before it could be released
+ */
+
+/**
+ * @typedef {import('./LionCombobox.js.js.js.js').LionCombobox} LionCombobox
+ */
+
+/**
+ * Renders the wrapper containing the textbox that triggers the listbox with filtered options.
+ * Optionally, shows 'chips' that indicate the selection.
+ * Should be considered an internal/protected web component to be used in conjunction with
+ * LionCombobox
+ *
+ */
+export class DemoSelectionDisplay extends LitElement {
+  static get properties() {
+    return {
+      comboboxElement: Object,
+      /**
+       * Can be used to visually indicate the next
+       */
+      removeChipOnNextBackspace: Boolean,
+      selectedElements: Array,
+    };
+  }
+
+  static get styles() {
+    return css`
+      :host {
+        display: flex;
+      }
+
+      .combobox__selection {
+        flex: none;
+      }
+
+      .combobox__input {
+        display: block;
+      }
+
+      .selection-chip {
+        border-radius: 4px;
+        background-color: #eee;
+        padding: 4px;
+        font-size: 10px;
+      }
+
+      .selection-chip--highlighted {
+        background-color: #ccc;
+      }
+
+      * > ::slotted([slot='_textbox']) {
+        outline: none;
+        width: 100%;
+        height: 100%;
+        box-sizing: border-box;
+        border: none;
+        border-bottom: 1px solid;
+      }
+    `;
+  }
+
+  /**
+   * @configure FocusMixin
+   */
+  get _inputNode() {
+    return this.comboboxElement._inputNode;
+  }
+
+  _computeSelectedElements() {
+    const { formElements, checkedIndex } = /** @type {LionCombobox} */ (this.comboboxElement);
+    const checkedIndexes = Array.isArray(checkedIndex) ? checkedIndex : [checkedIndex];
+    return formElements.filter((_, i) => checkedIndexes.includes(i));
+  }
+
+  get multipleChoice() {
+    return this.comboboxElement?.multipleChoice;
+  }
+
+  constructor() {
+    super();
+
+    this.selectedElements = [];
+
+    /** @type {EventListener} */
+    this.__textboxOnKeyup = this.__textboxOnKeyup.bind(this);
+    /** @type {EventListener} */
+    this.__restoreBackspace = this.__restoreBackspace.bind(this);
+  }
+
+  /**
+   * @param {import('lit-element').PropertyValues } changedProperties
+   */
+  firstUpdated(changedProperties) {
+    super.firstUpdated(changedProperties);
+
+    if (this.multipleChoice) {
+      this._inputNode.addEventListener('keyup', this.__textboxOnKeyup);
+      this._inputNode.addEventListener('focusout', this.__restoreBackspace);
+    }
+  }
+
+  /**
+   * @param {import('lit-element').PropertyValues } changedProperties
+   */
+  onComboboxElementUpdated(changedProperties) {
+    if (changedProperties.has('modelValue')) {
+      this.selectedElements = this._computeSelectedElements();
+    }
+  }
+
+  /**
+   * Whenever selectedElements are updated, makes sure that latest added elements
+   * are shown latest, and deleted elements respect existing order of chips.
+   */
+  __reorderChips() {
+    const { selectedElements } = this;
+    if (this.__prevSelectedEls) {
+      const addedEls = selectedElements.filter(e => !this.__prevSelectedEls.includes(e));
+      const deletedEls = this.__prevSelectedEls.filter(e => !selectedElements.includes(e));
+      if (addedEls.length) {
+        this.selectedElements = [...this.__prevSelectedEls, ...addedEls];
+      } else if (deletedEls.length) {
+        deletedEls.forEach(delEl => {
+          this.__prevSelectedEls.splice(this.__prevSelectedEls.indexOf(delEl), 1);
+        });
+        this.selectedElements = this.__prevSelectedEls;
+      }
+    }
+    this.__prevSelectedEls = this.selectedElements;
+  }
+
+  /**
+   * @param {import("@lion/listbox").LionOption} option
+   * @param {boolean} highlight
+   */
+  // eslint-disable-next-line class-methods-use-this
+  _selectedElementTemplate(option, highlight) {
+    return html`
+      <span class="selection-chip ${highlight ? 'selection-chip--highlighted' : ''}">
+        ${option.value}
+      </span>
+    `;
+  }
+
+  _selectedElementsTemplate() {
+    if (!this.multipleChoice) {
+      return nothing;
+    }
+    return html`
+      <div class="combobox__selection">
+        ${this.selectedElements.map((option, i) => {
+          const highlight = Boolean(
+            this.removeChipOnNextBackspace && i === this.selectedElements.length - 1,
+          );
+          return this._selectedElementTemplate(option, highlight);
+        })}
+      </div>
+    `;
+  }
+
+  render() {
+    return html` ${this._selectedElementsTemplate()} `;
+  }
+
+  /**
+   * @param {{ key: string; }} ev
+   */
+  __textboxOnKeyup(ev) {
+    if (ev.key === 'Backspace') {
+      if (!this._inputNode.value) {
+        if (this.removeChipOnNextBackspace && this.selectedElements.length) {
+          this.selectedElements[this.selectedElements.length - 1].checked = false;
+        }
+        this.removeChipOnNextBackspace = true;
+      }
+    } else {
+      this.removeChipOnNextBackspace = false;
+    }
+  }
+
+  __restoreBackspace() {
+    this.removeChipOnNextBackspace = false;
+  }
+}
+customElements.define('demo-selection-display', DemoSelectionDisplay);