@clidey/dory 0.29.0 → 0.31.0

package/src/embed/widget-iframe.ts

@@ -0,0 +1,302 @@
+/**
+ * Dory Widget Shell (Stage 2) - Iframe Approach
+ * Creates an iframe pointing to the already-built documentation
+ * This is simpler and more reliable than rebuilding the app
+ */
+
+import type { DoryEmbedConfig } from './types';
+
+export class DoryWidget {
+  private config: DoryEmbedConfig;
+  private container: HTMLElement | null = null;
+  private iframe: HTMLIFrameElement | null = null;
+  private overlay: HTMLElement | null = null;
+  private isOpenState = false;
+  private eventHandlers: Map<string, Function[]> = new Map();
+
+  constructor(config: DoryEmbedConfig) {
+    this.config = config;
+    this.init();
+  }
+
+  private init() {
+    this.createContainer();
+    this.setupEventListeners();
+  }
+
+  private createContainer() {
+    // Create overlay
+    if (this.config.showOverlay !== false) {
+      this.overlay = document.createElement('div');
+      this.overlay.className = 'dory-embed-overlay';
+      this.overlay.style.cssText = `
+        position: fixed;
+        inset: 0;
+        background: rgba(0, 0, 0, 0.5);
+        z-index: 999998;
+        opacity: 0;
+        pointer-events: none;
+        transition: opacity 0.3s ease;
+      `;
+
+      if (this.config.closeOnOverlayClick !== false) {
+        this.overlay.addEventListener('click', () => this.close());
+      }
+
+      document.body.appendChild(this.overlay);
+    }
+
+    // Create main container
+    this.container = document.createElement('div');
+    this.container.className = 'dory-embed-container';
+    this.container.setAttribute('data-position', this.config.position || 'right');
+    this.container.style.cssText = this.getContainerStyles();
+
+    // Create iframe
+    this.iframe = document.createElement('iframe');
+    this.iframe.style.cssText = 'width: 100%; height: 100%; border: none;';
+    this.iframe.setAttribute('sandbox', 'allow-scripts allow-same-origin allow-popups');
+    this.iframe.src = this.buildIframeUrl();
+
+    this.container.appendChild(this.iframe);
+
+    // Add container to body
+    document.body.appendChild(this.container);
+
+    // Setup iframe communication
+    this.setupIframeMessaging();
+  }
+
+  private buildIframeUrl(): string {
+    const baseUrl = this.config.baseUrl;
+    const path = this.config.initialPath || '/';
+    const params = new URLSearchParams();
+
+    // Add embedded mode flag
+    params.set('embedded', 'true');
+
+    // Add theme
+    if (this.config.theme && this.config.theme !== 'inherit') {
+      params.set('theme', this.config.theme);
+    }
+
+    const url = new URL(baseUrl);
+    url.pathname = path;
+    url.search = params.toString();
+
+    return url.toString();
+  }
+
+  private setupIframeMessaging() {
+    window.addEventListener('message', (event) => {
+      // Verify origin
+      if (event.origin !== new URL(this.config.baseUrl).origin) {
+        return;
+      }
+
+      const message = event.data;
+
+      switch (message.type) {
+        case 'navigate':
+          this.emit('navigate', message.path);
+          break;
+        case 'ready':
+          this.emit('ready');
+          break;
+      }
+    });
+  }
+
+  private getContainerStyles(): string {
+    const { position = 'right', width = 500, height = '100vh' } = this.config;
+    const widthStr = typeof width === 'number' ? `${width}px` : width;
+
+    const baseStyles = `
+      position: fixed;
+      z-index: 999999;
+      background: white;
+      box-shadow: -2px 0 20px rgba(0, 0, 0, 0.15);
+      transition: transform 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+      will-change: transform;
+      overflow: hidden;
+    `;
+
+    const positionStyles = {
+      right: `
+        top: 0;
+        right: 0;
+        bottom: 0;
+        width: ${widthStr};
+        max-width: 100vw;
+        transform: translateX(100%);
+      `,
+      left: `
+        top: 0;
+        left: 0;
+        bottom: 0;
+        width: ${widthStr};
+        max-width: 100vw;
+        transform: translateX(-100%);
+      `,
+      bottom: `
+        bottom: 0;
+        left: 0;
+        right: 0;
+        height: ${height};
+        max-height: 90vh;
+        transform: translateY(100%);
+      `,
+    };
+
+    return baseStyles + positionStyles[position];
+  }
+
+  private setupEventListeners() {
+    // Keyboard shortcuts
+    const handleKeydown = (e: KeyboardEvent) => {
+      // ESC to close
+      if (e.key === 'Escape' && this.isOpenState && this.config.closeOnEscape !== false) {
+        this.close();
+      }
+    };
+
+    document.addEventListener('keydown', handleKeydown);
+
+    // Store cleanup function
+    (this.container as any).__cleanup = () => {
+      document.removeEventListener('keydown', handleKeydown);
+    };
+  }
+
+  async open(path?: string) {
+    if (this.isOpenState) {
+      if (path) this.navigate(path);
+      return;
+    }
+
+    this.isOpenState = true;
+
+    // Show overlay
+    if (this.overlay) {
+      this.overlay.style.opacity = '1';
+      this.overlay.style.pointerEvents = 'auto';
+    }
+
+    // Slide in container
+    if (this.container) {
+      this.container.style.transform = 'translate(0, 0)';
+    }
+
+    // Update iframe URL if path is specified
+    if (path && this.iframe) {
+      const url = new URL(this.iframe.src);
+      url.pathname = path;
+      this.iframe.src = url.toString();
+    }
+
+    // Focus management
+    this.container?.focus();
+
+    // Disable body scroll
+    document.body.style.overflow = 'hidden';
+
+    // Emit event
+    this.emit('open');
+  }
+
+  close() {
+    if (!this.isOpenState) return;
+
+    this.isOpenState = false;
+
+    // Hide overlay
+    if (this.overlay) {
+      this.overlay.style.opacity = '0';
+      this.overlay.style.pointerEvents = 'none';
+    }
+
+    // Slide out container
+    if (this.container) {
+      const { position = 'right' } = this.config;
+      const transforms: Record<string, string> = {
+        right: 'translateX(100%)',
+        left: 'translateX(-100%)',
+        bottom: 'translateY(100%)',
+      };
+      this.container.style.transform = transforms[position];
+    }
+
+    // Re-enable body scroll
+    document.body.style.overflow = '';
+
+    // Emit event
+    this.emit('close');
+  }
+
+  toggle() {
+    this.isOpenState ? this.close() : this.open();
+  }
+
+  navigate(path: string) {
+    if (this.iframe) {
+      const url = new URL(this.iframe.src);
+      url.pathname = path;
+      this.iframe.src = url.toString();
+      this.emit('navigate', path);
+    }
+  }
+
+  setTheme(theme: 'light' | 'dark') {
+    if (this.iframe) {
+      const url = new URL(this.iframe.src);
+      url.searchParams.set('theme', theme);
+      this.iframe.src = url.toString();
+    }
+  }
+
+  isOpen() {
+    return this.isOpenState;
+  }
+
+  on(event: string, handler: Function) {
+    if (!this.eventHandlers.has(event)) {
+      this.eventHandlers.set(event, []);
+    }
+    this.eventHandlers.get(event)!.push(handler);
+  }
+
+  private emit(event: string, ...args: any[]) {
+    const handlers = this.eventHandlers.get(event);
+    if (handlers) {
+      handlers.forEach(handler => {
+        try {
+          handler(...args);
+        } catch (error) {
+          console.error(`[DoryDocs] Error in ${event} handler:`, error);
+        }
+      });
+    }
+  }
+
+  destroy() {
+    // Cleanup event listeners
+    if (this.container && (this.container as any).__cleanup) {
+      (this.container as any).__cleanup();
+    }
+
+    // Remove DOM elements
+    this.container?.remove();
+    this.overlay?.remove();
+
+    // Clear references
+    this.container = null;
+    this.iframe = null;
+    this.overlay = null;
+    this.eventHandlers.clear();
+  }
+}
+
+// Expose widget globally for loader script
+if (typeof window !== 'undefined') {
+  window.__DoryWidget__ = DoryWidget;
+}

