@lion/ui 0.0.2 → 0.0.3

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

@@ -0,0 +1,192 @@
+# Calendar >> Use Cases ||20
+
+```js script
+import { html, css } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-calendar.js';
+```
+
+## Selected date
+
+The `selectedDate` is the date which is currently marked as selected.
+You usually select a date by clicking on it with the mouse or hitting Enter on the keyboard.
+
+The `selectedDate` might not be within the dates in the current month view.
+
+```js preview-story
+export const selectedDate = () => html`
+  <style>
+    .demo-calendar {
+      border: 1px solid #adadad;
+      box-shadow: 0 0 16px #ccc;
+      max-width: 500px;
+    }
+  </style>
+  <lion-calendar class="demo-calendar" .selectedDate=${new Date(1988, 2, 5)}></lion-calendar>
+`;
+```
+
+## Central Date
+
+The `centralDate` defines which day will be focused when keyboard moves the focus to the current month grid.
+By default it is set to today, or the enabled day of the current month view that is closest to today's date.
+
+The next and previous months' buttons work by changing the `centralDate` with plus or minus one month.
+Changing the `centralDate` may mean a different view will be displayed to your users if it is in a different month.
+Usually if you change only the day, "nothing" happens as it's already currently in view.
+
+The `centralDate` can be different from `selectedDate` as you can have today as actively selected but still look at date that is years ago.
+When the `selectedDate` changes, it will sync its value to the `centralDate`.
+
+```js preview-story
+export const centralDate = () => {
+  const today = new Date();
+  const centralDate = new Date(today.getFullYear(), today.getMonth() + 1, today.getDate());
+  return html`
+    <style>
+      .demo-calendar {
+        border: 1px solid #adadad;
+        box-shadow: 0 0 16px #ccc;
+        max-width: 500px;
+      }
+    </style>
+    <lion-calendar class="demo-calendar" .centralDate="${centralDate}"></lion-calendar>
+  `;
+};
+```
+
+## Controlling focus
+
+You can control the focus by calling the following methods
+
+- `focusCentralDate()`
+- `focusSelectedDate()`
+- `focusDate(dateInstanceToFocus)`
+
+> Be aware that the central date changes when a new date is focused.
+
+```js preview-story
+export const controllingFocus = () => {
+  const today = new Date();
+  const selectedDate = new Date(today.getFullYear(), today.getMonth(), today.getDate() + 1);
+  const centralDate = new Date(today.getFullYear(), today.getMonth(), today.getDate() - 5);
+  return html`
+    <style>
+      .demo-calendar {
+        border: 1px solid #adadad;
+        box-shadow: 0 0 16px #ccc;
+        max-width: 500px;
+      }
+    </style>
+    <lion-calendar
+      id="js-demo-calendar"
+      class="demo-calendar"
+      .selectedDate="${selectedDate}"
+      .centralDate="${centralDate}"
+    ></lion-calendar>
+    <button
+      @click="${e => e.target.parentElement.querySelector('#js-demo-calendar').focusCentralDate()}"
+    >
+      Set focus on: Central date
+    </button>
+    <button
+      @click="${e => e.target.parentElement.querySelector('#js-demo-calendar').focusSelectedDate()}"
+    >
+      Set focus on: Selected date
+    </button>
+    <button
+      @click="${e => e.target.parentElement.querySelector('#js-demo-calendar').focusDate(today)}"
+    >
+      Set focus on: Today
+    </button>
+  `;
+};
+```
+
+## Limiting selectable values
+
+### Providing a lower limit
+
+To give a lower limit you can bind a date to the `minDate` property.
+
+```js preview-story
+export const providingLowerLimit = () => {
+  const minDate = new Date();
+  return html`
+    <style>
+      .demo-calendar {
+        border: 1px solid #adadad;
+        box-shadow: 0 0 16px #ccc;
+        max-width: 500px;
+      }
+    </style>
+    <lion-calendar class="demo-calendar" .minDate="${minDate}"></lion-calendar>
+  `;
+};
+```
+
+### Provide a higher limit
+
+To give a higher limit you can bind a date to the `maxDate` property. In this example, we show how to create an offset of + 2 days.
+
+```js preview-story
+export const providingHigherLimit = () => {
+  const today = new Date();
+  const maxDate = new Date(today.getFullYear(), today.getMonth(), today.getDate() + 2);
+  return html`
+    <style>
+      .demo-calendar {
+        border: 1px solid #adadad;
+        box-shadow: 0 0 16px #ccc;
+        max-width: 500px;
+      }
+    </style>
+    <lion-calendar class="demo-calendar" .maxDate="${maxDate}"></lion-calendar>
+  `;
+};
+```
+
+### Provide a list of disabled dates
+
+In some cases a specific date or day of the week needs to be disabled, supply those days to the `disableDates` property.
+
+```js preview-story
+export const disabledDates = () => html`
+  <style>
+    .demo-calendar {
+      border: 1px solid #adadad;
+      box-shadow: 0 0 16px #ccc;
+      max-width: 500px;
+    }
+  </style>
+  <lion-calendar
+    class="demo-calendar"
+    .disableDates=${day => day.getDay() === 6 || day.getDay() === 0}
+  ></lion-calendar>
+`;
+```
+
+### Combined disable dates
+
+To limit the scope of possible dates further, combine the methods mentioned above.
+
+```js preview-story
+export const combinedDisabledDates = () => {
+  const today = new Date();
+  const maxDate = new Date(today.getFullYear(), today.getMonth() + 2, today.getDate());
+  return html`
+    <style>
+      .demo-calendar {
+        border: 1px solid #adadad;
+        box-shadow: 0 0 16px #ccc;
+        max-width: 500px;
+      }
+    </style>
+    <lion-calendar
+      class="demo-calendar"
+      .disableDates=${day => day.getDay() === 6 || day.getDay() === 0}
+      .minDate="${new Date()}"
+      .maxDate="${maxDate}"
+    ></lion-calendar>
+  `;
+};
+```

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

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

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

