@btst/stack 2.5.5 → 2.6.0

package/dist/shared/stack.D3BsrpAz.d.ts

@@ -0,0 +1,228 @@
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { S as SerializedPost, c as createPostSchema, u as updatePostSchema, a as SerializedTag } from './stack.BWp0hcm9.js';
+import { z } from 'zod';
+
+/**
+ * Options for the usePosts hook
+ */
+interface UsePostsOptions {
+    /** Filter posts by tag name */
+    tag?: string;
+    /** Filter posts by tag slug */
+    tagSlug?: string;
+    /** Number of posts to fetch per page (default: 10) */
+    limit?: number;
+    /** Whether to enable the query (default: true) */
+    enabled?: boolean;
+    /** Search query to filter posts by title, content, or excerpt */
+    query?: string;
+    /** Filter by published status */
+    published?: boolean;
+    /** Filter by specific post slug */
+    slug?: string;
+}
+/**
+ * Result from the usePosts hook
+ */
+interface UsePostsResult {
+    /** Array of fetched posts */
+    posts: SerializedPost[];
+    /** Whether the initial load is in progress */
+    isLoading: boolean;
+    /** Error if the query failed */
+    error: Error | null;
+    /** Function to load the next page of posts */
+    loadMore: () => void;
+    /** Whether there are more posts to load */
+    hasMore: boolean;
+    /** Whether the next page is being loaded */
+    isLoadingMore: boolean;
+    /** Function to refetch the posts */
+    refetch: () => void;
+}
+/**
+ * Options for the usePostSearch hook
+ */
+interface UsePostSearchOptions {
+    /** Search query string to filter posts */
+    query: string;
+    /** Whether to enable the search query (default: true) */
+    enabled?: boolean;
+    /** Debounce delay in milliseconds (default: 300) */
+    debounceMs?: number;
+    /** Number of results to return (default: 10) */
+    limit?: number;
+    /** Filter by published status (default: true) */
+    published?: boolean;
+}
+/**
+ * Result from the usePostSearch hook
+ */
+interface UsePostSearchResult {
+    /** Array of posts matching the search query */
+    posts: SerializedPost[];
+    /** Alias for posts (React Query compatibility) */
+    data: SerializedPost[];
+    /** Whether the search is in progress */
+    isLoading: boolean;
+    /** Error if the search failed */
+    error: Error | null;
+    /** Function to refetch the search results */
+    refetch: () => void;
+    /** Whether a search is currently in progress (includes debounce time) */
+    isSearching: boolean;
+    /** The debounced search query being used */
+    searchQuery: string;
+}
+/**
+ * Result from the usePost hook
+ */
+interface UsePostResult {
+    /** The fetched post, or null if not found */
+    post: SerializedPost | null;
+    /** Whether the post is being loaded */
+    isLoading: boolean;
+    /** Error if the query failed */
+    error: Error | null;
+    /** Function to refetch the post */
+    refetch: () => void;
+}
+/** Input type for creating a new post */
+type PostCreateInput = z.infer<typeof createPostSchema>;
+/** Input type for updating an existing post */
+type PostUpdateInput = z.infer<typeof updatePostSchema>;
+/**
+ * Hook for fetching paginated posts with load more functionality
+ */
+declare function usePosts(options?: UsePostsOptions): UsePostsResult;
+/** Suspense variant of usePosts */
+declare function useSuspensePosts(options?: UsePostsOptions): {
+    posts: SerializedPost[];
+    loadMore: () => Promise<unknown>;
+    hasMore: boolean;
+    isLoadingMore: boolean;
+    refetch: () => Promise<unknown>;
+};
+/**
+ * Hook for fetching a single post by slug
+ */
+declare function usePost(slug?: string): UsePostResult;
+/** Suspense variant of usePost */
+declare function useSuspensePost(slug: string): {
+    post: SerializedPost | null;
+    refetch: () => Promise<unknown>;
+};
+/**
+ * Hook for fetching all unique tags across posts
+ */
+declare function useTags(): {
+    tags: SerializedTag[];
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => void;
+};
+/** Suspense variant of useTags */
+declare function useSuspenseTags(): {
+    tags: SerializedTag[];
+    refetch: () => Promise<unknown>;
+};
+/** Create a new post */
+declare function useCreatePost(): _tanstack_react_query.UseMutationResult<SerializedPost | null, Error, {
+    tags: ({
+        name: string;
+    } | {
+        id: string;
+        name: string;
+        slug: string;
+    })[];
+    published: boolean;
+    title: string;
+    content: string;
+    excerpt: string;
+    slug?: string | undefined;
+    publishedAt?: Date | undefined;
+    createdAt?: Date | undefined;
+    updatedAt?: Date | undefined;
+    image?: string | undefined;
+}, unknown>;
+/** Update an existing post by id */
+declare function useUpdatePost(): _tanstack_react_query.UseMutationResult<SerializedPost | null, Error, {
+    id: string;
+    data: PostUpdateInput;
+}, unknown>;
+/** Delete a post by id */
+declare function useDeletePost(): _tanstack_react_query.UseMutationResult<{
+    success: boolean;
+}, Error, {
+    id: string;
+}, unknown>;
+/**
+ * Hook for searching posts by a free-text query. Uses `usePosts` under the hood.
+ * Debounces the query and preserves last successful results to avoid flicker.
+ */
+declare function usePostSearch({ query, enabled, debounceMs, limit, published, }: UsePostSearchOptions): UsePostSearchResult;
+/**
+ * Options for the useNextPreviousPosts hook
+ */
+interface UseNextPreviousPostsOptions {
+    /** Whether to enable the query (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Result from the useNextPreviousPosts hook
+ */
+interface UseNextPreviousPostsResult {
+    /** The previous post (older), or null if none exists */
+    previousPost: SerializedPost | null;
+    /** The next post (newer), or null if none exists */
+    nextPost: SerializedPost | null;
+    /** Whether the query is loading */
+    isLoading: boolean;
+    /** Error if the query failed */
+    error: Error | null;
+    /** Function to refetch the posts */
+    refetch: () => void;
+}
+/**
+ * Hook for fetching previous and next posts relative to a given date
+ * Uses useInView to only fetch when the component is in view
+ */
+declare function useNextPreviousPosts(createdAt: string | Date, options?: UseNextPreviousPostsOptions): UseNextPreviousPostsResult & {
+    ref: (node: Element | null) => void;
+    inView: boolean;
+};
+/**
+ * Options for the useRecentPosts hook
+ */
+interface UseRecentPostsOptions {
+    /** Maximum number of recent posts to fetch (default: 5) */
+    limit?: number;
+    /** Slug of a post to exclude from results */
+    excludeSlug?: string;
+    /** Whether to enable the query (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Result from the useRecentPosts hook
+ */
+interface UseRecentPostsResult {
+    /** Array of recent posts */
+    recentPosts: SerializedPost[];
+    /** Whether the query is loading */
+    isLoading: boolean;
+    /** Error if the query failed */
+    error: Error | null;
+    /** Function to refetch the posts */
+    refetch: () => void;
+}
+/**
+ * Hook for fetching recent posts
+ * Uses useInView to only fetch when the component is in view
+ */
+declare function useRecentPosts(options?: UseRecentPostsOptions): UseRecentPostsResult & {
+    ref: (node: Element | null) => void;
+    inView: boolean;
+};
+
+export { useSuspensePosts as f, usePost as g, useSuspensePost as h, useTags as i, useSuspenseTags as j, useCreatePost as k, useUpdatePost as l, useDeletePost as m, usePostSearch as n, useNextPreviousPosts as q, useRecentPosts as t, usePosts as u };
+export type { PostCreateInput as P, UsePostsOptions as U, UsePostsResult as a, UsePostSearchOptions as b, UsePostSearchResult as c, UsePostResult as d, PostUpdateInput as e, UseNextPreviousPostsOptions as o, UseNextPreviousPostsResult as p, UseRecentPostsOptions as r, UseRecentPostsResult as s };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btst/stack",
-  "version": "2.5.5",
+  "version": "2.6.0",
   "description": "A composable, plugin-based library for building full-stack applications.",
   "repository": {
     "type": "git",
@@ -25,7 +25,10 @@
     "build:analyze": "ANALYZE=1 unbuild --clean && node ./scripts/postbuild.cjs",
     "stub": "unbuild --stub",
     "test": "vitest",
-    "typecheck": "tsc --project tsconfig.json"
+    "typecheck": "tsc --project tsconfig.json",
+    "build-registry": "tsx scripts/build-registry.ts",
+    "test-registry": "bash scripts/test-registry.sh",
+    "host-registry": "npx http-server registry -p 8766 -c-1"
   },
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -123,6 +126,16 @@
         "default": "./dist/plugins/blog/client/index.cjs"
       }
     },
