@btst/stack 1.1.10 → 1.2.0

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

@@ -34,52 +34,99 @@ const SHARED_QUERY_CONFIG = {
 	gcTime: 1000 * 60 * 10, // 10 minutes
 } as const;
 
+/**
+ * Options for the usePosts hook
+ */
 export 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
+ */
 export 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
+ */
 export 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
+ */
 export 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
+ */
 export 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 */
 export type PostCreateInput = z.infer<typeof createPostSchema>;
+/** Input type for updating an existing post */
 export type PostUpdateInput = z.infer<typeof updatePostSchema>;
 
 /**
@@ -532,15 +579,27 @@ export function usePostSearch({
 	};
 }
 
+/**
+ * Options for the useNextPreviousPosts hook
+ */
 export interface UseNextPreviousPostsOptions {
+	/** Whether to enable the query (default: true) */
 	enabled?: boolean;
 }
 
+/**
+ * Result from the useNextPreviousPosts hook
+ */
 export 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;
 }
 
@@ -596,16 +655,29 @@ export function useNextPreviousPosts(
 	};
 }
 
+/**
+ * Options for the useRecentPosts hook
+ */
 export 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
+ */
 export 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;
 }
 

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

@@ -6,9 +6,13 @@ import type { BlogLocalization } from "./localization";
  * Context passed to lifecycle hooks
  */
 export interface RouteContext {
+	/** Current route path */
 	path: string;
+	/** Route parameters (e.g., { slug: "my-post" }) */
 	params?: Record<string, string>;
+	/** Whether rendering on server (true) or client (false) */
 	isSSR: boolean;
+	/** Additional context properties */
 	[key: string]: any;
 }
 
@@ -19,7 +23,13 @@ export interface RouteContext {
  * to customize the behavior for their framework (Next.js, React Router, etc.)
  */
 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;
 	}>;

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

@@ -17,9 +17,13 @@ import { PostPageComponent } from "./components/pages/post-page";
  * Context passed to route hooks
  */
 export interface RouteContext {
+	/** Current route path */
 	path: string;
+	/** Route parameters (e.g., { slug: "my-post" }) */
 	params?: Record<string, string>;
+	/** Whether rendering on server (true) or client (false) */
 	isSSR: boolean;
+	/** Additional context properties */
 	[key: string]: any;
 }
 
@@ -27,12 +31,19 @@ export interface RouteContext {
  * Context passed to loader hooks
  */
 export interface LoaderContext {
+	/** Current route path */
 	path: string;
+	/** Route parameters (e.g., { slug: "my-post" }) */
 	params?: Record<string, string>;
+	/** Whether rendering on server (true) or client (false) */
 	isSSR: boolean;
+	/** Base URL for API calls */
 	apiBaseURL: string;
+	/** Path where the API is mounted */
 	apiBasePath: string;
+	/** Optional headers for the request */
 	headers?: Headers;
+	/** Additional context properties */
 	[key: string]: any;
 }
 
@@ -41,26 +52,35 @@ export interface LoaderContext {
  * Note: queryClient is passed at runtime to both loader and meta (for SSR isolation)
  */
 export interface BlogClientConfig {
-	// Required configuration
+	/** Base URL for API calls (e.g., "http://localhost:3000") */
 	apiBaseURL: string;
+	/** Path where the API is mounted (e.g., "/api/data") */
 	apiBasePath: string;
+	/** Base URL of your site for SEO meta tags */
 	siteBaseURL: string;
+	/** Path where pages are mounted (e.g., "/pages") */
 	siteBasePath: string;
+	/** React Query client instance for caching */
 	queryClient: QueryClient;
 
-	// Optional SEO/meta configuration
+	/** Optional SEO configuration for meta tags */
 	seo?: {
+		/** Site name for Open Graph tags */
 		siteName?: string;
+		/** Default author name */
 		author?: string;
+		/** Twitter handle (e.g., "@yourhandle") */
 		twitterHandle?: string;
+		/** Locale for Open Graph (e.g., "en_US") */
 		locale?: string;
+		/** Default image URL for social sharing */
 		defaultImage?: string;
 	};
 
-	// Optional hooks
+	/** Optional hooks for customizing behavior */
 	hooks?: BlogClientHooks;
 
-	// Optional headers for SSR (e.g., forwarding cookies)
+	/** Optional headers for SSR (e.g., forwarding cookies) */
 	headers?: Headers;
 }
 
@@ -69,27 +89,61 @@ export interface BlogClientConfig {
  * All hooks are optional and allow consumers to customize behavior
  */
 export interface BlogClientHooks {
-	// Loader Hooks - called during data loading (SSR)
+	/**
+	 * Called before loading posts list. Return false to cancel loading.
+	 * @param filter - Filter parameters including published status
+	 * @param context - Loader context with path, params, etc.
+	 */
 	beforeLoadPosts?: (
 		filter: { published: boolean },
 		context: LoaderContext,
 	) => Promise<boolean> | boolean;
+	/**
+	 * Called after posts are loaded. Return false to cancel further processing.
+	 * @param posts - Array of loaded posts or null
+	 * @param filter - Filter parameters used
+	 * @param context - Loader context
+	 */
 	afterLoadPosts?: (
 		posts: Post[] | null,
 		filter: { published: boolean },
 		context: LoaderContext,
 	) => Promise<boolean> | boolean;
+	/**
+	 * Called before loading a single post. Return false to cancel loading.
+	 * @param slug - Post slug being loaded
+	 * @param context - Loader context
+	 */
 	beforeLoadPost?: (
 		slug: string,
 		context: LoaderContext,
 	) => Promise<boolean> | boolean;
+	/**
+	 * Called after a post is loaded. Return false to cancel further processing.
+	 * @param post - Loaded post or null if not found
+	 * @param slug - Post slug that was requested
+	 * @param context - Loader context
+	 */
 	afterLoadPost?: (
 		post: Post | null,
 		slug: string,
 		context: LoaderContext,
 	) => Promise<boolean> | boolean;
+	/**
+	 * Called before loading the new post page. Return false to cancel.
+	 * @param context - Loader context
+	 */
 	beforeLoadNewPost?: (context: LoaderContext) => Promise<boolean> | boolean;
+	/**
+	 * Called after the new post page is loaded. Return false to cancel.
+	 * @param context - Loader context
+	 */
 	afterLoadNewPost?: (context: LoaderContext) => Promise<boolean> | boolean;
+	/**
+	 * Called when a loading error occurs
+	 * @param error - The error that occurred
+	 * @param context - Loader context
+	 */
 	onLoadError?: (error: Error, context: LoaderContext) => Promise<void> | void;
 }