@pol-studios/filters

Filter components and utilities for POL applications

A comprehensive filtering system with support for advanced queries, sorting, searching, saved queries, and real-time notifications.

Installation

pnpm add @pol-studios/filters

Peer Dependencies

pnpm add react react-dom @pol-studios/utils @pol-studios/hooks @pol-studios/features @pol-studios/ui @pol-studios/db

Quick Start

import { FilterBuilder, AutoFilterBuilder, useFilterBuilderContext } from "@pol-studios/filters";

// Basic FilterBuilder usage
function MyFilters() {
  return (
    <FilterBuilder
      initQuery={[{ field: "status", operator: "eq", value: "active" }]}
      onQueryChange={(query) => console.log("Query changed:", query)}
    />
  );
}

// Schema-aware AutoFilterBuilder
function SchemaBasedFilters() {
  return (
    <SchemaProvider schema={myDatabaseSchema}>
      <AutoFilterBuilder
        config={filterConfig}
        onFilterChange={handleFilterChange}
      />
    </SchemaProvider>
  );
}

Subpath Exports

| Path | Description | |------|-------------| | @pol-studios/filters | All exports (components, hooks, utils, state) | | @pol-studios/filters/components | FilterBuilder, AutoFilterBuilder, FilterContainer, MobileFilterDrawer | | @pol-studios/filters/state | FilterContext, useFilterBuilderContext | | @pol-studios/filters/saved | SavedQueryManager, QuerySharingModal | | @pol-studios/filters/selectors | ComparatorSelect, OperatorSelect, OptionSelect | | @pol-studios/filters/advanced | AdvancedLayer, AdvancedFilter, FilterChip | | @pol-studios/filters/preview | FilterPreview, RenderFilters | | @pol-studios/filters/sorting | SortByManager | | @pol-studios/filters/searching | SearchFilter | | @pol-studios/filters/notifications | FilterNotificationHandler | | @pol-studios/filters/utils | generateFilterOptionsFromConfig, filterStyles, filterLayerToInitQuery | | @pol-studios/filters/hooks | useFilterBuilderInitQuery, getSearchParams |

API Reference

Components

FilterBuilder

Main filter builder component for creating dynamic filter queries.

import { FilterBuilder } from "@pol-studios/filters/components";

<FilterBuilder
  initQuery={initialQuery}
  onQueryChange={handleQueryChange}
/>

AutoFilterBuilder

Schema-aware filter builder that auto-generates filter options from database schema.

import { AutoFilterBuilder, SchemaProvider } from "@pol-studios/filters/components";

<SchemaProvider schema={databaseSchema}>
  <AutoFilterBuilder config={autoFilterConfig} />
</SchemaProvider>

MobileFilterDrawer

Mobile-optimized filter drawer component.

import { MobileFilterDrawer } from "@pol-studios/filters/components";

<MobileFilterDrawer
  isOpen={isOpen}
  onClose={handleClose}
>
  <FilterBuilder {...filterProps} />
</MobileFilterDrawer>

Sorting & Searching

SortByManager

Manage sorting options for filtered data.

import { SortByManager } from "@pol-studios/filters/sorting";

<SortByManager
  sortOptions={[
    { field: "name", label: "Name" },
    { field: "createdAt", label: "Date Created" }
  ]}
  onSortChange={handleSortChange}
/>

SearchFilter

Full-text search component.

import { SearchFilter } from "@pol-studios/filters/searching";

<SearchFilter
  placeholder="Search..."
  onSearch={handleSearch}
/>

Saved Queries

SavedQueryManager

Save and manage filter query presets.

import { SavedQueryManager } from "@pol-studios/filters/saved";

<SavedQueryManager
  queries={savedQueries}
  onSelect={handleSelectQuery}
  onSave={handleSaveQuery}
/>

Advanced Filters

AdvancedFilter

Complex filter UI with nested groups and conditions.

import { AdvancedFilter, FilterChip } from "@pol-studios/filters/advanced";

<AdvancedFilter
  groups={filterGroups}
  onGroupChange={handleGroupChange}
/>

Hooks

useFilterBuilderInitQuery

Initialize filter state from URL parameters.

import { useFilterBuilderInitQuery, getSearchParams } from "@pol-studios/filters/hooks";

const { initQuery, setQuery } = useFilterBuilderInitQuery();
const params = getSearchParams(window.location.search);

Utils

generateFilterOptionsFromConfig

Generate filter options from configuration.

import { generateFilterOptionsFromConfig } from "@pol-studios/filters/utils";

const filterOptions = generateFilterOptionsFromConfig(config, schema);

TypeScript Types

import type {
  // Query types
  Query,
  QueryGroup,
  InitQuery,
  Group,

  // Schema types
  AutoFilterConfig,
  DatabaseSchema,
  SchemaColumn,
  SchemaTable,
  SchemaRelationship,
  TableReference,
  NestedRelationshipConfig,

  // Component props
  FilterBuilderProps,
  FilterOptionProps,
  MobileFilterDrawerProps,
  FilterStateView,
  FilterContextValue,
} from "@pol-studios/filters";

Related Packages

• @pol-studios/hooks - Custom React hooks
• @pol-studios/ui - UI components
• @pol-studios/db - Database utilities
• @pol-studios/features - Feature modules

License

UNLICENSED