pulse-js-framework 1.11.2 → 1.11.4

package/loader/README.md

@@ -1,509 +0,0 @@
-# Pulse Build Tool Integrations
-
-Build tool loaders and plugins for the Pulse JavaScript framework.
-
-## Available Integrations
-
-### Vite Plugin (`vite-plugin.js`) ✅
-
-Full-featured Vite plugin with HMR support and CSS extraction.
-
-**Installation:**
-
-```javascript
-// vite.config.js
-import pulsePlugin from 'pulse-js-framework/vite';
-
-export default {
-  plugins: [pulsePlugin({
-    sourceMap: true,
-    sass: {
-      loadPaths: ['src/styles'],
-      compressed: false
-    }
-  })]
-};
-```
-
-**Features:**
-- ✅ Automatic `.pulse` file transformation
-- ✅ Hot Module Replacement (HMR)
-- ✅ CSS extraction to Vite's CSS pipeline
-- ✅ Source map generation
-- ✅ SASS/LESS/Stylus auto-detection and compilation
-- ✅ Virtual CSS modules
-
-### Webpack Loader (`webpack-loader.js`) ✅
-
-Webpack loader with CSS extraction and preprocessor support.
-
-**Installation:**
-
-```javascript
-// webpack.config.js
-module.exports = {
-  module: {
-    rules: [
-      {
-        test: /\.pulse$/,
-        use: [
-          'style-loader',        // Inject CSS into DOM
-          'css-loader',          // Resolve CSS imports
-          {
-            loader: 'pulse-js-framework/loader/webpack-loader',
-            options: {
-              sourceMap: true,
-              extractCss: true,   // Extract CSS for css-loader
-              hmr: true,          // Enable HMR support
-              sass: {
-                loadPaths: ['src/styles']
-              }
-            }
-          }
-        ]
-      }
-    ]
-  }
-};
-```
-
-**With MiniCssExtractPlugin (production):**
-
-```javascript
-const MiniCssExtractPlugin = require('mini-css-extract-plugin');
-
-module.exports = {
-  module: {
-    rules: [
-      {
-        test: /\.pulse$/,
-        use: [
-          MiniCssExtractPlugin.loader,  // Extract to .css file
-          'css-loader',
-          'pulse-js-framework/loader/webpack-loader'
-        ]
-      }
-    ]
-  },
-  plugins: [
-    new MiniCssExtractPlugin({
-      filename: '[name].[contenthash].css'
-    })
-  ]
-};
-```
-
-**Features:**
-- ✅ Webpack 5+ support
-- ✅ CSS extraction for loaders chain
-- ✅ Hot Module Replacement (HMR)
-- ✅ Source map generation
-- ✅ SASS/LESS/Stylus auto-detection
-- ✅ Compatible with style-loader and MiniCssExtractPlugin
-
-### Rollup Plugin (`rollup-plugin.js`) ✅
-
-Rollup plugin with CSS extraction and tree-shaking support.
-
-**Installation:**
-
-```javascript
-// rollup.config.js
-import pulsePlugin from 'pulse-js-framework/rollup';
-import resolve from '@rollup/plugin-node-resolve';
-
-export default {
-  input: 'src/main.js',
-  output: {
-    file: 'dist/bundle.js',
-    format: 'es',
-    sourcemap: true
-  },
-  plugins: [
-    pulsePlugin({
-      sourceMap: true,
-      extractCss: 'bundle.css',  // Extract to CSS file
-      sass: {
-        loadPaths: ['src/styles']
-      }
-    }),
-    resolve()
-  ]
-};
-```
-
-**Features:**
-- ✅ Rollup 4+ support
-- ✅ CSS extraction to separate file
-- ✅ Source map generation
-- ✅ SASS/LESS/Stylus auto-detection
-- ✅ Tree-shaking compatible (ES modules)
-- ✅ No external dependencies required
-
-## CSS Preprocessor Support
-
-Both integrations support **automatic CSS preprocessing** for SASS, LESS, and Stylus:
-
-1. **Install the preprocessor** in your project:
-   ```bash
-   npm install -D sass        # For SASS/SCSS
-   npm install -D less        # For LESS
-   npm install -D stylus      # For Stylus
-   ```
-
-2. **Use preprocessor syntax** in `.pulse` style blocks:
-   ```pulse
-   style {
-     $primary: #646cff;       // SASS
-     @primary: #646cff;       // LESS
-     primary = #646cff        // Stylus
-
-     .button {
-       background: $primary;
-       &:hover { opacity: 0.8; }
-     }
-   }
-   ```
-
-3. **Auto-detection** - Framework detects preprocessor syntax automatically:
-   - Priority: SASS > LESS > Stylus
-   - Falls back to plain CSS if no preprocessor detected
-
-## Options Reference
-
-### Vite Plugin Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `exclude` | RegExp | `/node_modules/` | Files to exclude |
-| `sourceMap` | boolean | `true` | Generate source maps |
-| `sass.loadPaths` | string[] | `[]` | SASS include paths |
-| `sass.compressed` | boolean | `false` | Minify SASS output |
-
-### Webpack Loader Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `sourceMap` | boolean | `true` | Generate source maps |
-| `extractCss` | boolean | `true` | Extract CSS for css-loader |
-| `hmr` | boolean | `true` | Enable HMR support |
-| `verbose` | boolean | `true` | Log preprocessor info |
-| `sass.loadPaths` | string[] | `[]` | SASS include paths |
-| `sass.compressed` | boolean | `false` | Minify SASS output |
-| `sass.verbose` | boolean | `false` | Log SASS compilation |
-| `less.*` | object | `{}` | LESS-specific options |
-| `stylus.*` | object | `{}` | Stylus-specific options |
-
-### Rollup Plugin Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `include` | RegExp/Array | `/\.pulse$/` | Files to include |
-| `exclude` | RegExp/Array | `/node_modules/` | Files to exclude |
-| `sourceMap` | boolean | `true` | Generate source maps |
-| `extractCss` | string | `null` | Output CSS filename (null = inline) |
-| `sass.loadPaths` | string[] | `[]` | SASS include paths |
-| `sass.compressed` | boolean | `false` | Minify SASS output |
-| `sass.verbose` | boolean | `false` | Log SASS compilation |
-| `less.*` | object | `{}` | LESS-specific options |
-| `stylus.*` | object | `{}` | Stylus-specific options |
-
-### ESBuild Plugin Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `sourceMap` | boolean | `true` | Generate source maps |
-| `extractCss` | string | `null` | Output CSS filename (null = inline) |
-| `sass.loadPaths` | string[] | `[]` | SASS include paths |
-| `sass.compressed` | boolean | `false` | Minify SASS output |
-| `sass.verbose` | boolean | `false` | Log SASS compilation |
-| `less.*` | object | `{}` | LESS-specific options |
-| `stylus.*` | object | `{}` | Stylus-specific options |
-
-### Parcel Plugin Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `sourceMap` | boolean | `true` | Generate source maps |
-| `extractCss` | boolean | `true` | Extract CSS for Parcel's CSS pipeline |
-| `verbose` | boolean | `false` | Log preprocessor info |
-| `sass.loadPaths` | string[] | `[]` | SASS include paths |
-| `sass.compressed` | boolean | `false` | Minify SASS output |
-| `sass.verbose` | boolean | `false` | Log SASS compilation |
-| `less.*` | object | `{}` | LESS-specific options |
-| `stylus.*` | object | `{}` | Stylus-specific options |
-
-### SWC Plugin Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `sourceMap` | boolean | `true` | Generate source maps |
-| `extractCss` | string | `null` | Output CSS filename (null = inline) |
-| `sass.loadPaths` | string[] | `[]` | SASS include paths |
-| `sass.compressed` | boolean | `false` | Minify SASS output |
-| `sass.verbose` | boolean | `false` | Log SASS compilation |
-| `less.*` | object | `{}` | LESS-specific options |
-| `stylus.*` | object | `{}` | Stylus-specific options |
-
-## Development
-
-### Testing Vite Plugin
-
-```bash
-cd examples/vite-example
-npm install
-npm run dev
-```
-
-### Testing Webpack Loader
-
-```bash
-cd examples/webpack-example
-npm install
-npm run dev
-```
-
-### Testing Rollup Plugin
-
-```bash
-cd examples/rollup-example
-npm install
-npm run dev
-```
-
-### Testing ESBuild Plugin
-
-```bash
-cd examples/esbuild-example
-npm install
-npm run dev
-```
-
-### Testing Parcel Plugin
-
-```bash
-cd examples/parcel-example
-npm install
-npm run dev
-```
-
-### Testing SWC Plugin
-
-```bash
-npm run test:swc-plugin
-```
-
-### ESBuild Plugin (`esbuild-plugin.js`) ✅
-
-ESBuild plugin with CSS extraction and preprocessor support.
-
-**Installation:**
-
-```javascript
-// build.js
-import * as esbuild from 'esbuild';
-import pulsePlugin from 'pulse-js-framework/esbuild';
-
-await esbuild.build({
-  entryPoints: ['src/main.js'],
-  bundle: true,
-  outfile: 'dist/bundle.js',
-  plugins: [
-    pulsePlugin({
-      sourceMap: true,
-      extractCss: 'dist/bundle.css',  // Extract to CSS file
-      sass: {
-        loadPaths: ['src/styles']
-      }
-    })
-  ]
-});
-```
-
-**Features:**
-- ✅ ESBuild support
-- ✅ CSS extraction to separate file
-- ✅ Source map generation
-- ✅ SASS/LESS/Stylus auto-detection
-- ✅ Fast incremental builds
-- ✅ Watch mode compatible
-- ✅ No external dependencies required
-
-### Parcel Plugin (`parcel-plugin.js`) ✅
-
-Parcel transformer with CSS extraction and preprocessor support.
-
-**Installation:**
-
-1. Install Pulse as a dev dependency:
-```bash
-npm install -D pulse-js-framework
-```
-
-2. Create `.parcelrc` configuration:
-```json
-{
-  "extends": "@parcel/config-default",
-  "transformers": {
-    "*.pulse": ["pulse-js-framework/parcel"]
-  }
-}
-```
-
-3. Optionally create `.pulserc` or `.pulserc.json` for plugin options:
-```json
-{
-  "sourceMap": true,
-  "extractCss": true,
-  "verbose": false,
-  "sass": {
-    "loadPaths": ["src/styles"],
-    "compressed": false
-  },
-  "less": {
-    "loadPaths": []
-  },
-  "stylus": {
-    "loadPaths": []
-  }
-}
-```
-
-Or configure via `package.json`:
-```json
-{
-  "pulse": {
-    "sourceMap": true,
-    "extractCss": true,
-    "sass": {
-      "loadPaths": ["src/styles"]
-    }
-  }
-}
-```
-
-**Usage:**
-
-```javascript
-// src/main.js
-import MyComponent from './MyComponent.pulse';
-import { mount } from 'pulse-js-framework/runtime';
-
-mount('#app', MyComponent());
-```
-
-**Features:**
-- ✅ Automatic `.pulse` file transformation
-- ✅ CSS extraction to Parcel's CSS pipeline
-- ✅ Source map generation
-- ✅ SASS/LESS/Stylus auto-detection and compilation
-- ✅ Hot Module Replacement (HMR)
-- ✅ Watch mode support
-- ✅ Zero configuration (works out of the box)
-
-**Development Server:**
-
-```bash
-parcel src/index.html
-```
-
-**Production Build:**
-
-```bash
-parcel build src/index.html
-```
-
-### SWC Plugin (`swc-plugin.js`) ✅
-
-SWC plugin with CSS extraction, preprocessor support, and standalone transform API.
-
-**Usage with plugin interface:**
-
-```javascript
-// build.js
-import pulsePlugin from 'pulse-js-framework/swc';
-
-const plugin = pulsePlugin({
-  sourceMap: true,
-  extractCss: 'dist/bundle.css',
-  sass: {
-    loadPaths: ['src/styles']
-  }
-});
-
-plugin.buildStart();
-
-// Transform each .pulse file
-const result = plugin.transform(pulseSource, 'src/App.pulse');
-console.log(result.code);  // Compiled JavaScript
-console.log(result.css);   // Extracted CSS
-
-plugin.buildEnd();  // Writes accumulated CSS to dist/bundle.css
-```
-
-**Usage with direct transform API:**
-
-```javascript
-import { transformPulseFile, transformPulseCode } from 'pulse-js-framework/swc';
-
-// Transform a file
-const result = transformPulseFile('src/App.pulse', { sourceMap: true });
-
-// Transform source code
-const result2 = transformPulseCode(source, { filename: 'App.pulse' });
-```
-
-**Batch processing:**
-
-```javascript
-import { buildPulseFiles } from 'pulse-js-framework/swc';
-
-const results = buildPulseFiles(
-  ['src/App.pulse', 'src/Home.pulse'],
-  { extractCss: 'dist/bundle.css' }
-);
-```
-
-**Features:**
-- ✅ Standalone transform API (no SWC dependency required)
-- ✅ Plugin interface with build lifecycle
-- ✅ CSS extraction to separate file
-- ✅ Source map generation
-- ✅ SASS/LESS/Stylus auto-detection and compilation
-- ✅ Batch file processing
-- ✅ No external dependencies required
-
-## Planned Integrations
-
-All planned integrations have been implemented.
-
-## Architecture
-
-All integrations follow the same pattern:
-
-1. **Compile** `.pulse` files to JavaScript using `compiler/index.js`
-2. **Extract CSS** from compiled output
-3. **Preprocess CSS** if SASS/LESS/Stylus detected and available
-4. **Pass to build tool** pipeline:
-   - Vite: Virtual CSS modules
-   - Webpack: css-loader chain
-   - Rollup: Accumulated CSS asset
-   - ESBuild: File-based CSS accumulation
-   - Parcel: Asset API
-   - SWC: File-based CSS accumulation with standalone transform API
-5. **Enable HMR** for development (where supported)
-
-## Contributing
-
-When adding a new build tool integration:
-
-1. Follow the naming convention: `{tool}-{type}.js` (e.g., `rollup-plugin.js`)
-2. Support CSS extraction for the tool's pipeline
-3. Enable HMR if the tool supports it
-4. Add preprocessor auto-detection
-5. Document options in this README
-6. Add example project in `examples/`
-
-## License
-
-MIT