@fgv/ts-res-browser 1.0.0 → 5.0.0-3

package/README.md

@@ -4,9 +4,20 @@ A visual tool for loading, browsing, and experimenting with ts-res resources. Bu
 
 ## Features
 
-- **Source Browser**: Browse and explore built resources
-- **Compiled Browser**: Navigate compiled resource collections
-- **Resolution Viewer**: Test resource resolution with different qualifiers
+### Core Tools
+- **Import Tool**: Load resources from files or directories using File System Access API
+- **ZIP Loader**: Load pre-bundled ZIP archives created by ts-res-browser-cli
+- **Source Browser**: Browse and explore built resources in alphabetical order
+- **Compiled Browser**: Navigate compiled resource collections in tree view
+- **Filter Tool**: Filter resources by context for focused analysis
+- **Resolution Viewer**: Test resource resolution with different qualifiers and contexts
+- **Configuration Tool**: Manage qualifier types, qualifiers, and resource types
+
+### Advanced Features
+- **ZIP Archive Support**: Direct loading of ZIP bundles with automatic configuration application
+- **URL Parameter Integration**: Launch with pre-configured settings via command line
+- **Context Filtering**: Advanced filtering by language, territory, and custom qualifiers
+- **Interactive Mode**: Explore with sample data and predefined configurations
 - **Modern UI**: Built with React, TypeScript, and Tailwind CSS
 
 ## Getting Started
@@ -37,10 +48,40 @@ The application will open in your browser at `http://localhost:3000`.
 
 ### Usage
 
-1. **Import Files**: Click "Import Files" to select your ts-res project files
-2. **Browse Resources**: Use the sidebar to navigate between different tools
+#### Option 1: Direct File Loading
+1. **Import Files**: Use the Import Tool to select your ts-res project files/directories
+2. **Browse Resources**: Navigate between different tools using the sidebar
 3. **Explore**: View resource details, test resolution, and experiment with qualifiers
 
+#### Option 2: ZIP Archive Workflow (Recommended)
+1. **Create Archive**: Use ts-res-browser-cli to create ZIP archives:
+   ```bash
+   ts-res-browser-cli browse --input ./resources --config extended-example
+   ```
+2. **Load Archive**: Use the ZIP Loader tool to load the created archive
+3. **Automatic Setup**: Configuration and resources are applied automatically
+
+#### Option 3: Command Line Integration
+Launch directly with pre-configured settings:
+```bash
+# Launch with automatic development server
+ts-res-browser-cli browse --input ./resources --dev
+
+# Launch with ZIP creation but no browser opening
+ts-res-browser-cli browse --input ./resources --no-open
+```
+
+### URL Parameters
+
+The browser supports URL parameters for automated setup:
+- `config=<name>`: Load predefined configuration
+- `contextFilter=<filter>`: Apply context filtering  
+- `loadZip=true`: Navigate directly to ZIP Loader
+- `interactive=true`: Launch in interactive mode
+- `reduceQualifiers=true`: Enable qualifier reduction
+
+Example: `http://localhost:3000?config=extended-example&loadZip=true`
+
 ## Development
 
 ### Scripts
@@ -55,32 +96,61 @@ The application will open in your browser at `http://localhost:3000`.
 ```
 src/
 ├── components/
-│   ├── layout/          # Layout components
+│   ├── layout/          # Layout components (Header, Sidebar, etc.)
 │   ├── tools/           # Tool-specific components
+│   │   ├── ImportTool.tsx           # File/directory import
+│   │   ├── ZipLoader.tsx            # ZIP archive loader
+│   │   ├── SourceBrowser.tsx        # Resource browsing
+│   │   ├── CompiledBrowser.tsx      # Tree view navigation  
+│   │   ├── FilterTool.tsx           # Context filtering
+│   │   ├── ResolutionViewer.tsx     # Resolution testing
+│   │   └── ConfigurationTool.tsx    # Configuration management
 │   └── common/          # Shared components
 ├── hooks/               # Custom React hooks
-├── types/               # TypeScript type definitions
+│   ├── useAppState.ts               # Main application state
+│   ├── useResourceManager.ts        # Resource processing
+│   ├── useFileImport.ts             # File system operations
+│   └── useUrlParams.ts              # URL parameter parsing
 ├── utils/               # Utility functions
-├── App.tsx              # Main application component
+│   ├── zip/                         # Browser-specific ZIP utilities
+│   ├── fileImport.ts                # File system integration
+│   ├── fileTreeConverter.ts         # FileTree integration
+│   └── urlParams.ts                 # URL parameter utilities
+├── types/               # TypeScript type definitions
+├── App.tsx              # Main application component  
 └── main.tsx             # Application entry point
 ```
 
 ### Technology Stack
 
-- **React 18+** with TypeScript
-- **Webpack** for bundling
+- **React 19** with TypeScript
+- **Webpack 5** for bundling with browser polyfills
 - **Tailwind CSS** for styling
-- **Heroicons** for iconography
+- **Heroicons** for iconography  
+- **JSZip** for browser-based ZIP processing
 - **@fgv/ts-res** for resource management
