camox 0.43.0 → 0.45.0

package/dist/core/createLayout.js

@@ -1,26 +1,30 @@
+import { notFound } from "./notFound.js";
+import { useOptionalCamoxApp } from "../features/provider/components/CamoxAppContext.js";
+import { useBlockEditingRuntime } from "./editing/BlockEditingRuntime.js";
 import { BlockErrorBoundary } from "../features/preview/components/BlockErrorBoundary.js";
+import { asCollectionItem, fieldPlainText } from "./recordItem.js";
+import { RecordScope } from "./lib/recordScope.js";
 import { c } from "react/compiler-runtime";
 import * as React from "react";
 import { Fragment, jsx } from "react/jsx-runtime";
 
 //#region src/core/createLayout.tsx
+const INITIAL_LAYOUT_ONLY_ERROR = "❌ Camox: blocks in `blocks.initial` must NOT be `layoutOnly: true` — `initial` is for page-content blocks. Remove `layoutOnly: true` from this block's `createBlock` options.";
 function createLayoutDefinition(options) {
 	if (options.kind === "singleton" && !/^[\w-]+(?:\.[\w-]+)*$/.test(options.id)) throw new Error(`Singleton layouts require a fixed file route: ${options.id}`);
 	if (options.kind && options.kind !== "curated" && options.blocks.initial) throw new Error("Code-owned layouts cannot define initial page blocks");
+	if (options.routes && options.kind !== "derived") throw new Error(`Only derived layouts can define routes: ${options.id}`);
+	if (options.toMarkdown && (options.kind ?? "curated") === "curated") throw new Error(`Curated layouts cannot define toMarkdown: ${options.id}`);
 	const LayoutContext = React.createContext(null);
 	const beforeBlocks = options.blocks.before;
 	const afterBlocks = options.blocks.after;
 	const initialBlocks = options.blocks.initial;
 	const BeforeBlocks = () => {
-		const $ = c(5);
-		if ($[0] !== "776e504f06a16915ba8008212a5b0af4dec7762a3d0b05161ac1048bec619433") {
-			for (let $i = 0; $i < 5; $i += 1) $[$i] = Symbol.for("react.memo_cache_sentinel");
-			$[0] = "776e504f06a16915ba8008212a5b0af4dec7762a3d0b05161ac1048bec619433";
-		}
+		const $ = c(4);
 		const ctx = React.use(LayoutContext);
 		if (!ctx) throw new Error(`Layout "${options.id}" BeforeBlocks must be rendered inside its Provider`);
 		let t0;
-		if ($[1] !== ctx) {
+		if ($[0] !== ctx) {
 			t0 = beforeBlocks.map((block, i) => {
 				const blockData = ctx.layoutBlocks[block._internal.id];
 				if (!blockData) return null;
@@ -36,28 +40,24 @@ function createLayoutDefinition(options) {
 					})
 				}, block._internal.id);
 			});
-			$[1] = ctx;
-			$[2] = t0;
-		} else t0 = $[2];
+			$[0] = ctx;
+			$[1] = t0;
+		} else t0 = $[1];
 		let t1;
-		if ($[3] !== t0) {
+		if ($[2] !== t0) {
 			t1 = /* @__PURE__ */ jsx(Fragment, { children: t0 });
-			$[3] = t0;
-			$[4] = t1;
-		} else t1 = $[4];
+			$[2] = t0;
+			$[3] = t1;
+		} else t1 = $[3];
 		return t1;
 	};
 	BeforeBlocks.displayName = `LayoutBeforeBlocks(${options.id})`;
 	const AfterBlocks = () => {
-		const $ = c(5);
-		if ($[0] !== "776e504f06a16915ba8008212a5b0af4dec7762a3d0b05161ac1048bec619433") {
-			for (let $i = 0; $i < 5; $i += 1) $[$i] = Symbol.for("react.memo_cache_sentinel");
-			$[0] = "776e504f06a16915ba8008212a5b0af4dec7762a3d0b05161ac1048bec619433";
-		}
+		const $ = c(4);
 		const ctx = React.use(LayoutContext);
 		if (!ctx) throw new Error(`Layout "${options.id}" AfterBlocks must be rendered inside its Provider`);
 		let t0;
-		if ($[1] !== ctx) {
+		if ($[0] !== ctx) {
 			t0 = afterBlocks.map((block, i) => {
 				const blockData = ctx.layoutBlocks[block._internal.id];
 				if (!blockData) return null;
@@ -73,48 +73,106 @@ function createLayoutDefinition(options) {
 					})
 				}, block._internal.id);
 			});
