@bento/listbox 0.1.2

package/dist/index.d.cts

@@ -0,0 +1,264 @@
+import React, { ReactNode } from 'react';
+import { Slots } from '@bento/slots';
+import { LinkDOMProps, HoverEvents, Key } from '@react-types/shared';
+import { SelectionBehavior, ListState, Orientation } from 'react-stately';
+import { AriaListBoxProps } from '@react-types/listbox';
+export { Collection } from '@react-aria/collections';
+
+/**
+ * Props for the Header component.
+ * @interface HeaderProps
+ */
+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>;
+}
+/**
+ * React context for providing header-related attributes and refs to Header components.
+ * Used internally by ListBoxSection to pass heading props to Header elements.
+ * @public
+ */
+declare const HeaderContext: React.Context<HeaderContextValue>;
+/**
+ * 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
+ */
+declare const Header: React.ForwardRefExoticComponent<HeaderProps & React.RefAttributes<HTMLElement>>;
+
+/**
+ * Render props provided to ListBoxItem render functions.
+ * @interface ListBoxItemRenderProps
+ */
+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
+ */
+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;
+}
+/**
+ * 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
+ */
+declare const ListBoxItem: <T extends object>(props: ListBoxItemProps<T> & React.RefAttributes<T>) => React.ReactElement | null;
+
+/**
+ * Render props provided to ListBox render functions and empty state renderers.
+ * @interface ListBoxRenderProps
+ */
+interface ListBoxRenderProps {
+    /**
+     * Whether the listbox has no items and should display its empty state.
+     * @selector [data-empty]
+     */
+    readonly isEmpty: boolean;
+    /**
+     * Whether the listbox is currently focused.
+     * @selector [data-focused]
+     */
+    readonly isFocused: boolean;
+    /**
+     * Whether the listbox is currently keyboard focused.
+     * @selector [data-focus-visible]
+     */
+    readonly isFocusVisible: boolean;
+    /**
+     * Whether the listbox is currently the active drop target.
+     * @selector [data-drop-target]
+     */
+    readonly isDropTarget: boolean;
+    /**
+     * Whether the items are arranged in a stack or grid.
+     * @selector [data-layout="stack | grid"]
+     */
+    readonly layout?: 'stack' | 'grid';
+    /**
+     * State of the listbox.
+     */
+    readonly state: ListState<unknown>;
+    /**
+     * The items array when using dynamic collections.
+     */
+    readonly items?: Iterable<unknown>;
+}
+/**
+ * Props for the ListBox component.
+ * @interface ListBoxProps
+ * @template T The type of items in the collection
+ */
+interface ListBoxProps<T> extends Omit<AriaListBoxProps<T>, 'label' | 'children'>, Omit<React.ComponentProps<'div'>, keyof AriaListBoxProps<T> | 'children'>, Slots {
+    /**
+     * How multiple selection should behave in the collection.
+     */
+    readonly selectionBehavior?: SelectionBehavior;
+    /**
+     * Provides content to display when there are no items in the list.
+     */
+    readonly renderEmptyState?: (props: ListBoxRenderProps) => React.ReactNode;
+    /**
+     * Whether the items are arranged in a stack layout.
+     * @default 'stack'
+     */
+    readonly layout?: 'stack';
+    /**
+     * The primary orientation of the items. Usually this is the direction that the collection scrolls.
+     * @default 'vertical'
+     */
+    readonly orientation?: Orientation;
+    /**
+     * Static children or render function for the ListBox.
+     * When items prop is provided, children receives individual items for React Aria compatibility.
+     * When no items prop is provided, children receives Bento render props { isEmpty, isFocused, state, etc. }.
+     */
+    readonly children?: React.ReactNode | ((item: T) => React.ReactNode) | ((props: ListBoxRenderProps) => React.ReactNode);
+}
+/**
+ * A complete ListBox component providing accessible selection lists with keyboard navigation.
+ * Supports both static children and dynamic collections, with single/multiple selection modes.
+ * Built on React Aria with full ARIA compliance and keyboard accessibility.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <ListBox aria-label="Fruits" selectionMode="single">
+ *   <ListBoxItem id="apple" textValue="Apple">Apple</ListBoxItem>
+ *   <ListBoxItem id="banana" textValue="Banana">Banana</ListBoxItem>
+ * </ListBox>
+ * ```
+ * @public
+ */
+declare const ListBox: React.NamedExoticComponent<ListBoxProps<unknown> & Slots>;
+
+/**
+ * Props for the ListBoxSection component.
+ * @interface ListBoxSectionProps
+ */
+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;
+}
+/**
+ * A section component for organizing related items within a ListBox.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <ListBoxSection title="Fruits">
+ *   <ListBoxItem>Apple</ListBoxItem>
+ *   <ListBoxItem>Banana</ListBoxItem>
+ * </ListBoxSection>
+ * ```
+ * @public
+ */
+declare const ListBoxSection: <_T extends object>(props: ListBoxSectionProps & {
+    children?: React.ReactNode;
+}) => React.ReactElement;
+
+export { Header, HeaderContext, type HeaderProps, ListBox, ListBoxItem, type ListBoxItemProps, type ListBoxItemRenderProps, type ListBoxProps, type ListBoxRenderProps, ListBoxSection, type ListBoxSectionProps };

