@btst/stack 2.12.2 → 3.0.0-rc.1

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

@@ -1,4 +1,5 @@
 import type { DBAdapter as Adapter } from "@btst/db";
+import { DEFAULT_MAX_PAGE_SIZE } from "../schemas";
 import type {
 	ContentType,
 	ContentItem,
@@ -107,7 +108,32 @@ export async function getAllContentTypes(
 }
 
 /**
- * Retrieve all content items for a given content type, with optional pagination.
+ * Case-insensitive substring match against an item's slug and the string
+ * values of its parsed data (one level deep — nested objects/arrays of
+ * primitives are scanned, deeper structures are skipped).
+ */
+function contentItemMatchesSearch(
+	item: SerializedContentItemWithType,
+	searchLower: string,
+): boolean {
+	if (item.slug.toLowerCase().includes(searchLower)) return true;
+
+	const matchesValue = (value: unknown): boolean =>
+		typeof value === "string" && value.toLowerCase().includes(searchLower);
+
+	return Object.values(item.parsedData).some((value) => {
+		if (matchesValue(value)) return true;
+		if (Array.isArray(value)) return value.some(matchesValue);
+		if (typeof value === "object" && value !== null) {
+			return Object.values(value).some(matchesValue);
+		}
+		return false;
+	});
+}
+
+/**
+ * Retrieve all content items for a given content type, with optional pagination
+ * and free-text search.
  * Pure DB function — no hooks, no HTTP context. Safe for SSG and server-side use.
  *
  * @remarks **Security:** Authorization hooks (e.g. `onBeforeListItems`) are NOT
@@ -116,12 +142,13 @@ export async function getAllContentTypes(
  *
  * @param adapter - The database adapter
  * @param contentTypeSlug - The slug of the content type to query
- * @param params - Optional filter/pagination parameters
+ * @param params - Optional filter/pagination parameters. `search` matches
+ * case-insensitively against item slugs and string values in the item data.
  */
 export async function getAllContentItems(
 	adapter: Adapter,
 	contentTypeSlug: string,
-	params?: { slug?: string; limit?: number; offset?: number },
+	params?: { slug?: string; limit?: number; offset?: number; search?: string },
 ): Promise<{
 	items: SerializedContentItemWithType[];
 	total: number;
@@ -168,24 +195,58 @@ export async function getAllContentItems(
 		});
 	}
 
+	// Free-text search must remain in-memory: item data is stored as a JSON
+	// string, so the adapter cannot match individual field values. All other
+	// filters above are pushed to DB; when searching, pagination happens
+	// after the in-memory pass so `total` reflects the filtered set.
+	// The DB scan is capped at DEFAULT_MAX_PAGE_SIZE to bound memory use;
+	// items beyond the cap are not searched.
+	const search = params?.search?.trim();
+	const needsInMemoryFilter = !!search;
+
 	// TODO: remove cast once @btst/db types expose adapter.count()
-	const total: number = await adapter.count({
-		model: "contentItem",
-		where: whereConditions,
-	});
+	const dbTotal: number | undefined = !needsInMemoryFilter
+		? await adapter.count({
+				model: "contentItem",
+				where: whereConditions,
+			})
+		: undefined;
 
 	const items = await adapter.findMany<ContentItemWithType>({
 		model: "contentItem",
 		where: whereConditions,
-		limit: params?.limit,
-		offset: params?.offset,
+		limit: !needsInMemoryFilter ? params?.limit : DEFAULT_MAX_PAGE_SIZE,
+		offset: !needsInMemoryFilter ? params?.offset : undefined,
 		sortBy: { field: "createdAt", direction: "desc" },
 		join: { contentType: true },
 	});
 
+	let result = items.map(serializeContentItemWithType);
+
+	if (needsInMemoryFilter) {
+		const searchLower = search.toLowerCase();
+		result = result.filter((item) =>
+			contentItemMatchesSearch(item, searchLower),
+		);
+
+		const total = result.length;
+		const offset = params?.offset ?? 0;
+		const limit = params?.limit;
+		result = result.slice(
+			offset,
+			limit !== undefined ? offset + limit : undefined,
+		);
+		return {
+			items: result,
+			total,
+			limit: params?.limit,
+			offset: params?.offset,
+		};
+	}
+
 	return {
-		items: items.map(serializeContentItemWithType),
-		total,
+		items: result,
+		total: dbTotal ?? result.length,
 		limit: params?.limit,
 		offset: params?.offset,
 	};

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

