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

package/.rush/temp/{03c8b056281d9db0a97d8a6e25eea798a160d393.tar.log → 96dcc283522e3a0fcf1e18730f9bb0a1d0fe9ad2.tar.log}

@@ -1,5 +1,5 @@
-Start time: Sat Aug 09 2025 19:30:22 GMT+0000 (Coordinated Universal Time)
-Invoking "/usr/bin/tar -c -f /home/runner/work/fgv/fgv/common/temp/build-cache/03c8b056281d9db0a97d8a6e25eea798a160d393-5dfd4ce4c834780c.temp -z --files-from=-"
+Start time: Sun Aug 10 2025 04:16:47 GMT+0000 (Coordinated Universal Time)
+Invoking "/usr/bin/tar -c -f /home/runner/work/fgv/fgv/common/temp/build-cache/96dcc283522e3a0fcf1e18730f9bb0a1d0fe9ad2-1d929c2480b91670.temp -z --files-from=-"
 
 ======= BEGIN PROCESS INPUT ======
 .rush/temp/operation/build/all.log

package/.rush/temp/chunked-rush-logs/ts-res-ui-components.build.chunks.jsonl

@@ -5,5 +5,5 @@
 {"kind":"O","text":"[build:sass] No SCSS files to process.\n"}
 {"kind":"O","text":"[build:typescript] Using TypeScript version 5.8.3\n"}
 {"kind":"O","text":"[build:webpack] No Webpack configuration found\n"}
-{"kind":"O","text":" ---- build finished (9.286s) ---- \n"}
-{"kind":"O","text":"-------------------- Finished (9.291s) --------------------\n"}
+{"kind":"O","text":" ---- build finished (9.270s) ---- \n"}
+{"kind":"O","text":"-------------------- Finished (9.275s) --------------------\n"}

package/.rush/temp/operation/build/all.log

@@ -5,5 +5,5 @@ Invoking: heft build --clean
 [build:sass] No SCSS files to process.
 [build:typescript] Using TypeScript version 5.8.3
 [build:webpack] No Webpack configuration found
- ---- build finished (9.286s) ---- 
--------------------- Finished (9.291s) --------------------
+ ---- build finished (9.270s) ---- 
+-------------------- Finished (9.275s) --------------------

package/.rush/temp/operation/build/log-chunks.jsonl

@@ -5,5 +5,5 @@
 {"kind":"O","text":"[build:sass] No SCSS files to process.\n"}
 {"kind":"O","text":"[build:typescript] Using TypeScript version 5.8.3\n"}
 {"kind":"O","text":"[build:webpack] No Webpack configuration found\n"}
-{"kind":"O","text":" ---- build finished (9.286s) ---- \n"}
-{"kind":"O","text":"-------------------- Finished (9.291s) --------------------\n"}
+{"kind":"O","text":" ---- build finished (9.270s) ---- \n"}
+{"kind":"O","text":"-------------------- Finished (9.275s) --------------------\n"}

package/.rush/temp/operation/build/state.json

@@ -1,3 +1,3 @@
 {
-  "nonCachedDurationMs": 9754.645378000001
+  "nonCachedDurationMs": 9753.646215999994
 }

package/README.md

@@ -1,18 +1,512 @@
-# Name
-### @fgv/ts-res-ui-components
+# @fgv/ts-res-ui-components
 
