mitway-tagger 1.3.0

package/README.md

@@ -0,0 +1,256 @@
+# mITway Tagger
+
+Vite plugin suite for Mesh IT Midway integration. Provides everything needed for the mITway-Starter template to communicate with mITway-App.
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **JSX Source Tracking** | Injects source location metadata into React components for visual editing |
+| **Virtual Overrides** | Temporary file modifications with HMR support (no disk writes) |
+| **Visual Editor** | Element selection and live style preview via postMessage |
+| **Iframe Navigation** | Notifies parent window of navigation changes |
+| **Theme Bridge** | Real-time theme preview from mITway-App |
+| **Server Config** | Pre-configured CORS and CSP settings for iframe integration |
+
+## Installation
+
+```bash
+pnpm add -D mitway-tagger
+```
+
+## Usage
+
+### Basic (all features enabled)
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react-swc';
+import { mitwayTagger } from 'mitway-tagger';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    ...mitwayTagger()
+  ]
+});
+```
+
+### With options
+
+```typescript
+import { mitwayTagger } from 'mitway-tagger';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    ...mitwayTagger({
+      jsxSource: true,        // JSX source tracking (default: true)
+      virtualOverrides: true, // Virtual file overrides (default: true)
+      visualEditor: true,     // Visual editor support (default: true)
+      iframeNavigation: true, // Iframe navigation events (default: true)
+      themeBridge: true,      // Theme preview bridge (default: true)
+    })
+  ]
+});
+```
+
+### Individual plugins
+
+```typescript
+import {
+  createJsxSourcePlugin,
+  createVirtualOverridesPlugin,
+  createVisualEditorPlugin,
+  createIframeNavigationPlugin,
+  createThemeBridgePlugin
+} from 'mitway-tagger';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    createJsxSourcePlugin({ extensions: ['.tsx'], exclude: ['node_modules'] }),
+    createVisualEditorPlugin(),
+    createThemeBridgePlugin(),
+    // ... only the plugins you need
+  ]
+});
+```
+
+## Features Detail
+
+### 1. JSX Source Tracking
+
+Intercepts `react/jsx-dev-runtime` to attach source location metadata to DOM nodes via a Symbol. This enables the Visual Editor to map selected elements back to their source code.
+
+```javascript
+// How it works:
+// Every React element gets a Symbol attached with source info
+element[Symbol.for('__mitwaySource__')] = {
+  fileName: '/src/components/Button.tsx',
+  lineNumber: 42,
+  columnNumber: 8
+};
+```
+
+### 2. Virtual Overrides
+
+Allows mITway-App to send temporary file modifications via WebSocket. Changes are applied in-memory and trigger HMR without writing to disk.
+
+**WebSocket events:**
+- `mitway:override` - Apply temporary file override
+- `mitway:clear-override` - Clear override for a file
+- `mitway:clear-all-overrides` - Clear all overrides
+
+### 3. Visual Editor
+
+Injects a script that enables:
+- Element highlighting on hover
+- Element selection with visual overlay
+- Live style preview via inline styles
+- Communication with parent window via postMessage
+
+**Message types (to parent):**
+- `VISUAL_EDITOR_ELEMENT_SELECTED` - Element was selected
+- `VISUAL_EDITOR_ELEMENT_DESELECTED` - Selection cleared
+- `VISUAL_EDITOR_HOVER` - Element being hovered
+
+**Message types (from parent):**
+- `VISUAL_EDITOR_ACTIVATE` - Enable selection mode
+- `VISUAL_EDITOR_DEACTIVATE` - Disable selection mode
+- `VISUAL_EDITOR_PREVIEW_STYLE` - Preview styles on element
+- `VISUAL_EDITOR_RESTORE_STYLE` - Restore original styles
+
+### 4. Iframe Navigation
+
+Notifies mITway-App when navigation occurs within the iframe:
+- Intercepts `history.pushState` and `history.replaceState`
+- Listens for `popstate` events
+- Sends `IFRAME_NAVIGATION` messages to parent
+- Receives `NAVIGATE_TO` commands from parent
+
+### 5. Theme Bridge
+
+Enables real-time theme preview:
+- Captures original CSS variable values
+- Applies theme colors with proper HSL wrapping
+- Supports both base (`--background`) and color-prefixed (`--color-background`) variables
+- Handles radius variables separately
+
+**Message types (from parent):**
+- `PREVIEW_THEME` - Preview theme without persisting
+- `RESTORE_THEME` - Restore original CSS variables
+- `APPLY_THEME` - Apply and persist theme
+
+**Message types (to parent):**
+- `THEME_BRIDGE_READY` - Bridge initialized
+- `THEME_APPLIED` - Theme was applied
+
+## Server Configuration
+
+Mesh IT Midway requires specific CORS and CSP settings to work properly inside iframes. The package exports pre-configured server settings:
+
+### Using `mitwayServerConfig`
+
+```typescript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react-swc';
+import path from 'path';
+import { mitwayTagger, mitwayServerConfig } from 'mitway-tagger';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    ...mitwayTagger()
+  ],
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    },
+  },
+  server: mitwayServerConfig,
+  preview: mitwayServerConfig,
+});
+```
+
+### With custom domains
+
+If you need to add custom domains to the allowed origins:
+
+```typescript
+import { mitwayTagger, createmITwayServerConfig } from 'mitway-tagger';
+
+const serverConfig = createmITwayServerConfig({
+  additionalOrigins: ['https://my-custom-domain.com'],
+  additionalHosts: ['.my-custom-domain.com'],
+  port: 3000, // optional, defaults to 80
+});
+
+export default defineConfig({
+  plugins: [react(), ...mitwayTagger()],
+  server: serverConfig,
+  preview: serverConfig,
+});
+```
+
+### What's included in `mitwayServerConfig`
+
+| Setting | Value |
+|---------|-------|
+| **Host** | `0.0.0.0` |
+| **Port** | `80` |
+| **CORS Origins** | `app.nttmitway.com`, `app.dev.nttmitway.com`, `app.mitway.local`, `localhost:*` |
+| **CORS Methods** | GET, POST, PUT, DELETE, OPTIONS |
+| **CORS Headers** | Content-Type, Authorization |
+| **CSP frame-ancestors** | Same as CORS origins |
+| **Allowed Hosts** | `.azurecontainerapps.io`, `.nttmitway.com` |
+
+## mITway-Starter Integration
+
+With `mitway-tagger`, your `vite.config.ts` becomes minimal:
+
+```typescript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react-swc';
+import path from 'path';
+import { mitwayTagger, mitwayServerConfig } from 'mitway-tagger';
+
+export default defineConfig({
+  plugins: [react(), ...mitwayTagger()],
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    },
+  },
+  server: mitwayServerConfig,
+  preview: mitwayServerConfig,
+});
+```
+
+No need for separate plugin files or manual CORS/CSP configuration - everything is included in `mitway-tagger`.
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build
+pnpm build
+
+# Watch mode
+pnpm dev
+```
+
+## Publishing
+
+```bash
+# Build and publish
+pnpm build
+npm publish
+```
+
+## License
+
+MIT