@project-sunbird/sunbird-questionset-editor-web-component-react

A React-based authoring editor for Sunbird QuML QuestionSets (question banks organized into sections/hierarchy). It is distributed as:

• a native custom element — <sb-questionset-editor> — that can be embedded in any framework or plain HTML, and
• a React component (QuestionsetEditor) for apps that are already on React.

It replaces the older Angular questionset-editor-library and is built to be embedded by a host app (e.g. the Sunbird portal), not run standalone.

Installation

npm install @project-sunbird/sunbird-questionset-editor-web-component-react react react-dom

react and react-dom are peer dependencies (^18.0.0 || ^19.0.0) — they are not bundled and must be provided by the host page/app. The published bundle externalizes react, react-dom, react-dom/client, and react/jsx-runtime, so your app (or an import map, if you're not using a bundler) must resolve these.

The package ships as an ES module only:

| package.json field | value | |---|---| | module / entry | dist/index.js | | types | dist/index.d.ts | | stylesheet | dist/style.css (import path: @project-sunbird/sunbird-questionset-editor-web-component-react/dist/style.css) | | files | dist (everything published lives under dist/) |

The component renders in the light DOM (no Shadow DOM), so it relies on the page loading dist/style.css — it does not inject its own styles.

Static assets that must be served

The dist/ folder contains more than just index.js/style.css; it also includes assets that are referenced at fixed, root-relative runtime paths, not resolved via the module graph. Your app must make these reachable at the paths below (e.g. copy them into your public/static directory, or serve dist/ itself at your app root):

• dist/assets/sunbird-quml-player.js and dist/assets/sunbird-quml-player-styles.css — the QuML player used for question/questionset preview, lazy-loaded at runtime from /assets/sunbird-quml-player.js by default (override via config.playerScriptUrl).
• dist/assets/libs/mathEquation/** — the MathQuill/KaTeX equation-editor modal (iframe), loaded from the fixed path /assets/libs/mathEquation/plugin/mathModal/index.html. Copy the whole mathEquation folder as-is, including its nested fonts/ (KaTeX) and css/js subfolders — its index.html, katex.min.css, and mathquill.css all load these siblings by relative path, so they must stay nested exactly as shipped, not flattened or split across other static folders.
• dist/ckeditor/ckeditor.js — CKEditor 4 classic build used for rich-text question/option fields. This is not loaded automatically; the host page must load it as a global <script> tag before the editor mounts (it registers window.ClassicEditor, which CKEditorField looks for).

Quick start — Web component (framework-agnostic)

Register the custom element once, then create it like any other DOM element and set its configuration as element properties (not string attributes) so React receives real objects:

<script src="/ckeditor/ckeditor.js"></script>
<link rel="stylesheet" href="/style.css" />

<div id="root"></div>

<script type="module">
  import { registerQuestionsetEditor } from '@project-sunbird/sunbird-questionset-editor-web-component-react';
  registerQuestionsetEditor(); // defines <sb-questionset-editor>, idempotent

  const editor = document.createElement('sb-questionset-editor');

  editor.context = {
    authToken: '',
    userId: 'user-001',
    channel: 'my-channel',
    pdata: { id: 'sunbird.portal', ver: '1.0' },
    env: 'questionset_editor',
    contentId: 'do_123',
    identifier: 'do_123',
    framework: 'NCF',
  };

  editor.config = {
    mode: 'edit',
    objectType: 'QuestionSet',
    primaryCategory: 'Practice Question Set',
    maxDepth: 3,
  };

  editor.style.cssText = 'display:block;width:100%;height:100%;';
  document.getElementById('root').appendChild(editor);
</script>

The tag name is fixed: sb-questionset-editor. registerQuestionsetEditor() guards against double-registration, so it's safe to call more than once.

Quick start — React

import { QuestionsetEditor } from '@project-sunbird/sunbird-questionset-editor-web-component-react';
import '@project-sunbird/sunbird-questionset-editor-web-component-react/dist/style.css';

<QuestionsetEditor
  context={context}
  config={config}
  onQuestionSaved={(question) => console.log('saved', question)}
  onHierarchySaved={(hierarchy) => console.log('hierarchy saved', hierarchy)}
  onError={(err) => console.error(err)}
/>

API

<QuestionsetEditor> props

| Prop | Type | Required | Description | |---|---|---|---| | context | IContext | ✅ | Runtime context — user, session, channel, content identifier | | config | IConfig | ✅ | Editor mode and behaviour | | metadata | Record<string, unknown> | — | Pre-loaded content metadata | | data | unknown | — | Reserved/advanced pass-through data | | apiBaseUrl | string | — | Base URL for all API calls. Omit when using a server-side proxy | | onToolbarEvent | (e: { action: ToolbarAction; data?: unknown }) => void | — | Fired on every toolbar action | | onQuestionSaved | (question: unknown) => void | — | Fired after a question is saved | | onHierarchySaved | (hierarchy: unknown) => void | — | Fired after a successful hierarchy save | | onError | (error: Error) => void | — | Fired on unrecoverable editor errors |

On the web component, set the same fields as element properties (e.g. editor.onQuestionSaved = (q) => ...), the same way context/config are set.

IContext

Identifies the current user/session and the content being edited. sid, did, channel, and pdata are required; everything else is optional.

interface IContext {
  authToken?: string;
  userId?: string;
  user?: { id: string; fullName?: string; firstName?: string; lastName?: string; orgIds?: string[] };
  sid: string;
  did: string;
  uid?: string;
  channel: string;
  pdata: { id: string; ver: string; pid?: string };
  env?: string;
  contentId?: string;
  identifier?: string;      // same value as contentId is also accepted
  framework?: string;
  targetFWIds?: string[];
  rollup?: Record<string, string>;
  contextRollup?: Record<string, string>;
  objectRollup?: Record<string, string>;
  cdata?: Array<Record<string, unknown>>;
  tags?: string[];
  host?: string;             // telemetry host/endpoint
  endpoint?: string;
  timeDiff?: number;
  defaultLicense?: string;
  enableReviewEdit?: boolean;   // allow reviewer edits in orgreview/sourcingreview
  uiLanguage?: string;          // 'en' | 'ar' | 'fr' | 'hi' | 'pt'
  labels?: Record<string, string>;  // overrides for editor button labels
  cloudStorage?: { provider?: string; presigned_headers?: Record<string, string> };
  cloudStorageUrls?: string[];  // blob-storage origins to rewrite to /assets/public/
}

IConfig

Controls editor mode and behaviour. mode and objectType are required.

interface IConfig {
  mode: 'edit' | 'review' | 'read' | 'orgreview' | 'sourcingreview';
  objectType: string;               // e.g. 'QuestionSet'
  hideSubmitForReviewBtn?: boolean;
  playerScriptUrl?: string;         // default '/assets/sunbird-quml-player.js'
  apiSlug?: string;                 // API path prefix, default '/api'
  questionSet?: { maxQuestionsLimit?: number };
  showAddCollaborator?: boolean;
  primaryCategory?: string;
  framework?: string[];
  targetFWIds?: string[];
  toolbarConfig?: Record<string, unknown>;
  hierarchy?: Record<string, unknown>;
  children?: unknown[];
  defaultFields?: Record<string, unknown>;
  maxDepth?: number;
  questionTypes?: string[];         // restrict which question types are offered
  maxQuestions?: number;
  showSolutions?: boolean;
  showHints?: boolean;
  showTimer?: boolean;
  categoryDefinitionApiVersion?: 'v1' | 'v4';  // default 'v4'
}

ToolbarAction

type ToolbarAction =
  | 'back' | 'preview' | 'sendForReview' | 'onFormValueChange' | 'onFormStatusChange'
  | 'saveContent' | 'publish' | 'reject';

API base URL

By default all API calls are made relative to the page origin (works with a server-side proxy). To point directly at a backend, either pass the prop:

<QuestionsetEditor {...config} apiBaseUrl="https://api.your-sunbird-instance.com" />

or call the exported setters directly (also lets you override the /api path prefix independently):

import { setApiBaseUrl, setApiSlug } from '@project-sunbird/sunbird-questionset-editor-web-component-react';

setApiBaseUrl('https://api.your-sunbird-instance.com');
setApiSlug('/api'); // default

Stores (advanced)

The editor exposes its internal Zustand stores for advanced integration scenarios — for example, reading the current tree selection or editor mode from outside the component:

import { useEditorStore, useTreeStore, useQuestionStore, useUiStore } from '@project-sunbird/sunbird-questionset-editor-web-component-react';

// Inside a React component
const selectedNodeId = useTreeStore((s) => s.selectedNodeId);
const editorMode      = useEditorStore((s) => s.editorMode);

Styles

The stylesheet must be imported once in your app — it is not auto-injected (the component renders in the light DOM, not Shadow DOM):

import '@project-sunbird/sunbird-questionset-editor-web-component-react/dist/style.css';

Supported question types

Registered out of the box (matching the old editor's six built-in QuML types):

| Type | qType | primaryCategory | Description | |---|---|---|---| | Multiple Choice | MCQ | Multiple Choice Question | Pick one correct option from a list | | Subjective | SA (aliases: VSA, LA) | Subjective Question | Free-form written or long answer | | Fill in the Blank | FTB | FTB Question | Hide words in a sentence with [[ ]] | | Match the Following | MTF | Match The Following Question | Pair items across two columns | | Sequence | SEQ | Sequence Question | Arrange items in the correct order | | Reorder | REO | Reorder Question | Rearrange shuffled words into a sentence | | True / False | BOOL | Boolean Question | Pick between true or false choices |

config.questionTypes can be used to restrict which of these are offered when adding a question. Host apps can also register additional/custom types before mounting the editor via the exported registry functions: registerQuestionType, resolveQuestionType, resolveByQType, resolveByCategory, resolveByInteractionType, allQuestionTypes.

Development setup

# Clone the repo
git clone https://github.com/Sunbird-inQuiry/editor-v2.git
cd editor

# Install
npm install

# Dev server with mock data — no .env needed, just run:
npm run dev

To point the dev server at a real backend instead of mock data, copy .env.example to .env and fill in your credentials (BASE_URL, AUTH_TOKEN, USER_TOKEN, CONTENT_ID, etc.):

cp .env.example .env
# edit .env with your credentials

npm run build   # runs tsc -b && vite build
npm run serve   # standalone server.js, reads .env

# Run tests
npm test

Compatibility

| Dependency | Version | |---|---| | React | 18.x or 19.x | | React DOM | 18.x or 19.x |

License

MIT — see the repository root for the full licence text.

Notes and caveats

• CKEditor must be loaded manually. Add <script src=".../ckeditor.js"></script> (from this package's dist/ckeditor/ckeditor.js) to the host page before the editor mounts; rich-text fields look for window.ClassicEditor and log an error if it isn't present.
• No Shadow DOM. The custom element renders into the light DOM so the Sunbird design system CSS (dist/style.css) applies directly — make sure it's loaded on the page.
• QuML player script for previews defaults to the root-relative path /assets/sunbird-quml-player.js; override with config.playerScriptUrl if you serve it elsewhere.
• Localized UI labels are available for en, ar, fr, hi, pt via context.uiLanguage.
• This package is ESM-only ("type": "module") and built for evergreen browsers; there is no UMD/CJS build.