mitway-tagger 1.3.0

package/dist/index.d.cts

@@ -0,0 +1,204 @@
+import { Plugin } from 'vite';
+
+/**
+ * JSX Source Tracking Plugin
+ *
+ * Intercepts react/jsx-dev-runtime to inject source location metadata
+ * into React components. This allows mapping rendered DOM elements
+ * back to their source code locations.
+ */
+
+interface JsxSourceOptions {
+    extensions: string[];
+    exclude: string[];
+}
+/**
+ * Creates the JSX source tracking plugin
+ */
+declare function createJsxSourcePlugin(options: JsxSourceOptions): Plugin;
+
+/**
+ * Virtual Overrides Plugin
+ *
+ * Allows temporary file modifications without writing to disk.
+ * Uses Vite's HMR system to update modules in real-time.
+ *
+ * Communication is done via WebSocket events:
+ * - mitway:override - Set a virtual override for a file
+ * - mitway:clear-override - Clear a specific override
+ * - mitway:clear-all-overrides - Clear all overrides
+ */
+
+/**
+ * Creates the virtual overrides plugin
+ */
+declare function createVirtualOverridesPlugin(): Plugin;
+
+/**
+ * Visual Editor Plugin
+ *
+ * Injects a script into the HTML that enables:
+ * - Element selection with visual overlays
+ * - Style preview in real-time
+ * - Communication with parent window via postMessage
+ * - Reading source info from jsxSource plugin
+ */
+
+/**
+ * Creates the visual editor plugin
+ */
+declare function createVisualEditorPlugin(): Plugin;
+
+/**
+ * Iframe Navigation Plugin
+ *
+ * Notifies the parent window (mITway-App) when navigation occurs in the iframe.
+ * Also listens for navigation commands from the parent.
+ *
+ * Features:
+ * - Intercepts history.pushState and history.replaceState
+ * - Listens for popstate events
+ * - Sends IFRAME_NAVIGATION messages to parent
+ * - Receives NAVIGATE_TO commands from parent
+ */
+
+/**
+ * Creates the iframe navigation plugin
+ */
+declare function createIframeNavigationPlugin(): Plugin;
+
+/**
+ * Theme Bridge Plugin
+ *
+ * Enables real-time theme preview from mITway-App via postMessage.
+ * Allows the parent window to preview, apply, and restore themes.
+ *
+ * Features:
+ * - 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 (no HSL wrapper)
+ * - Notifies parent when theme bridge is ready
+ *
+ * Message types:
+ * - PREVIEW_THEME: Preview theme without persisting
+ * - RESTORE_THEME: Restore original CSS variables
+ * - APPLY_THEME: Apply and persist theme
+ * - THEME_BRIDGE_READY: Sent when bridge initializes
+ * - THEME_APPLIED: Sent after theme is applied
+ */
+
+/**
+ * Creates the theme bridge plugin
+ */
+declare function createThemeBridgePlugin(): Plugin;
+
+/**
+ * mITway Tagger - Vite plugin suite for mITway integration
+ *
+ * This plugin provides five main features:
+ * 1. JSX Source Tracking - Injects source location metadata into React components
+ * 2. Virtual Overrides - Allows temporary file modifications with HMR support
+ * 3. Visual Editor - Enables element selection and live style preview via postMessage
+ * 4. Iframe Navigation - Notifies parent window of navigation changes
+ * 5. Theme Bridge - Enables real-time theme preview from mITway-App
+ */
+
+interface mITwayTaggerOptions {
+    /**
+     * Enable JSX source tracking
+     * @default true
+     */
+    jsxSource?: boolean;
+    /**
+     * Enable virtual file overrides with HMR
+     * @default true
+     */
+    virtualOverrides?: boolean;
+    /**
+     * Enable visual editor for element selection and style preview
+     * @default true
+     */
+    visualEditor?: boolean;
+    /**
+     * Enable iframe navigation notifications to parent window
+     * @default true
+     */
+    iframeNavigation?: boolean;
+    /**
+     * Enable theme bridge for real-time theme preview
+     * @default true
+     */
+    themeBridge?: boolean;
+    /**
+     * File extensions to process for JSX source tracking
+     * @default ['.jsx', '.tsx']
+     */
+    extensions?: string[];
+    /**
+     * Directories to exclude from processing
+     * @default ['node_modules', '.git']
+     */
+    exclude?: string[];
+}
+/**
+ * Creates the mITway Tagger Vite plugin suite
+ *
+ * @example
+ * // Enable all features (default)
+ * mitwayTagger()
+ *
+ * @example
+ * // Disable specific features
+ * mitwayTagger({ jsxSource: false, virtualOverrides: false })
+ */
+declare function mitwayTagger(options?: mITwayTaggerOptions): Plugin[];
+
+/**
+ * Server configuration interface for mITway iframe integration
+ */
+interface mITwayServerConfig {
+    host: string;
+    port: number;
+    cors: {
+        origin: (string | RegExp)[];
+        methods: string[];
+        allowedHeaders: string[];
+        credentials: boolean;
+    };
+    headers: Record<string, string>;
+    allowedHosts: string[];
+}
+/**
+ * Pre-configured server settings for mITway iframe integration.
+ * Includes host, port, CORS, CSP headers, and allowed hosts.
+ * Use directly with Vite's server and preview options.
+ *
+ * @example
+ * // vite.config.ts
+ * import { mitwayTagger, mitwayServerConfig } from 'mitway-tagger';
+ *
+ * export default defineConfig({
+ *   plugins: [react(), ...mitwayTagger()],
+ *   server: mitwayServerConfig,
+ *   preview: mitwayServerConfig,
+ * });
+ */
+declare const mitwayServerConfig: mITwayServerConfig;
+/**
+ * Creates a customized server config by merging with additional origins.
+ * Useful when you need to add custom domains to the CORS and CSP settings.
+ *
+ * @example
+ * const config = createmITwayServerConfig({
+ *   additionalOrigins: ['https://my-custom-domain.com'],
+ *   additionalHosts: ['.my-custom-domain.com'],
+ * });
+ */
+declare function createmITwayServerConfig(options?: {
+    additionalOrigins?: (string | RegExp)[];
+    additionalHosts?: string[];
+    port?: number;
+}): mITwayServerConfig;
+
+export { createIframeNavigationPlugin, createJsxSourcePlugin, createThemeBridgePlugin, createVirtualOverridesPlugin, createVisualEditorPlugin, createmITwayServerConfig, mitwayTagger as default, type mITwayServerConfig, type mITwayTaggerOptions, mitwayServerConfig, mitwayTagger };

