@ubean/vue 0.2.1 → 0.3.0

package/README.md

@@ -365,7 +365,7 @@ On SSR (via `SSR_KEY`), KeepAlive/Transition/Suspense/ErrorBoundary are skipped.
 
 Internal links render via `RouterLink`; external links (`http*`, `//`, `#`) render as native `<a target="_blank" rel="noopener noreferrer">`.
 
-Props: `to` (string or location object), `href`, `replace`, `activeClass`, `exactActiveClass`, `noActiveClass`. Path localization is opt-in via `LOCALIZE_PATH_KEY` (the framework runtime provides it; lean SPAs render paths verbatim).
+Props: `to` (string or location object), `href`, `replace`, `activeClass`, `exactActiveClass`, `noActiveClass`, optional `locale`. Path localization is opt-in via `LOCALIZE_PATH_KEY` (the framework runtime provides it; lean SPAs render paths verbatim).
 
 ### `<SlotView>`
 

package/README.zh-CN.md

@@ -372,7 +372,7 @@ SSR 场景（经 `SSR_KEY`）跳过 KeepAlive/Transition/Suspense/ErrorBoundary
 
 内部链接经 `RouterLink` 渲染；外部链接（`http*`、`//`、`#`）渲染为原生 `<a target="_blank" rel="noopener noreferrer">`。
 
-Props：`to`（字符串或位置对象）、`href`、`replace`、`activeClass`、`exactActiveClass`、`noActiveClass`。路径本地化经 `LOCALIZE_PATH_KEY` opt-in（框架运行时提供；精简 SPA 原样渲染路径）。
+Props：`to`（字符串或位置对象）、`href`、`replace`、`activeClass`、`exactActiveClass`、`noActiveClass`、可选 `locale`。路径本地化经 `LOCALIZE_PATH_KEY` opt-in（框架运行时提供；精简 SPA 原样渲染路径）。
 
 ### `<SlotView>`
 

package/dist/{generator/index.d.ts → generator.d.ts}

@@ -1,5 +1,5 @@
-import { a as ScannedLayout, o as ScannedPage } from "../types-VHF1RJu2.js";
-//#region src/generator/index.d.ts
+import { a as ScannedLayout, o as ScannedPage } from "./types-CeX4SJit.js";
+//#region src/generator.d.ts
 /**
  * 实体路由文件生成器(页面路由实体文件模式的唯一所有者,原
  * `@ubean/scan/generator`,已下沉到页面路由所有者 `@ubean/vue`)。
@@ -73,6 +73,11 @@ interface GeneratorOptions {
    * Return `null` to skip. Existing keys are NOT overwritten.
    */
   getRouteMeta?: (page: ScannedPage) => Record<string, unknown> | null;
