@useinsider/guido 1.0.0-beta.7f477db → 1.0.0-beta.80693fc

package/README.md

@@ -14,7 +14,10 @@ Guido is a Vue 2 + TypeScript wrapper for the Stripo Email Editor plugin. Easily
 ```bash
 npm install @useinsider/guido
 ```
+### Prerequisites
+  🍍 Your project should have `pinia`
 
+---
 ## 🚀 Usage
 
 ### Basic Usage
@@ -23,9 +26,11 @@ npm install @useinsider/guido
 <template>
   <div>
     <Guido
+      ref="guidoEditor"
       :email-id="emailId"
       :user-id="userId"
       :guido-config="guidoConfig"
+      @dynamic-content:open="handleDynamicContentOpen"
     />
   </div>
 </template>
@@ -42,9 +47,33 @@ export default {
       emailId: 'abc123',
       userId: '12345',
       guidoConfig: {
-        translationsPath: 'window.trans.en'
+        translationsPath: 'window.trans.en',
+        htmlCompilerRules: [],
+        ignoreDefaultHtmlCompilerRules: false,
       }
+      dynamicContentModalVisible: false
     };
+  },
+
+  methods: {
+    handleDynamicContentOpen() {
+      this.dynamicContentModalVisible = true;
+    }
+    // ⚠️ Your own Dynamic Content Modal should have this id: #guido-dynamic-content-modal
+    handleDynamicContentInsert() {
+      this.$ref.guidoEditor?.dynamicContent.insert({
+        text: 'Text', 
+        value: 'Value', 
+        fallback: 'Fallback'
+      });
+
+      this.dynamicContentModalVisible = false;
+    },
+    // ⚠️ It's mandatory. There is no way to understand if user closes the modal without selection.
+    handleDynamicContentClose() {
+      this.$ref.guidoEditor?.dynamicContent.close();
+    }
+
   }
 };
 </script>
