npm package: @ordojs/css-frameworks
Description: CSS framework integration system for OrdoJS - Tailwind CSS, Bootstrap, Bulma, Foundation support
Author: OrdoJS Team
Latest version: 0.1.0

# @ordojs/css-frameworks

Comprehensive CSS framework integration system for OrdoJS applications. Provides seamless
integration with popular CSS frameworks including Tailwind CSS, Bootstrap, Bulma, and Foundation,
along with advanced optimization features.

## Features

- 🎨 **Multi-Framework Support**: Tailwind CSS, Bootstrap, Bulma, Foundation, and custom frameworks
- ⚡ **JIT Compilation**: Just-in-time compilation with hot reload support for Tailwind CSS
- 🗜️ **Advanced Optimization**: CSS minification, unused class removal, and critical CSS extraction
- 📱 **Responsive Design**: Built-in responsive utilities and breakpoint management
- 🌙 **Dark Mode**: Automatic dark mode support and theme switching
- 🔧 **TypeScript**: Full TypeScript support with comprehensive type definitions
- 📊 **Performance Monitoring**: Built-in performance metrics and optimization suggestions
- 🔄 **Hot Reload**: Development server integration with instant CSS updates

## Installation

```bash
# Install the package
pnpm add @ordojs/css-frameworks

# Install peer dependencies for Tailwind CSS
pnpm add tailwindcss @tailwindcss/forms @tailwindcss/typography autoprefixer postcss

# Or for Bootstrap
pnpm add bootstrap @popperjs/core sass
```

## Quick Start

### Tailwind CSS Integration

```typescript
import { createCSSFrameworkManager } from '@ordojs/css-frameworks';

// Initialize Tailwind CSS
const manager = await createCSSFrameworkManager({
  framework: 'tailwind',
  optimization: {
    contentPaths: ['./src/**/*.{js,ts,jsx,tsx,ordo}'],
    removeUnusedClasses: true,
    minify: true,
  },
});

// Compile CSS
const result = await manager.compile(`
  @tailwind base;
  @tailwind components;
  @tailwind utilities;
`);

console.log(result.css);
```

### Bootstrap Integration

```typescript
import { createCSSFrameworkManager } from '@ordojs/css-frameworks';

// Initialize Bootstrap
const manager = await createCSSFrameworkManager({
  framework: 'bootstrap',
  config: {
    theme: {
      colors: {
        primary: '#007bff',
        secondary: '#6c757d',
      },
    },
  },
});

// Compile with custom styles
const result = await manager.compile(`
  .my-component {
    @extend .btn-primary;
    border-radius: 0.5rem;
  }
`);
```

## Framework-Specific Usage

### Tailwind CSS

#### Basic Configuration

```typescript
import { TailwindCSSAdapter } from '@ordojs/css-frameworks';

const adapter = new TailwindCSSAdapter();

await adapter.initialize({
  framework: 'tailwind',
  optimization: {
    contentPaths: ['./src/**/*.ordo'],
    removeUnusedClasses: true,
    minify: true,
    generateSourceMaps: true,
  },
});

// Generate configuration files
await adapter.generateConfig('./config');
```

#### Advanced Tailwind Configuration

```typescript
const manager = await createCSSFrameworkManager({
  framework: 'tailwind',
  config: {
    theme: {
      extend: {
        colors: {
          brand: {
            50: '#eff6ff',
            500: '#3b82f6',
            900: '#1e3a8a',
          },
        },
        fontFamily: {
          sans: ['Inter', 'system-ui', 'sans-serif'],
        },
      },
    },
    plugins: ['@tailwindcss/forms', '@tailwindcss/typography'],
  },
  optimization: {
    criticalCSS: true,
    codeSplitting: {
      enabled: true,
      strategy: 'route',
    },
  },
});
```

### Bootstrap

#### Theme Customization

```typescript
import { BootstrapCSSAdapter } from '@ordojs/css-frameworks';

const adapter = new BootstrapCSSAdapter();

await adapter.initialize({
  framework: 'bootstrap',
  config: {
    theme: {
      colors: {
        primary: '#6366f1',
        secondary: '#64748b',
      },
      fonts: {
        primary: 'Inter, sans-serif',
      },
    },
    customVariables: {
      'border-radius': '0.5rem',
      'box-shadow': '0 4px 6px -1px rgba(0, 0, 0, 0.1)',
    },
  },
});
```

