@nubisco/cms-vue 1.2.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/index.d.ts CHANGED
@@ -1,9 +1,17 @@
1
+ import { App } from 'vue';
1
2
  import { Component } from 'vue';
2
3
  import { ComponentOptionsMixin } from 'vue';
3
4
  import { ComponentProvideOptions } from 'vue';
5
+ import { ComputedRef } from 'vue';
4
6
  import { DefineComponent } from 'vue';
5
7
  import { InjectionKey } from 'vue';
8
+ import { PropType } from 'vue';
6
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>;
7
15
 
8
16
  declare type __VLS_Props = {
9
17
  block: BlockInstance;
@@ -18,11 +26,113 @@ declare type __VLS_Props_2 = {
18
26
  editing?: boolean;
19
27
  selectedId?: string | null;
20
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;
21
39
  setText?: (block: BlockInstance, field: string, current: FieldValue | undefined, next: string) => void;
22
40
  };
23
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
+
24
124
  export declare type BlockCategory = 'content' | 'media' | 'form' | 'layout';
25
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
+
26
136
  /**
27
137
  * A block type definition, registered once. The editor catalog, the inspector
28
138
  * fields, validation, and serialization all derive from this, mirroring how the
@@ -82,8 +192,71 @@ export declare interface BlueprintCard {
82
192
  };
83
193
  }
84
194
 
195
+ export declare const CMS_CLIENT: InjectionKey<CmsClient>;
196
+
85
197
  export declare const CMS_CONTEXT: InjectionKey<CmsContext>;
86
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
+
87
260
  /**
88
261
  * Render context provided by CmsZone and injected by field primitives. It
89
262
  * carries the string table (for { $t } refs), whether edit mode is on, and the
@@ -96,6 +269,80 @@ export declare interface CmsContext {
96
269
  setText: (block: BlockInstance, field: string, current: FieldValue | undefined, next: string) => void;
97
270
  }
98
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
+
99
346
  export declare const CmsText: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
100
347
  el: HTMLSpanElement;
101
348
  }, any>;
@@ -106,6 +353,15 @@ select: (id: string) => any;
106
353
  onSelect?: ((id: string) => any) | undefined;
107
354
  }>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLDivElement>;
108
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
+
109
365
  export declare type Condition = {
110
366
  kind: 'always';
111
367
  } | {
@@ -140,6 +396,35 @@ export declare type Condition = {
140
396
  */
141
397
  export declare const CORE_LOGIC_INPUTS: LogicInputDefinition[];
142
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
+
143
428
  /**
144
429
  * Evaluates a Condition tree to a visibility boolean. `graphs` supplies the
145
430
  * logic graphs referenced by { kind: 'graph' } conditions (stored on the page
@@ -150,6 +435,15 @@ export declare function evaluate(condition: Condition | undefined, env: LogicEnv
150
435
  /** Evaluates the graph to the Visible sink's value, plus each node's output. */
151
436
  export declare function evaluateGraph(graph: LogicGraph, env: LogicEnv): GraphResult;
152
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
+
153
447
  /** A field's schema: what a Block declares it accepts. */
154
448
  export declare interface FieldSchema {
155
449
  type: FieldType;
@@ -184,6 +478,32 @@ export declare type FieldType = 'text' | 'richtext' | 'number' | 'boolean' | 'im
184
478
 
185
479
  export declare type FieldValue = TRef | string | number | boolean | ImageValue | LinkValue;
186
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
+
187
507
  export declare interface GraphConnection {
188
508
  fromNode: string;
189
509
  fromPort: string;
@@ -196,6 +516,19 @@ export declare interface GraphResult {
196
516
  nodeOut: Record<string, boolean>;
197
517
  }
198
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
+
199
532
  export declare interface ImageValue {
200
533
  src: string;
201
534
  alt?: TRef;
@@ -212,12 +545,97 @@ export declare interface ImageValue {
212
545
  */
213
546
  export declare type InputResolver = (params: Record<string, unknown> | undefined, op: Op | undefined, value: unknown) => boolean;
214
547
 
548
+ /** Whether an authored value carries markup, or is one plain paragraph of text. */
549
+ export declare function isHtml(value: string): boolean;
550
+
215
551
  export declare function isImage(v: unknown): v is ImageValue;
216
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
+
217
556
  export declare function isLink(v: unknown): v is LinkValue;
218
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
+
219
573
  export declare function isTRef(v: unknown): v is TRef;
220
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
+
221
639
  export declare interface LinkValue {
222
640
  href: string;
223
641
  label?: TRef;
@@ -284,6 +702,24 @@ declare interface NodeSpec {
284
702
  param?: 'flag' | 'environment' | 'region';
285
703
  }
286
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
+
287
723
  /**
288
724
  * Logic contract: visibility and variation conditions.
289
725
  *
@@ -314,6 +750,18 @@ export declare interface PageDocument {
314
750
  graphs?: Record<string, LogicGraph>;
315
751
  }
316
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
+
317
765
  /**
318
766
  * Where a logic input can be evaluated. This is load-bearing for delivery:
319
767
  * - `build` inputs (flag, environment, locale) let a gated block prerender.
@@ -323,6 +771,92 @@ export declare interface PageDocument {
323
771
  */
324
772
  export declare type ResolveAt = 'build' | 'request';
325
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
+
326
860
  /** A named region inside a composed block that nests other blocks. */
327
861
  export declare interface SlotSchema {
328
862
  label: string;
@@ -330,6 +864,13 @@ export declare interface SlotSchema {
330
864
  allow?: string[];
331
865
  }
332
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
+
333
874
  /**
334
875
  * Resolves a field value to display text. String refs ({ $t }) resolve from the
335
876
  * provided message table (Verba / locale JSON), falling back to the key so a
@@ -350,6 +891,48 @@ export declare interface TRef {
350
891
  $t: string;
351
892
  }
352
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
+
353
936
  /** Small helper for block components: resolve a field value to display text. */
354
937
  export declare function useField(): {
355
938
  t: (value: FieldValue | undefined) => string;