boltdocs 3.3.5 → 3.4.0

package/dist/{link-vZjmD-es.cjs → link-Xb69Oy2F.cjs}

@@ -3,8 +3,9 @@
  * Copyright (c) 2026 Jesus Alcala
  * Licensed under the MIT License.
  */
-const require_router = require('./router-C3kygdRK.cjs');
+const require_router = require('./router-DKC0Lu0n.cjs');
 let react = require("react");
+react = require_router.__toESM(react);
 let react_jsx_runtime = require("react/jsx-runtime");
 let clsx = require("clsx");
 let tailwind_merge = require("tailwind-merge");
@@ -22,10 +23,10 @@ function getSavedPrefs() {
 		return {};
 	}
 }
-const globalRegistry$1 = globalThis;
-const existingContext = globalRegistry$1[BOLTDOCS_CONTEXT_SYMBOL];
+const globalRegistry = globalThis;
+const existingContext = globalRegistry[BOLTDOCS_CONTEXT_SYMBOL];
 const BoltdocsContext = existingContext || (0, react.createContext)(void 0);
-if (!existingContext) Reflect.set(globalRegistry$1, BOLTDOCS_CONTEXT_SYMBOL, BoltdocsContext);
+if (!existingContext) Reflect.set(globalRegistry, BOLTDOCS_CONTEXT_SYMBOL, BoltdocsContext);
 function BoltdocsProvider({ children, initialLocale = "", initialVersion = "" }) {
 	const [locale, setLocaleState] = (0, react.useState)(() => {
 		if (initialLocale) return initialLocale;
@@ -48,7 +49,7 @@ function BoltdocsProvider({ children, initialLocale = "", initialVersion = "" })
 			return newL;
 		});
 		if (typeof globalThis !== "undefined") Reflect.set(globalThis, BOLTDOCS_INSTANCE_SYMBOL, {
-			...globalThis[BOLTDOCS_INSTANCE_SYMBOL],
+			...globalRegistry[BOLTDOCS_INSTANCE_SYMBOL],
 			currentLocale: newL
 		});
 		if (typeof window !== "undefined") try {
@@ -66,7 +67,7 @@ function BoltdocsProvider({ children, initialLocale = "", initialVersion = "" })
 			return newV;
 		});
 		if (typeof globalThis !== "undefined") Reflect.set(globalThis, BOLTDOCS_INSTANCE_SYMBOL, {
-			...globalThis[BOLTDOCS_INSTANCE_SYMBOL],
+			...globalRegistry[BOLTDOCS_INSTANCE_SYMBOL],
 			currentVersion: newV
 		});
 		if (typeof window !== "undefined") try {
@@ -105,41 +106,6 @@ function useBoltdocsContext() {
 	return context;
 }
 
-//#endregion
-//#region src/client/app/config-context.tsx
-/**
-* Context for the global documentation configuration.
-* Using a global singleton pattern to survive dual-package or duplicated-code hazards.
-*/
-const CONFIG_CONTEXT_SYMBOL = Symbol.for("__BDOCS_CONFIG_CONTEXT__");
-const CONFIG_INSTANCE_SYMBOL = Symbol.for("__BDOCS_CONFIG_INSTANCE__");
-const globalRegistry = globalThis;
-const existingConfigContext = globalRegistry[CONFIG_CONTEXT_SYMBOL];
-const ConfigContext = existingConfigContext || (0, react.createContext)(null);
-if (!existingConfigContext) globalRegistry[CONFIG_CONTEXT_SYMBOL] = ConfigContext;
-/**
-* Hook to access the Boltdocs configuration when one is available.
-*
-* Low-level primitives such as icons can also be rendered standalone (for
-* example in a component preview or a unit test), so they must not be forced
-* to mount the full application provider just to render an inline SVG.
-*/
-function useOptionalConfig() {
-	const context = (0, react.use)(ConfigContext);
-	if (context) return context;
-	const globalConfig = globalRegistry[CONFIG_INSTANCE_SYMBOL];
-	if (globalConfig) return globalConfig;
-	return null;
-}
-/**
-* Hook to access the Boltdocs configuration.
-*/
-function useConfig() {
-	const config = useOptionalConfig();
-	if (!config) throw new Error("useConfig must be used within a ConfigProvider");
-	return config;
-}
-
 //#endregion
 //#region src/client/components/ui-base/icons.tsx
 var icons_exports = /* @__PURE__ */ require_router.__exportAll({
@@ -547,6 +513,66 @@ const FaceBad = createIcon("FaceBad", /* @__PURE__ */ (0, react_jsx_runtime.jsxs
 	})
 ] }));
 
