boxbrew/README.md

Generate optimized React container components from configuration

# 📦 Boxbrew

A tool for generating optimized React container components with static CSS from configuration files.

## 🔎 Overview

Boxbrew generates responsive React container components based on a simple JSON configuration file. It produces code optimized for Server-Side Rendering with no layout flash issues.

Generated files include:

1. React component files (`.tsx`)
2. CSS Module files (`.module.css`) with media queries
3. TypeScript type definitions
4. Core utility files

## ✨ Benefits

- **🚀 SSR Compatible**: No more layout flash issues with server-side rendering
- **⚡ Performance**: Static CSS is more performant than runtime matchMedia evaluations
- **🎨 CSS Variables Based**: Uses CSS variables and media queries instead of JavaScript
- **🛡️ Type Safety**: Strong TypeScript typings for all components and options
- **🪶 Minimal Runtime Overhead**: Most responsive behavior happens in CSS, with limited JavaScript for specific components like Switcher
- **🔌 Framework Agnostic**: Works with any React-based framework

## 🧩 How Boxbrew Works

Unlike typical React component libraries that you import and use at runtime, Boxbrew is a **code generator**. It creates static component files that you add directly to your project's source code:

1. You define a configuration file with your desired responsive breakpoints and spacing values
2. Boxbrew generates optimized React components and CSS modules based on this configuration
3. You add these generated files to your project's source code (and can commit them to your repository)
4. You import and use these components like any other React component in your project

This approach gives you:

- 🔧 Complete control over the generated code
- 🚄 Better performance since the components are optimized for your specific configuration
- 🔗 No runtime dependencies on Boxbrew itself

### 🤔 Why Static Generation?

Traditional responsive React components often use `matchMedia` or other runtime JavaScript to adapt to different viewport sizes, which creates several problems:

1. **Layout Flash**: Components may initially render with default styles before JavaScript adapts them to the correct breakpoint
2. **SSR Incompatibility**: Server-side rendering environments cannot evaluate `matchMedia` queries, leading to hydration mismatches
3. **Runtime Overhead**: Evaluating media queries in JavaScript adds unnecessary processing
4. **Maintenance Complexity**: Developers need to maintain both TypeScript configurations and runtime component logic

Boxbrew solves these issues by generating static components that use pure CSS for responsive behavior.

## 📥 Installation

```bash
# Install the generator globally or as a dev dependency
npm install -g boxbrew
# or
npm install --save-dev boxbrew
```

## 📋 Usage

```bash
# Generate components based on your configuration
npx boxbrew --config ./config.json --output ./src/components/boxbrew

# Use the --force flag to overwrite existing files (useful for regenerating after config changes)
npx boxbrew --config ./config.json --output ./src/components/boxbrew --force

```

Once generated, you can commit these files to your project repository and use them like any other React component.

## ⚙️ Configuration Format

The configuration file uses a JSON format that defines your queries (breakpoints), spacing values, and container components to generate:

```json
{
  "queries": [
    { "name": "vp_sm", "query": "(min-width: 0px)" },
    { "name": "vp_md", "query": "(min-width: 640px)" },
    { "name": "vp_lg", "query": "(min-width: 1024px)" }
  ],
  "spacing": [
    { "name": "sp_sm", "value": "var(--spacing-sm)" },
    { "name": "sp_md", "value": "var(--spacing-md)" },
    { "name": "sp_lg", "value": "var(--spacing-lg)" }
  ],
  "containers": ["Stack", "Tile", "Cluster", "Reel", "Switcher"],
  "variablePrefix": "rcg"
}
```

### Configuration Properties

- **queries**: Array of query objects with `name` and `query` (CSS media query) properties
- **spacing**: Array of spacing objects with `name` and `value` (CSS value) properties
- **containers**: Array of container component names to generate
- **variablePrefix** (optional): Prefix for CSS variables to avoid naming collisions

## 🧰 Available Containers

The system includes these built-in container components:

| Component | Description         | CSS Implementation                 |
| --------- | ------------------- | ---------------------------------- |
| Stack     | Vertical layout     | Flexbox with column direction      |
| Tile      | Grid layout         | CSS Grid with configurable columns |
| Cluster   | Wrapped flex layout | Flexbox with wrap                  |
| Reel      | Horizontal scroll   | CSS scroll snap with overflow      |
| Switcher  | Content switching   | CSS display with JS media queries  |

## 📂 Generated Output Structure

The generator creates the following directory structure in your specified output directory:

```
src/components/boxbrew/            # Your specified output directory
├── index.ts                       - Exports all components and utilities
├── types.ts                       - Type definitions
├── utils.ts                       - Utility functions
├── useMediaQueries.ts             - Hook for media query detection (used by some components)
└── components/
    ├── Stack.tsx
    ├── Stack.module.css
    ├── Tile.tsx
    ├── Tile.module.css
    └── ... other components
```

## 💻 Using the Generated Components

```tsx
import { Stack, Tile, spacing } from '@/components/boxbrew'

function App() {
  return (
    <Stack
      options={{ gap: spacing.sp_md }}
      adaptiveOptions={{
        vp_sm: { gap: spacing.sp_sm },
        vp_lg: { gap: spacing.sp_lg },
      }}
    >
      <Tile
        options={{ columns: 1 }}
        adaptiveOptions={{
          vp_md: { columns: 2 },
          vp_lg: { columns: 3 },
        }}
      >
        {/* Content */}
      </Tile>
    </Stack>
  )
}
```

## 🗺️ Roadmap

- 🌐 Add Panorama component (not yet implemented)
- 🧪 Implement test auto-generation

Boxbrew is designed to be a minimal, focused tool that solves a specific problem well, rather than expanding with plugins or framework-specific templates.

## 📄 License

MIT