@farming-labs/theme 0.2.105 → 0.2.106

package/dist/ai-search-dialog.mjs

@@ -4,6 +4,7 @@ import { emitClientAnalyticsEvent } from "./client-analytics.mjs";
 import { renderAIResponseMarkdown } from "./ai-markdown.mjs";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { createPortal } from "react-dom";
+import { useRouter } from "fumadocs-core/framework";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/ai-search-dialog.tsx
@@ -948,6 +949,7 @@ function AIChat({ api, requestMode, requestHeaders, requestStream = true, messag
 	});
 }
 function DocsSearchDialog({ open, onOpenChange, api = "/api/docs", requestMode, requestHeaders, requestStream, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics = false, feedbackEnabled = true }) {
+	const router = useRouter();
 	const [tab, setTab] = useState("search");
 	const [searchQuery, setSearchQuery] = useState("");
 	const [searchResults, setSearchResults] = useState([]);
@@ -1064,7 +1066,7 @@ function DocsSearchDialog({ open, onOpenChange, api = "/api/docs", requestMode,
 					queryLength: searchQuery.length
 				}
 			});
-			window.location.href = searchResults[activeIndex].url;
+			router.push(searchResults[activeIndex].url);
 		}
 	};
 	if (!open) return null;
@@ -1166,7 +1168,7 @@ function DocsSearchDialog({ open, onOpenChange, api = "/api/docs", requestMode,
 									queryLength: searchQuery.length
 								}
 							});
-							window.location.href = result.url;
+							router.push(result.url);
 						},
 						onMouseEnter: () => setActiveIndex(i),
 						className: "fd-ai-result",

package/dist/browser.d.mts

@@ -16,13 +16,20 @@ declare global {
 interface BrowserRootProviderProps extends FumadocsProviderProps {
   /** Path rendered by the server, used to keep hydration deterministic. */
   initialPathname?: string;
+  /** Framework adapter navigation that preserves the current document shell. */
+  navigation?: BrowserNavigationAdapter;
+}
+interface BrowserNavigationAdapter {
+  push(url: string): void | Promise<void>;
+  refresh(): void | Promise<void>;
 }
 /** Framework-neutral provider for server-rendered React documentation adapters. */
 declare function BrowserRootProvider({
   children,
   search,
   initialPathname,
+  navigation,
   ...props
 }: BrowserRootProviderProps): react_jsx_runtime0.JSX.Element;
 //#endregion
-export { BrowserDocsLayout, BrowserDocsLayoutProps, BrowserRootProvider, BrowserRootProviderProps };
+export { BrowserDocsLayout, BrowserDocsLayoutProps, BrowserNavigationAdapter, BrowserRootProvider, BrowserRootProviderProps };

package/dist/browser.mjs

@@ -1,7 +1,7 @@
 "use client";
 
 import { TanstackDocsLayout } from "./tanstack-layout.mjs";
-import { useMemo, useSyncExternalStore } from "react";
+import { createContext, useCallback, useContext, useMemo, useSyncExternalStore } from "react";
 import { FrameworkProvider } from "fumadocs-core/framework";
 import { jsx } from "react/jsx-runtime";
 import { RootProvider } from "fumadocs-ui/provider/base";
@@ -14,6 +14,15 @@ function BrowserDocsLayout(props) {
 		browserRuntime: true
 	});
 }
+const defaultBrowserNavigation = {
+	push(url) {
+		window.location.assign(url);
+	},
+	refresh() {
+		window.location.reload();
+	}
+};
+const BrowserNavigationContext = createContext(defaultBrowserNavigation);
 function patchHistoryEvents() {
 	if (typeof window === "undefined" || window.__fdBrowserHistoryPatched) return;
 	for (const method of ["pushState", "replaceState"]) {
@@ -40,39 +49,71 @@ function getBrowserPathname() {
 	return typeof window === "undefined" ? "/" : window.location.pathname;
 }
 function useBrowserRouter() {
+	const navigation = useContext(BrowserNavigationContext);
 	return useMemo(() => ({
 		push(url) {
-			window.location.assign(url);
+			return navigation.push(url);
 		},
 		refresh() {
-			window.location.reload();
+			return navigation.refresh();
 		}
-	}), []);
+	}), [navigation]);
 }
 function useBrowserParams() {
 	return useMemo(() => ({}), []);
 }
