juxscript 1.0.131 → 1.1.0

package/lib/components/include.ts

@@ -0,0 +1,410 @@
+
+/**
+ * Include - Include external resources (CSS, JS, images, fonts, etc.)
+ * Auto-detects resource type from URL and provides simple, fluent API
+ */
+
+type IncludeType = 'stylesheet' | 'script' | 'image' | 'font' | 'preload' | 'prefetch' | 'module' | 'json';
+type IncludeLocation = 'head' | 'body-start' | 'body-end';
+
+interface IncludeOptions {
+  as?: string;
+  crossOrigin?: 'anonymous' | 'use-credentials';
+  integrity?: string;
+  async?: boolean;
+  defer?: boolean;
+  location?: IncludeLocation;
+}
+
+export class Include {
+  private url: string;
+  private type: IncludeType;
+  private options: IncludeOptions = {};
+  private element: HTMLElement | null = null;
+  private explicitType: boolean = false;  // NEW: Track if type was explicitly set
+
+  constructor(urlOrFile: string) {
+    this.url = urlOrFile;
+    this.type = this.detectType(urlOrFile);
+  }
+
+  /* -------------------------
+   * Type Detection
+   * ------------------------- */
+
+  private detectType(url: string): IncludeType {
+    // Check for common script patterns in URLs (CDN, etc.)
+    if (url.includes('tailwindcss') ||
+      url.includes('jsdelivr.net/npm') ||
+      url.includes('unpkg.com') ||
+      url.includes('cdn.') ||
+      url.match(/\.(js|mjs)($|\?)/)) {
+      return 'script';
+    }
+
+    if (url.endsWith('.css')) return 'stylesheet';
+    if (url.endsWith('.json')) return 'json';
+    if (url.match(/\.(png|jpg|jpeg|gif|svg|webp)$/i)) return 'image';
+    if (url.match(/\.(woff|woff2|ttf|otf|eot)$/i)) return 'font';
+
+    // Default to script for extensionless URLs from CDN domains
+    if (!url.includes('.') || url.match(/^https?:\/\/cdn/)) {
+      return 'script';
+    }
+
+    return 'preload';
+  }
+
+  /* -------------------------
+   * Fluent Type Setters
+   * ------------------------- */
+
+  /**
+   * Force treat as CSS stylesheet
+   * Use when URL doesn't have .css extension
+   */
+  withCss(): this {
+    this.type = 'stylesheet';
+    this.explicitType = true;  // Mark as explicit
+    return this;
+  }
+
+  /**
+   * Force treat as JavaScript
+   * Use when URL doesn't have .js extension (CDN scripts, etc.)
+   * 
+   * @example
+   * jux.include('https://cdn.tailwindcss.com').withJs().render();
+   * jux.include('https://unpkg.com/alpine').withJs({ defer: true }).render();
+   */
+  withJs(options?: { async?: boolean; defer?: boolean }): this {
+    this.type = 'script';
+    this.explicitType = true;  // Mark as explicit
+    if (options?.async) this.options.async = true;
+    if (options?.defer) this.options.defer = true;
+    return this;
+  }
+
+  /**
+   * Force treat as ES module
+   * Use for module scripts
+   */
+  withModule(): this {
+    this.type = 'module';
+    this.explicitType = true;  // Mark as explicit
+    return this;
+  }
+
+  withImage(): this {
+    this.type = 'image';
+    this.explicitType = true;
+    return this;
+  }
+
+  withFont(): this {
+    this.type = 'font';
+    this.explicitType = true;
+    return this;
+  }
+
+  withPreload(as?: string): this {
+    this.type = 'preload';
+    this.explicitType = true;
+    if (as) this.options.as = as;
+    return this;
+  }
+
+  withPrefetch(): this {
+    this.type = 'prefetch';
+    this.explicitType = true;
+    return this;
+  }
+
+  withJson(): this {
+    this.type = 'json';
+    this.explicitType = true;
+    return this;
+  }
+
+  /* -------------------------
+   * Convenience aliases for common patterns
+   * ------------------------- */
+
+  /**
+   * Shorthand for .withJs()
+   * @example jux.include(url).asScript()
+   */
+  asScript(options?: { async?: boolean; defer?: boolean }): this {
+    return this.withJs(options);
+  }
+
+  /**
+   * Shorthand for .withCss()
+   * @example jux.include(url).asStylesheet()
+   */
+  asStylesheet(): this {
+    return this.withCss();
+  }
+
+  /* -------------------------
+   * JSON Fetching
+   * ------------------------- */
+
+  /**
+   * Fetch and parse JSON file
+   * Returns a Promise that resolves to the parsed JSON data
+   * 
+   * Usage:
+   *   const config = await jux.include('config.json').asJson();
+   *   const data = await jux.include('/api/data').asJson();
+   */
+  async asJson<T = any>(): Promise<T> {
+    try {
+      const response = await fetch(this.url);
+
+      if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status}`);
+      }
+
+      const data = await response.json();
+      console.log(`✓ JSON loaded: ${this.url}`);
+      return data;
+    } catch (error: any) {
+      throw error;
+    }
+  }
+
+  /**
+   * Fetch JSON and execute callback with data
+   * 
+   * Usage:
+   *   jux.include('config.json').onJson(data => {
+   *     console.log('Config:', data);
+   *   });
+   */
+  onJson<T = any>(callback: (data: T) => void): this {
+    this.asJson<T>().then(callback).catch(error => {
+      console.error('Failed to load JSON:', error);
+    });
+    return this;
+  }
+
+  /* -------------------------
+   * Options
+   * ------------------------- */
+
+  with(options: IncludeOptions): this {
+    this.options = { ...this.options, ...options };
+    return this;
+  }
+
+  inHead(): this {
+    this.options.location = 'head';
+    return this;
+  }
+
+  inBody(): this {
+    this.options.location = 'body-end';
+    return this;
+  }
+
+  async(): this {
+    this.options.async = true;
+    return this;
+  }
+
+  defer(): this {
+    this.options.defer = true;
+    return this;
+  }
+
+  crossOrigin(value: 'anonymous' | 'use-credentials' = 'anonymous'): this {
+    this.options.crossOrigin = value;
+    return this;
+  }
+
+  integrity(hash: string): this {
+    this.options.integrity = hash;
+    return this;
+  }
+
+  /* -------------------------
+   * Render
+   * ------------------------- */
+
+  render(): this {
+    if (typeof document === 'undefined') return this;
+
+    // Don't render JSON type (it's fetched via asJson() instead)
+    if (this.type === 'json') {
+      console.warn('Include: JSON files should be loaded with .asJson() instead of .render()');
+      return this;
+    }
+
+    try {
+      this.remove();
+
+      let element: HTMLElement;
+
+      switch (this.type) {
+        case 'stylesheet':
+          element = this.createStylesheet();
+          break;
+        case 'script':
+        case 'module':
+          element = this.createScript();
+          break;
+        case 'image':
+        case 'font':
+        case 'preload':
+        case 'prefetch':
+          element = this.createLink();
+          break;
+        default:
+          throw new Error(`Unknown include type: ${this.type}`);
+      }
+
+      const container = this.getContainer();
+      const location = this.options.location || 'head';
+
+      if (location === 'body-end') {
+        container.appendChild(element);
+      } else {
+        container.insertBefore(element, container.firstChild);
+      }
+
+      this.element = element;
+
+      // Log with type indicator
+      const typeIndicator = this.explicitType ? '(explicit)' : '(auto-detected)';
+      console.log(`✓ Include loaded as ${this.type} ${typeIndicator}: ${this.url}`);
+    } catch (error: any) {
+      throw error;
+    }
+
+    return this;
+  }
+
+  /* -------------------------
+   * Element Creation
+   * ------------------------- */
+
+  private createStylesheet(): HTMLLinkElement {
+    const link = document.createElement('link');
+    link.rel = 'stylesheet';
+    link.href = this.url;
+
+    if (this.options.crossOrigin) link.crossOrigin = this.options.crossOrigin;
+    if (this.options.integrity) link.integrity = this.options.integrity;
+
+    link.onload = () => console.log(`✓ Stylesheet loaded: ${this.url}`);
+    link.onerror = () => this.handleError('stylesheet');
+
+    return link;
+  }
+
+  private createScript(): HTMLScriptElement {
+    const script = document.createElement('script');
+    script.src = this.url;
+
+    if (this.type === 'module') script.type = 'module';
+    if (this.options.async) script.async = true;
+    if (this.options.defer) script.defer = true;
+    if (this.options.crossOrigin) script.crossOrigin = this.options.crossOrigin;
+    if (this.options.integrity) script.integrity = this.options.integrity;
+
+    script.onload = () => console.log(`✓ Script loaded: ${this.url}`);
+    script.onerror = () => this.handleError('script');
+
+    return script;
+  }
+
+  private createLink(): HTMLLinkElement {
+    const link = document.createElement('link');
+
+    // Set rel based on type
+    if (this.type === 'prefetch') {
+      link.rel = 'prefetch';
+    } else {
+      link.rel = 'preload';
+    }
+
+    link.href = this.url;
+
+    // Set 'as' attribute
+    if (this.type === 'image') {
+      link.as = 'image';
+    } else if (this.type === 'font') {
+      link.as = 'font';
+      link.crossOrigin = this.options.crossOrigin || 'anonymous';
+    } else if (this.options.as) {
+      link.as = this.options.as;
+    }
+
+    if (this.options.crossOrigin && this.type !== 'font') {
+      link.crossOrigin = this.options.crossOrigin;
+    }
+    if (this.options.integrity) {
+      link.integrity = this.options.integrity;
+    }
+
+    return link;
+  }
+
+  /* -------------------------
+   * Helpers
+   * ------------------------- */
+
+  private getContainer(): HTMLElement {
+    const location = this.options.location || 'head';
+    return location === 'head' ? document.head : document.body;
+  }
+
+  private handleError(type: string): void {
+    const error = new Error(`Failed to load ${type}: ${this.url}`);
+    throw error;
+  }
+
+
+  remove(): this {
+    if (this.element?.parentNode) {
+      this.element.parentNode.removeChild(this.element);
+      this.element = null;
+    }
+    return this;
+  }
+}
+
+/**
+ * Factory function - auto-detects type and renders immediately
+ * 
+ * Usage:
+ *   // Auto-detect (works for most cases)
+ *   jux.include('styles.css');
+ *   jux.include('script.js').async();
+ *   
+ *   // Explicit type (for extensionless URLs)
+ *   jux.include('https://cdn.tailwindcss.com').withJs();
+ *   jux.include('https://cdn.tailwindcss.com').asScript();
+ *   jux.include('https://unpkg.com/htmx.org').withJs({ defer: true });
+ *   
+ *   // CDN with parameters
+ *   jux.include('https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4').withJs();
+ *   
+ *   // Module
+ *   jux.include('app.mjs').withModule();
+ *   
+ *   // For JSON:
+ *   const data = await jux.include('config.json').asJson();
+ *   jux.include('data.json').onJson(data => console.log(data));
+ */
+export function include(urlOrFile: string): Include {
+  const imp = new Include(urlOrFile);
+
+  // Don't auto-render JSON files
+  if (imp['type'] !== 'json') {
+    imp.render();
+  }
+
+  return imp;
+}