@cloudcannon/editable-regions 0.0.16 → 0.0.18

package/integrations/liquid/shortcodes.mjs

@@ -1,92 +1,29 @@
-/**
- * Shortcode-to-LiquidJS-Tag wrapper utilities.
- * Converts Eleventy-style shortcode functions into LiquidJS custom tags.
- *
- * Eleventy shortcodes: simple functions that return HTML
- * LiquidJS tags: objects with parse() and render() methods
- */
+// Wraps Eleventy-style shortcode functions (return a string) as LiquidJS
+// custom tags (objects with parse/render).
 
 import { evalToken, Tokenizer, toPromise } from "liquidjs";
 import { group, groupEnd, log } from "./logger.mjs";
 
 /**
- * Parses comma-separated arguments from a tag's args string.
- * Handles quoted strings and variable references.
- *
- * @param {string} argsString - Raw arguments string from tagToken.args
- * @param {any} operatorsTrie - Liquid options operatorsTrie
- * @returns {any[]} Array of parsed tokens
- */
-function parseArgs(argsString, operatorsTrie) {
-	if (!argsString || !argsString.trim()) {
-		return [];
-	}
-
-	const tokenizer = new Tokenizer(argsString, operatorsTrie);
-	const tokens = [];
-
-	while (true) {
-		tokenizer.skipBlank();
-		const token = tokenizer.readValue();
-		if (!token) break;
-		tokens.push(token);
-
-		tokenizer.skipBlank();
-		if (tokenizer.peek() === ",") {
-			tokenizer.advance();
-		} else {
-			break;
-		}
-	}
-
-	return tokens;
-}
-
-/**
- * Evaluates parsed tokens against the render context.
- *
- * @param {any[]} tokens - Array of parsed tokens
- * @param {any} context - LiquidJS render context
- * @returns {Promise<any[]>} Array of evaluated values
- */
-async function evaluateArgs(tokens, context) {
-	const values = [];
-	for (const token of tokens) {
-		const value = await toPromise(evalToken(token, context));
-		values.push(value);
-	}
-	return values;
-}
-
-/**
- * Creates a LiquidJS tag implementation for a regular (non-paired) shortcode.
- *
  * Usage: {% shortcodeName arg1, arg2, "literal" %}
  *
- * @param {any} shortcodeFn - The shortcode function (arg1, arg2, ...) => string
- * @param {string} shortcodeName - The shortcode name for logging
- * @returns {import('liquidjs/dist/template/tag-options-adapter').TagImplOptions} LiquidJS tag implementation
+ * @param {string} shortcodeName
+ * @param {any} shortcodeFn
+ * @returns {import('liquidjs/dist/template/tag-options-adapter').TagImplOptions}
  */