-function BrowserLink({ prefetch: _prefetch, ...props }) {
-	return /* @__PURE__ */ jsx("a", { ...props });
+function BrowserLink({ prefetch: _prefetch, href, target, download, onClick, ...props }) {
+	const navigation = useContext(BrowserNavigationContext);
+	const handleClick = useCallback((event) => {
+		onClick?.(event);
+		if (event.defaultPrevented || event.button !== 0) return;
+		if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+		if (!href || download !== void 0 && download !== false || target && target !== "_self") return;
+		let url;
+		try {
+			url = new URL(href, window.location.href);
+		} catch {
+			return;
+		}
+		if (url.origin !== window.location.origin) return;
+		event.preventDefault();
+		navigation.push(`${url.pathname}${url.search}${url.hash}`);
+	}, [
+		download,
+		href,
+		navigation,
+		onClick,
+		target
+	]);
+	return /* @__PURE__ */ jsx("a", {
+		...props,
+		href,
+		target,
+		download,
+		onClick: handleClick
+	});
 }
 /** Framework-neutral provider for server-rendered React documentation adapters. */
-function BrowserRootProvider({ children, search, initialPathname = "/", ...props }) {
+function BrowserRootProvider({ children, search, initialPathname = "/", navigation = defaultBrowserNavigation, ...props }) {
 	const useBrowserPathname = () => useSyncExternalStore(subscribeToLocation, getBrowserPathname, () => initialPathname);
-	return /* @__PURE__ */ jsx(FrameworkProvider, {
-		Link: BrowserLink,
-		usePathname: useBrowserPathname,
-		useParams: useBrowserParams,
-		useRouter: useBrowserRouter,
-		children: /* @__PURE__ */ jsx(RootProvider, {
-			search: {
-				...search,
-				options: {
-					api: "/api/docs",
-					...search?.options
-				}
-			},
-			...props,
-			children
+	return /* @__PURE__ */ jsx(BrowserNavigationContext.Provider, {
+		value: navigation,
+		children: /* @__PURE__ */ jsx(FrameworkProvider, {
+			Link: BrowserLink,
+			usePathname: useBrowserPathname,
+			useParams: useBrowserParams,
+			useRouter: useBrowserRouter,
+			children: /* @__PURE__ */ jsx(RootProvider, {
+				search: {
+					...search,
+					options: {
+						api: "/api/docs",
+						...search?.options
+					}
+				},
+				...props,
+				children
+			})
 		})
 	});
 }

package/dist/docs-command-search.mjs

@@ -5,6 +5,7 @@ import { useWindowSearchParams } from "./client-location.mjs";
 import { resolveClientLocale, withLangInUrl } from "./i18n.mjs";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { createPortal } from "react-dom";
+import { useRouter } from "fumadocs-core/framework";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/docs-command-search.tsx
@@ -242,6 +243,7 @@ function HistoryIcon() {
 * so each theme provides its own visual variant.
 */
 function DocsCommandSearch({ api = "/api/docs", locale, analytics = false }) {
+	const router = useRouter();
 	const [open, setOpen] = useState(false);
 	const [query, setQuery] = useState("");
 	const [debouncedQuery, setDebouncedQuery] = useState("");
@@ -476,11 +478,12 @@ function DocsCommandSearch({ api = "/api/docs", locale, analytics = false }) {
 		saveRecent(item);
 		setOpen(false);
 		if (item.url.startsWith("http")) window.open(item.url, "_blank", "noopener");
-		else window.location.href = item.url;
+		else router.push(item.url);
 	}, [
 		activeLocale,
 		analytics,
 		query.length,
+		router,
 		saveRecent
 	]);
 	const displayItems = useMemo(() => {

package/dist/docs-layout.mjs

@@ -670,7 +670,7 @@ function LayoutStyle({ layout }) {
 	}
 	if (rootVars.length === 0 && desktopRootVars.length === 0) return null;
 	const parts = [];
-	if (rootVars.length > 0) parts.push(`:root {\n  ${rootVars.join("\n  ")}\n}`);
+	if (rootVars.length > 0) parts.push(`:root,\n#nd-docs-layout {\n  ${rootVars.join("\n  ")}\n}`);
 	if (desktopRootVars.length > 0) {
 		const inner = [`:root {\n    ${desktopRootVars.join("\n    ")}\n  }`];
 		if (desktopGridVars.length > 0) inner.push(`[style*="fd-sidebar-col"] {\n    ${desktopGridVars.join("\n    ")}\n  }`);

package/dist/docs-page-client.mjs

@@ -163,7 +163,7 @@ function isDocsNavigationPath(pathname, entry, publicPath) {
 	if (publicPath === "") return pathname.startsWith("/");
 	return pathname === publicPath || pathname.startsWith(`${publicPath}/`);
 }
-function installDocsPathNavigationGuard(entry, publicPath) {
+function installDocsPathNavigationGuard(entry, publicPath, navigate) {
 	if (publicPath === `/${entry.replace(/^\/+|\/+$/g, "") || "docs"}`) return void 0;
 	function onClick(event) {
 		if (event.defaultPrevented) return;
@@ -184,7 +184,7 @@ function installDocsPathNavigationGuard(entry, publicPath) {
 			const nextHref = `${nextPath}${url.search}${url.hash}`;
 			if (nextHref === `${window.location.pathname}${window.location.search}${window.location.hash}`) return;
 			event.preventDefault();
-			window.location.assign(nextHref);
+			navigate(nextHref);
 		} catch {}
 	}
 	document.addEventListener("click", onClick, true);
@@ -256,6 +256,7 @@ function findThreadlineTocActionsContainer() {
 	return toc.parentElement ?? toc;
 }
 function DocsPageClient({ tocEnabled, showLlmsInHeader = false, tocStyle = "default", breadcrumbEnabled = true, changelogBasePath, entry = "docs", publicPath, locale, copyMarkdown = false, copyMarkdownFormat, copyMarkdownIncludeTitle, copyMarkdownLabel, copyMarkdownCopiedLabel, openDocs = false, openDocsProviders, openDocsTarget, openDocsPrompt, connectMcp, installSkills, pageActionsPosition = "below-title", pageActionsAlignment = "left", githubUrl, contentDir, githubBranch = "main", githubDirectory, editOnGithubUrl, lastModifiedMap, lastModified: lastModifiedProp, readingTimeMap, readingTime: readingTimeProp, readingTimeFormat = "long", previousPage, nextPage, structuredDataMap, structuredData: structuredDataProp, readingTimeEnabled = false, lastUpdatedEnabled = true, lastUpdatedLabel = "Last updated", lastUpdatedPosition = "footer", llmsTxtEnabled = false, generatedTitleMap, descriptionMap, description, descriptionInBody = false, feedbackEnabled = false, feedbackQuestion, feedbackPlaceholder, feedbackRequireComment, feedbackPositiveLabel, feedbackNegativeLabel, feedbackSubmitLabel, feedbackSuccessMessage, feedbackErrorMessage, feedbackOnFeedback, analytics = false, children }) {
+	const router = useRouter();
 	const fdTocStyle = tocStyle === "directional" ? "clerk" : void 0;
 	const [toc, setToc] = useState([]);
 	const [titlePortalHost, setTitlePortalHost] = useState(null);
@@ -297,8 +298,12 @@ function DocsPageClient({ tocEnabled, showLlmsInHeader = false, tocStyle = "defa
 		normalizedPath
 	]);
 	useEffect(() => {
-		return installDocsPathNavigationGuard(entry, resolvedPublicPath);
-	}, [entry, resolvedPublicPath]);
+		return installDocsPathNavigationGuard(entry, resolvedPublicPath, (url) => router.push(url));
+	}, [
+		entry,
+		resolvedPublicPath,
+		router
+	]);
 	const resolvedReadingTime = !isChangelogRoute ? readingTimeProp !== void 0 ? readingTimeProp : readingTimeEnabled ? matchedReadingTime : void 0 : void 0;
 	const effectiveTocEnabled = isChangelogRoute ? false : tocEnabled;
 	const effectiveBreadcrumbEnabled = isChangelogRoute ? false : breadcrumbEnabled;
@@ -315,7 +320,11 @@ function DocsPageClient({ tocEnabled, showLlmsInHeader = false, tocStyle = "defa
 			})));
 		});
 		return () => cancelAnimationFrame(timer);
-	}, [effectiveTocEnabled, pathname]);
+	}, [
+		children,
+		effectiveTocEnabled,
+		pathname
+	]);
 	useEffect(() => {
 		const timer = requestAnimationFrame(() => {
 			const root = document.body;
@@ -505,14 +514,19 @@ function DocsPageClient({ tocEnabled, showLlmsInHeader = false, tocStyle = "defa
 			setTitlePortalHost(null);
 			return;
 		}
-		const title = document.getElementById("nd-page")?.querySelector("h1");
-		if (!title) {
+		const container = document.getElementById("nd-page");
+		if (!container) {
 			setTitlePortalHost(null);
 			return;
 		}
 		const host = document.createElement("div");
 		host.className = "fd-title-decorations-host";
 		const placeHost = () => {
+			const title = container.querySelector("h1");
+			if (!title) {
+				host.remove();
+				return;
+			}
 			let anchor = title;
 			if (descriptionInBody) {
 				let sibling = title.nextElementSibling;
@@ -527,10 +541,12 @@ function DocsPageClient({ tocEnabled, showLlmsInHeader = false, tocStyle = "defa
 			}
 			if (anchor.nextElementSibling !== host) anchor.insertAdjacentElement("afterend", host);
 		};
-		title.insertAdjacentElement("afterend", host);
 		placeHost();
 		const observer = new MutationObserver(placeHost);
-		observer.observe(title.parentElement ?? title, { childList: true });
+		observer.observe(container, {
+			childList: true,
+			subtree: true
+		});
 		const animationFrame = window.requestAnimationFrame(placeHost);
 		setTitlePortalHost(host);
 		return () => {
@@ -540,6 +556,7 @@ function DocsPageClient({ tocEnabled, showLlmsInHeader = false, tocStyle = "defa
 			setTitlePortalHost(null);
 		};
 	}, [
+		children,
 		descriptionInBody,
 		needsTitleDecorationsPortal,
 		pathname
@@ -549,7 +566,11 @@ function DocsPageClient({ tocEnabled, showLlmsInHeader = false, tocStyle = "defa
 		belowTitle: belowTitleBlock
 	}) : null;
 	const titleDecorationsPortal = titleDecorations && titlePortalHost ? createPortal(titleDecorations, titlePortalHost, "title-decorations") : null;
-	const titleDecorationsFallback = titleDecorations && !titlePortalHost ? titleDecorations : null;
+	const titleDecorationsFallback = titleDecorations && !titlePortalHost ? /* @__PURE__ */ jsx("div", {
+		className: "fd-title-decorations-fallback",
+		hidden: true,
+		children: titleDecorations
+	}) : null;
 	const generatedPageHeader = pageTitle ? /* @__PURE__ */ jsxs("div", {
 		className: "fd-generated-page-header not-prose",
 		children: [/* @__PURE__ */ jsx("h1", {
@@ -610,7 +631,7 @@ function DocsPageClient({ tocEnabled, showLlmsInHeader = false, tocStyle = "defa
 				style: fdTocStyle
 			},
 			breadcrumb: { enabled: false },
-			footer: { enabled: !isChangelogRoute },
+			footer: { enabled: !isChangelogRoute && !showPageNavigation },
 			children: [
 				effectiveBreadcrumbEnabled && /* @__PURE__ */ jsx(PathBreadcrumb, {
 					pathname,
@@ -643,6 +664,7 @@ function DocsPageClient({ tocEnabled, showLlmsInHeader = false, tocStyle = "defa
 				}, "actions-above-title"),
 				!showReadingTimeAboveTitle && !showReadingTimeBelowTitle ? readingTimeBlock : null,
 				/* @__PURE__ */ jsxs(DocsBody, {
+					className: "fd-page-body",
 					style: {
 						display: "flex",
 						flexDirection: "column"
@@ -650,6 +672,7 @@ function DocsPageClient({ tocEnabled, showLlmsInHeader = false, tocStyle = "defa
 					children: [
 						generatedPageHeader,
 						/* @__PURE__ */ jsx("div", {
+							className: "fd-docs-content",
 							style: { flex: 1 },
 							children: renderedChildren
 						}, "content"),

package/dist/tanstack-layout.mjs

@@ -42,6 +42,22 @@ function resolveTreeIcons(tree, registry) {
 		children: tree.children.map(mapNode)
 	};
 }
+function applyFlatSidebarLayout(tree, flat) {
+	if (!flat) return tree;
+	function mapNode(node) {
+		if (node.type === "page") return node;
+		return {
+			...node,
+			collapsible: false,
+			defaultOpen: true,
+			children: node.children.map(mapNode)
+		};
+	}
+	return {
+		...tree,
+		children: tree.children.map(mapNode)
+	};
+}
 function localizeTreeUrls(tree, locale) {
 	function mapNode(node) {
 		if (node.type === "page") return {
@@ -173,7 +189,7 @@ function LayoutStyle({ layout }) {
 	}
 	if (rootVars.length === 0 && desktopRootVars.length === 0) return null;
 	const parts = [];
-	if (rootVars.length > 0) parts.push(`:root {\n  ${rootVars.join("\n  ")}\n}`);
+	if (rootVars.length > 0) parts.push(`:root,\n#nd-docs-layout {\n  ${rootVars.join("\n  ")}\n}`);
 	if (desktopRootVars.length > 0) {
 		const inner = [`:root {\n    ${desktopRootVars.join("\n    ")}\n  }`];
 		if (desktopGridVars.length > 0) inner.push(`[style*="fd-sidebar-col"] {\n    ${desktopGridVars.join("\n    ")}\n  }`);
@@ -262,7 +278,10 @@ function TanstackDocsLayout({ config, tree, browserRuntime = false, locale, desc
 	const llmsTxtEnabled = resolveEnabledByDefault(config.llmsTxt);
 	const feedbackConfig = resolveFeedbackConfig(config.feedback);
 	const staticExport = !!config.staticExport;
-	const frameworkContainerProps = browserRuntime ? { "data-fd-framework": "" } : void 0;
+	const frameworkContainerProps = browserRuntime ? {
+		"data-fd-framework": "",
+		"data-fd-browser-adapter": ""
+	} : void 0;
 	const openDocsConfig = pageActions?.openDocs && typeof pageActions.openDocs === "object" ? pageActions.openDocs : void 0;
 	const openDocsProviders = resolveOpenDocsProviders(openDocsConfig?.providers, {
 		target: openDocsConfig?.target,
@@ -284,13 +303,13 @@ function TanstackDocsLayout({ config, tree, browserRuntime = false, locale, desc
 		aiDefaultModelId = rawModelConfig.defaultModel ?? rawModelConfig.models?.[0]?.id ?? aiDefaultModelId;
 	}
 	const i18n = config.i18n;
-	const resolvedTree = resolveTreeIcons(locale ? localizeTreeUrls(applySidebarFolderIndexBehavior(tree, {
+	const resolvedTree = resolveTreeIcons(applyFlatSidebarLayout(locale ? localizeTreeUrls(applySidebarFolderIndexBehavior(tree, {
 		sidebar: config.sidebar,
 		defaultBehavior: config.theme?.name === "shadcn" ? "hidden" : "link"
 	}), locale) : applySidebarFolderIndexBehavior(tree, {
 		sidebar: config.sidebar,
 		defaultBehavior: config.theme?.name === "shadcn" ? "hidden" : "link"
-	}), config.icons);
+	}), !!sidebarFlat), config.icons);
 	const finalSidebarProps = { ...sidebarProps };
 	const sidebarFooter = sidebarProps.footer;
 	if (locale && i18n?.locales && i18n.defaultLocale) finalSidebarProps.footer = /* @__PURE__ */ jsxs("div", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/theme",
-  "version": "0.2.105",
+  "version": "0.2.106",
   "description": "Theme package for @farming-labs/docs — layout, provider, MDX components, and styles",
   "keywords": [
     "docs",
@@ -161,7 +161,7 @@
     "tsdown": "^0.20.3",
     "typescript": "^5.9.3",
     "vitest": "^4.1.8",
-    "@farming-labs/docs": "0.2.105"
+    "@farming-labs/docs": "0.2.106"
   },
   "peerDependencies": {
     "@farming-labs/docs": ">=0.0.1",

package/styles/bundles/browser-framework.css

@@ -7098,7 +7098,7 @@ body:has(#nd-docs-layout[data-fd-framework]) {
   );
 }
 
-#nd-docs-layout[data-fd-framework] {
+#nd-docs-layout[data-fd-framework]:not([data-fd-browser-adapter]) {
   display: grid;
   grid-template-columns: var(--fd-sidebar-width) 1fr;
   min-height: 100dvh;
@@ -7153,14 +7153,14 @@ body:has(#nd-docs-layout[data-fd-framework]) {
     display: flex;
   }
 
-  #nd-docs-layout[data-fd-framework] {
+  #nd-docs-layout[data-fd-framework]:not([data-fd-browser-adapter]) {
     display: flex;
     flex-direction: column;
   }
 }
 
 @media (min-width: 1024px) {
-  #nd-docs-layout[data-fd-framework] {
+  #nd-docs-layout[data-fd-framework]:not([data-fd-browser-adapter]) {
     grid-template-columns: var(--fd-sidebar-width) minmax(0, 1fr);
   }
 

package/styles/bundles/shared-framework.css

@@ -7112,7 +7112,7 @@ body:has(#nd-docs-layout[data-fd-framework]) {
   );
 }
 
-#nd-docs-layout[data-fd-framework] {
+#nd-docs-layout[data-fd-framework]:not([data-fd-browser-adapter]) {
   display: grid;
   grid-template-columns: var(--fd-sidebar-width) 1fr;
   min-height: 100dvh;
@@ -7167,14 +7167,14 @@ body:has(#nd-docs-layout[data-fd-framework]) {
     display: flex;
   }
 
-  #nd-docs-layout[data-fd-framework] {
+  #nd-docs-layout[data-fd-framework]:not([data-fd-browser-adapter]) {
     display: flex;
     flex-direction: column;
   }
 }
 
 @media (min-width: 1024px) {
-  #nd-docs-layout[data-fd-framework] {
+  #nd-docs-layout[data-fd-framework]:not([data-fd-browser-adapter]) {
     grid-template-columns: var(--fd-sidebar-width) minmax(0, 1fr);
   }
 

package/styles/framework.css

@@ -75,7 +75,7 @@ body:has(#nd-docs-layout[data-fd-framework]) {
 
 /* Layout (sidebar + content, TOC lives inside content area) */
 
-#nd-docs-layout[data-fd-framework] {
+#nd-docs-layout[data-fd-framework]:not([data-fd-browser-adapter]) {
   display: grid;
   grid-template-columns: var(--fd-sidebar-width) 1fr;
   min-height: 100dvh;
@@ -132,14 +132,14 @@ body:has(#nd-docs-layout[data-fd-framework]) {
     display: flex;
   }
 
-  #nd-docs-layout[data-fd-framework] {
+  #nd-docs-layout[data-fd-framework]:not([data-fd-browser-adapter]) {
     display: flex;
     flex-direction: column;
   }
 }
 
 @media (min-width: 1024px) {
-  #nd-docs-layout[data-fd-framework] {
+  #nd-docs-layout[data-fd-framework]:not([data-fd-browser-adapter]) {
     grid-template-columns: var(--fd-sidebar-width) minmax(0, 1fr);
   }