@lion/ui 0.0.1 → 0.0.3

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

@@ -0,0 +1,22 @@
+# Node Tools >> Providence Analytics >> Dashboard ||30
+
+An interactive overview of all aggregated [QueryResults](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/node-tools/providence-analytics/QueryResult.md) can be found in the dashboard.
+The dashboard is a small nodejs server (based on es-dev-server + middleware) and a frontend
+application.
+
+## Run
+
+Start the dashboard via `providence dashboard` to automatically open the browser and start the dashboard.
+
+## Interface
+
+- Select all reference projects
+- Select all target projects
+
+### Generate csv
+
+When `get csv` is pressed, a `.csv` will be downloaded that can be loaded into Excel.
+
+## Analyzer support
+
+Currently, `match-imports` and `match-subclasses` are supported, more analyzers will be added in the future.

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

@@ -0,0 +1 @@
+# Node Tools >> Providence Analytics ||20

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

@@ -0,0 +1,192 @@
+# Node Tools >> Providence Analytics >> Overview ||10
+
+```js script
+import { html } from '@mdjs/mdjs-preview';
+import { providenceFlowSvg, providenceInternalFlowSvg } from './assets/_mermaid.svg.js';
+```
+
+Providence is the 'All Seeing Eye' that generates usage statistics by analyzing code.
+It measures the effectivity and popularity of your software.
+With just a few commands you can measure the impact for (breaking) changes, making
+your release process more stable and predictable.
+
+Providence can be used as a dev dependency in a project for which metrics
+can be generated via analyzers (see below).
+For instance for a repo "lion-based-ui" that extends @lion/\* we can answer questions like:
+
+- **Which subsets of my product are popular?**
+  Which exports of reference project @lion/form-core are consumed by target project "lion-based-ui"?
+
+- **How do sub classers consume/override my product?**
+  Which classes / webcomponents inside target project "lion-based-ui" extend from reference project `@lion/\*`?
+  Which of the methods within those classes are overridden?
+
+- etc...
+
+All the above results can be shown in a dashboard (see below), which allows to sort exports from reference project (@lion) based on popularity, category, consumer etc.
+The dashboard allows to aggregate data from many target projects as well and will show you on a detailed (file) level how those components are being consumed by which projects.
+
+## Setup
+
+### Install providence
+
+```bash
+npm i --save-dev providence-analytics
+```
+
+### Add a providence script to package.json
+
+```json
+"scripts": {
+  "providence:match-imports": "providence analyze match-imports -r 'node_modules/@lion/ui/*.js'",
+}
+```
+
+> The example above illustrates how to run the "match-imports" analyzer for reference project 'lion-based-ui'. Note that it is possible to run other analyzers and configurations supported by providence as well. For a full overview of cli options, run `npx providence --help`. All supported analyzers will be viewed when running `npx providence analyze`
+
+You are now ready to use providence in your project. All
+data will be stored in json files in the folder `./providence-output`
+
+![CLI](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/node-tools/providence-analytics/assets/provicli.gif 'CLI')
+
+## Setup: Dashboard
+
+### Add "providence:dashboard" script to package.json
+
+```js
+...
+"scripts": {
+    ...
+    "providence:dashboard": "providence dashboard"
+}
+```
+
+### Add providence.conf.js
+
+```js
+export default {
+  referenceCollections: {
+    'lion-based-ui-collection': [
+      './node_modules/lion-based-ui/packages/x',
+      './node_modules/lion-based-ui/packages/y',
+    ],
+  },
+};
+```
+
+Run `npm run providence:dashboard`
+
+![dashboard](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/node-tools/providence-analytics/assets/providash.gif 'dashboard')
+
+## Setup: about result output
+
+All output files will be stored in `./providence-output`.
+This means they will be committed to git, so your colleagues don't have to
+rerun the analysis (for large projects with many dependencies this can be time consuming)
+and can directly start the dashboard usage metrics.
+Also, note that the files serve as cache (they are stored with hashes based on project version and analyzer configuration). This means that an interrupted analysis can be
+resumed later on.
+
+## Conceptual overview
+
+Providence performs queries on one or more search targets.
+These search targets consist of one or more software projects (javascript/html repositories)
+
+The diagram below shows how `providenceMain` function can be used from an external context.
+
+```js story
+export const providenceFlow = () => providenceFlowSvg;
+```
+
+## Flow inside providence
+
+The diagram below depicts the flow inside the `providenceMain` function.
+It uses:
+
+- InputDataService
+  Used to create a data structure based on a folder (for instance the search target or
+  the references root). The structure creates entries for every file, which get enriched with code,
+  ast results, query results etc. Returns `InputData` object.
+- QueryService
+  Requires a `queryConfig` and `InputData` object. It will perform a query (grep search or ast analysis)
+  and returns a `QueryResult`.
+  It also contains helpers for the creation of a `queryConfig`
+- ReportService
+  The result gets outputted to the user. Currently, a log to the console and/or a dump to a json file
+  are available as output formats.
+
+```js story
+export const providenceInternalFlow = () => providenceInternalFlowSvg;
+```
+
+## Queries
+
+Providence requires a queries as input.
+Queries are defined as objects and can be of two types:
+
+- feature-query
+- ast-analyzer
+
+A `QueryConfig` is required as input to run the `providenceMain` function.
+This object specifies the type of query and contains the relevant meta
+information that will later be outputted in the `QueryResult` (the JSON object that
+the `providenceMain` function returns.)
+
+## Analyzer Query
+
+Analyzer queries are also created via `QueryConfig`s.
+
+Analyzers can be described as predefined queries that use AST traversal.
+
+Run:
+
+```bash
+providence analyze
+```
+
+Now you will get a list of all predefined analyzers:
+
+- find-imports
+- find-exports
+- find-classes
+- match-imports
+- match-subclasses
+- etc...
+
+![Analyzer query](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/node-tools/providence-analytics/assets/analyzer-query.gif 'Analyzer query')
+
+<!--
+## Running providence from its own repo
+
+### How to add a new search target project
+
+```bash
+git submodule add <git-url> ./providence-input-data/search-targets/<project-name>
+```
+
+### How to add a reference project
+
+By adding a reference project, you can automatically see how code in your reference project is
+used across the search target projects.
+Under the hood, this automatically creates a set of queries for you.
+
+```bash
+git submodule add <git-url> ./providence-input-data/references/<project-name>
+```
+
+### Updating submodules
+
+Please run:
+
+```bash
+git submodule update --init --recursive
+```
+
+### Removing submodules
+
+Please run:
+
+```bash
+sh ./rm-submodule.sh <path/to/submodule>
+```
+-->

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

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

