@btst/stack 1.7.0 → 1.9.0

package/src/plugins/cms/client/hooks/cms-hooks.tsx

@@ -722,3 +722,347 @@ export function useDeleteContent(typeSlug: string) {
 		},
 	});
 }
+
+// ========== Relation Hooks ==========
+
+/**
+ * Content item with populated relations
+ */
+export interface ContentItemWithRelations<TData = Record<string, unknown>>
+	extends SerializedContentItemWithType<TData> {
+	_relations?: Record<string, SerializedContentItemWithType[]>;
+}
+
+/**
+ * Hook for fetching a content item with its relations populated.
+ * Use this when you need to display related items alongside the main item.
+ *
+ * @template TMap - A type map of content type slugs to their data types
+ * @template TSlug - The content type slug (inferred from typeSlug parameter)
+ *
+ * @example
+ * ```typescript
+ * type MyCMSTypes = {
+ *   resource: { name: string; categoryIds: Array<{ id: string }> }
+ *   category: { name: string }
+ * }
+ * const { item } = useContentItemPopulated<MyCMSTypes, "resource">("resource", "some-id")
+ * // item?._relations?.categoryIds contains populated category items
+ * ```
+ */
+export function useContentItemPopulated<
+	TMap extends Record<string, Record<string, unknown>> = Record<
+		string,
+		Record<string, unknown>
+	>,
+	TSlug extends keyof TMap = keyof TMap,
+>(
+	typeSlug: TSlug & string,
+	id: string,
+): {
+	item: ContentItemWithRelations<TMap[TSlug]> | null;
+	isLoading: boolean;
+	error: Error | null;
+	refetch: () => void;
+} {
+	const { apiBaseURL, apiBasePath, headers } =
+		usePluginOverrides<CMSPluginOverrides>("cms");
+	const client = createApiClient<CMSApiRouter>({
+		baseURL: apiBaseURL,
+		basePath: apiBasePath,
+	});
+
+	const { data, isLoading, error, refetch } = useQuery({
+		queryKey: ["cmsContent", typeSlug, id, "populated"],
+		queryFn: async () => {
+			const response: unknown = await client(
+				"/content/:typeSlug/:id/populated",
+				{
+					method: "GET",
+					params: { typeSlug, id },
+					headers,
+				},
+			);
+			if (isErrorResponse(response)) {
+				throw toError(response.error);
+			}
+			return (response as { data?: unknown }).data as ContentItemWithRelations<
+				TMap[TSlug]
+			>;
+		},
+		...SHARED_QUERY_CONFIG,
+		enabled: !!typeSlug && !!id,
+	});
+
+	return {
+		item: data ?? null,
+		isLoading,
+		error,
+		refetch,
+	};
+}
+
+/**
+ * Suspense variant of useContentItemPopulated
+ */
+export function useSuspenseContentItemPopulated<
+	TMap extends Record<string, Record<string, unknown>> = Record<
+		string,
+		Record<string, unknown>
+	>,
+	TSlug extends keyof TMap = keyof TMap,
+>(
+	typeSlug: TSlug & string,
+	id: string,
+): {
+	item: ContentItemWithRelations<TMap[TSlug]> | null;
+	refetch: () => Promise<unknown>;
+} {
+	const { apiBaseURL, apiBasePath, headers } =
+		usePluginOverrides<CMSPluginOverrides>("cms");
+	const client = createApiClient<CMSApiRouter>({
+		baseURL: apiBaseURL,
+		basePath: apiBasePath,
+	});
+
+	const { data, refetch, error, isFetching } = useSuspenseQuery({
+		queryKey: ["cmsContent", typeSlug, id, "populated"],
+		queryFn: async () => {
+			const response: unknown = await client(
+				"/content/:typeSlug/:id/populated",
+				{
+					method: "GET",
+					params: { typeSlug, id },
+					headers,
+				},
+			);
+			if (isErrorResponse(response)) {
+				throw toError(response.error);
+			}
+			return (response as { data?: unknown }).data as ContentItemWithRelations<
+				TMap[TSlug]
+			>;
+		},
+		...SHARED_QUERY_CONFIG,
+	});
+
+	if (error && !isFetching) {
+		throw error;
+	}
+
+	return {
+		item: data ?? null,
+		refetch,
+	};
+}
+
+/**
+ * Options for useContentByRelation hook
+ */
+export interface UseContentByRelationOptions {
+	/** Number of items per page (default: 20) */
+	limit?: number;
+	/** Whether to enable the query (default: true) */
+	enabled?: boolean;
+}
+
+/**
+ * Hook for fetching content items that have a specific relation.
+ * Useful for "filter by category" functionality.
+ *
+ * @template TMap - A type map of content type slugs to their data types
+ * @template TSlug - The content type slug (inferred from typeSlug parameter)
+ *
+ * @example
+ * ```typescript
+ * // Get all resources in a specific category
+ * const { items } = useContentByRelation("resource", "categoryIds", categoryId)
+ * ```
+ */
+export function useContentByRelation<
+	TMap extends Record<string, Record<string, unknown>> = Record<
+		string,
+		Record<string, unknown>
+	>,
+	TSlug extends keyof TMap = keyof TMap,
+>(
+	typeSlug: TSlug & string,
+	fieldName: string,
+	targetId: string,
+	options: UseContentByRelationOptions = {},
+): {
+	items: SerializedContentItemWithType<TMap[TSlug]>[];
+	total: number;
+	isLoading: boolean;
+	error: Error | null;
+	loadMore: () => void;
+	hasMore: boolean;
+	isLoadingMore: boolean;
+	refetch: () => void;
+} {
+	const { apiBaseURL, apiBasePath, headers } =
+		usePluginOverrides<CMSPluginOverrides>("cms");
+	const client = createApiClient<CMSApiRouter>({
+		baseURL: apiBaseURL,
+		basePath: apiBasePath,
+	});
+	const { limit = 20, enabled = true } = options;
+
+	const {
+		data,
+		isLoading,
+		error,
+		fetchNextPage,
+		hasNextPage,
+		isFetchingNextPage,
+		refetch,
+	} = useInfiniteQuery({
+		queryKey: ["cmsContent", typeSlug, "by-relation", fieldName, targetId],
+		queryFn: async ({ pageParam = 0 }) => {
+			const response: unknown = await client("/content/:typeSlug/by-relation", {
+				method: "GET",
+				params: { typeSlug },
+				query: { field: fieldName, targetId, limit, offset: pageParam },
+				headers,
+			});
+			if (isErrorResponse(response)) {
+				throw toError(response.error);
+			}
+			return (response as { data?: unknown }).data as PaginatedContentItems<
+				TMap[TSlug]
+			>;
+		},
+		...SHARED_QUERY_CONFIG,
+		initialPageParam: 0,
+		getNextPageParam: (lastPage, allPages) => {
+			if (!lastPage || typeof lastPage !== "object") return undefined;
+			const items = (lastPage as PaginatedContentItems)?.items;
+			if (!Array.isArray(items) || items.length < limit) return undefined;
+			const loadedCount = (allPages || []).reduce(
+				(sum, page) =>
+					sum +
+					(Array.isArray((page as PaginatedContentItems)?.items)
+						? (page as PaginatedContentItems).items.length
+						: 0),
+				0,
+			);
+			const total = (lastPage as PaginatedContentItems)?.total ?? 0;
+			if (loadedCount >= total) return undefined;
+			return loadedCount;
+		},
+		enabled: enabled && !!typeSlug && !!fieldName && !!targetId,
+	});
+
+	const pages = (
+		data as InfiniteData<PaginatedContentItems<TMap[TSlug]>, number> | undefined
+	)?.pages;
+	const items = (pages?.flatMap((page) =>
+		Array.isArray(page?.items) ? page.items : [],
+	) ?? []) as SerializedContentItemWithType<TMap[TSlug]>[];
+	const total = pages?.[0]?.total ?? 0;
+
+	return {
+		items,
+		total,
+		isLoading,
+		error,
+		loadMore: fetchNextPage,
+		hasMore: !!hasNextPage,
+		isLoadingMore: isFetchingNextPage,
+		refetch,
+	};
+}
+
+/**
+ * Suspense variant of useContentByRelation
+ */
+export function useSuspenseContentByRelation<
+	TMap extends Record<string, Record<string, unknown>> = Record<
+		string,
+		Record<string, unknown>
+	>,
+	TSlug extends keyof TMap = keyof TMap,
+>(
+	typeSlug: TSlug & string,
+	fieldName: string,
+	targetId: string,
+	options: UseContentByRelationOptions = {},
+): {
+	items: SerializedContentItemWithType<TMap[TSlug]>[];
+	total: number;
+	loadMore: () => Promise<unknown>;
+	hasMore: boolean;
+	isLoadingMore: boolean;
+	refetch: () => Promise<unknown>;
+} {
+	const { apiBaseURL, apiBasePath, headers } =
+		usePluginOverrides<CMSPluginOverrides>("cms");
+	const client = createApiClient<CMSApiRouter>({
+		baseURL: apiBaseURL,
+		basePath: apiBasePath,
+	});
+	const { limit = 20 } = options;
+
+	const {
+		data,
+		fetchNextPage,
+		hasNextPage,
+		isFetchingNextPage,
+		refetch,
+		error,
+		isFetching,
+	} = useSuspenseInfiniteQuery({
+		queryKey: ["cmsContent", typeSlug, "by-relation", fieldName, targetId],
+		queryFn: async ({ pageParam = 0 }) => {
+			const response: unknown = await client("/content/:typeSlug/by-relation", {
+				method: "GET",
+				params: { typeSlug },
+				query: { field: fieldName, targetId, limit, offset: pageParam },
+				headers,
+			});
+			if (isErrorResponse(response)) {
+				throw toError(response.error);
+			}
+			return (response as { data?: unknown }).data as PaginatedContentItems<
+				TMap[TSlug]
+			>;
+		},
+		...SHARED_QUERY_CONFIG,
+		initialPageParam: 0,
+		getNextPageParam: (lastPage, allPages) => {
+			if (!lastPage || typeof lastPage !== "object") return undefined;
+			const items = (lastPage as PaginatedContentItems)?.items;
+			if (!Array.isArray(items) || items.length < limit) return undefined;
+			const loadedCount = (allPages || []).reduce(
+				(sum, page) =>
+					sum +
+					(Array.isArray((page as PaginatedContentItems)?.items)
+						? (page as PaginatedContentItems).items.length
+						: 0),
+				0,
+			);
+			const total = (lastPage as PaginatedContentItems)?.total ?? 0;
+			if (loadedCount >= total) return undefined;
+			return loadedCount;
+		},
+	});
+
+	if (error && !isFetching) {
+		throw error;
+	}
+
+	const pages = data.pages as PaginatedContentItems<TMap[TSlug]>[];
+	const items = (pages?.flatMap((page) =>
+		Array.isArray(page?.items) ? page.items : [],
+	) ?? []) as SerializedContentItemWithType<TMap[TSlug]>[];
+	const total = pages?.[0]?.total ?? 0;
+
+	return {
+		items,
+		total,
+		loadMore: fetchNextPage,
+		hasMore: !!hasNextPage,
+		isLoadingMore: isFetchingNextPage,
+		refetch,
+	};
+}