package/dist/index.d.ts

@@ -0,0 +1,204 @@
+import { Plugin } from 'vite';
+
+/**
+ * JSX Source Tracking Plugin
+ *
+ * Intercepts react/jsx-dev-runtime to inject source location metadata
+ * into React components. This allows mapping rendered DOM elements
+ * back to their source code locations.
+ */
+
+interface JsxSourceOptions {
+    extensions: string[];
+    exclude: string[];
+}
+/**
+ * Creates the JSX source tracking plugin
+ */
+declare function createJsxSourcePlugin(options: JsxSourceOptions): Plugin;
+
+/**
+ * Virtual Overrides Plugin
+ *
+ * Allows temporary file modifications without writing to disk.
+ * Uses Vite's HMR system to update modules in real-time.
+ *
+ * Communication is done via WebSocket events:
+ * - mitway:override - Set a virtual override for a file
+ * - mitway:clear-override - Clear a specific override
+ * - mitway:clear-all-overrides - Clear all overrides
+ */
+
+/**
+ * Creates the virtual overrides plugin
+ */
+declare function createVirtualOverridesPlugin(): Plugin;
+
+/**
+ * Visual Editor Plugin
+ *
+ * Injects a script into the HTML that enables:
+ * - Element selection with visual overlays
+ * - Style preview in real-time
+ * - Communication with parent window via postMessage
+ * - Reading source info from jsxSource plugin
+ */
+
+/**
+ * Creates the visual editor plugin
+ */
+declare function createVisualEditorPlugin(): Plugin;
+
+/**
+ * Iframe Navigation Plugin
+ *
+ * Notifies the parent window (mITway-App) when navigation occurs in the iframe.
+ * Also listens for navigation commands from the parent.
+ *
+ * Features:
+ * - Intercepts history.pushState and history.replaceState
+ * - Listens for popstate events
+ * - Sends IFRAME_NAVIGATION messages to parent
+ * - Receives NAVIGATE_TO commands from parent
+ */
+
+/**
+ * Creates the iframe navigation plugin
+ */
+declare function createIframeNavigationPlugin(): Plugin;
+
+/**
+ * Theme Bridge Plugin
+ *
+ * Enables real-time theme preview from mITway-App via postMessage.
+ * Allows the parent window to preview, apply, and restore themes.
+ *
+ * Features:
+ * - 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 (no HSL wrapper)
+ * - Notifies parent when theme bridge is ready
+ *
+ * Message types:
+ * - PREVIEW_THEME: Preview theme without persisting
+ * - RESTORE_THEME: Restore original CSS variables
+ * - APPLY_THEME: Apply and persist theme
+ * - THEME_BRIDGE_READY: Sent when bridge initializes
+ * - THEME_APPLIED: Sent after theme is applied
+ */
+
+/**
+ * Creates the theme bridge plugin
+ */
+declare function createThemeBridgePlugin(): Plugin;
+
+/**
+ * mITway Tagger - Vite plugin suite for mITway integration
+ *
+ * This plugin provides five main features:
+ * 1. JSX Source Tracking - Injects source location metadata into React components
+ * 2. Virtual Overrides - Allows temporary file modifications with HMR support
+ * 3. Visual Editor - Enables element selection and live style preview via postMessage
+ * 4. Iframe Navigation - Notifies parent window of navigation changes
+ * 5. Theme Bridge - Enables real-time theme preview from mITway-App
+ */
+
+interface mITwayTaggerOptions {
+    /**
+     * Enable JSX source tracking
+     * @default true
+     */
+    jsxSource?: boolean;
+    /**
+     * Enable virtual file overrides with HMR
+     * @default true
+     */
+    virtualOverrides?: boolean;
+    /**
+     * Enable visual editor for element selection and style preview
+     * @default true
+     */
+    visualEditor?: boolean;
+    /**
+     * Enable iframe navigation notifications to parent window
+     * @default true
+     */
+    iframeNavigation?: boolean;
+    /**
+     * Enable theme bridge for real-time theme preview
+     * @default true
+     */
+    themeBridge?: boolean;
+    /**
+     * File extensions to process for JSX source tracking
+     * @default ['.jsx', '.tsx']
+     */
+    extensions?: string[];
+    /**
+     * Directories to exclude from processing
+     * @default ['node_modules', '.git']
+     */
+    exclude?: string[];
+}
+/**
+ * Creates the mITway Tagger Vite plugin suite
+ *
+ * @example
+ * // Enable all features (default)
+ * mitwayTagger()
+ *
+ * @example
+ * // Disable specific features
+ * mitwayTagger({ jsxSource: false, virtualOverrides: false })
+ */
+declare function mitwayTagger(options?: mITwayTaggerOptions): Plugin[];
+
+/**
+ * Server configuration interface for mITway iframe integration
+ */
+interface mITwayServerConfig {
+    host: string;
+    port: number;
+    cors: {
+        origin: (string | RegExp)[];
+        methods: string[];
+        allowedHeaders: string[];
+        credentials: boolean;
+    };
+    headers: Record<string, string>;
+    allowedHosts: string[];
+}
+/**
+ * Pre-configured server settings for mITway iframe integration.
+ * Includes host, port, CORS, CSP headers, and allowed hosts.
+ * Use directly with Vite's server and preview options.
+ *
+ * @example
+ * // vite.config.ts
+ * import { mitwayTagger, mitwayServerConfig } from 'mitway-tagger';
+ *
+ * export default defineConfig({
+ *   plugins: [react(), ...mitwayTagger()],
+ *   server: mitwayServerConfig,
+ *   preview: mitwayServerConfig,
+ * });
+ */
+declare const mitwayServerConfig: mITwayServerConfig;
+/**
+ * Creates a customized server config by merging with additional origins.
+ * Useful when you need to add custom domains to the CORS and CSP settings.
+ *
+ * @example
+ * const config = createmITwayServerConfig({
+ *   additionalOrigins: ['https://my-custom-domain.com'],
+ *   additionalHosts: ['.my-custom-domain.com'],
+ * });
+ */
+declare function createmITwayServerConfig(options?: {
+    additionalOrigins?: (string | RegExp)[];
+    additionalHosts?: string[];
+    port?: number;
+}): mITwayServerConfig;
+
+export { createIframeNavigationPlugin, createJsxSourcePlugin, createThemeBridgePlugin, createVirtualOverridesPlugin, createVisualEditorPlugin, createmITwayServerConfig, mitwayTagger as default, type mITwayServerConfig, type mITwayTaggerOptions, mitwayServerConfig, mitwayTagger };