npm package: @foundrykit/components
Description: A collection of pre-built, styled React components built on top of `@foundrykit/primitives`. These components provide ready-to-use UI elements with consistent styling and behavior.
Latest version: 1.0.23

# @foundrykit/components

A collection of pre-built, styled React components built on top of
`@foundrykit/primitives`. These components provide ready-to-use UI elements with
consistent styling and behavior.

## Features

- **Pre-styled components** - Ready-to-use with consistent design
- **Built on primitives** - Leverages `@foundrykit/primitives` for accessibility
- **TypeScript support** - Full type safety with comprehensive definitions
- **Customizable** - Easy to override styles and behavior
- **Consistent API** - Uniform component patterns across the library

## Installation

```bash
pnpm add @foundrykit/components
```

## Available Components

### Data Entry

- **Calendar** - Date picker calendar component
- **Date Picker** - Complete date selection interface
- **Search Bar** - Search input with suggestions and filters

### Navigation

- **Command** - Command palette interface for keyboard navigation
- **Pagination** - Page navigation with configurable page sizes

## Usage

### Basic Example

```tsx
import { Calendar } from '@foundrykit/components/calendar';
import { DatePicker } from '@foundrykit/components/date-picker';
import { SearchBar } from '@foundrykit/components/search-bar';

function MyApp() {
  return (
    <div>
      <SearchBar
        placeholder='Search...'
        onSearch={query => console.log(query)}
      />

      <DatePicker onDateSelect={date => console.log(date)} />

      <Calendar mode='single' onSelect={date => console.log(date)} />
    </div>
  );
}
```

### Component Configuration

Each component can be configured through its config file:

```tsx
import { Calendar } from '@foundrykit/components/calendar'

// Use default configuration
<Calendar />

// Override with custom configuration
<Calendar
  className="custom-calendar"
  disabled={false}
  mode="range"
/>
```

### Styling

Components come with default styling but can be customized:

```tsx
import { SearchBar } from '@foundrykit/components/search-bar';
import { cn } from '@foundrykit/utils';

function CustomSearchBar({ className, ...props }) {
  return (
    <SearchBar
      className={cn('rounded-lg border-2 border-blue-500', className)}
      {...props}
    />
  );
}
```

## Component Structure

Each component is organized as follows:

```
component/
├── config.ts          # Component configuration and variants
├── index.tsx          # Main component exports
├── variants-grid.tsx  # Component variants for documentation
└── README.md          # Component-specific documentation
```

## Dependencies

- **@foundrykit/primitives** - Base UI primitives
- **@foundrykit/types** - TypeScript type definitions
- **@foundrykit/utils** - Utility functions
- **React** - UI framework
- **date-fns** - Date manipulation utilities
- **cmdk** - Command palette functionality

## Integration with Primitives

Components are built on top of primitives for maximum flexibility:

```tsx
import { Calendar } from '@foundrykit/components/calendar'
import { Calendar as CalendarPrimitive } from '@foundrykit/primitives/calendar'

// Use the pre-styled component
<Calendar />

// Or use the primitive directly for custom styling
<CalendarPrimitive className="my-custom-styles" />
```

## Customization

### Theme Integration

Components work with your existing theme system:

```tsx
import { SearchBar } from '@foundrykit/components/search-bar';

// Components automatically use your theme tokens
<SearchBar className='bg-background text-foreground' />;
```

### Variant System

Many components support variants for different use cases:

```tsx
import { SearchBar } from '@foundrykit/components/search-bar'

<SearchBar variant="default" />
<SearchBar variant="outline" />
<SearchBar variant="ghost" />
```

## Accessibility

All components inherit accessibility features from their underlying primitives:

- Keyboard navigation
- Screen reader support
- Focus management
- ARIA attributes
- Color contrast compliance

## Contributing

When adding new components:

1. Build on existing primitives when possible
2. Follow the established component structure
3. Include comprehensive TypeScript definitions
4. Add usage examples and documentation
5. Ensure accessibility compliance
6. Update this README

## License

MIT