@bento/listbox 0.1.2

package/src/header.tsx

@@ -0,0 +1,132 @@
+import React, { forwardRef, createContext, useContext } from 'react';
+import { createLeafComponent } from '@react-aria/collections';
+import { useProps } from '@bento/use-props';
+import { withSlots, type Slots } from '@bento/slots';
+
+/**
+ * Props for the Header component.
+ * @interface HeaderProps
+ */
+export interface HeaderProps extends Slots, React.ComponentProps<'header'> {
+  /**
+   * The children of the header.
+   */
+  readonly children?: React.ReactNode;
+}
+
+/**
+ * Context value structure for Header components.
+ * Extends HTML attributes to support all standard header element properties.
+ * @interface HeaderContextValue
+ */
+interface HeaderContextValue extends React.HTMLAttributes<HTMLElement> {
+  /**
+   * Reference to the header element for forwarding.
+   */
+  readonly ref?: React.RefObject<HTMLDivElement>;
+}
+
+/**
+ * Combined props type for the internal BentoHeader implementation.
+ * Merges Header-specific props with standard HTML attributes to provide
+ * a comprehensive interface for the internal header component.
+ *
+ * @type BentoHeaderProps
+ * @internal
+ */
+type BentoHeaderProps = HeaderProps & React.HTMLAttributes<HTMLElement>;
+
+/**
+ * React context for providing header-related attributes and refs to Header components.
+ * Used internally by ListBoxSection to pass heading props to Header elements.
+ * @public
+ */
+export const HeaderContext = createContext<HeaderContextValue>({});
+
+/**
+ * Internal implementation of the BentoHeader component with slots support.
+ * This component handles prop processing and context integration.
+ * It merges props from useProps and HeaderContext while preserving styling props.
+ *
+ * @internal
+ */
+const BentoHeaderImpl = withSlots(
+  'BentoHeader',
+  forwardRef(function BentoHeader(props: BentoHeaderProps, ref: React.ForwardedRef<HTMLElement>) {
+    const { props: processedProps, apply } = useProps(props);
+    const contextProps = useContext(HeaderContext);
+
+    // Apply user props directly (preserves className, style, etc.)
+    const appliedUserProps = apply(processedProps);
+
+    const composed = {
+      ...contextProps,
+      ...appliedUserProps // User props take precedence over context
+    };
+
+    return (
+      <header {...composed} ref={contextProps.ref || ref}>
+        {processedProps.children}
+      </header>
+    );
+  })
+);
+
+/**
+ * Wrapper component that connects the BentoHeaderImpl to React Aria's collection system.
+ * This function serves as an adapter between the createLeafComponent system and
+ * the internal BentoHeaderImpl component, ensuring proper prop forwarding and ref handling.
+ *
+ * @param {HeaderProps} props - Header component props
+ * @param {React.ReactNode} [props.children] - React children to render inside the header
+ * @param {React.ForwardedRef<HTMLElement>} ref - Forwarded ref to the header element
+ * @returns {React.ReactElement} The BentoHeaderImpl component with forwarded props and ref
+ * @internal
+ */
+function HeaderWrapper(props: HeaderProps, ref: React.ForwardedRef<HTMLElement>) {
+  return <BentoHeaderImpl {...props} ref={ref} />;
+}
+
+/**
+ * A Header represents a heading for a section within a ListBox.
+ * Uses React Aria's createLeafComponent for automatic collection handling.
+ *
+ * @component
+ * @param {HeaderProps} props - The props for the Header component
+ * @param {React.ForwardedRef<HTMLElement>} ref - Forwarded ref to the header element
+ * @returns {JSX.Element} A header element with proper accessibility attributes
+ *
+ * @example
+ * ```tsx
+ * <Header>My Section Title</Header>
+ * ```
+ * @public
+ */
+/**
+ * Base Header component created through React Aria's collection system.
+ * This handles the connection to the parent ListBox's collection state and
+ * integrates with the collection rendering system.
+ * @internal
+ */
+const HeaderBase = createLeafComponent('header', HeaderWrapper);
+
+/**
+ * A Header component for section headings within a ListBox.
+ * Provides semantic header structure with proper accessibility attributes
+ * and integrates with React Aria's collection system for automatic handling.
+ *
+ * This is the main public interface for creating headers in ListBox sections.
+ * It automatically receives heading props from the parent ListBoxSection via HeaderContext.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <ListBoxSection>
+ *   <Header>Fruits</Header>
+ *   <ListBoxItem>Apple</ListBoxItem>
+ *   <ListBoxItem>Banana</ListBoxItem>
+ * </ListBoxSection>
+ * ```
+ * @public
+ */
+export const Header = HeaderBase as React.ForwardRefExoticComponent<HeaderProps & React.RefAttributes<HTMLElement>>;