@@ -41,7 +41,7 @@ import {
 } from "./relations";
 import type { QueryClient } from "@tanstack/react-query";
 import { CMS_QUERY_KEYS } from "./query-key-defs";
-import { runHookWithShim } from "../../utils";
+import { runHook } from "../../utils";
 
 /**
  * Route keys for the CMS plugin — matches the keys returned by
@@ -595,14 +595,19 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) => {
 				},
 				async (ctx) => {
 					const { typeSlug } = ctx.params;
-					const { slug, limit, offset } = ctx.query;
+					const { slug, search, limit, offset } = ctx.query;
 
 					const contentType = await getContentType(typeSlug);
 					if (!contentType) {
 						throw ctx.error(404, { message: "Content type not found" });
 					}
 
-					return getAllContentItems(adapter, typeSlug, { slug, limit, offset });
+					return getAllContentItems(adapter, typeSlug, {
+						slug,
+						search,
+						limit,
+						offset,
+					});
 				},
 			);
 
@@ -680,9 +685,12 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) => {
 					const zodSchema = getContentTypeZodSchema(contentType);
 					const validation = zodSchema.safeParse(dataWithResolvedRelations);
 					if (!validation.success) {
+						// `issues` matches the shape better-call emits for body
+						// validation errors, so clients get field-level errors
+						// (StackError.errors) for inline form display.
 						throw ctx.error(400, {
 							message: "Validation failed",
-							errors: validation.error.issues,
+							issues: validation.error.issues,
 						});
 					}
 
@@ -707,7 +715,7 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) => {
 					// Call before hook - may deny operation
 					const processedData = validation.data as Record<string, unknown>;
 					if (config.hooks?.onBeforeCreate) {
-						await runHookWithShim(
+						await runHook(
 							() => config.hooks!.onBeforeCreate!(processedData, context),
 							ctx.error,
 							"Create operation denied",
@@ -837,9 +845,10 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) => {
 						const zodSchema = getContentTypeZodSchema(contentType);
 						const validation = zodSchema.safeParse(mergedData);
 						if (!validation.success) {
+							// See the create endpoint: `issues` → StackError.errors
 							throw ctx.error(400, {
 								message: "Validation failed",
-								errors: validation.error.issues,
+								issues: validation.error.issues,
 							});
 						}
 						validatedData = validation.data as Record<string, unknown>;
@@ -848,7 +857,7 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) => {
 					// Call before hook - may deny operation
 					const processedData = validatedData;
 					if (config.hooks?.onBeforeUpdate && validatedData) {
-						await runHookWithShim(
+						await runHook(
 							() => config.hooks!.onBeforeUpdate!(id, validatedData, context),
 							ctx.error,
 							"Update operation denied",
@@ -919,7 +928,7 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) => {
 
 					// Call before hook
 					if (config.hooks?.onBeforeDelete) {
-						await runHookWithShim(
+						await runHook(
 							() => config.hooks!.onBeforeDelete!(id, context),
 							ctx.error,
 							"Delete operation denied",

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

@@ -8,21 +8,29 @@ export interface ContentListDiscriminator {
 	typeSlug: string;
 	limit: number;
 	offset: number;
+	search: string | undefined;
 }
 
 /**
  * Builds the discriminator object used as the cache key for the content list.
- * Mirrors the params object used in createContentQueries.list so both paths stay in sync.
+ * Mirrors the params object used in the cmsContent.list resource declaration
+ * so both paths stay in sync. An empty/whitespace search term is normalized
+ * to `undefined` so it hashes identically to "no search".
  */
 export function contentListDiscriminator(params: {
 	typeSlug: string;
 	limit?: number;
 	offset?: number;
+	search?: string;
 }): ContentListDiscriminator {
 	return {
 		typeSlug: params.typeSlug,
 		limit: params.limit ?? 20,
 		offset: params.offset ?? 0,
+		search:
+			params.search !== undefined && params.search.trim() === ""
+				? undefined
+				: params.search,
 	};
 }
 
