feat: add onKeyDown prop to ListBoxItem for custom keyboard handling (adobe#9181)

* Add `onKeyDown` prop to ListBoxItem for custom keyboard handling

* Update type annotation in ListBox example and fix style formatting in ListBox story

* fix: remove custom keyboard handling example from ListBox docs and story

* test: add unit tests for `onKeyDown` prop in ListBox component

* test: remove redundant assertions for `onKeyDown` in ListBox tests

* test: update `onKeyDown` tests in ListBox to use user-event for better simulation

* Add `onKeyDown` prop to ListBoxItem for custom keyboard handling

* Update type annotation in ListBox example and fix style formatting in ListBox story

* fix: remove custom keyboard handling example from ListBox docs and story

* test: add unit tests for `onKeyDown` prop in ListBox component

* test: remove redundant assertions for `onKeyDown` in ListBox tests

* test: update `onKeyDown` tests in ListBox to use user-event for better simulation

* chore: remove unnecessary blank lines in ListBox story

* chore: remove trailing blank line in ListBox story

* Add tests and move to useKeyboard

---------

Co-authored-by: Robert Snow <snowystinger@gmail.com>

Author: hasegawa-101

packages/react-aria-components/src/ListBox.tsx

@@ -10,7 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
-import {AriaListBoxOptions, AriaListBoxProps, DraggableItemResult, DragPreviewRenderer, DroppableCollectionResult, DroppableItemResult, FocusScope, ListKeyboardDelegate, mergeProps, useCollator, useFocus, useFocusRing, useHover, useListBox, useListBoxSection, useLocale, useOption} from 'react-aria';
+import {AriaListBoxOptions, AriaListBoxProps, DraggableItemResult, DragPreviewRenderer, DroppableCollectionResult, DroppableItemResult, FocusScope, ListKeyboardDelegate, mergeProps, useCollator, useFocus, useFocusRing, useHover, useKeyboard, useListBox, useListBoxSection, useLocale, useOption} from 'react-aria';
 import {
   ClassNameOrFunction,
   ContextValue,
@@ -33,7 +33,7 @@ import {DragAndDropContext, DropIndicatorContext, DropIndicatorProps, useDndPers
 import {DragAndDropHooks} from './useDragAndDrop';
 import {DraggableCollectionState, DroppableCollectionState, ListState, Node, Orientation, SelectionBehavior, UNSTABLE_useFilteredListState, useListState} from 'react-stately';
 import {filterDOMProps, inertValue, LoadMoreSentinelProps, useLoadMoreSentinel, useObjectRef} from '@react-aria/utils';
-import {FocusEvents, forwardRefType, GlobalDOMAttributes, HoverEvents, Key, LinkDOMProps, PressEvents, RefObject} from '@react-types/shared';
+import {FocusEvents, forwardRefType, GlobalDOMAttributes, HoverEvents, Key, KeyboardEvents, LinkDOMProps, PressEvents, RefObject} from '@react-types/shared';
 import {HeaderContext} from './Header';
 import React, {createContext, ForwardedRef, forwardRef, JSX, ReactNode, useContext, useEffect, useMemo, useRef} from 'react';
 import {SelectableCollectionContext, SelectableCollectionContextValue} from './RSPContexts';
@@ -340,7 +340,7 @@ export const ListBoxSection = /*#__PURE__*/ createBranchComponent(SectionNode, L
 
 export interface ListBoxItemRenderProps extends ItemRenderProps {}
 
-export interface ListBoxItemProps<T = object> extends Omit<RenderProps<ListBoxItemRenderProps>, 'render'>, PossibleLinkDOMRenderProps<'div', ListBoxItemRenderProps>, LinkDOMProps, HoverEvents, PressEvents, FocusEvents<HTMLDivElement>, Omit<GlobalDOMAttributes<HTMLDivElement>, 'onClick'> {
+export interface ListBoxItemProps<T = object> extends Omit<RenderProps<ListBoxItemRenderProps>, 'render'>, PossibleLinkDOMRenderProps<'div', ListBoxItemRenderProps>, LinkDOMProps, HoverEvents, PressEvents, KeyboardEvents, FocusEvents<HTMLDivElement>, Omit<GlobalDOMAttributes<HTMLDivElement>, 'onClick'> {
   /**
    * The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state.
    * @default 'react-aria-ListBoxItem'
@@ -383,6 +383,7 @@ export const ListBoxItem = /*#__PURE__*/ createLeafComponent(ItemNode, function
     onHoverEnd: item.props.onHoverEnd
   });
 
+  let {keyboardProps} = useKeyboard(props);
   let {focusProps} = useFocus(props);
 
   let draggableItem: DraggableItemResult | null = null;
@@ -431,7 +432,7 @@ export const ListBoxItem = /*#__PURE__*/ createLeafComponent(ItemNode, function
 
   return (
     <ElementType
-      {...mergeProps(DOMProps, renderProps, optionProps, hoverProps, focusProps, draggableItem?.dragProps, droppableItem?.dropProps)}
+      {...mergeProps(DOMProps, renderProps, optionProps, hoverProps, keyboardProps, focusProps, draggableItem?.dragProps, droppableItem?.dropProps)}
       ref={ref}
       data-allows-dragging={!!dragState || undefined}
       data-selected={states.isSelected || undefined}

packages/react-aria-components/test/ListBox.test.js

@@ -1406,7 +1406,7 @@ describe('ListBox', () => {
       act(() => jest.runAllTimers());
 
       expect(onReorder).toHaveBeenCalledTimes(1);
-      
+
       // Verify we're no longer in drag mode
       options = getAllByRole('option');
       expect(options.filter(opt => opt.classList.contains('react-aria-DropIndicator'))).toHaveLength(0);
@@ -1949,6 +1949,28 @@ describe('ListBox', () => {
     });
   });
 
+  describe('onKeyDown', () => {
+    it('should call key handler when key is pressed on item', async () => {
+      let onKeyDown = jest.fn((e) => e.continuePropagation());
+      let onKeyUp = jest.fn();
+      let onSelectionChange = jest.fn();
+      renderListbox({selectionMode: 'multiple', onSelectionChange}, {onKeyDown, onKeyUp});
+
+      await user.tab();
+      expect(onKeyUp).toHaveBeenCalledTimes(1);
+      onKeyUp.mockClear();
+      await user.keyboard('{Enter}');
+      expect(onKeyDown).toHaveBeenCalledTimes(1);
+      expect(onKeyUp).toHaveBeenCalledTimes(1);
+      expect(onSelectionChange).toHaveBeenCalledTimes(1);
+
+      await user.keyboard('{Escape}');
+      expect(onKeyDown).toHaveBeenCalledTimes(2);
+      expect(onKeyUp).toHaveBeenCalledTimes(2);
+      expect(onSelectionChange).toHaveBeenCalledTimes(2);
+    });
+  });
+
   if (React.version.startsWith('19')) {
     it('supports Activity', async () => {
       function ActivityListBox() {