@nebula.js/stardust

v0.6.0-alpha.0
experimental

Product and framework agnostic integration API for Qlik's Associative Engine

experimental

Initiates a new embed instance using the specified app.

Parameters

app
enigma.Doc

No description

instanceConfig

No description

Returns

No description

import { embed } from '@nebula.js/stardust'
const n = embed(app);
n.render({ id: 'abc' });
experimental

Creates a new embed scope bound to the specified configuration.

The configuration is merged with all previous scopes.

Parameters

configuration

The configuration object

Returns

No description

import { embed } from '@nebula.js/stardust';
// create a 'master' config which registers all types
const m = embed.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
embed(app).render({ type: 'mekko' }); // will throw error since 'mekko' is not a register type on the default instance
experimental

Creates a stateful value.

Parameters

initialState
S | function

The initial state.

Returns

Array<S, SetStateFn>

The value and a function to update it.

import { useState } from '@nebula.js/stardust';
// ...
// initiate with simple primitive value
const [zoomed, setZoomed] = useState(false);

// update
setZoomed(true);

// lazy initiation
const [value, setValue] = useState(() => heavy());
experimental

Triggers a callback function when a dependant value changes.

Parameters

effect

The callback.

deps
optional
Array<any>

The dependencies which should trigger the callback.

import { useEffect } from '@nebula.js/stardust';
// ...
useEffect(() => {
  console.log('mounted');
  return () => {
    console.log('unmounted');
  };
}, []);
experimental

Creates a stateful value when a dependant changes.

Parameters

factory
function

The factory function.

deps
Array<any>

The dependencies.

Returns

T

The value returned from the factory function.

import { useMemo } from '@nebula.js/stardust';
// ...
const v = useMemo(() => {
  return doSomeHeavyCalculation();
}), []);
experimental

Runs a callback function when a dependant changes.

Parameters

factory
function

The factory function that calls the promise.

deps
optional
Array<any>

The dependencies.

Returns

Array<P, Error>

The resolved value.

import { usePromise } from '@nebula.js/stardust';
import { useModel } from '@nebula.js/stardust';
// ...
const model = useModel();
const [resolved, rejected] = usePromise(() => model.getLayout(), []);

useElement
()

function
experimental

Gets the HTMLElement this supernova is rendered into.

Returns

HTMLElement

No description

import { useElement } from '@nebula.js/stardust';
// ...
const el = useElement();
el.innerHTML = 'Hello!';

useRect
()

function
experimental

Gets the size of the HTMLElement the supernova is rendered into.

Returns

The size of the element.

import { useRect } from '@nebula.js/stardust';
// ...
const rect = useRect();
useEffect(() => {
  console.log('resize');
}, [rect.width, rect.height])

useLayout
()

function
experimental

Gets the layout of the generic object associated with this supernova.

Returns

qae.GenericObjectLayout

No description

import { useLayout } from '@nebula.js/stardust';
// ...
const layout = useLayout();
console.log(layout);
experimental

Gets the layout of the generic object associated with this supernova.

Unlike the regular layout, a stale layout is not changed when a generic object enters
the modal state. This is mostly notable in that qSelectionInfo.qInSelections in the layout is
always false.
The returned value from useStaleLayout() and useLayout() are identical when the object
is not in a modal state.

Returns

qae.GenericObjectLayout

No description

import { useStaleLayout } from '@nebula.js/stardust';
// ...
const staleLayout = useStaleLayout();
console.log(staleLayout);
experimental

Gets the layout of the app associated with this supernova.

Returns

qae.NxAppLayout

The app layout

import { useAppLayout } from '@nebula.js/stardust';
// ...
const appLayout = useAppLayout();
console.log(appLayout.qLocaleInfo);

useModel
()

function
experimental

Gets the generic object API of the generic object connected to this supernova.

Returns

enigma.GenericObject | undefined

No description

