boltdocs 3.2.2 → 3.3.0

package/dist/{docs-layout-CFWI15Id.cjs → docs-layout-vzfXed1Q.cjs}

@@ -3,27 +3,30 @@
  * Copyright (c) 2026 Jesus Alcala
  * Licensed under the MIT License.
  */
-const require_link = require('./link-D1Gjkb-2.cjs');
+const require_router = require('./router-C3kygdRK.cjs');
+const require_link = require('./link-vZjmD-es.cjs');
 let react = require("react");
-let react_router_dom = require("react-router-dom");
 let react_jsx_runtime = require("react/jsx-runtime");
 let react_aria_components = require("react-aria-components");
-react_aria_components = require_link.__toESM(react_aria_components);
+react_aria_components = require_router.__toESM(react_aria_components);
+let isomorphic_dompurify = require("isomorphic-dompurify");
+isomorphic_dompurify = require_router.__toESM(isomorphic_dompurify);
 let virtual_boltdocs_icons = require("virtual:boltdocs-icons");
-virtual_boltdocs_icons = require_link.__toESM(virtual_boltdocs_icons);
+virtual_boltdocs_icons = require_router.__toESM(virtual_boltdocs_icons);
 let scroll_into_view_if_needed = require("scroll-into-view-if-needed");
-scroll_into_view_if_needed = require_link.__toESM(scroll_into_view_if_needed);
+scroll_into_view_if_needed = require_router.__toESM(scroll_into_view_if_needed);
 
 //#region src/client/app/ui-context.tsx
 const UIContext = (0, react.createContext)(void 0);
 function UIProvider({ children }) {
 	const [isSidebarOpen, setIsSidebarOpen] = (0, react.useState)(false);
-	const location = (0, react_router_dom.useLocation)();
+	const location = require_router.useLocation();
 	const toggleSidebar = () => setIsSidebarOpen((prev) => !prev);
 	const closeSidebar = () => setIsSidebarOpen(false);
+	const { pathname } = location;
 	(0, react.useEffect)(() => {
-		setIsSidebarOpen(false);
-	}, [location.pathname]);
+		if (pathname) setIsSidebarOpen(false);
+	}, [pathname]);
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(UIContext.Provider, {
 		value: {
 			isSidebarOpen,
@@ -35,11 +38,14 @@ function UIProvider({ children }) {
 }
 function useUI() {
 	const context = (0, react.useContext)(UIContext);
-	if (context === void 0) return {
-		isSidebarOpen: false,
-		toggleSidebar: () => {},
-		closeSidebar: () => {}
-	};
+	if (context === void 0) {
+		if (typeof window !== "undefined") console.warn("[boltdocs] useUI() was called outside of a <UIProvider>. Make sure Navbar/Sidebar are rendered within BoltdocsShell. The mobile sidebar will not open until the provider is shared.");
+		return {
+			isSidebarOpen: false,
+			toggleSidebar: () => {},
+			closeSidebar: () => {}
+		};
+	}
 	return context;
 }
 
@@ -67,10 +73,13 @@ function BreadcrumbsLink({ children, href, className, ...props }) {
 		children
 	});
 }
-function BreadcrumbsSeparator({ className }) {
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_link.ChevronRight, {
-		size: 14,
-		className: require_link.cn("shrink-0", className)
+function BreadcrumbsSeparator({ className, separator }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+		className,
+		children: separator ?? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_link.ChevronRight, {
+			size: 14,
+			className: "shrink-0"
+		})
 	});
 }
 Breadcrumbs.Root = Breadcrumbs;
@@ -80,22 +89,54 @@ Breadcrumbs.Separator = BreadcrumbsSeparator;
 
 //#endregion
 //#region src/client/components/primitives/button-group.tsx
-function ButtonGroup({ children, className, vertical = false }) {
+const RADIUS_BY_RADIUS = {
+	full: [
+		"[&>*:first-child]:rounded-l-full",
+		"[&>*:last-child]:rounded-r-full",
+		"[&>*:first-child]:rounded-t-full",
+		"[&>*:last-child]:rounded-b-full"
+	],
+	xl: [
+		"[&>*:first-child]:rounded-l-xl",
+		"[&>*:last-child]:rounded-r-xl",
+		"[&>*:first-child]:rounded-t-xl",
+		"[&>*:last-child]:rounded-b-xl"
+	],
+	lg: [
+		"[&>*:first-child]:rounded-l-lg",
+		"[&>*:last-child]:rounded-r-lg",
+		"[&>*:first-child]:rounded-t-lg",
+		"[&>*:last-child]:rounded-b-lg"
+	],
+	md: [
+		"[&>*:first-child]:rounded-l-md",
+		"[&>*:last-child]:rounded-r-md",
+		"[&>*:first-child]:rounded-t-md",
+		"[&>*:last-child]:rounded-b-md"
+	],
+	none: []
+};
+function inferRadius(className) {
+	if (className?.includes("rounded-full")) return "full";
+	if (className?.includes("rounded-xl")) return "xl";
+	if (className?.includes("rounded-lg")) return "lg";
+	return "md";
+}
+function ButtonGroup({ children, className, vertical = false, radius }) {
+	const outer = RADIUS_BY_RADIUS[radius ?? inferRadius(className)] ?? [];
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 		className: require_link.cn("inline-flex", vertical ? "flex-col" : "flex-row", !vertical && [
 			"[&>*:not(:first-child)]:-ml-px",
 			"[&>*:first-child]:rounded-r-none",
 			"[&>*:last-child]:rounded-l-none",
 			"[&>*:not(:first-child):not(:last-child)]:rounded-none",
-			className?.includes("rounded-full") && ["[&>*:first-child]:rounded-l-full", "[&>*:last-child]:rounded-r-full"],
-			className?.includes("rounded-xl") && ["[&>*:first-child]:rounded-l-xl", "[&>*:last-child]:rounded-r-xl"],
-			className?.includes("rounded-lg") && ["[&>*:first-child]:rounded-l-lg", "[&>*:last-child]:rounded-r-lg"]
+			outer.filter((c) => c.includes("rounded-l-") || c.includes("rounded-r-"))
 		], vertical && [
 			"[&>*:not(:first-child)]:-mt-px",
 			"[&>*:first-child]:rounded-b-none",
 			"[&>*:last-child]:rounded-t-none",
 			"[&>*:not(:first-child):not(:last-child)]:rounded-none",
-			className?.includes("rounded-full") && ["[&>*:first-child]:rounded-t-full", "[&>*:last-child]:rounded-b-full"]
+			outer.filter((c) => c.includes("rounded-t-") || c.includes("rounded-b-"))
 		], className),
 		children
 	});
