@btst/stack 2.11.8 → 2.12.1

package/src/plugins/cms/client/components/forms/relation-field.tsx

@@ -1,7 +1,14 @@
 "use client";
 
 import { useState, useCallback, useMemo } from "react";
+import { useQueries } from "@tanstack/react-query";
+import { createApiClient } from "@btst/stack/plugins/client";
+import { usePluginOverrides } from "@btst/stack/context";
 import { useContent, useCreateContent } from "../../hooks";
+import type { CMSApiRouter } from "../../../api";
+import type { SerializedContentItemWithType } from "../../../types";
+import type { CMSPluginOverrides } from "../../overrides";
+import { createCMSQueryKeys } from "../../../query-keys";
 import MultipleSelector from "@workspace/ui/components/multi-select";
 import type { Option } from "@workspace/ui/components/multi-select";
 import { Button } from "@workspace/ui/components/button";
@@ -19,6 +26,16 @@ import { Textarea } from "@workspace/ui/components/textarea";
 import type { AutoFormInputComponentProps } from "@workspace/ui/components/auto-form/types";
 import type { RelationConfig } from "../../../types";
 
+/** Match cms-hooks SHARED_QUERY_CONFIG for detail fetches (deduped labels). */
+const RELATION_DETAIL_QUERY_OPTS = {
+	retry: false,
+	refetchOnWindowFocus: false,
+	refetchOnMount: false,
+	refetchOnReconnect: false,
+	staleTime: 1000 * 60 * 5,
+	gcTime: 1000 * 60 * 10,
+} as const;
+
 interface RelationFieldProps extends AutoFormInputComponentProps {
 	relation: RelationConfig;
 }