package/src/plugins/cms/db.ts

@@ -77,4 +77,42 @@ export const cmsSchema = createDbPlugin("cms", {
 			},
 		},
 	},
+	/**
+	 * Junction table for content item relationships
+	 * Stores many-to-many and one-to-many relations between content items
+	 */
+	contentRelation: {
+		modelName: "contentRelation",
+		fields: {
+			/** The content item that has the relation field */
+			sourceId: {
+				type: "string",
+				required: true,
+				references: {
+					model: "contentItem",
+					field: "id",
+					onDelete: "cascade",
+				},
+			},
+			/** The content item being referenced */
+			targetId: {
+				type: "string",
+				required: true,
+				references: {
+					model: "contentItem",
+					field: "id",
+					onDelete: "cascade",
+				},
+			},
+			/** The field name in the source content type schema (e.g., "categoryIds") */
+			fieldName: {
+				type: "string",
+				required: true,
+			},
+			createdAt: {
+				type: "date",
+				defaultValue: () => new Date(),
+			},
+		},
+	},
 });

package/src/plugins/cms/types.ts

@@ -68,6 +68,92 @@ export type ContentItemWithType = ContentItem & {
 	contentType?: ContentType;
 };
 
+/**
+ * Content relation stored in the database (junction table)
+ * Links source content items to target content items for relationship fields
+ */
+export type ContentRelation = {
+	id: string;
+	/** The content item that has the relation field */
+	sourceId: string;
+	/** The content item being referenced */
+	targetId: string;
+	/** The field name in the source content type schema (e.g., "categoryIds") */
+	fieldName: string;
+	createdAt: Date;
+};
+
+// ========== Relation Field Types ==========
+
+/**
+ * Configuration for a relation field in schema metadata.
+ * Use with .meta({ fieldType: "relation", relation: {...} })
+ *
+ * The schema stores relation values as simple `{ id: string }` references.
+ * When `creatable: true`, the frontend sends `{ _new: true, data: {...} }`
+ * which the API processes before validation - creating new items and
+ * converting them to ID references.
+ *
+ * @example
+ * ```typescript
+ * const ResourceSchema = z.object({
+ *   // Simple array of ID references - API handles _new items before validation
+ *   categoryIds: z.array(z.object({ id: z.string() })).default([]).meta({
+ *     fieldType: "relation",
+ *     relation: {
+ *       type: "manyToMany",
+ *       targetType: "category",
+ *       displayField: "name",
+ *       creatable: true,
+ *     },
+ *   }),
+ * });
+ * ```
+ */
+export interface RelationConfig {
+	/** Relation type */
+	type: "belongsTo" | "hasMany" | "manyToMany";
+	/** Target content type slug */
+	targetType: string;
+	/** Field to display in the dropdown (e.g., "name", "title") */
+	displayField: string;
+	/** Allow creating new items inline via modal (default: false) */
+	creatable?: boolean;
+}
+
+/**
+ * Value for a relation field - either a reference to existing item or a new item to create.
+ *
+ * @example
+ * ```typescript
+ * // Reference to existing item
+ * const existing: RelationValue = { id: "abc123" };
+ *
+ * // New item to create on save
+ * const newItem: RelationValue = {
+ *   _new: true,
+ *   data: { name: "New Category", description: "..." }
+ * };
+ * ```
+ */
+export type RelationValue =
+	| { id: string }
+	| { _new: true; data: Record<string, unknown> };
+
+/**
+ * Represents an inverse relation (content types that reference this type via belongsTo)
+ */
+export interface InverseRelation {
+	/** The content type slug that has the belongsTo relation */
+	sourceType: string;
+	/** Display name of the source content type */
+	sourceTypeName: string;
+	/** The field name that contains the belongsTo relation */
+	fieldName: string;
+	/** Count of items with this relation (when itemId is provided) */
+	count: number;
+}
+
 /**
  * Serialized content type for API responses (dates as strings)
  */