-			$[1] = ctx;
-			$[2] = t0;
-		} else t0 = $[2];
+			$[0] = ctx;
+			$[1] = t0;
+		} else t0 = $[1];
 		let t1;
-		if ($[3] !== t0) {
+		if ($[2] !== t0) {
 			t1 = /* @__PURE__ */ jsx(Fragment, { children: t0 });
-			$[3] = t0;
-			$[4] = t1;
-		} else t1 = $[4];
+			$[2] = t0;
+			$[3] = t1;
+		} else t1 = $[3];
 		return t1;
 	};
 	AfterBlocks.displayName = `LayoutAfterBlocks(${options.id})`;
 	const Provider = (t0) => {
-		const $ = c(7);
-		if ($[0] !== "776e504f06a16915ba8008212a5b0af4dec7762a3d0b05161ac1048bec619433") {
-			for (let $i = 0; $i < 7; $i += 1) $[$i] = Symbol.for("react.memo_cache_sentinel");
-			$[0] = "776e504f06a16915ba8008212a5b0af4dec7762a3d0b05161ac1048bec619433";
-		}
-		const { layoutBlocks, children, data } = t0;
+		const $ = c(6);
+		const { layoutBlocks, children, result } = t0;
 		let t1;
-		if ($[1] !== data || $[2] !== layoutBlocks) {
+		if ($[0] !== layoutBlocks || $[1] !== result) {
 			t1 = {
 				layoutBlocks,
-				data
+				result
 			};
-			$[1] = data;
-			$[2] = layoutBlocks;
-			$[3] = t1;
-		} else t1 = $[3];
+			$[0] = layoutBlocks;
+			$[1] = result;
+			$[2] = t1;
+		} else t1 = $[2];
 		const value = t1;
 		let t2;
-		if ($[4] !== children || $[5] !== value) {
+		if ($[3] !== children || $[4] !== value) {
 			t2 = /* @__PURE__ */ jsx(LayoutContext.Provider, {
 				value,
 				children
 			});
-			$[4] = children;
-			$[5] = value;
-			$[6] = t2;
-		} else t2 = $[6];
+			$[3] = children;
+			$[4] = value;
+			$[5] = t2;
+		} else t2 = $[5];
 		return t2;
 	};
