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

package/README.md

@@ -117,11 +117,85 @@ function buildStructure(
   widget: Widget,
   customization?: WidgetCustomization,
   version?: WidgetVersion,
+  options?: BuildStructureOptions,
 ): WidgetStructureInstance
 ```
 
 Throws an error if no matching configuration is found.
 
+`options.layers` applies stored customizations before `customization`, in order, each over what the previous
+one left: nothing removed by an earlier layer can come back, a `keep` of keys already removed empties its
+level, and defaults merge by leaf key with the last layer winning. Without layers the result is unchanged.
+
+```ts
+const result = await loadRemoteCustomization({ widget: 'dashboard', customizationId, domain, qvToken });
+if (result.status === 'error') showConfigurationError();
+const structure = buildStructure(Widget.DASHBOARD, inlineCustomization, undefined, {
+  layers: remoteCustomizationLayers(result),
+});
+```
+
+### `loadRemoteCustomization`
+
+Resolves the stored definition a widget uses as its base, falling back to `default` when the requested one does
+not exist. It calls admin_api_manager: `GET /api/admin/v5/customizations/widgets/{widget}/{id}` or
+`GET /api/admin/v5/customizations/widgets/{widget}?context=`. Returns
+`{ status: 'found' | 'fallback' | 'none' | 'error', definition?, error? }`. A 404 means "not found" whatever its
+body says; other error bodies are not read, only their status is reported. One request per URL is shared for
+the life of the page. It uses the global `fetch`, sends `Authorization: Bearer` and/or `x-api-key` only to the
+configured domain and never logs them.
+
+### Customization metadata (`@qrvey/widget-configurability/metadata`)
+
+A separate entry point, so widgets do not ship the labels. Admin Center builds its switch tree from it:
+
+- `getCustomizationTree(widget, { views, subModules? })`: the labelled tree of a view, or of the embedded widget
+  (`subModules: ['chartPanel']`), derived from the structure, so a new key appears and a removed one disappears.
+- `getCustomizationTreeState(widget, customization, target)`: the same tree with `visible: true | false | 'mixed'`
+  per node, computed with the engine, and `lockedBy` on hidden nodes a switch cannot bring back (a keep, a wildcard,
+  a root verb, a hidden parent).
+- `toggleCustomizationKey(customization, target, key, visible)`: the minimal change for one switch, in the remove
+  list of each target view (or of its submodule); it never touches keep, conditional, defaults or root verbs.
+
+Labels are English only, looked up by full key path and then by leaf id; a guard spec fails when a key has no label
+or a label names no key. A label may also carry `description`, `since` ('9.0', '9.2.PR.4'), `notes` and
+`audience: 'partner' | 'internal'` (partner when absent), seeded from the DX Widget Config sheet (RB-7258).
+
+The same entry generates the customization docs the sheet used to hold:
+
+- `getCustomizationDocs(widget, options?)`: one flat entry per key per scope, each view (`design`) and each submodule
+  of the view (`design::chartPanel`), with `key`, `scope`, `parent`, `kind`, `label`, `description`, `since`, `notes`,
+  `audience` and the `defaults` the key owns. `options.views` and `options.subModules` filter the scopes.
+- `getCustomizationDefaultDocs(widget, options?)`: every documented default with name, type, accepted values,
+  example and the key it belongs to (`null` for the ones that apply to the whole widget, like `customStyles`).
+
+Both, and `getCustomizationTree`, read the structure in `options.structure` (and `options.subModuleStructures` by
+submodule name) instead of the one this package ships, so a host can document the tree its release runs with:
+
+```ts
+import { getWidgetConfig, Widget } from '@qrvey/widget-configurability';
+import { getCustomizationDocs } from '@qrvey/widget-configurability/metadata';
+
+const entries = getCustomizationDocs(Widget.DASHBOARD, {
+  structure: getWidgetConfig(Widget.DASHBOARD),
+  subModuleStructures: { chartPanel: getWidgetConfig(Widget.CHART_PANEL) },
+});
+```
+
+### `validateCustomization`
+
+Strict validation for writes (admin_api_manager and Admin Center use the same function):
+
+```ts
+validateCustomization('dashboard', { views: { design: { remove: ['menuBar.file.qMnuDeleteDsh'] } } });
+// { valid: false, errors: [{ path: ['views', 'design', 'remove', 0], code: 'UNKNOWN_KEY', severity: 'error',
+//   message: "Key 'menuBar.file.qMnuDeleteDsh' does not exist in the design view",
+//   suggestion: 'menuBar.file.qMnuDeleteDash' }] }
+```
+
+At runtime nothing throws: unknown keys are ignored. A customization hides UI; it is not an authorization
+mechanism.
+
 ---
 
 ### `WidgetStructureInstance`
@@ -133,6 +207,7 @@ Class that wraps a widget’s “view map” and provides helper methods:
 | `isVisible(key: string, state?: ConditionState): boolean`                       | Returns `true` if the key exists and its conditions (if any) are met                          |
 | `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`                              |
+| `getSubmoduleLayers(module: string, view?: string)`                             | Submodule customizations of the stored layers (`structureFromSubmodule` applies them)        |
 | `getDefaults(key: string): Record<string, unknown> \| undefined`                | Retrieves default settings for a given key (e.g. `assetList.defaults`)                        |
 
 ---

package/dist/cjs/index.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DashboardDoc = exports.hostKeepInheritance = exports.DOWNLOAD_MODAL_V1_KEYS = exports.DOWNLOAD_MODAL_V1_DEFAULTS = exports.structureFromSubmodule = exports.structureFrom = exports.scopeToCustomization = exports.isWidgetStructureScope = exports.extractCustomization = exports.validateDefaults = exports.validateBoolean = exports.DX_VALIDATOR_MAP = exports.DOWNLOAD_MODAL_VALIDATOR_MAP = exports.evaluateCondition = exports.checkConditions = exports.getWidgetStructure = exports.calculateViewMap = exports.calculateRootDefaults = exports.WIDGET_SUBMODULE_NAMES = exports.WIDGET_STRUCTURE_SCOPE_KIND = exports.WIDGET_STRUCTURE_SCOPE_FORMAT = exports.Widget = exports.getWidgetConfig = exports.buildStructure = exports.WidgetStructureInstance = exports.WidgetVersion = void 0;
+exports.DashboardDoc = exports.remoteCustomizationLayers = exports.loadRemoteCustomization = exports.isValidCustomizationId = exports.clearRemoteCustomizationCache = exports.DEFAULT_CUSTOMIZATION_ID = exports.CUSTOMIZATIONS_API_PATH = exports.validateCustomization = exports.isEmptyCustomization = exports.formatCustomizationPath = exports.hostKeepInheritance = exports.DOWNLOAD_MODAL_V1_KEYS = exports.DOWNLOAD_MODAL_V1_DEFAULTS = exports.structureFromSubmodule = exports.structureFrom = exports.scopeToCustomization = exports.isWidgetStructureScope = exports.extractCustomization = exports.validateDefaults = exports.validateBoolean = exports.DX_VALIDATOR_MAP = exports.DOWNLOAD_MODAL_VALIDATOR_MAP = exports.evaluateCondition = exports.checkConditions = exports.getWidgetStructure = exports.calculateViewMap = exports.calculateRootDefaults = exports.WIDGET_SUBMODULE_NAMES = exports.WIDGET_STRUCTURE_SCOPE_KIND = exports.WIDGET_STRUCTURE_SCOPE_FORMAT = exports.Widget = exports.getWidgetConfig = exports.buildStructure = exports.WidgetStructureInstance = exports.WidgetVersion = void 0;
 const structure_constants_1 = require("./constants/structure.constants");
 Object.defineProperty(exports, "WidgetVersion", { enumerable: true, get: function () { return structure_constants_1.WidgetVersion; } });
 var structural_manager_1 = require("./structural-manager");
@@ -67,5 +67,16 @@ var download_modal_structure_v1_1 = require("./structures/download-modal.structu
 Object.defineProperty(exports, "DOWNLOAD_MODAL_V1_DEFAULTS", { enumerable: true, get: function () { return download_modal_structure_v1_1.DOWNLOAD_MODAL_V1_DEFAULTS; } });
 Object.defineProperty(exports, "DOWNLOAD_MODAL_V1_KEYS", { enumerable: true, get: function () { return download_modal_structure_v1_1.DOWNLOAD_MODAL_V1_KEYS; } });
 Object.defineProperty(exports, "hostKeepInheritance", { enumerable: true, get: function () { return download_modal_structure_v1_1.hostKeepInheritance; } });
+var customization_validator_1 = require("./validation/customization.validator");
+Object.defineProperty(exports, "formatCustomizationPath", { enumerable: true, get: function () { return customization_validator_1.formatCustomizationPath; } });
+Object.defineProperty(exports, "isEmptyCustomization", { enumerable: true, get: function () { return customization_validator_1.isEmptyCustomization; } });
+Object.defineProperty(exports, "validateCustomization", { enumerable: true, get: function () { return customization_validator_1.validateCustomization; } });
+var remote_customization_loader_1 = require("./remote/remote-customization.loader");
+Object.defineProperty(exports, "CUSTOMIZATIONS_API_PATH", { enumerable: true, get: function () { return remote_customization_loader_1.CUSTOMIZATIONS_API_PATH; } });
+Object.defineProperty(exports, "DEFAULT_CUSTOMIZATION_ID", { enumerable: true, get: function () { return remote_customization_loader_1.DEFAULT_CUSTOMIZATION_ID; } });
+Object.defineProperty(exports, "clearRemoteCustomizationCache", { enumerable: true, get: function () { return remote_customization_loader_1.clearRemoteCustomizationCache; } });
+Object.defineProperty(exports, "isValidCustomizationId", { enumerable: true, get: function () { return remote_customization_loader_1.isValidCustomizationId; } });
+Object.defineProperty(exports, "loadRemoteCustomization", { enumerable: true, get: function () { return remote_customization_loader_1.loadRemoteCustomization; } });
+Object.defineProperty(exports, "remoteCustomizationLayers", { enumerable: true, get: function () { return remote_customization_loader_1.remoteCustomizationLayers; } });
 exports.DashboardDoc = __importStar(require("./doc/dashboard.structure.doc"));
 //# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,yEAAgE;AA4BvD,8FA5BA,mCAAa,OA4BA;AAEtB,2DAI8B;AAH1B,6HAAA,uBAAuB,OAAA;AACvB,oHAAA,cAAc,OAAA;AACd,qHAAA,eAAe,OAAA;AAEnB,uEAKyC;AAJrC,6GAAA,MAAM,OAAA;AACN,oIAAA,6BAA6B,OAAA;AAC7B,kIAAA,2BAA2B,OAAA;AAC3B,6HAAA,sBAAsB,OAAA;AAE1B,iEAIoC;AAHhC,2HAAA,qBAAqB,OAAA;AACrB,sHAAA,gBAAgB,OAAA;AAChB,wHAAA,kBAAkB,OAAA;AAEtB,iEAAgF;AAAvE,qHAAA,eAAe,OAAA;AAAE,uHAAA,iBAAiB,OAAA;AAC3C,6DAKkC;AAJ9B,gIAAA,4BAA4B,OAAA;AAC5B,oHAAA,gBAAgB,OAAA;AAChB,mHAAA,eAAe,OAAA;AACf,oHAAA,gBAAgB,OAAA;AAEpB,uDAM+B;AAL3B,qHAAA,oBAAoB,OAAA;AACpB,uHAAA,sBAAsB,OAAA;AACtB,qHAAA,oBAAoB,OAAA;AACpB,8GAAA,aAAa,OAAA;AACb,uHAAA,sBAAsB,OAAA;AAG1B,wFAIkD;AAH9C,yIAAA,0BAA0B,OAAA;AAC1B,qIAAA,sBAAsB,OAAA;AACtB,kIAAA,mBAAmB,OAAA;AAIvB,8EAA8D"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,yEAAgE;AA0CvD,8FA1CA,mCAAa,OA0CA;AAEtB,2DAI8B;AAH1B,6HAAA,uBAAuB,OAAA;AACvB,oHAAA,cAAc,OAAA;AACd,qHAAA,eAAe,OAAA;AAEnB,uEAKyC;AAJrC,6GAAA,MAAM,OAAA;AACN,oIAAA,6BAA6B,OAAA;AAC7B,kIAAA,2BAA2B,OAAA;AAC3B,6HAAA,sBAAsB,OAAA;AAE1B,iEAIoC;AAHhC,2HAAA,qBAAqB,OAAA;AACrB,sHAAA,gBAAgB,OAAA;AAChB,wHAAA,kBAAkB,OAAA;AAEtB,iEAAgF;AAAvE,qHAAA,eAAe,OAAA;AAAE,uHAAA,iBAAiB,OAAA;AAC3C,6DAKkC;AAJ9B,gIAAA,4BAA4B,OAAA;AAC5B,oHAAA,gBAAgB,OAAA;AAChB,mHAAA,eAAe,OAAA;AACf,oHAAA,gBAAgB,OAAA;AAEpB,uDAM+B;AAL3B,qHAAA,oBAAoB,OAAA;AACpB,uHAAA,sBAAsB,OAAA;AACtB,qHAAA,oBAAoB,OAAA;AACpB,8GAAA,aAAa,OAAA;AACb,uHAAA,sBAAsB,OAAA;AAG1B,wFAIkD;AAH9C,yIAAA,0BAA0B,OAAA;AAC1B,qIAAA,sBAAsB,OAAA;AACtB,kIAAA,mBAAmB,OAAA;AAIvB,gFAI8C;AAH1C,kIAAA,uBAAuB,OAAA;AACvB,+HAAA,oBAAoB,OAAA;AACpB,gIAAA,qBAAqB,OAAA;AAEzB,oFAO8C;AAN1C,sIAAA,uBAAuB,OAAA;AACvB,uIAAA,wBAAwB,OAAA;AACxB,4IAAA,6BAA6B,OAAA;AAC7B,qIAAA,sBAAsB,OAAA;AACtB,sIAAA,uBAAuB,OAAA;AACvB,wIAAA,yBAAyB,OAAA;AAG7B,8EAA8D"}

package/dist/cjs/metadata/customization-docs.js

@@ -0,0 +1,200 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCustomizationDocs = getCustomizationDocs;
+exports.getCustomizationDefaultDocs = getCustomizationDefaultDocs;
+const customization_metadata_1 = require("./customization-metadata");
+const submodule_labels_1 = require("./labels/submodule.labels");
+const configs_1 = require("../constants/configs");
+const structure_constants_1 = require("../constants/structure.constants");
+const structural_manager_1 = require("../structural-manager");
+const structural_helpers_1 = require("../utils/structural.helpers");
+const DEFAULT_AUDIENCE = 'partner';
+const compact = (value) => Object.fromEntries(Object.entries(value).filter(([, field]) => field !== undefined));
+const asObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value
+    : {};
+const viewPrefix = (view) => view ? `${view}${structure_constants_1.STRUCTURE_VIEW_NAME_SEPARATOR}` : '';
+const parentOf = (key) => {
+    const index = key.lastIndexOf(structure_constants_1.STRUCTURE_SECTION_NAME_SEPARATOR);
+    return index < 0 ? undefined : key.slice(0, index);
+};
+const typeOf = (value) => {
+    if (value === undefined)
+        return undefined;
+    return Array.isArray(value) ? 'Array' : typeof value;
+};
+// The deepest key a default's path starts with: 'filterPanel.defaultView' belongs to filterPanel.
+const ownerByPath = (name, keys) => keys
+    .filter((key) => name.startsWith(`${key}${structure_constants_1.STRUCTURE_SECTION_NAME_SEPARATOR}`))
+    .sort((left, right) => right.length - left.length)[0];
+// The defaults a key's structure node sets itself: the names it adds or changes over what its parent (or the root) passes
+// down, read from the engine's map so a section's defaults are not repeated on every key below it.
+function declaredDefaults(widget, structure) {
+    const instance = new structural_manager_1.WidgetStructureInstance((0, structural_helpers_1.calculateViewMap)(structure));
+    const root = asObject(structure.defaults);
+    const declared = new Map();
+    const views = structure.views ? Object.keys(structure.views) : [undefined];
+    views.forEach((view) => (0, customization_metadata_1.structureKeysOf)(widget, view, undefined, {
+        structure,
+    }).forEach((key) => {
+        const parent = parentOf(key);
+        const inherited = parent
+            ? asObject(instance.getDefaults(viewPrefix(view) + parent))
+            : root;
+        Object.entries(asObject(instance.getDefaults(viewPrefix(view) + key)))
+            .filter(([name, value]) => !(name in inherited) ||
+            JSON.stringify(inherited[name]) !==
+                JSON.stringify(value))
+            .forEach(([name, value]) => declared.set(key, Object.assign(Object.assign({}, declared.get(key)), { [name]: value })));
+    }));
+    return declared;
+}
+/**
+ * The documented defaults of a widget: the structure's own (with the value it sets as example), the paths its validators
+ * check, and the docs written for it, which add description, version, notes, type and accepted values. Documented names
+ * come first, in the order the docs list them.
+ */
+function defaultDocsOf(widget, structure, validators) {
+    var _a, _b;
+    const labels = (_b = (_a = customization_metadata_1.widgetMetadata[widget]) === null || _a === void 0 ? void 0 : _a.defaults) !== null && _b !== void 0 ? _b : {};
+    const values = new Map();
+    const declaredBy = new Map();
+    Object.entries(asObject(structure.defaults)).forEach(([name, value]) => values.set(name, value));
+    declaredDefaults(widget, structure).forEach((defaults, key) => Object.entries(defaults).forEach(([name, value]) => {
+        var _a;
+        if (!values.has(name))
+            values.set(name, value);
+        declaredBy.set(name, [...((_a = declaredBy.get(name)) !== null && _a !== void 0 ? _a : []), key]);
+    }));
+    const names = [
+        ...new Set([
+            ...Object.keys(labels),
+            ...values.keys(),
+            ...Object.keys(validators),
+        ]),
+    ];
+    const docs = names.map((name) => {
+        var _a, _b, _c;
+        const label = (_a = labels[name]) !== null && _a !== void 0 ? _a : {};
+        const value = values.get(name);
+        return compact({
+            name,
+            type: (_b = label.type) !== null && _b !== void 0 ? _b : typeOf(value),
+            values: label.values,
+            example: value === undefined ? label.example : JSON.stringify(value),
+            description: label.description,
+            since: label.since,
+            notes: label.notes,
+            audience: (_c = label.audience) !== null && _c !== void 0 ? _c : DEFAULT_AUDIENCE,
+        });
+    });
+    return { docs, declaredBy };
+}
+const validatorsOf = (widget, validationMap) => { var _a; return (_a = validationMap !== null && validationMap !== void 0 ? validationMap : configs_1.widgetValidators[widget]) !== null && _a !== void 0 ? _a : {}; };
+// The defaults of each key of a scope: the ones its node declares, else the ones whose path starts with it.
+function defaultsByKey({ docs, declaredBy }, keys) {
+    const byKey = new Map();
+    docs.forEach((doc) => {
+        var _a;
+        const declared = ((_a = declaredBy.get(doc.name)) !== null && _a !== void 0 ? _a : []).filter((key) => keys.includes(key));
+        const owners = declared.length
+            ? declared
+            : [ownerByPath(doc.name, keys)].filter((key) => !!key);
+        owners.forEach((key) => { var _a; return byKey.set(key, [...((_a = byKey.get(key)) !== null && _a !== void 0 ? _a : []), doc]); });
+    });
+    return byKey;
+}
+function flatten(widget, tree, scope, defaults) {
+    const keys = [];
+    const collect = (nodes) => nodes.forEach((node) => {
+        var _a;
+        keys.push(node.key);
+        collect((_a = node.children) !== null && _a !== void 0 ? _a : []);
+    });
+    collect(tree);
+    const byKey = defaultsByKey(defaults, keys);
+    // A key without an audience takes its section's, so an internal section keeps its keys out of the partner docs.
+    const walk = (nodes, parent, inherited) => nodes.flatMap((node) => {
+        var _a;
+        const { since, notes, audience } = (0, customization_metadata_1.getCustomizationLabel)(widget, node.key);
+        const own = audience !== null && audience !== void 0 ? audience : inherited;
+        const entry = compact({
+            key: node.key,
+            scope,
+            parent,
+            kind: node.kind,
+            label: node.label,
+            description: node.description,
+            since,
+            notes,
+            audience: own,
+            defaults: byKey.get(node.key),
+        });
+        return [entry, ...walk((_a = node.children) !== null && _a !== void 0 ? _a : [], node.key, own)];
+    });
+    return walk(tree, null, DEFAULT_AUDIENCE);
+}
+function subModuleEntry(widget, name, scope) {
+    var _a;
+    const key = `subModules${structure_constants_1.STRUCTURE_SECTION_NAME_SEPARATOR}${name}`;
+    const { label, description, since, notes, audience } = (_a = submodule_labels_1.SUBMODULE_LABELS[name]) !== null && _a !== void 0 ? _a : (0, customization_metadata_1.getCustomizationLabel)(widget, key);
+    return compact({
+        key,
+        scope,
+        parent: null,
+        kind: 'subModule',
+        label,
+        description,
+        since,
+        notes,
+        audience: audience !== null && audience !== void 0 ? audience : DEFAULT_AUDIENCE,
+    });
+}
+/**
+ * The customization keys of a widget as flat doc entries, one per key per scope: each view of the structure, then each
+ * submodule of the view ('design::chartPanel') with the keys its structure resolves to inside the host. Options may pass
+ * the structures to document, so a host can describe the tree it shipped with instead of this package's.
+ */
+function getCustomizationDocs(widget, options = {}) {
+    const structure = (0, customization_metadata_1.structureRootOf)(widget, options);
+    const map = (0, structural_helpers_1.calculateViewMap)(structure);
+    const hostDefaults = defaultDocsOf(widget, structure, validatorsOf(widget, options.validationMap));
+    const views = structure.views
+        ? Object.keys(structure.views).filter((view) => !options.views || options.views.includes(view))
+        : [undefined];
+    return views.flatMap((view) => {
+        const scope = view !== null && view !== void 0 ? view : '';
+        const target = { views: view ? [view] : [] };
+        const entries = flatten(widget, (0, customization_metadata_1.getCustomizationTree)(widget, target, options), scope, hostDefaults);
+        Object.keys(asObject(map[`${viewPrefix(view)}subModules`]))
+            .filter((name) => !options.subModules || options.subModules.includes(name))
+            .forEach((name) => {
+            entries.push(subModuleEntry(widget, name, scope));
+            const embedded = (0, customization_metadata_1.findWidgetOfSubmodule)(name);
+            // A submodule no widget is registered for is listed, but has no keys to document.
+            if (!embedded)
+                return;
+            entries.push(...flatten(embedded, (0, customization_metadata_1.getCustomizationTree)(widget, Object.assign(Object.assign({}, target), { subModules: [name] }), options), view
+                ? `${view}${structure_constants_1.STRUCTURE_VIEW_NAME_SEPARATOR}${name}`
+                : name, defaultDocsOf(embedded, (0, customization_metadata_1.structureRootOf)(embedded, options, name), validatorsOf(embedded))));
+        });
+        return entries;
+    });
+}
+/**
+ * Every documented default of a widget, with the key it belongs to: the defaults no key owns (customStyles,
+ * unsavedChangesBehavior) apply to the whole widget and come with a null key.
+ */
+function getCustomizationDefaultDocs(widget, options = {}) {
+    const structure = (0, customization_metadata_1.structureRootOf)(widget, options);
+    const { docs, declaredBy } = defaultDocsOf(widget, structure, validatorsOf(widget, options.validationMap));
+    const views = structure.views ? Object.keys(structure.views) : [undefined];
+    const keys = [
+        ...new Set(views.flatMap((view) => (0, customization_metadata_1.structureKeysOf)(widget, view, undefined, { structure }))),
+    ];
+    return docs.map((doc) => {
+        var _a, _b, _c;
+        return (Object.assign(Object.assign({}, doc), { key: (_c = (_b = (_a = declaredBy.get(doc.name)) === null || _a === void 0 ? void 0 : _a[0]) !== null && _b !== void 0 ? _b : ownerByPath(doc.name, keys)) !== null && _c !== void 0 ? _c : null }));
+    });
+}
+//# sourceMappingURL=customization-docs.js.map

package/dist/cjs/metadata/customization-docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"customization-docs.js","sourceRoot":"","sources":["../../../src/metadata/customization-docs.ts"],"names":[],"mappings":"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"}

package/dist/cjs/metadata/customization-metadata.js

@@ -0,0 +1,297 @@
+"use strict";
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findWidgetOfSubmodule = exports.widgetMetadata = void 0;
+exports.structureRootOf = structureRootOf;
+exports.structureKeysOf = structureKeysOf;
+exports.getCustomizationLabel = getCustomizationLabel;
+exports.getCustomizationTree = getCustomizationTree;
+exports.lockOf = lockOf;
+exports.getCustomizationTreeState = getCustomizationTreeState;
+exports.toggleCustomizationKey = toggleCustomizationKey;
+const chart_panel_defaults_1 = require("./labels/chart-panel.defaults");
+const chart_panel_labels_1 = require("./labels/chart-panel.labels");
+const dashboard_defaults_1 = require("./labels/dashboard.defaults");
+const dashboard_labels_1 = require("./labels/dashboard.labels");
+const structure_constants_1 = require("../constants/structure.constants");
+const structural_manager_1 = require("../structural-manager");
+const scope_helpers_1 = require("../utils/scope.helpers");
+const structural_helpers_1 = require("../utils/structural.helpers");
+// Label maps by widget, and the docs of their defaults; a new widget adds its maps here and the guard spec checks them (3.7.1).
+exports.widgetMetadata = {
+    [structure_constants_1.Widget.DASHBOARD]: {
+        labels: dashboard_labels_1.DASHBOARD_LABELS,
+        defaults: dashboard_defaults_1.DASHBOARD_DEFAULTS,
+    },
+    [structure_constants_1.Widget.CHART_PANEL]: {
+        labels: chart_panel_labels_1.CHART_PANEL_LABELS,
+        defaults: chart_panel_defaults_1.CHART_PANEL_DEFAULTS,
+    },
+};
+const findWidgetOfSubmodule = (name) => Object.keys(structure_constants_1.WIDGET_SUBMODULE_NAMES).find((key) => structure_constants_1.WIDGET_SUBMODULE_NAMES[key] === name);
+exports.findWidgetOfSubmodule = findWidgetOfSubmodule;
+const widgetOfSubmodule = (name) => {
+    const widget = (0, exports.findWidgetOfSubmodule)(name);
+    if (!widget)
+        throw new Error(`No widget registered for the submodule ${name}`);
+    return widget;
+};
+const isWidgetConfig = (source) => typeof source.version === 'string' &&
+    typeof source.baseStructure === 'object';
+const rootOf = (source) => isWidgetConfig(source) ? source.baseStructure : source;
+/**
+ * The structure to read for a widget, or for the widget a submodule name embeds: the caller's when it passes one (a host
+ * documenting the tree it released with), else the one this package ships.
+ */
+function structureRootOf(widget, options = {}, subModule) {
+    var _a;
+    const source = subModule
+        ? (_a = options.subModuleStructures) === null || _a === void 0 ? void 0 : _a[subModule]
+        : options.structure;
+    if (source)
+        return rootOf(source);
+    return (0, structural_manager_1.getWidgetConfig)(widget, subModule ? undefined : options.version)
+        .baseStructure;
+}
+const asCustomization = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value
+    : undefined;
+// Keys of a target. A submodule's keys come from its structure under the customization its host declares for it, the way
+// structureFromSubmodule builds it, so a host structure that removes a chart panel key leaves it out of the tree.
+function resolveTarget(widget, target, options) {
+    var _a;
+    const subModules = (_a = target.subModules) !== null && _a !== void 0 ? _a : [];
+    const host = structureRootOf(widget, options);
+    const views = host.views ? target.views : [undefined];
+    if (!subModules.length) {
+        return {
+            widget,
+            keys: views.map((view) => structureKeysOf(widget, view, options.version, {
+                structure: host,
+            })),
+        };
+    }
+    const embedded = widgetOfSubmodule(subModules[subModules.length - 1]);
+    return {
+        widget: embedded,
+        keys: views.map((view) => {
+            let structure = host;
+            let customization;
+            let hostView = view;
+            subModules.forEach((name) => {
+                const instance = new structural_manager_1.WidgetStructureInstance((0, structural_helpers_1.calculateViewMap)(structure, customization));
+                customization = asCustomization(instance.getSubmodule(name, hostView));
+                structure = structureRootOf(widgetOfSubmodule(name), options, name);
+                hostView = structure.views ? view : undefined;
+            });
+            return structureKeysOf(embedded, hostView, undefined, {
+                structure,
+                customization,
+            });
+        }),
+    };
+}
+/**
+ * Keys of the structure in a view (or at the root), in structure order, without the view prefix. Reads the structure the
+ * options pass, under their customization, instead of the one this package ships when they set one.
+ */
+function structureKeysOf(widget, view, version, options = {}) {
+    const map = (0, structural_helpers_1.calculateViewMap)(options.structure
+        ? rootOf(options.structure)
+        : (0, structural_manager_1.getWidgetConfig)(widget, version).baseStructure, options.customization);
+    const prefix = view ? `${view}${structure_constants_1.STRUCTURE_VIEW_NAME_SEPARATOR}` : '';
+    return Object.keys(map)
+        .filter((key) => view
+        ? key.startsWith(prefix)
+        : !key.includes(structure_constants_1.STRUCTURE_VIEW_NAME_SEPARATOR))
+        .map((key) => key.slice(prefix.length))
+        .filter((key) => key !== 'subModules');
+}
+const humanize = (id) => id
+    .replace(/^q(?=[A-Z])/, '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/^./, (char) => char.toUpperCase());
+/**
+ * Label of a key: full path first, then the leaf id; a humanized id when neither exists.
+ */
+function getCustomizationLabel(widget, key) {
+    var _a, _b, _c, _d, _e;
+    const labels = (_b = (_a = exports.widgetMetadata[widget]) === null || _a === void 0 ? void 0 : _a.labels) !== null && _b !== void 0 ? _b : {};
+    const id = (_c = key.split(structure_constants_1.STRUCTURE_SECTION_NAME_SEPARATOR).pop()) !== null && _c !== void 0 ? _c : key;
+    return (_e = (_d = labels[key]) !== null && _d !== void 0 ? _d : labels[id]) !== null && _e !== void 0 ? _e : { label: humanize(id) };
+}
+/**
+ * The labelled tree of a target: a widget view, or the structure of the embedded widget when subModules is set. Options
+ * may pass the structures to read (CustomizationStructureOptions).
+ */
+function getCustomizationTree(widget, target, options = {}) {
+    const resolved = resolveTarget(widget, target, options);
+    const ordered = [];
+    resolved.keys.forEach((keys) => keys.forEach((key) => {
+        if (!ordered.includes(key))
+            ordered.push(key);
+    }));
+    const roots = [];
+    const nodes = new Map();
+    const ensure = (key) => {
+        var _a;
+        const existing = nodes.get(key);
+        if (existing)
+            return existing;
+        const parts = key.split(structure_constants_1.STRUCTURE_SECTION_NAME_SEPARATOR);
+        const { label, description } = getCustomizationLabel(resolved.widget, key);
+        const node = Object.assign(Object.assign({ key, id: parts[parts.length - 1], label }, (description && { description })), { kind: 'item' });
+        nodes.set(key, node);
+        if (parts.length === 1) {
+            roots.push(node);
+        }
+        else {
+            const parent = ensure(parts.slice(0, -1).join(structure_constants_1.STRUCTURE_SECTION_NAME_SEPARATOR));
+            parent.kind = 'section';
+            parent.children = [...((_a = parent.children) !== null && _a !== void 0 ? _a : []), node];
+        }
+        return node;
+    };
+    ordered.forEach(ensure);
+    return roots;
+}
+function instanceFor(widget, customization, target, view) {
+    var _a;
+    let instance = (0, structural_manager_1.buildStructure)(widget, customization);
+    ((_a = target.subModules) !== null && _a !== void 0 ? _a : []).forEach((name) => {
+        instance = (0, scope_helpers_1.structureFromSubmodule)(instance, name, view);
+    });
+    return instance;
+}
+const matches = (pattern, key) => pattern === key ||
+    new RegExp(`^${pattern.replace(/\./g, '\\.').replace(/\*/g, '.*')}$`).test(key);
+// The block where the tree's switches write, and the blocks above it whose rules a switch cannot undo.
+function scopesOf(customization, target, view) {
+    var _a, _b, _c, _d, _e, _f;
+    const subModules = (_a = target.subModules) !== null && _a !== void 0 ? _a : [];
+    if (!subModules.length) {
+        return { own: (_b = customization === null || customization === void 0 ? void 0 : customization.views) === null || _b === void 0 ? void 0 : _b[view], root: customization };
+    }
+    const name = subModules[subModules.length - 1];
+    return {
+        own: (_e = (_d = (_c = customization === null || customization === void 0 ? void 0 : customization.views) === null || _c === void 0 ? void 0 : _c[view]) === null || _d === void 0 ? void 0 : _d.subModules) === null || _e === void 0 ? void 0 : _e[name],
+        root: (_f = customization === null || customization === void 0 ? void 0 : customization.subModules) === null || _f === void 0 ? void 0 : _f[name],
+    };
+}
+function lockOf(customization, target, view, key, hiddenParent) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const { own, root } = scopesOf(customization, target, view);
+    if (hiddenParent)
+        return { verb: 'remove', pattern: hiddenParent, scope: 'parent' };
+    if ((_a = own === null || own === void 0 ? void 0 : own.remove) === null || _a === void 0 ? void 0 : _a.includes(key))
+        return undefined;
+    const rootRemove = (_b = root === null || root === void 0 ? void 0 : root.remove) === null || _b === void 0 ? void 0 : _b.find((pattern) => matches(pattern, key));
+    if (rootRemove)
+        return { verb: 'remove', pattern: rootRemove, scope: 'root' };
+    const viewRemove = (_c = own === null || own === void 0 ? void 0 : own.remove) === null || _c === void 0 ? void 0 : _c.find((pattern) => matches(pattern, key));
+    if (viewRemove)
+        return { verb: 'remove', pattern: viewRemove, scope: 'view' };
+    if ((_d = root === null || root === void 0 ? void 0 : root.keep) === null || _d === void 0 ? void 0 : _d.length)
+        return { verb: 'keep', pattern: root.keep.join(', '), scope: 'root' };
+    if ((_e = own === null || own === void 0 ? void 0 : own.keep) === null || _e === void 0 ? void 0 : _e.length)
+        return { verb: 'keep', pattern: own.keep.join(', '), scope: 'view' };
+    // Hidden by something the switches do not write (a conditional, a submodule rule of the host).
+    return {
+        verb: 'remove',
+        pattern: key,
+        scope: ((_f = own === null || own === void 0 ? void 0 : own.conditional) === null || _f === void 0 ? void 0 : _f.length) || ((_g = root === null || root === void 0 ? void 0 : root.conditional) === null || _g === void 0 ? void 0 : _g.length)
+            ? 'conditional'
+            : 'view',
+    };
+}
+/**
+ * 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.
+ */
+function getCustomizationTreeState(widget, customization, target) {
+    var _a;
+    const tree = getCustomizationTree(widget, target);
+    const embedded = !!((_a = target.subModules) === null || _a === void 0 ? void 0 : _a.length);
+    const instances = target.views.map((view) => ({
+        view,
+        instance: instanceFor(widget, customization, target, view),
+    }));
+    const isVisible = (instance, view, key) => instance.isVisible(embedded ? key : `${view}${structure_constants_1.STRUCTURE_VIEW_NAME_SEPARATOR}${key}`, {});
+    const walk = (nodes, hiddenParents) => nodes.map((node) => {
+        const states = instances.map(({ view, instance }) => isVisible(instance, view, node.key));
+        const visible = states.every(Boolean)
+            ? true
+            : states.some(Boolean)
+                ? 'mixed'
+                : false;
+        const locks = visible === false
+            ? instances.map(({ view }, index) => lockOf(customization, target, view, node.key, hiddenParents[index]))
+            : [];
+        const lockedBy = locks.length && locks.every(Boolean) ? locks[0] : undefined;
+        const childParents = states.map((state, index) => { var _a; return (_a = hiddenParents[index]) !== null && _a !== void 0 ? _a : (state ? undefined : node.key); });
+        const { children } = node, rest = __rest(node, ["children"]);
+        const stateNode = Object.assign(Object.assign({}, rest), { visible });
+        if (lockedBy)
+            stateNode.lockedBy = lockedBy;
+        if (children)
+            stateNode.children = walk(children, childParents);
+        return stateNode;
+    });
+    return walk(tree, instances.map(() => undefined));
+}
+const isEmptyObject = (value) => typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.keys(value).length === 0;
+/**
+ * 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.
+ */
+function toggleCustomizationKey(customization, target, key, visible) {
+    const result = JSON.parse(JSON.stringify(customization !== null && customization !== void 0 ? customization : {}));
+    target.views.forEach((view) => {
+        var _a, _b;
+        const chain = [
+            result,
+        ];
+        const step = (holder, name) => {
+            var _a;
+            holder[name] = (_a = holder[name]) !== null && _a !== void 0 ? _a : {};
+            chain.push(holder[name]);
+            return holder[name];
+        };
+        let block = step(step(result, 'views'), view);
+        ((_a = target.subModules) !== null && _a !== void 0 ? _a : []).forEach((name) => {
+            block = step(step(block, 'subModules'), name);
+        });
+        const remove = (_b = block.remove) !== null && _b !== void 0 ? _b : [];
+        if (!visible && !remove.includes(key))
+            block.remove = [...remove, key];
+        if (visible) {
+            const next = remove.filter((item) => item !== key);
+            if (next.length)
+                block.remove = next;
+            else
+                delete block.remove;
+        }
+        // Drops the empty objects this switch left behind, from the innermost out.
+        for (let index = chain.length - 1; index > 0; index--) {
+            const holder = chain[index - 1];
+            const name = Object.keys(holder).find((property) => holder[property] === chain[index]);
+            if (name && isEmptyObject(chain[index]))
+                delete holder[name];
+        }
+    });
+    return result;
+}
+//# sourceMappingURL=customization-metadata.js.map