@farming-labs/theme 0.1.2 → 0.1.4

package/dist/docs-api.d.mts

@@ -1,4 +1,4 @@
-import { DocsI18nConfig, DocsMcpConfig, OrderingItem } from "@farming-labs/docs";
+import { DocsI18nConfig, DocsMcpConfig, DocsSearchConfig, OrderingItem } from "@farming-labs/docs";
 
 //#region src/docs-api.d.ts
 interface AIProviderConfig {
@@ -26,14 +26,19 @@ interface AIOptions {
   maxResults?: number;
 }
 interface DocsAPIOptions {
+  rootDir?: string;
   /** Docs entry folder (default: read from docs.config) */
   entry?: string;
+  /** Override the docs content directory when it does not live in app/<entry>. */
+  contentDir?: string;
   /** Search language (default: "english") */
   language?: string;
   /** AI chat configuration */
   ai?: AIOptions;
   /** i18n config (optional) */
   i18n?: DocsI18nConfig;
+  /** Search configuration */
+  search?: boolean | DocsSearchConfig;
 }
 interface DocsMCPAPIOptions {
   rootDir?: string;
@@ -44,6 +49,7 @@ interface DocsMCPAPIOptions {
   };
   ordering?: "alphabetical" | "numeric" | OrderingItem[];
   mcp?: boolean | DocsMcpConfig;
+  search?: boolean | DocsSearchConfig;
 }
 /**
  * Create a unified docs API route handler.
@@ -57,18 +63,22 @@ interface DocsMCPAPIOptions {
  * @example
  * ```ts
  * // app/api/docs/route.ts (auto-generated by withDocs)
- * import { createDocsAPI } from "@farming-labs/theme/api";
+ * import { createDocsAPI } from "@farming-labs/next/api";
  * export const { GET, POST } = createDocsAPI();
  * export const revalidate = false;
  * ```
  *
  * @param options - Optional overrides (entry, language, ai config)
  */
+/**
+ * @deprecated Prefer `createDocsAPI` from `@farming-labs/next/api` in Next.js apps.
+ * The `@farming-labs/theme/api` path is kept for compatibility and will be phased out.
+ */
 declare function createDocsAPI(options?: DocsAPIOptions): {
   /**
    * GET handler — search, llms.txt, or llms-full.txt depending on query params.
    */
-  GET(request: Request): Response | Promise<Response>;
+  GET(request: Request): Promise<Response>;
   /**
    * POST handler — AI chat with RAG.
    * Body: `{ messages: [{ role: "user", content: "How do I …?" }] }`
@@ -81,6 +91,10 @@ declare function createDocsAPI(options?: DocsAPIOptions): {
  *
  * Returns `{ GET, POST, DELETE }` for use in a Next.js route handler.
  */
+/**
+ * @deprecated Prefer `createDocsMCPAPI` from `@farming-labs/next/api` in Next.js apps.
+ * The `@farming-labs/theme/api` path is kept for compatibility and will be phased out.
+ */
 declare function createDocsMCPAPI(options?: DocsMCPAPIOptions): {
   GET(request: Request): Promise<Response>;
   POST(request: Request): Promise<Response>;

package/dist/docs-api.mjs

@@ -1,10 +1,9 @@
 import { withLangInUrl } from "./i18n.mjs";
 import { getNextAppDir } from "./get-app-dir.mjs";
-import { resolveDocsI18n, resolveDocsLocale } from "@farming-labs/docs";
+import { performDocsSearch, resolveDocsI18n, resolveDocsLocale, resolveSearchRequestConfig } from "@farming-labs/docs";
 import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
-import { createSearchAPI } from "fumadocs-core/search/server";
 import { createDocsMcpHttpHandler, createFilesystemDocsMcpSource } from "@farming-labs/docs/server";
 
 //#region src/docs-api.ts
@@ -22,7 +21,7 @@ import { createDocsMcpHttpHandler, createFilesystemDocsMcpSource } from "@farmin
 * @example
 * ```ts
 * // app/api/docs/route.ts (auto-generated by withDocs)
-* import { createDocsAPI } from "@farming-labs/theme/api";
+* import { createDocsAPI } from "@farming-labs/next/api";
 * export const { GET, POST } = createDocsAPI();
 * export const revalidate = false;
 * ```
@@ -289,13 +288,16 @@ function scanDocsDir(docsDir, entry, locale) {
 			const { data } = matter(raw);
 			const title = data.title || slugParts[slugParts.length - 1]?.replace(/-/g, " ") || "Documentation";
 			const description = data.description;
+			const { content: rawContent } = matter(raw);
 			const content = stripMdx(raw);
 			const url = withLangInUrl(slugParts.length === 0 ? `/${entry}` : `/${entry}/${slugParts.join("/")}`, locale);
 			indexes.push({
 				title,
 				description,
 				content,
-				url
+				rawContent,
+				url,
+				locale
 			});
 		} catch {}
 		let entries;
@@ -334,7 +336,7 @@ function resolveModelAndProvider(aiConfig, requestedModelId) {
 		apiKey
 	};
 }
-async function handleAskAI(request, indexes, searchServer, aiConfig) {
+async function handleAskAI(request, indexes, aiConfig) {
 	let body;
 	try {
 		body = await request.json();
@@ -445,21 +447,45 @@ function generateLlmsTxt(indexes, options) {
 * @example
 * ```ts
 * // app/api/docs/route.ts (auto-generated by withDocs)
-* import { createDocsAPI } from "@farming-labs/theme/api";
+* import { createDocsAPI } from "@farming-labs/next/api";
 * export const { GET, POST } = createDocsAPI();
 * export const revalidate = false;
 * ```
 *
 * @param options - Optional overrides (entry, language, ai config)
 */
+/**
+* @deprecated Prefer `createDocsAPI` from `@farming-labs/next/api` in Next.js apps.
+* The `@farming-labs/theme/api` path is kept for compatibility and will be phased out.
+*/
 function createDocsAPI(options) {
-	const root = process.cwd();
+	const root = options?.rootDir ?? process.cwd();
 	const entry = options?.entry ?? readEntry(root);
 	const appDir = getNextAppDir(root);
-	const language = options?.language ?? "english";
+	const contentDir = options?.contentDir ?? path.join(appDir, entry);
 	const i18n = resolveDocsI18n(options?.i18n ?? readI18nConfig(root));
 	const aiConfig = options?.ai ?? readAIConfig(root);
+	const searchConfig = options?.search;
 	const llmsConfig = readLlmsTxtConfig(root);
+	function resolveDocsDirCandidates(locale) {
+		const relativeCandidates = /* @__PURE__ */ new Set();
+		if (path.isAbsolute(contentDir)) return [locale ? path.join(contentDir, locale) : contentDir];
+		relativeCandidates.add(contentDir);
+		relativeCandidates.add(path.join("app", entry));
+		relativeCandidates.add(path.join("src", "app", entry));
+		const rootCandidates = new Set([root]);
+		if (path.basename(root) === "server") rootCandidates.add(path.resolve(root, "..", ".."));
+		else {
+			rootCandidates.add(path.join(root, ".next", "server"));
+			rootCandidates.add(path.join(root, ".next-build", "server"));
+		}
+		const resolved = /* @__PURE__ */ new Set();
+		for (const base of rootCandidates) for (const relative of relativeCandidates) {
+			const candidate = path.join(base, relative);
+			resolved.add(locale ? path.join(candidate, locale) : candidate);
+		}
+		return [...resolved];
+	}
 	function resolveLocaleFromRequest(request) {
 		if (!i18n) return void 0;
 		const direct = resolveDocsLocale(new URL(request.url).searchParams, i18n);
@@ -474,37 +500,29 @@ function createDocsAPI(options) {
 	function resolveContextFromRequest(request) {
 		if (!i18n) return {
 			entryPath: entry,
-			docsDir: path.join(root, appDir, entry)
+			docsDirs: resolveDocsDirCandidates()
 		};
 		const locale = resolveLocaleFromRequest(request) ?? i18n.defaultLocale;
 		return {
 			entryPath: entry,
 			locale,
-			docsDir: path.join(root, appDir, entry, locale)
+			docsDirs: resolveDocsDirCandidates(locale)
 		};
 	}
 	const indexesByLocale = /* @__PURE__ */ new Map();
-	const searchApiByLocale = /* @__PURE__ */ new Map();
 	const llmsCacheByLocale = /* @__PURE__ */ new Map();
 	function getIndexes(ctx) {
 		const key = ctx.locale ?? "__default__";
 		const cached = indexesByLocale.get(key);
 		if (cached) return cached;
-		const next = scanDocsDir(ctx.docsDir, ctx.entryPath, ctx.locale);
+		let next = [];
+		for (const docsDir of ctx.docsDirs) {
+			next = scanDocsDir(docsDir, ctx.entryPath, ctx.locale);
+			if (next.length > 0) break;
+		}
 		indexesByLocale.set(key, next);
 		return next;
 	}
-	function getSearchAPI(ctx) {
-		const key = ctx.locale ?? "__default__";
-		const cached = searchApiByLocale.get(key);
-		if (cached) return cached;
-		const api = createSearchAPI("simple", {
-			language,
-			indexes: getIndexes(ctx)
-		});
-		searchApiByLocale.set(key, api);
-		return api;
-	}
 	function getLlmsContent(ctx) {
 		const key = ctx.locale ?? "__default__";
 		const cached = llmsCacheByLocale.get(key);
@@ -518,9 +536,10 @@ function createDocsAPI(options) {
 		return next;
 	}
 	return {
-		GET(request) {
+		async GET(request) {
 			const ctx = resolveContextFromRequest(request);
-			const format = new URL(request.url).searchParams.get("format");
+			const url = new URL(request.url);
+			const format = url.searchParams.get("format");
 			if (format === "llms") return new Response(getLlmsContent(ctx).llmsTxt, { headers: {
 				"Content-Type": "text/plain; charset=utf-8",
 				"Cache-Control": "public, max-age=3600"
@@ -529,12 +548,21 @@ function createDocsAPI(options) {
 				"Content-Type": "text/plain; charset=utf-8",
 				"Cache-Control": "public, max-age=3600"
 			} });
-			return getSearchAPI(ctx).GET(request);
+			const query = url.searchParams.get("query")?.trim();
+			if (!query) return new Response(JSON.stringify([]), { headers: { "Content-Type": "application/json" } });
+			const results = await performDocsSearch({
+				pages: getIndexes(ctx),
+				query,
+				search: resolveSearchRequestConfig(searchConfig, request.url),
+				locale: ctx.locale,
+				pathname: url.searchParams.get("pathname") ?? void 0,
+				siteTitle: llmsConfig.siteTitle ?? "Documentation"
+			});
+			return new Response(JSON.stringify(results), { headers: { "Content-Type": "application/json" } });
 		},
 		async POST(request) {
 			if (!aiConfig.enabled) return Response.json({ error: "AI is not enabled. Set `ai: { enabled: true }` in your docs.config to enable it." }, { status: 404 });
-			const ctx = resolveContextFromRequest(request);
-			return handleAskAI(request, getIndexes(ctx), getSearchAPI(ctx), aiConfig);
+			return handleAskAI(request, getIndexes(resolveContextFromRequest(request)), aiConfig);
 		}
 	};
 }
@@ -543,6 +571,10 @@ function createDocsAPI(options) {
 *
 * Returns `{ GET, POST, DELETE }` for use in a Next.js route handler.
 */
+/**
+* @deprecated Prefer `createDocsMCPAPI` from `@farming-labs/next/api` in Next.js apps.
+* The `@farming-labs/theme/api` path is kept for compatibility and will be phased out.
+*/
 function createDocsMCPAPI(options = {}) {
 	const rootDir = options.rootDir ?? process.cwd();
 	const entry = options.entry ?? readEntry(rootDir);
@@ -558,6 +590,7 @@ function createDocsMCPAPI(options = {}) {
 			ordering: options.ordering
 		}),
 		mcp: options.mcp ?? readMcpConfig(rootDir),
+		search: options.search,
 		defaultName: navTitle
 	});
 	return {

package/dist/docs-command-search.mjs

@@ -18,6 +18,9 @@ function stripHtml(html) {
 	}
 	return html.replace(/<[^>]+>/g, "");
 }
+function stripSearchPreview(text) {
+	return text.replace(/```[\s\S]*?```/g, "").replace(/~~~[\s\S]*?~~~/g, "").replace(/!\[([^\]]*)\]\([^)]+\)/g, "$1").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/^#{1,6}\s+/gm, "").replace(/^\|?[\s:-]+(\|[\s:-]+)+\|?\s*$/gm, "").replace(/\|/g, " ").replace(/^[-*+]\s+/gm, "").replace(/(\*{1,3}|_{1,3})(.*?)\1/g, "$2").replace(/`([^`]+)`/g, "$1").replace(/`+/g, "").replace(/\s{2,}/g, " ").trim();
+}
 function fuzzyScore(query, text) {
 	const q = query.trim().toLowerCase();
 	const t = text.toLowerCase();
@@ -366,12 +369,12 @@ function DocsCommandSearch({ api = "/api/docs", locale }) {
 				const res = await fetch(requestUrl.toString());
 				if (!res.ok || cancelled) return;
 				const items = (await res.json()).map((r) => {
-					const label = stripHtml(r.content);
+					const label = stripSearchPreview(stripHtml(r.content));
 					const { score, indices } = fuzzyScore(debouncedQuery, label);
 					return {
 						id: r.id,
 						label,
-						subtitle: labelForType(r.type),
+						subtitle: r.description ? stripSearchPreview(stripHtml(r.description)) : labelForType(r.type),
 						url: withLangInUrl(r.url, activeLocale),
 						icon: iconForType(r.type),
 						score,

package/dist/docs-page-client.mjs

@@ -89,6 +89,27 @@ function localizeInternalLinks(root, locale) {
 		} catch {}
 	}
 }
+function decodeHashTarget(hash) {
+	const value = hash.startsWith("#") ? hash.slice(1) : hash;
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return value;
+	}
+}
+function escapeIdSelector(value) {
+	if (typeof CSS !== "undefined" && typeof CSS.escape === "function") return CSS.escape(value);
+	return value.replace(/["\\.#:[\]>+~(){}^$|*?=!'`\s]/g, "\\$&");
+}
+function scrollToHashTarget(hash) {
+	if (!hash || hash === "#") return false;
+	const targetId = decodeHashTarget(hash);
+	if (!targetId) return false;
+	const target = document.getElementById(targetId) ?? document.querySelector(`#${escapeIdSelector(targetId)}`);
+	if (!target) return false;
+	target.scrollIntoView({ block: "start" });
+	return true;
+}
 function injectTitleDecorations(node, { description, belowTitle }) {
 	if (!description && !belowTitle) return {
 		node,
@@ -172,6 +193,33 @@ function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled =
 		children,
 		pathname
 	]);
+	useEffect(() => {
+		let frame = 0;
+		let timeout = 0;
+		let cancelled = false;
+		const scheduleScroll = (attempt = 0) => {
+			if (cancelled) return;
+			const hash = window.location.hash;
+			if (!hash) return;
+			if (scrollToHashTarget(hash) || attempt >= 20) return;
+			timeout = window.setTimeout(() => {
+				frame = requestAnimationFrame(() => scheduleScroll(attempt + 1));
+			}, 100);
+		};
+		frame = requestAnimationFrame(() => scheduleScroll());
+		const onHashChange = () => {
+			cancelAnimationFrame(frame);
+			clearTimeout(timeout);
+			frame = requestAnimationFrame(() => scheduleScroll());
+		};
+		window.addEventListener("hashchange", onHashChange);
+		return () => {
+			cancelled = true;
+			window.removeEventListener("hashchange", onHashChange);
+			cancelAnimationFrame(frame);
+			clearTimeout(timeout);
+		};
+	}, [pathname, children]);
 	const showActions = copyMarkdown || openDocs;
 	const showActionsBelowTitle = showActions && pageActionsPosition === "below-title";
 	const showActionsAboveTitle = showActions && pageActionsPosition === "above-title";

package/dist/search.d.mts

@@ -2,7 +2,7 @@
 /**
  * Search API — backward-compatible re-export.
  *
- * New projects should use `createDocsAPI` from `@farming-labs/theme/api`
+ * New projects should use `createDocsAPI` from `@farming-labs/next/api`
  * which provides a unified handler for both search (GET) and AI chat (POST).
  *
  * This module is kept for backward compatibility with existing projects
@@ -11,7 +11,7 @@
  * @example
  * ```ts
  * // Recommended (new): app/api/docs/route.ts
- * import { createDocsAPI } from "@farming-labs/theme/api";
+ * import { createDocsAPI } from "@farming-labs/next/api";
  * export const { GET, POST } = createDocsAPI();
  *
  * // Legacy: app/api/search/route.ts
@@ -20,14 +20,14 @@
  * ```
  */
 /**
- * @deprecated Use `createDocsAPI` from `@farming-labs/theme/api` instead.
+ * @deprecated Use `createDocsAPI` from `@farming-labs/next/api` instead.
  * This function is kept for backward compatibility.
  */
 declare function createDocsSearchAPI(options?: {
   entry?: string;
   language?: string;
 }): {
-  GET(request: Request): Response | Promise<Response>;
+  GET(request: Request): Promise<Response>;
   POST(request: Request): Promise<Response>;
 };
 //#endregion

package/dist/search.mjs

@@ -4,7 +4,7 @@ import { createDocsAPI } from "./docs-api.mjs";
 /**
 * Search API — backward-compatible re-export.
 *
-* New projects should use `createDocsAPI` from `@farming-labs/theme/api`
+* New projects should use `createDocsAPI` from `@farming-labs/next/api`
 * which provides a unified handler for both search (GET) and AI chat (POST).
 *
 * This module is kept for backward compatibility with existing projects
@@ -13,7 +13,7 @@ import { createDocsAPI } from "./docs-api.mjs";
 * @example
 * ```ts
 * // Recommended (new): app/api/docs/route.ts
-* import { createDocsAPI } from "@farming-labs/theme/api";
+* import { createDocsAPI } from "@farming-labs/next/api";
 * export const { GET, POST } = createDocsAPI();
 *
 * // Legacy: app/api/search/route.ts
@@ -22,7 +22,7 @@ import { createDocsAPI } from "./docs-api.mjs";
 * ```
 */
 /**
-* @deprecated Use `createDocsAPI` from `@farming-labs/theme/api` instead.
+* @deprecated Use `createDocsAPI` from `@farming-labs/next/api` instead.
 * This function is kept for backward compatibility.
 */
 function createDocsSearchAPI(options) {

package/package.json

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