@decocms/blocks 8.9.1 → 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 (409) hide show
  1. package/dist/index.d.ts +1 -1
  2. package/dist/index.d.ts.map +1 -1
  3. package/dist/index.js +1 -1
  4. package/dist/index.js.map +1 -1
  5. package/dist/protocol/channel.d.ts +98 -0
  6. package/dist/protocol/channel.d.ts.map +1 -0
  7. package/dist/protocol/channel.js +58 -0
  8. package/dist/protocol/channel.js.map +1 -0
  9. package/dist/protocol/client.js +2 -2
  10. package/dist/protocol/client.js.map +1 -1
  11. package/dist/protocol/conformance/blockMetaVectors.json +214 -0
  12. package/dist/protocol/conformance/contentHashFixtures.d.ts +22 -0
  13. package/dist/protocol/conformance/contentHashFixtures.d.ts.map +1 -1
  14. package/dist/protocol/conformance/contentHashFixtures.js +55 -0
  15. package/dist/protocol/conformance/contentHashFixtures.js.map +1 -1
  16. package/dist/protocol/conformance/index.d.ts +2 -1
  17. package/dist/protocol/conformance/index.d.ts.map +1 -1
  18. package/dist/protocol/conformance/index.js +2 -1
  19. package/dist/protocol/conformance/index.js.map +1 -1
  20. package/dist/protocol/conformance/vectors.d.ts +33 -0
  21. package/dist/protocol/conformance/vectors.d.ts.map +1 -0
  22. package/dist/protocol/conformance/vectors.js +3 -0
  23. package/dist/protocol/conformance/vectors.js.map +1 -0
  24. package/dist/protocol/index.d.ts +11 -1
  25. package/dist/protocol/index.d.ts.map +1 -1
  26. package/dist/protocol/index.js +11 -1
  27. package/dist/protocol/index.js.map +1 -1
  28. package/dist/protocol/keys.d.ts +1 -1
  29. package/dist/protocol/keys.js +1 -1
  30. package/dist/v8/background.d.ts +13 -0
  31. package/dist/v8/background.d.ts.map +1 -1
  32. package/dist/v8/background.js +41 -0
  33. package/dist/v8/background.js.map +1 -1
  34. package/dist/v8/blockMeta.d.ts +27 -0
  35. package/dist/v8/blockMeta.d.ts.map +1 -0
  36. package/dist/v8/blockMeta.js +75 -0
  37. package/dist/v8/blockMeta.js.map +1 -0
  38. package/dist/v8/blockStore.d.ts +43 -0
  39. package/dist/v8/blockStore.d.ts.map +1 -0
  40. package/dist/v8/blockStore.js +95 -0
  41. package/dist/v8/blockStore.js.map +1 -0
  42. package/dist/v8/boundedJson.d.ts +5 -0
  43. package/dist/v8/boundedJson.d.ts.map +1 -1
  44. package/dist/v8/boundedJson.js +10 -2
  45. package/dist/v8/boundedJson.js.map +1 -1
  46. package/dist/v8/boundedMap.d.ts +19 -0
  47. package/dist/v8/boundedMap.d.ts.map +1 -0
  48. package/dist/v8/boundedMap.js +52 -0
  49. package/dist/v8/boundedMap.js.map +1 -0
  50. package/dist/v8/builtins/data.d.ts +18 -2
  51. package/dist/v8/builtins/data.d.ts.map +1 -1
  52. package/dist/v8/builtins/data.js +17 -1
  53. package/dist/v8/builtins/data.js.map +1 -1
  54. package/dist/v8/builtins/index.d.ts.map +1 -1
  55. package/dist/v8/builtins/index.js +2 -1
  56. package/dist/v8/builtins/index.js.map +1 -1
  57. package/dist/v8/builtins/legacy.d.ts +6 -3
  58. package/dist/v8/builtins/legacy.d.ts.map +1 -1
  59. package/dist/v8/builtins/legacy.js +6 -3
  60. package/dist/v8/builtins/legacy.js.map +1 -1
  61. package/dist/v8/canonical.d.ts +8 -0
  62. package/dist/v8/canonical.d.ts.map +1 -1
  63. package/dist/v8/canonical.js +15 -0
  64. package/dist/v8/canonical.js.map +1 -1
  65. package/dist/v8/cli/builtins.d.ts.map +1 -1
  66. package/dist/v8/cli/builtins.js +1 -0
  67. package/dist/v8/cli/builtins.js.map +1 -1
  68. package/dist/v8/cli/check/index.d.ts +10 -0
  69. package/dist/v8/cli/check/index.d.ts.map +1 -1
  70. package/dist/v8/cli/check/index.js +91 -7
  71. package/dist/v8/cli/check/index.js.map +1 -1
  72. package/dist/v8/cli/content.d.ts +12 -25
  73. package/dist/v8/cli/content.d.ts.map +1 -1
  74. package/dist/v8/cli/content.js +46 -75
  75. package/dist/v8/cli/content.js.map +1 -1
  76. package/dist/v8/cli/index.d.ts +2 -2
  77. package/dist/v8/cli/index.d.ts.map +1 -1
  78. package/dist/v8/cli/index.js +2 -2
  79. package/dist/v8/cli/index.js.map +1 -1
  80. package/dist/v8/cli/remote/commands.d.ts +71 -0
  81. package/dist/v8/cli/remote/commands.d.ts.map +1 -0
  82. package/dist/v8/cli/remote/commands.js +644 -0
  83. package/dist/v8/cli/remote/commands.js.map +1 -0
  84. package/dist/v8/cli/remote/diff.d.ts +15 -0
  85. package/dist/v8/cli/remote/diff.d.ts.map +1 -0
  86. package/dist/v8/cli/remote/diff.js +102 -0
  87. package/dist/v8/cli/remote/diff.js.map +1 -0
  88. package/dist/v8/cli/remote/env.d.ts +35 -0
  89. package/dist/v8/cli/remote/env.d.ts.map +1 -0
  90. package/dist/v8/cli/remote/env.js +84 -0
  91. package/dist/v8/cli/remote/env.js.map +1 -0
  92. package/dist/v8/cli/remote/http.d.ts +149 -0
  93. package/dist/v8/cli/remote/http.d.ts.map +1 -0
  94. package/dist/v8/cli/remote/http.js +381 -0
  95. package/dist/v8/cli/remote/http.js.map +1 -0
  96. package/dist/v8/cli/remote/local.d.ts +90 -0
  97. package/dist/v8/cli/remote/local.d.ts.map +1 -0
  98. package/dist/v8/cli/remote/local.js +309 -0
  99. package/dist/v8/cli/remote/local.js.map +1 -0
  100. package/dist/v8/cli/root.d.ts +29 -0
  101. package/dist/v8/cli/root.d.ts.map +1 -1
  102. package/dist/v8/cli/root.js +28 -0
  103. package/dist/v8/cli/root.js.map +1 -1
  104. package/dist/v8/cli/run.d.ts +13 -1
  105. package/dist/v8/cli/run.d.ts.map +1 -1
  106. package/dist/v8/cli/run.js +310 -124
  107. package/dist/v8/cli/run.js.map +1 -1
  108. package/dist/v8/cli/schema/builtinSchemas.d.ts.map +1 -1
  109. package/dist/v8/cli/schema/builtinSchemas.js +28 -10
  110. package/dist/v8/cli/schema/builtinSchemas.js.map +1 -1
  111. package/dist/v8/cli/schema/generate.js +1 -1
  112. package/dist/v8/cli/schema/generate.js.map +1 -1
  113. package/dist/v8/cli/skills.d.ts +25 -0
  114. package/dist/v8/cli/skills.d.ts.map +1 -0
  115. package/dist/v8/cli/skills.js +70 -0
  116. package/dist/v8/cli/skills.js.map +1 -0
  117. package/dist/v8/client.d.ts +9 -9
  118. package/dist/v8/client.d.ts.map +1 -1
  119. package/dist/v8/client.js +138 -50
  120. package/dist/v8/client.js.map +1 -1
  121. package/dist/v8/cms.d.ts +2 -1
  122. package/dist/v8/cms.d.ts.map +1 -1
  123. package/dist/v8/cms.js +55 -46
  124. package/dist/v8/cms.js.map +1 -1
  125. package/dist/v8/content.d.ts +39 -78
  126. package/dist/v8/content.d.ts.map +1 -1
  127. package/dist/v8/content.js +155 -195
  128. package/dist/v8/content.js.map +1 -1
  129. package/dist/v8/contentIndex.d.ts +71 -0
  130. package/dist/v8/contentIndex.d.ts.map +1 -0
  131. package/dist/v8/contentIndex.js +137 -0
  132. package/dist/v8/contentIndex.js.map +1 -0
  133. package/dist/v8/draft.d.ts +7 -7
  134. package/dist/v8/draft.d.ts.map +1 -1
  135. package/dist/v8/draft.js +10 -9
  136. package/dist/v8/draft.js.map +1 -1
  137. package/dist/v8/draftChanges.d.ts +59 -32
  138. package/dist/v8/draftChanges.d.ts.map +1 -1
  139. package/dist/v8/draftChanges.js +139 -75
  140. package/dist/v8/draftChanges.js.map +1 -1
  141. package/dist/v8/errors.d.ts +21 -0
  142. package/dist/v8/errors.d.ts.map +1 -1
  143. package/dist/v8/errors.js +22 -0
  144. package/dist/v8/errors.js.map +1 -1
  145. package/dist/v8/hostedSource.d.ts +57 -0
  146. package/dist/v8/hostedSource.d.ts.map +1 -0
  147. package/dist/v8/hostedSource.js +18 -0
  148. package/dist/v8/hostedSource.js.map +1 -0
  149. package/dist/v8/identity.d.ts +1 -1
  150. package/dist/v8/identity.js +1 -1
  151. package/dist/v8/index.d.ts +1 -0
  152. package/dist/v8/index.d.ts.map +1 -1
  153. package/dist/v8/index.js +1 -0
  154. package/dist/v8/index.js.map +1 -1
  155. package/dist/v8/matchRoute.js +7 -4
  156. package/dist/v8/matchRoute.js.map +1 -1
  157. package/dist/v8/pin.d.ts +34 -0
  158. package/dist/v8/pin.d.ts.map +1 -0
  159. package/dist/v8/pin.js +156 -0
  160. package/dist/v8/pin.js.map +1 -0
  161. package/dist/v8/preview/StudioBridge.d.ts +8 -8
  162. package/dist/v8/preview/StudioBridge.d.ts.map +1 -1
  163. package/dist/v8/preview/StudioBridge.js +8 -10
  164. package/dist/v8/preview/StudioBridge.js.map +1 -1
  165. package/dist/v8/preview/StudioChannel.d.ts +51 -0
  166. package/dist/v8/preview/StudioChannel.d.ts.map +1 -0
  167. package/dist/v8/preview/StudioChannel.js +104 -0
  168. package/dist/v8/preview/StudioChannel.js.map +1 -0
  169. package/dist/v8/preview/index.d.ts +3 -0
  170. package/dist/v8/preview/index.d.ts.map +1 -1
  171. package/dist/v8/preview/index.js +3 -0
  172. package/dist/v8/preview/index.js.map +1 -1
  173. package/dist/v8/remoteLoader.d.ts +42 -5
  174. package/dist/v8/remoteLoader.d.ts.map +1 -1
  175. package/dist/v8/remoteLoader.js +317 -259
  176. package/dist/v8/remoteLoader.js.map +1 -1
  177. package/dist/v8/resolver.d.ts +22 -8
  178. package/dist/v8/resolver.d.ts.map +1 -1
  179. package/dist/v8/resolver.js +37 -32
  180. package/dist/v8/resolver.js.map +1 -1
  181. package/dist/v8/revisionId.d.ts +11 -0
  182. package/dist/v8/revisionId.d.ts.map +1 -0
  183. package/dist/v8/revisionId.js +13 -0
  184. package/dist/v8/revisionId.js.map +1 -0
  185. package/dist/v8/settings.d.ts +6 -6
  186. package/dist/v8/settings.d.ts.map +1 -1
  187. package/dist/v8/settings.js +8 -7
  188. package/dist/v8/settings.js.map +1 -1
  189. package/dist/v8/telemetry.d.ts +4 -2
  190. package/dist/v8/telemetry.d.ts.map +1 -1
  191. package/dist/v8/telemetry.js +2 -2
  192. package/dist/v8/telemetry.js.map +1 -1
  193. package/dist/v8/types.d.ts +52 -40
  194. package/dist/v8/types.d.ts.map +1 -1
  195. package/dist/v8/variants.d.ts +7 -2
  196. package/dist/v8/variants.d.ts.map +1 -1
  197. package/dist/v8/variants.js +21 -24
  198. package/dist/v8/variants.js.map +1 -1
  199. package/dist/v8/vite/index.d.ts +2 -2
  200. package/dist/v8/vite/index.js +1 -1
  201. package/dist/v8/vite/index.js.map +1 -1
  202. package/package.json +3 -2
  203. package/skills/deco-apps/SKILL.md +82 -0
  204. package/skills/deco-apps/references/algolia.md +51 -0
  205. package/skills/deco-apps/references/commerce-types.md +132 -0
  206. package/skills/deco-apps/references/instrumented-fetch.md +144 -0
  207. package/skills/deco-apps/references/magento.md +55 -0
  208. package/skills/deco-apps/references/messaging.md +76 -0
  209. package/skills/deco-apps/references/shopify.md +69 -0
  210. package/skills/deco-apps/references/vendored-loaders.md +135 -0
  211. package/skills/deco-apps/references/vtex-cookies-auth.md +146 -0
  212. package/skills/deco-apps/references/vtex.md +150 -0
  213. package/skills/deco-apps/references/wake.md +75 -0
  214. package/skills/deco-cms-schema/SKILL.md +80 -0
  215. package/skills/deco-cms-schema/references/annotations.md +147 -0
  216. package/skills/deco-cms-schema/references/content-hygiene.md +91 -0
  217. package/skills/deco-cms-schema/references/formats-and-widgets.md +112 -0
  218. package/skills/deco-cms-schema/references/shapes-that-break-the-form.md +165 -0
  219. package/skills/deco-cms-schema/references/types-to-fields.md +112 -0
  220. package/skills/deco-go-live/SKILL.md +127 -0
  221. package/skills/deco-go-live/references/content-releases.md +90 -0
  222. package/skills/deco-go-live/references/process.md +106 -0
  223. package/skills/deco-go-live/references/proxy-headers-checkout.md +139 -0
  224. package/skills/deco-go-live/references/qa-checklist-template.md +150 -0
  225. package/skills/deco-go-live/references/qa-inventory.md +120 -0
  226. package/skills/deco-go-live/references/react-spa.md +183 -0
  227. package/skills/deco-go-live/references/seo-analytics.md +114 -0
  228. package/skills/deco-go-live/references/traffic-ramp.md +87 -0
  229. package/skills/deco-go-live/references/worker-runtime.md +93 -0
  230. package/skills/deco-go-live/scripts/preflight.sh +221 -0
  231. package/skills/deco-images-media/SKILL.md +64 -0
  232. package/skills/deco-images-media/references/asset-upload.md +191 -0
  233. package/skills/deco-images-media/references/components-per-binding.md +167 -0
  234. package/skills/deco-images-media/references/providers-and-cdn.md +145 -0
  235. package/skills/deco-images-media/references/quality-and-lcp.md +93 -0
  236. package/skills/deco-images-media/references/troubleshooting.md +147 -0
  237. package/skills/deco-images-media/references/video.md +122 -0
  238. package/skills/deco-make-editable/SKILL.md +94 -0
  239. package/skills/deco-make-editable/references/a11y-and-e2e.md +104 -0
  240. package/skills/deco-make-editable/references/content-shapes.md +198 -0
  241. package/skills/deco-make-editable/references/from-figma.md +110 -0
  242. package/skills/deco-make-editable/references/i18n-fields.md +112 -0
  243. package/skills/deco-make-editable/references/inventory.md +79 -0
  244. package/skills/deco-make-editable/references/pixel-parity.md +175 -0
  245. package/skills/deco-make-editable/references/seeding-content.md +119 -0
  246. package/skills/deco-nextjs-site/SKILL.md +74 -0
  247. package/skills/deco-nextjs-site/references/caching.md +116 -0
  248. package/skills/deco-nextjs-site/references/metadata-seo.md +100 -0
  249. package/skills/deco-nextjs-site/references/proxy-and-drafts.md +177 -0
  250. package/skills/deco-nextjs-site/references/rendering.md +171 -0
  251. package/skills/deco-nextjs-site/references/setup.md +190 -0
  252. package/skills/deco-nextjs-site/references/studio-bridge.md +130 -0
  253. package/skills/deco-site-authoring/SKILL.md +75 -0
  254. package/skills/deco-site-authoring/references/lazy-blocks.md +155 -0
  255. package/skills/deco-site-authoring/references/loaders.md +192 -0
  256. package/skills/deco-site-authoring/references/pages.md +156 -0
  257. package/skills/deco-site-authoring/references/review-before-publish.md +95 -0
  258. package/skills/deco-site-authoring/references/sections.md +158 -0
  259. package/skills/deco-site-authoring/references/seo.md +116 -0
  260. package/skills/deco-site-workflow/SKILL.md +92 -0
  261. package/skills/deco-site-workflow/references/check.md +116 -0
  262. package/skills/deco-site-workflow/references/cli-reference.md +104 -0
  263. package/skills/deco-site-workflow/references/content-layout.md +93 -0
  264. package/skills/deco-site-workflow/references/content-sync.md +146 -0
  265. package/skills/deco-site-workflow/references/delivery.md +51 -0
  266. package/skills/deco-site-workflow/references/deploy.md +87 -0
  267. package/skills/deco-site-workflow/references/schema.md +173 -0
  268. package/skills/deco-site-workflow/references/serve-and-studio.md +138 -0
  269. package/skills/deco-storefront-caching/SKILL.md +67 -0
  270. package/skills/deco-storefront-caching/references/cache-keys.md +129 -0
  271. package/skills/deco-storefront-caching/references/case-study.md +82 -0
  272. package/skills/deco-storefront-caching/references/egress-traps.md +153 -0
  273. package/skills/deco-storefront-caching/references/nextjs.md +60 -0
  274. package/skills/deco-storefront-caching/references/perf-guardrails-e2e.md +123 -0
  275. package/skills/deco-storefront-caching/references/verification.md +136 -0
  276. package/skills/deco-storefront-caching/references/worker-page-cache.md +160 -0
  277. package/skills/deco-storefront-caching/scripts/html-anatomy.mjs +97 -0
  278. package/skills/deco-storefront-performance/SKILL.md +81 -0
  279. package/skills/deco-storefront-performance/references/cls-third-party.md +90 -0
  280. package/skills/deco-storefront-performance/references/hydration.md +116 -0
  281. package/skills/deco-storefront-performance/references/loaders-n-plus-1.md +107 -0
  282. package/skills/deco-storefront-performance/references/navigation-ux.md +130 -0
  283. package/skills/deco-storefront-performance/references/payload-trim.md +163 -0
  284. package/skills/deco-storefront-performance/references/render-location.md +152 -0
  285. package/skills/deco-storefront-performance/references/request-dedupe.md +147 -0
  286. package/skills/deco-storefront-performance/references/trace-reading.md +79 -0
  287. package/skills/deco-storefront-performance/references/worker-memory.md +176 -0
  288. package/skills/deco-tanstack-site/SKILL.md +68 -0
  289. package/skills/deco-tanstack-site/references/document-and-security.md +155 -0
  290. package/skills/deco-tanstack-site/references/router-and-navigation.md +137 -0
  291. package/skills/deco-tanstack-site/references/routes-and-pages.md +183 -0
  292. package/skills/deco-tanstack-site/references/server-functions.md +123 -0
  293. package/skills/deco-tanstack-site/references/setup.md +153 -0
  294. package/skills/deco-tanstack-site/references/worker-entry.md +152 -0
  295. package/skills/deco-v7-to-v8-migration/SKILL.md +122 -0
  296. package/skills/deco-v7-to-v8-migration/references/caching-and-privacy.md +10 -0
  297. package/skills/deco-v7-to-v8-migration/references/content.md +25 -0
  298. package/skills/deco-v7-to-v8-migration/references/editor-forms.md +27 -0
  299. package/skills/deco-v7-to-v8-migration/references/faststore.md +40 -0
  300. package/skills/deco-v7-to-v8-migration/references/framework-code.md +53 -0
  301. package/skills/deco-v7-to-v8-migration/references/hosted-releases.md +16 -0
  302. package/skills/deco-v7-to-v8-migration/references/import-map.md +81 -0
  303. package/skills/deco-v7-to-v8-migration/references/legacy-names.md +33 -0
  304. package/skills/deco-v7-to-v8-migration/references/manual-steps.md +10 -0
  305. package/skills/deco-v7-to-v8-migration/references/native-apps.md +43 -0
  306. package/skills/deco-v7-to-v8-migration/references/nextjs.md +19 -0
  307. package/skills/deco-v7-to-v8-migration/references/parity.md +66 -0
  308. package/skills/deco-v7-to-v8-migration/references/rendering.md +13 -0
  309. package/skills/deco-v7-to-v8-migration/references/running-the-script.md +29 -0
  310. package/skills/deco-v7-to-v8-migration/references/script-steps.md +13 -0
  311. package/skills/deco-v7-to-v8-migration/references/server-functions.md +15 -0
  312. package/skills/deco-v7-to-v8-migration/references/sibling-port.md +11 -0
  313. package/skills/deco-v7-to-v8-migration/references/site-code.md +15 -0
  314. package/skills/deco-v7-to-v8-migration/references/telemetry.md +10 -0
  315. package/skills/deco-v7-to-v8-migration/references/verify.md +20 -0
  316. package/skills/deco-v7-to-v8-migration/scripts/apps.ts +297 -0
  317. package/skills/deco-v7-to-v8-migration/scripts/asyncRendering.ts +73 -0
  318. package/skills/deco-v7-to-v8-migration/scripts/blockMap.ts +584 -0
  319. package/skills/deco-v7-to-v8-migration/scripts/ciSchemaCheck.ts +145 -0
  320. package/skills/deco-v7-to-v8-migration/scripts/compat.ts +357 -0
  321. package/skills/deco-v7-to-v8-migration/scripts/content.ts +121 -0
  322. package/skills/deco-v7-to-v8-migration/scripts/experiments.ts +81 -0
  323. package/skills/deco-v7-to-v8-migration/scripts/framework.ts +61 -0
  324. package/skills/deco-v7-to-v8-migration/scripts/imageCopy.ts +276 -0
  325. package/skills/deco-v7-to-v8-migration/scripts/imageModule.ts +285 -0
  326. package/skills/deco-v7-to-v8-migration/scripts/imports.ts +942 -0
  327. package/skills/deco-v7-to-v8-migration/scripts/invoke.ts +624 -0
  328. package/skills/deco-v7-to-v8-migration/scripts/legacyNames.ts +45 -0
  329. package/skills/deco-v7-to-v8-migration/scripts/main.ts +59 -0
  330. package/skills/deco-v7-to-v8-migration/scripts/matchers.ts +41 -0
  331. package/skills/deco-v7-to-v8-migration/scripts/migrate.ts +176 -0
  332. package/skills/deco-v7-to-v8-migration/scripts/redirects.ts +455 -0
  333. package/skills/deco-v7-to-v8-migration/scripts/report.ts +50 -0
  334. package/skills/deco-v7-to-v8-migration/scripts/scaffold.ts +1119 -0
  335. package/skills/deco-v7-to-v8-migration/scripts/secrets.ts +35 -0
  336. package/skills/deco-v7-to-v8-migration/scripts/sectionLoaders.ts +216 -0
  337. package/skills/deco-v7-to-v8-migration/scripts/siteSettings.ts +261 -0
  338. package/skills/deco-v7-to-v8-migration/scripts/stubs.ts +388 -0
  339. package/skills/deco-v7-to-v8-migration/scripts/tsconfig.json +7 -0
  340. package/skills/deco-v7-to-v8-migration/scripts/vendor.ts +249 -0
  341. package/skills/deco-v7-to-v8-migration/scripts/vtexInvoke.ts +240 -0
  342. package/skills/deco-v7-to-v8-migration/scripts/walk.ts +30 -0
  343. package/skills/deco-variants/SKILL.md +57 -0
  344. package/skills/deco-variants/references/caching-variants.md +63 -0
  345. package/skills/deco-variants/references/custom-matchers.md +83 -0
  346. package/skills/deco-variants/references/draft-preview.md +59 -0
  347. package/skills/deco-variants/references/experiments-and-campaigns.md +104 -0
  348. package/skills/deco-variants/references/multivariate.md +85 -0
  349. package/skills/deco-variants/references/v7-matchers.md +71 -0
  350. package/src/index.ts +2 -0
  351. package/src/protocol/channel.ts +127 -0
  352. package/src/protocol/client.ts +2 -2
  353. package/src/protocol/conformance/blockMetaVectors.json +214 -0
  354. package/src/protocol/conformance/contentHashFixtures.ts +74 -0
  355. package/src/protocol/conformance/index.ts +9 -1
  356. package/src/protocol/conformance/vectors.ts +36 -0
  357. package/src/protocol/index.ts +32 -0
  358. package/src/protocol/keys.ts +1 -1
  359. package/src/v8/background.ts +42 -0
  360. package/src/v8/blockMeta.ts +100 -0
  361. package/src/v8/blockStore.ts +124 -0
  362. package/src/v8/boundedJson.ts +20 -2
  363. package/src/v8/boundedMap.ts +53 -0
  364. package/src/v8/builtins/data.ts +26 -2
  365. package/src/v8/builtins/index.ts +2 -1
  366. package/src/v8/builtins/legacy.ts +6 -3
  367. package/src/v8/canonical.ts +15 -0
  368. package/src/v8/cli/builtins.ts +1 -0
  369. package/src/v8/cli/check/index.ts +97 -7
  370. package/src/v8/cli/content.ts +49 -91
  371. package/src/v8/cli/index.ts +2 -2
  372. package/src/v8/cli/remote/commands.ts +834 -0
  373. package/src/v8/cli/remote/diff.ts +100 -0
  374. package/src/v8/cli/remote/env.ts +107 -0
  375. package/src/v8/cli/remote/http.ts +484 -0
  376. package/src/v8/cli/remote/local.ts +343 -0
  377. package/src/v8/cli/root.ts +40 -0
  378. package/src/v8/cli/run.ts +366 -135
  379. package/src/v8/cli/schema/builtinSchemas.ts +29 -10
  380. package/src/v8/cli/schema/generate.ts +1 -1
  381. package/src/v8/cli/skills.ts +91 -0
  382. package/src/v8/client.ts +162 -60
  383. package/src/v8/cms.ts +62 -53
  384. package/src/v8/content.ts +179 -229
  385. package/src/v8/contentIndex.ts +183 -0
  386. package/src/v8/draft.ts +15 -14
  387. package/src/v8/draftChanges.ts +151 -85
  388. package/src/v8/errors.ts +37 -0
  389. package/src/v8/hostedSource.ts +67 -0
  390. package/src/v8/identity.ts +1 -1
  391. package/src/v8/index.ts +1 -0
  392. package/src/v8/matchRoute.ts +7 -4
  393. package/src/v8/pin.ts +176 -0
  394. package/src/v8/preview/StudioBridge.ts +8 -10
  395. package/src/v8/preview/StudioChannel.ts +116 -0
  396. package/src/v8/preview/index.ts +3 -0
  397. package/src/v8/remoteLoader.ts +350 -286
  398. package/src/v8/resolver.ts +56 -33
  399. package/src/v8/revisionId.ts +14 -0
  400. package/src/v8/settings.ts +10 -9
  401. package/src/v8/telemetry.ts +3 -3
  402. package/src/v8/types.ts +52 -40
  403. package/src/v8/variants.ts +30 -26
  404. package/src/v8/vite/index.ts +3 -3
  405. package/dist/v8/cli/serve/server.d.ts +0 -29
  406. package/dist/v8/cli/serve/server.d.ts.map +0 -1
  407. package/dist/v8/cli/serve/server.js +0 -296
  408. package/dist/v8/cli/serve/server.js.map +0 -1
  409. package/src/v8/cli/serve/server.ts +0 -348
