@farming-labs/theme 0.1.59 → 0.1.62

package/dist/docs-command-search.mjs

@@ -1,10 +1,11 @@
 "use client";
 
+import { emitClientAnalyticsEvent } from "./client-analytics.mjs";
 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 { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/docs-command-search.tsx
 function cn(...classes) {
@@ -56,7 +57,7 @@ function fuzzyScore(query, text) {
 	};
 }
 function HighlightedLabel({ label, indices }) {
-	if (!indices.length) return /* @__PURE__ */ jsx(Fragment, { children: label });
+	if (!indices.length) return /* @__PURE__ */ jsx(Fragment$1, { children: label });
 	const out = [];
 	for (let pos = 0; pos < label.length; pos++) if (indices.includes(pos)) {
 		let run = label[pos];
@@ -71,7 +72,7 @@ function HighlightedLabel({ label, indices }) {
 		}, `m-${pos}`));
 		pos = p - 1;
 	} else out.push(/* @__PURE__ */ jsx("span", { children: label[pos] }, `t-${pos}`));
-	return /* @__PURE__ */ jsx(Fragment, { children: out });
+	return /* @__PURE__ */ jsx(Fragment$1, { children: out });
 }
 function SearchIcon() {
 	return /* @__PURE__ */ jsxs("svg", {
@@ -302,7 +303,7 @@ function labelForType(type) {
 * fuzzy-search experience. Styled entirely via omni-* CSS classes
 * so each theme provides its own visual variant.
 */
-function DocsCommandSearch({ api = "/api/docs", locale }) {
+function DocsCommandSearch({ api = "/api/docs", locale, analytics = false }) {
 	const [open, setOpen] = useState(false);
 	const [query, setQuery] = useState("");
 	const [debouncedQuery, setDebouncedQuery] = useState("");
@@ -315,6 +316,18 @@ function DocsCommandSearch({ api = "/api/docs", locale }) {
 	const searchApi = useMemo(() => withLangInUrl(api, activeLocale), [activeLocale, api]);
 	const inputRef = useRef(null);
 	const listRef = useRef(null);
+	const setOpenWithAnalytics = useCallback((nextOpen, trigger) => {
+		setOpen(nextOpen);
+		if (!analytics) return;
+		emitClientAnalyticsEvent({
+			type: nextOpen ? "search_open" : "search_close",
+			locale: activeLocale,
+			properties: {
+				trigger,
+				mode: "command"
+			}
+		});
+	}, [activeLocale, analytics]);
 	useEffect(() => {
 		setMounted(true);
 		try {
@@ -332,12 +345,12 @@ function DocsCommandSearch({ api = "/api/docs", locale }) {
 				e.preventDefault();
 				e.stopPropagation();
 				e.stopImmediatePropagation();
-				setOpen(true);
+				setOpenWithAnalytics(true, "keyboard");
 			}
 		}
 		document.addEventListener("keydown", handler, true);
 		return () => document.removeEventListener("keydown", handler, true);
-	}, []);
+	}, [setOpenWithAnalytics]);
 	useEffect(() => {
 		function handler(e) {
 			const button = e.target.closest("button");
@@ -348,12 +361,12 @@ function DocsCommandSearch({ api = "/api/docs", locale }) {
 				e.preventDefault();
 				e.stopPropagation();
 				e.stopImmediatePropagation();
-				setOpen(true);
+				setOpenWithAnalytics(true, "button");
 			}
 		}
 		document.addEventListener("click", handler, true);
 		return () => document.removeEventListener("click", handler, true);
-	}, []);
+	}, [setOpenWithAnalytics]);
 	useEffect(() => {
 		if (!debouncedQuery.trim()) {
 			setResults([]);
@@ -363,6 +376,7 @@ function DocsCommandSearch({ api = "/api/docs", locale }) {
 		let cancelled = false;
 		setLoading(true);
 		(async () => {
+			const startedAt = Date.now();
 			try {
 				const requestUrl = new URL(searchApi, window.location.origin);
 				requestUrl.searchParams.set("query", debouncedQuery);
@@ -385,8 +399,28 @@ function DocsCommandSearch({ api = "/api/docs", locale }) {
 				if (!cancelled) {
 					setResults(items);
 					setActiveIndex(0);
+					if (analytics) emitClientAnalyticsEvent({
+						type: "search_query",
+						locale: activeLocale,
+						properties: {
+							mode: "command",
+							queryLength: debouncedQuery.length,
+							resultCount: items.length,
+							durationMs: Math.max(0, Date.now() - startedAt)
+						}
+					});
 				}
-			} catch {}
+			} catch {
+				if (!cancelled && analytics) emitClientAnalyticsEvent({
+					type: "search_error",
+					locale: activeLocale,
+					properties: {
+						mode: "command",
+						queryLength: debouncedQuery.length,
+						durationMs: Math.max(0, Date.now() - startedAt)
+					}
+				});
+			}
 			if (!cancelled) setLoading(false);
 		})();
 		return () => {
@@ -394,6 +428,7 @@ function DocsCommandSearch({ api = "/api/docs", locale }) {
 		};
 	}, [
 		activeLocale,
+		analytics,
 		debouncedQuery,
 		searchApi
 	]);
@@ -424,11 +459,11 @@ function DocsCommandSearch({ api = "/api/docs", locale }) {
 	useEffect(() => {
 		if (!open) return;
 		function handler(e) {
-			if (e.key === "Escape") setOpen(false);
+			if (e.key === "Escape") setOpenWithAnalytics(false, "escape");
 		}
 		document.addEventListener("keydown", handler);
 		return () => document.removeEventListener("keydown", handler);
-	}, [open]);
+	}, [open, setOpenWithAnalytics]);
 	const saveRecent = useCallback((item) => {
 		try {
 			const entry = {
@@ -442,11 +477,28 @@ function DocsCommandSearch({ api = "/api/docs", locale }) {
 		} catch {}
 	}, [recents]);
 	const execute = useCallback((item) => {
+		if (analytics) emitClientAnalyticsEvent({
+			type: "search_result_click",
+			locale: activeLocale,
+			path: item.url,
+			properties: {
+				mode: "command",
+				resultId: item.id,
+				resultUrl: item.url,
+				labelLength: item.label.length,
+				queryLength: query.length
+			}
+		});
 		saveRecent(item);
 		setOpen(false);
 		if (item.url.startsWith("http")) window.open(item.url, "_blank", "noopener");
 		else window.location.href = item.url;
-	}, [saveRecent]);
+	}, [
+		activeLocale,
+		analytics,
+		query.length,
+		saveRecent
+	]);
 	const displayItems = useMemo(() => {
 		if (results.length > 0) return results;
 		return [];
@@ -492,9 +544,9 @@ function DocsCommandSearch({ api = "/api/docs", locale }) {
 	}
 	if (!mounted || !open) return null;
 	const allItems = [...recentItems, ...displayItems];
-	return createPortal(/* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("div", {
+	return createPortal(/* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("div", {
 		className: "omni-overlay",
-		onClick: () => setOpen(false)
+		onClick: () => setOpenWithAnalytics(false, "overlay")
 	}), /* @__PURE__ */ jsxs("div", {
 		className: "omni-content",
 		role: "dialog",
@@ -528,7 +580,7 @@ function DocsCommandSearch({ api = "/api/docs", locale }) {
 						/* @__PURE__ */ jsx("button", {
 							"aria-label": "Close",
 							className: "omni-close-btn",
-							onClick: () => setOpen(false),
+							onClick: () => setOpenWithAnalytics(false, "button"),
 							children: /* @__PURE__ */ jsx(CloseIcon, {})
 						})
 					]

package/dist/docs-feedback.d.mts

@@ -12,6 +12,7 @@ interface DocsFeedbackProps {
   negativeLabel?: string;
   submitLabel?: string;
   onFeedback?: (data: DocsFeedbackData) => void | Promise<void>;
+  analytics?: boolean;
 }
 declare function DocsFeedback({
   pathname,
@@ -22,7 +23,8 @@ declare function DocsFeedback({
   positiveLabel,
   negativeLabel,
   submitLabel,
-  onFeedback
+  onFeedback,
+  analytics
 }: DocsFeedbackProps): react_jsx_runtime0.JSX.Element;
 //#endregion
 export { DocsFeedback, DocsFeedbackProps };

package/dist/docs-feedback.mjs

@@ -1,5 +1,6 @@
 "use client";
 
+import { emitClientAnalyticsEvent } from "./client-analytics.mjs";
 import { useEffect, useMemo, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 
@@ -99,7 +100,7 @@ function CheckIcon() {
 		})
 	});
 }
-function DocsFeedback({ pathname, entry, locale, question = "How is this guide?", placeholder = "Leave your feedback...", positiveLabel = "Good", negativeLabel = "Bad", submitLabel = "Submit", onFeedback }) {
+function DocsFeedback({ pathname, entry, locale, question = "How is this guide?", placeholder = "Leave your feedback...", positiveLabel = "Good", negativeLabel = "Bad", submitLabel = "Submit", onFeedback, analytics = false }) {
 	const [selected, setSelected] = useState(null);
 	const [comment, setComment] = useState("");
 	const [status, setStatus] = useState("idle");
@@ -114,14 +115,46 @@ function DocsFeedback({ pathname, entry, locale, question = "How is this guide?"
 	function handleSelect(value) {
 		setSelected(value);
 		if (status !== "idle") setStatus("idle");
+		if (analytics) emitClientAnalyticsEvent({
+			type: "feedback_select",
+			locale,
+			path: normalizedPathname,
+			properties: {
+				value,
+				slug: resolveSlug(entry, normalizedPathname)
+			}
+		});
 	}
 	async function handleSubmit() {
 		if (!selected || status === "submitting") return;
 		setStatus("submitting");
 		try {
-			await emitFeedback(buildFeedbackPayload(selected, normalizedPathname, entry, comment, locale), onFeedback);
+			const payload = buildFeedbackPayload(selected, normalizedPathname, entry, comment, locale);
+			await emitFeedback(payload, onFeedback);
+			if (analytics) emitClientAnalyticsEvent({
+				type: "feedback_submit",
+				locale,
+				path: normalizedPathname,
+				properties: {
+					value: payload.value,
+					slug: payload.slug,
+					hasComment: Boolean(payload.comment),
+					commentLength: payload.comment?.length ?? 0
+				}
+			});
 			setStatus("submitted");
 		} catch {
+			if (analytics) emitClientAnalyticsEvent({
+				type: "feedback_error",
+				locale,
+				path: normalizedPathname,
+				properties: {
+					value: selected,
+					slug: resolveSlug(entry, normalizedPathname),
+					hasComment: Boolean(comment.trim()),
+					commentLength: comment.trim().length
+				}
+			});
 			setStatus("error");
 		}
 	}

package/dist/docs-layout.mjs

@@ -11,7 +11,7 @@ import path from "node:path";
 import matter from "gray-matter";
 import { DocsLayout } from "fumadocs-ui/layouts/docs";
 import { Suspense } from "react";
-import { applySidebarFolderIndexBehavior, buildPageOpenGraph, buildPageTwitter, resolveChangelogConfig, resolveDocsAgentMdxContent, resolvePageSidebarFolderIndexBehavior } from "@farming-labs/docs";
+import { applySidebarFolderIndexBehavior, buildPageOpenGraph, buildPageTwitter, resolveChangelogConfig, resolveDocsAgentMdxContent, resolveDocsAnalyticsConfig, resolvePageSidebarFolderIndexBehavior } from "@farming-labs/docs";
 import { jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/docs-layout.tsx
@@ -554,6 +554,7 @@ function createDocsLayout(config, options) {
 	const tocConfig = config.theme?.ui?.layout?.toc;
 	const tocEnabled = tocConfig?.enabled !== false;
 	const tocStyle = tocConfig?.style;
+	const analyticsEnabled = resolveDocsAnalyticsConfig(config.analytics).enabled;
 	const localeContext = resolveDocsLocaleContext(config, options?.locale);
 	const i18n = resolveDocsI18nConfig(getDocsI18n(config));
 	const activeLocale = localeContext.locale ?? i18n?.defaultLocale;
@@ -673,7 +674,8 @@ function createDocsLayout(config, options) {
 					fallback: null,
 					children: /* @__PURE__ */ jsx(DocsCommandSearch, {
 						api: docsApiUrl,
-						locale: activeLocale
+						locale: activeLocale,
+						analytics: analyticsEnabled
 					})
 				}),
 				aiEnabled && /* @__PURE__ */ jsx(Suspense, {
@@ -690,7 +692,8 @@ function createDocsLayout(config, options) {
 						loaderVariant: aiLoaderVariant,
 						loadingComponentHtml: aiLoadingComponentHtml,
 						models: aiModels,
-						defaultModelId: aiDefaultModelId
+						defaultModelId: aiDefaultModelId,
+						analytics: analyticsEnabled
 					})
 				}),
 				/* @__PURE__ */ jsx(Suspense, {
@@ -724,6 +727,7 @@ function createDocsLayout(config, options) {
 						feedbackPositiveLabel: feedbackConfig.positiveLabel,
 						feedbackNegativeLabel: feedbackConfig.negativeLabel,
 						feedbackSubmitLabel: feedbackConfig.submitLabel,
+						analytics: analyticsEnabled,
 						children
 					})
 				})

package/dist/docs-page-client.d.mts

@@ -66,6 +66,7 @@ interface DocsPageClientProps {
   feedbackNegativeLabel?: string;
   feedbackSubmitLabel?: string;
   feedbackOnFeedback?: (data: DocsFeedbackData) => void | Promise<void>;
+  analytics?: boolean;
   children: ReactNode;
 }
 declare function DocsPageClient({
@@ -102,6 +103,7 @@ declare function DocsPageClient({
   feedbackNegativeLabel,
   feedbackSubmitLabel,
   feedbackOnFeedback,
+  analytics,
   children
 }: DocsPageClientProps): react_jsx_runtime0.JSX.Element;
 //#endregion

package/dist/docs-page-client.mjs

@@ -1,14 +1,15 @@
 "use client";
 
+import { emitClientAnalyticsEvent } from "./client-analytics.mjs";
 import { PageActions } from "./page-actions.mjs";
 import { useWindowSearchParams } from "./client-location.mjs";
 import { DocsFeedback } from "./docs-feedback.mjs";
 import { resolveClientLocale, withLangInUrl } from "./i18n.mjs";
-import { Children, cloneElement, isValidElement, useEffect, useState } from "react";
+import { Children, Fragment, cloneElement, isValidElement, useEffect, useState } from "react";
 import { DocsBody, DocsPage, EditOnGitHub } from "fumadocs-ui/layouts/docs/page";
 import { createPortal } from "react-dom";
 import { usePathname, useRouter } from "fumadocs-core/framework";
-import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/docs-page-client.tsx
 /**
@@ -124,6 +125,7 @@ function injectTitleDecorations(node, { description, belowTitle }) {
 		node,
 		inserted: false
 	};
+	const insertedExtras = extras.map((extra, index) => /* @__PURE__ */ jsx(Fragment, { children: extra }, `fd-title-decoration-${index}`));
 	function visit(current) {
 		if (current == null || typeof current === "boolean") return current;
 		if (inserted) return current;
@@ -134,7 +136,7 @@ function injectTitleDecorations(node, { description, belowTitle }) {
 		if (!isValidElement(current)) return current;
 		if (typeof current.type === "string" && current.type === "h1") {
 			inserted = true;
-			return Children.toArray([current, ...extras]);
+			return /* @__PURE__ */ jsxs(Fragment, { children: [current, insertedExtras] }, "fd-title-decoration-block");
 		}
 		const childProps = current.props ?? null;
 		if (childProps?.children === void 0) return current;
@@ -159,9 +161,9 @@ function injectTitleDecorations(node, { description, belowTitle }) {
 }
 function TitleDecorations({ description, belowTitle }) {
 	if (!description && !belowTitle) return null;
-	return /* @__PURE__ */ jsx(Fragment, { children: Children.toArray([description, belowTitle].filter(Boolean)) });
+	return /* @__PURE__ */ jsx(Fragment$1, { children: Children.toArray([description, belowTitle].filter(Boolean)) });
 }
-function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled = true, changelogBasePath, entry = "docs", locale, copyMarkdown = false, openDocs = false, openDocsProviders, pageActionsPosition = "below-title", pageActionsAlignment = "left", githubUrl, contentDir, githubBranch = "main", githubDirectory, editOnGithubUrl, lastModifiedMap, lastModified: lastModifiedProp, readingTimeMap, readingTime: readingTimeProp, readingTimeEnabled = false, lastUpdatedEnabled = true, lastUpdatedPosition = "footer", llmsTxtEnabled = false, descriptionMap, description, feedbackEnabled = false, feedbackQuestion, feedbackPlaceholder, feedbackPositiveLabel, feedbackNegativeLabel, feedbackSubmitLabel, feedbackOnFeedback, children }) {
+function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled = true, changelogBasePath, entry = "docs", locale, copyMarkdown = false, openDocs = false, openDocsProviders, pageActionsPosition = "below-title", pageActionsAlignment = "left", githubUrl, contentDir, githubBranch = "main", githubDirectory, editOnGithubUrl, lastModifiedMap, lastModified: lastModifiedProp, readingTimeMap, readingTime: readingTimeProp, readingTimeEnabled = false, lastUpdatedEnabled = true, lastUpdatedPosition = "footer", llmsTxtEnabled = false, descriptionMap, description, feedbackEnabled = false, feedbackQuestion, feedbackPlaceholder, feedbackPositiveLabel, feedbackNegativeLabel, feedbackSubmitLabel, feedbackOnFeedback, analytics = false, children }) {
 	const fdTocStyle = tocStyle === "directional" ? "clerk" : void 0;
 	const [toc, setToc] = useState([]);
 	const [titlePortalHost, setTitlePortalHost] = useState(null);
@@ -173,6 +175,25 @@ function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled =
 	const normalizedPath = (browserPath ?? pathname).replace(/\/$/, "") || "/";
 	const isChangelogRoute = !!(changelogBasePath && (normalizedPath === changelogBasePath || normalizedPath.startsWith(`${changelogBasePath}/`)));
 	const matchedReadingTime = readingTimeMap?.[normalizedPath];
+	useEffect(() => {
+		if (!analytics) return;
+		emitClientAnalyticsEvent({
+			type: "page_view",
+			locale: activeLocale,
+			path: normalizedPath,
+			properties: {
+				entry,
+				pathname: normalizedPath,
+				isChangelogRoute
+			}
+		});
+	}, [
+		analytics,
+		activeLocale,
+		entry,
+		isChangelogRoute,
+		normalizedPath
+	]);
 	const resolvedReadingTime = !isChangelogRoute ? readingTimeProp !== void 0 ? readingTimeProp : readingTimeEnabled ? matchedReadingTime : void 0 : void 0;
 	const effectiveTocEnabled = isChangelogRoute ? false : tocEnabled;
 	const effectiveBreadcrumbEnabled = isChangelogRoute ? false : breadcrumbEnabled;
@@ -284,7 +305,8 @@ function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled =
 					openDocs,
 					providers: openDocsProviders,
 					alignment: pageActionsAlignment,
-					githubFileUrl
+					githubFileUrl,
+					analytics
 				})
 			}),
 			showReadingTimeBelowTitle && readingTimeBlock
@@ -318,6 +340,7 @@ function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled =
 		description: titleDescription,
 		belowTitle: belowTitleBlock
 	}), titlePortalHost) : null;
+	const renderedChildren = Children.toArray(decoratedChildren);
 	return /* @__PURE__ */ jsxs(DocsPage, {
 		full: false,
 		toc,
@@ -347,7 +370,8 @@ function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled =
 						openDocs,
 						providers: openDocsProviders,
 						alignment: pageActionsAlignment,
-						githubFileUrl
+						githubFileUrl,
+						analytics
 					})
 				}), readingTimeBlock]
 			}),
@@ -360,7 +384,7 @@ function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled =
 				children: [
 					/* @__PURE__ */ jsx("div", {
 						style: { flex: 1 },
-						children: decoratedChildren
+						children: renderedChildren
 					}),
 					titleDecorationsPortal,
 					!isChangelogRoute && feedbackEnabled && /* @__PURE__ */ jsx(DocsFeedback, {
@@ -372,7 +396,8 @@ function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled =
 						positiveLabel: feedbackPositiveLabel,
 						negativeLabel: feedbackNegativeLabel,
 						submitLabel: feedbackSubmitLabel,
-						onFeedback: feedbackOnFeedback
+						onFeedback: feedbackOnFeedback,
+						analytics
 					}),
 					showFooter && /* @__PURE__ */ jsxs("div", {
 						className: "not-prose fd-page-footer",

package/dist/page-actions.d.mts

@@ -14,13 +14,15 @@ interface PageActionsProps {
   alignment?: "left" | "right";
   /** GitHub file URL (edit view) for the current page. Used when urlTemplate contains {githubUrl}. */
   githubFileUrl?: string | null;
+  analytics?: boolean;
 }
 declare function PageActions({
   copyMarkdown,
   openDocs,
   providers,
   alignment,
-  githubFileUrl
+  githubFileUrl,
+  analytics
 }: PageActionsProps): react_jsx_runtime0.JSX.Element | null;
 //#endregion
 export { PageActions };

package/dist/page-actions.mjs

@@ -1,5 +1,6 @@
 "use client";
 
+import { emitClientAnalyticsEvent } from "./client-analytics.mjs";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { usePathname } from "fumadocs-core/framework";
 import { jsx, jsxs } from "react/jsx-runtime";
@@ -72,7 +73,7 @@ const DEFAULT_PROVIDERS = [{
 	name: "Claude",
 	urlTemplate: "https://claude.ai/new?q=Read+{mdxUrl},+I+want+to+ask+questions+about+it."
 }];
-function PageActions({ copyMarkdown, openDocs, providers, alignment = "left", githubFileUrl }) {
+function PageActions({ copyMarkdown, openDocs, providers, alignment = "left", githubFileUrl, analytics = false }) {
 	const [copied, setCopied] = useState(false);
 	const [dropdownOpen, setDropdownOpen] = useState(false);
 	const dropdownRef = useRef(null);
@@ -82,13 +83,22 @@ function PageActions({ copyMarkdown, openDocs, providers, alignment = "left", gi
 		try {
 			const article = document.querySelector("article");
 			if (article) {
-				await navigator.clipboard.writeText(article.innerText || "");
+				const content = article.innerText || "";
+				await navigator.clipboard.writeText(content);
+				if (analytics) emitClientAnalyticsEvent({
+					type: "page_action_copy_markdown",
+					properties: {
+						contentLength: content.length,
+						pathname
+					}
+				});
 				setCopied(true);
 				setTimeout(() => setCopied(false), 2e3);
 			}
 		} catch {}
-	}, []);
-	const handleOpen = useCallback((template) => {
+	}, [analytics, pathname]);
+	const handleOpen = useCallback((provider) => {
+		const template = provider.urlTemplate;
 		if (/\{githubUrl\}/.test(template) && !githubFileUrl) {
 			setDropdownOpen(false);
 			return;
@@ -96,9 +106,21 @@ function PageActions({ copyMarkdown, openDocs, providers, alignment = "left", gi
 		const pageUrl = window.location.href;
 		const mdxUrl = `${window.location.origin}${pathname}.mdx`;
 		let url = template.replace(/\{url\}/g, encodeURIComponent(pageUrl)).replace(/\{mdxUrl\}/g, encodeURIComponent(mdxUrl)).replace(/\{githubUrl\}/g, githubFileUrl ?? "");
+		if (analytics) emitClientAnalyticsEvent({
+			type: "page_action_open_docs",
+			properties: {
+				provider: provider.name,
+				pathname,
+				usesGithubUrl: template.includes("{githubUrl}")
+			}
+		});
 		window.open(url, "_blank", "noopener,noreferrer");
 		setDropdownOpen(false);
-	}, [pathname, githubFileUrl]);
+	}, [
+		analytics,
+		pathname,
+		githubFileUrl
+	]);
 	useEffect(() => {
 		if (!dropdownOpen) return;
 		function handleClick(e) {
@@ -127,7 +149,17 @@ function PageActions({ copyMarkdown, openDocs, providers, alignment = "left", gi
 			className: "fd-page-action-dropdown",
 			children: [/* @__PURE__ */ jsxs("button", {
 				type: "button",
-				onClick: () => setDropdownOpen(!dropdownOpen),
+				onClick: () => {
+					const next = !dropdownOpen;
+					setDropdownOpen(next);
+					if (analytics && next) emitClientAnalyticsEvent({
+						type: "page_action_open_docs_menu",
+						properties: {
+							providerCount: resolvedProviders.length,
+							pathname
+						}
+					});
+				},
 				className: "fd-page-action-btn",
 				"aria-expanded": dropdownOpen,
 				children: [/* @__PURE__ */ jsx("span", { children: "Open in" }), /* @__PURE__ */ jsx(ChevronDownIcon, {})]
@@ -138,7 +170,7 @@ function PageActions({ copyMarkdown, openDocs, providers, alignment = "left", gi
 					type: "button",
 					role: "menuitem",
 					className: "fd-page-action-menu-item",
-					onClick: () => handleOpen(provider.urlTemplate),
+					onClick: () => handleOpen(provider),
 					children: [
 						provider.iconHtml && /* @__PURE__ */ jsx("span", {
 							className: "fd-page-action-menu-icon",

package/dist/tanstack-layout.mjs

@@ -7,7 +7,7 @@ import { SidebarSearchWithAI } from "./sidebar-search-ai.mjs";
 import { LocaleThemeControl } from "./locale-theme-control.mjs";
 import { DocsLayout } from "fumadocs-ui/layouts/docs";
 import { Suspense } from "react";
-import { applySidebarFolderIndexBehavior } from "@farming-labs/docs";
+import { applySidebarFolderIndexBehavior, resolveDocsAnalyticsConfig } from "@farming-labs/docs";
 import { jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/tanstack-layout.tsx
@@ -211,6 +211,7 @@ function TanstackDocsLayout({ config, tree, locale, description, readingTime, la
 	const tocConfig = config.theme?.ui?.layout?.toc;
 	const tocEnabled = tocConfig?.enabled !== false;
 	const tocStyle = tocConfig?.style;
+	const analyticsEnabled = resolveDocsAnalyticsConfig(config.analytics).enabled;
 	const docsApiUrl = withLangInUrl("/api/docs", locale);
 	const navTitle = config.nav?.title ?? "Docs";
 	const navUrl = withLangInUrl(config.nav?.url ?? `/${config.entry ?? "docs"}`, locale);
@@ -310,7 +311,8 @@ function TanstackDocsLayout({ config, tree, locale, description, readingTime, la
 				fallback: null,
 				children: /* @__PURE__ */ jsx(DocsCommandSearch, {
 					api: docsApiUrl,
-					locale
+					locale,
+					analytics: analyticsEnabled
 				})
 			}),
 			aiEnabled && /* @__PURE__ */ jsx(Suspense, {
@@ -325,7 +327,8 @@ function TanstackDocsLayout({ config, tree, locale, description, readingTime, la
 					aiLabel,
 					loaderVariant: aiLoaderVariant,
 					models: aiModels,
-					defaultModelId: aiDefaultModelId
+					defaultModelId: aiDefaultModelId,
+					analytics: analyticsEnabled
 				})
 			}),
 			/* @__PURE__ */ jsx(Suspense, {
@@ -355,6 +358,7 @@ function TanstackDocsLayout({ config, tree, locale, description, readingTime, la
 					feedbackPositiveLabel: feedbackConfig.positiveLabel,
 					feedbackNegativeLabel: feedbackConfig.negativeLabel,
 					feedbackSubmitLabel: feedbackConfig.submitLabel,
+					analytics: analyticsEnabled,
 					children
 				})
 			})

package/package.json

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

package/styles/base.css

@@ -1399,8 +1399,10 @@ html[data-fd-route-kind="changelog"] .fd-ai-fm-input-bar {
 .fd-page-nav-card {
   display: flex;
   min-width: 0;
+  min-height: 8.75rem;
   flex-direction: column;
-  gap: 0.25rem;
+  justify-content: flex-start;
+  gap: 0.375rem;
   padding: 1rem;
   border: 1px solid var(--color-fd-border, hsl(0 0% 80% / 50%));
   border-radius: 0.5rem;
@@ -1434,10 +1436,32 @@ html[data-fd-route-kind="changelog"] .fd-ai-fm-input-bar {
 }
 
 .fd-page-nav-title {
+  display: -webkit-box;
+  overflow: hidden;
+  min-height: calc(1.4em * 2);
   font-size: 0.875rem;
   font-weight: 600;
   line-height: 1.4;
   color: var(--color-fd-foreground);
+  overflow-wrap: anywhere;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+}
+
+.fd-page-nav-description {
+  display: -webkit-box;
+  overflow: hidden;
+  min-height: calc(1.5em * 2);
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+  font-size: 0.875rem;
+  line-height: 1.5;
+  color: var(--color-fd-muted-foreground, hsl(0 0% 45%));
+  overflow-wrap: anywhere;
+}
+
+.fd-page-nav-description-empty {
+  visibility: hidden;
 }
 
 @media (max-width: 640px) {