@clidey/dory 0.30.0 → 0.31.0

package/src/embed/loader.ts

@@ -0,0 +1,200 @@
+/**
+ * Dory Embed Loader Script (Stage 1)
+ * This is the minimal initial script that sets up the global API
+ * and lazy-loads the widget on demand.
+ * Target size: ~3-5KB gzipped
+ */
+
+import type { DoryEmbedConfig, DoryDocsAPI } from './types';
+
+// Prevent double-loading
+if (typeof window !== 'undefined' && window.DoryDocs) {
+  console.warn('[DoryDocs] Already loaded');
+} else {
+  // Main initialization
+  (function() {
+    'use strict';
+
+  // Extract base URL from script tag
+  const currentScript = document.currentScript as HTMLScriptElement;
+  const scriptSrc = currentScript?.src || '';
+  const baseUrl = scriptSrc.replace(/\/embed\.js.*$/, '');
+
+  // Configuration storage
+  let config: DoryEmbedConfig = {
+    baseUrl,
+    position: 'right',
+    width: 500,
+    height: '100vh',
+    theme: 'inherit',
+    initialPath: '/',
+    autoInit: true,
+    showOverlay: true,
+    closeOnEscape: true,
+    closeOnOverlayClick: true,
+  };
+
+  // Widget instance (loaded lazily)
+  let widgetInstance: any = null;
+  let widgetLoading = false;
+  let widgetLoadPromise: Promise<any> | null = null;
+
+  // Load the widget script
+  async function loadWidget(): Promise<any> {
+    if (widgetInstance) return widgetInstance;
+    if (widgetLoading) return widgetLoadPromise;
+
+    widgetLoading = true;
+    widgetLoadPromise = new Promise((resolve, reject) => {
+      const script = document.createElement('script');
+      script.src = `${baseUrl}/embed-widget.js`;
+      script.async = true;
+      script.type = 'module';
+
+      script.onload = () => {
+        // Widget script exposes window.__DoryWidget__
+        if (window.__DoryWidget__) {
+          widgetInstance = new window.__DoryWidget__(config);
+          resolve(widgetInstance);
+        } else {
+          reject(new Error('[DoryDocs] Widget failed to load'));
+        }
+      };
+
+      script.onerror = () => {
+        widgetLoading = false;
+        widgetLoadPromise = null;
+        reject(new Error('[DoryDocs] Failed to load widget script'));
+      };
+
+      document.head.appendChild(script);
+    });
+
+    return widgetLoadPromise;
+  }
+
+  // Public API
+  const DoryDocs: DoryDocsAPI = {
+    // Configuration
+    init(userConfig: Partial<DoryEmbedConfig>) {
+      config = { ...config, ...userConfig };
+
+      // Auto-attach trigger if specified
+      if (config.trigger) {
+        const attachTrigger = () => {
+          const element = typeof config.trigger === 'string'
+            ? document.querySelector(config.trigger)
+            : config.trigger;
+
+          if (element) {
+            element.addEventListener('click', () => this.open());
+          } else if (typeof config.trigger === 'string') {
+            console.warn(`[DoryDocs] Trigger element not found: ${config.trigger}`);
+          }
+        };
+
+        // Try immediately, or wait for DOM ready
+        if (document.readyState === 'loading') {
+          document.addEventListener('DOMContentLoaded', attachTrigger);
+        } else {
+          attachTrigger();
+        }
+      }
+
+      return this;
+    },
+
+    // Open documentation
+    async open(path?: string) {
+      try {
+        const widget = await loadWidget();
+        await widget.open(path || config.initialPath);
+        config.onOpen?.();
+      } catch (error) {
+        console.error('[DoryDocs] Failed to open:', error);
+      }
+    },
+
+    // Close documentation
+    async close() {
+      if (!widgetInstance) return;
+      widgetInstance.close();
+      config.onClose?.();
+    },
+
+    // Toggle documentation
+    async toggle() {
+      try {
+        const widget = await loadWidget();
+        widget.toggle();
+      } catch (error) {
+        console.error('[DoryDocs] Failed to toggle:', error);
+      }
+    },
+
+    // Navigate to path
+    async navigate(path: string) {
+      try {
+        const widget = await loadWidget();
+        widget.navigate(path);
+      } catch (error) {
+        console.error('[DoryDocs] Failed to navigate:', error);
+      }
+    },
+
+    // Set theme
+    async setTheme(theme: 'light' | 'dark') {
+      try {
+        const widget = await loadWidget();
+        widget.setTheme(theme);
+      } catch (error) {
+        console.error('[DoryDocs] Failed to set theme:', error);
+      }
+    },
+
+    // Get current state
+    isOpen() {
+      return widgetInstance?.isOpen() || false;
+    },
+
+    // Destroy widget
+    async destroy() {
+      if (widgetInstance) {
+        widgetInstance.destroy();
+        widgetInstance = null;
+        widgetLoading = false;
+        widgetLoadPromise = null;
+      }
+    },
+
+    // Event listeners
+    on(event: string, handler: Function) {
+      const eventKey = `on${event.charAt(0).toUpperCase()}${event.slice(1)}` as keyof DoryEmbedConfig;
+      (config as any)[eventKey] = handler;
+      if (widgetInstance) {
+        widgetInstance.on(event, handler);
+      }
+      return this;
+    },
+  };
+
+  // Expose global API
+  window.DoryDocs = DoryDocs;
+
+  // Auto-initialize if configured
+  if (config.autoInit) {
+    // Check for URL hash deep linking
+    if (window.location.hash.startsWith('#docs=')) {
+      const path = decodeURIComponent(window.location.hash.replace('#docs=', ''));
+      DoryDocs.open(path);
+    }
+  }
+
+  // Dispatch ready event
+  window.dispatchEvent(new CustomEvent('dory:ready', { detail: { api: DoryDocs } }));
+
+  // Call onReady callback
+  config.onReady?.();
+
+  })();
+}

