qlik-oss/nebula.js/nebula-chart-dev

npx @nebula.js/cli create <name> --picasso none   # plain canvas/DOM chart
npx @nebula.js/cli create <name> --picasso minimal # picasso.js scaffold
npx @nebula.js/cli create <name>                  # full picasso barchart scaffold

npm run start   # start nebula dev server with hot reload
npm run build   # bundle to /dist
npm run sense   # bundle as Qlik Sense extension to /name-ext/

import { useElement, useLayout, useEffect } from '@nebula.js/stardust';
import properties from './object-properties';
import data from './data';
import ext from './ext';
export default function supernova(galaxy) {
  return {
    qae: { properties, data },
    ext: ext(galaxy),
    component() {
      // All hooks MUST be called here, at the top level — never conditionally
      const element = useElement();
      const layout = useLayout();
      useEffect(() => {
        element.innerHTML = `<p>${layout.title}</p>`;
      }, [element, layout]);
    },
  };
}

const element = useElement();
element.innerHTML = '<p>Hello</p>';

// Picasso / most charts — render from stale, don't re-render mid-selection
const layout = useStaleLayout();
// Table / charts that must update their highlight state
const layout = useLayout();
useEffect(() => {
  if (layout.qSelectionInfo.qInSelections) {
    // optionally skip heavy re-render
    return;
  }
  // ...render...
}, [layout]);

import { useModel, usePromise, useEffect } from '@nebula.js/stardust';
const model = useModel();
// GOOD — framework waits for this before considering chart "rendered"
const [layout, error] = usePromise(() => model.getLayout(), [model]);
useEffect(() => {
  if (!layout) return;
  // render with layout
}, [layout]);

// BAD for printing — framework does not know to wait
useEffect(() => {
  model.getLayout().then((layout) => {
    // render...
  });
}, [model]);

const layout = useLayout();
const [data, err] = usePromise(async () => {
  if (!layout?.qHyperCube?.qDataPages[0]?.qMatrix.length) {
    throw new Error('No data');
  }
  // async processing (e.g. fetch enrichment data)
  return processRows(layout.qHyperCube.qDataPages[0].qMatrix);
}, [layout]);
useEffect(() => {
  if (!data) return;
  renderChart(element, data);
}, [data, element]);

import { useTheme, useEffect } from '@nebula.js/stardust';
const theme = useTheme();
useEffect(() => {
  const bgColor = theme.getStyle('object', '', 'backgroundColor') ?? '#ffffff';
  const fgColor = theme.getContrastingColorTo(bgColor);
  element.style.background = bgColor;
  element.style.color = fgColor;
}, [theme, element]);

// Font size for chart titles
theme.getStyle('object', 'title.main', 'fontSize');
// Same — attribute dotted notation
theme.getStyle('object', '', 'title.main.fontSize');
// Global font size fallback
theme.getStyle('', '', 'fontSize');

import { useRect, useEffect } from '@nebula.js/stardust';
const rect = useRect();
// Only re-render when dimensions change
useEffect(() => {
  if (!instance) return;
  instance.resize(rect.width, rect.height);
  instance.update();
}, [rect.width, rect.height, instance]);

import { useSelections, useElement, useState, useEffect } from '@nebula.js/stardust';
const selections = useSelections();
const [selectedRows, setSelectedRows] = useState([]);
// Add click listener (register in one effect, keeping it stable)
useEffect(() => {
  const onClick = (e) => {
    if (e.target.tagName !== 'TD') return;
    if (!selections.isActive()) {
      selections.begin('/qHyperCubeDef');
    }
    const row = +e.target.parentElement.getAttribute('data-row');
    setSelectedRows((prev) => (prev.includes(row) ? prev.filter((v) => v !== row) : [...prev, row]));
  };
  element.addEventListener('click', onClick);
  return () => element.removeEventListener('click', onClick);
}, [element]);
// Commit or clear selections when rows change
useEffect(() => {
  if (selections.isActive()) {
    if (selectedRows.length) {
      selections.select({ method: 'selectHyperCubeCells', params: ['/qHyperCubeDef', selectedRows, []] });
    } else {
      selections.select({ method: 'resetMadeSelections', params: [] });
    }
  } else if (selectedRows.length) {
    setSelectedRows([]);
  }
}, [selections.isActive(), selectedRows]);

import { useInteractionState } from '@nebula.js/stardust';
const interactions = useInteractionState();
// interactions.active  — true = user can click/scroll
// interactions.select  — true = selections allowed
// interactions.passive — true = tooltips allowed
// interactions.edit    — true = edit mode active
useEffect(() => {
  if (!interactions.active) return; // don't add listeners in passive/view mode
  element.addEventListener('click', handler);
  return () => element.removeEventListener('click', handler);
}, [interactions.active]);

// src/components/root.jsx
import React from 'react';
import { createRoot } from 'react-dom/client';
import MyChart from './MyChart';
export function render(element, props) {
  const root = createRoot(element);
  root.render(<MyChart {...props} />);
  return root;
}
export function teardown(root) {
  root.unmount();
}

// src/index.js
import { useElement, useLayout, useEffect } from '@nebula.js/stardust';
import { render, teardown } from './components/root';