@lion/ui 0.0.2 → 0.0.3

package/docs/components/progress-indicator/examples.md

@@ -0,0 +1,125 @@
+# Progress Indicator >> Examples ||30
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-progress-indicator.js';
+import './assets/my-indeterminate-progress-spinner.js';
+import './assets/my-determinate-progress-bar.js';
+
+const changeProgress = () => {
+  const progressBar = document.getElementsByName('my-bar')[0];
+  progressBar.value = Math.floor(Math.random() * 101);
+};
+```
+
+## Styled progress bar example
+
+Add custom styles and more features by extending the `LionProgressIndicator`.
+
+```js
+export class MyDeterminateProgressBar extends LionProgressIndicator {
+  static get styles() {
+    return [
+      css`
+        :host {
+          display: block;
+          position: relative;
+          width: 100%;
+          height: 6px;
+          overflow: hidden;
+          background-color: #eee;
+        }
+
+        .progress__filled {
+          height: inherit;
+          background-color: green;
+          border-radius: inherit;
+        }
+      `,
+    ];
+  }
+
+  _graphicTemplate() {
+    return html`
+      <div class="progress__filled" style="width: \${this._progressPercentage}%"></div>
+    `;
+  }
+}
+```
+
+By given the progress-indicator a value it becomes determinate.
+The min is automatically set to "0" and max to "100", but they can be set to your local needs.
+
+```js preview-story
+export const progressBarDemo = () =>
+  html`
+    <my-determinate-progress-bar
+      aria-label="Interest rate"
+      name="my-bar"
+      value="50"
+    ></my-determinate-progress-bar>
+    <button @click="${changeProgress}">Randomize Value</button>
+  `;
+```
+
+## Styled progress spinner example
+
+`LionProgressIndicator` is designed to be extended to add visuals. Implement the `_graphicTemplate()` method to set the rendered content and apply styles normally.
+
+```js
+class MyIndeterminateProgressSpinner extends LionProgressIndicator {
+  static get styles() {
+    return [
+      css`
+        .progress__icon {
+          display: inline-block;
+          width: 48px;
+          height: 48px;
+          animation: spinner-rotate 2s linear infinite;
+        }
+
+        .progress__filled {
+          animation: spinner-dash 1.35s ease-in-out infinite;
+          fill: none;
+          stroke-width: 6px;
+          stroke: var(--primary-color);
+        }
+
+        @keyframes spinner-rotate {
+          to {
+            transform: rotate(360deg);
+          }
+        }
+
+        @keyframes spinner-dash {
+          0% {
+            stroke-dasharray: 6, 122;
+            stroke-dashoffset: 0;
+          }
+          50% {
+            stroke-dasharray: 100, 28;
+            stroke-dashoffset: -16;
+          }
+          100% {
+            stroke-dasharray: 6, 122;
+            stroke-dashoffset: -127;
+          }
+        }
+      `,
+    ];
+  }
+
+  _graphicTemplate() {
+    return html`
+      <svg class="progress__icon" viewBox="20 20 47 47">
+        <circle class="progress__filled" cx="44" cy="44" r="20.2" />
+      </svg>
+    `;
+  }
+}
+```
+
+```js preview-story
+export const main = () =>
+  html` <my-indeterminate-progress-spinner></my-indeterminate-progress-spinner> `;
+```

package/docs/components/progress-indicator/index.md

@@ -0,0 +1,3 @@
+# Progress Indicator ||30
+
+-> go to Overview

package/docs/components/progress-indicator/overview.md

@@ -0,0 +1,36 @@
+# Progress Indicator >> Overview ||10
+
+A web component that implements accessibility requirements for progress indicators.
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-progress-indicator.js';
+```
+
+```html
+<lion-progress-indicator aria-label="Interest rate" value="50"></lion-progress-indicator>
+```
+
+## Features
+
+This component is designed to be extended in order to add visuals.
+
+- Can be indeterminate or determinate, depending on whether it has a value.
+- Accessibility compliant
+- Localized "Loading" label in case of an indeterminate progress-indicator
+- Implementation independent of visuals
+- `value`: progress value, setting this makes the progress-indicator determinate.
+- `min`: progress min value
+- `max`: progress max value
+
+## Installation
+
+```bash
+npm i --save @lion/ui
+```
+
+```js
+import { LionProgressIndicator } from '@lion/ui/progress-indicator.js';
+// or
+import '@lion/ui/define/lion-progress-indicator.js';
+```

