@btst/stack 2.11.3 → 2.11.5

package/src/plugins/cms/api/mutations.ts

@@ -2,6 +2,11 @@ import type { DBAdapter as Adapter } from "@btst/db";
 import type { ContentType, ContentItem } from "../types";
 import { serializeContentItem } from "./getters";
 import type { SerializedContentItem } from "../types";
+import {
+	collectExistingRelationIds,
+	extractRelationFields,
+	syncRelations,
+} from "./relations";
 
 /**
  * Input for creating a new CMS content item.
@@ -13,12 +18,37 @@ export interface CreateCMSContentItemInput {
 	data: Record<string, unknown>;
 }
 
+/**
+ * Options for {@link createCMSContentItem}.
+ */
+export interface CreateCMSContentItemOptions {
+	/**
+	 * When `true`, persist relation fields (`belongsTo`, `hasMany`,
+	 * `manyToMany`) into the `contentRelation` junction table in addition to
+	 * the item's JSON payload.
+	 *
+	 * This is what the HTTP `POST /content/:typeSlug` route does, and is
+	 * required for the admin "Related Items" panel / inverse-relation queries
+	 * to find the item.
+	 *
+	 * Seeds and other programmatic callers that want the admin UI to work
+	 * should enable this flag. Callers are still expected to pass
+	 * pre-created target IDs (`{ id }` or `[{ id }, ...]`) — inline `_new`
+	 * creation is only supported via the HTTP route.
+	 *
+	 * Defaults to `false` for backwards compatibility (a no-op for content
+	 * types without relations).
+	 */
+	syncRelations?: boolean;
+}
+
 /**
  * Create a new content item for a content type (looked up by slug).
  *
- * Bypasses Zod schema validation and relation processing — the caller is
- * responsible for providing valid, relation-free data. For relation fields or
- * schema validation, use the HTTP endpoint instead.
+ * Bypasses Zod schema validation and inline `_new` relation creation — the
+ * caller is responsible for providing valid data and pre-created relation
+ * IDs. For schema validation or inline creation of related items, use the
+ * HTTP endpoint instead.
  *
  * Throws if the content type is not found or the slug is already taken within
  * that content type.
@@ -30,11 +60,15 @@ export interface CreateCMSContentItemInput {
  * @param adapter - The database adapter
  * @param contentTypeSlug - Slug of the target content type
  * @param input - Item slug and data payload
+ * @param options - See {@link CreateCMSContentItemOptions}. Pass
+ *   `{ syncRelations: true }` to also populate the `contentRelation`
+ *   junction table for relation fields in the payload.
  */
 export async function createCMSContentItem(
 	adapter: Adapter,
 	contentTypeSlug: string,
 	input: CreateCMSContentItemInput,
+	options: CreateCMSContentItemOptions = {},
 ): Promise<SerializedContentItem> {
 	const contentType = await adapter.findOne<ContentType>({
 		model: "contentType",
@@ -80,5 +114,16 @@ export async function createCMSContentItem(
 		},
 	});
 
+	if (options.syncRelations) {
+		const relationFields = extractRelationFields(contentType);
+		if (Object.keys(relationFields).length > 0) {
+			const relationIds = collectExistingRelationIds(
+				input.data,
+				relationFields,
+			);
+			await syncRelations(adapter, item.id, relationIds);
+		}
+	}
+
 	return serializeContentItem(item);
 }

package/src/plugins/cms/api/plugin.ts

@@ -15,7 +15,6 @@ import type {
 	CMSBackendConfig,
 	CMSHookContext,
 	SerializedContentItemWithType,
-	RelationConfig,
 	RelationValue,
 	InverseRelation,
 } from "../types";
@@ -31,6 +30,12 @@ import {
 	serializeContentItemWithType,
 } from "./getters";
 import { createCMSContentItem } from "./mutations";
+import {
+	extractRelationFields,
+	isExistingRelationValue,
+	isNewRelationValue,
+	syncRelations,
+} from "./relations";
 import type { QueryClient } from "@tanstack/react-query";
 import { CMS_QUERY_KEYS } from "./query-key-defs";
 import { runHookWithShim } from "../../utils";
@@ -145,67 +150,9 @@ function getContentTypeZodSchema(contentType: ContentType): z.ZodTypeAny {
 }
 
 // ========== Relation Helpers ==========