+- **@fgv/ts-utils** for Result pattern and FileTree abstraction
 
 ## Architecture
 
 The application follows a component-based architecture with:
 
-- **State Management**: React Context + useReducer
-- **File Access**: File System Access API with fallback
-- **Error Handling**: Result pattern from @fgv/ts-utils
-- **Testing**: Jest with React Testing Library
+### Core Systems
+- **State Management**: React hooks with centralized state management
+- **File Access**: File System Access API with fallback to input elements
+- **ZIP Processing**: Browser-compatible ZIP implementation using JSZip
+- **Resource Processing**: FileTree abstraction for unified file access
+- **Error Handling**: Result pattern from @fgv/ts-utils throughout
+
+### Integration Points
+- **CLI Integration**: Seamless workflow with ts-res-browser-cli via ZIP archives
+- **URL Parameters**: Support for automated setup and configuration
+- **Development Server**: Integration with webpack-dev-server for hot reloading
+
+### Browser Compatibility
+- **File System Access API**: Modern file access with graceful fallback
+- **Node.js Polyfills**: Webpack configuration for browser compatibility
+- **ZIP Archives**: Client-side processing without server dependencies
 
 ## Contributing
 

package/cli.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+
+const { exec, spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const command = process.argv[2];
+const projectRoot = __dirname;
+
+// Check if we have a built dist directory
+const distPath = path.join(projectRoot, 'dist');
+const hasBuiltFiles = fs.existsSync(distPath) && fs.existsSync(path.join(distPath, 'index.html'));
+
+function startDevServer(port = 3000) {
+  const packageManager = fs.existsSync(path.join(projectRoot, 'package-lock.json'))
+    ? 'npm'
+    : fs.existsSync(path.join(projectRoot, 'yarn.lock'))
+    ? 'yarn'
+    : 'npm';
+
+  console.log('Starting TS-RES Browser development server...');
+  console.log(`Using ${packageManager} to start server...`);
+
+  const child = spawn(packageManager, ['run', 'dev'], {
+    cwd: projectRoot,
+    stdio: 'inherit',
+    env: { ...process.env, PORT: port.toString() }
+  });
+
+  child.on('error', (error) => {
+    console.error(`Error starting dev server: ${error.message}`);
+    process.exit(1);
+  });
+}
+
+function serveBuildFiles(port = 8080) {
+  if (!hasBuiltFiles) {
+    console.error('No built files found. Please run "ts-res-browser build" first.');
+    process.exit(1);
+  }
+
+  // Try to use a simple static server
+  try {
+    const handler = require('serve-handler');
+    const http = require('http');
+
+    const server = http.createServer((request, response) => {
+      return handler(request, response, {
+        public: distPath,
+        rewrites: [{ source: '**', destination: '/index.html' }]
+      });
+    });
+
+    server.listen(port, () => {
+      console.log(`TS-RES Browser running at http://localhost:${port}`);
+      console.log('Press Ctrl+C to stop');
+    });
+  } catch (error) {
+    // Fallback: just open the HTML file
+    console.log(`Built files available at: ${path.join(distPath, 'index.html')}`);
+    console.log('To serve the files, install a static server like: npm install -g serve');
+    console.log(`Then run: serve -s ${distPath} -p ${port}`);
+  }
+}
+
+switch (command) {
+  case 'dev':
+    const devPort = process.argv[3] || process.env.PORT || 3000;
+    startDevServer(devPort);
+    break;
+
+  case 'serve':
+  case 'start':
+    const servePort = process.argv[3] || 8080;
+    serveBuildFiles(servePort);
+    break;
+
+  case 'build':
+    console.log('Building TS-RES Browser...');
+    const packageManager = fs.existsSync(path.join(projectRoot, 'package-lock.json')) ? 'npm' : 'npm';
+
+    const buildChild = spawn(packageManager, ['run', 'build'], {
+      cwd: projectRoot,
+      stdio: 'inherit'
+    });
+
+    buildChild.on('error', (error) => {
+      console.error(`Error building: ${error.message}`);
+      process.exit(1);
+    });
+
+    buildChild.on('close', (code) => {
+      if (code === 0) {
+        console.log('Build completed successfully!');
+        console.log('To serve the built files, run: ts-res-browser serve');
+      } else {
+        console.error(`Build failed with code ${code}`);
+        process.exit(code);
+      }
+    });
+    break;
+
+  default:
+    console.log('TS-RES Browser CLI');
+    console.log('');
+    console.log('Usage:');
+    console.log('  ts-res-browser dev    - Start development server');
+    console.log('  ts-res-browser build  - Build for production');
+    console.log('  ts-res-browser serve  - Serve built files');
+    console.log('');
+    console.log('Options:');
+    console.log('  ts-res-browser dev [port]   - Start dev server on specific port');
+    console.log('  ts-res-browser serve [port] - Serve on specific port');
+    console.log('');
+    if (hasBuiltFiles) {
+      console.log('✅ Built files found - you can run "ts-res-browser serve"');
+    } else {
+      console.log('⚠️  No built files - run "ts-res-browser build" first');
+    }
+    break;
+}