@contrail/extensions-sdk 1.0.24 → 1.0.25
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/lib/apps/plan.d.ts +64 -1
- package/lib/apps/plan.js +64 -0
- package/package.json +1 -1
package/lib/apps/plan.d.ts
CHANGED
|
@@ -4,7 +4,8 @@ export declare enum PlanCommand {
|
|
|
4
4
|
SHOW_MESSAGE = "plan:show_message",
|
|
5
5
|
CLEAR_SELECTED_ROWS = "plan:clear_selected_rows",
|
|
6
6
|
ADD_PLACEHOLDERS = "plan:add_placeholders",
|
|
7
|
-
ADD_PLACEHOLDERS_WITH_ITEMS = "plan:add_placeholders_with_items"
|
|
7
|
+
ADD_PLACEHOLDERS_WITH_ITEMS = "plan:add_placeholders_with_items",
|
|
8
|
+
GET_PLACEHOLDERS = "plan:get_placeholders"
|
|
8
9
|
}
|
|
9
10
|
/**
|
|
10
11
|
* A row on a plan. Beyond the item linkage below, properties are the org-configured
|
|
@@ -23,10 +24,72 @@ export interface AddPlaceholdersOptions {
|
|
|
23
24
|
/** Skip the undo/redo entry. Intended for bulk programmatic writes. */
|
|
24
25
|
skipRecordingUndoRedo?: boolean;
|
|
25
26
|
}
|
|
27
|
+
/**
|
|
28
|
+
* Which rows {@link PlanApp.getPlaceholders} should return. Mirrors the plan's own data scopes.
|
|
29
|
+
*
|
|
30
|
+
* - `all` — every row on the plan, ignoring filters (the default)
|
|
31
|
+
* - `filtered` — the user's active filter applied
|
|
32
|
+
* - `displayed` — filter plus focused item family, i.e. what the grid is actually showing
|
|
33
|
+
* - `selected` — only the currently selected rows
|
|
34
|
+
*/
|
|
35
|
+
export declare type PlanPlaceholderScope = 'all' | 'filtered' | 'displayed' | 'selected';
|
|
36
|
+
export interface GetPlaceholdersOptions {
|
|
37
|
+
/** Defaults to `all`. */
|
|
38
|
+
scope?: PlanPlaceholderScope;
|
|
39
|
+
/**
|
|
40
|
+
* Return only these property slugs, to keep the payload small on large plans.
|
|
41
|
+
* `id`, `itemFamilyId` and `itemOptionId` are always included.
|
|
42
|
+
*/
|
|
43
|
+
propertySlugs?: Array<string>;
|
|
44
|
+
}
|
|
26
45
|
export declare class PlanApp {
|
|
27
46
|
static getCurrentPlan(): PlanContext;
|
|
47
|
+
/**
|
|
48
|
+
* The plan's rows **as they were when this extension opened**.
|
|
49
|
+
*
|
|
50
|
+
* Synchronous and free, because it reads the context snapshot the host sent at startup. That
|
|
51
|
+
* snapshot is never re-sent, so it will not contain rows created since (including ones this
|
|
52
|
+
* extension created itself), edits made in the grid, or other users' changes.
|
|
53
|
+
*
|
|
54
|
+
* Use this for a one-shot read on open. For current state, `await` {@link getPlaceholders} —
|
|
55
|
+
* which also refreshes what this method returns.
|
|
56
|
+
*/
|
|
28
57
|
static getAllPlanPlaceholders(): any[];
|
|
58
|
+
/**
|
|
59
|
+
* The snapshot narrowed to the user's active filter — the same startup snapshot as
|
|
60
|
+
* {@link getAllPlanPlaceholders}, and equally subject to going stale.
|
|
61
|
+
*
|
|
62
|
+
* Note this filters the snapshot by the `filteredPlanPlaceholderIds` captured at startup, so it
|
|
63
|
+
* reflects the filter *at open time*. If the user changes the filter while the extension is open,
|
|
64
|
+
* use `getPlaceholders({ scope: 'filtered' })` instead.
|
|
65
|
+
*/
|
|
29
66
|
static getFilteredPlanPlaceholders(): any[];
|
|
67
|
+
/**
|
|
68
|
+
* The plan's rows **as they are right now**, read from the host on demand.
|
|
69
|
+
*
|
|
70
|
+
* Asynchronous, because it round-trips to the plan. Returns fully hydrated rows — property
|
|
71
|
+
* defaults applied and formulas evaluated — so it is the only way to see the real state of rows
|
|
72
|
+
* created during this session, or edits the user has made in the grid since it opened.
|
|
73
|
+
*
|
|
74
|
+
* ### How this differs from {@link getAllPlanPlaceholders}
|
|
75
|
+
*
|
|
76
|
+
* | | `getAllPlanPlaceholders()` | `getPlaceholders()` |
|
|
77
|
+
* | --- | --- | --- |
|
|
78
|
+
* | Source | startup context snapshot | live host state |
|
|
79
|
+
* | Call | synchronous | `await` |
|
|
80
|
+
* | Sees later changes | no | yes |
|
|
81
|
+
* | Scope | all, or filter-at-open-time | `all` / `filtered` / `displayed` / `selected` |
|
|
82
|
+
*
|
|
83
|
+
* ### Side effect
|
|
84
|
+
*
|
|
85
|
+
* A **full, unprojected** read (no `scope`, or `scope: 'all'`, and no `propertySlugs`) replaces
|
|
86
|
+
* the cached snapshot, so `getAllPlanPlaceholders()` returns the fresh rows afterwards. A
|
|
87
|
+
* filtered or projected read deliberately does not, since a partial result is not a valid
|
|
88
|
+
* substitute for the snapshot.
|
|
89
|
+
*
|
|
90
|
+
* Reading is always permitted, including on a view-only plan.
|
|
91
|
+
*/
|
|
92
|
+
static getPlaceholders(options?: GetPlaceholdersOptions): Promise<Array<PlanPlaceholder>>;
|
|
30
93
|
/**
|
|
31
94
|
* Creates new rows on the plan from property data, and returns them.
|
|
32
95
|
*
|
package/lib/apps/plan.js
CHANGED
|
@@ -19,18 +19,37 @@ var PlanCommand;
|
|
|
19
19
|
PlanCommand["CLEAR_SELECTED_ROWS"] = "plan:clear_selected_rows";
|
|
20
20
|
PlanCommand["ADD_PLACEHOLDERS"] = "plan:add_placeholders";
|
|
21
21
|
PlanCommand["ADD_PLACEHOLDERS_WITH_ITEMS"] = "plan:add_placeholders_with_items";
|
|
22
|
+
PlanCommand["GET_PLACEHOLDERS"] = "plan:get_placeholders";
|
|
22
23
|
})(PlanCommand = exports.PlanCommand || (exports.PlanCommand = {}));
|
|
23
24
|
class PlanApp {
|
|
24
25
|
static getCurrentPlan() {
|
|
25
26
|
PlanApp.validatePlanContext();
|
|
26
27
|
return (0, app_context_1.getAppContext)().appContext.plan;
|
|
27
28
|
}
|
|
29
|
+
/**
|
|
30
|
+
* The plan's rows **as they were when this extension opened**.
|
|
31
|
+
*
|
|
32
|
+
* Synchronous and free, because it reads the context snapshot the host sent at startup. That
|
|
33
|
+
* snapshot is never re-sent, so it will not contain rows created since (including ones this
|
|
34
|
+
* extension created itself), edits made in the grid, or other users' changes.
|
|
35
|
+
*
|
|
36
|
+
* Use this for a one-shot read on open. For current state, `await` {@link getPlaceholders} —
|
|
37
|
+
* which also refreshes what this method returns.
|
|
38
|
+
*/
|
|
28
39
|
static getAllPlanPlaceholders() {
|
|
29
40
|
var _a;
|
|
30
41
|
PlanApp.validatePlanContext();
|
|
31
42
|
const plan = PlanApp.getCurrentPlan();
|
|
32
43
|
return (_a = plan === null || plan === void 0 ? void 0 : plan.planPlaceholders) !== null && _a !== void 0 ? _a : [];
|
|
33
44
|
}
|
|
45
|
+
/**
|
|
46
|
+
* The snapshot narrowed to the user's active filter — the same startup snapshot as
|
|
47
|
+
* {@link getAllPlanPlaceholders}, and equally subject to going stale.
|
|
48
|
+
*
|
|
49
|
+
* Note this filters the snapshot by the `filteredPlanPlaceholderIds` captured at startup, so it
|
|
50
|
+
* reflects the filter *at open time*. If the user changes the filter while the extension is open,
|
|
51
|
+
* use `getPlaceholders({ scope: 'filtered' })` instead.
|
|
52
|
+
*/
|
|
34
53
|
static getFilteredPlanPlaceholders() {
|
|
35
54
|
var _a;
|
|
36
55
|
PlanApp.validatePlanContext();
|
|
@@ -43,6 +62,51 @@ class PlanApp {
|
|
|
43
62
|
const filteredResults = allPlanPlaceholders.filter((placeholder) => filteredPlanPlaceholderIds.includes(placeholder.id));
|
|
44
63
|
return filteredResults;
|
|
45
64
|
}
|
|
65
|
+
/**
|
|
66
|
+
* The plan's rows **as they are right now**, read from the host on demand.
|
|
67
|
+
*
|
|
68
|
+
* Asynchronous, because it round-trips to the plan. Returns fully hydrated rows — property
|
|
69
|
+
* defaults applied and formulas evaluated — so it is the only way to see the real state of rows
|
|
70
|
+
* created during this session, or edits the user has made in the grid since it opened.
|
|
71
|
+
*
|
|
72
|
+
* ### How this differs from {@link getAllPlanPlaceholders}
|
|
73
|
+
*
|
|
74
|
+
* | | `getAllPlanPlaceholders()` | `getPlaceholders()` |
|
|
75
|
+
* | --- | --- | --- |
|
|
76
|
+
* | Source | startup context snapshot | live host state |
|
|
77
|
+
* | Call | synchronous | `await` |
|
|
78
|
+
* | Sees later changes | no | yes |
|
|
79
|
+
* | Scope | all, or filter-at-open-time | `all` / `filtered` / `displayed` / `selected` |
|
|
80
|
+
*
|
|
81
|
+
* ### Side effect
|
|
82
|
+
*
|
|
83
|
+
* A **full, unprojected** read (no `scope`, or `scope: 'all'`, and no `propertySlugs`) replaces
|
|
84
|
+
* the cached snapshot, so `getAllPlanPlaceholders()` returns the fresh rows afterwards. A
|
|
85
|
+
* filtered or projected read deliberately does not, since a partial result is not a valid
|
|
86
|
+
* substitute for the snapshot.
|
|
87
|
+
*
|
|
88
|
+
* Reading is always permitted, including on a view-only plan.
|
|
89
|
+
*/
|
|
90
|
+
static getPlaceholders(options) {
|
|
91
|
+
var _a, _b, _c;
|
|
92
|
+
return __awaiter(this, void 0, void 0, function* () {
|
|
93
|
+
PlanApp.validatePlanContext();
|
|
94
|
+
const results = yield (0, actions_1.getExtensionActions)().sendMessageToHost({
|
|
95
|
+
command: PlanCommand.GET_PLACEHOLDERS,
|
|
96
|
+
data: { options },
|
|
97
|
+
});
|
|
98
|
+
const placeholders = (_a = PlanApp.validateAndReturnResults(results)) !== null && _a !== void 0 ? _a : [];
|
|
99
|
+
const isFullRead = (!(options === null || options === void 0 ? void 0 : options.scope) || options.scope === 'all') && !((_b = options === null || options === void 0 ? void 0 : options.propertySlugs) === null || _b === void 0 ? void 0 : _b.length);
|
|
100
|
+
if (isFullRead) {
|
|
101
|
+
// getAppContext() hands back the live singleton, so this updates what the sync getters see.
|
|
102
|
+
const plan = (_c = (0, app_context_1.getAppContext)().appContext) === null || _c === void 0 ? void 0 : _c.plan;
|
|
103
|
+
if (plan) {
|
|
104
|
+
plan.planPlaceholders = placeholders;
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
return placeholders;
|
|
108
|
+
});
|
|
109
|
+
}
|
|
46
110
|
/**
|
|
47
111
|
* Creates new rows on the plan from property data, and returns them.
|
|
48
112
|
*
|
package/package.json
CHANGED