npm package: @jerry-fd/ui
Description: UI component library based on Ant Design (Client-side only)
Author: jerry.fd
Latest version: 0.6.6

A powerful and flexible data filter component library for React, providing multiple filter types with rich configuration options.

> ⚠️ **Note**: This is a client-side only component library. It does not support Server-Side Rendering (SSR) or React Server Components (RSC).

## Installation

```bash
npm install @jerry-fd/data-filter

# Install peer dependencies
npm install dayjs antd
```

## Features

- 📦 Multiple filter types (text, number, date, option, multi-option)
- 🎨 Customizable UI with modern design
- 🔍 Built-in search functionality
- 📅 Date picker with single and range modes
- 🔢 Number filter with single and range modes
- 🎯 Full TypeScript support
- ♿ Accessible (ARIA compliant)
- 🎛️ Controlled component with state management

## Quick Start

```tsx
import React, { useState } from 'react';
import { DataFilter, FilterColumnDef, FiltersState } from '@jerry-fd/data-filter';
import '@jerry-fd/data-filter/styles';
import dayjs from 'dayjs';

function App() {
  const [filters, setFilters] = useState<FiltersState>([]);

  const columns: FilterColumnDef[] = [
    {
      type: 'text',
      columnId: 'name',
      displayName: 'Name',
      icon: Heading1,
    },
  ];

  return (
    <DataFilter
      columns={columns}
      filters={filters}
      onFiltersChange={setFilters}
    />
  );
}
```

## Example

```tsx
import type { FilterColumnDef, FilterColumnOption, FiltersState } from '@jerry-fd/data-filter';
import { DataFilter } from '@jerry-fd/data-filter';
import dayjs from 'dayjs';

type DataSchema = {
  id: number;
  name: string;
  status: string;
  tags: string[];
  date: Date;
  score: number;
};

const filterColumns: FilterColumnDef<DataSchema>[] = [
  {
    type: 'text',
    columnId: 'name',
    displayName: 'Name',
    icon: Heading1,
  },
];

// Initialize with default filters (optional)
const defaultFilters: FiltersState = [
  {
    columnId: 'name',
    type: 'text',
    values: ['Search'],
  },
];

function App() {
  const [filters, setFilters] = useState<FiltersState>(defaultFilters);

  return (
    <DataFilter
      columns={filterColumns}
      filters={filters}
      onFiltersChange={setFilters}
    />
  );
}

export default App;
```

## API Reference

### DataFilter Props

| Prop | Type | Description |
|------|------|-------------|
| `columns` | `FilterColumnDef[]` | Array of filter column definitions |
| `filters` | `FiltersState` | Current filter state (controlled) |
| `onFiltersChange` | `(filters: FiltersState) => void` | Callback when filters change |

### FilterColumnDef

Base properties for all filter types:

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `'text' \| 'number' \| 'date' \| 'option' \| 'multiOption'` | ✅ | Filter type |
| `columnId` | `string` | ✅ | Unique identifier for the filter |
| `displayName` | `string` | ✅ | Display name for the filter |
| `icon` | `React.ReactNode` | ❌ | Optional |

### Number/Date Filter Additional Props

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `mode` | `'single' \| 'range'` | ✅ | Single value or range selection |
| `min` | `number` | ❌ | Minimum value (number only) |
| `max` | `number` | ❌ | Maximum value (number only) |
| `showTime` | `boolean` | ❌ | Show time picker (date only) |

### Option Filter Additional Props

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `options` | `FilterColumnOption[]` | ✅ | Array of selectable options |

### FilterColumnOption

| Property | Type | Description |
|----------|------|-------------|
| `label` | `string` | Display label |
| `value` | `string` | Option value |
| `icon` | `React.ReactNode` | Optional icon or visual indicator |

### FiltersState

Array of active filter values:

```tsx
type FiltersState = Array<{
  columnId: string;
  type: 'text' | 'number' | 'date' | 'option' | 'multiOption';
  values: any[];
}>;
```

## License

MIT