@@ -0,0 +1,40 @@
+# Checkbox Group >> Overview ||10
+
+A checkbox group enhances the functionality of the native `<input type="checkbox">` element.
+Its purpose is to provide a way for users to check **multiple** options amongst a set of choices, or to function as a single toggle.
+
+> You should use our `checkbox` elements as children in checkbox group.
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-checkbox-group.js';
+import '@lion/ui/define/lion-checkbox.js';
+```
+
+```js preview-story
+export const main = () => html`
+  <lion-checkbox-group name="scientists[]" label="Favorite scientists">
+    <lion-checkbox label="Archimedes" .choiceValue=${'Archimedes'}></lion-checkbox>
+    <lion-checkbox label="Francis Bacon" .choiceValue=${'Francis Bacon'}></lion-checkbox>
+    <lion-checkbox label="Marie Curie" .choiceValue=${'Marie Curie'}></lion-checkbox>
+  </lion-checkbox-group>
+`;
+```
+
+> Make sure that the checkbox-group also has a name attribute, this is necessary for our [form](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/components/form/overview.md)'s serialization result.
+
+## 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.
+
+## Installation
+
+```bash
+npm i --save @lion/ui
+```
+
+```js
+import '@lion/ui/define/lion-checkbox-group.js';
+import '@lion/ui/define/lion-checkbox.js';
+```

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

@@ -0,0 +1,256 @@
+# Checkbox Group >> Use Cases ||20
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-checkbox-group.js';
+import '@lion/ui/define/lion-checkbox.js';
+```
+
+## Model value
+
+The `modelValue` of a `lion-checkbox-group` is an array containing the `choiceValues` of the `lion-checkbox` elements that have been checked.
+
+Given the scientists example above, say that we were to select the first and last options
+(Archimedes & Marie Curie).
+
+Then the `modelValue` of the `lion-checkbox-group` will look as follows:
+
+```js
+const groupElement = [parent].querySelector('lion-checkbox-group');
+groupElement.modelValue;
+  => ["Archimedes", "Marie Curie"];
+```
+
+## The `name` attribute
+
+The `name` attribute of a `lion-checkbox-group` automatically gets assigned to its `lion-checkbox` children. You can also specify names for the `lion-checkbox` elements, but if this name is different from the name assigned to `lion-checkbox-group`, then an exception will be thrown.
+
+Our recommendation would be to set the `name` attribute only on the `lion-checkbox-group` and not on the `lion-checkbox` elements.
+
+## Example
+
+```html
+<lion-checkbox-group
+  name="scientists[]"
+  label="Favorite scientists"
+>
+  <lion-checkbox label="Archimedes" .choiceValue=${'Archimedes'}></lion-checkbox>
+  <lion-checkbox label="Francis Bacon" .choiceValue=${'Francis Bacon'}></lion-checkbox>
+  <lion-checkbox label="Marie Curie" .choiceValue=${'Marie Curie'}></lion-checkbox>
+</lion-checkbox-group>
+```
+
+## Pre-select
+
+You can pre-select options by targeting the `modelValue` object of the option and setting the `checked` property to `true`.
+
+```js preview-story
+export const preselect = () => html`
+  <lion-checkbox-group name="scientists" label="Favorite scientists">
+    <lion-checkbox label="Archimedes" .choiceValue=${'Archimedes'}></lion-checkbox>
+    <lion-checkbox label="Francis Bacon" .choiceValue=${'Francis Bacon'} checked></lion-checkbox>
+    <lion-checkbox
+      label="Marie Curie"
+      .modelValue=${{ value: 'Marie Curie', checked: true }}
+    ></lion-checkbox>
+  </lion-checkbox-group>
+`;
+```
+
+## Disabled
+
+You can disable the entire group by setting the `disabled` attribute on the `<lion-checkbox-group>`.
+
+```js preview-story
+export const disabled = () => html`
+  <lion-checkbox-group name="scientists[]" label="Favorite scientists" disabled>
+    <lion-checkbox label="Archimedes" .choiceValue=${'Archimedes'}></lion-checkbox>
+    <lion-checkbox label="Francis Bacon" .choiceValue=${'Francis Bacon'}></lion-checkbox>
+    <lion-checkbox
+      label="Marie Curie"
+      .modelValue=${{ value: 'Marie Curie', checked: true }}
+    ></lion-checkbox>
+  </lion-checkbox-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-checkbox-group name="scientists[]" label="Favorite scientists">
+    <lion-checkbox .choiceValue=${'Archimedes'}>
+      <label slot="label"
+        ><a href="https://wikipedia.org/wiki/Archimedes" target="_blank">Archimedes</a></label
+      >
+    </lion-checkbox>
+    <lion-checkbox .choiceValue=${'Francis Bacon'}>
+      <label slot="label"
+        ><a href="https://wikipedia.org/wiki/Francis_Bacon" target="_blank">Francis Bacon</a></label
+      >
+    </lion-checkbox>
+    <lion-checkbox .choiceValue=${'Marie Curie'}>
+      <label slot="label"
+        ><a href="https://wikipedia.org/wiki/Marie_Curie" target="_blank">Marie Curie</a></label
+      >
+    </lion-checkbox>
+  </lion-checkbox-group>
+`;
+```
+
+## Help text
+
+You can add help text on each checkbox with `help-text` attribute on the `<lion-checkbox>`.
+
+```js preview-story
+export const helpText = () => html`
+  <lion-checkbox-group name="scientists[]" label="Favorite scientists">
+    <lion-checkbox
+      label="Archimedes"
+      .choiceValue=${'Archimedes'}
+      help-text="Archimedes of Syracuse was a Greek mathematician, physicist, engineer, inventor, and astronomer"
+    ></lion-checkbox>
+    <lion-checkbox
+      label="Francis Bacon"
+      .choiceValue=${'Francis Bacon'}
+      help-text="Francis Bacon, 1st Viscount St Alban also known as Lord Verulam, was an English philosopher and statesman who served as Attorney General and as Lord Chancellor of England"
+    ></lion-checkbox>
+    <lion-checkbox
+      label="Marie Curie"
+      .choiceValue=${'Marie Curie'}
+      help-text="Marie Skłodowska Curie born Maria Salomea Skłodowska, was a Polish and naturalized-French physicist and chemist who conducted pioneering research on radioactivity"
+    ></lion-checkbox>
+  </lion-checkbox-group>
+`;
+```
+
+## Event
+
+You can listen to the `model-value-changed` event whenever the value of the checkbox group is changed.
+
+```js preview-story
+export const event = ({ shadowRoot }) => html`
+  <lion-checkbox-group
+    name="scientists[]"
+    label="Favorite scientists"
+    @model-value-changed=${ev =>
+      (ev.target.parentElement.querySelector('#selectedDinosaur').innerText = JSON.stringify(
+        ev.target.modelValue,
+        null,
+        4,
+      ))}
+  >
+    <lion-checkbox label="Archimedes" .choiceValue=${'Archimedes'}></lion-checkbox>
+    <lion-checkbox label="Francis Bacon" .choiceValue=${'Francis Bacon'}></lion-checkbox>
+    <lion-checkbox label="Marie Curie" .choiceValue=${'Marie Curie'}></lion-checkbox>
+  </lion-checkbox-group>
+  <br />
+  <span>Selected scientists: <strong id="selectedDinosaur">N/A</strong></span>
+`;
+```
+
+## Indeterminate
+
+A `checkbox-indeterminate`'s value is neither true nor false, but is instead indeterminate, meaning that its state cannot be determined or stated in pure binary terms, based on it's `checkbox` children.
+
+```js preview-story
+export const indeterminateSiblings = () => html`
+  <lion-checkbox-group name="scientists[]" label="Favorite scientists">
+    <lion-checkbox-indeterminate label="Old Greek scientists">
+      <lion-checkbox
+        slot="checkbox"
+        label="Archimedes"
+        .choiceValue=${'Archimedes'}
+      ></lion-checkbox>
+      <lion-checkbox slot="checkbox" label="Plato" .choiceValue=${'Plato'}></lion-checkbox>
+      <lion-checkbox
+        slot="checkbox"
+        label="Pythagoras"
+        .choiceValue=${'Pythagoras'}
+      ></lion-checkbox>
+    </lion-checkbox-indeterminate>
+    <lion-checkbox-indeterminate label="17th Century scientists">
+      <lion-checkbox
+        slot="checkbox"
+        label="Isaac Newton"
+        .choiceValue=${'Isaac Newton'}
+      ></lion-checkbox>
+      <lion-checkbox
+        slot="checkbox"
+        label="Galileo Galilei"
+        .choiceValue=${'Galileo Galilei'}
+      ></lion-checkbox>
+    </lion-checkbox-indeterminate>
+  </lion-checkbox-group>
+`;
+```
+
+The `checkbox-indeterminate` can have another `checkbox-indeterminate` as a child.
+
+```js preview-story
+export const indeterminateChildren = () => html`
+  <lion-checkbox-group name="scientists[]" label="Favorite scientists">
+    <lion-checkbox-indeterminate label="Scientists">
+      <lion-checkbox
+        slot="checkbox"
+        label="Isaac Newton"
+        .choiceValue=${'Isaac Newton'}
+      ></lion-checkbox>
+      <lion-checkbox
+        slot="checkbox"
+        label="Galileo Galilei"
+        .choiceValue=${'Galileo Galilei'}
+      ></lion-checkbox>
+      <lion-checkbox-indeterminate slot="checkbox" label="Old Greek scientists">
+        <lion-checkbox
+          slot="checkbox"
+          label="Archimedes"
+          .choiceValue=${'Archimedes'}
+        ></lion-checkbox>
+        <lion-checkbox slot="checkbox" label="Plato" .choiceValue=${'Plato'}></lion-checkbox>
+        <lion-checkbox
+          slot="checkbox"
+          label="Pythagoras"
+          .choiceValue=${'Pythagoras'}
+        ></lion-checkbox>
+      </lion-checkbox-indeterminate>
+    </lion-checkbox-indeterminate>
+  </lion-checkbox-group>
+`;
+```
+
+You can also use `mixed-state` attribute so your indeterminate checkbox toggles through three states (indeterminate, checked, unchecked), where for indeterminate state the old children states are restored when you toggle back into this.
+
+```js preview-story
+export const mixedState = () => html`
+  <lion-checkbox-group name="scientists[]" label="Favorite scientists">
+    <lion-checkbox-indeterminate mixed-state label="Scientists">
+      <lion-checkbox
+        slot="checkbox"
+        label="Isaac Newton"
+        .choiceValue=${'Isaac Newton'}
+      ></lion-checkbox>
+      <lion-checkbox
+        slot="checkbox"
+        label="Galileo Galilei"
+        .choiceValue=${'Galileo Galilei'}
+      ></lion-checkbox>
+      <lion-checkbox-indeterminate mixed-state slot="checkbox" label="Old Greek scientists">
+        <lion-checkbox
+          slot="checkbox"
+          label="Archimedes"
+          .choiceValue=${'Archimedes'}
+        ></lion-checkbox>
+        <lion-checkbox slot="checkbox" label="Plato" .choiceValue=${'Plato'}></lion-checkbox>
+        <lion-checkbox
+          slot="checkbox"
+          label="Pythagoras"
+          .choiceValue=${'Pythagoras'}
+        ></lion-checkbox>
+      </lion-checkbox-indeterminate>
+    </lion-checkbox-indeterminate>
+  </lion-checkbox-group>
+`;
+```

