@ticatec/uniface-flexi-module 0.0.2

package/FLEXICRITERIASET_GUIDE.md

@@ -0,0 +1,1559 @@
+# FlexiCriteriaSet Complete Usage Guide
+
+A comprehensive guide to using FlexiCriteriaSet for building dynamic search and filtering panels in Svelte applications.
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Basic Usage](#basic-usage)
+3. [Schema Structure](#schema-structure)
+4. [Criteria Field Types](#criteria-field-types)
+5. [Advanced Search Patterns](#advanced-search-patterns)
+6. [Dynamic Criteria Generation](#dynamic-criteria-generation)
+7. [Events and Interactions](#events-and-interactions)
+8. [Extending FlexiCriteriaSet](#extending-flexicriteriaset)
+9. [Integration Patterns](#integration-patterns)
+10. [Best Practices](#best-practices)
+
+## Overview
+
+FlexiCriteriaSet is a powerful search criteria builder that allows users to construct complex search queries through an intuitive interface. It supports various field types, operators, and provides extensible architecture for custom search components.
+
+### Key Features
+
+- **Flexible Search Fields**: Support for text, number, date, select, and range searches
+- **Dynamic Operators**: Context-aware operators for different field types
+- **Schema-Based Configuration**: JSON-driven criteria panel setup
+- **Extensible Architecture**: Custom field types and search logic
+- **Type Safety**: Full TypeScript support
+- **Real-time Updates**: Immediate search criteria generation
+
+## Basic Usage
+
+### 1. Installation and Setup
+
+```typescript
+import CriteriaPanel, { FlexiCriteriaSet } from '@ticatec/uniface-flexi-form/criteria-panel';
+import '@ticatec/uniface-flexi-form/uniface-flexi-form.css';
+```
+
+### 2. Simple Criteria Panel
+
+```svelte
+<!-- SimpleCriteriaPanel.svelte -->
+<script lang="ts">
+  import CriteriaPanel from '@ticatec/uniface-flexi-form/criteria-panel';
+  
+  // Search criteria data
+  let searchCriteria = {};
+  
+  // Criteria panel schema
+  const userSearchSchema = {
+    arrangement: 'vertical',
+    variant: 'outlined',
+    fields: [
+      {
+        type: 'text-search',
+        name: 'userName',
+        label: 'User Name',
+        keys: { field: 'userName' },
+        size: 'x25',
+        props: {
+          placeholder: 'Enter user name'
+        }
+      },
+      {
+        type: 'option-select-search',
+        name: 'status',
+        label: 'Status',
+        keys: { field: 'status' },
+        dictName: 'user-status',
+        size: 'x20',
+        props: {
+          placeholder: 'Select status'
+        }
+      },
+      {
+        type: 'date-range',
+        name: 'registrationDate',
+        label: 'Registration Date',
+        keys: { 
+          fromField: 'registeredFrom', 
+          toField: 'registeredTo' 
+        },
+        size: 'x30'
+      },
+      {
+        type: 'number-range',
+        name: 'ageRange',
+        label: 'Age Range',
+        keys: { 
+          minField: 'ageMin', 
+          maxField: 'ageMax' 
+        },
+        size: 'x25'
+      }
+    ]
+  };
+  
+  function handleCriteriaChange(event) {
+    searchCriteria = event.detail.criteria;
+    console.log('Search criteria updated:', searchCriteria);
+    performSearch(searchCriteria);
+  }
+  
+  function handleSearch(event) {
+    const criteria = event.detail.criteria;
+    console.log('Search triggered with criteria:', criteria);
+    executeSearch(criteria);
+  }
+  
+  function handleReset() {
+    searchCriteria = {};
+    console.log('Search criteria reset');
+  }
+  
+  async function performSearch(criteria) {
+    // Implement your search logic
+    try {
+      const results = await searchAPI(criteria);
+      console.log('Search results:', results);
+    } catch (error) {
+      console.error('Search failed:', error);
+    }
+  }
+</script>
+
+<div class="search-panel">
+  <h3>User Search</h3>
+  <CriteriaPanel 
+    schema={userSearchSchema}
+    bind:criteria={searchCriteria}
+    on:change={handleCriteriaChange}
+    on:search={handleSearch}
+    on:reset={handleReset}
+  />
+</div>
+
+<style>
+  .search-panel {
+    padding: 16px;
+    border: 1px solid #ddd;
+    border-radius: 8px;
+  }
+</style>
+```
+
+## Schema Structure
+
+### FlexiCriteriaSetSchema
+
+```typescript
+interface FlexiCriteriaSetSchema {
+  class?: string;                    // CSS class for styling
+  variant?: 'outlined' | 'filled';  // Field variant
+  arrangement?: 'vertical' | 'horizontal'; // Layout direction
+  label$style?: string;              // Label styling
+  fields: Array<FlexiCriteriaFieldSchema>; // Search fields
+}
+```
+
+### FlexiCriteriaFieldSchema
+
+```typescript
+interface FlexiCriteriaFieldSchema {
+  type: string;                      // Field type identifier
+  name?: string;                     // Field name
+  label: string;                     // Display label
+  keys: { [key: string]: string };  // Data binding keys
+  dictName?: string;                 // Dictionary for options
+  visible?: boolean;                 // Field visibility
+  size?: 'x15' | 'x20' | 'x25' | 'x30' | 'x35' | 'x40'; // Field width
+  events?: Record<string, string>;   // Event handlers
+  props?: any;                       // Field-specific properties
+}
+```
+
+## Criteria Field Types
+
+### Built-in Field Types
+
+| Type | Description | Keys Required | Common Props |
+|------|-------------|---------------|--------------|
+| `text-search` | Text search field | `field` | `placeholder`, `operators` |
+| `number-search` | Numeric search field | `field` | `min`, `max`, `operators` |
+| `number-range` | Number range search | `minField`, `maxField` | `min`, `max`, `step` |
+| `date-search` | Date search field | `field` | `min`, `max`, `format` |
+| `date-range` | Date range search | `fromField`, `toField` | `min`, `max`, `format` |
+| `datetime-search` | DateTime search | `field` | `min`, `max`, `format` |
+| `option-select-search` | Single select search | `field` | `dictName`, `placeholder` |
+| `option-multi-select-search` | Multi-select search | `field` | `dictName`, `maxSelections` |
+| `input-option-select-search` | Searchable select | `field` | `getOptions`, `minLength` |
+| `cascade-select-search` | Cascade select search | `field` | `dictName`, `levels` |
+
+### Field Examples
+
+```typescript
+// Text search with operators
+{
+  type: 'text-search',
+  name: 'productName',
+  label: 'Product Name',
+  keys: { field: 'name' },
+  size: 'x30',
+  props: {
+    placeholder: 'Enter product name',
+    operators: ['contains', 'startsWith', 'endsWith', 'equals']
+  }
+}
+
+// Number range search
+{
+  type: 'number-range',
+  name: 'priceRange',
+  label: 'Price Range',
+  keys: { 
+    minField: 'priceMin', 
+    maxField: 'priceMax' 
+  },
+  size: 'x25',
+  props: {
+    min: 0,
+    max: 10000,
+    step: 10,
+    currency: 'USD'
+  }
+}
+
+// Date range with constraints
+{
+  type: 'date-range',
+  name: 'orderDate',
+  label: 'Order Date',
+  keys: { 
+    fromField: 'orderDateFrom', 
+    toField: 'orderDateTo' 
+  },
+  size: 'x30',
+  props: {
+    min: '2020-01-01',
+    max: new Date().toISOString().split('T')[0],
+    format: 'YYYY-MM-DD'
+  }
+}
+
+// Multi-select with dictionary
+{
+  type: 'option-multi-select-search',
+  name: 'categories',
+  label: 'Categories',
+  keys: { field: 'categoryIds' },
+  dictName: 'product-categories',
+  size: 'x25',
+  props: {
+    maxSelections: 5,
+    placeholder: 'Select categories'
+  }
+}
+
+// Dynamic searchable select
+{
+  type: 'input-option-select-search',
+  name: 'assignee',
+  label: 'Assigned To',
+  keys: { field: 'assigneeId' },
+  size: 'x25',
+  props: {
+    getOptions: 'loadUserSuggestions',
+    minLength: 2,
+    debounce: 300,
+    placeholder: 'Type to search users'
+  }
+}
+```
+
+## Advanced Search Patterns
+
+### Complex Search Builder
+
+```typescript
+class AdvancedSearchBuilder {
+  private schema: FlexiCriteriaSetSchema;
+  
+  constructor() {
+    this.schema = {
+      arrangement: 'vertical',
+      variant: 'outlined',
+      fields: []
+    };
+  }
+  
+  addTextField(name: string, label: string, options: any = {}): this {
+    this.schema.fields.push({
+      type: 'text-search',
+      name,
+      label,
+      keys: { field: options.field || name },
+      size: options.size || 'x25',
+      props: {
+        placeholder: options.placeholder || `Enter ${label.toLowerCase()}`,
+        operators: options.operators || ['contains', 'equals']
+      }
+    });
+    return this;
+  }
+  
+  addSelectField(name: string, label: string, dictName: string, options: any = {}): this {
+    this.schema.fields.push({
+      type: options.multi ? 'option-multi-select-search' : 'option-select-search',
+      name,
+      label,
+      keys: { field: options.field || name },
+      dictName,
+      size: options.size || 'x20',
+      props: {
+        placeholder: options.placeholder || `Select ${label.toLowerCase()}`,
+        maxSelections: options.maxSelections
+      }
+    });
+    return this;
+  }
+  
+  addDateRangeField(name: string, label: string, options: any = {}): this {
+    this.schema.fields.push({
+      type: 'date-range',
+      name,
+      label,
+      keys: {
+        fromField: options.fromField || `${name}From`,
+        toField: options.toField || `${name}To`
+      },
+      size: options.size || 'x30',
+      props: {
+        min: options.min,
+        max: options.max,
+        format: options.format || 'YYYY-MM-DD'
+      }
+    });
+    return this;
+  }
+  
+  addNumberRangeField(name: string, label: string, options: any = {}): this {
+    this.schema.fields.push({
+      type: 'number-range',
+      name,
+      label,
+      keys: {
+        minField: options.minField || `${name}Min`,
+        maxField: options.maxField || `${name}Max`
+      },
+      size: options.size || 'x25',
+      props: {
+        min: options.min,
+        max: options.max,
+        step: options.step,
+        precision: options.precision
+      }
+    });
+    return this;
+  }
+  
+  build(): FlexiCriteriaSetSchema {
+    return this.schema;
+  }
+}
+
+// Usage
+const productSearchSchema = new AdvancedSearchBuilder()
+  .addTextField('name', 'Product Name', { 
+    operators: ['contains', 'startsWith'] 
+  })
+  .addTextField('sku', 'SKU', { 
+    operators: ['equals', 'startsWith'] 
+  })
+  .addSelectField('category', 'Category', 'product-categories')
+  .addSelectField('tags', 'Tags', 'product-tags', { 
+    multi: true, 
+    maxSelections: 3 
+  })
+  .addNumberRangeField('price', 'Price Range', { 
+    min: 0, 
+    step: 0.01 
+  })
+  .addDateRangeField('createdDate', 'Created Date')
+  .build();
+```
+
+### Conditional Criteria Fields
+
+```typescript
+class ConditionalCriteriaSet extends FlexiCriteriaSet {
+  private conditionalFields = new Map<string, string[]>();
+  
+  constructor(schema: FlexiCriteriaSetSchema) {
+    super(schema);
+    this.setupConditionalLogic();
+  }
+  
+  private setupConditionalLogic(): void {
+    // Define conditional relationships
+    this.conditionalFields.set('searchType', ['specificFields']);
+    
+    // Setup change handlers
+    this.setupFieldChangeHandlers();
+  }
+  
+  private setupFieldChangeHandlers(): void {
+    const searchTypeField = this.field['searchType'];
+    if (searchTypeField) {
+      searchTypeField.events.change = (value: string) => {
+        this.updateConditionalFields(value);
+      };
+    }
+  }
+  
+  private updateConditionalFields(searchType: string): void {
+    const showAdvanced = searchType === 'advanced';
+    
+    // Show/hide fields based on search type
+    this.fields.forEach(field => {
+      if (field.name?.startsWith('advanced_')) {
+        field.visible = showAdvanced;
+      }
+    });
+    
+    this.invalidate();
+  }
+}
+
+// Usage
+const conditionalSchema = {
+  arrangement: 'vertical',
+  fields: [
+    {
+      type: 'option-select-search',
+      name: 'searchType',
+      label: 'Search Type',
+      keys: { field: 'type' },
+      props: {
+        options: [
+          { value: 'basic', label: 'Basic Search' },
+          { value: 'advanced', label: 'Advanced Search' }
+        ]
+      }
+    },
+    {
+      type: 'text-search',
+      name: 'basicQuery',
+      label: 'Search Query',
+      keys: { field: 'query' },
+      visible: true
+    },
+    {
+      type: 'text-search',
+      name: 'advanced_title',
+      label: 'Title',
+      keys: { field: 'title' },
+      visible: false
+    },
+    {
+      type: 'text-search',
+      name: 'advanced_content',
+      label: 'Content',
+      keys: { field: 'content' },
+      visible: false
+    }
+  ]
+};
+```
+
+## Dynamic Criteria Generation
+
+### Loading Criteria from API
+
+```typescript
+class DynamicCriteriaLoader {
+  private cache = new Map<string, FlexiCriteriaSetSchema>();
+  
+  async loadCriteriaSchema(entityType: string): Promise<FlexiCriteriaSetSchema> {
+    if (this.cache.has(entityType)) {
+      return this.cache.get(entityType)!;
+    }
+    
+    try {
+      const response = await fetch(`/api/search/criteria/${entityType}`);
+      const schema = await response.json();
+      this.cache.set(entityType, schema);
+      return schema;
+    } catch (error) {
+      console.error('Failed to load criteria schema:', error);
+      return this.getDefaultSchema();
+    }
+  }
+  
+  async loadDictionaries(dictNames: string[]): Promise<Record<string, any[]>> {
+    const dictionaries: Record<string, any[]> = {};
+    
+    for (const dictName of dictNames) {
+      try {
+        const response = await fetch(`/api/dictionaries/${dictName}`);
+        dictionaries[dictName] = await response.json();
+      } catch (error) {
+        console.error(`Failed to load dictionary ${dictName}:`, error);
+        dictionaries[dictName] = [];
+      }
+    }
+    
+    return dictionaries;
+  }
+  
+  private getDefaultSchema(): FlexiCriteriaSetSchema {
+    return {
+      arrangement: 'vertical',
+      fields: [
+        {
+          type: 'text-search',
+          name: 'query',
+          label: 'Search',
+          keys: { field: 'q' },
+          size: 'x40'
+        }
+      ]
+    };
+  }
+}
+
+// Usage in Svelte component
+let criteriaSchema = null;
+let searchCriteria = {};
+
+onMount(async () => {
+  const loader = new DynamicCriteriaLoader();
+  criteriaSchema = await loader.loadCriteriaSchema('products');
+  
+  // Load required dictionaries
+  const dictNames = extractDictionaryNames(criteriaSchema);
+  const dictionaries = await loader.loadDictionaries(dictNames);
+  
+  // Setup criteria set with dictionaries
+  setupCriteriaSet(criteriaSchema, dictionaries);
+});
+```
+
+### Saved Search Patterns
+
+```typescript
+class SavedSearchManager {
+  private storageKey = 'saved-searches';
+  
+  saveSearch(name: string, criteria: any, schema: FlexiCriteriaSetSchema): void {
+    const savedSearches = this.getSavedSearches();
+    savedSearches[name] = {
+      criteria,
+      schema,
+      createdAt: new Date().toISOString()
+    };
+    localStorage.setItem(this.storageKey, JSON.stringify(savedSearches));
+  }
+  
+  loadSearch(name: string): { criteria: any; schema: FlexiCriteriaSetSchema } | null {
+    const savedSearches = this.getSavedSearches();
+    return savedSearches[name] || null;
+  }
+  
+  listSavedSearches(): string[] {
+    const savedSearches = this.getSavedSearches();
+    return Object.keys(savedSearches);
+  }
+  
+  deleteSearch(name: string): void {
+    const savedSearches = this.getSavedSearches();
+    delete savedSearches[name];
+    localStorage.setItem(this.storageKey, JSON.stringify(savedSearches));
+  }
+  
+  private getSavedSearches(): Record<string, any> {
+    try {
+      return JSON.parse(localStorage.getItem(this.storageKey) || '{}');
+    } catch {
+      return {};
+    }
+  }
+}
+
+// Usage
+const searchManager = new SavedSearchManager();
+
+function saveCurrentSearch() {
+  const name = prompt('Enter search name:');
+  if (name) {
+    searchManager.saveSearch(name, searchCriteria, criteriaSchema);
+  }
+}
+
+function loadSavedSearch(name: string) {
+  const saved = searchManager.loadSearch(name);
+  if (saved) {
+    searchCriteria = saved.criteria;
+    criteriaSchema = saved.schema;
+  }
+}
+```
+
+## Events and Interactions
+
+### Criteria Change Events
+
+```svelte
+<script>
+  function handleCriteriaChange(event) {
+    const { criteria, field, value } = event.detail;
+    console.log(`Field ${field} changed to:`, value);
+    console.log('Full criteria:', criteria);
+    
+    // Trigger real-time search
+    debouncedSearch(criteria);
+  }
+  
+  function handleFieldFocus(event) {
+    const { field } = event.detail;
+    console.log(`Field ${field} focused`);
+    
+    // Load suggestions for this field
+    loadFieldSuggestions(field);
+  }
+  
+  function handleOperatorChange(event) {
+    const { field, operator } = event.detail;
+    console.log(`Field ${field} operator changed to:`, operator);
+  }
+  
+  // Debounced search function
+  const debouncedSearch = debounce((criteria) => {
+    performSearch(criteria);
+  }, 300);
+  
+  function debounce(func, wait) {
+    let timeout;
+    return function executedFunction(...args) {
+      const later = () => {
+        clearTimeout(timeout);
+        func(...args);
+      };
+      clearTimeout(timeout);
+      timeout = setTimeout(later, wait);
+    };
+  }
+</script>
+
+<CriteriaPanel 
+  {schema}
+  bind:criteria={searchCriteria}
+  on:change={handleCriteriaChange}
+  on:fieldFocus={handleFieldFocus}
+  on:operatorChange={handleOperatorChange}
+  on:search={handleSearch}
+  on:reset={handleReset}
+/>
+```
+
+### Custom Event Handlers
+
+```typescript
+class CustomCriteriaEventHandler {
+  private criteriaSet: FlexiCriteriaSet;
+  
+  constructor(criteriaSet: FlexiCriteriaSet) {
+    this.criteriaSet = criteriaSet;
+    this.setupEventHandlers();
+  }
+  
+  private setupEventHandlers(): void {
+    // Setup field-specific event handlers
+    this.setupCategoryFieldHandler();
+    this.setupLocationFieldHandler();
+    this.setupDateRangeHandler();
+  }
+  
+  private setupCategoryFieldHandler(): void {
+    const categoryField = this.criteriaSet.field['category'];
+    if (categoryField) {
+      categoryField.events.change = async (value: string) => {
+        console.log('Category changed:', value);
+        
+        // Load subcategories based on selected category
+        await this.loadSubcategories(value);
+        
+        // Update related fields
+        this.updateRelatedFields('category', value);
+      };
+    }
+  }
+  
+  private setupLocationFieldHandler(): void {
+    const countryField = this.criteriaSet.field['country'];
+    const stateField = this.criteriaSet.field['state'];
+    
+    if (countryField && stateField) {
+      countryField.events.change = async (country: string) => {
+        // Clear state field
+        stateField.data = null;
+        
+        // Load states for selected country
+        const states = await this.loadStates(country);
+        stateField.props.options = states;
+        
+        this.criteriaSet.invalidate();
+      };
+    }
+  }
+  
+  private setupDateRangeHandler(): void {
+    const fromDateField = this.criteriaSet.field['fromDate'];
+    const toDateField = this.criteriaSet.field['toDate'];
+    
+    if (fromDateField && toDateField) {
+      fromDateField.events.change = (fromDate: string) => {
+        // Update minimum date for toDate field
+        toDateField.props.min = fromDate;
+        this.criteriaSet.invalidate();
+      };
+      
+      toDateField.events.change = (toDate: string) => {
+        // Update maximum date for fromDate field
+        fromDateField.props.max = toDate;
+        this.criteriaSet.invalidate();
+      };
+    }
+  }
+  
+  private async loadSubcategories(categoryId: string): Promise<void> {
+    try {
+      const response = await fetch(`/api/categories/${categoryId}/subcategories`);
+      const subcategories = await response.json();
+      
+      const subcategoryField = this.criteriaSet.field['subcategory'];
+      if (subcategoryField) {
+        subcategoryField.props.options = subcategories;
+        this.criteriaSet.invalidate();
+      }
+    } catch (error) {
+      console.error('Failed to load subcategories:', error);
+    }
+  }
+  
+  private async loadStates(countryCode: string): Promise<any[]> {
+    try {
+      const response = await fetch(`/api/countries/${countryCode}/states`);
+      return await response.json();
+    } catch (error) {
+      console.error('Failed to load states:', error);
+      return [];
+    }
+  }
+  
+  private updateRelatedFields(changedField: string, value: any): void {
+    // Implement business logic for updating related fields
+    console.log(`Updating fields related to ${changedField}:`, value);
+  }
+}
+```
+
+## Extending FlexiCriteriaSet
+
+### Creating Custom Criteria Field Types
+
+#### 1. Custom Range Slider Field
+
+```svelte
+<!-- CustomRangeSliderField.svelte -->
+<script lang="ts">
+  import type FlexiCriteriaField from "$lib/criteria-panel/lib/FlexiCriteriaField";
+  
+  export let field: FlexiCriteriaField;
+  export let readonly: boolean = false;
+  export let disabled: boolean = false;
+  
+  $: props = field.props;
+  $: keys = field.keys;
+  
+  let minValue = props.min || 0;
+  let maxValue = props.max || 100;
+  let currentMin = minValue;
+  let currentMax = maxValue;
+  
+  // Initialize from data
+  if (field.data) {
+    currentMin = field.data[keys.minField] || minValue;
+    currentMax = field.data[keys.maxField] || maxValue;
+  }
+  
+  function updateRange() {
+    if (!field.data) field.data = {};
+    field.data[keys.minField] = currentMin;
+    field.data[keys.maxField] = currentMax;
+    
+    // Trigger change event
+    field.events.change?.({ min: currentMin, max: currentMax });
+  }
+  
+  $: if (currentMin !== undefined && currentMax !== undefined) {
+    updateRange();
+  }
+</script>
+
+<div class="range-slider-field" class:readonly class:disabled>
+  <label>{field.label}</label>
+  
+  <div class="range-inputs">
+    <input
+      type="number"
+      bind:value={currentMin}
+      min={minValue}
+      max={currentMax}
+      {disabled}
+      {readonly}
+      class="range-input"
+    />
+    <span class="range-separator">to</span>
+    <input
+      type="number"
+      bind:value={currentMax}
+      min={currentMin}
+      max={maxValue}
+      {disabled}
+      {readonly}
+      class="range-input"
+    />
+  </div>
+  
+  <div class="slider-container">
+    <input
+      type="range"
+      bind:value={currentMin}
+      min={minValue}
+      max={maxValue}
+      step={props.step || 1}
+      {disabled}
+      {readonly}
+      class="slider slider-min"
+    />
+    <input
+      type="range"
+      bind:value={currentMax}
+      min={minValue}
+      max={maxValue}
+      step={props.step || 1}
+      {disabled}
+      {readonly}
+      class="slider slider-max"
+    />
+  </div>
+  
+  <div class="range-display">
+    {props.prefix || ''}{currentMin} - {currentMax}{props.suffix || ''}
+  </div>
+</div>
+
+<style>
+  .range-slider-field {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+  }
+  
+  .range-inputs {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+  }
+  
+  .range-input {
+    width: 80px;
+    padding: 4px 8px;
+    border: 1px solid #ddd;
+    border-radius: 4px;
+  }
+  
+  .range-separator {
+    color: #666;
+  }
+  
+  .slider-container {
+    position: relative;
+    height: 20px;
+  }
+  
+  .slider {
+    position: absolute;
+    width: 100%;
+    height: 20px;
+    -webkit-appearance: none;
+    background: transparent;
+    outline: none;
+  }
+  
+  .slider::-webkit-slider-track {
+    height: 4px;
+    background: #ddd;
+    border-radius: 2px;
+  }
+  
+  .slider::-webkit-slider-thumb {
+    -webkit-appearance: none;
+    width: 16px;
+    height: 16px;
+    background: #007bff;
+    border-radius: 50%;
+    cursor: pointer;
+  }
+  
+  .range-display {
+    text-align: center;
+    font-weight: bold;
+    color: #333;
+  }
+  
+  .readonly, .disabled {
+    opacity: 0.6;
+    pointer-events: none;
+  }
+</style>
+```
+
+#### 2. Register Custom Field Type
+
+```typescript
+import CriteriaComponentBuilder from '@ticatec/uniface-flexi-form/criteria-panel/lib/CriteriaComponentBuilder';
+import CustomRangeSliderField from './CustomRangeSliderField.svelte';
+
+// Create builder function
+const buildRangeSliderField = (schema: FlexiCriteriaFieldSchema, dictLoader: DictionaryLoader) => {
+  return {
+    component: CustomRangeSliderField,
+    props: schema.props,
+    keyFields: schema.keys
+  };
+};
+
+// Register the custom field type
+const componentBuilder = CriteriaComponentBuilder.getInstance();
+componentBuilder.register('range-slider', buildRangeSliderField);
+
+// Use in schema
+const schemaWithRangeSlider = {
+  arrangement: 'vertical',
+  fields: [
+    {
+      type: 'range-slider',
+      name: 'priceRange',
+      label: 'Price Range',
+      keys: { 
+        minField: 'priceMin', 
+        maxField: 'priceMax' 
+      },
+      size: 'x30',
+      props: {
+        min: 0,
+        max: 1000,
+        step: 10,
+        prefix: '$',
+        suffix: ' USD'
+      }
+    }
+  ]
+};
+```
+
+### Creating Custom Criteria Sets
+
+```typescript
+class AdvancedProductCriteriaSet extends FlexiCriteriaSet {
+  private productCategories: any[] = [];
+  private priceHistory: any[] = [];
+  
+  constructor(schema: FlexiCriteriaSetSchema) {
+    super(schema);
+    this.setupAdvancedFeatures();
+  }
+  
+  private async setupAdvancedFeatures(): Promise<void> {
+    await this.loadProductCategories();
+    await this.loadPriceHistory();
+    this.setupSmartDefaults();
+    this.setupAdvancedValidation();
+  }
+  
+  private async loadProductCategories(): Promise<void> {
+    try {
+      const response = await fetch('/api/products/categories/tree');
+      this.productCategories = await response.json();
+    } catch (error) {
+      console.error('Failed to load product categories:', error);
+    }
+  }
+  
+  private async loadPriceHistory(): Promise<void> {
+    try {
+      const response = await fetch('/api/products/price-history');
+      this.priceHistory = await response.json();
+    } catch (error) {
+      console.error('Failed to load price history:', error);
+    }
+  }
+  
+  private setupSmartDefaults(): void {
+    // Set intelligent defaults based on user history or popular searches
+    const categoryField = this.field['category'];
+    const priceField = this.field['priceRange'];
+    
+    if (categoryField && this.productCategories.length > 0) {
+      // Set most popular category as default
+      const popularCategory = this.getMostPopularCategory();
+      categoryField.data = popularCategory?.id;
+    }
+    
+    if (priceField && this.priceHistory.length > 0) {
+      // Set common price range as default
+      const commonRange = this.getCommonPriceRange();
+      priceField.data = commonRange;
+    }
+  }
+  
+  private setupAdvancedValidation(): void {
+    // Add cross-field validation
+    this.addValidator('priceRange', (value: any) => {
+      if (value.min > value.max) {
+        return 'Minimum price cannot be greater than maximum price';
+      }
+      return null;
+    });
+    
+    this.addValidator('dateRange', (value: any) => {
+      if (new Date(value.from) > new Date(value.to)) {
+        return 'Start date cannot be after end date';
+      }
+      return null;
+    });
+  }
+  
+  private getMostPopularCategory(): any {
+    // Implement logic to determine most popular category
+    return this.productCategories[0];
+  }
+  
+  private getCommonPriceRange(): any {
+    // Implement logic to determine common price range
+    return { min: 10, max: 100 };
+  }
+  
+  private addValidator(fieldName: string, validator: (value: any) => string | null): void {
+    const field = this.field[fieldName];
+    if (field) {
+      const originalChange = field.events.change;
+      field.events.change = (value: any) => {
+        const error = validator(value);
+        if (error) {
+          console.error(`Validation error for ${fieldName}:`, error);
+          // Handle validation error
+        } else {
+          originalChange?.(value);
+        }
+      };
+    }
+  }
+  
+  // Public API methods
+  getCriteriaQuery(): any {
+    const criteria = {};
+    
+    for (const field of this.fields) {
+      if (field.data !== null && field.data !== undefined) {
+        // Convert field data to query format
+        const queryPart = this.convertFieldToQuery(field);
+        Object.assign(criteria, queryPart);
+      }
+    }
+    
+    return criteria;
+  }
+  
+  private convertFieldToQuery(field: FlexiCriteriaField): any {
+    const query = {};
+    
+    switch (field.component.name) {
+      case 'TextSearchField':
+        query[field.keys.field] = {
+          operator: field.props.selectedOperator || 'contains',
+          value: field.data
+        };
+        break;
+        
+      case 'RangeSliderField':
+        if (field.data.min !== undefined) {
+          query[field.keys.minField] = {
+            operator: 'gte',
+            value: field.data.min
+          };
+        }
+        if (field.data.max !== undefined) {
+          query[field.keys.maxField] = {
+            operator: 'lte',
+            value: field.data.max
+          };
+        }
+        break;
+        
+      // Handle other field types...
+    }
+    
+    return query;
+  }
+  
+  exportCriteria(): string {
+    return JSON.stringify(this.getCriteriaQuery(), null, 2);
+  }
+  
+  importCriteria(jsonString: string): void {
+    try {
+      const criteria = JSON.parse(jsonString);
+      this.applyCriteria(criteria);
+    } catch (error) {
+      console.error('Failed to import criteria:', error);
+    }
+  }
+  
+  private applyCriteria(criteria: any): void {
+    // Apply imported criteria to fields
+    for (const [key, value] of Object.entries(criteria)) {
+      const field = this.findFieldByKey(key);
+      if (field) {
+        field.data = value;
+      }
+    }
+    this.invalidate();
+  }
+  
+  private findFieldByKey(key: string): FlexiCriteriaField | null {
+    for (const field of this.fields) {
+      if (Object.values(field.keys).includes(key)) {
+        return field;
+      }
+    }
+    return null;
+  }
+}
+```
+
+## Integration Patterns
+
+### Integration with Data Tables
+
+```svelte
+<!-- ProductSearchAndTable.svelte -->
+<script lang="ts">
+  import CriteriaPanel from '@ticatec/uniface-flexi-form/criteria-panel';
+  import DataTable from '@ticatec/uniface-element/DataTable';
+  
+  let searchCriteria = {};
+  let tableData = [];
+  let loading = false;
+  let totalRecords = 0;
+  let currentPage = 1;
+  let pageSize = 20;
+  
+  const criteriaSchema = {
+    arrangement: 'horizontal',
+    fields: [
+      {
+        type: 'text-search',
+        name: 'name',
+        label: 'Product Name',
+        keys: { field: 'name' },
+        size: 'x25'
+      },
+      {
+        type: 'option-select-search',
+        name: 'category',
+        label: 'Category',
+        keys: { field: 'categoryId' },
+        dictName: 'categories',
+        size: 'x20'
+      },
+      {
+        type: 'number-range',
+        name: 'price',
+        label: 'Price Range',
+        keys: { minField: 'priceMin', maxField: 'priceMax' },
+        size: 'x25'
+      }
+    ]
+  };
+  
+  const tableColumns = [
+    { field: 'name', text: 'Product Name', width: 200 },
+    { field: 'category', text: 'Category', width: 150 },
+    { field: 'price', text: 'Price', width: 100, formatter: 'currency' },
+    { field: 'stock', text: 'Stock', width: 100 },
+    { field: 'status', text: 'Status', width: 120 }
+  ];
+  
+  // Reactive search when criteria changes
+  $: if (searchCriteria) {
+    performSearch();
+  }
+  
+  async function performSearch() {
+    loading = true;
+    try {
+      const queryParams = new URLSearchParams({
+        page: currentPage.toString(),
+        limit: pageSize.toString(),
+        ...flattenCriteria(searchCriteria)
+      });
+      
+      const response = await fetch(`/api/products/search?${queryParams}`);
+      const result = await response.json();
+      
+      tableData = result.data;
+      totalRecords = result.total;
+    } catch (error) {
+      console.error('Search failed:', error);
+      tableData = [];
+    } finally {
+      loading = false;
+    }
+  }
+  
+  function flattenCriteria(criteria) {
+    const flattened = {};
+    for (const [key, value] of Object.entries(criteria)) {
+      if (value !== null && value !== undefined && value !== '') {
+        flattened[key] = value;
+      }
+    }
+    return flattened;
+  }
+  
+  function handlePageChange(event) {
+    currentPage = event.detail.page;
+    performSearch();
+  }
+  
+  function handleCriteriaChange(event) {
+    searchCriteria = event.detail.criteria;
+    currentPage = 1; // Reset to first page on new search
+  }
+  
+  function handleReset() {
+    searchCriteria = {};
+    currentPage = 1;
+  }
+</script>
+
+<div class="search-and-table">
+  <div class="search-panel">
+    <h3>Product Search</h3>
+    <CriteriaPanel 
+      schema={criteriaSchema}
+      bind:criteria={searchCriteria}
+      on:change={handleCriteriaChange}
+      on:reset={handleReset}
+    />
+  </div>
+  
+  <div class="results-panel">
+    <div class="results-header">
+      <h3>Search Results ({totalRecords} items)</h3>
+      {#if loading}
+        <div class="loading">Searching...</div>
+      {/if}
+    </div>
+    
+    <DataTable 
+      columns={tableColumns}
+      data={tableData}
+      {totalRecords}
+      {currentPage}
+      {pageSize}
+      on:pageChange={handlePageChange}
+    />
+  </div>
+</div>
+
+<style>
+  .search-and-table {
+    display: flex;
+    flex-direction: column;
+    gap: 20px;
+  }
+  
+  .search-panel {
+    background: #f8f9fa;
+    padding: 16px;
+    border-radius: 8px;
+    border: 1px solid #dee2e6;
+  }
+  
+  .results-panel {
+    flex: 1;
+  }
+  
+  .results-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: 16px;
+  }
+  
+  .loading {
+    color: #6c757d;
+    font-style: italic;
+  }
+</style>
+```
+
+### URL State Management
+
+```typescript
+class CriteriaURLManager {
+  private criteria: any = {};
+  private schema: FlexiCriteriaSetSchema;
+  
+  constructor(schema: FlexiCriteriaSetSchema) {
+    this.schema = schema;
+    this.loadFromURL();
+  }
+  
+  loadFromURL(): any {
+    const urlParams = new URLSearchParams(window.location.search);
+    const criteria = {};
+    
+    for (const field of this.schema.fields) {
+      const keys = field.keys || {};
+      
+      for (const [keyName, paramName] of Object.entries(keys)) {
+        const value = urlParams.get(paramName);
+        if (value !== null) {
+          if (!criteria[field.name!]) {
+            criteria[field.name!] = {};
+          }
+          criteria[field.name!][keyName] = this.parseURLValue(value, field.type);
+        }
+      }
+    }
+    
+    this.criteria = criteria;
+    return criteria;
+  }
+  
+  updateURL(criteria: any): void {
+    const urlParams = new URLSearchParams();
+    
+    for (const field of this.schema.fields) {
+      const fieldCriteria = criteria[field.name!];
+      if (fieldCriteria) {
+        const keys = field.keys || {};
+        
+        for (const [keyName, paramName] of Object.entries(keys)) {
+          const value = fieldCriteria[keyName];
+          if (value !== null && value !== undefined && value !== '') {
+            urlParams.set(paramName, this.serializeURLValue(value));
+          }
+        }
+      }
+    }
+    
+    const newURL = `${window.location.pathname}?${urlParams.toString()}`;
+    window.history.replaceState({}, '', newURL);
+  }
+  
+  private parseURLValue(value: string, fieldType: string): any {
+    switch (fieldType) {
+      case 'number-search':
+      case 'number-range':
+        return parseFloat(value);
+      case 'date-search':
+      case 'date-range':
+        return value; // Keep as string for date inputs
+      case 'option-multi-select-search':
+        return value.split(',');
+      default:
+        return value;
+    }
+  }
+  
+  private serializeURLValue(value: any): string {
+    if (Array.isArray(value)) {
+      return value.join(',');
+    }
+    return String(value);
+  }
+  
+  getCriteria(): any {
+    return this.criteria;
+  }
+}
+
+// Usage in component
+let criteriaURLManager: CriteriaURLManager;
+let searchCriteria = {};
+
+onMount(() => {
+  criteriaURLManager = new CriteriaURLManager(criteriaSchema);
+  searchCriteria = criteriaURLManager.loadFromURL();
+});
+
+function handleCriteriaChange(event) {
+  searchCriteria = event.detail.criteria;
+  criteriaURLManager.updateURL(searchCriteria);
+}
+```
+
+## Best Practices
+
+### 1. Schema Organization
+
+```typescript
+// Good: Organized schema with constants
+const FIELD_SIZES = {
+  SMALL: 'x15',
+  MEDIUM: 'x25',
+  LARGE: 'x35',
+  FULL: 'x40'
+} as const;
+
+const COMMON_FIELDS = {
+  NAME_SEARCH: {
+    type: 'text-search',
+    keys: { field: 'name' },
+    size: FIELD_SIZES.MEDIUM,
+    props: {
+      placeholder: 'Enter name',
+      operators: ['contains', 'startsWith', 'equals']
+    }
+  },
+  
+  STATUS_SELECT: {
+    type: 'option-select-search',
+    keys: { field: 'status' },
+    dictName: 'status-options',
+    size: FIELD_SIZES.SMALL
+  }
+} as const;
+
+const PRODUCT_SEARCH_SCHEMA = {
+  arrangement: 'horizontal' as const,
+  variant: 'outlined' as const,
+  fields: [
+    {
+      ...COMMON_FIELDS.NAME_SEARCH,
+      name: 'productName',
+      label: 'Product Name'
+    },
+    {
+      ...COMMON_FIELDS.STATUS_SELECT,
+      name: 'status',
+      label: 'Status'
+    }
+  ]
+};
+```
+
+### 2. Performance Optimization
+
+```typescript
+// Debounced search for real-time filtering
+class OptimizedCriteriaHandler {
+  private searchDebounceTime = 300;
+  private dictionaryCache = new Map();
+  
+  createDebouncedSearch(searchFunction: Function) {
+    let timeoutId: number;
+    
+    return (criteria: any) => {
+      clearTimeout(timeoutId);
+      timeoutId = setTimeout(() => {
+        searchFunction(criteria);
+      }, this.searchDebounceTime);
+    };
+  }
+  
+  async getCachedDictionary(dictName: string): Promise<any[]> {
+    if (this.dictionaryCache.has(dictName)) {
+      return this.dictionaryCache.get(dictName);
+    }
+    
+    const dictionary = await this.loadDictionary(dictName);
+    this.dictionaryCache.set(dictName, dictionary);
+    return dictionary;
+  }
+  
+  private async loadDictionary(dictName: string): Promise<any[]> {
+    const response = await fetch(`/api/dictionaries/${dictName}`);
+    return await response.json();
+  }
+}
+```
+
+### 3. Error Handling
+
+```typescript
+class CriteriaErrorHandler {
+  static handleCriteriaError(error: any, criteriaSet: FlexiCriteriaSet): void {
+    if (error.fieldErrors) {
+      this.displayFieldErrors(error.fieldErrors, criteriaSet);
+    } else if (error.networkError) {
+      this.displayNetworkError();
+    } else {
+      this.displayGenericError(error);
+    }
+  }
+  
+  private static displayFieldErrors(errors: Record<string, string>, criteriaSet: FlexiCriteriaSet): void {
+    for (const [fieldName, errorMessage] of Object.entries(errors)) {
+      const field = criteriaSet.field[fieldName];
+      if (field) {
+        // Display error near field
+        console.error(`Field ${fieldName}: ${errorMessage}`);
+      }
+    }
+  }
+  
+  private static displayNetworkError(): void {
+    console.error('Network error occurred while searching');
+  }
+  
+  private static displayGenericError(error: any): void {
+    console.error('Search error:', error);
+  }
+}
+```
+
+### 4. Accessibility
+
+```typescript
+const accessibleCriteriaSchema = {
+  arrangement: 'vertical',
+  fields: [
+    {
+      type: 'text-search',
+      name: 'search',
+      label: 'Search Products',
+      keys: { field: 'query' },
+      props: {
+        placeholder: 'Enter search terms',
+        'aria-label': 'Search products by name or description',
+        'aria-describedby': 'search-help'
+      }
+    }
+  ]
+};
+
+// Add help text and ARIA attributes
+const helpText = {
+  'search-help': 'Use keywords to search product names and descriptions'
+};
+```
+
+This comprehensive guide provides everything needed to effectively use and extend FlexiCriteriaSet for building sophisticated search interfaces. The examples progress from basic usage to advanced patterns, showing how to create powerful search experiences with FlexiCriteriaSet's flexible architecture.