@@ -154,29 +195,33 @@ function Menu(props) {
 */
 function MenuItem(props) {
 	const textValue = props.textValue || (typeof props.children === "string" ? props.children : void 0);
+	const { contentClassName, checkClassName, chevronClassName, check, chevron, ...racProps } = props;
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_aria_components.MenuItem, {
-		...props,
+		...racProps,
 		textValue,
 		className: react_aria_components.composeRenderProps(props.className, (className) => require_link.cn("group relative flex flex-row items-center cursor-default outline-none", className)),
 		children: react_aria_components.composeRenderProps(props.children, (children, { selectionMode, isSelected, hasSubmenu }) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
 			selectionMode === "multiple" && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-				className: "flex items-center shrink-0 justify-center",
-				children: isSelected && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_link.Check, { className: "size-3.5" })
+				className: require_link.cn("flex items-center shrink-0 justify-center", checkClassName),
+				children: check ?? (isSelected ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_link.Check, { className: "size-3.5" }) : null)
 			}),
 			/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-				className: "flex flex-row w-full items-center",
+				className: require_link.cn("flex flex-row w-full items-center", contentClassName),
 				children
 			}),
-			hasSubmenu && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_link.ChevronRight, { className: "size-4 ml-auto" })
+			hasSubmenu && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+				className: "ml-auto",
+				children: chevron ?? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_link.ChevronRight, { className: require_link.cn("size-4", chevronClassName) })
+			})
 		] }))
 	});
 }
