@btst/stack 2.12.2 → 3.0.0-rc.2

package/src/plugins/blog/client/components/shared/post-card.tsx

@@ -6,12 +6,16 @@ import {
 	CardHeader,
 	CardTitle,
 } from "@workspace/ui/components/card";
-import { useBasePath, usePluginOverrides } from "@btst/stack/context";
+import {
+	useBasePath,
+	usePluginOverrides,
+	useStack,
+	useTranslate,
+} from "@btst/stack/context";
 import { formatDate } from "date-fns";
 import type { SerializedPost } from "../../../types";
 import { CalendarIcon } from "lucide-react";
 import type { BlogPluginOverrides } from "../../overrides";
-import { BLOG_LOCALIZATION } from "../../localization";
 import { DefaultLink, DefaultImage } from "./defaults";
 
 // Beautiful gradient color combinations
@@ -216,19 +220,14 @@ function getGradientFromTitle(title: string) {
 }
 
 export function PostCard({ post }: { post: SerializedPost }) {
-	const { Link, Image } = usePluginOverrides<
-		BlogPluginOverrides,
-		Partial<BlogPluginOverrides>
-	>("blog", {
-		Link: DefaultLink,
-		Image: DefaultImage,
-	});
+	const t = useTranslate();
 	const { localization } = usePluginOverrides<
 		BlogPluginOverrides,
 		Partial<BlogPluginOverrides>
-	>("blog", {
-		localization: BLOG_LOCALIZATION,
-	});
+	>("blog", {});
+	const { router } = useStack();
+	const Link = router?.Link ?? DefaultLink;
+	const Image = router?.Image ?? DefaultImage;
 	const basePath = useBasePath();
 	const blogPath = `${basePath}/blog/${post.slug}`;
 	const postDate = formatDate(
@@ -272,7 +271,8 @@ export function PostCard({ post }: { post: SerializedPost }) {
 
 			{!post.published && (
 				<Badge variant="destructive" className="absolute top-2 left-2 text-xs">
-					{localization.BLOG_CARD_DRAFT_BADGE}
+					{localization?.BLOG_CARD_DRAFT_BADGE ??
+						t("blog.card.draftBadge", "Draft")}
 				</Badge>
 			)}
 

package/src/plugins/blog/client/components/shared/post-navigation.tsx

@@ -1,9 +1,8 @@
 "use client";
 
-import { usePluginOverrides, useBasePath } from "@btst/stack/context";
+import { useBasePath, useStack, useTranslate } from "@btst/stack/context";
 import { Button } from "@workspace/ui/components/button";
 import { ChevronLeft, ChevronRight } from "lucide-react";
-import type { BlogPluginOverrides } from "../../overrides";
 import { DefaultLink } from "./defaults";
 import type { SerializedPost } from "../../../types";
 
@@ -16,12 +15,9 @@ export function PostNavigation({
 	previousPost,
 	nextPost,
 }: PostNavigationProps) {
-	const { Link } = usePluginOverrides<
-		BlogPluginOverrides,
-		Partial<BlogPluginOverrides>
-	>("blog", {
-		Link: DefaultLink,
-	});
+	const t = useTranslate();
+	const { router } = useStack();
+	const Link = router?.Link ?? DefaultLink;
 	const basePath = useBasePath();
 	const blogPath = `${basePath}/blog`;
 
@@ -46,7 +42,7 @@ export function PostNavigation({
 										<ChevronLeft className="h-4 w-4 shrink-0" />
 										<div className="flex flex-col items-start min-w-0 flex-1">
 											<span className="text-xs text-muted-foreground">
-												Previous
+												{t("blog.post.previous", "Previous")}
 											</span>
 											<div className="font-semibold line-clamp-2 text-sm leading-tight transition-colors text-start">
 												{previousPost.title}
@@ -72,7 +68,7 @@ export function PostNavigation({
 									<div className="flex items-center gap-2 w-full min-w-0">
 										<div className="flex flex-col items-end min-w-0 flex-1">
 											<span className="text-xs text-muted-foreground">
-												Next
+												{t("blog.post.next", "Next")}
 											</span>
 											<div className="font-semibold line-clamp-2 text-sm leading-tight transition-colors text-start">
 												{nextPost.title}

package/src/plugins/blog/client/components/shared/posts-list.tsx

@@ -1,11 +1,10 @@
-import { usePluginOverrides } from "@btst/stack/context";
+import { usePluginOverrides, useTranslate } from "@btst/stack/context";
 import type { SerializedPost } from "../../../types";
 import { Button } from "@workspace/ui/components/button";
 import { EmptyList } from "./empty-list";
 import { SearchInput } from "./search-input";
 import type { BlogPluginOverrides } from "../../overrides";
 import { PostCard as DefaultPostCard } from "./post-card";
-import { BLOG_LOCALIZATION } from "../../localization";
 
 interface PostsListProps {
 	posts: SerializedPost[];
@@ -20,26 +19,38 @@ export function PostsList({
 	hasMore,
 	isLoadingMore,
 }: PostsListProps) {
-	const { localization } = usePluginOverrides<
-		BlogPluginOverrides,
-		Partial<BlogPluginOverrides>
-	>("blog", {
-		localization: BLOG_LOCALIZATION,
-	});
-	const { PostCard } = usePluginOverrides<BlogPluginOverrides>("blog");
+	const t = useTranslate();
+	const { localization, PostCard } =
+		usePluginOverrides<BlogPluginOverrides>("blog");
 
 	const PostCardComponent = PostCard || DefaultPostCard;
 	if (posts.length === 0) {
-		return <EmptyList message={localization.BLOG_LIST_EMPTY} />;
+		return (
+			<EmptyList
+				message={
+					localization?.BLOG_LIST_EMPTY ??
+					t("blog.list.empty", "There are no posts here yet.")
+				}
+			/>
+		);
 	}
 
 	return (
 		<div className="w-full space-y-6">
 			<div className="flex justify-center pb-6">
 				<SearchInput
-					placeholder={localization.BLOG_LIST_SEARCH_PLACEHOLDER}
-					buttonText={localization.BLOG_LIST_SEARCH_BUTTON}
-					emptyMessage={localization.BLOG_LIST_SEARCH_EMPTY}
+					placeholder={
+						localization?.BLOG_LIST_SEARCH_PLACEHOLDER ??
+						t("blog.list.searchPlaceholder", "Search Blog Posts...")
+					}
+					buttonText={
+						localization?.BLOG_LIST_SEARCH_BUTTON ??
+						t("blog.list.searchButton", "Search Posts")
+					}
+					emptyMessage={
+						localization?.BLOG_LIST_SEARCH_EMPTY ??
+						t("blog.list.searchEmpty", "No blog posts found.")
+					}
 				/>
 			</div>
 			<div className="grid grid-cols-1 gap-6 md:grid-cols-2 lg:grid-cols-3">
@@ -57,8 +68,10 @@ export function PostsList({
 						size="lg"
 					>
 						{isLoadingMore
-							? localization.BLOG_LIST_LOADING_MORE
-							: localization.BLOG_LIST_LOAD_MORE}
+							? (localization?.BLOG_LIST_LOADING_MORE ??
+								t("blog.list.loadingMore", "Loading more..."))
+							: (localization?.BLOG_LIST_LOAD_MORE ??
+								t("blog.list.loadMore", "Load more posts"))}
 					</Button>
 				</div>
 			)}

package/src/plugins/blog/client/components/shared/recent-posts-carousel.tsx

@@ -1,6 +1,11 @@
 "use client";
 
-import { useBasePath, usePluginOverrides } from "@btst/stack/context";
+import {
+	useBasePath,
+	usePluginOverrides,
+	useStack,
+	useTranslate,
+} from "@btst/stack/context";
 import type { BlogPluginOverrides } from "../../overrides";
 import type { SerializedPost } from "../../../types";
 import {
@@ -12,21 +17,21 @@ import {
 } from "@workspace/ui/components/carousel";
 import { PostCard as DefaultPostCard } from "./post-card";
 import { DefaultLink } from "./defaults";
-import { BLOG_LOCALIZATION } from "../../localization";
 
 interface RecentPostsCarouselProps {
 	posts: SerializedPost[];
 }
 
 export function RecentPostsCarousel({ posts }: RecentPostsCarouselProps) {
-	const { PostCard, Link, localization } = usePluginOverrides<
+	const t = useTranslate();
+	const { PostCard, localization } = usePluginOverrides<
 		BlogPluginOverrides,
 		Partial<BlogPluginOverrides>
 	>("blog", {
 		PostCard: DefaultPostCard,
-		Link: DefaultLink,
-		localization: BLOG_LOCALIZATION,
 	});
+	const { router } = useStack();
+	const Link = router?.Link ?? DefaultLink;
 	const PostCardComponent = PostCard || DefaultPostCard;
 	const basePath = useBasePath();
 	return (
@@ -36,13 +41,15 @@ export function RecentPostsCarousel({ posts }: RecentPostsCarouselProps) {
 					<div className="mt-4 py-4 w-full text-start border-t">
 						<div className="mt-4 flex items-center justify-between">
 							<h2 className="text-xl font-semibold">
-								{localization.BLOG_POST_KEEP_READING}
+								{localization?.BLOG_POST_KEEP_READING ??
+									t("blog.post.keepReading", "Keep Reading")}
 							</h2>
 							<Link
 								href={`${basePath}/blog`}
 								className="text-sm text-muted-foreground hover:text-foreground transition-colors"
 							>
-								{localization.BLOG_POST_VIEW_ALL}
+								{localization?.BLOG_POST_VIEW_ALL ??
+									t("blog.post.viewAll", "View all")}
 							</Link>
 						</div>
 					</div>

package/src/plugins/blog/client/components/shared/search-input.tsx

@@ -5,8 +5,8 @@ import { usePostSearch } from "../../hooks/blog-hooks";
 import { stripHtml, stripMarkdown } from "../../../utils";
 import { HighlightText } from "./highlight-text";
 import { SearchModal, type SearchResult } from "./search-modal";
-import type { BlogPluginOverrides } from "../../overrides";
-import { useBasePath, usePluginOverrides } from "@btst/stack/context";
+import { useBasePath, useStack } from "@btst/stack/context";
+import { useListState, type ListStateSchema } from "@btst/stack/client";
 
 // Simplified blog post search result interface
 interface BlogPostSearchResult extends SearchResult {
@@ -87,6 +87,12 @@ const renderBlogResult = (
 	);
 };
 
+// URL-synced search state: `?q=...` while typing (history: replace), clean URL
+// when the query is empty (the default is omitted from the URL).
+const SEARCH_LIST_STATE_SCHEMA = {
+	q: { type: "string", default: "", history: "replace" },
+} as const satisfies ListStateSchema;
+
 export function SearchInput({
 	className,
 	triggerClassName,
@@ -94,9 +100,13 @@ export function SearchInput({
 	buttonText,
 	emptyMessage,
 }: SearchInputProps) {
-	const { navigate } = usePluginOverrides<BlogPluginOverrides>("blog");
+	const { router } = useStack();
+	const navigate = router?.navigate;
 	const basePath = useBasePath();
-	const [currentQuery, setCurrentQuery] = React.useState("");
+	const [{ q: currentQuery }, setListState] = useListState(
+		"blog-posts",
+		SEARCH_LIST_STATE_SCHEMA,
+	);
 
 	const { data: searchResults = [], isLoading } = usePostSearch({
 		query: currentQuery,
@@ -114,17 +124,17 @@ export function SearchInput({
 			authorName: "",
 			processedContent: stripMarkdown(stripHtml(post.content || "")),
 			processedExcerpt: stripMarkdown(stripHtml(post.excerpt || "")),
-			onClick: () => navigate(`${basePath}/blog/${post.slug}`),
+			onClick: () => void navigate?.(`${basePath}/blog/${post.slug}`),
 		}));
 	}, [searchResults, navigate, basePath]);
 
-	// Search function that updates our query state
+	// Search function that updates the URL-synced query state
 	const handleSearch = React.useCallback(
 		(query: string): BlogPostSearchResult[] => {
-			setCurrentQuery(query);
+			setListState({ q: query });
 			return []; // Return empty since we use external async results
 		},
-		[],
+		[setListState],
 	);
 
 	return (
@@ -132,6 +142,7 @@ export function SearchInput({
 			placeholder={placeholder}
 			buttonText={buttonText}
 			emptyMessage={emptyMessage}
+			initialQuery={currentQuery}
 			searchFn={handleSearch}
 			renderResult={renderBlogResult}
 			results={formattedResults}

package/src/plugins/blog/client/components/shared/search-modal.tsx

@@ -2,6 +2,7 @@
 
 import { SearchIcon } from "lucide-react";
 import * as React from "react";
+import { useTranslate } from "@btst/stack/context";
 import { useDebounce } from "../../hooks/use-debounce";
 
 import {
@@ -31,12 +32,17 @@ export interface SearchModalProps<T = SearchResult> {
 	groupTitle?: string;
 	className?: string;
 	triggerClassName?: string;
+	/**
+	 * Query the input is seeded with when the dialog opens (e.g. an
+	 * externally persisted `?q=` value), so opening the modal never clears it.
+	 */
+	initialQuery?: string;
 }
 
 export function SearchModal<T extends SearchResult>({
-	placeholder = "Type to search...",
-	emptyMessage = "No results found.",
-	buttonText = "Search",
+	placeholder,
+	emptyMessage,
+	buttonText,
 	keyboardShortcut = "⌘K",
 	searchFn,
 	renderResult,
@@ -44,11 +50,39 @@ export function SearchModal<T extends SearchResult>({
 	isLoading = false,
 	className,
 	triggerClassName,
+	initialQuery = "",
 }: SearchModalProps<T>) {
+	const t = useTranslate();
+	const resolvedPlaceholder =
+		placeholder ?? t("blog.search.placeholder", "Type to search...");
+	const resolvedEmptyMessage =
+		emptyMessage ?? t("blog.search.empty", "No results found.");
+	const resolvedButtonText = buttonText ?? t("blog.search.button", "Search");
 	const [open, setOpen] = React.useState(false);
-	const [query, setQuery] = React.useState("");
+	const [query, setQuery] = React.useState(initialQuery);
 	const [results, setResults] = React.useState<T[]>([]);
 
+	// Tracks the last query passed to searchFn so externally persisted state
+	// (e.g. a `?q=` URL param) is not cleared by the seed value on open.
+	const lastSentQueryRef = React.useRef(initialQuery);
+	// Latest seed value without retriggering the open handler.
+	const initialQueryRef = React.useRef(initialQuery);
+	initialQueryRef.current = initialQuery;
+
+	// Seed the input in the same event that opens the dialog, so the first
+	// open render (and its effects) already sees the persisted query and never
+	// clears it back through searchFn.
+	const openRef = React.useRef(open);
+	openRef.current = open;
+	const handleOpenChange = React.useCallback((nextOpen: boolean) => {
+		if (nextOpen && !openRef.current) {
+			const seed = initialQueryRef.current;
+			setQuery(seed);
+			lastSentQueryRef.current = seed;
+		}
+		setOpen(nextOpen);
+	}, []);
+
 	// Only debounce if not using external results
 	const shouldDebounce = externalResults === undefined;
 	const debouncedQuery = useDebounce(query, shouldDebounce ? 300 : 0);
@@ -63,35 +97,47 @@ export function SearchModal<T extends SearchResult>({
 			if (e.key === cleanShortcut && (e.metaKey || e.ctrlKey)) {
 				e.preventDefault();
 
-				setOpen((open) => !open);
+				handleOpenChange(!openRef.current);
 			}
 		};
 
 		document.addEventListener("keydown", down);
 		return () => document.removeEventListener("keydown", down);
-	}, [keyboardShortcut]);
+	}, [keyboardShortcut, handleOpenChange]);
 
 	React.useEffect(() => {
 		if (!open) {
-			setQuery("");
 			setResults([]);
-			return;
 		}
 	}, [open]);
 
+	// Notify the parent of query changes. Deliberately NOT keyed on
+	// `externalResults`: searchFn may update URL-synced state, and re-invoking
+	// it whenever results change identity can restart an in-flight router
+	// navigation on every render (infinite loop on React Router/Next.js).
+	const hasExternalResults = externalResults !== undefined;
 	React.useEffect(() => {
 		if (!open) return;
 
-		// Always call searchFn to notify parent component of the search query
-		const searchResults = searchFn(debouncedQuery);
-
-		// If external results are provided, use them; otherwise use searchFn results
-		if (externalResults !== undefined) {
-			setResults(externalResults);
-		} else {
-			setResults(searchResults);
+		if (hasExternalResults) {
+			// External mode: only notify once the debounce settled on a value the
+			// parent hasn't seen, so opening the modal never overwrites the
+			// persisted query with the transient empty/seed value.
+			if (debouncedQuery !== query) return;
+			if (debouncedQuery === lastSentQueryRef.current) return;
+			lastSentQueryRef.current = debouncedQuery;
+			searchFn(debouncedQuery);
+			return;
 		}
-	}, [debouncedQuery, open, searchFn, externalResults]);
+
+		setResults(searchFn(debouncedQuery));
+	}, [debouncedQuery, query, open, searchFn, hasExternalResults]);
+
+	// Sync externally-provided (async) results into the list.
+	React.useEffect(() => {
+		if (!open || externalResults === undefined) return;
+		setResults(externalResults);
+	}, [open, externalResults]);
 
 	// Base button classes for better readability
 	const buttonClasses = [
@@ -108,7 +154,9 @@ export function SearchModal<T extends SearchResult>({
 
 	// Determine what to show based on state
 	const showEmpty = debouncedQuery && !isLoading && results.length === 0;
-	const currentEmptyMessage = isLoading ? "Searching..." : emptyMessage;
+	const currentEmptyMessage = isLoading
+		? t("blog.search.searching", "Searching...")
+		: resolvedEmptyMessage;
 
 	return (
 		<>
@@ -116,7 +164,7 @@ export function SearchModal<T extends SearchResult>({
 				data-testid="search-button"
 				type="button"
 				className={buttonClasses}
-				onClick={() => setOpen(true)}
+				onClick={() => handleOpenChange(true)}
 			>
 				<span className="flex grow items-center">
 					<SearchIcon
@@ -125,7 +173,7 @@ export function SearchModal<T extends SearchResult>({
 						aria-hidden="true"
 					/>
 					<span className="font-normal text-muted-foreground">
-						{buttonText}
+						{resolvedButtonText}
 					</span>
 				</span>
 				{keyboardShortcut && (
@@ -137,12 +185,12 @@ export function SearchModal<T extends SearchResult>({
 			<CommandDialog
 				data-testid="search-modal"
 				open={open}
-				onOpenChange={setOpen}
+				onOpenChange={handleOpenChange}
 				className={className}
 			>
 				<CommandInput
 					data-testid="search-input"
-					placeholder={placeholder}
+					placeholder={resolvedPlaceholder}
 					value={query}
 					onValueChange={setQuery}
 				/>