@btst/stack 1.1.9 → 1.1.11

package/dist/plugins/blog/client/index.d.ts

@@ -11,21 +11,32 @@ import 'zod';
  * Context passed to route hooks
  */
 interface RouteContext$1 {
+    /** 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;
 }
 /**
  * Context passed to loader hooks
  */
 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;
 }
 /**
@@ -33,19 +44,32 @@ interface LoaderContext {
  * Note: queryClient is passed at runtime to both loader and meta (for SSR isolation)
  */
 interface BlogClientConfig {
+    /** 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 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 for customizing behavior */
     hooks?: BlogClientHooks;
+    /** Optional headers for SSR (e.g., forwarding cookies) */
     headers?: Headers;
 }
 /**
@@ -53,16 +77,51 @@ interface BlogClientConfig {
  * All hooks are optional and allow consumers to customize behavior
  */
 interface BlogClientHooks {
+    /**
+     * 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;
 }
 /**
@@ -313,9 +372,13 @@ type BlogLocalization = typeof BLOG_LOCALIZATION;
  * Context passed to lifecycle hooks
  */
 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;
 }
 /**
@@ -325,7 +388,13 @@ interface RouteContext {
  * to customize the behavior for their framework (Next.js, React Router, etc.)
  */
 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/dist/plugins/blog/query-keys.d.cts

