@useinsider/guido 1.0.3-beta.a5608d9 → 1.0.3-beta.a60dd8d

package/README.md

@@ -4,309 +4,650 @@
   </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, customizable interface.
 
-## 📚 Table of Contents
-
-- [Install](#-install)
-- [Quick Start](#-quick-start)
-- [Documentation](#-documentation)
-- [Development](#-development)
-- [Contributing](#-contributing)
-- [License](#-license)
-
-## 📖 Documentation
-
-**For comprehensive documentation, visit our [Wiki](./wiki/Home.md):**
-
-- **[Getting Started Guide](./wiki/Getting-Started.md)** - Installation, setup, and basic usage
-- **[API Reference](./wiki/API-Reference.md)** - Complete API documentation with examples
-- **[HTML Compiler Rules](./wiki/HTML-Compiler-Rules.md)** - Advanced HTML transformation guide
-- **[Architecture](./wiki/Architecture.md)** - Project structure and design patterns
-- **[Contributing Guide](./wiki/Contributing.md)** - Development workflow and coding standards
-
 ## 📦 Install
 
 ```bash
 npm install @useinsider/guido
 ```
-
-Or using bun:
-
-```bash
-bun add @useinsider/guido
-```
-
 ### Prerequisites
-
-**Required:** Your project must have `pinia` installed.
-
-**Bundler Configuration** (required for proper module sharing):
-
-<details>
-<summary>Webpack Configuration</summary>
-
-```js
-// webpack.config.js or vue.config.js
-{
+  🍍 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 },
-  }
-}
-```
-</details>
-
-<details>
-<summary>Vite Configuration</summary>
+  },
+  // ... Upcoming Configs
+  ```
 
-```js
-// vite.config.js
-{
+  ##### For Vite: 
+  `/vite.config.js`
+  ```js
+  // ... Previous Configs
   resolve: {
     dedupe: ['vue', 'pinia'],
-  }
-}
-```
-</details>
-
+  },
+  // ... Upcoming Configs
+  ```
 ---
-## 🚀 Quick Start
+## 🚀 Usage
+
+### Basic Usage
 
-```vue
+```html
 <template>
-  <Guido
-    ref="guidoEditor"
-    :template-id="templateId"
-    :user-id="userId"
-    :guido-config="guidoConfig"
-    @save:complete="handleSave"
-  />
+  <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 lang="ts">
 import { Guido } from '@useinsider/guido';
-import '@useinsider/guido/style';
 
 export default {
-  components: { Guido },
-
+  components: {
+    Guido
+  },
   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',
-        useHeader: true,
-        emailHeader: {
-          senderName: 'Your Company',
-          subject: 'Email Subject'
-        },
-        partner: {
-          partnerName: 'your-partner',
-          productType: 1,
-          messageType: 1
-        },
+        htmlCompilerRules: [],
+        ignoreDefaultHtmlCompilerRules: false,
         features: {
           dynamicContent: true,
           saveAsTemplate: true,
           versionHistory: true
         }
-      }
+      },
+      dynamicContentModalVisible: false
     };
   },
 
   methods: {
-    handleSave(template) {
-      console.log('Template saved:', template);
+    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>
 ```
 
-> For complete usage examples including dynamic content, see the [Getting Started Guide](./wiki/Getting-Started.md)
-
-## 📚 API Quick Reference
+## 📚 API
 
-### Props
+### Guido Component Props
 
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `templateId` | `string` | ✅ | Unique identifier for the email template |
-| `userId` | `string` | ✅ | Unique identifier for the user |
-| `guidoConfig` | `GuidoConfig` | ✅ | Configuration object for the editor |
-| `html` | `string` | ⚪ | Initial HTML content |
-| `css` | `string` | ⚪ | Initial CSS styles |
+| 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 |
 
-### Events
+### Guido Component Events
 
 | Event | Payload | Description |
 |-------|---------|-------------|
-| `save:complete` | `Template` | Fired when template is saved |
-| `save:start` | - | Fired when save begins |
-| `dynamic-content:open` | `DynamicContent \| null` | Dynamic content requested |
-| `back` | - | Back button clicked |
-| `ready` | - | Editor is ready |
-| `on-change` | - | Template content changed |
+| `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-message:open` | void | Fired when user clicks test message button. |
+
+### Guido Exposed Methods
+```typescript
+dynamicContent.insert(DynamicContent);
+dynamicContent.close();
+saveSilent();
+```
 
-### Exposed Methods
+### Guido Interfaces
 
 ```typescript
-// Insert dynamic content
-this.$refs.guidoEditor?.dynamicContent.insert({ value, text, fallback });
+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;
+  };
+}
+```
 
-// Close dynamic content modal
-this.$refs.guidoEditor?.dynamicContent.close();
+| 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 |
 
-// Silent save (no notifications)
-this.$refs.guidoEditor?.saveSilent();
+```typescript
+interface DynamicContent {
+  value: string;
+  text: string;
+  fallback?: string;
+}
 ```
+---
 
-> For complete API documentation, see [API Reference](./wiki/API-Reference.md)
+| 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
 
-Transform HTML content with custom rules before saving. Supports 4 rule types:
+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
 
-<details>
-<summary><b>1. Replace Rule</b> - String replacement</summary>
+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',
-  replacement: '%7B%22',
-  priority: 10
+  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)
 }
 ```
-</details>
 
-<details>
-<summary><b>2. Regex Rule</b> - Pattern matching</summary>
+#### 2. Regex Rule
+Use regular expressions for complex pattern matching and replacement.
 
 ```typescript
 {
   id: 'remove-comments',
+  description: 'Remove HTML comments',
   type: 'regex',
-  pattern: '<!--.*?-->',
-  replacement: '',
-  flags: 'g',
+  pattern: '<!--.*?-->',    // Regex pattern
+  replacement: '',          // Replacement string
+  flags: 'g',              // Regex flags (default: 'g')
   priority: 20
 }
 ```
-</details>
 
-<details>
-<summary><b>3. Remove Rule</b> - Remove content</summary>
+#### 3. Remove Rule
+Remove specific strings or patterns from HTML content.
 
 ```typescript
 {
   id: 'cleanup-scripts',
+  description: 'Remove unwanted script tags',
   type: 'remove',
-  targets: [
+  targets: [                              // Array of strings or RegExp objects
     '<script src="unwanted.js"></script>',
     /onclick="[^"]*"/g
   ],
   priority: 30
 }
 ```
-</details>
 
-<details>
-<summary><b>4. Custom Rule</b> - Custom processor</summary>
+#### 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
 }
 ```
-</details>
 
-### Quick Example
+### 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
     }
   ]
 };
 ```
 
-> For comprehensive compiler rules documentation, see [HTML Compiler Rules Guide](./wiki/HTML-Compiler-Rules.md)
+### 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
 
-### Quick Commands
+### Prerequisites
+
+- 🧄 `Bun` (strongly recommended)
+or
+- NodeJS 18+ & `npm`
+
+### Setup
 
 ```bash
 # Install dependencies
 bun install
 