+  /**
+   * Compact locale vue-router param (plain data from `getVueLocaleParam`).
+   * Example: `':locale(zh)?'`. Empty/undefined = no locale prefix.
+   */
+  localeVueParam?: string;
   /**
    * Compute the import specifier for a page file. Receives the absolute
    * `fullPath` of the page; should return a module specifier usable from
@@ -102,6 +107,7 @@ declare class RouteFileGenerator {
   constructor(options: GeneratorOptions);
   generate(scan: GeneratorScanInput): Promise<GeneratorResult>;
   renderRoutesFile(scan: GeneratorScanInput): string;
+  private toLocalePath;
   private renderRouteRecord;
   private computeMeta;
   renderImportsFile(scan: GeneratorScanInput): string;

package/dist/{generator/index.js → generator.js}

@@ -1,4 +1,4 @@
-//#region src/generator/index.ts
+//#region src/generator.ts
 const DEFAULT_HEADER_COMMENT = "// @generated by @ubean/vue/generator — do not edit manually.\n// This file is regenerated on every dev start / build.";
 async function generateRouteFiles(scan, options) {
 	return new RouteFileGenerator(options).generate(scan);
@@ -51,10 +51,16 @@ ${scan.pages.map((p) => this.renderRouteRecord(p)).join(",\n")}
 ];
 `;
 	}
+	toLocalePath(pagePath) {
+		const param = this.opts.localeVueParam;
+		if (!param) return pagePath;
+		if (pagePath === "/") return `/${param}`;
+		return `/${param}${pagePath}`;
+	}
 	renderRouteRecord(page) {
 		const parts = [];
 		parts.push(`    name: ${JSON.stringify(page.name)}`);
-		parts.push(`    path: ${JSON.stringify(page.route)}`);
+		parts.push(`    path: ${JSON.stringify(this.toLocalePath(page.route))}`);
 		const componentKey = page.isReuse && page.reuseTarget ? page.reuseTarget : page.name;
 		parts.push(`    component: ${JSON.stringify(componentKey)}`);
 		if (page.layout !== void 0) {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { a as ScannedLayout, i as ScanPagesResult, n as PageMeta, o as ScannedPage, r as ScanPagesOptions, t as PageHead } from "./types-VHF1RJu2.js";
+import { a as ScannedLayout, i as ScanPagesResult, n as PageMeta, o as ScannedPage, r as ScanPagesOptions, t as PageHead } from "./types-CeX4SJit.js";
 import { Component, ComputedRef, InjectionKey, Plugin, PropType, Ref, VNode } from "vue";
 import { NavigationGuard, RouteMeta, Router } from "vue-router";
 //#region src/view-transitions.d.ts
@@ -27,7 +27,7 @@ declare const ERROR_KEY: InjectionKey<Component | null>;
  * (`@ubean/client`) provides the reactive `localizePath`; when absent,
  * `Link` renders paths verbatim — this package never imports i18n itself.
  */
-declare const LOCALIZE_PATH_KEY: InjectionKey<(path: string) => string>;
+declare const LOCALIZE_PATH_KEY: InjectionKey<(path: string, locale?: string) => string>;
 /**
  * Layout chain context — provided by `LayoutChainRenderer` so that `<PageView />`
  * inside a layout knows whether to render the next nested layout or the actual
@@ -204,6 +204,11 @@ declare const Link: import("vue").DefineComponent<import("vue").ExtractPropTypes
     type: BooleanConstructor;
     default: boolean;
   };
+  /** Target locale for path localization; omit to use the current locale. */
+  locale: {
+    type: StringConstructor;
+    default: undefined;
+  };
 }>, () => VNode<import("vue").RendererNode, import("vue").RendererElement, {
   [key: string]: any;
 }>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
@@ -235,6 +240,11 @@ declare const Link: import("vue").DefineComponent<import("vue").ExtractPropTypes
     type: BooleanConstructor;
     default: boolean;
   };
+  /** Target locale for path localization; omit to use the current locale. */
+  locale: {
+    type: StringConstructor;
+    default: undefined;
+  };
 }>> & Readonly<{}>, {
   to: string | Record<string, unknown>;
   href: string;
@@ -243,6 +253,7 @@ declare const Link: import("vue").DefineComponent<import("vue").ExtractPropTypes
   activeClass: string;
   exactActiveClass: string;
   noActiveClass: boolean;
+  locale: string;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
 /**
  * `PAGE_KEY` 注入的页面数据形状(框架工厂 / SSR 链路提供;精简 SPA
@@ -560,6 +571,11 @@ interface DefineClientPageOptions {
    * `setupPageHeadGuard()` 应用,SSR 链路经服务端扫描结果消费。
    */
   head?: PageHead;
+  /**
+   * Per-page select SSR (`false` | `'data-only'` | `true` | `'streaming'`).
+   * Consumed by the server router; also written to `route.meta.ssr`.
+   */
+  ssr?: boolean | 'streaming' | 'data-only';
   /** 任意扩展 meta,浅合并进 `route.meta`(类型上扩展 vue-router RouteMeta)。 */
   meta?: RouteMeta;
 }
@@ -725,7 +741,7 @@ interface PageHeadClient {
 }
 /**
  * 将静态 `PageHead` push 进 head 实例(falsy 字段自动跳过)。
- * 与 SSR 侧 `pushPageHead`(@ubean/ssr)语义一致,保证双端同构。
+ * 与 SSR 侧 `pushPageHead`(@ubean/client/ssr)语义一致,保证双端同构。
  */
 declare function pushPageHead(head: PageHeadClient, pageHead: PageHead): void;
 /**
@@ -776,6 +792,8 @@ declare module 'vue-router' {
     head?: PageHead;
     /** `[param=matcher]` mapping consumed by `createMatcherGuard()`. */
     matchers?: Record<string, string>;
