@bettercms-ai/mcp 0.73.2 → 0.74.0

package/dist/skills/bettercms/references/worked-examples.md

@@ -1,6 +1,6 @@
 ---
 title: "Worked examples"
-description: "Five conversions from source HTML to a production schema, a production value and a bound template: hero, feature grid, pricing with a comparison table, testimonials as a collection, FAQ with FAQPage markup."
+description: "Six conversions from source HTML to a production schema, a production value and a bound template: hero, feature grid, pricing with a comparison table, testimonials as a collection, FAQ with FAQPage markup, bento grid with per-cell sizes."
 ---
 
 # Worked examples: source HTML to schema, value and bound template
@@ -20,6 +20,7 @@ its binding attributes. Copy the shape, never the customer's words. Rules behind
 - [3. Pricing plans with a comparison table](#3-pricing-plans-with-a-comparison-table)
 - [4. Testimonials kept as a collection](#4-testimonials-kept-as-a-collection)
 - [5. FAQ accordion with FAQPage markup](#5-faq-accordion-with-faqpage-markup)
+- [9. Bento grid with per-cell sizes](#9-bento-grid-with-per-cell-sizes)
 - [Checks after any example](#checks-after-any-example)
 - Examples 6 to 8 (blog post as an entry, mega menu in the Global Layout, tabs holding columns
   of cards): [worked-examples-advanced.md](worked-examples-advanced.md)
@@ -35,6 +36,7 @@ Production stores content in four places. Pick by what the markup is, then follo
 | Records that repeat on one route | Content model and entries | `create_content_model` | `create_content_entry` | the entry's field key | 4, 6 (advanced) |
 | Header, footer, promo bar | Global Layout Section | `update_layout` | `update_layout` | `data-bcms-layout-field` | 7 (advanced) |
 | A one-off band built from blocks | `section` block with child blocks | `update_page` `blockJson` | the same call | `<blockId>__<prop>` | 8 (advanced) |
+| Cells of different kinds, each with its own size | Component with a `slot` list and `slotSettings` | `create_component` | `compose_pages` | `<instanceId>__overrides.<key>` | 9 |
 
 Rules that hold in every example:
 
@@ -728,6 +730,149 @@ Not available today: FAQPage markup that appears on its own. Without `schemaType
 page gets WebPage. An "open several at once" setting has no field type of its own; if editors
 need it, add a `boolean` field and have the template read it.
 
+## 9. Bento grid with per-cell sizes
+
+Source: the cookware brand's home page. The kit's `core-bento` entry is this shape, and
+`bento-feature-showcase` is its responsive long form ([kit-scenarios.md](kit-scenarios.md)).
+
+```html
+<section class="bento" id="field">
+  <p class="eyebrow">In the field</p>
+  <h2>Made to be handed down.</h2>
+  <div class="bento__grid grid grid-cols-4 gap-6">
+    <figure class="cell col-span-2 row-span-2 cell--dark">
+      <img src="/img/sierra-dawn-2400.jpg" alt="Dawn over a Sierra camp, kettle steaming" width="2400" height="2400">
+      <figcaption>Three nights in the Sierra</figcaption>
+    </figure>
+    <div class="cell cell--brand"><i class="ti ti-flame" aria-hidden="true"></i>
+      <span class="stat__value">120k+</span><span class="stat__label">Fires cooked over</span></div>
+    <div class="cell"><i class="ti ti-star" aria-hidden="true"></i>
+      <span class="stat__value">4.9</span><span class="stat__label">Average review</span></div>
+    <blockquote class="cell col-span-2"><p>Our restaurant runs four Ember ovens over live fire every night.</p>
+      <cite>Chef Amara Osei, Hearth &amp; Ash, Portland</cite></blockquote>
+  </div>
+</section>
+```
+
+Reasoning:
+
+1. The grid's children differ in shape (an image, two stats, a quote) and in size. Different
+   shapes chosen by the editor are slot children, not rows of one list.
+2. Each cell's size and surface belong to its place in this grid, not to the cell. Reading
+   `col-span-2 row-span-2` and `cell--dark` into the image tile's own props would carry a
+   meaningless span to every other page that reuses the tile. They go in the slot's settings.
+3. Size is a small set of presets (1 × 1, 2 × 1, 1 × 2, 2 × 2), so it is a select, never a free
+   column number. If the source's spans do not fit four presets, it is the per-cell grid
+   (`grid-cell-layout`), not a bento.
+4. The four-column versus three-column layout is a variant: a second component sharing the
+   `sectionType`, with the same prop keys.
+5. The icons and the gap between cells are design: they stay in the template's classes.
+
+Schema: one component per tile kind (`create_component`, then `publish_component`). The stat tile:
+
+```json
+{
+  "name": "Stat tile",
+  "slug": "stat-tile",
+  "category": "content",
+  "description": "A big number with a short label.",
+  "blockJson": [
+    { "type": "section", "id": "stat-root", "props": { "children": [
+      { "type": "text", "id": "stat-value", "props": { "html": "" } },
+      { "type": "text", "id": "stat-label", "props": { "html": "" } }
+    ] } }
+  ],
+  "props": [
+    { "key": "value", "label": "Number", "type": "text", "target": { "blockId": "stat-value", "path": "props.html" } },
+    { "key": "label", "label": "Label", "type": "text", "target": { "blockId": "stat-label", "path": "props.html" } }
+  ]
+}
+```
+
+The image tile (`image`, `caption`) and the quote tile (`quote`, `author`, `role`) are built the
+same way. Then the grid, whose `cells` slot lists them:
+
+```json
+{
+  "name": "Bento grid",
+  "slug": "bento-grid",
+  "sectionType": "bento",
+  "category": "section",
+  "description": "A mosaic of image, stat and quote cells, each with its own size and surface.",
+  "blockJson": [
+    { "type": "section", "id": "bento-root", "props": { "children": [
+      { "type": "text", "id": "bento-eyebrow", "props": { "html": "" } },
+      { "type": "heading", "id": "bento-title", "props": { "text": "", "level": 2 } },
+      { "type": "section", "id": "bento-cells", "props": { "children": [] } }
+    ] } }
+  ],
+  "props": [
+    { "key": "eyebrow", "label": "Eyebrow", "type": "text", "target": { "blockId": "bento-eyebrow", "path": "props.html" } },
+    { "key": "heading", "label": "Heading", "type": "text", "target": { "blockId": "bento-title", "path": "props.text" } },
+    { "key": "cells", "label": "Cells", "type": "slot",
+      "target": { "blockId": "bento-cells", "path": "props.children" },
+      "config": {
+        "multiple": true, "minItems": 3, "maxItems": 9,
+        "componentIds": ["<image tile id>", "<stat tile id>", "<quote tile id>"],
+        "slotSettings": [
+          { "key": "span", "label": "Size", "type": "select", "defaultValue": "1x1",
+            "options": [
+              { "value": "1x1", "label": "Small" }, { "value": "2x1", "label": "Wide" },
+              { "value": "1x2", "label": "Tall" }, { "value": "2x2", "label": "Large" } ] },
+          { "key": "tone", "label": "Surface", "type": "select", "defaultValue": "light",
+            "options": [
+              { "value": "light", "label": "Light" }, { "value": "dark", "label": "Dark" },
+              { "value": "brand", "label": "Brand" } ] }
+        ] } }
+  ]
+}
+```
+
+Value: the instance, inside the page's whole `blockJson` (`update_page` with `ifMatch`, or
+`compose_pages`). Each cell names its tile component in `_type`, holds that tile's props at its
+root, and its place in the grid in `_settings`:
+
+```json
+{ "type": "component", "id": "home-bento", "props": { "componentId": "<bento grid id>", "overrides": {
+  "eyebrow": "In the field",
+  "heading": "Made to be handed down.",
+  "cells": [
+    { "_key": "g1", "_type": "<image tile id>", "_settings": { "span": "2x2", "tone": "dark" },
+      "image": "/img/sierra-dawn-2400.jpg", "caption": "Three nights in the Sierra" },
+    { "_key": "g2", "_type": "<stat tile id>", "_settings": { "span": "1x1", "tone": "brand" },
+      "value": "120k+", "label": "Fires cooked over" },
+    { "_key": "g3", "_type": "<stat tile id>", "_settings": { "span": "1x1", "tone": "light" },
+      "value": "4.9", "label": "Average review" },
+    { "_key": "g4", "_type": "<quote tile id>", "_settings": { "span": "2x1", "tone": "light" },
+      "quote": "Our restaurant runs four Ember ovens over live fire every night.",
+      "author": "Chef Amara Osei", "role": "Hearth & Ash, Portland" }
+  ] } } }
+```
+
+Bound template: render the blocks with `BcmsBlocks`. Each cell arrives as a `component` block
+whose `props.slotSettings` holds its `_settings`; the template turns `span` and `tone` into its own
+grid and surface classes.
+
+```html
+<section data-bcms-block="home-bento">
+  <p data-bcms-field="home-bento__overrides.eyebrow" data-bcms-kind="text">In the field</p>
+  <h2 data-bcms-field="home-bento__overrides.heading" data-bcms-kind="text">Made to be handed down.</h2>
+  <div class="bento__grid grid grid-cols-4 gap-6">
+    <figure class="cell col-span-2 row-span-2 cell--dark">…</figure>
+  </div>
+</section>
+```
+
+- A `_settings` value that does not fit the slot's `slotSettings` is refused, naming the cell's
+  `_key`; a slot with no `slotSettings` takes no `_settings` at all.
+- `_key` is the cell's identity: keep it stable across reorders.
+- Publish every tile component before the grid: a draft child renders nothing.
+- A cell's copy is edited in the placement's `cells` list, not by clicking it on the canvas
+  ([components.md](components.md) §1).
+
+Not available today: spans that depend on the variant's column count (validate them yourself),
+per-breakpoint spans, and a phone order per cell.
+
 ## Checks after any example
 
 1. Read back what you wrote: `get_page`, `get_component` or `get_layout`. A richtext value comes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/mcp",
-  "version": "0.73.2",
+  "version": "0.74.0",
   "type": "module",
   "description": "BetterCMS MCP server — schema, content, forms + components authoring tools over the Management API, authed via OAuth device-code.",
   "bin": {