@vezham/docs-core 1.0.1

package/dist/source/plugins/status-badges.d.ts

@@ -0,0 +1,50 @@
+import { a as Separator$1, n as Item$1, t as Folder$1 } from "../../definitions-CFOhwE1k.js";
+import { x as LoaderPlugin } from "../../index-DIwKCYOz.js";
+import { ReactNode } from "react";
+//#region src/source/plugins/status-badges.d.ts
+interface Item extends Item$1 {
+  /**
+   * Status badge to display in the sidebar (e.g., "new", "beta", "deprecated", "experimental").
+   */
+  status?: string;
+}
+interface Folder extends Omit<Folder$1, 'children' | 'index'> {
+  index?: Item;
+  children: Node[];
+}
+type Separator = Separator$1;
+type Node = Item | Folder | Separator;
+/**
+ * Plugin to add status badges to pages in the sidebar.
+ *
+ * This reads the `status` field from page frontmatter and adds it to the page tree item.
+ * Define the `renderBadge` option to render it.
+ *
+ * @example
+ * ```tsx
+ * import { loader } from '@vezham/docs-core/source';
+ * import { statusBadgesPlugin } from '@vezham/docs-core/source/status-badges';
+ *
+ * export const source = loader({
+ *   plugins: [
+ *     statusBadgesPlugin({
+ *       renderBadge: (status) => <span>{status}</span>,
+ *     }),
+ *   ],
+ *   // ...
+ * });
+ * ```
+ *
+ * Then in your frontmatter:
+ * ```yaml
+ * ---
+ * title: My Page
+ * status: new
+ * ---
+ * ```
+ */
+declare function statusBadgesPlugin(options?: {
+  renderBadge?: (status: string) => ReactNode;
+}): LoaderPlugin;
+//#endregion
+export { Folder, Item, Node, Separator, statusBadgesPlugin };

package/dist/source/plugins/status-badges.js

@@ -0,0 +1,52 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/source/plugins/status-badges.tsx
+/**
+* Plugin to add status badges to pages in the sidebar.
+*
+* This reads the `status` field from page frontmatter and adds it to the page tree item.
+* Define the `renderBadge` option to render it.
+*
+* @example
+* ```tsx
+* import { loader } from '@vezham/docs-core/source';
+* import { statusBadgesPlugin } from '@vezham/docs-core/source/status-badges';
+*
+* export const source = loader({
+*   plugins: [
+*     statusBadgesPlugin({
+*       renderBadge: (status) => <span>{status}</span>,
+*     }),
+*   ],
+*   // ...
+* });
+* ```
+*
+* Then in your frontmatter:
+* ```yaml
+* ---
+* title: My Page
+* status: new
+* ---
+* ```
+*/
+function statusBadgesPlugin(options = {}) {
+	const { renderBadge = (status) => /* @__PURE__ */ jsx("span", {
+		"data-status": status,
+		children: status
+	}) } = options;
+	return {
+		name: "fumadocs:status-badges",
+		transformPageTree: { file(node, filePath) {
+			if (!filePath) return node;
+			const file = this.storage.read(filePath);
+			if (file?.format === "page" && "status" in file.data && typeof file.data.status === "string") {
+				const status = file.data.status;
+				node.name = /* @__PURE__ */ jsxs(Fragment, { children: [node.name, renderBadge(status)] });
+				node.status = status;
+			}
+			return node;
+		} }
+	};
+}
+//#endregion
+export { statusBadgesPlugin };

