@lion/ui 0.0.1 → 0.0.3

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

@@ -0,0 +1,165 @@
+# Tools >> Helpers >> Action Logger ||20
+
+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.
+
+```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>
+<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

@@ -0,0 +1,3 @@
+# Tools >> Helpers
+
+-> go to Overview

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

@@ -0,0 +1,30 @@
+# Tools >> Helpers >> Overview ||10
+
+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/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/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>
+```

package/docs/fundamentals/tools/index.md

@@ -0,0 +1 @@
+# Tools ||20

package/docs/fundamentals/tools/singleton-manager/index.md

@@ -0,0 +1,3 @@
+# Tools >> Singleton Manager ||20
+
+-> go to Overview

package/docs/fundamentals/tools/singleton-manager/overview.md

@@ -0,0 +1,304 @@
+# Tools >> Singleton Manager >> Overview ||10
+
+A singleton manager provides a way to make sure a singleton instance loaded from multiple file locations stays a singleton.
+Primarily useful if two major version of a package with a singleton is used.
+
+## Installation
+
+```bash
+npm i --save singleton-manager
+```
+
+⚠️ You need to make SURE that only ONE version of `singleton-manager` is installed. For how see [Non Goals](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/tools/singleton-manager/#non-goals).
+
+### Example Singleton Users
+
+Use the same singleton for both versions (as we don't use any of the breaking features)
+
+```js
+// managed-my-singleton.js
+import { singletonManager } from 'singleton-manager';
+import { mySingleton } from 'my-singleton'; // is available as 1.x and 2.x via node resolution
+
+singletonManager.set('my-singleton::index.js::1.x', mySingleton);
+singletonManager.set('my-singleton::index.js::2.x', mySingleton);
+```
+
+OR create a special compatible version of the singleton
+
+```js
+// managed-my-singleton.js
+import { singletonManager } from 'singleton-manager';
+import { MySingleton } from 'my-singleton'; // is available as 1.x and 2.x via node resolution
+
+class CompatibleSingleton extends MySingleton {
+  // add forward or backward compatibility code
+}
+const compatibleSingleton = new CompatibleSingleton();
+
+singletonManager.set('my-singleton::index.js::1.x', compatibleSingleton);
+singletonManager.set('my-singleton::index.js::2.x', compatibleSingleton);
+```
+
+AND in you App then you need to load the above code BEFORE loading the singleton or any feature using it.
+
+```js
+import './managed-my-singleton.js';
+
+import { mySingleton } from 'my-singleton'; // will no always be what is "defined" in managed-my-singleton.js
+```
+
+### Warning
+
+Overriding version is an App level concern hence components or "features" are not allowed to use it.
+If you try to call it multiple times for the same key then it will be ignored.
+
+```js
+// on app level
+singletonManager.set('my-singleton/index.js::1.x', compatibleSingleton);
+
+// somewhere in a dependency
+singletonManager.set('my-singleton/index.js::1.x', otherSingleton);
+
+// .get('my-singleton/index.js::1.x') will always return the first set value
+// e.g. the app can set it and no one can later override it
+```
+
+### Example Singleton Maintainers
+
+If you are a maintainer of a singleton be sure to check if a singleton manager version is set.
+If that is the case return it instead of your default instance.
+
+It could look something like this:
+
+```js
+// my-singleton.js
+import { singletonManager } from 'singleton-manager';
+import { MySingleton } from './src/MySingleton.js';
+
+export const overlays =
+  singletonManager.get('my-singleton/my-singleton.js::1.x') || new MySingleton();
+```
+
+## Convention Singleton Key
+
+The key for a singleton needs to be "unique" for the package.
+Hence the following convention helps maintaining this.
+
+As a key use the `<package>::<unique-variable>::<semver-range>`.
+
+Examples Do:
+
+- `overlays::overlays::1.x` - instance created in index.js
+- `@scope/overlays::overlays::1.x` - with scope
+- `overlays::overlays::1.x` - version 1.x.x (> 1.0.0 you do 1.x, 2.x)
+- `overlays::overlays::2.x` - version 2.x.x (> 1.0.0 you do 1.x, 2.x)
+- `overlays::overlays::0.10.x` - version 0.10.x (< 1.0.0 you do 0.1.x, 0.2.x)
+
+Examples Don't:
+
+- `overlays` - too generic
+- `overlays::overlays` - you should include a version
+- `overlays::1.x` - you should include a package name & unique var
+- `./index.js::1.x` - it should start with a package name
+
+---
+
+## Singleton Manager Rationale
+
+We have an app with 2 pages.
+
+- page-a uses overlays 1.x
+- page-b uses overlays 2.x (gets installed nested)
+
+```markdown
+my-app (node_modules)
+├── overlays (1.x)
+├── page-a
+│ └── page-a.js
+└── page-b
+├── node_modules
+│ └── overlays (2.x)
+└── page-b.js
+```
+
+The tough part in this case is the OverlaysManager within the overlays package as it needs to be a singleton.
+
+It starts of simplified like this
+
+```js
+export class OverlaysManager {
+  name = 'OverlayManager 1.x';
+  blockBody = false;
+  constructor() {
+    this._setupBlocker();
+  }
+  _setupBlocker() {
+    /* ... */
+  }
+  block() {
+    this.blockBody = true; // ...
+  }
+
+  unBlock() {
+    this.blockBody = false; // ...
+  }
+}
+```
+
+## Example A (fail)
+
+See it "fail" e.g. 2 separate OverlaysManager are at work and are "fighting" over the way to block the body.
+
+```bash
+npm run start:fail
+```
+
+Steps to reproduce:
+
+1. Page A click on block
+2. Page B => "Blocked: false" (even when hitting the refresh button)
+
+➡️ See [it on the example page](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/tools/singleton-manager/example-fail/index.md). <br>
+➡️ See [the code](https://github.com/ing-bank/lion/tree/master/docs/fundamentals/tools/singleton-manager/example-fail/demo-app.js).
+
+---
+
+## Example B (singleton manager)
+
+The breaking change in `OverlayManager` was renaming of 2 function (which has been deprecated before).
+
+- `block()` => `blockingBody()`
+- `unBlock()` => `unBlockingBody()`
+
+knowing that we can create a Manager that is compatible with both via
+
+```js
+import { OverlaysManager } from 'overlays';
+
+class CompatibleOverlaysManager extends OverlaysManager {
+  blockingBody() {
+    this.block();
+  }
+  unBlockingBody() {
+    this.unBlock();
+  }
+}
+```
+
+all that is left is a to "override" the default instance of the "users"
+
+```js
+import { singletonManager } from 'singleton-manager';
+
+const compatibleOverlaysManager = new CompatibleOverlaysManager();
+singletonManager.set('overlays::overlays::1.x', compatibleOverlaysManager);
+singletonManager.set('overlays::overlays::2.x', compatibleOverlaysManager);
+```
+
+See it in action
+
+```bash
+npm run start:singleton
+```
+
+➡️ See [it on the example page](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/tools/singleton-manager/example-success/index.md). <br>
+➡️ See [the code](https://github.com/ing-bank/lion/tree/master/docs/fundamentals/tools/singleton-manager/example-success/demo-app.js).
+
+---
+
+## Example C (singleton and complex patching on app level)
+
+The breaking change in `OverlayManager` was converting a property to a function and a rename of a function.
+
+- `blockBody` => `_blockBody`
+- `block()` => `blockBody()`
+- `unBlock()` => `unBlockBody()`
+
+e.g. what is impossible to make compatible with a single instance is to have `blockBody` act as a property for 1.x and as a function `blockBody()` for 2.x.
+
+So how do we solve it then?
+
+We will make 2 separate instances of the `OverlayManager`.
+
+```js
+compatibleManager1 = new CompatibleManager1(); // 1.x
+compatibleManager2 = new CompatibleManager2(); // 2.x
+console.log(typeof compatibleManager1.blockBody); // Boolean
+console.log(typeof compatibleManager2.blockBody); // Function
+
+// and override
+singletonManager.set('overlays::overlays::1.x', compatibleManager1);
+singletonManager.set('overlays::overlays::2.x', compatibleManager2);
+```
+
+and they are "compatible" to each other because they sync the important data to each other.
+e.g. even though there are 2 instances there is only `one` dom element inserted which both can write to.
+When syncing data only the initiator will update the dom.
+This makes sure even though functions and data is separate it will be always consistent.
+
+See it in action
+
+```bash
+npm run start:singleton-complex
+```
+
+➡️ See [it on the example page](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/tools/singleton-manager/example-complex/index.md). <br>
+➡️ See [the code](https://github.com/ing-bank/lion/tree/master/docs/fundamentals/tools/singleton-manager/example-complex/demo-app.js).
+
+---
+
+## How does it work?
+
+As a user you can override what the import of `overlays/instance.js` provides.
+You do this via a singletonManager and a "magic" string.
+
+- Reason be that you can target ranges of versions
+
+```js
+singletonManager.set('overlays::overlays::1.x', compatibleManager1);
+singletonManager.set('overlays::overlays::2.x', compatibleManager2);
+```
+
+### Potential Improvements
+
+Potentially we could have "range", "exacts version" and symbol for unique filename.
+So you can override with increasing specificity.
+If you have a use case for that please open an issue.
+
+## Non Goals
+
+Making sure that there are only 2 major versions of a specific packages.
+npm is not meant to handle it - and it never will
+
+```markdown
+my-app
+├─┬ feat-a@x
+│ └── foo@2.x
+├─┬ feat-a@x
+│ └── foo@2.x
+└── foo@1.x
+```
+
+Dedupe works by moving dependencies up the tree
+
+```markdown
+// this app
+my-app
+my-app/node_modules/feat-a/node_modules/foo
+my-app/node_modules/foo
+
+// can become if versions match
+my-app
+my-app/node_modules/foo
+```
+
+in there `feat-a` will grab the version of it's "parent" because of the node resolution system.
+If however the versions do not match or there is no "common" folder to move it up to then it needs to be "duplicated" by npm/yarn.
+
+Only by using a more controlled way like
+
+- [import-maps](https://github.com/WICG/import-maps)
+- [yarn resolutions](https://classic.yarnpkg.com/en/docs/selective-version-resolutions/)
+
+you can "hard" code it to the same versions.