@btst/stack 2.12.2 → 3.0.0-rc.2

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

@@ -1,37 +1,15 @@
 "use client";
 
-import { createApiClient } from "@btst/stack/plugins/client";
-import {
-	useInfiniteQuery,
-	useMutation,
-	useQuery,
-	useQueryClient,
-	useSuspenseInfiniteQuery,
-	useSuspenseQuery,
-	type InfiniteData,
-} from "@tanstack/react-query";
-import type { SerializedPost, SerializedTag } from "../../types";
-import type { BlogApiRouter } from "../../api/plugin";
-import { useDebounce } from "./use-debounce";
 import { useEffect, useRef } from "react";
 import { z } from "zod";
-import { createPostSchema, updatePostSchema } from "../../schemas";
-import { createBlogQueryKeys } from "../../query-keys";
-import { usePluginOverrides } from "@btst/stack/context";
-import type { BlogPluginOverrides } from "../overrides";
-
-/**
- * Shared React Query configuration for all blog queries
- * Prevents automatic refetching to avoid hydration mismatches in SSR
- */
-const SHARED_QUERY_CONFIG = {
-	retry: false,
-	refetchOnWindowFocus: false,
-	refetchOnMount: false,
-	refetchOnReconnect: false,
-	staleTime: 1000 * 60 * 5, // 5 minutes
-	gcTime: 1000 * 60 * 10, // 10 minutes
-} as const;
+import type {
+	ResourceFormConfig,
+	ResourceFormResult,
+} from "@btst/stack/plugins/client/hooks";
+import type { SerializedPost, SerializedTag } from "../../types";
+import type { createPostSchema, updatePostSchema } from "../../schemas";
+import { useDebounce } from "./use-debounce";
+import { blog } from "./blog-resource";
 
 /**
  * Options for the usePosts hook
@@ -132,31 +110,7 @@ export type PostUpdateInput = z.infer<typeof updatePostSchema>;
  * Hook for fetching paginated posts with load more functionality
  */
 export function usePosts(options: UsePostsOptions = {}): UsePostsResult {
-	const { apiBaseURL, apiBasePath, headers } =
-		usePluginOverrides<BlogPluginOverrides>("blog");
-	const client = createApiClient<BlogApiRouter>({
-		baseURL: apiBaseURL,
-		basePath: apiBasePath,
-	});
-	const {
-		tag,
-		tagSlug,
-		limit = 10,
-		enabled = true,
-		query,
-		published,
-	} = options;
-	const queries = createBlogQueryKeys(client, headers);
-
-	const queryParams = {
-		tag,
-		tagSlug,
-		limit,
-		query,
-		published,
-	};
-
-	const basePosts = queries.posts.list(queryParams);
+	const { tagSlug, limit = 10, enabled = true, query, published } = options;
 
 	const {
 		data,
@@ -166,21 +120,11 @@ export function usePosts(options: UsePostsOptions = {}): UsePostsResult {
 		hasNextPage,
 		isFetchingNextPage,
 		refetch,
-	} = useInfiniteQuery({
-		...basePosts,
-		...SHARED_QUERY_CONFIG,
-		initialPageParam: 0,
-		getNextPageParam: (lastPage, allPages) => {
-			const posts = lastPage as SerializedPost[];
-			if (posts.length < limit) return undefined;
-			return allPages.length * limit;
-		},
-		enabled: enabled && !!client,
+	} = blog.posts.list.useInfinite([{ tagSlug, limit, query, published }], {
+		enabled,
 	});
 
-	const posts = ((
-		data as InfiniteData<SerializedPost[], number> | undefined
-	)?.pages?.flat() ?? []) as SerializedPost[];
+	const posts = data?.pages?.flat() ?? [];
 
 	return {
 		posts,
@@ -201,51 +145,12 @@ export function useSuspensePosts(options: UsePostsOptions = {}): {
 	isLoadingMore: boolean;
 	refetch: () => Promise<unknown>;
 } {
-	const { apiBaseURL, apiBasePath, headers } =
-		usePluginOverrides<BlogPluginOverrides>("blog");
-	const client = createApiClient<BlogApiRouter>({
-		baseURL: apiBaseURL,
-		basePath: apiBasePath,
-	});
-	const {
-		tag,
-		tagSlug,
-		limit = 10,
-		enabled = true,
-		query,
-		published,
-	} = options;
-	const queries = createBlogQueryKeys(client, headers);
+	const { tagSlug, limit = 10, query, published } = options;
 
-	const queryParams = { tag, tagSlug, limit, query, published };
-	const basePosts = queries.posts.list(queryParams);
+	const { data, fetchNextPage, hasNextPage, isFetchingNextPage, refetch } =
+		blog.posts.list.useSuspenseInfinite([{ tagSlug, limit, query, published }]);
 
-	const {
-		data,
-		fetchNextPage,
-		hasNextPage,
-		isFetchingNextPage,
-		refetch,
-		error,
-		isFetching,
-	} = useSuspenseInfiniteQuery({
-		...basePosts,
-		...SHARED_QUERY_CONFIG,
-		initialPageParam: 0,
-		getNextPageParam: (lastPage, allPages) => {
-			const posts = lastPage as SerializedPost[];
-			if (posts.length < limit) return undefined;
-			return allPages.length * limit;
-		},
-	});
-
-	// Manually throw errors for Error Boundaries (per React Query Suspense docs)
-	// useSuspenseQuery only throws errors if there's no data, but we want to throw always
-	if (error && !isFetching) {
-		throw error;
-	}
-
-	const posts = (data.pages?.flat() ?? []) as SerializedPost[];
+	const posts = data.pages?.flat() ?? [];
 
 	return {
 		posts,
@@ -260,25 +165,10 @@ export function useSuspensePosts(options: UsePostsOptions = {}): {
  * Hook for fetching a single post by slug
  */
 export function usePost(slug?: string): UsePostResult {
-	const { apiBaseURL, apiBasePath, headers } =
-		usePluginOverrides<BlogPluginOverrides>("blog");
-	const client = createApiClient<BlogApiRouter>({
-		baseURL: apiBaseURL,
-		basePath: apiBasePath,
-	});
-	const queries = createBlogQueryKeys(client, headers);
-
-	const basePost = queries.posts.detail(slug ?? "");
-	const { data, isLoading, error, refetch } = useQuery<
-		SerializedPost | null,
-		Error,
-		SerializedPost | null,
-		typeof basePost.queryKey
-	>({
-		...basePost,
-		...SHARED_QUERY_CONFIG,
-		enabled: !!client && !!slug,
-	});
+	const { data, isLoading, error, refetch } = blog.posts.detail.use(
+		[slug ?? ""],
+		{ enabled: !!slug },
+	);
 
 	return {
 		post: data || null,
@@ -293,29 +183,7 @@ export function useSuspensePost(slug: string): {
 	post: SerializedPost | null;
 	refetch: () => Promise<unknown>;
 } {
-	const { apiBaseURL, apiBasePath, headers } =
-		usePluginOverrides<BlogPluginOverrides>("blog");
-	const client = createApiClient<BlogApiRouter>({
-		baseURL: apiBaseURL,
-		basePath: apiBasePath,
-	});
-	const queries = createBlogQueryKeys(client, headers);
-	const basePost = queries.posts.detail(slug);
-	const { data, refetch, error, isFetching } = useSuspenseQuery<
-		SerializedPost | null,
-		Error,
-		SerializedPost | null,
-		typeof basePost.queryKey
-	>({
-		...basePost,
-		...SHARED_QUERY_CONFIG,
-	});
-
-	// Manually throw errors for Error Boundaries (per React Query Suspense docs)
-	// useSuspenseQuery only throws errors if there's no data, but we want to throw always
-	if (error && !isFetching) {
-		throw error;
-	}
+	const { data, refetch } = blog.posts.detail.useSuspense([slug]);
 
 	return { post: data || null, refetch };
 }
@@ -329,24 +197,7 @@ export function useTags(): {
 	error: Error | null;
 	refetch: () => void;
 } {
-	const { apiBaseURL, apiBasePath, headers } =
-		usePluginOverrides<BlogPluginOverrides>("blog");
-	const client = createApiClient<BlogApiRouter>({
-		baseURL: apiBaseURL,
-		basePath: apiBasePath,
-	});
-	const queries = createBlogQueryKeys(client, headers);
-	const baseTags = queries.tags.list();
-	const { data, isLoading, error, refetch } = useQuery<
-		SerializedTag[] | null,
-		Error,
-		SerializedTag[] | null,
-		typeof baseTags.queryKey
-	>({
-		...baseTags,
-		...SHARED_QUERY_CONFIG,
-		enabled: !!client,
-	});
+	const { data, isLoading, error, refetch } = blog.tags.list.use([]);
 
 	return {
 		tags: data ?? [],
@@ -361,29 +212,7 @@ export function useSuspenseTags(): {
 	tags: SerializedTag[];
 	refetch: () => Promise<unknown>;
 } {
-	const { apiBaseURL, apiBasePath, headers } =
-		usePluginOverrides<BlogPluginOverrides>("blog");
-	const client = createApiClient<BlogApiRouter>({
-		baseURL: apiBaseURL,
-		basePath: apiBasePath,
-	});
-	const queries = createBlogQueryKeys(client, headers);
-	const baseTags = queries.tags.list();
-	const { data, refetch, error, isFetching } = useSuspenseQuery<
-		SerializedTag[] | null,
-		Error,
-		SerializedTag[] | null,
-		typeof baseTags.queryKey
-	>({
-		...baseTags,
-		...SHARED_QUERY_CONFIG,
-	});
-
-	// Manually throw errors for Error Boundaries (per React Query Suspense docs)
-	// useSuspenseQuery only throws errors if there's no data, but we want to throw always
-	if (error && !isFetching) {
-		throw error;
-	}
+	const { data, refetch } = blog.tags.list.useSuspense([]);
 
 	return {
 		tags: data ?? [],
@@ -391,135 +220,34 @@ export function useSuspenseTags(): {
 	};
 }
 
+/**
+ * Form lifecycle hook for creating/editing posts, built on the core
+ * resource `useForm`: submits the right mutation, awaits invalidation,
+ * notifies, redirects, and maps server validation issues to `fieldErrors`.
+ */
+export function usePostForm<TValues>(
+	config: ResourceFormConfig<
+		TValues,
+		SerializedPost | null,
+		SerializedPost | null
+	>,
+): ResourceFormResult<TValues, SerializedPost | null, SerializedPost | null> {
+	return blog.posts.useForm<TValues, SerializedPost | null>(config);
+}
+
 /** Create a new post */
 export function useCreatePost() {
-	const { refresh, apiBaseURL, apiBasePath } =
-		usePluginOverrides<BlogPluginOverrides>("blog");
-	const client = createApiClient<BlogApiRouter>({
-		baseURL: apiBaseURL,
-		basePath: apiBasePath,
-	});
-	const queryClient = useQueryClient();
-	const queries = createBlogQueryKeys(client);
-
-	return useMutation<SerializedPost | null, Error, PostCreateInput>({
-		mutationKey: [...queries.posts._def, "create"],
-		mutationFn: async (postData: PostCreateInput) => {
-			const response = await client("@post/posts", {
-				method: "POST",
-				body: postData,
-			});
-			return response.data as SerializedPost | null;
-		},
-		onSuccess: async (created) => {
-			// Update detail cache if available
-			if (created?.slug) {
-				queryClient.setQueryData(
-					queries.posts.detail(created.slug).queryKey,
-					created,
-				);
-			}
-			// Invalidate lists scoped to posts and drafts - wait for completion
-			await queryClient.invalidateQueries({
-				queryKey: queries.posts.list._def,
-			});
-			await queryClient.invalidateQueries({
-				queryKey: queries.drafts.list._def,
-			});
-			// Refresh server-side cache (Next.js router cache)
-			if (refresh) {
-				await refresh();
-			}
-		},
-	});
+	return blog.posts.create.use();
 }
 
 /** Update an existing post by id */
 export function useUpdatePost() {
-	const { refresh, apiBaseURL, apiBasePath } =
-		usePluginOverrides<BlogPluginOverrides>("blog");
-
-	const client = createApiClient<BlogApiRouter>({
-		baseURL: apiBaseURL,
-		basePath: apiBasePath,
-	});
-
-	const queryClient = useQueryClient();
-	const queries = createBlogQueryKeys(client);
-
-	return useMutation<
-		SerializedPost | null,
-		Error,
-		{ id: string; data: PostUpdateInput }
-	>({
-		mutationKey: [...queries.posts._def, "update"],
-		mutationFn: async ({ id, data }: { id: string; data: PostUpdateInput }) => {
-			const response = await client(`@put/posts/:id`, {
-				method: "PUT",
-				params: { id },
-				body: data,
-			});
-			return response.data as SerializedPost | null;
-		},
-		onSuccess: async (updated) => {
-			// Update detail cache if available
-			if (updated?.slug) {
-				queryClient.setQueryData(
-					queries.posts.detail(updated.slug).queryKey,
-					updated,
-				);
-			}
-			// Invalidate lists scoped to posts and drafts - wait for completion
-			await queryClient.invalidateQueries({
-				queryKey: queries.posts.list._def,
-			});
-			await queryClient.invalidateQueries({
-				queryKey: queries.drafts.list._def,
-			});
-			// Refresh server-side cache (Next.js router cache)
-			if (refresh) {
-				await refresh();
-			}
-		},
-	});
+	return blog.posts.update.use();
 }
 
 /** Delete a post by id */
 export function useDeletePost() {
-	const { refresh, apiBaseURL, apiBasePath } =
-		usePluginOverrides<BlogPluginOverrides>("blog");
-
-	const client = createApiClient<BlogApiRouter>({
-		baseURL: apiBaseURL,
-		basePath: apiBasePath,
-	});
-
-	const queryClient = useQueryClient();
-	const queries = createBlogQueryKeys(client);
-
-	return useMutation<{ success: boolean }, Error, { id: string }>({
-		mutationKey: [...queries.posts._def, "delete"],
-		mutationFn: async ({ id }: { id: string }) => {
-			const response = await client(`@delete/posts/:id`, {
-				method: "DELETE",
-				params: { id },
-			});
-			return response.data as { success: boolean };
-		},
-		onSuccess: async () => {
-			// Invalidate all post lists and detail caches - wait for completion
-			await queryClient.invalidateQueries({
-				queryKey: queries.posts._def,
-			});
-			await queryClient.invalidateQueries({
-				queryKey: queries.drafts.list._def,
-			});
-			// Refresh server-side cache (Next.js router cache)
-			if (refresh) {
-				await refresh();
-			}
-		},
-	});
+	return blog.posts.delete.use();
 }
 
 /**
@@ -610,28 +338,13 @@ export function useNextPreviousPosts(
 	createdAt: string | Date,
 	options: UseNextPreviousPostsOptions = {},
 ): UseNextPreviousPostsResult {
-	const { apiBaseURL, apiBasePath, headers } =
-		usePluginOverrides<BlogPluginOverrides>("blog");
-	const client = createApiClient<BlogApiRouter>({
-		baseURL: apiBaseURL,
-		basePath: apiBasePath,
-	});
-	const queries = createBlogQueryKeys(client, headers);
-
 	const dateValue =
 		typeof createdAt === "string" ? new Date(createdAt) : createdAt;
-	const baseQuery = queries.posts.nextPrevious(dateValue);
-
-	const { data, isLoading, error, refetch } = useQuery<
-		{ previous: SerializedPost | null; next: SerializedPost | null },
-		Error,
-		{ previous: SerializedPost | null; next: SerializedPost | null },
-		typeof baseQuery.queryKey
-	>({
-		...baseQuery,
-		...SHARED_QUERY_CONFIG,
-		enabled: (options.enabled ?? true) && !!client,
-	});
+
+	const { data, isLoading, error, refetch } = blog.posts.nextPrevious.use(
+		[dateValue],
+		{ enabled: options.enabled ?? true },
+	);
 
 	return {
 		previousPost: data?.previous ?? null,
@@ -675,29 +388,10 @@ export interface UseRecentPostsResult {
 export function useRecentPosts(
 	options: UseRecentPostsOptions = {},
 ): UseRecentPostsResult {
-	const { apiBaseURL, apiBasePath, headers } =
-		usePluginOverrides<BlogPluginOverrides>("blog");
-	const client = createApiClient<BlogApiRouter>({
-		baseURL: apiBaseURL,
-		basePath: apiBasePath,
-	});
-	const queries = createBlogQueryKeys(client, headers);
-
-	const baseQuery = queries.posts.recent({
-		limit: options.limit ?? 5,
-		excludeSlug: options.excludeSlug,
-	});
-
-	const { data, isLoading, error, refetch } = useQuery<
-		SerializedPost[],
-		Error,
-		SerializedPost[],
-		typeof baseQuery.queryKey
-	>({
-		...baseQuery,
-		...SHARED_QUERY_CONFIG,
-		enabled: (options.enabled ?? true) && !!client,
-	});
+	const { data, isLoading, error, refetch } = blog.posts.recent.use(
+		[{ limit: options.limit ?? 5, excludeSlug: options.excludeSlug }],
+		{ enabled: options.enabled ?? true },
+	);
 
 	return {
 		recentPosts: data ?? [],

package/src/plugins/blog/client/hooks/blog-resource.ts

@@ -0,0 +1,13 @@
+"use client";
+
+import { createResource } from "@btst/stack/plugins/client/hooks";
+import { blogResources } from "../../query-keys";
+
+/**
+ * Factory-generated blog resource hooks. Internal — the public hook surface
+ * (`usePosts`, `useSuspensePost`, ...) in `blog-hooks.tsx` wraps these.
+ */
+export const blog = createResource({
+	plugin: "blog",
+	resources: blogResources,
+});

package/src/plugins/blog/client/hooks/use-debounce.ts

@@ -1,19 +1,8 @@
 import { throttle } from "../../utils";
 import { useEffect, useMemo, useRef, useState } from "react";
 
-export function useDebounce<T>(value: T, delay?: number): T {
-	const [debouncedValue, setDebouncedValue] = useState<T>(value);
-
-	useEffect(() => {
-		const timer = setTimeout(() => setDebouncedValue(value), delay || 500);
-
-		return () => {
-			clearTimeout(timer);
-		};
-	}, [value, delay]);
-
-	return debouncedValue;
-}
+// Re-export the shared core hook — never copy it into a plugin.
+export { useDebounce } from "@btst/stack/plugins/client/hooks";
 
 export function useThrottle<T>(value: T, wait?: number): T {
 	const [throttledValue, setThrottledValue] = useState<T>(value);

package/src/plugins/blog/client/localization/blog-forms.ts

@@ -26,6 +26,7 @@ export const BLOG_FORMS = {
 	BLOG_FORMS_TOAST_CREATE_SUCCESS: "Post created successfully",
 	BLOG_FORMS_TOAST_UPDATE_SUCCESS: "Post updated successfully",
 	BLOG_FORMS_TOAST_DELETE_SUCCESS: "Post deleted successfully",
+	BLOG_FORMS_TOAST_DELETE_FAILURE: "Failed to delete post",
 	BLOG_FORMS_LOADING_POST: "Loading post...",
 
 	// Delete post

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

@@ -31,34 +31,16 @@ export interface RouteContext {
 /**
  * Overridable components and functions for the Blog plugin
  *
- * External consumers can provide their own implementations of these
- * to customize the behavior for their framework (Next.js, React Router, etc.)
+ * External consumers can provide their own implementations to customize
+ * plugin-specific components and behavior.
  */
 export interface BlogPluginOverrides {
-	/**
-	 * Link component for navigation
-	 */
-	Link?: ComponentType<React.ComponentProps<"a"> & Record<string, any>>;
 	/**
 	 * Post card component for displaying a post
 	 */
 	PostCard?: ComponentType<{
 		post: SerializedPost;
 	}>;
-	/**
-	 * Navigation function for programmatic navigation
-	 */
-	navigate: (path: string) => void | Promise<void>;
-	/**
-	 * Refresh function to invalidate server-side cache (e.g., Next.js router.refresh())
-	 */
-	refresh?: () => void | Promise<void>;
-	/**
-	 * Image component for displaying images
-	 */
-	Image?: ComponentType<
-		React.ImgHTMLAttributes<HTMLImageElement> & Record<string, any>
-	>;
 	/**
 	 * Function used to upload a new image file and return its URL.
 	 * This is separate from `imagePicker`, which selects an existing asset URL.
@@ -112,14 +94,6 @@ export interface BlogPluginOverrides {
 	 * Localization object for the blog plugin
 	 */
 	localization?: BlogLocalization;
-	/**
-	 * API base URL
-	 */
-	apiBaseURL: string;
-	/**
-	 * API base path
-	 */
-	apiBasePath: string;
 	/**
 	 * Whether to show the attribution
 	 */
@@ -152,46 +126,6 @@ export interface BlogPluginOverrides {
 		context: RouteContext,
 	) => void | Promise<void>;
 
-	/**
-	 * Called before the posts list page is rendered
-	 * Return false to prevent rendering (e.g., for authorization)
-	 * @param context - Route context
-	 */
-	onBeforePostsPageRendered?: (context: RouteContext) => boolean;
-
-	/**
-	 * Called before a single post page is rendered
-	 * Return false to prevent rendering (e.g., for authorization)
-	 * @param slug - The post slug
-	 * @param context - Route context
-	 */
-	onBeforePostPageRendered?: (slug: string, context: RouteContext) => boolean;
-
-	/**
-	 * Called before the new post page is rendered
-	 * Return false to prevent rendering (e.g., for authorization)
-	 * @param context - Route context
-	 */
-	onBeforeNewPostPageRendered?: (context: RouteContext) => boolean;
-
-	/**
-	 * Called before the edit post page is rendered
-	 * Return false to prevent rendering (e.g., for authorization)
-	 * @param slug - The post slug being edited
-	 * @param context - Route context
-	 */
-	onBeforeEditPostPageRendered?: (
-		slug: string,
-		context: RouteContext,
-	) => boolean;
-
-	/**
-	 * Called before the drafts page is rendered
-	 * Return false to prevent rendering (e.g., for authorization)
-	 * @param context - Route context
-	 */
-	onBeforeDraftsPageRendered?: (context: RouteContext) => boolean;
-
 	// ============ Slot Overrides ============
 
 	/**
@@ -206,10 +140,6 @@ export interface BlogPluginOverrides {
 	 *     <CommentThread
 	 *       resourceId={post.slug}
 	 *       resourceType="blog-post"
-	 *       apiBaseURL={apiBaseURL}
-	 *       apiBasePath="/api/data"
-	 *       currentUserId={session?.userId}
-	 *       loginHref="/login"
 	 *     />
 	 *   ),
 	 * }