@btst/stack 1.0.0 → 1.1.0

package/src/client/components/compose.tsx

@@ -0,0 +1,116 @@
+"use client";
+
+import React, { Suspense, type ErrorInfo } from "react";
+import { type FallbackProps } from "react-error-boundary";
+import type { createRouter } from "@btst/yar";
+import { ErrorBoundary } from "./error-boundary";
+
+/**
+ * Route type with optional components
+ */
+export type RouteWithComponents =
+	| {
+			PageComponent?: React.ComponentType;
+			ErrorComponent?: React.ComponentType<FallbackProps>;
+			LoadingComponent?: React.ComponentType;
+	  }
+	| null
+	| undefined;
+
+/**
+ * Composes the route content with Suspense and Error Boundary
+ * Resolves the route on the client-side where component references are available
+ *
+ * This is marked "use client" so it can access component references safely
+ */
+export function RouteRenderer({
+	router,
+	path,
+	NotFoundComponent,
+	onNotFound,
+	onError,
+	props,
+}: {
+	router: ReturnType<typeof createRouter>;
+	path: string;
+	NotFoundComponent?: React.ComponentType<{ message: string }>;
+	onNotFound?: () => never;
+	onError: (error: Error, info: ErrorInfo) => void;
+	props?: any;
+}) {
+	// Resolve route on the client where components are available
+	const route = router.getRoute(path);
+
+	return (
+		<ComposedRoute
+			path={path}
+			PageComponent={route?.PageComponent}
+			ErrorComponent={route?.ErrorComponent}
+			LoadingComponent={route?.LoadingComponent}
+			onNotFound={onNotFound}
+			NotFoundComponent={NotFoundComponent}
+			onError={onError}
+			props={props}
+		/>
+	);
+}
+
+export function ComposedRoute({
+	path,
+	PageComponent,
+	ErrorComponent,
+	LoadingComponent,
+	onNotFound,
+	NotFoundComponent,
+	props,
+	onError,
+}: {
+	path: string;
+	PageComponent: React.ComponentType<any>;
+	ErrorComponent?: React.ComponentType<FallbackProps>;
+	LoadingComponent: React.ComponentType;
+	onNotFound?: () => never;
+	NotFoundComponent?: React.ComponentType<{ message: string }>;
+	props?: any;
+	onError: (error: Error, info: ErrorInfo) => void;
+}) {
+	if (PageComponent) {
+		const content = <PageComponent {...props} />;
+		// Avoid server-side skeletons: only show loading fallback in the browser
+		const isBrowser = typeof window !== "undefined";
+		const suspenseFallback =
+			isBrowser && LoadingComponent ? <LoadingComponent /> : null;
+
+		// If an ErrorComponent is provided (which itself may be lazy), ensure we have
+		// a Suspense boundary that can handle both the page content and the lazy error UI
+		if (ErrorComponent) {
+			return (
+				<Suspense key={`outer-${path}`} fallback={suspenseFallback}>
+					<ErrorBoundary
+						FallbackComponent={ErrorComponent}
+						resetKeys={[path]}
+						onError={onError}
+					>
+						<Suspense key={`inner-${path}`} fallback={suspenseFallback}>
+							{content}
+						</Suspense>
+					</ErrorBoundary>
+				</Suspense>
+			);
+		}
+
+		return (
+			<Suspense key={path} fallback={suspenseFallback}>
+				{content}
+			</Suspense>
+		);
+	} else {
+		if (onNotFound) {
+			onNotFound();
+		}
+
+		if (NotFoundComponent) {
+			return <NotFoundComponent message={`Unknown route: ${path}`} />;
+		}
+	}
+}

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

@@ -0,0 +1,30 @@
+"use client";
+import type { ErrorInfo } from "react";
+import {
+	ErrorBoundary as ReactErrorBoundary,
+	type FallbackProps,
+} from "react-error-boundary";
+
+export type { FallbackProps } from "react-error-boundary";
+
+export function ErrorBoundary({
+	children,
+	FallbackComponent,
+	resetKeys,
+	onError,
+}: {
+	children: React.ReactNode;
+	FallbackComponent: React.ComponentType<FallbackProps>;
+	resetKeys?: Array<string | number | boolean | null | undefined>;
+	onError: (error: Error, info: ErrorInfo) => void;
+}) {
+	return (
+		<ReactErrorBoundary
+			FallbackComponent={FallbackComponent}
+			onError={onError}
+			resetKeys={resetKeys}
+		>
+			{children}
+		</ReactErrorBoundary>
+	);
+}

