Skip to content

armgit / dify

Public Imported from GitHub
0

Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.

fix(web): upgrade TanStack Hotkeys and isolate search commands (#44401)

yyh88529a0dcdda
diff --git a/.agents/skills/how-to-write-component/references/interactions.md b/.agents/skills/how-to-write-component/references/interactions.md
index 10e5f86990b..784c0da7ae0 100644
--- a/.agents/skills/how-to-write-component/references/interactions.md
+++ b/.agents/skills/how-to-write-component/references/interactions.md
@@ -11,7 +11,7 @@ Read this document when a change involves application hotkeys, focus, dialogs, m
## Keyboard Commands
- Keep widget navigation, dialog dismissal, and editor commands in their local primitive or owner.
-- For Web application commands, follow [Keyboard commands] for TanStack registration, typed bindings, targets, event consumption, display, and verification. Do not recreate that policy in a wrapper or a second command framework.
+- For Web application commands, follow [Keyboard commands]. Keep registration and business behavior with the feature owner; do not introduce a second command framework.
## Secondary Surfaces
diff --git a/packages/dify-ui/src/kbd/index.stories.tsx b/packages/dify-ui/src/kbd/index.stories.tsx
index bdc1342966d..2147def650a 100644
--- a/packages/dify-ui/src/kbd/index.stories.tsx
+++ b/packages/dify-ui/src/kbd/index.stories.tsx
@@ -1,5 +1,5 @@
import type { Meta, StoryObj } from '@storybook/react-vite'
-import type { DisplayHotkey, FormatDisplayOptions } from '@tanstack/react-hotkeys'
+import type { DisplayHotkeyChord, FormatDisplayOptions } from '@tanstack/react-hotkeys'
import { formatForDisplay } from '@tanstack/react-hotkeys'
import { Kbd, KbdGroup } from '.'
import {
@@ -48,7 +48,7 @@ function HotkeyKbdGroup({
color = 'gray',
platform = 'mac',
}: {
- hotkey: DisplayHotkey
+ hotkey: DisplayHotkeyChord
color?: 'gray' | 'white'
platform?: FormatDisplayOptions['platform']
}) {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 1daae39b847..3f9d00b1710 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -330,8 +330,8 @@ catalogs:
specifier: 1.33.5
version: 1.33.5
'@tanstack/react-hotkeys':
- specifier: 0.13.0
- version: 0.13.0
+ specifier: 0.16.0
+ version: 0.16.0
'@tanstack/react-query':
specifier: 5.104.4
version: 5.104.4
@@ -1129,7 +1129,7 @@ importers:
'@tanstack/react-hotkeys':
specifier: 'catalog:'
'@tanstack/react-virtual':
specifier: 'catalog:'
@@ -1448,7 +1448,7 @@ importers:
'@tanstack/react-hotkeys':
specifier: 'catalog:'
'@tanstack/react-query':
specifier: 'catalog:'
version: 5.104.4(@types/[email protected])([email protected])
@@ -4620,8 +4620,8 @@ packages:
'@tanstack/[email protected]':
resolution: {integrity: sha512-3dfx9MBP0aq5sXKteikG629X9oviptrQj0IFRk9YGcb+lB7Kv5x8S17oOSk1wUWgjQZ4xVJEMbKwOAODymocgA==}
- '@tanstack/[email protected]':
- resolution: {integrity: sha512-uFKTuknj3sNp5ERoxsI0ISMMOVw3KmSkgy2iIcp19QR/zheYm7bkwzNndMv5NDAqhXpavOn6h4A6HPVJFCBXPg==}
+ '@tanstack/[email protected]':
+ resolution: {integrity: sha512-HhgfF+Wqz3ofCQaDHXSkItRbLXmigoHsxJsQGbGc3Kgu/gunwcFLqVubfoUmdRK/YN7fuZYN2vEOk3oMGxSWTg==}
engines: {node: '>=20'}
'@tanstack/[email protected]':
@@ -4640,8 +4640,8 @@ packages:
'@tanstack/react-start':
optional: true
- '@tanstack/[email protected]':
- resolution: {integrity: sha512-+iF7bQe1YegbMa/mL7Zl490OXjSuGLlu2IPYd2YcvdeI8OcTHfdENPrRNk7PklWQ2WAIJjCVxMXiQ/Uiq8fzIQ==}
+ '@tanstack/[email protected]':
+ resolution: {integrity: sha512-mP1ZFjBdqllK5xrUU2BGi2ZAryrVmgCAsWSEVJWq1w+qkxRNZ+c5h+J7+99sTwhVa2dLIgnJwE2PzITSopUZnA==}
engines: {node: '>=20'}
peerDependencies:
react: '>=16.8'
@@ -11734,7 +11734,7 @@ snapshots:
'@tanstack/pacer-lite': 0.1.1
'@tanstack/store': 0.11.2
- '@tanstack/[email protected]':
+ '@tanstack/[email protected]':
dependencies:
'@tanstack/store': 0.11.2
@@ -11750,9 +11750,9 @@ snapshots:
transitivePeerDependencies:
- react-dom
dependencies:
- '@tanstack/hotkeys': 0.11.0
+ '@tanstack/hotkeys': 0.17.0
'@tanstack/react-store': 0.11.2([email protected]([email protected]))([email protected])
react: 19.3.1
react-dom: 19.3.1([email protected])
@@ -17007,7 +17007,7 @@ time:
'@tanstack/[email protected]': '2026-08-11T12:45:38.255Z'
'@tanstack/[email protected]': '2026-10-17T17:54:27.802Z'
'@tanstack/[email protected]': '2026-08-11T12:45:38.642Z'
- '@tanstack/[email protected]': '2026-10-04T05:10:59.975Z'
+ '@tanstack/[email protected]': '2026-10-19T18:24:08.957Z'
'@tanstack/[email protected]': '2026-10-17T17:55:14.077Z'
'@tanstack/[email protected]': '2026-10-16T11:19:18.479Z'
'@testing-library/[email protected]': '2026-09-13T18:08:36.116Z'
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 38fb17686aa..216953b7680 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -123,7 +123,7 @@ catalog:
'@tanstack/form-core': 1.33.5
'@tanstack/query-core': 5.104.4
'@tanstack/react-form': 1.33.5
- '@tanstack/react-hotkeys': 0.13.0
+ '@tanstack/react-hotkeys': 0.16.0
'@tanstack/react-query': 5.104.4
'@tanstack/react-virtual': 3.14.21
'@testing-library/dom': 10.4.2
diff --git a/web/app/components/app/app-publisher/hotkeys.ts b/web/app/components/app/app-publisher/hotkeys.ts
index a1b8f13b397..3fab978cc7e 100644
--- a/web/app/components/app/app-publisher/hotkeys.ts
+++ b/web/app/components/app/app-publisher/hotkeys.ts
@@ -1,3 +1,3 @@
-import type { Hotkey } from '@tanstack/react-hotkeys'
+import type { HotkeyChord } from '@tanstack/react-hotkeys'
-export const APP_PUBLISH_HOTKEY = 'Mod+Shift+P' satisfies Hotkey
+export const APP_PUBLISH_HOTKEY = 'Mod+Shift+P' satisfies HotkeyChord
diff --git a/web/app/components/app/create-app-modal/index.tsx b/web/app/components/app/create-app-modal/index.tsx
index e3a69ba5bee..60ed21990ac 100644
--- a/web/app/components/app/create-app-modal/index.tsx
+++ b/web/app/components/app/create-app-modal/index.tsx
@@ -1,6 +1,6 @@
'use client'
-import type { Hotkey } from '@tanstack/react-hotkeys'
+import type { HotkeyChord } from '@tanstack/react-hotkeys'
import type { AppType } from '@/app/components/apps/app-type'
import type { IconPickerValue } from '@/app/components/base/icon-picker'
import { zPostAppsBody } from '@dify/contracts/api/console/apps/zod.gen'
@@ -44,7 +44,7 @@ type CreateAppProps = {
defaultAppMode?: AppType
}
-const CREATE_APP_HOTKEY = 'Mod+Enter' satisfies Hotkey
+const CREATE_APP_HOTKEY = 'Mod+Enter' satisfies HotkeyChord
const shouldExpandBeginnerAppTypes = (appMode?: AppType) => {
return appMode === 'chat' || appMode === 'agent-chat' || appMode === 'completion'
diff --git a/web/app/components/app/create-from-dsl-modal/index.tsx b/web/app/components/app/create-from-dsl-modal/index.tsx
index 73b462b2763..f42f56aa1ff 100644
--- a/web/app/components/app/create-from-dsl-modal/index.tsx
+++ b/web/app/components/app/create-from-dsl-modal/index.tsx
@@ -1,7 +1,7 @@
'use client'
import type { AppImportPayload, AppMode, Import } from '@dify/contracts/api/console/apps/types.gen'
-import type { Hotkey } from '@tanstack/react-hotkeys'
+import type { HotkeyChord } from '@tanstack/react-hotkeys'
import { Button } from '@langgenius/dify-ui/button'
import {
Dialog,
@@ -62,7 +62,7 @@ type ImportSource =
| { type: (typeof CreateFromDSLModalTab)['FROM_FILE']; file: File }
| { type: (typeof CreateFromDSLModalTab)['FROM_URL']; url: string }
-const CREATE_FROM_DSL_HOTKEY = 'Mod+Enter' satisfies Hotkey
+const CREATE_FROM_DSL_HOTKEY = 'Mod+Enter' satisfies HotkeyChord
function getImportedAppMode(mode?: string | null): AppMode | undefined {
switch (mode) {
diff --git a/web/app/components/base/prompt-editor/index.tsx b/web/app/components/base/prompt-editor/index.tsx
index 36d7d5be070..728dcc124fb 100644
--- a/web/app/components/base/prompt-editor/index.tsx
+++ b/web/app/components/base/prompt-editor/index.tsx
@@ -1,7 +1,7 @@
'use client'
import type { InitialConfigType } from '@lexical/react/LexicalComposer'
-import type { Hotkey } from '@tanstack/react-hotkeys'
+import type { HotkeyChord } from '@tanstack/react-hotkeys'
import type { EditorState } from 'lexical'
import type { FC } from 'react'
import type {
@@ -125,7 +125,7 @@ type PromptEditorProps = PromptEditorAriaProps & {
disableSlashPicker?: boolean
disableBracePicker?: boolean
shortcutPopups?: Array<{
- hotkey: Hotkey
+ hotkey: HotkeyChord
displayMode?: ShortcutPopupDisplayMode
Popup: React.ComponentType<{ onClose: () => void; onInsert: ShortcutPopupInsertHandler }>
}>
diff --git a/web/app/components/base/prompt-editor/plugins/hitl-input-block/input-field.tsx b/web/app/components/base/prompt-editor/plugins/hitl-input-block/input-field.tsx
index 48f23f98038..fcbf0c75651 100644
--- a/web/app/components/base/prompt-editor/plugins/hitl-input-block/input-field.tsx
+++ b/web/app/components/base/prompt-editor/plugins/hitl-input-block/input-field.tsx
@@ -1,4 +1,4 @@
-import type { Hotkey } from '@tanstack/react-hotkeys'
+import type { HotkeyChord } from '@tanstack/react-hotkeys'
import type { Item as TypeSelectItem } from '@/app/components/app/configuration/config-var/config-modal/type-select'
import type {
FormInputItem,
@@ -31,7 +31,7 @@ import { InputVarType, VarType } from '@/app/components/workflow/types'
import PrePopulate from './pre-populate'
import TypeSwitch from './type-switch'
-const SAVE_HOTKEY = 'Mod+Enter' satisfies Hotkey
+const SAVE_HOTKEY = 'Mod+Enter' satisfies HotkeyChord
const i18nPrefix = 'nodes.humanInput.insertInputField'
diff --git a/web/app/components/base/prompt-editor/plugins/shortcuts-popup-plugin/__tests__/index.spec.tsx b/web/app/components/base/prompt-editor/plugins/shortcuts-popup-plugin/__tests__/index.spec.tsx
index 80986ebcbb8..81be248e1dd 100644
--- a/web/app/components/base/prompt-editor/plugins/shortcuts-popup-plugin/__tests__/index.spec.tsx
+++ b/web/app/components/base/prompt-editor/plugins/shortcuts-popup-plugin/__tests__/index.spec.tsx
@@ -1,4 +1,4 @@
-import type { Hotkey } from '@tanstack/react-hotkeys'
+import type { HotkeyChord } from '@tanstack/react-hotkeys'
import type { ShortcutPopupDisplayMode, ShortcutPopupInsertHandler } from '../index'
import { LexicalComposer } from '@lexical/react/LexicalComposer'
import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext'
@@ -79,7 +79,7 @@ const InsertTextPlugin = () => {
type MinimalEditorProps = {
withContainer?: boolean
- hotkey?: Hotkey
+ hotkey?: HotkeyChord
displayMode?: ShortcutPopupDisplayMode
children?:
| React.ReactNode
diff --git a/web/app/components/base/prompt-editor/plugins/shortcuts-popup-plugin/index.tsx b/web/app/components/base/prompt-editor/plugins/shortcuts-popup-plugin/index.tsx
index 1f3528a9350..aefe6f68f99 100644
--- a/web/app/components/base/prompt-editor/plugins/shortcuts-popup-plugin/index.tsx
+++ b/web/app/components/base/prompt-editor/plugins/shortcuts-popup-plugin/index.tsx
@@ -1,4 +1,4 @@
-import type { Hotkey } from '@tanstack/react-hotkeys'
+import type { HotkeyChord } from '@tanstack/react-hotkeys'
import type { LexicalCommand } from 'lexical'
import type { CSSProperties } from 'react'
import { autoUpdate, flip, offset, shift, size, useFloating } from '@floating-ui/react'
@@ -17,7 +17,7 @@ export type ShortcutPopupInsertHandler = <Payload>(
export type ShortcutPopupDisplayMode = 'selection' | 'workflow-panel-adjacent-center'
type ShortcutPopupPluginProps = {
- hotkey?: Hotkey
+ hotkey?: HotkeyChord
children?:
| React.ReactNode
| ((close: () => void, onInsert: ShortcutPopupInsertHandler) => React.ReactNode)
diff --git a/web/app/components/base/prompt-editor/prompt-editor-content.tsx b/web/app/components/base/prompt-editor/prompt-editor-content.tsx
index 9d824f4da7a..4b788dd0e74 100644
--- a/web/app/components/base/prompt-editor/prompt-editor-content.tsx
+++ b/web/app/components/base/prompt-editor/prompt-editor-content.tsx
@@ -1,4 +1,4 @@
-import type { Hotkey } from '@tanstack/react-hotkeys'
+import type { HotkeyChord } from '@tanstack/react-hotkeys'
import type { EditorState } from 'lexical'
import type { FC } from 'react'
import type {
@@ -52,7 +52,7 @@ import {
} from './plugins/workflow-variable-block'
type ShortcutPopup = {
- hotkey: Hotkey
+ hotkey: HotkeyChord
displayMode?: ShortcutPopupDisplayMode
Popup: React.ComponentType<{ onClose: () => void; onInsert: ShortcutPopupInsertHandler }>
}
@@ -93,7 +93,7 @@ type PromptEditorContentProps = PromptEditorContentAriaProps & {
}
const getShortcutPopupKey = (
- hotkey: Hotkey,
+ hotkey: HotkeyChord,
displayMode: ShortcutPopupDisplayMode | undefined,
Popup: React.ComponentType<{ onClose: () => void; onInsert: ShortcutPopupInsertHandler }>,
) => {
diff --git a/web/app/components/datasets/documents/detail/completed/common/action-buttons.tsx b/web/app/components/datasets/documents/detail/completed/common/action-buttons.tsx
index 4dcdc2a9618..3884d604387 100644
--- a/web/app/components/datasets/documents/detail/completed/common/action-buttons.tsx
+++ b/web/app/components/datasets/documents/detail/completed/common/action-buttons.tsx
@@ -1,4 +1,4 @@
-import type { Hotkey } from '@tanstack/react-hotkeys'
+import type { HotkeyChord } from '@tanstack/react-hotkeys'
import type { RefObject } from 'react'
import { Button } from '@langgenius/dify-ui/button'
import { Kbd, KbdGroup } from '@langgenius/dify-ui/kbd'
@@ -7,8 +7,8 @@ import { useTranslation } from 'react-i18next'
import { ChunkingMode } from '@/models/datasets'
import { useDocumentContext } from '../../context'
-const CANCEL_HOTKEY = 'Escape' satisfies Hotkey
-const SAVE_HOTKEY = 'Mod+S' satisfies Hotkey
+const CANCEL_HOTKEY = 'Escape' satisfies HotkeyChord
+const SAVE_HOTKEY = 'Mod+S' satisfies HotkeyChord
type ActionButtonsProps = {
target: RefObject<HTMLDivElement | null>
diff --git a/web/app/components/detail-sidebar/hotkeys.ts b/web/app/components/detail-sidebar/hotkeys.ts
index 45f19d1c289..eea5b3715a2 100644
--- a/web/app/components/detail-sidebar/hotkeys.ts
+++ b/web/app/components/detail-sidebar/hotkeys.ts
@@ -1,3 +1,3 @@
-import type { Hotkey } from '@tanstack/react-hotkeys'
+import type { HotkeyChord } from '@tanstack/react-hotkeys'
-export const DETAIL_SIDEBAR_TOGGLE_HOTKEY = 'Mod+B' satisfies Hotkey
+export const DETAIL_SIDEBAR_TOGGLE_HOTKEY = 'Mod+B' satisfies HotkeyChord
diff --git a/web/app/components/explore/create-app-modal/index.tsx b/web/app/components/explore/create-app-modal/index.tsx
index 4da00211fde..e5bc1e5e0db 100644
--- a/web/app/components/explore/create-app-modal/index.tsx
+++ b/web/app/components/explore/create-app-modal/index.tsx
@@ -4,7 +4,7 @@ import type {
AppDetailWithSite,
UpdateAppPayload,
} from '@dify/contracts/api/console/apps/types.gen'
-import type { Hotkey } from '@tanstack/react-hotkeys'
+import type { HotkeyChord } from '@tanstack/react-hotkeys'
import type { IconPickerInputValue, IconPickerValue } from '@/app/components/base/icon-picker'
import { Button } from '@langgenius/dify-ui/button'
import {
@@ -58,7 +58,7 @@ export type CreateAppModalProps = {
onHide: () => void
}
-const SUBMIT_APP_HOTKEY = 'Mod+Enter' satisfies Hotkey
+const SUBMIT_APP_HOTKEY = 'Mod+Enter' satisfies HotkeyChord
const CreateAppModal = ({
show = false,
diff --git a/web/app/components/goto-anything/__tests__/index.spec.tsx b/web/app/components/goto-anything/__tests__/index.spec.tsx
index 3e9c3271572..23ed656677f 100644
--- a/web/app/components/goto-anything/__tests__/index.spec.tsx
+++ b/web/app/components/goto-anything/__tests__/index.spec.tsx
@@ -4,7 +4,7 @@ import type { marketplaceClient } from '@/service/marketplace'
import { zAgentAppPartial } from '@dify/contracts/api/console/agent/zod.gen'
import { zAppPartial } from '@dify/contracts/api/console/apps/zod.gen'
import { zSkillResponse } from '@dify/contracts/api/console/workspaces/zod.gen'
-import { detectPlatform } from '@tanstack/react-hotkeys'
+import { detectPlatform, useHotkey } from '@tanstack/react-hotkeys'
import { act, fireEvent, render, screen, waitFor, within } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { ThemeProvider } from 'next-themes'
@@ -176,6 +176,37 @@ afterEach(() => {
})
describe('search shortcut ownership', () => {
+ it('suspends background commands while search is open and restores them after closing', async () => {
+ const save = vi.fn()
+ function BackgroundEditor() {
+ useHotkey('Mod+S', save)
+ return <button onClick={save}>Save document</button>
+ }
+ const { user } = setup()
+ render(<BackgroundEditor />)
+ const pressSave = (target: HTMLElement) =>
+ fireEvent.keyDown(target, { key: 's', ctrlKey: !isMac, metaKey: isMac })
+
+ pressSave(screen.getByRole('button', { name: 'Save document' }))
+ expect(save).toHaveBeenCalledTimes(1)
+ const input = await openSearch()
+ pressSave(input)
+ expect(save).toHaveBeenCalledTimes(1)
+ expect(triggerSearchShortcut(input)).toBe(false)
+ expect(
+ fireEvent.keyDown(input, { key: 'k', ctrlKey: !isMac, metaKey: isMac, repeat: true }),
+ ).toBe(false)
+ expect(input).toHaveFocus()
+ await user.keyboard('{Escape}')
+ await waitFor(() =>
+ expect(
+ screen.queryByRole('dialog', { name: 'app.gotoAnything.searchTitle' }),
+ ).not.toBeInTheDocument(),
+ )
+ pressSave(screen.getByRole('button', { name: 'Save document' }))
+ expect(save).toHaveBeenCalledTimes(2)
+ })
+
it('opens search, keeps the current query on a repeated shortcut, and clears it after closing', async () => {
const { user } = setup()
const input = await openSearch()
diff --git a/web/app/components/goto-anything/hotkeys.ts b/web/app/components/goto-anything/hotkeys.ts
index 98ef6f2dac3..1fa3be9490c 100644
--- a/web/app/components/goto-anything/hotkeys.ts
+++ b/web/app/components/goto-anything/hotkeys.ts
@@ -1,3 +1,3 @@
-import type { Hotkey } from '@tanstack/react-hotkeys'
+import type { HotkeyChord } from '@tanstack/react-hotkeys'
-export const GOTO_ANYTHING_HOTKEY = 'Mod+K' satisfies Hotkey
+export const GOTO_ANYTHING_HOTKEY = 'Mod+K' satisfies HotkeyChord
diff --git a/web/app/components/goto-anything/index.tsx b/web/app/components/goto-anything/index.tsx
index ca388ed0b73..c8b8f174a90 100644
--- a/web/app/components/goto-anything/index.tsx
+++ b/web/app/components/goto-anything/index.tsx
@@ -19,7 +19,7 @@ import {
ScrollAreaThumb,
ScrollAreaViewport,
} from '@langgenius/dify-ui/scroll-area'
-import { formatForDisplay, useHotkey } from '@tanstack/react-hotkeys'
+import { formatForDisplay, HotkeysProvider, useHotkey } from '@tanstack/react-hotkeys'
import { keepPreviousData, useQuery } from '@tanstack/react-query'
import { useDebouncedValue } from 'foxact/use-debounced-value'
import { useAtomValue } from 'jotai'
@@ -134,6 +134,12 @@ function groupSearchResults(results: SearchResult[]) {
}, {})
}
+function SearchDialogHotkeys() {
+ // Keep the browser from claiming Mod+K while the global opener is suspended.
+ useHotkey(GOTO_ANYTHING_HOTKEY, () => {})
+ return null
+}
+
export function GotoAnything() {
const { t } = useTranslation(['app', 'common', 'skill', 'modelProvider', 'agentRoster'])
const pathname = usePathname()
@@ -155,6 +161,7 @@ export function GotoAnything() {
const [activePlugin, setActivePlugin] = useState<Plugin>()
const inputRef = useRef<HTMLInputElement>(null)
const searchHintId = useId()
+ const hotkeyScopeId = useId()
const commandContext = useCommandContext(agentsAvailable, skillsAvailable, isWorkflowPage)
const actions = useMemo(
() =>
@@ -435,137 +442,140 @@ export function GotoAnything() {
className="w-160 data-open:transition-none"
backdropProps={{ className: 'bg-background-overlay-alt data-open:transition-none' }}
>
- <div
- aria-hidden
- className="pointer-events-none absolute inset-x-0 top-0 h-64 bg-[url('/marketplace/hero-gradient-noise.svg')] bg-cover bg-center opacity-18 dark:opacity-28"
- />
- <div
- aria-hidden
- className="pointer-events-none absolute inset-x-0 top-0 h-64 bg-linear-to-b from-components-panel-bg/20 via-components-panel-bg/70 to-components-panel-bg"
- />
- <DialogTitle className="sr-only">
- {t(($) => $['gotoAnything.searchTitle'], { ns: 'app' })}
- </DialogTitle>
- <Autocomplete<GotoAnythingOption>
- items={visibleOptions}
- value={searchQuery}
- onValueChange={handleAutocompleteValueChange}
- itemToStringValue={optionToInputValue}
- filter={null}
- grid={isCommandsMode}
- open
- inline
- autoHighlight="always"
- keepHighlight
- loopFocus
- >
- <AutocompleteInputGroup
- size="medium"
- className="h-auto shrink-0 gap-3 rounded-none border-0 bg-components-panel-bg-blur px-4 py-3 has-[input:focus]:ring-0"
+ <HotkeysProvider scope={hotkeyScopeId} exclusive>
+ <SearchDialogHotkeys />
+ <div
+ aria-hidden
+ className="pointer-events-none absolute inset-x-0 top-0 h-64 bg-[url('/marketplace/hero-gradient-noise.svg')] bg-cover bg-center opacity-18 dark:opacity-28"
+ />
+ <div
+ aria-hidden
+ className="pointer-events-none absolute inset-x-0 top-0 h-64 bg-linear-to-b from-components-panel-bg/20 via-components-panel-bg/70 to-components-panel-bg"
+ />
+ <DialogTitle className="sr-only">
+ {t(($) => $['gotoAnything.searchTitle'], { ns: 'app' })}
+ </DialogTitle>
+ <Autocomplete<GotoAnythingOption>
+ items={visibleOptions}
+ value={searchQuery}
+ onValueChange={handleAutocompleteValueChange}
+ itemToStringValue={optionToInputValue}
+ filter={null}
+ grid={isCommandsMode}
+ open
+ inline
+ autoHighlight="always"
+ keepHighlight
+ loopFocus
>
- <span aria-hidden className="i-ri-search-line size-4 text-text-quaternary" />
- <div className="flex min-w-0 flex-1 items-center gap-2">
- <AutocompleteInput
- ref={inputRef}
- size="medium"
- aria-label={t(($) => $['gotoAnything.searchTitle'], { ns: 'app' })}
- placeholder={t(($) => $['gotoAnything.searchPlaceholder'], { ns: 'app' })}
- aria-describedby={searchHintId}
- className="px-0"
- />
- </div>
- <KbdGroup className="hidden sm:flex">
- {formatForDisplay(GOTO_ANYTHING_HOTKEY, { parts: true }).map((key) => (
- <Kbd key={key}>{key}</Kbd>
- ))}
- </KbdGroup>
- </AutocompleteInputGroup>
- <p id={searchHintId} className="sr-only">
- {t(($) => $['gotoAnything.searchHint'], { ns: 'app' })}
- </p>
-
- <AutocompleteStatus className="sr-only">{autocompleteStatus}</AutocompleteStatus>
-
- <ScrollArea className="h-120 min-h-0 shrink overflow-hidden border-t border-divider-subtle">
- <ScrollAreaViewport
- tabIndex={-1}
- aria-busy={isLoading || undefined}
- className="scroll-pt-10 scroll-pb-1 overscroll-contain"
+ <AutocompleteInputGroup
+ size="medium"
+ className="h-auto shrink-0 gap-3 rounded-none border-0 bg-components-panel-bg-blur px-4 py-3 has-[input:focus]:ring-0"
>
- <ScrollAreaContent
- className="min-h-full w-full max-w-full"
- style={{ minWidth: '100%' }}
+ <span aria-hidden className="i-ri-search-line size-4 text-text-quaternary" />
+ <div className="flex min-w-0 flex-1 items-center gap-2">
+ <AutocompleteInput
+ ref={inputRef}
+ size="medium"
+ aria-label={t(($) => $['gotoAnything.searchTitle'], { ns: 'app' })}
+ placeholder={t(($) => $['gotoAnything.searchPlaceholder'], { ns: 'app' })}
+ aria-describedby={searchHintId}
+ className="px-0"
+ />
+ </div>
+ <KbdGroup className="hidden sm:flex">
+ {formatForDisplay(GOTO_ANYTHING_HOTKEY, { parts: true }).map((key) => (
+ <Kbd key={key}>{key}</Kbd>
+ ))}
+ </KbdGroup>
+ </AutocompleteInputGroup>
+ <p id={searchHintId} className="sr-only">
+ {t(($) => $['gotoAnything.searchHint'], { ns: 'app' })}
+ </p>
+
+ <AutocompleteStatus className="sr-only">{autocompleteStatus}</AutocompleteStatus>
+
+ <ScrollArea className="h-120 min-h-0 shrink overflow-hidden border-t border-divider-subtle">
+ <ScrollAreaViewport
+ tabIndex={-1}
+ aria-busy={isLoading || undefined}
+ className="scroll-pt-10 scroll-pb-1 overscroll-contain"
>
- {emptyStateVariant === 'loading' && <EmptyState variant="loading" />}
-
- {emptyStateVariant === 'error' && <EmptyState variant="error" error={error} />}
-
- {emptyStateVariant === 'no-results' && isCommandsMode && (
- <div className="flex items-center justify-center py-8 text-center text-text-tertiary">
- <div>
- <div className="text-sm font-medium text-text-tertiary">
- {t(($) => $['gotoAnything.noMatchingCommands'], { ns: 'app' })}
- </div>
- <div className="mt-1 text-xs text-text-quaternary">
- {t(($) => $['gotoAnything.tryDifferentSearch'], { ns: 'app' })}
+ <ScrollAreaContent
+ className="min-h-full w-full max-w-full"
+ style={{ minWidth: '100%' }}
+ >
+ {emptyStateVariant === 'loading' && <EmptyState variant="loading" />}
+
+ {emptyStateVariant === 'error' && <EmptyState variant="error" error={error} />}
+
+ {emptyStateVariant === 'no-results' && isCommandsMode && (
+ <div className="flex items-center justify-center py-8 text-center text-text-tertiary">
+ <div>
+ <div className="text-sm font-medium text-text-tertiary">
+ {t(($) => $['gotoAnything.noMatchingCommands'], { ns: 'app' })}
+ </div>
+ <div className="mt-1 text-xs text-text-quaternary">
+ {t(($) => $['gotoAnything.tryDifferentSearch'], { ns: 'app' })}
+ </div>
</div>
</div>
- </div>
- )}
-
- {emptyStateVariant === 'no-results' && !isCommandsMode && (
- <EmptyState
- variant={emptyStateVariant}
- searchMode={searchMode}
- actions={actions}
- />
- )}
-
- {isCommandsMode ? (
- <CommandGrid
- groups={optionGroups}
- label={
- isHome
- ? t(($) => $['gotoAnything.searchTitle'], { ns: 'app' })
- : optionGroups[0]!.label
- }
- onSelect={selectOption}
- />
- ) : (
- <ResultList
- groups={[
- {
- id: 'commands',
- label: getGroupLabel('command'),
- items: optionSuggestions,
- },
- ...Object.entries(groupedResults).map(([type, items]) => ({
- id: type,
- label: getGroupLabel(type),
- items,
- })),
- ]}
- label={t(($) => $['gotoAnything.searchTitle'], { ns: 'app' })}
- onSelect={selectOption}
- />
- )}
- </ScrollAreaContent>
- </ScrollAreaViewport>
- <ScrollAreaScrollbar>
- <ScrollAreaThumb />
- </ScrollAreaScrollbar>
- </ScrollArea>
-
- <Footer
- onSelectMode={changeSearchQuery}
- resultCount={trimmedSearchQuery ? autocompleteResultCount : null}
- isLoading={isLoading}
- hasPartialFailure={hasUnavailableServices && !isError}
- />
- </Autocomplete>
- <DialogClose tabIndex={-1} className="sr-only">
- {t(($) => $['operation.close'], { ns: 'common' })}
- </DialogClose>
+ )}
+
+ {emptyStateVariant === 'no-results' && !isCommandsMode && (
+ <EmptyState
+ variant={emptyStateVariant}
+ searchMode={searchMode}
+ actions={actions}
+ />
+ )}
+
+ {isCommandsMode ? (
+ <CommandGrid
+ groups={optionGroups}
+ label={
+ isHome
+ ? t(($) => $['gotoAnything.searchTitle'], { ns: 'app' })
+ : optionGroups[0]!.label
+ }
+ onSelect={selectOption}
+ />
+ ) : (
+ <ResultList
+ groups={[
+ {
+ id: 'commands',
+ label: getGroupLabel('command'),
+ items: optionSuggestions,
+ },
+ ...Object.entries(groupedResults).map(([type, items]) => ({
+ id: type,
+ label: getGroupLabel(type),
+ items,
+ })),
+ ]}
+ label={t(($) => $['gotoAnything.searchTitle'], { ns: 'app' })}
+ onSelect={selectOption}
+ />
+ )}
+ </ScrollAreaContent>
+ </ScrollAreaViewport>
+ <ScrollAreaScrollbar>
+ <ScrollAreaThumb />
+ </ScrollAreaScrollbar>
+ </ScrollArea>
+
+ <Footer
+ onSelectMode={changeSearchQuery}
+ resultCount={trimmedSearchQuery ? autocompleteResultCount : null}
+ isLoading={isLoading}
+ hasPartialFailure={hasUnavailableServices && !isError}
+ />
+ </Autocomplete>
+ <DialogClose tabIndex={-1} className="sr-only">
+ {t(($) => $['operation.close'], { ns: 'common' })}
+ </DialogClose>
+ </HotkeysProvider>
</DialogContent>
</Dialog>
diff --git a/web/app/components/plugins/marketplace/home/home-search.tsx b/web/app/components/plugins/marketplace/home/home-search.tsx
index 76727505423..9ca6ccd2f7d 100644
--- a/web/app/components/plugins/marketplace/home/home-search.tsx
+++ b/web/app/components/plugins/marketplace/home/home-search.tsx
@@ -1,6 +1,6 @@
'use client'
-import type { Hotkey } from '@tanstack/react-hotkeys'
+import type { HotkeyChord } from '@tanstack/react-hotkeys'
import type { ReactNode } from 'react'
import { cn } from '@langgenius/dify-ui/cn'
import { useHotkey } from '@tanstack/react-hotkeys'
@@ -10,7 +10,7 @@ import EmbeddedMarketplaceSearch from './embedded-marketplace-search'
import styles from './home-sticky.module.css'
import { preserveStickySearchScroll } from './preserve-sticky-search-scroll'
-const SEARCH_HOTKEY = 'Mod+K' satisfies Hotkey
+const SEARCH_HOTKEY = 'Mod+K' satisfies HotkeyChord
type HomeSearchProps = {
children?: ReactNode
diff --git a/web/app/components/rag-pipeline/components/rag-pipeline-header/hotkeys.ts b/web/app/components/rag-pipeline/components/rag-pipeline-header/hotkeys.ts
index 5be8e60bba2..236726a0905 100644
--- a/web/app/components/rag-pipeline/components/rag-pipeline-header/hotkeys.ts
+++ b/web/app/components/rag-pipeline/components/rag-pipeline-header/hotkeys.ts
@@ -1,4 +1,4 @@
-import type { Hotkey } from '@tanstack/react-hotkeys'
+import type { HotkeyChord } from '@tanstack/react-hotkeys'
-export const RAG_PIPELINE_RUN_HOTKEY = 'Alt+R' satisfies Hotkey
-export const RAG_PIPELINE_PUBLISH_HOTKEY = 'Mod+Shift+P' satisfies Hotkey
+export const RAG_PIPELINE_RUN_HOTKEY = 'Alt+R' satisfies HotkeyChord
+export const RAG_PIPELINE_PUBLISH_HOTKEY = 'Mod+Shift+P' satisfies HotkeyChord
diff --git a/web/app/components/snippets/create-snippet-dialog.tsx b/web/app/components/snippets/create-snippet-dialog.tsx
index a5650b86691..77d3c45b760 100644
--- a/web/app/components/snippets/create-snippet-dialog.tsx
+++ b/web/app/components/snippets/create-snippet-dialog.tsx
@@ -1,5 +1,5 @@
'use client'
-import type { Hotkey } from '@tanstack/react-hotkeys'
+import type { HotkeyChord } from '@tanstack/react-hotkeys'
import type { InputVar } from '@/models/pipeline'
import type { SnippetCanvasData } from '@/models/snippet'
import { Button } from '@langgenius/dify-ui/button'
@@ -18,7 +18,7 @@ import { matchesKeyboardEvent } from '@tanstack/react-hotkeys'
import { useId, useRef, useState } from 'react'
import { useTranslation } from 'react-i18next'
-const CREATE_SNIPPET_HOTKEY = 'Mod+Enter' satisfies Hotkey
+const CREATE_SNIPPET_HOTKEY = 'Mod+Enter' satisfies HotkeyChord
export type CreateSnippetDialogPayload = {
name: string
diff --git a/web/app/components/workflow/hotkeys.ts b/web/app/components/workflow/hotkeys.ts
index 86d954abe16..a49f21a7f26 100644
--- a/web/app/components/workflow/hotkeys.ts
+++ b/web/app/components/workflow/hotkeys.ts
@@ -1,4 +1,4 @@
-import type { Hotkey } from '@tanstack/react-hotkeys'
+import type { HotkeyChord } from '@tanstack/react-hotkeys'
-export const TEST_RUN_MENU_HOTKEY = 'Alt+R' satisfies Hotkey
-export const VERSION_HISTORY_HOTKEY = 'Mod+Shift+H' satisfies Hotkey
+export const TEST_RUN_MENU_HOTKEY = 'Alt+R' satisfies HotkeyChord
+export const VERSION_HISTORY_HOTKEY = 'Mod+Shift+H' satisfies HotkeyChord
diff --git a/web/app/components/workflow/nodes/agent-v2/components/agent-output-variables/edit-card.tsx b/web/app/components/workflow/nodes/agent-v2/components/agent-output-variables/edit-card.tsx
index e10cd152109..b4fac214319 100644
--- a/web/app/components/workflow/nodes/agent-v2/components/agent-output-variables/edit-card.tsx
+++ b/web/app/components/workflow/nodes/agent-v2/components/agent-output-variables/edit-card.tsx
@@ -1,5 +1,5 @@
import type { DeclaredOutputConfig } from '@dify/contracts/api/console/apps/types.gen'
-import type { Hotkey } from '@tanstack/react-hotkeys'
+import type { HotkeyChord } from '@tanstack/react-hotkeys'
import type { EditableOutputConfig, EditingState, OutputDraft } from './utils'
import { Button } from '@langgenius/dify-ui/button'
import { Collapsible, CollapsiblePanel, CollapsibleTrigger } from '@langgenius/dify-ui/collapsible'
@@ -20,8 +20,8 @@ import {
OUTPUT_NAME_PATTERN_SOURCE,
} from './utils'
-const CANCEL_HOTKEY = 'Escape' satisfies Hotkey
-const CONFIRM_HOTKEY = 'Mod+Enter' satisfies Hotkey
+const CANCEL_HOTKEY = 'Escape' satisfies HotkeyChord
+const CONFIRM_HOTKEY = 'Mod+Enter' satisfies HotkeyChord
function ConfirmHotkeyHint() {
const displayKeys = formatForDisplay(CONFIRM_HOTKEY, { parts: true })
diff --git a/web/app/components/workflow/nodes/llm/components/json-schema-config-modal/visual-editor/edit-card/advanced-actions.tsx b/web/app/components/workflow/nodes/llm/components/json-schema-config-modal/visual-editor/edit-card/advanced-actions.tsx
index 2f945ff7127..bf557cbd6ab 100644
--- a/web/app/components/workflow/nodes/llm/components/json-schema-config-modal/visual-editor/edit-card/advanced-actions.tsx
+++ b/web/app/components/workflow/nodes/llm/components/json-schema-config-modal/visual-editor/edit-card/advanced-actions.tsx
@@ -1,11 +1,11 @@
-import type { Hotkey } from '@tanstack/react-hotkeys'
+import type { HotkeyChord } from '@tanstack/react-hotkeys'
import type { RefObject } from 'react'
import { Button } from '@langgenius/dify-ui/button'
import { useHotkey } from '@tanstack/react-hotkeys'
import { useTranslation } from 'react-i18next'
import { ShortcutKbd } from '@/app/components/workflow/shortcuts/shortcut-kbd'
-const JSON_SCHEMA_CONFIRM_HOTKEY = 'Mod+Enter' satisfies Hotkey
+const JSON_SCHEMA_CONFIRM_HOTKEY = 'Mod+Enter' satisfies HotkeyChord
type AdvancedActionsProps = {
target: RefObject<HTMLDivElement | null>
diff --git a/web/app/components/workflow/shortcuts/definitions.ts b/web/app/components/workflow/shortcuts/definitions.ts
index 8e01e0bfaff..fb7d782612a 100644
--- a/web/app/components/workflow/shortcuts/definitions.ts
+++ b/web/app/components/workflow/shortcuts/definitions.ts
@@ -1,8 +1,7 @@
-import type { Hotkey, IndividualKey } from '@tanstack/react-hotkeys'
+import type { HotkeyChord, IndividualKey } from '@tanstack/react-hotkeys'
export type WorkflowCanvasHotkeyMeta = {
id: WorkflowCanvasShortcutId
- scope: 'workflow-canvas'
name: string
description: string
}
@@ -13,8 +12,8 @@ type WorkflowCanvasShortcutDefinitionBase = {
}
export type WorkflowCanvasHotkeyDefinition = WorkflowCanvasShortcutDefinitionBase & {
- hotkeys: readonly [Hotkey, ...Hotkey[]]
- displayHotkey?: Hotkey
+ hotkeys: readonly [HotkeyChord, ...HotkeyChord[]]
+ displayHotkey?: HotkeyChord
}
type WorkflowCanvasHoldKeyDefinition = WorkflowCanvasShortcutDefinitionBase & {
@@ -130,7 +129,7 @@ export type WorkflowCanvasHotkeyId = {
export const getWorkflowCanvasShortcutDisplayKey = (
id: WorkflowCanvasShortcutId,
-): Hotkey | IndividualKey => {
+): HotkeyChord | IndividualKey => {
const shortcut = WORKFLOW_CANVAS_SHORTCUTS[id]
if ('displayHotkey' in shortcut && shortcut.displayHotkey) return shortcut.displayHotkey
diff --git a/web/app/components/workflow/shortcuts/shortcut-kbd.tsx b/web/app/components/workflow/shortcuts/shortcut-kbd.tsx
index 59a68f04cbd..b8215f77f41 100644
--- a/web/app/components/workflow/shortcuts/shortcut-kbd.tsx
+++ b/web/app/components/workflow/shortcuts/shortcut-kbd.tsx
@@ -1,5 +1,5 @@
import type { KbdColor } from '@langgenius/dify-ui/kbd'
-import type { FormatDisplayOptions, Hotkey } from '@tanstack/react-hotkeys'
+import type { FormatDisplayOptions, HotkeyChord } from '@tanstack/react-hotkeys'
import type { WorkflowCanvasShortcutId } from './definitions'
import { cn } from '@langgenius/dify-ui/cn'
import { Kbd, KbdGroup } from '@langgenius/dify-ui/kbd'
@@ -8,7 +8,7 @@ import { getWorkflowCanvasShortcutDisplayKey } from './definitions'
type ShortcutKbdSource =
| { shortcut: WorkflowCanvasShortcutId; hotkey?: never; displayKey?: never }
- | { shortcut?: never; hotkey: Hotkey; displayKey?: never }
+ | { shortcut?: never; hotkey: HotkeyChord; displayKey?: never }
| { shortcut?: never; hotkey?: never; displayKey: string }
type ShortcutKbdProps = ShortcutKbdSource & {
diff --git a/web/app/components/workflow/shortcuts/use-workflow-hotkeys.ts b/web/app/components/workflow/shortcuts/use-workflow-hotkeys.ts
index 33fc9128de8..f8ab9e00b05 100644
--- a/web/app/components/workflow/shortcuts/use-workflow-hotkeys.ts
+++ b/web/app/components/workflow/shortcuts/use-workflow-hotkeys.ts
@@ -58,7 +58,6 @@ const toHotkeyDefinitions = (
...registrationOptions,
meta: {
id,
- scope: 'workflow-canvas',
name: shortcut.name,
description: shortcut.description,
} satisfies WorkflowCanvasHotkeyMeta,
diff --git a/web/app/components/workflow/workflow-generator/index.tsx b/web/app/components/workflow/workflow-generator/index.tsx
index 8547eadec69..7f2ace3ac9c 100644
--- a/web/app/components/workflow/workflow-generator/index.tsx
+++ b/web/app/components/workflow/workflow-generator/index.tsx
@@ -5,7 +5,7 @@ import type {
WorkflowGeneratePayload,
WorkflowGeneratePlanEventResponse,
} from '@dify/contracts/api/console/workflow-generate/types.gen'
-import type { Hotkey } from '@tanstack/react-hotkeys'
+import type { HotkeyChord } from '@tanstack/react-hotkeys'
import type { SelectorParam, TFunction } from 'i18next'
import type { GeneratedGraph } from './types'
import type { FormValue } from '@/app/components/header/account-setting/model-provider-page/declarations'
@@ -62,7 +62,7 @@ import useGenGraph from './use-gen-graph'
// Mirrors the backend's instruction/ideal-output cap on /workflow-generate —
// keeping the limit client-side turns an opaque 400 into a visible input stop.
const MAX_INSTRUCTION_LENGTH = 10_000
-const WORKFLOW_GENERATOR_SUBMIT_HOTKEY = 'Mod+Enter' satisfies Hotkey
+const WORKFLOW_GENERATOR_SUBMIT_HOTKEY = 'Mod+Enter' satisfies HotkeyChord
// A single structured generation error. Mirrors the backend ``errors[]`` entry
// (stable ``code`` + human ``detail`` + optional ``node_id``) so the error panel
diff --git a/web/docs/hotkeys.md b/web/docs/hotkeys.md
index b918541825f..d7997eceeea 100644
--- a/web/docs/hotkeys.md
+++ b/web/docs/hotkeys.md
@@ -1,135 +1,124 @@
# Keyboard Commands
-Keep each command's binding, action, availability, and registration with the feature that owns
-it. Use TanStack Hotkeys for application commands; keep text editing, widget navigation, and
-primitive dismissal with their existing controls.
+Use TanStack Hotkeys for application commands. Keep registration, business actions, and
+availability with the feature owner; keep text editing, widget navigation, and dismissal with
+their existing editor or Dify UI primitive. Do not add a generic shortcut wrapper.
-## Default pattern
+The official [React guide] owns library options and [defaults], including input filtering,
+keyboard layouts, composition matching, and repeats. This document adds Dify's integration
+contracts. Check the installed declarations when an API differs from the latest documentation.
-Inside mounted content, bind directly to the actual command owner's ref:
+## Registration and availability
-```tsx
-import type { Hotkey } from '@tanstack/react-hotkeys'
-import { useHotkey } from '@tanstack/react-hotkeys'
-import { useRef } from 'react'
-
-const PUBLISH_HOTKEY = 'Mod+Shift+P' satisfies Hotkey
+For commands belonging to mounted popup content, pass the actual owner's ref:
+```tsx
+const PUBLISH_HOTKEY = 'Mod+Shift+P' satisfies HotkeyChord
const popupRef = useRef<HTMLDivElement>(null)
+
useHotkey(PUBLISH_HOTKEY, publish, {
target: popupRef,
enabled: canPublish,
- ignoreInputs: true,
requireReset: true,
})
```
-Attach `popupRef` to the actual Popup. Call the same action as the button, with the same
-availability. The library matches modifiers, consumes accepted events before the callback,
-and keeps that callback current.
-
-- **Scope:** pass the owner's ref. Omit `target` for intentional page/application commands.
- `ignoreInputs` only controls input filtering; form commands usually allow input targets.
-- **Availability:** align `enabled` with permissions, loading, validation, and open state.
- Keep validation in the action too, since buttons and menus also invoke it.
-- **Repeat:** use `requireReset: true` for one-shot commands; allow repeats for continuous zoom.
-
-## Choose the registration boundary
-
-| Situation | Pattern |
-| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| The hook and target mount together | `useHotkey` with the actual owner ref. The ref may be local or passed from a parent. |
-| Form content mounts later than its transaction owner | The actual Form's `onKeyDown + matchesKeyboardEvent` is a direct option; a hook inside mounted content also works. |
-| Child React handlers must process the key first | Handle it during React bubbling, or at document bubble with an owner-ref containment check, as Workflow does. |
-
-Choose by lifetime and event order. Being inside a Popup alone does not determine the API.
-The target must exist when the hook's registration effect runs; changing `ref.current` does
-not re-render the hook owner. Keep normal targets in `useRef` and transactions with their
-business owner. Element state is useful when an external subscription reports target
-replacement, such as Lexical's root listener; guard a nullable element with `enabled`, since
-a bare null target falls back to document.
-
-For a real form, call `event.currentTarget.requestSubmit()` to share submission and validation.
-React Portal events follow React ancestry: a local handler should check DOM containment when
-nested portals must stay outside its command. A feature may intentionally include its own
-portalled menus, as the Skills file tree does.
-
-## Bindings and hints
-
-| Need | API and type |
-| ------------------------------- | --------------------------------------------------------------------- |
-| One command / a command group | `useHotkey` / `useHotkeys`; retain feature command IDs. |
-| Binding definition | `satisfies Hotkey` for strings; `satisfies RawHotkey` for objects. |
-| Existing React keyboard handler | `matchesKeyboardEvent(event.nativeEvent, binding)`. |
-| Keycap hint | `formatForDisplay(binding, { parts: true })` with `Kbd` / `KbdGroup`. |
-| A held modifier | `useKeyHold`; combine key state with the interaction's actual scope. |
-
-Share bindings between registration and hints; keep single-owner constants local. Use
-`RegisterableHotkey` where both binding forms are accepted. `DisplayHotkey` is wider and belongs
-only to display. Validate dynamic bindings before parsing; narrow the `key`/`code` union when
-inspecting objects. Logical `Mod+S` follows the character; `Mod+[KeyS]` follows physical position.
-
-Preserve the initial platform through SSR hydration, as navigation search does.
-`aria-keyshortcuts` uses `Meta+K` or `Control+K`, not keycap glyphs or `Mod`.
-
-## Conditional event handling
-
-Use library defaults unless ownership or event priority requires a decision before consumption.
-An element's native listener can precede child React handlers, and the manager does not skip
-`defaultPrevented`. For these conditional owners, set `preventDefault: false` and
-`stopPropagation: false`, check scope and `defaultPrevented`, then consume the accepted event.
-For one-shot actions in this mode, consume repeats before returning on `event.repeat`; leave
-`requireReset` unset so its latch cannot bypass that consumption.
-
-The library filters composing printable shortcuts such as `Mod+S`. Custom submission and
-logical Enter/Escape still need IME protection; retain existing composition-end handling.
-`stopPropagation()` stops ancestors, not another callback on the same manager target.
-Keep eligible owners unambiguous; `conflictBehavior: 'replace'` is not a restoring modal stack,
-and provider defaults or metadata do not establish scope.
-
-Let Dialog, Popover, and Menu primitives own dismissal. A container handling bubbled child
-events keeps its actual semantics; an explained lint exception is preferable to inventing a
-button role or tab stop. Custom nonmodal panels should describe their real modality.
-
-## Workflow ownership
-
-| Layer | Responsibility |
-| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| Canvas | `WorkflowCanvas` supplies the ReactFlow root ref. `useWorkflowHotkeys` runs after child React handlers and accepts events within that subtree. |
-| Graph actions | Existing graph hooks own permissions, mutations, history, and persistence; keyboard commands invoke them. |
-| Editors and node navigation | ReactFlow, local node handlers, Lexical, CodeMirror, and forms own navigation, undo, suggestions, and submission. |
-| Portalled menus | Each menu matches its displayed commands and acts on its actual node, edge, or selection. |
-| Run and history | Header features own page commands with button-aligned availability; header focus is unnecessary. |
-| Comments | The focused draft/thread handles dismissal after suggestions. Active pointer-following placement owns Escape without taking focus. |
-
-The outer Workflow container includes unrelated panels. Use the canvas root for graph scope,
-restore canvas focus when deleting its focused object or applying graph undo/redo, and use
-Popup `finalFocus` when a menu action deletes its return target. Keep text undo with editors.
-Hold-to-dim combines key state with canvas focus and clears on focus loss.
-
-## Verification and maintenance
-
-Follow [the Web testing policy]. Use the real matcher/manager to verify scope, availability,
-mount/reopen behavior, child event priority, IME flags, and repeat where affected. Verify
-native editing, focus, and selection in a browser; check both platform modifiers for binding
-or hint changes. State the limits of simulated IME and SDK mocks.
-
-Follow these patterns for new commands. Recorders, remapping, and extra wrappers need a
-concrete product requirement.
-
-## References
-
-- [TanStack Hotkeys options]
-- [TanStack formatting]
-- [React Portal events]
-- [Delegated event handlers]
-- [Modal dialog requirements]
-- [Character shortcuts and focus]
-
-[Character shortcuts and focus]: https://www.w3.org/WAI/WCAG22/Understanding/character-key-shortcuts.html
-[Delegated event handlers]: https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/main/docs/rules/no-static-element-interactions.md
-[Modal dialog requirements]: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal
-[React Portal events]: https://react.dev/reference/react-dom/createPortal
-[TanStack Hotkeys options]: https://tanstack.com/hotkeys/latest/docs/framework/react/guides/hotkeys
-[TanStack formatting]: https://tanstack.com/hotkeys/latest/docs/framework/react/guides/formatting-display
-[the Web testing policy]: test.md
+Attach the ref to the Popup. Import the hook and type from `@tanstack/react-hotkeys` and
+`useRef` from React. Call the button's action, including its validation and permission checks.
+
+- Use `enabled` when an unavailable command should release the key entirely. A disabled
+ registration does not consume the event. If the browser action must remain suppressed,
+ keep the registration enabled and guard the business action inside its callback instead.
+- Use default input filtering unless the feature requires otherwise. Form submission may need
+ `ignoreInputs: false`; canvas commands use `true` to preserve editing. See [defaults].
+- Use `requireReset: true` for one-shot commands with default consumption; allow continuous
+ actions such as zoom to repeat. Conditional event owners follow the rules below.
+- Pass a ref, not `ref.current`. An empty ref skips registration; a bare null target falls back
+ to document. Ref mutation does not re-render the owner: put the hook in mounted content or
+ use the actual Form's `onKeyDown` when it mounts later. Lexical root replacement can use its
+ root subscription with element state; disable registration while that element is null.
+- For form commands, call `event.currentTarget.requestSubmit()` to share native submission and
+ validation. React events from nested portals follow React ancestry; check DOM containment
+ when those portals must be excluded. The Skills file tree intentionally includes its menus.
+
+## Bindings and display
+
+| Boundary | Contract |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| One command / a group | `useHotkey` / `useHotkeys`; preserve feature command IDs. |
+| Chord-only strings / objects | `HotkeyChord` / `RawHotkeyChord`; use `satisfies` for constants. |
+| Both chord forms | `RegisterableHotkeyChord`; `Hotkey` / `RegisterableHotkey` also admit sequences. |
+| Existing React handler | `matchesKeyboardEvent(event.nativeEvent, chord)` matches one chord only. |
+| Keycaps | Share the binding with registration; use `formatForDisplay(..., { parts: true })` and Dify UI `Kbd` / `KbdGroup`. |
+
+Use `DisplayHotkeyChord` for chord-only display boundaries. Sequence formatting returns groups
+of keycaps; do not widen a chord renderer without implementing that UI. Follow [formatting] for
+logical/physical keys, validation, and labels. Preserve the initial platform through hydration,
+as navigation search does. `aria-keyshortcuts` uses `Meta+K` or `Control+K`, not glyphs or `Mod`.
+
+Local constants are the default. Use native [app hotkeys] when a product needs app-wide discovery
+or remapping: declarations contain no callbacks; business callbacks stay with their feature.
+Recording, sequences, and modifier hints are optional capabilities, not migration requirements.
+
+## Event ownership and scopes
+
+A DOM target limits event origin; a [scope] controls whether TanStack registrations are active.
+Neither replaces editor handling or Dify UI dismissal. Use a scoped provider above its hook
+consumers, with a unique name for independently mounted surfaces. Same-scope matches may all
+run; `conflictBehavior: 'replace'` is not a restoring stack, and metadata is not activation.
+
+Use `exclusive` when a modal feature must suspend background application commands. Activate it
+with the interactive content, not a permanently mounted Root. Content may retain exclusivity
+through its closing transition; hidden retained content needs explicit `enabled` handling.
+Preserve commands needed inside the modal: GotoAnything consumes repeated `Mod+K` inside its
+scope while the global opener is suspended. Scope precedence and exceptions belong to [scope].
+
+Use normal library consumption unless the owner must decide whether to claim an event:
+
+- An element's native listener can precede child React handlers. When children must go first,
+ handle React bubbling, or use document bubble plus owner containment as Workflow does.
+ `capture: true` is for an intentional requirement to precede descendants, not a general fix.
+- The manager does not skip `defaultPrevented`. Conditional owners set `preventDefault: false`
+ and `stopPropagation: false`, check scope and `defaultPrevented`, then consume accepted events.
+ Consume repeats before returning on `event.repeat`; leave `requireReset` unset in this mode
+ so its callback latch cannot bypass that consumption. `stopPropagation()` does not stop
+ another callback on the same manager target.
+- Keep IME protection for custom submission and logical Enter/Escape, including existing
+ composition-end handling. Library composition filtering does not cover those named keys.
+- A container delegating child events retains its real semantics. Explain a necessary lint
+ exception instead of adding a fake button role or tab stop.
+
+[Character shortcuts], including Shift plus a character, must be disableable, remappable to
+include a non-character key, or limited to focus within their owning component. Input filtering
+or an active page-wide scope alone is insufficient.
+
+## Workflow boundaries
+
+| Owner | Responsibility |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Canvas | `WorkflowCanvas` supplies the ReactFlow root ref. `useWorkflowHotkeys` runs after child React handlers and accepts only events within that subtree. |
+| Graph actions | Existing graph hooks own permissions, mutations, history, and persistence. Keyboard commands invoke them. |
+| Editors and nodes | ReactFlow, local handlers, Lexical, CodeMirror, and forms own navigation, undo, suggestions, and submission. |
+| Portalled menus | Match displayed commands and act on the actual node, edge, or selection. |
+| Run and history | Header features own page commands; header focus is unnecessary. |
+| Comments | Focused draft/thread dismissal runs after suggestions. Active pointer-following placement owns Escape without taking focus. |
+
+The outer Workflow container includes unrelated panels; use the canvas root for graph scope.
+Restore canvas focus after deleting its focused object or applying graph undo/redo. Use Popup
+`finalFocus` when a menu action deletes its return target. Hold-to-dim combines held-key state
+with canvas focus and clears on focus loss; held-key state alone does not establish ownership.
+
+## Verification
+
+Follow [Web testing]. Use the real matcher/manager to verify affected scope, availability,
+mount/reopen behavior, child priority, IME flags, and repeats. Check native editing, focus, and
+selection in a browser, and both platform modifiers for binding or hint changes. State the
+limits of simulated IME and mocked business actions.
+
+[Character shortcuts]: https://www.w3.org/WAI/WCAG22/Understanding/character-key-shortcuts.html
+[React guide]: https://tanstack.com/hotkeys/latest/docs/framework/react/guides/hotkeys
+[Web testing]: test.md
+[app hotkeys]: https://tanstack.com/hotkeys/latest/docs/framework/react/guides/app-hotkeys
+[defaults]: https://tanstack.com/hotkeys/latest/docs/guides/sensible-defaults
+[formatting]: https://tanstack.com/hotkeys/latest/docs/framework/react/guides/formatting-display
+[scope]: https://tanstack.com/hotkeys/latest/docs/framework/react/guides/hotkeys-provider-and-scopes
diff --git a/web/features/agent-v2/agent-detail/configure/components/orchestrate/publish-bar/index.tsx b/web/features/agent-v2/agent-detail/configure/components/orchestrate/publish-bar/index.tsx
index 772036ffa33..16cbc879be6 100644
--- a/web/features/agent-v2/agent-detail/configure/components/orchestrate/publish-bar/index.tsx
+++ b/web/features/agent-v2/agent-detail/configure/components/orchestrate/publish-bar/index.tsx
@@ -5,7 +5,7 @@ import type {
AgentReferencingWorkflowResponse,
AgentReferencingWorkflowsResponse,
} from '@dify/contracts/api/console/agent/types.gen'
-import type { Hotkey } from '@tanstack/react-hotkeys'
+import type { HotkeyChord } from '@tanstack/react-hotkeys'
import type { AgentConfigurePublishResult } from '../../../use-agent-configure-sync'
import { Button } from '@langgenius/dify-ui/button'
import { Collapsible, CollapsiblePanel } from '@langgenius/dify-ui/collapsible'
@@ -29,7 +29,7 @@ import { AgentVersionRestore } from '../../version-restore'
import { AgentPublishImpactDetails } from './publish-impact-details'
import { AgentPublishSuccess } from './publish-success'
-const PUBLISH_AGENT_HOTKEY = 'Mod+Shift+P' satisfies Hotkey
+const PUBLISH_AGENT_HOTKEY = 'Mod+Shift+P' satisfies HotkeyChord
type AgentConfigurePublishState = 'draft' | 'publishing' | 'published' | 'unpublished'
diff --git a/web/features/skills/detail/publish-bar.tsx b/web/features/skills/detail/publish-bar.tsx
index e4968b2c5bf..b438da46ce5 100644
--- a/web/features/skills/detail/publish-bar.tsx
+++ b/web/features/skills/detail/publish-bar.tsx
@@ -1,6 +1,6 @@
'use client'
-import type { Hotkey } from '@tanstack/react-hotkeys'
+import type { HotkeyChord } from '@tanstack/react-hotkeys'
import type { ReactNode } from 'react'
import { Button } from '@langgenius/dify-ui/button'
import { Kbd, KbdGroup } from '@langgenius/dify-ui/kbd'
@@ -8,7 +8,7 @@ import { StatusDot } from '@langgenius/dify-ui/status-dot'
import { formatForDisplay, useHotkey } from '@tanstack/react-hotkeys'
import { useTranslation } from 'react-i18next'
-const PUBLISH_SKILL_HOTKEY = 'Mod+Shift+P' satisfies Hotkey
+const PUBLISH_SKILL_HOTKEY = 'Mod+Shift+P' satisfies HotkeyChord
type SkillPublishState = 'draft' | 'publishing' | 'published' | 'unpublished'
diff --git a/web/features/skills/detail/shared.tsx b/web/features/skills/detail/shared.tsx
index cb07dec6e9d..9276402dc11 100644
--- a/web/features/skills/detail/shared.tsx
+++ b/web/features/skills/detail/shared.tsx
@@ -6,7 +6,7 @@ import type {
SkillResponse,
SkillVersionResponse,
} from '@dify/contracts/api/console/workspaces/types.gen'
-import type { Hotkey } from '@tanstack/react-hotkeys'
+import type { HotkeyChord } from '@tanstack/react-hotkeys'
import type { InfiniteData, useQueryClient } from '@tanstack/react-query'
import type {
DefaultModel,
@@ -82,12 +82,12 @@ export function runSkillFileMutation(
export const skillFileHotkeys = {
copy: {
- command: 'Mod+C' satisfies Hotkey,
+ command: 'Mod+C' satisfies HotkeyChord,
},
cut: {
- command: 'Mod+X' satisfies Hotkey,
+ command: 'Mod+X' satisfies HotkeyChord,
},
- paste: { command: 'Mod+V' satisfies Hotkey },
+ paste: { command: 'Mod+V' satisfies HotkeyChord },
} as const
export const skillFileMenuPopupClassName = 'w-[168px] data-ending-style:transition-none'