@bento/listbox 0.1.2 → 0.2.0

package/README.md

@@ -0,0 +1,540 @@
+# ListBox
+
+The `@bento/listbox` package provides a flexible, accessible listbox primitive that supports both controlled and uncontrolled selection modes. Built on React Aria for interaction fidelity and designed for composition within higher-level components like Select, Combobox, and Menu.
+
+## Installation
+
+```shell
+npm install --save @bento/listbox
+```
+
+## Component Structure
+
+The `@bento/listbox` package exports five main components:
+
+- **ListBox**: The main container component that manages selection state, keyboard navigation, and accessibility
+- **ListBoxItem**: Individual selectable items within the listbox
+- **ListBoxSection**: Optional grouping component for organizing options into sections
+- **Header**: Accessible heading for a `ListBoxSection`, forwards props and refs for full styling control
+- **Collection**: Utility for rendering nested dynamic data inside a `ListBoxSection` (or other collection-aware context).
+
+## Props
+
+The following properties are available on the `ListBox` component:
+
+## Static Items
+
+```tsx
+/* v8 ignore next */
+import React from 'react';
+import { ListBox, ListBoxItem } from '@bento/listbox';
+import style from './listbox.module.css';
+
+/**
+ * Example component demonstrating basic ListBox usage.
+ *
+ * @param {any} args - The component props.
+ * @returns {JSX.Element} The rendered ListBox with static items.
+ * @public
+ */
+export function BasicListBoxExample(args: any) {
+  return (
+    <ListBox {...args} className={style.listbox}>
+      <ListBoxItem>Chicken Teriyaki</ListBoxItem>
+      <ListBoxItem>Salmon Bento</ListBoxItem>
+      <ListBoxItem>Beef Bowl</ListBoxItem>
+    </ListBox>
+  );
+}
+```
+
+## Sections
+
+Use `ListBoxSection` to group related options. Use `Header` inside a `ListBoxSection` to render an accessible heading for the group. It automatically links the heading to the section via `aria-labelledby`.
+
+The `<Header>` component accepts standard DOM props and a `slot` prop for Bento’s slot system, enabling fine-grained overrides in composite components.
+
+```tsx
+/* v8 ignore next */
+import React from 'react';
+import { ListBox, ListBoxItem, ListBoxSection, Header } from '@bento/listbox';
+import style from './listbox.module.css';
+
+/**
+ * Example component demonstrating ListBox with static sections.
+ *
+ * @param {any} args - The component props.
+ * @returns {JSX.Element} The rendered ListBox with sectioned items.
+ * @public
+ */
+export function SectionsExample(args: any) {
+  return (
+    <ListBox {...args} className={style.listbox}>
+      <ListBoxSection>
+        <Header>Main Dishes</Header>
+        <ListBoxItem>Chicken Teriyaki</ListBoxItem>
+        <ListBoxItem>Salmon Bento</ListBoxItem>
+      </ListBoxSection>
+      <ListBoxSection>
+        <Header>Side Dishes</Header>
+        <ListBoxItem>Pickled Vegetables</ListBoxItem>
+        <ListBoxItem>Edamame</ListBoxItem>
+      </ListBoxSection>
+    </ListBox>
+  );
+}
+```
+
+## Dynamic Collections
+
+For dynamic data, use the `items` prop with a render function. The ListBox component follows different patterns depending on how it's used:
+
+### When `items` prop is provided
+When you provide an `items` prop, the `children` function receives **individual items** for React Aria compatibility:
+
+```tsx
+/* v8 ignore next */
+import React from 'react';
+import { ListBox, ListBoxItem } from '@bento/listbox';
+import style from './listbox.module.css';
+
+/**
+ * Example component demonstrating ListBox with dynamic collections.
+ *
+ * @param {any} args - The component props including items array.
+ * @returns {JSX.Element} The rendered ListBox with dynamic items.
+ * @public
+ */
+export function DynamicCollectionExample({ items, ...args }: any) {
+  return (
+    <ListBox {...args} className={style.listbox} items={items}>
+      {(item: any) => (
+        <ListBoxItem key={item.id} textValue={item.name}>
+          {item.name}
+        </ListBoxItem>
+      )}
+    </ListBox>
+  );
+}
+```
+
+In this pattern, `children` is called for each item in the `items` array, receiving the individual item data to render `ListBoxItem` components.
+
+### When no `items` prop is provided
+When you don't provide an `items` prop but use `children` as a function, it follows **Bento's render prop pattern** and receives an object with render props:
+
+```tsx
+<ListBox aria-label="Custom ListBox">
+  {({ isEmpty, isFocused, state, items }) => (
+    isEmpty ? (
+      <div>No items available</div>
+    ) : (
+      // Render items normally using static children or other logic
+      <ListBoxItem>Static Item</ListBoxItem>
+    )
+  )}
+</ListBox>
+```
+
+This pattern provides access to the ListBox's state, focus status, and other render props following Bento's consistent render prop API.
+
+### Nested Collections with Sections
+You can also render nested data inside a section using the exported `Collection` component:
+
+```tsx
+/* v8 ignore next */
+import React from 'react';
+import { ListBox, ListBoxItem } from '@bento/listbox';
+import style from './listbox.module.css';
+
+/**
+ * Example component demonstrating ListBox with dynamic collections.
+ *
+ * @param {any} args - The component props including items array.
+ * @returns {JSX.Element} The rendered ListBox with dynamic items.
+ * @public
+ */
+export function DynamicCollectionExample({ items, ...args }: any) {
+  return (
+    <ListBox {...args} className={style.listbox} items={items}>
+      {(item: any) => (
+        <ListBoxItem key={item.id} textValue={item.name}>
+          {item.name}
+        </ListBoxItem>
+      )}
+    </ListBox>
+  );
+}
+```
+
+## Customization
+
+The ListBox components provide extensive customization options through data attributes, slots, render props, and standard CSS styling. This section covers all available approaches to customize the appearance and behavior.
+
+### Styling with Data Attributes
+
+All ListBox components expose their internal state through data attributes,
+enabling CSS-based styling without JavaScript. This follows Bento's design
+philosophy of returning styling control to CSS.
+
+#### ListBox Container Attributes
+
+The main `ListBox` component exposes these data attributes:
+
+| Attribute                    | Description                                       | Example Values                |
+| ---------------------------- | ------------------------------------------------- | ----------------------------- |
+| `data-empty`                 | Applied when the listbox contains no items        | "true"                        |
+| `data-focused`               | Applied when the listbox is focused               | "true"                        |
+| `data-focus-visible`         | Applied when the listbox has keyboard focus       | "true"                        |
+| `data-layout`                | The layout type                                   | "stack"                       |
+| `data-orientation`           | The primary orientation                           | "vertical" / "horizontal"     |
+| `data-selection-mode`        | The selection mode                                | "none" / "single" / "multiple"|
+| `data-selection-behavior`    | How selection behaves                             | "toggle" / "replace"          |
+| `data-allows-tab-navigation` | Whether tab navigation is enabled                 | "true"                        |
+| `data-focus-wrap`            | Whether focus wraps around the collection         | "true"                        |
+
+#### ListBoxItem Attributes
+
+Individual `ListBoxItem` components expose these data attributes:
+
+| Attribute                | Description                                | Example Values                |
+| ------------------------ | ------------------------------------------ | ----------------------------- |
+| `data-selected`          | Applied when the item is selected          | "true"                        |
+| `data-disabled`          | Applied when the item is disabled          | "true"                        |
+| `data-hovered`           | Applied when the item is being hovered     | "true"                        |
+| `data-focused`           | Applied when the item is focused           | "true"                        |
+| `data-focus-visible`     | Applied when the item has keyboard focus   | "true"                        |
+| `data-pressed`           | Applied when the item is being pressed     | "true"                        |
+| `data-level`             | The nesting level (useful for indentation) | "0" / "1" / "2"               |
+| `data-selection-mode`    | Inherited selection mode                   | "none" / "single" / "multiple"|
+| `data-selection-behavior`| Inherited selection behavior               | "toggle" / "replace"          |
+| `data-text-value`        | The computed text value for the item       | "Item text"                   |
+
+#### ListBoxSection Attributes
+
+The `ListBoxSection` component exposes:
+
+| Attribute    | Description                      | Example Values  |
+| ------------ | -------------------------------- | --------------- |
+| `data-level` | The nesting level of the section | "0" / "1" / "2" |
+
+#### CSS Styling Examples
+
+```css
+/* Basic item styling */
+[role="option"] {
+  padding: 8px 12px;
+  border-radius: 6px;
+  transition: all 0.15s ease-in-out;
+  cursor: pointer;
+}
+
+/* Selected items */
+[role="option"][data-selected] {
+  background: Highlight;
+  color: HighlightText;
+}
+
+/* Hovered items */
+[role="option"][data-hovered] {
+  background: color-mix(in srgb, Highlight 10%, transparent);
+}
+
+/* Disabled items */
+[role="option"][data-disabled] {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+/* Focused items (keyboard navigation) */
+[role="option"][data-focus-visible] {
+  outline: 2px solid Highlight;
+  outline-offset: -2px;
+}
+
+/* Combined states */
+[role="option"][data-selected][data-hovered] {
+  background: color-mix(in srgb, Highlight 90%, white);
+}
+
+/* Empty state styling */
+.listbox[data-empty] {
+  min-height: 100px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: #64748b;
+}
+
+/* Section headers */
+.section-header {
+  font-weight: 600;
+  font-size: 0.875rem;
+  color: #64748b;
+  padding: 6px 12px;
+  margin-bottom: 4px;
+}
+```
+
+### Slots System
+
+The components use Bento's `@bento/slots` package for fine-grained component overrides. Slots allow you to replace or wrap specific parts of the component tree with custom implementations.
+
+#### Basic Slot Usage
+
+```tsx
+/* v8 ignore next */
+import React from 'react';
+import { ListBox, ListBoxItem, ListBoxSection, Header, Collection } from '@bento/listbox';
+import { useProps } from '@bento/use-props';
+import style from './listbox.module.css';
+
+//
+// Slot namespace layout:
+//
+// ```
+// bento-list                 (ListBox)
+// ├── main-dishes            (ListBoxSection)
+// │   ├── header             (Header)
+// │   ├── chicken-teriyaki   (ListBoxItem)
+// │   └── salmon-bento       (ListBoxItem)
+// └── side-dishes            (ListBoxSection)
+//     ├── header             (Header)
+//     ├── pickled-vegetables (ListBoxItem)
+//     └── edamame            (ListBoxItem)
+// ```
+//
+// This example demonstrates several slot override patterns:
+// 1. `side-dishes.header` – Custom header component with enhanced styling
+// 2. `side-dishes.pickled-vegetables` – Override specific item in specific section
+// 3. `main-dishes` – Override entire section styling
+//
+
+/**
+ * Example component demonstrating ListBox with dynamic sections and slot overrides.
+ *
+ * @param {any} args - The component props including categories and slots.
+ * @returns {JSX.Element} The rendered ListBox with slotted dynamic sections.
+ * @public
+ */
+export function SlotsDynamicSectionsExample({ categories, ...args }: any) {
+  const {
+    items: argItems,
+    slots: argSlots = {},
+    ...rest
+  } = args as {
+    items?: Iterable<unknown>;
+    slots?: Record<string, any>;
+  } & Record<string, unknown>;
+
+  const { apply } = useProps(rest);
+
+  //
+  // Default slot overrides for demo - these show different override patterns
+  //
+  const demoSlots: Record<string, any> = {
+    //
+    // Override a header in a specific section with custom styling
+    //
+    'side-dishes.header': ({ props, original }: { props: Record<string, any>; original: React.ReactNode }) => (
+      <Header {...props}>🥢 {original}</Header>
+    ),
+
+    //
+    // Override another specific item with custom content
+    //
+    'side-dishes.pickled-vegetables': ({ original }: { original: React.ReactNode }) => (
+      <div style={{ backgroundColor: '#4ade80', color: 'white', padding: '2px 6px', borderRadius: '4px' }}>
+        🥒 {original} (Traditional)
+      </div>
+    ),
+
+    //
+    // Override an entire section with custom wrapper
+    //
+    'main-dishes': ({ original }: { original: React.ReactNode }) => (
+      <div style={{ border: '2px dashed #f59e0b', padding: '8px', borderRadius: '6px' }}>{original}</div>
+    )
+  };
+
+  //
+  // Merge provided slots with demo slots (provided slots take precedence)
+  //
+  const mergedSlots = { ...demoSlots, ...argSlots };
+
+  return (
+    <ListBox
+      {...apply({ className: style.listbox })}
+      // Only set items if caller didn't already supply one
+      items={argItems ?? categories}
+      slot="bento-list"
+      slots={mergedSlots}
+    >
+      {(category: any) => (
+        <ListBoxSection key={category.id} slot={category.id}>
+          <Header slot="header">{category.name}</Header>
+          <Collection items={category.items}>
+            {(item: { id: string; name: string }) => (
+              <ListBoxItem key={item.id} textValue={item.name} slot={item.id}>
+                {item.name}
+              </ListBoxItem>
+            )}
+          </Collection>
+        </ListBoxSection>
+      )}
+    </ListBox>
+  );
+}
+```
+
+#### Advanced Slot Patterns
+
+You can target specific items or sections using hierarchical slot names:
+
+```tsx
+// Override a specific section header
+const slots = {
+  'my-listbox.fruits.header': ({ original, props }) => (
+    <Header {...props}>🍎 {original}</Header>
+  ),
+
+  // Override a specific item in a specific section
+  'my-listbox.fruits.apple': ({ original }) => (
+    <div className="special-item">⭐ {original}</div>
+  ),
+
+  // Override an entire section
+  'my-listbox.vegetables': ({ original }) => (
+    <div className="veggie-section">{original}</div>
+  )
+};
+
+<ListBox slot="my-listbox" slots={slots}>
+  <ListBoxSection slot="fruits">
+    <Header slot="header">Fruits</Header>
+    <ListBoxItem slot="apple">Apple</ListBoxItem>
+    <ListBoxItem slot="orange">Orange</ListBoxItem>
+  </ListBoxSection>
+  <ListBoxSection slot="vegetables">
+    <Header slot="header">Vegetables</Header>
+    <ListBoxItem slot="carrot">Carrot</ListBoxItem>
+  </ListBoxSection>
+</ListBox>
+```
+
+### Render Props
+
+The `ListBoxItem` component supports render prop patterns for dynamic content based on interaction state:
+
+```tsx
+// ListBoxItem render prop with interaction state
+<ListBoxItem>
+  {({ isSelected, isHovered, isDisabled }) => (
+    <div className={`item ${isSelected ? 'selected' : ''}`}>
+      {isHovered && '👆 '}
+      My Item
+      {isSelected && ' ✓'}
+    </div>
+  )}
+</ListBoxItem>
+```
+
+For ListBox-level render props, use the `renderEmptyState` prop to customize empty state display:
+
+```tsx
+<ListBox
+  items={items}
+  renderEmptyState={({ isEmpty, isFocused, state, items }) => (
+    <div className="empty-state">
+      {isFocused ? 'No items found (focused)' : 'No items available'}
+    </div>
+  )}
+>
+  {(item: any) => (
+    <ListBoxItem key={item.id} textValue={item.name}>
+      {item.name}
+    </ListBoxItem>
+  )}
+</ListBox>
+```
+
+### Empty State Customization
+
+Customize the appearance when no items are present:
+
+```tsx
+<ListBox
+  renderEmptyState={({ isEmpty, isFocused }) => (
+    <div className="empty-state">
+      <span>📭</span>
+      <p>No items to display</p>
+      {isFocused && <p>Start typing to search...</p>}
+    </div>
+  )}
+>
+  {/* Items when present */}
+</ListBox>
+```
+
+### Accessibility Customization
+
+All components support standard ARIA attributes for enhanced accessibility:
+
+```tsx
+<ListBox
+  aria-label="Food menu"
+  aria-describedby="menu-description"
+>
+  <ListBoxSection aria-label="Main courses">
+    <Header>Main Dishes</Header>
+    <ListBoxItem aria-label="Chicken teriyaki with rice">
+      Chicken Teriyaki
+    </ListBoxItem>
+  </ListBoxSection>
+</ListBox>
+```
+
+### CSS-in-JS and Styled Components
+
+The data attributes work seamlessly with CSS-in-JS libraries:
+
+```tsx
+// Styled Components
+const StyledListBox = styled.div`
+  &[data-focused] {
+    box-shadow: 0 0 0 2px blue;
+  }
+
+  [role="option"][data-selected] {
+    background: ${props => props.theme.primary};
+  }
+`;
+
+// Emotion
+const listboxStyles = css`
+  &[data-empty] {
+    opacity: 0.5;
+  }
+`;
+```
+
+### Animation and Transitions
+
+Data attributes enable smooth state transitions:
+
+```css
+[role="option"] {
+  transition: all 0.2s ease-in-out;
+  transform: translateY(0);
+}
+
+[role="option"][data-hovered] {
+  transform: translateY(-2px);
+  box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1);
+}
+
+[role="option"][data-pressed] {
+  transform: translateY(0);
+  transition-duration: 0.1s;
+}
+```

package/README.mdx

@@ -57,7 +57,7 @@ When you provide an `items` prop, the `children` function receives **individual
 
 In this pattern, `children` is called for each item in the `items` array, receiving the individual item data to render `ListBoxItem` components.
 
-### When no `items` prop is provided  
+### When no `items` prop is provided
 When you don't provide an `items` prop but use `children` as a function, it follows **Bento's render prop pattern** and receives an object with render props:
 
 ```tsx
