@decocms/blocks 8.5.2 → 8.7.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.
Files changed (126) hide show
  1. package/dist/async/default.d.ts +10 -0
  2. package/dist/async/default.d.ts.map +1 -0
  3. package/dist/async/default.js +5 -0
  4. package/dist/async/default.js.map +1 -0
  5. package/dist/async/node.d.ts +3 -0
  6. package/dist/async/node.d.ts.map +1 -0
  7. package/dist/async/node.js +11 -0
  8. package/dist/async/node.js.map +1 -0
  9. package/dist/async/types.d.ts +6 -0
  10. package/dist/async/types.d.ts.map +1 -0
  11. package/dist/async/types.js +2 -0
  12. package/dist/async/types.js.map +1 -0
  13. package/dist/index.d.ts +1 -1
  14. package/dist/index.d.ts.map +1 -1
  15. package/dist/index.js +1 -1
  16. package/dist/index.js.map +1 -1
  17. package/dist/v8/bucketing.d.ts +24 -0
  18. package/dist/v8/bucketing.d.ts.map +1 -0
  19. package/dist/v8/bucketing.js +78 -0
  20. package/dist/v8/bucketing.js.map +1 -0
  21. package/dist/v8/builtins/campaigns.d.ts +36 -0
  22. package/dist/v8/builtins/campaigns.d.ts.map +1 -0
  23. package/dist/v8/builtins/campaigns.js +107 -0
  24. package/dist/v8/builtins/campaigns.js.map +1 -0
  25. package/dist/v8/builtins/data.d.ts +2 -2
  26. package/dist/v8/builtins/data.js +2 -2
  27. package/dist/v8/builtins/experiments.d.ts +27 -0
  28. package/dist/v8/builtins/experiments.d.ts.map +1 -0
  29. package/dist/v8/builtins/experiments.js +62 -0
  30. package/dist/v8/builtins/experiments.js.map +1 -0
  31. package/dist/v8/builtins/index.d.ts.map +1 -1
  32. package/dist/v8/builtins/index.js +7 -2
  33. package/dist/v8/builtins/index.js.map +1 -1
  34. package/dist/v8/builtins/matchers.d.ts +0 -14
  35. package/dist/v8/builtins/matchers.d.ts.map +1 -1
  36. package/dist/v8/builtins/matchers.js +0 -19
  37. package/dist/v8/builtins/matchers.js.map +1 -1
  38. package/dist/v8/cli/builtins.d.ts +6 -0
  39. package/dist/v8/cli/builtins.d.ts.map +1 -1
  40. package/dist/v8/cli/builtins.js +19 -0
  41. package/dist/v8/cli/builtins.js.map +1 -1
  42. package/dist/v8/cli/check/index.d.ts.map +1 -1
  43. package/dist/v8/cli/check/index.js +231 -8
  44. package/dist/v8/cli/check/index.js.map +1 -1
  45. package/dist/v8/cli/schema/builtinSchemas.d.ts.map +1 -1
  46. package/dist/v8/cli/schema/builtinSchemas.js +76 -21
  47. package/dist/v8/cli/schema/builtinSchemas.js.map +1 -1
  48. package/dist/v8/cli/schema/generate.d.ts.map +1 -1
  49. package/dist/v8/cli/schema/generate.js +48 -2
  50. package/dist/v8/cli/schema/generate.js.map +1 -1
  51. package/dist/v8/client.d.ts +25 -0
  52. package/dist/v8/client.d.ts.map +1 -1
  53. package/dist/v8/client.js +58 -10
  54. package/dist/v8/client.js.map +1 -1
  55. package/dist/v8/cms.d.ts.map +1 -1
  56. package/dist/v8/cms.js +113 -44
  57. package/dist/v8/cms.js.map +1 -1
  58. package/dist/v8/content.d.ts +80 -1
  59. package/dist/v8/content.d.ts.map +1 -1
  60. package/dist/v8/content.js +149 -4
  61. package/dist/v8/content.js.map +1 -1
  62. package/dist/v8/current.d.ts +28 -0
  63. package/dist/v8/current.d.ts.map +1 -0
  64. package/dist/v8/current.js +77 -0
  65. package/dist/v8/current.js.map +1 -0
  66. package/dist/v8/draft.d.ts +40 -21
  67. package/dist/v8/draft.d.ts.map +1 -1
  68. package/dist/v8/draft.js +160 -25
  69. package/dist/v8/draft.js.map +1 -1
  70. package/dist/v8/experiments.d.ts +107 -0
  71. package/dist/v8/experiments.d.ts.map +1 -0
  72. package/dist/v8/experiments.js +292 -0
  73. package/dist/v8/experiments.js.map +1 -0
  74. package/dist/v8/hosts.d.ts +3 -2
  75. package/dist/v8/hosts.d.ts.map +1 -1
  76. package/dist/v8/hosts.js +3 -2
  77. package/dist/v8/hosts.js.map +1 -1
  78. package/dist/v8/index.d.ts +7 -5
  79. package/dist/v8/index.d.ts.map +1 -1
  80. package/dist/v8/index.js +6 -4
  81. package/dist/v8/index.js.map +1 -1
  82. package/dist/v8/preview/DraftBadge.d.ts +9 -1
  83. package/dist/v8/preview/DraftBadge.d.ts.map +1 -1
  84. package/dist/v8/preview/DraftBadge.js +42 -2
  85. package/dist/v8/preview/DraftBadge.js.map +1 -1
  86. package/dist/v8/remoteLoader.d.ts.map +1 -1
  87. package/dist/v8/remoteLoader.js +169 -21
  88. package/dist/v8/remoteLoader.js.map +1 -1
  89. package/dist/v8/resolver.d.ts +4 -2
  90. package/dist/v8/resolver.d.ts.map +1 -1
  91. package/dist/v8/resolver.js +11 -3
  92. package/dist/v8/resolver.js.map +1 -1
  93. package/dist/v8/settings.d.ts +16 -4
  94. package/dist/v8/settings.d.ts.map +1 -1
  95. package/dist/v8/settings.js +24 -21
  96. package/dist/v8/settings.js.map +1 -1
  97. package/dist/v8/types.d.ts +162 -22
  98. package/dist/v8/types.d.ts.map +1 -1
  99. package/package.json +35 -1
  100. package/src/async/default.ts +13 -0
  101. package/src/async/node.ts +12 -0
  102. package/src/async/types.ts +5 -0
  103. package/src/index.ts +4 -0
  104. package/src/v8/bucketing.ts +88 -0
  105. package/src/v8/builtins/campaigns.ts +120 -0
  106. package/src/v8/builtins/data.ts +2 -2
  107. package/src/v8/builtins/experiments.ts +72 -0
  108. package/src/v8/builtins/index.ts +7 -2
  109. package/src/v8/builtins/matchers.ts +0 -26
  110. package/src/v8/cli/builtins.ts +23 -0
  111. package/src/v8/cli/check/index.ts +289 -8
  112. package/src/v8/cli/schema/builtinSchemas.ts +82 -22
  113. package/src/v8/cli/schema/generate.ts +48 -3
  114. package/src/v8/client.ts +76 -10
  115. package/src/v8/cms.ts +134 -45
  116. package/src/v8/content.ts +168 -4
  117. package/src/v8/current.ts +98 -0
  118. package/src/v8/draft.ts +170 -30
  119. package/src/v8/experiments.ts +340 -0
  120. package/src/v8/hosts.ts +3 -2
  121. package/src/v8/index.ts +8 -4
  122. package/src/v8/preview/DraftBadge.tsx +72 -2
  123. package/src/v8/remoteLoader.ts +193 -26
  124. package/src/v8/resolver.ts +14 -4
  125. package/src/v8/settings.ts +35 -29
  126. package/src/v8/types.ts +163 -20
