@lion/ui 0.0.2 → 0.0.4

package/docs/fundamentals/node-tools/rocket-preset-extend-lion-docs/overview.md

@@ -0,0 +1,285 @@
+# Node Tools >> Extend Docs >> Overview ||10
+
+When maintaining your own extension layer of lion you most likely want to maintain a similar documentation.
+Copying and rewriting imports/tags the markdown files works but also means that whenever something change you need copy and rewrite again.
+
+To do this automatically you can use this preset for [rocket](https://rocket.modern-web.dev/).
+
+## Features
+
+- Import lion documentation and adjust it using [remark-extend](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/fundamentals/node-tools/remark-extend/overview.md)
+- Renames named imports and all it's usage
+- Adjusts import paths
+- Replace tags in template literals
+
+## Installation
+
+```bash
+npm i -D rocket-preset-extend-lion-docs
+```
+
+👉 _rocket.config.js_
+
+```js
+import { rocketLaunch } from '@rocket/launch';
+import { extendLionDocs } from 'rocket-preset-extend-lion-docs';
+
+const extendLionDocsInstance = await extendLionDocs({
+  classPrefix: 'Wolf',
+  classBareImport: '@wolf/',
+  tagPrefix: 'wolf-',
+  tagBareImport: '@wolf/',
+});
+
+export default {
+  presets: [rocketLaunch(), extendLionDocsInstance],
+};
+```
+
+## Reusing documentation
+
+To take an existing documentation you can "import" it using [remark-extend](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/fundamentals/node-tools/remark-extend/overview.md).
+
+As an example you can create `docs/components/tabs/overview.md`.
+
+In it you do
+
+- write a headline
+- use importSmallBlockContent to reuse content from lion
+- add your own installation instruction
+
+````md
+# Tabs >> Overview ||10
+
+```js ::importSmallBlockContent('@lion/ui/tabs/docs/overview.md', '# Tabs >> Overview ||10.js')
+
+```
+
+## Installation
+
+```bash
+npm i --save @wolf/tabs
+```
+
+```js
+import { WolfTabs } from '@wolf/tabs';
+```
+````
+
+## How does it work
+
+1. `importSmallBlockContent`` will import the content from lion
+2. all code blocks will then be precessed to use `@wolf` instead of `@lion`
+3. all links which are absolute to github will be processed to be local links
+
+as an example this is a part of the lion docs for tabs
+
+````md
+```js script
+import { LitElement, html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-tabs.js';
+```
+
+```js preview-story
+export const main = () => html`
+  <lion-tabs>
+    <button slot="tab">Info</button>
+    <p slot="panel">Info page with lots of information about us.</p>
+    <button slot="tab">Work</button>
+    <p slot="panel">Work page that showcases our work.</p>
+  </lion-tabs>
+`;
+```
+````
+
+After all replacements the output that will be used for markdown rendering will be
+
+````md
+# Tabs >> Overview ||10
+
+```js script
+import { LitElement, html } from '@wolf/core';
+import '@wolf/tabs/define';
+```
+
+```js preview-story
+export const main = () => html`
+  <wolf-tabs>
+    <button slot="tab">Info</button>
+    <p slot="panel">Info page with lots of information about us.</p>
+    <button slot="tab">Work</button>
+    <p slot="panel">Work page that showcases our work.</p>
+  </wolf-tabs>
+`;
+```
+
+## Installation
+
+```bash
+npm i --save @wolf/tabs
+```
+
+```js
+import { WolfTabs } from '@wolf/tabs';
+```
+````
+
+Doing so means you can focus on writing what is specific to your design system extension and you don't need to rewrite all the examples and explanations of lion but you can import them while still using your components.
+
+## Use with a monorepo
+
+The above setup assumes that you have the same "system" of exports in `@wolf` as we have in `@lion`.
+
+So your users are able to do
+
+```js
+// provide classes as side effect free imports
+import { WolfTabs } from '@wolf/tabs';
+// register web components via `/define`
+import '@wolf/tabs/define';
+```
+
+This means you need to have to define the following package entry points for you tabs extension.
+
+👉 _tabs/package.json_
+
+```json
+"exports": {
+  ".": "./src/index.js",
+  "./define": "./src/define/tabs.js",
+}
+```
+
+## Use as a single repo
+
+Often its easier for your users to have one package to work with instead of a big list of individual packages.
+If you are distributing one package then your exports/imports will be different.
+
+So your users are able to do
+
+```js
+// provide classes as side effect free imports
+import { WolfTabs } from 'wolf-web/tabs';
+// register web components via `/define`
+import 'wolf-web/tabs/define';
+```
+
+👉 _package.json_
+
+```json
+"exports": {
+  ".": "./index.js",
+  "./tabs/define": "./define/tabs.js",
+}
+```
+
+The configuration for that is
+
+👉 _rocket.config.js_
+
+```js
+import { rocketLaunch } from '@rocket/launch';
+import { extendLionDocs } from 'rocket-preset-extend-lion-docs';
+
+const extendLionDocsInstance = await extendLionDocs({
+  classPrefix: 'Wolf',
+  classBareImport: 'wolf-web/',
+  tagPrefix: 'wolf-',
+  tagBareImport: 'wolf-web/',
+});
+
+export default {
+  presets: [rocketLaunch(), extendLionDocsInstance],
+};
+```
+
+## Do not distribute side effects
+
+When distributing you may choose to stay side effect free. This means no definitions of custom elements. You may want to do this to "force" usage of a scoped registry in order to support multiple mayor version of a component in a single application. We would recommend [Scoped Elements](https://open-wc.org/docs/development/scoped-elements/) for that.
+
+So your users are able to do
+
+```js
+// provide classes as side effect free imports
+import { WolfTabs } from 'wolf-web/tabs';
+// NOTE: there no way to import a definition as a user
+```
+
+For demos it's still useful/needed to have those definitions. To have them but not exposing them you can use private imports which are only available to the package itself. This feature is called [Subpath imports](https://nodejs.org/dist/latest-v16.x/docs/api/packages.html#packages_subpath_imports) in node.
+
+To enable it you can set the following settings
+
+👉 _rocket.config.js_
+
+```js
+import { rocketLaunch } from '@rocket/launch';
+import { extendLionDocs } from 'rocket-preset-extend-lion-docs';
+
+const extendLionDocsInstance = await extendLionDocs({
+  classPrefix: 'Wolf',
+  classBareImport: 'wolf-web/',
+  tagPrefix: 'wolf-',
+  tagBareImport: '#',
+});
+
+export default {
+  presets: [rocketLaunch(), extendLionDocsInstance],
+};
+```
+
+This rewrites the custom element definition side effects to
+
+```js
+// from
+import '@lion/ui/define/lion-tabs.js';
+
+// to
+import '#tabs/define';
+```
+
+In order for such imports to work you need to define them
+
+👉 _package.json_
+
+```json
+"imports": {
+  "#tabs/define": "./__element-definitions/wolf-tabs.js",
+}
+```
+
+## Global replacements
+
+Sometimes you need a bit more power when extending lion documentation.
+For instance, you're extending repository has a different folder structure. Instead of putting your systems
+documentation inside 'systems', you want to put it in 'web-systems'.
+
+The configuration for that is (see `globalReplaceFunction`):
+
+👉 _rocket.config.js_
+
+```js
+import { rocketLaunch } from '@rocket/launch';
+import { extendLionDocs } from 'rocket-preset-extend-lion-docs';
+
+const extendLionDocsInstance = await extendLionDocs({
+  classPrefix: 'Wolf',
+  classBareImport: 'wolf-web/',
+  tagPrefix: 'wolf-',
+  tagBareImport: 'wolf-web/',
+  globalReplaceFunction: node => {
+    if (node.type === 'link') {
+      // All internal links to '/systems/' (like '(../../fundamentals/systems/overlays/configuration.md)'),
+      // will be changed into '/web-systems/' ('(../../fundamentals/web-systems/overlays/configuration.md)').
+      node.url = node.url.replace(/\systems\/g, '/web-systems/');
+    }
+    return node;
+  }
+});
+
+export default {
+  presets: [rocketLaunch(), extendLionDocsInstance],
+};
+```
+
+Remember: with great power comes great responsibility, so make sure your replacements do not introduce unintended
+effects.

package/docs/fundamentals/rationales/TypeScript.md

@@ -0,0 +1,18 @@
+# Rationales >> TypeScript ||30
+
+[TypeScript](https://www.typescriptlang.org) is superset of JavaScript and a popular tool for getting strongly typed syntax and better autocompletion in JavaScript.
+
+We've ensured that the entire Lion library is typed so that you can use it in TypeScript, but there are some caveats.
+
+In Lion, we rely heavily on [Mixins](https://lit.dev/docs/composition/mixins/#mixin-basics) as a pattern for abstracting certain behaviors and properties into implementable interfaces.
+Since JavaScript has a one-dimensional inheritance chain, inheriting from multiple ancestors has always been tricky, the Mixin pattern is used to get around that.
+
+Here's the thing, Mixins have been notoriously difficult to type properly in TypeScript and in addition, we did not feel happy about adding an adhoc compilation step in our developer workflow. Therefore, we opted for typing our code with [JSDoc](https://jsdoc.app/) and using TypeScript to lint our types and generate type definition files.
+
+Consuming Lion as `.js` typed by JSDoc is not much different from consuming it as when they were `.ts` files, but due to Mixins being very tricky to type, we've had to use `@ts-ignore` in a couple of places, most importantly, in many of our mixins.
+
+For context, here's a [thread on the issue](https://github.com/microsoft/TypeScript/issues/36821) of inheritance type constraints in mixins, where a user suggested allowing to ignore the rule that causes problems.
+This suggestion was declined and in [this comment](https://github.com/microsoft/TypeScript/issues/36821#issuecomment-588375051), Ryan Cavanaugh explained that using `@ts-ignore` is the right way to get around the limitation here.
+As a user of Lion this means that because we've got `@ts-ignore`s in our source code, you may get type errors that originate from Lion, and there's nothing we can do about that, TypeScript's stance is that sometimes rules are too conservative, and ignoring them is the correct answer.
+
+In order to ignore type issues coming from Lion, please use the [skipLibCheck](https://www.typescriptlang.org/tsconfig#skipLibCheck) option in your `ts.config.json`, this will ignore issues that aren't coming from your code.

package/docs/fundamentals/rationales/index.md

@@ -0,0 +1 @@
+# Rationales ||50

package/docs/fundamentals/rationales/side-effects.md

@@ -0,0 +1,203 @@
+# Rationales >> Side Effects ||10
+
+All our packages are side effect free due to the fact that es modules are always side effect free even when changing other es modules. Only code which accesses browser globals like `window`, `console` in the root of the module will be treated a side effect and always included.
+Everything else can be tree shaken by [rollup](https://rollupjs.org).
+
+## Example
+
+In this example we will define a function to override an es module export.
+
+👉 `main.js`
+
+```js
+import { somethingElse, overlays } from './overlays.js';
+
+console.log(somethingElse);
+```
+
+👉 `overlays.js`
+
+```js
+class OverlayManager {}
+
+export let overlays = new OverlayManager();
+
+export function setOverlays(newOverlays) {
+  overlays = newOverlays;
+}
+
+export const somethingElse = 'something else';
+```
+
+### Example Result
+
+However having this function alone does not mean a side effect as rollup can tree shake it.
+
+See the code in [rollup repl][1].
+
+```js
+const somethingElse = 'something else';
+
+console.log(somethingElse);
+```
+
+## Example Override
+
+Let's add an es module which uses that override.
+
+👉 `main.js`
+
+```js
+import { somethingElse, overlays } from './overlays.js';
+import './override.js';
+
+console.log(somethingElse);
+
+// this will trigger loading of full overlays.js & override.js code
+// console.log(overlays.list);
+```
+
+👉 `override.js`
+
+```js
+import { setOverlays } from './overlays.js';
+
+setOverlays(new Object());
+```
+
+## Example Override Result
+
+It will still be fully tree shaken.
+
+See the code in [rollup repl][2].
+
+```js
+const somethingElse = 'something else';
+
+console.log(somethingElse);
+
+// this will trigger loading of full overlays.js & override.js code
+// console.log(overlays.list);
+```
+
+## Example Override Result Accessing
+
+ONLY if you actually access `overlays` it will include `overlays.js` & `override.js`.
+
+```js
+class OverlayManager {}
+
+let overlays = new OverlayManager();
+
+function setOverlays(newOverlays) {
+  overlays = newOverlays;
+}
+
+const somethingElse = 'something else';
+
+setOverlays(new Object());
+
+console.log(somethingElse);
+
+// this will trigger loading of full overlays.js & override.js code
+console.log(overlays.list);
+```
+
+---
+
+## Comprehensive Example
+
+This time we have a separate controller which also accesses the `overlays`.
+
+👉 `main.js`
+
+```js
+import { somethingElse, setOverlays, overlays } from './overlays.js';
+import { OverlayController, somethingElse2 } from './OverlayController.js';
+
+// the following code will tree shake overlays away hence overlays is side effect free
+
+setOverlays(new Object());
+console.log(somethingElse);
+console.log(somethingElse2);
+
+//** The following will toggle importing of overlays */
+
+// 1. import overlays directly and access it
+// console.log(overlays.list);
+
+// 2. create an OverlayController which internally accesses overlays
+// const ctrl = new OverlayController();
+// console.log(ctrl.manager.list);
+```
+
+👉 `overlays.js`
+
+```js
+class OverlayManager {
+  constructor() {
+    this.list = [];
+  }
+  add(a) {
+    this.list.push(a);
+  }
+}
+
+export let overlays = new OverlayManager();
+
+export function setOverlays(newOverlays) {
+  overlays = newOverlays;
+}
+
+export const somethingElse = 'something else';
+
+// the following line is a side effect as it always will be included
+console.log('overlays side effect');
+```
+
+👉 `OverlayController.js`
+
+```js
+import { overlays } from './overlays.js';
+
+export class OverlayController {
+  constructor(config = {}, manager = overlays) {
+    this.manager = manager;
+    this.manager.add(this);
+  }
+}
+
+export const somethingElse2 = 'something else';
+```
+
+### Comprehensive Example Result
+
+Even with all these intertwined code rollup can tree shake it fully away.
+Again if you access the `overlays` or you start instantiating an `OverlaysController` it will include all the needed code.
+
+Be sure to see it for yourself in the [rollup repl][3].
+
+```js
+const somethingElse = 'something else';
+
+// the following line is a side effect as it always will be included
+console.log('overlays side effect');
+
+const somethingElse2 = 'something else';
+
+console.log(somethingElse);
+console.log(somethingElse2);
+
+//** The following will toggle importing of overlays */
+
+// 1. import overlays directly and access it
+// console.log(overlays.list);
+
+// 2. create an OverlayController which internally accesses overlays
+// const ctrl = new OverlayController();
+// console.log(ctrl.manager.list);
+```
+
+[1]: https://rollupjs.org/repl/?version=2.10.2&shareable=JTdCJTIybW9kdWxlcyUyMiUzQSU1QiU3QiUyMm5hbWUlMjIlM0ElMjJtYWluLmpzJTIyJTJDJTIyY29kZSUyMiUzQSUyMmltcG9ydCUyMCU3QiUyMHNvbWV0aGluZ0Vsc2UlMkMlMjBvdmVybGF5cyUyMCU3RCUyMGZyb20lMjAnLiUyRm92ZXJsYXlzLmpzJyUzQiU1Q24lNUNuY29uc29sZS5sb2coc29tZXRoaW5nRWxzZSklM0IlMjIlMkMlMjJpc0VudHJ5JTIyJTNBdHJ1ZSU3RCUyQyU3QiUyMm5hbWUlMjIlM0ElMjJvdmVybGF5cy5qcyUyMiUyQyUyMmNvZGUlMjIlM0ElMjJjbGFzcyUyME92ZXJsYXlNYW5hZ2VyJTIwJTdCJTdEJTVDbiU1Q25leHBvcnQlMjBsZXQlMjBvdmVybGF5cyUyMCUzRCUyMG5ldyUyME92ZXJsYXlNYW5hZ2VyKCklM0IlNUNuJTVDbmV4cG9ydCUyMGZ1bmN0aW9uJTIwc2V0T3ZlcmxheXMobmV3T3ZlcmxheXMpJTIwJTdCJTVDbiU1Q3RvdmVybGF5cyUyMCUzRCUyMG5ld092ZXJsYXlzJTNCJTVDbiU3RCU1Q24lNUNuZXhwb3J0JTIwY29uc3QlMjBzb21ldGhpbmdFbHNlJTIwJTNEJTIwJ3NvbWV0aGluZyUyMGVsc2UnJTNCJTIyJTdEJTVEJTJDJTIyb3B0aW9ucyUyMiUzQSU3QiUyMmZvcm1hdCUyMiUzQSUyMmVzJTIyJTJDJTIybmFtZSUyMiUzQSUyMm15QnVuZGxlJTIyJTJDJTIyYW1kJTIyJTNBJTdCJTIyaWQlMjIlM0ElMjIlMjIlN0QlMkMlMjJnbG9iYWxzJTIyJTNBJTdCJTdEJTdEJTJDJTIyZXhhbXBsZSUyMiUzQW51bGwlN0Q=
+[2]: https://rollupjs.org/repl/?version=2.10.2&shareable=JTdCJTIybW9kdWxlcyUyMiUzQSU1QiU3QiUyMm5hbWUlMjIlM0ElMjJtYWluLmpzJTIyJTJDJTIyY29kZSUyMiUzQSUyMmltcG9ydCUyMCU3QiUyMHNvbWV0aGluZ0Vsc2UlMkMlMjBvdmVybGF5cyUyMCU3RCUyMGZyb20lMjAnLiUyRm92ZXJsYXlzLmpzJyUzQiU1Q25pbXBvcnQlMjAnLiUyRm92ZXJyaWRlLmpzJyUzQiU1Q24lNUNuY29uc29sZS5sb2coc29tZXRoaW5nRWxzZSklM0IlNUNuJTVDbiUyRiUyRiUyMHRoaXMlMjB3aWxsJTIwdHJpZ2dlciUyMGxvYWRpbmclMjBvZiUyMGZ1bGwlMjBvdmVybGF5cy5qcyUyMCUyNiUyMG92ZXJyaWRlLmpzJTIwY29kZSU1Q24lMkYlMkYlMjBjb25zb2xlLmxvZyhvdmVybGF5cy5saXN0KSUzQiUyMiUyQyUyMmlzRW50cnklMjIlM0F0cnVlJTdEJTJDJTdCJTIybmFtZSUyMiUzQSUyMm92ZXJsYXlzLmpzJTIyJTJDJTIyY29kZSUyMiUzQSUyMmNsYXNzJTIwT3ZlcmxheU1hbmFnZXIlMjAlN0IlN0QlNUNuJTVDbmV4cG9ydCUyMGxldCUyMG92ZXJsYXlzJTIwJTNEJTIwbmV3JTIwT3ZlcmxheU1hbmFnZXIoKSUzQiU1Q24lNUNuZXhwb3J0JTIwZnVuY3Rpb24lMjBzZXRPdmVybGF5cyhuZXdPdmVybGF5cyklMjAlN0IlNUNuJTVDdG92ZXJsYXlzJTIwJTNEJTIwbmV3T3ZlcmxheXMlM0IlNUNuJTdEJTVDbiU1Q25leHBvcnQlMjBjb25zdCUyMHNvbWV0aGluZ0Vsc2UlMjAlM0QlMjAnc29tZXRoaW5nJTIwZWxzZSclM0IlMjIlN0QlMkMlN0IlMjJuYW1lJTIyJTNBJTIyb3ZlcnJpZGUuanMlMjIlMkMlMjJjb2RlJTIyJTNBJTIyaW1wb3J0JTIwJTdCJTIwc2V0T3ZlcmxheXMlMjAlN0QlMjBmcm9tJTIwJy4lMkZvdmVybGF5cy5qcyclM0IlNUNuJTVDbnNldE92ZXJsYXlzKG5ldyUyME9iamVjdCgpKSUzQiUyMiU3RCU1RCUyQyUyMm9wdGlvbnMlMjIlM0ElN0IlMjJmb3JtYXQlMjIlM0ElMjJlcyUyMiUyQyUyMm5hbWUlMjIlM0ElMjJteUJ1bmRsZSUyMiUyQyUyMmFtZCUyMiUzQSU3QiUyMmlkJTIyJTNBJTIyJTIyJTdEJTJDJTIyZ2xvYmFscyUyMiUzQSU3QiU3RCU3RCUyQyUyMmV4YW1wbGUlMjIlM0FudWxsJTdE
+[3]: https://rollupjs.org/repl/?version=2.10.2&shareable=JTdCJTIybW9kdWxlcyUyMiUzQSU1QiU3QiUyMm5hbWUlMjIlM0ElMjJtYWluLmpzJTIyJTJDJTIyY29kZSUyMiUzQSUyMmltcG9ydCUyMCU3QiUyMHNvbWV0aGluZ0Vsc2UlMkMlMjBzZXRPdmVybGF5cyUyQyUyMG92ZXJsYXlzJTIwJTdEJTIwZnJvbSUyMCcuJTJGb3ZlcmxheXMuanMnJTNCJTVDbmltcG9ydCUyMCU3QiUyME92ZXJsYXlDb250cm9sbGVyJTJDJTIwc29tZXRoaW5nRWxzZTIlMjAlN0QlMjBmcm9tJTIwJy4lMkZPdmVybGF5Q29udHJvbGxlci5qcyclM0IlNUNuJTVDbiUyRiUyRiUyMHRoZSUyMGZvbGxvd2luZyUyMGNvZGUlMjB3aWxsJTIwdHJlZSUyMHNoYWtlJTIwb3ZlcmxheXMlMjBhd2F5JTIwaGVuY2UlMjBvdmVybGF5cyUyMGlzJTIwc2lkZSUyMGVmZmVjdCUyMGZyZWUlMjAlNUNuJTVDbnNldE92ZXJsYXlzKG5ldyUyME9iamVjdCgpKSUzQiU1Q25jb25zb2xlLmxvZyhzb21ldGhpbmdFbHNlKSUzQiU1Q25jb25zb2xlLmxvZyhzb21ldGhpbmdFbHNlMiklM0IlNUNuJTVDbiUyRiUyRioqJTIwVGhlJTIwZm9sbG93aW5nJTIwd2lsbCUyMHRvZ2dsZSUyMGltcG9ydGluZyUyMG9mJTIwb3ZlcmxheXMlMjAqJTJGJTVDbiU1Q24lMkYlMkYlMjAxLiUyMGltcG9ydCUyMG92ZXJsYXlzJTIwZGlyZWN0bHklMjBhbmQlMjBhY2Nlc3MlMjBpdCU1Q24lMkYlMkYlMjBjb25zb2xlLmxvZyhvdmVybGF5cy5saXN0KSUzQiUyMCU1Q24lNUNuJTJGJTJGJTIwMi4lMjBjcmVhdGUlMjBhbiUyME92ZXJsYXlDb250cm9sbGVyJTIwd2hpY2glMjBpbnRlcm5hbGx5JTIwYWNjZXNzZXMlMjBvdmVybGF5cyU1Q24lMkYlMkYlMjBjb25zdCUyMGN0cmwlMjAlM0QlMjBuZXclMjBPdmVybGF5Q29udHJvbGxlcigpJTNCJTVDbiUyRiUyRiUyMGNvbnNvbGUubG9nKGN0cmwubWFuYWdlci5saXN0KSUzQiU1Q24lNUNuJTIyJTJDJTIyaXNFbnRyeSUyMiUzQXRydWUlN0QlMkMlN0IlMjJuYW1lJTIyJTNBJTIyb3ZlcmxheXMuanMlMjIlMkMlMjJjb2RlJTIyJTNBJTIyY2xhc3MlMjBPdmVybGF5TWFuYWdlciUyMCU3QiU1Q24lNUN0Y29uc3RydWN0b3IoKSUyMCU3QiU1Q24lNUN0JTVDdHRoaXMubGlzdCUyMCUzRCUyMCU1QiU1RCUzQiU1Q24lNUN0JTdEJTVDbiUyMCUyMGFkZChhKSUyMCU3QiU1Q24lMjAlMjAlMjAlMjB0aGlzLmxpc3QucHVzaChhKSUzQiU1Q24lNUN0JTdEJTVDbiU3RCU1Q24lNUNuZXhwb3J0JTIwbGV0JTIwb3ZlcmxheXMlMjAlM0QlMjBuZXclMjBPdmVybGF5TWFuYWdlcigpJTNCJTVDbiU1Q25leHBvcnQlMjBmdW5jdGlvbiUyMHNldE92ZXJsYXlzKG5ld092ZXJsYXlzKSUyMCU3QiU1Q24lNUN0b3ZlcmxheXMlMjAlM0QlMjBuZXdPdmVybGF5cyUzQiU1Q24lN0QlNUNuJTVDbmV4cG9ydCUyMGNvbnN0JTIwc29tZXRoaW5nRWxzZSUyMCUzRCUyMCdzb21ldGhpbmclMjBlbHNlJyUzQiU1Q24lNUNuJTJGJTJGJTIwdGhlJTIwZm9sbG93aW5nJTIwbGluZSUyMGlzJTIwYSUyMHNpZGUlMjBlZmZlY3QlMjBhcyUyMGl0JTIwYWx3YXlzJTIwd2lsbCUyMGJlJTIwaW5jbHVkZWQlNUNuY29uc29sZS5sb2coJ292ZXJsYXlzJTIwc2lkZSUyMGVmZmVjdCcpJTNCJTIyJTJDJTIyaXNFbnRyeSUyMiUzQWZhbHNlJTdEJTJDJTdCJTIybmFtZSUyMiUzQSUyMk92ZXJsYXlDb250cm9sbGVyLmpzJTIyJTJDJTIyY29kZSUyMiUzQSUyMmltcG9ydCUyMCU3QiUyMG92ZXJsYXlzJTIwJTdEJTIwZnJvbSUyMCcuJTJGb3ZlcmxheXMuanMnJTNCJTVDbiU1Q25leHBvcnQlMjBjbGFzcyUyME92ZXJsYXlDb250cm9sbGVyJTIwJTdCJTVDbiUyMCUyMCUyMGNvbnN0cnVjdG9yKGNvbmZpZyUyMCUzRCUyMCU3QiU3RCUyQyUyMG1hbmFnZXIlMjAlM0QlMjBvdmVybGF5cyklMjAlN0IlNUNuJTIwJTIwJTIwJTIwJTIwdGhpcy5tYW5hZ2VyJTIwJTNEJTIwbWFuYWdlciUzQiU1Q24lNUN0JTVDdCUyMHRoaXMubWFuYWdlci5hZGQodGhpcyklM0IlNUNuJTVDdCUyMCU3RCU1Q24lN0QlNUNuJTVDbmV4cG9ydCUyMGNvbnN0JTIwc29tZXRoaW5nRWxzZTIlMjAlM0QlMjAnc29tZXRoaW5nJTIwZWxzZSclM0IlMjIlN0QlNUQlMkMlMjJvcHRpb25zJTIyJTNBJTdCJTIyZm9ybWF0JTIyJTNBJTIyZXMlMjIlMkMlMjJuYW1lJTIyJTNBJTIybXlCdW5kbGUlMjIlMkMlMjJhbWQlMjIlM0ElN0IlMjJpZCUyMiUzQSUyMiUyMiU3RCUyQyUyMmdsb2JhbHMlMjIlM0ElN0IlN0QlN0QlMkMlMjJleGFtcGxlJTIyJTNBbnVsbCU3RA==

package/docs/fundamentals/rationales/versioning.md

@@ -0,0 +1,35 @@
+# Rationales >> Versioning Lion ||20
+
+Since Lion is a monorepository where each package is published separately under the `@lion` scope, we have packages that depend on other packages.
+
+For example, `@lion/dialog` has a dependency on `@lion/overlays`.
+
+The way we now version those is with `^` carets, for example:
+
+```json
+{
+  "dependencies": {
+    "@lion/overlays": "^0.30.0"
+  }
+}
+```
+
+This means:
+
+- For versions >= 1.0.0, get the latest minor of a certain major, major upgrades may contain breaking changes
+- For versions < 1.0.0, get the latest patch of a certain minor, minor upgrades may contain breaking changes
+
+See also, [Semantic Versioning](https://semver.org/).
+
+In the past, we used to have fixed versioning, our rationale was as follows:
+
+> Given there is a subclasser that consumes lion and publishes their own component set, each installation of a certain version of that component set must have the exact same versions of lion installed, so that the experience of the end user is consistent.
+
+**However**, if semver is followed properly, users should never get the situation where they get diverging experiences, because that would only happen in a breaking change.
+Additionally, fixing the versions led to other problems:
+
+- Undedupable installations of the same package. If there are two installations of `@lion/ui/button` and one is installed as a dependency of another lion package, this installation will never be able to be deduped to another version, even if they.js're on the same minor. This is because the dependency is set to a fixed version, so NPM will see the two installations as incompatible and not dedupe them. For Lion, this can definitely lead to problems, especially with packages like `@lion/form-core`, `@lion/localize`, `@lion/overlays`, due to the singleton nature of some of the parts in those packages.
+- Importing directly from lion as an end user when consuming a subclasser package that uses lion under the hood is dangerous. This is because you will need to always match, **exactly**, the version that is installed by the subclasser package. This means syncing your lion version with the subclasser's installed lion version every time you upgrade.
+- Changesets will see (correctly) every bump in a `@lion` dependency as a semver-incompatible change for its `@lion` dependents and bump them as a result. This means a change to `@lion/core`, no matter how tiny, will bump almost every other `@lion` package "unnecessarily". This results in large changelogs that are mostly meaningless noise, hardly "human readable" which is the goal of changesets when used correctly.
+
+Given all this, we changed our approach to versioning and went back to using `^` carets in our versions and **our new recommendation is to depend on `@lion` with `^` carets**. This should prevent majority of undedupable installation problems our users were having, allow importing from `@lion` directly, more safely, make our changelogs cleaner and reduce our publishing bloat.

package/docs/fundamentals/systems/core/index.md

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

package/docs/fundamentals/systems/core/overview.md

@@ -0,0 +1,85 @@
+# Systems >> Core >> Overview ||10
+
+The core package is mostly for in-depth usage.
+It handles the version of `lit-element` and `lit-html`.
+
+To be sure a compatible version is used you should import it via this package.
+
+```js
+// DO
+import { LitElement, html, render } from 'lit';
+
+// DON'T
+import { LitElement, html, render } from 'lit-element';
+```
+
+## Features
+
+- [function to deduplicate mixins (dedupeMixin)](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/fundamentals/systems/core/#deduping-of-mixins)
+- Mixin to handle disabled (DisabledMixin)
+- Mixin to handle disabled AND tabIndex (DisabledWithTabIndexMixin)
+- Mixin to manage auto-generated needed slot elements in light dom (SlotMixin)
+- Mixin to create scoped styles in LightDOM-using components (ScopedStylesMixin)
+
+> These features are not well documented - care to help out?
+
+## Installation
+
+```bash
+npm i --save @lion/ui
+```
+
+```js
+import { dedupeMixin, LitElement } from 'lit';
+```
+
+### Example
+
+```js
+const BaseMixin = dedupeMixin((superClass) => {
+  return class extends superClass { ... };
+});
+```
+
+## Deduping of mixins
+
+### Why is deduping of mixins necessary?
+
+Imagine you are developing web components and creating ES classes for Custom Elements. You have two generic mixins (let's say `M1` and `M2`) which require independently the same even more generic mixin (`BaseMixin`). `M1` and `M2` can be used independently, that means they have to inherit from `BaseMixin` also independently. But they can be also used in combination. Sometimes `M1` and `M2` are used in the same component and can mess up the inheritance chain if `BaseMixin` is applied twice.
+In other words, this may happen to the protoype chain `... -> M2 -> BaseMixin -> M1 -> BaseMixin -> ...`.
+
+An example of this may be a `LocalizeMixin` used across different components and mixins. Some mixins may need it and many components need it too and can not rely on other mixins to have it by default, so must inherit from it independently.
+
+The more generic the mixin is, the higher the chance of being applied more than once. As a mixin author you can't control how it is used, and can't always predict it. So as a safety measure it is always recommended to create deduping mixins.
+
+### Usage of dedupeMixin()
+
+This is an example of how to make a conventional ES mixin deduping.
+
+```js
+const BaseMixin = dedupeMixin((superClass) => {
+  return class extends superClass { ... };
+});
+
+// inherits from BaseMixin
+const M1 = dedupeMixin((superClass) => {
+  return class extends BaseMixin(superClass) { ... };
+});
+
+// inherits from BaseMixin
+const M2 = dedupeMixin((superClass) => {
+  return class extends BaseMixin(superClass) { ... };
+});
+
+// component inherits from M1
+// MyCustomElement -> M1 -> BaseMixin -> BaseCustomElement;
+class MyCustomElement extends M1(BaseCustomElement) { ... }
+
+// component inherits from M2
+// MyCustomElement -> M2 -> BaseMixin -> BaseCustomElement;
+class MyCustomElement extends M2(BaseCustomElement) { ... }
+
+// component inherits from both M1 and M2
+// MyCustomElement -> M2 -> M1 -> BaseMixin -> BaseCustomElement;
+class MyCustomElement extends M2(M1(BaseCustomElement)) { ... }
+```