@@ -63,17 +92,42 @@ export default {
 | `productType` | `string` | ⚪ | Getting from URL path | Unique identifier for the product draft |
 | `guidoConfig` | `GuidoConfig` | ✅ | - | Configuration object for the editor |
 
-### GuidoConfig Interface
+### Guido Exposed Methods
+```typescript
+dynamicContent.insert(DynamicContent);
+dynamicContent.close();
+```
+
+### Guido Interfaces
 
 ```typescript
 interface GuidoConfig {
   translationsPath: string;
+  htmlCompilerRules: CompilerRule[];
+  ignoreDefaultHtmlCompilerRules: 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` |
+
+```typescript
+interface DynamicContent {
+  value: string;
+  text: string;
+  fallback?: string;
+}
+```
+---
+
+| 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 |
 
 ### TypeScript Types
 
@@ -88,17 +142,183 @@ import type { GuidoConfig } from '@useinsider/guido';
 import type { StripoEventType } from '@useinsider/guido';
 ```
 
-### StripoEventType
+## 🔨 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
-type StripoEventType = 
-  | 'save'
-  | 'export'
-  | 'close'
-  | 'autosave'
-  | 'publish'
-  | 'export:requested'
-  | 'export:ready';
+{
+  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',
+  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',
+  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;
 ```
 
 ---
@@ -170,6 +390,34 @@ const trans = useTranslations();
 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
+```
+
+Since bun does not have packaging yet, use npm here: 🥲
+```sh
+npm pack
+```
+
+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.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:

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

@@ -1,3 +1,17 @@
+import type { CompilerRule } from './html-compiler';
 export type GuidoConfig = {
     translationsPath: string;
+    htmlCompilerRules?: CompilerRule[];
+    ignoreDefaultHtmlCompilerRules?: boolean;
 };
+export type DynamicContent = {
+    value: string;
+    text: string;
+    fallback?: string;
+};
+export interface TooltipOptions {
+    id: string;
+    dynamicPosition: boolean;
+    staticPosition: string;
+    iconStatus: boolean;
+}

package/dist/App.vue.d.ts

@@ -1,3 +1,3 @@
 import '../node_modules/@useinsider/design-system-vue/dist/design-system-vue.css';
-declare const _default: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue/types/v3-component-options").ComponentOptionsMixin, import("vue/types/v3-component-options").ComponentOptionsMixin, {}, string, Readonly<import("vue").ExtractPropTypes<{}>>, {}>;
+declare const _default: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue/types/v3-component-options.js").ComponentOptionsMixin, import("vue/types/v3-component-options.js").ComponentOptionsMixin, {}, string, Readonly<import("vue").ExtractPropTypes<{}>>, {}>;
 export default _default;

package/dist/_virtual/AddCustomFont.js

@@ -0,0 +1,4 @@
+var o = {};
+export {
+  o as __exports
+};

package/dist/_virtual/AiAssistantValueType.js

@@ -0,0 +1,4 @@
+var s = {};
+export {
+  s as __exports
+};

package/dist/_virtual/BackgroundColorBuiltInControl.js

@@ -0,0 +1,4 @@
+var o = {};
+export {
+  o as __exports
+};

package/dist/_virtual/BackgroundImageBuiltInControl.js

@@ -0,0 +1,4 @@
+var o = {};
+export {
+  o as __exports
+};

package/dist/_virtual/Block.js

@@ -0,0 +1,4 @@
+var o = {};
+export {
+  o as __exports
+};

package/dist/_virtual/BlockAttributes.js

@@ -0,0 +1,4 @@
+var t = {};
+export {
+  t as __exports
+};

package/dist/_virtual/BlockCompositionType.js

@@ -0,0 +1,4 @@
+var o = {};
+export {
+  o as __exports
+};

package/dist/_virtual/BlockPaddingsBuiltInControl.js

@@ -0,0 +1,4 @@
+var o = {};
+export {
+  o as __exports
+};

package/dist/_virtual/BlockRenderer.js

@@ -0,0 +1,4 @@
+var e = {};
+export {
+  e as __exports
+};

package/dist/_virtual/BlockType.js

@@ -0,0 +1,4 @@
+var e = {};
+export {
+  e as __exports
+};

package/dist/_virtual/BlocksPanel.js

@@ -0,0 +1,4 @@
+var a = {};
+export {
+  a as __exports
+};

package/dist/_virtual/BuiltInControl.js

@@ -0,0 +1,4 @@
+var o = {};
+export {
+  o as __exports
+};

package/dist/_virtual/BuiltInControlTypes.js

@@ -0,0 +1,4 @@
+var o = {};
+export {
+  o as __exports
+};

package/dist/_virtual/ButtonBorderBuiltInControl.js

@@ -0,0 +1,4 @@
+var o = {};
+export {
+  o as __exports
+};

package/dist/_virtual/ButtonColorBuiltInControl.js

@@ -0,0 +1,4 @@
+var o = {};
+export {
+  o as __exports
+};

package/dist/_virtual/ButtonFontColorBuiltInControl.js

@@ -0,0 +1,4 @@
+var o = {};
+export {
+  o as __exports
+};

package/dist/_virtual/ButtonInternalIndentsBuiltInControl.js

@@ -0,0 +1,4 @@
+var t = {};
+export {
+  t as __exports
+};

package/dist/_virtual/ButtonTextBuiltInControl.js

@@ -0,0 +1,4 @@
+var t = {};
+export {
+  t as __exports
+};

package/dist/_virtual/ContextAction.js

@@ -0,0 +1,4 @@
+var t = {};
+export {
+  t as __exports
+};

package/dist/_virtual/ContextActionType.js

@@ -0,0 +1,4 @@
+var t = {};
+export {
+  t as __exports
+};

package/dist/_virtual/Control.js

@@ -0,0 +1,4 @@
+var o = {};
+export {
+  o as __exports
+};

package/dist/_virtual/EditorStatePropertyType.js

@@ -0,0 +1,4 @@
+var r = {};
+export {
+  r as __exports
+};

package/dist/_virtual/Extension.js

@@ -0,0 +1,4 @@
+var e = {};
+export {
+  e as __exports
+};

package/dist/_virtual/ExtensionBuilder.js

@@ -0,0 +1,4 @@
+var e = {};
+export {
+  e as __exports
+};

package/dist/_virtual/FontFamilyBuiltInControl.js

@@ -0,0 +1,4 @@
+var o = {};
+export {
+  o as __exports
+};

package/dist/_virtual/LinkColorBuiltInControl.js

@@ -0,0 +1,4 @@
+var o = {};
+export {
+  o as __exports
+};

package/dist/_virtual/ModificationDescription.js

@@ -0,0 +1,4 @@
+var i = {};
+export {
+  i as __exports
+};

package/dist/_virtual/PanelPosition.js

@@ -0,0 +1,4 @@
+var o = {};
+export {
+  o as __exports
+};

package/dist/_virtual/PreviewDeviceMode.js

@@ -0,0 +1,4 @@
+var e = {};
+export {
+  e as __exports
+};

package/dist/_virtual/SettingsPanelRegistry.js

@@ -0,0 +1,4 @@
+var e = {};
+export {
+  e as __exports
+};

package/dist/_virtual/SettingsPanelTab.js

@@ -0,0 +1,4 @@
+var a = {};
+export {
+  a as __exports
+};

package/dist/_virtual/SettingsTab.js

@@ -0,0 +1,4 @@
+var t = {};
+export {
+  t as __exports
+};

package/dist/_virtual/StructureBorderBuiltInControl.js

@@ -0,0 +1,4 @@
+var r = {};
+export {
+  r as __exports
+};

package/dist/_virtual/StructurePaddingsBuiltInControl.js

@@ -0,0 +1,4 @@
+var r = {};
+export {
+  r as __exports
+};

package/dist/_virtual/TextColorBuiltInControl.js

@@ -0,0 +1,4 @@
+var o = {};
+export {
+  o as __exports
+};

package/dist/_virtual/TextLineSpacingBuiltInControl.js

@@ -0,0 +1,4 @@
+var t = {};
+export {
+  t as __exports
+};

package/dist/_virtual/TextSizeBuiltInControl.js

@@ -0,0 +1,4 @@
+var t = {};
+export {
+  t as __exports
+};

package/dist/_virtual/TextStyleBuiltInControl.js

@@ -0,0 +1,4 @@
+var t = {};
+export {
+  t as __exports
+};

package/dist/_virtual/UIElement.js

@@ -0,0 +1,4 @@
+var e = {};
+export {
+  e as __exports
+};

package/dist/_virtual/UIElementTagRegistry.js

@@ -0,0 +1,4 @@
+var e = {};
+export {
+  e as __exports
+};

package/dist/_virtual/UIElementType.js

@@ -0,0 +1,4 @@
+var e = {};
+export {
+  e as __exports
+};

package/dist/_virtual/UIElementsAttributes.js

@@ -0,0 +1,4 @@
+var t = {};
+export {
+  t as __exports
+};

package/dist/_virtual/index.js

@@ -0,0 +1,5 @@
+import { __require as r } from "../node_modules/@stripoinc/ui-editor-extensions/dist/index.js";
+var i = r();
+export {
+  i as d
+};

package/dist/_virtual/index2.js

@@ -0,0 +1,4 @@
+var r = {};
+export {
+  r as __exports
+};

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

@@ -1,4 +1,4 @@
-import type { GuidoConfig } from '@@/Types/generic';
+import type { DynamicContent, GuidoConfig } from '@@/Types/generic';
 type __VLS_Props = {
     emailId: string;
     userId: string;
@@ -7,7 +7,14 @@ type __VLS_Props = {
     username?: string;
     guidoConfig: GuidoConfig;
 };
-declare const _default: import("vue").DefineComponent<__VLS_TypePropsToOption<__VLS_Props>, {}, {}, {}, {}, import("vue/types/v3-component-options").ComponentOptionsMixin, import("vue/types/v3-component-options").ComponentOptionsMixin, {}, string, Readonly<import("vue").ExtractPropTypes<__VLS_TypePropsToOption<__VLS_Props>>>, {}>;
+declare const _default: import("vue").DefineComponent<__VLS_TypePropsToOption<__VLS_Props>, {
+    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;
+}, string, Readonly<import("vue").ExtractPropTypes<__VLS_TypePropsToOption<__VLS_Props>>>, {}>;
 export default _default;
 type __VLS_NonUndefinedable<T> = T extends undefined ? never : T;
 type __VLS_TypePropsToOption<T> = {

package/dist/components/Guido.vue.js

@@ -1,18 +1,18 @@
 import o from "./Guido.vue2.js";
 /* empty css           */
-import a from "../_virtual/_plugin-vue2_normalizer.js";
+import i from "../_virtual/_plugin-vue2_normalizer.js";
 var s = function() {
-  var t = this, e = t._self._c, r = t._self._setupProxy;
-  return e("div", { staticClass: "guido-editor__wrapper" }, [e(r.HeaderWrapper), e("div", { staticClass: "guido-editor__container", attrs: { id: "guido-editor" } }), e(r.SaveTemplateModal, { attrs: { "is-open": r.editorStore.isSaveTemplateModalOpen }, on: { close: r.handleCloseSaveTemplateModal } })], 1);
-}, i = [], n = /* @__PURE__ */ a(
+  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(
   o,
   s,
-  i,
+  _,
   !1,
   null,
-  "69c35c60"
+  "89423288"
 );
-const c = n.exports;
+const f = a.exports;
 export {
-  c as default
+  f as default
 };