@btst/stack 1.7.0 → 1.8.0

package/dist/plugins/route-docs/client/index.d.ts

@@ -0,0 +1,126 @@
+import * as _btst_stack_plugins_client from '@btst/stack/plugins/client';
+import * as react from 'react';
+import * as _btst_yar from '@btst/yar';
+import { QueryClient } from '@tanstack/react-query';
+import { S as SitemapEntry, b as ClientStackContext } from '../../../shared/stack.u9iYV6vt.js';
+import '@btst/db';
+import 'better-call';
+
+/**
+ * Represents a documented route parameter
+ */
+interface RouteParameter {
+    name: string;
+    type: string;
+    required: boolean;
+    description?: string;
+    schema?: Record<string, any>;
+}
+/**
+ * Sitemap entry with plugin source
+ */
+interface PluginSitemapEntry extends SitemapEntry {
+    pluginKey: string;
+}
+/**
+ * Represents a documented route
+ */
+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
+ */
+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
+ */
+interface RouteDocsSchema {
+    /** All documented plugins */
+    plugins: DocumentedPlugin[];
+    /** Generation timestamp */
+    generatedAt: string;
+    /** All sitemap entries aggregated */
+    allSitemapEntries: PluginSitemapEntry[];
+}
+
+/**
+ * Query key for route docs schema
+ */
+declare const ROUTE_DOCS_QUERY_KEY: readonly ["route-docs", "schema"];
+/**
+ * Get the stored client stack context
+ * Used by the docs page component to generate schema on client-side navigation
+ */
+declare function getStoredContext(): ClientStackContext | null;
+/**
+ * Generate the route docs schema from the stored context
+ * This can be called from both server and client
+ */
+declare function generateSchema(): Promise<RouteDocsSchema>;
+/**
+ * Configuration for Route Docs client plugin
+ */
+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;
+}
+/**
+ * Route Docs client plugin
+ * Provides a route that displays documentation for all client routes
+ */
+declare const routeDocsClientPlugin: (config: RouteDocsClientConfig) => _btst_stack_plugins_client.ClientPlugin<Record<string, never>, {
+    docs: {
+        (inputCtx_0?: _btst_yar.InputContext<"/route-docs", _btst_yar.RouteOptions> | undefined): {
+            PageComponent?: react.ComponentType<unknown> | undefined;
+            LoadingComponent?: react.ComponentType<unknown> | undefined;
+            ErrorComponent?: react.ComponentType<unknown> | undefined;
+            loader?: (() => Promise<void>) | undefined;
+            meta?: (() => ({
+                title: string;
+                name?: undefined;
+                content?: undefined;
+            } | {
+                name: string;
+                content: string;
+                title?: undefined;
+            })[]) | undefined;
+            extra?: (() => any) | undefined;
+        };
+        options: _btst_yar.RouteOptions | undefined;
+        path: "/route-docs";
+        meta: _btst_yar.RouteMeta | undefined;
+    };
+}>;
+
+export { ROUTE_DOCS_QUERY_KEY, generateSchema, getStoredContext, routeDocsClientPlugin };
+export type { RouteDocsClientConfig };

package/dist/plugins/route-docs/client/index.mjs

@@ -0,0 +1 @@
+export { ROUTE_DOCS_QUERY_KEY, generateSchema, getStoredContext, routeDocsClientPlugin } from '../../../packages/better-stack/src/plugins/route-docs/client/plugin.mjs';

package/dist/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/dist/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/dist/shared/{stack.CSce37mX.d.cts → stack.u9iYV6vt.d.cts}

@@ -14,6 +14,16 @@ interface BetterStackContext {
     /** The database adapter */
     adapter: Adapter;
 }
+/**
+ * Context passed to client plugins during route creation
+ * Provides access to all registered plugins for introspection (used by routeDocs plugin)
+ */
+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
@@ -50,8 +60,10 @@ interface ClientPlugin<TOverrides = Record<string, never>, TRoutes extends Recor
     /**
      * 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.
      * Implementations can call their own API endpoints to include dynamic routes.
@@ -142,4 +154,4 @@ type SitemapEntry = {
 };
 type Sitemap = Array<SitemapEntry>;
 
-export type { BackendPlugin as B, ClientPlugin as C, PluginOverrides as P, Sitemap as S, BetterStackContext as a, PluginRoutes as b, ClientLibConfig as c, ClientLib as d, PrefixedPluginRoutes as e, BackendLibConfig as f, BackendLib as g };
+export type { BackendPlugin as B, ClientPlugin as C, PluginOverrides as P, SitemapEntry as S, BetterStackContext as a, ClientStackContext as b, Sitemap as c, PluginRoutes as d, ClientLibConfig as e, ClientLib as f, PrefixedPluginRoutes as g, BackendLibConfig as h, BackendLib as i };

package/dist/shared/{stack.CSce37mX.d.mts → stack.u9iYV6vt.d.mts}

@@ -14,6 +14,16 @@ interface BetterStackContext {
     /** The database adapter */
     adapter: Adapter;
 }