package/src/client/components/index.tsx

@@ -0,0 +1,2 @@
+export * from "./compose";
+export * from "./error-boundary";

package/src/client/index.ts

@@ -0,0 +1,107 @@
+import { createRouter } from "@btst/yar";
+
+import type {
+	ClientLibConfig,
+	ClientLib,
+	ClientPlugin,
+	PluginRoutes,
+	Sitemap,
+} from "../types";
+export type { ClientPlugin } from "../types";
+
+/**
+ * Creates the client library with plugin support
+ *
+ * @example
+ * ```ts
+ * // For Next.js with SSR:
+ * const lib = createStackClient({
+ *   plugins: {
+ *     blog: blogPlugin.client
+ *   }
+ * });
+ *
+ * // SPA usage - just render the route
+ * function Page() {
+ *   return lib.resolveRoute('/blog');
+ * }
+ *
+ * // SSR usage - prefetch data with loader, then render
+ * async function Page({ params }) {
+ *   const path = '/blog';
+ *
+ *   // Load data server-side if loader exists
+ *   const loader = lib.getLoader(path);
+ *   if (loader) await loader(queryClient, baseURL, basePath);
+ *
+ *   // Render with built-in Suspense + Error Boundary
+ *   return lib.resolveRoute(path);
+ * }
+ *
+ * // Next.js with notFound() function
+ * import { notFound } from 'next/navigation';
+ *
+ * async function Page({ params }) {
+ *   const path = '/blog';
+ *   const loader = lib.getLoader(path);
+ *   if (loader) await loader(queryClient, baseURL);
+ *
+ *   return lib.resolveRoute(path, {
+ *     onNotFound: notFound // Calls Next.js notFound() instead of rendering
+ *   });
+ * }
+ *
+ * ```
+ *
+ * @template TPlugins - The exact plugins map (inferred from config)
+ * @template TRoutes - All routes from all plugins, merged (computed automatically)
+ */
+export function createStackClient<
+	TPlugins extends Record<string, ClientPlugin<any, any>>,
+	TRoutes extends PluginRoutes<TPlugins> = PluginRoutes<TPlugins>,
+>(config: ClientLibConfig<TPlugins>): ClientLib<TRoutes> {
+	const { plugins } = config;
+
+	// Collect all routes from all plugins
+	// We build this with type assertions to preserve literal keys
+	const allRoutes = {} as TRoutes;
+
+	for (const [pluginKey, plugin] of Object.entries(plugins)) {
+		// Add routes
+		const pluginRoutes = plugin.routes();
+		Object.assign(allRoutes, pluginRoutes);
+	}
+
+	// Create the composed router - TypeScript will infer the router type
+	// The router's getRoute method will return the union of all route return types
+	const router = createRouter<TRoutes, {}>(allRoutes);
+
+	return {
+		router,
+		async generateSitemap() {
+			const sitemapEntries: Sitemap = [];
+			for (const plugin of Object.values(plugins)) {
+				if (typeof plugin.sitemap === "function") {
+					// Allow each plugin to return a partial sitemap
+					const entries = await plugin.sitemap();
+					if (Array.isArray(entries)) sitemapEntries.push(...entries);
+				}
+			}
+			// De-duplicate by URL while preserving lastModified/priorities preferring the first occurrence
+			const seen = new Set<string>();
+			const deduped: Sitemap = [];
+			for (const entry of sitemapEntries) {
+				if (!entry?.url || seen.has(entry.url)) continue;
+				seen.add(entry.url);
+				deduped.push(entry);
+			}
+			return deduped;
+		},
+	};
+}
+
+export type { ClientLib, ClientLibConfig };
+
+export { sitemapEntryToXmlString } from "./sitemap-utils";
+
+export { metaElementsToObject } from "./meta-utils";

package/src/client/meta-utils.ts

