@fgv/ts-res-ui-components 5.0.0-17 → 5.0.0-19

package/README.md

@@ -14,6 +14,7 @@ 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
+- **🔒 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
 - **📁 File Handling**: Support for directory imports, ZIP files via ts-res zip-archive packlet, and bundle loading
@@ -247,9 +248,12 @@ is a generic component used by all of the views, which can also be used to power
       console.log(`Pending ${selection.pendingType} operation`);
     }
   }}
-  defaultView="tree"
-  enableSearch={true}
-  searchPlaceholder="Search resources..."
+  options={{
+    defaultView: "tree",
+    enableSearch: true,
+    searchPlaceholder: "Search resources...",
+    height: "500px"
+  }}
   resourceAnnotations={{
     'user.welcome': { 
       badge: { text: '3', variant: 'info' },
@@ -257,7 +261,6 @@ is a generic component used by all of the views, which can also be used to power
     }
   }}
   pendingResources={pendingChanges}
-  height="500px"
 />
 ```
 
@@ -268,6 +271,36 @@ is a generic component used by all of the views, which can also be used to power
 - **Pending resources**: Show unsaved changes with visual distinction
 - **Branch isolation**: Focus on specific parts of large resource trees
 - **Type safety**: Full TypeScript support with generic resource types
+- **Debug controls**: Optional ResourcePickerOptionsControl for development and debugging
+
+#### ResourcePickerOptionsControl
+
+A debugging/design tool for interactively configuring ResourcePicker behavior. Hidden by default for production use, but can be enabled in development:
+
+```tsx
+// All view components support pickerOptionsPresentation
+<SourceView
+  resources={state.processedResources}
+  pickerOptionsPresentation="collapsible"  // Enable picker options UI
+  onMessage={(type, message) => console.log(`${type}: ${message}`)}
+/>
+
+// Direct usage in custom components
+<PickerTools.ResourcePickerOptionsControl
+  options={pickerOptions}
+  onOptionsChange={setPickerOptions}
+  presentation="popup"  // 'hidden' | 'inline' | 'collapsible' | 'popup' | 'popover'
+  title="Picker Configuration"
+  showAdvanced={true}
+/>
+```
+
+**Presentation modes:**
+- `'hidden'`: Not displayed (default for production)
+- `'inline'`: Always visible with expanded controls
+- `'collapsible'`: Expandable/collapsible section
+- `'popup'`: Full modal dialog overlay
+- `'popover'`: Small dropdown overlay
 
 ### SourceView
 
@@ -278,9 +311,13 @@ Displays the source resource collection with search and navigation capabilities
 ```tsx
 <SourceView
   resources={state.processedResources}
-  selectedResourceId={selectedId}
-  onResourceSelect={(selection) => setSelectedId(selection.resourceId)}
   onExport={actions.exportData}
+  onMessage={(type, message) => console.log(`${type}: ${message}`)}
+  pickerOptions={{
+    defaultView: "list",
+    enableSearch: true,
+    searchPlaceholder: "Search resources..."
+  }}
 />
 ```
 
@@ -297,9 +334,10 @@ Provides filtering capabilities with context value specification and dual-resour
   filterActions={filterActions}
   filterResult={filterResult}
   onFilterResult={setFilterResult}
-  onResourceSelect={(selection) => {
-    setSelectedId(selection.resourceId);
-    // Enhanced callback provides comprehensive selection data
+  onMessage={(type, message) => console.log(`${type}: ${message}`)}
+  pickerOptions={{
+    enableSearch: true,
+    searchPlaceholder: "Search resources..."
   }}
 />
 ```
@@ -316,16 +354,17 @@ Shows the compiled resource structure with detailed candidate information using
   filterResult={filterResult}
   useNormalization={true}
   onExport={(data, type) => exportData(data, type)}
-  onResourceSelect={(selection) => {
-    // Enhanced callback with comprehensive resource data
-    setSelectedId(selection.resourceId);
+  onMessage={(type, message) => console.log(`${type}: ${message}`)}
+  pickerOptions={{
+    defaultView: "tree",
+    enableSearch: true
   }}
 />
 ```
 
 ### 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.
 
 > 📚 **[See ResolutionView documentation →](./docs/ts-res-ui-components.resolutionview.md)**
 
@@ -336,6 +375,12 @@ Interactive resource resolution testing with context management and support for
   resolutionActions={resolutionActions}
   availableQualifiers={availableQualifiers}
   resourceEditorFactory={myResourceEditorFactory}
+  onMessage={(type, message) => console.log(`${type}: ${message}`)}
+  pickerOptions={{
+    defaultView: "list",
+    enableSearch: true,
+    searchPlaceholder: "Search resources for resolution testing..."
+  }}
 />
 ```
 
@@ -398,6 +443,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.