@@ -86,42 +86,50 @@ The ListBox components provide extensive customization options through data attr
 
 ### Styling with Data Attributes
 
-All ListBox components expose their internal state through `data-` attributes, enabling CSS-based styling without JavaScript. This follows Bento's design philosophy of returning styling control to CSS.
+All ListBox components expose their internal state through data attributes,
+enabling CSS-based styling without JavaScript. This follows Bento's design
+philosophy of returning styling control to CSS.
 
 #### ListBox Container Attributes
 
 The main `ListBox` component exposes these data attributes:
 
-- `[data-empty]` - Applied when the listbox contains no items
-- `[data-focused]` - Applied when the listbox is focused
-- `[data-focus-visible]` - Applied when the listbox has keyboard focus
-- `[data-layout="stack"]` - The layout type (currently only "stack" supported)
-- `[data-orientation="vertical|horizontal"]` - The primary orientation
-- `[data-selection-mode="none|single|multiple"]` - The selection mode
-- `[data-selection-behavior="toggle|replace"]` - How selection behaves
-- `[data-allows-tab-navigation]` - Whether tab navigation is enabled
-- `[data-focus-wrap]` - Whether focus wraps around the collection
+| Attribute                    | Description                                       | Example Values                |
+| ---------------------------- | ------------------------------------------------- | ----------------------------- |
+| `data-empty`                 | Applied when the listbox contains no items        | "true"                        |
+| `data-focused`               | Applied when the listbox is focused               | "true"                        |
+| `data-focus-visible`         | Applied when the listbox has keyboard focus       | "true"                        |
+| `data-layout`                | The layout type                                   | "stack"                       |
+| `data-orientation`           | The primary orientation                           | "vertical" / "horizontal"     |
+| `data-selection-mode`        | The selection mode                                | "none" / "single" / "multiple"|
+| `data-selection-behavior`    | How selection behaves                             | "toggle" / "replace"          |
+| `data-allows-tab-navigation` | Whether tab navigation is enabled                 | "true"                        |
+| `data-focus-wrap`            | Whether focus wraps around the collection         | "true"                        |
 
 #### ListBoxItem Attributes
 
 Individual `ListBoxItem` components expose these data attributes:
 