package/dist/index.d.ts

@@ -0,0 +1,264 @@
+import React, { ReactNode } from 'react';
+import { Slots } from '@bento/slots';
+import { LinkDOMProps, HoverEvents, Key } from '@react-types/shared';
+import { SelectionBehavior, ListState, Orientation } from 'react-stately';
+import { AriaListBoxProps } from '@react-types/listbox';
+export { Collection } from '@react-aria/collections';
+
+/**
+ * Props for the Header component.
+ * @interface HeaderProps
+ */
+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>;
+}
+/**
+ * React context for providing header-related attributes and refs to Header components.
+ * Used internally by ListBoxSection to pass heading props to Header elements.
+ * @public
+ */
+declare const HeaderContext: React.Context<HeaderContextValue>;
+/**
+ * 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
+ */
+declare const Header: React.ForwardRefExoticComponent<HeaderProps & React.RefAttributes<HTMLElement>>;
+
+/**
+ * Render props provided to ListBoxItem render functions.
+ * @interface ListBoxItemRenderProps
+ */
+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
+ */
+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;
+}
+/**
+ * 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
+ */
+declare const ListBoxItem: <T extends object>(props: ListBoxItemProps<T> & React.RefAttributes<T>) => React.ReactElement | null;
+
+/**
+ * Render props provided to ListBox render functions and empty state renderers.
+ * @interface ListBoxRenderProps
+ */
+interface ListBoxRenderProps {
+    /**
+     * Whether the listbox has no items and should display its empty state.
+     * @selector [data-empty]
+     */
+    readonly isEmpty: boolean;
+    /**
+     * Whether the listbox is currently focused.
+     * @selector [data-focused]
+     */
+    readonly isFocused: boolean;
+    /**
+     * Whether the listbox is currently keyboard focused.
+     * @selector [data-focus-visible]
+     */
+    readonly isFocusVisible: boolean;
+    /**
+     * Whether the listbox is currently the active drop target.
+     * @selector [data-drop-target]
+     */
+    readonly isDropTarget: boolean;
+    /**
+     * Whether the items are arranged in a stack or grid.
+     * @selector [data-layout="stack | grid"]
+     */
+    readonly layout?: 'stack' | 'grid';
+    /**
+     * State of the listbox.
+     */
+    readonly state: ListState<unknown>;
+    /**
+     * The items array when using dynamic collections.
+     */
+    readonly items?: Iterable<unknown>;
+}
+/**
+ * Props for the ListBox component.
+ * @interface ListBoxProps
+ * @template T The type of items in the collection
+ */
+interface ListBoxProps<T> extends Omit<AriaListBoxProps<T>, 'label' | 'children'>, Omit<React.ComponentProps<'div'>, keyof AriaListBoxProps<T> | 'children'>, Slots {
+    /**
+     * How multiple selection should behave in the collection.
+     */
+    readonly selectionBehavior?: SelectionBehavior;
+    /**
+     * Provides content to display when there are no items in the list.
+     */
+    readonly renderEmptyState?: (props: ListBoxRenderProps) => React.ReactNode;
+    /**
+     * Whether the items are arranged in a stack layout.
+     * @default 'stack'
+     */
+    readonly layout?: 'stack';
+    /**
+     * The primary orientation of the items. Usually this is the direction that the collection scrolls.
+     * @default 'vertical'
+     */
+    readonly orientation?: Orientation;
+    /**
+     * Static children or render function for the ListBox.
+     * When items prop is provided, children receives individual items for React Aria compatibility.
+     * When no items prop is provided, children receives Bento render props { isEmpty, isFocused, state, etc. }.
+     */
+    readonly children?: React.ReactNode | ((item: T) => React.ReactNode) | ((props: ListBoxRenderProps) => React.ReactNode);
+}
+/**
+ * A complete ListBox component providing accessible selection lists with keyboard navigation.
+ * Supports both static children and dynamic collections, with single/multiple selection modes.
+ * Built on React Aria with full ARIA compliance and keyboard accessibility.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <ListBox aria-label="Fruits" selectionMode="single">
+ *   <ListBoxItem id="apple" textValue="Apple">Apple</ListBoxItem>
+ *   <ListBoxItem id="banana" textValue="Banana">Banana</ListBoxItem>
+ * </ListBox>
+ * ```
+ * @public
+ */
+declare const ListBox: React.NamedExoticComponent<ListBoxProps<unknown> & Slots>;
+
+/**
+ * Props for the ListBoxSection component.
+ * @interface ListBoxSectionProps
+ */
+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;
+}
+/**
+ * A section component for organizing related items within a ListBox.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <ListBoxSection title="Fruits">
+ *   <ListBoxItem>Apple</ListBoxItem>
+ *   <ListBoxItem>Banana</ListBoxItem>
+ * </ListBoxSection>
+ * ```
+ * @public
+ */
+declare const ListBoxSection: <_T extends object>(props: ListBoxSectionProps & {
+    children?: React.ReactNode;
+}) => React.ReactElement;
+
+export { Header, HeaderContext, type HeaderProps, ListBox, ListBoxItem, type ListBoxItemProps, type ListBoxItemRenderProps, type ListBoxProps, type ListBoxRenderProps, ListBoxSection, type ListBoxSectionProps };