-export function createShortcodeTag(shortcodeFn, shortcodeName) {
+export function createShortcodeTag(shortcodeName, shortcodeFn) {
 	/** @type {any} */
 	const tag = {
-		/**
-		 * @param {any} tagToken - The tag token from LiquidJS parser
-		 */
-		parse(tagToken) {
+		parse(/** @type {any} */ tagToken) {
 			this.argTokens = parseArgs(
 				tagToken.args,
 				this.liquid.options.operatorsTrie,
 			);
 		},
 
-		/**
-		 * @param {any} context - The LiquidJS render context
-		 */
-		async render(context) {
-			log(`Executing shortcode "${shortcodeName}"`);
+		async render(/** @type {any} */ context) {
 			const args = await evaluateArgs(this.argTokens, context);
-			log("Shortcode args:", args);
+			log(`Shortcode "${shortcodeName}" args:`, args);
 			const result = await shortcodeFn(...args);
 			log("Shortcode returned:", result?.substring?.(0, 100) || result);
 			return result ?? "";
@@ -96,64 +33,44 @@ export function createShortcodeTag(shortcodeFn, shortcodeName) {
 }
 
 /**
- * Creates a LiquidJS tag implementation for a paired shortcode.
- *
  * Usage: {% shortcodeName arg1 %}content{% endshortcodeName %}
  *
- * @param {string} tagName - The shortcode/tag name (needed to find end tag)
- * @param {any} shortcodeFn - The shortcode function (content, arg1, ...) => string
- * @returns {import('liquidjs/dist/template/tag-options-adapter').TagImplOptions} LiquidJS tag implementation
+ * @param {string} tagName
+ * @param {any} shortcodeFn
+ * @returns {import('liquidjs/dist/template/tag-options-adapter').TagImplOptions}
  */
 export function createPairedShortcodeTag(tagName, shortcodeFn) {
 	const endTagName = `end${tagName}`;
 
 	/** @type {any} */
 	const tag = {
-		/**
-		 * @param {any} tagToken - The tag token from LiquidJS parser
-		 * @param {any} remainTokens - Remaining tokens to parse
-		 */
-		parse(tagToken, remainTokens) {
+		parse(/** @type {any} */ tagToken, /** @type {any} */ remainTokens) {
 			this.argTokens = parseArgs(
 				tagToken.args,
 				this.liquid.options.operatorsTrie,
 			);
 			this.templates = [];
 
-			// Consume tokens until we find the end tag
 			while (remainTokens.length) {
 				const token = remainTokens.shift();
-
-				// Check if this is our end tag
-				if (token.name === endTagName) {
-					break;
-				}
-
-				// Parse this token into a template and add to our templates
+				if (token.name === endTagName) break;
 				const template = this.liquid.parser.parseToken(token, remainTokens);
 				this.templates.push(template);
 			}
 		},
 
-		/**
-		 * @param {any} context - The LiquidJS render context
-		 */
-		async render(context) {
+		async render(/** @type {any} */ context) {
 			group(`Paired shortcode "${tagName}"`);
-			log("Inner templates to render:", this.templates.length);
 
-			// Render the content between the tags
-			// NOTE: renderTemplates returns a generator, must use toPromise() to resolve it
+			// renderTemplates returns a generator — toPromise resolves it.
 			const content = await toPromise(
 				this.liquid.renderer.renderTemplates(this.templates, context),
 			);
 			log("Content resolved:", content);
 
-			// Evaluate arguments
 			const args = await evaluateArgs(this.argTokens, context);
 			log("Args:", args);
 
-			// Call shortcode with content as first argument, then other args
 			const result = await shortcodeFn(content, ...args);
 			log("Final HTML:", result?.substring?.(0, 100) || result);
 			groupEnd();
@@ -163,3 +80,49 @@ export function createPairedShortcodeTag(tagName, shortcodeFn) {
 	};
 	return tag;
 }
+
+/**
+ * Parses comma-separated tag arguments (quoted strings and variable refs).
+ *
+ * @param {string} argsString
+ * @param {any} operatorsTrie
+ * @returns {any[]}
+ */
+export function parseArgs(argsString, operatorsTrie) {
+	if (!argsString?.trim()) {
+		return [];
+	}
+
+	const tokenizer = new Tokenizer(argsString, operatorsTrie);
+	const tokens = [];
+
+	while (true) {
+		tokenizer.skipBlank();
+		const token = tokenizer.readValue();
+		if (!token) break;
+		tokens.push(token);
+
+		tokenizer.skipBlank();
+		if (tokenizer.peek() === ",") {
+			tokenizer.advance();
+		} else {
+			break;
+		}
+	}
+
+	return tokens;
+}
+
+/**
+ * @param {any[]} tokens
+ * @param {any} context
+ * @returns {Promise<any[]>}
+ */
+export async function evaluateArgs(tokens, context) {
+	const values = [];
+	for (const token of tokens) {
+		const value = await toPromise(evalToken(token, context));
+		values.push(value);
+	}
+	return values;
+}

package/integrations/react.mjs

@@ -4,19 +4,15 @@ import { createRoot } from "react-dom/client";
 import { addEditableComponentRenderer } from "../helpers/cloudcannon.mjs";
 
 /**
- * Registers a React component with the CloudCannon component system.
- * Creates a wrapper that renders the React component to an HTMLElement.
+ * Registers a React component, wrapping it to render to an HTMLElement.
  *
- * @param {string} key - Unique identifier for the component
- * @param {any} component - The React component function to register
- * @returns {void}
+ * @param {string} key
+ * @param {any} component
  */
 export const registerReactComponent = (key, component) => {
 	/**
-	 * Wrapper function that renders the React component to an HTMLElement.
-	 *
-	 * @param {any} props - Props to pass to the React component
-	 * @returns {HTMLElement} The rendered component as an HTMLElement
+	 * @param {any} props
+	 * @returns {HTMLElement}
 	 */
 	const wrappedComponent = (props) => {
 		const reactNode = createElement(component, props, null);

package/nodes/editable-component.ts

@@ -215,6 +215,12 @@ export default class EditableComponent extends Editable {
 				continue;
 			}
 
+			// Both children are the same subclass (node/element) but are of different types (e.g. text -> comment)
+			if (renderChild.nodeName !== targetChild.nodeName) {
+				targetChild.replaceWith(renderChild);
+				continue;
+			}
+
 			// Both existing and rendered children are nodes (i.e. some text)
 			if (
 				!(renderChild instanceof Element) &&
@@ -225,12 +231,6 @@ export default class EditableComponent extends Editable {
 				continue;
 			}
 
-			// Both children are elements but are different types
-			if (renderChild.nodeName !== targetChild.nodeName) {
-				targetChild.replaceWith(renderChild);
-				continue;
-			}
-
 			// Both existing and rendered children are the same kind of element, and neither is editable
 			if (!isEditableElement(renderChild) && !isEditableElement(targetChild)) {
 				// Update the existing element to match the rendered element and recurse their subtrees

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cloudcannon/editable-regions",
-	"version": "0.0.16",
+	"version": "0.0.18",
 	"type": "module",
 	"description": "Visual Editing for the CloudCannon CMS.",
 	"keywords": [
@@ -58,21 +58,32 @@
 			"default": "./integrations/astro/svelte-renderer.mjs"
 		},
 		"./liquid": "./integrations/liquid/index.mjs",
-		"./eleventy": "./integrations/eleventy.mjs",
+		"./eleventy": {
+			"require": {
+				"types": "./types/eleventy.d.cts",
+				"default": "./integrations/eleventy/index.cjs"
+			},
+			"import": {
+				"types": "./types/eleventy.d.ts",
+				"default": "./integrations/eleventy/index.mjs"
+			}
+		},
+		"./eleventy/browser": "./integrations/eleventy/browser/index.mjs",
 		"./internal/components": "./components/index.js",
 		"./internal/styles": "./styles/index.js"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "2.5.0",
-		"@cloudcannon/visual-editor-api": "0.0.18",
+		"@biomejs/biome": "2.5.3",
+		"@cloudcannon/visual-editor-api": "0.0.19",
 		"@sindresorhus/slugify": "3.0.0",
 		"@types/js-beautify": "1.14.3",
-		"@types/node": "25.9.4",
+		"@types/node": "26.1.1",
 		"@types/react": "19.2.17",
 		"@types/react-dom": "19.2.3",
-		"astro": "6.4.8",
-		"js-beautify": "1.15.4",
-		"liquidjs": "10.27.0",
+		"astro": "7.0.7",
+		"js-beautify": "2.0.3",
+		"liquidjs": "10.27.2",
+		"slugify": "1.6.9",
 		"typescript": "6.0.3"
 	},
 	"dependencies": {

package/types/eleventy.d.cts

@@ -0,0 +1,20 @@
+/**
+ * CommonJS declaration shape for `@cloudcannon/editable-regions/eleventy`.
+ * Mirrors the ESM `.d.ts` but uses `export = ` so `require()` resolves to
+ * the function directly. Shared interfaces are re-imported from the ESM
+ * declarations to keep them in one place.
+ */
+import type {
+	LiquidOptions,
+	NormalizedPluginOptions,
+	PluginOptions,
+} from "./eleventy";
+
+declare function editableRegions(
+	eleventyConfig: any,
+	pluginOptions: PluginOptions,
+): void;
+declare namespace editableRegions {
+	export { LiquidOptions, NormalizedPluginOptions, PluginOptions };
+}
+export = editableRegions;

package/types/eleventy.d.ts

@@ -0,0 +1,81 @@
+export interface LiquidOptions {
+	/** Directories to walk for component templates. Defaults to `[directories.includes, directories.input]`. */
+	componentDirs?: string[];
+	/** Template file extensions to bundle. Defaults to `[".liquid", ".html"]`. */
+	extensions?: string[];
+	/** Directory names to skip when walking. Defaults to `[directories.output, "node_modules"]`. */
+	ignoreDirectories?: string[];
+	/** Map of component name → module path. Wins over the auto-discovered components. */
+	components?: Record<string, string>;
+	/**
+	 * Path to the Eleventy config file, used to auto-mirror its helpers into
+	 * the browser bundle. Resolved relative to the project root. Defaults to
+	 * the first of 11ty's standard names that exists (`.eleventy.js`,
+	 * `eleventy.config.{js,mjs,cjs}`). Set this only if you run Eleventy with a
+	 * non-default `--config` path.
+	 */
+	configPath?: string;
+	/**
+	 * Extra bare module specifiers to stub out of the browser bundle, on top of
+	 * the 11ty toolchain and Node built-ins (always stubbed). Use this when the
+	 * config imports a native/Node-only package (e.g. `sharp`) that no
+	 * browser-bound helper actually calls at render time but that would
+	 * otherwise break bundling.
+	 */
+	browserStub?: string[];
+	/**
+	 * Browser-side filter overrides: filter name → module path. The config's
+	 * filters are auto-mirrored into the browser by bundling the real config,
+	 * so closures and imports survive. Use an override only when a filter
+	 * genuinely can't run in the browser (it calls a Node API at render time);
+	 * the override replaces it and its name is excluded from the mirror.
+	 */
+	filters?: Record<string, string>;
+	/** Browser-side shortcode overrides. Same auto-mirror + override model as `filters`. */
+	shortcodes?: Record<string, string>;
+	/** Browser-side paired-shortcode overrides. Same auto-mirror + override model as `filters`. */
+	pairedShortcodes?: Record<string, string>;
+	/**
+	 * Browser-side custom Liquid tag overrides: tag name → module path
+	 * (default-exporting a `(engine) => { parse, render }` factory). Tags are
+	 * auto-mirrored from the config like filters/shortcodes; supply an override
+	 * here only for a tag that can't run in the browser as written.
+	 */
+	tags?: Record<string, string>;
+}
+
+export interface PluginOptions {
+	/** Output path for the generated bundle. Defaults to `register-components.js` inside Eleventy's `dir.output`. */
+	output?: string;
+	/** Enable verbose browser logging. */
+	verbose?: boolean;
+	/**
+	 * Liquid is the plugin's default language and is enabled implicitly.
+	 * Pass `false` to disable, `true` for defaults, or an options object
+	 * for customisation.
+	 */
+	liquid?: LiquidOptions | boolean;
+	/**
+	 * Extra globals to expose to editor-rendered templates, mirroring whatever
+	 * global data your build already provides (via `_data/` or
+	 * `addGlobalData`). Embedded into the bundle at build time, so values must
+	 * be JSON-serialisable. To surface env vars, pass them in explicitly, e.g.
+	 * `globals: { env: { API_BASE: process.env.API_BASE } }`, and register the
+	 * same data server-side so the editor and build agree. Don't include secrets.
+	 */
+	globals?: Record<string, unknown>;
+}
+
+/**
+ * Internal shape after `normalizePluginOptions`: each supported language is
+ * resolved to either an options object (enabled) or `false` (disabled). Same
+ * shape as `PluginOptions` aside from that resolution.
+ */
+export type NormalizedPluginOptions = Omit<PluginOptions, "liquid"> & {
+	liquid: LiquidOptions | false;
+};
+
+export default function (
+	eleventyConfig: any,
+	pluginOptions: PluginOptions,
+): void;

package/types/liquid.d.ts

@@ -1,33 +1,29 @@
 declare module "@cloudcannon/editable-regions/liquid" {
-	import type { Liquid } from "liquidjs";
-
-	interface LiquidConfig {
-		componentDirs?: string[];
-	}
+	import type { Liquid, LiquidOptions } from "liquidjs";
 
 	export function setVerbose(value: boolean): void;
 	export function log(...args: any[]): void;
 	export function group(label?: string): void;
 	export function groupEnd(): void;
 
-	export function configureLiquid(options: LiquidConfig): void;
-	export function getLiquidEngine(options?: Record<string, any>): Liquid;
+	export function createSharedLiquidEngine(options?: LiquidOptions): Liquid;
 	export function registerLiquidComponent(key: string, contents: string): void;
+	export function initComponentProxy(): void;
 
-	export function createBindIncludeTag(liquidEngine: Liquid): {
+	export function createIncludeWithTag(liquidEngine: Liquid): {
 		parse(tagToken: any): void;
 		render(context: any): Promise<string>;
 	};
 
-	export function registerCustomFilter(
+	export function registerFilter(
 		name: string,
 		fn: (...args: any[]) => any,
 	): void;
-	export function registerCustomShortcode(
+	export function registerShortcode(
 		name: string,
 		fn: (...args: any[]) => any,
 	): void;
-	export function registerCustomPairedShortcode(
+	export function registerPairedShortcode(
 		name: string,
 		fn: (...args: any[]) => any,
 	): void;
@@ -35,6 +31,13 @@ declare module "@cloudcannon/editable-regions/liquid" {
 		name: string,
 		factory: (liquidEngine: Liquid) => any,
 	): void;
+	export function registerProcessEnv(env: Record<string, string>): void;
+	export function registerEleventyData(data: {
+		version: string;
+		generator: string;
+		env: { runMode: string; source: string };
+		directories: Record<string, string>;
+	}): void;
 }
 
 /** Window globals used by the liquid integration */
@@ -46,7 +49,7 @@ declare global {
 			(props: Record<string, any>) => Promise<HTMLElement>
 		>;
 		/** Liquid template files keyed by path */
-		cc_files?: Record<string, string>;
+		cc_liquid_files?: Record<string, string>;
 	}
 }