-function MenuSection({ title, ...props }) {
+function MenuSection({ title, headerClassName, ...props }) {
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_aria_components.MenuSection, {
 		...props,
 		className: require_link.cn("flex flex-col", props.className),
 		children: [title && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_aria_components.Header, {
-			className: "select-none",
+			className: require_link.cn("select-none", headerClassName),
 			children: title
 		}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_aria_components.Collection, {
 			items: props.items,
@@ -244,33 +289,126 @@ Tabs.Item = TabsItem;
 Tabs.Content = TabsContent;
 Tabs.Indicator = TabsIndicator;
 
+//#endregion
+//#region src/client/components/ui-base/icon-renderer.tsx
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function normalizeIconExports(value) {
+	if (!isRecord(value)) return {};
+	const directExports = Object.fromEntries(Object.entries(value).filter(([key]) => key !== "default"));
+	const defaultExport = value.default;
+	if (!isRecord(defaultExport)) return directExports;
+	return {
+		...normalizeIconExports(defaultExport),
+		...directExports
+	};
+}
+function getIconRegistry() {
+	return {
+		...require_link.icons_exports,
+		...normalizeIconExports(virtual_boltdocs_icons.default)
+	};
+}
+function resolveIcon(icon, registry = getIconRegistry()) {
+	if (!icon || typeof icon !== "string") return icon;
+	if (icon.trim().startsWith("<svg")) return icon;
+	if (/^(?:https?:|data:image\/|\/|\.\.?(?:\/|$))/.test(icon) || /\.(?:svg|png|jpe?g|gif|webp|avif)(?:\?.*)?$/i.test(icon)) return icon;
+	return registry[icon] || registry[`${icon}Icon`];
+}
+function isImageSource(value) {
+	return /^(?:https?:|data:image\/|\/|\.\.?(?:\/|$))/.test(value) || /\.(?:svg|png|jpe?g|gif|webp|avif)(?:\?.*)?$/i.test(value);
+}
+function IconRenderer({ icon, size = 16, className, label }) {
+	const config = require_link.useOptionalConfig();
+	const resolved = resolveIcon(icon);
+	if (!resolved) return null;
+	if (typeof resolved === "function") return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(resolved, {
+		size,
+		width: size,
+		height: size,
+		className,
+		"aria-hidden": label ? void 0 : true,
+		"aria-label": label
+	});
+	if (resolved.trim().startsWith("<svg")) {
+		const clean = isomorphic_dompurify.default.sanitize(resolved, { USE_PROFILES: { svg: true } });
+		if (label) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+			className,
+			role: "img",
+			"aria-label": label,
+			dangerouslySetInnerHTML: { __html: clean }
+		});
+		return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+			className,
+			"aria-hidden": "true",
+			dangerouslySetInnerHTML: { __html: clean }
+		});
+	}
+	if (isImageSource(resolved)) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("img", {
+		src: require_link.resolvePublicAssetUrl(resolved, config?.base),
+		alt: label || "",
+		"aria-hidden": label ? void 0 : true,
+		className,
+		width: size,
+		height: size
+	});
+	return null;
+}
+
 //#endregion
 //#region src/client/hooks/use-sidebar.ts
 const capitalize = (str) => str.charAt(0).toUpperCase() + str.slice(1).replace(/-/g, " ");
-const getCleanDirectoryMeta = (directoryMeta) => {
-	const meta = {};
-	if (!directoryMeta) return meta;
+/**
+* Builds a lookup map from meta.json relative-directory keys.
+* Keys keep the locale (`es/...`) and tab (`(guides)/...`) segments so meta
+* resolution can be scoped per tab and per locale; numeric prefixes are
+* stripped and keys are lowercased for stable matching.
+*/
+const getDirectoryMetaLookup = (directoryMeta) => {
+	const lookup = {};
+	if (!directoryMeta) return lookup;
 	for (const [key, value] of Object.entries(directoryMeta)) {
-		const cleanKey = key.split("/").filter((part) => !part.startsWith("(") || !part.endsWith(")")).map((part) => part.replace(/^\d+-/, "")).join("/");
-		meta[cleanKey === "" ? "." : cleanKey] = value;
+		const normalizedKey = key.split("/").map((part) => part.replace(/^\d+-/, "")).join("/").toLowerCase();
+		lookup[normalizedKey] = value;
+	}
+	return lookup;
+};
+/**
+* Resolves the meta.json entry for a sidebar group by trying increasingly
+* specific directory keys: locale + tab, tab, locale, then the bare path.
+* This keeps groups that share a directory name across tabs or locales
+* (e.g. `(guides)/content` vs `(plugins)/content`) from clobbering each
+* other and lets localized sites resolve their own translated meta.
+*/
+const findDirectoryMeta = (lookup, route, relPath) => {
+	const locale = route?.locale;
+	const tab = route?.tab;
+	const candidates = [];
+	if (locale && tab) candidates.push(`${locale}/(${tab})/${relPath}`);
+	if (tab) candidates.push(`(${tab})/${relPath}`);
+	if (locale) candidates.push(`${locale}/${relPath}`);
+	candidates.push(relPath);
+	for (const candidate of candidates) {
+		const meta = lookup[candidate.toLowerCase()];
+		if (meta) return meta;
 	}
-	return meta;
 };
-const getOrCreateNode = (parts, rootMap, directoryMeta) => {
+const getOrCreateNode = (parts, rootMap, directoryMetaLookup, route) => {
 	let currentMap = rootMap;
 	let parentPath = "";
 	let lastNode;
 	for (const segment of parts) {
 		const currentRelPath = parentPath ? `${parentPath}/${segment}` : segment;
 		if (!currentMap.has(segment)) {
-			const meta = directoryMeta[currentRelPath] || {};
+			const meta = findDirectoryMeta(directoryMetaLookup, route, currentRelPath) || {};
 			const newNode = {
 				path: "#",
 				title: meta.title || capitalize(segment),
 				componentPath: "",
 				filePath: "",
 				icon: meta.icon,
-				groupPosition: typeof meta.order === "number" ? meta.order : 999,
+				groupPosition: typeof meta.order === "number" ? meta.order : void 0,
 				collapsible: meta.collapsible,
 				collapsed: meta.collapsed,
 				hasCustomTitle: meta.title !== void 0,
@@ -285,6 +423,20 @@ const getOrCreateNode = (parts, rootMap, directoryMeta) => {
 	}
 	return lastNode;
 };
+/**
+* Whether a route (or any of its nested children) matches the active path or
+* the active route's file. Used for group-level active detection and for the
+* `isActive` helper exposed by `useSidebar`.
+*/
+function isRouteActive(route, activePath, activeRoute) {
+	if (!route?.path) return false;
+	const normalizedPath = route.path.endsWith("/") ? route.path.slice(0, -1) : route.path;
+	if ((activePath.endsWith("/") ? activePath.slice(0, -1) : activePath) === normalizedPath) return true;
+	if (activeRoute?.filePath && route.filePath && activeRoute.filePath === route.filePath) return true;
+	if (route.routes?.some((r) => isRouteActive(r, activePath, activeRoute))) return true;
+	if (route.subRoutes?.some((r) => isRouteActive(r, activePath, activeRoute))) return true;
+	return false;
+}
 const getRoutePosition = (r) => r.sidebarPosition ?? r.order ?? 999;
 const getNodePosition = (n) => n.sidebarPosition ?? n.groupPosition ?? 999;
 const finalizeTree = (nodes) => {
@@ -304,13 +456,19 @@ const finalizeTree = (nodes) => {
 };
 function useSidebar(routes) {
 	const config = require_link.useConfig();
-	const { pathname } = (0, react_router_dom.useLocation)();
-	return (0, react.useMemo)(() => {
-		const currentPath = require_link.normalizePath(pathname);
-		const activeRoute = routes.find((r) => require_link.normalizePath(r.path) === currentPath);
-		const activeTabId = activeRoute?.tab?.toLowerCase();
-		const filteredRoutes = routes.filter((r) => !r.collection && !r.sidebarHidden && !r.fallback).filter((r) => !activeTabId || r.tab?.toLowerCase() === activeTabId).sort((a, b) => getRoutePosition(a) - getRoutePosition(b));
-		const directoryMeta = getCleanDirectoryMeta(config.directoryMeta);
+	const { pathname } = require_router.useLocation();
+	const { index } = require_link.useRoutesContext();
+	const currentPath = require_link.normalizePath(pathname);
+	const activeRoute = index.byPath.size > 0 ? index.byPath.get(currentPath) : routes.find((route) => require_link.normalizePath(route.path) === currentPath);
+	const configuredTabs = config.theme?.tabs || [];
+	const configuredTabIds = new Set(configuredTabs.map((tab) => tab.id.toLowerCase()));
+	const normalizedBase = require_link.normalizePath(config.base || "/docs");
+	const routeTabId = activeRoute?.tab?.toLowerCase();
+	const parsedCurrentRoute = require_router.parseUrlReference(currentPath, config, { kind: "doc" });
+	const activeTabId = (currentPath === normalizedBase || Boolean(activeRoute?.fallback) && parsedCurrentRoute.routePath === "/" || currentPath.startsWith(`${normalizedBase}/`) && parsedCurrentRoute.routePath === "/" ? configuredTabs[0]?.id.toLowerCase() : routeTabId && configuredTabIds.has(routeTabId) ? routeTabId : void 0) || void 0;
+	const sidebar = (0, react.useMemo)(() => {
+		const filteredRoutes = routes.filter((r) => !r.collection && !r.sidebarHidden && !r.fallback).filter((r) => !configuredTabs.length || r.tab?.toLowerCase() === activeTabId).sort((a, b) => getRoutePosition(a) - getRoutePosition(b));
+		const directoryMeta = getDirectoryMetaLookup(config.directoryMeta);
 		const rootNodesMap = /* @__PURE__ */ new Map();
 		const ungrouped = [];
 		for (const route of filteredRoutes) {
@@ -320,13 +478,13 @@ function useSidebar(routes) {
 				if (route.filePath) ungrouped.push(route);
 				continue;
 			}
-			const containerNode = getOrCreateNode(parts, rootNodesMap, directoryMeta);
+			const containerNode = getOrCreateNode(parts, rootNodesMap, directoryMeta, route);
 			if (isIndex) Object.assign(containerNode, {
 				path: route.path,
 				title: containerNode.hasCustomTitle ? containerNode.title : route.title || containerNode.title,
 				icon: route.icon || containerNode.icon,
 				badge: route.badge,
-				sidebarPosition: route.sidebarPosition,
+				sidebarPosition: containerNode.groupPosition === void 0 ? route.sidebarPosition : void 0,
 				frontmatter: route.frontmatter,
 				filePath: route.filePath
 			});
@@ -334,45 +492,93 @@ function useSidebar(routes) {
 		}
 		const finalizedTopNodes = finalizeTree(Array.from(rootNodesMap.values()));
 		const groups = [];
-		for (const node of finalizedTopNodes) if (node.subRoutes && node.subRoutes.length > 0) groups.push({
-			slug: node.title.toLowerCase().replace(/\s+/g, "-"),
-			title: node.title,
-			icon: node.icon,
-			path: node.path,
-			filePath: node.filePath,
-			routes: node.subRoutes,
-			sidebarPosition: node.sidebarPosition ?? node.groupPosition ?? 999,
-			collapsible: node.collapsible,
-			collapsed: node.collapsed
-		});
-		else ungrouped.push(node);
+		for (const node of finalizedTopNodes) if (node.subRoutes && node.subRoutes.length > 0) {
+			const nodeWithMeta = node;
+			groups.push({
+				slug: node.title.toLowerCase().replace(/\s+/g, "-"),
+				title: node.title,
+				icon: node.icon,
+				path: node.path,
+				filePath: node.filePath,
+				routes: node.subRoutes,
+				sidebarPosition: node.sidebarPosition ?? node.groupPosition ?? 999,
+				collapsible: nodeWithMeta.collapsible,
+				collapsed: nodeWithMeta.collapsed
+			});
+		} else ungrouped.push(node);
+		const finalizedUngrouped = finalizeTree(ungrouped);
 		return {
 			groups,
-			ungrouped: finalizeTree(ungrouped),
-			activeRoute,
-			activePath: currentPath,
-			config
+			ungrouped: finalizedUngrouped,
+			merged: [...finalizedUngrouped.map((route) => ({
+				type: "link",
+				position: route.sidebarPosition ?? 999,
+				title: route.title,
+				route
+			})), ...groups.map((group) => ({
+				type: "group",
+				position: group.sidebarPosition ?? 999,
+				title: group.title,
+				group
+			}))].sort((a, b) => {
+				if (a.position !== b.position) return a.position - b.position;
+				if (a.type !== b.type) return a.type === "link" ? -1 : 1;
+				return a.title.localeCompare(b.title);
+			})
 		};
 	}, [
 		routes,
 		config,
-		pathname
+		activeTabId,
+		configuredTabs.length
+	]);
+	const isActive = (0, react.useCallback)((route) => isRouteActive(route, currentPath, activeRoute), [currentPath, activeRoute]);
+	const isGroupActive = (0, react.useCallback)((group) => group.routes.some((route) => isRouteActive(route, currentPath, activeRoute)), [currentPath, activeRoute]);
+	const tree = (0, react.useMemo)(() => {
+		const buildNode = (route, depth) => {
+			const children = route.routes || route.subRoutes || [];
+			return {
+				route,
+				depth,
+				isGroup: false,
+				isActive: isRouteActive(route, currentPath, activeRoute),
+				hasChildren: children.length > 0,
+				children: children.map((child) => buildNode(child, depth + 1))
+			};
+		};
+		const buildGroupNode = (group) => ({
+			route: group,
+			depth: 0,
+			isGroup: true,
+			isActive: isGroupActive(group),
+			hasChildren: true,
+			children: group.routes.map((route) => buildNode(route, 1))
+		});
+		return sidebar.merged.map((item) => item.type === "group" ? buildGroupNode(item.group) : buildNode(item.route, 0));
+	}, [
+		sidebar,
+		activeRoute,
+		currentPath,
+		isGroupActive
 	]);
+	return {
+		...sidebar,
+		tree,
+		isActive,
+		isGroupActive,
+		activeRoute,
+		activePath: currentPath,
+		config
+	};
 }
 
-//#endregion
-//#region src/client/hooks/use-location.ts
-const useLocation = () => {
-	return (0, react_router_dom.useLocation)();
-};
-
 //#endregion
 //#region src/client/hooks/use-search-highlight.ts
 /**
 * Hook to highlight search terms based on the 'hl' query parameter.
 */
 function useSearchHighlight(containerSelector = ".boltdocs-page") {
-	const { search } = useLocation();
+	const { search } = require_router.useLocation();
 	const query = new URLSearchParams(search).get("hl");
 	(0, react.useEffect)(() => {
 		if (!query) {
@@ -408,11 +614,7 @@ function useSearchHighlight(containerSelector = ".boltdocs-page") {
 			observer.disconnect();
 			clearHighlights(containerSelector);
 		};
-	}, [
-		query,
-		search,
-		containerSelector
-	]);
+	}, [query, containerSelector]);
 }
 function clearHighlights(selector) {
 	document.querySelectorAll(`${selector} mark[data-search-highlight]`).forEach((mark) => {
@@ -432,8 +634,11 @@ function highlightTerms(container, terms) {
 		return NodeFilter.FILTER_ACCEPT;
 	} });
 	const nodes = [];
-	let node;
-	while (node = walker.nextNode()) nodes.push(node);
+	let node = walker.nextNode();
+	while (node) {
+		nodes.push(node);
+		node = walker.nextNode();
+	}
 	const accentMap = {
 		a: "[aáàäâã]",
 		e: "[eéèëê]",
@@ -630,7 +835,7 @@ function AnchorProvider({ toc, single = false, observerOptions, children }) {
 		return () => {
 			observer.unwatch();
 		};
-	}, [observer]);
+	}, [observer, observerOptions]);
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ItemsContext.Provider, {
 		value: items,
 		children
@@ -638,53 +843,64 @@ function AnchorProvider({ toc, single = false, observerOptions, children }) {
 }
 function OnThisPage({ children, className }) {
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("nav", {
-		className: require_link.cn("sticky top-navbar hidden xl:flex flex-col shrink-0", "w-toc", "py-4 pl-6 pr-4", className),
+		"data-otp-root": true,
+		className,
 		children
 	});
 }
 function OnThisPageHeader({ children, className, ...props }) {
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-		className: require_link.cn("mb-4 text-xs font-bold text-body", className),
+		className,
 		...props,
 		children
 	});
 }
-function OnThisPageContent({ children, className, ref, ...props }) {
+function OnThisPageContent({ children, className, ref, fadeClassName, innerClassName, ...props }) {
 	const internalRef = (0, react.useRef)(null);
-	(0, react.useImperativeHandle)(ref, () => internalRef.current);
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-		ref: internalRef,
-		className: require_link.cn("relative overflow-y-auto boltdocs-otp-content pb-12", "max-h-[70%]", className),
-		style: {
-			maskImage: "linear-gradient(to bottom, black 90%, transparent 100%)",
-			WebkitMaskImage: "linear-gradient(to bottom, black 90%, transparent 100%)"
-		},
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		ref: (0, react.useCallback)((node) => {
+			internalRef.current = node;
+			if (typeof ref === "function") ref(node);
+			else if (ref) ref.current = node;
+		}, [ref]),
+		"data-otp-content": true,
+		className: require_link.cn("relative isolate overflow-y-auto", className),
 		...props,
-		children
+		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+			className: require_link.cn("relative z-10", innerClassName),
+			children
+		}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+			"aria-hidden": "true",
+			"data-otp-fade": true,
+			className: require_link.cn("pointer-events-none sticky bottom-0 z-0 -mt-10 h-10 w-full", fadeClassName)
+		})]
 	});
 }
 OnThisPageContent.displayName = "OnThisPageContent";
 function OnThisPageList({ children, className }) {
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("ul", {
-		className: require_link.cn("relative space-y-0.5 text-sm border-l border-subtle", className),
+		"data-otp-list": true,
+		className: require_link.cn("relative", className),
 		children
 	});
 }
 function OnThisPageItem({ level, children, className }) {
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("li", {
-		className: require_link.cn(level === 3 && "pl-3", className),
+		"data-level": level || void 0,
+		className,
 		children
 	});
 }
 function OnThisPageLink({ children, href, active, onClick, className }) {
 	const items = (0, react.use)(ItemsContext);
 	const containerRef = (0, react.use)(ScrollContext);
+	const navigate = require_router.useNavigate();
 	const id = href ? getItemId(href) : null;
 	const anchorRef = (0, react.useRef)(null);
 	const computedActive = active !== void 0 ? active : id && items ? !!items.find((i) => i.id === id)?.active : false;
 	(0, react.useEffect)(() => {
 		if (computedActive && anchorRef.current && containerRef?.current) (0, scroll_into_view_if_needed.default)(anchorRef.current, {
-			behavior: "smooth",
+			behavior: "auto",
 			block: "center",
 			inline: "center",
 			scrollMode: "if-needed",
@@ -692,14 +908,14 @@ function OnThisPageLink({ children, href, active, onClick, className }) {
 		});
 	}, [computedActive, containerRef]);
 	const handleClick = (e) => {
-		if (onClick) onClick(e);
-		else if (href && href.startsWith("#")) {
-			e.preventDefault();
-			const elementId = href.slice(1);
-			const el = document.getElementById(elementId);
-			if (el) {
-				el.scrollIntoView({ behavior: "smooth" });
-				window.history.pushState(null, "", href);
+		if (onClick) {
+			onClick(e);
+			return;
+		}
+		if (href) {
+			if ((href.includes("#") ? href.split("#")[1] : null) && navigate !== require_router.defaultNavigate) {
+				e.preventDefault();
+				navigate(href);
 			}
 		}
 	};
@@ -707,8 +923,9 @@ function OnThisPageLink({ children, href, active, onClick, className }) {
 		ref: anchorRef,
 		href,
 		onClick: handleClick,
-		"data-active": computedActive,
-		className: require_link.cn("block py-0.5 pl-4 text-[13px] outline-none transition-colors", computedActive ? "text-primary-500" : "text-muted hover:text-body", className),
+		"data-active": computedActive || void 0,
+		"aria-current": computedActive ? "true" : void 0,
+		className,
 		children
 	});
 }
@@ -718,7 +935,9 @@ function OnThisPageIndicator({ style, className }) {
 		opacity: 0,
 		...style
 	});
+	const items = useItems();
 	(0, react.useEffect)(() => {
+		if (items.length === 0) return;
 		const parent = containerRef.current?.parentElement;
 		if (!parent) return;
 		const activeLinks = parent.querySelectorAll("a[data-active=\"true\"]");
@@ -740,10 +959,11 @@ function OnThisPageIndicator({ style, className }) {
 			opacity: 0,
 			...style
 		});
-	}, [useItems(), style]);
+	}, [items, style]);
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 		ref: containerRef,
-		className: require_link.cn("absolute -left-px w-0.5 rounded-full bg-primary-500", className),
+		"data-otp-indicator": true,
+		className: require_link.cn("absolute", className),
 		style: {
 			transition: "transform 180ms cubic-bezier(0.2, 0.8, 0.2, 1), height 180ms cubic-bezier(0.2, 0.8, 0.2, 1), opacity 150ms",
 			...internalStyle
@@ -753,16 +973,18 @@ function OnThisPageIndicator({ style, className }) {
 /**
 * High-level automated list of toc items
 */
-function OnThisPageItems({ headings = [], className }) {
+function OnThisPageItems({ headings = [], className, itemClassName, linkClassName, indicatorClassName }) {
 	const activeIds = useActiveAnchors();
 	if (headings.length === 0) return null;
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(OnThisPageList, {
 		className,
-		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(OnThisPageIndicator, {}), headings.map((h) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(OnThisPageItem, {
+		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(OnThisPageIndicator, { className: indicatorClassName }), headings.map((h) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(OnThisPageItem, {
 			level: h.level,
+			className: itemClassName,
 			children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(OnThisPageLink, {
 				href: `#${h.id}`,
 				active: activeIds.includes(h.id),
+				className: linkClassName,
 				children: h.text
 			})
 		}, h.id))]
@@ -771,7 +993,7 @@ function OnThisPageItems({ headings = [], className }) {
 /**
 * High-level automated Table of Contents tree
 */
-function OnThisPageTree({ headings = [], className }) {
+function OnThisPageTree({ headings = [], className, itemClassName, linkClassName, indicatorClassName, fadeClassName, contentClassName }) {
 	const toc = (0, react.useMemo)(() => headings.map((h) => ({
 		title: h.text,
 		url: `#${h.id}`,
@@ -781,14 +1003,19 @@ function OnThisPageTree({ headings = [], className }) {
 	if (headings.length === 0) return null;
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(AnchorProvider, {
 		toc,
-		single: false,
+		single: true,
 		children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ScrollProvider, {
 			containerRef: scrollContainerRef,
 			children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(OnThisPageContent, {
 				ref: scrollContainerRef,
+				fadeClassName,
+				className: contentClassName,
 				children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(OnThisPageItems, {
 					headings,
-					className
+					className,
+					itemClassName,
+					linkClassName,
+					indicatorClassName
 				})
 			})
 		})
@@ -813,18 +1040,10 @@ function PageNav({ children, className }) {
 	});
 }
 function PageNavLink({ children, to, direction, className }) {
-	const isNext = direction === "next";
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(require_link.Link, {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_link.Link, {
 		href: to,
-		className: require_link.cn("flex items-center outline-none no-underline", isNext ? "justify-end" : "justify-start", className),
-		children: [
-			!isNext && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_link.ChevronLeft, { className: "shrink-0" }),
-			/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-				className: "flex flex-col flex-1",
-				children
-			}),
-			isNext && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_link.ChevronRight, { className: "shrink-0" })
-		]
+		className: require_link.cn("flex items-center outline-none no-underline", direction === "next" ? "justify-end" : "justify-start", className),
+		children
 	});
 }
 function PageNavTitle({ children, className }) {
@@ -839,8 +1058,11 @@ function PageNavDescription({ children, className }) {
 		children
 	});
 }
-function PageNavIcon({ children }) {
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_jsx_runtime.Fragment, { children });
+function PageNavIcon({ children, className }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+		className: require_link.cn("shrink-0", className),
+		children
+	});
 }
 PageNav.Root = PageNav;
 PageNav.Link = PageNavLink;
@@ -852,27 +1074,20 @@ PageNav.Icon = PageNavIcon;
 //#region src/client/components/primitives/sidebar.tsx
 let sidebarScrollPos = 0;
 function getIcon(iconName) {
-	if (!iconName) return void 0;
-	const icons = {
-		...require_link.icons_exports,
-		...virtual_boltdocs_icons.default
-	};
-	return icons[iconName] || icons[iconName + "Icon"] || void 0;
+	return resolveIcon(iconName);
 }
 /**
-* Internal Badge component for links
+* Internal Badge component for links.
+*
+* Carries no colors — the theme styles it via `data-badge`.
 */
-function Badge({ badge }) {
-	const colors = {
-		new: "bg-primary-500/10 text-primary-500 border border-primary-500/20",
-		updated: "bg-emerald-500/10 text-emerald-500 border border-emerald-500/20",
-		deprecated: "bg-danger-500/10 text-danger-500 border border-danger-500/20"
-	};
-	const text = typeof badge === "string" ? badge : badge?.text;
-	if (!text) return null;
+function Badge({ badge, badgeClassName }) {
+	const type = typeof badge === "string" ? badge : badge?.text;
+	if (!type) return null;
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-		className: require_link.cn("ml-auto flex h-5 items-center rounded-md text-[10px] font-bold px-1.5 py-0.5 uppercase tracking-wider", colors[text] || colors.new),
-		children: text
+		"data-badge": type,
+		className: require_link.cn("ml-auto shrink-0", badgeClassName),
+		children: type
 	});
 }
 /**
@@ -880,24 +1095,25 @@ function Badge({ badge }) {
 */
 function SidebarRoot({ children, className }) {
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("aside", {
-		className: require_link.cn("hidden lg:flex flex-col w-sidebar sticky top-navbar h-[calc(100vh-var(--spacing-navbar))] border-r border-subtle bg-main", className),
+		"data-sidebar-root": true,
+		className,
 		children
 	});
 }
 /**
 * Mobile Sidebar Modal
 */
-function SidebarMobile({ children, className }) {
+function SidebarMobile({ children, className, overlayClassName, dialogClassName }) {
 	const { isSidebarOpen, closeSidebar } = useUI();
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_aria_components.ModalOverlay, {
 		isOpen: isSidebarOpen,
 		onOpenChange: (open) => !open && closeSidebar(),
 		isDismissable: true,
-		className: require_link.cn("fixed inset-0 z-50 bg-black/20 backdrop-blur-sm lg:hidden", "entering:animate-in entering:fade-in exiting:animate-out exiting:fade-out duration-300"),
+		className: require_link.cn("lg:hidden", overlayClassName),
 		children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_aria_components.Modal, {
-			className: require_link.cn("fixed top-0 left-0 bottom-0 w-80 bg-main border-r border-subtle shadow-2xl outline-none", "entering:animate-in entering:slide-in-from-left exiting:animate-out exiting:slide-out-to-left duration-300", className),
+			className: require_link.cn("lg:hidden", className),
 			children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_aria_components.Dialog, {
-				className: "h-full focus:outline-none outline-none flex flex-col",
+				className: require_link.cn("h-full flex flex-col outline-none focus:outline-none", dialogClassName),
 				children
 			})
 		})
@@ -908,12 +1124,15 @@ function SidebarMobile({ children, className }) {
 */
 function SidebarHeader({ children, className }) {
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-		className: require_link.cn("flex items-center justify-between p-4 border-b border-subtle", className),
+		className,
 		children
 	});
 }
 /**
 * Scrollable Content Wrapper
+*
+* The scroll container doubles as the semantic `<nav>` landmark. State and
+* scroll-position handling live here; all visuals belong to the theme.
 */
 function SidebarContent({ children, className }) {
 	const scrollRef = (0, react.useRef)(null);
@@ -929,107 +1148,143 @@ function SidebarContent({ children, className }) {
 		el.addEventListener("scroll", handleScroll, { passive: true });
 		return () => el.removeEventListener("scroll", handleScroll);
 	}, []);
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("nav", {
 		ref: scrollRef,
-		className: require_link.cn("flex-1 overflow-y-auto p-4 pb-16 custom-scrollbar", className),
-		children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("nav", {
-			className: "flex flex-col gap-6",
-			children
-		})
+		"data-sidebar-content": true,
+		className,
+		children
 	});
 }
 /**
 * Navigation Group
 */
-function SidebarGroup({ title, icon: Icon, children, className, collapsible = false, collapsed = false, active = false }) {
+function SidebarGroup({ title, icon: Icon, children, className, collapsible = false, collapsed = false, active = false, headerClassName, iconClassName, titleClassName, contentClassName, trailing, trailingClassName, renderTitle }) {
 	const [isOpen, setIsOpen] = (0, react.useState)(() => active || !collapsed);
-	const [prevActive, setPrevActive] = (0, react.useState)(active);
-	if (active !== prevActive) {
-		setPrevActive(active);
+	(0, react.useEffect)(() => {
 		if (active) setIsOpen(true);
-	}
+	}, [active]);
+	const titleContent = title && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+		className: require_link.cn("flex items-center gap-2", titleClassName),
+		children: [Icon && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(IconRenderer, {
+			icon: Icon,
+			size: 12,
+			className: iconClassName
+		}), title]
+	});
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		"data-group": true,
+		"data-active": active || void 0,
+		"data-collapsible": collapsible || void 0,
 		className,
-		children: [title && (collapsible ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("button", {
+		children: [title && (renderTitle ? renderTitle({
+			title,
+			isOpen
+		}) : collapsible ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("button", {
 			onClick: () => setIsOpen(!isOpen),
-			className: "w-full text-left px-2 mb-2 flex items-center justify-between text-xs font-regular tracking-widest text-muted/50 hover:text-body transition-colors outline-none cursor-pointer group",
-			children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
-				className: "flex items-center gap-2",
-				children: [Icon && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Icon, { size: 12 }), title]
-			}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_link.ChevronRight, {
+			"aria-expanded": isOpen,
+			"data-open": isOpen || void 0,
+			className: require_link.cn("group flex w-full cursor-pointer items-center justify-between gap-2 text-left outline-none", headerClassName),
+			children: [titleContent, trailing ?? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_link.ChevronRight, {
 				size: 12,
-				className: require_link.cn("transition-transform duration-200 text-muted/40 group-hover:text-body", isOpen && "rotate-90")
+				"data-open": isOpen || void 0,
+				className: require_link.cn("shrink-0 transition-transform duration-200", isOpen && "rotate-90")
 			})]
 		}) : /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("h4", {
-			className: "px-2 mb-2 flex items-center gap-2 text-[11px] font-bold uppercase tracking-widest text-muted/50",
-			children: [Icon && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Icon, { size: 12 }), title]
+			className: require_link.cn("flex items-center gap-2 outline-none", headerClassName),
+			children: [titleContent, trailing && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+				className: require_link.cn("ml-auto", trailingClassName),
+				children: trailing
+			})]
 		})), (!collapsible || isOpen) && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-			className: "flex flex-col gap-0.5",
+			className: require_link.cn("flex flex-col", contentClassName),
 			children
 		})]
 	});
 }
-function SidebarLink({ label, href, active, icon: Icon, badge, className }) {
+function SidebarLink({ label, href, active, icon: Icon, badge, className, iconClassName, labelClassName, badgeClassName, children, trailing, depth }) {
+	const linkRef = (0, react.useRef)(null);
+	(0, react.useEffect)(() => {
+		if (active && linkRef.current?.scrollIntoView) linkRef.current.scrollIntoView({ block: "nearest" });
+	}, [active]);
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(require_link.Link, {
+		ref: linkRef,
 		href,
-		className: require_link.cn("group flex items-center gap-2.5 rounded-lg px-2.5 py-1.5 text-sm transition-all outline-none", active ? "bg-primary-500/10 text-primary-500 font-medium shadow-sm" : "text-muted hover:bg-surface hover:text-body", className),
+		"data-active": active || void 0,
+		"data-depth": depth !== void 0 ? depth : void 0,
+		"aria-current": active ? "page" : void 0,
+		className: require_link.cn("group flex items-center gap-2.5 outline-none", className),
 		children: [
-			Icon && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Icon, {
+			Icon && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(IconRenderer, {
+				icon: Icon,
 				size: 16,
-				className: require_link.cn(active ? "text-primary-500" : "text-muted group-hover:text-body")
+				className: require_link.cn("shrink-0", iconClassName)
 			}),
-			/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-				className: "truncate",
+			children ?? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+				className: require_link.cn("truncate", labelClassName),
 				children: label
 			}),
-			badge && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Badge, { badge })
+			badge && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Badge, {
+				badge,
+				badgeClassName
+			}),
+			trailing
 		]
 	});
 }
 /**
 * Nested SubGroup
 */