package/src/index.tsx

@@ -0,0 +1,9 @@
+export { Header, HeaderContext } from './header';
+export { ListBoxItem } from './listbox-item';
+export { ListBox, Collection } from './listbox';
+export { ListBoxSection } from './listbox-section';
+
+export type { HeaderProps } from './header';
+export type { ListBoxSectionProps } from './listbox-section';
+export type { ListBoxProps, ListBoxRenderProps } from './listbox';
+export type { ListBoxItemProps, ListBoxItemRenderProps } from './listbox-item';

package/src/listbox-item.tsx

@@ -0,0 +1,255 @@
+import React, { ForwardedRef, ReactNode, createContext, useContext, useMemo, forwardRef } from 'react';
+import { mergeProps, useOption, useHover } from 'react-aria';
+import { createLeafComponent } from '@react-aria/collections';
+import { HoverEvents, Key, LinkDOMProps, Node } from '@react-types/shared';
+import { useDataAttributes } from '@bento/use-data-attributes';
+import { useProps } from '@bento/use-props';
+import { ListStateContext } from './listbox';
+import { useSafeObjectRef } from './utils';
+import { withSlots } from '@bento/slots';
+
+/**
+ * Context value structure for text-related slot attributes.
+ * Used to provide label and description attributes to child components.
+ * @interface TextContextValue
+ */
+interface TextContextValue {
+  readonly slots: {
+    /** Attributes for label elements */
+    readonly label?: React.HTMLAttributes<HTMLElement>;
+    /** Attributes for description elements */
+    readonly description?: React.HTMLAttributes<HTMLElement>;
+  };
+}
+
+/**
+ * Internal context for providing text-related slot attributes to child components.
+ * This context allows ListBoxItem to pass label and description attributes
+ * to nested components that need them for accessibility.
+ * @internal
+ */
+const TextContext = createContext<TextContextValue>({ slots: {} });
+
+/**
+ * Render props provided to ListBoxItem render functions.
+ * @interface ListBoxItemRenderProps
+ */
+export interface ListBoxItemRenderProps {
+  /**
+   * Whether the item is currently hovered.
+   * @selector [data-hovered]
+   */
+  readonly isHovered: boolean;
+  /**
+   * Whether the item is currently pressed.
+   * @selector [data-pressed]
+   */
+  readonly isPressed: boolean;
+  /**
+   * Whether the item is currently selected.
+   * @selector [data-selected]
+   */
+  readonly isSelected: boolean;
+  /**
+   * Whether the item is currently focused.
+   * @selector [data-focused]
+   */
+  readonly isFocused: boolean;
+  /**
+   * Whether the item is currently keyboard focused.
+   * @selector [data-focus-visible]
+   */
+  readonly isFocusVisible: boolean;
+  /**
+   * Whether the item is disabled.
+   * @selector [data-disabled]
+   */
+  readonly isDisabled: boolean;
+  /**
+   * The type of selection that is allowed in the collection.
+   * @selector [data-selection-mode="none | single | multiple"]
+   */
+  readonly selectionMode: 'none' | 'single' | 'multiple';
+  /**
+   * The selection behavior for the collection.
+   * @selector [data-selection-behavior="toggle | replace"]
+   */
+  readonly selectionBehavior: 'toggle' | 'replace';
+}
+
+/**
+ * Props for the ListBoxItem component.
+ * @interface ListBoxItemProps
+ * @template T The type of the item value
+ */
+export interface ListBoxItemProps<T = object>
+  extends LinkDOMProps,
+    HoverEvents,
+    Omit<React.HTMLAttributes<HTMLElement>, keyof LinkDOMProps | keyof HoverEvents | 'id' | 'children'> {
+  /** The unique id of the item. If not provided, React Aria will auto-generate one. */
+  readonly id?: Key;
+  /** The object value that this item represents. When using dynamic collections, this is set automatically. */
+  readonly value?: T;
+  /** A string representation of the item's contents, used for features like typeahead. If not provided, React Aria will derive it from children automatically. */
+  readonly textValue?: string;
+  /**
+   * Handler that is called when a user performs an action on the item. The exact user event depends on the
+   * collection's `selectionBehavior` prop and the interaction modality.
+   */
+  readonly onAction?: () => void;
+  /** The contents of the item. Can be a render function that receives render props. */
+  readonly children?: ReactNode | ((values: ListBoxItemRenderProps) => ReactNode);
+  /**
+   * A slot name for the component. Used by Bento's slot system.
+   */
+  readonly slot?: string;
+  /** Whether the item is disabled. */
+  readonly isDisabled?: boolean;
+}
+
+/**
+ * Internal implementation component for ListBoxItem.
+ * Handles the core logic for rendering a single listbox item with proper accessibility.
+ * This component manages all the hooks, state, and interactions needed for a functional
+ * listbox item including selection, hover, focus, and keyboard interactions.
+ *
+ * @template T - The type of the item value
+ * @param {object} props - Combined ListBoxItem props and internal node data
+ * @param {Node<T>} props.__node - Internal React Aria node containing item metadata
+ * @param {React.ReactNode | ((values: ListBoxItemRenderProps) => React.ReactNode)} [props.children] - Content to render, can be static or a render function
+ * @param {boolean} [props.isDisabled] - Whether the item is disabled
+ * @param {string} [props.aria-label] - ARIA label for accessibility
+ * @param {(e: HoverEvent) => void} [props.onHoverStart] - Handler for hover start events
+ * @param {(isHovering: boolean) => void} [props.onHoverChange] - Handler for hover change events
+ * @param {(e: HoverEvent) => void} [props.onHoverEnd] - Handler for hover end events
+ * @param {React.ForwardedRef<HTMLDivElement>} ref - Forwarded ref to the item element
+ * @returns {React.ReactElement} A fully interactive listbox item with accessibility and state management
+ * @internal
+ */
+const ListBoxItemImplComponent = function ListBoxItemImplComponent<T extends object>(
+  { __node, ...props }: ListBoxItemProps<T> & { readonly __node: Node<T> },
+  ref: ForwardedRef<HTMLDivElement>
+) {
+  const state = useContext(ListStateContext)!;
+  const safeRef = useSafeObjectRef(ref);
+
+  const { optionProps, labelProps, descriptionProps, ...states } = useOption(
+    {
+      key: __node.key,
+      'aria-label': props['aria-label'],
+      isDisabled: props.isDisabled
+    },
+    state,
+    safeRef
+  );
+
+  const { hoverProps, isHovered } = useHover({
+    isDisabled: states.isDisabled,
+    onHoverStart: props.onHoverStart,
+    onHoverChange: props.onHoverChange,
+    onHoverEnd: props.onHoverEnd
+  });
+
+  const renderValues: ListBoxItemRenderProps = {
+    ...states,
+    isHovered,
+    selectionMode: state.selectionManager.selectionMode,
+    selectionBehavior: state.selectionManager.selectionBehavior
+  };
+
+  const content = typeof props.children === 'function' ? props.children(renderValues) : props.children;
+
+  const { apply } = useProps(props, renderValues);
+
+  const dataAttributes = useDataAttributes({
+    selected: states.isSelected,
+    disabled: states.isDisabled,
+    hovered: isHovered,
+    focused: states.isFocused,
+    'focus-visible': states.isFocusVisible,
+    pressed: states.isPressed,
+    level: __node.level,
+    'selection-mode': state.selectionManager.selectionMode,
+    'selection-behavior': state.selectionManager.selectionBehavior
+  });
+
+  const textContext = useMemo(
+    function createTextContext() {
+      return {
+        slots: {
+          label: labelProps,
+          description: descriptionProps
+        }
+      };
+    },
+    [labelProps, descriptionProps]
+  );
+
+  const ElementType = __node.props.href ? 'a' : 'div';
+
+  // Use original node props (which contain className) not filtered finalProps
+  const appliedUserProps = apply(__node.props, ['ref']);
+
+  const finalAttributes = {
+    ...mergeProps(optionProps, hoverProps), // React Aria props
+    ...dataAttributes, // Bento data attributes
+    ...appliedUserProps,
+    ref: safeRef,
+    'data-text-value': __node.textValue
+  };
+
+  return (
+    <TextContext.Provider value={textContext}>
+      {React.createElement(ElementType, finalAttributes, content)}
+    </TextContext.Provider>
+  );
+};
+
+/**
+ * Enhanced ListBoxItem implementation with slots support.
+ * This wraps the core ListBoxItemImplComponent with Bento's slot system
+ * for advanced composition and styling capabilities.
+ * @internal
+ */
+export const ListBoxItemImpl = withSlots('BentoListBoxItem', forwardRef(ListBoxItemImplComponent));
+
+/**
+ * Adapter component that connects ListBoxItemImpl to React Aria's collection system.
+ * This function serves as a bridge between React Aria's createLeafComponent and
+ * the internal ListBoxItemImpl, ensuring proper prop forwarding and node injection.
+ *
+ * @template T - The type of the item value
+ * @param {ListBoxItemProps<T>} props - ListBoxItem component props
+ * @param {React.ForwardedRef<HTMLDivElement>} forwardedRef - Ref forwarded from the collection system
+ * @param {Node<T>} item - React Aria node containing item metadata and collection info
+ * @returns {React.ReactElement} The ListBoxItemImpl component with proper node and ref wiring
+ * @internal
+ */
+function ListBoxItemComponent<T extends object>(
+  props: ListBoxItemProps<T>,
+  forwardedRef: ForwardedRef<HTMLDivElement>,
+  item: Node<T>
+) {
+  return <ListBoxItemImpl {...props} ref={forwardedRef} __node={item} />;
+}
+
+/**
+ * Base ListBoxItem component created through React Aria's collection system.
+ * This handles the connection to the parent ListBox's collection state.
+ * @internal
+ */
+const ListBoxItemBase = createLeafComponent('item', ListBoxItemComponent);
+
+/**
+ * A single item within a ListBox component.
+ * Handles user interactions, accessibility, and state management for individual options.
+ *
+ * @component
+ * @template T The type of the item value
+ * @example
+ * ```tsx
+ * <ListBoxItem>Simple option</ListBoxItem>
+ * ```
+ * @public
+ */
+export const ListBoxItem = ListBoxItemBase;

