@qrvey/widget-configurability 0.0.0-beta.4589 → 0.0.0-beta.4657

package/dist/types/index.d.ts

@@ -1,48 +1,5 @@
-declare enum Widget {
-    DASHBOARD = "dashboard",
-    REPORT = "report",
-    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"
-}
-
-declare const allowedOperators: readonly ["=", "!=", ">", ">=", "<", "<=", "startsWith", "endsWith", "contains"];
-type Operators = (typeof allowedOperators)[number];
-type ConditionValue = string | number;
-interface Condition {
-    field: string;
-    operator: Operators;
-    value: ConditionValue;
-}
-type ConditionState = Record<string, ConditionValue>;
-
-interface Verbs {
-    remove?: string[];
-    keep?: string[];
-    reorder?: string[];
-}
-interface CustomizationStructure extends Verbs {
-    defaults?: Record<string, unknown>;
-    subModules?: WidgetSubModuleCollection;
-}
-interface Conditional extends CustomizationStructure {
-    condition: Condition;
-}
-type View = Record<string, WidgetCustomization>;
-type WidgetSubModuleCollection = Record<string, WidgetCustomization>;
-interface WidgetCustomization extends CustomizationStructure {
-    conditional?: Conditional[];
-    views?: View;
-}
+import { W as WidgetCustomization, C as Condition, a as Widget, b as WidgetVersion, c as ConditionState } from './customization.models-CCSWjfb2.js';
+export { d as ConditionValue, O as Operators, e as WIDGET_STRUCTURE_SCOPE_FORMAT, f as WIDGET_STRUCTURE_SCOPE_KIND, g as WIDGET_SUBMODULE_NAMES, h as WidgetSubModuleCollection } from './customization.models-CCSWjfb2.js';
 
 type SectionValue = number | boolean | string | undefined | SectionValue[] | Record<string, unknown>;
 type SectionDefinition = WidgetStructure | (string | WidgetStructure)[] | undefined | boolean;
