@ubean/vue 0.2.0

package/dist/types-VHF1RJu2.d.ts

@@ -0,0 +1,132 @@
+import { RouteMeta } from "vue-router";
+//#region src/types.d.ts
+/**
+ * `@ubean/vue` 页面路由共享类型(运行时 + 构建期 `/vite` 共用)。
+ *
+ * 本包是页面路由的唯一所有者:`@ubean/scan` 聚合层通过
+ * `import type { ... } from '@ubean/vue'` re-export 这些类型保持向后兼容。
+ */
+/**
+ * Page-level head configuration (SEO title, meta, link, etc.).
+ *
+ * 提取自 Markdown frontmatter 与 `definePage({ head })` 宏(构建期);
+ * SSR 链路经 `pageObj.head` 应用,SPA 链路经 `setupPageHeadGuard` 读取
+ * `route.meta.head` 后 push 进 head 实例。动态/响应式 head 用 `useHead()`。
+ */
+interface PageHead {
+  title?: string;
+  meta?: Array<Record<string, string>>;
+  link?: Array<Record<string, string>>;
+  script?: Array<Record<string, string>>;
+  htmlAttrs?: Record<string, string>;
+  bodyAttrs?: Record<string, string>;
+}
+/**
+ * Page-level route metadata extracted from `definePage()` macro calls.
+ *
+ * 注意:无 `middleware` 字段 —— 此前该字段从未被任何运行时消费
+ * (服务端中间件走 `middleware/` 目录挂载,客户端守卫读 `meta`)。
+ * 需要按路由声明守卫时,用 `meta: { middleware: [...] }` 透传到
+ * `route.meta` 由用户导航守卫消费。
+ */
+interface PageMeta {
+  name?: string;
+  path?: string;
+  /**
+   * Layout name, array of layout names (outer → inner, applied left-to-right),
+   * or `false` to disable layout.
+   */
+  layout?: string | string[] | false;
+  /** Reuse route target page name(元数据文件 `.reuse.ts` / `.reuse.js`)。 */
+  reuse?: string;
+  /** 任意扩展 meta,浅合并进 `route.meta`。 */
+  meta?: RouteMeta;
+  /** 鉴权标记,写入 `route.meta.requiresAuth`,由用户导航守卫消费。 */
+  requiresAuth?: boolean;
+  /** keep-alive 页面缓存声明。reuse 路由未显式声明时继承目标页。 */
+  cache?: boolean;
+  /** 页面级过渡名,`<PageView>` 消费;空串禁用本页过渡。 */
+  transition?: string;
+  /**
+   * 页面级静态 head(SEO)。构建期提取;仅当 `/vite` 插件
+   * `head: true` 时写入 `route.meta.head` 并参与扫描输出。
+   */
+  head?: PageHead;
+}
+/** 扫描得到的单个页面(字段与旧 `ScannedPageRoute` 完全兼容)。 */
+interface ScannedPage {
+  fullPath: string;
+  relativePath: string;
+  dirname: string;
+  basename: string;
+  name: string;
+  route: string;
+  path: string;
+  layout?: string | string[] | false;
+  cache?: boolean;
+  isReuse: boolean;
+  isMarkdown: boolean;
+  reuseTarget?: string;
+  pageMeta?: PageMeta;
+  frontmatter?: Record<string, unknown>;
+  /** Parallel route slot name(`@slotName/` 目录约定)。 */
+  slot?: string;
+  /** Intercepting route:从 `interceptFrom` 导航到 `interceptTarget` 时拦截。 */
+  interceptFrom?: string;
+  interceptTarget?: string;
+  /** 路由参数 → matcher 名称映射(`[param=matcher]` 语法)。 */
+  matchers?: Record<string, string>;
+}
+/** 扫描得到的布局(`layouts/` 下 `xx.vue` 或 `xx/index.vue`)。 */
+interface ScannedLayout {
+  fullPath: string;
+  relativePath: string;
+  dirname: string;
+  basename: string;
+  name: string;
+  path: string;
+  isDefault: boolean;
+}
+/**
+ * `scanPages` 入参。`pagesDir` / `layoutsDir` 支持多目录
+ * (先到先得去重,可分层叠加目录)。
+ */
+interface ScanPagesOptions {
+  /** 项目根目录(绝对)。 */
+  cwd: string;
+  /** 源码目录(绝对或相对 `cwd`)。 */
+  srcDir: string;
+  /** 页面目录,相对 `srcDir` 或绝对。默认 `['pages']`。 */
+  pagesDir?: string | string[];
+  /** 布局目录,相对 `srcDir` 或绝对。默认 `['layouts']`。 */
+  layoutsDir?: string | string[];
+  /**
+   * 页面文件扩展名。默认 `['vue', 'tsx', 'jsx']`;markdown 开启后自动追加
+   * 对应的 `.md` / `.mdx`。`.reuse.ts` 元数据文件为独立约定,始终参与扫描。
+   */
+  extensions?: string[];
+  /** 额外 glob ignore。 */
+  ignore?: string[];
+  /**
+   * Markdown 页面支持,默认 `false`(零成本)。
+   * - `true`:扫描 `.md` + `.mdx`
+   * - `'md'`:仅 `.md`
+   * - `'mdx'`:仅 `.mdx`
+   * 需安装 `@ubean/markdown`(构建期按需加载,未安装时降级为无 frontmatter)。
+   */
+  markdown?: boolean | 'mdx' | 'md';
+  /**
+   * 页面级 head 支持,默认 `false`。开启后 `definePage({ head })` 与
+   * markdown frontmatter `head` 写入 `pageMeta.head` / `route.meta.head`。
+   */
+  head?: boolean;
+}
+interface ScanPagesResult {
+  pages: ScannedPage[];
+  layouts: ScannedLayout[];
+  notFoundPage?: ScannedPage;
+  loadingPage?: ScannedPage;
+  errorPage?: ScannedPage;
+}
+//#endregion
+export { ScannedLayout as a, ScanPagesResult as i, PageMeta as n, ScannedPage as o, ScanPagesOptions as r, PageHead as t };

