@fgv/ts-res-browser 5.0.0-2 → 5.0.0-21

package/src/utils/zip/browserZipFileTreeAccessors.ts

@@ -1,385 +0,0 @@
-/*
- * Copyright (c) 2025 Erik Fortune
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all
- * copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- */
-
-import JSZip from 'jszip';
-import { Result, succeed, fail, captureResult, Converter, Validator, FileTree } from '@fgv/ts-utils';
-
-/**
- * Implementation of {@link FileTree.IFileTreeFileItem} for files in a ZIP archive (browser version).
- */
-export class BrowserZipFileItem implements FileTree.IFileTreeFileItem {
-  /**
-   * Indicates that this {@link FileTree.FileTreeItem} is a file.
-   */
-  public readonly type: 'file' = 'file';
-
-  /**
-   * The absolute path of the file within the ZIP archive.
-   */
-  public readonly absolutePath: string;
-
-  /**
-   * The name of the file
-   */
-  public readonly name: string;
-
-  /**
-   * The base name of the file (without extension)
-   */
-  public readonly baseName: string;
-
-  /**
-   * The extension of the file
-   */
-  public readonly extension: string;
-
-  /**
-   * The pre-loaded contents of the file.
-   */
-  private readonly _contents: string;
-
-  /**
-   * The ZIP file tree accessors that created this item.
-   */
-  private readonly _accessors: BrowserZipFileTreeAccessors;
-
-  /**
-   * Constructor for BrowserZipFileItem.
-   * @param zipFilePath - The path of the file within the ZIP.
-   * @param contents - The pre-loaded contents of the file.
-   * @param accessors - The ZIP file tree accessors.
-   */
-  public constructor(zipFilePath: string, contents: string, accessors: BrowserZipFileTreeAccessors) {
-    this._contents = contents;
-    this._accessors = accessors;
-    this.absolutePath = '/' + zipFilePath;
-    this.name = accessors.getBaseName(zipFilePath);
-    this.extension = accessors.getExtension(zipFilePath);
-    this.baseName = accessors.getBaseName(zipFilePath, this.extension);
-  }
-
-  /**
-   * Gets the contents of the file as parsed JSON.
-   */
-  public getContents(): Result<unknown>;
-  public getContents<T>(converter: Validator<T> | Converter<T>): Result<T>;
-  public getContents<T>(converter?: Validator<T> | Converter<T>): Result<T | unknown> {
-    return this.getRawContents()
-      .onSuccess((contents) => {
-        return captureResult(() => {
-          const parsed = JSON.parse(contents);
-          if (converter) {
-            if ('convert' in converter) {
-              return converter.convert(parsed);
-            } else {
-              return (converter as Validator<T>).validate(parsed);
-            }
-          }
-          return succeed(parsed);
-        }).onFailure(() => {
-          return fail(`Failed to parse JSON from file: ${this.absolutePath}`);
-        });
-      })
-      .onFailure((error) => {
-        return fail(`Failed to get contents from file: ${error}`);
-      });
-  }
-
-  /**
-   * Gets the raw contents of the file as a string.
-   */
-  public getRawContents(): Result<string> {
-    return succeed(this._contents);
-  }
-}
-
-/**
- * Implementation of {@link FileTree.IFileTreeDirectoryItem} for directories in a ZIP archive (browser version).
- */
-export class BrowserZipDirectoryItem implements FileTree.IFileTreeDirectoryItem {
-  /**
-   * Indicates that this {@link FileTree.FileTreeItem} is a directory.
-   */
-  public readonly type: 'directory' = 'directory';
-
-  /**
-   * The absolute path of the directory within the ZIP archive.
-   */
-  public readonly absolutePath: string;
-
-  /**
-   * The name of the directory
-   */
-  public readonly name: string;
-
-  /**
-   * The ZIP file tree accessors that created this item.
-   */
-  private readonly _accessors: BrowserZipFileTreeAccessors;
-
-  /**
-   * Constructor for BrowserZipDirectoryItem.
-   * @param directoryPath - The path of the directory within the ZIP.
-   * @param accessors - The ZIP file tree accessors.
-   */
-  public constructor(directoryPath: string, accessors: BrowserZipFileTreeAccessors) {
-    this._accessors = accessors;
-    this.absolutePath = '/' + directoryPath.replace(/\/$/, ''); // Normalize path
-    this.name = accessors.getBaseName(directoryPath);
-  }
-
-  /**
-   * Gets the children of the directory.
-   */
-  public getChildren(): Result<ReadonlyArray<FileTree.FileTreeItem>> {
-    return this._accessors.getChildren(this.absolutePath);
-  }
-}
-
-/**
- * File tree accessors for ZIP archives (browser version using JSZip).
- */
-export class BrowserZipFileTreeAccessors implements FileTree.IFileTreeAccessors {
-  /**
-   * The JSZip instance containing the archive.
-   */
-  private readonly _zip: JSZip;
-
-  /**
-   * Optional prefix to prepend to paths.
-   */
-  private readonly _prefix: string;
-
-  /**
-   * Cache of all items in the ZIP for efficient lookups.
-   */
-  private readonly _itemCache: Map<string, FileTree.FileTreeItem> = new Map();
-
-  /**
-   * Cache of all file contents pre-loaded from the ZIP.
-   */
-  private readonly _fileContents: Map<string, string> = new Map();
-
-  /**
-   * Constructor for BrowserZipFileTreeAccessors.
-   * @param zip - The JSZip instance.
-   * @param fileContents - Pre-loaded file contents.
-   * @param prefix - Optional prefix to prepend to paths.
-   */
-  private constructor(zip: JSZip, fileContents: Map<string, string>, prefix?: string) {
-    this._zip = zip;
-    this._fileContents = fileContents;
-    this._prefix = prefix || '';
-    this._buildItemCache();
-  }
-
-  /**
-   * Creates a new BrowserZipFileTreeAccessors instance from a ZIP file buffer.
-   * @param zipBuffer - The ZIP file as an ArrayBuffer or Uint8Array.
-   * @param prefix - Optional prefix to prepend to paths.
-   * @returns Result containing the BrowserZipFileTreeAccessors instance.
-   */
-  public static async fromBuffer(
-    zipBuffer: ArrayBuffer | Uint8Array,
-    prefix?: string
-  ): Promise<Result<BrowserZipFileTreeAccessors>> {
-    try {
-      const zip = new JSZip();
-      await zip.loadAsync(zipBuffer);
-      const fileContents = new Map<string, string>();
-
-      // Pre-load all file contents
-      const promises: Promise<void>[] = [];
-      zip.forEach((relativePath, zipObject) => {
-        if (!zipObject.dir) {
-          const promise = zipObject.async('string').then((content) => {
-            fileContents.set(relativePath, content);
-          });
-          promises.push(promise);
-        }
-      });
-
-      await Promise.all(promises);
-      return succeed(new BrowserZipFileTreeAccessors(zip, fileContents, prefix));
-    } catch (error) {
-      return fail(`Failed to load ZIP archive: ${error instanceof Error ? error.message : String(error)}`);
-    }
-  }
-
-  /**
-   * Creates a new BrowserZipFileTreeAccessors instance from a File object (browser environment).
-   * @param file - The File object containing ZIP data.
-   * @param prefix - Optional prefix to prepend to paths.
-   * @returns Result containing the BrowserZipFileTreeAccessors instance.
-   */
-  public static async fromFile(file: File, prefix?: string): Promise<Result<BrowserZipFileTreeAccessors>> {
-    try {
-      const arrayBuffer = await file.arrayBuffer();
-      return await BrowserZipFileTreeAccessors.fromBuffer(arrayBuffer, prefix);
-    } catch (error) {
-      return fail(`Failed to read file: ${error instanceof Error ? error.message : String(error)}`);
-    }
-  }
-
-  /**
-   * Builds the cache of all items in the ZIP archive.
-   */
-  private _buildItemCache(): void {
-    const directories = new Set<string>();
-
-    // First pass: collect all directories from file paths
-    this._zip.forEach((relativePath, zipObject) => {
-      if (!zipObject.dir) {
-        // Extract directory path from file path
-        const pathParts = relativePath.split('/');
-        for (let i = 1; i < pathParts.length; i++) {
-          const dirPath = pathParts.slice(0, i).join('/');
-          directories.add(dirPath);
-        }
-      }
-    });
-
-    // Add directory items to cache
-    directories.forEach((dirPath) => {
-      const absolutePath = this.resolveAbsolutePath(dirPath);
-      const item = new BrowserZipDirectoryItem(dirPath, this);
-      this._itemCache.set(absolutePath, item);
-    });
-
-    // Add file items to cache
-    this._zip.forEach((relativePath, zipObject) => {
-      if (!zipObject.dir) {
-        const absolutePath = this.resolveAbsolutePath(relativePath);
-        const contents = this._fileContents.get(relativePath) || '';
-        const item = new BrowserZipFileItem(relativePath, contents, this);
-        this._itemCache.set(absolutePath, item);
-      }
-    });
-  }
-
-  /**
-   * Resolves paths to an absolute path.
-   */
-  public resolveAbsolutePath(...paths: string[]): string {
-    const joinedPath = this.joinPaths(...paths);
-    const prefixed = this._prefix ? this.joinPaths(this._prefix, joinedPath) : joinedPath;
-    return prefixed.startsWith('/') ? prefixed : '/' + prefixed;
-  }
-
-  /**
-   * Gets the extension of a path.
-   */
-  public getExtension(path: string): string {
-    const name = this.getBaseName(path);
-    const lastDotIndex = name.lastIndexOf('.');
-    return lastDotIndex >= 0 ? name.substring(lastDotIndex) : '';
-  }
-
-  /**
-   * Gets the base name of a path.
-   */
-  public getBaseName(path: string, suffix?: string): string {
-    const normalizedPath = path.replace(/\/$/, ''); // Remove trailing slash
-    const parts = normalizedPath.split('/');
-    let baseName = parts[parts.length - 1] || '';
-
-    if (suffix && baseName.endsWith(suffix)) {
-      baseName = baseName.substring(0, baseName.length - suffix.length);
-    }
-
-    return baseName;
-  }
-
-  /**
-   * Joins paths together.
-   */
-  public joinPaths(...paths: string[]): string {
-    return paths
-      .filter((p) => p && p.length > 0)
-      .map((p) => p.replace(/^\/+|\/+$/g, '')) // Remove leading/trailing slashes
-      .join('/')
-      .replace(/\/+/g, '/'); // Normalize multiple slashes
-  }
-
-  /**
-   * Gets an item from the file tree.
-   */
-  public getItem(path: string): Result<FileTree.FileTreeItem> {
-    const absolutePath = this.resolveAbsolutePath(path);
-    const item = this._itemCache.get(absolutePath);
-
-    if (item) {
-      return succeed(item);
-    }
-
-    return fail(`Item not found: ${absolutePath}`);
-  }
-
-  /**
-   * Gets the contents of a file in the file tree.
-   */
-  public getFileContents(path: string): Result<string> {
-    return this.getItem(path).onSuccess((item) => {
-      if (item.type !== 'file') {
-        return fail(`Path is not a file: ${path}`);
-      }
-      return item.getRawContents();
-    });
-  }
-
-  /**
-   * Gets the children of a directory in the file tree.
-   */
-  public getChildren(path: string): Result<ReadonlyArray<FileTree.FileTreeItem>> {
-    const absolutePath = this.resolveAbsolutePath(path);
-    const children: FileTree.FileTreeItem[] = [];
-
-    // Find all items that are direct children of this directory
-    for (const [itemPath, item] of this._itemCache) {
-      if (this._isDirectChild(absolutePath, itemPath)) {
-        children.push(item);
-      }
-    }
-
-    return succeed(children);
-  }
-
-  /**
-   * Checks if childPath is a direct child of parentPath.
-   */
-  private _isDirectChild(parentPath: string, childPath: string): boolean {
-    // Normalize paths
-    const normalizedParent = parentPath.replace(/\/$/, '');
-    const normalizedChild = childPath.replace(/\/$/, '');
-
-    // Child must start with parent path
-    if (!normalizedChild.startsWith(normalizedParent + '/')) {
-      return false;
-    }
-
-    // Get the relative path from parent to child
-    const relativePath = normalizedChild.substring(normalizedParent.length + 1);
-
-    // Direct child means no additional slashes in the relative path
-    return !relativePath.includes('/');
-  }
-}