package/src/plugins/html-files-middleware.ts

@@ -0,0 +1,108 @@
+import type { Plugin } from 'vite';
+import { readFileSync, existsSync, statSync } from 'fs';
+import { resolve, extname } from 'path';
+
+/**
+ * Vite plugin to serve HTML files and assets directly from the docs directory
+ * and static files from the dist directory without routing them through the SPA
+ */
+export function htmlFilesMiddleware(): Plugin {
+  // Define asset extensions
+  const assetExtensions = new Set([
+    '.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.ico',
+    '.pdf', '.mp4', '.webm', '.mp3', '.wav', '.mov',
+    '.woff', '.woff2', '.ttf', '.eot',
+  ]);
+
+  // Map extensions to MIME types
+  const mimeTypes: Record<string, string> = {
+    '.html': 'text/html',
+    '.js': 'application/javascript',
+    '.css': 'text/css',
+    '.json': 'application/json',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.ico': 'image/x-icon',
+    '.pdf': 'application/pdf',
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.mov': 'video/quicktime',
+    '.mp3': 'audio/mpeg',
+    '.wav': 'audio/wav',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.eot': 'application/vnd.ms-fontobject',
+  };
+
+  return {
+    name: 'html-files-middleware',
+    configureServer(server) {
+      server.middlewares.use((req, res, next) => {
+        if (!req.url) {
+          next();
+          return;
+        }
+
+        // Remove query params
+        const url = req.url.split('?')[0];
+
+        // Check if the request is for a file in the dist directory
+        if (url.startsWith('/dist/')) {
+          const distPath = resolve(process.cwd(), url.slice(1));
+
+          if (existsSync(distPath)) {
+            try {
+              const content = readFileSync(distPath, 'utf-8');
+              const ext = extname(url).toLowerCase();
+              const contentType = mimeTypes[ext] || 'application/octet-stream';
+
+              res.setHeader('Content-Type', contentType);
+              res.setHeader('Cache-Control', 'no-cache');
+              res.setHeader('Access-Control-Allow-Origin', '*');
+              res.end(content);
+              return;
+            } catch (error) {
+              console.error(`Error reading ${distPath}:`, error);
+            }
+          }
+        }
+
+        // Check if the request is for a file in the docs directory
+        // This handles both direct file requests and directory requests
+        const docsPath = resolve(process.cwd(), 'docs', url.slice(1));
+
+        if (existsSync(docsPath)) {
+          try {
+            const stats = statSync(docsPath);
+
+            // If it's a file, serve it
+            if (stats.isFile()) {
+              const ext = extname(url).toLowerCase();
+
+              // Only serve HTML files and assets, not MDX files
+              if (url.endsWith('.html') || assetExtensions.has(ext)) {
+                const content = readFileSync(docsPath);
+                const contentType = mimeTypes[ext] || 'application/octet-stream';
+
+                res.setHeader('Content-Type', contentType);
+                res.setHeader('Cache-Control', 'no-cache');
+                res.setHeader('Access-Control-Allow-Origin', '*');
+                res.end(content);
+                return;
+              }
+            }
+          } catch (error) {
+            console.error(`Error reading ${docsPath}:`, error);
+          }
+        }
+
+        next();
+      });
+    },
+  };
+}

