@lion/ui 0.0.2 → 0.0.4

package/docs/components/tooltip/overview.md

@@ -0,0 +1,44 @@
+# Tooltip >> Overview ||10
+
+A web component used for basic popups on hover.
+Its purpose is to show content appearing when the user hovers over an invoker element with the cursor or with the keyboard, or if the invoker element is focused.
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import '@lion/ui/define/lion-tooltip.js';
+```
+
+```js preview-story
+export const main = () => html`
+  <style>
+    .demo-tooltip-invoker {
+      margin: 50px;
+    }
+  </style>
+  <lion-tooltip has-arrow>
+    <button slot="invoker" class="demo-tooltip-invoker">Hover me</button>
+    <div slot="content">This is a tooltip</div>
+  </lion-tooltip>
+`;
+```
+
+## Features
+
+- Show content when hovering the invoker
+- Show content when the invoker is focused
+- Does not show content when invoker is disabled
+- Uses Popper.js under the hood, to have the content pop up relative to the invoker
+- Use `.config` to override the overlay configuration
+- Config has `popperConfig` property that has a one to one relation with Popper.js configuration API.
+
+## Installation
+
+```bash
+npm i --save @lion/ui
+```
+
+```js
+import { LionTooltip } from '@lion/ui/tooltip.js';
+// or
+import '@lion/ui/define/lion-tooltip.js';
+```

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

@@ -0,0 +1,208 @@
+# Tooltip >> Use Cases ||20
+
+```js script
+import { css, html } from '@mdjs/mdjs-preview';
+import { LionTooltip } from '@lion/ui/tooltip.js';
+import '@lion/ui/define/lion-tooltip.js';
+```
+
+## invokerRelation
+
+There is a difference between tooltips used as a primary label or as a description. In most cases a button will already have its own label, so the tooltip will be used as a description with extra information, which is already set as default. Only in case of icon buttons you want to use the tooltip as the primary label. To do so you need to set the `invokerRelation` to `label`.
+
+> For detailed information please read: [inclusive tooltips](https://inclusive-components.design/tooltips-toggletips/#inclusivetooltips).
+
+```js preview-story
+export const invokerRelation = () => {
+  const invokerRelationConfig = { invokerRelation: 'label' };
+  return html`
+    <style>
+      .demo-tooltip-invoker {
+        margin: 50px;
+      }
+    </style>
+    <lion-tooltip .config=${invokerRelationConfig}>
+      <button slot="invoker" class="demo-tooltip-invoker">📅</button>
+      <div slot="content">Agenda<div>
+    </lion-tooltip>
+  `;
+};
+```
+
+## Placements
+
+You can easily change the placement of the content node relative to the invoker, by adjusting the `placement` inside the `popperConfig`.
+
+```js preview-story
+export const placements = () => {
+  const placementTopConfig = { popperConfig: { placement: 'top' } };
+  const placementRightConfig = { popperConfig: { placement: 'right' } };
+  const placementBottomConfig = { popperConfig: { placement: 'bottom' } };
+  const placementLeftConfig = { popperConfig: { placement: 'left' } };
+  return html`
+    <style>
+      button[slot='invoker'] {
+        margin: 50px;
+      }
+      div[slot='content'] {
+        background-color: white;
+        padding: 4px;
+      }
+    </style>
+    <div class="demo-box-placements">
+      <lion-tooltip has-arrow .config=${placementTopConfig}>
+        <button slot="invoker">Top</button>
+        <div slot="content">Top placement</div>
+      </lion-tooltip>
+      <lion-tooltip has-arrow .config=${placementRightConfig}>
+        <button slot="invoker">Right</button>
+        <div slot="content">Right placement</div>
+      </lion-tooltip>
+      <lion-tooltip has-arrow .config=${placementBottomConfig}>
+        <button slot="invoker">Bottom</button>
+        <div slot="content">Bottom placement</div>
+      </lion-tooltip>
+      <lion-tooltip has-arrow .config=${placementLeftConfig}>
+        <button slot="invoker">Left</button>
+        <div slot="content">Left placement</div>
+      </lion-tooltip>
+    </div>
+  `;
+};
+```
+
+## Override Popper configuration
+
+You can override the Popper configuration, the API is one to one with Popper's API, and includes modifiers.
+
+```js preview-story
+export const overridePopperConfig = () => {
+  const overridePopperConfig = {
+    popperConfig: {
+      placement: 'bottom-start',
+      strategy: 'fixed',
+      modifiers: [
+        {
+          name: 'keepTogether',
+          options: {},
+          enabled: true,
+        },
+        {
+          name: 'preventOverflow',
+          options: {
+            boundariesElement: 'viewport',
+            padding: 16,
+          },
+          enabled: false,
+        },
+        {
+          name: 'flip',
+          options: {
+            boundariesElement: 'viewport',
+            padding: 4,
+          },
+          enabled: true,
+        },
+        {
+          name: 'offset',
+          options: {
+            // Note the different offset notation
+            offset: [0, 4],
+          },
+          enabled: true,
+        },
+      ],
+    },
+  };
+  return html`
+    <style>
+      .demo-tooltip-invoker {
+        margin: 50px;
+      }
+    </style>
+    <lion-tooltip .config=${overridePopperConfig}>
+      <button slot="invoker" class="demo-tooltip-invoker">Hover me</button>
+      <div slot="content">This is a tooltip<div>
+    </lion-tooltip>
+  `;
+};
+```
+
+Modifier explanations:
+
+- keepTogether: prevents detachment of content element from reference element, which could happen if the invoker is not in the viewport any more. If this is disabled, the content will always be in view.
+- preventOverflow: enables shifting and sliding behavior on the secondary axis (e.g. if top placement, this is horizontal shifting and sliding). The padding property defines the margin with the boundariesElement, which is usually the viewport.
+- flip: enables flipping behavior on the primary axis (e.g. if top placement, flipping to bottom if there is not enough space on the top). The padding property defines the margin with the boundariesElement, which is usually the viewport.
+- offset: enables an offset between the content node and the invoker node. First argument is horizontal margin, second argument is vertical margin.
+
+## Arrow
+
+By default, the arrow is disabled for our tooltip. Via the `has-arrow` property it can be enabled.
+
+> As a Subclasser, you can decide to turn the arrow on by default if this fits your Design System, by setting `this.hasArrow = true;` in the constructor.
+
+```js preview-story
+export const arrow = () => html`
+  <style>
+    .demo-tooltip-invoker {
+      margin: 50px;
+    }
+  </style>
+  <lion-tooltip has-arrow>
+    <button slot="invoker" class="demo-tooltip-invoker">Hover me</button>
+    <div slot="content">This is a tooltip</div>
+  </lion-tooltip>
+`;
+```
+
+### Use a custom arrow
+
+If you plan on providing a custom arrow, you can extend the `lion-tooltip`.
+
+All you need to do is override the `_arrowTemplate` method to pass your own SVG, and extend the styles to pass the proper dimensions of your arrow.
+The rest of the work is done by Popper.js (for positioning) and the `lion-tooltip-arrow` (arrow dimensions, rotation, etc.).
+
+```js preview-story
+export const customArrow = () => {
+  if (!customElements.get('custom-tooltip')) {
+    customElements.define(
+      'custom-tooltip',
+      class extends LionTooltip {
+        static get styles() {
+          return [
+            ...super.styles,
+            css`
+              :host {
+                --tooltip-arrow-width: 20px;
+                --tooltip-arrow-height: 8px;
+              }
+            `,
+          ];
+        }
+        constructor() {
+          super();
+          this.hasArrow = true;
+        }
+        _arrowTemplate() {
+          return html`
+            <svg viewBox="0 0 20 8" class="arrow__graphic">
+              <path d="M 0,0 h 20 L 10,8 z"></path>
+            </svg>
+          `;
+        }
+      },
+    );
+  }
+  return html`
+    <style>
+      .demo-tooltip-invoker {
+        margin: 50px;
+      }
+    </style>
+    <custom-tooltip>
+      <button slot="invoker" class="demo-tooltip-invoker">Hover me</button>
+      <div slot="content">This is a tooltip</div>
+    </custom-tooltip>
+  `;
+};
+```

package/docs/fundamentals/index.md

@@ -0,0 +1,19 @@
+---
+title: Documentation
+eleventyNavigation:
+  key: Fundamentals
+  order: 20
+---
+
+Here you find more details about what we offer.
+
+Let's see what each section describes.
+
+1. [](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/fundamentals/systems/core/overview.md) <br>
+   These are the fundamental systems that power all of our components.
+2. [Tools](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/fundamentals/tools/helpers/overview.md) <br>
+   Frontend Tools useful for web development but are not visual and therefore are not components.
+3. [Node Tools](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/fundamentals/node-tools/babel-plugin-extend-docs/overview.md) <br>
+   Node tools to analyse the code and for extending the documentation.
+4. [Rationales](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/fundamentals/rationales/side-effects.md) <br>
+   The reasoning behind some of our decisions.

package/docs/fundamentals/node-tools/babel-plugin-extend-docs/index.md

@@ -0,0 +1 @@
+# Node Tools >> Babel Extend Docs ||10

package/docs/fundamentals/node-tools/babel-plugin-extend-docs/overview.md

@@ -0,0 +1,233 @@
+# Node Tools >> Babel Extend Docs >> Overview ||10
+
+A plugin which rewrites imports and templates according to a configuration.
+This enables the reuse of existing documentation from source packages while still using your extensions code.
+
+## Installation
+
+```bash
+npm i -D babel-plugin-extend-docs
+```
+
+We want to only execute `babel-plugin-extend-docs` on the actual files we want to modify/extend.
+
+You may also consider using [babel overrides](https://babeljs.io/docs/en/options#overrides).
+
+👉 _web-dev-server.config.js_
+
+```js
+import path from 'path';
+import { fromRollup } from '@web/dev-server-rollup';
+import rollupBabel from '@rollup/plugin-babel';
+
+const extendDocsConfig = {
+  changes: [
+    // possible changes as described below
+  ],
+};
+
+// note that you need to use `.default` for babel
+const babel = fromRollup(rollupBabel.default);
+
+export default {
+  nodeResolve: true,
+  plugins: [
+    babel({
+      include: ['./glob/to/files/**/*.js'],
+      plugins: [[path.resolve('./'), extendDocsConfig]],
+    }),
+  ],
+};
+```
+
+## Features
+
+- Renames named imports and all it's usage
+- Adjusts import paths
+- Replace tags in template literals
+
+## A Change
+
+A change is what gets placed between in the extendDocsConfig within the `changes` array.
+
+> automating the generation of changes is optional but encouraged
+
+It has the following possibilities:
+
+```js
+changes: [
+  {
+    description: 'MyCounter', // not needed but can be added for easier reading of the config
+    variable: {
+      // see below
+    },
+    tag: {
+      // see below
+    },
+  },
+];
+```
+
+### Paths
+
+Both `variable` and `tag` are required to have a `paths` array which defines how to remap import paths. Generally it should be a single entry.
+
+```js
+paths: [
+  { from: 'source-pkg/counter', to: 'extension-pkg/counter' },
+],
+```
+
+## Replacement of tags
+
+We have an existing demo code which we want to reuse.
+
+```js
+import { LitElement, html } from 'lit';
+import 'source-pkg/counter/define';
+class MyApp extends LitElement {
+  render() {
+    return html`
+      <h1>Example App</h1>
+      <source-counter></source-counter>
+    `;
+  }
+}
+customElements.define('my-app', MyApp);
+```
+
+We created a "better" version of `<source-counter>` so we would like to use that in the demo.
+Our extension is called `<extension-counter>` and is available via `extension-pkg/counter/define`.
+
+Within `babel-plugin-extend-docs` we can define to replace the tag + it's import.
+
+```js
+tag: {
+  from: 'source-counter',
+  to: 'extension-counter',
+  paths: [{ from: 'source-pkg/counter/define', to: 'extension-pkg/counter/define' }],
+}
+```
+
+### Result of Replacement of tags
+
+```js
+import { LitElement, html } from 'lit';
+import 'extension-pkg/counter/define';
+class MyApp extends LitElement {
+  render() {
+    return html`
+      <h1>Example App</h1>
+      <extension-counter></extension-counter>
+    `;
+  }
+}
+customElements.define('my-app', MyApp);
+```
+
+## Replacement of classes
+
+We have an existing demo code which we want to reuse.
+
+```js
+import { LitElement, html } from 'lit';
+import { SourceCounter } from 'source-pkg/counter';
+class TenCounter extends SourceCounter {
+  inc() {
+    this.count += 10;
+  }
+}
+customElements.define('ten-counter', TenCounter);
+
+class MyApp extends LitElement {
+  render() {
+    return html`
+      <h1>Example App</h1>
+      <ten-counter></ten-counter>
+    `;
+  }
+}
+customElements.define('my-app', MyApp);
+```
+
+We created a "better" version of `SourceCounter` so we would like that `TenCounter` now extends it instead.
+
+Within `babel-plugin-extend-docs` we can define to replace the class + it's import.
+
+```js
+variable: {
+  from: 'SourceCounter',
+  to: 'ExtensionCounter',
+  paths: [
+    { from: 'source-pkg/counter', to: 'extension-pkg/counter' },
+  ],
+},
+```
+
+### Result of Replacement of classes
+
+```js
+import { LitElement, html } from 'lit';
+import { SourceCounter } from 'extension-pkg/counter';
+class TenCounter extends SourceCounter {
+  inc() {
+    this.count += 10;
+  }
+}
+customElements.define('ten-counter', TenCounter);
+class MyApp extends LitElement {
+  render() {
+    return html`
+      <h1>Example App</h1>
+      <ten-counter></ten-counter>
+    `;
+  }
+}
+customElements.define('my-app', MyApp);
+```
+
+## Full Demo & Api Example
+
+You can run the example locally via `npm run start` or look at its [source code](https://github.com/ing-bank/lion/tree/master/packages-node/babel-plugin-extend-docs/demo/).
+_Note we are configuring babel via the [server.config.mjs](https://github.com/ing-bank/lion/tree/master/packages-node/babel-plugin-extend-docs/demo/server.config.mjs)_
+
+👉 _server.config.mjs_
+
+```js
+import path from 'path';
+import { fromRollup } from '@web/dev-server-rollup';
+import rollupBabel from '@rollup/plugin-babel';
+
+const extendDocsConfig = {
+  changes: [
+    {
+      name: 'SourceCounter',
+      variable: {
+        from: 'SourceCounter',
+        to: 'ExtensionCounter',
+        paths: [{ from: '#source/counter', to: '#extension/counter' }],
+      },
+      tag: {
+        from: 'source-counter',
+        to: 'extension-counter',
+        paths: [{ from: '#source/counter/define', to: '#extension/counter/define' }],
+      },
+    },
+  ],
+};
+
+// note that you need to use `.default` for babel
+const babel = fromRollup(rollupBabel.default);
+
+export default {
+  nodeResolve: true,
+  watch: true,
+  open: 'demo/',
+  plugins: [
+    babel({
+      include: ['./demo/**/*.demo.js'],
+      plugins: [[path.resolve('./'), extendDocsConfig]],
+    }),
+  ],
+};
+```

package/docs/fundamentals/node-tools/index.md

@@ -0,0 +1 @@
+# Node Tools ||30

package/docs/fundamentals/node-tools/providence-analytics/LocalConfiguration.md

@@ -0,0 +1,68 @@
+# Node Tools >> Providence Analytics >> Local configuration ||40
+
+The Providence configuration file is read by providence cli (optional) and by the dashboard (required).
+It has a few requirements:
+
+- it must be called `providence.conf.js` or `providence.conf.mjs`
+- it must be in ESM format
+- it must be located in the root of a repository (under `process.cwd()`)
+
+## Meta data
+
+### Category info
+
+Based on the filePath of a result, a category can be added.
+For example:
+
+```js
+export default {
+  metaConfig: {
+    categoryConfig: [
+      {
+        // This is the name found in package.json
+        project: '@lion/ui/root.js',
+        // These conditions will be run on overy filePath
+        categories: {
+          core: p => p.startsWith('./packages/core'),
+          utils: p => p.startsWith('./packages/ajax') || p.startsWith('./packages/localize'),
+          overlays: p =>
+            p.startsWith('./packages/overlays') ||
+            p.startsWith('./packages/dialog') ||
+            p.startsWith('./packages/tooltip'),
+          ...
+        },
+      },
+    ],
+  },
+}
+```
+
+> N.B. category info is regarded as subjective, therefore it's advised to move this away from
+> Analyzers (and thus file-system cache). Categories can be added realtime in the dashboard.
+
+## Project paths
+
+### referenceCollections
+
+A list of file system paths. They can be defined relative from the current project root or they can be full paths.
+When a [MatchAnalyzer](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/fundamentals/node-tools/providence-analytics/analyzer.md) like `match-imports` or `match-subclasses` is used, the default reference(s) can be configured here. For instance: ['/path/to/@lion/ui/form.js']
+
+An example:
+
+```js
+  referenceCollections: {
+    // Our products
+    'lion-based-ui': [
+      './providence-input-data/references/lion-based-ui',
+      './providence-input-data/references/lion-based-ui-labs',
+    ],
+    ...
+  }
+```
+
+### searchTargetCollections
+
+A list of file system paths. They can be defined relative from the current project root
+or they can be full paths.
+When not defined, the current project will be the search target (this is most common when
+providence is used as a dev dependency).

package/docs/fundamentals/node-tools/providence-analytics/QueryResult.md

@@ -0,0 +1,111 @@
+# Node Tools >> Providence Analytics >> QueryResult ||50
+
+When an Analyzer has run, it returns a QueryResult. This is a json object that contains all
+meta info (mainly configuration parameters) and the query output.
+A QueryResult always contains the analysis of one project (a target project). Optionally,
+it can contain a reference project as well.
+
+## Anatomy
+
+A QueryResult starts with a meta section, followed by the actual results
+
+### Meta
+
+The meta section lists all configuration options the analyzer was run with. Here, you see an
+example of a `find-imports` QueryResult:
+
+```js
+  "meta": {
+    "searchType": "ast-analyzer",
+    "analyzerMeta": {
+      "name": "find-imports",
+      "requiredAst": "babel",
+      "identifier": "importing-target-project_0.0.2-target-mock__1970011674",
+      "targetProject": {
+        "name": "importing-target-project",
+        "commitHash": "3e5014d6ecdff1fc71138cdb29aaf7bf367588f5",
+        "version": "0.0.2-target-mock"
+      },
+      "configuration": {
+        "keepInternalSources": false
+      }
+    }
+  },
+```
+
+### Output
+
+The output is usually more specifically tied to the Analyzer. What most regular Analyzers
+(not being MatchAnalyzers that require a referenceProjectPath) have in common, is that their
+results are being shown per "entry" (an entry corresponds with an AST generated by Babel, which in
+turn corresponds to a file found in a target or reference project).
+
+Below an example is shown of `find-imports` QueryOutput:
+
+```js
+  "queryOutput": [
+    {
+      "project": {
+        "name": "importing-target-project",
+        "mainEntry": "./target-src/match-imports/root-level-imports.js",
+        "version": "0.0.2-target-mock",
+        "commitHash": "3e5014d6ecdff1fc71138cdb29aaf7bf367588f5"
+      },
+      "entries": [
+        {
+          "file": "./target-src/find-imports/all-notations.js",
+          "result": [
+            {
+              "importSpecifiers": [
+                "[file]"
+              ],
+              "source": "imported/source",
+              "normalizedSource": "imported/source",
+              "fullSource": "imported/source"
+            },
+            {
+              "importSpecifiers": [
+                "[default]"
+              ],
+              "source": "imported/source-a",
+              "normalizedSource": "imported/source-a",
+              "fullSource": "imported/source-a"
+            },
+            ...
+```
+
+MatchAnalyzers usually do post processing on the entries. The output below (for the `match-imports`
+Analyzer) shows an ordering by matched specifier.
+
+```js
+ "queryOutput": [
+    {
+      "exportSpecifier": {
+        "name": "[default]",
+        "project": "exporting-ref-project",
+        "filePath": "./index.js",
+        "id": "[default]::./index.js::exporting-ref-project"
+      },
+      "matchesPerProject": [
+        {
+          "project": "importing-target-project",
+          "files": [
+            "./target-src/match-imports/root-level-imports.js",
+            "./target-src/match-subclasses/internalProxy.js"
+          ]
+        }
+      ]
+    },
+    ...
+```
+
+Due to some legacy decisions, the QueryOutput allows for multiple target- and reference projects.
+Aggregation of data now takes place in the dashboard.
+QueryOutputs always contain one or a combination of two projects. This means that the
+QueryOutput structure could be simplified in the future.
+
+## Environment agnosticism
+
+The output files stored in the file system always need to be machine independent:
+this means that all machine specific information, like a complete filepath, needs to be removed from a QueryOutput (paths relative from project root are still allowed).
+In that way, the caching mechanism (based on hash comparisons) as described in [Analyzer](https://github.com/ing-bank/lion/blob/edc6920a90aa7658358819e7c324daf6badf7d30/docs/fundamentals/node-tools/providence-analytics/analyzer.md) is guaranteed to work across different machines.