@getvitops/emdash 2.0.0-alpha.0 → 2.0.0-alpha.2

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { definePlugin, getMenus, pluginResponse } from "emdash";
+import { definePlugin, getMenus, getWidgetAreas, pluginResponse } from "emdash";
 import { iconMap } from "@getvitops/utils";
 import { designSystemPath, formatConfig, getAt, isConfig, mergePatch, resolveInput, setAt } from "@getvitops/generator/config";
 import { buildReverseIndex, patchToOverrideCss, validateColorContract } from "@getvitops/generator/tokens";
@@ -35,7 +35,10 @@ const SEMANTIC_ICON_OPTIONS = Object.keys(iconMap.fa7).sort().map((name) => ({
 *   fallbacks, then `neutral`.
 * - **`color`** — the escape hatch: a palette hue (`amber`) or hue and step (`amber-300`).
 *   Wins over `tone` when set. Contrast is NOT checked for it — the generator's contrast
-*   contract covers roles, not arbitrary hue/step pairs — so it is for decoration.
+*   contract covers roles, not arbitrary hue/step pairs — so it is for decoration. A solid fill
+*   reads from the site's `--color-<hue>-<step>-on` and the tint flips with the colour scheme
+*   (`light-dark()`); mid steps (300–500) cannot reach APCA Lc 75 with either text colour, so use
+*   a role where contrast matters.
 *
 * **Why CSS custom properties, not classes.** A class name built from a field value
 * (`bg-${tone}`) is invisible to Tailwind's scanner, so it generates nothing in that
@@ -102,14 +105,16 @@ function resolveTone(tone, color) {
 	if (hue) {
 		const [, name, step] = hue;
 		const at = (s) => `var(--color-${name}-${s})`;
+		const fill = step ?? "600";
+		const flip = (light, dark) => `light-dark(${at(light)}, ${at(dark)})`;
 		return {
 			className: "tone",
 			style: [
-				`--tone-bg: ${at("100")}`,
-				`--tone-fg: ${at("900")}`,
-				`--tone-border: ${at("300")}`,
-				`--tone-solid: ${at(step ?? "600")}`,
-				`--tone-on-solid: #fff`
+				`--tone-bg: ${flip("100", "900")}`,
+				`--tone-fg: ${flip("900", "100")}`,
+				`--tone-border: ${flip("300", "700")}`,
+				`--tone-solid: ${at(fill)}`,
+				`--tone-on-solid: ${at(`${fill}-on`)}`
 			].join("; ")
 		};
 	}
@@ -131,10 +136,138 @@ function resolveTone(tone, color) {
 	};
 }
 
+// src/block-types.ts
+/** Block-type slugs may not contain a dot, so `vitops_section` is stored as `vitops_section`. */
+const SECTION_SLUG = "vitops_section";
+const select = (slug, label, options, defaultValue) => ({
+	slug,
+	label,
+	type: "select",
+	defaultValue,
+	validation: { options }
+});
+/**
+* The `theme` select's values: `none`, a role, or `<role>:solid`. Block-type selects are
+* static, so this lists the roles every site defines; any other site role still works through
+* the `tone` field. `<role>:solid` is the filled backdrop with the contrast-computed text.
+*/
+const THEME_ROLES = [
+	"neutral",
+	"surface",
+	"brand-primary",
+	"brand-secondary",
+	"info",
+	"success",
+	"warning",
+	"danger"
+];
+const THEMES = [
+	"none",
+	...THEME_ROLES,
+	...THEME_ROLES.map((r) => `${r}:solid`)
+];
+const SECTION_FIELDS = [
+	{
+		slug: "kicker",
+		label: "Kicker (small line above the heading)",
+		type: "string"
+	},
+	{
+		slug: "heading",
+		label: "Heading",
+		type: "string"
+	},
+	select("level", "Heading level (p: styled like a heading, not in the outline)", [
+		"1",
+		"2",
+		"3",
+		"4",
+		"5",
+		"6",
+		"p"
+	], "2"),
+	{
+		slug: "sub",
+		label: "Lead-in text under the heading",
+		type: "text"
+	},
+	{
+		slug: "body",
+		label: "Content (any blocks)",
+		type: "portableText"
+	},
+	select("layout", "Layout", [
+		"stack",
+		"center",
+		"split"
+	], "stack"),
+	select("width", "Width", [
+		"measure",
+		"breakout",
+		"spotlight",
+		"fullbleed"
+	], "measure"),
+	{
+		slug: "tone",
+		label: "Backdrop tone (a colour role from the site, e.g. surface or brand-primary)",
+		type: "string"
+	},
+	{
+		slug: "color",
+		label: "Palette colour instead of a tone (e.g. amber or amber-300)",
+		type: "string"
+	},
+	{
+		slug: "solid",
+		label: "Fill with the solid colour",
+		type: "boolean",
+		defaultValue: false
+	},
+	select("theme", "Theme (backdrop and readable text in one pick; overrides the tone fields)", THEMES, "none"),
+	{
+		slug: "anchor",
+		label: "Anchor id (so a link can point here with #id)",
+		type: "string"
+	},
+	{
+		slug: "class_name",
+		label: "Extra CSS classes",
+		type: "string"
+	},
+	{
+		slug: "style",
+		label: "CSS custom properties, e.g. --p-card: 2rem",
+		type: "string"
+	}
+];
+/** `vitops_section`: kicker, heading, lead-in, tone/backdrop, optional heading-left layout, and a body of blocks. */
+const SECTION_BLOCK_TYPE = {
+	slug: SECTION_SLUG,
+	label: "Section",
+	description: "A titled page section whose body can hold any other blocks.",
+	category: "Sections",
+	icon: "layout",
+	currentVersion: 1,
+	versions: [{
+		version: 1,
+		fields: SECTION_FIELDS
+	}]
+};
+/**
+* Every block type this plugin ships, in the shape `seed.json`'s `blockTypes` takes. Spread
+* it into the seed (and allow the slugs on the collection's `blocks` field), e.g.
+* `blockTypes: [...vitopsBlockTypes()]`.
+*/
+function vitopsBlockTypes() {
+	return [SECTION_BLOCK_TYPE];
+}
+
 // src/blocks.ts
 /** Route that fills every tone select with the site's own roles — see `index.ts`. */
 const TONES_ROUTE = "tones/list";
-/** Route that lists the site's EmDash menus for `vitops.nav`'s `menu` select — see `menus-route.ts`. */
+/** Lists each colour role twice: tinted (`role`) and filled (`role:solid`), for every block's `theme`. */
+const THEMES_ROUTE = "themes/list";
+/** Route that lists the site's EmDash menus for `vitops_nav`'s `menu` select — see `menus-route.ts`. */
 const MENUS_ROUTE = "menus/list";
 /**
 * The tone options an editor can always pick, before the site adds its own roles.
@@ -167,6 +300,48 @@ function toneFields() {
 		label: "Palette colour instead of a tone (e.g. amber or amber-300)"
 	}];
 }
+/** Route that lists the site's widget areas for `vitops_widgetArea`'s `area` select. */
+const WIDGET_AREAS_ROUTE = "widget-areas/list";
+/**
+* The escape hatches every block carries, appended last by `BLOCKS` (see `astro/blocks/attrs.ts`
+* for how each is validated and why `style` takes custom properties only).
+*/
+function commonFields() {
+	return [
+		{
+			type: "select",
+			action_id: "theme",
+			label: "Theme (a backdrop with readable text, from the site colours)",
+			initial_value: "",
+			options: [{
+				label: "None",
+				value: ""
+			}, ...THEME_ROLES.flatMap((r) => [{
+				label: r.replace(/-/g, " "),
+				value: r
+			}, {
+				label: `${r.replace(/-/g, " ")} (filled)`,
+				value: `${r}:solid`
+			}])],
+			optionsRoute: THEMES_ROUTE
+		},
+		{
+			type: "text_input",
+			action_id: "anchor",
+			label: "Anchor id (so a link can point here with #id)"
+		},
+		{
+			type: "text_input",
+			action_id: "className",
+			label: "Extra CSS classes (with the tailwind format, only classes the site already uses)"
+		},
+		{
+			type: "text_input",
+			action_id: "style",
+			label: "CSS custom properties, e.g. --p-card: 2rem; --tone-bg: #fee"
+		}
+	];
+}
 /** Heading level for a block's own heading; `h1` is reserved for the page title. */
 const levelField = (initial) => ({
 	type: "select",
@@ -184,7 +359,31 @@ const levelField = (initial) => ({
 		value: n
 	}))
 });
-const BLOCKS = [
+/**
+* Heading level for a block that can own the page title (hero): `h1`, or `p` for a heading that is
+* visual only and should not appear in the outline.
+*/
+const titleLevelField = (initial) => ({
+	type: "select",
+	action_id: "level",
+	label: "Heading level (h1 is the page title; p is styled like a heading but not in the outline)",
+	initial_value: initial,
+	options: [...[
+		"1",
+		"2",
+		"3",
+		"4",
+		"5",
+		"6"
+	].map((n) => ({
+		label: `h${n}`,
+		value: n
+	})), {
+		label: "p (not a heading)",
+		value: "p"
+	}]
+});
+const BASE_BLOCKS = [
 	{
 		/**
 		* A link or button, optionally with an icon at either end.
@@ -199,7 +398,7 @@ const BLOCKS = [
 		* raw HTML), so `<wc-icon-picker>` cannot be mounted inside a block modal
 		* however much nicer it would be. Revisit if EmDash opens that union.
 		*/
-		type: "vitops.actionLink",
+		type: "vitops_actionLink",
 		label: "Link or button",
 		icon: "link",
 		placeholder: "A link or button, with optional icons",
@@ -285,7 +484,7 @@ const BLOCKS = [
 		]
 	},
 	{
-		type: "vitops.imageCompare",
+		type: "vitops_imageCompare",
 		label: "Image compare",
 		placeholder: "Before/after image slider",
 		fields: [
@@ -324,7 +523,7 @@ const BLOCKS = [
 		]
 	},
 	{
-		type: "vitops.copyButton",
+		type: "vitops_copyButton",
 		label: "Copy snippet",
 		icon: "code",
 		placeholder: "Text with a copy-to-clipboard button",
@@ -357,7 +556,7 @@ const BLOCKS = [
 		]
 	},
 	{
-		type: "vitops.banner",
+		type: "vitops_banner",
 		label: "Banner",
 		placeholder: "Announcement or notice",
 		fields: [
@@ -400,7 +599,7 @@ const BLOCKS = [
 		]
 	},
 	{
-		type: "vitops.details",
+		type: "vitops_details",
 		label: "Disclosure",
 		placeholder: "Collapsible details/summary",
 		fields: [
@@ -424,7 +623,7 @@ const BLOCKS = [
 		]
 	},
 	{
-		type: "vitops.carousel",
+		type: "vitops_carousel",
 		label: "Carousel",
 		placeholder: "Image carousel",
 		category: "Media",
@@ -484,7 +683,7 @@ const BLOCKS = [
 		]
 	},
 	{
-		type: "vitops.gallery",
+		type: "vitops_gallery",
 		label: "Gallery",
 		placeholder: "Thumbnail grid that opens a lightbox carousel",
 		category: "Media",
@@ -534,7 +733,7 @@ const BLOCKS = [
 		]
 	},
 	{
-		type: "vitops.cards",
+		type: "vitops_cards",
 		label: "Cards",
 		placeholder: "A grid of cards",
 		category: "Sections",
@@ -638,7 +837,7 @@ const BLOCKS = [
 		]
 	},
 	{
-		type: "vitops.accordion",
+		type: "vitops_accordion",
 		label: "Accordion",
 		placeholder: "A group of collapsible sections",
 		category: "Sections",
@@ -675,7 +874,7 @@ const BLOCKS = [
 		}]
 	},
 	{
-		type: "vitops.hero",
+		type: "vitops_hero",
 		label: "Hero",
 		placeholder: "Page opener: heading, text, buttons and an optional image",
 		category: "Sections",
@@ -690,7 +889,7 @@ const BLOCKS = [
 				action_id: "heading",
 				label: "Heading (wrap words in *stars* to accent them)"
 			},
-			levelField("2"),
+			titleLevelField("1"),
 			{
 				type: "text_input",
 				action_id: "body",
@@ -774,7 +973,7 @@ const BLOCKS = [
 		]
 	},
 	{
-		type: "vitops.marquee",
+		type: "vitops_marquee",
 		label: "Marquee",
 		placeholder: "A continuously scrolling row (logos, quotes, badges)",
 		category: "Media",
@@ -818,7 +1017,7 @@ const BLOCKS = [
 		]
 	},
 	{
-		type: "vitops.logos",
+		type: "vitops_logos",
 		label: "Logos",
 		placeholder: "A still row of partner or client logos",
 		category: "Media",
@@ -839,12 +1038,12 @@ const BLOCKS = [
 					{
 						type: "text_input",
 						action_id: "image",
-						label: "Image URL"
+						label: "Image URL (leave empty to show the name as text)"
 					},
 					{
 						type: "text_input",
 						action_id: "alt",
-						label: "Name (alt text)"
+						label: "Name (alt text, or the text shown with no image)"
 					},
 					{
 						type: "text_input",
@@ -882,7 +1081,7 @@ const BLOCKS = [
 		]
 	},
 	{
-		type: "vitops.steps",
+		type: "vitops_steps",
 		label: "Steps",
 		placeholder: "A numbered sequence joined by a connector line",
 		category: "Sections",
@@ -922,7 +1121,7 @@ const BLOCKS = [
 		]
 	},
 	{
-		type: "vitops.stats",
+		type: "vitops_stats",
 		label: "Stats",
 		placeholder: "Headline figures that count up, or labelled tiles",
 		category: "Sections",
@@ -999,7 +1198,7 @@ const BLOCKS = [
 		]
 	},
 	{
-		type: "vitops.callout",
+		type: "vitops_callout",
 		label: "Callout",
 		placeholder: "A call-to-action band (not a dismissible banner)",
 		category: "Sections",
@@ -1059,7 +1258,7 @@ const BLOCKS = [
 		]
 	},
 	{
-		type: "vitops.entries",
+		type: "vitops_entries",
 		label: "Entries table",
 		placeholder: "Rows of term/value pairs: a stacked list that becomes a table when wide",
 		category: "Sections",
@@ -1091,7 +1290,7 @@ const BLOCKS = [
 		]
 	},
 	{
-		type: "vitops.pricing",
+		type: "vitops_pricing",
 		label: "Pricing",
 		placeholder: "Plan cards with aligned feature rows",
 		category: "Sections",
@@ -1143,7 +1342,7 @@ const BLOCKS = [
 		}, levelField("3")]
 	},
 	{
-		type: "vitops.embed",
+		type: "vitops_embed",
 		label: "Embed (video or map)",
 		placeholder: "A video or map that loads only after the visitor allows it",
 		category: "Embeds",
@@ -1211,7 +1410,7 @@ const BLOCKS = [
 		]
 	},
 	{
-		type: "vitops.form",
+		type: "vitops_form",
 		label: "Contact form",
 		placeholder: "An enquiry form that emails you (and your CRM) and works without JavaScript",
 		category: "Forms",
@@ -1274,6 +1473,10 @@ const BLOCKS = [
 							{
 								label: "Tick box",
 								value: "checkbox"
+							},
+							{
+								label: "Tick any number",
+								value: "checkboxes"
 							}
 						]
 					},
@@ -1296,7 +1499,7 @@ const BLOCKS = [
 					{
 						type: "text_input",
 						action_id: "options",
-						label: "Choices (one per line; for \"Choose one\" only)",
+						label: "Choices (one per line; for \"Choose one\" and \"Tick any number\")",
 						multiline: true
 					}
 				]
@@ -1341,7 +1544,7 @@ const BLOCKS = [
 		* an editor saves. Which reviews show is `selectReviews()` from `@getvitops/utils`, the
 		* one place that is decided — these fields are exactly its `ReviewLocationConfig`.
 		*/
-		type: "vitops.reviews",
+		type: "vitops_reviews",
 		label: "Google reviews",
 		icon: "star",
 		placeholder: "Customer reviews from the Google Business Profile cache",
@@ -1452,7 +1655,7 @@ const BLOCKS = [
 		* The menu is chosen from `menus/list` (the site's own menus) with the conventional names as
 		* the static fallback, because a select needs a non-empty `options` list.
 		*/
-		type: "vitops.nav",
+		type: "vitops_nav",
 		label: "Menu",
 		icon: "list",
 		placeholder: "An EmDash menu as a list of links",
@@ -1530,8 +1733,147 @@ const BLOCKS = [
 			},
 			...toneFields()
 		]
+	},
+	{
+		/** A row of static labels (`badge`) or editable/dismissable ones (`tag`). */
+		type: "vitops_badges",
+		label: "Badges",
+		icon: "tag",
+		placeholder: "A row of short labels",
+		fields: [
+			{
+				type: "repeater",
+				action_id: "items",
+				label: "Labels",
+				fields: [
+					{
+						type: "text_input",
+						action_id: "label",
+						label: "Label"
+					},
+					{
+						type: "select",
+						action_id: "tone",
+						label: "Tone (blank uses the block tone)",
+						initial_value: "",
+						options: STATIC_TONE_OPTIONS,
+						optionsRoute: TONES_ROUTE
+					},
+					{
+						type: "text_input",
+						action_id: "color",
+						label: "Palette colour instead (e.g. amber)"
+					},
+					{
+						type: "combobox",
+						action_id: "icon",
+						label: "Icon before the label",
+						placeholder: "None",
+						options: SEMANTIC_ICON_OPTIONS
+					},
+					{
+						type: "text_input",
+						action_id: "href",
+						label: "Link URL (optional)"
+					}
+				]
+			},
+			{
+				type: "select",
+				action_id: "variant",
+				label: "Style",
+				initial_value: "badge",
+				options: [{
+					label: "Badge (static label)",
+					value: "badge"
+				}, {
+					label: "Tag",
+					value: "tag"
+				}]
+			},
+			...toneFields()
+		]
+	},
+	{
+		/**
+		* A widget area: content defined once under Widgets in the admin and shown wherever this
+		* block is placed. Edits reach every page it sits on (after the next build, on a
+		* prerendered site) — unlike a Section, which is copied.
+		*/
+		type: "vitops_widgetArea",
+		label: "Widget area",
+		icon: "layout",
+		placeholder: "Shared content managed under Widgets",
+		fields: [{
+			type: "select",
+			action_id: "area",
+			label: "Widget area",
+			initial_value: "",
+			options: [{
+				label: "Choose…",
+				value: ""
+			}],
+			optionsRoute: WIDGET_AREAS_ROUTE
+		}, levelField("3")]
 	}
 ];
+/** Every block gets the escape hatches last, so the editor reads content first. */
+/**
+* Repeaters whose rows can carry their own colour. A row's `tone` / `color` win over the block's,
+* and blank falls back to it, so one block can hold a pine card and an amber one without
+* becoming two blocks. (If you want a single colour for the lot, set it on the block.)
+*/
+const ROW_TONE = {
+	vitops_cards: "cards",
+	vitops_stats: "stats",
+	vitops_steps: "steps",
+	vitops_hero: "cards"
+};
+/** Extra row fields for one repeater, beyond the shared tone pair. */
+const ROW_EXTRA = { vitops_hero: { cards: [
+	{
+		type: "text_input",
+		action_id: "eyebrow",
+		label: "Eyebrow (small line above the title)"
+	},
+	{
+		type: "text_input",
+		action_id: "ctaLabel",
+		label: "Button text"
+	},
+	{
+		type: "text_input",
+		action_id: "ctaHref",
+		label: "Button URL"
+	}
+] } };
+const rowToneFields = () => [{
+	type: "select",
+	action_id: "tone",
+	label: "Tone for this item (blank uses the block tone)",
+	initial_value: "",
+	options: STATIC_TONE_OPTIONS,
+	optionsRoute: TONES_ROUTE
+}, {
+	type: "text_input",
+	action_id: "color",
+	label: "Palette colour instead (e.g. amber)"
+}];
+function withRowFields(block) {
+	const repeater = ROW_TONE[block.type];
+	return (block.fields ?? []).map((f) => f.type === "repeater" && f.action_id === repeater ? {
+		...f,
+		fields: [
+			...f.fields,
+			...ROW_EXTRA[block.type]?.[repeater] ?? [],
+			...rowToneFields()
+		]
+	} : f);
+}
+const BLOCKS = BASE_BLOCKS.map((b) => ({
+	...b,
+	fields: [...withRowFields(b), ...commonFields()]
+}));
 /**
 * Resolve {@link BlockSelection} against {@link BLOCKS}.
 *
@@ -1626,6 +1968,27 @@ function createTonesRoute(roles) {
 		handler: async () => ({ items: toneItems(roles()) })
 	};
 }
+/** The `theme` select's items: `None`, then each role tinted and filled (`role`, `role:solid`). */
+function themeItems(roles) {
+	const names = [.../* @__PURE__ */ new Set([...roles, ...SEMANTIC_TONES])];
+	const label = (id) => id.replace(/-/g, " ");
+	return [{
+		id: "",
+		name: "None"
+	}, ...names.flatMap((id) => [{
+		id,
+		name: label(id)
+	}, {
+		id: `${id}:solid`,
+		name: `${label(id)} (filled)`
+	}])];
+}
+function createThemesRoute(roles) {
+	return {
+		permission: "content:read",
+		handler: async () => ({ items: themeItems(roles()) })
+	};
+}
 
 // src/design-system-route.ts
 /**
@@ -1768,94 +2131,6 @@ async function designSystemOverrideFragment(ctx, opts) {
 	};
 }
 
-// src/block-types.ts
-/** Block-type slugs may not contain a dot, so `vitops.section` is stored as `vitops_section`. */
-const SECTION_SLUG = "vitops_section";
-const select = (slug, label, options, defaultValue) => ({
-	slug,
-	label,
-	type: "select",
-	defaultValue,
-	validation: { options }
-});
-const SECTION_FIELDS = [
-	{
-		slug: "kicker",
-		label: "Kicker (small line above the heading)",
-		type: "string"
-	},
-	{
-		slug: "heading",
-		label: "Heading",
-		type: "string"
-	},
-	select("level", "Heading level", [
-		"2",
-		"3",
-		"4",
-		"5",
-		"6"
-	], "2"),
-	{
-		slug: "sub",
-		label: "Lead-in text under the heading",
-		type: "text"
-	},
-	{
-		slug: "body",
-		label: "Content (any blocks)",
-		type: "portableText"
-	},
-	select("layout", "Layout", [
-		"stack",
-		"center",
-		"split"
-	], "stack"),
-	select("width", "Width", [
-		"measure",
-		"breakout",
-		"spotlight",
-		"fullbleed"
-	], "measure"),
-	{
-		slug: "tone",
-		label: "Backdrop tone (a colour role from the site, e.g. surface or brand-primary)",
-		type: "string"
-	},
-	{
-		slug: "color",
-		label: "Palette colour instead of a tone (e.g. amber or amber-300)",
-		type: "string"
-	},
-	{
-		slug: "solid",
-		label: "Fill with the solid colour",
-		type: "boolean",
-		defaultValue: false
-	}
-];
-/** `vitops.section`: kicker, heading, lead-in, tone/backdrop, optional heading-left layout, and a body of blocks. */
-const SECTION_BLOCK_TYPE = {
-	slug: SECTION_SLUG,
-	label: "Section",
-	description: "A titled page section whose body can hold any other blocks.",
-	category: "Sections",
-	icon: "layout",
-	currentVersion: 1,
-	versions: [{
-		version: 1,
-		fields: SECTION_FIELDS
-	}]
-};
-/**
-* Every block type this plugin ships, in the shape `seed.json`'s `blockTypes` takes. Spread
-* it into the seed (and allow the slugs on the collection's `blocks` field), e.g.
-* `blockTypes: [...vitopsBlockTypes()]`.
-*/
-function vitopsBlockTypes() {
-	return [SECTION_BLOCK_TYPE];
-}
-
 // src/blocks-doc.ts
 const cell = (s) => (s ?? "").replace(/\|/g, "\\|").replace(/\n/g, " ");
 function describe(f) {
@@ -1889,7 +2164,7 @@ function renderBlocksDoc(blocks = BLOCKS) {
 		"",
 		"# EmDash blocks",
 		"",
-		"Each block is a Portable Text object: `{ \"_type\": \"vitops.cards\", \"_key\": \"<unique>\", ...fields }`.",
+		"Each block is a Portable Text object: `{ \"_type\": \"vitops_cards\", \"_key\": \"<unique>\", ...fields }`.",
 		"Portable Text blocks are flat — they cannot contain other blocks, and a repeater row holds scalar fields only.",
 		"To put blocks inside something, use the section block TYPE (end of this page), whose body is Portable Text.",
 		"Give every block a unique `_key`; gallery and carousel derive their element id from it.",
@@ -1899,9 +2174,27 @@ function renderBlocksDoc(blocks = BLOCKS) {
 		"Every block that colours something takes the same two fields. `tone` is a colour role from the",
 		"site's `colors.roles` (or a semantic name); an unknown role falls back through its semantic",
 		"relatives to `neutral`. `color` is an escape hatch naming a palette hue (`amber`) or hue and step",
-		"(`amber-300`) and wins over `tone`; its contrast is not checked. Renderers emit `--tone-*` custom",
-		"properties, never a class built from the value. Multiline fields that accept links take",
+		"(`amber-300`) and wins over `tone`; text on a hue solid is the site's `--color-<hue>-<step>-on`,",
+		"but contrast is only guaranteed for roles. Renderers emit `--tone-*` custom properties, never a",
+		"class built from the value. Rows of `hero.cards`, `cards`, `stats` and `steps` (and `badges.items`)",
+		"take their own `tone`/`color`; blank inherits the block's, and a row's colour never reaches its",
+		"siblings, so mixed colours need no extra block. Multiline fields that accept links take",
 		"`[text](/url)`; hero headings accent words wrapped in `*stars*`.",
+		"",
+		"## Theme",
+		"",
+		"Every block carries `theme`: a colour role, tinted (`surface`) or filled (`brand-primary:solid`), applied to",
+		"the block's own root with the role's computed readable text. It wins over the block's `tone`.",
+		"",
+		"## Type size",
+		"",
+		"Titles use the type roles (`font-heading`, `font-display`, `font-eyebrow`). Every role reads its size",
+		"from a custom property, `--<role>-fs` (`--heading-fs`, `--display-fs`), falling back to the role's",
+		"configured size, so one block can resize its titles through its `style` field",
+		"(`--heading-fs: 1.125rem`) with no site CSS; set it on an ancestor to resize a region. It is inherited,",
+		"so it reaches every use of that role inside the block. `style` accepts custom properties only.",
+		"Steps, stats and cards also have per-part hooks: `--steps-title-size` (default one step below the",
+		"heading role), `--stats-figure-size` and `--card-title-size`.",
 		""
 	];
 	for (const b of blocks) {
@@ -1909,7 +2202,7 @@ function renderBlocksDoc(blocks = BLOCKS) {
 		if (b.placeholder) out.push(`${b.placeholder}.`, "");
 		if (b.fields?.length) out.push("| Field | Type | Label | Notes |", "| --- | --- | --- | --- |", ...fieldRows(b.fields), "");
 	}
-	out.push("## `vitops.form` needs an endpoint", "", "The form posts to `/api/track` (the `action` field overrides it), which must be an on-demand route", "built with `createConversionRoute()` from `@getvitops/astro/routes`; the emdash template ships one.", "Field names are submitted as written, except that `phone` becomes `tel` and a few names the route", "reserves (`event`, `website`, `honeypot`, `_honeypot`, `cf-turnstile-response`) are renamed.", "It emails `site.notifications.email` and writes `site.crm` when set; with neither, the route refuses", "the post rather than accept a message nobody receives. Add the spam check with", "`vitops setup turnstile`: once `site.security.turnstile.siteKey` is set the block renders", "`<wc-turnstile>`, which loads Cloudflare Turnstile only when the visitor first uses the form", "(category `necessary`, so it is not behind the consent banner). The secret lives in the", "`VITOPS_TURNSTILE_SECRET` Worker secret, never in `site.json`. Use one form per page.", "", "## Block types (the `blocks` field)", "", "Schema-level block types, not Portable Text blocks: add them to the seed (`blockTypes: [...vitopsBlockTypes()]`),", "allow the slug on the collection's `blocks` field, and render with `blockTypeComponents` from `@getvitops/emdash/astro`.", "");
+	out.push("## `vitops_form` needs an endpoint", "", "The form posts to `/api/track` (the `action` field overrides it), which must be an on-demand route", "built with `createConversionRoute()` from `@getvitops/astro/routes`; the emdash template ships one.", "Field names are submitted as written, except that `phone` becomes `tel` and a few names the route", "reserves (`event`, `website`, `honeypot`, `_honeypot`, `cf-turnstile-response`) are renamed.", "It emails `site.notifications.email` and writes `site.crm` when set; with neither, the route refuses", "the post rather than accept a message nobody receives. Add the spam check with", "`vitops setup turnstile`: once `site.security.turnstile.siteKey` is set the block renders", "`<wc-turnstile>`, which loads Cloudflare Turnstile only when the visitor first uses the form", "(category `necessary`, so it is not behind the consent banner). The secret lives in the", "`VITOPS_TURNSTILE_SECRET` Worker secret, never in `site.json`. Use one form per page.", "`vitops emdash check-prerender` warns (fails under `--strict`) when a built page has a form", "posting to `/api/track` and `site.json` configures nowhere to deliver it, or lists none of its fields", "under `site.templates`.", "", "A `checkboxes` field (\"tick any number\") posts one entry per ticked box under the same name; the route", "joins them with `\", \"`. HTML cannot require \"at least one\", so `required` is not applied to the group.", "", "The generated privacy policy reads `site.templates` form entries, not this block. Convert the saved", "block with `formTemplateFromBlock(block)` from `@getvitops/emdash` and paste the result under", "`site.templates` in `site.json`, so the policy lists what the form collects.", "", "## Block types (the `blocks` field)", "", "Schema-level block types, not Portable Text blocks: add them to the seed (`blockTypes: [...vitopsBlockTypes()]`),", "allow the slug on the collection's `blocks` field, and render with `blockTypeComponents` from `@getvitops/emdash/astro`.", "");
 	for (const t of vitopsBlockTypes()) {
 		out.push(`### \`${t.slug}\` — ${t.label}`, "", `${t.description ?? ""}`, "");
 		const fields = t.versions.find((v) => v.version === t.currentVersion)?.fields ?? [];
@@ -1917,7 +2210,7 @@ function renderBlocksDoc(blocks = BLOCKS) {
 			const notes = [
 				f.validation?.options ? `one of ${f.validation.options.join(", ")}` : "",
 				f.defaultValue !== void 0 ? `default \`${String(f.defaultValue)}\`` : "",
-				f.type === "portableText" ? "accepts every `vitops.*` block above" : ""
+				f.type === "portableText" ? "accepts every `vitops_*` block above" : ""
 			].filter(Boolean);
 			return `| \`${f.slug}\` | ${f.type} | ${cell(f.label)} | ${cell(notes.join("; "))} |`;
 		}), "");
@@ -1925,6 +2218,160 @@ function renderBlocksDoc(blocks = BLOCKS) {
 	return out.join("\n");
 }
 
+// src/astro/blocks/form.ts
+/**
+* Pure decisions for the `vitops_form` block: which of an editor's field rows become real
+* controls, and under what submitted names.
+*
+* Names matter more than they look. `createConversionRoute` (`@getvitops/astro/routes`) is
+* what receives the post, and it reserves a few: `phone` and `event` are the tel:/mailto:
+* click-beacon payload and are dropped from a form submission, `cf-turnstile-response` is
+* the Turnstile token, and `website`/`honeypot`/`_honeypot` are the honeypots (a filled one
+* makes the route answer success and deliver nothing). A visitor-facing field called
+* "Phone" must therefore not submit as `phone`, or the number silently vanishes from the
+* notification and the CRM record. `identifySubmitter` reads `tel` for a phone number, so
+* that is where it goes.
+*/
+const FIELD_TYPES = [
+	"text",
+	"email",
+	"tel",
+	"textarea",
+	"select",
+	"checkbox",
+	"checkboxes"
+];
+/** Names the route treats specially. A field must never submit under one of these. */
+const RESERVED_NAMES = /* @__PURE__ */ new Set([
+	"event",
+	"phone",
+	"cf-turnstile-response",
+	"website",
+	"honeypot",
+	"_honeypot",
+	"_next"
+]);
+const MAX_FIELDS = 20;
+const str = (v) => typeof v === "string" ? v.trim() : "";
+/** `Your full name` -> `your_full_name`. Empty when the text holds nothing usable. */
+function slugName(input) {
+	return input.toLowerCase().normalize("NFKD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 40);
+}
+/** A submitted name for a row: the editor's `name` if usable, else one derived from the label. */
+function fieldName(raw, label, type, taken) {
+	let base = slugName(str(raw)) || slugName(label) || type;
+	if (!/^[a-z]/.test(base)) base = `f_${base}`;
+	if (base === "phone") base = "tel";
+	if (RESERVED_NAMES.has(base)) base = `${base}_field`;
+	let name = base;
+	for (let n = 2; taken.has(name); n++) name = `${base}_${n}`;
+	taken.add(name);
+	return name;
+}
+/** The HTML `autocomplete` token for a field, or undefined when there is no honest one. */
+function autocompleteFor(name, type) {
+	if (type === "email") return "email";
+	if (type === "tel") return "tel";
+	if (type !== "text") return void 0;
+	return {
+		name: "name",
+		full_name: "name",
+		your_name: "name",
+		first_name: "given-name",
+		given_name: "given-name",
+		last_name: "family-name",
+		family_name: "family-name",
+		company: "organization",
+		organization: "organization",
+		organisation: "organization",
+		postal_code: "postal-code",
+		postcode: "postal-code",
+		zip: "postal-code",
+		city: "address-level2",
+		address: "street-address"
+	}[name];
+}
+/** Editor rows to renderable fields. Rows with no label are dropped; at most {@link MAX_FIELDS}. */
+function resolveFields(rows) {
+	const taken = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const row of rows) {
+		const label = str(row["label"]);
+		if (!label) continue;
+		if (out.length >= 20) break;
+		const rawType = str(row["type"]);
+		const type = FIELD_TYPES.includes(rawType) ? rawType : "text";
+		const name = fieldName(row["name"], label, type, taken);
+		const options = type === "select" || type === "checkboxes" ? str(row["options"]).split("\n").map((o) => o.trim()).filter(Boolean) : [];
+		const effective = (type === "select" || type === "checkboxes") && options.length === 0 ? "text" : type;
+		out.push({
+			name,
+			id: `form-${out.length + 1}-${name}`,
+			label,
+			type: effective,
+			required: row["required"] === true,
+			placeholder: effective === "checkbox" || effective === "select" || effective === "checkboxes" ? "" : str(row["placeholder"]),
+			help: str(row["help"]),
+			options,
+			autocomplete: autocompleteFor(name, effective)
+		});
+	}
+	return out;
+}
+/**
+* Where the endpoint may send a visitor back to: a same-site path, nothing else. The form
+* posts its own page path as `_next`; the route that reads it must apply this too, or the
+* field becomes an open redirect.
+*/
+function safeNext(input) {
+	const v = typeof input === "string" ? input : "";
+	if (!v.startsWith("/") || v.startsWith("//") || v.includes("\\") || v.length > 200) return null;
+	if (/[\u0000-\u001f\u007f#?]/.test(v)) return null;
+	return v;
+}
+/** The endpoint a form posts to: a same-site path, defaulting to the conversion route. */
+function safeAction(input) {
+	return safeNext(input) ?? "/api/track";
+}
+
+// src/form-template.ts
+/**
+* A saved `vitops_form` block as a `site.templates` form entry.
+*
+* `vitops legal` derives "what personal information we collect" from `site.templates` entries
+* of type `form`, and a build cannot read the CMS database the editor's block lives in, so a
+* form added in the admin is invisible to the generated privacy policy. This turns a block's
+* saved value (copy it from the admin's JSON view, or from `emdash` content export) into the
+* entry to paste under `site.templates` in `site.json`.
+*
+* It resolves fields through the SAME `resolveFields` the renderer uses, so the names are the
+* ones the form actually submits (`phone` becomes `tel`, reserved names are renamed) and rows
+* the renderer drops (no label) are dropped here too. A `checkboxes` becomes a `checkbox`
+* with its choices as `options`: the policy's schema has no group type and both read as
+* "your answers to the questions we ask".
+*/
+/** `block` is a saved `vitops_form` value (the object with `fields`, `action`, …). */
+function formTemplateFromBlock(block) {
+	const value = block && typeof block === "object" ? block : {};
+	const rows = (Array.isArray(value["fields"]) ? value["fields"] : []).filter((r) => !!r && typeof r === "object" && !Array.isArray(r));
+	return {
+		type: "form",
+		action: safeAction(value["action"]),
+		method: "post",
+		honeypot: true,
+		fields: resolveFields(rows).map((f) => ({
+			name: f.name,
+			type: f.type === "checkboxes" ? "checkbox" : f.type,
+			label: f.label,
+			...f.required ? { required: true } : {},
+			...f.options.length ? { options: f.options.map((o) => ({
+				label: o,
+				value: o
+			})) } : {}
+		}))
+	};
+}
+
 // src/hosting.ts
 const TARGETS = ["cloudflare", "node"];
 /**
@@ -1986,7 +2433,7 @@ async function vitopsHosting(options = {}) {
 }
 
 // package.json
-var version = "2.0.0-alpha.0";
+var version = "2.0.0-alpha.2";
 
 // src/index.ts
 /**
@@ -2088,11 +2535,13 @@ function createPlugin(options = {}) {
 		},
 		routes: {
 			[TONES_ROUTE]: createTonesRoute(() => roles),
+			[THEMES_ROUTE]: createThemesRoute(() => roles),
 			[MENUS_ROUTE]: createMenusRoute(() => getMenus()),
+			[WIDGET_AREAS_ROUTE]: createMenusRoute(() => getWidgetAreas()),
 			...editor ? { "design-system": createDesignSystemRoute(editor) } : {}
 		}
 	});
 }
 
-export { BLOCKS, SECTION_BLOCK_TYPE, SECTION_SLUG, createPlugin, createPlugin as default, renderBlocksDoc, resolveTone, selectBlocks, toneChain, vitopsBlockTypes, vitopsEmdash, vitopsHosting };
+export { BLOCKS, SECTION_BLOCK_TYPE, SECTION_SLUG, createPlugin, createPlugin as default, formTemplateFromBlock, renderBlocksDoc, resolveTone, selectBlocks, toneChain, vitopsBlockTypes, vitopsEmdash, vitopsHosting };
 //# sourceMappingURL=index.mjs.map