@flusys/ng-email 3.0.0-rc → 3.0.0

package/README.md

@@ -1,6 +1,7 @@
 # Email Package Guide
 
 > **Package:** `@flusys/ng-email`
+> **Version:** 3.0.0
 > **Type:** Email management with configurations, templates, and sending
 
 ---
@@ -15,15 +16,17 @@
 - **Test Sending** - Test configurations and templates with dynamic variables
 - **Company Scoping** - Automatic company-scoped queries (when enabled)
 - **Lazy Loading** - All page components are lazy-loaded via routes
+- **Permission Guards** - Route-level access control using `permissionGuard`
+- **Zoneless Ready** - All components use signals for zoneless change detection
 - **Responsive Design** - Mobile-first with horizontal scroll tables
 - **Dark Mode** - Full dark/light mode support
 
 ### Package Hierarchy
 
 ```
-@flusys/ng-core           <- Foundation (APP_CONFIG, DEFAULT_APP_NAME)
+@flusys/ng-core           <- Foundation (APP_CONFIG, DEFAULT_APP_NAME, getServiceUrl)
         |
-@flusys/ng-shared         <- Shared utilities (ApiResourceService, IBaseEntity)
+@flusys/ng-shared         <- Shared utilities (ApiResourceService, HasPermissionDirective, PermissionValidatorService)
         |
 @flusys/ng-layout         <- Layout (LAYOUT_AUTH_STATE for company context)
         |
@@ -58,31 +61,30 @@ readonly currentCompanyName = computed(
 ng-email/
 ├── enums/
 │   ├── email-provider.enum.ts       # EmailProviderEnum (smtp, sendgrid, mailgun)
-│   ├── email-block-type.enum.ts     # EmailBlockType (text, image, button, etc.)
+│   ├── email-block-type.enum.ts     # EmailBlockType (text, image, button, divider, html)
 │   └── public-api.ts
 ├── interfaces/
-│   ├── email-config.interface.ts    # IEmailConfig, ICreateEmailConfigDto
-│   ├── email-template.interface.ts  # IEmailTemplate, ICreateEmailTemplateDto
-│   ├── email-schema.interface.ts    # IEmailSchema, IEmailSection, IEmailBlock
-│   ├── email-send.interface.ts      # ISendEmailDto, ISendTemplateEmailDto
+│   ├── email-config.interface.ts    # IEmailConfig, ICreateEmailConfigDto, ISmtpAuth, ISmtpConfig, ISendGridConfig, IMailgunConfig
+│   ├── email-template.interface.ts  # IEmailTemplate, ICreateEmailTemplateDto, IUpdateEmailTemplateDto
+│   ├── email-schema.interface.ts    # IEmailSchema, IEmailSection, IEmailBlock, block content types
+│   ├── email-send.interface.ts      # ISendEmailDto, ISendTemplateEmailDto, ITestSendResult
 │   └── public-api.ts
 ├── services/
 │   ├── email-config-api.service.ts  # Config CRUD + test sending
 │   ├── email-template-api.service.ts # Template CRUD + getBySlug
-│   ├── email-send.service.ts        # Email sending operations
-│   ├── email-builder-state.service.ts # Template builder state management
-│   └── public-api.ts
+│   ├── email-send.service.ts        # Email sending operations (direct + template)
+│   └── email-builder-state.service.ts # Template builder state management
 ├── pages/
 │   ├── email-container/
-│   │   └── email-container.component.ts  # Main container with tabs
+│   │   └── email-container.component.ts  # Main container with permission-filtered tabs
 │   ├── config/
-│   │   ├── email-config-list.component.ts
-│   │   └── email-config-form.component.ts
+│   │   ├── email-config-list.component.ts  # Config list with test dialog
+│   │   └── email-config-form.component.ts  # Config form with dynamic provider fields
 │   └── template/
-│       ├── template-list.component.ts
-│       └── template-form.component.ts
+│       ├── template-list.component.ts      # Template list with test send dialog
+│       └── template-form.component.ts      # Template form with Angular Signal Forms
 ├── routes/
-│   └── email.routes.ts
+│   └── email.routes.ts                     # Routes with permission guards
 └── public-api.ts
 ```
 
@@ -104,17 +106,17 @@ export const routes: Routes = [
 ];
 ```
 
-### Route Structure
+### Route Structure with Permission Guards
 
-| Path | Component | Description |
-|------|-----------|-------------|
-| `/email` | EmailContainerComponent | Main container with tab navigation |
-| `/email/templates` | TemplateListComponent | List email templates |
-| `/email/templates/new` | TemplateFormComponent | Create new template |
-| `/email/templates/:id` | TemplateFormComponent | Edit template |
-| `/email/configs` | EmailConfigListComponent | List email configurations |
-| `/email/configs/new` | EmailConfigFormComponent | Create new config |
-| `/email/configs/:id` | EmailConfigFormComponent | Edit config |
+| Path | Component | Permission Guard |
+|------|-----------|------------------|
+| `/email` | EmailContainerComponent | - |
+| `/email/templates` | TemplateListComponent | `EMAIL_TEMPLATE_PERMISSIONS.READ` |
+| `/email/templates/new` | TemplateFormComponent | `EMAIL_TEMPLATE_PERMISSIONS.CREATE` |
+| `/email/templates/:id` | TemplateFormComponent | `EMAIL_TEMPLATE_PERMISSIONS.UPDATE` |
+| `/email/configs` | EmailConfigListComponent | `EMAIL_CONFIG_PERMISSIONS.READ` |
+| `/email/configs/new` | EmailConfigFormComponent | `EMAIL_CONFIG_PERMISSIONS.CREATE` |
+| `/email/configs/:id` | EmailConfigFormComponent | `EMAIL_CONFIG_PERMISSIONS.UPDATE` |
 
 ---
 
@@ -149,60 +151,68 @@ export enum EmailBlockType {
 ### Email Configuration
 
 ```typescript