+//#endregion
+//#region src/client/router/prefetch-viewport.ts
+/**
+* Viewport-triggered route prefetching.
+*
+* Hover prefetching only warms a link once the pointer commits to it, which
+* misses the most common case: a reader scrolls the sidebar, reads a heading,
+* and clicks without ever hovering. Every destination they are plausibly
+* heading for sits on screen, untouched.
+*
+* A single shared `IntersectionObserver` watches anchors registered by
+* `Link` and fires the normal prefetch pipeline when one becomes visible, so
+* the route chunk and its loader data are already cached by the time the click
+* lands. Hover keeps working and still wins: whichever signal arrives first
+* populates `prefetchCache`, and the other is a cache hit.
+*
+* The existing prefetch queue bounds the cost (two in flight, a shallow
+* backlog) and drops work when saturated, so this stays opportunistic
+* exactly like hover prefetching is.
+*/
+/**
+* Start slightly before the link is on screen so a short scroll already feels
+* instant, without warming the whole page below the fold.
+*/
+const VIEWPORT_PREFETCH_MARGIN = "200px 0px";
+let observer = null;
+const pending = /* @__PURE__ */ new WeakMap();
+function getObserver() {
+	if (typeof window === "undefined") return null;
+	if (typeof IntersectionObserver === "undefined") return null;
+	if (observer) return observer;
+	observer = new IntersectionObserver((entries) => {
+		for (const entry of entries) {
+			if (!entry.isIntersecting) continue;
+			const run = pending.get(entry.target);
+			if (!run) continue;
+			observer?.unobserve(entry.target);
+			pending.delete(entry.target);
+			run();
+		}
+	}, { rootMargin: VIEWPORT_PREFETCH_MARGIN });
+	return observer;
+}
+/**
+* Watches `element` and invokes `run` once it approaches the viewport.
+*
+* Returns a cleanup function. Safe to call during SSR, where it is a no-op.
+*/
+function observeForPrefetch(element, run) {
+	if (!element) return () => {};
+	const target = getObserver();
+	if (!target) return () => {};
+	pending.set(element, run);
+	target.observe(element);
+	return () => {
+		target.unobserve(element);
+		pending.delete(element);
+	};
+}
+
 //#endregion
 //#region src/client/utils/path.ts
 /**
@@ -573,13 +599,58 @@ function resolvePublicAssetUrl(value, base) {
 
 //#endregion
 //#region src/client/app/routes-context.tsx
+const emptyRouteIndex = {
+	byPath: /* @__PURE__ */ new Map(),
+	hintsByPath: /* @__PURE__ */ new Map(),
+	collectionNames: [],
+	byCollectionPath: /* @__PURE__ */ new Map(),
+	countsByFilePath: /* @__PURE__ */ new Map()
+};
+function getCollectionPathKey(route) {
+	if (!route.collection) return void 0;
+	const parts = normalizePath(route.path).split("/").filter(Boolean);
+	const collectionIndex = parts.indexOf(route.collection);
+	if (collectionIndex < 0) return void 0;
+	return `/${parts.slice(collectionIndex).join("/")}`;
+}
+/** Build all client route lookup structures in one cached pass. */
+function createRouteIndex(routes) {
+	const byPath = /* @__PURE__ */ new Map();
+	const hintsByPath = /* @__PURE__ */ new Map();
+	const byCollectionPath = /* @__PURE__ */ new Map();
+	const countsByFilePath = /* @__PURE__ */ new Map();
+	const collectionNames = /* @__PURE__ */ new Set();
+	for (const route of routes) {
+		if (!route.path) continue;
+		const path = normalizePath(route.path);
+		byPath.set(path, route);
+		hintsByPath.set(path, {
+			path: route.path,
+			kind: route.collection ? "collection" : void 0,
+			collection: route.collection
+		});
+		countsByFilePath.set(route.filePath, (countsByFilePath.get(route.filePath) || 0) + 1);
+		if (route.collection) {
+			collectionNames.add(route.collection);
+			const collectionPath = getCollectionPathKey(route);
+			if (collectionPath) {
+				const variants = byCollectionPath.get(collectionPath) || [];
+				variants.push(route);
+				byCollectionPath.set(collectionPath, variants);
+			}
+		}
+	}
+	return {
+		byPath,
+		hintsByPath,
+		byCollectionPath,
+		countsByFilePath,
+		collectionNames: [...collectionNames]
+	};
+}
 const RoutesContext = (0, react.createContext)({
 	routes: [],
-	index: {
-		byPath: /* @__PURE__ */ new Map(),
-		hintsByPath: /* @__PURE__ */ new Map(),
-		collectionNames: []
-	}
+	index: emptyRouteIndex
 });
 /**
 * Hook to access the processed routes list from the closest provider.
@@ -592,27 +663,7 @@ function useRoutesContext() {
 */
 function RoutesProvider({ routes: initialRoutes, children }) {
 	const [routes, setRoutes] = (0, react.useState)(initialRoutes);
-	const index = (0, react.useMemo)(() => {
-		const byPath = /* @__PURE__ */ new Map();
-		const hintsByPath = /* @__PURE__ */ new Map();
-		const collectionNames = /* @__PURE__ */ new Set();
-		for (const route of routes) {
-			if (!route.path) continue;
-			const path = normalizePath(route.path);
-			byPath.set(path, route);
-			hintsByPath.set(path, {
-				path: route.path,
-				kind: route.collection ? "collection" : void 0,
-				collection: route.collection
-			});
-			if (route.collection) collectionNames.add(route.collection);
-		}
-		return {
-			byPath,
-			hintsByPath,
-			collectionNames: [...collectionNames]
-		};
-	}, [routes]);
+	const index = (0, react.useMemo)(() => createRouteIndex(routes), [routes]);
 	(0, react.useEffect)(() => {
 		if (!{}.hot) return;
 		const handler = (payload) => {
@@ -643,7 +694,7 @@ function RoutesProvider({ routes: initialRoutes, children }) {
 //#endregion
 //#region src/client/hooks/use-localized-to.ts
 function useLocalizedTo(to) {
-	const config = useConfig();
+	const config = require_router.useConfig();
 	const routeContext = useRoutesContext();
 	const routeIndex = routeContext.index || {
 		byPath: new Map(routeContext.routes.map((route) => [route.path, route])),
@@ -706,74 +757,6 @@ function cn(...inputs) {
 	return (0, tailwind_merge.twMerge)((0, clsx.clsx)(inputs));
 }
 
-//#endregion
-//#region src/client/view-transitions.ts
-function resolveOptions(options) {
-	if (options?.enabled === false) return void 0;
-	return {
-		enabled: true,
-		...options?.types?.length ? { types: options.types } : {}
-	};
-}
-function isNativeViewTransitionSupported() {
-	return typeof document !== "undefined" && typeof document.startViewTransition === "function";
-}
-/**
-* Starts a native document transition when the browser supports it. On older
-* browsers, the update still runs normally and the function returns null.
-*/
-function startViewTransition(update, options) {
-	const resolved = resolveOptions(options);
-	if (typeof document === "undefined" || resolved?.enabled !== true) {
-		update();
-		return null;
-	}
-	const start = document.startViewTransition;
-	if (!start) {
-		update();
-		return null;
-	}
-	const types = options?.types;
-	return start.call(document, {
-		update,
-		...types?.length ? { types } : {}
-	});
-}
-/**
-* Returns a transition-aware runner that follows the project's experimental
-* configuration. It is safe to use in custom layouts and external pages.
-*
-* The returned value is callable for backwards compatibility:
-* `transition(() => setState(...))`. It also exposes `run` and `start` aliases
-* for discoverability in editor autocomplete.
-*/
-function useViewTransition() {
-	const configured = useOptionalConfig()?.experimental?.viewTransitions;
-	const enabled = configured === true || typeof configured === "object" && configured.enabled === true;
-	const supported = isNativeViewTransitionSupported();
-	const run = (0, react.useCallback)((update, options) => {
-		if (!enabled && options?.enabled !== true) {
-			update();
-			return null;
-		}
-		const configuredTypes = typeof configured === "object" ? configured.types : void 0;
-		return startViewTransition(update, {
-			...options,
-			types: options?.types || configuredTypes
-		});
-	}, [configured, enabled]);
-	return (0, react.useMemo)(() => Object.assign(run, {
-		run,
-		start: run,
-		enabled,
-		supported
-	}), [
-		enabled,
-		run,
-		supported
-	]);
-}
-
 //#endregion
 //#region src/client/components/primitives/link.tsx
 /**
@@ -785,7 +768,7 @@ function Link(props) {
 	const target = href ?? to ?? "";
 	const navigate = require_router.useNavigate();
 	const prefetchRoute = require_router.usePrefetch();
-	const runTransition = useViewTransition();
+	const runTransition = require_router.useViewTransition();
 	const localizedHref = useLocalizedTo(target);
 	const handleClick = (e) => {
 		onClick?.(e);
@@ -801,7 +784,7 @@ function Link(props) {
 		}
 	};
 	const handlePrefetch = () => {
-		if (prefetch === "hover" && localizedHref) prefetchRoute(localizedHref);
+		if (prefetch !== "none" && localizedHref) prefetchRoute(localizedHref);
 	};
 	const handleMouseEnter = (e) => {
 		onMouseEnter?.(e);
@@ -811,9 +794,25 @@ function Link(props) {
 		onFocus?.(e);
 		handlePrefetch();
 	};
+	const anchorRef = react.default.useRef(null);
+	const setRef = react.default.useCallback((node) => {
+		anchorRef.current = node;
+		if (typeof ref === "function") ref(node);
+		else if (ref) ref.current = node;
+	}, [ref]);
+	react.default.useEffect(() => {
+		if (prefetch !== "viewport" || !localizedHref) return;
+		return observeForPrefetch(anchorRef.current, () => {
+			prefetchRoute(localizedHref);
+		});
+	}, [
+		prefetch,
+		localizedHref,
+		prefetchRoute
+	]);
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("a", {
 		...rest,
-		ref,
+		ref: setRef,
 		href: localizedHref,
 		target: linkTarget,
 		download,
@@ -906,12 +905,6 @@ Object.defineProperty(exports, 'CircleHelp', {
     return CircleHelp;
   }
 });
-Object.defineProperty(exports, 'ConfigContext', {
-  enumerable: true,
-  get: function () {
-    return ConfigContext;
-  }
-});
 Object.defineProperty(exports, 'Copy', {
   enumerable: true,
   get: function () {
@@ -1074,6 +1067,12 @@ Object.defineProperty(exports, 'cn', {
     return cn;
   }
 });
+Object.defineProperty(exports, 'createRouteIndex', {
+  enumerable: true,
+  get: function () {
+    return createRouteIndex;
+  }
+});
 Object.defineProperty(exports, 'icons_exports', {
   enumerable: true,
   get: function () {
@@ -1092,45 +1091,21 @@ Object.defineProperty(exports, 'resolvePublicAssetUrl', {
     return resolvePublicAssetUrl;
   }
 });
-Object.defineProperty(exports, 'startViewTransition', {
-  enumerable: true,
-  get: function () {
-    return startViewTransition;
-  }
-});
 Object.defineProperty(exports, 'useBoltdocsContext', {
   enumerable: true,
   get: function () {
     return useBoltdocsContext;
   }
 });
-Object.defineProperty(exports, 'useConfig', {
-  enumerable: true,
-  get: function () {
-    return useConfig;
-  }
-});
 Object.defineProperty(exports, 'useLocalizedTo', {
   enumerable: true,
   get: function () {
     return useLocalizedTo;
   }
 });
-Object.defineProperty(exports, 'useOptionalConfig', {
-  enumerable: true,
-  get: function () {
-    return useOptionalConfig;
-  }
-});
 Object.defineProperty(exports, 'useRoutesContext', {
   enumerable: true,
   get: function () {
     return useRoutesContext;
   }
-});
-Object.defineProperty(exports, 'useViewTransition', {
-  enumerable: true,
-  get: function () {
-    return useViewTransition;
-  }
 });

package/dist/{mdx-D0Absdq5.cjs → mdx-BCOrMd-P.cjs}

@@ -3,9 +3,9 @@
  * Copyright (c) 2026 Jesus Alcala
  * Licensed under the MIT License.
  */
-const require_router = require('./router-C3kygdRK.cjs');
-const require_link = require('./link-vZjmD-es.cjs');
-const require_image = require('./image-Hnaa2bJd.cjs');
+const require_router = require('./router-DKC0Lu0n.cjs');
+const require_link = require('./link-Xb69Oy2F.cjs');
+const require_image = require('./image-Bke2ojW1.cjs');
 let react = require("react");
 let react_jsx_runtime = require("react/jsx-runtime");
 let react_aria_components = require("react-aria-components");
@@ -281,6 +281,18 @@ function useCopyButton() {
 //#endregion
 //#region src/client/components/mdx/use-expandable.ts
 /**
+* Counts the rendered lines of a pre-rendered Shiki block.
+*
+* `data-highlighted-html` holds the same markup the server writes, so the count
+* is available before the DOM exists. Returns 0 when there is no HTML, which
+* leaves the caller on the DOM-measured path.
+*/
+function countHighlightedLines(highlightedHtml) {
+	if (!highlightedHtml) return 0;
+	const spans = highlightedHtml.split("<span class=\"line\"").length - 1;
+	return spans > 0 ? spans : highlightedHtml.split("\n").length;
+}
+/**
 * Expand / collapse behavior for long code blocks. Measures the rendered code
 * through `preRef` and exposes whether the block is expandable, whether it
 * should be visually truncated, and a toggle handler.
@@ -288,7 +300,7 @@ function useCopyButton() {
 function useExpandable(options = {}) {
 	const { children, highlightedHtml, maxLines = 6 } = options;
 	const [isExpanded, setIsExpanded] = (0, react.useState)(false);
-	const [isExpandable, setIsExpandable] = (0, react.useState)(false);
+	const [isExpandable, setIsExpandable] = (0, react.useState)(countHighlightedLines(highlightedHtml) > maxLines);
 	const preRef = (0, react.useRef)(null);
 	const shouldTruncate = isExpandable && !isExpanded;
 	const toggle = () => setIsExpanded((prev) => !prev);
@@ -326,7 +338,7 @@ function useExpandable(options = {}) {
 function useCodeBlockFeedback(options = {}) {
 	const { plain = false, lang = "", submitFeedback } = options;
 	const [rated, setRated] = (0, react.useState)(null);
-	const customConfig = require_link.useConfig().integrations?.feedback?.custom;
+	const customConfig = require_router.useConfig().integrations?.feedback?.custom;
 	const enabled = !!(customConfig?.enabled && !plain);
 	return {
 		rated,
@@ -577,6 +589,46 @@ function Cards({ children, className, cols = 2, ...props }) {
 	});
 }
 
+//#endregion
+//#region src/client/utils/date.ts
+/**
+* Deterministic date formatting for server-rendered output.
+*
+* `toLocaleDateString` with no locale resolves against the *runtime* default,
+* which is not the same in Node and in a browser: the server rendered
+* "26 de septiembre de 2026" from an `es` system locale while the client
+* produced "September 26, 2026". That is a text mismatch during hydration and
+* React throws away the server HTML and re-renders the whole page.
+*
+* The time zone has to be pinned for the same reason. A frontmatter date such
+* as `2026-09-27` parses as UTC midnight, so any zone behind UTC renders the
+* previous day and any zone ahead renders the correct one, which is a second,
+* environment-dependent mismatch.
+*
+* Both are therefore explicit here. Callers that genuinely want a different
+* locale can pass one, and it is still deterministic because it is fixed in
+* the markup rather than inferred.
+*/
+const DEFAULT_LOCALE = "en-US";
+const DEFAULT_TIME_ZONE = "UTC";
+/**
+* Formats a date as a stable, locale- and zone-pinned string.
+*
+* Returns an empty string for values that are not real dates so callers can
+* render nothing rather than "Invalid Date".
+*/
+function formatDeterministicDate(date, options = {}) {
+	if (date === void 0 || date === null || date === "") return "";
+	const parsed = date instanceof Date ? date : new Date(date);
+	if (Number.isNaN(parsed.getTime())) return "";
+	return parsed.toLocaleDateString(options.locale ?? DEFAULT_LOCALE, {
+		year: "numeric",
+		month: options.month ?? "long",
+		day: options.day ?? "numeric",
+		timeZone: options.timeZone ?? DEFAULT_TIME_ZONE
+	});
+}
+
 //#endregion
 //#region src/client/components/mdx/last-updated.tsx
 /**
@@ -587,11 +639,7 @@ function LastUpdated({ date, className }) {
 	if (!date) return null;
 	const d = new Date(date);
 	if (Number.isNaN(d.getTime())) return null;
-	const formattedDate = d.toLocaleDateString(void 0, {
-		year: "numeric",
-		month: "long",
-		day: "numeric"
-	});
+	const formattedDate = formatDeterministicDate(d);
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 		className: require_link.cn("mt-16 pt-6 border-t border-subtle flex items-center justify-between text-xs text-muted select-none", className),
 		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
@@ -703,13 +751,11 @@ function normalizeBadge(badge) {
 }
 function formatDate(date, locale) {
 	if (date === void 0 || date === null || date === "") return null;
-	const d = date instanceof Date ? date : new Date(date);
-	if (Number.isNaN(d.getTime())) return null;
-	return d.toLocaleDateString(locale ?? "en-US", {
-		year: "numeric",
-		month: "short",
-		day: "numeric"
+	const formatted = formatDeterministicDate(date, {
+		locale,
+		month: "short"
 	});
+	return formatted === "" ? null : formatted;
 }
 const VARIANT_DEFAULT_ICON = {
 	success: require_link.Check,
@@ -806,6 +852,12 @@ Object.defineProperty(exports, 'copyToClipboard', {
     return copyToClipboard;
   }
 });
+Object.defineProperty(exports, 'formatDeterministicDate', {
+  enumerable: true,
+  get: function () {
+    return formatDeterministicDate;
+  }
+});
 Object.defineProperty(exports, 'mdx_components_default', {
   enumerable: true,
   get: function () {