@@ -0,0 +1,228 @@
+interface Metadata {
+	title: string;
+	description?: string;
+	keywords?: string[];
+	applicationName?: string;
+	generator?: string;
+	referrer?:
+		| "no-referrer"
+		| "origin"
+		| "no-referrer-when-downgrade"
+		| "origin-when-cross-origin"
+		| "same-origin"
+		| "strict-origin"
+		| "strict-origin-when-cross-origin";
+	themeColor?: string;
+	viewport?: string;
+	creator?: string;
+	publisher?: string;
+	authors?: { name: string }[];
+	abstract?: string;
+	robots?: string;
+	alternates?: Partial<{ canonical: string }>;
+	twitter?: Partial<{
+		title: string;
+		description: string;
+		site: string;
+		creator: string;
+		images?: string[];
+	}>;
+	openGraph?: Partial<{
+		title: string;
+		description: string;
+		url: string;
+		siteName: string;
+		locale: string;
+		images?: string[];
+		videos?: string[];
+		audio?: string[];
+	}>;
+}
+
+/**
+ * Converts an array of meta elements to a metadata object
+ * @param metaElements - An array of meta elements
+ * @example
+ * ```ts
+ * const metaElements = [
+ *   { name: "title", content: "My Page" },
+ *   { name: "description", content: "This is my page" },
+ * ];
+ * const metadata = metaElementsToObject(metaElements);
+ * console.log(metadata);
+ * ```
+ */
+export function metaElementsToObject(
+	metaElements: Array<React.JSX.IntrinsicElements["meta"] | undefined>,
+) {
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	const metadata: Metadata = { title: "" };
+
+	// Handlers for meta name= mappings
+	const nameHandlers: Record<string, (content: string) => void> = {
+		title: (c) => {
+			metadata.title = c;
+		},
+		description: (c) => {
+			metadata.description = c;
+		},
+		keywords: (c) => {
+			const parts = c
+				.split(",")
+				.map((k) => k.trim())
+				.filter(Boolean);
+			metadata.keywords = parts.length > 0 ? parts : undefined;
+		},
+		"application-name": (c) => {
+			metadata.applicationName = c;
+		},
+		generator: (c) => {
+			metadata.generator = c;
+		},
+		referrer: (c) => {
+			const allowedReferrers = new Set([
+				"no-referrer",
+				"origin",
+				"no-referrer-when-downgrade",
+				"origin-when-cross-origin",
+				"same-origin",
+				"strict-origin",
+				"strict-origin-when-cross-origin",
+				"unsafe-url",
+			]);
+			if (allowedReferrers.has(c)) {
+				metadata.referrer = c as never;
+			}
+		},
+		"theme-color": (c) => {
+			metadata.themeColor = c;
+		},
+		viewport: (c) => {
+			metadata.viewport = c;
+		},
+		creator: (c) => {
+			metadata.creator = c;
+		},
+		publisher: (c) => {
+			metadata.publisher = c;
+		},
+		author: (c) => {
+			metadata.authors = [{ name: c }];
+		},
+		abstract: (c) => {
+			metadata.abstract = c;
+		},
+		robots: (c) => {
+			metadata.robots = c;
+		},
+		// Twitter
+		"twitter:title": (c) => {
+			if (!metadata.twitter) metadata.twitter = {};
+			metadata.twitter.title = c;
+		},
+		"twitter:description": (c) => {
+			if (!metadata.twitter) metadata.twitter = {};
+			metadata.twitter.description = c;
+		},
+		"twitter:site": (c) => {
+			if (!metadata.twitter) metadata.twitter = {};
+			metadata.twitter.site = c;
+		},
+		"twitter:creator": (c) => {
+			if (!metadata.twitter) metadata.twitter = {};
+			metadata.twitter.creator = c;
+		},
+		"twitter:image": (c) => {
+			if (!metadata.twitter) metadata.twitter = {};
+			const currentImages = metadata.twitter.images;
+			if (!currentImages) {
+				metadata.twitter.images = [c];
+			} else if (Array.isArray(currentImages)) {
+				metadata.twitter.images = [...currentImages, c];
+			} else {
+				metadata.twitter.images = [currentImages, c];
+			}
+		},
+	};
+
+	// Handlers for meta property= (Open Graph)
+	const propertyHandlers: Record<string, (content: string) => void> = {
+		"og:title": (c) => {
+			if (!metadata.openGraph) metadata.openGraph = {};
+			metadata.openGraph.title = c;
+		},
+		"og:description": (c) => {
+			if (!metadata.openGraph) metadata.openGraph = {};
+			metadata.openGraph.description = c;
+		},
+		"og:url": (c) => {
+			if (!metadata.openGraph) metadata.openGraph = {};
+			metadata.openGraph.url = c;
+			metadata.alternates = {
+				...(metadata.alternates ?? {}),
+				canonical: c,
+			};
+		},
+		"og:site_name": (c) => {
+			if (!metadata.openGraph) metadata.openGraph = {};
+			metadata.openGraph.siteName = c;
+		},
+		"og:locale": (c) => {
+			if (!metadata.openGraph) metadata.openGraph = {};
+			metadata.openGraph.locale = c;
+		},
+		"og:image": (c) => {
+			if (!metadata.openGraph) metadata.openGraph = {};
+			const currentImages = metadata.openGraph.images;
+			if (!currentImages) {
+				metadata.openGraph.images = [c];
+			} else if (Array.isArray(currentImages)) {
+				metadata.openGraph.images = [...currentImages, c];
+			} else {
+				metadata.openGraph.images = [currentImages, c];
+			}
+		},
+		"og:video": (c) => {
+			if (!metadata.openGraph) metadata.openGraph = {};
+			const currentVideos = metadata.openGraph.videos;
+			if (!currentVideos) {
+				metadata.openGraph.videos = [c];
+			} else if (Array.isArray(currentVideos)) {
+				metadata.openGraph.videos = [...currentVideos, c];
+			} else {
+				metadata.openGraph.videos = [currentVideos, c];
+			}
+		},
+		"og:audio": (c) => {
+			if (!metadata.openGraph) metadata.openGraph = {};
+			const currentAudio = metadata.openGraph.audio;
+			if (!currentAudio) {
+				metadata.openGraph.audio = [c];
+			} else if (Array.isArray(currentAudio)) {
+				metadata.openGraph.audio = [...currentAudio, c];
+			} else {
+				metadata.openGraph.audio = [currentAudio, c];
+			}
+		},
+	};
+
+	for (const meta of metaElements) {
+		if (!meta) continue;
+
+		// name-based
+		if ("name" in meta && "content" in meta) {
+			const handler = nameHandlers[String(meta.name)];
+			if (handler) handler(String(meta.content));
+			continue;
+		}
+
+		// property-based (Open Graph)
+		if ("property" in meta && "content" in meta) {
+			const handler = propertyHandlers[String(meta.property)];
+			if (handler) handler(String(meta.content));
+			continue;
+		}
+	}
+
+	return metadata;
+}

