From 668639722c71e7924c06c5c7b99e63e2e65cfc3a Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Sun, 15 Mar 2026 08:39:46 +0000
Subject: [PATCH] Cleanups

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 .changeset/add-listbox-component.md           |  2 +
 .../components/list-box/props-definition.tsx  | 10 +++
 packages/ui/report.api.md                     | 90 +++++++++++++++++--
 .../src/recipes/CardsWithListBox.stories.tsx  |  6 +-
 4 files changed, 98 insertions(+), 10 deletions(-)

diff --git a/.changeset/add-listbox-component.md b/.changeset/add-listbox-component.md
index 45faab32c5..af070bcbaa 100644
--- a/.changeset/add-listbox-component.md
+++ b/.changeset/add-listbox-component.md
@@ -3,3 +3,5 @@
 ---
 
 Added `ListBox` and `ListBoxItem` components. These provide a standalone, accessible list of selectable options built on top of React Aria's `ListBox` and `ListBoxItem` primitives. Items support icons, descriptions, and single or multiple selection modes.
+
+**Affected components:** ListBox, ListBoxItem
diff --git a/docs-ui/src/app/components/list-box/props-definition.tsx b/docs-ui/src/app/components/list-box/props-definition.tsx
index 861b211bc0..e2dcf2e5bf 100644
--- a/docs-ui/src/app/components/list-box/props-definition.tsx
+++ b/docs-ui/src/app/components/list-box/props-definition.tsx
@@ -67,6 +67,16 @@ export const listBoxItemPropDefs: Record<string, PropDef> = {
     type: 'boolean',
     description: 'Whether the item is disabled.',
   },
+  menuItems: {
+    type: 'enum',
+    values: ['Iterable<MenuItemConfig>'],
+    description: 'Menu items displayed for this list box item.',
+  },
+  customActions: {
+    type: 'enum',
+    values: ['ReactNode'],
+    description: 'Custom action elements displayed alongside the item.',
+  },
   ...childrenPropDefs,
   ...classNamePropDefs,
 };
diff --git a/packages/ui/report.api.md b/packages/ui/report.api.md
index 834251f088..a6786fb16e 100644
--- a/packages/ui/report.api.md
+++ b/packages/ui/report.api.md
@@ -23,8 +23,8 @@ import type { HeadingProps } from 'react-aria-components';
 import type { HTMLAttributes } from 'react';
 import { JSX as JSX_2 } from 'react/jsx-runtime';
 import type { LinkProps as LinkProps_2 } from 'react-aria-components';
-import type { ListBoxItemProps } from 'react-aria-components';
-import type { ListBoxProps } from 'react-aria-components';
+import type { ListBoxItemProps as ListBoxItemProps_2 } from 'react-aria-components';
+import type { ListBoxProps as ListBoxProps_2 } from 'react-aria-components';
 import type { MenuItemProps as MenuItemProps_2 } from 'react-aria-components';
 import type { MenuProps as MenuProps_2 } from 'react-aria-components';
 import type { MenuSectionProps as MenuSectionProps_2 } from 'react-aria-components';
@@ -1555,6 +1555,82 @@ export interface LinkProps
   extends Omit<LinkProps_2, 'children' | 'className'>,
     LinkOwnProps {}
 