package/dist/vite.d.ts

@@ -0,0 +1,164 @@
+import { i as ScanPagesResult, n as PageMeta, r as ScanPagesOptions, t as PageHead } from "./types-VHF1RJu2.js";
+import { Plugin } from "vite";
+//#region src/scan-pages.d.ts
+/**
+ * Extract parallel route slot name and intercept info from a relative file path.
+ *
+ * Parallel routes: `@slotName/page.vue` → slot = 'slotName'
+ * Intercepting routes:
+ *   `(..)target/page.vue`  → intercept from parent, target = 'target'
+ *   `(.)target/page.vue`   → intercept from same level, target = 'target'
+ *   `(...)target/page.vue` → intercept from root, target = 'target'
+ */
+declare function extractSlotAndIntercept(fileBase: string): {
+  cleanedBase: string;
+  slot?: string;
+  interceptFrom?: string;
+  interceptTarget?: string;
+};
+declare function scanPages(options: ScanPagesOptions): Promise<ScanPagesResult>;
+//#endregion
+//#region src/virtual-pages.d.ts
+type PagesModuleInput = Pick<ScanPagesResult, 'pages' | 'layouts' | 'notFoundPage' | 'loadingPage' | 'errorPage'>;
+/** Generate the virtual module source(plain JS — no TS syntax, SSR-safe)。 */
+declare function generatePagesModuleSource(input: PagesModuleInput): string;
+/**
+ * Generate the ambient module declaration d.ts for the virtual module.
+ *
+ * 产物必须是 **script 文件**(无顶层 import/export)—— `declare module` 在
+ * script 上下文中才注册「环境模块声明」;在 module 文件中会被当作模块增强,
+ * 对不存在的模块无法生效。由 `/vite` 插件写入 `<root>/ubean-vue-routes.d.ts`。
+ */
+declare function generateVirtualModuleDts(input: PagesModuleInput, moduleId?: string): string;
+/**
+ * Generate `typed-router.d.ts` content for the virtual module.
+ *
+ * 包含 `vue-router/auto-routes` 的 `RouteNamedMap` 增强,让 vue-router 的
+ * `useRoute<Name>(name)` / `RouterLink` 能推断 `route.params` 类型。
+ *
+ * 产物是 **module 文件**(顶层 `export {}`)—— `declare module` 块按「模块
+ * 增强」语义合并进真实的 'vue-router' / 'vue-router/auto-routes' 模块;
+ * 若以 script 形式输出,同名环境模块声明会整体遮蔽真实包的类型。
+ * 虚拟模块自身的环境声明见 `generateVirtualModuleDts`。
+ */
+declare function generateTypedRouter(input: PagesModuleInput, _moduleId?: string): string;
+//#endregion
+//#region src/route-path.d.ts
+declare function stripRouteGroups(path: string): string;
+interface ParsedRoutePath {
+  route: string;
+  method?: string;
+  env?: string;
+  /**
+   * matcher 后缀剥离后、语法转换前的文件路由路径(保留 `[id]` / `[...slug]`
+   * 方括号语法)。`generateRouteName` 消费文件语法而非转换后的 `:id` 语法。
+   */
+  cleaned?: string;
+  /**
+   * 路由参数 → matcher 名称的映射。
+   *
+   * 由 `[paramName=matcherName]` 语法解析得到,例如 `[id=numeric].vue` →
+   * `{ id: 'numeric' }`。无 matcher 语法的路由此项为 `undefined`。
+   */
+  matchers?: Record<string, string>;
+}
+/**
+ * 解析 `[param=matcher]` 语法,从原始路径中提取 matcher 名称映射,并把
+ * `=matcher` 后缀剥离,以便后续正则能正确识别为普通动态参数。
+ *
+ * @example
+ * parseMatchers('users/[id=numeric]') → { cleaned: 'users/[id]', matchers: { id: 'numeric' } }
+ * parseMatchers('blog/[...slug=any]') → { cleaned: 'blog/[...slug]', matchers: { slug: 'any' } }
+ * parseMatchers('users/[id]')         → { cleaned: 'users/[id]', matchers: undefined }
+ */
+declare function parseMatchers(filePath: string): {
+  cleaned: string;
+  matchers?: Record<string, string>;
+};
+declare function filePathToRoute(filePath: string, prefix?: string): ParsedRoutePath;
+//#endregion
+//#region src/route-name.d.ts
+/**
+ * 路由名生成器(页面路由所有权归属 `@ubean/vue`)。
+ * `@ubean/scan` 聚合层 re-export 保持向后兼容;服务端专用的
+ * `generateApiRouteId` 保留在 `@ubean/scan`。
+ */
+declare function generateRouteName(routePath: string): string;
+declare function generateLayoutName(layoutPath: string): string;
+//#endregion
+//#region src/extract-page.d.ts
+/**
+ * 通用宏调用提取:在代码中查找 `funcName({...})` 形式的调用并解析其
+ * 对象字面量参数。供本包的 `definePage` 提取与 `@ubean/scan` 的
+ * `defineHandlerMeta` 提取共用(单一解析器实现)。
+ */
+declare function extractCallObject(code: string, funcName: string): Record<string, unknown> | null;
+/**
+ * Normalize a parsed `head` value into a `PageHead` object。
+ *
+ * Mirrors the markdown frontmatter head validation so Vue pages (via
+ * `definePage`) and Markdown pages (via frontmatter) share the same rules.
+ */
+declare function normalizePageHead(raw: unknown): PageHead | undefined;
+declare function extractDefinePageFromCode(code: string): PageMeta | null;
+declare function extractDefinePage(filePath: string): Promise<PageMeta | null>;
+//#endregion
+//#region src/vite.d.ts
+/**
+ * `@ubean/vue/vite` —— 精简客户端路由 Vite 插件(页面路由唯一所有者)。
+ *
+ * 能力:
+ * - 多 `pagesDir` / `layoutsDir` 扫描(先到先得去重)
+ * - reuse 路由、特殊页(404/loading/error)、并行路由 `@slot/`、拦截路由
+ * - `[param=matcher]` 语法(matchers 注入 `route.meta`)
+ * - markdown 页面(opt-in,默认 false,`@ubean/markdown` 按需加载)
+ * - 页面级 head(opt-in,默认 false,写入 `route.meta.head`)
+ * - `typed-router.d.ts` 生成(RouteNamedMap 完整类型推断,产物在 `dtsDir`,默认 `.ubean`)
+ *
+ * 框架层(`@ubean/vite`)通过 `generatePagesModuleSource` /
+ * `scanPages` / `generateTypedRouter` 复用同一套生成器。
+ */
+declare const VUE_ROUTES_MODULE_ID = "virtual:ubean-vue-routes";
+interface UbeanVueViteOptions {
+  /** 页面目录(相对项目根或绝对),支持多目录。默认 `'src/pages'`。 */
+  pagesDir?: string | string[];
+  /** 布局目录(相对项目根或绝对),支持多目录。默认 `'src/layouts'`。 */
+  layoutsDir?: string | string[];
+  /**
+   * 页面文件扩展名。默认 `['vue', 'tsx', 'jsx']`;markdown 开启后自动追加
+   * 对应的 `.md` / `.mdx`。`.reuse.ts` 元数据文件为独立约定,始终参与扫描。
+   */
+  extensions?: string[];
+  /** 额外 glob ignore。 */
+  ignore?: string[];
+  /** 是否生成 `typed-router.d.ts`。默认 `true`。 */
+  generateTypes?: boolean;
+  /**
+   * 类型声明产物目录(相对项目根或绝对路径)。默认 `'.ubean'` ——
+   * `ubean-vue-routes.d.ts` 与 `typed-router.d.ts` 都生成在该目录下,
+   * 与框架层(`@ubean/vite` 的 auto-imports dts)保持同一约定。
+   */
+  dtsDir?: string;
+  /**
+   * Markdown 页面支持,默认 `false`(零成本)。
+   * - `true`:扫描并渲染 `.md` + `.mdx`
+   * - `'md'`:仅 `.md`
+   * - `'mdx'`:仅 `.mdx`
+   * 需安装 `@ubean/markdown`(构建期按需加载)。
+   */
+  markdown?: boolean | 'mdx' | 'md';
+  /**
+   * 页面级 head 支持,默认 `false`。开启后 `definePage({ head })` 与
+   * frontmatter `head` 写入 `route.meta.head`(配合 `setupPageHeadGuard`)。
+   */
+  head?: boolean;
+}
+/** 剥离 `definePage({...})` 宏调用(构建期,扫描后源码中不再需要)。 */
+declare function stripDefinePageCalls(code: string): string;
+/**
+ * 扫描客户端页面/布局(对外工具函数,`root` 为项目根)。
+ */
+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 };