# DijitalMask

Türkiye kurumsal standartlarına ve yerel yasal kurallara tam uyumlu, sıfır bağımlılıklı akıllı girdi maskeleme ve doğrulama kütüphanesi.  
Vanilla JS & CSS (~22 KB minified JS, ~4.5 KB minified CSS).

---

## 🎯 Neden DijitalMask?

Türkiye'deki formlarda sıklıkla kullanılan TCKN, VKN, IBAN ve Para formatları için standart uluslararası maskeleme kütüphaneleri (IMask, Cleave.js) yetersiz kalmaktadır:
- **TCKN Algoritması & '0' Engeli:** Yalnızca 11 haneyle sınırlamak yetmez; T.C. Kimlik Numarası asla `0` ile başlayamaz. İlk hanede sıfır girilmesini engeller, 10. ve 11. hanelerin resmi matematiksel Luhn varyantı denetimini anlık gerçekleştirir.
- **20+ Türk Bankası & IBAN Tespiti:** 26 haneli TR IBAN'ının ilk 5 hanesindeki banka kodundan kamu (Ziraat, Halk, Vakıf), özel (İş, Garanti, Akbank, Yapı Kredi), katılım (Kuveyt Türk, Albaraka, Emlak Katılım) ve yeni nesil dijital/fintek (Enpara, Papara, Hayat Finans, TOM Bank) bankalarını logolu ve kurumsal renkli rozetleriyle anında tanır.
- **VKN (Vergi Kimlik No):** 10 haneli tüzel kişi vergi numaralarını resmi Gelir İdaresi Başkanlığı (GİB) algoritmasıyla doğrular ve okunabilir format sunar.
- **Canlı Kuruş & Para Formatı:** Kullanıcı yazdıkça binlik basamakları (`.`) dinamik yerleştirir; virgül (`,`) tuşlandığında kuruş hanesine geçer. Backend veya veritabanına gönderilmek üzere saf ondalık sayı (`1250000.50`) sunar.
- **Telefon & Kurumsal Hatlar:** Cep telefonları (`+90 5XX`), kurumsal çağrı merkezleri (`444`), 0850 ve sabit hatları (`0212`) akıllıca ayrıştırır.
- **Form & HTMX / SSR Senkronizasyonu:** `data-mask-sync-hidden="true"` ile form submit edildiğinde maskelenmiş metin yerine saf ham veriyi otomatik arka planda taşır.

---

## 🚀 Temel Yetenekler

- **Sıfır Dış Bağımlılık (Zero-Dependency)** — Saf Vanilla ES6+ motoru.
- **Otomatik HTML5 Başlatma** — Sadece `data-mask="..."` özniteliğiyle zahmetsiz kurulum.
- **Resmi Algoritmik Doğrulama:**
  - TCKN Luhn Algoritması (İlk hane sıfır koruması)
  - VKN (Gelir İdaresi Başkanlığı) Algoritması
  - IBAN Mod-97 ISO 13616 Doğrulaması
  - Kredi Kartı Luhn Kontrolü (Troy, Visa, Mastercard, Amex tespiti)
  - 01-81 İl Kodu Araç Plaka Kontrolü
- **Canlı Geri Bildirim (`dm-feedback`):** İnput altında anlık geçerli/geçersiz doğrulama mesajları.
- **Akıllı Backspace / İmleç Koruması:** Format karakterleri (boşluk, parantez) silinirken imlecin takılmasını önleyen klavye motoru.
- **Minimalist Zinc Teması:** Açık ve Koyu tema uyumlu kurumsal tasarım.

---

## 📦 Kurulum

### CDN

```html
<!-- CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/dijital-mask/dist/dijital-mask.min.css">

<!-- JS -->
<script src="https://cdn.jsdelivr.net/npm/dijital-mask/dist/dijital-mask.min.js"></script>
```

### NPM

```bash
npm install dijital-mask
```

---

## 💡 Kullanım

### 1. Otomatik HTML Nitelikleri (`data-mask`)