package/docs/fundamentals/node-tools/publish-docs/overview.md

@@ -0,0 +1,136 @@
+# Node Tools >> Publish Docs >> Overview ||10
+
+A tool that copies and processes your documentation (in a monorepo) so it can be published/shipped with your package.
+
+It will:
+
+- copy files into your npm package (which is especially useful for mono repositories)
+- processes all markdown files by replacing all relative links to full absolute urls to the commit sha on GitHub
+- have a document structure that is useable on GitHub
+
+## Installation
+
+For a Mono Repository
+
+1. Add dependency
+
+   ```bash
+   npm i -D publish-docs
+   ```
+
+2. Add to your `packages/[my-package]/package.json`:
+
+   ```js
+   "scripts": {
+      "prepublishOnly": "publish-docs --github-url https://github.com/ing-bank/lion/ --git-root-dir ../../"
+   }
+   ```
+
+3. Replace you `packages/[my-package]/README.md` with
+
+   ```md
+   # My Pkg
+
+   [=> See Source <=](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/docs/deep/dir/overview.md)
+   ```
+
+## CLI flags
+
+| name         | type   | description                                                                                  |
+| ------------ | ------ | -------------------------------------------------------------------------------------------- |
+| github-url   | string | Defines which GitHub Urls should be generated for relative links (mandatory)                 |
+| project-dir  | string | The directory of your project/package. Defaults to the current working directory             |
+| git-root-dir | string | The directory of your git entry point. Defaults to the current working directory             |
+| copy-dir     | string | Allows to copies the content of a folder into the copy-target (relative to the git-root-dir) |
+| copy-target  | string | Copies all files into the target (e.g. flattening the directory structure)                   |
+
+Examples:
+
+```
+cd packages/my-pkg/
+publish-docs --github-url https://github.com/ing-bank/lion/ --git-root-dir ../../
+publish-docs --github-url https://github.com/ing-bank/lion/ --git-root-dir ../../ --copy-dir docs/my-components/assets
+```
+
+## More Files
+
+Often it makes sense to have multiple documentation files. If you want to bring them along you can do so by adding more `[=> See Source <=]` hooks.
+
+Bring the `overview.md` in a docs folder along.
+
+👉 `packages/[my-package]/docs/overview.md`
+
+```md
+[=> See Source <=](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/docs/deep/dir/overview.md)
+```
+
+Add a `use-cases.md`
+
+👉 `packages/[my-package]/docs/use-cases.md`
+
+```md
+[=> See Source <=](https://github.com/ing-bank/lion/blob/fbf0bd22378e76aa4261c2a97faf8be4f5fc461e/docs/fundamentals/docs/deep/dir/use-cases.md)
+```
+
+So you will end up with something like this in your package.
+
+```
+.
+├── docs
+│   ├── use-cases.md
+│   └── overview.md
+├── src
+│   ├── my-code.js
+│   └── ...
+├── package.json
+└── README.md
+```
+
+Each of those md files will have a followable link on GitHub and will be replaced with the actual documentation before you publish it.
+
+## Copying assets
+
+On top of markdown documentation, there is often the need to bring along accompanying assets.
+
+For that, a copy dir can be provided.
+
+Note: This pattern is relative to the `git-root-dir`
+
+Therefore given the following tree
+
+```
+.
+├── docs
+│   ├── green
+│   │   ├── green-data.json
+│   │   └── overview.md
+│   └── red
+│       ├── assets
+│       │   ├── more
+│       │   │   └── red-data.json
+│       │   └── red-data.json
+│       └── overview.md
+└── packages
+   └── my-pkg       <-- executed here
+         ├── docs
+         │   └── overview.md
+         └── README.md
+```
+
+we can copy the red assets folder by providing the following copy-dir
+
+```js
+"prepublish": "publish-docs --github-url https://github.com/ing-bank/lion/ --git-root-dir ../../ --copy-dir docs/red/assets"
+```
+
+The published package will look like this
+
+```
+├── docs
+│   ├── assets
+│   │   ├── more
+│   │   │   └── red-data.json
+│   │   └── red-data.json
+│   └── overview.md
+└── README.md
+```

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