+    "./plugins/blog/client/hooks": {
+      "import": {
+        "types": "./dist/plugins/blog/client/hooks/index.d.ts",
+        "default": "./dist/plugins/blog/client/hooks/index.mjs"
+      },
+      "require": {
+        "types": "./dist/plugins/blog/client/hooks/index.d.cts",
+        "default": "./dist/plugins/blog/client/hooks/index.cjs"
+      }
+    },
     "./plugins/ai-chat/api": {
       "import": {
         "types": "./dist/plugins/ai-chat/api/index.d.ts",
@@ -390,6 +403,9 @@
       "plugins/blog/client": [
         "./dist/plugins/blog/client/index.d.ts"
       ],
+      "plugins/blog/client/hooks": [
+        "./dist/plugins/blog/client/hooks/index.d.ts"
+      ],
       "plugins/ai-chat/api": [
         "./dist/plugins/ai-chat/api/index.d.ts"
       ],
@@ -505,6 +521,7 @@
     "zod": ">=4.2.0"
   },
   "devDependencies": {
+    "tsx": "catalog:",
     "@ai-sdk/react": "^2.0.94",
     "@btst/adapter-memory": "2.0.3",
     "@btst/yar": "1.2.0",

package/src/__tests__/page-component-overrides.test.tsx

@@ -0,0 +1,147 @@
+import { describe, it, expect } from "vitest";
+import { defineClientPlugin } from "../plugins/client";
+import type { ComponentType } from "react";
+import { createRoute } from "@btst/yar";
+
+/**
+ * Default page components used by the mock plugin factory.
+ * These stand in for the real plugin page components (e.g. HomePageComponent).
+ */
+const DefaultListComponent: ComponentType = () => <div>Default List</div>;
+const DefaultDetailComponent: ComponentType<{ id: string }> = ({ id }) => (
+	<div>Default Detail {id}</div>
+);
+
+/**
+ * Lightweight mock plugin factory that mirrors the real plugin pattern:
+ * - Accepts a config with an optional `pageComponents` field
+ * - Falls back to built-in components when no override is provided
+ * - For param routes, extracts the override before the handler closure
+ */
+function createTestPlugin(config: {
+	pageComponents?: {
+		list?: ComponentType;
+		detail?: ComponentType<{ id: string }>;
+	};
+}) {
+	return defineClientPlugin({
+		name: "test",
+		routes: () => ({
+			list: createRoute("/items", () => {
+				const CustomList = config.pageComponents?.list;
+				return {
+					PageComponent: CustomList ?? DefaultListComponent,
+				};
+			}),
+			detail: createRoute("/items/:id", ({ params }) => {
+				const CustomDetail = config.pageComponents?.detail;
+				return {
+					PageComponent: CustomDetail
+						? () => <CustomDetail id={params.id} />
+						: () => <DefaultDetailComponent id={params.id} />,
+				};
+			}),
+		}),
+	});
+}
+
+describe("pageComponents overrides", () => {
+	describe("default components used when no override provided", () => {
+		it("uses the default component for a no-param route", () => {
+			const plugin = createTestPlugin({});
+			const routes = plugin.routes();
+			const routeData = routes.list();
+
+			expect(routeData.PageComponent).toBe(DefaultListComponent);
+		});
+
+		it("uses the default component wrapper for a param route", () => {
+			const plugin = createTestPlugin({});
+			const routes = plugin.routes();
+			const routeData = routes.detail({ params: { id: "42" } });
+
+			// Should be an inline wrapper, not the custom component
+			expect(routeData.PageComponent).toBeDefined();
+			expect(typeof routeData.PageComponent).toBe("function");
+			// Verify it is NOT the custom component (no override was given)
+			const CustomDetail: ComponentType<{ id: string }> = () => (
+				<div>Custom</div>
+			);
+			expect(routeData.PageComponent).not.toBe(CustomDetail);
+		});
+	});
+
+	describe("custom component replaces default (no-param route)", () => {
+		it("uses the provided override instead of the default", () => {
+			const CustomList: ComponentType = () => <div>Custom List</div>;
+
+			const plugin = createTestPlugin({
+				pageComponents: { list: CustomList },
+			});
+			const routes = plugin.routes();
+			const routeData = routes.list();
+
+			expect(routeData.PageComponent).toBe(CustomList);
+			expect(routeData.PageComponent).not.toBe(DefaultListComponent);
+		});
+
+		it("leaves other routes using their defaults when only one is overridden", () => {
+			const CustomList: ComponentType = () => <div>Custom List</div>;
+
+			const plugin = createTestPlugin({
+				pageComponents: { list: CustomList },
+			});
+			const routes = plugin.routes();
+
+			// list uses custom
+			expect(routes.list().PageComponent).toBe(CustomList);
+
+			// detail still uses a wrapper (no override)
+			const detailData = routes.detail({ params: { id: "1" } });
+			expect(detailData.PageComponent).not.toBe(CustomList);
+		});
+	});
+
+	describe("custom component replaces default (param route)", () => {
+		it("uses the override wrapper for a param route", () => {
+			const CustomDetail: ComponentType<{ id: string }> = ({ id }) => (
+				<div>Custom Detail {id}</div>
+			);
+
+			const plugin = createTestPlugin({
+				pageComponents: { detail: CustomDetail },
+			});
+			const routes = plugin.routes();
+			const routeData = routes.detail({ params: { id: "42" } });
+
+			// Should be an inline wrapper (not the raw CustomDetail directly)
+			expect(routeData.PageComponent).toBeDefined();
+			expect(typeof routeData.PageComponent).toBe("function");
+			// Should NOT be the default
+			expect(routeData.PageComponent).not.toBe(DefaultDetailComponent);
+		});
+
+		it("produces a different PageComponent than when no override is given", () => {
+			const CustomDetail: ComponentType<{ id: string }> = ({ id }) => (
+				<div>Custom Detail {id}</div>
+			);
+
+			const defaultPlugin = createTestPlugin({});
+			const overridePlugin = createTestPlugin({
+				pageComponents: { detail: CustomDetail },
+			});
+
+			const defaultRouteData = defaultPlugin
+				.routes()
+				.detail({ params: { id: "1" } });
+			const overrideRouteData = overridePlugin
+				.routes()
+				.detail({ params: { id: "1" } });
+
+			// The wrapped component should be a different function reference
+			expect(overrideRouteData.PageComponent).not.toBe(
+				defaultRouteData.PageComponent,
+			);
+		});
+	});
+});

package/src/plugins/ai-chat/client/components/shared/default-error.tsx

@@ -21,7 +21,7 @@ export function DefaultError({ error }: FallbackProps) {
 		process.env.NODE_ENV === "production"
 			? (localization?.CHAT_GENERIC_ERROR_MESSAGE ??
 				AI_CHAT_LOCALIZATION.CHAT_GENERIC_ERROR_MESSAGE)
-			: (error?.message ??
+			: ((error instanceof Error ? error.message : undefined) ??
 				localization?.CHAT_GENERIC_ERROR_MESSAGE ??
 				AI_CHAT_LOCALIZATION.CHAT_GENERIC_ERROR_MESSAGE);
 	return <ErrorPlaceholder title={title} message={message} />;

package/src/plugins/ai-chat/client/plugin.tsx

@@ -4,6 +4,7 @@ import {
 	runClientHookWithShim,
 } from "@btst/stack/plugins/client";
 import { createRoute } from "@btst/yar";
+import type { ComponentType } from "react";
 import type { QueryClient } from "@tanstack/react-query";
 import type { AiChatApiRouter } from "../api";
 import { createAiChatQueryKeys } from "../query-keys";
@@ -85,6 +86,18 @@ export interface AiChatClientConfig {
 
 	/** Optional headers for SSR (e.g., forwarding cookies) */
 	headers?: Headers;
+
+	/**
+	 * Optional page component overrides.
+	 * Replace any plugin page with a custom React component.
+	 * The built-in component is used as the fallback when not provided.
+	 */
+	pageComponents?: {
+		/** Replaces the chat home page */
+		chat?: ComponentType;
+		/** Replaces the conversation page (authenticated mode only) */
+		chatConversation?: ComponentType<{ conversationId: string }>;
+	};
 }
 
 /**
@@ -381,17 +394,22 @@ export const aiChatClientPlugin = (config: AiChatClientConfig) => {
 
 			routes: () => ({
 				// Chat home - simple chat interface without history
-				chat: createRoute("/chat", () => ({
-					PageComponent: () => (
-						<ChatLayout
-							apiBaseURL={config.apiBaseURL}
-							apiBasePath={config.apiBasePath}
-							showSidebar={false}
-						/>
-					),
-					loader: createConversationsLoader(config),
-					meta: createChatHomeMeta(config),
-				})),
+				chat: createRoute("/chat", () => {
+					const CustomChat = config.pageComponents?.chat;
+					return {
+						PageComponent:
+							CustomChat ??
+							(() => (
+								<ChatLayout
+									apiBaseURL={config.apiBaseURL}
+									apiBasePath={config.apiBasePath}
+									showSidebar={false}
+								/>
+							)),
+						loader: createConversationsLoader(config),
+						meta: createChatHomeMeta(config),
+					};
+				}),
 			}),
 
 			sitemap: async () => [],
@@ -404,29 +422,39 @@ export const aiChatClientPlugin = (config: AiChatClientConfig) => {
 
 		routes: () => ({
 			// Chat home - new conversation or list
-			chat: createRoute("/chat", () => ({
-				PageComponent: () => (
-					<ChatLayout
-						apiBaseURL={config.apiBaseURL}
-						apiBasePath={config.apiBasePath}
-					/>
-				),
-				loader: createConversationsLoader(config),
-				meta: createChatHomeMeta(config),
-			})),
+			chat: createRoute("/chat", () => {
+				const CustomChat = config.pageComponents?.chat;
+				return {
+					PageComponent:
+						CustomChat ??
+						(() => (
+							<ChatLayout
+								apiBaseURL={config.apiBaseURL}
+								apiBasePath={config.apiBasePath}
+							/>
+						)),
+					loader: createConversationsLoader(config),
+					meta: createChatHomeMeta(config),
+				};
+			}),
 
 			// Existing conversation
-			chatConversation: createRoute("/chat/:id", ({ params }) => ({
-				PageComponent: () => (
-					<ChatLayout
-						apiBaseURL={config.apiBaseURL}
-						apiBasePath={config.apiBasePath}
-						conversationId={params.id}
-					/>
-				),
-				loader: createConversationLoader(params.id, config),
-				meta: createConversationMeta(params.id, config),
-			})),
+			chatConversation: createRoute("/chat/:id", ({ params }) => {
+				const CustomConversation = config.pageComponents?.chatConversation;
+				return {
+					PageComponent: CustomConversation
+						? () => <CustomConversation conversationId={params.id} />
+						: () => (
+								<ChatLayout
+									apiBaseURL={config.apiBaseURL}
+									apiBasePath={config.apiBasePath}
+									conversationId={params.id}
+								/>
+							),
+					loader: createConversationLoader(params.id, config),
+					meta: createConversationMeta(params.id, config),
+				};
+			}),
 		}),
 
 		// Chat pages typically shouldn't be in sitemap, but we provide the option

package/src/plugins/blog/client/components/shared/default-error.tsx

@@ -18,6 +18,7 @@ export function DefaultError({ error }: FallbackProps) {
 	const message =
 		process.env.NODE_ENV === "production"
 			? localization.BLOG_GENERIC_ERROR_MESSAGE
-			: (error?.message ?? localization.BLOG_GENERIC_ERROR_MESSAGE);
+			: ((error instanceof Error ? error.message : undefined) ??
+				localization.BLOG_GENERIC_ERROR_MESSAGE);
 	return <ErrorPlaceholder title={title} message={message} />;
 }

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

@@ -1 +1,2 @@
 export * from "./blog-hooks";
+export * from "./use-debounce";

package/src/plugins/blog/client/plugin.tsx

@@ -5,6 +5,7 @@ import {
 	runClientHookWithShim,
 } from "@btst/stack/plugins/client";
 import { createRoute } from "@btst/yar";
+import type { ComponentType } from "react";
 import type { QueryClient } from "@tanstack/react-query";
 import type { BlogApiRouter } from "../api";
 import { createBlogQueryKeys } from "../query-keys";
@@ -84,6 +85,26 @@ export interface BlogClientConfig {
 
 	/** Optional headers for SSR (e.g., forwarding cookies) */
 	headers?: Headers;
+
+	/**
+	 * Optional page component overrides.
+	 * Replace any plugin page with a custom React component.
+	 * The built-in component is used as the fallback when not provided.
+	 */
+	pageComponents?: {
+		/** Replaces the published posts list page */
+		posts?: ComponentType;
+		/** Replaces the drafts list page */
+		drafts?: ComponentType;
+		/** Replaces the new post page */
+		newPost?: ComponentType;
+		/** Replaces the single post page */
+		post?: ComponentType<{ slug: string }>;
+		/** Replaces the edit post page */
+		editPost?: ComponentType<{ slug: string }>;
+		/** Replaces the tag posts page */
+		tag?: ComponentType<{ tagSlug: string }>;
+	};
 }
 
 /**
@@ -700,43 +721,57 @@ export const blogClientPlugin = (config: BlogClientConfig) =>
 
 		routes: () => ({
 			posts: createRoute("/blog", () => {
+				const CustomPosts = config.pageComponents?.posts;
 				return {
-					PageComponent: () => <HomePageComponent published={true} />,
+					PageComponent:
+						CustomPosts ?? (() => <HomePageComponent published={true} />),
 					loader: createPostsLoader(true, config),
 					meta: createPostsListMeta(true, config),
 				};
 			}),
 			drafts: createRoute("/blog/drafts", () => {
+				const CustomDrafts = config.pageComponents?.drafts;
 				return {
-					PageComponent: () => <HomePageComponent published={false} />,
+					PageComponent:
+						CustomDrafts ?? (() => <HomePageComponent published={false} />),
 					loader: createPostsLoader(false, config),
 					meta: createPostsListMeta(false, config),
 				};
 			}),
 			newPost: createRoute("/blog/new", () => {
+				const CustomNewPost = config.pageComponents?.newPost;
 				return {
-					PageComponent: NewPostPageComponent,
+					PageComponent: CustomNewPost ?? NewPostPageComponent,
 					loader: createNewPostLoader(config),
 					meta: createNewPostMeta(config),
 				};
 			}),
 			editPost: createRoute("/blog/:slug/edit", ({ params: { slug } }) => {
+				const CustomEditPost = config.pageComponents?.editPost;
 				return {
-					PageComponent: () => <EditPostPageComponent slug={slug} />,
+					PageComponent: CustomEditPost
+						? () => <CustomEditPost slug={slug} />
+						: () => <EditPostPageComponent slug={slug} />,
 					loader: createPostLoader(slug, config, `/blog/${slug}/edit`),
 					meta: createEditPostMeta(slug, config),
 				};
 			}),
 			tag: createRoute("/blog/tag/:tagSlug", ({ params: { tagSlug } }) => {
+				const CustomTag = config.pageComponents?.tag;
 				return {
-					PageComponent: () => <TagPageComponent tagSlug={tagSlug} />,
+					PageComponent: CustomTag
+						? () => <CustomTag tagSlug={tagSlug} />
+						: () => <TagPageComponent tagSlug={tagSlug} />,
 					loader: createTagLoader(tagSlug, config),
 					meta: createTagMeta(tagSlug, config),
 				};
 			}),
 			post: createRoute("/blog/:slug", ({ params: { slug } }) => {
+				const CustomPost = config.pageComponents?.post;
 				return {
-					PageComponent: () => <PostPageComponent slug={slug} />,
+					PageComponent: CustomPost
+						? () => <CustomPost slug={slug} />
+						: () => <PostPageComponent slug={slug} />,
 					loader: createPostLoader(slug, config),
 					meta: createPostMeta(slug, config),
 				};