@contentstack/studio-client 3.2.0 → 4.0.0
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/dist/breakpoints/BreakpointManager.js +7 -5
- package/dist/breakpoints/BreakpointManager.js.map +1 -1
- package/dist/breakpoints/breakpoint.js +3 -2
- package/dist/breakpoints/breakpoint.js.map +1 -1
- package/dist/canvas/canvas.utils.js +13 -1
- package/dist/canvas/canvas.utils.js.map +1 -1
- package/dist/composable-studio/build-scoped-data.js +12 -35
- package/dist/composable-studio/build-scoped-data.js.map +1 -1
- package/dist/composable-studio/sdk.js +1064 -430
- package/dist/composable-studio/sdk.js.map +1 -1
- package/dist/composable-studio/studio-intelligence.manager.js +5 -2
- package/dist/composable-studio/studio-intelligence.manager.js.map +1 -1
- package/dist/config/config.schema.js +45 -8
- package/dist/config/config.schema.js.map +1 -1
- package/dist/config/default-config.js +10 -3
- package/dist/config/default-config.js.map +1 -1
- package/dist/config/process-user-config.js +37 -1
- package/dist/config/process-user-config.js.map +1 -1
- package/dist/config/stack-sdk-wrapper.js +36 -1
- package/dist/config/stack-sdk-wrapper.js.map +1 -1
- package/dist/context-menu/context-menu.js +5 -2
- package/dist/context-menu/context-menu.js.map +1 -1
- package/dist/design/handle-active-style-change.js +3 -2
- package/dist/design/handle-active-style-change.js.map +1 -1
- package/dist/dnd/dnd-event.js +2 -1
- package/dist/dnd/dnd-event.js.map +1 -1
- package/dist/dnd/dnd-manager.js +3 -1
- package/dist/dnd/dnd-manager.js.map +1 -1
- package/dist/editor.d.ts +250 -0
- package/dist/editor.js +11 -0
- package/dist/editor.js.map +1 -0
- package/dist/get-active-node-screenshot/get-node-screenshot-event.js +2 -1
- package/dist/get-active-node-screenshot/get-node-screenshot-event.js.map +1 -1
- package/dist/hidden-element-notification/hidden-element-notification-event.js +2 -1
- package/dist/hidden-element-notification/hidden-element-notification-event.js.map +1 -1
- package/dist/highlight-node/highlight-node-manager.js +225 -15
- package/dist/highlight-node/highlight-node-manager.js.map +1 -1
- package/dist/highlight-node/highlight-node.js +42 -6
- package/dist/highlight-node/highlight-node.js.map +1 -1
- package/dist/highlight-spacing/highlight-spacing-events.js +2 -1
- package/dist/highlight-spacing/highlight-spacing-events.js.map +1 -1
- package/dist/index.d.ts +1006 -436
- package/dist/index.js +12 -13
- package/dist/index.js.map +1 -1
- package/dist/url-change/url-change.js +4 -3
- package/dist/url-change/url-change.js.map +1 -1
- package/dist/url-metadata/build-template-query.js +14 -3
- package/dist/url-metadata/build-template-query.js.map +1 -1
- package/dist/utils/canvas.js +2 -1
- package/dist/utils/canvas.js.map +1 -1
- package/dist/utils/check-bindings.js +233 -0
- package/dist/utils/check-bindings.js.map +1 -0
- package/dist/utils/classify-response-error.js +288 -0
- package/dist/utils/classify-response-error.js.map +1 -0
- package/dist/utils/composable-studio-error.js +36 -20
- package/dist/utils/composable-studio-error.js.map +1 -1
- package/dist/utils/composition-not-found.js +52 -0
- package/dist/utils/composition-not-found.js.map +1 -0
- package/dist/utils/constants.js +21 -2
- package/dist/utils/constants.js.map +1 -1
- package/dist/utils/degraded-finding.js +166 -0
- package/dist/utils/degraded-finding.js.map +1 -0
- package/dist/utils/editor-mode.js +1 -1
- package/dist/utils/http-error.constants.js +12 -46
- package/dist/utils/http-error.constants.js.map +1 -1
- package/dist/utils/include-path-rules.js +40 -1
- package/dist/utils/include-path-rules.js.map +1 -1
- package/dist/utils/is-composition-being-edited.js +1 -1
- package/dist/utils/is-inside-iframe.js +1 -1
- package/dist/utils/is-inside-visual-builder-frame.js +1 -1
- package/dist/utils/parse-ui.js +60 -0
- package/dist/utils/parse-ui.js.map +1 -0
- package/dist/utils/query-param.js +1 -1
- package/dist/utils/query-param.js.map +1 -1
- package/dist/utils/reference-stub.js +75 -0
- package/dist/utils/reference-stub.js.map +1 -0
- package/dist/utils/reference_fetcher.js +44 -3
- package/dist/utils/reference_fetcher.js.map +1 -1
- package/dist/utils/require-stack.js +141 -0
- package/dist/utils/require-stack.js.map +1 -0
- package/dist/utils/served-by.js +33 -0
- package/dist/utils/served-by.js.map +1 -0
- package/dist/utils/studio-error-codes.js +253 -0
- package/dist/utils/studio-error-codes.js.map +1 -0
- package/dist/utils/studio-error.js +122 -0
- package/dist/utils/studio-error.js.map +1 -0
- package/dist/utils/studio-messaging.js +25 -0
- package/dist/utils/studio-messaging.js.map +1 -0
- package/dist/visual-builder/composition-save-event.js +2 -1
- package/dist/visual-builder/composition-save-event.js.map +1 -1
- package/package.json +19 -6
- package/dist/utils/error-messages.default.js +0 -141
- package/dist/utils/error-messages.default.js.map +0 -1
- package/dist/utils/error-messages.js +0 -47
- package/dist/utils/error-messages.js.map +0 -1
package/dist/index.d.ts
CHANGED
|
@@ -3,14 +3,16 @@ import { Node, BindingType, PathNode, Operation, Descendant, Path, Condition, No
|
|
|
3
3
|
import * as _contentstack_studio_registry from '@contentstack/studio-registry';
|
|
4
4
|
import { StudioStateConfig, RawStaticValue, ICSEntryReference, StudioSpecData, DataSources, SectionScopedDataSources, StaticValue, BreakpointInput, Breakpoint } from '@contentstack/studio-registry';
|
|
5
5
|
export { Breakpoint } from '@contentstack/studio-registry';
|
|
6
|
+
import { ComposableStudioQueryParams, ComposableStudioQueryParamsKeys } from '@contentstack/studio-messenger/types';
|
|
6
7
|
import * as _contentstack_studio_messenger from '@contentstack/studio-messenger';
|
|
7
|
-
import { CompositionQuery, CompositionQueryInput,
|
|
8
|
+
import { CompositionQuery, CompositionQueryInput, HiddenElementNotificationEventData } from '@contentstack/studio-messenger';
|
|
8
9
|
export { IS_BROWSER } from '@contentstack/studio-messenger';
|
|
9
10
|
import { z } from 'zod';
|
|
10
11
|
import deliverySdk, { BaseAsset } from '@contentstack/delivery-sdk';
|
|
11
12
|
import { Stack } from 'contentstack';
|
|
12
13
|
import { HitboxDetails, SerializedEvent, RefetchSpecEventData } from '@contentstack/studio-message-types/latest';
|
|
13
|
-
export { ActiveBreakpointEventPayload, BaseHighlightEventPayload, ChangeActiveStyleGroupPayload, ComputedStyleSection, DraggerPosition, HighlightActiveNodeEventPayload, HighlightAncestorsEventPayload, HighlightFocusedNodeEventPayload, HighlightNodeEventPayload, HighlightSlotNodeEventPayload, HighlightStyleNodeEventPayload, HitboxDetails, MouseMoveEventPayload, MouseUpEventPayload, RefetchSpecEventData, RequestHighlightNodeEventPayload, SetCursorTypeEventPayload, TARGET_NODE, UpdateStyleEventPayload, ValidatePropEventPayload, handleActiveNodePayload, handleActiveSlotNode, handleFocusedNodePayload } from '@contentstack/studio-message-types/latest';
|
|
14
|
+
export { ActiveBreakpointEventPayload, BaseHighlightEventPayload, ChangeActiveStyleGroupPayload, ComputedStyleSection, DraggerPosition, HighlightActiveNodeEventPayload, HighlightAncestorsEventPayload, HighlightFocusedNodeEventPayload, HighlightNodeEventPayload, HighlightSlotNodeEventPayload, HighlightStyleNodeEventPayload, HitboxDetails, MouseMoveEventPayload, MouseUpEventPayload, RefetchSpecEventData, RequestHighlightNodeEventPayload, RevealMissKind, RevealNodePayload, RevealResultPayload, SetCursorTypeEventPayload, TARGET_NODE, UpdateStyleEventPayload, ValidatePropEventPayload, handleActiveNodePayload, handleActiveSlotNode, handleFocusedNodePayload } from '@contentstack/studio-message-types/latest';
|
|
15
|
+
import { POST_MESSAGE_EVENTS } from '@contentstack/studio-messenger/constants';
|
|
14
16
|
import { EventEmitter } from 'eventemitter3';
|
|
15
17
|
import { IJsonToHtmlOptions } from '@contentstack/json-rte-serializer';
|
|
16
18
|
|
|
@@ -29,8 +31,28 @@ declare const userConfigSchema: z.ZodObject<{
|
|
|
29
31
|
* Visual type to be used for storing the UI
|
|
30
32
|
*/
|
|
31
33
|
contentTypeUid: z.ZodOptional<z.ZodString>;
|
|
34
|
+
/**
|
|
35
|
+
* Accepted as given. Whether a stack is usable is settled by the preflight,
|
|
36
|
+
* not here: a missing or malformed stack is recorded at setup and raised at
|
|
37
|
+
* the first call that needs it, so validating it here would throw at setup
|
|
38
|
+
* for a page that may never fetch a composition.
|
|
39
|
+
*
|
|
40
|
+
* The check this replaces applied `in` to the value, which throws a
|
|
41
|
+
* `TypeError` rather than failing validation when nothing was passed.
|
|
42
|
+
*/
|
|
32
43
|
stackSdk: z.ZodType<any, z.ZodTypeDef, any>;
|
|
33
44
|
locale: z.ZodOptional<z.ZodString>;
|
|
45
|
+
/**
|
|
46
|
+
* Turns on reporting for the failures that do not stop the page — a binding
|
|
47
|
+
* that reads a field which is not there, a query that matched nothing, a
|
|
48
|
+
* reference that came back as a stub.
|
|
49
|
+
*
|
|
50
|
+
* Off by default, and that default is deliberate: those findings are reported
|
|
51
|
+
* in development already, and a customer's production console belongs to
|
|
52
|
+
* them. Switching this on is how a developer diagnoses a deployed site, which
|
|
53
|
+
* has no Studio chrome on it and no other way to say what went wrong.
|
|
54
|
+
*/
|
|
55
|
+
debug: z.ZodOptional<z.ZodBoolean>;
|
|
34
56
|
cslp: z.ZodOptional<z.ZodObject<{
|
|
35
57
|
appendTags: z.ZodOptional<z.ZodBoolean>;
|
|
36
58
|
}, "strip", z.ZodTypeAny, {
|
|
@@ -48,6 +70,30 @@ declare const userConfigSchema: z.ZodObject<{
|
|
|
48
70
|
enable?: boolean | undefined;
|
|
49
71
|
position?: "top" | "top-left" | "top-right" | "top-center" | "bottom" | "bottom-left" | "bottom-right" | "bottom-center" | undefined;
|
|
50
72
|
}>>;
|
|
73
|
+
/**
|
|
74
|
+
* Whether this SDK works out `include[]` paths of its own, on top of the set
|
|
75
|
+
* the composition already carries in `data_sources[*].resolvedReferences`.
|
|
76
|
+
*
|
|
77
|
+
* Studio recomputes that set on every save and, having the content type
|
|
78
|
+
* schemas, keeps only paths that end at a reference (ADR 0018). This SDK has
|
|
79
|
+
* no schema, so what it derives cannot be filtered: measured on one page it
|
|
80
|
+
* added 23 paths of which 22 addressed nothing. The Delivery API refuses a
|
|
81
|
+
* request carrying more than 100 include[] paths, so those are not free.
|
|
82
|
+
*
|
|
83
|
+
* Leave it unset and the SDK decides per composition, from the
|
|
84
|
+
* `schema_version` the entry was saved with: derive for anything older than
|
|
85
|
+
* the point the persisted set became authoritative, skip it for anything at or
|
|
86
|
+
* beyond. That matters because a composition saved before the save-time derive
|
|
87
|
+
* existed holds only the author's ticks, and switching derivation off there
|
|
88
|
+
* would leave every bound-but-un-ticked reference unfetched.
|
|
89
|
+
*
|
|
90
|
+
* Set it explicitly to override that judgement in either direction.
|
|
91
|
+
*
|
|
92
|
+
* What the SDK does regardless is COMPOSE: a section's paths are stored
|
|
93
|
+
* relative to its own scope and only the host knows where the section sits, so
|
|
94
|
+
* prefixing them is the one job that cannot move.
|
|
95
|
+
*/
|
|
96
|
+
deriveIncludePaths: z.ZodOptional<z.ZodBoolean>;
|
|
51
97
|
fetchComposition: z.ZodOptional<z.ZodType<CompositionFetcher, z.ZodTypeDef, CompositionFetcher>>;
|
|
52
98
|
fetchTemplateEntry: z.ZodOptional<z.ZodType<TemplateEntryFetcher, z.ZodTypeDef, TemplateEntryFetcher>>;
|
|
53
99
|
/**
|
|
@@ -62,6 +108,7 @@ declare const userConfigSchema: z.ZodObject<{
|
|
|
62
108
|
locale?: string | undefined;
|
|
63
109
|
contentTypeUid?: string | undefined;
|
|
64
110
|
stackSdk?: any;
|
|
111
|
+
debug?: boolean | undefined;
|
|
65
112
|
cslp?: {
|
|
66
113
|
appendTags?: boolean | undefined;
|
|
67
114
|
} | undefined;
|
|
@@ -69,6 +116,7 @@ declare const userConfigSchema: z.ZodObject<{
|
|
|
69
116
|
enable?: boolean | undefined;
|
|
70
117
|
position?: "top" | "top-left" | "top-right" | "top-center" | "bottom" | "bottom-left" | "bottom-right" | "bottom-center" | undefined;
|
|
71
118
|
} | undefined;
|
|
119
|
+
deriveIncludePaths?: boolean | undefined;
|
|
72
120
|
fetchComposition?: CompositionFetcher | undefined;
|
|
73
121
|
fetchTemplateEntry?: TemplateEntryFetcher | undefined;
|
|
74
122
|
state?: StudioStateConfig | undefined;
|
|
@@ -76,6 +124,7 @@ declare const userConfigSchema: z.ZodObject<{
|
|
|
76
124
|
locale?: string | undefined;
|
|
77
125
|
contentTypeUid?: string | undefined;
|
|
78
126
|
stackSdk?: any;
|
|
127
|
+
debug?: boolean | undefined;
|
|
79
128
|
cslp?: {
|
|
80
129
|
appendTags?: boolean | undefined;
|
|
81
130
|
} | undefined;
|
|
@@ -83,6 +132,7 @@ declare const userConfigSchema: z.ZodObject<{
|
|
|
83
132
|
enable?: boolean | undefined;
|
|
84
133
|
position?: "top" | "top-left" | "top-right" | "top-center" | "bottom" | "bottom-left" | "bottom-right" | "bottom-center" | undefined;
|
|
85
134
|
} | undefined;
|
|
135
|
+
deriveIncludePaths?: boolean | undefined;
|
|
86
136
|
fetchComposition?: CompositionFetcher | undefined;
|
|
87
137
|
fetchTemplateEntry?: TemplateEntryFetcher | undefined;
|
|
88
138
|
state?: StudioStateConfig | undefined;
|
|
@@ -115,10 +165,27 @@ declare class StackSDK {
|
|
|
115
165
|
private isJsQuery;
|
|
116
166
|
where(query: ReturnType<StackSDK["ctQuery"]>, field: string, value: any): any;
|
|
117
167
|
get apiKey(): string;
|
|
168
|
+
get deliveryToken(): string | undefined;
|
|
169
|
+
get environment(): string | undefined;
|
|
170
|
+
/**
|
|
171
|
+
* The host the stack will actually call. Always populated on both SDKs — the
|
|
172
|
+
* TS factory overwrites `config.host` with the region's resolved default, and
|
|
173
|
+
* the JS SDK's own defaults carry one. There is deliberately no
|
|
174
|
+
* `hostWasExplicit` companion: by the time a constructed stack reaches us the
|
|
175
|
+
* customer's original value is gone, and recovering it would mean comparing
|
|
176
|
+
* against a table of Contentstack hostnames, which breaks on dev and staging
|
|
177
|
+
* stacks and on custom CDNs.
|
|
178
|
+
*/
|
|
179
|
+
get host(): string | undefined;
|
|
118
180
|
get livePreviewConfig(): {
|
|
119
181
|
host?: string;
|
|
120
182
|
preview_token?: string;
|
|
121
183
|
enable?: boolean;
|
|
184
|
+
/**
|
|
185
|
+
* The hash from the address. The runtime object carries it under this
|
|
186
|
+
* name and the transport routes on it; it was previously undeclared.
|
|
187
|
+
*/
|
|
188
|
+
live_preview?: string;
|
|
122
189
|
} | undefined;
|
|
123
190
|
get locale(): string | undefined;
|
|
124
191
|
/**
|
|
@@ -133,9 +200,17 @@ declare class StackSDK {
|
|
|
133
200
|
applyTaxonomyFilters(query: any, taxonomyConstraints: Record<string, string>): any;
|
|
134
201
|
}
|
|
135
202
|
|
|
136
|
-
interface Config extends DeepRequired<Omit<UserConfig, "stackSdk" | "locale" | "fetchComposition" | "fetchTemplateEntry" | "state">> {
|
|
137
|
-
|
|
203
|
+
interface Config extends DeepRequired<Omit<UserConfig, "stackSdk" | "locale" | "fetchComposition" | "fetchTemplateEntry" | "state" | "deriveIncludePaths">> {
|
|
204
|
+
/** Absent when nothing usable was supplied; the guards test for it. */
|
|
205
|
+
stackSdk?: StackSDK;
|
|
138
206
|
locale?: string;
|
|
207
|
+
/**
|
|
208
|
+
* Whether the caller passed `contentTypeUid` themselves. `contentTypeUid` is
|
|
209
|
+
* always populated, so the value alone cannot tell a chosen uid from the
|
|
210
|
+
* default — and a developer who set nothing needs a different leading cause
|
|
211
|
+
* from one who set the wrong thing.
|
|
212
|
+
*/
|
|
213
|
+
contentTypeUidWasSupplied: boolean;
|
|
139
214
|
/**
|
|
140
215
|
* Variant alias the SDK should use for all data fetches. Not part of the
|
|
141
216
|
* public `UserConfig` — set by Studio (when running inside a Studio iframe)
|
|
@@ -145,6 +220,12 @@ interface Config extends DeepRequired<Omit<UserConfig, "stackSdk" | "locale" | "
|
|
|
145
220
|
variantAlias?: string;
|
|
146
221
|
fetchComposition?: CompositionFetcher;
|
|
147
222
|
fetchTemplateEntry?: TemplateEntryFetcher;
|
|
223
|
+
/**
|
|
224
|
+
* Override for whether the SDK derives include[] paths of its own. Left
|
|
225
|
+
* undefined it is decided per composition from its `schema_version`, which is
|
|
226
|
+
* why it stays out of `DeepRequired` — "unset" is a meaningful third state.
|
|
227
|
+
*/
|
|
228
|
+
deriveIncludePaths?: boolean;
|
|
148
229
|
/**
|
|
149
230
|
* Bring-Your-Own-State config, passed through as-is (kept out of
|
|
150
231
|
* DeepRequired so `subscribe` / `variables` stay optional).
|
|
@@ -154,6 +235,623 @@ interface Config extends DeepRequired<Omit<UserConfig, "stackSdk" | "locale" | "
|
|
|
154
235
|
type LightConfig = Pick<Config, "openInStudioButton" | "contentTypeUid" | "cslp">;
|
|
155
236
|
type UserConfig = z.infer<typeof userConfigSchema>;
|
|
156
237
|
|
|
238
|
+
/**
|
|
239
|
+
* The documented error codes, and the class each one belongs to.
|
|
240
|
+
*
|
|
241
|
+
* A code names one diagnosable case and is the only identifier on an error. It
|
|
242
|
+
* is printed in the log line, quoted in support conversations and sent to
|
|
243
|
+
* Studio, so it is stable across releases once published.
|
|
244
|
+
*
|
|
245
|
+
* The class is looked up from {@link ERROR_CLASS} rather than carried on the
|
|
246
|
+
* error, because a second identifier that nothing branches on is a second thing
|
|
247
|
+
* to keep in step.
|
|
248
|
+
*
|
|
249
|
+
* Codes land here as the cases behind them are built, not up front — a code
|
|
250
|
+
* with no throw site is a promise, not a contract.
|
|
251
|
+
*/
|
|
252
|
+
declare const StudioErrorCode: {
|
|
253
|
+
/** The stack has no content type with the uid Studio queried. */
|
|
254
|
+
readonly CONTENT_TYPE_NOT_FOUND: "CONTENT_TYPE_NOT_FOUND";
|
|
255
|
+
/** No stack on this host answers to the API key the request carried. */
|
|
256
|
+
readonly STACK_NOT_FOUND_ON_HOST: "STACK_NOT_FOUND_ON_HOST";
|
|
257
|
+
/** The stack has no environment by the name the connection uses. */
|
|
258
|
+
readonly ENVIRONMENT_NOT_FOUND: "ENVIRONMENT_NOT_FOUND";
|
|
259
|
+
/** The stack has no language by the code the SDK was configured with. */
|
|
260
|
+
readonly LOCALE_NOT_CONFIGURED: "LOCALE_NOT_CONFIGURED";
|
|
261
|
+
/** The address asked for a language the stack does not have. */
|
|
262
|
+
readonly URL_LOCALE_NOT_FOUND: "URL_LOCALE_NOT_FOUND";
|
|
263
|
+
/**
|
|
264
|
+
* Studio was given no Contentstack stack to query, or given something that is
|
|
265
|
+
* not one. Raised by the first call that needs the stack, never at setup: a
|
|
266
|
+
* site that wires Studio into a layout and renders no composition on this
|
|
267
|
+
* route is legitimate.
|
|
268
|
+
*/
|
|
269
|
+
readonly STACK_SDK_MISSING: "STACK_SDK_MISSING";
|
|
270
|
+
/**
|
|
271
|
+
* A stack arrived, and the api key inside it is empty.
|
|
272
|
+
*
|
|
273
|
+
* Only reachable on a JavaScript-SDK stack — the TypeScript delivery factory
|
|
274
|
+
* refuses to construct one without an api key, in the caller's own code. Its
|
|
275
|
+
* response-driven sibling is `STACK_NOT_FOUND_ON_HOST`, which is what an empty
|
|
276
|
+
* key used to be reported as once the request came back 412.
|
|
277
|
+
*/
|
|
278
|
+
readonly API_KEY_MISSING: "API_KEY_MISSING";
|
|
279
|
+
/**
|
|
280
|
+
* A stack arrived, and the delivery token inside it is empty.
|
|
281
|
+
*
|
|
282
|
+
* JavaScript-SDK stacks only, as above. No response can report this one: the
|
|
283
|
+
* delivery client's retry policy consumes the 401 into an unknown error before
|
|
284
|
+
* anything here sees it, so the preflight is the only place it can be found.
|
|
285
|
+
*/
|
|
286
|
+
readonly DELIVERY_TOKEN_MISSING: "DELIVERY_TOKEN_MISSING";
|
|
287
|
+
/**
|
|
288
|
+
* A stack arrived, and the environment inside it is empty.
|
|
289
|
+
*
|
|
290
|
+
* JavaScript-SDK stacks only, as above. The value reads as optional and is
|
|
291
|
+
* not — Studio queries published content per environment — which is why the
|
|
292
|
+
* message says so rather than only naming the gap.
|
|
293
|
+
*/
|
|
294
|
+
readonly ENVIRONMENT_MISSING: "ENVIRONMENT_MISSING";
|
|
295
|
+
/**
|
|
296
|
+
* The configured Contentstack address cannot be used as written: it does not
|
|
297
|
+
* parse as an address, or it is `http:` on a page the browser serves over
|
|
298
|
+
* `https:` and will block as mixed content.
|
|
299
|
+
*
|
|
300
|
+
* States only that the value cannot work, never what it should have been. We
|
|
301
|
+
* have no way to know the right host, and any test for a Contentstack-shaped
|
|
302
|
+
* hostname breaks on dev and staging stacks and on customers' own CDNs.
|
|
303
|
+
*/
|
|
304
|
+
readonly HOST_UNUSABLE: "HOST_UNUSABLE";
|
|
305
|
+
/**
|
|
306
|
+
* The call carried none of `compositionUid`, `url` or `templateContentTypeUid`,
|
|
307
|
+
* so there was nothing to look for.
|
|
308
|
+
*
|
|
309
|
+
* Never a not-found: the composition may well exist, the request just never
|
|
310
|
+
* asked for one. The fault is in the call rather than the configuration, which
|
|
311
|
+
* `findings.lookedIn` says so a developer does not audit a correct config file.
|
|
312
|
+
*/
|
|
313
|
+
readonly COMPOSITION_IDENTIFIER_MISSING: "COMPOSITION_IDENTIFIER_MISSING";
|
|
314
|
+
/**
|
|
315
|
+
* A composition was requested before `init()` finished, and it had still not
|
|
316
|
+
* finished when the wait ran out.
|
|
317
|
+
*
|
|
318
|
+
* The wait is long on purpose (~30s). A shorter one fires on inits that were
|
|
319
|
+
* going to succeed — a cold serverless start, a slow server render — and
|
|
320
|
+
* reporting a working site as broken is worse than reporting a broken one late.
|
|
321
|
+
*/
|
|
322
|
+
readonly INIT_NOT_COMPLETE: "INIT_NOT_COMPLETE";
|
|
323
|
+
/**
|
|
324
|
+
* The candidate scan hit its safety cap without finding a match, so we stopped
|
|
325
|
+
* looking rather than established that nothing matched.
|
|
326
|
+
*
|
|
327
|
+
* Never a not-found, and the distinction is the whole point: a 404 is acted on
|
|
328
|
+
* by crawlers, caches and link checkers, and a project that has simply grown
|
|
329
|
+
* past the cap would start de-indexing pages that exist. Nothing in the
|
|
330
|
+
* customer's project causes this and nothing there can fix it.
|
|
331
|
+
*/
|
|
332
|
+
readonly SEARCH_INCOMPLETE: "SEARCH_INCOMPLETE";
|
|
333
|
+
/**
|
|
334
|
+
* Every ownership check on a tied address failed, so no candidate could be
|
|
335
|
+
* shown to own it — and none could be shown not to either.
|
|
336
|
+
*
|
|
337
|
+
* A single failed probe is survivable: another candidate may still answer. All
|
|
338
|
+
* of them failing is a delivery outage, and calling that "nothing owns this
|
|
339
|
+
* address" 404s a page that exists and is published.
|
|
340
|
+
*/
|
|
341
|
+
readonly URL_OWNERSHIP_PROBE_FAILED: "URL_OWNERSHIP_PROBE_FAILED";
|
|
342
|
+
/**
|
|
343
|
+
* Something answered, and what came back is not a delivery response — a
|
|
344
|
+
* proxy's error page, a gateway's JSON, a body truncated in transit.
|
|
345
|
+
*
|
|
346
|
+
* Never a not-found, and the damage of getting it wrong is the widest of any
|
|
347
|
+
* case here: the entries list is simply absent, which reads as "no
|
|
348
|
+
* compositions", which would 404 every page on the site at once for as long as
|
|
349
|
+
* whatever is in the way keeps answering.
|
|
350
|
+
*/
|
|
351
|
+
readonly RESPONSE_UNUSABLE: "RESPONSE_UNUSABLE";
|
|
352
|
+
/**
|
|
353
|
+
* A composition or section was found, and its stored layout will not open.
|
|
354
|
+
*
|
|
355
|
+
* Not a missing page: the composition is there and is damaged. And never
|
|
356
|
+
* version skew — a spec written by a newer Studio inflates and parses fine and
|
|
357
|
+
* fails later as an unknown component type, so offering that here sends the
|
|
358
|
+
* reader to upgrade something that was never in the way.
|
|
359
|
+
*/
|
|
360
|
+
readonly SPEC_UNREADABLE: "SPEC_UNREADABLE";
|
|
361
|
+
/**
|
|
362
|
+
* A complete scan over a usable response found no composition set up for the
|
|
363
|
+
* address. The page is genuinely not there.
|
|
364
|
+
*/
|
|
365
|
+
readonly NO_COMPOSITION_FOR_URL: "NO_COMPOSITION_FOR_URL";
|
|
366
|
+
/**
|
|
367
|
+
* Compositions are set up for the address, every one of them was asked for an
|
|
368
|
+
* entry, and none has one.
|
|
369
|
+
*
|
|
370
|
+
* Distinct from nothing being set up, because the fixes are opposite: this
|
|
371
|
+
* reader's routing is right and their content is missing, so sending them to
|
|
372
|
+
* check the URL sends them to audit something already correct.
|
|
373
|
+
*/
|
|
374
|
+
readonly URL_MATCHED_NO_ENTRY: "URL_MATCHED_NO_ENTRY";
|
|
375
|
+
/**
|
|
376
|
+
* A composition uid was asked for, the query answered, and nothing in the
|
|
377
|
+
* project has it.
|
|
378
|
+
*
|
|
379
|
+
* The wording stops at that. Whether the composition exists at all is not
|
|
380
|
+
* knowable from one query — it may be published to another environment,
|
|
381
|
+
* mistyped, or on a different stack — and the sentence this replaces asserted
|
|
382
|
+
* "does not exist or has been deleted" in every one of those cases.
|
|
383
|
+
*/
|
|
384
|
+
readonly COMPOSITION_UID_NOT_FOUND: "COMPOSITION_UID_NOT_FOUND";
|
|
385
|
+
/**
|
|
386
|
+
* A composition names a connected content type, the entry for it was asked
|
|
387
|
+
* for, and there is none.
|
|
388
|
+
*
|
|
389
|
+
* Renamed from an id that said "preview", which it never had anything to do
|
|
390
|
+
* with — it fires identically on published content, and the name sent people
|
|
391
|
+
* to check a preview setup that was not involved.
|
|
392
|
+
*/
|
|
393
|
+
readonly CONNECTED_ENTRY_NOT_FOUND: "CONNECTED_ENTRY_NOT_FOUND";
|
|
394
|
+
/**
|
|
395
|
+
* A component the stored layout uses was never registered, so there is
|
|
396
|
+
* nothing to render it with.
|
|
397
|
+
*
|
|
398
|
+
* Setup rather than content: the composition is fine and the application did
|
|
399
|
+
* not tell the SDK about a component it refers to. Built-in components
|
|
400
|
+
* register on first import of the React package, so the usual cause is that
|
|
401
|
+
* the package root was never imported.
|
|
402
|
+
*/
|
|
403
|
+
readonly COMPONENT_NOT_REGISTERED: "COMPONENT_NOT_REGISTERED";
|
|
404
|
+
/**
|
|
405
|
+
* The request went out and nothing came back — no response, no status.
|
|
406
|
+
*
|
|
407
|
+
* Never a not-found: a page that cannot be reached is not a page that does
|
|
408
|
+
* not exist, and 404ing it would have crawlers and caches de-index a working
|
|
409
|
+
* site over a bad minute.
|
|
410
|
+
*/
|
|
411
|
+
readonly TRANSPORT_FAILED: "TRANSPORT_FAILED";
|
|
412
|
+
/**
|
|
413
|
+
* Something answered, and the answer was not one we can act on — a 5xx, or a
|
|
414
|
+
* status this SDK has no reading for.
|
|
415
|
+
*
|
|
416
|
+
* The terminal case, and the one that matters most: every response no other
|
|
417
|
+
* check recognises ends up here. It used to end up at "composition not
|
|
418
|
+
* found", which is how a wrong api key, a wrong environment and a delivery
|
|
419
|
+
* outage all came to tell a developer their page did not exist.
|
|
420
|
+
*/
|
|
421
|
+
readonly UPSTREAM_ERROR: "UPSTREAM_ERROR";
|
|
422
|
+
/** A content type was asked for, and no composition in the project is connected to it. */
|
|
423
|
+
readonly NO_COMPOSITION_FOR_TEMPLATE_CONTENT_TYPE: "NO_COMPOSITION_FOR_TEMPLATE_CONTENT_TYPE";
|
|
424
|
+
};
|
|
425
|
+
type StudioErrorCodeType = (typeof StudioErrorCode)[keyof typeof StudioErrorCode];
|
|
426
|
+
/**
|
|
427
|
+
* The five classes, each named for an observable fact about the attempt rather
|
|
428
|
+
* than for a situation. A host reads the class to decide an HTTP status: only
|
|
429
|
+
* `NOT_FOUND` is a 404, everything else is a 5xx.
|
|
430
|
+
*/
|
|
431
|
+
declare const StudioErrorClass: {
|
|
432
|
+
/** Something the SDK needed was not available when it was needed. */
|
|
433
|
+
readonly SETUP_INCOMPLETE: "SETUP_INCOMPLETE";
|
|
434
|
+
/** Something supplied is wrong. */
|
|
435
|
+
readonly SETUP_INVALID: "SETUP_INVALID";
|
|
436
|
+
/** Sent, no response. */
|
|
437
|
+
readonly NETWORK_ERROR: "NETWORK_ERROR";
|
|
438
|
+
/** We could not establish an answer. */
|
|
439
|
+
readonly SERVER_ERROR: "SERVER_ERROR";
|
|
440
|
+
/** We established that nothing matched. */
|
|
441
|
+
readonly NOT_FOUND: "NOT_FOUND";
|
|
442
|
+
};
|
|
443
|
+
type StudioErrorClassType = (typeof StudioErrorClass)[keyof typeof StudioErrorClass];
|
|
444
|
+
|
|
445
|
+
/**
|
|
446
|
+
* What each diagnosis established, keyed by the code that established it.
|
|
447
|
+
*
|
|
448
|
+
* Distinct from `context`, and the difference is enforced by the shapes rather
|
|
449
|
+
* than by a convention: `context` says where the request went and is identical on
|
|
450
|
+
* every error, which is what makes the no-token rule checkable in one place.
|
|
451
|
+
* These say what one particular failure found, so they differ per code.
|
|
452
|
+
*
|
|
453
|
+
* The map is closed on purpose. A receiver narrows on the error's `code`, which
|
|
454
|
+
* it already has, so nothing here repeats the code as a tag. And because adding a
|
|
455
|
+
* field means editing this file, a token can never reach a diagnosis by accident
|
|
456
|
+
* at some throw site — which matters, since the whole object is built to be
|
|
457
|
+
* pasted somewhere public.
|
|
458
|
+
*
|
|
459
|
+
* Named `findings` rather than `details` in the code because
|
|
460
|
+
* `ComposableStudioError.details` is the legacy metadata bag and is still public.
|
|
461
|
+
* The two collapse when [the legacy ids are retired].
|
|
462
|
+
*/
|
|
463
|
+
interface StudioErrorFindingsByCode {
|
|
464
|
+
[StudioErrorCode.CONTENT_TYPE_NOT_FOUND]: {
|
|
465
|
+
contentTypeUid: string;
|
|
466
|
+
/** Whether the site named it, which decides how the causes are ordered. */
|
|
467
|
+
contentTypeUidWasSupplied: boolean;
|
|
468
|
+
};
|
|
469
|
+
[StudioErrorCode.STACK_NOT_FOUND_ON_HOST]: WireFacts;
|
|
470
|
+
[StudioErrorCode.ENVIRONMENT_NOT_FOUND]: WireFacts & {
|
|
471
|
+
/** The environment the request carried, when the stack reported one. */
|
|
472
|
+
environment?: string;
|
|
473
|
+
};
|
|
474
|
+
[StudioErrorCode.LOCALE_NOT_CONFIGURED]: WireFacts & {
|
|
475
|
+
locale: string;
|
|
476
|
+
localeSource: "configuration";
|
|
477
|
+
};
|
|
478
|
+
[StudioErrorCode.URL_LOCALE_NOT_FOUND]: WireFacts & {
|
|
479
|
+
locale: string;
|
|
480
|
+
localeSource: "url-pattern";
|
|
481
|
+
/** The address whose pattern supplied the locale. */
|
|
482
|
+
requestedUrl?: string;
|
|
483
|
+
};
|
|
484
|
+
[StudioErrorCode.HOST_UNUSABLE]: {
|
|
485
|
+
/** The value as configured, so the reader can find where it came from. */
|
|
486
|
+
host: string;
|
|
487
|
+
/** What was proved about it. Never a claim about what it should have been. */
|
|
488
|
+
reason: "unparseable" | "blocked-as-mixed-content";
|
|
489
|
+
};
|
|
490
|
+
/** Carries only where we looked: there is no value to report when none was named. */
|
|
491
|
+
[StudioErrorCode.COMPOSITION_IDENTIFIER_MISSING]: {
|
|
492
|
+
lookedIn: LookedIn;
|
|
493
|
+
};
|
|
494
|
+
[StudioErrorCode.INIT_NOT_COMPLETE]: {
|
|
495
|
+
lookedIn: LookedIn;
|
|
496
|
+
/** How long the fetch waited before giving up, in milliseconds. */
|
|
497
|
+
waitedMs: number;
|
|
498
|
+
};
|
|
499
|
+
/**
|
|
500
|
+
* Where the value was looked for, and nothing else. Which value is missing is
|
|
501
|
+
* the code's job, and the value itself does not exist to report — reporting the
|
|
502
|
+
* api key that *was* found belongs to `context`, which carries it on every
|
|
503
|
+
* error alike.
|
|
504
|
+
*/
|
|
505
|
+
[StudioErrorCode.API_KEY_MISSING]: {
|
|
506
|
+
lookedIn: LookedIn;
|
|
507
|
+
};
|
|
508
|
+
/**
|
|
509
|
+
* Where the token was looked for. Deliberately nothing else: this is the one
|
|
510
|
+
* diagnosis whose subject has no field anywhere in the contract, because a
|
|
511
|
+
* delivery token must never reach a block built to be pasted somewhere public.
|
|
512
|
+
*/
|
|
513
|
+
[StudioErrorCode.DELIVERY_TOKEN_MISSING]: {
|
|
514
|
+
lookedIn: LookedIn;
|
|
515
|
+
};
|
|
516
|
+
/** Where the environment was looked for; `context.environment` is empty by definition. */
|
|
517
|
+
[StudioErrorCode.ENVIRONMENT_MISSING]: {
|
|
518
|
+
lookedIn: LookedIn;
|
|
519
|
+
};
|
|
520
|
+
/**
|
|
521
|
+
* What was being read and how, but never the bytes themselves — the diagnosis
|
|
522
|
+
* is built to be pasted somewhere public, and a stored layout is the customer's
|
|
523
|
+
* content.
|
|
524
|
+
*/
|
|
525
|
+
[StudioErrorCode.SPEC_UNREADABLE]: {
|
|
526
|
+
/** The composition or section the layout belongs to, when the caller knows it. */
|
|
527
|
+
subject?: string;
|
|
528
|
+
/** Whether the value claimed to be compressed, which decides where to look first. */
|
|
529
|
+
wasCompressed: boolean;
|
|
530
|
+
/** How much there was to read. A surprising length is itself a clue. */
|
|
531
|
+
byteLength: number;
|
|
532
|
+
};
|
|
533
|
+
/** Which address answered unreadably. There is no body here: it may be anything. */
|
|
534
|
+
[StudioErrorCode.RESPONSE_UNUSABLE]: {
|
|
535
|
+
host?: string;
|
|
536
|
+
};
|
|
537
|
+
/** The address nothing matched, and how much of the project was looked at. */
|
|
538
|
+
[StudioErrorCode.NO_COMPOSITION_FOR_URL]: {
|
|
539
|
+
url: string;
|
|
540
|
+
/** How many compositions were considered. The scan completed, so this is all of them. */
|
|
541
|
+
consideredCount: number;
|
|
542
|
+
};
|
|
543
|
+
/**
|
|
544
|
+
* Which compositions were in the running and what happened to each.
|
|
545
|
+
*
|
|
546
|
+
* The trace is the diagnosis here; the causes only interpret it. It is computed
|
|
547
|
+
* during resolution either way, so carrying it costs nothing — and without it
|
|
548
|
+
* the reader is told several compositions matched without being told which.
|
|
549
|
+
*/
|
|
550
|
+
[StudioErrorCode.URL_MATCHED_NO_ENTRY]: {
|
|
551
|
+
url: string;
|
|
552
|
+
considered: ConsideredComposition[];
|
|
553
|
+
};
|
|
554
|
+
/** The uid asked for, and the content type it was looked for in. */
|
|
555
|
+
[StudioErrorCode.COMPOSITION_UID_NOT_FOUND]: {
|
|
556
|
+
compositionUid: string;
|
|
557
|
+
contentTypeUid: string;
|
|
558
|
+
};
|
|
559
|
+
/** The content type nothing is connected to. */
|
|
560
|
+
[StudioErrorCode.NO_COMPOSITION_FOR_TEMPLATE_CONTENT_TYPE]: {
|
|
561
|
+
templateContentTypeUid: string;
|
|
562
|
+
};
|
|
563
|
+
/**
|
|
564
|
+
* Which address could not be settled, and how many checks were attempted. The
|
|
565
|
+
* count is what separates "one candidate, one failure" from an outage.
|
|
566
|
+
*/
|
|
567
|
+
[StudioErrorCode.URL_OWNERSHIP_PROBE_FAILED]: {
|
|
568
|
+
url: string;
|
|
569
|
+
/** How many tied candidates were checked, every one of which failed. */
|
|
570
|
+
probeCount: number;
|
|
571
|
+
};
|
|
572
|
+
/**
|
|
573
|
+
* How far the search got before giving up, and what it was looking for. The
|
|
574
|
+
* count is what tells a reader this is about the size of their project rather
|
|
575
|
+
* than about the address they asked for.
|
|
576
|
+
*/
|
|
577
|
+
[StudioErrorCode.SEARCH_INCOMPLETE]: {
|
|
578
|
+
/** The address being resolved when the scan ran out of room. */
|
|
579
|
+
url: string;
|
|
580
|
+
/** How many compositions were considered before the cap stopped the scan. */
|
|
581
|
+
consideredCount: number;
|
|
582
|
+
};
|
|
583
|
+
/** The content type whose entry was looked for, and the address it was looked for at. */
|
|
584
|
+
[StudioErrorCode.CONNECTED_ENTRY_NOT_FOUND]: {
|
|
585
|
+
contentTypeUid: string;
|
|
586
|
+
/** Set when the entry was asked for by id rather than found by address. */
|
|
587
|
+
templateEntryUid?: string;
|
|
588
|
+
};
|
|
589
|
+
/** Which component types the layout uses and the registry does not have. */
|
|
590
|
+
[StudioErrorCode.COMPONENT_NOT_REGISTERED]: {
|
|
591
|
+
componentTypes: string[];
|
|
592
|
+
/** Whether these are ours to register or the application's. */
|
|
593
|
+
areBuiltIn: boolean;
|
|
594
|
+
};
|
|
595
|
+
/**
|
|
596
|
+
* Which address was unreachable, and what the transport said. Never a body —
|
|
597
|
+
* there is no body.
|
|
598
|
+
*/
|
|
599
|
+
[StudioErrorCode.TRANSPORT_FAILED]: {
|
|
600
|
+
host?: string;
|
|
601
|
+
detail?: string;
|
|
602
|
+
};
|
|
603
|
+
/** The status and error code, which is everything we established about it. */
|
|
604
|
+
[StudioErrorCode.UPSTREAM_ERROR]: {
|
|
605
|
+
status?: number;
|
|
606
|
+
errorCode?: unknown;
|
|
607
|
+
host?: string;
|
|
608
|
+
};
|
|
609
|
+
/** Where the stack was looked for. A stack that never arrived has nothing else to say. */
|
|
610
|
+
[StudioErrorCode.STACK_SDK_MISSING]: {
|
|
611
|
+
/**
|
|
612
|
+
* Where the value was looked for. The class covers defects outside the
|
|
613
|
+
* configuration object too — a call that named no composition, an import
|
|
614
|
+
* that never ran — so naming the place saves a developer auditing the
|
|
615
|
+
* wrong file.
|
|
616
|
+
*/
|
|
617
|
+
lookedIn: LookedIn;
|
|
618
|
+
};
|
|
619
|
+
}
|
|
620
|
+
/** Where a value the SDK needed was looked for and not found. */
|
|
621
|
+
type LookedIn = "configuration" | "call" | "registry";
|
|
622
|
+
/** The response facts a host reads to decide what to render in the page's place. */
|
|
623
|
+
interface WireFacts {
|
|
624
|
+
status?: number;
|
|
625
|
+
errorCode?: unknown;
|
|
626
|
+
}
|
|
627
|
+
/** The findings for one code. */
|
|
628
|
+
type StudioErrorFindings = StudioErrorFindingsByCode[StudioErrorCodeType];
|
|
629
|
+
/** One candidate in a URL resolution, and what became of it. */
|
|
630
|
+
interface ConsideredComposition {
|
|
631
|
+
composable_uid: string;
|
|
632
|
+
/** The pattern or address it is set up for. */
|
|
633
|
+
url?: string;
|
|
634
|
+
/** Literal characters matched — how the winner is chosen between ties. */
|
|
635
|
+
specificity?: number;
|
|
636
|
+
/** The content type it reads from, when it is a linked composition. */
|
|
637
|
+
connected_content_type?: string;
|
|
638
|
+
/** Whether asking it for an entry found one, found none, or never happened. */
|
|
639
|
+
connectedEntryResult?: string;
|
|
640
|
+
}
|
|
641
|
+
|
|
642
|
+
/**
|
|
643
|
+
* Information about a possible cause of an error and how to fix it
|
|
644
|
+
*/
|
|
645
|
+
interface TroubleshootingInfo {
|
|
646
|
+
/**
|
|
647
|
+
* Description of the possible cause of the error
|
|
648
|
+
*/
|
|
649
|
+
cause: string;
|
|
650
|
+
/**
|
|
651
|
+
* Suggested fix or resolution for this cause
|
|
652
|
+
*/
|
|
653
|
+
fix: string;
|
|
654
|
+
}
|
|
655
|
+
/**
|
|
656
|
+
* Type definition for error details that can be passed to ComposableStudioError
|
|
657
|
+
*/
|
|
658
|
+
interface ComposableStudioErrorDetails {
|
|
659
|
+
/**
|
|
660
|
+
* Array of troubleshooting information with causes and fixes
|
|
661
|
+
*/
|
|
662
|
+
troubleshootingInfo?: TroubleshootingInfo[];
|
|
663
|
+
/**
|
|
664
|
+
* Additional error context and metadata
|
|
665
|
+
*/
|
|
666
|
+
[key: string]: any;
|
|
667
|
+
}
|
|
668
|
+
declare class ComposableStudioError extends Error {
|
|
669
|
+
details?: ComposableStudioErrorDetails;
|
|
670
|
+
/**
|
|
671
|
+
* The case this error is, and the identifier everything new reads: the log
|
|
672
|
+
* line, the docs, a support conversation, and the diagnostic Studio receives.
|
|
673
|
+
*
|
|
674
|
+
* Optional while throw sites move over one at a time. Absent means the site
|
|
675
|
+
* that raised it has not been diagnosed yet, not that the case is unknown.
|
|
676
|
+
* `id` is what those sites still carry, and it goes once they have all moved.
|
|
677
|
+
*/
|
|
678
|
+
code?: StudioErrorCodeType;
|
|
679
|
+
/**
|
|
680
|
+
* What to do, ordered, most likely first. One entry means we proved the
|
|
681
|
+
* cause; more than one means we are ranking and the reader should work down
|
|
682
|
+
* the list. Set together with `code`, and never empty when set.
|
|
683
|
+
*/
|
|
684
|
+
causes?: Causes;
|
|
685
|
+
/** Where the request went and what it was made with. Never a token. */
|
|
686
|
+
context?: StudioErrorContext;
|
|
687
|
+
/**
|
|
688
|
+
* What this particular failure established, typed by `code`. Separate from
|
|
689
|
+
* `details`, which is the legacy metadata bag: these are the facts a surface
|
|
690
|
+
* reads, and the shape is closed so no throw site can add a token to it.
|
|
691
|
+
*/
|
|
692
|
+
findings?: StudioErrorFindings;
|
|
693
|
+
/**
|
|
694
|
+
* Which of the five classes this code belongs to, looked up rather than
|
|
695
|
+
* stored, so it can never disagree with `code`. A surface that does not
|
|
696
|
+
* recognise the code can still act on the class — it is the coarse answer
|
|
697
|
+
* that stays true for every code added after that surface shipped.
|
|
698
|
+
*/
|
|
699
|
+
get errorClass(): StudioErrorClassType | undefined;
|
|
700
|
+
constructor(message: string, details?: ComposableStudioErrorDetails);
|
|
701
|
+
}
|
|
702
|
+
|
|
703
|
+
/** The three author-facing render contexts a host app can find itself in. */
|
|
704
|
+
type StudioMode = "canvas" | "preview" | "visitor";
|
|
705
|
+
/**
|
|
706
|
+
* The query param Studio always appends to canvas / template-preview iframe
|
|
707
|
+
* URLs. Part of the stable contract — changing its value is a breaking
|
|
708
|
+
* change and will be release-noted as such.
|
|
709
|
+
*/
|
|
710
|
+
declare const STUDIO_CANVAS_QUERY_PARAM: "cs-composable-studio";
|
|
711
|
+
/**
|
|
712
|
+
* Class the SDK bootstrap adds to `<html>` when running inside the Studio
|
|
713
|
+
* canvas. Available for CSS-only gating (e.g. `html.cs-studio-canvas
|
|
714
|
+
* #onetrust-banner-sdk { display: none }`).
|
|
715
|
+
*/
|
|
716
|
+
declare const STUDIO_MODE_HTML_CLASS = "cs-studio-canvas";
|
|
717
|
+
declare global {
|
|
718
|
+
interface Window {
|
|
719
|
+
__CS_STUDIO_MODE__?: StudioMode;
|
|
720
|
+
}
|
|
721
|
+
}
|
|
722
|
+
/**
|
|
723
|
+
* Detects the current Studio mode.
|
|
724
|
+
*
|
|
725
|
+
* Browser: the `window.__CS_STUDIO_MODE__` marker wins when present (it
|
|
726
|
+
* survives client-side navigations that strip query params); otherwise the
|
|
727
|
+
* URL's query params decide.
|
|
728
|
+
*
|
|
729
|
+
* Server: pass the request's search params (string or URLSearchParams) to
|
|
730
|
+
* get a real answer; with no arguments it safely reports `"visitor"`.
|
|
731
|
+
*/
|
|
732
|
+
declare function detectStudioMode(searchQuery?: string | URLSearchParams): StudioMode;
|
|
733
|
+
/**
|
|
734
|
+
* True when the host app is rendering inside the Studio canvas (or Visual
|
|
735
|
+
* Builder frame) — the one check to gate cookie banners, chat widgets,
|
|
736
|
+
* analytics, marketing pixels, and feature-flag bootstraps behind.
|
|
737
|
+
*
|
|
738
|
+
* SSR-safe: returns false on the server unless the request's search params
|
|
739
|
+
* are passed explicitly.
|
|
740
|
+
*/
|
|
741
|
+
declare function isStudioCanvas(searchQuery?: string | URLSearchParams): boolean;
|
|
742
|
+
/**
|
|
743
|
+
* True in any Studio-driven context (canvas OR live-preview pane). Use when
|
|
744
|
+
* a third-party should also stay out of preview sessions — e.g. analytics.
|
|
745
|
+
*/
|
|
746
|
+
declare function isStudioEditorMode(searchQuery?: string | URLSearchParams): boolean;
|
|
747
|
+
/**
|
|
748
|
+
* Bootstrap: computes the mode from the current URL, stamps
|
|
749
|
+
* `window.__CS_STUDIO_MODE__`, and (for canvas mode) adds
|
|
750
|
+
* {@link STUDIO_MODE_HTML_CLASS} to `<html>`. Idempotent; no-op on the
|
|
751
|
+
* server. Invoked automatically when `@contentstack/studio-react` loads in
|
|
752
|
+
* the browser — call it manually only if you gate scripts that run before
|
|
753
|
+
* the SDK's module graph is evaluated.
|
|
754
|
+
*/
|
|
755
|
+
declare function markStudioMode(): StudioMode;
|
|
756
|
+
|
|
757
|
+
/** Which Contentstack service answered a request. */
|
|
758
|
+
type ServedBy = "cdn" | "preview" | "unknown";
|
|
759
|
+
|
|
760
|
+
/**
|
|
761
|
+
* The shape every diagnosable failure is raised in, and the one place it is
|
|
762
|
+
* rendered and logged.
|
|
763
|
+
*
|
|
764
|
+
* Each field answers one question and no field answers two: which case this is
|
|
765
|
+
* (`code`), what happened (`message`), what to do (`causes`), where the request
|
|
766
|
+
* went (`context`), and what this particular failure established (`details`).
|
|
767
|
+
*/
|
|
768
|
+
|
|
769
|
+
/** What might be wrong, and what to do about it. */
|
|
770
|
+
interface Cause {
|
|
771
|
+
cause: string;
|
|
772
|
+
fix: string;
|
|
773
|
+
}
|
|
774
|
+
/**
|
|
775
|
+
* At least one cause, enforced by the type rather than by a runtime check.
|
|
776
|
+
*
|
|
777
|
+
* The length of the list carries our confidence: one means we proved it, more
|
|
778
|
+
* than one means the reader should work down the list. Zero would mean we
|
|
779
|
+
* raised an error and had nothing to say about it, which is worse than not
|
|
780
|
+
* classifying it at all.
|
|
781
|
+
*/
|
|
782
|
+
type Causes = readonly [Cause, ...Cause[]];
|
|
783
|
+
/**
|
|
784
|
+
* Where the request went and what it was made with. The same shape on every
|
|
785
|
+
* error, which is what makes the no-secrets rule enforceable in one place:
|
|
786
|
+
* there is no field here for a delivery or preview token, so no throw site can
|
|
787
|
+
* add one by accident. A *missing* token is a finding about one failure and
|
|
788
|
+
* belongs in that error's `details`.
|
|
789
|
+
*
|
|
790
|
+
* One field the catalogue describes is deliberately absent. `hostWasExplicit`
|
|
791
|
+
* is not derivable — both stack kinds overwrite the host with a resolved
|
|
792
|
+
* default during construction, so by the time a stack reaches us an explicit
|
|
793
|
+
* host cannot be told from a defaulted one.
|
|
794
|
+
*/
|
|
795
|
+
interface StudioErrorContext {
|
|
796
|
+
mode: StudioMode;
|
|
797
|
+
apiKey?: string;
|
|
798
|
+
environment?: string;
|
|
799
|
+
locale?: string;
|
|
800
|
+
host?: string;
|
|
801
|
+
/**
|
|
802
|
+
* Absent when there was no stack to read it from. A surface states only what
|
|
803
|
+
* the payload supports, and `false` here would be a claim about a
|
|
804
|
+
* configuration we were never given.
|
|
805
|
+
*/
|
|
806
|
+
livePreviewEnabled?: boolean;
|
|
807
|
+
/**
|
|
808
|
+
* Which service answered. Captured before the request rather than read back
|
|
809
|
+
* afterwards, and `"unknown"` when the application fetched for itself.
|
|
810
|
+
*/
|
|
811
|
+
servedBy: ServedBy;
|
|
812
|
+
sdkVersion: string;
|
|
813
|
+
}
|
|
814
|
+
interface StudioErrorInput<C extends StudioErrorCodeType = StudioErrorCodeType> {
|
|
815
|
+
code: C;
|
|
816
|
+
/** One sentence stating what happened. The causes are appended by the renderer. */
|
|
817
|
+
headline: string;
|
|
818
|
+
causes: Causes;
|
|
819
|
+
context: StudioErrorContext;
|
|
820
|
+
/**
|
|
821
|
+
* What this specific failure established, narrowed to the shape this code
|
|
822
|
+
* declares. Closed by {@link StudioErrorFindingsByCode}, so a token cannot be
|
|
823
|
+
* added to a diagnosis without editing that map.
|
|
824
|
+
*/
|
|
825
|
+
findings: StudioErrorFindingsByCode[C];
|
|
826
|
+
}
|
|
827
|
+
/** Reads the facts a diagnosis prints from the config the fetch actually used. */
|
|
828
|
+
declare function buildStudioErrorContext(config?: Config, servedBy?: ServedBy): StudioErrorContext;
|
|
829
|
+
/**
|
|
830
|
+
* Builds the error and returns it to be thrown.
|
|
831
|
+
*
|
|
832
|
+
* **It does not log.** Whether a diagnosis reaches a console, a reporting
|
|
833
|
+
* service or neither is the application's decision, not ours — it is the only
|
|
834
|
+
* party that knows its environment, its log budget and its privacy rules. An
|
|
835
|
+
* SDK that writes to the console on the app's behalf takes that decision away
|
|
836
|
+
* and duplicates whatever the app already does with the rejection.
|
|
837
|
+
*
|
|
838
|
+
* What we owe the app in exchange is an error worth logging: the message
|
|
839
|
+
* carries the code and every cause, so a plain `console.error(err)` shows the
|
|
840
|
+
* whole diagnosis, and the structured `code`, `causes` and `context` are there
|
|
841
|
+
* for anything that wants to report rather than print.
|
|
842
|
+
*/
|
|
843
|
+
declare function createStudioError<C extends StudioErrorCodeType>(input: StudioErrorInput<C>): ComposableStudioError;
|
|
844
|
+
/**
|
|
845
|
+
* Whether a failure is a property of the setup rather than of one attempt.
|
|
846
|
+
*
|
|
847
|
+
* Fallbacks exist to survive a request that did not work out: another candidate
|
|
848
|
+
* may own the url, a scan may find what a fast path missed. None of that applies
|
|
849
|
+
* here. The same configuration produces the same answer on every path and every
|
|
850
|
+
* retry, so falling back spends work to reach an identical failure — and reports
|
|
851
|
+
* the one diagnosis worth reading as a transient hiccup on the way.
|
|
852
|
+
*/
|
|
853
|
+
declare function isSetupFault(error: unknown): boolean;
|
|
854
|
+
|
|
157
855
|
declare function getDefaultConfig(): Config;
|
|
158
856
|
|
|
159
857
|
declare const isBrowser: () => boolean;
|
|
@@ -176,7 +874,26 @@ declare const isBrowser: () => boolean;
|
|
|
176
874
|
*/
|
|
177
875
|
declare const INCLUDE_DEPTH_COUNT = 3;
|
|
178
876
|
declare const SDK_VERSION: string;
|
|
179
|
-
|
|
877
|
+
/**
|
|
878
|
+
* Version of the composition spec this SDK writes and reads.
|
|
879
|
+
*
|
|
880
|
+
* Studio persists whatever the canvas SDK reports here onto the composition as
|
|
881
|
+
* `schema_version`, so it doubles as a marker of what a saved composition can be
|
|
882
|
+
* trusted to contain.
|
|
883
|
+
*
|
|
884
|
+
* 1.1.0 (COMPLETE_INCLUDES_FROM_SCHEMA_VERSION) — every fetch root's
|
|
885
|
+
* `data_sources[*].resolvedReferences` is recomputed on save and holds exactly
|
|
886
|
+
* the references it needs, including what this SDK used to work out at render
|
|
887
|
+
* (`derivePlacementIncludePaths`), so the SDK derives nothing (ADR 0018). Below
|
|
888
|
+
* that the sets were accumulated by union, and before 2026-07-17 they held only
|
|
889
|
+
* what the author had ticked — which is why the derivation still runs for them.
|
|
890
|
+
*
|
|
891
|
+
* RELEASE ORDER: released only after Studio saves complete sets for every fetch
|
|
892
|
+
* root (studio-ui#1303, which calls `derivePlacementIncludePaths` at save). An SDK
|
|
893
|
+
* reporting 1.1.0 to a Studio that does not yet do that would mark compositions
|
|
894
|
+
* as trustworthy when they are not.
|
|
895
|
+
*/
|
|
896
|
+
declare const SCHEMA_VERSION = "1.1.0";
|
|
180
897
|
declare const COMPOSABLE_DATA_ATTRIBUTES: {
|
|
181
898
|
readonly BUILDER: "data-composable-studio-builder";
|
|
182
899
|
readonly PLACEHOLDER: "data-composable-studio-placeholder";
|
|
@@ -226,6 +943,16 @@ declare const getHitboxDirection: (event: MouseEvent, nodeBoundingBox: DOMRect)
|
|
|
226
943
|
*/
|
|
227
944
|
declare const toggleNodeVisible: (node: Element, visible: boolean) => void;
|
|
228
945
|
declare const getComposableElement: (uid: string) => HTMLElement;
|
|
946
|
+
/**
|
|
947
|
+
* Every element a node rendered, not just the first.
|
|
948
|
+
*
|
|
949
|
+
* One composition node can reach the DOM many times: a Repeater renders its
|
|
950
|
+
* subtree once per item, and each copy carries the same uid, so a node inside
|
|
951
|
+
* a Repeater has one element per iteration. Callers that ask "where is this
|
|
952
|
+
* node on the page" have to reason over all of them — the first in document
|
|
953
|
+
* order is iteration 0, which is routinely the one that rendered nothing.
|
|
954
|
+
*/
|
|
955
|
+
declare const getComposableElements: (uid: string) => HTMLElement[];
|
|
229
956
|
declare const getHitboxDetails: (event: MouseEvent) => HitboxDetails;
|
|
230
957
|
declare const getComputedStyles: (event: MouseEvent) => Record<string, string> | null;
|
|
231
958
|
declare const serializeEvent: (event: MouseEvent) => SerializedEvent;
|
|
@@ -428,6 +1155,12 @@ interface CompositionEntry {
|
|
|
428
1155
|
created_at: string;
|
|
429
1156
|
updated_at: string;
|
|
430
1157
|
url?: string;
|
|
1158
|
+
/**
|
|
1159
|
+
* Spec version the composition was last saved against — the `SCHEMA_VERSION`
|
|
1160
|
+
* the canvas SDK reported to Studio at the time. Absent on anything saved
|
|
1161
|
+
* before Studio began persisting it. Read by `compositionCarriesCompleteIncludes`.
|
|
1162
|
+
*/
|
|
1163
|
+
schema_version?: string;
|
|
431
1164
|
place_composition_as?: CompositionPlacement;
|
|
432
1165
|
linked_schemas?: {
|
|
433
1166
|
content_type_uid: string;
|
|
@@ -471,6 +1204,13 @@ interface StudioSpec {
|
|
|
471
1204
|
urlResolution?: {
|
|
472
1205
|
shortlisted: UrlMatchDiagnostic[];
|
|
473
1206
|
};
|
|
1207
|
+
/**
|
|
1208
|
+
* Where this request went and what it was made with — the same block every
|
|
1209
|
+
* error carries. Present on success too, because a page that rendered the
|
|
1210
|
+
* wrong content is diagnosed by comparing these facts against what Studio
|
|
1211
|
+
* holds, and there is no error to carry them on. Never holds a token.
|
|
1212
|
+
*/
|
|
1213
|
+
requestContext?: StudioErrorContext;
|
|
474
1214
|
}
|
|
475
1215
|
type SearchQueryInput = (Partial<ComposableStudioQueryParams> & {
|
|
476
1216
|
[key: string]: string | string[] | undefined;
|
|
@@ -646,15 +1386,28 @@ type StudioComponentSpecOptions = {
|
|
|
646
1386
|
* is published. Its exact meaning also differs between the fetch and push
|
|
647
1387
|
* paths, which is a second reason not to branch on it.
|
|
648
1388
|
*
|
|
649
|
-
* @deprecated For composition kind read
|
|
650
|
-
* `
|
|
651
|
-
*
|
|
652
|
-
*
|
|
653
|
-
* `COMPOSITION_NOT_FOUND_BY_URL` and `PREVIEW_ENTRY_NOT_FOUND` mean "no page
|
|
654
|
-
* at this URL"; every other id is a render failure and should surface as
|
|
655
|
-
* 5xx, not 404. Slated for removal in a future major.
|
|
1389
|
+
* @deprecated For composition kind read {@link connectedContentTypeUid}. For
|
|
1390
|
+
* the 404 decision use `isCompositionNotFound(error)`, which answers the
|
|
1391
|
+
* question directly and keeps working across two copies of the package in one
|
|
1392
|
+
* dependency tree. Slated for removal in a future major.
|
|
656
1393
|
*/
|
|
657
1394
|
hasTemplate: boolean;
|
|
1395
|
+
/**
|
|
1396
|
+
* The content type this composition reads from, or `null` when it is freeform.
|
|
1397
|
+
*
|
|
1398
|
+
* The question `hasTemplate` was being misread as, spelled honestly. The value
|
|
1399
|
+
* already exists at `spec.compositionEntry.connected_content_type`; surfacing
|
|
1400
|
+
* it here saves every host reaching two levels into the raw CMS entry and
|
|
1401
|
+
* normalising the empty string that means "none".
|
|
1402
|
+
*
|
|
1403
|
+
* **Still not a 404 signal.** A freeform composition is a real page and a
|
|
1404
|
+
* connected one with no entry is a real miss, so kind cannot decide a status
|
|
1405
|
+
* in either direction — that is what `isCompositionNotFound` is for.
|
|
1406
|
+
*
|
|
1407
|
+
* Optional because callers construct this object by hand, and a required field
|
|
1408
|
+
* would break them.
|
|
1409
|
+
*/
|
|
1410
|
+
connectedContentTypeUid?: string | null;
|
|
658
1411
|
/**
|
|
659
1412
|
* The SEO metadata for the composition. This data can be added to the head
|
|
660
1413
|
* of the HTML.
|
|
@@ -709,275 +1462,13 @@ declare const studioSdk: {
|
|
|
709
1462
|
internal: {
|
|
710
1463
|
getConfig: () => Pick<LightConfig, "contentTypeUid" | "cslp" | "openInStudioButton">;
|
|
711
1464
|
};
|
|
712
|
-
};
|
|
713
|
-
};
|
|
714
|
-
|
|
715
|
-
declare const ELEMENT_TO_NODE: WeakMap<HTMLElement, any>;
|
|
716
|
-
declare const NODE_TO_ELEMENT: WeakMap<any, HTMLElement>;
|
|
717
|
-
declare const NODE_TO_PATH_NODE: WeakMap<any, PathNode>;
|
|
718
|
-
declare const NODE_TO_PARENT: WeakMap<any, any>;
|
|
719
|
-
|
|
720
|
-
declare const findPath: (node: Descendant) => Path;
|
|
721
|
-
declare const findPathForElement: (el: HTMLElement) => Path;
|
|
722
|
-
declare const applyOperation: (editor: Node, operations: Operation[]) => Node;
|
|
723
|
-
|
|
724
|
-
declare function isCompositionBeingEdited(compositionUid: string): boolean;
|
|
725
|
-
|
|
726
|
-
declare const queryParam: {
|
|
727
|
-
get(key: ComposableStudioQueryParamsKeys): string | null;
|
|
728
|
-
has(key: ComposableStudioQueryParamsKeys): boolean;
|
|
729
|
-
};
|
|
730
|
-
declare const onlyParmasGenerator: (only: [string, string][]) => Record<string, string[]>;
|
|
731
|
-
|
|
732
|
-
declare const SECTION_COMPOSITIONS_KEY = "section_compositions";
|
|
733
|
-
declare const TEMPLATE_FULL_ENTRY_KEY = "template_full_entry";
|
|
734
|
-
declare const setTemplateEntryInDS: (dataSources: Record<string, any>, entry: unknown) => void;
|
|
735
|
-
declare const setStaticEntryInDS: (dataSources: Record<string, any>, ct_uid: string, _entries: unknown) => void;
|
|
736
|
-
/**
|
|
737
|
-
* Counterpart to setStaticEntryInDS: drop a single resolved additional entry
|
|
738
|
-
* from the contentstack data source bucket. Called when the author removes an
|
|
739
|
-
* entry so the pruned bucket replaces the stale one on the next UPDATE_SPEC_DATA
|
|
740
|
-
* push (which merges at the dataSources level); without it the removed entry's
|
|
741
|
-
* data lingers and keeps rendering.
|
|
742
|
-
*/
|
|
743
|
-
declare const removeStaticEntryFromDS: (dataSources: Record<string, any>, ct_uid: string, uid: string) => void;
|
|
744
|
-
declare const batchFetchEntries: (sdk: StackSDK, entries: ICSEntryReference[]) => Promise<[string, CompositionEntry[]][]>;
|
|
745
|
-
declare const getBindingStringForCS: (binding: BindingType) => string;
|
|
746
|
-
type EntriesResponse<T> = {
|
|
747
|
-
entries: T[];
|
|
748
|
-
} | [T[]];
|
|
749
|
-
declare function entriesFromResponse<T>(response: EntriesResponse<T>): T[];
|
|
750
|
-
|
|
751
|
-
declare const isInsideVisualBuilderFrame: () => boolean;
|
|
752
|
-
|
|
753
|
-
/**
|
|
754
|
-
* Checks if the current context is inside an iframe.
|
|
755
|
-
*
|
|
756
|
-
* @returns {boolean} True if inside an iframe, false otherwise.
|
|
757
|
-
*/
|
|
758
|
-
declare const isInsideIframe: () => boolean;
|
|
759
|
-
|
|
760
|
-
/** The three author-facing render contexts a host app can find itself in. */
|
|
761
|
-
type StudioMode = "canvas" | "preview" | "visitor";
|
|
762
|
-
/**
|
|
763
|
-
* The query param Studio always appends to canvas / template-preview iframe
|
|
764
|
-
* URLs. Part of the stable contract — changing its value is a breaking
|
|
765
|
-
* change and will be release-noted as such.
|
|
766
|
-
*/
|
|
767
|
-
declare const STUDIO_CANVAS_QUERY_PARAM: "cs-composable-studio";
|
|
768
|
-
/**
|
|
769
|
-
* Class the SDK bootstrap adds to `<html>` when running inside the Studio
|
|
770
|
-
* canvas. Available for CSS-only gating (e.g. `html.cs-studio-canvas
|
|
771
|
-
* #onetrust-banner-sdk { display: none }`).
|
|
772
|
-
*/
|
|
773
|
-
declare const STUDIO_MODE_HTML_CLASS = "cs-studio-canvas";
|
|
774
|
-
declare global {
|
|
775
|
-
interface Window {
|
|
776
|
-
__CS_STUDIO_MODE__?: StudioMode;
|
|
777
|
-
}
|
|
778
|
-
}
|
|
779
|
-
/**
|
|
780
|
-
* Detects the current Studio mode.
|
|
781
|
-
*
|
|
782
|
-
* Browser: the `window.__CS_STUDIO_MODE__` marker wins when present (it
|
|
783
|
-
* survives client-side navigations that strip query params); otherwise the
|
|
784
|
-
* URL's query params decide.
|
|
785
|
-
*
|
|
786
|
-
* Server: pass the request's search params (string or URLSearchParams) to
|
|
787
|
-
* get a real answer; with no arguments it safely reports `"visitor"`.
|
|
788
|
-
*/
|
|
789
|
-
declare function detectStudioMode(searchQuery?: string | URLSearchParams): StudioMode;
|
|
790
|
-
/**
|
|
791
|
-
* True when the host app is rendering inside the Studio canvas (or Visual
|
|
792
|
-
* Builder frame) — the one check to gate cookie banners, chat widgets,
|
|
793
|
-
* analytics, marketing pixels, and feature-flag bootstraps behind.
|
|
794
|
-
*
|
|
795
|
-
* SSR-safe: returns false on the server unless the request's search params
|
|
796
|
-
* are passed explicitly.
|
|
797
|
-
*/
|
|
798
|
-
declare function isStudioCanvas(searchQuery?: string | URLSearchParams): boolean;
|
|
799
|
-
/**
|
|
800
|
-
* True in any Studio-driven context (canvas OR live-preview pane). Use when
|
|
801
|
-
* a third-party should also stay out of preview sessions — e.g. analytics.
|
|
802
|
-
*/
|
|
803
|
-
declare function isStudioEditorMode(searchQuery?: string | URLSearchParams): boolean;
|
|
804
|
-
/**
|
|
805
|
-
* Bootstrap: computes the mode from the current URL, stamps
|
|
806
|
-
* `window.__CS_STUDIO_MODE__`, and (for canvas mode) adds
|
|
807
|
-
* {@link STUDIO_MODE_HTML_CLASS} to `<html>`. Idempotent; no-op on the
|
|
808
|
-
* server. Invoked automatically when `@contentstack/studio-react` loads in
|
|
809
|
-
* the browser — call it manually only if you gate scripts that run before
|
|
810
|
-
* the SDK's module graph is evaluated.
|
|
811
|
-
*/
|
|
812
|
-
declare function markStudioMode(): StudioMode;
|
|
813
|
-
|
|
814
|
-
declare const ComposableStudioErrors: {
|
|
815
|
-
readonly COMPOSITION_NOT_FOUND: "COMPOSITION_NOT_FOUND";
|
|
816
|
-
readonly COMPOSITION_NOT_FOUND_BY_URL: "COMPOSITION_NOT_FOUND_BY_URL";
|
|
817
|
-
readonly PREVIEW_ENTRY_NOT_FOUND: "PREVIEW_ENTRY_NOT_FOUND";
|
|
818
|
-
readonly FETCHING_CONNECTED_DATA_FAILED: "FETCHING_CONNECTED_DATA_FAILED";
|
|
819
|
-
readonly RESOLVING_DATA_SOURCES_FAILED: "RESOLVING_DATA_SOURCES_FAILED";
|
|
820
|
-
readonly STACK_SDK_NOT_AVAILABLE: "STACK_SDK_NOT_AVAILABLE";
|
|
821
|
-
readonly INVALID_FETCH_SPEC_OPTIONS: "INVALID_FETCH_SPEC_OPTIONS";
|
|
822
|
-
readonly MISSING_COMPOSITION_IDENTIFIER: "MISSING_COMPOSITION_IDENTIFIER";
|
|
823
|
-
readonly UI_PARSING_ERROR: "UI_PARSING_ERROR";
|
|
824
|
-
readonly SPEC_DATA_INVALID: "SPEC_DATA_INVALID";
|
|
825
|
-
readonly NETWORK_ERROR: "NETWORK_ERROR";
|
|
826
|
-
readonly AUTHENTICATION_ERROR: "AUTHENTICATION_ERROR";
|
|
827
|
-
readonly SERVER_ERROR: "SERVER_ERROR";
|
|
828
|
-
readonly COMPONENT_NOT_FOUND: "COMPONENT_NOT_FOUND";
|
|
829
|
-
};
|
|
830
|
-
/**
|
|
831
|
-
* Information about a possible cause of an error and how to fix it
|
|
832
|
-
*/
|
|
833
|
-
interface TroubleshootingInfo {
|
|
834
|
-
/**
|
|
835
|
-
* Description of the possible cause of the error
|
|
836
|
-
*/
|
|
837
|
-
cause: string;
|
|
838
|
-
/**
|
|
839
|
-
* Suggested fix or resolution for this cause
|
|
840
|
-
*/
|
|
841
|
-
fix: string;
|
|
842
|
-
}
|
|
843
|
-
/**
|
|
844
|
-
* Type definition for error details that can be passed to ComposableStudioError
|
|
845
|
-
*/
|
|
846
|
-
interface ComposableStudioErrorDetails {
|
|
847
|
-
/**
|
|
848
|
-
* Array of troubleshooting information with causes and fixes
|
|
849
|
-
*/
|
|
850
|
-
troubleshootingInfo?: TroubleshootingInfo[];
|
|
851
|
-
/**
|
|
852
|
-
* Additional error context and metadata
|
|
853
|
-
*/
|
|
854
|
-
[key: string]: any;
|
|
855
|
-
}
|
|
856
|
-
declare class ComposableStudioError extends Error {
|
|
857
|
-
id: keyof typeof ComposableStudioErrors;
|
|
858
|
-
details?: ComposableStudioErrorDetails;
|
|
859
|
-
constructor(id: keyof typeof ComposableStudioErrors, message: string, details?: ComposableStudioErrorDetails);
|
|
860
|
-
}
|
|
861
|
-
|
|
862
|
-
declare const evaluateCondition: (condition: Condition, data: any) => boolean;
|
|
863
|
-
/**
|
|
864
|
-
* Answers both questions a ConditionBlock has to ask: does this condition pass,
|
|
865
|
-
* and what data should its children see.
|
|
866
|
-
*
|
|
867
|
-
* When the condition binds through a repeater, the bound value is projected
|
|
868
|
-
* onto the repeater's context path so descendants resolve against the matched
|
|
869
|
-
* branch. Everything off that path is shared by reference — the projection must
|
|
870
|
-
* not deep-copy the spec, which is large.
|
|
871
|
-
*
|
|
872
|
-
* Lives here, with `evaluateCondition`, because all three renderers (runtime,
|
|
873
|
-
* editor and RSC) need the identical answer and previously derived it
|
|
874
|
-
* separately. `shouldRender` is evaluated against the UNPROJECTED data, which
|
|
875
|
-
* is what all three did.
|
|
876
|
-
*/
|
|
877
|
-
declare const resolveConditionScope: <T>(condition: Condition, data: T) => {
|
|
878
|
-
shouldRender: boolean;
|
|
879
|
-
scopedData: T;
|
|
880
|
-
};
|
|
881
|
-
|
|
882
|
-
declare class RendererModeUtil {
|
|
883
|
-
private searchParams;
|
|
884
|
-
private isServerWithoutParams;
|
|
885
|
-
constructor(searchParams?: URLSearchParams);
|
|
886
|
-
/**
|
|
887
|
-
* Checks if the current context is inside a Studio.
|
|
888
|
-
*
|
|
889
|
-
* @returns {boolean} True if inside a Studio, false otherwise.
|
|
890
|
-
*/
|
|
891
|
-
isInsideStudioFrame(): boolean;
|
|
892
|
-
/**
|
|
893
|
-
* Checks if the current context is inside an iframe.
|
|
894
|
-
*
|
|
895
|
-
* @returns {boolean} True if inside an iframe, false otherwise.
|
|
896
|
-
*/
|
|
897
|
-
isInsideIframe(): boolean;
|
|
898
|
-
/**
|
|
899
|
-
* Checks if the current context is inside a Visual Builder frame.
|
|
900
|
-
*
|
|
901
|
-
* Learn more about Visual Builder: {@link https://www.contentstack.com/docs/content-managers/visual-builder}
|
|
902
|
-
*
|
|
903
|
-
* @returns {boolean} True if inside a Visual Builder frame, false otherwise.
|
|
904
|
-
*/
|
|
905
|
-
isInsideVisualBuilderFrame(): boolean;
|
|
906
|
-
/**
|
|
907
|
-
* Checks if the current context is editing a specific composition.
|
|
908
|
-
*
|
|
909
|
-
* It is useful when you have multiple compositions in a single page
|
|
910
|
-
* and you want to know if the current context is editing a specific
|
|
911
|
-
* composition.
|
|
912
|
-
*
|
|
913
|
-
* @param compositionUid - The UID of the composition to check.
|
|
914
|
-
* @returns {boolean} True if editing the specified composition, false otherwise.
|
|
915
|
-
*/
|
|
916
|
-
isEditingCurrentComposition(compositionUid: string): boolean;
|
|
917
|
-
/**
|
|
918
|
-
* Determines the current renderer mode for a given composition UID.
|
|
919
|
-
*
|
|
920
|
-
* - Returns "edit" if the current composition is being edited.
|
|
921
|
-
* - Returns "show_edit_button" if inside the visual builder frame
|
|
922
|
-
* or if the composition is not currently being edited but should show the edit button.
|
|
923
|
-
* - Returns "preview" otherwise.
|
|
924
|
-
*
|
|
925
|
-
* This method is useful when you want to change the functionality of the
|
|
926
|
-
* component based on where it is being rendered.
|
|
927
|
-
*
|
|
928
|
-
* @param compositionUid - The UID of the composition to check.
|
|
929
|
-
* @returns RendererMode - The current mode (EDIT, SHOW_EDIT_BUTTON, or PREVIEW).
|
|
930
|
-
*/
|
|
931
|
-
getMode(compositionUid: string): "preview" | "edit" | "show_edit_button";
|
|
932
|
-
}
|
|
933
|
-
/**
|
|
934
|
-
* Module-level mode util backed by `window.location.search` (the browser URL).
|
|
935
|
-
*
|
|
936
|
-
* SSR CAUTION: this reads `window`, which does not exist on the server, so on the server
|
|
937
|
-
* every method returns its production default (e.g. `isInsideStudioFrame()` -> false) for
|
|
938
|
-
* ALL requests. It is correct ONLY in browser-only code (the editor render, hooks,
|
|
939
|
-
* INIT_STUDIO). In server-reachable fetch code (studio-client's spec-fetch path) do NOT use
|
|
940
|
-
* this: the answer is wrong on the server, and a single shared singleton cannot represent
|
|
941
|
-
* per-request state across concurrent SSR requests anyway. There, use the request-scoped
|
|
942
|
-
* helpers in `sdk.ts` (`isInStudio` / `isEditorFetch` / `readStudioParam`, built on
|
|
943
|
-
* `getRequestSearchParams`), which read the forwarded request query on the server and fall
|
|
944
|
-
* back to `window` on the client. See COMS-1554 for the AsyncLocalStorage proposal that would
|
|
945
|
-
* remove this split and make this util correct everywhere.
|
|
946
|
-
*/
|
|
947
|
-
declare const clientRendererModeUtil: RendererModeUtil;
|
|
948
|
-
declare const serializeComputedStyles: (computedStyle: CSSStyleDeclaration) => Record<string, string>;
|
|
1465
|
+
};
|
|
1466
|
+
};
|
|
949
1467
|
|
|
950
|
-
|
|
951
|
-
|
|
952
|
-
|
|
953
|
-
|
|
954
|
-
* @param spec - The root node of the UI spec
|
|
955
|
-
* @returns Set of component types used in the spec
|
|
956
|
-
*/
|
|
957
|
-
declare function analyzeUsedComponents(spec: Node | null | undefined): Set<string>;
|
|
958
|
-
/**
|
|
959
|
-
* Analyzes multiple UI specs and returns the union of all component types used.
|
|
960
|
-
* Useful for optimizing multi-composition loading.
|
|
961
|
-
*
|
|
962
|
-
* @param specs - Array of UI spec root nodes
|
|
963
|
-
* @returns Set of all unique component types used across all specs
|
|
964
|
-
*/
|
|
965
|
-
declare function analyzeMultipleSpecs(specs: (Node | null | undefined)[]): Set<string>;
|
|
966
|
-
/**
|
|
967
|
-
* Checks if a spec uses a specific component type.
|
|
968
|
-
*
|
|
969
|
-
* @param spec - The UI spec to check
|
|
970
|
-
* @param componentType - The component type to look for
|
|
971
|
-
* @returns true if the component is used in the spec
|
|
972
|
-
*/
|
|
973
|
-
declare function specUsesComponent(spec: Node | null | undefined, componentType: string): boolean;
|
|
974
|
-
/**
|
|
975
|
-
* Gets component usage statistics for a spec.
|
|
976
|
-
*
|
|
977
|
-
* @param spec - The UI spec to analyze
|
|
978
|
-
* @returns Map of component types to their usage count
|
|
979
|
-
*/
|
|
980
|
-
declare function getComponentUsageStats(spec: Node | null | undefined): Map<string, number>;
|
|
1468
|
+
declare const ELEMENT_TO_NODE: WeakMap<HTMLElement, any>;
|
|
1469
|
+
declare const NODE_TO_ELEMENT: WeakMap<any, HTMLElement>;
|
|
1470
|
+
declare const NODE_TO_PATH_NODE: WeakMap<any, PathNode>;
|
|
1471
|
+
declare const NODE_TO_PARENT: WeakMap<any, any>;
|
|
981
1472
|
|
|
982
1473
|
interface UrlPatternVariableInfo {
|
|
983
1474
|
type: string;
|
|
@@ -1077,6 +1568,25 @@ declare function getSeoMetadataPure(ui: Node, specData?: StudioSpecData): SeoMet
|
|
|
1077
1568
|
* section rendered as the root reads `dataSources.template` directly).
|
|
1078
1569
|
*/
|
|
1079
1570
|
declare function buildSectionScopedData(compositionEntry: CompositionEntry, pageUi: Node, sectionEntries: SectionCompositionEntry[], dataSources: StudioSpecData["dataSources"]): ReturnType<typeof buildScopedDataSources>;
|
|
1571
|
+
/**
|
|
1572
|
+
* Every include[] path the SDK would work out on its own for a composition,
|
|
1573
|
+
* grouped by the fetch root whose request it belongs on — `"template"`, a
|
|
1574
|
+
* `<ct>:<uid>` pinned entry, or `query:<uid>` (ADR 0017, ADR 0018):
|
|
1575
|
+
*
|
|
1576
|
+
* - the composition's own reference-condition paths, on `"template"`;
|
|
1577
|
+
* - for every placed section, its reference-condition paths composed onto where
|
|
1578
|
+
* it sits, and each step of that position (`derivedIncludePathsForInstance`).
|
|
1579
|
+
*
|
|
1580
|
+
* Below COMPLETE_INCLUDES_FROM_SCHEMA_VERSION the SDK adds these at render. From
|
|
1581
|
+
* that version on it adds none: Studio calls this at save, keeps what the schema
|
|
1582
|
+
* confirms is a reference, and persists it on the matching data source, so the
|
|
1583
|
+
* composition carries everything its fetch roots need. The render path and the
|
|
1584
|
+
* save path share `derivedIncludePathsForInstance`, so they cannot drift apart.
|
|
1585
|
+
*
|
|
1586
|
+
* Paths are unvalidated — the SDK has no schema. A caller persisting them must
|
|
1587
|
+
* validate them first.
|
|
1588
|
+
*/
|
|
1589
|
+
declare function derivePlacementIncludePaths(compositionEntry: Pick<CompositionEntry, "ui" | "connected_content_type">, sectionEntries: SectionCompositionEntry[]): Record<string, string[]>;
|
|
1080
1590
|
|
|
1081
1591
|
/**
|
|
1082
1592
|
* A single, framework-neutral meta tag. `attr` distinguishes standard
|
|
@@ -1435,142 +1945,6 @@ declare function addContextMenuEventListeners(): {
|
|
|
1435
1945
|
removeEventListeners: () => void;
|
|
1436
1946
|
} | undefined;
|
|
1437
1947
|
|
|
1438
|
-
declare const MAX_SCROLL_SPEED = 100;
|
|
1439
|
-
declare const SCROLL_INTERVAL = 50;
|
|
1440
|
-
declare const EDGE_PADDING = 50;
|
|
1441
|
-
interface MousePosition {
|
|
1442
|
-
clientX: number;
|
|
1443
|
-
clientY: number;
|
|
1444
|
-
}
|
|
1445
|
-
declare class DNDManager {
|
|
1446
|
-
started: boolean;
|
|
1447
|
-
dragging: boolean;
|
|
1448
|
-
scrollContainer: HTMLElement | null;
|
|
1449
|
-
scrollInterval: ReturnType<typeof setInterval> | undefined;
|
|
1450
|
-
startPosition: MousePosition | null;
|
|
1451
|
-
hasMoved: boolean;
|
|
1452
|
-
mouseDown: boolean;
|
|
1453
|
-
constructor();
|
|
1454
|
-
handleMouseDown(_e: MouseEvent): void;
|
|
1455
|
-
handleMouseUp(_e: MouseEvent): void;
|
|
1456
|
-
handleMouseLeave(e: MouseEvent): void;
|
|
1457
|
-
start(e: MouseEvent): void;
|
|
1458
|
-
startParent(): void;
|
|
1459
|
-
end(): void;
|
|
1460
|
-
mouseMove(e: MouseEvent): void;
|
|
1461
|
-
get isStarted(): boolean;
|
|
1462
|
-
get isDragging(): boolean;
|
|
1463
|
-
hasExceededTolerance(start: MousePosition, end: MousePosition): boolean;
|
|
1464
|
-
}
|
|
1465
|
-
declare const dndManager: DNDManager;
|
|
1466
|
-
|
|
1467
|
-
declare const dndEventListener: () => {
|
|
1468
|
-
removeEventListeners: () => void;
|
|
1469
|
-
};
|
|
1470
|
-
|
|
1471
|
-
declare const getScrollableParent: (el: HTMLElement) => HTMLElement;
|
|
1472
|
-
declare const calculateDynamicSpeed: (distance: number, padding: number, maxSpeed: number) => number;
|
|
1473
|
-
|
|
1474
|
-
declare function handleOnScroll(): void;
|
|
1475
|
-
declare function handleResize(): void;
|
|
1476
|
-
declare const isModKey: (e: MouseEvent | KeyboardEvent) => boolean;
|
|
1477
|
-
declare function addHighlightNodeEventListeners(): {
|
|
1478
|
-
removeEventListeners: () => void;
|
|
1479
|
-
} | undefined;
|
|
1480
|
-
|
|
1481
|
-
type OnStyleChangeCallback = (options: {
|
|
1482
|
-
activeNodeUID: string;
|
|
1483
|
-
element: HTMLElement;
|
|
1484
|
-
componentClassName: string;
|
|
1485
|
-
}) => void;
|
|
1486
|
-
declare class HighlightNodeManager {
|
|
1487
|
-
activeNodeUID: string | null;
|
|
1488
|
-
focusedNodeUID: string | null;
|
|
1489
|
-
activeNodePath: Path | null;
|
|
1490
|
-
focusedNodePath: Path | null;
|
|
1491
|
-
hoveredNodeUID: string | null;
|
|
1492
|
-
activeSlotUID: string | null;
|
|
1493
|
-
styleGroup: string | null;
|
|
1494
|
-
onStyleChangeCallbacks: Set<OnStyleChangeCallback>;
|
|
1495
|
-
onActiveNodeChangeCallbacks: Set<(uid: string, path: Path) => void>;
|
|
1496
|
-
visible: boolean;
|
|
1497
|
-
constructor();
|
|
1498
|
-
private setActiveNodeUID;
|
|
1499
|
-
private setFocusedNodeUID;
|
|
1500
|
-
setHoveredNode(uid: string): void;
|
|
1501
|
-
setActiveSlotUID(uid: string | null): void;
|
|
1502
|
-
resetActiveNode(): void;
|
|
1503
|
-
resetFocusedNode(): void;
|
|
1504
|
-
/**
|
|
1505
|
-
* Subscribe to changes in the active node.
|
|
1506
|
-
*
|
|
1507
|
-
* @param callback - Function that will be called whenever the active node changes.
|
|
1508
|
-
* The callback receives the UID of the newly active node as a parameter.
|
|
1509
|
-
* @param options - Configuration options
|
|
1510
|
-
* @param options.syncToExistingValue - When true, the callback will be immediately called
|
|
1511
|
-
* with the current active node's UID. When false, the callback will only be called on future changes.
|
|
1512
|
-
* Defaults to false.
|
|
1513
|
-
*
|
|
1514
|
-
* @example
|
|
1515
|
-
* ```ts
|
|
1516
|
-
* highlightNodeManager.onActiveNodeChange((uid) => {
|
|
1517
|
-
* console.log('Active node changed to:', uid);
|
|
1518
|
-
* }, { syncToExistingValue: true });
|
|
1519
|
-
* ```
|
|
1520
|
-
*/
|
|
1521
|
-
onActiveNodeChange(callback: (uid: string, path: Path) => void, options: {
|
|
1522
|
-
syncToExistingValue: boolean;
|
|
1523
|
-
}): void;
|
|
1524
|
-
/**
|
|
1525
|
-
* Unsubscribe from changes in the active node.
|
|
1526
|
-
*
|
|
1527
|
-
* @param callback - The callback function to unsubscribe.
|
|
1528
|
-
*
|
|
1529
|
-
* @example
|
|
1530
|
-
* ```ts
|
|
1531
|
-
* const onHighlight = (uid: string) => {
|
|
1532
|
-
* console.log('Active node changed to:', uid);
|
|
1533
|
-
* };
|
|
1534
|
-
*
|
|
1535
|
-
* highlightNodeManager.onActiveNodeChange(onHighlight);
|
|
1536
|
-
* highlightNodeManager.unsubscribeFromActiveNodeChange(onHighlight);
|
|
1537
|
-
* ```
|
|
1538
|
-
*/
|
|
1539
|
-
unsubscribeFromActiveNodeChange(callback: (uid: string, path: Path) => void): void;
|
|
1540
|
-
private notifyActiveNodeChange;
|
|
1541
|
-
removeNodeHighligher(): void;
|
|
1542
|
-
hideActiveNode(): void;
|
|
1543
|
-
setStyleGroup: (styleGroup: string | null) => void;
|
|
1544
|
-
subscribeToOnStyleChange: (callback: OnStyleChangeCallback) => void;
|
|
1545
|
-
unsubscribeFromOnStyleChange: (callback: OnStyleChangeCallback) => void;
|
|
1546
|
-
resetStyleGroup(): void;
|
|
1547
|
-
setAndHighlightActiveNode(uid: string): void;
|
|
1548
|
-
setAndHighlightFocusedNode(uid: string): void;
|
|
1549
|
-
setAndHighlightHoveredNode(uid: string): void;
|
|
1550
|
-
setAndHighlightStyleNode(styleGroup: string, uid: string): {
|
|
1551
|
-
styles: undefined;
|
|
1552
|
-
} | {
|
|
1553
|
-
styles: Partial<CSSStyleDeclaration>;
|
|
1554
|
-
};
|
|
1555
|
-
highlightActiveNode(): void;
|
|
1556
|
-
highlightFocusedNode(): void;
|
|
1557
|
-
highlightNodeOnHover(): void;
|
|
1558
|
-
highlightStyleNode(): void;
|
|
1559
|
-
sendStylesToClient(): {
|
|
1560
|
-
styles: undefined;
|
|
1561
|
-
} | {
|
|
1562
|
-
styles: Partial<CSSStyleDeclaration>;
|
|
1563
|
-
};
|
|
1564
|
-
highlightSlotNode(): void;
|
|
1565
|
-
private getStylesObject;
|
|
1566
|
-
private getHighlightStyleNodePayload;
|
|
1567
|
-
getBoundingRectOfDisplayContents(element: HTMLElement): DOMRect | null;
|
|
1568
|
-
private getNodeRect;
|
|
1569
|
-
private getNodePath;
|
|
1570
|
-
getAncestorsElements(currEl: HTMLElement): HTMLElement[];
|
|
1571
|
-
}
|
|
1572
|
-
declare const highlightNodeManager: HighlightNodeManager;
|
|
1573
|
-
|
|
1574
1948
|
/**
|
|
1575
1949
|
* Listens for URL changes inside the iframe (SPA navigations, pushState, replaceState, popstate)
|
|
1576
1950
|
* and sends URL_CHANGE postMessage to the parent so the studio can sync the navbar URL.
|
|
@@ -1580,10 +1954,6 @@ declare function addUrlChangeListeners(): {
|
|
|
1580
1954
|
removeEventListeners: () => void;
|
|
1581
1955
|
} | undefined;
|
|
1582
1956
|
|
|
1583
|
-
declare function addHighlightSpacingEventListeners(): {
|
|
1584
|
-
removeEventListeners: () => void;
|
|
1585
|
-
} | undefined;
|
|
1586
|
-
|
|
1587
1957
|
declare function addBreakpointEventListeners(): {
|
|
1588
1958
|
removeEventListeners: () => void;
|
|
1589
1959
|
} | undefined;
|
|
@@ -1613,6 +1983,220 @@ declare class BreakpointManager {
|
|
|
1613
1983
|
private syncBreakpointsWithStudio;
|
|
1614
1984
|
}
|
|
1615
1985
|
|
|
1986
|
+
declare const findPath: (node: Descendant) => Path;
|
|
1987
|
+
declare const findPathForElement: (el: HTMLElement) => Path;
|
|
1988
|
+
declare const applyOperation: (editor: Node, operations: Operation[]) => Node;
|
|
1989
|
+
|
|
1990
|
+
declare function isCompositionBeingEdited(compositionUid: string): boolean;
|
|
1991
|
+
|
|
1992
|
+
declare const queryParam: {
|
|
1993
|
+
get(key: ComposableStudioQueryParamsKeys): string | null;
|
|
1994
|
+
has(key: ComposableStudioQueryParamsKeys): boolean;
|
|
1995
|
+
};
|
|
1996
|
+
declare const onlyParmasGenerator: (only: [string, string][]) => Record<string, string[]>;
|
|
1997
|
+
|
|
1998
|
+
declare const SECTION_COMPOSITIONS_KEY = "section_compositions";
|
|
1999
|
+
declare const TEMPLATE_FULL_ENTRY_KEY = "template_full_entry";
|
|
2000
|
+
declare const setTemplateEntryInDS: (dataSources: Record<string, any>, entry: unknown) => void;
|
|
2001
|
+
declare const setStaticEntryInDS: (dataSources: Record<string, any>, ct_uid: string, _entries: unknown) => void;
|
|
2002
|
+
/**
|
|
2003
|
+
* Counterpart to setStaticEntryInDS: drop a single resolved additional entry
|
|
2004
|
+
* from the contentstack data source bucket. Called when the author removes an
|
|
2005
|
+
* entry so the pruned bucket replaces the stale one on the next UPDATE_SPEC_DATA
|
|
2006
|
+
* push (which merges at the dataSources level); without it the removed entry's
|
|
2007
|
+
* data lingers and keeps rendering.
|
|
2008
|
+
*/
|
|
2009
|
+
declare const removeStaticEntryFromDS: (dataSources: Record<string, any>, ct_uid: string, uid: string) => void;
|
|
2010
|
+
declare const batchFetchEntries: (sdk: StackSDK, entries: ICSEntryReference[]) => Promise<[string, CompositionEntry[]][]>;
|
|
2011
|
+
declare const getBindingStringForCS: (binding: BindingType) => string;
|
|
2012
|
+
type EntriesResponse<T> = {
|
|
2013
|
+
entries: T[];
|
|
2014
|
+
} | [T[]];
|
|
2015
|
+
declare function entriesFromResponse<T>(response: EntriesResponse<T>): T[];
|
|
2016
|
+
|
|
2017
|
+
declare const isInsideVisualBuilderFrame: () => boolean;
|
|
2018
|
+
|
|
2019
|
+
/**
|
|
2020
|
+
* Checks if the current context is inside an iframe.
|
|
2021
|
+
*
|
|
2022
|
+
* @returns {boolean} True if inside an iframe, false otherwise.
|
|
2023
|
+
*/
|
|
2024
|
+
declare const isInsideIframe: () => boolean;
|
|
2025
|
+
|
|
2026
|
+
/**
|
|
2027
|
+
* How a host tells "there is no such page" from "we could not answer".
|
|
2028
|
+
*
|
|
2029
|
+
* A host rendering a composition answers one question per request: render this,
|
|
2030
|
+
* return 404, or return 5xx. Only one kind of failure is a 404, and getting it
|
|
2031
|
+
* wrong is expensive in one direction — a 404 is acted on permanently by crawlers
|
|
2032
|
+
* and caches, while a 5xx is retried.
|
|
2033
|
+
*/
|
|
2034
|
+
|
|
2035
|
+
/**
|
|
2036
|
+
* Whether this failure means the page is not there.
|
|
2037
|
+
*
|
|
2038
|
+
* **This is the check to write, rather than `instanceof`.** Two copies of the
|
|
2039
|
+
* package in one dependency tree is an ordinary outcome of a transitive install,
|
|
2040
|
+
* and each copy has its own class object — so a prototype check returns false for
|
|
2041
|
+
* an error raised by the other copy. It fails silently and in the worst direction:
|
|
2042
|
+
* a genuinely missing page is reported as a server error, and the host serves a
|
|
2043
|
+
* 500 where it meant to serve a 404.
|
|
2044
|
+
*
|
|
2045
|
+
* A code is a string. It survives the package boundary, a structured-clone, a
|
|
2046
|
+
* serialisation to a log and back, and a second copy of the SDK.
|
|
2047
|
+
*/
|
|
2048
|
+
declare function isCompositionNotFound(error: unknown): boolean;
|
|
2049
|
+
/**
|
|
2050
|
+
* The not-found subclass, for a host that would rather catch by type.
|
|
2051
|
+
*
|
|
2052
|
+
* It ships because catching by type is a reasonable thing to want, and because an
|
|
2053
|
+
* error's class is what a debugger and a stack trace show. It is not the
|
|
2054
|
+
* documented check: see {@link isCompositionNotFound} for why.
|
|
2055
|
+
*
|
|
2056
|
+
* Nothing constructs this directly. The diagnosis factory picks it whenever the
|
|
2057
|
+
* code it is given belongs to the not-found class, which is what keeps the class
|
|
2058
|
+
* and the predicate from ever disagreeing about the same error.
|
|
2059
|
+
*/
|
|
2060
|
+
declare class CompositionNotFoundError extends ComposableStudioError {
|
|
2061
|
+
}
|
|
2062
|
+
|
|
2063
|
+
declare const evaluateCondition: (condition: Condition, data: any) => boolean;
|
|
2064
|
+
/**
|
|
2065
|
+
* Answers both questions a ConditionBlock has to ask: does this condition pass,
|
|
2066
|
+
* and what data should its children see.
|
|
2067
|
+
*
|
|
2068
|
+
* When the condition binds through a repeater, the bound value is projected
|
|
2069
|
+
* onto the repeater's context path so descendants resolve against the matched
|
|
2070
|
+
* branch. Everything off that path is shared by reference — the projection must
|
|
2071
|
+
* not deep-copy the spec, which is large.
|
|
2072
|
+
*
|
|
2073
|
+
* Lives here, with `evaluateCondition`, because all three renderers (runtime,
|
|
2074
|
+
* editor and RSC) need the identical answer and previously derived it
|
|
2075
|
+
* separately. `shouldRender` is evaluated against the UNPROJECTED data, which
|
|
2076
|
+
* is what all three did.
|
|
2077
|
+
*/
|
|
2078
|
+
declare const resolveConditionScope: <T>(condition: Condition, data: T) => {
|
|
2079
|
+
shouldRender: boolean;
|
|
2080
|
+
scopedData: T;
|
|
2081
|
+
};
|
|
2082
|
+
|
|
2083
|
+
declare class RendererModeUtil {
|
|
2084
|
+
private searchParams;
|
|
2085
|
+
private isServerWithoutParams;
|
|
2086
|
+
constructor(searchParams?: URLSearchParams);
|
|
2087
|
+
/**
|
|
2088
|
+
* Checks if the current context is inside a Studio.
|
|
2089
|
+
*
|
|
2090
|
+
* @returns {boolean} True if inside a Studio, false otherwise.
|
|
2091
|
+
*/
|
|
2092
|
+
isInsideStudioFrame(): boolean;
|
|
2093
|
+
/**
|
|
2094
|
+
* Checks if the current context is inside an iframe.
|
|
2095
|
+
*
|
|
2096
|
+
* @returns {boolean} True if inside an iframe, false otherwise.
|
|
2097
|
+
*/
|
|
2098
|
+
isInsideIframe(): boolean;
|
|
2099
|
+
/**
|
|
2100
|
+
* Checks if the current context is inside a Visual Builder frame.
|
|
2101
|
+
*
|
|
2102
|
+
* Learn more about Visual Builder: {@link https://www.contentstack.com/docs/content-managers/visual-builder}
|
|
2103
|
+
*
|
|
2104
|
+
* @returns {boolean} True if inside a Visual Builder frame, false otherwise.
|
|
2105
|
+
*/
|
|
2106
|
+
isInsideVisualBuilderFrame(): boolean;
|
|
2107
|
+
/**
|
|
2108
|
+
* Checks if the current context is editing a specific composition.
|
|
2109
|
+
*
|
|
2110
|
+
* It is useful when you have multiple compositions in a single page
|
|
2111
|
+
* and you want to know if the current context is editing a specific
|
|
2112
|
+
* composition.
|
|
2113
|
+
*
|
|
2114
|
+
* @param compositionUid - The UID of the composition to check.
|
|
2115
|
+
* @returns {boolean} True if editing the specified composition, false otherwise.
|
|
2116
|
+
*/
|
|
2117
|
+
isEditingCurrentComposition(compositionUid: string): boolean;
|
|
2118
|
+
/**
|
|
2119
|
+
* Determines the current renderer mode for a given composition UID.
|
|
2120
|
+
*
|
|
2121
|
+
* - Returns "edit" if the current composition is being edited.
|
|
2122
|
+
* - Returns "show_edit_button" if inside the visual builder frame
|
|
2123
|
+
* or if the composition is not currently being edited but should show the edit button.
|
|
2124
|
+
* - Returns "preview" otherwise.
|
|
2125
|
+
*
|
|
2126
|
+
* This method is useful when you want to change the functionality of the
|
|
2127
|
+
* component based on where it is being rendered.
|
|
2128
|
+
*
|
|
2129
|
+
* @param compositionUid - The UID of the composition to check.
|
|
2130
|
+
* @returns RendererMode - The current mode (EDIT, SHOW_EDIT_BUTTON, or PREVIEW).
|
|
2131
|
+
*/
|
|
2132
|
+
getMode(compositionUid: string): "preview" | "edit" | "show_edit_button";
|
|
2133
|
+
}
|
|
2134
|
+
/**
|
|
2135
|
+
* Module-level mode util backed by `window.location.search` (the browser URL).
|
|
2136
|
+
*
|
|
2137
|
+
* SSR CAUTION: this reads `window`, which does not exist on the server, so on the server
|
|
2138
|
+
* every method returns its production default (e.g. `isInsideStudioFrame()` -> false) for
|
|
2139
|
+
* ALL requests. It is correct ONLY in browser-only code (the editor render, hooks,
|
|
2140
|
+
* INIT_STUDIO). In server-reachable fetch code (studio-client's spec-fetch path) do NOT use
|
|
2141
|
+
* this: the answer is wrong on the server, and a single shared singleton cannot represent
|
|
2142
|
+
* per-request state across concurrent SSR requests anyway. There, use the request-scoped
|
|
2143
|
+
* helpers in `sdk.ts` (`isInStudio` / `isEditorFetch` / `readStudioParam`, built on
|
|
2144
|
+
* `getRequestSearchParams`), which read the forwarded request query on the server and fall
|
|
2145
|
+
* back to `window` on the client. See COMS-1554 for the AsyncLocalStorage proposal that would
|
|
2146
|
+
* remove this split and make this util correct everywhere.
|
|
2147
|
+
*/
|
|
2148
|
+
declare const clientRendererModeUtil: RendererModeUtil;
|
|
2149
|
+
declare const serializeComputedStyles: (computedStyle: CSSStyleDeclaration) => Record<string, string>;
|
|
2150
|
+
|
|
2151
|
+
/**
|
|
2152
|
+
* Analyzes a UI spec (Node tree) and extracts all component types used.
|
|
2153
|
+
* Recursively traverses the spec to find all components.
|
|
2154
|
+
*
|
|
2155
|
+
* @param spec - The root node of the UI spec
|
|
2156
|
+
* @returns Set of component types used in the spec
|
|
2157
|
+
*/
|
|
2158
|
+
declare function analyzeUsedComponents(spec: Node | null | undefined): Set<string>;
|
|
2159
|
+
/**
|
|
2160
|
+
* Analyzes multiple UI specs and returns the union of all component types used.
|
|
2161
|
+
* Useful for optimizing multi-composition loading.
|
|
2162
|
+
*
|
|
2163
|
+
* @param specs - Array of UI spec root nodes
|
|
2164
|
+
* @returns Set of all unique component types used across all specs
|
|
2165
|
+
*/
|
|
2166
|
+
declare function analyzeMultipleSpecs(specs: (Node | null | undefined)[]): Set<string>;
|
|
2167
|
+
/**
|
|
2168
|
+
* Checks if a spec uses a specific component type.
|
|
2169
|
+
*
|
|
2170
|
+
* @param spec - The UI spec to check
|
|
2171
|
+
* @param componentType - The component type to look for
|
|
2172
|
+
* @returns true if the component is used in the spec
|
|
2173
|
+
*/
|
|
2174
|
+
declare function specUsesComponent(spec: Node | null | undefined, componentType: string): boolean;
|
|
2175
|
+
/**
|
|
2176
|
+
* Gets component usage statistics for a spec.
|
|
2177
|
+
*
|
|
2178
|
+
* @param spec - The UI spec to analyze
|
|
2179
|
+
* @returns Map of component types to their usage count
|
|
2180
|
+
*/
|
|
2181
|
+
declare function getComponentUsageStats(spec: Node | null | undefined): Map<string, number>;
|
|
2182
|
+
|
|
2183
|
+
type StudioEvent = (typeof POST_MESSAGE_EVENTS)[keyof typeof POST_MESSAGE_EVENTS];
|
|
2184
|
+
/**
|
|
2185
|
+
* Fire-and-forget send to the Studio parent frame.
|
|
2186
|
+
*
|
|
2187
|
+
* The postMessage bridge (`@contentstack/studio-messenger` →
|
|
2188
|
+
* `@contentstack/advanced-post-message`) is imported on demand rather than at
|
|
2189
|
+
* module scope. Importing it statically put the whole bridge into every bundle
|
|
2190
|
+
* that reached one of these modules — including a published site, where the
|
|
2191
|
+
* event manager is `undefined` outside the Studio iframe and every one of these
|
|
2192
|
+
* calls is already a no-op.
|
|
2193
|
+
*
|
|
2194
|
+
* Callers are all fire-and-forget today, so resolving the bridge a microtask
|
|
2195
|
+
* later is not observable. Anything that needs to *receive* events keeps a
|
|
2196
|
+
* static import: listener registration cannot be deferred safely.
|
|
2197
|
+
*/
|
|
2198
|
+
declare function sendStudioEvent<TResponse = unknown>(event: StudioEvent, payload?: unknown): Promise<TResponse | undefined>;
|
|
2199
|
+
|
|
1616
2200
|
interface GoogleFont {
|
|
1617
2201
|
family: string;
|
|
1618
2202
|
variants: string[];
|
|
@@ -1852,20 +2436,6 @@ declare function getEmbeddedEntryRenderer(): ((args: EmbeddedEntryRenderArgs) =>
|
|
|
1852
2436
|
*/
|
|
1853
2437
|
declare function getEmbeddedAssetRenderer(): ((args: EmbeddedAssetRenderArgs) => string) | null;
|
|
1854
2438
|
|
|
1855
|
-
declare const compositionSaveEventListener: () => {
|
|
1856
|
-
unregister: () => void;
|
|
1857
|
-
} | undefined;
|
|
1858
|
-
|
|
1859
|
-
declare function openHiddenElementNotification(uid: string): void;
|
|
1860
|
-
declare function closeHiddenElementNotification(uid: string): void;
|
|
1861
|
-
declare function hiddenElementNotificationEventEmitter(): {
|
|
1862
|
-
unregister: () => void;
|
|
1863
|
-
} | undefined;
|
|
1864
|
-
|
|
1865
|
-
declare function getNodeScreenshotEvent(): {
|
|
1866
|
-
unregister: () => void;
|
|
1867
|
-
} | undefined;
|
|
1868
|
-
|
|
1869
2439
|
interface QuerySpec {
|
|
1870
2440
|
contentType: string;
|
|
1871
2441
|
sourceType?: "content_type" | "contentstack" | "taxonomy";
|
|
@@ -1955,7 +2525,7 @@ type UrlMetadataQueryMode = "match" | "existence";
|
|
|
1955
2525
|
* stringifies it and passes it to `api.cma.entry.getAll` via the `query` param.
|
|
1956
2526
|
*
|
|
1957
2527
|
* In `existence` mode for `legacy_url` and `content_type_url_pattern` the
|
|
1958
|
-
* object is `{ url: { $nin: ["", null
|
|
2528
|
+
* object is `{ url: { $nin: [""], $ne: null } }` regardless of `extractedVariables`.
|
|
1959
2529
|
*/
|
|
1960
2530
|
declare function buildUrlMetadataQueryObject(context: Pick<TemplateQueryContext, "compositionQuery" | "extractedVariables" | "url_source">, mode?: UrlMetadataQueryMode): Record<string, any>;
|
|
1961
2531
|
/**
|
|
@@ -2026,5 +2596,5 @@ declare function rankUrlMatches(requestUrl: string, lightweightEntries: Lightwei
|
|
|
2026
2596
|
*/
|
|
2027
2597
|
declare function shouldUseUrlMetadataPath(url_metadata?: Partial<CompositionUrlMetadataSerialized>): boolean;
|
|
2028
2598
|
|
|
2029
|
-
export { BreakpointManager, COMPOSABLE_DATA_ATTRIBUTES, COMPOSABLE_STUDIO_EMITTED_EVENTS, COMPOSITION_PLACEMENT_OPTIONS, COMPOSITION_PREVIEW_URL_SOURCES, COMPOSITION_PREVIEW_URL_SOURCES_VALUES, ComposableStudioError,
|
|
2599
|
+
export { BreakpointManager, COMPOSABLE_DATA_ATTRIBUTES, COMPOSABLE_STUDIO_EMITTED_EVENTS, COMPOSITION_PLACEMENT_OPTIONS, COMPOSITION_PREVIEW_URL_SOURCES, COMPOSITION_PREVIEW_URL_SOURCES_VALUES, ComposableStudioError, CompositionNotFoundError, DEFAULT_BREAKPOINTS, DEFAULT_COMPOSITION_PREVIEW_URL_SOURCE, ELEMENT_TO_NODE, ExpressionResolver, GOOGLE_FONT_API, INCLUDE_DEPTH_COUNT, NODE_TO_ELEMENT, NODE_TO_PARENT, NODE_TO_PATH_NODE, QueryExecutor, RendererMode, RendererModeUtil, SCHEMA_VERSION, SDK_VERSION, SECTION_COMPOSITIONS_KEY, STUDIO_CANVAS_QUERY_PARAM, STUDIO_MODE_HTML_CLASS, StudioErrorClass, StudioErrorCode, TEMPLATE_BINDING_TYPE, TEMPLATE_FETCH_ROOT_KEY, TEMPLATE_FULL_ENTRY_KEY, URL_PATTERN_DATE_VARIABLES, URL_PATTERN_METADATA_FIELDS, URL_PATTERN_METADATA_FIELDS_VALUES, URL_PATTERN_VARIABLE_TYPES, addBreakpointEventListeners, addContextMenuEventListeners, addUrlChangeListeners, analyzeMultipleSpecs, analyzeUsedComponents, applyOperation, batchFetchEntries, buildSectionScopedData, buildStudioErrorContext, buildTemplateQuery, buildUrlMetadataQueryObject, clientRendererModeUtil, compileUrlPattern, composableStudioEventEmitter, computePatternSpecificity, createClassNameUid, createEmbeddedEntryConversion, createStudioError, studioSdk as default, defaultAssetRender, derivePlacementIncludePaths, detectStudioMode, entriesFromResponse, evaluateCondition, extractHtmlRteRefs, extractJsonRteRefs, fetchEmbeddedEntries, fetchRootFromBinding, findNearestBuilderNode, findNearestSlotNode, findPath, findPathForElement, flattenPath, getBindingStringForCS, getComponentUsageStats, getComposableElement, getComposableElements, getCompositionMetadata, getComputedStyles, getDefaultConfig, getEmbeddedAssetRenderer, getEmbeddedEntryRenderer, getHitboxDetails, getHitboxDirection, getJSONRTE, getRootBindingPath, getRootScopePath, getSeoMetadataPure, hasSlotDropzone, isBrowser, isCompositionBeingEdited, isCompositionNotFound, isDataRootCleared, isInsideIframe, isInsideVisualBuilderFrame, isPageAbsoluteField, isSetupFault, isStudioCanvas, isStudioEditorMode, isTemplateFetchRoot, isTemplateRootBinding, loadGoogleFont, markStudioMode, matchCompositionUrl, matchUrlPattern, nestPath, onlyParmasGenerator, parseEntryFetchRootKey, parseStringValue, parseUrlMetadata, preProcessStaticValues, queryParam, rankUrlMatches, registerEmbeddedEntryRenderer, registerJSONRTE, registerRTERenderer, removeStaticEntryFromDS, renderMetadataToHtml, resolveByUrlSource, resolveConditionScope, resolveInstanceRootBinding, resolveLegacySelectedField, resolveLegacySelectedFieldWithProvenance, resolveMatchedSchema, sectionDataEqual, sendStudioEvent, serializeComputedStyles, serializeEvent, setStaticEntryInDS, setTemplateEntryInDS, shouldExtractTaxonomies, shouldUseUrlMetadataPath, specUsesComponent, splitFieldPath, studioSdk, synthesizeTemplateRootBinding, templateFetchRoot, toggleNodeVisible, updateStyleOnStyleNodeChange };
|
|
2030
2600
|
export type { ClientEditableNodeInternalAttributes, ClientPreviewNodeInternalAttributes, ComposableStudioErrorDetails, ComposableStudioLightSdk, CompositionEntry, CompositionEntryIncompleteUi, CompositionFetcher, CompositionMetaTag, CompositionMetadata, CompositionPlacement, CompositionPreviewUrlSource, CompositionPreviewUrlSourceValues, CompositionQueryForSSR, CompositionQueryForSSRInput, CompositionQueryOptions, CompositionUrlMetadata, CompositionUrlMetadataSerialized, CompositionUrlQueries, Config, ConnectedEntryResult, DateVariableKey, EmbeddedAssetRenderArgs, EmbeddedEntryConversionOptions, EmbeddedEntryRenderArgs, EmittedEvents, ExtractedUrlPatternVariables, ExtractedUrlVariables, FetchCompositionContext, FetchRoot, FetchTemplateEntryContext, FieldValue, FontVariants, GetCompositionMetadataOptions, GoogleFont, HiddenElementNotificationHandler, LightConfig, LightweightCompositionEntry, LinkedSchemasLookup, MetaProp, ParsedStringResult, PatternMatchResult, QueryExecutionOptions, QueryResult, QuerySpec, QueryState, RTEConfig, RankingResult, ReferenceFieldValue, RenderableCompositionEntry, ResolvedEmbeddedEntry, ResolvedQueryOptions, RuntimeContext, SearchQueryInput, SectionBindingOverride, SectionCompositionEntry, SectionDataBinding, SectionInstanceNode, SelectedFieldProvenance, SeoMetadata, StudioComponentFetchOptions, StudioComponentSpecOptions, StudioMode, StudioSdk, StudioSpec, TemplateEntryFetcher, TemplateQueryContext, TroubleshootingInfo, URLSearchParamsString, UrlMatchDiagnostic, UrlMetadataQueryMode, UrlPatternMetadataField, UrlPatternMetadataFieldValue, UserConfig };
|