@tanstack/vue-hotkeys 0.19.1 → 0.21.0

package/dist/HotkeysProvider.d.ts

@@ -11,7 +11,8 @@ import { HotkeysProviderScopeProps } from "@tanstack/hotkeys/adapter";
  *
  * Nest providers to create hotkey scopes. A nested provider inherits app
  * hotkeys and merges default options. With `scope`, its hotkeys fire only
- * while it is mounted and enabled; with `exclusive`, only its hotkeys fire.
+ * while it is mounted, enabled, and not hidden by `<KeepAlive>`; with
+ * `exclusive`, only its hotkeys fire.
  *
  * @example
  * ```vue

package/dist/HotkeysProvider.js

@@ -10,7 +10,8 @@ import { defineComponent } from "vue";
 *
 * Nest providers to create hotkey scopes. A nested provider inherits app
 * hotkeys and merges default options. With `scope`, its hotkeys fire only
-* while it is mounted and enabled; with `exclusive`, only its hotkeys fire.
+* while it is mounted, enabled, and not hidden by `<KeepAlive>`; with
+* `exclusive`, only its hotkeys fire.
 *
 * @example
 * ```vue

package/dist/HotkeysProviderContext.d.ts

@@ -1,9 +1,15 @@
 import { UseHotkeyCommonOptions } from "./useHotkey.js";