package/docs/components/radio-group/index.md

@@ -0,0 +1,3 @@
+# Radio Group ||30
+
+-> go to Overview

package/docs/components/radio-group/overview.md

@@ -0,0 +1,46 @@
+# Radio Group >> Overview ||10
+
+A web component that enhances the functionality of the native `<input type="radio">` element. Its purpose is to provide a way for users to check a **single** option amongst a set of choices.
+
+You should use our `radio` inside this element.
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-radio-group.js';
+import '@lion/ui/define/lion-radio.js';
+```
+
+```js preview-story
+export const main = () => html`
+  <lion-radio-group name="dinos" label="What are your favourite dinosaurs?">
+    <lion-radio label="allosaurus" .choiceValue=${'allosaurus'}></lion-radio>
+    <lion-radio label="brontosaurus" .choiceValue=${'brontosaurus'}></lion-radio>
+    <lion-radio label="diplodocus" .choiceValue=${'diplodocus'}></lion-radio>
+  </lion-radio-group>
+`;
+```
+
+- Make sure that to use a name attribute as it is necessary for our [form](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/components/form/overview.md)'s serialization result.
+- If you have many options for a user to pick from, consider using our [select](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/components/select/overview.md) instead.
+
+## Features
+
+Since it extends from our [fieldset](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/components/fieldset/overview.md), it has all the features a fieldset has.
+
+- Get or set the checked value of the group:
+  - modelValue (default) - `checkedValue()`
+  - formattedValue - `formattedValue()`
+  - serializedValue - `serializedValue()`
+
+## Installation
+
+```bash
+npm i --save @lion/ui
+```
+
+```js
+import { LionRadioGroup, LionRadio } from '@lion/ui/radio-group.js';
+// or
+import '@lion/ui/define/lion-radio-group.js';
+import '@lion/ui/define/lion-radio.js';
+```

package/docs/components/radio-group/use-cases.md

@@ -0,0 +1,140 @@
+# Radio Group >> Use Cases ||20
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-radio-group.js';
+import '@lion/ui/define/lion-radio.js';
+```
+
+## Model value
+
+The `modelValue` of a `lion-radio-group` is string equal to the `choiceValue` of the `lion-radio` element that has been checked.
+
+Given the dinosaur example above, say that we were to select the last option (diplodocus).
+
+Then the `modelValue` of the `lion-radio-group` will look as follows:
+
+```js
+const groupElement = [parent].querySelector('lion-radio-group');
+groupElement.modelValue;
+  => "diplodocus";
+```
+
+## The `name` attribute
+
+The `name` attribute of a `lion-radio-group` automatically gets assigned to its `lion-radio` children. You can also specify names for the `lion-radio` elements, but if this name is different from the name assigned to `lion-radio-group`, then an exception will be thrown.
+
+Our recommendation would be to set the `name` attribute only on the `lion-radio-group` and not on the `lion-checkbox` elements.
+
+## Pre-select
+
+You can pre-select an option by adding the checked attribute to the selected `lion-radio`.
+
+```js preview-story
+export const preSelect = () => html`
+  <lion-radio-group name="dinos_2" label="What are your favourite dinosaurs?">
+    <lion-radio label="allosaurus" .choiceValue=${'allosaurus'}></lion-radio>
+    <lion-radio label="brontosaurus" .choiceValue=${'brontosaurus'} checked></lion-radio>
+    <lion-radio label="diplodocus" .choiceValue=${'diplodocus'}></lion-radio>
+  </lion-radio-group>
+`;
+```
+
+## Disabled
+
+You can disable a specific `lion-radio` option by adding the `disabled` attribute.
+
+```js preview-story
+export const disabledRadio = () => html`
+  <lion-radio-group name="dinos_4" label="What are your favourite dinosaurs?">
+    <lion-radio label="allosaurus" .choiceValue=${'allosaurus'}></lion-radio>
+    <lion-radio label="brontosaurus" .choiceValue=${'brontosaurus'} disabled></lion-radio>
+    <lion-radio label="diplodocus" .choiceValue=${'diplodocus'}></lion-radio>
+  </lion-radio-group>
+`;
+```
+
+You can do the same thing for the entire group by setting the `disabled` attribute on the `lion-radio-group` element.
+
+```js preview-story
+export const disabledGroup = () => html`
+  <lion-radio-group name="dinos_6" label="What are your favourite dinosaurs?" disabled>
+    <lion-radio label="allosaurus" .choiceValue=${'allosaurus'}></lion-radio>
+    <lion-radio label="brontosaurus" .choiceValue=${'brontosaurus'}></lion-radio>
+    <lion-radio label="diplodocus" .choiceValue=${'diplodocus'}></lion-radio>
+  </lion-radio-group>
+`;
+```
+
+## Label
+
+You can use `slot="label"` instead of the `label` attribute for defining more complex labels, such as containing screen reader only text or an anchor.
+
+```js preview-story
+export const label = () => html`
+  <lion-radio-group name="dinos_7" label="Favourite dinosaur">
+    <lion-radio .choiceValue=${'allosaurus'}>
+      <label slot="label"
+        ><a href="https://wikipedia.org/wiki/allosaurus" target="_blank">allosaurus</a></label
+      >
+    </lion-radio>
+    <lion-radio .choiceValue=${'brontosaurus'}>
+      <label slot="label"
+        ><a href="https://wikipedia.org/wiki/brontosaurus" target="_blank">brontosaurus</a></label
+      >
+    </lion-radio>
+    <lion-radio .choiceValue=${'diplodocus'}>
+      <label slot="label"
+        ><a href="https://wikipedia.org/wiki/diplodocus" target="_blank">diplodocus</a></label
+      >
+    </lion-radio>
+  </lion-radio-group>
+`;
+```
+
+## Help text
+
+You can add help text on each checkbox with `help-text` attribute on the `<lion-radio>`.
+
+```js preview-story
+export const helpText = () => html`
+  <lion-radio-group name="dinosTwo" label="Favourite dinosaur">
+    <lion-radio
+      label="allosaurus"
+      .choiceValue=${'allosaurus'}
+      help-text="Allosaurus is a genus of carnivorous theropod dinosaur that lived 155 to 145 million years ago during the late Jurassic period"
+    ></lion-radio>
+    <lion-radio
+      label="brontosaurus"
+      .choiceValue=${'brontosaurus'}
+      help-text="Brontosaurus is a genus of gigantic quadruped sauropod dinosaurs"
+    ></lion-radio>
+    <lion-radio
+      label="diplodocus"
+      .choiceValue=${'diplodocus'}
+      help-text="Diplodocus is a genus of diplodocid sauropod dinosaurs whose fossils were first discovered in 1877 by S. W. Williston"
+    ></lion-radio>
+  </lion-radio-group>
+`;
+```
+
+## Event
+
+You can listen to the `model-value-changed` event whenever the value of the radio group is changed.
+
+```js preview-story
+export const event = ({ shadowRoot }) => html`
+  <lion-radio-group
+    name="dinosTwo"
+    label="Favourite dinosaur"
+    @model-value-changed=${ev =>
+      (ev.target.parentElement.querySelector('#selectedDinosaur').innerText = ev.target.modelValue)}
+  >
+    <lion-radio label="allosaurus" .choiceValue=${'allosaurus'}></lion-radio>
+    <lion-radio label="brontosaurus" .choiceValue=${'brontosaurus'}></lion-radio>
+    <lion-radio label="diplodocus" .choiceValue=${'diplodocus'}></lion-radio>
+  </lion-radio-group>
+  <br />
+  <span>Selected dinosaur: <strong id="selectedDinosaur">N/A</strong></span>
+`;
+```

