@btst/stack 2.12.1 → 3.0.0-rc.1

package/src/context/auth.tsx

@@ -0,0 +1,255 @@
+"use client";
+import {
+	createContext,
+	useCallback,
+	useContext,
+	useEffect,
+	useRef,
+	useState,
+	type ReactNode,
+} from "react";
+import type {
+	CanParams,
+	StackAuthProvider,
+	StackIdentity,
+} from "../shared/auth-types";
+
+interface AuthContextValue {
+	provider: StackAuthProvider;
+	identity: StackIdentity | null;
+	/** True until the initial `getIdentity()` call settles */
+	isPending: boolean;
+	/** Re-run `getIdentity()` (e.g. after login/logout) */
+	refetch: () => Promise<void>;
+}
+
+/**
+ * Default is `null` = no auth provider configured. Every consumer treats that
+ * as "auth disabled": identity is `null`, all permission checks pass, and
+ * `<CanAccess>` renders its children — preserving pre-auth behavior exactly.
+ */
+const AuthContext = createContext<AuthContextValue | null>(null);
+
+/**
+ * Internal boundary rendered by `StackProvider` when an `auth` provider is
+ * configured. Resolves `getIdentity()` once on the client (effects don't run
+ * during SSR, so server renders see `isPending: true`) and shares the result
+ * with all `useIdentity()` / `useCan()` / `<CanAccess>` consumers.
+ */
+export function StackAuthBoundary({
+	provider,
+	children,
+}: {
+	provider: StackAuthProvider;
+	children?: ReactNode;
+}) {
+	const [state, setState] = useState<{
+		identity: StackIdentity | null;
+		isPending: boolean;
+	}>({ identity: null, isPending: true });
+
+	const refetch = useCallback(async () => {
+		try {
+			const identity = await provider.getIdentity();
+			setState({ identity: identity ?? null, isPending: false });
+		} catch (error) {
+			console.error("[btst/auth] getIdentity() failed:", error);
+			setState({ identity: null, isPending: false });
+		}
+	}, [provider]);
+
+	useEffect(() => {
+		void refetch();
+	}, [refetch]);
+
+	return (
+		<AuthContext.Provider
+			value={{
+				provider,
+				identity: state.identity,
+				isPending: state.isPending,
+				refetch,
+			}}
+		>
+			{children}
+		</AuthContext.Provider>
+	);
+}
+
+/** @internal Access the raw auth context (or `null` when no provider is set). */
+export function useAuthContext(): AuthContextValue | null {
+	return useContext(AuthContext);
+}
+
+/**
+ * Returns the current user's identity as resolved by the auth provider
+ * configured on `StackProvider`.
+ *
+ * Without an auth provider, returns `{ identity: null, isPending: false }`.
+ *
+ * @example
+ * ```tsx
+ * const { identity, isPending } = useIdentity();
+ * if (identity) return <span>Hello {identity.name}</span>;
+ * ```
+ */
+export function useIdentity(): {
+	identity: StackIdentity | null;
+	isPending: boolean;
+	refetch: () => Promise<void>;
+} {
+	const auth = useContext(AuthContext);
+
+	if (!auth) {
+		return { identity: null, isPending: false, refetch: async () => {} };
+	}
+
+	return {
+		identity: auth.identity,
+		isPending: auth.isPending,
+		refetch: auth.refetch,
+	};
+}
+
+type CanState = { can: boolean; isPending: boolean };
+
+/**
+ * A resolved `can()` result together with the inputs it was computed for.
+ * `useCan` only trusts it while those inputs are still current, so a change
+ * in identity (login/logout/user switch) or check parameters immediately
+ * reads as pending instead of momentarily returning the previous user's
+ * permission.
+ */
+type ResolvedCan = {
+	can: boolean;
+	forIdentity: StackIdentity | null;
+	forKey: string;
+};
+
+/**
+ * Checks whether the current user can perform `action` on `resource` using
+ * the auth provider's `can()` function.
+ *
+ * Resolves to `{ can: true, isPending: false }` immediately when no auth
+ * provider is configured or the provider has no `can()` function — permission
+ * checks are opt-in and non-breaking.
+ *
+ * While the identity or the `can()` result is still resolving, returns
+ * `{ can: false, isPending: true }` so callers can avoid flashing
+ * permission-gated UI.
+ *
+ * @example
+ * ```tsx
+ * const { can, isPending } = useCan({ resource: "blog:post", action: "delete" });
+ * if (!isPending && can) return <DeletePostButton />;
+ * ```
+ */
+export function useCan(params: CanParams): CanState {
+	const auth = useContext(AuthContext);
+	const canFn = auth?.provider.can;
+	const identity = auth?.identity ?? null;
+	const identityPending = auth?.isPending ?? false;
+
+	const { resource, action, params: extraParams } = params;
+	// Serialized only for change detection: plain-object literals must not
+	// retrigger the effect on every render. The original object (via ref) is
+	// what gets passed to can(), so non-JSON-safe values survive intact.
+	const extraParamsKey = extraParams ? JSON.stringify(extraParams) : "";
+	const extraParamsRef = useRef(extraParams);
+	extraParamsRef.current = extraParams;
+
+	const checkKey = `${resource}\u0000${action}\u0000${extraParamsKey}`;
+
+	const [resolved, setResolved] = useState<ResolvedCan | null>(null);
+
+	useEffect(() => {
+		if (!canFn || identityPending) return;
+
+		let cancelled = false;
+
+		void (async () => {
+			try {
+				const currentParams = extraParamsRef.current;
+				const allowed = await canFn({
+					resource,
+					action,
+					...(currentParams ? { params: currentParams } : {}),
+					identity,
+				});
+				if (!cancelled) {
+					setResolved({
+						can: allowed,
+						forIdentity: identity,
+						forKey: checkKey,
+					});
+				}
+			} catch (error) {
+				console.error("[btst/auth] can() failed:", error);
+				if (!cancelled) {
+					setResolved({ can: false, forIdentity: identity, forKey: checkKey });
+				}
+			}
+		})();
+
+		return () => {
+			cancelled = true;
+		};
+	}, [canFn, identity, identityPending, resource, action, checkKey]);
+
+	// No provider or no can() function: always allowed, never pending.
+	if (!auth || !canFn) {
+		return { can: true, isPending: false };
+	}
+
+	if (identityPending) {
+		return { can: false, isPending: true };
+	}
+
+	// Only trust a result computed for the current identity and inputs;
+	// anything else (including right after an identity change) is pending.
+	if (
+		!resolved ||
+		resolved.forIdentity !== identity ||
+		resolved.forKey !== checkKey
+	) {
+		return { can: false, isPending: true };
+	}
+
+	return { can: resolved.can, isPending: false };
+}
+
+/**
+ * Element-level permission gate (Refine's `<CanAccess>` pattern).
+ *
+ * - Without an auth provider configured, always renders `children`.
+ * - While the check is pending, renders `loading` (default `null`) to avoid
+ *   flashing gated UI.
+ * - Renders `children` when `can()` allows, `fallback` (default `null`)
+ *   otherwise.
+ *
+ * @example
+ * ```tsx
+ * <CanAccess resource="blog:post" action="delete" fallback={null}>
+ *   <DeletePostButton />
+ * </CanAccess>
+ * ```
+ */
+export function CanAccess({
+	resource,
+	action,
+	params,
+	fallback = null,
+	loading = null,
+	children,
+}: CanParams & {
+	/** Rendered when access is denied (default `null`) */
+	fallback?: ReactNode;
+	/** Rendered while the permission check is pending (default `null`) */
+	loading?: ReactNode;
+	children?: ReactNode;
+}) {
+	const { can, isPending } = useCan({ resource, action, params });
+
+	if (isPending) return <>{loading}</>;
+	return <>{can ? children : fallback}</>;
+}