package/tailwind.config.js

@@ -1,21 +0,0 @@
-/** @type {import('tailwindcss').Config} */
-module.exports = {
-  content: [
-    './src/**/*.{js,jsx,ts,tsx}',
-    './public/index.html',
-    './src/components/**/*.{js,jsx,ts,tsx}',
-    './src/hooks/**/*.{js,jsx,ts,tsx}',
-    './src/utils/**/*.{js,jsx,ts,tsx}'
-  ],
-  theme: {
-    extend: {
-      colors: {
-        // Custom colors for the ts-res browser
-        'res-primary': '#2563eb',
-        'res-secondary': '#1e40af',
-        'res-accent': '#3b82f6'
-      }
-    }
-  },
-  plugins: []
-};

package/test-data/README.md

@@ -1,184 +0,0 @@
-# TS-RES Test Data
-
-This directory contains test data for the ts-res-browser tool that demonstrates all ts-res file formats and naming conventions.
-
-## Structure
-
-The test data demonstrates three different JSON file formats supported by ts-res:
-
-### 1. Simple JSON Files (Auto-converted to Resource Candidates)
-Individual JSON files with plain resource values that the ImportManager automatically converts to resource candidates.
-
-### 2. Resource Collection Format (`IResourceCollectionDecl`)
-JSON files that explicitly define multiple resources with their candidates and conditions.
-
-### 3. Resource Tree Format (`IResourceTreeRootDecl`)
-JSON files that define hierarchical resource structures with nested organization.
-
-## Directory Structure
-
-```
-src/resources/
-├── strings.json                              # Resource Collection (common, errors resources)
-├── app.json                                  # Resource Tree (app.config, app.ui.dashboard, app.ui.icons.* resources)
-├── strings/
-│   ├── common.json                           # Simple JSON → "common" resource
-│   ├── common.language=es.json               # Simple JSON → "common" resource (Spanish)
-│   ├── common.language=fr.json               # Simple JSON → "common" resource (French)
-│   ├── language=en-US.json                   # Simple JSON → "language" resource
-│   ├── dashboard.json                        # Simple JSON → "dashboard" resource
-│   ├── dashboard.role=user.json              # Simple JSON → "dashboard" resource (user)
-│   ├── dashboard.role=admin.json             # Simple JSON → "dashboard" resource (admin)
-│   ├── dashboard.home=CA,language=fr.json    # Simple JSON → "dashboard" resource (CA+FR)
-│   └── errors.json                           # Simple JSON → "errors" resource
-├── config/
-│   ├── app.json                              # Simple JSON → "app" resource
-│   ├── app.env=development.json              # Simple JSON → "app" resource (dev)
-│   └── app.platform=mobile.json             # Simple JSON → "app" resource (mobile)
-├── images/
-│   ├── home.json                             # Simple JSON → "home" resource
-│   ├── home.density=hdpi.json                # Simple JSON → "home" resource (hdpi)
-│   ├── user.json                             # Simple JSON → "user" resource
-│   ├── user.density=hdpi.json                # Simple JSON → "user" resource (hdpi)
-│   ├── settings.json                         # Simple JSON → "settings" resource
-│   ├── settings.density=hdpi.json            # Simple JSON → "settings" resource (hdpi)
-│   ├── logout.json                           # Simple JSON → "logout" resource
-│   └── logout.density=hdpi.json              # Simple JSON → "logout" resource (hdpi)
-├── en-US/
-│   └── common.json                           # Simple JSON → "common" resource (en-US context)
-├── home=CA/
-│   └── common.json                           # Simple JSON → "common" resource (CA context)
-└── import-config.json                        # TS-RES configuration
-```
-
-## Format Examples
-
-### Simple JSON Format
-```json
-{
-  "welcome": "Welcome to the application",
-  "hello": "Hello",
-  "goodbye": "Goodbye"
-}
-```
-*Auto-converted to resource candidate by ImportManager*
-
-### Resource Collection Format
-```json
-{
-  "resources": [
-    {
-      "id": "common",
-      "resourceTypeName": "json", 
-      "candidates": [
-        {
-          "json": {
-            "welcome": "Welcome to the application",
-            "hello": "Hello"
-          }
-        },
-        {
-          "json": {
-            "welcome": "Bienvenido a la aplicación", 
-            "hello": "Hola"
-          },
-          "conditions": {
-            "language": "es"
-          }
-        }
-      ]
-    }
-  ]
-}
-```
-
-### Resource Tree Format
-```json
-{
-  "context": {
-    "baseId": "app"
-  },
-  "resources": {
-    "config": {
-      "resourceTypeName": "json",
-      "candidates": [
-        {
-          "json": {
-            "app_name": "Sample Application",
-            "version": "1.0.0"
-          }
-        }
-      ]
-    }
-  },
-  "children": {
-    "ui": {
-      "resources": {
-        "dashboard": {
-          "resourceTypeName": "json",
-          "candidates": [
-            {
-              "json": {
-                "title": "Dashboard",
-                "overview": "Overview"
-              }
-            }
-          ]
-        }
-      }
-    }
-  }
-}
-```
-
-## Resources Generated
-
-The test data creates these resources:
-
-### From Simple JSON Files
-- `common` (4 candidates: base, Spanish, French, directory-based)
-- `dashboard` (4 candidates: base, user, admin, CA+French)
-- `errors` (1 candidate: base)
-- `language` (1 candidate: en-US)
-- `app` (3 candidates: base, dev, mobile)
-- `home`, `user`, `settings`, `logout` (2 candidates each: standard, hdpi)
-
-### From Resource Collection (strings.json)
-- `common` (3 candidates: base, Spanish, French)
-- `errors` (1 candidate: base)
-
-### From Resource Tree (app.json)
-- `app.config` (3 candidates: base, dev, mobile)
-- `app.ui.dashboard` (3 candidates: base, user, admin)
-- `app.ui.icons.home` (2 candidates: standard, hdpi)
-- `app.ui.icons.user` (2 candidates: standard, hdpi)
-
-## Qualifiers Demonstrated
-
-- **language**: `es`, `fr`, `en-US` (language codes)
-- **homeTerritory**: `CA` (with `home=` token, optional)
-- **role**: `user`, `admin` (literal values)
-- **env**: `development` (literal values)
-- **platform**: `mobile` (literal values)
-- **density**: `hdpi` (literal values)
-
-## Import Configuration
-
-The `import-config.json` file defines:
-- **Qualifier Types**: language, territory, literal
-- **Qualifiers**: language, homeTerritory, currentTerritory, role, env, platform, density
-- **Resource Types**: json
-
-## Usage
-
-This test data demonstrates:
-
-1. **Simple JSON Import**: Basic file-to-resource conversion
-2. **Resource Collections**: Multiple resources with candidates in one file
-3. **Resource Trees**: Hierarchical organization with nested resources
-4. **Qualifier Parsing**: File-based and explicit condition formats
-5. **Multi-condition Resources**: Complex qualifier combinations
-6. **Directory-based Organization**: Conditional directories
-7. **Mixed Formats**: Using different formats together
-
-The data follows ts-res patterns and provides comprehensive examples for testing all browser tool features. 