import { useModel } from '@nebula.js/stardust';
// ...
const model = useModel();
useEffect(() => {
  model.getInfo().then(info => {
    console.log(info);
  })
}, []);

useApp
()

function
experimental

Gets the doc API.

Returns

enigma.Doc | undefined

The doc API.

import { useApp } from '@nebula.js/stardust';
// ...
const app = useApp();
useEffect(() => {
  app.getAllInfos().then(infos => {
    console.log(infos);
  })
}, []);

useGlobal
()

function
experimental

Gets the global API.

Returns

enigma.Global | undefined

The global API.

import { useGlobal } from '@nebula.js/stardust';

// ...
const g = useGlobal();
useEffect(() => {
  g.engineVersion().then(version => {
    console.log(version);
  })
}, []);
experimental

Gets the object selections.

Returns

The object selections.

import { useSelections } from '@nebula.js/stardust';
import { useElement } from '@nebula.js/stardust';
import { useEffect } from '@nebula.js/stardust';
// ...
const selections = useSelections();
const element = useElement();
useEffect(() => {
  const onClick = () => {
    selections.begin('/qHyperCubeDef');
  };
  element.addEventListener('click', onClick);
  return () => {
    element.removeEventListener('click', onClick);
  };
}, []);

useTheme
()

function
experimental

Gets the theme.

Returns

The theme.

import { useTheme } from '@nebula.js/stardust';

const theme = useTheme();
console.log(theme.getContrastinColorTo('#ff0000'));
experimental

Gets the translator.

Returns

The translator.

import { useTranslator } from '@nebula.js/stardust';
// ...
const translator = useTranslator();
console.log(translator.get('SomeString'));
experimental

Registers a custom action.

Parameters

factory
function

No description

deps
optional
Array<any>

No description

Returns

A

No description

import { useAction } from '@nebula.js/stardust';
// ...
const [zoomed, setZoomed] = useState(false);
const act = useAction(() => ({
  hidden: false,
  disabled: zoomed,
  action() {
    setZoomed(prev => !prev);
  },
  icon: {}
}), [zoomed]);
experimental

Gets the desired constraints that should be applied when rendering the supernova.

The constraints are set on the nuclues configuration before the supernova is rendered
and should respected by you when implementing the supernova.

Returns

No description

// configure embed to disallow active interactions when rendering
embed(app, {
  constraints: {
    active: true, // do not allow interactions
  }
}).render({ element, id: 'sdfsdf' });
import { useConstraints } from '@nebula.js/stardust';
// ...
const constraints = useConstraints();
useEffect(() => {
  if (constraints.active) {
    // do not add any event listener if active constraint is set
    return undefined;
  }
  const listener = () => {};
  element.addEventListener('click', listener);
  return () => {
    element.removeEventListener('click', listener);
  };
}, [constraints])

useOptions
()

function
experimental

Gets the options object provided when rendering the supernova.

This is an empty object by default but enables customization of the supernova through this object.
Options are different from setting properties on the generic object in that options
are only temporary settings applied to the supernova when rendered.

You have the responsibility to provide documentation of the options you support, if any.

Returns

object

No description

// when embedding the supernova, anything can be set in options
embed(app).render({
  element,
  type: 'my-chart',
  options: {
    showNavigation: true,
  }
});
// it is up to you use and implement the provided options
import { useOptions } from '@nebula.js/stardust';
import { useEffect } from '@nebula.js/stardust';
// ...
const options = useOptions();
useEffect(() => {
  if (!options.showNavigation) {
    // hide navigation
  } else {
    // show navigation
  }
}, [options.showNavigation]);
experimental

Registers a callback that is called when a snapshot is taken.

Parameters

snapshotCallback
function

No description

import { onTakeSnapshot } from '@nebula.js/stardust';
import { useState } from '@nebula.js/stardust';
import { useLayout } from '@nebula.js/stardust';

const layout = useLayout();
const [zoomed] = useState(layout.isZoomed || false);