package/src/client/sitemap-utils.ts

@@ -0,0 +1,46 @@
+import type { Sitemap } from "../types";
+
+/**
+ * Converts an array of sitemap entries into an XML string following the sitemap.org protocol.
+ *
+ * @param entries - Array of sitemap entries from `lib.generateSitemap()`
+ * @returns Complete XML string for the sitemap
+ *
+ * @example
+ * ```ts
+ * const entries = await lib.generateSitemap();
+ * const xml = sitemapEntryToXmlString(entries);
+ * return new Response(xml, {
+ *   headers: { "Content-Type": "application/xml; charset=utf-8" }
+ * });
+ * ```
+ */
+export function sitemapEntryToXmlString(entries: Sitemap): string {
+	const xml =
+		`<?xml version="1.0" encoding="UTF-8"?>` +
+		`<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">` +
+		entries
+			.map((entry) => {
+				const url = `<loc>${entry.url}</loc>`;
+				const lastModified = entry.lastModified
+					? `<lastmod>${
+							entry.lastModified instanceof Date
+								? entry.lastModified.toISOString()
+								: entry.lastModified
+						}</lastmod>`
+					: "";
+				const changeFrequency = entry.changeFrequency
+					? `<changefreq>${entry.changeFrequency}</changefreq>`
+					: "";
+				const priority =
+					entry.priority !== undefined
+						? `<priority>${entry.priority}</priority>`
+						: "";
+
+				return `<url>${url}${lastModified}${changeFrequency}${priority}</url>`;
+			})
+			.join("") +
+		`</urlset>`;
+
+	return xml;
+}

package/src/context/index.ts

@@ -0,0 +1 @@
+export * from "./provider";

package/src/context/provider.tsx