@@ -0,0 +1 @@
+# Node Tools >> Remark Extend ||30

package/docs/fundamentals/node-tools/remark-extend/overview.md

@@ -0,0 +1,274 @@
+# Node Tools >> Remark Extend >> Overview ||10
+
+A plugin for remark to extend markdown by importing from source files.
+
+`remark-extend` is build to be integrated within the [unifiedjs](https://unifiedjs.com/) system.
+
+## Installation
+
+```bash
+npm i -D remark-extend
+```
+
+````js
+const unified = require('unified');
+const markdown = require('remark-parse');
+const mdStringify = require('remark-html');
+
+const { remarkExtend } = require('remark-extend');
+
+const sourceMd = [
+  //
+  '# Headline',
+  "```js ::import('@name/pkg/README.md')",
+  '```',
+].join('\n');
+
+const parser = unified().use(markdown).use(remarkExtend).use(mdStringify);
+const result = await parser.process(sourceMd);
+````
+
+## Importing a block
+
+In many cases, the full file might be too much so you want to import a "block".
+A block starts with a headline and ends when the next headline of an equal level starts.
+
+```md
+## Block one
+
+Content of block one
+
+## Block two
+
+Content of block two
+
+### Sub headline in block two
+
+Still content of block two
+
+## Block three
+
+Content of block three
+```
+
+Now if you wish to import only block two you can write.
+
+````md
+# Blew you will find Block two
+
+```js ::importBlock('./path/to/file.md', '## Block two')
+
+```
+````
+
+### Result after import
+
+```md
+# Blew you will find Block two
+
+## Block two
+
+Content of block two
+
+### Sub headline in block two
+
+Still content of block two
+```
+
+PS: importBlock is a faster way of writing imports for headlines
+
+```md
+::importBlock('./path/to/file.md', '## red')
+// is the same as
+::import('./path/to/file.md', 'heading[depth=2]:has([value=red])', 'heading[depth=2]:has([value=red]) ~heading[depth=2]')
+```
+
+## Block Variations
+
+Besides block there are is also `::importBlockContent`, `::importSmallBlock` and `::importSmallBlockContent`.
+
+- `::importBlockContent` will take the same block (headline to next headline of equal level) but excludes the headline.
+- `::importSmallBlock` will import a small block (headline to any next headline)
+
+Given the following content let's compare what the content would be.
+
+```md
+# My Package
+
+Intro to my Package
+
+## Installation
+
+How to install my package
+```
+
+### `::importBlock('./path/to/file.md', '# My Package')`
+
+```md
+# My Package
+
+Intro to my Package
+
+## Installation
+
+How to install my package
+```
+
+### `::importBlockContent('./path/to/file.md', '# My Package')`
+
+```md
+Intro to my Package
+
+## Installation
+
+How to install my package
+```
+
+### `::importSmallBlock('./path/to/file.md', '# My Package')`
+
+```md
+# My Package
+
+Intro to my Package
+```
+
+### `::importSmallBlockContent('./path/to/file.md', '# My Package')`
+
+```md
+Intro to my Package
+```
+
+---
+
+## Adjusting imported content
+
+If a function gets placed in the import code block then it does get called for every node from the starting point (including the starting point).
+
+Note: does work for `::import` and `::importBlock`
+
+### Adjustment Input File
+
+👉 `file.md`
+
+```md
+### Red
+
+red is the fire
+```
+
+#### Adjustment Extending File
+
+The goal is to replace all red with green.
+
+````md
+# Below you will not find any read
+
+```js ::import('./path/to/file.md')
+module.exports.replaceSection = node => {
+  if (node.value) {
+    node.value = node.value.replace(/red/g, 'green').replace(/Red/g, 'Green');
+  }
+  return node;
+};
+```
+````
+
+This function gets called with these nodes in order.
+
+1. root
+2. heading
+3. text
+4. paragraph
+5. text
+
+#### Adjustment Result
+
+```md
+# Below you will not find any 'red'
+
+### Green
+
+green is the fire
+```
+
+---
+
+It's also possible to globally define a replace function.
+The example below shows the config object that is provided to the `remarkExtend` function.
+Note that local replacements are run after global replacements.
+
+```js
+{ 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;
+}};
+```
+
+## Import selection
+
+For `::import` you can provide a start and end selector based on [unist-util-select](https://github.com/syntax-tree/unist-util-select#support).
+
+Some examples are:
+
+- `:root` for the top of the markdown file
+- `:scope:last-child` for the end of the markdown file
+- `heading:has([value=Red])` first heading with a text value of Red (e.g. ### Red)
+- `heading[depth=2]` first second level heading (e.g. ## Something)
+- `heading[depth=2]:has([value=Red]) ~ heading[depth=2]` following h2 after h2 with "Red" (e.g. ## Red ... ## Something)
+
+### Markdown AST
+
+All adjustments to the markdown file happen via the markdown AST (Abstract Syntax Tree).
+
+You can explore it via the [ASTExplorer](https://astexplorer.net/). (> Markdown > remark)
+
+```md
+### Red
+
+red is the fire
+```
+
+Resulting AST.
+
+```json
+{
+  "type": "root",
+  "children": [
+    {
+      "type": "heading",
+      "depth": 3,
+      "children": [
+        {
+          "type": "text",
+          "value": "Red"
+        }
+      ]
+    },
+    {
+      "type": "paragraph",
+      "children": [
+        {
+          "type": "text",
+          "value": "red is the fire"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Usage in import
+
+If you full control of what the start and end selector should be then you can use `::import`.
+
+To for example import everything that is between `## Red` and `## More Red` you can use something like this.
+
+````md
+```::import('./path/to/file.md', 'heading[depth=2]:has([value=Red])', 'heading[depth=2]:has([value=More Red])')
+
+```
+````

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

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