@qrvey/widget-configurability 0.0.0-beta.4430 → 0.0.0-beta.4482

package/dist/types/index.d.ts

@@ -1,8 +1,15 @@
 declare enum Widget {
     DASHBOARD = "dashboard",
     REPORT = "report",
-    DOWNLOAD_MANAGER = "download-manager"
+    DOWNLOAD_MANAGER = "download-manager",
+    DOWNLOAD_MODAL = "download-modal",
+    CHART_PANEL = "chart-panel",
+    CHART_GALLERY = "chart-gallery",
+    CHART_BUILDER = "chart-builder"
 }
+declare const WIDGET_SUBMODULE_NAMES: Partial<Record<Widget, string>>;
+declare const WIDGET_STRUCTURE_SCOPE_KIND = "qrvey.widget-structure-scope";
+declare const WIDGET_STRUCTURE_SCOPE_FORMAT = 1;
 declare enum WidgetVersion {
     v1 = "1.0",
     latest = "latest"
@@ -37,7 +44,31 @@ interface WidgetCustomization extends CustomizationStructure {
     views?: View;
 }
 
-type SectionValue = number | boolean | string | SectionValue[] | Record<string, unknown>;
+type SectionValue = number | boolean | string | undefined | SectionValue[] | Record<string, unknown>;
+type SectionDefinition = WidgetStructure | (string | WidgetStructure)[] | undefined | boolean;
+interface WidgetStructure {
+    defaults?: Record<string, SectionValue>;
+    subModules?: Record<string, SectionValue>;
+    [key: string]: SectionDefinition | Record<string, SectionValue> | undefined;
+}
+interface WidgetStructureRoot extends WidgetStructure {
+    views?: Record<string, string[]>;
+}
+interface WidgetConfig {
+    version: string;
+    baseStructure: WidgetStructureRoot;
+    keepInheritance?: Record<string, string>;
+}
+type ValidationFN<T = any> = (value: T) => T | undefined;
+type ValidationMap = Record<string, ValidationFN>;
+type SanitizeFn = (value: string) => string;
+interface StructureEngineOptions {
+    sanitize?: SanitizeFn;
+    viewConditionals?: boolean;
+}
+interface BuildStructureOptions extends StructureEngineOptions {
+    validationMap?: ValidationMap;
+}
 interface WidgetItemCondition {
     effect: 'keep' | 'remove';
     condition: Condition;
@@ -49,17 +80,116 @@ interface WidgetViewMapItemObj {
 }
 type WidgetViewMapItem = string | boolean | WidgetViewMapItemObj | Record<string, SectionValue>;
 type WidgetViewMap = Record<string, WidgetViewMapItem>;
+interface WidgetConditionMap {
+    condition: Condition;
+    map: WidgetViewMap;
+}
+
+interface ScopeOptions {
+    widget?: Widget;
+    version?: WidgetVersion;
+    state?: ConditionState;
+    defaultsNamespace?: string | null;
+}
+interface WidgetStructureScope {
+    kind: 'qrvey.widget-structure-scope';
+    format: number;
+    widget?: Widget;
+    structureVersion?: string;
+    source: string;
+    present: boolean;
+    map: Record<string, boolean>;
+    defaults?: Record<string, unknown>;
+}
 
-declare function buildStructure(widget: Widget, customization?: WidgetCustomization, version?: WidgetVersion): WidgetStructureInstance;
+declare function getWidgetConfig(widget: Widget, version?: WidgetVersion): WidgetConfig;
+declare function buildStructure(widget: Widget, customization?: WidgetCustomization, version?: WidgetVersion, options?: BuildStructureOptions): WidgetStructureInstance;
 declare class WidgetStructureInstance {
     private viewMap;
-    constructor(viewMap: WidgetViewMap);
+    private rootDefaults?;
+    constructor(viewMap: WidgetViewMap, rootDefaults?: Record<string, unknown> | undefined);
     private getValue;
     isVisible(key: string, state?: ConditionState): boolean;
     getChildMap(key: string): WidgetViewMap | undefined;
     getSubmodule(module: string, view?: string): WidgetCustomization | undefined;
     getDefaults(key: string): Record<string, unknown> | undefined;
+    getRootDefaults(): Record<string, unknown> | undefined;
+    /**
+     * Re-roots a resolved section (`design::downloadModal`) as plain JSON another bundle can rebuild a structure from.
+     */
+    scope(prefixKey: string, options?: ScopeOptions): WidgetStructureScope;
+}
+
+declare function validateDefaults(obj: Record<string, unknown>, validatorMap: ValidationMap, sanitize?: SanitizeFn): Record<string, unknown>;
+declare const validateBoolean: (value: unknown) => boolean | undefined;
+declare const DX_VALIDATOR_MAP: ValidationMap;
+declare const DOWNLOAD_MODAL_VALIDATOR_MAP: ValidationMap;
+
+interface ViewMapOptions extends StructureEngineOptions {
+    keepInheritance?: Record<string, string>;
+}
+/**
+ * constructs the permission map structure for a widget
+ * @param config configuration of a widget
+ * @param customization customization options for a widget
+ * @param validationMap
+ * @returns object representing the view map for the widget
+ */
+declare function getWidgetStructure(config: WidgetConfig, customization?: WidgetCustomization, validationMap?: ValidationMap, options?: StructureEngineOptions): WidgetViewMap;
+declare function calculateViewMap(config: WidgetStructureRoot, customization?: WidgetCustomization, validationMap?: ValidationMap, options?: ViewMapOptions): WidgetViewMap;
+/**
+ * Defaults at the root of a structure without views (structure defaults merged with the customization's).
+ */
+declare function calculateRootDefaults(config: WidgetStructureRoot, customization?: WidgetCustomization, validationMap?: ValidationMap, sanitize?: SanitizeFn): Record<string, unknown> | undefined;
+
+declare function evaluateCondition(state: ConditionState | undefined, ...conditions: Condition[]): boolean;
+declare function checkConditions(state: ConditionState | undefined, conditions: WidgetItemCondition[]): boolean;
+
+type StructureInput = WidgetStructureScope | WidgetCustomization | null | undefined;
+declare function isWidgetStructureScope(value: unknown): value is WidgetStructureScope;
+/**
+ * Turns a resolved scope back into a customization of the widget it lists: hidden keys become an explicit remove list.
+ */
+declare function scopeToCustomization(scope: WidgetStructureScope): WidgetCustomization;
+/**
+ * Extracts a section of a host's customization as a customization of the embedded widget, by evaluating it with the host's engine.
+ */
+declare function extractCustomization(host: Widget, customization: WidgetCustomization | undefined, prefixKey: string, target: Widget, options?: BuildStructureOptions): WidgetCustomization;
+/**
+ * Builds an embedded widget's structure from what its host passes: a resolved scope, a raw customization of the widget, or a host
+ * customization carrying the widget under subModules. Returns undefined for no input or an invalid one, so the receiver keeps its
+ * legacy behaviour.
+ */
+declare function structureFrom(widget: Widget, input: unknown, view?: string, version?: WidgetVersion): WidgetStructureInstance | undefined;
+/**
+ * Builds the structure of a widget a host embeds as a submodule (chartPanel, chartGallery, chartBuilder, downloadModal).
+ */
+declare function structureFromSubmodule(parent: WidgetStructureInstance, module: string, view?: string, options?: BuildStructureOptions): WidgetStructureInstance;
+
+interface DownloadModalResolvedConfig {
+    schedule: boolean;
+    subscribe: boolean;
+    banner: boolean;
+    owner: boolean;
+    organization: boolean;
+    myself: boolean;
+    specificPeople: boolean;
+    externalUsers: boolean;
+    subscribeMyselfDefault: boolean;
 }
+interface ResolveDownloadModalOptions {
+    organizationAvailable?: boolean;
+}
+/**
+ * The export modal's visibility rules: Schedule hides Subscribe, and Subscribe hides when it has nothing left to show.
+ */
+declare function resolveDownloadModalConfig(structure: WidgetStructureInstance, { organizationAvailable }?: ResolveDownloadModalOptions): DownloadModalResolvedConfig;
+
+declare const DOWNLOAD_MODAL_V1_KEYS: readonly ["qScheduleOption", "qSubscribeOption", "qSubscribeExternalUsers", "qSubscribeBanner", "qSubscribeOwner", "qSubscribeOrganization", "qSubscribeMyself", "qSubscribeSpecificPeople", "qIncludeHyperlinks"];
+type DownloadModalKey = (typeof DOWNLOAD_MODAL_V1_KEYS)[number];
+declare const DOWNLOAD_MODAL_V1_DEFAULTS: {
+    subscribeMyself: boolean;
+};
 
 declare class ViewsDto {
     list: string[];
@@ -124,4 +254,4 @@ declare namespace dashboard_structure_doc {
   export { dashboard_structure_doc_AssetListDto as AssetListDto, dashboard_structure_doc_BaseDashboardV1StructureDto as BaseDashboardV1StructureDto, dashboard_structure_doc_FilterPanelDto as FilterPanelDto, dashboard_structure_doc_MenuBarDto as MenuBarDto, dashboard_structure_doc_SubModulesDto as SubModulesDto, dashboard_structure_doc_ViewsDto as ViewsDto };
 }
 
-export { dashboard_structure_doc as DashboardDoc, Widget, type WidgetCustomization, WidgetStructureInstance, WidgetVersion, buildStructure };
+export { type BuildStructureOptions, type Condition, type ConditionState, type ConditionValue, DOWNLOAD_MODAL_V1_DEFAULTS, DOWNLOAD_MODAL_V1_KEYS, DOWNLOAD_MODAL_VALIDATOR_MAP, DX_VALIDATOR_MAP, dashboard_structure_doc as DashboardDoc, type DownloadModalKey, type DownloadModalResolvedConfig, type Operators, type ResolveDownloadModalOptions, type SanitizeFn, type ScopeOptions, type StructureEngineOptions, type StructureInput, type ValidationFN, type ValidationMap, WIDGET_STRUCTURE_SCOPE_FORMAT, WIDGET_STRUCTURE_SCOPE_KIND, WIDGET_SUBMODULE_NAMES, Widget, type WidgetConditionMap, type WidgetConfig, type WidgetCustomization, type WidgetItemCondition, type WidgetStructure, WidgetStructureInstance, type WidgetStructureRoot, type WidgetStructureScope, type WidgetSubModuleCollection, WidgetVersion, type WidgetViewMap, type WidgetViewMapItem, buildStructure, calculateRootDefaults, calculateViewMap, checkConditions, evaluateCondition, extractCustomization, getWidgetConfig, getWidgetStructure, isWidgetStructureScope, resolveDownloadModalConfig, scopeToCustomization, structureFrom, structureFromSubmodule, validateBoolean, validateDefaults };

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@qrvey/widget-configurability",
-  "version": "0.0.0-beta.4430",
+  "version": "0.0.0-beta.4482",
   "types": "dist/types/index.d.ts",
   "main": "dist/cjs/index.js",
+  "module": "./dist/esm/index.mjs",
   "exports": {
     ".": {
+      "types": "./dist/types/index.d.ts",
       "import": "./dist/esm/index.mjs",
       "require": "./dist/cjs/index.js",
       "default": "./dist/cjs/index.js"
@@ -33,6 +35,11 @@
   "peerDependencies": {
     "@nestjs/swagger": "11.4.5"
   },
+  "peerDependenciesMeta": {
+    "@nestjs/swagger": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@nestjs/swagger": "11.4.5",
     "@types/jest": "29.5.14",