@farming-labs/docs 0.1.81 → 0.1.83

package/dist/reading-time-pKUeloSI.mjs

@@ -0,0 +1,315 @@
+import matter from "gray-matter";
+
+//#region src/define-docs.ts
+/**
+* Define docs configuration. Validates and returns the config.
+*/
+function defineDocs(config) {
+	return {
+		entry: config.entry ?? "docs",
+		contentDir: config.contentDir,
+		i18n: config.i18n,
+		theme: config.theme,
+		nav: config.nav,
+		github: config.github,
+		themeToggle: config.themeToggle,
+		breadcrumb: config.breadcrumb,
+		sidebar: config.sidebar,
+		components: config.components,
+		analytics: config.analytics,
+		observability: config.observability,
+		onCopyClick: config.onCopyClick,
+		feedback: config.feedback,
+		search: config.search,
+		mcp: config.mcp,
+		icons: config.icons,
+		pageActions: config.pageActions,
+		lastUpdated: config.lastUpdated,
+		readingTime: config.readingTime,
+		llmsTxt: config.llmsTxt,
+		sitemap: config.sitemap,
+		robots: config.robots,
+		ai: config.ai,
+		ordering: config.ordering,
+		metadata: config.metadata,
+		og: config.og,
+		changelog: config.changelog,
+		apiReference: config.apiReference,
+		agent: config.agent
+	};
+}
+
+//#endregion
+//#region src/changelog.ts
+function normalizePathSegment(value, fallback) {
+	return (value ?? fallback).trim().replace(/^\/+|\/+$/g, "") || fallback;
+}
+function normalizeContentDir(value) {
+	const trimmed = value?.trim();
+	if (!trimmed) return "changelog";
+	return trimmed.replace(/\/+$/, "") || "changelog";
+}
+function resolveChangelogConfig(value) {
+	if (value === false || value === void 0) return {
+		enabled: false,
+		path: "changelog",
+		contentDir: "changelog",
+		title: "Changelog",
+		description: void 0,
+		search: true
+	};
+	if (value === true) return {
+		enabled: true,
+		path: "changelog",
+		contentDir: "changelog",
+		title: "Changelog",
+		description: void 0,
+		search: true
+	};
+	return {
+		enabled: value.enabled !== false,
+		path: normalizePathSegment(value.path, "changelog"),
+		contentDir: normalizeContentDir(value.contentDir),
+		title: value.title?.trim() || "Changelog",
+		description: value.description?.trim() || void 0,
+		search: value.search !== false,
+		actionsComponent: value.actionsComponent
+	};
+}
+
+//#endregion
+//#region src/utils.ts
+/**
+* Deep merge utility for theme overrides.
+* Merges objects recursively; later values override earlier ones.
+*/
+function deepMerge(target, ...sources) {
+	if (!sources.length) return target;
+	const source = sources.shift();
+	if (!source) return target;
+	const result = { ...target };
+	for (const key of Object.keys(source)) {
+		const sourceVal = source[key];
+		const targetVal = result[key];
+		if (sourceVal && typeof sourceVal === "object" && !Array.isArray(sourceVal) && targetVal && typeof targetVal === "object" && !Array.isArray(targetVal)) result[key] = deepMerge(targetVal, sourceVal);
+		else if (sourceVal !== void 0) result[key] = sourceVal;
+	}
+	if (sources.length) return deepMerge(result, ...sources);
+	return result;
+}
+
+//#endregion
+//#region src/create-theme.ts
+/**
+* Create a theme preset factory.
+*
+* Returns a function that accepts optional overrides and deep-merges them
+* with the base theme defaults. This is the same pattern used by the
+* built-in `fumadocs()`, `darksharp()`, and `pixelBorder()` presets.
+*
+* @param baseTheme - The default theme configuration
+* @returns A factory function `(overrides?) => DocsTheme`
+*
+* @example
+* ```ts
+* import { createTheme } from "@farming-labs/docs";
+*
+* export const myTheme = createTheme({
+*   name: "my-theme",
+*   ui: {
+*     colors: { primary: "#6366f1" },
+*     layout: { contentWidth: 800 },
+*   },
+* });
+* ```
+*/
+function createTheme(baseTheme) {
+	return function themeFactory(overrides = {}) {
+		const merged = deepMerge(baseTheme, overrides);
+		if (overrides.ui?.colors) merged._userColorOverrides = { ...overrides.ui.colors };
+		return merged;
+	};
+}
+/**
+* Extend an existing theme preset with additional defaults.
+*
+* Useful when you want to build on top of an existing theme (e.g. fumadocs)
+* rather than starting from scratch.
+*
+* @example
+* ```ts
+* import { extendTheme } from "@farming-labs/docs";
+* import { fumadocs } from "@farming-labs/theme/default";
+*
+* // Start with fumadocs defaults, override some values
+* export const myTheme = extendTheme(fumadocs(), {
+*   name: "my-custom-fumadocs",
+*   ui: { colors: { primary: "#22c55e" } },
+* });
+* ```
+*/
+function extendTheme(baseTheme, extensions) {
+	return deepMerge(baseTheme, extensions);
+}
+
+//#endregion
+//#region src/i18n.ts
+function normalizeSegment(value) {
+	return value.replace(/^\/+|\/+$/g, "");
+}
+function splitSegments(value) {
+	const cleaned = normalizeSegment(value);
+	return cleaned ? cleaned.split("/").filter(Boolean) : [];
+}
+function resolveDocsI18n(config) {
+	if (!config || !Array.isArray(config.locales)) return null;
+	const locales = Array.from(new Set(config.locales.map((l) => l.trim()).filter(Boolean)));
+	if (locales.length === 0) return null;
+	return {
+		locales,
+		defaultLocale: config.defaultLocale && locales.includes(config.defaultLocale) ? config.defaultLocale : locales[0]
+	};
+}
+function resolveDocsLocale(searchParams, i18n) {
+	if (!i18n) return void 0;
+	const raw = searchParams.get("lang") ?? searchParams.get("locale");
+	if (!raw) return void 0;
+	if (i18n.locales.includes(raw)) return raw;
+	return i18n.defaultLocale;
+}
+function resolveDocsPath(pathname, entry) {
+	const entryBase = normalizeSegment(entry || "docs") || "docs";
+	const entryParts = splitSegments(entryBase);
+	const pathParts = splitSegments(pathname);
+	let rest = pathParts;
+	if (entryParts.length > 0) {
+		if (pathParts.slice(0, entryParts.length).join("/") === entryParts.join("/")) rest = pathParts.slice(entryParts.length);
+	}
+	return {
+		slug: rest.join("/"),
+		entryPath: entryBase
+	};
+}
+
+//#endregion
+//#region src/metadata.ts
+/**
+* Resolve page title using metadata titleTemplate.
+* %s is replaced with page title.
+*/
+function resolveTitle(pageTitle, metadata) {
+	return (metadata?.titleTemplate ?? "%s").replace("%s", pageTitle);
+}
+/**
+* Resolve OG image URL for a page.
+* Prefers page.openGraph.images[0], then page.ogImage, then config endpoint/default.
+*/
+function resolveOGImage(page, ogConfig, baseUrl) {
+	if (page.openGraph?.images?.length) return resolveImageUrl(page.openGraph.images[0].url, baseUrl);
+	if (!ogConfig?.enabled) return void 0;
+	if (page.ogImage) return resolveImageUrl(page.ogImage, baseUrl);
+	if (ogConfig.type === "dynamic" && ogConfig.endpoint) return `${baseUrl ?? ""}${ogConfig.endpoint}`;
+	return ogConfig.defaultImage;
+}
+function resolveImageUrl(url, baseUrl) {
+	if (url.startsWith("/") || url.startsWith("http")) return url;
+	const base = baseUrl ?? "";
+	return `${base}${base.length > 0 && !base.endsWith("/") ? "/" : ""}${url}`;
+}
+/**
+* Build the Open Graph metadata object for a page.
+* When the page has openGraph in frontmatter, uses it (with title/description filled from page if omitted).
+* Otherwise uses ogImage or config (dynamic endpoint / defaultImage).
+*/
+function buildPageOpenGraph(page, ogConfig, baseUrl) {
+	if (page.openGraph) {
+		const images = page.openGraph.images?.length ? page.openGraph.images.map((img) => ({
+			url: resolveImageUrl(img.url, baseUrl),
+			width: img.width ?? 1200,
+			height: img.height ?? 630
+		})) : void 0;
+		return {
+			title: page.openGraph.title ?? page.title,
+			description: page.openGraph.description ?? page.description,
+			...images && { images }
+		};
+	}
+	const url = resolveOGImage(page, ogConfig, baseUrl);
+	if (!url) return void 0;
+	return {
+		title: page.title,
+		...page.description && { description: page.description },
+		images: [{
+			url,
+			width: 1200,
+			height: 630
+		}]
+	};
+}
+/**
+* Build the Twitter card metadata object for a page.
+* When the page has twitter in frontmatter, uses it.
+* Otherwise builds from ogImage or config (dynamic endpoint).
+*/
+function buildPageTwitter(page, ogConfig, baseUrl) {
+	if (page.twitter) {
+		const images = page.twitter.images?.length ? page.twitter.images.map((url) => resolveImageUrl(url, baseUrl)) : void 0;
+		return {
+			...page.twitter.card && { card: page.twitter.card },
+			...page.twitter.title !== void 0 && { title: page.twitter.title },
+			...page.twitter.description !== void 0 && { description: page.twitter.description },
+			...images && { images }
+		};
+	}
+	const url = resolveOGImage(page, ogConfig, baseUrl);
+	if (!url) return void 0;
+	return {
+		card: "summary_large_image",
+		title: page.title,
+		...page.description && { description: page.description },
+		images: [url]
+	};
+}
+
+//#endregion
+//#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);
+}
+function resolveReadingTimeFromSource(source, wordsPerMinute) {
+	const { data, content } = matter(source);
+	return resolveReadingTimeFromContent(data, content, wordsPerMinute);
+}
+
+//#endregion
+export { defineDocs as _, resolveReadingTimeOptions as a, resolveOGImage as c, resolveDocsLocale as d, resolveDocsPath as f, resolveChangelogConfig as g, deepMerge as h, resolveReadingTimeFromSource as i, resolveTitle as l, extendTheme as m, resolvePageReadingTime as n, buildPageOpenGraph as o, createTheme as p, resolveReadingTimeFromContent as r, buildPageTwitter as s, estimateReadingTimeMinutes as t, resolveDocsI18n as u };