-function SidebarSubGroup({ label, href, active, icon: Icon, badge, isOpen, onToggle, children, className }) {
+function SidebarSubGroup({ label, href, active, icon: Icon, badge, isOpen, onToggle, children, className, rootClassName, linkClassName, contentClassName, toggleClassName, wrapperClassName, renderToggle, depth }) {
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-		className: "flex flex-col gap-0.5",
+		className: require_link.cn("flex flex-col", rootClassName),
 		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-			className: "group relative flex items-center",
+			className: require_link.cn("group relative flex items-center", wrapperClassName),
 			children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(SidebarLink, {
 				label,
 				href,
 				active,
 				icon: Icon,
 				badge,
-				className: require_link.cn("flex-1 pr-8", className)
-			}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+				depth,
+				className: require_link.cn("flex-1 pr-8", linkClassName, className)
+			}), renderToggle ? renderToggle({ isOpen }) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
 				onClick: (e) => {
 					e.preventDefault();
 					e.stopPropagation();
 					onToggle();
 				},
-				className: "absolute right-1 p-1.5 text-muted hover:text-body transition-colors outline-none cursor-pointer",
+				"aria-expanded": isOpen,
+				"data-open": isOpen || void 0,
+				className: require_link.cn("absolute right-1 cursor-pointer outline-none", toggleClassName),
 				children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_link.ChevronRight, {
 					size: 14,
+					"data-open": isOpen || void 0,
 					className: require_link.cn("transition-transform duration-200", isOpen && "rotate-90")
 				})
 			})]
 		}), isOpen && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-			className: "ml-4 pl-3 border-l border-subtle/50 mt-0.5 flex flex-col gap-0.5",