package/src/context/i18n.tsx

@@ -0,0 +1,57 @@
+"use client";
+import { createContext, useCallback, useContext, useMemo } from "react";
+import { interpolate } from "../shared/interpolate";
+import type { StackI18nProvider } from "../shared/i18n-types";
+
+const I18nContext = createContext<StackI18nProvider | null>(null);
+
+export function StackI18nBoundary({
+	i18n,
+	children,
+}: {
+	i18n?: StackI18nProvider;
+	children?: React.ReactNode;
+}) {
+	return (
+		<I18nContext.Provider value={i18n ?? null}>{children}</I18nContext.Provider>
+	);
+}
+
+export type TranslateFn = (
+	key: string,
+	defaultValue: string,
+	params?: Record<string, unknown>,
+) => string;
+
+/**
+ * Returns a `t(key, defaultValue, params?)` function for translatable UI strings.
+ *
+ * Without an `i18n` provider on `StackProvider`, returns the default English
+ * string with `{{param}}` interpolation — identical to hardcoded strings today.
+ *
+ * @example
+ * ```tsx
+ * const t = useTranslate();
+ * return <button>{t("blog.posts.create", "Create Post")}</button>;
+ * ```
+ */
+export function useTranslate(): TranslateFn {
+	const i18n = useContext(I18nContext);
+
+	const fallback = useCallback<TranslateFn>(
+		(key, defaultValue, params) => interpolate(defaultValue, params),
+		[],
+	);
+
+	return useMemo(() => {
+		if (!i18n) return fallback;
+
+		return (key, defaultValue, params) =>
+			i18n.translate(key, defaultValue, params);
+	}, [i18n, fallback]);
+}
+
+/** @internal Access the raw i18n provider (or `null` when none is set). */
+export function useI18nContext(): StackI18nProvider | null {
+	return useContext(I18nContext);
+}

