llms.txt

# react-native-quick-filter

> Reusable quick-filter flow for React Native & Expo: a horizontal chip/pill bar,
> chip-anchored dropdowns, and a slide-in filter panel with three presentations
> (drilldown, master-detail, sheet). Headless core (hooks) + themed UI. Sort,
> faceted counts, live result counter, i18n (EN default, TR included), light/dark
> theme, instant vs deferred apply, controlled/uncontrolled selection.
> JS-only (no native module) — works in Expo Go and dev builds.

This file is a condensed, machine-readable map for LLM coding tools. For prose
docs see README.md, docs/USAGE.md, docs/API.md, docs/CONSUMING.md.

## Install

```
npm install react-native-quick-filter
npx expo install react-native-reanimated react-native-gesture-handler react-native-safe-area-context
```

Peer deps: react >=18, react-native >=0.74, react-native-reanimated >=3.6 (v3/v4),
react-native-gesture-handler >=2.14, react-native-safe-area-context >=4.8.

App root MUST be wrapped once:
```tsx
<GestureHandlerRootView style={{ flex: 1 }}>
  <SafeAreaProvider>{/* app */}</SafeAreaProvider>
</GestureHandlerRootView>
```
Babel: reanimated plugin last (`react-native-reanimated/plugin`; v4 `react-native-worklets/plugin`).
Expo adds it automatically via babel-preset-expo.

## Data model (types)

```ts
type FacetKind = 'single' | 'multi' | 'range' | 'toggle';
type Presentation = 'dropdown' | 'sidePanel';
type ApplyMode = 'instant' | 'deferred';

interface FacetOption { id: string; label: string; count?: number } // count = faceted count
interface Facet {
  id: string; label: string; kind: FacetKind;
  options?: FacetOption[]; searchable?: boolean; selectAll?: boolean; columns?: 1 | 2;
  min?: number; max?: number; step?: number;
  presets?: { id: string; label: string; min?: number; max?: number }[]; slider?: boolean;
  presentation?: Presentation; applyMode?: ApplyMode;
}

type ChipKind = 'action' | 'dropdown' | 'toggle' | 'segment';
interface ChipSpec {
  facetId: string; kind: ChipKind; label?: string; leadingIcon?: React.ReactNode;
  badge?: 'activeCount' | 'facetCount' | 'none'; removable?: boolean;
  pinActiveFirst?: boolean; opens?: 'dropdown' | 'sidePanel';
}

interface RangeValue { min?: number; max?: number }
interface Selection { options: Record<string, string[]>; ranges: Record<string, RangeValue> }
// emptySelection() returns { options: {}, ranges: {} }
```

- The `filter` chip id is a convention for the action chip that opens the detailed panel/sheet (`kind: 'action', opens: 'sidePanel'`).
- `Selection` is the single source of truth. `options[facetId]` = selected option ids; `ranges[facetId]` = {min,max}.

## Provider

```tsx
<FilterProvider
  facets={Facet[]}
  chips={ChipSpec[]}
  selection?={Selection}            // controlled
  defaultSelection?={Selection}     // uncontrolled
  onSelectionChange?={(next: Selection) => void}   // fires on every commit
  resolveResultCount?={(sel: Selection) => number | Promise<number>}
  applyMode?={'instant' | 'deferred'}
  resultCountDebounceMs?={number}   // default 250
>
  {children}
</FilterProvider>
```

## Components

- `QuickFilterBar` — horizontal scrollable chip bar. Props: `pinActiveFirst?`, `renderChip?`.
- `FilterDropdown` — chip-anchored dropdown for `kind:'dropdown'` chips. Props: `topOffset?`.
- `FilterSidePanel` — slide-in panel. Props:
  - `variant?: 'drilldown' | 'masterDetail'` (default drilldown)
  - `side?: 'left' | 'right'`
  - `animated?: boolean` (default true; false = no slide, for masterDetail)
  - `groups?: string[]` (facet ids to include), `title?`, `footer?`, `swipeToClose?`
