@qrvey/widget-configurability

A utility library for managing widget configuration, structure, and permissions in Qrvey applications.

---

Table of Contents

• Installation
• Quick Start
• Package Exports
• Enums
• Core API
  • buildStructureInstance
  • WidgetStructureInstance
  • structureInstanceMap
• Dashboard Documentation
• Examples

---

Installation

# npm
npm install @qrvey/widget-configurability

# yarn
yarn add @qrvey/widget-configurability

---

Quick Start

import {
  WidgetStructureInstance,
  buildStructureInstance,
  structureInstanceMap,
  UserRole,
  Widget,
  WidgetVersion,
  DashboardDoc,
} from '@qrvey/widget-configurability';

// 1. Build a new structure instance for Dashboard v1
const instance = buildStructureInstance(
  Widget.DASHBOARD,
  WidgetVersion.v1,
  /* optional customization object */,
  UserRole.MANAGER
);

// 2. Store or reuse the instance
structureInstanceMap.set('dashboard-v1-manager', instance);

// 3. Inspect visibility / permissions
console.log(instance.isVisible('navBar'));      // true / false
console.log(instance.hasPermission());          // true if role === MANAGER
console.log(instance.getCanvasPermissions('design'));

---

Package Exports

export {
  WidgetStructureInstance,   // Class for inspecting a widget’s view map & permissions
  buildStructureInstance,    // Factory to create a WidgetStructureInstance
  structureInstanceMap,      // Map<string, WidgetStructureInstance> for caching instances
  UserRole,                  // Enum of supported user roles (e.g. MANAGER, VIEWER)
  Widget,                    // Enum of widget types (e.g. DASHBOARD)
  WidgetVersion,             // Enum of widget versions (e.g. v1)
  DashboardDoc,              // The raw Dashboard v1 configuration documentation
};

---

Enums

Widget

export enum Widget {
  DASHBOARD = 'dashboard',
}

WidgetVersion

export enum WidgetVersion {
  v1 = '1.0',
}

UserRole

export enum UserRole {
  MANAGER = 'manager',
  VIEWER  = 'viewer',
}

---

Core API

buildStructureInstance

Creates a WidgetStructureInstance based on:

• widget – one of the Widget enum values
• version – one of the WidgetVersion enum values
• customization – optional overrides to base configuration
• userRole – optional role, defaults to UserRole.MANAGER if invalid

function buildStructureInstance(
  widget: Widget,
  version: WidgetVersion,
  customization?: WidgetCustomization,
  userRole?: string
): WidgetStructureInstance

Throws an error if no matching configuration is found.

---

WidgetStructureInstance

Class that wraps a widget’s “view map” and provides helper methods:

Method	Description
isVisible(key: string, state?: ConditionState): boolean	Returns true if the key exists and its conditions (if any) are met
hasPermission(): boolean	Returns true if the instance’s role equals UserRole.MANAGER
getCanvasPermissions(mode: CanvasMode): CanvasModePermissions	Returns the permission set for the given canvas mode (list, design, preview, endUser)
getChildMap(key: string): WidgetViewMap | undefined	If the key has a nested childMap, returns it; otherwise undefined
getSubmodule(module: string, view?: string): WidgetCustomization | undefined	Retrieves a specific sub-module customization under subModules
getDefaults(key: string): Record<string, unknown> | undefined	Retrieves default settings for a given key (e.g. assetList.defaults)

---

structureInstanceMap

A simple Map<string, WidgetStructureInstance> you can use to cache or share built instances across your application.

---

Dashboard Documentation

All of the raw Dashboard v1 configuration—including version, base structure, nested views, menus, toolbars, panels, and sub-modules—is exported as DashboardDoc.

import * as DashboardDoc from '@qrvey/widget-configurability/doc/dashboard.structure.doc';

console.log(DashboardDoc.default);
/*
{
  version: '1.0',
  baseStructure: { views: { … }, navBar: [ … ], … }
}
*/

---

Examples

Customizing a Dashboard

import { buildStructureInstance, Widget, WidgetVersion } from '@qrvey/widget-configurability';
import { case1 } from './your-customizations';

const inst = buildStructureInstance(
  Widget.DASHBOARD,
  WidgetVersion.v1,
  case1,        // your WidgetCustomization
  'viewer'      // non-manager role
);

console.log(inst.isVisible('assetList'));  // based on your customization
console.log(inst.hasPermission());         // false