npm package: @qt-test/apex-dsl-compiler
Description: AXML/ACSS DSL compiler for APEX mini-app platform
Author: Interswitch
Latest version: 0.1.0

# @interswitch/apex-compiler

> AXML/ACSS compiler for APEX mini-app platform

This package compiles APEX DSL (AXML templates and ACSS styles) into JavaScript code that works with the APEX runtime.

## Installation

```bash
npm install @interswitch/apex-compiler
```

## Usage

### Programmatic API

```javascript
import { compile, compileAXML, compileACSS } from '@interswitch/apex-compiler';

// Compile a complete page/component
const result = compile({
  axml: '<view class="container"><text>{{message}}</text></view>',
  acss: '.container { padding: 20rpx; }',
  json: { component: true }
});

console.log(result.code);
console.log(result.styles);

// Compile AXML only
const template = compileAXML('<view a:for="{{items}}">{{item}}</view>');
console.log(template.render);

// Compile ACSS only
const styles = compileACSS('.btn { width: 200rpx; color: #333; }');
console.log(styles.css);
```

### CLI

```bash
# Compile a single file
apexc compile pages/index/index.axml -o dist/

# Compile a directory
apexc compile src/ -o dist/

# Watch mode
apexc compile src/ -o dist/ --watch
```

## AXML Syntax

### Basic Elements

```xml
<!-- View container -->
<view class="container">
  <text>Hello World</text>
</view>

<!-- Data binding -->
<text>{{message}}</text>
<view class="item-{{index}}">{{item.name}}</view>

<!-- Attribute binding -->
<image src="{{imageUrl}}" mode="aspectFit" />
```

### Directives

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

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

<!-- Key for optimization -->
<view a:for="{{items}}" a:key="id">{{item.name}}</view>
```

### Event Binding

```xml
<!-- Tap event -->
<button bindtap="handleTap">Click me</button>

<!-- With event object -->
<input bindinput="handleInput" />

<!-- Catch (stop propagation) -->
<view catchtap="handleTap">Won't bubble</view>

<!-- Pass data -->
<button bindtap="handleTap" data-id="{{item.id}}">{{item.name}}</button>
```

### Built-in Components

```xml
<!-- View -->
<view class="container" style="padding: 10px;">Content</view>

<!-- Text -->
<text selectable="{{true}}">Selectable text</text>

<!-- Image -->
<image src="/images/logo.png" mode="aspectFit" lazy-load />

<!-- Button -->
<button type="primary" loading="{{isLoading}}">Submit</button>

<!-- Input -->
<input type="text" placeholder="Enter name" value="{{name}}" bindinput="onInput" />

<!-- Scroll View -->
<scroll-view scroll-y style="height: 300px;">
  <view a:for="{{items}}">{{item}}</view>
</scroll-view>

<!-- Swiper -->
<swiper autoplay circular>
  <swiper-item a:for="{{banners}}">
    <image src="{{item.url}}" />
  </swiper-item>
</swiper>
```

### Templates & Slots

```xml
<!-- Define template -->
<template name="userCard">
  <view class="card">
    <text>{{name}}</text>
    <text>{{age}}</text>
  </view>
</template>

<!-- Use template -->
<template is="userCard" data="{{...user}}" />

<!-- Slots in components -->
<my-component>
  <view slot="header">Header content</view>
  <view>Default slot content</view>
  <view slot="footer">Footer content</view>
</my-component>
```

## ACSS Syntax

ACSS is CSS with extensions for mini-app development.

### RPX Units

```css
/* rpx = responsive pixel, auto-scales with screen width */
/* 750rpx = full screen width on any device */
.container {
  width: 750rpx;
  padding: 20rpx;
  font-size: 28rpx;
}
```

### Standard CSS

```css
.button {
  background-color: #1890ff;
  color: white;
  border-radius: 8rpx;
  padding: 16rpx 32rpx;
}

.button:active {
  opacity: 0.8;
}
```

### Import

```css
@import './common.acss';
@import '/styles/theme.acss';
```

### Variables (CSS Custom Properties)

```css
:root {
  --primary-color: #1890ff;
  --text-color: #333;
}

.button {
  background: var(--primary-color);
  color: var(--text-color);
}
```

## Compiler Output

### Input

```xml
<!-- index.axml -->
<view class="page">
  <text class="title">{{title}}</text>
  <button bindtap="handleClick">Click</button>
</view>
```

### Output (simplified)

```javascript
export function render(_ctx) {
  return h('view', { class: 'page' }, [
    h('text', { class: 'title' }, [_ctx.title]),
    h('button', { bindtap: _ctx.handleClick }, ['Click'])
  ]);
}
```

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    Source Files                          │
│         (.axml, .acss, .json, .js)                      │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                      Lexer                               │
│            (Tokenize source code)                        │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                      Parser                              │
│         (Build Abstract Syntax Tree)                     │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                    Transformer                           │
│    (Optimize, validate, transform AST)                   │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                   Code Generator                         │
│          (Generate JavaScript output)                    │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                    Output Files                          │
│            (.js, .css, .json)                           │
└─────────────────────────────────────────────────────────┘
```

## License

MIT