@deot/docs-client 1.0.4 → 1.0.6

package/README.md

@@ -19,6 +19,15 @@ pnpm add @deot/docs-client
 	window.$docs = {
 		base: new URL('./', document.baseURI).href,
 		namespace: 'my-docs',
+		layout: {
+			header: {
+				brand: {
+					logo: './logo.svg',
+					label: { 'zh-CN': '组件文档', 'en-US': 'Component Docs' },
+					value: '/guide'
+				}
+			}
+		},
 		locales: {
 			'zh-CN': {
 				label: '简体中文',
@@ -73,6 +82,7 @@ const { app, router, disconnect } = await bootstrap(window.$docs);
 | `styles` | 站点级预览 CSS 默认地址；同名 key 覆盖内置样式表，也可追加。管理页 `/:lang/__docs/playground-resource` 与 `modules` 同一张表管理。 |
 | `prefetch` | 空闲预加载开关或 `{ batchSize, idleTimeout }` 配置，默认开启。 |
 | `theme` | 主题开关或 `{ default: 'system' \| 'light' \| 'dark' }`，默认跟随系统。 |
+| `layout.header` | 内置 Header 配置；`brand.logo`、`brand.label` 和 `brand.value` 均支持固定值或按语言配置。文案未配置时回退到 `namespace` 和内置翻译，链接未配置时指向当前语言首页。站内链接自动补语言前缀，外链在新窗口打开。 |
 | `layout.footer` | Footer 内容；未配置或 `default` 使用内置分组，`false` 全局隐藏，也可配置 `{ groups, poweredBy }`。两项均支持按语言代码配置，`groups` 复用 Sidebar 的 `{ label, value?, children? }` 结构。 |
 | `home` | 可选的 `{ locales }` 首页配置；语言值是 Renderer 文档或 `.page.json` 地址。未配置时首页为空。 |
 | `renderers` | 业务自定义 Renderer 模块注册项；type 必须使用非 `docs:` 的命名空间。 |

package/dist/index.cjs

@@ -251,7 +251,7 @@ var _hoisted_4$9 = {
 };
 var _hoisted_5$7 = ["href"];
 var _hoisted_6$5 = { key: 2 };
-var _hoisted_7$3 = {
+var _hoisted_7$4 = {
 	key: 1,
 	class: "docs-footer__powered-by"
 };
@@ -379,7 +379,7 @@ var default_footer_default = /* @__PURE__ */ (0, vue.defineComponent)({
 						_: 2
 					}, 1032, ["to"])) : ((0, vue.openBlock)(), (0, vue.createElementBlock)("span", _hoisted_6$5, (0, vue.toDisplayString)(item.label), 1))]);
 				}), 128))])) : (0, vue.createCommentVNode)("v-if", true)]);
-			}), 128))])) : (0, vue.createCommentVNode)("v-if", true), poweredBy.value ? ((0, vue.openBlock)(), (0, vue.createElementBlock)("div", _hoisted_7$3, (0, vue.toDisplayString)(poweredBy.value), 1)) : (0, vue.createCommentVNode)("v-if", true)])) : (0, vue.createCommentVNode)("v-if", true);
+			}), 128))])) : (0, vue.createCommentVNode)("v-if", true), poweredBy.value ? ((0, vue.openBlock)(), (0, vue.createElementBlock)("div", _hoisted_7$4, (0, vue.toDisplayString)(poweredBy.value), 1)) : (0, vue.createCommentVNode)("v-if", true)])) : (0, vue.createCommentVNode)("v-if", true);
 		};
 	}
 });