-
-interface JsonSchemaProperty {
-	fieldType?: string;
-	relation?: RelationConfig;
-	type?: string;
-	items?: JsonSchemaProperty;
-	[key: string]: unknown;
-}
-
-interface JsonSchemaWithProperties {
-	properties?: Record<string, JsonSchemaProperty>;
-	[key: string]: unknown;
-}
-
-/**
- * Extract relation field configurations from a content type's JSON Schema
- */
-function extractRelationFields(
-	contentType: ContentType,
-): Record<string, RelationConfig> {
-	const jsonSchema = JSON.parse(
-		contentType.jsonSchema,
-	) as JsonSchemaWithProperties;
-	const properties = jsonSchema.properties || {};
-	const relationFields: Record<string, RelationConfig> = {};
-
-	for (const [fieldName, fieldSchema] of Object.entries(properties)) {
-		if (fieldSchema.fieldType === "relation" && fieldSchema.relation) {
-			relationFields[fieldName] = fieldSchema.relation;
-		}
-	}
-
-	return relationFields;
-}
-
-/**
- * Check if a value is a "new" relation item (to be created)
- */
-function isNewRelationValue(
-	value: unknown,
-): value is { _new: true; data: Record<string, unknown> } {
-	return (
-		typeof value === "object" &&
-		value !== null &&
-		"_new" in value &&
-		(value as { _new: unknown })._new === true &&
-		"data" in value
-	);
-}
-
-/**
- * Check if a value is an existing relation reference
- */
-function isExistingRelationValue(value: unknown): value is { id: string } {
-	return (
-		typeof value === "object" &&
-		value !== null &&
-		"id" in value &&
-		typeof (value as { id: unknown }).id === "string"
-	);
-}
+// `extractRelationFields`, `isNewRelationValue`, `isExistingRelationValue`,
+// and `syncRelations` live in ./relations so both this HTTP route module
+// and the programmatic mutations helper can share them.
 
 /**
  * Process relation fields in content data:
@@ -363,44 +310,6 @@ async function createRelatedItem(
 	return item;
 }
 
-/**
- * Sync relations in the junction table for a content item.
- *
- * Only updates relations for fields explicitly present in relationIds.
- * Fields not in relationIds are left unchanged - this preserves existing
- * relations during partial updates.
- */
-async function syncRelations(
-	adapter: Adapter,
-	sourceId: string,
-	relationIds: Record<string, string[]>,
-): Promise<void> {
-	// Only sync fields that are explicitly included in relationIds
-	for (const [fieldName, targetIds] of Object.entries(relationIds)) {
-		// Delete existing relations for this specific field only
-		await adapter.delete({
-			model: "contentRelation",
-			where: [
-				{ field: "sourceId", value: sourceId, operator: "eq" as const },
-				{ field: "fieldName", value: fieldName, operator: "eq" as const },
-			],
-		});
-
-		// Create new relations for this field
-		for (const targetId of targetIds) {
-			await adapter.create<ContentRelation>({
-				model: "contentRelation",
-				data: {
-					sourceId,
-					targetId,
-					fieldName,
-					createdAt: new Date(),
-				},
-			});
-		}
-	}
-}
-
 /**
  * Populate relations for a content item by fetching related items
  */
@@ -575,9 +484,10 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) => {
 			createContentItem: async (
 				typeSlug: string,
 				input: Parameters<typeof createCMSContentItem>[2],
+				options?: Parameters<typeof createCMSContentItem>[3],
 			) => {
 				await ensureSynced(adapter);
-				return createCMSContentItem(adapter, typeSlug, input);
+				return createCMSContentItem(adapter, typeSlug, input, options);
 			},
 		}),
 

package/src/plugins/cms/api/relations.ts

