@anymux/ui-kit 0.1.0

package/src/file-browser/registry/ViewerRegistry.ts

@@ -0,0 +1,551 @@
+import React from 'react';
+import type {
+  FileViewerPlugin,
+  FileMatchContext,
+  ResolvedViewer,
+} from './types';
+
+// Re-export types from types.ts for convenience
+export type { FileViewerPlugin, FileMatchContext, ResolvedViewer, ToolbarAction, KeyboardShortcut } from './types';
+
+// ---- Legacy interfaces (kept for backward compatibility) ----
+
+export interface ViewerConfig {
+  id: string;
+  name: string;
+  description?: string;
+  extensions: string[];
+  component: React.ComponentType<ViewerProps>;
+  priority?: number;
+  canEdit?: boolean;
+  isDefault?: boolean;
+}
+
+export interface ViewerProps {
+  file: {
+    path: string;
+    name: string;
+    content?: string | ArrayBuffer;
+    size?: number;
+    mimeType?: string;
+  };
+  onClose?: () => void;
+  onSave?: (content: string | ArrayBuffer) => Promise<void>;
+  className?: string;
+  readOnly?: boolean;
+  /** Callback for viewer to register toolbar controls rendered in parent toolbar */
+  onToolbarExtras?: (extras: React.ReactNode) => void;
+
+  // ---- NEW: Edit lifecycle ----
+
+  /**
+   * Called by the plugin when the content becomes dirty (modified).
+   * The host uses this to show unsaved-changes indicators and
+   * to prompt before closing.
+   */
+  onDirtyChange?: (isDirty: boolean) => void;
+
+  /**
+   * Whether to render in compact/preview mode (inside the preview pane)
+   * vs full mode (inside the main viewer area).
+   * Plugins can adjust their layout based on this.
+   */
+  mode?: 'preview' | 'full';
+
+  /**
+   * Content fetcher for streaming/on-demand loading.
+   * Plugins that handle large files (PDF, video) can use this
+   * instead of receiving the full content upfront.
+   */
+  fetchContent?: () => Promise<string | ArrayBuffer>;
+
+  /**
+   * URL for the file if it can be accessed directly (e.g., S3 presigned URL).
+   * Useful for media players that need a URL, not a buffer.
+   */
+  contentUrl?: string;
+}
+
+// ---- Match type bonus constants ----
+
+const MATCH_BONUS_EXTENSION = 80;
+const MATCH_BONUS_MIME = 70;
+const MATCH_BONUS_PATTERN = 60;
+
+// ---- Adapter: wrap legacy ViewerConfig into FileViewerPlugin ----
+
+export function viewerConfigToPlugin(config: ViewerConfig): FileViewerPlugin {
+  const plugin: FileViewerPlugin = {
+    id: config.id,
+    name: config.name,
+    extensions: config.extensions.map(ext => ext.toLowerCase().replace(/^\./, '')),
+    capabilities: {
+      canPreview: true,
+      canFullscreen: true,
+    },
+    priority: config.priority ?? 0,
+    component: config.component,
+  };
+  if (config.description !== undefined) plugin.description = config.description;
+  if (config.canEdit !== undefined) plugin.capabilities.canEdit = config.canEdit;
+  if (config.isDefault !== undefined) plugin.isDefault = config.isDefault;
+  return plugin;
+}
+
+// ---- Adapter: convert FileViewerPlugin back to ViewerConfig (for backward-compat getters) ----
+
+function pluginToViewerConfig(plugin: FileViewerPlugin): ViewerConfig {
+  const config: ViewerConfig = {
+    id: plugin.id,
+    name: plugin.name,
+    extensions: plugin.extensions ?? [],
+    component: resolveComponent(plugin),
+    priority: plugin.priority ?? 0,
+  };
+  if (plugin.description !== undefined) config.description = plugin.description;
+  if (plugin.capabilities.canEdit !== undefined) config.canEdit = plugin.capabilities.canEdit;
+  if (plugin.isDefault !== undefined) config.isDefault = plugin.isDefault;
+  return config;
+}
+
+// ---- Lazy component cache ----
+
+const lazyCache = new Map<string, React.LazyExoticComponent<React.ComponentType<ViewerProps>>>();
+
+function resolveComponent(plugin: FileViewerPlugin): React.ComponentType<ViewerProps> {
+  if (plugin.component) {
+    return plugin.component;
+  }
+  if (plugin.load) {
+    if (!lazyCache.has(plugin.id)) {
+      lazyCache.set(plugin.id, React.lazy(plugin.load));
+    }
+    return lazyCache.get(plugin.id)!;
+  }
+  throw new Error(`Plugin "${plugin.id}" has no component or loader`);
+}
+
+// ---- Simple glob matching for filePatterns ----
+
+function matchesGlob(filename: string, pattern: string): boolean {
+  // Convert simple glob pattern to regex
+  // Supports: * (any chars), ? (single char), and literal strings
+  const escaped = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*/g, '.*')
+    .replace(/\?/g, '.');
+  const regex = new RegExp(`^${escaped}$`, 'i');
+  return regex.test(filename);
+}
+
+// ---- ViewerRegistry class ----
+
+export class ViewerRegistry {
+  // ---- Legacy storage (kept for backward compat) ----
+  private viewers = new Map<string, ViewerConfig>();
+  private extensionMap = new Map<string, ViewerConfig[]>();
+
+  // ---- New plugin storage ----
+  private plugins = new Map<string, FileViewerPlugin>();
+  private extensionIndex = new Map<string, FileViewerPlugin[]>();
+  private mimeTypeIndex = new Map<string, FileViewerPlugin[]>();
+  private patternPlugins: FileViewerPlugin[] = [];
+
+  // ==============================
+  // NEW: Plugin API
+  // ==============================
+
+  /**
+   * Register a plugin. Replaces any existing plugin with the same ID.
+   */
+  registerPlugin(plugin: FileViewerPlugin): void {
+    if (!plugin.component && !plugin.load) {
+      throw new Error(`Plugin "${plugin.id}" must provide either component or load()`);
+    }
+
+    // Remove existing plugin with same ID (if any)
+    this.unregisterPlugin(plugin.id);
+
+    this.plugins.set(plugin.id, plugin);
+    this.rebuildIndexes();
+
+    // Also register in legacy storage for backward compat
+    this.syncPluginToLegacy(plugin);
+  }
+
+  /**
+   * Unregister a plugin by ID.
+   */
+  unregisterPlugin(pluginId: string): void {
+    if (!this.plugins.has(pluginId)) return;
+
+    this.plugins.delete(pluginId);
+    this.rebuildIndexes();
+
+    // Also remove from legacy maps
+    this.removeLegacy(pluginId);
+
+    // Clean lazy cache
+    lazyCache.delete(pluginId);
+  }
+
+  /**
+   * Find the best viewer for a given file.
+   *
+   * Matching order with scoring:
+   * 1. Extension match (bonus: 80)
+   * 2. MIME type match (bonus: 70)
+   * 3. Filename pattern match (bonus: 60)
+   * 4. canHandle() callback (bonus: canHandle return value 0-100)
+   * 5. Default plugin (isDefault: true, bonus: 0)
+   *
+   * Final score = matchTypeBonus + plugin.priority + canHandle score (if applicable)
+   */
+  resolveViewer(
+    file: FileMatchContext,
+    options?: { preferEditable?: boolean }
+  ): ResolvedViewer | null {
+    const candidates = this.findCandidates(file);
+
+    if (options?.preferEditable) {
+      const editable = candidates.filter(c => c.plugin.capabilities.canEdit);
+      if (editable.length > 0) return editable[0]!;
+    }
+
+    return candidates[0] ?? null;
+  }
+
+  /**
+   * Find ALL viewers that can handle a file, sorted by score (descending).
+   * Used for "Open with..." menu.
+   */
+  resolveAllViewers(file: FileMatchContext): ResolvedViewer[] {
+    return this.findCandidates(file);
+  }
+
+  /**
+   * Get a plugin by ID.
+   */
+  getPluginById(pluginId: string): FileViewerPlugin | null {
+    return this.plugins.get(pluginId) ?? null;
+  }
+
+  /**
+   * Get all registered plugins.
+   */
+  getAllPlugins(): FileViewerPlugin[] {
+    return Array.from(this.plugins.values()).sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  /**
+   * Build a FileMatchContext from a filename (convenience helper).
+   */
+  buildFileMatchContext(
+    filename: string,
+    opts?: { path?: string; mimeType?: string; size?: number }
+  ): FileMatchContext {
+    const ctx: FileMatchContext = {
+      name: filename,
+      path: opts?.path ?? filename,
+      extension: this.extractExtension(filename),
+    };
+    if (opts?.mimeType !== undefined) ctx.mimeType = opts.mimeType;
+    if (opts?.size !== undefined) ctx.size = opts.size;
+    return ctx;
+  }
+
+  // ==============================
+  // LEGACY API (backward compat)
+  // ==============================
+
+  registerViewer(config: ViewerConfig): void {
+    // Register via plugin API, which also syncs to legacy
+    this.registerPlugin(viewerConfigToPlugin(config));
+  }
+
+  unregisterViewer(viewerId: string): void {
+    this.unregisterPlugin(viewerId);
+  }
+
+  getViewer(filename: string, preferEditable = false): ViewerConfig | null {
+    const extension = this.extractExtension(filename);
+    const viewers = this.extensionMap.get(extension) || [];
+
+    if (viewers.length === 0) {
+      return this.getDefaultViewer();
+    }
+
+    let candidates = viewers;
+    if (preferEditable) {
+      const editableViewers = viewers.filter(v => v.canEdit);
+      if (editableViewers.length > 0) {
+        candidates = editableViewers;
+      }
+    }
+
+    return candidates[0] || null;
+  }
+
+  getViewers(filename: string): ViewerConfig[] {
+    const extension = this.extractExtension(filename);
+    return [...(this.extensionMap.get(extension) || [])];
+  }
+
+  canHandle(filename: string): boolean {
+    const extension = this.extractExtension(filename);
+    if (this.extensionMap.has(extension)) return true;
+
+    // Also check plugin pattern/canHandle matching
+    const ctx = this.buildFileMatchContext(filename);
+    for (const plugin of this.patternPlugins) {
+      if (plugin.filePatterns) {
+        for (const pattern of plugin.filePatterns) {
+          if (matchesGlob(filename, pattern)) return true;
+        }
+      }
+      if (plugin.canHandle) {
+        if (plugin.canHandle(ctx) > 0) return true;
+      }
+    }
+
+    return false;
+  }
+
+  getAllViewers(): ViewerConfig[] {
+    return Array.from(this.viewers.values()).sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  getViewerById(id: string): ViewerConfig | null {
+    return this.viewers.get(id) || null;
+  }
+
+  getFileCategory(filename: string): string {
+    const extension = this.extractExtension(filename);
+
+    const imageExts = ['jpg', 'jpeg', 'png', 'gif', 'svg', 'webp', 'bmp', 'ico'];
+    const videoExts = ['mp4', 'avi', 'mov', 'wmv', 'flv', 'webm', 'mkv'];
+    const audioExts = ['mp3', 'wav', 'flac', 'aac', 'ogg', 'wma', 'm4a'];
+    const codeExts = ['js', 'jsx', 'ts', 'tsx', 'py', 'java', 'cpp', 'c', 'cs', 'php', 'rb', 'go', 'rs', 'swift', 'kt', 'html', 'css', 'scss'];
+    const textExts = ['txt', 'md', 'mdx', 'rst', 'rtf'];
+    const documentExts = ['pdf', 'doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx'];
+    const archiveExts = ['zip', 'rar', '7z', 'tar', 'gz', 'bz2'];
+
+    if (imageExts.includes(extension)) return 'image';
+    if (videoExts.includes(extension)) return 'video';
+    if (audioExts.includes(extension)) return 'audio';
+    if (codeExts.includes(extension)) return 'code';
+    if (textExts.includes(extension)) return 'text';
+    if (documentExts.includes(extension)) return 'document';
+    if (archiveExts.includes(extension)) return 'archive';
+
+    return 'file';
+  }
+
+  // ==============================
+  // INTERNAL
+  // ==============================
+
+  private extractExtension(filename: string): string {
+    const lastDot = filename.lastIndexOf('.');
+    if (lastDot === -1 || lastDot === filename.length - 1) {
+      return '';
+    }
+    return filename.slice(lastDot + 1).toLowerCase();
+  }
+
+  private getDefaultViewer(): ViewerConfig | null {
+    for (const viewer of this.viewers.values()) {
+      if (viewer.isDefault) {
+        return viewer;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Find all candidate viewers for a file, scored and sorted descending.
+   */
+  private findCandidates(file: FileMatchContext): ResolvedViewer[] {
+    const scored: Array<{ plugin: FileViewerPlugin; score: number }> = [];
+
+    // 1. Extension match
+    if (file.extension) {
+      const byExt = this.extensionIndex.get(file.extension) || [];
+      for (const plugin of byExt) {
+        let score = MATCH_BONUS_EXTENSION + (plugin.priority ?? 0);
+        if (plugin.canHandle) {
+          const canHandleScore = plugin.canHandle(file);
+          if (canHandleScore <= 0) continue; // canHandle rejected
+          score += canHandleScore;
+        }
+        scored.push({ plugin, score });
+      }
+    }
+
+    // 2. MIME type match
+    if (file.mimeType) {
+      const byMime = this.mimeTypeIndex.get(file.mimeType) || [];
+      for (const plugin of byMime) {
+        // Skip if already scored by extension
+        if (scored.some(s => s.plugin.id === plugin.id)) continue;
+
+        let score = MATCH_BONUS_MIME + (plugin.priority ?? 0);
+        if (plugin.canHandle) {
+          const canHandleScore = plugin.canHandle(file);
+          if (canHandleScore <= 0) continue;
+          score += canHandleScore;
+        }
+        scored.push({ plugin, score });
+      }
+    }
+
+    // 3. Pattern match + canHandle-only plugins
+    for (const plugin of this.patternPlugins) {
+      // Skip if already scored
+      if (scored.some(s => s.plugin.id === plugin.id)) continue;
+
+      let matched = false;
+      let matchBonus = 0;
+
+      // Check filePatterns
+      if (plugin.filePatterns) {
+        for (const pattern of plugin.filePatterns) {
+          if (matchesGlob(file.name, pattern)) {
+            matched = true;
+            matchBonus = MATCH_BONUS_PATTERN;
+            break;
+          }
+        }
+      }
+
+      // Check canHandle (for plugins with only canHandle, or in addition to pattern match)
+      if (plugin.canHandle) {
+        const canHandleScore = plugin.canHandle(file);
+        if (canHandleScore > 0) {
+          if (!matched) {
+            // canHandle-only match: score IS the canHandle return value
+            matched = true;
+            matchBonus = canHandleScore;
+          } else {
+            // Pattern + canHandle: add canHandle score
+            matchBonus += canHandleScore;
+          }
+        } else if (!matched) {
+          continue;
+        }
+      }
+
+      if (matched) {
+        scored.push({ plugin, score: matchBonus + (plugin.priority ?? 0) });
+      }
+    }
+
+    // 4. If nothing matched, try default plugin
+    if (scored.length === 0) {
+      for (const plugin of this.plugins.values()) {
+        if (plugin.isDefault) {
+          scored.push({ plugin, score: 0 });
+          break;
+        }
+      }
+    }
+
+    // Sort by score descending, break ties by priority descending
+    scored.sort((a, b) => {
+      if (b.score !== a.score) return b.score - a.score;
+      return (b.plugin.priority ?? 0) - (a.plugin.priority ?? 0);
+    });
+
+    // Resolve to ResolvedViewer
+    return scored.map(({ plugin, score }) => ({
+      plugin,
+      Component: resolveComponent(plugin),
+      confidence: score,
+    }));
+  }
+
+  /**
+   * Rebuild plugin indexes from the plugin map.
+   */
+  private rebuildIndexes(): void {
+    this.extensionIndex.clear();
+    this.mimeTypeIndex.clear();
+    this.patternPlugins = [];
+
+    for (const plugin of this.plugins.values()) {
+      // Index by extension
+      if (plugin.extensions) {
+        for (const ext of plugin.extensions) {
+          const normalized = ext.toLowerCase().replace(/^\./, '');
+          const list = this.extensionIndex.get(normalized) || [];
+          list.push(plugin);
+          this.extensionIndex.set(normalized, list);
+        }
+      }
+
+      // Index by MIME type
+      if (plugin.mimeTypes) {
+        for (const mime of plugin.mimeTypes) {
+          const list = this.mimeTypeIndex.get(mime) || [];
+          list.push(plugin);
+          this.mimeTypeIndex.set(mime, list);
+        }
+      }
+
+      // Track plugins with patterns or canHandle
+      if (plugin.filePatterns || plugin.canHandle) {
+        this.patternPlugins.push(plugin);
+      }
+    }
+  }
+
+  /**
+   * Sync a plugin into the legacy viewers/extensionMap storage.
+   */
+  private syncPluginToLegacy(plugin: FileViewerPlugin): void {
+    const config = pluginToViewerConfig(plugin);
+    this.viewers.set(config.id, config);
+
+    if (config.extensions) {
+      config.extensions.forEach(ext => {
+        const normalizedExt = ext.toLowerCase().replace(/^\./, '');
+        const existingViewers = this.extensionMap.get(normalizedExt) || [];
+
+        const insertIndex = existingViewers.findIndex(
+          v => (v.priority || 0) < (config.priority || 0)
+        );
+        if (insertIndex === -1) {
+          existingViewers.push(config);
+        } else {
+          existingViewers.splice(insertIndex, 0, config);
+        }
+
+        this.extensionMap.set(normalizedExt, existingViewers);
+      });
+    }
+  }
+
+  /**
+   * Remove a plugin from legacy storage.
+   */
+  private removeLegacy(pluginId: string): void {
+    const config = this.viewers.get(pluginId);
+    if (!config) return;
+
+    this.viewers.delete(pluginId);
+
+    config.extensions.forEach(ext => {
+      const normalizedExt = ext.toLowerCase().replace(/^\./, '');
+      const viewers = this.extensionMap.get(normalizedExt) || [];
+      const filtered = viewers.filter(v => v.id !== pluginId);
+
+      if (filtered.length === 0) {
+        this.extensionMap.delete(normalizedExt);
+      } else {
+        this.extensionMap.set(normalizedExt, filtered);
+      }
+    });
+  }
+}
+
+export const globalViewerRegistry = new ViewerRegistry();

package/src/file-browser/registry/types.ts

@@ -0,0 +1,144 @@
+import React from 'react';
+import type { ViewerProps } from './ViewerRegistry';
+
+/**
+ * Plugin interface for file viewers.
+ * Extends the simple ViewerConfig with richer matching, lazy loading, and toolbar support.
+ */
+export interface FileViewerPlugin {
+  /** Unique plugin ID, e.g., 'pdf-viewer', 'monaco-editor' */
+  id: string;
+
+  /** Human-readable name shown in "Open with..." menu */
+  name: string;
+
+  /** Optional description for UI tooltips */
+  description?: string;
+
+  /** Plugin capabilities */
+  capabilities: {
+    /** Can this plugin edit files (enables save flow)? */
+    canEdit?: boolean;
+    /** Can this plugin render in the inline preview pane (smaller viewport)? */
+    canPreview?: boolean;
+    /** Can this plugin render full-screen (the main viewer mode)? */
+    canFullscreen?: boolean;
+  };
+
+  // ---- MATCHING ----
+
+  /** File extensions this plugin handles (without dots), e.g., ['pdf', 'epub'] */
+  extensions?: string[];
+
+  /** MIME types this plugin handles, e.g., ['application/pdf'] */
+  mimeTypes?: string[];
+
+  /** Glob patterns for filenames, e.g., ['Dockerfile', 'Makefile', '.env*'] */
+  filePatterns?: string[];
+
+  /**
+   * Advanced match function for content-sniffing or complex logic.
+   * Called only if extension/MIME/pattern matching passes or if no
+   * static matchers are defined.
+   * Return a confidence score 0-100 (0 = cannot handle, 100 = perfect match).
+   */
+  canHandle?: (file: FileMatchContext) => number;
+
+  // ---- PRIORITY ----
+
+  /**
+   * Priority (higher = preferred). Default: 0.
+   * Built-in viewers use 10-20. Third-party plugins should use 50+
+   * to override built-in viewers, or negative to serve as fallbacks.
+   */
+  priority?: number;
+
+  // ---- COMPONENT LOADING ----
+
+  /**
+   * The viewer React component. Can be a concrete component or a lazy loader.
+   * When undefined, `load()` must be provided.
+   */
+  component?: React.ComponentType<ViewerProps>;
+
+  /**
+   * Dynamic loader that returns the viewer component.
+   * Used for code-splitting. The registry wraps this in React.lazy().
+   */
+  load?: () => Promise<{ default: React.ComponentType<ViewerProps> }>;
+
+  // ---- DEFAULT ----
+
+  /** If true, this plugin is used as the fallback for unrecognized file types */
+  isDefault?: boolean;
+
+  // ---- TOOLBAR EXTENSION ----
+
+  /**
+   * Declarative toolbar actions rendered by the ViewerHost.
+   * For dynamic toolbar items, plugins should use the `onToolbarExtras`
+   * callback on ViewerProps (already supported).
+   */
+  toolbarActions?: ToolbarAction[];
+
+  /**
+   * Keyboard shortcuts the plugin handles.
+   * The ViewerHost binds these when the plugin is active.
+   */
+  keyboardShortcuts?: KeyboardShortcut[];
+}
+
+/** Context passed to canHandle() and resolveViewer() for file matching */
+export interface FileMatchContext {
+  /** Filename including extension */
+  name: string;
+  /** Full path */
+  path: string;
+  /** File extension without dot, lowercase */
+  extension: string;
+  /** MIME type if known */
+  mimeType?: string;
+  /** File size in bytes */
+  size?: number;
+  /**
+   * First bytes of content (for magic-number sniffing).
+   * Only available if the registry is configured to pre-read headers.
+   * Typically 512 bytes.
+   */
+  headerBytes?: ArrayBuffer;
+}
+
+/** Declarative toolbar action for ViewerHost */
+export interface ToolbarAction {
+  id: string;
+  label: string;
+  icon?: React.ComponentType<{ className?: string }>;
+  /** Called when the action is triggered */
+  onClick: () => void;
+  /** Whether the action is currently enabled */
+  enabled?: boolean | (() => boolean);
+  /** Keyboard shortcut label for tooltip, e.g., "Ctrl+S" */
+  shortcutLabel?: string;
+  /** Position: 'left' | 'right'. Default: 'right' */
+  position?: 'left' | 'right';
+}
+
+/** Keyboard shortcut binding for ViewerHost */
+export interface KeyboardShortcut {
+  /** Key combination, e.g., 'ctrl+s', 'escape', 'ctrl+shift+p' */
+  key: string;
+  /** Handler */
+  handler: () => void;
+  /** Only active when the viewer has focus? Default: true */
+  requireFocus?: boolean;
+}
+
+/** Result of resolving a viewer for a file */
+export interface ResolvedViewer {
+  /** The matched plugin */
+  plugin: FileViewerPlugin;
+  /** The React component to render (resolved from component or load via React.lazy) */
+  Component: React.ComponentType<ViewerProps>;
+  /** Match confidence score. Extension match = 80, MIME = 70, pattern = 60, canHandle = dynamic */
+  confidence: number;
+}