package/src/listbox-section.tsx

@@ -0,0 +1,171 @@
+import React, { forwardRef, useRef, useContext } from 'react';
+import { useListBoxSection, mergeProps } from 'react-aria';
+import { createBranchComponent } from '@react-aria/collections';
+import { CollectionRendererContext } from 'react-aria-components';
+import type { Node } from '@react-types/shared';
+import { useDataAttributes } from '@bento/use-data-attributes';
+import { useProps } from '@bento/use-props';
+import { withSlots } from '@bento/slots';
+import { HeaderContext } from './header';
+import { ListStateContext } from './listbox';
+
+/**
+ * Props for the ListBoxSection component.
+ * @interface ListBoxSectionProps
+ */
+export interface ListBoxSectionProps extends Omit<React.ComponentProps<'section'>, 'title'> {
+  /**
+   * A slot name for the component. Used by Bento's slot system.
+   */
+  readonly slot?: string;
+  /**
+   * The title of the section.
+   */
+  readonly title?: React.ReactNode;
+  /**
+   * The children of the section.
+   */
+  readonly children?: React.ReactNode;
+}
+
+/**
+ * Internal props interface for BentoListBoxSectionImpl component.
+ * Extends ListBoxSectionProps with internal React Aria node data and allows
+ * additional properties for flexibility in prop handling.
+ *
+ * @interface BentoListBoxSectionImplProps
+ * @template T - The type of the section node data
+ * @internal
+ */
+interface BentoListBoxSectionImplProps<T = unknown> extends ListBoxSectionProps {
+  readonly __node?: Node<T>;
+  readonly [key: string]: unknown;
+}
+
+/**
+ * Props interface for the ListBoxSectionInner component.
+ * Contains the React Aria section node that represents this section
+ * in the collection hierarchy for dynamic rendering.
+ *
+ * @interface ListBoxSectionInnerProps
+ * @internal
+ */
+interface ListBoxSectionInnerProps {
+  readonly section: Node<unknown>;
+}
+
+/**
+ * Internal implementation of the BentoListBoxSection component with slots support.
+ * This component handles the core logic for rendering a section within a ListBox,
+ * including title rendering, accessibility attributes, and child content management.
+ * It integrates with React Aria's useListBoxSection hook for proper ARIA compliance.
+ *
+ * @internal
+ */
+const BentoListBoxSectionImpl = withSlots(
+  'BentoListBoxSection',
+  forwardRef(function BentoListBoxSectionImpl<T>(
+    { __node, children, title: titleProp, ...rest }: BentoListBoxSectionImplProps<T>,
+    ref: React.ForwardedRef<HTMLElement>
+  ) {
+    const { props, apply } = useProps(rest);
+    const data = useDataAttributes({ level: __node?.level });
+    const headingRef = useRef<HTMLDivElement>(null);
+
+    const title = titleProp ?? props.title ?? __node?.rendered;
+    const { groupProps, headingProps } = useListBoxSection({
+      heading: title,
+      'aria-label': props['aria-label']
+    });
+
+    const composed = mergeProps(apply({ ...data, ...props }, ['children', 'title', 'slot']), groupProps);
+
+    const sectionContent = children || props.children;
+
+    return (
+      <section {...composed} ref={ref}>
+        <HeaderContext.Provider value={{ ...headingProps, ref: headingRef }}>
+          {title && <div {...headingProps}>{title}</div>}
+          {sectionContent}
+        </HeaderContext.Provider>
+      </section>
+    );
+  })
+);
+
+/**
+ * Wrapper component that connects BentoListBoxSectionImpl to React Aria's collection system.
+ * This function serves as an adapter between createBranchComponent and the internal
+ * BentoListBoxSectionImpl, ensuring proper prop forwarding and node injection for sections.
+ *
+ * @template T - The type of the section node data
+ * @param {ListBoxSectionProps} props - ListBoxSection component props
+ * @param {string} [props.slot] - Slot name for Bento's slot system
+ * @param {React.ReactNode} [props.title] - Title for the section
+ * @param {React.ReactNode} [props.children] - Children to render in the section
+ * @param {string} [props.aria-label] - ARIA label for accessibility
+ * @param {React.ForwardedRef<HTMLElement>} ref - Ref forwarded from the collection system
+ * @param {Node<T>} section - React Aria node containing section metadata and collection info
+ * @returns {React.ReactElement} The BentoListBoxSectionImpl component with proper node and ref wiring
+ * @internal
+ */
+/* v8 ignore start */
+function ListBoxSectionWrapper<T extends object>(
+  props: ListBoxSectionProps,
+  ref: React.ForwardedRef<HTMLElement>,
+  section: Node<T>
+) {
+  return <BentoListBoxSectionImpl {...props} __node={section} ref={ref} />;
+}
+/* v8 ignore stop */
+
+/**
+ * Base ListBoxSection component created through React Aria's collection system.
+ * This handles the connection to the parent ListBox's collection state and
+ * manages the branch structure for nested items.
+ * @internal
+ */
+const ListBoxSectionBase = createBranchComponent('section', ListBoxSectionWrapper);
+
+/**
+ * Internal component for rendering dynamic collection sections.
+ * This component is used specifically for sections that are part of a dynamic collection,
+ * connecting to the ListStateContext and CollectionRendererContext to properly render
+ * nested items through React Aria's collection system.
+ *
+ * @component
+ * @param {object} props - The component props containing the section node
+ * @param {Node<unknown>} props.section - The React Aria node representing this section in the collection
+ * @throws {BentoError} Throws an error if used outside of a ListBox context
+ * @returns {React.ReactElement} JSX element representing a dynamically rendered listbox section
+ * @internal
+ */
+export const ListBoxSectionInner: React.FC<ListBoxSectionInnerProps> = function ListBoxSectionInner({ section }) {
+  const state = useContext(ListStateContext);
+  const { CollectionBranch } = useContext(CollectionRendererContext);
+
+  return (
+    <BentoListBoxSectionImpl {...section.props} __node={section}>
+      {CollectionBranch && state?.collection ? (
+        <CollectionBranch collection={state.collection} parent={section} />
+      ) : null}
+    </BentoListBoxSectionImpl>
+  );
+};
+
+/**
+ * A section component for organizing related items within a ListBox.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <ListBoxSection title="Fruits">
+ *   <ListBoxItem>Apple</ListBoxItem>
+ *   <ListBoxItem>Banana</ListBoxItem>
+ * </ListBoxSection>
+ * ```
+ * @public
+ */
+export const ListBoxSection = ListBoxSectionBase as <_T extends object>(
+  props: ListBoxSectionProps & { children?: React.ReactNode }
+) => React.ReactElement;