@bettercms-ai/kit 3.1.6 → 3.1.8
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/button.js +11 -4
- package/dist/controls/button.js.map +1 -1
- package/dist/controls/choice.js +2 -2
- package/dist/controls/choice.js.map +1 -1
- package/dist/controls/code.js +1 -1
- package/dist/controls/code.js.map +1 -1
- package/dist/controls/color.js +1 -1
- package/dist/controls/color.js.map +1 -1
- package/dist/controls/icon.js +1 -1
- package/dist/controls/icon.js.map +1 -1
- package/dist/controls/location.js +1 -1
- package/dist/controls/location.js.map +1 -1
- package/dist/controls/number.js +4 -4
- package/dist/controls/number.js.map +1 -1
- package/dist/controls/reference.js +3 -3
- package/dist/controls/reference.js.map +1 -1
- package/dist/controls/rich-text/editor.d.ts +0 -2
- package/dist/controls/rich-text/editor.js +4 -11
- package/dist/controls/rich-text/editor.js.map +1 -1
- package/dist/controls/rich-text/ops.js +4 -0
- package/dist/controls/rich-text/ops.js.map +1 -1
- package/dist/controls/table/table-editor.js +1 -1
- package/dist/controls/table/table-editor.js.map +1 -1
- package/dist/engine/array.d.ts +11 -0
- package/dist/engine/array.js +24 -4
- package/dist/engine/array.js.map +1 -1
- package/dist/index.js +2 -2
- package/dist/lib/validate.d.ts +2 -0
- package/dist/lib/validate.js +4 -2
- package/dist/lib/validate.js.map +1 -1
- package/dist/library/entries/advanced.entries.js +4 -0
- package/dist/library/entries/advanced.entries.js.map +1 -1
- package/dist/library/entries/conversion.entries.js +6 -1
- package/dist/library/entries/conversion.entries.js.map +1 -1
- package/dist/library/entries/features.entries.js +2 -1
- package/dist/library/entries/features.entries.js.map +1 -1
- package/dist/library/kit-catalog.json +3 -3
- package/dist/styles.css +1 -1
- package/dist/theme.css +0 -3
- package/dist/tokens.css +6 -12
- package/dist/ui/controls.js +9 -9
- package/dist/ui/controls.js.map +1 -1
- package/package.json +2 -2
|
@@ -1397,7 +1397,7 @@
|
|
|
1397
1397
|
{"id":"accordion-feature-image-swap","name":"Accordion features with image swap","category":"Features & storytelling","kind":"block","tags":["repeater","media-heavy","a11y","variants","rich-text"],"proves":"One required image per item drives a shared media slot · open-state as design, not content","why":"Each accordion item OWNS the image shown while it is open, so the image lives on the item (required) rather than in a parallel array the editor would have to keep in sync. Which item starts open is a design toggle, not a per-item boolean, so there can never be two “default open” items. It is an array, not the FAQ block: these are product features with media, not questions, and must not emit FAQPage JSON-LD.","htmlSignals":["`<details>/<summary>` or buttons with `aria-expanded` in one column, and ONE large image in the other column","JS that swaps the image `src` (or toggles opacity on stacked images) when a row opens","Several `<img>` stacked absolutely with only one visible, one per accordion row"],"mcp":"Count accordion rows and images: if image count equals row count (stacked or swapped), map row i → image i. Summary/button text → title, revealed content → body (portable rich text, keep links), trailing link → link. If rows have NO images, this is an FAQ or plain accordion, not this entry. Image column side → variant. If the first row is expanded by default → isFirstOpen; a progress bar on the open row → autoplay.","pitfalls":["Images of different aspect ratios cause the layout to jump on every click — warn when the source images differ.","Do not tag these rows as FAQ structured data — they are not questions."],"notCarried":["variants"],"component":{"name":"Accordion features","slug":"accordion-features","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content","order":0}}},{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"items","label":"Features","type":"table","config":{"minItems":2,"maxItems":7,"fields":[{"key":"title","label":"Title","type":"text","required":true,"ai":true,"localized":true,"config":{"maxLength":56}},{"key":"body","label":"Body","type":"richtext","ai":true,"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"]}},{"key":"image","label":"Image","type":"image","helpText":"Replaces the main image while this row is open.","required":true,"ui":{"tab":{"id":"media"}}},{"key":"link","label":"Link","type":"link"}]},"ui":{"itemLabel":"Feature","icon":"chevron-down","preview":{"title":"title","media":"image","fallback":"Untitled feature"},"tab":{"id":"content"}}},{"key":"isFirstOpen","label":"Open the first feature","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design","label":"Design","order":2}}},{"key":"autoplay","label":"Play automatically","type":"boolean","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":"An accordion of features; opening one swaps the image beside it","category":"Features & storytelling","icon":"list-details","preview":{"title":"heading","icon":"layout-list"},"tabs":[{"id":"media","label":"Media","order":1}]}},
|
|
1398
1398
|
{"id":"comparison-vs-competitors","name":"Comparison vs competitors","category":"Features & storytelling","kind":"block","tags":["deep-nesting","conditional","repeater","validation","a11y","variants"],"proves":"Brand columns + one `table` keyed by brand key (reorder-safe) · row groups · Yes / no with words · partial answers as Text cells · source in the table's own note + a required last-checked date","why":"A comparison table is 2-D data: brand COLUMNS (name, logo, badge, price, button: the header) + one `table` (CPO D42) whose brand columns are keyed by the same `key`, so adding or reordering a competitor never shifts a value into the wrong column. Rows sit in row groups (tbody + th scope=rowgroup) instead of 5 drill levels. Brand columns are Yes / no, written as ✓ plus the words 'Included' / 'Not included'; a row of words is a Text row and a partial answer is one Text cell ('Partly: rules written by hand'); explainers are footnotes, so their words stay on the page. The source line is the table's own note (rendered under the table and linked with aria-describedby), not a second block field; the last-checked date is a required field because comparative advertising claims go stale. If the same competitors appear on several pages, columns should become references to a `col_competitors` collection.","htmlSignals":["A `<table>` (or CSS grid) whose header row contains brand names/logos, with the first data column of capability names","Cells containing check/cross SVGs, ✓ ✗ characters or `aria-label=\"Included\"`","One header column visually highlighted (tinted background, “Recommended” badge)","`<tbody>` sections or full-width rows acting as group headers (`colspan`)","Small print below: “Compared on …”, “Based on public pricing”, trademark notice"],"mcp":"Header cells → columns (slugify the name for `key`; img → logo; highlighted column → isHighlighted + badge text) AND the table's brand columns with `_key` = that key, type Yes / no. Body via the table detector (docs/TABLES.md): first cell → row header (tooltip → footnote); check icon/✓/“Yes”/aria-label included → true; cross/✗/“—”/“No” → false; “Limited”/“Partial” + words → a Text cell with those words; a row of words → row type Text. Full-width rows (colspan) start a row group. Small print under the table (source, trademark notice) → the table's `notes`; parse a date in it → verifiedOn, otherwise set verifiedOn to the import date and flag it for review. Never emit a separate `footnote` field on the block.","pitfalls":["RESOLVED (D42): cells are keyed by column; never emit positional cells.","Icons without text alternatives fail screen readers; the enum lets the renderer output “Included”/“Not included”.","Comparative claims without a date and source are a legal risk — `verifiedOn` is required on purpose."],"notCarried":["variants"],"component":{"name":"Competitor comparison","slug":"competitor-comparison","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,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"intro","label":"Intro","type":"longtext","localized":true,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"columns","label":"Columns","type":"table","helpText":"The first column is you.","config":{"minItems":2,"maxItems":5,"fields":[{"key":"key","label":"Key","type":"slug","required":true,"unique":true,"readOnly":"developer","lockReason":"The table's column uses this key. Changing it would orphan its cells.","ui":{"access":{"edit":"schema.manage"}}},{"key":"name","label":"Name","type":"text","required":true,"config":{"maxLength":24}},{"key":"logo","label":"Logo","type":"image","helpText":"SVG or a transparent PNG."},{"key":"isHighlighted","label":"Highlight this column","type":"boolean"},{"key":"badge","label":"Badge","type":"text","showIf":{"match":"all","rules":[{"field":"isHighlighted","op":"eq","value":"true"}]},"placeholder":"Best value","config":{"maxLength":16}},{"key":"price","label":"Price line","type":"text","placeholder":"$29 / month","config":{"maxLength":24}},{"key":"button","label":"Button","type":"button","showIf":{"match":"all","rules":[{"field":"isHighlighted","op":"eq","value":"true"}]}}]},"ui":{"itemLabel":"Column","icon":"columns","preview":{"title":"name","subtitle":"key","media":"logo","fallback":"Untitled column"},"tab":{"id":"columns","label":"Brands"}}},{"key":"comparison","label":"Comparison","type":"table","required":true,"localized":true,"config":{"mode":"data","maxColumns":6,"maxRows":60,"columnTypes":["text","boolean","number","money","rating","link"],"jsonLd":["ItemList"],"settings":{"totals":false,"phones":[]}},"ui":{"tab":{"id":"content"}}},{"key":"verifiedOn","label":"Last checked","type":"date","helpText":"Shown under the table.","required":true,"ui":{"tab":{"id":"content"}}},{"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","label":"Design"}}}],"description":"Your product against alternatives, row by row: included, not included, or a few words","category":"Features & storytelling","icon":"vs","preview":{"title":"heading","icon":"table"}}},
|
|
1399
1399
|
{"id":"stats-band","name":"Stats band","category":"Features & storytelling","kind":"block","tags":["repeater","validation","variants","a11y","localized"],"proves":"Numbers stored as numbers (prefix/value/suffix) so they localise and count up · per-stat source + as-of date","why":"A stat is split into prefix · number · suffix so the number is real data: it can animate, be formatted per locale (1.2M vs 1,2 M) and be checked. The core `statBlock` stores a display string (\"120k+\") for quick bento cells — this section is for numbers that matter and need a SOURCE and AS-OF date (health, finance and B2B claims get audited). Count-up is design; the renderer skips it under reduced motion and always outputs the final number in the HTML.","htmlSignals":["A row of 2–5 items each with a very large number (font-size ≥ 2.5rem) and a small label beneath","`data-count`, `data-target`, `countup`, `odometer` attributes or classes","Numbers with units/magnitudes: “94%”, “$2.4B”, “11 min”, “10k+”","Footnote markers (*, †, superscript numbers) linking to a sources line"],"mcp":"Parse each big number with a regex: leading non-digits → prefix, the number (strip thousands separators; respect the page locale's decimal mark) → value, trailing text → suffix (keep the leading space if present), digits after the decimal → decimals. Prefer the `data-target`/`data-count` attribute over the visible text when both exist (the visible text may be mid-animation “0”). Label → label. Footnote text with a URL → source; any date in it → asOf. Presence of count-up attributes → useCountUp true.","pitfalls":["Scraping during a count-up animation captures “0” — read the data attribute or wait for the final value.","“1.2M” is value 1.2 + suffix M, not 1200000 with no suffix, unless the design formats compact numbers itself."],"notCarried":["variants"],"component":{"name":"Stats band","slug":"stats-band","props":[{"key":"heading","label":"Heading","type":"text","helpText":"Heading + stats layout only.","ai":true,"recommendedMax":60,"localized":true,"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"stats","label":"Stats","type":"table","config":{"minItems":2,"maxItems":5,"fields":[{"key":"prefix","label":"Before","type":"text","helpText":"Shown before the number, e.g. $.","placeholder":"$","config":{"maxLength":3}},{"key":"value","label":"Number","type":"number","helpText":"Digits only. Formatting is added per language.","required":true,"config":{"step":0.1}},{"key":"suffix","label":"After","type":"text","helpText":"Shown after the number, e.g. %, k+, yrs.","placeholder":"k+","config":{"maxLength":6}},{"key":"decimals","label":"Decimals","type":"number","defaultValue":0,"advanced":true,"config":{"min":0,"max":2,"step":1}},{"key":"label","label":"Label","type":"text","required":true,"localized":true,"config":{"maxLength":48}},{"key":"source","label":"Source","type":"link"},{"key":"asOf","label":"As of","type":"date"}]},"ui":{"itemLabel":"Stat","icon":"number","preview":{"title":"label","subtitle":"value","fallback":"Untitled stat"},"tab":{"id":"content"}}},{"key":"useCountUp","label":"Count up on scroll","type":"boolean","defaultValue":true,"ui":{"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":"Three to five big numbers in a row, each with its source","category":"Features & storytelling","icon":"chart-bar","preview":{"title":"heading","icon":"chart-bar"}}},
|
|
1400
|
-
{"id":"manifesto-pull-quote","name":"Manifesto / pull quote","category":"Features & storytelling","kind":"block","tags":["conditional","rich-text","variants","localized"],"proves":"Mode select swaps an array of rich-text lines for a single quote · overlay shown only when a background exists (notEmpty)","why":"One block covers both a multi-line manifesto and a single pull quote because they share attribution and treatment; a `mode` select decides which content field shows so editors never see both. Each manifesto line is a tiny RICH-TEXT value (italic for emphasis only) rather than a plain string with markup, so emphasis survives translation. Attribution is a small inline object. The overlay slider only appears when a background image exists (`notEmpty` condition).","htmlSignals":["Very large type (≥ 2.5rem) over a full-width section with a few short lines or one `<blockquote>`","`<blockquote>` with `<cite>` or a `<figcaption>` holding name/role, often with a signature `<img>`","Lines revealed one at a time on scroll (`data-aos`, GSAP `SplitText`, staggered opacity)"],"mcp":"One `<blockquote>` (or one paragraph in display type) → mode quote, quote text WITHOUT surrounding quotation marks (the renderer adds typographic quotes). Several short display-size lines/paragraphs → mode lines, one line per element, keeping `<em>`/`<i>` as italic marks and dropping spans used only for color. `<cite>`/caption → attribution.name / role; signature image → attribution.signature. Section background-image → background + overlay from the gradient/scrim opacity.","pitfalls":["Quotation marks typed into content double up with the design's quotes — strip them.","Lines split by `<br>` inside one paragraph are still separate lines."],"notCarried":["variants"],"component":{"name":"Manifesto","slug":"manifesto","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"mode","label":"Content","type":"select","defaultValue":"lines","config":{"options":[{"label":"Lines","value":"lines"},{"label":"Quote","value":"quote"}]},"ui":{"control":"segmented","tab":{"id":"content"}}},{"key":"lines","label":"Lines","type":"array","showIf":{"match":"all","rules":[{"field":"mode","op":"eq","value":"lines"}]},"config":{"minItems":2,"maxItems":8,"itemType":"richtext","item":{"localized":true,"helpText":"Italic words are emphasised."}},"ui":{"itemLabel":"Line","tab":{"id":"content"}}},{"key":"quote","label":"Quote","type":"longtext","helpText":"Without quotation marks; the design adds them.","required":true,"showIf":{"match":"all","rules":[{"field":"mode","op":"eq","value":"quote"}]},"recommendedMax":220,"localized":true,"ui":{"rows":4,"tab":{"id":"content"}}},{"key":"attribution","label":"Attribution","type":"object","openMode":"inline","config":{"fields":[{"key":"name","label":"Name","type":"text","config":{"maxLength":48}},{"key":"role","label":"Role","type":"text","localized":true,"config":{"maxLength":64}},{"key":"signature","label":"Signature","type":"image","helpText":"A transparent PNG or SVG."}]},"ui":{"icon":"signature","tab":{"id":"content"}}},{"key":"background","label":"Background image","type":"image","ui":{"tab":{"id":"media","label":"Media"}}},{"key":"overlay","label":"Image overlay","type":"number","defaultValue":45,"showIf":{"match":"all","rules":[{"field":"background","op":"notEmpty"}]},"config":{"min":0,"max":80,"step":5,"unit":"%"},"ui":{"control":"slider","tab":{"id":"design","label":"Design"}}},{"key":"size","label":"Type size","type":"select","defaultValue":"xl","config":{"options":[{"label":"Large","value":"lg"},{"label":"Extra large","value":"xl"},{"label":"Display","value":"display"}]},"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 big-type statement of belief or a single pull quote, with attribution","category":"Features & storytelling","icon":"blockquote","preview":{"title":"eyebrow","subtitle":"attribution.name","icon":"quote"}}},
|
|
1400
|
+
{"id":"manifesto-pull-quote","name":"Manifesto / pull quote","category":"Features & storytelling","kind":"block","tags":["conditional","rich-text","variants","localized"],"proves":"Mode select swaps an array of rich-text lines for a single quote · overlay shown only when a background exists (notEmpty)","why":"One block covers both a multi-line manifesto and a single pull quote because they share attribution and treatment; a `mode` select decides which content field shows so editors never see both. Each manifesto line is a tiny RICH-TEXT value (italic for emphasis only) rather than a plain string with markup, so emphasis survives translation. Attribution is a small inline object. The overlay slider only appears when a background image exists (`notEmpty` condition).","htmlSignals":["Very large type (≥ 2.5rem) over a full-width section with a few short lines or one `<blockquote>`","`<blockquote>` with `<cite>` or a `<figcaption>` holding name/role, often with a signature `<img>`","Lines revealed one at a time on scroll (`data-aos`, GSAP `SplitText`, staggered opacity)"],"mcp":"One `<blockquote>` (or one paragraph in display type) → mode quote, quote text WITHOUT surrounding quotation marks (the renderer adds typographic quotes). Several short display-size lines/paragraphs → mode lines, one line per element, keeping `<em>`/`<i>` as italic marks and dropping spans used only for color. `<cite>`/caption → attribution.name / role; signature image → attribution.signature. Section background-image → background + overlay from the gradient/scrim opacity.","pitfalls":["Quotation marks typed into content double up with the design's quotes — strip them.","Lines split by `<br>` inside one paragraph are still separate lines."],"notCarried":["item settings","variants"],"component":{"name":"Manifesto","slug":"manifesto","props":[{"key":"eyebrow","label":"Eyebrow","type":"text","config":{"maxLength":32},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"mode","label":"Content","type":"select","defaultValue":"lines","config":{"options":[{"label":"Lines","value":"lines"},{"label":"Quote","value":"quote"}]},"ui":{"control":"segmented","tab":{"id":"content"}}},{"key":"lines","label":"Lines","type":"array","showIf":{"match":"all","rules":[{"field":"mode","op":"eq","value":"lines"}]},"config":{"minItems":2,"maxItems":8,"itemType":"richtext","item":{"localized":true,"helpText":"Italic words are emphasised."}},"ui":{"itemLabel":"Line","tab":{"id":"content"}}},{"key":"quote","label":"Quote","type":"longtext","helpText":"Without quotation marks; the design adds them.","required":true,"showIf":{"match":"all","rules":[{"field":"mode","op":"eq","value":"quote"}]},"recommendedMax":220,"localized":true,"ui":{"rows":4,"tab":{"id":"content"}}},{"key":"attribution","label":"Attribution","type":"object","openMode":"inline","config":{"fields":[{"key":"name","label":"Name","type":"text","config":{"maxLength":48}},{"key":"role","label":"Role","type":"text","localized":true,"config":{"maxLength":64}},{"key":"signature","label":"Signature","type":"image","helpText":"A transparent PNG or SVG."}]},"ui":{"icon":"signature","tab":{"id":"content"}}},{"key":"background","label":"Background image","type":"image","ui":{"tab":{"id":"media","label":"Media"}}},{"key":"overlay","label":"Image overlay","type":"number","defaultValue":45,"showIf":{"match":"all","rules":[{"field":"background","op":"notEmpty"}]},"config":{"min":0,"max":80,"step":5,"unit":"%"},"ui":{"control":"slider","tab":{"id":"design","label":"Design"}}},{"key":"size","label":"Type size","type":"select","defaultValue":"xl","config":{"options":[{"label":"Large","value":"lg"},{"label":"Extra large","value":"xl"},{"label":"Display","value":"display"}]},"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 big-type statement of belief or a single pull quote, with attribution","category":"Features & storytelling","icon":"blockquote","preview":{"title":"eyebrow","subtitle":"attribution.name","icon":"quote"}}},
|
|
1401
1401
|
{"id":"problem-solution","name":"Problem → solution","category":"Features & storytelling","kind":"block","tags":["repeater","variants","validation"],"proves":"Pairs keep both columns aligned · column labels as small objects with defaults","why":"Problems and solutions are stored as PAIRS, not two independent arrays, because the strongest version of this section lines each pain up with its fix — two arrays drift (four problems, three solutions) and the paired layout breaks. The two-column variant reads the same data column-wise. Column labels and summaries are small objects with sensible defaults so the common case needs no typing.","htmlSignals":["Two columns labeled “Before / After”, “Without X / With X”, “The old way / The new way”","One column with ✗ / red / strikethrough items, the other with ✓ / green items","Equal item counts in both columns, often vertically aligned"],"mcp":"Find the two lists; take their headers → problem.label / solution.label. If counts match, zip item i of each list into a pair; if they differ, create pairs for the shorter length and append the leftovers with an empty partner and a review flag. Small numeric callouts (“6 hours saved”) → metric. Strike-through/red styling → tone warning. Layout: rows where each problem sits next to its fix → pairs, two independent stacks → columns.","pitfalls":["Unequal lists in the source must not be silently truncated — flag them."],"notCarried":["variants"],"component":{"name":"Problem and solution","slug":"problem-solution","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,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"problem","label":"Problem side","type":"object","config":{"fields":[{"key":"label","label":"Column label","type":"text","defaultValue":"Without Ledgerly","localized":true,"config":{"maxLength":32}},{"key":"summary","label":"Summary","type":"longtext","localized":true,"ui":{"rows":2}}]},"ui":{"icon":"alert-triangle","tab":{"id":"content"}}},{"key":"solution","label":"Solution side","type":"object","config":{"fields":[{"key":"label","label":"Column label","type":"text","defaultValue":"With Ledgerly","localized":true,"config":{"maxLength":32}},{"key":"summary","label":"Summary","type":"longtext","localized":true,"ui":{"rows":2}},{"key":"button","label":"Button","type":"button"}]},"ui":{"icon":"circle-check","tab":{"id":"content"}}},{"key":"pairs","label":"Pairs","type":"table","config":{"minItems":2,"maxItems":6,"fields":[{"key":"problem","label":"Problem","type":"text","required":true,"ai":true,"localized":true,"config":{"maxLength":90}},{"key":"solution","label":"Solution","type":"text","required":true,"ai":true,"localized":true,"config":{"maxLength":90}},{"key":"metric","label":"Proof","type":"text","localized":true,"placeholder":"4 hours saved a month","config":{"maxLength":40}}]},"ui":{"itemLabel":"Pair","icon":"arrows-exchange","preview":{"title":"problem","subtitle":"solution","fallback":"Untitled pair"},"tab":{"id":"content"}}},{"key":"tone","label":"Problem tone","type":"select","defaultValue":"muted","config":{"options":[{"label":"Muted","value":"muted"},{"label":"Warning","value":"warning"}]},"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":"The pain your buyer has today, set against how you fix it","category":"Features & storytelling","icon":"arrows-exchange","preview":{"title":"heading","icon":"arrows-exchange"}}},
|
|
1402
1402
|
{"id":"integrations-grid","name":"Integrations grid","category":"Features & storytelling","kind":"block","tags":["dynamic-query","references","conditional","variants","media-heavy"],"proves":"Dynamic query vs manual references to a collection · filter chips derived from referenced categories","why":"Integrations are REFERENCED, not inlined: each one has its own detail page (/integrations/stripe), logo, category and description, and appears on several pages — that is a collection (`col_integrations`) with a category reference (`col_integration_categories`). The section stores only HOW to pick: a dynamic query (categories, featured, limit, sort) so new integrations appear automatically, or a manual list of references for a curated row. Filter chips are derived from the categories of what is shown, so there is no second list to maintain. Inline the items only when the site has no integration pages and fewer than ~12 logos.","htmlSignals":["A grid of 12+ tiles each with a third-party logo, a product name and a short line, linking to `/integrations/<slug>`","Filter chips or a sidebar of categories (“All”, “Payments”, “CRM”) with `data-filter`/`aria-pressed`","A search input filtering the tiles; a “See all integrations” link"],"mcp":"If tiles link to per-integration pages (shared `/integrations/` prefix), create or match `col_integrations` entries (name, slug from href, logo, one-line description, category from the active filter or a `data-category` attribute) and set source to `query` with the categories present. If tiles do not link anywhere, use source `manual` and create entries anyway so logos are reusable. Filter chip labels → integration category entries (skip “All”). A visible search box → showSearch. Count tiles shown before a “See all” link → limit.","pitfalls":["Brand logos have usage rules — keep the original SVG, never recolor it in content; `isMonochrome` is a render-time filter.","Category options cannot come from a sibling array in our schema, which is exactly why categories are a referenced collection."],"notCarried":["variants"],"component":{"name":"Integrations grid","slug":"integrations-grid","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,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"subheading","label":"Subheading","type":"longtext","localized":true,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"source","label":"Which integrations","type":"select","defaultValue":"query","config":{"options":[{"label":"From the Integrations collection","value":"query","description":"New integrations appear here on their own"},{"label":"Pick them","value":"manual","description":"A fixed list in your order"}]},"ui":{"control":"radio","tab":{"id":"content"}}},{"key":"categories","label":"Categories","type":"multi-reference","helpText":"Leave empty for all categories.","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"query"}]},"config":{"contentModelId":"col_integration_categories"},"ui":{"tab":{"id":"content"}}},{"key":"showFeaturedOnly","label":"Featured only","type":"boolean","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"query"}]},"ui":{"tab":{"id":"content"}}},{"key":"limit","label":"How many","type":"number","defaultValue":24,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"query"}]},"config":{"min":4,"max":96,"step":4},"ui":{"tab":{"id":"content"}}},{"key":"sort","label":"Sort by","type":"select","defaultValue":"popular","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"query"}]},"config":{"options":[{"label":"Most used","value":"popular"},{"label":"A to Z","value":"az"},{"label":"Newest","value":"new"}]},"ui":{"tab":{"id":"content"}}},{"key":"items","label":"Integrations","type":"multi-reference","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"manual"}]},"config":{"min":4,"max":48,"contentModelId":"col_integrations"},"ui":{"itemLabel":"Integration","layout":"gallery","itemName":"integration","tab":{"id":"content"}}},{"key":"showFilter","label":"Show category filter","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"content"}}},{"key":"showSearch","label":"Show search","type":"boolean","ui":{"tab":{"id":"content"}}},{"key":"viewAllButton","label":"View all button","type":"button","helpText":"Hidden when everything already fits.","ui":{"tab":{"id":"content"}}},{"key":"columns","label":"Columns on desktop","type":"number","defaultValue":4,"config":{"min":3,"max":6,"step":1},"ui":{"control":"slider","tab":{"id":"design","label":"Design"}}},{"key":"isMonochrome","label":"Monochrome logos","type":"boolean","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":"Logos of the tools you connect with, filterable by category, each linking to its page","category":"Features & storytelling","icon":"plug-connected","preview":{"title":"heading","icon":"plug-connected"}}},
|
|
1403
1403
|
{"id":"testimonial-grid","name":"Testimonial grid","category":"Social proof","kind":"block","tags":["references","dynamic-query","conditional","variants","validation"],"proves":"References to a Testimonials collection · pick vs query (tags, limit, min rating) · uniqueness","why":"Testimonials are REFERENCES to `col_testimonials` because the same quote appears on the home page, product pages and the reviews page, and each one carries facts that must not drift between copies: the customer's consent date, their exact words, rating, photo and the product they bought. The section only stores which ones and how many. A query mode (by tag, limit, minimum rating) keeps product pages fresh without hand-curation. Inline the quotes only for a one-off campaign page whose quotes appear nowhere else.","htmlSignals":["A grid/masonry (`column-count`, `grid-auto-flow: dense`) of 3+ cards each with a quote, a person name, a role/company and often an avatar","Star ratings (5 SVG stars, `aria-label=\"5 out of 5 stars\"`, ★ characters)","`<blockquote>` + `<figcaption>`/`<cite>` per card","Headings like “What customers say”, “Reviews”, “Loved by …”"],"mcp":"For each card, create or match a `col_testimonials` entry: quote (strip surrounding quotation marks), name, role, company, photo, rating (count filled stars or parse aria-label), product if the card names one. Match existing entries by name + first 40 characters of the quote before creating. Store references in source `pick` in DOM order. Uniform card heights → grid; varying heights → masonry; one large first card → featured. Never import a testimonial without a name — flag it.","pitfalls":["Inlining quotes creates copies that drift when the customer asks for an edit or removal — reference them.","Grids look broken with 4 or 5 items in a 3-column layout; validation nudges multiples of 3.","Do not emit Review JSON-LD for testimonials about your own business — Google ignores self-serving reviews."],"notCarried":["variants"],"component":{"name":"Testimonial grid","slug":"testimonial-grid","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,"localized":true,"ui":{"tab":{"id":"content"}}},{"key":"source","label":"Which testimonials","type":"select","defaultValue":"pick","config":{"options":[{"label":"Pick them","value":"pick","description":"A fixed set in your order"},{"label":"Latest matching","value":"query","description":"Filled from the collection by tag"}]},"ui":{"control":"radio","tab":{"id":"content"}}},{"key":"testimonials","label":"Testimonials","type":"multi-reference","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"pick"}]},"unique":true,"config":{"min":3,"max":12,"contentModelId":"col_testimonials"},"ui":{"itemLabel":"Testimonial","tab":{"id":"content"}}},{"key":"tags","label":"Tagged","type":"tags","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"query"}]},"ui":{"tab":{"id":"content"}}},{"key":"limit","label":"How many","type":"number","defaultValue":6,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"query"}]},"config":{"min":3,"max":12,"step":3},"ui":{"tab":{"id":"content"}}},{"key":"minRating","label":"Minimum rating","type":"rating","helpText":"Leave empty to include quotes without a rating.","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"query"}]},"config":{"step":0.1},"ui":{"tab":{"id":"content"}}},{"key":"showRating","label":"Show rating","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design","label":"Design"}}},{"key":"showPhotos","label":"Show photos","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"design"}}},{"key":"button","label":"Button","type":"button","ui":{"tab":{"id":"content"}}},{"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":"Customer quotes from the Testimonials collection, in a grid or masonry","category":"Social proof","icon":"message-star","preview":{"title":"heading","icon":"message-star"}}},
|
|
@@ -1436,7 +1436,7 @@
|
|
|
1436
1436
|
{"id":"pricing-faq","name":"Pricing FAQ","category":"Pricing & plans","kind":"block","tags":["rich-text","seo-structured","conditional","references","repeater","validation"],"proves":"Grouped questions (written here or FAQs collection) · price tokens in answers so copy never drifts from the plans · FAQPage rich results","why":"A pricing FAQ is different from a general FAQ in two ways: it's GROUPED (plans, payments, security) — so groups › items, one level deeper than the core FAQ example — and its answers quote prices, which is where pricing pages most often contradict themselves. Answers therefore support {{plan.cycle}} tokens resolved from the Plans block on the same page, documented in helpMore. Written-here vs FAQs-collection stays a conditional pair (the collection reference is filtered to billing questions), and FAQPage rich results are a toggle because two FAQ blocks on one page must not both emit it.","htmlSignals":["a 'Pricing FAQ', 'Billing questions' or 'Frequently asked' heading right after the plans","<details>/<summary> or aria-expanded accordions, sometimes with group sub-headings","answers that mention the same prices as the plan cards","existing FAQPage JSON-LD"],"mcp":"Group sub-headings → groups; each question/answer → items (answer as rich text, keep links). When an answer contains a price that equals a plan price on the same page, replace it with the matching token ({{pro.monthly}}) and note it in the conversion receipt. If the site has an FAQs collection with the same questions, prefer source:'collection' with references. Existing FAQPage JSON-LD → useRichResults: true (and remove the hand-written script).","pitfalls":["Tokens are plain strings inside rich text — typos aren't caught until preview (gap: typed inline references to plan fields).","Two FAQ blocks emitting FAQPage on one URL is invalid; the toggle exists for that."],"notCarried":["variants"],"component":{"name":"Pricing FAQ","slug":"pricing-faq","props":[{"key":"heading","label":"Heading","type":"text","required":true,"recommendedMax":48,"localized":true,"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"source","label":"Questions come from","type":"select","defaultValue":"inline","config":{"options":[{"label":"Written here","value":"inline"},{"label":"FAQs collection","value":"collection"}]},"ui":{"control":"segmented","tab":{"id":"content"}}},{"key":"groups","label":"Groups","type":"table","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"inline"}]},"config":{"minItems":1,"maxItems":5,"fields":[{"key":"title","label":"Group title","type":"text","required":true,"config":{"maxLength":32}},{"key":"items","label":"Questions","type":"table","fields":[{"key":"question","label":"Question","type":"text","required":true,"ai":true,"localized":true,"config":{"maxLength":120}},{"key":"answer","label":"Answer","type":"richtext","helpText":"Use {{pro.yearly}}-style tokens so prices stay in step with the plans.","required":true,"helpMore":"Tokens read the Plans block on this page: {{key.monthly}}, {{key.yearly}} or {{key.name}}, where key is the plan name in lowercase.","ai":true,"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"]}}],"config":{"minItems":1,"maxItems":10},"ui":{"itemLabel":"Question","itemName":"faqItem","icon":"help-circle","preview":{"title":"question","subtitle":"answer","fallback":"Untitled question"}}}]},"ui":{"itemLabel":"Group","itemName":"faqGroup","icon":"folder","preview":{"title":"title","fallback":"Untitled group"},"tab":{"id":"content"}}},{"key":"questions","label":"FAQs to show","type":"multi-reference","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"collection"}]},"config":{"max":12,"contentModelId":"col_faq","filter":"category == 'billing'"},"ui":{"itemName":"faqRef","itemTitle":"FAQ","tab":{"id":"content"}}},{"key":"contactButton","label":"Contact button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"useRichResults","label":"FAQ rich results","type":"boolean","helpText":"Turn off if another FAQ on this page already sends it.","defaultValue":true,"ui":{"tab":{"id":"settings","label":"Settings"}}},{"key":"isFirstOpen","label":"Open the first question","type":"boolean","defaultValue":true,"ui":{"tab":{"id":"settings"}}}],"description":"Billing questions, grouped, with prices that stay in sync","category":"Pricing & plans","icon":"help-circle","preview":{"title":"heading"}}},
|
|
1437
1437
|
{"id":"pricing-annual-savings-banner","name":"Pay-yearly savings banner","category":"Pricing & plans","kind":"block","tags":["personalization","conditional","validation","commerce"],"proves":"Savings expressed three ways (percent / months free / amount) as a conditional unit · audience targeting (members on monthly) · placement","why":"Unlike a sale banner, this one is about the BILLING CYCLE and only makes sense to some people, so audience is first-class (members on monthly need a signed-in portal; visitors see the public version). The saving can be told three ways — percent, months free, dollar amount — and each is a conditional numeric with its own unit and range, substituted into the message through a single {{saving}} token, so the copy and the number can't disagree.","htmlSignals":["a slim notice on a pricing/billing page: 'Switch to annual and save 20%', '2 months free'","links with ?cycle=yearly / ?billing=annual / /billing/switch","rendered only for logged-in users (inside an account/portal layout)"],"mcp":"Copy → message with the saving replaced by {{saving}}; detect the unit ('%' → percent, 'months free' → months, '$' → amount). A banner inside an authenticated layout → audience:'monthly-members'; on a public pricing page → 'visitors' or 'everyone'. Its URL path → placements.","pitfalls":["The saving isn't computed from the actual plan prices (no computed fields) — a price change can make the banner untrue.","Targeting signed-in members needs the portal integration; without it the banner silently shows to no one."],"notCarried":[],"component":{"name":"Savings banner","slug":"savings-banner","props":[{"key":"message","label":"Message","type":"text","helpText":"{{saving}} becomes the saving.","required":true,"ai":true,"recommendedMax":70,"config":{"maxLength":90},"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"savingType","label":"Saving shown as","type":"select","defaultValue":"months","config":{"options":[{"label":"Percent","value":"percent"},{"label":"Months free","value":"months"},{"label":"Amount","value":"amount"}]},"ui":{"control":"segmented","tab":{"id":"content"}}},{"key":"percent","label":"Percent","type":"number","required":true,"showIf":{"match":"all","rules":[{"field":"savingType","op":"eq","value":"percent"}]},"config":{"min":1,"max":50,"step":1,"unit":"%"},"ui":{"tab":{"id":"content"}}},{"key":"months","label":"Months free","type":"number","required":true,"showIf":{"match":"all","rules":[{"field":"savingType","op":"eq","value":"months"}]},"config":{"min":1,"max":4,"step":1,"unit":"months"},"ui":{"tab":{"id":"content"}}},{"key":"amount","label":"Amount","type":"number","helpText":"In dollars.","required":true,"showIf":{"match":"all","rules":[{"field":"savingType","op":"eq","value":"amount"}]},"config":{"unit":"USD","min":1,"step":1},"ui":{"tab":{"id":"content"}}},{"key":"button","label":"Button","type":"button","required":true,"ui":{"tab":{"id":"content"}}},{"key":"audience","label":"Who sees it","type":"select","defaultValue":"monthly-members","config":{"options":[{"label":"Everyone","value":"everyone"},{"label":"Visitors who aren't members","value":"visitors"},{"label":"Members paying monthly","value":"monthly-members","description":"Needs them signed in to the member portal"}]},"ui":{"tab":{"id":"targeting","label":"Who and where"}}},{"key":"placements","label":"Shows on","type":"multiselect","config":{"min":1,"options":[{"label":"Membership page","value":"pricing"},{"label":"Member portal home","value":"portal"},{"label":"After booking confirmation","value":"booking"}]},"ui":{"control":"checkbox","tab":{"id":"targeting"}}},{"key":"until","label":"Show until","type":"date","helpText":"Leave empty for an always-on offer.","ui":{"tab":{"id":"targeting"}}},{"key":"isDismissible","label":"Visitors can close it","type":"boolean","helpText":"Closed banners stay hidden for 30 days.","defaultValue":true,"ui":{"tab":{"id":"targeting"}}}],"description":"A nudge to switch to yearly billing, shown to the right people","category":"Pricing & plans","icon":"pig-money","preview":{"title":"message","subtitle":"audience","icon":"pig-money"}}},
|
|
1438
1438
|
{"id":"conversion-cta-band","name":"CTA band","category":"Conversion & forms","kind":"block","tags":["variants","conditional","media-heavy"],"proves":"Variants that swap layout without losing content · two button units · background as a conditional design cluster (color vs photo + overlay)","why":"The CTA band is the most-reused section on any site, so the schema optimises for swapping: three variants share one content shape, and fields one layout doesn't use (image on Centered) are kept rather than deleted so switching back loses nothing. Buttons are button units (label + link + style). Background is design, modelled as a conditional cluster — a color, or a photo with an overlay slider whose help gives the readable range.","htmlSignals":["a full-width section with high-contrast background, one heading, at most one sentence and 1–2 buttons","placed just before the footer or between long sections","a background-image with a semi-transparent overlay (::before with rgba/opacity or bg-black/40)","no form inputs (otherwise it's a newsletter or lead form)"],"mcp":"Heading/eyebrow/body text → fields; each <a>/<button> styled as a button → primaryButton/secondaryButton units (style from class: solid → primary, bordered → outline). Pick the variant from layout: centered text → centered, a sibling <img> column → split (+ image), flex row with buttons at the end → inline. Background image → background:'photo' + photo + overlay from the overlay opacity; solid color → map to the nearest brand token.","pitfalls":["Fields can't be conditioned on the variant (gap) — `image` is always visible and its help explains why.","Hard-coded hex colors break dark mode and brand updates; map to tokens."],"notCarried":["variants"],"component":{"name":"Call to action band","slug":"call-to-action","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":50,"localized":true,"config":{"maxLength":80},"ui":{"tab":{"id":"content"}}},{"key":"body","label":"Body","type":"longtext","helpText":"Hidden on phones in the Inline layout.","ai":true,"recommendedMax":140,"localized":true,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"primaryButton","label":"Primary button","type":"button","required":true,"ui":{"tab":{"id":"content"}}},{"key":"secondaryButton","label":"Secondary button","type":"button","ui":{"tab":{"id":"content"}}},{"key":"image","label":"Image","type":"image","helpText":"Split layout only.","ui":{"tab":{"id":"content"}}},{"key":"background","label":"Background","type":"select","defaultValue":"color","config":{"options":[{"label":"Color","value":"color"},{"label":"Photo","value":"photo"}]},"ui":{"control":"segmented","tab":{"id":"design","label":"Design"}}},{"key":"color","label":"Background color","type":"color","showIf":{"match":"all","rules":[{"field":"background","op":"eq","value":"color"}]},"ui":{"tab":{"id":"design"}}},{"key":"photo","label":"Background photo","type":"image","helpText":"At least 2000px wide.","showIf":{"match":"all","rules":[{"field":"background","op":"eq","value":"photo"}]},"ui":{"tab":{"id":"design"}}},{"key":"overlay","label":"Darken photo","type":"number","showIf":{"match":"all","rules":[{"field":"background","op":"eq","value":"photo"}]},"config":{"min":0,"max":80,"step":5,"unit":"%"},"ui":{"control":"slider","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 full-width band with one message and one or two buttons","category":"Conversion & forms","icon":"click","preview":{"title":"heading","subtitle":"body","media":"image"}}},
|
|
1439
|
-
{"id":"conversion-newsletter-consent","name":"Newsletter sign-up with consent","category":"Conversion & forms","kind":"block","tags":["form","references","conditional","validation","a11y","repeater"],"proves":"The simple inline form: visible label + placeholder + submit label · interest checkboxes that tag subscribers · consent mode (checkbox vs notice) · success with an optional code","why":"The newsletter is the 'simple inline form' case: the visitor sees one email field, but submissions still go to a form (the reference), so double opt-in, list sync and suppression live in one place. The section owns only presentation: a REQUIRED visible label (a placeholder is not a label — WCAG 3.3.2), the placeholder, the submit label (a string, not a button unit, because submit isn't a link), optional interest checkboxes that map to subscriber tags, and the consent mode — an unticked checkbox or a notice — with rich-text wording so the privacy link is a real link.","htmlSignals":["a <form> with exactly one type=email input (maybe a first-name input) and one submit button","copy like 'Subscribe', 'Join the list', 'Get the newsletter', 'No spam'","a consent checkbox or a small line mentioning privacy/unsubscribe","action URLs or scripts from Klaviyo, Mailchimp (list-manage.com), ConvertKit, Beehiiv"],"mcp":"Match the form to an existing form in Forms by its action/list id; otherwise create one with an email field (and first name if present) and reference it. Visible <label> → emailLabel (if only a placeholder exists, generate 'Email address' and flag it); button text → submitLabel; checkbox groups → interests with tags from their value attributes. A consent checkbox → consent:'checkbox' + its label as consentText; a fine-print line → 'notice'. Never inline the list id into the section.","pitfalls":["Placeholder-only fields fail accessibility; emailLabel is required for that reason.","A pre-ticked consent box is not valid consent under GDPR — the option says 'Unticked'.","Submit is a string, not `type: button`: our button unit is label + LINK, and a submit action has no link (gap: action buttons)."],"notCarried":["variants"],"component":{"name":"Newsletter sign-up","slug":"newsletter","props":[{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":48,"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"body","label":"Body","type":"longtext","ai":true,"recommendedMax":140,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"image","label":"Image","type":"image","helpText":"Card layout only.","ui":{"tab":{"id":"content"}}},{"key":"form","label":"Form","type":"form","helpText":"Sign-ups go to this form's list. Pick the one connected to your email tool.","required":true,"ui":{"tab":{"id":"content"}}},{"key":"emailLabel","label":"Field label","type":"text","helpText":"Read by screen readers. The Inline layout hides it.","required":true,"defaultValue":"Email address","config":{"maxLength":32},"ui":{"tab":{"id":"form","label":"Form & consent"}}},{"key":"placeholder","label":"Placeholder","type":"text","placeholder":"you@example.com","config":{"maxLength":40},"ui":{"tab":{"id":"form"}}},{"key":"submitLabel","label":"Button label","type":"text","required":true,"placeholder":"Subscribe","config":{"maxLength":20},"ui":{"tab":{"id":"form"}}},{"key":"interests","label":"Interests","type":"table","helpText":"Each one adds a tag to the subscriber.","openMode":"inline","config":{"maxItems":5,"fields":[{"key":"label","label":"Label","type":"text","required":true,"config":{"maxLength":32}},{"key":"tag","label":"Tag","type":"text","helpText":"Exactly as named in your email tool.","required":true,"config":{"pattern":"^[a-z0-9-]+$","patternMessage":"Use lowercase letters, numbers and hyphens, like camp-kitchen."}}]},"ui":{"itemLabel":"Interest","icon":"tag","preview":{"title":"label","subtitle":"tag","fallback":"Untitled interest"},"tab":{"id":"form"}}},{"key":"consent","label":"Consent","type":"select","defaultValue":"checkbox","config":{"options":[{"label":"Unticked checkbox","value":"checkbox","description":"Required for the EU, UK and Canada"},{"label":"A notice under the button","value":"notice","description":"Signing up is the consent"}]},"ui":{"control":"radio","tab":{"id":"form"}}},{"key":"consentText","label":"Consent wording","type":"richtext","required":true,"config":{"features":["bold","italic","
|
|
1439
|
+
{"id":"conversion-newsletter-consent","name":"Newsletter sign-up with consent","category":"Conversion & forms","kind":"block","tags":["form","references","conditional","validation","a11y","repeater"],"proves":"The simple inline form: visible label + placeholder + submit label · interest checkboxes that tag subscribers · consent mode (checkbox vs notice) · success with an optional code","why":"The newsletter is the 'simple inline form' case: the visitor sees one email field, but submissions still go to a form (the reference), so double opt-in, list sync and suppression live in one place. The section owns only presentation: a REQUIRED visible label (a placeholder is not a label — WCAG 3.3.2), the placeholder, the submit label (a string, not a button unit, because submit isn't a link), optional interest checkboxes that map to subscriber tags, and the consent mode — an unticked checkbox or a notice — with rich-text wording so the privacy link is a real link.","htmlSignals":["a <form> with exactly one type=email input (maybe a first-name input) and one submit button","copy like 'Subscribe', 'Join the list', 'Get the newsletter', 'No spam'","a consent checkbox or a small line mentioning privacy/unsubscribe","action URLs or scripts from Klaviyo, Mailchimp (list-manage.com), ConvertKit, Beehiiv"],"mcp":"Match the form to an existing form in Forms by its action/list id; otherwise create one with an email field (and first name if present) and reference it. Visible <label> → emailLabel (if only a placeholder exists, generate 'Email address' and flag it); button text → submitLabel; checkbox groups → interests with tags from their value attributes. A consent checkbox → consent:'checkbox' + its label as consentText; a fine-print line → 'notice'. Never inline the list id into the section.","pitfalls":["Placeholder-only fields fail accessibility; emailLabel is required for that reason.","A pre-ticked consent box is not valid consent under GDPR — the option says 'Unticked'.","Submit is a string, not `type: button`: our button unit is label + LINK, and a submit action has no link (gap: action buttons)."],"notCarried":["variants"],"component":{"name":"Newsletter sign-up","slug":"newsletter","props":[{"key":"heading","label":"Heading","type":"text","required":true,"ai":true,"recommendedMax":48,"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"body","label":"Body","type":"longtext","ai":true,"recommendedMax":140,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"image","label":"Image","type":"image","helpText":"Card layout only.","ui":{"tab":{"id":"content"}}},{"key":"form","label":"Form","type":"form","helpText":"Sign-ups go to this form's list. Pick the one connected to your email tool.","required":true,"ui":{"tab":{"id":"content"}}},{"key":"emailLabel","label":"Field label","type":"text","helpText":"Read by screen readers. The Inline layout hides it.","required":true,"defaultValue":"Email address","config":{"maxLength":32},"ui":{"tab":{"id":"form","label":"Form & consent"}}},{"key":"placeholder","label":"Placeholder","type":"text","placeholder":"you@example.com","config":{"maxLength":40},"ui":{"tab":{"id":"form"}}},{"key":"submitLabel","label":"Button label","type":"text","required":true,"placeholder":"Subscribe","config":{"maxLength":20},"ui":{"tab":{"id":"form"}}},{"key":"interests","label":"Interests","type":"table","helpText":"Each one adds a tag to the subscriber.","openMode":"inline","config":{"maxItems":5,"fields":[{"key":"label","label":"Label","type":"text","required":true,"config":{"maxLength":32}},{"key":"tag","label":"Tag","type":"text","helpText":"Exactly as named in your email tool.","required":true,"config":{"pattern":"^[a-z0-9-]+$","patternMessage":"Use lowercase letters, numbers and hyphens, like camp-kitchen."}}]},"ui":{"itemLabel":"Interest","icon":"tag","preview":{"title":"label","subtitle":"tag","fallback":"Untitled interest"},"tab":{"id":"form"}}},{"key":"consent","label":"Consent","type":"select","defaultValue":"checkbox","config":{"options":[{"label":"Unticked checkbox","value":"checkbox","description":"Required for the EU, UK and Canada"},{"label":"A notice under the button","value":"notice","description":"Signing up is the consent"}]},"ui":{"control":"radio","tab":{"id":"form"}}},{"key":"consentText","label":"Consent wording","type":"richtext","required":true,"config":{"features":["bold","italic","link"]},"ui":{"tab":{"id":"form"}}},{"key":"successMessage","label":"Thank-you message","type":"text","required":true,"placeholder":"You're in. Check your inbox to confirm.","config":{"maxLength":120},"ui":{"tab":{"id":"success","label":"After sign-up"}}},{"key":"welcomeCode","label":"Welcome code","type":"text","helpText":"Must exist in Shopify.","config":{"pattern":"^[A-Z0-9]{3,20}$","patternMessage":"Use capital letters and numbers, like SAVE20."},"ui":{"tab":{"id":"success"}}}],"description":"An email field, a promise and a clear consent line","category":"Conversion & forms","icon":"mail","preview":{"title":"heading","subtitle":"body","icon":"mail"}}},
|
|
1440
1440
|
{"id":"conversion-lead-capture","name":"Lead capture form + success state","category":"Conversion & forms","kind":"block","tags":["form","references","conditional","repeater","validation","rich-text"],"proves":"Form reference + section-level presentation · success: message / redirect / file download as a conditional trio · hidden attribution fields with tokens","why":"The FORM (fields, validation, notifications, CRM sync, spam protection) is a form in Forms referenced here; everything the section adds is presentation and context: the pitch, the reasons, an optional submit-label override for this placement, hidden attribution fields with submit-time tokens, and the success state. Success is a conditional trio — message, redirect (best for analytics) or download (message + file) — because those are the three things marketers actually choose between. Hidden fields are advanced: most editors never need them.","htmlSignals":["a two-column section: persuasive copy + bullets on one side, a multi-field <form> on the other","form fields beyond email (company, phone, store type, message) and a submit button with an action verb","<input type=hidden> fields named utm_*, lead_source, page_url","a thank-you state in markup (hidden div), a redirect in the submit handler, or a gated PDF link","HubSpot (hsforms), Marketo (mktoForm), Typeform or Formspree embeds/actions"],"mcp":"Extract the form's fields into a form in Forms (or match an existing one by field names) and reference it — never copy fields into the section. Copy and bullets → heading/body/points. Hidden inputs → hiddenFields, converting server-rendered values to tokens where they're clearly UTM/page values. Detect the success path: a hidden success div → message; window.location / redirect param → redirect; a PDF link revealed after submit → download.","pitfalls":["A per-section copy of the fields forks submissions and notification rules.","Redirect pages must exist and be noindexed natively — never add a robots field to the section.","Token names in hidden fields are free strings; a typo silently sends an empty value."],"notCarried":["variants"],"component":{"name":"Lead form","slug":"lead-form","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":56,"ui":{"tab":{"id":"content"}}},{"key":"body","label":"Body","type":"richtext","ai":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":"points","label":"Reasons to apply","type":"table","openMode":"inline","config":{"maxItems":4,"fields":[{"key":"icon","label":"Icon","type":"icon"},{"key":"label","label":"Label","type":"text","required":true,"config":{"maxLength":56}}]},"ui":{"itemLabel":"Reason","icon":"check","preview":{"title":"label","fallback":"Untitled reason"},"tab":{"id":"content"}}},{"key":"form","label":"Form","type":"form","helpText":"Fields, notifications and submissions are managed in Forms.","required":true,"ui":{"tab":{"id":"form","label":"Form"}}},{"key":"submitLabel","label":"Button label","type":"text","helpText":"Overrides the form's own label here only.","config":{"maxLength":24},"ui":{"tab":{"id":"form"}}},{"key":"hiddenFields","label":"Hidden fields","type":"table","helpText":"Not shown. Sent with every submission from this page.","helpMore":"Tokens: {{utm_source}}, {{utm_campaign}}, {{page_url}}, {{referrer}}.","advanced":true,"openMode":"inline","config":{"maxItems":6,"fields":[{"key":"name","label":"Field key","type":"text","required":true,"config":{"pattern":"^[a-z_]+$","patternMessage":"Use lowercase letters and underscores, like analytics_storage."}},{"key":"value","label":"Value","type":"text","required":true,"config":{"maxLength":80}}]},"ui":{"itemLabel":"Hidden field","icon":"eye-off","preview":{"title":"name","subtitle":"value","fallback":"Untitled hidden field"},"tab":{"id":"form"}}},{"key":"onSuccess","label":"Then","type":"select","defaultValue":"message","config":{"options":[{"label":"Show a message","value":"message","icon":"message-check"},{"label":"Go to a page","value":"redirect","icon":"arrow-right","description":"Best for tracking conversions"},{"label":"Start a download","value":"download","icon":"download"}]},"ui":{"control":"cards","tab":{"id":"success","label":"After sending"}}},{"key":"successMessage","label":"Message","type":"richtext","required":true,"showIf":{"match":"all","rules":[{"field":"onSuccess","op":"in","value":["message","download"]}]},"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":"success"}}},{"key":"redirect","label":"Page","type":"link","required":true,"showIf":{"match":"all","rules":[{"field":"onSuccess","op":"eq","value":"redirect"}]},"ui":{"tab":{"id":"success"}}},{"key":"file","label":"File","type":"file","helpText":"A PDF under 10 MB. The link is also emailed to them.","required":true,"showIf":{"match":"all","rules":[{"field":"onSuccess","op":"eq","value":"download"}]},"ui":{"tab":{"id":"success"}}},{"key":"privacyNote","label":"Privacy note","type":"richtext","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":"form"}}}],"description":"A pitch beside a form, with what happens after they send it","category":"Conversion & forms","icon":"forms","preview":{"title":"heading","subtitle":"form","icon":"forms"}}},
|
|
1441
1441
|
{"id":"conversion-multi-step-form","name":"Multi-step form","category":"Conversion & forms","kind":"block","tags":["form","polymorphic-array","deep-nesting","conditional","validation","references","a11y"],"proves":"form grouped into steps by field key OR steps › polymorphic fields › options built here · visitor-side showIf branching · progress UI","why":"Two honest paths. The recommended one references a form in Forms and only GROUPS its fields into steps by key (presentation stays here, data stays in Forms). The 'Built here' path exists for one-off forms and shows the full inline shape: steps › fields (a polymorphic array of text | choice | scale | consent) › answers — 4 drill levels, each field type carrying only the settings it needs. Branching ('ask for the surgery date only if they had surgery') is visitor-side DATA in `showIf`, deliberately separate from schema `hidden`, which only controls what the editor sees. The sample is a clinic intake, so 'Remember answers' is off — health data shouldn't sit in a browser.","htmlSignals":["one <form> split into fieldsets/panels with Next/Back buttons and only one visible at a time","a progress bar, step indicator (1 · 2 · 3) or 'Step 2 of 3'","fields that appear when an earlier answer changes (data-show-if, x-show, conditional rendering)","Typeform/Jotform/Tally-style one-question-per-screen layouts"],"mcp":"Prefer source:'form': create or match a form in Forms with ALL fields (flattened), then emit formSteps with each panel's field names as fieldKeys. Use source:'inline' only when asked for a one-off. Map inputs: text/email/tel/date/textarea → textField with format; radio/checkbox groups → choiceField (+ options with value keys); range inputs → scaleField; consent checkboxes → consentField. Translate show/hide scripts into showIf on the dependent field (equals / not / answered). Health, financial or ID fields → set saveProgress:false and flag the form for a compliance review.","pitfalls":["Schema conditions can't read a parent's value (gap), so the two step arrays sit side by side at the root instead of one array whose items change shape.","`showIf.field` is a string key, not a reference to an earlier field (gap: references within the same entry) — renaming a key breaks the branch silently.","Inline-built forms fork submissions and notifications from the Forms area; keep them rare.","Persisting answers in localStorage is a privacy risk for health data."],"notCarried":[],"component":{"name":"Multi-step form","slug":"multi-step-form","props":[{"key":"heading","label":"Heading","type":"text","required":true,"recommendedMax":48,"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"intro","label":"Intro","type":"longtext","recommendedMax":160,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"source","label":"Fields come from","type":"select","defaultValue":"form","config":{"options":[{"label":"A form in Forms","value":"form","icon":"forms","description":"Recommended: one set of fields everywhere"},{"label":"Built here","value":"inline","icon":"pencil","description":"Only for a one-off form"}]},"ui":{"control":"cards","tab":{"id":"steps","label":"Steps"}}},{"key":"form","label":"Form","type":"form","helpText":"Its fields are grouped into the steps below by key.","required":true,"showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"form"}]},"ui":{"tab":{"id":"steps"}}},{"key":"formSteps","label":"Steps","type":"table","helpText":"Fields not placed in a step go in the last one.","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"form"}]},"config":{"minItems":2,"maxItems":6,"fields":[{"key":"title","label":"Step title","type":"text","required":true,"config":{"maxLength":32}},{"key":"description","label":"Description","type":"text","config":{"maxLength":100}},{"key":"fieldKeys","label":"Fields","type":"array","helpText":"The form's field keys, in order, e.g. first_name.","config":{"itemType":"text","minItems":1},"ui":{"itemLabel":"Field"}}]},"ui":{"itemLabel":"Step","icon":"list-numbers","preview":{"title":"title","subtitle":"fieldKeys","fallback":"Untitled step"},"tab":{"id":"steps"}}},{"key":"steps","label":"Steps","type":"table","showIf":{"match":"all","rules":[{"field":"source","op":"eq","value":"inline"}]},"config":{"minItems":2,"maxItems":6,"fields":[{"key":"title","label":"Step title","type":"text","required":true,"config":{"maxLength":32}},{"key":"description","label":"Description","type":"text","config":{"maxLength":100}},{"key":"fields","label":"Fields","type":"table","config":{"mode":"types","minItems":1,"maxItems":8,"itemTypes":[{"name":"textField","label":"Text","fields":[{"key":"key","label":"Key","type":"text","helpText":"The column name in submissions.","required":true,"config":{"pattern":"^[a-z_]+$","patternMessage":"Use lowercase letters and underscores, like analytics_storage."}},{"key":"label","label":"Label","type":"text","required":true,"config":{"maxLength":60}},{"key":"format","label":"Format","type":"select","defaultValue":"text","options":[{"label":"Text","value":"text"},{"label":"Email","value":"email"},{"label":"Phone","value":"phone"},{"label":"Date","value":"date"},{"label":"Paragraph","value":"long"}]},{"key":"isRequired","label":"Required","type":"boolean"},{"key":"showIf","label":"Only show if","type":"object","helpText":"Leave empty to always show it.","openMode":"popover","fields":[{"key":"field","label":"Answer to","type":"text","helpText":"The key of an earlier question or field.","config":{"maxLength":32}},{"key":"operator","label":"Condition","type":"select","defaultValue":"equals","options":[{"label":"Is","value":"equals"},{"label":"Is not","value":"not"},{"label":"Has any answer","value":"answered"}]},{"key":"value","label":"Value","type":"text","helpText":"The answer's key, e.g. self-pay.","showIf":{"match":"all","rules":[{"field":"operator","op":"in","value":["equals","not"]}]},"config":{"maxLength":48}}],"ui":{"icon":"git-branch"}}],"icon":"forms","preview":{"title":"label","subtitle":"key","fallback":"Untitled text field"}},{"name":"choiceField","label":"Choice","fields":[{"key":"key","label":"Key","type":"text","required":true,"config":{"pattern":"^[a-z_]+$","patternMessage":"Use lowercase letters and underscores, like analytics_storage."}},{"key":"label","label":"Question","type":"text","required":true,"config":{"maxLength":80}},{"key":"allowMultiple","label":"Allow several answers","type":"boolean"},{"key":"options","label":"Answers","type":"table","openMode":"inline","fields":[{"key":"label","label":"Label","type":"text","required":true,"config":{"maxLength":48}},{"key":"value","label":"Key","type":"text","required":true,"config":{"pattern":"^[a-z0-9-]+$","patternMessage":"Use lowercase letters, numbers and hyphens, like camp-kitchen."}}],"config":{"minItems":2,"maxItems":12},"ui":{"itemLabel":"Answer","itemName":"choice","icon":"point","preview":{"title":"label","subtitle":"value","fallback":"Untitled answer"}}},{"key":"isRequired","label":"Required","type":"boolean"},{"key":"showIf","label":"Only show if","type":"object","helpText":"Leave empty to always show it.","openMode":"popover","fields":[{"key":"field","label":"Answer to","type":"text","helpText":"The key of an earlier question or field.","config":{"maxLength":32}},{"key":"operator","label":"Condition","type":"select","defaultValue":"equals","options":[{"label":"Is","value":"equals"},{"label":"Is not","value":"not"},{"label":"Has any answer","value":"answered"}]},{"key":"value","label":"Value","type":"text","helpText":"The answer's key, e.g. self-pay.","showIf":{"match":"all","rules":[{"field":"operator","op":"in","value":["equals","not"]}]},"config":{"maxLength":48}}],"ui":{"icon":"git-branch"}}],"icon":"list-check","preview":{"title":"label","subtitle":"key","fallback":"Untitled choice field"}},{"name":"scaleField","label":"Scale","fields":[{"key":"key","label":"Key","type":"text","required":true,"config":{"pattern":"^[a-z_]+$","patternMessage":"Use lowercase letters and underscores, like analytics_storage."}},{"key":"label","label":"Question","type":"text","required":true,"config":{"maxLength":80}},{"key":"min","label":"From","type":"number","defaultValue":0},{"key":"max","label":"To","type":"number","defaultValue":10},{"key":"minLabel","label":"Low end means","type":"text","placeholder":"No pain","config":{"maxLength":24}},{"key":"maxLabel","label":"High end means","type":"text","placeholder":"Worst pain imaginable","config":{"maxLength":24}},{"key":"showIf","label":"Only show if","type":"object","helpText":"Leave empty to always show it.","openMode":"popover","fields":[{"key":"field","label":"Answer to","type":"text","helpText":"The key of an earlier question or field.","config":{"maxLength":32}},{"key":"operator","label":"Condition","type":"select","defaultValue":"equals","options":[{"label":"Is","value":"equals"},{"label":"Is not","value":"not"},{"label":"Has any answer","value":"answered"}]},{"key":"value","label":"Value","type":"text","helpText":"The answer's key, e.g. self-pay.","showIf":{"match":"all","rules":[{"field":"operator","op":"in","value":["equals","not"]}]},"config":{"maxLength":48}}],"ui":{"icon":"git-branch"}}],"icon":"adjustments-horizontal","preview":{"title":"label","subtitle":"key","fallback":"Untitled scale field"}},{"name":"consentField","label":"Consent","fields":[{"key":"key","label":"Key","type":"text","required":true,"config":{"pattern":"^[a-z_]+$","patternMessage":"Use lowercase letters and underscores, like analytics_storage."}},{"key":"text","label":"Wording","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"]}},{"key":"isRequired","label":"Must be ticked to send","type":"boolean","defaultValue":true}],"icon":"shield-check","preview":{"title":"key","fallback":"Untitled consent field"}}]},"ui":{"itemLabel":"Field"}}]},"ui":{"itemLabel":"Step","icon":"list-numbers","preview":{"title":"title","subtitle":"description","fallback":"Untitled step"},"tab":{"id":"steps"}}},{"key":"progress","label":"Progress","type":"select","defaultValue":"steps","config":{"options":[{"label":"Bar","value":"bar"},{"label":"Step names","value":"steps"},{"label":"Step 2 of 4","value":"count"}]},"ui":{"control":"segmented","tab":{"id":"settings","label":"Settings"}}},{"key":"useSaveProgress","label":"Remember answers","type":"boolean","helpText":"Keeps answers on this device for 24 hours.","defaultValue":true,"ui":{"tab":{"id":"settings"}}},{"key":"submitLabel","label":"Last button label","type":"text","required":true,"placeholder":"Send","config":{"maxLength":24},"ui":{"tab":{"id":"settings"}}},{"key":"successMessage","label":"Thank-you message","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"]},"ui":{"tab":{"id":"settings"}}}],"description":"A long form split into short steps with a progress bar","category":"Conversion & forms","icon":"list-check","preview":{"title":"heading","subtitle":"source","icon":"list-numbers"}}},
|
|
1442
1442
|
{"id":"conversion-booking-embed","name":"Booking / reservations embed","category":"Conversion & forms","kind":"block","tags":["embed","conditional","repeater","validation","media-heavy","rich-text"],"proves":"Provider select → provider-specific ids (conditional) · experiences array with party-size range and deposits · large-party handoff","why":"Booking is an EMBED with content around it. The provider select drives exactly one conditional id field (Resy venue number, OpenTable rid, Tock slug, Cal.com link — each validated in its own format) so editors never paste raw script tags. Experiences are editorial cards (photo, length, party range, price, deposit) that open the widget on a developer-locked booking type. Large parties are handed off to a private-dining page above a threshold, which is how restaurants actually avoid six-top no-shows.","htmlSignals":["scripts/iframes from widgets.resy.com, opentable.com/widget, exploretock.com, cal.com/embed, calendly.com","a 'Reserve', 'Book a table' or 'Book an appointment' heading with a date/party-size picker","cards for different seatings or services with durations and per-person prices","cancellation/deposit policy text near the widget"],"mcp":"Identify the provider from the script/iframe host and extract ONLY the id (data-venue-id / rid / slug / cal link) — never store the script. Seating/service cards → experiences (price per person and party size parsed from copy). A 'larger parties' link → largePartyFrom + largePartyButton. Policy paragraphs → policy (rich text).","pitfalls":["Storing the widget script as HTML makes it uneditable and a security risk; store ids only.","partyMin ≤ partyMax is a cross-field rule the schema can't express (gap).","Widget heights vary by provider; the renderer reserves space to avoid layout shift."],"notCarried":[],"component":{"name":"Booking","slug":"booking","props":[{"key":"heading","label":"Heading","type":"text","required":true,"recommendedMax":48,"ui":{"tab":{"id":"content","label":"Content"}}},{"key":"intro","label":"Intro","type":"longtext","recommendedMax":180,"ui":{"rows":2,"tab":{"id":"content"}}},{"key":"provider","label":"Provider","type":"select","required":true,"config":{"options":[{"label":"Resy","value":"resy"},{"label":"OpenTable","value":"opentable"},{"label":"Tock","value":"tock"},{"label":"Cal.com","value":"calcom","description":"For appointments and consultations"}]},"ui":{"tab":{"id":"provider","label":"Booking provider"}}},{"key":"resyVenueId","label":"Resy venue ID","type":"number","helpText":"The number in your Resy widget code, e.g. 58421.","required":true,"showIf":{"match":"all","rules":[{"field":"provider","op":"eq","value":"resy"}]},"ui":{"tab":{"id":"provider"}}},{"key":"openTableRid","label":"OpenTable restaurant ID","type":"number","helpText":"The rid in your OpenTable widget code.","required":true,"showIf":{"match":"all","rules":[{"field":"provider","op":"eq","value":"opentable"}]},"ui":{"tab":{"id":"provider"}}},{"key":"tockSlug","label":"Tock page","type":"text","required":true,"showIf":{"match":"all","rules":[{"field":"provider","op":"eq","value":"tock"}]},"config":{"pattern":"^[a-z0-9-]+$","patternMessage":"Use the part after exploretock.com/, like caldera-kitchen."},"ui":{"tab":{"id":"provider"}}},{"key":"calLink","label":"Cal.com link","type":"url","required":true,"showIf":{"match":"all","rules":[{"field":"provider","op":"eq","value":"calcom"}]},"config":{"pattern":"^https://cal\\.com/","patternMessage":"Use a cal.com link, like https://cal.com/caldera/demo."},"ui":{"tab":{"id":"provider"}}},{"key":"display","label":"Shows as","type":"select","defaultValue":"inline","config":{"options":[{"label":"Inline widget","value":"inline"},{"label":"Button that opens it","value":"button"}]},"ui":{"control":"segmented","tab":{"id":"provider"}}},{"key":"experiences","label":"Experiences","type":"table","config":{"maxItems":6,"fields":[{"key":"name","label":"Name","type":"text","required":true,"config":{"maxLength":40}},{"key":"description","label":"Description","type":"longtext","recommendedMax":160,"ui":{"rows":2}},{"key":"image","label":"Image","type":"image"},{"key":"duration","label":"Length","type":"number","config":{"min":15,"max":360,"step":15,"unit":"min"}},{"key":"partyMin","label":"Smallest party","type":"number","config":{"min":1,"max":20,"step":1,"unit":"guests"}},{"key":"partyMax","label":"Largest party","type":"number","config":{"min":1,"max":40,"step":1,"unit":"guests"}},{"key":"pricePerPerson","label":"Price per person","type":"number","helpText":"0 or empty for à la carte.","config":{"unit":"USD","min":0,"step":1}},{"key":"hasDeposit","label":"Takes a deposit","type":"boolean"},{"key":"bookingType","label":"Booking type ID","type":"text","helpText":"Opens the widget straight on this experience.","readOnly":"developer","lockReason":"Matches the provider's booking type","ui":{"access":{"edit":"schema.manage"}}}]},"ui":{"itemLabel":"Experience","icon":"tools-kitchen-2","preview":{"title":"name","subtitle":"duration","media":"image","fallback":"Untitled experience"},"tab":{"id":"experiences","label":"What can be booked"}}},{"key":"largePartyFrom","label":"Large parties from","type":"number","helpText":"Parties this size or bigger see the button below instead.","config":{"min":6,"max":40,"step":1,"unit":"guests"},"ui":{"tab":{"id":"content"}}},{"key":"largePartyButton","label":"Large party button","type":"button","showIf":{"match":"all","rules":[{"field":"largePartyFrom","op":"notEmpty"}]},"ui":{"tab":{"id":"content"}}},{"key":"policy","label":"Booking policy","type":"richtext","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":"phone","label":"Phone","type":"link","ui":{"tab":{"id":"content"}}}],"description":"Reservations or appointments from your booking provider","category":"Conversion & forms","icon":"calendar-time","preview":{"title":"heading","subtitle":"provider","icon":"calendar-event"}}},
|
|
@@ -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":{"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":{"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":{"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":{"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 override the wording, never the legal line or schedule","category":"Navigation & chrome","v2":{"shape":"global"},"icon":"speakerphone","preview":{"title":"message","subtitle":"tone"}}},
|
|
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 override the wording, 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"}}},
|