npm package: @rhavenside/css-watch
Description: Runtime CSS conflict detector for development - analyzes CSS conflicts, overrides, and complexity
Latest version: 1.0.19

# CSS Watch

Runtime CSS conflict detector for development - analyzes CSS conflicts, overrides, and complexity at runtime.

## Overview

CSS Watch is a development tool that runs at runtime in dev mode and shows where CSS rules neutralize, override, or unnecessarily complicate each other. It's not a linter or formatter - it generates hints, not errors, and is fully disableable.

## Features

- ✅ **Automatic detection of duplicate classes** - Find classes defined multiple times
- ✅ **Analysis of CSS overrides** - See which rules win and which are overridden
- ✅ **Complexity evaluation** - Identify selectors with high depth and DOM dependency
- ✅ **DOM integration** - Distinguish between active and potential conflicts
- ✅ **Visual highlighting** - Highlight affected elements in the DOM
- ✅ **Filtering** - Filter by class, selector, or file
- ✅ **Source map support** - Works with SCSS source maps
- ✅ **Automatic updates** - Updates on DOM changes

## Installation

```bash
npm install css-watch --save-dev
```

## Usage

### Basic Usage

CSS Watch automatically initializes in development mode:

```javascript
// In your main entry file (e.g., main.jsx)
import 'css-watch';

// That's it! CSS Watch will automatically activate in dev mode
```

### Manual Initialization

For more control, you can manually initialize:

```javascript
import { initCSSWatch } from 'css-watch';

// Initialize with options
const cssWatch = initCSSWatch({
  rootElement: 'body',  // or a specific element
  autoStart: true       // automatically start analysis
});

// Later, you can destroy it
cssWatch.destroy();
```

### With Vite

CSS Watch works seamlessly with Vite projects. Just import it in your main file:

```javascript
// src/main.jsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App.jsx';

// Import CSS Watch (only active in dev mode)
if (import.meta.env.DEV) {
  import('css-watch');
}

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);
```

## Three Analysis Levels

### 1. Structure (What exists?)

Captures which classes exist, how often they are defined, where they are defined, and in what context (global, component, utility).

**Example:**
- Class `.button` is defined in `styles/global.scss` and `components/Button.scss`
- Shows all definitions with file locations and line numbers

### 2. Effect (What wins?)

Examines which rules set the same property and which rule is actually applied based on CSS specificity.

**Example:**
- `.button { color: red; }` and `.button.primary { color: blue; }`
- Shows that `.button.primary` wins due to higher specificity

### 3. Complexity (How complicated is it?)

Evaluates selector depth, number of combined classes, use of IDs, and dependency on DOM structure.

**Example:**
- `.container .header .title` has depth 2 and is DOM-dependent
- Flags selectors that are hard to maintain

## API

### `initCSSWatch(options?)`

Initializes CSS Watch in the current application.

**Parameters:**
- `options.rootElement` (string | HTMLElement): Root element or selector (default: `'body'`)
- `options.autoStart` (boolean): Automatically start analysis (default: `true`)

**Returns:**
- Object with `destroy()` method to remove CSS Watch

### `isCSSWatchAvailable()`

Checks if CSS Watch is available (dev mode).

**Returns:**
- `boolean` - true if in development mode

### `analyzeStyles()`

Manually trigger CSS analysis.

**Returns:**
- `Promise<AnalysisResults>` - Analysis results object

## Configuration

CSS Watch automatically detects development mode using:
- `import.meta.env.DEV` (Vite)
- `process.env.NODE_ENV === 'development'` (Other bundlers)

## Requirements

- React 18+
- Modern browser with ES6+ support
- Development environment (automatically disabled in production)

## Browser Support

- Chrome/Edge (latest)
- Firefox (latest)
- Safari (latest)

## Development

```bash
# Install dependencies
npm install

# Run dev server
npm run dev

# Build library
npm run build:lib
```

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.