@deot/docs-markdown 1.1.0 → 1.1.2

package/dist/index.js

@@ -1,4 +1,4 @@
-import { Fragment, computed, createApp, createBlock, createCommentVNode, createElementBlock, createElementVNode, defineComponent, h, inject, nextTick, normalizeClass, normalizeStyle, onBeforeUnmount, openBlock, ref, renderList, shallowRef, toDisplayString, unref, watch, withDirectives } from "vue";
+import { Fragment, computed, createApp, createBlock, createCommentVNode, createElementBlock, createElementVNode, defineComponent, h, inject, nextTick, normalizeClass, normalizeStyle, onBeforeUnmount, onMounted, openBlock, ref, renderList, shallowRef, toDisplayString, unref, watch, withDirectives } from "vue";
 import { provideLocale, useLocale } from "@deot/docs-locale";
 import Config from "markdown-it-chain";
 import anchor from "markdown-it-anchor";
@@ -9,9 +9,11 @@ import { getScroller } from "@deot/helper-dom";
 //#region packages/markdown/src/markdown.ts
 var HTML_MD_SIGN = "md";
 var PLAYGROUND = "playground";
+var TABS = "tabs";
 var TIP = "tip";
 var WARNING = "warning";
 var CALLOUT_FILLED_RE = /(^|\s)filled(\s|$)/;
