jprdonnelly/nebula.js
1
0
Fork 0
mirror of https://github.com/qlik-oss/nebula.js.git synced 2025-12-19 17:58:43 -05:00
Code Issues Projects Releases Wiki Activity

docs(nucleus): update jsdoc (#366)

Browse Source
This commit is contained in:
Miralem Drek
2020-03-20 13:21:20 +01:00
committed by GitHub
parent faaaed822a
commit 3670b64ad4
3 changed files with 330 additions and 336 deletions
Download Patch File Download Diff File Expand all files Collapse all files

400
apis/nucleus/spec/spec.json
View File

@@ -10,7 +10,7 @@
"entries": {
"nucleus": {
"description": "Initiates a new `Nucleus` instance using the specified `app`.",
"kind": "function",
"kind": "interface",
"params": [
{
"name": "app",
@@ -25,7 +25,6 @@
"returns": {
"type": "#/definitions/Nucleus"
},
"examples": ["import nucleus from '@nebula.js/nucleus'\nconst n = nucleus(app);\nn.render({ id: 'abc' });"],
"entries": {
"createConfiguration": {
"description": "Creates a new `nucleus` scope bound to the specified `configuration`.\n\nThe configuration is merged with all previous scopes.",
@@ -44,10 +43,180 @@
"import nucleus from '@nebula.js/nucleus';\n// create a 'master' config which registers all types\nconst m = nucleus.createConfiguration({\n types: [{\n name: 'mekko',\n version: '1.0.0',\n load: () => Promise.resolve(mekko)\n }],\n});\n\n// create an alternate config with dark theme\n// and inherit the config from the previous\nconst d = m.createConfiguration({\n theme: 'dark'\n});\n\nm(app).render({ type: 'mekko' }); // will render the object with default theme\nd(app).render({ type: 'mekko' }); // will render the object with 'dark' theme\nnucleus(app).render({ type: 'mekko' }); // will throw error since 'mekko' is not a register type on the default instance"
]
}
}
},
"examples": ["import nucleus from '@nebula.js/nucleus'\nconst n = nucleus(app);\nn.render({ id: 'abc' });"]
}
},
"definitions": {
"Context": {
"kind": "interface",
"entries": {
"constraints": {
"optional": true,
"kind": "object",
"entries": {
"active": {
"optional": true,
"type": "boolean"
},
"passive": {
"optional": true,
"type": "boolean"
},
"select": {
"optional": true,
"type": "boolean"
}
}
},
"theme": {
"optional": true,
"defaultValue": "light",
"type": "string"
},
"language": {
"optional": true,
"defaultValue": "en-US",
"type": "string"
}
}
},
"Configuration": {
"kind": "interface",
"entries": {
"context": {
"optional": true,
"type": "#/definitions/Context"
},
"types": {
"optional": true,
"kind": "array",
"items": {
"type": "#/definitions/TypeInfo"
}
},
"themes": {
"optional": true,
"kind": "array",
"items": {
"type": "#/definitions/ThemeInfo"
}
},
"env": {
"optional": true,
"type": "object"
}
}
},
"Nucleus": {
"kind": "class",
"entries": {
"render": {
"description": "Renders a supernova into an HTMLElement.",
"kind": "function",
"params": [
{
"name": "cfg",
"description": "The render configuration.",
"kind": "union",
"items": [
{
"type": "#/definitions/CreateConfig"
},
{
"type": "#/definitions/GetConfig"
}
]
}
],
"returns": {
"description": "A controller to the rendered supernova",
"type": "Promise",
"generics": [
{
"type": "#/definitions/SupernovaController"
}
]
},
"examples": [
"// render from existing object\nn.render({\n element: el,\n id: 'abcdef'\n});",
"// render on the fly\nn.render({\n type: 'barchart',\n fields: ['Product', { qLibraryId: 'u378hn', type: 'measure' }]\n});"
]
},
"context": {
"description": "Updates the current context of this nucleus instance.\nUse this when you want to change some part of the current context, like theme.",
"kind": "function",
"params": [
{
"name": "ctx",
"description": "The context to update.",
"type": "#/definitions/Context"
}
],
"returns": {
"type": "Promise",
"generics": [
{
"type": "undefined"
}
]
},
"examples": [
"// change theme\nn.context({ theme: 'dark'});",
"// limit constraints\nn.context({ constraints: { active: true } });"
]
},
"selections": {
"description": "Gets the app selections of this instance.",
"kind": "function",
"params": [],
"returns": {
"type": "Promise",
"generics": [
{
"type": "#/definitions/AppSelections"
}
]
},
"examples": ["const selections = await n.selections();\nselections.mount(element);"]
}
}
},
"ThemeInfo": {
"kind": "interface",
"entries": {
"id": {
"description": "Theme identifier",
"type": "string"
},
"load": {
"description": "A function that should return a Promise that resolve to a raw JSON theme",
"kind": "function",
"params": [],
"returns": {
"type": "Promise",
"generics": [
{
"type": "ThemeJSON"
}
]
}
}
}
},
"SupernovaController": {
"description": "A controller to further modify a supernova after it has been rendered.",
"kind": "class",
"entries": {
"destroy": {
"description": "Destroys the supernova and removes if from the the DOM.",
"kind": "function",
"params": [],
"examples": ["const ctl =\nctl.destroy();"]
}
},
"examples": ["const ctl = await nucleus(app).render({\n element,\n type: 'barchart'\n});\nctl.destroy();"]
},
"AppSelections": {
"kind": "class",
"entries": {
@@ -70,78 +239,6 @@
}
}
},
"BaseConfig": {
"kind": "interface",
"entries": {
"element": {
"type": "HTMLElement"
},
"options": {
"optional": true,
"type": "object"
}
}
},
"Configuration": {
"kind": "interface",
"entries": {
"context": {
"optional": true,
"type": "#/definitions/Context"
},
"env": {
"optional": true,
"type": "object"
},
"themes": {
"optional": true,
"kind": "array",
"items": {
"type": "#/definitions/ThemeInfo"
}
},
"types": {
"optional": true,
"kind": "array",
"items": {
"type": "#/definitions/TypeInfo"
}
}
}
},
"Context": {
"kind": "interface",
"entries": {
"constraints": {
"optional": true,
"kind": "object",
"entries": {
"active": {
"optional": true,
"type": "boolean"
},
"passive": {
"optional": true,
"type": "boolean"
},
"select": {
"optional": true,
"type": "boolean"
}
}
},
"language": {
"optional": true,
"defaultValue": "en-US",
"type": "string"
},
"theme": {
"optional": true,
"defaultValue": "light",
"type": "string"
}
}
},
"CreateConfig": {
"extends": [
{
@@ -158,10 +255,15 @@
},
"fields": {
"optional": true,
"kind": "array",
"items": {
"type": "#/definitions/Field"
}
"kind": "union",
"items": [
{
"kind": "array",
"items": {
"type": "#/definitions/Field"
}
}
]
},
"properties": {
"optional": true,
@@ -169,6 +271,31 @@
}
}
},
"BaseConfig": {
"kind": "interface",
"entries": {
"element": {
"type": "HTMLElement"
},
"options": {
"optional": true,
"type": "object"
}
}
},
"GetConfig": {
"extends": [
{
"type": "#/definitions/BaseConfig"
}
],
"kind": "interface",
"entries": {
"id": {
"type": "string"
}
}
},
"Field": {
"kind": "alias",
"items": {
@@ -189,19 +316,6 @@
]
}
},
"GetConfig": {
"extends": [
{
"type": "#/definitions/BaseConfig"
}
],
"kind": "interface",
"entries": {
"id": {
"type": "string"
}
}
},
"LibraryField": {
"kind": "interface",
"entries": {
@@ -213,11 +327,11 @@
"items": [
{
"kind": "literal",
"value": "'dimension'"
"value": "dimension"
},
{
"kind": "literal",
"value": "'measure'"
"value": "measure"
}
]
}
@@ -253,110 +367,18 @@
},
"entries": {}
},
"Nucleus": {
"kind": "class",
"entries": {
"context": {
"description": "Updates the current context of this nucleus instance.\nUse this when you want to change some part of the current context, like theme.",
"kind": "function",
"params": [
{
"name": "ctx",
"description": "The context to update.",
"type": "#/definitions/Context"
}
],
"examples": [
"// change theme\nn.context({ theme: 'dark'});",
"// limit constraints\nn.context({ constraints: { active: true } });"
]
},
"render": {
"description": "Renders a supernova into an HTMLElement.",
"kind": "function",
"params": [
{
"name": "cfg",
"description": "The render configuration.",
"kind": "union",
"items": [
{
"type": "#/definitions/CreateConfig"
},
{
"type": "#/definitions/GetConfig"
}
]
}
],
"returns": {
"description": "A controller to the rendered supernova",
"type": "Promise",
"generics": [
{
"type": "#/definitions/SupernovaController"
}
]
},
"examples": [
"// render from existing object\nn.render({\n element: el,\n id: 'abcdef'\n});",
"// render on the fly\nn.render({\n type: 'barchart',\n fields: ['Product', { qLibraryId: 'u378hn', type: 'measure' }]\n});"
]
},
"selections": {
"description": "Gets the app selections of this instance.",
"kind": "function",
"params": [],
"returns": {
"type": "Promise",
"generics": [
{
"type": "#/definitions/AppSelections"
}
]
},
"examples": ["const selections = await n.selections();\nselections.mount(element);"]
}
}
},
"SupernovaController": {
"description": "A controller to further modify a supernova after it has been rendered.",
"kind": "class",
"entries": {
"destroy": {
"description": "Destroys the supernova and removes if from the the DOM.",
"kind": "function",
"params": [],
"examples": ["const ctl =\nctl.destroy();"]
}
},
"examples": ["const ctl = await nucleus(app).render({\n element,\n type: 'barchart'\n});\nctl.destroy();"]
},
"ThemeInfo": {
"kind": "interface",
"entries": {
"id": {
"description": "Theme identifier",
"type": "string"
},
"load": {
"description": "A function that should return a Promise that resolve to a raw JSON theme",
"type": "function"
}
}
},
"TypeInfo": {
"kind": "interface",
"entries": {
"load": {
"type": "#/definitions/LoadType"
},
"name": {
"type": "string"
},
"version": {
"type": "string"
},
"load": {
"type": "#/definitions/LoadType"
},
"meta": {
"optional": true,
"type": "object"

16
apis/nucleus/src/index.js
View File

@@ -9,12 +9,6 @@ import create from './object/create-session-object';
import get from './object/get-object';
import { create as typesFn } from './sn/types';
/**
* @interface ThemeInfo
* @property {string} id Theme identifier
* @property {function(): Promise<ThemeJSON>} load A function that should return a Promise that resolve to a raw JSON theme
*/
/**
* @interface Context
* @property {object=} constraints
@@ -113,7 +107,7 @@ function nuked(configuration = {}) {
/**
* Initiates a new `Nucleus` instance using the specified `app`.
* @entry
* @alias nucleus
* @interface nucleus
* @param {enigma.Doc} app
* @param {Configuration=} instanceConfig
* @returns {Nucleus}
@@ -223,6 +217,7 @@ function nuked(configuration = {}) {
* Updates the current context of this nucleus instance.
* Use this when you want to change some part of the current context, like theme.
* @param {Context} ctx - The context to update.
* @returns {Promise<undefined>}
* @example
* // change theme
* n.context({ theme: 'dark'});
@@ -320,6 +315,7 @@ function nuked(configuration = {}) {
* Creates a new `nucleus` scope bound to the specified `configuration`.
*
* The configuration is merged with all previous scopes.
* @memberof nucleus
* @param {Configuration} configuration - The configuration object
* @returns {nucleus}
* @example
@@ -349,4 +345,10 @@ function nuked(configuration = {}) {
return nucleus;
}
/**
* @interface ThemeInfo
* @property {string} id Theme identifier
* @property {function(): Promise<ThemeJSON>} load A function that should return a Promise that resolve to a raw JSON theme
*/
export default nuked(DEFAULT_CONFIG);

250
docs/nucleus-reference.md
View File

@@ -5,31 +5,30 @@ title: API Reference
## Table of contents
- [function: nucleus(app[, instanceConfig])](#function-nucleusapp-instanceconfig)
- [nucleus.createConfiguration(configuration)](#nucleuscreateconfigurationconfiguration)
- [interface: nucleus(app[, instanceConfig])](#interface-nucleusapp-instanceconfig)
- [interface: Context](#interface-context)
- [interface: Configuration](#interface-configuration)
- [class: Nucleus](#class-nucleus)
- [nucleus.render(cfg)](#nucleusrendercfg)
- [nucleus.context(ctx)](#nucleuscontextctx)
- [nucleus.selections()](#nucleusselections)
- [interface: ThemeInfo](#interface-themeinfo)
- [class: SupernovaController](#class-supernovacontroller)
- [supernovaController.destroy()](#supernovacontrollerdestroy)
- [class: AppSelections](#class-appselections)
- [appSelections.mount(element)](#appselectionsmountelement)
- [appSelections.unmount()](#appselectionsunmount)
- [interface: BaseConfig](#interface-baseconfig)
- [interface: Configuration](#interface-configuration)
- [interface: Context](#interface-context)
- [interface: CreateConfig](#interface-createconfig)
- [type `Field`= <[string]|`qae.NxDimension`|`qae.NxMeasure`|[LibraryField]>](#type-field-stringqaenxdimensionqaenxmeasurelibraryfield)
- [interface: BaseConfig](#interface-baseconfig)
- [interface: GetConfig](#interface-getconfig)
- [type Field = <[string]|[qae.NxDimension]|[qae.NxMeasure]|[LibraryField]>](#type-field-stringqaenxdimensionqaenxmeasurelibraryfield)
- [interface: LibraryField](#interface-libraryfield)
- [interface: LoadType(type, env)](#interface-loadtypetype-env)
- [class: Nucleus](#class-nucleus)
- [nucleus.context(ctx)](#nucleuscontextctx)
- [nucleus.render(cfg)](#nucleusrendercfg)
- [nucleus.selections()](#nucleusselections)
- [class: SupernovaController](#class-supernovacontroller)
- [supernovaController.destroy()](#supernovacontrollerdestroy)
- [interface: ThemeInfo](#interface-themeinfo)
- [interface: TypeInfo](#interface-typeinfo)
## API
### function: nucleus(app[, instanceConfig])
### interface: nucleus(app[, instanceConfig])
- `app` <`enigma.Doc`>
- `instanceConfig` <[Configuration]>
@@ -43,129 +42,28 @@ const n = nucleus(app);
n.render({ id: 'abc' });
```
#### nucleus.createConfiguration(configuration)
- `configuration` <[Configuration]> The configuration object
- `returns:` <[nucleus]>
Creates a new `nucleus` scope bound to the specified `configuration`.
- `createConfiguration` <[Function]> Creates a new `nucleus` scope bound to the specified `configuration`.
The configuration is merged with all previous scopes.
```js
import nucleus from '@nebula.js/nucleus';
// create a 'master' config which registers all types
const m = nucleus.createConfiguration({
types: [
{
name: 'mekko',
version: '1.0.0',
load: () => Promise.resolve(mekko),
},
],
});
// create an alternate config with dark theme
// and inherit the config from the previous
const d = m.createConfiguration({
theme: 'dark',
});
m(app).render({ type: 'mekko' }); // will render the object with default theme
d(app).render({ type: 'mekko' }); // will render the object with 'dark' theme
nucleus(app).render({ type: 'mekko' }); // will throw error since 'mekko' is not a register type on the default instance
```
### class: AppSelections
#### appSelections.mount(element)
- `element` <`HTMLElement`>
Mounts the app selection UI into the provided HTMLElement
```js
selections.mount(element);
```
#### appSelections.unmount()
Unmounts the app selection UI from the DOM
```js
selections.unmount();
```
### interface: BaseConfig
- `element` <`HTMLElement`>
- `options` <[Object]>
### interface: Configuration
- `context` <[Context]>
- `env` <[Object]>
- `themes` <[Array]<[ThemeInfo]>>
- `types` <[Array]<[TypeInfo]>>
### interface: Context
- `constraints` <[Object]>
- `active` <[boolean]>
- `passive` <[boolean]>
- `select` <[boolean]>
- `language` <[string]> Defaults to `en-US`
- `theme` <[string]> Defaults to `light`
- `language` <[string]> Defaults to `en-US`
### interface: CreateConfig
### interface: Configuration
- extends: <[BaseConfig]>
* `type` <[string]>
* `version` <[string]>
* `fields` <[Array]<[Field]>>
* `properties` <`qae.GenericObjectProperties`>
### type `Field`= <[string]|`qae.NxDimension`|`qae.NxMeasure`|[LibraryField]>
### interface: GetConfig
- extends: <[BaseConfig]>
* `id` <[string]>
### interface: LibraryField
- `qLibraryId` <[string]>
- `type` <`'dimension'`|`'measure'`>
### interface: LoadType(type, env)
- `type` <[Object]>
- `name` <[string]>
- `version` <[string]>
- `context` <[Context]>
- `types` <[Array]<[TypeInfo]>>
- `themes` <[Array]<[ThemeInfo]>>
- `env` <[Object]>
- `returns:` <[Promise]<`Supernova`>>
### class: Nucleus
#### nucleus.context(ctx)
- `ctx` <[Context]> The context to update.
Updates the current context of this nucleus instance.
Use this when you want to change some part of the current context, like theme.
```js
// change theme
n.context({ theme: 'dark' });
```
```js
// limit constraints
n.context({ constraints: { active: true } });
```
#### nucleus.render(cfg)
- `cfg` <[CreateConfig]|[GetConfig]> The render configuration.
@@ -189,6 +87,24 @@ n.render({
});
```
#### nucleus.context(ctx)
- `ctx` <[Context]> The context to update.
- `returns:` <[Promise]<[undefined]>>
Updates the current context of this nucleus instance.
Use this when you want to change some part of the current context, like theme.
```js
// change theme
n.context({ theme: 'dark' });
```
```js
// limit constraints
n.context({ constraints: { active: true } });
```
#### nucleus.selections()
- `returns:` <[Promise]<[AppSelections]>>
@@ -200,6 +116,11 @@ const selections = await n.selections();
selections.mount(element);
```
### interface: ThemeInfo
- `id` <[string]> Theme identifier
- `load` <[Function]> A function that should return a Promise that resolve to a raw JSON theme
### class: SupernovaController
A controller to further modify a supernova after it has been rendered.
@@ -220,41 +141,90 @@ Destroys the supernova and removes if from the the DOM.
const ctl = ctl.destroy();
```
### interface: ThemeInfo
### class: AppSelections
- `id` <[string]> Theme identifier
- `load` <[Function]> A function that should return a Promise that resolve to a raw JSON theme
#### appSelections.mount(element)
- `element` <`HTMLElement`>
Mounts the app selection UI into the provided HTMLElement
```js
selections.mount(element);
```
#### appSelections.unmount()
Unmounts the app selection UI from the DOM
```js
selections.unmount();
```
### interface: CreateConfig
- extends: <[BaseConfig]>
* `type` <[string]>
* `version` <[string]>
* `fields` <[Array]>
* `properties` <[qae.GenericObjectProperties]>
### interface: BaseConfig
- `element` <`HTMLElement`>
- `options` <[Object]>
### interface: GetConfig
- extends: <[BaseConfig]>
* `id` <[string]>
### type Field = <[string]|[qae.NxDimension]|[qae.NxMeasure]|[LibraryField]>
### interface: LibraryField
- `qLibraryId` <[string]>
- `type` <`dimension`|`measure`>
### interface: LoadType(type, env)
- `type` <[Object]>
- `name` <[string]>
- `version` <[string]>
- `env` <[Object]>
- `returns:` <[Promise]<`Supernova`>>
### interface: TypeInfo
- `load` <[LoadType]>
- `name` <[string]>
- `version` <[string]>
- `load` <[LoadType]>
- `meta` <[Object]>
[enigma.doc]: undefined
[htmlelement]: undefined
[function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function
[object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object
[array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
[boolean]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type
[qae.genericobjectproperties]: undefined
[qae.nxdimension]: undefined
[qae.nxmeasure]: undefined
[supernova]: undefined
[array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
[promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
[function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function
[nucleus]: #function-nucleusapp-instanceconfig
[appselections]: #class-appselections
[baseconfig]: #interface-baseconfig
[configuration]: #interface-configuration
[undefined]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined
[htmlelement]: undefined
[qae.genericobjectproperties]: https://core.qlik.com/services/qix-engine/apis/qix/definitions/#genericobjectproperties
[qae.nxdimension]: https://core.qlik.com/services/qix-engine/apis/qix/definitions/#nxdimension
[qae.nxmeasure]: https://core.qlik.com/services/qix-engine/apis/qix/definitions/#nxmeasure
[supernova]: undefined
[context]: #interface-context
[configuration]: #interface-configuration
[nucleus]: #class-nucleus
[themeinfo]: #interface-themeinfo
[supernovacontroller]: #class-supernovacontroller
[appselections]: #class-appselections
[createconfig]: #interface-createconfig
[field]: #type-field-stringqaenxdimensionqaenxmeasurelibraryfield
[baseconfig]: #interface-baseconfig
[getconfig]: #interface-getconfig
[libraryfield]: #interface-libraryfield
[loadtype]: #interface-loadtypetype-env
[nucleus]: #class-nucleus
[supernovacontroller]: #class-supernovacontroller
[themeinfo]: #interface-themeinfo
[typeinfo]: #interface-typeinfo