+	const Item = (t0) => {
+		const $ = c(6);
+		const { children } = t0;
+		const context = React.use(LayoutContext);
+		const app = useOptionalCamoxApp();
+		const editingRuntime = useBlockEditingRuntime();
+		if (!context) throw new Error(`Layout "${options.id}" Item must be rendered inside its Provider`);
+		let t1;
+		let t2;
+		if ($[0] !== app || $[1] !== children || $[2] !== context.result || $[3] !== editingRuntime) {
+			t2 = Symbol.for("react.early_return_sentinel");
+			bb0: {
+				const result = asCollectionItem(context.result);
+				if (!result) {
+					t2 = null;
+					break bb0;
+				}
+				const collection = app?.getCollectionById(result.collectionId);
+				if (!collection) {
+					t2 = null;
+					break bb0;
+				}
+				const { contentSchema, label } = collection._internal;
+				const { id, content, references } = result.data;
+				const readOnly = /* @__PURE__ */ jsx(RecordScope, {
+					record: {
+						id,
+						label: fieldPlainText(content[label]),
+						content,
+						references
+					},
+					properties: contentSchema.properties,
+					hop: 1,
+					children
+				});
+				if (!editingRuntime?.renderLayoutItem) {
+					t2 = readOnly;
+					break bb0;
+				}
+				t1 = editingRuntime.renderLayoutItem({
+					collectionId: result.collectionId,
+					labelField: label,
+					properties: contentSchema.properties,
+					record: result.data,
+					children,
+					fallback: readOnly
+				});
+			}
+			$[0] = app;
+			$[1] = children;
+			$[2] = context.result;
+			$[3] = editingRuntime;
+			$[4] = t1;
+			$[5] = t2;
+		} else {
+			t1 = $[4];
+			t2 = $[5];
+		}
+		if (t2 !== Symbol.for("react.early_return_sentinel")) return t2;
+		return t1;
+	};
+	Item.displayName = `LayoutItem(${options.id})`;
 	const blockDefinitions = [...beforeBlocks.map((block) => {
 		const bundle = block._internal.getInitialBundle();
 		return {
@@ -122,7 +180,7 @@ function createLayoutDefinition(options) {
 			content: bundle.content,
 			settings: bundle.settings,
 			repeatableItems: bundle.repeatableItems,
-			placement: "before"
+			slot: "before"
 		};
 	}), ...afterBlocks.map((block) => {
 		const bundle = block._internal.getInitialBundle();
@@ -131,7 +189,7 @@ function createLayoutDefinition(options) {
 			content: bundle.content,
 			settings: bundle.settings,
 			repeatableItems: bundle.repeatableItems,
-			placement: "after"
+			slot: "after"
 		};
 	})];
 	const buildOgImage = options.buildOgImage ? async (params) => {
@@ -142,7 +200,9 @@ function createLayoutDefinition(options) {
 			height: 630
 		});
 	} : void 0;
-	const initialBlockBundles = initialBlocks?.map((block) => {
+	const loadInitialBlockBundles = initialBlocks && (() => Promise.all(initialBlocks.map(async (load) => {
+		const { block } = await load();
+		if (block._internal.layoutOnly) throw new Error(`${INITIAL_LAYOUT_ONLY_ERROR} (block "${block._internal.id}")`);
 		const bundle = block._internal.getInitialBundle();
 		return {
 			type: block._internal.id,
@@ -150,25 +210,30 @@ function createLayoutDefinition(options) {
 			settings: bundle.settings,
 			repeatableItems: bundle.repeatableItems
 		};
-	});
+	})));
 	return {
 		BeforeBlocks,
 		AfterBlocks,
+		Item,
 		useData() {
 			const context = React.use(LayoutContext);
 			if (!context) throw new Error(`Layout "${options.id}" useData must be rendered inside its Provider`);
-			return context.data;
+			return context.result?.data;
 		},
 		_internal: {
 			id: options.id,
 			kind: options.kind ?? "curated",
 			loader: options.loader,
+			routes: options.routes,
+			recordPages: options.recordPages,
 			title: options.title,
 			description: options.description,
 			buildMetaTitle: options.buildMetaTitle,
+			buildMetaDescription: options.buildMetaDescription,
+			toMarkdown: options.toMarkdown,
 			buildOgImage,
 			blockDefinitions,
-			initialBlockBundles,
+			loadInitialBlockBundles,
 			component: options.component,
 			Provider
 		}
@@ -181,13 +246,6 @@ function createLayout(idOrOptions) {
 		id: idOrOptions
 	});
 }
-/** Signal a missing derived page; other loader failures remain server errors. */
-function notFound() {
-	return Object.assign(/* @__PURE__ */ new Error("Page not found"), {
-		status: 404,
-		code: "NOT_FOUND"
-	});
-}
 
 //#endregion
 export { createLayout, notFound };

package/dist/core/defineDocument.d.ts

@@ -1,7 +1,5 @@
 import { UseHeadInput } from "unhead/types";
-
 //#region src/core/defineDocument.d.ts
