@vx-oss/docs-twoslash 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Fuma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# Fumadocs Twoslash
+
+Use Typescript Twoslash in Fumadocs.

package/dist/cache-fs.d.ts

@@ -0,0 +1,14 @@
+import { TwoslashTypesCache } from "@shikijs/twoslash";
+//#region src/cache-fs.d.ts
+interface FileSystemTypeResultCacheOptions {
+  /**
+   * The directory to store the cache files.
+   *
+   * @default '.next/cache/twoslash'
+   */
+  dir?: string;
+  cwd?: string;
+}
+declare function createFileSystemTypesCache(options?: FileSystemTypeResultCacheOptions): TwoslashTypesCache;
+//#endregion
+export { FileSystemTypeResultCacheOptions, createFileSystemTypesCache };

package/dist/cache-fs.js

@@ -0,0 +1,33 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as process from "node:process";
+//#region src/cache-fs.ts
+/**
+* Original: https://github.com/shikijs/shiki/blob/main/packages/vitepress-twoslash/src/cache-fs.ts
+*/
+function createFileSystemTypesCache(options = {}) {
+	const { cwd = process.cwd() } = options;
+	const dir = path.join(cwd, options.dir ?? ".next/cache/twoslash");
+	return {
+		init() {
+			try {
+				fs.mkdirSync(dir, { recursive: true });
+			} catch {}
+		},
+		read(code) {
+			const hash = createHash("SHA256").update(code).digest("hex").slice(0, 12);
+			const filePath = path.join(dir, `${hash}.json`);
+			if (!fs.existsSync(filePath)) return null;
+			return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+		},
+		write(code, data) {
+			const hash = createHash("SHA256").update(code).digest("hex").slice(0, 12);
+			const filePath = path.join(dir, `${hash}.json`);
+			const json = JSON.stringify(data);
+			fs.writeFileSync(filePath, json, "utf-8");
+		}
+	};
+}
+//#endregion
+export { createFileSystemTypesCache };

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { TransformerTwoslashIndexOptions, TwoslashTypesCache } from "@shikijs/twoslash";
+import { ShikiTransformer } from "shiki";
+//#region src/index.d.ts
+type TransformerTwoslashOptions = TransformerTwoslashIndexOptions;
+/**
+ * This transformer **must** be used with the `rehype-code` plugin of Fumadocs.
+ */
+declare function transformerTwoslash(_options?: TransformerTwoslashOptions): ShikiTransformer;
+//#endregion
+export { TransformerTwoslashOptions, type TwoslashTypesCache, transformerTwoslash };

package/dist/index.js