package/src/embed/types.ts

@@ -0,0 +1,54 @@
+/**
+ * TypeScript interfaces for Dory embedded documentation
+ */
+
+export interface DoryEmbedConfig {
+  baseUrl: string;
+  position?: 'left' | 'right' | 'bottom';
+  width?: number | string;
+  height?: string;
+  theme?: 'light' | 'dark' | 'inherit';
+  initialPath?: string;
+  trigger?: string | HTMLElement;
+  autoInit?: boolean;
+  showOverlay?: boolean;
+  closeOnEscape?: boolean;
+  closeOnOverlayClick?: boolean;
+  onOpen?: () => void;
+  onClose?: () => void;
+  onNavigate?: (path: string) => void;
+  onReady?: () => void;
+  authToken?: string;
+  getAuthToken?: () => Promise<string>;
+}
+
+export interface EmbeddedAppConfig {
+  container: HTMLElement;
+  config: DoryEmbedConfig;
+  onNavigate: (path: string) => void;
+  onClose: () => void;
+}
+
+export interface RouterContext {
+  currentPath: string;
+  navigate: (path: string) => void;
+}
+
+declare global {
+  interface Window {
+    DoryDocs: DoryDocsAPI;
+    __DoryWidget__: any;
+  }
+}
+
+export interface DoryDocsAPI {
+  init(userConfig: Partial<DoryEmbedConfig>): 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;
+}

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/main.tsx

@@ -0,0 +1,22 @@
+import { render } from 'preact'
+import '@clidey/ux/styles.css';
+import { App } from './app.tsx'
+import { withMDX } from './components/mdx-provider.tsx'
+import { loadFonts } from './utils/fonts'
+import { loadColors } from './utils/colors'
+import { Toaster } from '@clidey/ux'
+import { ThemeProvider } from '@clidey/ux'
+
+// Load fonts and colors before rendering the app
+loadFonts()
+loadColors()
+
+const AppWithMDX = withMDX(App)
+
+render(
+    <ThemeProvider storageKey="@clidey/dory/theme">
+        <Toaster />
+        <AppWithMDX />
+    </ThemeProvider>,
+    document.getElementById('app')!
+)

package/src/mdx/accordion.tsx

@@ -0,0 +1,41 @@
+import {
+  Accordion as UXAccordion,
+  AccordionItem,
+  AccordionTrigger,
+  AccordionContent
+} from '@clidey/ux'
+import { Icon } from './icon'
+
+export function AccordionGroup({ children }: { children: React.ReactNode }) {
+  return (
+    <UXAccordion type="single" collapsible className="my-6">
+      {children}
+    </UXAccordion>
+  )
+}
+
+export function Accordion({
+  title,
+  children,
+  icon,
+}: {
+  title: string
+  children: React.ReactNode
+  icon?: React.ComponentProps<typeof Icon>['icon']
+}) {
+  return (
+    <AccordionItem value={title}>
+      <AccordionTrigger className="text-left">
+        <div className="flex items-center gap-2">
+          {icon && <Icon icon={icon} className="h-5 w-5" />}
+          <span className="text-base font-semibold">{title}</span>
+        </div>
+      </AccordionTrigger>
+      <AccordionContent>
+        <div className="text-base leading-relaxed">
+          {children}
+        </div>
+      </AccordionContent>
+    </AccordionItem>
+  )
+}