@cloudcannon/editable-regions 0.0.18 → 0.0.19

package/helpers/checks.ts

@@ -1,7 +1,3 @@
-import Editable from "../nodes/editable.js";
-import EditableArrayItem from "../nodes/editable-array-item.js";
-import EditableText from "../nodes/editable-text.js";
-
 const getEditableType = (el: HTMLElement): string | undefined => {
 	if (el.tagName.startsWith("EDITABLE-")) {
 		return el.tagName.slice(9).toLowerCase();
@@ -9,24 +5,6 @@ const getEditableType = (el: HTMLElement): string | undefined => {
 	return el.dataset.editable;
 };
 
-export const hasEditable = <T extends object>(
-	el: T,
-): el is T & { editable: Editable } => {
-	return "editable" in el && el.editable instanceof Editable;
-};
-
-export const hasEditableText = <T extends object>(
-	el: T,
-): el is T & { editable: EditableText } => {
-	return "editable" in el && el.editable instanceof EditableText;
-};
-
-export const hasEditableArrayItem = <T extends object>(
-	el: T,
-): el is T & { editable: EditableArrayItem } => {
-	return "editable" in el && el.editable instanceof EditableArrayItem;
-};
-
 export const isEditableWebcomponent = (el: unknown): boolean => {
 	if (!(el instanceof HTMLElement)) {
 		return false;

package/helpers/hydrate-editable-regions.ts

@@ -7,7 +7,8 @@ import {
 	EditableSource,
 	EditableText,
 } from "../nodes";
-import { hasEditable, isEditableWebcomponent } from "./checks";
+import { hasEditable } from "../nodes/editable.js";
+import { isEditableWebcomponent } from "./checks";
 
 const baseEditableMap: Record<string, typeof Editable | undefined> = {
 	array: EditableArray,

package/integrations/astro/react-renderer.mjs

@@ -1,54 +1,129 @@
-import { createElement } from "react";
+/** biome-ignore-all lint/suspicious/noPrototypeBuiltins: Matches the behaviour of @astrojs/react */
+import ssr from "@astrojs/react/server.js";
+import * as React from "react";
 import { flushSync } from "react-dom";
 import { createRoot } from "react-dom/client";
-import { renderToStaticMarkup } from "react-dom/server.browser";
-
 import { addFrameworkRenderer, queueForClientSideRender } from "./index.mjs";
 
+/**
+ * @param {string} str
+ * @returns {string}
+ */
+const slotName = (str) =>
+	str.trim().replace(/[-_]([a-z])/g, (_, w) => w.toUpperCase());
+const reactTypeof = Symbol.for("react.element");
+const reactTransitionalTypeof = Symbol.for("react.transitional.element");
+
 addFrameworkRenderer({
 	name: "@astrojs/react",
 	clientEntrypoint: "@astrojs/react/client.js",
 	ssr: {
 		/**
 		 * @param {any} Component
-		 * @returns {boolean}
+		 * @param {any} props
+		 * @param {Record<string, string>} children
+		 * @returns {Promise<boolean>}
 		 */
-		check: (Component) => {
+		check: async (Component, props, children) => {
+			if (typeof Component === "object") {
+				return !!Component.$$typeof
+					?.toString()
+					.slice("Symbol(".length)
+					.startsWith("react");
+			}
 			if (typeof Component !== "function") return false;
+			if (Component.name === "QwikComponent") return false;
 
-			// React class components have render on the prototype
-			if (typeof Component.prototype?.render === "function") return true;
+			if (
+				typeof Component === "function" &&
+				Component.$$typeof === Symbol.for("react.forward_ref")
+			)
+				return false;
 
-			// React functional components return vnodes with $$typeof
-			try {
-				const vnode = Component({});
+			if (
+				Component.prototype != null &&
+				typeof Component.prototype.render === "function"
+			) {
 				return (
-					vnode != null && typeof vnode === "object" && "$$typeof" in vnode
+					React.Component.isPrototypeOf(Component) ||
+					React.PureComponent.isPrototypeOf(Component)
 				);
-			} catch {
-				return false;
 			}
+
+			let isReactComponent = false;
+			/** @param  {...any} args */
+			function Tester(...args) {
+				try {
+					const vnode = Component(...args);
+					if (
+						vnode &&
+						(vnode.$$typeof === reactTypeof ||
+							vnode.$$typeof === reactTransitionalTypeof)
+					) {
+						isReactComponent = true;
+					}
+				} catch {}
+
+				return React.createElement("div");
+			}
+
+			await ssr.renderToStaticMarkup.call(this, Tester, props, children);
+
+			return isReactComponent;
 		},
 		/**
 		 * Renders to static markup, falling back to a client-side render queue.
 		 * @param {any} Component
 		 * @param {any} props
+		 * @param {Record<string, string>} inputSlotted
+		 * @param {any} metadata
 		 * @returns {Promise<{ html: string }>}
 		 */
-		renderToStaticMarkup: async (Component, props) => {
-			try {
-				const reactNode = Component(props);
-				return { html: renderToStaticMarkup(reactNode) };
-			} catch (_err) {
+		renderToStaticMarkup: async (Component, props, inputSlotted, metadata) => {
+			if (metadata?.hydrate) {
+				const { default: children, ...slotted } = inputSlotted;
+				/** @type{Record<string, React.ReactNode>} */
+				const slots = {};
+				for (const [key, value] of Object.entries(slotted)) {
+					const name = slotName(key);
+					slots[name] = React.createElement("astro-static-slot", {
+						suppressHydrationWarning: true,
+						// biome-ignore lint/security/noDangerouslySetInnerHtml: Intentionally rendering static html
+						dangerouslySetInnerHTML: { __html: value },
+					});
+				}
+
+				const newProps = {
+					...props,
+					...slots,
+				};
+				const newChildren = children ?? props.children;
+				if (newChildren != null) {
+					newProps.children = React.createElement("astro-static-slot", {
+						suppressHydrationWarning: true,
+						// biome-ignore lint/security/noDangerouslySetInnerHtml: Intentionally rendering static html
+						dangerouslySetInnerHTML: { __html: newChildren },
+					});
+				}
+
 				const id = queueForClientSideRender((node) => {
-					const reactNode = createElement(Component, props, null);
+					const reactNode = React.createElement(Component, newProps);
 					const root = createRoot(node);
 					flushSync(() => root.render(reactNode));
 				});
+
 				return {
 					html: `<div data-editable-region-csr-id=${id}></div>`,
 				};
 			}
+
+			return ssr.renderToStaticMarkup.call(
+				this,
+				Component,
+				props,
+				inputSlotted,
+				{ ...metadata, astroStaticSlot: true, hydrate: false },
+			);
 		},
 	},
 });

package/integrations/astro/svelte-renderer.mjs

@@ -1,3 +1,4 @@
+import { createRawSnippet } from "svelte";
 import { addFrameworkRenderer, queueForClientSideRender } from "./index.mjs";
 
 /** @type{((component: any, args: { target: HTMLElement, props: unknown }) => void) | undefined} */
@@ -39,27 +40,83 @@ addFrameworkRenderer({
 			return false;
 		},
 		/**
+		 * Renders to static markup, falling back to a client-side render queue.
 		 * @param {any} Component
-		 * @param {unknown} props
-		 * @returns {Promise<{html: string}>}
+		 * @param {any} props
+		 * @param {Record<string, string>} slots
+		 * @param {any} metadata
+		 * @returns {Promise<{ html: string }>}
 		 */
-		renderToStaticMarkup: async (Component, props) => {
-			const id = queueForClientSideRender((node) => {
-				if (mount) {
-					mount(Component, {
-						target: /** @type{any}*/ (node),
-						props,
-					});
+		renderToStaticMarkup: async (Component, props, slots, metadata) => {
+			/** @type{Record<string, any>} */
+			const renderProps = {};
+			/** @type{Record<string, any> | undefined} */
+			let $$slots;
+			/** @type{import("svelte").Snippet | undefined} */
+			let children;
+			for (const [key, value] of Object.entries(slots)) {
+				$$slots ??= {};
+				if (key === "default") {
+					$$slots.default = true;
+					children = createRawSnippet(() => ({
+						render: () => value,
+					}));
 				} else {
-					new Component({ target: node, props });
+					$$slots[key] = createRawSnippet(() => ({
+						render: () => value,
+					}));
 				}
+				const slotName = key === "default" ? "children" : key;
+				renderProps[slotName] = createRawSnippet(() => ({
+					render: () => value,
+				}));
+			}
 
-				flushSync();
-			});
-
-			return {
-				html: `<div data-editable-region-csr-id=${id}></div>`,
+			const newProps = {
+				...props,
+				children,
+				$$slots,
+				...renderProps,
 			};
+
+			if (metadata?.hydrate) {
+				const id = queueForClientSideRender((node) => {
+					if (mount) {
+						mount(Component, {
+							target: /** @type{any}*/ (node),
+							props: newProps,
+						});
+					} else {
+						new Component({
+							target: node,
+							props: newProps,
+						});
+					}
+
+					flushSync();
+				});
+
+				return {
+					html: `<div data-editable-region-csr-id=${id}></div>`,
+				};
+			}
+
+			const doc = document.implementation.createHTMLDocument();
+			if (mount) {
+				mount(Component, {
+					target: /** @type{any}*/ (doc.body),
+					props: newProps,
+				});
+			} else {
+				new Component({
+					target: doc.body,
+					props: newProps,
+				});
+			}
+
+			flushSync();
+
+			return { html: doc.body.innerHTML };
 		},
 	},
 });

package/integrations/astro/vue-renderer.mjs

@@ -0,0 +1,61 @@
+import { createApp, h } from "vue";
+import { renderToString } from "vue/server-renderer";
+
+import { addFrameworkRenderer, queueForClientSideRender } from "./index.mjs";
+
+addFrameworkRenderer({
+	name: "@astrojs/vue",
+	clientEntrypoint: "@astrojs/vue/client.js",
+	ssr: {
+		/**
+		 * Checks if the component is a Vue component (object with Vue-specific markers).
+		 * @param {any} Component - The component to check
+		 * @returns {boolean} True if component looks like a Vue component
+		 */
+		check: (Component) => {
+			return (
+				typeof Component === "object" &&
+				Component !== null &&
+				("render" in Component ||
+					"setup" in Component ||
+					"template" in Component ||
+					"ssrRender" in Component ||
+					"__ssrInlineRender" in Component ||
+					"__file" in Component)
+			);
+		},
+
+		/**
+		 * Renders to static markup, falling back to a client-side render queue.
+		 * @param {any} Component
+		 * @param {any} inputProps
+		 * @param {Record<string, string>} slotted
+		 * @param {any} metadata
+		 * @returns {Promise<{ html: string }>}
+		 */
+		renderToStaticMarkup: async (Component, inputProps, slotted, metadata) => {
+			/** @type{Record<string, Function>} */
+			const slots = {};
+			const props = { ...inputProps };
+			delete props.slot;
+			for (const [key, value] of Object.entries(slotted)) {
+				slots[key] = () => h("astro-static-slot", { innerHTML: value });
+			}
+
+			if (metadata?.hydrate) {
+				const id = queueForClientSideRender((node) => {
+					const app = createApp({ render: () => h(Component, props, slots) });
+					app.mount(node);
+				});
+
+				return {
+					html: `<div data-editable-region-csr-id=${id}></div>`,
+				};
+			}
+
+			const app = createApp({ render: () => h(Component, props, slots) });
+			const html = await renderToString(app);
+			return { html };
+		},
+	},
+});

package/integrations/eleventy/browser/collect-config.mjs

@@ -18,10 +18,12 @@ import {
 	registerShortcode,
 } from "../../liquid/index.mjs";
 import { warnOnce } from "../../liquid/logger.mjs";
+import { createInertValue } from "./inert.mjs";
 import {
 	builtinFilterNames,
 	builtinShortcodeNames,
 } from "./liquid-builtins.mjs";
+import { setStubsStrict } from "./stub-mode.mjs";
 
 /** @type {Record<HelperKind, (name: string, fn: any) => void>} */
 const KIND_REGISTRARS = {
@@ -58,7 +60,8 @@ const METHOD_TARGETS = {
  * if it's neither (so the caller can skip it).
  *
  * @param {any} plugin
- * @returns {((config: any, opts: any) => void) | null}
+ * @returns {((config: any, opts: any) => any) | null} Async plugins return a
+ *   promise the caller must await.
  */
 function resolvePluginFunction(plugin) {
 	if (typeof plugin === "function") return plugin;
@@ -78,15 +81,34 @@ function createEmptyLayer() {
 }
 
 /**
- * Replays `configFn` against a recording stand-in and registers every
- * collected helper that isn't skipped.
+ * Mirrors the config's helpers into the live-editing engine.
+ *
+ * The mirror is async because configs commonly are — `await
+ * import("@11ty/eleventy")` is how a CommonJS config reaches the ESM-only
+ * exports, and such a config registers nothing until that settles. The bundle
+ * awaits the returned promise before registering anything else.
  *
  * @param {unknown} config - The config's default export (a function), or a
  *   module namespace whose `.default` is that function (ESM/CJS interop).
  * @param {{ skip?: Partial<Record<HelperKind, string[]>> }} [options] - Per-kind
  *   override names to skip; builtin browser-port names are skipped automatically.
+ * @returns {Promise<void>} Resolves once every mirrored helper is registered.
  */
 export function collectAndRegisterEleventyHelpers(config, options = {}) {
+	// `finally` so a mirror that failed still leaves render-time stub calls
+	// throwing; see `stub-mode.mjs`.
+	return mirrorConfig(config, options).finally(setStubsStrict);
+}
+
+/**
+ * Replays `configFn` against a recording stand-in and registers every
+ * collected helper that isn't skipped.
+ *
+ * @param {unknown} config
+ * @param {{ skip?: Partial<Record<HelperKind, string[]>> }} options
+ * @returns {Promise<void>}
+ */
+async function mirrorConfig(config, options) {
 	const configFn =
 		typeof config === "function"
 			? config
@@ -130,15 +152,22 @@ export function collectAndRegisterEleventyHelpers(config, options = {}) {
 		};
 	}
 
-	// Unrecorded methods are no-ops so running the real config (which calls
-	// `addPassthroughCopy`, `on`, sets `dir`, ...) doesn't throw.
+	// Unrecorded members are inert so the real config (`addPassthroughCopy`,
+	// `on`, `ignores.add(…)`, setting `dir`, ...) doesn't throw. Chainable, so
+	// reaching through a property before calling still works.
+	const unrecorded = createInertValue();
 	const configRecorder = new Proxy(recorder, {
 		get(target, prop, receiver) {
 			if (prop in target) return Reflect.get(target, prop, receiver);
-			return () => {};
+			// Thenable-looking recorder would hang `pendingPlugins`; see `inert.mjs`.
+			if (prop === "then" || typeof prop === "symbol") return undefined;
+			return unrecorded;
 		},
 	});
 
+	/** Async plugins, drained before the registration pass. @type {Promise<void>[]} */
+	const pendingPlugins = [];
+
 	recorder.addPlugin = (/** @type {any} */ plugin, /** @type {any} */ opts) => {
 		const pluginFn = resolvePluginFunction(plugin);
 		if (!pluginFn) return;
@@ -146,16 +175,28 @@ export function collectAndRegisterEleventyHelpers(config, options = {}) {
 		// A plugin is itself a config function, so replay it against the same
 		// recorder to capture the helpers it registers.
 		try {
-			pluginFn(configRecorder, opts);
+			const result = pluginFn(configRecorder, opts);
+			if (typeof result?.then === "function") {
+				// `Promise.resolve` normalizes: a native promise is returned as-is,
+				// a bare thenable gains `.catch`. Async stubs reject; swallow both.
+				pendingPlugins.push(Promise.resolve(result).catch(() => {}));
+			}
 		} catch {
 			// Node-only plugins are stubbed at bundle time and throw when called.
 			// Helpers registered before the throw are kept; the config continues.
 		}
 	};
 
+	let replayFailed = false;
+
 	try {
-		configFn(configRecorder);
+		await configFn(configRecorder);
+		// A plugin can register further plugins, so drain until nothing new lands.
+		while (pendingPlugins.length > 0) {
+			await Promise.all(pendingPlugins.splice(0));
+		}
 	} catch (err) {
+		replayFailed = true;
 		warnOnce(
 			"eleventy-config-replay",
 			"Replaying the Eleventy config to mirror its helpers threw: " +
@@ -165,12 +206,15 @@ export function collectAndRegisterEleventyHelpers(config, options = {}) {
 		);
 	}
 
+	let mirroredCount = 0;
+
 	for (const kind of /** @type {HelperKind[]} */ (
 		Object.keys(KIND_REGISTRARS)
 	)) {
 		const register = KIND_REGISTRARS[kind];
 		// Liquid layer spread last so it wins on a name collision.
 		const merged = new Map([...layers.universal[kind], ...layers.liquid[kind]]);
+		mirroredCount += merged.size;
 
 		for (const [name, helperFn] of merged) {
 			if (skip[kind].has(name)) continue;
@@ -185,4 +229,21 @@ export function collectAndRegisterEleventyHelpers(config, options = {}) {
 			}
 		}
 	}
+
+	// An async config mirroring nothing otherwise surfaces as a `strictFilters`
+	// "unknown filter" error inside an unrelated template. A replay that threw
+	// has already warned, and explains the empty result.
+	if (
+		mirroredCount === 0 &&
+		!replayFailed &&
+		configFn.constructor?.name === "AsyncFunction"
+	) {
+		warnOnce(
+			"eleventy-async-config",
+			"Your Eleventy config is async and registered no helpers when replayed " +
+				"for live editing. If it defines filters/shortcodes they won't be " +
+				"available — define a browser override via " +
+				"`pluginOptions.liquid.<kind>` for any that are needed.",
+		);
+	}
 }

package/integrations/eleventy/browser/inert.mjs

@@ -0,0 +1,35 @@
+/**
+ * A stand-in that survives whatever a config does to it — property access,
+ * calls and `new` all return it again. Used for unrecorded config methods
+ * (`collect-config.mjs`) and stubbed Node modules (`stub-mode.mjs`).
+ *
+ * @returns {any}
+ */
+export function createInertValue() {
+	// `function`, not an arrow: arrows have no [[Construct]], so `new inert()`
+	// would throw before the trap runs.
+	const handler = {
+		/** @param {any} _target @param {string | symbol} prop */
+		get(_target, prop) {
+			// Must not look thenable: `collect-config.mjs` treats a plugin result
+			// with a callable `.then` as a promise, and this one would never
+			// settle — hanging the mirror, so no component is ever published.
+			if (prop === "then") return undefined;
+
+			if (typeof prop === "symbol") {
+				// Else `String(inert)` walks toPrimitive → valueOf → toString,
+				// gets a proxy from each, and throws.
+				if (prop === Symbol.toPrimitive) return () => "";
+				// Else `for…of` / spread over a stubbed call throws.
+				if (prop === Symbol.iterator) return function* () {};
+				return undefined;
+			}
+			return inert;
+		},
+		apply: () => inert,
+		construct: () => inert,
+	};
+
+	const inert = new Proxy(function () {}, handler);
+	return inert;
+}

package/integrations/eleventy/browser/process-shim.mjs

@@ -0,0 +1,32 @@
+/**
+ * Stand-ins for the Node globals a config reaches for without importing
+ * anything, so there's no module to stub — `process.env.X` at the top of a
+ * config otherwise kills the bundle with `ReferenceError: process is not
+ * defined`. esbuild's `inject` substitutes these for unbound identifiers.
+ */
+
+/**
+ * `"development"` for the same reason `eleventy.env.runMode` is `"serve"`: a
+ * config gated on `NODE_ENV === "production"` shouldn't drag build-only
+ * plugins into the mirror. Real values belong in `pluginOptions.globals`.
+ *
+ * esbuild defines the exact expression `process.env.NODE_ENV` itself, and that
+ * wins over this object — changing the value here only affects indirect reads
+ * like `const e = process.env`.
+ */
+export const process = {
+	env: { NODE_ENV: "development" },
+	argv: [],
+	platform: "browser",
+	version: "",
+	versions: {},
+	browser: true,
+	cwd: () => "/",
+	nextTick: (/** @type {any} */ fn, /** @type {any[]} */ ...args) =>
+		queueMicrotask(() => fn(...args)),
+};
+
+export const __dirname = "/";
+export const __filename = "/";
+
+export default process;

package/integrations/eleventy/browser/stub-mode.mjs

@@ -0,0 +1,61 @@
+/**
+ * Strictness switch for the stubs `createBrowserStubPlugin` generates. The two
+ * phases want opposite behaviour:
+ *
+ * - **Config replay** — skip and warn. An argument-side call like
+ *   `addPlugin(pluginBookshop({…}))` runs before `addPlugin` is reached, so a
+ *   throw escapes the config function and loses every helper below that line.
+ * - **Render time** — throw. That's the documented signal to add a
+ *   `pluginOptions.liquid.<kind>` override, named by `enhanceLiquidError`.
+ *
+ * `collect-config.mjs` flips it once the mirror finishes, and the bundle awaits
+ * that before publishing components, so the phases can't overlap.
+ */
+
+import { log, warnOnce } from "../../liquid/logger.mjs";
+import { createInertValue } from "./inert.mjs";
+
+/**
+ * This plugin's own Eleventy entry — the one entry in `ALWAYS_STUBBED`. Every
+ * config calls it via `addPlugin`, and the browser bundle registers its helpers
+ * itself, so skipping it is expected and there's nothing to act on.
+ */
+const SELF_SPECIFIER = "@cloudcannon/editable-regions/eleventy";
+
+let strict = false;
+
+/** Called by the mirror once every helper has been registered. */
+export function setStubsStrict() {
+	strict = true;
+}
+
+/**
+ * @param {string} specifier - The stubbed module, e.g. `"node:fs"`
+ * @param {"called" | "constructed"} verb
+ * @returns {any} An inert stand-in, while we're still replaying the config
+ */
+export function onStubInvoked(specifier, verb) {
+	if (strict) {
+		throw new Error(
+			`editable-regions: "${specifier}" was ${verb} in the browser ` +
+				"live-editing bundle. It's a Node/build-time module with no browser " +
+				"equivalent — provide an override via pluginOptions.liquid.<kind>.",
+		);
+	}
+
+	if (specifier === SELF_SPECIFIER) {
+		log(
+			`[editable-regions] "${specifier}" was ${verb} and skipped, as expected.`,
+		);
+	} else {
+		warnOnce(
+			`eleventy-stub:${specifier}`,
+			`[editable-regions] "${specifier}" was ${verb} while replaying your ` +
+				"Eleventy config for live editing. It's a Node/build-time module, so " +
+				"the call was skipped and the rest of the config still mirrored. If a " +
+				"filter or shortcode is missing from the editor, this is the reason.",
+		);
+	}
+
+	return createInertValue();
+}

package/integrations/eleventy/index.cjs

@@ -1 +1,28 @@
-module.exports = require("./index.mjs").default;
+// Node can `require()` an ES module from v20.19 / v22.12 onward, so this stays
+// a re-export. Older runtimes throw a bare ERR_REQUIRE_ESM naming neither this
+// package nor a way out — translate it.
+
+/** @type {any} */
+let editableRegionsPlugin;
+
+try {
+	editableRegionsPlugin = require("./index.mjs").default;
+} catch (err) {
+	const code = /** @type {{ code?: string } | undefined} */ (err)?.code;
+	if (code !== "ERR_REQUIRE_ESM") throw err;
+
+	throw new Error(
+		"@cloudcannon/editable-regions/eleventy is an ES module, and Node " +
+			`${process.version} can't \`require()\` one (needs v20.19+ or v22.12+).` +
+			"\n\nEither upgrade Node, or load the plugin with a dynamic import from " +
+			"an async Eleventy config:\n\n" +
+			"  module.exports = async function (eleventyConfig) {\n" +
+			"    const { default: editableRegions } = await import(\n" +
+			'      "@cloudcannon/editable-regions/eleventy"\n' +
+			"    );\n" +
+			"    eleventyConfig.addPlugin(editableRegions);\n" +
+			"  };\n",
+	);
+}
+
+module.exports = editableRegionsPlugin;