@hanamura/rcgen/README.md

Generate optimized React container components from configuration

# React Containers Static Generator

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

## Overview

This tool 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
- **Zero Runtime Overhead**: All responsive behavior happens entirely in CSS
- **Framework Agnostic**: Works with any React-based framework

## Installation

```bash
# Install the generator (not yet published)
npm install @hanamura/rcgen

# Or clone this repository and build it locally
git clone https://github.com/hanamura/react-containers.git
cd react-containers/static-generator
npm install
npm run build
```

## Usage

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

# Use the --force flag to overwrite existing files
npx rcgen --config ./config.json --output ./src/generated --force

# Use the --verbose flag for detailed output
npx rcgen --config ./config.json --verbose
```

## 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", "Panorama"],
  "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 | Key Options |
|-----------|-------------|-------------------|-------------|
| Stack | Vertical layout | Flexbox with column direction | gap, direction |
| Tile | Grid layout | CSS Grid with configurable columns | columns, gap |
| Cluster | Wrapped flex layout | Flexbox with wrap | gap, align, justify |
| Reel | Horizontal scroll | CSS scroll snap with overflow | gap, snap |
| Switcher | Content switching | CSS-based display switching | threshold, gap |
| Panorama | Full-width container | 100vw width and negative margins | indent |

## Generated Output Structure

The generator creates the following directory structure:

```
output-dir/
├── core/
│   ├── index.ts   - Exports all utilities and types
│   ├── types.ts   - Type definitions
│   └── utils.ts   - Utility functions
└── components/
    ├── Stack.tsx
    ├── Stack.module.css
    ├── Tile.tsx
    ├── Tile.module.css
    └── ... other components
```

## Using the Generated Components

```tsx
import { Stack, Tile, spacing } from './generated';

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

- Support for custom component templates
- Plugin system for extending with custom behaviors
- Visual editor for configuration
- Integration with popular frameworks (Next.js, Gatsby, etc.)
- Additional container component types

## License

MIT