# CSV Formatter & Mapper — Full Technical Context & Documentation

## Overview
CSV Formatter & Mapper is a high-performance client-side Single Page Application (SPA) designed to solve column mapping, schema synchronization, and data normalization bottlenecks when moving tabular data between heterogeneous systems.

## Key Architectural Principles
1. **Zero Server Footprint (100% Client-Side Privacy)**:
   - CSV parsing is performed entirely inside the user's browser using PapaParse.
   - All transformations, auto-increment sequences, and regular expressions run inside local memory.
   - User mapping presets and preferences are stored exclusively in the browser's `localStorage`.
   - No rows, tokens, or PII (Personally Identifiable Information) ever leave the client.

2. **Technology Stack**:
   - Frontend Framework: React 19 (Functional Components, Custom Hooks).
   - Bundler: Vite 8.
   - Internationalization: `i18next` and `react-i18next` supporting 35 languages (with RTL support).
   - CSV Parsing & Serialization: `papaparse`.
   - Icons: `lucide-react`.
   - Typography: Plus Jakarta Sans & JetBrains Mono.

## Supported Transformation Rules & Schema
Each destination column slot in the target schema adheres to the following JSON structure:

### 1. `mapped` Rule
Maps a source column directly into a destination column with optional transformation and fallback:
```json
{
  "type": "mapped",
  "sourceColumn": "fiyat_kdvli",
  "transform": "normalize_decimal",
  "fallback": "0.00"
}
```
Available Transforms:
- `none`: Preserves raw value.
- `trim`: Strips leading and trailing whitespace.
- `uppercase`: Converts all characters to uppercase.
- `lowercase`: Converts all characters to lowercase.
- `capitalize`: Capitalizes first letter of each word.
- `normalize_decimal`: Converts European/Turkish formatted currency/floats (`1.250,50` ➔ `1250.50`).
- `round_2`: Rounds numerical values to 2 decimal places (`99.9` ➔ `99.90`).
- `clean_barcode`: Strips non-digit characters, preserving pure numeric barcode/GTIN strings.

### 2. `auto_increment` Rule
Generates sequence numbers for rows, ideal for systems requiring primary keys or incremental codes:
```json
{
  "type": "auto_increment",
  "startFrom": 54,
  "step": 1,
  "prefix": "OTS-",
  "suffix": "",
  "padZero": 4
}
```
Output progression for rows: `"OTS-0054"`, `"OTS-0055"`, `"OTS-0056"`, ...

### 3. `concat` Rule
Combines multiple source columns into a single target column using a specified separator:
```json
{
  "type": "concat",
  "sourceColumns": ["MusteriAdi", "MusteriSoyadi"],
  "separator": " "
}
```
Example Output: `"Ahmet Yılmaz"`.

### 4. `static` Rule
Assigns a constant value across every row in the dataset:
```json
{
  "type": "static",
  "value": "Aktif"
}
```

## Export & Delimiter Handling
- **Excel UTF-8 BOM**: Adds `\uFEFF` byte order mark at the start of the serialized CSV string, guaranteeing that non-ASCII and special characters (Turkish `ç, ğ, ı, ö, ş, ü`, Arabic, Cyrillic, Greek, Asian scripts) render without encoding mojibake in Microsoft Excel.
- **Delimiters Supported**:
  - Semicolon (`;`) — Default standard for Excel in Turkish, German, and European locales.
  - Comma (`,`) — Standard for US/international platforms and RFC 4180.
  - Tab (`\t`) — TSV format.
  - Pipe (`|`) — Database dump format.

## Supported Languages (35 Locales)
- **LTR Locales**: `tr` (Türkçe), `en` (English), `de` (Deutsch), `fr` (Français), `es` (Español), `it` (Italiano), `ro` (Română), `bg` (Български), `cs` (Čeština), `hu` (Magyar), `uk` (Українська), `da` (Dansk), `no` (Norsk), `fi` (Suomi), `ru` (Русский), `el` (Ελληνικά), `zh` (中文), `ja` (日本語), `ko` (한국어), `th` (ไทย), `vi` (Tiếng Việt), `id` (Bahasa Indonesia), `ms` (Bahasa Melayu), `tl` (Tagalog), `hi` (हिन्दी), `bn` (বাংলা), `pt` (Português), `nl` (Nederlands), `pl` (Polski), `sv` (Svenska), `sw` (Kiswahili).
- **RTL Locales**: `ar` (العربية), `he` (עברית), `ur` (اردو), `fa` (فارسی).

## Preset Management
Presets are serialized as JSON objects containing:
- `id`: Unique identifier (UUID).
- `name`: User-defined template name.
- `description`: Optional description.
- `isSystem`: Boolean flag identifying built-in templates (e.g. OTS Standart Ürün Şablonu, OTS Cari/Müşteri Şablonu).
- `columns`: Array of target column definitions and their rule trees.
- `createdAt` / `updatedAt`: ISO 8601 timestamps.
Users can back up all presets to a `.json` file and restore them on any computer.