fix(shortcut): revert semver breaking changes in 4.0.1

vnphanquang · Dec 19, 2024 · b86c53c · b86c53c
1 parent 136109d
commit b86c53c
Show file tree

Hide file tree

Showing 4 changed files with 51 additions and 35 deletions.
diff --git a/.changeset/weak-countries-shop.md b/.changeset/weak-countries-shop.md
@@ -0,0 +1,6 @@
+---
+'@svelte-put/shortcut': minor
+---
+
+resolve #334, deprecate [4.0.1](https://github.com/vnphanquang/svelte-put/releases/tag/%40svelte-put/shortcut%404.0.1) (break semver): revert default modifier to catch-all , drop `*` modifier definition (leave `undefined` instead).
+
diff --git a/packages/shortcut/src/shortcut.js b/packages/shortcut/src/shortcut.js
@@ -61,7 +61,7 @@ function mapModifierToBitMask(def) {
  *       },
  *       {
  *         key: 'Escape',
- *         modifier: undefined, // or any falsy value to means 'expect no modifier'
+ *         modifier: false, // or any falsy value other than undefined to means 'expect no modifier'
  *
  *         // preferably avoid arrow functions here for better performance
  *         // with arrow functions the action has to be updated more frequently
@@ -124,13 +124,13 @@ export function shortcut(node, param) {
 			if (triggerEnabled) {
 				if (event.key !== key) continue;
 
-				if (!modifier) {
+				if (modifier === null || modifier === false) {
 					if (modifierMask !== 0b0000) continue;
-				} else if (modifier === '*') {
-					if (modifierMask === 0b0000) continue;
-				} else {
+				} else if (
+					modifier !== undefined &&
+					modifier?.[0]?.length > 0
+				) {
 					const orDefs = Array.isArray(modifier) ? modifier : [modifier];
-
 					let modified = false;
 					for (const orDef of orDefs) {
 						const mask = (Array.isArray(orDef) ? orDef : [orDef]).reduce(
@@ -142,7 +142,6 @@ export function shortcut(node, param) {
 							break;
 						}
 					}
-
 					if (!modified) continue;
 				}
 

diff --git a/packages/shortcut/src/types.public.d.ts b/packages/shortcut/src/types.public.d.ts
@@ -24,7 +24,7 @@ export type ShortcutModifier = 'alt' | 'ctrl' | 'meta' | 'shift';
  *
  * @example
  *
- * Listen for no modifier
+ * Listen for key (catch-all, modifier or not)
  *
  * ```svelte
  * <script>
@@ -33,15 +33,15 @@ export type ShortcutModifier = 'alt' | 'ctrl' | 'meta' | 'shift';
  *
  * <window use:shortcut={{
  *   trigger: {
- *    key: 'k', // only trigger when no modifier is pressed
+ *    key: 'k',
  *   },
  * }}
  * />
  * ```
  *
  * @example
  *
- * Listen for any modifier (ctrl, shift, alt, or meta)
+ * Listen for key with no modifier
  *
  * ```svelte
  * <script>
@@ -50,15 +50,16 @@ export type ShortcutModifier = 'alt' | 'ctrl' | 'meta' | 'shift';
  *
  * <window use:shortcut={{
  *   trigger: {
- *    key: '*',
+ *    key: 'k',
+ *    modifier: false,  // only trigger when no modifier is pressed
  *   },
  * }}
  * />
  * ```
  *
  * @example
  *
- * Listen for a single modifier
+ * Listen for key with a single modifier
  *
  * ```svelte
  * <script>
@@ -76,7 +77,7 @@ export type ShortcutModifier = 'alt' | 'ctrl' | 'meta' | 'shift';
  *
  * @example
  *
- * Listen for one of many modifiers (or)
+ * Listen for key with one of many modifiers (or)
  *
  * ```svelte
  * <script>
@@ -94,7 +95,7 @@ export type ShortcutModifier = 'alt' | 'ctrl' | 'meta' | 'shift';
  *
  * @example
  *
- * Listen for a combination of multiple modifiers (and)
+ * Listen for key with a combination of multiple modifiers (and)
  *
  * ```svelte
  * <script>
@@ -133,13 +134,10 @@ export type ShortcutModifier = 'alt' | 'ctrl' | 'meta' | 'shift';
  * ```
  */
 export type ShortcutModifierDefinition =
-	| undefined // none
 	| null // none
 	| false // none
-	| '*' // any
 	| ShortcutModifier // one
-	| ShortcutModifier[] // one of (OR)
-	| ShortcutModifier[][]; // all of (AND)
+	| (ShortcutModifier|ShortcutModifier[])[] // all of (AND);
 
 /**
  * A definition of a shortcut trigger
@@ -152,7 +150,7 @@ export interface ShortcutTrigger {
 	 *  but event listener is still placed on node
 	 */
 	enabled?: boolean;
-	/** modifier key to listen to in conjunction of `key` */
+	/** modifier key to listen to in conjunction of `key`, defaults to `undefined` (catch-all) */
 	modifier?: ShortcutModifierDefinition;
 	/** id to distinguish this trigger from others, recommended when using `onshortcut` */
 	id?: string;

diff --git a/sites/docs/src/packages/shortcut/docs.md.svelte b/sites/docs/src/packages/shortcut/docs.md.svelte
@@ -1,6 +1,5 @@
 <script>
-	import { SettingsContext } from '$lib/settings/context.svelte';
-
+  import { SettingsContext } from '$lib/settings/context.svelte';
   const settings = SettingsContext.get();
 </script>
 
@@ -95,40 +94,35 @@ This approach does take up some additional memory. It should be negligible in mo
 
 Each `ShortcutTrigger` can specify either one or multiple modifiers (`ctrl`, `meta`, `alt`, `shift`) via `trigger.modifier` in both `AND` & `OR` fashions.
 
-### No modifier
-
-<p class="c-callout c-callout--info c-callout--icon-megaphone w-fit">
-  Available since <a href="https://github.com/vnphanquang/svelte-put/releases/tag/%40svelte-put%2Fshortcut%404.0.1">v4.0.1</a>.
-</p>
+### Catch all
 
-Simply omit `trigger.modifier` or set it to any falsy value — `false`, `null`, or `undefined` — to
-listen for the key without any modifier.
+When left as `undefined`, `trigger.modifier` means "don't check for modifiers".
 
 ```svelte title=modifier-single.svelte
 <svelte:window
   use:shortcut={{
     trigger: {
-      key: 'Escape',
+      key: 'k',
     },
   }}
 />
 ```
 
-### Any modifier
+### No modifier
 
 <p class="c-callout c-callout--info c-callout--icon-megaphone w-fit">
-  Available since <a href="https://github.com/vnphanquang/svelte-put/releases/tag/%40svelte-put%2Fshortcut%404.0.1">v4.0.1</a>.
+  Available since <a href="https://github.com/vnphanquang/svelte-put/releases/tag/%40svelte-put%2Fshortcut%404.1.0">v4.1.0</a>.
 </p>
 
-Set `trigger.modifier` to `*` to listen for the key with any modifier.
+Set `trigger.modifier` to `false` or `null` for keys that expect **no** modifier.
 
 ```svelte title=modifier-single.svelte
 <svelte:window
   use:shortcut={{
     trigger: {
-      key: 'k',
+      key: 'Escape',
       <!-- :::highlight -->
-      modifier: '*',
+      modifier: false,
       <!-- ::: -->
     },
   }}
@@ -269,7 +263,7 @@ Handlers can be provided via either `trigger.callback`...
 
 <div class="c-callout c-callout--info">
 
-`trigger.id` is specified definition in the `handler-custom-event.svelte` example to conveniently help identify the trigger in the `onshortcut` event listener.
+`trigger.id` is specified in the `handler-custom-event.svelte` example to conveniently help identify the trigger in the `onshortcut` event listener.
 
 </div>
 
@@ -281,6 +275,25 @@ You should use only one of the two presented approaches and **NOT** both to avoi
 
 </div>
 
+## Event Type
+
+`@svelte-put/shortcut` support `keydown` (default) or `keyup` event type. You may change this via
+the `type` option.
+
+```svelte title=event-type.svelte
+<svelte:window
+  use:shortcut={{
+    trigger: {
+      key: 'k',
+      modifier: ['ctrl', 'meta'],
+    },
+    <!-- :::highlight -->
+    type: 'keyup',
+    <!-- ::: -->
+  }}
+/>
+```
+
 ## Original `KeyboardEvent`
 
 You can access the original `KeyboardEvent` via `detail.originalEvent`. This is helpful for checking `target`.