```html
<!-- T.C. Kimlik No (Feedback ile) -->
<input type="text" data-mask="tckn" data-mask-feedback="true" placeholder="000 000 000 00">

<!-- IBAN (Banka tespiti ve feedback ile) -->
<input type="text" data-mask="iban" data-mask-feedback="true" placeholder="TR00 0000 0000 0000 0000 0000 00">

<!-- Vergi Kimlik No (GİB Algoritması) -->
<input type="text" data-mask="vkn" data-mask-feedback="true" placeholder="000 000 00 00">

<!-- Para / Döviz (Canlı Binlik & Kuruş) -->
<input type="text" data-mask="currency" data-mask-currency="TRY" placeholder="0,00 ₺">

<!-- Telefon (+90 / 0850 / 444 / Sabit Hat) -->
<input type="text" data-mask="phone" data-mask-phone-format="+90">

<!-- Araç Plaka -->
<input type="text" data-mask="plate" placeholder="34 ABC 123">

<!-- Kredi Kartı (Troy / Visa / MC) -->
<input type="text" data-mask="card" placeholder="0000 0000 0000 0000">

<!-- Özel Şablon -->
<input type="text" data-mask="custom" data-mask-pattern="TR-0000-AA">
```

### 2. Form & HTMX Entegrasyonu (`syncHiddenInput`)

Form submit edildiğinde Django, Laravel, Spring veya HTMX backend'inize maskelenmiş metin (`1.250.000,50 ₺`) yerine saf verinin (`1250000.50`) gitmesini sağlamak için:

```html
<form action="/api/odeme" method="POST">
  <!-- Ekranda maskeli görünür, submit olunca name="tckn" ile saf '10000000146' gider -->
  <input type="text" 
         name="tckn_display" 
         data-mask="tckn" 
         data-mask-sync-hidden="true" 
         data-mask-raw-name="tckn">

  <!-- Submit olunca name="tutar" ile saf '1250000.50' gider -->
  <input type="text" 
         name="tutar_display" 
         data-mask="currency" 
         data-mask-sync-hidden="true" 
         data-mask-raw-name="tutar">

  <button type="submit">Ödeme Yap</button>
</form>
```

### 3. JavaScript / Programatik API

```javascript
import DijitalMask from 'dijital-mask';

const inputEl = document.querySelector('#myInput');

// Maskeyi bağla
const mask = new DijitalMask(inputEl, {
  mask: 'tckn',
  showFeedback: true,
  autoValidate: true,
  onValid: (detail) => {
    console.log('Geçerli TCKN:', detail.value);
  },
  onInvalid: (detail) => {
    console.warn('Geçersiz TCKN:', detail.value);
  }
});

// Ham (raw) değeri al (örn: '12345678901' veya currency için 1250000.50)
console.log(mask.getRawValue());

// Biçimlendirilmiş değeri al
console.log(mask.getValue());

// Geçerlilik kontrolü
console.log(mask.isValid()); // true / false

// Programatik değer atama
mask.setValue('10000000146');
```

---

## ⚡ Canlı Olaylar (Custom Events)

Tüm maskelenen inputlar standart Custom Event'leri fırlatır:

| Olay Adı | Tetiklenme Anı | `e.detail` İçeriği |
| :--- | :--- | :--- |
| `dm:change` | Değer her değiştiğinde | `{ value, rawValue, isValid, mask, bank, card, detail }` |
| `dm:valid` | Giriş matematiksel algoritmadan başarıyla geçtiğinde | `{ value, rawValue, isValid, detail }` |
| `dm:invalid` | Tamamlanan giriş algoritmaya uymadığında | `{ value, rawValue, isValid, detail }` |

```javascript
document.addEventListener('dm:valid', (e) => {
  if (e.detail.mask === 'iban') {
    console.log('Tespit Edilen Banka:', e.detail.bank?.name);
  }
});
```

---

## 📄 Lisans

MIT © DijitalUI Team