-type CamoxDocument = UseHeadInput;
-declare function defineDocument(document: CamoxDocument): CamoxDocument;
-//#endregion
-export { CamoxDocument, defineDocument };
+export type CamoxDocument = UseHeadInput;
+export declare function defineDocument(document: CamoxDocument): CamoxDocument;
+//#endregion

package/dist/core/derivedRoutes.js

@@ -1,3 +1,5 @@
+import { asCollectionItem } from "./recordItem.js";
+
 //#region src/core/derivedRoutes.ts
 function routeSegments(id) {
 	return id.split(".");
@@ -31,6 +33,52 @@ function matchDerivedLayout(layouts, pathname) {
 	}
 	return null;
 }
+/** Builds the path of one discovered page, rejecting params the route could not match. */
+function derivedLayoutPath(layoutId, params) {
+	const segments = routeSegments(layoutId);
+	const names = segments.filter((s) => s.startsWith("$")).map((s) => s.slice(1));
+	if (!params || typeof params !== "object" || Array.isArray(params)) throw new Error(`Layout "${layoutId}" routes returned an entry without params`);
+	const values = params;
+	const extra = Object.keys(values).find((name) => !names.includes(name));
+	if (extra) throw new Error(`Layout "${layoutId}" routes returned an unknown param "${extra}"`);
+	return `/${segments.map((segment) => {
+		if (!segment.startsWith("$")) return encodeURIComponent(segment);
+		const name = segment.slice(1);
+		const value = values[name];
+		if (typeof value !== "string" || !value || value.includes("/")) throw new Error(`Layout "${layoutId}" routes returned an invalid "${name}" param: ${JSON.stringify(value)}`);
+		return encodeURIComponent(value);
+	}).join("/")}`;
+}
+/** The record a discovery entry names, if its `target` is a record target. */
+function targetRecord(entry) {
+	const target = asCollectionItem(entry?.target);
+	if (typeof target?.id !== "string") return {};
+	return {
+		recordId: target.id,
+		...typeof target.label === "string" && { label: target.label }
+	};
+}
+/**
+* Runs a derived layout's route discovery, keeping the record each page renders. An invalid
+* result throws rather than omitting pages.
+*/
+async function discoverLayoutPages(layout, context) {
+	const { id, routes } = layout._internal;
+	if (!routes) return [];
+	let result;
+	try {
+		result = await routes({ context });
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Layout "${id}" routes failed: ${message}`, { cause: error });
+	}
+	const entries = result?.data;
+	if (!Array.isArray(entries)) throw new Error(`Layout "${id}" routes must return { data: [{ params }] }`);
+	return entries.map((entry) => ({
+		path: derivedLayoutPath(id, entry?.params),
+		...targetRecord(entry)
+	}));
+}
 
 //#endregion
-export { matchDerivedLayout, routeSegments };
+export { derivedLayoutPath, discoverLayoutPages, matchDerivedLayout, routeSegments };

package/dist/core/dom.d.ts

@@ -1,6 +1,7 @@
+import * as React from "react";
 //#region src/core/dom.d.ts
 /** The browsing context that owns a rendered element. */
-interface ElementContext {
+export interface ElementContext {
   document: Document;
   window: Window & typeof globalThis;
 }
@@ -12,6 +13,14 @@ interface ElementContext {
  * Returns null for a missing element or a document without a window. Never
  * falls back to globals. This does not convert objects into the target realm.
  */
-declare function getElementContext(element: Element | null | undefined): ElementContext | null;
-//#endregion
-export { ElementContext, getElementContext };
+export declare function getElementContext(element: Element | null | undefined): ElementContext | null;
+/**
+ * Whether Camox has paused the preview rendering an element, such as a Canvas
+ * frame nobody is looking at. Camox already pauses CSS animations, transitions
+ * and media there; stop JavaScript-driven animation (WebGL, canvas, requestAnimationFrame
+ * loops) while this is true. Always false outside Camox preview.
+ *
+ * The element must render together with the component calling this.
+ */
+export declare function usePreviewPaused(ref: React.RefObject<Element | null>): boolean;
+//#endregion

package/dist/core/dom.js

@@ -1,3 +1,7 @@
+import { PREVIEW_PAUSED_ATTRIBUTE } from "./lib/previewPaused.js";
+import { c } from "react/compiler-runtime";
+import * as React from "react";
+
 //#region src/core/dom.ts
 /**
 * Resolve DOM APIs from an element rather than the component's JavaScript realm.
@@ -17,6 +21,45 @@ function getElementContext(element) {
 		window
 	};
 }
+/**
+* Whether Camox has paused the preview rendering an element, such as a Canvas
+* frame nobody is looking at. Camox already pauses CSS animations, transitions
+* and media there; stop JavaScript-driven animation (WebGL, canvas, requestAnimationFrame
+* loops) while this is true. Always false outside Camox preview.
+*
+* The element must render together with the component calling this.
+*/
+function usePreviewPaused(ref) {
+	const $ = c(4);
+	let t0;
+	if ($[0] !== ref) {
+		t0 = (onChange) => {
+			const root = ref.current?.ownerDocument.documentElement;
+			const Observer = root?.ownerDocument.defaultView?.MutationObserver;
+			if (!root || !Observer) return _temp;
+			const observer = new Observer(onChange);
+			observer.observe(root, {
+				attributes: true,
+				attributeFilter: [PREVIEW_PAUSED_ATTRIBUTE]
+			});
+			return () => observer.disconnect();
+		};
+		$[0] = ref;
+		$[1] = t0;
+	} else t0 = $[1];
+	const subscribe = t0;
+	let t1;
+	if ($[2] !== ref) {
+		t1 = () => !!ref.current?.ownerDocument.documentElement.hasAttribute(PREVIEW_PAUSED_ATTRIBUTE);
+		$[2] = ref;
+		$[3] = t1;
+	} else t1 = $[3];
+	return React.useSyncExternalStore(subscribe, t1, _temp2);
+}
+function _temp2() {
+	return false;
+}
+function _temp() {}
 
 //#endregion
-export { getElementContext };
+export { getElementContext, usePreviewPaused };

package/dist/core/editing/BlockEditingRuntime.d.ts

@@ -0,0 +1,16 @@
+import { LoadedRecord } from "../requestContext.js";
+import * as React from "react";
+//#region src/core/editing/BlockEditingRuntime.d.ts
+/** A record page's record, as `layout.Item` hands it to the editing runtime. */
+export interface LayoutItemProps {
+  collectionId: string;
+  /** The collection's label field. */
+  labelField: string;
+  /** The collection's field schemas. */
+  properties: Record<string, unknown>;
+  record: LoadedRecord;
+  children: (scope: any) => React.ReactNode;
+  /** The read-only rendering, for where the record can't be edited. */
+  fallback: React.ReactNode;
+}
+//#endregion

package/dist/core/editing/BlockEditingRuntime.js

@@ -5,30 +5,21 @@ import { jsx } from "react/jsx-runtime";
 //#region src/core/editing/BlockEditingRuntime.tsx
 const BlockEditingRuntimeContext = React.createContext(null);
 function BlockEditingRuntimeProvider(t0) {
-	const $ = c(4);
-	if ($[0] !== "ad4fc9cc5b1b02b16c68794c8ba79d99d7e878328fdbc5bd08fcf7fbaebb83df") {
-		for (let $i = 0; $i < 4; $i += 1) $[$i] = Symbol.for("react.memo_cache_sentinel");
-		$[0] = "ad4fc9cc5b1b02b16c68794c8ba79d99d7e878328fdbc5bd08fcf7fbaebb83df";
-	}
+	const $ = c(3);
 	const { children, runtime } = t0;
 	let t1;
-	if ($[1] !== children || $[2] !== runtime) {
+	if ($[0] !== children || $[1] !== runtime) {
 		t1 = /* @__PURE__ */ jsx(BlockEditingRuntimeContext.Provider, {
 			value: runtime,
 			children
 		});
-		$[1] = children;
-		$[2] = runtime;
-		$[3] = t1;
-	} else t1 = $[3];
+		$[0] = children;
+		$[1] = runtime;
+		$[2] = t1;
+	} else t1 = $[2];
 	return t1;
 }
 function useBlockEditingRuntime() {
-	const $ = c(1);
-	if ($[0] !== "ad4fc9cc5b1b02b16c68794c8ba79d99d7e878328fdbc5bd08fcf7fbaebb83df") {
-		for (let $i = 0; $i < 1; $i += 1) $[$i] = Symbol.for("react.memo_cache_sentinel");
-		$[0] = "ad4fc9cc5b1b02b16c68794c8ba79d99d7e878328fdbc5bd08fcf7fbaebb83df";
-	}
 	return React.useContext(BlockEditingRuntimeContext);
 }
 

package/dist/core/editing/CompleteBlockEditingRuntime.js

@@ -14,30 +14,39 @@ function getEditableDefinition(options) {
 	return definition;
 }
 function EditableBlock(t0) {
-	const $ = c(6);
-	if ($[0] !== "e1b3ebcb34bc95f5c457074764df3357687300ade86d161e3e1014255268f87d") {
-		for (let $i = 0; $i < 6; $i += 1) $[$i] = Symbol.for("react.memo_cache_sentinel");
-		$[0] = "e1b3ebcb34bc95f5c457074764df3357687300ade86d161e3e1014255268f87d";
-	}
+	const $ = c(5);
 	const { options, props } = t0;
 	let t1;
-	if ($[1] !== options) {
+	if ($[0] !== options) {
 		t1 = getEditableDefinition(options);
-		$[1] = options;
-		$[2] = t1;
-	} else t1 = $[2];
+		$[0] = options;
+		$[1] = t1;
+	} else t1 = $[1];
 	const Component = t1._internal.Component;
 	const t2 = props;
 	let t3;
-	if ($[3] !== Component || $[4] !== t2) {
+	if ($[2] !== Component || $[3] !== t2) {
 		t3 = /* @__PURE__ */ jsx(Component, { ...t2 });
-		$[3] = Component;
-		$[4] = t2;
-		$[5] = t3;
-	} else t3 = $[5];
+		$[2] = Component;
+		$[3] = t2;
+		$[4] = t3;
+	} else t3 = $[4];
 	return t3;
 }
+/** Record pages' records render through the record scope of a block without fields. */
+const layoutItemOptions = {
+	id: "camox-layout-item",
+	title: "",
+	description: "",
+	content: () => ({}),
+	toMarkdown: () => [],
+	component: () => null
+};
 const completeEditingRuntime = {
+	renderLayoutItem(props) {
+		const { LayoutItem } = getEditableDefinition(layoutItemOptions)._internal;
+		return /* @__PURE__ */ jsx(LayoutItem, { ...props });
+	},
 	useSetting(options, name) {
 		return getEditableDefinition(options).useSetting(name);
 	},
@@ -54,21 +63,17 @@ const completeEditingRuntime = {
 	}
 };
 function CompleteBlockEditingRuntimeProvider(t0) {
-	const $ = c(3);
-	if ($[0] !== "e1b3ebcb34bc95f5c457074764df3357687300ade86d161e3e1014255268f87d") {
-		for (let $i = 0; $i < 3; $i += 1) $[$i] = Symbol.for("react.memo_cache_sentinel");
-		$[0] = "e1b3ebcb34bc95f5c457074764df3357687300ade86d161e3e1014255268f87d";
-	}
+	const $ = c(2);
 	const { children } = t0;
 	let t1;
-	if ($[1] !== children) {
+	if ($[0] !== children) {
 		t1 = /* @__PURE__ */ jsx(BlockEditingRuntimeProvider, {
 			runtime: completeEditingRuntime,
 			children
 		});
-		$[1] = children;
-		$[2] = t1;
-	} else t1 = $[2];
+		$[0] = children;
+		$[1] = t1;
+	} else t1 = $[1];
 	return t1;
 }