@fgv/ts-res-ui-components 5.0.0-18 → 5.0.0-20

package/README.md

@@ -14,8 +14,11 @@ This packlet is largely AI written, and it shows.
 - **🔄 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
+- **➕ Resource Creation**: Create new resources with pending/apply workflow and template support
+- **🔒 View Mode Locking**: Lock to single view mode for simplified interfaces
 - **📊 Visualization**: Multiple views for exploring resource structures and compiled output
 - **⚙️ Configuration**: Visual configuration management for qualifier types, qualifiers, and resource types
+- **🎛️ Host Control**: Programmatic control of qualifier values and resource types
 - **📁 File Handling**: Support for directory imports, ZIP files via ts-res zip-archive packlet, and bundle loading
 - **🎨 Modern UI**: Built with Tailwind CSS and Heroicons for a clean, responsive interface
 
@@ -363,7 +366,7 @@ Shows the compiled resource structure with detailed candidate information using
 
 ### ResolutionView
 
-Interactive resource resolution testing with context management and support for custom resource editors via the ResourceEditorFactory pattern.
+Interactive resource resolution testing with context management and support for custom resource editors via the ResourceEditorFactory pattern. Supports locking to a single view mode to simplify the interface for specific use cases. Now includes host-controlled resolution support for programmatic qualifier value management and the ability to create new resources with a pending/apply workflow.
 
 > 📚 **[See ResolutionView documentation →](./docs/ts-res-ui-components.resolutionview.md)**
 
@@ -380,9 +383,144 @@ Interactive resource resolution testing with context management and support for
     enableSearch: true,
     searchPlaceholder: "Search resources for resolution testing..."
   }}
