camox 0.47.0 → 0.51.0

package/dist/core/createApp.d.ts

@@ -3,7 +3,7 @@ import { CamoxDocument } from "./defineDocument.js";
 import { ArtifactRenderProps } from "./lib/artifact.js";
 import { InlineTextStyles } from "./lib/textStyles.js";
 import { ReferenceContent, ReferenceScope } from "./lib/reference.js";
-import { Layout, RecordPages } from "./createLayout.js";
+import { Layout } from "./createLayout.js";
 import { Collection } from "./createCollection.js";
 import { IconValue } from "./lib/iconTypes.js";
 import { ArtifactSource, EmbedURL, FileValue, ImageValue, LinkValue } from "./lib/contentType.js";
@@ -416,17 +416,19 @@ export declare function createApp({ blocks, lazyBlocks, layouts, collections, do
       Component: ({ blockData, mode, isFirstBlock, showAddBlockTop, showAddBlockBottom, addBlockAfterPosition }: BlockComponentProps<{
         [x: string]: unknown;
       }>) => import("react").JSX.Element;
-      LayoutItem: ({ collectionId, labelField, properties, record, children, fallback }: LayoutItemProps) => string | number | bigint | boolean | Iterable<import("react").ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<import("react").ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
+      LayoutItem: ({ collectionId, collection, properties, record, children, fallback }: LayoutItemProps) => string | number | bigint | boolean | Iterable<import("react").ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<import("react").ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
       id: string;
       title: string;
       description: string;
       contentSchema: {
+        toStructuredData?: unknown;
         type: "object";
         title: string;
         description: string;
         properties: Record<string, import("@sinclair/typebox").TSchema>;
         required: string[];
         toMarkdown: string[];
+        toTitle: string;
       };
       settingsSchema: {
         type: "object";
@@ -458,6 +460,7 @@ export declare function createApp({ blocks, lazyBlocks, layouts, collections, do
           settings: Record<string, unknown>;
           slot: null;
           summary: string;
+          title: string;
           position: string;
           createdAt: number;
           updatedAt: number;
@@ -855,17 +858,19 @@ export declare function createApp({ blocks, lazyBlocks, layouts, collections, do
       Component: ({ blockData, mode, isFirstBlock, showAddBlockTop, showAddBlockBottom, addBlockAfterPosition }: BlockComponentProps<{
         [x: string]: unknown;
       }>) => import("react").JSX.Element;
-      LayoutItem: ({ collectionId, labelField, properties, record, children, fallback }: LayoutItemProps) => string | number | bigint | boolean | Iterable<import("react").ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<import("react").ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
+      LayoutItem: ({ collectionId, collection, properties, record, children, fallback }: LayoutItemProps) => string | number | bigint | boolean | Iterable<import("react").ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<import("react").ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
       id: string;
       title: string;
       description: string;
       contentSchema: {
+        toStructuredData?: unknown;
         type: "object";
         title: string;
         description: string;
         properties: Record<string, import("@sinclair/typebox").TSchema>;
         required: string[];
         toMarkdown: string[];
+        toTitle: string;
       };
       settingsSchema: {
         type: "object";
@@ -897,6 +902,7 @@ export declare function createApp({ blocks, lazyBlocks, layouts, collections, do
           settings: Record<string, unknown>;
           slot: null;
           summary: string;
+          title: string;
           position: string;
           createdAt: number;
           updatedAt: number;
@@ -925,12 +931,14 @@ export declare function createApp({ blocks, lazyBlocks, layouts, collections, do
       title: string;
       description: string;
       contentSchema: {
+        toStructuredData?: unknown;
         type: "object";
         title: string;
         description: string;
         properties: Record<string, import("@sinclair/typebox").TSchema>;
         required: string[];
         toMarkdown: string[];
+        toTitle: string;
       };
       settingsSchema: {
         type: "object";
@@ -947,7 +955,10 @@ export declare function createApp({ blocks, lazyBlocks, layouts, collections, do
       synced: boolean;
     }[];
     layouts: {
-      recordPages?: RecordPages | undefined;
+      recordPages?: {
+        collectionId: string;
+        field: string;
+      } | undefined;
       layoutId: string;
       kind: "curated" | "derived" | "singleton";
       description: string;
@@ -978,11 +989,13 @@ export declare function createApp({ blocks, lazyBlocks, layouts, collections, do
       })[];
     }[];
     collections: {
+      contentSchema: any;
+      toStructuredData?: Record<string, unknown> | undefined;
       collectionId: string;
       title: string;
       description: string;
-      label: string;
-      contentSchema: any;
+      toTitle: string;
+      toDescription: string | null;
     }[];
     homepage: {
       layoutId: string;

package/dist/core/createApp.js

@@ -134,7 +134,10 @@ function createApp({ blocks, lazyBlocks = {}, layouts = [], collections = [], do
 				kind: layout._internal.kind,
 				description: layout._internal.description,
 				blocks: layout._internal.blockDefinitions,
-				...layout._internal.recordPages && { recordPages: layout._internal.recordPages }
+				...layout._internal.recordPages && { recordPages: {
+					collectionId: layout._internal.recordPages.collectionId,
+					field: layout._internal.recordPages.field
+				} }
 			}));
 			const typesUsedInLayouts = new Set(layoutDefinitions.flatMap((layout) => layout.blocks.map((block) => block.type)));
 			return {
@@ -154,7 +157,9 @@ function createApp({ blocks, lazyBlocks = {}, layouts = [], collections = [], do
 					collectionId: _internal.id,
 					title: _internal.title,
 					description: _internal.description,
-					label: _internal.label,
+					toTitle: _internal.toTitle,
+					toDescription: _internal.toDescription,
+					..._internal.toStructuredData && { toStructuredData: _internal.toStructuredData },
 					contentSchema: JSON.parse(JSON.stringify(_internal.contentSchema))
 				})),
 				homepage: await getHomepage()

package/dist/core/createBlock.js

@@ -1,6 +1,6 @@
 import { artifactFrameProps, artifactStandInProps, isArtifactSource } from "./lib/artifact.js";
 import { artifactData } from "./lib/artifactData.js";
-import { resolveBlockFields, resolveToMarkdown } from "./lib/contentType.js";
+import { resolveBlockFields, resolveToMarkdown, resolveToStructuredData, resolveToTitle } from "./lib/contentType.js";
 import { useProjectUuid } from "../lib/auth.js";
 import { useLocation, useNavigate } from "../features/navigation/navigation.js";
 import { useOptionalCamoxApp } from "../features/provider/components/CamoxAppContext.js";
@@ -96,6 +96,7 @@ function buildPeekItems(properties, blockId, parentItemId, content, items, count
 				content: itemContent,
 				settings: property.defaultItemSettings ? { ...property.defaultItemSettings } : null,
 				summary: "",
+				title: "",
 				position,
 				createdAt: 0,
 				updatedAt: 0,
@@ -434,7 +435,7 @@ function createViewBlock(options) {
 		}, record.id));
 	};
 	const RecordScope = (t0) => {
-		const $ = c(13);
+		const $ = c(14);
 		const { block, schema, record, children } = t0;
 		const hop = block.recordHop ? 2 : 1;
 		let t1;
@@ -452,10 +453,11 @@ function createViewBlock(options) {
 			$[4] = t1;
 		} else t1 = $[4];
 		let t2;
-		if ($[5] !== children || $[6] !== hop || $[7] !== record.id || $[8] !== record.label) {
+		if ($[5] !== children || $[6] !== hop || $[7] !== record.description || $[8] !== record.id || $[9] !== record.title) {
 			t2 = children({
 				id: record.id,
-				label: record.label,
+				title: record.title,
+				description: record.description,
 				Field,
 				Image: ReferenceImage,
 				File: ReferenceFile,
@@ -469,12 +471,13 @@ function createViewBlock(options) {
 			});
 			$[5] = children;
 			$[6] = hop;
-			$[7] = record.id;
-			$[8] = record.label;
-			$[9] = t2;
-		} else t2 = $[9];
+			$[7] = record.description;
+			$[8] = record.id;
+			$[9] = record.title;
+			$[10] = t2;
+		} else t2 = $[10];
 		let t3;
-		if ($[10] !== t1 || $[11] !== t2) {
+		if ($[11] !== t1 || $[12] !== t2) {
 			t3 = /* @__PURE__ */ jsx(RepeaterContext.Provider, {
 				value: null,
 				children: /* @__PURE__ */ jsx(Context.Provider, {
@@ -482,10 +485,10 @@ function createViewBlock(options) {
 					children: t2
 				})
 			});
-			$[10] = t1;
-			$[11] = t2;
-			$[12] = t3;
-		} else t3 = $[12];
+			$[11] = t1;
+			$[12] = t2;
+			$[13] = t3;
+		} else t3 = $[13];
 		return t3;
 	};
 	const AssetList = ({ name, children, primitive }) => {
@@ -634,7 +637,7 @@ function createViewBlock(options) {
 		return t1;
 	};
 	const Component = (props) => {
-		const $ = c(22);
+		const $ = c(23);
 		const editingRuntime = useBlockEditingRuntime();
 		if (editingRuntime) {
 			let t0;
@@ -663,66 +666,71 @@ function createViewBlock(options) {
 			mergedContent = $[4];
 			normalizedContent = $[5];
 		}
-		const AuthoredComponent = options.component;
+		const ToReact = options.toReact;
 		let t0;
-		if ($[6] === Symbol.for("react.memo_cache_sentinel")) {
+		if ($[6] !== blockData.settings) {
 			t0 = {
-				position: "relative",
-				scrollMargin: "5rem"
+				...settingsDefaults,
+				...blockData.settings
 			};
-			$[6] = t0;
-		} else t0 = $[6];
+			$[6] = blockData.settings;
+			$[7] = t0;
+		} else t0 = $[7];
+		const settings = t0;
 		let t1;
-		if ($[7] !== blockData.settings) {
+		if ($[8] === Symbol.for("react.memo_cache_sentinel")) {
 			t1 = {
-				...settingsDefaults,
-				...blockData.settings
+				position: "relative",
+				scrollMargin: "5rem"
 			};
-			$[7] = blockData.settings;
 			$[8] = t1;
 		} else t1 = $[8];
 		let t2;
-		if ($[9] !== blockData._id || $[10] !== mergedContent || $[11] !== mode || $[12] !== t1) {
+		if ($[9] !== blockData._id || $[10] !== mergedContent || $[11] !== mode || $[12] !== settings) {
 			t2 = {
 				blockId: blockData._id,
 				content: mergedContent,
-				settings: t1,
+				settings,
 				mode
 			};
 			$[9] = blockData._id;
 			$[10] = mergedContent;
 			$[11] = mode;
-			$[12] = t1;
+			$[12] = settings;
 			$[13] = t2;
 		} else t2 = $[13];
 		let t3;
-		if ($[14] !== normalizedContent) {
-			t3 = /* @__PURE__ */ jsx(AuthoredComponent, { content: normalizedContent });
+		if ($[14] !== normalizedContent || $[15] !== settings) {
+			t3 = /* @__PURE__ */ jsx(ToReact, {
+				content: normalizedContent,
+				settings
+			});
 			$[14] = normalizedContent;
-			$[15] = t3;
-		} else t3 = $[15];
+			$[15] = settings;
+			$[16] = t3;
+		} else t3 = $[16];
 		let t4;
-		if ($[16] !== t2 || $[17] !== t3) {
+		if ($[17] !== t2 || $[18] !== t3) {
 			t4 = /* @__PURE__ */ jsx(Context.Provider, {
 				value: t2,
 				children: t3
 			});
-			$[16] = t2;
-			$[17] = t3;
-			$[18] = t4;
-		} else t4 = $[18];
+			$[17] = t2;
+			$[18] = t3;
+			$[19] = t4;
+		} else t4 = $[19];
 		let t5;
-		if ($[19] !== blockData._id || $[20] !== t4) {
+		if ($[20] !== blockData._id || $[21] !== t4) {
 			t5 = /* @__PURE__ */ jsx("div", {
 				className: "group visual-editing-block",
 				"data-camox-viewport-block": blockData._id,
-				style: t0,
+				style: t1,
 				children: t4
 			});
-			$[19] = blockData._id;
-			$[20] = t4;
-			$[21] = t5;
-		} else t5 = $[21];
+			$[20] = blockData._id;
+			$[21] = t4;
+			$[22] = t5;
+		} else t5 = $[22];
 		return t5;
 	};
 	const contentSchema = {
@@ -731,7 +739,9 @@ function createViewBlock(options) {
 		description: options.description,
 		properties: typeboxSchema.properties,
 		required: Object.keys(fields.content),
-		toMarkdown: resolveToMarkdown(options.toMarkdown, fields.settings, "block", fields.content)
+		toMarkdown: resolveToMarkdown(options.toMarkdown, fields.settings, "block", fields.content),
+		toTitle: resolveToTitle(options.toTitle, fields.settings, "block", fields.content),
+		...options.toStructuredData && { toStructuredData: resolveToStructuredData(options.toStructuredData, fields.settings, "block", fields.content) }
 	};
 	const settingsSchema = settingsTypeboxSchema ? {
 		type: "object",
@@ -810,6 +820,7 @@ function createViewBlock(options) {
 						settings: settingsDefaults,
 						slot: null,
 						summary: "",
+						title: "",
 						position: "",
 						createdAt: 0,
 						updatedAt: 0

package/dist/core/createCollection.d.ts

@@ -1,6 +1,7 @@
 import { LayoutRequestContext } from "./requestContext.js";
+import { KnownPropertiesOnly, RecordNode } from "./structuredData.js";
 import { LayoutCollectionItemResult, LayoutRoutesResult, RecordPages } from "./createLayout.js";
-import { CollectionFieldBuilder, StringField } from "./lib/contentType.js";
+import { CollectionFieldBuilder, RecordStructuredDataContext, RecordTemplateContext } from "./lib/contentType.js";
 import { SystemOrderKey } from "@camox/api-contract";
 import { Static, TObject, TSchema } from "@sinclair/typebox";
 //#region src/core/createCollection.d.ts
@@ -11,15 +12,27 @@ type TextKey<T extends Record<string, TSchema>> = { [K in keyof T & string]: T[K
 } ? K : never; }[keyof T & string];
 /**
  * A definition only: record authoring and querying are not public SDK APIs.
- * `label` is checked against `content`'s return type: typing it against `T` directly would fix
- * `T` before the `content` callback is inferred.
+ *
+ * `toTitle` and `toDescription` are templates of the record's String fields, such as
+ * `` ({ content }) => `${content.firstName} ${content.lastName}` ``. The API fills them with each
+ * record's plain text wherever records are named: studio lists and pickers, record pages,
+ * `llms.txt` and agents. `toDescription` may return nothing, and records then have no description.
  */
-export declare function createCollection<const T extends Record<string, TSchema> & ReservedFieldNames, const L extends string>(options: {
+export declare function createCollection<const T extends Record<string, TSchema> & ReservedFieldNames, Node extends RecordNode = RecordNode>(options: {
   id: string;
   title: string;
   description: string;
-  content: (field: CollectionFieldBuilder) => T & Record<NoInfer<L>, StringField>;
-  label: L;
+  content: (field: CollectionFieldBuilder) => T;
+  toTitle: (context: RecordTemplateContext<NoInfer<T>>) => string;
+  toDescription: (context: RecordTemplateContext<NoInfer<T>>) => string | undefined;
+  /**
+   * Each record's Structured Data node, from tokens of its fields, such as
+   * `({ content }) => ({ "@type": "Person", jobTitle: content.role })`. Camox fills its name and
+   * description from the record's title and description, and gives it an `@id` per record and
+   * locale. Every page referencing the record links this one node, and on the record's own page
+   * it's the main entity unless the layout declares one. A reference links the record's node.
+   */
+  toStructuredData?: (context: RecordStructuredDataContext<NoInfer<T>>) => Node & KnownPropertiesOnly<Node, RecordNode>;
 }): Collection<T>;
 /** The pages of a derived layout, one per record, found by the record's `by` field. */
 export interface CollectionPages<T extends Record<string, TSchema>, Param extends string> {
@@ -47,7 +60,12 @@ export type Collection<T extends Record<string, TSchema> = any> = {
     id: string;
     title: string;
     description: string;
-    label: TextKey<T>;
+    /** The token template titling each record, such as `{{firstName}} {{lastName}}`. */
+    toTitle: string;
+    /** The token template describing each record, or null when records have no description. */
+    toDescription: string | null;
+    /** The JSON template of each record's Structured Data node, or null when records have none. */
+    toStructuredData: Record<string, unknown> | null;
     contentSchema: TObject<T>;
   };
 };

package/dist/core/createCollection.js

@@ -1,14 +1,17 @@
-import { collectionFieldBuilder } from "./lib/contentType.js";
+import { collectionFieldBuilder, resolveRecordStructuredData, resolveRecordTemplate } from "./lib/contentType.js";
 import { notFound } from "./notFound.js";
 import { getRecordLookup } from "./requestContext.js";
-import { SYSTEM_ORDER_KEYS } from "@camox/api-contract";
+import { SYSTEM_ORDER_KEYS, nonStringTemplateFields } from "@camox/api-contract";
 import { Type } from "@sinclair/typebox";
 
 //#region src/core/createCollection.ts
 /**
 * A definition only: record authoring and querying are not public SDK APIs.
-* `label` is checked against `content`'s return type: typing it against `T` directly would fix
-* `T` before the `content` callback is inferred.
+*
+* `toTitle` and `toDescription` are templates of the record's String fields, such as
+* `` ({ content }) => `${content.firstName} ${content.lastName}` ``. The API fills them with each
+* record's plain text wherever records are named: studio lists and pickers, record pages,
+* `llms.txt` and agents. `toDescription` may return nothing, and records then have no description.
 */
 function createCollection(options) {
 	if (!options.id.trim()) throw new Error("Collection id is required");
@@ -27,7 +30,13 @@ function createCollection(options) {
 		"ReferenceList"
 	]);
 	for (const [key, field] of Object.entries(content)) if (!supported.has(field.fieldType)) throw new Error(`Collection "${options.id}" field "${key}": ${String(field.fieldType)} storage is not supported yet`);
-	if (content[options.label]?.fieldType !== "String") throw new Error("Collection label must name a String field");
+	const toTitle = resolveRecordTemplate(options.toTitle, content);
+	if (toTitle === null) throw new Error(`Collection "${options.id}": toTitle returned nothing`);
+	const toDescription = resolveRecordTemplate(options.toDescription, content);
+	for (const template of [toTitle, toDescription]) {
+		const [name] = nonStringTemplateFields(template ?? "", content);
+		if (name !== void 0) throw new Error(`Collection "${options.id}": "${name}" names no String field`);
+	}
 	const id = options.id;
 	return {
 		pages({ by, param }) {
@@ -49,10 +58,17 @@ function createCollection(options) {
 						collectionId: id,
 						data: {
 							id: record.id,
+							...record.title !== void 0 && { title: record.title },
+							...record.description !== void 0 && { description: record.description },
 							content: record.content,
 							...record.references && { references: record.references },
 							...record.updatedAt != null && { updatedAt: record.updatedAt }
-						}
+						},
+						...record.structuredData && { structuredData: record.structuredData },
+						...record.firstPublishedAt !== void 0 && { published: {
+							first: record.firstPublishedAt,
+							last: record.publishedAt ?? null
+						} }
 					};
 				},
 				async routes({ context }) {
@@ -69,13 +85,14 @@ function createCollection(options) {
 							kind: "collection-item",
 							collectionId: id,
 							id: record.id,
-							label: record.label
+							title: record.title
 						}
 					})) };
 				},
 				recordPages: {
 					collectionId: id,
-					field: by
+					field: by,
+					param
 				}
 			};
 		},
@@ -83,7 +100,9 @@ function createCollection(options) {
 			id,
 			title: options.title,
 			description: options.description,
-			label: options.label,
+			toTitle,
+			toDescription,
+			toStructuredData: options.toStructuredData ? resolveRecordStructuredData(options.toStructuredData, content) : null,
 			contentSchema: Type.Object(content, { additionalProperties: false })
 		}
 	};