@@ -0,0 +1,104 @@
1
+ # Accessibility and functional checks
2
+
3
+ Pixel parity proves a section looks right with today's content. These checks
4
+ prove it works, for every visitor, and keeps working when editors change the
5
+ content.
6
+
7
+ Deeper checklists live in other skills; this file lists what a conversion or a
8
+ Figma build must not skip:
9
+
10
+ - `deco-go-live`: a QA checklist built from the site's blocks and routes.
11
+ - `deco-images-media` and `deco-storefront-performance`: images, LCP, CLS,
12
+ heavy HTML.
13
+
14
+ ## Content robustness
15
+
16
+ Editors will do things the design never showed. For each section, try:
17
+
18
+ - every optional field empty: no empty heading tag, no dangling separator, no
19
+ broken layout;
20
+ - a text three times longer than the design's, and a one-word one;
21
+ - a list with zero items, one item, and more items than the design shows;
22
+ - a section removed, and the same section added twice to one page;
23
+ - an image with a different aspect ratio than the design's.
24
+
25
+ A section that renders nothing when its main content is empty is better than
26
+ one that renders an empty box. A section added twice must not reuse an `id`
27
+ (two `id="faq"` break anchors and `aria-controls`).
28
+
29
+ ## Accessibility
30
+
31
+ - **Headings:** one `h1` per page, then `h2` and `h3` in order. A section's
32
+ heading level must not depend on where an editor puts it: when a section can
33
+ be first on a page (and become the `h1`), give it a prop for the level or
34
+ keep the `h1` in a section that only goes first.
35
+ - **Images:** every content image has `alt` text, and the `alt` is a field
36
+ next to the image in the form. Decorative images have `alt=""`.
37
+ - **Links and buttons:** every icon-only control has an accessible name
38
+ (`aria-label`, kept in code). Links that open a new tab say so to screen
39
+ readers.
40
+ - **Contrast:** WCAG AA, 4.5:1 for normal text, 3:1 for large text and UI
41
+ parts. When editors choose colors or put text over an image they choose,
42
+ contrast is their choice: add an overlay or a text color option to the
43
+ section instead of trusting each image.
44
+ - **Keyboard:** every interactive element is reachable with Tab, shows a
45
+ visible focus ring, and works with Enter or Space. Menus and drawers close
46
+ with Escape and return focus to the button that opened them.
47
+ - **Language:** `<html lang>` matches the page's language on a two-language
48
+ site (`DecoDocument` takes a `lang` prop on TanStack Start).
49
+ - A skip link to the main content, when the header has many links.
50
+
51
+ Run an automated pass (axe or Lighthouse) on each converted page as a floor,
52
+ not as proof.
53
+
54
+ ## Functional checks
55
+
56
+ Walk each converted page on desktop (1440px) and mobile (375px or 390px).
57
+
58
+ **Header and navigation**
59
+
60
+ - The logo links home. Every menu link goes where its `href` says, with the
61
+ locale prefix on secondary-language pages.
62
+ - Dropdowns or mega menus open on hover and on keyboard focus.
63
+ - Mobile: the menu button opens the drawer, nested items expand and collapse,
64
+ the drawer closes on navigation and on a backdrop tap.
65
+ - A sticky header does not cover anchored headings (`scroll-margin-top`).
66
+
67
+ **Content sections**
68
+
69
+ - Calls to action link to the right page. External links open in a new tab.
70
+ - Carousels: arrows and dots work, swipe works on mobile, autoplay stops on
71
+ hover and focus.
72
+ - Accordions and tabs work with the keyboard.
73
+ - Forms (newsletter, contact) submit, show success and error states, and
74
+ keep their messages in code, not in a block.
75
+
76
+ **Footer**
77
+
78
+ - Every link column renders and links work. Social and payment icons render.
79
+ - Mobile: columns stack or collapse as designed.
80
+
81
+ **Mobile**
82
+
83
+ - Touch targets are at least 44×44px.
84
+ - No horizontal scroll at 375px.
85
+ - Body text is at least 16px.
86
+ - Fixed or sticky bars do not hide content.
87
+
88
+ ## Performance, briefly
89
+
90
+ - The page's LCP image uses `preload`; every other image loads lazily.
91
+ - Every image has `width` and `height`, so nothing shifts while it loads.
92
+ - Deferring sections far below the fold (the built-in `lazy` block, loading
93
+ skeletons) is covered in `deco-site-authoring`.
94
+ - Compare the HTML size of a converted page with `main`. Content from a block
95
+ should not make a page heavier than the hardcoded version.
96
+
97
+ ## Automate what you repeat
98
+
99
+ When a check runs on every PR (menu links, the mobile drawer, the CTA
100
+ targets), write it as a Playwright test against the dev server. Keep the tests
101
+ on behavior and roles (`getByRole("navigation")`, `getByRole("button", { name:
102
+ "Open menu" })` for interface text kept in code), not on CSS classes or
103
+ positions, so an editor reordering sections or rewording a heading does not
104
+ break them.
@@ -0,0 +1,198 @@
1
+ # The three content shapes
2
+
3
+ Every piece of content from the [inventory](./inventory.md) takes one of three
4
+ shapes. Pick the shape first; the code follows from it.
5
+
6
+ | Shape | Use for | Saved as | Read with |
7
+ |---|---|---|---|
8
+ | **Global block** | Things on every page: header menu, footer, a top banner | One saved block with a fixed name, e.g. `.deco/blocks/Header%20menu.json` | `client.resolve("Header menu")` in a loader shared by every page |
9
+ | **Composed page** | Pages editors rearrange: home, landings | A saved block of type `page` with `name`, `path`, `seo` and `sections` | `client.routes()` + `matchRoute`, then `client.resolve(name)` |
10
+ | **Collection** | Many documents of one kind: articles, FAQ entries, store addresses | One saved block per document, all of one type | `client.list(type, { where, sort, limit })` |
11
+
12
+ A saved block's file name is `encodeURIComponent(name) + ".json"`, so the
13
+ block named `Header menu` lives in `Header%20menu.json`. Subfolders of
14
+ `.deco/blocks` are not read. A saved block cannot take the name of a block
15
+ type or a built-in (`page`, `lazy`, `multivariate`, …): `deco check` reports
16
+ it.
17
+
18
+ The site wiring around these (the client, the catch-all route, the worker) is
19
+ in `deco-tanstack-site` or `deco-nextjs-site`. The examples below assume a
20
+ TanStack Start site with `src/cms.ts` exporting `cms` from `createCMS`, as in
21
+ `examples/tanstack-worker-smoke`.
22
+
23
+ ## Sections: JSX or descriptors
24
+
25
+ A block function that returns JSX, or a `{ component, props }` object, is a
26
+ section: Studio offers it wherever a section fits. `tanstack-smoke` and
27
+ `tanstack-worker-smoke` in `examples/` return descriptors, because a server
28
+ function's result must be serialized; the site maps each descriptor to its
29
+ component when it renders. The Next.js examples and `tanstack-rsc-smoke`
30
+ (server components) return JSX from the block map (`.deco/index.tsx`).
31
+
32
+ ```ts
33
+ // .deco/index.ts
34
+ import type { Blocks, Seo } from "@decocms/blocks";
35
+ import type { HeaderMenuProps } from "../src/sections/HeaderMenu";
36
+ import type { HeroProps } from "../src/sections/Hero";
37
+
38
+ export type Section =
39
+ | { component: "header-menu"; props: HeaderMenuProps }
40
+ | { component: "hero"; props: HeroProps };
41
+
42
+ export default {
43
+ seo: (input: Seo) => input,
44
+ "header-menu": (input: HeaderMenuProps): Section => ({ component: "header-menu", props: input }),
45
+ hero: (input: HeroProps): Section => ({ component: "hero", props: input }),
46
+ } satisfies Blocks;
47
+ ```
48
+
49
+ Run `deco schema` after every change to a `Props` type, and commit the
50
+ regenerated `.deco/schema.gen.json`. In CI, `deco schema --check` fails when
51
+ the file is out of date.
52
+
53
+ ## Global blocks
54
+
55
+ One saved block per piece, named for what editors call it:
56
+
57
+ ```json
58
+ // .deco/blocks/Header%20menu.json
59
+ {
60
+ "__resolveType": "header-menu",
61
+ "links": [
62
+ { "label": "Pricing", "href": "/pricing" },
63
+ { "label": "Docs", "href": "/docs" }
64
+ ]
65
+ }
66
+ ```
67
+
68
+ Read it once per request, in a loader every page shares (the root route on
69
+ TanStack Start), and hand the result to the layout:
70
+
71
+ ```ts
72
+ // src/global-blocks.functions.ts
73
+ import { createServerFn } from "@tanstack/react-start";
74
+ import { contentClient } from "@decocms/tanstack/server";
75
+ import type { Section } from "../.deco";
76
+ import { cms } from "./cms";
77
+
78
+ const GLOBAL_BLOCKS = ["Header menu", "Footer"] as const;
79
+
80
+ export const loadGlobalBlocks = createServerFn({ method: "GET" }).handler(async () => {
81
+ const client = contentClient(cms);
82
+ const results = await Promise.all(GLOBAL_BLOCKS.map((name) => client.resolve<Section>(name)));
83
+ return Object.fromEntries(
84
+ GLOBAL_BLOCKS.map((name, i) => {
85
+ const [value, error] = results[i]!;
86
+ if (error) console.error(name, error);
87
+ return [name, value ?? null];
88
+ }),
89
+ ) as Record<(typeof GLOBAL_BLOCKS)[number], Section | null>;
90
+ });
91
+ ```
92
+
93
+ What held up in practice:
94
+
95
+ - **List the global block names in one place.** A missing block then shows up
96
+ as one `null` you can test for, not as a header that silently renders empty.
97
+ - **No fallback copy in code.** When a block cannot be read, render nothing (or
98
+ the section's empty state) and log the error. A constant with the old menu
99
+ becomes a second source of truth that drifts from what editors see.
100
+ - **Derive what editors should not manage.** The active menu item comes from
101
+ comparing `href` with the current path, not from an extra field.
102
+ - **External links** in CMS lists still need `target="_blank"` and
103
+ `rel="noopener noreferrer"`. Set them in the component from the URL, not
104
+ from a field editors can forget.
105
+
106
+ ## Composed pages
107
+
108
+ A page is a saved block of the built-in type `page`. Its `sections` are the
109
+ blocks editors add, remove and reorder:
110
+
111
+ ```json
112
+ // .deco/blocks/Home.json
113
+ {
114
+ "__resolveType": "page",
115
+ "name": "Home",
116
+ "path": "/",
117
+ "seo": { "__resolveType": "seo", "title": "…", "description": "…" },
118
+ "sections": [
119
+ { "__resolveType": "hero", "title": "…", "cta": { "label": "…", "href": "/start" } },
120
+ { "__resolveType": "guides", "items": [] }
121
+ ]
122
+ }
123
+ ```
124
+
125
+ The page loader in `examples/tanstack-worker-smoke/src/open-page.server.ts`
126
+ does the rest: `client.routes()` lists every page's `{ name, path }` from the
127
+ index, `matchRoute(href, { routes })` picks one, and `client.resolve(name, {
128
+ run: false })` reads it, then each section resolves on its own so a slow one
129
+ does not hold the others. `deco-tanstack-site` covers the catch-all route that
130
+ calls it.
131
+
132
+ **Keep your routes.** You do not have to hand the whole site to a catch-all
133
+ route to get CMS pages. A site with content files, locale prefixes or
134
+ redirects of its own can keep its file routes and call the same page loader
135
+ only in the routes that are now CMS pages (`loadPage({ data: { href: "/" } })`
136
+ in `src/routes/index.tsx`). On TanStack Router a file route such as `/` ranks
137
+ above the `$` catch-all, so converting one route never changes the others.
138
+
139
+ **Keep the frame in code.** The header and footer around a page stay in the
140
+ layout, fed by global blocks. A page's `sections` hold only what changes from
141
+ page to page.
142
+
143
+ **Render no wrapper you did not have.** The site writes the loop that renders
144
+ each section. If the old page had no element around each section, do not add
145
+ one: an extra `<div>` breaks CSS such as `.page > section` and fails the
146
+ [HTML parity](./pixel-parity.md) check.
147
+
148
+ **The tab title can come from the page.** The `page` block's `seo` field takes
149
+ any block that returns a `Seo` (`{ title, description }`), such as the `seo`
150
+ block in the map above. A page without one falls back to the root route's
151
+ defaults.
152
+
153
+ ## Collections
154
+
155
+ A collection is a block type whose function returns its own input, with one
156
+ saved block per document:
157
+
158
+ ```ts
159
+ // src/post.ts
160
+ import type { Route } from "@decocms/blocks";
161
+
162
+ export interface Post extends Route {
163
+ /**
164
+ * @title Published on
165
+ * @format date
166
+ */
167
+ date: string;
168
+ /** @format rich-text */
169
+ body: string;
170
+ }
171
+
172
+ // .deco/index.ts
173
+ post: (input: Post) => input,
174
+ ```
175
+
176
+ Because `Post` extends `Route` (`name` and `path`), `deco schema` puts the
177
+ type in the `pages` group and `deco check` reports two posts with conflicting
178
+ paths. A type without `path` is plain content that only the site's code reads.
179
+
180
+ `client.routes()` lists only blocks of type `page`, not posts. To give each
181
+ post its own URL, list the posts and match them together with the pages, as
182
+ `examples/nextjs-binding-smoke/src/open-page.server.ts` does:
183
+ `matchRoute(href, { routes: [...routes, ...posts] })`.
184
+
185
+ List them with `client.list`:
186
+
187
+ ```ts
188
+ const [posts, error] = await client.list<Post>("post", {
189
+ sort: (a, b) => b.date.localeCompare(a.date),
190
+ limit: 20,
191
+ });
192
+ ```
193
+
194
+ `list` reads every saved block of that type whole. That is fine for an index
195
+ of tens of documents. For pages, route with `client.routes()`, which reads
196
+ only the index: `list("page")` warns outside production for that reason.
197
+
198
+ See `examples/nextjs-binding-smoke/src/app/blog/page.tsx` for a list page.
@@ -0,0 +1,110 @@
1
+ # From a Figma file to editable sections
2
+
3
+ The same method as a hardcoded site, with the design as the source: map the
4
+ file, build each section with typed props, seed the blocks with the design's
5
+ content, then compare with the design (see [pixel-parity.md](./pixel-parity.md)).
6
+
7
+ The Figma tools named here (`get_metadata`, `get_design_context`,
8
+ `get_screenshot`, `get_variable_defs`) belong to the Figma MCP server, not to
9
+ this repo. Follow that server's own instructions: it may ask for a session or
10
+ a design-to-code skill before the first read.
11
+
12
+ ## 1. Map the file
13
+
14
+ Take the file key from the URL (`figma.com/design/<fileKey>/<name>?node-id=1-2`;
15
+ a `node-id` of `1-2` is node `1:2`). Call `get_metadata` on the root node to
16
+ list pages and their top-level frames.
17
+
18
+ Map Figma pages to routes, and say which ones are not pages:
19
+
20
+ | Figma page | Route | Shape |
21
+ |---|---|---|
22
+ | Home | `/` | composed page |
23
+ | Landing / Campaign | `/campaign/...` | composed page |
24
+ | Institutional (About, Contact) | `/about`, `/contact` | composed page |
25
+ | Blog | `/blog`, `/blog/:slug` | collection (see [content-shapes.md](./content-shapes.md)) |
26
+ | Product listing, product detail, search, cart | the site's commerce routes | sections fed by loaders; see `deco-site-authoring` and `deco-apps` |
27
+ | Components / Design system | none | reusable parts, not a page |
28
+
29
+ Call `get_metadata` on each page node. Each top-level frame is usually one
30
+ section. Record for each: node id, name, page, width and position (top to
31
+ bottom is render order).
32
+
33
+ - **Desktop and mobile:** frames named `Hero - Desktop` and `Hero - Mobile`
34
+ are one section with two layouts. Frames wider than 1024px are desktop;
35
+ 375px is the usual mobile width. With only a desktop frame, build the mobile
36
+ layout with responsive styles and confirm it with the designer.
37
+ - **Shared or page-specific:** the header and footer appear on every page:
38
+ global blocks. A newsletter band on several pages is one section type used
39
+ in several pages, not a global block, unless editors want to change it in
40
+ one place.
41
+
42
+ ## 2. The section map
43
+
44
+ Before writing code, produce a table and get the user's confirmation:
45
+
46
+ | # | Section | Figma page | Node | Shape | Variants | Data | Interactive parts |
47
+ |---|---|---|---|---|---|---|---|
48
+ | 1 | Header | all | 12:34 | global block | desktop, mobile | none | mobile menu, search |
49
+ | 2 | Hero | Home | 12:56 | page section | desktop, mobile | none | carousel |
50
+ | 3 | ProductShelf | Home | 13:10 | page section | desktop | product list loader | none |
51
+
52
+ Build in this order: header, footer, the home's first section, the rest of the
53
+ home top to bottom, then the other pages. The header and footer are on every
54
+ screenshot, so getting them right first makes every later comparison cleaner.
55
+
56
+ ## 3. Design tokens
57
+
58
+ Call `get_variable_defs` on a frame to read the file's variables (colors,
59
+ spacing, type, radii). Match them to the site's existing theme first (Tailwind
60
+ config, CSS variables). Add a token only when no existing one matches, and
61
+ name it as the design names it. A section that hardcodes `#1a1a2e` where the
62
+ theme has `--color-secondary` drifts the first time the brand changes.
63
+
64
+ ## 4. Build each section
65
+
66
+ Call `get_design_context` on the frame (and on its mobile frame). It returns
67
+ reference markup, a screenshot and asset URLs. The markup is a reference to
68
+ adapt to the site's components and tokens, not code to paste.
69
+
70
+ For each section:
71
+
72
+ - **Props are the content.** Every text, link, image and list an editor could
73
+ change is a prop. Type them for the form (`deco-cms-schema`); an image is a
74
+ string typed `ImageWidget` (from `@decocms/compat-v7/types/widgets`, or any
75
+ local `type ImageWidget = string`: `deco schema` reads the name) so Studio
76
+ shows an image picker.
77
+ - **No content in default values.** The design's texts go into the seeded
78
+ blocks ([seeding-content.md](./seeding-content.md)), not into default
79
+ parameters. Defaults in code are a second copy of the content.
80
+ - **Interactive parts are small client components.** A carousel, an accordion
81
+ or a menu drawer is its own component with state; the section around it
82
+ stays plain. The examples in this repo mark such components `"use client"`,
83
+ which matters for React Server Components (Next.js). Pass them serializable
84
+ props only. `deco-site-authoring` covers this.
85
+ - **Data comes from loaders.** A shelf that shows products takes them from a
86
+ loader block, not from a fetch inside the component. See
87
+ `deco-site-authoring` and `deco-apps`.
88
+ - **Images:** render with `Image` or `Picture` from `@decocms/tanstack/react`
89
+ (or `next/image` with the deco loader on Next.js), always with `width` and
90
+ `height`. Set `preload` on the one image that is the page's LCP, usually the
91
+ first hero image; every other `Image` loads lazily by default.
92
+ - Add the section to the block map and run `deco schema`.
93
+
94
+ ## 5. Assets
95
+
96
+ The asset URLs from `get_design_context` are temporary Figma exports. Download
97
+ them, prefer the original files when the designer can export them, and put
98
+ them where the site's images live. The `deco` CLI has no asset upload command;
99
+ `deco-images-media` covers where images go and how their URLs are served.
100
+ Use the final URLs in the seeded blocks.
101
+
102
+ ## 6. Assemble the pages
103
+
104
+ Write one `page` block per Figma page, with its sections in the design's order
105
+ and the design's content in each section
106
+ ([content-shapes.md](./content-shapes.md#composed-pages)). Write the global
107
+ blocks (header, footer). Run `deco check`, or push to a draft and run
108
+ `deco check --draft=<name>` on a hosted site.
109
+
110
+ Then compare with the design: [pixel-parity.md](./pixel-parity.md#against-a-figma-design).
@@ -0,0 +1,112 @@
1
+ # Two languages: one block, `foo` and `fooPt`
2
+
3
+ `@decocms/blocks` 8 has no locale concept for content. A site with two
4
+ languages decides how content carries both. This is the convention that held
5
+ up in a real conversion of a two-language site. Rename `Pt` for your secondary
6
+ language.
7
+
8
+ ## The options, and why this one
9
+
10
+ | Option | Problem |
11
+ |---|---|
12
+ | One block per language (`Header menu`, `Header menu PT`) | Every change is made twice, and the two drift. The editors who tried it rejected it. |
13
+ | Variants that pick a language by path | Every block holds two full copies of its content, and the language rule repeats in every block. |
14
+ | An object per field (`title: { en, pt }`) | Form tags that name a string field, such as `@titleBy` for a list item's title, have no flat string to point at. |
15
+ | **A sibling field: `title` and `titlePt`** | Fields stay flat. One block, both languages side by side in the form. |
16
+
17
+ ## The convention
18
+
19
+ - **One block per piece of content, never one per language.**
20
+ - Any text field `foo` may have a sibling `fooPt`. Pages in the secondary
21
+ language show `fooPt` when it is filled and fall back to `foo` when it is
22
+ empty.
23
+ - **Sections read only `foo`.** One `localize(props, locale)` call, where the
24
+ site renders blocks, picks the language. No section knows about `Pt`.
25
+ - **Links are written without the locale prefix.** The component adds `/pt`
26
+ for the secondary language. Editors write `/pricing` once.
27
+ - Say it in the form: give each `fooPt` a description such as "Shown on
28
+ Portuguese pages. When empty, the English text is used." (`deco-cms-schema`
29
+ lists the JSDoc tags the form reads.)
30
+
31
+ ```ts
32
+ // src/sections/HeaderMenu.tsx
33
+ export interface NavigationLink {
34
+ /** @title Label (English) */
35
+ label: string;
36
+ /**
37
+ * @title Label (Português)
38
+ * @description Shown on Portuguese pages. When empty, the English label is used.
39
+ */
40
+ labelPt?: string;
41
+ /**
42
+ * @title Link
43
+ * @description A path such as /pricing. Portuguese pages add /pt automatically.
44
+ */
45
+ href: string;
46
+ }
47
+
48
+ export interface HeaderMenuProps {
49
+ links: NavigationLink[];
50
+ }
51
+ ```
52
+
53
+ ## `localize`
54
+
55
+ Block results are read-only: a client hands the same object to every place
56
+ that uses the same block in a request. `localize` builds a new object and never
57
+ changes its input.
58
+
59
+ ```ts
60
+ // src/localize.ts
61
+ export type Locale = "en" | "pt";
62
+ const SUFFIX = "Pt";
63
+
64
+ /** `fooPt` replaces `foo` on secondary-language pages when filled; `*Pt` keys are dropped. */
65
+ export function localize<T>(value: T, locale: Locale): T {
66
+ if (Array.isArray(value)) return value.map((item) => localize(item, locale)) as T;
67
+ if (!value || typeof value !== "object") return value;
68
+ const source = value as Record<string, unknown>;
69
+ const result: Record<string, unknown> = {};
70
+ for (const [key, child] of Object.entries(source)) {
71
+ // Drop `fooPt` only when `foo` exists, so a field that is really named `ctaPt` survives.
72
+ if (key.endsWith(SUFFIX) && key.length > SUFFIX.length && key.slice(0, -SUFFIX.length) in source) continue;
73
+ const translated = source[`${key}${SUFFIX}`];
74
+ const useTranslation = locale === "pt" && typeof translated === "string" && translated.trim() !== "";
75
+ result[key] = useTranslation ? translated : localize(child, locale);
76
+ }
77
+ return result as T;
78
+ }
79
+ ```
80
+
81
+ Write a unit test for it: a nested list, an empty `fooPt`, a field genuinely
82
+ named `somethingPt` without a `something`.
83
+
84
+ ## Where the language comes from
85
+
86
+ A block function receives only its saved input, so the language is never
87
+ decided inside the block map. The site decides it from the request (the path
88
+ prefix, usually) and applies `localize` where it renders:
89
+
90
+ - **Descriptors:** the code that maps `{ component, props }` to a component
91
+ calls `localize(props, locale)` and passes `locale` as an extra prop, outside
92
+ the `Props` type, so it never appears in the form.
93
+ - **JSX blocks:** the component reads the language from the site's own React
94
+ context and calls `localize` on its props.
95
+
96
+ ## Routing the secondary language
97
+
98
+ Both languages render the **same** page block. The secondary-language route
99
+ removes its prefix before matching, so `/pt/pricing` finds the page whose
100
+ `path` is `/pricing`, and only `locale` changes:
101
+
102
+ ```ts
103
+ const locale: Locale = href === "/pt" || href.startsWith("/pt/") ? "pt" : "en";
104
+ const path = locale === "pt" ? href.slice(3) || "/" : href;
105
+ const match = matchRoute(path, { routes });
106
+ ```
107
+
108
+ ## Automatic translation
109
+
110
+ Filling `fooPt` with an LLM (for example a CI job on the content change) is
111
+ possible. It needs an API key and a human review step. Start with manual
112
+ fields; add translation only when the team asks for it.
@@ -0,0 +1,79 @@
1
+ # Inventory: what is content, what is interface
2
+
3
+ Do this before writing any block. It decides the size of every PR after it.
4
+
5
+ ## Find the candidates
6
+
7
+ Search every component for:
8
+
9
+ - literal text in JSX (headings, paragraphs, button labels);
10
+ - arrays of links or cards (`const LINKS = [...]`, `const FEATURES = [...]`);
11
+ - copy objects (`COPY = { en: {...}, pt: {...} }`, `t.title`, `label`/`labelPt`);
12
+ - image URLs and `alt` texts written in code;
13
+ - page composition: a route component that renders `<Hero/><Features/><Faq/>`
14
+ in a fixed order.
15
+
16
+ A quick start:
17
+
18
+ ```sh
19
+ rg -n -g '*.tsx' '>[A-Z][a-z]+ [a-z]+' src/ # literal text in JSX
20
+ rg -n 'const [A-Z_]+ = \[' src/ # hardcoded lists
21
+ rg -n '(en|pt|es):\s*\{' src/ # per-language copy objects
22
+ ```
23
+
24
+ ## Classify each one
25
+
26
+ | Goes to the CMS (content) | Stays in code (interface or logic) |
27
+ |---|---|
28
+ | Headings, intros, card texts, calls to action and their links | `aria-label`s, "Skip to content", "Open menu" |
29
+ | Menus, footers, banners | Button states ("Copy link" then "Link copied") |
30
+ | Lists editors will reorder (cards, steps, FAQs) | Text tied to logic: status labels driven by data, version pickers |
31
+ | Which sections a page has, and their order | Navigation built by code from several sources |
32
+ | Images and their `alt` text | Error messages from forms and APIs |
33
+
34
+ Rule of thumb: if changing it needs a code release anyway (a new route, a new
35
+ version), it stays in code. Putting it in the CMS only adds a second place to
36
+ forget.
37
+
38
+ Interface text that stays in code still needs a translation when the site has
39
+ two languages. Keep it in a small dictionary in code, not in a block.
40
+
41
+ ## Record it
42
+
43
+ Write the inventory down before converting. One row per area:
44
+
45
+ | Area | Files | Fields | Shape | Priority |
46
+ |---|---|---|---|---|
47
+ | Header menu | `src/components/Header.tsx` | links (label, href) | global block | 1 |
48
+ | Home | `src/routes/index.tsx`, `src/components/home/*` | hero, guides, CTA | composed page | 2 |
49
+ | Landing pages | `src/routes/solutions/*` | hero, features | composed page | 3 |
50
+ | Articles | `content/*.mdx` | title, body, date | collection | 4 |
51
+
52
+ The shapes are explained in [content-shapes.md](./content-shapes.md).
53
+
54
+ Convert by priority: the most viewed pages first. They pay back the work
55
+ soonest, and the parity checks on them catch the most.
56
+
57
+ ## Size of a PR
58
+
59
+ One area per PR. A PR that converts the header, the home and two landings at
60
+ once cannot be checked for parity in a review: any pixel difference has four
61
+ possible causes.
62
+
63
+ Each PR carries:
64
+
65
+ - the block types added to the block map and the regenerated
66
+ `.deco/schema.gen.json`;
67
+ - the seeded `.deco/blocks` files, or the draft name they were pushed to (see
68
+ [seeding-content.md](./seeding-content.md));
69
+ - the parity evidence (see [pixel-parity.md](./pixel-parity.md)).
70
+
71
+ ## Clean up on the way
72
+
73
+ - Delete dead components you find. They cost nothing in Studio on v8 (only the
74
+ block map is listed), but they confuse the next person who greps for a text.
75
+ - When you move a component to a new file, say so in the PR description: open
76
+ PRs that import the old path will break.
77
+ - Element ids built from a list index (`card-0`) instead of a slug change the
78
+ HTML when an editor reorders the list. Check that no CSS or anchor link
79
+ targets them.