docs: initial instructions (#348)

docs/README.md

@@ -7,8 +7,9 @@ title: Introduction
 
 `nebula.js` is a collection of JavaScript libraries and APIs that helps developers integrate visualizations and mashups on top of Qlik's Associative Engine.
 
-It consists of three parts:
+It consists of :
 
 - `nucleus`: A product and framework agnostic JavaScript library for building mashups.
 - `supernova`: A JavaScript API for consuming and visualizing QIX data.
+- `snapshooter`: A JavaScript API for rendering a `supernova` in offline mode.
 - `cli`: Tools to help you create, develop and build a `supernova`.

docs/app-selections.md

@@ -0,0 +1,6 @@
+---
+id: app-selections
+title: App selections
+---
+
+TODO

docs/installation.md

@@ -0,0 +1,67 @@
+---
+id: installation
+title: Installation
+---
+
+All `nebula.js` modules are available on the public npm registry as npm packages and can be installed through either npm or as a script import.
+
+`@nebula.js/supernova` and `@nebula.js/nucleus` are the two core modules that you will be using and are required when integrating `nebula.js` on the web.
+
+## Script import
+
+The easiest way to load the modules is from a CDN like `jsdelivr`:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@nebula.js/supernova" crossorigin></script>
+<script src="https://cdn.jsdelivr.net/npm/@nebula.js/nucleus" crossorigin></script>
+```
+
+Both are UMD packages and will add the variables `supernova` and `nucleus` to the global namespace.
+
+For production, it is recommended to use a specific version of each module to avoid surprises from newer or breaking versions of the APIs:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@nebula.js/supernova@0.1.1" crossorigin></script>
+<script src="https://cdn.jsdelivr.net/npm/@nebula.js/nucleus@0.1.1" crossorigin></script>
+```
+
+## Npm or yarn
+
+If you are building your own web project using Webpack, Rollup, Parcel or similar you can install the packages with npm:
+
+```bash
+$ npm install @nebula.js/supernova @nebula.js/nucleus
+```
+
+or yarn:
+
+```bash
+$ yarn add @nebula.js/supernova @nebula.js/nucleus
+```
+
+and then import `nucleus` wherever you're using it:
+
+```js
+import nucleus from '@nebula.js/nucleus';
+```
+
+You should not need to import `@nebula.js/supernova` yourself, it is a dependency to most charts and will be resolved automatically by the bundling tool when needed.
+
+## CLI
+
+`nebula.js` provides a CLI for quickly getting started with a supernova project and provides a development server to help you during the
+development phase.
+
+```bash
+$ npm install @nebula.js/cli
+```
+
+## Development builds
+
+Some modules are available as a development build which provide more errors and warnings when detecting potentially bad usage of the APIs.
+You should only use these during the development phase of your project, never in production.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@nebula.js/supernova@0.1.1/dist/supernova.dev.js" crossorigin></script>
+<script src="https://cdn.jsdelivr.net/npm/@nebula.js/nucleus@0.1.1/dist/nucleus.dev.js" crossorigin></script>
+```

docs/nucleus-configuration.md

@@ -0,0 +1,6 @@
+---
+id: nucleus-configuration
+title: Configuration
+---
+
+TODO

docs/render-charts.md

@@ -0,0 +1,6 @@
+---
+id: render-charts
+title: Render charts
+---
+
+TODO

docs/sn-controller.md

@@ -0,0 +1,6 @@
+---
+id: sn-controller
+title: Modify charts
+---
+
+TODO

docs/web-integration.md

@@ -0,0 +1,117 @@
+---
+id: web-integration
+title: Web integration
+---
+
+Integrating `nebula.js` with your project requires the following steps:
+
+1. Connect to a Qlik Sense deployment
+1. Load `nebula.js` core modules
+1. Load chart modules
+1. Configure nucleus
+1. Render charts
+
+## Connect to Qlik
+
+The majority of communication between the web and a Qlik Sense deployment happens with a WebSocket connection, how you authenticate and create such a connection depends on the type of deployment you want to connect to. The examples will assume you are connecting to your own Qlik Cloud Services tenant and have already [configured it to allow web integrations](https://help.qlik.com/en-US/cloud-services/Subsystems/Hub/Content/Sense_Hub/Admin/mc-adminster-web-integrations.htm).
+
+The connection needs to be created using `enigma.js` which you should load first:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/enigma.js" crossorigin></script>
+```
+
+Before creating the connection, you need to fetch a `schema` which helps `enigma.js` understand how and what methods you can use to communicate with Qlik:
+
+```js
+async function connect() {
+  const schema = await (await fetch('https://cdn.jsdelivr.net/npm/enigma.js@2.6.3/schemas/12.170.2.json')).json();
+}
+```
+
+To create the connection you need to know your QCS tenant url, the `qlik-web-integration-id` and the GUID of the document you want to open:
+
+```js
+async function connect() {
+  const schema = await (await fetch('https://cdn.jsdelivr.net/npm/enigma.js@2.6.3/schemas/12.170.2.json')).json();
+
+  const enigmaGlobal = await enigma
+    .create({
+      schema,
+      url: 'wss://<tenant>.us.qlikcloud.com/app/<GUID>?qlik-web-integration-id=<qlik-web-integration-id>',
+    })
+    .open();
+
+  const enigmaApp = await enigmaGlobal.openDoc('<GUID>');
+}
+```
+
+Read more:
+
+- [Connecting to various Qlik Sense deployments](#)
+- [enigma.js](#)
+
+## Load nebula core modules
+
+Load the two core `nebula.js` modules:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@nebula.js/supernova" crossorigin></script>
+<script src="https://cdn.jsdelivr.net/npm/@nebula.js/nucleus" crossorigin></script>
+```
+
+## Load chart modules
+
+The core modules do not contain any charts by themselves, each chart is its own separate module and needs to be loaded and registered before it can be used.
+
+Official supernova chart modules from Qlik are published under the `@nebula.js` scope and are prefixed with `sn-`.
+The available charts are as follows:
+
+- Bar chart: `@nebula.js/sn-bar-chart`
+- Line chart: `@nebula.js/sn-line-chart`
+- Pie chart: `@nebula.js/sn-pie-chart`
+- Sankey chart: `@nebula.js/sn-sankey-chart`
+- Funnel chart: `@nebula.js/sn-funnel-chart`
+- Mekko chart: `@nebula.js/sn-mekko-chart`
+
+You can load a chart through a `<script>` tag:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@nebula.js/sn-bar-chart" crossorigin></script>
+```
+
+which makes it available to you on the global `window` object as `@nebula.js/sn-bar-chart`.
+
+## Render charts
+
+Before rendering the chart you need to configure `nucleus` with the supernova types you want to support:
+
+```js
+const n = nucleus.createConfiguration({
+  types: [
+    {
+      type: 'barchart',
+      load: () => Promise.resolve(window['@nebula.js/sn-bar-chart']),
+    },
+  ],
+});
+```
+
+You can then render a chart on the fly in an `HTMLElement` that has a fixed size and provide the initial `fields` to it:
+
+```js
+n(enigmaApp).render({
+  element: document.querySelector('#chart'),
+  type: 'barchart',
+  fields: ['Product', '=sum(Sales)'],
+});
+```
+
+If the `GenericObject` already exists in the app you opened, you can render it by providing its `id`:
+
+```js
+n(enigmaApp).render({
+  element: document.querySelector('#chart'),
+  id: '<ObjectID>',
+});
+```