+/** SMTP auth credentials (nodemailer style) */
+interface ISmtpAuth {
+  user: string;
+  pass: string;
+}
+
+/** SMTP provider configuration (nodemailer style) */
+interface ISmtpConfig {
+  host: string;
+  port: number;
+  secure?: boolean;
+  auth: ISmtpAuth;
+}
+
+/** SendGrid provider configuration */
+interface ISendGridConfig {
+  apiKey: string;
+}
+
+/** Mailgun provider configuration */
+interface IMailgunConfig {
+  apiKey: string;
+  domain: string;
+  region?: 'us' | 'eu';
+}
+
+/** Union type for all provider configurations */
+type EmailProviderConfig = ISmtpConfig | ISendGridConfig | IMailgunConfig;
+
+/** Email configuration interface */
 interface IEmailConfig extends IBaseEntity {
   name: string;
   provider: EmailProviderEnum;
-  config: Record<string, any>;    // Provider-specific config
+  config: EmailProviderConfig;
   fromEmail: string | null;
   fromName: string | null;
   isActive: boolean;
-  isDefault: boolean;             // Set as default configuration
+  isDefault: boolean;
   companyId?: string | null;
 }
 
+/** Create email config DTO */
 interface ICreateEmailConfigDto {
   name: string;
   provider: EmailProviderEnum;
-  config: Record<string, any>;
+  config: EmailProviderConfig;
   fromEmail?: string;
   fromName?: string;
   isActive?: boolean;
   isDefault?: boolean;
 }
 
+/** Update email config DTO */
 interface IUpdateEmailConfigDto extends Partial<ICreateEmailConfigDto> {
   id: string;
 }
 ```
 
-### Provider-Specific Configs
-
-```typescript
-// SMTP
-interface ISmtpConfig {
-  host: string;
-  port: number;
-  secure?: boolean;
-  username: string;
-  password: string;
-}
-
-// SendGrid
-interface ISendGridConfig {
-  apiKey: string;
-}
-
-// Mailgun
-interface IMailgunConfig {
-  apiKey: string;
-  domain: string;
-  region?: 'us' | 'eu';
-}
-```
-
 ### Email Template
 
 ```typescript
