@getvitops/emdash 0.3.10 → 1.0.0

package/dist/index.mjs

@@ -1,7 +1,10 @@
-import { definePlugin } from "emdash";
+import { definePlugin, 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";
+import { commitFile } from "@getvitops/utils/git";
 
-//#region src/icon-options.ts
+// src/icon-options.ts
 /**
 * Semantic icon names, as Block Kit combobox options.
 *
@@ -22,8 +25,7 @@ const SEMANTIC_ICON_OPTIONS = Object.keys(iconMap.fa7).sort().map((name) => ({
 	value: name
 }));
 
-//#endregion
-//#region src/blocks.ts
+// src/blocks.ts
 const BLOCKS = [
 	{
 		/**
@@ -267,17 +269,34 @@ const BLOCKS = [
 		type: "vitops.carousel",
 		label: "Carousel",
 		placeholder: "Image carousel",
+		category: "Media",
 		fields: [
+			{
+				type: "repeater",
+				action_id: "slides",
+				label: "Slides",
+				item_label: "slide",
+				min_items: 1,
+				fields: [{
+					type: "text_input",
+					action_id: "src",
+					label: "Image URL"
+				}, {
+					type: "text_input",
+					action_id: "alt",
+					label: "Alt text"
+				}]
+			},
 			{
 				type: "text_input",
 				action_id: "images",
-				label: "Image URLs (one per line)",
+				label: "Image URLs, one per line (legacy — use Slides)",
 				multiline: true
 			},
 			{
 				type: "text_input",
 				action_id: "alts",
-				label: "Alt texts (one per line, same order)",
+				label: "Alt texts, one per line (legacy — use Slides)",
 				multiline: true
 			},
 			{
@@ -305,11 +324,489 @@ const BLOCKS = [
 				initial_value: "16 / 9"
 			}
 		]
+	},
+	{
+		type: "vitops.gallery",
+		label: "Gallery",
+		placeholder: "Thumbnail grid that opens a lightbox carousel",
+		category: "Media",
+		fields: [
+			{
+				type: "text_input",
+				action_id: "label",
+				label: "Accessible name",
+				initial_value: "Gallery"
+			},
+			{
+				type: "repeater",
+				action_id: "images",
+				label: "Images",
+				item_label: "image",
+				min_items: 1,
+				fields: [
+					{
+						type: "text_input",
+						action_id: "src",
+						label: "Image URL"
+					},
+					{
+						type: "text_input",
+						action_id: "alt",
+						label: "Alt text"
+					},
+					{
+						type: "text_input",
+						action_id: "caption",
+						label: "Caption"
+					}
+				]
+			},
+			{
+				type: "text_input",
+				action_id: "aspect",
+				label: "Thumbnail aspect ratio",
+				initial_value: "1"
+			},
+			{
+				type: "toggle",
+				action_id: "loop",
+				label: "Wrap around at the ends",
+				initial_value: false
+			}
+		]
+	},
+	{
+		type: "vitops.cards",
+		label: "Cards",
+		placeholder: "A grid of cards",
+		category: "Sections",
+		fields: [{
+			type: "repeater",
+			action_id: "cards",
+			label: "Cards",
+			item_label: "card",
+			min_items: 1,
+			fields: [
+				{
+					type: "text_input",
+					action_id: "title",
+					label: "Title"
+				},
+				{
+					type: "text_input",
+					action_id: "body",
+					label: "Text",
+					multiline: true
+				},
+				{
+					type: "text_input",
+					action_id: "image",
+					label: "Image URL"
+				},
+				{
+					type: "text_input",
+					action_id: "imageAlt",
+					label: "Image alt text"
+				},
+				{
+					type: "text_input",
+					action_id: "href",
+					label: "Link URL (makes the whole card clickable)"
+				},
+				{
+					type: "text_input",
+					action_id: "linkLabel",
+					label: "Link text",
+					initial_value: "Read more"
+				}
+			]
+		}, {
+			type: "select",
+			action_id: "columns",
+			label: "Columns",
+			initial_value: "3",
+			options: [
+				{
+					label: "1",
+					value: "1"
+				},
+				{
+					label: "2",
+					value: "2"
+				},
+				{
+					label: "3",
+					value: "3"
+				},
+				{
+					label: "4",
+					value: "4"
+				}
+			]
+		}]
+	},
+	{
+		type: "vitops.accordion",
+		label: "Accordion",
+		placeholder: "A group of collapsible sections",
+		category: "Sections",
+		fields: [{
+			type: "repeater",
+			action_id: "items",
+			label: "Items",
+			item_label: "item",
+			min_items: 1,
+			fields: [
+				{
+					type: "text_input",
+					action_id: "summary",
+					label: "Summary (always visible)"
+				},
+				{
+					type: "text_input",
+					action_id: "body",
+					label: "Body (revealed)",
+					multiline: true
+				},
+				{
+					type: "toggle",
+					action_id: "open",
+					label: "Open by default",
+					initial_value: false
+				}
+			]
+		}, {
+			type: "toggle",
+			action_id: "exclusive",
+			label: "Only one open at a time",
+			initial_value: false
+		}]
+	},
+	{
+		type: "vitops.hero",
+		label: "Hero",
+		placeholder: "Page opener: heading, text, buttons and an optional image",
+		category: "Sections",
+		fields: [
+			{
+				type: "text_input",
+				action_id: "eyebrow",
+				label: "Eyebrow (small line above)"
+			},
+			{
+				type: "text_input",
+				action_id: "heading",
+				label: "Heading"
+			},
+			{
+				type: "text_input",
+				action_id: "body",
+				label: "Text",
+				multiline: true
+			},
+			{
+				type: "text_input",
+				action_id: "primaryLabel",
+				label: "Main button text"
+			},
+			{
+				type: "text_input",
+				action_id: "primaryHref",
+				label: "Main button URL"
+			},
+			{
+				type: "text_input",
+				action_id: "secondaryLabel",
+				label: "Second link text"
+			},
+			{
+				type: "text_input",
+				action_id: "secondaryHref",
+				label: "Second link URL"
+			},
+			{
+				type: "text_input",
+				action_id: "image",
+				label: "Image URL (split layout)"
+			},
+			{
+				type: "text_input",
+				action_id: "imageAlt",
+				label: "Image alt text"
+			},
+			{
+				type: "select",
+				action_id: "layout",
+				label: "Layout",
+				initial_value: "centered",
+				options: [{
+					label: "Centered",
+					value: "centered"
+				}, {
+					label: "Text and image side by side",
+					value: "split"
+				}]
+			}
+		]
+	},
+	{
+		type: "vitops.marquee",
+		label: "Marquee",
+		placeholder: "A continuously scrolling row (logos, quotes, badges)",
+		category: "Media",
+		fields: [
+			{
+				type: "repeater",
+				action_id: "items",
+				label: "Items",
+				item_label: "item",
+				min_items: 1,
+				fields: [
+					{
+						type: "text_input",
+						action_id: "text",
+						label: "Text"
+					},
+					{
+						type: "text_input",
+						action_id: "image",
+						label: "Image URL (shown instead of text)"
+					},
+					{
+						type: "text_input",
+						action_id: "alt",
+						label: "Image alt text"
+					}
+				]
+			},
+			{
+				type: "toggle",
+				action_id: "pauseOnHover",
+				label: "Pause on hover",
+				initial_value: true
+			},
+			{
+				type: "toggle",
+				action_id: "reverse",
+				label: "Scroll the other way",
+				initial_value: false
+			}
+		]
 	}
 ];
+/**
+* Resolve {@link BlockSelection} against {@link BLOCKS}.
+*
+* Pure so a misconfiguration fails at plugin construction, with the offending name in the
+* message, rather than as an editor menu that is quietly missing something.
+*/
+function selectBlocks(selection = {}) {
+	const known = new Set(BLOCKS.map((b) => b.type));
+	const check = (names, option) => {
+		for (const name of names ?? []) if (!known.has(name)) throw new Error(`[vitops] blocks.${option}: unknown block '${name}'. Known: ${[...known].join(", ")}.`);
+	};
+	check(selection.include, "include");
+	check(selection.exclude, "exclude");
+	const include = selection.include ? new Set(selection.include) : null;
+	const exclude = new Set(selection.exclude);
+	const base = BLOCKS.filter((b) => (!include || include.has(b.type)) && !exclude.has(b.type));
+	const extra = selection.extra ?? [];
+	const taken = new Set(BLOCKS.map((b) => b.type));
+	for (const block of extra) {
+		if (taken.has(block.type)) throw new Error(`[vitops] blocks.extra: type '${block.type}' is already defined.`);
+		taken.add(block.type);
+	}
+	return [...base, ...extra];
+}
+
+// src/design-system-route.ts
+/**
+* The `vitops.design-system` plugin route — what `<wc-theme-editor>` probes
+* and POSTs its patch to when mounted inside the EmDash admin (see this
+* package's README and AGENTS.md's "EmDash plugin as the design-system
+* editing surface" section). Mounted at
+* `/_emdash/api/plugins/vitops/design-system`.
+*
+* Two responsibilities, matching the dev-only `@getvitops/vite` endpoint's
+* contract byte-for-byte (`GET → { writable }`, `POST { patch } → { ok } |
+* { errors }`) so `<wc-theme-editor>` needs no branch for which one it's
+* talking to:
+*
+* 1. **Immediate**: persist the patch to `ctx.settings` — read back by the
+*    `page:fragments` hook in `index.ts`, which turns it into a site-wide
+*    `:root` override `<style>` on every public page. This is what makes an
+*    edit visible without a rebuild.
+* 2. **Canonical**: auto-commit the merged file to `site.deployment.branch`
+*    (default `dev`) via `@getvitops/utils/git`'s `commitFile()`, so the edit
+*    reaches the git-tracked `site.json` through this repo's own normal
+*    `dev → promote → main` review path — never a silent second source of
+*    truth. A commit failure (missing token, misconfigured repo, a transient
+*    GitHub error) is logged and surfaces as a warning, but never fails the
+*    save: the immediate override already works regardless.
+*
+* **Assumes `config` is a full site `Config`** (has `organization`/`site`),
+* not a bare `design-system.json` — true for any real EmDash site (it always
+* has a `site.json`), and the only case this plugin already handles anywhere
+* else (`vitopsHosting()`, `BLOCKS`).
+*
+* The GitHub token is read as `process.env.VITOPS_GITHUB_TOKEN` — matching
+* `hosting.ts`'s own `process.env.HOSTING` read in this same package, rather
+* than a `cloudflare:workers`-specific import: a native EmDash plugin runs
+* in-process with no isolation boundary (EmDash's own docs say plugins "can
+* access environment variables" directly), and this package already targets
+* both the Cloudflare and Node hosting targets through one `process.env`
+* convention (`nodejs_compat` on Workers maps bindings into `process.env`).
+*/
+const SETTINGS_KEY = "designSystemPatch";
+function json(status, body) {
+	return pluginResponse({
+		status,
+		headers: { "content-type": "application/json" },
+		body: {
+			kind: "text",
+			value: JSON.stringify(body)
+		}
+	});
+}
+/** Fetches the currently-stored patch, clearing it if the bundled `config`
+* (the last real build) already reflects every value in it — see the
+* module docblock's "self-clearing" note in AGENTS.md. */
+async function currentPatch(ctx, ds) {
+	const stored = await ctx.settings.get(SETTINGS_KEY);
+	if (!stored) return null;
+	const patchedColors = stored.patch["colors"];
+	if (patchedColors != null && JSON.stringify(mergePatch(ds.colors, patchedColors)) === JSON.stringify(ds.colors)) {
+		await ctx.settings.delete(SETTINGS_KEY);
+		return null;
+	}
+	return stored;
+}
+function createDesignSystemRoute(opts) {
+	const theme = opts.theme ?? "default";
+	return {
+		methods: ["GET", "POST"],
+		response: "raw",
+		permission: "plugins:manage",
+		handler: async (ctx) => {
+			const { designSystem: ds, config } = resolveInput(opts.config, {
+				theme,
+				siteEnv: "production"
+			});
+			if (ctx.request.method === "GET") {
+				await currentPatch(ctx, ds);
+				return json(200, { writable: true });
+			}
+			const patch = ctx.input?.patch;
+			if (patch == null || typeof patch !== "object" || Array.isArray(patch)) return json(400, { errors: ["body must be { patch: object }"] });
+			const mergedColors = mergePatch(ds.colors, patch["colors"] ?? {});
+			const contrastErrors = validateColorContract(mergedColors);
+			if (contrastErrors.length) return json(400, { errors: contrastErrors });
+			await ctx.settings.set(SETTINGS_KEY, {
+				patch,
+				at: Date.now()
+			});
+			const warnings = [];
+			const repoSpec = config?.site.deployment?.repo;
+			const token = process.env["VITOPS_GITHUB_TOKEN"];
+			if (!repoSpec || !token) warnings.push(!repoSpec ? "design-system sync skipped: site.deployment.repo is not set — the change is live but not yet synced to source." : "design-system sync skipped: no GitHub token configured — the change is live but not yet synced to source.");
+			else {
+				const [owner, repo] = repoSpec.split("/");
+				if (!owner || !repo) warnings.push(`design-system sync skipped: site.deployment.repo "${repoSpec}" isn't "owner/name".`);
+				else if (!isConfig(opts.config)) warnings.push("design-system sync skipped: config is not a recognised site Config.");
+				else {
+					const at = designSystemPath(opts.config, theme);
+					const mergedSubtree = mergePatch(getAt(opts.config, at), patch);
+					const content = `${formatConfig(setAt(opts.config, at, mergedSubtree))}\n`;
+					const result = await commitFile({
+						owner,
+						repo,
+						branch: config.site.deployment?.branch ?? "dev",
+						path: "site.json",
+						content,
+						message: "Sync design-system edit from EmDash admin",
+						token,
+						fetchImpl: ctx.http && ((url, init) => ctx.http.fetch(url, init))
+					});
+					if (!result.ok) {
+						ctx.log.warn("design-system sync commit failed", { message: result.message });
+						warnings.push(`design-system sync failed (change is still live): ${result.message}`);
+					}
+				}
+			}
+			return json(200, {
+				ok: true,
+				warnings
+			});
+		}
+	};
+}
+/**
+* The `page:fragments` contribution serving the stored patch's override
+* CSS site-wide. Returns `null` (no fragment) when there's nothing unsynced
+* — the same "no gated tag, no cost" discipline `@getvitops/astro`'s consent
+* gate already follows.
+*/
+async function designSystemOverrideFragment(ctx, opts) {
+	const { designSystem: ds } = resolveInput(opts.config, { theme: opts.theme ?? "default" });
+	const stored = await currentPatch(ctx, ds);
+	if (!stored) return null;
+	const css = patchToOverrideCss(stored.patch, buildReverseIndex(ds));
+	if (!css) return null;
+	return {
+		kind: "html",
+		placement: "head",
+		html: `<style id="ds-overrides">${css}</style>`,
+		key: "vitops-ds-overrides"
+	};
+}
 
-//#endregion
-//#region src/hosting.ts
+// src/blocks-doc.ts
+const cell = (s) => (s ?? "").replace(/\|/g, "\\|").replace(/\n/g, " ");
+function describe(f) {
+	const bits = [];
+	if ("options" in f && Array.isArray(f.options) && f.options.length) {
+		const values = f.options.map((o) => String(o.value));
+		bits.push(values.length > 8 ? `one of ${values.length} values (e.g. ${values.slice(0, 4).join(", ")})` : `one of ${values.join(", ")}`);
+	}
+	if ("initial_value" in f && f.initial_value !== void 0) bits.push(`default \`${String(f.initial_value)}\``);
+	if (f.type === "repeater" && "min_items" in f && f.min_items) bits.push(`min ${f.min_items} rows`);
+	return bits.join("; ");
+}
+function fieldRows(fields, prefix = "") {
+	return fields.flatMap((f) => {
+		const own = `| \`${prefix}${f.action_id}\` | ${f.type} | ${cell(f.label)} | ${cell(describe(f))} |`;
+		return f.type === "repeater" ? [own, ...fieldRows(f.fields, `${f.action_id}[].`)] : [own];
+	});
+}
+/**
+* The block reference an agent reads via `vitops docs blocks`: every Portable Text `_type`,
+* its fields and what each saves. Rendered from the same `BLOCKS` the editor menu uses, so
+* it cannot describe a field the editor doesn't offer.
+*/
+function renderBlocksDoc(blocks = BLOCKS) {
+	const out = [
+		"---",
+		"type: concept",
+		"title: EmDash blocks",
+		"description: Portable Text block types from @getvitops/emdash, with every field",
+		"---",
+		"",
+		"# EmDash blocks",
+		"",
+		"Each block is a Portable Text object: `{ \"_type\": \"vitops.cards\", \"_key\": \"<unique>\", ...fields }`.",
+		"Blocks are flat — a block cannot contain other blocks, and a repeater row holds scalar fields only.",
+		"Give every block a unique `_key`; gallery and carousel derive their element id from it.",
+		""
+	];
+	for (const b of blocks) {
+		out.push(`## \`${b.type}\` — ${b.label}`, "");
+		if (b.placeholder) out.push(`${b.placeholder}.`, "");
+		if (b.fields?.length) out.push("| Field | Type | Label | Notes |", "| --- | --- | --- | --- |", ...fieldRows(b.fields), "");
+	}
+	return out.join("\n");
+}
+
+// src/hosting.ts
 const TARGETS = ["cloudflare", "node"];
 /**
 * Import an optional hosting dependency. The specifier is passed as a
@@ -338,7 +835,8 @@ async function vitopsHosting(options = {}) {
 			adapter: cloudflare(),
 			database: d1({
 				binding: cf.dbBinding ?? "DB",
-				session: cf.session ?? "auto"
+				session: cf.session ?? "auto",
+				coalesce: cf.coalesce ?? true
 			}),
 			storage: r2({ binding: cf.mediaBinding ?? "MEDIA" })
 		};
@@ -368,12 +866,10 @@ async function vitopsHosting(options = {}) {
 	throw new Error(`[vitops] unknown hosting target '${target}' (from ${process.env.HOSTING ? "HOSTING env var" : "options.target"}). Valid targets: ${TARGETS.join(", ")}.`);
 }
 
-//#endregion
-//#region package.json
-var version = "0.3.9";
+// package.json
+var version = "1.0.0";
 
-//#endregion
-//#region src/index.ts
+// src/index.ts
 /**
 * @getvitops/emdash — EmDash CMS native plugin for the Vitops design system.
 *
@@ -388,10 +884,12 @@ var version = "0.3.9";
 *
 * ```js
 * // astro.config.mjs
+* import config from './site.json' with { type: 'json' };
+*
 * integrations: [
 *   react(),
 *   vitops({ css: {...} }),
-*   emdash({ database, storage, plugins: [vitopsEmdash()] }),
+*   emdash({ database, storage, plugins: [vitopsEmdash({ designSystemEditor: { config } })] }),
 * ]
 * ```
 */
@@ -407,6 +905,8 @@ var version = "0.3.9";
 const VERSION = version;
 const PLUGIN_ID = "vitops";
 const FRAGMENTS_CAPABILITY = "hooks.page-fragments:register";
+/** For the design-system-editor's GitHub auto-commit — see design-system-route.ts. */
+const NETWORK_CAPABILITY = "network:request";
 /**
 * Descriptor factory — import in `astro.config.mjs` and pass to the emdash()
 * integration's `plugins` array.
@@ -418,19 +918,20 @@ function vitopsEmdash(options = {}) {
 		format: "native",
 		entrypoint: "@getvitops/emdash",
 		componentsEntry: "@getvitops/emdash/astro",
+		...options.designSystemEditor ? { adminEntry: "@getvitops/emdash/admin" } : {},
 		options,
-		capabilities: options.scripts === "fragments" ? [FRAGMENTS_CAPABILITY] : []
+		capabilities: [...options.scripts === "fragments" || options.designSystemEditor ? [FRAGMENTS_CAPABILITY] : [], ...options.designSystemEditor ? [NETWORK_CAPABILITY] : []]
 	};
 }
 /** Runtime side — EmDash imports and calls this from the descriptor's entrypoint. */
 function createPlugin(options = {}) {
 	const scripts = options.scripts ?? "integration";
 	const wcBase = options.wcBase ?? "/vitops";
-	return definePlugin({
-		id: PLUGIN_ID,
-		version: VERSION,
-		capabilities: scripts === "fragments" ? [FRAGMENTS_CAPABILITY] : [],
-		hooks: scripts === "fragments" ? { "page:fragments": async () => [{
+	const editor = options.designSystemEditor || void 0;
+	const fragmentsEnabled = scripts === "fragments" || !!editor;
+	const pageFragments = async (_event, ctx) => {
+		const contributions = [];
+		if (scripts === "fragments") contributions.push({
 			kind: "html",
 			placement: "head",
 			html: `<link rel="modulepreload" href="${wcBase}/polyfills.js"><script type="module" src="${wcBase}/polyfills.js"><\/script><script type="module" src="${wcBase}/elements.js"><\/script>`,
@@ -441,11 +942,33 @@ function createPlugin(options = {}) {
 			src: `${wcBase}/deferred.js`,
 			defer: true,
 			key: "vitops-deferred"
-		}] } : {},
-		admin: { portableTextBlocks: BLOCKS }
+		});
+		if (editor) {
+			const fragment = await designSystemOverrideFragment(ctx, editor);
+			if (fragment) contributions.push(fragment);
+		}
+		return contributions;
+	};
+	return definePlugin({
+		id: PLUGIN_ID,
+		version: VERSION,
+		capabilities: [...fragmentsEnabled ? [FRAGMENTS_CAPABILITY] : [], ...editor ? [NETWORK_CAPABILITY] : []],
+		...editor ? { allowedHosts: ["api.github.com"] } : {},
+		...fragmentsEnabled ? { hooks: { "page:fragments": pageFragments } } : {},
+		admin: {
+			portableTextBlocks: selectBlocks(options.blocks),
+			...editor ? {
+				entry: "@getvitops/emdash/admin",
+				pages: [{
+					path: "/design-system",
+					label: "Design System",
+					icon: "palette"
+				}]
+			} : {}
+		},
+		...editor ? { routes: { "design-system": createDesignSystemRoute(editor) } } : {}
 	});
 }
 
-//#endregion
-export { BLOCKS, createPlugin, createPlugin as default, vitopsEmdash, vitopsHosting };
+export { BLOCKS, createPlugin, createPlugin as default, renderBlocksDoc, selectBlocks, vitopsEmdash, vitopsHosting };
 //# sourceMappingURL=index.mjs.map