+// @public
+export const ListBox: <T extends object>(
+  props: ListBoxProps<T>,
+) => JSX_2.Element;
+
+// @public
+export const ListBoxDefinition: {
+  readonly styles: {
+    readonly [key: string]: string;
+  };
+  readonly classNames: {
+    readonly root: 'bui-ListBox';
+  };
+  readonly propDefs: {
+    readonly items: {};
+    readonly children: {};
+    readonly renderEmptyState: {};
+    readonly className: {};
+  };
+};
+
+// @public
+export const ListBoxItem: (props: ListBoxItemProps) => JSX_2.Element;
+
+// @public
+export const ListBoxItemDefinition: {
+  readonly styles: {
+    readonly [key: string]: string;
+  };
+  readonly bg: 'consumer';
+  readonly classNames: {
+    readonly root: 'bui-ListBoxItem';
+    readonly check: 'bui-ListBoxItemCheck';
+    readonly icon: 'bui-ListBoxItemIcon';
+    readonly label: 'bui-ListBoxItemLabel';
+    readonly description: 'bui-ListBoxItemDescription';
+    readonly actions: 'bui-ListBoxItemActions';
+  };
+  readonly propDefs: {
+    readonly children: {};
+    readonly description: {};
+    readonly icon: {};
+    readonly menuItems: {};
+    readonly customActions: {};
+    readonly className: {};
+  };
+};
+
+// @public
+export type ListBoxItemOwnProps = {
+  children?: React.ReactNode;
+  description?: string;
+  icon?: React.ReactNode;
+  menuItems?: React.ReactNode;
+  customActions?: React.ReactNode;
+  className?: string;
+};
+
+// @public
+export interface ListBoxItemProps
+  extends ListBoxItemOwnProps,
+    Omit<ListBoxItemProps_2, keyof ListBoxItemOwnProps> {}
+
+// @public
+export type ListBoxOwnProps<T = object> = {
+  items?: ListBoxProps_2<T>['items'];
+  children?: ListBoxProps_2<T>['children'];
+  renderEmptyState?: ListBoxProps_2<T>['renderEmptyState'];
+  className?: string;
+};
+
+// @public
+export interface ListBoxProps<T>
+  extends ListBoxOwnProps<T>,
+    Omit<ListBoxProps_2<T>, keyof ListBoxOwnProps<T>> {}
+
 // @public (undocumented)
 export interface MarginProps {
   // (undocumented)
@@ -1589,13 +1665,13 @@ export const MenuAutocompleteListbox: (
 // @public (undocumented)
 export type MenuAutocompleteListBoxOwnProps = MenuPopoverOwnProps & {
   placeholder?: string;
-  selectionMode?: ListBoxProps<object>['selectionMode'];
+  selectionMode?: ListBoxProps_2<object>['selectionMode'];
 };
 
 // @public (undocumented)
 export interface MenuAutocompleteListBoxProps<T>
   extends MenuAutocompleteListBoxOwnProps,
-    Omit<ListBoxProps<T>, keyof MenuAutocompleteListBoxOwnProps> {}
+    Omit<ListBoxProps_2<T>, keyof MenuAutocompleteListBoxOwnProps> {}
 
 // @public (undocumented)
 export type MenuAutocompleteOwnProps = MenuPopoverOwnProps & {
@@ -1664,17 +1740,17 @@ export type MenuListBoxItemOwnProps = {
 // @public (undocumented)
 export interface MenuListBoxItemProps
   extends MenuListBoxItemOwnProps,
-    Omit<ListBoxItemProps, keyof MenuListBoxItemOwnProps> {}
+    Omit<ListBoxItemProps_2, keyof MenuListBoxItemOwnProps> {}
 
 // @public (undocumented)
 export type MenuListBoxOwnProps = MenuPopoverOwnProps & {
-  selectionMode?: ListBoxProps<object>['selectionMode'];
+  selectionMode?: ListBoxProps_2<object>['selectionMode'];
 };
 
 // @public (undocumented)
 export interface MenuListBoxProps<T>
   extends MenuListBoxOwnProps,
-    Omit<ListBoxProps<T>, keyof MenuListBoxOwnProps> {}
+    Omit<ListBoxProps_2<T>, keyof MenuListBoxOwnProps> {}
 
 // @public (undocumented)
 export type MenuOwnProps = MenuPopoverOwnProps;
diff --git a/packages/ui/src/recipes/CardsWithListBox.stories.tsx b/packages/ui/src/recipes/CardsWithListBox.stories.tsx
index d979743525..18d116f9e5 100644
--- a/packages/ui/src/recipes/CardsWithListBox.stories.tsx
+++ b/packages/ui/src/recipes/CardsWithListBox.stories.tsx
@@ -221,18 +221,18 @@ export const WithDescription = meta.story({
   args: {
     description: true,
   },
-  render: () => (
+  render: args => (
     <Container pt="4">
       <Grid.Root columns="2" gap="4">
         <ServiceListCard
           title="Frontend services"
           items={frontendServices}
-          description={true}
+          description={args.description}
         />
         <ServiceListCard
           title="Backend services"
           items={backendServices}
-          description={true}
+          description={args.description}
         />
       </Grid.Root>
     </Container>