+    /** Select SSR mode from `definePage({ ssr })`. */
+    ssr?: boolean | 'streaming' | 'data-only';
   }
 }
 //#endregion

package/dist/index.js

@@ -753,6 +753,22 @@ const SlotView = defineComponent({
 		};
 	}
 });
+function isExternalHref(path) {
+	return path.startsWith("http") || path.startsWith("//") || path.startsWith("#");
+}
+function resolveLinkTo(to, localize, locale) {
+	if (typeof to !== "string") {
+		if (!localize) return to;
+		const path = to.path;
+		if (typeof path !== "string" || isExternalHref(path)) return to;
+		return {
+			...to,
+			path: localize(path, locale)
+		};
+	}
+	if (isExternalHref(to) || !localize) return to;
+	return localize(to, locale);
+}
 /**
 * Link — internal links render via RouterLink; external links (`http*`,
 * `//`, `#`) render as native `<a target="_blank" rel="noopener noreferrer">`.
@@ -790,19 +806,17 @@ const Link = defineComponent({
 		noActiveClass: {
 			type: Boolean,
 			default: false
+		},
+		/** Target locale for path localization; omit to use the current locale. */
+		locale: {
+			type: String,
+			default: void 0
 		}
 	},
 	setup(props, { slots, attrs }) {
 		const localize = inject(LOCALIZE_PATH_KEY, null);
-		const resolvedTo = computed(() => {
-			const path = props.to ?? props.href ?? "";
-			if (typeof path === "string" && (path.startsWith("http") || path.startsWith("//") || path.startsWith("#"))) return path;
-			return localize ? localize(path) : path;
-		});
-		const isExternal = computed(() => {
-			const path = String(resolvedTo.value);
-			return path.startsWith("http") || path.startsWith("//") || path.startsWith("#");
-		});
+		const resolvedTo = computed(() => resolveLinkTo(props.to ?? props.href ?? "", localize, props.locale));
+		const isExternal = computed(() => typeof resolvedTo.value === "string" && isExternalHref(resolvedTo.value));
 		return () => {
 			if (isExternal.value) return h("a", {
 				...attrs,
@@ -1024,7 +1038,7 @@ function createMatcherGuard(options = {}) {
 //#region src/head.ts
 /**
 * 将静态 `PageHead` push 进 head 实例(falsy 字段自动跳过)。
-* 与 SSR 侧 `pushPageHead`(@ubean/ssr)语义一致,保证双端同构。
+* 与 SSR 侧 `pushPageHead`(@ubean/client/ssr)语义一致,保证双端同构。
 */
 function pushPageHead(head, pageHead) {
 	const input = {};

package/dist/{types-VHF1RJu2.d.ts → types-CeX4SJit.d.ts}

@@ -52,6 +52,11 @@ interface PageMeta {
    * `head: true` 时写入 `route.meta.head` 并参与扫描输出。
    */
   head?: PageHead;
+  /**
+   * Per-page select SSR. Wins over `routeRules.ssr` and the global exclude list.
+   * `false` = CSR without loader; `'data-only'` = loader + CSR shell; `true` = SSR.
+   */
+  ssr?: boolean | 'streaming' | 'data-only';
 }
 /** 扫描得到的单个页面(字段与旧 `ScannedPageRoute` 完全兼容)。 */
 interface ScannedPage {

package/dist/vite.d.ts

@@ -1,4 +1,4 @@
-import { i as ScanPagesResult, n as PageMeta, r as ScanPagesOptions, t as PageHead } from "./types-VHF1RJu2.js";
+import { i as ScanPagesResult, n as PageMeta, r as ScanPagesOptions, t as PageHead } from "./types-CeX4SJit.js";
 import { Plugin } from "vite";
 //#region src/scan-pages.d.ts
 /**
@@ -20,8 +20,15 @@ declare function scanPages(options: ScanPagesOptions): Promise<ScanPagesResult>;
 //#endregion
 //#region src/virtual-pages.d.ts
 type PagesModuleInput = Pick<ScanPagesResult, 'pages' | 'layouts' | 'notFoundPage' | 'loadingPage' | 'errorPage'>;
+/**
+ * Optional compact locale prefix (plain data — `@ubean/vue` does not import i18n).
+ * Example: `':locale(zh)?'` for prefix_except_default with extra locales `zh`.
+ */
+interface LocaleRouteCompileOptions {
+  vueParam?: string;
+}
 /** Generate the virtual module source(plain JS — no TS syntax, SSR-safe)。 */
-declare function generatePagesModuleSource(input: PagesModuleInput): string;
+declare function generatePagesModuleSource(input: PagesModuleInput, locale?: LocaleRouteCompileOptions): string;
 /**
  * Generate the ambient module declaration d.ts for the virtual module.
  *
@@ -161,4 +168,4 @@ declare function stripDefinePageCalls(code: string): string;
 declare function scanClientPages(root: string, options?: UbeanVueViteOptions): Promise<ScanPagesResult>;
 declare function ubeanVueVite(options?: UbeanVueViteOptions): Plugin;
 //#endregion
-export { type ParsedRoutePath, UbeanVueViteOptions, VUE_ROUTES_MODULE_ID, ubeanVueVite as default, ubeanVueVite, extractCallObject, extractDefinePage, extractDefinePageFromCode, extractSlotAndIntercept, filePathToRoute, generateLayoutName, generatePagesModuleSource, generateRouteName, generateTypedRouter, generateVirtualModuleDts, normalizePageHead, parseMatchers, scanClientPages, scanPages, stripDefinePageCalls, stripRouteGroups };
+export { type LocaleRouteCompileOptions, type PagesModuleInput, type ParsedRoutePath, UbeanVueViteOptions, VUE_ROUTES_MODULE_ID, ubeanVueVite as default, ubeanVueVite, extractCallObject, extractDefinePage, extractDefinePageFromCode, extractSlotAndIntercept, filePathToRoute, generateLayoutName, generatePagesModuleSource, generateRouteName, generateTypedRouter, generateVirtualModuleDts, normalizePageHead, parseMatchers, scanClientPages, scanPages, stripDefinePageCalls, stripRouteGroups };

package/dist/vite.js

@@ -301,6 +301,7 @@ function extractDefinePageFromCode(code) {
 	if (typeof parsed.requiresAuth === "boolean") result.requiresAuth = parsed.requiresAuth;
 	if (typeof parsed.cache === "boolean") result.cache = parsed.cache;
 	if (typeof parsed.transition === "string") result.transition = parsed.transition;
+	if (parsed.ssr === false || parsed.ssr === true || parsed.ssr === "streaming" || parsed.ssr === "data-only") result.ssr = parsed.ssr;
 	const head = normalizePageHead(parsed.head);
 	if (head) result.head = head;
 	return result;
@@ -790,6 +791,7 @@ function buildRouteMeta(page, extra = {}) {
 		reuseTarget: page.isReuse ? page.reuseTarget : void 0,
 		transition: page.pageMeta?.transition,
 		requiresAuth: page.pageMeta?.requiresAuth === true ? true : void 0,
+		ssr: page.pageMeta?.ssr,
 		matchers: page.matchers && Object.keys(page.matchers).length > 0 ? page.matchers : void 0,
 		head: page.pageMeta?.head,
 		...page.pageMeta?.meta,
@@ -797,8 +799,13 @@ function buildRouteMeta(page, extra = {}) {
 	};
 	return JSON.stringify(meta);
 }
+function withLocaleParam(routerPath, vueParam) {
+	if (!vueParam) return routerPath;
+	if (routerPath === "/") return `/${vueParam}`;
+	return `/${vueParam}${routerPath}`;
+}
 /** Generate the virtual module source(plain JS — no TS syntax, SSR-safe)。 */
-function generatePagesModuleSource(input) {
+function generatePagesModuleSource(input, locale) {
 	const { pages, layouts } = input;
 	const pageLoaders = [];
 	const layoutLoaders = [];
@@ -838,11 +845,15 @@ function generatePagesModuleSource(input) {
 			const componentParts = [];
 			if (defaultPage) componentParts.push(`default: ${varNameFor(defaultPage.name)}`);
 			for (const sp of slotPages) componentParts.push(`${JSON.stringify(sp.slot)}: ${varNameFor(sp.name)}`);
-			routeEntries.push(`  { path: ${JSON.stringify(routerPath)}, name: ${JSON.stringify(primaryPage.name)}, components: { ${componentParts.join(", ")} }, meta: ${buildRouteMeta(primaryPage, { parallelSlots: slotPages.map((s) => s.slot) })} }`);
-		} else routeEntries.push(`  { path: ${JSON.stringify(routerPath)}, name: ${JSON.stringify(defaultPage.name)}, component: ${varNameFor(defaultPage.name)}, meta: ${buildRouteMeta(defaultPage)} }`);
+			const vuePath = withLocaleParam(routerPath, locale?.vueParam);
+			routeEntries.push(`  { path: ${JSON.stringify(vuePath)}, name: ${JSON.stringify(primaryPage.name)}, components: { ${componentParts.join(", ")} }, meta: ${buildRouteMeta(primaryPage, { parallelSlots: slotPages.map((s) => s.slot) })} }`);
+		} else {
+			const vuePath = withLocaleParam(routerPath, locale?.vueParam);
+			routeEntries.push(`  { path: ${JSON.stringify(vuePath)}, name: ${JSON.stringify(defaultPage.name)}, component: ${varNameFor(defaultPage.name)}, meta: ${buildRouteMeta(defaultPage)} }`);
+		}
 	}
 	for (const p of interceptPages) {
-		const routerPath = toVueRouterPath(p.route);
+		const routerPath = withLocaleParam(toVueRouterPath(p.route), locale?.vueParam);
 		const interceptName = `__intercept_${p.name}`;
 		routeEntries.push(`  { path: ${JSON.stringify(routerPath)}, name: ${JSON.stringify(interceptName)}, component: ${varNameFor(p.name)}, meta: ${buildRouteMeta(p, {
 			interceptFrom: p.interceptFrom,
@@ -853,7 +864,8 @@ function generatePagesModuleSource(input) {
 	let hasNotFound = false;
 	if (input.notFoundPage) {
 		hasNotFound = true;
-		routeEntries.push(`  { path: ${JSON.stringify("/:pathMatch(.*)*")}, name: "NotFound", component: Page_NotFound, meta: { pageName: "NotFound" } }`);
+		const notFoundPath = withLocaleParam("/:pathMatch(.*)*", locale?.vueParam);
+		routeEntries.push(`  { path: ${JSON.stringify(notFoundPath)}, name: "NotFound", component: Page_NotFound, meta: { pageName: "NotFound" } }`);
 	}
 	let loadingLoaderName = "null";
 	if (input.loadingPage) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ubean/vue",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Lean Vue client kernel & page-routing owner for ubean — plugin-first page routing outlet, page cache (keep-alive), transitions, reload signal, definePage macro + file-routing Vite plugin (/vite: multi-dir scan, reuse routes, markdown & page-head opt-in). Runtime deps: vue + vue-router only.",
   "files": [
     "dist"
@@ -19,8 +19,8 @@
       "import": "./dist/vite.js"
     },
     "./generator": {
-      "types": "./dist/generator/index.d.ts",
-      "import": "./dist/generator/index.js"
+      "types": "./dist/generator.d.ts",
+      "import": "./dist/generator.js"
     }
   },
   "dependencies": {
@@ -33,14 +33,14 @@
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
-    "@unhead/vue": "^3.3.2",
+    "@unhead/vue": "^3.4.0",
     "@vue/server-renderer": "^3.5.41",
     "happy-dom": "^20.11.6",
     "typescript": "7.0.2",
     "vite": "npm:@voidzero-dev/vite-plus-core@0.2.9",
     "vite-plus": "0.2.9",
     "vitest": "4.1.11",
-    "@ubean/markdown": "0.2.1"
+    "@ubean/markdown": "0.3.0"
   },
   "peerDependencies": {
     "@ubean/markdown": ">=0.1.0",