- `FilterSheet` — collapsible sections popping over the page. Props:
  - `presentation?: 'sheet' | 'fullScreen'` (default 'sheet')
  - `sectionMaxHeight?: number` (default 280; long sections scroll independently)
- Bodies (shared by dropdown/panel/sheet): `FacetBody` (router), `CheckboxListBody`, `RadioListBody`, `RangeBody`.
- Atoms: `ResultCountButton`, `FilterFooter`, `Button`, `Checkbox`, `Radio`, `Badge`, `SearchInput`, `Chevron`.

## Hooks (headless)

- `useFilter()` → `{ selection, activeCount, clearAll, ... }`
- `useFacet(facetId)` → `{ optionValue, toggleOption, selectAll, clearFacet, visibleOptions, searchQuery, setSearchQuery, commit, ... }`
- `useResultCount()` → live count from `resolveResultCount`
- `useDropdown()`, `usePanel()`, `useChip(chipSpec)`

## Theme & i18n

- `ThemeProvider scheme="light"|"dark" override={{ colors: { accent } }}` — defaults: light + EN when absent.
- `useTheme()`, `defaultLightTheme`, `defaultDarkTheme`, `mergeTheme(base, override)`.
- `StringsProvider strings={Partial<QuickFilterStrings>}`, `useStrings()`, dictionaries `en` (default) and `tr`, `formatNumber`.

## Three detailed-filter presentations (all share one state)

```tsx
<FilterSidePanel variant="drilldown" side="right" />                    // Trendyol
<FilterSidePanel variant="masterDetail" side="left" animated={false} /> // Amazon
<FilterSheet presentation="sheet" sectionMaxHeight={280} />             // MediaMarkt
```

## Minimal working example

```tsx
import { useState } from 'react';
import {
  FilterProvider, QuickFilterBar, FilterDropdown, FilterSidePanel,
  type Facet, type ChipSpec, type Selection,
} from 'react-native-quick-filter';

const facets: Facet[] = [
  { id: 'sort', label: 'Sort', kind: 'single', options: [
    { id: 'recommended', label: 'Recommended' }, { id: 'priceAsc', label: 'Price: Low to High' } ] },
  { id: 'brand', label: 'Brand', kind: 'multi', searchable: true, columns: 2,
    options: [{ id: 'nike', label: 'Nike' }, { id: 'adidas', label: 'Adidas' }] },
  { id: 'price', label: 'Price', kind: 'range', min: 0, max: 5000,
    presets: [{ id: 'p1', label: '$0 – $300', min: 0, max: 300 }] },
];
const chips: ChipSpec[] = [
  { facetId: 'filter', kind: 'action', label: 'Filter', opens: 'sidePanel' },
  { facetId: 'sort', kind: 'dropdown', label: 'Sort' },
  { facetId: 'brand', kind: 'dropdown' },
  { facetId: 'price', kind: 'dropdown' },
];

function Screen() {
  const [selection, setSelection] = useState<Selection>();
  return (
    <FilterProvider facets={facets} chips={chips} onSelectionChange={setSelection}
      resolveResultCount={(sel) => fetchCount(sel)}>
      <QuickFilterBar />
      <FilterDropdown />
      <FilterSidePanel variant="masterDetail" side="left" />
    </FilterProvider>
  );
}
```

## Gotchas for code generation

- Always render exactly ONE detailed presentation (`FilterSidePanel` OR `FilterSheet`); the `filter` action chip opens whichever is mounted.
- `FilterDropdown` must be mounted once for `kind:'dropdown'` chips to open.
- Provider does not render a list — you render your own results using `selection`.
- Toggle facets apply instantly; dropdown/panel/sheet use deferred draft→commit by default.
- Import types with `import type { ... }`. All public types are exported from the package root.
```