@btst/stack 1.7.0 → 1.8.0

package/src/plugins/route-docs/client/index.ts

@@ -0,0 +1,7 @@
+export {
+	routeDocsClientPlugin,
+	type RouteDocsClientConfig,
+	ROUTE_DOCS_QUERY_KEY,
+	generateSchema,
+	getStoredContext,
+} from "./plugin";

package/src/plugins/route-docs/client/plugin.tsx

@@ -0,0 +1,187 @@
+import { lazy } from "react";
+import { defineClientPlugin } from "@btst/stack/plugins/client";
+import { createRoute } from "@btst/yar";
+import type { QueryClient } from "@tanstack/react-query";
+import type { ClientStackContext } from "../../../types";
+import {
+	generateRouteDocsSchema,
+	fetchAllSitemapEntries,
+	type RouteDocsSchema,
+} from "../generator";
+import type { DocsPageProps } from "./components/pages/docs-page";
+
+// Lazy load page components for code splitting
+const DocsPageComponent = lazy(() =>
+	import("./components/pages/docs-page").then((m) => ({
+		default: m.DocsPageComponent as React.ComponentType<DocsPageProps>,
+	})),
+);
+
+const DocsPageSkeleton = lazy(() =>
+	import("./components/loading/docs-skeleton").then((m) => ({
+		default: m.DocsPageSkeleton,
+	})),
+);
+
+/**
+ * Query key for route docs schema
+ */
+export const ROUTE_DOCS_QUERY_KEY = ["route-docs", "schema"] as const;
+
+/**
+ * Module-level storage for the client stack context
+ * This allows the schema to be generated on both server and client
+ */
+let moduleStoredContext: ClientStackContext | null = null;
+
+/**
+ * Get the stored client stack context
+ * Used by the docs page component to generate schema on client-side navigation
+ */
+export function getStoredContext(): ClientStackContext | null {
+	return moduleStoredContext;
+}
+
+/**
+ * Generate the route docs schema from the stored context
+ * This can be called from both server and client
+ */
+export async function generateSchema(): Promise<RouteDocsSchema> {
+	if (!moduleStoredContext) {
+		return {
+			plugins: [],
+			generatedAt: new Date().toISOString(),
+			allSitemapEntries: [],
+		};
+	}
+
+	try {
+		const sitemapEntries = await fetchAllSitemapEntries(moduleStoredContext);
+		return generateRouteDocsSchema(moduleStoredContext, sitemapEntries);
+	} catch (error) {
+		console.warn("Failed to generate route docs schema:", error);
+		// Return schema without sitemap entries on error
+		return generateRouteDocsSchema(moduleStoredContext, []);
+	}
+}
+
+/**
+ * Configuration for Route Docs client plugin
+ */
+export interface RouteDocsClientConfig {
+	/** React Query client for SSR prefetching */
+	queryClient: QueryClient;
+	/** Title for the documentation page */
+	title?: string;
+	/** Description for the documentation page */
+	description?: string;
+	/** Site base path for constructing URLs (e.g., "/pages") */
+	siteBasePath: string;
+}
+
+/**
+ * Create meta generator for the docs page
+ */
+function createDocsMeta(config: RouteDocsClientConfig) {
+	return () => {
+		const title = config.title || "Route Documentation";
+		return [
+			{ title },
+			{ name: "title", content: title },
+			{ name: "robots", content: "noindex" },
+		];
+	};
+}
+
+/**
+ * Default error component - no required props, matches other plugins
+ */
+function DocsErrorComponent() {
+	return (
+		<div className="flex items-center justify-center min-h-screen bg-background">
+			<div className="text-center">
+				<h1 className="text-2xl font-semibold text-destructive mb-2">
+					Error Loading Documentation
+				</h1>
+				<p className="text-muted-foreground">
+					An error occurred while loading the documentation.
+				</p>
+			</div>
+		</div>
+	);
+}
+
+/**
+ * Create loader for SSR prefetching of route docs schema
+ * This properly awaits all sitemap data before storing in React Query
+ */
+function createRouteDocsLoader(config: RouteDocsClientConfig) {
+	return async () => {
+		// Only run on server for SSR prefetching
+		// Client-side navigation uses the queryFn in the component
+		if (typeof window === "undefined" && moduleStoredContext) {
+			const { queryClient } = config;
+
+			try {
+				// Await all sitemap entries from all plugins
+				const sitemapEntries =
+					await fetchAllSitemapEntries(moduleStoredContext);
+
+				// Generate the complete schema with sitemap data
+				const schema = generateRouteDocsSchema(
+					moduleStoredContext,
+					sitemapEntries,
+				);
+
+				// Store in React Query for the component to read
+				queryClient.setQueryData<RouteDocsSchema>(ROUTE_DOCS_QUERY_KEY, schema);
+			} catch (error) {
+				console.warn("Failed to load route docs schema:", error);
+				// Store empty schema on error
+				queryClient.setQueryData<RouteDocsSchema>(ROUTE_DOCS_QUERY_KEY, {
+					plugins: [],
+					generatedAt: new Date().toISOString(),
+					allSitemapEntries: [],
+				});
+			}
+		}
+	};
+}
+
+/**
+ * Route Docs client plugin
+ * Provides a route that displays documentation for all client routes
+ */
+export const routeDocsClientPlugin = (config: RouteDocsClientConfig) => {
+	return defineClientPlugin({
+		name: "route-docs",
+
+		routes: (context?: ClientStackContext) => {
+			// Store context at module level for client-side schema generation
+			moduleStoredContext = context || null;
+
+			return {
+				docs: createRoute("/route-docs", () => {
+					return {
+						PageComponent: () => (
+							<DocsPageComponent
+								title={config.title}
+								description={config.description}
+								siteBasePath={config.siteBasePath || "/pages"}
+							/>
+						),
+						LoadingComponent: () => <DocsPageSkeleton />,
+						ErrorComponent: () => <DocsErrorComponent />,
+						loader: createRouteDocsLoader(config),
+						meta: createDocsMeta(config),
+					};
+				}),
+			};
+		},
+
+		sitemap: async () => {
+			// Route docs page should NOT be in sitemap
+			return [];
+		},
+	});
+};