package/docs/components/collapsible/assets/CustomCollapsible.js

@@ -0,0 +1,113 @@
+import { LionCollapsible } from '@lion/ui/collapsible.js';
+
+const EVENT = {
+  TRANSITION_END: 'transitionend',
+  TRANSITION_START: 'transitionstart',
+};
+/**
+ * `CustomCollapsible` is a class for custom collapsible element (`<custom-collapsible>` web component).
+ * @customElement custom-collapsible
+ */
+// @ts-expect-error false positive for incompatible static get properties. Lit-element merges super properties already for you.
+export class CustomCollapsible extends LionCollapsible {
+  static get properties() {
+    return {
+      transitioning: {
+        type: Boolean,
+        reflect: true,
+      },
+    };
+  }
+
+  constructor() {
+    super();
+    this.transitioning = false;
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    this._contentNode?.style.setProperty(
+      'transition',
+      'max-height 0.35s, padding 0.35s, opacity 0.35s',
+    );
+    if (this.opened) {
+      this._contentNode?.style.setProperty('padding', '12px 0');
+    }
+  }
+
+  /**
+   * Wait until transition is finished.
+   * @override
+   */
+  toggle() {
+    if (!this.transitioning) {
+      super.toggle();
+    }
+  }
+
+  /**
+   * Trigger show animation and wait for transition to be finished.
+   * @param {Object} options - element node and its options
+   * @param {HTMLElement} options.contentNode
+   * @override
+   */
+  async _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 });
+  }
+
+  /**
+   * Trigger hide animation and wait for transition to be finished.
+   * @param {Object} options - element node and its options
+   * @param {HTMLElement} options.contentNode
+   * @override
+   */
+  async _hideAnimation({ contentNode }) {
+    if (this._contentHeight === '0px') {
+      return;
+    }
+    ['opacity', 'padding', 'max-height'].map(prop => contentNode.style.setProperty(prop, '0'));
+    await this._waitForTransition({ contentNode });
+  }
+
+  /**
+   *  Wait until the transition event is finished.
+   * @param {Object} options - element node and its options
+   * @param {HTMLElement} options.contentNode
+   * @returns {Promise<void>} transition event
+   */
+  _waitForTransition({ contentNode }) {
+    return new Promise(resolve => {
+      const transitionStarted = () => {
+        contentNode.removeEventListener(EVENT.TRANSITION_START, transitionStarted);
+        this.transitioning = true;
+      };
+      contentNode.addEventListener(EVENT.TRANSITION_START, transitionStarted);
+
+      const transitionEnded = () => {
+        contentNode.removeEventListener(EVENT.TRANSITION_END, transitionEnded);
+        this.transitioning = false;
+        resolve();
+      };
+      contentNode.addEventListener(EVENT.TRANSITION_END, transitionEnded);
+    });
+  }
+
+  /**
+   * Calculate total content height after collapsible opens
+   * @param {HTMLElement} contentNode content node
+   * @private
+   */
+  async __calculateHeight(contentNode) {
+    contentNode.style.setProperty('max-height', '');
+    await new Promise(resolve => requestAnimationFrame(() => resolve()));
+    return this._contentHeight; // Expected height i.e. actual size once collapsed after animation
+  }
+}
+
+customElements.define('custom-collapsible', CustomCollapsible);

