@useinsider/guido 1.0.0-beta.dad21f4 → 1.0.0-beta.de03990

package/README.md

@@ -27,10 +27,15 @@ npm install @useinsider/guido
   <div>
     <Guido
       ref="guidoEditor"
-      :email-id="emailId"
+      :template-id="templateId"
       :user-id="userId"
       :guido-config="guidoConfig"
+      :html="initialHtml"
+      :css="initialCss"
       @dynamic-content:open="handleDynamicContentOpen"
+      @back="handleBack"
+      @save:start="handleSaveStart"
+      @save:complete="handleSaveComplete"
     />
   </div>
 </template>
@@ -44,28 +49,59 @@ export default {
   },
   data() {
     return {
-      emailId: 'abc123',
-      userId: '12345',
+      templateId: 'template-123',
+      userId: 'user-456',
+      initialHtml: '<p>Initial HTML content</p>',
+      initialCss: 'p { color: #333; }',
       guidoConfig: {
-        translationsPath: 'window.trans.en'
-      }
+        translationsPath: 'window.trans.en',
+        htmlCompilerRules: [],
+        ignoreDefaultHtmlCompilerRules: false,
+        features: {
+          dynamicContent: true,
+          saveAsTemplate: true,
+          versionHistory: true
+        }
+      },
       dynamicContentModalVisible: false
     };
   },
 
   methods: {
-    handleDynamicContentOpen() {
+    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
-    handleDynamicContentApply() {
-      this.$ref.guidoEditor.applyDynamicContent({
-        text: 'Text', 
-        value: 'Value', 
-        fallback: 'Fallback'
+    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();
     }
   }
 };
@@ -78,16 +114,28 @@ export default {
 
 | Prop | Type | Required | Default | Description |
 |------|------|----------|---------|-------------|
-| `emailId` | `string` | ✅ | - | Unique identifier for the email draft |
-| `userId` | `string` | ✅ | - | Unique identifier for the user draft |
-| `username` | `string` | ⚪ | Guido User | User name |
-| `partnerName` | `string` | ⚪ | Getting from URL host | Unique identifier for the partner draft |
-| `productType` | `string` | ⚪ | Getting from URL path | Unique identifier for the product draft |
+| `templateId` | `string` | ✅ | - | Unique identifier for the email template |
+| `userId` | `string` | ✅ | - | Unique identifier for the user |
 | `guidoConfig` | `GuidoConfig` | ✅ | - | Configuration object for the editor |
+| `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 |
+
+### Guido Component Events
+
+| 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 |
 
 ### Guido Exposed Methods
 ```typescript
-applyDynamicContent(DynamicContent);
+dynamicContent.insert(DynamicContent);
+dynamicContent.close();
 ```
 
 ### Guido Interfaces
@@ -95,12 +143,25 @@ applyDynamicContent(DynamicContent);
 ```typescript
 interface GuidoConfig {
   translationsPath: string;
+  htmlCompilerRules?: CompilerRule[];
+  ignoreDefaultHtmlCompilerRules?: boolean;
+  features: {
+    dynamicContent: boolean;
+    saveAsTemplate: boolean;
+    versionHistory: boolean;
+  };
 }
 ```
 
 | 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` |
+| `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 |
 
 ```typescript
 interface DynamicContent {
@@ -109,6 +170,7 @@ interface DynamicContent {
   fallback?: string;
 }
 ```
+---
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
@@ -129,6 +191,195 @@ 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.
+
+### Rule Types
+
+There are 4 types of compiler rules:
+
+#### 1. Replace Rule
+Replace specific strings in HTML content.
+
+```typescript
+{
+  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)
+}
+```
+
+#### 2. Regex Rule
+Use regular expressions for complex pattern matching and replacement.
+
+```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.
+
+```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
+}
+```
+
+#### 4. Custom Rule
+Define complex transformation logic with a custom processor function.
+
+```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
+}
+```
+
+### Using HTML Compiler Rules
+
+#### Basic Usage with Custom Rules
+
+```typescript
+const guidoConfig = {
+  translationsPath: 'window.trans.en',
+  features: {
+    dynamicContent: true,
+    saveAsTemplate: true,
+    versionHistory: false  // Disable version history
+  },
+  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
+
+```typescript
+const guidoConfig = {
+  translationsPath: 'window.trans.en',
+  features: {
+    dynamicContent: true,
+    saveAsTemplate: true,
+    versionHistory: 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
+    }
+  ]
+};
+```
+
+### 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
@@ -185,6 +436,87 @@ src/
 └── library.ts          # Main export
 ```
 
+## 🔌 Provide/Inject Utilities
+
+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. 🚀
@@ -210,16 +542,16 @@ Since bun does not have packaging yet, use npm here: 🥲
 npm pack
 ```
 
-It'll crate like `useinsider-guido-1.0.0.gz` file.
+It'll crate like `useinsider-guido-1.0.0.tgz` file.
 
 Move this file to your project path like: `email-fe` via:
 ```sh
-cp useinsider-guido-1.0.0.gz ../email-fe
+cp useinsider-guido-1.0.0.tgz ../email-fe
 ```
 
 Install the file to your project: 
 ```sh
-npm i ./useinsider-guido-1.0.0.gz
+npm i ./useinsider-guido-1.0.0.tgz
 ```
 
 Then you just need to rebuild to your project or restart the Container. 🎉
@@ -271,8 +603,4 @@ ISC License
 - Master Version Generator should be fixed.
 - Playwright integration
 - Commitlint & Precommit Hooks integration
-- We need to emit save event and we should return template config to it
-- Default template should be same with production
-- Open Guido with saved template
-- Get User ID, Email and Unique Template ID as dynamic from props
 - Get Pre-built display conditions from API

package/dist/@types/generic.d.ts

@@ -1,8 +1,38 @@
+import type { CompilerRule } from './html-compiler';
+type Features = {
+    dynamicContent?: boolean;
+    saveAsTemplate?: boolean;
+    versionHistory?: boolean;
+};
 export type GuidoConfig = {
     translationsPath: string;
+    htmlCompilerRules?: CompilerRule[];
+    ignoreDefaultHtmlCompilerRules?: boolean;
+    emailHeader: EmailHeader;
+    features?: Features;
 };
 export type DynamicContent = {
     value: string;
     text: string;
     fallback?: string;
 };
+export interface EmailHeader {
+    senderName: string;
+    subject: string;
+}
+export interface TooltipOptions {
+    id: string;
+    dynamicPosition: boolean;
+    staticPosition: 'top center' | 'top left' | 'top right' | 'bottom center' | 'bottom left' | 'bottom right' | 'right center' | 'right top' | 'right bottom' | 'left center' | 'left top' | 'left bottom';
+    iconStatus: boolean;
+    offset?: {
+        x: number;
+        y: number;
+    };
+    preventXss?: boolean;
+}
+export type MergeTag = {
+    label: string;
+    value: string;
+};
+export {};

package/dist/components/Guido.vue.d.ts

@@ -1,16 +1,29 @@
 import type { DynamicContent, GuidoConfig } from '@@/Types/generic';
+import type { Template } from '@@/Types/stripo';
 type __VLS_Props = {
-    emailId: string;
+    templateId: string;
     userId: string;
     partnerName?: string;
     productType?: string;
     username?: string;
+    html?: string;
+    css?: string;
+    preselectedDynamicContentList: DynamicContent[];
     guidoConfig: GuidoConfig;
 };
 declare const _default: import("vue").DefineComponent<__VLS_TypePropsToOption<__VLS_Props>, {
-    applyDynamicContent: (data: DynamicContent) => void;
+    dynamicContent: {
+        insert: (data: DynamicContent) => void;
+        close: () => void;
+    };
 }, {}, {}, {}, import("vue/types/v3-component-options.js").ComponentOptionsMixin, import("vue/types/v3-component-options.js").ComponentOptionsMixin, {
     "dynamic-content:open": (detail: DynamicContent | null) => void;
+    back: () => void;
+    "save:start": () => void;
+    "save:complete": (data: {
+        template: Omit<Template, "forceRecreate">;
+        dynamicContentList: DynamicContent[];
+    }) => void;
 }, string, Readonly<import("vue").ExtractPropTypes<__VLS_TypePropsToOption<__VLS_Props>>>, {}>;
 export default _default;
 type __VLS_NonUndefinedable<T> = T extends undefined ? never : T;

package/dist/components/Guido.vue.js

@@ -1,18 +1,18 @@
 import o from "./Guido.vue2.js";
 /* empty css           */
-import i from "../_virtual/_plugin-vue2_normalizer.js";
+import t from "../_virtual/_plugin-vue2_normalizer.js";
 var s = function() {
-  var e = this, r = e._self._c, t = e._self._setupProxy;
-  return r("div", { staticClass: "guido-editor__wrapper" }, [r(t.HeaderWrapper), r("div", { staticClass: "guido-editor__container", attrs: { id: "guido-editor" } })], 1);
-}, _ = [], a = /* @__PURE__ */ i(
+  var i = this, e = i._self._c, r = i._self._setupProxy;
+  return e("div", { staticClass: "guido-editor__wrapper" }, [e(r.HeaderWrapper), r.previewStore.isPreviewModeOpen ? e(r.PreviewContainer) : i._e(), e("div", { directives: [{ name: "show", rawName: "v-show", value: !r.previewStore.isPreviewModeOpen, expression: "!previewStore.isPreviewModeOpen" }], staticClass: "guido-editor__container", attrs: { id: "guido-editor" } }), e(r.Toaster)], 1);
+}, a = [], n = /* @__PURE__ */ t(
   o,
   s,
-  _,
+  a,
   !1,
   null,
-  "1d1d2b7c"
+  "09c28ccc"
 );
-const f = a.exports;
+const v = n.exports;
 export {
-  f as default
+  v as default
 };