# Build Guide — Wow Extensions for WooCommerce

This document explains how to set up the development environment, build assets, and follow coding standards for this plugin.

---

## Requirements

| Tool | Version |
|------|---------|
| [Node.js](https://nodejs.org/) | 16+ |
| [npm](https://www.npmjs.com/) | 8+ |
| [PHP](https://www.php.net/) | 7.4+ |
| [Composer](https://getcomposer.org/) | 2+ _(for PHPCS)_ |

---

## Project Structure

```
wow-extensions-for-woocommerce/
├── src/                        # Source files (edit these)
│   ├── css/
│   │   └── admin.css           # Admin dashboard styles (source)
│   └── js/
│       └── admin.js            # Admin dashboard scripts (source)
│
├── assets/                     # Compiled/minified files (do not edit)
│   ├── css/
│   │   └── admin.css           # Minified CSS output
│   ├── js/
│   │   └── admin.js            # Minified JS output
│   └── vendor/
│       └── select2/            # Bundled Select2 library
│
├── docs/                       # Developer documentation
├── includes/                   # Core PHP classes
├── extensions/                 # Plugin extensions (e.g. role-based-pricing)
├── package.json                # Node.js build config
├── phpcs.xml                   # PHP CodeSniffer config
└── wow-extensions-for-woocommerce.php  # Main plugin file
```

---

## Installation

Install Node.js dependencies:

```bash
npm install
```

---

## Available npm Scripts

| Command | Description |
|---------|-------------|
| `npm run build` | Build all assets (CSS + JS) for production |
| `npm run build:css` | Minify CSS only (`src/css/admin.css` → `assets/css/admin.css`) |
| `npm run build:js` | Minify JS only (`src/js/admin.js` → `assets/js/admin.js`) |
| `npm run watch` | Watch both CSS and JS files for changes |
| `npm run watch:css` | Watch CSS files only |
| `npm run watch:js` | Watch JS files only |
| `npm run dev` | Alias for `npm run watch` |
| `npm run zip` | Build assets then package a production-ready ZIP to `dist/` |

---

## Development Workflow

### 1. Start the file watcher

```bash
npm run dev
```

This watches `src/css/*.css` and `src/js/*.js` and automatically rebuilds the minified output in `assets/` on every save.

### 2. Edit source files

- **Styles** → edit `src/css/admin.css`
- **Scripts** → edit `src/js/admin.js`

> ⚠️ Never edit files in `assets/` directly — they are overwritten on every build.

### 3. Build for production

```bash
npm run build
```

This runs both `build:css` and `build:js` sequentially and outputs minified files to `assets/`.

---

## How the Build Works

### CSS

[clean-css-cli](https://github.com/clean-css/clean-css-cli) minifies the admin stylesheet:

```
src/css/admin.css  →  assets/css/admin.css
```

### JavaScript

[Terser](https://terser.org/) minifies and mangles the admin script:

```
src/js/admin.js  →  assets/js/admin.js
```

### File Watching

[chokidar-cli](https://github.com/open-cli-tools/chokidar-cli) watches for file changes and triggers the relevant build command automatically.

---

## PHP Coding Standards

This plugin uses [PHP CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) with the [WordPress Coding Standards](https://github.com/WordPress/WordPress-Coding-Standards).

The ruleset is defined in `phpcs.xml` with the following valid prefixes:

- `wowexfow`
- `Wowexfow`
- `WOWEXFOW`

### Run PHPCS

```bash
vendor/bin/phpcs
```

### Auto-fix fixable issues

```bash
vendor/bin/phpcbf
```

---

## Vendor Assets

The following third-party libraries are bundled locally inside `assets/vendor/` for WordPress Plugin Check compliance (no CDN dependency):

| Library | Version | Location |
|---------|---------|----------|
| [Select2](https://select2.org/) | 4.0.13 | `assets/vendor/select2/` |

---

## Production ZIP

Run the following to produce a clean, upload-ready ZIP:

```bash
npm run zip
```

This command:
1. Runs `npm run build` (minifies CSS + JS)
2. Executes `scripts/zip.js` which packages the plugin into `dist/wow-extensions-for-woocommerce-<version>.zip`

The following are **excluded** from the ZIP:

| Excluded |
|----------|
| `node_modules/` |
| `src/` |
| `scripts/` |
| `dist/` |
| `docs/` |
| `.git/` / `.gitignore` |
| `package.json` / `package-lock.json` |
| `phpcs.xml` |
| `README.md` |
| `.DS_Store` / `*.map` |

---

## Notes

- The `node_modules/` directory must **not** be included in plugin releases.
- The `src/` directory must **not** be included in plugin releases.
- Only the compiled `assets/` directory should be shipped.
- The ZIP output lives in `dist/` — this folder is also excluded from the ZIP itself.