+/**
+ * Context passed to client plugins during route creation
+ * Provides access to all registered plugins for introspection (used by routeDocs plugin)
+ */
+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
@@ -50,8 +60,10 @@ interface ClientPlugin<TOverrides = Record<string, never>, TRoutes extends Recor
     /**
      * 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.
      * Implementations can call their own API endpoints to include dynamic routes.
@@ -142,4 +154,4 @@ type SitemapEntry = {
 };
 type Sitemap = Array<SitemapEntry>;
 
-export type { BackendPlugin as B, ClientPlugin as C, PluginOverrides as P, Sitemap as S, BetterStackContext as a, PluginRoutes as b, ClientLibConfig as c, ClientLib as d, PrefixedPluginRoutes as e, BackendLibConfig as f, BackendLib as g };
+export type { BackendPlugin as B, ClientPlugin as C, PluginOverrides as P, SitemapEntry as S, BetterStackContext as a, ClientStackContext as b, Sitemap as c, PluginRoutes as d, ClientLibConfig as e, ClientLib as f, PrefixedPluginRoutes as g, BackendLibConfig as h, BackendLib as i };

package/dist/shared/{stack.CSce37mX.d.ts → stack.u9iYV6vt.d.ts}

@@ -14,6 +14,16 @@ interface BetterStackContext {
     /** The database adapter */
     adapter: Adapter;
 }
