npm package: @planeasyinc/fe-angular
Description: Angular 17+ standalone components for form engine. Built with partial-Ivy compilation for optimal bundle size and performance.
Latest version: 0.1.32

# @planeasyinc/fe-angular

Angular 17+ standalone components for form engine. Built with partial-Ivy compilation for optimal bundle size and performance.

## TL;DR - Quick Reference

```bash
# Install
npm install @planeasyinc/fe-angular @planeasyinc/fe-core

# Use in component
import { FeFieldHost } from '@planeasyinc/fe-angular';
import { createEngine } from '@planeasyinc/fe-core';

# Build library
pnpm run build

# Publish
pnpm publish --registry=https://npm.pkg.github.com
```

---

## What is @planeasyinc/fe-angular?

`@planeasyinc/fe-angular` is an Angular library that provides 32+ form control components for building dynamic forms. It works with `@planeasyinc/fe-core` to manage form state, validation, and value changes.

**Key features:**
- ✅ 32+ form controls (text, number, select, date, file upload, etc.)
- ✅ Standalone Angular 17+ components
- ✅ Dynamic form rendering via `FeFieldHost`
- ✅ Type-safe with TypeScript
- ✅ Built with NG-ZORRO Ant Design components

---

## Requirements

- **Angular:** 17.0.0 or higher
- **TypeScript:** 5.4.x (5.2+ minimum)
- **RxJS:** 7.8.0 or higher
- **Node.js:** 18+ (for building)
- **NG-ZORRO Ant Design:** 17.x (peer dependency)
- **@angular/animations:** 17.x (peer dependency)
- **date-fns:** ^2.0.0 (peer dependency)

---

## Installation

### From GitHub Packages

1. Create `.npmrc` in your project root:

```ini
@planeasyinc:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
```

2. Install packages:

```bash
npm install @planeasyinc/fe-angular @planeasyinc/fe-core ng-zorro-antd@17 @angular/animations@17 date-fns
# or
pnpm add @planeasyinc/fe-angular @planeasyinc/fe-core ng-zorro-antd@17 @angular/animations@17 date-fns
```

**Note:** You need a GitHub Personal Access Token with `read:packages` scope.

### NG-ZORRO Setup

After installing, you must configure NG-ZORRO in your Angular app. See the [NG-ZORRO Setup Guide](./docs/ng-zorro-setup.md) for detailed instructions.

**Quick setup:**
1. Import `BrowserAnimationsModule` in your app module
2. Provide `NZ_I18N` with locale (e.g., `en_US`)
3. Add NG-ZORRO styles to your global stylesheet
4. (Optional) Register icons from `@planeasyinc/fe-angular/icons`

### From Workspace (Development)

If using pnpm workspaces:

```json
{
  "dependencies": {
    "@planeasyinc/fe-angular": "workspace:*",
    "@planeasyinc/fe-core": "workspace:*"
  }
}
```

---

## Quick Start

### 1. Import and Use Standalone Components

```typescript
import { Component } from '@angular/core';
import { FeTextControl, FeNumberControl } from '@planeasyinc/fe-angular';
import { createEngine } from '@planeasyinc/fe-core';

@Component({
  selector: 'app-form',
  standalone: true,
  imports: [FeTextControl, FeNumberControl],
  template: `
    <fe-text [engine]="engine" path="name" [label]="'Name'" />
    <fe-number [engine]="engine" path="age" [label]="'Age'" />
  `
})
export class FormComponent {
  engine = createEngine({
    fields: [
      { type: 'text', name: 'name', label: 'Name' },
      { type: 'number', name: 'age', label: 'Age' }
    ]
  });
}
```

### 2. Use FieldHost for Dynamic Forms

```typescript
import { Component } from '@angular/core';
import { FeFieldHost } from '@planeasyinc/fe-angular';
import { createEngine, type FeControlConfig } from '@planeasyinc/fe-core';
import { CommonModule } from '@angular/common';

@Component({
  selector: 'app-dynamic-form',
  standalone: true,
  imports: [FeFieldHost, CommonModule],
  template: `
    <fe-field
      *ngFor="let field of fields"
      [engine]="engine"
      [control]="field"
    />
  `
})
export class DynamicFormComponent {
  engine = createEngine({
    fields: [
      { type: 'text', name: 'email', label: 'Email' },
      { type: 'select', name: 'country', label: 'Country', meta: { options: [...] } }
    ]
  });

  fields: FeControlConfig[] = this.engine.config.fields;
}
```

### 3. Access Form Values

```typescript
// Get all values
const values = this.engine.values.getAll();

// Get single value
const email = this.engine.values.get('email');

// Listen to changes
this.engine.on('valueChanges', (values) => {
  console.log('Form values changed:', values);
});

// Submit
const isValid = this.engine.validate();
if (isValid) {
  const formData = this.engine.values.getAll();
  // Submit formData
}
```

---

## Registry Overview

The library uses a **registry pattern** to map control types to Angular components:

```typescript
import { getRenderer, hasRenderer, ANGULAR_RENDERERS } from '@planeasyinc/fe-angular';

// Check if a control type is supported
if (hasRenderer('text')) {
  const Component = getRenderer('text');
  // Component is FeTextControl
}

// Access full registry
console.log(ANGULAR_RENDERERS); // Record<FeControlType, Type<any>>
```

`FeFieldHost` uses this registry to dynamically render controls based on `control.type`.

---

## Available Controls

See [docs/controls.md](./docs/controls.md) for the complete catalog of 32+ controls.

**Categories:**
- Text inputs (text, email, phone, password, textarea)
- Numbers (number, number-slider, number-operations)
- Selection (select, multiselect, radio, checkbox, toggle)
- Date/Time (date, datetime, time, date-triplet)
- Structural (array, dict, group, object)
- File uploads (attachment, file)
- Special (button, chat, infoscreen, mask, json)

---

## Versioning & Releases

We follow [Semantic Versioning](https://semver.org/):

- **Major (x.0.0):** Breaking changes
- **Minor (0.x.0):** New features, backward compatible
- **Patch (0.0.x):** Bug fixes, backward compatible

**Current version:** `0.1.2`

**Release tags:**
- Published to GitHub Packages: `@planeasyinc/fe-angular@0.1.2`
- Git tags: `v0.1.2`

**Breaking changes:**
- Angular 17+ required (no support for Angular 16 or lower)
- TypeScript 5.4.x recommended (5.2+ minimum)

---

## Documentation

- **[NG-ZORRO Setup Guide](./docs/ng-zorro-setup.md)** - **Required:** Setting up NG-ZORRO in your app
- **[Guide](./docs/guide.md)** - Architecture, adding controls, theming, publishing
- **[Controls Catalog](./docs/controls.md)** - Complete list of all controls
- **[Migration Guide](./docs/migration-from-console.md)** - Migrating from console components
- **[Troubleshooting](./docs/troubleshooting.md)** - Common errors and fixes

---

## Support

- **Issues:** GitHub Issues (if public) or internal ticketing
- **Questions:** Contact the team lead

---

## License

Proprietary - Internal use only