package/src/context/index.ts

@@ -1 +1,16 @@
 export * from "./provider";
+export * from "./router";
+export { CanAccess, useCan, useIdentity } from "./auth";
+export { useNotify, defaultNotifyProvider } from "./notify";
+export { useTranslate, type TranslateFn } from "./i18n";
+export type {
+	CanParams,
+	StackAuthProvider,
+	StackIdentity,
+	StackServerAuthProvider,
+} from "../shared/auth-types";
+export type {
+	StackNotifyProvider,
+	NotifyOptions,
+} from "../shared/notify-types";
+export type { StackI18nProvider } from "../shared/i18n-types";

package/src/context/notify.tsx

@@ -0,0 +1,66 @@
+"use client";
+import { createContext, useContext, useMemo } from "react";
+import { toast } from "sonner";
+import type {
+	NotifyOptions,
+	StackNotifyProvider,
+} from "../shared/notify-types";
+
+const NotifyContext = createContext<Required<StackNotifyProvider> | null>(null);
+
+/** Sonner-backed defaults used when no custom `notify` prop is configured. */
+export const defaultNotifyProvider: Required<StackNotifyProvider> = {
+	success: (message: string, options?: NotifyOptions) => {
+		toast.success(message, options);
+	},
+	error: (message: string, options?: NotifyOptions) => {
+		toast.error(message, options);
+	},
+	info: (message: string, options?: NotifyOptions) => {
+		toast.info(message, options);
+	},
+	warning: (message: string, options?: NotifyOptions) => {
+		toast.warning(message, options);
+	},
+};
+
+function mergeNotifyProvider(
+	custom: StackNotifyProvider | undefined,
+): Required<StackNotifyProvider> {
+	return {
+		success: custom?.success ?? defaultNotifyProvider.success,
+		error: custom?.error ?? defaultNotifyProvider.error,
+		info: custom?.info ?? defaultNotifyProvider.info,
+		warning: custom?.warning ?? defaultNotifyProvider.warning,
+	};
+}
+
+export function StackNotifyBoundary({
+	notify,
+	children,
+}: {
+	notify?: StackNotifyProvider;
+	children?: React.ReactNode;
+}) {
+	const value = useMemo(() => mergeNotifyProvider(notify), [notify]);
+
+	return (
+		<NotifyContext.Provider value={value}>{children}</NotifyContext.Provider>
+	);
+}
+
+/**
+ * Returns notification methods routed through the `notify` provider on
+ * `StackProvider`, falling back to sonner toasts when no override is set.
+ *
+ * @example
+ * ```tsx
+ * const notify = useNotify();
+ * notify.success("Post saved");
+ * notify.error("Failed to delete", { description: "Try again later" });
+ * ```
+ */
+export function useNotify(): Required<StackNotifyProvider> {
+	const notify = useContext(NotifyContext);
+	return notify ?? defaultNotifyProvider;
+}

package/src/context/provider.tsx

@@ -1,5 +1,12 @@
 "use client";
 import { createContext, useContext, type ReactNode } from "react";