package/docs/components/select/index.md

@@ -0,0 +1,3 @@
+# Select ||40
+
+-> go to Overview

package/docs/components/select/overview.md

@@ -0,0 +1,44 @@
+# Select >> Overview ||10
+
+A web component that works as a wrapper around the native `select`.
+
+You cannot use interactive elements inside the options. Avoid very long names to facilitate the understandability and perceivability for screen reader users.
+Sets of options where each option name starts with the same word or phrase can also significantly degrade usability for keyboard and screen reader users.
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-select.js';
+```
+
+```js preview-story
+export const main = () => html`
+  <lion-select name="favoriteColor" label="Favorite color">
+    <select slot="input">
+      <option selected hidden value>Please select</option>
+      <option value="red">Red</option>
+      <option value="hotpink">Hotpink</option>
+      <option value="teal">Teal</option>
+    </select>
+  </lion-select>
+`;
+```
+
+For this form element it is important to put the `slot="input"` with the native `select` yourself, because you are responsible for filling it with `<option>`s.
+For most other form elements we do this for you, because there's no need to put html inside the native form inputs.
+
+## Features
+
+- Catches and forwards the select events
+- Can be set to required or disabled
+
+## Installation
+
+```bash
+npm i --save @lion/ui
+```
+
+```js
+import { LionSelect } from '@lion/ui/select.js';
+// or
+import '@lion/ui/define/lion-select.js';
+```

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

@@ -0,0 +1,55 @@
+# Select >> Use Cases ||20
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-select.js';
+```
+
+## Pre-select
+
+You can preselect an option by setting the property modelValue.
+
+```js preview-story
+export const preSelect = () => html`
+  <lion-select name="favoriteColor" label="Favorite color" .modelValue=${'hotpink'}>
+    <select slot="input">
+      <option selected hidden value>Please select</option>
+      <option value="red">Red</option>
+      <option value="hotpink">Hotpink</option>
+      <option value="teal">Teal</option>
+    </select>
+  </lion-select>
+`;
+```
+
+## Disabled
+
+You can disable an option by adding the `disabled` attribute to an option.
+
+```js preview-story
+export const disabledOption = () => html`
+  <lion-select name="favoriteColor" label="Favorite color">
+    <select slot="input">
+      <option selected hidden value>Please select</option>
+      <option value="red">Red</option>
+      <option value="hotpink" disabled>Hotpink</option>
+      <option value="teal">Teal</option>
+    </select>
+  </lion-select>
+`;
+```
+
+Or by setting the `disabled` attribute on the entire `lion-select` field.
+
+```js preview-story
+export const disabledSelect = () => html`
+  <lion-select name="favoriteColor" label="Favorite color" disabled>
+    <select slot="input">
+      <option selected hidden value>Please select</option>
+      <option value="red">Red</option>
+      <option value="hotpink">Hotpink</option>
+      <option value="teal">Teal</option>
+    </select>
+  </lion-select>
+`;
+```

