npm package: @hilemangroup/bp-email-base
Description: React based email components to reliably build HTML emails that work across major email clients.
Author: Ken Sugiura
Latest version: 4.0.0

# BP Email Base

> React-based email components to reliably build HTML emails that work across major email clients

This package provides a comprehensive set of React components specifically designed for building HTML emails that render consistently across all major email clients, including Outlook, Gmail, Apple Mail, and more. Built with TypeScript and optimized for email client compatibility.

## 🚀 Features

- **Cross-Client Compatibility**: Components are built using table-based layouts and inline styles to ensure consistent rendering across all email clients
- **React-Based**: Leverage the power of React for component composition and reusability
- **TypeScript Support**: Full TypeScript definitions for better development experience and type safety
- **Email-Specific Components**: Purpose-built components for common email patterns (containers, sections, columns, buttons, etc.)
- **VML Support**: Built-in support for Vector Markup Language (VML) for Outlook compatibility
- **Raw HTML Injection**: Safe raw HTML injection for complex email layouts
- **Responsive Design**: Mobile-friendly components that adapt to different screen sizes
- **MSO Support**: Microsoft Outlook-specific styling and conditional comments

## 📦 Installation

### Prerequisites

- [Node.js](https://nodejs.org/en/) (16.0 or greater)
- [npm](https://www.npmjs.com/) or [yarn](https://yarnpkg.com/)
- React 18.2.0 or greater (peer dependency)

### Install the Package

```bash
npm install @hilemangroup/bp-email-base
```

or

```bash
yarn add @hilemangroup/bp-email-base
```

## 🏗️ Core Components

### Layout Components

- **`Container`** - Main email container with configurable width and gutters
- **`Section`** - Full-width sections with background colors and padding
- **`Column`** - Flexible column layouts for responsive email design
- **`Wrap`** - Wrapper component for grouping content

### Content Components

- **`RichText`** - Styled text content with email-safe formatting
- **`ImageBlock`** - Responsive images with proper email client support
- **`Button`** - Email-safe buttons that work across all clients
- **`BackgroundSection`** - Sections with background images (with VML fallbacks)

### Utility Components

- **`Raw`** - Safe injection of raw HTML content
- **`ConditionalComment`** - Outlook-specific conditional comments
- **`Element`** - Generic HTML element wrapper with email-safe attributes

## 🎯 Usage

### Basic Email Structure

```tsx
import React from 'react';
import { Container, Section, Column, RichText, Button } from '@hilemangroup/bp-email-base';

const MyEmail = () => {
  return (
    <Container width="600px">
      <Section backgroundColor="#f8f9fa" padding="20px">
        <Column>
          <RichText>
            <h1>Welcome to Our Newsletter!</h1>
            <p>Thank you for subscribing to our updates.</p>
          </RichText>
          <Button href="https://example.com" backgroundColor="#007bff">
            Learn More
          </Button>
        </Column>
      </Section>
    </Container>
  );
};
```

### Multi-Column Layout

```tsx
import React from 'react';
import { Container, Section, Column, RichText, ImageBlock } from '@hilemangroup/bp-email-base';

const TwoColumnEmail = () => {
  return (
    <Container width="600px">
      <Section padding="20px">
        <Column width={6}>
          <ImageBlock 
            src="https://example.com/image1.jpg" 
            alt="Product Image"
            width="250"
          />
        </Column>
        <Column width={6}>
          <RichText>
            <h2>Our Latest Product</h2>
            <p>Discover amazing features and benefits.</p>
          </RichText>
        </Column>
      </Section>
    </Container>
  );
};
```

### Using Raw HTML

```tsx
import React from 'react';
import { Container, Raw } from '@hilemangroup/bp-email-base';

const CustomEmail = () => {
  return (
    <Container>
      <Raw text="<!--[if mso]><xml>Custom Outlook content</xml><![endif]-->" />
      {/* Your other components */}
    </Container>
  );
};
```

## 🛠️ Build Process

The package includes a build utility to process your React email components into email-ready HTML:

```tsx
import { replaceRawTags } from '@hilemangroup/bp-email-base';

// After rendering your React email to HTML string
const processedHtml = replaceRawTags(htmlString);
```

## 🎨 Styling

### CSS-in-JS Support

Components support both inline styles and CSS-in-JS patterns:

```tsx
<Section 
  style={{ backgroundColor: '#f0f0f0' }}
  padding="20px 10px"
>
  <RichText style={{ color: '#333', fontSize: '16px' }}>
    Styled content
  </RichText>
</Section>
```

### MSO-Specific Styles

The package includes TypeScript definitions for Microsoft Outlook-specific CSS properties:

```tsx
<div style={{
  'mso-line-height-rule': 'exactly',
  'mso-text-raise': '2px'
}}>
  Outlook-optimized content
</div>
```


## 🧪 Development

### Setting Up Development Environment

```bash
# Clone the repository
git clone <repository-url>
cd bp-email-base

# Install dependencies
npm install

# Start development server
npm start

# Build for production
npm run build
```

### Project Structure

```
src/
├── js/
│   ├── components/        # React email components
│   ├── util/             # Utility functions
│   ├── build/            # Build-time utilities
│   ├── constants/        # Email constants and aliases
│   ├── vml/              # VML type definitions
│   └── types.ts          # TypeScript type definitions
```

## 📚 API Reference

### Component Props

All components extend base `LayoutProps`:

```typescript
interface LayoutProps {
  children?: ReactNode;
  varName?: string;
  className?: string;
  innerClassName?: string;
  style?: CSSProperties;
  innerStyle?: CSSProperties;
}
```

### Utility Functions

- `replaceRawTags(html: string): string` - Remove raw HTML tags from processed email
- `getColumnInnerWidth(width: string, gutter: number): number` - Calculate inner column widths
- `cssModifier(base: string, modifier?: string): string` - Generate BEM-style class names
- `parseCssSideValues(value: CssSidesValues): object` - Parse CSS shorthand values

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.