-# Synopsis
-Reusable React components for ts-res resource visualization and management
+React components for building user interfaces that work with the [ts-res](https://github.com/fgv/ts-res) multidimensional resource management library.
 
-# Description
+## Overview
 
-# Example
+This library provides a complete set of React components, hooks, and utilities for creating applications that visualize, manage, and interact with ts-res resource systems. It supports the full workflow from importing configurations to resolving resources with dynamic context.
 
-# Install:
-`npm install @fgv/ts-res-ui-components`
+## Warning
+This packlet is largely AI written, and it shows.
 
-# Test:
-`npm test`
+## Features
 
-#License:
-MIT
+- **🔄 Resource Management**: Import, process, and manage ts-res configurations and bundles
+- **🔍 Advanced Filtering**: Filter resources by context with qualifier reduction
+- **🎯 Resource Resolution**: Test resource resolution with dynamic context values
+- **📊 Visualization**: Multiple views for exploring resource structures and compiled output
+- **⚙️ Configuration**: Visual configuration management for qualifier types, qualifiers, and resource types
+- **📁 File Handling**: Support for directory imports, ZIP files, and bundle loading
+- **🎨 Modern UI**: Built with Tailwind CSS and Heroicons for a clean, responsive interface
+
+## Installation
+
+```bash
+npm install @fgv/ts-res-ui-components
+```
+
+### Peer Dependencies
+
+This library requires the following peer dependencies:
+
+```json
+{
+  "@fgv/ts-res": "^5.0.0",
+  "@fgv/ts-utils": "^5.0.0",
+  "@fgv/ts-json-base": "^5.0.0",
+  "react": "^18.0.0",
+  "react-dom": "^18.0.0"
+}
+```
+
+## Quick Start
+
+### Basic Usage with ResourceOrchestrator
+
+The `ResourceOrchestrator` component provides centralized state management for all ts-res UI functionality:
+
+```tsx
+import React from 'react';
+import { ResourceOrchestrator, ImportView, SourceView } from '@fgv/ts-res-ui-components';
+
+function App() {
+  return (
+    <ResourceOrchestrator>
+      {({ state, actions }) => (
+        <div className="min-h-screen bg-gray-50">
+          <div className="container mx-auto px-4 py-8">
+            <h1 className="text-3xl font-bold mb-8">Resource Manager</h1>
+            
+            {!state.processedResources ? (
+              <ImportView
+                onImport={actions.importDirectory}
+                onBundleImport={actions.importBundle}
+                onZipImport={actions.importZipWithConfig}
+              />
+            ) : (
+              <SourceView
+                resources={state.processedResources}
+                onExport={actions.exportData}
+              />
+            )}
+          </div>
+        </div>
+      )}
+    </ResourceOrchestrator>
+  );
+}
+
+export default App;
+```
+
+### Using Individual Hooks
+
+For more granular control, you can use individual hooks:
+
+```tsx
+import React from 'react';
+import { useResourceData, SourceView } from '@fgv/ts-res-ui-components';
+
+function MyResourceViewer() {
+  const { state, actions } = useResourceData();
+
+  const handleFileImport = async (files: File[]) => {
+    const importedFiles = await processFiles(files); // Your file processing logic
+    await actions.processFiles(importedFiles);
+  };
+
+  return (
+    <div>
+      {state.isProcessing && <div>Processing...</div>}
+      {state.error && <div className="error">{state.error}</div>}
+      {state.processedResources && (
+        <SourceView 
+          resources={state.processedResources}
+          onExport={(data) => console.log('Export:', data)}
+        />
+      )}
+    </div>
+  );
+}
+```
+
+## Architecture
+
+### Component Hierarchy
+
+```
+ResourceOrchestrator (state management)
+├── ImportView (file/bundle import)
+├── SourceView (resource collection display)
+├── FilterView (context filtering)
+├── CompiledView (compiled resource structure)
+├── ResolutionView (resource resolution testing)
+├── ConfigurationView (system configuration)
+└── ZipLoaderView (ZIP file handling)
+```
+
+### Data Flow
+
+1. **Import Phase**: Resources are imported via `ImportView` or programmatically
+2. **Processing Phase**: Raw files are processed into a `ProcessedResources` object containing:
+   - `ResourceManagerBuilder` for build-time operations
+   - `CompiledResourceCollection` for runtime efficiency
+   - `ResourceResolver` for resource resolution
+3. **Interaction Phase**: Users can filter, explore, and test resource resolution
+4. **Export Phase**: Processed resources can be exported as JSON or compiled bundles
+
+### Key Concepts
+
+- **ProcessedResources**: The main data structure containing both build-time and runtime representations
+- **ResourceManagerBuilder**: Build-time resource manager for constructing and modifying resources
+- **CompiledResourceCollection**: Runtime-optimized representation for efficient resolution
+- **Filter Context**: Dynamic context values used to filter and resolve resources
+- **Resolution State**: Testing environment for resource resolution with different contexts
+
+## Core Components
+
+### ResourceOrchestrator
+
+The main orchestration component that manages all state and provides actions via render props.
+
+```tsx
+<ResourceOrchestrator
+  initialConfiguration={myConfig}
+  onStateChange={(state) => console.log('State changed:', state)}
+>
+  {({ state, actions }) => (
+    // Your UI components
+  )}
+</ResourceOrchestrator>
+```
+
+### ImportView
+
+Handles importing resource files, directories, bundles, and ZIP files.
+
+```tsx
+<ImportView
+  onImport={actions.importDirectory}
+  onBundleImport={actions.importBundle}
+  onZipImport={actions.importZipWithConfig}
+  acceptedFileTypes={['.json', '.ts', '.js']}
+  onMessage={(type, message) => console.log(type, message)}
+/>
+```
+
+### SourceView
+
+Displays the source resource collection with search and navigation capabilities.
+
+```tsx
+<SourceView
+  resources={state.processedResources}
+  selectedResourceId={selectedId}
+  onResourceSelect={setSelectedId}
+  onExport={actions.exportData}
+/>
+```
+
+### FilterView
+
+Provides filtering capabilities with context value specification.
+
+```tsx
+<FilterView
+  resources={state.processedResources}
+  filterState={filterState}
+  filterActions={filterActions}
+  filterResult={filterResult}
+  onFilterResult={setFilterResult}
+/>
+```
+
+### CompiledView
+
+Shows the compiled resource structure with detailed candidate information.
+
+```tsx
+<CompiledView
+  resources={state.processedResources}
+  filterResult={filterResult}
+  useNormalization={true}
+  onExport={(data, type) => exportData(data, type)}
+/>
+```
+
+### ResolutionView
+
+Interactive resource resolution testing with context management.
+
+```tsx
+<ResolutionView
+  resources={state.processedResources}
+  resolutionState={resolutionState}
+  resolutionActions={resolutionActions}
+  availableQualifiers={availableQualifiers}
+/>
+```
+
+### ConfigurationView
+
+Visual configuration management for the ts-res system.
+
+```tsx
+<ConfigurationView
+  configuration={state.activeConfiguration}
+  onConfigurationChange={actions.applyConfiguration}
+  onMessage={(type, msg) => showMessage(type, msg)}
+/>
+```
+
+## Hooks API
+
+### useResourceData
+
+Main hook for resource processing and management.
+
+```tsx
+const { state, actions } = useResourceData();
+
+// Process files
+await actions.processFiles(importedFiles);
+
+// Resolve a resource
+const result = await actions.resolveResource('my.resource', {
+  language: 'en-US',
+  environment: 'production'
+});
+
+// Apply configuration
+actions.applyConfiguration(newConfig);
+```
+
+### useFilterState
+
+Manages resource filtering state and actions.
+
+```tsx
+const { filterState, filterActions } = useFilterState();
+
+// Update filter values
+filterActions.updateFilterValues({ 
+  language: 'en-US',
+  environment: 'prod' 
+});
+
+// Apply filters
+filterActions.applyFilterValues();
+
+// Check if there are pending changes
+if (filterState.hasPendingChanges) {
+  // Show save prompt
+}
+```
+
+### useResolutionState
+
+Manages resource resolution testing state.
+
+```tsx
+const { state, actions } = useResolutionState(processedResources);
+
+// Set context for resolution testing
+actions.setContextValues({ language: 'en-US' });
+
+// Test resource resolution
+const result = await actions.resolveResource('test.resource');
+```
+
+### useConfigurationState
+
+Manages system configuration state.
+
+```tsx
+const { configuration, updateConfiguration, resetConfiguration } = useConfigurationState();
+
+// Update qualifier types
+updateConfiguration({
+  ...configuration,
+  qualifierTypes: [...newQualifierTypes]
+});
+```
+
+## Styling
+
+This library uses Tailwind CSS for styling. Make sure to include Tailwind CSS in your project:
+
+```bash
+npm install -D tailwindcss
+```
+
+### Tailwind Configuration
+
+Add the library's source files to your Tailwind content configuration:
+
+```js
+// tailwind.config.js
+module.exports = {
+  content: [
+    './src/**/*.{js,jsx,ts,tsx}',
+    './node_modules/@fgv/ts-res-ui-components/**/*.{js,jsx,ts,tsx}'
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+}
+```
+
+### Custom Styling
+
+All components accept a `className` prop for custom styling:
+
+```tsx
+<SourceView 
+  className="my-custom-class"
+  resources={resources}
+/>
+```
+
+## Advanced Usage
+
+### Custom Resource Processing
+
+```tsx
+import { processImportedDirectory, createTsResSystemFromConfig } from '@fgv/ts-res-ui-components';
+
+// Custom processing pipeline
+const customProcessor = async (files: ImportedFile[]) => {
+  // Pre-process files
+  const processedFiles = files.map(transformFile);
+  
+  // Create configuration
+  const config = await createConfigFromFiles(processedFiles);
+  
+  // Create ts-res system
+  const system = await createTsResSystemFromConfig(config);
+  
+  return system;
+};
+```
+
+### Resource Resolution with Custom Context
+
+```tsx
+const { state, actions } = useResourceData();
+
+// Complex context resolution
+const resolveWithComplexContext = async (resourceId: string) => {
+  const context = {
+    language: getUserLanguage(),
+    region: getUserRegion(),
+    theme: getThemePreference(),
+    featureFlags: await getFeatureFlags()
+  };
+  
+  return await actions.resolveResource(resourceId, context);
+};
+```
+
+### Bundle Creation and Export
+
+```tsx
+const { state, actions } = useResourceData();
+
+// Create and export bundle
+const exportBundle = async () => {
+  if (state.processedResources) {
+    const bundleData = {
+      ...state.processedResources.compiledCollection,
+      metadata: {
+        version: '1.0.0',
+        created: new Date().toISOString(),
+        description: 'My resource bundle'
+      }
+    };
+    
+    actions.exportData(bundleData, 'bundle');
+  }
+};
+```
+
+## Error Handling
+
+The library provides comprehensive error handling through the state management system:
+
+```tsx
+<ResourceOrchestrator>
+  {({ state, actions }) => (
+    <div>
+      {state.error && (
+        <div className="bg-red-50 border border-red-200 rounded p-4 mb-4">
+          <h3 className="text-red-800 font-medium">Error</h3>
+          <p className="text-red-600">{state.error}</p>
+          <button 
+            onClick={actions.clearError}
+            className="mt-2 px-3 py-1 bg-red-600 text-white rounded text-sm"
+          >
+            Dismiss
+          </button>
+        </div>
+      )}
+      
+      {/* Rest of your UI */}
+    </div>
+  )}
+</ResourceOrchestrator>
+```
+
+## TypeScript Support
+
+This library is written in TypeScript and provides comprehensive type definitions:
+
+```tsx
+import type {
+  ProcessedResources,
+  FilterState,
+  ResolutionResult,
+  Message,
+  ImportedFile
+} from '@fgv/ts-res-ui-components';
+
+// Type-safe component props
+interface MyComponentProps {
+  resources: ProcessedResources;
+  onMessage: (type: Message['type'], message: string) => void;
+}
+
+const MyComponent: React.FC<MyComponentProps> = ({ resources, onMessage }) => {
+  // Component implementation
+};
+```
+
+## Performance Considerations
+
+- **Lazy Loading**: Components are designed for lazy loading and code splitting
+- **Memoization**: Internal state updates are optimized with React.memo and useMemo
+- **Virtual Scrolling**: Large resource lists use virtual scrolling for performance
+- **Compiled Resources**: Runtime resolution uses pre-compiled structures for efficiency
+
+## Browser Support
+
+- Chrome/Edge: >= 88
+- Firefox: >= 85  
+- Safari: >= 14
+- Modern browsers with ES2020 support
+
+## Development
+
+### Building
+
+```bash
+npm run build
+```
+
+### Testing
+
+```bash
+npm test
+```
+
+### Linting
+
+```bash
+npm run lint
+```
+
+## License
+
+MIT License - see [LICENSE](./LICENSE) file for details.
+
+## Contributing
+
+Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+
+## Support
+
+For questions and support, please:
+
+1. Check the [documentation](https://docs.ts-res.dev)
+2. Search [existing issues](https://github.com/fgv/ts-res/issues)
+3. Create a [new issue](https://github.com/fgv/ts-res/issues/new)

package/lib/components/forms/QualifierEditForm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"QualifierEditForm.d.ts","sourceRoot":"","sources":["../../../src/components/forms/QualifierEditForm.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAgC,MAAM,OAAO,CAAC;AAErD,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEzD,MAAM,WAAW,sBAAsB;IACrC,SAAS,CAAC,EAAE,UAAU,CAAC,cAAc,CAAC;IACtC,cAAc,EAAE,cAAc,CAAC,MAAM,CAAC,0BAA0B,EAAE,CAAC;IACnE,MAAM,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC,cAAc,KAAK,IAAI,CAAC;IACvD,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAWD,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,EAAE,CAAC,sBAAsB,CA6U9D,CAAC"}
+{"version":3,"file":"QualifierEditForm.d.ts","sourceRoot":"","sources":["../../../src/components/forms/QualifierEditForm.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAgC,MAAM,OAAO,CAAC;AAErD,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGzD,MAAM,WAAW,sBAAsB;IACrC,SAAS,CAAC,EAAE,UAAU,CAAC,cAAc,CAAC;IACtC,cAAc,EAAE,cAAc,CAAC,MAAM,CAAC,0BAA0B,EAAE,CAAC;IACnE,MAAM,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC,cAAc,KAAK,IAAI,CAAC;IACvD,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAWD,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,EAAE,CAAC,sBAAsB,CA+W9D,CAAC"}

package/lib/components/forms/QualifierEditForm.js

@@ -1,5 +1,6 @@
 import React, { useState, useCallback } from 'react';
 import { XMarkIcon, InformationCircleIcon } from '@heroicons/react/24/outline';
+import { Converters } from '@fgv/ts-utils';
 export const QualifierEditForm = ({ qualifier, qualifierTypes, onSave, onCancel, existingNames = [] }) => {
     const [formData, setFormData] = useState(() => {
         if (qualifier) {
@@ -24,7 +25,13 @@ export const QualifierEditForm = ({ qualifier, qualifierTypes, onSave, onCancel,
     const [errors, setErrors] = useState({});
     // Get the selected qualifier type for context
     const selectedQualifierType = qualifierTypes.find((qt) => qt.name === formData.typeName);
-    const allowsContextList = selectedQualifierType?.configuration && selectedQualifierType.configuration.allowContextList;
+    // Type-safe extraction of allowContextList property
+    const allowsContextList = (() => {
+        if (!selectedQualifierType?.configuration)
+            return false;
+        const result = Converters.boolean.convert(selectedQualifierType.configuration.allowContextList);
+        return result.isSuccess() ? result.value : false;
+    })();
     // Validation
     const validateForm = useCallback(() => {
         const newErrors = {};
@@ -64,7 +71,9 @@ export const QualifierEditForm = ({ qualifier, qualifierTypes, onSave, onCancel,
             const updated = { ...prev, [field]: value };
             // Auto-generate token from name if no custom token is set
             if (field === 'name' && !prev.token) {
-                updated.token = value.toLowerCase().replace(/[^a-zA-Z0-9]/g, '');
+                updated.token = String(value)
+                    .toLowerCase()
+                    .replace(/[^a-zA-Z0-9]/g, '');
             }
             // Clear tokenIsOptional if token is cleared
             if (field === 'token' && !value) {
@@ -85,7 +94,13 @@ export const QualifierEditForm = ({ qualifier, qualifierTypes, onSave, onCancel,
             case 'territory':
                 return allowsContextList ? 'e.g., US or US,CA' : 'e.g., US';
             case 'literal':
-                const enumValues = selectedQualifierType.configuration?.enumeratedValues;
+                // Type-safe extraction of enumeratedValues
+                const enumValues = (() => {
+                    if (!selectedQualifierType.configuration)
+                        return undefined;
+                    const result = Converters.arrayOf(Converters.string).convert(selectedQualifierType.configuration.enumeratedValues);
+                    return result.isSuccess() ? result.value : undefined;
+                })();
                 if (enumValues && enumValues.length > 0) {
                     return allowsContextList
                         ? `e.g., ${enumValues[0]} or ${enumValues.slice(0, 2).join(',')}`
@@ -157,23 +172,33 @@ export const QualifierEditForm = ({ qualifier, qualifierTypes, onSave, onCancel,
                             ' ',
                             allowsContextList ? 'Yes' : 'No'),
                         selectedQualifierType.systemType === 'literal' && selectedQualifierType.configuration && (React.createElement(React.Fragment, null,
-                            selectedQualifierType.configuration.caseSensitive !== undefined && (React.createElement("p", null,
+                            selectedQualifierType.configuration.caseSensitive !==
+                                undefined && (React.createElement("p", null,
                                 React.createElement("span", { className: "font-medium" }, "Case Sensitive:"),
                                 ' ',
-                                selectedQualifierType.configuration.caseSensitive ? 'Yes' : 'No')),
+                                selectedQualifierType.configuration
+                                    .caseSensitive
+                                    ? 'Yes'
+                                    : 'No')),
                             selectedQualifierType.configuration.enumeratedValues && (React.createElement("p", null,
                                 React.createElement("span", { className: "font-medium" }, "Allowed Values:"),
                                 ' ',
-                                selectedQualifierType.configuration.enumeratedValues.join(', '))))),
+                                selectedQualifierType.configuration
+                                    .enumeratedValues.join(', '))))),
                         selectedQualifierType.systemType === 'territory' && selectedQualifierType.configuration && (React.createElement(React.Fragment, null,
-                            selectedQualifierType.configuration.acceptLowercase !== undefined && (React.createElement("p", null,
+                            selectedQualifierType.configuration.acceptLowercase !==
+                                undefined && (React.createElement("p", null,
                                 React.createElement("span", { className: "font-medium" }, "Accept Lowercase:"),
                                 ' ',
-                                selectedQualifierType.configuration.acceptLowercase ? 'Yes' : 'No')),
+                                selectedQualifierType.configuration
+                                    .acceptLowercase
+                                    ? 'Yes'
+                                    : 'No')),
                             selectedQualifierType.configuration.allowedTerritories && (React.createElement("p", null,
                                 React.createElement("span", { className: "font-medium" }, "Allowed Territories:"),
                                 ' ',
-                                selectedQualifierType.configuration.allowedTerritories.join(', '))))))))),
+                                selectedQualifierType.configuration
+                                    .allowedTerritories.join(', '))))))))),
             React.createElement("div", { className: "flex justify-end space-x-3 px-6 py-4 border-t bg-gray-50 flex-shrink-0" },
                 React.createElement("button", { onClick: onCancel, className: "px-4 py-2 text-sm font-medium text-gray-700 bg-white border border-gray-300 rounded-md hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500" }, "Cancel"),
                 React.createElement("button", { onClick: handleSave, className: "px-4 py-2 text-sm font-medium text-white bg-blue-600 border border-transparent rounded-md hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500" }, qualifier ? 'Save Changes' : 'Add Qualifier')))));