@contentstack/studio-client 3.1.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/README.md +21 -0
- 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 +53 -31
- package/dist/composable-studio/build-scoped-data.js.map +1 -1
- package/dist/composable-studio/collect-data-needs.js +22 -4
- package/dist/composable-studio/collect-data-needs.js.map +1 -1
- package/dist/composable-studio/sdk.js +1288 -453
- package/dist/composable-studio/sdk.js.map +1 -1
- package/dist/composable-studio/section-data.js +316 -0
- package/dist/composable-studio/section-data.js.map +1 -0
- 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 +71 -2
- 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 +1334 -467
- package/dist/index.js +14 -14
- 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 +27 -6
- 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/conditionBlock.js +80 -3
- package/dist/utils/conditionBlock.js.map +1 -1
- 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 +141 -0
- package/dist/utils/include-path-rules.js.map +1 -0
- 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/query-url-budget.js +79 -0
- package/dist/utils/query-url-budget.js.map +1 -0
- package/dist/utils/reference-stub.js +75 -0
- package/dist/utils/reference-stub.js.map +1 -0
- package/dist/utils/reference_fetcher.js +59 -4
- 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/spec-analyzer.js +2 -2
- package/dist/utils/spec-analyzer.js.map +1 -1
- 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 -7
- package/LICENSE +0 -21
- 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,9 +874,28 @@ declare const isBrowser: () => boolean;
|
|
|
176
874
|
*/
|
|
177
875
|
declare const INCLUDE_DEPTH_COUNT = 3;
|
|
178
876
|
declare const SDK_VERSION: string;
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
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";
|
|
897
|
+
declare const COMPOSABLE_DATA_ATTRIBUTES: {
|
|
898
|
+
readonly BUILDER: "data-composable-studio-builder";
|
|
182
899
|
readonly PLACEHOLDER: "data-composable-studio-placeholder";
|
|
183
900
|
readonly LEAF: "data-composable-studio-leaf";
|
|
184
901
|
readonly NODE: "data-composable-studio-node";
|
|
@@ -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;
|
|
@@ -614,25 +1354,60 @@ type StudioComponentFetchOptions = {
|
|
|
614
1354
|
*/
|
|
615
1355
|
type StudioComponentSpecOptions = {
|
|
616
1356
|
/**
|
|
617
|
-
*
|
|
618
|
-
*
|
|
1357
|
+
* The resolved composition. `null` only when a caller builds this object by
|
|
1358
|
+
* hand to mean "I hold no spec, fetch it from the parent window" — the
|
|
1359
|
+
* built-in canvas does exactly that, having no credentials to fetch with.
|
|
1360
|
+
* A fetch never returns `null`; it rejects instead.
|
|
619
1361
|
*/
|
|
620
1362
|
spec: StudioSpec | null;
|
|
1363
|
+
/**
|
|
1364
|
+
* Opaque machinery for `<StudioComponent>` — pass it through, do not inspect
|
|
1365
|
+
* it. The renderer reads the composition query, the query options and the
|
|
1366
|
+
* config out of it to re-initialise and re-fetch on the client.
|
|
1367
|
+
*/
|
|
621
1368
|
fetchOptions: StudioComponentFetchOptions;
|
|
622
1369
|
/**
|
|
623
|
-
*
|
|
624
|
-
*
|
|
1370
|
+
* Whether the resolved spec carries a composition entry.
|
|
1371
|
+
*
|
|
1372
|
+
* **Not a 404 signal.** Every "there is no composition here" outcome rejects
|
|
1373
|
+
* rather than returning, so on a resolved fetch this is always `true`, and on
|
|
1374
|
+
* the push path it is `true` whenever Studio supplied a spec. To test for the
|
|
1375
|
+
* no-spec sentinel, check `spec` itself.
|
|
1376
|
+
*
|
|
1377
|
+
* @deprecated Read `spec.compositionEntry` directly, and decide 404 from the
|
|
1378
|
+
* rejected `ComposableStudioError`. Slated for removal in a future major.
|
|
625
1379
|
*/
|
|
626
1380
|
hasSpec: boolean;
|
|
627
1381
|
/**
|
|
628
|
-
*
|
|
629
|
-
* is available.
|
|
630
|
-
* If the template is not available, we can show a 404 page.
|
|
1382
|
+
* Whether the spec carries resolved data for a connected content type.
|
|
631
1383
|
*
|
|
632
|
-
*
|
|
633
|
-
*
|
|
1384
|
+
* **Not a 404 signal.** It is `false` for every **freeform** composition, so
|
|
1385
|
+
* gating a 404 on it returns 404 for every freeform page, however that page
|
|
1386
|
+
* is published. Its exact meaning also differs between the fetch and push
|
|
1387
|
+
* paths, which is a second reason not to branch on it.
|
|
1388
|
+
*
|
|
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.
|
|
634
1393
|
*/
|
|
635
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;
|
|
636
1411
|
/**
|
|
637
1412
|
* The SEO metadata for the composition. This data can be added to the head
|
|
638
1413
|
* of the HTML.
|
|
@@ -695,250 +1470,6 @@ declare const NODE_TO_ELEMENT: WeakMap<any, HTMLElement>;
|
|
|
695
1470
|
declare const NODE_TO_PATH_NODE: WeakMap<any, PathNode>;
|
|
696
1471
|
declare const NODE_TO_PARENT: WeakMap<any, any>;
|
|
697
1472
|
|
|
698
|
-
declare const findPath: (node: Descendant) => Path;
|
|
699
|
-
declare const findPathForElement: (el: HTMLElement) => Path;
|
|
700
|
-
declare const applyOperation: (editor: Node, operations: Operation[]) => Node;
|
|
701
|
-
|
|
702
|
-
declare function isCompositionBeingEdited(compositionUid: string): boolean;
|
|
703
|
-
|
|
704
|
-
declare const queryParam: {
|
|
705
|
-
get(key: ComposableStudioQueryParamsKeys): string | null;
|
|
706
|
-
has(key: ComposableStudioQueryParamsKeys): boolean;
|
|
707
|
-
};
|
|
708
|
-
declare const onlyParmasGenerator: (only: [string, string][]) => Record<string, string[]>;
|
|
709
|
-
|
|
710
|
-
declare const SECTION_COMPOSITIONS_KEY = "section_compositions";
|
|
711
|
-
declare const TEMPLATE_FULL_ENTRY_KEY = "template_full_entry";
|
|
712
|
-
declare const setTemplateEntryInDS: (dataSources: Record<string, any>, entry: unknown) => void;
|
|
713
|
-
declare const setStaticEntryInDS: (dataSources: Record<string, any>, ct_uid: string, _entries: unknown) => void;
|
|
714
|
-
/**
|
|
715
|
-
* Counterpart to setStaticEntryInDS: drop a single resolved additional entry
|
|
716
|
-
* from the contentstack data source bucket. Called when the author removes an
|
|
717
|
-
* entry so the pruned bucket replaces the stale one on the next UPDATE_SPEC_DATA
|
|
718
|
-
* push (which merges at the dataSources level); without it the removed entry's
|
|
719
|
-
* data lingers and keeps rendering.
|
|
720
|
-
*/
|
|
721
|
-
declare const removeStaticEntryFromDS: (dataSources: Record<string, any>, ct_uid: string, uid: string) => void;
|
|
722
|
-
declare const batchFetchEntries: (sdk: StackSDK, entries: ICSEntryReference[]) => Promise<[string, CompositionEntry[]][]>;
|
|
723
|
-
declare const getBindingStringForCS: (binding: BindingType) => string;
|
|
724
|
-
type EntriesResponse<T> = {
|
|
725
|
-
entries: T[];
|
|
726
|
-
} | [T[]];
|
|
727
|
-
declare function entriesFromResponse<T>(response: EntriesResponse<T>): T[];
|
|
728
|
-
|
|
729
|
-
declare const isInsideVisualBuilderFrame: () => boolean;
|
|
730
|
-
|
|
731
|
-
/**
|
|
732
|
-
* Checks if the current context is inside an iframe.
|
|
733
|
-
*
|
|
734
|
-
* @returns {boolean} True if inside an iframe, false otherwise.
|
|
735
|
-
*/
|
|
736
|
-
declare const isInsideIframe: () => boolean;
|
|
737
|
-
|
|
738
|
-
/** The three author-facing render contexts a host app can find itself in. */
|
|
739
|
-
type StudioMode = "canvas" | "preview" | "visitor";
|
|
740
|
-
/**
|
|
741
|
-
* The query param Studio always appends to canvas / template-preview iframe
|
|
742
|
-
* URLs. Part of the stable contract — changing its value is a breaking
|
|
743
|
-
* change and will be release-noted as such.
|
|
744
|
-
*/
|
|
745
|
-
declare const STUDIO_CANVAS_QUERY_PARAM: "cs-composable-studio";
|
|
746
|
-
/**
|
|
747
|
-
* Class the SDK bootstrap adds to `<html>` when running inside the Studio
|
|
748
|
-
* canvas. Available for CSS-only gating (e.g. `html.cs-studio-canvas
|
|
749
|
-
* #onetrust-banner-sdk { display: none }`).
|
|
750
|
-
*/
|
|
751
|
-
declare const STUDIO_MODE_HTML_CLASS = "cs-studio-canvas";
|
|
752
|
-
declare global {
|
|
753
|
-
interface Window {
|
|
754
|
-
__CS_STUDIO_MODE__?: StudioMode;
|
|
755
|
-
}
|
|
756
|
-
}
|
|
757
|
-
/**
|
|
758
|
-
* Detects the current Studio mode.
|
|
759
|
-
*
|
|
760
|
-
* Browser: the `window.__CS_STUDIO_MODE__` marker wins when present (it
|
|
761
|
-
* survives client-side navigations that strip query params); otherwise the
|
|
762
|
-
* URL's query params decide.
|
|
763
|
-
*
|
|
764
|
-
* Server: pass the request's search params (string or URLSearchParams) to
|
|
765
|
-
* get a real answer; with no arguments it safely reports `"visitor"`.
|
|
766
|
-
*/
|
|
767
|
-
declare function detectStudioMode(searchQuery?: string | URLSearchParams): StudioMode;
|
|
768
|
-
/**
|
|
769
|
-
* True when the host app is rendering inside the Studio canvas (or Visual
|
|
770
|
-
* Builder frame) — the one check to gate cookie banners, chat widgets,
|
|
771
|
-
* analytics, marketing pixels, and feature-flag bootstraps behind.
|
|
772
|
-
*
|
|
773
|
-
* SSR-safe: returns false on the server unless the request's search params
|
|
774
|
-
* are passed explicitly.
|
|
775
|
-
*/
|
|
776
|
-
declare function isStudioCanvas(searchQuery?: string | URLSearchParams): boolean;
|
|
777
|
-
/**
|
|
778
|
-
* True in any Studio-driven context (canvas OR live-preview pane). Use when
|
|
779
|
-
* a third-party should also stay out of preview sessions — e.g. analytics.
|
|
780
|
-
*/
|
|
781
|
-
declare function isStudioEditorMode(searchQuery?: string | URLSearchParams): boolean;
|
|
782
|
-
/**
|
|
783
|
-
* Bootstrap: computes the mode from the current URL, stamps
|
|
784
|
-
* `window.__CS_STUDIO_MODE__`, and (for canvas mode) adds
|
|
785
|
-
* {@link STUDIO_MODE_HTML_CLASS} to `<html>`. Idempotent; no-op on the
|
|
786
|
-
* server. Invoked automatically when `@contentstack/studio-react` loads in
|
|
787
|
-
* the browser — call it manually only if you gate scripts that run before
|
|
788
|
-
* the SDK's module graph is evaluated.
|
|
789
|
-
*/
|
|
790
|
-
declare function markStudioMode(): StudioMode;
|
|
791
|
-
|
|
792
|
-
declare const ComposableStudioErrors: {
|
|
793
|
-
readonly COMPOSITION_NOT_FOUND: "COMPOSITION_NOT_FOUND";
|
|
794
|
-
readonly COMPOSITION_NOT_FOUND_BY_URL: "COMPOSITION_NOT_FOUND_BY_URL";
|
|
795
|
-
readonly PREVIEW_ENTRY_NOT_FOUND: "PREVIEW_ENTRY_NOT_FOUND";
|
|
796
|
-
readonly FETCHING_CONNECTED_DATA_FAILED: "FETCHING_CONNECTED_DATA_FAILED";
|
|
797
|
-
readonly RESOLVING_DATA_SOURCES_FAILED: "RESOLVING_DATA_SOURCES_FAILED";
|
|
798
|
-
readonly STACK_SDK_NOT_AVAILABLE: "STACK_SDK_NOT_AVAILABLE";
|
|
799
|
-
readonly INVALID_FETCH_SPEC_OPTIONS: "INVALID_FETCH_SPEC_OPTIONS";
|
|
800
|
-
readonly MISSING_COMPOSITION_IDENTIFIER: "MISSING_COMPOSITION_IDENTIFIER";
|
|
801
|
-
readonly UI_PARSING_ERROR: "UI_PARSING_ERROR";
|
|
802
|
-
readonly SPEC_DATA_INVALID: "SPEC_DATA_INVALID";
|
|
803
|
-
readonly NETWORK_ERROR: "NETWORK_ERROR";
|
|
804
|
-
readonly AUTHENTICATION_ERROR: "AUTHENTICATION_ERROR";
|
|
805
|
-
readonly SERVER_ERROR: "SERVER_ERROR";
|
|
806
|
-
readonly COMPONENT_NOT_FOUND: "COMPONENT_NOT_FOUND";
|
|
807
|
-
};
|
|
808
|
-
/**
|
|
809
|
-
* Information about a possible cause of an error and how to fix it
|
|
810
|
-
*/
|
|
811
|
-
interface TroubleshootingInfo {
|
|
812
|
-
/**
|
|
813
|
-
* Description of the possible cause of the error
|
|
814
|
-
*/
|
|
815
|
-
cause: string;
|
|
816
|
-
/**
|
|
817
|
-
* Suggested fix or resolution for this cause
|
|
818
|
-
*/
|
|
819
|
-
fix: string;
|
|
820
|
-
}
|
|
821
|
-
/**
|
|
822
|
-
* Type definition for error details that can be passed to ComposableStudioError
|
|
823
|
-
*/
|
|
824
|
-
interface ComposableStudioErrorDetails {
|
|
825
|
-
/**
|
|
826
|
-
* Array of troubleshooting information with causes and fixes
|
|
827
|
-
*/
|
|
828
|
-
troubleshootingInfo?: TroubleshootingInfo[];
|
|
829
|
-
/**
|
|
830
|
-
* Additional error context and metadata
|
|
831
|
-
*/
|
|
832
|
-
[key: string]: any;
|
|
833
|
-
}
|
|
834
|
-
declare class ComposableStudioError extends Error {
|
|
835
|
-
id: keyof typeof ComposableStudioErrors;
|
|
836
|
-
details?: ComposableStudioErrorDetails;
|
|
837
|
-
constructor(id: keyof typeof ComposableStudioErrors, message: string, details?: ComposableStudioErrorDetails);
|
|
838
|
-
}
|
|
839
|
-
|
|
840
|
-
declare const evaluateCondition: (condition: Condition, data: any) => boolean;
|
|
841
|
-
|
|
842
|
-
declare class RendererModeUtil {
|
|
843
|
-
private searchParams;
|
|
844
|
-
private isServerWithoutParams;
|
|
845
|
-
constructor(searchParams?: URLSearchParams);
|
|
846
|
-
/**
|
|
847
|
-
* Checks if the current context is inside a Studio.
|
|
848
|
-
*
|
|
849
|
-
* @returns {boolean} True if inside a Studio, false otherwise.
|
|
850
|
-
*/
|
|
851
|
-
isInsideStudioFrame(): boolean;
|
|
852
|
-
/**
|
|
853
|
-
* Checks if the current context is inside an iframe.
|
|
854
|
-
*
|
|
855
|
-
* @returns {boolean} True if inside an iframe, false otherwise.
|
|
856
|
-
*/
|
|
857
|
-
isInsideIframe(): boolean;
|
|
858
|
-
/**
|
|
859
|
-
* Checks if the current context is inside a Visual Builder frame.
|
|
860
|
-
*
|
|
861
|
-
* Learn more about Visual Builder: {@link https://www.contentstack.com/docs/content-managers/visual-builder}
|
|
862
|
-
*
|
|
863
|
-
* @returns {boolean} True if inside a Visual Builder frame, false otherwise.
|
|
864
|
-
*/
|
|
865
|
-
isInsideVisualBuilderFrame(): boolean;
|
|
866
|
-
/**
|
|
867
|
-
* Checks if the current context is editing a specific composition.
|
|
868
|
-
*
|
|
869
|
-
* It is useful when you have multiple compositions in a single page
|
|
870
|
-
* and you want to know if the current context is editing a specific
|
|
871
|
-
* composition.
|
|
872
|
-
*
|
|
873
|
-
* @param compositionUid - The UID of the composition to check.
|
|
874
|
-
* @returns {boolean} True if editing the specified composition, false otherwise.
|
|
875
|
-
*/
|
|
876
|
-
isEditingCurrentComposition(compositionUid: string): boolean;
|
|
877
|
-
/**
|
|
878
|
-
* Determines the current renderer mode for a given composition UID.
|
|
879
|
-
*
|
|
880
|
-
* - Returns "edit" if the current composition is being edited.
|
|
881
|
-
* - Returns "show_edit_button" if inside the visual builder frame
|
|
882
|
-
* or if the composition is not currently being edited but should show the edit button.
|
|
883
|
-
* - Returns "preview" otherwise.
|
|
884
|
-
*
|
|
885
|
-
* This method is useful when you want to change the functionality of the
|
|
886
|
-
* component based on where it is being rendered.
|
|
887
|
-
*
|
|
888
|
-
* @param compositionUid - The UID of the composition to check.
|
|
889
|
-
* @returns RendererMode - The current mode (EDIT, SHOW_EDIT_BUTTON, or PREVIEW).
|
|
890
|
-
*/
|
|
891
|
-
getMode(compositionUid: string): "preview" | "edit" | "show_edit_button";
|
|
892
|
-
}
|
|
893
|
-
/**
|
|
894
|
-
* Module-level mode util backed by `window.location.search` (the browser URL).
|
|
895
|
-
*
|
|
896
|
-
* SSR CAUTION: this reads `window`, which does not exist on the server, so on the server
|
|
897
|
-
* every method returns its production default (e.g. `isInsideStudioFrame()` -> false) for
|
|
898
|
-
* ALL requests. It is correct ONLY in browser-only code (the editor render, hooks,
|
|
899
|
-
* INIT_STUDIO). In server-reachable fetch code (studio-client's spec-fetch path) do NOT use
|
|
900
|
-
* this: the answer is wrong on the server, and a single shared singleton cannot represent
|
|
901
|
-
* per-request state across concurrent SSR requests anyway. There, use the request-scoped
|
|
902
|
-
* helpers in `sdk.ts` (`isInStudio` / `isEditorFetch` / `readStudioParam`, built on
|
|
903
|
-
* `getRequestSearchParams`), which read the forwarded request query on the server and fall
|
|
904
|
-
* back to `window` on the client. See COMS-1554 for the AsyncLocalStorage proposal that would
|
|
905
|
-
* remove this split and make this util correct everywhere.
|
|
906
|
-
*/
|
|
907
|
-
declare const clientRendererModeUtil: RendererModeUtil;
|
|
908
|
-
declare const serializeComputedStyles: (computedStyle: CSSStyleDeclaration) => Record<string, string>;
|
|
909
|
-
|
|
910
|
-
/**
|
|
911
|
-
* Analyzes a UI spec (Node tree) and extracts all component types used.
|
|
912
|
-
* Recursively traverses the spec to find all components.
|
|
913
|
-
*
|
|
914
|
-
* @param spec - The root node of the UI spec
|
|
915
|
-
* @returns Set of component types used in the spec
|
|
916
|
-
*/
|
|
917
|
-
declare function analyzeUsedComponents(spec: Node | null | undefined): Set<string>;
|
|
918
|
-
/**
|
|
919
|
-
* Analyzes multiple UI specs and returns the union of all component types used.
|
|
920
|
-
* Useful for optimizing multi-composition loading.
|
|
921
|
-
*
|
|
922
|
-
* @param specs - Array of UI spec root nodes
|
|
923
|
-
* @returns Set of all unique component types used across all specs
|
|
924
|
-
*/
|
|
925
|
-
declare function analyzeMultipleSpecs(specs: (Node | null | undefined)[]): Set<string>;
|
|
926
|
-
/**
|
|
927
|
-
* Checks if a spec uses a specific component type.
|
|
928
|
-
*
|
|
929
|
-
* @param spec - The UI spec to check
|
|
930
|
-
* @param componentType - The component type to look for
|
|
931
|
-
* @returns true if the component is used in the spec
|
|
932
|
-
*/
|
|
933
|
-
declare function specUsesComponent(spec: Node | null | undefined, componentType: string): boolean;
|
|
934
|
-
/**
|
|
935
|
-
* Gets component usage statistics for a spec.
|
|
936
|
-
*
|
|
937
|
-
* @param spec - The UI spec to analyze
|
|
938
|
-
* @returns Map of component types to their usage count
|
|
939
|
-
*/
|
|
940
|
-
declare function getComponentUsageStats(spec: Node | null | undefined): Map<string, number>;
|
|
941
|
-
|
|
942
1473
|
interface UrlPatternVariableInfo {
|
|
943
1474
|
type: string;
|
|
944
1475
|
name: string;
|
|
@@ -982,6 +1513,18 @@ interface SectionNeeds {
|
|
|
982
1513
|
uidRemapping?: Record<string, string>;
|
|
983
1514
|
cardinality?: "collection" | "single";
|
|
984
1515
|
componentPropsFallback?: Record<string, unknown>;
|
|
1516
|
+
/**
|
|
1517
|
+
* The document this instance's section data lives in (ADR 0017): `"template"`,
|
|
1518
|
+
* a `<ct>:<uid>` pinned-entry key, or `query:<dsUid>`. Absent ⇒ template, so
|
|
1519
|
+
* every pre-existing composition behaves exactly as before.
|
|
1520
|
+
*/
|
|
1521
|
+
fetchRootKey?: string;
|
|
1522
|
+
/**
|
|
1523
|
+
* The path WITHIN that document. For the template root this is the same thing
|
|
1524
|
+
* as `selectedField`; for a pinned-entry root it is the root path with the
|
|
1525
|
+
* `<ct>:<uid>` document segment already dropped.
|
|
1526
|
+
*/
|
|
1527
|
+
fetchRootPrefix?: string[];
|
|
985
1528
|
}
|
|
986
1529
|
type NeedsBySection = Map<string, SectionNeeds>;
|
|
987
1530
|
|
|
@@ -1024,67 +1567,331 @@ declare function getSeoMetadataPure(ui: Node, specData?: StudioSpecData): SeoMet
|
|
|
1024
1567
|
* Returns `{}` when there are no section compositions (e.g. a standalone
|
|
1025
1568
|
* section rendered as the root reads `dataSources.template` directly).
|
|
1026
1569
|
*/
|
|
1027
|
-
declare function buildSectionScopedData(compositionEntry: CompositionEntry, pageUi: Node, sectionEntries: SectionCompositionEntry[], dataSources: StudioSpecData["dataSources"]): ReturnType<typeof buildScopedDataSources>;
|
|
1028
|
-
|
|
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[]>;
|
|
1590
|
+
|
|
1591
|
+
/**
|
|
1592
|
+
* A single, framework-neutral meta tag. `attr` distinguishes standard
|
|
1593
|
+
* `<meta name="...">` tags from Open Graph-style `<meta property="...">`.
|
|
1594
|
+
*/
|
|
1595
|
+
interface CompositionMetaTag {
|
|
1596
|
+
attr: "name" | "property";
|
|
1597
|
+
key: string;
|
|
1598
|
+
content: string;
|
|
1599
|
+
}
|
|
1600
|
+
/**
|
|
1601
|
+
* Framework-neutral SEO metadata derived from a composition's resolved
|
|
1602
|
+
* `specOptions.seo`. Consumers bind this to their host's head mechanism:
|
|
1603
|
+
* Next.js `generateMetadata`, Remix `meta()`, TanStack `head()`, or a raw
|
|
1604
|
+
* HTML template via {@link renderMetadataToHtml}.
|
|
1605
|
+
*/
|
|
1606
|
+
interface CompositionMetadata {
|
|
1607
|
+
title?: string;
|
|
1608
|
+
description?: string;
|
|
1609
|
+
ogImage?: string;
|
|
1610
|
+
/** Absolute canonical URL. Present only when `baseUrl` was provided and the composition has a URL. */
|
|
1611
|
+
canonical?: string;
|
|
1612
|
+
/** Every derived tag (description, og:*, twitter:*, custom metaProps) in render order. */
|
|
1613
|
+
tags: CompositionMetaTag[];
|
|
1614
|
+
}
|
|
1615
|
+
interface GetCompositionMetadataOptions {
|
|
1616
|
+
/**
|
|
1617
|
+
* Site origin used to absolutize the canonical URL and og:url,
|
|
1618
|
+
* e.g. `https://www.example.com`. No trailing slash required.
|
|
1619
|
+
*/
|
|
1620
|
+
baseUrl?: string;
|
|
1621
|
+
}
|
|
1622
|
+
/**
|
|
1623
|
+
* Derives framework-neutral SEO metadata from a fetched composition.
|
|
1624
|
+
*
|
|
1625
|
+
* The heavy lifting (resolving field bindings for title/description/OG image)
|
|
1626
|
+
* already happens inside `fetchCompositionData` — this helper only shapes the
|
|
1627
|
+
* resolved values into standard head-tag structures.
|
|
1628
|
+
*
|
|
1629
|
+
* @example Plain Node
|
|
1630
|
+
* ```ts
|
|
1631
|
+
* const meta = getCompositionMetadata(specOptions, { baseUrl: "https://example.com" });
|
|
1632
|
+
* res.send(`<head><title>${meta.title}</title>${renderMetadataToHtml(meta)}</head>...`);
|
|
1633
|
+
* ```
|
|
1634
|
+
*
|
|
1635
|
+
* @example Next.js App Router
|
|
1636
|
+
* ```ts
|
|
1637
|
+
* export async function generateMetadata() {
|
|
1638
|
+
* const meta = getCompositionMetadata(await getSpecOptions());
|
|
1639
|
+
* return { title: meta.title, description: meta.description };
|
|
1640
|
+
* }
|
|
1641
|
+
* ```
|
|
1642
|
+
*/
|
|
1643
|
+
declare function getCompositionMetadata(specOptions: Pick<StudioComponentSpecOptions, "seo" | "spec">, options?: GetCompositionMetadataOptions): CompositionMetadata;
|
|
1644
|
+
/**
|
|
1645
|
+
* Renders {@link CompositionMetadata} to a raw HTML string (meta + canonical
|
|
1646
|
+
* link tags — the `<title>` element is left to the caller since most hosts
|
|
1647
|
+
* manage it separately). For template-string SSR hosts (Express/Fastify).
|
|
1648
|
+
*/
|
|
1649
|
+
declare function renderMetadataToHtml(metadata: CompositionMetadata): string;
|
|
1650
|
+
|
|
1651
|
+
/**
|
|
1652
|
+
* A placement's **Section data** — the binding that supplies a placed section's
|
|
1653
|
+
* data, i.e. what the section's own `template.*` paths resolve against.
|
|
1654
|
+
*
|
|
1655
|
+
* Persisted on the placed section-composition node as part of
|
|
1656
|
+
* `metadata.sectionBindingOverride`. Being a binding rather than a bare field
|
|
1657
|
+
* path is what lets a section root at a pinned entry, a query result or a
|
|
1658
|
+
* repeater item — none of which a freeform page can express as a path into a
|
|
1659
|
+
* page template entry it does not have. See ADR 0016.
|
|
1660
|
+
*
|
|
1661
|
+
* Three states, all distinguishable and all load-bearing:
|
|
1662
|
+
*
|
|
1663
|
+
* | value | meaning |
|
|
1664
|
+
* |-------------|--------------------------------------------------------|
|
|
1665
|
+
* | `undefined` | inherit the section's declared `selected_field` |
|
|
1666
|
+
* | `null` | deliberately cleared — render no bound data |
|
|
1667
|
+
* | a binding | the author's choice |
|
|
1668
|
+
*
|
|
1669
|
+
* `undefined` cannot be collapsed into `null`: absence has to keep meaning
|
|
1670
|
+
* "follow the section's declaration", so a section author's later change to
|
|
1671
|
+
* `linked_schemas` still propagates to placements that never opted in.
|
|
1672
|
+
*/
|
|
1673
|
+
type SectionDataBinding = BindingType | null | undefined;
|
|
1674
|
+
interface SectionBindingOverride {
|
|
1675
|
+
/**
|
|
1676
|
+
* Legacy per-placement field path. Still READ (it is the migration source for
|
|
1677
|
+
* `rootBinding`), never newly written.
|
|
1678
|
+
*/
|
|
1679
|
+
selectedField?: string;
|
|
1680
|
+
uidRemapping?: Record<string, string>;
|
|
1681
|
+
/** The Section data. See {@link SectionDataBinding} for the three states. */
|
|
1682
|
+
rootBinding?: BindingType | null;
|
|
1683
|
+
/**
|
|
1684
|
+
* Which `linked_schemas` entry the Section data matched.
|
|
1685
|
+
*
|
|
1686
|
+
* On a template the winner is found by `content_type_uid === pageCT`. A
|
|
1687
|
+
* freeform page has no page content type, so without this the cold-load path
|
|
1688
|
+
* falls back to `linked_schemas[0]` and reads `cardinality` off the wrong
|
|
1689
|
+
* schema — a collection section then silently renders as a single element.
|
|
1690
|
+
*/
|
|
1691
|
+
matchedSchemaCt?: string;
|
|
1692
|
+
}
|
|
1693
|
+
/** Binding `type` for a path into the page's template entry. */
|
|
1694
|
+
declare const TEMPLATE_BINDING_TYPE = "template";
|
|
1695
|
+
/**
|
|
1696
|
+
* Split a dotted field path into binding-path segments, dropping the array
|
|
1697
|
+
* indices and modular-block numeric prefixes that are not data keys. Mirrors
|
|
1698
|
+
* `sanitizeFieldPath` in sdk.ts — kept local so this module stays dependency-free
|
|
1699
|
+
* and usable from Studio.
|
|
1700
|
+
*/
|
|
1701
|
+
declare function splitFieldPath(path: string): string[];
|
|
1702
|
+
/**
|
|
1703
|
+
* Nest dotted path segments into the object shape a binding `value.path` uses:
|
|
1704
|
+
* `["a", "b"]` → `{ a: { b: {} } }`. An empty path nests to `{}`, which is what
|
|
1705
|
+
* a scope-root binding carries.
|
|
1706
|
+
*/
|
|
1707
|
+
declare function nestPath(segments: string[]): Record<string, unknown>;
|
|
1708
|
+
/** The inverse of {@link nestPath}: walk the single-key chain back to segments. */
|
|
1709
|
+
declare function flattenPath(path: Record<string, unknown> | undefined | null): string[];
|
|
1710
|
+
/**
|
|
1711
|
+
* Build the template-typed Section data equivalent to a legacy `selectedField`.
|
|
1712
|
+
*
|
|
1713
|
+
* This is the whole migration: every placement saved before the Section data
|
|
1714
|
+
* existed resolves to exactly the binding it behaved as, derived on read. No
|
|
1715
|
+
* stored data changes.
|
|
1716
|
+
*/
|
|
1717
|
+
declare function synthesizeTemplateRootBinding(selectedField: string | undefined): BindingType;
|
|
1718
|
+
/** Whether a resolved Section data means "deliberately cleared". */
|
|
1719
|
+
declare function isDataRootCleared(root: SectionDataBinding): root is null;
|
|
1720
|
+
/**
|
|
1721
|
+
* Whether a Section data points into the page's template entry — the only kind
|
|
1722
|
+
* that extends a page-template prefix. A contentstack / query / repeater-typed
|
|
1723
|
+
* root names its own document instead (see ADR 0017's fetch root).
|
|
1724
|
+
*/
|
|
1725
|
+
declare function isTemplateRootBinding(root: SectionDataBinding): boolean;
|
|
1726
|
+
/**
|
|
1727
|
+
* The path a Section data addresses **within the scope its placement already
|
|
1728
|
+
* inherits** — the page template entry for a `template` root, the live
|
|
1729
|
+
* iteration item for a `repeater` one (ADR 0006).
|
|
1730
|
+
*
|
|
1731
|
+
* This is what the renderer means by `selectedField`: the provider scopes the
|
|
1732
|
+
* enclosing repeater item (or the template entry) by it. A root naming ANOTHER
|
|
1733
|
+
* document carries its path in the fetch root's `prefix` instead, so it has no
|
|
1734
|
+
* scope path — the two are never both in play.
|
|
1735
|
+
*
|
|
1736
|
+
* The `template`-only version of this test is what left a repeater-relative
|
|
1737
|
+
* root unusable: its path (`hero_card` inside the item) was dropped on the way
|
|
1738
|
+
* to the renderer, every iteration scoped to the whole item, and the section
|
|
1739
|
+
* rendered component defaults.
|
|
1740
|
+
*/
|
|
1741
|
+
declare function getRootScopePath(root: SectionDataBinding): string[];
|
|
1742
|
+
/**
|
|
1743
|
+
* The dotted path a Section data addresses *within* its document.
|
|
1744
|
+
*
|
|
1745
|
+
* For a template root this is the old `selectedField`. For a contentstack root
|
|
1746
|
+
* the first segment is the `<ct>:<uid>` pool key, which names the **document**
|
|
1747
|
+
* rather than a field inside it — callers that need the in-document path must
|
|
1748
|
+
* drop it (`dropDocumentSegment`).
|
|
1749
|
+
*/
|
|
1750
|
+
declare function getRootBindingPath(root: SectionDataBinding): string[];
|
|
1751
|
+
interface SectionInstanceNode {
|
|
1752
|
+
metadata?: {
|
|
1753
|
+
sectionBindingOverride?: SectionBindingOverride;
|
|
1754
|
+
selectedField?: string;
|
|
1755
|
+
compositionUID?: string;
|
|
1756
|
+
[key: string]: unknown;
|
|
1757
|
+
};
|
|
1758
|
+
}
|
|
1759
|
+
type LinkedSchemasLookup = (compositionUid: string | undefined) => Array<{
|
|
1760
|
+
content_type_uid: string;
|
|
1761
|
+
selected_field?: string;
|
|
1762
|
+
}>;
|
|
1763
|
+
/**
|
|
1764
|
+
* The legacy `selectedField` ladder, verbatim: per-instance override → legacy
|
|
1765
|
+
* `metadata.selectedField` → the `linked_schemas` default for the page content
|
|
1766
|
+
* type → the first schema.
|
|
1767
|
+
*
|
|
1768
|
+
* Extracted so the Section data resolver and the existing page-template
|
|
1769
|
+
* projection read the SAME ladder and cannot drift. Returns the path
|
|
1770
|
+
* **unsanitised** — callers that need CDA-safe segments sanitise at the point
|
|
1771
|
+
* of use, exactly as they did before the Section data existed.
|
|
1772
|
+
*/
|
|
1773
|
+
declare function resolveLegacySelectedField(node: SectionInstanceNode, linkedSchemasFor: LinkedSchemasLookup, pageContentTypeUid: string): string;
|
|
1774
|
+
/**
|
|
1775
|
+
* Where a resolved `selectedField` came from — which decides whether it is
|
|
1776
|
+
* relative to an enclosing wrapper section or absolute from the page root.
|
|
1777
|
+
*
|
|
1778
|
+
* - `"override"` — the page composer picked it. The picker's options come from
|
|
1779
|
+
* `findMatchingPageFields` against the schema **scoped to the drop
|
|
1780
|
+
* location**, so an override is RELATIVE to the enclosing wrapper.
|
|
1781
|
+
* - `"declared"` — read off `linked_schemas` by matching the PAGE content
|
|
1782
|
+
* type, so it is rooted at the page entry: ABSOLUTE.
|
|
1783
|
+
* - `"legacy"` — `metadata.selectedField` from before per-instance overrides
|
|
1784
|
+
* existed; same origin as `declared`, so also absolute.
|
|
1785
|
+
*
|
|
1786
|
+
* This distinction is what the leading-overlap collapse in
|
|
1787
|
+
* `composeSectionTemplatePrefix` was approximating by string comparison. Overlap
|
|
1788
|
+
* catches an absolute path that happens to SHARE a leading segment with its
|
|
1789
|
+
* ancestor; it cannot catch one that does not, which is how a slot child ends up
|
|
1790
|
+
* with `author.related_block` — a path the referenced content type does not
|
|
1791
|
+
* have, silently dropped by CDA.
|
|
1792
|
+
*/
|
|
1793
|
+
type SelectedFieldProvenance = "override" | "legacy" | "declared";
|
|
1794
|
+
declare function resolveLegacySelectedFieldWithProvenance(node: SectionInstanceNode, linkedSchemasFor: LinkedSchemasLookup, pageContentTypeUid: string): {
|
|
1795
|
+
field: string;
|
|
1796
|
+
provenance: SelectedFieldProvenance;
|
|
1797
|
+
};
|
|
1798
|
+
/**
|
|
1799
|
+
* Whether a resolved field is rooted at the page entry rather than at an
|
|
1800
|
+
* enclosing wrapper section. A page-absolute field must REPLACE the inherited
|
|
1801
|
+
* prefix, never be concatenated onto it.
|
|
1802
|
+
*
|
|
1803
|
+
* A scope-root field ("") is neither — it adds no segment either way — so it is
|
|
1804
|
+
* reported as not absolute to keep the inherited prefix intact.
|
|
1805
|
+
*/
|
|
1806
|
+
declare function isPageAbsoluteField(field: string, provenance: SelectedFieldProvenance): boolean;
|
|
1807
|
+
/**
|
|
1808
|
+
* Resolve a section-composition node's effective **Section data**.
|
|
1809
|
+
*
|
|
1810
|
+
* Resolution order — the existing `selectedField` ladder with one tier added on
|
|
1811
|
+
* top, so this is strictly a superset of today's behaviour:
|
|
1812
|
+
*
|
|
1813
|
+
* 1. `sectionBindingOverride.rootBinding` when the key is PRESENT (including
|
|
1814
|
+
* an explicit `null`, which means cleared)
|
|
1815
|
+
* 2. otherwise synthesise a template-typed binding from the legacy
|
|
1816
|
+
* `selectedField` ladder: override → `metadata.selectedField` →
|
|
1817
|
+
* `linked_schemas` default for the page content type → first schema
|
|
1818
|
+
*
|
|
1819
|
+
* The caller MUST NOT write the result back onto the node. Persisted state is
|
|
1820
|
+
* structurally diffed against the save baseline (ADR 0007), so persisting a
|
|
1821
|
+
* derived value would mark every pre-existing page dirty the moment it opens,
|
|
1822
|
+
* and would freeze a live fallback into a copy.
|
|
1823
|
+
*/
|
|
1824
|
+
declare function resolveInstanceRootBinding(node: SectionInstanceNode, linkedSchemasFor: LinkedSchemasLookup, pageContentTypeUid: string): SectionDataBinding;
|
|
1825
|
+
/**
|
|
1826
|
+
* Which `linked_schemas` entry a placement is bound to.
|
|
1827
|
+
*
|
|
1828
|
+
* Prefers the persisted `matchedSchemaCt` (the only answer available on a
|
|
1829
|
+
* freeform page), falling back to matching the page content type the way the
|
|
1830
|
+
* template path always has.
|
|
1831
|
+
*/
|
|
1832
|
+
declare function resolveMatchedSchema<T extends {
|
|
1833
|
+
content_type_uid: string;
|
|
1834
|
+
selected_field?: string;
|
|
1835
|
+
}>(node: {
|
|
1836
|
+
metadata?: {
|
|
1837
|
+
sectionBindingOverride?: SectionBindingOverride;
|
|
1838
|
+
};
|
|
1839
|
+
}, linkedSchemas: T[] | undefined, pageContentTypeUid: string): T | undefined;
|
|
1840
|
+
/**
|
|
1841
|
+
* Deep-compare two Section datas. Used by the stamp pass, which must compare a
|
|
1842
|
+
* DERIVED binding against a DERIVED binding: comparing a `BindingType` object
|
|
1843
|
+
* against a raw `selectedField` string never matches, so every template
|
|
1844
|
+
* placement would stamp and every old page would go dirty on open.
|
|
1845
|
+
*/
|
|
1846
|
+
declare function sectionDataEqual(a: SectionDataBinding, b: SectionDataBinding): boolean;
|
|
1029
1847
|
/**
|
|
1030
|
-
* A single
|
|
1031
|
-
*
|
|
1848
|
+
* A **fetch root**: the single fetched document a set of data paths is rooted
|
|
1849
|
+
* at, and whose CDA `include[]` those paths are contributed to.
|
|
1850
|
+
*
|
|
1851
|
+
* `include[]` / `only[]` are properties of a *request*, not of a path — you can
|
|
1852
|
+
* only add an include to a document that is actually being fetched. So a path
|
|
1853
|
+
* is only meaningful paired with the document it counts from.
|
|
1854
|
+
*
|
|
1855
|
+
* A template page has exactly ONE fetch root (the template entry), which is why
|
|
1856
|
+
* the pre-existing code could accumulate every section's paths into two flat
|
|
1857
|
+
* arrays. A freeform page has one per Section data in play, so the destination is
|
|
1858
|
+
* per-instance and only knowable after resolving that instance's binding.
|
|
1032
1859
|
*/
|
|
1033
|
-
interface
|
|
1034
|
-
|
|
1860
|
+
interface FetchRoot {
|
|
1861
|
+
/** `"template"`, a `<ct>:<uid>` pool key, or `query:<dsUid>`. */
|
|
1035
1862
|
key: string;
|
|
1036
|
-
|
|
1863
|
+
/** The path *within* that document. */
|
|
1864
|
+
prefix: string[];
|
|
1037
1865
|
}
|
|
1866
|
+
declare const TEMPLATE_FETCH_ROOT_KEY = "template";
|
|
1867
|
+
declare const templateFetchRoot: (prefix?: string[]) => FetchRoot;
|
|
1868
|
+
/** Whether a fetch-root key names the page template entry. */
|
|
1869
|
+
declare function isTemplateFetchRoot(key: string): boolean;
|
|
1038
1870
|
/**
|
|
1039
|
-
*
|
|
1040
|
-
*
|
|
1041
|
-
* Next.js `generateMetadata`, Remix `meta()`, TanStack `head()`, or a raw
|
|
1042
|
-
* HTML template via {@link renderMetadataToHtml}.
|
|
1871
|
+
* Parse a `<ct>:<uid>` fetch-root key back into its parts. Returns null for the
|
|
1872
|
+
* template root and for query roots, neither of which is an entry.
|
|
1043
1873
|
*/
|
|
1044
|
-
|
|
1045
|
-
|
|
1046
|
-
|
|
1047
|
-
|
|
1048
|
-
/** Absolute canonical URL. Present only when `baseUrl` was provided and the composition has a URL. */
|
|
1049
|
-
canonical?: string;
|
|
1050
|
-
/** Every derived tag (description, og:*, twitter:*, custom metaProps) in render order. */
|
|
1051
|
-
tags: CompositionMetaTag[];
|
|
1052
|
-
}
|
|
1053
|
-
interface GetCompositionMetadataOptions {
|
|
1054
|
-
/**
|
|
1055
|
-
* Site origin used to absolutize the canonical URL and og:url,
|
|
1056
|
-
* e.g. `https://www.example.com`. No trailing slash required.
|
|
1057
|
-
*/
|
|
1058
|
-
baseUrl?: string;
|
|
1059
|
-
}
|
|
1874
|
+
declare function parseEntryFetchRootKey(key: string): {
|
|
1875
|
+
contentTypeUid: string;
|
|
1876
|
+
entryUid: string;
|
|
1877
|
+
} | null;
|
|
1060
1878
|
/**
|
|
1061
|
-
*
|
|
1879
|
+
* Derive the fetch root a Section data addresses.
|
|
1062
1880
|
*
|
|
1063
|
-
* The
|
|
1064
|
-
*
|
|
1065
|
-
* resolved values into standard head-tag structures.
|
|
1881
|
+
* The first path segment of a non-template binding names the **document**, not
|
|
1882
|
+
* a field inside it, so it becomes the key and is dropped from the prefix:
|
|
1066
1883
|
*
|
|
1067
|
-
*
|
|
1068
|
-
*
|
|
1069
|
-
* const meta = getCompositionMetadata(specOptions, { baseUrl: "https://example.com" });
|
|
1070
|
-
* res.send(`<head><title>${meta.title}</title>${renderMetadataToHtml(meta)}</head>...`);
|
|
1071
|
-
* ```
|
|
1884
|
+
* { contentstack, path: { "mkt_ct:blt1": { banner: {} } } }
|
|
1885
|
+
* → { key: "mkt_ct:blt1", prefix: ["banner"] }
|
|
1072
1886
|
*
|
|
1073
|
-
*
|
|
1074
|
-
*
|
|
1075
|
-
*
|
|
1076
|
-
*
|
|
1077
|
-
*
|
|
1078
|
-
*
|
|
1079
|
-
* ```
|
|
1080
|
-
*/
|
|
1081
|
-
declare function getCompositionMetadata(specOptions: Pick<StudioComponentSpecOptions, "seo" | "spec">, options?: GetCompositionMetadataOptions): CompositionMetadata;
|
|
1082
|
-
/**
|
|
1083
|
-
* Renders {@link CompositionMetadata} to a raw HTML string (meta + canonical
|
|
1084
|
-
* link tags — the `<title>` element is left to the caller since most hosts
|
|
1085
|
-
* manage it separately). For template-string SSR hosts (Express/Fastify).
|
|
1887
|
+
* A `repeater`-typed root inherits the enclosing document: the repeater re-scopes
|
|
1888
|
+
* per iteration at render time, but the includes still belong to whichever
|
|
1889
|
+
* document the repeater's own source was fetched from.
|
|
1890
|
+
*
|
|
1891
|
+
* Returns `inherited` unchanged for a cleared root — there is nothing to fetch,
|
|
1892
|
+
* so nothing should be re-anchored.
|
|
1086
1893
|
*/
|
|
1087
|
-
declare function
|
|
1894
|
+
declare function fetchRootFromBinding(root: SectionDataBinding, inherited: FetchRoot): FetchRoot;
|
|
1088
1895
|
|
|
1089
1896
|
/**
|
|
1090
1897
|
* Processes the raw static values and stored them against their static value UID.
|
|
@@ -1138,142 +1945,6 @@ declare function addContextMenuEventListeners(): {
|
|
|
1138
1945
|
removeEventListeners: () => void;
|
|
1139
1946
|
} | undefined;
|
|
1140
1947
|
|
|
1141
|
-
declare const MAX_SCROLL_SPEED = 100;
|
|
1142
|
-
declare const SCROLL_INTERVAL = 50;
|
|
1143
|
-
declare const EDGE_PADDING = 50;
|
|
1144
|
-
interface MousePosition {
|
|
1145
|
-
clientX: number;
|
|
1146
|
-
clientY: number;
|
|
1147
|
-
}
|
|
1148
|
-
declare class DNDManager {
|
|
1149
|
-
started: boolean;
|
|
1150
|
-
dragging: boolean;
|
|
1151
|
-
scrollContainer: HTMLElement | null;
|
|
1152
|
-
scrollInterval: ReturnType<typeof setInterval> | undefined;
|
|
1153
|
-
startPosition: MousePosition | null;
|
|
1154
|
-
hasMoved: boolean;
|
|
1155
|
-
mouseDown: boolean;
|
|
1156
|
-
constructor();
|
|
1157
|
-
handleMouseDown(_e: MouseEvent): void;
|
|
1158
|
-
handleMouseUp(_e: MouseEvent): void;
|
|
1159
|
-
handleMouseLeave(e: MouseEvent): void;
|
|
1160
|
-
start(e: MouseEvent): void;
|
|
1161
|
-
startParent(): void;
|
|
1162
|
-
end(): void;
|
|
1163
|
-
mouseMove(e: MouseEvent): void;
|
|
1164
|
-
get isStarted(): boolean;
|
|
1165
|
-
get isDragging(): boolean;
|
|
1166
|
-
hasExceededTolerance(start: MousePosition, end: MousePosition): boolean;
|
|
1167
|
-
}
|
|
1168
|
-
declare const dndManager: DNDManager;
|
|
1169
|
-
|
|
1170
|
-
declare const dndEventListener: () => {
|
|
1171
|
-
removeEventListeners: () => void;
|
|
1172
|
-
};
|
|
1173
|
-
|
|
1174
|
-
declare const getScrollableParent: (el: HTMLElement) => HTMLElement;
|
|
1175
|
-
declare const calculateDynamicSpeed: (distance: number, padding: number, maxSpeed: number) => number;
|
|
1176
|
-
|
|
1177
|
-
declare function handleOnScroll(): void;
|
|
1178
|
-
declare function handleResize(): void;
|
|
1179
|
-
declare const isModKey: (e: MouseEvent | KeyboardEvent) => boolean;
|
|
1180
|
-
declare function addHighlightNodeEventListeners(): {
|
|
1181
|
-
removeEventListeners: () => void;
|
|
1182
|
-
} | undefined;
|
|
1183
|
-
|
|
1184
|
-
type OnStyleChangeCallback = (options: {
|
|
1185
|
-
activeNodeUID: string;
|
|
1186
|
-
element: HTMLElement;
|
|
1187
|
-
componentClassName: string;
|
|
1188
|
-
}) => void;
|
|
1189
|
-
declare class HighlightNodeManager {
|
|
1190
|
-
activeNodeUID: string | null;
|
|
1191
|
-
focusedNodeUID: string | null;
|
|
1192
|
-
activeNodePath: Path | null;
|
|
1193
|
-
focusedNodePath: Path | null;
|
|
1194
|
-
hoveredNodeUID: string | null;
|
|
1195
|
-
activeSlotUID: string | null;
|
|
1196
|
-
styleGroup: string | null;
|
|
1197
|
-
onStyleChangeCallbacks: Set<OnStyleChangeCallback>;
|
|
1198
|
-
onActiveNodeChangeCallbacks: Set<(uid: string, path: Path) => void>;
|
|
1199
|
-
visible: boolean;
|
|
1200
|
-
constructor();
|
|
1201
|
-
private setActiveNodeUID;
|
|
1202
|
-
private setFocusedNodeUID;
|
|
1203
|
-
setHoveredNode(uid: string): void;
|
|
1204
|
-
setActiveSlotUID(uid: string | null): void;
|
|
1205
|
-
resetActiveNode(): void;
|
|
1206
|
-
resetFocusedNode(): void;
|
|
1207
|
-
/**
|
|
1208
|
-
* Subscribe to changes in the active node.
|
|
1209
|
-
*
|
|
1210
|
-
* @param callback - Function that will be called whenever the active node changes.
|
|
1211
|
-
* The callback receives the UID of the newly active node as a parameter.
|
|
1212
|
-
* @param options - Configuration options
|
|
1213
|
-
* @param options.syncToExistingValue - When true, the callback will be immediately called
|
|
1214
|
-
* with the current active node's UID. When false, the callback will only be called on future changes.
|
|
1215
|
-
* Defaults to false.
|
|
1216
|
-
*
|
|
1217
|
-
* @example
|
|
1218
|
-
* ```ts
|
|
1219
|
-
* highlightNodeManager.onActiveNodeChange((uid) => {
|
|
1220
|
-
* console.log('Active node changed to:', uid);
|
|
1221
|
-
* }, { syncToExistingValue: true });
|
|
1222
|
-
* ```
|
|
1223
|
-
*/
|
|
1224
|
-
onActiveNodeChange(callback: (uid: string, path: Path) => void, options: {
|
|
1225
|
-
syncToExistingValue: boolean;
|
|
1226
|
-
}): void;
|
|
1227
|
-
/**
|
|
1228
|
-
* Unsubscribe from changes in the active node.
|
|
1229
|
-
*
|
|
1230
|
-
* @param callback - The callback function to unsubscribe.
|
|
1231
|
-
*
|
|
1232
|
-
* @example
|
|
1233
|
-
* ```ts
|
|
1234
|
-
* const onHighlight = (uid: string) => {
|
|
1235
|
-
* console.log('Active node changed to:', uid);
|
|
1236
|
-
* };
|
|
1237
|
-
*
|
|
1238
|
-
* highlightNodeManager.onActiveNodeChange(onHighlight);
|
|
1239
|
-
* highlightNodeManager.unsubscribeFromActiveNodeChange(onHighlight);
|
|
1240
|
-
* ```
|
|
1241
|
-
*/
|
|
1242
|
-
unsubscribeFromActiveNodeChange(callback: (uid: string, path: Path) => void): void;
|
|
1243
|
-
private notifyActiveNodeChange;
|
|
1244
|
-
removeNodeHighligher(): void;
|
|
1245
|
-
hideActiveNode(): void;
|
|
1246
|
-
setStyleGroup: (styleGroup: string | null) => void;
|
|
1247
|
-
subscribeToOnStyleChange: (callback: OnStyleChangeCallback) => void;
|
|
1248
|
-
unsubscribeFromOnStyleChange: (callback: OnStyleChangeCallback) => void;
|
|
1249
|
-
resetStyleGroup(): void;
|
|
1250
|
-
setAndHighlightActiveNode(uid: string): void;
|
|
1251
|
-
setAndHighlightFocusedNode(uid: string): void;
|
|
1252
|
-
setAndHighlightHoveredNode(uid: string): void;
|
|
1253
|
-
setAndHighlightStyleNode(styleGroup: string, uid: string): {
|
|
1254
|
-
styles: undefined;
|
|
1255
|
-
} | {
|
|
1256
|
-
styles: Partial<CSSStyleDeclaration>;
|
|
1257
|
-
};
|
|
1258
|
-
highlightActiveNode(): void;
|
|
1259
|
-
highlightFocusedNode(): void;
|
|
1260
|
-
highlightNodeOnHover(): void;
|
|
1261
|
-
highlightStyleNode(): void;
|
|
1262
|
-
sendStylesToClient(): {
|
|
1263
|
-
styles: undefined;
|
|
1264
|
-
} | {
|
|
1265
|
-
styles: Partial<CSSStyleDeclaration>;
|
|
1266
|
-
};
|
|
1267
|
-
highlightSlotNode(): void;
|
|
1268
|
-
private getStylesObject;
|
|
1269
|
-
private getHighlightStyleNodePayload;
|
|
1270
|
-
getBoundingRectOfDisplayContents(element: HTMLElement): DOMRect | null;
|
|
1271
|
-
private getNodeRect;
|
|
1272
|
-
private getNodePath;
|
|
1273
|
-
getAncestorsElements(currEl: HTMLElement): HTMLElement[];
|
|
1274
|
-
}
|
|
1275
|
-
declare const highlightNodeManager: HighlightNodeManager;
|
|
1276
|
-
|
|
1277
1948
|
/**
|
|
1278
1949
|
* Listens for URL changes inside the iframe (SPA navigations, pushState, replaceState, popstate)
|
|
1279
1950
|
* and sends URL_CHANGE postMessage to the parent so the studio can sync the navbar URL.
|
|
@@ -1283,10 +1954,6 @@ declare function addUrlChangeListeners(): {
|
|
|
1283
1954
|
removeEventListeners: () => void;
|
|
1284
1955
|
} | undefined;
|
|
1285
1956
|
|
|
1286
|
-
declare function addHighlightSpacingEventListeners(): {
|
|
1287
|
-
removeEventListeners: () => void;
|
|
1288
|
-
} | undefined;
|
|
1289
|
-
|
|
1290
1957
|
declare function addBreakpointEventListeners(): {
|
|
1291
1958
|
removeEventListeners: () => void;
|
|
1292
1959
|
} | undefined;
|
|
@@ -1316,6 +1983,220 @@ declare class BreakpointManager {
|
|
|
1316
1983
|
private syncBreakpointsWithStudio;
|
|
1317
1984
|
}
|
|
1318
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
|
+
|
|
1319
2200
|
interface GoogleFont {
|
|
1320
2201
|
family: string;
|
|
1321
2202
|
variants: string[];
|
|
@@ -1555,20 +2436,6 @@ declare function getEmbeddedEntryRenderer(): ((args: EmbeddedEntryRenderArgs) =>
|
|
|
1555
2436
|
*/
|
|
1556
2437
|
declare function getEmbeddedAssetRenderer(): ((args: EmbeddedAssetRenderArgs) => string) | null;
|
|
1557
2438
|
|
|
1558
|
-
declare const compositionSaveEventListener: () => {
|
|
1559
|
-
unregister: () => void;
|
|
1560
|
-
} | undefined;
|
|
1561
|
-
|
|
1562
|
-
declare function openHiddenElementNotification(uid: string): void;
|
|
1563
|
-
declare function closeHiddenElementNotification(uid: string): void;
|
|
1564
|
-
declare function hiddenElementNotificationEventEmitter(): {
|
|
1565
|
-
unregister: () => void;
|
|
1566
|
-
} | undefined;
|
|
1567
|
-
|
|
1568
|
-
declare function getNodeScreenshotEvent(): {
|
|
1569
|
-
unregister: () => void;
|
|
1570
|
-
} | undefined;
|
|
1571
|
-
|
|
1572
2439
|
interface QuerySpec {
|
|
1573
2440
|
contentType: string;
|
|
1574
2441
|
sourceType?: "content_type" | "contentstack" | "taxonomy";
|
|
@@ -1658,7 +2525,7 @@ type UrlMetadataQueryMode = "match" | "existence";
|
|
|
1658
2525
|
* stringifies it and passes it to `api.cma.entry.getAll` via the `query` param.
|
|
1659
2526
|
*
|
|
1660
2527
|
* In `existence` mode for `legacy_url` and `content_type_url_pattern` the
|
|
1661
|
-
* object is `{ url: { $nin: ["", null
|
|
2528
|
+
* object is `{ url: { $nin: [""], $ne: null } }` regardless of `extractedVariables`.
|
|
1662
2529
|
*/
|
|
1663
2530
|
declare function buildUrlMetadataQueryObject(context: Pick<TemplateQueryContext, "compositionQuery" | "extractedVariables" | "url_source">, mode?: UrlMetadataQueryMode): Record<string, any>;
|
|
1664
2531
|
/**
|
|
@@ -1729,5 +2596,5 @@ declare function rankUrlMatches(requestUrl: string, lightweightEntries: Lightwei
|
|
|
1729
2596
|
*/
|
|
1730
2597
|
declare function shouldUseUrlMetadataPath(url_metadata?: Partial<CompositionUrlMetadataSerialized>): boolean;
|
|
1731
2598
|
|
|
1732
|
-
export { BreakpointManager, COMPOSABLE_DATA_ATTRIBUTES, COMPOSABLE_STUDIO_EMITTED_EVENTS, COMPOSITION_PLACEMENT_OPTIONS, COMPOSITION_PREVIEW_URL_SOURCES, COMPOSITION_PREVIEW_URL_SOURCES_VALUES, ComposableStudioError,
|
|
1733
|
-
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, FetchTemplateEntryContext, FieldValue, FontVariants, GetCompositionMetadataOptions, GoogleFont, HiddenElementNotificationHandler, LightConfig, LightweightCompositionEntry, MetaProp, ParsedStringResult, PatternMatchResult, QueryExecutionOptions, QueryResult, QuerySpec, QueryState, RTEConfig, RankingResult, ReferenceFieldValue, RenderableCompositionEntry, ResolvedEmbeddedEntry, ResolvedQueryOptions, RuntimeContext, SearchQueryInput, SectionCompositionEntry, SeoMetadata, StudioComponentFetchOptions, StudioComponentSpecOptions, StudioMode, StudioSdk, StudioSpec, TemplateEntryFetcher, TemplateQueryContext, TroubleshootingInfo, URLSearchParamsString, UrlMatchDiagnostic, UrlMetadataQueryMode, UrlPatternMetadataField, UrlPatternMetadataFieldValue, UserConfig };
|
|
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 };
|
|
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 };
|