@useinsider/guido 1.4.4-beta.b4adc85 → 1.4.4

package/README.md

@@ -4,420 +4,789 @@
   </a>
 </p>
 
+
 # @useinsider/guido
 
-Guido is a Vue 2 + TypeScript wrapper for the Stripo Email Editor plugin. Easily embed the professional email editor in your Vue applications with a clean, type-safe configuration.
+Guido is a Vue 2 + TypeScript wrapper for the Stripo Email Editor plugin. Easily embed the professional email editor in your Vue applications with a clean, customizable interface.
 
-## Installation
+## 📦 Install
 
 ```bash
 npm install @useinsider/guido
 ```
-
 ### Prerequisites
-
-Your project needs:
-- Vue 2.7+
-- Pinia (state management)
-
-Add these to your bundler config to optimize dependencies:
-
-**Webpack** (`webpack.config.js` or `vue.config.js`):
-```js
-shared: {
-  vue: { singleton: true },
-  pinia: { singleton: true },
-},
-```
-
-**Vite** (`vite.config.js`):
-```js
-resolve: {
-  dedupe: ['vue', 'pinia'],
-},
-```
-
+  🍍 Your project should have `pinia`
+  You need to be sure those lines added in your config file:
+  
+  ℹ️ It helps to optimize your dependencies and sharing by Guido. This is why Guido pretty fast and tiny.
+
+  #### For Webpack
+  `/webpack.config.js` or `/vue.config.js`
+  ```js
+  // ... Previous Configs
+  shared: {
+    vue: { singleton: true },
+    pinia: { singleton: true },
+  },
+  // ... Upcoming Configs
+  ```
+
+  ##### For Vite: 
+  `/vite.config.js`
+  ```js
+  // ... Previous Configs
+  resolve: {
+    dedupe: ['vue', 'pinia'],
+  },
+  // ... Upcoming Configs
+  ```
 ---
+## 🚀 Usage
 
-## Quick Start
+### Basic Usage
 
-```vue
+```html
 <template>
-  <Guido
-    ref="guidoRef"
-    :config="config"
-    @ready="onReady"
-    @dynamic-content:open="onDynamicContentOpen"
-    @save:complete="onSaveComplete"
-  />
+  <div>
+    <Guido
+      ref="guidoEditor"
+      :template-id="templateId"
+      :user-id="userId"
+      :migration-date="migrationDate"
+      :guido-config="guidoConfig"
+      :html="initialHtml"
+      :css="initialCss"
+      @dynamic-content:open="handleDynamicContentOpen"
+      @back="handleBack"
+      @save:start="handleSaveStart"
+      @save:complete="handleSaveComplete"
+    />
+  </div>
 </template>
 
-<script setup lang="ts">
-import { ref } from 'vue';
+<script lang="ts">
 import { Guido } from '@useinsider/guido';
-import type { GuidoConfigInput } from '@useinsider/guido';
-
-const guidoRef = ref<InstanceType<typeof Guido> | null>(null);
 
