@bettercms-ai/kit 3.1.10 → 3.1.12
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/controls/rich-text/editor.js +1 -2
- package/dist/controls/rich-text/editor.js.map +1 -1
- package/dist/lib/utils.js +1 -1
- package/dist/lib/utils.js.map +1 -1
- package/dist/library/entries/advanced.entries.js +1 -1
- package/dist/library/entries/advanced.entries.js.map +1 -1
- package/dist/library/entries/media.entries.js +1 -1
- package/dist/library/entries/media.entries.js.map +1 -1
- package/dist/library/kit-catalog.json +2 -2
- package/package.json +1 -1
|
@@ -1410,7 +1410,7 @@
|
|
|
1410
1410
|
{"id":"review-summary","name":"Review summary","category":"Social proof","kind":"block","tags":["seo-structured","references","conditional","validation","a11y","commerce"],"proves":"Synced vs typed ratings (developer-locked provider) · 5-bucket distribution validation · AggregateRating only with a product subject","why":"Ratings are DATA, not copy: when a review app is connected the average, count and distribution are synced (the provider is developer-locked) and editors only choose presentation; manual mode exists for sources that can't sync. The distribution is exactly five buckets (validation min=max=5) so bars always render 5→1. The block references its SUBJECT product because AggregateRating structured data is only valid for a specific product/service, and must match what is visible — so JSON-LD is emitted only when a subject is set (the toggle is hidden otherwise). Featured reviews reference the testimonials collection.","htmlSignals":["A big average number (“4.8”) next to stars and “Based on 2,418 reviews”","Five horizontal bars labeled 5★…1★ with counts or percentages (`<progress>`, `<meter>`, width-% divs)","Review-app markup: `jdgm-`, `okendo-`, `yotpo-`, `trustpilot-widget` classes or their script tags","`application/ld+json` with `AggregateRating` / `ratingValue` / `reviewCount`"],"mcp":"Detect the review app from class prefixes/scripts → dataSource connected + provider (and tell the developer to connect it); otherwise manual. Read average/count from JSON-LD first (most reliable), then visible text. Bars → ratingCounts: parse each bar's count; if only percentages are shown, compute counts from the total and round so they sum to it. Badges for other platforms → platforms with their profile links. The product the page is about → subject. Never emit AggregateRating for store-wide/self-serving ratings.","pitfalls":["AggregateRating on a home page about your own business is ignored or penalised — only with a product subject.","Typed-in ratings drift from the real ones; prefer the connected source and show “Synced …” in the UI.","Distribution counts that don't sum to the total look fake; validate the sum."],"notCarried":["item openMode","itemNoun (derived)","shopify reference","variants"],"component":{"name":"Review summary","slug":"review-summary","props":[{"key":"heading","label":"Heading","type":"text","recommendedMax":48,"localized":true,"placeholder":"What cooks are saying","ui":{"tab":{"id":"content","label":"Content"}}},{"key":"subject","label":"Reviews of","type":"reference","helpText":"Leave empty for store-wide reviews.","helpMore":"Star snippets in search only appear for a specific product.","config":{"contentModelId":"col_products"},"ui":{"tab":{"id":"content"}}},{"key":"dataSource","label":"Ratings come from","type":"select","defaultValue":"connected","config":{"options":[{"label":"Connected review app","value":"connected","description":"Synced nightly from the reviews integration"},{"label":"Typed in","value":"manual","description":"For ratings you can't sync, e.g. a trade show survey"}]},"ui":{"control":"radio","tab":{"id":"data","label":"Ratings"}}},{"key":"provider","label":"Review app","type":"select","showIf":{"match":"all","rules":[{"field":"dataSource","op":"eq","value":"connected"}]},"readOnly":"developer","lockReason":"Connected by the developer in Settings › Integrations.","config":{"options":[{"label":"Judge.me","value":"judgeme"},{"label":"Okendo","value":"okendo"},{"label":"Yotpo","value":"yotpo"},{"label":"Trustpilot","value":"trustpilot"}]},"ui":{"access":{"edit":"schema.manage"},"tab":{"id":"data"}}},{"key":"average","label":"Average rating","type":"number","required":true,"showIf":{"match":"all","rules":[{"field":"dataSource","op":"eq","value":"manual"}]},"config":{"min":1,"max":5,"step":0.1},"ui":{"tab":{"id":"data"}}},{"key":"count","label":"Number of reviews","type":"number","required":true,"showIf":{"match":"all","rules":[{"field":"dataSource","op":"eq","value":"manual"}]},"config":{"min":1,"step":1},"ui":{"tab":{"id":"data"}}},{"key":"ratingCounts","label":"Rating breakdown","type":"table","helpText":"One row per star level, 5 to 1. Counts must add up to the total.","showIf":{"match":"all","rules":[{"field":"dataSource","op":"eq","value":"manual"}]},"config":{"minItems":5,"maxItems":5,"fields":[{"key":"stars","label":"Stars","type":"number","readOnly":true,"config":{"min":1,"max":5,"step":1}},{"key":"count","label":"Reviews","type":"number","config":{"min":0,"step":1}}]},"ui":{"itemLabel":"Star level","itemName":"bucket","preview":{"title":"stars","subtitle":"count"},"tab":{"id":"data"}}},{"key":"platforms","label":"Other platforms","type":"table","config":{"maxItems":4,"fields":[{"key":"name","label":"Platform","type":"select","required":true,"options":[{"label":"Google","value":"google"},{"label":"Trustpilot","value":"trustpilot"},{"label":"Amazon","value":"amazon"},{"label":"REI","value":"rei"},{"label":"G2","value":"g2"}]},{"key":"rating","label":"Rating","type":"number","required":true,"config":{"min":1,"max":5,"step":0.1}},{"key":"count","label":"Reviews","type":"number","config":{"min":0,"step":1}},{"key":"profile","label":"Profile link","type":"link","required":true}]},"ui":{"itemLabel":"Platform","icon":"star","preview":{"title":"name","subtitle":"rating"},"tab":{"id":"data"}}},{"key":"featuredReviews","label":"Featured reviews","type":"multi-reference","config":{"max":3,"contentModelId":"col_testimonials"},"ui":{"itemLabel":"Review","itemName":"review","itemTitle":"Review","tab":{"id":"content"}}},{"key":"button","label":"Button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"useRichResults","label":"Send rating to search engines","type":"boolean","helpText":"Shows the stars in search results.","defaultValue":true,"showIf":{"match":"all","rules":[{"field":"subject","op":"notEmpty"}]},"ui":{"tab":{"id":"data"}}},{"key":"starColor","label":"Star color","type":"select","defaultValue":"brand","config":{"options":[{"label":"Brand","value":"brand"},{"label":"Gold","value":"gold"},{"label":"Ink","value":"ink"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"Average rating, distribution bars, platform scores and a few top reviews","category":"Social proof","icon":"stars","preview":{"title":"heading","subtitle":"subject","icon":"stars"}}},
|
|
1411
1411
|
{"id":"masonry-gallery","name":"Masonry gallery","category":"Media & galleries","kind":"block","tags":["media-heavy","a11y","responsive-layout","repeater","validation","localized"],"proves":"Bulk image array as tiles · caption + structured credit per photo · columns per breakpoint as design","why":"Photos are an array of small objects (image + caption + credit + optional link) shown as a GRID of tiles because galleries are managed visually and in bulk. Caption and credit are separate: the caption is localised content, the credit is attribution (name + link) that must survive translation and appear in the lightbox. Alt text lives on the image value itself. Column counts per breakpoint are DESIGN in the Design group — never per-photo sizes, because masonry keeps each photo's natural aspect ratio from its stored width/height.","htmlSignals":["Many `<img>` (6+) inside a container with `column-count`, `columns-3`, `grid-template-rows: masonry`, or Masonry.js / `data-masonry`","Images of differing aspect ratios with no fixed height","`<figure>` + `<figcaption>` per image, often with “Photo: Name” or © text","Links to full-size images (`href` ending .jpg) or useLightbox libraries (PhotoSwipe, GLightbox, fancybox) via `data-pswp-*`, `data-fancybox`"],"mcp":"Each figure → a photo: highest-resolution source (`srcset` largest, or the useLightbox `href`) → image.url, intrinsic width/height from `data-pswp-width`/natural size, `alt` → image.alt. Split `<figcaption>`: text after “Photo:”, “©”, “Credit:” or in a `<small>`/`<cite>` → credit.name (+ any link), the rest → caption. Count CSS columns at 1280/768/375px → desktopColumns/tabletColumns/phoneColumns. Lightbox library present → useLightbox true.","pitfalls":["Importing the thumbnail instead of the full-size file — always prefer the lightbox href or the largest srcset entry.","Credits pasted into captions get translated; keep them in the credit object.","Empty alt is right for decorative photos but wrong for a portfolio — flag empties for review."],"notCarried":["variants"],"component":{"name":"Masonry gallery","slug":"masonry-gallery","props":[{"key":"heading","label":"Heading","type":"text","recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"intro","label":"Intro","type":"longtext","localized":true,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"images","label":"Photos","type":"table","config":{"minItems":3,"maxItems":60,"fields":[{"key":"image","label":"Image","type":"image","helpText":"At least 1600px on the long side.","required":true},{"key":"caption","label":"Caption","type":"longtext","helpText":"Shown on hover and in the lightbox.","localized":true,"config":{"maxLength":200},"ui":{"rows":2}},{"key":"credit","label":"Credit","type":"object","openMode":"inline","fields":[{"key":"name","label":"Name","type":"text","config":{"maxLength":48}},{"key":"link","label":"Link","type":"link"}],"ui":{"icon":"camera"}},{"key":"link","label":"Link","type":"link","helpText":"Opens this instead of the lightbox."}]},"ui":{"itemLabel":"Photo","layout":"grid","itemName":"photo","icon":"photo","preview":{"title":"caption","subtitle":"credit.name","media":"image","fallback":"Untitled photo"},"tab":{"id":"media","label":"Media"}}},{"key":"useLightbox","label":"Open in a lightbox","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design","label":"Design"}}},{"key":"captionDisplay","label":"Captions","type":"select","defaultValue":"hover","config":{"options":[{"label":"Below","value":"below"},{"label":"On hover","value":"hover"},{"label":"Lightbox only","value":"lightbox"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"desktopColumns","label":"Columns on desktop","type":"number","defaultValue":3,"config":{"min":2,"max":5,"step":1},"ui":{"control":"slider","tab":{"id":"design"}}},{"key":"tabletColumns","label":"Columns on tablet","type":"number","defaultValue":2,"config":{"min":1,"max":3,"step":1},"ui":{"control":"slider","tab":{"id":"design"}}},{"key":"phoneColumns","label":"Columns on phones","type":"number","defaultValue":1,"config":{"min":1,"max":2,"step":1},"ui":{"control":"slider","tab":{"id":"design"}}},{"key":"gap","label":"Gap","type":"select","defaultValue":"md","config":{"options":[{"label":"None","value":"none"},{"label":"S","value":"sm"},{"label":"M","value":"md"},{"label":"L","value":"lg"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"Photos at their natural shapes, packed in columns, with captions and credits","category":"Media & galleries","icon":"layout-board","preview":{"title":"heading","media":"images.0.image","icon":"layout-board"}}},
|
|
1412
1412
|
{"id":"lightbox-gallery-filters","name":"Gallery with category filters","category":"Media & galleries","kind":"block","tags":["media-heavy","a11y","repeater","validation","localized"],"proves":"Filters defined once as key/label objects · photos tag themselves by key · URL-synced filter state","why":"Filter categories are defined ONCE on the section (label + stable key, localised labels) and each photo tags itself with keys, so renaming “Dining” to “Restaurant” never touches the photos and a photo can sit in two filters. The keys are a `tags` field today because our schema can't populate a select's options from a sibling array — a real gap (see notes). If the same photos are reused across pages, move them into the media library with media tags and switch the section to a query.","htmlSignals":["Filter buttons above a grid (`data-filter`, `aria-pressed`, Isotope/MixItUp/`data-category`) and tiles carrying category classes (`.dining`, `data-groups='[\"spa\"]'`)","A uniform tile grid (fixed aspect ratio, `object-fit: cover`)","A lightbox on click; sometimes a “Load more” button"],"mcp":"Filter button labels → categories (skip the “All”/“Everything” chip → allLabel; key from `data-filter` minus `.`/`*` or slugified label). For each tile, read its category classes/data attributes → categories (keys). Image from the lightbox href or largest srcset, alt → alt, lightbox caption → caption. Tile aspect → variant (1:1 square, else landscape). Visible count before “Load more” → initialCount. `?filter=`/hash usage in links → useUrlFilter.","pitfalls":["A photo tagged with a key that no filter defines is invisible under every filter except All — validate keys against the filters.","Free-typed keys are error-prone; a select fed by the section's filters is the right control (schema gap)."],"notCarried":["item openMode","variants"],"component":{"name":"Gallery with filters","slug":"filter-gallery","props":[{"key":"heading","label":"Heading","type":"text","recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"categories","label":"Filters","type":"table","config":{"minItems":2,"maxItems":8,"fields":[{"key":"label","label":"Label","type":"text","required":true,"localized":true,"config":{"maxLength":20}},{"key":"key","label":"Key","type":"slug","helpText":"Changing it unlinks the photos that use it.","required":true,"unique":true}]},"ui":{"itemLabel":"Filter","icon":"filter","preview":{"title":"label","subtitle":"key"},"tab":{"id":"content"}}},{"key":"allLabel","label":"\"All\" chip label","type":"text","helpText":"Leave empty to hide the All chip.","defaultValue":"All","localized":true,"config":{"maxLength":16},"ui":{"tab":{"id":"content"}}},{"key":"images","label":"Photos","type":"table","config":{"minItems":4,"maxItems":120,"fields":[{"key":"image","label":"Image","type":"image","required":true},{"key":"categories","label":"Filters","type":"tags","helpText":"Filter keys, e.g. rooms, dining.","config":{"min":1}},{"key":"caption","label":"Caption","type":"longtext","helpText":"Shown in the lightbox.","localized":true,"config":{"maxLength":160},"ui":{"rows":2}}]},"ui":{"itemLabel":"Photo","layout":"grid","itemName":"photo","icon":"photo","preview":{"title":"caption","subtitle":"categories","media":"image","fallback":"Untitled photo"},"tab":{"id":"media","label":"Media"}}},{"key":"useUrlFilter","label":"Remember filter in the URL","type":"boolean","advanced":true,"ui":{"tab":{"id":"design","label":"Design"}}},{"key":"columns","label":"Columns on desktop","type":"number","defaultValue":4,"config":{"min":2,"max":6,"step":1},"ui":{"control":"slider","tab":{"id":"design"}}},{"key":"initialCount","label":"Show before \"Load more\"","type":"number","defaultValue":12,"config":{"min":4,"max":48,"step":4},"ui":{"tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"A uniform grid filtered by category chips; every photo opens in a lightbox","category":"Media & galleries","icon":"photo-search","preview":{"title":"heading","media":"images.0.image","icon":"photo-search"}}},
|
|
1413
|
-
{"id":"video-section","name":"Video section (YouTube · Vimeo · hosted)","category":"Media & galleries","kind":"block","tags":["media-heavy","a11y","seo-structured","conditional","validation","embed","localized","variants"],"proves":"Source select switches link vs file · captions per language required for hosted · chapters with timestamp validation · VideoObject JSON-LD","why":"One block covers all three hosts with a `source` select: YouTube/Vimeo store a link (the renderer lazy-loads a facade until play), hosted stores a FILE so we can transcode and serve renditions. Captions are a per-language array required for hosted video (WCAG 1.2.2) — YouTube/Vimeo carry their own. Chapters are validated timestamps so the renderer can seek and emit `Clip` markup. Title, description, poster, duration and upload date are REQUIRED because they feed VideoObject JSON-LD — that is native SEO generated from content the section already needs, not modelled meta fields. Playback settings are design; loop only shows with autoplay.","htmlSignals":["`<iframe src=\"https://www.youtube(-nocookie).com/embed/…\">`, `player.vimeo.com/video/…`, `lite-youtube` / `lite-vimeo` facades","`<video>` with `<source type=\"video/mp4\">`, `poster=` and `<track kind=\"captions\" srclang=…>`","A list of timestamps (“1:12 Making the moulds”) next to or under the player","`application/ld+json` with `VideoObject`, `duration` (ISO 8601 like PT6M48S), `uploadDate`"],"mcp":"Host from the iframe/src domain → source; canonicalise YouTube/Vimeo to watch URLs (`youtube.com/watch?v=ID`, `vimeo.com/ID`) and keep `?start=`/`#t=` as startAt. `<video><source>` → source hosted + file (download the MP4); every `<track>` → captions (srclang → language, label → label, kind). Read title/description/duration/uploadDate from VideoObject JSON-LD first (convert PT6M48S → 6:48), else from visible text. Timestamp list → chapters (first must be 0:00 — prepend “Intro” if missing). `autoplay muted loop` attributes → design flags.","pitfalls":["Autoplay with sound is blocked by browsers; autoplay always means muted here.","Missing uploadDate/duration silently drops the video from rich results — they are required for that reason.","Embedding raw YouTube iframes costs ~1 MB of JS per video; the renderer uses a facade until play."],"notCarried":["item openMode","variants"],"component":{"name":"Video","slug":"video-section","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"title","label":"Title","type":"text","helpText":"Also the video's name for search engines.","required":true,"recommendedMax":70,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"description","label":"Description","type":"longtext","helpText":"Also sent to search engines.","recommendedMax":300,"localized":true,"ui":{"rows":3,"tab":{"id":"content"}}},{"key":"source","label":"Hosted on","type":"select","defaultValue":"youtube","config":{"options":[{"label":"YouTube","value":"youtube"},{"label":"Vimeo","value":"vimeo"},{"label":"Our media library","value":"hosted"}]},"ui":{"control":"segmented","tab":{"id":"content"}}},{"key":"video","label":"Video link","type":"video","helpText":"Paste the watch link.","required":true,"showIf":{"match":"all","rules":[{"field":"source","op":"in","value":["youtube","vimeo"]}]},"ui":{"tab":{"id":"content"}}},{"key":"file","label":"Video file","type":"file","helpText":"MP4 (H.264) up to 500 MB.","required":true,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"hosted"}]},"ui":{"tab":{"id":"content"}}},{"key":"poster","label":"Poster","type":"image","helpText":"At 16:9.","required":true,"ui":{"tab":{"id":"content"}}},{"key":"duration","label":"Length","type":"text","helpText":"Also sent to search engines.","required":true,"placeholder":"4:32","config":{"pattern":"^(\\d{1,2}:)?\\d{1,2}:\\d{2}$","patternMessage":"Use m:ss or h:mm:ss, like 4:05."},"ui":{"tab":{"id":"content"}}},{"key":"uploadDate","label":"Published","type":"date","helpText":"The date the video first went public.","required":true,"ui":{"tab":{"id":"content"}}},{"key":"captions","label":"Caption tracks","type":"table","helpText":"One WebVTT file per language.","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"hosted"}]},"config":{"minItems":1,"maxItems":12,"fields":[{"key":"language","label":"Language","type":"text","required":true,"placeholder":"en","config":{"pattern":"^[a-z]{2}(-[A-Z]{2})?$","patternMessage":"Use a language code, like en or es-MX."}},{"key":"label","label":"Label","type":"text","helpText":"Shown in the captions menu.","required":true,"placeholder":"English","config":{"maxLength":24}},{"key":"file","label":"WebVTT file","type":"file","required":true},{"key":"kind","label":"Kind","type":"select","defaultValue":"captions","options":[{"label":"Captions","value":"captions","description":"Speech plus sounds"},{"label":"Subtitles","value":"subtitles","description":"Translated speech only"}],"ui":{"control":"segmented"}},{"key":"isOnByDefault","label":"On by default","type":"boolean","helpText":"One track at most."}]},"ui":{"itemLabel":"Caption track","itemName":"track","icon":"badge-cc","preview":{"title":"label","subtitle":"language"},"tab":{"id":"access","label":"Captions & chapters"}}},{"key":"chapters","label":"Chapters","type":"table","helpText":"The first one must start at 0:00.","config":{"maxItems":30,"fields":[{"key":"start","label":"Starts at","type":"text","required":true,"placeholder":"1:05","config":{"pattern":"^(\\d{1,2}:)?\\d{1,2}:\\d{2}$","patternMessage":"Use m:ss or h:mm:ss, like 4:05."}},{"key":"title","label":"Title","type":"text","required":true,"localized":true,"config":{"maxLength":60}}]},"ui":{"itemLabel":"Chapter","icon":"list","preview":{"title":"title","subtitle":"start"},"tab":{"id":"access"}}},{"key":"transcript","label":"Transcript","type":"richtext","localized":true,"config":{"features":["bold","italic","underline","strikethrough","code","highlight","blockquote","horizontalRule","orderedList","unorderedList","checklist","link","internalLink","inlineImage","videoEmbed","codeBlock","table","columns","h1","h2","h3","h4","h5","h6","gallery","embed","tableOfContents","relatedPosts","authorBio","footnotes","button"]},"ui":{"tab":{"id":"access"}}},{"key":"button","label":"Button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"autoplay","label":"Play automatically","type":"boolean","ui":{"tab":{"id":"design","label":"Playback"}}},{"key":"loop","label":"Loop the video","type":"boolean","showIf":{"match":"all","rules":[{"field":"autoplay","op":"eq","value":"true"}]},"ui":{"tab":{"id":"design"}}},{"key":"controls","label":"Show player controls","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design"}}},{"key":"startAt","label":"Start at","type":"text","advanced":true,"placeholder":"0:30","config":{"pattern":"^((\\d{1,2}:)?\\d{1,2}:\\d{2})?$","patternMessage":"Use m:ss, like 1:24."},"ui":{"tab":{"id":"design"}}},{"key":"usePrivacyMode","label":"Privacy-enhanced embed","type":"boolean","helpText":"No tracking cookies until play.","defaultValue":true,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"youtube"}]},"ui":{"tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"A featured video from YouTube, Vimeo or your own host, with captions
|
|
1413
|
+
{"id":"video-section","name":"Video section (YouTube · Vimeo · hosted)","category":"Media & galleries","kind":"block","tags":["media-heavy","a11y","seo-structured","conditional","validation","embed","localized","variants"],"proves":"Source select switches link vs file · captions per language required for hosted · chapters with timestamp validation · VideoObject JSON-LD","why":"One block covers all three hosts with a `source` select: YouTube/Vimeo store a link (the renderer lazy-loads a facade until play), hosted stores a FILE so we can transcode and serve renditions. Captions are a per-language array required for hosted video (WCAG 1.2.2) — YouTube/Vimeo carry their own. Chapters are validated timestamps so the renderer can seek and emit `Clip` markup. Title, description, poster, duration and upload date are REQUIRED because they feed VideoObject JSON-LD — that is native SEO generated from content the section already needs, not modelled meta fields. Playback settings are design; loop only shows with autoplay.","htmlSignals":["`<iframe src=\"https://www.youtube(-nocookie).com/embed/…\">`, `player.vimeo.com/video/…`, `lite-youtube` / `lite-vimeo` facades","`<video>` with `<source type=\"video/mp4\">`, `poster=` and `<track kind=\"captions\" srclang=…>`","A list of timestamps (“1:12 Making the moulds”) next to or under the player","`application/ld+json` with `VideoObject`, `duration` (ISO 8601 like PT6M48S), `uploadDate`"],"mcp":"Host from the iframe/src domain → source; canonicalise YouTube/Vimeo to watch URLs (`youtube.com/watch?v=ID`, `vimeo.com/ID`) and keep `?start=`/`#t=` as startAt. `<video><source>` → source hosted + file (download the MP4); every `<track>` → captions (srclang → language, label → label, kind). Read title/description/duration/uploadDate from VideoObject JSON-LD first (convert PT6M48S → 6:48), else from visible text. Timestamp list → chapters (first must be 0:00 — prepend “Intro” if missing). `autoplay muted loop` attributes → design flags.","pitfalls":["Autoplay with sound is blocked by browsers; autoplay always means muted here.","Missing uploadDate/duration silently drops the video from rich results — they are required for that reason.","Embedding raw YouTube iframes costs ~1 MB of JS per video; the renderer uses a facade until play."],"notCarried":["item openMode","variants"],"component":{"name":"Video","slug":"video-section","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"title","label":"Title","type":"text","helpText":"Also the video's name for search engines.","required":true,"recommendedMax":70,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"description","label":"Description","type":"longtext","helpText":"Also sent to search engines.","recommendedMax":300,"localized":true,"ui":{"rows":3,"tab":{"id":"content"}}},{"key":"source","label":"Hosted on","type":"select","defaultValue":"youtube","config":{"options":[{"label":"YouTube","value":"youtube"},{"label":"Vimeo","value":"vimeo"},{"label":"Our media library","value":"hosted"}]},"ui":{"control":"segmented","tab":{"id":"content"}}},{"key":"video","label":"Video link","type":"video","helpText":"Paste the watch link.","required":true,"showIf":{"match":"all","rules":[{"field":"source","op":"in","value":["youtube","vimeo"]}]},"ui":{"tab":{"id":"content"}}},{"key":"file","label":"Video file","type":"file","helpText":"MP4 (H.264) up to 500 MB.","required":true,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"hosted"}]},"ui":{"tab":{"id":"content"}}},{"key":"poster","label":"Poster","type":"image","helpText":"At 16:9.","required":true,"ui":{"tab":{"id":"content"}}},{"key":"duration","label":"Length","type":"text","helpText":"Also sent to search engines.","required":true,"placeholder":"4:32","config":{"pattern":"^(\\d{1,2}:)?\\d{1,2}:\\d{2}$","patternMessage":"Use m:ss or h:mm:ss, like 4:05."},"ui":{"tab":{"id":"content"}}},{"key":"uploadDate","label":"Published","type":"date","helpText":"The date the video first went public.","required":true,"ui":{"tab":{"id":"content"}}},{"key":"captions","label":"Caption tracks","type":"table","helpText":"One WebVTT file per language.","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"hosted"}]},"config":{"minItems":1,"maxItems":12,"fields":[{"key":"language","label":"Language","type":"text","required":true,"placeholder":"en","config":{"pattern":"^[a-z]{2}(-[A-Z]{2})?$","patternMessage":"Use a language code, like en or es-MX."}},{"key":"label","label":"Label","type":"text","helpText":"Shown in the captions menu.","required":true,"placeholder":"English","config":{"maxLength":24}},{"key":"file","label":"WebVTT file","type":"file","required":true},{"key":"kind","label":"Kind","type":"select","defaultValue":"captions","options":[{"label":"Captions","value":"captions","description":"Speech plus sounds"},{"label":"Subtitles","value":"subtitles","description":"Translated speech only"}],"ui":{"control":"segmented"}},{"key":"isOnByDefault","label":"On by default","type":"boolean","helpText":"One track at most."}]},"ui":{"itemLabel":"Caption track","itemName":"track","icon":"badge-cc","preview":{"title":"label","subtitle":"language"},"tab":{"id":"access","label":"Captions & chapters"}}},{"key":"chapters","label":"Chapters","type":"table","helpText":"The first one must start at 0:00.","config":{"maxItems":30,"fields":[{"key":"start","label":"Starts at","type":"text","required":true,"placeholder":"1:05","config":{"pattern":"^(\\d{1,2}:)?\\d{1,2}:\\d{2}$","patternMessage":"Use m:ss or h:mm:ss, like 4:05."}},{"key":"title","label":"Title","type":"text","required":true,"localized":true,"config":{"maxLength":60}}]},"ui":{"itemLabel":"Chapter","icon":"list","preview":{"title":"title","subtitle":"start"},"tab":{"id":"access"}}},{"key":"transcript","label":"Transcript","type":"richtext","localized":true,"config":{"features":["bold","italic","underline","strikethrough","code","highlight","blockquote","horizontalRule","orderedList","unorderedList","checklist","link","internalLink","inlineImage","videoEmbed","codeBlock","table","columns","h1","h2","h3","h4","h5","h6","gallery","embed","tableOfContents","relatedPosts","authorBio","footnotes","button"]},"ui":{"tab":{"id":"access"}}},{"key":"button","label":"Button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"autoplay","label":"Play automatically","type":"boolean","ui":{"tab":{"id":"design","label":"Playback"}}},{"key":"loop","label":"Loop the video","type":"boolean","showIf":{"match":"all","rules":[{"field":"autoplay","op":"eq","value":"true"}]},"ui":{"tab":{"id":"design"}}},{"key":"controls","label":"Show player controls","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design"}}},{"key":"startAt","label":"Start at","type":"text","advanced":true,"placeholder":"0:30","config":{"pattern":"^((\\d{1,2}:)?\\d{1,2}:\\d{2})?$","patternMessage":"Use m:ss, like 1:24."},"ui":{"tab":{"id":"design"}}},{"key":"usePrivacyMode","label":"Privacy-enhanced embed","type":"boolean","helpText":"No tracking cookies until play.","defaultValue":true,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"youtube"}]},"ui":{"tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"A featured video from YouTube, Vimeo or your own host, with captions and chapters","category":"Media & galleries","icon":"player-play","preview":{"title":"title","media":"poster","icon":"player-play"}}},
|
|
1414
1414
|
{"id":"before-after-slider","name":"Before / after slider","category":"Media & galleries","kind":"block","tags":["media-heavy","a11y","repeater","validation","variants","localized"],"proves":"Paired required images per comparison · localised labels with defaults · single vs tabs via one array","why":"A comparison is a PAIR of required images plus labels, so it's an object; an array of comparisons covers both the single and tabbed layouts without two blocks. Labels default to “Before/After” but are editable and localised (“1987 / 2025” is stronger). Divider start, orientation and the first-view nudge are design. Both images keep their own alt — screen readers get “Before: …, After: …” and a keyboard-operable slider from the renderer.","htmlSignals":["Two stacked images in one container where the top one is clipped (`clip-path: inset(0 50% 0 0)` or a width %) with a draggable handle","`<input type=\"range\">` overlaid on images, or libraries `img-comparison-slider`, `twentytwenty`, `juxtapose`, `beer-slider`","Labels “Before” / “After” pinned in the corners"],"mcp":"Find the two images inside the comparison container: the clipped/overlay one is usually AFTER (check the label nearest each image rather than assuming). Labels → beforeLabel/afterLabel. Initial clip/range value → start. Vertical clip (inset top/bottom) → orientation vertical. Multiple comparisons under tabs → one block with several comparisons and variant tabs. Compare the two images' natural sizes; if they differ by more than 2%, flag it.","pitfalls":["Before and after with different crops make the slider useless — dimensions should match (not enforceable in our schema yet).","A slider built from a div with mouse events only is not keyboard accessible; the renderer must use a real range input."],"notCarried":["variants"],"component":{"name":"Before and after","slug":"before-after","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"comparisons","label":"Comparisons","type":"table","helpText":"Add more than one to show tabs.","config":{"minItems":1,"maxItems":6,"fields":[{"key":"label","label":"Tab label","type":"text","helpText":"Only shown when there are several.","localized":true,"config":{"maxLength":24}},{"key":"before","label":"Before","type":"image","helpText":"Same position, size and crop as After.","required":true},{"key":"after","label":"After","type":"image","required":true},{"key":"beforeLabel","label":"Before label","type":"text","defaultValue":"Before","localized":true,"config":{"maxLength":16}},{"key":"afterLabel","label":"After label","type":"text","defaultValue":"After","localized":true,"config":{"maxLength":16}},{"key":"caption","label":"Caption","type":"longtext","localized":true,"config":{"maxLength":200},"ui":{"rows":2}},{"key":"credit","label":"Credit","type":"object","openMode":"inline","fields":[{"key":"name","label":"Name","type":"text","config":{"maxLength":48}},{"key":"link","label":"Link","type":"link"}],"ui":{"icon":"camera"}}]},"ui":{"itemLabel":"Comparison","icon":"arrows-horizontal","preview":{"title":"label","subtitle":"caption","media":"after","fallback":"Untitled comparison"},"tab":{"id":"media","label":"Media"}}},{"key":"start","label":"Divider starts at","type":"number","defaultValue":50,"config":{"min":10,"max":90,"step":5,"unit":"%"},"ui":{"control":"slider","tab":{"id":"design","label":"Design"}}},{"key":"orientation","label":"Direction","type":"select","defaultValue":"horizontal","config":{"options":[{"label":"Side by side","value":"horizontal"},{"label":"Top and bottom","value":"vertical"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"showHint","label":"Nudge on first view","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"A draggable divider comparing two photos of the same view","category":"Media & galleries","icon":"arrows-horizontal","preview":{"title":"heading","media":"comparisons.0.after","icon":"arrows-horizontal"}}},
|
|
1415
1415
|
{"id":"image-hotspots","name":"Image with hotspots (shop the look)","category":"Media & galleries","kind":"block","tags":["media-heavy","conditional","references","commerce","a11y","validation","variants"],"proves":"Points stored as % coordinates · each pin opens a live product reference OR a note (conditional) · required pin labels","why":"Each hotspot stores its position as PERCENTAGES of the image (x, y 0–100), not pixels, so pins stay put at every screen size — which is why the image's crop must not change after pins are placed. A pin opens either a PRODUCT (a Shopify reference — name, price and stock stay live, never copied) or a NOTE (title/body/link); the `kind` select shows only the relevant fields. Every pin needs a text label because pins are tiny buttons with no visible text. The phone image is optional and shows the hotspots as a list, since pins on a small crop are unusable.","htmlSignals":["A relatively-positioned image wrapper containing absolutely-positioned buttons with `style=\"left: 24%; top: 58%\"`","Small circular buttons (“+”, numbers, pulsing dots) that open popovers with a product name, price and Add-to-cart","Shopify product handles/IDs in `data-product-id`, `data-handle` or links to `/products/…` inside the popovers"],"mcp":"For each positioned pin: parse `left`/`top` (or `inset`, `transform: translate`) as percentages of the wrapper → x/y (convert px using the wrapper's rendered size if needed, round to 0.5). Popover with a product link/handle → kind product + reference (resolve handle → Shopify GID); else kind note with heading → title, text → body, link → link. Label from the pin's `aria-label`, else the product title or note title. Keep the base image at its original crop.","pitfalls":["Pixel positions break on every other screen size — always convert to %.","Copying product price into the note text goes stale; reference the product.","Re-cropping the image after placing pins moves every pin. A visual point picker would prevent this (schema gap)."],"notCarried":["shopify reference","variants"],"component":{"name":"Image with hotspots","slug":"image-hotspots","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"image","label":"Image","type":"image","helpText":"Pins are placed in % of this photo. Changing the crop moves them.","required":true,"ui":{"tab":{"id":"media","label":"Media"}}},{"key":"mobileImage","label":"Phone photo","type":"image","helpText":"Pins show as a list on this crop.","advanced":true,"ui":{"tab":{"id":"media"}}},{"key":"hotspots","label":"Hotspots","type":"table","config":{"minItems":1,"maxItems":12,"fields":[{"key":"label","label":"Label","type":"text","helpText":"Not shown. Read by screen readers.","required":true,"localized":true,"config":{"maxLength":48}},{"key":"x","label":"Across","type":"number","helpText":"0 is the left edge, 100 the right.","required":true,"config":{"min":0,"max":100,"step":0.5,"unit":"%"},"ui":{"control":"slider"}},{"key":"y","label":"Down","type":"number","helpText":"0 is the top edge, 100 the bottom.","required":true,"config":{"min":0,"max":100,"step":0.5,"unit":"%"},"ui":{"control":"slider"}},{"key":"kind","label":"Opens","type":"select","defaultValue":"product","options":[{"label":"Product","value":"product"},{"label":"Note","value":"note"}],"ui":{"control":"segmented"}},{"key":"product","label":"Product","type":"text","required":true,"showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"product"}]},"readOnly":true,"lockReason":"A Shopify product id. No Shopify integration backs a reference in BetterCMS yet, so the id is kept as it is."},{"key":"title","label":"Title","type":"text","required":true,"showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"note"}]},"localized":true,"config":{"maxLength":48}},{"key":"body","label":"Body","type":"longtext","showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"note"}]},"localized":true,"config":{"maxLength":240},"ui":{"rows":3}},{"key":"link","label":"Link","type":"link","showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"note"}]}},{"key":"cardSide","label":"Card opens","type":"select","defaultValue":"auto","advanced":true,"options":[{"label":"Auto","value":"auto"},{"label":"Left","value":"left"},{"label":"Right","value":"right"},{"label":"Above","value":"top"}],"ui":{"control":"segmented"}}]},"ui":{"itemLabel":"Hotspot","icon":"point","preview":{"title":"label","subtitle":"kind","fallback":"Untitled hotspot"},"tab":{"id":"content"}}},{"key":"pinStyle","label":"Pin style","type":"select","defaultValue":"number","config":{"options":[{"label":"Dot","value":"dot"},{"label":"Plus","value":"plus"},{"label":"Number","value":"number"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}},{"key":"usePulse","label":"Pulse pins","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"Pins on a photo that open a product card or a note: shop the look, label the parts","category":"Media & galleries","icon":"focus-2","preview":{"title":"heading","media":"image","icon":"focus-2"}}},
|
|
1416
1416
|
{"id":"interactive-3d-lottie-embed","name":"3D model / Lottie / 360° embed","category":"Media & galleries","kind":"block","tags":["embed","conditional","media-heavy","a11y","validation","variants"],"proves":"Embed kind decides file vs allow-listed URL · required still fallback + accessible name · load-on-click for performance","why":"Three very different embeds share one block because they share the hard parts: a REQUIRED still fallback (loading, slow networks, reduced motion), a REQUIRED accessible name, and a load strategy. `kind` decides what is stored — uploaded files for 3D (GLB + optional USDZ for iOS AR) and Lottie, or an iframe URL for hosted scenes. The URL is pattern-validated against an allow-list of hosts so a marketer can't paste an arbitrary site into an iframe; raw HTML/script embeds are deliberately NOT offered here (that's a developer-only code block).","htmlSignals":["`<model-viewer src=\"….glb\" ios-src=\"….usdz\" camera-orbit=… auto-rotate ar>`","`<lottie-player>`, `<dotlottie-player>`, `lottie.loadAnimation({ path: '….json' })` or `data-animation-path`","Iframes from `my.spline.design`, `sketchfab.com/models/…/embed`, `my.matterport.com/show`, `kuula.co/share`","A canvas element (`<canvas>` from three.js/Spline runtime) with a poster image fallback"],"mcp":"`<model-viewer>` → kind model: src → model (download the GLB), ios-src → iosModel, camera-orbit → cameraOrbit, auto-rotate → useAutoRotate, poster → fallback, alt → label. Lottie players → kind lottie: src/path → lottie file, loop/autoplay/hover/scroll triggers → loop/playOn. Allow-listed iframes → kind iframe + embedUrl; any other iframe host → do NOT import into this block — emit a developer task instead. If no poster exists, capture a screenshot of the first frame as fallback and flag it.","pitfalls":["A 40 MB GLB will tank the page — validate size and recommend Draco/meshopt compression.","Iframe embeds from un-vetted hosts are a security hole — the host allow-list is intentional.","Lottie animations that loop forever must stop for reduced-motion users; the renderer shows the fallback instead."],"notCarried":["variants"],"component":{"name":"Interactive embed","slug":"interactive-embed","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"body","label":"Body","type":"richtext","localized":true,"config":{"features":["bold","italic","underline","strikethrough","code","highlight","blockquote","horizontalRule","orderedList","unorderedList","checklist","link","internalLink","inlineImage","videoEmbed","codeBlock","table","columns","h1","h2","h3","h4","h5","h6","gallery","embed","tableOfContents","relatedPosts","authorBio","footnotes","button"]},"ui":{"tab":{"id":"content"}}},{"key":"kind","label":"Type","type":"select","defaultValue":"model","config":{"options":[{"label":"3D model","value":"model","icon":"box","description":"A .glb file people can spin and view in AR"},{"label":"Lottie animation","value":"lottie","icon":"sparkles","description":"A .json or .lottie file"},{"label":"Hosted scene","value":"iframe","icon":"world","description":"Spline, Sketchfab, Matterport or a 360° tour"}]},"ui":{"control":"cards","tab":{"id":"media","label":"Media"}}},{"key":"model","label":"Model file","type":"file","helpText":"GLB under 8 MB.","required":true,"showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"model"}]},"ui":{"tab":{"id":"media"}}},{"key":"iosModel","label":"iPhone AR file","type":"file","helpText":"USDZ, so iPhones can place it in the room.","showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"model"}]},"ui":{"tab":{"id":"media"}}},{"key":"cameraOrbit","label":"Starting angle","type":"text","helpText":"Rotation, tilt and distance, e.g. 45deg 60deg 2m.","showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"model"}]},"advanced":true,"placeholder":"30deg 75deg 2m","ui":{"tab":{"id":"media"}}},{"key":"useAutoRotate","label":"Rotate slowly","type":"boolean","defaultValue":true,"showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"model"}]},"ui":{"tab":{"id":"design","label":"Design"}}},{"key":"lottie","label":"Animation file","type":"file","helpText":"Lottie .json or .lottie, under 500 KB.","required":true,"showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"lottie"}]},"ui":{"tab":{"id":"media"}}},{"key":"loop","label":"Loop the animation","type":"boolean","defaultValue":true,"showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"lottie"}]},"ui":{"tab":{"id":"design"}}},{"key":"playOn","label":"Play","type":"select","defaultValue":"view","showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"lottie"}]},"config":{"options":[{"label":"In view","value":"view"},{"label":"On hover","value":"hover"},{"label":"With scroll","value":"scroll"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"embedUrl","label":"Scene link","type":"url","helpText":"The share or embed link from the host.","required":true,"showIf":{"match":"all","rules":[{"field":"kind","op":"eq","value":"iframe"}]},"helpMore":"Only allow-listed hosts load. Ask a developer to add another.","config":{"pattern":"^https://(my\\.spline\\.design|prod\\.spline\\.design|sketchfab\\.com|my\\.matterport\\.com|kuula\\.co)/","patternMessage":"Use a Spline, Sketchfab, Matterport or Kuula link, like https://my.spline.design/caldera."},"ui":{"tab":{"id":"media"}}},{"key":"fallback","label":"Still image","type":"image","required":true,"ui":{"tab":{"id":"media"}}},{"key":"label","label":"Accessible name","type":"text","helpText":"Not shown. Read by screen readers.","required":true,"localized":true,"config":{"maxLength":120},"ui":{"tab":{"id":"content"}}},{"key":"aspect","label":"Shape","type":"select","defaultValue":"4:3","config":{"options":[{"label":"Square","value":"1:1"},{"label":"4:3","value":"4:3"},{"label":"16:9","value":"16:9"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"loadOn","label":"Load","type":"select","defaultValue":"click","config":{"options":[{"label":"In view","value":"view"},{"label":"On click","value":"click"}]},"ui":{"control":"segmented","tab":{"id":"design"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Dark","value":"dark"},{"label":"Brand","value":"brand"}]},"ui":{"control":"segmented","tab":{"id":"design"}}}],"description":"A spinnable 3D model, a Lottie animation or a hosted 360°/Spline scene, with a still fallback","category":"Media & galleries","icon":"box","preview":{"title":"heading","media":"fallback","icon":"box"}}},
|
|
@@ -1491,7 +1491,7 @@
|
|
|
1491
1491
|
{"id":"page-builder-six-deep","name":"Page builder, six levels deep","category":"Advanced patterns","kind":"block","tags":["deep-nesting","slots","repeater","variants","media-heavy"],"proves":"Guide › Tab › Columns › Column › Accordion › Item › Card › Button — slots inside arrays inside slots · breadcrumb folding + Pathway","why":"Real page builders alternate between ARRAYS (items the section owns: tabs, columns, accordion items) and SLOTS (any block from the library: columns, accordion, text, image). Each slot is a seam where the content stops belonging to this section and becomes a reusable block with its own schema and variants; each array is where content is specific to its parent. The card is an object (always one per item), the button is the one-unit button screen. Depth is legal here because every level is a different KIND of thing with its own preview row — drill-in keeps each frame small.","htmlSignals":["role=\"tablist\" with role=\"tabpanel\" siblings, each panel holding a CSS grid/flex row of columns","<details>/<summary> or buttons with aria-expanded inside a column","Expanded panels containing a card (image + heading + paragraph + link/button)","Repeated structural wrappers (.row > .col > .accordion > .item > .card) 5+ levels deep"],"mcp":"Measure depth by counting CONTENT boundaries, not DOM nodes: each element that repeats siblings of the same shape (tabs, columns, items) is an array level; each element whose inner structure differs from its siblings (a column holding an accordion next to a column holding an image) is a slot level. Wrappers that only add spacing/grid are design, not levels. Model arrays for same-shaped siblings and slots where siblings differ. Rules: (1) up to 6 content levels → one section, as here; (2) if any slot child is used on more than one page, extract it as a block (D17) and place it as a linked instance; (3) if depth would exceed 6, or a level has more than ~10 children, split the deepest repeated subtree into its own block (e.g. the accordion becomes a standalone FAQ block referenced from the column); (4) never make a column an array item AND a slot at the same time. Paths: emit _key on every array item and slot child so drill-in paths stay stable across reorders.","pitfalls":["SCHEMA GAP: a TypeSchema can't declare its own nested block types — slot `allow` names blocks from a global registry, so a converted section that introduces Columns/Accordion must also register them (handled here via the new optional KitEntry.blocks; production needs a schema-level `blocks` or a registry write).","SCHEMA GAP: no per-slot depth limit — nothing stops an author nesting Columns inside Columns inside an Accordion card forever. Needs `maxDepth` or 'cannot contain itself' on slot fields.","SCHEMA GAP: fieldsets and groups exist only at the TypeSchema root; array item objects (Tab, Column, Item) can't group their own fields.","Breadcrumb at 7 drills (Guide / Seasoning / Steps and kit / Steps / Season over fire… / Heat it upside down / Card / Button) must fold into the Pathway chip on a 380px inspector — this entry is the test case.","Accordion item cards inside a 1/3 column are cramped; that's a variant decision, not a field."],"notCarried":["variants"],"component":{"name":"Guide","slug":"guide-section","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":60,"ui":{"tab":{"id":"content"}}},{"key":"intro","label":"Intro","type":"longtext","recommendedMax":180,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"tabs","label":"Tabs","type":"table","config":{"minItems":2,"maxItems":6,"fields":[{"key":"label","label":"Tab label","type":"text","required":true,"config":{"maxLength":24}},{"key":"icon","label":"Icon","type":"icon"},{"key":"content","label":"Content","type":"slot","config":{"multiple":true,"minItems":1,"maxItems":6,"allow":["layoutColumns","accordionBlock","textBlock","imageBlock","videoBlock","ctaCard"]}}]},"ui":{"itemLabel":"Tab","itemName":"guideTab","icon":"layout-list","preview":{"title":"label","fallback":"Untitled tab"},"tab":{"id":"content"}}},{"key":"theme","label":"Theme","type":"select","defaultValue":"light","config":{"options":[{"label":"Light","value":"light"},{"label":"Warm","value":"warm"},{"label":"Dark","value":"dark"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}},{"key":"anchor","label":"Anchor","type":"text","advanced":true,"config":{"pattern":"^[a-z][a-z0-9-]*$","patternMessage":"Use lowercase letters, numbers and hyphens, starting with a letter, like grate-xl."},"ui":{"tab":{"id":"design"}}}],"description":"Tabbed guide: each tab holds columns, accordions and cards","category":"Long-form & docs","icon":"book-2","preview":{"title":"heading","subtitle":"eyebrow"}}},
|
|
1492
1492
|
{"id":"polymorphic-modules","name":"Any-block module list","category":"Advanced patterns","kind":"entry","tags":["polymorphic-array","media-heavy","references","rich-text","repeater"],"proves":"One array mixing 8 item types (_type per item) · type picker on add · references and media inside items","why":"A feature story is a sequence where ORDER is content and each item is a different shape. A polymorphic array (`of` with 8 object types, each item stamped `_type`) keeps every module typed and validated while letting the author interleave freely. These module types are local to the Feature model — they aren't reusable site blocks, so they're inline `of` types rather than a slot of library blocks. Rule of thumb: inline types when the shapes belong to one model; a slot when the blocks are shared across pages and need variants.","htmlSignals":["<article> whose direct children alternate between prose <div>s, <figure>s, <blockquote>s, galleries and asides","Repeated wrapper classes with a type suffix (.module--quote, .module--gallery, data-module=\"stat\")","Full-bleed figures breaking out of the text column (negative margins, width: 100vw)","Inline 'Read next' cards linking to another story mid-article"],"mcp":"Walk the article's top-level children in order. Classify each into one module type by its dominant element (figure+img → imageModule, multiple imgs → galleryModule, blockquote → quoteModule, iframe/video → videoModule, large numeral + label → statModule, aside/callout → calloutModule, internal story link card → relatedModule, otherwise textModule). Merge consecutive prose paragraphs into ONE textModule (never one module per <p>). Unknown shapes → textModule with the HTML preserved and a review flag. If more than 40 modules, or most modules are prose with occasional media, use a rich-text body with embedded blocks instead (see rich-text-embedded-components).","pitfalls":["SCHEMA GAP: no per-type count limits inside a polymorphic array (e.g. at most one relatedModule, galleries never adjacent) — `validation` applies to the whole array.","SCHEMA GAP: no way to share module types between models without copying FieldSchema objects; a named, reusable object type registry (Sanity's defineType for objects) is missing for non-block types.","Changing an item's type (quote → callout) isn't a schema operation; the editor must delete and re-add, losing the _key.","A textModule per paragraph is the most common bad conversion — it explodes the list and breaks reading flow."],"notCarried":[],"component":{"name":"Feature","slug":"feature-story","props":[{"key":"title","label":"Title","type":"text","required":true,"ai":true,"recommendedMax":80,"config":{"maxLength":100},"ui":{"tab":{"id":"story","label":"Story"}}},{"key":"dek","label":"Dek","type":"longtext","recommendedMax":180,"ui":{"rows":2,"tab":{"id":"story"}}},{"key":"coverImage","label":"Cover image","type":"image","required":true,"ui":{"tab":{"id":"story"}}},{"key":"authors","label":"Authors","type":"multi-reference","config":{"min":1,"max":3,"contentModelId":"col_authors"},"ui":{"itemName":"writer","itemTitle":"Writer","tab":{"id":"story"}}},{"key":"modules","label":"Modules","type":"table","config":{"mode":"types","minItems":1,"maxItems":40,"itemTypes":[{"name":"textModule","label":"Text","fields":[{"key":"heading","label":"Heading","type":"text","recommendedMax":70},{"key":"body","label":"Body","type":"richtext","required":true,"config":{"features":["bold","italic","underline","strikethrough","code","highlight","blockquote","horizontalRule","orderedList","unorderedList","checklist","link","internalLink","inlineImage","videoEmbed","codeBlock","table","columns","h1","h2","h3","h4","h5","h6","gallery","embed","tableOfContents","relatedPosts","authorBio","footnotes","button"]}}],"icon":"typography","preview":{"title":"heading","subtitle":"body","fallback":"Untitled text"}},{"name":"imageModule","label":"Image","fields":[{"key":"image","label":"Image","type":"image","required":true},{"key":"caption","label":"Caption","type":"text","config":{"maxLength":160}},{"key":"credit","label":"Credit","type":"text","config":{"maxLength":60}},{"key":"width","label":"Width","type":"select","defaultValue":"column","options":[{"label":"Text column","value":"column"},{"label":"Wide","value":"wide"},{"label":"Full bleed","value":"full"}],"ui":{"control":"segmented"}}],"icon":"photo","preview":{"title":"caption","media":"image","fallback":"Untitled image"}},{"name":"quoteModule","label":"Pull quote","fields":[{"key":"quote","label":"Quote","type":"longtext","required":true,"recommendedMax":160,"ui":{"rows":3}},{"key":"attribution","label":"Who said it","type":"text","config":{"maxLength":60}},{"key":"role","label":"Role","type":"text","config":{"maxLength":60}}],"icon":"quote","preview":{"title":"quote","subtitle":"attribution","fallback":"Untitled quote"}},{"name":"statModule","label":"Big number","fields":[{"key":"value","label":"Number","type":"text","required":true,"config":{"maxLength":12}},{"key":"label","label":"What it counts","type":"text","required":true,"config":{"maxLength":80}},{"key":"source","label":"Source","type":"link"}],"icon":"chart-bar","preview":{"title":"value","subtitle":"label","fallback":"Untitled number"}},{"name":"videoModule","label":"Video","fields":[{"key":"title","label":"Title","type":"text","required":true,"config":{"maxLength":80}},{"key":"video","label":"Video","type":"video","required":true},{"key":"poster","label":"Poster","type":"image"},{"key":"transcript","label":"Transcript","type":"richtext","helpText":"Required for interviews.","config":{"features":["bold","italic","underline","strikethrough","code","highlight","blockquote","horizontalRule","orderedList","unorderedList","checklist","link","internalLink","inlineImage","videoEmbed","codeBlock","table","columns","h1","h2","h3","h4","h5","h6","gallery","embed","tableOfContents","relatedPosts","authorBio","footnotes","button"]}}],"icon":"player-play","preview":{"title":"title","media":"poster","fallback":"Untitled video"}},{"name":"galleryModule","label":"Gallery","fields":[{"key":"images","label":"Images","type":"array","config":{"minItems":2,"maxItems":12,"itemType":"image"},"ui":{"layout":"gallery","itemName":"photo","itemTitle":"Photo"}},{"key":"layout","label":"Layout","type":"select","defaultValue":"grid","options":[{"label":"Grid","value":"grid"},{"label":"Carousel","value":"carousel"}],"ui":{"control":"segmented"}},{"key":"caption","label":"Caption","type":"text","config":{"maxLength":160}}],"icon":"layout-grid","preview":{"title":"caption","fallback":"Untitled gallery"}},{"name":"calloutModule","label":"Callout","fields":[{"key":"tone","label":"Tone","type":"select","defaultValue":"note","options":[{"label":"Note","value":"note"},{"label":"Correction","value":"correction"},{"label":"Context","value":"context"}],"ui":{"control":"segmented"}},{"key":"title","label":"Title","type":"text","config":{"maxLength":60}},{"key":"body","label":"Body","type":"longtext","required":true,"config":{"maxLength":400},"ui":{"rows":3}}],"icon":"info-square-rounded","preview":{"title":"title","subtitle":"tone","fallback":"Untitled callout"}},{"name":"relatedModule","label":"Related story","fields":[{"key":"story","label":"Story","type":"reference","required":true,"config":{"contentModelId":"col_journal"}},{"key":"label","label":"Label","type":"text","placeholder":"Read next","config":{"maxLength":24}}],"icon":"news","preview":{"title":"label","fallback":"Untitled related story"}}]},"ui":{"itemLabel":"Module","tab":{"id":"modules","label":"Modules","icon":"stack-2"}}}],"description":"A long read assembled from modules","category":"Long-form & docs","v2":{"shape":"entry"},"icon":"news","preview":{"title":"title","subtitle":"dek","media":"coverImage"}}},
|
|
1493
1493
|
{"id":"conditional-source-matrix","name":"Conditional source matrix","category":"Advanced patterns","kind":"block","tags":["conditional","references","dynamic-query","commerce","validation"],"proves":"Manual / collection / query / external branches · nested conditionals two levels down · empty-state fallback","why":"Four sources are four different data contracts, so they're exclusive branches of one select — and the bigger branches are drill-in OBJECTS so each can have its own conditionals (query.price → min/max, query.sort → metafield, external.provider → intent/seed vs endpoint/mapping). Nesting the conditionals inside objects is how a sibling-only condition system expresses a second level. Inactive branches keep their values (the query is still there if you switch back), and the renderer reads only the active branch.","htmlSignals":["Product cards rendered client-side from a fetch (Shopify recommendations API /recommendations/products.json, Algolia, Klaviyo)","data-collection / data-handle / data-tags / data-limit attributes on the section wrapper","'You might also like' / 'Goes well with' headings with a product carousel","Server-rendered lists with sort/filter query params in the 'View all' link"],"mcp":"Decide the source from how the products got there, not how they look: hard-coded product links → manual (resolve each to a Shopify reference); a collection URL or data-handle → collection; filter params (tag, price, sort) → query; a call to a recommendations endpoint → external. Fill only the active branch; leave others empty. Map the 'View all' link to cta. When the HTML is a snapshot of a dynamic list, NEVER freeze it into a manual list — that silently stops it updating; flag it if you can't tell.","pitfalls":["SCHEMA GAP: conditions test one sibling for equality — no AND/OR, no comparison (>), no reading a parent or the whole entry (e.g. 'show seed only when this block is on a product page'). Nested objects are a workaround, not a model.","SCHEMA GAP: values in hidden branches are kept and published; there's no 'clear when hidden' option, so stale manual product ids ship in the payload of an external-source block.","SCHEMA GAP: required-if — `maxPrice` is required only when visible; that works because hidden fields skip validation, but 'required when price = between AND minPrice is set' can't be written.","minPrice < maxPrice can't be validated (cross-field)."],"notCarried":["shopify reference","variants"],"component":{"name":"Product row","slug":"product-feed","props":[{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":50,"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"viewAllButton","label":"View all button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"source","label":"Products come from","type":"select","defaultValue":"manual","config":{"options":[{"label":"Picked by hand","value":"manual","icon":"hand-finger"},{"label":"A collection","value":"collection","icon":"folder"},{"label":"Rules","value":"query","icon":"filter","description":"Tags, price, stock"},{"label":"Recommendations","value":"external","icon":"sparkles","description":"Shopify or a custom API"}]},"ui":{"control":"cards","tab":{"id":"source","label":"Products","icon":"filter"}}},{"key":"products","label":"Products","type":"array","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"manual"}]},"unique":true,"readOnly":true,"lockReason":"A Shopify product id. No Shopify integration backs a reference in BetterCMS yet, so the id is kept as it is.","config":{"minItems":1,"maxItems":12,"itemType":"text"},"ui":{"tab":{"id":"source"}}},{"key":"collectionHandle","label":"Shopify collection handle","type":"text","required":true,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"collection"}]},"config":{"pattern":"^[a-z0-9-]+$","patternMessage":"Use the handle from the collection's URL, like camp-kitchen."},"ui":{"tab":{"id":"source"}}},{"key":"query","label":"Rules","type":"object","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"query"}]},"openMode":"drill","config":{"fields":[{"key":"tags","label":"Has any of these tags","type":"tags"},{"key":"price","label":"Price","type":"select","defaultValue":"any","options":[{"label":"Any","value":"any"},{"label":"Under","value":"under"},{"label":"Between","value":"between"}],"ui":{"control":"segmented"}},{"key":"minPrice","label":"From","type":"number","showIf":{"match":"all","rules":[{"field":"price","op":"eq","value":"between"}]},"config":{"unit":"USD","min":0}},{"key":"maxPrice","label":"Up to","type":"number","required":true,"showIf":{"match":"all","rules":[{"field":"price","op":"in","value":["under","between"]}]},"config":{"unit":"USD","min":0}},{"key":"showInStockOnly","label":"In stock only","type":"boolean","defaultValue":true},{"key":"sort","label":"Sort by","type":"select","defaultValue":"bestselling","options":[{"label":"Bestselling","value":"bestselling"},{"label":"Newest","value":"newest"},{"label":"Price, low to high","value":"priceAsc"},{"label":"A metafield","value":"metafield","description":"e.g. custom.rank"}]},{"key":"metafield","label":"Metafield","type":"text","required":true,"showIf":{"match":"all","rules":[{"field":"sort","op":"eq","value":"metafield"}]},"config":{"pattern":"^[a-z_]+\\.[a-z_]+$","patternMessage":"Use namespace.key, like custom.rank."}},{"key":"limit","label":"How many","type":"number","defaultValue":8,"config":{"min":1,"max":24,"step":1}}]},"ui":{"icon":"filter","tab":{"id":"source"}}},{"key":"external","label":"Recommendations","type":"object","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"external"}]},"openMode":"drill","config":{"fields":[{"key":"provider","label":"Provider","type":"select","defaultValue":"shopify","options":[{"label":"Shopify","value":"shopify"},{"label":"Custom API","value":"custom"}],"ui":{"control":"segmented"}},{"key":"intent","label":"Recommend","type":"select","defaultValue":"related","showIf":{"match":"all","rules":[{"field":"provider","op":"eq","value":"shopify"}]},"options":[{"label":"Similar products","value":"related"},{"label":"Goes well with","value":"complementary"}]},{"key":"seed","label":"Based on","type":"text","helpText":"Leave empty on product pages to use the page's product.","showIf":{"match":"all","rules":[{"field":"provider","op":"eq","value":"shopify"}]},"readOnly":true,"lockReason":"A Shopify product id. No Shopify integration backs a reference in BetterCMS yet, so the id is kept as it is."},{"key":"endpoint","label":"Endpoint","type":"url","required":true,"showIf":{"match":"all","rules":[{"field":"provider","op":"eq","value":"custom"}]},"config":{"pattern":"^https://","patternMessage":"Use an https:// address, like https://your-site.com."},"ui":{"access":{"view":"schema.view","edit":"schema.manage"}}},{"key":"mapping","label":"Response mapping","type":"object","helpText":"Where each product field lives in the API's JSON.","showIf":{"match":"all","rules":[{"field":"provider","op":"eq","value":"custom"}]},"openMode":"drill","fields":[{"key":"list","label":"List path","type":"text","placeholder":"data.items"},{"key":"id","label":"Shopify id path","type":"text","placeholder":"product_gid"},{"key":"reason","label":"Reason path","type":"text","placeholder":"explanation"}],"ui":{"icon":"arrows-exchange","access":{"view":"schema.view","edit":"schema.manage"}}},{"key":"limit","label":"How many","type":"number","defaultValue":4,"config":{"min":1,"max":12,"step":1}}]},"ui":{"icon":"sparkles","tab":{"id":"source"}}},{"key":"whenEmpty","label":"If nothing matches","type":"select","defaultValue":"bestsellers","config":{"options":[{"label":"Hide the section","value":"hide"},{"label":"Show bestsellers instead","value":"bestsellers"},{"label":"Show a message","value":"message"}]},"ui":{"control":"radio","tab":{"id":"source"}}},{"key":"emptyMessage","label":"Message","type":"text","required":true,"showIf":{"match":"all","rules":[{"field":"whenEmpty","op":"eq","value":"message"}]},"config":{"maxLength":90},"ui":{"tab":{"id":"source"}}}],"description":"Products picked by hand, from a collection, by rules or from a recommendations API","category":"Commerce","icon":"shopping-cart","preview":{"title":"heading","subtitle":"source"}}},
|
|
1494
|
-
{"id":"global-announcement-overrides","name":"Global block with per-page overrides","category":"Advanced patterns","kind":"global","tags":["global-synced","conditional","validation","variants"],"proves":"Synced fields from a global · locked vs overridable fields · instance-only settings · override map in the value","why":"A global block has three kinds of field and the schema shows them as three groups: synced fields a page MAY override (message, link, tone — marked `synced`), fields owned by the global that pages can't touch (offer terms, schedule — developer-locked with a reason), and instance-only settings that never exist on the global (hide on this page). The value carries `_ref` (the global's id) and `_overrides` (only the fields this page changed), matching D28's instance = reference + overrides, so editing the global still reaches every page except the overridden field. `published` here is the global's own value, which is what the overridden fields differ from.","htmlSignals":["A thin full-width bar above the header, identical on every page of the crawl except a few","Dismiss (×) button with a cookie/localStorage key (announcement-dismissed)","Small-print text ('Ends Oct 12', 'US only') next to the message","Pages where the bar's text differs from the site-wide version (candidate overrides)"],"mcp":"Crawl first, then decide: an element repeated with identical content on ≥80% of pages is a GLOBAL — create it once (kind: global) from the most common version. Pages whose copy differs get an instance with `_overrides` containing ONLY the differing fields; never create a second global for a variant. Offer terms and dates that never differ → global-owned (locked). If a page lacks the bar, set visibility: hide on that page rather than omitting the instance silently. If more than half the fields differ on more than a third of pages, it isn't one global — model a regular block instead.","pitfalls":["SCHEMA GAP: no per-field `overridable` flag. `synced` marks inheritance and `readOnly: \"developer\"` locks, but 'locked in instances, editable in the global' is a different permission from 'developer only' — the language conflates them.","SCHEMA GAP: the override map (`_overrides`) and instance reference (`_ref`) are value conventions, not schema — nothing validates that an override key is an overridable field.","SCHEMA GAP: instance-only fields (visibility, hideReason) live in the same schema as the global's fields; there's no way to say 'this field exists only on instances'.","Overriding `tone` on one page makes the bar look broken next to the header; consider locking design fields too."],"notCarried":["variants"],"component":{"name":"Announcement bar","slug":"announcement-bar","props":[{"key":"message","label":"Message","type":"text","required":true,"ai":true,"recommendedMax":70,"localized":true,"config":{"maxLength":90},"ui":{"synced":{"from":"Announcement bar"},"tab":{"id":"content","label":"Content"}}},{"key":"link","label":"Link","type":"link","ui":{"synced":{"from":"Announcement bar"},"tab":{"id":"content"}}},{"key":"tone","label":"Tone","type":"select","defaultValue":"brand","config":{"options":[{"label":"Brand","value":"brand"},{"label":"Dark","value":"dark"},{"label":"Warning","value":"warning"}]},"ui":{"control":"segmented","synced":{"from":"Announcement bar"},"tab":{"id":"content"}}},{"key":"legal","label":"Offer terms","type":"text","readOnly":"developer","lockReason":"Set in the global block. Pages can't override offer terms.","config":{"maxLength":120},"ui":{"synced":{"from":"Announcement bar"},"access":{"edit":"schema.manage"},"tab":{"id":"global","label":"Set in the global","icon":"world"}}},{"key":"startsAt","label":"Show from","type":"datetime","readOnly":"developer","lockReason":"The schedule is the same on every page.","ui":{"synced":{"from":"Announcement bar"},"access":{"edit":"schema.manage"},"tab":{"id":"global"}}},{"key":"endsAt","label":"Hide after","type":"datetime","readOnly":"developer","lockReason":"The schedule is the same on every page.","ui":{"synced":{"from":"Announcement bar"},"access":{"edit":"schema.manage"},"tab":{"id":"global"}}},{"key":"isDismissible","label":"Visitors can close it","type":"boolean","helpText":"Remembers the close for 7 days.","readOnly":"developer","lockReason":"Set in the global block.","ui":{"synced":{"from":"Announcement bar"},"access":{"edit":"schema.manage"},"tab":{"id":"global"}}},{"key":"visibility","label":"On this page","type":"select","helpText":"This page only. The global keeps showing elsewhere.","defaultValue":"show","config":{"options":[{"label":"Show","value":"show"},{"label":"Hide on this page","value":"hide"}]},"ui":{"control":"radio","tab":{"id":"page","label":"This page","icon":"file"}}},{"key":"hideReason","label":"Why it's hidden","type":"text","helpText":"Only editors see this.","required":true,"showIf":{"match":"all","rules":[{"field":"visibility","op":"eq","value":"hide"}]},"config":{"maxLength":80},"ui":{"tab":{"id":"page"}}}],"description":"One message across the site. Pages may
|
|
1494
|
+
{"id":"global-announcement-overrides","name":"Global block with per-page overrides","category":"Advanced patterns","kind":"global","tags":["global-synced","conditional","validation","variants"],"proves":"Synced fields from a global · locked vs overridable fields · instance-only settings · override map in the value","why":"A global block has three kinds of field and the schema shows them as three groups: synced fields a page MAY override (message, link, tone — marked `synced`), fields owned by the global that pages can't touch (offer terms, schedule — developer-locked with a reason), and instance-only settings that never exist on the global (hide on this page). The value carries `_ref` (the global's id) and `_overrides` (only the fields this page changed), matching D28's instance = reference + overrides, so editing the global still reaches every page except the overridden field. `published` here is the global's own value, which is what the overridden fields differ from.","htmlSignals":["A thin full-width bar above the header, identical on every page of the crawl except a few","Dismiss (×) button with a cookie/localStorage key (announcement-dismissed)","Small-print text ('Ends Oct 12', 'US only') next to the message","Pages where the bar's text differs from the site-wide version (candidate overrides)"],"mcp":"Crawl first, then decide: an element repeated with identical content on ≥80% of pages is a GLOBAL — create it once (kind: global) from the most common version. Pages whose copy differs get an instance with `_overrides` containing ONLY the differing fields; never create a second global for a variant. Offer terms and dates that never differ → global-owned (locked). If a page lacks the bar, set visibility: hide on that page rather than omitting the instance silently. If more than half the fields differ on more than a third of pages, it isn't one global — model a regular block instead.","pitfalls":["SCHEMA GAP: no per-field `overridable` flag. `synced` marks inheritance and `readOnly: \"developer\"` locks, but 'locked in instances, editable in the global' is a different permission from 'developer only' — the language conflates them.","SCHEMA GAP: the override map (`_overrides`) and instance reference (`_ref`) are value conventions, not schema — nothing validates that an override key is an overridable field.","SCHEMA GAP: instance-only fields (visibility, hideReason) live in the same schema as the global's fields; there's no way to say 'this field exists only on instances'.","Overriding `tone` on one page makes the bar look broken next to the header; consider locking design fields too."],"notCarried":["variants"],"component":{"name":"Announcement bar","slug":"announcement-bar","props":[{"key":"message","label":"Message","type":"text","required":true,"ai":true,"recommendedMax":70,"localized":true,"config":{"maxLength":90},"ui":{"synced":{"from":"Announcement bar"},"tab":{"id":"content","label":"Content"}}},{"key":"link","label":"Link","type":"link","ui":{"synced":{"from":"Announcement bar"},"tab":{"id":"content"}}},{"key":"tone","label":"Tone","type":"select","defaultValue":"brand","config":{"options":[{"label":"Brand","value":"brand"},{"label":"Dark","value":"dark"},{"label":"Warning","value":"warning"}]},"ui":{"control":"segmented","synced":{"from":"Announcement bar"},"tab":{"id":"content"}}},{"key":"legal","label":"Offer terms","type":"text","readOnly":"developer","lockReason":"Set in the global block. Pages can't override offer terms.","config":{"maxLength":120},"ui":{"synced":{"from":"Announcement bar"},"access":{"edit":"schema.manage"},"tab":{"id":"global","label":"Set in the global","icon":"world"}}},{"key":"startsAt","label":"Show from","type":"datetime","readOnly":"developer","lockReason":"The schedule is the same on every page.","ui":{"synced":{"from":"Announcement bar"},"access":{"edit":"schema.manage"},"tab":{"id":"global"}}},{"key":"endsAt","label":"Hide after","type":"datetime","readOnly":"developer","lockReason":"The schedule is the same on every page.","ui":{"synced":{"from":"Announcement bar"},"access":{"edit":"schema.manage"},"tab":{"id":"global"}}},{"key":"isDismissible","label":"Visitors can close it","type":"boolean","helpText":"Remembers the close for 7 days.","readOnly":"developer","lockReason":"Set in the global block.","ui":{"synced":{"from":"Announcement bar"},"access":{"edit":"schema.manage"},"tab":{"id":"global"}}},{"key":"visibility","label":"On this page","type":"select","helpText":"This page only. The global keeps showing elsewhere.","defaultValue":"show","config":{"options":[{"label":"Show","value":"show"},{"label":"Hide on this page","value":"hide"}]},"ui":{"control":"radio","tab":{"id":"page","label":"This page","icon":"file"}}},{"key":"hideReason","label":"Why it's hidden","type":"text","helpText":"Only editors see this.","required":true,"showIf":{"match":"all","rules":[{"field":"visibility","op":"eq","value":"hide"}]},"config":{"maxLength":80},"ui":{"tab":{"id":"page"}}}],"description":"One message across the site. Pages may reword it, never the legal line or schedule","category":"Navigation & chrome","v2":{"shape":"global"},"icon":"speakerphone","preview":{"title":"message","subtitle":"tone"}}},
|
|
1495
1495
|
{"id":"localized-section","name":"Localized section with RTL","category":"Advanced patterns","kind":"block","tags":["localized","repeater","conditional","a11y","validation"],"proves":"Localized fields · per-locale and per-field translation status · fallback chain · Arabic right-to-left sample","why":"Two localization models meet here. Field-level (`localized: true` on heading/body/cta) is how the editor shows a locale badge and switches values per locale — it's the right primitive. But the language has nowhere to store status, direction or fallback per locale, so the closest honest model is an internationalized array (one item per locale, Sanity's @sanity/internationalized-array pattern) carrying the translated copy plus status, direction and a per-field status list. Shared things (the image file) stay single; its alt text is copy, so it's translated.","htmlSignals":["<html lang> / hreflang alternates across crawled URLs (/pt/, /ar/) with the same section structure","dir=\"rtl\" on <html> or on the section; mirrored layouts (padding-inline-start)","A language switcher in the header","Identical structure with different text across locale paths"],"mcp":"Crawl every hreflang alternate. Match the same section across locales by position + structure, never by text. The default locale's copy fills the localized fields; every other locale becomes a `translation` item with its copy, `dir` from the dir attribute (rtl for ar/he/fa/ur), status 'approved' for human-published pages (or 'machine' if the site marks machine translation). Missing locales get a `missing` item so the gap is visible. Never translate during conversion. Keep the image shared unless a locale uses a different photo — then the image becomes localized too and you note it.","pitfalls":["SCHEMA GAP: `localized: true` is a flag only — no value shape for per-locale values, no translation status, no per-locale direction, and no fallback chain in the schema. The internationalized array here duplicates the localized fields by hand.","SCHEMA GAP: the locale list is a hard-coded select; it should come from site settings (dynamic options).","SCHEMA GAP: `unique: true` on `locale` is declared but not enforced — two pt-PT items can exist.","SCHEMA GAP: no `dir`/`lang` awareness in text fields — the editor won't render the Arabic copy right-to-left while typing.","Recommended lengths are per English; German runs ~30% longer and Arabic ~25% shorter, so a single recommendedMax misfires per locale."],"notCarried":["variants"],"component":{"name":"Studio intro","slug":"studio-intro","props":[{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"body","label":"Body","type":"longtext","ai":true,"recommendedMax":280,"localized":true,"ui":{"rows":3,"tab":{"id":"content"}}},{"key":"button","label":"Button","type":"button","localized":true,"ui":{"tab":{"id":"content"}}},{"key":"image","label":"Image","type":"image","helpText":"Shared by every language. Alt text is translated with the copy.","ui":{"tab":{"id":"content"}}},{"key":"baseLocale","label":"Written in","type":"select","defaultValue":"en","readOnly":"developer","lockReason":"The site's default locale.","config":{"options":[{"label":"English","value":"en"}]},"ui":{"access":{"edit":"schema.manage"},"tab":{"id":"translations","label":"Translations","icon":"language"}}},{"key":"fallback","label":"When a translation is missing","type":"select","defaultValue":"chain","config":{"options":[{"label":"Show English","value":"base"},{"label":"Try a related locale first","value":"chain","description":"e.g. pt-BR before English for pt-PT"},{"label":"Hide the section","value":"hide"}]},"ui":{"control":"radio","tab":{"id":"translations"}}},{"key":"translations","label":"Locales","type":"table","config":{"maxItems":12,"fields":[{"key":"locale","label":"Locale","type":"select","required":true,"unique":true,"options":[{"label":"Portuguese (Portugal)","value":"pt-PT"},{"label":"Portuguese (Brazil)","value":"pt-BR"},{"label":"Arabic (UAE)","value":"ar-AE"},{"label":"French","value":"fr-FR"},{"label":"German","value":"de-DE"}]},{"key":"status","label":"Status","type":"select","defaultValue":"missing","options":[{"label":"Missing","value":"missing"},{"label":"Machine","value":"machine"},{"label":"In review","value":"review"},{"label":"Approved","value":"approved"}],"ui":{"control":"segmented"}},{"key":"dir","label":"Direction","type":"select","helpText":"Auto reads it from the language.","defaultValue":"auto","options":[{"label":"Auto","value":"auto"},{"label":"Left to right","value":"ltr"},{"label":"Right to left","value":"rtl"}],"ui":{"control":"segmented"}},{"key":"fallbackTo","label":"Fall back to","type":"text","helpText":"Used when the section's fallback is \"related locale\".","config":{"pattern":"^[a-z]{2}(-[A-Z]{2})?$","patternMessage":"Use a locale code, like pt-BR or en."}},{"key":"heading","label":"Heading","type":"text","recommendedMax":60},{"key":"body","label":"Body","type":"longtext","recommendedMax":280,"ui":{"rows":3}},{"key":"buttonLabel","label":"Button label","type":"text","config":{"maxLength":32}},{"key":"imageAlt","label":"Image alt text","type":"text","config":{"maxLength":140}},{"key":"fields","label":"Field status","type":"table","openMode":"inline","fields":[{"key":"field","label":"Field","type":"select","options":[{"label":"Heading","value":"heading"},{"label":"Body","value":"body"},{"label":"Button label","value":"ctaLabel"},{"label":"Alt text","value":"imageAlt"}]},{"key":"status","label":"Status","type":"select","options":[{"label":"Missing","value":"missing"},{"label":"Machine","value":"machine"},{"label":"In review","value":"review"},{"label":"Approved","value":"approved"}]},{"key":"by","label":"By","type":"text","config":{"maxLength":40}}],"ui":{"itemLabel":"Field","itemName":"fieldStatus","icon":"check","preview":{"title":"field","subtitle":"status","fallback":"Untitled field"}}}]},"ui":{"itemLabel":"Locale","icon":"language","preview":{"title":"locale","subtitle":"status","fallback":"Untitled locale"},"tab":{"id":"translations"}}}],"description":"Statement, body and a button, translated per locale","category":"Company & people","icon":"language","preview":{"title":"heading","subtitle":"body","media":"image"}}},
|
|
1496
1496
|
{"id":"personalized-hero","name":"Personalized hero with A/B test","category":"Advanced patterns","kind":"block","tags":["personalization","deep-nesting","conditional","repeater","validation"],"proves":"Default fallback · audience segments with rules · priority · experiment variants with split weights · 5 levels deep","why":"Personalization is three layers with a strict precedence: audiences (first match wins), then the experiment (for everyone unmatched), then the default — which is required and complete so the page is never blank. Audience and variant content are partial objects that inherit empty fields from the default, so editors only write what changes. The deepest path (Hero › A/B test › Version › Content › Button) is five frames.","htmlSignals":["Multiple hidden copies of the hero (display:none, data-variant, data-audience attributes) or a flicker-guard style (async-hide, .optimize-loading)","Experimentation scripts: Optimizely, VWO, Google Optimize remnants, Statsig, LaunchDarkly, Mutiny, Intellimize","Server responses differing by query string (utm_campaign) or Vary headers","Clearbit/6sense reveal calls before the hero renders"],"mcp":"A static crawl only sees ONE variant — never invent audiences. Use what the page reveals: variant markup in the DOM, experiment configs inlined by the testing tool, or utm-specific versions you were given URLs for. The visible version becomes `default` (complete). Each discovered audience → `segment` with rules translated from the tool's targeting (unknown targeting → a rule with attribute 'utmCampaign' and a review flag). Experiment configs → `experiment.variants` with their weights; the original is the control. If the testing tool rewrites more than this hero (multi-section tests), don't model it per block — flag it for a page-level experiment.","pitfalls":["SCHEMA GAP: no cross-item validation — version weights must sum to 100 and exactly one version should be the control; neither can be expressed.","SCHEMA GAP: no audience/segment collection to reference; rules are re-typed in every block that personalizes (a `reference: { to: ['audience'] }` target is needed).","SCHEMA GAP: partial content objects need 'inherits from default' semantics in the schema (show the default as a placeholder, mark overridden fields); today it's a description.","SCHEMA GAP: a variant's hidden `content` is still required-validated by its own rules if `isControl` flips — conditions hide but can't relax `required` declaratively.","Personalized copy must not change the H1 for SEO purposes; the native page title stays the default's."],"notCarried":["variants"],"component":{"name":"Personalized hero","slug":"personalized-hero","props":[{"key":"default","label":"Default","type":"object","helpText":"Shown when no audience matches.","openMode":"drill","config":{"fields":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":40}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":60},{"key":"body","label":"Body","type":"longtext","ai":true,"recommendedMax":160,"ui":{"rows":2}},{"key":"primaryButton","label":"Primary button","type":"button","required":true},{"key":"image","label":"Image","type":"image","required":true}]},"ui":{"icon":"user","tab":{"id":"content","label":"Everyone"}}},{"key":"segments","label":"Audiences","type":"table","helpText":"Checked top to bottom. The first match wins.","config":{"maxItems":6,"fields":[{"key":"name","label":"Name","type":"text","required":true,"config":{"maxLength":40}},{"key":"match","label":"Match","type":"select","defaultValue":"all","options":[{"label":"All rules","value":"all"},{"label":"Any rule","value":"any"}],"ui":{"control":"segmented"}},{"key":"rules","label":"Rules","type":"table","fields":[{"key":"attribute","label":"When","type":"select","required":true,"options":[{"label":"Industry (from IP)","value":"industry"},{"label":"Company size (from IP)","value":"companySize"},{"label":"Country","value":"country"},{"label":"UTM campaign","value":"utmCampaign"},{"label":"Returning visitor","value":"returning"},{"label":"CRM lifecycle stage","value":"lifecycle"}]},{"key":"operator","label":"Condition","type":"select","defaultValue":"is","options":[{"label":"Is","value":"is"},{"label":"Is not","value":"isNot"},{"label":"Contains","value":"contains"}],"ui":{"control":"segmented"}},{"key":"value","label":"Value","type":"text","required":true,"config":{"maxLength":60}}],"config":{"minItems":1,"maxItems":5},"ui":{"itemLabel":"Rule","icon":"filter","preview":{"title":"attribute","subtitle":"value","fallback":"Untitled rule"}}},{"key":"content","label":"What they see","type":"object","helpText":"Empty fields fall back to the default.","openMode":"drill","fields":[{"key":"heading","label":"Heading","type":"text","ai":true,"recommendedMax":60},{"key":"body","label":"Body","type":"longtext","recommendedMax":160,"ui":{"rows":2}},{"key":"primaryButton","label":"Primary button","type":"button"},{"key":"image","label":"Image","type":"image"}],"ui":{"icon":"layout"}}]},"ui":{"itemLabel":"Audience","icon":"users","preview":{"title":"name","subtitle":"match","fallback":"Untitled audience"},"tab":{"id":"audiences","label":"Audiences","icon":"users"}}},{"key":"experiment","label":"A/B test","type":"object","helpText":"Splits visitors who match no audience between versions.","openMode":"drill","config":{"fields":[{"key":"isRunning","label":"Run a test","type":"boolean"},{"key":"name","label":"Test name","type":"text","required":true,"showIf":{"match":"all","rules":[{"field":"isRunning","op":"eq","value":"true"}]},"config":{"maxLength":60}},{"key":"goal","label":"Winning means more","type":"select","defaultValue":"demo","showIf":{"match":"all","rules":[{"field":"isRunning","op":"eq","value":"true"}]},"options":[{"label":"Demos booked","value":"demo"},{"label":"Trials started","value":"signup"},{"label":"Button clicks","value":"click"}]},{"key":"variants","label":"Versions","type":"table","helpText":"Weights must add up to 100%.","showIf":{"match":"all","rules":[{"field":"isRunning","op":"eq","value":"true"}]},"fields":[{"key":"name","label":"Name","type":"text","required":true,"placeholder":"B: outcome headline","config":{"maxLength":24}},{"key":"weight","label":"Traffic","type":"number","required":true,"config":{"min":0,"max":100,"step":5,"unit":"%"},"ui":{"control":"slider"}},{"key":"isControl","label":"This is the control","type":"boolean","helpText":"Uses the default content unchanged.","defaultValue":false},{"key":"content","label":"Content","type":"object","showIf":{"match":"all","rules":[{"field":"isControl","op":"eq","value":"false"}]},"openMode":"drill","fields":[{"key":"heading","label":"Heading","type":"text","ai":true,"recommendedMax":60},{"key":"body","label":"Body","type":"longtext","ui":{"rows":2}},{"key":"primaryButton","label":"Primary button","type":"button"}],"ui":{"icon":"layout"}}],"config":{"minItems":2,"maxItems":4},"ui":{"itemLabel":"Version","itemName":"testVariant","icon":"flask","preview":{"title":"name","subtitle":"weight","fallback":"Untitled version"}}},{"key":"endsAt","label":"Stop on","type":"date","showIf":{"match":"all","rules":[{"field":"isRunning","op":"eq","value":"true"}]}}]},"ui":{"icon":"flask","tab":{"id":"experiment","label":"A/B test","icon":"flask"}}}],"description":"One hero, different words for different visitors","category":"Heroes","icon":"users-group","preview":{"title":"default.heading","subtitle":"experiment.name"}}},
|
|
1497
1497
|
{"id":"responsive-layout-settings","name":"Responsive layout settings","category":"Advanced patterns","kind":"block","tags":["responsive-layout","repeater","conditional","variants"],"proves":"Columns, gap and spacing per breakpoint · inherit from the larger screen · per-item visibility and mobile order","why":"Layout is design, so it lives in its own Layout tab, split by breakpoint because the decisions differ per screen (4 columns → 2 → swipe). Tablet inherits desktop until switched off — editors only touch what changes. Per-item visibility and mobile order sit on the item because they're about THAT card. Arrangement on phones is a choice of patterns (cards select), not a column count, because 'swipe' isn't a number of columns.","htmlSignals":["Media-query grid changes: grid-template-columns: repeat(4, …) at ≥1280px, repeat(2, …) at ≥768px, one column below","Responsive utility classes: md:grid-cols-2 lg:grid-cols-4, hidden md:block, order-first sm:order-none","Scroll-snap carousels that only apply under a breakpoint","Different padding utilities per breakpoint (py-12 lg:py-24)"],"mcp":"Read the computed layout at three widths (1440, 834, 390) rather than parsing CSS. Desktop values → `desktop`; if tablet matches desktop, set `tablet.useDesktopLayout: true` and leave the rest empty; otherwise fill only what differs. Phone: one column → stack, horizontal overflow with snap → carousel (+ showPeek if the next card is partially visible), two columns → grid. Map spacing to tokens (S/M/L/XL) by nearest value — never store raw pixels. Items hidden at a width → remove that breakpoint from `showOn`; reordered items → `mobileOrder`.","pitfalls":["SCHEMA GAP: no responsive value type (`responsive<T>`: one field with a value per breakpoint and inheritance). Modelling it as three objects triplicates fields and the inherit toggle is a hand-made convention.","SCHEMA GAP: breakpoints are hard-coded in descriptions (768/1280); they should come from the site's design tokens.","SCHEMA GAP: `mobileOrder` should be unique among items and ≤ item count — cross-item validation isn't available.","Hiding content on phones hides it from mobile-first indexing too; prefer reordering over hiding."],"notCarried":["variants"],"component":{"name":"Services grid","slug":"services-grid","props":[{"key":"heading","label":"Heading","type":"text","required":true,"recommendedMax":50,"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"intro","label":"Intro","type":"longtext","ui":{"rows":2,"tab":{"id":"content"}}},{"key":"items","label":"Services","type":"table","config":{"minItems":2,"maxItems":9,"fields":[{"key":"title","label":"Title","type":"text","required":true,"config":{"maxLength":40}},{"key":"body","label":"Body","type":"longtext","recommendedMax":140,"ui":{"rows":2}},{"key":"image","label":"Image","type":"image"},{"key":"link","label":"Link","type":"link"},{"key":"showOn","label":"Show on","type":"multiselect","defaultValue":["desktop","tablet","mobile"],"options":[{"label":"Desktop","value":"desktop"},{"label":"Tablet","value":"tablet"},{"label":"Phone","value":"mobile"}]},{"key":"mobileOrder","label":"Order on phones","type":"number","helpText":"Leave empty to keep the desktop order.","config":{"min":1,"max":9,"step":1}}]},"ui":{"itemLabel":"Service","itemName":"service","icon":"briefcase","preview":{"title":"title","subtitle":"body","media":"image","fallback":"Untitled service"},"tab":{"id":"content"}}},{"key":"desktop","label":"Desktop","type":"object","helpText":"1280px and wider.","openMode":"drill","config":{"fields":[{"key":"columns","label":"Columns","type":"number","defaultValue":3,"config":{"min":1,"max":4,"step":1},"ui":{"control":"slider"}},{"key":"gap","label":"Gap","type":"select","defaultValue":"lg","options":[{"label":"S","value":"sm"},{"label":"M","value":"md"},{"label":"L","value":"lg"}],"ui":{"control":"segmented"}},{"key":"paddingY","label":"Space above and below","type":"select","defaultValue":"xl","options":[{"label":"M","value":"md"},{"label":"L","value":"lg"},{"label":"XL","value":"xl"}],"ui":{"control":"segmented"}},{"key":"alignment","label":"Alignment","type":"select","defaultValue":"left","options":[{"label":"Left","value":"left"},{"label":"Center","value":"center"}],"ui":{"control":"segmented"}}]},"ui":{"icon":"device-desktop","tab":{"id":"layout","label":"Layout","icon":"devices"}}},{"key":"tablet","label":"Tablet","type":"object","helpText":"768 to 1279px.","openMode":"drill","config":{"fields":[{"key":"useDesktopLayout","label":"Same as desktop","type":"boolean","defaultValue":true},{"key":"columns","label":"Columns","type":"number","showIf":{"match":"all","rules":[{"field":"useDesktopLayout","op":"eq","value":"false"}]},"config":{"min":1,"max":3,"step":1},"ui":{"control":"slider"}},{"key":"gap","label":"Gap","type":"select","showIf":{"match":"all","rules":[{"field":"useDesktopLayout","op":"eq","value":"false"}]},"options":[{"label":"S","value":"sm"},{"label":"M","value":"md"},{"label":"L","value":"lg"}],"ui":{"control":"segmented"}},{"key":"paddingY","label":"Space above and below","type":"select","showIf":{"match":"all","rules":[{"field":"useDesktopLayout","op":"eq","value":"false"}]},"options":[{"label":"M","value":"md"},{"label":"L","value":"lg"},{"label":"XL","value":"xl"}],"ui":{"control":"segmented"}}]},"ui":{"icon":"device-tablet","tab":{"id":"layout"}}},{"key":"mobile","label":"Phone","type":"object","helpText":"Under 768px.","openMode":"drill","config":{"fields":[{"key":"arrangement","label":"Arrange as","type":"select","defaultValue":"stack","options":[{"label":"Stack","value":"stack","icon":"layout-rows","description":"One card per row"},{"label":"Swipe","value":"carousel","icon":"carousel-horizontal","description":"Cards scroll sideways"},{"label":"Two columns","value":"grid","icon":"layout-grid","description":"Small cards, short text only"}],"ui":{"control":"cards"}},{"key":"showPeek","label":"Show the next card's edge","type":"boolean","defaultValue":true,"showIf":{"match":"all","rules":[{"field":"arrangement","op":"eq","value":"carousel"}]}},{"key":"paddingY","label":"Space above and below","type":"select","defaultValue":"md","options":[{"label":"S","value":"sm"},{"label":"M","value":"md"},{"label":"L","value":"lg"}],"ui":{"control":"segmented"}},{"key":"hideImages","label":"Hide card images","type":"boolean"}]},"ui":{"icon":"device-mobile","tab":{"id":"layout"}}}],"description":"Services as cards, laid out separately for desktop, tablet and phone","category":"Features & storytelling","icon":"apps","preview":{"title":"heading","subtitle":"intro"}}},
|