+  // Optional: Host-controlled resolution
+  contextOptions={{
+    hostManagedValues: {
+      language: 'en-US',
+      platform: 'web',
+      market: 'eastern-europe'
+    },
+    showContextControls: true  // Can hide controls for host-only resolution
+  }}
+  // Optional: Resource creation with pending/apply workflow
+  allowResourceCreation={true}
+  defaultResourceType="json"  // Optional: Host-controlled resource type
+  showPendingResourcesInList={true}  // Show pending resources in the picker (default: true)
+  onPendingResourcesApplied={(added, deleted) => {
+    console.log(`Applied ${added.length} new resources, ${deleted.length} deletions`);
+  }}
+/>
+```
+
+#### Host-Controlled Resolution
+
+The ResolutionView now supports a three-layer context system that allows host applications to programmatically control qualifier values while still allowing user interaction:
+
+1. **Host-Managed Values**: Values controlled by the host application that are applied automatically
+2. **Applied User Values**: User values that have been explicitly applied via the "Apply Changes" button
+3. **Pending User Values**: User edits that haven't been applied yet
+
+This is particularly useful when:
+- The UI needs to be hidden but resolution still needs to work
+- Certain qualifier values should be controlled by the application logic
+- You want to provide default values that users can optionally override
+
+```tsx
+// Example: Host-controlled resolution with hidden UI
+<ResolutionView
+  resources={state.processedResources}
+  resolutionState={resolutionState}
+  resolutionActions={resolutionActions}
+  availableQualifiers={['language', 'platform', 'market']}
+  contextOptions={{
+    hostManagedValues: {
+      language: userProfile.language,
+      platform: detectPlatform(),
+      market: userProfile.region
+    },
+    showContextControls: false,  // Hide the context controls
+    qualifierOptions: {
+      language: { visible: false },  // Hide specific qualifiers
+      platform: { visible: false }
+    }
+  }}
+/>
+
+// Example: Mixed host and user control
+<ResolutionView
+  resources={state.processedResources}
+  resolutionState={resolutionState}
+  resolutionActions={resolutionActions}
+  availableQualifiers={availableQualifiers}
+  contextOptions={{
+    hostManagedValues: {
+      platform: 'web'  // Platform is always controlled by host
+    },
+    qualifierOptions: {
+      platform: { 
+        visible: true,
+        hostValue: 'web',  // Shows as read-only in UI
+        disabled: true
+      }
+    }
+  }}
+/>
+```
+
+**Key features of host-controlled resolution:**
+- Host values are applied automatically when they change
+- User values require explicit "Apply Changes" action
+- Host values override user values when both are set
+- Flexible UI control - can hide all controls, specific qualifiers, or show as read-only
+- Works seamlessly with the existing resolution state management
+
+#### Resource Creation
+
+ResolutionView now supports creating new resources directly in the UI with a pending/apply workflow similar to context management:
+
+```tsx
+// Basic resource creation - user selects resource type
+<ResolutionView
+  resources={state.processedResources}
+  resolutionState={resolutionState}
+  resolutionActions={resolutionActions}
+  allowResourceCreation={true}
+  onPendingResourcesApplied={(added, deleted) => {
+    // Rebuild resource manager with new resources
+    const updatedResources = rebuildWithResources(added, deleted);
+    setState({ processedResources: updatedResources });
+  }}
+/>
+
+// Host-controlled resource type
+<ResolutionView
+  resources={state.processedResources}
+  resolutionState={resolutionState}
+  resolutionActions={resolutionActions}
+  allowResourceCreation={true}
+  defaultResourceType="json"  // Type selector hidden, always creates JSON resources
+  onPendingResourcesApplied={(added, deleted) => {
+    console.log(`Applied ${added.length} additions, ${deleted.length} deletions`);
+  }}
+/>
+
+// With custom resource types
+<ResolutionView
+  resources={state.processedResources}
+  resolutionState={resolutionState}
+  resolutionActions={resolutionActions}
+  allowResourceCreation={true}
+  resourceTypeFactory={[customType1, customType2]}  // Provide custom resource types
+  showPendingResourcesInList={true}  // Show pending resources with visual distinction
 />
 ```
 
+**Unified Change Workflow (Edits, Additions, Deletions):**
+1. Click "Add Resource" in the picker header to create new resources (if enabled)
+2. Edit existing resources from the results pane using the JSON or custom editors
+3. Mark resources for deletion where supported
+4. All changes appear in a single "Pending Changes" bar with counts (edits/additions/deletions)
+5. Click "Apply Changes" to commit everything in one atomic rebuild
+6. Or click "Discard Changes" to remove all pending changes
+
+**Key features:**
+- **Template-based creation**: Resource types provide default templates for new resources
+- **Pending workflow**: Resources aren't added immediately, allowing review before applying
+- **Host control**: Can specify a default resource type to hide the type selector
+- **Batch operations**: Create multiple resources before applying
+- **Visual feedback**: Pending resources shown with distinct styling
+- **Validation**: Resource IDs are validated for uniqueness
+
 #### Custom Resource Editors
 
 The ResolutionView supports custom editors for specific resource types through the `ResourceEditorFactory` interface:
@@ -442,6 +580,271 @@ const editorFactory = new MyResourceEditorFactory();
 - **Extensible**: Easy to add new editors for new resource types
 - **Error Handling**: Factory failures are caught and reported to users
 
+#### Context Control Extensibility
+
+ResolutionView provides comprehensive control over the context configuration UI, allowing hosts to customize which qualifiers are editable, provide external values, and control the presentation. This is especially useful for applications that need to drive context externally or provide selective user control.
+
+**Hide Context UI Entirely (Host-Driven Context):**
+```tsx
+<ResolutionView
+  resources={processedResources}
+  resolutionState={resolutionState}
+  resolutionActions={resolutionActions}
+  contextOptions={{
+    showContextControls: false  // Hide all context UI
+  }}
+/>
+```
+
+**Lock to Single View Mode:**
+```tsx
+<ResolutionView
+  resources={processedResources}
+  resolutionState={resolutionState}
+  resolutionActions={resolutionActions}
+  lockedViewMode="composed"  // Lock to composed view, hide view selector
+/>
+```
+
+**Lock to Best View Mode:**
+```tsx
+<ResolutionView
+  resources={processedResources}
+  resolutionState={resolutionState}
+  resolutionActions={resolutionActions}
+  lockedViewMode="best"  // Lock to best view, hide view selector
+/>
+```
+
+**Custom Section Titles:**
+```tsx
+<ResolutionView
+  resources={processedResources}
+  resolutionState={resolutionState}
+  resolutionActions={resolutionActions}
+  sectionTitles={{
+    resources: "Available Items",  // Custom title for resources picker
+    results: "Resolution Output"   // Custom title for results section
+  }}
+/>
+```
+
+**Fine-Grained Qualifier Control:**
+```tsx
+<ResolutionView
+  resources={processedResources}
+  resolutionState={resolutionState}
+  resolutionActions={resolutionActions}
+  contextOptions={{
+    // Panel visibility control
+    showContextControls: true,
+    showCurrentContext: true,
+    showContextActions: true,
+    
+    // Per-qualifier configuration
+    qualifierOptions: {
+      language: { 
+        editable: true, 
+        placeholder: "Select language..." 
+      },
+      platform: { 
+        editable: false, 
+        hostValue: "web", 
+        showHostValue: true 
+      },
+      environment: { 
+        visible: false  // Hidden from UI entirely
+      }
+    },
+    
+    // Host-managed values (invisible but active in context)
+    hostManagedValues: { 
+      environment: "production",
+      deployment: "us-east-1"
+    },
+    
+    // Appearance customization
+    contextPanelTitle: "Resolution Context",
+    globalPlaceholder: "Enter {qualifierName}..."
+  }}
+/>
+```
+
+**Visual Indicators:**
+- **🔵 Blue border + light blue background** - Host-managed qualifiers have subtle visual styling
+- **🖱️ Hover tooltip** - "Host-managed value - controlled externally" appears on hover
+- **🎯 Actual values displayed** - Shows real host values instead of generic "Disabled" text
+- **📋 Current context** - Displays combined user + host-managed values
+
+**Development & Debug Controls:**
+Enable the context options gear icon during development for interactive configuration:
+
+```tsx
+<ResolutionView
+  resources={processedResources}
+  pickerOptionsPresentation="collapsible"  // Shows both picker & context gear icons
+  resolutionState={resolutionState}
+  resolutionActions={resolutionActions}
+/>
+```
+
+The gear icon provides a live configuration interface for:
+- **Context Panel Visibility** - Show/hide controls, current context display, action buttons
+- **Global Defaults** - Set default visibility and editability for all qualifiers
+- **Per-Qualifier Settings** - Configure visibility, editability, host values, and custom placeholders
+- **Host-Managed Values** - Set external values that override user input
+
+This extensibility is perfect for:
+- **Embedded applications** where the host drives context from sidebar controls
+- **Guided workflows** where only specific qualifiers should be user-editable
+- **Multi-tenant applications** where some context is determined by tenant configuration
+- **Progressive disclosure** where advanced qualifiers are hidden from basic users
+
+### FilterView
+
+Provides context-based resource filtering with candidate count analysis and export functionality.
+
+> 📚 **[See FilterView documentation →](./docs/ts-res-ui-components.filterview.md)**
+
+```tsx
+import { FilterView, ResourceTools } from '@fgv/ts-res-ui-components';
+
+function MyFilterTool() {
+  const { state, actions } = ResourceTools.useResourceData();
+
+  return (
+    <FilterView
+      resources={state.resources}
+      filterState={state.filterState}
+      filterActions={{
+        updateFilterEnabled: (enabled) => actions.updateFilterState({ enabled }),
+        updateFilterValues: (values) => actions.updateFilterState({ values }),
+        applyFilterValues: () => actions.applyFilter(),
+        resetFilterValues: () => actions.resetFilter(),
+        updateReduceQualifiers: (reduce) => actions.updateFilterState({ reduceQualifiers: reduce })
+      }}
+      filterResult={state.filterResult}
+      onMessage={(type, message) => console.log(`${type}: ${message}`)}
+    />
+  );
+}
+```
+
+#### FilterView Context Control Extensibility
+
+FilterView provides the same comprehensive context control features as ResolutionView, allowing hosts to customize which qualifiers are editable for filtering, provide external values, and control the presentation. This is especially useful for filtering applications that need to drive filter context externally or provide selective user control.
+
+**Hide Context UI Entirely (Host-Driven Filtering):**
+```tsx
+<FilterView
+  resources={processedResources}
+  filterState={filterState}
+  filterActions={filterActions}
+  filterResult={filterResult}
+  contextOptions={{
+    showContextControls: false  // Hide all context filter controls
+  }}
+/>
+```
+
+**Fine-Grained Filter Context Control:**
+```tsx
+<FilterView
+  resources={processedResources}
+  filterState={filterState}
+  filterActions={filterActions}
+  filterResult={filterResult}
+  contextOptions={{
+    // Panel appearance
+    contextPanelTitle: "Filter Criteria",
+    globalPlaceholder: "Filter by {qualifierName}...",
+    
+    // Per-qualifier configuration
+    qualifierOptions: {
+      language: { 
+        editable: true, 
+        placeholder: "Filter by language..." 
+      },
+      platform: { 
+        editable: false, 
+        hostValue: "web", 
+        showHostValue: true 
+      },
+      environment: { 
+        visible: false  // Hidden from filter UI entirely
+      }
+    },
+    
+    // Host-managed filter values (invisible but active in filter context)
+    hostManagedValues: { 
+      environment: "production",
+      deployment: "us-east-1"
+    },
+    
+    // UI visibility control
+    showCurrentContext: true,  // Show pending/applied filter summary
+    showContextActions: true   // Show filter reset/apply buttons
+  }}
+/>
+```
+
+**Combined with External Filter Logic:**
+```tsx
+function SmartFilterView() {
+  const [externalContext, setExternalContext] = useState({
+    userRole: 'admin',
+    tenant: 'enterprise'
+  });
+
+  return (
+    <FilterView
+      resources={processedResources}
+      filterState={filterState}
+      filterActions={filterActions}
+      contextOptions={{
+        contextPanelTitle: "Available Filters",
+        qualifierOptions: {
+          // Hide sensitive qualifiers from basic users
+          environment: { 
+            visible: externalContext.userRole === 'admin' 
+          },
+          // Lock tenant-specific qualifiers
+          tenant: { 
+            editable: false,
+            hostValue: externalContext.tenant
+          }
+        }
+      }}
+    />
+  );
+}
+```
+
+**Development & Debug Controls:**
+Enable the context options gear icon during development for interactive filter configuration:
+
+```tsx
+<FilterView
+  resources={processedResources}
+  pickerOptionsPresentation="collapsible"  // Shows both picker & context gear icons
+  filterState={filterState}
+  filterActions={filterActions}
+/>
+```
+
+The gear icon provides a live configuration interface for:
+- **Context Panel Visibility** - Show/hide filter controls, current context display, action buttons
+- **Global Defaults** - Set default visibility and editability for all filter qualifiers
+- **Per-Qualifier Settings** - Configure visibility, editability, host values, and custom placeholders
+- **Host-Managed Values** - Set external filter values that override user input
+
+This filter extensibility is perfect for:
+- **Dashboard applications** where filters are driven from external controls
+- **Multi-tenant systems** where filter options vary by tenant or user role
+- **Guided filter workflows** where only specific criteria should be user-selectable
+- **Advanced/basic user modes** where filter complexity adapts to user expertise
+- **Integration scenarios** where filter context comes from external systems
+
 ### MessagesWindow
 
 Displays and manages application messages with filtering, search, and copy functionality. Perfect for debugging interfaces and development tools where message visibility is critical.

package/config/jest.setup.js

@@ -50,6 +50,9 @@ global.URL = {
   revokeObjectURL: jest.fn()
 };
 
+// Extend jest matchers (toBeInTheDocument, etc.)
+require('@testing-library/jest-dom');
+
 // Mock document methods for file export
 global.document = {
   createElement: jest.fn(() => ({