@nubisco/cms-vue 1.1.0 → 1.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/cms-vue.css +1 -1
- package/dist/index.d.ts +601 -0
- package/dist/index.js +872 -41
- package/package.json +5 -3
package/dist/index.d.ts
CHANGED
|
@@ -1,16 +1,138 @@
|
|
|
1
|
+
import { App } from 'vue';
|
|
2
|
+
import { Component } from 'vue';
|
|
1
3
|
import { ComponentOptionsMixin } from 'vue';
|
|
2
4
|
import { ComponentProvideOptions } from 'vue';
|
|
5
|
+
import { ComputedRef } from 'vue';
|
|
3
6
|
import { DefineComponent } from 'vue';
|
|
4
7
|
import { InjectionKey } from 'vue';
|
|
8
|
+
import { PropType } from 'vue';
|
|
5
9
|
import { PublicProps } from 'vue';
|
|
10
|
+
import { Ref } from 'vue';
|
|
11
|
+
|
|
12
|
+
declare const __VLS_component: DefineComponent<__VLS_Props_4, {
|
|
13
|
+
link: ComputedRef<ResolvedLink>;
|
|
14
|
+
}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_4> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
|
|
6
15
|
|
|
7
16
|
declare type __VLS_Props = {
|
|
8
17
|
block: BlockInstance;
|
|
9
18
|
field: string;
|
|
10
19
|
};
|
|
11
20
|
|
|
21
|
+
declare type __VLS_Props_2 = {
|
|
22
|
+
zone: Zone;
|
|
23
|
+
registry: Record<string, Component>;
|
|
24
|
+
messages: Record<string, string>;
|
|
25
|
+
env: LogicEnv;
|
|
26
|
+
editing?: boolean;
|
|
27
|
+
selectedId?: string | null;
|
|
28
|
+
graphs?: Record<string, LogicGraph>;
|
|
29
|
+
/**
|
|
30
|
+
* Also pass `index`, `blocks` and `context` to every block component, the
|
|
31
|
+
* shape `getBlockComponentProps()` declares. OFF by default and deliberately:
|
|
32
|
+
* a block component that does not declare those props would render them as
|
|
33
|
+
* fallthrough attributes on its root element, changing the markup of every
|
|
34
|
+
* site already rendering with this zone.
|
|
35
|
+
*/
|
|
36
|
+
provideBlockProps?: boolean;
|
|
37
|
+
/** Passed straight through to each block as `context` when the above is on. */
|
|
38
|
+
context?: unknown;
|
|
39
|
+
setText?: (block: BlockInstance, field: string, current: FieldValue | undefined, next: string) => void;
|
|
40
|
+
};
|
|
41
|
+
|
|
42
|
+
declare type __VLS_Props_3 = {
|
|
43
|
+
block?: BlockInstance;
|
|
44
|
+
field?: string | readonly string[];
|
|
45
|
+
/**
|
|
46
|
+
* Or pass the authored value directly. Typed `unknown` rather than
|
|
47
|
+
* `FieldValue` because `FieldValue` includes `boolean`, and Vue casts an
|
|
48
|
+
* absent prop whose declared type includes Boolean to `false`: every block
|
|
49
|
+
* that read its body from `block`/`field` would have rendered "false".
|
|
50
|
+
*/
|
|
51
|
+
value?: unknown;
|
|
52
|
+
/** Per-node-type rendering overrides, the Prismic serializer equivalent. */
|
|
53
|
+
serializers?: RichTextSerializers;
|
|
54
|
+
/** The element wrapping authored markup. */
|
|
55
|
+
as?: string;
|
|
56
|
+
/** The element wrapping plain authored text. */
|
|
57
|
+
plainAs?: string;
|
|
58
|
+
/**
|
|
59
|
+
* Transform applied after serializers, for the rewrites a serializer cannot
|
|
60
|
+
* express (restructuring a subtree). Kept as an escape hatch so a product
|
|
61
|
+
* with an existing transform can adopt the primitive without losing it.
|
|
62
|
+
*/
|
|
63
|
+
transform?: (html: string) => string;
|
|
64
|
+
};
|
|
65
|
+
|
|
66
|
+
declare type __VLS_Props_4 = {
|
|
67
|
+
/** Read the link out of a block's fields. */
|
|
68
|
+
block?: BlockInstance;
|
|
69
|
+
/** The field name, or several accepted spellings, first filled one wins. */
|
|
70
|
+
field?: string | readonly string[];
|
|
71
|
+
/** Or pass the authored value directly (the object shape, or a bare string). */
|
|
72
|
+
value?: unknown;
|
|
73
|
+
/** The host's own coded href, used only when the document carries nothing. */
|
|
74
|
+
fallback?: string;
|
|
75
|
+
/**
|
|
76
|
+
* Label, when it is not supplied as slot content. Typed `unknown` rather than
|
|
77
|
+
* `FieldValue` on purpose: `FieldValue` includes `boolean`, and Vue casts an
|
|
78
|
+
* ABSENT prop whose declared type includes Boolean to `false`, so the label
|
|
79
|
+
* of every link that did not pass one rendered as the word "false".
|
|
80
|
+
*/
|
|
81
|
+
label?: unknown;
|
|
82
|
+
/** Field holding the label, read from `block` like `field` is. */
|
|
83
|
+
labelField?: string | readonly string[];
|
|
84
|
+
};
|
|
85
|
+
|
|
86
|
+
declare type __VLS_Props_5 = {
|
|
87
|
+
block?: BlockInstance;
|
|
88
|
+
field?: string | readonly string[];
|
|
89
|
+
value?: unknown;
|
|
90
|
+
/** The host's own bundled asset, used only when the document carries nothing. */
|
|
91
|
+
fallback?: string | ResolvedImage;
|
|
92
|
+
/** Overrides the authored alt (a product that knows better than the document). */
|
|
93
|
+
alt?: string;
|
|
94
|
+
};
|
|
95
|
+
|
|
96
|
+
declare function __VLS_template(): {
|
|
97
|
+
attrs: Partial<{}>;
|
|
98
|
+
slots: {
|
|
99
|
+
default?(_: {
|
|
100
|
+
link: ResolvedLink;
|
|
101
|
+
}): any;
|
|
102
|
+
};
|
|
103
|
+
refs: {};
|
|
104
|
+
rootEl: any;
|
|
105
|
+
};
|
|
106
|
+
|
|
107
|
+
declare type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
|
|
108
|
+
|
|
109
|
+
declare type __VLS_WithTemplateSlots<T, S> = T & {
|
|
110
|
+
new (): {
|
|
111
|
+
$slots: S;
|
|
112
|
+
};
|
|
113
|
+
};
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* Apply serializers to authored HTML.
|
|
117
|
+
*
|
|
118
|
+
* A single pass over the tags, keeping a stack of open elements, so a renamed
|
|
119
|
+
* tag's close tag is renamed with it and nesting is never guessed at. Text
|
|
120
|
+
* between tags is passed through byte for byte: nothing here rewrites content.
|
|
121
|
+
*/
|
|
122
|
+
export declare function applySerializers(html: string, serializers?: RichTextSerializers): string;
|
|
123
|
+
|
|
12
124
|
export declare type BlockCategory = 'content' | 'media' | 'form' | 'layout';
|
|
13
125
|
|
|
126
|
+
export declare interface BlockComponentProps<TFields extends Record<string, FieldValue> = Record<string, FieldValue>, TContext = unknown> {
|
|
127
|
+
block: TypedBlock<TFields>;
|
|
128
|
+
/** Position within the zone, for a block whose look depends on where it sits. */
|
|
129
|
+
index?: number;
|
|
130
|
+
/** Every block in the zone, for a block that must know its neighbours. */
|
|
131
|
+
blocks?: BlockInstance[];
|
|
132
|
+
/** Whatever the host passed to the zone: a locale, a feature-flag bag, a route. */
|
|
133
|
+
context?: TContext;
|
|
134
|
+
}
|
|
135
|
+
|
|
14
136
|
/**
|
|
15
137
|
* A block type definition, registered once. The editor catalog, the inspector
|
|
16
138
|
* fields, validation, and serialization all derive from this, mirroring how the
|
|
@@ -70,8 +192,71 @@ export declare interface BlueprintCard {
|
|
|
70
192
|
};
|
|
71
193
|
}
|
|
72
194
|
|
|
195
|
+
export declare const CMS_CLIENT: InjectionKey<CmsClient>;
|
|
196
|
+
|
|
73
197
|
export declare const CMS_CONTEXT: InjectionKey<CmsContext>;
|
|
74
198
|
|
|
199
|
+
/** Key under which the snapshot travels inside the host's initial state. */
|
|
200
|
+
export declare const CMS_PARTIAL_STATE_KEY = "cmsPartials";
|
|
201
|
+
|
|
202
|
+
export declare interface CmsClient {
|
|
203
|
+
readonly siteId: string;
|
|
204
|
+
readonly environment: string;
|
|
205
|
+
readonly apiBase: string;
|
|
206
|
+
/** The console protocol this canvas answers to. See CmsClientOptions. */
|
|
207
|
+
readonly patchMessageType: string;
|
|
208
|
+
readonly options: CmsClientOptions;
|
|
209
|
+
/** The preview state of this render. */
|
|
210
|
+
preview(): CmsPreview;
|
|
211
|
+
/** The delivery URL for a document path, preview included. */
|
|
212
|
+
documentUrl(path: string): string;
|
|
213
|
+
/**
|
|
214
|
+
* Navigate in-app. Returns false when the host gave no router, which is the
|
|
215
|
+
* caller's signal to leave the click to the browser.
|
|
216
|
+
*/
|
|
217
|
+
navigate(href: string): boolean;
|
|
218
|
+
fetchPage(route: string): Promise<CmsPageResult>;
|
|
219
|
+
fetchPartial(key: string): Promise<CmsPartialResult>;
|
|
220
|
+
/** Vue plugin: `app.use(cms)`. */
|
|
221
|
+
install(app: App): void;
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
export declare interface CmsClientOptions {
|
|
225
|
+
/** e.g. 'nubisco-corporate'. */
|
|
226
|
+
siteId: string;
|
|
227
|
+
/** Which environment to read: development | staging | production. */
|
|
228
|
+
environment?: string;
|
|
229
|
+
/** Delivery base, e.g. https://cms.nubisco.io. Required: there is no default. */
|
|
230
|
+
apiBase: string;
|
|
231
|
+
/**
|
|
232
|
+
* The postMessage type the editing console posts a live document with.
|
|
233
|
+
* Defaults to the Nubisco console's, so a white-label console can speak its
|
|
234
|
+
* own protocol without forking the library.
|
|
235
|
+
*/
|
|
236
|
+
patchMessageType?: string;
|
|
237
|
+
/** Injected for tests, or for a Worker that must pass its own fetch. */
|
|
238
|
+
fetch?: FetchLike;
|
|
239
|
+
/**
|
|
240
|
+
* How an internal link navigates. A library cannot assume the host's router,
|
|
241
|
+
* so give it one of these, or neither: with neither, every link stays a plain
|
|
242
|
+
* anchor and the browser does a full page load, which is correct, just slower.
|
|
243
|
+
*/
|
|
244
|
+
router?: CmsRouterLike;
|
|
245
|
+
navigate?: (href: string) => unknown;
|
|
246
|
+
/** Where preview comes from. Defaults to reading the browser's query string. */
|
|
247
|
+
preview?: () => CmsPreview;
|
|
248
|
+
/**
|
|
249
|
+
* Whether partials may be fetched at all. A partial has no route to be
|
|
250
|
+
* published at, so there is no row whose presence could turn it on: the host
|
|
251
|
+
* either composes its chrome from the CMS or it does not.
|
|
252
|
+
*/
|
|
253
|
+
partials?: boolean;
|
|
254
|
+
/** Accept live-preview patches from the console while in edit mode. */
|
|
255
|
+
livePreview?: boolean;
|
|
256
|
+
/** Extra origins a live-preview patch may arrive from (the console's URL). */
|
|
257
|
+
consoleOrigins?: string[];
|
|
258
|
+
}
|
|
259
|
+
|
|
75
260
|
/**
|
|
76
261
|
* Render context provided by CmsZone and injected by field primitives. It
|
|
77
262
|
* carries the string table (for { $t } refs), whether edit mode is on, and the
|
|
@@ -84,10 +269,99 @@ export declare interface CmsContext {
|
|
|
84
269
|
setText: (block: BlockInstance, field: string, current: FieldValue | undefined, next: string) => void;
|
|
85
270
|
}
|
|
86
271
|
|
|
272
|
+
export declare const CmsImage: DefineComponent<__VLS_Props_5, {
|
|
273
|
+
image: ComputedRef<ResolvedImage>;
|
|
274
|
+
}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_5> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
|
|
275
|
+
|
|
276
|
+
export declare const CmsLink: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
|
|
277
|
+
|
|
278
|
+
/**
|
|
279
|
+
* How a load ended. Separate from `error` because the two failures are not the
|
|
280
|
+
* same fact and a request-time renderer has to tell them apart: delivery
|
|
281
|
+
* answering 404 means this path genuinely has no page (render the 404), while
|
|
282
|
+
* delivery being unreachable or broken means we do not know (render nothing and
|
|
283
|
+
* answer 503, so a crawler comes back instead of recording the page as gone).
|
|
284
|
+
*/
|
|
285
|
+
export declare type CmsOutcome = 'ok' | 'missing' | 'unavailable';
|
|
286
|
+
|
|
287
|
+
export declare interface CmsPageDocument {
|
|
288
|
+
route: string;
|
|
289
|
+
meta?: Record<string, unknown>;
|
|
290
|
+
zones: Record<string, Zone>;
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
export declare interface CmsPageResult {
|
|
294
|
+
doc: CmsPageDocument | null;
|
|
295
|
+
error: string | null;
|
|
296
|
+
outcome: CmsOutcome;
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
export declare interface CmsPartialDocument {
|
|
300
|
+
/** The partial key, e.g. 'footer'. Delivery returns it as `key`. */
|
|
301
|
+
key?: string;
|
|
302
|
+
meta?: Record<string, unknown>;
|
|
303
|
+
zones: Record<string, Zone>;
|
|
304
|
+
}
|
|
305
|
+
|
|
306
|
+
export declare interface CmsPartialResult {
|
|
307
|
+
doc: CmsPartialDocument | null;
|
|
308
|
+
/** '' on success; a reason otherwise. Any reason means: render the coded fallback. */
|
|
309
|
+
error: string | null;
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
/** What the server render hands to the browser, per partial key. */
|
|
313
|
+
export declare interface CmsPartialSnapshot {
|
|
314
|
+
doc: CmsPartialDocument | null;
|
|
315
|
+
error: string | null;
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
/** Whether this render is the editor canvas, and what it may read. */
|
|
319
|
+
export declare interface CmsPreview {
|
|
320
|
+
/** True in the in-context editor (?cms-edit=1). Bypasses the edge cache. */
|
|
321
|
+
active: boolean;
|
|
322
|
+
/** ?cms-env override, so the canvas shows the environment being edited. */
|
|
323
|
+
environment?: string;
|
|
324
|
+
/**
|
|
325
|
+
* The short-lived token the console mints for the canvas. Reading a draft is
|
|
326
|
+
* a capability, not a flag: delivery serves one only to a caller that proves
|
|
327
|
+
* it edits this site. The canvas runs on the host's own origin and therefore
|
|
328
|
+
* cannot send a CMS session cookie, which is why the token exists.
|
|
329
|
+
*/
|
|
330
|
+
token?: string;
|
|
331
|
+
}
|
|
332
|
+
|
|
333
|
+
export declare const CmsRichText: DefineComponent<__VLS_Props_3, {
|
|
334
|
+
html: ComputedRef<string>;
|
|
335
|
+
plain: ComputedRef<string>;
|
|
336
|
+
}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_3> & Readonly<{}>, {
|
|
337
|
+
as: string;
|
|
338
|
+
plainAs: string;
|
|
339
|
+
}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
|
|
340
|
+
|
|
341
|
+
/** A router this library can hand a route to, without depending on any router. */
|
|
342
|
+
export declare interface CmsRouterLike {
|
|
343
|
+
push: (to: string) => unknown;
|
|
344
|
+
}
|
|
345
|
+
|
|
87
346
|
export declare const CmsText: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
|
|
88
347
|
el: HTMLSpanElement;
|
|
89
348
|
}, any>;
|
|
90
349
|
|
|
350
|
+
export declare const CmsZone: DefineComponent<__VLS_Props_2, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
|
|
351
|
+
select: (id: string) => any;
|
|
352
|
+
}, string, PublicProps, Readonly<__VLS_Props_2> & Readonly<{
|
|
353
|
+
onSelect?: ((id: string) => any) | undefined;
|
|
354
|
+
}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLDivElement>;
|
|
355
|
+
|
|
356
|
+
/**
|
|
357
|
+
* Turn authored `<router-link>` into a real anchor (or an inert span).
|
|
358
|
+
*
|
|
359
|
+
* The close tag is matched to what the OPEN tag became, so a destination-less
|
|
360
|
+
* link closes `</span>` and not `</a>`: emitting the wrong closer leaves the
|
|
361
|
+
* span open and the browser swallows the rest of the paragraph into it.
|
|
362
|
+
*/
|
|
363
|
+
export declare function compileLinks(html: string): string;
|
|
364
|
+
|
|
91
365
|
export declare type Condition = {
|
|
92
366
|
kind: 'always';
|
|
93
367
|
} | {
|
|
@@ -122,6 +396,35 @@ export declare type Condition = {
|
|
|
122
396
|
*/
|
|
123
397
|
export declare const CORE_LOGIC_INPUTS: LogicInputDefinition[];
|
|
124
398
|
|
|
399
|
+
export declare function createCms(options: CmsClientOptions): CmsClient;
|
|
400
|
+
|
|
401
|
+
/**
|
|
402
|
+
* Declare a block's fields once and get both the runtime props and the type.
|
|
403
|
+
* `defineBlock<HeroFields>()` is the shorthand a product block uses when it also
|
|
404
|
+
* wants the field type exported for its schema.
|
|
405
|
+
*/
|
|
406
|
+
export declare function defineBlock<TFields extends Record<string, FieldValue>>(): {
|
|
407
|
+
block: {
|
|
408
|
+
type: PropType<TypedBlock<TFields>>;
|
|
409
|
+
required: true;
|
|
410
|
+
};
|
|
411
|
+
index: {
|
|
412
|
+
type: PropType<number>;
|
|
413
|
+
required: false;
|
|
414
|
+
default: number;
|
|
415
|
+
};
|
|
416
|
+
blocks: {
|
|
417
|
+
type: PropType<BlockInstance[]>;
|
|
418
|
+
required: false;
|
|
419
|
+
default: () => BlockInstance[];
|
|
420
|
+
};
|
|
421
|
+
context: {
|
|
422
|
+
type: PropType<unknown>;
|
|
423
|
+
required: false;
|
|
424
|
+
default: unknown;
|
|
425
|
+
};
|
|
426
|
+
};
|
|
427
|
+
|
|
125
428
|
/**
|
|
126
429
|
* Evaluates a Condition tree to a visibility boolean. `graphs` supplies the
|
|
127
430
|
* logic graphs referenced by { kind: 'graph' } conditions (stored on the page
|
|
@@ -132,6 +435,15 @@ export declare function evaluate(condition: Condition | undefined, env: LogicEnv
|
|
|
132
435
|
/** Evaluates the graph to the Visible sink's value, plus each node's output. */
|
|
133
436
|
export declare function evaluateGraph(graph: LogicGraph, env: LogicEnv): GraphResult;
|
|
134
437
|
|
|
438
|
+
export declare type FetchLike = (input: string, init?: {
|
|
439
|
+
cache?: RequestCache;
|
|
440
|
+
headers?: Record<string, string>;
|
|
441
|
+
}) => Promise<{
|
|
442
|
+
ok: boolean;
|
|
443
|
+
status: number;
|
|
444
|
+
json: () => Promise<unknown>;
|
|
445
|
+
}>;
|
|
446
|
+
|
|
135
447
|
/** A field's schema: what a Block declares it accepts. */
|
|
136
448
|
export declare interface FieldSchema {
|
|
137
449
|
type: FieldType;
|
|
@@ -166,6 +478,32 @@ export declare type FieldType = 'text' | 'richtext' | 'number' | 'boolean' | 'im
|
|
|
166
478
|
|
|
167
479
|
export declare type FieldValue = TRef | string | number | boolean | ImageValue | LinkValue;
|
|
168
480
|
|
|
481
|
+
/**
|
|
482
|
+
* The runtime props definition matching BlockComponentProps. Returned fresh on
|
|
483
|
+
* every call, because Vue mutates the object it is handed.
|
|
484
|
+
*/
|
|
485
|
+
export declare function getBlockComponentProps<TFields extends Record<string, FieldValue> = Record<string, FieldValue>, TContext = unknown>(): {
|
|
486
|
+
block: {
|
|
487
|
+
type: PropType<TypedBlock<TFields>>;
|
|
488
|
+
required: true;
|
|
489
|
+
};
|
|
490
|
+
index: {
|
|
491
|
+
type: PropType<number>;
|
|
492
|
+
required: false;
|
|
493
|
+
default: number;
|
|
494
|
+
};
|
|
495
|
+
blocks: {
|
|
496
|
+
type: PropType<BlockInstance[]>;
|
|
497
|
+
required: false;
|
|
498
|
+
default: () => BlockInstance[];
|
|
499
|
+
};
|
|
500
|
+
context: {
|
|
501
|
+
type: PropType<TContext>;
|
|
502
|
+
required: false;
|
|
503
|
+
default: TContext | undefined;
|
|
504
|
+
};
|
|
505
|
+
};
|
|
506
|
+
|
|
169
507
|
export declare interface GraphConnection {
|
|
170
508
|
fromNode: string;
|
|
171
509
|
fromPort: string;
|
|
@@ -178,6 +516,19 @@ export declare interface GraphResult {
|
|
|
178
516
|
nodeOut: Record<string, boolean>;
|
|
179
517
|
}
|
|
180
518
|
|
|
519
|
+
/** Whether a field value is an image the renderer can draw. */
|
|
520
|
+
export declare function hasImage(value: FieldValue | unknown): boolean;
|
|
521
|
+
|
|
522
|
+
/**
|
|
523
|
+
* Adopt the server's partials before the app mounts, so hydration matches the
|
|
524
|
+
* HTML exactly and no fetch is issued.
|
|
525
|
+
*
|
|
526
|
+
* Skipped in edit mode on purpose: the canvas is meant to show the DRAFT and to
|
|
527
|
+
* take live patches from the console, so it must fetch for itself rather than
|
|
528
|
+
* inherit the published documents the server render resolved.
|
|
529
|
+
*/
|
|
530
|
+
export declare function hydrateCmsPartials(raw: unknown, client?: CmsClient | null): void;
|
|
531
|
+
|
|
181
532
|
export declare interface ImageValue {
|
|
182
533
|
src: string;
|
|
183
534
|
alt?: TRef;
|
|
@@ -194,12 +545,97 @@ export declare interface ImageValue {
|
|
|
194
545
|
*/
|
|
195
546
|
export declare type InputResolver = (params: Record<string, unknown> | undefined, op: Op | undefined, value: unknown) => boolean;
|
|
196
547
|
|
|
548
|
+
/** Whether an authored value carries markup, or is one plain paragraph of text. */
|
|
549
|
+
export declare function isHtml(value: string): boolean;
|
|
550
|
+
|
|
197
551
|
export declare function isImage(v: unknown): v is ImageValue;
|
|
198
552
|
|
|
553
|
+
/** A route the host app can navigate to in place: site-absolute, not protocol-relative. */
|
|
554
|
+
export declare function isInternalHref(href: string): boolean;
|
|
555
|
+
|
|
199
556
|
export declare function isLink(v: unknown): v is LinkValue;
|
|
200
557
|
|
|
558
|
+
/**
|
|
559
|
+
* True when a live-preview patch is carrying THIS partial rather than a page.
|
|
560
|
+
*
|
|
561
|
+
* The console posts whichever document it currently has open. A page document
|
|
562
|
+
* is addressed by a route (always '/'-prefixed); a partial is addressed by its
|
|
563
|
+
* key. Every marker delivery or the console might use is accepted, and the
|
|
564
|
+
* '/'-prefix rule is the backstop, so a footer patch is never mistaken for a
|
|
565
|
+
* page (which would replace the page body with the footer) and a page patch is
|
|
566
|
+
* never mistaken for the footer.
|
|
567
|
+
*/
|
|
568
|
+
export declare function isPartialDocument(doc: unknown, key?: string): boolean;
|
|
569
|
+
|
|
570
|
+
/** True in any non-browser render (a Worker isolate, Node, a test). */
|
|
571
|
+
export declare function isServerRender(): boolean;
|
|
572
|
+
|
|
201
573
|
export declare function isTRef(v: unknown): v is TRef;
|
|
202
574
|
|
|
575
|
+
/**
|
|
576
|
+
* The attributes an anchor needs, or NOTHING when the link is inert.
|
|
577
|
+
*
|
|
578
|
+
* Binding this with `v-bind` on a `<component :is="linkTag(link)">` is the whole
|
|
579
|
+
* of rule 2: an inert link gets no `href`, no `target` and no `rel`, so it
|
|
580
|
+
* renders as the label in plain text.
|
|
581
|
+
*/
|
|
582
|
+
export declare function linkAttrs(link: ResolvedLink): Record<string, string>;
|
|
583
|
+
|
|
584
|
+
/** The class that paints an inert link as body copy rather than as a link. */
|
|
585
|
+
export declare function linkClass(link: ResolvedLink): string;
|
|
586
|
+
|
|
587
|
+
export declare type LinkKind = 'doc' | 'url' | 'media' | 'none';
|
|
588
|
+
|
|
589
|
+
/**
|
|
590
|
+
* The `link` field, generalised out of the site that first shipped it.
|
|
591
|
+
*
|
|
592
|
+
* A link used to be a raw href typed as a free string, so a typo was a silent
|
|
593
|
+
* 404, renaming a route broke every href pointing at it, and nothing stopped an
|
|
594
|
+
* editor linking to a page that is deliberately held back. The CMS models a
|
|
595
|
+
* link as an object and DELIVERY RESOLVES IT server side, so a renderer needs no
|
|
596
|
+
* resolver of its own:
|
|
597
|
+
*
|
|
598
|
+
* { "kind": "doc", "route": "/docs", "href": "/docs", "status": "ok" }
|
|
599
|
+
* { "kind": "url", "url": "https://…", "newTab": true }
|
|
600
|
+
* { "kind": "media", "id": "<media id>", "href": "https://…/asset.pdf", "newTab": true }
|
|
601
|
+
*
|
|
602
|
+
* `newTab` is authored on ANY of the three kinds. It is orthogonal to `status`:
|
|
603
|
+
* a link that is not 'ok' renders inert whatever the editor asked for, because
|
|
604
|
+
* there is no destination to open in either tab.
|
|
605
|
+
*
|
|
606
|
+
* `status` is delivery's verdict on a `doc` reference against the SAME site and
|
|
607
|
+
* environment: 'ok', 'missing' (no document for that route) or 'unpublished'
|
|
608
|
+
* (the document exists but is not visible to this caller).
|
|
609
|
+
*
|
|
610
|
+
* Two rules this module exists to enforce, in ONE place rather than in each of
|
|
611
|
+
* the fields a product renders as a link:
|
|
612
|
+
*
|
|
613
|
+
* 1. BACKWARD COMPATIBILITY. Documents in the wild still hold plain strings,
|
|
614
|
+
* and a document is migrated when it is migrated. A bare string is
|
|
615
|
+
* therefore a first-class input: a leading '/' reads as an internal route,
|
|
616
|
+
* anything else as an external URL. Nothing may 404 or render blank because
|
|
617
|
+
* a document has not been migrated yet.
|
|
618
|
+
*
|
|
619
|
+
* 2. A LINK THAT IS NOT 'ok' RENDERS INERT. The label still shows, as plain
|
|
620
|
+
* text, never as a dead anchor. This is what stops a held-back page (an
|
|
621
|
+
* unreleased product, say) leaking through a link on a page that IS live:
|
|
622
|
+
* the URL never reaches the markup at all, so it cannot be read out of the
|
|
623
|
+
* rendered HTML either.
|
|
624
|
+
*/
|
|
625
|
+
/** Delivery's verdict, plus the two verdicts a renderer reaches on its own. */
|
|
626
|
+
export declare type LinkStatus = 'ok'
|
|
627
|
+
/** No document for that route. */
|
|
628
|
+
| 'missing'
|
|
629
|
+
/** The document exists but is not published (or not visible to this caller). */
|
|
630
|
+
| 'unpublished'
|
|
631
|
+
/** Nothing authored at all. */
|
|
632
|
+
| 'empty'
|
|
633
|
+
/** A reference delivery did not resolve (a media id with no asset URL). */
|
|
634
|
+
| 'unresolved';
|
|
635
|
+
|
|
636
|
+
/** The tag an anchor slot should render: a real link, or plain text. */
|
|
637
|
+
export declare function linkTag(link: ResolvedLink): 'a' | 'span';
|
|
638
|
+
|
|
203
639
|
export declare interface LinkValue {
|
|
204
640
|
href: string;
|
|
205
641
|
label?: TRef;
|
|
@@ -266,6 +702,24 @@ declare interface NodeSpec {
|
|
|
266
702
|
param?: 'flag' | 'environment' | 'region';
|
|
267
703
|
}
|
|
268
704
|
|
|
705
|
+
/** The node type a tag maps to, so serializers are named by meaning, not by tag. */
|
|
706
|
+
export declare function nodeTypeOf(tag: string): RichTextNodeType;
|
|
707
|
+
|
|
708
|
+
/**
|
|
709
|
+
* Normalise ANY authored image value. `messages` resolves a `{ $t }` alt;
|
|
710
|
+
* `fallback` is the host's own bundled asset, used only when nothing is
|
|
711
|
+
* authored, so a half-authored document still renders a complete page.
|
|
712
|
+
*/
|
|
713
|
+
export declare function normalizeImage(value: unknown, messages?: Record<string, string>, fallback?: string | ResolvedImage): ResolvedImage;
|
|
714
|
+
|
|
715
|
+
/**
|
|
716
|
+
* Normalise ANY authored link value: the object shape, a legacy bare string, or
|
|
717
|
+
* nothing at all. `fallback` is the host's own bundled href, used only when the
|
|
718
|
+
* document carries nothing (blocks often keep a coded default so a
|
|
719
|
+
* half-authored document still renders a complete page).
|
|
720
|
+
*/
|
|
721
|
+
export declare function normalizeLink(value: unknown, fallback?: string): ResolvedLink;
|
|
722
|
+
|
|
269
723
|
/**
|
|
270
724
|
* Logic contract: visibility and variation conditions.
|
|
271
725
|
*
|
|
@@ -296,6 +750,18 @@ export declare interface PageDocument {
|
|
|
296
750
|
graphs?: Record<string, LogicGraph>;
|
|
297
751
|
}
|
|
298
752
|
|
|
753
|
+
/** The first alias that is filled, for documents that spell a field several ways. */
|
|
754
|
+
export declare function pickField(source: Record<string, unknown> | undefined, aliases: readonly string[]): unknown;
|
|
755
|
+
|
|
756
|
+
/** The link under the first accepted spelling that is filled. */
|
|
757
|
+
export declare function pickLink(source: Record<string, unknown> | undefined, aliases: readonly string[], fallback?: string): ResolvedLink;
|
|
758
|
+
|
|
759
|
+
/** The default preview source: the canvas's own query string. */
|
|
760
|
+
export declare function readPreviewFromLocation(): CmsPreview;
|
|
761
|
+
|
|
762
|
+
/** Test/dev helper: forget the memoised partials so the next call refetches. */
|
|
763
|
+
export declare function resetCmsPartials(): void;
|
|
764
|
+
|
|
299
765
|
/**
|
|
300
766
|
* Where a logic input can be evaluated. This is load-bearing for delivery:
|
|
301
767
|
* - `build` inputs (flag, environment, locale) let a gated block prerender.
|
|
@@ -305,6 +771,92 @@ export declare interface PageDocument {
|
|
|
305
771
|
*/
|
|
306
772
|
export declare type ResolveAt = 'build' | 'request';
|
|
307
773
|
|
|
774
|
+
export declare interface ResolvedImage {
|
|
775
|
+
/** '' when nothing is authored, which is the caller's signal to render nothing. */
|
|
776
|
+
src: string;
|
|
777
|
+
/** Always a string. '' means decorative, and must still reach the markup as alt="". */
|
|
778
|
+
alt: string;
|
|
779
|
+
width?: number;
|
|
780
|
+
height?: number;
|
|
781
|
+
}
|
|
782
|
+
|
|
783
|
+
/**
|
|
784
|
+
* An authored link, normalised. Named `ResolvedLink` rather than `CmsLink`
|
|
785
|
+
* because `CmsLink` is the component that renders one.
|
|
786
|
+
*/
|
|
787
|
+
export declare interface ResolvedLink {
|
|
788
|
+
/** True when this may render as a real anchor. False means render it inert. */
|
|
789
|
+
ok: boolean;
|
|
790
|
+
/** Where it points. Always '' when `ok` is false, so it cannot leak. */
|
|
791
|
+
href: string;
|
|
792
|
+
/** True when `href` is a route the host app owns, so its router should take it. */
|
|
793
|
+
internal: boolean;
|
|
794
|
+
/**
|
|
795
|
+
* Whether it should open in a new tab. Authored per link, for ALL THREE
|
|
796
|
+
* kinds: an editor can send an internal page to a new tab just as easily as
|
|
797
|
+
* an external URL, and a linked PDF in the media library is the case that
|
|
798
|
+
* made this matter. Never true for a destination that must open in place
|
|
799
|
+
* (#anchor, mailto:, tel:), where a new tab would leave an empty one behind.
|
|
800
|
+
*/
|
|
801
|
+
newTab: boolean;
|
|
802
|
+
status: LinkStatus;
|
|
803
|
+
kind: LinkKind;
|
|
804
|
+
}
|
|
805
|
+
|
|
806
|
+
/** The node a serializer is handed. `attrs` are the authored attributes, as written. */
|
|
807
|
+
export declare interface RichTextNode {
|
|
808
|
+
type: RichTextNodeType;
|
|
809
|
+
/** The authored tag name, lowercased. */
|
|
810
|
+
tag: string;
|
|
811
|
+
attrs: Record<string, string>;
|
|
812
|
+
}
|
|
813
|
+
|
|
814
|
+
/**
|
|
815
|
+
* Richtext: authored HTML, and the one hook a product needs to style it.
|
|
816
|
+
*
|
|
817
|
+
* The CMS stores a richtext field as HTML written by an editor. A renderer
|
|
818
|
+
* inserts it (Vue: `v-html`), which is why two things live here rather than in
|
|
819
|
+
* each product's blocks:
|
|
820
|
+
*
|
|
821
|
+
* 1. `compileLinks`, because inserted markup is NOT compiled. A document that
|
|
822
|
+
* authored `<router-link to="/x">` would otherwise render the literal
|
|
823
|
+
* element and vanish; it becomes a real `<a href>`, and CmsRichText's
|
|
824
|
+
* delegated click handler gives it SPA navigation. A `router-link` with no
|
|
825
|
+
* destination becomes a `<span>`: the label renders, never a dead anchor,
|
|
826
|
+
* the same rule the link field enforces everywhere else.
|
|
827
|
+
*
|
|
828
|
+
* 2. `applySerializers`, the equivalent of Prismic's rich text serializers. A
|
|
829
|
+
* product styles its own headings, paragraphs and quotes by naming a class
|
|
830
|
+
* (or rewriting the tag) per node type, instead of forking the component.
|
|
831
|
+
*
|
|
832
|
+
* WHAT A SERIALIZER CAN DO, precisely: it rewrites an element's OPEN TAG (its
|
|
833
|
+
* tag name, its classes, its attributes). The children are passed through
|
|
834
|
+
* untouched, and a renamed tag has its matching close tag renamed with it. It
|
|
835
|
+
* cannot restructure a subtree (wrapping a blockquote's text in an extra
|
|
836
|
+
* paragraph, say) because the input is HTML rather than a node tree. A product
|
|
837
|
+
* that needs that keeps its own transform and passes the result in as `html`.
|
|
838
|
+
*/
|
|
839
|
+
export declare type RichTextNodeType = 'paragraph' | 'heading1' | 'heading2' | 'heading3' | 'heading4' | 'heading5' | 'heading6' | 'list' | 'oList' | 'listItem' | 'quote' | 'preformatted' | 'code' | 'hyperlink' | 'image' | 'strong' | 'em' | 'span' | 'break' | 'table' | 'row' | 'cell' | 'other';
|
|
840
|
+
|
|
841
|
+
/** What a serializer may return. Returning nothing leaves the element alone. */
|
|
842
|
+
export declare interface RichTextRewrite {
|
|
843
|
+
/** Render as a different element. The matching close tag is renamed too. */
|
|
844
|
+
tag?: string;
|
|
845
|
+
/** Classes to ADD to whatever the element already carries. */
|
|
846
|
+
class?: string;
|
|
847
|
+
/** Attributes to set (or, with an empty string, to leave as-is). */
|
|
848
|
+
attrs?: Record<string, string>;
|
|
849
|
+
}
|
|
850
|
+
|
|
851
|
+
/**
|
|
852
|
+
* A serializer for one node type. The string form is the common case: classes
|
|
853
|
+
* to add. The function form returns a rewrite, or a raw open tag if a product
|
|
854
|
+
* wants full control (its close tag then keeps the authored tag name).
|
|
855
|
+
*/
|
|
856
|
+
export declare type RichTextSerializer = string | ((node: RichTextNode) => RichTextRewrite | string | void);
|
|
857
|
+
|
|
858
|
+
export declare type RichTextSerializers = Partial<Record<RichTextNodeType, RichTextSerializer>>;
|
|
859
|
+
|
|
308
860
|
/** A named region inside a composed block that nests other blocks. */
|
|
309
861
|
export declare interface SlotSchema {
|
|
310
862
|
label: string;
|
|
@@ -312,6 +864,13 @@ export declare interface SlotSchema {
|
|
|
312
864
|
allow?: string[];
|
|
313
865
|
}
|
|
314
866
|
|
|
867
|
+
/**
|
|
868
|
+
* Everything resolved so far, for the server render to serialise. Call it after
|
|
869
|
+
* renderToString, so every partial an awaited prefetch resolved is in. Pass the
|
|
870
|
+
* app instance: on the server that is where the states live.
|
|
871
|
+
*/
|
|
872
|
+
export declare function snapshotCmsPartials(app?: unknown): Record<string, CmsPartialSnapshot>;
|
|
873
|
+
|
|
315
874
|
/**
|
|
316
875
|
* Resolves a field value to display text. String refs ({ $t }) resolve from the
|
|
317
876
|
* provided message table (Verba / locale JSON), falling back to the key so a
|
|
@@ -332,6 +891,48 @@ export declare interface TRef {
|
|
|
332
891
|
$t: string;
|
|
333
892
|
}
|
|
334
893
|
|
|
894
|
+
/** A block instance narrowed to the fields one block type declares. */
|
|
895
|
+
export declare interface TypedBlock<TFields extends Record<string, FieldValue> = Record<string, FieldValue>> extends BlockInstance {
|
|
896
|
+
fields: TFields;
|
|
897
|
+
}
|
|
898
|
+
|
|
899
|
+
/**
|
|
900
|
+
* The configured client, or null when the host never installed one. Null is a
|
|
901
|
+
* supported state: the primitives fall back to plain anchors and coded content,
|
|
902
|
+
* which is what lets a product adopt them one component at a time.
|
|
903
|
+
*/
|
|
904
|
+
export declare function useCms(): CmsClient | null;
|
|
905
|
+
|
|
906
|
+
/** The same, but for code that cannot proceed without configuration. */
|
|
907
|
+
export declare function useCmsOrThrow(): CmsClient;
|
|
908
|
+
|
|
909
|
+
export declare interface UseCmsPage {
|
|
910
|
+
doc: Ref<CmsPageDocument | null>;
|
|
911
|
+
error: Ref<string | null>;
|
|
912
|
+
outcome: Ref<CmsOutcome>;
|
|
913
|
+
loading: Ref<boolean>;
|
|
914
|
+
load: () => Promise<void>;
|
|
915
|
+
}
|
|
916
|
+
|
|
917
|
+
export declare function useCmsPage(route: string, client?: CmsClient | null): UseCmsPage;
|
|
918
|
+
|
|
919
|
+
export declare interface UseCmsPartial {
|
|
920
|
+
doc: Ref<CmsPartialDocument | null>;
|
|
921
|
+
messages: Ref<Record<string, string>>;
|
|
922
|
+
error: Ref<string | null>;
|
|
923
|
+
loading: Ref<boolean>;
|
|
924
|
+
/** Await the first load, so a server render emits the partial, not the fallback. */
|
|
925
|
+
whenReady: () => Promise<void>;
|
|
926
|
+
}
|
|
927
|
+
|
|
928
|
+
/**
|
|
929
|
+
* The 'footer' partial (or any other key), shared across the whole app load.
|
|
930
|
+
* `doc` is null whenever the partial is unavailable for ANY reason: partials are
|
|
931
|
+
* off, the endpoint 404s, the CMS is unreachable, or the document is empty.
|
|
932
|
+
* Callers render their coded fallback in that case.
|
|
933
|
+
*/
|
|
934
|
+
export declare function useCmsPartial(key: string, client?: CmsClient | null): UseCmsPartial;
|
|
935
|
+
|
|
335
936
|
/** Small helper for block components: resolve a field value to display text. */
|
|
336
937
|
export declare function useField(): {
|
|
337
938
|
t: (value: FieldValue | undefined) => string;
|