ngx-column-filter-popup 1.0.0

package/README.md

@@ -0,0 +1,451 @@
+# Column Filter Library
+
+A powerful, reusable Angular column filter component with support for multiple field types, advanced filtering rules, and customizable match modes.
+
+[![npm version](https://badge.fury.io/js/%40blumptech%2Fcolumn-filter.svg)](https://badge.fury.io/js/%40blumptech%2Fcolumn-filter)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- ✅ **Multiple Filter Rules**: Add multiple filter conditions per column
+- ✅ **Multiple Field Types**: Specialized filters for different data types
+  - **Text** - Text fields (default)
+  - **Currency** - Currency values with symbol support
+  - **Age/Number** - Numeric values
+  - **Date** - Date values with date picker
+  - **Status** - Predefined status options dropdown
+- ✅ **Global Match Mode**: Choose how to combine multiple rules
+  - **Match All Rules** (AND Logic): All rules must match
+  - **Match Any Rule** (OR Logic): Any rule can match (default)
+- ✅ **Various Match Types**: Different matching options based on field type
+- ✅ **Visual Feedback**: Filter icon changes when active
+- ✅ **Single Filter Open**: Only one filter dropdown can be open at a time
+- ✅ **ESC Key Support**: Press ESC to close the open filter
+- ✅ **Programmatic Control**: Clear filters programmatically using `clearFilter()` method
+- ✅ **Type-Safe**: Fully typed with TypeScript
+- ✅ **Standalone Component**: Works with Angular 14+ standalone components
+- ✅ **Fully Customizable**: Configurable inputs for customization
+- ✅ **Accessible**: ARIA labels and keyboard navigation support
+- ✅ **Data Adaptive**: Simply update `columnKey` and `columnName` when your data changes
+
+## Installation
+
+```bash
+npm install ngx-column-filter-popup
+```
+
+**Note**: This package is published with TypeScript source files. Make sure your Angular project has TypeScript configured to compile these files.
+
+## Quick Start
+
+### Standalone Component (Angular 14+)
+
+```typescript
+import { Component } from '@angular/core';
+import { ColumnFilterComponent } from 'ngx-column-filter-popup';
+import { FilterConfig, applyColumnFilter } from 'ngx-column-filter-popup';
+
+@Component({
+  selector: 'app-example',
+  imports: [ColumnFilterComponent],
+  template: `
+    <lib-column-filter
+      columnName="first name"
+      columnKey="firstName"
+      (filterApplied)="onFilterApplied($event)"
+      (filterCleared)="onFilterCleared()">
+    </lib-column-filter>
+  `
+})
+export class ExampleComponent {
+  onFilterApplied(filterConfig: FilterConfig) {
+    console.log('Filter applied:', filterConfig);
+    // Apply filter to your data
+  }
+
+  onFilterCleared() {
+    console.log('Filter cleared');
+    // Clear filter from your data
+  }
+}
+```
+
+### Module-Based (Optional)
+
+```typescript
+import { NgModule } from '@angular/core';
+import { ColumnFilterModule } from 'ngx-column-filter-popup';
+
+@NgModule({
+  imports: [ColumnFilterModule],
+  // ...
+})
+export class YourModule {}
+```
+
+## Field Types
+
+### Text Field (Default)
+
+```html
+<lib-column-filter
+  columnName="name"
+  columnKey="name"
+  fieldType="text"
+  (filterApplied)="onFilter($event)">
+</lib-column-filter>
+```
+
+### Currency Field
+
+```html
+<lib-column-filter
+  columnName="balance"
+  columnKey="balance"
+  fieldType="currency"
+  currencySymbol="$"
+  (filterApplied)="onBalanceFilter($event)">
+</lib-column-filter>
+```
+
+### Age/Number Field
+
+```html
+<lib-column-filter
+  columnName="age"
+  columnKey="age"
+  fieldType="age"
+  (filterApplied)="onAgeFilter($event)">
+</lib-column-filter>
+```
+
+### Date Field
+
+```html
+<lib-column-filter
+  columnName="date"
+  columnKey="date"
+  fieldType="date"
+  (filterApplied)="onDateFilter($event)">
+</lib-column-filter>
+```
+
+### Status Field
+
+```html
+<lib-column-filter
+  columnName="status"
+  columnKey="status"
+  fieldType="status"
+  [statusOptions]="['qualified', 'unqualified', 'negotiation', 'new']"
+  (filterApplied)="onStatusFilter($event)">
+</lib-column-filter>
+```
+
+## API Reference
+
+### ColumnFilterComponent
+
+#### Inputs
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `columnName` | `string` | `''` | Display name of the column (used in placeholder) |
+| `columnKey` | `string` | `''` | Property name to filter on |
+| `fieldType` | `FieldType` | `'text'` | Field type: 'text', 'currency', 'age', 'date', or 'status' |
+| `currencySymbol` | `string` | `'$'` | Currency symbol for currency field type (optional) |
+| `statusOptions` | `string[]` | `[]` | Array of status options for status field type (required for status) |
+| `initialFilter` | `FilterConfig?` | `undefined` | Initial filter configuration (optional) |
+| `placeholder` | `string?` | `undefined` | Custom placeholder text. Default: "Search by {columnName}" |
+| `availableMatchTypes` | `MatchType[]?` | `undefined` | Customize available match types (optional) |
+
+#### Outputs
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `filterApplied` | `EventEmitter<FilterConfig>` | Emitted when filter is applied |
+| `filterCleared` | `EventEmitter<void>` | Emitted when filter is cleared |
+
+#### Public Methods
+
+| Method | Description |
+|--------|-------------|
+| `clearFilter()` | Programmatically clear all filter rules and reset the filter |
+
+### FilterConfig Interface
+
+```typescript
+type FieldType = 'text' | 'currency' | 'age' | 'date' | 'status';
+
+interface FilterConfig {
+  rules: FilterRule[];
+  globalMatchMode?: GlobalMatchMode; // 'match-all-rules' | 'match-any-rule'
+  fieldType?: FieldType;
+  statusOptions?: string[];
+}
+
+interface FilterRule {
+  id: string;
+  matchType: MatchType;
+  value: string;
+}
+```
+
+### Utility Functions
+
+#### applyColumnFilter
+
+Apply filter rules to a dataset:
+
+```typescript
+import { applyColumnFilter } from 'ngx-column-filter-popup';
+
+const filteredData = applyColumnFilter(
+  data,
+  'columnKey',
+  filterConfig
+);
+```
+
+#### itemMatchesFilter
+
+Check if a single item matches filter rules:
+
+```typescript
+import { itemMatchesFilter } from 'ngx-column-filter-popup';
+
+const matches = itemMatchesFilter(
+  item,
+  'columnKey',
+  filterConfig
+);
+```
+
+## Programmatic Control
+
+### Clearing Filters Programmatically
+
+```typescript
+import { Component, ViewChild } from '@angular/core';
+import { ColumnFilterComponent } from 'ngx-column-filter-popup';
+
+@Component({
+  template: `
+    <lib-column-filter
+      #nameFilter
+      columnName="name"
+      columnKey="name">
+    </lib-column-filter>
+    <button (click)="clearFilter()">Clear Filter</button>
+  `
+})
+export class ExampleComponent {
+  @ViewChild('nameFilter') filter!: ColumnFilterComponent;
+
+  clearFilter() {
+    this.filter.clearFilter(); // Programmatically clear the filter
+  }
+}
+```
+
+## Complete Example
+
+```typescript
+import { Component } from '@angular/core';
+import { ColumnFilterComponent } from 'ngx-column-filter-popup';
+import { FilterConfig, applyColumnFilter } from 'ngx-column-filter-popup';
+
+interface User {
+  id: number;
+  firstName: string;
+  lastName: string;
+  email: string;
+  age: number;
+  balance: number;
+  joinDate: string;
+  status: string;
+}
+
+@Component({
+  selector: 'app-user-list',
+  imports: [ColumnFilterComponent],
+  template: `
+    <table>
+      <thead>
+        <tr>
+          <th>
+            First Name
+            <lib-column-filter
+              columnName="first name"
+              columnKey="firstName"
+              (filterApplied)="onFirstNameFilter($event)"
+              (filterCleared)="onFirstNameClear()">
+            </lib-column-filter>
+          </th>
+          <th>
+            Age
+            <lib-column-filter
+              columnName="age"
+              columnKey="age"
+              fieldType="age"
+              (filterApplied)="onAgeFilter($event)">
+            </lib-column-filter>
+          </th>
+          <th>
+            Balance
+            <lib-column-filter
+              columnName="balance"
+              columnKey="balance"
+              fieldType="currency"
+              currencySymbol="$"
+              (filterApplied)="onBalanceFilter($event)">
+            </lib-column-filter>
+          </th>
+          <th>
+            Join Date
+            <lib-column-filter
+              columnName="join date"
+              columnKey="joinDate"
+              fieldType="date"
+              (filterApplied)="onDateFilter($event)">
+            </lib-column-filter>
+          </th>
+          <th>
+            Status
+            <lib-column-filter
+              columnName="status"
+              columnKey="status"
+              fieldType="status"
+              [statusOptions]="statusOptions"
+              (filterApplied)="onStatusFilter($event)">
+            </lib-column-filter>
+          </th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr *ngFor="let user of filteredUsers">
+          <td>{{ user.firstName }}</td>
+          <td>{{ user.age }}</td>
+          <td>${{ user.balance }}</td>
+          <td>{{ user.joinDate }}</td>
+          <td>{{ user.status }}</td>
+        </tr>
+      </tbody>
+    </table>
+  `
+})
+export class UserListComponent {
+  users: User[] = [
+    { id: 1, firstName: 'John', lastName: 'Doe', email: 'john@example.com', age: 30, balance: 50000, joinDate: '2020-01-15', status: 'active' }
+  ];
+  
+  filteredUsers: User[] = [...this.users];
+  statusOptions = ['active', 'inactive', 'on-leave'];
+  
+  firstNameFilter: FilterConfig | null = null;
+  ageFilter: FilterConfig | null = null;
+  balanceFilter: FilterConfig | null = null;
+  dateFilter: FilterConfig | null = null;
+  statusFilter: FilterConfig | null = null;
+
+  onFirstNameFilter(filterConfig: FilterConfig) {
+    this.firstNameFilter = filterConfig;
+    this.applyAllFilters();
+  }
+
+  onFirstNameClear() {
+    this.firstNameFilter = null;
+    this.applyAllFilters();
+  }
+
+  onAgeFilter(filterConfig: FilterConfig) {
+    this.ageFilter = filterConfig;
+    this.applyAllFilters();
+  }
+
+  onBalanceFilter(filterConfig: FilterConfig) {
+    this.balanceFilter = filterConfig;
+    this.applyAllFilters();
+  }
+
+  onDateFilter(filterConfig: FilterConfig) {
+    this.dateFilter = filterConfig;
+    this.applyAllFilters();
+  }
+
+  onStatusFilter(filterConfig: FilterConfig) {
+    this.statusFilter = filterConfig;
+    this.applyAllFilters();
+  }
+
+  private applyAllFilters() {
+    let result = [...this.users];
+
+    if (this.firstNameFilter) {
+      result = applyColumnFilter(result, 'firstName', this.firstNameFilter);
+    }
+    if (this.ageFilter) {
+      result = applyColumnFilter(result, 'age', this.ageFilter);
+    }
+    if (this.balanceFilter) {
+      result = applyColumnFilter(result, 'balance', this.balanceFilter);
+    }
+    if (this.dateFilter) {
+      result = applyColumnFilter(result, 'joinDate', this.dateFilter);
+    }
+    if (this.statusFilter) {
+      result = applyColumnFilter(result, 'status', this.statusFilter);
+    }
+
+    this.filteredUsers = result;
+  }
+}
+```
+
+## Documentation
+
+For comprehensive documentation including:
+- Detailed usage examples
+- How to adapt to different data structures
+- Match All Rules feature explanation
+- Complete API reference
+- Troubleshooting guide
+
+See [DOCUMENTATION.md](./DOCUMENTATION.md)
+
+For programmatic control examples, see [USAGE_EXAMPLES.md](./USAGE_EXAMPLES.md)
+
+## Styling
+
+The component uses SCSS and includes default styles. You can customize the appearance by overriding CSS classes:
+
+- `.column-filter-wrapper` - Main wrapper
+- `.filter-trigger` - Filter button
+- `.filter-dropdown` - Dropdown container
+- `.filter-rule` - Individual filter rule
+- `.btn-apply` - Apply button
+- `.btn-clear` - Clear button
+
+## Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+## Requirements
+
+- Angular 14+
+- TypeScript 4.7+
+
+## License
+
+MIT
+
+## Author
+
+Made with ❤️ by Shivam Sharma
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

package/USAGE_EXAMPLES.md

@@ -0,0 +1,251 @@
+# Column Filter Library - Usage Examples
+
+## 1. Clear Filter as Exported Function
+
+You can call the `clearFilter()` method programmatically from any component:
+
+### Using ViewChild:
+
+```typescript
+import { Component, ViewChild } from '@angular/core';
+import { ColumnFilterComponent } from 'ngx-column-filter-popup';
+
+@Component({
+  selector: 'app-example',
+  template: `
+    <table>
+      <thead>
+        <tr>
+          <th>
+            Name
+            <lib-column-filter
+              #nameFilter
+              columnName="name"
+              columnKey="name"
+              (filterApplied)="onFilter($event)">
+            </lib-column-filter>
+          </th>
+        </tr>
+      </thead>
+    </table>
+    
+    <button (click)="clearNameFilter()">Clear Name Filter</button>
+  `
+})
+export class ExampleComponent {
+  @ViewChild('nameFilter') nameFilter!: ColumnFilterComponent;
+
+  clearNameFilter() {
+    // Programmatically clear the filter
+    this.nameFilter.clearFilter();
+  }
+
+  onFilter(filterConfig: FilterConfig) {
+    // Handle filter applied
+  }
+}
+```
+
+### Using Multiple Filters:
+
+```typescript
+import { Component, ViewChildren, QueryList } from '@angular/core';
+import { ColumnFilterComponent } from 'ngx-column-filter-popup';
+
+@Component({
+  selector: 'app-example',
+  template: `
+    <table>
+      <thead>
+        <tr>
+          <th>
+            First Name
+            <lib-column-filter
+              #firstNameFilter
+              columnName="first name"
+              columnKey="firstName">
+            </lib-column-filter>
+          </th>
+          <th>
+            Last Name
+            <lib-column-filter
+              #lastNameFilter
+              columnName="last name"
+              columnKey="lastName">
+            </lib-column-filter>
+          </th>
+        </tr>
+      </thead>
+    </table>
+    
+    <button (click)="clearAllFilters()">Clear All Filters</button>
+  `
+})
+export class ExampleComponent {
+  @ViewChildren(ColumnFilterComponent) filters!: QueryList<ColumnFilterComponent>;
+
+  clearAllFilters() {
+    // Clear all filters programmatically
+    this.filters.forEach(filter => {
+      filter.clearFilter();
+    });
+  }
+}
+```
+
+---
+
+## 2. Only One Column Filter Open at a Time
+
+This feature is automatically enabled. When you open one filter, others will automatically close.
+
+**No additional code needed!** This works automatically.
+
+Example:
+- First Name filter is open
+- User opens Last Name filter
+- First Name filter automatically closes
+
+---
+
+## 3. ESC Key Support
+
+Pressing the ESC key will automatically close the open filter.
+
+**No additional code needed!** This works automatically.
+
+### How it works:
+1. User opens filter dropdown
+2. User presses ESC key
+3. Filter dropdown automatically closes
+
+---
+
+## Complete Example
+
+```typescript
+import { Component, ViewChild, ViewChildren, QueryList } from '@angular/core';
+import { ColumnFilterComponent } from 'ngx-column-filter-popup';
+import { FilterConfig, applyColumnFilter } from 'ngx-column-filter-popup';
+
+interface User {
+  id: number;
+  firstName: string;
+  lastName: string;
+  email: string;
+}
+
+@Component({
+  selector: 'app-user-list',
+  imports: [ColumnFilterComponent],
+  template: `
+    <div>
+      <button (click)="clearFirstNameFilter()">Clear First Name Filter</button>
+      <button (click)="clearAllFilters()">Clear All Filters</button>
+    </div>
+
+    <table>
+      <thead>
+        <tr>
+          <th>
+            First Name
+            <lib-column-filter
+              #firstNameFilter
+              columnName="first name"
+              columnKey="firstName"
+              (filterApplied)="onFirstNameFilter($event)"
+              (filterCleared)="onFirstNameClear()">
+            </lib-column-filter>
+          </th>
+          <th>
+            Last Name
+            <lib-column-filter
+              #lastNameFilter
+              columnName="last name"
+              columnKey="lastName"
+              (filterApplied)="onLastNameFilter($event)">
+            </lib-column-filter>
+          </th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr *ngFor="let user of filteredUsers">
+          <td>{{ user.firstName }}</td>
+          <td>{{ user.lastName }}</td>
+        </tr>
+      </tbody>
+    </table>
+  `
+})
+export class UserListComponent {
+  users: User[] = [
+    { id: 1, firstName: 'John', lastName: 'Doe', email: 'john@example.com' },
+    { id: 2, firstName: 'Jane', lastName: 'Smith', email: 'jane@example.com' }
+  ];
+  
+  filteredUsers: User[] = [...this.users];
+  firstNameFilter: FilterConfig | null = null;
+  lastNameFilter: FilterConfig | null = null;
+
+  // Using ViewChild for single filter
+  @ViewChild('firstNameFilter') firstNameFilterComponent!: ColumnFilterComponent;
+
+  // Using ViewChildren for multiple filters
+  @ViewChildren(ColumnFilterComponent) allFilters!: QueryList<ColumnFilterComponent>;
+
+  // Clear single filter programmatically
+  clearFirstNameFilter() {
+    this.firstNameFilterComponent.clearFilter();
+  }
+
+  // Clear all filters programmatically
+  clearAllFilters() {
+    this.allFilters.forEach(filter => {
+      filter.clearFilter();
+    });
+    // Also clear filter configs
+    this.firstNameFilter = null;
+    this.lastNameFilter = null;
+    this.filteredUsers = [...this.users];
+  }
+
+  onFirstNameFilter(filterConfig: FilterConfig) {
+    this.firstNameFilter = filterConfig;
+    this.applyFilters();
+  }
+
+  onFirstNameClear() {
+    this.firstNameFilter = null;
+    this.applyFilters();
+  }
+
+  onLastNameFilter(filterConfig: FilterConfig) {
+    this.lastNameFilter = filterConfig;
+    this.applyFilters();
+  }
+
+  private applyFilters() {
+    let result = [...this.users];
+    
+    if (this.firstNameFilter) {
+      result = applyColumnFilter(result, 'firstName', this.firstNameFilter);
+    }
+    
+    if (this.lastNameFilter) {
+      result = applyColumnFilter(result, 'lastName', this.lastNameFilter);
+    }
+    
+    this.filteredUsers = result;
+  }
+}
+```
+
+---
+
+## Features Summary
+
+✅ **Clear Filter Programmatically**: Call `clearFilter()` method  
+✅ **Only One Filter Open**: Automatically handled  
+✅ **ESC Key Support**: Automatically handled  
+
+**All features work automatically - no additional configuration needed!**