onTakeSnapshot((copyOfLayout) => {
  copyOfLayout.isZoomed = zoomed;
  return Promise.resolve(copyOfLayout);
});

Context

interface
experimental

Properties

constraints
experimental
optional
object

No description

theme
experimental
optional, default='light'
string

No description

language
experimental
optional, default='en-US'
string

No description

Configuration

interface
experimental

Properties

context
experimental
optional

No description

types
experimental
optional
Array<any>

No description

themes
experimental
optional
Array<any>

No description

anything
experimental
optional
object

No description

experimental
experimental
experimental
experimental

Renders a visualization into an HTMLElement.

Parameters

cfg

The render configuration.

Returns

A controller to the rendered visualization

// render from existing object
n.render({
  element: el,
  id: 'abcdef'
});
// render on the fly
n.render({
  type: 'barchart',
  fields: ['Product', { qLibraryId: 'u378hn', type: 'measure' }]
});
experimental

Updates the current context of this embed instance.
Use this when you want to change some part of the current context, like theme.

Parameters

ctx

The context to update.

Returns

Promise<undefined>

No description

// change theme
n.context({ theme: 'dark'});
// limit constraints
n.context({ constraints: { active: true } });
experimental

Gets the app selections of this instance.

Returns

Promise<AppSelections>

No description

const selections = await n.selections();
selections.mount(element);

ThemeInfo

interface
experimental

Properties

id
experimental
string

Theme identifier

experimental

A function that should return a Promise that resolve to a raw JSON theme

Returns

Promise<ThemeJSON>

No description

experimental

A controller to further modify a supernova after it has been rendered.

const ctl = await embed(app).render({
  element,
  type: 'barchart'
});
ctl.destroy();
experimental

Destroys the supernova and removes if from the the DOM.

const ctl =
ctl.destroy();

Flags

interface
experimental
experimental

Checks whether the specified flag is enabled.

Parameters

flag
string

The value flag to check.

Returns

boolean

True if the specified flag is enabled, false otherwise.

CreateConfig

interface
extendsBaseConfig
experimental

Properties

type
experimental
string

No description

version
experimental
string

No description

fields
experimental
optional
Array<any>

No description

properties
experimental
optional
qae.GenericObjectProperties

No description

BaseConfig

interface
experimental

Properties

element
experimental
HTMLElement

No description

options
experimental
optional
object

No description

GetConfig

interface
extendsBaseConfig
experimental

Properties

id
experimental
string

No description

type Field

string | qae.NxDimension | qae.NxMeasure | LibraryField
experimental

LibraryField

interface
experimental

Properties

qLibraryId
experimental
string

No description

type
experimental
'dimension' | 'measure'

No description

experimental
experimental

Mounts the app selection UI into the provided HTMLElement

Parameters

element
HTMLElement

No description

selections.mount(element);
experimental

Unmounts the app selection UI from the DOM

selections.unmount();
experimental
experimental

Parameters

paths
Array<any>

No description

Returns

Promise<undefined>

No description

experimental

Returns

Promise<undefined>

No description

experimental

Returns

Promise<undefined>

No description

experimental

Returns

Promise<undefined>

No description

experimental

Parameters

s
object

No description

Returns

Promise<boolean>

No description

experimental

Returns

boolean

No description

experimental

Returns

boolean

No description

experimental

Returns

boolean

No description

experimental

Returns

boolean

No description

experimental

Returns

boolean

No description

experimental

Parameters

paths
Array<any>

No description

Returns

Promise<undefined>

No description

experimental

Parameters

accept
optional, default=false
boolean

No description

Returns

Promise<undefined>

No description

experimental

Returns

Promise<undefined>

No description

experimental

Parameters

type
object

No description

Returns

Promise<Supernova>

No description

TypeInfo

interface
experimental

Properties

name
experimental
string

No description

version
experimental
string

No description

load
experimental