package/dist/source/schema.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+//#region src/source/schema.d.ts
+/**
+ * Zod 4 schema
+ */
+declare const metaSchema: z.ZodObject<{
+  title: z.ZodOptional<z.ZodString>;
+  pages: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  pagesIndex: z.ZodOptional<z.ZodString>;
+  description: z.ZodOptional<z.ZodString>;
+  root: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+  defaultOpen: z.ZodOptional<z.ZodBoolean>;
+  collapsible: z.ZodOptional<z.ZodBoolean>;
+  icon: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type _JSONType = number | boolean | string | null | _JSONType[] | {
+  [key: string]: _JSONType;
+};
+/**
+ * Zod 4 schema
+ */
+declare const pageSchema: z.ZodObject<{
+  title: z.ZodString;
+  description: z.ZodOptional<z.ZodString>;
+  icon: z.ZodOptional<z.ZodString>;
+  full: z.ZodOptional<z.ZodBoolean>;
+  _openapi: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodCustom<_JSONType, _JSONType>>>;
+}, z.core.$strip>;
+//#endregion
+export { _JSONType, metaSchema, pageSchema };

package/dist/source/schema.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+//#region src/source/schema.ts
+/**
+* Zod 4 schema
+*/
+const metaSchema = z.object({
+	title: z.string().optional(),
+	pages: z.array(z.string()).optional(),
+	/** specify a index page for folder */
+	pagesIndex: z.string().optional(),
+	description: z.string().optional(),
+	root: z.union([z.boolean(), z.string()]).optional(),
+	defaultOpen: z.boolean().optional(),
+	collapsible: z.boolean().optional(),
+	icon: z.string().optional()
+});
+/**
+* Zod 4 schema
+*/
+const pageSchema = z.object({
+	title: z.string(),
+	description: z.string().optional(),
+	icon: z.string().optional(),
+	full: z.boolean().optional(),
+	_openapi: z.record(z.string(), z.custom()).optional()
+});
+//#endregion
+export { metaSchema, pageSchema };

package/dist/stringifier-B_QUcUyo.d.ts

@@ -0,0 +1,63 @@
+import { MdxJsxAttribute, MdxJsxExpressionAttribute, MdxJsxFlowElement, MdxJsxTextElement } from "mdast-util-mdx";
+import { Info, Options, State } from "mdast-util-to-markdown";
+import { Processor } from "unified";
+import { Nodes, Parents } from "mdast";
+//#region src/mdx-plugins/stringifier.d.ts
+declare module 'mdast' {
+  interface Data {
+    /**
+     * [Fumadocs: stringify] Extra info for stringifying the node:
+     * - `children-only`: only stringify its children.
+     * - `{ node }`: stringify as another node.
+     * - `{ text }`: the stringified form of node.
+     */
+    _stringify?: 'children-only' | {
+      node: Nodes;
+    } | {
+      text: string;
+    };
+  }
+}
+type Stringifier<Context> = ((this: Processor, node: Nodes, ctx: Context) => string) | ((node: Nodes, ctx: Context) => string);
+interface StringifyOptions<Context = undefined> extends Options {
+  /**
+   * Filter the elements to be included in the output:
+   *
+   * - `true`: include element & its children.
+   * - `children-only`: exclude element but keep its children.
+   * - `false`: exclude element & its children.
+   *
+   * Default:
+   *
+   * ```ts
+   * filterElement = (node) => {
+   *   switch (node.type) {
+   *     case 'mdxJsxFlowElement':
+   *     case 'mdxJsxTextElement':
+   *       switch (node.name) {
+   *         case 'File':
+   *         case 'TypeTable':
+   *         case 'Callout':
+   *         case 'Card':
+   *           return true;
+   *       }
+   *       return 'children-only';
+   *   }
+   *
+   *   return true;
+   * },
+   * ```
+   */
+  filterElement?: (node: Nodes) => boolean | 'children-only';
+  /**
+   * Filter the attributes to stringify.
+   */
+  filterMdxAttributes?: (node: MdxJsxFlowElement | MdxJsxTextElement, attribute: MdxJsxAttribute | MdxJsxExpressionAttribute) => boolean;
+  /**
+   * override default stringifier
+   */
+  stringify?: (node: Nodes, parent: Parents | undefined, state: State, info: Info, ctx: Context) => string | undefined;
+}
+declare function defaultStringifier<Context = undefined>(config?: StringifyOptions<Context>): Stringifier<Context>;
+//#endregion
+export { StringifyOptions as n, defaultStringifier as r, Stringifier as t };

package/dist/toc-CtW5lwA1.d.ts

@@ -0,0 +1,64 @@
+import { ComponentProps, ReactNode, RefObject } from "react";
+//#region src/toc.d.ts
+interface TOCItemType {
+  title: ReactNode;
+  url: string;
+  depth: number;
+  /** [remark-steps] the step number */
+  _step?: number;
+}
+type TableOfContents = TOCItemType[];
+interface TOCItemInfo {
+  id: string;
+  active: boolean;
+  /** last time the item is updated */
+  t: number;
+  /** currently active but not intersecting in viewport */
+  fallback: boolean;
+  original: TOCItemType;
+}
+interface AnchorProviderProps {
+  toc: TOCItemType[];
+  /**
+   * Only accept one active item at most
+   *
+   * @defaultValue false
+   */
+  single?: boolean;
+  children?: ReactNode;
+}
+interface ScrollProviderProps {
+  /**
+   * Scroll into the view of container when active
+   */
+  containerRef: RefObject<HTMLElement | null>;
+  children?: ReactNode;
+}
+/** Optional: add auto-scroll to TOC items. */
+declare function ScrollProvider({ containerRef, children }: ScrollProviderProps): import("react").JSX.Element;
+declare function AnchorProvider({ toc, single, children }: AnchorProviderProps): import("react").JSX.Element;
+interface TOCItemProps extends ComponentProps<'a'> {
+  autoScroll?: boolean;
+  onActiveChange?: (v: boolean) => void;
+}
+declare function TOCItem({ ref, onActiveChange, autoScroll, ...props }: TOCItemProps): import("react").JSX.Element;
+/** @returns static info object, useful for custom rendering logic */
+declare function useTOC(): {
+  get(): TOCItemInfo[];
+  listen: (listener: ChangeListener) => void;
+  unlisten: (listener: ChangeListener) => void;
+};
+declare function useTOCListener(listener: ChangeListener): void;
+declare function useTOCSelector<T>(select: (items: TOCItemInfo[]) => T, isEqual?: (a: T, b: T) => boolean): T;
+/**
+ * The estimated active heading ID
+ */
+declare function useActiveAnchor(): string | undefined;
+/**
+ * The id of visible anchors
+ */
+declare function useActiveAnchors(): string[];
+declare function useItems(): TOCItemInfo[];
+type ChangeListener = (items: TOCItemInfo[]) => void;
+//#endregion
+export { TOCItem as a, TOCItemType as c, useActiveAnchors as d, useItems as f, useTOCSelector as h, ScrollProviderProps as i, TableOfContents as l, useTOCListener as m, AnchorProviderProps as n, TOCItemInfo as o, useTOC as p, ScrollProvider as r, TOCItemProps as s, AnchorProvider as t, useActiveAnchor as u };

package/dist/toc.d.ts

@@ -0,0 +1,2 @@
+import { a as TOCItem, c as TOCItemType, d as useActiveAnchors, f as useItems, h as useTOCSelector, i as ScrollProviderProps, l as TableOfContents, m as useTOCListener, n as AnchorProviderProps, o as TOCItemInfo, p as useTOC, r as ScrollProvider, s as TOCItemProps, t as AnchorProvider, u as useActiveAnchor } from "./toc-CtW5lwA1.js";
+export { AnchorProvider, AnchorProviderProps, ScrollProvider, ScrollProviderProps, TOCItem, TOCItemInfo, TOCItemProps, TOCItemType, TableOfContents, useActiveAnchor, useActiveAnchors, useItems, useTOC, useTOCListener, useTOCSelector };

package/dist/toc.js

@@ -0,0 +1,245 @@
+"use client";
+import { t as isEqualShallow } from "./is-equal-LdLqRs0o.js";
+import { createContext, use, useEffect, useEffectEvent, useMemo, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+import scrollIntoView from "scroll-into-view-if-needed";
+//#region src/utils/merge-refs.ts
+function mergeRefs(...refs) {
+	return (value) => {
+		refs.forEach((ref) => {
+			if (typeof ref === "function") ref(value);
+			else if (ref != null) ref.current = value;
+		});
+	};
+}
+//#endregion
+//#region src/toc.tsx
+const ObserverContext = createContext(null);
+const ScrollContext = createContext(null);
+/** Optional: add auto-scroll to TOC items. */
+function ScrollProvider({ containerRef, children }) {
+	return /* @__PURE__ */ jsx(ScrollContext, {
+		value: containerRef,
+		children
+	});
+}
+function AnchorProvider({ toc, single = false, children }) {
+	const observer = useMemo(() => new Observer(), []);
+	observer.single = single;
+	useEffect(() => {
+		observer.setItems(toc);
+	}, [observer, toc]);
+	useEffect(() => {
+		observer.watch({ threshold: .9 });
+		return () => observer.unwatch();
+	}, [observer]);
+	return /* @__PURE__ */ jsx(ObserverContext, {
+		value: observer,
+		children
+	});
+}
+function TOCItem({ ref, onActiveChange = () => null, autoScroll = true, ...props }) {
+	const id = props.href ? getItemId(props.href) : null;
+	const containerRef = use(ScrollContext);
+	const anchorRef = useRef(null);
+	const isInitialRef = useRef(true);
+	const observer = useObserver();
+	const [active, setActive] = useState(() => observer.items.some((item) => item.id === id && item.active));
+	const onUpdate = useEffectEvent((items, initial) => {
+		const itemData = id ? items.find((item) => item.id === id) : null;
+		if (!itemData) return;
+		if (itemData.active !== active) {
+			setActive(itemData.active);
+			onActiveChange(itemData.active);
+		}
+		const anchor = anchorRef.current;
+		const container = containerRef?.current;
+		if (!autoScroll || !anchor || !container) return;
+		let lastActive;
+		for (const item of items) {
+			if (!item.active) continue;
+			if (!lastActive || lastActive.t < item.t) lastActive = item;
+		}
+		if (lastActive?.id === id) scrollIntoView(anchor, {
+			behavior: initial ? "instant" : "smooth",
+			block: "center",
+			inline: "center",
+			scrollMode: "always",
+			boundary: container
+		});
+	});
+	useEffect(() => {
+		if (autoScroll) onUpdate(observer.items, isInitialRef.current);
+		isInitialRef.current = false;
+	}, [observer, autoScroll]);
+	useEffect(() => {
+		const listener = (items) => onUpdate(items, false);
+		observer.listen(listener);
+		return () => observer.unlisten(listener);
+	}, [observer]);
+	return /* @__PURE__ */ jsx("a", {
+		ref: mergeRefs(anchorRef, ref),
+		"data-active": active,
+		...props
+	});
+}
+function useObserver() {
+	const observer = use(ObserverContext);
+	if (!observer) throw new Error(`Component must be used under the <AnchorProvider /> component.`);
+	return observer;
+}
+/** @returns static info object, useful for custom rendering logic */
+function useTOC() {
+	const observer = useObserver();
+	return useMemo(() => ({
+		get() {
+			return observer.items;
+		},
+		listen: observer.listen.bind(observer),
+		unlisten: observer.unlisten.bind(observer)
+	}), [observer]);
+}
+function useTOCListener(listener) {
+	const observer = useObserver();
+	const callback = useEffectEvent(listener);
+	useEffect(() => {
+		observer.listen(callback);
+		return () => observer.unlisten(callback);
+	}, [observer]);
+}
+function useTOCSelector(select, isEqual = isEqualShallow) {
+	const observer = useObserver();
+	const [value, setValue] = useState(() => select(observer.items));
+	useTOCListener((items) => {
+		const next = select(items);
+		if (!isEqual(value, next)) setValue(next);
+	});
+	return value;
+}
+/**
+* The estimated active heading ID
+*/
+function useActiveAnchor() {
+	return useTOCSelector((items) => {
+		let out;
+		for (const item of items) {
+			if (!item.active) continue;
+			if (!out || item.t > out.t) out = item;
+		}
+		return out?.id;
+	});
+}
+/**
+* The id of visible anchors
+*/
+function useActiveAnchors() {
+	return useTOCSelector((items) => {
+		const out = [];
+		for (const item of items) if (item.active) out.push(item.id);
+		return out;
+	});
+}
+function useItems() {
+	return useTOCSelector((items) => items);
+}
+function getItemId(url) {
+	if (url.startsWith("#")) return url.slice(1);
+	return null;
+}
+var Observer = class {
+	constructor() {
+		this.items = [];
+		this.single = false;
+		this.observer = null;
+		this.listeners = /* @__PURE__ */ new Set();
+	}
+	listen(listener) {
+		this.listeners.add(listener);
+	}
+	unlisten(listener) {
+		this.listeners.delete(listener);
+	}
+	setItems(newItems) {
+		const observer = this.observer;
+		if (observer) for (const item of this.items) {
+			const element = document.getElementById(item.id);
+			if (!element) continue;
+			observer.unobserve(element);
+		}
+		const next = [];
+		for (const item of newItems) {
+			const id = getItemId(item.url);
+			if (!id) continue;
+			next.push({
+				id,
+				active: false,
+				fallback: false,
+				t: 0,
+				original: item
+			});
+		}
+		this.update(next);
+		this.observeItems();
+	}
+	watch(options) {
+		if (this.observer) return;
+		this.observer = new IntersectionObserver(this.callback.bind(this), options);
+		this.observeItems();
+	}
+	unwatch() {
+		this.observer?.disconnect();
+		this.observer = null;
+	}
+	callback(entries) {
+		if (entries.length === 0) return;
+		let hasActive = false;
+		const updated = this.items.map((item) => {
+			const entry = entries.find((entry) => entry.target.id === item.id);
+			let active = entry ? entry.isIntersecting : item.active && !item.fallback;
+			if (this.single && hasActive) active = false;
+			if (item.active !== active) item = {
+				...item,
+				t: Date.now(),
+				active,
+				fallback: false
+			};
+			if (active) hasActive = true;
+			return item;
+		});
+		if (!hasActive && entries[0].rootBounds) {
+			const viewTop = entries[0].rootBounds.top;
+			let min = Number.MAX_VALUE;
+			let fallbackIdx = -1;
+			for (let i = 0; i < updated.length; i++) {
+				const element = document.getElementById(updated[i].id);
+				if (!element) continue;
+				const d = Math.abs(viewTop - element.getBoundingClientRect().top);
+				if (d < min) {
+					fallbackIdx = i;
+					min = d;
+				}
+			}
+			if (fallbackIdx !== -1) updated[fallbackIdx] = {
+				...updated[fallbackIdx],
+				active: true,
+				fallback: true,
+				t: Date.now()
+			};
+		}
+		this.update(updated);
+	}
+	observeItems() {
+		if (!this.observer) return;
+		for (const item of this.items) {
+			const element = document.getElementById(item.id);
+			if (!element) continue;
+			this.observer.observe(element);
+		}
+	}
+	update(next) {
+		this.items = next;
+		for (const listener of this.listeners) listener(next);
+	}
+};
+//#endregion
+export { AnchorProvider, ScrollProvider, TOCItem, useActiveAnchor, useActiveAnchors, useItems, useTOC, useTOCListener, useTOCSelector };

package/dist/transformer-icon-DlrneIS3.d.ts

@@ -0,0 +1,17 @@
+import { ShikiTransformer } from "shiki";
+//#region src/mdx-plugins/transformer-icon.d.ts
+type CodeBlockIcon = {
+  viewBox: string;
+  fill: string;
+  d: string;
+} | string;
+interface IconOptions {
+  shortcuts?: Record<string, string>;
+  extend?: Record<string, CodeBlockIcon>;
+}
+/**
+ * Inject icons to `icon` property (as HTML)
+ */
+declare function transformerIcon(options?: IconOptions): ShikiTransformer;
+//#endregion
+export { IconOptions as n, transformerIcon as r, CodeBlockIcon as t };

package/dist/types-D89QoQR-.d.ts

@@ -0,0 +1,4 @@
+//#region src/types.d.ts
+type Awaitable<T> = T | PromiseLike<T>;
+//#endregion
+export { Awaitable as t };

package/dist/url-BVHvi3_K.js

@@ -0,0 +1,29 @@
+//#region src/utils/url.tsx
+/**
+* The base path (Vite)
+*/
+const BASE_PATH = typeof import.meta.env !== "undefined" && typeof import.meta.env.BASE_URL === "string" ? import.meta.env.BASE_URL : "/";
+function join(...paths) {
+	let out = "";
+	for (let p of paths) {
+		if (out.length > 0) {
+			if (p.startsWith("/")) p = p.slice(1);
+			if (!out.endsWith("/")) out += "/";
+		}
+		out += p;
+	}
+	return out;
+}
+/**
+* normalize URL into the Fumadocs standard form (`/slug-1/slug-2`).
+*
+* This includes URLs with trailing slashes.
+*/
+function normalizeUrl(url) {
+	if (url.startsWith("http://") || url.startsWith("https://")) return url;
+	if (!url.startsWith("/")) url = "/" + url;
+	if (url.length > 1 && url.endsWith("/")) url = url.slice(0, -1);
+	return url;
+}
+//#endregion
+export { join as n, normalizeUrl as r, BASE_PATH as t };

package/dist/util-BDsqOxh3.d.ts

@@ -0,0 +1,6 @@
+import { Pluggable } from "unified";
+//#region src/content/mdx/util.d.ts
+type Thenable<T> = T | PromiseLike<T>;
+type ResolvePlugins = Thenable<Pluggable>[] | ((v: Pluggable[]) => Thenable<Pluggable>[]);
+//#endregion
+export { ResolvePlugins as t };

package/dist/util-DjBr9b3w.js

@@ -0,0 +1,8 @@
+//#region src/content/mdx/util.ts
+async function resolvePlugins(def, options = []) {
+	const list = (await Promise.all(def(Array.isArray(options) ? options : []))).filter((v) => v !== false);
+	if (typeof options === "function") return Promise.all(options(list));
+	return list;
+}
+//#endregion
+export { resolvePlugins as t };

package/dist/utils/use-media-query.d.ts

@@ -0,0 +1,4 @@
+//#region src/utils/use-media-query.d.ts
+declare function useMediaQuery(query: string, disabled?: boolean): boolean | null;
+//#endregion
+export { useMediaQuery };

package/dist/utils/use-media-query.js

@@ -0,0 +1,20 @@
+import { useEffect, useState } from "react";
+//#region src/utils/use-media-query.ts
+function useMediaQuery(query, disabled = false) {
+	const [isMatch, setMatch] = useState(null);
+	useEffect(() => {
+		if (disabled) return;
+		const mediaQueryList = window.matchMedia(query);
+		const handleChange = () => {
+			setMatch(mediaQueryList.matches);
+		};
+		handleChange();
+		mediaQueryList.addEventListener("change", handleChange);
+		return () => {
+			mediaQueryList.removeEventListener("change", handleChange);
+		};
+	}, [disabled, query]);
+	return isMatch;
+}
+//#endregion
+export { useMediaQuery };

package/dist/utils/use-on-change.d.ts

@@ -0,0 +1,9 @@
+//#region src/utils/use-on-change.d.ts
+/**
+ * @param value - state to watch
+ * @param onChange - when the state changed
+ * @param isUpdated - a function that determines if the state is updated
+ */
+declare function useOnChange<T>(value: T, onChange: (current: T, previous: T) => void, isUpdated?: (prev: T, current: T) => boolean): void;
+//#endregion
+export { useOnChange };

package/dist/utils/use-on-change.js

@@ -0,0 +1,17 @@
+import { t as isEqualShallow } from "../is-equal-LdLqRs0o.js";
+import { useState } from "react";
+//#region src/utils/use-on-change.ts
+/**
+* @param value - state to watch
+* @param onChange - when the state changed
+* @param isUpdated - a function that determines if the state is updated
+*/
+function useOnChange(value, onChange, isUpdated = (a, b) => !isEqualShallow(a, b)) {
+	const [prev, setPrev] = useState(value);
+	if (isUpdated(prev, value)) {
+		onChange(value, prev);
+		setPrev(value);
+	}
+}
+//#endregion
+export { useOnChange };