+import type { StackAuthProvider } from "../shared/auth-types";
+import type { StackI18nProvider } from "../shared/i18n-types";
+import type { StackNotifyProvider } from "../shared/notify-types";
+import { StackAuthBoundary } from "./auth";
+import { StackI18nBoundary } from "./i18n";
+import { StackNotifyBoundary } from "./notify";
+import type { StackApiConfig, StackRouter, StackRouterConfig } from "./router";
 
 /**
  * Context value that provides plugin-specific overrides
@@ -14,10 +21,78 @@ interface StackContextValue<TPluginOverrides extends Record<string, any>> {
 	 * The base path where the client router is mounted.
 	 */
 	basePath: string;
+	/**
+	 * Resolved top-level router (static preset fields merged with the
+	 * preset's `useRouter` hook result).
+	 */
+	router?: StackRouter;
+	/**
+	 * Top-level API config applied to all plugins.
+	 */
+	api?: StackApiConfig;
+	/** Top-level auth provider used by identity-aware components. */
+	auth?: StackAuthProvider;
 }
 
 const StackContext = createContext<StackContextValue<any> | null>(null);
 
+/**
+ * The `overrides` prop shape for `StackProvider`.
+ * Plugin blocks are optional; fields inside each block retain the plugin's
+ * declared requirements.
+ */
+export type StackProviderOverrides<
+	TPluginOverrides extends Record<string, any>,
+> = Partial<TPluginOverrides>;
+
+/** Removes keys whose value is `undefined` so they don't clobber lower layers in spreads. */
+function stripUndefined<T extends Record<string, any>>(obj: T): Partial<T> {
+	const result: Record<string, any> = {};
+	for (const key of Object.keys(obj)) {
+		if (obj[key] !== undefined) {
+			result[key] = obj[key];
+		}
+	}
+	return result as Partial<T>;
+}
+
+function resolveStaticRouter(
+	router: StackRouterConfig | undefined,
+): StackRouter | undefined {
+	if (!router) return undefined;
+	const { useRouter: _useRouter, ...staticFields } = router;
+	return stripUndefined(staticFields);
+}
+
+/**
+ * Internal component that evaluates the router preset's `useRouter` hook.
+ * Rendered only when the hook exists, so the hook itself is always called
+ * unconditionally within this component.
+ */
+function RouterBridge({
+	useRouter,
+	staticRouter,
+	value,
+	children,
+}: {
+	useRouter: () => StackRouter;
+	staticRouter: StackRouter | undefined;
+	value: Omit<StackContextValue<any>, "router">;
+	children?: ReactNode;
+}) {
+	const hookRouter = useRouter();
+	const router: StackRouter = {
+		...staticRouter,
+		...stripUndefined(hookRouter),
+	};
+
+	return (
+		<StackContext.Provider value={{ ...value, router }}>
+			{children}
+		</StackContext.Provider>
+	);
+}
+
 /**
  * Provider component for BTST context
  * Provides type-safe access to plugin-specific overrides
@@ -28,16 +103,13 @@ const StackContext = createContext<StackContextValue<any> | null>(null);
  * ```tsx
  * // Define the type shape (no import of plugin values needed!)
  * type MyPluginOverrides = {
- *   todos: TodosPluginOverrides;
  *   messages: MessagesPluginOverrides;
  * };
  *
  * <StackProvider<MyPluginOverrides>
+ *   router={frameworkRouter}
+ *   api={{ baseURL, basePath: "/api/data" }}
  *   overrides={{
- *     todos: {
- *       Link: (props) => <NextLink {...props} />,
- *       navigate: (path) => router.push(path),
- *     },
  *     messages: {
  *       MarkdownRenderer: (props) => <ReactMarkdown {...props} />,
  *     }
@@ -46,6 +118,25 @@ const StackContext = createContext<StackContextValue<any> | null>(null);
  *   {children}
  * </StackProvider>
  * ```
+ *
+ * Framework router and API wiring live at the top level. Per-plugin overrides
+ * carry only genuinely plugin-specific values:
+ *
+ * @example
+ * ```tsx
+ * import { nextRouter } from "@btst/stack/next";
+ *
+ * <StackProvider<MyPluginOverrides>
+ *   basePath="/pages"
+ *   router={nextRouter()}
+ *   api={{ baseURL, basePath: "/api/data" }}
+ *   overrides={{
+ *     blog: { uploadImage },
+ *   }}
+ * >
+ *   {children}
+ * </StackProvider>
+ * ```
  */
 export function StackProvider<
 	TPluginOverrides extends Record<string, any> = Record<string, any>,
@@ -53,18 +144,67 @@ export function StackProvider<
 	children,
 	overrides,
 	basePath,