@@ -1389,6 +1389,19 @@ var localizeRoutePath = (lang, pathname) => {
 	return `/${lang}${normalized === "/" ? "" : normalized}`;
 };
 /**
+* 给站内地址补语言前缀；外链和已带已配置语言的地址保持不变。
+* @param config 文档配置，用于识别语言路径段。
+* @param lang 当前语言。
+* @param target 原始跳转地址。
+* @returns 可直接交给 RouterLink 的地址。
+*/
+var localizePath = (config, lang, target) => {
+	const language = target.split(/[?#]/u, 1)[0].split("/").filter(Boolean)[0];
+	const configuredLanguages = Object.keys(config.locales);
+	const hasLanguage = Boolean(language && (Object.prototype.hasOwnProperty.call(config.locales, language) || !configuredLanguages.length && language === lang));
+	return isExternalLink(target) || hasLanguage ? target : localizeRoutePath(lang, target);
+};
+/**
 * 按显式 value、动态参数和路径末段的顺序确定当前文档值。
 * 该纯函数独立于 Router 注册模块，避免布局组件反向导入 Router 时形成循环依赖。
 * @param route 当前标准化路由，或资源计划合成的等价 route shape。
@@ -3619,12 +3632,12 @@ var _hoisted_3$12 = ["placeholder", "aria-label"];
 var _hoisted_4$7 = { class: "docs-search__actions" };
 var _hoisted_5$6 = ["aria-label"];
 var _hoisted_6$4 = { class: "docs-search__body" };
-var _hoisted_7$2 = { class: "docs-search__content" };
-var _hoisted_8$2 = {
+var _hoisted_7$3 = { class: "docs-search__content" };
+var _hoisted_8$3 = {
 	key: 0,
 	class: "docs-search__state"
 };
-var _hoisted_9$2 = {
+var _hoisted_9$3 = {
 	key: 1,
 	class: "docs-search__state docs-search__state--error"
 };
@@ -3913,7 +3926,7 @@ var search_default = /* @__PURE__ */ (0, vue.defineComponent)({
 					height: "100%",
 					"wrapper-style": "overflow-x: hidden;"
 				}, {
-					default: (0, vue.withCtx)(() => [(0, vue.createElementVNode)("div", _hoisted_7$2, [loading.value ? ((0, vue.openBlock)(), (0, vue.createElementBlock)("div", _hoisted_8$2, (0, vue.toDisplayString)((0, vue.unref)(t)("client.search.searching")), 1)) : error.value ? ((0, vue.openBlock)(), (0, vue.createElementBlock)("div", _hoisted_9$2, (0, vue.toDisplayString)(error.value), 1)) : keyword.value.trim() ? ((0, vue.openBlock)(), (0, vue.createElementBlock)(vue.Fragment, { key: 2 }, [
+					default: (0, vue.withCtx)(() => [(0, vue.createElementVNode)("div", _hoisted_7$3, [loading.value ? ((0, vue.openBlock)(), (0, vue.createElementBlock)("div", _hoisted_8$3, (0, vue.toDisplayString)((0, vue.unref)(t)("client.search.searching")), 1)) : error.value ? ((0, vue.openBlock)(), (0, vue.createElementBlock)("div", _hoisted_9$3, (0, vue.toDisplayString)(error.value), 1)) : keyword.value.trim() ? ((0, vue.openBlock)(), (0, vue.createElementBlock)(vue.Fragment, { key: 2 }, [
 						(0, vue.createElementVNode)("div", _hoisted_10$2, (0, vue.toDisplayString)((0, vue.unref)(t)("client.search.documentation")), 1),
 						((0, vue.openBlock)(true), (0, vue.createElementBlock)(vue.Fragment, null, (0, vue.renderList)(results.value, (item, index) => {
 							return (0, vue.openBlock)(), (0, vue.createElementBlock)("button", {
@@ -4527,18 +4540,21 @@ var takeInlineRendererDocument = (from) => {
 //#endregion
 //#region packages/client/src/components/layout/default-header.vue?vue&type=script&setup=true&lang.ts
 var _hoisted_1$15 = { class: "docs-header" };
-var _hoisted_2$13 = { class: "docs-header__search" };
-var _hoisted_3$11 = { class: "docs-header__actions" };
-var _hoisted_4$6 = {
+var _hoisted_2$13 = ["href"];
+var _hoisted_3$11 = ["src"];
+var _hoisted_4$6 = ["src"];
+var _hoisted_5$5 = { class: "docs-header__search" };
+var _hoisted_6$3 = { class: "docs-header__actions" };
+var _hoisted_7$2 = {
 	key: 0,
 	class: "docs-header__locales"
 };
-var _hoisted_5$5 = [
+var _hoisted_8$2 = [
 	"title",
 	"aria-label",
 	"aria-expanded"
 ];
-var _hoisted_6$3 = ["title", "aria-label"];
+var _hoisted_9$2 = ["title", "aria-label"];
 //#endregion
 //#region packages/client/src/components/layout/default-header.vue
 var default_header_default = /* @__PURE__ */ (0, vue.defineComponent)({
@@ -4550,6 +4566,21 @@ var default_header_default = /* @__PURE__ */ (0, vue.defineComponent)({
 		const { t } = (0, _deot_docs_locale.useLocale)();
 		const localeMenuVisible = (0, vue.ref)(false);
 		const lang = (0, vue.computed)(() => String(route.params.lang));
+		/**
+		* 按当前语言和站点默认语言选择 Header 配置。
+		* @param value 固定配置或语言映射。
+		* @returns 当前语言、站点默认语言或空值。
+		*/
+		function resolveLocalized(value) {
+			if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+			return findLanguageValue(value, lang.value) ?? findLanguageValue(value, getDefaultLanguage(config));
+		}
+		const brandOptions = config.layout?.header?.brand;
+		const brandLogo = (0, vue.computed)(() => resolveLocalized(brandOptions?.logo) || "");
+		const brandLabel = (0, vue.computed)(() => resolveLocalized(brandOptions?.label) || config.namespace || t("client.header.brand"));
+		const brandValue = (0, vue.computed)(() => resolveLocalized(brandOptions?.value) || `/${lang.value}`);
+		const brandExternal = (0, vue.computed)(() => isExternalLink(brandValue.value));
+		const brandPath = (0, vue.computed)(() => localizePath(config, lang.value, brandValue.value));
 		const databasePath = (0, vue.computed)(() => `/${lang.value}/__docs/database`);
 		const playgroundResourcePath = (0, vue.computed)(() => `/${lang.value}/__docs/playground-resource`);
 		const localeOptions = (0, vue.computed)(() => Object.entries(config.locales).map(([value, item]) => ({
@@ -4610,17 +4641,34 @@ var default_header_default = /* @__PURE__ */ (0, vue.defineComponent)({
 		};
 		return (_ctx, _cache) => {
 			return (0, vue.openBlock)(), (0, vue.createElementBlock)("header", _hoisted_1$15, [
-				(0, vue.createVNode)((0, vue.unref)(vue_router.RouterLink), {
+				brandExternal.value ? ((0, vue.openBlock)(), (0, vue.createElementBlock)("a", {
+					key: 0,
+					class: "docs-header__brand",
+					href: brandValue.value,
+					target: "_blank",
+					rel: "noopener noreferrer"
+				}, [brandLogo.value ? ((0, vue.openBlock)(), (0, vue.createElementBlock)("img", {
+					key: 0,
+					class: "docs-header__brand-logo",
+					src: brandLogo.value,
+					alt: ""
+				}, null, 8, _hoisted_3$11)) : (0, vue.createCommentVNode)("v-if", true), (0, vue.createTextVNode)(" " + (0, vue.toDisplayString)(brandLabel.value), 1)], 8, _hoisted_2$13)) : ((0, vue.openBlock)(), (0, vue.createBlock)((0, vue.unref)(vue_router.RouterLink), {
+					key: 1,
 					class: "docs-header__brand",
-					to: `/${lang.value}`
+					to: brandPath.value
 				}, {
-					default: (0, vue.withCtx)(() => [(0, vue.createTextVNode)((0, vue.toDisplayString)((0, vue.unref)(t)("client.header.brand")), 1)]),
+					default: (0, vue.withCtx)(() => [brandLogo.value ? ((0, vue.openBlock)(), (0, vue.createElementBlock)("img", {
+						key: 0,
+						class: "docs-header__brand-logo",
+						src: brandLogo.value,
+						alt: ""
+					}, null, 8, _hoisted_4$6)) : (0, vue.createCommentVNode)("v-if", true), (0, vue.createTextVNode)(" " + (0, vue.toDisplayString)(brandLabel.value), 1)]),
 					_: 1
-				}, 8, ["to"]),
-				(0, vue.createElementVNode)("div", _hoisted_2$13, [(0, vue.createVNode)((0, vue.unref)(trigger_default))]),
-				(0, vue.createElementVNode)("div", _hoisted_3$11, [
+				}, 8, ["to"])),
+				(0, vue.createElementVNode)("div", _hoisted_5$5, [(0, vue.createVNode)((0, vue.unref)(trigger_default))]),
+				(0, vue.createElementVNode)("div", _hoisted_6$3, [
 					(0, vue.createVNode)((0, vue.unref)(theme_toggler_default), { class: "docs-header__theme" }),
-					localeOptions.value.length > 1 ? ((0, vue.openBlock)(), (0, vue.createElementBlock)("nav", _hoisted_4$6, [(0, vue.createVNode)((0, vue.unref)(_deot_vc.Dropdown), {
+					localeOptions.value.length > 1 ? ((0, vue.openBlock)(), (0, vue.createElementBlock)("nav", _hoisted_7$2, [(0, vue.createVNode)((0, vue.unref)(_deot_vc.Dropdown), {
 						modelValue: localeMenuVisible.value,
 						"onUpdate:modelValue": _cache[0] || (_cache[0] = ($event) => localeMenuVisible.value = $event),
 						class: "docs-header__locale-dropdown",
@@ -4660,7 +4708,7 @@ var default_header_default = /* @__PURE__ */ (0, vue.defineComponent)({
 							"aria-label": (0, vue.unref)(t)("client.header.language"),
 							"aria-expanded": localeMenuVisible.value,
 							"aria-haspopup": "menu"
-						}, [(0, vue.createVNode)((0, vue.unref)(icon_default), { name: "language" })], 8, _hoisted_5$5)]),
+						}, [(0, vue.createVNode)((0, vue.unref)(icon_default), { name: "language" })], 8, _hoisted_8$2)]),
 						_: 1
 					}, 8, ["modelValue"])])) : (0, vue.createCommentVNode)("v-if", true),
 					(0, vue.createElementVNode)("button", {
@@ -4669,7 +4717,7 @@ var default_header_default = /* @__PURE__ */ (0, vue.defineComponent)({
 						title: (0, vue.unref)(t)("client.header.editor"),
 						"aria-label": (0, vue.unref)(t)("client.header.editor"),
 						onClick: handleEditor
-					}, [(0, vue.createVNode)((0, vue.unref)(icon_default), { name: "editor" })], 8, _hoisted_6$3),
+					}, [(0, vue.createVNode)((0, vue.unref)(icon_default), { name: "editor" })], 8, _hoisted_9$2),
 					(0, vue.createVNode)((0, vue.unref)(vue_router.RouterLink), {
 						class: "docs-header__action docs-header__playground-resource",
 						to: playgroundResourcePath.value,
@@ -8519,11 +8567,6 @@ var slotProps = {
 	extra: { name: "extra" }
 };
 var hasConfiguredLanguage = (config, language) => Object.prototype.hasOwnProperty.call(config.locales, language);
-var hasLanguage = (config, path) => {
-	const language = path.split(/[?#]/u, 1)[0].split("/").filter(Boolean)[0];
-	const configuredLanguages = Object.keys(config.locales);
-	return Boolean(language && (hasConfiguredLanguage(config, language) || !configuredLanguages.length && language === getDefaultLanguage(config)));
-};
 var matchesConfiguredPath = (config, pathname) => {
 	const target = pathname.split("/").filter(Boolean);
 	return Object.keys(config.routes).some((path) => {
@@ -8549,10 +8592,6 @@ var normalizeInvalidLanguage = (config, defaultLanguage, to, languageRoot = fals
 	};
 	return replaceLanguage(defaultLanguage, to);
 };
-var localizePath = (config, lang, target) => {
-	if (isExternalLink(target) || hasLanguage(config, target)) return target;
-	return localizeRoutePath(lang, target);
-};
 var resolveRedirect = (config, target, to) => localizePath(config, String(to.params.lang || getDefaultLanguage(config)), typeof target === "function" ? target(to) : target);
 var createRouteRecord = (config, path, routeConfig, options = {}) => {
 	if (typeof routeConfig === "string" || typeof routeConfig === "function") return {

package/dist/index.d.ts

@@ -56,11 +56,22 @@ export declare interface DocsFooterOptions {
 
 export declare type DocsFooterPoweredBy = 'default' | string | false;
 
+export declare interface DocsHeaderBrandOptions {
+    logo?: DocsLocalized<string>;
+    label?: DocsLocalized<string>;
+    value?: DocsLocalized<string>;
+}
+
+export declare interface DocsHeaderOptions {
+    brand?: DocsHeaderBrandOptions;
+}
+
 export declare interface DocsHomeOptions {
     locales: Record<string, RendererDocument | string>;
 }
 
 export declare interface DocsLayoutOptions {
+    header?: DocsHeaderOptions;
     footer?: 'default' | DocsFooterOptions | false;
 }