@fgv/ts-res-ui-components 5.0.0-10

package/src/utils/zipLoader/browserZipLoader.ts

@@ -0,0 +1,319 @@
+import { Result, succeed, fail } from '@fgv/ts-utils';
+import {
+  IZipLoader,
+  ZipLoadOptions,
+  ZipLoadResult,
+  ZipProgressCallback,
+  ZipFileTree,
+  ZipFileItem,
+  ZipLoadingStage
+} from './types';
+import { parseManifest, parseConfiguration, zipTreeToFiles, zipTreeToDirectory, isZipFile } from './zipUtils';
+import { processImportedFiles, processImportedDirectory } from '../tsResIntegration';
+import { ProcessedResources } from '../../types';
+
+// Dynamic import for JSZip to support both Node.js and browser environments
+let JSZip: any = null;
+
+/**
+ * Get JSZip instance (assumes JSZip is available)
+ */
+function getJSZip(): any {
+  if (JSZip) return JSZip;
+
+  // Check if JSZip is globally available
+  if (typeof window !== 'undefined' && (window as any).JSZip) {
+    JSZip = (window as any).JSZip;
+    return JSZip;
+  }
+
+  // Try to get JSZip from require/import (will work in bundled environments)
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    JSZip = require('jszip');
+    return JSZip;
+  } catch (error) {
+    throw new Error('JSZip is not available. Please install jszip as a dependency: npm install jszip');
+  }
+}
+
+/**
+ * Browser-based ZIP loader implementation
+ */
+export class BrowserZipLoader implements IZipLoader {
+  /**
+   * Load ZIP from File object
+   */
+  async loadFromFile(
+    file: File,
+    options: ZipLoadOptions = {},
+    onProgress?: ZipProgressCallback
+  ): Promise<Result<ZipLoadResult>> {
+    onProgress?.('reading-file', 0, `Reading file: ${file.name}`);
+
+    if (!isZipFile(file.name)) {
+      return fail(`File ${file.name} is not a ZIP file`);
+    }
+
+    const buffer = await file.arrayBuffer().catch((error) => {
+      throw new Error(`Failed to read file: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    onProgress?.('reading-file', 100, 'File read complete');
+
+    return this.loadFromBuffer(buffer, options, onProgress);
+  }
+
+  /**
+   * Load ZIP from ArrayBuffer
+   */
+  async loadFromBuffer(
+    buffer: ArrayBuffer,
+    options: ZipLoadOptions = {},
+    onProgress?: ZipProgressCallback
+  ): Promise<Result<ZipLoadResult>> {
+    onProgress?.('parsing-zip', 0, 'Parsing ZIP archive');
+
+    const JSZipClass = getJSZip();
+    const zip = new JSZipClass();
+    const loadedZip = await zip.loadAsync(buffer).catch((error: any) => {
+      throw new Error(`Failed to parse ZIP: ${error instanceof Error ? error.message : String(error)}`);
+    });
+
+    onProgress?.('parsing-zip', 100, 'ZIP archive parsed');
+
+    // Build file tree
+    const fileTree = await this.buildFileTree(loadedZip, onProgress);
+
+    // Load manifest
+    onProgress?.('loading-manifest', 0, 'Loading manifest');
+    const manifest = await this.loadManifest(loadedZip);
+    onProgress?.('loading-manifest', 100, 'Manifest loaded');
+
+    // Load configuration
+    onProgress?.('loading-config', 0, 'Loading configuration');
+    const config = await this.loadConfiguration(loadedZip, options);
+    onProgress?.('loading-config', 100, 'Configuration loaded');
+
+    // Extract files and directory structure
+    onProgress?.('extracting-files', 0, 'Extracting files');
+    const files = zipTreeToFiles(fileTree);
+    const directory = zipTreeToDirectory(fileTree);
+    onProgress?.('extracting-files', 100, `Extracted ${files.length} files`);
+
+    // Process resources if requested
+    let processedResources: ProcessedResources | null = null;
+    if (options.autoProcessResources) {
+      onProgress?.('processing-resources', 0, 'Processing resources');
+
+      const configToUse = options.overrideConfig || config;
+
+      if (directory) {
+        const processResult = await processImportedDirectory(directory, configToUse || undefined);
+        if (processResult.isSuccess()) {
+          processedResources = processResult.value;
+        } else {
+          throw new Error(`Failed to process resources from directory: ${processResult.message}`);
+        }
+      } else if (files.length > 0) {
+        const processResult = await processImportedFiles(files, configToUse || undefined);
+        if (processResult.isSuccess()) {
+          processedResources = processResult.value;
+        } else {
+          throw new Error(`Failed to process resources from files: ${processResult.message}`);
+        }
+      }
+
+      onProgress?.('processing-resources', 100, 'Resources processed');
+    }
+
+    onProgress?.('complete', 100, 'ZIP loading complete');
+
+    return succeed({
+      manifest,
+      config: options.overrideConfig || config,
+      files,
+      directory,
+      processedResources
+    });
+  }
+
+  /**
+   * Load ZIP from URL
+   */
+  async loadFromUrl(
+    url: string,
+    options: ZipLoadOptions = {},
+    onProgress?: ZipProgressCallback
+  ): Promise<Result<ZipLoadResult>> {
+    onProgress?.('reading-file', 0, `Fetching from URL: ${url}`);
+
+    const response = await fetch(url).catch((error) => {
+      throw new Error(
+        `Failed to fetch ZIP from URL: ${error instanceof Error ? error.message : String(error)}`
+      );
+    });
+
+    if (!response.ok) {
+      return fail(`Failed to fetch ZIP from URL: ${response.status} ${response.statusText}`);
+    }
+
+    const buffer = await response.arrayBuffer().catch((error) => {
+      throw new Error(
+        `Failed to read response buffer: ${error instanceof Error ? error.message : String(error)}`
+      );
+    });
+    onProgress?.('reading-file', 100, 'URL fetch complete');
+
+    return this.loadFromBuffer(buffer, options, onProgress);
+  }
+
+  /**
+   * Build file tree from JSZip instance
+   */
+  private async buildFileTree(zip: any, onProgress?: ZipProgressCallback): Promise<ZipFileTree> {
+    const files = new Map<string, ZipFileItem>();
+    const directories = new Set<string>();
+
+    const zipFiles = Object.keys(zip.files);
+    let processed = 0;
+
+    // Pre-load all file contents for performance
+    for (const filename of zipFiles) {
+      const zipEntry = zip.files[filename];
+
+      if (zipEntry.dir) {
+        directories.add(filename);
+        files.set(filename, {
+          name:
+            filename
+              .split('/')
+              .filter((p) => p)
+              .pop() || filename,
+          path: filename,
+          size: 0,
+          isDirectory: true,
+          lastModified: zipEntry.date
+        });
+      } else {
+        // Load file content
+        const content = await zipEntry.async('string');
+
+        files.set(filename, {
+          name: filename.split('/').pop() || filename,
+          path: filename,
+          size: content.length,
+          isDirectory: false,
+          lastModified: zipEntry.date,
+          content
+        });
+      }
+
+      processed++;
+      const progress = Math.round((processed / zipFiles.length) * 100);
+      onProgress?.('extracting-files', progress, `Processing ${filename}`);
+    }
+
+    return {
+      files,
+      directories,
+      root: this.findCommonRoot(Array.from(files.keys()))
+    };
+  }
+
+  /**
+   * Load manifest from ZIP
+   */
+  private async loadManifest(zip: any): Promise<any> {
+    const manifestFile = zip.files['manifest.json'];
+    if (!manifestFile) {
+      return null;
+    }
+
+    const manifestData = await manifestFile.async('string').catch((error: any) => {
+      console.warn('Failed to read manifest file:', error);
+      return null;
+    });
+
+    if (!manifestData) return null;
+
+    const parseResult = parseManifest(manifestData);
+    return parseResult.orDefault() ?? null;
+  }
+
+  /**
+   * Load configuration from ZIP
+   */
+  private async loadConfiguration(zip: any, options: ZipLoadOptions): Promise<any> {
+    if (options.overrideConfig) {
+      return options.overrideConfig;
+    }
+
+    const configFile = zip.files['config.json'];
+    if (!configFile) {
+      return null;
+    }
+
+    const configData = await configFile.async('string').catch((error: any) => {
+      console.warn('Failed to read config file:', error);
+      return null;
+    });
+
+    if (!configData) return null;
+
+    const parseResult = parseConfiguration(configData);
+    return parseResult.orDefault() ?? null;
+  }
+
+  /**
+   * Find common root directory from file paths
+   */
+  private findCommonRoot(paths: string[]): string {
+    if (paths.length === 0) return '';
+    if (paths.length === 1) return paths[0].split('/')[0] || '';
+
+    const parts = paths[0].split('/');
+    let commonLength = 0;
+
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+      if (paths.every((path) => path.split('/')[i] === part)) {
+        commonLength = i + 1;
+      } else {
+        break;
+      }
+    }
+
+    return parts.slice(0, commonLength).join('/');
+  }
+}
+
+/**
+ * Create a new browser ZIP loader instance
+ */
+export function createBrowserZipLoader(): IZipLoader {
+  return new BrowserZipLoader();
+}
+
+/**
+ * Convenience function to load ZIP from File with default options
+ */
+export async function loadZipFile(
+  file: File,
+  options?: ZipLoadOptions,
+  onProgress?: ZipProgressCallback
+): Promise<Result<ZipLoadResult>> {
+  const loader = createBrowserZipLoader();
+  return loader.loadFromFile(file, options, onProgress);
+}
+
+/**
+ * Convenience function to load ZIP from URL with default options
+ */
+export async function loadZipFromUrl(
+  url: string,
+  options?: ZipLoadOptions,
+  onProgress?: ZipProgressCallback
+): Promise<Result<ZipLoadResult>> {
+  const loader = createBrowserZipLoader();
+  return loader.loadFromUrl(url, options, onProgress);
+}

package/src/utils/zipLoader/index.ts

@@ -0,0 +1,26 @@
+// Export types
+export * from './types';
+
+// Export utilities
+export * from './zipUtils';
+
+// Export browser ZIP loader
+export * from './browserZipLoader';
+
+// Export Node.js ZIP builder (placeholder)
+export * from './nodeZipBuilder';
+
+// Re-export commonly used functions
+export { loadZipFile, loadZipFromUrl, createBrowserZipLoader } from './browserZipLoader';
+
+export { prepareZipData, prepareZipDataFromDirectory, createNodeZipBuilder } from './nodeZipBuilder';
+
+export {
+  generateZipFilename,
+  parseManifest,
+  parseConfiguration,
+  zipTreeToFiles,
+  zipTreeToDirectory,
+  formatFileSize,
+  isZipFile
+} from './zipUtils';

package/src/utils/zipLoader/nodeZipBuilder.ts

@@ -0,0 +1,153 @@
+import { Result, succeed, fail } from '@fgv/ts-utils';
+import { IZipBuilder, ZipArchiveOptions, ZipArchiveResult, ZipManifest } from './types';
+import { ImportedDirectory, ImportedFile } from '../../types';
+import { generateZipFilename, createManifest, sanitizeFilename, normalizePath } from './zipUtils';
+
+/**
+ * Node.js-based ZIP builder implementation
+ *
+ * Note: This is a placeholder implementation for interface compatibility.
+ * The actual Node.js ZIP building functionality should be implemented
+ * in a separate Node.js-specific package or tool.
+ */
+export class NodeZipBuilder implements IZipBuilder {
+  /**
+   * Create ZIP from files
+   */
+  async createFromFiles(
+    files: ImportedFile[],
+    options: ZipArchiveOptions = {}
+  ): Promise<Result<ZipArchiveResult>> {
+    return fail(
+      'Node.js ZIP building not implemented in browser library. Use @fgv/ts-res-browser-cli for ZIP creation.'
+    );
+  }
+
+  /**
+   * Create ZIP from directory
+   */
+  async createFromDirectory(
+    directory: ImportedDirectory,
+    options: ZipArchiveOptions = {}
+  ): Promise<Result<ZipArchiveResult>> {
+    return fail(
+      'Node.js ZIP building not implemented in browser library. Use @fgv/ts-res-browser-cli for ZIP creation.'
+    );
+  }
+
+  /**
+   * Create ZIP from file system path
+   */
+  async createFromPath(path: string, options: ZipArchiveOptions = {}): Promise<Result<ZipArchiveResult>> {
+    return fail(
+      'Node.js ZIP building not implemented in browser library. Use @fgv/ts-res-browser-cli for ZIP creation.'
+    );
+  }
+}
+
+/**
+ * Create a new Node.js ZIP builder instance
+ *
+ * Note: This returns a placeholder implementation.
+ * For actual ZIP building, use the ts-res-browser-cli tool.
+ */
+export function createNodeZipBuilder(): IZipBuilder {
+  return new NodeZipBuilder();
+}
+
+/**
+ * Browser-compatible ZIP creation interface
+ *
+ * This provides a way to prepare ZIP data in the browser,
+ * though actual ZIP file creation requires server-side processing
+ * or a separate Node.js tool.
+ */
+export interface BrowserZipData {
+  files: Array<{
+    path: string;
+    content: string;
+  }>;
+  manifest: ZipManifest;
+  config?: any;
+}
+
+/**
+ * Prepare ZIP data structure for browser download or server processing
+ */
+export function prepareZipData(
+  files: ImportedFile[],
+  options: ZipArchiveOptions = {}
+): Result<BrowserZipData> {
+  const timestamp = new Date().toISOString();
+  const filename = options.filename || 'ts-res-bundle';
+
+  // Create manifest
+  const manifest = createManifest(
+    'file',
+    'browser-files',
+    'files/',
+    options.includeConfig ? 'config.json' : undefined
+  );
+
+  // Prepare file data
+  const zipFiles = files.map((file) => ({
+    path: normalizePath(file.path || file.name),
+    content: file.content
+  }));
+
+  // Add manifest
+  zipFiles.push({
+    path: 'manifest.json',
+    content: JSON.stringify(manifest, null, 2)
+  });
+
+  // Add configuration if provided
+  if (options.includeConfig && options.config) {
+    zipFiles.push({
+      path: 'config.json',
+      content: JSON.stringify(options.config, null, 2)
+    });
+  }
+
+  return succeed({
+    files: zipFiles,
+    manifest,
+    config: options.config
+  });
+}
+
+/**
+ * Prepare ZIP data from directory structure
+ */
+export function prepareZipDataFromDirectory(
+  directory: ImportedDirectory,
+  options: ZipArchiveOptions = {}
+): Result<BrowserZipData> {
+  // Flatten directory to files
+  const files: ImportedFile[] = [];
+
+  const collectFiles = (dir: ImportedDirectory, basePath: string = '') => {
+    // Add files from current directory
+    dir.files.forEach((file) => {
+      files.push({
+        ...file,
+        path: basePath ? `${basePath}/${file.name}` : file.name
+      });
+    });
+
+    // Recursively collect from subdirectories
+    if (dir.subdirectories) {
+      dir.subdirectories.forEach((subdir) => {
+        const subdirPath = basePath ? `${basePath}/${subdir.name}` : subdir.name;
+        collectFiles(subdir, subdirPath);
+      });
+    }
+  };
+
+  collectFiles(directory);
+
+  return prepareZipData(files, {
+    ...options,
+    filename: options.filename || sanitizeFilename(directory.name)
+  });
+}

package/src/utils/zipLoader/types.ts

@@ -0,0 +1,175 @@
+import { Result } from '@fgv/ts-utils';
+import { Config } from '@fgv/ts-res';
+import { ImportedDirectory, ImportedFile, ProcessedResources } from '../../types';
+
+/**
+ * ZIP manifest metadata structure
+ */
+export interface ZipManifest {
+  timestamp: string;
+  input?: {
+    type: 'file' | 'directory';
+    originalPath: string;
+    archivePath: string;
+  };
+  config?: {
+    type: 'file';
+    originalPath: string;
+    archivePath: string;
+  };
+}
+
+/**
+ * Options for creating ZIP archives
+ */
+export interface ZipArchiveOptions {
+  /** Output directory for the ZIP file */
+  outputDir?: string;
+  /** Custom filename (without extension) */
+  filename?: string;
+  /** Compression level (0-9) */
+  compressionLevel?: number;
+  /** Include configuration file */
+  includeConfig?: boolean;
+  /** Custom configuration to include */
+  config?: Config.Model.ISystemConfiguration;
+}
+
+/**
+ * Result of ZIP archive creation
+ */
+export interface ZipArchiveResult {
+  /** Path to the created ZIP file */
+  filePath: string;
+  /** Size of the ZIP file in bytes */
+  fileSize: number;
+  /** Generated manifest */
+  manifest: ZipManifest;
+  /** Timestamp when created */
+  timestamp: string;
+}
+
+/**
+ * Options for loading ZIP archives
+ */
+export interface ZipLoadOptions {
+  /** Whether to auto-apply configuration found in ZIP */
+  autoApplyConfig?: boolean;
+  /** Whether to auto-process resources after loading */
+  autoProcessResources?: boolean;
+  /** Custom configuration to use instead of ZIP config */
+  overrideConfig?: Config.Model.ISystemConfiguration;
+}
+
+/**
+ * Result of ZIP loading operation
+ */
+export interface ZipLoadResult {
+  /** Manifest from the ZIP */
+  manifest: ZipManifest | null;
+  /** Configuration found in ZIP */
+  config: Config.Model.ISystemConfiguration | null;
+  /** Loaded files */
+  files: ImportedFile[];
+  /** Loaded directory structure */
+  directory: ImportedDirectory | null;
+  /** File tree for direct processing */
+  fileTree?: any; // FileTree.FileTree from ts-utils
+  /** Processed resources if auto-processing was enabled */
+  processedResources: ProcessedResources | null;
+}
+
+/**
+ * ZIP loading progress stages
+ */
+export type ZipLoadingStage =
+  | 'reading-file'
+  | 'parsing-zip'
+  | 'loading-manifest'
+  | 'loading-config'
+  | 'extracting-files'
+  | 'processing-resources'
+  | 'complete';
+
+/**
+ * Progress callback for ZIP operations
+ */
+export interface ZipProgressCallback {
+  (stage: ZipLoadingStage, progress: number, message?: string): void;
+}
+
+/**
+ * ZIP builder interface (Node.js environment)
+ */
+export interface IZipBuilder {
+  /**
+   * Create ZIP from files
+   */
+  createFromFiles(files: ImportedFile[], options?: ZipArchiveOptions): Promise<Result<ZipArchiveResult>>;
+
+  /**
+   * Create ZIP from directory
+   */
+  createFromDirectory(
+    directory: ImportedDirectory,
+    options?: ZipArchiveOptions
+  ): Promise<Result<ZipArchiveResult>>;
+
+  /**
+   * Create ZIP from file system path
+   */
+  createFromPath(path: string, options?: ZipArchiveOptions): Promise<Result<ZipArchiveResult>>;
+}
+
+/**
+ * ZIP loader interface (Browser environment)
+ */
+export interface IZipLoader {
+  /**
+   * Load ZIP from File object
+   */
+  loadFromFile(
+    file: File,
+    options?: ZipLoadOptions,
+    onProgress?: ZipProgressCallback
+  ): Promise<Result<ZipLoadResult>>;
+
+  /**
+   * Load ZIP from ArrayBuffer
+   */
+  loadFromBuffer(
+    buffer: ArrayBuffer,
+    options?: ZipLoadOptions,
+    onProgress?: ZipProgressCallback
+  ): Promise<Result<ZipLoadResult>>;
+
+  /**
+   * Load ZIP from URL
+   */
+  loadFromUrl(
+    url: string,
+    options?: ZipLoadOptions,
+    onProgress?: ZipProgressCallback
+  ): Promise<Result<ZipLoadResult>>;
+}
+
+/**
+ * File item within a ZIP archive
+ */
+export interface ZipFileItem {
+  name: string;
+  path: string;
+  size: number;
+  isDirectory: boolean;
+  lastModified?: Date;
+  content?: string | ArrayBuffer;
+}
+
+/**
+ * ZIP file tree representation
+ */
+export interface ZipFileTree {
+  files: Map<string, ZipFileItem>;
+  directories: Set<string>;
+  root: string;
+}