-# Start dev server (localhost:3000)
+# Start development server
 bun start
 
-# Build library
+# Build for production
 bun run build
 
-# Run linting & type checking
+# Type checking
+bun run type-check
+
+# Linting
 bun run lint
 ```
 
-### Local Testing
+### Environment Variables
 
-Test the package locally before publishing:
+Create a `.env` file with the following variables: (You can get env variables from your senior)
 
-```bash
-# Build and create tarball
-bun run build && npm pack
+```env
+VITE_STRIPO_PLUGIN_ID=your_plugin_id
+VITE_STRIPO_SECRET_KEY=your_secret_key
+VITE_STRIPO_ROLE=your_role
+```
+
+### Project Structure
 
-# Install in your project
-npm i ./useinsider-guido-1.0.3.tgz
+```
+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
 ```
 
-> For complete development setup, project structure, and contribution guidelines, see [Contributing Guide](./wiki/Contributing.md)
+## 🔌 Provide/Inject Utilities
 
-## 🤝 Contributing
+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');
 
-Contributions are welcome! Please follow these guidelines:
+// Provide the value
+const myService = new MyService();
+provideValue(MyServiceKey, myService);
 
-- **PR Title Format**: `TASK-ID | EMOJI | Clear Description`
-  - Example: `SD-12345 | ✨ | Add new feature`
-- **PR Requirements**:
-  - Fill PR labels
-  - Assign to yourself
-  - Include tests
-  - Pass all checks before review
+// Child component
+import { useInjectedValue } from '@useinsider/guido';
 
-> For detailed contribution guidelines, see [Contributing Guide](./wiki/Contributing.md)
+// 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
+```
+
+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
 
-## 🔗 Related Resources
+---
+
+## 🔗 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
 
----
-
-**Made with ❤️ by the Insider Team**
+## 🎯 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