@contentstack/studio-message-types 1.5.2 → 2.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.
@@ -13,6 +13,52 @@ export type InitMessage = {
13
13
  configPassedToTheSdk: {
14
14
  contentTypeUid: string;
15
15
  };
16
+ /**
17
+ * What the connection was built from, as read at init.
18
+ *
19
+ * These are facts, not diagnoses. The SDK reports what it holds and the
20
+ * surface decides what it means — which is what lets the reading improve
21
+ * without every site upgrading its SDK, and what keeps a judgement about a
22
+ * customer's setup out of a package that cannot see the other half of it.
23
+ *
24
+ * Every field is optional and its absence says nothing. An older SDK sends
25
+ * none of them, and a surface that reads an absent value as `false` turns
26
+ * silence into a claim about a configuration it was never shown.
27
+ *
28
+ * There is no field for a delivery or preview token, and there never will be:
29
+ * whether a preview token is present is a boolean, so a token cannot reach
30
+ * the parent even by accident.
31
+ */
32
+ setup?: {
33
+ /**
34
+ * The api key the connection was built with. A public identifier that rides
35
+ * in every client request, not a secret — it is here so a surface can show it
36
+ * beside the key it expected, which is a string a developer can search their
37
+ * codebase for. Naming only the correct one says nothing about where the
38
+ * wrong one came from.
39
+ */
40
+ apiKey?: string;
41
+ /** The environment the connection queries published content from. */
42
+ environment?: string;
43
+ /** The locale the SDK was configured with, before any address overrides it. */
44
+ locale?: string;
45
+ /** The address delivery requests go to. */
46
+ host?: string;
47
+ /**
48
+ * Whether live preview is switched on in the site's setup.
49
+ *
50
+ * Absent when there was no stack to read it from. A surface that read that
51
+ * absence as `false` would tell an author live preview is not switched on in
52
+ * a configuration it was never shown.
53
+ */
54
+ livePreviewEnabled?: boolean;
55
+ /** Whether a preview token was supplied. Never the token itself. */
56
+ hasPreviewToken?: boolean;
57
+ /** The address live preview is pointed at, when one is configured. */
58
+ previewHost?: string;
59
+ /** Whether a preview hash reached the SDK from the address. */
60
+ hasPreviewHash?: boolean;
61
+ };
16
62
  };
17
63
  export declare enum TARGET_NODE {
18
64
  ACTIVE_NODE = "active-node",
@@ -35,6 +81,14 @@ export interface HighlightAncestorsEventPayload extends BaseHighlightEventPayloa
35
81
  path: Path;
36
82
  hoveredNodeRect: DOMRect;
37
83
  hoveredNodeAncestorsRect: DOMRect[];
84
+ /**
85
+ * Set when the pointer (or a Layers slot row) is on one slot of the node at
86
+ * `path` rather than on the node itself; `hoveredSlotRect` is that slot's box.
87
+ * `hoveredNodeRect` stays the node's, so a Studio that predates slot hover
88
+ * keeps outlining the node.
89
+ */
90
+ slotUid?: string;
91
+ hoveredSlotRect?: DOMRect;
38
92
  }
