@useinsider/guido 1.0.0-beta.e239762 → 1.0.0-beta.e415f9e

package/README.md

@@ -1,25 +1,38 @@
-# @useinsider/guido-plugin
+<p align="center">
+  <a href="https://www.youtube.com/shorts/Y0RwBeMezL4" target="_blank" rel="noopener noreferrer">
+    <img width="180" src="./public/guido.png" alt="Guido logo">
+  </a>
+</p>
 
-Guido is a Vue + TypeScript wrapper for Email Plugin. Easily embed the email editor in your Vue applications.
+
+# @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, customizable interface.
 
 ## 📦 Install
+
 ```bash
 npm install @useinsider/guido
 ```
+### Prerequisites
+  🍍 Your project should have `pinia`
+
+---
+## 🚀 Usage
+
+### Basic Usage
 
-## 🚀 Usage (Vue 2)
-```vue
+```html
 <template>
-  <Guido
-    email-id="abc123"
-    :api="apiEndpoints"
-    :extensions="extensions"
-    :insider-stripo-config="insiderStripoConfig"
-    @save="handleSave"
-    @export:requested="onExportRequested"
-    @export:ready="handleHtml"
-    @close="onClose"
-  />
+  <div>
+    <Guido
+      ref="guidoEditor"
+      :email-id="emailId"
+      :user-id="userId"
+      :guido-config="guidoConfig"
+      @dynamic-content:open="handleDynamicContentOpen"
+    />
+  </div>
 </template>
 
 <script lang="ts">
@@ -31,99 +44,427 @@ export default {
   },
   data() {
     return {
-      apiEndpoints: {
-        dynamicContent: '/api/dynamic-content',
-        unsubPages: '/api/unsub-pages',
-        header: '/api/header',
-        footer: '/api/footer',
-        productName: '/api/product-name',
-        productVersion: '/api/product-version',
-        token: '/api/stripo-token'
-      },
-      extensions: {
-        dynamicContent: true,
-        unsubPages: true,
-        header: false,
-        footer: false
+      emailId: 'abc123',
+      userId: '12345',
+      guidoConfig: {
+        translationsPath: 'window.trans.en',
+        htmlCompilerRules: [],
+        ignoreDefaultHtmlCompilerRules: false,
       }
+      dynamicContentModalVisible: false
     };
   },
+
   methods: {
-    handleSave(data: any) {
-      console.log('Saved:', data);
-    },
-    handleHtml({ html }: { html: string }) {
-      console.log('HTML ready:', html);
-    },
-    onExportRequested() {
-      console.log('Export started');
+    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;
     },
-    onClose() {
-      console.log('Closed');
+    // ⚠️ It's mandatory. There is no way to understand if user closes the modal without selection.
+    handleDynamicContentClose() {
+      this.$ref.guidoEditor?.dynamicContent.close();
     }
+
   }
 };
 </script>
 ```
 
 ## 📚 API
-### `<StripoEditor />` Props
-| Prop        | Type     | Required | Description                |
-|-------------|----------|----------|----------------------------|
-| emailId     | string   | ✅       | Stripo email draft ID     |
-| iframeId    | string   | ❌       | Custom iframe ID          |
-| api         | object   | ❌       | Custom API endpoints      |
-| extensions  | object   | ❌       | Enable/disable extensions |
-| insiderStripoConfig | object | ❌ | Insider Stripo configuration |
-
-### Extensions
-| Extension       | Type      | Default | Description                    |
-|----------------|-----------|---------|--------------------------------|
-| dynamicContent | boolean   | true    | Dynamic content functionality  |
-| unsubPages     | boolean   | true    | Unsubscribe pages feature      |
-| header         | boolean   | true    | Header customization           |
-| footer         | boolean   | true    | Footer customization           |
-
-### Insider Stripo Configuration
-| Property          | Type     | Default | Description                    |
-|-------------------|----------|---------|--------------------------------|
-| translationsPath  |  string  | 'window.trans.en | JS Path to translations file |
-
-### API Endpoints
-| Endpoint           | Default Path           | Description                    |
-|-------------------|------------------------|--------------------------------|
-| dynamicContent    | /api/dynamic-content   | Dynamic content endpoint       |
-| unsubPages        | /api/unsub-pages       | Unsubscribe pages endpoint     |
-| header            | /api/header            | Header endpoint                |
-| footer            | /api/footer            | Footer endpoint                |
-| productName       | /api/product-name      | Product name endpoint          |
-| productVersion    | /api/product-version   | Product version endpoint       |
-| token             | /api/stripo-token      | Authentication token endpoint  |
-
-### Events
-| Event             | Payload                | Description                    |
-|-------------------|------------------------|--------------------------------|
-| `save`            | any                    | Triggered on save              |
-| `export:requested`| void                   | Triggered when export starts   |
-| `export:ready`    | { html: string }       | Triggered when HTML is ready   |
-| `close`           | void                   | Triggered when editor closes   |
 
+### Guido Component Props
+
+| 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 |
+| `guidoConfig` | `GuidoConfig` | ✅ | - | Configuration object for the editor |
+
+### 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;
+}
+```
 ---
 
-## 🛠 Development
+| 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
+
+The library exports the following TypeScript types:
+
+```typescript
+// Main component
+import { Guido } from '@useinsider/guido';
+
+// Types
+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',
+  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;
+```
+
+---
+
+## 🔧 Development
+
+### Prerequisites
+
+- 🧄 `Bun` (strongly recommended)
+or
+- NodeJS 18+ & `npm`
+
+### Setup
+
 ```bash
+# Install dependencies
 bun install
+
+# Start development server
 bun start
+
+# Build for production
+bun run build
+
+# Type checking
+bun run type-check
+
+# Linting
+bun run lint
 ```
 
-Build & types:
-```bash
+### 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
+```
+
+### 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
+```
+
+## 🌐 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
 ```
 
+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:
+
+- **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
+
 ---
 
-TODO: 
-[ ] - Default Template @edugencioglu
-[ ] - Using CSS variables into [editor.css](./src/static/editor.css) @berkansezer-useinsider
+## 🔗 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 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,6 +1,11 @@
-export type Translations = {
-    [key: string]: string;
-};
-export type InsiderStripoConfig = {
+import type { CompilerRule } from './html-compiler';
+export type GuidoConfig = {
     translationsPath: string;
+    htmlCompilerRules?: CompilerRule[];
+    ignoreDefaultHtmlCompilerRules?: boolean;
+};
+export type DynamicContent = {
+    value: string;
+    text: string;
+    fallback?: string;
 };

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
+};