+var TAB_MARKDOWN_INFO_RE = /^markdown(?:\s+(.*))?$/i;
 var CALLOUT_INFO_ICON = [
 	"<svg width=\"22\" height=\"28\" viewBox=\"0 0 22 28\" fill=\"none\" aria-hidden=\"true\">",
 	"<circle class=\"docs-markdown-callout-icon__fill\" cx=\"11\" cy=\"14\" r=\"11\"></circle>",
@@ -44,9 +46,13 @@ config.options.html(true).typographer(true).linkify(true).end().plugin("anchor")
 	placement: "before",
 	symbol: "#"
 }) }]).end().plugin("container").use(($md) => {
-	const reg = new RegExp(`^${PLAYGROUND}\\s*(.*)$`);
+	const playgroundReg = new RegExp(`^${PLAYGROUND}\\s*(.*)$`);
 	$md.use(mdContainer, PLAYGROUND, { validate(params) {
-		return params.trim().match(reg);
+		return params.trim().match(playgroundReg);
+	} });
+	const tabsReg = new RegExp(`^${TABS}\\s*$`);
+	$md.use(mdContainer, TABS, { validate(params) {
+		return tabsReg.test(params.trim());
 	} });
 	$md.use(mdContainer, TIP, { render: renderCallout(TIP, CALLOUT_INFO_ICON) });
 	$md.use(mdContainer, WARNING, { render: renderCallout(WARNING, CALLOUT_WARNING_ICON) });
@@ -54,9 +60,33 @@ config.options.html(true).typographer(true).linkify(true).end().plugin("anchor")
 var md = config.toMd(markdownIt);
 var playgroundOpen = `container_${PLAYGROUND}_open`;
 var playgroundClose = `container_${PLAYGROUND}_close`;
+var tabsOpen = `container_${TABS}_open`;
+var tabsClose = `container_${TABS}_close`;
 var htmlCommentRE = /<!--([\s\S]*?)-->/g;
 var runtimeConfigRE = /<config\s+lang\s*=\s*["']json5["']\s*>([\s\S]*?)<\/config>/i;
 var renderPlaygroundError = (message) => `<div class="docs-playground-error">PLAYGROUND: ${md.utils.escapeHtml(message)}</div>\n`;
+var renderTabsError = (message) => `<div class="docs-markdown-tabs-error">TABS: ${md.utils.escapeHtml(message)}</div>\n`;
+/**
+* 从 fence info 解析 Tab 显示名：去掉可选的 `markdown` 语言前缀。
+* @param info fence 的 info 字符串，如 `markdown Linux` 或 `Android`。
+* @returns 显示标题（可能为空）。
+*/
+var parseTabFenceTitle = (info) => {
+	const trimmed = info.trim();
+	const match = trimmed.match(TAB_MARKDOWN_INFO_RE);
+	if (match) return (match[1] || "").trim();
+	return trimmed;
+};
+/**
+* 生成 `?tab=` 使用的 id：小写、空白变 `-`；含非 ASCII 时与标题锚点一致做 encodeURIComponent。
+* @param title Tab 显示名。
+* @returns 可写入 query 的 id；标题为空时返回空串。
+*/
+var toMarkdownTabId = (title) => {
+	const normalized = title.trim().toLowerCase().replace(/\s+/gu, "-");
+	if (!normalized) return "";
+	return /[^\x20-\x7E]/u.test(normalized) ? encodeURIComponent(normalized) : normalized;
+};
 var PLAYGROUND_VIEWS = ["runtime", "files"];
 var isPlaygroundView = (value) => typeof value === "string" && PLAYGROUND_VIEWS.includes(value);
 var isRuntimeViewport = (viewport) => {
@@ -113,6 +143,11 @@ var validateTitleId = (propsData) => {
 	if (typeof propsData.id === "string") return "";
 	return "id 必须是字符串";
 };
+var validatePreviewScroller = (propsData) => {
+	if (!("previewScroller" in propsData)) return "";
+	if (typeof propsData.previewScroller === "boolean") return "";
+	return "previewScroller 必须是布尔值";
+};
 var parseRuntimeProps = (tokens) => {
 	for (const token of tokens) {
 		const sources = [];
@@ -134,7 +169,61 @@ var parseRuntimeProps = (tokens) => {
 	return {};
 };
 var renderPlaygroundAttrs = (propsData) => `data-props="${md.utils.escapeHtml(JSON.stringify(propsData))}"`;
-md.core.ruler.after("block", "runtime-files", (state) => {
+var renderTabsHtml = (panels) => {
+	const parts = ["<div class=\"docs-markdown-tabs\" md data-tabs>", "<div class=\"docs-markdown-tabs__nav\" data-tabs-nav></div>"];
+	panels.forEach((panel, index) => {
+		const hidden = index === 0 ? "" : " hidden";
+		const id = md.utils.escapeHtml(panel.id);
+		const title = md.utils.escapeHtml(panel.title);
+		parts.push(`<div class="docs-markdown-tabs__panel" role="tabpanel" data-tab="${id}" data-tab-title="${title}"${hidden}>`, md.render(panel.content), "</div>");
+	});
+	parts.push("</div>\n");
+	return parts.join("");
+};
+md.core.ruler.after("block", "markdown-tabs", (state) => {
+	const panelSources = Array.isArray(state.env?.tabsPanelSources) ? state.env.tabsPanelSources : void 0;
+	for (let index = 0; index < state.tokens.length; index++) {
+		if (state.tokens[index].type !== tabsOpen) continue;
+		let depth = 1;
+		let closeIndex = index + 1;
+		for (; closeIndex < state.tokens.length; closeIndex++) {
+			if (state.tokens[closeIndex].type === tabsOpen) depth++;
+			if (state.tokens[closeIndex].type === tabsClose) depth--;
+			if (depth === 0) break;
+		}
+		const fences = state.tokens.slice(index + 1, closeIndex).filter((token) => token.type === "fence");
+		const placeholder = new state.Token("html_block", "", 0);
+		placeholder.block = true;
+		if (!fences.length) placeholder.content = renderTabsError("至少需要声明一个分栏");
+		else {
+			const panels = [];
+			const seen = /* @__PURE__ */ new Set();
+			let error = "";
+			for (const fence of fences) {
+				const title = parseTabFenceTitle(fence.info);
+				const id = toMarkdownTabId(title);
+				if (!title || !id) {
+					error = "每个分栏都必须声明标题";
+					break;
+				}
+				if (seen.has(id)) {
+					error = `分栏 ${title} 的 id 重复`;
+					break;
+				}
+				seen.add(id);
+				panels.push({
+					id,
+					title,
+					content: fence.content
+				});
+				panelSources?.push(fence.content);
+			}
+			placeholder.content = error ? renderTabsError(error) : renderTabsHtml(panels);
+		}
+		state.tokens.splice(index, closeIndex - index + 1, placeholder);
+	}
+});
+md.core.ruler.after("markdown-tabs", "runtime-files", (state) => {
 	for (let index = 0; index < state.tokens.length; index++) {
 		if (state.tokens[index].type !== playgroundOpen) continue;
 		let depth = 1;
@@ -149,7 +238,7 @@ md.core.ruler.after("block", "runtime-files", (state) => {
 		const placeholder = new state.Token("html_block", "", 0);
 		placeholder.block = true;
 		const propsData = parseRuntimeProps(innerTokens);
-		const propsError = validateRuntimeViews(propsData) || validateRuntimeViewport(propsData) || validatePreviewInset(propsData) || validateExpandable(propsData) || validateTitle(propsData) || validateTitleId(propsData);
+		const propsError = validateRuntimeViews(propsData) || validateRuntimeViewport(propsData) || validatePreviewInset(propsData) || validateExpandable(propsData) || validateTitle(propsData) || validateTitleId(propsData) || validatePreviewScroller(propsData);
 		const propsAttr = renderPlaygroundAttrs(propsData);
 		if (!fences.length) placeholder.content = renderPlaygroundError("至少需要声明一个代码文件");
 		else if (propsError) placeholder.content = renderPlaygroundError(propsError);
@@ -187,7 +276,7 @@ md.core.ruler.after("block", "runtime-files", (state) => {
 });
 var renderAttrs = md.renderer.renderAttrs;
 md.renderer.renderAttrs = (token) => {
-	const reg = new RegExp(`container_${PLAYGROUND}|fence|text`);
+	const reg = new RegExp(`container_${PLAYGROUND}|container_${TABS}|fence|text`);
 	if (token.nesting !== -1 && token.type && !reg.test(token.type)) token.attrPush([HTML_MD_SIGN, ""]);
 	return renderAttrs(token);
 };
@@ -215,32 +304,39 @@ var getInlineSearchText = (token) => {
 * @returns 文档标题、正文和按标题划分的小节。
 */
 var parseMarkdownSearchSections = (content) => {
-	const tokens = md.parse(content, {});
 	const sections = [];
 	const documentParts = [];
 	let activeSection;
-	for (let index = 0; index < tokens.length; index++) {
-		const token = tokens[index];
-		if (token.type === "heading_open") {
-			const inline = tokens[index + 1];
-			if (inline?.type !== "inline") continue;
-			const title = getInlineSearchText(inline);
-			if (!title) continue;
-			activeSection = {
-				title,
-				anchor: token.attrGet("id") || "",
-				level: Number(token.tag.slice(1)) || 1,
-				text: ""
-			};
-			sections.push(activeSection);
-			continue;
-		}
-		if (token.type !== "inline" || tokens[index - 1]?.type === "heading_open") continue;
-		const text = getInlineSearchText(token);
-		if (!text) continue;
+	const consumeInline = (text) => {
+		if (!text) return;
 		documentParts.push(text);
 		if (activeSection) activeSection.text = normalizeSearchText(`${activeSection.text} ${text}`);
-	}
+	};
+	const walk = (source, withHeadings) => {
+		const tabsPanelSources = [];
+		const tokens = md.parse(source, { tabsPanelSources });
+		for (let index = 0; index < tokens.length; index++) {
+			const token = tokens[index];
+			if (withHeadings && token.type === "heading_open") {
+				const inline = tokens[index + 1];
+				if (inline?.type !== "inline") continue;
+				const title = getInlineSearchText(inline);
+				if (!title) continue;
+				activeSection = {
+					title,
+					anchor: token.attrGet("id") || "",
+					level: Number(token.tag.slice(1)) || 1,
+					text: ""
+				};
+				sections.push(activeSection);
+				continue;
+			}
+			if (token.type !== "inline" || tokens[index - 1]?.type === "heading_open") continue;
+			consumeInline(getInlineSearchText(token));
+		}
+		for (const panelSource of tabsPanelSources) walk(panelSource, false);
+	};
+	walk(content, true);
 	return {
 		title: sections.find((section) => section.level === 1)?.title || sections[0]?.title || "",
 		text: normalizeSearchText(documentParts.join(" ")),
@@ -248,11 +344,137 @@ var parseMarkdownSearchSections = (content) => {
 	};
 };
 //#endregion
+//#region packages/markdown/src/tab-query.ts
+var markdownTabQueryKey = Symbol("docs-markdown-tab-query");
+var TAB_QUERY = "tab";
+/**
+* 不依赖 Vue Router 的默认适配器：读写 `location.search` 的 `tab`，
+* 并用 `history.replaceState` 更新（供 examples / 单测使用）。
+* @returns 可注入 TabsNav 的 get/set/subscribe 适配器。
+*/
+var createHistoryTabQueryAdapter = () => {
+	const read = () => {
+		try {
+			return new URLSearchParams(window.location.search).get(TAB_QUERY) || "";
+		} catch {
+			return "";
+		}
+	};
+	const write = (tab) => {
+		try {
+			const url = new URL(window.location.href);
+			if (tab) url.searchParams.set(TAB_QUERY, tab);
+			else url.searchParams.delete(TAB_QUERY);
+			window.history.replaceState(window.history.state, "", `${url.pathname}${url.search}${url.hash}`);
+		} catch {}
+	};
+	return {
+		get: read,
+		set: write,
+		subscribe: (listener) => {
+			const onPopState = () => listener();
+			window.addEventListener("popstate", onPopState);
+			return () => window.removeEventListener("popstate", onPopState);
+		}
+	};
+};
+//#endregion
+//#region packages/markdown/src/tabs-nav.vue?vue&type=script&setup=true&lang.ts
+var _hoisted_1$1 = ["aria-label"];
+var _hoisted_2$1 = [
+	"id",
+	"aria-selected",
+	"aria-controls",
+	"tabindex",
+	"onClick"
+];
+//#endregion
+//#region packages/markdown/src/tabs-nav.vue
+var tabs_nav_default = /* @__PURE__ */ defineComponent({
+	__name: "tabs-nav",
+	props: {
+		items: {},
+		label: {},
+		adapter: {},
+		root: {},
+		groupId: {}
+	},
+	setup(__props) {
+		const props = __props;
+		const activeId = ref("");
+		let unsubscribe;
+		const tabButtonId = (id) => `${props.groupId}-tab-${id}`;
+		const tabPanelId = (id) => `${props.groupId}-panel-${id}`;
+		const resolveActive = () => {
+			const fromQuery = props.adapter.get();
+			const matched = props.items.find((item) => item.id === fromQuery);
+			activeId.value = matched?.id || props.items[0]?.id || "";
+		};
+		const syncPanels = () => {
+			props.root.querySelectorAll(".docs-markdown-tabs__panel").forEach((panel) => {
+				const id = panel.dataset.tab || "";
+				const selected = id === activeId.value;
+				panel.hidden = !selected;
+				panel.setAttribute("aria-labelledby", tabButtonId(id));
+				if (selected) {
+					panel.removeAttribute("hidden");
+					panel.id = tabPanelId(id);
+				} else {
+					panel.setAttribute("hidden", "");
+					panel.id = tabPanelId(id);
+				}
+			});
+		};
+		const select = (id) => {
+			if (!id) return;
+			activeId.value = id;
+			props.adapter.set(id);
+			syncPanels();
+		};
+		onMounted(() => {
+			resolveActive();
+			syncPanels();
+			unsubscribe = props.adapter.subscribe?.(() => {
+				resolveActive();
+				syncPanels();
+			});
+		});
+		onBeforeUnmount(() => {
+			unsubscribe?.();
+			unsubscribe = void 0;
+		});
+		watch(() => props.items.map((item) => item.id).join("\0"), () => {
+			resolveActive();
+			syncPanels();
+		});
+		return (_ctx, _cache) => {
+			return openBlock(), createElementBlock("div", {
+				class: "docs-markdown-tabs__list",
+				role: "tablist",
+				"aria-label": __props.label
+			}, [(openBlock(true), createElementBlock(Fragment, null, renderList(__props.items, (item) => {
+				return openBlock(), createElementBlock("button", {
+					key: item.id,
+					type: "button",
+					class: normalizeClass(["docs-markdown-tabs__tab", { "docs-markdown-tabs__tab--active": item.id === activeId.value }]),
+					role: "tab",
+					id: tabButtonId(item.id),
+					"aria-selected": item.id === activeId.value,
+					"aria-controls": tabPanelId(item.id),
+					tabindex: item.id === activeId.value ? 0 : -1,
+					onClick: ($event) => select(item.id)
+				}, toDisplayString(item.title), 11, _hoisted_2$1);
+			}), 128))], 8, _hoisted_1$1);
+		};
+	}
+});
+//#endregion
 //#region packages/markdown/src/directive.ts
 var mountedApps = /* @__PURE__ */ new WeakMap();
 var renderVersions = /* @__PURE__ */ new WeakMap();
 var playgroundModule;
 var loadPlayground = () => playgroundModule ||= import("@deot/docs-playground");
+var defaultTabQuery = createHistoryTabQueryAdapter();
 var cleanup = (el) => {
 	for (const app of mountedApps.get(el) || []) app.unmount();
 	mountedApps.delete(el);
@@ -261,12 +483,36 @@ var resolveBlockLanguage = (block) => {
 	return [...block.classList].find((className) => className.startsWith("language-"))?.slice(9) || "";
 };
 var serializePlaygroundDefaults = (value) => JSON.stringify(value || {});
+var mountTabs = (el, apps, locale, adapter) => {
+	const label = locale.markdown?.tabs?.label || "Tabs";
+	el.querySelectorAll("[data-tabs]").forEach((root, index) => {
+		const nav = root.querySelector("[data-tabs-nav]");
+		if (!nav) return;
+		const items = [...root.querySelectorAll(".docs-markdown-tabs__panel")].map((panel) => ({
+			id: panel.dataset.tab || "",
+			title: panel.dataset.tabTitle || panel.dataset.tab || ""
+		})).filter((item) => item.id && item.title);
+		if (!items.length) return;
+		const groupId = `docs-markdown-tabs-${index}`;
+		const app = createApp({ render: () => h(tabs_nav_default, {
+			items,
+			label,
+			adapter,
+			root,
+			groupId
+		}) });
+		app.mount(nav);
+		apps.push(app);
+	});
+};
 var render = async (el, binding) => {
 	cleanup(el);
 	const version = (renderVersions.get(el) || 0) + 1;
 	renderVersions.set(el, version);
 	el.innerHTML = binding.value.source ? Markdown.render(binding.value.source) : "";
 	const apps = [];
+	const adapter = binding.value.tabQuery || defaultTabQuery;
+	mountTabs(el, apps, binding.value.locale, adapter);
 	const blocks = el.querySelectorAll("pre code");
 	const playgrounds = el.querySelectorAll("div[data-playground]");
 	if (!blocks.length && !playgrounds.length) {
@@ -316,7 +562,7 @@ var render = async (el, binding) => {
 	mountedApps.set(el, apps);
 };
 var update = (el, binding) => {
-	if (binding.value.source !== binding.oldValue?.source || binding.value.locale !== binding.oldValue?.locale || serializePlaygroundDefaults(binding.value.playground) !== serializePlaygroundDefaults(binding.oldValue?.playground)) render(el, binding);
+	if (binding.value.source !== binding.oldValue?.source || binding.value.locale !== binding.oldValue?.locale || binding.value.tabQuery !== binding.oldValue?.tabQuery || serializePlaygroundDefaults(binding.value.playground) !== serializePlaygroundDefaults(binding.oldValue?.playground)) render(el, binding);
 };
 var vMarkdown = {
 	mounted: (el, binding) => void render(el, binding),
@@ -427,7 +673,13 @@ var getIndicatorInlineOffset = (root, rail, side, viewportWidth) => {
 //#endregion
 //#region packages/markdown/src/headings.ts
 var HEADING_SELECTOR = "h1[id], h2[id], h3[id], h4[id], h5[id], h6[id]";
-var SKIP_CLOSEST = "pre, .docs-markdown-code-preview, [data-playground][data-code], [data-playground][data-files]";
+var SKIP_CLOSEST = [
+	"pre",
+	".docs-markdown-code-preview",
+	"[data-playground][data-code]",
+	"[data-playground][data-files]",
+	".docs-markdown-tabs__panel[hidden]"
+].join(", ");
 /**
 * 去掉 markdown-it-anchor 的井号后，读取标题的可见文案。
 * @param element 当前标题节点。
@@ -972,6 +1224,7 @@ var wrapper_default = /* @__PURE__ */ defineComponent({
 		locale: {},
 		theme: { default: "default" },
 		playground: { default: () => ({}) },
+		tabQuery: {},
 		modelValue: {},
 		value: {}
 	},
@@ -987,11 +1240,15 @@ var wrapper_default = /* @__PURE__ */ defineComponent({
 			return typeof props.indicator === "object" ? props.indicator : {};
 		});
 		const resolvedTheme = computed(() => props.theme === "traditional" ? "traditional" : "default");
+		const injectedTabQuery = inject(markdownTabQueryKey, null);
+		const historyTabQuery = createHistoryTabQueryAdapter();
+		const resolvedTabQuery = computed(() => props.tabQuery || injectedTabQuery || historyTabQuery);
 		const source = computed(() => typeof props.modelValue === "string" ? props.modelValue : props.value);
 		const markdownBinding = computed(() => ({
 			source: source.value,
 			locale: locale.value,
-			playground: props.playground
+			playground: props.playground,
+			tabQuery: resolvedTabQuery.value
 		}));
 		return (_ctx, _cache) => {
 			return openBlock(), createElementBlock("div", { class: normalizeClass(["docs-markdown", `docs-markdown--${resolvedTheme.value}`]) }, [indicatorOptions.value && content.value ? (openBlock(), createBlock(indicator_default, {
@@ -1007,4 +1264,4 @@ var wrapper_default = /* @__PURE__ */ defineComponent({
 	}
 });
 //#endregion
-export { wrapper_default as Markdown, collectMarkdownHeadings, getMarkdownHeadingTitle, parseMarkdownSearchSections };
+export { wrapper_default as Markdown, collectMarkdownHeadings, createHistoryTabQueryAdapter, getMarkdownHeadingTitle, markdownTabQueryKey, parseMarkdownSearchSections, toMarkdownTabId };