39
93
  export interface HighlightStyleNodeEventPayload extends BaseHighlightEventPayload {
40
94
  target: TARGET_NODE_TYPE["STYLE_NODE"];
@@ -56,10 +110,37 @@ export type HighlightNodeEventPayload = HighlightActiveNodeEventPayload | Highli
56
110
  export interface RequestHighlightNodeEventPayload {
57
111
  target: TARGET_NODE_TYPE["ACTIVE_NODE"] | TARGET_NODE_TYPE["HOVERED_NODE"] | TARGET_NODE_TYPE["FOCUSED_NODE"];
58
112
  uid: string;
113
+ /**
114
+ * Hovered-node only: hover this slot of the node `uid` instead of the node.
115
+ * An SDK that predates slot hover ignores it and hovers the node.
116
+ */
117
+ slotUid?: string;
59
118
  }
60
119
  export interface handleActiveNodePayload {
61
120
  uid?: string;
62
121
  }
122
+ /** Ask the canvas to scroll to the first node in `chain` that it can measure. */
123
+ export interface RevealNodePayload {
124
+ /** The node the author picked, then its ancestors, nearest first. */
125
+ chain: string[];
126
+ }
127
+ /** Why the canvas could not show the node that was asked for. */
128
+ export type RevealMissKind = "no-element" | "zero-area";
129
+ /**
130
+ * What the canvas found for a reveal request.
131
+ *
132
+ * `miss` is the one fact only the canvas can supply. The editor cannot derive
133
+ * it: the component registry's `wrap: false` means Studio adds no wrapper of
134
+ * its own, not that the component renders nothing.
135
+ */
136
+ export interface RevealResultPayload {
137
+ /** The node the author picked in Layers — `chain[0]` of the request. */
138
+ requestedUid: string;
139
+ /** The node actually scrolled to: an ancestor on a miss, null when none could be measured. */
140
+ revealedUid: string | null;
141
+ /** Absent when the requested node was the one revealed. */
142
+ miss: RevealMissKind | null;
143
+ }
63
144
  export interface handleFocusedNodePayload {
64
145
  uid?: string;
65
146
  }
@@ -204,6 +285,47 @@ export interface ResolvedComposition {
204
285
  * specificity), and which won — letting Studio list what loaded and, when the
205
286
  * data proves it, explain why the edited composition didn't.
206
287
  */
288
+ /**
289
+ * Where a request went and what it was made with. The same shape on every
290
+ * diagnostic, sent whether the request succeeded or failed.
291
+ *
292
+ * It rides on the message rather than on the error because the failures that
293
+ * need it most are the ones where nothing fails: a page that renders published
294
+ * content instead of the author's drafts has no error to carry anything, and is
295
+ * diagnosed by comparing these facts against what Studio holds.
296
+ *
297
+ * **There is no field here for a delivery or preview token**, and there never
298
+ * will be. One fixed shape is what makes that checkable in one place.
299
+ */
300
+ export interface StudioDiagnosticContext {
301
+ mode?: string;
302
+ apiKey?: string;
303
+ environment?: string;
304
+ locale?: string;
305
+ host?: string;
306
+ livePreviewEnabled?: boolean;
307
+ /** Which service answered: published content, preview, or not knowable. */
308
+ servedBy?: "cdn" | "preview" | "unknown";
309
+ sdkVersion?: string;
310
+ }
311
+ /** What the SDK diagnosed about a failure. */
312
+ export interface StudioDiagnosticFinding {
313
+ /** Names the diagnosed case. What a surface selects its wording from. */
314
+ code?: string;
315
+ /**
316
+ * Which of the five classes the code belongs to. Carried so a surface that
317
+ * does not recognise the code can still say something true about it — the
318
+ * codes a surface knows are fixed the day it ships, and the classes are not.
319
+ */
320
+ class?: string;
321
+ /** Ordered, most likely first. Developer-facing English: never rendered to an author. */
322
+ causes?: Array<{
323
+ cause: string;
324
+ fix: string;
325
+ }>;
326
+ /** What this particular failure established, narrowed by `code`. */
327
+ findings?: Record<string, unknown>;
328
+ }
207
329
  export interface CompositionResolutionDiagnosticEventData {
208
330
  kind: "composition-resolution";
209
331
  /** True for `StudioCanvas` (renders the edited composition by uid), false for regular components. */
@@ -222,9 +344,19 @@ export interface CompositionResolutionDiagnosticEventData {
222
344
  shortlisted?: ShortlistedComposition[];
223
345
  /** The winner — present on success. */
224
346
  resolved?: ResolvedComposition;
225
- /** Present on failure (e.g. COMPOSITION_NOT_FOUND_BY_URL). */
226
- error?: {
227
- id?: string;
347
+ /** Where this request went. Sent on success and on failure alike. */
348
+ context?: StudioDiagnosticContext;
349
+ /**
350
+ * Present when the page could not be loaded. Its presence means the SDK threw,
351
+ * and a throw is what decides the host's HTTP status — so nothing that leaves
352
+ * a working page belongs here. A page that rendered with something wrong on it
353
+ * is diagnosed by comparing `context` against what the surface already knows,
354
+ * the way a content-type mismatch already is.
355
+ *
356
+ * `message` is developer-facing English and is not translated for an author;
357
+ * read `code` for the case.
358
+ */
359
+ error?: StudioDiagnosticFinding & {
228
360
  message: string;
229
361
  };
230
362
  timestamp: number;
@@ -1,7 +1,7 @@
1
- import { HitboxDetails, ValidatePropEventPayload, PreProcessedBreakpoint, SlotNodeHitboxDetails, HighlightNodeEventPayload, RequestHighlightNodeEventPayload, HighlightFocusedNodeEventPayload, HighlightSlotNodeEventPayload, HighlightStyleNodeEventPayload, HighlightActiveNodeEventPayload, BaseHighlightEventPayload, RegularNodeHitboxDetails, SerializedEvent, UrlChangeEventPayload, Breakpoint, HighlightAncestorsEventPayload, InitMessage, DefaultBreakpoint, ActiveBreakpointEventPayload, BreakpointInput, RegisterBreakpointsEventPayload, SetCursorTypeEventPayload, UpdateStyleEventPayload, ComputedStyleSection, ChangeActiveStyleGroupPayload, handleActiveNodePayload, handleFocusedNodePayload, handleActiveSlotNode, MouseMoveEventPayload, MouseUpEventPayload, DraggerPosition, UpdateBindingErrorsEventPayload, OpenComposableStudioFromVBEventData, OpenComposableStudioFromStudioEventData, CompositionSavedEventData, PrimaryCompositionDetectedEventData, CompositionResolutionDiagnosticEventData, HiddenElementNotificationEventData, GetNodeScreenshotEventData, GetNodeScreenshotResponseEventData, RefetchSpecEventData, TARGET_NODE } from "./client.js";
1
+ import { HitboxDetails, ValidatePropEventPayload, PreProcessedBreakpoint, SlotNodeHitboxDetails, HighlightNodeEventPayload, RequestHighlightNodeEventPayload, HighlightFocusedNodeEventPayload, HighlightSlotNodeEventPayload, RevealNodePayload, RevealResultPayload, HighlightStyleNodeEventPayload, HighlightActiveNodeEventPayload, BaseHighlightEventPayload, RegularNodeHitboxDetails, SerializedEvent, UrlChangeEventPayload, Breakpoint, HighlightAncestorsEventPayload, InitMessage, DefaultBreakpoint, ActiveBreakpointEventPayload, BreakpointInput, RegisterBreakpointsEventPayload, SetCursorTypeEventPayload, UpdateStyleEventPayload, ComputedStyleSection, ChangeActiveStyleGroupPayload, handleActiveNodePayload, handleFocusedNodePayload, handleActiveSlotNode, MouseMoveEventPayload, MouseUpEventPayload, DraggerPosition, UpdateBindingErrorsEventPayload, OpenComposableStudioFromVBEventData, OpenComposableStudioFromStudioEventData, CompositionSavedEventData, PrimaryCompositionDetectedEventData, CompositionResolutionDiagnosticEventData, HiddenElementNotificationEventData, GetNodeScreenshotEventData, GetNodeScreenshotResponseEventData, RefetchSpecEventData, TARGET_NODE } from "./client.js";
2
2
  import type { CompositionQuery } from "./composition-query.js";
3
3
  export type { CompositionQuery };
4
- export type { InitMessage, HighlightActiveNodeEventPayload, HighlightAncestorsEventPayload, HighlightStyleNodeEventPayload, HighlightSlotNodeEventPayload, HighlightFocusedNodeEventPayload, HighlightNodeEventPayload, RequestHighlightNodeEventPayload, BaseHighlightEventPayload, HitboxDetails, RegularNodeHitboxDetails, SlotNodeHitboxDetails, SerializedEvent, UrlChangeEventPayload, ValidatePropEventPayload, Breakpoint, PreProcessedBreakpoint, DefaultBreakpoint, BreakpointInput, ActiveBreakpointEventPayload, RegisterBreakpointsEventPayload, SetCursorTypeEventPayload, UpdateStyleEventPayload, ComputedStyleSection, ChangeActiveStyleGroupPayload, handleActiveNodePayload, handleFocusedNodePayload, handleActiveSlotNode, MouseMoveEventPayload, MouseUpEventPayload, DraggerPosition, UpdateBindingErrorsEventPayload, OpenComposableStudioFromVBEventData, OpenComposableStudioFromStudioEventData, CompositionSavedEventData, PrimaryCompositionDetectedEventData, CompositionResolutionDiagnosticEventData, ShortlistedComposition, ResolvedComposition, HiddenElementNotificationEventData, GetNodeScreenshotEventData, GetNodeScreenshotResponseEventData, RefetchSpecEventData, } from "./client.js";
4
+ export type { InitMessage, HighlightActiveNodeEventPayload, HighlightAncestorsEventPayload, HighlightStyleNodeEventPayload, HighlightSlotNodeEventPayload, RevealMissKind, RevealNodePayload, RevealResultPayload, HighlightFocusedNodeEventPayload, HighlightNodeEventPayload, RequestHighlightNodeEventPayload, BaseHighlightEventPayload, HitboxDetails, RegularNodeHitboxDetails, SlotNodeHitboxDetails, SerializedEvent, UrlChangeEventPayload, ValidatePropEventPayload, Breakpoint, PreProcessedBreakpoint, DefaultBreakpoint, BreakpointInput, ActiveBreakpointEventPayload, RegisterBreakpointsEventPayload, SetCursorTypeEventPayload, UpdateStyleEventPayload, ComputedStyleSection, ChangeActiveStyleGroupPayload, handleActiveNodePayload, handleFocusedNodePayload, handleActiveSlotNode, MouseMoveEventPayload, MouseUpEventPayload, DraggerPosition, UpdateBindingErrorsEventPayload, OpenComposableStudioFromVBEventData, OpenComposableStudioFromStudioEventData, CompositionSavedEventData, PrimaryCompositionDetectedEventData, CompositionResolutionDiagnosticEventData, ShortlistedComposition, ResolvedComposition, HiddenElementNotificationEventData, GetNodeScreenshotEventData, GetNodeScreenshotResponseEventData, RefetchSpecEventData, } from "./client.js";
5
5
  export { TARGET_NODE } from "./client.js";
6
6
  export type BaseType = {
7
7
  InitMessage: InitMessage;
@@ -9,6 +9,8 @@ export type BaseType = {
9
9
  HighlightAncestorsEventPayload: HighlightAncestorsEventPayload;
10
10
  HighlightStyleNodeEventPayload: HighlightStyleNodeEventPayload;
11
11
  HighlightSlotNodeEventPayload: HighlightSlotNodeEventPayload;
12
+ RevealNodePayload: RevealNodePayload;
13
+ RevealResultPayload: RevealResultPayload;
12
14
  HighlightFocusedNodeEventPayload: HighlightFocusedNodeEventPayload;
13
15
  HighlightNodeEventPayload: HighlightNodeEventPayload;
14
16
  RequestHighlightNodeEventPayload: RequestHighlightNodeEventPayload;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@contentstack/studio-message-types",
3
- "version": "1.5.2",
3
+ "version": "2.0.0",
4
4
  "type": "module",
5
5
  "description": "Shared message types for communication between Studio platform and SDKs",
6
6
  "author": "RavenColEvol <ravilamkoti@gmail.com>",