package/test-data/config-variations/README.md

@@ -1,64 +0,0 @@
-# Configuration Variations
-
-This directory contains various system configuration files for testing the ts-res browser tool. Each configuration demonstrates different priority schemes and use cases.
-
-## Available Configurations
-
-### high-priority-language.json
-- **Use Case**: Internationalization-focused applications
-- **Priority**: Language (900) > Territory (600/500) > Role (400) > Platform (300)
-- **Features**: Simplified role set, basic platform types
-
-### territory-first.json
-- **Use Case**: Region-specific applications
-- **Priority**: Territory (950/900) > Language (700) > Role (600) > Environment (500)
-- **Features**: Case-sensitive roles, territory context lists enabled, non-optional home territory token
-
-### gaming-app.json
-- **Use Case**: Gaming applications
-- **Priority**: Platform (850) > Language (800) > Territory (750) > Graphics (700) > Player Level (600) > Game Mode (550)
-- **Features**: Gaming-specific qualifiers (graphics quality, player level, game mode), platform-focused hierarchy
-
-### minimal-basic.json
-- **Use Case**: Simple applications with basic requirements
-- **Priority**: Language (600) > Device (500)
-- **Features**: Only two qualifiers, minimal complexity
-
-### qualifier-default-values.json
-- **Use Case**: Demonstrating qualifier default values functionality
-- **Priority**: Language (600) > Territory (500) > Device (400) > Environment (300)
-- **Features**: All qualifiers have default values configured (language with multiple values, territory single value, device with list, environment single value)
-- **Demonstrates**: How default values are defined and used when qualifiers are not specified in context
-
-### enterprise-complex.json
-- **Use Case**: Large enterprise applications with complex permissions and multi-tenancy
-- **Priority**: Tenant (1000) > Environment (950) > Security (900) > Territory (850/800) > Language (750) > Role (700) > Department (650) > Feature Flags (600)
-- **Features**: Multi-tenant support, security levels, department-based access, feature flags, complex role hierarchies
-
-### composition-terminology.json
-- **Use Case**: Demonstrating resource composition with international terminology variations plus full application context
-- **Priority**: Home Territory (850) > Language (800) > Territory (700) > Region (600) > Role (500) > Environment (400) > Platform (300) > Density (200)
-- **Features**: Comprehensive terminology resources showing composition with partial candidates for regional variations, plus full application qualifiers for testing existing resources
-- **Resources**: UI terms with base English/French/Dutch candidates and partial variants for Canadian English, British English, Canadian French, Belgian Dutch; App configuration with territory-specific settings; Feature flags with regional overrides; Plus supports existing sample project resources
-- **Demonstrates**: How partial candidates compose with base candidates to create localized terminology sets while maintaining compatibility with existing test resources
-
-## Usage
-
-These configurations can be loaded into the Configuration Tool to test different system setups and see how they affect resource resolution behavior.
-
-Each configuration includes:
-- **name**: Human-readable name for the configuration
-- **description**: Explanation of the use case and features
-- **qualifierTypes**: Defines the available qualifier types with their configurations
-- **qualifiers**: Defines the actual qualifiers with their priorities and tokens
-- **resourceTypes**: Available resource types (currently just JSON)
-
-## Testing Different Scenarios
-
-Use these configurations to test:
-1. **Priority Effects**: How different priority schemes affect resource resolution
-2. **Context Lists**: Territory and role configurations with `allowContextList` enabled
-3. **Case Sensitivity**: Role configurations with different case sensitivity settings
-4. **Token Usage**: Various token configurations (optional vs required)
-5. **Default Values**: Qualifier default values for fallback behavior (see qualifier-default-values.json)
-6. **Complexity Scaling**: From minimal (2 qualifiers) to complex (9 qualifiers)