preact-combobox/CLAUDE.md

Preact Multi-select Combo Box component

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is **preact-combobox**, a Preact multi-select/single-select combobox component. The project provides a flexible, accessible autocomplete component with support for:

- Multi-select and single-select modes
- Async/lazy-loaded options
- Internationalization and RTL support
- Custom rendering and theming
- Form submission compatibility
- Mobile-responsive tray interface

## Architecture

### Core Files Structure
- `lib/PreactCombobox.jsx` - Main component implementation with comprehensive TypeScript-style JSDoc types
- `lib/PreactCombobox.css` - Component styles with CSS custom properties for theming
- `lib/hooks.js` - Custom hooks including `useDeepMemo` for deep equality comparison and `useLive` for state management
- `lib/PreactCombobox.d.ts` - TypeScript declarations (generated)
- `example/` - Demo files for testing and development

### Key Architecture Patterns
- **State Management**: Uses custom `useLive` hook for efficient state updates without re-renders
- **Deep Comparison**: `useDeepMemo` hook prevents unnecessary re-computations using deep equality
- **Lazy Loading**: Supports async option loading via function-based `allowedOptions` prop
- **Internationalization**: Built-in support for multiple languages with `Intl.Segmenter` and `Intl.Collator`
- **Accessibility**: Implements ARIA patterns, keyboard navigation, and screen reader support
- **Portal Rendering**: Uses Preact's `createPortal` for dropdown positioning
- **Popper Integration**: Uses `@popperjs/core` for dropdown positioning and collision detection

### Component Props Architecture
The component accepts 25+ props with comprehensive TypeScript definitions, including:
- Core functionality: `allowedOptions`, `value`, `onChange`, `multiple`
- Customization: `optionRenderer`, `optionIconRenderer`, custom icons
- Internationalization: `language`, `translations`
- Accessibility: ARIA labels, form compatibility
- Theming: `theme`, CSS custom properties

## Common Development Commands

### Development Workflow
```bash
# Start development server with live reload and example page
npm run dev
# Opens http://localhost:3050/example/example.html

# Build for production (both ESM and CJS formats)
npm run build

# Run linting and auto-fix issues
npm run lint

# Type checking
npm run tsc
```

### Build Process
The build process uses esbuild to create:
- ESM build in `dist/esm/` with Preact externalized
- CJS build in `dist/cjs/` with React externalized (for compatibility)
- TypeScript declarations copied to both output directories

### Testing and Example
- Use `npm run example` to serve just the example without file watching
- Example files demonstrate all major features including async loading, custom rendering, and mobile tray

## Development Notes

### Mobile Tray Feature
The project includes a mobile-responsive tray interface with specific design requirements:
- Height: `clamp(200px, calc(100dvh - 50px), 480px)`
- 200px minimum for usability
- 480px max (3-4 inch comfort zone)
- 50px padding for tap-outside-to-close functionality

### Code Quality Tools
- **Biome**: Used for linting, formatting, and import organization
- **TypeScript**: Strict type checking with JSDoc annotations
- **Husky**: Git hooks for pre-commit validation

### Key Implementation Details
- Component uses JSX with `h` factory function for Preact compatibility
- Extensive use of `useCallback` and `useMemo` for performance optimization
- Custom equality checking prevents unnecessary re-renders
- Support for both function-based and array-based option loading
- Comprehensive accessibility implementation with ARIA patterns

### Future Roadmap (from TODO.md)
Priority items include documentation improvements and mobile tray enhancements. Nice-to-have features include disabled options, grouped options, and performance improvements.