-import { AppHotkeys, AppHotkeysStore, CustomHotkeys, HotkeyChordRecorderOptions, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
+import { AppHotkeys, AppHotkeysStore, CustomHotkeys, HotkeyChordRecorderOptions, HotkeyPlatform, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
 import { MaybeRefOrGetter } from "vue";
 import { HotkeysProviderScopeProps } from "@tanstack/hotkeys/adapter";
 //#region src/HotkeysProviderContext.d.ts
 export interface HotkeysProviderOptions {
+  /**
+   * The user's platform, for labels from `useFormatForDisplay`, hotkeys, and
+   * recorders. On a server, set it from the request with
+   * `detectPlatform(userAgent)`.
+   */
+  platform?: HotkeyPlatform;
   /**
    * Defaults for every hotkey registered by `useHotkey` and `useHotkeys`.
    * `requireReset` applies to chords and `timeout` applies to sequences.
@@ -51,8 +57,8 @@ export interface ProvideHotkeysContextOptions {
  *
  * Nest contexts to create hotkey scopes. A nested context inherits app
  * hotkeys and merges default options. With `scope`, its hotkeys fire only
- * while the component is mounted and enabled; with `exclusive`, only its
- * hotkeys fire.
+ * while the component is mounted, enabled, and not hidden by `<KeepAlive>`;
+ * with `exclusive`, only its hotkeys fire.
  *
  * @example
  * ```ts

package/dist/HotkeysProviderContext.js

@@ -1,3 +1,4 @@
+import { useLive } from "./_useLive.js";
 import { publishAppHotkeysStore } from "@tanstack/hotkeys";
 import { computed, hasInjectionContext, inject, onMounted, onScopeDispose, provide, toValue, watch } from "vue";
 import { activateHotkeysProviderScope, createAppHotkeysStore, getHotkeysProviderScopeKey, mergeHotkeysProviderDefaults } from "@tanstack/hotkeys/adapter";
@@ -12,8 +13,8 @@ const DEFAULT_OPTIONS = {};
 *
 * Nest contexts to create hotkey scopes. A nested context inherits app
 * hotkeys and merges default options. With `scope`, its hotkeys fire only
-* while the component is mounted and enabled; with `exclusive`, only its
-* hotkeys fire.
+* while the component is mounted, enabled, and not hidden by `<KeepAlive>`;
+* with `exclusive`, only its hotkeys fire.
 *
 * @example
 * ```ts
@@ -39,7 +40,8 @@ function provideHotkeysContext(options = {}) {
 		watch(() => toValue(options.customHotkeys), (customHotkeys) => store.setOptions({ customHotkeys }), { deep: true });
 		if (typeof document !== "undefined") onScopeDispose(publishAppHotkeysStore(store));
 	}
-	const active = computed(() => (parent?.enabled ?? true) && toValue(options.enabled) !== false);
+	const live = useLive();
+	const active = computed(() => live.value && (parent?.enabled ?? true) && toValue(options.enabled) !== false);
 	const defaultOptions = computed(() => mergeHotkeysProviderDefaults(parent?.defaultOptions, toValue(options.defaultOptions), toValue(options.scope)));
 	const scopeKey = computed(() => getHotkeysProviderScopeKey({
 		scope: toValue(options.scope),

package/dist/_useLive.js

@@ -0,0 +1,19 @@
+import { getCurrentInstance, onActivated, onDeactivated, ref } from "vue";
+
+//#region src/_useLive.ts
+/**
+* Whether the component is shown. A component in a page cached by
+* `<KeepAlive>` is not live while the page is hidden. Always true outside a
+* component, where the hooks would warn.
+*/
+function useLive() {
+	const live = ref(true);
+	if (getCurrentInstance()) {
+		onActivated(() => live.value = true);
+		onDeactivated(() => live.value = false);
+	}
+	return live;
+}
+
+//#endregion
+export { useLive };

package/dist/index.d.ts

@@ -9,6 +9,7 @@ import { VueHotkeyRecorder, useHotkeyRecorder } from "./useHotkeyRecorder.js";
 import { useHotkeyRegistrations } from "./useHotkeyRegistrations.js";
 import { useHotkeyScopesState } from "./useHotkeyScopesState.js";
 import { useHotkeyHint } from "./useHotkeyHint.js";
+import { useFormatForDisplay } from "./useFormatForDisplay.js";
 import { UseCustomHotkeysResult, useAppHotkeyList, useAppHotkeys, useCustomHotkeys } from "./useAppHotkeys.js";
 export * from "@tanstack/hotkeys";
-export { HotkeysProvider, HotkeysProviderOptions, ProvideHotkeysContextOptions, UseAppHotkeyOptions, UseCustomHotkeysResult, UseHotkeyChordOptions, UseHotkeyCommonOptions, UseHotkeyDefinition, UseHotkeyOptions, UseHotkeyOptionsFor, UseHotkeySequenceOptions, UseHotkeyTarget, VueHotkeyRecorder, provideHotkeysContext, useAppHotkeyList, useAppHotkeys, useCustomHotkeys, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeyScopesState, useHotkeys, useHotkeysContext, useKeyHold };
+export { HotkeysProvider, HotkeysProviderOptions, ProvideHotkeysContextOptions, UseAppHotkeyOptions, UseCustomHotkeysResult, UseHotkeyChordOptions, UseHotkeyCommonOptions, UseHotkeyDefinition, UseHotkeyOptions, UseHotkeyOptionsFor, UseHotkeySequenceOptions, UseHotkeyTarget, VueHotkeyRecorder, provideHotkeysContext, useAppHotkeyList, useAppHotkeys, useCustomHotkeys, useDefaultHotkeysOptions, useFormatForDisplay, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeyScopesState, useHotkeys, useHotkeysContext, useKeyHold };

package/dist/index.js

@@ -9,8 +9,9 @@ import { useHotkeyRecorder } from "./useHotkeyRecorder.js";
 import { useHotkeyRegistrations } from "./useHotkeyRegistrations.js";
 import { useHotkeyScopesState } from "./useHotkeyScopesState.js";
 import { useHotkeyHint } from "./useHotkeyHint.js";
+import { useFormatForDisplay } from "./useFormatForDisplay.js";
 import { useAppHotkeyList, useAppHotkeys, useCustomHotkeys } from "./useAppHotkeys.js";
 
 export * from "@tanstack/hotkeys"
 
-export { HotkeysProvider, provideHotkeysContext, useAppHotkeyList, useAppHotkeys, useCustomHotkeys, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeyScopesState, useHotkeys, useHotkeysContext, useKeyHold };
+export { HotkeysProvider, provideHotkeysContext, useAppHotkeyList, useAppHotkeys, useCustomHotkeys, useDefaultHotkeysOptions, useFormatForDisplay, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeyScopesState, useHotkeys, useHotkeysContext, useKeyHold };

package/dist/useFormatForDisplay.d.ts

@@ -0,0 +1,24 @@
+import { formatForDisplay } from "@tanstack/hotkeys";
+//#region src/useFormatForDisplay.d.ts
+/**
+ * Returns `formatForDisplay` with the provider's `platform` as the default,
+ * so labels match the user's platform. Call in `setup`; the returned function
+ * works anywhere, and templates update when the provider's platform changes.
+ * An explicit `platform` option wins.
+ *
+ * Server-rendered apps should set the provider's `defaultOptions.platform`
+ * from the request user agent with `detectPlatform(userAgent)`.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * const format = useFormatForDisplay()
+ * </script>
+ *
+ * <template>
+ *   <kbd>{{ format('Mod+S') }}</kbd>
+ * </template>
+ * ```
+ */
+export declare function useFormatForDisplay(): typeof formatForDisplay;
+//#endregion

package/dist/useFormatForDisplay.js

@@ -0,0 +1,34 @@
+import { useDefaultHotkeysOptionsSource } from "./defaultOptions.js";
+import { formatForDisplay } from "@tanstack/hotkeys";
+
+//#region src/useFormatForDisplay.ts
+/**
+* Returns `formatForDisplay` with the provider's `platform` as the default,
+* so labels match the user's platform. Call in `setup`; the returned function
+* works anywhere, and templates update when the provider's platform changes.
+* An explicit `platform` option wins.
+*
+* Server-rendered apps should set the provider's `defaultOptions.platform`
+* from the request user agent with `detectPlatform(userAgent)`.
+*
+* @example
+* ```vue
+* <script setup lang="ts">
+* const format = useFormatForDisplay()
+* <\/script>
+*
+* <template>
+*   <kbd>{{ format('Mod+S') }}</kbd>
+* </template>
+* ```
+*/
+function useFormatForDisplay() {
+	const defaultOptions = useDefaultHotkeysOptionsSource();
+	return ((hotkey, options) => formatForDisplay(hotkey, {
+		...options,
+		platform: options?.platform ?? defaultOptions().platform
+	}));
+}
+
+//#endregion
+export { useFormatForDisplay };

package/dist/useHotkeyRecorder.js

@@ -1,7 +1,8 @@
+import { useLive } from "./_useLive.js";
 import { useStoreSelector } from "./useStoreSelector.js";
 import { useDefaultHotkeysOptionsSource } from "./defaultOptions.js";
 import { HotkeyRecorder } from "@tanstack/hotkeys";
-import { onScopeDispose, toValue, watch } from "vue";
+import { getCurrentInstance, onScopeDispose, toValue, watch } from "vue";
 import { withDefaults } from "@tanstack/hotkeys/adapter";
 
 //#region src/useHotkeyRecorder.ts
@@ -13,6 +14,12 @@ function useHotkeyRecorder(options) {
 	const steps = useStoreSelector(recorder.store, (state) => state.steps);
 	const recordedHotkey = useStoreSelector(recorder.store, (state) => state.recordedHotkey);
 	const stopWatcher = watch(resolve, (resolved) => recorder.setOptions(resolved));
+	const instance = getCurrentInstance();
+	const hidden = () => {
+		for (let i = instance; i; i = i.parent) if (i.isDeactivated) return true;
+		return false;
+	};
+	watch(useLive(), (live) => live || recorder.store.state.isRecording && recorder.stop());
 	onScopeDispose(() => {
 		stopWatcher();
 		recorder.destroy();
@@ -21,7 +28,9 @@ function useHotkeyRecorder(options) {
 		isRecording,
 		steps,
 		recordedHotkey,
-		startRecording: () => recorder.start(),
+		startRecording: () => {
+			if (!hidden()) recorder.start();
+		},
 		stopRecording: () => recorder.stop(),
 		cancelRecording: () => recorder.cancel(),
 		commitRecording: () => recorder.commit()

package/dist/useHotkeys.js

@@ -1,3 +1,4 @@
+import { useLive } from "./_useLive.js";
 import { useAppHotkeysStoreSource, useDefaultHotkeysOptionsSource } from "./defaultOptions.js";
 import { onScopeDispose, toValue, watch } from "vue";
 import { createHotkeyBindings, prepareHotkeyDefinitions } from "@tanstack/hotkeys/adapter";
@@ -34,7 +35,9 @@ function useHotkeys(hotkeys, commonOptions = {}) {
 	const defaultOptions = useDefaultHotkeysOptionsSource();
 	const appHotkeys = useAppHotkeysStoreSource();
 	const bindings = createHotkeyBindings();
+	const live = useLive();
 	const stopWatcher = watch(() => {
+		if (!live.value) return [];
 		appHotkeys.state.value;
 		const definitions = toValue(hotkeys).map((definition) => ({
 			hotkey: toValue(definition.hotkey),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/vue-hotkeys",
-  "version": "0.19.1",
+  "version": "0.21.0",
   "description": "Vue adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -38,7 +38,7 @@
     "skills"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.22.0"
+    "@tanstack/hotkeys": "0.23.0"
   },
   "devDependencies": {
     "@vitejs/plugin-vue": "^6.0.9",

package/skills/vue-hotkeys/SKILL.md

@@ -60,6 +60,7 @@ useHotkey('Escape', () => closePanel(), { target: panel })
 | `provideHotkeysContext(options)`          | Provide the same options from a component's setup instead of rendering `HotkeysProvider`; they apply to its children.                                                                                    |
 | `useHotkeysContext()`                     | Read the nearest provider's merged defaults and enabled state, or `null` outside a provider.                                                                                                             |
 | `useDefaultHotkeysOptions()`              | Read the default options merged from every provider above.                                                                                                                                               |
+| `useFormatForDisplay()`                   | Get `formatForDisplay` with the provider's `platform` filled in, for labels in server-rendered apps. Call it in `setup`.                                                                                 |
 | `useAppHotkeys()`                         | Get a computed ref of the declared app hotkeys with the user's custom hotkeys applied.                                                                                                                   |
 | `useAppHotkeyList()`                      | Get a computed ref listing every app hotkey with its status, for a cheat sheet or settings screen.                                                                                                       |
 | `useCustomHotkeys()`                      | Read, change, and reset the user's custom hotkeys, and check a new one for conflicts.                                                                                                                    |
@@ -82,6 +83,7 @@ No provider is required. Call the composables synchronously in setup.
 - **Destructure the recorder.** Templates unwrap only top-level refs, so `v-if="recorder.isRecording"` is always true. Use `const { isRecording, startRecording } = useHotkeyRecorder(...)`.
 - **The callback isn't tracked.** Read refs and props inside it.
 - **Call the composables directly.** A `useShortcut(keys: string)` wrapper has to cast strings to hotkeys, which turns off type checking and drops sequences, reactive options, and app hotkeys.
+- **Server-rendered labels need the user's platform.** On the server, `formatForDisplay` can't see the user's OS, so it renders Linux labels that differ after hydration for Mac and Windows users. Set the provider's `defaultOptions.platform` to `detectPlatform(userAgent)` from the request's `User-Agent` header, and format labels with `const format = useFormatForDisplay()` in `setup`, then `format(hotkey)`. Keep plain `formatForDisplay` for labels that render only in the browser.
 
 When declaring app hotkeys, building a cheat sheet, or letting users rebind shortcuts, load `@tanstack/hotkeys#app-hotkeys` and read [app hotkeys in Vue](references/app-hotkeys.md).