npm package: @foundrykit/blocks
Description: A collection of pre-built page sections and content blocks for rapid website development. These blocks provide complete, customizable sections that can be easily integrated into any page layout.
Latest version: 1.0.25

# @foundrykit/blocks

A collection of pre-built page sections and content blocks for rapid website
development. These blocks provide complete, customizable sections that can be
easily integrated into any page layout.

## Features

- **Complete page sections** - Ready-to-use blocks for common page layouts
- **Highly customizable** - Easy to modify content, styling, and behavior
- **Responsive design** - Mobile-first responsive layouts
- **Accessible** - Built with accessibility best practices
- **TypeScript support** - Full type safety for all block props
- **SEO optimized** - Proper semantic HTML and meta tags

## Installation

```bash
pnpm add @foundrykit/blocks
```

## Available Blocks

### Hero Sections

- **HeroMinimal** - Clean, minimal hero section with title and CTA
- **HeroWithImage** - Hero section with background image
- **HeroWithVideo** - Hero section with video background

### Content Sections

- **Testimonials** - Customer testimonial carousel
- **Pricing** - Pricing table with multiple tiers
- **Features** - Feature showcase with icons and descriptions
- **FAQ** - Frequently asked questions accordion

### Marketing Sections

- **Newsletter** - Email newsletter signup form
- **CTA** - Call-to-action section
- **SocialProof** - Social proof with logos and stats

## Usage

### Basic Example

```tsx
import { HeroMinimal, Testimonials, Pricing } from '@foundrykit/blocks';

function HomePage() {
  return (
    <div>
      <HeroMinimal
        title='Build amazing websites'
        subtitle='Create beautiful, responsive websites with our component library'
        ctaText='Get Started'
        ctaHref='/signup'
      />

      <Testimonials
        testimonials={[
          {
            name: 'John Doe',
            role: 'CEO',
            company: 'Tech Corp',
            content:
              'Amazing product that saved us months of development time.',
          },
        ]}
      />

      <Pricing
        plans={[
          {
            name: 'Starter',
            price: '$9',
            features: ['Feature 1', 'Feature 2'],
          },
        ]}
      />
    </div>
  );
}
```

### Customizing Blocks

```tsx
import { HeroMinimal } from '@foundrykit/blocks';

function CustomHero() {
  return (
    <HeroMinimal
      title='Custom Title'
      subtitle='Custom subtitle text'
      ctaText='Custom Button'
      ctaHref='/custom-link'
      className='bg-gradient-to-r from-blue-500 to-purple-600'
      titleClassName='text-4xl font-bold text-white'
      subtitleClassName='text-xl text-gray-200'
    />
  );
}
```

### Block Configuration

Each block can be configured through its config file:

```tsx
import { Testimonials } from '@foundrykit/blocks'

// Use default configuration
<Testimonials testimonials={data} />

// Override with custom configuration
<Testimonials
  testimonials={data}
  autoPlay={false}
  showDots={true}
  className="my-custom-styles"
/>
```

## Block Structure

Each block is organized as follows:

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

## Content Management

### Dynamic Content

Blocks support dynamic content through props:

```tsx
import { Testimonials } from '@foundrykit/blocks';

function DynamicTestimonials({ testimonials }) {
  return (
    <Testimonials
      testimonials={testimonials}
      title='What our customers say'
      subtitle='Real feedback from real users'
    />
  );
}
```

### CMS Integration

Blocks are designed to work with headless CMS systems:

```tsx
import { HeroMinimal } from '@foundrykit/blocks';

function CMSHero({ cmsData }) {
  return (
    <HeroMinimal
      title={cmsData.title}
      subtitle={cmsData.subtitle}
      ctaText={cmsData.ctaText}
      ctaHref={cmsData.ctaLink}
      backgroundImage={cmsData.backgroundImage}
    />
  );
}
```

## Styling and Theming

### Theme Integration

Blocks automatically use your theme tokens:

```tsx
import { Pricing } from '@foundrykit/blocks';

// Automatically uses theme colors and spacing
<Pricing plans={plans} className='bg-background text-foreground' />;
```

### Custom Styling

Override default styles with custom classes:

```tsx
import { Testimonials } from '@foundrykit/blocks';
import { cn } from '@foundrykit/utils';

function StyledTestimonials({ className, ...props }) {
  return (
    <Testimonials
      className={cn(
        'bg-gradient-to-br from-blue-50 to-indigo-100',
        'rounded-xl border border-blue-200',
        className
      )}
      {...props}
    />
  );
}
```

## Responsive Design

All blocks are mobile-first and responsive:

```tsx
import { HeroMinimal } from '@foundrykit/blocks';

// Automatically responsive
<HeroMinimal
  title='Responsive Title'
  subtitle='This block looks great on all devices'
  className='
    px-4 py-8
    text-center md:px-8 md:py-12
    md:text-left lg:px-16 lg:py-20
  '
/>;
```

## Accessibility

Blocks include comprehensive accessibility features:

- Semantic HTML structure
- Proper ARIA attributes
- Keyboard navigation support
- Screen reader compatibility
- Color contrast compliance
- Focus management

## Performance

### Optimized Rendering

- Lazy loading for images and videos
- Optimized bundle sizes
- Efficient re-rendering
- Minimal JavaScript overhead

### SEO Optimization

- Proper heading hierarchy
- Meta tag support
- Structured data markup
- Fast loading times

## Dependencies

- **@foundrykit/primitives** - Base UI components
- **@foundrykit/components** - Higher-level components
- **@foundrykit/animation** - Animation utilities
- **React** - UI framework
- **TypeScript** - Type safety

## Contributing

When adding new blocks:

1. Follow the established block structure
2. Ensure mobile-first responsive design
3. Include comprehensive accessibility features
4. Add TypeScript definitions
5. Provide usage examples
6. Test across different screen sizes
7. Update this README

## License

MIT