package/src/plugins/route-docs/client.css

@@ -0,0 +1,3 @@
+/* Route Docs Plugin Client CSS */
+/* No custom styles needed - uses shadcn/ui components and Tailwind */
+

package/src/plugins/route-docs/generator.ts

@@ -0,0 +1,385 @@
+import type { ClientStackContext, SitemapEntry } from "../../types";
+import type { Route } from "@btst/yar";
+import * as z from "zod";
+
+/**
+ * Represents a documented route parameter
+ */
+export interface RouteParameter {
+	name: string;
+	type: string;
+	required: boolean;
+	description?: string;
+	schema?: Record<string, any>;
+}
+
+/**
+ * Sitemap entry with plugin source
+ */
+export interface PluginSitemapEntry extends SitemapEntry {
+	pluginKey: string;
+}
+
+/**
+ * Represents a documented route
+ */
+export interface DocumentedRoute {
+	/** Route key from the plugin */
+	key: string;
+	/** The route path pattern (e.g., "/users/:id") */
+	path: string;
+	/** Path parameters extracted from the path */
+	pathParams: RouteParameter[];
+	/** Query parameters from the route's query schema */
+	queryParams: RouteParameter[];
+	/** Route metadata */
+	meta?: {
+		title?: string;
+		description?: string;
+		tags?: string[];
+		[key: string]: any;
+	};
+}
+
+/**
+ * Represents a plugin's documented routes
+ */
+export interface DocumentedPlugin {
+	/** Plugin key */
+	key: string;
+	/** Plugin name */
+	name: string;
+	/** Routes from this plugin */
+	routes: DocumentedRoute[];
+	/** Sitemap entries from this plugin */
+	sitemapEntries: PluginSitemapEntry[];
+}
+
+/**
+ * The complete route documentation schema
+ */
+export interface RouteDocsSchema {
+	/** All documented plugins */
+	plugins: DocumentedPlugin[];
+	/** Generation timestamp */
+	generatedAt: string;
+	/** All sitemap entries aggregated */
+	allSitemapEntries: PluginSitemapEntry[];
+}
+
+/**
+ * Extract path parameters from a route path pattern
+ * e.g., "/users/:id/posts/:postId" => ["id", "postId"]
+ */
+function extractPathParams(path: string): string[] {
+	const params: string[] = [];
+	const segments = path.split("/");
+
+	for (const segment of segments) {
+		if (segment.startsWith(":")) {
+			params.push(segment.slice(1));
+		} else if (segment.startsWith("*:")) {
+			// Wildcard with name: /*:splat
+			params.push(segment.slice(2));
+		} else if (segment === "*") {
+			// Anonymous wildcard
+			params.push("_");
+		}
+	}
+
+	return params;
+}
+
+/**
+ * Get the primitive type from a Zod type
+ */
+function getTypeFromZodType(zodType: z.ZodType<any>): string {
+	if (zodType instanceof z.ZodString) return "string";
+	if (zodType instanceof z.ZodNumber) return "number";
+	if (zodType instanceof z.ZodBoolean) return "boolean";
+	if (zodType instanceof z.ZodArray) return "array";
+	if (zodType instanceof z.ZodObject) return "object";
+	if (zodType instanceof z.ZodEnum) return "enum";
+	if (zodType instanceof z.ZodLiteral) return "literal";
+	if (zodType instanceof z.ZodUnion) return "union";
+
+	// Fallback based on type property if available
+	const type = (zodType as any).type;
+	if (type === "string") return "string";
+	if (type === "number") return "number";
+	if (type === "boolean") return "boolean";
+	if (type === "array") return "array";
+	if (type === "object") return "object";
+
+	return "string";
+}
+
+/**
+ * Process a Zod type into a simplified schema
+ */
+function processZodType(zodType: z.ZodType<any>): Record<string, any> {
+	// Handle optional - unwrap and process inner type
+	if (zodType instanceof z.ZodOptional) {
+		const innerType =
+			(zodType as any)._def?.innerType || (zodType as any).unwrap?.();
+		if (innerType) {
+			return processZodType(innerType);
+		}
+	}
+
+	// Handle nullable
+	if (zodType instanceof z.ZodNullable) {
+		const innerType =
+			(zodType as any)._def?.innerType || (zodType as any).unwrap?.();
+		if (innerType) {
+			const innerSchema = processZodType(innerType);
+			return {
+				...innerSchema,
+				nullable: true,
+			};
+		}
+	}
+
+	// Handle default - unwrap and process inner type
+	if (zodType instanceof z.ZodDefault) {
+		const innerType = (zodType as any)._def?.innerType;
+		const defaultValue = (zodType as any)._def?.defaultValue?.();
+		if (innerType) {
+			const innerSchema = processZodType(innerType);
+			if (defaultValue !== undefined) {
+				return {
+					...innerSchema,
+					default: defaultValue,
+				};
+			}
+			return innerSchema;
+		}
+	}
+
+	// Handle object
+	if (zodType instanceof z.ZodObject) {
+		const shape = (zodType as any).shape || (zodType as any)._def?.shape?.();
+		if (shape) {
+			const properties: Record<string, any> = {};
+			const required: string[] = [];
+
+			for (const [key, value] of Object.entries(shape)) {
+				if (value instanceof z.ZodType) {
+					properties[key] = processZodType(value);
+					if (!(value instanceof z.ZodOptional)) {
+						required.push(key);
+					}
+				}
+			}
+
+			return {
+				type: "object",
+				properties,
+				...(required.length > 0 ? { required } : {}),
+			};
+		}
+	}
+
+	// Handle array
+	if (zodType instanceof z.ZodArray) {
+		const elementType = (zodType as any)._def?.type || (zodType as any).element;
+		return {
+			type: "array",
+			items: elementType ? processZodType(elementType) : { type: "string" },
+		};
+	}
+
+	// Handle enum
+	if (zodType instanceof z.ZodEnum) {
+		const values = (zodType as any)._def?.values || (zodType as any).options;
+		return {
+			type: "string",
+			enum: values,
+		};
+	}
+
+	// Handle literal
+	if (zodType instanceof z.ZodLiteral) {
+		const value = (zodType as any)._def?.value || (zodType as any).value;
+		return {
+			type: typeof value,
+			const: value,
+		};
+	}
+
+	// Handle union
+	if (zodType instanceof z.ZodUnion) {
+		const options = (zodType as any)._def?.options || (zodType as any).options;
+		if (options && Array.isArray(options)) {
+			return {
+				oneOf: options.map((opt: z.ZodType<any>) => processZodType(opt)),
+			};
+		}
+	}
+
+	// Handle coerce types
+	if ((zodType as any)._def?.coerce) {
+		const innerType = (zodType as any)._def?.innerType;
+		if (innerType) {
+			return processZodType(innerType);
+		}
+	}
+
+	// Default to primitive type
+	return {
+		type: getTypeFromZodType(zodType),
+	};
+}
+
+/**
+ * Check if an object is a StandardSchemaV1 (Zod) schema
+ */
+function isStandardSchema(obj: any): boolean {
+	return obj && typeof obj === "object" && "~standard" in obj;
+}
+
+/**
+ * Extract query parameters from a route's query schema
+ */
+function extractQueryParams(querySchema: any): RouteParameter[] {
+	const params: RouteParameter[] = [];
+
+	if (!querySchema) return params;
+
+	// Handle Zod objects directly
+	if (querySchema instanceof z.ZodObject) {
+		const shape =
+			(querySchema as any).shape || (querySchema as any)._def?.shape?.();
+		if (shape) {
+			for (const [key, value] of Object.entries(shape)) {
+				if (value instanceof z.ZodType) {
+					params.push({
+						name: key,
+						type: getTypeFromZodType(value),
+						required: !(value instanceof z.ZodOptional),
+						schema: processZodType(value),
+					});
+				}
+			}
+		}
+	}
+	// Handle StandardSchemaV1 (which Zod implements)
+	else if (isStandardSchema(querySchema)) {
+		// Try to access the underlying Zod schema
+		const zodSchema = querySchema;
+		if (zodSchema instanceof z.ZodObject) {
+			return extractQueryParams(zodSchema);
+		}
+	}
+
+	return params;
+}
+
+/**
+ * Fetch sitemap data from all plugins
+ */
+export async function fetchAllSitemapEntries(
+	context: ClientStackContext,
+): Promise<PluginSitemapEntry[]> {
+	const allEntries: PluginSitemapEntry[] = [];
+
+	for (const [pluginKey, plugin] of Object.entries(context.plugins)) {
+		// Skip route-docs plugin
+		if (pluginKey === "routeDocs" || plugin.name === "route-docs") {
+			continue;
+		}
+
+		if (plugin.sitemap) {
+			try {
+				const entries = await plugin.sitemap();
+				for (const entry of entries) {
+					allEntries.push({
+						...entry,
+						pluginKey,
+					});
+				}
+			} catch (error) {
+				console.warn(`Failed to fetch sitemap for plugin ${pluginKey}:`, error);
+			}
+		}
+	}
+
+	return allEntries;
+}
+
+/**
+ * Generate route documentation schema from client stack context
+ */
+export function generateRouteDocsSchema(
+	context: ClientStackContext,
+	sitemapEntries: PluginSitemapEntry[] = [],
+): RouteDocsSchema {
+	const documentedPlugins: DocumentedPlugin[] = [];
+
+	// Group sitemap entries by plugin
+	const sitemapByPlugin: Record<string, PluginSitemapEntry[]> = {};
+	for (const entry of sitemapEntries) {
+		if (!sitemapByPlugin[entry.pluginKey]) {
+			sitemapByPlugin[entry.pluginKey] = [];
+		}
+		sitemapByPlugin[entry.pluginKey]!.push(entry);
+	}
+
+	// Iterate over all plugins
+	for (const [pluginKey, plugin] of Object.entries(context.plugins)) {
+		// Skip the route-docs plugin itself
+		if (pluginKey === "routeDocs" || plugin.name === "route-docs") {
+			continue;
+		}
+
+		// Get plugin routes
+		const pluginRoutes = plugin.routes(context);
+		const documentedRoutes: DocumentedRoute[] = [];
+
+		// Process each route
+		for (const [routeKey, route] of Object.entries(pluginRoutes)) {
+			const r = route as Route;
+
+			// Access route properties
+			const path = r.path;
+			const routeOptions = r.options || {};
+			const routeMeta = r.meta;
+
+			if (!path) continue;
+
+			// Extract path parameters from the path pattern
+			const pathParamNames = extractPathParams(path);
+			const pathParams: RouteParameter[] = pathParamNames.map((name) => ({
+				name,
+				type: "string", // Path params are always strings
+				required: true,
+			}));
+
+			// Extract query parameters from the query schema
+			const queryParams = extractQueryParams(routeOptions.query);
+
+			documentedRoutes.push({
+				key: routeKey,
+				path,
+				pathParams,
+				queryParams,
+				meta: routeMeta as DocumentedRoute["meta"],
+			});
+		}
+
+		if (documentedRoutes.length > 0) {
+			documentedPlugins.push({
+				key: pluginKey,
+				name: plugin.name,
+				routes: documentedRoutes,
+				sitemapEntries: sitemapByPlugin[pluginKey] || [],
+			});
+		}
+	}
+
+	return {
+		plugins: documentedPlugins,
+		generatedAt: new Date().toISOString(),
+		allSitemapEntries: sitemapEntries,
+	};
+}

