@tixxin/nuxt-theme-engine 0.0.1 → 0.0.3

package/README.md

@@ -44,6 +44,8 @@
 pnpm add @tixxin/nuxt-theme-engine
 ```
 
+默认博客契约已经内置在 `@tixxin/nuxt-theme-engine` 发布包内，消费者**不需要额外安装** `@tixxin/theme-contracts`。
+
 ```ts
 // nuxt.config.ts
 export default defineNuxtConfig({
@@ -74,11 +76,15 @@ export default defineNuxtConfig({
 </template>
 ```
 
+`ThemeComponent` 在主题切换时会优先保留当前已显示的组件树，等目标主题组件实际加载完成后再原子切换，以减少异步主题组件带来的空白闪屏。
+
 ## 自定义契约
 
 引擎本身不强绑定某一套业务契约。
 
-仓库里的 `@tixxin/theme-contracts` 只是**默认博客示例契约**。如果你的项目是电商、文档站、社区或其他业务，可以直接换成自己的契约入口。
+模块默认会使用内置的博客示例契约，等价导入路径为 `@tixxin/nuxt-theme-engine/default-contracts`。
+
+仓库里的 `@tixxin/theme-contracts` 现在只是**开发期/示例来源**。如果你的项目是电商、文档站、社区或其他业务，可以直接换成自己的契约入口。
 
 ### 使用本地契约文件
 
@@ -145,7 +151,7 @@ pnpm dev
 pnpm dev           # 启动 playground
 pnpm dev:prepare   # 生成 .nuxt 类型声明
 pnpm typecheck     # 类型检查模块与 playground
-pnpm build         # 构建契约包和模块
+pnpm build         # 构建主题引擎模块与内置默认契约
 ```
 
 仓库结构：

package/dist/default-contracts.d.mts

@@ -0,0 +1,68 @@
+interface ThemePostSummary {
+    id: string | number;
+    title: string;
+    excerpt?: string;
+    url?: string;
+    likesCount?: number;
+    commentsCount?: number;
+    readingTime?: string;
+}
+interface ThemePostDetail extends ThemePostSummary {
+    content: string;
+}
+interface HomeLayoutProps {
+    title?: string;
+    subtitle?: string;
+}
+interface PostListProps {
+    posts: ThemePostSummary[];
+    loading?: boolean;
+}
+interface PostDetailProps {
+    post: ThemePostDetail;
+}
+interface NavItem {
+    label: string;
+    icon?: string;
+    path: string;
+}
+interface SidebarNavProps {
+    items: NavItem[];
+    currentPath?: string;
+}
+interface SiteStatsData {
+    runningDays: number;
+    postCount: number;
+    viewCount: string;
+    commentCount: number;
+    tagCount: number;
+}
+interface SiteStatsProps {
+    stats: SiteStatsData;
+}
+interface SubscribeCardProps {
+    description?: string;
+    placeholder?: string;
+}
+interface BlogFooterProps {
+    copyright?: string;
+    poweredBy?: string;
+    links?: {
+        label: string;
+        url: string;
+    }[];
+}
+interface ThemeComponentContracts {
+    HomeLayout: HomeLayoutProps;
+    PostList: PostListProps;
+    PostDetail: PostDetailProps;
+    SidebarNav: SidebarNavProps;
+    SiteStats: SiteStatsProps;
+    SubscribeCard: SubscribeCardProps;
+    BlogFooter: BlogFooterProps;
+}
+declare const themeContractNames: readonly ["HomeLayout", "PostList", "PostDetail", "SidebarNav", "SiteStats", "SubscribeCard", "BlogFooter"];
+type ThemeContractName = typeof themeContractNames[number];
+
+export { themeContractNames };
+export type { BlogFooterProps, HomeLayoutProps, NavItem, PostDetailProps, PostListProps, SidebarNavProps, SiteStatsData, SiteStatsProps, SubscribeCardProps, ThemeComponentContracts, ThemeContractName, ThemePostDetail, ThemePostSummary };

package/dist/default-contracts.mjs

@@ -0,0 +1,11 @@
+const themeContractNames = [
+  "HomeLayout",
+  "PostList",
+  "PostDetail",
+  "SidebarNav",
+  "SiteStats",
+  "SubscribeCard",
+  "BlogFooter"
+];
+
+export { themeContractNames };

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": ">=4.0.0"
   },
-  "version": "0.0.1",
+  "version": "0.0.3",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -470,6 +470,7 @@ async function checkCssVars(rootDir, themes, requiredCssVars) {
   });
 }
 
+const DEFAULT_CONTRACTS_IMPORT_ID$1 = "@tixxin/nuxt-theme-engine/default-contracts";
 function parseContractNames(source) {
   const match = source.match(/themeContractNames\s*=\s*\[([\s\S]*?)\]\s*as const/);
   if (!match) {
@@ -481,9 +482,10 @@ function parseContractNames(source) {
 async function generateThemeComponentDts(contractsSourcePath, contractsImportId) {
   const source = await promises.readFile(contractsSourcePath, "utf8");
   const names = parseContractNames(source);
+  const importSource = contractsImportId || DEFAULT_CONTRACTS_IMPORT_ID$1;
   const union = names.length > 0 ? names.map((name) => `'${name}'`).join(" | ") : "never";
   return `import type { DefineComponent } from 'vue'
-import type { ThemeComponentContracts } from ${JSON.stringify(contractsImportId)}
+import type { ThemeComponentContracts } from ${JSON.stringify(importSource)}
 
 declare module '#build/theme-engine.contracts.mjs' {
   export const themeEngineContracts: {
@@ -691,14 +693,15 @@ async function loadThemeDefinitions(themesDir) {
   return resolvedThemes.sort((left, right) => left.name.localeCompare(right.name));
 }
 
+const DEFAULT_CONTRACTS_IMPORT_ID = "@tixxin/nuxt-theme-engine/default-contracts";
 const DEFAULTS = {
   themesDir: "themes",
   defaultTheme: "base",
   cookieKey: "theme-pref",
   lazyLoadThemes: false,
   requiredCssVars: [],
-  contractsEntry: "@tixxin/theme-contracts",
-  contractsImportId: "@tixxin/theme-contracts"
+  contractsEntry: DEFAULT_CONTRACTS_IMPORT_ID,
+  contractsImportId: DEFAULT_CONTRACTS_IMPORT_ID
 };
 const require$1 = createRequire(import.meta.url);
 async function pathExists(path) {
@@ -712,10 +715,12 @@ async function pathExists(path) {
 function isLocalSpecifier(specifier) {
   return specifier.startsWith(".") || specifier.startsWith("/") || specifier.startsWith("~") || /^[A-Za-z]:[\\/]/.test(specifier);
 }
-async function resolveContractsEntry(entry, importId, rootDir, moduleRoot, aliases) {
-  const internalDefaultEntry = resolve(moduleRoot, "packages/theme-contracts/src/index.ts");
-  if ((entry === "@tixxin/theme-contracts" || entry === "packages/theme-contracts/src/index.ts") && await pathExists(internalDefaultEntry)) {
-    return internalDefaultEntry;
+async function resolveContractsEntry(entry, importId, rootDir, moduleRoot, defaultContractsEntry, aliases) {
+  if (entry === DEFAULT_CONTRACTS_IMPORT_ID || importId === DEFAULT_CONTRACTS_IMPORT_ID) {
+    return defaultContractsEntry;
+  }
+  if (entry === "packages/theme-contracts/src/index.ts" && await pathExists(resolve(rootDir, entry))) {
+    return resolve(rootDir, entry);
   }
   const aliasTarget = aliases[entry] ?? aliases[importId];
   if (typeof aliasTarget === "string") {
@@ -800,6 +805,7 @@ const module$1 = defineNuxtModule({
   async setup(moduleOptions, nuxt) {
     const resolver = createResolver(import.meta.url);
     const moduleRoot = resolver.resolve("..");
+    const defaultContractsEntry = resolver.resolve("./default-contracts");
     const options = {
       ...DEFAULTS,
       ...moduleOptions
@@ -811,6 +817,7 @@ const module$1 = defineNuxtModule({
       contractsImportId,
       nuxt.options.rootDir,
       moduleRoot,
+      defaultContractsEntry,
       nuxt.options.alias
     );
     const themes = await loadThemeDefinitions(themesDir);

package/dist/runtime/components/ThemeComponent.vue

@@ -1,8 +1,54 @@
 <script>
-import { computed, defineAsyncComponent, defineComponent, h, useAttrs, useSlots } from "vue";
+import { computed, defineAsyncComponent, defineComponent, h, onServerPrefetch, shallowRef, useAttrs, useSlots, watch } from "vue";
 import { themeComponentLoaders, themeComponentRegistry } from "#build/theme-engine.registry.mjs";
 import { useThemeEngine } from "../composables/useThemeEngine";
 const asyncComponentCache = /* @__PURE__ */ new Map();
+const loadedComponentCache = /* @__PURE__ */ new Map();
+const loadingTaskCache = /* @__PURE__ */ new Map();
+function resolveThemeComponent(themeName, componentName, firstThemeName) {
+  const entry = themeComponentRegistry[themeName]?.[componentName] ?? themeComponentRegistry[firstThemeName]?.[componentName];
+  const loader = themeComponentLoaders[themeName]?.[componentName] ?? themeComponentLoaders[firstThemeName]?.[componentName];
+  if (!entry || !loader) {
+    return null;
+  }
+  return {
+    cacheKey: `${entry.sourceTheme}:${componentName}`,
+    loader
+  };
+}
+async function loadThemeComponent(cacheKey, loader) {
+  const cachedComponent = loadedComponentCache.get(cacheKey);
+  if (cachedComponent) {
+    return cachedComponent;
+  }
+  const loadingTask = loadingTaskCache.get(cacheKey);
+  if (loadingTask) {
+    return loadingTask;
+  }
+  const task = loader().then((module) => {
+    const component = module.default ?? null;
+    if (component) {
+      loadedComponentCache.set(cacheKey, component);
+    }
+    return component;
+  }).finally(() => {
+    loadingTaskCache.delete(cacheKey);
+  });
+  loadingTaskCache.set(cacheKey, task);
+  return task;
+}
+function getAsyncComponent(cacheKey, loader) {
+  if (!asyncComponentCache.has(cacheKey)) {
+    asyncComponentCache.set(cacheKey, defineAsyncComponent(async () => {
+      const component = await loadThemeComponent(cacheKey, loader);
+      if (!component) {
+        throw new Error(`Theme component "${cacheKey}" failed to load.`);
+      }
+      return component;
+    }));
+  }
+  return asyncComponentCache.get(cacheKey) ?? null;
+}
 export default defineComponent({
   name: "ThemeComponent",
   inheritAttrs: false,
@@ -17,29 +63,53 @@ export default defineComponent({
     const slots = useSlots();
     const { currentTheme } = useThemeEngine();
     const firstThemeName = Object.keys(themeComponentRegistry)[0] ?? "";
-    const entry = computed(() => {
-      return themeComponentRegistry[currentTheme.value]?.[props.name] ?? themeComponentRegistry[firstThemeName]?.[props.name];
-    });
-    const resolvedComponent = computed(() => {
-      const resolvedEntry = entry.value;
-      if (!resolvedEntry) {
-        return null;
+    const displayedComponent = shallowRef(null);
+    const displayedCacheKey = shallowRef(null);
+    const targetComponent = computed(() => resolveThemeComponent(currentTheme.value, props.name, firstThemeName));
+    let activeRequestId = 0;
+    async function syncDisplayedComponent() {
+      const requestId = ++activeRequestId;
+      const resolvedTarget = targetComponent.value;
+      if (!resolvedTarget) {
+        displayedComponent.value = null;
+        displayedCacheKey.value = null;
+        return;
       }
-      const loader = themeComponentLoaders[currentTheme.value]?.[props.name] ?? themeComponentLoaders[firstThemeName]?.[props.name];
-      if (!loader) {
-        return null;
+      if (displayedCacheKey.value === resolvedTarget.cacheKey && displayedComponent.value) {
+        return;
       }
-      const cacheKey = `${resolvedEntry.sourceTheme}:${props.name}`;
-      if (!asyncComponentCache.has(cacheKey)) {
-        asyncComponentCache.set(cacheKey, defineAsyncComponent(loader));
+      const cachedComponent = loadedComponentCache.get(resolvedTarget.cacheKey);
+      if (cachedComponent) {
+        displayedComponent.value = cachedComponent;
+        displayedCacheKey.value = resolvedTarget.cacheKey;
+        return;
       }
-      return asyncComponentCache.get(cacheKey) ?? null;
+      const hasDisplayedComponent = Boolean(displayedComponent.value);
+      if (!hasDisplayedComponent) {
+        displayedComponent.value = getAsyncComponent(resolvedTarget.cacheKey, resolvedTarget.loader);
+        displayedCacheKey.value = resolvedTarget.cacheKey;
+      }
+      const loadedComponent = await loadThemeComponent(resolvedTarget.cacheKey, resolvedTarget.loader);
+      if (!loadedComponent || requestId !== activeRequestId) {
+        return;
+      }
+      displayedComponent.value = loadedComponent;
+      displayedCacheKey.value = resolvedTarget.cacheKey;
+    }
+    watch([
+      () => currentTheme.value,
+      () => props.name
+    ], () => {
+      void syncDisplayedComponent();
+    }, {
+      immediate: true
     });
+    onServerPrefetch(syncDisplayedComponent);
     return () => {
-      if (!resolvedComponent.value) {
+      if (!displayedComponent.value) {
         return null;
       }
-      return h(resolvedComponent.value, attrs, slots);
+      return h(displayedComponent.value, attrs, slots);
     };
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tixxin/nuxt-theme-engine",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "type": "module",
   "description": "A Nuxt 4 theme engine with layered themes, typed contracts, and runtime theme switching.",
   "license": "MIT",
@@ -11,6 +11,10 @@
       "types": "./dist/types.d.mts",
       "import": "./dist/module.mjs"
     },
+    "./default-contracts": {
+      "types": "./dist/default-contracts.d.mts",
+      "import": "./dist/default-contracts.mjs"
+    },
     "./runtime/*": "./dist/runtime/*"
   },
   "files": [
@@ -19,7 +23,7 @@
   "scripts": {
     "dev": "nuxi dev playground",
     "dev:prepare": "nuxi prepare playground",
-    "build": "pnpm --filter @tixxin/theme-contracts build && nuxt-module-build build",
+    "build": "nuxt-module-build build",
     "prepack": "pnpm build",
     "lint": "eslint .",
     "typecheck": "pnpm dev:prepare && tsc --noEmit -p tsconfig.json && vue-tsc --noEmit -p playground/.nuxt/tsconfig.json"
@@ -28,7 +32,6 @@
     "nuxt": "^4.0.0"
   },
   "dependencies": {
-    "@tixxin/theme-contracts": "workspace:*",
     "defu": "^6.1.6",
     "fast-glob": "^3.3.3",
     "pathe": "^2.0.3",