@@ -0,0 +1,174 @@
+import type { DBAdapter as Adapter } from "@btst/db";
+import type {
+	ContentType,
+	ContentRelation,
+	RelationConfig,
+	RelationValue,
+} from "../types";
+
+/**
+ * Shape of a property inside a content type's stored JSON Schema.
+ * Relation fields carry `fieldType: "relation"` and a `relation` descriptor.
+ */
+interface JsonSchemaProperty {
+	fieldType?: string;
+	relation?: RelationConfig;
+	type?: string;
+	items?: JsonSchemaProperty;
+	[key: string]: unknown;
+}
+
+interface JsonSchemaWithProperties {
+	properties?: Record<string, JsonSchemaProperty>;
+	[key: string]: unknown;
+}
+
+/**
+ * Extract relation field configurations from a content type's JSON Schema.
+ *
+ * Returns a map of field name -> RelationConfig for every field declared
+ * with `fieldType: "relation"` and a populated `relation` descriptor.
+ */
+export function extractRelationFields(
+	contentType: ContentType,
+): Record<string, RelationConfig> {
+	const jsonSchema = JSON.parse(
+		contentType.jsonSchema,
+	) as JsonSchemaWithProperties;
+	const properties = jsonSchema.properties || {};
+	const relationFields: Record<string, RelationConfig> = {};
+
+	for (const [fieldName, fieldSchema] of Object.entries(properties)) {
+		if (fieldSchema.fieldType === "relation" && fieldSchema.relation) {
+			relationFields[fieldName] = fieldSchema.relation;
+		}
+	}
+
+	return relationFields;
+}
+
+/**
+ * Type guard: value is a `{ _new: true, data: ... }` descriptor used by the
+ * HTTP endpoints to request inline creation of a related item on save.
+ */
+export function isNewRelationValue(
+	value: unknown,
+): value is { _new: true; data: Record<string, unknown> } {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		"_new" in value &&
+		(value as { _new: unknown })._new === true &&
+		"data" in value
+	);
+}
+
+/**
+ * Type guard: value is an existing relation reference (`{ id: string }`).
+ */
+export function isExistingRelationValue(
+	value: unknown,
+): value is { id: string } {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		"id" in value &&
+		typeof (value as { id: unknown }).id === "string"
+	);
+}
+
+/**
+ * Collect relation target IDs out of a content item's data payload,
+ * grouped by relation field name.
+ *
+ * Only processes fields that are:
+ * - present in `data`
+ * - declared as relations in `relationFields`
+ * - hold existing `{ id }` references (or arrays of them)
+ *
+ * Unlike `processRelationsInData` in the HTTP route, this does NOT create
+ * inline `_new` items — callers passing `_new` values will have them
+ * silently ignored. Programmatic callers (seeds, imports) are expected to
+ * supply pre-created IDs.
+ *
+ * Returns a map of `{ fieldName: targetIds[] }` ready to hand to
+ * {@link syncRelations}.
+ */
+export function collectExistingRelationIds(
+	data: Record<string, unknown>,
+	relationFields: Record<string, RelationConfig>,
+): Record<string, string[]> {
+	const relationIds: Record<string, string[]> = {};
+
+	for (const [fieldName, relationConfig] of Object.entries(relationFields)) {
+		if (!(fieldName in data)) continue;
+
+		const fieldValue = data[fieldName];
+		if (!fieldValue) {
+			relationIds[fieldName] = [];
+			continue;
+		}
+
+		const ids: string[] = [];
+
+		if (relationConfig.type === "belongsTo") {
+			const value = fieldValue as RelationValue;
+			if (isExistingRelationValue(value)) {
+				ids.push(value.id);
+			}
+		} else {
+			// hasMany / manyToMany — expect an array of { id }
+			const values = (
+				Array.isArray(fieldValue) ? fieldValue : []
+			) as RelationValue[];
+
+			for (const value of values) {
+				if (isExistingRelationValue(value)) {
+					ids.push(value.id);
+				}
+			}
+		}
+
+		relationIds[fieldName] = ids;
+	}
+
+	return relationIds;
+}
+
+/**
+ * Sync relations in the junction table for a content item.
+ *
+ * Only updates relations for fields explicitly present in `relationIds`.
+ * Fields not included are left untouched — this preserves existing
+ * relations during partial updates.
+ *
+ * For each included field, existing junction rows (matching sourceId +
+ * fieldName) are deleted and replaced with the provided target IDs.
+ */
+export async function syncRelations(
+	adapter: Adapter,
+	sourceId: string,
+	relationIds: Record<string, string[]>,
+): Promise<void> {
+	for (const [fieldName, targetIds] of Object.entries(relationIds)) {
+		await adapter.delete({
+			model: "contentRelation",
+			where: [
+				{ field: "sourceId", value: sourceId, operator: "eq" as const },
+				{ field: "fieldName", value: fieldName, operator: "eq" as const },
+			],
+		});
+
+		for (const targetId of targetIds) {
+			await adapter.create<ContentRelation>({
+				model: "contentRelation",
+				data: {
+					sourceId,
+					targetId,
+					fieldName,
+					createdAt: new Date(),
+				},
+			});
+		}
+	}
+}

package/src/plugins/cms/client/components/forms/content-form.tsx