package/src/plugins/route-docs/index.ts

@@ -0,0 +1,12 @@
+export {
+	routeDocsClientPlugin,
+	type RouteDocsClientConfig,
+} from "./client";
+
+export {
+	generateRouteDocsSchema,
+	type RouteDocsSchema,
+	type DocumentedPlugin,
+	type DocumentedRoute,
+	type RouteParameter,
+} from "./generator";

package/src/plugins/route-docs/style.css

@@ -0,0 +1,19 @@
+@import "./client.css";
+
+/*
+ * Route Docs Plugin CSS - Includes Tailwind class scanning
+ * 
+ * When consumed from npm, Tailwind v4 will automatically scan this package's
+ * source files for Tailwind classes. Consumers only need:
+ *   @import "@btst/stack/plugins/route-docs/css";
+ */
+
+/* Scan this package's source files for Tailwind classes */
+@source "../../../src/**/*.{ts,tsx}";
+
+/* Scan UI package components (when installed as npm package the UI package will be in this dir) */
+@source "../../packages/ui/src";
+
+/*
+* alternatively consumer can use @source "../node_modules/@btst/stack/src/**\/*.{ts,tsx}";
+*/

package/src/types.ts

@@ -15,6 +15,22 @@ export interface BetterStackContext {
 	adapter: Adapter;
 }
 