@@ -0,0 +1,157 @@
+"use client";
+import { createContext, useContext, type ReactNode } from "react";
+
+/**
+ * Context value that provides plugin-specific overrides
+ * Generic over the shape of all plugin overrides
+ */
+interface BetterStackContextValue<
+	TPluginOverrides extends Record<string, any>,
+> {
+	/**
+	 * The overrides for the plugin.
+	 */
+	overrides: TPluginOverrides;
+	/**
+	 * The base path where the client router is mounted.
+	 */
+	basePath: string;
+}
+
+const BetterStackContext = createContext<BetterStackContextValue<any> | null>(
+	null,
+);
+
+/**
+ * Provider component for BetterStack context
+ * Provides type-safe access to plugin-specific overrides
+ *
+ * Only requires override values, not plugin objects - keeps bundle size minimal!
+ *
+ * @example
+ * ```tsx
+ * // Define the type shape (no import of plugin values needed!)
+ * type MyPluginOverrides = {
+ *   todos: TodosPluginOverrides;
+ *   messages: MessagesPluginOverrides;
+ * };
+ *
+ * <BetterStackProvider<MyPluginOverrides>
+ *   overrides={{
+ *     todos: {
+ *       Link: (props) => <NextLink {...props} />,
+ *       navigate: (path) => router.push(path),
+ *     },
+ *     messages: {
+ *       MarkdownRenderer: (props) => <ReactMarkdown {...props} />,
+ *     }
+ *   }}
+ * >
+ *   {children}
+ * </BetterStackProvider>
+ * ```
+ */
+export function BetterStackProvider<
+	TPluginOverrides extends Record<string, any> = Record<string, any>,
+>({
+	children,
+	overrides,
+	basePath,
+}: {
+	children?: ReactNode;
+	overrides: TPluginOverrides;
+	basePath: string;
+}) {
+	const value: BetterStackContextValue<TPluginOverrides> = {
+		overrides,
+		basePath,
+	};
+
+	return (
+		<BetterStackContext.Provider value={value}>
+			{children}
+		</BetterStackContext.Provider>
+	);
+}
+
+/**
+ * Hook to access the entire context
+ * Useful if you need access to multiple plugins or the full context
+ */
+export function useBetterStack<
+	TPluginOverrides extends Record<string, any> = Record<string, any>,
+>() {
+	const context = useContext(
+		BetterStackContext,
+	) as BetterStackContextValue<TPluginOverrides> | null;
+
+	if (!context) {
+		throw new Error(
+			"useBetterStack must be used within BetterStackProvider. " +
+				"Wrap your app with <BetterStackProvider> in your layout file.",
+		);
+	}
+
+	return context;
+}
+
+// Helper type: merge TOverrides with TDefaults, making defaulted properties required
+type OverridesResult<TOverrides, TDefaults> = undefined extends TDefaults
+	? TOverrides
+	: TOverrides & Required<Pick<TDefaults & {}, keyof TDefaults>>;
+
+/**
+ * Hook to access overrides for a specific plugin
+ * This is type-safe and will only expose the overrides defined by that plugin
+ *
+ * When default values are provided, properties with defaults are guaranteed to be non-null.
+ *
+ * @example
+ * ```tsx
+ * // Without defaults - trusts plugin is configured
+ * function TodosList() {
+ *   const { navigate } = usePluginOverrides<TodosPluginOverrides>("todos");
+ *   // navigate is (path: string) => void (required fields are non-nullable)
+ *   navigate("/todos/add");
+ * }
+ *
+ * // With defaults - optional fields with defaults become required
+ * function TodosList() {
+ *   const { localization } = usePluginOverrides<TodosPluginOverrides, Partial<TodosPluginOverrides>>("todos", {
+ *     localization: DEFAULT_LOCALIZATION
+ *   });
+ *   // localization is Localization (guaranteed to exist because we provided a default)
+ *   console.log(localization.SOME_KEY);
+ * }
+ * ```
+ */
+export function usePluginOverrides<
+	TOverrides = any,
+	TDefaults extends Partial<TOverrides> | undefined = undefined,
+>(
+	pluginName: string,
+	defaultValues?: TDefaults,
+): OverridesResult<TOverrides, TDefaults> {
+	const context = useBetterStack();
+
+	const pluginOverrides = context.overrides[pluginName];
+
+	// If defaults are provided, merge them with plugin overrides
+	// This ensures default properties exist even if plugin is partially configured
+	const overrides = defaultValues
+		? { ...defaultValues, ...pluginOverrides }
+		: pluginOverrides;
+
+	return overrides as OverridesResult<TOverrides, TDefaults>;
+}
+
+export function useBasePath() {
+	const context = useBetterStack();
+	if (!context) {
+		throw new Error(
+			"useBasePath must be used within BetterStackProvider. " +
+				"Wrap your app with <BetterStackProvider> in your layout file.",
+		);
+	}
+	return context.basePath;
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./api";