@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.
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/protocol/channel.d.ts +98 -0
- package/dist/protocol/channel.d.ts.map +1 -0
- package/dist/protocol/channel.js +58 -0
- package/dist/protocol/channel.js.map +1 -0
- package/dist/protocol/client.js +2 -2
- package/dist/protocol/client.js.map +1 -1
- package/dist/protocol/conformance/blockMetaVectors.json +214 -0
- package/dist/protocol/conformance/contentHashFixtures.d.ts +22 -0
- package/dist/protocol/conformance/contentHashFixtures.d.ts.map +1 -1
- package/dist/protocol/conformance/contentHashFixtures.js +55 -0
- package/dist/protocol/conformance/contentHashFixtures.js.map +1 -1
- package/dist/protocol/conformance/index.d.ts +2 -1
- package/dist/protocol/conformance/index.d.ts.map +1 -1
- package/dist/protocol/conformance/index.js +2 -1
- package/dist/protocol/conformance/index.js.map +1 -1
- package/dist/protocol/conformance/vectors.d.ts +33 -0
- package/dist/protocol/conformance/vectors.d.ts.map +1 -0
- package/dist/protocol/conformance/vectors.js +3 -0
- package/dist/protocol/conformance/vectors.js.map +1 -0
- package/dist/protocol/index.d.ts +11 -1
- package/dist/protocol/index.d.ts.map +1 -1
- package/dist/protocol/index.js +11 -1
- package/dist/protocol/index.js.map +1 -1
- package/dist/protocol/keys.d.ts +1 -1
- package/dist/protocol/keys.js +1 -1
- package/dist/v8/background.d.ts +13 -0
- package/dist/v8/background.d.ts.map +1 -1
- package/dist/v8/background.js +41 -0
- package/dist/v8/background.js.map +1 -1
- package/dist/v8/blockMeta.d.ts +27 -0
- package/dist/v8/blockMeta.d.ts.map +1 -0
- package/dist/v8/blockMeta.js +75 -0
- package/dist/v8/blockMeta.js.map +1 -0
- package/dist/v8/blockStore.d.ts +43 -0
- package/dist/v8/blockStore.d.ts.map +1 -0
- package/dist/v8/blockStore.js +95 -0
- package/dist/v8/blockStore.js.map +1 -0
- package/dist/v8/boundedJson.d.ts +5 -0
- package/dist/v8/boundedJson.d.ts.map +1 -1
- package/dist/v8/boundedJson.js +10 -2
- package/dist/v8/boundedJson.js.map +1 -1
- package/dist/v8/boundedMap.d.ts +19 -0
- package/dist/v8/boundedMap.d.ts.map +1 -0
- package/dist/v8/boundedMap.js +52 -0
- package/dist/v8/boundedMap.js.map +1 -0
- package/dist/v8/builtins/data.d.ts +18 -2
- package/dist/v8/builtins/data.d.ts.map +1 -1
- package/dist/v8/builtins/data.js +17 -1
- package/dist/v8/builtins/data.js.map +1 -1
- package/dist/v8/builtins/index.d.ts.map +1 -1
- package/dist/v8/builtins/index.js +2 -1
- package/dist/v8/builtins/index.js.map +1 -1
- package/dist/v8/builtins/legacy.d.ts +6 -3
- package/dist/v8/builtins/legacy.d.ts.map +1 -1
- package/dist/v8/builtins/legacy.js +6 -3
- package/dist/v8/builtins/legacy.js.map +1 -1
- package/dist/v8/canonical.d.ts +8 -0
- package/dist/v8/canonical.d.ts.map +1 -1
- package/dist/v8/canonical.js +15 -0
- package/dist/v8/canonical.js.map +1 -1
- package/dist/v8/cli/builtins.d.ts.map +1 -1
- package/dist/v8/cli/builtins.js +1 -0
- package/dist/v8/cli/builtins.js.map +1 -1
- package/dist/v8/cli/check/index.d.ts +10 -0
- package/dist/v8/cli/check/index.d.ts.map +1 -1
- package/dist/v8/cli/check/index.js +91 -7
- package/dist/v8/cli/check/index.js.map +1 -1
- package/dist/v8/cli/content.d.ts +12 -25
- package/dist/v8/cli/content.d.ts.map +1 -1
- package/dist/v8/cli/content.js +46 -75
- package/dist/v8/cli/content.js.map +1 -1
- package/dist/v8/cli/index.d.ts +2 -2
- package/dist/v8/cli/index.d.ts.map +1 -1
- package/dist/v8/cli/index.js +2 -2
- package/dist/v8/cli/index.js.map +1 -1
- package/dist/v8/cli/remote/commands.d.ts +71 -0
- package/dist/v8/cli/remote/commands.d.ts.map +1 -0
- package/dist/v8/cli/remote/commands.js +644 -0
- package/dist/v8/cli/remote/commands.js.map +1 -0
- package/dist/v8/cli/remote/diff.d.ts +15 -0
- package/dist/v8/cli/remote/diff.d.ts.map +1 -0
- package/dist/v8/cli/remote/diff.js +102 -0
- package/dist/v8/cli/remote/diff.js.map +1 -0
- package/dist/v8/cli/remote/env.d.ts +35 -0
- package/dist/v8/cli/remote/env.d.ts.map +1 -0
- package/dist/v8/cli/remote/env.js +84 -0
- package/dist/v8/cli/remote/env.js.map +1 -0
- package/dist/v8/cli/remote/http.d.ts +149 -0
- package/dist/v8/cli/remote/http.d.ts.map +1 -0
- package/dist/v8/cli/remote/http.js +381 -0
- package/dist/v8/cli/remote/http.js.map +1 -0
- package/dist/v8/cli/remote/local.d.ts +90 -0
- package/dist/v8/cli/remote/local.d.ts.map +1 -0
- package/dist/v8/cli/remote/local.js +309 -0
- package/dist/v8/cli/remote/local.js.map +1 -0
- package/dist/v8/cli/root.d.ts +29 -0
- package/dist/v8/cli/root.d.ts.map +1 -1
- package/dist/v8/cli/root.js +28 -0
- package/dist/v8/cli/root.js.map +1 -1
- package/dist/v8/cli/run.d.ts +13 -1
- package/dist/v8/cli/run.d.ts.map +1 -1
- package/dist/v8/cli/run.js +310 -124
- package/dist/v8/cli/run.js.map +1 -1
- package/dist/v8/cli/schema/builtinSchemas.d.ts.map +1 -1
- package/dist/v8/cli/schema/builtinSchemas.js +28 -10
- package/dist/v8/cli/schema/builtinSchemas.js.map +1 -1
- package/dist/v8/cli/schema/generate.js +1 -1
- package/dist/v8/cli/schema/generate.js.map +1 -1
- package/dist/v8/cli/skills.d.ts +25 -0
- package/dist/v8/cli/skills.d.ts.map +1 -0
- package/dist/v8/cli/skills.js +70 -0
- package/dist/v8/cli/skills.js.map +1 -0
- package/dist/v8/client.d.ts +9 -9
- package/dist/v8/client.d.ts.map +1 -1
- package/dist/v8/client.js +138 -50
- package/dist/v8/client.js.map +1 -1
- package/dist/v8/cms.d.ts +2 -1
- package/dist/v8/cms.d.ts.map +1 -1
- package/dist/v8/cms.js +55 -46
- package/dist/v8/cms.js.map +1 -1
- package/dist/v8/content.d.ts +39 -78
- package/dist/v8/content.d.ts.map +1 -1
- package/dist/v8/content.js +155 -195
- package/dist/v8/content.js.map +1 -1
- package/dist/v8/contentIndex.d.ts +71 -0
- package/dist/v8/contentIndex.d.ts.map +1 -0
- package/dist/v8/contentIndex.js +137 -0
- package/dist/v8/contentIndex.js.map +1 -0
- package/dist/v8/draft.d.ts +7 -7
- package/dist/v8/draft.d.ts.map +1 -1
- package/dist/v8/draft.js +10 -9
- package/dist/v8/draft.js.map +1 -1
- package/dist/v8/draftChanges.d.ts +59 -32
- package/dist/v8/draftChanges.d.ts.map +1 -1
- package/dist/v8/draftChanges.js +139 -75
- package/dist/v8/draftChanges.js.map +1 -1
- package/dist/v8/errors.d.ts +21 -0
- package/dist/v8/errors.d.ts.map +1 -1
- package/dist/v8/errors.js +22 -0
- package/dist/v8/errors.js.map +1 -1
- package/dist/v8/hostedSource.d.ts +57 -0
- package/dist/v8/hostedSource.d.ts.map +1 -0
- package/dist/v8/hostedSource.js +18 -0
- package/dist/v8/hostedSource.js.map +1 -0
- package/dist/v8/identity.d.ts +1 -1
- package/dist/v8/identity.js +1 -1
- package/dist/v8/index.d.ts +1 -0
- package/dist/v8/index.d.ts.map +1 -1
- package/dist/v8/index.js +1 -0
- package/dist/v8/index.js.map +1 -1
- package/dist/v8/matchRoute.js +7 -4
- package/dist/v8/matchRoute.js.map +1 -1
- package/dist/v8/pin.d.ts +34 -0
- package/dist/v8/pin.d.ts.map +1 -0
- package/dist/v8/pin.js +156 -0
- package/dist/v8/pin.js.map +1 -0
- package/dist/v8/preview/StudioBridge.d.ts +8 -8
- package/dist/v8/preview/StudioBridge.d.ts.map +1 -1
- package/dist/v8/preview/StudioBridge.js +8 -10
- package/dist/v8/preview/StudioBridge.js.map +1 -1
- package/dist/v8/preview/StudioChannel.d.ts +51 -0
- package/dist/v8/preview/StudioChannel.d.ts.map +1 -0
- package/dist/v8/preview/StudioChannel.js +104 -0
- package/dist/v8/preview/StudioChannel.js.map +1 -0
- package/dist/v8/preview/index.d.ts +3 -0
- package/dist/v8/preview/index.d.ts.map +1 -1
- package/dist/v8/preview/index.js +3 -0
- package/dist/v8/preview/index.js.map +1 -1
- package/dist/v8/remoteLoader.d.ts +42 -5
- package/dist/v8/remoteLoader.d.ts.map +1 -1
- package/dist/v8/remoteLoader.js +317 -259
- package/dist/v8/remoteLoader.js.map +1 -1
- package/dist/v8/resolver.d.ts +22 -8
- package/dist/v8/resolver.d.ts.map +1 -1
- package/dist/v8/resolver.js +37 -32
- package/dist/v8/resolver.js.map +1 -1
- package/dist/v8/revisionId.d.ts +11 -0
- package/dist/v8/revisionId.d.ts.map +1 -0
- package/dist/v8/revisionId.js +13 -0
- package/dist/v8/revisionId.js.map +1 -0
- package/dist/v8/settings.d.ts +6 -6
- package/dist/v8/settings.d.ts.map +1 -1
- package/dist/v8/settings.js +8 -7
- package/dist/v8/settings.js.map +1 -1
- package/dist/v8/telemetry.d.ts +4 -2
- package/dist/v8/telemetry.d.ts.map +1 -1
- package/dist/v8/telemetry.js +2 -2
- package/dist/v8/telemetry.js.map +1 -1
- package/dist/v8/types.d.ts +52 -40
- package/dist/v8/types.d.ts.map +1 -1
- package/dist/v8/variants.d.ts +7 -2
- package/dist/v8/variants.d.ts.map +1 -1
- package/dist/v8/variants.js +21 -24
- package/dist/v8/variants.js.map +1 -1
- package/dist/v8/vite/index.d.ts +2 -2
- package/dist/v8/vite/index.js +1 -1
- package/dist/v8/vite/index.js.map +1 -1
- package/package.json +3 -2
- package/skills/deco-apps/SKILL.md +82 -0
- package/skills/deco-apps/references/algolia.md +51 -0
- package/skills/deco-apps/references/commerce-types.md +132 -0
- package/skills/deco-apps/references/instrumented-fetch.md +144 -0
- package/skills/deco-apps/references/magento.md +55 -0
- package/skills/deco-apps/references/messaging.md +76 -0
- package/skills/deco-apps/references/shopify.md +69 -0
- package/skills/deco-apps/references/vendored-loaders.md +135 -0
- package/skills/deco-apps/references/vtex-cookies-auth.md +146 -0
- package/skills/deco-apps/references/vtex.md +150 -0
- package/skills/deco-apps/references/wake.md +75 -0
- package/skills/deco-cms-schema/SKILL.md +80 -0
- package/skills/deco-cms-schema/references/annotations.md +147 -0
- package/skills/deco-cms-schema/references/content-hygiene.md +91 -0
- package/skills/deco-cms-schema/references/formats-and-widgets.md +112 -0
- package/skills/deco-cms-schema/references/shapes-that-break-the-form.md +165 -0
- package/skills/deco-cms-schema/references/types-to-fields.md +112 -0
- package/skills/deco-go-live/SKILL.md +127 -0
- package/skills/deco-go-live/references/content-releases.md +90 -0
- package/skills/deco-go-live/references/process.md +106 -0
- package/skills/deco-go-live/references/proxy-headers-checkout.md +139 -0
- package/skills/deco-go-live/references/qa-checklist-template.md +150 -0
- package/skills/deco-go-live/references/qa-inventory.md +120 -0
- package/skills/deco-go-live/references/react-spa.md +183 -0
- package/skills/deco-go-live/references/seo-analytics.md +114 -0
- package/skills/deco-go-live/references/traffic-ramp.md +87 -0
- package/skills/deco-go-live/references/worker-runtime.md +93 -0
- package/skills/deco-go-live/scripts/preflight.sh +221 -0
- package/skills/deco-images-media/SKILL.md +64 -0
- package/skills/deco-images-media/references/asset-upload.md +191 -0
- package/skills/deco-images-media/references/components-per-binding.md +167 -0
- package/skills/deco-images-media/references/providers-and-cdn.md +145 -0
- package/skills/deco-images-media/references/quality-and-lcp.md +93 -0
- package/skills/deco-images-media/references/troubleshooting.md +147 -0
- package/skills/deco-images-media/references/video.md +122 -0
- package/skills/deco-make-editable/SKILL.md +94 -0
- package/skills/deco-make-editable/references/a11y-and-e2e.md +104 -0
- package/skills/deco-make-editable/references/content-shapes.md +198 -0
- package/skills/deco-make-editable/references/from-figma.md +110 -0
- package/skills/deco-make-editable/references/i18n-fields.md +112 -0
- package/skills/deco-make-editable/references/inventory.md +79 -0
- package/skills/deco-make-editable/references/pixel-parity.md +175 -0
- package/skills/deco-make-editable/references/seeding-content.md +119 -0
- package/skills/deco-nextjs-site/SKILL.md +74 -0
- package/skills/deco-nextjs-site/references/caching.md +116 -0
- package/skills/deco-nextjs-site/references/metadata-seo.md +100 -0
- package/skills/deco-nextjs-site/references/proxy-and-drafts.md +177 -0
- package/skills/deco-nextjs-site/references/rendering.md +171 -0
- package/skills/deco-nextjs-site/references/setup.md +190 -0
- package/skills/deco-nextjs-site/references/studio-bridge.md +130 -0
- package/skills/deco-site-authoring/SKILL.md +75 -0
- package/skills/deco-site-authoring/references/lazy-blocks.md +155 -0
- package/skills/deco-site-authoring/references/loaders.md +192 -0
- package/skills/deco-site-authoring/references/pages.md +156 -0
- package/skills/deco-site-authoring/references/review-before-publish.md +95 -0
- package/skills/deco-site-authoring/references/sections.md +158 -0
- package/skills/deco-site-authoring/references/seo.md +116 -0
- package/skills/deco-site-workflow/SKILL.md +92 -0
- package/skills/deco-site-workflow/references/check.md +116 -0
- package/skills/deco-site-workflow/references/cli-reference.md +104 -0
- package/skills/deco-site-workflow/references/content-layout.md +93 -0
- package/skills/deco-site-workflow/references/content-sync.md +146 -0
- package/skills/deco-site-workflow/references/delivery.md +51 -0
- package/skills/deco-site-workflow/references/deploy.md +87 -0
- package/skills/deco-site-workflow/references/schema.md +173 -0
- package/skills/deco-site-workflow/references/serve-and-studio.md +138 -0
- package/skills/deco-storefront-caching/SKILL.md +67 -0
- package/skills/deco-storefront-caching/references/cache-keys.md +129 -0
- package/skills/deco-storefront-caching/references/case-study.md +82 -0
- package/skills/deco-storefront-caching/references/egress-traps.md +153 -0
- package/skills/deco-storefront-caching/references/nextjs.md +60 -0
- package/skills/deco-storefront-caching/references/perf-guardrails-e2e.md +123 -0
- package/skills/deco-storefront-caching/references/verification.md +136 -0
- package/skills/deco-storefront-caching/references/worker-page-cache.md +160 -0
- package/skills/deco-storefront-caching/scripts/html-anatomy.mjs +97 -0
- package/skills/deco-storefront-performance/SKILL.md +81 -0
- package/skills/deco-storefront-performance/references/cls-third-party.md +90 -0
- package/skills/deco-storefront-performance/references/hydration.md +116 -0
- package/skills/deco-storefront-performance/references/loaders-n-plus-1.md +107 -0
- package/skills/deco-storefront-performance/references/navigation-ux.md +130 -0
- package/skills/deco-storefront-performance/references/payload-trim.md +163 -0
- package/skills/deco-storefront-performance/references/render-location.md +152 -0
- package/skills/deco-storefront-performance/references/request-dedupe.md +147 -0
- package/skills/deco-storefront-performance/references/trace-reading.md +79 -0
- package/skills/deco-storefront-performance/references/worker-memory.md +176 -0
- package/skills/deco-tanstack-site/SKILL.md +68 -0
- package/skills/deco-tanstack-site/references/document-and-security.md +155 -0
- package/skills/deco-tanstack-site/references/router-and-navigation.md +137 -0
- package/skills/deco-tanstack-site/references/routes-and-pages.md +183 -0
- package/skills/deco-tanstack-site/references/server-functions.md +123 -0
- package/skills/deco-tanstack-site/references/setup.md +153 -0
- package/skills/deco-tanstack-site/references/worker-entry.md +152 -0
- package/skills/deco-v7-to-v8-migration/SKILL.md +122 -0
- package/skills/deco-v7-to-v8-migration/references/caching-and-privacy.md +10 -0
- package/skills/deco-v7-to-v8-migration/references/content.md +25 -0
- package/skills/deco-v7-to-v8-migration/references/editor-forms.md +27 -0
- package/skills/deco-v7-to-v8-migration/references/faststore.md +40 -0
- package/skills/deco-v7-to-v8-migration/references/framework-code.md +53 -0
- package/skills/deco-v7-to-v8-migration/references/hosted-releases.md +16 -0
- package/skills/deco-v7-to-v8-migration/references/import-map.md +81 -0
- package/skills/deco-v7-to-v8-migration/references/legacy-names.md +33 -0
- package/skills/deco-v7-to-v8-migration/references/manual-steps.md +10 -0
- package/skills/deco-v7-to-v8-migration/references/native-apps.md +43 -0
- package/skills/deco-v7-to-v8-migration/references/nextjs.md +19 -0
- package/skills/deco-v7-to-v8-migration/references/parity.md +66 -0
- package/skills/deco-v7-to-v8-migration/references/rendering.md +13 -0
- package/skills/deco-v7-to-v8-migration/references/running-the-script.md +29 -0
- package/skills/deco-v7-to-v8-migration/references/script-steps.md +13 -0
- package/skills/deco-v7-to-v8-migration/references/server-functions.md +15 -0
- package/skills/deco-v7-to-v8-migration/references/sibling-port.md +11 -0
- package/skills/deco-v7-to-v8-migration/references/site-code.md +15 -0
- package/skills/deco-v7-to-v8-migration/references/telemetry.md +10 -0
- package/skills/deco-v7-to-v8-migration/references/verify.md +20 -0
- package/skills/deco-v7-to-v8-migration/scripts/apps.ts +297 -0
- package/skills/deco-v7-to-v8-migration/scripts/asyncRendering.ts +73 -0
- package/skills/deco-v7-to-v8-migration/scripts/blockMap.ts +584 -0
- package/skills/deco-v7-to-v8-migration/scripts/ciSchemaCheck.ts +145 -0
- package/skills/deco-v7-to-v8-migration/scripts/compat.ts +357 -0
- package/skills/deco-v7-to-v8-migration/scripts/content.ts +121 -0
- package/skills/deco-v7-to-v8-migration/scripts/experiments.ts +81 -0
- package/skills/deco-v7-to-v8-migration/scripts/framework.ts +61 -0
- package/skills/deco-v7-to-v8-migration/scripts/imageCopy.ts +276 -0
- package/skills/deco-v7-to-v8-migration/scripts/imageModule.ts +285 -0
- package/skills/deco-v7-to-v8-migration/scripts/imports.ts +942 -0
- package/skills/deco-v7-to-v8-migration/scripts/invoke.ts +624 -0
- package/skills/deco-v7-to-v8-migration/scripts/legacyNames.ts +45 -0
- package/skills/deco-v7-to-v8-migration/scripts/main.ts +59 -0
- package/skills/deco-v7-to-v8-migration/scripts/matchers.ts +41 -0
- package/skills/deco-v7-to-v8-migration/scripts/migrate.ts +176 -0
- package/skills/deco-v7-to-v8-migration/scripts/redirects.ts +455 -0
- package/skills/deco-v7-to-v8-migration/scripts/report.ts +50 -0
- package/skills/deco-v7-to-v8-migration/scripts/scaffold.ts +1119 -0
- package/skills/deco-v7-to-v8-migration/scripts/secrets.ts +35 -0
- package/skills/deco-v7-to-v8-migration/scripts/sectionLoaders.ts +216 -0
- package/skills/deco-v7-to-v8-migration/scripts/siteSettings.ts +261 -0
- package/skills/deco-v7-to-v8-migration/scripts/stubs.ts +388 -0
- package/skills/deco-v7-to-v8-migration/scripts/tsconfig.json +7 -0
- package/skills/deco-v7-to-v8-migration/scripts/vendor.ts +249 -0
- package/skills/deco-v7-to-v8-migration/scripts/vtexInvoke.ts +240 -0
- package/skills/deco-v7-to-v8-migration/scripts/walk.ts +30 -0
- package/skills/deco-variants/SKILL.md +57 -0
- package/skills/deco-variants/references/caching-variants.md +63 -0
- package/skills/deco-variants/references/custom-matchers.md +83 -0
- package/skills/deco-variants/references/draft-preview.md +59 -0
- package/skills/deco-variants/references/experiments-and-campaigns.md +104 -0
- package/skills/deco-variants/references/multivariate.md +85 -0
- package/skills/deco-variants/references/v7-matchers.md +71 -0
- package/src/index.ts +2 -0
- package/src/protocol/channel.ts +127 -0
- package/src/protocol/client.ts +2 -2
- package/src/protocol/conformance/blockMetaVectors.json +214 -0
- package/src/protocol/conformance/contentHashFixtures.ts +74 -0
- package/src/protocol/conformance/index.ts +9 -1
- package/src/protocol/conformance/vectors.ts +36 -0
- package/src/protocol/index.ts +32 -0
- package/src/protocol/keys.ts +1 -1
- package/src/v8/background.ts +42 -0
- package/src/v8/blockMeta.ts +100 -0
- package/src/v8/blockStore.ts +124 -0
- package/src/v8/boundedJson.ts +20 -2
- package/src/v8/boundedMap.ts +53 -0
- package/src/v8/builtins/data.ts +26 -2
- package/src/v8/builtins/index.ts +2 -1
- package/src/v8/builtins/legacy.ts +6 -3
- package/src/v8/canonical.ts +15 -0
- package/src/v8/cli/builtins.ts +1 -0
- package/src/v8/cli/check/index.ts +97 -7
- package/src/v8/cli/content.ts +49 -91
- package/src/v8/cli/index.ts +2 -2
- package/src/v8/cli/remote/commands.ts +834 -0
- package/src/v8/cli/remote/diff.ts +100 -0
- package/src/v8/cli/remote/env.ts +107 -0
- package/src/v8/cli/remote/http.ts +484 -0
- package/src/v8/cli/remote/local.ts +343 -0
- package/src/v8/cli/root.ts +40 -0
- package/src/v8/cli/run.ts +366 -135
- package/src/v8/cli/schema/builtinSchemas.ts +29 -10
- package/src/v8/cli/schema/generate.ts +1 -1
- package/src/v8/cli/skills.ts +91 -0
- package/src/v8/client.ts +162 -60
- package/src/v8/cms.ts +62 -53
- package/src/v8/content.ts +179 -229
- package/src/v8/contentIndex.ts +183 -0
- package/src/v8/draft.ts +15 -14
- package/src/v8/draftChanges.ts +151 -85
- package/src/v8/errors.ts +37 -0
- package/src/v8/hostedSource.ts +67 -0
- package/src/v8/identity.ts +1 -1
- package/src/v8/index.ts +1 -0
- package/src/v8/matchRoute.ts +7 -4
- package/src/v8/pin.ts +176 -0
- package/src/v8/preview/StudioBridge.ts +8 -10
- package/src/v8/preview/StudioChannel.ts +116 -0
- package/src/v8/preview/index.ts +3 -0
- package/src/v8/remoteLoader.ts +350 -286
- package/src/v8/resolver.ts +56 -33
- package/src/v8/revisionId.ts +14 -0
- package/src/v8/settings.ts +10 -9
- package/src/v8/telemetry.ts +3 -3
- package/src/v8/types.ts +52 -40
- package/src/v8/variants.ts +30 -26
- package/src/v8/vite/index.ts +3 -3
- package/dist/v8/cli/serve/server.d.ts +0 -29
- package/dist/v8/cli/serve/server.d.ts.map +0 -1
- package/dist/v8/cli/serve/server.js +0 -296
- package/dist/v8/cli/serve/server.js.map +0 -1
- 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.
|