@@ -43,16 +60,25 @@ export function RelationField({
 	const [newItemDescription, setNewItemDescription] = useState("");
 	const [createError, setCreateError] = useState<string | null>(null);
 
-	// For belongsTo (single relation), we only allow one selection
-	const isSingleSelect = relation.type === "belongsTo";
+	const { apiBaseURL, apiBasePath, headers } =
+		usePluginOverrides<CMSPluginOverrides>("cms");
 
-	// Fetch available items from the target content type
-	const { items: availableItems, isLoading } = useContent(relation.targetType, {
-		limit: 100, // Load a good chunk for the dropdown
-	});
+	const listClient = useMemo(
+		() =>
+			createApiClient<CMSApiRouter>({
+				baseURL: apiBaseURL,
+				basePath: apiBasePath,
+			}),
+		[apiBaseURL, apiBasePath],
+	);
 
-	// Mutation for creating new items
-	const createMutation = useCreateContent(relation.targetType);
+	const cmsQueries = useMemo(
+		() => createCMSQueryKeys(listClient, headers),
+		[listClient, headers],
+	);
+
+	// For belongsTo (single relation), we only allow one selection
+	const isSingleSelect = relation.type === "belongsTo";
 
 	// Normalize the field value to an array for internal use
 	// belongsTo stores as single object { id }, hasMany/manyToMany store as array
@@ -72,36 +98,95 @@ export function RelationField({
 		return (field.value as Array<{ id: string }>) || [];
 	}, [field.value, isSingleSelect]);
 
-	// Convert normalized value to Option[] for MultipleSelector
-	const selectedOptions: Option[] = normalizedValue
-		.map((v) => {
-			const item = availableItems.find((item) => item.id === v.id);
-			if (item) {
-				const displayValue =
-					(item.parsedData as Record<string, unknown>)?.[
-						relation.displayField
-					] || item.slug;
-				return {
-					value: item.id,
-					label: String(displayValue),
-				};
+	// Fetch available items from the target content type (first page only)
+	const { items: availableItems, isLoading } = useContent(relation.targetType, {
+		limit: 500,
+	});
+
+	const missingDetailIds = useMemo(() => {
+		const loadedIds = new Set(availableItems.map((i) => i.id));
+		return normalizedValue
+			.map((v) => v.id)
+			.filter((id) => id.length > 0 && !loadedIds.has(id));
+	}, [availableItems, normalizedValue]);
+
+	const hydrationResult = useQueries({
+		queries: missingDetailIds.map((id) => ({
+			...cmsQueries.cmsContent.detail(relation.targetType, id),
+			...RELATION_DETAIL_QUERY_OPTS,
+			enabled: Boolean(relation.targetType && id),
+		})),
+		combine: (results) => ({
+			data: results.map(
+				(r) => r.data as SerializedContentItemWithType | null | undefined,
+			),
+			isHydrating: results.some((r) => r.isFetching),
+		}),
+	});
+
+	const isHydratingLabels = hydrationResult.isHydrating;
+
+	const itemById = useMemo(() => {
+		const m = new Map<string, SerializedContentItemWithType>();
+		for (const it of availableItems) {
+			m.set(it.id, it as SerializedContentItemWithType);
+		}
+		for (let i = 0; i < missingDetailIds.length; i++) {
+			const row = hydrationResult.data[i];
+			if (row?.id) {
+				m.set(row.id, row);
 			}
-			// Item not found in loaded items - show ID
-			return { value: v.id, label: `ID: ${v.id.slice(0, 8)}...` };
-		})
-		.filter(Boolean);
+		}
+		return m;
+	}, [availableItems, missingDetailIds, hydrationResult.data]);
 
-	// Convert available items to options
-	const options: Option[] = availableItems.map((item) => {
-		const displayValue =
-			(item.parsedData as Record<string, unknown>)?.[relation.displayField] ||
-			item.slug;
-		return {
-			value: item.id,
-			label: String(displayValue),
-		};
+	// Convert normalized value to Option[] for MultipleSelector
+	const selectedOptions: Option[] = normalizedValue.map((v) => {
+		const item = itemById.get(v.id);
+		if (item) {
+			const displayValue =
+				(item.parsedData as Record<string, unknown>)?.[relation.displayField] ||
+				item.slug;
+			return {
+				value: item.id,
+				label: String(displayValue),
+			};
+		}
+		return { value: v.id, label: `ID: ${v.id.slice(0, 8)}...` };
 	});
 
+	// Listed options + any selected partners loaded by id (not on first list page)
+	const options: Option[] = useMemo(() => {
+		const merged: SerializedContentItemWithType[] = [
+			...(availableItems as SerializedContentItemWithType[]),
+		];
+		const seen = new Set(merged.map((x) => x.id));
+		for (let i = 0; i < missingDetailIds.length; i++) {
+			const row = hydrationResult.data[i];
+			if (row?.id && !seen.has(row.id)) {
+				merged.push(row);
+				seen.add(row.id);
+			}
+		}
+		return merged.map((item) => {
+			const displayValue =
+				(item.parsedData as Record<string, unknown>)?.[relation.displayField] ||
+				item.slug;
+			return {
+				value: item.id,
+				label: String(displayValue),
+			};
+		});
+	}, [
+		availableItems,
+		hydrationResult.data,
+		missingDetailIds,
+		relation.displayField,
+	]);
+
+	// Mutation for creating new items
+	const createMutation = useCreateContent(relation.targetType);
+
 	// Handle selection change - convert back to appropriate format
 	const handleChange = useCallback(
 		(newOptions: Option[]) => {
@@ -187,11 +272,11 @@ export function RelationField({
 						onChange={handleChange}
 						options={options}
 						placeholder={
-							isLoading
+							isLoading || isHydratingLabels
 								? "Loading..."
 								: `Select ${relation.targetType}${isSingleSelect ? "" : "(s)"}...`
 						}
-						disabled={isLoading}
+						disabled={isLoading || isHydratingLabels}
 						hidePlaceholderWhenSelected
 						emptyIndicator={
 							<p className="text-center text-sm text-muted-foreground py-4">

package/src/plugins/cms/schemas.ts

@@ -1,13 +1,33 @@
 import { z } from "zod";
 
+/** Default upper bound for a single page when no maxPageSize is configured. */
+export const DEFAULT_MAX_PAGE_SIZE = 1000;
+
 /**
- * Schema for listing content items with pagination
+ * Factory that creates the list-content query schema with a configurable
+ * upper bound on the `limit` parameter.
+ *
+ * Use this inside the backend plugin factory (where `config.maxPageSize` is
+ * available) so the cap is set at registration time rather than hardcoded.
  */
-export const listContentQuerySchema = z.object({
-	slug: z.string().optional(),
-	limit: z.coerce.number().min(1).max(100).optional().default(20),
-	offset: z.coerce.number().min(0).optional().default(0),
-});
+export function createListContentQuerySchema(
+	maxPageSize = DEFAULT_MAX_PAGE_SIZE,
+) {
+	return z.object({
+		slug: z.string().optional(),
+		limit: z.coerce.number().min(1).max(maxPageSize).optional().default(20),
+		offset: z.coerce.number().min(0).optional().default(0),
+	});
+}
+
+/**
+ * Schema for listing content items with pagination.
+ * Uses the default maxPageSize (1000).
+ *
+ * @deprecated Prefer {@link createListContentQuerySchema} inside plugin
+ * factories so consumers can configure the upper bound via `maxPageSize`.
+ */
+export const listContentQuerySchema = createListContentQuerySchema();
 
 /**
  * Schema for creating a content item

package/src/plugins/cms/types.ts

@@ -303,4 +303,14 @@ export interface CMSBackendConfig {
 	contentTypes: ContentTypeConfig[];
 	/** Optional hooks for customizing behavior */
 	hooks?: CMSBackendHooks;
+	/**
+	 * Maximum number of items that can be requested in a single page.
+	 * Applied to all list endpoints (`/content/:typeSlug`, by-relation, and inverse-relation).
+	 *
+	 * Raise this when your content types have many items and you need to fetch
+	 * large pages (e.g. for SSG, CSV export, or programmatic access).
+	 *
+	 * @default 1000
+	 */
+	maxPageSize?: number;
 }

package/src/plugins/comments/api/query-key-defs.ts

@@ -71,6 +71,7 @@ export interface CommentsThreadDiscriminator {
 	parentId: string | null | undefined;
 	status: string | undefined;
 	currentUserId: string | undefined;
+	sort: string | undefined;
 	limit: number;
 }
 
@@ -80,6 +81,7 @@ export function commentsThreadDiscriminator(params?: {
 	parentId?: string | null;
 	status?: string;
 	currentUserId?: string;
+	sort?: string;
 	limit?: number;
 }): CommentsThreadDiscriminator {
 	return {
@@ -88,6 +90,7 @@ export function commentsThreadDiscriminator(params?: {
 		parentId: params?.parentId,
 		status: params?.status,
 		currentUserId: params?.currentUserId,
+		sort: params?.sort,
 		limit: params?.limit ?? 20,
 	};
 }
@@ -128,7 +131,7 @@ export const COMMENTS_QUERY_KEYS = {
 
 	/**
 	 * Key for the infinite thread query (top-level comments, load-more).
-	 * Full key: ["commentsThread", "list", { resourceId, resourceType, parentId, status, currentUserId, limit }]
+	 * Full key: ["commentsThread", "list", { resourceId, resourceType, parentId, status, currentUserId, sort, limit }]
 	 * Offset is excluded — it is driven by `pageParam`, not baked into the key.
 	 */
 	commentsThread: (params?: {
@@ -137,6 +140,7 @@ export const COMMENTS_QUERY_KEYS = {
 		parentId?: string | null;
 		status?: string;
 		currentUserId?: string;
+		sort?: string;
 		limit?: number;
 	}) =>
 		["commentsThread", "list", commentsThreadDiscriminator(params)] as const,

package/src/plugins/comments/client/components/comment-thread.tsx

@@ -98,6 +98,17 @@ export interface CommentThreadProps {
 	 * Defaults to true.
 	 */
 	allowEditing?: boolean;
+	/**
+	 * Sort direction for top-level comments by `createdAt`.
+	 * - `"desc"` (default): newest first.
+	 * - `"asc"`: oldest first.
+	 *
+	 * Replies inside each thread always render chronologically (oldest → newest)
+	 * and are unaffected by this prop.
+	 *
+	 * Overrides the global `defaultCommentSort` from `CommentsPluginOverrides`.
+	 */
+	sort?: "asc" | "desc";
 }
 
 const DEFAULT_RENDERER: ComponentType<CommentRendererProps> = ({ body }) => (
@@ -325,6 +336,7 @@ function CommentThreadInner({
 	pageSize: pageSizeProp,
 	allowPosting: allowPostingProp,
 	allowEditing: allowEditingProp,
+	sort: sortProp,
 }: CommentThreadProps) {
 	const overrides = usePluginOverrides<
 		CommentsPluginOverrides,
@@ -334,6 +346,7 @@ function CommentThreadInner({
 		pageSizeProp ?? overrides.defaultCommentPageSize ?? DEFAULT_PAGE_SIZE;
 	const allowPosting = allowPostingProp ?? overrides.allowPosting ?? true;
 	const allowEditing = allowEditingProp ?? overrides.allowEditing ?? true;
+	const sort = sortProp ?? overrides.defaultCommentSort ?? "desc";
 	const loc = { ...COMMENTS_LOCALIZATION, ...localizationProp };
 	const [replyingTo, setReplyingTo] = useState<string | null>(null);
 	const [expandedReplies, setExpandedReplies] = useState<Set<string>>(
@@ -357,6 +370,7 @@ function CommentThreadInner({
 		status: "approved",
 		parentId: null,
 		currentUserId,
+		sort,
 		pageSize,
 	});
 
@@ -366,6 +380,7 @@ function CommentThreadInner({
 		currentUserId,
 		infiniteKey: threadQueryKey,
 		pageSize,
+		sort,
 	});
 
 	const handlePost = async (body: string) => {

package/src/plugins/comments/client/hooks/use-comments.tsx

@@ -164,6 +164,11 @@ export function useInfiniteComments(
 		parentId?: string | null;
 		status?: "pending" | "approved" | "spam";
 		currentUserId?: string;
+		/**
+		 * Sort direction by `createdAt`. Default: `"asc"` (oldest first) — matches
+		 * the server-side default. Pass `"desc"` for newest-first threads.
+		 */
+		sort?: "asc" | "desc";
 		pageSize?: number;
 	},
 	options?: { enabled?: boolean },
@@ -178,6 +183,7 @@ export function useInfiniteComments(
 		parentId: params.parentId ?? null,
 		status: params.status,
 		currentUserId: params.currentUserId,
+		sort: params.sort,
 		limit: pageSize,
 	});
 
@@ -266,6 +272,17 @@ export function usePostComment(
 		 * `nextOffset` from `lastPage.limit` instead of a hardcoded fallback.
 		 */
 		pageSize?: number;
+		/**
+		 * Sort direction of the surrounding infinite thread.
+		 * - `"asc"` (default): newest comments belong on the LAST page → optimistic
+		 *   item is appended to `pages[last].items`.
+		 * - `"desc"`: newest comments belong on the FIRST page → optimistic item
+		 *   is prepended to `pages[0].items`.
+		 *
+		 * Must match the `sort` passed to `useInfiniteComments` so the optimistic
+		 * item appears in the same position the server will place it.
+		 */
+		sort?: "asc" | "desc";
 	},
 ) {
 	const queryClient = useQueryClient();
@@ -350,6 +367,7 @@ export function usePostComment(
 				const previous =
 					queryClient.getQueryData<InfiniteData<CommentListResult>>(listKey);
 
+				const isDesc = params.sort === "desc";
 				queryClient.setQueryData<InfiniteData<CommentListResult>>(
 					listKey,
 					(old) => {
@@ -366,16 +384,21 @@ export function usePostComment(
 								pageParams: [0],
 							};
 						}
-						const lastIdx = old.pages.length - 1;
+						// For asc (oldest-first) threads the new comment lives at the end →
+						// append to the last page. For desc (newest-first) threads it lives
+						// at the top → prepend to the first page.
+						const targetIdx = isDesc ? 0 : old.pages.length - 1;
 						return {
 							...old,
 							// Increment `total` on every page so the header count (which reads
 							// pages[0].total) stays in sync even after multiple pages are loaded.
 							pages: old.pages.map((page, idx) =>
-								idx === lastIdx
+								idx === targetIdx
 									? {
 											...page,
-											items: [...page.items, optimistic],
+											items: isDesc
+												? [optimistic, ...page.items]
+												: [...page.items, optimistic],
 											total: page.total + 1,
 										}
 									: { ...page, total: page.total + 1 },

package/src/plugins/comments/client/overrides.ts

@@ -75,6 +75,16 @@ export interface CommentsPluginOverrides {
 	 */
 	defaultCommentPageSize?: number;
 
+	/**
+	 * Default sort direction (by `createdAt`) for top-level comments in
+	 * `CommentThread`.
+	 * - `"desc"` (default): newest comments first.
+	 * - `"asc"`: oldest comments first.
+	 *
+	 * Can be overridden per-instance via the `sort` prop on `CommentThread`.
+	 */
+	defaultCommentSort?: "asc" | "desc";
+
 	/**
 	 * When false, the comment form and reply buttons are hidden in all
 	 * `CommentThread` instances. Users can still read existing comments.

package/src/plugins/comments/query-keys.ts

@@ -142,6 +142,7 @@ function createCommentsThreadQueries(
 			parentId?: string | null;
 			status?: "pending" | "approved" | "spam";
 			currentUserId?: string;
+			sort?: "asc" | "desc";
 			limit?: number;
 		}) => ({
 			// Offset is excluded from the key — it is driven by pageParam.
@@ -162,6 +163,7 @@ function createCommentsThreadQueries(
 						// The server resolves the caller's identity server-side via the
 						// resolveCurrentUserId hook. It is still included in the queryKey
 						// above for client-side cache segregation.
+						sort: params?.sort,
 						limit: params?.limit ?? 20,
 						offset: pageParam ?? 0,
 					},