@@ -36,12 +44,13 @@ export const CMS_QUERY_KEYS = {
 
 	/**
 	 * Key for the cmsContent.list({ typeSlug, limit, offset }) query.
-	 * Full key: ["cmsContent", "list", { typeSlug, limit, offset }]
+	 * Full key: ["cmsContent", "list", { typeSlug, limit, offset, search }]
 	 */
 	contentList: (params: {
 		typeSlug: string;
 		limit?: number;
 		offset?: number;
+		search?: string;
 	}) => ["cmsContent", "list", contentListDiscriminator(params)] as const,
 
 	/**

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

@@ -2,6 +2,7 @@
 
 import { useState, useMemo, useEffect, useRef } from "react";
 import { z } from "zod";
+import type { FieldPath, FieldValues, UseFormReturn } from "react-hook-form";
 import { SteppedAutoForm } from "@workspace/ui/components/auto-form/stepped-auto-form";
 import type {
 	FieldConfig,
@@ -12,11 +13,10 @@ import { formSchemaToZod } from "@workspace/ui/lib/schema-converter";
 import { Input } from "@workspace/ui/components/input";
 import { Label } from "@workspace/ui/components/label";
 import { Badge } from "@workspace/ui/components/badge";
-import { usePluginOverrides } from "@btst/stack/context";
+import { usePluginOverrides, useTranslate } from "@btst/stack/context";
 import type { CMSPluginOverrides } from "../../overrides";
 import type { SerializedContentType, RelationConfig } from "../../../types";
 import { slugify } from "../../../utils";
-import { CMS_LOCALIZATION } from "../../localization";
 import { CMSFileUpload } from "./file-upload";
 import { RelationField } from "./relation-field";
 
@@ -30,6 +30,49 @@ interface ContentFormProps {
 		data: Record<string, unknown>;
 	}) => Promise<void>;
 	onCancel?: () => void;
+	/**
+	 * Server-side field validation errors (`StackError.errors`), applied to
+	 * the matching form fields for inline display.
+	 */
+	fieldErrors?: Record<string, string | string[]>;
+	/** Non-field submit error to display above the form */
+	errorMessage?: string;
+	/** External submit-in-flight state (e.g. from a resource `useForm`) */
+	isSubmitting?: boolean;
+}
+
+/**
+ * Applies server-side field validation errors onto react-hook-form field
+ * state, and clears previously applied server errors that are no longer
+ * present. The form instance arrives asynchronously (captured from
+ * SteppedAutoForm's `onValuesChange`) and is `null` for multi-step forms.
+ */
+function useServerFieldErrors<T extends FieldValues>(
+	form: UseFormReturn<T> | null,
+	fieldErrors: Record<string, string | string[]>,
+) {
+	const appliedFieldsRef = useRef<string[]>([]);
+
+	useEffect(() => {
+		if (!form) return;
+
+		// Clear stale server errors from fields that are no longer failing
+		for (const field of appliedFieldsRef.current) {
+			if (field in fieldErrors) continue;
+			const { error } = form.getFieldState(field as FieldPath<T>);
+			if (error?.type === "server") {
+				form.clearErrors(field as FieldPath<T>);
+			}
+		}
+		appliedFieldsRef.current = Object.keys(fieldErrors);
+
+		for (const [field, message] of Object.entries(fieldErrors)) {
+			form.setError(field as FieldPath<T>, {
+				type: "server",
+				message: Array.isArray(message) ? message.join(", ") : message,
+			});
+		}
+	}, [fieldErrors, form]);
 }
 
 /**
@@ -204,24 +247,39 @@ export function ContentForm({
 	isEditing = false,
 	onSubmit,
 	onCancel,
+	fieldErrors,
+	errorMessage,
+	isSubmitting: isSubmittingProp,
 }: ContentFormProps) {
+	const t = useTranslate();
 	const {
-		localization: customLocalization,
+		localization,
 		uploadImage,
 		imagePicker,
 		imageInputField,
 		fieldComponents,
 	} = usePluginOverrides<CMSPluginOverrides>("cms");
-	const localization = { ...CMS_LOCALIZATION, ...customLocalization };
 
 	const [slug, setSlug] = useState(initialSlug);
 	const [slugManuallyEdited, setSlugManuallyEdited] = useState(isEditing);
-	const [isSubmitting, setIsSubmitting] = useState(false);
+	const [isSubmittingLocal, setIsSubmittingLocal] = useState(false);
 	const [formData, setFormData] =
 		useState<Record<string, unknown>>(initialData);
 	const [slugError, setSlugError] = useState<string | null>(null);
 	const [submitError, setSubmitError] = useState<string | null>(null);
 
+	const isSubmitting = isSubmittingProp || isSubmittingLocal;
+
+	// Single-step forms pass their react-hook-form instance through
+	// onValuesChange; multi-step forms pass undefined (no single instance).
+	const [formInstance, setFormInstance] = useState<UseFormReturn<
+		Record<string, unknown>
+	> | null>(null);
+
+	const serverFieldErrors = useMemo(() => fieldErrors ?? {}, [fieldErrors]);
+	useServerFieldErrors(formInstance, serverFieldErrors);
+	const hasFieldErrors = Object.keys(serverFieldErrors).length > 0;
+
 	// Track if we've already synced prefill data to avoid overwriting user input
 	const hasSyncedPrefillRef = useRef(false);
 
@@ -290,7 +348,13 @@ export function ContentForm({
 	);
 
 	// Handle form value changes for slug auto-generation
-	const handleValuesChange = (values: Record<string, unknown>) => {
+	const handleValuesChange = (
+		values: Record<string, unknown>,
+		form?: UseFormReturn<Record<string, unknown>>,
+	) => {
+		if (form) {
+			setFormInstance((current) => (current === form ? current : form));
+		}
 		setFormData(values);
 
 		// Auto-generate slug from source field if not manually edited
@@ -308,33 +372,58 @@ export function ContentForm({
 		setSubmitError(null);
 
 		if (!slug.trim()) {
-			setSlugError("Slug is required");
+			setSlugError(
+				localization?.CMS_EDITOR_SLUG_REQUIRED ??
+					t("cms.editor.slugRequired", "Slug is required"),
+			);
 			return;
 		}
 
-		setIsSubmitting(true);
+		setIsSubmittingLocal(true);
 		try {
 			await onSubmit({ slug, data });
 		} catch (error) {
 			const message =
-				error instanceof Error ? error.message : localization.CMS_TOAST_ERROR;
+				error instanceof Error
+					? error.message
+					: (localization?.CMS_TOAST_ERROR ??
+						t("cms.toasts.error", "An error occurred. Please try again."));
 			setSubmitError(message);
 		} finally {
-			setIsSubmitting(false);
+			setIsSubmittingLocal(false);
 		}
 	};
 
+	// Non-field error from the parent (resource form), or a local submit
+	// failure. Field errors display inline instead — unless the form
+	// instance is unavailable (multi-step), where they land in the banner.
+	const bannerMessage =
+		errorMessage ??
+		submitError ??
+		(hasFieldErrors && !formInstance
+			? Object.entries(serverFieldErrors)
+					.map(
+						([field, message]) =>
+							`${field}: ${Array.isArray(message) ? message.join(", ") : message}`,
+					)
+					.join(" · ")
+			: undefined);
+
 	return (
 		<div className="space-y-6">
 			{/* Slug field */}
 			<div className="space-y-2">
 				<div className="flex items-center gap-2">
