ref(cmdk): implement async actions (#112173)

Implements async actions inside our CMDK by allowing each action to
define a resource callback function that returns `queryOptions`.

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: getsantry[bot] <66042841+getsantry[bot]@users.noreply.github.com>

Author: 3 people

static/app/components/commandPalette/__stories__/components.tsx

@@ -2,30 +2,31 @@ import {useCallback} from 'react';
 
 import {addSuccessMessage} from 'sentry/actionCreators/indicator';
 import {CommandPaletteProvider} from 'sentry/components/commandPalette/context';
+import {useCommandPaletteActionsRegister} from 'sentry/components/commandPalette/context';
 import type {
   CommandPaletteAction,
-  CommandPaletteActionCallbackWithKey,
-  CommandPaletteActionLinkWithKey,
+  CommandPaletteActionWithKey,
 } from 'sentry/components/commandPalette/types';
 import {CommandPalette} from 'sentry/components/commandPalette/ui/commandPalette';
-import {useCommandPaletteActions} from 'sentry/components/commandPalette/useCommandPaletteActions';
 import {normalizeUrl} from 'sentry/utils/url/normalizeUrl';
 import {useNavigate} from 'sentry/utils/useNavigate';
 
 export function RegisterActions({actions}: {actions: CommandPaletteAction[]}) {
-  useCommandPaletteActions(actions);
+  useCommandPaletteActionsRegister(actions);
   return null;
 }
 
 export function CommandPaletteDemo() {
   const navigate = useNavigate();
 
   const handleAction = useCallback(
-    (action: CommandPaletteActionLinkWithKey | CommandPaletteActionCallbackWithKey) => {
+    (action: CommandPaletteActionWithKey) => {
       if ('to' in action) {
         navigate(normalizeUrl(action.to));
-      } else {
+      } else if ('onAction' in action) {
         action.onAction();
+      } else {
+        // @TODO: implement async actions
       }
     },
     [navigate]

static/app/components/commandPalette/context.tsx

@@ -1,15 +1,71 @@
-import {createContext, useCallback, useContext, useReducer} from 'react';
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useReducer,
+} from 'react';
+import {uuid4} from '@sentry/core';
 
+import {slugify} from 'sentry/utils/slugify';
 import {unreachable} from 'sentry/utils/unreachable';
 
 import {CommandPaletteStateProvider} from './ui/commandPaletteStateContext';
-import type {CommandPaletteActionWithKey} from './types';
+import type {CommandPaletteAction, CommandPaletteActionWithKey} from './types';
+
+function addKeysToActions(
+  actions: CommandPaletteAction[]
+): CommandPaletteActionWithKey[] {
+  return actions.map(action => {
+    const kind = 'actions' in action ? 'group' : 'to' in action ? 'navigate' : 'callback';
+    const actionKey = `${kind}:${slugify(action.display.label)}:${uuid4()}`;
+
+    if ('actions' in action) {
+      return {
+        ...action,
+        actions: addKeysToChildActions(actionKey, action.actions),
+        key: actionKey,
+      };
+    }
+
+    return {
+      ...action,
+      key: actionKey,
+    };
+  });
+}
+
+function addKeysToChildActions(
+  parentKey: string,
+  actions: CommandPaletteAction[]
+): CommandPaletteActionWithKey[] {
+  return actions.map(action => {
+    const actionKey = `${parentKey}::${'actions' in action ? 'group' : 'to' in action ? 'navigate' : 'callback'}:${slugify(action.display.label)}`;
+
+    if ('actions' in action) {
+      return {
+        ...action,
+        actions: addKeysToChildActions(actionKey, action.actions),
+        key: actionKey,
+      };
+    }
+
+    return {
+      ...action,
+      key: actionKey,
+    };
+  });
+}
 
 type CommandPaletteProviderProps = {children: React.ReactNode};
 type CommandPaletteActions = CommandPaletteActionWithKey[];
 
 type Unregister = () => void;
-type CommandPaletteRegistration = (actions: CommandPaletteActionWithKey[]) => Unregister;
+type CommandPaletteRegistration = {
+  dispatch: React.Dispatch<CommandPaletteActionReducerAction>;
+  registerActions: (actions: CommandPaletteAction[]) => Unregister;
+};
 
 type CommandPaletteActionReducerAction =
   | {
@@ -25,7 +81,7 @@ const CommandPaletteRegistrationContext =
   createContext<CommandPaletteRegistration | null>(null);
 const CommandPaletteActionsContext = createContext<CommandPaletteActions | null>(null);
 
-export function useCommandPaletteRegistration(): CommandPaletteRegistration {
+function useCommandPaletteRegistration(): CommandPaletteRegistration {
   const ctx = useContext(CommandPaletteRegistrationContext);
   if (ctx === null) {
     throw new Error(
@@ -65,6 +121,7 @@ function actionsReducer(
       return result;
     }
     case 'unregister':
+      // @TODO(Jonas): this needs to support deep unregistering of actions
       return state.filter(action => !reducerAction.keys.includes(action.key));
     default:
       unreachable(type);
@@ -76,20 +133,45 @@ export function CommandPaletteProvider({children}: CommandPaletteProviderProps)
   const [actions, dispatch] = useReducer(actionsReducer, []);
 
   const registerActions = useCallback(
-    (newActions: CommandPaletteActionWithKey[]) => {
-      dispatch({type: 'register', actions: newActions});
+    (newActions: CommandPaletteAction[]) => {
+      const actionsWithKeys = addKeysToActions(newActions);
+
+      dispatch({type: 'register', actions: actionsWithKeys});
       return () => {
-        dispatch({type: 'unregister', keys: newActions.map(a => a.key)});
+        dispatch({type: 'unregister', keys: actionsWithKeys.map(a => a.key)});
       };
     },
     [dispatch]
   );
 
+  const registerContext = useMemo(
+    () => ({registerActions, dispatch}),
+    [registerActions, dispatch]
+  );
   return (
-    <CommandPaletteRegistrationContext.Provider value={registerActions}>
+    <CommandPaletteRegistrationContext.Provider value={registerContext}>
       <CommandPaletteActionsContext.Provider value={actions}>
         <CommandPaletteStateProvider>{children}</CommandPaletteStateProvider>
       </CommandPaletteActionsContext.Provider>
     </CommandPaletteRegistrationContext.Provider>
   );
 }
+
+/**
+ * Use this hook inside your page or feature component to register contextual actions with the global command palette.
+ * Actions are registered on mount and automatically unregistered on unmount, so they only appear in the palette while
+ * your component is rendered. This is ideal for page‑specific shortcuts.
+ *
+ * There are a few different types of actions you can register:
+ *
+ * - **Navigation actions**: Provide a `to` destination to navigate to when selected.
+ * - **Callback actions**: Provide an `onAction` handler to execute when selected.
+ * - **Nested actions**: Provide an `actions: CommandPaletteAction[]` array on a parent item to show a second level. Selecting the parent reveals its children.
+ *
+ * See the CommandPaletteAction type for more details on configuration.
+ */
+export function useCommandPaletteActionsRegister(actions: CommandPaletteAction[]) {
+  const {registerActions} = useCommandPaletteRegistration();
+
+  useEffect(() => registerActions(actions), [actions, registerActions]);
+}

static/app/components/commandPalette/types.tsx

@@ -1,7 +1,9 @@
 import type {ReactNode} from 'react';
 import type {LocationDescriptor} from 'history';
 
-interface CommonCommandPaletteAction {
+import type {UseQueryOptions} from 'sentry/utils/queryClient';
+
+interface Action {
   display: {
     /** Primary text shown to the user */
     label: string;
@@ -14,46 +16,97 @@ interface CommonCommandPaletteAction {
   keywords?: string[];
 }
 
-export interface CommandPaletteActionLink extends CommonCommandPaletteAction {
+/**
+ * Actions that can be returned from an async resource query.
+ * Async results cannot themselves carry a `resource` — chained async lookups
+ * are not supported. Use CommandPaletteAction for registering top-level actions.
+ */
+interface CommandPaletteAsyncResultGroup extends Action {
+  actions: CommandPaletteAsyncResult[];
+}
+
+export type CommandPaletteAsyncResult =
+  | CommandPaletteActionLink
+  | CommandPaletteActionCallback
+  | CommandPaletteAsyncResultGroup;
+
+export type CMDKQueryOptions = UseQueryOptions<
+  any,
+  Error,
+  CommandPaletteAsyncResult[],
+  any
+>;
+
+export interface CommandPaletteActionLink extends Action {
   /** Navigate to a route when selected */
   to: LocationDescriptor;
 }
 
-export interface CommandPaletteActionCallback extends CommonCommandPaletteAction {
+interface CommandPaletteActionCallback extends Action {
   /**
    * Execute a callback when the action is selected.
    * Use the `to` prop if you want to navigate to a route.
    */
   onAction: () => void;
 }
 
+interface CommandPaletteAsyncAction extends Action {
+  /**
+   * Execute a callback when the action is selected.
+   * Use the `to` prop if you want to navigate to a route.
+   */
+  resource: (query: string) => CMDKQueryOptions;
+}
+
+interface CommandPaletteAsyncActionGroup extends Action {
+  actions: CommandPaletteAction[];
+  resource: (query: string) => CMDKQueryOptions;
+}
+
 export type CommandPaletteAction =
   | CommandPaletteActionLink
   | CommandPaletteActionCallback
-  | CommandPaletteActionGroup;
+  | CommandPaletteActionGroup
+  | CommandPaletteAsyncAction
+  | CommandPaletteAsyncActionGroup;
 
-export interface CommandPaletteActionGroup extends CommonCommandPaletteAction {
+interface CommandPaletteActionGroup extends Action {
   /** Nested actions to show when this action is selected */
-  actions: Array<
-    CommandPaletteActionLink | CommandPaletteActionCallback | CommandPaletteActionGroup
-  >;
+  actions: CommandPaletteAction[];
 }
 
 // Internally, a key is added to the actions in order to track them for registration and selection.
-export type CommandPaletteActionLinkWithKey = CommandPaletteActionLink & {key: string};
-export type CommandPaletteActionCallbackWithKey = CommandPaletteActionCallback & {
+type CommandPaletteActionLinkWithKey = CommandPaletteActionLink & {key: string};
+type CommandPaletteActionCallbackWithKey = CommandPaletteActionCallback & {
   key: string;
 };
+type CommandPaletteAsyncActionWithKey = CommandPaletteAsyncAction & {
+  key: string;
+};
+type CommandPaletteAsyncActionGroupWithKey = Omit<
+  CommandPaletteAsyncActionGroup,
+  'actions'
+> & {
+  actions: CommandPaletteActionWithKey[];
+  key: string;
+};
+
 export type CommandPaletteActionWithKey =
+  // Sync actions (to, callback, group)
   | CommandPaletteActionLinkWithKey
   | CommandPaletteActionCallbackWithKey
-  | CommandPaletteActionGroupWithKey;
+  | CommandPaletteActionGroupWithKey
+  // Async actions
+  | CommandPaletteAsyncActionWithKey
+  | CommandPaletteAsyncActionGroupWithKey;
 
-export interface CommandPaletteActionGroupWithKey extends CommandPaletteActionGroup {
+interface CommandPaletteActionGroupWithKey extends CommandPaletteActionGroup {
   actions: Array<
     | CommandPaletteActionLinkWithKey
     | CommandPaletteActionCallbackWithKey
     | CommandPaletteActionGroupWithKey
+    | CommandPaletteAsyncActionWithKey
+    | CommandPaletteAsyncActionGroupWithKey
   >;
   key: string;
 }

static/app/components/commandPalette/ui/commandPalette.spec.tsx

@@ -2,6 +2,8 @@ import {useCallback} from 'react';
 
 import {render, screen, userEvent, waitFor} from 'sentry-test/reactTestingLibrary';
 
+jest.unmock('lodash/debounce');
+
 jest.mock('@tanstack/react-virtual', () => ({
   useVirtualizer: ({count}: {count: number}) => {
     const virtualItems = Array.from({length: count}, (_, index) => ({
@@ -23,17 +25,16 @@ jest.mock('@tanstack/react-virtual', () => ({
 import {closeModal} from 'sentry/actionCreators/modal';
 import * as modalActions from 'sentry/actionCreators/modal';
 import {CommandPaletteProvider} from 'sentry/components/commandPalette/context';
+import {useCommandPaletteActionsRegister} from 'sentry/components/commandPalette/context';
 import type {
   CommandPaletteAction,
-  CommandPaletteActionCallbackWithKey,
-  CommandPaletteActionLinkWithKey,
+  CommandPaletteActionWithKey,
 } from 'sentry/components/commandPalette/types';
 import {CommandPalette} from 'sentry/components/commandPalette/ui/commandPalette';
-import {useCommandPaletteActions} from 'sentry/components/commandPalette/useCommandPaletteActions';
 import {useNavigate} from 'sentry/utils/useNavigate';
 
 function RegisterActions({actions}: {actions: CommandPaletteAction[]}) {
-  useCommandPaletteActions(actions);
+  useCommandPaletteActionsRegister(actions);
   return null;
 }
 
@@ -47,11 +48,13 @@ function GlobalActionsComponent({
   const navigate = useNavigate();
 
   const handleAction = useCallback(
-    (action: CommandPaletteActionLinkWithKey | CommandPaletteActionCallbackWithKey) => {
+    (action: CommandPaletteActionWithKey) => {
       if ('to' in action) {
         navigate(action.to);
-      } else {
+      } else if ('onAction' in action) {
         action.onAction();
+      } else {
+        // @TODO: implement async actions
       }
       closeModal();
     },