npm package: @metagptx/css-to-tailwind
Description: A utility library for converting CSS properties to Tailwind CSS classes
Author: caowenyue
Latest version: 0.0.4

# CSS to Tailwind Converter

A powerful utility library for bidirectional conversion between CSS properties and Tailwind CSS class names.

## Features

- 🔄 **Bidirectional Conversion**: CSS properties ↔ Tailwind class names
- 🎨 **Complete Color Support**: Supports OKLCH, RGB, HEX, and other color formats
- 📏 **Spacing Handling**: Automatic handling of margin, padding, and other spacing properties
- 🎯 **Type Safe**: Complete TypeScript type definitions
- 🚀 **Lightweight**: No external dependencies (except for Tailwind to CSS conversion)
- 🔧 **Extensible**: Supports custom configuration and extensions
- ⚙️ **Flexible Configuration**: Supports custom color mappings and style mappings

## Installation

```bash
npm install @metagptx/css-to-tailwind
```

## Usage

### CSS to Tailwind Conversion

```typescript
import { cssToTailwind } from '@metagptx/css-to-tailwind';

// Basic usage
const cssProps = {
  backgroundColor: '#3b82f6',
  color: '#ffffff',
  padding: '16px',
  margin: '8px',
  borderRadius: '8px',
  fontSize: '1rem',
  fontWeight: '600',
  textDecoration: 'underline',
  fontVariantNumeric: 'tabular-nums',
};

const tailwindClasses = cssToTailwind(cssProps);
console.log(tailwindClasses);
// Output: "bg-[#3b82f6] text-[#ffffff] p-[16px] m-[8px] rounded-[8px] text-base font-semibold underline tabular-nums"
```

### Using Custom Configuration

```typescript
import { cssToTailwind } from '@metagptx/css-to-tailwind';
import type { ConverterConfig } from '@metagptx/css-to-tailwind';

// Custom color mappings
const customConfig: ConverterConfig = {
  colorMaps: {
    background: {
      '#ff0000': 'bg-red-custom',
      '#00ff00': 'bg-green-custom',
      '#3b82f6': 'bg-blue-500', // Override default mapping
    },
    text: {
      '#ffffff': 'text-white-custom',
      '#000000': 'text-black-custom',
    },
  },
  styleMaps: {
    fontSize: {
      '1rem': 'text-custom-base',
      '2rem': 'text-custom-xl',
    },
    fontWeight: {
      '600': 'font-custom-semibold',
      '700': 'font-custom-bold',
    },
    textAlign: {
      center: 'text-custom-center',
      left: 'text-custom-left',
    },
    display: {
      flex: 'flex-custom',
      block: 'block-custom',
    },
    position: {
      relative: 'relative-custom',
      absolute: 'absolute-custom',
    },
    borderRadius: {
      '8px': 'rounded-custom',
    },
    fontFamily: {
      'ui-sans-serif': 'font-custom-sans',
    },
  },
};

const cssProps = {
  backgroundColor: '#ff0000',
  color: '#ffffff',
  fontSize: '1rem',
  fontWeight: '600',
  textAlign: 'center',
  textDecoration: 'underline',
  display: 'flex',
  position: 'relative',
};

const tailwindClasses = cssToTailwind(cssProps, customConfig);
console.log(tailwindClasses);
// Output: "bg-red-custom text-white-custom text-custom-base font-custom-semibold text-custom-center underline-custom flex-custom relative-custom"
```

### Validating Tailwind Classes

```typescript
import { validateTailwindClasses } from '@metagptx/css-to-tailwind';

const classes = 'bg-blue-500 text-white invalid-class';
const validation = validateTailwindClasses(classes);

console.log(validation);
// Output: {
//   isValid: false,
//   invalidClasses: ['invalid-class']
// }
```

### Color Conversion Utilities

```typescript
import { oklchToHex, rgbToHex } from '@metagptx/css-to-tailwind';

// OKLCH to HEX
const hexColor = oklchToHex('oklch(0.637 0.237 25.331)');
console.log(hexColor); // "#ef4444"

// RGB to HEX
const hexFromRgb = rgbToHex('rgb(239, 68, 68)');
console.log(hexFromRgb); // "#ef4444"
```