## CSS Optimization

### Advanced Optimization Features

```typescript
import { CSSOptimizer } from '@ordojs/css-frameworks';

const optimizer = new CSSOptimizer({
  removeUnusedClasses: true,
  minify: true,
  criticalCSS: true,
  contentPaths: ['./src/**/*.{html,js,ts,ordo}'],
  codeSplitting: {
    enabled: true,
    chunkSize: 50000,
    strategy: 'component',
  },
});

const result = await optimizer.optimize(cssContent);

console.log(`
  Original size: ${result.stats.originalSize} bytes
  Optimized size: ${result.stats.optimizedSize} bytes
  Compression ratio: ${(result.stats.compressionRatio * 100).toFixed(1)}%
  Removed rules: ${result.stats.removedRules}
`);
```

### Critical CSS Extraction

```typescript
const { critical, remaining } = await optimizer.extractCriticalCSS(css, {
  html: ['./src/index.html', './src/pages/*.html'],
  dimensions: [
    { width: 1200, height: 900 },
    { width: 768, height: 1024 },
  ],
  include: ['.hero', '.navbar'],
  exclude: ['.modal', '.tooltip'],
});

// Inline critical CSS, defer remaining CSS
```

## Hot Reload and Development

### Development Server Integration

```typescript
const manager = await createCSSFrameworkManager({
  framework: 'tailwind',
  development: {
    hotReload: true,
    sourceComments: true,
    verbose: true,
  },
});

// Listen for hot reload events
manager.onHotReload((event, data) => {
  if (event === 'css-update') {
    console.log(`CSS updated: ${data.file}`);
    // Trigger browser reload or CSS injection
  }
});
```

## CLI Integration

This package integrates seamlessly with the OrdoJS CLI:

```bash
# Initialize Tailwind CSS
ordojs css-framework tailwind --output ./styles --content "./src/**/*.ordo"

# Bootstrap with custom configuration
ordojs css-framework bootstrap --output ./styles --source-maps

# Custom framework
ordojs css-framework custom --css-file ./custom.css --output ./dist
```

## Performance Monitoring

### Built-in Performance Metrics

```typescript
const manager = await createCSSFrameworkManager(options);

// Compile CSS
await manager.compile(cssInput);

// Get performance metrics
const suggestions = await manager.getOptimizationSuggestions('./project');
console.log('Optimization suggestions:', suggestions);

// Validate compatibility
const { valid, issues } = await manager.validateCompatibility('tailwind', './project');
if (!valid) {
  console.warn('Compatibility issues:', issues);
}
```

## Framework Detection

### Automatic Framework Detection

```typescript
const detection = await manager.detectFrameworks('./project');

console.log({
  frameworks: detection.frameworks,
  confidence: detection.confidence,
  configFiles: detection.configFiles,
  conflicts: detection.conflicts,
});
```

## TypeScript Support

The package includes comprehensive TypeScript definitions:

```typescript
import type {
  CSSFramework,
  CSSFrameworkOptions,
  CSSCompilationResult,
  CSSOptimizationOptions,
  TailwindConfig,
  BootstrapConfig,
} from '@ordojs/css-frameworks';

// Full type safety for all configuration options
const options: CSSFrameworkOptions = {
  framework: 'tailwind',
  optimization: {
    removeUnusedClasses: true,
    minify: true,
    generateSourceMaps: true,
  },
};
```

## API Reference

### Core Classes

- **`CSSFrameworkIntegrationManager`**: Main integration manager
- **`TailwindCSSAdapter`**: Tailwind CSS specific adapter
- **`BootstrapCSSAdapter`**: Bootstrap specific adapter
- **`CSSOptimizer`**: Advanced CSS optimization engine

### Utility Functions

- **`createCSSFrameworkManager(options)`**: Quick setup factory
- **`compileTailwindCSS(input, options)`**: Direct Tailwind compilation

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite: `pnpm test`
6. Submit a pull request

## License

MIT © OrdoJS Team

## Changelog

### v0.1.0

- Initial release with Tailwind CSS and Bootstrap support
- Advanced CSS optimization engine
- Hot reload development integration
- Comprehensive TypeScript definitions
- CLI integration with OrdoJS

---

For more information, visit the [OrdoJS documentation](https://ordojs.com/docs/css-frameworks).