@fgv/ts-res-ui-components 5.0.0-18 → 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
@@ -363,7 +364,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.
 
 > 📚 **[See ResolutionView documentation →](./docs/ts-res-ui-components.resolutionview.md)**
 
@@ -442,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.

package/dist/ts-res-ui-components.d.ts

@@ -274,15 +274,15 @@ declare interface ConfigurationState {
 }
 
 /**
- * Predefined configuration templates
+ * Configuration template using predefined configurations from ts-res
  * @internal
  */
 declare interface ConfigurationTemplate {
-    id: string;
+    id: Config.PredefinedSystemConfiguration;
     name: string;
     description: string;
     configuration: Config.Model.ISystemConfiguration;
-    category: 'basic' | 'intermediate' | 'advanced' | 'enterprise';
+    category: 'basic' | 'intermediate' | 'advanced';
 }
 
 export declare namespace ConfigurationTools {
@@ -518,7 +518,7 @@ declare function createSimpleContext(qualifiers: Qualifiers.IReadOnlyQualifierCo
  * Create ts-res system from configuration
  */
 /** @internal */
-declare function createTsResSystemFromConfig(systemConfig?: Config.Model.ISystemConfiguration): Result<{
+declare function createTsResSystemFromConfig(systemConfig?: Config.Model.ISystemConfiguration, qualifierTypeFactory?: Config.IConfigInitFactory<QualifierTypes.Config.IAnyQualifierTypeConfig, QualifierTypes.QualifierType>, resourceTypeFactory?: Config.IConfigInitFactory<ResourceTypes.Config.IResourceTypeConfig, ResourceTypes.ResourceType>): Result<{
     qualifierTypes: QualifierTypes.ReadOnlyQualifierTypeCollector;
     qualifiers: Qualifiers.IReadOnlyQualifierCollector;
     resourceTypes: ResourceTypes.ReadOnlyResourceTypeCollector;
@@ -1336,6 +1336,8 @@ declare interface FilterViewProps extends ViewBaseProps {
     onFilterResult?: (result: FilterResult | null) => void;
     /** Optional configuration for the ResourcePicker behavior */
     pickerOptions?: ResourcePickerOptions;
+    /** Optional configuration for context control behavior */
+    contextOptions?: ResolutionContextOptions;
 }
 
 /**
@@ -2314,7 +2316,7 @@ declare interface ProcessedResources {
  * Process imported directory using the ts-res system
  */
 /** @internal */
-declare function processImportedDirectory(directory: ImportedDirectory, systemConfig?: Config.Model.ISystemConfiguration): Result<{
+declare function processImportedDirectory(directory: ImportedDirectory, systemConfig?: Config.Model.ISystemConfiguration, qualifierTypeFactory?: Config.IConfigInitFactory<QualifierTypes.Config.IAnyQualifierTypeConfig, QualifierTypes.QualifierType>, resourceTypeFactory?: Config.IConfigInitFactory<ResourceTypes.Config.IResourceTypeConfig, ResourceTypes.ResourceType>): Result<{
     system: {
         qualifierTypes: QualifierTypes.ReadOnlyQualifierTypeCollector;
         qualifiers: Qualifiers.IReadOnlyQualifierCollector;
@@ -2338,7 +2340,7 @@ declare function processImportedDirectory(directory: ImportedDirectory, systemCo
  * Process imported files using the ts-res system
  */
 /** @internal */
-declare function processImportedFiles(files: ImportedFile[], systemConfig?: Config.Model.ISystemConfiguration): Result<{
+declare function processImportedFiles(files: ImportedFile[], systemConfig?: Config.Model.ISystemConfiguration, qualifierTypeFactory?: Config.IConfigInitFactory<QualifierTypes.Config.IAnyQualifierTypeConfig, QualifierTypes.QualifierType>, resourceTypeFactory?: Config.IConfigInitFactory<ResourceTypes.Config.IResourceTypeConfig, ResourceTypes.ResourceType>): Result<{
     system: {
         qualifierTypes: QualifierTypes.ReadOnlyQualifierTypeCollector;
         qualifiers: Qualifiers.IReadOnlyQualifierCollector;
@@ -2436,6 +2438,62 @@ declare function processZipResources(files: ImportedFile[], directory: ImportedD
  * }
  * ```
  *
+ * @example
+ * ```tsx
+ * // Using with host-managed values and custom options
+ * import { ResolutionTools } from '@fgv/ts-res-ui-components';
+ *
+ * function HostControlledQualifier() {
+ *   return (
+ *     <ResolutionTools.QualifierContextControl
+ *       qualifierName="platform"
+ *       value={undefined} // Ignored when hostValue is set
+ *       onChange={() => {}} // Called only when editable
+ *       options={{
+ *         editable: false,
+ *         hostValue: 'web',
+ *         showHostValue: true,
+ *         placeholder: 'Platform controlled by application',
+ *         className: 'border-blue-300'
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Using for selective visibility and editability
+ * function ConditionalQualifierControls() {
+ *   const [userRole, setUserRole] = useState<'admin' | 'user'>('user');
+ *
+ *   return (
+ *     <div>
+ *       <ResolutionTools.QualifierContextControl
+ *         qualifierName="environment"
+ *         value={envValue}
+ *         onChange={handleEnvChange}
+ *         options={{
+ *           visible: userRole === 'admin', // Only visible to admins
+ *           editable: true,
+ *           placeholder: 'Select environment...'
+ *         }}
+ *       />
+ *       <ResolutionTools.QualifierContextControl
+ *         qualifierName="language"
+ *         value={langValue}
+ *         onChange={handleLangChange}
+ *         options={{
+ *           visible: true,
+ *           editable: userRole === 'admin', // Only editable by admins
+ *           placeholder: userRole === 'admin' ? 'Select language...' : 'Language locked'
+ *         }}
+ *       />
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
  * @public
  */
 declare const QualifierContextControl: React_2.FC<QualifierContextControlProps>;
@@ -2460,6 +2518,44 @@ declare interface QualifierContextControlProps {
     resources?: ProcessedResources | null;
     /** Optional CSS classes to apply to the control */
     className?: string;
+    /** Extended options for controlling the qualifier behavior */
+    options?: QualifierControlOptions;
+}
+
+/**
+ * Options for controlling individual qualifier context controls.
+ *
+ * Provides fine-grained control over the behavior, appearance, and editability
+ * of individual qualifier inputs. This allows hosts to customize which qualifiers
+ * are editable, provide external values, and control the presentation.
+ *
+ * @example
+ * ```tsx
+ * // Make a qualifier readonly with external value
+ * const languageOptions: QualifierControlOptions = {
+ *   visible: true,
+ *   editable: false,
+ *   hostValue: 'en-US',
+ *   showHostValue: true,
+ *   placeholder: 'Language managed externally'
+ * };
+ * ```
+ *
+ * @public
+ */
+declare interface QualifierControlOptions {
+    /** Whether this qualifier should be visible at all */
+    visible?: boolean;
+    /** Whether this qualifier is editable by the user */
+    editable?: boolean;
+    /** External/host-managed value that overrides user input */
+    hostValue?: string | undefined;
+    /** Whether to show host-managed values in the display */
+    showHostValue?: boolean;
+    /** Custom placeholder text for this qualifier */
+    placeholder?: string;
+    /** Custom CSS classes for this qualifier control */
+    className?: string;
 }
 
 /**
@@ -2726,6 +2822,120 @@ declare interface ResolutionActions {
     discardEdits: () => void;
 }
 
+/**
+ * Configuration options for the resolution context controls in ResolutionView.
+ *
+ * Controls the visibility and behavior of the context configuration panel,
+ * allowing hosts to customize which qualifiers are editable and provide
+ * externally managed context values. Uses QualifierControlOptions for
+ * per-qualifier customization.
+ *
+ * @example
+ * ```tsx
+ * // Hide context UI entirely - host controls context externally
+ * <ResolutionView
+ *   contextOptions={{ showContextControls: false }}
+ *   // ... other props
+ * />
+ *
+ * // Fine-grained qualifier control
+ * <ResolutionView
+ *   contextOptions={{
+ *     showContextControls: true,
+ *     qualifierOptions: {
+ *       language: { editable: true, placeholder: 'Select language...' },
+ *       platform: { editable: false, hostValue: 'web', showHostValue: true },
+ *       env: { visible: false } // Hidden from UI entirely
+ *     },
+ *     hostManagedValues: { env: 'production' } // Invisible but active
+ *   }}
+ *   // ... other props
+ * />
+ * ```
+ *
+ * @public
+ */
+declare interface ResolutionContextOptions {
+    /** Visibility options */
+    /** Whether to show the context configuration panel at all */
+    showContextControls?: boolean;
+    /** Whether to show the current context display */
+    showCurrentContext?: boolean;
+    /** Whether to show the Apply/Reset buttons */
+    showContextActions?: boolean;
+    /** Per-qualifier control options */
+    qualifierOptions?: Record<string, QualifierControlOptions>;
+    /** Global defaults for qualifiers not specifically configured */
+    defaultQualifierEditable?: boolean;
+    defaultQualifierVisible?: boolean;
+    /** Host-managed values that override all user input for invisible qualifiers */
+    hostManagedValues?: Record<string, string | undefined>;
+    /** Appearance options */
+    /** Custom title for the context configuration panel */
+    contextPanelTitle?: string;
+    /** Global placeholder text pattern for qualifier inputs */
+    globalPlaceholder?: string | ((qualifierName: string) => string);
+    /** Additional CSS classes for the context panel */
+    contextPanelClassName?: string;
+}
+
+/**
+ * Reusable control for configuring ResolutionView context options.
+ *
+ * Provides a clean interface for adjusting context behavior including:
+ * - Visibility of context controls, current context display, and action buttons
+ * - Per-qualifier options (visibility, editability, host values)
+ * - Global defaults and appearance customization
+ *
+ * Can be rendered in multiple presentation modes:
+ * - 'hidden': Not displayed (default for production)
+ * - 'inline': Always expanded with full controls visible
+ * - 'collapsible': Expandable/collapsible section
+ * - 'popover': Small dropdown overlay
+ * - 'popup': Full modal dialog
+ *
+ * @example
+ * ```tsx
+ * import { ResolutionContextOptionsControl } from '@fgv/ts-res-ui-components';
+ *
+ * function ContextConfiguration() {
+ *   const [contextOptions, setContextOptions] = useState<ResolutionContextOptions>({});
+ *
+ *   return (
+ *     <ResolutionContextOptionsControl
+ *       options={contextOptions}
+ *       onOptionsChange={setContextOptions}
+ *       availableQualifiers={['language', 'platform', 'env']}
+ *       presentation="collapsible"
+ *       title="Context Configuration"
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @public
+ */
+declare const ResolutionContextOptionsControl: React_2.FC<ResolutionContextOptionsControlProps>;
+
+/**
+ * Props for the ResolutionContextOptionsControl component.
+ * @public
+ */
+declare interface ResolutionContextOptionsControlProps {
+    /** Current context options */
+    options: ResolutionContextOptions;
+    /** Callback when options change */
+    onOptionsChange: (options: ResolutionContextOptions) => void;
+    /** Available qualifiers for configuration */
+    availableQualifiers?: string[];
+    /** How to present the options control (default: 'hidden' for production use) */
+    presentation?: 'hidden' | 'inline' | 'collapsible' | 'popup' | 'popover';
+    /** Custom class name */
+    className?: string;
+    /** Title for the control section */
+    title?: string;
+}
+
 /**
  * Control panel for managing pending resource edits during resolution testing.
  *
@@ -3122,6 +3332,7 @@ export declare namespace ResolutionTools {
         EditableJsonView,
         ResolutionEditControls,
         QualifierContextControl,
+        ResolutionContextOptionsControl,
         useResolutionState,
         createResolverWithContext,
         evaluateConditionsForCandidate,
@@ -3136,7 +3347,10 @@ export declare namespace ResolutionTools {
         CandidateInfo,
         ConditionEvaluationResult,
         EditedResourceInfo,
-        EditableJsonViewProps
+        ResolutionContextOptions,
+        QualifierControlOptions,
+        EditableJsonViewProps,
+        ResolutionContextOptionsControlProps
     }
 }
 
@@ -3214,6 +3428,17 @@ declare interface ResolutionViewProps extends ViewBaseProps {
     resourceEditorFactory?: ResourceEditorFactory;
     /** Optional configuration for the ResourcePicker behavior */
     pickerOptions?: ResourcePickerOptions;
+    /** Optional configuration for the resolution context controls */
+    contextOptions?: ResolutionContextOptions;
+    /** Lock to a single view state and suppress the view state selector */
+    lockedViewMode?: 'composed' | 'best' | 'all' | 'raw';
+    /** Custom titles for the main sections */
+    sectionTitles?: {
+        /** Title for the resources picker section (default: "Resources") */
+        resources?: string;
+        /** Title for the results section (default: "Results") */
+        results?: string;
+    };
 }
 
 /**
@@ -3679,6 +3904,10 @@ declare interface ResourceOrchestratorProps {
     }) => ReactNode;
     /** Optional initial configuration to apply on mount */
     initialConfiguration?: Config.Model.ISystemConfiguration;
+    /** Optional qualifier type factory for creating custom qualifier types */
+    qualifierTypeFactory?: Config.IConfigInitFactory<QualifierTypes.Config.IAnyQualifierTypeConfig, QualifierTypes.QualifierType>;
+    /** Optional resource type factory for creating custom resource types */
+    resourceTypeFactory?: Config.IConfigInitFactory<ResourceTypes.Config.IResourceTypeConfig, ResourceTypes.ResourceType>;
     /** Callback fired when orchestrator state changes */
     onStateChange?: (state: Partial<OrchestratorState>) => void;
 }
@@ -4637,7 +4866,20 @@ declare interface UseResolutionStateReturn {
  *
  * @public
  */
-declare function useResourceData(): UseResourceDataReturn;
+declare function useResourceData(params?: UseResourceDataParams): UseResourceDataReturn;
+
+/**
+ * Parameters for the useResourceData hook.
+ * Allows customization of type factories for extended functionality.
+ *
+ * @public
+ */
+declare interface UseResourceDataParams {
+    /** Optional qualifier type factory for creating custom qualifier types */
+    qualifierTypeFactory?: Config.IConfigInitFactory<QualifierTypes.Config.IAnyQualifierTypeConfig, QualifierTypes.QualifierType>;
+    /** Optional resource type factory for creating custom resource types */
+    resourceTypeFactory?: Config.IConfigInitFactory<ResourceTypes.Config.IResourceTypeConfig, ResourceTypes.ResourceType>;
+}
 
 /**
  * Return type for the useResourceData hook.