Uniface Filter Panel

中文文档 ｜ English

A powerful and flexible filter panel component library for Svelte 5 applications. Built on the Uniface design system, it provides comprehensive filtering solutions with dynamic criteria rendering, internationalization, and extensible architecture. Perfect for data tables, search interfaces, e-commerce platforms, and admin dashboards.

✨ Features

• 🎯 Dual Panel Architecture: Static FilterPanel and Dynamic DynamicFilterPanel with slot-based and configuration-driven approaches
• 🌐 Full Internationalization: Built-in i18n support with resource proxy system and runtime language switching
• 🎨 Flexible Theming: Customizable appearance with CSS variables, SCSS compilation, and responsive design
• 🔧 Complete TypeScript: Full type definitions, interfaces, and generics for enhanced developer experience
• 🧩 Extensible Components: Plugin-based criteria system with 8+ built-in components and custom component registration
• ⚡ Advanced UI/UX: Overlay-based advanced panels, cascading selectors, and smooth animations
• 🏗️ Modern Architecture: Svelte 5 compatibility, singleton pattern management, and modular exports

📦 Installation

npm install @ticatec/uniface-filter-panel

🚀 Quick Start

Installation & Setup

npm install @ticatec/uniface-filter-panel

// Initialize component registration (required for DynamicFilterPanel)
import { registerComponents } from '@ticatec/uniface-filter-panel';
registerComponents();

Basic FilterPanel Usage

<script>
  import FilterPanel from '@ticatec/uniface-filter-panel';
  import '@ticatec/uniface-filter-panel/uniface-filter-panel.css';
  
  function handleSearch(event) {
    console.log('Search clicked', event);
  }
  
  function handleReset(event) {
    console.log('Reset clicked', event);
  }
</script>

<FilterPanel 
  searchClickHandler={handleSearch}
  resetClickHandler={handleReset}
  advancedCriteriaTitle="Advanced Options"
>
  <!-- Basic criteria in main panel -->
  <input placeholder="Enter search term..." />
  <select>
    <option value="">All Categories</option>
    <option value="tech">Technology</option>
  </select>
  
  <!-- Advanced criteria in overlay panel -->
  <div slot="advanced-panel">
    <input placeholder="Advanced search..." />
    <input type="date" />
  </div>
</FilterPanel>

Dynamic Filter Panel Usage

<script>
  import { DynamicFilterPanel } from '@ticatec/uniface-filter-panel';
  import type { MetaCriteriaField } from '@ticatec/uniface-filter-panel';
  import { registerComponents } from '@ticatec/uniface-filter-panel';
  
  // Initialize built-in components
  registerComponents();
  
  let criteria = {};
  
  const fields: MetaCriteriaField[] = [
    {
      type: 'text-editor',
      label: 'Product Name',
      size: 'x25',
      attrs: { key: 'productName', placeholder: 'Enter product name...' }
    },
    {
      type: 'number-range',
      label: 'Price Range',
      size: 'x30',
      attrs: { 
        key: 'priceRange',
        minKey: 'minPrice',
        maxKey: 'maxPrice'
      }
    },
    {
      type: 'date-range',
      label: 'Creation Date',
      size: 'x35',
      attrs: { 
        key: 'dateRange',
        fromField: 'startDate',
        toField: 'endDate'
      },
      isAdvanced: true // This will appear in advanced panel
    },
    {
      type: 'options-selector',
      label: 'Category',
      size: 'x20',
      attrs: {
        key: 'category',
        options: [
          { label: 'Electronics', value: 'electronics' },
          { label: 'Clothing', value: 'clothing' },
          { label: 'Books', value: 'books' }
        ]
      }
    }
  ];
  
  function handleSearch(event) {
    console.log('Search criteria:', criteria);
    // Process search with criteria object
  }
  
  function handleReset(event) {
    criteria = {};
    console.log('Filters reset');
  }
</script>

<DynamicFilterPanel 
  {fields}
  bind:criteria
  searchClickHandler={handleSearch}
  resetClickHandler={handleReset}
  variant="outlined"
  advancedCriteriaTitle="More Filters"
/>

📚 Components

FilterPanel

A flexible filter panel that uses slots to define filter criteria content.

Props:

• resetClickHandler: MouseClickHandler - Reset button click handler
• searchClickHandler: MouseClickHandler - Search button click handler
• actions?: ButtonActions - Additional action buttons
• advancedCriteriaTitle?: string - Advanced criteria button text (default: "More")
• style?: string - Custom CSS styles
• advStyle?: string - Advanced panel custom styles
• hasAdvanced?: boolean - Show advanced criteria button (default: true)

Slots:

• Default slot: Basic filter criteria
• advanced-panel: Advanced filter criteria (shown in overlay)

DynamicFilterPanel

Dynamically renders filter criteria based on field definitions.

Props:

• criteria: any - Binding object for filter values
• fields: MetaCriteriaField[] - Array of field definitions
• resetClickHandler: MouseClickHandler - Reset button click handler
• searchClickHandler: MouseClickHandler - Search button click handler
• actions?: ButtonActions - Additional action buttons
• variant?: 'outlined' | 'filled' - Input field variant (default: 'outlined')
• advancedCriteriaTitle?: string - Advanced criteria title
• style?: string - Custom CSS styles
• advStyle?: string - Advanced panel custom styles

MetaCriteriaField Interface

interface MetaCriteriaField {
  type: string;           // Component type
  attrs: any;             // Component attributes
  label: string;          // Field label
  size: '' | 'x15' | 'x20' | 'x25' | 'x30' | 'x35' | 'x40'; // Field width
  isAdvanced?: boolean;   // Show in advanced panel
  props?: any;            // Additional properties
  component?: any;        // Custom component override
}

🎨 Built-in Criteria Components

Component Types & Usage

| Component | Type Key | Description | Attrs | |-----------|----------|-------------|---------| | TextEditorCriteria | text-editor | Text input fields | key, placeholder | | NumberCriteria | number-editor | Single number input | key, placeholder, min, max | | NumberRangeCriteria | number-range | Number range (min/max) | key, minKey, maxKey | | DateCriteria | date-picker | Single date picker | key, format | | DateRangeCriteria | date-range | Date range picker | key, fromField, toField | | OptionsSelectorCriteria | options-selector | Single select dropdown | key, options[] | | OptionsMultiSelectorCriteria | options-multi-selector | Multi-select dropdown | key, options[] | | CascadeSelectorCriteria | cascade-selector | Hierarchical cascading selector | key, options[], levels |

Component Registration

import { registerComponents, CriteriaComponents } from '@ticatec/uniface-filter-panel';

// Register all built-in components
registerComponents();

// Or register individual components
const manager = CriteriaComponents.getInstance();
manager.register('my-component', MyCustomComponent);

Field Size Options

Control component width with the size property:

• '' - 100px width
• 'x15' - 150px width
• 'x20' - 200px width
• 'x25' - 250px width
• 'x30' - 300px width
• 'x35' - 350px width
• 'x40' - 400px width

🌐 Internationalization

The component supports i18n with the following default keys:

| Key | Description | Default | |-----|-------------|---------| | uniface.filterPanel.btnCancel | Cancel button | Cancel | | uniface.filterPanel.btnReset | Reset button | Reset | | uniface.filterPanel.btnSearch | Search button | Search | | uniface.filterPanel.btnMoreCriteria | Advanced criteria button | Advanced criteria |

Custom Language Setup

import i18n, { i18nUtils } from '@ticatec/i18n';
i18n.language = 'zh-CN';
i18nUtils.loadResources('uniface-filterpanel.json');

📖 Use Cases

1. Data Table Filtering

Perfect for large data tables where users need to quickly locate specific records by filtering on multiple attributes like name, department, or status.

2. E-commerce Product Search

Enable customers to filter products by price range, brand, category, color, and other attributes to find their desired items efficiently.

3. Advanced Search Interfaces

Enhance search result pages with additional filtering options like date ranges, content types, or source filters for more precise results.

4. Admin Dashboard Filtering

Provide administrators with powerful tools to filter and manage users, orders, reports, or any other data through intuitive filter interfaces.

5. Report Data Filtering

Allow users to dynamically adjust report parameters by filtering on time periods, regions, categories, or other dimensions.

🔧 Extending Components

Register custom criteria components:

import { CriteriaComponents } from '@ticatec/uniface-filter-panel';
import MyCustomCriteria from './MyCustomCriteria.svelte';

const manager = CriteriaComponents.getInstance();
manager.register('my-custom-type', MyCustomCriteria);

📁 Exports

The library provides multiple export paths:

// Main components
import FilterPanel from '@ticatec/uniface-filter-panel';
import { DynamicFilterPanel } from '@ticatec/uniface-filter-panel';

// Type definitions
import type { MetaCriteriaField } from '@ticatec/uniface-filter-panel';

// Criteria components system
import { CriteriaComponents } from '@ticatec/uniface-filter-panel/CriteriaComponents';

// CSS styles
import '@ticatec/uniface-filter-panel/uniface-filter-panel.css';

🔗 Dependencies

This library is built on the Uniface ecosystem:

• @ticatec/uniface-element - Core UI components
• @ticatec/i18n - Internationalization support

🤝 Contributing

Issues and pull requests are welcome! Please read our contributing guidelines before submitting.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👤 Author

Henry Feng

• Email: [email protected]
• GitHub: @henryfeng

🙏 Acknowledgments

© 2023 Ticatec. All rights reserved.

For detailed documentation on specific components, see:

• Filter Panel Documentation
• Dynamic Filter Panel Documentation