npm package: @smg-automotive/filters
Description: Shared filter hooks, types and utilities
Author: SMG Automotive
Latest version: 1.6.0

# filters-pkg

## Installation

```bash
npm install @smg-automotive/filters
```

## Environment variables

| Variable | Used by                                          | Required | Description |
|----------|--------------------------------------------------|----------|-------------|
| `API_ROOT` | `fetchSearchConfiguration`, `fetchReferenceData` | Yes (for search config) | Base URL of the search-configuration API. |
| `API_VERSION` | `fetchSearchConfiguration`, `fetchReferenceData` | Yes (for search config) | API version segment (e.g. `v1`). |

## Reference data

### Search configuration

Range filters (e.g. mileage, price) use slider scales and optional histogram data from the search-configuration API. Fetch it during your build and pass the result into `FilterProvider` as `histogramRanges`.

Use the package’s **`fetchSearchConfiguration`** utility so the app doesn’t need to implement the API call or response transform. It uses **`process.env.API_ROOT`** and **`process.env.API_VERSION`**

### Filter options

| Option | Type | Source | Description |
|--------|------|--------|-------------|
| `referenceData` | `ReferenceData` | `fetchReferenceData()` or build-time JSON | Per–vehicle-category reference data (fuel types, body types, etc.) for checkbox filters. |

Use **`fetchReferenceData`** to load reference data; it calls the reference-data API for each vehicle category (car, utility, motorcycle, truck, trailer, camper) and uses `process.env.API_ROOT` and `process.env.API_VERSION`. For build-time prefetch, call it during your build and write the result to JSON, then import and pass it into `FilterProvider`.

## i18n setup (translations)

The package does not load or bundle translations. Your app uses `@smg-automotive/i18n-pkg` and passes the `t` function from `useI18n()` into `FilterProvider`. All filter-related keys live under the **`filtersPkg`** namespace.

**Import the package translation files into your project dictionary** so the `filtersPkg` namespace is available. Merge each locale’s object under a `filtersPkg` key in the dictionary you pass to `I18nProvider`. Then `t('filtersPkg.mileage')`, `t('filtersPkg.from')`, etc. will resolve.

Use the **`/translations` subpath** so that React and client-only code are not loaded (e.g. in server components or RSC):

```ts
import {
  filterTranslationsDe,
  filterTranslationsEn,
  filterTranslationsFr,
  filterTranslationsIt,
} from '@smg-automotive/filters/translations';

// Merge into your existing locale dictionaries, e.g.:
// dictionary.de.filtersPkg = filterTranslationsDe;
// dictionary.en.filtersPkg = filterTranslationsEn;
// ...
```

If you are not in a server/RSC context, you can instead import from the main entry: `import { filterTranslations } from '@smg-automotive/filters'`.

## FilterProvider

**Wrap your filter tree with `FilterProvider`** and pass `t`, `brand`, `histogramRanges`, `referenceData`, and `language`. Do this inside a component that is already under `I18nProvider`. Pass the result of `fetchSearchConfiguration` (or the JSON you wrote at build time) as `histogramRanges`. Pass your app’s reference data (e.g. from prefetched data) as `referenceData` so checkbox filters (e.g. fuel type) can read options per vehicle category. Pass the current locale as `language` (e.g. from `useI18n().language`).

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `t` | `TFunction` | Yes | Translation function from `useI18n()` (or equivalent). |
| `brand` | `Brand` | Yes | Current brand (e.g. `AutoScout24`, `MotoScout24`). |
| `histogramRanges` | `HistogramRanges` | Yes | Search configuration for range filters; from `fetchSearchConfiguration` or build-time JSON. |
| `referenceData` | `ReferenceData` | Yes | Per–vehicle-category reference data (fuel types, body types, etc.). Used by checkbox filters. |
| `language` | `Language` | Yes | Current UI language (`'de'`, `'en'`, `'fr'`, or `'it'`). Used for sorting and display. |

```tsx
import { useI18n } from 'shared/utilities/i18nInit';
import { useDataDrivenAppRendering } from 'shared/contexts/dataDrivenRendering/App';
import { FilterProvider } from '@smg-automotive/filters';
// e.g. from files written at build time:
import { searchConfiguration as histogramRanges } from 'prefetchedData';
import { referenceData } from 'prefetchedData';

function FilterLayout() {
  const { t, language } = useI18n();
  const { brand } = useDataDrivenAppRendering();
  return (
    <FilterProvider
      t={t}
      brand={brand}
      histogramRanges={histogramRanges}
      referenceData={referenceData}
      language={language}
    >
      <YourFilterUI />
    </FilterProvider>
  );
}
```

## Development
```
npm run build
```

You can link your local npm package to integrate it with any local project:
```
cd filters-pkg
npm run build

cd <project directory>
npm link ../filters-pkg
```

## Release a new version

New versions are released on the ci using semantic-release as soon as you merge into master. Please
make sure your merge commit message adheres to the corresponding [conventions](https://www.conventionalcommits.org/en/v1.0.0/) and your branch name does not contain forward slashes `/`.