@lion/ui 0.25.0 → 0.26.0

package/docs/fundamentals/tools/ajax/use-cases.md

@@ -1,469 +0,0 @@
----
-parts:
-  - Use Cases
-  - Ajax
-  - Tools
-title: 'Use Cases'
-eleventyNavigation:
-  key: Tools >> Ajax >> Use Cases
-  title: Use Cases
-  order: 20
-  parent: Tools >> Ajax
----
-
-# Use Cases
-
-```js script
-import { html } from '@mdjs/mdjs-preview';
-import { renderLitAsNode } from '@lion/ui/helpers.js';
-import { ajax, createCacheInterceptors } from '@lion/ajax';
-import '@lion/ui/define-helpers/sb-action-logger.js';
-
-const getCacheIdentifier = () => {
-  let userId = localStorage.getItem('lion-ajax-cache-demo-user-id');
-  if (!userId) {
-    localStorage.setItem('lion-ajax-cache-demo-user-id', '1');
-    userId = '1';
-  }
-  return userId;
-};
-
-const TEN_MINUTES = 1000 * 60 * 10; // in milliseconds
-
-const cacheOptions = {
-  useCache: true,
-  maxAge: TEN_MINUTES,
-};
-
-const { cacheRequestInterceptor, cacheResponseInterceptor } = createCacheInterceptors(
-  getCacheIdentifier,
-  cacheOptions,
-);
-
-ajax.addRequestInterceptor(cacheRequestInterceptor);
-ajax.addResponseInterceptor(cacheResponseInterceptor);
-```
-
-## GET request
-
-```js preview-story
-export const getRequest = () => {
-  const actionLogger = renderLitAsNode(html`<sb-action-logger></sb-action-logger>`);
-
-  const fetchHandler = name => {
-    ajax
-      .fetch(`../assets/${name}.json`)
-      .then(response => response.json())
-      .then(result => {
-        actionLogger.log(JSON.stringify(result, null, 2));
-      });
-  };
-
-  return html`
-    <style>
-      sb-action-logger {
-        --sb-action-logger-max-height: 300px;
-      }
-    </style>
-    <button @click="${() => fetchHandler('pabu')}">Fetch Pabu</button>
-    <button @click="${() => fetchHandler('naga')}">Fetch Naga</button>
-    ${actionLogger}
-  `;
-};
-```
-
-## POST request
-
-```js
-import { ajax } from '@lion/ajax';
-
-const response = await ajax.fetch('/api/users', {
-  method: 'POST',
-  body: JSON.stringify({ username: 'steve' }),
-});
-
-const newUser = await response.json();
-```
-
-### JSON requests
-
-We usually deal with JSON requests and responses. `ajax.fetchJson` supports JSON by:
-
-- Serializing request body as JSON
-- Deserializing response payload as JSON
-- Adding the correct Content-Type and Accept headers
-
-> Note that, the result will have the Response object on `.response` property, and the parsed JSON will be available on `.body`.
-
-## GET JSON request
-
-```js preview-story
-export const getJsonRequest = () => {
-  const actionLogger = renderLitAsNode(html`<sb-action-logger></sb-action-logger>`);
-
-  const fetchHandler = name => {
-    ajax.fetchJson(`../assets/${name}.json`).then(result => {
-      console.log(result.response);
-      actionLogger.log(JSON.stringify(result.body, null, 2));
-    });
-  };
-
-  return html`
-    <style>
-      sb-action-logger {
-        --sb-action-logger-max-height: 300px;
-      }
-    </style>
-    <button @click="${() => fetchHandler('pabu')}">Fetch Pabu</button>
-    <button @click="${() => fetchHandler('naga')}">Fetch Naga</button>
-    ${actionLogger}
-  `;
-};
-```
-
-## POST JSON request
-
-```js
-import { ajax } from '@lion/ajax';
-
-const { response, body } = await ajax.fetchJson('/api/users', {
-  method: 'POST',
-  body: { username: 'steve' },
-});
-```
-
-### Error handling
-
-Different from fetch, `Ajax` throws when the server returns a 4xx or 5xx, returning the request and response:
-
-```js preview-story
-export const errorHandling = () => {
-  const actionLogger = renderLitAsNode(html`<sb-action-logger></sb-action-logger>`);
-
-  const fetchHandler = async () => {
-    try {
-      const users = await ajax.fetchJson('/api/users');
-    } catch (error) {
-      if (error.response) {
-        if (error.response.status === 400) {
-          // handle a specific status code, for example 400 bad request
-        } else {
-          actionLogger.log(error);
-        }
-      } else {
-        // an error happened before receiving a response,
-        // Example: an incorrect request or network error
-        actionLogger.log(error);
-      }
-    }
-  };
-
-  return html`
-    <style>
-      sb-action-logger {
-        --sb-action-logger-max-height: 300px;
-      }
-    </style>
-    <button @click="${fetchHandler}">Fetch</button>
-    ${actionLogger}
-  `;
-};
-```
-
-## Fetch Polyfill
-
-For IE11 you will need a polyfill for fetch. You should add this on your top level layer, e.g. your application.
-
-[This is the polyfill we recommend](https://github.com/github/fetch). It also has a [section for polyfilling AbortController](https://github.com/github/fetch#aborting-requests)
-
-## Ajax Caching Support
-
-Ajax package provides in-memory cache support through interceptors. And cache interceptors can be added manually or by configuring the Ajax instance.
-
-The cache request interceptor and cache response interceptor are designed to work together to support caching of network requests/responses.
-
-> The **request interceptor** checks whether the response for this particular request is cached, and if so returns the cached response.
-> And the **response interceptor** caches the response for this particular request.
-
-### Getting started
-
-Consume the global `ajax` instance and add interceptors to it, using a cache configuration which is applied on application level. If a developer wants to add specifics to cache behaviour they have to provide a cache config per action (`get`, `post`, etc.) via `cacheOptions` field of local ajax config,
-see examples below.
-
-> **Note**: make sure to add the **interceptors** only **once**. This is usually done on app-level
-
-```js
-import { ajax, createCacheInterceptors } from '@lion-web/ajax';
-
-const globalCacheOptions = {
-  useCache: true,
-  maxAge: 1000 * 60 * 5, // 5 minutes
-};
-
-// Cache is removed each time an identifier changes,
-// for instance when a current user is logged out
-const getCacheIdentifier = () => getActiveProfile().profileId;
-
-const { cacheRequestInterceptor, cacheResponseInterceptor } = createCacheInterceptors(
-  getCacheIdentifier,
-  globalCacheOptions,
-);
-
-ajax.addRequestInterceptor(cacheRequestInterceptor);
-ajax.addResponseInterceptor(cacheResponseInterceptor);
-
-const { response, body } = await ajax.fetchJson('/my-url');
-```
-
-Alternatively, most often for sub-classers, you can extend or import `Ajax` yourself, and pass cacheOptions when instantiating the ajax.
-
-```js
-import { Ajax } from '@lion/ajax';
-
-export const ajax = new Ajax({
-  cacheOptions: {
-    useCache: true,
-    maxAge: 1000 * 60 * 5, // 5 minutes
-    getCacheIdentifier: () => getActiveProfile().profileId,
-  },
-});
-```
-
-### Ajax cache example
-
-> Let's assume that we have a user session, for this demo purposes we already created an identifier function for this and set the cache interceptors.
-
-We can see if a response is served from the cache by checking the `response.fromCache` property, which is either undefined for normal requests, or set to true for responses that were served from cache.
-
-```js preview-story
-export const cache = () => {
-  const actionLogger = renderLitAsNode(html`<sb-action-logger></sb-action-logger>`);
-
-  const fetchHandler = name => {
-    ajax.fetchJson(`../assets/${name}.json`).then(result => {
-      actionLogger.log(`From cache: ${result.response.fromCache || false}`);
-      actionLogger.log(JSON.stringify(result.body, null, 2));
-    });
-  };
-
-  return html`
-    <style>
-      sb-action-logger {
-        --sb-action-logger-max-height: 300px;
-      }
-    </style>
-    <button @click="${() => fetchHandler('pabu')}">Fetch Pabu</button>
-    <button @click="${() => fetchHandler('naga')}">Fetch Naga</button>
-    ${actionLogger}
-  `;
-};
-```
-
-You can also change the cache options per request, which is handy if you don't want to remove and re-add the interceptors for a simple configuration change.
-
-In this demo, when we fetch naga, we always pass `useCache: false` so the Response is never a cached one.
-
-```js preview-story
-export const cacheActionOptions = () => {
-  const actionLogger = renderLitAsNode(html`<sb-action-logger></sb-action-logger>`);
-
-  const fetchHandler = name => {
-    let actionCacheOptions;
-    if (name === 'naga') {
-      actionCacheOptions = {
-        useCache: false,
-      };
-    }
-
-    ajax.fetchJson(`../assets/${name}.json`, { cacheOptions: actionCacheOptions }).then(result => {
-      actionLogger.log(`From cache: ${result.response.fromCache || false}`);
-      actionLogger.log(JSON.stringify(result.body, null, 2));
-    });
-  };
-
-  return html`
-    <style>
-      sb-action-logger {
-        --sb-action-logger-max-height: 300px;
-      }
-    </style>
-    <button @click="${() => fetchHandler('pabu')}">Fetch Pabu</button>
-    <button @click="${() => fetchHandler('naga')}">Fetch Naga</button>
-    ${actionLogger}
-  `;
-};
-```
-
-### Invalidating cache
-
-Invalidating the cache, or cache busting, can be done in multiple ways:
-
-- Going past the `maxAge` of the cache object
-- Changing cache identifier (e.g. user session or active profile changes)
-- Doing a non GET request to the cached endpoint
-  - Invalidates the cache of that endpoint
-  - Invalidates the cache of all other endpoints matching `invalidatesUrls` and `invalidateUrlsRegex`
-
-## maxAge
-
-In this demo we pass a maxAge of three seconds.
-Try clicking the fetch button and watch fromCache change whenever maxAge expires.
-
-After maxAge expires, the next request will set the cache again, and for the next 3 seconds you will get cached responses for subsequent requests.
-
-```js preview-story
-export const cacheMaxAge = () => {
-  const actionLogger = renderLitAsNode(html`<sb-action-logger></sb-action-logger>`);
-
-  const fetchHandler = () => {
-    ajax
-      .fetchJson(`../assets/pabu.json`, {
-        cacheOptions: {
-          maxAge: 1000 * 3, // 3 seconds
-        },
-      })
-      .then(result => {
-        actionLogger.log(`From cache: ${result.response.fromCache || false}`);
-        actionLogger.log(JSON.stringify(result.body, null, 2));
-      });
-  };
-
-  return html`
-    <style>
-      sb-action-logger {
-        --sb-action-logger-max-height: 300px;
-      }
-    </style>
-    <button @click="${fetchHandler}">Fetch Pabu</button>
-    ${actionLogger}
-  `;
-};
-```
-
-## Changing cache identifier
-
-For this demo we use localStorage to set a user id to `'1'`.
-
-Now we will allow you to change this identifier to invalidate the cache.
-
-```js preview-story
-export const changeCacheIdentifier = () => {
-  const actionLogger = renderLitAsNode(html`<sb-action-logger></sb-action-logger>`);
-
-  const fetchHandler = () => {
-    ajax.fetchJson(`../assets/pabu.json`).then(result => {
-      actionLogger.log(`From cache: ${result.response.fromCache || false}`);
-      actionLogger.log(JSON.stringify(result.body, null, 2));
-    });
-  };
-
-  const changeUserHandler = () => {
-    const currentUser = parseInt(localStorage.getItem('lion-ajax-cache-demo-user-id'), 10);
-    localStorage.setItem('lion-ajax-cache-demo-user-id', `${currentUser + 1}`);
-  };
-
-  return html`
-    <style>
-      sb-action-logger {
-        --sb-action-logger-max-height: 300px;
-      }
-    </style>
-    <button @click="${fetchHandler}">Fetch Pabu</button>
-    <button @click="${changeUserHandler}">Change user</button>
-    ${actionLogger}
-  `;
-};
-```
-
-## Non-GET request
-
-In this demo we show that by doing a PATCH request, you invalidate the cache of the endpoint for subsequent GET requests.
-
-Try clicking the GET pabu button twice so you see a cached response.
-Then click the PATCH pabu button, followed by another GET, and you will see that this one is not served from cache, because the PATCH invalidated it.
-
-The rationale is that if a user does a non-GET request to an endpoint, it will make the client-side caching of this endpoint outdated.
-This is because non-GET requests usually in some way mutate the state of the database through interacting with this endpoint.
-Therefore, we invalidate the cache, so the user gets the latest state from the database on the next GET request.
-
-> Ignore the browser errors when clicking PATCH buttons, JSON files (our mock database) don't accept PATCH requests.
-
-```js preview-story
-export const nonGETRequest = () => {
-  const actionLogger = renderLitAsNode(html`<sb-action-logger></sb-action-logger>`);
-
-  const fetchHandler = (name, method) => {
-    ajax.fetchJson(`../assets/${name}.json`, { method }).then(result => {
-      actionLogger.log(`From cache: ${result.response.fromCache || false}`);
-      actionLogger.log(JSON.stringify(result.body, null, 2));
-    });
-  };
-
-  return html`
-    <style>
-      sb-action-logger {
-        --sb-action-logger-max-height: 300px;
-      }
-    </style>
-    <button @click="${() => fetchHandler('pabu', 'GET')}">GET Pabu</button>
-    <button @click="${() => fetchHandler('pabu', 'PATCH')}">PATCH Pabu</button>
-    <button @click="${() => fetchHandler('naga', 'GET')}">GET Naga</button>
-    <button @click="${() => fetchHandler('naga', 'PATCH')}">PATCH Naga</button>
-    ${actionLogger}
-  `;
-};
-```
-
-## Invalidate Rules
-
-There are two kinds of invalidate rules:
-
-- `invalidateUrls` (array of URL like strings)
-- `invalidateUrlsRegex` (RegExp)
-
-If a non-GET method is fired, by default it only invalidates its own endpoint.
-Invalidating `/api/users` cache by doing a PATCH, will not invalidate `/api/accounts` cache.
-
-However, in the case of users and accounts, they may be very interconnected, so perhaps you do want to invalidate `/api/accounts` when invalidating `/api/users`.
-
-This is what the invalidate rules are for.
-
-In this demo, invalidating the `pabu` endpoint will invalidate `naga`, but not the other way around.
-
-> For invalidateUrls you need the full URL e.g. `<protocol>://<domain>:<port>/<url>` so it's often easier to use invalidateUrlsRegex
-
-```js preview-story
-export const invalidateRules = () => {
-  const actionLogger = renderLitAsNode(html`<sb-action-logger></sb-action-logger>`);
-
-  const fetchHandler = (name, method) => {
-    const actionCacheOptions = {};
-    if (name === 'pabu') {
-      actionCacheOptions.invalidateUrlsRegex = /\/docs\/tools\/ajax\/assets\/naga.json/;
-    }
-
-    ajax
-      .fetchJson(`../assets/${name}.json`, {
-        method,
-        cacheOptions: actionCacheOptions,
-      })
-      .then(result => {
-        actionLogger.log(`From cache: ${result.response.fromCache || false}`);
-        actionLogger.log(JSON.stringify(result.body, null, 2));
-      });
-  };
-
-  return html`
-    <style>
-      sb-action-logger {
-        --sb-action-logger-max-height: 300px;
-      }
-    </style>
-    <button @click="${() => fetchHandler('pabu', 'GET')}">GET Pabu</button>
-    <button @click="${() => fetchHandler('pabu', 'PATCH')}">PATCH Pabu</button>
-    <button @click="${() => fetchHandler('naga', 'GET')}">GET Naga</button>
-    <button @click="${() => fetchHandler('naga', 'PATCH')}">PATCH Naga</button>
-    ${actionLogger}
-  `;
-};
-```

package/docs/fundamentals/tools/helpers/action-logger.md

@@ -1,175 +0,0 @@
----
-parts:
-  - Action Logger
-  - Helpers
-  - Tools
-title: 'Action Logger'
-eleventyNavigation:
-  key: Tools >> Helpers >> Action Logger
-  title: Action Logger
-  order: 20
-  parent: Tools >> Helpers
----
-
-# Action Logger
-
-A visual element to show action logs in demos `sb-action-logger`
-
-```js script
-import { html } from '@mdjs/mdjs-preview';
-import '@lion/ui/define-helpers/sb-action-logger.js';
-```
-
-```js preview-story
-export const main = () => {
-  const uid = Math.random().toString(36).substr(2, 10);
-  return html`
-    <p>To log: <code>Hello, World!</code></p>
-    <button
-      @click=${e => {
-        e.target.parentElement.querySelector(`#logger-${uid}`).log('Hello, World!');
-      }}
-    >
-      Click this button
-    </button>
-    <p>Or to log: <code>What's up, Planet!</code></p>
-    <button
-      @click=${e => {
-        e.target.parentElement.querySelector(`#logger-${uid}`).log(`What's up, Planet!`);
-      }}
-    >
-      Click this button
-    </button>
-    <sb-action-logger id="logger-${uid}"></sb-action-logger>
-  `;
-};
-```
-
-You need some reference to your logger. Above example shows this by using a unique ID.
-
-```js
-const uid = Math.random().toString(36).substr(2, 10);
-```
-
-This connects the logger element to the trigger.
-
-```jsx
-<div>To log: <code>Hello, World!</code></div>
-<button @click="${e => { e.target.parentElement.querySelector('#logger-${uid}').log('Hello, World!') }}">Click this button
-</button>
-<sb-action-logger id="logger-${uid}"></sb-action-logger>
-```
-
-**This is a demonstrative tool**, not a debugging tool (although it may help initially).
-If you try logging complex values such as arrays, objects or promises,
-you should expect to get only the string interpretation as the output in this logger.
-
-## Features:
-
-- A public method `log` to log things to the action logger.
-- Overridable `title` property.
-- Clear button to clear logs
-- A counter to count the total amount of logs
-- Stacks consecutive duplicate logs and shows a counter
-- `simple` property/attribute to only show a single log
-
-## Installation
-
-```bash
-npm i @lion/helpers
-
-```
-
-## Variations
-
-### Simple mode
-
-Simple mode essentially means there is only ever 1 log.
-Duplicates are not counted or stacked, but you will still see the visual cue.
-
-```js preview-story
-export const simpleMode = () => {
-  const uid = Math.random().toString(36).substr(2, 10);
-  return html`
-    <div>To log: <code>Hello, World!</code></div>
-    <button
-      @click=${e => {
-        e.target.parentElement.querySelector(`#logger-${uid}`).log('Hello, World!');
-      }}
-    >
-      Click this button
-    </button>
-    <div>Or to log: <code>What's up, Planet!</code></div>
-    <button
-      @click=${e => {
-        e.target.parentElement.querySelector(`#logger-${uid}`).log(`What's up, Planet!`);
-      }}
-    >
-      Click this button
-    </button>
-    <sb-action-logger simple id="logger-${uid}"></sb-action-logger>
-  `;
-};
-```
-
-```html
-<sb-action-logger simple></sb-action-logger>
-```
-
-### Custom Title
-
-You can customize the action logger title with the `.title` property.
-
-```js preview-story
-export const customTitle = () => {
-  const uid = Math.random().toString(36).substr(2, 10);
-  return html`
-    <button
-      @click="${e => e.target.parentElement.querySelector(`#logger-${uid}`).log('Hello, World!')}"
-    >
-      Log
-    </button>
-    <sb-action-logger id="logger-${uid}" .title="${'Hello World'}"></sb-action-logger>
-  `;
-};
-```
-
-```html
-<sb-action-logger .title="${'Hello World'}"></sb-action-logger>
-```
-
-## Rationale
-
-This component was created due to a need for a nice visual action logger in Storybook Docs mode.
-
-In docs mode, you do not have access to the action logger addon component, and it is nice to be able to show actions inline in your demos and documentation.
-
-### Opinionated
-
-I added quite a bit of styling on this component to make it look decent.
-There are a bunch of styles that you can easily override to make it fit your design system which I believe should be enough in most cases.
-If you need more control you can always:
-
-- Override the host styles, there's a few custom CSS props that you can override as well.
-- Extend the component and apply your overrides
-- Open an issue if you believe it would be good to make something more flexible / configurable
-
-Maybe in the future I will abstract this component to a more generic (ugly) one with no styles, so it's more friendly as a shared component.
-
-### Plugin
-
-If you use an action logger inside your Story in Storybook, you will also see it in your canvas, and this may not be your intention.
-
-One idea is to simplify the usage further by making this a Storybook (docs-)plugin or decorator or whatever.
-It would be cool if someone can simply enable an action logger option on a particular Story inside their .mdx,
-and then actions are automatically logged to the visual logger below it.
-Would need to figure out how to catch the action and pass it to the visual logger element.
-
-Isn't investigated yet on the how, but that is the rough idea.
-
-## Future
-
-New planned features can be found in the test folder where they are specified as skipped tests.
-If the feature you'd like is not in the tests, feel free to make an issue so we can add it.
-
-See our [CONTRIBUTING.md](https://github.com/ing-bank/lion/blob/master/CONTRIBUTING.md) for more guidelines on how to contribute.

package/docs/fundamentals/tools/helpers/index.md

@@ -1,15 +0,0 @@
----
-parts:
-  - Helpers
-  - Tools
-title: 'Helpers'
-eleventyNavigation:
-  key: Tools >> Helpers
-  title: Helpers
-  order: 5
-  parent: Tools
----
-
-# Helpers
-
--> go to Overview

package/docs/fundamentals/tools/helpers/overview.md

@@ -1,43 +0,0 @@
----
-parts:
-  - Overview
-  - Helpers
-  - Tools
-title: 'Overview'
-eleventyNavigation:
-  key: Tools >> Helpers >> Overview
-  title: Overview
-  order: 10
-  parent: Tools >> Helpers
----
-
-# Overview
-
-A helpers package that contains several helpers that are used inside lion but can be used outside as well.
-
-These helpers are considered developer tools, not actual things to use in production.
-Therefore, they may not have the same quality standards as our other packages.
-
-## Packages
-
-| Package                                | Description             |
-| -------------------------------------- | ----------------------- |
-| [sb-action-logger](https://github.com/ing-bank/lion/blob/9575386e5fb419f7dbd3b893be4c4ce7925bcb2e/docs/fundamentals/tools/helpers/action-logger.md) | Storybook action logger |
-
-## Installation
-
-```bash
-npm i @lion/helpers
-```
-
-## Usage
-
-Example using the sb-action-logger helper component.
-
-```html
-<script type="module">
-  import '@lion/ui/define-helpers/sb-action-logger.js';
-</script>
-
-<sb-action-logger></sb-action-logger>
-```