package/src/v8/types.ts CHANGED
@@ -3,6 +3,7 @@
3
3
  * (`/next/api-reference#types`) — every type here is documented there.
4
4
  */
5
5
  import type { ReactNode } from "react";
6
+ import type { Assignments, Visitor } from "./experiments.ts";
6
7
 
7
8
  // ---------------------------------------------------------------------------
8
9
  // Blocks and content
@@ -41,6 +42,13 @@ export type Snapshot = {
41
42
  * module, a build outside git), the bundled content counts as the oldest.
42
43
  */
43
44
  committedAt?: string;
45
+ /**
46
+ * The hosts this release may be previewed on (host patterns), as Studio
47
+ * wrote them into the release metadata on delivery.decocms.com
48
+ * (`latest.json` and `revisions/<sha>.json`). Previews are checked against
49
+ * the current release's list; the bundled content has none.
50
+ */
51
+ previewHosts?: string[];
44
52
  };
45
53
 
46
54
  /**
@@ -99,10 +107,14 @@ export interface Seo {
99
107
  description: string;
100
108
  }
101
109
 
102
- /** The built-in `page` block, resolved: without `seo`, the site's defaults apply. */
103
- export interface Page extends Route {
110
+ /**
111
+ * The built-in `page` block, resolved: without `seo`, the site's defaults
112
+ * apply. Its sections are whatever its section blocks return: React
113
+ * elements by default, or a site's descriptors (`Page<{ component, props }>`).
114
+ */
115
+ export interface Page<Section = ReactNode> extends Route {
104
116
  seo?: Seo;
105
- sections: ReactNode[];
117
+ sections: Section[];
106
118
  }
107
119
 
108
120
  /** The built-in `redirect` block. */
@@ -158,15 +170,20 @@ export interface Variant<T> {
158
170
  * caps (see /next/built-in-blocks#cms-settings).
159
171
  */
160
172
  export interface CMSSettings {
161
- /** Host patterns previews are allowed on, within `createCMS`'s `preview.hosts`. */
162
- preview?: { hosts?: string[] };
163
173
  telemetry?: Telemetry;
164
174
  analytics?: Analytics;
165
175
  }
166
176
 
167
177
  /** What `cms.settings()` returns: every section, defaults filled in, caps applied. */
168
178
  export interface EffectiveSettings {
169
- /** `["*"]` means every host; an empty list, none. */
179
+ /**
180
+ * The hosts previews are allowed on, as known in memory: the current
181
+ * release's `previewHosts` (Studio writes them into the release metadata)
182
+ * plus `createCMS`'s `preview.hosts`. A site with no list published (no
183
+ * `latest.json` yet, or one without `previewHosts`) and content with no
184
+ * remote site and no `preview.hosts` give `["*"]`, every host; an empty
185
+ * list, none (as before this process has read the release metadata).
186
+ */
170
187
  preview: { hosts: string[] };
171
188
  telemetry: Required<Telemetry>;
172
189
  analytics: Required<Analytics>;
@@ -266,8 +283,12 @@ export interface CMSConfig {
266
283
  telemetry?: false | TelemetryConfig;
267
284
  preview?: {
268
285
  /**
269
- * The most content may allow previews on, in the host pattern format
270
- * (/next/api-reference#host-patterns). Without it, content may allow any host.
286
+ * Hosts previews are allowed on besides the release's own (Studio writes
287
+ * those into the release metadata), in the host pattern format
288
+ * (/next/api-reference#host-patterns). Without `site`, the only list:
289
+ * left out, previews are allowed on every host. With `site`, it adds to
290
+ * the release's list; a site with no list published previews on every
291
+ * host anyway.
271
292
  */
272
293
  hosts?: string[];
273
294
  /**
@@ -304,13 +325,14 @@ export interface ListOptions<T> {
304
325
  }
305
326
 
306
327
  /**
307
- * Reads one revision for one request.
328
+ * Reads one revision for one request, for one visitor, at one moment.
308
329
  *
309
330
  * Results are read-only. A client runs each block function once per distinct
310
331
  * input, so the same block at two places in a request hands both places the
311
332
  * same object; mutating it in place changes the other occurrence too. Copy a
312
333
  * result before changing it. (The memo belongs to one client, so nothing is
313
- * shared across requests.)
334
+ * shared across requests; it is also why tests and campaigns are decided once
335
+ * per client, however many rules ask.)
314
336
  */
315
337
  export interface Client {
316
338
  resolve<T = unknown>(target: unknown, options?: ResolveOptions): Promise<Result<T>>;
@@ -321,18 +343,120 @@ export interface Client {
321
343
  * can't load, since there is no revision to report.
322
344
  */
323
345
  revision(): Promise<string>;
346
+ /** Who is visiting, as passed to `cms.client()` (a frozen copy); `null` for none. */
347
+ readonly visitor: Visitor | null;
348
+ /**
349
+ * The version it reads: the release's commit SHA, or the draft pointer, as
350
+ * passed to `cms.client()`. For the current release, the SHA of the release
351
+ * it loaded (`undefined` until its first `resolve`, `list` or `revision()`).
352
+ */
353
+ readonly version: string | undefined;
354
+ /** The date campaigns run at: the one passed to `cms.client()`, otherwise when the client was created. */
355
+ readonly date: Date;
356
+ }
357
+
358
+ /**
359
+ * What one client is created with, all read by the app outside blocks and
360
+ * passed in. The visitor and the date decide; `experiments` and `campaigns`
361
+ * override what they decide, name by name. Given every test and campaign and
362
+ * no visitor, a client is fully decided in advance (a page rendering what a
363
+ * proxy in front of it decided).
364
+ */
365
+ export interface ClientOptions {
366
+ /**
367
+ * What to read: `undefined` (or `null`) for the current release; a
368
+ * published release's commit SHA (40 hex characters), read from hosted
369
+ * releases; or a draft pointer, the draft's changes over the current
370
+ * release. Only a version: a Studio link's moment and switched tests are
371
+ * the options below (`cms.readVersion(request)` reads all of them).
372
+ */
373
+ version?: string | null;
374
+ /**
375
+ * For a draft: the release check made for this request
376
+ * (`cms.checkRelease()`), so the draft waits for it instead of making a
377
+ * check of its own; one request, one read of the release metadata. An id
378
+ * this CMS didn't make (another process's) is a check of its own. Ignored
379
+ * for the release and a release's SHA.
380
+ */
381
+ releaseCheck?: string | null;
382
+ /**
383
+ * Who is visiting (`readVisitor`, `parseVisitor` or `newVisitor` from
384
+ * `@decocms/blocks/experiments`): the saved block `experiments` decides
385
+ * its tests for them. Without one, every test not in `experiments` is off.
386
+ */
387
+ visitor?: Visitor | null;
388
+ /**
389
+ * The moment the saved block `campaigns` checks its windows at
390
+ * (`client.date`). Default: when the client is created.
391
+ */
392
+ date?: Date | null;
393
+ /**
394
+ * Tests on (`true`) or off (`false`) by name, whatever the visitor and the
395
+ * test's percentage; the others are decided for the visitor. A name the
396
+ * saved block `experiments` doesn't have stays out.
397
+ */
398
+ experiments?: Partial<Assignments> | null;
399
+ /**
400
+ * Campaigns on (`true`) or off (`false`) by name, whatever their window;
401
+ * the others are checked at `date`. A name the saved block `campaigns`
402
+ * doesn't have stays out.
403
+ */
404
+ campaigns?: Partial<Assignments> | null;
405
+ }
406
+
407
+ /**
408
+ * What a Studio link asks for (`cms.readVersion`, `parseVersion`): the
409
+ * version, and the preview's moment and the tests and campaigns it switches,
410
+ * in the shape of `ClientOptions`, so it spreads into `cms.client()`.
411
+ */
412
+ export interface RequestVersion {
413
+ /** A draft pointer, or a published release's commit SHA. */
414
+ version: string;
415
+ /** The moment the preview shows (`__at`). */
416
+ date?: Date;
417
+ /** The tests the preview switches on or off (`__test=<name>=on|off`). */
418
+ experiments?: Assignments;
419
+ /** The campaigns the preview switches on or off (`__campaign=<name>=on|off`). */
420
+ campaigns?: Assignments;
324
421
  }
325
422
 
423
+ /**
424
+ * `cms.readVersion`'s and `cms.forDraft`'s options: the release check made
425
+ * for the request (`cms.checkRelease()`), so they share it instead of
426
+ * checking again.
427
+ */
428
+ export type ReleaseCheckOptions = { releaseCheck?: string | null };
429
+
326
430
  export interface CMS {
327
- /** A client reading the current release. */
431
+ /**
432
+ * A client: the version it reads and the visitor it decides tests for, both
433
+ * passed in. Create one per request.
434
+ */
435
+ client(options?: ClientOptions): Client;
436
+ /** A client reading the current release: `cms.client()`. */
328
437
  forRelease(): Client;
329
438
  /**
330
- * A client reading the draft a pointer names: its changes, fetched from a
331
- * draft host (`*.decocms.com` and loopback by default;
332
- * `createCMS({ preview: { draftHosts } })` replaces the list), over this
333
- * server's production content.
439
+ * A client reading the draft a pointer names: `cms.client({ version: pointer })`.
440
+ * Its changes are fetched from a draft host (`*.decocms.com` and loopback by
441
+ * default; `createCMS({ preview: { draftHosts } })` replaces the list) and
442
+ * laid over this server's production content.
443
+ */
444
+ forDraft(pointer: string, options?: ReleaseCheckOptions): Client;
445
+ /**
446
+ * Checks for the latest release now, as a draft read does before it
447
+ * renders, and resolves with that check's id once it ends; never rejects.
448
+ * A request arriving while a check runs waits for the next one, shared by
449
+ * every request arriving meanwhile; there is no time-based throttle. Pass
450
+ * the id as `releaseCheck` to `readVersion`, `forDraft` and `client` for
451
+ * the same request, so its host check, its draft reads and its render
452
+ * share one check: one read of `latest.json` per preview request. A
453
+ * binding (`@decocms/tanstack`'s worker, `@decocms/nextjs`'s proxy) makes
454
+ * one per draft request and hands it down. Given the id of a check this
455
+ * CMS made (one the proxy in front made for the same request), it waits
456
+ * for that check and resolves with the same id; an id it didn't make
457
+ * (another process's) is ignored, and it checks.
334
458
  */
335
- forDraft(pointer: string): Client;
459
+ checkRelease(releaseCheck?: string | null): Promise<string>;
336
460
  /** Ask the content source for newer content now; never throws. */
337
461
  update(): Promise<{ updated: boolean }>;
338
462
  /**
@@ -342,11 +466,30 @@ export interface CMS {
342
466
  */
343
467
  settings(): Promise<EffectiveSettings>;
344
468
  /**
345
- * The request's draft pointer: `?__draft=` first, then the `__deco_draft`
346
- * cookie. `null` when neither is present, for `?__draft=off`, on a host
347
- * outside `settings().preview.hosts`, and for a value that doesn't parse
348
- * (ignored, as if absent): in each case the request gets the release.
469
+ * What a Studio link asks for: `?__draft=` first, then the `__deco_draft`
470
+ * cookie, holding a draft pointer or a published release's commit SHA,
471
+ * with the preview's moment (`__at`) and switched tests (`__test`) and
472
+ * campaigns (`__campaign`) as `date`, `experiments` and `campaigns`.
473
+ * `null` when neither is present, for `?__draft=off`, on a host outside
474
+ * the preview hosts (the current release's `previewHosts`, which Studio
475
+ * writes into the release metadata, plus `createCMS`'s `preview.hosts`;
476
+ * every host while the site has published no list, or without `site` and
477
+ * `preview.hosts`; no host while the metadata can't be read, besides
478
+ * `preview.hosts`), and for a value that doesn't parse (ignored,
479
+ * as if absent): in each case the request gets the current release. A
480
+ * draft and an older release's SHA are both checked against the current
481
+ * release's list.
482
+ *
483
+ * ```ts
484
+ * const client = cms.client({ visitor, ...(await cms.readVersion(request)) });
485
+ * ```
486
+ *
487
+ * With `releaseCheck` (the id `checkRelease()` resolved with for this
488
+ * request), the host check uses the preview hosts that check read instead
489
+ * of reading the release metadata again.
349
490
  */
491
+ readVersion(request: RequestLike, options?: ReleaseCheckOptions): Promise<RequestVersion | null>;
492
+ /** The version alone (`readVersion(request)`'s `version`), under its earlier name. */
350
493
  draftPointer(request: RequestLike): Promise<string | null>;
351
494
  /**
352
495
  * The `Set-Cookie` value that starts a preview (a valid `?__draft=` on an