@@ -68,6 +25,7 @@ interface StructureEngineOptions {
 }
 interface BuildStructureOptions extends StructureEngineOptions {
     validationMap?: ValidationMap;
+    layers?: WidgetCustomization[];
 }
 interface WidgetItemCondition {
     effect: 'keep' | 'remove';
@@ -102,16 +60,77 @@ interface WidgetStructureScope {
     defaults?: Record<string, unknown>;
 }
 
+type CustomizationErrorCode = 'INVALID_TYPE' | 'UNKNOWN_PROPERTY' | 'UNKNOWN_VIEW' | 'UNKNOWN_SUBMODULE' | 'UNKNOWN_KEY' | 'INVALID_PATTERN' | 'INVALID_DEFAULT' | 'INVALID_CONDITION' | 'EMPTY_CUSTOMIZATION' | 'UNKNOWN_WIDGET' | 'UNKNOWN_VERSION';
+type CustomizationPath = (string | number)[];
+interface CustomizationValidationError {
+    path: CustomizationPath;
+    code: CustomizationErrorCode;
+    severity: 'error' | 'warning';
+    message: string;
+    suggestion?: string;
+}
+interface CustomizationValidationResult {
+    valid: boolean;
+    errors: CustomizationValidationError[];
+}
+interface ValidateCustomizationOptions {
+    version?: string;
+    allowEmpty?: boolean;
+}
+
+interface RemoteCustomizationDefinition {
+    widget: string;
+    customizationId: string;
+    name?: string | null;
+    description?: string | null;
+    source?: 'system' | 'user';
+    structureVersion?: string;
+    contexts?: string[];
+    customization: WidgetCustomization;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface LoadRemoteCustomizationOptions {
+    widget: string;
+    customizationId?: string | null;
+    context?: string;
+    domain: string;
+    apiDomain?: string;
+    apiKey?: string;
+    qvToken?: string;
+    timeoutMs?: number;
+    fetchFn?: typeof fetch;
+    cache?: boolean;
+}
+type RemoteCustomizationStatus = 'found' | 'fallback' | 'none' | 'error';
+interface RemoteCustomizationError {
+    code: 'NETWORK' | 'TIMEOUT' | 'HTTP' | 'INVALID_RESPONSE' | 'INVALID_INPUT';
+    status?: number;
+    message: string;
+}
+interface RemoteCustomizationResult {
+    status: RemoteCustomizationStatus;
+    definition?: RemoteCustomizationDefinition;
+    error?: RemoteCustomizationError;
+}
+
+type SubmoduleLayers = Record<string, Record<string, WidgetCustomization[]>>;
+
 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;
     private rootDefaults?;
-    constructor(viewMap: WidgetViewMap, rootDefaults?: Record<string, unknown> | undefined);
+    private submoduleLayers?;
+    constructor(viewMap: WidgetViewMap, rootDefaults?: Record<string, unknown> | undefined, submoduleLayers?: SubmoduleLayers | undefined);
     private getValue;
     isVisible(key: string, state?: ConditionState): boolean;
     getChildMap(key: string): WidgetViewMap | undefined;
     getSubmodule(module: string, view?: string): WidgetCustomization | undefined;
+    /**
+     * Submodule customizations of the stored layers, to pass as layers when building the embedded widget (structureFromSubmodule).
+     */
+    getSubmoduleLayers(module: string, view?: string): WidgetCustomization[] | undefined;
     getDefaults(key: string): Record<string, unknown> | undefined;
     getRootDefaults(): Record<string, unknown> | undefined;
     /**
@@ -173,6 +192,38 @@ declare const DOWNLOAD_MODAL_V1_DEFAULTS: {
     subscribeMyself: boolean;
 };
 
+/**
+ * Formats a validation path as the API error messages show it, e.g. views.design.remove[2]
+ * (admin_api_manager prefixes it with `customization.`).
+ */
+declare function formatCustomizationPath(path: CustomizationPath): string;
+/**
+ * True when the customization has no effective rule: no verb with items and no defaults anywhere.
+ */
+declare function isEmptyCustomization(value: unknown): boolean;
+/**
+ * Strict validation of a customization for writes (API and Admin Center): collects every error in one pass, each with its path.
+ */
+declare function validateCustomization(widget: Widget | string, customization: unknown, options?: ValidateCustomizationOptions): CustomizationValidationResult;
+
+declare const CUSTOMIZATIONS_API_PATH = "/api/admin/v5/customizations/widgets";
+declare const DEFAULT_CUSTOMIZATION_ID = "default";
+/**
+ * Forgets every cached request (tests, or a host that needs to re-read definitions without reloading).
+ */
+declare function clearRemoteCustomizationCache(): void;
+declare const isValidCustomizationId: (value: unknown) => value is string;
+/**
+ * Resolves the stored customization a widget uses as its base layer (resolution table 3.3.1 of QRV-749).
+ * found: the requested definition (or the context's); fallback: default, because the requested one does not exist;
+ * none: no remote layer; error: the widget shows its configuration error.
+ */
+declare function loadRemoteCustomization(options: LoadRemoteCustomizationOptions): Promise<RemoteCustomizationResult>;
+/**
+ * The layers a widget passes to buildStructure for a resolved result: the definition's customization, or none.
+ */
+declare function remoteCustomizationLayers(result: RemoteCustomizationResult | undefined): WidgetCustomization[];
+
 declare class ViewsDto {
     list: string[];
     design: string[];
@@ -236,4 +287,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 { 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 Operators, 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, hostKeepInheritance, isWidgetStructureScope, scopeToCustomization, structureFrom, structureFromSubmodule, validateBoolean, validateDefaults };
+export { type BuildStructureOptions, CUSTOMIZATIONS_API_PATH, Condition, ConditionState, type CustomizationErrorCode, type CustomizationPath, type CustomizationValidationError, type CustomizationValidationResult, DEFAULT_CUSTOMIZATION_ID, DOWNLOAD_MODAL_V1_DEFAULTS, DOWNLOAD_MODAL_V1_KEYS, DOWNLOAD_MODAL_VALIDATOR_MAP, DX_VALIDATOR_MAP, dashboard_structure_doc as DashboardDoc, type DownloadModalKey, type LoadRemoteCustomizationOptions, type RemoteCustomizationDefinition, type RemoteCustomizationError, type RemoteCustomizationResult, type RemoteCustomizationStatus, type SanitizeFn, type ScopeOptions, type StructureEngineOptions, type StructureInput, type ValidateCustomizationOptions, type ValidationFN, type ValidationMap, Widget, type WidgetConditionMap, type WidgetConfig, WidgetCustomization, type WidgetItemCondition, type WidgetStructure, WidgetStructureInstance, type WidgetStructureRoot, type WidgetStructureScope, WidgetVersion, type WidgetViewMap, type WidgetViewMapItem, buildStructure, calculateRootDefaults, calculateViewMap, checkConditions, clearRemoteCustomizationCache, evaluateCondition, extractCustomization, formatCustomizationPath, getWidgetConfig, getWidgetStructure, hostKeepInheritance, isEmptyCustomization, isValidCustomizationId, isWidgetStructureScope, loadRemoteCustomization, remoteCustomizationLayers, scopeToCustomization, structureFrom, structureFromSubmodule, validateBoolean, validateCustomization, validateDefaults };

package/dist/types/metadata.d.ts

@@ -0,0 +1,59 @@
+import { a as Widget, b as WidgetVersion, W as WidgetCustomization } from './customization.models-CCSWjfb2.js';
+
+interface CustomizationLabel {
+    label: string;
+    description?: string;
+}
+type CustomizationLabelMap = Record<string, CustomizationLabel>;
+interface CustomizationTarget {
+    views: string[];
+    subModules?: string[];
+}
+interface CustomizationTreeNode {
+    key: string;
+    id: string;
+    label: string;
+    description?: string;
+    kind: 'section' | 'item' | 'subModule';
+    children?: CustomizationTreeNode[];
+}
+interface CustomizationLock {
+    verb: 'keep' | 'remove';
+    pattern: string;
+    scope: 'root' | 'view' | 'conditional' | 'parent';
+}
+interface CustomizationTreeStateNode extends CustomizationTreeNode {
+    visible: boolean | 'mixed';
+    lockedBy?: CustomizationLock;
+    children?: CustomizationTreeStateNode[];
+}
+
+declare const widgetMetadata: Partial<Record<Widget, {
+    labels: CustomizationLabelMap;
+}>>;
+/**
+ * Keys of the structure in a view (or at the root), in structure order, without the view prefix.
+ */
+declare function structureKeysOf(widget: Widget, view?: string, version?: WidgetVersion): string[];
+/**
+ * Label of a key: full path first, then the leaf id; a humanized id when neither exists.
+ */
+declare function getCustomizationLabel(widget: Widget, key: string): CustomizationLabel;
+/**
+ * The labelled tree of a target: a widget view, or the structure of the embedded widget when subModules is set.
+ */
+declare function getCustomizationTree(widget: Widget, target: CustomizationTarget, options?: {
+    version?: WidgetVersion;
+}): CustomizationTreeNode[];
+/**
+ * The tree with the visibility of each node for a customization, computed with the real engine. A node whose
+ * visibility differs between the target views is 'mixed'; a hidden node a switch cannot bring back is locked.
+ */
+declare function getCustomizationTreeState(widget: Widget, customization: WidgetCustomization | undefined, target: CustomizationTarget): CustomizationTreeStateNode[];
+/**
+ * A new customization with the minimal change for one switch, applied to every view of the target. It only edits
+ * the remove list of each view (or of the submodule inside it), never keep, conditional, defaults or root verbs.
+ */
+declare function toggleCustomizationKey(customization: WidgetCustomization | undefined, target: CustomizationTarget, key: string, visible: boolean): WidgetCustomization;
+
+export { type CustomizationLabel, type CustomizationLabelMap, type CustomizationLock, type CustomizationTarget, type CustomizationTreeNode, type CustomizationTreeStateNode, getCustomizationLabel, getCustomizationTree, getCustomizationTreeState, structureKeysOf, toggleCustomizationKey, widgetMetadata };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qrvey/widget-configurability",
-  "version": "0.0.0-beta.4589",
+  "version": "0.0.0-beta.4657",
   "types": "dist/types/index.d.ts",
   "main": "dist/cjs/index.js",
   "module": "./dist/esm/index.mjs",
@@ -10,6 +10,12 @@
       "import": "./dist/esm/index.mjs",
       "require": "./dist/cjs/index.js",
       "default": "./dist/cjs/index.js"
+    },
+    "./metadata": {
+      "types": "./dist/types/metadata.d.ts",
+      "import": "./dist/esm/metadata.mjs",
+      "require": "./dist/cjs/metadata/index.js",
+      "default": "./dist/cjs/metadata/index.js"
     }
   },
   "files": [