@@ -0,0 +1,120 @@
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { gfmFromMarkdown } from "mdast-util-gfm";
+import { defaultHandlers, toHast } from "mdast-util-to-hast";
+import { ShikiError } from "shiki/core";
+import { createTransformerFactory, rendererRich } from "@shikijs/twoslash";
+import { createTwoslasher } from "twoslash";
+//#region src/index.ts
+let cachedInstance;
+/**
+* This transformer **must** be used with the `rehype-code` plugin of Fumadocs.
+*/
+function transformerTwoslash(_options = {}) {
+	const ignoreClass = "nd-copy-ignore";
+	const { twoslashOptions = {}, rendererRich: rendererOptions, ...rest } = _options;
+	function lazyInstance() {
+		function get() {
+			return cachedInstance ??= createTwoslasher({
+				...twoslashOptions,
+				compilerOptions: {
+					moduleResolution: 100,
+					baseUrl: void 0,
+					...twoslashOptions.compilerOptions
+				}
+			});
+		}
+		const wrapper = (...args) => get()(...args);
+		wrapper.getCacheMap = () => get().getCacheMap();
+		return wrapper;
+	}
+	const renderer = rendererRich({
+		classExtra: ignoreClass,
+		queryRendering: "line",
+		renderMarkdown,
+		renderMarkdownInline,
+		...rendererOptions,
+		hast: {
+			hoverToken: { tagName: "Popup" },
+			hoverPopup: {
+				tagName: "PopupContent",
+				properties: { class: ignoreClass }
+			},
+			hoverCompose: ({ popup, token }) => [popup, {
+				type: "element",
+				tagName: "PopupTrigger",
+				properties: {},
+				children: [token]
+			}],
+			popupDocs: { class: "prose twoslash-popup-docs" },
+			popupTypes: {
+				tagName: "div",
+				class: "twoslash shiki fd-codeblock prose-no-margin",
+				children: (v) => {
+					if (v.length === 1 && v[0].type === "element" && v[0].tagName === "pre") return v;
+					return [{
+						type: "element",
+						tagName: "code",
+						properties: { class: "twoslash-popup-code" },
+						children: v
+					}];
+				}
+			},
+			popupDocsTags: { class: "prose twoslash-popup-docs twoslash-popup-docs-tags" },
+			nodesHighlight: { class: "highlighted-word twoslash-highlighted" },
+			...rendererOptions?.hast
+		}
+	});
+	const fn = renderer.lineQuery;
+	renderer.lineQuery = function(...args) {
+		const result = fn.call(this, ...args);
+		const child = result[0].children[0];
+		result[0].children[0] = {
+			type: "element",
+			tagName: "span",
+			children: [child]
+		};
+		return result;
+	};
+	return createTransformerFactory(lazyInstance(), renderer)({
+		explicitTrigger: true,
+		...rest
+	});
+}
+function renderMarkdown(md) {
+	const mdast = fromMarkdown(md.replace(/{@link (?<link>[^}]*)}/g, "$1"), { mdastExtensions: [gfmFromMarkdown()] });
+	const onCode = (lang, node) => {
+		return this.codeToHast(node.value, {
+			...this.options,
+			transformers: [],
+			meta: node.meta ? { __raw: node.meta } : {},
+			lang
+		}).children[0];
+	};
+	return toHast(mdast, { handlers: { code: (state, node) => {
+		const lang = node.lang;
+		if (!lang) return defaultHandlers.code(state, node);
+		try {
+			return onCode(lang, node);
+		} catch (e) {
+			const def = defaultHandlers.code(state, node);
+			if (e instanceof ShikiError) {
+				this.meta._fd_postprocess ??= [];
+				this.meta._fd_postprocess.push(async ({ highlighter }) => {
+					await highlighter.loadLanguage(lang);
+					Object.assign(def, onCode(lang, node));
+				});
+				return def;
+			}
+			if (e instanceof Error) console.error(`[@vx-oss/docs-twoslash] encountered an error when highlighting codeblock in a Twoslash popup: ${e.message}`);
+			return def;
+		}
+	} } }).children;
+}
+function renderMarkdownInline(md, context) {
+	const text = context === "tag:param" ? md.replace(/^(?<link>[\w$-]+)/, "`$1` ") : md;
+	const children = renderMarkdown.call(this, text);
+	if (children.length === 1 && children[0].type === "element" && children[0].tagName === "p") return children[0].children;
+	return children;
+}
+//#endregion
+export { transformerTwoslash };

package/dist/ui/index.d.ts

@@ -0,0 +1,11 @@
+import { ComponentProps, ReactNode } from "react";
+import { Popover } from "@base-ui/react/popover";
+//#region src/ui/popup.d.ts
+declare function Popup({ delay, children }: {
+  delay?: number;
+  children: ReactNode;
+}): import("react").JSX.Element;
+declare function PopupTrigger({ children, ...props }: ComponentProps<typeof Popover.Trigger>): import("react").JSX.Element;
+declare function PopupContent({ className, side, align, sideOffset, ref, ...props }: React.ComponentProps<typeof Popover.Popup> & Pick<React.ComponentProps<typeof Popover.Positioner>, 'align' | 'side' | 'sideOffset'>): import("react").JSX.Element;
+//#endregion
+export { Popup, PopupContent, PopupTrigger };