package/docs/components/collapsible/assets/applyDemoCollapsibleStyles.js

@@ -0,0 +1,37 @@
+import { css } from 'lit';
+
+const applyDemoCollapsibleStyles = () => {
+  const demoCollapsibleStyles = css`
+    .demo-custom-collapsible-container {
+      padding: 16px;
+      margin: 16px;
+      border-radius: 4px;
+      width: 400px;
+      box-shadow: 0 1px 3px rgba(0, 0, 0, 0.12), 0 1px 2px rgba(0, 0, 0, 0.24);
+    }
+
+    .demo-custom-collapsible-body {
+      padding: 12px 0px;
+    }
+
+    .demo-custom-collapsible-invoker {
+      border-width: 0;
+      border-radius: 2px;
+      padding: 12px 24px;
+      box-shadow: 0 1px 3px rgba(0, 0, 0, 0.12), 0 1px 2px rgba(0, 0, 0, 0.24);
+      font-weight: bold;
+      color: #3f51b5;
+    }
+
+    .demo-custom-collapsible-state-container {
+      padding: 12px 0;
+    }
+  `;
+
+  const styleTag = document.createElement('style');
+  styleTag.setAttribute('data-demo-collapsible', '');
+  styleTag.textContent = demoCollapsibleStyles.cssText;
+  document.head.appendChild(styleTag);
+};
+
+applyDemoCollapsibleStyles();