-- `[data-selected]` - Applied when the item is selected
-- `[data-disabled]` - Applied when the item is disabled
-- `[data-hovered]` - Applied when the item is being hovered
-- `[data-focused]` - Applied when the item is focused
-- `[data-focus-visible]` - Applied when the item has keyboard focus
-- `[data-pressed]` - Applied when the item is being pressed
-- `[data-level]` - The nesting level (useful for indentation)
-- `[data-selection-mode]` - Inherited selection mode
-- `[data-selection-behavior]` - Inherited selection behavior
-- `[data-text-value]` - The computed text value for the item
+| Attribute                | Description                                | Example Values                |
+| ------------------------ | ------------------------------------------ | ----------------------------- |
+| `data-selected`          | Applied when the item is selected          | "true"                        |
+| `data-disabled`          | Applied when the item is disabled          | "true"                        |
+| `data-hovered`           | Applied when the item is being hovered     | "true"                        |
+| `data-focused`           | Applied when the item is focused           | "true"                        |
+| `data-focus-visible`     | Applied when the item has keyboard focus   | "true"                        |
+| `data-pressed`           | Applied when the item is being pressed     | "true"                        |
+| `data-level`             | The nesting level (useful for indentation) | "0" / "1" / "2"               |
+| `data-selection-mode`    | Inherited selection mode                   | "none" / "single" / "multiple"|
+| `data-selection-behavior`| Inherited selection behavior               | "toggle" / "replace"          |
+| `data-text-value`        | The computed text value for the item       | "Item text"                   |
 
 #### ListBoxSection Attributes
 
 The `ListBoxSection` component exposes:
 
-- `[data-level]` - The nesting level of the section
+| Attribute    | Description                      | Example Values  |
+| ------------ | -------------------------------- | --------------- |
+| `data-level` | The nesting level of the section | "0" / "1" / "2" |
 
 #### CSS Styling Examples
 
@@ -199,12 +207,12 @@ const slots = {
   'my-listbox.fruits.header': ({ original, props }) => (
     <Header {...props}>🍎 {original}</Header>
   ),
-  
+
   // Override a specific item in a specific section
   'my-listbox.fruits.apple': ({ original }) => (
     <div className="special-item">⭐ {original}</div>
   ),
-  
+
   // Override an entire section
   'my-listbox.vegetables': ({ original }) => (
     <div className="veggie-section">{original}</div>
@@ -283,7 +291,7 @@ Customize the appearance when no items are present:
 All components support standard ARIA attributes for enhanced accessibility:
 
 ```tsx
-<ListBox 
+<ListBox
   aria-label="Food menu"
   aria-describedby="menu-description"
 >
@@ -306,7 +314,7 @@ const StyledListBox = styled.div`
   &[data-focused] {
     box-shadow: 0 0 0 2px blue;
   }
-  
+
   [role="option"][data-selected] {
     background: ${props => props.theme.primary};
   }