+			className: require_link.cn("flex flex-col", contentClassName),
 			children
 		})]
 	});
 }
-function SidebarItem({ route, activePath, activeRoute, className }) {
+function SidebarItem({ route, activePath, activeRoute, className, depth = 0, renderItem, classNames }) {
 	const localizedHref = require_link.useLocalizedTo(route.path);
 	const isCurrent = activePath === (localizedHref.endsWith("/") ? localizedHref.slice(0, -1) : localizedHref) || !!activeRoute?.filePath && !!route.filePath && activeRoute.filePath === route.filePath;
 	const hasChildren = !!route.routes?.length || !!route.subRoutes?.length;
 	const children = route.routes || route.subRoutes;
-	const [isOpen, setIsOpen] = (0, react.useState)(() => activePath.startsWith(localizedHref) || !!activeRoute?.filePath && !!route.filePath && activeRoute.filePath === route.filePath);
-	const [prevActivePath, setPrevActivePath] = (0, react.useState)(activePath);
-	if (activePath !== prevActivePath) {
-		setPrevActivePath(activePath);
-		if (activePath.startsWith(localizedHref) || !!activeRoute?.filePath && !!route.filePath && activeRoute.filePath === route.filePath) setIsOpen(true);
-	}
+	const shouldBeOpen = activePath.startsWith(localizedHref) || !!activeRoute?.filePath && !!route.filePath && activeRoute.filePath === route.filePath;
+	const [isOpen, setIsOpen] = (0, react.useState)(() => shouldBeOpen);
+	(0, react.useEffect)(() => {
+		if (shouldBeOpen) setIsOpen(true);
+	}, [shouldBeOpen]);
+	const renderChild = (subRoute) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react.Fragment, { children: renderItem ? renderItem(subRoute, depth + 1) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(SidebarItem, {
+		route: subRoute,
+		activePath,
+		activeRoute,
+		depth: depth + 1,
+		classNames
+	}) }, subRoute.path);
 	if (hasChildren) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(SidebarSubGroup, {
 		label: route.title,
 		href: route.path,
@@ -1038,12 +1293,13 @@ function SidebarItem({ route, activePath, activeRoute, className }) {
 		badge: route.badge,
 		isOpen,
 		onToggle: () => setIsOpen(!isOpen),
-		className,
-		children: children?.map((subRoute) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(SidebarItem, {
-			route: subRoute,
-			activePath,
-			activeRoute
-		}, subRoute.path))
+		depth,
+		rootClassName: classNames?.subgroup,
+		linkClassName: require_link.cn(classNames?.subgroupLink, className),
+		contentClassName: classNames?.subgroupContent,
+		toggleClassName: classNames?.toggle,
+		wrapperClassName: classNames?.subgroupWrapper,
+		children: children?.map(renderChild)
 	});
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(SidebarLink, {
 		label: route.title,
@@ -1051,67 +1307,74 @@ function SidebarItem({ route, activePath, activeRoute, className }) {
 		active: isCurrent,
 		icon: getIcon(route.icon),
 		badge: route.badge,
-		className
+		depth,
+		className: require_link.cn(classNames?.item, className),
+		iconClassName: classNames?.itemIcon,
+		labelClassName: classNames?.itemLabel,
+		badgeClassName: classNames?.itemBadge
 	});
 }
-const isRouteActive = (route, activePath, activeRoute) => {
-	const normalizedPath = route.path.endsWith("/") ? route.path.slice(0, -1) : route.path;
-	if ((activePath.endsWith("/") ? activePath.slice(0, -1) : activePath) === normalizedPath) return true;
-	if (activeRoute?.filePath && route.filePath && activeRoute.filePath === route.filePath) return true;
-	if (route.routes && route.routes.some((r) => isRouteActive(r, activePath, activeRoute))) return true;
-	if (route.subRoutes && route.subRoutes.some((r) => isRouteActive(r, activePath, activeRoute))) return true;
-	return false;
-};
-function SidebarItems({ routes, className }) {
-	const { groups, ungrouped, activePath, activeRoute } = useSidebar(routes);
-	const mergedItems = [...ungrouped.map((route) => ({
-		type: "link",
-		position: route.sidebarPosition ?? 999,
-		title: route.title,
-		route
-	})), ...groups.map((group) => ({
-		type: "group",
-		position: group.sidebarPosition ?? 999,
-		title: group.title,
-		group
-	}))].sort((a, b) => {
-		if (a.position !== b.position) return a.position - b.position;
-		if (a.type !== b.type) return a.type === "link" ? -1 : 1;
-		return a.title.localeCompare(b.title);
-	});
+function SidebarItems({ routes, className, classNames, componentItem, componentGroup }) {
+	const { merged, activePath, activeRoute, isGroupActive } = useSidebar(routes);
+	const renderItem = (route, depth) => {
+		if (componentItem) return componentItem({
+			route,
+			activePath,
+			activeRoute,
+			isActive: isRouteActive(route, activePath, activeRoute),
+			depth
+		});
+		return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(SidebarItem, {
+			route,
+			activePath,
+			activeRoute,
+			depth,
+			renderItem,
+			classNames
+		});
+	};
 	const renderedElements = [];
 	let currentUngrouped = [];
 	const pushUngrouped = () => {
 		if (currentUngrouped.length > 0) {
 			const routesToRender = [...currentUngrouped];
-			renderedElements.push(/* @__PURE__ */ (0, react_jsx_runtime.jsx)(SidebarGroup, { children: routesToRender.map((route) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(SidebarItem, {
-				route,
-				activePath,
-				activeRoute
-			}, route.path)) }, `ungrouped-${routesToRender[0].path}`));
+			renderedElements.push(/* @__PURE__ */ (0, react_jsx_runtime.jsx)(SidebarGroup, {
+				className: classNames?.group,
+				headerClassName: classNames?.groupHeader,
+				iconClassName: classNames?.groupIcon,
+				titleClassName: classNames?.groupTitle,
+				contentClassName: classNames?.groupContent,
+				children: routesToRender.map((route) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react.Fragment, { children: renderItem(route, 0) }, route.path))
+			}, `ungrouped-${routesToRender[0]?.path || "root"}`));
 			currentUngrouped = [];
 		}
 	};
-	for (const item of mergedItems) if (item.type === "link") currentUngrouped.push(item.route);
+	for (const item of merged) if (item.type === "link") currentUngrouped.push(item.route);
 	else {
 		pushUngrouped();
-		const isGroupActive = item.group.routes.some((route) => isRouteActive(route, activePath, activeRoute));
-		renderedElements.push(/* @__PURE__ */ (0, react_jsx_runtime.jsx)(SidebarGroup, {
+		const groupActive = isGroupActive(item.group);
+		const groupChildren = item.group.routes.map((route) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react.Fragment, { children: renderItem(route, 1) }, route.path));
+		renderedElements.push(componentGroup ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react.Fragment, { children: componentGroup({
+			group: item.group,
+			isGroupActive: groupActive,
+			children: groupChildren
+		}) }, item.group.title) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(SidebarGroup, {
 			title: item.group.title,
 			icon: getIcon(item.group.icon),
 			collapsible: item.group.collapsible,
 			collapsed: item.group.collapsed,
-			active: isGroupActive,
-			children: item.group.routes.map((route) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(SidebarItem, {
-				route,
-				activePath,
-				activeRoute
-			}, route.path))
+			active: groupActive,
+			className: classNames?.group,
+			headerClassName: classNames?.groupHeader,
+			iconClassName: classNames?.groupIcon,
+			titleClassName: classNames?.groupTitle,
+			contentClassName: classNames?.groupContent,
+			children: groupChildren
 		}, item.group.title));
 	}
 	pushUngrouped();
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-		className: require_link.cn("flex flex-col gap-6", className),
+		className,
 		children: renderedElements
 	});
 }
@@ -1168,12 +1431,13 @@ function Content({ children, className, style }) {
 		children
 	});
 }