package/src/sdk/index.ts

@@ -0,0 +1,89 @@
+/**
+ * Dory Embedded Documentation SDK
+ * Export all framework integrations
+ */
+
+// Re-export React SDK
+export { useDoryDocs as useReactDoryDocs, DoryDocsTrigger, DoryDocsProvider } from './react';
+
+// Re-export Vue SDK
+export { useDoryDocs as useVueDoryDocs } from './vue';
+
+// Export types
+export type { DoryEmbedConfig } from '../embed/types';
+
+// Export vanilla JS API reference
+export interface DoryDocsAPI {
+  init(config: Partial<any>): DoryDocsAPI;
+  open(path?: string): Promise<void>;
+  close(): Promise<void>;
+  toggle(): Promise<void>;
+  navigate(path: string): Promise<void>;
+  setTheme(theme: 'light' | 'dark'): Promise<void>;
+  isOpen(): boolean;
+  destroy(): Promise<void>;
+  on(event: string, handler: Function): DoryDocsAPI;
+}
+
+/**
+ * Check if DoryDocs is loaded
+ */
+export function isDoryDocsLoaded(): boolean {
+  return typeof window !== 'undefined' && !!window.DoryDocs;
+}
+
+/**
+ * Wait for DoryDocs to be loaded
+ */
+export function waitForDoryDocs(timeout = 5000): Promise<boolean> {
+  return new Promise((resolve) => {
+    if (isDoryDocsLoaded()) {
+      resolve(true);
+      return;
+    }
+
+    const timeoutId = setTimeout(() => {
+      window.removeEventListener('dory:ready', handleReady);
+      resolve(false);
+    }, timeout);
+
+    const handleReady = () => {
+      clearTimeout(timeoutId);
+      resolve(true);
+    };
+
+    window.addEventListener('dory:ready', handleReady, { once: true });
+  });
+}
+
+/**
+ * Load Dory embed script dynamically
+ */
+export function loadDoryScript(docsUrl: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (isDoryDocsLoaded()) {
+      resolve();
+      return;
+    }
+
+    const script = document.createElement('script');
+    script.src = `${docsUrl}/embed.js`;
+    script.async = true;
+
+    script.onload = () => {
+      waitForDoryDocs().then((loaded) => {
+        if (loaded) {
+          resolve();
+        } else {
+          reject(new Error('DoryDocs failed to initialize'));
+        }
+      });
+    };
+
+    script.onerror = () => {
+      reject(new Error('Failed to load DoryDocs script'));
+    };
+
+    document.head.appendChild(script);
+  });
+}