-const config = ref<GuidoConfigInput>({
-  identity: {
-    templateId: 'template-123',
-    userId: 'user-456',
-  },
-  partner: {
-    name: 'your-partner-name',
+export default {
+  components: {
+    Guido
   },
-  template: {
-    html: '<p>Initial content</p>',
-    css: '',
+  data() {
+    return {
+      templateId: 'template-123',
+      userId: 'user-456',
+      migrationDate: 1699488000,
+      initialHtml: '<p>Initial HTML content</p>',
+      initialCss: 'p { color: #333; }',
+      guidoConfig: {
+        translationsPath: 'window.trans.en',
+        htmlCompilerRules: [],
+        ignoreDefaultHtmlCompilerRules: false,
+        backButtonLabel?: "Back to Design",
+        features: {
+          dynamicContent: true,
+          saveAsTemplate: true,
+          versionHistory: true,
+          testMessage: true
+        }
+      },
+      dynamicContentModalVisible: false
+    };
   },
-});
 
-const onReady = () => console.log('Editor ready');
-const onDynamicContentOpen = () => console.log('Dynamic content requested');
-const onSaveComplete = (template) => console.log('Saved:', template);
+  methods: {
+    handleDynamicContentOpen(detail) {
+      console.log('Dynamic content requested:', detail);
+      this.dynamicContentModalVisible = true;
+    },
+    
+    handleBack() {
+      console.log('User clicked back button');
+      // Handle navigation back
+    },
+    
+    handleSaveStart() {
+      console.log('Save process started');
+      // Show loading indicator
+    },
+    
+    handleSaveComplete(template) {
+      console.log('Save completed:', template);
+      // Handle saved template data
+    },
+    
+    // ⚠️ Your own Dynamic Content Modal should have this id: #guido-dynamic-content-modal
+    handleDynamicContentInsert() {
+      this.$refs.guidoEditor?.dynamicContent.insert({
+        text: 'Display Text', 
+        value: 'actual-value', 
+        fallback: 'Fallback Text'
+      });
+
+      this.dynamicContentModalVisible = false;
+    },
+    
+    // ⚠️ It's mandatory. There is no way to understand if user closes the modal without selection.
+    handleDynamicContentClose() {
+      this.$refs.guidoEditor?.dynamicContent.close();
+    },
+
+    // If you need to trigger save manually like leave modal cases, you can use this method.
+    save () {
+      this.$refs.guidoEditor?.saveSilent();
+    }
+  }
+};
 </script>
 ```
 
----
-
-## Configuration
-
-Guido uses a single, validated `config` prop organized by domain:
-
-```typescript
-import type { GuidoConfigInput } from '@useinsider/guido';
-
-const config: GuidoConfigInput = {
-  // Required: Identity
-  identity: {
-    templateId: string,      // Required - Template identifier
-    userId: string,          // Required - User identifier
-    variationId?: string,    // Optional - A/B test variation
-  },
+## 📚 API
 
-  // Required: Partner
-  partner: {
-    name: string,            // Required - Partner name
-    productType?: number,    // Optional - Default: 60 (Email)
-    messageType?: number,    // Optional - Default: 1 (Promotional)
-    username?: string,       // Optional - Default: 'Guido User'
-  },
+### Guido Component Props
 
-  // Optional: Template content
-  template?: {
-    html?: string,
-    css?: string,
-    preselectedDynamicContent?: DynamicContent[],
-    selectedUnsubscribePages?: number[],
-  },
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `templateId` | `string` | ✅ | - | Unique identifier for the email template |
+| `userId` | `string` | ✅ | - | Unique identifier for the user |
+| `guidoConfig` | `GuidoConfig` | ✅ | - | Configuration object for the editor |
+| `migrationDate` | `number` | ✅ | - | Stripo migration date in Unix timestamp (seconds). Retrieved from backend `/partner-settings` endpoint as `migrationDate`. Used for onboarding process |
+| `partnerName` | `string` | ⚪ | From URL host | Partner identifier |
+| `productType` | `string` | ⚪ | From URL path | Product type identifier |
+| `username` | `string` | ⚪ | `'Guido User'` | Display name for the user |
+| `html` | `string` | ⚪ | `''` | Initial HTML content for the template |
+| `css` | `string` | ⚪ | `''` | Initial CSS styles for the template |
 
-  // Optional: Editor settings
-  editor?: {
-    locale?: string,              // Default: 'en'
-    translationsPath?: string,    // Default: 'window.trans.en'
-    migrationDate?: number,       // Stripo migration timestamp
-    emailHeader?: {
-      senderName?: string,
-      subject?: string,
-    },
-  },
+### Guido Component Events
 
-  // Optional: UI settings
-  ui?: {
-    showHeader?: boolean,         // Default: true
-    backButtonLabel?: string,
-  },
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `dynamic-content:open` | `DynamicContent \| null` | Fired when user requests to insert dynamic content |
+| `back` | - | Fired when user clicks the back button |
+| `save:start` | - | Fired when the save process begins |
+| `save:complete` | `Omit<Template, 'forceRecreate'>` | Fired when template is successfully saved |
+| `on-change` | void | It Fires once for managing leave modal etc. |
+| `ready` | void | Fired when the editor is ready and template is loaded |
+| `onboarding-finished` | void | Fired when the onboarding popup is dismissed or completed, allowing parent applications to track onboarding state |
+| `test-email:click` | - | Fired when user clicks the test email button in the header |
+
+### Guido Exposed Methods
+```typescript
+dynamicContent.insert(DynamicContent);
+dynamicContent.close();
+saveSilent();
+```
 
-  // Optional: Feature toggles
-  features?: {
-    dynamicContent?: boolean,     // Default: true
-    saveAsTemplate?: boolean,     // Default: true
-    versionHistory?: boolean,     // Default: true
-    testMessage?: boolean,        // Default: true
-    displayConditions?: boolean,  // Default: true
-    unsubscribe?: boolean,        // Default: true
-  },
+### Guido Interfaces
 
-  // Optional: Block configuration
+```typescript
+interface GuidoConfig {
+  translationsPath: string;
+  htmlCompilerRules?: CompilerRule[];
+  ignoreDefaultHtmlCompilerRules?: boolean;
+  useHeader: boolean
+  emailHeader: {
+    senderName: string;
+    subject: string;
+  };
+  partner: {
+    partnerName: string;
+    productType: number;
+    messageType: number;
+  };
+  features: {
+    dynamicContent: boolean;
+    saveAsTemplate: boolean;
+    versionHistory: boolean;
+    testMessage: boolean;
+    displayConditions: boolean;
+  };
   blocks?: {
-    excludeDefaults?: DefaultBlockType[],
-    includeCustoms?: CustomBlockType[],
-  },
-
-  // Optional: HTML compiler
-  compiler?: {
-    customRules?: CompilerRule[],
-    ignoreDefaultRules?: boolean,  // Default: false
-  },
-};
+    excludeDefaults?: GuidoBlockType[];
+    includeCustoms?: GuidoCustomBlockType[];
+  };
+}
 ```
 
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `translationsPath` | `string` | `'window.trans.en'` | JavaScript path to the translations object |
+| `htmlCompilerRules` | `CompilerRule[]` | `[]` | Additional compiler rules to apply to HTML content. See [HTML Compiler Rules](#-html-compiler-rules) section below |
+| `ignoreDefaultHtmlCompilerRules` | `boolean` | `false` | Skip default compiler rules and only use custom rules. Default rules: `src/config/compiler/htmlCompilerRules.ts` |
+| `useHeader` | `boolean` | `true` | Adds extra spaces to height for adjusting. If you don't use Inone Page header, override as `false` |
+| `features` | `Features` | `{ dynamicContent: true, saveAsTemplate: true, versionHistory: true }` | Feature flags to enable/disable editor functionality |
+| `features.dynamicContent` | `boolean` | `true` | Enable dynamic content insertion feature |
+| `features.saveAsTemplate` | `boolean` | `true` | Enable save as template feature |
+| `features.versionHistory` | `boolean` | `true` | Enable version history feature |
+| `features.displayConditions` | `boolean` | `true` | Enable display conditions |
+| `blocks` | `BlocksConfig` | `{ excludeDefaults: [], includeCustoms: [] }` | Block configuration for excluding default blocks and including custom blocks. See [Blocks Configuration](#-blocks-configuration) section below |
+| `blocks.excludeDefaults` | `GuidoBlockType[]` | `[]` | Array of default Stripo blocks to exclude from the editor |
+| `blocks.includeCustoms` | `GuidoCustomBlockType[]` | `[]` | Array of custom blocks to include in the editor |
+
+```typescript
+interface DynamicContent {
+  value: string;
+  text: string;
+  fallback?: string;
+}
+```
 ---
 
-## Events
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | `string` | '' | Value of the dynamic content |
+| `text` | `string` | '' | Visible value of the dynamic content |
+| `fallback?` | `string` | '' | Fallback value of the dynamic content. Optional |
 
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `ready` | - | Editor is loaded and ready |
-| `dynamic-content:open` | `DynamicContent \| null` | User wants to insert dynamic content |
-| `back` | - | Back button clicked |
-| `save:start` | - | Save process started |
-| `save:complete` | `Template` | Save completed successfully |
-| `on-change` | - | Template was modified |
-| `test-email:click` | - | Test email button clicked |
-| `onboarding-finished` | - | Onboarding popup dismissed |
+## 🧱 Blocks Configuration
 
----
+Guido allows you to customize which blocks are available in the editor. You can exclude default Stripo blocks and selectively include custom blocks to create tailored editing experiences for different product types.
+
+### Block Types
+
+#### Default Blocks (GuidoBlockType)
 
-## Exposed Methods
+These are the standard Stripo email editor blocks that can be excluded:
 
 ```typescript
-const guidoRef = ref<InstanceType<typeof Guido> | null>(null);
+type GuidoBlockType =
+  | 'amp-accordion'      // AMP accordion component
+  | 'amp-carousel'       // AMP image carousel
+  | 'amp-form-controls'  // AMP form elements
+  | 'banner-block'       // Banner/hero section
+  | 'button-block'       // Call-to-action buttons
+  | 'html-block'         // Custom HTML
+  | 'image-block'        // Image elements
+  | 'menu-block'         // Navigation menu
+  | 'social-block'       // Social media links
+  | 'spacer-block'       // Vertical spacing
+  | 'text-block'         // Text content
+  | 'timer-block'        // Countdown timer
+  | 'video-block'        // Video embeds
+```
 
-// Insert dynamic content
-guidoRef.value?.dynamicContent.insert({
-  text: 'Display Name',
-  value: 'variable_name',
-  fallback: 'Default Value',
-});
+#### Custom Blocks (GuidoCustomBlockType)
 
-// Close dynamic content modal
-guidoRef.value?.dynamicContent.close();
+These are custom blocks that can be selectively included:
 
-// Silent save (no UI feedback)
-guidoRef.value?.saveSilent();
+```typescript
+type GuidoCustomBlockType =
+  | 'dynamic-content'      // Dynamic content merge tags
+  | 'checkbox-block'       // Checkbox form input
+  | 'radio-button-block'   // Radio button form input
+  | 'recommendation-block' // Product recommendations
+  | 'unsubscribe-block'    // Unsubscribe link
+  | 'coupon-block'         // Coupon/promo code
+  | 'items-block'          // Cart items display
 ```
 
----
+### Configuration Examples
 
-## Block Configuration
+#### Example 1: Exclude Specific Default Blocks
 
-### Default Blocks (can be excluded)
+Disable button, image, and video blocks while keeping all custom blocks:
 
 ```typescript
-type DefaultBlockType =
-  | 'amp-accordion'
-  | 'amp-carousel'
-  | 'amp-form-controls'
-  | 'banner-block'
-  | 'button-block'
-  | 'html-block'
-  | 'image-block'
-  | 'menu-block'
-  | 'social-block'
-  | 'spacer-block'
-  | 'text-block'
-  | 'timer-block'
-  | 'video-block';
-```
-
-### Custom Blocks (opt-in)
-
-```typescript
-type CustomBlockType =
-  | 'dynamic-content'
-  | 'checkbox-block'
-  | 'radio-button-block'
-  | 'recommendation-block'
-  | 'unsubscribe-block'
-  | 'coupon-block'
-  | 'items-block';
+const guidoConfig = {
+  translationsPath: 'window.trans.en',
+  features: {
+    dynamicContent: true,
+    saveAsTemplate: true,
+    versionHistory: true,
+    testMessage: true
+  },
+  blocks: {
+    excludeDefaults: ['button-block', 'image-block', 'video-block']
+  }
+};
 ```
 
-### Examples
+**Result:**
+- Button, Image, Video blocks disabled
+- All other default blocks enabled
+- All custom blocks are disabled.
+
+#### Example 2: Include Only Specific Custom Blocks
+
+Enable only coupon and recommendation blocks:
 
 ```typescript
-// Exclude specific default blocks
-const config: GuidoConfigInput = {
-  identity: { templateId: 'tpl-123', userId: 'user-456' },
-  partner: { name: 'partner' },
-  blocks: {
-    excludeDefaults: ['timer-block', 'video-block'],
+const guidoConfig = {
+  translationsPath: 'window.trans.en',
+  features: {
+    dynamicContent: true,
+    saveAsTemplate: true,
+    versionHistory: true,
+    testMessage: true
   },
-};
-
-// Include custom blocks
-const config: GuidoConfigInput = {
-  identity: { templateId: 'tpl-123', userId: 'user-456' },
-  partner: { name: 'partner' },
   blocks: {
-    includeCustoms: ['recommendation-block', 'coupon-block', 'dynamic-content'],
-  },
+    includeCustoms: ['coupon-block', 'recommendation-block']
+  }
 };
 ```
 
----
+**Result:**
+- All default blocks enabled
+- Only Coupon and Recommendation extensions enabled.
+- Other custom blocks are disabled
 
-## HTML Compiler Rules
+### Default Behavior
 
-Add custom rules to transform HTML during export:
+When `blocks` is not provided or is `undefined`:
 
 ```typescript
-const config: GuidoConfigInput = {
-  identity: { templateId: 'tpl-123', userId: 'user-456' },
-  partner: { name: 'partner' },
-  compiler: {
-    customRules: [
-      // Replace rule
-      {
-        id: 'replace-domain',
-        type: 'replace',
-        search: 'old-domain.com',
-        replacement: 'new-domain.com',
-        priority: 10,
-      },
-      // Regex rule
-      {
-        id: 'remove-comments',
-        type: 'regex',
-        pattern: '<!--.*?-->',
-        replacement: '',
-        flags: 'g',
-        priority: 20,
-      },
-      // Custom processor
-      {
-        id: 'add-tracking',
-        type: 'custom',
-        processor: (html) => html.replace('</body>', '<img src="track.gif"/></body>'),
-        priority: 30,
-      },
-    ],
-    ignoreDefaultRules: false, // Set true to skip built-in rules
+const guidoConfig = {
+  translationsPath: 'window.trans.en',
+  features: {
+    dynamicContent: true,
+    saveAsTemplate: true,
+    versionHistory: true,
+    testMessage: true
   },
+  // No blocks config
 };
 ```
 
----
+**Result:**
+- All 13 default Stripo blocks enabled
+- All custom blocks are disabled.
+
+### Block Configuration Interface
 
-## TypeScript Exports
+```typescript
+interface BlocksConfig {
+  excludeDefaults?: GuidoBlockType[];
+  includeCustoms?: GuidoCustomBlockType[];
+}
+```
+
+### TypeScript Types
+
+The library exports the following TypeScript types:
 
 ```typescript
-// Component
+// Main component
 import { Guido } from '@useinsider/guido';
 
 // Types
-import type {
-  GuidoConfig,
-  GuidoConfigInput,
-  IdentityConfig,
-  PartnerConfig,
-  TemplateConfig,
-  EditorConfig,
-  UIConfig,
-  FeaturesConfig,
-  BlocksConfig,
-  CompilerConfig,
-  DynamicContent,
-  DefaultBlockType,
-  CustomBlockType,
-} from '@useinsider/guido';
-
-// Utilities
-import {
-  validateConfig,
-  parseConfig,
-  MessageType,
-  ProductType,
-} from '@useinsider/guido';
-
-// Styles
-import '@useinsider/guido/style';
+import type { GuidoConfig } from '@useinsider/guido';
+import type { StripoEventType } from '@useinsider/guido';
 ```
 
----
+## 🔨 HTML Compiler Rules
+
+Guido includes a powerful HTML compiler system that allows you to transform HTML content with custom rules. You can define additional rules and optionally ignore the default rules.
 
-## Constants
+### Rule Types
+
+There are 4 types of compiler rules:
+
+#### 1. Replace Rule
+Replace specific strings in HTML content.
 
 ```typescript
-import { MessageType, ProductType } from '@useinsider/guido';
+{
+  id: 'fix-encoding',
+  description: 'Fix URL encoding issues',
+  type: 'replace',
+  search: '{%22',           // String to find
+  replacement: '%7B%22',    // String to replace with
+  replaceAll: true,         // Replace all occurrences (default: true)
+  priority: 10              // Execution priority (lower = earlier)
+}
+```
 
-MessageType.PROMOTIONAL    // 1
-MessageType.TRANSACTIONAL  // 2
+#### 2. Regex Rule
+Use regular expressions for complex pattern matching and replacement.
 
-ProductType.EMAIL          // 60
-ProductType.ARCHITECT      // 49
-ProductType.UNSUBSCRIBE_PAGES // 97
+```typescript
+{
+  id: 'remove-comments',
+  description: 'Remove HTML comments',
+  type: 'regex',
+  pattern: '<!--.*?-->',    // Regex pattern
+  replacement: '',          // Replacement string
+  flags: 'g',              // Regex flags (default: 'g')
+  priority: 20
+}
 ```
 
----
+#### 3. Remove Rule
+Remove specific strings or patterns from HTML content.
 
-## Dynamic Content Modal
+```typescript
+{
+  id: 'cleanup-scripts',
+  description: 'Remove unwanted script tags',
+  type: 'remove',
+  targets: [                              // Array of strings or RegExp objects
+    '<script src="unwanted.js"></script>',
+    /onclick="[^"]*"/g
+  ],
+  priority: 30
+}
+```
 
-When the `dynamic-content:open` event fires, show your custom modal and call the insert method:
+#### 4. Custom Rule
+Define complex transformation logic with a custom processor function.
 
-```vue
-<template>
-  <Guido ref="guidoRef" :config="config" @dynamic-content:open="showModal = true" />
+```typescript
+{
+  id: 'add-meta-tags',
+  description: 'Add custom meta tags to head',
+  type: 'custom',
+  processor: (html: string): string => {
+    // Custom transformation logic
+    const metaTags = '<meta name="custom" content="value">';
+    return html.replace('</head>', `${metaTags}</head>`);
+  },
+  priority: 40
+}
+```
 
-  <!-- Your modal must have id="guido-dynamic-content-modal" -->
-  <YourModal v-if="showModal" id="guido-dynamic-content-modal" @select="insertContent" @close="closeModal" />
-</template>
+### Using HTML Compiler Rules
 
-<script setup>
-const showModal = ref(false);
+#### Basic Usage with Custom Rules
 
-const insertContent = (content) => {
-  guidoRef.value?.dynamicContent.insert({
-    text: content.label,
-    value: content.value,
-    fallback: content.fallback || '',
-  });
-  showModal.value = false;
+```typescript
+const guidoConfig = {
+  translationsPath: 'window.trans.en',
+  features: {
+    dynamicContent: true,
+    saveAsTemplate: true,
+    versionHistory: false,  // Disable version history
+    testMessage: true
+  },
+  htmlCompilerRules: [
+    {
+      id: 'replace-domain',
+      description: 'Replace old domain with new one',
+      type: 'replace',
+      search: 'old-domain.com',
+      replacement: 'new-domain.com',
+      replaceAll: true,
+      priority: 10
+    },
+    {
+      id: 'remove-tracking',
+      description: 'Remove tracking pixels',
+      type: 'regex',
+      pattern: '<img[^>]*tracking[^>]*>',
+      replacement: '',
+      flags: 'gi',
+      priority: 20
+    }
+  ]
 };
+```
+
+#### Ignoring Default Rules
 
-const closeModal = () => {
-  guidoRef.value?.dynamicContent.close();
-  showModal.value = false;
+```typescript
+const guidoConfig = {
+  translationsPath: 'window.trans.en',
+  features: {
+    dynamicContent: true,
+    saveAsTemplate: true,
+    versionHistory: true,
+    testMessage: true
+  },
+  ignoreDefaultHtmlCompilerRules: true, // Skip all default rules
+  htmlCompilerRules: [
+    // Only your custom rules will be applied
+    {
+      id: 'custom-transformation',
+      type: 'replace',
+      search: 'old-text',
+      replacement: 'new-text',
+      priority: 1
+    }
+  ]
 };
-</script>
+```
+
+### Rule Execution Order
+
+Rules are executed in priority order (lower numbers first). Rules with the same priority are executed in array order.
+
+- **Priority 1-99**: Reserved for critical transformations
+- **Priority 100-999**: Standard transformations  
+- **Priority 1000+**: Additional custom rules (automatically assigned)
+
+### Default Rules
+
+Guido includes several default rules for common email HTML optimizations:
+
+- **URL encoding fixes**: Fixes malformed URL encoding in dynamic content
+- **Template tag restoration**: Restores `{{}}` template tags that got URL encoded
+- **HTML entity decoding**: Converts `&lt;` and `&gt;` back to `<` and `>`
+- **Cleanup rules**: Removes unwanted iframe and style elements
+- **MSO conditions**: Manages Outlook-specific conditional comments
+- **Domain replacement**: Updates old image domains to current ones
+
+You can view all default rules in: `src/config/compiler/htmlCompilerRules.ts`
+
+### CompilerRule Interface
+
+```typescript
+type CompilerRuleType = 'replace' | 'regex' | 'remove' | 'custom';
+
+interface BaseCompilerRule {
+  id: string;
+  description?: string;
+  priority: number;
+}
+
+interface ReplaceRule extends BaseCompilerRule {
+  type: 'replace';
+  search: string;
+  replacement: string;
+  replaceAll?: boolean; // Default: true
+}
+
+interface RegexRule extends BaseCompilerRule {
+  type: 'regex';
+  pattern: string;
+  replacement: string;
+  flags?: string; // Default: 'g'
+}
+
+interface RemoveRule extends BaseCompilerRule {
+  type: 'remove';
+  targets: (string | RegExp)[]; // Array of strings or RegExp objects
+}
+
+interface CustomRule extends BaseCompilerRule {
+  type: 'custom';
+  processor: (html: string) => string;
+}
+
+type CompilerRule = ReplaceRule | RegexRule | RemoveRule | CustomRule;
 ```
 
 ---
 
-## Development
+## 🔧 Development
+
+### Prerequisites
+
+- 🧄 `Bun` (strongly recommended)
+or
+- NodeJS 18+ & `npm`
+
+### Setup
 
 ```bash
-# Install
+# Install dependencies
 bun install
 
-# Start dev server
+# Start development server
 bun start
 
-# Build
+# Build for production
 bun run build
 
-# Lint & type-check
+# Type checking
+bun run type-check
+
+# Linting
 bun run lint
 ```
 
 ### Environment Variables
 
+Create a `.env` file with the following variables: (You can get env variables from your senior)
+
 ```env
 VITE_STRIPO_PLUGIN_ID=your_plugin_id
 VITE_STRIPO_SECRET_KEY=your_secret_key
 VITE_STRIPO_ROLE=your_role
+
+# Playwright Test Configuration (Optional - for local debugging only)
+HEADED=false  # Set to 'true' to run tests with visible browser
 ```
 
----
+### Project Structure
+
+```
+src/
+├── components/         # Vue components
+├── composables/        # Vue composables & business logic
+├── services/           # API layer
+├── stores/             # State management
+├── @types/             # TypeScript definitions
+├── static/             # Static assets & templates
+├── utils/              # Utility functions
+├── enums/              # Constants & enums
+├── mock/               # Mock data for development
+├── plugins/            # Vue plugins
+└── library.ts          # Main export
+```
 
-## Local Testing
+## 🔌 Provide/Inject Utilities
 
-```bash
-# Build the package
+Guido includes type-safe utilities for Vue's provide/inject system to facilitate dependency injection between components.
+
+### useProvideInject
+
+The `useProvideInject` composable provides two helper functions for type-safe dependency injection:
+
+#### Basic Usage
+
+```typescript
+// Parent component
+import { provideValue } from '@useinsider/guido';
+import { InjectionKey } from 'vue';
+
+// Define a typed injection key
+const MyServiceKey: InjectionKey<MyService> = Symbol('MyService');
+
+// Provide the value
+const myService = new MyService();
+provideValue(MyServiceKey, myService);
+
+// Child component
+import { useInjectedValue } from '@useinsider/guido';
+
+// Inject the value with type safety
+const myService = useInjectedValue(MyServiceKey);
+```
+
+#### With Default Value
+
+```typescript
+// Inject with a fallback value
+const myService = useInjectedValue(MyServiceKey, new DefaultService());
+```
+
+#### Error Handling
+
+The `useInjectedValue` function will throw a descriptive error if no provider is found and no default value is provided:
+
+```typescript
+// This will throw an error if no provider exists
+try {
+  const myService = useInjectedValue(MyServiceKey);
+} catch (error) {
+  console.error('No provider found for MyService');
+}
+```
+
+### API Reference
+
+#### `provideValue`
+
+```typescript
+provideValue<T>(key: InjectionKey<T>, value: T): void
+```
+
+Provides a value using Vue's provide system with type safety.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `key` | `InjectionKey<T>` | The typed injection key |
+| `value` | `T` | The value to provide |
+
+#### `useInjectedValue`
+
+```typescript
+useInjectedValue<T>(key: InjectionKey<T>, defaultValue?: T): T
+```
+
+Injects a value using Vue's inject system with type safety and error handling.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `key` | `InjectionKey<T>` | ✅ | The typed injection key |
+| `defaultValue` | `T` | ⚪ | Optional fallback value |
+
+**Returns:** `T` - The injected value
+
+**Throws:** `Error` - When no provider is found and no default value is provided
+
+## 🌐 i18n
+Before running the project, it sends to request to inone.useinsider.com/translations and writes the JSON file into - [trans.json](src/mock/responses/trans.json). 
+It allows to use production or local translations on your code. 🚀
+Example usage: 
+```js
+import { useTranslations } from '@@/Composables/useTranslations';
+
+const trans = useTranslations();
+
+// use everywhere like this:
+trans('foo.bar')
+```
+
+## 📦 Local Building (Recommended)
+
+Run this commands if you want to test the package on your local before sending to NPM.
+```sh
 bun run build
+```
 
-# Create tarball
+Since bun does not have packaging yet, use npm here: 🥲
+```sh
 npm pack
+```
+
+It'll crate like `useinsider-guido-1.0.0.tgz` file.
 
-# Install in your project
-cd ../your-project
-npm install ../guido/useinsider-guido-1.0.0.tgz
+Move this file to your project path like: `email-fe` via:
+```sh
+cp useinsider-guido-1.0.0.tgz ../email-fe
 ```
 
----
+Install the file to your project: 
+```sh
+npm i ./useinsider-guido-1.0.0.tgz
+```
+
+Then you just need to rebuild to your project or restart the Container. 🎉
+
+For Future, we can create a shell script for it. Feel free to help 🙃
+
+## 📦 Build Output
+
+The library builds to multiple formats:
 
-## License
+- **ES Module**: `dist/library.js` (recommended)
+- **CSS**: `dist/guido.css` (custom styles)
+
+### Package Exports
+
+```json
+{
+  "exports": {
+    ".": {
+      "import": "./dist/library.js",
+      "types": "./dist/components/Guido.vue.d.ts",
+      "require": "./dist/components/Guido.vue.js"
+    },
+    "./style": "./dist/guido.css"
+  }
+}
+```
+
+## 🤝 Contributing
+- PR Titles should be structured like `TASK-ID | 🔥 | Some Clear Task Descriptions`
+- PR Labels should be filled.
+- PR Assignee required.
+- Tests should be covered.
+- All required checks should be passed before sending review request.
+
+## 📄 License
 
 ISC License
+
+---
+
+## 🔗 Related
+
+- [Stripo Email Editor](https://stripo.email/) - The underlying email editor
+- [@useinsider/design-system-vue](https://github.com/useinsider/design-system-vue) - Insider's Vue design system
+
+## 🎯 TODO:
+- CSS part should be optimized with variables & `sass-loader`.
+- Master Version Generator should be fixed.
+- Playwright integrationBoilerplate/control.ts
+- Commitlint & Precommit Hooks integration
+- Get Pre-built display conditions from API