-function ContentMdx({ children, className, style }) {
+function ContentMdx({ children, className, style, contentClassName, contentStyle }) {
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-		className: require_link.cn("boltdocs-page w-full pt-4 pb-20 px-4 sm:px-8", className),
+		className: require_link.cn("boltdocs-page w-full", className),
 		style,
 		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(SearchHighlight, {}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-			className: "mx-auto w-full max-w-3xl sm:max-w-4xl lg:max-w-5xl",
+			className: require_link.cn("mx-auto w-full max-w-3xl sm:max-w-4xl lg:max-w-5xl", contentClassName),
+			style: contentStyle,
 			children
 		})]
 	});
@@ -1185,19 +1449,11 @@ function Header({ children, className, style }) {
 		children
 	});
 }
-function Footer({ children, className, style }) {
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-		className: require_link.cn("mt-20", className),
-		style,
-		children
-	});
-}
 const DocsLayout = Object.assign(DocsLayoutRoot, {
 	Body,
 	Content,
 	ContentMdx,
-	Header,
-	Footer
+	Header
 });
 
 //#endregion
@@ -1225,6 +1481,12 @@ Object.defineProperty(exports, 'DocsLayout', {
     return DocsLayout;
   }
 });
+Object.defineProperty(exports, 'IconRenderer', {
+  enumerable: true,
+  get: function () {
+    return IconRenderer;
+  }
+});
 Object.defineProperty(exports, 'Menu', {
   enumerable: true,
   get: function () {
@@ -1339,6 +1601,12 @@ Object.defineProperty(exports, 'UIProvider', {
     return UIProvider;
   }
 });
+Object.defineProperty(exports, 'resolveIcon', {
+  enumerable: true,
+  get: function () {
+    return resolveIcon;
+  }
+});
 Object.defineProperty(exports, 'useActiveAnchor', {
   enumerable: true,
   get: function () {
@@ -1357,12 +1625,6 @@ Object.defineProperty(exports, 'useItems', {
     return useItems;
   }
 });
-Object.defineProperty(exports, 'useLocation', {
-  enumerable: true,
-  get: function () {
-    return useLocation;
-  }
-});
 Object.defineProperty(exports, 'useSearchHighlight', {
   enumerable: true,
   get: function () {