+/**
+ * Context passed to client plugins during route creation
+ * Provides access to all registered plugins for introspection (used by routeDocs plugin)
+ */
+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
@@ -50,8 +60,10 @@ interface ClientPlugin<TOverrides = Record<string, never>, TRoutes extends Recor
     /**
      * 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.
      * Implementations can call their own API endpoints to include dynamic routes.
@@ -142,4 +154,4 @@ type SitemapEntry = {
 };
 type Sitemap = Array<SitemapEntry>;
 
-export type { BackendPlugin as B, ClientPlugin as C, PluginOverrides as P, Sitemap as S, BetterStackContext as a, PluginRoutes as b, ClientLibConfig as c, ClientLib as d, PrefixedPluginRoutes as e, BackendLibConfig as f, BackendLib as g };
+export type { BackendPlugin as B, ClientPlugin as C, PluginOverrides as P, SitemapEntry as S, BetterStackContext as a, ClientStackContext as b, Sitemap as c, PluginRoutes as d, ClientLibConfig as e, ClientLib as f, PrefixedPluginRoutes as g, BackendLibConfig as h, BackendLib as i };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btst/stack",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "A composable, plugin-based library for building full-stack applications.",
   "repository": {
     "type": "git",
@@ -257,6 +257,17 @@
         "default": "./dist/plugins/open-api/api/index.cjs"
       }
     },
+    "./plugins/route-docs/client": {
+      "import": {
+        "types": "./dist/plugins/route-docs/client/index.d.ts",
+        "default": "./dist/plugins/route-docs/client/index.mjs"
+      },
+      "require": {
+        "types": "./dist/plugins/route-docs/client/index.d.cts",
+        "default": "./dist/plugins/route-docs/client/index.cjs"
+      }
+    },
+    "./plugins/route-docs/css": "./dist/plugins/route-docs/style.css",
     "./dist/*": "./dist/*",
     "./ui/css": "./dist/ui/components.css",
     "./package.json": "./package.json"
@@ -325,6 +336,9 @@
       ],
       "plugins/open-api/api": [
         "./dist/plugins/open-api/api/index.d.ts"
+      ],
+      "plugins/route-docs/client": [
+        "./dist/plugins/route-docs/client/index.d.ts"
       ]
     }
   },

package/src/client/index.ts

@@ -4,10 +4,11 @@ import type {
 	ClientLibConfig,
 	ClientLib,
 	ClientPlugin,
+	ClientStackContext,
 	PluginRoutes,
 	Sitemap,
 } from "../types";
-export type { ClientPlugin } from "../types";
+export type { ClientPlugin, ClientStackContext } from "../types";
 
 /**
  * Creates the client library with plugin support
@@ -60,15 +61,21 @@ export function createStackClient<
 	TPlugins extends Record<string, ClientPlugin<any, any>>,
 	TRoutes extends PluginRoutes<TPlugins> = PluginRoutes<TPlugins>,
 >(config: ClientLibConfig<TPlugins>): ClientLib<TRoutes> {
-	const { plugins } = config;
+	const { plugins, basePath } = config;
 
 	// Collect all routes from all plugins
 	// We build this with type assertions to preserve literal keys
 	const allRoutes = {} as TRoutes;
 
+	// Create the context object to pass to plugin routes
+	const clientStackContext: ClientStackContext<TPlugins> = {
+		plugins,
+		basePath,
+	};
+
 	for (const [pluginKey, plugin] of Object.entries(plugins)) {
-		// Add routes
-		const pluginRoutes = plugin.routes();
+		// Add routes - pass the context for plugins that need introspection (e.g., routeDocs)
+		const pluginRoutes = plugin.routes(clientStackContext);
 		Object.assign(allRoutes, pluginRoutes);
 	}
 

package/src/plugins/route-docs/client/components/loading/docs-skeleton.tsx

@@ -0,0 +1,82 @@
+"use client";
+
+import { Skeleton } from "@workspace/ui/components/skeleton";
+import { ScrollArea } from "@workspace/ui/components/scroll-area";
+import { Card, CardContent } from "@workspace/ui/components/card";
+
+export function DocsPageSkeleton() {
+	return (
+		<div className="flex min-h-screen bg-background">
+			{/* Desktop Sidebar skeleton */}
+			<aside className="hidden md:block w-72 border-r bg-card shrink-0">
+				<div className="p-4 border-b">
+					<Skeleton className="h-4 w-16" />
+				</div>
+				<ScrollArea className="h-[calc(100vh-57px)]">
+					<div className="p-3 space-y-4">
+						{/* Plugin groups */}
+						{[1, 2, 3].map((i) => (
+							<div key={i} className="space-y-2">
+								<Skeleton className="h-8 w-full" />
+								<div className="ml-2 space-y-1">
+									{[1, 2, 3].map((j) => (
+										<Skeleton key={j} className="h-7 w-full" />
+									))}
+								</div>
+							</div>
+						))}
+					</div>
+				</ScrollArea>
+			</aside>
+
+			{/* Mobile header skeleton */}
+			<div className="md:hidden fixed top-0 left-0 right-0 z-40 bg-card border-b">
+				<div className="flex items-center justify-between p-4">
+					<Skeleton className="h-4 w-24" />
+					<Skeleton className="h-8 w-20" />
+				</div>
+			</div>
+
+			{/* Main content skeleton */}
+			<main className="flex-1 overflow-auto pt-16 md:pt-0">
+				<div className="max-w-4xl mx-auto p-4 sm:p-6 lg:p-8 space-y-4 sm:space-y-6">
+					{/* Title */}
+					<div className="space-y-2">
+						<Skeleton className="h-8 sm:h-9 w-48 sm:w-64" />
+						<Skeleton className="h-4 sm:h-5 w-72 sm:w-96" />
+					</div>
+
+					{/* Separator */}
+					<div className="h-px bg-border" />
+
+					{/* Badges */}
+					<div className="flex gap-2">
+						<Skeleton className="h-6 w-24" />
+						<Skeleton className="h-6 w-20" />
+					</div>
+
+					{/* Routes card */}
+					<Card>
+						<div className="p-4 sm:p-6">
+							<Skeleton className="h-6 w-32 mb-4" />
+						</div>
+						<CardContent className="pt-0 space-y-4">
+							{/* Desktop table skeleton */}
+							<div className="hidden md:block space-y-2">
+								{[1, 2, 3, 4].map((i) => (
+									<Skeleton key={i} className="h-12 w-full" />
+								))}
+							</div>
+							{/* Mobile cards skeleton */}
+							<div className="md:hidden space-y-3">
+								{[1, 2, 3].map((i) => (
+									<Skeleton key={i} className="h-28 w-full rounded-lg" />
+								))}
+							</div>
+						</CardContent>
+					</Card>
+				</div>
+			</main>
+		</div>
+	);
+}

package/src/plugins/route-docs/client/components/loading/index.tsx

@@ -0,0 +1 @@
+export { DocsPageSkeleton } from "./docs-skeleton";