+	router,
+	api,
+	auth,
+	notify,
+	i18n,
 }: {
 	children?: ReactNode;
-	overrides: TPluginOverrides;
+	overrides?: StackProviderOverrides<TPluginOverrides>;
 	basePath: string;
+	router?: StackRouterConfig;
+	api?: StackApiConfig;
+	/**
+	 * Optional auth provider. When set, `useIdentity()` / `useCan()` and
+	 * `<CanAccess>` resolve identity and permissions through it. When omitted,
+	 * behavior is identical to before: identity is `null` and all permission
+	 * checks pass.
+	 */
+	auth?: StackAuthProvider;
+	/**
+	 * Optional notification provider. When omitted, sonner toasts are used via
+	 * `useNotify()`.
+	 */
+	notify?: StackNotifyProvider;
+	/**
+	 * Optional i18n provider. When omitted, `useTranslate()` returns English
+	 * defaults with `{{param}}` interpolation.
+	 */
+	i18n?: StackI18nProvider;
 }) {
-	const value: StackContextValue<TPluginOverrides> = {
-		overrides,
+	const staticRouter = resolveStaticRouter(router);
+	const value: Omit<StackContextValue<any>, "router"> = {
+		overrides: overrides ?? {},
 		basePath,
+		api,
+		auth,
 	};
 
+	const content = auth ? (
+		<StackAuthBoundary provider={auth}>{children}</StackAuthBoundary>
+	) : (
+		children
+	);
+
+	const stackTree = router?.useRouter ? (
+		<RouterBridge
+			useRouter={router.useRouter}
+			staticRouter={staticRouter}
+			value={value}
+		>
+			{content}
+		</RouterBridge>
+	) : (
+		<StackContext.Provider value={{ ...value, router: staticRouter }}>
+			{content}
+		</StackContext.Provider>
+	);
+
 	return (
-		<StackContext.Provider value={value}>{children}</StackContext.Provider>
+		<StackNotifyBoundary notify={notify}>
+			<StackI18nBoundary i18n={i18n}>{stackTree}</StackI18nBoundary>
+		</StackNotifyBoundary>
 	);
 }
 
@@ -97,6 +237,19 @@ export function useStack<
 	return context;
 }
 
+/**
+ * Like `useStack`, but returns `null` instead of throwing when rendered
+ * outside a `StackProvider`.
+ *
+ * @internal Used by core components (e.g. route gating) that must not change
+ * behavior for consumers rendering outside the provider.
+ */
+export function useStackOrNull<
+	TPluginOverrides extends Record<string, any> = Record<string, any>,
+>() {
+	return useContext(StackContext) as StackContextValue<TPluginOverrides> | null;
+}
+
 // Helper type: merge TOverrides with TDefaults, making defaulted properties required
 type OverridesResult<TOverrides, TDefaults> = undefined extends TDefaults
 	? TOverrides
@@ -111,15 +264,14 @@ type OverridesResult<TOverrides, TDefaults> = undefined extends TDefaults
  * @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");
+ * function MessagesList() {
+ *   const { MarkdownRenderer } = usePluginOverrides<MessagesPluginOverrides>("messages");
+ *   return <MarkdownRenderer>{message.body}</MarkdownRenderer>;
  * }
  *
  * // With defaults - optional fields with defaults become required
- * function TodosList() {
- *   const { localization } = usePluginOverrides<TodosPluginOverrides, Partial<TodosPluginOverrides>>("todos", {
+ * function MessagesList() {
+ *   const { localization } = usePluginOverrides<MessagesPluginOverrides, Partial<MessagesPluginOverrides>>("messages", {
  *     localization: DEFAULT_LOCALIZATION
  *   });
  *   // localization is Localization (guaranteed to exist because we provided a default)
@@ -134,15 +286,11 @@ export function usePluginOverrides<
 	pluginName: string,
 	defaultValues?: TDefaults,
 ): OverridesResult<TOverrides, TDefaults> {
-	const context = useStack();
-
-	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: allOverrides } = useStack();
+	const pluginOverrides = allOverrides[pluginName];
 	const overrides = defaultValues
 		? { ...defaultValues, ...pluginOverrides }
-		: pluginOverrides;
+		: (pluginOverrides ?? {});
 
 	return overrides as OverridesResult<TOverrides, TDefaults>;
 }