@bndynet/vue-site 0.1.0 → 0.1.1

package/README.md

@@ -109,12 +109,14 @@ import config from './site.config'
 createSiteApp(config).mount('#app')
 ```
 
-Exports: `createSiteApp`, `defineConfig`, `useTheme`, `useSiteConfig`. Types: `SiteConfig`, `SiteEnvConfig`, `SiteViteConfig`, `SiteExternalLink`, `NavItem`, `ThemeConfig`, `ThemeOption`, `ThemePaletteVars`, `ResolvedNavItem`.
+Exports: `createSiteApp`, `defineConfig`, `useTheme`, `useSiteConfig`, `themeRefKey`. Types: `SiteConfig`, `SiteEnvConfig`, `SiteViteConfig`, `SiteExternalLink`, `NavItem`, `ThemeConfig`, `ThemeOption`, `ThemePaletteVars`, `ResolvedNavItem`.
 
 ### Theme in Vue pages (`useTheme`)
 
 Import `useTheme` from `@bndynet/vue-site`. It returns a reactive `theme` ref (the active theme id, e.g. `light`, `dark`, or an `extraThemes[].id`) plus `setTheme` and `toggleTheme`. The root layout also sets `document.documentElement` attribute `data-theme` and applies CSS variables, so you can style with `var(--color-*)` without JavaScript.
 
+The theme ref is **provided** by `createSiteApp()` (same Vue runtime as your app), so `watch(theme, …)` works reliably even when another tool would otherwise load a second copy of `vue` from nested `node_modules`.
+
 ```vue
 <script setup lang="ts">
 import { watch } from 'vue'
@@ -132,6 +134,8 @@ watch(theme, (next, prev) => {
 </template>
 ```
 
+`watch` only runs when the theme **changes** after your component is set up (for example after the user clicks the theme control). It does not run on the initial value unless you pass `{ immediate: true }`.
+
 ## Upgrade
 
 ```bash

package/dist/composables/useTheme.d.ts

@@ -1,12 +1,16 @@
+import { InjectionKey, Ref } from 'vue';
+/** Use `Symbol.for` so the key matches even if multiple copies of this package are resolved. */
+export declare const themeRefKey: InjectionKey<Ref<string>>;
 /**
+ * @param themeRef — ref created next to `createApp` so it uses the same Vue runtime as the app (fixes `watch(theme)` when npm/Vite dedupes `vue` imperfectly).
  * @param defaultMode — used when nothing valid is in localStorage
  * @param themeIds — full list of allowed ids (built-in `light`/`dark` plus any `extraThemes`)
  * @param palettes — resolved CSS variable maps per id
  * @param overlay — optional `:root` overrides applied after the active palette
  */
-export declare function initTheme(defaultMode?: string, themeIds?: readonly string[], palettes?: Record<string, Record<string, string>>, overlay?: Record<string, string>): void;
+export declare function initTheme(themeRef: Ref<string>, defaultMode?: string, themeIds?: readonly string[], palettes?: Record<string, Record<string, string>>, overlay?: Record<string, string>): void;
 export declare function useTheme(): {
-    theme: import('vue').Ref<string, string>;
+    theme: Ref<string, string>;
     setTheme: (mode: string) => void;
     toggleTheme: () => void;
 };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { SiteConfig } from './types';
 export { createSiteApp } from './create-app';
-export { useTheme } from './composables/useTheme';
+export { useTheme, themeRefKey } from './composables/useTheme';
 export { useSiteConfig } from './composables/useSiteConfig';
 export { builtinThemePalettes } from './theme/presets';
 export type { SiteConfig, SiteEnvConfig, SiteViteConfig, SiteExternalLink, NavItem, ThemeConfig, ThemeOption, ThemePaletteVars, ResolvedNavItem, } from './types';