package/src/sdk/react.tsx

@@ -0,0 +1,139 @@
+/**
+ * React SDK for Dory Embedded Documentation
+ * Usage: npm install @clidey/dory-embedded
+ */
+
+import { useEffect, useRef, useCallback } from 'react';
+import type { DoryDocsAPI } from '../embed/types';
+
+interface DoryDocsConfig {
+  docsUrl: string;
+  position?: 'left' | 'right' | 'bottom';
+  width?: number | string;
+  height?: string;
+  theme?: 'light' | 'dark' | 'inherit';
+  initialPath?: string;
+  showOverlay?: boolean;
+  closeOnEscape?: boolean;
+  closeOnOverlayClick?: boolean;
+  onOpen?: () => void;
+  onClose?: () => void;
+  onNavigate?: (path: string) => void;
+  onReady?: () => void;
+}
+
+/**
+ * Hook to use Dory Documentation in React components
+ */
+export function useDoryDocs(config: DoryDocsConfig) {
+  const docsRef = useRef<any>(null);
+  const configRef = useRef(config);
+
+  useEffect(() => {
+    configRef.current = config;
+  }, [config]);
+
+  useEffect(() => {
+    // Wait for DoryDocs to be available
+    const checkDoryDocs = () => {
+      if (window.DoryDocs) {
+        docsRef.current = window.DoryDocs.init(configRef.current);
+      } else {
+        console.warn('[useDoryDocs] DoryDocs not loaded. Make sure to include the embed script.');
+      }
+    };
+
+    if (document.readyState === 'loading') {
+      window.addEventListener('dory:ready', checkDoryDocs);
+    } else {
+      checkDoryDocs();
+    }
+
+    return () => {
+      window.removeEventListener('dory:ready', checkDoryDocs);
+      docsRef.current?.destroy();
+    };
+  }, []);
+
+  const open = useCallback((path?: string) => {
+    return docsRef.current?.open(path);
+  }, []);
+
+  const close = useCallback(() => {
+    return docsRef.current?.close();
+  }, []);
+
+  const toggle = useCallback(() => {
+    return docsRef.current?.toggle();
+  }, []);
+
+  const navigate = useCallback((path: string) => {
+    return docsRef.current?.navigate(path);
+  }, []);
+
+  const setTheme = useCallback((theme: 'light' | 'dark') => {
+    return docsRef.current?.setTheme(theme);
+  }, []);
+
+  const isOpen = useCallback(() => {
+    return docsRef.current?.isOpen() || false;
+  }, []);
+
+  return {
+    open,
+    close,
+    toggle,
+    navigate,
+    setTheme,
+    isOpen,
+  };
+}
+
+/**
+ * Component that renders a trigger button for Dory Documentation
+ */
+export function DoryDocsTrigger({
+  children,
+  config,
+  className,
+  path,
+}: {
+  children: React.ReactNode;
+  config: DoryDocsConfig;
+  className?: string;
+  path?: string;
+}) {
+  const docs = useDoryDocs(config);
+
+  const handleClick = () => {
+    docs.open(path);
+  };
+
+  return (
+    <button onClick={handleClick} className={className}>
+      {children}
+    </button>
+  );
+}
+
+/**
+ * Component that initializes Dory Documentation without rendering anything
+ */
+export function DoryDocsProvider({
+  config,
+  children,
+}: {
+  config: DoryDocsConfig;
+  children: React.ReactNode;
+}) {
+  useDoryDocs(config);
+
+  return <>{children}</>;
+}
+
+// Type declarations
+declare global {
+  interface Window {
+    DoryDocs: DoryDocsAPI;
+  }
+}