npm package: @qt-test/apex-compiler
Description: Compiler for APEX mini-app platform - AXML templates, ACSS styles, and JavaScript bundling
Author: Interswitch Group
Latest version: 1.0.3

# @qt-test/apex-compiler

Compiler for APEX mini-app platform - handles AXML templates, ACSS styles, and JavaScript bundling.

## Installation

```bash
npm install @qt-test/apex-compiler
```

## Quick Start

```typescript
import { compile } from '@qt-test/apex-compiler';

const result = compile({
  axml: '<view class="container">Hello {{name}}</view>',
  acss: '.container { padding: 20rpx; }',
  js: 'Page({ data: { name: "World" } });',
  json: '{"navigationBarTitleText": "Home"}',
  filename: 'index',
  minify: true,
});

console.log(result.code);    // Compiled JavaScript
console.log(result.css);     // Compiled CSS
console.log(result.config);  // Page configuration
```

## Features

### AXML Template Compilation

- Converts AXML templates to render functions
- Supports mustache expressions `{{...}}`
- Handles directives: `a:if`, `a:elif`, `a:else`, `a:for`, `a:key`
- Supports event handlers: `onTap`, `onChange`, etc.
- Custom component detection

```typescript
import { compileTemplate, generateRenderFunction } from '@qt-test/apex-compiler';

const ast = compileTemplate('<view a:if="{{show}}">{{message}}</view>');
const { code } = generateRenderFunction(ast);
```

### ACSS Style Compilation

- Converts `rpx` units to responsive `vw` units
- CSS nesting support
- Auto vendor prefixing
- Minification

```typescript
import { compileStyles, transformRpx } from '@qt-test/apex-compiler';

const result = compileStyles(`
  .card {
    padding: 20rpx;

    .title {
      font-size: 32rpx;
    }
  }
`, { minify: true });
```

### JavaScript Transformation

- ES6+ transpilation
- TypeScript support
- Minification
- Source map generation

```typescript
import { transformScript } from '@qt-test/apex-compiler';

const result = transformScript(`
  Page({
    data: { count: 0 },
    increment() {
      this.setData({ count: this.data.count + 1 });
    }
  });
`, { minify: true });
```

## API Reference

### `compile(options)`

Main compilation function that handles all file types.

**Options:**

| Option | Type | Description |
|--------|------|-------------|
| `axml` | `string` | AXML template source |
| `acss` | `string` | ACSS style source |
| `js` | `string` | JavaScript source |
| `json` | `string` | Page configuration JSON |
| `filename` | `string` | File name for error reporting |
| `sourceMap` | `boolean` | Generate source maps |
| `minify` | `boolean` | Minify output |
| `isComponent` | `boolean` | Is this a component (vs page) |

**Returns:**

```typescript
interface CompileResult {
  code: string;           // Compiled JavaScript
  css?: string;           // Compiled CSS
  config: object;         // Page/component configuration
  map?: object;           // JavaScript source map
  cssMap?: object;        // CSS source map
  errors: CompileError[]; // Compilation errors
  warnings: CompileError[]; // Compilation warnings
  stats: {
    time: number;         // Compilation time (ms)
    originalSize: number; // Original size (bytes)
    compiledSize: number; // Compiled size (bytes)
  };
}
```

### `compileTemplate(source, options)`

Parses AXML template into an AST.

### `generateRenderFunction(ast, options)`

Generates render function from AXML AST.

### `compileStyles(source, options)`

Compiles ACSS styles to CSS.

### `transformRpx(css, designWidth)`

Converts `rpx` units to `vw`.

```typescript
transformRpx('20rpx', 750); // '2.666667vw'
```

### `transformScript(source, options)`

Transforms JavaScript/TypeScript code.

### `minifyCode(code, options)`

Minifies JavaScript code.

## AXML Syntax

### Directives

```xml
<!-- Conditional rendering -->
<view a:if="{{condition}}">Shown if true</view>
<view a:elif="{{other}}">Shown if other is true</view>
<view a:else>Shown otherwise</view>

<!-- List rendering -->
<view a:for="{{items}}" a:for-item="item" a:for-index="idx" a:key="id">
  {{idx}}: {{item.name}}
</view>

<!-- Block element (no DOM output) -->
<block a:if="{{show}}">
  <view>A</view>
  <view>B</view>
</block>
```

### Events

```xml
<button onTap="handleTap">Tap me</button>
<input onInput="handleInput" onChange="handleChange" />
```

### Dynamic Attributes

```xml
<view class="{{className}}" style="{{styleObj}}">
  Dynamic styling
</view>
```

## ACSS Syntax

### rpx Units

`rpx` (responsive pixel) is automatically converted to `vw`:

```css
/* Input */
.container {
  padding: 20rpx;
  font-size: 28rpx;
}

/* Output (750 design width) */
.container {
  padding: 2.666667vw;
  font-size: 3.733333vw;
}
```

### CSS Nesting

```css
.card {
  background: white;

  .title {
    font-weight: bold;
  }

  &:hover {
    box-shadow: 0 2px 8px rgba(0,0,0,0.1);
  }
}
```

## Error Handling

```typescript
const result = compile({
  axml: '<view>{{unclosed}',
  filename: 'broken',
});

if (result.errors.length > 0) {
  for (const error of result.errors) {
    console.error(`${error.file}:${error.line} - ${error.message}`);
  }
}
```

## License

MIT