@decocms/blocks 8.10.0 → 8.11.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 (163) hide show
  1. package/dist/v8/cli/index.d.ts +1 -0
  2. package/dist/v8/cli/index.d.ts.map +1 -1
  3. package/dist/v8/cli/index.js +1 -0
  4. package/dist/v8/cli/index.js.map +1 -1
  5. package/dist/v8/cli/run.d.ts +2 -0
  6. package/dist/v8/cli/run.d.ts.map +1 -1
  7. package/dist/v8/cli/run.js +30 -1
  8. package/dist/v8/cli/run.js.map +1 -1
  9. package/dist/v8/cli/skills.d.ts +25 -0
  10. package/dist/v8/cli/skills.d.ts.map +1 -0
  11. package/dist/v8/cli/skills.js +70 -0
  12. package/dist/v8/cli/skills.js.map +1 -0
  13. package/package.json +3 -2
  14. package/skills/deco-apps/SKILL.md +82 -0
  15. package/skills/deco-apps/references/algolia.md +51 -0
  16. package/skills/deco-apps/references/commerce-types.md +132 -0
  17. package/skills/deco-apps/references/instrumented-fetch.md +144 -0
  18. package/skills/deco-apps/references/magento.md +55 -0
  19. package/skills/deco-apps/references/messaging.md +76 -0
  20. package/skills/deco-apps/references/shopify.md +69 -0
  21. package/skills/deco-apps/references/vendored-loaders.md +135 -0
  22. package/skills/deco-apps/references/vtex-cookies-auth.md +146 -0
  23. package/skills/deco-apps/references/vtex.md +150 -0
  24. package/skills/deco-apps/references/wake.md +75 -0
  25. package/skills/deco-cms-schema/SKILL.md +80 -0
  26. package/skills/deco-cms-schema/references/annotations.md +147 -0
  27. package/skills/deco-cms-schema/references/content-hygiene.md +91 -0
  28. package/skills/deco-cms-schema/references/formats-and-widgets.md +112 -0
  29. package/skills/deco-cms-schema/references/shapes-that-break-the-form.md +165 -0
  30. package/skills/deco-cms-schema/references/types-to-fields.md +112 -0
  31. package/skills/deco-go-live/SKILL.md +127 -0
  32. package/skills/deco-go-live/references/content-releases.md +90 -0
  33. package/skills/deco-go-live/references/process.md +106 -0
  34. package/skills/deco-go-live/references/proxy-headers-checkout.md +139 -0
  35. package/skills/deco-go-live/references/qa-checklist-template.md +150 -0
  36. package/skills/deco-go-live/references/qa-inventory.md +120 -0
  37. package/skills/deco-go-live/references/react-spa.md +183 -0
  38. package/skills/deco-go-live/references/seo-analytics.md +114 -0
  39. package/skills/deco-go-live/references/traffic-ramp.md +87 -0
  40. package/skills/deco-go-live/references/worker-runtime.md +93 -0
  41. package/skills/deco-go-live/scripts/preflight.sh +221 -0
  42. package/skills/deco-images-media/SKILL.md +64 -0
  43. package/skills/deco-images-media/references/asset-upload.md +191 -0
  44. package/skills/deco-images-media/references/components-per-binding.md +167 -0
  45. package/skills/deco-images-media/references/providers-and-cdn.md +145 -0
  46. package/skills/deco-images-media/references/quality-and-lcp.md +93 -0
  47. package/skills/deco-images-media/references/troubleshooting.md +147 -0
  48. package/skills/deco-images-media/references/video.md +122 -0
  49. package/skills/deco-make-editable/SKILL.md +94 -0
  50. package/skills/deco-make-editable/references/a11y-and-e2e.md +104 -0
  51. package/skills/deco-make-editable/references/content-shapes.md +198 -0
  52. package/skills/deco-make-editable/references/from-figma.md +110 -0
  53. package/skills/deco-make-editable/references/i18n-fields.md +112 -0
  54. package/skills/deco-make-editable/references/inventory.md +79 -0
  55. package/skills/deco-make-editable/references/pixel-parity.md +175 -0
  56. package/skills/deco-make-editable/references/seeding-content.md +119 -0
  57. package/skills/deco-nextjs-site/SKILL.md +74 -0
  58. package/skills/deco-nextjs-site/references/caching.md +116 -0
  59. package/skills/deco-nextjs-site/references/metadata-seo.md +100 -0
  60. package/skills/deco-nextjs-site/references/proxy-and-drafts.md +177 -0
  61. package/skills/deco-nextjs-site/references/rendering.md +171 -0
  62. package/skills/deco-nextjs-site/references/setup.md +190 -0
  63. package/skills/deco-nextjs-site/references/studio-bridge.md +130 -0
  64. package/skills/deco-site-authoring/SKILL.md +75 -0
  65. package/skills/deco-site-authoring/references/lazy-blocks.md +155 -0
  66. package/skills/deco-site-authoring/references/loaders.md +192 -0
  67. package/skills/deco-site-authoring/references/pages.md +156 -0
  68. package/skills/deco-site-authoring/references/review-before-publish.md +95 -0
  69. package/skills/deco-site-authoring/references/sections.md +158 -0
  70. package/skills/deco-site-authoring/references/seo.md +116 -0
  71. package/skills/deco-site-workflow/SKILL.md +92 -0
  72. package/skills/deco-site-workflow/references/check.md +116 -0
  73. package/skills/deco-site-workflow/references/cli-reference.md +104 -0
  74. package/skills/deco-site-workflow/references/content-layout.md +93 -0
  75. package/skills/deco-site-workflow/references/content-sync.md +146 -0
  76. package/skills/deco-site-workflow/references/delivery.md +51 -0
  77. package/skills/deco-site-workflow/references/deploy.md +87 -0
  78. package/skills/deco-site-workflow/references/schema.md +173 -0
  79. package/skills/deco-site-workflow/references/serve-and-studio.md +138 -0
  80. package/skills/deco-storefront-caching/SKILL.md +67 -0
  81. package/skills/deco-storefront-caching/references/cache-keys.md +129 -0
  82. package/skills/deco-storefront-caching/references/case-study.md +82 -0
  83. package/skills/deco-storefront-caching/references/egress-traps.md +153 -0
  84. package/skills/deco-storefront-caching/references/nextjs.md +60 -0
  85. package/skills/deco-storefront-caching/references/perf-guardrails-e2e.md +123 -0
  86. package/skills/deco-storefront-caching/references/verification.md +136 -0
  87. package/skills/deco-storefront-caching/references/worker-page-cache.md +160 -0
  88. package/skills/deco-storefront-caching/scripts/html-anatomy.mjs +97 -0
  89. package/skills/deco-storefront-performance/SKILL.md +81 -0
  90. package/skills/deco-storefront-performance/references/cls-third-party.md +90 -0
  91. package/skills/deco-storefront-performance/references/hydration.md +116 -0
  92. package/skills/deco-storefront-performance/references/loaders-n-plus-1.md +107 -0
  93. package/skills/deco-storefront-performance/references/navigation-ux.md +130 -0
  94. package/skills/deco-storefront-performance/references/payload-trim.md +163 -0
  95. package/skills/deco-storefront-performance/references/render-location.md +152 -0
  96. package/skills/deco-storefront-performance/references/request-dedupe.md +147 -0
  97. package/skills/deco-storefront-performance/references/trace-reading.md +79 -0
  98. package/skills/deco-storefront-performance/references/worker-memory.md +176 -0
  99. package/skills/deco-tanstack-site/SKILL.md +68 -0
  100. package/skills/deco-tanstack-site/references/document-and-security.md +155 -0
  101. package/skills/deco-tanstack-site/references/router-and-navigation.md +137 -0
  102. package/skills/deco-tanstack-site/references/routes-and-pages.md +183 -0
  103. package/skills/deco-tanstack-site/references/server-functions.md +123 -0
  104. package/skills/deco-tanstack-site/references/setup.md +153 -0
  105. package/skills/deco-tanstack-site/references/worker-entry.md +152 -0
  106. package/skills/deco-v7-to-v8-migration/SKILL.md +122 -0
  107. package/skills/deco-v7-to-v8-migration/references/caching-and-privacy.md +10 -0
  108. package/skills/deco-v7-to-v8-migration/references/content.md +25 -0
  109. package/skills/deco-v7-to-v8-migration/references/editor-forms.md +27 -0
  110. package/skills/deco-v7-to-v8-migration/references/faststore.md +40 -0
  111. package/skills/deco-v7-to-v8-migration/references/framework-code.md +53 -0
  112. package/skills/deco-v7-to-v8-migration/references/hosted-releases.md +16 -0
  113. package/skills/deco-v7-to-v8-migration/references/import-map.md +81 -0
  114. package/skills/deco-v7-to-v8-migration/references/legacy-names.md +33 -0
  115. package/skills/deco-v7-to-v8-migration/references/manual-steps.md +10 -0
  116. package/skills/deco-v7-to-v8-migration/references/native-apps.md +43 -0
  117. package/skills/deco-v7-to-v8-migration/references/nextjs.md +19 -0
  118. package/skills/deco-v7-to-v8-migration/references/parity.md +66 -0
  119. package/skills/deco-v7-to-v8-migration/references/rendering.md +13 -0
  120. package/skills/deco-v7-to-v8-migration/references/running-the-script.md +29 -0
  121. package/skills/deco-v7-to-v8-migration/references/script-steps.md +13 -0
  122. package/skills/deco-v7-to-v8-migration/references/server-functions.md +15 -0
  123. package/skills/deco-v7-to-v8-migration/references/sibling-port.md +11 -0
  124. package/skills/deco-v7-to-v8-migration/references/site-code.md +15 -0
  125. package/skills/deco-v7-to-v8-migration/references/telemetry.md +10 -0
  126. package/skills/deco-v7-to-v8-migration/references/verify.md +20 -0
  127. package/skills/deco-v7-to-v8-migration/scripts/apps.ts +297 -0
  128. package/skills/deco-v7-to-v8-migration/scripts/asyncRendering.ts +73 -0
  129. package/skills/deco-v7-to-v8-migration/scripts/blockMap.ts +584 -0
  130. package/skills/deco-v7-to-v8-migration/scripts/ciSchemaCheck.ts +145 -0
  131. package/skills/deco-v7-to-v8-migration/scripts/compat.ts +357 -0
  132. package/skills/deco-v7-to-v8-migration/scripts/content.ts +121 -0
  133. package/skills/deco-v7-to-v8-migration/scripts/experiments.ts +81 -0
  134. package/skills/deco-v7-to-v8-migration/scripts/framework.ts +61 -0
  135. package/skills/deco-v7-to-v8-migration/scripts/imageCopy.ts +276 -0
  136. package/skills/deco-v7-to-v8-migration/scripts/imageModule.ts +285 -0
  137. package/skills/deco-v7-to-v8-migration/scripts/imports.ts +942 -0
  138. package/skills/deco-v7-to-v8-migration/scripts/invoke.ts +624 -0
  139. package/skills/deco-v7-to-v8-migration/scripts/legacyNames.ts +45 -0
  140. package/skills/deco-v7-to-v8-migration/scripts/main.ts +59 -0
  141. package/skills/deco-v7-to-v8-migration/scripts/matchers.ts +41 -0
  142. package/skills/deco-v7-to-v8-migration/scripts/migrate.ts +176 -0
  143. package/skills/deco-v7-to-v8-migration/scripts/redirects.ts +455 -0
  144. package/skills/deco-v7-to-v8-migration/scripts/report.ts +50 -0
  145. package/skills/deco-v7-to-v8-migration/scripts/scaffold.ts +1119 -0
  146. package/skills/deco-v7-to-v8-migration/scripts/secrets.ts +35 -0
  147. package/skills/deco-v7-to-v8-migration/scripts/sectionLoaders.ts +216 -0
  148. package/skills/deco-v7-to-v8-migration/scripts/siteSettings.ts +261 -0
  149. package/skills/deco-v7-to-v8-migration/scripts/stubs.ts +388 -0
  150. package/skills/deco-v7-to-v8-migration/scripts/tsconfig.json +7 -0
  151. package/skills/deco-v7-to-v8-migration/scripts/vendor.ts +249 -0
  152. package/skills/deco-v7-to-v8-migration/scripts/vtexInvoke.ts +240 -0
  153. package/skills/deco-v7-to-v8-migration/scripts/walk.ts +30 -0
  154. package/skills/deco-variants/SKILL.md +57 -0
  155. package/skills/deco-variants/references/caching-variants.md +63 -0
  156. package/skills/deco-variants/references/custom-matchers.md +83 -0
  157. package/skills/deco-variants/references/draft-preview.md +59 -0
  158. package/skills/deco-variants/references/experiments-and-campaigns.md +104 -0
  159. package/skills/deco-variants/references/multivariate.md +85 -0
  160. package/skills/deco-variants/references/v7-matchers.md +71 -0
  161. package/src/v8/cli/index.ts +1 -0
  162. package/src/v8/cli/run.ts +35 -1
  163. package/src/v8/cli/skills.ts +91 -0