-					<Label htmlFor="slug">{localization.CMS_LABEL_SLUG}</Label>
+					<Label htmlFor="slug">
+						{localization?.CMS_LABEL_SLUG ?? t("cms.common.slugLabel", "Slug")}
+					</Label>
 					{!isEditing && (
 						<Badge variant="outline" className="text-xs">
 							{slugManuallyEdited
-								? localization.CMS_EDITOR_SLUG_MANUAL
-								: localization.CMS_EDITOR_SLUG_AUTO}
+								? (localization?.CMS_EDITOR_SLUG_MANUAL ??
+									t("cms.editor.slugManual", "Manually set"))
+								: (localization?.CMS_EDITOR_SLUG_AUTO ??
+									t("cms.editor.slugAuto", "Auto-generated from first field"))}
 						</Badge>
 					)}
 				</div>
@@ -351,20 +440,31 @@ export function ContentForm({
 					disabled={isEditing}
 					placeholder={
 						slugSourceField
-							? `Auto-generated from ${slugSourceField}`
-							: "Enter slug..."
+							? (
+									localization?.CMS_EDITOR_SLUG_PLACEHOLDER_AUTO ??
+									t(
+										"cms.editor.slugPlaceholderAuto",
+										"Auto-generated from {field}",
+									)
+								).replace("{field}", slugSourceField)
+							: (localization?.CMS_EDITOR_SLUG_PLACEHOLDER ??
+								t("cms.editor.slugPlaceholder", "Enter slug..."))
 					}
 				/>
 				{slugError && <p className="text-sm text-destructive">{slugError}</p>}
 				<p className="text-sm text-muted-foreground">
-					{localization.CMS_LABEL_SLUG_DESCRIPTION}
+					{localization?.CMS_LABEL_SLUG_DESCRIPTION ??
+						t(
+							"cms.common.slugDescription",
+							"URL-friendly identifier for this item",
+						)}
 				</p>
 			</div>
 
 			{/* Submit error message */}
-			{submitError && (
+			{bannerMessage && (
 				<div className="rounded-md border border-destructive/50 bg-destructive/10 p-3">
-					<p className="text-sm text-destructive">{submitError}</p>
+					<p className="text-sm text-destructive">{bannerMessage}</p>
 				</div>
 			)}
 
@@ -379,8 +479,9 @@ export function ContentForm({
 				isSubmitting={isSubmitting}
 				submitButtonText={
 					isSubmitting
-						? localization.CMS_STATUS_SAVING
-						: localization.CMS_BUTTON_SAVE
+						? (localization?.CMS_STATUS_SAVING ??
+							t("cms.common.saving", "Saving..."))
+						: (localization?.CMS_BUTTON_SAVE ?? t("cms.common.save", "Save"))
 				}
 			>
 				{onCancel && (
@@ -389,7 +490,8 @@ export function ContentForm({
 						onClick={onCancel}
 						className="px-4 py-2 text-sm text-muted-foreground hover:text-foreground"
 					>
-						{localization.CMS_BUTTON_CANCEL}
+						{localization?.CMS_BUTTON_CANCEL ??
+							t("cms.common.cancel", "Cancel")}
 					</button>
 				)}
 			</SteppedAutoForm>

package/src/plugins/cms/client/components/forms/file-upload.tsx

@@ -7,7 +7,12 @@ import {
 	type ChangeEvent,
 	type ComponentType,
 } from "react";
-import { toast } from "sonner";
+import {
+	useNotify,
+	usePluginOverrides,
+	useTranslate,
+} from "@btst/stack/context";
+import type { CMSPluginOverrides } from "../../overrides";
 import type { AutoFormInputComponentProps } from "@workspace/ui/components/auto-form/types";
 import { Input } from "@workspace/ui/components/input";
 import { Button } from "@workspace/ui/components/button";
@@ -87,6 +92,9 @@ export function CMSFileUpload({
 	const showLabel = _showLabel === undefined ? true : _showLabel;
 
 	// All hooks must be called unconditionally before any early return.
+	const t = useTranslate();
+	const notify = useNotify();
+	const { localization } = usePluginOverrides<CMSPluginOverrides>("cms");
 	const [isUploading, setIsUploading] = useState(false);
 	const [previewUrl, setPreviewUrl] = useState<string | null>(
 		field.value || null,
@@ -105,7 +113,10 @@ export function CMSFileUpload({
 			if (!file) return;
 
 			if (!file.type.startsWith("image/")) {
-				toast.error("Please select an image file");
+				notify.error(
+					localization?.CMS_EDITOR_FILE_INVALID_TYPE ??
+						t("cms.editor.fileInvalidType", "Please select an image file"),
+				);
 				return;
 			}
 
@@ -116,12 +127,15 @@ export function CMSFileUpload({
 				field.onChange(url);
 			} catch (error) {
 				console.error("Image upload failed:", error);
-				toast.error("Failed to upload image");
+				notify.error(
+					localization?.CMS_EDITOR_FILE_UPLOAD_FAILED ??
+						t("cms.editor.fileUploadFailed", "Failed to upload image"),
+				);
 			} finally {
 				setIsUploading(false);
 			}
 		},
-		[field, uploadImage],
+		[field, uploadImage, notify, localization, t],
 	);
 
 	const handleRemove = useCallback(() => {