@@ -32,17 +32,79 @@ interface BlogApiContext<TBody = any, TParams = any, TQuery = any> {
  * All hooks are optional and allow consumers to customize behavior
  */
 interface BlogBackendHooks {
+    /**
+     * Called before listing posts. Return false to deny access.
+     * @param filter - Query parameters for filtering posts
+     * @param context - Request context with headers, etc.
+     */
     onBeforeListPosts?: (filter: z.infer<typeof PostListQuerySchema>, context: BlogApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before creating a post. Return false to deny access.
+     * @param data - Post data being created
+     * @param context - Request context with headers, etc.
+     */
     onBeforeCreatePost?: (data: z.infer<typeof createPostSchema>, context: BlogApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before updating a post. Return false to deny access.
+     * @param postId - ID of the post being updated
+     * @param data - Updated post data
+     * @param context - Request context with headers, etc.
+     */
     onBeforeUpdatePost?: (postId: string, data: z.infer<typeof updatePostSchema>, context: BlogApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before deleting a post. Return false to deny access.
+     * @param postId - ID of the post being deleted
+     * @param context - Request context with headers, etc.
+     */
     onBeforeDeletePost?: (postId: string, context: BlogApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called after posts are read successfully
+     * @param posts - Array of posts that were read
+     * @param filter - Query parameters used for filtering
+     * @param context - Request context
+     */
     onPostsRead?: (posts: Post[], filter: z.infer<typeof PostListQuerySchema>, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called after a post is created successfully
+     * @param post - The created post
+     * @param context - Request context
+     */
     onPostCreated?: (post: Post, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called after a post is updated successfully
+     * @param post - The updated post
+     * @param context - Request context
+     */
     onPostUpdated?: (post: Post, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called after a post is deleted successfully
+     * @param postId - ID of the deleted post
+     * @param context - Request context
+     */
     onPostDeleted?: (postId: string, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called when listing posts fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
     onListPostsError?: (error: Error, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called when creating a post fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
     onCreatePostError?: (error: Error, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called when updating a post fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
     onUpdatePostError?: (error: Error, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called when deleting a post fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
     onDeletePostError?: (error: Error, context: BlogApiContext) => Promise<void> | void;
 }
 /**

package/dist/plugins/blog/query-keys.d.mts

@@ -32,17 +32,79 @@ interface BlogApiContext<TBody = any, TParams = any, TQuery = any> {
  * All hooks are optional and allow consumers to customize behavior
  */
 interface BlogBackendHooks {
+    /**
+     * Called before listing posts. Return false to deny access.
+     * @param filter - Query parameters for filtering posts
+     * @param context - Request context with headers, etc.
+     */
     onBeforeListPosts?: (filter: z.infer<typeof PostListQuerySchema>, context: BlogApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before creating a post. Return false to deny access.
+     * @param data - Post data being created
+     * @param context - Request context with headers, etc.
+     */
     onBeforeCreatePost?: (data: z.infer<typeof createPostSchema>, context: BlogApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before updating a post. Return false to deny access.
+     * @param postId - ID of the post being updated
+     * @param data - Updated post data
+     * @param context - Request context with headers, etc.
+     */
     onBeforeUpdatePost?: (postId: string, data: z.infer<typeof updatePostSchema>, context: BlogApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before deleting a post. Return false to deny access.
+     * @param postId - ID of the post being deleted
+     * @param context - Request context with headers, etc.
+     */
     onBeforeDeletePost?: (postId: string, context: BlogApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called after posts are read successfully
+     * @param posts - Array of posts that were read
+     * @param filter - Query parameters used for filtering
+     * @param context - Request context
+     */
     onPostsRead?: (posts: Post[], filter: z.infer<typeof PostListQuerySchema>, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called after a post is created successfully
+     * @param post - The created post
+     * @param context - Request context
+     */
     onPostCreated?: (post: Post, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called after a post is updated successfully
+     * @param post - The updated post
+     * @param context - Request context
+     */
     onPostUpdated?: (post: Post, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called after a post is deleted successfully
+     * @param postId - ID of the deleted post
+     * @param context - Request context
+     */
     onPostDeleted?: (postId: string, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called when listing posts fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
     onListPostsError?: (error: Error, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called when creating a post fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
     onCreatePostError?: (error: Error, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called when updating a post fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
     onUpdatePostError?: (error: Error, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called when deleting a post fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
     onDeletePostError?: (error: Error, context: BlogApiContext) => Promise<void> | void;
 }
 /**

package/dist/plugins/blog/query-keys.d.ts

@@ -32,17 +32,79 @@ interface BlogApiContext<TBody = any, TParams = any, TQuery = any> {
  * All hooks are optional and allow consumers to customize behavior
  */
 interface BlogBackendHooks {
+    /**
+     * Called before listing posts. Return false to deny access.
+     * @param filter - Query parameters for filtering posts
+     * @param context - Request context with headers, etc.
+     */
     onBeforeListPosts?: (filter: z.infer<typeof PostListQuerySchema>, context: BlogApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before creating a post. Return false to deny access.
+     * @param data - Post data being created
+     * @param context - Request context with headers, etc.
+     */
     onBeforeCreatePost?: (data: z.infer<typeof createPostSchema>, context: BlogApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before updating a post. Return false to deny access.
+     * @param postId - ID of the post being updated
+     * @param data - Updated post data
+     * @param context - Request context with headers, etc.
+     */
     onBeforeUpdatePost?: (postId: string, data: z.infer<typeof updatePostSchema>, context: BlogApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before deleting a post. Return false to deny access.
+     * @param postId - ID of the post being deleted
+     * @param context - Request context with headers, etc.
+     */
     onBeforeDeletePost?: (postId: string, context: BlogApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called after posts are read successfully
+     * @param posts - Array of posts that were read
+     * @param filter - Query parameters used for filtering
+     * @param context - Request context
+     */
     onPostsRead?: (posts: Post[], filter: z.infer<typeof PostListQuerySchema>, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called after a post is created successfully
+     * @param post - The created post
+     * @param context - Request context
+     */
     onPostCreated?: (post: Post, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called after a post is updated successfully
+     * @param post - The updated post
+     * @param context - Request context
+     */
     onPostUpdated?: (post: Post, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called after a post is deleted successfully
+     * @param postId - ID of the deleted post
+     * @param context - Request context
+     */
     onPostDeleted?: (postId: string, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called when listing posts fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
     onListPostsError?: (error: Error, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called when creating a post fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
     onCreatePostError?: (error: Error, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called when updating a post fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
     onUpdatePostError?: (error: Error, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called when deleting a post fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
     onDeletePostError?: (error: Error, context: BlogApiContext) => Promise<void> | void;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btst/stack",
-  "version": "1.1.9",
+  "version": "1.1.11",
   "description": "A composable, plugin-based library for building full-stack applications.",
   "repository": {
     "type": "git",

package/src/client/components/compose.tsx

@@ -55,6 +55,19 @@ export function RouteRenderer({
 	);
 }
 
+/**
+ * Renders a route with Suspense and ErrorBoundary wrappers.
+ * Handles loading states, error boundaries, and not-found scenarios for a single route.
+ *
+ * @param path - The current route path
+ * @param PageComponent - The page component to render
+ * @param ErrorComponent - Optional error fallback component
+ * @param LoadingComponent - Component to show during suspense
+ * @param onNotFound - Optional callback when route is not found
+ * @param NotFoundComponent - Optional component to show for 404s
+ * @param props - Additional props to pass to the page component
+ * @param onError - Error handler callback for the error boundary
+ */
 export function ComposedRoute({
 	path,
 	PageComponent,

package/src/client/components/error-boundary.tsx

@@ -7,6 +7,15 @@ import {
 
 export type { FallbackProps } from "react-error-boundary";
 
+/**
+ * Error boundary wrapper component for catching and handling React errors.
+ * Wraps react-error-boundary with a simplified API.
+ *
+ * @param children - Child components to wrap with error boundary
+ * @param FallbackComponent - Component to render when an error occurs
+ * @param resetKeys - Array of values that will reset the error boundary when changed
+ * @param onError - Callback invoked when an error is caught
+ */
 export function ErrorBoundary({
 	children,
 	FallbackComponent,

package/src/context/provider.tsx

@@ -75,8 +75,16 @@ export function BetterStackProvider<
 }
 
 /**
- * Hook to access the entire context
+ * Hook to access the entire BetterStack context
  * Useful if you need access to multiple plugins or the full context
+ *
+ * @returns The full context value including overrides and basePath
+ * @throws Error if used outside of BetterStackProvider
+ *
+ * @example
+ * ```tsx
+ * const { overrides, basePath } = useBetterStack<MyPluginOverrides>();
+ * ```
  */
 export function useBetterStack<
 	TPluginOverrides extends Record<string, any> = Record<string, any>,
@@ -145,6 +153,18 @@ export function usePluginOverrides<
 	return overrides as OverridesResult<TOverrides, TDefaults>;
 }
 
+/**
+ * Hook to access the base path where the client router is mounted
+ *
+ * @returns The base path string (e.g., "/pages")
+ * @throws Error if used outside of BetterStackProvider
+ *
+ * @example
+ * ```tsx
+ * const basePath = useBasePath();
+ * // basePath = "/pages"
+ * ```
+ */
 export function useBasePath() {
 	const context = useBetterStack();
 	if (!context) {

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

@@ -45,51 +45,110 @@ export interface BlogApiContext<TBody = any, TParams = any, TQuery = any> {
  * All hooks are optional and allow consumers to customize behavior
  */
 export interface BlogBackendHooks {
-	// Hooks - called before the operation
+	/**
+	 * Called before listing posts. Return false to deny access.
+	 * @param filter - Query parameters for filtering posts
+	 * @param context - Request context with headers, etc.
+	 */
 	onBeforeListPosts?: (
 		filter: z.infer<typeof PostListQuerySchema>,
 		context: BlogApiContext,
 	) => Promise<boolean> | boolean;
+	/**
+	 * Called before creating a post. Return false to deny access.
+	 * @param data - Post data being created
+	 * @param context - Request context with headers, etc.
+	 */
 	onBeforeCreatePost?: (
 		data: z.infer<typeof createPostSchema>,
 		context: BlogApiContext,
 	) => Promise<boolean> | boolean;
+	/**
+	 * Called before updating a post. Return false to deny access.
+	 * @param postId - ID of the post being updated
+	 * @param data - Updated post data
+	 * @param context - Request context with headers, etc.
+	 */
 	onBeforeUpdatePost?: (
 		postId: string,
 		data: z.infer<typeof updatePostSchema>,
 		context: BlogApiContext,
 	) => Promise<boolean> | boolean;
+	/**
+	 * Called before deleting a post. Return false to deny access.
+	 * @param postId - ID of the post being deleted
+	 * @param context - Request context with headers, etc.
+	 */
 	onBeforeDeletePost?: (
 		postId: string,
 		context: BlogApiContext,
 	) => Promise<boolean> | boolean;
 
-	// Lifecycle hooks - called after the operation
+	/**
+	 * Called after posts are read successfully
+	 * @param posts - Array of posts that were read
+	 * @param filter - Query parameters used for filtering
+	 * @param context - Request context
+	 */
 	onPostsRead?: (
 		posts: Post[],
 		filter: z.infer<typeof PostListQuerySchema>,
 		context: BlogApiContext,
 	) => Promise<void> | void;
+	/**
+	 * Called after a post is created successfully
+	 * @param post - The created post
+	 * @param context - Request context
+	 */
 	onPostCreated?: (post: Post, context: BlogApiContext) => Promise<void> | void;
+	/**
+	 * Called after a post is updated successfully
+	 * @param post - The updated post
+	 * @param context - Request context
+	 */
 	onPostUpdated?: (post: Post, context: BlogApiContext) => Promise<void> | void;
+	/**
+	 * Called after a post is deleted successfully
+	 * @param postId - ID of the deleted post
+	 * @param context - Request context
+	 */
 	onPostDeleted?: (
 		postId: string,
 		context: BlogApiContext,
 	) => Promise<void> | void;
 
-	// Error hooks - called when operations fail
+	/**
+	 * Called when listing posts fails
+	 * @param error - The error that occurred
+	 * @param context - Request context
+	 */
 	onListPostsError?: (
 		error: Error,
 		context: BlogApiContext,
 	) => Promise<void> | void;
+	/**
+	 * Called when creating a post fails
+	 * @param error - The error that occurred
+	 * @param context - Request context
+	 */
 	onCreatePostError?: (
 		error: Error,
 		context: BlogApiContext,
 	) => Promise<void> | void;
+	/**
+	 * Called when updating a post fails
+	 * @param error - The error that occurred
+	 * @param context - Request context
+	 */
 	onUpdatePostError?: (
 		error: Error,
 		context: BlogApiContext,
 	) => Promise<void> | void;
+	/**
+	 * Called when deleting a post fails
+	 * @param error - The error that occurred
+	 * @param context - Request context
+	 */
 	onDeletePostError?: (
 		error: Error,
 		context: BlogApiContext,

package/src/plugins/blog/client/components/shared/on-this-page.tsx

@@ -12,6 +12,7 @@ import {
 	SelectTrigger,
 	SelectValue,
 } from "@workspace/ui/components/select";
+import { TextAlignStart } from "lucide-react";
 
 interface Heading {
 	id: string;
@@ -62,8 +63,9 @@ export function OnThisPage({ markdown, className }: OnThisPageProps) {
 			aria-label="Table of contents"
 		>
 			<div className="overflow-y-auto px-2">
-				<div className="flex flex-col gap-2 p-4 pt-0 text-sm">
-					<p className="font-semibold text-muted-foreground sticky top-0 h-6 text-xs">
+				<div className="flex flex-col gap-1 p-4 pt-0 text-sm">
+					<p className="flex items-center gap-2 font-semibold text-muted-foreground sticky top-0 h-6 text-xs">
+						<TextAlignStart className="w-3 h-3" />{" "}
 						{localization.BLOG_POST_ON_THIS_PAGE}
 					</p>
 					{headings.map(({ id, text, level }) => {