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