package/dist/ui/index.js

@@ -0,0 +1,72 @@
+"use client";
+import { createContext, useContext, useMemo, useRef, useState } from "react";
+import { Popover } from "@base-ui/react/popover";
+import { cn } from "cnfast";
+import { jsx } from "react/jsx-runtime";
+//#region src/ui/popup.tsx
+const PopupContext = createContext(void 0);
+function Popup({ delay = 300, children }) {
+	const [open, setOpen] = useState(false);
+	const openTimeoutRef = useRef(void 0);
+	const closeTimeoutRef = useRef(void 0);
+	return /* @__PURE__ */ jsx(Popover.Root, {
+		open,
+		onOpenChange: setOpen,
+		children: /* @__PURE__ */ jsx(PopupContext.Provider, {
+			value: useMemo(() => ({
+				open,
+				setOpen,
+				handleOpen(e) {
+					if (e.pointerType === "touch") return;
+					if (closeTimeoutRef.current) clearTimeout(closeTimeoutRef.current);
+					openTimeoutRef.current = window.setTimeout(() => {
+						setOpen(true);
+					}, delay);
+				},
+				handleClose(e) {
+					if (e.pointerType === "touch") return;
+					if (openTimeoutRef.current) clearTimeout(openTimeoutRef.current);
+					closeTimeoutRef.current = window.setTimeout(() => {
+						setOpen(false);
+					}, delay);
+				}
+			}), [delay, open]),
+			children
+		})
+	});
+}
+function PopupTrigger({ children, ...props }) {
+	const ctx = useContext(PopupContext);
+	if (!ctx) throw new Error("Missing Popup Context");
+	return /* @__PURE__ */ jsx(Popover.Trigger, {
+		onPointerEnter: ctx.handleOpen,
+		onPointerLeave: ctx.handleClose,
+		render: (triggerProps) => /* @__PURE__ */ jsx("button", {
+			...triggerProps,
+			type: "button",
+			className: cn("twoslash-hover", triggerProps.className),
+			children
+		}),
+		...props
+	});
+}
+function PopupContent({ className, side = "bottom", align = "center", sideOffset = 4, ref, ...props }) {
+	const ctx = useContext(PopupContext);
+	if (!ctx) throw new Error("Missing Popup Context");
+	return /* @__PURE__ */ jsx(Popover.Portal, { children: /* @__PURE__ */ jsx(Popover.Positioner, {
+		side,
+		align,
+		sideOffset,
+		children: /* @__PURE__ */ jsx(Popover.Popup, {
+			ref,
+			className: cn("fd-twoslash-popover", className),
+			onPointerEnter: ctx.handleOpen,
+			onPointerLeave: ctx.handleClose,
+			initialFocus: false,
+			finalFocus: false,
+			...props
+		})
+	}) });
+}
+//#endregion
+export { Popup, PopupContent, PopupTrigger };

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@vx-oss/docs-twoslash",
+  "version": "1.0.3",
+  "description": "Typescript Twoslash Integration for Fumadocs",
+  "keywords": [
+    "Docs",
+    "fumadocs"
+  ],
+  "homepage": "https://vezham.com",
+  "license": "MIT",
+  "author": "Fuma Nama",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vezham/fumadocs",
+    "directory": "packages/twoslash"
+  },
+  "files": [
+    "dist",
+    "styles"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./twoslash.css": "./styles/twoslash.css",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./ui": {
+      "types": "./dist/ui/index.d.ts",
+      "import": "./dist/ui/index.js"
+    },
+    "./cache-fs": {
+      "types": "./dist/cache-fs.d.ts",
+      "import": "./dist/cache-fs.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.7.0",
+    "@shikijs/twoslash": "^4.4.3",
+    "cnfast": "^0.1.0",
+    "mdast-util-from-markdown": "^2.0.3",
+    "mdast-util-gfm": "^3.1.0",
+    "mdast-util-to-hast": "^13.2.1",
+    "twoslash": "^0.3.9"
+  },
+  "devDependencies": {
+    "@types/hast": "^3.0.5",
+    "@types/mdast": "^4.0.4",
+    "@types/node": "26.3.0",
+    "@types/react": "^19.2.18",
+    "shiki": "4.4.3",
+    "tsdown": "0.22.14",
+    "typescript": "^6.0.3",
+    "@vx-oss/docs-react": "1.0.3",
+    "@vx-oss/docs-core": "1.0.3",
+    "tsconfig": "0.0.1"
+  },
+  "peerDependencies": {
+    "@types/react": "*",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "shiki": "4.x.x",
+    "@vx-oss/docs-core": "^1.0.1",
+    "@vx-oss/docs-react": "^1.0.1"
+  },
+  "peerDependenciesMeta": {
+    "@types/react": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "clean": "rimraf dist",
+    "dev": "tsdown --watch",
+    "lint": "oxlint .",
+    "types:check": "tsc --noEmit"
+  }
+}