## API Reference

### cssToTailwind(cssProps, config?)

Converts a CSS properties object to a Tailwind class name string.

**Parameters:**
- `cssProps`: CSS properties object, supports the following properties:
  - `backgroundColor`: Background color
  - `color`: Text color
  - `margin`, `marginTop`, `marginRight`, `marginBottom`, `marginLeft`, `marginX`, `marginY`: Margins
  - `padding`, `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft`, `paddingX`, `paddingY`: Padding
  - `borderRadius`: Border radius
  - `fontSize`, `fontWeight`, `fontFamily`, `textAlign`, `textDecoration`, `fontVariantNumeric`: Font-related properties
  - `width`, `height`: Dimensions
  - `display`, `flexDirection`, `justifyContent`, `alignItems`, `gap`: Layout properties
  - `position`: Positioning
  - `opacity`: Opacity
  - `className`: Custom class names
- `config?`: Optional converter configuration object

**Returns:** `string` - Tailwind class name string

### validateTailwindClasses(classes)

Validates whether Tailwind class names are valid.

**Parameters:**
- `classes`: `string` - Class name string to validate

**Returns:** `ValidationResult` - Validation result object

### Utility Functions

- `oklchToHex(oklchString)`: Converts OKLCH color to HEX
- `rgbToHex(color)`: Converts RGB color to HEX
- `parseColorsConfig(config)`: Parses color configuration
- `getSpacingClass(type, value)`: Generates spacing class names

## Configuration Types

### ConverterConfig

```typescript
interface ConverterConfig {
  colorMaps?: ColorMapsConfig;
  styleMaps?: StyleMapsConfig;
}
```

### ColorMapsConfig

```typescript
interface ColorMapsConfig {
  background: Record<string, string>; // Color value -> Background class name
  text: Record<string, string>;       // Color value -> Text class name
}
```

### StyleMapsConfig

```typescript
interface StyleMapsConfig {
  borderRadius: Record<string, string>;
  fontSize: Record<string, string>;
  fontWeight: Record<string, string>;
  fontFamily: Record<string, string>;
  textAlign: Record<string, string>;
  textDecoration: Record<string, string>;
  fontVariantNumeric: Record<string, string>;
  display: Record<string, string>;
  position: Record<string, string>;
}
```

## Supported CSS Properties

### Colors
- `backgroundColor`: Supports HEX, RGB, OKLCH formats
- `color`: Supports HEX, RGB, OKLCH formats

### Spacing
- `margin`, `marginTop`, `marginRight`, `marginBottom`, `marginLeft`, `marginX`, `marginY`
- `padding`, `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft`, `paddingX`, `paddingY`

### Typography
- `fontSize`: Supports rem, px, and other units
- `fontWeight`: 100-900
- `fontFamily`: Supports system fonts
- `textAlign`: left, center, right, justify
- `textDecoration`: underline, overline, line-through, none
- `fontVariantNumeric`: tabular-nums, oldstyle-nums, lining-nums, proportional-nums, diagonal-fractions, stacked-fractions, ordinal, slashed-zero, normal

### Layout
- `display`: block, flex, grid, hidden, etc.
- `flexDirection`: row, column, etc.
- `justifyContent`: flex-start, center, space-between, etc.
- `alignItems`: flex-start, center, stretch, etc.
- `gap`: Spacing values

### Others
- `borderRadius`: Border radius values
- `width`, `height`: Dimension values
- `position`: Positioning methods
- `opacity`: Opacity values

## Development

### Install Dependencies

```bash
npm install
```

### Build

```bash
npm run build
```

### Test

```bash
npm test
```

### Format Code

```bash
npm run format
```

### Lint Code

```bash
npm run lint
```

## License

MIT

## Contributing

Issues and Pull Requests are welcome!

## Changelog

### 1.0.0
- Initial release
- Support for CSS to Tailwind conversion
- Support for Tailwind to CSS conversion
- Complete color support
- TypeScript type definitions
- Support for custom configuration