@btst/stack 2.12.2 → 3.0.0-rc.1

package/src/plugins/comments/client/components/pages/resource-comments-page.internal.tsx

@@ -16,36 +16,33 @@ import {
 } from "@workspace/ui/components/avatar";
 import { CheckCircle, ShieldOff, Trash2 } from "lucide-react";
 import { formatDistanceToNow } from "date-fns";
-import { toast } from "sonner";
 import {
-	COMMENTS_LOCALIZATION,
-	type CommentsLocalization,
-} from "../../localization";
+	CanAccess,
+	useNotify,
+	useStack,
+	useTranslate,
+} from "@btst/stack/context";
+import type { CommentsLocalization } from "../../localization";
 import { getInitials } from "../../utils";
 
 interface ResourceCommentsPageProps {
 	resourceId: string;
 	resourceType: string;
-	apiBaseURL: string;
-	apiBasePath: string;
-	headers?: HeadersInit;
-	currentUserId?: string;
-	loginHref?: string;
-	localization?: CommentsLocalization;
+	localization?: Partial<CommentsLocalization>;
 }
 
 export function ResourceCommentsPage({
 	resourceId,
 	resourceType,
-	apiBaseURL,
-	apiBasePath,
-	headers,
-	currentUserId,
-	loginHref,
-	localization: localizationProp,
+	localization,
 }: ResourceCommentsPageProps) {
-	const loc = { ...COMMENTS_LOCALIZATION, ...localizationProp };
-	const config = { apiBaseURL, apiBasePath, headers };
+	const t = useTranslate();
+	const notify = useNotify();
+	const { api } = useStack();
+	const config = {
+		apiBaseURL: api?.baseURL ?? "",
+		apiBasePath: api?.basePath ?? "",
+	};
 
 	const {
 		comments: pendingComments,
@@ -63,31 +60,52 @@ export function ResourceCommentsPage({
 	const handleApprove = async (id: string) => {
 		try {
 			await updateStatus.mutateAsync({ id, status: "approved" });
-			toast.success(loc.COMMENTS_RESOURCE_TOAST_APPROVED);
+			notify.success(
+				localization?.COMMENTS_RESOURCE_TOAST_APPROVED ??
+					t("comments.resource.toastApproved", "Comment approved"),
+			);
 			refetch();
 		} catch {
-			toast.error(loc.COMMENTS_RESOURCE_TOAST_APPROVE_ERROR);
+			notify.error(
+				localization?.COMMENTS_RESOURCE_TOAST_APPROVE_ERROR ??
+					t("comments.resource.toastApproveError", "Failed to approve"),
+			);
 		}
 	};
 
 	const handleSpam = async (id: string) => {
 		try {
 			await updateStatus.mutateAsync({ id, status: "spam" });
-			toast.success(loc.COMMENTS_RESOURCE_TOAST_SPAM);
+			notify.success(
+				localization?.COMMENTS_RESOURCE_TOAST_SPAM ??
+					t("comments.resource.toastSpam", "Marked as spam"),
+			);
 			refetch();
 		} catch {
-			toast.error(loc.COMMENTS_RESOURCE_TOAST_SPAM_ERROR);
+			notify.error(
+				localization?.COMMENTS_RESOURCE_TOAST_SPAM_ERROR ??
+					t("comments.resource.toastSpamError", "Failed to update"),
+			);
 		}
 	};
 
 	const handleDelete = async (id: string) => {
-		if (!window.confirm(loc.COMMENTS_RESOURCE_DELETE_CONFIRM)) return;
+		const confirmMessage =
+			localization?.COMMENTS_RESOURCE_DELETE_CONFIRM ??
+			t("comments.resource.deleteConfirm", "Delete this comment?");
+		if (!window.confirm(confirmMessage)) return;
 		try {
 			await deleteMutation.mutateAsync(id);
-			toast.success(loc.COMMENTS_RESOURCE_TOAST_DELETED);
+			notify.success(
+				localization?.COMMENTS_RESOURCE_TOAST_DELETED ??
+					t("comments.resource.toastDeleted", "Comment deleted"),
+			);
 			refetch();
 		} catch {
-			toast.error(loc.COMMENTS_RESOURCE_TOAST_DELETE_ERROR);
+			notify.error(
+				localization?.COMMENTS_RESOURCE_TOAST_DELETE_ERROR ??
+					t("comments.resource.toastDeleteError", "Failed to delete"),
+			);
 		}
 	};
 
@@ -97,7 +115,10 @@ export function ResourceCommentsPage({
 			data-testid="resource-comments-page"
 		>
 			<div>
-				<h1 className="text-2xl font-bold">{loc.COMMENTS_RESOURCE_TITLE}</h1>
+				<h1 className="text-2xl font-bold">
+					{localization?.COMMENTS_RESOURCE_TITLE ??
+						t("comments.resource.title", "Comments")}
+				</h1>
 				<p className="text-muted-foreground text-sm mt-1">
 					{resourceType}/{resourceId}
 				</p>
@@ -106,7 +127,8 @@ export function ResourceCommentsPage({
 			{pendingTotal > 0 && (
 				<div className="space-y-3">
 					<h2 className="text-base font-semibold flex items-center gap-2">
-						{loc.COMMENTS_RESOURCE_PENDING_SECTION}
+						{localization?.COMMENTS_RESOURCE_PENDING_SECTION ??
+							t("comments.resource.pendingSection", "Pending Review")}
 						<Badge variant="secondary">{pendingTotal}</Badge>
 					</h2>
 					<div className="divide-y divide-border rounded-lg border">
@@ -114,7 +136,7 @@ export function ResourceCommentsPage({
 							<PendingCommentRow
 								key={comment.id}
 								comment={comment}
-								loc={loc}
+								localization={localization}
 								onApprove={() => handleApprove(comment.id)}
 								onSpam={() => handleSpam(comment.id)}
 								onDelete={() => handleDelete(comment.id)}
@@ -128,17 +150,13 @@ export function ResourceCommentsPage({
 
 			<div>
 				<h2 className="text-base font-semibold mb-4">
-					{loc.COMMENTS_RESOURCE_THREAD_SECTION}
+					{localization?.COMMENTS_RESOURCE_THREAD_SECTION ??
+						t("comments.resource.threadSection", "Thread")}
 				</h2>
 				<CommentThread
 					resourceId={resourceId}
 					resourceType={resourceType}
-					apiBaseURL={apiBaseURL}
-					apiBasePath={apiBasePath}
-					headers={headers}
-					currentUserId={currentUserId}
-					loginHref={loginHref}
-					localization={loc}
+					localization={localization}
 				/>
 			</div>
 		</div>
@@ -147,7 +165,7 @@ export function ResourceCommentsPage({
 
 function PendingCommentRow({
 	comment,
-	loc,
+	localization,
 	onApprove,
 	onSpam,
 	onDelete,
@@ -155,13 +173,14 @@ function PendingCommentRow({
 	isDeleting,
 }: {
 	comment: SerializedComment;
-	loc: CommentsLocalization;
+	localization?: Partial<CommentsLocalization>;
 	onApprove: () => void;
 	onSpam: () => void;
 	onDelete: () => void;
 	isUpdating: boolean;
 	isDeleting: boolean;
 }) {
+	const t = useTranslate();
 	return (
 		<div className="flex gap-3 p-4" data-testid="pending-comment-row">
 			<Avatar className="h-8 w-8 shrink-0 mt-0.5">
@@ -187,37 +206,58 @@ function PendingCommentRow({
 					{comment.body}
 				</p>
 				<div className="flex gap-1 mt-2">
-					<Button
-						size="sm"
-						variant="outline"
-						className="h-7 text-xs text-green-600 border-green-200 hover:bg-green-50"
-						onClick={onApprove}
-						disabled={isUpdating}
-						data-testid="approve-button"
+					<CanAccess
+						resource="comments:comment"
+						action="moderate"
+						params={{ id: comment.id }}
 					>
-						<CheckCircle className="h-3.5 w-3.5 mr-1" />
-						{loc.COMMENTS_RESOURCE_ACTION_APPROVE}
-					</Button>
-					<Button
-						size="sm"
-						variant="outline"
-						className="h-7 text-xs text-orange-500 border-orange-200 hover:bg-orange-50"
-						onClick={onSpam}
-						disabled={isUpdating}
+						<Button
+							size="sm"
+							variant="outline"
+							className="h-7 text-xs text-green-600 border-green-200 hover:bg-green-50"
+							onClick={onApprove}
+							disabled={isUpdating}
+							data-testid="approve-button"
+						>
+							<CheckCircle className="h-3.5 w-3.5 mr-1" />
+							{localization?.COMMENTS_RESOURCE_ACTION_APPROVE ??
+								t("comments.resource.actionApprove", "Approve")}
+						</Button>
+					</CanAccess>
+					<CanAccess
+						resource="comments:comment"
+						action="moderate"
+						params={{ id: comment.id }}
 					>
-						<ShieldOff className="h-3.5 w-3.5 mr-1" />
-						{loc.COMMENTS_RESOURCE_ACTION_SPAM}
-					</Button>
-					<Button
-						size="sm"
-						variant="outline"
-						className="h-7 text-xs text-destructive border-destructive/30 hover:bg-destructive/5"
-						onClick={onDelete}
-						disabled={isDeleting}
+						<Button
+							size="sm"
+							variant="outline"
+							className="h-7 text-xs text-orange-500 border-orange-200 hover:bg-orange-50"
+							onClick={onSpam}
+							disabled={isUpdating}
+						>
+							<ShieldOff className="h-3.5 w-3.5 mr-1" />
+							{localization?.COMMENTS_RESOURCE_ACTION_SPAM ??
+								t("comments.resource.actionSpam", "Spam")}
+						</Button>
+					</CanAccess>
+					<CanAccess
+						resource="comments:comment"
+						action="delete"
+						params={{ id: comment.id }}
 					>
-						<Trash2 className="h-3.5 w-3.5 mr-1" />
-						{loc.COMMENTS_RESOURCE_ACTION_DELETE}
-					</Button>
+						<Button
+							size="sm"
+							variant="outline"
+							className="h-7 text-xs text-destructive border-destructive/30 hover:bg-destructive/5"
+							onClick={onDelete}
+							disabled={isDeleting}
+						>
+							<Trash2 className="h-3.5 w-3.5 mr-1" />
+							{localization?.COMMENTS_RESOURCE_ACTION_DELETE ??
+								t("comments.resource.actionDelete", "Delete")}
+						</Button>
+					</CanAccess>
 				</div>
 			</div>
 		</div>

package/src/plugins/comments/client/components/pages/resource-comments-page.tsx

@@ -4,10 +4,8 @@ import { lazy } from "react";
 import { ComposedRoute } from "@btst/stack/client/components";
 import { usePluginOverrides } from "@btst/stack/context";
 import type { CommentsPluginOverrides } from "../../overrides";
-import { COMMENTS_LOCALIZATION } from "../../localization";
 import { useRouteLifecycle } from "@workspace/ui/hooks/use-route-lifecycle";
 import { PageWrapper } from "../shared/page-wrapper";
-import { useResolvedCurrentUserId } from "../../utils";
 
 const ResourceCommentsPageInternal = lazy(() =>
 	import("./resource-comments-page.internal").then((m) => ({
@@ -57,8 +55,6 @@ function ResourceCommentsPageWrapper({
 	resourceType: string;
 }) {
 	const overrides = usePluginOverrides<CommentsPluginOverrides>("comments");
-	const loc = { ...COMMENTS_LOCALIZATION, ...overrides.localization };
-	const resolvedUserId = useResolvedCurrentUserId(overrides.currentUserId);
 
 	useRouteLifecycle({
 		routeName: "resourceComments",
@@ -68,29 +64,13 @@ function ResourceCommentsPageWrapper({
 			isSSR: typeof window === "undefined",
 		},
 		overrides,
-		beforeRenderHook: (o, context) => {
-			if (o.onBeforeResourceCommentsRendered) {
-				return o.onBeforeResourceCommentsRendered(
-					resourceType,
-					resourceId,
-					context,
-				);
-			}
-			return true;
-		},
 	});
-
 	return (
 		<PageWrapper>
 			<ResourceCommentsPageInternal
 				resourceId={resourceId}
 				resourceType={resourceType}
-				apiBaseURL={overrides.apiBaseURL}
-				apiBasePath={overrides.apiBasePath}
-				headers={overrides.headers as HeadersInit | undefined}
-				currentUserId={resolvedUserId}
-				loginHref={overrides.loginHref}
-				localization={loc}
+				localization={overrides.localization}
 			/>
 		</PageWrapper>
 	);

package/src/plugins/comments/client/components/shared/pagination.tsx

@@ -1,8 +1,7 @@
 "use client";
 
-import { usePluginOverrides } from "@btst/stack/context";
+import { usePluginOverrides, useTranslate } from "@btst/stack/context";
 import type { CommentsPluginOverrides } from "../../overrides";
-import { COMMENTS_LOCALIZATION } from "../../localization";
 import { PaginationControls } from "@workspace/ui/components/pagination-controls";
 
 interface PaginationProps {
@@ -22,9 +21,9 @@ export function Pagination({
 	limit,
 	offset,
 }: PaginationProps) {
-	const { localization: customLocalization } =
+	const t = useTranslate();
+	const { localization } =
 		usePluginOverrides<CommentsPluginOverrides>("comments");
-	const localization = { ...COMMENTS_LOCALIZATION, ...customLocalization };
 
 	return (
 		<PaginationControls
@@ -35,9 +34,18 @@ export function Pagination({
 			limit={limit}
 			offset={offset}
 			labels={{
-				previous: localization.COMMENTS_MODERATION_PAGINATION_PREVIOUS,
-				next: localization.COMMENTS_MODERATION_PAGINATION_NEXT,
-				showing: localization.COMMENTS_MODERATION_PAGINATION_SHOWING,
+				previous:
+					localization?.COMMENTS_MODERATION_PAGINATION_PREVIOUS ??
+					t("comments.moderation.paginationPrevious", "Previous"),
+				next:
+					localization?.COMMENTS_MODERATION_PAGINATION_NEXT ??
+					t("comments.moderation.paginationNext", "Next"),
+				showing:
+					localization?.COMMENTS_MODERATION_PAGINATION_SHOWING ??
+					t(
+						"comments.moderation.paginationShowing",
+						"Showing {from}–{to} of {total}",
+					),
 			}}
 		/>
 	);

package/src/plugins/comments/client/hooks/use-comments.tsx

@@ -8,11 +8,20 @@ import {
 	useSuspenseQuery,
 	type InfiniteData,
 } from "@tanstack/react-query";
-import { createApiClient } from "@btst/stack/plugins/client";
-import { createCommentsQueryKeys } from "../../query-keys";
+import {
+	createApiClient,
+	runResourceMutation,
+} from "@btst/stack/plugins/client";
+import { commentsResources, createCommentsQueryKeys } from "../../query-keys";
 import type { CommentsApiRouter } from "../../api";
 import type { SerializedComment, CommentListResult } from "../../types";
-import { toError } from "../utils";
+
+// HTTP mappings for all comment mutations live in the resource declaration;
+// the hooks below own the cache behavior (optimistic updates, invalidation)
+// because they take an explicit client config — required by the embeddable
+// `CommentThread` — and therefore cannot use the overrides-bound
+// `createResource` mutation hooks.
+const commentMutations = commentsResources.comments.mutations;
 
 interface CommentsClientConfig {
 	apiBaseURL: string;
@@ -318,27 +327,23 @@ export function usePostComment(
 		!!params.infiniteKey && (parentId ?? null) === null;
 
 	return useMutation({
-		mutationFn: async (input: {
+		mutationFn: (input: {
 			body: string;
 			parentId?: string | null;
 			limit?: number;
 			offset?: number;
-		}) => {
-			const response = await client("@post/comments", {
-				method: "POST",
-				body: {
+		}) =>
+			runResourceMutation(
+				client,
+				commentMutations.create,
+				{
 					resourceId: params.resourceId,
 					resourceType: params.resourceType,
 					parentId: input.parentId ?? null,
 					body: input.body,
 				},
-				headers: config.headers,
-			});
-
-			const data = (response as { data?: unknown }).data;
-			if (!data) throw toError((response as { error?: unknown }).error);
-			return data as SerializedComment;
-		},
+				config.headers,
+			) as Promise<SerializedComment>,
 		onMutate: async (input) => {
 			const listKey = getListKey(input.parentId, input.offset, input.limit);
 			await queryClient.cancelQueries({ queryKey: listKey });
@@ -505,17 +510,13 @@ export function useUpdateComment(config: CommentsClientConfig) {
 	const queries = createCommentsQueryKeys(client, config.headers);
 
 	return useMutation({
-		mutationFn: async (input: { id: string; body: string }) => {
-			const response = await client("@patch/comments/:id", {
-				method: "PATCH",
-				params: { id: input.id },
-				body: { body: input.body },
-				headers: config.headers,
-			});
-			const data = (response as { data?: unknown }).data;
-			if (!data) throw toError((response as { error?: unknown }).error);
-			return data as SerializedComment;
-		},
+		mutationFn: (input: { id: string; body: string }) =>
+			runResourceMutation(
+				client,
+				commentMutations.update,
+				input,
+				config.headers,
+			) as Promise<SerializedComment>,
 		onSettled: () => {
 			queryClient.invalidateQueries({
 				queryKey: queries.comments.list._def,
@@ -535,17 +536,13 @@ export function useApproveComment(config: CommentsClientConfig) {
 	const queries = createCommentsQueryKeys(client, config.headers);
 
 	return useMutation({
-		mutationFn: async (id: string) => {
-			const response = await client("@patch/comments/:id/status", {
-				method: "PATCH",
-				params: { id },
-				body: { status: "approved" },
-				headers: config.headers,
-			});
-			const data = (response as { data?: unknown }).data;
-			if (!data) throw toError((response as { error?: unknown }).error);
-			return data as SerializedComment;
-		},
+		mutationFn: (id: string) =>
+			runResourceMutation(
+				client,
+				commentMutations.updateStatus,
+				{ id, status: "approved" },
+				config.headers,
+			) as Promise<SerializedComment>,
 		onSettled: () => {
 			queryClient.invalidateQueries({
 				queryKey: queries.comments.list._def,
@@ -568,20 +565,16 @@ export function useUpdateCommentStatus(config: CommentsClientConfig) {
 	const queries = createCommentsQueryKeys(client, config.headers);
 
 	return useMutation({
-		mutationFn: async (input: {
+		mutationFn: (input: {
 			id: string;
 			status: "pending" | "approved" | "spam";
-		}) => {
-			const response = await client("@patch/comments/:id/status", {
-				method: "PATCH",
-				params: { id: input.id },
-				body: { status: input.status },
-				headers: config.headers,
-			});
-			const data = (response as { data?: unknown }).data;
-			if (!data) throw toError((response as { error?: unknown }).error);
-			return data as SerializedComment;
-		},
+		}) =>
+			runResourceMutation(
+				client,
+				commentMutations.updateStatus,
+				input,
+				config.headers,
+			) as Promise<SerializedComment>,
 		onSettled: () => {
 			queryClient.invalidateQueries({
 				queryKey: queries.comments.list._def,
@@ -604,16 +597,13 @@ export function useDeleteComment(config: CommentsClientConfig) {
 	const queries = createCommentsQueryKeys(client, config.headers);
 
 	return useMutation({
-		mutationFn: async (id: string) => {
-			const response = await client("@delete/comments/:id", {
-				method: "DELETE",
-				params: { id },
-				headers: config.headers,
-			});
-			const data = (response as { data?: unknown }).data;
-			if (!data) throw toError((response as { error?: unknown }).error);
-			return data as { success: boolean };
-		},
+		mutationFn: (id: string) =>
+			runResourceMutation(
+				client,
+				commentMutations.delete,
+				id,
+				config.headers,
+			) as Promise<{ success: boolean }>,
 		onSettled: () => {
 			queryClient.invalidateQueries({
 				queryKey: queries.comments.list._def,
@@ -698,17 +688,13 @@ export function useToggleLike(
 	}
 
 	return useMutation({
-		mutationFn: async (input: { commentId: string; authorId: string }) => {
-			const response = await client("@post/comments/:id/like", {
-				method: "POST",
-				params: { id: input.commentId },
-				body: { authorId: input.authorId },
-				headers: config.headers,
-			});
-			const data = (response as { data?: unknown }).data;
-			if (!data) throw toError((response as { error?: unknown }).error);
-			return data as { likes: number; isLiked: boolean };
-		},
+		mutationFn: (input: { commentId: string; authorId: string }) =>
+			runResourceMutation(
+				client,
+				commentMutations.like,
+				input,
+				config.headers,
+			) as Promise<{ likes: number; isLiked: boolean }>,
 		onMutate: async (input) => {
 			await queryClient.cancelQueries({ queryKey: listKey });
 

package/src/plugins/comments/client/overrides.ts

@@ -17,7 +17,7 @@ import type { CommentsLocalization } from "./localization";
 /**
  * Overridable configuration and hooks for the Comments plugin.
  *
- * Provide these in the layout wrapping your pages via `PluginOverridesProvider`.
+ * Provide these in the `comments` block of `StackProvider.overrides`.
  */
 export interface CommentsPluginOverrides {
 	/**
@@ -25,49 +25,12 @@ export interface CommentsPluginOverrides {
 	 * Defaults to English when not provided.
 	 */
 	localization?: Partial<CommentsLocalization>;
-	/**
-	 * Base URL for API calls (e.g., "https://example.com")
-	 */
-	apiBaseURL: string;
-
-	/**
-	 * Path where the API is mounted (e.g., "/api/data")
-	 */
-	apiBasePath: string;
-
-	/**
-	 * Optional headers for authenticated API calls (e.g., forwarding cookies)
-	 */
-	headers?: Record<string, string>;
-
 	/**
 	 * Whether to show the "Powered by BTST" attribution on plugin pages.
 	 * Defaults to true.
 	 */
 	showAttribution?: boolean;
 
-	/**
-	 * The ID of the currently authenticated user.
-	 *
-	 * Used by the User Comments page and the per-resource comments admin view to
-	 * scope the comment list to the current user and to enable posting.
-	 * Can be a static string or an async function (useful when the user ID must
-	 * be resolved from a session cookie at render time).
-	 *
-	 * When absent both pages show a "Please log in" prompt.
-	 */
-	currentUserId?:
-		| string
-		| (() => string | undefined | Promise<string | undefined>);
-
-	/**
-	 * URL to redirect unauthenticated users to when they try to post a comment.
-	 *
-	 * Forwarded to every embedded `CommentThread` (including the one on the
-	 * per-resource admin comments view). When absent no login link is shown.
-	 */
-	loginHref?: string;
-
 	/**
 	 * Default number of top-level comments to load per page in `CommentThread`.
 	 * Can be overridden per-instance via the `pageSize` prop.
@@ -119,35 +82,6 @@ export interface CommentsPluginOverrides {
 	 */
 	resourceLinks?: Record<string, (id: string) => string>;
 
-	// ============ Access Control Hooks ============
-
-	/**
-	 * Called before the moderation dashboard page is rendered.
-	 * Return false to block rendering (e.g., redirect to login or show 403).
-	 * @param context - Route context
-	 */
-	onBeforeModerationPageRendered?: (context: RouteContext) => boolean;
-
-	/**
-	 * Called before the per-resource comments page is rendered.
-	 * Return false to block rendering (e.g., for authorization).
-	 * @param resourceType - The type of resource (e.g., "blog-post")
-	 * @param resourceId - The ID of the resource
-	 * @param context - Route context
-	 */
-	onBeforeResourceCommentsRendered?: (
-		resourceType: string,
-		resourceId: string,
-		context: RouteContext,
-	) => boolean;
-
-	/**
-	 * Called before the User Comments page is rendered.
-	 * Throw to block rendering (e.g., when the user is not authenticated).
-	 * @param context - Route context
-	 */
-	onBeforeUserCommentsPageRendered?: (context: RouteContext) => boolean | void;
-
 	// ============ Lifecycle Hooks ============
 
 	/**