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.
Python agentagentic-aiagentic-frameworkagentic-workflowaiautomationclaudedeepseekgenaigptllmlow-codemcpnextjsno-codeopenaipythonskillsworkflow
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.mdindex 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 Surfacesdiff --git a/packages/dify-ui/src/kbd/index.stories.tsx b/packages/dify-ui/src/kbd/index.stories.tsxindex 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: DisplayHotkeyChordcolor?: 'gray' | 'white'platform?: FormatDisplayOptions['platform']}) {diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 1daae39b847..3f9d00b1710 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -330,8 +330,8 @@ catalogs:specifier: 1.33.5version: 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.4version: 5.104.4@@ -1129,7 +1129,7 @@ importers:version: 4.3.3(@voidzero-dev/[email protected](@types/[email protected])(@typescript/[email protected])(@volar/[email protected](@typescript/[email protected]))([email protected])([email protected])([email protected])([email protected]))'@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-domdependencies:- '@tanstack/hotkeys': 0.11.0+ '@tanstack/hotkeys': 0.17.0react: 19.3.1react-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.yamlindex 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.2diff --git a/web/app/components/app/app-publisher/hotkeys.ts b/web/app/components/app/app-publisher/hotkeys.tsindex 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 HotkeyChorddiff --git a/web/app/components/app/create-app-modal/index.tsx b/web/app/components/app/create-app-modal/index.tsxindex 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 HotkeyChordconst 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.tsxindex 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 HotkeyChordfunction 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.tsxindex 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?: booleandisableBracePicker?: booleanshortcutPopups?: Array<{- hotkey: Hotkey+ hotkey: HotkeyChorddisplayMode?: ShortcutPopupDisplayModePopup: 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.tsxindex 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 HotkeyChordconst 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.tsxindex 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?: HotkeyChorddisplayMode?: ShortcutPopupDisplayModechildren?:| React.ReactNodediff --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.tsxindex 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?: HotkeyChordchildren?:| 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.tsxindex 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: HotkeyChorddisplayMode?: ShortcutPopupDisplayModePopup: 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.tsxindex 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 HotkeyChordtype ActionButtonsProps = {target: RefObject<HTMLDivElement | null>diff --git a/web/app/components/detail-sidebar/hotkeys.ts b/web/app/components/detail-sidebar/hotkeys.tsindex 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 HotkeyChorddiff --git a/web/app/components/explore/create-app-modal/index.tsx b/web/app/components/explore/create-app-modal/index.tsxindex 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 HotkeyChordconst CreateAppModal = ({show = false,diff --git a/web/app/components/goto-anything/__tests__/index.spec.tsx b/web/app/components/goto-anything/__tests__/index.spec.tsxindex 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.tsindex 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 HotkeyChorddiff --git a/web/app/components/goto-anything/index.tsx b/web/app/components/goto-anything/index.tsxindex 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.tsxindex 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 HotkeyChordtype HomeSearchProps = {children?: ReactNodediff --git a/web/app/components/rag-pipeline/components/rag-pipeline-header/hotkeys.ts b/web/app/components/rag-pipeline/components/rag-pipeline-header/hotkeys.tsindex 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 HotkeyChorddiff --git a/web/app/components/snippets/create-snippet-dialog.tsx b/web/app/components/snippets/create-snippet-dialog.tsxindex 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 HotkeyChordexport type CreateSnippetDialogPayload = {name: stringdiff --git a/web/app/components/workflow/hotkeys.ts b/web/app/components/workflow/hotkeys.tsindex 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 HotkeyChorddiff --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.tsxindex 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 HotkeyChordfunction 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.tsxindex 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 HotkeyChordtype AdvancedActionsProps = {target: RefObject<HTMLDivElement | null>diff --git a/web/app/components/workflow/shortcuts/definitions.ts b/web/app/components/workflow/shortcuts/definitions.tsindex 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: stringdescription: 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.displayHotkeydiff --git a/web/app/components/workflow/shortcuts/shortcut-kbd.tsx b/web/app/components/workflow/shortcuts/shortcut-kbd.tsxindex 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.tsindex 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.tsxindex 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 paneldiff --git a/web/docs/hotkeys.md b/web/docs/hotkeys.mdindex 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 HotkeyChordconst 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-scopesdiff --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.tsxindex 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 HotkeyChordtype AgentConfigurePublishState = 'draft' | 'publishing' | 'published' | 'unpublished'diff --git a/web/features/skills/detail/publish-bar.tsx b/web/features/skills/detail/publish-bar.tsxindex 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 HotkeyChordtype SkillPublishState = 'draft' | 'publishing' | 'published' | 'unpublished'diff --git a/web/features/skills/detail/shared.tsx b/web/features/skills/detail/shared.tsxindex 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 constexport const skillFileMenuPopupClassName = 'w-[168px] data-ending-style:transition-none'