+/**
+ * Context passed to client plugins during route creation
+ * Provides access to all registered plugins for introspection (used by routeDocs plugin)
+ */
+export interface ClientStackContext<
+	TPlugins extends Record<string, ClientPlugin<any, any>> = Record<
+		string,
+		ClientPlugin<any, any>
+	>,
+> {
+	/** All registered client plugins */
+	plugins: TPlugins;
+	/** The base path for the client (e.g., "/app") */
+	basePath?: string;
+}
+
 /**
  * Backend plugin definition
  * Defines API routes and data access for a feature
@@ -59,8 +75,10 @@ export interface ClientPlugin<
 	/**
 	 * Define routes (pages) for this plugin
 	 * Returns yar routes that will be composed into the router
+	 *
+	 * @param context - Optional context with access to all plugins (for introspection)
 	 */
-	routes: () => TRoutes;
+	routes: (context?: ClientStackContext) => TRoutes;
 
 	/**
 	 * Optional sitemap generator for this plugin. Should return absolute URLs.

package/dist/shared/{stack.CcI4sYJP.d.mts → stack.DLhzx1-D.d.cts}

@@ -35,10 +35,10 @@ interface SerializedTag extends Omit<Tag, "createdAt" | "updatedAt"> {
 }
 
 declare const createPostSchema: z.ZodObject<{
+    title: z.ZodString;
     slug: z.ZodOptional<z.ZodString>;
     published: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
-    title: z.ZodString;
     content: z.ZodString;
     excerpt: z.ZodString;
     image: z.ZodOptional<z.ZodString>;

package/dist/shared/{stack.CcI4sYJP.d.ts → stack.DLhzx1-D.d.mts}

@@ -35,10 +35,10 @@ interface SerializedTag extends Omit<Tag, "createdAt" | "updatedAt"> {
 }
 
 declare const createPostSchema: z.ZodObject<{
+    title: z.ZodString;
     slug: z.ZodOptional<z.ZodString>;
     published: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
-    title: z.ZodString;
     content: z.ZodString;
     excerpt: z.ZodString;
     image: z.ZodOptional<z.ZodString>;

package/dist/shared/{stack.CcI4sYJP.d.cts → stack.DLhzx1-D.d.ts}

@@ -35,10 +35,10 @@ interface SerializedTag extends Omit<Tag, "createdAt" | "updatedAt"> {
 }
 
 declare const createPostSchema: z.ZodObject<{
+    title: z.ZodString;
     slug: z.ZodOptional<z.ZodString>;
     published: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
-    title: z.ZodString;
     content: z.ZodString;
     excerpt: z.ZodString;
     image: z.ZodOptional<z.ZodString>;