package/styles/twoslash.css

@@ -0,0 +1,225 @@
+/* ===== Basic ===== */
+@theme {
+  --color-twoslash-error-foreground: #d45656;
+  --color-twoslash-error: #d4565620;
+  --color-twoslash-tag-foreground: #3772cf;
+  --color-twoslash-tag: #3772cf20;
+  --color-twoslash-tag-warn-foreground: #c37d0d;
+  --color-twoslash-tag-warn: #c37d0d20;
+  --color-twoslash-tag-annotate-foreground: #1ba673;
+  --color-twoslash-tag-annotate: #1ba67320;
+}
+
+.twoslash-meta-line {
+  display: flex;
+}
+
+.twoslash-completion-list,
+.twoslash-popup-container {
+  position: relative;
+  user-select: none;
+  display: flex;
+  margin-top: 8px;
+  width: 20rem;
+  margin-right: -20rem;
+  flex-direction: column;
+  white-space: normal;
+  box-shadow:
+    0 4px 6px -1px rgb(0 0 0 / 0.1),
+    0 2px 4px -2px rgb(0 0 0 / 0.1);
+  border: 1px solid var(--color-fd-border);
+  border-radius: 6px;
+  padding: 8px;
+  z-index: 8;
+  color: var(--color-fd-popover-foreground);
+  background-color: var(--color-fd-popover);
+}
+
+.twoslash-completion-cursor {
+  display: inline-flex;
+  flex-direction: column;
+}
+
+.twoslash-completion-list:hover {
+  user-select: auto;
+}
+
+.twoslash-popup-arrow {
+  position: absolute;
+  top: -4px;
+  left: 1em;
+  transform: rotate(-45deg);
+  pointer-events: none;
+  width: 6px;
+  height: 6px;
+  border-top-width: 1px;
+  border-right-width: 1px;
+  border-color: var(--color-fd-primary);
+  background-color: var(--color-fd-popover);
+}
+
+.twoslash-popup-docs-tag {
+  display: flex;
+  flex-direction: row;
+  gap: 0.5em;
+}
+
+.twoslash-popup-docs-tag-name {
+  font-weight: 600;
+}
+
+.twoslash-popup-code {
+  font-size: 13px !important;
+  overflow-wrap: anywhere;
+}
+
+.twoslash-popup-code .line {
+  padding-left: 0 !important;
+}
+
+.twoslash-popup-docs,
+.twoslash-popup-docs-tags {
+  font-size: 14px !important;
+  line-height: 20px !important;
+  margin-top: 8px !important;
+}
+
+/* ===== Hover Info ===== */
+.twoslash:hover .twoslash-hover {
+  border-color: currentColor;
+}
+
+.twoslash .twoslash-hover {
+  /* Reset button styles to make it behave like inline text */
+  all: unset;
+
+  /* Restore the original hover indicator styles */
+  position: relative;
+  transition: border 300ms;
+  border-bottom: 1px dotted;
+  border-color: transparent;
+}
+
+/* ===== Error Line ===== */
+.twoslash .twoslash-error-line {
+  position: relative;
+  background-color: var(--twoslash-error-bg);
+  border-left: 3px solid var(--color-twoslash-error-foreground);
+  color: var(--color-twoslash-error-foreground);
+  padding: 6px 12px;
+  margin: 0.2em 0;
+}
+
+.twoslash .twoslash-error {
+  text-decoration: wavy underline var(--color-twoslash-error-foreground);
+  padding-bottom: 2px;
+}
+
+/* ===== Completions ===== */
+.twoslash-completion-cursor::before {
+  width: 1px;
+  height: 1.4em;
+  content: ' ';
+  background-color: var(--color-fd-foreground);
+}
+
+.twoslash-completion-list {
+  display: inline-flex;
+}
+
+.twoslash-completion-list li {
+  font-size: 13px;
+  display: inline-flex;
+  align-items: center;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  gap: 0.5rem;
+}
+
+.twoslash-completion-list li span.twoslash-completions-unmatched {
+  color: var(--color-fd-muted-foreground);
+}
+
+.twoslash-completion-list .deprecated {
+  text-decoration: line-through;
+  opacity: 0.5;
+}
+
+/* Icons */
+.twoslash-completion-list .twoslash-completions-icon {
+  width: 1em;
+  flex: none;
+  color: var(--color-fd-muted-foreground);
+}
+
+/* Custom Tags */
+.twoslash .twoslash-tag-line {
+  position: relative;
+  background-color: var(--color-twoslash-tag);
+  border-left: 3px solid var(--color-twoslash-tag-foreground);
+  color: var(--color-twoslash-tag-foreground);
+  padding: 6px 10px;
+  margin: 0.2em 0;
+  display: flex;
+  align-items: center;
+  gap: 0.3em;
+}
+
+.twoslash .twoslash-tag-line .twoslash-tag-icon {
+  width: 1.1em;
+  color: inherit;
+}
+
+.twoslash .twoslash-tag-line.twoslash-tag-error-line {
+  background-color: var(--color-twoslash-error);
+  border-left: 3px solid var(--color-twoslash-error-foreground);
+  color: var(--color-twoslash-error-foreground);
+}
+
+.twoslash .twoslash-tag-line.twoslash-tag-warn-line {
+  background-color: var(--color-twoslash-tag-warn);
+  border-left: 3px solid var(--color-twoslash-tag-warn-foreground);
+  color: var(--color-twoslash-tag-warn-foreground);
+}
+
+.twoslash .twoslash-tag-line.twoslash-tag-annotate-line {
+  background-color: var(--color-twoslash-tag-annotate);
+  border-left: 3px solid var(--color-twoslash-tag-annotate-foreground);
+  color: var(--color-twoslash-tag-annotate-foreground);
+}
+
+/* Respect people's wishes to not have animations */
+@media (prefers-reduced-motion: reduce) {
+  .twoslash * {
+    transition: none !important;
+  }
+}
+
+.fd-twoslash-popover {
+  z-index: 50;
+  min-width: 240px;
+  max-width: min(450px, 96vw);
+  max-height: 400px;
+  overflow: auto;
+  border-radius: var(--radius-xl);
+  border: 1px solid var(--color-fd-border);
+  background-color: var(--color-fd-popover);
+  padding: calc(var(--spacing) * 3);
+  font-size: var(--text-sm);
+  color: var(--color-fd-popover-foreground);
+  box-shadow: var(--shadow-md);
+  transform-origin: var(--transform-origin);
+}
+
+.fd-twoslash-popover[data-open] {
+  animation: var(--animate-fd-popover-in);
+}
+
+.fd-twoslash-popover[data-closed] {
+  animation: var(--animate-fd-popover-out);
+}
+
+.fd-twoslash-popover:focus-visible {
+  outline-style: none;
+}