npm package: @ohto/postcss-ohto
Description: Custom PostCSS preset with nested rules, custom media queries, data attribute expansion, and autoprefixer. Plug-and-play for modern projects.
Author: Liam Hall
Latest version: 1.7.0

# @ohto/postcss-ohto

A custom PostCSS preset with nested rules, custom media queries, data attribute expansion, and autoprefixer. Plug-and-play for modern projects.

## Features

- **Custom Media Queries**: Predefined responsive breakpoints using modern `@custom-media` syntax
- **Data Attribute Expansion**: Powerful range syntax for generating utility classes from data attributes
- **@breakpoints Directive**: Generate responsive variants for all configured breakpoints automatically
- **Nested CSS**: Write nested CSS rules with `postcss-nested`
- **Autoprefixer**: Automatic vendor prefixing for better browser compatibility
- **Configurable**: Override default screen sizes with your own configuration
- **TypeScript Support**: Full TypeScript support with included type definitions

## Installation

```bash
npm install @ohto/postcss-ohto
# or
pnpm add @ohto/postcss-ohto
```

## Usage

### Basic Usage

```javascript
import postcssOhto from "@ohto/postcss-ohto";

const config = await postcssOhto();

// Use with your PostCSS setup
import postcss from "postcss";
const result = await postcss(config.plugins).process(css);
```

### With PostCSS Config

```javascript
// postcss.config.js
import postcssOhto from "@ohto/postcss-ohto";

export default async () => {
  const ohtoConfig = await postcssOhto();
  return {
    plugins: ohtoConfig.plugins,
  };
};
```

### With TypeScript

The package includes full TypeScript support:

```typescript
// postcss.config.ts
import postcssOhto from "@ohto/postcss-ohto";

export default async () => {
  const ohtoConfig = await postcssOhto();
  return {
    plugins: ohtoConfig.plugins,
  };
};
```

### CSS Usage

The plugin provides the following default custom media queries:

```css
/* Available custom media queries */
@media (--sm) /* min-width: 640px */ @media (--md) /* min-width: 768px */ @media (--lg) /* min-width: 1024px */ @media (--xl) /* min-width: 1280px */ @media (--2xl); /* min-width: 1536px */
```

Example usage:

```css
.container {
  padding: 1rem;

  @media (--md) {
    padding: 2rem;
  }

  @media (--lg) {
    max-width: 1024px;
    margin: 0 auto;
  }
}

.button {
  background: blue;

  &:hover {
    background: darkblue;
  }

  @media (--sm) {
    font-size: 1.2rem;
  }
}
```

## Data Attribute Expansion

The plugin provides powerful data attribute expansion with range syntax, perfect for generating utility classes:

### Range Syntax (1..12)

```css
[ohto:columns="(1..12)"] {
  --columns: attr(ohto:columns number);
  grid-template-columns: repeat(var(--columns), 1fr);
}
```

Expands to:

```css
[ohto:columns="1"] {
  --columns: 1;
  grid-template-columns: repeat(var(--columns), 1fr);
}
[ohto:columns="2"] {
  --columns: 2;
  grid-template-columns: repeat(var(--columns), 1fr);
}
[ohto:columns="3"] {
  --columns: 3;
  grid-template-columns: repeat(var(--columns), 1fr);
}
/* ... continues to 12 */
```

### Comma-Separated Values

```css
/* Numeric values */
[ohto:size="(1,6,12)"] {
  --size: attr(ohto:size number);
}

/* String values */
[ohto:theme="('light','dark','auto')"] {
  --theme: attr(ohto:theme);
}
```

Expands to:

```css
[ohto:size="1"] {
  --size: 1;
}
[ohto:size="6"] {
  --size: 6;
}
[ohto:size="12"] {
  --size: 12;
}

[ohto:theme="light"] {
  --theme: "light";
}
[ohto:theme="dark"] {
  --theme: "dark";
}
[ohto:theme="auto"] {
  --theme: "auto";
}
```

### Usage in HTML

```html
<div ohto:columns="4" class="grid">
  <!-- This will use --columns: 4 -->
</div>

<div ohto:theme="dark" class="card">
  <!-- This will use --theme: 'dark' -->
</div>
```

## @breakpoints Directive

The `@breakpoints` directive automatically generates responsive variants for all configured breakpoints:

### Basic Usage

```css
@breakpoints {
  [ohto:columns="(1..12)"] {
    --columns: attr(ohto:columns number);
    grid-template-columns: repeat(var(--columns), 1fr);
  }
}
```

Generates:

```css
/* Base classes */
[ohto:columns="1"] {
  --columns: 1;
  grid-template-columns: repeat(var(--columns), 1fr);
}
[ohto:columns="2"] {
  --columns: 2;
  grid-template-columns: repeat(var(--columns), 1fr);
}
/* ... continues to 12 */

/* Responsive variants for each breakpoint */
@media (min-width: 640px) {
  [ohto:sm-columns="1"] {
    --columns: 1;
    grid-template-columns: repeat(var(--columns), 1fr);
  }
  [ohto:sm-columns="2"] {
    --columns: 2;
    grid-template-columns: repeat(var(--columns), 1fr);
  }
  /* ... etc */
}

@media (min-width: 768px) {
  [ohto:md-columns="1"] {
    --columns: 1;
    grid-template-columns: repeat(var(--columns), 1fr);
  }
  [ohto:md-columns="2"] {
    --columns: 2;
    grid-template-columns: repeat(var(--columns), 1fr);
  }
  /* ... etc */
}
/* ... continues for lg, xl, 2xl */
```

### Usage in HTML

```html
<!-- Base -->
<div ohto:columns="4">4 columns on all screen sizes</div>

<!-- Responsive -->
<div ohto:md-columns="6" ohto:lg-columns="8">
  6 columns on md+, 8 columns on lg+
</div>
```

### Multiple @breakpoints Blocks

```css
@breakpoints {
  [ohto:gap="(1,2,4,8)"] {
    --gap: attr(ohto:gap number);
    gap: calc(var(--gap) * 0.25rem);
  }
}

@breakpoints {
  [ohto:theme="('light','dark')"] {
    --theme: attr(ohto:theme);
  }
}
```

This creates both base classes and responsive variants for each utility.

## Configuration

You can override the default screen sizes by creating a `postcss-ohto.config.js` file in your project root:

```javascript
// postcss-ohto.config.js
export const screenSizes = {
  mobile: 480,
  tablet: 768,
  desktop: 1024,
  wide: 1440,
};
```

This will generate custom media queries like:

- `--mobile` → `(min-width: 480px)`
- `--tablet` → `(min-width: 768px)`
- `--desktop` → `(min-width: 1024px)`
- `--wide` → `(min-width: 1440px)`

## What's Included

This preset includes:

1. **postcss-nested**: Enables CSS nesting syntax
2. **postcss-breakpoints**: Custom @breakpoints directive for responsive utilities (OHTO)
3. **postcss-expand-data-attributes**: Custom plugin for data attribute range expansion (OHTO)
4. **postcss-custom-media**: Processes custom media queries (modern syntax)
5. **autoprefixer**: Adds vendor prefixes automatically
6. **@csstools/postcss-global-data**: Provides global custom media definitions

## Migration from Previous Versions

If you were using an older version that relied on the deprecated `importFrom` option, this version now uses the modern approach with `@csstools/postcss-global-data` to provide global custom media query definitions.

## License

MIT