+/** Email template interface */
 interface IEmailTemplate extends IBaseEntity {
   name: string;
   slug: string;
@@ -213,11 +223,12 @@ interface IEmailTemplate extends IBaseEntity {
   textContent: string | null;
   schemaVersion: number;
   isActive: boolean;
-  isHtml: boolean;                 // true=HTML mode, false=plain text
+  isHtml: boolean;
   metadata: Record<string, unknown> | null;
   companyId?: string | null;
 }
 
+/** Create email template DTO */
 interface ICreateEmailTemplateDto {
   name: string;
   slug: string;
@@ -231,6 +242,7 @@ interface ICreateEmailTemplateDto {
   metadata?: Record<string, unknown>;
 }
 
+/** Update email template DTO */
 interface IUpdateEmailTemplateDto extends Partial<ICreateEmailTemplateDto> {
   id: string;
 }
@@ -238,55 +250,70 @@ interface IUpdateEmailTemplateDto extends Partial<ICreateEmailTemplateDto> {
 
 ### Email Schema
 
-```typescript
-interface IEmailSchema {
-  id: string;
-  version: string;
-  name: string;
-  subject: string;
-  preheader?: string;
-  sections: IEmailSection[];
-  variables?: IEmailTemplateVariable[];
-  settings?: IEmailSettings;
-}
+**Type Aliases:**
+- `EmailVariableType` = `'string' | 'number' | 'boolean' | 'date'`
+- `EmailSectionType` = `'header' | 'body' | 'footer'`
+- `EmailBlockContent` = `ITextBlockContent | IImageBlockContent | IButtonBlockContent | IDividerBlockContent | IHtmlBlockContent`
 
-interface IEmailSection {
-  id: string;
-  type: 'header' | 'body' | 'footer';
-  name: string;
-  blocks: IEmailBlock[];
-  order: number;
-  style?: IEmailSectionStyle;
-}
+**Block Content Types:**
 
-interface IEmailBlock {
-  id: string;
-  type: EmailBlockType;
-  order: number;
-  content: ITextBlockContent | IImageBlockContent | IButtonBlockContent | IDividerBlockContent | IHtmlBlockContent;
-  style?: IEmailBlockStyle;
-}
+| Interface | Fields |
+|-----------|--------|
+| `ITextBlockContent` | `text`, `html?` |
+| `IImageBlockContent` | `src`, `alt?`, `link?`, `width?`, `height?` |
+| `IButtonBlockContent` | `text`, `link`, `backgroundColor?`, `textColor?`, `borderRadius?` |
+| `IDividerBlockContent` | `height?`, `color?`, `style?` (solid\|dashed\|dotted) |
+| `IHtmlBlockContent` | `html` |
 
-interface IEmailTemplateVariable {
-  name: string;
-  type: 'string' | 'number' | 'boolean' | 'date';
-  required?: boolean;
-  defaultValue?: string;
-  description?: string;
+**Schema Interfaces:**
+
+| Interface | Fields |
+|-----------|--------|
+| `IEmailTemplateVariable` | `name`, `type`, `required?`, `defaultValue?`, `description?` |
+| `IEmailSectionStyle` | `backgroundColor?`, `padding?`, `maxWidth?` |
+| `IEmailBlockStyle` | `textAlign?`, `padding?`, `margin?`, `backgroundColor?` |
+| `IEmailBlock` | `id`, `type`, `order`, `content`, `style?` |
+| `IEmailSection` | `id`, `type`, `name`, `blocks[]`, `order`, `style?` |
+| `IEmailSettings` | `maxWidth?`, `backgroundColor?`, `fontFamily?`, `baseTextColor?` |
+| `IEmailSchema` | `id`, `version`, `name`, `subject`, `preheader?`, `sections[]`, `variables?`, `settings?` |
+
+### Schema Helper Functions
+
+```typescript
+/** Default email settings */
+const DEFAULT_EMAIL_SETTINGS: IEmailSettings = {
+  maxWidth: '600px',
+  backgroundColor: '#f5f5f5',
+  fontFamily: 'Arial, sans-serif',
+  baseTextColor: '#333333',
+};
+
+/** Create a new email schema with default sections */
+function createEmailSchema(partial: Partial<IEmailSchema> = {}): IEmailSchema {
+  return {
+    id: partial.id ?? crypto.randomUUID(),
+    version: partial.version ?? '1.0.0',
+    name: partial.name ?? 'Untitled Template',
+    subject: partial.subject ?? '',
+    preheader: partial.preheader,
+    sections: partial.sections ?? createDefaultSections(),
+    variables: partial.variables ?? [],
+    settings: { ...DEFAULT_EMAIL_SETTINGS, ...partial.settings },
+  };
 }
 ```
 
 ### Email Sending
 
 ```typescript
-// Test send result
+/** Test send result */
 interface ITestSendResult {
   success: boolean;
   messageId?: string;
   error?: string;
 }
 
-// Direct email
+/** Send email request DTO (direct) */
 interface ISendEmailDto {
   to: string | string[];
   cc?: string | string[];
@@ -300,7 +327,7 @@ interface ISendEmailDto {
   emailConfigId?: string;
 }
 
-// Template email
+/** Send template email request DTO */
 interface ISendTemplateEmailDto {
   templateId?: string;
   templateSlug?: string;
@@ -319,46 +346,53 @@ interface ISendTemplateEmailDto {
 
 ## Services
 
-All services are `providedIn: 'root'`. Company scoping is automatic when the company feature is enabled.
-
 ### EmailConfigApiService
 
-Email configuration CRUD. Extends `ApiResourceService<IUpdateEmailConfigDto, IEmailConfig>`.
+Email configuration CRUD. Extends `ApiResourceService<ICreateEmailConfigDto | IUpdateEmailConfigDto, IEmailConfig>`.
 
 ```typescript
 @Injectable({ providedIn: 'root' })
 export class EmailConfigApiService extends ApiResourceService<
-  IUpdateEmailConfigDto,
+  ICreateEmailConfigDto | IUpdateEmailConfigDto,
   IEmailConfig
 > {
+  private readonly appConfig = inject<IAppConfig>(APP_CONFIG);
+
   constructor() {
-    const http = inject(HttpClient);
-    super('email/email-config', http);
+    // Resource name, HttpClient, service prefix
+    super('email-config', inject(HttpClient), 'email');
   }
 
   /** Send test email to verify configuration */
   sendTest(configId: string, recipient: string): Observable<ISingleResponse<ITestSendResult>> {
+    const emailBaseUrl = getServiceUrl(this.appConfig, 'email');
     return this.http.post<ISingleResponse<ITestSendResult>>(
-      `${this.baseUrl.replace('/email-config', '')}/send/test`,
+      `${emailBaseUrl}/send/test`,
       { emailConfigId: configId, recipient },
     );
   }
 }
 ```
 
+**Inherited Methods from ApiResourceService:**
+- `getAll(search, queryParams)` - List with pagination
+- `findByIdAsync(id)` - Get single by ID
+- `insertAsync(dto)` - Create new
+- `updateAsync(dto)` - Update existing
+- `deleteAsync({ id, type })` - Delete
+
 ### EmailTemplateApiService
 
-Email template CRUD. Extends `ApiResourceService<IUpdateEmailTemplateDto, IEmailTemplate>`.
+Email template CRUD. Extends `ApiResourceService<ICreateEmailTemplateDto | IUpdateEmailTemplateDto, IEmailTemplate>`.
 
 ```typescript
 @Injectable({ providedIn: 'root' })
 export class EmailTemplateApiService extends ApiResourceService<
-  IUpdateEmailTemplateDto,
+  ICreateEmailTemplateDto | IUpdateEmailTemplateDto,
   IEmailTemplate
 > {
   constructor() {
-    const http = inject(HttpClient);
-    super('email/email-template', http);
+    super('email-template', inject(HttpClient), 'email');
   }
 
   /** Get template by slug (POST-only RPC pattern) */
@@ -373,268 +407,157 @@ export class EmailTemplateApiService extends ApiResourceService<
 
 ### EmailSendService
 
-Handles email sending operations.
+Handles email sending operations. Uses `getServiceUrl` from `@flusys/ng-core` for dynamic endpoint resolution.
 
 ```typescript
 @Injectable({ providedIn: 'root' })
 export class EmailSendService {
   private readonly http = inject(HttpClient);
-  private readonly baseUrl = `${inject(APP_CONFIG).apiBaseUrl}/email/send`;
+  private readonly appConfig = inject<IAppConfig>(APP_CONFIG);
+  private readonly baseUrl = `${getServiceUrl(this.appConfig, 'email')}/send`;
 
   /** Send email directly (without template) */
-  sendDirect(dto: ISendEmailDto): Observable<ISingleResponse<ITestSendResult>>;
+  sendDirect(dto: ISendEmailDto): Observable<ISingleResponse<ITestSendResult>> {
+    return this.http.post<ISingleResponse<ITestSendResult>>(
+      `${this.baseUrl}/direct`,
+      dto,
+    );
+  }
 
   /** Send email using template */
-  sendTemplate(dto: ISendTemplateEmailDto): Observable<ISingleResponse<ITestSendResult>>;
+  sendTemplate(dto: ISendTemplateEmailDto): Observable<ISingleResponse<ITestSendResult>> {
+    return this.http.post<ISingleResponse<ITestSendResult>>(
+      `${this.baseUrl}/template`,
+      dto,
+    );
+  }
 }
 ```
 
 ### EmailBuilderStateService
 
-Manages email builder UI state. Should be provided at component level, not root.
+Manages email builder UI state. **Provided at component level**, not root.
 
 ```typescript
-@Injectable()
+@Injectable()  // NOT providedIn: 'root'
 export class EmailBuilderStateService {
-  // Schema state
-  readonly schema: Signal<IEmailSchema>;
-  readonly isDirty: Signal<boolean>;
-
-  // Selection state
-  readonly selectedSectionId: Signal<string | null>;
-  readonly selectedBlockId: Signal<string | null>;
-
-  // Computed signals
-  readonly sections: Signal<IEmailSection[]>;
-  readonly headerSection: Signal<IEmailSection | null>;
-  readonly bodySection: Signal<IEmailSection | null>;
-  readonly footerSection: Signal<IEmailSection | null>;
-
-  // Methods
-  loadSchema(schema: IEmailSchema): void;
-  createNewSchema(name?: string): void;
-  addBlock(sectionId: string, blockType: EmailBlockType): string | null;
-  updateBlock(sectionId: string, blockId: string, updates: Partial<IEmailBlock>): void;
-  deleteBlock(sectionId: string, blockId: string): void;
+  // =========================================
+  // Private Writable Signals
+  // =========================================
+  private readonly _schema = signal<IEmailSchema>(createEmailSchema());
+  private readonly _isDirty = signal(false);
+  private readonly _selectedSectionId = signal<string | null>(null);
+  private readonly _selectedBlockId = signal<string | null>(null);
+  private readonly _viewMode = signal<'visual' | 'html'>('visual');
+
+  // =========================================
+  // Public Readonly Signals
+  // =========================================
+  readonly schema = this._schema.asReadonly();
+  readonly isDirty = this._isDirty.asReadonly();
+  readonly selectedSectionId = this._selectedSectionId.asReadonly();
+  readonly selectedBlockId = this._selectedBlockId.asReadonly();
+  readonly viewMode = this._viewMode.asReadonly();
+
+  // Computed Signals
+  readonly sections = computed(() => this._schema().sections);
+  readonly templateName = computed(() => this._schema().name);
+  readonly subject = computed(() => this._schema().subject);
+  readonly settings = computed(() => this._schema().settings ?? DEFAULT_EMAIL_SETTINGS);
+  readonly variables = computed(() => this._schema().variables ?? []);
+  readonly headerSection = computed(() => this.sections().find((s) => s.type === 'header') ?? null);
+  readonly bodySection = computed(() => this.sections().find((s) => s.type === 'body') ?? null);
+  readonly footerSection = computed(() => this.sections().find((s) => s.type === 'footer') ?? null);
+  readonly selectedSection = computed(() => /* finds section by _selectedSectionId */);
+  readonly selectedBlock = computed(() => /* finds block by _selectedBlockId across sections */);
+  readonly allBlocks = computed(() => this.sections().flatMap((s) => s.blocks));
+
+  // Methods documented in table below
 }
 ```
 
+**Methods:**
+
+| Category | Method | Description |
+|----------|--------|-------------|
+| Schema | `loadSchema(schema)` | Load existing schema into builder |
+| Schema | `createNewSchema(name?)` | Create new empty schema |
+| Schema | `updateSchemaMeta(updates)` | Update name, subject, preheader, settings, variables |
+| Schema | `markAsSaved()` | Clear dirty flag |
+| Schema | `setViewMode(mode)` | Set 'visual' or 'html' mode |
+| Section | `updateSection(sectionId, updates)` | Update section properties |
+| Block | `addBlock(sectionId, blockType, block?)` | Add block, returns block ID |
+| Block | `updateBlock(sectionId, blockId, updates)` | Update block properties |
+| Block | `deleteBlock(sectionId, blockId)` | Delete block from section |
+| Block | `reorderBlocks(sectionId, from, to)` | Reorder blocks within section |
+| Block | `duplicateBlock(sectionId, blockId)` | Duplicate block, returns new ID |
+| Selection | `selectSection(sectionId)` | Select section (clears block selection) |
+| Selection | `selectBlock(blockId)` | Select block (auto-selects parent section) |
+| Selection | `clearSelection()` | Clear all selection |
+
+**Default Block Content:**
+
+| Block Type | Default Content |
+|------------|-----------------|
+| TEXT | `{ text: 'Enter your text here...', html: '<p>Enter your text here...</p>' }` |
+| IMAGE | `{ src: '', alt: 'Image' }` |
+| BUTTON | `{ text: 'Click Here', link: 'https://', backgroundColor: '#007bff', textColor: '#ffffff', borderRadius: '4px' }` |
+| DIVIDER | `{ height: '1px', color: '#cccccc', style: 'solid' }` |
+| HTML | `{ html: '<!-- Custom HTML -->' }` |
+
 ---
 
 ## Components
 
 All components are standalone, use Angular 21 signals, OnPush change detection, and lazy-load via routes.
 
-### EmailContainerComponent
-
-Main container with tab navigation between Templates and Configurations.
-
-**Features:**
-- Responsive page title (`text-xl sm:text-2xl`)
-- Tab navigation with horizontal scroll on mobile
-- Router outlet for child routes
+### Component Overview
 
-```html
-<div class="p-2 sm:p-4">
-  <h1 class="text-xl sm:text-2xl font-bold m-0">Email</h1>
-  <p class="text-sm text-muted-color mt-1">Manage email templates...</p>
+| Component | Purpose | Key Features |
+|-----------|---------|--------------|
+| `EmailContainerComponent` | Tab container | Permission-filtered tabs, horizontal scroll, router outlet |
+| `EmailConfigListComponent` | Config list | Lazy pagination, provider metadata badges, test dialog |
+| `EmailConfigFormComponent` | Config form | Dynamic provider fields, type guards, signal-based form |
+| `TemplateListComponent` | Template list | Lazy pagination, variable extraction, test send dialog |
+| `TemplateFormComponent` | Template form | Angular Signal Forms, HTML/Text toggle, live preview |
 
-  <div class="scrollbar-hide flex gap-1 mb-4 border-b border-surface overflow-x-auto">
-    @for (tab of tabs; track tab.id) {
-      <a [routerLink]="tab.route" routerLinkActive="tab-active">...</a>
-    }
-  </div>
+### EmailContainerComponent
 
-  <router-outlet />
-</div>
-```
+Filters tabs using `PermissionValidatorService.hasPermission()`. Tabs: Templates (`EMAIL_TEMPLATE_PERMISSIONS.READ`), Configurations (`EMAIL_CONFIG_PERMISSIONS.READ`).
 
 ### EmailConfigListComponent
 
-Lists email configurations with actions.
-
-**Features:**
-- Lazy pagination via `p-table` with `[paginator]="totalRecords() > 0"`
-- Horizontal scroll on mobile (`overflow-x-auto -mx-4 sm:mx-0`)
-- Provider type tags (SMTP, SendGrid, Mailgun)
-- Active/Inactive status badges
-- Default configuration badge
-- Test button with dialog for recipient input
-- Edit and delete actions
-- Company info display when enabled
-
-**Test Dialog:**
-
-```typescript
-showTestDialog = false;  // Plain property for ngModel
-readonly selectedConfig = signal<IEmailConfig | null>(null);
-readonly isSendingTest = signal(false);
-testRecipient = '';
-
-onTest(config: IEmailConfig): void {
-  this.selectedConfig.set(config);
-  this.testRecipient = '';
-  this.showTestDialog = true;
-}
+**Provider Metadata:** SMTP (`pi pi-server`, info), SendGrid (`pi pi-cloud`, success), Mailgun (`pi pi-cloud`, warn). Default icon: `pi pi-envelope`.
 
-async sendTestEmail(): Promise<void> {
-  const config = this.selectedConfig();
-  if (!config || !this.testRecipient) return;
-
-  const response = await firstValueFrom(
-    this.configService.sendTest(config.id, this.testRecipient)
-  );
-
-  if (response.data?.success) {
-    this.messageService.add({
-      severity: 'success',
-      summary: 'Success',
-      detail: `Test email sent! Message ID: ${response.data.messageId}`,
-    });
-    this.showTestDialog = false;
-  }
-}
-```
+**Signals:** `isLoading`, `configs`, `totalRecords`, `pageSize`, `first`, `showTestDialog`, `selectedConfig`, `isSendingTest`, `testRecipient`.
 
 ### EmailConfigFormComponent
 
-Create/edit email configuration with dynamic provider fields.
+**Type Guards:** `isSmtpConfig` (`'host' in config && 'auth' in config`), `isSendGridConfig` (`'apiKey' in config && !('domain' in config)`), `isMailgunConfig` (`'apiKey' in config && 'domain' in config`).
 
-**Features:**
-- Responsive grid layout (`grid-cols-1 md:grid-cols-2`)
-- Dynamic form fields based on selected provider
-- SMTP: host, port, secure toggle, username, password
-- SendGrid: apiKey (masked input)
-- Mailgun: apiKey, domain, region
-- Active toggle and Set as Default toggle
-- Form actions right-aligned at bottom
-- Create/Edit mode auto-detection
+**Form Pattern:** Private signal with flattened provider fields, public getter, typed `updateFormModel<K>()` method.
 
 ### TemplateListComponent
 
-Lists email templates with test send functionality.
-
-**Features:**
-- Lazy pagination with conditional display
-- Responsive table with hidden columns on mobile
-- HTML/Text type badges (based on `isHtml`)
-- Active/Inactive status badges
-- Test send with dynamic variables
-- Edit and delete actions
-
-**Test Send Dialog with Variables:**
-
-```typescript
-/** Extract variables from template content */
-readonly templateVariables = computed(() => {
-  const template = this.selectedTemplate();
-  if (!template) return [];
-
-  const content = [
-    template.subject,
-    template.htmlContent,
-    template.textContent || '',
-  ].join(' ');
-
-  const matches = content.matchAll(/\{\{(\w+)\}\}/g);
-  const variables = new Set<string>();
-
-  for (const match of matches) {
-    variables.add(match[1]);
-  }
-
-  return Array.from(variables).sort();
-});
-
-variableValues: Record<string, string> = {};
-```
+**Variable Extraction:** Computed signal extracts `{{variableName}}` patterns via `matchAll(/\{\{(\w+)\}\}/g)`, deduplicates with Set, returns sorted array.
 
 ### TemplateFormComponent
 
-Create/edit email template with HTML/Plain Text toggle and live preview.
-
-**Features:**
-- Responsive form grid (`grid-cols-1 md:grid-cols-2`)
-- Name, slug, subject, description fields
-- Subject line with variable support hint
-- Editor Mode Toggle (HTML/Plain Text buttons)
-- Same height content editor and preview (`h-[400px]`)
-- Horizontal scroll for code (`wrap="off"`)
-- Live HTML preview in iframe with white background
-- Content sync between modes when switching
-- Active toggle
-- Form actions right-aligned at bottom
+Uses Angular Signal Forms (`form`, `FormField`, `required` from `@angular/forms/signals`). Integrates with `EmailBuilderStateService` for schema management.
 
-**Preview with Light Background:**
-
-```typescript
-getPreviewHtml(): string {
-  const baseStyles = `
-    <style>
-      body {
-        font-family: Arial, sans-serif;
-        margin: 16px;
-        background-color: #ffffff;
-        color: #333333;
-      }
-      img { max-width: 100%; height: auto; }
-    </style>
-  `;
-  return baseStyles + (this.formModel.htmlContent || '');
-}
-```
+**Content Conversion:** Auto-syncs when switching modes. `textToHtml()` wraps in `<p>`, `htmlToPlainText()` uses `DOMParser` for XSS-safe parsing. Preview renders in sandboxed iframe.
 
 ---
 
 ## Responsive Design Patterns
 
-### Tables
-
-```html
-<!-- Horizontal scroll wrapper -->
-<div class="overflow-x-auto -mx-4 sm:mx-0">
-  <p-table
-    [paginator]="totalRecords() > 0"
-    styleClass="p-datatable-sm"
-    [tableStyle]="{ 'min-width': '50rem' }"
-  >
-    <!-- Hidden columns on smaller screens -->
-    <th class="hidden md:table-cell">Slug</th>
-    <th class="hidden lg:table-cell">Subject</th>
-    <th class="hidden xl:table-cell">Created</th>
-  </p-table>
-</div>
-```
-
-### Forms
-
-```html
-<!-- Responsive grid -->
-<div class="grid grid-cols-1 md:grid-cols-2 gap-4">
-  <div class="field">...</div>
-  <div class="field md:col-span-2">...</div>  <!-- Full width on all screens -->
-</div>
-
-<!-- Form actions -->
-<div class="flex justify-end gap-2 mt-6 pt-4 border-t border-surface">
-  <p-button label="Cancel" severity="secondary" [outlined]="true" routerLink="../" />
-  <p-button [label]="isEditMode() ? 'Update' : 'Create'" icon="pi pi-save" />
-</div>
-```
-
-### Headers
-
-```html
-<div class="flex flex-col sm:flex-row justify-between items-start sm:items-center gap-3 mb-4">
-  <div>
-    <h3 class="text-lg sm:text-xl font-semibold m-0">Title</h3>
-    @if (showCompanyInfo()) {
-      <p class="text-sm text-muted-color mt-1">Company: {{ currentCompanyName() }}</p>
-    }
-  </div>
-  <p-button label="Action" styleClass="w-full sm:w-auto" />
-</div>
-```
+| Pattern | Implementation |
+|---------|----------------|
+| **Tables** | `overflow-x-auto -mx-4 sm:mx-0` wrapper, `[lazy]="true"`, `[paginator]="totalRecords() > 0"`, hidden columns: `hidden md:table-cell` |
+| **Forms** | `grid grid-cols-1 md:grid-cols-2 gap-4`, full-width: `md:col-span-2` |
+| **Headers** | `flex flex-col sm:flex-row justify-between items-start sm:items-center gap-3` |
+| **Buttons** | `styleClass="w-full sm:w-auto"` |
+| **Dialogs** | `{ width: '95vw', maxWidth: '500px' }`, `[breakpoints]="{ '575px': '95vw' }"` |
 
 ---
 
@@ -649,90 +572,40 @@ All components use PrimeNG/Tailwind dark mode classes:
 | Backgrounds | `bg-surface-0 dark:bg-surface-900`, `bg-surface-100 dark:bg-surface-700` |
 | Code blocks | `bg-surface-100 dark:bg-surface-700` |
 | Hover states | `hover:bg-surface-hover` |
+| Surface ground | `bg-surface-ground` |
 
 ---
 
 ## Usage Examples
 
-### Send Direct Email
-
 ```typescript
-import { EmailSendService } from '@flusys/ng-email';
+import { EmailSendService, EmailConfigApiService, EmailTemplateApiService, EmailBuilderStateService, EmailBlockType } from '@flusys/ng-email';
 
+// Inject services
 private readonly emailSendService = inject(EmailSendService);
-
-async sendEmail(): Promise<void> {
-  const response = await firstValueFrom(
-    this.emailSendService.sendDirect({
-      to: 'user@example.com',
-      subject: 'Hello!',
-      html: '<h1>Hello World</h1>',
-      text: 'Hello World',
-      emailConfigId: 'config-id',
-    })
-  );
-
-  if (response.data?.success) {
-    console.log('Sent! Message ID:', response.data.messageId);
-  }
-}
-```
-
-### Send Template Email
-
-```typescript
-async sendTemplateEmail(): Promise<void> {
-  const response = await firstValueFrom(
-    this.emailSendService.sendTemplate({
-      templateId: 'template-id',
-      to: 'user@example.com',
-      emailConfigId: 'config-id',
-      variables: {
-        userName: 'John',
-        appName: 'My App',
-        verificationLink: 'https://example.com/verify/abc123',
-      },
-    })
-  );
-
-  if (response.data?.success) {
-    console.log('Sent! Message ID:', response.data.messageId);
-  }
-}
-```
-
-### Test Configuration
-
-```typescript
-import { EmailConfigApiService } from '@flusys/ng-email';
-
 private readonly configService = inject(EmailConfigApiService);
+private readonly templateService = inject(EmailTemplateApiService);
 
-async testConfig(configId: string, recipient: string): Promise<boolean> {
-  const response = await firstValueFrom(
-    this.configService.sendTest(configId, recipient)
-  );
-
-  return response.data?.success ?? false;
-}
-```
-
-### Get Template by Slug
+// Send direct email
+const res1 = await firstValueFrom(this.emailSendService.sendDirect({
+  to: 'user@example.com', subject: 'Hello!', html: '<h1>Hello</h1>', emailConfigId: 'config-id'
+}));
 
-```typescript
-import { EmailTemplateApiService } from '@flusys/ng-email';
-
-private readonly templateService = inject(EmailTemplateApiService);
+// Send template email (prefer templateSlug over templateId)
+const res2 = await firstValueFrom(this.emailSendService.sendTemplate({
+  templateSlug: 'welcome-email', to: 'user@example.com', emailConfigId: 'config-id',
+  variables: { userName: 'John', appName: 'My App' }
+}));
 
-async getTemplate(slug: string): Promise<IEmailTemplate | null> {
-  const response = await firstValueFrom(
-    this.templateService.getBySlug(slug)
-  );
+// Test configuration
+const success = (await firstValueFrom(this.configService.sendTest(configId, recipient))).data?.success;
 
-  return response.data ?? null;
-}
+// Get template by slug
+const template = (await firstValueFrom(this.templateService.getBySlug('welcome-email'))).data;
 ```
 
+**Using EmailBuilderStateService:** Provide at component level, access signals (`headerSection`, `bodySection`), methods: `loadSchema()`, `addBlock(sectionId, EmailBlockType.TEXT)`, `updateBlock(sectionId, blockId, { content })`.
+
 ---
 
 ## Backend Integration
@@ -760,113 +633,34 @@ All endpoints use **POST-only RPC** style (not REST).
 
 ## Best Practices
 
-### 1. Use Template Slugs for Code References
-
-```typescript
-// ✅ Use slug for programmatic access
-await this.emailSendService.sendTemplate({
-  templateSlug: 'welcome-email',  // Stable identifier
-  ...
-});
-
-// ❌ Don't hardcode template IDs
-await this.emailSendService.sendTemplate({
-  templateId: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',  // May change
-  ...
-});
-```
-
-### 2. Provide Both HTML and Text Content
-
-```typescript
-// ✅ Provide both for maximum compatibility
-{
-  isHtml: true,
-  htmlContent: '<h1>Hello!</h1>',
-  textContent: 'Hello!',  // Fallback for text-only clients
-}
-```
-
-### 3. Test Configurations Before Production
-
-Always use the test send feature to verify configurations work before using them in production.
-
-### 4. Use Meaningful Variable Names
-
-```typescript
-// ✅ Clear, descriptive variable names
-"Hello {{userName}}, your order #{{orderNumber}} shipped on {{shipDate}}."
-
-// ❌ Vague or abbreviated names
-"Hello {{u}}, order {{o}} shipped {{d}}."
-```
-
-### 5. Handle Send Failures Gracefully
-
-```typescript
-async sendEmail(): Promise<void> {
-  try {
-    const response = await firstValueFrom(
-      this.emailSendService.sendTemplate({ ... })
-    );
-
-    if (response.data?.success) {
-      this.messageService.add({
-        severity: 'success',
-        summary: 'Email Sent',
-        detail: `Message ID: ${response.data.messageId}`,
-      });
-    } else {
-      this.messageService.add({
-        severity: 'error',
-        summary: 'Send Failed',
-        detail: response.data?.error || 'Unknown error occurred',
-      });
-    }
-  } catch (error: any) {
-    this.messageService.add({
-      severity: 'error',
-      summary: 'Error',
-      detail: error?.message || 'Failed to send email.',
-    });
-  }
-}
-```
+| Practice | Description |
+|----------|-------------|
+| **Use Template Slugs** | Use `templateSlug: 'welcome-email'` instead of hardcoded UUIDs |
+| **Provide Both Content Types** | Include both `htmlContent` and `textContent` for email client compatibility |
+| **Test Before Production** | Always use test send feature to verify configurations |
+| **Meaningful Variable Names** | Use `{{userName}}` not `{{u}}` - clear, descriptive names |
+| **Handle Failures** | Check `response.data?.success`, show toast on error (HTTP errors handled by global interceptor) |
+| **Signal-Based Forms** | See [EmailConfigFormComponent](#emailconfigformcomponent) for zoneless pattern |
+| **Component-Level StateService** | `providers: [EmailBuilderStateService]` - never `providedIn: 'root'` |
 
 ---
 
 ## Public API Exports
 
-```typescript
-// Enums
-export { EmailProviderEnum } from '@flusys/ng-email';
-export { EmailBlockType } from '@flusys/ng-email';
-
-// Interfaces
-export {
-  IEmailConfig, ICreateEmailConfigDto, IUpdateEmailConfigDto,
-  ISmtpConfig, ISendGridConfig, IMailgunConfig,
-  IEmailTemplate, ICreateEmailTemplateDto, IUpdateEmailTemplateDto,
-  IEmailSchema, IEmailSection, IEmailBlock, IEmailTemplateVariable,
-  ISendEmailDto, ISendTemplateEmailDto, ITestSendResult,
-} from '@flusys/ng-email';
-
-// Services
-export {
-  EmailConfigApiService,
-  EmailTemplateApiService,
-  EmailSendService,
-  EmailBuilderStateService,
-} from '@flusys/ng-email';
-
-// Components
-export { EmailContainerComponent } from '@flusys/ng-email';
-
-// Routes
-export { EMAIL_ROUTES } from '@flusys/ng-email';
-```
+| Category | Exports |
+|----------|---------|
+| **Enums** | `EmailProviderEnum`, `EmailBlockType` |
+| **Config Interfaces** | `IEmailConfig`, `ICreateEmailConfigDto`, `IUpdateEmailConfigDto`, `ISmtpAuth`, `ISmtpConfig`, `ISendGridConfig`, `IMailgunConfig`, `EmailProviderConfig` |
+| **Template Interfaces** | `IEmailTemplate`, `ICreateEmailTemplateDto`, `IUpdateEmailTemplateDto` |
+| **Schema Interfaces** | `IEmailSchema`, `IEmailSection`, `IEmailBlock`, `IEmailTemplateVariable`, `IEmailSettings`, `IEmailSectionStyle`, `IEmailBlockStyle`, `ITextBlockContent`, `IImageBlockContent`, `IButtonBlockContent`, `IDividerBlockContent`, `IHtmlBlockContent`, `EmailBlockContent`, `EmailVariableType`, `EmailSectionType` |
+| **Send Interfaces** | `ISendEmailDto`, `ISendTemplateEmailDto`, `ITestSendResult` |
+| **Constants** | `DEFAULT_EMAIL_SETTINGS`, `createEmailSchema` |
+| **Services** | `EmailConfigApiService`, `EmailTemplateApiService`, `EmailSendService`, `EmailBuilderStateService` |
+| **Components** | `EmailContainerComponent` |
+| **Routes** | `EMAIL_ROUTES` |
 
 ---
 
-**Last Updated:** 2026-02-21
+**Last Updated:** 2026-02-25
+**Version:** 3.0.0
 **Angular Version:** 21