package/dist/related-BNj_NdHq.mjs

@@ -0,0 +1,50 @@
+//#region src/related.ts
+function normalizeDocsRelated(value) {
+	if (!Array.isArray(value)) return [];
+	const seen = /* @__PURE__ */ new Set();
+	const links = [];
+	for (const item of value) {
+		const parsed = parseRelatedInput(item);
+		if (!parsed) continue;
+		const dedupeKey = normalizeRelatedLookupPath(parsed.href) ?? parsed.href;
+		if (seen.has(dedupeKey)) continue;
+		seen.add(dedupeKey);
+		links.push({ href: parsed.href });
+	}
+	return links;
+}
+function renderDocsRelatedMarkdownLines(related) {
+	if (!related?.length) return [];
+	return [`Related: ${related.map((link) => normalizeInlineText(link.href)).join(", ")}`];
+}
+function parseRelatedInput(value) {
+	if (typeof value === "string") {
+		const href = cleanString(value);
+		return href ? { href } : null;
+	}
+	return null;
+}
+function cleanString(value) {
+	if (typeof value !== "string") return void 0;
+	return value.trim() || void 0;
+}
+function normalizeRelatedLookupPath(value) {
+	const trimmed = value.trim();
+	if (!trimmed) return null;
+	let pathname = trimmed;
+	try {
+		pathname = new URL(trimmed, "https://docs.local").pathname;
+	} catch {
+		pathname = trimmed.split(/[?#]/, 1)[0] ?? trimmed;
+	}
+	pathname = pathname.replace(/\/+/g, "/").replace(/\.md$/i, "");
+	if (!pathname.startsWith("/")) pathname = `/${pathname}`;
+	if (pathname !== "/") pathname = pathname.replace(/\/+$/, "");
+	return pathname;
+}
+function normalizeInlineText(value) {
+	return value.replace(/\s+/g, " ").trim();
+}
+
+//#endregion
+export { renderDocsRelatedMarkdownLines as n, normalizeDocsRelated as t };