feat: callback version of conflictBehavior

.changeset/vast-jokes-serve.md

@@ -0,0 +1,6 @@
+---
+'@tanstack/hotkeys-devtools': patch
+'@tanstack/hotkeys': patch
+---
+
+feat: callback variant of conflictBehavior

docs/reference/type-aliases/ConflictBehavior.md

@@ -6,7 +6,10 @@ title: ConflictBehavior
 # Type Alias: ConflictBehavior
 
 ```ts
-type ConflictBehavior = "warn" | "error" | "replace" | "allow";
+type ConflictBehavior = "warn" | "error" | "replace" | "allow" | (
+  keyDisplay: string,
+  unregisterConflicting: () => void
+) => void;
 ```
 
 Defined in: [manager.utils.ts:11](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/manager.utils.ts#L11)
@@ -17,3 +20,4 @@ Behavior when registering a hotkey/sequence that conflicts with an existing regi
 - `'error'` - Throw an error and prevent the new registration
 - `'replace'` - Unregister the existing registration and register the new one
 - `'allow'` - Allow multiple registrations without warning
+- custom callback - You can log the issue with configuration or unregister conflicting registration conditionally e.g. with showing confirmation popup 

packages/hotkeys-devtools/src/components/DetailsPanel.tsx

@@ -119,7 +119,18 @@ function getConflictLabel(
   if (behavior === 'allow') return 'allowed'
   if (behavior === 'error') return 'error'
   if (behavior === 'replace') return 'replaced'
-  return 'warning'
+  if (behavior === 'warn') return 'warning'
+  return 'callback handled conflict with'
+}
+
+function serializeConflictBehavior(
+  behavior: ConflictBehavior
+): string {
+  if (typeof behavior === 'string') {
+    return behavior
+  }
+
+  return '[Function function]'
 }
 
 function HotkeyDetails(props: {
@@ -285,7 +296,7 @@ function HotkeyDetails(props: {
             </div>
             <div class={styles().optionRow}>
               <span class={styles().optionLabel}>conflictBehavior</span>
-              <span class={styles().optionValue}>{conflictBehavior()}</span>
+              <span class={styles().optionValue}>{serializeConflictBehavior(conflictBehavior())}</span>
             </div>
             <div class={styles().optionRow}>
               <span class={styles().optionLabel}>hasFired</span>
@@ -498,7 +509,7 @@ function SequenceDetails(props: {
             </div>
             <div class={styles().optionRow}>
               <span class={styles().optionLabel}>conflictBehavior</span>
-              <span class={styles().optionValue}>{conflictBehavior()}</span>
+              <span class={styles().optionValue}>{serializeConflictBehavior(conflictBehavior())}</span>
             </div>
           </div>
         </div>

packages/hotkeys/src/manager.utils.ts

@@ -1,5 +1,10 @@
 import type { ParsedHotkey } from './hotkey'
 
+type CustomConflictHandler = (
+  keyDisplay: string,
+  unregisterAnotherConflictingId: () => void
+) => void
+
 /**
  * Behavior when registering a hotkey/sequence that conflicts with an existing registration.
  *
@@ -8,7 +13,7 @@ import type { ParsedHotkey } from './hotkey'
  * - `'replace'` - Unregister the existing registration and register the new one
  * - `'allow'` - Allow multiple registrations without warning
  */
-export type ConflictBehavior = 'warn' | 'error' | 'replace' | 'allow'
+export type ConflictBehavior = 'warn' | 'error' | 'replace' | 'allow' | CustomConflictHandler
 
 /**
  * Default options for hotkey/sequence registration.
@@ -164,6 +169,11 @@ export function handleConflict(
     )
   }
 
+  if (typeof conflictBehavior === 'function') {
+      conflictBehavior(keyDisplay, () => unregister(conflictingId))
+      return
+  }
+
   // At this point, conflictBehavior must be 'replace'
   unregister(conflictingId)
 }

packages/hotkeys/tests/manager.utils.test.ts

@@ -286,5 +286,20 @@ describe('manager.utils', () => {
 
       expect(unregister).toHaveBeenCalledWith('id-1')
     })
+
+    it('should call custom callback if passed as conflictBehaviour', () => {
+      const unregister = vi.fn()
+      const handleConflictCallback = vi.fn()
+
+      handleConflict('id-1', 'Mod+S', handleConflictCallback, unregister)
+
+      expect(unregister).not.toHaveBeenCalledWith()
+      expect(handleConflictCallback).toHaveBeenCalledWith(
+        'Mod+S',
+        expect.any(Function),
+      )
+      handleConflictCallback.mock.calls[0]?.[1]()
+      expect(unregister).toHaveBeenCalledWith('id-1')
+    })
   })
 })