@@ -63,63 +63,109 @@ function buildFieldConfigFromJsonSchema(
 		isRequired?: boolean;
 	}>,
 ): FieldConfig<Record<string, unknown>> {
-	// Get base config from shared utility (handles fieldType from JSON Schema)
+	// Get base config from shared utility (handles fieldType from JSON Schema,
+	// including per-item configs for arrays of objects).
 	const baseConfig = buildFieldConfigBase(jsonSchema, fieldComponents);
 
-	// Apply CMS-specific handling for special fieldTypes ONLY if no custom component exists
-	// Custom fieldComponents take priority - don't override if user provided one
-	const properties = jsonSchema.properties as Record<
-		string,
-		JsonSchemaProperty
-	>;
+	const properties = jsonSchema.properties as
+		| Record<string, JsonSchemaProperty>
+		| undefined;
 
 	if (!properties) return baseConfig;
 
-	for (const [key, prop] of Object.entries(properties)) {
-		// Handle "file" fieldType when there's NO custom component for "file"
-		if (prop.fieldType === "file" && !fieldComponents?.["file"]) {
-			// Use CMSFileUpload as the default file component
-			if (!uploadImage && !imageInputField) {
-				// Show a clear error message if neither uploadImage nor imageInputField is provided
-				baseConfig[key] = {
-					...baseConfig[key],
-					fieldType: () => (
-						<div className="rounded-md border border-destructive bg-destructive/10 p-3 text-sm text-destructive">
-							File upload requires an <code>uploadImage</code> or{" "}
-							<code>imageInputField</code> function in CMS overrides.
-						</div>
-					),
-				};
-			} else {
-				baseConfig[key] = {
-					...baseConfig[key],
-					fieldType: (props: AutoFormInputComponentProps) => (
-						<CMSFileUpload
-							{...props}
-							uploadImage={uploadImage ?? (() => Promise.resolve(""))}
-							imageInputField={imageInputField}
-							imagePicker={imagePicker}
-						/>
+	// Recursively walk the JSON Schema properties and inject CMS-specific custom
+	// components (file upload, relation picker) for any field with a matching
+	// fieldType, regardless of nesting depth. Targets:
+	//   - top-level fields
+	//   - properties of nested object fields
+	//   - properties of array items (e.g. `components: z.array(z.object({...}))`)
+	//
+	// `targetConfig` is the FieldConfigObject slot to mutate for the property at
+	// `key`. The recursion mirrors how AutoFormObject + AutoFormArray look up
+	// per-property configs: nested object/array per-item configs live as keys
+	// alongside their parent's meta on the same FieldConfigObject.
+	const injectCustomFieldTypes = (
+		props: Record<string, JsonSchemaProperty>,
+		targetConfig: Record<string, unknown>,
+	) => {
+		for (const [key, prop] of Object.entries(props)) {
+			// Ensure a slot exists so we can mutate it whether or not the base
+			// helper produced an entry for this key.
+			const existing =
+				(targetConfig[key] as Record<string, unknown> | undefined) ?? {};
+
+			let updated = existing;
+
+			// Handle "file" fieldType when there's NO custom component for "file"
+			if (prop.fieldType === "file" && !fieldComponents?.["file"]) {
+				if (!uploadImage && !imageInputField) {
+					updated = {
+						...updated,
+						fieldType: () => (
+							<div className="rounded-md border border-destructive bg-destructive/10 p-3 text-sm text-destructive">
+								File upload requires an <code>uploadImage</code> or{" "}
+								<code>imageInputField</code> function in CMS overrides.
+							</div>
+						),
+					};
+				} else {
+					updated = {
+						...updated,
+						fieldType: (componentProps: AutoFormInputComponentProps) => (
+							<CMSFileUpload
+								{...componentProps}
+								uploadImage={uploadImage ?? (() => Promise.resolve(""))}
+								imageInputField={imageInputField}
+								imagePicker={imagePicker}
+							/>
+						),
+					};
+				}
+			}
+
+			// Handle "relation" fieldType when there's NO custom component for "relation"
+			if (
+				prop.fieldType === "relation" &&
+				prop.relation &&
+				!fieldComponents?.["relation"]
+			) {
+				const relationConfig = prop.relation;
+				updated = {
+					...updated,
+					fieldType: (componentProps: AutoFormInputComponentProps) => (
+						<RelationField {...componentProps} relation={relationConfig} />
 					),
 				};
 			}
-		}
 
-		// Handle "relation" fieldType when there's NO custom component for "relation"
-		if (
-			prop.fieldType === "relation" &&
-			prop.relation &&
-			!fieldComponents?.["relation"]
-		) {
-			const relationConfig = prop.relation;
-			baseConfig[key] = {
-				...baseConfig[key],
-				fieldType: (props: AutoFormInputComponentProps) => (
-					<RelationField {...props} relation={relationConfig} />
-				),
-			};
+			// Recurse into nested objects — their per-property configs live as
+			// keys on the same parent FieldConfigObject.
+			if (prop.properties) {
+				injectCustomFieldTypes(
+					prop.properties as Record<string, JsonSchemaProperty>,
+					updated,
+				);
+			}
+
+			// Recurse into array items — same convention as nested objects.
+			const items = prop.items as JsonSchemaProperty | undefined;
+			if (items?.properties) {
+				injectCustomFieldTypes(
+					items.properties as Record<string, JsonSchemaProperty>,
+					updated,
+				);
+			}
+
+			if (Object.keys(updated).length > 0) {
+				targetConfig[key] = updated;
+			}
 		}
-	}
+	};
+
+	injectCustomFieldTypes(
+		properties,
+		baseConfig as unknown as Record<string, unknown>,
+	);
 
 	return baseConfig;
 }

package/src/plugins/cms/client/components/inverse-relations-panel.tsx

@@ -95,6 +95,19 @@ export function InverseRelationsPanel({
 		return null;
 	}
 
+	// When a single source content type has multiple belongsTo fields pointing
+	// at this target type (e.g. StackSynergy has both compoundAId and
+	// compoundBId → compound), the section title alone ("Stack Synergy") is
+	// ambiguous — two cards would render with identical headings. Mark those
+	// relations so we can disambiguate them by field name.
+	const sourceTypeCounts = new Map<string, number>();
+	for (const rel of inverseRelations) {
+		sourceTypeCounts.set(
+			rel.sourceType,
+			(sourceTypeCounts.get(rel.sourceType) ?? 0) + 1,
+		);
+	}
+
 	return (
 		<div className="space-y-4">
 			<h3 className="text-lg font-semibold">Related Items</h3>
@@ -109,12 +122,32 @@ export function InverseRelationsPanel({
 					Link={Link}
 					client={client}
 					headers={headers}
+					ambiguous={(sourceTypeCounts.get(relation.sourceType) ?? 0) > 1}
 				/>
 			))}
 		</div>
 	);
 }
 
+/**
+ * Turn a relation field name like `compoundAId` / `categoryIds` into a
+ * friendlier label like `Compound A` / `Category` for display in the
+ * inverse-relations panel when two sections would otherwise share a title.
+ *
+ * Strips a trailing `Id` or `Ids`, splits camelCase boundaries, and
+ * title-cases the result. Leaves unrecognised shapes as-is so we never
+ * produce an empty string.
+ */
+function humanizeFieldName(fieldName: string): string {
+	const stripped = fieldName.replace(/Ids?$/, "") || fieldName;
+	const words = stripped
+		.replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+		.replace(/[_-]+/g, " ")
+		.trim()
+		.split(/\s+/);
+	return words.map((w) => (w ? w[0]!.toUpperCase() + w.slice(1) : w)).join(" ");
+}
+
 interface InverseRelationSectionProps {
 	relation: InverseRelation;
 	contentTypeSlug: string;
@@ -128,6 +161,12 @@ interface InverseRelationSectionProps {
 	}>;
 	client: ReturnType<typeof createApiClient<CMSApiRouter>>;
 	headers?: HeadersInit;
+	/**
+	 * True when another inverse relation from the same `sourceType` is also
+	 * being rendered — in which case the field-name suffix is shown so the
+	 * user can tell the two cards apart.
+	 */
+	ambiguous: boolean;
 }
 
 function InverseRelationSection({
@@ -139,6 +178,7 @@ function InverseRelationSection({
 	Link,
 	client,
 	headers,
+	ambiguous,
 }: InverseRelationSectionProps) {
 	const [isExpanded, setIsExpanded] = useState(true);
 	const [deleteItemId, setDeleteItemId] = useState<string | null>(null);
@@ -205,6 +245,7 @@ function InverseRelationSection({
 	};
 
 	const LinkComponent = Link ?? "a";
+	const fieldLabel = ambiguous ? humanizeFieldName(relation.fieldName) : null;
 
 	return (
 		<Card>
@@ -220,7 +261,13 @@ function InverseRelationSection({
 						) : (
 							<ChevronRight className="h-4 w-4" />
 						)}
-						{relation.sourceTypeName} ({total})
+						<span>{relation.sourceTypeName}</span>
+						{fieldLabel && (
+							<span className="font-normal text-muted-foreground">
+								· {fieldLabel}
+							</span>
+						)}
+						<span className="font-normal text-muted-foreground">({total})</span>
 					</CardTitle>
 				</button>
 			</CardHeader>
@@ -269,6 +316,7 @@ function InverseRelationSection({
 						>
 							<Plus className="h-4 w-4 mr-2" />
 							Add {relation.sourceTypeName}
+							{fieldLabel ? ` (${fieldLabel})` : ""}
 						</Button>
 					</div>
 				</CardContent>