@farming-labs/theme 0.1.45 → 0.1.48

package/dist/docs-layout.mjs

@@ -3,6 +3,7 @@ import { withLangInUrl } from "./i18n.mjs";
 import { DocsPageClient } from "./docs-page-client.mjs";
 import { DocsAIFeatures } from "./docs-ai-features.mjs";
 import { DocsCommandSearch } from "./docs-command-search.mjs";
+import { resolvePageReadingTime, resolveReadingTimeOptions } from "./reading-time.mjs";
 import { SidebarSearchWithAI } from "./sidebar-search-ai.mjs";
 import { LocaleThemeControl } from "./locale-theme-control.mjs";
 import fs from "node:fs";
@@ -10,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 { buildPageOpenGraph, buildPageTwitter, resolveChangelogConfig } from "@farming-labs/docs";
+import { buildPageOpenGraph, buildPageTwitter, resolveChangelogConfig, resolveDocsAgentMdxContent } from "@farming-labs/docs";
 import { jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/docs-layout.tsx
@@ -340,6 +341,30 @@ function buildDescriptionMap(config, ctx) {
 	scan(docsDir, []);
 	return map;
 }
+function buildReadingTimeMap(config, ctx, options) {
+	const docsDir = ctx.docsDir;
+	const map = {};
+	const excludedDirs = getExcludedDocsDirs(config, ctx);
+	function scan(dir, slugParts) {
+		if (!fs.existsSync(dir)) return;
+		if (isExcludedDir(dir, excludedDirs)) return;
+		const pagePath = path.join(dir, "page.mdx");
+		if (fs.existsSync(pagePath)) {
+			const { data, content } = matter(fs.readFileSync(pagePath, "utf-8"));
+			const minutes = resolvePageReadingTime(data, resolveDocsAgentMdxContent(content, "human"), options);
+			if (typeof minutes === "number") {
+				const url = slugParts.length === 0 ? `/${ctx.entryPath}` : `/${ctx.entryPath}/${slugParts.join("/")}`;
+				map[url] = minutes;
+			}
+		}
+		for (const name of fs.readdirSync(dir)) {
+			const full = path.join(dir, name);
+			if (fs.statSync(full).isDirectory()) scan(full, [...slugParts, name]);
+		}
+	}
+	scan(docsDir, []);
+	return map;
+}
 /**
 * Build a Next.js Metadata object from the docs config.
 *
@@ -556,6 +581,9 @@ function createDocsLayout(config, options) {
 	const lastUpdatedRaw = config.lastUpdated;
 	const lastUpdatedEnabled = lastUpdatedRaw !== false && (typeof lastUpdatedRaw !== "object" || lastUpdatedRaw.enabled !== false);
 	const lastUpdatedPosition = typeof lastUpdatedRaw === "object" ? lastUpdatedRaw.position ?? "footer" : "footer";
+	const readingTimeOptions = resolveReadingTimeOptions(config.readingTime);
+	const readingTimeEnabledByDefault = readingTimeOptions.enabled;
+	const readingTimeWordsPerMinute = readingTimeOptions.wordsPerMinute ?? 220;
 	const llmsTxtEnabled = resolveBool(config.llmsTxt);
 	const feedbackConfig = resolveFeedbackConfig(config.feedback);
 	const openDocsProviders = (typeof pageActions?.openDocs === "object" && pageActions.openDocs.providers ? pageActions.openDocs.providers : void 0)?.map((p) => ({
@@ -588,6 +616,11 @@ function createDocsLayout(config, options) {
 	}
 	const lastModifiedMap = buildLastModifiedMap(config, localeContext);
 	const descriptionMap = buildDescriptionMap(config, localeContext);
+	const readingTimeMap = buildReadingTimeMap(config, localeContext, {
+		enabledByDefault: readingTimeEnabledByDefault,
+		wordsPerMinute: readingTimeWordsPerMinute
+	});
+	const readingTimeEnabled = readingTimeEnabledByDefault || Object.keys(readingTimeMap).length > 0;
 	return function DocsLayoutWrapper({ children }) {
 		const tree = buildTree(config, localeContext, !!sidebarFlat);
 		const localizedTree = i18n ? localizeTreeUrls(tree, activeLocale) : tree;
@@ -680,6 +713,8 @@ function createDocsLayout(config, options) {
 							lastModifiedMap,
 							lastUpdatedEnabled,
 							lastUpdatedPosition,
+							readingTimeEnabled,
+							readingTimeMap,
 							llmsTxtEnabled,
 							descriptionMap,
 							feedbackEnabled: feedbackConfig.enabled,

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

@@ -39,6 +39,15 @@ interface DocsPageClientProps {
   lastModifiedMap?: Record<string, string>;
   /** Direct last-modified value override for the current page. */
   lastModified?: string;
+  /** Map of pathname → reading time in minutes */
+  readingTimeMap?: Record<string, number>;
+  /** Direct reading-time override for the current page. */
+  readingTime?: number | null;
+  /**
+   * Whether path-based reading time values should render by default.
+   * Explicit `readingTime` overrides can still render when this is false.
+   */
+  readingTimeEnabled?: boolean;
   /** Whether to show "Last updated" at all */
   lastUpdatedEnabled?: boolean;
   /** Where to show the "Last updated" date: "footer" (next to Edit on GitHub) or "below-title" */
@@ -78,6 +87,9 @@ declare function DocsPageClient({
   editOnGithubUrl,
   lastModifiedMap,
   lastModified: lastModifiedProp,
+  readingTimeMap,
+  readingTime: readingTimeProp,
+  readingTimeEnabled,
   lastUpdatedEnabled,
   lastUpdatedPosition,
   llmsTxtEnabled,

package/dist/docs-page-client.mjs

@@ -97,6 +97,9 @@ function decodeHashTarget(hash) {
 		return value;
 	}
 }
+function formatReadingTimeLabel(minutes) {
+	return `${Math.max(1, Math.ceil(minutes))} min read`;
+}
 function escapeIdSelector(value) {
 	if (typeof CSS !== "undefined" && typeof CSS.escape === "function") return CSS.escape(value);
 	return value.replace(/["\\.#:[\]>+~(){}^$|*?=!'`\s]/g, "\\$&");
@@ -116,7 +119,7 @@ function injectTitleDecorations(node, { description, belowTitle }) {
 		inserted: false
 	};
 	let inserted = false;
-	const extras = [description, belowTitle].filter(Boolean);
+	const extras = Children.toArray([description, belowTitle].filter(Boolean));
 	if (extras.length === 0) return {
 		node,
 		inserted: false
@@ -131,7 +134,7 @@ function injectTitleDecorations(node, { description, belowTitle }) {
 		if (!isValidElement(current)) return current;
 		if (typeof current.type === "string" && current.type === "h1") {
 			inserted = true;
-			return [current, ...extras];
+			return Children.toArray([current, ...extras]);
 		}
 		const childProps = current.props ?? null;
 		if (childProps?.children === void 0) return current;
@@ -156,9 +159,9 @@ function injectTitleDecorations(node, { description, belowTitle }) {
 }
 function TitleDecorations({ description, belowTitle }) {
 	if (!description && !belowTitle) return null;
-	return /* @__PURE__ */ jsxs(Fragment, { children: [description, belowTitle] });
+	return /* @__PURE__ */ jsx(Fragment, { 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, 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, children }) {
 	const fdTocStyle = tocStyle === "directional" ? "clerk" : void 0;
 	const [toc, setToc] = useState([]);
 	const [titlePortalHost, setTitlePortalHost] = useState(null);
@@ -169,6 +172,8 @@ function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled =
 	const pageDescription = description ?? descriptionMap?.[pathname.replace(/\/$/, "") || "/"];
 	const normalizedPath = (browserPath ?? pathname).replace(/\/$/, "") || "/";
 	const isChangelogRoute = !!(changelogBasePath && (normalizedPath === changelogBasePath || normalizedPath.startsWith(`${changelogBasePath}/`)));
+	const matchedReadingTime = readingTimeMap?.[normalizedPath];
+	const resolvedReadingTime = !isChangelogRoute ? readingTimeProp !== void 0 ? readingTimeProp : readingTimeEnabled ? matchedReadingTime : void 0 : void 0;
 	const effectiveTocEnabled = isChangelogRoute ? false : tocEnabled;
 	const effectiveBreadcrumbEnabled = isChangelogRoute ? false : breadcrumbEnabled;
 	useEffect(() => {
@@ -246,11 +251,24 @@ function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled =
 	const showLastUpdatedBelowTitle = !!lastModified && lastUpdatedPosition === "below-title";
 	const showLastUpdatedInFooter = !!lastModified && lastUpdatedPosition === "footer";
 	const showFooter = !isChangelogRoute && (!!githubFileUrl || showLastUpdatedInFooter || llmsTxtEnabled);
+	const readingTimeBlock = typeof resolvedReadingTime === "number" ? /* @__PURE__ */ jsxs("div", {
+		className: "fd-page-meta not-prose",
+		children: [/* @__PURE__ */ jsx("span", {
+			className: "fd-page-meta-dot",
+			"aria-hidden": "true",
+			children: "·"
+		}), /* @__PURE__ */ jsx("span", {
+			className: "fd-page-meta-item",
+			children: formatReadingTimeLabel(resolvedReadingTime)
+		})]
+	}) : void 0;
 	const titleDescription = pageDescription ? /* @__PURE__ */ jsx("p", {
 		className: "fd-page-description",
 		children: pageDescription
 	}) : void 0;
-	const belowTitleBlock = showLastUpdatedBelowTitle || showActionsBelowTitle ? /* @__PURE__ */ jsxs("div", {
+	const showReadingTimeAboveTitle = !!readingTimeBlock && showActionsAboveTitle;
+	const showReadingTimeBelowTitle = !!readingTimeBlock && !showReadingTimeAboveTitle && (showActionsBelowTitle || showLastUpdatedBelowTitle || !showActions && pageActionsPosition === "below-title");
+	const belowTitleBlock = showLastUpdatedBelowTitle || showActionsBelowTitle || showReadingTimeBelowTitle ? /* @__PURE__ */ jsxs("div", {
 		className: "fd-below-title-block not-prose",
 		children: [
 			showLastUpdatedBelowTitle && /* @__PURE__ */ jsxs("p", {
@@ -268,7 +286,8 @@ function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled =
 					alignment: pageActionsAlignment,
 					githubFileUrl
 				})
-			})
+			}),
+			showReadingTimeBelowTitle && readingTimeBlock
 		]
 	}) : void 0;
 	const { node: decoratedChildren, inserted: titleDecorationsInserted } = injectTitleDecorations(children, {
@@ -318,9 +337,9 @@ function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled =
 				entry,
 				locale: activeLocale
 			}),
-			showActionsAboveTitle && /* @__PURE__ */ jsx("div", {
+			showActionsAboveTitle && /* @__PURE__ */ jsxs("div", {
 				className: "fd-below-title-block not-prose",
-				children: /* @__PURE__ */ jsx("div", {
+				children: [/* @__PURE__ */ jsx("div", {
 					className: "fd-actions-portal",
 					"data-actions-alignment": pageActionsAlignment,
 					children: /* @__PURE__ */ jsx(PageActions, {
@@ -330,8 +349,9 @@ function DocsPageClient({ tocEnabled, tocStyle = "default", breadcrumbEnabled =
 						alignment: pageActionsAlignment,
 						githubFileUrl
 					})
-				})
+				}), readingTimeBlock]
 			}),
+			!showReadingTimeAboveTitle && !showReadingTimeBelowTitle ? readingTimeBlock : null,
 			/* @__PURE__ */ jsxs(DocsBody, {
 				style: {
 					display: "flex",

package/dist/pixel-border/index.mjs

@@ -24,8 +24,8 @@ const PixelBorderUIDefaults = {
 	},
 	typography: { font: {
 		style: {
-			sans: "var(--font-geist-sans, system-ui, -apple-system, sans-serif)",
-			mono: "var(--font-geist-mono, ui-monospace, monospace)"
+			sans: "var(--font-sans, system-ui, -apple-system, sans-serif)",
+			mono: "var(--font-mono, ui-monospace, monospace)"
 		},
 		h1: {
 			size: "2.25rem",

package/dist/reading-time.mjs

@@ -0,0 +1,39 @@
+import matter from "gray-matter";
+
+//#region src/reading-time.ts
+function hasExplicitReadingTime(frontmatter) {
+	return Object.prototype.hasOwnProperty.call(frontmatter ?? {}, "readingTime");
+}
+function normalizeWordsPerMinute(wordsPerMinute) {
+	if (typeof wordsPerMinute !== "number" || !Number.isFinite(wordsPerMinute)) return 220;
+	return Math.max(1, Math.floor(wordsPerMinute));
+}
+function stripNonReadingContent(content) {
+	return content.replace(/(`{3,})[^\n]*\n[\s\S]*?\1/g, " ").replace(/(~{3,})[^\n]*\n[\s\S]*?\1/g, " ").replace(/`[^`\n]+`/g, " ").replace(/!\[[^\]]*\]\([^)]+\)/g, " ").replace(/\[([^\]]+)\]\([^)]+\)/g, " $1 ").replace(/<[^>]+>/g, " ").replace(/\{[^{}]*\}/g, " ").replace(/https?:\/\/\S+/g, " ").replace(/[#>*_~|]/g, " ");
+}
+function estimateReadingTimeMinutes(content, wordsPerMinute) {
+	const wordCount = stripNonReadingContent(content).match(/\b[\p{L}\p{N}][\p{L}\p{N}'’-]*\b/gu)?.length ?? 0;
+	return Math.max(1, Math.ceil(wordCount / normalizeWordsPerMinute(wordsPerMinute)));
+}
+function resolveReadingTimeOptions(readingTime) {
+	if (readingTime === true) return { enabled: true };
+	if (readingTime === false || readingTime === void 0 || readingTime === null) return { enabled: false };
+	if (typeof readingTime !== "object") return { enabled: false };
+	return {
+		enabled: readingTime.enabled !== false,
+		wordsPerMinute: typeof readingTime.wordsPerMinute === "number" && Number.isFinite(readingTime.wordsPerMinute) ? readingTime.wordsPerMinute : void 0
+	};
+}
+function resolveReadingTimeFromContent(frontmatter, content, wordsPerMinute) {
+	const pageData = frontmatter ?? {};
+	if (pageData.readingTime === false) return null;
+	if (typeof pageData.readingTime === "number" && Number.isFinite(pageData.readingTime)) return Math.max(1, Math.ceil(pageData.readingTime));
+	return estimateReadingTimeMinutes(content, wordsPerMinute);
+}
+function resolvePageReadingTime(frontmatter, content, options) {
+	if (!(options?.enabledByDefault ?? false) && !hasExplicitReadingTime(frontmatter)) return;
+	return resolveReadingTimeFromContent(frontmatter, content, options?.wordsPerMinute);
+}
+
+//#endregion
+export { resolvePageReadingTime, resolveReadingTimeOptions };

package/dist/tanstack-layout.d.mts

@@ -28,6 +28,7 @@ interface TanstackDocsLayoutProps {
   tree: TreeRoot;
   locale?: string;
   description?: string;
+  readingTime?: number | null;
   lastModified?: string;
   editOnGithubUrl?: string;
   children: ReactNode;
@@ -37,6 +38,7 @@ declare function TanstackDocsLayout({
   tree,
   locale,
   description,
+  readingTime,
   lastModified,
   editOnGithubUrl,
   children

package/dist/tanstack-layout.mjs

@@ -2,6 +2,7 @@ import { withLangInUrl } from "./i18n.mjs";
 import { DocsPageClient } from "./docs-page-client.mjs";
 import { DocsAIFeatures } from "./docs-ai-features.mjs";
 import { DocsCommandSearch } from "./docs-command-search.mjs";
+import { resolveReadingTimeOptions } from "./reading-time.mjs";
 import { SidebarSearchWithAI } from "./sidebar-search-ai.mjs";
 import { LocaleThemeControl } from "./locale-theme-control.mjs";
 import { DocsLayout } from "fumadocs-ui/layouts/docs";
@@ -205,7 +206,7 @@ function resolveFeedbackConfig(feedback) {
 function ForcedThemeScript({ theme }) {
 	return /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: `document.documentElement.classList.remove('light','dark');document.documentElement.classList.add('${theme === "light" || theme === "dark" ? theme : "light"}');` } });
 }
-function TanstackDocsLayout({ config, tree, locale, description, lastModified, editOnGithubUrl, children }) {
+function TanstackDocsLayout({ config, tree, locale, description, readingTime, lastModified, editOnGithubUrl, children }) {
 	const tocConfig = config.theme?.ui?.layout?.toc;
 	const tocEnabled = tocConfig?.enabled !== false;
 	const tocStyle = tocConfig?.style;
@@ -232,6 +233,7 @@ function TanstackDocsLayout({ config, tree, locale, description, lastModified, e
 	const lastUpdatedRaw = config.lastUpdated;
 	const lastUpdatedEnabled = lastUpdatedRaw !== false && (typeof lastUpdatedRaw !== "object" || lastUpdatedRaw.enabled !== false);
 	const lastUpdatedPosition = typeof lastUpdatedRaw === "object" ? lastUpdatedRaw.position ?? "footer" : "footer";
+	const readingTimeEnabled = resolveReadingTimeOptions(config.readingTime).enabled;
 	const llmsTxtEnabled = resolveBool(config.llmsTxt);
 	const feedbackConfig = resolveFeedbackConfig(config.feedback);
 	const staticExport = !!config.staticExport;
@@ -339,6 +341,8 @@ function TanstackDocsLayout({ config, tree, locale, description, lastModified, e
 						lastUpdatedEnabled,
 						lastUpdatedPosition,
 						lastModified,
+						readingTimeEnabled,
+						readingTime: typeof readingTime === "number" ? readingTime : void 0,
 						llmsTxtEnabled,
 						description,
 						feedbackEnabled: feedbackConfig.enabled,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/theme",
-  "version": "0.1.45",
+  "version": "0.1.48",
   "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.45"
+    "@farming-labs/docs": "0.1.48"
   },
   "peerDependencies": {
     "@farming-labs/docs": ">=0.0.1",

package/styles/base.css

@@ -171,6 +171,49 @@ figure.shiki:has(figcaption) figcaption {
 
 /* ─── Page description (frontmatter) ─────────────────────────────────── */
 
+.fd-page-meta {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.375rem;
+  margin-bottom: 0.75rem;
+}
+
+.fd-page-meta-dot {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font-family: var(
+    --fd-font-mono,
+    ui-monospace,
+    SFMono-Regular,
+    "SF Mono",
+    Menlo,
+    Consolas,
+    monospace
+  );
+  font-size: 0.8rem;
+  line-height: 1;
+  color: color-mix(in srgb, var(--color-fd-muted-foreground) 78%, transparent);
+}
+
+.fd-page-meta-item {
+  font-family: var(
+    --fd-font-mono,
+    ui-monospace,
+    SFMono-Regular,
+    "SF Mono",
+    Menlo,
+    Consolas,
+    monospace
+  );
+  font-size: 0.6875rem;
+  font-weight: 500;
+  letter-spacing: 0;
+  text-transform: uppercase;
+  color: var(--color-fd-muted-foreground);
+}
+
 .fd-page-description {
   margin-bottom: 1rem;
   font-size: 1.125rem;