@@ -96,6 +182,11 @@ export interface SerializedContentItemWithType<TData = Record<string, unknown>>
 	parsedData: TData;
 	/** Joined content type */
 	contentType?: SerializedContentType;
+	/**
+	 * Populated relation data (only present when using populated endpoints/hooks).
+	 * Keys are field names, values are arrays of related content items.
+	 */
+	_relations?: Record<string, SerializedContentItemWithType[]>;
 }
 
 /**
@@ -156,16 +247,17 @@ export interface CMSHookContext {
 
 /**
  * Hooks for customizing CMS backend behavior
+ *
+ * Note: Before hooks can only deny operations by returning `false`.
+ * They cannot modify the data being saved. This ensures consistency
+ * between the stored content item data and relation junction tables.
  */
 export interface CMSBackendHooks {
-	/** Called before creating a content item */
+	/** Called before creating a content item. Return false to deny the operation. */
 	onBeforeCreate?: (
 		data: Record<string, unknown>,
 		context: CMSHookContext,
-	) =>
-		| Promise<Record<string, unknown> | false>
-		| Record<string, unknown>
-		| false;
+	) => Promise<false | void> | false | void;
 
 	/** Called after creating a content item */
 	onAfterCreate?: (
@@ -173,15 +265,12 @@ export interface CMSBackendHooks {
 		context: CMSHookContext,
 	) => Promise<void> | void;
 
-	/** Called before updating a content item */
+	/** Called before updating a content item. Return false to deny the operation. */
 	onBeforeUpdate?: (
 		id: string,
 		data: Record<string, unknown>,
 		context: CMSHookContext,
-	) =>
-		| Promise<Record<string, unknown> | false>
-		| Record<string, unknown>
-		| false;
+	) => Promise<false | void> | false | void;
 
 	/** Called after updating a content item */
 	onAfterUpdate?: (

package/src/plugins/route-docs/client/components/loading/docs-skeleton.tsx

@@ -0,0 +1,82 @@
+"use client";
+
+import { Skeleton } from "@workspace/ui/components/skeleton";
+import { ScrollArea } from "@workspace/ui/components/scroll-area";
+import { Card, CardContent } from "@workspace/ui/components/card";
+
+export function DocsPageSkeleton() {
+	return (
+		<div className="flex min-h-screen bg-background">
+			{/* Desktop Sidebar skeleton */}
+			<aside className="hidden md:block w-72 border-r bg-card shrink-0">
+				<div className="p-4 border-b">
+					<Skeleton className="h-4 w-16" />
+				</div>
+				<ScrollArea className="h-[calc(100vh-57px)]">
+					<div className="p-3 space-y-4">
+						{/* Plugin groups */}
+						{[1, 2, 3].map((i) => (
+							<div key={i} className="space-y-2">
+								<Skeleton className="h-8 w-full" />
+								<div className="ml-2 space-y-1">
+									{[1, 2, 3].map((j) => (
+										<Skeleton key={j} className="h-7 w-full" />
+									))}
+								</div>
+							</div>
+						))}
+					</div>
+				</ScrollArea>
+			</aside>
+
+			{/* Mobile header skeleton */}
+			<div className="md:hidden fixed top-0 left-0 right-0 z-40 bg-card border-b">
+				<div className="flex items-center justify-between p-4">
+					<Skeleton className="h-4 w-24" />
+					<Skeleton className="h-8 w-20" />
+				</div>
+			</div>
+
+			{/* Main content skeleton */}
+			<main className="flex-1 overflow-auto pt-16 md:pt-0">
+				<div className="max-w-4xl mx-auto p-4 sm:p-6 lg:p-8 space-y-4 sm:space-y-6">
+					{/* Title */}
+					<div className="space-y-2">
+						<Skeleton className="h-8 sm:h-9 w-48 sm:w-64" />
+						<Skeleton className="h-4 sm:h-5 w-72 sm:w-96" />
+					</div>
+
+					{/* Separator */}
+					<div className="h-px bg-border" />
+
+					{/* Badges */}
+					<div className="flex gap-2">
+						<Skeleton className="h-6 w-24" />
+						<Skeleton className="h-6 w-20" />
+					</div>
+
+					{/* Routes card */}
+					<Card>
+						<div className="p-4 sm:p-6">
+							<Skeleton className="h-6 w-32 mb-4" />
+						</div>
+						<CardContent className="pt-0 space-y-4">
+							{/* Desktop table skeleton */}
+							<div className="hidden md:block space-y-2">
+								{[1, 2, 3, 4].map((i) => (
+									<Skeleton key={i} className="h-12 w-full" />
+								))}
+							</div>
+							{/* Mobile cards skeleton */}
+							<div className="md:hidden space-y-3">
+								{[1, 2, 3].map((i) => (
+									<Skeleton key={i} className="h-28 w-full rounded-lg" />
+								))}
+							</div>
+						</CardContent>
+					</Card>
+				</div>
+			</main>
+		</div>
+	);
+}

package/src/plugins/route-docs/client/components/loading/index.tsx

@@ -0,0 +1 @@
+export { DocsPageSkeleton } from "./docs-skeleton";