@@ -0,0 +1,150 @@
1
+ # `@decocms/apps-vtex`
2
+
3
+ A typed client for VTEX's Intelligent Search, legacy Catalog, Checkout, Session, Master
4
+ Data v1 and IO GraphQL APIs. It returns VTEX's own response types. Cookies and
5
+ `Set-Cookie` are covered in [`vtex-cookies-auth.md`](./vtex-cookies-auth.md).
6
+
7
+ ## Configure
8
+
9
+ ```ts
10
+ import { createVtexClient } from "@decocms/apps-vtex";
11
+
12
+ export const vtex = createVtexClient({
13
+ account: "mystore",
14
+ appKey: secrets.VTEX_APP_KEY, // from the deploy platform's secrets; optional,
15
+ appToken: secrets.VTEX_APP_TOKEN, // sent only when both are set
16
+ salesChannel: "1", // default `sc`
17
+ locale: "pt-BR", // default Intelligent Search locale
18
+ // environment: "vtexcommercestable", domain: "com.br" (defaults)
19
+ // fetch, retry, circuitBreaker: see instrumented-fetch.md
20
+ });
21
+ ```
22
+
23
+ - Requests go to `https://{account}.{environment}.{domain}`. `io.graphql` goes to
24
+ `https://{account}.myvtex.com/_v/private/graphql/v1`.
25
+ - `appKey` and `appToken` are sent as `X-VTEX-API-AppKey` / `X-VTEX-API-AppToken`, but
26
+ **only on calls without a `cookie`**. A call made for a shopper goes out as the
27
+ shopper. With app credentials, VTEX would return the orderForm with profile data
28
+ unmasked.
29
+ - Exported names: `createVtexClient`, `VtexClient`, `VtexClientConfig`, `VtexError`,
30
+ `VtexRequestOptions`, `VtexCheckoutOptions`, `VtexResponse`, `VtexSearchArgs`,
31
+ `VtexCatalogSearchArgs`. VTEX's response types (`ProductSearchResult`, `OrderForm`,
32
+ `Session`…) are not exported by name. Get them from the client:
33
+ `Awaited<ReturnType<VtexClient["search"]["products"]>>`.
34
+
35
+ Every operation accepts `cookie` and `signal` in its options.
36
+
37
+ ## Operations
38
+
39
+ **Intelligent Search** (GET, retried)
40
+
41
+ | Call | Endpoint |
42
+ |---|---|
43
+ | `search.products(args)` | `product_search` |
44
+ | `search.facets(args)` | `facets` |
45
+ | `search.suggestions(args)` | `search_suggestions` |
46
+ | `search.autocomplete(args)` | `autocomplete_suggestions` |
47
+ | `search.topSearches(args)` | `top_searches` |
48
+
49
+ `args`: `query`, `facets` (`[{ key, value }]`, sent as the path
50
+ `category-1/shirts/brand/acme`), `page` (1-based), `count`, `sort` (`"price:asc"`,
51
+ `"orders:desc"`…), `fuzzy` (`"0" | "1" | "auto"`), `locale`, `hideUnavailableItems`,
52
+ `simulationBehavior` (`"default" | "skip" | "only1P"`), `regionId`, `salesChannel`.
53
+ Suggestions, autocomplete and top searches ignore `facets`.
54
+
55
+ **Legacy Catalog** (GET, retried)
56
+
57
+ | Call | Notes |
58
+ |---|---|
59
+ | `catalog.products({ term, ft, fq, from, to, sort, salesChannel })` | `from`/`to` are 0-based inclusive (`_from`, `_to`); `fq` is a list; `sort` is the `O` value (`"OrderByPriceASC"`…) |
60
+ | `catalog.pageType(path)` | Page type of a URL path (`Product`, `Category`, `Brand`, `NotFound`…) |
61
+ | `catalog.crossSelling(type, productId)` | VTEX's cross-selling lists by type |
62
+ | `catalog.categoryTree(levels = 3)` | |
63
+
64
+ `term` and `pageType`'s `path` usually come from the shopper's URL. The client encodes
65
+ them segment by segment and throws on `.` or `..` segments, so a path can't climb to
66
+ another endpoint or add a query while credentials are attached.
67
+
68
+ **Checkout** (POST, never retried; shopper-scoped)
69
+
70
+ | Call | Returns |
71
+ |---|---|
72
+ | `checkout.orderForm({ cookie, sections?, salesChannel? })` | `VtexResponse<OrderForm>` |
73
+ | `checkout.addItems(orderFormId, [{ id, quantity, seller }], options)` | `VtexResponse<OrderForm>` |
74
+ | `checkout.updateItems(orderFormId, [{ index, quantity }], options)` | `VtexResponse<OrderForm>` |
75
+ | `checkout.addCoupon(orderFormId, text, options)` | `VtexResponse<OrderForm>` |
76
+ | `checkout.attachment(orderFormId, name, body, options)` | `VtexResponse<OrderForm>` |
77
+ | `checkout.simulation({ items, postalCode?, country? }, options)` | `SimulationOrderForm` |
78
+ | `checkout.regions({ postalCode, country, salesChannel? })` (GET) | `[{ id, sellers }]` |
79
+
80
+ `VtexResponse<T>` is `{ data, setCookies }`. Forward `setCookies` to the browser.
81
+
82
+ **Session**: `sessions.get({ cookie, items? })` and `sessions.update(publicProps, { cookie })`,
83
+ both `VtexResponse`. `items` is a list such as `["profile.email", "profile.isAuthenticated"]`.
84
+
85
+ **Master Data v1**
86
+
87
+ - `masterdata.search(entity, { where, fields, sort, from = 0, to = 10, cookie })`:
88
+ `from`/`to` go in the `REST-Range` header.
89
+ - `masterdata.create(entity, document, { cookie })`: when the client has app
90
+ credentials, it sends them and leaves the shopper's cookie out (Master Data refuses
91
+ anonymous writes). It returns `{ Id, Href, DocumentId }`.
92
+
93
+ **IO GraphQL**: `io.graphql<T>({ query, variables?, operationName? }, { cookie })`
94
+ returns `data`. GraphQL `errors` (sent with HTTP 200) throw `VtexError("io.graphql", 200)`
95
+ without the messages, since they can echo inputs.
96
+
97
+ ## Sales channel (`sc`)
98
+
99
+ A wrong or missing sales channel gives wrong prices, missing products or checkout
100
+ errors. VTEX answers 200 with a well-formed body either way, so nothing fails loudly.
101
+
102
+ - The client sends `sc` on Intelligent Search, `catalog.products`, every orderForm and
103
+ simulation call, and `regions`. The per-call `salesChannel` wins over the config's.
104
+ - With no channel configured or passed, no `sc` is sent (never an empty `sc=`). VTEX
105
+ then uses the account default.
106
+ - `pageType`, `crossSelling` and `categoryTree` send no `sc`.
107
+ - A store with several channels reads the shopper's channel per request (v7 read the
108
+ `VTEXSC` cookie) and passes it on cart calls, the same one the search used.
109
+
110
+ ## Region (`regionId`)
111
+
112
+ Regionalized stores price and stock by region. Get the region for a postal code with
113
+ `checkout.regions({ postalCode, country })`; its `id` is the `regionId`. VTEX also keeps
114
+ it in the shopper's `vtex_segment` cookie.
115
+
116
+ - Pass `regionId` to `search.*`. It goes on the query string, so it is part of the URL
117
+ and of any cache key built from it.
118
+ - A block function has no request, so it can't read `vtex_segment` itself. Fetch
119
+ regionalized results where you have the request, or pass the region in as an input.
120
+ Pages split by region are a cache decision: see `deco-storefront-caching`.
121
+ - Delivery promise badges, PLP delivery filters and postal-code capture are in the
122
+ `vtex-delivery-promise` skill (decocms/skills).
123
+
124
+ ## orderForm sections
125
+
126
+ `checkout.orderForm` sends `{ expectedOrderFormSections: sections }` when you pass
127
+ `sections`, and `{}` otherwise, which per the client asks for every section. Ask for
128
+ what the view needs: `SECTIONS_MINIMAL`, `SECTIONS_DRAWER` or `SECTIONS_FULL` from
129
+ `@decocms/compat-v7/commerce/types/cart` ([`commerce-types.md`](./commerce-types.md)).
130
+
131
+ `addItems`, `updateItems` and `addCoupon` send only their payload. `attachment` sends
132
+ the `body` you give it, so include `expectedOrderFormSections` there if you need it.
133
+
134
+ ## Images
135
+
136
+ `@decocms/apps-vtex/image` exports `ImageProvider`s for `createImageUrl` from
137
+ `@decocms/blocks/image`: `vtexCatalog()`, `vtexCatalogFrame({ frame? })`,
138
+ `vtexCatalogWebp({ quality? })` and `vtexFileManager({ via: "query" | "thumbor" })`.
139
+ List them before `decoCdn`. Which one matches a site, and the binding wiring, is in
140
+ `deco-images-media`.
141
+
142
+ ## Failure modes
143
+
144
+ | Symptom | Likely cause |
145
+ |---|---|
146
+ | Prices differ from the VTEX storefront | No `sc`, or a different `sc` than the shopper's; `regionId` missing on a regionalized store |
147
+ | Cart empties after each action | `setCookies` not forwarded, or joined into one header ([`vtex-cookies-auth.md`](./vtex-cookies-auth.md)) |
148
+ | A new, empty cart on every call | The cart call got no `cookie`: with no `checkout.vtex.com` cookie VTEX starts a new cart, and the call goes out with the app's credentials instead of as the shopper |
149
+ | Every call fails at once for a few seconds | The circuit breaker opened after 5 failures in a row on any operation |
150
+ | `vtex: invalid path segment` | A `.` or `..` segment in `term` or `pageType`'s path |
@@ -0,0 +1,75 @@
1
+ # `@decocms/apps-wake`
2
+
3
+ A client for Wake's Storefront GraphQL API, plus the one checkout REST call a storefront
4
+ needs (`getLogin`). Operations and their generated types ship with it.
5
+
6
+ ## Configure
7
+
8
+ ```ts
9
+ import { createWakeClient } from "@decocms/apps-wake";
10
+
11
+ export const wake = createWakeClient(
12
+ {
13
+ storefrontToken: secrets.WAKE_TOKEN, // sent as TCS-Access-Token
14
+ checkoutUrl: "https://acme.checkout.fbits.store", // needed by getLogin
15
+ // storefrontEndpoint: defaults to https://storefront-api.fbits.net/graphql
16
+ },
17
+ { fetch: cachedFetch }, // optional
18
+ );
19
+ ```
20
+
21
+ Exports: `createWakeClient`, `WakeClient`, `WakeClientConfig`, `WakeClientOptions`,
22
+ `WakeError`, and the type `UserAuthenticate`.
23
+
24
+ ## Run an operation
25
+
26
+ ```ts
27
+ import { GetProduct } from "@decocms/apps-wake/storefront";
28
+ import type { GetProductQuery, GetProductQueryVariables } from "@decocms/apps-wake/storefront/types";
29
+
30
+ const data = await wake.graphql<GetProductQuery, GetProductQueryVariables>(GetProduct, { productId: 1 });
31
+ ```
32
+
33
+ - `graphql(document, variables?, { headers? })` takes a string or one of the operation
34
+ objects (`{ query, fragments? }`) from `/storefront`, and returns `data`.
35
+ - `/storefront` exports Wake's Storefront operations: `GetProduct`, `GetProducts`, `Search`,
36
+ `Autocomplete`, `ProductRecommendations`, `GetURL`, `Hotsite`, `Shop`,
37
+ `GetCart`, `CreateCart`, `AddItemToCart`, `RemoveItemFromCart`, `AddCoupon`,
38
+ `RemoveCoupon`, `AddKit`, `RemoveKit`, `ShippingQuotes`, `GetUser`, `GetWishlist`,
39
+ `WishlistAddProduct`, `WishlistRemoveProduct`, `ProductRestockAlert`,
40
+ `CreateNewsletterRegister`, `CreateProductReview`, `SendGenericForm`, `GetBuyList`,
41
+ `GetPartners`, `CheckoutPartnerAssociate`, `CheckoutPartnerDisassociate` and
42
+ `productOptions`, plus two fragment strings (`Customer`, `WishlistReducedProduct`).
43
+ `/storefront/types` has a `…Query` or `…Mutation` type and a `…Variables` type for
44
+ each, named after the GraphQL operation inside, not the export: `GetURL` →
45
+ `GetUrlQuery`, `GetBuyList` → `BuyListQuery`.
46
+ - Per-call `headers` add things such as `X-Forwarded-For` or a customer access token.
47
+ They can't override the token or the content type.
48
+ - The label is the document's operation name; an unnamed one is `graphql`.
49
+ - This call takes no `signal`.
50
+
51
+ ## `getLogin(cookie)`
52
+
53
+ `GET {checkoutUrl}/api/Login/Get` with the shopper's checkout cookies (the
54
+ `fbits-login` cookie). It returns the shopper's account (`UserAuthenticate`: `Id`,
55
+ `Email`, `Name`, `Cpf`, `CustomerAccessToken`, …) or `null` when they aren't signed in
56
+ (401, 403 or 404). Any other failure, such as a 429, throws `WakeError`. It throws a
57
+ plain `Error` when `checkoutUrl` isn't set.
58
+
59
+ Customer operations take the returned `CustomerAccessToken` as the
60
+ `customerAccessToken` variable (`GetUser`, `WishlistAddProduct`, …). Both the cookie
61
+ and the token are per shopper: run these in a server function and don't cache the
62
+ results.
63
+
64
+ ## Errors
65
+
66
+ `WakeError` has `operation`, `status` and `graphqlErrors` (how many GraphQL errors the
67
+ response had; 0 for an HTTP failure). A response with no `data` also throws. No retries
68
+ or circuit breaker.
69
+
70
+ ## Vendored GraphQL documents
71
+
72
+ A migrated site may keep v7's `queries.ts` under `src/vendor/wake`. Don't run a
73
+ formatter over it: a reflowed document changes every request body, and a replaying
74
+ parity harness misses every call. Prefer the operations from
75
+ `@decocms/apps-wake/storefront` once parity is done.
@@ -0,0 +1,80 @@
1
+ ---
2
+ name: deco-cms-schema
3
+ description: "@decocms/blocks 8: how a section's Props type becomes the Studio form. Covers what `deco schema` (packages/blocks/src/v8/cli/schema/typeToSchema.ts) reads: the JSDoc tags (@title, @description, @titleBy, @format, @options, @hide, @ignore, @default, validation tags), widget aliases (ImageWidget, RichText, Color, Secret…) and format aliases, what each TypeScript shape turns into (literal unions, object unions, Lazy<T>, ReactNode, block-fillable fields), and declaration order as form order. Also the shapes that hurt editors (sibling anonymous inline types, one-to-many relations linked by a typed key, null holes in arrays, enum plus dead fields instead of a union), blank-on-empty sections, dead fields, and layout controls posing as content. Load it before adding or changing props on a section, loader or page, when a Studio form looks wrong (raw labels, missing widget, select with no options, unlabeled list rows), or when deco check rejects content after a Props change."
4
+ ---
5
+
6
+ # Deco CMS schema
7
+
8
+ A section's `Props` type is the form an editor fills in Studio. A badly shaped
9
+ field is not ugly code: it is a person stuck in front of a form that does not
10
+ say what it wants.
11
+
12
+ Load this when you add or change props, when a Studio form looks wrong, or when
13
+ `deco check` starts failing after a type change.
14
+
15
+ ## The pipeline
16
+
17
+ 1. `deco schema` reads the default export of `.deco/index.ts` (the block map).
18
+ For each block it takes the first parameter's type and writes one JSON Schema
19
+ per type into `.deco/schema.gen.json`.
20
+ 2. `deco schema push` uploads that file so Studio can draw forms. Until it runs,
21
+ Studio shows the old form.
22
+ 3. `deco check` validates every saved block in content against the committed
23
+ `.deco/schema.gen.json`.
24
+
25
+ Nothing regenerates the schema for you during `vite dev`. Run `deco schema`
26
+ after each `Props` change, or keep `deco schema --watch` running. In CI,
27
+ `deco schema --check` fails when the committed file is stale. Running these
28
+ commands day to day is covered by the `deco-site-workflow` skill.
29
+
30
+ The generator writes warnings you should not ignore:
31
+
32
+ - `its props are typed any, so its form is empty`
33
+ - `its first parameter isn't an object of props, so its form is empty`
34
+ - `returns any, so it isn't offered for any field`
35
+
36
+ ## When to load what
37
+
38
+ | Reference | Load it when |
39
+ |---|---|
40
+ | [`references/annotations.md`](./references/annotations.md) | Writing JSDoc on a prop: which tags the generator reads, how values are coerced, `@hide` vs `@ignore`, `@options` lists, `/** */` vs `//` |
41
+ | [`references/formats-and-widgets.md`](./references/formats-and-widgets.md) | Picking a widget: image, video, color, rich text, HTML, textarea, date, secret; `@format` on a field or on a type alias; which formats `deco check` validates |
42
+ | [`references/types-to-fields.md`](./references/types-to-fields.md) | A field came out as the wrong kind: selects, variant pickers, section pickers, `Lazy<T>`, fields a loader can fill, hidden or missing props |
43
+ | [`references/shapes-that-break-the-form.md`](./references/shapes-that-break-the-form.md) | Designing arrays, relations and variants: sibling inline types, keyed relations, null holes, variants as a union |
44
+ | [`references/content-hygiene.md`](./references/content-hygiene.md) | Reviewing a section for editors: empty props, dead fields, layout controls, removing or renaming a field that has saved content |
45
+
46
+ ## Two rules that cover most of it
47
+
48
+ 1. **Give every prop a `@title`.** Without one the label is the identifier,
49
+ title-cased: `desktopCardWidth` becomes "Desktop Card Width". That is a
50
+ developer's word, not an editor's.
51
+ 2. **Declaration order is form order.** Fields come out in the order the type
52
+ declares them. Put what editors touch most at the top: content before
53
+ settings, the heading before the padding.
54
+
55
+ ## Checklist before `deco schema`
56
+
57
+ - [ ] Every prop has `@title`; `@description` where the field is not obvious,
58
+ written for the editor.
59
+ - [ ] Every type used as an array item has `@titleBy <field>`.
60
+ - [ ] Image, video, color, rich text, date and secret fields use a widget
61
+ alias or `@format`. No free-text field holding an image URL.
62
+ - [ ] `@options` is one JSON array, not one tag per choice.
63
+ - [ ] One-to-many relations nest. No two sibling arrays joined by a typed key.
64
+ - [ ] No two sibling fields share the same anonymous inline type.
65
+ - [ ] Arrays from `Props` are compacted before the first `.map`.
66
+ - [ ] The section renders something sensible with empty props.
67
+ - [ ] Every field reaches the DOM. No layout controls posing as content.
68
+
69
+ Then run `deco schema`, read `.deco/schema.gen.json` for the block you changed,
70
+ and run `deco check`.
71
+
72
+ ## Related skills
73
+
74
+ - `deco-site-workflow`: running `deco schema`, `deco schema push`, `deco check`.
75
+ - `deco-site-authoring`: writing the section itself.
76
+ - `deco-variants`: multivariate blocks inside arrays and fields.
77
+ - `deco-images-media`: what an image field's `@description` should say.
78
+ - `deco-make-editable`: turning hardcoded content into blocks.
79
+ - `deco-v7-to-v8-migration`: form differences between v7 and v8 after a
80
+ migration.
@@ -0,0 +1,147 @@
1
+ # Annotations `deco schema` reads
2
+
3
+ The generator is `packages/blocks/src/v8/cli/schema/typeToSchema.ts`
4
+ (`getJsDocTags` and `applyJsDocToSchema`). It was ported from v7's generator,
5
+ so most tags behave as they did. The differences are called out below.
6
+
7
+ ## Only `/** */` reaches the schema
8
+
9
+ The generator reads JSDoc blocks. A `//` comment never reaches the form. Use
10
+ the split on purpose:
11
+
12
+ - `/** @title … @description … */` is for whoever fills the form.
13
+ - `// comment` is for whoever reads the code: measurements, the reason behind
14
+ a value, links to tickets.
15
+
16
+ One section shipped a `@description` with twenty lines of typography
17
+ measurements and production URLs. The editor opened the form and got a spec
18
+ sheet where the help text should be.
19
+
20
+ The free text at the top of a JSDoc block becomes `description`. An explicit
21
+ `@description` tag replaces it.
22
+
23
+ A tag followed directly by punctuation (`@description: text`) is skipped. Write
24
+ `@description text`.
25
+
26
+ Put each prop's JSDoc on its own line, above the prop. A one-line type such
27
+ as `{ /** @title Ratio */ ratio: string }` loses the tag: the generator does
28
+ not read a JSDoc that sits on the same line, right after the opening brace.
29
+
30
+ ## Tag table
31
+
32
+ | Tag | What lands in the schema |
33
+ |---|---|
34
+ | `@title` | `title`, the field label. Without it: the prop name title-cased (`marginTop` → "Margin Top") |
35
+ | `@description` | `description`, help text |
36
+ | `@titleBy <field>` | Passed through. On an array item's type, names the field that labels each row |
37
+ | `@format <name>` | `format`, the widget. `datetime` is rewritten to `date-time`. See [formats-and-widgets.md](./formats-and-widgets.md) |
38
+ | `@default <value>` | `default`, coerced (below) |
39
+ | `@options <JSON array>` | `enum` (and `enumNames` when items have labels). Anything else is dropped (below) |
40
+ | `@hide` | `hide: "true"`. The field stays in the schema and in content, hidden from the form |
41
+ | `@ignore` | The prop is left out of the schema |
42
+ | `@examples` | `examples`: one per line, or a JSON value |
43
+ | `@minimum` `@maximum` `@exclusiveMinimum` `@exclusiveMaximum` `@multipleOf` | Numbers |
44
+ | `@minLength` `@maxLength` | Numbers |
45
+ | `@minItems` `@maxItems` `@minProperties` `@maxProperties` | Numbers |
46
+ | `@readOnly` `@writeOnly` `@deprecated` `@uniqueItems` | Booleans |
47
+ | Any other tag (`@pattern`, `@placeholder`, `@widget`, `@icon`, `@mode`…) | Passed through as a string. The generator gives it no meaning; whether Studio does is Studio's call |
48
+
49
+ `deco check` validates content with Ajv against the generated schema, so the
50
+ standard JSON Schema keywords above (`minimum`, `maxLength`, `pattern`,
51
+ `minItems`…) are enforced on saved content too, not only in the form.
52
+
53
+ ## Coercion
54
+
55
+ - **Numeric tags** become `Number(value)`. Always give a value: a bare
56
+ `@minimum` is `Number("true")`, which is `NaN` and is written to
57
+ `.deco/schema.gen.json` as `null`.
58
+ - **Boolean tags** are `true` when the value is `true` or missing. A bare
59
+ `@deprecated` or `@uniqueItems` works. Anything else, including `yes`, is
60
+ `false`.
61
+ - **`@default`**: `true`, `false` and `null` become those values; a numeric
62
+ string becomes a number; otherwise it is parsed as JSON, and if that fails it
63
+ is kept as the raw string. `@default hello` is `"hello"`;
64
+ `@default ["a","b"]` is an array.
65
+ - **`@hide`** sets `hide: "true"` whatever value follows it.
66
+
67
+ ## `@titleBy`: make array rows readable
68
+
69
+ Put `@titleBy` on every type used as an array item. Without it Studio has no
70
+ field to label rows with, and the editor opens each row to find out what it
71
+ is.
72
+
73
+ ```ts
74
+ /** @titleBy label */
75
+ export interface FooterLink {
76
+ /** @title Label */
77
+ label: string;
78
+ /** @title URL */
79
+ href: string;
80
+ }
81
+ ```
82
+
83
+ ## `@options`: one JSON array
84
+
85
+ A static list must be one JSON array in one tag:
86
+
87
+ ```ts
88
+ /**
89
+ * @title Align
90
+ * @options ["left", "center", "right"]
91
+ */
92
+ align: string;
93
+
94
+ /**
95
+ * @title Level
96
+ * @options [{ "value": "advanced", "label": "Advanced" }, { "value": "basic", "label": "Basic" }]
97
+ */
98
+ level: string;
99
+ ```
100
+
101
+ Items are strings, numbers or `{ value, label }` objects. Labels go to
102
+ `enumNames`.
103
+
104
+ What does not work in v8:
105
+
106
+ - **One `@options` tag per choice.** The generator keeps one value per tag
107
+ name, so only the last line survives. A single object is not an array, so it
108
+ is dropped and the field is plain text.
109
+ - **A loader path** (`@options site/loaders/x.ts`, often with
110
+ `@format dynamic-options`). The v8 site editor never runs site code, so the
111
+ list is dropped and the field is a text field. Make sure the field still accepts what an editor would type,
112
+ and rewrite any `@description` that promises suggestions.
113
+
114
+ A string-literal union needs no `@options`: `align: "left" | "center"` is
115
+ already a select. See [types-to-fields.md](./types-to-fields.md).
116
+
117
+ ## `@hide` vs `@ignore`
118
+
119
+ - `@ignore` removes the prop from the schema. Studio does not know it exists.
120
+ Saved content that still has the key fails `deco check` (a field the code
121
+ does not declare).
122
+ - `@hide` keeps the field in the schema and in content, and hides it in the
123
+ form. Use it for a value another tool or old content still sets, or a field
124
+ you are retiring (see [content-hygiene.md](./content-hygiene.md)).
125
+
126
+ A hidden prop that is not optional is not marked `required`, since no editor
127
+ can fill it, unless it has a `@default` (or a literal type, which gets a
128
+ default).
129
+
130
+ Leave a `//` comment that says why a field is hidden or ignored. Otherwise the
131
+ next person sees a prop that is mysteriously missing from the form.
132
+
133
+ ## Tags on a type, not a field
134
+
135
+ JSDoc on an interface or type alias applies to the object schema built from
136
+ it. This is how a union member gets its name in a variant picker:
137
+
138
+ ```ts
139
+ /** @title Wide */
140
+ export interface WideLayout {
141
+ /** @title Aspect ratio */
142
+ aspectRatio: string;
143
+ }
144
+ ```
145
+
146
+ `@format` on a type alias reaches every field of that type. See
147
+ [formats-and-widgets.md](./formats-and-widgets.md).
@@ -0,0 +1,91 @@
1
+ # Content hygiene: fields that should not exist
2
+
3
+ A form is easier to use with fewer, better fields. This file covers what to
4
+ render when fields are empty, which fields to remove, and how to remove one
5
+ without breaking saved content.
6
+
7
+ ## Render something sensible with empty props
8
+
9
+ A new block starts with nothing filled in, and an optional prop arrives as
10
+ `undefined`. The section must not throw and should not render blank: a
11
+ realistic default is how an editor learns what a field is for.
12
+
13
+ Declare `DEFAULT_*` constants for what optional fields fall back to, and use
14
+ them once, where props enter the component, instead of scattering
15
+ `?? something` through the JSX.
16
+
17
+ ```tsx
18
+ const DEFAULT_TITLE = "New arrivals";
19
+
20
+ export function Shelf({ title = DEFAULT_TITLE, products = [] }: Props) {
21
+ // …
22
+ }
23
+ ```
24
+
25
+ `@default` only writes `default` into the schema. It does not change what
26
+ your component receives for content saved without the field, so keep the code
27
+ default too.
28
+
29
+ ## Dead fields: the editor sets them, nothing happens
30
+
31
+ A field that reaches no DOM attribute is worse than a missing one. The editor
32
+ changes it, sees no effect, and decides the CMS is broken.
33
+
34
+ They pile up when a shared type is reused for a narrower purpose: a `Cta` type
35
+ with `buttonStyle`, `backgroundColor`, `hoverColor` and `showArrowIcon`,
36
+ attached to a section that only reads `url` and `text`. Give that section its
37
+ own narrower type.
38
+
39
+ Check the result in `.deco/schema.gen.json`, not in the `.tsx` diff: every
40
+ removed field gone from the block's definition, every kept field still there.
41
+
42
+ ## Layout controls posing as content
43
+
44
+ A field should carry an editorial decision: which image, which text, which
45
+ color, how many items. Not a layout one: card width in pixels, a desktop gap
46
+ and a separate mobile gap as raw numbers.
47
+
48
+ The test: remove the field and fix one value in the component. Does the
49
+ editor lose a decision they really need to make? If not, it is not a prop.
50
+ One content review removed a set of these because every editor used the same
51
+ value anyway. The fields only added a way to break the layout by accident.
52
+
53
+ When a developer escape hatch has to stay visible, end its `@title` with
54
+ "(advanced)" so editors can tell it from fields meant for daily use.
55
+
56
+ ## Removing or renaming a field with saved content
57
+
58
+ `deco check` rejects a key that the code does not declare. Keys starting with
59
+ `_`, `$` or `@` are exempt. So deleting or renaming a prop makes every saved
60
+ block that still has the old key fail `deco check`.
61
+
62
+ Two safe paths:
63
+
64
+ - **Migrate the content in the same change.** Update the saved blocks so no
65
+ value uses the old key, run `deco check`, and ship both together. How to
66
+ edit content and send it as a draft is in the `deco-site-workflow` skill.
67
+ - **Retire the field first.** Keep it in the type with `@hide` and
68
+ `@deprecated`, with a `//` comment saying what replaced it. Content keeps
69
+ validating; editors no longer see it. Delete it once no content uses it.
70
+
71
+ `@ignore` is not a way to retire a field: it removes the field from the
72
+ schema, so saved values fail `deco check` just as if it were deleted.
73
+
74
+ ## Placeholder content
75
+
76
+ Blocks left with lorem ipsum, placeholder image URLs, or hidden on the page
77
+ render nothing useful and clutter the form with entries an editor cannot tell
78
+ from real ones. Delete them before handing the site over.
79
+
80
+ ## Structure
81
+
82
+ - Past about 30–40 lines of `Props`, or once there are two or more nested
83
+ types (an array item, a variant union), move the types to a sibling
84
+ `types.ts`. Types only, no logic.
85
+ - More than about eight top-level fields with no grouping reads as a wall of
86
+ inputs. Group them into named nested objects (`/** @title Colors */ colors:
87
+ {…}`).
88
+ - When two or more sections need the same piece of form (same field, same
89
+ label, same `@description`), extract a shared type and compose it. Image
90
+ pairs (desktop and mobile) and autoplay settings are the usual candidates.
91
+ Sections that should behave the same drift apart otherwise.
@@ -0,0 +1,112 @@
1
+ # Formats and widgets
2
+
3
+ A field's `format` picks its widget in Studio. There are three ways to set it:
4
+
5
+ 1. `@format` on the **field** itself. This always wins.
6
+ 2. A **widget alias** as the field's type (`image: ImageWidget`).
7
+ 3. `@format` on a **type alias** the field uses. It applies only when no
8
+ widget alias already set a format.
9
+
10
+ All three end up as the same `format` string in `.deco/schema.gen.json`.
11
+
12
+ ## Widget aliases
13
+
14
+ `deco schema` matches these by **name, as written on the prop**
15
+ (`WIDGET_TYPE_FORMATS` in `typeToSchema.ts`). Each is a `string`.
16
+
17
+ | Alias | `format` |
18
+ |---|---|
19
+ | `ImageWidget` | `image-uri` |
20
+ | `VideoWidget` | `video-uri` |
21
+ | `HTMLWidget` | `html` |
22
+ | `RichText` | `rich-text` |
23
+ | `Color` | `color` |
24
+ | `TextArea` | `textarea` |
25
+ | `Code` | `code` |
26
+ | `DateTimeWidget` | `date-time` |
27
+ | `Secret` | `password` |
28
+
29
+ Where to get them:
30
+
31
+ - `@decocms/compat-v7/types/widgets` (also re-exported from
32
+ `@decocms/compat-v7/types` and `@decocms/compat-v7`) exports `ImageWidget`,
33
+ `VideoWidget`, `HTMLWidget`, `RichText`, `TextArea`, `Color`, `Secret`, plus
34
+ `TextWidget` and `ButtonWidget`.
35
+ - `Code` and `DateTimeWidget` are not exported there. Because the match is by
36
+ name, a site can declare `type Code = string` itself and get the widget.
37
+ - `TextWidget` and `ButtonWidget` have no format. They are plain text fields.
38
+
39
+ The alias also works inside the annotation: `ImageWidget[]` sets the format on
40
+ the items, and `ImageWidget | null` or an optional field works too. The match is a whole
41
+ word, so `BrandColor` does not count as `Color`.
42
+
43
+ Other names are not guessed from. For a `BrandColor` alias, put
44
+ `@format color` on the alias or on the field.
45
+
46
+ `Secret` is a masked text box, nothing more. The value is a plain string saved
47
+ in content. Real credentials belong in the deploy platform's secrets, read by
48
+ the site's code.
49
+
50
+ ## `@format` on a type alias
51
+
52
+ `@format` on a type alias reaches every field typed with it, including a
53
+ literal select and arrays of it. A field's own `@format` still wins.
54
+
55
+ ```ts
56
+ /** @format color */
57
+ type TextTone = "black" | "white";
58
+
59
+ interface Props {
60
+ /** @title Text color */
61
+ tone: TextTone; // select with format "color"
62
+ /** @title Palette */
63
+ palette: TextTone[]; // items get format "color"
64
+ }
65
+ ```
66
+
67
+ ## `@format` values
68
+
69
+ The generator passes any `@format` value through unchanged, except `datetime`,
70
+ which it rewrites to `date-time` (`FORMAT_ALIASES`).
71
+
72
+ `deco check` validates only three formats on saved content:
73
+
74
+ | `@format` | `deco check` accepts |
75
+ |---|---|
76
+ | `date` | A real calendar date, `YYYY-MM-DD` |
77
+ | `date-time` | A date, `T` or a space, and a time; seconds and zone optional |
78
+ | `uri` | A parseable URL with a scheme |
79
+
80
+ Every other format (`image-uri`, `color`, `rich-text`, `textarea`, `html`…)
81
+ names a widget, not a rule. `deco check` accepts any string there.
82
+
83
+ Whether Studio draws a special widget for a format outside the alias table is
84
+ Studio's decision, not the generator's. Open the form and look before you rely
85
+ on one.
86
+
87
+ `@format dynamic-options` is kept in the schema, but in v8 it gives a text
88
+ field: the site editor never runs site code, so there are no suggestions. See
89
+ the `@options` section of [annotations.md](./annotations.md).
90
+
91
+ ## Picking a text widget
92
+
93
+ - **`RichText`** when the editor needs bold or an inline link. One rich-text
94
+ field beats a text field plus a separate URL field.
95
+ - **`TextArea`** for plain running text.
96
+ - A bare `string` for one line.
97
+ - **`HTMLWidget`** only for markup pasted from elsewhere. It gives the least
98
+ protection against an editor breaking the page.
99
+
100
+ ## Never a bare string where a widget exists
101
+
102
+ A `videoSrc: string` renders as a text box that asks an editor for a URL. Use
103
+ `VideoWidget`. The same goes for images (`ImageWidget`) and colors (`Color`):
104
+ no free-text field holding an image URL, no raw hex string without a color
105
+ picker.
106
+
107
+ Name the field for what it holds. Once a field is titled "Video (MP4 URL)",
108
+ editors keep pasting URLs even after a picker arrives. Title it "Video
109
+ (desktop)" and say in `@description` what an empty value does.
110
+
111
+ For what an image field's `@description` should say about sizes, see the
112
+ `deco-images-media` skill.