package/docs/components/select-rich/examples.md

@@ -0,0 +1,31 @@
+# Select Rich >> Examples ||30
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import { repeat } from 'lit/directives/repeat.js';
+import '@lion/ui/define/lion-select-rich.js';
+import './src/intl-select-rich.js';
+import { regionMetaList } from './src/regionMetaList.js';
+```
+
+## Select Rich International
+
+A visually advanced Subclasser implementation of `LionSelectRich`.
+
+Inspired by:
+
+- [intl-tel-input](https://intl-tel-input.com/)
+
+```js story
+export const IntlSelectRich = () => html`
+  <intl-select-rich label="Choose a region" name="regions">
+    ${repeat(
+      regionMetaList,
+      regionMeta => regionMeta.regionCode,
+      regionMeta =>
+        html` <intl-option .choiceValue="${regionMeta.regionCode}" .regionMeta="${regionMeta}">
+        </intl-option>`,
+    )}
+  </intl-select-rich>
+`;
+```

package/docs/components/select-rich/index.md

@@ -0,0 +1,3 @@
+# Select Rich ||40
+
+-> go to Overview

package/docs/components/select-rich/overview.md

@@ -0,0 +1,46 @@
+# Select Rich >> Overview ||10
+
+This web component is a 'rich' version of the native `<select>` element.
+It allows providing fully customized options and a fully customized invoker button and is meant to be used whenever the native `<select>` doesn't provide enough
+styling,theming or user interaction opportunities.
+
+Its implementation is based on the following Design pattern:
+<https://www.w3.org/TR/wai-aria-practices/examples/listbox/listbox-collapsible.html>
+
+```js script
+import { LitElement, html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-select-rich.js';
+import '@lion/ui/define/lion-option.js';
+```
+
+```js preview-story
+export const main = () => html`
+  <lion-select-rich name="favoriteColor" label="Favorite color">
+    <lion-option .choiceValue=${'red'}>Red</lion-option>
+    <lion-option .choiceValue=${'hotpink'}>Hotpink</lion-option>
+    <lion-option .choiceValue=${'blue'}>Blue</lion-option>
+  </lion-select-rich>
+`;
+```
+
+## Features
+
+- Fully accessible
+- Flexible API
+- Fully customizable option elements
+- Fully customizable invoker element
+- Mimics native select interaction mode (windows/linux and mac)
+
+## Installation
+
+```bash
+npm i --save @lion/ui
+```
+
+```js
+import { LionSelectRich } from '@lion/ui/select-rich.js';
+import { LionOptions, LionOption } from '@lion/ui/listbox.js';
+// or
+import '@lion/ui/define/lion-select-rich.js';
+import '@lion/ui/define/lion-option.js';
+```