No description

meta
experimental
optional
object

No description

experimental

The entry point for defining a supernova.

Parameters

galaxy
Galaxy

No description

Returns

No description

import { useElement, useLayout } from '@nebula.js/stardust';

export default function() {
  return {
    qae: {
      properties: {
        dude: 'Heisenberg',
      }
    },
    component() {
      const el = useElement();
      const layout = useLayout();
      el.innerHTML = `What's my name? ${layout.dude}!!!`;
    }
  };
}
experimental

Properties

qae
experimental

No description

experimental

Returns

void

No description

experimental

Parameters

newState
S | function

The new state

experimental

Returns

void | function

No description

Rect

interface
experimental

Properties

top
experimental
number

No description

left
experimental
number

No description

width
experimental
number

No description

height
experimental
number

No description

experimental

Properties

action
experimental
A

No description

hidden
experimental
optional
boolean

No description

disabled
experimental
optional
boolean

No description

icon
experimental
optional
object

No description

Constraints

interface
experimental

Properties

passive
experimental
optional
boolean

No description

active
experimental
optional
boolean

No description

select
experimental
optional
boolean

No description

QAEDefinition

interface
experimental

Properties

properties
experimental
optional
qae.GenericObjectProperties

No description

data
experimental
optional
object

No description

DataTarget

interface
experimental

Properties

path
experimental
string

No description

dimensions
experimental
optional

No description

measures
experimental
optional

No description

FieldTarget

interface
experimental
experimental

Returns

number

No description

experimental

Returns

number

No description

experimental

Parameters

T

No description

qae.GenericObjectProperties

No description

experimental

Parameters

T

No description

qae.GenericObjectProperties

No description

number

No description

experimental
experimental

Registers a string in multiple locales

Parameters

item
object

No description

translator.add({
  id: 'company.hello_user',
  locale: {
    'en-US': 'Hello {0}',
    'sv-SE': 'Hej {0}
  }
});
translator.get('company.hello_user', ['John']); // Hello John
experimental

Translates a string for current locale

Parameters

str
string

Id of the registered string

args
optional
Array<any>

Values passed down for string interpolation

Returns

string

The translated string

experimental
experimental

Returns

Array<any>

No description

experimental

Returns

Array<any>

No description

experimental

Returns

Array<any>

No description

experimental

Returns

No description

experimental

Resolve a color object using the color picker palette from the provided JSON theme.

Parameters

c
object

No description

Returns

string

The resolved color.

theme.getColorPickerColor({ index: 1 });
theme.getColorPickerColor({ color: 'red' });
experimental

Get the best contrasting color against the specified color.
This is typically used to find a suitable text color for a label placed on an arbitrarily colored background.

The returned colors are derived from the theme.

Parameters

color
string

A color to measure the contrast against

Returns

string
  • The color that has the best contrast against the specified color.
theme.getContrastingColorTo('#400');
experimental

Get the value of a style attribute in the theme by searching in the theme's json structure.
The search starts at the specified base path and continue upwards until the value is found.
If possible it will get the attribute's value using the given path.

Parameters

basePath
string

Base path in the theme's json structure to start the search in (specified as a name path separated by dots)

path
string

Expected path for the attribute (specified as a name path separated by dots)

attribute
string

Name of the style attribute

Returns

string

The style value

theme.getStyle('object', 'title.main', 'fontSize'));
theme.getStyle('', '', 'fontSize'));
experimental

Properties

key
experimental
string

No description

type
experimental
'gradient' | 'class'

No description

colors
experimental
Array<any>

No description

experimental

Properties

key
experimental
string

No description

type
experimental
'pyramid' | 'row'

No description

colors
experimental
Array<any> | Array<any>

No description

experimental

Properties

key
experimental
string

No description

colors
experimental
Array<any>

No description

experimental

Properties

primary
experimental
string

No description

nil
experimental
string

No description

others
experimental
string

No description